feat: add canonical agent workflow package (#19 )

* feat: add Truth Sync intent checklist * feat: add canonical agent workflow package Add the .truthmark/agent canonical workflow package, convert duplicated host workflow bodies into adapter/expanded-adapter surfaces, and validate canonical/adapter freshness in Truthmark check. Refresh generated surfaces and package metadata for Truthmark 2.3.0, with OpenSpec tasks completed and release notes added. * fix: preserve native workflow skill packages * docs: record native skill package decision * fix: drop unused agent workflow package * chore: remove implemented OpenSpec docs * chore: release workflow fixes as 2.2.2 * fix: remove agent-visible version markers * fix: drop generated surface version markers * feat: capture decision context in Truth Sync --------- Co-authored-by: MerlinH <merlinh221@gmail.com>
refactor: remove semantic repository index (#17 )
2026-08-25 07:53:25 +02:00 · 2026-06-18 17:07:40 +10:00 · 2026-06-16 11:03:04 +10:00 · 2026-06-16 00:55:23 +10:00 · 2026-06-16 00:54:46 +10:00 · 2026-06-13 05:02:17 +10:00
418 changed files with 39437 additions and 9057 deletions
@@ -0,0 +1,25 @@
+---
+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 Check
+
+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 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/routes/areas.md; docs/truthmark/routes/areas/) only when they exist; then inspect canonical docs and relevant implementation directly.
+- Report issues and suggested fixes; do not silently rewrite unrelated files.
+- Read support/procedure.md before auditing details.
+- Read support/subagents-and-leases.md only when dispatching verifier subagents.
+- Read support/report-template.md before the final report.
+
+Progressive disclosure:
+- support/procedure.md — read before edits or detailed auditing; contains core review questions
+- support/report-template.md — read before the final report
+- support/subagents-and-leases.md — read only when using subagents, leases, or accepting worker output
@@ -7,5 +7,4 @@ policy:
  allow_implicit_invocation: false

 truthmark:
-  version: "1.2.3"
  refresh_command: "truthmark init"
@@ -0,0 +1,56 @@
+# Truthmark Check Procedure
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+# Truthmark Check
+
+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.
+
+Truth Check is agent-led:
+
+- inspect .truthmark/config.yml and configured route files only when they exist; then inspect canonical docs and relevant implementation directly
+- inspect the configured root route index at docs/truthmark/routes/areas.md and relevant child route files under docs/truthmark/routes/areas/ when they exist
+- Evidence 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.
+- Lane classification:
+  - classify the request or changed surface as product-lane, engineering-lane, both-lane, or ambiguous for reporting only
+  - product-lane ownership belongs under docs/truthmark/product and describes product promises, boundaries, rationale, decisions, and success criteria
+  - engineering-lane ownership belongs under docs/truthmark/engineering and describes source-backed current realization, contracts, architecture, workflows, operations, or tests
+  - both-lane ownership uses separate product and engineering docs cross-linked in route YAML with realized_by and realizes, not in doc frontmatter
+  - ambiguous lane ownership should be reported for manual handoff or routed to Truth Structure
+  - Do not make product docs a summary of engineering docs. Do not make engineering docs a detailed version of product docs. Product truth says what must be true and why. Engineering truth says how the repository currently realizes it.
+- check that current docs describe current code rather than historical plans
+- keep lane and cross-lane checks route-first and bounded:
+  - for a narrow audit, inspect only the routed area and directly linked counterpart docs
+  - for root-wide truth health, first build a cheap route-map/index from route files, then inspect only mismatches and linked leaves
+  - inspect product counterparts for engineering docs only when route YAML claims a product relationship, or when the user explicitly asks for user-visible product coverage
+- check lane root/kind alignment for product truth under docs/truthmark/product and engineering truth under docs/truthmark/engineering
+- check route YAML cross-lane realized_by and realizes links for existence and lane compatibility
+- report missing product links for user-visible engineering docs only as a second-pass review diagnostic, not as default full-document reads or hard errors
+- check product docs do not contain engineering execution flow, generated file inventories, or CLI envelope mechanics
+- check engineering docs do not contain product promises, product rationale, or Product Decisions sections
+- never judge whether a product decision is commercially correct, valuable, prioritized, or desirable
+- 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 docs keep lane-appropriate decisions and rationale sections
+- optionally run truthmark check when local tooling is available
+- must not require the truthmark binary; direct inspection is always valid
+- report issues and suggested fixes without silently rewriting unrelated files
+- if follow-up docs edits are needed for mixed-owner docs, run or recommend Truth Structure before editing
+Evidence checklist:
+- support each finding and suggested fix with evidence from config, route files, canonical docs, implementation, templates, or tests
+- 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 hints:
+- Config, when present: .truthmark/config.yml
+- Root route index, when present: docs/truthmark/routes/areas.md
+- Area route files, when present: docs/truthmark/routes/areas/**/*.md
+- Product truth docs, when present: docs/truthmark/product/**/*.md
+- Engineering truth docs, when present: docs/truthmark/engineering/**/*.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.
+Product decisions belong in product truth; engineering, architecture, contract, workflow, and operational decisions belong in engineering truth.
@@ -0,0 +1,27 @@
+# Truthmark Check Report Template
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+Report completion in this shape:
+
+```md
+Truth Check: completed
+
+Files reviewed:
+- docs/truthmark/routes/areas.md
+
+Issues found:
+- none
+
+Fixes suggested:
+- none
+
+Evidence checked:
+- Finding: The root route index is present and maps repository truth owners.
+  Evidence: docs/truthmark/routes/areas.md:1
+  Suggested fix: none
+  Confidence: high
+
+Validation:
+- truthmark check
+```
@@ -0,0 +1,10 @@
+# Truthmark Check Subagents And Leases
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+Codex subagent mode:
+- use automatically when this workflow runs in Codex and the parent agent chooses bounded subagent fan-out
+- dispatch read-only project agents only: truth_route_auditor, truth_claim_verifier, truth_doc_reviewer
+- workers inspect checkout evidence directly, return structured findings, and must not edit files
+- parent supplies bounded evidence shards; workers must not preload host instruction files or repo-wide policy docs unless assigned as evidence
+- Parent agent owns the final Truth Check report
@@ -0,0 +1,28 @@
+---
+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 Document
+
+Use this skill to document existing implemented behavior when no functional-code changes are required for the task.
+
+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 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/routes/areas.md; docs/truthmark/routes/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.
+- Read support/subagents-and-leases.md only when dispatching or accepting worker output.
+- Read support/report-template.md before the final report.
+
+Progressive disclosure:
+- support/procedure.md — read before edits or detailed auditing; contains core review questions
+- support/report-template.md — read before the final report
+- support/subagents-and-leases.md — read only when using subagents, leases, or accepting worker output
+- helper-manifest.yml — read only when invoking helper validators or validating helper registration
+- support/helper-policy.md — read only when invoking helper validators or reporting helper status
@@ -7,5 +7,4 @@ policy:
  allow_implicit_invocation: false

 truthmark:
-  version: "1.2.3"
  refresh_command: "truthmark init"
@@ -0,0 +1,34 @@
+# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+helpers:
+  validate-document-report:
+    optional: true
+    runner: truthmark
+    command:
+      argv:
+        - truthmark
+        - validate
+        - document-report
+        - <report-file>
+        - --json
+    inputs:
+      - document report file
+    output: json
+    writes: false
+    fallback: manually validate support/report-template.md required sections and structured Evidence checked entries
+  validate-write-lease:
+    optional: true
+    runner: truthmark
+    command:
+      argv:
+        - truthmark
+        - validate
+        - write-lease
+        - <lease-or-report-file>
+        - <changed-files-file>
+        - --json
+    inputs:
+      - lease or worker report yaml
+      - changed file list
+    output: json
+    writes: false
+    fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files
@@ -0,0 +1,23 @@
+# Optional Helper CLI Policy
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+Optional helper CLI commands may collect deterministic checkout facts or validate artifacts. If the Truthmark CLI is unavailable or cannot return the declared helper output, 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.
+
+Runner detection:
+- Check that the declared Truthmark CLI runner is available before invoking a helper.
+- Invoke helpers through the installed `truthmark validate ... --json` CLI command using argv-style arguments from helper-manifest.yml.
+- If unavailable, failing, or returning incompatible output, treat the helper as skipped and use the manual fallback.
+- Do not fail the workflow solely because a helper cannot run.
+
+Available helpers:
+- validate-document-report: optional truthmark; manual fallback: manually validate support/report-template.md required sections and structured Evidence checked entries
+- validate-write-lease: optional truthmark; 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:
+
+```md
+Helper scripts:
+- validate-document-report: ran, passed
+- validate-write-lease: skipped, no write lease used
+```
@@ -0,0 +1,92 @@
+# Truthmark Document Procedure
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+# Truthmark Document
+
+Use this skill to document existing implemented behavior when no functional-code changes are required for the task.
+Invocations: OpenCode /skill truthmark-document; Codex /truthmark-document or $truthmark-document; Claude Code /truthmark-document; GitHub Copilot /truthmark-document; Gemini CLI /truthmark:document.
+
+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 and configured route files only when they exist; then inspect existing canonical docs, implementation code, and tests directly
+- Evidence 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.
+- Lane classification:
+  - before writing canonical truth docs, classify the request or change as product-lane, engineering-lane, both-lane, or ambiguous
+  - product-lane writes belong under docs/truthmark/product and state product promises, boundaries, rationale, decisions, and success criteria
+  - engineering-lane writes belong under docs/truthmark/engineering and state source-backed current realization, contracts, architecture, workflows, operations, or tests
+  - both-lane work must write separate product and engineering docs and cross-link them in route YAML with realized_by and realizes, not in doc frontmatter
+  - ambiguous lane ownership must stop or invoke Truth Structure instead of writing a mixed document
+  - Do not make product docs a summary of engineering docs. Do not make engineering docs a detailed version of product docs. Product truth says what must be true and why. Engineering truth says how the repository currently realizes it.
+- document current implemented behavior; do not invent future behavior or planned endpoints
+- may write canonical truth docs and docs/truthmark/routes/areas.md or relevant child route files only
+- must not write functional code
+- when routing is missing, stale, broad, overloaded, catch-all, or cannot map the behavior to a bounded truth owner, run Truth Structure first when routing repair is safe and in scope
+- stop and recommend Truth Structure when routing repair is unsafe, ambiguous, or outside the task boundary
+- keep feature README.md files as indexes rather than truth-document targets
+- create or update bounded leaf truth docs when behavior does not fit an existing leaf doc
+- write product capability/boundary truth under docs/truthmark/product when documenting product promise, boundary, rationale, or user/stakeholder value
+- write engineering truth under docs/truthmark/engineering when documenting implementation behavior, contracts, architecture, workflows, operations, or tests
+- for both-lane documentation requests, write separate product and engineering docs and cross-link them in route YAML with realized_by and realizes, not in doc frontmatter
+- keep engineering behavior truth behavior-oriented, not endpoint-oriented, unless the endpoint itself is the behavior boundary
+- keep API endpoint details in the nearest contract truth doc when such a doc owns the API contract
+- preserve unrelated authored content
+Truth-doc ownership review:
+- before editing or relying on the implemented behavior and candidate truth docs, verify each target/source truth doc is a bounded owner for the behavior
+- if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it
+- if the target doc is broad, mixed-owner, index-like, or the documented behavior spans independent owners, run Truth Structure first when safe and in scope; otherwise stop and recommend Truth Structure
+- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Manual handoff reason as applicable
+Decision/Rationale preservation review:
+- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions, Engineering Decisions, and Rationale sections in every source or touched truth doc
+- preserve each current decision and rationale in the correct product or engineering lane owner; when splitting, move it to the new owner doc rather than deleting it or leaving it in an index
+- remove or narrow a decision or rationale only when checkout evidence shows it is stale or unsupported, and report the exact claim, evidence, and result
+- if ownership of a decision or rationale is unclear, stop with manual-review files instead of deleting it or guessing
+- after the edit, verify every touched truth doc keeps lane-appropriate decision/rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked
+Evidence checklist:
+- route-first: map the documented behavior to bounded route owners and primary canonical docs
+- review new or changed behavior-bearing claims only in touched docs, route ownership, lane-specific decisions, and rationale
+- support claims with primary checkout evidence: implementation, config, routing, generated templates, schemas, or contract definitions
+- tests/examples/canonical docs corroborate; they are not sole proof when implementation conflicts
+- remove, narrow, or record unsupported claims for manual handoff
+- 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 WorkflowState/action context may guide routing, write boundaries, and verification planning when available.
+They do not override checkout evidence, canonical truth docs, route files, or workflow write boundaries.
+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 template under the configured Truthmark templates root.
+Supported kinds: product-capability, engineering-behavior, engineering-contract, engineering-architecture, engineering-workflow, engineering-operations, and engineering-test-behavior.
+Treat the HTML comments under each template section as normative authoring guidance for that section.
+Align existing docs to that template and write or repair section content so it satisfies the comment guidance while preserving accurate authored content.
+If the template is missing, use lane-specific sections: product truth says what must be true and why; engineering truth says how the repository currently realizes it.
+Teams may edit template files under the configured Truthmark templates root to define their local truth-doc standards.
+Truth-doc shape repair review:
+- Truth Document may restructure only truth docs for the implemented behavior being documented.
+- repair shape in place only after the ownership review confirms the doc is the right bounded owner
+- use Truth Structure for ownership splits; do not treat broad or mixed-owner docs as in-place repair work
+- repair shape when a narrow edit would make truth worse: missing template sections, stale evidence conflicts, cross-section updates within one owner, or wrong frontmatter/source/headings
+- preserve supported claims; remove, narrow, or record unsupported or stale claims for manual handoff
+- 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 hints:
+- Config, when present: .truthmark/config.yml
+- Root route index, when present: docs/truthmark/routes/areas.md
+- Area route files, when present: docs/truthmark/routes/areas/**/*.md
+- Product truth docs, when present: docs/truthmark/product/**/*.md
+- Engineering truth docs, when present: docs/truthmark/engineering/**/*.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.
+Product decisions belong in product truth; engineering, architecture, contract, workflow, and operational decisions belong in engineering truth.
+Helper status reporting:
+- Validate the report body before adding this validator's own success status; the body may omit `validate-document-report` while validation is pending.
+- After `truthmark validate document-report <report-file> --json` returns `data.validation.ok: true`, append or update `validate-document-report: ran, passed` in the final report.
+- If the installed Truthmark CLI is unavailable or the helper is skipped, record `validate-document-report: skipped, <reason>` 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.
+Parent post-document verification:
+- verify only truth docs and leased truth routing files changed during document work
+- stop on functional code, generated host surfaces, or unrelated diffs caused by document work
+- for each write lease, validate the worker report against the actual worker diff, allowedWrites, forbiddenWrites, identity fields, filesChanged, offLeaseChanges, blockers, and expected report fields before accepting it
+- verify the final report records ownership review, structure requirement, restructure, routing update, or manual handoff reason when applicable
@@ -0,0 +1,37 @@
+# Truthmark Document Report Template
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+Report completion in this shape:
+```md
+Truth Document: completed
+
+Implementation reviewed:
+- src/routing/area-resolver.ts
+
+Ownership reviewed:
+- docs/truthmark/routes/areas.md
+
+Truth docs created:
+- docs/truthmark/engineering/contracts/routing.md
+
+Truth docs updated:
+- docs/truthmark/engineering/behaviors/check-diagnostics.md
+
+Truth docs restructured:
+- docs/truthmark/engineering/behaviors/check-diagnostics.md
+
+Routing updated:
+- docs/truthmark/routes/areas.md
+
+Evidence checked:
+- Claim: Route resolution behavior is documented in the contracts truth doc.
+  Evidence: src/routing/area-resolver.ts:14 / docs/truthmark/routes/areas.md:9
+  Result: supported
+
+Helper scripts:
+- validate-write-lease: skipped, no write lease used
+
+Notes:
+- Documented routing and behavior from route handlers and tests.
+```
@@ -0,0 +1,14 @@
+# Truthmark Document Subagents And Leases
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+Codex subagent mode:
+- use automatically when this workflow runs in Codex and the parent agent chooses bounded subagent fan-out
+- dispatch read-only project agents for verification: truth_route_auditor, truth_claim_verifier
+- read-only workers inspect checkout evidence directly, return structured findings, and must not edit files
+- parent supplies bounded evidence shards; read-only workers must not preload host instruction files or repo-wide policy docs unless assigned as evidence
+- dispatch write-capable project agents only with explicit write leases: truth_doc_writer
+- each write lease must name objective, required reads, allowed writes, forbidden writes, evidence, verification, and report fields
+- write workers must stop when a required edit is off-lease and report status, filesChanged, evidence, offLeaseChanges, blockers, and notes
+- parent must inspect the actual checkout diff against each lease before accepting a worker report
+- Parent agent owns Truth Document acceptance, lease validation, and final report
@@ -0,0 +1,25 @@
+---
+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 Preview
+
+Use this skill only when the user explicitly asks to preview Truthmark routing or workflow choice before edits.
+
+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 repository instruction files that exist in this checkout; do not assume any optional policy path exists.
+- Inspect .truthmark/config.yml and the root route index (docs/truthmark/routes/areas.md) first when present; then inspect only child route files under docs/truthmark/routes/areas/ that are relevant to the selected scope or changed paths, plus 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.
+- Hand off to the selected workflow after user approval.
+
+Progressive disclosure:
+- support/procedure.md — read before edits or detailed auditing; contains core review questions
+- support/report-template.md — read before the final report
+- support/subagents-and-leases.md — read only when using subagents, leases, or accepting worker output
@@ -0,0 +1,10 @@
+interface:
+  display_name: "Truthmark Preview"
+  short_description: "Preview likely workflow routing before edits; read-only and explicit"
+  default_prompt: "Use $truthmark-preview to preview likely Truthmark routing before edits."
+
+policy:
+  allow_implicit_invocation: false
+
+truthmark:
+  refresh_command: "truthmark init"
@@ -0,0 +1,53 @@
+# Truthmark Preview Procedure
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+Use this skill only when the user explicitly asks to preview Truthmark routing or workflow choice before edits.
+
+Invocations: OpenCode /skill truthmark-preview; Codex /truthmark-preview or $truthmark-preview; Claude Code /truthmark-preview; GitHub Copilot /truthmark-preview; Gemini CLI /truthmark:preview.
+
+Truth Preview is read-only. Its report is intended, not authorized.
+
+Purpose:
+- preview the likely Truthmark workflow, route owner, target files, expected write classes, suggested subagent use, and manual handoff questions before edits happen
+- report likely product lane impact, engineering lane impact, target docs, and ambiguity before edits
+- hand off to the selected workflow after user approval
+- keep the selector thin so agents can avoid loading or acting through heavier workflows prematurely
+
+Read:
+- .truthmark/config.yml, only when present
+- docs/truthmark/routes/areas.md, first, only when present
+- relevant child route files under docs/truthmark/routes/areas/ for the selected scope or changed paths, only when present
+- relevant truth docs and implementation files needed to preview ownership
+- Evidence 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.
+- Lane classification:
+  - classify the request or changed surface as product-lane, engineering-lane, both-lane, or ambiguous for reporting only
+  - product-lane ownership belongs under docs/truthmark/product and describes product promises, boundaries, rationale, decisions, and success criteria
+  - engineering-lane ownership belongs under docs/truthmark/engineering and describes source-backed current realization, contracts, architecture, workflows, operations, or tests
+  - both-lane ownership uses separate product and engineering docs cross-linked in route YAML with realized_by and realizes, not in doc frontmatter
+  - ambiguous lane ownership should be reported for manual handoff or routed to Truth Structure
+  - Do not make product docs a summary of engineering docs. Do not make engineering docs a detailed version of product docs. Product truth says what must be true and why. Engineering truth says how the repository currently realizes it.
+
+Do not:
+- must not edit files
+- must not create truth docs
+- must not update routing
+- must not run Truth Sync automatically
+- must not replace Truth Check
+- must not claim final correctness
+- must not issue write leases
+- must not mutate code
+
+Suggested subagent use:
+- optional read-only verifier: truth_route_auditor
+- write workers: none
+- leases needed: none
+
+Truthmark hierarchy hints:
+- Config, when present: .truthmark/config.yml
+- Root route index, when present: docs/truthmark/routes/areas.md
+- Area route files, when present: docs/truthmark/routes/areas/**/*.md
+- Product truth docs, when present: docs/truthmark/product/**/*.md
+- Engineering truth docs, when present: docs/truthmark/engineering/**/*.md
@@ -0,0 +1,43 @@
+# Truthmark Preview Report Template
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+Report completion in this shape:
+```md
+Truth Preview: completed
+
+Requested outcome:
+- preview likely Truthmark workflow routing before edits
+
+Likely workflow:
+- truthmark-document
+
+Why this workflow:
+- positive trigger: document existing implemented behavior
+- negative triggers considered: functional-code change, doc-first implementation, topology repair, truth audit
+- forbidden adjacency considered: must not edit functional code
+
+Likely route owner:
+- route file: docs/truthmark/routes/areas.md
+- likely lane impact: engineering-lane
+- product target docs: none identified
+- engineering target docs: docs/truthmark/engineering/behaviors/example.md
+- confidence: medium
+
+Expected write classes:
+- truth docs
+
+Expected target files:
+- docs/truthmark/engineering/behaviors/example.md
+
+Suggested subagent use:
+- read-only verifiers: truth_route_auditor
+- write workers: none in Preview
+- leases needed: none in Preview
+
+Manual handoff questions:
+- none identified in preview
+
+Handoff:
+- Run the selected Truthmark workflow after user approval.
+```
@@ -0,0 +1,10 @@
+# Truthmark Preview Subagents And Leases
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+Codex subagent mode:
+- use automatically when this workflow runs in Codex and the parent agent chooses bounded subagent fan-out
+- dispatch read-only project agents only: truth_route_auditor
+- workers inspect checkout evidence directly, return structured findings, and must not edit files
+- parent supplies bounded evidence shards; workers must not preload host instruction files or repo-wide policy docs unless assigned as evidence
+- Parent agent owns the final Truth Preview report
@@ -0,0 +1,24 @@
+---
+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 Realize
+
+Use this skill only when the user explicitly asks to realize truth docs into code.
+
+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 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/routes/areas.md; docs/truthmark/routes/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.
+- Read support/report-template.md before the final report.
+
+Progressive disclosure:
+- support/procedure.md — read before edits or detailed auditing; contains core review questions
+- support/report-template.md — read before the final report
@@ -7,5 +7,4 @@ policy:
  allow_implicit_invocation: false

 truthmark:
-  version: "1.2.3"
  refresh_command: "truthmark init"
@@ -0,0 +1,43 @@
+# Truthmark Realize Procedure
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+# Truthmark Realize
+
+Use this skill only when the user explicitly asks to realize truth docs into code.
+
+Invocations: OpenCode /skill truthmark-realize; Codex /truthmark-realize or $truthmark-realize; Claude Code /truthmark-realize; GitHub Copilot /truthmark-realize; Gemini CLI /truthmark:realize.
+
+Truth Realize is doc-first:
+
+- truth docs lead
+- code follows
+- Truth Realize never edits the truth docs it is realizing
+
+Workflow:
+
+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/routes/areas.md; docs/truthmark/routes/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 review:
+- before editing or relying on source truth docs before writing code, verify each target/source truth doc is a bounded owner for the behavior
+- if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it
+- if a source truth doc is broad, mixed-owner, index-like, unrouteable, stale, or conflicts with implementation evidence, stop before writing code and recommend Truth Structure or Truth Document
+- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Manual handoff reason as applicable
+4. Update functional code only so implementation matches bounded, current truth claims from the source docs.
+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 hints:
+- Config, when present: .truthmark/config.yml
+- Root route index, when present: docs/truthmark/routes/areas.md
+- Area route files, when present: docs/truthmark/routes/areas/**/*.md
+- Product truth docs, when present: docs/truthmark/product/**/*.md
+- Engineering truth docs, when present: docs/truthmark/engineering/**/*.md
+
+Read and write boundaries:
+
+- may read truth docs, routing docs, and relevant functional code
+- may write functional code only
+- must not edit truth docs or truth routing while realizing those docs
@@ -0,0 +1,19 @@
+# Truthmark Realize Report Template
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+Report completion in this shape:
+
+```md
+Truth Realize: completed
+
+Truth docs used:
+- docs/truthmark/product/capabilities/authentication-session.md
+- docs/truthmark/engineering/behaviors/authentication-session.md
+
+Code updated:
+- src/auth/session.ts
+
+Verification:
+- npm test -- auth
+```
@@ -0,0 +1,25 @@
+---
+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 Structure
+
+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 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/routes/areas.md; docs/truthmark/routes/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.
+- Read support/report-template.md before the final report.
+
+Progressive disclosure:
+- support/procedure.md — read before edits or detailed auditing; contains core review questions
+- support/report-template.md — read before the final report
+- support/subagents-and-leases.md — read only when using subagents, leases, or accepting worker output
@@ -0,0 +1,10 @@
+interface:
+  display_name: "Truthmark Structure"
+  short_description: "Design, repair, or set up Truthmark area routing"
+  default_prompt: "Use $truthmark-structure to design, repair, or set up Truthmark area routing."
+
+policy:
+  allow_implicit_invocation: false
+
+truthmark:
+  refresh_command: "truthmark init"
@@ -0,0 +1,121 @@
+# Truthmark Structure Procedure
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+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 and route files when present, and relevant code directly
+- Evidence 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.
+- Lane classification:
+  - before writing canonical truth docs, classify the request or change as product-lane, engineering-lane, both-lane, or ambiguous
+  - product-lane writes belong under docs/truthmark/product and state product promises, boundaries, rationale, decisions, and success criteria
+  - engineering-lane writes belong under docs/truthmark/engineering and state source-backed current realization, contracts, architecture, workflows, operations, or tests
+  - both-lane work must write separate product and engineering docs and cross-link them in route YAML with realized_by and realizes, not in doc frontmatter
+  - ambiguous lane ownership must stop or invoke Truth Structure instead of writing a mixed document
+  - Do not make product docs a summary of engineering docs. Do not make engineering docs a detailed version of product docs. Product truth says what must be true and why. Engineering truth says how the repository currently realizes it.
+- inspect the configured root route index at docs/truthmark/routes/areas.md and relevant child route files under docs/truthmark/routes/areas/ when they exist
+- define areas by product or behavior ownership, not by mechanical directory mirroring
+- create or repair docs/truthmark/routes/areas.md
+- create starter truth docs when useful and when they belong in the canonical current-truth surface
+- Starter truth docs must use closed YAML frontmatter bounded by opening and closing --- lines; include status, truth_kind, and last_reviewed inside that frontmatter. Put source references in the final ## Source References section, not in frontmatter.
+- Starter truth docs must use lane-specific templates and keep product and engineering truth in separate files.
+
+When creating or updating a truth doc, inspect the routed truth kind and use the matching template under the configured Truthmark templates root.
+Supported kinds: product-capability, engineering-behavior, engineering-contract, engineering-architecture, engineering-workflow, engineering-operations, and engineering-test-behavior.
+Treat the HTML comments under each template section as normative authoring guidance for that section.
+Align existing docs to that template and write or repair section content so it satisfies the comment guidance while preserving accurate authored content.
+If the template is missing, use lane-specific sections: product truth says what must be true and why; engineering truth says how the repository currently realizes it.
+Teams may edit template files under the configured Truthmark templates root to define their local truth-doc standards.
+- use docs/truthmark/product/** for product truth destinations
+- use docs/truthmark/engineering/** for engineering truth destinations
+- use only canonical current-truth destinations for starter truth docs
+- keep active Product Decisions in product truth and Engineering Decisions in engineering truth
+- preserve unrelated authored content
+## New area setup
+Use when a user asks to onboard a new code area into Truthmark, a new package, controller, domain, or product area lacks bounded truth ownership, or a new product area needs routing and starter truth docs.
+Do:
+- inspect the named code area
+- infer bounded product or behavior ownership
+- choose the owning route when ownership is clear; otherwise propose the route and stop for manual review
+- create or update the child route entry or file
+- create starter truth docs only where current truth is missing
+- report the initial truth boundary
+Do not:
+- do not edit functional code
+- do not perform full behavior documentation unless evidence is inspected and the task explicitly asks for it
+- do not patch broad or mixed-owner docs in place
+- do not create generic catch-all docs
+- do not treat README files as Sync targets
+## Topology Governance
+Truth Structure owns documentation topology, lane splits, decision relocation, and relationship repair. Do not depend on humans to manually organize docs/truthmark/product or docs/truthmark/engineering. Treat both configured lane roots as managed semantic roots.
+Inspect controllers, routes, handlers, services, packages, tests, existing truth docs, and route files; infer product and domain ownership from behavior boundaries, not from mechanical directory mirroring.
+When topology pressure exists, repair structure before creating or extending truth docs.
+Truth-doc ownership review:
+- before editing or relying on candidate route owners and current truth docs, verify each target/source truth doc is a bounded owner for the behavior
+- if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it
+- if a truth doc mixes independent owners, route ownership is broad, or a split is required for bounded ownership, split and reroute into bounded truth docs when safe; otherwise stop with manual-review files
+- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Manual handoff reason as applicable
+Decision/Rationale preservation review:
+- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions, Engineering Decisions, and Rationale sections in every source or touched truth doc
+- preserve each current decision and rationale in the correct product or engineering lane owner; when splitting, move it to the new owner doc rather than deleting it or leaving it in an index
+- remove or narrow a decision or rationale only when checkout evidence shows it is stale or unsupported, and report the exact claim, evidence, and result
+- if ownership of a decision or rationale is unclear, stop with manual-review files instead of deleting it or guessing
+- after the edit, verify every touched truth doc keeps lane-appropriate decision/rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked
+Topology pressure signals:
+- one area maps broad code such as src/**, app/**, server/**, services/**, or packages/**
+- one area maps multiple unrelated controllers, route groups, services, or bounded contexts
+- one truth doc owns unrelated behaviors or unrelated endpoint families
+- either configured lane root has many direct non-index docs
+- a changed controller, route, or service cannot map to a specific behavior doc
+- Truth Sync would need to create a new generic truth doc because routing is too broad
+- endpoint or controller names reveal domains missing from docs/truthmark/routes/areas/**
+Use these review thresholds as guidance:
+- more than 10 direct truth docs in one folder
+- more than 15 leaf areas in one child route file
+- more than 8 truth docs mapped to one area
+- more than 5 controllers mapped through one catch-all area
+Repair rules:
+- split broad, overloaded, or catch-all areas into behavior-owned child route files
+- split mixed-owner truth docs into bounded owner docs before adding new behavior claims
+- create route files under docs/truthmark/routes/areas/ when a product/domain boundary is clear
+- create engineering behavior truth docs under docs/truthmark/engineering only when behavior lacks a current doc
+- create product truth docs under docs/truthmark/product only when product promise, boundary, rationale, or user-visible capability truth is in scope
+- README.md files are indexes, not Truth Sync targets
+- prefer bounded product docs under product/capabilities or product/decisions and engineering docs under engineering/<kind>/<surface>.md
+- keep behavior truth docs behavior-oriented, not endpoint-oriented
+- keep API endpoint details in the nearest contract truth doc when such a doc exists
+- update routing so future Truth Sync can target small docs
+- preserve existing authored docs; move or rewrite only when needed to remove ambiguity
+- report Truth docs split when one broad or mixed-owner truth doc becomes multiple bounded docs
+Truth-doc shape repair review:
+- Truth Structure may restructure broader routed docs when topology, ownership, or doc-shape repair is already in scope.
+- repair shape in place only after the ownership review confirms the doc is the right bounded owner
+- use Truth Structure for ownership splits; do not treat broad or mixed-owner docs as in-place repair work
+- repair shape when a narrow edit would make truth worse: missing template sections, stale evidence conflicts, cross-section updates within one owner, or wrong frontmatter/source/headings
+- preserve supported claims; remove, narrow, or record unsupported or stale claims for manual handoff
+- report docs restructured and why a narrow edit was not sufficient
+Evidence checklist:
+- apply the evidence checklist before finishing when Truth Structure writes routed docs, ownership claims, lane-specific decisions, or rationale
+- support ownership/behavior claims with topology or primary checkout evidence from layout, implementation boundaries, docs, config, route files, tests, templates, schemas, or contracts
+- tests/examples/canonical docs corroborate; remove, narrow, or record unsupported claims for manual handoff
+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.
+- Do not finish topology repair with mixed product/engineering authority in a single canonical truth doc.
+- If an existing canonical doc has wrong-lane sections, split or move them into the correct product or engineering lane.
+Portable fallback:
+- If this skill surface is unavailable, perform the same workflow directly from committed repository files.
+- Do not require the truthmark CLI.
+- 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 hints:
+- Config, when present: .truthmark/config.yml
+- Root route index, when present: docs/truthmark/routes/areas.md
+- Area route files, when present: docs/truthmark/routes/areas/**/*.md
+- Product truth docs, when present: docs/truthmark/product/**/*.md
+- Engineering truth docs, when present: docs/truthmark/engineering/**/*.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.
+Product decisions belong in product truth; engineering, architecture, contract, workflow, and operational decisions belong in engineering truth.
@@ -0,0 +1,38 @@
+# Truthmark Structure Report Template
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+Report completion in this shape:
+```md
+Truth Structure: completed
+Topology reviewed:
+- controllers: src/auth/**
+- product docs root: docs/truthmark/product
+- engineering docs root: docs/truthmark/engineering
+- route files: docs/truthmark/routes/areas.md
+Areas reviewed:
+- src/auth/**
+Routing updated:
+- docs/truthmark/routes/areas.md
+Initial truth boundary:
+- Area: Authentication
+- Code: src/auth/**
+- Product owner: docs/truthmark/product/capabilities/authentication-session.md
+- Engineering owner: docs/truthmark/engineering/behaviors/authentication-session.md
+- Scope: session behavior only
+Truth docs created:
+- docs/truthmark/product/capabilities/authentication-session.md
+- docs/truthmark/engineering/behaviors/authentication-session.md
+Truth docs split:
+- docs/truthmark/truth/authentication/README.md -> docs/truthmark/product/capabilities/authentication-session.md and docs/truthmark/engineering/behaviors/authentication-session.md
+Truth docs restructured:
+- docs/truthmark/truth/authentication/README.md
+Evidence checked:
+- Claim: Session behavior belongs to a dedicated Authentication truth owner.
+  Evidence: src/auth/** / docs/truthmark/routes/areas.md:7
+  Result: supported
+Topology decisions:
+- Added an Authentication area because session behavior has a distinct code surface and truth owner.
+Notes:
+- Added an Authentication area for session behavior.
+```
@@ -0,0 +1,10 @@
+# Truthmark Structure Subagents And Leases
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+Codex subagent mode:
+- use automatically when this workflow runs in Codex and the parent agent chooses bounded subagent fan-out
+- dispatch read-only project agents only: truth_route_auditor
+- workers inspect checkout evidence directly, return structured findings, and must not edit files
+- parent supplies bounded evidence shards; workers must not preload host instruction files or repo-wide policy docs unless assigned as evidence
+- Parent agent owns all Truth Structure writes and final topology decisions
@@ -0,0 +1,29 @@
+---
+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 Sync
+
+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.
+
+Quick procedure:
+- 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.
+- Inspect .truthmark/config.yml and configured route files (docs/truthmark/routes/areas.md; docs/truthmark/routes/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.
+- Read support/subagents-and-leases.md only when dispatching or accepting worker output.
+- Read support/report-template.md before the final report.
+
+Progressive disclosure:
+- support/procedure.md — read before edits or detailed auditing; contains core review questions
+- support/report-template.md — read before the final report
+- support/subagents-and-leases.md — read only when using subagents, leases, or accepting worker output
+- helper-manifest.yml — read only when invoking helper validators or validating helper registration
+- support/helper-policy.md — read only when invoking helper validators or reporting helper status
@@ -7,5 +7,4 @@ policy:
  allow_implicit_invocation: true

 truthmark:
-  version: "1.2.3"
  refresh_command: "truthmark init"
@@ -0,0 +1,34 @@
+# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+helpers:
+  validate-sync-report:
+    optional: true
+    runner: truthmark
+    command:
+      argv:
+        - truthmark
+        - validate
+        - sync-report
+        - <report-file>
+        - --json
+    inputs:
+      - sync report file
+    output: json
+    writes: false
+    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
+    command:
+      argv:
+        - truthmark
+        - validate
+        - write-lease
+        - <lease-or-report-file>
+        - <changed-files-file>
+        - --json
+    inputs:
+      - lease or worker report yaml
+      - changed file list
+    output: json
+    writes: false
+    fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files
@@ -0,0 +1,23 @@
+# Optional Helper CLI Policy
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+Optional helper CLI commands may collect deterministic checkout facts or validate artifacts. If the Truthmark CLI is unavailable or cannot return the declared helper output, 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.
+
+Runner detection:
+- Check that the declared Truthmark CLI runner is available before invoking a helper.
+- Invoke helpers through the installed `truthmark validate ... --json` CLI command using argv-style arguments from helper-manifest.yml.
+- If unavailable, failing, or returning incompatible output, treat the helper as skipped and use the manual fallback.
+- Do not fail the workflow solely because a helper cannot run.
+
+Available helpers:
+- validate-sync-report: optional truthmark; 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; 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:
+
+```md
+Helper scripts:
+- validate-sync-report: ran, passed
+- validate-write-lease: skipped, no write lease used
+```
@@ -0,0 +1,110 @@
+# Truthmark Sync Procedure
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+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.
+Explicit invocation runs immediately. Later functional-code changes need a fresh finish-time review, and an earlier explicit run satisfies the finish-time review only if no later functional-code changes occur.
+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. 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:
+  - 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. Product truth decision:
+  - ask whether a user-visible promise, capability boundary, API contract, acceptance criterion, or explicit user/product evidence changed
+  - if yes, update or route product truth under docs/truthmark/product as well as engineering truth under docs/truthmark/engineering
+  - if no, default to engineering truth under docs/truthmark/engineering for internal implementation changes
+  - when both lanes change, keep separate product and engineering docs cross-linked through route YAML with realized_by and realizes
+  - when ownership is ambiguous, stop or route to Truth Structure instead of writing a mixed document
+6. Capture decision context from the task conversation: ask whether the user provided a product or technical decision, rationale, constraint, tradeoff, rejection reason, or scope boundary. Preserve concise user-provided decision rationale in Sync Intent before truth edits, route it to Product Decisions, Engineering Decisions, Rationale, Capability Scope, Non-Goals, Maintenance Notes, or the relevant workflow/contract section, and report whether it was placed, skipped because none was provided, or needs manual handoff.
+7. Update engineering truth first after code changes. Product truth is opt-in for externally visible promises, product boundaries, APIs, acceptance criteria, or explicit user/product evidence.
+8. Code verification is parent-owned: follow repository instructions and task context, and report what ran or why it did not run.
+9. 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.
+10. Fill Sync Intent before editing truth docs or truth routing files:
+   - Changed code reviewed: functional files, tests, configs, generated outputs, or other implementation evidence inspected
+   - Affected route/truth owner: bounded route area or canonical truth owner that maps the change
+   - Target truth docs: docs expected to change, or docs reviewed and left unchanged
+   - Intended update: claim/doc/routing update planned before writing
+   - Evidence to verify: checkout evidence that will support, narrow, remove, or record each claim for manual handoff
+   - User-provided decisions/rationale: decisions, rationale, constraints, tradeoffs, rejection reasons, or scope boundaries from the current task conversation, or "none provided"
+   - No-update-needed rationale: why mapped truth is already current when no truth doc should change
+   - Blockers: missing routing, ambiguous ownership, failed verification, unavailable evidence, or off-boundary write needs
+11. Only edit allowed truth docs/routes after Sync Intent is clear; if ownership is ambiguous, stop and recommend Truth Structure instead of guessing.
+Topology review:
+- before updating truth docs, verify the changed code resolves to a specific behavior-owned area and bounded truth owner
+- if routing is missing, stale, broad, overloaded, catch-all route only, or cannot map changed code to a bounded truth owner, do not create another generic truth doc
+- run Truth Structure before syncing when topology repair is safe and in scope
+- stop and recommend Truth Structure when topology repair is unsafe, ambiguous, or outside the current task boundary
+- report the route files and changed code paths that require structure repair
+- README.md files are indexes, not Truth Sync targets
+- must not append behavior details to a README.md index
+- create or update a bounded leaf truth doc when behavior changes do not fit an existing leaf doc
+- write engineering truth under docs/truthmark/engineering; product truth updates under docs/truthmark/product are allowed only for explicit current product behavior changes
+Truth-doc ownership review:
+- before editing or relying on changed functional files and impacted truth docs, verify each target/source truth doc is a bounded owner for the behavior
+- if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it
+- if an impacted doc is broad, mixed-owner, index-like, or the update spans independent behavior owners, run Truth Structure before syncing when safe and in scope; otherwise stop and recommend Truth Structure
+- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Manual handoff reason as applicable
+Decision/Rationale preservation review:
+- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions, Engineering Decisions, and Rationale sections in every source or touched truth doc
+- preserve each current decision and rationale in the correct product or engineering lane owner; when splitting, move it to the new owner doc rather than deleting it or leaving it in an index
+- remove or narrow a decision or rationale only when checkout evidence shows it is stale or unsupported, and report the exact claim, evidence, and result
+- if ownership of a decision or rationale is unclear, stop with manual-review files instead of deleting it or guessing
+- after the edit, verify every touched truth doc keeps lane-appropriate decision/rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked
+When creating or updating a truth doc, inspect the routed truth kind and use the matching template under the configured Truthmark templates root.
+Supported kinds: product-capability, engineering-behavior, engineering-contract, engineering-architecture, engineering-workflow, engineering-operations, and engineering-test-behavior.
+Treat the HTML comments under each template section as normative authoring guidance for that section.
+Align existing docs to that template and write or repair section content so it satisfies the comment guidance while preserving accurate authored content.
+If the template is missing, use lane-specific sections: product truth says what must be true and why; engineering truth says how the repository currently realizes it.
+Teams may edit template files under the configured Truthmark templates root to define their local truth-doc standards.
+Truth-doc shape repair review:
+- Truth Sync may restructure leased canonical truth docs when the current sync evidence shows repository truth is stale, even when the doc is outside the initially affected route focus.
+- repair shape in place only after the ownership review confirms the doc is the right bounded owner
+- use Truth Structure for ownership splits; do not treat broad or mixed-owner docs as in-place repair work
+- repair shape when a narrow edit would make truth worse: missing template sections, stale evidence conflicts, cross-section updates within one owner, or wrong frontmatter/source/headings
+- preserve supported claims; remove, narrow, or record unsupported or stale claims for manual handoff
+- 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.
+Evidence checklist:
+- route-first: map changed functional files to bounded route owners and primary canonical docs
+- review new or changed behavior-bearing claims only in touched docs, route ownership, lane-specific decisions, and rationale
+- support claims with primary checkout evidence: implementation, config, routing, generated templates, schemas, or contract definitions
+- tests/examples/canonical docs corroborate; they are not sole proof when implementation conflicts
+- remove, narrow, or record unsupported claims for manual handoff
+- 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 WorkflowState/action context may guide routing, write boundaries, and verification planning when available.
+They do not override checkout evidence, canonical truth docs, route files, or workflow write boundaries.
+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
+- optional validation must not replace agent judgment about docs and routing
+- update Product Decisions only in product truth and Engineering Decisions only in engineering truth when evidence supports the lane-specific decision change
+Helper status reporting:
+- Validate the report body before adding this validator's own success status; the body may omit `validate-sync-report` while validation is pending.
+- After `truthmark validate sync-report <report-file> --json` returns `data.validation.ok: true`, append or update `validate-sync-report: ran, passed` in the final report.
+- If the installed Truthmark CLI is unavailable or the helper is skipped, record `validate-sync-report: skipped, <reason>` 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 hints:
+- Config, when present: .truthmark/config.yml
+- Root route index, when present: docs/truthmark/routes/areas.md
+- Area route files, when present: docs/truthmark/routes/areas/**/*.md
+- Product truth docs, when present: docs/truthmark/product/**/*.md
+- Engineering truth docs, when present: docs/truthmark/engineering/**/*.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.
+Product decisions belong in product truth; engineering, architecture, contract, workflow, and operational decisions belong in engineering truth.
+Parent post-sync verification:
+- verify only truth docs and leased truth routing files changed during sync
+- stop on any unrelated diff caused by the sync step
+- stop if functional code changed during sync
+- for each write lease, validate the worker report against the actual worker diff, allowedWrites, forbiddenWrites, identity fields, filesChanged, offLeaseChanges, blockers, and expected report fields before accepting it
+- validate the final report against the structured Truth Sync report contract, including Claim, indented Evidence, and Result values supported, narrowed, removed, or blocked under Evidence checked
+- verify the updated docs correspond to reviewed checkout evidence, changed-code impact, or a recorded stale-truth correction made within the sync write lease
+- verify the final report records ownership review, structure requirement, split, restructure, or manual handoff reason when the ownership review applies
+- manual handoff outcomes must preserve the working tree as-is: no rollback, no post-block cleanup edits, and manual-review reporting of any remaining files
@@ -0,0 +1,54 @@
+# Truthmark Sync Report Template
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+Report completion in this shape:
+```md
+Truth Sync: completed
+
+Changed code reviewed:
+- src/auth/session.ts
+
+Sync Intent:
+- Changed code reviewed: src/auth/session.ts
+- Affected route/truth owner: docs/truthmark/routes/areas.md
+- Target truth docs: docs/truthmark/engineering/repository/bootstrap-routing.md
+- Intended update: Update session timeout behavior.
+- Evidence to verify: src/auth/session.ts:12 / docs/truthmark/routes/areas.md:11
+- User-provided decisions/rationale: User rationale: session timeout behavior changed for internal implementation consistency
+- No-update-needed rationale: not applicable; mapped truth is stale
+- Blockers: none
+
+Ownership reviewed:
+- docs/truthmark/routes/areas.md
+
+Truth docs updated:
+- docs/truthmark/engineering/repository/bootstrap-routing.md
+
+Decision/rationale captured:
+- Placed user rationale in the mapped engineering truth doc under Engineering Decisions/Rationale.
+
+Evidence checked:
+- Claim: Session timeout behavior is documented in the mapped repository truth doc.
+  Evidence: src/auth/session.ts:12 / docs/truthmark/routes/areas.md:11
+  Result: supported
+
+Helper scripts:
+- validate-write-lease: skipped, no write lease used
+
+Notes:
+- Updated session timeout behavior.
+```
+Blocked report example:
+```md
+Truth Sync: blocked
+
+Reason:
+- routing repair is not allowed
+
+Files requiring manual review:
+- docs/truthmark/routes/areas.md
+
+Next action:
+- update routing metadata and rerun Truth Sync
+```
@@ -0,0 +1,14 @@
+# Truthmark Sync Subagents And Leases
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+Codex subagent mode:
+- use automatically when this workflow runs in Codex and the parent agent chooses bounded subagent fan-out
+- dispatch read-only project agents for verification: truth_route_auditor, truth_claim_verifier
+- read-only workers inspect checkout evidence directly, return structured findings, and must not edit files
+- parent supplies bounded evidence shards; read-only workers must not preload host instruction files or repo-wide policy docs unless assigned as evidence
+- dispatch write-capable project agents only with explicit write leases: truth_doc_writer
+- each write lease must name objective, required reads, allowed writes, forbidden writes, evidence, verification, and report fields
+- write workers must stop when a required edit is off-lease and report status, filesChanged, evidence, offLeaseChanges, blockers, and notes
+- parent must inspect the actual checkout diff against each lease before accepting a worker report
+- Parent agent owns Truth Sync acceptance, lease validation, and final report
@@ -0,0 +1,21 @@
+---
+name: truth-claim-verifier
+description: Read-only Truthmark claim verifier for checking canonical truth against checkout evidence.
+tools: Read, Grep, Glob, LS
+---
+
+# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+Manual invocation: use the truth-claim-verifier subagent.
+
+Stay read-only.
+Verify the behavior-bearing truth claims assigned by the parent against primary checkout evidence.
+Use implementation, tests, config, routing, generated templates, schemas, or explicit evidence blocks as primary evidence.
+Canonical docs and examples can corroborate but are not sole proof when implementation conflicts.
+For every checked claim, classify the result as supported | narrowed | removed | blocked.
+Do not edit files, stage changes, or invent missing behavior.
+Return JSON only with keys: scope, filesReviewed, claimsChecked, evidence, unsupportedClaims, confidence, recommendedWorkflow, notes.
+Context boundary:
+Do not preload AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, or repo-wide policy docs unless the parent explicitly assigns them as evidence.
+Use only the parent-assigned shard plus required checkout evidence files.
+Return findings only; the parent workflow owns repository-policy interpretation, final decisions, and all writes.
@@ -0,0 +1,20 @@
+---
+name: truth-doc-reviewer
+description: Read-only Truthmark doc reviewer for shape, decision, rationale, and evidence hygiene.
+tools: Read, Grep, Glob, LS
+---
+
+# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+Manual invocation: use the truth-doc-reviewer subagent.
+
+Stay read-only.
+Review assigned canonical truth docs for compact frontmatter, required template sections, final Source References entries, Evidence checked entries, and lane-appropriate decision sections (Product Decisions in product truth, Engineering Decisions in engineering truth).
+Flag README.md files used as behavior truth targets, mixed-owner docs, and shape repairs that should move to Truth Structure.
+Do not edit files, stage changes, or rewrite docs.
+Return JSON only with keys: scope, filesReviewed, findings, evidence, confidence, recommendedWorkflow, notes.
+recommendedWorkflow must be one of: none, truthmark-document, truthmark-structure.
+Context boundary:
+Do not preload AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, or repo-wide policy docs unless the parent explicitly assigns them as evidence.
+Use only the parent-assigned shard plus required checkout evidence files.
+Return findings only; the parent workflow owns repository-policy interpretation, final decisions, and all writes.
@@ -0,0 +1,21 @@
+---
+name: truth-doc-writer
+description: Write-capable Truthmark doc worker for one parent-leased truth-document shard.
+tools: Read, Grep, Glob, LS, Edit, MultiEdit
+---
+
+# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+Manual invocation: use the truth-doc-writer subagent with an explicit parent write lease.
+
+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.
+Read every requiredReads entry directly before editing.
+Edit only leased canonical truth docs or leased truth routing files. Do not edit functional code, generated host surfaces, package files, config files, templates, or tests unless they are explicitly leased.
+Do not expand your own write scope. If the task needs an off-lease file, stop and report blocked.
+Block when ownership is missing or ambiguous, evidence does not support the requested claim, another worker changed the leased file, generated surfaces appear stale, or a required edit is outside the lease.
+Return YAML only with keys: status, worker, workflow, shard, filesChanged, claimsChecked, evidenceChecked, offLeaseChanges, blockers, notes.
+status must be completed or blocked.
+filesChanged must list only files you actually changed.
+offLeaseChanges must be empty for completed reports.
+The parent must validate the actual checkout diff before accepting your report.
@@ -0,0 +1,28 @@
+---
+name: truth-route-auditor
+description: Read-only Truthmark route auditor for bounded routing and ownership verification.
+tools: Read, Grep, Glob, LS
+---
+
+# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+Manual invocation: use the truth-route-auditor subagent.
+
+Stay read-only.
+Audit one bounded Truthmark route, area, or doc shard assigned by the parent.
+Inspect .truthmark/config.yml and route files only when they exist; then inspect mapped truth docs and relevant implementation files directly.
+Use a route-first bounded strategy: narrow audits inspect only the routed area and directly linked counterpart docs; root-wide health first builds a cheap route-map/index from route files, then inspects only mismatches and linked leaves.
+Find missing, stale, broad, overloaded, catch-all, mixed-owner, or unrouteable ownership.
+Validate route ownership against lane-specific roots and route kind:
+- confirm mapped truth docs resolve to the correct lane root (product or engineering) for their kind
+- flag mismatch between assigned route kind and resolved doc kind (for example, product-capability routed to engineering paths)
+- verify route-doc linkage for lane pairings via realized_by and realizes before recommending edits
+- inspect product counterparts for engineering docs only when route YAML claims a product relationship, or when the parent explicitly asks for user-visible product coverage
+- treat missing product links for user-visible engineering docs as a second-pass diagnostic, not a default full-document read.
+Do not edit files, stage changes, or propose broad rewrites.
+Return JSON only with keys: scope, filesReviewed, findings, evidence, confidence, recommendedWorkflow, notes.
+recommendedWorkflow must be one of: none, truthmark-document, truthmark-structure.
+Context boundary:
+Do not preload AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, or repo-wide policy docs unless the parent explicitly assigns them as evidence.
+Use only the parent-assigned shard plus required checkout evidence files.
+Return findings only; the parent workflow owns repository-policy interpretation, final decisions, and all writes.
@@ -1,9 +1,8 @@
 ---
 name: truthmark-check
-description: Use when the user asks to audit repository truth health. Inspects truth docs, routing, and implementation directly; may optionally run truthmark check when available.
+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.2.3
 ---

 # Truthmark Check
@@ -12,44 +11,15 @@ 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.

-Truth Check is agent-led:
+Quick procedure:
+- 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/routes/areas.md; docs/truthmark/routes/areas/) only when they exist; then inspect canonical docs and relevant implementation directly.
+- Report issues and suggested fixes; do not silently rewrite unrelated files.
+- Read support/procedure.md before auditing details.
+- Read support/subagents-and-leases.md only when dispatching verifier subagents.
+- Read support/report-template.md before the final report.

- 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.
-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/
- 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 canonical behavior docs keep active Product Decisions and Rationale sections
- optionally run truthmark check when local tooling is available
- must not require the truthmark binary; direct inspection is always valid
- report issues and suggested fixes without silently rewriting unrelated files
-
-Truthmark hierarchy:
- Config: .truthmark/config.yml
- Root route index: docs/truthmark/areas.md
- Area route files: docs/truthmark/areas/**/*.md
- Feature docs: docs/features/**/*.md
-Decision truth lives in the canonical doc it governs.
-Date active decisions inline when added or changed, for example `Decision (2026-05-09): ...`.
-Do not create separate timestamped ADR logs or planning tickets for active decisions.
-Replace old active decisions instead of appending separate timestamped decision logs; Git history is the audit trail.
-Update Product Decisions and Rationale when a behavior change comes from a decision change.
-
-Report completion in this shape:
-
-```md
-Truth Check: completed
-
-Files reviewed:
- docs/truthmark/areas.md
-
-Issues found:
- none
-
-Fixes suggested:
- none
-
-Validation:
- truthmark check
-```
+Progressive disclosure:
+- support/procedure.md — read before edits or detailed auditing; contains core review questions
+- support/report-template.md — read before the final report
+- support/subagents-and-leases.md — read only when using subagents, leases, or accepting worker output
@@ -0,0 +1,56 @@
+# Truthmark Check Procedure
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+# Truthmark Check
+
+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.
+
+Truth Check is agent-led:
+
+- inspect .truthmark/config.yml and configured route files only when they exist; then inspect canonical docs and relevant implementation directly
+- inspect the configured root route index at docs/truthmark/routes/areas.md and relevant child route files under docs/truthmark/routes/areas/ when they exist
+- Evidence 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.
+- Lane classification:
+  - classify the request or changed surface as product-lane, engineering-lane, both-lane, or ambiguous for reporting only
+  - product-lane ownership belongs under docs/truthmark/product and describes product promises, boundaries, rationale, decisions, and success criteria
+  - engineering-lane ownership belongs under docs/truthmark/engineering and describes source-backed current realization, contracts, architecture, workflows, operations, or tests
+  - both-lane ownership uses separate product and engineering docs cross-linked in route YAML with realized_by and realizes, not in doc frontmatter
+  - ambiguous lane ownership should be reported for manual handoff or routed to Truth Structure
+  - Do not make product docs a summary of engineering docs. Do not make engineering docs a detailed version of product docs. Product truth says what must be true and why. Engineering truth says how the repository currently realizes it.
+- check that current docs describe current code rather than historical plans
+- keep lane and cross-lane checks route-first and bounded:
+  - for a narrow audit, inspect only the routed area and directly linked counterpart docs
+  - for root-wide truth health, first build a cheap route-map/index from route files, then inspect only mismatches and linked leaves
+  - inspect product counterparts for engineering docs only when route YAML claims a product relationship, or when the user explicitly asks for user-visible product coverage
+- check lane root/kind alignment for product truth under docs/truthmark/product and engineering truth under docs/truthmark/engineering
+- check route YAML cross-lane realized_by and realizes links for existence and lane compatibility
+- report missing product links for user-visible engineering docs only as a second-pass review diagnostic, not as default full-document reads or hard errors
+- check product docs do not contain engineering execution flow, generated file inventories, or CLI envelope mechanics
+- check engineering docs do not contain product promises, product rationale, or Product Decisions sections
+- never judge whether a product decision is commercially correct, valuable, prioritized, or desirable
+- 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 docs keep lane-appropriate decisions and rationale sections
+- optionally run truthmark check when local tooling is available
+- must not require the truthmark binary; direct inspection is always valid
+- report issues and suggested fixes without silently rewriting unrelated files
+- if follow-up docs edits are needed for mixed-owner docs, run or recommend Truth Structure before editing
+Evidence checklist:
+- support each finding and suggested fix with evidence from config, route files, canonical docs, implementation, templates, or tests
+- 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 hints:
+- Config, when present: .truthmark/config.yml
+- Root route index, when present: docs/truthmark/routes/areas.md
+- Area route files, when present: docs/truthmark/routes/areas/**/*.md
+- Product truth docs, when present: docs/truthmark/product/**/*.md
+- Engineering truth docs, when present: docs/truthmark/engineering/**/*.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.
+Product decisions belong in product truth; engineering, architecture, contract, workflow, and operational decisions belong in engineering truth.
@@ -0,0 +1,27 @@
+# Truthmark Check Report Template
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+Report completion in this shape:
+
+```md
+Truth Check: completed
+
+Files reviewed:
+- docs/truthmark/routes/areas.md
+
+Issues found:
+- none
+
+Fixes suggested:
+- none
+
+Evidence checked:
+- Finding: The root route index is present and maps repository truth owners.
+  Evidence: docs/truthmark/routes/areas.md:1
+  Suggested fix: none
+  Confidence: high
+
+Validation:
+- truthmark check
+```
@@ -0,0 +1,10 @@
+# Truthmark Check Subagents And Leases
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+Claude Code subagent mode:
+- use automatically when this workflow runs in Claude Code and the parent agent chooses bounded subagent fan-out
+- dispatch read-only project subagents only: truth-route-auditor subagent, truth-claim-verifier subagent, truth-doc-reviewer subagent
+- subagents inspect checkout evidence directly, return structured findings, and must not edit files
+- parent supplies bounded evidence shards; subagents must not preload host instruction files or repo-wide policy docs unless assigned as evidence
+- Parent agent owns the final Truth Check report
@@ -1,66 +1,28 @@
 ---
 name: truthmark-document
-description: Use when the user explicitly asks to document existing implemented behavior, or when Truth Sync, Truth Check, or Truth Structure reports implemented behavior that lacks canonical truth docs. Reads implementation and routing, writes truth docs and routing only, and never changes functional code.
+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.2.3
 ---

 # Truthmark Document

 Use this skill to document existing implemented behavior when no functional-code changes are required for the task.
+
 Invocations: OpenCode /skill truthmark-document; Codex /truthmark-document or $truthmark-document; Claude Code /truthmark-document; GitHub Copilot /truthmark-document; Gemini CLI /truthmark:document.

-Truth Document is manual and implementation-first:
+Quick procedure:
+- 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/routes/areas.md; docs/truthmark/routes/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.
+- Read support/subagents-and-leases.md only when dispatching or accepting worker output.
+- Read support/report-template.md before the final report.

- 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.
-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
- must not write functional code
- when routing is missing, stale, broad, overloaded, catch-all, or cannot map the behavior to a bounded truth owner, run Truth Structure first when routing repair is safe and in scope
- block and recommend Truth Structure when routing repair is unsafe, ambiguous, or outside the task boundary
- keep feature README.md files as indexes rather than truth-document targets
- create or update bounded leaf truth docs when behavior does not fit an existing leaf doc
- keep feature docs behavior-oriented, not endpoint-oriented, unless the endpoint itself is the behavior boundary
- keep API endpoint details in the nearest contract truth doc when such a doc owns the API contract
- preserve unrelated authored content
-When creating or updating a feature doc, read docs/templates/feature-doc.md and follow its frontmatter, heading order, and section intent.
-When updating an existing feature doc, align existing feature docs to the template standard while preserving authored content that remains accurate.
-If docs/templates/feature-doc.md is missing, use the built-in minimal feature-doc structure with Current Behavior, Product Decisions, and Rationale sections.
-Teams may edit docs/templates/feature-doc.md to define their local feature-doc standard.
-Maintain architecture docs when a code change alters system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership.
-Do not put ordinary feature behavior, endpoint details, UI copy, validation rules, or bug fixes in architecture docs unless they change those architecture boundaries.
-Keep architecture docs focused on structure and ownership; keep current product behavior in feature or contract docs.
-Truthmark hierarchy:
- Config: .truthmark/config.yml
- Root route index: docs/truthmark/areas.md
- Area route files: docs/truthmark/areas/**/*.md
- Feature docs: docs/features/**/*.md
-Decision truth lives in the canonical doc it governs.
-Date active decisions inline when added or changed, for example `Decision (2026-05-09): ...`.
-Do not create separate timestamped ADR logs or planning tickets for active decisions.
-Replace old active decisions instead of appending separate timestamped decision logs; Git history is the audit trail.
-Update Product Decisions and Rationale when a behavior change comes from a decision change.
-
-Report completion in this shape:
-```md
-Truth Document: completed
-
-Implementation reviewed:
- src/api/orders/**
-
-Truth docs created:
- docs/features/orders/order-submission.md
-
-Truth docs updated:
- docs/features/contracts.md
-
-Routing updated:
- docs/truthmark/areas/orders.md
-
-Notes:
- Documented existing order submission behavior from route handlers and tests.
-```
+Progressive disclosure:
+- support/procedure.md — read before edits or detailed auditing; contains core review questions
+- support/report-template.md — read before the final report
+- support/subagents-and-leases.md — read only when using subagents, leases, or accepting worker output
+- helper-manifest.yml — read only when invoking helper validators or validating helper registration
+- support/helper-policy.md — read only when invoking helper validators or reporting helper status
@@ -0,0 +1,34 @@
+# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+helpers:
+  validate-document-report:
+    optional: true
+    runner: truthmark
+    command:
+      argv:
+        - truthmark
+        - validate
+        - document-report
+        - <report-file>
+        - --json
+    inputs:
+      - document report file
+    output: json
+    writes: false
+    fallback: manually validate support/report-template.md required sections and structured Evidence checked entries
+  validate-write-lease:
+    optional: true
+    runner: truthmark
+    command:
+      argv:
+        - truthmark
+        - validate
+        - write-lease
+        - <lease-or-report-file>
+        - <changed-files-file>
+        - --json
+    inputs:
+      - lease or worker report yaml
+      - changed file list
+    output: json
+    writes: false
+    fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files
@@ -0,0 +1,23 @@
+# Optional Helper CLI Policy
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+Optional helper CLI commands may collect deterministic checkout facts or validate artifacts. If the Truthmark CLI is unavailable or cannot return the declared helper output, 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.
+
+Runner detection:
+- Check that the declared Truthmark CLI runner is available before invoking a helper.
+- Invoke helpers through the installed `truthmark validate ... --json` CLI command using argv-style arguments from helper-manifest.yml.
+- If unavailable, failing, or returning incompatible output, treat the helper as skipped and use the manual fallback.
+- Do not fail the workflow solely because a helper cannot run.
+
+Available helpers:
+- validate-document-report: optional truthmark; manual fallback: manually validate support/report-template.md required sections and structured Evidence checked entries
+- validate-write-lease: optional truthmark; 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:
+
+```md
+Helper scripts:
+- validate-document-report: ran, passed
+- validate-write-lease: skipped, no write lease used
+```
@@ -0,0 +1,92 @@
+# Truthmark Document Procedure
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+# Truthmark Document
+
+Use this skill to document existing implemented behavior when no functional-code changes are required for the task.
+Invocations: OpenCode /skill truthmark-document; Codex /truthmark-document or $truthmark-document; Claude Code /truthmark-document; GitHub Copilot /truthmark-document; Gemini CLI /truthmark:document.
+
+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 and configured route files only when they exist; then inspect existing canonical docs, implementation code, and tests directly
+- Evidence 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.
+- Lane classification:
+  - before writing canonical truth docs, classify the request or change as product-lane, engineering-lane, both-lane, or ambiguous
+  - product-lane writes belong under docs/truthmark/product and state product promises, boundaries, rationale, decisions, and success criteria
+  - engineering-lane writes belong under docs/truthmark/engineering and state source-backed current realization, contracts, architecture, workflows, operations, or tests
+  - both-lane work must write separate product and engineering docs and cross-link them in route YAML with realized_by and realizes, not in doc frontmatter
+  - ambiguous lane ownership must stop or invoke Truth Structure instead of writing a mixed document
+  - Do not make product docs a summary of engineering docs. Do not make engineering docs a detailed version of product docs. Product truth says what must be true and why. Engineering truth says how the repository currently realizes it.
+- document current implemented behavior; do not invent future behavior or planned endpoints
+- may write canonical truth docs and docs/truthmark/routes/areas.md or relevant child route files only
+- must not write functional code
+- when routing is missing, stale, broad, overloaded, catch-all, or cannot map the behavior to a bounded truth owner, run Truth Structure first when routing repair is safe and in scope
+- stop and recommend Truth Structure when routing repair is unsafe, ambiguous, or outside the task boundary
+- keep feature README.md files as indexes rather than truth-document targets
+- create or update bounded leaf truth docs when behavior does not fit an existing leaf doc
+- write product capability/boundary truth under docs/truthmark/product when documenting product promise, boundary, rationale, or user/stakeholder value
+- write engineering truth under docs/truthmark/engineering when documenting implementation behavior, contracts, architecture, workflows, operations, or tests
+- for both-lane documentation requests, write separate product and engineering docs and cross-link them in route YAML with realized_by and realizes, not in doc frontmatter
+- keep engineering behavior truth behavior-oriented, not endpoint-oriented, unless the endpoint itself is the behavior boundary
+- keep API endpoint details in the nearest contract truth doc when such a doc owns the API contract
+- preserve unrelated authored content
+Truth-doc ownership review:
+- before editing or relying on the implemented behavior and candidate truth docs, verify each target/source truth doc is a bounded owner for the behavior
+- if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it
+- if the target doc is broad, mixed-owner, index-like, or the documented behavior spans independent owners, run Truth Structure first when safe and in scope; otherwise stop and recommend Truth Structure
+- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Manual handoff reason as applicable
+Decision/Rationale preservation review:
+- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions, Engineering Decisions, and Rationale sections in every source or touched truth doc
+- preserve each current decision and rationale in the correct product or engineering lane owner; when splitting, move it to the new owner doc rather than deleting it or leaving it in an index
+- remove or narrow a decision or rationale only when checkout evidence shows it is stale or unsupported, and report the exact claim, evidence, and result
+- if ownership of a decision or rationale is unclear, stop with manual-review files instead of deleting it or guessing
+- after the edit, verify every touched truth doc keeps lane-appropriate decision/rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked
+Evidence checklist:
+- route-first: map the documented behavior to bounded route owners and primary canonical docs
+- review new or changed behavior-bearing claims only in touched docs, route ownership, lane-specific decisions, and rationale
+- support claims with primary checkout evidence: implementation, config, routing, generated templates, schemas, or contract definitions
+- tests/examples/canonical docs corroborate; they are not sole proof when implementation conflicts
+- remove, narrow, or record unsupported claims for manual handoff
+- 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 WorkflowState/action context may guide routing, write boundaries, and verification planning when available.
+They do not override checkout evidence, canonical truth docs, route files, or workflow write boundaries.
+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 template under the configured Truthmark templates root.
+Supported kinds: product-capability, engineering-behavior, engineering-contract, engineering-architecture, engineering-workflow, engineering-operations, and engineering-test-behavior.
+Treat the HTML comments under each template section as normative authoring guidance for that section.
+Align existing docs to that template and write or repair section content so it satisfies the comment guidance while preserving accurate authored content.
+If the template is missing, use lane-specific sections: product truth says what must be true and why; engineering truth says how the repository currently realizes it.
+Teams may edit template files under the configured Truthmark templates root to define their local truth-doc standards.
+Truth-doc shape repair review:
+- Truth Document may restructure only truth docs for the implemented behavior being documented.
+- repair shape in place only after the ownership review confirms the doc is the right bounded owner
+- use Truth Structure for ownership splits; do not treat broad or mixed-owner docs as in-place repair work
+- repair shape when a narrow edit would make truth worse: missing template sections, stale evidence conflicts, cross-section updates within one owner, or wrong frontmatter/source/headings
+- preserve supported claims; remove, narrow, or record unsupported or stale claims for manual handoff
+- 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 hints:
+- Config, when present: .truthmark/config.yml
+- Root route index, when present: docs/truthmark/routes/areas.md
+- Area route files, when present: docs/truthmark/routes/areas/**/*.md
+- Product truth docs, when present: docs/truthmark/product/**/*.md
+- Engineering truth docs, when present: docs/truthmark/engineering/**/*.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.
+Product decisions belong in product truth; engineering, architecture, contract, workflow, and operational decisions belong in engineering truth.
+Helper status reporting:
+- Validate the report body before adding this validator's own success status; the body may omit `validate-document-report` while validation is pending.
+- After `truthmark validate document-report <report-file> --json` returns `data.validation.ok: true`, append or update `validate-document-report: ran, passed` in the final report.
+- If the installed Truthmark CLI is unavailable or the helper is skipped, record `validate-document-report: skipped, <reason>` 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.
+Parent post-document verification:
+- verify only truth docs and leased truth routing files changed during document work
+- stop on functional code, generated host surfaces, or unrelated diffs caused by document work
+- for each write lease, validate the worker report against the actual worker diff, allowedWrites, forbiddenWrites, identity fields, filesChanged, offLeaseChanges, blockers, and expected report fields before accepting it
+- verify the final report records ownership review, structure requirement, restructure, routing update, or manual handoff reason when applicable
@@ -0,0 +1,37 @@
+# Truthmark Document Report Template
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+Report completion in this shape:
+```md
+Truth Document: completed
+
+Implementation reviewed:
+- src/routing/area-resolver.ts
+
+Ownership reviewed:
+- docs/truthmark/routes/areas.md
+
+Truth docs created:
+- docs/truthmark/engineering/contracts/routing.md
+
+Truth docs updated:
+- docs/truthmark/engineering/behaviors/check-diagnostics.md
+
+Truth docs restructured:
+- docs/truthmark/engineering/behaviors/check-diagnostics.md
+
+Routing updated:
+- docs/truthmark/routes/areas.md
+
+Evidence checked:
+- Claim: Route resolution behavior is documented in the contracts truth doc.
+  Evidence: src/routing/area-resolver.ts:14 / docs/truthmark/routes/areas.md:9
+  Result: supported
+
+Helper scripts:
+- validate-write-lease: skipped, no write lease used
+
+Notes:
+- Documented routing and behavior from route handlers and tests.
+```
@@ -0,0 +1,14 @@
+# Truthmark Document Subagents And Leases
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+Claude Code subagent mode:
+- use automatically when this workflow runs in Claude Code and the parent agent chooses bounded subagent fan-out
+- dispatch read-only project subagents for verification: truth-route-auditor subagent, truth-claim-verifier subagent
+- read-only subagents inspect checkout evidence directly, return structured findings, and must not edit files
+- parent supplies bounded evidence shards; read-only subagents must not preload host instruction files or repo-wide policy docs unless assigned as evidence
+- dispatch write-capable project subagents only with explicit write leases: truth-doc-writer subagent
+- each write lease must name objective, required reads, allowed writes, forbidden writes, evidence, verification, and report fields
+- write workers must stop when a required edit is off-lease and report status, filesChanged, evidence, offLeaseChanges, blockers, and notes
+- parent must inspect the actual checkout diff against each lease before accepting a worker report
+- Parent agent owns Truth Document acceptance, lease validation, and final report
@@ -0,0 +1,25 @@
+---
+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 Preview
+
+Use this skill only when the user explicitly asks to preview Truthmark routing or workflow choice before edits.
+
+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 repository instruction files that exist in this checkout; do not assume any optional policy path exists.
+- Inspect .truthmark/config.yml and the root route index (docs/truthmark/routes/areas.md) first when present; then inspect only child route files under docs/truthmark/routes/areas/ that are relevant to the selected scope or changed paths, plus 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.
+- Hand off to the selected workflow after user approval.
+
+Progressive disclosure:
+- support/procedure.md — read before edits or detailed auditing; contains core review questions
+- support/report-template.md — read before the final report
+- support/subagents-and-leases.md — read only when using subagents, leases, or accepting worker output
@@ -0,0 +1,53 @@
+# Truthmark Preview Procedure
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+Use this skill only when the user explicitly asks to preview Truthmark routing or workflow choice before edits.
+
+Invocations: OpenCode /skill truthmark-preview; Codex /truthmark-preview or $truthmark-preview; Claude Code /truthmark-preview; GitHub Copilot /truthmark-preview; Gemini CLI /truthmark:preview.
+
+Truth Preview is read-only. Its report is intended, not authorized.
+
+Purpose:
+- preview the likely Truthmark workflow, route owner, target files, expected write classes, suggested subagent use, and manual handoff questions before edits happen
+- report likely product lane impact, engineering lane impact, target docs, and ambiguity before edits
+- hand off to the selected workflow after user approval
+- keep the selector thin so agents can avoid loading or acting through heavier workflows prematurely
+
+Read:
+- .truthmark/config.yml, only when present
+- docs/truthmark/routes/areas.md, first, only when present
+- relevant child route files under docs/truthmark/routes/areas/ for the selected scope or changed paths, only when present
+- relevant truth docs and implementation files needed to preview ownership
+- Evidence 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.
+- Lane classification:
+  - classify the request or changed surface as product-lane, engineering-lane, both-lane, or ambiguous for reporting only
+  - product-lane ownership belongs under docs/truthmark/product and describes product promises, boundaries, rationale, decisions, and success criteria
+  - engineering-lane ownership belongs under docs/truthmark/engineering and describes source-backed current realization, contracts, architecture, workflows, operations, or tests
+  - both-lane ownership uses separate product and engineering docs cross-linked in route YAML with realized_by and realizes, not in doc frontmatter
+  - ambiguous lane ownership should be reported for manual handoff or routed to Truth Structure
+  - Do not make product docs a summary of engineering docs. Do not make engineering docs a detailed version of product docs. Product truth says what must be true and why. Engineering truth says how the repository currently realizes it.
+
+Do not:
+- must not edit files
+- must not create truth docs
+- must not update routing
+- must not run Truth Sync automatically
+- must not replace Truth Check
+- must not claim final correctness
+- must not issue write leases
+- must not mutate code
+
+Suggested subagent use:
+- optional read-only verifier: truth_route_auditor
+- write workers: none
+- leases needed: none
+
+Truthmark hierarchy hints:
+- Config, when present: .truthmark/config.yml
+- Root route index, when present: docs/truthmark/routes/areas.md
+- Area route files, when present: docs/truthmark/routes/areas/**/*.md
+- Product truth docs, when present: docs/truthmark/product/**/*.md
+- Engineering truth docs, when present: docs/truthmark/engineering/**/*.md
@@ -0,0 +1,43 @@
+# Truthmark Preview Report Template
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+Report completion in this shape:
+```md
+Truth Preview: completed
+
+Requested outcome:
+- preview likely Truthmark workflow routing before edits
+
+Likely workflow:
+- truthmark-document
+
+Why this workflow:
+- positive trigger: document existing implemented behavior
+- negative triggers considered: functional-code change, doc-first implementation, topology repair, truth audit
+- forbidden adjacency considered: must not edit functional code
+
+Likely route owner:
+- route file: docs/truthmark/routes/areas.md
+- likely lane impact: engineering-lane
+- product target docs: none identified
+- engineering target docs: docs/truthmark/engineering/behaviors/example.md
+- confidence: medium
+
+Expected write classes:
+- truth docs
+
+Expected target files:
+- docs/truthmark/engineering/behaviors/example.md
+
+Suggested subagent use:
+- read-only verifiers: truth_route_auditor
+- write workers: none in Preview
+- leases needed: none in Preview
+
+Manual handoff questions:
+- none identified in preview
+
+Handoff:
+- Run the selected Truthmark workflow after user approval.
+```
@@ -0,0 +1,10 @@
+# Truthmark Preview Subagents And Leases
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+Claude Code subagent mode:
+- use automatically when this workflow runs in Claude Code and the parent agent chooses bounded subagent fan-out
+- dispatch read-only project subagents only: truth-route-auditor subagent
+- subagents inspect checkout evidence directly, return structured findings, and must not edit files
+- parent supplies bounded evidence shards; subagents must not preload host instruction files or repo-wide policy docs unless assigned as evidence
+- Parent agent owns the final Truth Preview report
@@ -1,9 +1,8 @@
 ---
 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. Reads truth docs and routing first, updates functional code only, and reports verification.
+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.2.3
 ---

 # Truthmark Realize
@@ -12,40 +11,14 @@ 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.

-Truth Realize is doc-first:
+Quick procedure:
+- 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/routes/areas.md; docs/truthmark/routes/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.
+- Read support/report-template.md before the final report.

- truth docs lead
- code follows
- Truth Realize never edits the truth docs it is realizing
-
-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, and the relevant functional code.
-3. Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority.
-Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries.
-4. Update functional code only so implementation matches the truth docs.
-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.
-
-Read and write boundaries:
-
- may read truth docs, routing docs, and relevant functional code
- may write functional code only
- must not edit truth docs or truth routing while realizing those docs
-
-Report completion in this shape:
-
-```md
-Truth Realize: completed
-
-Truth docs used:
- docs/features/authentication.md
-
-Code updated:
- src/auth/session.ts
-
-Verification:
- npm test -- auth
-```
+Progressive disclosure:
+- support/procedure.md — read before edits or detailed auditing; contains core review questions
+- support/report-template.md — read before the final report
@@ -0,0 +1,43 @@
+# Truthmark Realize Procedure
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+# Truthmark Realize
+
+Use this skill only when the user explicitly asks to realize truth docs into code.
+
+Invocations: OpenCode /skill truthmark-realize; Codex /truthmark-realize or $truthmark-realize; Claude Code /truthmark-realize; GitHub Copilot /truthmark-realize; Gemini CLI /truthmark:realize.
+
+Truth Realize is doc-first:
+
+- truth docs lead
+- code follows
+- Truth Realize never edits the truth docs it is realizing
+
+Workflow:
+
+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/routes/areas.md; docs/truthmark/routes/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 review:
+- before editing or relying on source truth docs before writing code, verify each target/source truth doc is a bounded owner for the behavior
+- if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it
+- if a source truth doc is broad, mixed-owner, index-like, unrouteable, stale, or conflicts with implementation evidence, stop before writing code and recommend Truth Structure or Truth Document
+- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Manual handoff reason as applicable
+4. Update functional code only so implementation matches bounded, current truth claims from the source docs.
+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 hints:
+- Config, when present: .truthmark/config.yml
+- Root route index, when present: docs/truthmark/routes/areas.md
+- Area route files, when present: docs/truthmark/routes/areas/**/*.md
+- Product truth docs, when present: docs/truthmark/product/**/*.md
+- Engineering truth docs, when present: docs/truthmark/engineering/**/*.md
+
+Read and write boundaries:
+
+- may read truth docs, routing docs, and relevant functional code
+- may write functional code only
+- must not edit truth docs or truth routing while realizing those docs
@@ -0,0 +1,19 @@
+# Truthmark Realize Report Template
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+Report completion in this shape:
+
+```md
+Truth Realize: completed
+
+Truth docs used:
+- docs/truthmark/product/capabilities/authentication-session.md
+- docs/truthmark/engineering/behaviors/authentication-session.md
+
+Code updated:
+- src/auth/session.ts
+
+Verification:
+- npm test -- auth
+```
@@ -1,93 +1,25 @@
 ---
 name: truthmark-structure
-description: Use when the user asks to design, repair, or refresh missing, stale, broad, overloaded, catch-all, or unrouteable Truthmark area routing. Inspects the repository directly, updates docs/truthmark/areas.md, and may create starter canonical truth docs.
+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.2.3
 ---

+# Truthmark Structure
+
 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.
-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/
- 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
- Starter truth docs must use closed YAML frontmatter bounded by opening and closing --- lines; include status, doc_type, last_reviewed, and source_of_truth inside that frontmatter.
- Starter truth docs must include ## Product Decisions and ## Rationale sections.
-When creating or updating a feature doc, read docs/templates/feature-doc.md and follow its frontmatter, heading order, and section intent.
-When updating an existing feature doc, align existing feature docs to the template standard while preserving authored content that remains accurate.
-If docs/templates/feature-doc.md is missing, use the built-in minimal feature-doc structure with Current Behavior, Product Decisions, and Rationale sections.
-Teams may edit docs/templates/feature-doc.md to define their local feature-doc standard.
- use docs/features/**, docs/architecture/**, or docs/standards/** for current truth destinations
- use only canonical current-truth destinations for starter truth docs
- keep active Product Decisions and Rationale in the canonical doc that owns the behavior
- preserve unrelated authored content
-## Topology Governance
-Truth Structure owns documentation topology. Do not depend on humans to manually organize docs/features. Treat the configured feature root as a managed semantic root.
-Inspect controllers, routes, handlers, services, packages, tests, existing truth docs, and route files; infer product and domain ownership from behavior boundaries, not from mechanical directory mirroring.
-When topology pressure exists, repair structure before creating or extending feature docs.
-Topology pressure signals:
- one area maps broad code such as src/**, app/**, server/**, services/**, or packages/**
- one area maps multiple unrelated controllers, route groups, services, or bounded contexts
- one truth doc owns unrelated behaviors or unrelated endpoint families
- the configured feature root has many direct non-index docs
- a changed controller, route, or service cannot map to a specific behavior doc
- Truth Sync would need to create a new generic feature doc because routing is too broad
- endpoint or controller names reveal domains missing from docs/truthmark/areas/**
-Use these review thresholds as guidance:
- more than 10 direct feature docs in one folder
- more than 15 leaf areas in one child route file
- more than 8 truth docs mapped to one area
- more than 5 controllers mapped through one catch-all area
-Repair rules:
- split broad, overloaded, or catch-all areas into behavior-owned child route files
- create route files under docs/truthmark/areas/ when a product/domain boundary is clear
- create feature docs under the configured feature root only when behavior lacks a current doc
- README.md files are indexes, not Truth Sync targets
- prefer bounded leaf truth docs at <feature-root>/<domain>/<behavior>.md
- keep feature docs behavior-oriented, not endpoint-oriented
- keep API endpoint details in the nearest contract truth doc when such a doc exists
- update routing so future Truth Sync can target small docs
- preserve existing authored docs; move or rewrite only when needed to remove ambiguity
-Maintain architecture docs when a code change alters system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership.
-Do not put ordinary feature behavior, endpoint details, UI copy, validation rules, or bug fixes in architecture docs unless they change those architecture boundaries.
-Keep architecture docs focused on structure and ownership; keep current product behavior in feature or contract docs.
- Do not finish topology repair with routed canonical current-truth docs missing Product Decisions or Rationale sections.
- If an existing canonical doc lacks either section, add the missing heading beside Current Behavior with a concise current-state placeholder or active decision.
-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.
- 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
- Feature docs: docs/features/**/*.md
-Decision truth lives in the canonical doc it governs.
-Date active decisions inline when added or changed, for example `Decision (2026-05-09): ...`.
-Do not create separate timestamped ADR logs or planning tickets for active decisions.
-Replace old active decisions instead of appending separate timestamped decision logs; Git history is the audit trail.
-Update Product Decisions and Rationale when a behavior change comes from a decision change.
-Report completion in this shape:
-```md
-Truth Structure: completed
-Topology reviewed:
- controllers: src/auth/**
- docs root: docs/features
- route files: docs/truthmark/areas.md
-Areas reviewed:
- src/auth/**
-Routing updated:
- docs/truthmark/areas.md
-Truth docs created:
- docs/features/authentication.md
-Topology decisions:
- Added an Authentication area because session behavior has a distinct code surface and truth owner.
-Notes:
- Added an Authentication area for session behavior.
-```
+
+Quick procedure:
+- 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/routes/areas.md; docs/truthmark/routes/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.
+- Read support/report-template.md before the final report.
+
+Progressive disclosure:
+- support/procedure.md — read before edits or detailed auditing; contains core review questions
+- support/report-template.md — read before the final report
+- support/subagents-and-leases.md — read only when using subagents, leases, or accepting worker output
@@ -0,0 +1,121 @@
+# Truthmark Structure Procedure
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+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 and route files when present, and relevant code directly
+- Evidence 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.
+- Lane classification:
+  - before writing canonical truth docs, classify the request or change as product-lane, engineering-lane, both-lane, or ambiguous
+  - product-lane writes belong under docs/truthmark/product and state product promises, boundaries, rationale, decisions, and success criteria
+  - engineering-lane writes belong under docs/truthmark/engineering and state source-backed current realization, contracts, architecture, workflows, operations, or tests
+  - both-lane work must write separate product and engineering docs and cross-link them in route YAML with realized_by and realizes, not in doc frontmatter
+  - ambiguous lane ownership must stop or invoke Truth Structure instead of writing a mixed document
+  - Do not make product docs a summary of engineering docs. Do not make engineering docs a detailed version of product docs. Product truth says what must be true and why. Engineering truth says how the repository currently realizes it.
+- inspect the configured root route index at docs/truthmark/routes/areas.md and relevant child route files under docs/truthmark/routes/areas/ when they exist
+- define areas by product or behavior ownership, not by mechanical directory mirroring
+- create or repair docs/truthmark/routes/areas.md
+- create starter truth docs when useful and when they belong in the canonical current-truth surface
+- Starter truth docs must use closed YAML frontmatter bounded by opening and closing --- lines; include status, truth_kind, and last_reviewed inside that frontmatter. Put source references in the final ## Source References section, not in frontmatter.
+- Starter truth docs must use lane-specific templates and keep product and engineering truth in separate files.
+
+When creating or updating a truth doc, inspect the routed truth kind and use the matching template under the configured Truthmark templates root.
+Supported kinds: product-capability, engineering-behavior, engineering-contract, engineering-architecture, engineering-workflow, engineering-operations, and engineering-test-behavior.
+Treat the HTML comments under each template section as normative authoring guidance for that section.
+Align existing docs to that template and write or repair section content so it satisfies the comment guidance while preserving accurate authored content.
+If the template is missing, use lane-specific sections: product truth says what must be true and why; engineering truth says how the repository currently realizes it.
+Teams may edit template files under the configured Truthmark templates root to define their local truth-doc standards.
+- use docs/truthmark/product/** for product truth destinations
+- use docs/truthmark/engineering/** for engineering truth destinations
+- use only canonical current-truth destinations for starter truth docs
+- keep active Product Decisions in product truth and Engineering Decisions in engineering truth
+- preserve unrelated authored content
+## New area setup
+Use when a user asks to onboard a new code area into Truthmark, a new package, controller, domain, or product area lacks bounded truth ownership, or a new product area needs routing and starter truth docs.
+Do:
+- inspect the named code area
+- infer bounded product or behavior ownership
+- choose the owning route when ownership is clear; otherwise propose the route and stop for manual review
+- create or update the child route entry or file
+- create starter truth docs only where current truth is missing
+- report the initial truth boundary
+Do not:
+- do not edit functional code
+- do not perform full behavior documentation unless evidence is inspected and the task explicitly asks for it
+- do not patch broad or mixed-owner docs in place
+- do not create generic catch-all docs
+- do not treat README files as Sync targets
+## Topology Governance
+Truth Structure owns documentation topology, lane splits, decision relocation, and relationship repair. Do not depend on humans to manually organize docs/truthmark/product or docs/truthmark/engineering. Treat both configured lane roots as managed semantic roots.
+Inspect controllers, routes, handlers, services, packages, tests, existing truth docs, and route files; infer product and domain ownership from behavior boundaries, not from mechanical directory mirroring.
+When topology pressure exists, repair structure before creating or extending truth docs.
+Truth-doc ownership review:
+- before editing or relying on candidate route owners and current truth docs, verify each target/source truth doc is a bounded owner for the behavior
+- if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it
+- if a truth doc mixes independent owners, route ownership is broad, or a split is required for bounded ownership, split and reroute into bounded truth docs when safe; otherwise stop with manual-review files
+- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Manual handoff reason as applicable
+Decision/Rationale preservation review:
+- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions, Engineering Decisions, and Rationale sections in every source or touched truth doc
+- preserve each current decision and rationale in the correct product or engineering lane owner; when splitting, move it to the new owner doc rather than deleting it or leaving it in an index
+- remove or narrow a decision or rationale only when checkout evidence shows it is stale or unsupported, and report the exact claim, evidence, and result
+- if ownership of a decision or rationale is unclear, stop with manual-review files instead of deleting it or guessing
+- after the edit, verify every touched truth doc keeps lane-appropriate decision/rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked
+Topology pressure signals:
+- one area maps broad code such as src/**, app/**, server/**, services/**, or packages/**
+- one area maps multiple unrelated controllers, route groups, services, or bounded contexts
+- one truth doc owns unrelated behaviors or unrelated endpoint families
+- either configured lane root has many direct non-index docs
+- a changed controller, route, or service cannot map to a specific behavior doc
+- Truth Sync would need to create a new generic truth doc because routing is too broad
+- endpoint or controller names reveal domains missing from docs/truthmark/routes/areas/**
+Use these review thresholds as guidance:
+- more than 10 direct truth docs in one folder
+- more than 15 leaf areas in one child route file
+- more than 8 truth docs mapped to one area
+- more than 5 controllers mapped through one catch-all area
+Repair rules:
+- split broad, overloaded, or catch-all areas into behavior-owned child route files
+- split mixed-owner truth docs into bounded owner docs before adding new behavior claims
+- create route files under docs/truthmark/routes/areas/ when a product/domain boundary is clear
+- create engineering behavior truth docs under docs/truthmark/engineering only when behavior lacks a current doc
+- create product truth docs under docs/truthmark/product only when product promise, boundary, rationale, or user-visible capability truth is in scope
+- README.md files are indexes, not Truth Sync targets
+- prefer bounded product docs under product/capabilities or product/decisions and engineering docs under engineering/<kind>/<surface>.md
+- keep behavior truth docs behavior-oriented, not endpoint-oriented
+- keep API endpoint details in the nearest contract truth doc when such a doc exists
+- update routing so future Truth Sync can target small docs
+- preserve existing authored docs; move or rewrite only when needed to remove ambiguity
+- report Truth docs split when one broad or mixed-owner truth doc becomes multiple bounded docs
+Truth-doc shape repair review:
+- Truth Structure may restructure broader routed docs when topology, ownership, or doc-shape repair is already in scope.
+- repair shape in place only after the ownership review confirms the doc is the right bounded owner
+- use Truth Structure for ownership splits; do not treat broad or mixed-owner docs as in-place repair work
+- repair shape when a narrow edit would make truth worse: missing template sections, stale evidence conflicts, cross-section updates within one owner, or wrong frontmatter/source/headings
+- preserve supported claims; remove, narrow, or record unsupported or stale claims for manual handoff
+- report docs restructured and why a narrow edit was not sufficient
+Evidence checklist:
+- apply the evidence checklist before finishing when Truth Structure writes routed docs, ownership claims, lane-specific decisions, or rationale
+- support ownership/behavior claims with topology or primary checkout evidence from layout, implementation boundaries, docs, config, route files, tests, templates, schemas, or contracts
+- tests/examples/canonical docs corroborate; remove, narrow, or record unsupported claims for manual handoff
+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.
+- Do not finish topology repair with mixed product/engineering authority in a single canonical truth doc.
+- If an existing canonical doc has wrong-lane sections, split or move them into the correct product or engineering lane.
+Portable fallback:
+- If this skill surface is unavailable, perform the same workflow directly from committed repository files.
+- Do not require the truthmark CLI.
+- 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 hints:
+- Config, when present: .truthmark/config.yml
+- Root route index, when present: docs/truthmark/routes/areas.md
+- Area route files, when present: docs/truthmark/routes/areas/**/*.md
+- Product truth docs, when present: docs/truthmark/product/**/*.md
+- Engineering truth docs, when present: docs/truthmark/engineering/**/*.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.
+Product decisions belong in product truth; engineering, architecture, contract, workflow, and operational decisions belong in engineering truth.
@@ -0,0 +1,38 @@
+# Truthmark Structure Report Template
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+Report completion in this shape:
+```md
+Truth Structure: completed
+Topology reviewed:
+- controllers: src/auth/**
+- product docs root: docs/truthmark/product
+- engineering docs root: docs/truthmark/engineering
+- route files: docs/truthmark/routes/areas.md
+Areas reviewed:
+- src/auth/**
+Routing updated:
+- docs/truthmark/routes/areas.md
+Initial truth boundary:
+- Area: Authentication
+- Code: src/auth/**
+- Product owner: docs/truthmark/product/capabilities/authentication-session.md
+- Engineering owner: docs/truthmark/engineering/behaviors/authentication-session.md
+- Scope: session behavior only
+Truth docs created:
+- docs/truthmark/product/capabilities/authentication-session.md
+- docs/truthmark/engineering/behaviors/authentication-session.md
+Truth docs split:
+- docs/truthmark/truth/authentication/README.md -> docs/truthmark/product/capabilities/authentication-session.md and docs/truthmark/engineering/behaviors/authentication-session.md
+Truth docs restructured:
+- docs/truthmark/truth/authentication/README.md
+Evidence checked:
+- Claim: Session behavior belongs to a dedicated Authentication truth owner.
+  Evidence: src/auth/** / docs/truthmark/routes/areas.md:7
+  Result: supported
+Topology decisions:
+- Added an Authentication area because session behavior has a distinct code surface and truth owner.
+Notes:
+- Added an Authentication area for session behavior.
+```
@@ -0,0 +1,10 @@
+# Truthmark Structure Subagents And Leases
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+Claude Code subagent mode:
+- use automatically when this workflow runs in Claude Code and the parent agent chooses bounded subagent fan-out
+- dispatch read-only project subagents only: truth-route-auditor subagent
+- subagents inspect checkout evidence directly, return structured findings, and must not edit files
+- parent supplies bounded evidence shards; subagents must not preload host instruction files or repo-wide policy docs unless assigned as evidence
+- Parent agent owns all Truth Structure writes and final topology decisions
@@ -1,100 +1,29 @@
 ---
 name: truthmark-sync
-description: Use automatically before finishing when functional code changed since the last successful Truth Sync, and when the user explicitly invokes /truthmark-sync, $truthmark-sync, or /truthmark:sync. Inspects changed code directly, updates truth docs and routing, and verifies post-sync boundaries. Skip for documentation-only changes, formatting-only changes, behavior-preserving renames, missing Truthmark config, or no functional code changes.
+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.2.3
 ---

+# Truthmark Sync
+
 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.
-Explicit invocation runs immediately. Later functional-code changes reopen the finish-time requirement, and an earlier explicit run satisfies the finish gate only if no later functional-code changes occur.
-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.
-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.
-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 one bounded Truth Sync worker only when the host supports subagent dispatch and the acting agent chooses that path; otherwise execute the same sync task inline.
-Topology quality gate:
- before updating truth docs, verify the changed code resolves to a specific behavior-owned area and bounded truth owner
- if routing is missing, stale, broad, overloaded, catch-all route only, or cannot map changed code to a bounded truth owner, do not create another generic feature doc
- run Truth Structure before syncing when topology repair is safe and in scope
- block and recommend Truth Structure when topology repair is unsafe, ambiguous, or outside the current task boundary
- report the route files and changed code paths that require structure repair
- README.md files are indexes, not Truth Sync targets
- must not append behavior details to a feature README
- create or update a bounded leaf truth doc when behavior changes do not fit an existing leaf doc
-When creating or updating a feature doc, read docs/templates/feature-doc.md and follow its frontmatter, heading order, and section intent.
-When updating an existing feature doc, align existing feature docs to the template standard while preserving authored content that remains accurate.
-If docs/templates/feature-doc.md is missing, use the built-in minimal feature-doc structure with Current Behavior, Product Decisions, and Rationale sections.
-Teams may edit docs/templates/feature-doc.md to define their local feature-doc standard.
-Maintain architecture docs when a code change alters system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership.
-Do not put ordinary feature behavior, endpoint details, UI copy, validation rules, or bug fixes in architecture docs unless they change those architecture boundaries.
-Keep architecture docs focused on structure and ownership; keep current product behavior in feature or contract docs.
-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
- optional validation must not replace agent judgment about docs and routing
- update Product Decisions and Rationale when a behavior change comes from a decision change
-Truthmark hierarchy:
- Config: .truthmark/config.yml
- Root route index: docs/truthmark/areas.md
- Area route files: docs/truthmark/areas/**/*.md
- Feature docs: docs/features/**/*.md
-Decision truth lives in the canonical doc it governs.
-Date active decisions inline when added or changed, for example `Decision (2026-05-09): ...`.
-Do not create separate timestamped ADR logs or planning tickets for active decisions.
-Replace old active decisions instead of appending separate timestamped decision logs; Git history is the audit trail.
-Update Product Decisions and Rationale when a behavior change comes from a decision change.
-### Truth Sync Worker
-The parent provides the task focus and any repository context already gathered.
-Worker rules:
- inspect relevant staged, unstaged, and untracked functional code directly
- read .truthmark/config.yml, docs/truthmark/areas.md, and canonical truth docs directly
- Code verification is parent-owned; report what was run or why it was not run
- may write truth docs and docs/truthmark/areas.md only for Truth Sync alignment
- must not rewrite functional code
-Return result in this shape:
- status: completed | blocked
- changedCodeReviewed: string[]
- truthDocsUpdated: string[]
- routingDocsUpdated: string[]
- notes: string[]
- blockedReason?: string
- manualReviewFiles?: string[]
-Parent post-sync verification:
- verify only truth docs and docs/truthmark/areas.md changed during sync
- block on any unrelated diff caused by the sync step
- block if functional code changed during sync
- verify the worker report matches the required headings and sections
- verify the updated docs correspond to the reviewed changed-code surface
- blocked outcomes must preserve the working tree as-is: no rollback, no post-block cleanup edits, and manual-review reporting of any remaining files
-Report completion in this shape:
-```md
-Truth Sync: completed

-Changed code reviewed:
- src/auth/session.ts
+Quick procedure:
+- 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.
+- Inspect .truthmark/config.yml and configured route files (docs/truthmark/routes/areas.md; docs/truthmark/routes/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.
+- Read support/subagents-and-leases.md only when dispatching or accepting worker output.
+- Read support/report-template.md before the final report.

-Truth docs updated:
- docs/features/repository/overview.md
-
-Notes:
- Updated session timeout behavior.
-```
-Blocked report example:
-```md
-Truth Sync: blocked
-
-Reason:
- routing repair is not allowed
-
-Files requiring manual review:
- docs/truthmark/areas.md
-
-Next action:
- update routing metadata and rerun Truth Sync
-```
+Progressive disclosure:
+- support/procedure.md — read before edits or detailed auditing; contains core review questions
+- support/report-template.md — read before the final report
+- support/subagents-and-leases.md — read only when using subagents, leases, or accepting worker output
+- helper-manifest.yml — read only when invoking helper validators or validating helper registration
+- support/helper-policy.md — read only when invoking helper validators or reporting helper status
@@ -0,0 +1,34 @@
+# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+helpers:
+  validate-sync-report:
+    optional: true
+    runner: truthmark
+    command:
+      argv:
+        - truthmark
+        - validate
+        - sync-report
+        - <report-file>
+        - --json
+    inputs:
+      - sync report file
+    output: json
+    writes: false
+    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
+    command:
+      argv:
+        - truthmark
+        - validate
+        - write-lease
+        - <lease-or-report-file>
+        - <changed-files-file>
+        - --json
+    inputs:
+      - lease or worker report yaml
+      - changed file list
+    output: json
+    writes: false
+    fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files
@@ -0,0 +1,23 @@
+# Optional Helper CLI Policy
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+Optional helper CLI commands may collect deterministic checkout facts or validate artifacts. If the Truthmark CLI is unavailable or cannot return the declared helper output, 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.
+
+Runner detection:
+- Check that the declared Truthmark CLI runner is available before invoking a helper.
+- Invoke helpers through the installed `truthmark validate ... --json` CLI command using argv-style arguments from helper-manifest.yml.
+- If unavailable, failing, or returning incompatible output, treat the helper as skipped and use the manual fallback.
+- Do not fail the workflow solely because a helper cannot run.
+
+Available helpers:
+- validate-sync-report: optional truthmark; 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; 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:
+
+```md
+Helper scripts:
+- validate-sync-report: ran, passed
+- validate-write-lease: skipped, no write lease used
+```
@@ -0,0 +1,110 @@
+# Truthmark Sync Procedure
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+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.
+Explicit invocation runs immediately. Later functional-code changes need a fresh finish-time review, and an earlier explicit run satisfies the finish-time review only if no later functional-code changes occur.
+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. 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:
+  - 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. Product truth decision:
+  - ask whether a user-visible promise, capability boundary, API contract, acceptance criterion, or explicit user/product evidence changed
+  - if yes, update or route product truth under docs/truthmark/product as well as engineering truth under docs/truthmark/engineering
+  - if no, default to engineering truth under docs/truthmark/engineering for internal implementation changes
+  - when both lanes change, keep separate product and engineering docs cross-linked through route YAML with realized_by and realizes
+  - when ownership is ambiguous, stop or route to Truth Structure instead of writing a mixed document
+6. Capture decision context from the task conversation: ask whether the user provided a product or technical decision, rationale, constraint, tradeoff, rejection reason, or scope boundary. Preserve concise user-provided decision rationale in Sync Intent before truth edits, route it to Product Decisions, Engineering Decisions, Rationale, Capability Scope, Non-Goals, Maintenance Notes, or the relevant workflow/contract section, and report whether it was placed, skipped because none was provided, or needs manual handoff.
+7. Update engineering truth first after code changes. Product truth is opt-in for externally visible promises, product boundaries, APIs, acceptance criteria, or explicit user/product evidence.
+8. Code verification is parent-owned: follow repository instructions and task context, and report what ran or why it did not run.
+9. 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.
+10. Fill Sync Intent before editing truth docs or truth routing files:
+   - Changed code reviewed: functional files, tests, configs, generated outputs, or other implementation evidence inspected
+   - Affected route/truth owner: bounded route area or canonical truth owner that maps the change
+   - Target truth docs: docs expected to change, or docs reviewed and left unchanged
+   - Intended update: claim/doc/routing update planned before writing
+   - Evidence to verify: checkout evidence that will support, narrow, remove, or record each claim for manual handoff
+   - User-provided decisions/rationale: decisions, rationale, constraints, tradeoffs, rejection reasons, or scope boundaries from the current task conversation, or "none provided"
+   - No-update-needed rationale: why mapped truth is already current when no truth doc should change
+   - Blockers: missing routing, ambiguous ownership, failed verification, unavailable evidence, or off-boundary write needs
+11. Only edit allowed truth docs/routes after Sync Intent is clear; if ownership is ambiguous, stop and recommend Truth Structure instead of guessing.
+Topology review:
+- before updating truth docs, verify the changed code resolves to a specific behavior-owned area and bounded truth owner
+- if routing is missing, stale, broad, overloaded, catch-all route only, or cannot map changed code to a bounded truth owner, do not create another generic truth doc
+- run Truth Structure before syncing when topology repair is safe and in scope
+- stop and recommend Truth Structure when topology repair is unsafe, ambiguous, or outside the current task boundary
+- report the route files and changed code paths that require structure repair
+- README.md files are indexes, not Truth Sync targets
+- must not append behavior details to a README.md index
+- create or update a bounded leaf truth doc when behavior changes do not fit an existing leaf doc
+- write engineering truth under docs/truthmark/engineering; product truth updates under docs/truthmark/product are allowed only for explicit current product behavior changes
+Truth-doc ownership review:
+- before editing or relying on changed functional files and impacted truth docs, verify each target/source truth doc is a bounded owner for the behavior
+- if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it
+- if an impacted doc is broad, mixed-owner, index-like, or the update spans independent behavior owners, run Truth Structure before syncing when safe and in scope; otherwise stop and recommend Truth Structure
+- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Manual handoff reason as applicable
+Decision/Rationale preservation review:
+- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions, Engineering Decisions, and Rationale sections in every source or touched truth doc
+- preserve each current decision and rationale in the correct product or engineering lane owner; when splitting, move it to the new owner doc rather than deleting it or leaving it in an index
+- remove or narrow a decision or rationale only when checkout evidence shows it is stale or unsupported, and report the exact claim, evidence, and result
+- if ownership of a decision or rationale is unclear, stop with manual-review files instead of deleting it or guessing
+- after the edit, verify every touched truth doc keeps lane-appropriate decision/rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked
+When creating or updating a truth doc, inspect the routed truth kind and use the matching template under the configured Truthmark templates root.
+Supported kinds: product-capability, engineering-behavior, engineering-contract, engineering-architecture, engineering-workflow, engineering-operations, and engineering-test-behavior.
+Treat the HTML comments under each template section as normative authoring guidance for that section.
+Align existing docs to that template and write or repair section content so it satisfies the comment guidance while preserving accurate authored content.
+If the template is missing, use lane-specific sections: product truth says what must be true and why; engineering truth says how the repository currently realizes it.
+Teams may edit template files under the configured Truthmark templates root to define their local truth-doc standards.
+Truth-doc shape repair review:
+- Truth Sync may restructure leased canonical truth docs when the current sync evidence shows repository truth is stale, even when the doc is outside the initially affected route focus.
+- repair shape in place only after the ownership review confirms the doc is the right bounded owner
+- use Truth Structure for ownership splits; do not treat broad or mixed-owner docs as in-place repair work
+- repair shape when a narrow edit would make truth worse: missing template sections, stale evidence conflicts, cross-section updates within one owner, or wrong frontmatter/source/headings
+- preserve supported claims; remove, narrow, or record unsupported or stale claims for manual handoff
+- 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.
+Evidence checklist:
+- route-first: map changed functional files to bounded route owners and primary canonical docs
+- review new or changed behavior-bearing claims only in touched docs, route ownership, lane-specific decisions, and rationale
+- support claims with primary checkout evidence: implementation, config, routing, generated templates, schemas, or contract definitions
+- tests/examples/canonical docs corroborate; they are not sole proof when implementation conflicts
+- remove, narrow, or record unsupported claims for manual handoff
+- 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 WorkflowState/action context may guide routing, write boundaries, and verification planning when available.
+They do not override checkout evidence, canonical truth docs, route files, or workflow write boundaries.
+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
+- optional validation must not replace agent judgment about docs and routing
+- update Product Decisions only in product truth and Engineering Decisions only in engineering truth when evidence supports the lane-specific decision change
+Helper status reporting:
+- Validate the report body before adding this validator's own success status; the body may omit `validate-sync-report` while validation is pending.
+- After `truthmark validate sync-report <report-file> --json` returns `data.validation.ok: true`, append or update `validate-sync-report: ran, passed` in the final report.
+- If the installed Truthmark CLI is unavailable or the helper is skipped, record `validate-sync-report: skipped, <reason>` 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 hints:
+- Config, when present: .truthmark/config.yml
+- Root route index, when present: docs/truthmark/routes/areas.md
+- Area route files, when present: docs/truthmark/routes/areas/**/*.md
+- Product truth docs, when present: docs/truthmark/product/**/*.md
+- Engineering truth docs, when present: docs/truthmark/engineering/**/*.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.
+Product decisions belong in product truth; engineering, architecture, contract, workflow, and operational decisions belong in engineering truth.
+Parent post-sync verification:
+- verify only truth docs and leased truth routing files changed during sync
+- stop on any unrelated diff caused by the sync step
+- stop if functional code changed during sync
+- for each write lease, validate the worker report against the actual worker diff, allowedWrites, forbiddenWrites, identity fields, filesChanged, offLeaseChanges, blockers, and expected report fields before accepting it
+- validate the final report against the structured Truth Sync report contract, including Claim, indented Evidence, and Result values supported, narrowed, removed, or blocked under Evidence checked
+- verify the updated docs correspond to reviewed checkout evidence, changed-code impact, or a recorded stale-truth correction made within the sync write lease
+- verify the final report records ownership review, structure requirement, split, restructure, or manual handoff reason when the ownership review applies
+- manual handoff outcomes must preserve the working tree as-is: no rollback, no post-block cleanup edits, and manual-review reporting of any remaining files
@@ -0,0 +1,54 @@
+# Truthmark Sync Report Template
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+Report completion in this shape:
+```md
+Truth Sync: completed
+
+Changed code reviewed:
+- src/auth/session.ts
+
+Sync Intent:
+- Changed code reviewed: src/auth/session.ts
+- Affected route/truth owner: docs/truthmark/routes/areas.md
+- Target truth docs: docs/truthmark/engineering/repository/bootstrap-routing.md
+- Intended update: Update session timeout behavior.
+- Evidence to verify: src/auth/session.ts:12 / docs/truthmark/routes/areas.md:11
+- User-provided decisions/rationale: User rationale: session timeout behavior changed for internal implementation consistency
+- No-update-needed rationale: not applicable; mapped truth is stale
+- Blockers: none
+
+Ownership reviewed:
+- docs/truthmark/routes/areas.md
+
+Truth docs updated:
+- docs/truthmark/engineering/repository/bootstrap-routing.md
+
+Decision/rationale captured:
+- Placed user rationale in the mapped engineering truth doc under Engineering Decisions/Rationale.
+
+Evidence checked:
+- Claim: Session timeout behavior is documented in the mapped repository truth doc.
+  Evidence: src/auth/session.ts:12 / docs/truthmark/routes/areas.md:11
+  Result: supported
+
+Helper scripts:
+- validate-write-lease: skipped, no write lease used
+
+Notes:
+- Updated session timeout behavior.
+```
+Blocked report example:
+```md
+Truth Sync: blocked
+
+Reason:
+- routing repair is not allowed
+
+Files requiring manual review:
+- docs/truthmark/routes/areas.md
+
+Next action:
+- update routing metadata and rerun Truth Sync
+```
@@ -0,0 +1,14 @@
+# Truthmark Sync Subagents And Leases
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+Claude Code subagent mode:
+- use automatically when this workflow runs in Claude Code and the parent agent chooses bounded subagent fan-out
+- dispatch read-only project subagents for verification: truth-route-auditor subagent, truth-claim-verifier subagent
+- read-only subagents inspect checkout evidence directly, return structured findings, and must not edit files
+- parent supplies bounded evidence shards; read-only subagents must not preload host instruction files or repo-wide policy docs unless assigned as evidence
+- dispatch write-capable project subagents only with explicit write leases: truth-doc-writer subagent
+- each write lease must name objective, required reads, allowed writes, forbidden writes, evidence, verification, and report fields
+- write workers must stop when a required edit is off-lease and report status, filesChanged, evidence, offLeaseChanges, blockers, and notes
+- parent must inspect the actual checkout diff against each lease before accepting a worker report
+- Parent agent owns Truth Sync acceptance, lease validation, and final report
@@ -0,0 +1,18 @@
+# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+name = "truth_claim_verifier"
+description = "Read-only Truthmark claim verifier for checking canonical truth against checkout evidence."
+sandbox_mode = "read-only"
+nickname_candidates = ["Claim Audit", "Claim Trace", "Claim Check"]
+developer_instructions = """
+Stay read-only.
+Verify the behavior-bearing truth claims assigned by the parent against primary checkout evidence.
+Use implementation, tests, config, routing, generated templates, schemas, or explicit evidence blocks as primary evidence.
+Canonical docs and examples can corroborate but are not sole proof when implementation conflicts.
+For every checked claim, classify the result as supported | narrowed | removed | blocked.
+Do not edit files, stage changes, or invent missing behavior.
+Return JSON only with keys: scope, filesReviewed, claimsChecked, evidence, unsupportedClaims, confidence, recommendedWorkflow, notes.
+Context boundary:
+Do not preload AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, or repo-wide policy docs unless the parent explicitly assigns them as evidence.
+Use only the parent-assigned shard plus required checkout evidence files.
+Return findings only; the parent workflow owns repository-policy interpretation, final decisions, and all writes.
+"""
@@ -0,0 +1,17 @@
+# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+name = "truth_doc_reviewer"
+description = "Read-only Truthmark doc reviewer for shape, decision, rationale, and evidence hygiene."
+sandbox_mode = "read-only"
+nickname_candidates = ["Doc Audit", "Doc Shape", "Doc Check"]
+developer_instructions = """
+Stay read-only.
+Review assigned canonical truth docs for compact frontmatter, required template sections, final Source References entries, Evidence checked entries, and lane-appropriate decision sections (Product Decisions in product truth, Engineering Decisions in engineering truth).
+Flag README.md files used as behavior truth targets, mixed-owner docs, and shape repairs that should move to Truth Structure.
+Do not edit files, stage changes, or rewrite docs.
+Return JSON only with keys: scope, filesReviewed, findings, evidence, confidence, recommendedWorkflow, notes.
+recommendedWorkflow must be one of: none, truthmark-document, truthmark-structure.
+Context boundary:
+Do not preload AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, or repo-wide policy docs unless the parent explicitly assigns them as evidence.
+Use only the parent-assigned shard plus required checkout evidence files.
+Return findings only; the parent workflow owns repository-policy interpretation, final decisions, and all writes.
+"""
@@ -0,0 +1,18 @@
+# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+name = "truth_doc_writer"
+description = "Write-capable Truthmark doc worker for one parent-leased truth-document shard."
+sandbox_mode = "workspace-write"
+nickname_candidates = ["Doc Writer", "Truth Writer", "Doc Sync"]
+developer_instructions = """
+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.
+Read every requiredReads entry directly before editing.
+Edit only leased canonical truth docs or leased truth routing files. Do not edit functional code, generated host surfaces, package files, config files, templates, or tests unless they are explicitly leased.
+Do not expand your own write scope. If the task needs an off-lease file, stop and report blocked.
+Block when ownership is missing or ambiguous, evidence does not support the requested claim, another worker changed the leased file, generated surfaces appear stale, or a required edit is outside the lease.
+Return YAML only with keys: status, worker, workflow, shard, filesChanged, claimsChecked, evidenceChecked, offLeaseChanges, blockers, notes.
+status must be completed or blocked.
+filesChanged must list only files you actually changed.
+offLeaseChanges must be empty for completed reports.
+The parent must validate the actual checkout diff before accepting your report.
+"""
@@ -0,0 +1,25 @@
+# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+name = "truth_route_auditor"
+description = "Read-only Truthmark route auditor for bounded routing and ownership verification."
+sandbox_mode = "read-only"
+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.
+Inspect .truthmark/config.yml and route files only when they exist; then inspect mapped truth docs and relevant implementation files directly.
+Use a route-first bounded strategy: narrow audits inspect only the routed area and directly linked counterpart docs; root-wide health first builds a cheap route-map/index from route files, then inspects only mismatches and linked leaves.
+Find missing, stale, broad, overloaded, catch-all, mixed-owner, or unrouteable ownership.
+Validate route ownership against lane-specific roots and route kind:
+- confirm mapped truth docs resolve to the correct lane root (product or engineering) for their kind
+- flag mismatch between assigned route kind and resolved doc kind (for example, product-capability routed to engineering paths)
+- verify route-doc linkage for lane pairings via realized_by and realizes before recommending edits
+- inspect product counterparts for engineering docs only when route YAML claims a product relationship, or when the parent explicitly asks for user-visible product coverage
+- treat missing product links for user-visible engineering docs as a second-pass diagnostic, not a default full-document read.
+Do not edit files, stage changes, or propose broad rewrites.
+Return JSON only with keys: scope, filesReviewed, findings, evidence, confidence, recommendedWorkflow, notes.
+recommendedWorkflow must be one of: none, truthmark-document, truthmark-structure.
+Context boundary:
+Do not preload AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, or repo-wide policy docs unless the parent explicitly assigns them as evidence.
+Use only the parent-assigned shard plus required checkout evidence files.
+Return findings only; the parent workflow owns repository-policy interpretation, final decisions, and all writes.
+"""
@@ -1,55 +0,0 @@
---
-name: truthmark-check
-description: Use when the user asks to audit repository truth health. Inspects truth docs, routing, and implementation directly; may optionally run truthmark check when available.
-argument-hint: Optional area, doc path, or audit focus
-user-invocable: true
-truthmark-version: 1.2.3
---
-
-# Truthmark Check
-
-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.
-
-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.
-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/
- 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 canonical behavior docs keep active Product Decisions and Rationale sections
- optionally run truthmark check when local tooling is available
- must not require the truthmark binary; direct inspection is always valid
- report issues and suggested fixes without silently rewriting unrelated files
-
-Truthmark hierarchy:
- Config: .truthmark/config.yml
- Root route index: docs/truthmark/areas.md
- Area route files: docs/truthmark/areas/**/*.md
- Feature docs: docs/features/**/*.md
-Decision truth lives in the canonical doc it governs.
-Date active decisions inline when added or changed, for example `Decision (2026-05-09): ...`.
-Do not create separate timestamped ADR logs or planning tickets for active decisions.
-Replace old active decisions instead of appending separate timestamped decision logs; Git history is the audit trail.
-Update Product Decisions and Rationale when a behavior change comes from a decision change.
-
-Report completion in this shape:
-
-```md
-Truth Check: completed
-
-Files reviewed:
- docs/truthmark/areas.md
-
-Issues found:
- none
-
-Fixes suggested:
- none
-
-Validation:
- truthmark check
-```
@@ -1,66 +0,0 @@
---
-name: truthmark-document
-description: Use when the user explicitly asks to document existing implemented behavior, or when Truth Sync, Truth Check, or Truth Structure reports implemented behavior that lacks canonical truth docs. Reads implementation and routing, writes truth docs and routing only, and never changes functional code.
-argument-hint: Optional implemented behavior, API endpoint, route, controller, package, or truth-doc area to document
-user-invocable: true
-truthmark-version: 1.2.3
---
-
-# Truthmark Document
-
-Use this skill to document existing implemented behavior when no functional-code changes are required for the task.
-Invocations: OpenCode /skill truthmark-document; Codex /truthmark-document or $truthmark-document; Claude Code /truthmark-document; GitHub Copilot /truthmark-document; Gemini CLI /truthmark:document.
-
-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.
-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
- must not write functional code
- when routing is missing, stale, broad, overloaded, catch-all, or cannot map the behavior to a bounded truth owner, run Truth Structure first when routing repair is safe and in scope
- block and recommend Truth Structure when routing repair is unsafe, ambiguous, or outside the task boundary
- keep feature README.md files as indexes rather than truth-document targets
- create or update bounded leaf truth docs when behavior does not fit an existing leaf doc
- keep feature docs behavior-oriented, not endpoint-oriented, unless the endpoint itself is the behavior boundary
- keep API endpoint details in the nearest contract truth doc when such a doc owns the API contract
- preserve unrelated authored content
-When creating or updating a feature doc, read docs/templates/feature-doc.md and follow its frontmatter, heading order, and section intent.
-When updating an existing feature doc, align existing feature docs to the template standard while preserving authored content that remains accurate.
-If docs/templates/feature-doc.md is missing, use the built-in minimal feature-doc structure with Current Behavior, Product Decisions, and Rationale sections.
-Teams may edit docs/templates/feature-doc.md to define their local feature-doc standard.
-Maintain architecture docs when a code change alters system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership.
-Do not put ordinary feature behavior, endpoint details, UI copy, validation rules, or bug fixes in architecture docs unless they change those architecture boundaries.
-Keep architecture docs focused on structure and ownership; keep current product behavior in feature or contract docs.
-Truthmark hierarchy:
- Config: .truthmark/config.yml
- Root route index: docs/truthmark/areas.md
- Area route files: docs/truthmark/areas/**/*.md
- Feature docs: docs/features/**/*.md
-Decision truth lives in the canonical doc it governs.
-Date active decisions inline when added or changed, for example `Decision (2026-05-09): ...`.
-Do not create separate timestamped ADR logs or planning tickets for active decisions.
-Replace old active decisions instead of appending separate timestamped decision logs; Git history is the audit trail.
-Update Product Decisions and Rationale when a behavior change comes from a decision change.
-
-Report completion in this shape:
-```md
-Truth Document: completed
-
-Implementation reviewed:
- src/api/orders/**
-
-Truth docs created:
- docs/features/orders/order-submission.md
-
-Truth docs updated:
- docs/features/contracts.md
-
-Routing updated:
- docs/truthmark/areas/orders.md
-
-Notes:
- Documented existing order submission behavior from route handlers and tests.
-```
@@ -1,51 +0,0 @@
---
-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. Reads truth docs and routing first, updates functional code only, and reports verification.
-argument-hint: Optional truth doc path, area, or desired code behavior to realize
-user-invocable: true
-truthmark-version: 1.2.3
---
-
-# Truthmark Realize
-
-Use this skill only when the user explicitly asks to realize truth docs into code.
-
-Invocations: OpenCode /skill truthmark-realize; Codex /truthmark-realize or $truthmark-realize; Claude Code /truthmark-realize; GitHub Copilot /truthmark-realize; Gemini CLI /truthmark:realize.
-
-Truth Realize is doc-first:
-
- truth docs lead
- code follows
- Truth Realize never edits the truth docs it is realizing
-
-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, and the relevant functional code.
-3. Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority.
-Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries.
-4. Update functional code only so implementation matches the truth docs.
-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.
-
-Read and write boundaries:
-
- may read truth docs, routing docs, and relevant functional code
- may write functional code only
- must not edit truth docs or truth routing while realizing those docs
-
-Report completion in this shape:
-
-```md
-Truth Realize: completed
-
-Truth docs used:
- docs/features/authentication.md
-
-Code updated:
- src/auth/session.ts
-
-Verification:
- npm test -- auth
-```
@@ -1,93 +0,0 @@
---
-name: truthmark-structure
-description: Use when the user asks to design, repair, or refresh missing, stale, broad, overloaded, catch-all, or unrouteable Truthmark area routing. Inspects the repository directly, updates docs/truthmark/areas.md, and may create starter canonical truth docs.
-argument-hint: Optional area, directory, or routing concern
-user-invocable: true
-truthmark-version: 1.2.3
---
-
-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.
-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/
- 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
- Starter truth docs must use closed YAML frontmatter bounded by opening and closing --- lines; include status, doc_type, last_reviewed, and source_of_truth inside that frontmatter.
- Starter truth docs must include ## Product Decisions and ## Rationale sections.
-When creating or updating a feature doc, read docs/templates/feature-doc.md and follow its frontmatter, heading order, and section intent.
-When updating an existing feature doc, align existing feature docs to the template standard while preserving authored content that remains accurate.
-If docs/templates/feature-doc.md is missing, use the built-in minimal feature-doc structure with Current Behavior, Product Decisions, and Rationale sections.
-Teams may edit docs/templates/feature-doc.md to define their local feature-doc standard.
- use docs/features/**, docs/architecture/**, or docs/standards/** for current truth destinations
- use only canonical current-truth destinations for starter truth docs
- keep active Product Decisions and Rationale in the canonical doc that owns the behavior
- preserve unrelated authored content
-## Topology Governance
-Truth Structure owns documentation topology. Do not depend on humans to manually organize docs/features. Treat the configured feature root as a managed semantic root.
-Inspect controllers, routes, handlers, services, packages, tests, existing truth docs, and route files; infer product and domain ownership from behavior boundaries, not from mechanical directory mirroring.
-When topology pressure exists, repair structure before creating or extending feature docs.
-Topology pressure signals:
- one area maps broad code such as src/**, app/**, server/**, services/**, or packages/**
- one area maps multiple unrelated controllers, route groups, services, or bounded contexts
- one truth doc owns unrelated behaviors or unrelated endpoint families
- the configured feature root has many direct non-index docs
- a changed controller, route, or service cannot map to a specific behavior doc
- Truth Sync would need to create a new generic feature doc because routing is too broad
- endpoint or controller names reveal domains missing from docs/truthmark/areas/**
-Use these review thresholds as guidance:
- more than 10 direct feature docs in one folder
- more than 15 leaf areas in one child route file
- more than 8 truth docs mapped to one area
- more than 5 controllers mapped through one catch-all area
-Repair rules:
- split broad, overloaded, or catch-all areas into behavior-owned child route files
- create route files under docs/truthmark/areas/ when a product/domain boundary is clear
- create feature docs under the configured feature root only when behavior lacks a current doc
- README.md files are indexes, not Truth Sync targets
- prefer bounded leaf truth docs at <feature-root>/<domain>/<behavior>.md
- keep feature docs behavior-oriented, not endpoint-oriented
- keep API endpoint details in the nearest contract truth doc when such a doc exists
- update routing so future Truth Sync can target small docs
- preserve existing authored docs; move or rewrite only when needed to remove ambiguity
-Maintain architecture docs when a code change alters system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership.
-Do not put ordinary feature behavior, endpoint details, UI copy, validation rules, or bug fixes in architecture docs unless they change those architecture boundaries.
-Keep architecture docs focused on structure and ownership; keep current product behavior in feature or contract docs.
- Do not finish topology repair with routed canonical current-truth docs missing Product Decisions or Rationale sections.
- If an existing canonical doc lacks either section, add the missing heading beside Current Behavior with a concise current-state placeholder or active decision.
-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.
- 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
- Feature docs: docs/features/**/*.md
-Decision truth lives in the canonical doc it governs.
-Date active decisions inline when added or changed, for example `Decision (2026-05-09): ...`.
-Do not create separate timestamped ADR logs or planning tickets for active decisions.
-Replace old active decisions instead of appending separate timestamped decision logs; Git history is the audit trail.
-Update Product Decisions and Rationale when a behavior change comes from a decision change.
-Report completion in this shape:
-```md
-Truth Structure: completed
-Topology reviewed:
- controllers: src/auth/**
- docs root: docs/features
- route files: docs/truthmark/areas.md
-Areas reviewed:
- src/auth/**
-Routing updated:
- docs/truthmark/areas.md
-Truth docs created:
- docs/features/authentication.md
-Topology decisions:
- Added an Authentication area because session behavior has a distinct code surface and truth owner.
-Notes:
- Added an Authentication area for session behavior.
-```
@@ -1,11 +0,0 @@
-interface:
-  display_name: "Truthmark Structure"
-  short_description: "Design or repair Truthmark area routing"
-  default_prompt: "Use $truthmark-structure to design or repair Truthmark area routing."
-
-policy:
-  allow_implicit_invocation: false
-
-truthmark:
-  version: "1.2.3"
-  refresh_command: "truthmark init"
@@ -1,100 +0,0 @@
---
-name: truthmark-sync
-description: Use automatically before finishing when functional code changed since the last successful Truth Sync, and when the user explicitly invokes /truthmark-sync, $truthmark-sync, or /truthmark:sync. Inspects changed code directly, updates truth docs and routing, and verifies post-sync boundaries. Skip for documentation-only changes, formatting-only changes, behavior-preserving renames, missing Truthmark config, or no functional code changes.
-argument-hint: Optional changed-code area, truth-doc area, or sync focus
-user-invocable: true
-truthmark-version: 1.2.3
---
-
-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.
-Explicit invocation runs immediately. Later functional-code changes reopen the finish-time requirement, and an earlier explicit run satisfies the finish gate only if no later functional-code changes occur.
-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.
-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.
-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 one bounded Truth Sync worker only when the host supports subagent dispatch and the acting agent chooses that path; otherwise execute the same sync task inline.
-Topology quality gate:
- before updating truth docs, verify the changed code resolves to a specific behavior-owned area and bounded truth owner
- if routing is missing, stale, broad, overloaded, catch-all route only, or cannot map changed code to a bounded truth owner, do not create another generic feature doc
- run Truth Structure before syncing when topology repair is safe and in scope
- block and recommend Truth Structure when topology repair is unsafe, ambiguous, or outside the current task boundary
- report the route files and changed code paths that require structure repair
- README.md files are indexes, not Truth Sync targets
- must not append behavior details to a feature README
- create or update a bounded leaf truth doc when behavior changes do not fit an existing leaf doc
-When creating or updating a feature doc, read docs/templates/feature-doc.md and follow its frontmatter, heading order, and section intent.
-When updating an existing feature doc, align existing feature docs to the template standard while preserving authored content that remains accurate.
-If docs/templates/feature-doc.md is missing, use the built-in minimal feature-doc structure with Current Behavior, Product Decisions, and Rationale sections.
-Teams may edit docs/templates/feature-doc.md to define their local feature-doc standard.
-Maintain architecture docs when a code change alters system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership.
-Do not put ordinary feature behavior, endpoint details, UI copy, validation rules, or bug fixes in architecture docs unless they change those architecture boundaries.
-Keep architecture docs focused on structure and ownership; keep current product behavior in feature or contract docs.
-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
- optional validation must not replace agent judgment about docs and routing
- update Product Decisions and Rationale when a behavior change comes from a decision change
-Truthmark hierarchy:
- Config: .truthmark/config.yml
- Root route index: docs/truthmark/areas.md
- Area route files: docs/truthmark/areas/**/*.md
- Feature docs: docs/features/**/*.md
-Decision truth lives in the canonical doc it governs.
-Date active decisions inline when added or changed, for example `Decision (2026-05-09): ...`.
-Do not create separate timestamped ADR logs or planning tickets for active decisions.
-Replace old active decisions instead of appending separate timestamped decision logs; Git history is the audit trail.
-Update Product Decisions and Rationale when a behavior change comes from a decision change.
-### Truth Sync Worker
-The parent provides the task focus and any repository context already gathered.
-Worker rules:
- inspect relevant staged, unstaged, and untracked functional code directly
- read .truthmark/config.yml, docs/truthmark/areas.md, and canonical truth docs directly
- Code verification is parent-owned; report what was run or why it was not run
- may write truth docs and docs/truthmark/areas.md only for Truth Sync alignment
- must not rewrite functional code
-Return result in this shape:
- status: completed | blocked
- changedCodeReviewed: string[]
- truthDocsUpdated: string[]
- routingDocsUpdated: string[]
- notes: string[]
- blockedReason?: string
- manualReviewFiles?: string[]
-Parent post-sync verification:
- verify only truth docs and docs/truthmark/areas.md changed during sync
- block on any unrelated diff caused by the sync step
- block if functional code changed during sync
- verify the worker report matches the required headings and sections
- verify the updated docs correspond to the reviewed changed-code surface
- blocked outcomes must preserve the working tree as-is: no rollback, no post-block cleanup edits, and manual-review reporting of any remaining files
-Report completion in this shape:
-```md
-Truth Sync: completed
-
-Changed code reviewed:
- src/auth/session.ts
-
-Truth docs updated:
- docs/features/repository/overview.md
-
-Notes:
- Updated session timeout behavior.
-```
-Blocked report example:
-```md
-Truth Sync: blocked
-
-Reason:
- routing repair is not allowed
-
-Files requiring manual review:
- docs/truthmark/areas.md
-
-Next action:
- update routing metadata and rerun Truth Sync
-```
@@ -0,0 +1,22 @@
+---
+name: truth-claim-verifier
+description: Read-only Truthmark claim verifier for checking canonical truth against checkout evidence.
+kind: local
+tools: [read_file, grep_search]
+---
+
+# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+Manual invocation: @truth-claim-verifier
+
+Stay read-only.
+Verify the behavior-bearing truth claims assigned by the parent against primary checkout evidence.
+Use implementation, tests, config, routing, generated templates, schemas, or explicit evidence blocks as primary evidence.
+Canonical docs and examples can corroborate but are not sole proof when implementation conflicts.
+For every checked claim, classify the result as supported | narrowed | removed | blocked.
+Do not edit files, stage changes, or invent missing behavior.
+Return JSON only with keys: scope, filesReviewed, claimsChecked, evidence, unsupportedClaims, confidence, recommendedWorkflow, notes.
+Context boundary:
+Do not preload AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, or repo-wide policy docs unless the parent explicitly assigns them as evidence.
+Use only the parent-assigned shard plus required checkout evidence files.
+Return findings only; the parent workflow owns repository-policy interpretation, final decisions, and all writes.
@@ -0,0 +1,21 @@
+---
+name: truth-doc-reviewer
+description: Read-only Truthmark doc reviewer for shape, decision, rationale, and evidence hygiene.
+kind: local
+tools: [read_file, grep_search]
+---
+
+# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+Manual invocation: @truth-doc-reviewer
+
+Stay read-only.
+Review assigned canonical truth docs for compact frontmatter, required template sections, final Source References entries, Evidence checked entries, and lane-appropriate decision sections (Product Decisions in product truth, Engineering Decisions in engineering truth).
+Flag README.md files used as behavior truth targets, mixed-owner docs, and shape repairs that should move to Truth Structure.
+Do not edit files, stage changes, or rewrite docs.
+Return JSON only with keys: scope, filesReviewed, findings, evidence, confidence, recommendedWorkflow, notes.
+recommendedWorkflow must be one of: none, truthmark-document, truthmark-structure.
+Context boundary:
+Do not preload AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, or repo-wide policy docs unless the parent explicitly assigns them as evidence.
+Use only the parent-assigned shard plus required checkout evidence files.
+Return findings only; the parent workflow owns repository-policy interpretation, final decisions, and all writes.
@@ -0,0 +1,22 @@
+---
+name: truth-doc-writer
+description: Write-capable Truthmark doc worker for one parent-leased truth-document shard.
+kind: local
+tools: [read_file, grep_search, write_file]
+---
+
+# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+Manual invocation: @truth-doc-writer with an explicit parent write lease.
+
+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.
+Read every requiredReads entry directly before editing.
+Edit only leased canonical truth docs or leased truth routing files. Do not edit functional code, generated host surfaces, package files, config files, templates, or tests unless they are explicitly leased.
+Do not expand your own write scope. If the task needs an off-lease file, stop and report blocked.
+Block when ownership is missing or ambiguous, evidence does not support the requested claim, another worker changed the leased file, generated surfaces appear stale, or a required edit is outside the lease.
+Return YAML only with keys: status, worker, workflow, shard, filesChanged, claimsChecked, evidenceChecked, offLeaseChanges, blockers, notes.
+status must be completed or blocked.
+filesChanged must list only files you actually changed.
+offLeaseChanges must be empty for completed reports.
+The parent must validate the actual checkout diff before accepting your report.
@@ -0,0 +1,29 @@
+---
+name: truth-route-auditor
+description: Read-only Truthmark route auditor for bounded routing and ownership verification.
+kind: local
+tools: [read_file, grep_search]
+---
+
+# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+Manual invocation: @truth-route-auditor
+
+Stay read-only.
+Audit one bounded Truthmark route, area, or doc shard assigned by the parent.
+Inspect .truthmark/config.yml and route files only when they exist; then inspect mapped truth docs and relevant implementation files directly.
+Use a route-first bounded strategy: narrow audits inspect only the routed area and directly linked counterpart docs; root-wide health first builds a cheap route-map/index from route files, then inspects only mismatches and linked leaves.
+Find missing, stale, broad, overloaded, catch-all, mixed-owner, or unrouteable ownership.
+Validate route ownership against lane-specific roots and route kind:
+- confirm mapped truth docs resolve to the correct lane root (product or engineering) for their kind
+- flag mismatch between assigned route kind and resolved doc kind (for example, product-capability routed to engineering paths)
+- verify route-doc linkage for lane pairings via realized_by and realizes before recommending edits
+- inspect product counterparts for engineering docs only when route YAML claims a product relationship, or when the parent explicitly asks for user-visible product coverage
+- treat missing product links for user-visible engineering docs as a second-pass diagnostic, not a default full-document read.
+Do not edit files, stage changes, or propose broad rewrites.
+Return JSON only with keys: scope, filesReviewed, findings, evidence, confidence, recommendedWorkflow, notes.
+recommendedWorkflow must be one of: none, truthmark-document, truthmark-structure.
+Context boundary:
+Do not preload AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, or repo-wide policy docs unless the parent explicitly assigns them as evidence.
+Use only the parent-assigned shard plus required checkout evidence files.
+Return findings only; the parent workflow owns repository-policy interpretation, final decisions, and all writes.
@@ -1,58 +1,15 @@
-description = "Audit repository truth health."
+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."
 prompt = '''
---
-name: truthmark-check
-description: Use when the user asks to audit repository truth health. Inspects truth docs, routing, and implementation directly; may optionally run truthmark check when available.
-argument-hint: Optional area, doc path, or audit focus
-user-invocable: true
-truthmark-version: 1.2.3
---
+This command is the Gemini CLI entrypoint for Truthmark Check.

-# Truthmark Check
+Do not invoke another Truthmark command from here.

-Use this skill to audit repository truth health.
+Read these host-local files in order only as needed:
+- .gemini/skills/truthmark-check/SKILL.md
+- .gemini/skills/truthmark-check/support/procedure.md
+- .gemini/skills/truthmark-check/support/report-template.md
+- .gemini/skills/truthmark-check/support/subagents-and-leases.md

-Invocations: OpenCode /skill truthmark-check; Codex /truthmark-check or $truthmark-check; Claude Code /truthmark-check; GitHub Copilot /truthmark-check; Gemini CLI /truthmark:check.
-
-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.
-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/
- 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 canonical behavior docs keep active Product Decisions and Rationale sections
- optionally run truthmark check when local tooling is available
- must not require the truthmark binary; direct inspection is always valid
- report issues and suggested fixes without silently rewriting unrelated files
-
-Truthmark hierarchy:
- Config: .truthmark/config.yml
- Root route index: docs/truthmark/areas.md
- Area route files: docs/truthmark/areas/**/*.md
- Feature docs: docs/features/**/*.md
-Decision truth lives in the canonical doc it governs.
-Date active decisions inline when added or changed, for example `Decision (2026-05-09): ...`.
-Do not create separate timestamped ADR logs or planning tickets for active decisions.
-Replace old active decisions instead of appending separate timestamped decision logs; Git history is the audit trail.
-Update Product Decisions and Rationale when a behavior change comes from a decision change.
-
-Report completion in this shape:
-
-```md
-Truth Check: completed
-
-Files reviewed:
- docs/truthmark/areas.md
-
-Issues found:
- none
-
-Fixes suggested:
- none
-
-Validation:
- truthmark check
-```
+If skill entrypoints are unavailable, use the host's direct evidence-first manual fallback procedure.
+User focus or arguments: {{args}}
 '''
@@ -1,69 +1,17 @@
-description = "Document existing implemented behavior."
+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."
 prompt = '''
---
-name: truthmark-document
-description: Use when the user explicitly asks to document existing implemented behavior, or when Truth Sync, Truth Check, or Truth Structure reports implemented behavior that lacks canonical truth docs. Reads implementation and routing, writes truth docs and routing only, and never changes functional code.
-argument-hint: Optional implemented behavior, API endpoint, route, controller, package, or truth-doc area to document
-user-invocable: true
-truthmark-version: 1.2.3
---
+This command is the Gemini CLI entrypoint for Truthmark Document.

-# Truthmark Document
+Do not invoke another Truthmark command from here.

-Use this skill to document existing implemented behavior when no functional-code changes are required for the task.
-Invocations: OpenCode /skill truthmark-document; Codex /truthmark-document or $truthmark-document; Claude Code /truthmark-document; GitHub Copilot /truthmark-document; Gemini CLI /truthmark:document.
+Read these host-local files in order only as needed:
+- .gemini/skills/truthmark-document/SKILL.md
+- .gemini/skills/truthmark-document/support/procedure.md
+- .gemini/skills/truthmark-document/support/report-template.md
+- .gemini/skills/truthmark-document/support/subagents-and-leases.md
+- .gemini/skills/truthmark-document/helper-manifest.yml
+- .gemini/skills/truthmark-document/support/helper-policy.md

-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.
-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
- must not write functional code
- when routing is missing, stale, broad, overloaded, catch-all, or cannot map the behavior to a bounded truth owner, run Truth Structure first when routing repair is safe and in scope
- block and recommend Truth Structure when routing repair is unsafe, ambiguous, or outside the task boundary
- keep feature README.md files as indexes rather than truth-document targets
- create or update bounded leaf truth docs when behavior does not fit an existing leaf doc
- keep feature docs behavior-oriented, not endpoint-oriented, unless the endpoint itself is the behavior boundary
- keep API endpoint details in the nearest contract truth doc when such a doc owns the API contract
- preserve unrelated authored content
-When creating or updating a feature doc, read docs/templates/feature-doc.md and follow its frontmatter, heading order, and section intent.
-When updating an existing feature doc, align existing feature docs to the template standard while preserving authored content that remains accurate.
-If docs/templates/feature-doc.md is missing, use the built-in minimal feature-doc structure with Current Behavior, Product Decisions, and Rationale sections.
-Teams may edit docs/templates/feature-doc.md to define their local feature-doc standard.
-Maintain architecture docs when a code change alters system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership.
-Do not put ordinary feature behavior, endpoint details, UI copy, validation rules, or bug fixes in architecture docs unless they change those architecture boundaries.
-Keep architecture docs focused on structure and ownership; keep current product behavior in feature or contract docs.
-Truthmark hierarchy:
- Config: .truthmark/config.yml
- Root route index: docs/truthmark/areas.md
- Area route files: docs/truthmark/areas/**/*.md
- Feature docs: docs/features/**/*.md
-Decision truth lives in the canonical doc it governs.
-Date active decisions inline when added or changed, for example `Decision (2026-05-09): ...`.
-Do not create separate timestamped ADR logs or planning tickets for active decisions.
-Replace old active decisions instead of appending separate timestamped decision logs; Git history is the audit trail.
-Update Product Decisions and Rationale when a behavior change comes from a decision change.
-
-Report completion in this shape:
-```md
-Truth Document: completed
-
-Implementation reviewed:
- src/api/orders/**
-
-Truth docs created:
- docs/features/orders/order-submission.md
-
-Truth docs updated:
- docs/features/contracts.md
-
-Routing updated:
- docs/truthmark/areas/orders.md
-
-Notes:
- Documented existing order submission behavior from route handlers and tests.
-```
+If skill entrypoints are unavailable, use the host's direct evidence-first manual fallback procedure.
+User focus or arguments: {{args}}
 '''
@@ -0,0 +1,15 @@
+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."
+prompt = '''
+This command is the Gemini CLI entrypoint for Truthmark Preview.
+
+Do not invoke another Truthmark command from here.
+
+Read these host-local files in order only as needed:
+- .gemini/skills/truthmark-preview/SKILL.md
+- .gemini/skills/truthmark-preview/support/procedure.md
+- .gemini/skills/truthmark-preview/support/report-template.md
+- .gemini/skills/truthmark-preview/support/subagents-and-leases.md
+
+If skill entrypoints are unavailable, use the host's direct evidence-first manual fallback procedure.
+User focus or arguments: {{args}}
+'''
@@ -1,55 +1,14 @@
-description = "Realize repository truth docs into code."
+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."
 prompt = '''
---
-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. Reads truth docs and routing first, updates functional code only, and reports verification.
-argument-hint: Optional truth doc path, area, or desired code behavior to realize
-user-invocable: true
-truthmark-version: 1.2.3
---
+This command is the Gemini CLI entrypoint for Truthmark Realize.

-# Truthmark Realize
+Do not invoke another Truthmark command from here.

-Use this skill only when the user explicitly asks to realize truth docs into code.
-
-Invocations: OpenCode /skill truthmark-realize; Codex /truthmark-realize or $truthmark-realize; Claude Code /truthmark-realize; GitHub Copilot /truthmark-realize; Gemini CLI /truthmark:realize.
-
-Truth Realize is doc-first:
-
- truth docs lead
- code follows
- Truth Realize never edits the truth docs it is realizing
-
-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, and the relevant functional code.
-3. Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority.
-Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries.
-4. Update functional code only so implementation matches the truth docs.
-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.
-
-Read and write boundaries:
-
- may read truth docs, routing docs, and relevant functional code
- may write functional code only
- must not edit truth docs or truth routing while realizing those docs
-
-Report completion in this shape:
-
-```md
-Truth Realize: completed
-
-Truth docs used:
- docs/features/authentication.md
-
-Code updated:
- src/auth/session.ts
-
-Verification:
- npm test -- auth
-```
+Read these host-local files in order only as needed:
+- .gemini/skills/truthmark-realize/SKILL.md
+- .gemini/skills/truthmark-realize/support/procedure.md
+- .gemini/skills/truthmark-realize/support/report-template.md

+If skill entrypoints are unavailable, use the host's direct evidence-first manual fallback procedure.
+User focus or arguments: {{args}}
 '''
@@ -1,96 +1,15 @@
-description = "Design or repair Truthmark area routing."
+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."
 prompt = '''
---
-name: truthmark-structure
-description: Use when the user asks to design, repair, or refresh missing, stale, broad, overloaded, catch-all, or unrouteable Truthmark area routing. Inspects the repository directly, updates docs/truthmark/areas.md, and may create starter canonical truth docs.
-argument-hint: Optional area, directory, or routing concern
-user-invocable: true
-truthmark-version: 1.2.3
---
+This command is the Gemini CLI entrypoint for Truthmark Structure.

-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.
-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/
- 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
- Starter truth docs must use closed YAML frontmatter bounded by opening and closing --- lines; include status, doc_type, last_reviewed, and source_of_truth inside that frontmatter.
- Starter truth docs must include ## Product Decisions and ## Rationale sections.
-When creating or updating a feature doc, read docs/templates/feature-doc.md and follow its frontmatter, heading order, and section intent.
-When updating an existing feature doc, align existing feature docs to the template standard while preserving authored content that remains accurate.
-If docs/templates/feature-doc.md is missing, use the built-in minimal feature-doc structure with Current Behavior, Product Decisions, and Rationale sections.
-Teams may edit docs/templates/feature-doc.md to define their local feature-doc standard.
- use docs/features/**, docs/architecture/**, or docs/standards/** for current truth destinations
- use only canonical current-truth destinations for starter truth docs
- keep active Product Decisions and Rationale in the canonical doc that owns the behavior
- preserve unrelated authored content
-## Topology Governance
-Truth Structure owns documentation topology. Do not depend on humans to manually organize docs/features. Treat the configured feature root as a managed semantic root.
-Inspect controllers, routes, handlers, services, packages, tests, existing truth docs, and route files; infer product and domain ownership from behavior boundaries, not from mechanical directory mirroring.
-When topology pressure exists, repair structure before creating or extending feature docs.
-Topology pressure signals:
- one area maps broad code such as src/**, app/**, server/**, services/**, or packages/**
- one area maps multiple unrelated controllers, route groups, services, or bounded contexts
- one truth doc owns unrelated behaviors or unrelated endpoint families
- the configured feature root has many direct non-index docs
- a changed controller, route, or service cannot map to a specific behavior doc
- Truth Sync would need to create a new generic feature doc because routing is too broad
- endpoint or controller names reveal domains missing from docs/truthmark/areas/**
-Use these review thresholds as guidance:
- more than 10 direct feature docs in one folder
- more than 15 leaf areas in one child route file
- more than 8 truth docs mapped to one area
- more than 5 controllers mapped through one catch-all area
-Repair rules:
- split broad, overloaded, or catch-all areas into behavior-owned child route files
- create route files under docs/truthmark/areas/ when a product/domain boundary is clear
- create feature docs under the configured feature root only when behavior lacks a current doc
- README.md files are indexes, not Truth Sync targets
- prefer bounded leaf truth docs at <feature-root>/<domain>/<behavior>.md
- keep feature docs behavior-oriented, not endpoint-oriented
- keep API endpoint details in the nearest contract truth doc when such a doc exists
- update routing so future Truth Sync can target small docs
- preserve existing authored docs; move or rewrite only when needed to remove ambiguity
-Maintain architecture docs when a code change alters system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership.
-Do not put ordinary feature behavior, endpoint details, UI copy, validation rules, or bug fixes in architecture docs unless they change those architecture boundaries.
-Keep architecture docs focused on structure and ownership; keep current product behavior in feature or contract docs.
- Do not finish topology repair with routed canonical current-truth docs missing Product Decisions or Rationale sections.
- If an existing canonical doc lacks either section, add the missing heading beside Current Behavior with a concise current-state placeholder or active decision.
-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.
- 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
- Feature docs: docs/features/**/*.md
-Decision truth lives in the canonical doc it governs.
-Date active decisions inline when added or changed, for example `Decision (2026-05-09): ...`.
-Do not create separate timestamped ADR logs or planning tickets for active decisions.
-Replace old active decisions instead of appending separate timestamped decision logs; Git history is the audit trail.
-Update Product Decisions and Rationale when a behavior change comes from a decision change.
-Report completion in this shape:
-```md
-Truth Structure: completed
-Topology reviewed:
- controllers: src/auth/**
- docs root: docs/features
- route files: docs/truthmark/areas.md
-Areas reviewed:
- src/auth/**
-Routing updated:
- docs/truthmark/areas.md
-Truth docs created:
- docs/features/authentication.md
-Topology decisions:
- Added an Authentication area because session behavior has a distinct code surface and truth owner.
-Notes:
- Added an Authentication area for session behavior.
-```
+Do not invoke another Truthmark command from here.
+
+Read these host-local files in order only as needed:
+- .gemini/skills/truthmark-structure/SKILL.md
+- .gemini/skills/truthmark-structure/support/procedure.md
+- .gemini/skills/truthmark-structure/support/report-template.md
+- .gemini/skills/truthmark-structure/support/subagents-and-leases.md
+
+If skill entrypoints are unavailable, use the host's direct evidence-first manual fallback procedure.
+User focus or arguments: {{args}}
 '''
@@ -1,103 +1,17 @@
-description = "Sync repository truth docs from functional code changes; skip docs-only/no-code changes."
+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."
 prompt = '''
---
-name: truthmark-sync
-description: Use automatically before finishing when functional code changed since the last successful Truth Sync, and when the user explicitly invokes /truthmark-sync, $truthmark-sync, or /truthmark:sync. Inspects changed code directly, updates truth docs and routing, and verifies post-sync boundaries. Skip for documentation-only changes, formatting-only changes, behavior-preserving renames, missing Truthmark config, or no functional code changes.
-argument-hint: Optional changed-code area, truth-doc area, or sync focus
-user-invocable: true
-truthmark-version: 1.2.3
---
+This command is the Gemini CLI entrypoint for Truthmark Sync.

-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.
-Explicit invocation runs immediately. Later functional-code changes reopen the finish-time requirement, and an earlier explicit run satisfies the finish gate only if no later functional-code changes occur.
-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.
-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.
-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 one bounded Truth Sync worker only when the host supports subagent dispatch and the acting agent chooses that path; otherwise execute the same sync task inline.
-Topology quality gate:
- before updating truth docs, verify the changed code resolves to a specific behavior-owned area and bounded truth owner
- if routing is missing, stale, broad, overloaded, catch-all route only, or cannot map changed code to a bounded truth owner, do not create another generic feature doc
- run Truth Structure before syncing when topology repair is safe and in scope
- block and recommend Truth Structure when topology repair is unsafe, ambiguous, or outside the current task boundary
- report the route files and changed code paths that require structure repair
- README.md files are indexes, not Truth Sync targets
- must not append behavior details to a feature README
- create or update a bounded leaf truth doc when behavior changes do not fit an existing leaf doc
-When creating or updating a feature doc, read docs/templates/feature-doc.md and follow its frontmatter, heading order, and section intent.
-When updating an existing feature doc, align existing feature docs to the template standard while preserving authored content that remains accurate.
-If docs/templates/feature-doc.md is missing, use the built-in minimal feature-doc structure with Current Behavior, Product Decisions, and Rationale sections.
-Teams may edit docs/templates/feature-doc.md to define their local feature-doc standard.
-Maintain architecture docs when a code change alters system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership.
-Do not put ordinary feature behavior, endpoint details, UI copy, validation rules, or bug fixes in architecture docs unless they change those architecture boundaries.
-Keep architecture docs focused on structure and ownership; keep current product behavior in feature or contract docs.
-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
- optional validation must not replace agent judgment about docs and routing
- update Product Decisions and Rationale when a behavior change comes from a decision change
-Truthmark hierarchy:
- Config: .truthmark/config.yml
- Root route index: docs/truthmark/areas.md
- Area route files: docs/truthmark/areas/**/*.md
- Feature docs: docs/features/**/*.md
-Decision truth lives in the canonical doc it governs.
-Date active decisions inline when added or changed, for example `Decision (2026-05-09): ...`.
-Do not create separate timestamped ADR logs or planning tickets for active decisions.
-Replace old active decisions instead of appending separate timestamped decision logs; Git history is the audit trail.
-Update Product Decisions and Rationale when a behavior change comes from a decision change.
-### Truth Sync Worker
-The parent provides the task focus and any repository context already gathered.
-Worker rules:
- inspect relevant staged, unstaged, and untracked functional code directly
- read .truthmark/config.yml, docs/truthmark/areas.md, and canonical truth docs directly
- Code verification is parent-owned; report what was run or why it was not run
- may write truth docs and docs/truthmark/areas.md only for Truth Sync alignment
- must not rewrite functional code
-Return result in this shape:
- status: completed | blocked
- changedCodeReviewed: string[]
- truthDocsUpdated: string[]
- routingDocsUpdated: string[]
- notes: string[]
- blockedReason?: string
- manualReviewFiles?: string[]
-Parent post-sync verification:
- verify only truth docs and docs/truthmark/areas.md changed during sync
- block on any unrelated diff caused by the sync step
- block if functional code changed during sync
- verify the worker report matches the required headings and sections
- verify the updated docs correspond to the reviewed changed-code surface
- blocked outcomes must preserve the working tree as-is: no rollback, no post-block cleanup edits, and manual-review reporting of any remaining files
-Report completion in this shape:
-```md
-Truth Sync: completed
+Do not invoke another Truthmark command from here.

-Changed code reviewed:
- src/auth/session.ts
+Read these host-local files in order only as needed:
+- .gemini/skills/truthmark-sync/SKILL.md
+- .gemini/skills/truthmark-sync/support/procedure.md
+- .gemini/skills/truthmark-sync/support/report-template.md
+- .gemini/skills/truthmark-sync/support/subagents-and-leases.md
+- .gemini/skills/truthmark-sync/helper-manifest.yml
+- .gemini/skills/truthmark-sync/support/helper-policy.md

-Truth docs updated:
- docs/features/repository/overview.md
-
-Notes:
- Updated session timeout behavior.
-```
-Blocked report example:
-```md
-Truth Sync: blocked
-
-Reason:
- routing repair is not allowed
-
-Files requiring manual review:
- docs/truthmark/areas.md
-
-Next action:
- update routing metadata and rerun Truth Sync
-```
+If skill entrypoints are unavailable, use the host's direct evidence-first manual fallback procedure.
+User focus or arguments: {{args}}
 '''
@@ -0,0 +1,27 @@
+---
+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 Check
+
+Use this skill to audit repository truth health.
+
+Use as a Gemini CLI Agent Skill; commands remain available under `/truthmark:*` for command-first invocation.
+
+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 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/routes/areas.md; docs/truthmark/routes/areas/) only when they exist; then inspect canonical docs and relevant implementation directly.
+- Report issues and suggested fixes; do not silently rewrite unrelated files.
+- Read support/procedure.md before auditing details.
+- Read support/subagents-and-leases.md only when dispatching verifier subagents.
+- Read support/report-template.md before the final report.
+
+Progressive disclosure:
+- support/procedure.md — read before edits or detailed auditing; contains core review questions
+- support/report-template.md — read before the final report
+- support/subagents-and-leases.md — read only when using subagents, leases, or accepting worker output
@@ -0,0 +1,56 @@
+# Truthmark Check Procedure
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+# Truthmark Check
+
+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.
+
+Truth Check is agent-led:
+
+- inspect .truthmark/config.yml and configured route files only when they exist; then inspect canonical docs and relevant implementation directly
+- inspect the configured root route index at docs/truthmark/routes/areas.md and relevant child route files under docs/truthmark/routes/areas/ when they exist
+- Evidence 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.
+- Lane classification:
+  - classify the request or changed surface as product-lane, engineering-lane, both-lane, or ambiguous for reporting only
+  - product-lane ownership belongs under docs/truthmark/product and describes product promises, boundaries, rationale, decisions, and success criteria
+  - engineering-lane ownership belongs under docs/truthmark/engineering and describes source-backed current realization, contracts, architecture, workflows, operations, or tests
+  - both-lane ownership uses separate product and engineering docs cross-linked in route YAML with realized_by and realizes, not in doc frontmatter
+  - ambiguous lane ownership should be reported for manual handoff or routed to Truth Structure
+  - Do not make product docs a summary of engineering docs. Do not make engineering docs a detailed version of product docs. Product truth says what must be true and why. Engineering truth says how the repository currently realizes it.
+- check that current docs describe current code rather than historical plans
+- keep lane and cross-lane checks route-first and bounded:
+  - for a narrow audit, inspect only the routed area and directly linked counterpart docs
+  - for root-wide truth health, first build a cheap route-map/index from route files, then inspect only mismatches and linked leaves
+  - inspect product counterparts for engineering docs only when route YAML claims a product relationship, or when the user explicitly asks for user-visible product coverage
+- check lane root/kind alignment for product truth under docs/truthmark/product and engineering truth under docs/truthmark/engineering
+- check route YAML cross-lane realized_by and realizes links for existence and lane compatibility
+- report missing product links for user-visible engineering docs only as a second-pass review diagnostic, not as default full-document reads or hard errors
+- check product docs do not contain engineering execution flow, generated file inventories, or CLI envelope mechanics
+- check engineering docs do not contain product promises, product rationale, or Product Decisions sections
+- never judge whether a product decision is commercially correct, valuable, prioritized, or desirable
+- 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 docs keep lane-appropriate decisions and rationale sections
+- optionally run truthmark check when local tooling is available
+- must not require the truthmark binary; direct inspection is always valid
+- report issues and suggested fixes without silently rewriting unrelated files
+- if follow-up docs edits are needed for mixed-owner docs, run or recommend Truth Structure before editing
+Evidence checklist:
+- support each finding and suggested fix with evidence from config, route files, canonical docs, implementation, templates, or tests
+- 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 hints:
+- Config, when present: .truthmark/config.yml
+- Root route index, when present: docs/truthmark/routes/areas.md
+- Area route files, when present: docs/truthmark/routes/areas/**/*.md
+- Product truth docs, when present: docs/truthmark/product/**/*.md
+- Engineering truth docs, when present: docs/truthmark/engineering/**/*.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.
+Product decisions belong in product truth; engineering, architecture, contract, workflow, and operational decisions belong in engineering truth.
@@ -0,0 +1,27 @@
+# Truthmark Check Report Template
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+Report completion in this shape:
+
+```md
+Truth Check: completed
+
+Files reviewed:
+- docs/truthmark/routes/areas.md
+
+Issues found:
+- none
+
+Fixes suggested:
+- none
+
+Evidence checked:
+- Finding: The root route index is present and maps repository truth owners.
+  Evidence: docs/truthmark/routes/areas.md:1
+  Suggested fix: none
+  Confidence: high
+
+Validation:
+- truthmark check
+```
@@ -0,0 +1,10 @@
+# Truthmark Check Subagents And Leases
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+Gemini CLI subagent mode:
+- use automatically when this workflow runs in Gemini CLI and the parent agent chooses bounded project subagent fan-out
+- dispatch read-only project subagents only: @truth-route-auditor, @truth-claim-verifier, @truth-doc-reviewer
+- subagents inspect checkout evidence directly, return structured findings, and must not edit files
+- parent supplies bounded evidence shards; subagents must not preload host instruction files or repo-wide policy docs unless assigned as evidence
+- Parent agent owns the final Truth Check report
@@ -0,0 +1,30 @@
+---
+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 Document
+
+Use this skill to document existing implemented behavior when no functional-code changes are required for the task.
+
+Use as a Gemini CLI Agent Skill; commands remain available under `/truthmark:*` for command-first invocation.
+
+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 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/routes/areas.md; docs/truthmark/routes/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.
+- Read support/subagents-and-leases.md only when dispatching or accepting worker output.
+- Read support/report-template.md before the final report.
+
+Progressive disclosure:
+- support/procedure.md — read before edits or detailed auditing; contains core review questions
+- support/report-template.md — read before the final report
+- support/subagents-and-leases.md — read only when using subagents, leases, or accepting worker output
+- helper-manifest.yml — read only when invoking helper validators or validating helper registration
+- support/helper-policy.md — read only when invoking helper validators or reporting helper status
@@ -0,0 +1,34 @@
+# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+helpers:
+  validate-document-report:
+    optional: true
+    runner: truthmark
+    command:
+      argv:
+        - truthmark
+        - validate
+        - document-report
+        - <report-file>
+        - --json
+    inputs:
+      - document report file
+    output: json
+    writes: false
+    fallback: manually validate support/report-template.md required sections and structured Evidence checked entries
+  validate-write-lease:
+    optional: true
+    runner: truthmark
+    command:
+      argv:
+        - truthmark
+        - validate
+        - write-lease
+        - <lease-or-report-file>
+        - <changed-files-file>
+        - --json
+    inputs:
+      - lease or worker report yaml
+      - changed file list
+    output: json
+    writes: false
+    fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files
@@ -0,0 +1,23 @@
+# Optional Helper CLI Policy
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+Optional helper CLI commands may collect deterministic checkout facts or validate artifacts. If the Truthmark CLI is unavailable or cannot return the declared helper output, 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.
+
+Runner detection:
+- Check that the declared Truthmark CLI runner is available before invoking a helper.
+- Invoke helpers through the installed `truthmark validate ... --json` CLI command using argv-style arguments from helper-manifest.yml.
+- If unavailable, failing, or returning incompatible output, treat the helper as skipped and use the manual fallback.
+- Do not fail the workflow solely because a helper cannot run.
+
+Available helpers:
+- validate-document-report: optional truthmark; manual fallback: manually validate support/report-template.md required sections and structured Evidence checked entries
+- validate-write-lease: optional truthmark; 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:
+
+```md
+Helper scripts:
+- validate-document-report: ran, passed
+- validate-write-lease: skipped, no write lease used
+```
@@ -0,0 +1,92 @@
+# Truthmark Document Procedure
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+# Truthmark Document
+
+Use this skill to document existing implemented behavior when no functional-code changes are required for the task.
+Invocations: OpenCode /skill truthmark-document; Codex /truthmark-document or $truthmark-document; Claude Code /truthmark-document; GitHub Copilot /truthmark-document; Gemini CLI /truthmark:document.
+
+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 and configured route files only when they exist; then inspect existing canonical docs, implementation code, and tests directly
+- Evidence 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.
+- Lane classification:
+  - before writing canonical truth docs, classify the request or change as product-lane, engineering-lane, both-lane, or ambiguous
+  - product-lane writes belong under docs/truthmark/product and state product promises, boundaries, rationale, decisions, and success criteria
+  - engineering-lane writes belong under docs/truthmark/engineering and state source-backed current realization, contracts, architecture, workflows, operations, or tests
+  - both-lane work must write separate product and engineering docs and cross-link them in route YAML with realized_by and realizes, not in doc frontmatter
+  - ambiguous lane ownership must stop or invoke Truth Structure instead of writing a mixed document
+  - Do not make product docs a summary of engineering docs. Do not make engineering docs a detailed version of product docs. Product truth says what must be true and why. Engineering truth says how the repository currently realizes it.
+- document current implemented behavior; do not invent future behavior or planned endpoints
+- may write canonical truth docs and docs/truthmark/routes/areas.md or relevant child route files only
+- must not write functional code
+- when routing is missing, stale, broad, overloaded, catch-all, or cannot map the behavior to a bounded truth owner, run Truth Structure first when routing repair is safe and in scope
+- stop and recommend Truth Structure when routing repair is unsafe, ambiguous, or outside the task boundary
+- keep feature README.md files as indexes rather than truth-document targets
+- create or update bounded leaf truth docs when behavior does not fit an existing leaf doc
+- write product capability/boundary truth under docs/truthmark/product when documenting product promise, boundary, rationale, or user/stakeholder value
+- write engineering truth under docs/truthmark/engineering when documenting implementation behavior, contracts, architecture, workflows, operations, or tests
+- for both-lane documentation requests, write separate product and engineering docs and cross-link them in route YAML with realized_by and realizes, not in doc frontmatter
+- keep engineering behavior truth behavior-oriented, not endpoint-oriented, unless the endpoint itself is the behavior boundary
+- keep API endpoint details in the nearest contract truth doc when such a doc owns the API contract
+- preserve unrelated authored content
+Truth-doc ownership review:
+- before editing or relying on the implemented behavior and candidate truth docs, verify each target/source truth doc is a bounded owner for the behavior
+- if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it
+- if the target doc is broad, mixed-owner, index-like, or the documented behavior spans independent owners, run Truth Structure first when safe and in scope; otherwise stop and recommend Truth Structure
+- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Manual handoff reason as applicable
+Decision/Rationale preservation review:
+- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions, Engineering Decisions, and Rationale sections in every source or touched truth doc
+- preserve each current decision and rationale in the correct product or engineering lane owner; when splitting, move it to the new owner doc rather than deleting it or leaving it in an index
+- remove or narrow a decision or rationale only when checkout evidence shows it is stale or unsupported, and report the exact claim, evidence, and result
+- if ownership of a decision or rationale is unclear, stop with manual-review files instead of deleting it or guessing
+- after the edit, verify every touched truth doc keeps lane-appropriate decision/rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked
+Evidence checklist:
+- route-first: map the documented behavior to bounded route owners and primary canonical docs
+- review new or changed behavior-bearing claims only in touched docs, route ownership, lane-specific decisions, and rationale
+- support claims with primary checkout evidence: implementation, config, routing, generated templates, schemas, or contract definitions
+- tests/examples/canonical docs corroborate; they are not sole proof when implementation conflicts
+- remove, narrow, or record unsupported claims for manual handoff
+- 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 WorkflowState/action context may guide routing, write boundaries, and verification planning when available.
+They do not override checkout evidence, canonical truth docs, route files, or workflow write boundaries.
+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 template under the configured Truthmark templates root.
+Supported kinds: product-capability, engineering-behavior, engineering-contract, engineering-architecture, engineering-workflow, engineering-operations, and engineering-test-behavior.
+Treat the HTML comments under each template section as normative authoring guidance for that section.
+Align existing docs to that template and write or repair section content so it satisfies the comment guidance while preserving accurate authored content.
+If the template is missing, use lane-specific sections: product truth says what must be true and why; engineering truth says how the repository currently realizes it.
+Teams may edit template files under the configured Truthmark templates root to define their local truth-doc standards.
+Truth-doc shape repair review:
+- Truth Document may restructure only truth docs for the implemented behavior being documented.
+- repair shape in place only after the ownership review confirms the doc is the right bounded owner
+- use Truth Structure for ownership splits; do not treat broad or mixed-owner docs as in-place repair work
+- repair shape when a narrow edit would make truth worse: missing template sections, stale evidence conflicts, cross-section updates within one owner, or wrong frontmatter/source/headings
+- preserve supported claims; remove, narrow, or record unsupported or stale claims for manual handoff
+- 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 hints:
+- Config, when present: .truthmark/config.yml
+- Root route index, when present: docs/truthmark/routes/areas.md
+- Area route files, when present: docs/truthmark/routes/areas/**/*.md
+- Product truth docs, when present: docs/truthmark/product/**/*.md
+- Engineering truth docs, when present: docs/truthmark/engineering/**/*.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.
+Product decisions belong in product truth; engineering, architecture, contract, workflow, and operational decisions belong in engineering truth.
+Helper status reporting:
+- Validate the report body before adding this validator's own success status; the body may omit `validate-document-report` while validation is pending.
+- After `truthmark validate document-report <report-file> --json` returns `data.validation.ok: true`, append or update `validate-document-report: ran, passed` in the final report.
+- If the installed Truthmark CLI is unavailable or the helper is skipped, record `validate-document-report: skipped, <reason>` 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.
+Parent post-document verification:
+- verify only truth docs and leased truth routing files changed during document work
+- stop on functional code, generated host surfaces, or unrelated diffs caused by document work
+- for each write lease, validate the worker report against the actual worker diff, allowedWrites, forbiddenWrites, identity fields, filesChanged, offLeaseChanges, blockers, and expected report fields before accepting it
+- verify the final report records ownership review, structure requirement, restructure, routing update, or manual handoff reason when applicable
@@ -0,0 +1,37 @@
+# Truthmark Document Report Template
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+Report completion in this shape:
+```md
+Truth Document: completed
+
+Implementation reviewed:
+- src/routing/area-resolver.ts
+
+Ownership reviewed:
+- docs/truthmark/routes/areas.md
+
+Truth docs created:
+- docs/truthmark/engineering/contracts/routing.md
+
+Truth docs updated:
+- docs/truthmark/engineering/behaviors/check-diagnostics.md
+
+Truth docs restructured:
+- docs/truthmark/engineering/behaviors/check-diagnostics.md
+
+Routing updated:
+- docs/truthmark/routes/areas.md
+
+Evidence checked:
+- Claim: Route resolution behavior is documented in the contracts truth doc.
+  Evidence: src/routing/area-resolver.ts:14 / docs/truthmark/routes/areas.md:9
+  Result: supported
+
+Helper scripts:
+- validate-write-lease: skipped, no write lease used
+
+Notes:
+- Documented routing and behavior from route handlers and tests.
+```
@@ -0,0 +1,14 @@
+# Truthmark Document Subagents And Leases
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+Gemini CLI subagent mode:
+- use automatically when this workflow runs in Gemini CLI and the parent agent chooses bounded project subagent fan-out
+- dispatch read-only project subagents for verification: @truth-route-auditor, @truth-claim-verifier
+- read-only subagents inspect checkout evidence directly, return structured findings, and must not edit files
+- parent supplies bounded evidence shards; read-only subagents must not preload host instruction files or repo-wide policy docs unless assigned as evidence
+- dispatch write-capable project subagents only with explicit write leases: @truth-doc-writer
+- each write lease must name objective, required reads, allowed writes, forbidden writes, evidence, verification, and report fields
+- write workers must stop when a required edit is off-lease and report status, filesChanged, evidence, offLeaseChanges, blockers, and notes
+- parent must inspect the actual checkout diff against each lease before accepting a worker report
+- Parent agent owns Truth Document acceptance, lease validation, and final report
@@ -0,0 +1,27 @@
+---
+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 Preview
+
+Use this skill only when the user explicitly asks to preview Truthmark routing or workflow choice before edits.
+
+Use as a Gemini CLI Agent Skill; commands remain available under `/truthmark:*` for command-first invocation.
+
+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 repository instruction files that exist in this checkout; do not assume any optional policy path exists.
+- Inspect .truthmark/config.yml and the root route index (docs/truthmark/routes/areas.md) first when present; then inspect only child route files under docs/truthmark/routes/areas/ that are relevant to the selected scope or changed paths, plus 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.
+- Hand off to the selected workflow after user approval.
+
+Progressive disclosure:
+- support/procedure.md — read before edits or detailed auditing; contains core review questions
+- support/report-template.md — read before the final report
+- support/subagents-and-leases.md — read only when using subagents, leases, or accepting worker output
@@ -0,0 +1,53 @@
+# Truthmark Preview Procedure
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+Use this skill only when the user explicitly asks to preview Truthmark routing or workflow choice before edits.
+
+Invocations: OpenCode /skill truthmark-preview; Codex /truthmark-preview or $truthmark-preview; Claude Code /truthmark-preview; GitHub Copilot /truthmark-preview; Gemini CLI /truthmark:preview.
+
+Truth Preview is read-only. Its report is intended, not authorized.
+
+Purpose:
+- preview the likely Truthmark workflow, route owner, target files, expected write classes, suggested subagent use, and manual handoff questions before edits happen
+- report likely product lane impact, engineering lane impact, target docs, and ambiguity before edits
+- hand off to the selected workflow after user approval
+- keep the selector thin so agents can avoid loading or acting through heavier workflows prematurely
+
+Read:
+- .truthmark/config.yml, only when present
+- docs/truthmark/routes/areas.md, first, only when present
+- relevant child route files under docs/truthmark/routes/areas/ for the selected scope or changed paths, only when present
+- relevant truth docs and implementation files needed to preview ownership
+- Evidence 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.
+- Lane classification:
+  - classify the request or changed surface as product-lane, engineering-lane, both-lane, or ambiguous for reporting only
+  - product-lane ownership belongs under docs/truthmark/product and describes product promises, boundaries, rationale, decisions, and success criteria
+  - engineering-lane ownership belongs under docs/truthmark/engineering and describes source-backed current realization, contracts, architecture, workflows, operations, or tests
+  - both-lane ownership uses separate product and engineering docs cross-linked in route YAML with realized_by and realizes, not in doc frontmatter
+  - ambiguous lane ownership should be reported for manual handoff or routed to Truth Structure
+  - Do not make product docs a summary of engineering docs. Do not make engineering docs a detailed version of product docs. Product truth says what must be true and why. Engineering truth says how the repository currently realizes it.
+
+Do not:
+- must not edit files
+- must not create truth docs
+- must not update routing
+- must not run Truth Sync automatically
+- must not replace Truth Check
+- must not claim final correctness
+- must not issue write leases
+- must not mutate code
+
+Suggested subagent use:
+- optional read-only verifier: truth_route_auditor
+- write workers: none
+- leases needed: none
+
+Truthmark hierarchy hints:
+- Config, when present: .truthmark/config.yml
+- Root route index, when present: docs/truthmark/routes/areas.md
+- Area route files, when present: docs/truthmark/routes/areas/**/*.md
+- Product truth docs, when present: docs/truthmark/product/**/*.md
+- Engineering truth docs, when present: docs/truthmark/engineering/**/*.md
@@ -0,0 +1,43 @@
+# Truthmark Preview Report Template
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+Report completion in this shape:
+```md
+Truth Preview: completed
+
+Requested outcome:
+- preview likely Truthmark workflow routing before edits
+
+Likely workflow:
+- truthmark-document
+
+Why this workflow:
+- positive trigger: document existing implemented behavior
+- negative triggers considered: functional-code change, doc-first implementation, topology repair, truth audit
+- forbidden adjacency considered: must not edit functional code
+
+Likely route owner:
+- route file: docs/truthmark/routes/areas.md
+- likely lane impact: engineering-lane
+- product target docs: none identified
+- engineering target docs: docs/truthmark/engineering/behaviors/example.md
+- confidence: medium
+
+Expected write classes:
+- truth docs
+
+Expected target files:
+- docs/truthmark/engineering/behaviors/example.md
+
+Suggested subagent use:
+- read-only verifiers: truth_route_auditor
+- write workers: none in Preview
+- leases needed: none in Preview
+
+Manual handoff questions:
+- none identified in preview
+
+Handoff:
+- Run the selected Truthmark workflow after user approval.
+```
@@ -0,0 +1,10 @@
+# Truthmark Preview Subagents And Leases
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+Gemini CLI subagent mode:
+- use automatically when this workflow runs in Gemini CLI and the parent agent chooses bounded project subagent fan-out
+- dispatch read-only project subagents only: @truth-route-auditor
+- subagents inspect checkout evidence directly, return structured findings, and must not edit files
+- parent supplies bounded evidence shards; subagents must not preload host instruction files or repo-wide policy docs unless assigned as evidence
+- Parent agent owns the final Truth Preview report
@@ -0,0 +1,26 @@
+---
+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 Realize
+
+Use this skill only when the user explicitly asks to realize truth docs into code.
+
+Use as a Gemini CLI Agent Skill; commands remain available under `/truthmark:*` for command-first invocation.
+
+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 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/routes/areas.md; docs/truthmark/routes/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.
+- Read support/report-template.md before the final report.
+
+Progressive disclosure:
+- support/procedure.md — read before edits or detailed auditing; contains core review questions
+- support/report-template.md — read before the final report
@@ -0,0 +1,43 @@
+# Truthmark Realize Procedure
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+# Truthmark Realize
+
+Use this skill only when the user explicitly asks to realize truth docs into code.
+
+Invocations: OpenCode /skill truthmark-realize; Codex /truthmark-realize or $truthmark-realize; Claude Code /truthmark-realize; GitHub Copilot /truthmark-realize; Gemini CLI /truthmark:realize.
+
+Truth Realize is doc-first:
+
+- truth docs lead
+- code follows
+- Truth Realize never edits the truth docs it is realizing
+
+Workflow:
+
+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/routes/areas.md; docs/truthmark/routes/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 review:
+- before editing or relying on source truth docs before writing code, verify each target/source truth doc is a bounded owner for the behavior
+- if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it
+- if a source truth doc is broad, mixed-owner, index-like, unrouteable, stale, or conflicts with implementation evidence, stop before writing code and recommend Truth Structure or Truth Document
+- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Manual handoff reason as applicable
+4. Update functional code only so implementation matches bounded, current truth claims from the source docs.
+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 hints:
+- Config, when present: .truthmark/config.yml
+- Root route index, when present: docs/truthmark/routes/areas.md
+- Area route files, when present: docs/truthmark/routes/areas/**/*.md
+- Product truth docs, when present: docs/truthmark/product/**/*.md
+- Engineering truth docs, when present: docs/truthmark/engineering/**/*.md
+
+Read and write boundaries:
+
+- may read truth docs, routing docs, and relevant functional code
+- may write functional code only
+- must not edit truth docs or truth routing while realizing those docs
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Merlin's Cat GitHub MerlinH	fb2c469005	feat: add canonical agent workflow package (#19 ) * feat: add Truth Sync intent checklist * feat: add canonical agent workflow package Add the .truthmark/agent canonical workflow package, convert duplicated host workflow bodies into adapter/expanded-adapter surfaces, and validate canonical/adapter freshness in Truthmark check. Refresh generated surfaces and package metadata for Truthmark 2.3.0, with OpenSpec tasks completed and release notes added. * fix: preserve native workflow skill packages * docs: record native skill package decision * fix: drop unused agent workflow package * chore: remove implemented OpenSpec docs * chore: release workflow fixes as 2.2.2 * fix: remove agent-visible version markers * fix: drop generated surface version markers * feat: capture decision context in Truth Sync --------- Co-authored-by: MerlinH <merlinh221@gmail.com>	2026-06-18 17:07:40 +10:00
Merlin's Cat GitHub MerlinH	e9cd67f0b5	refactor: remove semantic repository index (#17 ) * docs: replace legacy truth path references * feat: fold contextpack into workflow status * refactor: remove semantic repository index * fix: remove vulnerable frontmatter dependency * feat: broaden truth sync write authorization * test: restore workflow state regression coverage --------- Co-authored-by: MerlinH <merlinh221@gmail.com>	2026-06-16 11:03:04 +10:00
Merlin's Cat GitHub MerlinH	32cfafa9c2	chore: refresh npm dependencies (#16 ) Co-authored-by: MerlinH <merlinh221@gmail.com>	2026-06-16 00:55:23 +10:00
Merlin's Cat GitHub MerlinH	2dc0da40ff	chore: refresh Truthmark to 2.2.0 (#15 ) * Split Truthmark product and engineering truth lanes * chore: align truthmark docs and runtime with lane updates * chore: bump package version to 2.2.0 * chore: refresh truthmark surfaces for 2.2.0 and document release * chore: migrate legacy truth docs to engineering legacy path * chore: remove legacy docs/truth legacy docs from repository * chore: trim document command prompts to adapter stubs * chore: customize truth root README guidance per lane * chore: make doc reviewer guidance lane-specific and helper-rendered * fix: remove duplicate check lane-classification render in evidence gate * fix: make realize doc example lane-agnostic to product and engineering * feat: separate product and engineering truth lanes * test: restore workflow surface coverage * Fix workflow lane prompt boundaries * test: guard read-only generated surface wording * Fix manual Realize lane guidance * fix: harden route relationship diagnostics Validate reciprocal product and engineering route links, gate missing product-link review diagnostics on product evidence, and reject duplicate route entries with divergent relationship metadata. * fix: merge duplicate route relationships Allow repeated route entries for the same truth document, kind, and lane to contribute additive relationship metadata. Keep hard validation errors for kind and lane conflicts and emit merged relationships in RouteMap output. * fix: make route relationships local Treat realized_by and realizes metadata as route-local navigation edges. Validate target existence and lane compatibility without requiring reciprocal declarations, and document the chosen semantics. --------- Co-authored-by: MerlinH <merlinh221@gmail.com>	2026-06-16 00:54:46 +10:00
Merlin's Cat GitHub MerlinH	7e68f5d216	docs: polish localized READMEs (#14 ) * docs: polish localized readmes * docs: remove stale future and research notes --------- Co-authored-by: MerlinH <merlinh221@gmail.com>	2026-06-13 05:02:17 +10:00
Merlin's Cat GitHub MerlinH	a083b703fa	feat: add Truthmark health scorecard and bounded workflow contracts (#13 ) * feat: add OpenSpec-driven workflow state * docs: plan generated playbooks workflow contract * feat: add truth health scorecard Release Truthmark 2.1.0 with check JSON scorecard output. Archive the completed OpenSpec pass 4 scorecard change and update generated truth surfaces. * fix: unblock truthmark scorecard review - restore and update coverage for scorecard/evidence/workflow behavior - make truthmark-sync select a cheap local base when --base is omitted - report malformed evidence YAML blocks as diagnostics instead of throwing * fix: tighten workflow boundaries * fix: fail closed when sync has no comparison base * fix: tighten truth health review coverage - only parse fenced YAML evidence blocks with top-level evidence markers - convert coverage fixtures to valid v2 config and assert non-vacuous diagnostics - update Truthmark truth docs for source traceability and workflow-state tests * docs: clarify source traceability diagnostics * docs: harden optional CLI workflow boundary * docs: clarify product boundary is repo-local * fix: bound truthmark workflow fallback behavior - make live workflow preflight use the one-call instructions contract - keep missing-CLI fallback bounded for Sync, Document, Structure, and Realize - add routing and generated-surface coverage plus refreshed host surfaces * test: cover no-cli workflow fallback bounds - assert route-first fallback wording in generated workflow surfaces - clarify progressive-disclosure support files are conditional - align overview docs with bounded no-CLI behavior * docs: route workflow eval coverage * fix: remove workflow instructions preflight * fix: remove stale workflow preflight wording * fix: remove generic workflow validation blocks * fix: avoid duplicated markdown context JSON * fix: keep workflow status manifest-only * docs: align truth docs with v2 hierarchy --------- Co-authored-by: MerlinH <merlinh221@gmail.com>	2026-06-13 04:09:45 +10:00
Merlin's Cat GitHub MerlinH	aa6442bba9	docs: align truth docs with templates (#12 ) * docs: align truth docs with templates * docs: clarify truth template comment guidance --------- Co-authored-by: MerlinH <merlinh221@gmail.com>	2026-05-31 22:56:16 +10:00
Merlin's Cat GitHub MerlinH	9e330a0fd3	fix(cli): fail on error diagnostics (#11 ) * fix(cli): fail on error diagnostics * chore: release 1.6.1 * feat(init): refresh truth doc templates * fix(init): preserve custom template preambles * ci: limit GitHub token permissions * ci: update setup-node action --------- Co-authored-by: MerlinH <merlinh221@gmail.com>	2026-05-31 00:35:18 +10:00
Merlin's Cat GitHub MerlinH	e5a586a420	chore: prune unused Truthmark surfaces (#10 ) Co-authored-by: MerlinH <merlinh221@gmail.com>	2026-05-28 22:12:15 +10:00
Merlin's Cat GitHub MerlinH	fcfd5f7adc	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 <merlinh221@gmail.com>	2026-05-28 14:39:21 +10:00
Merlin's Cat GitHub Hermes Agent	17ed1599a3	feat: add workflow helper validators and host-native surfaces (#7 ) * 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 --------- Co-authored-by: Hermes Agent <hermes-agent@users.noreply.github.com>	2026-05-20 11:15:24 +10:00
MerlinH	cc11b8e26c	(doc): readme enrichment	2026-05-17 01:06:41 +10:00
MerlinHandGitHub	403637022c	Workflow Verifier And Writer Agents v1.4.0 (#5 ) * feat(workflows): add verifier agent surfaces Generate project-scoped read-only verifier agents for Codex, Claude Code, GitHub Copilot, and OpenCode. Wire workflow manifests, generated surfaces, init diagnostics, sync classification, docs, and tests through the new subagent contract. * feat(workflows): add leased truth doc writer agents Add write-capable truth-doc-writer generated surfaces for Codex, Claude, Copilot, and OpenCode, guarded by explicit write leases. Tighten Truth Sync and Truth Document subagent contracts so parents validate leases, changed files, and worker reports before accepting doc updates. * feat(workflows): add Truth Preview and workflow support files Add the explicit read-only Truth Preview workflow across the manifest, generated host surfaces, docs, and tests. Move generated skill hosts to compact SKILL.md entrypoints with support procedure, report, and lease files, and add write-worker report acceptance validation against actual lease diffs.	2026-05-16 22:26:28 +10:00
MerlinHandGitHub	233bb61cb6	1.3.0 clis and index (#4 )	2026-05-16 03:55:55 +10:00
MerlinHandGitHub	caced773f5	1.2.4 strengthen truth workflow ownership and evidence gates (#3 ) * refactor(truthmark): parameterize truth agent paths with routing config * 1.2.4 truth flow research * Context and workflow optimization	2026-05-15 08:58:31 +10:00