From fcfd5f7adc89e5b55a093e264c18ecc59556b552 Mon Sep 17 00:00:00 2001 From: Merlin's Cat Date: Thu, 28 May 2026 14:39:21 +1000 Subject: [PATCH] feat: add Truthmark Portal workflow surfaces (#8) * fix: harden workflow helper manifests and reports * docs: add helper script portability design * fix: reject failed helper statuses in completed reports * fix: align helper report sections metadata * fix: preserve sync helper statuses in parser * test: harden helper validator negatives * feat: add Copilot and Gemini Truthmark surfaces - generate Copilot and Gemini workflow skill packages with helper manifests - add Gemini subagent surfaces and validate helper CLI plumbing - update README/docs for helper-package support Verification: npm run check * docs: simplify README workflow surface overview Replace long generated file lists with conceptual layers and Mermaid architecture diagrams across localized READMEs. Verification: node dist/main.js check --json; npm run package:check * docs: show agent CLI feedback loop in README diagram Clarify that host-native agent workflows can call the installed Truthmark CLI for validation, indexing, and helper checks. Verification: node dist/main.js check --json; npm run package:check * fix: wrap validate JSON output in command envelope Return helper validation results under data.validation for --json output while preserving the existing human-readable validate output. Verification: npm run check; truthmark check/index JSON diagnostics. * fix: clarify helper validation status reporting Add explicit helper-status policy to Truth Sync and Truth Document surfaces so standalone Copilot prompts and Gemini commands only report ran/passed after the installed CLI validator succeeds. Update README and workflow docs to describe the shared installed-CLI validator contract instead of saying standalone surfaces mark helper packages unavailable. Verification: npm run check; npm run package:check; truthmark check/index JSON diagnostics. * fix: normalize helper status ids during validation Parse helper status entries with the same regex used for syntax validation and compare captured helper IDs against required helpers. Adds regressions for extra whitespace after helper bullets in Truth Sync and Truth Document reports. Verification: npm run check; npm run package:check; truthmark check/index JSON diagnostics. * fix: parse write lease YAML structurally * chore: bump version to 1.5.0 * docs: include validate in repo CLI boundary * fix: enforce workflow report validator contracts * fix: require manual review files in blocked sync reports * feat: add Truthmark Portal workflow surfaces - add Portal workflow guidance, config/defaults, and generated provider surfaces - cover Portal config path boundaries and generated surface contracts - clarify project-local policy docs are optional and config-driven --------- Co-authored-by: MerlinH --- .claude/agents/truth-claim-verifier.md | 2 +- .claude/agents/truth-doc-reviewer.md | 2 +- .claude/agents/truth-doc-writer.md | 2 +- .claude/agents/truth-route-auditor.md | 4 +- .claude/skills/truthmark-check/SKILL.md | 6 +- .../truthmark-check/support/procedure.md | 20 +- .../support/report-template.md | 4 +- .../support/subagents-and-leases.md | 2 +- .claude/skills/truthmark-document/SKILL.md | 6 +- .../truthmark-document/helper-manifest.yml | 6 +- .../support/helper-policy.md | 6 +- .../truthmark-document/support/procedure.md | 18 +- .../support/report-template.md | 2 +- .../support/subagents-and-leases.md | 2 +- .claude/skills/truthmark-preview/SKILL.md | 6 +- .../truthmark-preview/support/procedure.md | 20 +- .../support/report-template.md | 2 +- .../support/subagents-and-leases.md | 2 +- .claude/skills/truthmark-realize/SKILL.md | 6 +- .../truthmark-realize/support/procedure.md | 18 +- .../support/report-template.md | 2 +- .claude/skills/truthmark-structure/SKILL.md | 6 +- .../truthmark-structure/support/procedure.md | 20 +- .../support/report-template.md | 2 +- .../support/subagents-and-leases.md | 2 +- .claude/skills/truthmark-sync/SKILL.md | 6 +- .../skills/truthmark-sync/helper-manifest.yml | 6 +- .../truthmark-sync/support/helper-policy.md | 6 +- .../truthmark-sync/support/procedure.md | 18 +- .../truthmark-sync/support/report-template.md | 2 +- .../support/subagents-and-leases.md | 2 +- .codex/agents/truth-claim-verifier.toml | 2 +- .codex/agents/truth-doc-reviewer.toml | 2 +- .codex/agents/truth-doc-writer.toml | 2 +- .codex/agents/truth-route-auditor.toml | 4 +- .codex/skills/truthmark-check/SKILL.md | 6 +- .../skills/truthmark-check/agents/openai.yaml | 2 +- .../truthmark-check/support/procedure.md | 20 +- .../support/report-template.md | 4 +- .../support/subagents-and-leases.md | 2 +- .codex/skills/truthmark-document/SKILL.md | 6 +- .../truthmark-document/agents/openai.yaml | 2 +- .../truthmark-document/helper-manifest.yml | 6 +- .../support/helper-policy.md | 6 +- .../truthmark-document/support/procedure.md | 18 +- .../support/report-template.md | 2 +- .../support/subagents-and-leases.md | 2 +- .codex/skills/truthmark-preview/SKILL.md | 6 +- .../truthmark-preview/agents/openai.yaml | 2 +- .../truthmark-preview/support/procedure.md | 20 +- .../support/report-template.md | 2 +- .../support/subagents-and-leases.md | 2 +- .codex/skills/truthmark-realize/SKILL.md | 6 +- .../truthmark-realize/agents/openai.yaml | 2 +- .../truthmark-realize/support/procedure.md | 18 +- .../support/report-template.md | 2 +- .codex/skills/truthmark-structure/SKILL.md | 6 +- .../truthmark-structure/agents/openai.yaml | 2 +- .../truthmark-structure/support/procedure.md | 20 +- .../support/report-template.md | 2 +- .../support/subagents-and-leases.md | 2 +- .codex/skills/truthmark-sync/SKILL.md | 6 +- .../skills/truthmark-sync/agents/openai.yaml | 2 +- .../skills/truthmark-sync/helper-manifest.yml | 6 +- .../truthmark-sync/support/helper-policy.md | 6 +- .../truthmark-sync/support/procedure.md | 18 +- .../truthmark-sync/support/report-template.md | 2 +- .../support/subagents-and-leases.md | 2 +- .gemini/agents/truth-claim-verifier.md | 2 +- .gemini/agents/truth-doc-reviewer.md | 2 +- .gemini/agents/truth-doc-writer.md | 2 +- .gemini/agents/truth-route-auditor.md | 4 +- .gemini/commands/truthmark/check.toml | 22 +- .gemini/commands/truthmark/document.toml | 18 +- .gemini/commands/truthmark/preview.toml | 20 +- .gemini/commands/truthmark/realize.toml | 18 +- .gemini/commands/truthmark/structure.toml | 20 +- .gemini/commands/truthmark/sync.toml | 18 +- .gemini/skills/truthmark-check/SKILL.md | 6 +- .../truthmark-check/support/procedure.md | 20 +- .../support/report-template.md | 4 +- .../support/subagents-and-leases.md | 2 +- .gemini/skills/truthmark-document/SKILL.md | 6 +- .../truthmark-document/helper-manifest.yml | 6 +- .../support/helper-policy.md | 6 +- .../truthmark-document/support/procedure.md | 18 +- .../support/report-template.md | 2 +- .../support/subagents-and-leases.md | 2 +- .gemini/skills/truthmark-preview/SKILL.md | 6 +- .../truthmark-preview/support/procedure.md | 20 +- .../support/report-template.md | 2 +- .../support/subagents-and-leases.md | 2 +- .gemini/skills/truthmark-realize/SKILL.md | 6 +- .../truthmark-realize/support/procedure.md | 18 +- .../support/report-template.md | 2 +- .gemini/skills/truthmark-structure/SKILL.md | 6 +- .../truthmark-structure/support/procedure.md | 20 +- .../support/report-template.md | 2 +- .../support/subagents-and-leases.md | 2 +- .gemini/skills/truthmark-sync/SKILL.md | 6 +- .../skills/truthmark-sync/helper-manifest.yml | 6 +- .../truthmark-sync/support/helper-policy.md | 6 +- .../truthmark-sync/support/procedure.md | 18 +- .../truthmark-sync/support/report-template.md | 2 +- .../support/subagents-and-leases.md | 2 +- .github/agents/truth-claim-verifier.agent.md | 2 +- .github/agents/truth-doc-reviewer.agent.md | 2 +- .github/agents/truth-doc-writer.agent.md | 2 +- .github/agents/truth-route-auditor.agent.md | 4 +- .github/copilot-instructions.md | 12 +- .github/prompts/truthmark-check.prompt.md | 22 +- .github/prompts/truthmark-document.prompt.md | 18 +- .github/prompts/truthmark-preview.prompt.md | 20 +- .github/prompts/truthmark-realize.prompt.md | 18 +- .github/prompts/truthmark-structure.prompt.md | 20 +- .github/prompts/truthmark-sync.prompt.md | 18 +- .github/skills/truthmark-check/SKILL.md | 6 +- .../truthmark-check/support/procedure.md | 20 +- .../support/report-template.md | 4 +- .../support/subagents-and-leases.md | 2 +- .github/skills/truthmark-document/SKILL.md | 6 +- .../truthmark-document/helper-manifest.yml | 6 +- .../support/helper-policy.md | 6 +- .../truthmark-document/support/procedure.md | 18 +- .../support/report-template.md | 2 +- .../support/subagents-and-leases.md | 2 +- .github/skills/truthmark-preview/SKILL.md | 6 +- .../truthmark-preview/support/procedure.md | 20 +- .../support/report-template.md | 2 +- .../support/subagents-and-leases.md | 2 +- .github/skills/truthmark-realize/SKILL.md | 6 +- .../truthmark-realize/support/procedure.md | 18 +- .../support/report-template.md | 2 +- .github/skills/truthmark-structure/SKILL.md | 6 +- .../truthmark-structure/support/procedure.md | 20 +- .../support/report-template.md | 2 +- .../support/subagents-and-leases.md | 2 +- .github/skills/truthmark-sync/SKILL.md | 6 +- .../skills/truthmark-sync/helper-manifest.yml | 6 +- .../truthmark-sync/support/helper-policy.md | 6 +- .../truthmark-sync/support/procedure.md | 18 +- .../truthmark-sync/support/report-template.md | 2 +- .../support/subagents-and-leases.md | 2 +- .opencode/agents/truth-claim-verifier.md | 2 +- .opencode/agents/truth-doc-reviewer.md | 2 +- .opencode/agents/truth-doc-writer.md | 2 +- .opencode/agents/truth-route-auditor.md | 4 +- .opencode/skills/truthmark-check/SKILL.md | 6 +- .../truthmark-check/support/procedure.md | 20 +- .../support/report-template.md | 4 +- .../support/subagents-and-leases.md | 2 +- .opencode/skills/truthmark-document/SKILL.md | 6 +- .../truthmark-document/helper-manifest.yml | 6 +- .../support/helper-policy.md | 6 +- .../truthmark-document/support/procedure.md | 18 +- .../support/report-template.md | 2 +- .../support/subagents-and-leases.md | 2 +- .opencode/skills/truthmark-preview/SKILL.md | 6 +- .../truthmark-preview/support/procedure.md | 20 +- .../support/report-template.md | 2 +- .../support/subagents-and-leases.md | 2 +- .opencode/skills/truthmark-realize/SKILL.md | 6 +- .../truthmark-realize/support/procedure.md | 18 +- .../support/report-template.md | 2 +- .opencode/skills/truthmark-structure/SKILL.md | 6 +- .../truthmark-structure/support/procedure.md | 20 +- .../support/report-template.md | 2 +- .../support/subagents-and-leases.md | 2 +- .opencode/skills/truthmark-sync/SKILL.md | 6 +- .../skills/truthmark-sync/helper-manifest.yml | 6 +- .../truthmark-sync/support/helper-policy.md | 6 +- .../truthmark-sync/support/procedure.md | 18 +- .../truthmark-sync/support/report-template.md | 2 +- .../support/subagents-and-leases.md | 2 +- AGENTS.md | 12 +- CLAUDE.md | 12 +- GEMINI.md | 12 +- README.md | 50 +- changes/2026-05-25-version-160.md | 28 + docs/truth/contracts.md | 10 + docs/truth/init-and-scaffold.md | 8 +- docs/truth/workflows/overview.md | 4 + docs/truth/workflows/truthmark-portal.md | 81 ++ docs/truthmark/areas.md | 1 + .../truthmark/areas/contracts-and-commands.md | 1 + docs/truthmark/areas/installed-workflows.md | 2 + package-lock.json | 4 +- package.json | 2 +- ...-05-25-truthmark-portal-workflow-design.md | 821 ++++++++++++++++++ src/agents/instructions.ts | 10 +- src/agents/prompts.ts | 2 +- src/agents/shared.ts | 14 +- src/agents/truth-check.ts | 8 +- src/agents/truth-document.ts | 2 +- src/agents/truth-preview.ts | 6 +- src/agents/truth-structure.ts | 6 +- src/agents/truth-sync.ts | 4 +- src/agents/truthmark-portal.ts | 84 ++ src/agents/workflow-manifest.ts | 49 +- src/config/defaults.ts | 7 + src/config/load.ts | 118 +++ src/config/schema.ts | 34 +- src/init/init.ts | 77 +- src/templates/agents-block.ts | 13 +- src/templates/generated-surfaces.ts | 86 +- src/templates/workflow-surfaces.ts | 115 ++- tests/agents/instructions.test.ts | 8 +- tests/agents/prompts.test.ts | 2 +- tests/agents/truth-check.test.ts | 4 +- tests/agents/truth-document.test.ts | 2 +- tests/agents/truth-structure.test.ts | 4 +- tests/agents/truth-sync.test.ts | 8 +- tests/agents/workflow-manifest.test.ts | 41 +- tests/config/load.test.ts | 150 ++++ tests/evals/workflow-routing-cases.ts | 13 + tests/evals/workflow-routing.test.ts | 10 + tests/init/init.test.ts | 26 +- .../agent-workflow-contract.test.ts | 8 +- tests/templates/generated-surfaces.test.ts | 72 ++ 219 files changed, 2553 insertions(+), 774 deletions(-) create mode 100644 changes/2026-05-25-version-160.md create mode 100644 docs/truth/workflows/truthmark-portal.md create mode 100644 research/2026-05-25-truthmark-portal-workflow-design.md create mode 100644 src/agents/truthmark-portal.ts create mode 100644 tests/templates/generated-surfaces.test.ts diff --git a/.claude/agents/truth-claim-verifier.md b/.claude/agents/truth-claim-verifier.md index 13f8d4d..c9db522 100644 --- a/.claude/agents/truth-claim-verifier.md +++ b/.claude/agents/truth-claim-verifier.md @@ -4,7 +4,7 @@ description: Read-only Truthmark claim verifier for checking canonical truth aga tools: Read, Grep, Glob, LS --- -# Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +# Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Manual invocation: use the truth-claim-verifier subagent. diff --git a/.claude/agents/truth-doc-reviewer.md b/.claude/agents/truth-doc-reviewer.md index f14975a..efee480 100644 --- a/.claude/agents/truth-doc-reviewer.md +++ b/.claude/agents/truth-doc-reviewer.md @@ -4,7 +4,7 @@ description: Read-only Truthmark doc reviewer for shape, decision, rationale, an tools: Read, Grep, Glob, LS --- -# Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +# Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Manual invocation: use the truth-doc-reviewer subagent. diff --git a/.claude/agents/truth-doc-writer.md b/.claude/agents/truth-doc-writer.md index b940ee3..6ae42b5 100644 --- a/.claude/agents/truth-doc-writer.md +++ b/.claude/agents/truth-doc-writer.md @@ -4,7 +4,7 @@ description: Write-capable Truthmark doc worker for one parent-leased truth-docu tools: Read, Grep, Glob, LS, Edit, MultiEdit --- -# Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +# Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Manual invocation: use the truth-doc-writer subagent with an explicit parent write lease. diff --git a/.claude/agents/truth-route-auditor.md b/.claude/agents/truth-route-auditor.md index 1876894..7794209 100644 --- a/.claude/agents/truth-route-auditor.md +++ b/.claude/agents/truth-route-auditor.md @@ -4,13 +4,13 @@ description: Read-only Truthmark route auditor for bounded routing and ownership tools: Read, Grep, Glob, LS --- -# Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +# Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Manual invocation: use the truth-route-auditor subagent. Stay read-only. Audit one bounded Truthmark route, area, or doc shard assigned by the parent. -Read .truthmark/config.yml, the root route index, relevant child route files, mapped truth docs, and relevant implementation files directly. +Inspect .truthmark/config.yml and route files only when they exist; then inspect mapped truth docs and relevant implementation files directly. Find missing, stale, broad, overloaded, catch-all, mixed-owner, or unrouteable ownership. Do not edit files, stage changes, or propose broad rewrites. Return JSON only with keys: scope, filesReviewed, findings, evidence, confidence, recommendedWorkflow, notes. diff --git a/.claude/skills/truthmark-check/SKILL.md b/.claude/skills/truthmark-check/SKILL.md index 7364b22..a81e78f 100644 --- a/.claude/skills/truthmark-check/SKILL.md +++ b/.claude/skills/truthmark-check/SKILL.md @@ -3,7 +3,7 @@ name: truthmark-check description: Use when the user asks to audit repository truth health, routing, ownership, or canonical docs. Not for normal lint/test/typecheck/code-review verification, finish-time Sync, or silently rewriting docs. argument-hint: Optional area, doc path, or audit focus user-invocable: true -truthmark-version: 1.5.0 +truthmark-version: 1.6.0 --- # Truthmark Check @@ -14,8 +14,8 @@ Use this skill to audit repository truth health. Invocations: OpenCode /skill truthmark-check; Codex /truthmark-check or $truthmark-check; Claude Code /truthmark-check; GitHub Copilot /truthmark-check; Gemini CLI /truthmark:check. Quick procedure: -- Follow docs/ai/repo-rules.md as the repository instruction authority. -- Read .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, canonical docs, and relevant implementation directly. +- Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists. +- Inspect .truthmark/config.yml and configured route files (docs/truthmark/areas.md; docs/truthmark/areas/) only when they exist; then inspect canonical docs and relevant implementation directly. - Report issues and suggested fixes; do not silently rewrite unrelated files. - Direct checkout inspection is valid even when local tooling is unavailable. - Read support/procedure.md before auditing details. diff --git a/.claude/skills/truthmark-check/support/procedure.md b/.claude/skills/truthmark-check/support/procedure.md index 82239d8..33b7663 100644 --- a/.claude/skills/truthmark-check/support/procedure.md +++ b/.claude/skills/truthmark-check/support/procedure.md @@ -1,6 +1,6 @@ # Truthmark Check Procedure -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. # Truthmark Check @@ -10,12 +10,12 @@ Invocations: OpenCode /skill truthmark-check; Codex /truthmark-check or $truthma Truth Check is agent-led: -- inspect .truthmark/config.yml, docs/truthmark/areas.md, canonical docs, and relevant implementation directly -- Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +- inspect .truthmark/config.yml and configured route files only when they exist; then inspect canonical docs and relevant implementation directly +- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. -- inspect the configured root route index at docs/truthmark/areas.md and relevant child route files under docs/truthmark/areas/ +- inspect the configured root route index at docs/truthmark/areas.md and relevant child route files under docs/truthmark/areas/ when they exist - check that current docs describe current code rather than historical plans -- check that docs/truthmark/areas.md routes code surfaces to canonical truth docs +- check that route files map code surfaces to canonical truth docs when route files exist - check for broad, catch-all, index-like, or mixed-owner truth docs and report them as topology issues requiring Truth Structure - check that canonical behavior docs keep active Product Decisions and Rationale sections - optionally run truthmark check when local tooling is available @@ -27,11 +27,11 @@ Evidence Gate: - canonical docs are context, not sole proof when implementation conflicts - remove unsupported findings or mark open questions; validate changed claims if you edit docs -Truthmark hierarchy: -- Config: .truthmark/config.yml -- Root route index: docs/truthmark/areas.md -- Area route files: docs/truthmark/areas/**/*.md -- Truth docs: docs/truth/**/*.md +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. Update Product Decisions and Rationale when a decision changes behavior. diff --git a/.claude/skills/truthmark-check/support/report-template.md b/.claude/skills/truthmark-check/support/report-template.md index 1dc6319..e98269e 100644 --- a/.claude/skills/truthmark-check/support/report-template.md +++ b/.claude/skills/truthmark-check/support/report-template.md @@ -1,6 +1,6 @@ # Truthmark Check Report Template -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Report completion in this shape: @@ -18,7 +18,7 @@ Fixes suggested: Evidence checked: - Finding: The root route index is present and maps repository truth owners. - Evidence: .truthmark/config.yml:1 / docs/truthmark/areas.md:1 + Evidence: docs/truthmark/areas.md:1 Suggested fix: none Confidence: high diff --git a/.claude/skills/truthmark-check/support/subagents-and-leases.md b/.claude/skills/truthmark-check/support/subagents-and-leases.md index 27edd42..1439a59 100644 --- a/.claude/skills/truthmark-check/support/subagents-and-leases.md +++ b/.claude/skills/truthmark-check/support/subagents-and-leases.md @@ -1,6 +1,6 @@ # Truthmark Check Subagents And Leases -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Claude Code subagent mode: - use automatically when this workflow runs in Claude Code and the parent agent chooses bounded subagent fan-out diff --git a/.claude/skills/truthmark-document/SKILL.md b/.claude/skills/truthmark-document/SKILL.md index bd9ca15..751caa5 100644 --- a/.claude/skills/truthmark-document/SKILL.md +++ b/.claude/skills/truthmark-document/SKILL.md @@ -3,7 +3,7 @@ name: truthmark-document description: Use when the user asks to document existing implemented behavior, or Sync, Check, or Structure finds implemented behavior missing canonical truth. Not for functional-code changes, doc-first implementation, or topology repair that needs Structure. argument-hint: Optional implemented behavior, API endpoint, route, controller, package, or truth-doc area to document user-invocable: true -truthmark-version: 1.5.0 +truthmark-version: 1.6.0 --- # Truthmark Document @@ -14,8 +14,8 @@ Use this skill to document existing implemented behavior when no functional-code Invocations: OpenCode /skill truthmark-document; Codex /truthmark-document or $truthmark-document; Claude Code /truthmark-document; GitHub Copilot /truthmark-document; Gemini CLI /truthmark:document. Quick procedure: -- Follow docs/ai/repo-rules.md as the repository instruction authority. -- Read .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, existing canonical docs, implementation code, and tests directly. +- Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists. +- Inspect .truthmark/config.yml and configured route files (docs/truthmark/areas.md; docs/truthmark/areas/) only when they exist; then inspect existing canonical docs, implementation code, and tests directly. - Document current implemented behavior; do not invent future behavior. - May write canonical truth docs and truth routing files only; must not write functional code. - Read support/procedure.md before editing truth docs. diff --git a/.claude/skills/truthmark-document/helper-manifest.yml b/.claude/skills/truthmark-document/helper-manifest.yml index e53fa02..dc05fe5 100644 --- a/.claude/skills/truthmark-document/helper-manifest.yml +++ b/.claude/skills/truthmark-document/helper-manifest.yml @@ -1,8 +1,8 @@ -# Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +# Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. helpers: validate-document-report: optional: true - runner: truthmark>=1.5.0 + runner: truthmark>=1.6.0 command: argv: - truthmark @@ -17,7 +17,7 @@ helpers: fallback: manually validate support/report-template.md required sections and structured Evidence checked entries validate-write-lease: optional: true - runner: truthmark>=1.5.0 + runner: truthmark>=1.6.0 command: argv: - truthmark diff --git a/.claude/skills/truthmark-document/support/helper-policy.md b/.claude/skills/truthmark-document/support/helper-policy.md index 24a89d8..53b72b7 100644 --- a/.claude/skills/truthmark-document/support/helper-policy.md +++ b/.claude/skills/truthmark-document/support/helper-policy.md @@ -1,6 +1,6 @@ # Optional Helper CLI Policy -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Optional helper CLI commands may collect deterministic checkout facts or validate artifacts. If the Truthmark CLI is unavailable or too old for a declared helper, continue manually using this procedure and report which helper was skipped. Helper output is derived evidence; it does not override direct checkout inspection, workflow write boundaries, or parent acceptance. @@ -11,8 +11,8 @@ Runner detection: - Do not fail the workflow solely because a helper cannot run. Available helpers: -- validate-document-report: optional truthmark>=1.5.0; manual fallback: manually validate support/report-template.md required sections and structured Evidence checked entries -- validate-write-lease: optional truthmark>=1.5.0; manual fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files +- validate-document-report: optional truthmark>=1.6.0; manual fallback: manually validate support/report-template.md required sections and structured Evidence checked entries +- validate-write-lease: optional truthmark>=1.6.0; manual fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files Final reports should include helper status when helpers are declared for this workflow: diff --git a/.claude/skills/truthmark-document/support/procedure.md b/.claude/skills/truthmark-document/support/procedure.md index c0af75d..44d8eb3 100644 --- a/.claude/skills/truthmark-document/support/procedure.md +++ b/.claude/skills/truthmark-document/support/procedure.md @@ -1,6 +1,6 @@ # Truthmark Document Procedure -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. # Truthmark Document @@ -10,8 +10,8 @@ Invocations: OpenCode /skill truthmark-document; Codex /truthmark-document or $t Truth Document is manual and implementation-first: - run only when the user explicitly asks to generate or update truth docs for existing behavior, or when Truth Sync, Truth Check, or Truth Structure reports implemented behavior that lacks canonical truth docs -- inspect .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, existing canonical docs, implementation code, and tests directly -- Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +- inspect .truthmark/config.yml and configured route files only when they exist; then inspect existing canonical docs, implementation code, and tests directly +- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. - document current implemented behavior; do not invent future behavior or planned endpoints - may write canonical truth docs and docs/truthmark/areas.md or relevant child route files only @@ -43,7 +43,7 @@ Evidence Gate: - if no truth doc changed, report why current truth was already sufficient or why documentation was blocked Repository intelligence artifacts are optional derived context: RepoIndex, RouteMap, ImpactSet, and ContextPack may guide routing, context selection, and verification planning when available. They do not override checkout evidence, canonical truth docs, route files, or workflow write boundaries. -If unavailable, inspect .truthmark/config.yml, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated. +If unavailable, inspect any present Truthmark config, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated. When creating or updating a truth doc, inspect the routed truth kind and use the matching `docs/templates/-doc.md` template. Supported kinds: behavior, contract, architecture, workflow, operations, and test-behavior. Align existing docs to that template while preserving accurate authored content. @@ -58,11 +58,11 @@ Truth-doc shape repair gate: - report docs restructured and why a narrow edit was not sufficient Maintain architecture docs only for structure-level changes: system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership. Keep ordinary behavior, endpoints, UI copy, validation rules, and bug fixes in behavior or contract docs unless they change those boundaries. -Truthmark hierarchy: -- Config: .truthmark/config.yml -- Root route index: docs/truthmark/areas.md -- Area route files: docs/truthmark/areas/**/*.md -- Truth docs: docs/truth/**/*.md +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. Update Product Decisions and Rationale when a decision changes behavior. diff --git a/.claude/skills/truthmark-document/support/report-template.md b/.claude/skills/truthmark-document/support/report-template.md index 32cb1c3..22741ff 100644 --- a/.claude/skills/truthmark-document/support/report-template.md +++ b/.claude/skills/truthmark-document/support/report-template.md @@ -1,6 +1,6 @@ # Truthmark Document Report Template -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Report completion in this shape: ```md diff --git a/.claude/skills/truthmark-document/support/subagents-and-leases.md b/.claude/skills/truthmark-document/support/subagents-and-leases.md index 0d844bb..c0960d9 100644 --- a/.claude/skills/truthmark-document/support/subagents-and-leases.md +++ b/.claude/skills/truthmark-document/support/subagents-and-leases.md @@ -1,6 +1,6 @@ # Truthmark Document Subagents And Leases -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Claude Code subagent mode: - use automatically when this workflow runs in Claude Code and the parent agent chooses bounded subagent fan-out diff --git a/.claude/skills/truthmark-preview/SKILL.md b/.claude/skills/truthmark-preview/SKILL.md index 83dd9db..05e0598 100644 --- a/.claude/skills/truthmark-preview/SKILL.md +++ b/.claude/skills/truthmark-preview/SKILL.md @@ -3,7 +3,7 @@ name: truthmark-preview description: Use when the user explicitly asks to preview likely workflow routing, target files, writes, or subagent use before edits. Not for validation, automatic gates, final correctness, or replacing Truth Check. argument-hint: Optional requested outcome, code area, doc path, or routing question user-invocable: true -truthmark-version: 1.5.0 +truthmark-version: 1.6.0 --- # Truthmark Preview @@ -14,8 +14,8 @@ Use this skill only when the user explicitly asks to preview Truthmark routing o Invocations: OpenCode /skill truthmark-preview; Codex /truthmark-preview or $truthmark-preview; Claude Code /truthmark-preview; GitHub Copilot /truthmark-preview; Gemini CLI /truthmark:preview. Quick procedure: -- Follow docs/ai/repo-rules.md as the repository instruction authority. -- Read .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, and only the truth docs or implementation files needed to preview ownership. +- Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists. +- Inspect .truthmark/config.yml and configured route files (docs/truthmark/areas.md; docs/truthmark/areas/) only when they exist; then inspect only the truth docs or implementation files needed to preview ownership. - Truth Preview is read-only; this report is intended, not authorized. - must not edit files and must not issue write leases; do not run Truth Sync automatically, replace Truth Check, claim final correctness, or mutate code. - Use optional read-only route-auditor evidence only when it reduces context or clarifies ownership. diff --git a/.claude/skills/truthmark-preview/support/procedure.md b/.claude/skills/truthmark-preview/support/procedure.md index 14c4376..d419bf2 100644 --- a/.claude/skills/truthmark-preview/support/procedure.md +++ b/.claude/skills/truthmark-preview/support/procedure.md @@ -1,6 +1,6 @@ # Truthmark Preview Procedure -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Use this skill only when the user explicitly asks to preview Truthmark routing or workflow choice before edits. @@ -14,11 +14,11 @@ Purpose: - keep the selector thin so agents can avoid loading or acting through heavier workflows prematurely Read: -- .truthmark/config.yml -- docs/truthmark/areas.md -- relevant child route files under docs/truthmark/areas/ +- .truthmark/config.yml, only when present +- docs/truthmark/areas.md, only when present +- relevant child route files under docs/truthmark/areas/, only when present - relevant truth docs and implementation files needed to preview ownership -- Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. Do not: @@ -36,8 +36,8 @@ Suggested subagent use: - write workers: none - leases needed: none -Truthmark hierarchy: -- Config: .truthmark/config.yml -- Root route index: docs/truthmark/areas.md -- Area route files: docs/truthmark/areas/**/*.md -- Truth docs: docs/truth/**/*.md +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md diff --git a/.claude/skills/truthmark-preview/support/report-template.md b/.claude/skills/truthmark-preview/support/report-template.md index 345ba01..72cf72b 100644 --- a/.claude/skills/truthmark-preview/support/report-template.md +++ b/.claude/skills/truthmark-preview/support/report-template.md @@ -1,6 +1,6 @@ # Truthmark Preview Report Template -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Report completion in this shape: ```md diff --git a/.claude/skills/truthmark-preview/support/subagents-and-leases.md b/.claude/skills/truthmark-preview/support/subagents-and-leases.md index c00071d..ccf877a 100644 --- a/.claude/skills/truthmark-preview/support/subagents-and-leases.md +++ b/.claude/skills/truthmark-preview/support/subagents-and-leases.md @@ -1,6 +1,6 @@ # Truthmark Preview Subagents And Leases -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Claude Code subagent mode: - use automatically when this workflow runs in Claude Code and the parent agent chooses bounded subagent fan-out diff --git a/.claude/skills/truthmark-realize/SKILL.md b/.claude/skills/truthmark-realize/SKILL.md index 90cb033..c91e02d 100644 --- a/.claude/skills/truthmark-realize/SKILL.md +++ b/.claude/skills/truthmark-realize/SKILL.md @@ -3,7 +3,7 @@ name: truthmark-realize description: Use when the user explicitly asks to realize Truthmark truth docs into code, including /truthmark-realize, $truthmark-realize, or /truthmark:realize. Not for syncing docs after code changes, documenting existing code, topology repair, or truth audits. argument-hint: Optional truth doc path, area, or desired code behavior to realize user-invocable: true -truthmark-version: 1.5.0 +truthmark-version: 1.6.0 --- # Truthmark Realize @@ -14,8 +14,8 @@ Use this skill only when the user explicitly asks to realize truth docs into cod Invocations: OpenCode /skill truthmark-realize; Codex /truthmark-realize or $truthmark-realize; Claude Code /truthmark-realize; GitHub Copilot /truthmark-realize; Gemini CLI /truthmark:realize. Quick procedure: -- Follow docs/ai/repo-rules.md as the repository instruction authority. -- Read the source truth docs, .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files, tests, and relevant functional code directly. +- Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists. +- Read the source truth docs, inspect .truthmark/config.yml and configured route files (docs/truthmark/areas.md; docs/truthmark/areas/) only when they exist, then inspect tests and relevant functional code directly. - Truth docs lead; code follows. - may write functional code only; must not edit truth docs or truth routing while realizing those docs. - Read support/procedure.md before changing code. diff --git a/.claude/skills/truthmark-realize/support/procedure.md b/.claude/skills/truthmark-realize/support/procedure.md index ad9eacd..aa9883b 100644 --- a/.claude/skills/truthmark-realize/support/procedure.md +++ b/.claude/skills/truthmark-realize/support/procedure.md @@ -1,6 +1,6 @@ # Truthmark Realize Procedure -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. # Truthmark Realize @@ -16,9 +16,9 @@ Truth Realize is doc-first: Workflow: -1. Read the updated truth docs named by the user, or infer the relevant docs from docs/truthmark/areas.md. -2. Read .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files, tests, and the relevant functional code. -3. Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +1. Read the updated truth docs named by the user, or infer the relevant docs from configured route files when present. +2. Inspect .truthmark/config.yml and configured route files (docs/truthmark/areas.md; docs/truthmark/areas/) only when they exist; then read tests and the relevant functional code. +3. Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. Truth-doc ownership gate: - before editing or relying on source truth docs before writing code, verify each target/source truth doc is a bounded owner for the behavior @@ -29,11 +29,11 @@ Truth-doc ownership gate: 5. Do not edit truth docs or truth routing while realizing those docs. 6. Run relevant tests for the changed code. 7. Report changed code files and verification steps. -Truthmark hierarchy: -- Config: .truthmark/config.yml -- Root route index: docs/truthmark/areas.md -- Area route files: docs/truthmark/areas/**/*.md -- Truth docs: docs/truth/**/*.md +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md Read and write boundaries: diff --git a/.claude/skills/truthmark-realize/support/report-template.md b/.claude/skills/truthmark-realize/support/report-template.md index 9ca297b..e49dde5 100644 --- a/.claude/skills/truthmark-realize/support/report-template.md +++ b/.claude/skills/truthmark-realize/support/report-template.md @@ -1,6 +1,6 @@ # Truthmark Realize Report Template -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Report completion in this shape: diff --git a/.claude/skills/truthmark-structure/SKILL.md b/.claude/skills/truthmark-structure/SKILL.md index f112e7e..67f522b 100644 --- a/.claude/skills/truthmark-structure/SKILL.md +++ b/.claude/skills/truthmark-structure/SKILL.md @@ -3,7 +3,7 @@ name: truthmark-structure description: Use when routing or truth ownership is missing, stale, broad, overloaded, catch-all, unrouteable, mixed-owner, needs split/repair, or needs new area setup. Not for documenting implemented behavior, syncing a code diff, or realizing docs into code. argument-hint: Optional area, directory, or routing concern user-invocable: true -truthmark-version: 1.5.0 +truthmark-version: 1.6.0 --- # Truthmark Structure @@ -14,8 +14,8 @@ Use this skill to design or repair Truthmark area structure. Invocations: OpenCode /skill truthmark-structure; Codex /truthmark-structure or $truthmark-structure; Claude Code /truthmark-structure; GitHub Copilot /truthmark-structure; Gemini CLI /truthmark:structure. Quick procedure: -- Follow docs/ai/repo-rules.md as the repository instruction authority. -- Read .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, current docs, and relevant code directly. +- Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists. +- Inspect .truthmark/config.yml and configured route files (docs/truthmark/areas.md; docs/truthmark/areas/) only when they exist; then inspect current docs and relevant code directly. - Define areas by product or behavior ownership, not by mechanical directory mirroring. - Do not edit functional code. - Read support/procedure.md before writing route or starter truth-doc changes. diff --git a/.claude/skills/truthmark-structure/support/procedure.md b/.claude/skills/truthmark-structure/support/procedure.md index 8315ea1..9104b33 100644 --- a/.claude/skills/truthmark-structure/support/procedure.md +++ b/.claude/skills/truthmark-structure/support/procedure.md @@ -1,14 +1,14 @@ # Truthmark Structure Procedure -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Use this skill to design or repair Truthmark area structure. Invocations: OpenCode /skill truthmark-structure; Codex /truthmark-structure or $truthmark-structure; Claude Code /truthmark-structure; GitHub Copilot /truthmark-structure; Gemini CLI /truthmark:structure. Truth Structure is agent-native: -- inspect repository layout, current docs, .truthmark/config.yml, docs/truthmark/areas.md, and relevant code directly -- Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +- inspect repository layout, current docs, Truthmark config and route files when present, and relevant code directly +- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. -- inspect the configured root route index at docs/truthmark/areas.md and relevant child route files under docs/truthmark/areas/ +- inspect the configured root route index at docs/truthmark/areas.md and relevant child route files under docs/truthmark/areas/ when they exist - define areas by product or behavior ownership, not by mechanical directory mirroring - create or repair docs/truthmark/areas.md - create starter truth docs when useful and when they belong in the canonical current-truth surface @@ -97,13 +97,13 @@ Keep ordinary behavior, endpoints, UI copy, validation rules, and bug fixes in b Portable fallback: - If this skill surface is unavailable, perform the same workflow directly from committed repository files. - Do not require the truthmark CLI. -- Read .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, canonical docs, and representative implementation code. +- Inspect .truthmark/config.yml and configured route files only when they exist; then inspect canonical docs and representative implementation code. - Use a subagent only when the host supports that pattern; otherwise perform the topology repair inline. -Truthmark hierarchy: -- Config: .truthmark/config.yml -- Root route index: docs/truthmark/areas.md -- Area route files: docs/truthmark/areas/**/*.md -- Truth docs: docs/truth/**/*.md +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. Update Product Decisions and Rationale when a decision changes behavior. diff --git a/.claude/skills/truthmark-structure/support/report-template.md b/.claude/skills/truthmark-structure/support/report-template.md index 75b6b1f..c104da3 100644 --- a/.claude/skills/truthmark-structure/support/report-template.md +++ b/.claude/skills/truthmark-structure/support/report-template.md @@ -1,6 +1,6 @@ # Truthmark Structure Report Template -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Report completion in this shape: ```md diff --git a/.claude/skills/truthmark-structure/support/subagents-and-leases.md b/.claude/skills/truthmark-structure/support/subagents-and-leases.md index e0dbcea..2e07107 100644 --- a/.claude/skills/truthmark-structure/support/subagents-and-leases.md +++ b/.claude/skills/truthmark-structure/support/subagents-and-leases.md @@ -1,6 +1,6 @@ # Truthmark Structure Subagents And Leases -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Claude Code subagent mode: - use automatically when this workflow runs in Claude Code and the parent agent chooses bounded subagent fan-out diff --git a/.claude/skills/truthmark-sync/SKILL.md b/.claude/skills/truthmark-sync/SKILL.md index 344e5c6..651ffc3 100644 --- a/.claude/skills/truthmark-sync/SKILL.md +++ b/.claude/skills/truthmark-sync/SKILL.md @@ -3,7 +3,7 @@ name: truthmark-sync description: Use automatically at finish-time after functional code changes, or explicit /truthmark-sync, $truthmark-sync, or /truthmark:sync. Skip docs-only, formatting-only, behavior-preserving renames, missing config, and no-code changes. Not for doc-first realization or manual topology design. argument-hint: Optional changed-code area, truth-doc area, or sync focus user-invocable: true -truthmark-version: 1.5.0 +truthmark-version: 1.6.0 --- # Truthmark Sync @@ -14,9 +14,9 @@ Use this skill automatically before finishing when functional code changed since Invocations: OpenCode /skill truthmark-sync; Codex /truthmark-sync or $truthmark-sync; Claude Code /truthmark-sync; GitHub Copilot /truthmark-sync; Gemini CLI /truthmark:sync. Quick procedure: -- Follow docs/ai/repo-rules.md as the repository instruction authority. +- Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists. - Skip docs-only, formatting-only, behavior-preserving renames with no truth impact, missing config, and no-code changes. -- Read .truthmark/config.yml, the configured root route index at docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, and relevant canonical docs. +- Inspect .truthmark/config.yml and configured route files (docs/truthmark/areas.md; docs/truthmark/areas/) only when they exist; then inspect relevant canonical docs directly. - direct checkout inspection is the canonical path; do not require the truthmark binary. - May write canonical truth docs and truth routing files only; must not rewrite functional code. - Read support/procedure.md before editing truth docs. diff --git a/.claude/skills/truthmark-sync/helper-manifest.yml b/.claude/skills/truthmark-sync/helper-manifest.yml index 663eeef..ce58751 100644 --- a/.claude/skills/truthmark-sync/helper-manifest.yml +++ b/.claude/skills/truthmark-sync/helper-manifest.yml @@ -1,8 +1,8 @@ -# Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +# Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. helpers: validate-sync-report: optional: true - runner: truthmark>=1.5.0 + runner: truthmark>=1.6.0 command: argv: - truthmark @@ -17,7 +17,7 @@ helpers: fallback: "manually validate support/report-template.md and check Evidence checked entries match Claim, indented Evidence, and Result: supported | narrowed | removed | blocked" validate-write-lease: optional: true - runner: truthmark>=1.5.0 + runner: truthmark>=1.6.0 command: argv: - truthmark diff --git a/.claude/skills/truthmark-sync/support/helper-policy.md b/.claude/skills/truthmark-sync/support/helper-policy.md index e7d086f..c3d00c7 100644 --- a/.claude/skills/truthmark-sync/support/helper-policy.md +++ b/.claude/skills/truthmark-sync/support/helper-policy.md @@ -1,6 +1,6 @@ # Optional Helper CLI Policy -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Optional helper CLI commands may collect deterministic checkout facts or validate artifacts. If the Truthmark CLI is unavailable or too old for a declared helper, continue manually using this procedure and report which helper was skipped. Helper output is derived evidence; it does not override direct checkout inspection, workflow write boundaries, or parent acceptance. @@ -11,8 +11,8 @@ Runner detection: - Do not fail the workflow solely because a helper cannot run. Available helpers: -- validate-sync-report: optional truthmark>=1.5.0; manual fallback: manually validate support/report-template.md and check Evidence checked entries match Claim, indented Evidence, and Result: supported | narrowed | removed | blocked -- validate-write-lease: optional truthmark>=1.5.0; manual fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files +- validate-sync-report: optional truthmark>=1.6.0; manual fallback: manually validate support/report-template.md and check Evidence checked entries match Claim, indented Evidence, and Result: supported | narrowed | removed | blocked +- validate-write-lease: optional truthmark>=1.6.0; manual fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files Final reports should include helper status when helpers are declared for this workflow: diff --git a/.claude/skills/truthmark-sync/support/procedure.md b/.claude/skills/truthmark-sync/support/procedure.md index 22da116..a80e050 100644 --- a/.claude/skills/truthmark-sync/support/procedure.md +++ b/.claude/skills/truthmark-sync/support/procedure.md @@ -1,6 +1,6 @@ # Truthmark Sync Procedure -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Use this skill automatically before finishing when functional code changed since the last successful Truth Sync. Also run it immediately when the user explicitly invokes Truth Sync. Invocations: OpenCode /skill truthmark-sync; Codex /truthmark-sync or $truthmark-sync; Claude Code /truthmark-sync; GitHub Copilot /truthmark-sync; Gemini CLI /truthmark:sync. @@ -8,9 +8,9 @@ Explicit invocation runs immediately. Later functional-code changes reopen the f Skip when changes are documentation-only, formatting-only, clearly behavior-preserving renames with no truth impact, when no Truthmark config exists yet, or when there are no functional code changes. Parent workflow: 1. Inspect git status, staged changes, unstaged changes, and untracked files directly. -2. Read .truthmark/config.yml, the configured root route index at docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, and relevant canonical docs. +2. Inspect .truthmark/config.yml and configured route files only when they exist; then inspect relevant canonical docs. 3. Identify functional-code changes and the nearest truth docs or routing repairs. -4. Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +4. Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. 5. Code verification is parent-owned: follow repository instructions and task context, and report what ran or why it did not run. 6. Dispatch bounded Truth Sync workers only when the host supports subagent dispatch and the acting agent chooses that path; otherwise execute the same sync task inline. @@ -57,7 +57,7 @@ Evidence Gate: - if no impacted doc changed, report why truth was already current or why sync was skipped Repository intelligence artifacts are optional derived context: RepoIndex, RouteMap, ImpactSet, and ContextPack may guide routing, context selection, and verification planning when available. They do not override checkout evidence, canonical truth docs, route files, or workflow write boundaries. -If unavailable, inspect .truthmark/config.yml, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated. +If unavailable, inspect any present Truthmark config, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated. Optional validation tooling: - you may run truthmark check when local tooling is available - do not require the truthmark binary; direct checkout inspection is the canonical path @@ -69,11 +69,11 @@ Helper status reporting: - If the installed Truthmark CLI is unavailable or the helper is skipped, record `validate-sync-report: skipped, ` and manually validate the report shape. - Record `validate-write-lease: ran, passed` only after validating a concrete write lease; otherwise use a truthful skipped status such as `skipped, no write lease used`. - Helper output is derived evidence and never replaces direct checkout inspection, evidence review, or parent acceptance. -Truthmark hierarchy: -- Config: .truthmark/config.yml -- Root route index: docs/truthmark/areas.md -- Area route files: docs/truthmark/areas/**/*.md -- Truth docs: docs/truth/**/*.md +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. Update Product Decisions and Rationale when a decision changes behavior. diff --git a/.claude/skills/truthmark-sync/support/report-template.md b/.claude/skills/truthmark-sync/support/report-template.md index 5cd2313..9bce186 100644 --- a/.claude/skills/truthmark-sync/support/report-template.md +++ b/.claude/skills/truthmark-sync/support/report-template.md @@ -1,6 +1,6 @@ # Truthmark Sync Report Template -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Report completion in this shape: ```md diff --git a/.claude/skills/truthmark-sync/support/subagents-and-leases.md b/.claude/skills/truthmark-sync/support/subagents-and-leases.md index 730620c..14b807f 100644 --- a/.claude/skills/truthmark-sync/support/subagents-and-leases.md +++ b/.claude/skills/truthmark-sync/support/subagents-and-leases.md @@ -1,6 +1,6 @@ # Truthmark Sync Subagents And Leases -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Claude Code subagent mode: - use automatically when this workflow runs in Claude Code and the parent agent chooses bounded subagent fan-out diff --git a/.codex/agents/truth-claim-verifier.toml b/.codex/agents/truth-claim-verifier.toml index c8b07bb..e52bcf2 100644 --- a/.codex/agents/truth-claim-verifier.toml +++ b/.codex/agents/truth-claim-verifier.toml @@ -1,4 +1,4 @@ -# Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +# Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. name = "truth_claim_verifier" description = "Read-only Truthmark claim verifier for checking canonical truth against checkout evidence." sandbox_mode = "read-only" diff --git a/.codex/agents/truth-doc-reviewer.toml b/.codex/agents/truth-doc-reviewer.toml index 083d4ec..03ee31d 100644 --- a/.codex/agents/truth-doc-reviewer.toml +++ b/.codex/agents/truth-doc-reviewer.toml @@ -1,4 +1,4 @@ -# Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +# Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. name = "truth_doc_reviewer" description = "Read-only Truthmark doc reviewer for shape, decision, rationale, and evidence hygiene." sandbox_mode = "read-only" diff --git a/.codex/agents/truth-doc-writer.toml b/.codex/agents/truth-doc-writer.toml index 0d82a54..06af27e 100644 --- a/.codex/agents/truth-doc-writer.toml +++ b/.codex/agents/truth-doc-writer.toml @@ -1,4 +1,4 @@ -# Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +# Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. name = "truth_doc_writer" description = "Write-capable Truthmark doc worker for one parent-leased truth-document shard." sandbox_mode = "workspace-write" diff --git a/.codex/agents/truth-route-auditor.toml b/.codex/agents/truth-route-auditor.toml index ae35981..ba1b766 100644 --- a/.codex/agents/truth-route-auditor.toml +++ b/.codex/agents/truth-route-auditor.toml @@ -1,4 +1,4 @@ -# Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +# Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. name = "truth_route_auditor" description = "Read-only Truthmark route auditor for bounded routing and ownership verification." sandbox_mode = "read-only" @@ -6,7 +6,7 @@ nickname_candidates = ["Route Audit", "Route Trace", "Route Check"] developer_instructions = """ Stay read-only. Audit one bounded Truthmark route, area, or doc shard assigned by the parent. -Read .truthmark/config.yml, the root route index, relevant child route files, mapped truth docs, and relevant implementation files directly. +Inspect .truthmark/config.yml and route files only when they exist; then inspect mapped truth docs and relevant implementation files directly. Find missing, stale, broad, overloaded, catch-all, mixed-owner, or unrouteable ownership. Do not edit files, stage changes, or propose broad rewrites. Return JSON only with keys: scope, filesReviewed, findings, evidence, confidence, recommendedWorkflow, notes. diff --git a/.codex/skills/truthmark-check/SKILL.md b/.codex/skills/truthmark-check/SKILL.md index 7364b22..a81e78f 100644 --- a/.codex/skills/truthmark-check/SKILL.md +++ b/.codex/skills/truthmark-check/SKILL.md @@ -3,7 +3,7 @@ name: truthmark-check description: Use when the user asks to audit repository truth health, routing, ownership, or canonical docs. Not for normal lint/test/typecheck/code-review verification, finish-time Sync, or silently rewriting docs. argument-hint: Optional area, doc path, or audit focus user-invocable: true -truthmark-version: 1.5.0 +truthmark-version: 1.6.0 --- # Truthmark Check @@ -14,8 +14,8 @@ Use this skill to audit repository truth health. Invocations: OpenCode /skill truthmark-check; Codex /truthmark-check or $truthmark-check; Claude Code /truthmark-check; GitHub Copilot /truthmark-check; Gemini CLI /truthmark:check. Quick procedure: -- Follow docs/ai/repo-rules.md as the repository instruction authority. -- Read .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, canonical docs, and relevant implementation directly. +- Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists. +- Inspect .truthmark/config.yml and configured route files (docs/truthmark/areas.md; docs/truthmark/areas/) only when they exist; then inspect canonical docs and relevant implementation directly. - Report issues and suggested fixes; do not silently rewrite unrelated files. - Direct checkout inspection is valid even when local tooling is unavailable. - Read support/procedure.md before auditing details. diff --git a/.codex/skills/truthmark-check/agents/openai.yaml b/.codex/skills/truthmark-check/agents/openai.yaml index 50ff847..8a350a7 100644 --- a/.codex/skills/truthmark-check/agents/openai.yaml +++ b/.codex/skills/truthmark-check/agents/openai.yaml @@ -7,5 +7,5 @@ policy: allow_implicit_invocation: false truthmark: - version: "1.5.0" + version: "1.6.0" refresh_command: "truthmark init" diff --git a/.codex/skills/truthmark-check/support/procedure.md b/.codex/skills/truthmark-check/support/procedure.md index 82239d8..33b7663 100644 --- a/.codex/skills/truthmark-check/support/procedure.md +++ b/.codex/skills/truthmark-check/support/procedure.md @@ -1,6 +1,6 @@ # Truthmark Check Procedure -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. # Truthmark Check @@ -10,12 +10,12 @@ Invocations: OpenCode /skill truthmark-check; Codex /truthmark-check or $truthma Truth Check is agent-led: -- inspect .truthmark/config.yml, docs/truthmark/areas.md, canonical docs, and relevant implementation directly -- Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +- inspect .truthmark/config.yml and configured route files only when they exist; then inspect canonical docs and relevant implementation directly +- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. -- inspect the configured root route index at docs/truthmark/areas.md and relevant child route files under docs/truthmark/areas/ +- inspect the configured root route index at docs/truthmark/areas.md and relevant child route files under docs/truthmark/areas/ when they exist - check that current docs describe current code rather than historical plans -- check that docs/truthmark/areas.md routes code surfaces to canonical truth docs +- check that route files map code surfaces to canonical truth docs when route files exist - check for broad, catch-all, index-like, or mixed-owner truth docs and report them as topology issues requiring Truth Structure - check that canonical behavior docs keep active Product Decisions and Rationale sections - optionally run truthmark check when local tooling is available @@ -27,11 +27,11 @@ Evidence Gate: - canonical docs are context, not sole proof when implementation conflicts - remove unsupported findings or mark open questions; validate changed claims if you edit docs -Truthmark hierarchy: -- Config: .truthmark/config.yml -- Root route index: docs/truthmark/areas.md -- Area route files: docs/truthmark/areas/**/*.md -- Truth docs: docs/truth/**/*.md +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. Update Product Decisions and Rationale when a decision changes behavior. diff --git a/.codex/skills/truthmark-check/support/report-template.md b/.codex/skills/truthmark-check/support/report-template.md index 1dc6319..e98269e 100644 --- a/.codex/skills/truthmark-check/support/report-template.md +++ b/.codex/skills/truthmark-check/support/report-template.md @@ -1,6 +1,6 @@ # Truthmark Check Report Template -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Report completion in this shape: @@ -18,7 +18,7 @@ Fixes suggested: Evidence checked: - Finding: The root route index is present and maps repository truth owners. - Evidence: .truthmark/config.yml:1 / docs/truthmark/areas.md:1 + Evidence: docs/truthmark/areas.md:1 Suggested fix: none Confidence: high diff --git a/.codex/skills/truthmark-check/support/subagents-and-leases.md b/.codex/skills/truthmark-check/support/subagents-and-leases.md index 7ec6746..0f1a0a2 100644 --- a/.codex/skills/truthmark-check/support/subagents-and-leases.md +++ b/.codex/skills/truthmark-check/support/subagents-and-leases.md @@ -1,6 +1,6 @@ # Truthmark Check Subagents And Leases -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Codex subagent mode: - use automatically when this workflow runs in Codex and the parent agent chooses bounded subagent fan-out diff --git a/.codex/skills/truthmark-document/SKILL.md b/.codex/skills/truthmark-document/SKILL.md index bd9ca15..751caa5 100644 --- a/.codex/skills/truthmark-document/SKILL.md +++ b/.codex/skills/truthmark-document/SKILL.md @@ -3,7 +3,7 @@ name: truthmark-document description: Use when the user asks to document existing implemented behavior, or Sync, Check, or Structure finds implemented behavior missing canonical truth. Not for functional-code changes, doc-first implementation, or topology repair that needs Structure. argument-hint: Optional implemented behavior, API endpoint, route, controller, package, or truth-doc area to document user-invocable: true -truthmark-version: 1.5.0 +truthmark-version: 1.6.0 --- # Truthmark Document @@ -14,8 +14,8 @@ Use this skill to document existing implemented behavior when no functional-code Invocations: OpenCode /skill truthmark-document; Codex /truthmark-document or $truthmark-document; Claude Code /truthmark-document; GitHub Copilot /truthmark-document; Gemini CLI /truthmark:document. Quick procedure: -- Follow docs/ai/repo-rules.md as the repository instruction authority. -- Read .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, existing canonical docs, implementation code, and tests directly. +- Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists. +- Inspect .truthmark/config.yml and configured route files (docs/truthmark/areas.md; docs/truthmark/areas/) only when they exist; then inspect existing canonical docs, implementation code, and tests directly. - Document current implemented behavior; do not invent future behavior. - May write canonical truth docs and truth routing files only; must not write functional code. - Read support/procedure.md before editing truth docs. diff --git a/.codex/skills/truthmark-document/agents/openai.yaml b/.codex/skills/truthmark-document/agents/openai.yaml index 4248571..8f286c1 100644 --- a/.codex/skills/truthmark-document/agents/openai.yaml +++ b/.codex/skills/truthmark-document/agents/openai.yaml @@ -7,5 +7,5 @@ policy: allow_implicit_invocation: false truthmark: - version: "1.5.0" + version: "1.6.0" refresh_command: "truthmark init" diff --git a/.codex/skills/truthmark-document/helper-manifest.yml b/.codex/skills/truthmark-document/helper-manifest.yml index e53fa02..dc05fe5 100644 --- a/.codex/skills/truthmark-document/helper-manifest.yml +++ b/.codex/skills/truthmark-document/helper-manifest.yml @@ -1,8 +1,8 @@ -# Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +# Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. helpers: validate-document-report: optional: true - runner: truthmark>=1.5.0 + runner: truthmark>=1.6.0 command: argv: - truthmark @@ -17,7 +17,7 @@ helpers: fallback: manually validate support/report-template.md required sections and structured Evidence checked entries validate-write-lease: optional: true - runner: truthmark>=1.5.0 + runner: truthmark>=1.6.0 command: argv: - truthmark diff --git a/.codex/skills/truthmark-document/support/helper-policy.md b/.codex/skills/truthmark-document/support/helper-policy.md index 24a89d8..53b72b7 100644 --- a/.codex/skills/truthmark-document/support/helper-policy.md +++ b/.codex/skills/truthmark-document/support/helper-policy.md @@ -1,6 +1,6 @@ # Optional Helper CLI Policy -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Optional helper CLI commands may collect deterministic checkout facts or validate artifacts. If the Truthmark CLI is unavailable or too old for a declared helper, continue manually using this procedure and report which helper was skipped. Helper output is derived evidence; it does not override direct checkout inspection, workflow write boundaries, or parent acceptance. @@ -11,8 +11,8 @@ Runner detection: - Do not fail the workflow solely because a helper cannot run. Available helpers: -- validate-document-report: optional truthmark>=1.5.0; manual fallback: manually validate support/report-template.md required sections and structured Evidence checked entries -- validate-write-lease: optional truthmark>=1.5.0; manual fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files +- validate-document-report: optional truthmark>=1.6.0; manual fallback: manually validate support/report-template.md required sections and structured Evidence checked entries +- validate-write-lease: optional truthmark>=1.6.0; manual fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files Final reports should include helper status when helpers are declared for this workflow: diff --git a/.codex/skills/truthmark-document/support/procedure.md b/.codex/skills/truthmark-document/support/procedure.md index c0af75d..44d8eb3 100644 --- a/.codex/skills/truthmark-document/support/procedure.md +++ b/.codex/skills/truthmark-document/support/procedure.md @@ -1,6 +1,6 @@ # Truthmark Document Procedure -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. # Truthmark Document @@ -10,8 +10,8 @@ Invocations: OpenCode /skill truthmark-document; Codex /truthmark-document or $t Truth Document is manual and implementation-first: - run only when the user explicitly asks to generate or update truth docs for existing behavior, or when Truth Sync, Truth Check, or Truth Structure reports implemented behavior that lacks canonical truth docs -- inspect .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, existing canonical docs, implementation code, and tests directly -- Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +- inspect .truthmark/config.yml and configured route files only when they exist; then inspect existing canonical docs, implementation code, and tests directly +- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. - document current implemented behavior; do not invent future behavior or planned endpoints - may write canonical truth docs and docs/truthmark/areas.md or relevant child route files only @@ -43,7 +43,7 @@ Evidence Gate: - if no truth doc changed, report why current truth was already sufficient or why documentation was blocked Repository intelligence artifacts are optional derived context: RepoIndex, RouteMap, ImpactSet, and ContextPack may guide routing, context selection, and verification planning when available. They do not override checkout evidence, canonical truth docs, route files, or workflow write boundaries. -If unavailable, inspect .truthmark/config.yml, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated. +If unavailable, inspect any present Truthmark config, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated. When creating or updating a truth doc, inspect the routed truth kind and use the matching `docs/templates/-doc.md` template. Supported kinds: behavior, contract, architecture, workflow, operations, and test-behavior. Align existing docs to that template while preserving accurate authored content. @@ -58,11 +58,11 @@ Truth-doc shape repair gate: - report docs restructured and why a narrow edit was not sufficient Maintain architecture docs only for structure-level changes: system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership. Keep ordinary behavior, endpoints, UI copy, validation rules, and bug fixes in behavior or contract docs unless they change those boundaries. -Truthmark hierarchy: -- Config: .truthmark/config.yml -- Root route index: docs/truthmark/areas.md -- Area route files: docs/truthmark/areas/**/*.md -- Truth docs: docs/truth/**/*.md +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. Update Product Decisions and Rationale when a decision changes behavior. diff --git a/.codex/skills/truthmark-document/support/report-template.md b/.codex/skills/truthmark-document/support/report-template.md index 32cb1c3..22741ff 100644 --- a/.codex/skills/truthmark-document/support/report-template.md +++ b/.codex/skills/truthmark-document/support/report-template.md @@ -1,6 +1,6 @@ # Truthmark Document Report Template -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Report completion in this shape: ```md diff --git a/.codex/skills/truthmark-document/support/subagents-and-leases.md b/.codex/skills/truthmark-document/support/subagents-and-leases.md index 0d368a1..72ce420 100644 --- a/.codex/skills/truthmark-document/support/subagents-and-leases.md +++ b/.codex/skills/truthmark-document/support/subagents-and-leases.md @@ -1,6 +1,6 @@ # Truthmark Document Subagents And Leases -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Codex subagent mode: - use automatically when this workflow runs in Codex and the parent agent chooses bounded subagent fan-out diff --git a/.codex/skills/truthmark-preview/SKILL.md b/.codex/skills/truthmark-preview/SKILL.md index 83dd9db..05e0598 100644 --- a/.codex/skills/truthmark-preview/SKILL.md +++ b/.codex/skills/truthmark-preview/SKILL.md @@ -3,7 +3,7 @@ name: truthmark-preview description: Use when the user explicitly asks to preview likely workflow routing, target files, writes, or subagent use before edits. Not for validation, automatic gates, final correctness, or replacing Truth Check. argument-hint: Optional requested outcome, code area, doc path, or routing question user-invocable: true -truthmark-version: 1.5.0 +truthmark-version: 1.6.0 --- # Truthmark Preview @@ -14,8 +14,8 @@ Use this skill only when the user explicitly asks to preview Truthmark routing o Invocations: OpenCode /skill truthmark-preview; Codex /truthmark-preview or $truthmark-preview; Claude Code /truthmark-preview; GitHub Copilot /truthmark-preview; Gemini CLI /truthmark:preview. Quick procedure: -- Follow docs/ai/repo-rules.md as the repository instruction authority. -- Read .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, and only the truth docs or implementation files needed to preview ownership. +- Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists. +- Inspect .truthmark/config.yml and configured route files (docs/truthmark/areas.md; docs/truthmark/areas/) only when they exist; then inspect only the truth docs or implementation files needed to preview ownership. - Truth Preview is read-only; this report is intended, not authorized. - must not edit files and must not issue write leases; do not run Truth Sync automatically, replace Truth Check, claim final correctness, or mutate code. - Use optional read-only route-auditor evidence only when it reduces context or clarifies ownership. diff --git a/.codex/skills/truthmark-preview/agents/openai.yaml b/.codex/skills/truthmark-preview/agents/openai.yaml index 021cf08..fadb6af 100644 --- a/.codex/skills/truthmark-preview/agents/openai.yaml +++ b/.codex/skills/truthmark-preview/agents/openai.yaml @@ -7,5 +7,5 @@ policy: allow_implicit_invocation: false truthmark: - version: "1.5.0" + version: "1.6.0" refresh_command: "truthmark init" diff --git a/.codex/skills/truthmark-preview/support/procedure.md b/.codex/skills/truthmark-preview/support/procedure.md index 14c4376..d419bf2 100644 --- a/.codex/skills/truthmark-preview/support/procedure.md +++ b/.codex/skills/truthmark-preview/support/procedure.md @@ -1,6 +1,6 @@ # Truthmark Preview Procedure -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Use this skill only when the user explicitly asks to preview Truthmark routing or workflow choice before edits. @@ -14,11 +14,11 @@ Purpose: - keep the selector thin so agents can avoid loading or acting through heavier workflows prematurely Read: -- .truthmark/config.yml -- docs/truthmark/areas.md -- relevant child route files under docs/truthmark/areas/ +- .truthmark/config.yml, only when present +- docs/truthmark/areas.md, only when present +- relevant child route files under docs/truthmark/areas/, only when present - relevant truth docs and implementation files needed to preview ownership -- Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. Do not: @@ -36,8 +36,8 @@ Suggested subagent use: - write workers: none - leases needed: none -Truthmark hierarchy: -- Config: .truthmark/config.yml -- Root route index: docs/truthmark/areas.md -- Area route files: docs/truthmark/areas/**/*.md -- Truth docs: docs/truth/**/*.md +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md diff --git a/.codex/skills/truthmark-preview/support/report-template.md b/.codex/skills/truthmark-preview/support/report-template.md index 345ba01..72cf72b 100644 --- a/.codex/skills/truthmark-preview/support/report-template.md +++ b/.codex/skills/truthmark-preview/support/report-template.md @@ -1,6 +1,6 @@ # Truthmark Preview Report Template -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Report completion in this shape: ```md diff --git a/.codex/skills/truthmark-preview/support/subagents-and-leases.md b/.codex/skills/truthmark-preview/support/subagents-and-leases.md index 5414e90..edee679 100644 --- a/.codex/skills/truthmark-preview/support/subagents-and-leases.md +++ b/.codex/skills/truthmark-preview/support/subagents-and-leases.md @@ -1,6 +1,6 @@ # Truthmark Preview Subagents And Leases -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Codex subagent mode: - use automatically when this workflow runs in Codex and the parent agent chooses bounded subagent fan-out diff --git a/.codex/skills/truthmark-realize/SKILL.md b/.codex/skills/truthmark-realize/SKILL.md index 90cb033..c91e02d 100644 --- a/.codex/skills/truthmark-realize/SKILL.md +++ b/.codex/skills/truthmark-realize/SKILL.md @@ -3,7 +3,7 @@ name: truthmark-realize description: Use when the user explicitly asks to realize Truthmark truth docs into code, including /truthmark-realize, $truthmark-realize, or /truthmark:realize. Not for syncing docs after code changes, documenting existing code, topology repair, or truth audits. argument-hint: Optional truth doc path, area, or desired code behavior to realize user-invocable: true -truthmark-version: 1.5.0 +truthmark-version: 1.6.0 --- # Truthmark Realize @@ -14,8 +14,8 @@ Use this skill only when the user explicitly asks to realize truth docs into cod Invocations: OpenCode /skill truthmark-realize; Codex /truthmark-realize or $truthmark-realize; Claude Code /truthmark-realize; GitHub Copilot /truthmark-realize; Gemini CLI /truthmark:realize. Quick procedure: -- Follow docs/ai/repo-rules.md as the repository instruction authority. -- Read the source truth docs, .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files, tests, and relevant functional code directly. +- Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists. +- Read the source truth docs, inspect .truthmark/config.yml and configured route files (docs/truthmark/areas.md; docs/truthmark/areas/) only when they exist, then inspect tests and relevant functional code directly. - Truth docs lead; code follows. - may write functional code only; must not edit truth docs or truth routing while realizing those docs. - Read support/procedure.md before changing code. diff --git a/.codex/skills/truthmark-realize/agents/openai.yaml b/.codex/skills/truthmark-realize/agents/openai.yaml index f923473..e06f4ed 100644 --- a/.codex/skills/truthmark-realize/agents/openai.yaml +++ b/.codex/skills/truthmark-realize/agents/openai.yaml @@ -7,5 +7,5 @@ policy: allow_implicit_invocation: false truthmark: - version: "1.5.0" + version: "1.6.0" refresh_command: "truthmark init" diff --git a/.codex/skills/truthmark-realize/support/procedure.md b/.codex/skills/truthmark-realize/support/procedure.md index ad9eacd..aa9883b 100644 --- a/.codex/skills/truthmark-realize/support/procedure.md +++ b/.codex/skills/truthmark-realize/support/procedure.md @@ -1,6 +1,6 @@ # Truthmark Realize Procedure -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. # Truthmark Realize @@ -16,9 +16,9 @@ Truth Realize is doc-first: Workflow: -1. Read the updated truth docs named by the user, or infer the relevant docs from docs/truthmark/areas.md. -2. Read .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files, tests, and the relevant functional code. -3. Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +1. Read the updated truth docs named by the user, or infer the relevant docs from configured route files when present. +2. Inspect .truthmark/config.yml and configured route files (docs/truthmark/areas.md; docs/truthmark/areas/) only when they exist; then read tests and the relevant functional code. +3. Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. Truth-doc ownership gate: - before editing or relying on source truth docs before writing code, verify each target/source truth doc is a bounded owner for the behavior @@ -29,11 +29,11 @@ Truth-doc ownership gate: 5. Do not edit truth docs or truth routing while realizing those docs. 6. Run relevant tests for the changed code. 7. Report changed code files and verification steps. -Truthmark hierarchy: -- Config: .truthmark/config.yml -- Root route index: docs/truthmark/areas.md -- Area route files: docs/truthmark/areas/**/*.md -- Truth docs: docs/truth/**/*.md +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md Read and write boundaries: diff --git a/.codex/skills/truthmark-realize/support/report-template.md b/.codex/skills/truthmark-realize/support/report-template.md index 9ca297b..e49dde5 100644 --- a/.codex/skills/truthmark-realize/support/report-template.md +++ b/.codex/skills/truthmark-realize/support/report-template.md @@ -1,6 +1,6 @@ # Truthmark Realize Report Template -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Report completion in this shape: diff --git a/.codex/skills/truthmark-structure/SKILL.md b/.codex/skills/truthmark-structure/SKILL.md index f112e7e..67f522b 100644 --- a/.codex/skills/truthmark-structure/SKILL.md +++ b/.codex/skills/truthmark-structure/SKILL.md @@ -3,7 +3,7 @@ name: truthmark-structure description: Use when routing or truth ownership is missing, stale, broad, overloaded, catch-all, unrouteable, mixed-owner, needs split/repair, or needs new area setup. Not for documenting implemented behavior, syncing a code diff, or realizing docs into code. argument-hint: Optional area, directory, or routing concern user-invocable: true -truthmark-version: 1.5.0 +truthmark-version: 1.6.0 --- # Truthmark Structure @@ -14,8 +14,8 @@ Use this skill to design or repair Truthmark area structure. Invocations: OpenCode /skill truthmark-structure; Codex /truthmark-structure or $truthmark-structure; Claude Code /truthmark-structure; GitHub Copilot /truthmark-structure; Gemini CLI /truthmark:structure. Quick procedure: -- Follow docs/ai/repo-rules.md as the repository instruction authority. -- Read .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, current docs, and relevant code directly. +- Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists. +- Inspect .truthmark/config.yml and configured route files (docs/truthmark/areas.md; docs/truthmark/areas/) only when they exist; then inspect current docs and relevant code directly. - Define areas by product or behavior ownership, not by mechanical directory mirroring. - Do not edit functional code. - Read support/procedure.md before writing route or starter truth-doc changes. diff --git a/.codex/skills/truthmark-structure/agents/openai.yaml b/.codex/skills/truthmark-structure/agents/openai.yaml index 5f655eb..ec6a11b 100644 --- a/.codex/skills/truthmark-structure/agents/openai.yaml +++ b/.codex/skills/truthmark-structure/agents/openai.yaml @@ -7,5 +7,5 @@ policy: allow_implicit_invocation: false truthmark: - version: "1.5.0" + version: "1.6.0" refresh_command: "truthmark init" diff --git a/.codex/skills/truthmark-structure/support/procedure.md b/.codex/skills/truthmark-structure/support/procedure.md index 8315ea1..9104b33 100644 --- a/.codex/skills/truthmark-structure/support/procedure.md +++ b/.codex/skills/truthmark-structure/support/procedure.md @@ -1,14 +1,14 @@ # Truthmark Structure Procedure -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Use this skill to design or repair Truthmark area structure. Invocations: OpenCode /skill truthmark-structure; Codex /truthmark-structure or $truthmark-structure; Claude Code /truthmark-structure; GitHub Copilot /truthmark-structure; Gemini CLI /truthmark:structure. Truth Structure is agent-native: -- inspect repository layout, current docs, .truthmark/config.yml, docs/truthmark/areas.md, and relevant code directly -- Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +- inspect repository layout, current docs, Truthmark config and route files when present, and relevant code directly +- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. -- inspect the configured root route index at docs/truthmark/areas.md and relevant child route files under docs/truthmark/areas/ +- inspect the configured root route index at docs/truthmark/areas.md and relevant child route files under docs/truthmark/areas/ when they exist - define areas by product or behavior ownership, not by mechanical directory mirroring - create or repair docs/truthmark/areas.md - create starter truth docs when useful and when they belong in the canonical current-truth surface @@ -97,13 +97,13 @@ Keep ordinary behavior, endpoints, UI copy, validation rules, and bug fixes in b Portable fallback: - If this skill surface is unavailable, perform the same workflow directly from committed repository files. - Do not require the truthmark CLI. -- Read .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, canonical docs, and representative implementation code. +- Inspect .truthmark/config.yml and configured route files only when they exist; then inspect canonical docs and representative implementation code. - Use a subagent only when the host supports that pattern; otherwise perform the topology repair inline. -Truthmark hierarchy: -- Config: .truthmark/config.yml -- Root route index: docs/truthmark/areas.md -- Area route files: docs/truthmark/areas/**/*.md -- Truth docs: docs/truth/**/*.md +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. Update Product Decisions and Rationale when a decision changes behavior. diff --git a/.codex/skills/truthmark-structure/support/report-template.md b/.codex/skills/truthmark-structure/support/report-template.md index 75b6b1f..c104da3 100644 --- a/.codex/skills/truthmark-structure/support/report-template.md +++ b/.codex/skills/truthmark-structure/support/report-template.md @@ -1,6 +1,6 @@ # Truthmark Structure Report Template -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Report completion in this shape: ```md diff --git a/.codex/skills/truthmark-structure/support/subagents-and-leases.md b/.codex/skills/truthmark-structure/support/subagents-and-leases.md index 8a0ca91..11d2d5e 100644 --- a/.codex/skills/truthmark-structure/support/subagents-and-leases.md +++ b/.codex/skills/truthmark-structure/support/subagents-and-leases.md @@ -1,6 +1,6 @@ # Truthmark Structure Subagents And Leases -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Codex subagent mode: - use automatically when this workflow runs in Codex and the parent agent chooses bounded subagent fan-out diff --git a/.codex/skills/truthmark-sync/SKILL.md b/.codex/skills/truthmark-sync/SKILL.md index 344e5c6..651ffc3 100644 --- a/.codex/skills/truthmark-sync/SKILL.md +++ b/.codex/skills/truthmark-sync/SKILL.md @@ -3,7 +3,7 @@ name: truthmark-sync description: Use automatically at finish-time after functional code changes, or explicit /truthmark-sync, $truthmark-sync, or /truthmark:sync. Skip docs-only, formatting-only, behavior-preserving renames, missing config, and no-code changes. Not for doc-first realization or manual topology design. argument-hint: Optional changed-code area, truth-doc area, or sync focus user-invocable: true -truthmark-version: 1.5.0 +truthmark-version: 1.6.0 --- # Truthmark Sync @@ -14,9 +14,9 @@ Use this skill automatically before finishing when functional code changed since Invocations: OpenCode /skill truthmark-sync; Codex /truthmark-sync or $truthmark-sync; Claude Code /truthmark-sync; GitHub Copilot /truthmark-sync; Gemini CLI /truthmark:sync. Quick procedure: -- Follow docs/ai/repo-rules.md as the repository instruction authority. +- Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists. - Skip docs-only, formatting-only, behavior-preserving renames with no truth impact, missing config, and no-code changes. -- Read .truthmark/config.yml, the configured root route index at docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, and relevant canonical docs. +- Inspect .truthmark/config.yml and configured route files (docs/truthmark/areas.md; docs/truthmark/areas/) only when they exist; then inspect relevant canonical docs directly. - direct checkout inspection is the canonical path; do not require the truthmark binary. - May write canonical truth docs and truth routing files only; must not rewrite functional code. - Read support/procedure.md before editing truth docs. diff --git a/.codex/skills/truthmark-sync/agents/openai.yaml b/.codex/skills/truthmark-sync/agents/openai.yaml index 03a9bfa..9e9e93c 100644 --- a/.codex/skills/truthmark-sync/agents/openai.yaml +++ b/.codex/skills/truthmark-sync/agents/openai.yaml @@ -7,5 +7,5 @@ policy: allow_implicit_invocation: true truthmark: - version: "1.5.0" + version: "1.6.0" refresh_command: "truthmark init" diff --git a/.codex/skills/truthmark-sync/helper-manifest.yml b/.codex/skills/truthmark-sync/helper-manifest.yml index 663eeef..ce58751 100644 --- a/.codex/skills/truthmark-sync/helper-manifest.yml +++ b/.codex/skills/truthmark-sync/helper-manifest.yml @@ -1,8 +1,8 @@ -# Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +# Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. helpers: validate-sync-report: optional: true - runner: truthmark>=1.5.0 + runner: truthmark>=1.6.0 command: argv: - truthmark @@ -17,7 +17,7 @@ helpers: fallback: "manually validate support/report-template.md and check Evidence checked entries match Claim, indented Evidence, and Result: supported | narrowed | removed | blocked" validate-write-lease: optional: true - runner: truthmark>=1.5.0 + runner: truthmark>=1.6.0 command: argv: - truthmark diff --git a/.codex/skills/truthmark-sync/support/helper-policy.md b/.codex/skills/truthmark-sync/support/helper-policy.md index e7d086f..c3d00c7 100644 --- a/.codex/skills/truthmark-sync/support/helper-policy.md +++ b/.codex/skills/truthmark-sync/support/helper-policy.md @@ -1,6 +1,6 @@ # Optional Helper CLI Policy -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Optional helper CLI commands may collect deterministic checkout facts or validate artifacts. If the Truthmark CLI is unavailable or too old for a declared helper, continue manually using this procedure and report which helper was skipped. Helper output is derived evidence; it does not override direct checkout inspection, workflow write boundaries, or parent acceptance. @@ -11,8 +11,8 @@ Runner detection: - Do not fail the workflow solely because a helper cannot run. Available helpers: -- validate-sync-report: optional truthmark>=1.5.0; manual fallback: manually validate support/report-template.md and check Evidence checked entries match Claim, indented Evidence, and Result: supported | narrowed | removed | blocked -- validate-write-lease: optional truthmark>=1.5.0; manual fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files +- validate-sync-report: optional truthmark>=1.6.0; manual fallback: manually validate support/report-template.md and check Evidence checked entries match Claim, indented Evidence, and Result: supported | narrowed | removed | blocked +- validate-write-lease: optional truthmark>=1.6.0; manual fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files Final reports should include helper status when helpers are declared for this workflow: diff --git a/.codex/skills/truthmark-sync/support/procedure.md b/.codex/skills/truthmark-sync/support/procedure.md index 22da116..a80e050 100644 --- a/.codex/skills/truthmark-sync/support/procedure.md +++ b/.codex/skills/truthmark-sync/support/procedure.md @@ -1,6 +1,6 @@ # Truthmark Sync Procedure -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Use this skill automatically before finishing when functional code changed since the last successful Truth Sync. Also run it immediately when the user explicitly invokes Truth Sync. Invocations: OpenCode /skill truthmark-sync; Codex /truthmark-sync or $truthmark-sync; Claude Code /truthmark-sync; GitHub Copilot /truthmark-sync; Gemini CLI /truthmark:sync. @@ -8,9 +8,9 @@ Explicit invocation runs immediately. Later functional-code changes reopen the f Skip when changes are documentation-only, formatting-only, clearly behavior-preserving renames with no truth impact, when no Truthmark config exists yet, or when there are no functional code changes. Parent workflow: 1. Inspect git status, staged changes, unstaged changes, and untracked files directly. -2. Read .truthmark/config.yml, the configured root route index at docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, and relevant canonical docs. +2. Inspect .truthmark/config.yml and configured route files only when they exist; then inspect relevant canonical docs. 3. Identify functional-code changes and the nearest truth docs or routing repairs. -4. Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +4. Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. 5. Code verification is parent-owned: follow repository instructions and task context, and report what ran or why it did not run. 6. Dispatch bounded Truth Sync workers only when the host supports subagent dispatch and the acting agent chooses that path; otherwise execute the same sync task inline. @@ -57,7 +57,7 @@ Evidence Gate: - if no impacted doc changed, report why truth was already current or why sync was skipped Repository intelligence artifacts are optional derived context: RepoIndex, RouteMap, ImpactSet, and ContextPack may guide routing, context selection, and verification planning when available. They do not override checkout evidence, canonical truth docs, route files, or workflow write boundaries. -If unavailable, inspect .truthmark/config.yml, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated. +If unavailable, inspect any present Truthmark config, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated. Optional validation tooling: - you may run truthmark check when local tooling is available - do not require the truthmark binary; direct checkout inspection is the canonical path @@ -69,11 +69,11 @@ Helper status reporting: - If the installed Truthmark CLI is unavailable or the helper is skipped, record `validate-sync-report: skipped, ` and manually validate the report shape. - Record `validate-write-lease: ran, passed` only after validating a concrete write lease; otherwise use a truthful skipped status such as `skipped, no write lease used`. - Helper output is derived evidence and never replaces direct checkout inspection, evidence review, or parent acceptance. -Truthmark hierarchy: -- Config: .truthmark/config.yml -- Root route index: docs/truthmark/areas.md -- Area route files: docs/truthmark/areas/**/*.md -- Truth docs: docs/truth/**/*.md +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. Update Product Decisions and Rationale when a decision changes behavior. diff --git a/.codex/skills/truthmark-sync/support/report-template.md b/.codex/skills/truthmark-sync/support/report-template.md index 5cd2313..9bce186 100644 --- a/.codex/skills/truthmark-sync/support/report-template.md +++ b/.codex/skills/truthmark-sync/support/report-template.md @@ -1,6 +1,6 @@ # Truthmark Sync Report Template -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Report completion in this shape: ```md diff --git a/.codex/skills/truthmark-sync/support/subagents-and-leases.md b/.codex/skills/truthmark-sync/support/subagents-and-leases.md index 95cb4d3..5730250 100644 --- a/.codex/skills/truthmark-sync/support/subagents-and-leases.md +++ b/.codex/skills/truthmark-sync/support/subagents-and-leases.md @@ -1,6 +1,6 @@ # Truthmark Sync Subagents And Leases -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Codex subagent mode: - use automatically when this workflow runs in Codex and the parent agent chooses bounded subagent fan-out diff --git a/.gemini/agents/truth-claim-verifier.md b/.gemini/agents/truth-claim-verifier.md index a0d3e8e..9f06dea 100644 --- a/.gemini/agents/truth-claim-verifier.md +++ b/.gemini/agents/truth-claim-verifier.md @@ -5,7 +5,7 @@ kind: local tools: [read_file, grep_search] --- -# Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +# Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Manual invocation: @truth-claim-verifier diff --git a/.gemini/agents/truth-doc-reviewer.md b/.gemini/agents/truth-doc-reviewer.md index b528bf9..f696479 100644 --- a/.gemini/agents/truth-doc-reviewer.md +++ b/.gemini/agents/truth-doc-reviewer.md @@ -5,7 +5,7 @@ kind: local tools: [read_file, grep_search] --- -# Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +# Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Manual invocation: @truth-doc-reviewer diff --git a/.gemini/agents/truth-doc-writer.md b/.gemini/agents/truth-doc-writer.md index baa0027..d595539 100644 --- a/.gemini/agents/truth-doc-writer.md +++ b/.gemini/agents/truth-doc-writer.md @@ -5,7 +5,7 @@ kind: local tools: [read_file, grep_search, write_file] --- -# Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +# Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Manual invocation: @truth-doc-writer with an explicit parent write lease. diff --git a/.gemini/agents/truth-route-auditor.md b/.gemini/agents/truth-route-auditor.md index 6b14e34..9a653f6 100644 --- a/.gemini/agents/truth-route-auditor.md +++ b/.gemini/agents/truth-route-auditor.md @@ -5,13 +5,13 @@ kind: local tools: [read_file, grep_search] --- -# Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +# Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Manual invocation: @truth-route-auditor Stay read-only. Audit one bounded Truthmark route, area, or doc shard assigned by the parent. -Read .truthmark/config.yml, the root route index, relevant child route files, mapped truth docs, and relevant implementation files directly. +Inspect .truthmark/config.yml and route files only when they exist; then inspect mapped truth docs and relevant implementation files directly. Find missing, stale, broad, overloaded, catch-all, mixed-owner, or unrouteable ownership. Do not edit files, stage changes, or propose broad rewrites. Return JSON only with keys: scope, filesReviewed, findings, evidence, confidence, recommendedWorkflow, notes. diff --git a/.gemini/commands/truthmark/check.toml b/.gemini/commands/truthmark/check.toml index f81518a..64adc0d 100644 --- a/.gemini/commands/truthmark/check.toml +++ b/.gemini/commands/truthmark/check.toml @@ -5,7 +5,7 @@ name: truthmark-check description: Use when the user asks to audit repository truth health, routing, ownership, or canonical docs. Not for normal lint/test/typecheck/code-review verification, finish-time Sync, or silently rewriting docs. argument-hint: Optional area, doc path, or audit focus user-invocable: true -truthmark-version: 1.5.0 +truthmark-version: 1.6.0 --- # Truthmark Check @@ -16,12 +16,12 @@ Invocations: OpenCode /skill truthmark-check; Codex /truthmark-check or $truthma Truth Check is agent-led: -- inspect .truthmark/config.yml, docs/truthmark/areas.md, canonical docs, and relevant implementation directly -- Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +- inspect .truthmark/config.yml and configured route files only when they exist; then inspect canonical docs and relevant implementation directly +- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. -- inspect the configured root route index at docs/truthmark/areas.md and relevant child route files under docs/truthmark/areas/ +- inspect the configured root route index at docs/truthmark/areas.md and relevant child route files under docs/truthmark/areas/ when they exist - check that current docs describe current code rather than historical plans -- check that docs/truthmark/areas.md routes code surfaces to canonical truth docs +- check that route files map code surfaces to canonical truth docs when route files exist - check for broad, catch-all, index-like, or mixed-owner truth docs and report them as topology issues requiring Truth Structure - check that canonical behavior docs keep active Product Decisions and Rationale sections - optionally run truthmark check when local tooling is available @@ -33,11 +33,11 @@ Evidence Gate: - canonical docs are context, not sole proof when implementation conflicts - remove unsupported findings or mark open questions; validate changed claims if you edit docs -Truthmark hierarchy: -- Config: .truthmark/config.yml -- Root route index: docs/truthmark/areas.md -- Area route files: docs/truthmark/areas/**/*.md -- Truth docs: docs/truth/**/*.md +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. Update Product Decisions and Rationale when a decision changes behavior. @@ -58,7 +58,7 @@ Fixes suggested: Evidence checked: - Finding: The root route index is present and maps repository truth owners. - Evidence: .truthmark/config.yml:1 / docs/truthmark/areas.md:1 + Evidence: docs/truthmark/areas.md:1 Suggested fix: none Confidence: high diff --git a/.gemini/commands/truthmark/document.toml b/.gemini/commands/truthmark/document.toml index 01fccfd..dc85a2d 100644 --- a/.gemini/commands/truthmark/document.toml +++ b/.gemini/commands/truthmark/document.toml @@ -5,7 +5,7 @@ name: truthmark-document description: Use when the user asks to document existing implemented behavior, or Sync, Check, or Structure finds implemented behavior missing canonical truth. Not for functional-code changes, doc-first implementation, or topology repair that needs Structure. argument-hint: Optional implemented behavior, API endpoint, route, controller, package, or truth-doc area to document user-invocable: true -truthmark-version: 1.5.0 +truthmark-version: 1.6.0 --- # Truthmark Document @@ -16,8 +16,8 @@ Invocations: OpenCode /skill truthmark-document; Codex /truthmark-document or $t Truth Document is manual and implementation-first: - run only when the user explicitly asks to generate or update truth docs for existing behavior, or when Truth Sync, Truth Check, or Truth Structure reports implemented behavior that lacks canonical truth docs -- inspect .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, existing canonical docs, implementation code, and tests directly -- Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +- inspect .truthmark/config.yml and configured route files only when they exist; then inspect existing canonical docs, implementation code, and tests directly +- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. - document current implemented behavior; do not invent future behavior or planned endpoints - may write canonical truth docs and docs/truthmark/areas.md or relevant child route files only @@ -49,7 +49,7 @@ Evidence Gate: - if no truth doc changed, report why current truth was already sufficient or why documentation was blocked Repository intelligence artifacts are optional derived context: RepoIndex, RouteMap, ImpactSet, and ContextPack may guide routing, context selection, and verification planning when available. They do not override checkout evidence, canonical truth docs, route files, or workflow write boundaries. -If unavailable, inspect .truthmark/config.yml, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated. +If unavailable, inspect any present Truthmark config, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated. When creating or updating a truth doc, inspect the routed truth kind and use the matching `docs/templates/-doc.md` template. Supported kinds: behavior, contract, architecture, workflow, operations, and test-behavior. Align existing docs to that template while preserving accurate authored content. @@ -64,11 +64,11 @@ Truth-doc shape repair gate: - report docs restructured and why a narrow edit was not sufficient Maintain architecture docs only for structure-level changes: system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership. Keep ordinary behavior, endpoints, UI copy, validation rules, and bug fixes in behavior or contract docs unless they change those boundaries. -Truthmark hierarchy: -- Config: .truthmark/config.yml -- Root route index: docs/truthmark/areas.md -- Area route files: docs/truthmark/areas/**/*.md -- Truth docs: docs/truth/**/*.md +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. Update Product Decisions and Rationale when a decision changes behavior. diff --git a/.gemini/commands/truthmark/preview.toml b/.gemini/commands/truthmark/preview.toml index fb2462a..9938294 100644 --- a/.gemini/commands/truthmark/preview.toml +++ b/.gemini/commands/truthmark/preview.toml @@ -5,7 +5,7 @@ name: truthmark-preview description: Use when the user explicitly asks to preview likely workflow routing, target files, writes, or subagent use before edits. Not for validation, automatic gates, final correctness, or replacing Truth Check. argument-hint: Optional requested outcome, code area, doc path, or routing question user-invocable: true -truthmark-version: 1.5.0 +truthmark-version: 1.6.0 --- Use this skill only when the user explicitly asks to preview Truthmark routing or workflow choice before edits. @@ -20,11 +20,11 @@ Purpose: - keep the selector thin so agents can avoid loading or acting through heavier workflows prematurely Read: -- .truthmark/config.yml -- docs/truthmark/areas.md -- relevant child route files under docs/truthmark/areas/ +- .truthmark/config.yml, only when present +- docs/truthmark/areas.md, only when present +- relevant child route files under docs/truthmark/areas/, only when present - relevant truth docs and implementation files needed to preview ownership -- Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. Do not: @@ -42,11 +42,11 @@ Suggested subagent use: - write workers: none - leases needed: none -Truthmark hierarchy: -- Config: .truthmark/config.yml -- Root route index: docs/truthmark/areas.md -- Area route files: docs/truthmark/areas/**/*.md -- Truth docs: docs/truth/**/*.md +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md Report completion in this shape: ```md diff --git a/.gemini/commands/truthmark/realize.toml b/.gemini/commands/truthmark/realize.toml index 09da1a4..f898d03 100644 --- a/.gemini/commands/truthmark/realize.toml +++ b/.gemini/commands/truthmark/realize.toml @@ -5,7 +5,7 @@ name: truthmark-realize description: Use when the user explicitly asks to realize Truthmark truth docs into code, including /truthmark-realize, $truthmark-realize, or /truthmark:realize. Not for syncing docs after code changes, documenting existing code, topology repair, or truth audits. argument-hint: Optional truth doc path, area, or desired code behavior to realize user-invocable: true -truthmark-version: 1.5.0 +truthmark-version: 1.6.0 --- # Truthmark Realize @@ -22,9 +22,9 @@ Truth Realize is doc-first: Workflow: -1. Read the updated truth docs named by the user, or infer the relevant docs from docs/truthmark/areas.md. -2. Read .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files, tests, and the relevant functional code. -3. Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +1. Read the updated truth docs named by the user, or infer the relevant docs from configured route files when present. +2. Inspect .truthmark/config.yml and configured route files (docs/truthmark/areas.md; docs/truthmark/areas/) only when they exist; then read tests and the relevant functional code. +3. Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. Truth-doc ownership gate: - before editing or relying on source truth docs before writing code, verify each target/source truth doc is a bounded owner for the behavior @@ -35,11 +35,11 @@ Truth-doc ownership gate: 5. Do not edit truth docs or truth routing while realizing those docs. 6. Run relevant tests for the changed code. 7. Report changed code files and verification steps. -Truthmark hierarchy: -- Config: .truthmark/config.yml -- Root route index: docs/truthmark/areas.md -- Area route files: docs/truthmark/areas/**/*.md -- Truth docs: docs/truth/**/*.md +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md Read and write boundaries: diff --git a/.gemini/commands/truthmark/structure.toml b/.gemini/commands/truthmark/structure.toml index 2dc75d8..4ab44fc 100644 --- a/.gemini/commands/truthmark/structure.toml +++ b/.gemini/commands/truthmark/structure.toml @@ -5,16 +5,16 @@ name: truthmark-structure description: Use when routing or truth ownership is missing, stale, broad, overloaded, catch-all, unrouteable, mixed-owner, needs split/repair, or needs new area setup. Not for documenting implemented behavior, syncing a code diff, or realizing docs into code. argument-hint: Optional area, directory, or routing concern user-invocable: true -truthmark-version: 1.5.0 +truthmark-version: 1.6.0 --- Use this skill to design or repair Truthmark area structure. Invocations: OpenCode /skill truthmark-structure; Codex /truthmark-structure or $truthmark-structure; Claude Code /truthmark-structure; GitHub Copilot /truthmark-structure; Gemini CLI /truthmark:structure. Truth Structure is agent-native: -- inspect repository layout, current docs, .truthmark/config.yml, docs/truthmark/areas.md, and relevant code directly -- Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +- inspect repository layout, current docs, Truthmark config and route files when present, and relevant code directly +- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. -- inspect the configured root route index at docs/truthmark/areas.md and relevant child route files under docs/truthmark/areas/ +- inspect the configured root route index at docs/truthmark/areas.md and relevant child route files under docs/truthmark/areas/ when they exist - define areas by product or behavior ownership, not by mechanical directory mirroring - create or repair docs/truthmark/areas.md - create starter truth docs when useful and when they belong in the canonical current-truth surface @@ -103,13 +103,13 @@ Keep ordinary behavior, endpoints, UI copy, validation rules, and bug fixes in b Portable fallback: - If this skill surface is unavailable, perform the same workflow directly from committed repository files. - Do not require the truthmark CLI. -- Read .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, canonical docs, and representative implementation code. +- Inspect .truthmark/config.yml and configured route files only when they exist; then inspect canonical docs and representative implementation code. - Use a subagent only when the host supports that pattern; otherwise perform the topology repair inline. -Truthmark hierarchy: -- Config: .truthmark/config.yml -- Root route index: docs/truthmark/areas.md -- Area route files: docs/truthmark/areas/**/*.md -- Truth docs: docs/truth/**/*.md +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. Update Product Decisions and Rationale when a decision changes behavior. diff --git a/.gemini/commands/truthmark/sync.toml b/.gemini/commands/truthmark/sync.toml index 90ef8fb..ac93125 100644 --- a/.gemini/commands/truthmark/sync.toml +++ b/.gemini/commands/truthmark/sync.toml @@ -5,7 +5,7 @@ name: truthmark-sync description: Use automatically at finish-time after functional code changes, or explicit /truthmark-sync, $truthmark-sync, or /truthmark:sync. Skip docs-only, formatting-only, behavior-preserving renames, missing config, and no-code changes. Not for doc-first realization or manual topology design. argument-hint: Optional changed-code area, truth-doc area, or sync focus user-invocable: true -truthmark-version: 1.5.0 +truthmark-version: 1.6.0 --- Use this skill automatically before finishing when functional code changed since the last successful Truth Sync. Also run it immediately when the user explicitly invokes Truth Sync. @@ -14,9 +14,9 @@ Explicit invocation runs immediately. Later functional-code changes reopen the f Skip when changes are documentation-only, formatting-only, clearly behavior-preserving renames with no truth impact, when no Truthmark config exists yet, or when there are no functional code changes. Parent workflow: 1. Inspect git status, staged changes, unstaged changes, and untracked files directly. -2. Read .truthmark/config.yml, the configured root route index at docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, and relevant canonical docs. +2. Inspect .truthmark/config.yml and configured route files only when they exist; then inspect relevant canonical docs. 3. Identify functional-code changes and the nearest truth docs or routing repairs. -4. Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +4. Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. 5. Code verification is parent-owned: follow repository instructions and task context, and report what ran or why it did not run. 6. Dispatch bounded Truth Sync workers only when the host supports subagent dispatch and the acting agent chooses that path; otherwise execute the same sync task inline. @@ -63,7 +63,7 @@ Evidence Gate: - if no impacted doc changed, report why truth was already current or why sync was skipped Repository intelligence artifacts are optional derived context: RepoIndex, RouteMap, ImpactSet, and ContextPack may guide routing, context selection, and verification planning when available. They do not override checkout evidence, canonical truth docs, route files, or workflow write boundaries. -If unavailable, inspect .truthmark/config.yml, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated. +If unavailable, inspect any present Truthmark config, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated. Optional validation tooling: - you may run truthmark check when local tooling is available - do not require the truthmark binary; direct checkout inspection is the canonical path @@ -75,11 +75,11 @@ Helper status reporting: - If the installed Truthmark CLI is unavailable or the helper is skipped, record `validate-sync-report: skipped, ` and manually validate the report shape. - Record `validate-write-lease: ran, passed` only after validating a concrete write lease; otherwise use a truthful skipped status such as `skipped, no write lease used`. - Helper output is derived evidence and never replaces direct checkout inspection, evidence review, or parent acceptance. -Truthmark hierarchy: -- Config: .truthmark/config.yml -- Root route index: docs/truthmark/areas.md -- Area route files: docs/truthmark/areas/**/*.md -- Truth docs: docs/truth/**/*.md +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. Update Product Decisions and Rationale when a decision changes behavior. diff --git a/.gemini/skills/truthmark-check/SKILL.md b/.gemini/skills/truthmark-check/SKILL.md index 2aa50ff..b9749f5 100644 --- a/.gemini/skills/truthmark-check/SKILL.md +++ b/.gemini/skills/truthmark-check/SKILL.md @@ -3,7 +3,7 @@ name: truthmark-check description: Use when the user asks to audit repository truth health, routing, ownership, or canonical docs. Not for normal lint/test/typecheck/code-review verification, finish-time Sync, or silently rewriting docs. argument-hint: Optional area, doc path, or audit focus user-invocable: true -truthmark-version: 1.5.0 +truthmark-version: 1.6.0 --- # Truthmark Check @@ -16,8 +16,8 @@ Use as a Gemini CLI Agent Skill; commands remain available under `/truthmark:*` Invocations: OpenCode /skill truthmark-check; Codex /truthmark-check or $truthmark-check; Claude Code /truthmark-check; GitHub Copilot /truthmark-check; Gemini CLI /truthmark:check. Quick procedure: -- Follow docs/ai/repo-rules.md as the repository instruction authority. -- Read .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, canonical docs, and relevant implementation directly. +- Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists. +- Inspect .truthmark/config.yml and configured route files (docs/truthmark/areas.md; docs/truthmark/areas/) only when they exist; then inspect canonical docs and relevant implementation directly. - Report issues and suggested fixes; do not silently rewrite unrelated files. - Direct checkout inspection is valid even when local tooling is unavailable. - Read support/procedure.md before auditing details. diff --git a/.gemini/skills/truthmark-check/support/procedure.md b/.gemini/skills/truthmark-check/support/procedure.md index 82239d8..33b7663 100644 --- a/.gemini/skills/truthmark-check/support/procedure.md +++ b/.gemini/skills/truthmark-check/support/procedure.md @@ -1,6 +1,6 @@ # Truthmark Check Procedure -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. # Truthmark Check @@ -10,12 +10,12 @@ Invocations: OpenCode /skill truthmark-check; Codex /truthmark-check or $truthma Truth Check is agent-led: -- inspect .truthmark/config.yml, docs/truthmark/areas.md, canonical docs, and relevant implementation directly -- Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +- inspect .truthmark/config.yml and configured route files only when they exist; then inspect canonical docs and relevant implementation directly +- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. -- inspect the configured root route index at docs/truthmark/areas.md and relevant child route files under docs/truthmark/areas/ +- inspect the configured root route index at docs/truthmark/areas.md and relevant child route files under docs/truthmark/areas/ when they exist - check that current docs describe current code rather than historical plans -- check that docs/truthmark/areas.md routes code surfaces to canonical truth docs +- check that route files map code surfaces to canonical truth docs when route files exist - check for broad, catch-all, index-like, or mixed-owner truth docs and report them as topology issues requiring Truth Structure - check that canonical behavior docs keep active Product Decisions and Rationale sections - optionally run truthmark check when local tooling is available @@ -27,11 +27,11 @@ Evidence Gate: - canonical docs are context, not sole proof when implementation conflicts - remove unsupported findings or mark open questions; validate changed claims if you edit docs -Truthmark hierarchy: -- Config: .truthmark/config.yml -- Root route index: docs/truthmark/areas.md -- Area route files: docs/truthmark/areas/**/*.md -- Truth docs: docs/truth/**/*.md +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. Update Product Decisions and Rationale when a decision changes behavior. diff --git a/.gemini/skills/truthmark-check/support/report-template.md b/.gemini/skills/truthmark-check/support/report-template.md index 1dc6319..e98269e 100644 --- a/.gemini/skills/truthmark-check/support/report-template.md +++ b/.gemini/skills/truthmark-check/support/report-template.md @@ -1,6 +1,6 @@ # Truthmark Check Report Template -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Report completion in this shape: @@ -18,7 +18,7 @@ Fixes suggested: Evidence checked: - Finding: The root route index is present and maps repository truth owners. - Evidence: .truthmark/config.yml:1 / docs/truthmark/areas.md:1 + Evidence: docs/truthmark/areas.md:1 Suggested fix: none Confidence: high diff --git a/.gemini/skills/truthmark-check/support/subagents-and-leases.md b/.gemini/skills/truthmark-check/support/subagents-and-leases.md index 281ff2d..3a13df5 100644 --- a/.gemini/skills/truthmark-check/support/subagents-and-leases.md +++ b/.gemini/skills/truthmark-check/support/subagents-and-leases.md @@ -1,6 +1,6 @@ # Truthmark Check Subagents And Leases -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Gemini CLI subagent mode: - use automatically when this workflow runs in Gemini CLI and the parent agent chooses bounded project subagent fan-out diff --git a/.gemini/skills/truthmark-document/SKILL.md b/.gemini/skills/truthmark-document/SKILL.md index 7e2a59f..adfe24c 100644 --- a/.gemini/skills/truthmark-document/SKILL.md +++ b/.gemini/skills/truthmark-document/SKILL.md @@ -3,7 +3,7 @@ name: truthmark-document description: Use when the user asks to document existing implemented behavior, or Sync, Check, or Structure finds implemented behavior missing canonical truth. Not for functional-code changes, doc-first implementation, or topology repair that needs Structure. argument-hint: Optional implemented behavior, API endpoint, route, controller, package, or truth-doc area to document user-invocable: true -truthmark-version: 1.5.0 +truthmark-version: 1.6.0 --- # Truthmark Document @@ -16,8 +16,8 @@ Use as a Gemini CLI Agent Skill; commands remain available under `/truthmark:*` Invocations: OpenCode /skill truthmark-document; Codex /truthmark-document or $truthmark-document; Claude Code /truthmark-document; GitHub Copilot /truthmark-document; Gemini CLI /truthmark:document. Quick procedure: -- Follow docs/ai/repo-rules.md as the repository instruction authority. -- Read .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, existing canonical docs, implementation code, and tests directly. +- Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists. +- Inspect .truthmark/config.yml and configured route files (docs/truthmark/areas.md; docs/truthmark/areas/) only when they exist; then inspect existing canonical docs, implementation code, and tests directly. - Document current implemented behavior; do not invent future behavior. - May write canonical truth docs and truth routing files only; must not write functional code. - Read support/procedure.md before editing truth docs. diff --git a/.gemini/skills/truthmark-document/helper-manifest.yml b/.gemini/skills/truthmark-document/helper-manifest.yml index e53fa02..dc05fe5 100644 --- a/.gemini/skills/truthmark-document/helper-manifest.yml +++ b/.gemini/skills/truthmark-document/helper-manifest.yml @@ -1,8 +1,8 @@ -# Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +# Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. helpers: validate-document-report: optional: true - runner: truthmark>=1.5.0 + runner: truthmark>=1.6.0 command: argv: - truthmark @@ -17,7 +17,7 @@ helpers: fallback: manually validate support/report-template.md required sections and structured Evidence checked entries validate-write-lease: optional: true - runner: truthmark>=1.5.0 + runner: truthmark>=1.6.0 command: argv: - truthmark diff --git a/.gemini/skills/truthmark-document/support/helper-policy.md b/.gemini/skills/truthmark-document/support/helper-policy.md index 24a89d8..53b72b7 100644 --- a/.gemini/skills/truthmark-document/support/helper-policy.md +++ b/.gemini/skills/truthmark-document/support/helper-policy.md @@ -1,6 +1,6 @@ # Optional Helper CLI Policy -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Optional helper CLI commands may collect deterministic checkout facts or validate artifacts. If the Truthmark CLI is unavailable or too old for a declared helper, continue manually using this procedure and report which helper was skipped. Helper output is derived evidence; it does not override direct checkout inspection, workflow write boundaries, or parent acceptance. @@ -11,8 +11,8 @@ Runner detection: - Do not fail the workflow solely because a helper cannot run. Available helpers: -- validate-document-report: optional truthmark>=1.5.0; manual fallback: manually validate support/report-template.md required sections and structured Evidence checked entries -- validate-write-lease: optional truthmark>=1.5.0; manual fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files +- validate-document-report: optional truthmark>=1.6.0; manual fallback: manually validate support/report-template.md required sections and structured Evidence checked entries +- validate-write-lease: optional truthmark>=1.6.0; manual fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files Final reports should include helper status when helpers are declared for this workflow: diff --git a/.gemini/skills/truthmark-document/support/procedure.md b/.gemini/skills/truthmark-document/support/procedure.md index c0af75d..44d8eb3 100644 --- a/.gemini/skills/truthmark-document/support/procedure.md +++ b/.gemini/skills/truthmark-document/support/procedure.md @@ -1,6 +1,6 @@ # Truthmark Document Procedure -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. # Truthmark Document @@ -10,8 +10,8 @@ Invocations: OpenCode /skill truthmark-document; Codex /truthmark-document or $t Truth Document is manual and implementation-first: - run only when the user explicitly asks to generate or update truth docs for existing behavior, or when Truth Sync, Truth Check, or Truth Structure reports implemented behavior that lacks canonical truth docs -- inspect .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, existing canonical docs, implementation code, and tests directly -- Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +- inspect .truthmark/config.yml and configured route files only when they exist; then inspect existing canonical docs, implementation code, and tests directly +- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. - document current implemented behavior; do not invent future behavior or planned endpoints - may write canonical truth docs and docs/truthmark/areas.md or relevant child route files only @@ -43,7 +43,7 @@ Evidence Gate: - if no truth doc changed, report why current truth was already sufficient or why documentation was blocked Repository intelligence artifacts are optional derived context: RepoIndex, RouteMap, ImpactSet, and ContextPack may guide routing, context selection, and verification planning when available. They do not override checkout evidence, canonical truth docs, route files, or workflow write boundaries. -If unavailable, inspect .truthmark/config.yml, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated. +If unavailable, inspect any present Truthmark config, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated. When creating or updating a truth doc, inspect the routed truth kind and use the matching `docs/templates/-doc.md` template. Supported kinds: behavior, contract, architecture, workflow, operations, and test-behavior. Align existing docs to that template while preserving accurate authored content. @@ -58,11 +58,11 @@ Truth-doc shape repair gate: - report docs restructured and why a narrow edit was not sufficient Maintain architecture docs only for structure-level changes: system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership. Keep ordinary behavior, endpoints, UI copy, validation rules, and bug fixes in behavior or contract docs unless they change those boundaries. -Truthmark hierarchy: -- Config: .truthmark/config.yml -- Root route index: docs/truthmark/areas.md -- Area route files: docs/truthmark/areas/**/*.md -- Truth docs: docs/truth/**/*.md +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. Update Product Decisions and Rationale when a decision changes behavior. diff --git a/.gemini/skills/truthmark-document/support/report-template.md b/.gemini/skills/truthmark-document/support/report-template.md index 32cb1c3..22741ff 100644 --- a/.gemini/skills/truthmark-document/support/report-template.md +++ b/.gemini/skills/truthmark-document/support/report-template.md @@ -1,6 +1,6 @@ # Truthmark Document Report Template -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Report completion in this shape: ```md diff --git a/.gemini/skills/truthmark-document/support/subagents-and-leases.md b/.gemini/skills/truthmark-document/support/subagents-and-leases.md index f40575c..73c161c 100644 --- a/.gemini/skills/truthmark-document/support/subagents-and-leases.md +++ b/.gemini/skills/truthmark-document/support/subagents-and-leases.md @@ -1,6 +1,6 @@ # Truthmark Document Subagents And Leases -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Gemini CLI subagent mode: - use automatically when this workflow runs in Gemini CLI and the parent agent chooses bounded project subagent fan-out diff --git a/.gemini/skills/truthmark-preview/SKILL.md b/.gemini/skills/truthmark-preview/SKILL.md index 7007f1e..0bcf1cb 100644 --- a/.gemini/skills/truthmark-preview/SKILL.md +++ b/.gemini/skills/truthmark-preview/SKILL.md @@ -3,7 +3,7 @@ name: truthmark-preview description: Use when the user explicitly asks to preview likely workflow routing, target files, writes, or subagent use before edits. Not for validation, automatic gates, final correctness, or replacing Truth Check. argument-hint: Optional requested outcome, code area, doc path, or routing question user-invocable: true -truthmark-version: 1.5.0 +truthmark-version: 1.6.0 --- # Truthmark Preview @@ -16,8 +16,8 @@ Use as a Gemini CLI Agent Skill; commands remain available under `/truthmark:*` Invocations: OpenCode /skill truthmark-preview; Codex /truthmark-preview or $truthmark-preview; Claude Code /truthmark-preview; GitHub Copilot /truthmark-preview; Gemini CLI /truthmark:preview. Quick procedure: -- Follow docs/ai/repo-rules.md as the repository instruction authority. -- Read .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, and only the truth docs or implementation files needed to preview ownership. +- Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists. +- Inspect .truthmark/config.yml and configured route files (docs/truthmark/areas.md; docs/truthmark/areas/) only when they exist; then inspect only the truth docs or implementation files needed to preview ownership. - Truth Preview is read-only; this report is intended, not authorized. - must not edit files and must not issue write leases; do not run Truth Sync automatically, replace Truth Check, claim final correctness, or mutate code. - Use optional read-only route-auditor evidence only when it reduces context or clarifies ownership. diff --git a/.gemini/skills/truthmark-preview/support/procedure.md b/.gemini/skills/truthmark-preview/support/procedure.md index 14c4376..d419bf2 100644 --- a/.gemini/skills/truthmark-preview/support/procedure.md +++ b/.gemini/skills/truthmark-preview/support/procedure.md @@ -1,6 +1,6 @@ # Truthmark Preview Procedure -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Use this skill only when the user explicitly asks to preview Truthmark routing or workflow choice before edits. @@ -14,11 +14,11 @@ Purpose: - keep the selector thin so agents can avoid loading or acting through heavier workflows prematurely Read: -- .truthmark/config.yml -- docs/truthmark/areas.md -- relevant child route files under docs/truthmark/areas/ +- .truthmark/config.yml, only when present +- docs/truthmark/areas.md, only when present +- relevant child route files under docs/truthmark/areas/, only when present - relevant truth docs and implementation files needed to preview ownership -- Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. Do not: @@ -36,8 +36,8 @@ Suggested subagent use: - write workers: none - leases needed: none -Truthmark hierarchy: -- Config: .truthmark/config.yml -- Root route index: docs/truthmark/areas.md -- Area route files: docs/truthmark/areas/**/*.md -- Truth docs: docs/truth/**/*.md +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md diff --git a/.gemini/skills/truthmark-preview/support/report-template.md b/.gemini/skills/truthmark-preview/support/report-template.md index 345ba01..72cf72b 100644 --- a/.gemini/skills/truthmark-preview/support/report-template.md +++ b/.gemini/skills/truthmark-preview/support/report-template.md @@ -1,6 +1,6 @@ # Truthmark Preview Report Template -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Report completion in this shape: ```md diff --git a/.gemini/skills/truthmark-preview/support/subagents-and-leases.md b/.gemini/skills/truthmark-preview/support/subagents-and-leases.md index 04b64cf..411fa28 100644 --- a/.gemini/skills/truthmark-preview/support/subagents-and-leases.md +++ b/.gemini/skills/truthmark-preview/support/subagents-and-leases.md @@ -1,6 +1,6 @@ # Truthmark Preview Subagents And Leases -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Gemini CLI subagent mode: - use automatically when this workflow runs in Gemini CLI and the parent agent chooses bounded project subagent fan-out diff --git a/.gemini/skills/truthmark-realize/SKILL.md b/.gemini/skills/truthmark-realize/SKILL.md index e8dfbc3..41a7a43 100644 --- a/.gemini/skills/truthmark-realize/SKILL.md +++ b/.gemini/skills/truthmark-realize/SKILL.md @@ -3,7 +3,7 @@ name: truthmark-realize description: Use when the user explicitly asks to realize Truthmark truth docs into code, including /truthmark-realize, $truthmark-realize, or /truthmark:realize. Not for syncing docs after code changes, documenting existing code, topology repair, or truth audits. argument-hint: Optional truth doc path, area, or desired code behavior to realize user-invocable: true -truthmark-version: 1.5.0 +truthmark-version: 1.6.0 --- # Truthmark Realize @@ -16,8 +16,8 @@ Use as a Gemini CLI Agent Skill; commands remain available under `/truthmark:*` Invocations: OpenCode /skill truthmark-realize; Codex /truthmark-realize or $truthmark-realize; Claude Code /truthmark-realize; GitHub Copilot /truthmark-realize; Gemini CLI /truthmark:realize. Quick procedure: -- Follow docs/ai/repo-rules.md as the repository instruction authority. -- Read the source truth docs, .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files, tests, and relevant functional code directly. +- Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists. +- Read the source truth docs, inspect .truthmark/config.yml and configured route files (docs/truthmark/areas.md; docs/truthmark/areas/) only when they exist, then inspect tests and relevant functional code directly. - Truth docs lead; code follows. - may write functional code only; must not edit truth docs or truth routing while realizing those docs. - Read support/procedure.md before changing code. diff --git a/.gemini/skills/truthmark-realize/support/procedure.md b/.gemini/skills/truthmark-realize/support/procedure.md index ad9eacd..aa9883b 100644 --- a/.gemini/skills/truthmark-realize/support/procedure.md +++ b/.gemini/skills/truthmark-realize/support/procedure.md @@ -1,6 +1,6 @@ # Truthmark Realize Procedure -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. # Truthmark Realize @@ -16,9 +16,9 @@ Truth Realize is doc-first: Workflow: -1. Read the updated truth docs named by the user, or infer the relevant docs from docs/truthmark/areas.md. -2. Read .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files, tests, and the relevant functional code. -3. Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +1. Read the updated truth docs named by the user, or infer the relevant docs from configured route files when present. +2. Inspect .truthmark/config.yml and configured route files (docs/truthmark/areas.md; docs/truthmark/areas/) only when they exist; then read tests and the relevant functional code. +3. Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. Truth-doc ownership gate: - before editing or relying on source truth docs before writing code, verify each target/source truth doc is a bounded owner for the behavior @@ -29,11 +29,11 @@ Truth-doc ownership gate: 5. Do not edit truth docs or truth routing while realizing those docs. 6. Run relevant tests for the changed code. 7. Report changed code files and verification steps. -Truthmark hierarchy: -- Config: .truthmark/config.yml -- Root route index: docs/truthmark/areas.md -- Area route files: docs/truthmark/areas/**/*.md -- Truth docs: docs/truth/**/*.md +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md Read and write boundaries: diff --git a/.gemini/skills/truthmark-realize/support/report-template.md b/.gemini/skills/truthmark-realize/support/report-template.md index 9ca297b..e49dde5 100644 --- a/.gemini/skills/truthmark-realize/support/report-template.md +++ b/.gemini/skills/truthmark-realize/support/report-template.md @@ -1,6 +1,6 @@ # Truthmark Realize Report Template -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Report completion in this shape: diff --git a/.gemini/skills/truthmark-structure/SKILL.md b/.gemini/skills/truthmark-structure/SKILL.md index 666535a..59f926c 100644 --- a/.gemini/skills/truthmark-structure/SKILL.md +++ b/.gemini/skills/truthmark-structure/SKILL.md @@ -3,7 +3,7 @@ name: truthmark-structure description: Use when routing or truth ownership is missing, stale, broad, overloaded, catch-all, unrouteable, mixed-owner, needs split/repair, or needs new area setup. Not for documenting implemented behavior, syncing a code diff, or realizing docs into code. argument-hint: Optional area, directory, or routing concern user-invocable: true -truthmark-version: 1.5.0 +truthmark-version: 1.6.0 --- # Truthmark Structure @@ -16,8 +16,8 @@ Use as a Gemini CLI Agent Skill; commands remain available under `/truthmark:*` Invocations: OpenCode /skill truthmark-structure; Codex /truthmark-structure or $truthmark-structure; Claude Code /truthmark-structure; GitHub Copilot /truthmark-structure; Gemini CLI /truthmark:structure. Quick procedure: -- Follow docs/ai/repo-rules.md as the repository instruction authority. -- Read .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, current docs, and relevant code directly. +- Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists. +- Inspect .truthmark/config.yml and configured route files (docs/truthmark/areas.md; docs/truthmark/areas/) only when they exist; then inspect current docs and relevant code directly. - Define areas by product or behavior ownership, not by mechanical directory mirroring. - Do not edit functional code. - Read support/procedure.md before writing route or starter truth-doc changes. diff --git a/.gemini/skills/truthmark-structure/support/procedure.md b/.gemini/skills/truthmark-structure/support/procedure.md index 8315ea1..9104b33 100644 --- a/.gemini/skills/truthmark-structure/support/procedure.md +++ b/.gemini/skills/truthmark-structure/support/procedure.md @@ -1,14 +1,14 @@ # Truthmark Structure Procedure -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Use this skill to design or repair Truthmark area structure. Invocations: OpenCode /skill truthmark-structure; Codex /truthmark-structure or $truthmark-structure; Claude Code /truthmark-structure; GitHub Copilot /truthmark-structure; Gemini CLI /truthmark:structure. Truth Structure is agent-native: -- inspect repository layout, current docs, .truthmark/config.yml, docs/truthmark/areas.md, and relevant code directly -- Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +- inspect repository layout, current docs, Truthmark config and route files when present, and relevant code directly +- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. -- inspect the configured root route index at docs/truthmark/areas.md and relevant child route files under docs/truthmark/areas/ +- inspect the configured root route index at docs/truthmark/areas.md and relevant child route files under docs/truthmark/areas/ when they exist - define areas by product or behavior ownership, not by mechanical directory mirroring - create or repair docs/truthmark/areas.md - create starter truth docs when useful and when they belong in the canonical current-truth surface @@ -97,13 +97,13 @@ Keep ordinary behavior, endpoints, UI copy, validation rules, and bug fixes in b Portable fallback: - If this skill surface is unavailable, perform the same workflow directly from committed repository files. - Do not require the truthmark CLI. -- Read .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, canonical docs, and representative implementation code. +- Inspect .truthmark/config.yml and configured route files only when they exist; then inspect canonical docs and representative implementation code. - Use a subagent only when the host supports that pattern; otherwise perform the topology repair inline. -Truthmark hierarchy: -- Config: .truthmark/config.yml -- Root route index: docs/truthmark/areas.md -- Area route files: docs/truthmark/areas/**/*.md -- Truth docs: docs/truth/**/*.md +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. Update Product Decisions and Rationale when a decision changes behavior. diff --git a/.gemini/skills/truthmark-structure/support/report-template.md b/.gemini/skills/truthmark-structure/support/report-template.md index 75b6b1f..c104da3 100644 --- a/.gemini/skills/truthmark-structure/support/report-template.md +++ b/.gemini/skills/truthmark-structure/support/report-template.md @@ -1,6 +1,6 @@ # Truthmark Structure Report Template -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Report completion in this shape: ```md diff --git a/.gemini/skills/truthmark-structure/support/subagents-and-leases.md b/.gemini/skills/truthmark-structure/support/subagents-and-leases.md index 7ead3e8..eef3b0b 100644 --- a/.gemini/skills/truthmark-structure/support/subagents-and-leases.md +++ b/.gemini/skills/truthmark-structure/support/subagents-and-leases.md @@ -1,6 +1,6 @@ # Truthmark Structure Subagents And Leases -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Gemini CLI subagent mode: - use automatically when this workflow runs in Gemini CLI and the parent agent chooses bounded project subagent fan-out diff --git a/.gemini/skills/truthmark-sync/SKILL.md b/.gemini/skills/truthmark-sync/SKILL.md index 6a0b11d..e6b801d 100644 --- a/.gemini/skills/truthmark-sync/SKILL.md +++ b/.gemini/skills/truthmark-sync/SKILL.md @@ -3,7 +3,7 @@ name: truthmark-sync description: Use automatically at finish-time after functional code changes, or explicit /truthmark-sync, $truthmark-sync, or /truthmark:sync. Skip docs-only, formatting-only, behavior-preserving renames, missing config, and no-code changes. Not for doc-first realization or manual topology design. argument-hint: Optional changed-code area, truth-doc area, or sync focus user-invocable: true -truthmark-version: 1.5.0 +truthmark-version: 1.6.0 --- # Truthmark Sync @@ -16,9 +16,9 @@ Use as a Gemini CLI Agent Skill; commands remain available under `/truthmark:*` Invocations: OpenCode /skill truthmark-sync; Codex /truthmark-sync or $truthmark-sync; Claude Code /truthmark-sync; GitHub Copilot /truthmark-sync; Gemini CLI /truthmark:sync. Quick procedure: -- Follow docs/ai/repo-rules.md as the repository instruction authority. +- Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists. - Skip docs-only, formatting-only, behavior-preserving renames with no truth impact, missing config, and no-code changes. -- Read .truthmark/config.yml, the configured root route index at docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, and relevant canonical docs. +- Inspect .truthmark/config.yml and configured route files (docs/truthmark/areas.md; docs/truthmark/areas/) only when they exist; then inspect relevant canonical docs directly. - direct checkout inspection is the canonical path; do not require the truthmark binary. - May write canonical truth docs and truth routing files only; must not rewrite functional code. - Read support/procedure.md before editing truth docs. diff --git a/.gemini/skills/truthmark-sync/helper-manifest.yml b/.gemini/skills/truthmark-sync/helper-manifest.yml index 663eeef..ce58751 100644 --- a/.gemini/skills/truthmark-sync/helper-manifest.yml +++ b/.gemini/skills/truthmark-sync/helper-manifest.yml @@ -1,8 +1,8 @@ -# Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +# Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. helpers: validate-sync-report: optional: true - runner: truthmark>=1.5.0 + runner: truthmark>=1.6.0 command: argv: - truthmark @@ -17,7 +17,7 @@ helpers: fallback: "manually validate support/report-template.md and check Evidence checked entries match Claim, indented Evidence, and Result: supported | narrowed | removed | blocked" validate-write-lease: optional: true - runner: truthmark>=1.5.0 + runner: truthmark>=1.6.0 command: argv: - truthmark diff --git a/.gemini/skills/truthmark-sync/support/helper-policy.md b/.gemini/skills/truthmark-sync/support/helper-policy.md index e7d086f..c3d00c7 100644 --- a/.gemini/skills/truthmark-sync/support/helper-policy.md +++ b/.gemini/skills/truthmark-sync/support/helper-policy.md @@ -1,6 +1,6 @@ # Optional Helper CLI Policy -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Optional helper CLI commands may collect deterministic checkout facts or validate artifacts. If the Truthmark CLI is unavailable or too old for a declared helper, continue manually using this procedure and report which helper was skipped. Helper output is derived evidence; it does not override direct checkout inspection, workflow write boundaries, or parent acceptance. @@ -11,8 +11,8 @@ Runner detection: - Do not fail the workflow solely because a helper cannot run. Available helpers: -- validate-sync-report: optional truthmark>=1.5.0; manual fallback: manually validate support/report-template.md and check Evidence checked entries match Claim, indented Evidence, and Result: supported | narrowed | removed | blocked -- validate-write-lease: optional truthmark>=1.5.0; manual fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files +- validate-sync-report: optional truthmark>=1.6.0; manual fallback: manually validate support/report-template.md and check Evidence checked entries match Claim, indented Evidence, and Result: supported | narrowed | removed | blocked +- validate-write-lease: optional truthmark>=1.6.0; manual fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files Final reports should include helper status when helpers are declared for this workflow: diff --git a/.gemini/skills/truthmark-sync/support/procedure.md b/.gemini/skills/truthmark-sync/support/procedure.md index 22da116..a80e050 100644 --- a/.gemini/skills/truthmark-sync/support/procedure.md +++ b/.gemini/skills/truthmark-sync/support/procedure.md @@ -1,6 +1,6 @@ # Truthmark Sync Procedure -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Use this skill automatically before finishing when functional code changed since the last successful Truth Sync. Also run it immediately when the user explicitly invokes Truth Sync. Invocations: OpenCode /skill truthmark-sync; Codex /truthmark-sync or $truthmark-sync; Claude Code /truthmark-sync; GitHub Copilot /truthmark-sync; Gemini CLI /truthmark:sync. @@ -8,9 +8,9 @@ Explicit invocation runs immediately. Later functional-code changes reopen the f Skip when changes are documentation-only, formatting-only, clearly behavior-preserving renames with no truth impact, when no Truthmark config exists yet, or when there are no functional code changes. Parent workflow: 1. Inspect git status, staged changes, unstaged changes, and untracked files directly. -2. Read .truthmark/config.yml, the configured root route index at docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, and relevant canonical docs. +2. Inspect .truthmark/config.yml and configured route files only when they exist; then inspect relevant canonical docs. 3. Identify functional-code changes and the nearest truth docs or routing repairs. -4. Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +4. Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. 5. Code verification is parent-owned: follow repository instructions and task context, and report what ran or why it did not run. 6. Dispatch bounded Truth Sync workers only when the host supports subagent dispatch and the acting agent chooses that path; otherwise execute the same sync task inline. @@ -57,7 +57,7 @@ Evidence Gate: - if no impacted doc changed, report why truth was already current or why sync was skipped Repository intelligence artifacts are optional derived context: RepoIndex, RouteMap, ImpactSet, and ContextPack may guide routing, context selection, and verification planning when available. They do not override checkout evidence, canonical truth docs, route files, or workflow write boundaries. -If unavailable, inspect .truthmark/config.yml, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated. +If unavailable, inspect any present Truthmark config, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated. Optional validation tooling: - you may run truthmark check when local tooling is available - do not require the truthmark binary; direct checkout inspection is the canonical path @@ -69,11 +69,11 @@ Helper status reporting: - If the installed Truthmark CLI is unavailable or the helper is skipped, record `validate-sync-report: skipped, ` and manually validate the report shape. - Record `validate-write-lease: ran, passed` only after validating a concrete write lease; otherwise use a truthful skipped status such as `skipped, no write lease used`. - Helper output is derived evidence and never replaces direct checkout inspection, evidence review, or parent acceptance. -Truthmark hierarchy: -- Config: .truthmark/config.yml -- Root route index: docs/truthmark/areas.md -- Area route files: docs/truthmark/areas/**/*.md -- Truth docs: docs/truth/**/*.md +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. Update Product Decisions and Rationale when a decision changes behavior. diff --git a/.gemini/skills/truthmark-sync/support/report-template.md b/.gemini/skills/truthmark-sync/support/report-template.md index 5cd2313..9bce186 100644 --- a/.gemini/skills/truthmark-sync/support/report-template.md +++ b/.gemini/skills/truthmark-sync/support/report-template.md @@ -1,6 +1,6 @@ # Truthmark Sync Report Template -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Report completion in this shape: ```md diff --git a/.gemini/skills/truthmark-sync/support/subagents-and-leases.md b/.gemini/skills/truthmark-sync/support/subagents-and-leases.md index 36495dc..5ad280c 100644 --- a/.gemini/skills/truthmark-sync/support/subagents-and-leases.md +++ b/.gemini/skills/truthmark-sync/support/subagents-and-leases.md @@ -1,6 +1,6 @@ # Truthmark Sync Subagents And Leases -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Gemini CLI subagent mode: - use automatically when this workflow runs in Gemini CLI and the parent agent chooses bounded project subagent fan-out diff --git a/.github/agents/truth-claim-verifier.agent.md b/.github/agents/truth-claim-verifier.agent.md index 2edf242..0b026ff 100644 --- a/.github/agents/truth-claim-verifier.agent.md +++ b/.github/agents/truth-claim-verifier.agent.md @@ -4,7 +4,7 @@ description: Read-only Truthmark claim verifier for checking canonical truth aga tools: [read, search] --- -# Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +# Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Stay read-only. Verify the behavior-bearing truth claims assigned by the parent against primary checkout evidence. diff --git a/.github/agents/truth-doc-reviewer.agent.md b/.github/agents/truth-doc-reviewer.agent.md index 98bd82b..97e5c9e 100644 --- a/.github/agents/truth-doc-reviewer.agent.md +++ b/.github/agents/truth-doc-reviewer.agent.md @@ -4,7 +4,7 @@ description: Read-only Truthmark doc reviewer for shape, decision, rationale, an tools: [read, search] --- -# Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +# Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Stay read-only. Review assigned canonical truth docs for frontmatter, source_of_truth, required template sections, Evidence checked entries, Product Decisions, and Rationale. diff --git a/.github/agents/truth-doc-writer.agent.md b/.github/agents/truth-doc-writer.agent.md index 2049d0e..29352a9 100644 --- a/.github/agents/truth-doc-writer.agent.md +++ b/.github/agents/truth-doc-writer.agent.md @@ -4,7 +4,7 @@ description: Write-capable Truthmark doc worker for one parent-leased truth-docu tools: [read, search, edit] --- -# Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +# Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Write one leased Truthmark truth-document shard assigned by the parent. Require an explicit write lease before editing. The lease must name workflow, worker, shard, objective, requiredReads, allowedWrites, forbiddenWrites, evidenceRequired, verification, and reportFields. diff --git a/.github/agents/truth-route-auditor.agent.md b/.github/agents/truth-route-auditor.agent.md index 22b4064..28e45ab 100644 --- a/.github/agents/truth-route-auditor.agent.md +++ b/.github/agents/truth-route-auditor.agent.md @@ -4,11 +4,11 @@ description: Read-only Truthmark route auditor for bounded routing and ownership tools: [read, search] --- -# Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +# Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Stay read-only. Audit one bounded Truthmark route, area, or doc shard assigned by the parent. -Read .truthmark/config.yml, the root route index, relevant child route files, mapped truth docs, and relevant implementation files directly. +Inspect .truthmark/config.yml and route files only when they exist; then inspect mapped truth docs and relevant implementation files directly. Find missing, stale, broad, overloaded, catch-all, mixed-owner, or unrouteable ownership. Do not edit files, stage changes, or propose broad rewrites. Return JSON only with keys: scope, filesReviewed, findings, evidence, confidence, recommendedWorkflow, notes. diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 8608a6c..78b7068 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,16 +1,16 @@ -Follow `docs/ai/repo-rules.md`. +Follow repository instruction files that are present in this checkout; do not assume optional policy docs exist. -Use that file as the primary repository instruction source for this agent. +Use explicitly configured repository policy docs only when they exist in this checkout. Agent-specific: -- Read `docs/README.md` only when choosing or updating canonical docs. -- Use `docs/ai/agent-onboarding.md` only when task routing is unclear or cross-area. +- Read the configured Truthmark routing files when choosing or updating canonical docs. +- Use repository onboarding or docs-map files only when present and needed for unclear or cross-area routing. ## Truthmark Workflow -Generated by Truthmark 1.5.0. Rerun `truthmark init` after upgrades. -Hierarchy: config .truthmark/config.yml; routes docs/truthmark/areas.md and docs/truthmark/areas/**/*.md; Truth docs: docs/truth/**/*.md. +Generated by Truthmark 1.6.0. Rerun `truthmark init` after upgrades. +Hierarchy hints: config .truthmark/config.yml when present; routes docs/truthmark/areas.md and docs/truthmark/areas/**/*.md when present; Truth docs: docs/truth/**/*.md when present. Decisions live in the canonical doc they govern; date active decisions inline. Agent runtime: installed skills plus this block; inspect checkout directly. Delegation is host-owned. ### Truth Sync diff --git a/.github/prompts/truthmark-check.prompt.md b/.github/prompts/truthmark-check.prompt.md index 7b5ce45..7d32da3 100644 --- a/.github/prompts/truthmark-check.prompt.md +++ b/.github/prompts/truthmark-check.prompt.md @@ -8,7 +8,7 @@ name: truthmark-check description: Use when the user asks to audit repository truth health, routing, ownership, or canonical docs. Not for normal lint/test/typecheck/code-review verification, finish-time Sync, or silently rewriting docs. argument-hint: Optional area, doc path, or audit focus user-invocable: true -truthmark-version: 1.5.0 +truthmark-version: 1.6.0 --- # Truthmark Check @@ -19,12 +19,12 @@ Invocations: OpenCode /skill truthmark-check; Codex /truthmark-check or $truthma Truth Check is agent-led: -- inspect .truthmark/config.yml, docs/truthmark/areas.md, canonical docs, and relevant implementation directly -- Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +- inspect .truthmark/config.yml and configured route files only when they exist; then inspect canonical docs and relevant implementation directly +- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. -- inspect the configured root route index at docs/truthmark/areas.md and relevant child route files under docs/truthmark/areas/ +- inspect the configured root route index at docs/truthmark/areas.md and relevant child route files under docs/truthmark/areas/ when they exist - check that current docs describe current code rather than historical plans -- check that docs/truthmark/areas.md routes code surfaces to canonical truth docs +- check that route files map code surfaces to canonical truth docs when route files exist - check for broad, catch-all, index-like, or mixed-owner truth docs and report them as topology issues requiring Truth Structure - check that canonical behavior docs keep active Product Decisions and Rationale sections - optionally run truthmark check when local tooling is available @@ -43,11 +43,11 @@ Copilot custom-agent mode: - parent supplies bounded evidence shards; custom agents must not preload host instruction files or repo-wide policy docs unless assigned as evidence - Parent agent owns the final Truth Check report -Truthmark hierarchy: -- Config: .truthmark/config.yml -- Root route index: docs/truthmark/areas.md -- Area route files: docs/truthmark/areas/**/*.md -- Truth docs: docs/truth/**/*.md +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. Update Product Decisions and Rationale when a decision changes behavior. @@ -68,7 +68,7 @@ Fixes suggested: Evidence checked: - Finding: The root route index is present and maps repository truth owners. - Evidence: .truthmark/config.yml:1 / docs/truthmark/areas.md:1 + Evidence: docs/truthmark/areas.md:1 Suggested fix: none Confidence: high diff --git a/.github/prompts/truthmark-document.prompt.md b/.github/prompts/truthmark-document.prompt.md index b383903..d2946cd 100644 --- a/.github/prompts/truthmark-document.prompt.md +++ b/.github/prompts/truthmark-document.prompt.md @@ -8,7 +8,7 @@ name: truthmark-document description: Use when the user asks to document existing implemented behavior, or Sync, Check, or Structure finds implemented behavior missing canonical truth. Not for functional-code changes, doc-first implementation, or topology repair that needs Structure. argument-hint: Optional implemented behavior, API endpoint, route, controller, package, or truth-doc area to document user-invocable: true -truthmark-version: 1.5.0 +truthmark-version: 1.6.0 --- # Truthmark Document @@ -19,8 +19,8 @@ Invocations: OpenCode /skill truthmark-document; Codex /truthmark-document or $t Truth Document is manual and implementation-first: - run only when the user explicitly asks to generate or update truth docs for existing behavior, or when Truth Sync, Truth Check, or Truth Structure reports implemented behavior that lacks canonical truth docs -- inspect .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, existing canonical docs, implementation code, and tests directly -- Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +- inspect .truthmark/config.yml and configured route files only when they exist; then inspect existing canonical docs, implementation code, and tests directly +- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. - document current implemented behavior; do not invent future behavior or planned endpoints - may write canonical truth docs and docs/truthmark/areas.md or relevant child route files only @@ -62,7 +62,7 @@ Copilot custom-agent mode: - Parent agent owns Truth Document acceptance, lease validation, and final report Repository intelligence artifacts are optional derived context: RepoIndex, RouteMap, ImpactSet, and ContextPack may guide routing, context selection, and verification planning when available. They do not override checkout evidence, canonical truth docs, route files, or workflow write boundaries. -If unavailable, inspect .truthmark/config.yml, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated. +If unavailable, inspect any present Truthmark config, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated. When creating or updating a truth doc, inspect the routed truth kind and use the matching `docs/templates/-doc.md` template. Supported kinds: behavior, contract, architecture, workflow, operations, and test-behavior. Align existing docs to that template while preserving accurate authored content. @@ -77,11 +77,11 @@ Truth-doc shape repair gate: - report docs restructured and why a narrow edit was not sufficient Maintain architecture docs only for structure-level changes: system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership. Keep ordinary behavior, endpoints, UI copy, validation rules, and bug fixes in behavior or contract docs unless they change those boundaries. -Truthmark hierarchy: -- Config: .truthmark/config.yml -- Root route index: docs/truthmark/areas.md -- Area route files: docs/truthmark/areas/**/*.md -- Truth docs: docs/truth/**/*.md +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. Update Product Decisions and Rationale when a decision changes behavior. diff --git a/.github/prompts/truthmark-preview.prompt.md b/.github/prompts/truthmark-preview.prompt.md index 3b31a62..55da8ca 100644 --- a/.github/prompts/truthmark-preview.prompt.md +++ b/.github/prompts/truthmark-preview.prompt.md @@ -8,7 +8,7 @@ name: truthmark-preview description: Use when the user explicitly asks to preview likely workflow routing, target files, writes, or subagent use before edits. Not for validation, automatic gates, final correctness, or replacing Truth Check. argument-hint: Optional requested outcome, code area, doc path, or routing question user-invocable: true -truthmark-version: 1.5.0 +truthmark-version: 1.6.0 --- Use this skill only when the user explicitly asks to preview Truthmark routing or workflow choice before edits. @@ -23,11 +23,11 @@ Purpose: - keep the selector thin so agents can avoid loading or acting through heavier workflows prematurely Read: -- .truthmark/config.yml -- docs/truthmark/areas.md -- relevant child route files under docs/truthmark/areas/ +- .truthmark/config.yml, only when present +- docs/truthmark/areas.md, only when present +- relevant child route files under docs/truthmark/areas/, only when present - relevant truth docs and implementation files needed to preview ownership -- Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. Do not: @@ -45,11 +45,11 @@ Suggested subagent use: - write workers: none - leases needed: none -Truthmark hierarchy: -- Config: .truthmark/config.yml -- Root route index: docs/truthmark/areas.md -- Area route files: docs/truthmark/areas/**/*.md -- Truth docs: docs/truth/**/*.md +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md Report completion in this shape: ```md diff --git a/.github/prompts/truthmark-realize.prompt.md b/.github/prompts/truthmark-realize.prompt.md index aa56cfd..ae768d6 100644 --- a/.github/prompts/truthmark-realize.prompt.md +++ b/.github/prompts/truthmark-realize.prompt.md @@ -8,7 +8,7 @@ name: truthmark-realize description: Use when the user explicitly asks to realize Truthmark truth docs into code, including /truthmark-realize, $truthmark-realize, or /truthmark:realize. Not for syncing docs after code changes, documenting existing code, topology repair, or truth audits. argument-hint: Optional truth doc path, area, or desired code behavior to realize user-invocable: true -truthmark-version: 1.5.0 +truthmark-version: 1.6.0 --- # Truthmark Realize @@ -25,9 +25,9 @@ Truth Realize is doc-first: Workflow: -1. Read the updated truth docs named by the user, or infer the relevant docs from docs/truthmark/areas.md. -2. Read .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files, tests, and the relevant functional code. -3. Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +1. Read the updated truth docs named by the user, or infer the relevant docs from configured route files when present. +2. Inspect .truthmark/config.yml and configured route files (docs/truthmark/areas.md; docs/truthmark/areas/) only when they exist; then read tests and the relevant functional code. +3. Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. Truth-doc ownership gate: - before editing or relying on source truth docs before writing code, verify each target/source truth doc is a bounded owner for the behavior @@ -38,11 +38,11 @@ Truth-doc ownership gate: 5. Do not edit truth docs or truth routing while realizing those docs. 6. Run relevant tests for the changed code. 7. Report changed code files and verification steps. -Truthmark hierarchy: -- Config: .truthmark/config.yml -- Root route index: docs/truthmark/areas.md -- Area route files: docs/truthmark/areas/**/*.md -- Truth docs: docs/truth/**/*.md +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md Read and write boundaries: diff --git a/.github/prompts/truthmark-structure.prompt.md b/.github/prompts/truthmark-structure.prompt.md index 18cdf74..487eea8 100644 --- a/.github/prompts/truthmark-structure.prompt.md +++ b/.github/prompts/truthmark-structure.prompt.md @@ -8,16 +8,16 @@ name: truthmark-structure description: Use when routing or truth ownership is missing, stale, broad, overloaded, catch-all, unrouteable, mixed-owner, needs split/repair, or needs new area setup. Not for documenting implemented behavior, syncing a code diff, or realizing docs into code. argument-hint: Optional area, directory, or routing concern user-invocable: true -truthmark-version: 1.5.0 +truthmark-version: 1.6.0 --- Use this skill to design or repair Truthmark area structure. Invocations: OpenCode /skill truthmark-structure; Codex /truthmark-structure or $truthmark-structure; Claude Code /truthmark-structure; GitHub Copilot /truthmark-structure; Gemini CLI /truthmark:structure. Truth Structure is agent-native: -- inspect repository layout, current docs, .truthmark/config.yml, docs/truthmark/areas.md, and relevant code directly -- Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +- inspect repository layout, current docs, Truthmark config and route files when present, and relevant code directly +- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. -- inspect the configured root route index at docs/truthmark/areas.md and relevant child route files under docs/truthmark/areas/ +- inspect the configured root route index at docs/truthmark/areas.md and relevant child route files under docs/truthmark/areas/ when they exist - define areas by product or behavior ownership, not by mechanical directory mirroring - create or repair docs/truthmark/areas.md - create starter truth docs when useful and when they belong in the canonical current-truth surface @@ -112,13 +112,13 @@ Keep ordinary behavior, endpoints, UI copy, validation rules, and bug fixes in b Portable fallback: - If this skill surface is unavailable, perform the same workflow directly from committed repository files. - Do not require the truthmark CLI. -- Read .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, canonical docs, and representative implementation code. +- Inspect .truthmark/config.yml and configured route files only when they exist; then inspect canonical docs and representative implementation code. - Use a subagent only when the host supports that pattern; otherwise perform the topology repair inline. -Truthmark hierarchy: -- Config: .truthmark/config.yml -- Root route index: docs/truthmark/areas.md -- Area route files: docs/truthmark/areas/**/*.md -- Truth docs: docs/truth/**/*.md +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. Update Product Decisions and Rationale when a decision changes behavior. diff --git a/.github/prompts/truthmark-sync.prompt.md b/.github/prompts/truthmark-sync.prompt.md index badba1c..5bb83aa 100644 --- a/.github/prompts/truthmark-sync.prompt.md +++ b/.github/prompts/truthmark-sync.prompt.md @@ -8,7 +8,7 @@ name: truthmark-sync description: Use automatically at finish-time after functional code changes, or explicit /truthmark-sync, $truthmark-sync, or /truthmark:sync. Skip docs-only, formatting-only, behavior-preserving renames, missing config, and no-code changes. Not for doc-first realization or manual topology design. argument-hint: Optional changed-code area, truth-doc area, or sync focus user-invocable: true -truthmark-version: 1.5.0 +truthmark-version: 1.6.0 --- Use this skill automatically before finishing when functional code changed since the last successful Truth Sync. Also run it immediately when the user explicitly invokes Truth Sync. @@ -17,9 +17,9 @@ Explicit invocation runs immediately. Later functional-code changes reopen the f Skip when changes are documentation-only, formatting-only, clearly behavior-preserving renames with no truth impact, when no Truthmark config exists yet, or when there are no functional code changes. Parent workflow: 1. Inspect git status, staged changes, unstaged changes, and untracked files directly. -2. Read .truthmark/config.yml, the configured root route index at docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, and relevant canonical docs. +2. Inspect .truthmark/config.yml and configured route files only when they exist; then inspect relevant canonical docs. 3. Identify functional-code changes and the nearest truth docs or routing repairs. -4. Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +4. Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. 5. Code verification is parent-owned: follow repository instructions and task context, and report what ran or why it did not run. 6. Dispatch bounded Truth Sync workers only when the host supports subagent dispatch and the acting agent chooses that path; otherwise execute the same sync task inline. @@ -76,7 +76,7 @@ Evidence Gate: - if no impacted doc changed, report why truth was already current or why sync was skipped Repository intelligence artifacts are optional derived context: RepoIndex, RouteMap, ImpactSet, and ContextPack may guide routing, context selection, and verification planning when available. They do not override checkout evidence, canonical truth docs, route files, or workflow write boundaries. -If unavailable, inspect .truthmark/config.yml, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated. +If unavailable, inspect any present Truthmark config, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated. Optional validation tooling: - you may run truthmark check when local tooling is available - do not require the truthmark binary; direct checkout inspection is the canonical path @@ -88,11 +88,11 @@ Helper status reporting: - If the installed Truthmark CLI is unavailable or the helper is skipped, record `validate-sync-report: skipped, ` and manually validate the report shape. - Record `validate-write-lease: ran, passed` only after validating a concrete write lease; otherwise use a truthful skipped status such as `skipped, no write lease used`. - Helper output is derived evidence and never replaces direct checkout inspection, evidence review, or parent acceptance. -Truthmark hierarchy: -- Config: .truthmark/config.yml -- Root route index: docs/truthmark/areas.md -- Area route files: docs/truthmark/areas/**/*.md -- Truth docs: docs/truth/**/*.md +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. Update Product Decisions and Rationale when a decision changes behavior. diff --git a/.github/skills/truthmark-check/SKILL.md b/.github/skills/truthmark-check/SKILL.md index e2dc7c1..67d1482 100644 --- a/.github/skills/truthmark-check/SKILL.md +++ b/.github/skills/truthmark-check/SKILL.md @@ -3,7 +3,7 @@ name: truthmark-check description: Use when the user asks to audit repository truth health, routing, ownership, or canonical docs. Not for normal lint/test/typecheck/code-review verification, finish-time Sync, or silently rewriting docs. argument-hint: Optional area, doc path, or audit focus user-invocable: true -truthmark-version: 1.5.0 +truthmark-version: 1.6.0 --- # Truthmark Check @@ -16,8 +16,8 @@ Use as a Copilot agent skill. Prompt files remain available under `.github/promp Invocations: OpenCode /skill truthmark-check; Codex /truthmark-check or $truthmark-check; Claude Code /truthmark-check; GitHub Copilot /truthmark-check; Gemini CLI /truthmark:check. Quick procedure: -- Follow docs/ai/repo-rules.md as the repository instruction authority. -- Read .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, canonical docs, and relevant implementation directly. +- Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists. +- Inspect .truthmark/config.yml and configured route files (docs/truthmark/areas.md; docs/truthmark/areas/) only when they exist; then inspect canonical docs and relevant implementation directly. - Report issues and suggested fixes; do not silently rewrite unrelated files. - Direct checkout inspection is valid even when local tooling is unavailable. - Read support/procedure.md before auditing details. diff --git a/.github/skills/truthmark-check/support/procedure.md b/.github/skills/truthmark-check/support/procedure.md index 82239d8..33b7663 100644 --- a/.github/skills/truthmark-check/support/procedure.md +++ b/.github/skills/truthmark-check/support/procedure.md @@ -1,6 +1,6 @@ # Truthmark Check Procedure -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. # Truthmark Check @@ -10,12 +10,12 @@ Invocations: OpenCode /skill truthmark-check; Codex /truthmark-check or $truthma Truth Check is agent-led: -- inspect .truthmark/config.yml, docs/truthmark/areas.md, canonical docs, and relevant implementation directly -- Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +- inspect .truthmark/config.yml and configured route files only when they exist; then inspect canonical docs and relevant implementation directly +- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. -- inspect the configured root route index at docs/truthmark/areas.md and relevant child route files under docs/truthmark/areas/ +- inspect the configured root route index at docs/truthmark/areas.md and relevant child route files under docs/truthmark/areas/ when they exist - check that current docs describe current code rather than historical plans -- check that docs/truthmark/areas.md routes code surfaces to canonical truth docs +- check that route files map code surfaces to canonical truth docs when route files exist - check for broad, catch-all, index-like, or mixed-owner truth docs and report them as topology issues requiring Truth Structure - check that canonical behavior docs keep active Product Decisions and Rationale sections - optionally run truthmark check when local tooling is available @@ -27,11 +27,11 @@ Evidence Gate: - canonical docs are context, not sole proof when implementation conflicts - remove unsupported findings or mark open questions; validate changed claims if you edit docs -Truthmark hierarchy: -- Config: .truthmark/config.yml -- Root route index: docs/truthmark/areas.md -- Area route files: docs/truthmark/areas/**/*.md -- Truth docs: docs/truth/**/*.md +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. Update Product Decisions and Rationale when a decision changes behavior. diff --git a/.github/skills/truthmark-check/support/report-template.md b/.github/skills/truthmark-check/support/report-template.md index 1dc6319..e98269e 100644 --- a/.github/skills/truthmark-check/support/report-template.md +++ b/.github/skills/truthmark-check/support/report-template.md @@ -1,6 +1,6 @@ # Truthmark Check Report Template -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Report completion in this shape: @@ -18,7 +18,7 @@ Fixes suggested: Evidence checked: - Finding: The root route index is present and maps repository truth owners. - Evidence: .truthmark/config.yml:1 / docs/truthmark/areas.md:1 + Evidence: docs/truthmark/areas.md:1 Suggested fix: none Confidence: high diff --git a/.github/skills/truthmark-check/support/subagents-and-leases.md b/.github/skills/truthmark-check/support/subagents-and-leases.md index 512ddcc..a6522ec 100644 --- a/.github/skills/truthmark-check/support/subagents-and-leases.md +++ b/.github/skills/truthmark-check/support/subagents-and-leases.md @@ -1,6 +1,6 @@ # Truthmark Check Subagents And Leases -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Copilot custom-agent mode: - use automatically when this workflow runs in Copilot and the parent agent chooses bounded custom-agent fan-out diff --git a/.github/skills/truthmark-document/SKILL.md b/.github/skills/truthmark-document/SKILL.md index 5b746ef..e1f4285 100644 --- a/.github/skills/truthmark-document/SKILL.md +++ b/.github/skills/truthmark-document/SKILL.md @@ -3,7 +3,7 @@ name: truthmark-document description: Use when the user asks to document existing implemented behavior, or Sync, Check, or Structure finds implemented behavior missing canonical truth. Not for functional-code changes, doc-first implementation, or topology repair that needs Structure. argument-hint: Optional implemented behavior, API endpoint, route, controller, package, or truth-doc area to document user-invocable: true -truthmark-version: 1.5.0 +truthmark-version: 1.6.0 --- # Truthmark Document @@ -16,8 +16,8 @@ Use as a Copilot agent skill. Prompt files remain available under `.github/promp Invocations: OpenCode /skill truthmark-document; Codex /truthmark-document or $truthmark-document; Claude Code /truthmark-document; GitHub Copilot /truthmark-document; Gemini CLI /truthmark:document. Quick procedure: -- Follow docs/ai/repo-rules.md as the repository instruction authority. -- Read .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, existing canonical docs, implementation code, and tests directly. +- Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists. +- Inspect .truthmark/config.yml and configured route files (docs/truthmark/areas.md; docs/truthmark/areas/) only when they exist; then inspect existing canonical docs, implementation code, and tests directly. - Document current implemented behavior; do not invent future behavior. - May write canonical truth docs and truth routing files only; must not write functional code. - Read support/procedure.md before editing truth docs. diff --git a/.github/skills/truthmark-document/helper-manifest.yml b/.github/skills/truthmark-document/helper-manifest.yml index e53fa02..dc05fe5 100644 --- a/.github/skills/truthmark-document/helper-manifest.yml +++ b/.github/skills/truthmark-document/helper-manifest.yml @@ -1,8 +1,8 @@ -# Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +# Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. helpers: validate-document-report: optional: true - runner: truthmark>=1.5.0 + runner: truthmark>=1.6.0 command: argv: - truthmark @@ -17,7 +17,7 @@ helpers: fallback: manually validate support/report-template.md required sections and structured Evidence checked entries validate-write-lease: optional: true - runner: truthmark>=1.5.0 + runner: truthmark>=1.6.0 command: argv: - truthmark diff --git a/.github/skills/truthmark-document/support/helper-policy.md b/.github/skills/truthmark-document/support/helper-policy.md index 24a89d8..53b72b7 100644 --- a/.github/skills/truthmark-document/support/helper-policy.md +++ b/.github/skills/truthmark-document/support/helper-policy.md @@ -1,6 +1,6 @@ # Optional Helper CLI Policy -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Optional helper CLI commands may collect deterministic checkout facts or validate artifacts. If the Truthmark CLI is unavailable or too old for a declared helper, continue manually using this procedure and report which helper was skipped. Helper output is derived evidence; it does not override direct checkout inspection, workflow write boundaries, or parent acceptance. @@ -11,8 +11,8 @@ Runner detection: - Do not fail the workflow solely because a helper cannot run. Available helpers: -- validate-document-report: optional truthmark>=1.5.0; manual fallback: manually validate support/report-template.md required sections and structured Evidence checked entries -- validate-write-lease: optional truthmark>=1.5.0; manual fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files +- validate-document-report: optional truthmark>=1.6.0; manual fallback: manually validate support/report-template.md required sections and structured Evidence checked entries +- validate-write-lease: optional truthmark>=1.6.0; manual fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files Final reports should include helper status when helpers are declared for this workflow: diff --git a/.github/skills/truthmark-document/support/procedure.md b/.github/skills/truthmark-document/support/procedure.md index c0af75d..44d8eb3 100644 --- a/.github/skills/truthmark-document/support/procedure.md +++ b/.github/skills/truthmark-document/support/procedure.md @@ -1,6 +1,6 @@ # Truthmark Document Procedure -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. # Truthmark Document @@ -10,8 +10,8 @@ Invocations: OpenCode /skill truthmark-document; Codex /truthmark-document or $t Truth Document is manual and implementation-first: - run only when the user explicitly asks to generate or update truth docs for existing behavior, or when Truth Sync, Truth Check, or Truth Structure reports implemented behavior that lacks canonical truth docs -- inspect .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, existing canonical docs, implementation code, and tests directly -- Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +- inspect .truthmark/config.yml and configured route files only when they exist; then inspect existing canonical docs, implementation code, and tests directly +- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. - document current implemented behavior; do not invent future behavior or planned endpoints - may write canonical truth docs and docs/truthmark/areas.md or relevant child route files only @@ -43,7 +43,7 @@ Evidence Gate: - if no truth doc changed, report why current truth was already sufficient or why documentation was blocked Repository intelligence artifacts are optional derived context: RepoIndex, RouteMap, ImpactSet, and ContextPack may guide routing, context selection, and verification planning when available. They do not override checkout evidence, canonical truth docs, route files, or workflow write boundaries. -If unavailable, inspect .truthmark/config.yml, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated. +If unavailable, inspect any present Truthmark config, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated. When creating or updating a truth doc, inspect the routed truth kind and use the matching `docs/templates/-doc.md` template. Supported kinds: behavior, contract, architecture, workflow, operations, and test-behavior. Align existing docs to that template while preserving accurate authored content. @@ -58,11 +58,11 @@ Truth-doc shape repair gate: - report docs restructured and why a narrow edit was not sufficient Maintain architecture docs only for structure-level changes: system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership. Keep ordinary behavior, endpoints, UI copy, validation rules, and bug fixes in behavior or contract docs unless they change those boundaries. -Truthmark hierarchy: -- Config: .truthmark/config.yml -- Root route index: docs/truthmark/areas.md -- Area route files: docs/truthmark/areas/**/*.md -- Truth docs: docs/truth/**/*.md +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. Update Product Decisions and Rationale when a decision changes behavior. diff --git a/.github/skills/truthmark-document/support/report-template.md b/.github/skills/truthmark-document/support/report-template.md index 32cb1c3..22741ff 100644 --- a/.github/skills/truthmark-document/support/report-template.md +++ b/.github/skills/truthmark-document/support/report-template.md @@ -1,6 +1,6 @@ # Truthmark Document Report Template -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Report completion in this shape: ```md diff --git a/.github/skills/truthmark-document/support/subagents-and-leases.md b/.github/skills/truthmark-document/support/subagents-and-leases.md index d606913..0bde5f6 100644 --- a/.github/skills/truthmark-document/support/subagents-and-leases.md +++ b/.github/skills/truthmark-document/support/subagents-and-leases.md @@ -1,6 +1,6 @@ # Truthmark Document Subagents And Leases -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Copilot custom-agent mode: - use automatically when this workflow runs in Copilot and the parent agent chooses bounded custom-agent fan-out diff --git a/.github/skills/truthmark-preview/SKILL.md b/.github/skills/truthmark-preview/SKILL.md index 5ae8975..06b91c9 100644 --- a/.github/skills/truthmark-preview/SKILL.md +++ b/.github/skills/truthmark-preview/SKILL.md @@ -3,7 +3,7 @@ name: truthmark-preview description: Use when the user explicitly asks to preview likely workflow routing, target files, writes, or subagent use before edits. Not for validation, automatic gates, final correctness, or replacing Truth Check. argument-hint: Optional requested outcome, code area, doc path, or routing question user-invocable: true -truthmark-version: 1.5.0 +truthmark-version: 1.6.0 --- # Truthmark Preview @@ -16,8 +16,8 @@ Use as a Copilot agent skill. Prompt files remain available under `.github/promp Invocations: OpenCode /skill truthmark-preview; Codex /truthmark-preview or $truthmark-preview; Claude Code /truthmark-preview; GitHub Copilot /truthmark-preview; Gemini CLI /truthmark:preview. Quick procedure: -- Follow docs/ai/repo-rules.md as the repository instruction authority. -- Read .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, and only the truth docs or implementation files needed to preview ownership. +- Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists. +- Inspect .truthmark/config.yml and configured route files (docs/truthmark/areas.md; docs/truthmark/areas/) only when they exist; then inspect only the truth docs or implementation files needed to preview ownership. - Truth Preview is read-only; this report is intended, not authorized. - must not edit files and must not issue write leases; do not run Truth Sync automatically, replace Truth Check, claim final correctness, or mutate code. - Use optional read-only route-auditor evidence only when it reduces context or clarifies ownership. diff --git a/.github/skills/truthmark-preview/support/procedure.md b/.github/skills/truthmark-preview/support/procedure.md index 14c4376..d419bf2 100644 --- a/.github/skills/truthmark-preview/support/procedure.md +++ b/.github/skills/truthmark-preview/support/procedure.md @@ -1,6 +1,6 @@ # Truthmark Preview Procedure -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Use this skill only when the user explicitly asks to preview Truthmark routing or workflow choice before edits. @@ -14,11 +14,11 @@ Purpose: - keep the selector thin so agents can avoid loading or acting through heavier workflows prematurely Read: -- .truthmark/config.yml -- docs/truthmark/areas.md -- relevant child route files under docs/truthmark/areas/ +- .truthmark/config.yml, only when present +- docs/truthmark/areas.md, only when present +- relevant child route files under docs/truthmark/areas/, only when present - relevant truth docs and implementation files needed to preview ownership -- Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. Do not: @@ -36,8 +36,8 @@ Suggested subagent use: - write workers: none - leases needed: none -Truthmark hierarchy: -- Config: .truthmark/config.yml -- Root route index: docs/truthmark/areas.md -- Area route files: docs/truthmark/areas/**/*.md -- Truth docs: docs/truth/**/*.md +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md diff --git a/.github/skills/truthmark-preview/support/report-template.md b/.github/skills/truthmark-preview/support/report-template.md index 345ba01..72cf72b 100644 --- a/.github/skills/truthmark-preview/support/report-template.md +++ b/.github/skills/truthmark-preview/support/report-template.md @@ -1,6 +1,6 @@ # Truthmark Preview Report Template -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Report completion in this shape: ```md diff --git a/.github/skills/truthmark-preview/support/subagents-and-leases.md b/.github/skills/truthmark-preview/support/subagents-and-leases.md index 2e9cf8e..bdcaeea 100644 --- a/.github/skills/truthmark-preview/support/subagents-and-leases.md +++ b/.github/skills/truthmark-preview/support/subagents-and-leases.md @@ -1,6 +1,6 @@ # Truthmark Preview Subagents And Leases -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Copilot custom-agent mode: - use automatically when this workflow runs in Copilot and the parent agent chooses bounded custom-agent fan-out diff --git a/.github/skills/truthmark-realize/SKILL.md b/.github/skills/truthmark-realize/SKILL.md index fe24ee9..7ce60a0 100644 --- a/.github/skills/truthmark-realize/SKILL.md +++ b/.github/skills/truthmark-realize/SKILL.md @@ -3,7 +3,7 @@ name: truthmark-realize description: Use when the user explicitly asks to realize Truthmark truth docs into code, including /truthmark-realize, $truthmark-realize, or /truthmark:realize. Not for syncing docs after code changes, documenting existing code, topology repair, or truth audits. argument-hint: Optional truth doc path, area, or desired code behavior to realize user-invocable: true -truthmark-version: 1.5.0 +truthmark-version: 1.6.0 --- # Truthmark Realize @@ -16,8 +16,8 @@ Use as a Copilot agent skill. Prompt files remain available under `.github/promp Invocations: OpenCode /skill truthmark-realize; Codex /truthmark-realize or $truthmark-realize; Claude Code /truthmark-realize; GitHub Copilot /truthmark-realize; Gemini CLI /truthmark:realize. Quick procedure: -- Follow docs/ai/repo-rules.md as the repository instruction authority. -- Read the source truth docs, .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files, tests, and relevant functional code directly. +- Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists. +- Read the source truth docs, inspect .truthmark/config.yml and configured route files (docs/truthmark/areas.md; docs/truthmark/areas/) only when they exist, then inspect tests and relevant functional code directly. - Truth docs lead; code follows. - may write functional code only; must not edit truth docs or truth routing while realizing those docs. - Read support/procedure.md before changing code. diff --git a/.github/skills/truthmark-realize/support/procedure.md b/.github/skills/truthmark-realize/support/procedure.md index ad9eacd..aa9883b 100644 --- a/.github/skills/truthmark-realize/support/procedure.md +++ b/.github/skills/truthmark-realize/support/procedure.md @@ -1,6 +1,6 @@ # Truthmark Realize Procedure -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. # Truthmark Realize @@ -16,9 +16,9 @@ Truth Realize is doc-first: Workflow: -1. Read the updated truth docs named by the user, or infer the relevant docs from docs/truthmark/areas.md. -2. Read .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files, tests, and the relevant functional code. -3. Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +1. Read the updated truth docs named by the user, or infer the relevant docs from configured route files when present. +2. Inspect .truthmark/config.yml and configured route files (docs/truthmark/areas.md; docs/truthmark/areas/) only when they exist; then read tests and the relevant functional code. +3. Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. Truth-doc ownership gate: - before editing or relying on source truth docs before writing code, verify each target/source truth doc is a bounded owner for the behavior @@ -29,11 +29,11 @@ Truth-doc ownership gate: 5. Do not edit truth docs or truth routing while realizing those docs. 6. Run relevant tests for the changed code. 7. Report changed code files and verification steps. -Truthmark hierarchy: -- Config: .truthmark/config.yml -- Root route index: docs/truthmark/areas.md -- Area route files: docs/truthmark/areas/**/*.md -- Truth docs: docs/truth/**/*.md +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md Read and write boundaries: diff --git a/.github/skills/truthmark-realize/support/report-template.md b/.github/skills/truthmark-realize/support/report-template.md index 9ca297b..e49dde5 100644 --- a/.github/skills/truthmark-realize/support/report-template.md +++ b/.github/skills/truthmark-realize/support/report-template.md @@ -1,6 +1,6 @@ # Truthmark Realize Report Template -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Report completion in this shape: diff --git a/.github/skills/truthmark-structure/SKILL.md b/.github/skills/truthmark-structure/SKILL.md index 3fdca34..a378a21 100644 --- a/.github/skills/truthmark-structure/SKILL.md +++ b/.github/skills/truthmark-structure/SKILL.md @@ -3,7 +3,7 @@ name: truthmark-structure description: Use when routing or truth ownership is missing, stale, broad, overloaded, catch-all, unrouteable, mixed-owner, needs split/repair, or needs new area setup. Not for documenting implemented behavior, syncing a code diff, or realizing docs into code. argument-hint: Optional area, directory, or routing concern user-invocable: true -truthmark-version: 1.5.0 +truthmark-version: 1.6.0 --- # Truthmark Structure @@ -16,8 +16,8 @@ Use as a Copilot agent skill. Prompt files remain available under `.github/promp Invocations: OpenCode /skill truthmark-structure; Codex /truthmark-structure or $truthmark-structure; Claude Code /truthmark-structure; GitHub Copilot /truthmark-structure; Gemini CLI /truthmark:structure. Quick procedure: -- Follow docs/ai/repo-rules.md as the repository instruction authority. -- Read .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, current docs, and relevant code directly. +- Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists. +- Inspect .truthmark/config.yml and configured route files (docs/truthmark/areas.md; docs/truthmark/areas/) only when they exist; then inspect current docs and relevant code directly. - Define areas by product or behavior ownership, not by mechanical directory mirroring. - Do not edit functional code. - Read support/procedure.md before writing route or starter truth-doc changes. diff --git a/.github/skills/truthmark-structure/support/procedure.md b/.github/skills/truthmark-structure/support/procedure.md index 8315ea1..9104b33 100644 --- a/.github/skills/truthmark-structure/support/procedure.md +++ b/.github/skills/truthmark-structure/support/procedure.md @@ -1,14 +1,14 @@ # Truthmark Structure Procedure -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Use this skill to design or repair Truthmark area structure. Invocations: OpenCode /skill truthmark-structure; Codex /truthmark-structure or $truthmark-structure; Claude Code /truthmark-structure; GitHub Copilot /truthmark-structure; Gemini CLI /truthmark:structure. Truth Structure is agent-native: -- inspect repository layout, current docs, .truthmark/config.yml, docs/truthmark/areas.md, and relevant code directly -- Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +- inspect repository layout, current docs, Truthmark config and route files when present, and relevant code directly +- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. -- inspect the configured root route index at docs/truthmark/areas.md and relevant child route files under docs/truthmark/areas/ +- inspect the configured root route index at docs/truthmark/areas.md and relevant child route files under docs/truthmark/areas/ when they exist - define areas by product or behavior ownership, not by mechanical directory mirroring - create or repair docs/truthmark/areas.md - create starter truth docs when useful and when they belong in the canonical current-truth surface @@ -97,13 +97,13 @@ Keep ordinary behavior, endpoints, UI copy, validation rules, and bug fixes in b Portable fallback: - If this skill surface is unavailable, perform the same workflow directly from committed repository files. - Do not require the truthmark CLI. -- Read .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, canonical docs, and representative implementation code. +- Inspect .truthmark/config.yml and configured route files only when they exist; then inspect canonical docs and representative implementation code. - Use a subagent only when the host supports that pattern; otherwise perform the topology repair inline. -Truthmark hierarchy: -- Config: .truthmark/config.yml -- Root route index: docs/truthmark/areas.md -- Area route files: docs/truthmark/areas/**/*.md -- Truth docs: docs/truth/**/*.md +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. Update Product Decisions and Rationale when a decision changes behavior. diff --git a/.github/skills/truthmark-structure/support/report-template.md b/.github/skills/truthmark-structure/support/report-template.md index 75b6b1f..c104da3 100644 --- a/.github/skills/truthmark-structure/support/report-template.md +++ b/.github/skills/truthmark-structure/support/report-template.md @@ -1,6 +1,6 @@ # Truthmark Structure Report Template -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Report completion in this shape: ```md diff --git a/.github/skills/truthmark-structure/support/subagents-and-leases.md b/.github/skills/truthmark-structure/support/subagents-and-leases.md index 28ff563..80b7c90 100644 --- a/.github/skills/truthmark-structure/support/subagents-and-leases.md +++ b/.github/skills/truthmark-structure/support/subagents-and-leases.md @@ -1,6 +1,6 @@ # Truthmark Structure Subagents And Leases -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Copilot custom-agent mode: - use automatically when this workflow runs in Copilot and the parent agent chooses bounded custom-agent fan-out diff --git a/.github/skills/truthmark-sync/SKILL.md b/.github/skills/truthmark-sync/SKILL.md index 59c133a..6856bf8 100644 --- a/.github/skills/truthmark-sync/SKILL.md +++ b/.github/skills/truthmark-sync/SKILL.md @@ -3,7 +3,7 @@ name: truthmark-sync description: Use automatically at finish-time after functional code changes, or explicit /truthmark-sync, $truthmark-sync, or /truthmark:sync. Skip docs-only, formatting-only, behavior-preserving renames, missing config, and no-code changes. Not for doc-first realization or manual topology design. argument-hint: Optional changed-code area, truth-doc area, or sync focus user-invocable: true -truthmark-version: 1.5.0 +truthmark-version: 1.6.0 --- # Truthmark Sync @@ -16,9 +16,9 @@ Use as a Copilot agent skill. Prompt files remain available under `.github/promp Invocations: OpenCode /skill truthmark-sync; Codex /truthmark-sync or $truthmark-sync; Claude Code /truthmark-sync; GitHub Copilot /truthmark-sync; Gemini CLI /truthmark:sync. Quick procedure: -- Follow docs/ai/repo-rules.md as the repository instruction authority. +- Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists. - Skip docs-only, formatting-only, behavior-preserving renames with no truth impact, missing config, and no-code changes. -- Read .truthmark/config.yml, the configured root route index at docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, and relevant canonical docs. +- Inspect .truthmark/config.yml and configured route files (docs/truthmark/areas.md; docs/truthmark/areas/) only when they exist; then inspect relevant canonical docs directly. - direct checkout inspection is the canonical path; do not require the truthmark binary. - May write canonical truth docs and truth routing files only; must not rewrite functional code. - Read support/procedure.md before editing truth docs. diff --git a/.github/skills/truthmark-sync/helper-manifest.yml b/.github/skills/truthmark-sync/helper-manifest.yml index 663eeef..ce58751 100644 --- a/.github/skills/truthmark-sync/helper-manifest.yml +++ b/.github/skills/truthmark-sync/helper-manifest.yml @@ -1,8 +1,8 @@ -# Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +# Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. helpers: validate-sync-report: optional: true - runner: truthmark>=1.5.0 + runner: truthmark>=1.6.0 command: argv: - truthmark @@ -17,7 +17,7 @@ helpers: fallback: "manually validate support/report-template.md and check Evidence checked entries match Claim, indented Evidence, and Result: supported | narrowed | removed | blocked" validate-write-lease: optional: true - runner: truthmark>=1.5.0 + runner: truthmark>=1.6.0 command: argv: - truthmark diff --git a/.github/skills/truthmark-sync/support/helper-policy.md b/.github/skills/truthmark-sync/support/helper-policy.md index e7d086f..c3d00c7 100644 --- a/.github/skills/truthmark-sync/support/helper-policy.md +++ b/.github/skills/truthmark-sync/support/helper-policy.md @@ -1,6 +1,6 @@ # Optional Helper CLI Policy -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Optional helper CLI commands may collect deterministic checkout facts or validate artifacts. If the Truthmark CLI is unavailable or too old for a declared helper, continue manually using this procedure and report which helper was skipped. Helper output is derived evidence; it does not override direct checkout inspection, workflow write boundaries, or parent acceptance. @@ -11,8 +11,8 @@ Runner detection: - Do not fail the workflow solely because a helper cannot run. Available helpers: -- validate-sync-report: optional truthmark>=1.5.0; manual fallback: manually validate support/report-template.md and check Evidence checked entries match Claim, indented Evidence, and Result: supported | narrowed | removed | blocked -- validate-write-lease: optional truthmark>=1.5.0; manual fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files +- validate-sync-report: optional truthmark>=1.6.0; manual fallback: manually validate support/report-template.md and check Evidence checked entries match Claim, indented Evidence, and Result: supported | narrowed | removed | blocked +- validate-write-lease: optional truthmark>=1.6.0; manual fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files Final reports should include helper status when helpers are declared for this workflow: diff --git a/.github/skills/truthmark-sync/support/procedure.md b/.github/skills/truthmark-sync/support/procedure.md index 22da116..a80e050 100644 --- a/.github/skills/truthmark-sync/support/procedure.md +++ b/.github/skills/truthmark-sync/support/procedure.md @@ -1,6 +1,6 @@ # Truthmark Sync Procedure -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Use this skill automatically before finishing when functional code changed since the last successful Truth Sync. Also run it immediately when the user explicitly invokes Truth Sync. Invocations: OpenCode /skill truthmark-sync; Codex /truthmark-sync or $truthmark-sync; Claude Code /truthmark-sync; GitHub Copilot /truthmark-sync; Gemini CLI /truthmark:sync. @@ -8,9 +8,9 @@ Explicit invocation runs immediately. Later functional-code changes reopen the f Skip when changes are documentation-only, formatting-only, clearly behavior-preserving renames with no truth impact, when no Truthmark config exists yet, or when there are no functional code changes. Parent workflow: 1. Inspect git status, staged changes, unstaged changes, and untracked files directly. -2. Read .truthmark/config.yml, the configured root route index at docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, and relevant canonical docs. +2. Inspect .truthmark/config.yml and configured route files only when they exist; then inspect relevant canonical docs. 3. Identify functional-code changes and the nearest truth docs or routing repairs. -4. Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +4. Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. 5. Code verification is parent-owned: follow repository instructions and task context, and report what ran or why it did not run. 6. Dispatch bounded Truth Sync workers only when the host supports subagent dispatch and the acting agent chooses that path; otherwise execute the same sync task inline. @@ -57,7 +57,7 @@ Evidence Gate: - if no impacted doc changed, report why truth was already current or why sync was skipped Repository intelligence artifacts are optional derived context: RepoIndex, RouteMap, ImpactSet, and ContextPack may guide routing, context selection, and verification planning when available. They do not override checkout evidence, canonical truth docs, route files, or workflow write boundaries. -If unavailable, inspect .truthmark/config.yml, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated. +If unavailable, inspect any present Truthmark config, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated. Optional validation tooling: - you may run truthmark check when local tooling is available - do not require the truthmark binary; direct checkout inspection is the canonical path @@ -69,11 +69,11 @@ Helper status reporting: - If the installed Truthmark CLI is unavailable or the helper is skipped, record `validate-sync-report: skipped, ` and manually validate the report shape. - Record `validate-write-lease: ran, passed` only after validating a concrete write lease; otherwise use a truthful skipped status such as `skipped, no write lease used`. - Helper output is derived evidence and never replaces direct checkout inspection, evidence review, or parent acceptance. -Truthmark hierarchy: -- Config: .truthmark/config.yml -- Root route index: docs/truthmark/areas.md -- Area route files: docs/truthmark/areas/**/*.md -- Truth docs: docs/truth/**/*.md +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. Update Product Decisions and Rationale when a decision changes behavior. diff --git a/.github/skills/truthmark-sync/support/report-template.md b/.github/skills/truthmark-sync/support/report-template.md index 5cd2313..9bce186 100644 --- a/.github/skills/truthmark-sync/support/report-template.md +++ b/.github/skills/truthmark-sync/support/report-template.md @@ -1,6 +1,6 @@ # Truthmark Sync Report Template -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Report completion in this shape: ```md diff --git a/.github/skills/truthmark-sync/support/subagents-and-leases.md b/.github/skills/truthmark-sync/support/subagents-and-leases.md index e3c0be1..fbfd493 100644 --- a/.github/skills/truthmark-sync/support/subagents-and-leases.md +++ b/.github/skills/truthmark-sync/support/subagents-and-leases.md @@ -1,6 +1,6 @@ # Truthmark Sync Subagents And Leases -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Copilot custom-agent mode: - use automatically when this workflow runs in Copilot and the parent agent chooses bounded custom-agent fan-out diff --git a/.opencode/agents/truth-claim-verifier.md b/.opencode/agents/truth-claim-verifier.md index 4bddb07..80493a8 100644 --- a/.opencode/agents/truth-claim-verifier.md +++ b/.opencode/agents/truth-claim-verifier.md @@ -16,7 +16,7 @@ permission: "grep *": allow --- -# Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +# Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Manual invocation: @truth-claim-verifier diff --git a/.opencode/agents/truth-doc-reviewer.md b/.opencode/agents/truth-doc-reviewer.md index e4646e4..c24e525 100644 --- a/.opencode/agents/truth-doc-reviewer.md +++ b/.opencode/agents/truth-doc-reviewer.md @@ -16,7 +16,7 @@ permission: "grep *": allow --- -# Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +# Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Manual invocation: @truth-doc-reviewer diff --git a/.opencode/agents/truth-doc-writer.md b/.opencode/agents/truth-doc-writer.md index 15e4dd5..ce3eb03 100644 --- a/.opencode/agents/truth-doc-writer.md +++ b/.opencode/agents/truth-doc-writer.md @@ -21,7 +21,7 @@ permission: "git diff*": allow --- -# Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +# Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Manual invocation: @truth-doc-writer diff --git a/.opencode/agents/truth-route-auditor.md b/.opencode/agents/truth-route-auditor.md index 32a47de..e0cf811 100644 --- a/.opencode/agents/truth-route-auditor.md +++ b/.opencode/agents/truth-route-auditor.md @@ -16,13 +16,13 @@ permission: "grep *": allow --- -# Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +# Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Manual invocation: @truth-route-auditor Stay read-only. Audit one bounded Truthmark route, area, or doc shard assigned by the parent. -Read .truthmark/config.yml, the root route index, relevant child route files, mapped truth docs, and relevant implementation files directly. +Inspect .truthmark/config.yml and route files only when they exist; then inspect mapped truth docs and relevant implementation files directly. Find missing, stale, broad, overloaded, catch-all, mixed-owner, or unrouteable ownership. Do not edit files, stage changes, or propose broad rewrites. Return JSON only with keys: scope, filesReviewed, findings, evidence, confidence, recommendedWorkflow, notes. diff --git a/.opencode/skills/truthmark-check/SKILL.md b/.opencode/skills/truthmark-check/SKILL.md index 7364b22..a81e78f 100644 --- a/.opencode/skills/truthmark-check/SKILL.md +++ b/.opencode/skills/truthmark-check/SKILL.md @@ -3,7 +3,7 @@ name: truthmark-check description: Use when the user asks to audit repository truth health, routing, ownership, or canonical docs. Not for normal lint/test/typecheck/code-review verification, finish-time Sync, or silently rewriting docs. argument-hint: Optional area, doc path, or audit focus user-invocable: true -truthmark-version: 1.5.0 +truthmark-version: 1.6.0 --- # Truthmark Check @@ -14,8 +14,8 @@ Use this skill to audit repository truth health. Invocations: OpenCode /skill truthmark-check; Codex /truthmark-check or $truthmark-check; Claude Code /truthmark-check; GitHub Copilot /truthmark-check; Gemini CLI /truthmark:check. Quick procedure: -- Follow docs/ai/repo-rules.md as the repository instruction authority. -- Read .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, canonical docs, and relevant implementation directly. +- Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists. +- Inspect .truthmark/config.yml and configured route files (docs/truthmark/areas.md; docs/truthmark/areas/) only when they exist; then inspect canonical docs and relevant implementation directly. - Report issues and suggested fixes; do not silently rewrite unrelated files. - Direct checkout inspection is valid even when local tooling is unavailable. - Read support/procedure.md before auditing details. diff --git a/.opencode/skills/truthmark-check/support/procedure.md b/.opencode/skills/truthmark-check/support/procedure.md index 82239d8..33b7663 100644 --- a/.opencode/skills/truthmark-check/support/procedure.md +++ b/.opencode/skills/truthmark-check/support/procedure.md @@ -1,6 +1,6 @@ # Truthmark Check Procedure -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. # Truthmark Check @@ -10,12 +10,12 @@ Invocations: OpenCode /skill truthmark-check; Codex /truthmark-check or $truthma Truth Check is agent-led: -- inspect .truthmark/config.yml, docs/truthmark/areas.md, canonical docs, and relevant implementation directly -- Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +- inspect .truthmark/config.yml and configured route files only when they exist; then inspect canonical docs and relevant implementation directly +- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. -- inspect the configured root route index at docs/truthmark/areas.md and relevant child route files under docs/truthmark/areas/ +- inspect the configured root route index at docs/truthmark/areas.md and relevant child route files under docs/truthmark/areas/ when they exist - check that current docs describe current code rather than historical plans -- check that docs/truthmark/areas.md routes code surfaces to canonical truth docs +- check that route files map code surfaces to canonical truth docs when route files exist - check for broad, catch-all, index-like, or mixed-owner truth docs and report them as topology issues requiring Truth Structure - check that canonical behavior docs keep active Product Decisions and Rationale sections - optionally run truthmark check when local tooling is available @@ -27,11 +27,11 @@ Evidence Gate: - canonical docs are context, not sole proof when implementation conflicts - remove unsupported findings or mark open questions; validate changed claims if you edit docs -Truthmark hierarchy: -- Config: .truthmark/config.yml -- Root route index: docs/truthmark/areas.md -- Area route files: docs/truthmark/areas/**/*.md -- Truth docs: docs/truth/**/*.md +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. Update Product Decisions and Rationale when a decision changes behavior. diff --git a/.opencode/skills/truthmark-check/support/report-template.md b/.opencode/skills/truthmark-check/support/report-template.md index 1dc6319..e98269e 100644 --- a/.opencode/skills/truthmark-check/support/report-template.md +++ b/.opencode/skills/truthmark-check/support/report-template.md @@ -1,6 +1,6 @@ # Truthmark Check Report Template -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Report completion in this shape: @@ -18,7 +18,7 @@ Fixes suggested: Evidence checked: - Finding: The root route index is present and maps repository truth owners. - Evidence: .truthmark/config.yml:1 / docs/truthmark/areas.md:1 + Evidence: docs/truthmark/areas.md:1 Suggested fix: none Confidence: high diff --git a/.opencode/skills/truthmark-check/support/subagents-and-leases.md b/.opencode/skills/truthmark-check/support/subagents-and-leases.md index 6b07235..e97782a 100644 --- a/.opencode/skills/truthmark-check/support/subagents-and-leases.md +++ b/.opencode/skills/truthmark-check/support/subagents-and-leases.md @@ -1,6 +1,6 @@ # Truthmark Check Subagents And Leases -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. OpenCode subagent mode: - use automatically when this workflow runs in OpenCode and the parent agent chooses bounded subagent fan-out diff --git a/.opencode/skills/truthmark-document/SKILL.md b/.opencode/skills/truthmark-document/SKILL.md index bd9ca15..751caa5 100644 --- a/.opencode/skills/truthmark-document/SKILL.md +++ b/.opencode/skills/truthmark-document/SKILL.md @@ -3,7 +3,7 @@ name: truthmark-document description: Use when the user asks to document existing implemented behavior, or Sync, Check, or Structure finds implemented behavior missing canonical truth. Not for functional-code changes, doc-first implementation, or topology repair that needs Structure. argument-hint: Optional implemented behavior, API endpoint, route, controller, package, or truth-doc area to document user-invocable: true -truthmark-version: 1.5.0 +truthmark-version: 1.6.0 --- # Truthmark Document @@ -14,8 +14,8 @@ Use this skill to document existing implemented behavior when no functional-code Invocations: OpenCode /skill truthmark-document; Codex /truthmark-document or $truthmark-document; Claude Code /truthmark-document; GitHub Copilot /truthmark-document; Gemini CLI /truthmark:document. Quick procedure: -- Follow docs/ai/repo-rules.md as the repository instruction authority. -- Read .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, existing canonical docs, implementation code, and tests directly. +- Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists. +- Inspect .truthmark/config.yml and configured route files (docs/truthmark/areas.md; docs/truthmark/areas/) only when they exist; then inspect existing canonical docs, implementation code, and tests directly. - Document current implemented behavior; do not invent future behavior. - May write canonical truth docs and truth routing files only; must not write functional code. - Read support/procedure.md before editing truth docs. diff --git a/.opencode/skills/truthmark-document/helper-manifest.yml b/.opencode/skills/truthmark-document/helper-manifest.yml index e53fa02..dc05fe5 100644 --- a/.opencode/skills/truthmark-document/helper-manifest.yml +++ b/.opencode/skills/truthmark-document/helper-manifest.yml @@ -1,8 +1,8 @@ -# Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +# Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. helpers: validate-document-report: optional: true - runner: truthmark>=1.5.0 + runner: truthmark>=1.6.0 command: argv: - truthmark @@ -17,7 +17,7 @@ helpers: fallback: manually validate support/report-template.md required sections and structured Evidence checked entries validate-write-lease: optional: true - runner: truthmark>=1.5.0 + runner: truthmark>=1.6.0 command: argv: - truthmark diff --git a/.opencode/skills/truthmark-document/support/helper-policy.md b/.opencode/skills/truthmark-document/support/helper-policy.md index 24a89d8..53b72b7 100644 --- a/.opencode/skills/truthmark-document/support/helper-policy.md +++ b/.opencode/skills/truthmark-document/support/helper-policy.md @@ -1,6 +1,6 @@ # Optional Helper CLI Policy -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Optional helper CLI commands may collect deterministic checkout facts or validate artifacts. If the Truthmark CLI is unavailable or too old for a declared helper, continue manually using this procedure and report which helper was skipped. Helper output is derived evidence; it does not override direct checkout inspection, workflow write boundaries, or parent acceptance. @@ -11,8 +11,8 @@ Runner detection: - Do not fail the workflow solely because a helper cannot run. Available helpers: -- validate-document-report: optional truthmark>=1.5.0; manual fallback: manually validate support/report-template.md required sections and structured Evidence checked entries -- validate-write-lease: optional truthmark>=1.5.0; manual fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files +- validate-document-report: optional truthmark>=1.6.0; manual fallback: manually validate support/report-template.md required sections and structured Evidence checked entries +- validate-write-lease: optional truthmark>=1.6.0; manual fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files Final reports should include helper status when helpers are declared for this workflow: diff --git a/.opencode/skills/truthmark-document/support/procedure.md b/.opencode/skills/truthmark-document/support/procedure.md index c0af75d..44d8eb3 100644 --- a/.opencode/skills/truthmark-document/support/procedure.md +++ b/.opencode/skills/truthmark-document/support/procedure.md @@ -1,6 +1,6 @@ # Truthmark Document Procedure -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. # Truthmark Document @@ -10,8 +10,8 @@ Invocations: OpenCode /skill truthmark-document; Codex /truthmark-document or $t Truth Document is manual and implementation-first: - run only when the user explicitly asks to generate or update truth docs for existing behavior, or when Truth Sync, Truth Check, or Truth Structure reports implemented behavior that lacks canonical truth docs -- inspect .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, existing canonical docs, implementation code, and tests directly -- Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +- inspect .truthmark/config.yml and configured route files only when they exist; then inspect existing canonical docs, implementation code, and tests directly +- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. - document current implemented behavior; do not invent future behavior or planned endpoints - may write canonical truth docs and docs/truthmark/areas.md or relevant child route files only @@ -43,7 +43,7 @@ Evidence Gate: - if no truth doc changed, report why current truth was already sufficient or why documentation was blocked Repository intelligence artifacts are optional derived context: RepoIndex, RouteMap, ImpactSet, and ContextPack may guide routing, context selection, and verification planning when available. They do not override checkout evidence, canonical truth docs, route files, or workflow write boundaries. -If unavailable, inspect .truthmark/config.yml, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated. +If unavailable, inspect any present Truthmark config, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated. When creating or updating a truth doc, inspect the routed truth kind and use the matching `docs/templates/-doc.md` template. Supported kinds: behavior, contract, architecture, workflow, operations, and test-behavior. Align existing docs to that template while preserving accurate authored content. @@ -58,11 +58,11 @@ Truth-doc shape repair gate: - report docs restructured and why a narrow edit was not sufficient Maintain architecture docs only for structure-level changes: system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership. Keep ordinary behavior, endpoints, UI copy, validation rules, and bug fixes in behavior or contract docs unless they change those boundaries. -Truthmark hierarchy: -- Config: .truthmark/config.yml -- Root route index: docs/truthmark/areas.md -- Area route files: docs/truthmark/areas/**/*.md -- Truth docs: docs/truth/**/*.md +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. Update Product Decisions and Rationale when a decision changes behavior. diff --git a/.opencode/skills/truthmark-document/support/report-template.md b/.opencode/skills/truthmark-document/support/report-template.md index 32cb1c3..22741ff 100644 --- a/.opencode/skills/truthmark-document/support/report-template.md +++ b/.opencode/skills/truthmark-document/support/report-template.md @@ -1,6 +1,6 @@ # Truthmark Document Report Template -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Report completion in this shape: ```md diff --git a/.opencode/skills/truthmark-document/support/subagents-and-leases.md b/.opencode/skills/truthmark-document/support/subagents-and-leases.md index 79b0164..2ee223f 100644 --- a/.opencode/skills/truthmark-document/support/subagents-and-leases.md +++ b/.opencode/skills/truthmark-document/support/subagents-and-leases.md @@ -1,6 +1,6 @@ # Truthmark Document Subagents And Leases -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. OpenCode subagent mode: - use automatically when this workflow runs in OpenCode and the parent agent chooses bounded subagent fan-out diff --git a/.opencode/skills/truthmark-preview/SKILL.md b/.opencode/skills/truthmark-preview/SKILL.md index 83dd9db..05e0598 100644 --- a/.opencode/skills/truthmark-preview/SKILL.md +++ b/.opencode/skills/truthmark-preview/SKILL.md @@ -3,7 +3,7 @@ name: truthmark-preview description: Use when the user explicitly asks to preview likely workflow routing, target files, writes, or subagent use before edits. Not for validation, automatic gates, final correctness, or replacing Truth Check. argument-hint: Optional requested outcome, code area, doc path, or routing question user-invocable: true -truthmark-version: 1.5.0 +truthmark-version: 1.6.0 --- # Truthmark Preview @@ -14,8 +14,8 @@ Use this skill only when the user explicitly asks to preview Truthmark routing o Invocations: OpenCode /skill truthmark-preview; Codex /truthmark-preview or $truthmark-preview; Claude Code /truthmark-preview; GitHub Copilot /truthmark-preview; Gemini CLI /truthmark:preview. Quick procedure: -- Follow docs/ai/repo-rules.md as the repository instruction authority. -- Read .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, and only the truth docs or implementation files needed to preview ownership. +- Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists. +- Inspect .truthmark/config.yml and configured route files (docs/truthmark/areas.md; docs/truthmark/areas/) only when they exist; then inspect only the truth docs or implementation files needed to preview ownership. - Truth Preview is read-only; this report is intended, not authorized. - must not edit files and must not issue write leases; do not run Truth Sync automatically, replace Truth Check, claim final correctness, or mutate code. - Use optional read-only route-auditor evidence only when it reduces context or clarifies ownership. diff --git a/.opencode/skills/truthmark-preview/support/procedure.md b/.opencode/skills/truthmark-preview/support/procedure.md index 14c4376..d419bf2 100644 --- a/.opencode/skills/truthmark-preview/support/procedure.md +++ b/.opencode/skills/truthmark-preview/support/procedure.md @@ -1,6 +1,6 @@ # Truthmark Preview Procedure -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Use this skill only when the user explicitly asks to preview Truthmark routing or workflow choice before edits. @@ -14,11 +14,11 @@ Purpose: - keep the selector thin so agents can avoid loading or acting through heavier workflows prematurely Read: -- .truthmark/config.yml -- docs/truthmark/areas.md -- relevant child route files under docs/truthmark/areas/ +- .truthmark/config.yml, only when present +- docs/truthmark/areas.md, only when present +- relevant child route files under docs/truthmark/areas/, only when present - relevant truth docs and implementation files needed to preview ownership -- Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. Do not: @@ -36,8 +36,8 @@ Suggested subagent use: - write workers: none - leases needed: none -Truthmark hierarchy: -- Config: .truthmark/config.yml -- Root route index: docs/truthmark/areas.md -- Area route files: docs/truthmark/areas/**/*.md -- Truth docs: docs/truth/**/*.md +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md diff --git a/.opencode/skills/truthmark-preview/support/report-template.md b/.opencode/skills/truthmark-preview/support/report-template.md index 345ba01..72cf72b 100644 --- a/.opencode/skills/truthmark-preview/support/report-template.md +++ b/.opencode/skills/truthmark-preview/support/report-template.md @@ -1,6 +1,6 @@ # Truthmark Preview Report Template -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Report completion in this shape: ```md diff --git a/.opencode/skills/truthmark-preview/support/subagents-and-leases.md b/.opencode/skills/truthmark-preview/support/subagents-and-leases.md index 4ce032d..07a7a42 100644 --- a/.opencode/skills/truthmark-preview/support/subagents-and-leases.md +++ b/.opencode/skills/truthmark-preview/support/subagents-and-leases.md @@ -1,6 +1,6 @@ # Truthmark Preview Subagents And Leases -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. OpenCode subagent mode: - use automatically when this workflow runs in OpenCode and the parent agent chooses bounded subagent fan-out diff --git a/.opencode/skills/truthmark-realize/SKILL.md b/.opencode/skills/truthmark-realize/SKILL.md index 90cb033..c91e02d 100644 --- a/.opencode/skills/truthmark-realize/SKILL.md +++ b/.opencode/skills/truthmark-realize/SKILL.md @@ -3,7 +3,7 @@ name: truthmark-realize description: Use when the user explicitly asks to realize Truthmark truth docs into code, including /truthmark-realize, $truthmark-realize, or /truthmark:realize. Not for syncing docs after code changes, documenting existing code, topology repair, or truth audits. argument-hint: Optional truth doc path, area, or desired code behavior to realize user-invocable: true -truthmark-version: 1.5.0 +truthmark-version: 1.6.0 --- # Truthmark Realize @@ -14,8 +14,8 @@ Use this skill only when the user explicitly asks to realize truth docs into cod Invocations: OpenCode /skill truthmark-realize; Codex /truthmark-realize or $truthmark-realize; Claude Code /truthmark-realize; GitHub Copilot /truthmark-realize; Gemini CLI /truthmark:realize. Quick procedure: -- Follow docs/ai/repo-rules.md as the repository instruction authority. -- Read the source truth docs, .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files, tests, and relevant functional code directly. +- Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists. +- Read the source truth docs, inspect .truthmark/config.yml and configured route files (docs/truthmark/areas.md; docs/truthmark/areas/) only when they exist, then inspect tests and relevant functional code directly. - Truth docs lead; code follows. - may write functional code only; must not edit truth docs or truth routing while realizing those docs. - Read support/procedure.md before changing code. diff --git a/.opencode/skills/truthmark-realize/support/procedure.md b/.opencode/skills/truthmark-realize/support/procedure.md index ad9eacd..aa9883b 100644 --- a/.opencode/skills/truthmark-realize/support/procedure.md +++ b/.opencode/skills/truthmark-realize/support/procedure.md @@ -1,6 +1,6 @@ # Truthmark Realize Procedure -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. # Truthmark Realize @@ -16,9 +16,9 @@ Truth Realize is doc-first: Workflow: -1. Read the updated truth docs named by the user, or infer the relevant docs from docs/truthmark/areas.md. -2. Read .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files, tests, and the relevant functional code. -3. Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +1. Read the updated truth docs named by the user, or infer the relevant docs from configured route files when present. +2. Inspect .truthmark/config.yml and configured route files (docs/truthmark/areas.md; docs/truthmark/areas/) only when they exist; then read tests and the relevant functional code. +3. Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. Truth-doc ownership gate: - before editing or relying on source truth docs before writing code, verify each target/source truth doc is a bounded owner for the behavior @@ -29,11 +29,11 @@ Truth-doc ownership gate: 5. Do not edit truth docs or truth routing while realizing those docs. 6. Run relevant tests for the changed code. 7. Report changed code files and verification steps. -Truthmark hierarchy: -- Config: .truthmark/config.yml -- Root route index: docs/truthmark/areas.md -- Area route files: docs/truthmark/areas/**/*.md -- Truth docs: docs/truth/**/*.md +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md Read and write boundaries: diff --git a/.opencode/skills/truthmark-realize/support/report-template.md b/.opencode/skills/truthmark-realize/support/report-template.md index 9ca297b..e49dde5 100644 --- a/.opencode/skills/truthmark-realize/support/report-template.md +++ b/.opencode/skills/truthmark-realize/support/report-template.md @@ -1,6 +1,6 @@ # Truthmark Realize Report Template -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Report completion in this shape: diff --git a/.opencode/skills/truthmark-structure/SKILL.md b/.opencode/skills/truthmark-structure/SKILL.md index f112e7e..67f522b 100644 --- a/.opencode/skills/truthmark-structure/SKILL.md +++ b/.opencode/skills/truthmark-structure/SKILL.md @@ -3,7 +3,7 @@ name: truthmark-structure description: Use when routing or truth ownership is missing, stale, broad, overloaded, catch-all, unrouteable, mixed-owner, needs split/repair, or needs new area setup. Not for documenting implemented behavior, syncing a code diff, or realizing docs into code. argument-hint: Optional area, directory, or routing concern user-invocable: true -truthmark-version: 1.5.0 +truthmark-version: 1.6.0 --- # Truthmark Structure @@ -14,8 +14,8 @@ Use this skill to design or repair Truthmark area structure. Invocations: OpenCode /skill truthmark-structure; Codex /truthmark-structure or $truthmark-structure; Claude Code /truthmark-structure; GitHub Copilot /truthmark-structure; Gemini CLI /truthmark:structure. Quick procedure: -- Follow docs/ai/repo-rules.md as the repository instruction authority. -- Read .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, current docs, and relevant code directly. +- Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists. +- Inspect .truthmark/config.yml and configured route files (docs/truthmark/areas.md; docs/truthmark/areas/) only when they exist; then inspect current docs and relevant code directly. - Define areas by product or behavior ownership, not by mechanical directory mirroring. - Do not edit functional code. - Read support/procedure.md before writing route or starter truth-doc changes. diff --git a/.opencode/skills/truthmark-structure/support/procedure.md b/.opencode/skills/truthmark-structure/support/procedure.md index 8315ea1..9104b33 100644 --- a/.opencode/skills/truthmark-structure/support/procedure.md +++ b/.opencode/skills/truthmark-structure/support/procedure.md @@ -1,14 +1,14 @@ # Truthmark Structure Procedure -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Use this skill to design or repair Truthmark area structure. Invocations: OpenCode /skill truthmark-structure; Codex /truthmark-structure or $truthmark-structure; Claude Code /truthmark-structure; GitHub Copilot /truthmark-structure; Gemini CLI /truthmark:structure. Truth Structure is agent-native: -- inspect repository layout, current docs, .truthmark/config.yml, docs/truthmark/areas.md, and relevant code directly -- Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +- inspect repository layout, current docs, Truthmark config and route files when present, and relevant code directly +- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. -- inspect the configured root route index at docs/truthmark/areas.md and relevant child route files under docs/truthmark/areas/ +- inspect the configured root route index at docs/truthmark/areas.md and relevant child route files under docs/truthmark/areas/ when they exist - define areas by product or behavior ownership, not by mechanical directory mirroring - create or repair docs/truthmark/areas.md - create starter truth docs when useful and when they belong in the canonical current-truth surface @@ -97,13 +97,13 @@ Keep ordinary behavior, endpoints, UI copy, validation rules, and bug fixes in b Portable fallback: - If this skill surface is unavailable, perform the same workflow directly from committed repository files. - Do not require the truthmark CLI. -- Read .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, canonical docs, and representative implementation code. +- Inspect .truthmark/config.yml and configured route files only when they exist; then inspect canonical docs and representative implementation code. - Use a subagent only when the host supports that pattern; otherwise perform the topology repair inline. -Truthmark hierarchy: -- Config: .truthmark/config.yml -- Root route index: docs/truthmark/areas.md -- Area route files: docs/truthmark/areas/**/*.md -- Truth docs: docs/truth/**/*.md +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. Update Product Decisions and Rationale when a decision changes behavior. diff --git a/.opencode/skills/truthmark-structure/support/report-template.md b/.opencode/skills/truthmark-structure/support/report-template.md index 75b6b1f..c104da3 100644 --- a/.opencode/skills/truthmark-structure/support/report-template.md +++ b/.opencode/skills/truthmark-structure/support/report-template.md @@ -1,6 +1,6 @@ # Truthmark Structure Report Template -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Report completion in this shape: ```md diff --git a/.opencode/skills/truthmark-structure/support/subagents-and-leases.md b/.opencode/skills/truthmark-structure/support/subagents-and-leases.md index 1aefc31..fa54016 100644 --- a/.opencode/skills/truthmark-structure/support/subagents-and-leases.md +++ b/.opencode/skills/truthmark-structure/support/subagents-and-leases.md @@ -1,6 +1,6 @@ # Truthmark Structure Subagents And Leases -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. OpenCode subagent mode: - use automatically when this workflow runs in OpenCode and the parent agent chooses bounded subagent fan-out diff --git a/.opencode/skills/truthmark-sync/SKILL.md b/.opencode/skills/truthmark-sync/SKILL.md index 344e5c6..651ffc3 100644 --- a/.opencode/skills/truthmark-sync/SKILL.md +++ b/.opencode/skills/truthmark-sync/SKILL.md @@ -3,7 +3,7 @@ name: truthmark-sync description: Use automatically at finish-time after functional code changes, or explicit /truthmark-sync, $truthmark-sync, or /truthmark:sync. Skip docs-only, formatting-only, behavior-preserving renames, missing config, and no-code changes. Not for doc-first realization or manual topology design. argument-hint: Optional changed-code area, truth-doc area, or sync focus user-invocable: true -truthmark-version: 1.5.0 +truthmark-version: 1.6.0 --- # Truthmark Sync @@ -14,9 +14,9 @@ Use this skill automatically before finishing when functional code changed since Invocations: OpenCode /skill truthmark-sync; Codex /truthmark-sync or $truthmark-sync; Claude Code /truthmark-sync; GitHub Copilot /truthmark-sync; Gemini CLI /truthmark:sync. Quick procedure: -- Follow docs/ai/repo-rules.md as the repository instruction authority. +- Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists. - Skip docs-only, formatting-only, behavior-preserving renames with no truth impact, missing config, and no-code changes. -- Read .truthmark/config.yml, the configured root route index at docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, and relevant canonical docs. +- Inspect .truthmark/config.yml and configured route files (docs/truthmark/areas.md; docs/truthmark/areas/) only when they exist; then inspect relevant canonical docs directly. - direct checkout inspection is the canonical path; do not require the truthmark binary. - May write canonical truth docs and truth routing files only; must not rewrite functional code. - Read support/procedure.md before editing truth docs. diff --git a/.opencode/skills/truthmark-sync/helper-manifest.yml b/.opencode/skills/truthmark-sync/helper-manifest.yml index 663eeef..ce58751 100644 --- a/.opencode/skills/truthmark-sync/helper-manifest.yml +++ b/.opencode/skills/truthmark-sync/helper-manifest.yml @@ -1,8 +1,8 @@ -# Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +# Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. helpers: validate-sync-report: optional: true - runner: truthmark>=1.5.0 + runner: truthmark>=1.6.0 command: argv: - truthmark @@ -17,7 +17,7 @@ helpers: fallback: "manually validate support/report-template.md and check Evidence checked entries match Claim, indented Evidence, and Result: supported | narrowed | removed | blocked" validate-write-lease: optional: true - runner: truthmark>=1.5.0 + runner: truthmark>=1.6.0 command: argv: - truthmark diff --git a/.opencode/skills/truthmark-sync/support/helper-policy.md b/.opencode/skills/truthmark-sync/support/helper-policy.md index e7d086f..c3d00c7 100644 --- a/.opencode/skills/truthmark-sync/support/helper-policy.md +++ b/.opencode/skills/truthmark-sync/support/helper-policy.md @@ -1,6 +1,6 @@ # Optional Helper CLI Policy -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Optional helper CLI commands may collect deterministic checkout facts or validate artifacts. If the Truthmark CLI is unavailable or too old for a declared helper, continue manually using this procedure and report which helper was skipped. Helper output is derived evidence; it does not override direct checkout inspection, workflow write boundaries, or parent acceptance. @@ -11,8 +11,8 @@ Runner detection: - Do not fail the workflow solely because a helper cannot run. Available helpers: -- validate-sync-report: optional truthmark>=1.5.0; manual fallback: manually validate support/report-template.md and check Evidence checked entries match Claim, indented Evidence, and Result: supported | narrowed | removed | blocked -- validate-write-lease: optional truthmark>=1.5.0; manual fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files +- validate-sync-report: optional truthmark>=1.6.0; manual fallback: manually validate support/report-template.md and check Evidence checked entries match Claim, indented Evidence, and Result: supported | narrowed | removed | blocked +- validate-write-lease: optional truthmark>=1.6.0; manual fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files Final reports should include helper status when helpers are declared for this workflow: diff --git a/.opencode/skills/truthmark-sync/support/procedure.md b/.opencode/skills/truthmark-sync/support/procedure.md index 22da116..a80e050 100644 --- a/.opencode/skills/truthmark-sync/support/procedure.md +++ b/.opencode/skills/truthmark-sync/support/procedure.md @@ -1,6 +1,6 @@ # Truthmark Sync Procedure -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Use this skill automatically before finishing when functional code changed since the last successful Truth Sync. Also run it immediately when the user explicitly invokes Truth Sync. Invocations: OpenCode /skill truthmark-sync; Codex /truthmark-sync or $truthmark-sync; Claude Code /truthmark-sync; GitHub Copilot /truthmark-sync; Gemini CLI /truthmark:sync. @@ -8,9 +8,9 @@ Explicit invocation runs immediately. Later functional-code changes reopen the f Skip when changes are documentation-only, formatting-only, clearly behavior-preserving renames with no truth impact, when no Truthmark config exists yet, or when there are no functional code changes. Parent workflow: 1. Inspect git status, staged changes, unstaged changes, and untracked files directly. -2. Read .truthmark/config.yml, the configured root route index at docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, and relevant canonical docs. +2. Inspect .truthmark/config.yml and configured route files only when they exist; then inspect relevant canonical docs. 3. Identify functional-code changes and the nearest truth docs or routing repairs. -4. Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +4. Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. 5. Code verification is parent-owned: follow repository instructions and task context, and report what ran or why it did not run. 6. Dispatch bounded Truth Sync workers only when the host supports subagent dispatch and the acting agent chooses that path; otherwise execute the same sync task inline. @@ -57,7 +57,7 @@ Evidence Gate: - if no impacted doc changed, report why truth was already current or why sync was skipped Repository intelligence artifacts are optional derived context: RepoIndex, RouteMap, ImpactSet, and ContextPack may guide routing, context selection, and verification planning when available. They do not override checkout evidence, canonical truth docs, route files, or workflow write boundaries. -If unavailable, inspect .truthmark/config.yml, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated. +If unavailable, inspect any present Truthmark config, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated. Optional validation tooling: - you may run truthmark check when local tooling is available - do not require the truthmark binary; direct checkout inspection is the canonical path @@ -69,11 +69,11 @@ Helper status reporting: - If the installed Truthmark CLI is unavailable or the helper is skipped, record `validate-sync-report: skipped, ` and manually validate the report shape. - Record `validate-write-lease: ran, passed` only after validating a concrete write lease; otherwise use a truthful skipped status such as `skipped, no write lease used`. - Helper output is derived evidence and never replaces direct checkout inspection, evidence review, or parent acceptance. -Truthmark hierarchy: -- Config: .truthmark/config.yml -- Root route index: docs/truthmark/areas.md -- Area route files: docs/truthmark/areas/**/*.md -- Truth docs: docs/truth/**/*.md +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. Update Product Decisions and Rationale when a decision changes behavior. diff --git a/.opencode/skills/truthmark-sync/support/report-template.md b/.opencode/skills/truthmark-sync/support/report-template.md index 5cd2313..9bce186 100644 --- a/.opencode/skills/truthmark-sync/support/report-template.md +++ b/.opencode/skills/truthmark-sync/support/report-template.md @@ -1,6 +1,6 @@ # Truthmark Sync Report Template -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. Report completion in this shape: ```md diff --git a/.opencode/skills/truthmark-sync/support/subagents-and-leases.md b/.opencode/skills/truthmark-sync/support/subagents-and-leases.md index 7a9950a..0cf4c73 100644 --- a/.opencode/skills/truthmark-sync/support/subagents-and-leases.md +++ b/.opencode/skills/truthmark-sync/support/subagents-and-leases.md @@ -1,6 +1,6 @@ # Truthmark Sync Subagents And Leases -Generated by Truthmark 1.5.0. Rerun truthmark init after upgrades. +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. OpenCode subagent mode: - use automatically when this workflow runs in OpenCode and the parent agent chooses bounded subagent fan-out diff --git a/AGENTS.md b/AGENTS.md index 8608a6c..78b7068 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,16 +1,16 @@ -Follow `docs/ai/repo-rules.md`. +Follow repository instruction files that are present in this checkout; do not assume optional policy docs exist. -Use that file as the primary repository instruction source for this agent. +Use explicitly configured repository policy docs only when they exist in this checkout. Agent-specific: -- Read `docs/README.md` only when choosing or updating canonical docs. -- Use `docs/ai/agent-onboarding.md` only when task routing is unclear or cross-area. +- Read the configured Truthmark routing files when choosing or updating canonical docs. +- Use repository onboarding or docs-map files only when present and needed for unclear or cross-area routing. ## Truthmark Workflow -Generated by Truthmark 1.5.0. Rerun `truthmark init` after upgrades. -Hierarchy: config .truthmark/config.yml; routes docs/truthmark/areas.md and docs/truthmark/areas/**/*.md; Truth docs: docs/truth/**/*.md. +Generated by Truthmark 1.6.0. Rerun `truthmark init` after upgrades. +Hierarchy hints: config .truthmark/config.yml when present; routes docs/truthmark/areas.md and docs/truthmark/areas/**/*.md when present; Truth docs: docs/truth/**/*.md when present. Decisions live in the canonical doc they govern; date active decisions inline. Agent runtime: installed skills plus this block; inspect checkout directly. Delegation is host-owned. ### Truth Sync diff --git a/CLAUDE.md b/CLAUDE.md index 8608a6c..78b7068 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,16 +1,16 @@ -Follow `docs/ai/repo-rules.md`. +Follow repository instruction files that are present in this checkout; do not assume optional policy docs exist. -Use that file as the primary repository instruction source for this agent. +Use explicitly configured repository policy docs only when they exist in this checkout. Agent-specific: -- Read `docs/README.md` only when choosing or updating canonical docs. -- Use `docs/ai/agent-onboarding.md` only when task routing is unclear or cross-area. +- Read the configured Truthmark routing files when choosing or updating canonical docs. +- Use repository onboarding or docs-map files only when present and needed for unclear or cross-area routing. ## Truthmark Workflow -Generated by Truthmark 1.5.0. Rerun `truthmark init` after upgrades. -Hierarchy: config .truthmark/config.yml; routes docs/truthmark/areas.md and docs/truthmark/areas/**/*.md; Truth docs: docs/truth/**/*.md. +Generated by Truthmark 1.6.0. Rerun `truthmark init` after upgrades. +Hierarchy hints: config .truthmark/config.yml when present; routes docs/truthmark/areas.md and docs/truthmark/areas/**/*.md when present; Truth docs: docs/truth/**/*.md when present. Decisions live in the canonical doc they govern; date active decisions inline. Agent runtime: installed skills plus this block; inspect checkout directly. Delegation is host-owned. ### Truth Sync diff --git a/GEMINI.md b/GEMINI.md index 8608a6c..78b7068 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -1,16 +1,16 @@ -Follow `docs/ai/repo-rules.md`. +Follow repository instruction files that are present in this checkout; do not assume optional policy docs exist. -Use that file as the primary repository instruction source for this agent. +Use explicitly configured repository policy docs only when they exist in this checkout. Agent-specific: -- Read `docs/README.md` only when choosing or updating canonical docs. -- Use `docs/ai/agent-onboarding.md` only when task routing is unclear or cross-area. +- Read the configured Truthmark routing files when choosing or updating canonical docs. +- Use repository onboarding or docs-map files only when present and needed for unclear or cross-area routing. ## Truthmark Workflow -Generated by Truthmark 1.5.0. Rerun `truthmark init` after upgrades. -Hierarchy: config .truthmark/config.yml; routes docs/truthmark/areas.md and docs/truthmark/areas/**/*.md; Truth docs: docs/truth/**/*.md. +Generated by Truthmark 1.6.0. Rerun `truthmark init` after upgrades. +Hierarchy hints: config .truthmark/config.yml when present; routes docs/truthmark/areas.md and docs/truthmark/areas/**/*.md when present; Truth docs: docs/truth/**/*.md when present. Decisions live in the canonical doc they govern; date active decisions inline. Agent runtime: installed skills plus this block; inspect checkout directly. Delegation is host-owned. ### Truth Sync diff --git a/README.md b/README.md index 6ba0c45..b58dfaf 100644 --- a/README.md +++ b/README.md @@ -194,6 +194,7 @@ When the agent changes functional code, Truth Sync acts as the finish-time guard | Local-first operation | Requires no hosted service, daemon, database, or MCP server. | | Safer write boundaries | Separates code-first, doc-first, read-only, and doc-only workflows. | | Validation | Reports routing, authority, frontmatter, link, generated-surface, branch-scope, freshness, and coverage issues. | +| Optional Portal | Generates a committed static HTML presentation site from Markdown truth docs when explicitly enabled and requested. | ## Visual overview @@ -326,6 +327,7 @@ They are used by agents or agent hosts during repository work. They are not top- | Truth Preview | read-only | The agent needs to preview likely routing before edits. | Reads only. Does not authorize writes. | | Truth Realize | doc-first | Product or architecture truth docs lead and code should be updated to match. | Updates code only. The agent must not edit the truth docs it is realizing. | | Truth Check | audit-first | A reviewer or agent needs to audit repository truth health. | Audits and reports. | +| Truthmark Portal | presentation-only | A human explicitly asks for a browsable static HTML Portal over repository truth docs. | Writes generated non-canonical static files only under the configured Portal output directory. | ### Important distinction @@ -437,6 +439,35 @@ They are not sources of truth. Structured output is available with `--json` where supported. +## Truthmark Portal + +Truthmark Portal is an optional presentation workflow for teams that want a human-readable site over their committed truth docs. + +It is deliberately separate from the core truth workflow: + +- Markdown truth docs remain canonical. +- Generated Portal HTML is presentation only. +- Portal is manual-only; it does not run as a completion gate, Truth Sync step, `truthmark check` step, or automatic post-change hook. +- Portal writes stay inside the configured output directory unless the user explicitly changes scope. +- Generated pages should use local assets, source provenance, and a visible Markdown-canonical disclaimer. + +Enable it with the namespaced config block: + +```yaml +truthmark-portal: + enabled: true + output: docs/truthmark-portal + template: default +``` + +Then rerun: + +```bash +truthmark init +``` + +When enabled, Truthmark installs host-native Portal workflow surfaces for the configured platforms, such as `/truthmark-portal` or `/truthmark:portal` depending on the agent host. + ## Configuration Truthmark is config-first. @@ -471,6 +502,7 @@ Important config areas include: | `docs.routing.area_files_root` | Directory for delegated child route files. | | `docs.routing.default_area` | Initial scaffolded child route basename. | | `docs.routing.max_delegation_depth` | Current maximum route delegation depth. | +| `truthmark-portal` | Optional manual presentation workflow settings: `enabled`, `output`, and `template`. | | `authority` | Ordered canonical docs and globs used as repository truth authority. | | `instruction_targets` | Files that receive shared managed instruction blocks, such as `AGENTS.md`. | | `frontmatter.required` | Metadata fields that produce error diagnostics when missing. | @@ -632,6 +664,21 @@ truthmark impact --base main truthmark context --workflow truth-sync --base main --format markdown ``` +### Enable the optional Portal workflow + +```yaml +truthmark-portal: + enabled: true + output: docs/truthmark-portal + template: default +``` + +```bash +truthmark init +``` + +Then explicitly ask the agent host to run the installed Portal workflow when you want the static presentation site generated or refreshed. + ## Project status Truthmark V1 currently provides: @@ -650,6 +697,7 @@ Truthmark V1 currently provides: - generated Truth Preview workflow surfaces - generated Truth Realize workflow surfaces - generated Truth Check workflow surfaces +- optional generated Truthmark Portal workflow surfaces - route, authority, decision-structure, frontmatter, link, freshness, generated-surface, and coverage diagnostics - derived RepoIndex, RouteMap, ImpactSet, and ContextPack artifacts - host-specific surfaces for Codex, Claude Code, GitHub Copilot, OpenCode, and Gemini CLI @@ -712,7 +760,7 @@ It is not: - a hosted service - an MCP server - a vector database -- a documentation website generator +- a canonical documentation website generator or hosted docs platform - a CI or PR enforcement product - a replacement for tests, code review, or technical leadership - an autonomous code rewrite engine diff --git a/changes/2026-05-25-version-160.md b/changes/2026-05-25-version-160.md new file mode 100644 index 0000000..e8cb38b --- /dev/null +++ b/changes/2026-05-25-version-160.md @@ -0,0 +1,28 @@ +# Portal And Host-Native Workflow Surface Updates + +Previous version: 1.4.0 +New version: 1.6.0 +Diff basis: release/1.4.0..HEAD plus working tree +Version action: minor +SemVer rationale: The pending payload adds backward-compatible generated-surface capabilities, including Copilot and Gemini host-native workflow support plus the optional manual Truthmark Portal presentation workflow, and hardens shipped helper validator contracts. + +Release payload: +- Added GitHub Copilot and Gemini CLI host-native workflow surfaces, including skill packages, Gemini subagents, and Gemini command argument support. +- Added the optional manual Truthmark Portal workflow for generating a committed static HTML presentation site from Markdown truth docs when `truthmark-portal.enabled` is set. +- Added Portal config normalization and validation for safe repo-relative output and template settings. +- Reworked helper manifests to use installed Truthmark CLI validator commands instead of repo-local helper scripts. +- Hardened Truth Sync and Truth Document helper-report validation, including failed helper statuses, flexible helper-status whitespace, preserved helper-status parsing, blocked Truth Sync manual-review-file enforcement, and report-body validation before appending a validator's own helper status. +- Wrapped `truthmark validate ... --json` helper output in the standard command envelope under `data.validation`. +- Clarified helper validation status reporting across generated workflow surfaces and README diagrams. +- Parsed `truthmark validate write-lease` inputs structurally as YAML and validated `allowedWrites` / `forbiddenWrites` before applying path-safety and pattern checks. +- Removed hard assumptions that every repository has specific optional policy docs or route files in generated workflow wording. + +User-facing release text: +- Truthmark now installs richer GitHub Copilot and Gemini CLI workflow surfaces, with generated skill packages, Gemini subagents, and command argument support where those hosts support them. +- Repositories can opt into Truthmark Portal, a manual presentation workflow that generates committed static HTML from Markdown truth docs while keeping Markdown canonical. +- Workflow helper validation now runs through installed `truthmark validate ... --json` commands with standard JSON envelopes and stricter report/write-lease validation. +- Generated workflow wording is more portable across repositories that do not use the same optional policy-doc paths. + +Verification: +- `npm run check` passes after the Portal config-validation fixes and generated surface refresh. +- `node dist/main.js check --json` passes with 0 error diagnostics and 0 review diagnostics after rerunning `node dist/main.js init --json`. diff --git a/docs/truth/contracts.md b/docs/truth/contracts.md index 39ad0b5..cc6d196 100644 --- a/docs/truth/contracts.md +++ b/docs/truth/contracts.md @@ -150,6 +150,8 @@ RepoIndex, RouteMap, ImpactSet, and ContextPack are derived from the active chec - `docs.roots.truth` is the configured root for behavior truth docs. - Repositories refresh generated workflow surfaces through `truthmark init`; removing a platform from config stops future refreshes but does not delete previously generated files. - Truth Realize has no config switch; selected platforms receive its explicit manual workflow surface. +- `truthmark-portal` is an optional namespaced config block. When omitted, normalized `truthmarkPortal` is `{ enabled: false, output: "docs/truthmark-portal", template: "default" }`; an existing block with omitted `enabled` also remains disabled. +- `truthmark-portal.output` and `truthmark-portal.template` must be strings when present. Output must be a non-empty repository-relative directory without absolute or parent traversal segments and must not overlap source roots, instruction targets, `.truthmark/config.yml`, route files, or canonical Markdown roots. Template must be `default` or a non-empty repository-relative path without absolute or parent traversal segments. - There is no `.truthmark/local.yml` compatibility surface in the current implementation. ## Config Result Data @@ -200,6 +202,8 @@ Current agent-native scaffold targets include: - `.codex/skills/truthmark-check/agents/openai.yaml` - `.codex/skills/truthmark-preview/SKILL.md` - `.codex/skills/truthmark-preview/agents/openai.yaml` +- `.codex/skills/truthmark-portal/SKILL.md` when Truthmark Portal is enabled +- `.codex/skills/truthmark-portal/agents/openai.yaml` when Truthmark Portal is enabled - `.codex/skills/truthmark-*/support/procedure.md` - `.codex/skills/truthmark-*/support/report-template.md` - `.codex/skills/truthmark-*/support/subagents-and-leases.md` when the workflow has generated subagent guidance @@ -215,6 +219,7 @@ Current agent-native scaffold targets include: - `.claude/skills/truthmark-realize/SKILL.md` - `.claude/skills/truthmark-check/SKILL.md` - `.claude/skills/truthmark-preview/SKILL.md` +- `.claude/skills/truthmark-portal/SKILL.md` when Truthmark Portal is enabled - `.claude/skills/truthmark-*/support/procedure.md` - `.claude/skills/truthmark-*/support/report-template.md` - `.claude/skills/truthmark-*/support/subagents-and-leases.md` when the workflow has generated subagent guidance @@ -230,6 +235,7 @@ Current agent-native scaffold targets include: - `.opencode/skills/truthmark-realize/SKILL.md` - `.opencode/skills/truthmark-check/SKILL.md` - `.opencode/skills/truthmark-preview/SKILL.md` +- `.opencode/skills/truthmark-portal/SKILL.md` when Truthmark Portal is enabled - `.opencode/skills/truthmark-*/support/procedure.md` - `.opencode/skills/truthmark-*/support/report-template.md` - `.opencode/skills/truthmark-*/support/subagents-and-leases.md` when the workflow has generated subagent guidance @@ -248,6 +254,7 @@ Current agent-native scaffold targets include: - `.github/skills/truthmark-realize/SKILL.md` - `.github/skills/truthmark-check/SKILL.md` - `.github/skills/truthmark-preview/SKILL.md` +- `.github/skills/truthmark-portal/SKILL.md` when Truthmark Portal is enabled - `.github/skills/truthmark-*/support/procedure.md` - `.github/skills/truthmark-*/support/report-template.md` - `.github/skills/truthmark-*/support/subagents-and-leases.md` when the workflow has generated subagent guidance @@ -259,6 +266,7 @@ Current agent-native scaffold targets include: - `.github/prompts/truthmark-realize.prompt.md` - `.github/prompts/truthmark-check.prompt.md` - `.github/prompts/truthmark-preview.prompt.md` +- `.github/prompts/truthmark-portal.prompt.md` when Truthmark Portal is enabled - `.github/agents/truth-route-auditor.agent.md` - `.github/agents/truth-claim-verifier.agent.md` - `.github/agents/truth-doc-reviewer.agent.md` @@ -270,6 +278,7 @@ Current agent-native scaffold targets include: - `.gemini/skills/truthmark-realize/SKILL.md` - `.gemini/skills/truthmark-check/SKILL.md` - `.gemini/skills/truthmark-preview/SKILL.md` +- `.gemini/skills/truthmark-portal/SKILL.md` when Truthmark Portal is enabled - `.gemini/skills/truthmark-*/support/procedure.md` - `.gemini/skills/truthmark-*/support/report-template.md` - `.gemini/skills/truthmark-*/support/subagents-and-leases.md` when the workflow has generated subagent guidance @@ -281,6 +290,7 @@ Current agent-native scaffold targets include: - `.gemini/commands/truthmark/realize.toml` - `.gemini/commands/truthmark/check.toml` - `.gemini/commands/truthmark/preview.toml` +- `.gemini/commands/truthmark/portal.toml` when Truthmark Portal is enabled - `.gemini/agents/truth-route-auditor.md` - `.gemini/agents/truth-claim-verifier.md` - `.gemini/agents/truth-doc-reviewer.md` diff --git a/docs/truth/init-and-scaffold.md b/docs/truth/init-and-scaffold.md index 426489d..3129ca1 100644 --- a/docs/truth/init-and-scaffold.md +++ b/docs/truth/init-and-scaffold.md @@ -151,18 +151,21 @@ Current scaffold targets: - `.gemini/commands/truthmark/realize.toml` - `.gemini/commands/truthmark/check.toml` - `.gemini/commands/truthmark/preview.toml` +- `.gemini/commands/truthmark/portal.toml` when Truthmark Portal is enabled - `.gemini/agents/truth-route-auditor.md` - `.gemini/agents/truth-claim-verifier.md` - `.gemini/agents/truth-doc-reviewer.md` - `.gemini/agents/truth-doc-writer.md` `instruction_targets` controls shared managed-instruction files such as `AGENTS.md`. These targets are written or refreshed whenever `truthmark init` runs with a valid config, independent of the configured platform list. -`platforms` controls which platform-specific surfaces are written or refreshed. Defaults include all supported platforms: `codex`, `opencode`, `claude-code`, `github-copilot`, and `gemini-cli`. Teams should remove unused platforms from `.truthmark/config.yml` before rerunning `truthmark init`. Claude Code installs `CLAUDE.md`, project skills under `.claude/skills/`, and verifier plus leased doc-writer subagents under `.claude/agents/`; skills surface as `/truthmark-structure`, `/truthmark-document`, `/truthmark-sync`, `/truthmark-preview`, `/truthmark-realize`, and `/truthmark-check`, while the generated project subagents provide bounded evidence checks and parent-leased truth-doc writes. GitHub Copilot installs `.github/copilot-instructions.md`, agent skills under `.github/skills/`, prompt files under `.github/prompts/`, and verifier plus leased doc-writer custom agents under `.github/agents/`; prompts and skills surface as `/truthmark-structure`, `/truthmark-document`, `/truthmark-sync`, `/truthmark-preview`, `/truthmark-realize`, and `/truthmark-check` in supported Copilot IDEs, while Copilot CLI can dispatch the generated `@truth-*` custom agents for bounded evidence checks or parent-leased doc shards. Gemini installs `GEMINI.md`, Agent Skills under `.gemini/skills/`, project-scoped TOML commands under `.gemini/commands/truthmark/`, and project subagents under `.gemini/agents/`; commands surface as `/truthmark:structure`, `/truthmark:document`, `/truthmark:sync`, `/truthmark:preview`, `/truthmark:realize`, and `/truthmark:check` in Gemini CLI and append `User focus or arguments: {{args}}` near the end of each TOML prompt. Unknown platform names are config errors. Removing a platform stops future refreshes for that platform, but `init` does not delete previously generated files. +`platforms` controls which platform-specific surfaces are written or refreshed. Defaults include all supported platforms: `codex`, `opencode`, `claude-code`, `github-copilot`, and `gemini-cli`. Teams should remove unused platforms from `.truthmark/config.yml` before rerunning `truthmark init`. Claude Code installs `CLAUDE.md`, project skills under `.claude/skills/`, and verifier plus leased doc-writer subagents under `.claude/agents/`; skills surface as `/truthmark-structure`, `/truthmark-document`, `/truthmark-sync`, `/truthmark-preview`, `/truthmark-realize`, and `/truthmark-check`, plus `/truthmark-portal` when Portal is enabled, while the generated project subagents provide bounded evidence checks and parent-leased truth-doc writes. GitHub Copilot installs `.github/copilot-instructions.md`, agent skills under `.github/skills/`, prompt files under `.github/prompts/`, and verifier plus leased doc-writer custom agents under `.github/agents/`; prompts and skills surface as `/truthmark-structure`, `/truthmark-document`, `/truthmark-sync`, `/truthmark-preview`, `/truthmark-realize`, and `/truthmark-check`, plus `/truthmark-portal` when Portal is enabled, in supported Copilot IDEs, while Copilot CLI can dispatch the generated `@truth-*` custom agents for bounded evidence checks or parent-leased doc shards. Gemini installs `GEMINI.md`, Agent Skills under `.gemini/skills/`, project-scoped TOML commands under `.gemini/commands/truthmark/`, and project subagents under `.gemini/agents/`; commands surface as `/truthmark:structure`, `/truthmark:document`, `/truthmark:sync`, `/truthmark:preview`, `/truthmark:realize`, and `/truthmark:check`, plus `/truthmark:portal` when Portal is enabled, in Gemini CLI and append `User focus or arguments: {{args}}` near the end of each TOML prompt. Unknown platform names are config errors. Removing a platform stops future refreshes for that platform, but `init` does not delete previously generated files. `ensureRepoFile` is intentionally conservative: existing non-empty files are left alone. The AGENTS managed block is the exception because Truthmark owns that block and may refresh it to match current template behavior. The generated Truth Structure, Truth Document, Truth Sync, Truth Preview, Truth Realize, and Truth Check explicit surfaces are also managed by Truthmark and may be refreshed on rerun so the Codex skills, metadata, Claude Code project skills, GitHub Copilot skills/prompts/custom agents, Gemini skills/commands/subagents, and OpenCode skills keep matching the installed workflow contract. Generated skill packages keep `SKILL.md` compact and write heavy procedure, report-template, and subagent or lease reference material into sibling `support/*.md` files. Optional helper manifests and helper policy files are emitted only for workflows that declare helpers and only for configured skill-package platforms; helper manifests invoke installed Truthmark CLI validators such as `truthmark validate sync-report --json`, `truthmark validate document-report --json`, and `truthmark validate write-lease --json`. Generated packages do not bundle repo-local `scripts/*.mjs` helper copies. GitHub Copilot prompts and Gemini commands remain standalone entrypoints; their report examples mark helper packages unavailable unless the matching generated skill package is being used. Generated skills, support files, Codex metadata, Copilot prompt files, Copilot custom-agent files, Gemini command files, Gemini subagent files, and managed instruction blocks include the Truthmark package version that rendered them; `package.json` is the single maintained version source. After upgrading Truthmark, rerun `truthmark init` and review generated workflow diffs. +Truthmark Portal surfaces are managed by the same renderer only when normalized `truthmarkPortal.enabled` is `true`. When disabled or omitted, init emits no Portal skills, prompts, commands, or managed-instruction mention. + ## AGENTS Management Rules The current managed-instruction update behavior is: @@ -207,10 +210,11 @@ Important current defaults: - default platforms are `codex`, `opencode`, `claude-code`, `github-copilot`, and `gemini-cli` - shared instruction targets are refreshed independently of platform-specific surfaces - explicit Truth Structure, Truth Document, Truth Sync, Truth Preview, Truth Realize, and Truth Check surfaces are installed only for configured platforms +- Truthmark Portal defaults to disabled; when enabled, Portal surfaces are installed only for configured platforms and use configured output/template values in generated guidance - installed workflows are agent-native; generated skills tell agents to inspect the checkout directly - Codex platform generation includes `.codex/agents/*.toml`, Claude Code platform generation includes `.claude/agents/*.md`, GitHub Copilot platform generation includes `.github/agents/*.agent.md`, Gemini CLI platform generation includes `.gemini/agents/*.md`, and OpenCode platform generation includes `.opencode/agents/*.md` read-only verifier agents plus `truth-doc-writer` for parent-leased Truth Sync and Truth Document shards; the acting parent agent may use them automatically when the host supports subagent dispatch, and read-only verifier agents are context-bounded so they do not preload repo-wide instruction or policy docs unless assigned as evidence - managed instruction blocks include only compact hierarchy, decision-truth, automatic-Sync trigger, boundary reminders, and a pointer to explicit workflows; generated skill entrypoints carry invocation strings and link to support files for detailed workflow bodies -- generated workflow surfaces must not demote repository instruction docs such as [docs/ai/repo-rules.md](../ai/repo-rules.md) when warning agents that product truth cannot override workflow write boundaries +- generated workflow surfaces must not demote configured repository instruction docs or optional project-local policy docs when warning agents that product truth cannot override workflow write boundaries; project-local policy docs are not universal Truthmark product files and generated wording must stay generic and config-driven - scaffolded default standards include AI-native topology repair guidance and an architecture-vs-behavior boundary so new repositories do not rely on human folder discipline - Truth Sync is the only generated skill with implicit invocation enabled because it is the automatic finish-time workflow - `truthmark check` is optional validation for agent workflows, not a required workflow preflight diff --git a/docs/truth/workflows/overview.md b/docs/truth/workflows/overview.md index b3c3589..7af5d10 100644 --- a/docs/truth/workflows/overview.md +++ b/docs/truth/workflows/overview.md @@ -30,6 +30,7 @@ This document owns the shared installed-workflow runtime model and generated hos - Explicit host invocations run manual workflows. - Truth Sync is the only automatic finish-time workflow trigger. - Truth Preview is an explicit read-only selector for likely workflow routing before edits; it is intended, not authorized. +- Truthmark Portal is an opt-in manual-only presentation workflow; it is not a completion gate or Sync/check substitute. ## Inputs @@ -66,6 +67,8 @@ Generated workflow descriptions are routing triggers. They use short positive tr The typed workflow manifest owns generated description text, Codex-facing short descriptions and default prompts, implicit-invocation policy, positive and negative routing examples, forbidden-adjacent cases, required gates, write boundaries, and report-section expectations. Generated host surfaces and deterministic routing tests should consume that manifest rather than duplicating workflow metadata in renderer code. +Truthmark Portal surfaces are generated only when `truthmark-portal.enabled` normalizes to `true`. When enabled, configured platforms receive the `truthmark-portal` skill package, GitHub Copilot receives `.github/prompts/truthmark-portal.prompt.md`, Gemini receives `.gemini/commands/truthmark/portal.toml`, and managed instruction blocks mention Portal with manual-only wording. Portal installs no dedicated subagents in V1. + Truthmark-owned workflow surfaces are generated under host-specific directories. Repo-root `skills/` files are not generated V1 workflow surfaces. Managed instruction blocks are compact automatic-Sync trigger and boundary indexes. They intentionally omit platform-specific invocation strings, non-automatic workflow procedures, report examples, and long checklists. Detailed invocations and procedures live in generated skills, skill support files, prompts, and command files. @@ -84,6 +87,7 @@ Managed instruction blocks are compact automatic-Sync trigger and boundary index - Decision (2026-05-16): Truth Preview is generated as an explicit read-only workflow surface, not an automatic gate, validator, or Truth Check replacement. - Decision (2026-05-16): Generated skill packages use progressive disclosure: `SKILL.md` stays compact for routing and first-step execution, while heavy procedure detail, report examples, and subagent or lease reference material move to generated support files beside the skill. - Decision (2026-05-18): Workflow helpers are optional read-only accelerators declared in generated helper manifests; current helpers are owned by the installed `truthmark` CLI and use argv-style `truthmark validate ... --json` commands rather than packaged script copies. +- Decision (2026-05-25): Truthmark Portal is opt-in and manual-only; generated Portal HTML is a non-canonical human presentation surface and Markdown remains canonical. ## Rationale diff --git a/docs/truth/workflows/truthmark-portal.md b/docs/truth/workflows/truthmark-portal.md new file mode 100644 index 0000000..4d3b185 --- /dev/null +++ b/docs/truth/workflows/truthmark-portal.md @@ -0,0 +1,81 @@ +--- +status: active +doc_type: behavior +truth_kind: workflow +last_reviewed: 2026-05-25 +source_of_truth: + - ../../../src/agents/truthmark-portal.ts + - ../../../src/agents/workflow-manifest.ts + - ../../../src/templates/generated-surfaces.ts + - ../../../src/templates/workflow-surfaces.ts + - ../../../src/templates/agents-block.ts + - ../../../src/config/schema.ts + - ../../../src/config/load.ts +--- + +# Truthmark Portal Workflow + +## Purpose + +Truthmark Portal is an opt-in installed workflow for generating a committed, human-facing, multi-page static HTML presentation site from repository Markdown truth sources. + +## Scope + +This document owns the installed Portal workflow boundary, config toggle, generated surface behavior, and generated-site safety rules. It does not define a deterministic Portal renderer CLI or make generated HTML canonical truth. + +## Triggers + +Portal runs only from an explicit user request to generate, refresh, or update the committed static HTML presentation site. It is not triggered by Truth Sync, `truthmark check`, `truthmark init`, repository indexing, or normal completion workflows. + +## Execution Model + +Portal is an agent-executed workflow that reads Markdown truth sources from the checkout and writes presentation output under the configured Portal output directory. The generated HTML, assets, and metadata are non-canonical; Markdown truth documents remain authoritative. + +## Current Behavior + +`.truthmark/config.yml` may contain a namespaced `truthmark-portal` block. The raw YAML key is exactly `truthmark-portal`; normalized config exposes `truthmarkPortal`. + +When the block is omitted, normalized config defaults to: + +```yaml +enabled: false +output: docs/truthmark-portal +template: default +``` + +If the block exists but `enabled` is omitted, Portal remains disabled. `output` and `template` default independently to `docs/truthmark-portal` and `default`. + +The config schema rejects non-object Portal blocks and non-string `output` or `template` values. Config loading also rejects empty, absolute, or parent-traversing Portal outputs and templates. Portal output must be a repository-relative directory and must not overlap source roots, configured instruction targets, `.truthmark/config.yml`, route files, or canonical Markdown roots. + +`truthmark init` renders Portal surfaces only when `truthmarkPortal.enabled` is `true`. Enabled platform surfaces include Codex, OpenCode, Claude Code, GitHub Copilot, and Gemini skill packages; `.github/prompts/truthmark-portal.prompt.md`; and `.gemini/commands/truthmark/portal.toml`. V1 Portal installs no dedicated subagents or helper agents. + +When Portal is disabled or omitted, init emits no Portal skill, prompt, or command surfaces, and generated managed instruction blocks do not mention Portal. + +Portal is manual-only. It is never a completion gate, never Truth Sync, and runs only when the user explicitly asks to generate, refresh, or update the committed static HTML Portal. + +The workflow reads Markdown directly from the checkout and does not require the `truthmark` CLI or package. `truthmark check` or index commands may be used only as optional supporting evidence when available. Portal has no `.truthmark/index.json` dependency. + +Portal writes generated non-canonical static files only under the configured output directory unless the user explicitly changes scope. The selected output directory may be replaced entirely during generation. + +Generated output should be a committed multi-page static HTML site with local CSS, JavaScript, assets, and search metadata. Generated pages must include source provenance and a visible statement that Markdown remains canonical and generated HTML is presentation only. Manifest and search metadata stay under `/assets`. No remote scripts, analytics, fonts, CSS, or CDN dependencies are used by default. Pictures and screenshots require an explicit user or template request. + +## Product Decisions + +- Decision (2026-05-25): Truthmark Portal is controlled by a namespaced `truthmark-portal` config block rather than a shared optional-workflows list, so enablement, output, and template selection stay together. +- Decision (2026-05-25): Portal is opt-in and manual-only; generated Portal output is a human presentation surface and must not become canonical repository truth or an automatic Sync/check gate. +- Decision (2026-05-25): Portal V1 is agent-native and Markdown-native. It does not introduce a required Portal package, generated `.truthmark/index.json`, or deterministic renderer dependency. + +## Rationale + +Large repositories need a human browsable entrypoint over routed truth docs, but Truthmark's authority model stays Markdown-first. Keeping Portal as an optional installed workflow gives humans a committed static site without changing agent truth sources or normal completion workflows. + +## Non-Goals + +- no automatic Portal generation after code changes +- no canonical HTML truth surface +- no mandatory `truthmark` binary, Portal package, remote service, or `.truthmark/index.json` +- no writes outside the configured Portal output directory by default + +## Maintenance Notes + +Update this document when Portal config, generated surfaces, write boundaries, default output/template behavior, or generated-site safety rules change. diff --git a/docs/truthmark/areas.md b/docs/truthmark/areas.md index b4259a9..9d030e7 100644 --- a/docs/truthmark/areas.md +++ b/docs/truthmark/areas.md @@ -21,6 +21,7 @@ Code surface: - src/cli/** - src/config/command.ts - src/config/defaults.ts +- src/config/load.ts - src/config/schema.ts - src/output/** diff --git a/docs/truthmark/areas/contracts-and-commands.md b/docs/truthmark/areas/contracts-and-commands.md index 063c355..5512abb 100644 --- a/docs/truthmark/areas/contracts-and-commands.md +++ b/docs/truthmark/areas/contracts-and-commands.md @@ -23,6 +23,7 @@ Code surface: - src/cli/** - src/config/command.ts - src/config/defaults.ts +- src/config/load.ts - src/config/schema.ts - src/output/** diff --git a/docs/truthmark/areas/installed-workflows.md b/docs/truthmark/areas/installed-workflows.md index 86943c9..ce0a846 100644 --- a/docs/truthmark/areas/installed-workflows.md +++ b/docs/truthmark/areas/installed-workflows.md @@ -34,6 +34,8 @@ truth_documents: kind: workflow - path: docs/truth/workflows/truth-check.md kind: workflow + - path: docs/truth/workflows/truthmark-portal.md + kind: workflow - path: docs/truth/workflows/content-generation.md kind: workflow ``` diff --git a/package-lock.json b/package-lock.json index beeb41a..238467d 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "truthmark", - "version": "1.5.0", + "version": "1.6.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "truthmark", - "version": "1.5.0", + "version": "1.6.0", "license": "MIT", "dependencies": { "ajv": "^8.17.1", diff --git a/package.json b/package.json index 79ddeb1..9633a20 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "truthmark", - "version": "1.5.0", + "version": "1.6.0", "description": "Git-native, branch-scoped truth workflow installer for local AI coding agents.", "license": "MIT", "type": "module", diff --git a/research/2026-05-25-truthmark-portal-workflow-design.md b/research/2026-05-25-truthmark-portal-workflow-design.md new file mode 100644 index 0000000..2194054 --- /dev/null +++ b/research/2026-05-25-truthmark-portal-workflow-design.md @@ -0,0 +1,821 @@ +# Truthmark Portal Workflow Design + +Status: draft for review + +This is a non-canonical design note. It is intentionally kept under `research/` so it does not redefine current Truthmark behavior until a reviewed decision is promoted into canonical docs and implementation. + +## Decision Summary + +Design `truthmark-portal` as an opt-in, manually triggered, Markdown-native agent workflow that generates a committed multi-page static HTML site for humans. + +Name rationale: **Truthmark Portal** is the strongest V1 name because the feature is a human entrypoint into repository truth: a browsable, publishable doorway to routes, areas, diagrams, and large-project orientation without implying that generated HTML is canonical truth. + +Confirmed product choices: + +1. Generated HTML is committed to the repository. +2. Portal is a full multi-page site, because Truthmark targets large projects. +3. Installation is opt-in only during `truthmark init`. +4. Truthmark Portal uses one namespaced config block, `truthmark-portal`, so the install toggle, output path, and template selection live together. Output path and template selection are V1 features. Repositories can rename the generated output folder and choose a shared committed template so different users generate the same Portal shape. +5. Generated Portal output may include presentation artifacts: HTML pages, diagrams, generated summaries, navigation files, search data, CSS, JavaScript, copied source images, and template-requested assets. Generated pictures and screenshots require an explicit user or template request. +6. The HTML site is for humans only. Markdown remains canonical and agents should not treat generated HTML as repository truth. + +## Problem + +Large projects need a browsable human-facing portal over Truthmark's branch-local Markdown truth docs. A raw tree of route files and truth docs is useful for agents and reviewers, but humans need stronger navigation, summaries, diagrams, and project-level orientation. + +A deterministic `truthmark-portal renderer` CLI/package would either duplicate Truthmark's routing model in another renderer or push the project toward canonical JSON/index artifacts too early. The desired V1 is instead LLM-native: an agent reads Markdown directly, interprets the project structure, and generates a committed static site. + +## Goals + +- Provide an opt-in `truthmark-portal` workflow installable by `truthmark init`. +- Require explicit manual invocation; never run as part of normal Truth Sync, Truth Check, or code-change completion. +- Read canonical Markdown directly from the checkout. +- Generate a committed static multi-page HTML site for human browsing. +- Include a strong default template suitable for large projects. +- Support configurable output path and template selection in V1. +- Allow committed shared templates to request additional generated content such as diagrams, pictures, visual explainers, summary pages, dependency maps, and other static assets. +- Keep generated site metadata disposable and scoped to Portal output. +- Avoid any hard runtime dependency on the `truthmark` package/binary for core generation. + +## Non-Goals + +- Do not make generated HTML canonical truth. +- Do not create `.truthmark/index.json` as required infrastructure. +- Do not create a separate Portal npm package for V1. +- Do not make the workflow automatic after code changes. +- Do not require agents to consume the generated HTML later. +- Do not let generated summaries replace source Markdown. +- Do not require a deterministic semantic index before the workflow is useful. + +## Product Boundary + +Canonical sources remain Markdown in the checkout: + +```text +.truthmark/config.yml +docs/truthmark/areas.md +docs/truthmark/areas/**/*.md +docs/ai/**/*.md +docs/architecture/**/*.md +docs/standards/**/*.md +docs/truth/**/*.md +``` + +Generated presentation output is committed but non-canonical. The default output is: + +```text +docs/truthmark-portal/** +``` + +Repositories may configure a different contained output directory through `truthmark-portal.output`: + +```text +/** +``` + +Every generated page should visibly disclose: + +```text +Generated Truthmark Portal. Markdown files are canonical; this site is presentation only. +``` + +## Configuration + +### Namespaced workflow block + +Use one opt-in namespaced block in `.truthmark/config.yml`: + +```yaml +truthmark-portal: + enabled: false + output: docs/truthmark-portal + template: default +``` + +Default when the block is omitted should be equivalent to the block above: Truthmark Portal is disabled, with default output and template values available after normalization. If `enabled` is omitted inside the block, treat it as `false` so adding shared settings never accidentally installs or runs the workflow. + +Configured example: + +```yaml +truthmark-portal: + enabled: true + output: docs/project-map + template: docs/truthmark/portal-templates/product-docs.md +``` + +`truthmark-portal.enabled` controls whether `truthmark init` installs Truthmark Portal surfaces. + +`truthmark-portal.output` is a repo-relative directory path for generated presentation output. It must stay inside the repository and must not overlap canonical Markdown roots, source roots, or instruction targets. + +`truthmark-portal.template` may be a built-in template ID such as `default` or a repo-relative Markdown file path. Repo-relative template files are committed and shared so different users generate the same Portal style. Template files are instructions for presentation generation only; they are not canonical truth docs. + +### Why a namespaced block instead of `optional_workflows` + +Preferred: + +```yaml +truthmark-portal: + enabled: true + output: docs/project-map + template: docs/truthmark/portal-templates/product-docs.md +``` + +Rejected split shape: + +```yaml +optional_workflows: + - truthmark-portal +portal: + output: docs/project-map + template: docs/truthmark/portal-templates/product-docs.md +``` + +The namespaced block is simpler for users because one feature owns its enable flag and settings. It avoids a split-brain config where installation lives in one key and runtime generation settings live in another. It also scales cleanly if Truthmark Portal later needs additional presentation-only options. + +## Init Behavior + +During `truthmark init`: + +1. Load and normalize config. +2. Generate existing platform surfaces as today. +3. If `truthmark-portal.enabled` is `true`, render `truthmark-portal` skill/prompt/command surfaces for all configured platforms. +4. If not enabled, do not mention or install `truthmark-portal`. + +Default init behavior must remain unchanged for existing users. + +## Workflow Identity + +Add workflow ID: + +```ts +"truthmark-portal" +``` + +Manifest intent: + +```text +Use only when the user explicitly asks to generate, refresh, or update a committed static HTML Truthmark Portal. +``` + +Positive triggers: + +- "generate the Truthmark Portal" +- "refresh the committed HTML docs site" +- "create a browsable project map from Truthmark docs" +- "update docs/truthmark-portal" +- "make a human-readable static site from the truth docs" + +Negative triggers: + +- code changed and truth needs syncing +- route ownership needs repair +- user asks for truth validation/checking +- user asks to document implemented behavior +- user asks to realize docs into code +- user asks for machine-readable agent context + +Manual-only boundary: + +```text +Truthmark Portal is never a completion gate. It runs only when explicitly requested. +``` + +## Installed Surfaces + +When enabled, install host-native workflow surfaces using existing generated-surface machinery. + +Examples: + +```text +.codex/skills/truthmark-portal/SKILL.md +.codex/skills/truthmark-portal/support/procedure.md +.codex/skills/truthmark-portal/support/report-template.md + +.claude/skills/truthmark-portal/SKILL.md +.claude/skills/truthmark-portal/support/procedure.md +.claude/skills/truthmark-portal/support/report-template.md + +.opencode/skills/truthmark-portal/SKILL.md +.opencode/skills/truthmark-portal/support/procedure.md +.opencode/skills/truthmark-portal/support/report-template.md + +.github/skills/truthmark-portal/SKILL.md +.github/prompts/truthmark-portal.prompt.md + +.gemini/skills/truthmark-portal/SKILL.md +.gemini/commands/truthmark/portal.toml +``` + +No dedicated subagents in V1 unless a later implementation needs separate visual-design, diagram, or link-checking specialists. + +## AGENTS Managed Block + +If installed, the generated instruction block may mention Truthmark Portal, but the wording must not imply that Truth Sync can require Truthmark Portal. + +Example wording: + +```md +Explicit workflows: Truth Structure, Truth Document, Truth Preview, Truth Realize, Truth Check. Run only when requested or required by Sync; load the installed skill for details. +Truthmark Portal is a separate manual-only presentation workflow. Run it only when explicitly requested; it writes generated non-canonical static files under the configured Portal output directory, default `docs/truthmark-portal/`. Markdown remains canonical. +``` + +If not installed, do not mention it. + +## Runtime Dependency Rule + +The workflow must not require the `truthmark` binary/package. + +Allowed: + +- Read Markdown directly from the checkout. +- Use shell/filesystem tools to inspect docs. +- Use an LLM to synthesize summaries, navigation, diagrams, and page copy. +- Optionally run `truthmark check --json` or `truthmark index --json` if available, but only as supporting evidence. + +Forbidden: + +- Blocking generation because the `truthmark` CLI is missing. +- Requiring `.truthmark/index.json`. +- Treating a generated index/manifest as canonical routing truth. +- Asking users to install a separate Portal package for V1. + +## Output Directory + +Default committed output: + +```text +docs/truthmark-portal/ +``` + +Rationale: + +- easy to commit +- easy to review in PRs +- easy to publish through GitHub Pages or static hosting +- clearly separate from canonical `docs/truth/**` +- visible to humans browsing the repo + +A repo may override the output path in config or in the user request, but the default should be `docs/truthmark-portal/`. + +## Generated Site Shape + +V1 should generate a multi-page static site optimized for large projects. + +Default structure under the selected output directory: + +```text +/ + index.html + areas/ + index.html + / + index.html + .html + truth/ + index.html + .html + architecture/ + index.html + .html + standards/ + index.html + .html + diagrams/ + index.html + .html + assets/ + style.css + app.js + search-index.json + manifest.json + images/ + .* +``` + +The exact page set can vary by project size and template instructions. + +## Default Human Template + +The default template should help humans answer: + +1. What is this project? +2. What are the major areas? +3. Where do I start? +4. What behavior is owned where? +5. What changed or looks risky? +6. Which source Markdown file backs this page? + +### Default pages + +#### Home page: `index.html` + +Include: + +- project title +- generated-at timestamp +- source branch/commit when available +- short human summary +- major areas grid +- quick links to architecture, standards, truth docs, diagrams, and search +- "Start here" path for new contributors +- source/canonical disclaimer + +#### Area overview: `areas/index.html` + +Include: + +- area tree +- parent/child relationships +- owned code surfaces when available from route docs +- owned truth docs +- stale/missing/ambiguous route notes when detected + +#### Area detail pages + +Each area page should include: + +- purpose of area +- child areas +- code surfaces +- truth docs +- update triggers +- source route Markdown link +- related diagrams and truth pages + +#### Truth doc pages + +Each truth doc page should include: + +- generated summary +- rendered Markdown body or major excerpts +- source path +- owning area when inferable +- related docs +- diagrams or pictures requested by template +- "canonical source" link + +#### Architecture and standards pages + +Include: + +- rendered source Markdown +- generated summary +- relationships to truth docs and areas +- source links + +#### Diagrams index + +Include all generated visual artifacts: + +- project map +- area ownership map +- workflow map +- code-surface-to-truth-doc map +- any template-requested diagrams or pictures + +### Default navigation + +Every page should include: + +- persistent left nav or top nav +- breadcrumb trail +- local table of contents +- source Markdown link +- search box when `assets/search-index.json` exists +- generated/canonical disclaimer + +## Template-Driven Extra Content + +The workflow should support template instructions that request extra generated content. + +Template examples: + +```md +## Extra generated pages + +- Create a Mermaid project ownership diagram. +- Create one architecture explainer page per major area. +- Create onboarding diagrams for new contributors. +- Create a visual map of Truthmark workflows. +- Create one picture/illustration per top-level area if useful. +``` + +Recommended source for shared custom template instructions: + +```text +docs/truthmark/portal-templates/.md +``` + +A repository may also use a single-file convention: + +```text +docs/truthmark/portal-template.md +``` + +or a config-near path when preferred: + +```text +.truthmark/portal-template.md +``` + +The default should work without a custom template, but `truthmark-portal.template` must support repo-relative committed Markdown files so teams can share portal style across users. + +### Template contract + +A template may request: + +- extra HTML pages +- Mermaid diagrams +- SVG diagrams +- generated images/pictures where tools are available +- copied source images +- navigation sections +- summary cards +- glossary pages +- onboarding paths +- contributor guides + +A template must not request: + +- edits to canonical truth docs as part of the portal workflow +- generated files that agents should treat as canonical truth +- destructive rewrites outside the output directory +- hidden external service dependencies + +## Provenance And Staleness Contract + +Committed generated HTML can become stale, so the generated site must make source provenance visible. + +Every generated page should include: + +- generated timestamp +- source branch when available +- source commit when available +- source Markdown path or paths backing the page +- canonical Markdown disclaimer + +The generated manifest should include source provenance for review and stale-output detection: + +```json +{ + "generatedAt": "2026-05-25T00:00:00.000Z", + "sourceBranch": "main", + "sourceCommit": "", + "output": "docs/truthmark-portal", + "template": "default", + "pages": [ + { + "output": "truth/example.html", + "sources": ["docs/truth/example.md"] + } + ] +} +``` + +This manifest is presentation metadata only. It must stay under the generated output directory and must not become repository authority. + +## Generated Metadata + +Generated metadata is allowed, but only as presentation support. + +Allowed examples: + +```text +/assets/manifest.json +/assets/search-index.json +/assets/link-map.json +/assets/page-data/*.json +``` + +These files may support search, navigation, link checking, and client-side browsing. + +Rules: + +- Metadata lives under the generated output directory. +- Metadata is disposable and regenerated with the site. +- Metadata is not canonical repository truth. +- Metadata must not replace `docs/truthmark/areas.md` or truth docs. +- Agents should read source Markdown, not generated Portal metadata, when doing Truthmark work. + +Avoid: + +```text +.truthmark/index.json +.truthmark/index/** +``` + +unless a future deterministic consumer creates a separate reviewed design. + +## HTML And Asset Safety + +Generated static output must be safe to commit and publish. + +Rules: + +- Escape or sanitize rendered Markdown before embedding it in HTML. +- Do not execute code blocks from source Markdown. +- Do not include remote scripts, analytics, fonts, CSS, or CDN dependencies by default. +- Prefer local static CSS and JavaScript under the generated output directory. +- Do not embed secrets, environment variables, access tokens, local absolute paths, or private machine metadata. +- Sanitize generated or embedded SVG/HTML so it cannot execute arbitrary script. +- If source Markdown contains raw HTML, either sanitize it or render it as escaped source content. +- Link copied source images back to their source paths. +- Keep all generated assets and metadata under the configured output directory. + +## Diagrams and Pictures + +The workflow may generate visual artifacts when useful or requested by the template. + +Recommended V1 diagram and image types: + +- Mermaid diagrams embedded in HTML +- SVG diagrams generated from Mermaid or handwritten SVG +- copied existing repo images with attribution/source links +- static PNG/WebP/JPEG images only when explicitly requested by the user or shared template and when image tools are available + +Default generated diagrams: + +1. Project area map +2. Area-to-truth-doc ownership map +3. Workflow overview map +4. Architecture dependency sketch when architecture docs provide enough evidence + +Diagram and image rules: + +- Prefer source-backed diagrams over invented architecture. +- Label uncertain relationships as inferred. +- Link every diagram back to the source Markdown files used. +- Store generated diagram and image assets under the output directory. +- Do not write diagram sources into canonical docs unless the user asks for documentation changes. +- Do not generate decorative pictures or screenshots by default; require an explicit user or template request. + +## Workflow Procedure + +The installed procedure should guide the agent through these steps. + +### 1. Confirm manual invocation + +Proceed only if the user explicitly asked to generate or refresh Truthmark Portal. + +### 2. Inspect config and source docs + +Read: + +1. `.truthmark/config.yml` +2. `docs/ai/repo-rules.md` if present +3. `docs/truthmark/areas.md` +4. `docs/truthmark/areas/**/*.md` +5. `docs/truth/**/*.md` +6. `docs/architecture/**/*.md` +7. `docs/standards/**/*.md` +8. custom Portal template if present + +### 3. Determine output path and template + +Use: + +1. user-requested output path if provided +2. config `truthmark-portal.output` if provided +3. default `docs/truthmark-portal/` + +Validate that the selected output path is repo-relative, inside the repository, and not overlapping canonical Markdown roots, source roots, or instruction targets. + +Use: + +1. user-requested template if provided +2. config `truthmark-portal.template` if provided +3. default template otherwise + +If the selected template is a repo-relative file, read it from the checkout. If it is a built-in template ID such as `default`, use the installed workflow's default template instructions. + +### 4. Plan generated page inventory + +Create a generation plan listing: + +- pages +- diagrams +- pictures/images +- assets +- metadata files +- source Markdown backing each page + +The plan is internal to the workflow report unless the agent needs user confirmation for unusually large output. + +### 5. Generate site + +Generate complete static output under the selected output directory. + +The workflow may replace the entire output directory because it owns generated presentation output. It must not edit files outside that directory except by explicit user request. + +### 6. Validate generated output + +Recommended checks: + +- entry page exists +- all generated HTML files have source/canonical disclaimer +- source Markdown links are present +- generated provenance includes generated timestamp and branch/commit when available +- relative links resolve within the generated site where practical +- major route/truth docs have corresponding pages or reported skips +- generated metadata stays under the output directory +- generated HTML/assets have no default remote scripts, analytics, fonts, CSS, or CDN dependencies +- raw Markdown HTML and generated SVG are sanitized or escaped +- no canonical truth docs were modified accidentally + +If available, optional supporting checks: + +```bash +truthmark check --json +truthmark index --json +``` + +These are helpful but not required for the Portal workflow. + +### 7. Report + +Final report must identify: + +- output path +- page count +- generated diagrams/assets +- source docs reviewed +- skipped/ambiguous docs +- validation performed +- statement that Markdown remains canonical + +## Write Boundaries + +Allowed writes by default: + +```text +docs/truthmark-portal/** +``` + +Allowed if configured or user-requested: + +```text +/** +``` + +The selected output directory must be contained in the repository and must not overlap canonical source or authority surfaces. Reject or block paths that resolve outside the repository, point at source roots, or overlap: + +```text +src/** +docs/ai/** +docs/truthmark/areas.md +docs/truthmark/areas/** +docs/truth/** +docs/architecture/** +docs/standards/** +.truthmark/config.yml +AGENTS.md +CLAUDE.md +GEMINI.md +.github/copilot-instructions.md +``` + +Forbidden unless the user changes the task: + +```text +src/** +docs/truthmark/areas.md +docs/truthmark/areas/**/*.md +docs/truth/**/*.md +docs/architecture/**/*.md +docs/standards/**/*.md +.truthmark/config.yml +AGENTS.md +CLAUDE.md +GEMINI.md +.github/copilot-instructions.md +``` + +The workflow may report issues in canonical docs, but should not repair them. Suggested follow-ups: + +- Truth Structure for routing problems +- Truth Document for missing or stale behavior docs +- Truth Check for validation/audit +- Truth Sync after functional code changes + +## Large Project Strategy + +Because this workflow is designed for large projects, the default site should avoid one giant page. + +Recommended behavior: + +- top-level landing page summarizes the repo +- area index splits navigation by ownership area +- each area gets an overview page +- each truth doc gets a page +- diagrams get their own index +- search index supports client-side lookup +- summaries stay concise and link to source docs +- pages use stable slugs derived from source paths +- generation report lists any docs skipped to keep output bounded + +For very large repos, the workflow can shard pages further: + +```text +/truth//.html +/areas///index.html +``` + +## Source Link and Canonicality Rules + +Every generated page should include: + +- source Markdown path(s) +- generated timestamp +- disclaimer that Markdown is canonical +- link to relevant area route when inferable + +Recommended footer: + +```text +Generated by Truthmark Portal from repository Markdown. This page is presentation only. Source Markdown is canonical. +``` + +## Implementation Touchpoints + +Likely files: + +```text +src/config/schema.ts +src/config/defaults.ts +src/config/load.ts +src/agents/workflow-manifest.ts +src/templates/generated-surfaces.ts +src/templates/workflow-surfaces.ts +src/templates/agents-block.ts +``` + +Config implementation must add a normalized `truthmark-portal` block with `enabled`, `output`, and `template` fields. Invalid field types, unsafe output paths, and invalid template references should fail visibly. + +Potential new files: + +```text +src/agents/truthmark-portal.ts +src/templates/truthmark-portal-default-template.ts +``` + +Tests: + +```text +tests/config/* +tests/init/init.test.ts +tests/agents/workflow-manifest.test.ts +tests/agents/truthmark-portal.test.ts +tests/agents/prompts.test.ts +tests/templates/generated-surfaces.test.ts +``` + +## Acceptance Criteria + +- `truthmark init` with omitted `truthmark-portal` config or `truthmark-portal.enabled: false` does not install Truthmark Portal. +- `truthmark init` with `truthmark-portal.enabled: true` installs Truthmark Portal surfaces for configured platforms. +- Config supports normalized `truthmark-portal.output` and `truthmark-portal.template` so users can rename the generated folder and share templates across users. +- Generated workflow text states manual-only invocation. +- Generated workflow text states Markdown is canonical and HTML is presentation. +- Generated workflow text does not require the `truthmark` binary. +- Generated workflow text defaults output to `docs/truthmark-portal/`. +- Generated workflow text permits configured repo-relative output paths after containment and non-overlap checks. +- Generated workflow text permits multi-page committed static output. +- Generated workflow text permits template-driven extra HTML, diagrams, assets, and presentation metadata under the output directory. +- Generated workflow text requires explicit user or template request for generated pictures or screenshots. +- Generated workflow text requires source provenance on generated pages and in generated manifest metadata. +- Generated workflow text forbids default remote scripts, analytics, fonts, CSS, and CDN dependencies. +- Generated workflow text forbids `.truthmark/index.json` as required infrastructure. +- Generated workflow text instructs agents not to edit canonical truth docs unless the user explicitly changes scope. +- Tests cover opt-in/opt-out generated-surface behavior, output/template config, provenance text, and HTML/asset safety rules. + +## Open Questions Before Implementation + +1. Should the default shared template path convention be `docs/truthmark/portal-template.md`, `docs/truthmark/portal-templates/.md`, or another repo-relative location? +2. Should the workflow replace the entire output directory on each run, or preserve unknown files under the configured output directory? +3. Should the default site include client-side JavaScript search, or stay HTML/CSS-only in V1? + +## Recommended V1 + +Implement the smallest durable version: + +```yaml +truthmark-portal: + enabled: true + output: docs/truthmark-portal + template: default +``` + +Default behavior: + +- install manual-only workflow surfaces +- generate committed multi-page static site under configured `truthmark-portal.output`, default `docs/truthmark-portal/` +- include default large-project human navigation template +- support `truthmark-portal.template` as either a built-in template ID or repo-relative shared Markdown template path +- support template-driven extra pages/assets if a template file is present +- keep generated metadata under `/assets/` +- include page-level and manifest-level source provenance +- enforce static HTML/asset safety rules with no default remote dependencies +- avoid `.truthmark/index.json` +- avoid any required Portal package or CLI + +This gives humans a useful browsable site while preserving Truthmark's core model: branch-local Markdown is canonical, generated surfaces are presentation, and agents inspect the checkout directly. diff --git a/src/agents/instructions.ts b/src/agents/instructions.ts index eef3d02..7d7fd18 100644 --- a/src/agents/instructions.ts +++ b/src/agents/instructions.ts @@ -11,10 +11,10 @@ export const renderTruthStructureInstructions = ( return `### Truth Structure Use when area routing is missing, stale, broad, overloaded, catch-all, unrouteable, or explicitly requested. Invocations: ${TRUTH_STRUCTURE_EXPLICIT_INVOCATIONS} -Inspect repository layout, ${config.docs.routing.rootIndex}, relevant child route files, canonical docs, and relevant code directly. +Inspect repository layout, configured route files when present (${config.docs.routing.rootIndex}; ${config.docs.routing.areaFilesRoot}/), canonical docs, and relevant code directly. Create or repair routing and starter canonical truth docs only when useful. Use only canonical current-truth destinations for starter truth docs. Own topology pressure: split broad/catch-all routing by inferred product or behavior ownership. -If the skill is unavailable, perform the same direct checkout workflow from committed config, route files, docs, and implementation.`; +If the skill is unavailable, perform the same direct checkout workflow from any present config, route files, docs, and implementation.`; }; export const renderTruthCheckInstructions = ( @@ -23,7 +23,7 @@ export const renderTruthCheckInstructions = ( return `### Truth Check Use when the user asks to audit repository truth health. Invocations: ${TRUTH_CHECK_EXPLICIT_INVOCATIONS} -Inspect truth docs, routing, implementation, and ${config.docs.routing.rootIndex} directly. Support findings with checkout evidence, include confidence, run the truthmark check command only when available for additional validation, and inspect the checkout directly when the command is unavailable. Report files reviewed, issues, suggested fixes, evidence checked, and validation.`; +Inspect truth docs, routing, implementation, and configured route files when present (${config.docs.routing.rootIndex}; ${config.docs.routing.areaFilesRoot}/). Support findings with checkout evidence, include confidence, run the truthmark check command only when available for additional validation, and inspect the checkout directly when the command is unavailable. Report files reviewed, issues, suggested fixes, evidence checked, and validation.`; }; export const renderTruthSyncInstructions = ( @@ -40,8 +40,8 @@ Run relevant tests before finishing when functional code changes occurred. Support new or changed behavior-bearing truth claims with checkout evidence and report the evidence reviewed. Truthmark is agent-native: installed skills and this managed block are the workflow runtime. Inspect the checkout directly; truthmark CLI commands are optional validation tools after installation. Code first: code leads; truth docs follow; Truth Sync never rewrites code for alignment. -May write truth docs and ${config.docs.routing.rootIndex} only; must not rewrite functional code. -Read ${config.docs.routing.rootIndex} and only relevant child route files under ${config.docs.routing.areaFilesRoot}/ when routing resolution requires them. +May write truth docs and configured truth routing files (${config.docs.routing.rootIndex}; ${config.docs.routing.areaFilesRoot}/) only when present; must not rewrite functional code. +Read configured route files (${config.docs.routing.rootIndex}; ${config.docs.routing.areaFilesRoot}/) only when they exist and routing resolution requires them. If routing is missing, stale, broad, overloaded, catch-all, or cannot map changed code to a bounded truth owner, run Truth Structure before syncing when repair is safe and in scope; otherwise block and recommend Truth Structure. If mapped truth is missing, extend mapped truth docs first, create an area-local truth doc second, and create a new area only as a last resort. Skip only for: ${TRUTH_SYNC_SKIP_REASONS.join("; ")}.`; diff --git a/src/agents/prompts.ts b/src/agents/prompts.ts index e393f72..e4d2cff 100644 --- a/src/agents/prompts.ts +++ b/src/agents/prompts.ts @@ -22,7 +22,7 @@ export const renderTruthRealizePrompt = ( Only run when the user explicitly asks to realize truth docs into code. This is a manual installed instruction or skill, not a dedicated CLI command. Invocations: OpenCode /skill truthmark-realize; Codex /truthmark-realize or $truthmark-realize; Claude Code /truthmark-realize; GitHub Copilot /truthmark-realize; Gemini CLI /truthmark:realize. Doc first: -- read the updated truth docs plus .truthmark/config.yml, route files, relevant code, and tests +- read the updated truth docs plus any present Truthmark config, route files, relevant code, and tests - ${EVIDENCE_AUTHORITY_INSTRUCTIONS} - ${REPOSITORY_INTELLIGENCE_INSTRUCTIONS} ${renderTruthDocOwnershipGateSection( diff --git a/src/agents/shared.ts b/src/agents/shared.ts index 89cebd3..6053a0a 100644 --- a/src/agents/shared.ts +++ b/src/agents/shared.ts @@ -21,14 +21,14 @@ export const DECISION_TRUTH_INSTRUCTIONS = [ ].join("\n"); export const EVIDENCE_AUTHORITY_INSTRUCTIONS = [ - "Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority.", + "Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path.", "Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries.", ].join("\n"); export const REPOSITORY_INTELLIGENCE_INSTRUCTIONS = [ "Repository intelligence artifacts are optional derived context: RepoIndex, RouteMap, ImpactSet, and ContextPack may guide routing, context selection, and verification planning when available.", "They do not override checkout evidence, canonical truth docs, route files, or workflow write boundaries.", - "If unavailable, inspect .truthmark/config.yml, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated.", + "If unavailable, inspect any present Truthmark config, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated.", ].join("\n"); export const FEATURE_DOC_TEMPLATE_INSTRUCTIONS = [ @@ -272,10 +272,10 @@ export const renderHierarchySummary = (config: TruthmarkConfig): string => { const truthRoot = resolveTruthDocsRoot(config); return [ - "Truthmark hierarchy:", - "- Config: .truthmark/config.yml", - `- Root route index: ${config.docs.routing.rootIndex}`, - `- Area route files: ${config.docs.routing.areaFilesRoot}/**/*.md`, - `- Truth docs: ${truthRoot}/**/*.md`, + "Truthmark hierarchy hints:", + "- Config, when present: .truthmark/config.yml", + `- Root route index, when present: ${config.docs.routing.rootIndex}`, + `- Area route files, when present: ${config.docs.routing.areaFilesRoot}/**/*.md`, + `- Truth docs, when present: ${truthRoot}/**/*.md`, ].join("\n"); }; diff --git a/src/agents/truth-check.ts b/src/agents/truth-check.ts index 8b083e1..0da6d7f 100644 --- a/src/agents/truth-check.ts +++ b/src/agents/truth-check.ts @@ -39,7 +39,7 @@ Fixes suggested: ${renderAuditEvidenceCheckedSection([ { finding: "The root route index is present and maps repository truth owners.", - evidence: [".truthmark/config.yml:1", `${rootRouteIndex}:1`], + evidence: [`${rootRouteIndex}:1`], suggestedFix: "none", confidence: "high", }, @@ -101,11 +101,11 @@ Invocations: ${TRUTH_CHECK_EXPLICIT_INVOCATIONS} Truth Check is agent-led: -- inspect .truthmark/config.yml, ${config.docs.routing.rootIndex}, canonical docs, and relevant implementation directly +- inspect .truthmark/config.yml and configured route files only when they exist; then inspect canonical docs and relevant implementation directly - ${EVIDENCE_AUTHORITY_INSTRUCTIONS} -- inspect the configured root route index at ${config.docs.routing.rootIndex} and relevant child route files under ${config.docs.routing.areaFilesRoot}/ +- inspect the configured root route index at ${config.docs.routing.rootIndex} and relevant child route files under ${config.docs.routing.areaFilesRoot}/ when they exist - check that current docs describe current code rather than historical plans -- check that ${config.docs.routing.rootIndex} routes code surfaces to canonical truth docs +- check that route files map code surfaces to canonical truth docs when route files exist - check for broad, catch-all, index-like, or mixed-owner truth docs and report them as topology issues requiring Truth Structure - check that canonical behavior docs keep active Product Decisions and Rationale sections - optionally run truthmark check when local tooling is available diff --git a/src/agents/truth-document.ts b/src/agents/truth-document.ts index b84e370..601a400 100644 --- a/src/agents/truth-document.ts +++ b/src/agents/truth-document.ts @@ -128,7 +128,7 @@ Invocations: ${TRUTH_DOCUMENT_EXPLICIT_INVOCATIONS} Truth Document is manual and implementation-first: - run only when the user explicitly asks to generate or update truth docs for existing behavior, or when Truth Sync, Truth Check, or Truth Structure reports implemented behavior that lacks canonical truth docs -- inspect .truthmark/config.yml, ${config.docs.routing.rootIndex}, relevant child route files under ${config.docs.routing.areaFilesRoot}/, existing canonical docs, implementation code, and tests directly +- inspect .truthmark/config.yml and configured route files only when they exist; then inspect existing canonical docs, implementation code, and tests directly - ${EVIDENCE_AUTHORITY_INSTRUCTIONS} - document current implemented behavior; do not invent future behavior or planned endpoints - may write canonical truth docs and ${config.docs.routing.rootIndex} or relevant child route files only diff --git a/src/agents/truth-preview.ts b/src/agents/truth-preview.ts index 519e15f..72d9132 100644 --- a/src/agents/truth-preview.ts +++ b/src/agents/truth-preview.ts @@ -81,9 +81,9 @@ Purpose: - keep the selector thin so agents can avoid loading or acting through heavier workflows prematurely Read: -- .truthmark/config.yml -- ${config.docs.routing.rootIndex} -- relevant child route files under ${config.docs.routing.areaFilesRoot}/ +- .truthmark/config.yml, only when present +- ${config.docs.routing.rootIndex}, only when present +- relevant child route files under ${config.docs.routing.areaFilesRoot}/, only when present - relevant truth docs and implementation files needed to preview ownership - ${EVIDENCE_AUTHORITY_INSTRUCTIONS} diff --git a/src/agents/truth-structure.ts b/src/agents/truth-structure.ts index aa1de2c..55be542 100644 --- a/src/agents/truth-structure.ts +++ b/src/agents/truth-structure.ts @@ -97,9 +97,9 @@ truthmark-version: ${TRUTHMARK_VERSION} Use this skill to design or repair Truthmark area structure. Invocations: ${TRUTH_STRUCTURE_EXPLICIT_INVOCATIONS} Truth Structure is agent-native: -- inspect repository layout, current docs, .truthmark/config.yml, ${config.docs.routing.rootIndex}, and relevant code directly +- inspect repository layout, current docs, Truthmark config and route files when present, and relevant code directly - ${EVIDENCE_AUTHORITY_INSTRUCTIONS} -- inspect the configured root route index at ${config.docs.routing.rootIndex} and relevant child route files under ${config.docs.routing.areaFilesRoot}/ +- inspect the configured root route index at ${config.docs.routing.rootIndex} and relevant child route files under ${config.docs.routing.areaFilesRoot}/ when they exist - define areas by product or behavior ownership, not by mechanical directory mirroring - create or repair ${config.docs.routing.rootIndex} - create starter truth docs when useful and when they belong in the canonical current-truth surface @@ -170,7 +170,7 @@ ${ARCHITECTURE_DOC_BOUNDARY_INSTRUCTIONS} Portable fallback: - If this skill surface is unavailable, perform the same workflow directly from committed repository files. - Do not require the truthmark CLI. -- Read .truthmark/config.yml, ${config.docs.routing.rootIndex}, relevant child route files under ${config.docs.routing.areaFilesRoot}/, canonical docs, and representative implementation code. +- Inspect .truthmark/config.yml and configured route files only when they exist; then inspect canonical docs and representative implementation code. - Use a subagent only when the host supports that pattern; otherwise perform the topology repair inline. ${renderHierarchySummary(config)} ${DECISION_TRUTH_INSTRUCTIONS} diff --git a/src/agents/truth-sync.ts b/src/agents/truth-sync.ts index e5e03c9..142db13 100644 --- a/src/agents/truth-sync.ts +++ b/src/agents/truth-sync.ts @@ -39,7 +39,7 @@ The parent provides the task focus, explicit write lease, and any repository con Worker rules: - require a write lease with workflow, worker, shard, objective, requiredReads, allowedWrites, forbiddenWrites, evidenceRequired, verification, and reportFields before editing - inspect relevant staged, unstaged, and untracked functional code directly -- read .truthmark/config.yml, ${config.docs.routing.rootIndex}, and canonical truth docs directly +- inspect .truthmark/config.yml and configured route files (${config.docs.routing.rootIndex}; ${config.docs.routing.areaFilesRoot}/) only when they exist; then inspect canonical truth docs directly - Code verification is parent-owned; report what was run or why it was not run - may write only leased truth docs and leased truth routing files for Truth Sync alignment - must not rewrite functional code or generated host surfaces @@ -118,7 +118,7 @@ Explicit invocation runs immediately. Later functional-code changes reopen the f Skip when changes are documentation-only, formatting-only, clearly behavior-preserving renames with no truth impact, when no Truthmark config exists yet, or when there are no functional code changes. Parent workflow: 1. Inspect git status, staged changes, unstaged changes, and untracked files directly. -2. Read .truthmark/config.yml, the configured root route index at ${config.docs.routing.rootIndex}, relevant child route files under ${config.docs.routing.areaFilesRoot}/, and relevant canonical docs. +2. Inspect .truthmark/config.yml and configured route files only when they exist; then inspect relevant canonical docs. 3. Identify functional-code changes and the nearest truth docs or routing repairs. 4. ${EVIDENCE_AUTHORITY_INSTRUCTIONS} 5. Code verification is parent-owned: follow repository instructions and task context, and report what ran or why it did not run. diff --git a/src/agents/truthmark-portal.ts b/src/agents/truthmark-portal.ts new file mode 100644 index 0000000..ef48cbb --- /dev/null +++ b/src/agents/truthmark-portal.ts @@ -0,0 +1,84 @@ +import type { TruthmarkConfig } from "../config/schema.js"; +import { TRUTHMARK_VERSION } from "../version.js"; +import { defaultAgentConfig, renderHierarchySummary } from "./shared.js"; +import { getTruthmarkWorkflow } from "./workflow-manifest.js"; + +export const TRUTHMARK_PORTAL_EXPLICIT_INVOCATIONS = + "OpenCode /skill truthmark-portal; Codex /truthmark-portal or $truthmark-portal; Claude Code /truthmark-portal; GitHub Copilot /truthmark-portal; Gemini CLI /truthmark:portal."; + +export const renderTruthmarkPortalSkillBody = ( + config: TruthmarkConfig = defaultAgentConfig(), +): string => { + const workflow = getTruthmarkWorkflow("truthmark-portal"); + const output = config.truthmarkPortal.output; + const template = config.truthmarkPortal.template; + + return `--- +name: truthmark-portal +description: ${workflow.description} +argument-hint: Optional output path, template, or portal generation focus +user-invocable: true +truthmark-version: ${TRUTHMARK_VERSION} +--- + +# Truthmark Portal + +Truthmark Portal is a manual-only presentation workflow. It is never a completion gate, never Truth Sync, and runs only when the user explicitly asks to generate, refresh, or update the committed static HTML Portal. + +Invocations: ${TRUTHMARK_PORTAL_EXPLICIT_INVOCATIONS} + +Core rules: + +- Markdown remains canonical; generated HTML is presentation only. +- Read Markdown directly from the checkout; the workflow does not require the truthmark CLI or package. +- truthmark check/index may be used only as optional supporting evidence when available. +- Default output is docs/truthmark-portal; configured output is ${output}. +- Configured template is ${template}; use default built-in template instructions when the template is default. +- The workflow may replace the entire output directory, but writes are limited to the configured Portal output directory only unless the user changes scope. +- Portal writes are generated non-canonical static files for human browsing. +- Generate a committed multi-page static HTML site with local CSS, JavaScript, assets, and search metadata under the output directory. +- Use no remote dependencies by default: no remote scripts, analytics, fonts, CSS, or CDN assets. +- Include source provenance and the Markdown canonical disclaimer on every page. +- Store manifest and search data under output/assets only. +- There is no .truthmark/index.json dependency; do not require or create it as infrastructure. +- Pictures and screenshots require an explicit user or template request. + +Workflow: + +1. Confirm the user explicitly requested Portal generation or refresh. +2. Inspect .truthmark/config.yml and configured route docs only when they exist; read repository instruction files when present, truth docs, architecture docs, standards docs, and the configured Portal template when it is a repo-relative file. +3. Validate the selected output path is repo-relative, non-empty, inside the repository, and does not overlap canonical docs, source roots, routing files, or instruction targets. +4. Plan the generated page inventory, diagrams/assets, source docs reviewed, and skipped or ambiguous docs. +5. Replace or write only under ${output}; do not edit canonical Markdown, routing, source code, or instruction files unless the user explicitly changes scope. +6. Generate the multi-page static site with local assets/search metadata and visible source provenance. +7. Validate entry page, links where practical, provenance/disclaimers, local-only assets, and that metadata remains under ${output}/assets. +${renderHierarchySummary(config)} + +Report completion in this shape: + +\`\`\`md +Truthmark Portal: completed + +Output path: +- ${output} + +Page count: +- + +Diagrams/assets: +- + +Source docs reviewed: +- + +Skipped/ambiguous docs: +- + +Validation: +- + +Markdown canonical statement: +- Markdown remains canonical; generated Portal HTML is non-canonical presentation only. +\`\`\` +`; +}; diff --git a/src/agents/workflow-manifest.ts b/src/agents/workflow-manifest.ts index 9b8001f..750eccf 100644 --- a/src/agents/workflow-manifest.ts +++ b/src/agents/workflow-manifest.ts @@ -6,7 +6,8 @@ export type TruthmarkWorkflowId = | "truthmark-document" | "truthmark-preview" | "truthmark-realize" - | "truthmark-check"; + | "truthmark-check" + | "truthmark-portal"; export type TruthmarkReadOnlySubagentId = | "truth_route_auditor" @@ -338,6 +339,52 @@ export const TRUTHMARK_WORKFLOW_MANIFEST = { "truth_doc_reviewer", ], }, + "truthmark-portal": { + id: "truthmark-portal", + displayName: "Truthmark Portal", + description: + "Use when the user explicitly asks to generate, refresh, or update the Truthmark Portal static HTML site. Not for code change sync, route repair, truth validation/checking, documenting behavior, realizing docs into code, or machine-readable agent context.", + shortDescription: "Generate a committed static HTML Truthmark Portal", + defaultPrompt: + "Use $truthmark-portal only when explicitly asked to generate or refresh the committed static HTML Portal.", + allowImplicitInvocation: false, + positiveTriggers: [ + "generate the Truthmark Portal", + "refresh the committed HTML docs site", + "create a browsable project map from Truthmark docs", + "update docs/truthmark-portal", + "make a human-readable static site from the truth docs", + ], + negativeTriggers: [ + "code change sync", + "route ownership repair", + "truth validation or checking", + "document implemented behavior", + "realize docs into code", + "machine-readable agent context", + ], + forbiddenAdjacency: [ + "must not run as a completion gate", + "must not replace Truth Sync, Truth Check, Truth Document, Truth Realize, or Truth Structure", + "must not write outside the configured Portal output directory unless the user changes scope", + ], + requiredGates: [ + "manual-only invocation", + "Portal output containment", + "Markdown canonical statement", + "source provenance", + ], + allowedWrites: ["configured Portal output directory only"], + reportSections: [ + "Output path", + "Page count", + "Diagrams/assets", + "Source docs reviewed", + "Skipped/ambiguous docs", + "Validation", + "Markdown canonical statement", + ], + }, } satisfies Record; export const TRUTHMARK_WORKFLOW_IDS = Object.keys( diff --git a/src/config/defaults.ts b/src/config/defaults.ts index 42bbdcd..57f665f 100644 --- a/src/config/defaults.ts +++ b/src/config/defaults.ts @@ -27,6 +27,12 @@ export const DEFAULT_AUTHORITY = [ export const DEFAULT_INSTRUCTION_TARGETS = ["AGENTS.md"] as const; +export const DEFAULT_TRUTHMARK_PORTAL = { + enabled: false, + output: "docs/truthmark-portal", + template: "default", +} as const; + export const createDefaultRawConfig = () => ({ version: 1 as const, platforms: [...DEFAULT_PLATFORMS], @@ -59,6 +65,7 @@ export const createDefaultConfig = (): TruthmarkConfig => ({ }, authority: [...DEFAULT_AUTHORITY], instructionTargets: [...DEFAULT_INSTRUCTION_TARGETS], + truthmarkPortal: { ...DEFAULT_TRUTHMARK_PORTAL }, frontmatter: { required: [], recommended: ["status", "doc_type", "last_reviewed", "source_of_truth"], diff --git a/src/config/load.ts b/src/config/load.ts index 844982e..8026d2f 100644 --- a/src/config/load.ts +++ b/src/config/load.ts @@ -1,4 +1,5 @@ import fs from "node:fs/promises"; +import path from "node:path"; import { Ajv, type ErrorObject } from "ajv"; import { parse } from "yaml"; @@ -8,6 +9,7 @@ import { resolveRepoPath } from "../fs/paths.js"; import { DEFAULT_DOCS_HIERARCHY, DEFAULT_INSTRUCTION_TARGETS, + DEFAULT_TRUTHMARK_PORTAL, } from "./defaults.js"; import { DEFAULT_PLATFORMS, @@ -35,6 +37,103 @@ const toConfigDiagnostic = (message: string, file: string): Diagnostic => { }; }; +const normalizeRepoRelativePath = (value: string): string => { + const slashNormalized = value.replace(/\\/gu, "/"); + const pathNormalized = path.posix.normalize(slashNormalized).replace(/\/+$/u, ""); + + return pathNormalized; +}; + +const isUnsafeRepoRelativePath = (value: string): boolean => { + const slashNormalized = value.replace(/\\/gu, "/"); + const normalized = normalizeRepoRelativePath(value); + const parts = slashNormalized.split("/"); + + return ( + normalized.length === 0 || + normalized === "." || + normalized === ".." || + path.isAbsolute(value) || + path.posix.isAbsolute(slashNormalized) || + path.win32.isAbsolute(value) || + /^[A-Za-z]:/u.test(value) || + normalized.startsWith("../") || + parts.includes("..") + ); +}; + +const pathsOverlap = (left: string, right: string): boolean => { + const normalizedLeft = normalizeRepoRelativePath(left); + const normalizedRight = normalizeRepoRelativePath(right); + + return ( + normalizedLeft === normalizedRight || + normalizedLeft.startsWith(`${normalizedRight}/`) || + normalizedRight.startsWith(`${normalizedLeft}/`) + ); +}; + +const portalForbiddenOutputRoots = (rawConfig: RawTruthmarkConfig): string[] => { + const rawDocs = rawConfig.docs; + const docsRoots = rawDocs?.roots ?? {}; + const routing = rawDocs?.routing ?? DEFAULT_DOCS_HIERARCHY.routing; + + return [ + "src", + DEFAULT_DOCS_HIERARCHY.roots.ai, + DEFAULT_DOCS_HIERARCHY.roots.standards, + DEFAULT_DOCS_HIERARCHY.roots.architecture, + DEFAULT_DOCS_HIERARCHY.roots.truth, + ...Object.values(docsRoots), + routing.root_index, + routing.area_files_root, + ".truthmark/config.yml", + "AGENTS.md", + "CLAUDE.md", + "GEMINI.md", + ".github/copilot-instructions.md", + ...(rawConfig.instruction_targets ?? DEFAULT_INSTRUCTION_TARGETS), + ]; +}; + +const validatePortalConfig = ( + rawConfig: RawTruthmarkConfig, + configPath: string, +): Diagnostic[] => { + const portal = rawConfig["truthmark-portal"]; + + if (portal === undefined) { + return []; + } + + const diagnostics: Diagnostic[] = []; + const output = portal.output ?? DEFAULT_TRUTHMARK_PORTAL.output; + const template = portal.template ?? DEFAULT_TRUTHMARK_PORTAL.template; + + if ( + isUnsafeRepoRelativePath(output) || + portalForbiddenOutputRoots(rawConfig).some((forbidden) => pathsOverlap(output, forbidden)) + ) { + diagnostics.push( + toConfigDiagnostic( + "truthmark-portal.output must be a non-empty repo-relative directory that does not overlap source, instruction, routing, or canonical docs roots.", + configPath, + ), + ); + } + + if (template !== "default" && isUnsafeRepoRelativePath(template)) { + diagnostics.push( + toConfigDiagnostic( + "truthmark-portal.template must be 'default' or a non-empty repo-relative template path without absolute or parent traversal segments.", + configPath, + ), + ); + } + + return diagnostics; +}; + const normalizeConfig = (rawConfig: RawTruthmarkConfig): TruthmarkConfig => { const rawDocs = rawConfig.docs ?? { layout: DEFAULT_DOCS_HIERARCHY.layout, @@ -58,6 +157,11 @@ const normalizeConfig = (rawConfig: RawTruthmarkConfig): TruthmarkConfig => { }, authority: rawConfig.authority, instructionTargets: rawConfig.instruction_targets ?? [...DEFAULT_INSTRUCTION_TARGETS], + truthmarkPortal: { + enabled: rawConfig["truthmark-portal"]?.enabled ?? DEFAULT_TRUTHMARK_PORTAL.enabled, + output: rawConfig["truthmark-portal"]?.output ?? DEFAULT_TRUTHMARK_PORTAL.output, + template: rawConfig["truthmark-portal"]?.template ?? DEFAULT_TRUTHMARK_PORTAL.template, + }, frontmatter: { required: rawConfig.frontmatter?.required ?? [], recommended: rawConfig.frontmatter?.recommended ?? [], @@ -127,6 +231,20 @@ export const loadConfig = async (rootDir: string): Promise => }; } + const portalDiagnostics = validatePortalConfig( + parsedConfig as RawTruthmarkConfig, + configPath, + ); + + if (portalDiagnostics.length > 0) { + return { + status: "invalid", + config: null, + diagnostics: portalDiagnostics, + configPath, + }; + } + return { status: "loaded", config: normalizeConfig(parsedConfig as RawTruthmarkConfig), diff --git a/src/config/schema.ts b/src/config/schema.ts index 33c7493..b1b9c5c 100644 --- a/src/config/schema.ts +++ b/src/config/schema.ts @@ -41,12 +41,25 @@ export type DocsHierarchyConfig = { }; }; +export type RawTruthmarkPortalConfig = { + enabled?: boolean; + output?: string; + template?: string; +}; + +export type TruthmarkPortalConfig = { + enabled: boolean; + output: string; + template: string; +}; + export type RawTruthmarkConfig = { version: 1; platforms?: TruthmarkPlatform[]; docs?: RawDocsHierarchyConfig; authority: string[]; instruction_targets?: string[]; + "truthmark-portal"?: RawTruthmarkPortalConfig; frontmatter?: { required?: string[]; recommended?: string[]; @@ -60,6 +73,7 @@ export type TruthmarkConfig = { docs: DocsHierarchyConfig; authority: string[]; instructionTargets: string[]; + truthmarkPortal: TruthmarkPortalConfig; frontmatter: { required: string[]; recommended: string[]; @@ -67,7 +81,7 @@ export type TruthmarkConfig = { ignore: string[]; }; -export const truthmarkConfigSchema: JSONSchemaType = { +export const truthmarkConfigSchema = { type: "object", additionalProperties: false, required: ["version", "authority"], @@ -138,6 +152,22 @@ export const truthmarkConfigSchema: JSONSchemaType = { type: "string", }, }, + "truthmark-portal": { + type: "object", + additionalProperties: false, + required: [], + properties: { + enabled: { + type: "boolean", + }, + output: { + type: "string", + }, + template: { + type: "string", + }, + }, + }, frontmatter: { type: "object", nullable: true, @@ -168,4 +198,4 @@ export const truthmarkConfigSchema: JSONSchemaType = { }, }, }, -}; +} as unknown as JSONSchemaType; diff --git a/src/init/init.ts b/src/init/init.ts index 06cabdc..75b79e0 100644 --- a/src/init/init.ts +++ b/src/init/init.ts @@ -68,20 +68,49 @@ const removeTrailingManagedChunk = (preservedLines: string[]): void => { } }; +const LEGACY_REPO_RULES_PATH = ["docs", "ai", `repo-${"rules.md"}`].join("/"); +const LEGACY_AGENT_ONBOARDING_PATH = ["docs", "ai", `agent-${"onboarding.md"}`].join( + "/", +); +const LEGACY_PRIMARY_REPO_INSTRUCTION_PHRASE = [ + "primary repository", + "instruction source", +].join(" "); + const normalizeLegacyInstructionPreamble = (content: string): string => { return content .replaceAll( - "Use that file as the primary repository instruction source for Codex.", - "Use that file as the primary repository instruction source for this agent.", + `Follow \`${LEGACY_REPO_RULES_PATH}\`.`, + "Follow repository instruction files that are present in this checkout; do not assume optional policy docs exist.", + ) + .replaceAll( + `Follow \`${LEGACY_REPO_RULES_PATH}\` as the ${LEGACY_PRIMARY_REPO_INSTRUCTION_PHRASE}.`, + "Follow repository instruction files that are present in this checkout; do not assume optional policy docs exist.", + ) + .replaceAll( + `Use that file as the ${LEGACY_PRIMARY_REPO_INSTRUCTION_PHRASE} for Codex.`, + "Use explicitly configured repository policy docs only when they exist in this checkout.", + ) + .replaceAll( + `Use that file as the ${LEGACY_PRIMARY_REPO_INSTRUCTION_PHRASE} for this agent.`, + "Use explicitly configured repository policy docs only when they exist in this checkout.", ) .replaceAll("Codex-specific:", "Agent-specific:") .replaceAll( "- Read `docs/README.md` for the canonical docs map.", - "- Read `docs/README.md` only when choosing or updating canonical docs.", + "- Read the configured Truthmark routing files when choosing or updating canonical docs.", ) .replaceAll( - "- Use `docs/ai/agent-onboarding.md` for quick task routing.", - "- Use `docs/ai/agent-onboarding.md` only when task routing is unclear or cross-area.", + "- Read `docs/README.md` only when choosing or updating canonical docs.", + "- Read the configured Truthmark routing files when choosing or updating canonical docs.", + ) + .replaceAll( + `- Use \`${LEGACY_AGENT_ONBOARDING_PATH}\` for quick task routing.`, + "- Use repository onboarding or docs-map files only when present and needed for unclear or cross-area routing.", + ) + .replaceAll( + `- Use \`${LEGACY_AGENT_ONBOARDING_PATH}\` only when task routing is unclear or cross-area.`, + "- Use repository onboarding or docs-map files only when present and needed for unclear or cross-area routing.", ); }; @@ -183,41 +212,39 @@ const diagnosticCategoryForPath = ( return "truth-sync"; } + if ( + filePath === ".github/prompts/truthmark-realize.prompt.md" || + filePath.startsWith(".github/skills/truthmark-realize/") || + filePath.startsWith(".claude/skills/truthmark-realize/") || + filePath.startsWith(".opencode/skills/truthmark-realize/") || + filePath.startsWith(".codex/skills/truthmark-realize/") || + filePath.startsWith(".gemini/skills/truthmark-realize/") + ) { + return "realization"; + } + if ( filePath === "CLAUDE.md" || filePath === "GEMINI.md" || filePath === ".github/copilot-instructions.md" || filePath.startsWith(".github/prompts/truthmark-") || filePath.startsWith(".github/agents/truth-") || + filePath.startsWith(".github/skills/truthmark-") || filePath.startsWith(".claude/agents/truth-") || filePath.startsWith(".claude/skills/truthmark-") || filePath.startsWith(".opencode/skills/truthmark-") || filePath.startsWith(".opencode/agents/") || - filePath.startsWith(".codex/agents/") + filePath.startsWith(".codex/agents/") || + filePath.startsWith(".gemini/agents/truth-") || + filePath.startsWith(".gemini/skills/truthmark-") ) { return "truth-sync"; } - if (filePath.startsWith(".codex/skills/truthmark-structure/")) { + if (filePath.startsWith(".codex/skills/truthmark-")) { return "truth-sync"; } - if (filePath.startsWith(".codex/skills/truthmark-document/")) { - return "truth-sync"; - } - - if (filePath.startsWith(".codex/skills/truthmark-sync/")) { - return "truth-sync"; - } - - if (filePath.startsWith(".codex/skills/truthmark-preview/")) { - return "truth-sync"; - } - - if (filePath.startsWith(".codex/skills/truthmark-realize/")) { - return "realization"; - } - if (filePath.startsWith(".gemini/commands/truthmark/realize")) { return "realization"; } @@ -226,10 +253,6 @@ const diagnosticCategoryForPath = ( return "truth-sync"; } - if (filePath.startsWith(".codex/skills/truthmark-check/")) { - return "truth-sync"; - } - if (filePath === config.docs.routing.rootIndex) { return "authority"; } diff --git a/src/templates/agents-block.ts b/src/templates/agents-block.ts index ec8d292..b1ac876 100644 --- a/src/templates/agents-block.ts +++ b/src/templates/agents-block.ts @@ -7,20 +7,24 @@ export const TRUTHMARK_BLOCK_END = ""; export const renderInstructionPreamble = (): string => { return [ - "Follow `docs/ai/repo-rules.md` as the primary repository instruction source.", - "Read `docs/README.md` only when choosing or updating canonical docs.", - "Use `docs/ai/agent-onboarding.md` only when task routing is unclear or cross-area.", + "Follow repository instruction files that are present in this checkout; do not assume optional policy docs exist.", + "Read the configured Truthmark routing files when choosing or updating canonical docs.", + "Use repository onboarding or docs-map files only when present and needed for unclear or cross-area routing.", ].join("\n"); }; const renderCompactHierarchySummary = (config: TruthmarkConfig): string => { const truthRoot = resolveTruthDocsRoot(config); - return `Hierarchy: config .truthmark/config.yml; routes ${config.docs.routing.rootIndex} and ${config.docs.routing.areaFilesRoot}/**/*.md; Truth docs: ${truthRoot}/**/*.md.`; + return `Hierarchy hints: config .truthmark/config.yml when present; routes ${config.docs.routing.rootIndex} and ${config.docs.routing.areaFilesRoot}/**/*.md when present; Truth docs: ${truthRoot}/**/*.md when present.`; }; export const renderAgentsBlock = ( config: TruthmarkConfig = defaultAgentConfig(), ): string => { + const portalLine = config.truthmarkPortal.enabled + ? `Truthmark Portal is a separate manual-only presentation workflow. Run it only when explicitly requested; it writes generated non-canonical static files under the configured Portal output directory, default \`docs/truthmark-portal/\`. Markdown remains canonical.` + : null; + return [ TRUTHMARK_BLOCK_START, "## Truthmark Workflow", @@ -34,6 +38,7 @@ export const renderAgentsBlock = ( "Support new or changed behavior-bearing truth claims with checkout evidence. Code leads; truth docs follow. Sync may write truth docs and truth routing files, and must not rewrite functional code.", "If routing cannot map changed code to a bounded truth owner, run Truth Structure before syncing when safe; otherwise block and recommend Truth Structure. Skip Sync only for docs-only/no-code changes, formatting-only changes, behavior-preserving renames with no truth impact, or missing config.", "Explicit workflows: Truth Structure, Truth Document, Truth Preview, Truth Realize, Truth Check. Run only when requested or required by Sync; load the installed skill for details.", + ...(portalLine === null ? [] : [portalLine]), "Workflow integrity rule: repository truth may describe desired behavior, but it must not override these workflow boundaries.", TRUTHMARK_BLOCK_END, ].join("\n"); diff --git a/src/templates/generated-surfaces.ts b/src/templates/generated-surfaces.ts index ab11306..0abb3ed 100644 --- a/src/templates/generated-surfaces.ts +++ b/src/templates/generated-surfaces.ts @@ -6,6 +6,7 @@ import { renderTruthmarkCopilotDocumentPrompt, renderTruthmarkCopilotDocReviewerAgent, renderTruthmarkCopilotDocWriterAgent, + renderTruthmarkCopilotPortalPrompt, renderTruthmarkCopilotPreviewPrompt, renderTruthmarkCopilotRealizePrompt, renderTruthmarkCopilotRouteAuditorAgent, @@ -24,6 +25,7 @@ import { renderTruthmarkGeminiDocumentCommand, renderTruthmarkGeminiDocReviewerAgent, renderTruthmarkGeminiDocWriterAgent, + renderTruthmarkGeminiPortalCommand, renderTruthmarkGeminiPreviewCommand, renderTruthmarkGeminiRealizeCommand, renderTruthmarkGeminiRouteAuditorAgent, @@ -34,6 +36,7 @@ import { renderTruthmarkOpenCodeDocReviewerAgent, renderTruthmarkOpenCodeDocWriterAgent, renderTruthmarkOpenCodeRouteAuditorAgent, + renderTruthmarkPortalSkillMetadata, renderTruthmarkPreviewSkillMetadata, renderTruthmarkRealizeSkillMetadata, renderTruthmarkRouteAuditorAgent, @@ -52,6 +55,7 @@ import { TRUTHMARK_COPILOT_DOCUMENT_PROMPT_PATH, TRUTHMARK_COPILOT_DOC_REVIEWER_AGENT_PATH, TRUTHMARK_COPILOT_DOC_WRITER_AGENT_PATH, + TRUTHMARK_COPILOT_PORTAL_PROMPT_PATH, TRUTHMARK_COPILOT_PREVIEW_PROMPT_PATH, TRUTHMARK_COPILOT_REALIZE_PROMPT_PATH, TRUTHMARK_COPILOT_ROUTE_AUDITOR_AGENT_PATH, @@ -66,6 +70,7 @@ import { TRUTHMARK_GEMINI_DOC_WRITER_AGENT_PATH, TRUTHMARK_GEMINI_CHECK_COMMAND_PATH, TRUTHMARK_GEMINI_DOCUMENT_COMMAND_PATH, + TRUTHMARK_GEMINI_PORTAL_COMMAND_PATH, TRUTHMARK_GEMINI_PREVIEW_COMMAND_PATH, TRUTHMARK_GEMINI_REALIZE_COMMAND_PATH, TRUTHMARK_GEMINI_ROUTE_AUDITOR_AGENT_PATH, @@ -75,6 +80,8 @@ import { TRUTHMARK_OPENCODE_DOC_REVIEWER_AGENT_PATH, TRUTHMARK_OPENCODE_DOC_WRITER_AGENT_PATH, TRUTHMARK_OPENCODE_ROUTE_AUDITOR_AGENT_PATH, + TRUTHMARK_PORTAL_SKILL_METADATA_PATH, + TRUTHMARK_PORTAL_SKILL_PATH, TRUTHMARK_PREVIEW_SKILL_METADATA_PATH, TRUTHMARK_PREVIEW_SKILL_PATH, TRUTHMARK_REALIZE_SKILL_METADATA_PATH, @@ -172,11 +179,26 @@ const codexFiles = (config: TruthmarkConfig): GeneratedSurface[] => { }, ]; + if (config.truthmarkPortal.enabled) { + files.push( + ...renderTruthmarkSkillPackage({ + skillPath: TRUTHMARK_PORTAL_SKILL_PATH, + workflowId: "truthmark-portal", + host: "codex", + config, + }), + { + path: TRUTHMARK_PORTAL_SKILL_METADATA_PATH, + content: renderTruthmarkPortalSkillMetadata(), + }, + ); + } + return files; }; const opencodeFiles = (config: TruthmarkConfig): GeneratedSurface[] => { - return [ + const files: GeneratedSurface[] = [ ...renderTruthmarkSkillPackage({ skillPath: ".opencode/skills/truthmark-structure/SKILL.md", workflowId: "truthmark-structure", @@ -230,13 +252,26 @@ const opencodeFiles = (config: TruthmarkConfig): GeneratedSurface[] => { content: renderTruthmarkOpenCodeDocWriterAgent(config), }, ]; + + if (config.truthmarkPortal.enabled) { + files.push( + ...renderTruthmarkSkillPackage({ + skillPath: ".opencode/skills/truthmark-portal/SKILL.md", + workflowId: "truthmark-portal", + host: "opencode", + config, + }), + ); + } + + return files; }; const claudeFiles = ( config: TruthmarkConfig, block: string, ): GeneratedSurface[] => { - return [ + const files: GeneratedSurface[] = [ ...instructionBlockFiles(["CLAUDE.md"], block), ...renderTruthmarkSkillPackage({ skillPath: ".claude/skills/truthmark-structure/SKILL.md", @@ -291,6 +326,19 @@ const claudeFiles = ( content: renderTruthmarkClaudeDocWriterAgent(), }, ]; + + if (config.truthmarkPortal.enabled) { + files.push( + ...renderTruthmarkSkillPackage({ + skillPath: ".claude/skills/truthmark-portal/SKILL.md", + workflowId: "truthmark-portal", + host: "claude-code", + config, + }), + ); + } + + return files; }; const copilotFiles = ( @@ -377,6 +425,21 @@ const copilotFiles = ( }, ]; + if (config.truthmarkPortal.enabled) { + files.push( + ...renderTruthmarkSkillPackage({ + skillPath: ".github/skills/truthmark-portal/SKILL.md", + workflowId: "truthmark-portal", + host: "github-copilot", + config, + }), + { + path: TRUTHMARK_COPILOT_PORTAL_PROMPT_PATH, + content: renderTruthmarkCopilotPortalPrompt(config), + }, + ); + } + return files; }; @@ -384,7 +447,7 @@ const geminiFiles = ( config: TruthmarkConfig, block: string, ): GeneratedSurface[] => { - return [ + const files: GeneratedSurface[] = [ ...instructionBlockFiles(["GEMINI.md"], block), ...renderTruthmarkSkillPackage({ skillPath: ".gemini/skills/truthmark-structure/SKILL.md", @@ -463,6 +526,23 @@ const geminiFiles = ( content: renderTruthmarkGeminiDocWriterAgent(), }, ]; + + if (config.truthmarkPortal.enabled) { + files.push( + ...renderTruthmarkSkillPackage({ + skillPath: ".gemini/skills/truthmark-portal/SKILL.md", + workflowId: "truthmark-portal", + host: "gemini-cli", + config, + }), + { + path: TRUTHMARK_GEMINI_PORTAL_COMMAND_PATH, + content: renderTruthmarkGeminiPortalCommand(config), + }, + ); + } + + return files; }; const instructionBlockFiles = ( diff --git a/src/templates/workflow-surfaces.ts b/src/templates/workflow-surfaces.ts index c87b406..5499f2a 100644 --- a/src/templates/workflow-surfaces.ts +++ b/src/templates/workflow-surfaces.ts @@ -25,6 +25,10 @@ import { TRUTH_PREVIEW_EXPLICIT_INVOCATIONS, renderTruthPreviewSkillBody, } from "../agents/truth-preview.js"; +import { + TRUTHMARK_PORTAL_EXPLICIT_INVOCATIONS, + renderTruthmarkPortalSkillBody, +} from "../agents/truthmark-portal.js"; import { TRUTH_STRUCTURE_EXPLICIT_INVOCATIONS, renderTruthStructureSkillBody, @@ -79,6 +83,12 @@ export const TRUTHMARK_PREVIEW_SKILL_PATH = export const TRUTHMARK_PREVIEW_SKILL_METADATA_PATH = ".codex/skills/truthmark-preview/agents/openai.yaml"; +export const TRUTHMARK_PORTAL_SKILL_PATH = + ".codex/skills/truthmark-portal/SKILL.md"; + +export const TRUTHMARK_PORTAL_SKILL_METADATA_PATH = + ".codex/skills/truthmark-portal/agents/openai.yaml"; + export const TRUTHMARK_ROUTE_AUDITOR_AGENT_PATH = ".codex/agents/truth-route-auditor.toml"; @@ -130,6 +140,9 @@ export const TRUTHMARK_GEMINI_CHECK_COMMAND_PATH = export const TRUTHMARK_GEMINI_PREVIEW_COMMAND_PATH = ".gemini/commands/truthmark/preview.toml"; +export const TRUTHMARK_GEMINI_PORTAL_COMMAND_PATH = + ".gemini/commands/truthmark/portal.toml"; + export const TRUTHMARK_GEMINI_ROUTE_AUDITOR_AGENT_PATH = ".gemini/agents/truth-route-auditor.md"; @@ -159,6 +172,9 @@ export const TRUTHMARK_COPILOT_CHECK_PROMPT_PATH = export const TRUTHMARK_COPILOT_PREVIEW_PROMPT_PATH = ".github/prompts/truthmark-preview.prompt.md"; +export const TRUTHMARK_COPILOT_PORTAL_PROMPT_PATH = + ".github/prompts/truthmark-portal.prompt.md"; + export const TRUTHMARK_COPILOT_ROUTE_AUDITOR_AGENT_PATH = ".github/agents/truth-route-auditor.agent.md"; @@ -225,6 +241,9 @@ type WorkflowPackageDefinition = { const TRUTH_REALIZE_EXPLICIT_INVOCATIONS = "OpenCode /skill truthmark-realize; Codex /truthmark-realize or $truthmark-realize; Claude Code /truthmark-realize; GitHub Copilot /truthmark-realize; Gemini CLI /truthmark:realize."; +const routeFilesHint = (config: TruthmarkConfig): string => + `${config.docs.routing.rootIndex}; ${config.docs.routing.areaFilesRoot}/`; + const WORKFLOW_PACKAGE_DEFINITIONS: Record< TruthmarkWorkflowId, WorkflowPackageDefinition @@ -235,8 +254,8 @@ const WORKFLOW_PACKAGE_DEFINITIONS: Record< invocations: TRUTH_STRUCTURE_EXPLICIT_INVOCATIONS, use: () => "Use this skill to design or repair Truthmark area structure.", quickRules: (config) => [ - "Follow docs/ai/repo-rules.md as the repository instruction authority.", - `Read .truthmark/config.yml, ${config.docs.routing.rootIndex}, relevant child route files under ${config.docs.routing.areaFilesRoot}/, current docs, and relevant code directly.`, + "Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists.", + `Inspect .truthmark/config.yml and configured route files (${routeFilesHint(config)}) only when they exist; then inspect current docs and relevant code directly.`, "Define areas by product or behavior ownership, not by mechanical directory mirroring.", "Do not edit functional code.", "Read support/procedure.md before writing route or starter truth-doc changes.", @@ -253,8 +272,8 @@ const WORKFLOW_PACKAGE_DEFINITIONS: Record< use: () => "Use this skill to document existing implemented behavior when no functional-code changes are required for the task.", quickRules: (config) => [ - "Follow docs/ai/repo-rules.md as the repository instruction authority.", - `Read .truthmark/config.yml, ${config.docs.routing.rootIndex}, relevant child route files under ${config.docs.routing.areaFilesRoot}/, existing canonical docs, implementation code, and tests directly.`, + "Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists.", + `Inspect .truthmark/config.yml and configured route files (${routeFilesHint(config)}) only when they exist; then inspect existing canonical docs, implementation code, and tests directly.`, "Document current implemented behavior; do not invent future behavior.", "May write canonical truth docs and truth routing files only; must not write functional code.", "Read support/procedure.md before editing truth docs.", @@ -271,9 +290,9 @@ const WORKFLOW_PACKAGE_DEFINITIONS: Record< use: () => "Use this skill automatically before finishing when functional code changed since the last successful Truth Sync. Also run it immediately when the user explicitly invokes Truth Sync.", quickRules: (config) => [ - "Follow docs/ai/repo-rules.md as the repository instruction authority.", + "Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists.", "Skip docs-only, formatting-only, behavior-preserving renames with no truth impact, missing config, and no-code changes.", - `Read .truthmark/config.yml, the configured root route index at ${config.docs.routing.rootIndex}, relevant child route files under ${config.docs.routing.areaFilesRoot}/, and relevant canonical docs.`, + `Inspect .truthmark/config.yml and configured route files (${routeFilesHint(config)}) only when they exist; then inspect relevant canonical docs directly.`, "direct checkout inspection is the canonical path; do not require the truthmark binary.", "May write canonical truth docs and truth routing files only; must not rewrite functional code.", "Read support/procedure.md before editing truth docs.", @@ -291,8 +310,8 @@ const WORKFLOW_PACKAGE_DEFINITIONS: Record< use: () => "Use this skill only when the user explicitly asks to preview Truthmark routing or workflow choice before edits.", quickRules: (config) => [ - "Follow docs/ai/repo-rules.md as the repository instruction authority.", - `Read .truthmark/config.yml, ${config.docs.routing.rootIndex}, relevant child route files under ${config.docs.routing.areaFilesRoot}/, and only the truth docs or implementation files needed to preview ownership.`, + "Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists.", + `Inspect .truthmark/config.yml and configured route files (${routeFilesHint(config)}) only when they exist; then inspect only the truth docs or implementation files needed to preview ownership.`, "Truth Preview is read-only; this report is intended, not authorized.", "must not edit files and must not issue write leases; do not run Truth Sync automatically, replace Truth Check, claim final correctness, or mutate code.", "Use optional read-only route-auditor evidence only when it reduces context or clarifies ownership.", @@ -308,8 +327,8 @@ const WORKFLOW_PACKAGE_DEFINITIONS: Record< use: () => "Use this skill only when the user explicitly asks to realize truth docs into code.", quickRules: (config) => [ - "Follow docs/ai/repo-rules.md as the repository instruction authority.", - `Read the source truth docs, .truthmark/config.yml, ${config.docs.routing.rootIndex}, relevant child route files, tests, and relevant functional code directly.`, + "Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists.", + `Read the source truth docs, inspect .truthmark/config.yml and configured route files (${routeFilesHint(config)}) only when they exist, then inspect tests and relevant functional code directly.`, "Truth docs lead; code follows.", "may write functional code only; must not edit truth docs or truth routing while realizing those docs.", "Read support/procedure.md before changing code.", @@ -322,8 +341,8 @@ const WORKFLOW_PACKAGE_DEFINITIONS: Record< invocations: TRUTH_CHECK_EXPLICIT_INVOCATIONS, use: () => "Use this skill to audit repository truth health.", quickRules: (config) => [ - "Follow docs/ai/repo-rules.md as the repository instruction authority.", - `Read .truthmark/config.yml, ${config.docs.routing.rootIndex}, relevant child route files under ${config.docs.routing.areaFilesRoot}/, canonical docs, and relevant implementation directly.`, + "Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists.", + `Inspect .truthmark/config.yml and configured route files (${routeFilesHint(config)}) only when they exist; then inspect canonical docs and relevant implementation directly.`, "Report issues and suggested fixes; do not silently rewrite unrelated files.", "Direct checkout inspection is valid even when local tooling is unavailable.", "Read support/procedure.md before auditing details.", @@ -332,6 +351,25 @@ const WORKFLOW_PACKAGE_DEFINITIONS: Record< ], parentRule: "Parent agent owns the final Truth Check report", }, + "truthmark-portal": { + title: "Truthmark Portal", + argumentHint: "Optional output path, template, or portal generation focus", + invocations: TRUTHMARK_PORTAL_EXPLICIT_INVOCATIONS, + use: () => + "Use this skill only when the user explicitly asks to generate or refresh the committed static HTML Truthmark Portal.", + quickRules: (config) => [ + "Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists.", + "Truthmark Portal is manual-only; never run it as a completion gate and never treat it as Truth Sync.", + "Markdown remains canonical; generated HTML is non-canonical presentation only.", + "Read Markdown directly; the workflow does not require the truthmark CLI or package.", + "Generate committed, generated non-canonical static files for humans.", + `Write only under configured Portal output ${config.truthmarkPortal.output}; default output is docs/truthmark-portal.`, + `Use configured Portal template ${config.truthmarkPortal.template}; no .truthmark/index.json dependency.`, + "Use no remote dependencies by default and include source provenance on every page.", + "Read support/procedure.md before generating Portal output.", + "Read support/report-template.md before the final report.", + ], + }, }; const stripWorkflowSkillFrontmatter = (body: string): string => { @@ -446,6 +484,8 @@ const renderStandaloneWorkflowSkillBody = ( return renderTruthmarkRealizeSkillBody(config); case "truthmark-check": return renderTruthCheckSkillBody(config); + case "truthmark-portal": + return renderTruthmarkPortalSkillBody(config); } }; @@ -679,7 +719,7 @@ const TRUTHMARK_SUBAGENT_PROFILES = { nicknameCandidates: ["Route Audit", "Route Trace", "Route Check"], instructions: `Stay read-only. Audit one bounded Truthmark route, area, or doc shard assigned by the parent. -Read .truthmark/config.yml, the root route index, relevant child route files, mapped truth docs, and relevant implementation files directly. +Inspect .truthmark/config.yml and route files only when they exist; then inspect mapped truth docs and relevant implementation files directly. Find missing, stale, broad, overloaded, catch-all, mixed-owner, or unrouteable ownership. Do not edit files, stage changes, or propose broad rewrites. Return JSON only with keys: scope, filesReviewed, findings, evidence, confidence, recommendedWorkflow, notes. @@ -1292,8 +1332,8 @@ Truth Realize is doc-first: Workflow: -1. Read the updated truth docs named by the user, or infer the relevant docs from ${config.docs.routing.rootIndex}. -2. Read .truthmark/config.yml, ${config.docs.routing.rootIndex}, relevant child route files, tests, and the relevant functional code. +1. Read the updated truth docs named by the user, or infer the relevant docs from configured route files when present. +2. Inspect .truthmark/config.yml and configured route files (${routeFilesHint(config)}) only when they exist; then read tests and the relevant functional code. 3. ${EVIDENCE_AUTHORITY_INSTRUCTIONS} ${renderTruthDocOwnershipGateSection( "source truth docs before writing code", @@ -1441,6 +1481,29 @@ truthmark: `; }; +export const renderTruthmarkPortalSkill = ( + config: TruthmarkConfig = defaultAgentConfig(), +): string => { + return renderTruthmarkPortalSkillBody(config); +}; + +export const renderTruthmarkPortalSkillMetadata = (): string => { + const workflow = getTruthmarkWorkflow("truthmark-portal"); + + return `interface: + display_name: "${workflow.displayName}" + short_description: "${workflow.shortDescription}" + default_prompt: "${workflow.defaultPrompt}" + +policy: + allow_implicit_invocation: ${workflow.allowImplicitInvocation} + +truthmark: + version: "${TRUTHMARK_VERSION}" + refresh_command: "truthmark init" +`; +}; + export const renderTruthmarkGeminiStructureCommand = ( config: TruthmarkConfig = defaultAgentConfig(), ): string => { @@ -1507,6 +1570,17 @@ export const renderTruthmarkGeminiPreviewCommand = ( ); }; +export const renderTruthmarkGeminiPortalCommand = ( + config: TruthmarkConfig = defaultAgentConfig(), +): string => { + const workflow = getTruthmarkWorkflow("truthmark-portal"); + + return renderGeminiCommand( + workflow.description, + renderTruthmarkPortalSkillBody(config), + ); +}; + export const renderTruthmarkCopilotStructurePrompt = ( config: TruthmarkConfig = defaultAgentConfig(), ): string => { @@ -1580,3 +1654,14 @@ export const renderTruthmarkCopilotPreviewPrompt = ( renderTruthPreviewSkillBody(config), ); }; + +export const renderTruthmarkCopilotPortalPrompt = ( + config: TruthmarkConfig = defaultAgentConfig(), +): string => { + const workflow = getTruthmarkWorkflow("truthmark-portal"); + + return renderCopilotPromptFile( + workflow.description, + renderTruthmarkPortalSkillBody(config), + ); +}; diff --git a/tests/agents/instructions.test.ts b/tests/agents/instructions.test.ts index c43c09c..a4a8d8c 100644 --- a/tests/agents/instructions.test.ts +++ b/tests/agents/instructions.test.ts @@ -65,16 +65,16 @@ describe("renderTruthSyncInstructions", () => { const instructions = renderTruthSyncInstructions(config); - expect(instructions).toContain("May write truth docs and docs/routes/index.md only"); - expect(instructions).toContain("Read docs/routes/index.md and only relevant child route files under docs/routes/areas/"); - expect(instructions).not.toContain("May write truth docs and docs/truthmark/areas.md only"); + expect(instructions).toContain("docs/routes/index.md; docs/routes/areas/"); + expect(instructions).toContain("only when present"); + expect(instructions).not.toContain("docs/truthmark/areas.md; docs/truthmark/areas/"); }); }); describe("agent-native workflow instructions", () => { it("renders Truth Structure and Truth Check summaries", () => { expect(renderTruthStructureInstructions()).toContain("truthmark-structure"); - expect(renderTruthStructureInstructions()).toContain("docs/truthmark/areas.md"); + expect(renderTruthStructureInstructions()).toContain("configured route files when present"); expect(renderTruthStructureInstructions()).toContain("missing, stale, broad, overloaded, catch-all, unrouteable"); expect(renderTruthStructureInstructions()).toContain("canonical current-truth destinations"); expect(renderTruthStructureInstructions()).toContain("topology pressure"); diff --git a/tests/agents/prompts.test.ts b/tests/agents/prompts.test.ts index 8001c9e..7ac8f20 100644 --- a/tests/agents/prompts.test.ts +++ b/tests/agents/prompts.test.ts @@ -11,7 +11,7 @@ describe("renderTruthRealizePrompt", () => { expect(prompt).toContain("### Manual Truth Realize"); expect(prompt).toContain("Only run when the user explicitly asks"); expect(prompt).toContain( - "read the updated truth docs plus .truthmark/config.yml, route files, relevant code, and tests", + "read the updated truth docs plus any present Truthmark config, route files, relevant code, and tests", ); expect(prompt).toContain("Truth-doc ownership gate"); expect(prompt).toContain( diff --git a/tests/agents/truth-check.test.ts b/tests/agents/truth-check.test.ts index 5da36e7..73cb712 100644 --- a/tests/agents/truth-check.test.ts +++ b/tests/agents/truth-check.test.ts @@ -44,7 +44,7 @@ describe("renderTruthCheckSkillBody", () => { ); expect(skill).toContain("audit repository truth health"); expect(skill).toContain( - "Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority.", + "Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path.", ); expect(skill).toContain( "Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries.", @@ -60,7 +60,7 @@ describe("renderTruthCheckSkillBody", () => { expect(skill).toContain( "remove unsupported findings or mark open questions", ); - expect(skill).toContain("Truthmark hierarchy:"); + expect(skill).toContain("Truthmark hierarchy hints:"); expect(skill).toContain("Product Decisions"); expect(skill).toContain("Rationale"); expect(skill).toContain("Truth Check: completed"); diff --git a/tests/agents/truth-document.test.ts b/tests/agents/truth-document.test.ts index 7d1b501..b0c5d43 100644 --- a/tests/agents/truth-document.test.ts +++ b/tests/agents/truth-document.test.ts @@ -88,7 +88,7 @@ describe("renderTruthDocumentSkillBody", () => { "block and recommend Truth Structure when routing repair is unsafe, ambiguous, or outside the task boundary", ); expect(skill).toContain( - "Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority.", + "Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path.", ); expect(skill).toContain("RepoIndex, RouteMap, ImpactSet, and ContextPack"); expect(skill).toContain("repository-intelligence artifacts were not generated"); diff --git a/tests/agents/truth-structure.test.ts b/tests/agents/truth-structure.test.ts index af74b87..40b0691 100644 --- a/tests/agents/truth-structure.test.ts +++ b/tests/agents/truth-structure.test.ts @@ -82,7 +82,7 @@ describe("renderTruthStructureSkillBody", () => { expect(skill).toContain(`truthmark-version: ${TRUTHMARK_VERSION}`); expect(skill).toContain("inspect repository layout"); expect(skill).toContain( - "Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority.", + "Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path.", ); expect(skill).toContain( "Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries.", @@ -95,7 +95,7 @@ describe("renderTruthStructureSkillBody", () => { expect(skill).toContain("docs/truth/**"); expect(skill).toContain("docs/architecture/**"); expect(skill).toContain("canonical current-truth destinations"); - expect(skill).toContain("Truthmark hierarchy:"); + expect(skill).toContain("Truthmark hierarchy hints:"); expect(skill).toContain("Product Decisions"); expect(skill).toContain("Rationale"); expect(skill).toContain( diff --git a/tests/agents/truth-sync.test.ts b/tests/agents/truth-sync.test.ts index a60025a..e2fddab 100644 --- a/tests/agents/truth-sync.test.ts +++ b/tests/agents/truth-sync.test.ts @@ -29,7 +29,7 @@ describe("renderTruthSyncWorkerPrompt", () => { ); expect(prompt).toContain(".truthmark/config.yml"); expect(prompt).toContain("Code verification is parent-owned"); - expect(prompt).toContain("docs/truthmark/areas.md"); + expect(prompt).toContain("configured route files"); expect(prompt).toContain("status: completed | blocked"); expect(prompt).toContain("filesChanged"); expect(prompt).toContain("changedCodeReviewed"); @@ -66,7 +66,7 @@ describe("renderTruthSyncSkillBody", () => { "direct checkout inspection is the canonical path", ); expect(skillBody).toContain( - "Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority.", + "Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path.", ); expect(skillBody).toContain( "Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries.", @@ -85,9 +85,9 @@ describe("renderTruthSyncSkillBody", () => { "verify only truth docs and leased truth routing files changed", ); expect(skillBody).toContain( - "Read .truthmark/config.yml, the configured root route index", + "Inspect .truthmark/config.yml and configured route files only when they exist", ); - expect(skillBody).toContain("relevant child route files"); + expect(skillBody).toContain("configured route files"); expect(skillBody).toContain("Topology quality gate"); expect(skillBody).toContain( "missing, stale, broad, overloaded, catch-all route only", diff --git a/tests/agents/workflow-manifest.test.ts b/tests/agents/workflow-manifest.test.ts index 5da9f70..4f12b62 100644 --- a/tests/agents/workflow-manifest.test.ts +++ b/tests/agents/workflow-manifest.test.ts @@ -11,7 +11,10 @@ import { renderTruthDocumentSkillBody } from "../../src/agents/truth-document.js import { renderTruthPreviewSkillBody } from "../../src/agents/truth-preview.js"; import { renderTruthStructureSkillBody } from "../../src/agents/truth-structure.js"; import { renderTruthSyncSkillBody } from "../../src/agents/truth-sync.js"; -import { renderTruthmarkRealizeSkill } from "../../src/templates/workflow-surfaces.js"; +import { + renderTruthmarkPortalSkill, + renderTruthmarkRealizeSkill, +} from "../../src/templates/workflow-surfaces.js"; const renderWorkflowSkill = (id: (typeof TRUTHMARK_WORKFLOW_IDS)[number]) => { switch (id) { @@ -27,6 +30,8 @@ const renderWorkflowSkill = (id: (typeof TRUTHMARK_WORKFLOW_IDS)[number]) => { return renderTruthmarkRealizeSkill(); case "truthmark-check": return renderTruthCheckSkillBody(); + case "truthmark-portal": + return renderTruthmarkPortalSkill(); } }; @@ -148,6 +153,40 @@ describe("Truthmark workflow manifest", () => { ]); }); + it("defines Truthmark Portal as a manual-only presentation workflow", () => { + const workflow = getTruthmarkWorkflow("truthmark-portal"); + + expect(workflow.displayName).toBe("Truthmark Portal"); + expect(workflow.allowImplicitInvocation).toBe(false); + expect(workflow.positiveTriggers).toEqual( + expect.arrayContaining([ + "generate the Truthmark Portal", + "refresh the committed HTML docs site", + "update docs/truthmark-portal", + ]), + ); + expect(workflow.negativeTriggers).toEqual( + expect.arrayContaining([ + "code change sync", + "route ownership repair", + "truth validation or checking", + "machine-readable agent context", + ]), + ); + expect(workflow.allowedWrites).toEqual(["configured Portal output directory only"]); + expect(workflow.reportSections).toEqual([ + "Output path", + "Page count", + "Diagrams/assets", + "Source docs reviewed", + "Skipped/ambiguous docs", + "Validation", + "Markdown canonical statement", + ]); + expect(workflow.subagents).toBeUndefined(); + expect(workflow.writeSubagents).toBeUndefined(); + }); + it("keeps routing descriptions focused on trigger selection", () => { for (const id of TRUTHMARK_WORKFLOW_IDS) { const { description } = getTruthmarkWorkflow(id); diff --git a/tests/config/load.test.ts b/tests/config/load.test.ts index ebb93d8..ef4cb3f 100644 --- a/tests/config/load.test.ts +++ b/tests/config/load.test.ts @@ -4,6 +4,19 @@ import { createTempRepo } from "../helpers/temp-repo.js"; import { loadConfig } from "../../src/config/load.js"; describe("loadConfig", () => { + const writeConfig = async ( + repo: Awaited>, + extraConfig = "", + ) => { + await repo.writeFile( + ".truthmark/config.yml", + `version: 1 +authority: + - docs/truthmark/areas.md +${extraConfig}`, + ); + }; + it("loads a valid config and applies defaults for optional frontmatter and ignore fields", async () => { const repo = await createTempRepo(); @@ -289,6 +302,143 @@ outputs: } }); + it("defaults omitted Portal config", async () => { + const repo = await createTempRepo(); + + try { + await writeConfig(repo); + + const result = await loadConfig(repo.rootDir); + + expect(result.status).toBe("loaded"); + expect(result.diagnostics).toEqual([]); + expect(result.config?.truthmarkPortal).toEqual({ + enabled: false, + output: "docs/truthmark-portal", + template: "default", + }); + } finally { + await repo.cleanup(); + } + }); + + it("loads enabled Portal config", async () => { + const repo = await createTempRepo(); + + try { + await writeConfig( + repo, + `truthmark-portal: + enabled: true + output: docs/portal + template: docs/templates/portal.md +`, + ); + + const result = await loadConfig(repo.rootDir); + + expect(result.status).toBe("loaded"); + expect(result.diagnostics).toEqual([]); + expect(result.config?.truthmarkPortal).toEqual({ + enabled: true, + output: "docs/portal", + template: "docs/templates/portal.md", + }); + } finally { + await repo.cleanup(); + } + }); + + it("defaults omitted Portal enabled when nested Portal config is present", async () => { + const repo = await createTempRepo(); + + try { + await writeConfig( + repo, + `truthmark-portal: + output: docs/portal +`, + ); + + const result = await loadConfig(repo.rootDir); + + expect(result.status).toBe("loaded"); + expect(result.config?.truthmarkPortal).toEqual({ + enabled: false, + output: "docs/portal", + template: "default", + }); + } finally { + await repo.cleanup(); + } + }); + + it.each([ + ["/tmp/truthmark-portal", "absolute output path"], + ["../truthmark-portal", "parent output traversal"], + ["docs/truth", "canonical truth root overlap"], + ["docs/truthmark/areas", "routing files root overlap"], + ["AGENTS.md/portal", "instruction target overlap"], + ])("rejects unsafe Portal output for %s (%s)", async (output) => { + const repo = await createTempRepo(); + + try { + await writeConfig( + repo, + `truthmark-portal: + enabled: true + output: ${output} +`, + ); + + const result = await loadConfig(repo.rootDir); + + expect(result.status).toBe("invalid"); + expect(result.config).toBeNull(); + expect(result.diagnostics).toEqual([ + expect.objectContaining({ + category: "config", + severity: "error", + message: expect.stringContaining("truthmark-portal.output"), + }), + ]); + } finally { + await repo.cleanup(); + } + }); + + it.each([ + ["/tmp/portal-template.md", "absolute template path"], + ["docs/templates/../portal.md", "parent template traversal"], + ])("rejects unsafe Portal template for %s (%s)", async (template) => { + const repo = await createTempRepo(); + + try { + await writeConfig( + repo, + `truthmark-portal: + enabled: true + output: docs/portal + template: ${template} +`, + ); + + const result = await loadConfig(repo.rootDir); + + expect(result.status).toBe("invalid"); + expect(result.config).toBeNull(); + expect(result.diagnostics).toEqual([ + expect.objectContaining({ + category: "config", + severity: "error", + message: expect.stringContaining("truthmark-portal.template"), + }), + ]); + } finally { + await repo.cleanup(); + } + }); + it("returns a typed missing status when config does not exist yet", async () => { const repo = await createTempRepo(); diff --git a/tests/evals/workflow-routing-cases.ts b/tests/evals/workflow-routing-cases.ts index 3aa2541..26996cb 100644 --- a/tests/evals/workflow-routing-cases.ts +++ b/tests/evals/workflow-routing-cases.ts @@ -141,6 +141,19 @@ export const WORKFLOW_ROUTING_EVAL_CASES: WorkflowRoutingEvalCase[] = [ forbiddenWorkflows: ["truthmark-sync", "truthmark-check"], source: "manifest-positive", }, + { + id: "portal-explicit-refresh", + userPrompt: + "Refresh the committed Truthmark Portal static HTML docs site under docs/truthmark-portal.", + expectedWorkflow: "truthmark-portal", + expectedReason: "generate or refresh the committed static HTML Portal", + expectedManifestSignals: [ + "generate, refresh, or update the Truthmark Portal static HTML site", + "update docs/truthmark-portal", + ], + forbiddenWorkflows: ["truthmark-sync", "truthmark-check"], + source: "manifest-positive", + }, { id: "adjacent-sync-not-realize", userPrompt: diff --git a/tests/evals/workflow-routing.test.ts b/tests/evals/workflow-routing.test.ts index e7e9945..c8b9024 100644 --- a/tests/evals/workflow-routing.test.ts +++ b/tests/evals/workflow-routing.test.ts @@ -16,6 +16,7 @@ const WORKFLOW_COMMAND_PATHS: Record = { "truthmark-preview": ".gemini/commands/truthmark/preview.toml", "truthmark-realize": ".gemini/commands/truthmark/realize.toml", "truthmark-check": ".gemini/commands/truthmark/check.toml", + "truthmark-portal": ".gemini/commands/truthmark/portal.toml", }; const WORKFLOW_SURFACE_PATHS = (id: TruthmarkWorkflowId): readonly string[] => [ @@ -108,6 +109,14 @@ const SURFACE_CONTRACT_TERMS: Record = { "Files reviewed:", "Validation:", ], + "truthmark-portal": [ + "manual-only presentation workflow", + "configured Portal output directory only", + "Markdown remains canonical", + "Truthmark Portal: completed", + "Output path:", + "Markdown canonical statement:", + ], }; const manifestRoutingText = (id: TruthmarkWorkflowId): string => { @@ -136,6 +145,7 @@ const candidateManifestText = ( const buildGeneratedSurfaceMap = (): Map => { const config = createDefaultConfig(); + config.truthmarkPortal.enabled = true; return new Map( renderGeneratedSurfaces(config).map((surface) => [ surface.path, diff --git a/tests/init/init.test.ts b/tests/init/init.test.ts index cda47ec..0ecef96 100644 --- a/tests/init/init.test.ts +++ b/tests/init/init.test.ts @@ -331,7 +331,7 @@ describe("runInit", () => { "Explicit workflows: Truth Structure, Truth Document, Truth Preview, Truth Realize, Truth Check", ); expect(agents).toContain("load the installed skill for details"); - expect(agents).toContain("Hierarchy: config .truthmark/config.yml"); + expect(agents).toContain("Hierarchy hints: config .truthmark/config.yml"); expect(agents).toContain("routes docs/truthmark/areas.md"); expect(agents).toContain("docs/truthmark/areas/**/*.md"); expect(agents).toContain("Truth docs: docs/truth/**/*.md"); @@ -351,7 +351,7 @@ describe("runInit", () => { expect(agents).toContain("code changed -> tests -> Sync -> report"); expect(agents).not.toContain("Truth Sync: completed"); expect(agents).not.toContain("Truth Realize: completed"); - expect(agents.match(/Hierarchy: config/g)).toHaveLength(1); + expect(agents.match(/Hierarchy hints: config/g)).toHaveLength(1); expect(agents.match(/Decisions live/g)).toHaveLength(1); expect(structureSkill).toContain("name: truthmark-structure"); expect(structureSkill).toContain("support/procedure.md"); @@ -430,9 +430,9 @@ describe("runInit", () => { expect(syncReportTemplate).toContain("Truth Sync: completed"); expect(syncReportTemplate).toContain("Truth Sync: blocked"); expect(syncSkill).toContain( - "Read .truthmark/config.yml, the configured root route index", + "Inspect .truthmark/config.yml and configured route files", ); - expect(syncSkill).toContain("relevant child route files"); + expect(syncSkill).toContain("then inspect relevant canonical docs directly"); expect(syncSkill).not.toContain(".truthmark/local.yml"); expect(syncSkill).not.toContain("truth_sync.sync_agent"); expect(syncSkill).not.toContain( @@ -657,6 +657,18 @@ describe("runInit", () => { diagnostic.file === ".opencode/agents/truth-route-auditor.md", ), ).toBe(true); + const diagnosticCategoriesByFile = new Map( + result.diagnostics.map((diagnostic) => [diagnostic.file, diagnostic.category]), + ); + for (const file of [ + ".github/prompts/truthmark-realize.prompt.md", + ".github/skills/truthmark-realize/SKILL.md", + ".claude/skills/truthmark-realize/SKILL.md", + ".opencode/skills/truthmark-realize/SKILL.md", + ".gemini/skills/truthmark-realize/SKILL.md", + ]) { + expect(diagnosticCategoriesByFile.get(file)).toBe("realization"); + } expect( result.diagnostics.some((diagnostic) => diagnostic.message.includes("Created"), @@ -856,14 +868,14 @@ Agent-specific: const geminiInstructions = await repo.readFile("GEMINI.md"); expect(geminiInstructions).not.toContain("/truthmark:sync"); expect(geminiInstructions).toContain( - "Use that file as the primary repository instruction source for this agent.", + "Use explicitly configured repository policy docs only when they exist in this checkout.", ); expect(geminiInstructions).toContain("Agent-specific:"); expect(geminiInstructions).toContain( - "Read `docs/README.md` only when choosing or updating canonical docs.", + "Read the configured Truthmark routing files when choosing or updating canonical docs.", ); expect(geminiInstructions).toContain( - "Use `docs/ai/agent-onboarding.md` only when task routing is unclear or cross-area.", + "Use repository onboarding or docs-map files only when present and needed for unclear or cross-area routing.", ); expect(geminiInstructions).not.toContain("for Codex"); expect(geminiInstructions).not.toContain("Codex-specific"); diff --git a/tests/integration/agent-workflow-contract.test.ts b/tests/integration/agent-workflow-contract.test.ts index 48fdaaf..a55b423 100644 --- a/tests/integration/agent-workflow-contract.test.ts +++ b/tests/integration/agent-workflow-contract.test.ts @@ -78,10 +78,14 @@ describe("installed workflow contract", () => { expect(agents).not.toContain("Truth Sync: completed"); expect(agents).not.toContain("Truth Realize: completed"); expect(structureSkill).toContain("name: truthmark-structure"); - expect(structureSkill).toContain("docs/ai/repo-rules.md"); + expect(structureSkill).toContain( + "Follow repository instruction files that exist in this checkout", + ); expect(structureSkill).toContain("docs/truthmark/areas.md"); expect(syncSkill).toContain("name: truthmark-sync"); - expect(syncSkill).toContain("docs/ai/repo-rules.md"); + expect(syncSkill).toContain( + "Follow repository instruction files that exist in this checkout", + ); expect(syncSkill).toContain( "Use this skill automatically before finishing", ); diff --git a/tests/templates/generated-surfaces.test.ts b/tests/templates/generated-surfaces.test.ts new file mode 100644 index 0000000..74fd756 --- /dev/null +++ b/tests/templates/generated-surfaces.test.ts @@ -0,0 +1,72 @@ +import { describe, expect, it } from "vitest"; + +import { createDefaultConfig } from "../../src/config/defaults.js"; +import { renderAgentsBlock } from "../../src/templates/agents-block.js"; +import { renderGeneratedSurfaces } from "../../src/templates/generated-surfaces.js"; + +const portalPaths = [ + ".codex/skills/truthmark-portal/SKILL.md", + ".codex/skills/truthmark-portal/agents/openai.yaml", + ".opencode/skills/truthmark-portal/SKILL.md", + ".claude/skills/truthmark-portal/SKILL.md", + ".github/skills/truthmark-portal/SKILL.md", + ".github/prompts/truthmark-portal.prompt.md", + ".gemini/skills/truthmark-portal/SKILL.md", + ".gemini/commands/truthmark/portal.toml", +]; + +describe("Truthmark Portal generated surfaces", () => { + it("omits Portal surfaces and AGENTS wording when disabled", () => { + const config = createDefaultConfig(); + const paths = renderGeneratedSurfaces(config).map((surface) => surface.path); + + expect(config.truthmarkPortal.enabled).toBe(false); + for (const portalPath of portalPaths) { + expect(paths).not.toContain(portalPath); + } + expect(renderAgentsBlock(config)).not.toContain("Truthmark Portal"); + }); + + it("renders Portal surfaces for all configured platforms when enabled", () => { + const config = createDefaultConfig(); + config.truthmarkPortal = { + enabled: true, + output: "docs/project-map", + template: "docs/truthmark/portal-templates/product.md", + }; + + const surfaces = renderGeneratedSurfaces(config); + const byPath = new Map(surfaces.map((surface) => [surface.path, surface.content])); + + for (const portalPath of portalPaths) { + expect(byPath.has(portalPath)).toBe(true); + } + + const portalSkill = byPath.get(".codex/skills/truthmark-portal/SKILL.md") ?? ""; + const portalProcedure = + byPath.get(".codex/skills/truthmark-portal/support/procedure.md") ?? ""; + const copilotPrompt = byPath.get(".github/prompts/truthmark-portal.prompt.md") ?? ""; + const geminiCommand = byPath.get(".gemini/commands/truthmark/portal.toml") ?? ""; + const agentsBlock = renderAgentsBlock(config); + + for (const text of [portalSkill, portalProcedure, copilotPrompt, geminiCommand]) { + expect(text).toContain("manual-only"); + expect(text).toContain("Markdown remains canonical"); + expect(text).toContain("does not require the truthmark CLI"); + expect(text).toContain("docs/truthmark-portal"); + expect(text).toContain("docs/project-map"); + expect(text).toContain("docs/truthmark/portal-templates/product.md"); + expect(text).toContain("no remote dependencies"); + expect(text).toContain("no .truthmark/index.json dependency"); + expect(text).toContain("source provenance"); + expect(text).toContain("generated non-canonical static files"); + } + + expect(portalProcedure).toContain("replace the entire output directory"); + expect(portalProcedure).toContain("configured Portal output directory only"); + expect(portalProcedure).toContain("explicit user or template request"); + expect(agentsBlock).toContain("Truthmark Portal is a separate manual-only presentation workflow"); + expect(agentsBlock).toContain("default `docs/truthmark-portal/`"); + expect(agentsBlock).toContain("Markdown remains canonical"); + }); +});