mirror of
https://github.com/merlinhu1/truthmark.git
synced 2026-08-25 07:53:25 +02:00
Compare commits
1
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
fb2c469005 |
@@ -3,7 +3,6 @@ name: truthmark-check
|
||||
description: Use when the user asks to audit repository truth health, routing, ownership, or canonical docs. Not for normal lint/test/typecheck/code-review verification, finish-time Sync, or silently rewriting docs.
|
||||
argument-hint: Optional area, doc path, or audit focus
|
||||
user-invocable: true
|
||||
truthmark-version: 2.2.1
|
||||
---
|
||||
|
||||
# Truthmark Check
|
||||
@@ -21,6 +20,6 @@ Quick procedure:
|
||||
- Read support/report-template.md before the final report.
|
||||
|
||||
Progressive disclosure:
|
||||
- support/procedure.md — read before edits or detailed auditing; contains core quality gates
|
||||
- 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: "2.2.1"
|
||||
refresh_command: "truthmark init"
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Truthmark Check Procedure
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
# Truthmark Check
|
||||
|
||||
@@ -20,7 +20,7 @@ Truth Check is agent-led:
|
||||
- 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 as blocked or routed to Truth Structure
|
||||
- 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:
|
||||
@@ -40,7 +40,7 @@ Truth Check is agent-led:
|
||||
- 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 Gate:
|
||||
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
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Truthmark Check Report Template
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Report completion in this shape:
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Truthmark Check Subagents And Leases
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
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
|
||||
|
||||
@@ -3,7 +3,6 @@ name: truthmark-document
|
||||
description: Use when the user asks to document existing implemented behavior, or Sync, Check, or Structure finds implemented behavior missing canonical truth. Not for functional-code changes, doc-first implementation, or topology repair that needs Structure.
|
||||
argument-hint: Optional implemented behavior, API endpoint, route, controller, package, or truth-doc area to document
|
||||
user-invocable: true
|
||||
truthmark-version: 2.2.1
|
||||
---
|
||||
|
||||
# Truthmark Document
|
||||
@@ -22,7 +21,7 @@ Quick procedure:
|
||||
- Read support/report-template.md before the final report.
|
||||
|
||||
Progressive disclosure:
|
||||
- support/procedure.md — read before edits or detailed auditing; contains core quality gates
|
||||
- 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
|
||||
|
||||
@@ -7,5 +7,4 @@ policy:
|
||||
allow_implicit_invocation: false
|
||||
|
||||
truthmark:
|
||||
version: "2.2.1"
|
||||
refresh_command: "truthmark init"
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
# Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
helpers:
|
||||
validate-document-report:
|
||||
optional: true
|
||||
runner: truthmark>=2.2.1
|
||||
runner: truthmark
|
||||
command:
|
||||
argv:
|
||||
- truthmark
|
||||
@@ -17,7 +17,7 @@ helpers:
|
||||
fallback: manually validate support/report-template.md required sections and structured Evidence checked entries
|
||||
validate-write-lease:
|
||||
optional: true
|
||||
runner: truthmark>=2.2.1
|
||||
runner: truthmark
|
||||
command:
|
||||
argv:
|
||||
- truthmark
|
||||
|
||||
@@ -1,18 +1,18 @@
|
||||
# Optional Helper CLI Policy
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
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 too old for a declared helper, continue manually using this procedure and report which helper was skipped. Helper output is derived evidence; it does not override direct checkout inspection, workflow write boundaries, or parent acceptance.
|
||||
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 the declared Truthmark CLI runner before invoking a helper.
|
||||
- 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 or version-mismatched, treat the helper as skipped and use the manual fallback.
|
||||
- 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>=2.2.1; manual fallback: manually validate support/report-template.md required sections and structured Evidence checked entries
|
||||
- validate-write-lease: optional truthmark>=2.2.1; manual fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files
|
||||
- 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:
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Truthmark Document Procedure
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
# Truthmark Document
|
||||
|
||||
@@ -19,13 +19,13 @@ Truth Document is manual and implementation-first:
|
||||
- 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 block or invoke Truth Structure instead of writing a mixed document
|
||||
- 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
|
||||
- block and recommend Truth Structure when routing repair is unsafe, ambiguous, or outside the task boundary
|
||||
- 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
|
||||
@@ -34,23 +34,23 @@ Truth Document is manual and implementation-first:
|
||||
- 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 gate:
|
||||
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 block and recommend Truth Structure
|
||||
- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Blocked reason as applicable
|
||||
Decision/Rationale preservation gate:
|
||||
- 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, block with manual-review files instead of deleting it or guessing
|
||||
- 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 Gate:
|
||||
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 block unsupported claims
|
||||
- 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.
|
||||
@@ -61,12 +61,12 @@ Treat the HTML comments under each template section as normative authoring guida
|
||||
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 gate:
|
||||
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 gate confirms the doc is the right bounded owner
|
||||
- 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 block unsupported or stale claims
|
||||
- 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.
|
||||
@@ -87,6 +87,6 @@ Helper status reporting:
|
||||
- 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
|
||||
- block 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 required report fields before accepting it
|
||||
- verify the final report records ownership review, structure requirement, restructure, routing update, or blocked reason when applicable
|
||||
- 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
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Truthmark Document Report Template
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Report completion in this shape:
|
||||
```md
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Truthmark Document Subagents And Leases
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
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
|
||||
|
||||
@@ -3,7 +3,6 @@ name: truthmark-preview
|
||||
description: Use when the user explicitly asks to preview likely workflow routing, target files, writes, or subagent use before edits. Not for validation, automatic gates, final correctness, or replacing Truth Check.
|
||||
argument-hint: Optional requested outcome, code area, doc path, or routing question
|
||||
user-invocable: true
|
||||
truthmark-version: 2.2.1
|
||||
---
|
||||
|
||||
# Truthmark Preview
|
||||
@@ -21,6 +20,6 @@ Quick procedure:
|
||||
- Hand off to the selected workflow after user approval.
|
||||
|
||||
Progressive disclosure:
|
||||
- support/procedure.md — read before edits or detailed auditing; contains core quality gates
|
||||
- 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: "2.2.1"
|
||||
refresh_command: "truthmark init"
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Truthmark Preview Procedure
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
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.
|
||||
|
||||
@@ -9,7 +9,7 @@ Invocations: OpenCode /skill truthmark-preview; Codex /truthmark-preview or $tru
|
||||
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 blocking ambiguity before edits happen
|
||||
- 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
|
||||
@@ -27,7 +27,7 @@ Read:
|
||||
- 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 as blocked or routed to Truth Structure
|
||||
- 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:
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Truthmark Preview Report Template
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Report completion in this shape:
|
||||
```md
|
||||
@@ -35,7 +35,7 @@ Suggested subagent use:
|
||||
- write workers: none in Preview
|
||||
- leases needed: none in Preview
|
||||
|
||||
Blocking ambiguity:
|
||||
Manual handoff questions:
|
||||
- none identified in preview
|
||||
|
||||
Handoff:
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Truthmark Preview Subagents And Leases
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
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
|
||||
|
||||
@@ -3,7 +3,6 @@ name: truthmark-realize
|
||||
description: Use when the user explicitly asks to realize Truthmark truth docs into code, including /truthmark-realize, $truthmark-realize, or /truthmark:realize. Not for syncing docs after code changes, documenting existing code, topology repair, or truth audits.
|
||||
argument-hint: Optional truth doc path, area, or desired code behavior to realize
|
||||
user-invocable: true
|
||||
truthmark-version: 2.2.1
|
||||
---
|
||||
|
||||
# Truthmark Realize
|
||||
@@ -21,5 +20,5 @@ Quick procedure:
|
||||
- Read support/report-template.md before the final report.
|
||||
|
||||
Progressive disclosure:
|
||||
- support/procedure.md — read before edits or detailed auditing; contains core quality gates
|
||||
- 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: "2.2.1"
|
||||
refresh_command: "truthmark init"
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Truthmark Realize Procedure
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
# Truthmark Realize
|
||||
|
||||
@@ -20,11 +20,11 @@ Workflow:
|
||||
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 gate:
|
||||
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, block before writing code and recommend Truth Structure or Truth Document
|
||||
- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Blocked reason as applicable
|
||||
- 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.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Truthmark Realize Report Template
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Report completion in this shape:
|
||||
|
||||
|
||||
@@ -3,7 +3,6 @@ name: truthmark-structure
|
||||
description: Use when routing or truth ownership is missing, stale, broad, overloaded, catch-all, unrouteable, mixed-owner, needs split/repair, or needs new area setup. Not for documenting implemented behavior, syncing a code diff, or realizing docs into code.
|
||||
argument-hint: Optional area, directory, or routing concern
|
||||
user-invocable: true
|
||||
truthmark-version: 2.2.1
|
||||
---
|
||||
|
||||
# Truthmark Structure
|
||||
@@ -21,6 +20,6 @@ Quick procedure:
|
||||
- Read support/report-template.md before the final report.
|
||||
|
||||
Progressive disclosure:
|
||||
- support/procedure.md — read before edits or detailed auditing; contains core quality gates
|
||||
- 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: "2.2.1"
|
||||
refresh_command: "truthmark init"
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Truthmark Structure Procedure
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
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.
|
||||
@@ -14,7 +14,7 @@ Truth Structure is agent-native:
|
||||
- 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 block or invoke Truth Structure instead of writing a mixed document
|
||||
- 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
|
||||
@@ -39,7 +39,7 @@ Use when a user asks to onboard a new code area into Truthmark, a new package, c
|
||||
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 block for review
|
||||
- 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
|
||||
@@ -53,16 +53,16 @@ Do not:
|
||||
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 gate:
|
||||
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 block with manual-review files
|
||||
- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Blocked reason as applicable
|
||||
Decision/Rationale preservation gate:
|
||||
- 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, block with manual-review files instead of deleting it or guessing
|
||||
- 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/**
|
||||
@@ -90,17 +90,17 @@ Repair rules:
|
||||
- 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 gate:
|
||||
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 gate confirms the doc is the right bounded owner
|
||||
- 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 block unsupported or stale claims
|
||||
- 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 Gate:
|
||||
- apply the Evidence Gate before finishing when Truth Structure writes routed docs, ownership claims, lane-specific decisions, or rationale
|
||||
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 block unsupported claims
|
||||
- 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.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Truthmark Structure Report Template
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Report completion in this shape:
|
||||
```md
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Truthmark Structure Subagents And Leases
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
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
|
||||
|
||||
@@ -3,7 +3,6 @@ name: truthmark-sync
|
||||
description: Use automatically at finish-time after functional code changes, or explicit /truthmark-sync, $truthmark-sync, or /truthmark:sync. Skip docs-only, formatting-only, behavior-preserving renames, missing config, and no-code changes. Not for doc-first realization or manual topology design.
|
||||
argument-hint: Optional changed-code area, truth-doc area, or sync focus
|
||||
user-invocable: true
|
||||
truthmark-version: 2.2.1
|
||||
---
|
||||
|
||||
# Truthmark Sync
|
||||
@@ -23,7 +22,7 @@ Quick procedure:
|
||||
- Read support/report-template.md before the final report.
|
||||
|
||||
Progressive disclosure:
|
||||
- support/procedure.md — read before edits or detailed auditing; contains core quality gates
|
||||
- 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
|
||||
|
||||
@@ -7,5 +7,4 @@ policy:
|
||||
allow_implicit_invocation: true
|
||||
|
||||
truthmark:
|
||||
version: "2.2.1"
|
||||
refresh_command: "truthmark init"
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
# Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
helpers:
|
||||
validate-sync-report:
|
||||
optional: true
|
||||
runner: truthmark>=2.2.1
|
||||
runner: truthmark
|
||||
command:
|
||||
argv:
|
||||
- truthmark
|
||||
@@ -17,7 +17,7 @@ helpers:
|
||||
fallback: "manually validate support/report-template.md and check Evidence checked entries match Claim, indented Evidence, and Result: supported | narrowed | removed | blocked"
|
||||
validate-write-lease:
|
||||
optional: true
|
||||
runner: truthmark>=2.2.1
|
||||
runner: truthmark
|
||||
command:
|
||||
argv:
|
||||
- truthmark
|
||||
|
||||
@@ -1,18 +1,18 @@
|
||||
# Optional Helper CLI Policy
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
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 too old for a declared helper, continue manually using this procedure and report which helper was skipped. Helper output is derived evidence; it does not override direct checkout inspection, workflow write boundaries, or parent acceptance.
|
||||
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 the declared Truthmark CLI runner before invoking a helper.
|
||||
- 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 or version-mismatched, treat the helper as skipped and use the manual fallback.
|
||||
- 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>=2.2.1; 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>=2.2.1; manual fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files
|
||||
- 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:
|
||||
|
||||
|
||||
@@ -1,10 +1,10 @@
|
||||
# Truthmark Sync Procedure
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
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 reopen the finish-time requirement, and an earlier explicit run satisfies the finish gate only if no later functional-code changes occur.
|
||||
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.
|
||||
@@ -13,36 +13,46 @@ Parent workflow:
|
||||
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. Lane classification gate:
|
||||
- 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 block 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.
|
||||
6. Update engineering truth first after code changes. Update product truth only when implemented user-visible product promise or capability boundary changed and explicit source/user evidence supports it; otherwise report product-lane review needed.
|
||||
7. Code verification is parent-owned: follow repository instructions and task context, and report what ran or why it did not run.
|
||||
8. 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.
|
||||
Topology quality gate:
|
||||
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
|
||||
- block and recommend Truth Structure when topology repair is unsafe, ambiguous, or outside the current task boundary
|
||||
- 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 gate:
|
||||
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 block and recommend Truth Structure
|
||||
- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Blocked reason as applicable
|
||||
Decision/Rationale preservation gate:
|
||||
- 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, block with manual-review files instead of deleting it or guessing
|
||||
- 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.
|
||||
@@ -50,21 +60,21 @@ Treat the HTML comments under each template section as normative authoring guida
|
||||
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 gate:
|
||||
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 gate confirms the doc is the right bounded owner
|
||||
- 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 block unsupported or stale claims
|
||||
- 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 Gate:
|
||||
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 block unsupported claims
|
||||
- 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.
|
||||
@@ -91,10 +101,10 @@ Do not create separate active-decision ADR/planning logs; replace the active dec
|
||||
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
|
||||
- block on any unrelated diff caused by the sync step
|
||||
- block 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 required report fields before accepting it
|
||||
- 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 blocked reason when the ownership gate fired
|
||||
- blocked outcomes must preserve the working tree as-is: no rollback, no post-block cleanup edits, and manual-review reporting of any remaining files
|
||||
- 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
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Truthmark Sync Report Template
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Report completion in this shape:
|
||||
```md
|
||||
@@ -9,11 +9,24 @@ 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/overview.md
|
||||
- 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.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Truthmark Sync Subagents And Leases
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
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
|
||||
|
||||
@@ -4,7 +4,7 @@ description: Read-only Truthmark claim verifier for checking canonical truth aga
|
||||
tools: Read, Grep, Glob, LS
|
||||
---
|
||||
|
||||
# Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Manual invocation: use the truth-claim-verifier subagent.
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ description: Read-only Truthmark doc reviewer for shape, decision, rationale, an
|
||||
tools: Read, Grep, Glob, LS
|
||||
---
|
||||
|
||||
# Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Manual invocation: use the truth-doc-reviewer subagent.
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ description: Write-capable Truthmark doc worker for one parent-leased truth-docu
|
||||
tools: Read, Grep, Glob, LS, Edit, MultiEdit
|
||||
---
|
||||
|
||||
# Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
# 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.
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ description: Read-only Truthmark route auditor for bounded routing and ownership
|
||||
tools: Read, Grep, Glob, LS
|
||||
---
|
||||
|
||||
# Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Manual invocation: use the truth-route-auditor subagent.
|
||||
|
||||
|
||||
@@ -3,7 +3,6 @@ name: truthmark-check
|
||||
description: Use when the user asks to audit repository truth health, routing, ownership, or canonical docs. Not for normal lint/test/typecheck/code-review verification, finish-time Sync, or silently rewriting docs.
|
||||
argument-hint: Optional area, doc path, or audit focus
|
||||
user-invocable: true
|
||||
truthmark-version: 2.2.1
|
||||
---
|
||||
|
||||
# Truthmark Check
|
||||
@@ -21,6 +20,6 @@ Quick procedure:
|
||||
- Read support/report-template.md before the final report.
|
||||
|
||||
Progressive disclosure:
|
||||
- support/procedure.md — read before edits or detailed auditing; contains core quality gates
|
||||
- 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
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Truthmark Check Procedure
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
# Truthmark Check
|
||||
|
||||
@@ -20,7 +20,7 @@ Truth Check is agent-led:
|
||||
- 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 as blocked or routed to Truth Structure
|
||||
- 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:
|
||||
@@ -40,7 +40,7 @@ Truth Check is agent-led:
|
||||
- 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 Gate:
|
||||
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
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Truthmark Check Report Template
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Report completion in this shape:
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Truthmark Check Subagents And Leases
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
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
|
||||
|
||||
@@ -3,7 +3,6 @@ name: truthmark-document
|
||||
description: Use when the user asks to document existing implemented behavior, or Sync, Check, or Structure finds implemented behavior missing canonical truth. Not for functional-code changes, doc-first implementation, or topology repair that needs Structure.
|
||||
argument-hint: Optional implemented behavior, API endpoint, route, controller, package, or truth-doc area to document
|
||||
user-invocable: true
|
||||
truthmark-version: 2.2.1
|
||||
---
|
||||
|
||||
# Truthmark Document
|
||||
@@ -22,7 +21,7 @@ Quick procedure:
|
||||
- Read support/report-template.md before the final report.
|
||||
|
||||
Progressive disclosure:
|
||||
- support/procedure.md — read before edits or detailed auditing; contains core quality gates
|
||||
- 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
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
# Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
helpers:
|
||||
validate-document-report:
|
||||
optional: true
|
||||
runner: truthmark>=2.2.1
|
||||
runner: truthmark
|
||||
command:
|
||||
argv:
|
||||
- truthmark
|
||||
@@ -17,7 +17,7 @@ helpers:
|
||||
fallback: manually validate support/report-template.md required sections and structured Evidence checked entries
|
||||
validate-write-lease:
|
||||
optional: true
|
||||
runner: truthmark>=2.2.1
|
||||
runner: truthmark
|
||||
command:
|
||||
argv:
|
||||
- truthmark
|
||||
|
||||
@@ -1,18 +1,18 @@
|
||||
# Optional Helper CLI Policy
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
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 too old for a declared helper, continue manually using this procedure and report which helper was skipped. Helper output is derived evidence; it does not override direct checkout inspection, workflow write boundaries, or parent acceptance.
|
||||
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 the declared Truthmark CLI runner before invoking a helper.
|
||||
- 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 or version-mismatched, treat the helper as skipped and use the manual fallback.
|
||||
- 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>=2.2.1; manual fallback: manually validate support/report-template.md required sections and structured Evidence checked entries
|
||||
- validate-write-lease: optional truthmark>=2.2.1; manual fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files
|
||||
- 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:
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Truthmark Document Procedure
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
# Truthmark Document
|
||||
|
||||
@@ -19,13 +19,13 @@ Truth Document is manual and implementation-first:
|
||||
- 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 block or invoke Truth Structure instead of writing a mixed document
|
||||
- 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
|
||||
- block and recommend Truth Structure when routing repair is unsafe, ambiguous, or outside the task boundary
|
||||
- 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
|
||||
@@ -34,23 +34,23 @@ Truth Document is manual and implementation-first:
|
||||
- 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 gate:
|
||||
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 block and recommend Truth Structure
|
||||
- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Blocked reason as applicable
|
||||
Decision/Rationale preservation gate:
|
||||
- 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, block with manual-review files instead of deleting it or guessing
|
||||
- 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 Gate:
|
||||
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 block unsupported claims
|
||||
- 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.
|
||||
@@ -61,12 +61,12 @@ Treat the HTML comments under each template section as normative authoring guida
|
||||
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 gate:
|
||||
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 gate confirms the doc is the right bounded owner
|
||||
- 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 block unsupported or stale claims
|
||||
- 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.
|
||||
@@ -87,6 +87,6 @@ Helper status reporting:
|
||||
- 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
|
||||
- block 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 required report fields before accepting it
|
||||
- verify the final report records ownership review, structure requirement, restructure, routing update, or blocked reason when applicable
|
||||
- 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
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Truthmark Document Report Template
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Report completion in this shape:
|
||||
```md
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Truthmark Document Subagents And Leases
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
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
|
||||
|
||||
@@ -3,7 +3,6 @@ name: truthmark-preview
|
||||
description: Use when the user explicitly asks to preview likely workflow routing, target files, writes, or subagent use before edits. Not for validation, automatic gates, final correctness, or replacing Truth Check.
|
||||
argument-hint: Optional requested outcome, code area, doc path, or routing question
|
||||
user-invocable: true
|
||||
truthmark-version: 2.2.1
|
||||
---
|
||||
|
||||
# Truthmark Preview
|
||||
@@ -21,6 +20,6 @@ Quick procedure:
|
||||
- Hand off to the selected workflow after user approval.
|
||||
|
||||
Progressive disclosure:
|
||||
- support/procedure.md — read before edits or detailed auditing; contains core quality gates
|
||||
- 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
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Truthmark Preview Procedure
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
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.
|
||||
|
||||
@@ -9,7 +9,7 @@ Invocations: OpenCode /skill truthmark-preview; Codex /truthmark-preview or $tru
|
||||
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 blocking ambiguity before edits happen
|
||||
- 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
|
||||
@@ -27,7 +27,7 @@ Read:
|
||||
- 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 as blocked or routed to Truth Structure
|
||||
- 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:
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Truthmark Preview Report Template
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Report completion in this shape:
|
||||
```md
|
||||
@@ -35,7 +35,7 @@ Suggested subagent use:
|
||||
- write workers: none in Preview
|
||||
- leases needed: none in Preview
|
||||
|
||||
Blocking ambiguity:
|
||||
Manual handoff questions:
|
||||
- none identified in preview
|
||||
|
||||
Handoff:
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Truthmark Preview Subagents And Leases
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
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
|
||||
|
||||
@@ -3,7 +3,6 @@ name: truthmark-realize
|
||||
description: Use when the user explicitly asks to realize Truthmark truth docs into code, including /truthmark-realize, $truthmark-realize, or /truthmark:realize. Not for syncing docs after code changes, documenting existing code, topology repair, or truth audits.
|
||||
argument-hint: Optional truth doc path, area, or desired code behavior to realize
|
||||
user-invocable: true
|
||||
truthmark-version: 2.2.1
|
||||
---
|
||||
|
||||
# Truthmark Realize
|
||||
@@ -21,5 +20,5 @@ Quick procedure:
|
||||
- Read support/report-template.md before the final report.
|
||||
|
||||
Progressive disclosure:
|
||||
- support/procedure.md — read before edits or detailed auditing; contains core quality gates
|
||||
- support/procedure.md — read before edits or detailed auditing; contains core review questions
|
||||
- support/report-template.md — read before the final report
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Truthmark Realize Procedure
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
# Truthmark Realize
|
||||
|
||||
@@ -20,11 +20,11 @@ Workflow:
|
||||
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 gate:
|
||||
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, block before writing code and recommend Truth Structure or Truth Document
|
||||
- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Blocked reason as applicable
|
||||
- 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.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Truthmark Realize Report Template
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Report completion in this shape:
|
||||
|
||||
|
||||
@@ -3,7 +3,6 @@ name: truthmark-structure
|
||||
description: Use when routing or truth ownership is missing, stale, broad, overloaded, catch-all, unrouteable, mixed-owner, needs split/repair, or needs new area setup. Not for documenting implemented behavior, syncing a code diff, or realizing docs into code.
|
||||
argument-hint: Optional area, directory, or routing concern
|
||||
user-invocable: true
|
||||
truthmark-version: 2.2.1
|
||||
---
|
||||
|
||||
# Truthmark Structure
|
||||
@@ -21,6 +20,6 @@ Quick procedure:
|
||||
- Read support/report-template.md before the final report.
|
||||
|
||||
Progressive disclosure:
|
||||
- support/procedure.md — read before edits or detailed auditing; contains core quality gates
|
||||
- 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
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Truthmark Structure Procedure
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
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.
|
||||
@@ -14,7 +14,7 @@ Truth Structure is agent-native:
|
||||
- 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 block or invoke Truth Structure instead of writing a mixed document
|
||||
- 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
|
||||
@@ -39,7 +39,7 @@ Use when a user asks to onboard a new code area into Truthmark, a new package, c
|
||||
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 block for review
|
||||
- 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
|
||||
@@ -53,16 +53,16 @@ Do not:
|
||||
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 gate:
|
||||
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 block with manual-review files
|
||||
- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Blocked reason as applicable
|
||||
Decision/Rationale preservation gate:
|
||||
- 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, block with manual-review files instead of deleting it or guessing
|
||||
- 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/**
|
||||
@@ -90,17 +90,17 @@ Repair rules:
|
||||
- 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 gate:
|
||||
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 gate confirms the doc is the right bounded owner
|
||||
- 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 block unsupported or stale claims
|
||||
- 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 Gate:
|
||||
- apply the Evidence Gate before finishing when Truth Structure writes routed docs, ownership claims, lane-specific decisions, or rationale
|
||||
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 block unsupported claims
|
||||
- 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.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Truthmark Structure Report Template
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Report completion in this shape:
|
||||
```md
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Truthmark Structure Subagents And Leases
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
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
|
||||
|
||||
@@ -3,7 +3,6 @@ name: truthmark-sync
|
||||
description: Use automatically at finish-time after functional code changes, or explicit /truthmark-sync, $truthmark-sync, or /truthmark:sync. Skip docs-only, formatting-only, behavior-preserving renames, missing config, and no-code changes. Not for doc-first realization or manual topology design.
|
||||
argument-hint: Optional changed-code area, truth-doc area, or sync focus
|
||||
user-invocable: true
|
||||
truthmark-version: 2.2.1
|
||||
---
|
||||
|
||||
# Truthmark Sync
|
||||
@@ -23,7 +22,7 @@ Quick procedure:
|
||||
- Read support/report-template.md before the final report.
|
||||
|
||||
Progressive disclosure:
|
||||
- support/procedure.md — read before edits or detailed auditing; contains core quality gates
|
||||
- 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
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
# Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
helpers:
|
||||
validate-sync-report:
|
||||
optional: true
|
||||
runner: truthmark>=2.2.1
|
||||
runner: truthmark
|
||||
command:
|
||||
argv:
|
||||
- truthmark
|
||||
@@ -17,7 +17,7 @@ helpers:
|
||||
fallback: "manually validate support/report-template.md and check Evidence checked entries match Claim, indented Evidence, and Result: supported | narrowed | removed | blocked"
|
||||
validate-write-lease:
|
||||
optional: true
|
||||
runner: truthmark>=2.2.1
|
||||
runner: truthmark
|
||||
command:
|
||||
argv:
|
||||
- truthmark
|
||||
|
||||
@@ -1,18 +1,18 @@
|
||||
# Optional Helper CLI Policy
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
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 too old for a declared helper, continue manually using this procedure and report which helper was skipped. Helper output is derived evidence; it does not override direct checkout inspection, workflow write boundaries, or parent acceptance.
|
||||
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 the declared Truthmark CLI runner before invoking a helper.
|
||||
- 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 or version-mismatched, treat the helper as skipped and use the manual fallback.
|
||||
- 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>=2.2.1; 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>=2.2.1; manual fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files
|
||||
- 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:
|
||||
|
||||
|
||||
@@ -1,10 +1,10 @@
|
||||
# Truthmark Sync Procedure
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
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 reopen the finish-time requirement, and an earlier explicit run satisfies the finish gate only if no later functional-code changes occur.
|
||||
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.
|
||||
@@ -13,36 +13,46 @@ Parent workflow:
|
||||
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. Lane classification gate:
|
||||
- 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 block 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.
|
||||
6. Update engineering truth first after code changes. Update product truth only when implemented user-visible product promise or capability boundary changed and explicit source/user evidence supports it; otherwise report product-lane review needed.
|
||||
7. Code verification is parent-owned: follow repository instructions and task context, and report what ran or why it did not run.
|
||||
8. 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.
|
||||
Topology quality gate:
|
||||
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
|
||||
- block and recommend Truth Structure when topology repair is unsafe, ambiguous, or outside the current task boundary
|
||||
- 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 gate:
|
||||
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 block and recommend Truth Structure
|
||||
- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Blocked reason as applicable
|
||||
Decision/Rationale preservation gate:
|
||||
- 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, block with manual-review files instead of deleting it or guessing
|
||||
- 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.
|
||||
@@ -50,21 +60,21 @@ Treat the HTML comments under each template section as normative authoring guida
|
||||
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 gate:
|
||||
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 gate confirms the doc is the right bounded owner
|
||||
- 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 block unsupported or stale claims
|
||||
- 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 Gate:
|
||||
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 block unsupported claims
|
||||
- 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.
|
||||
@@ -91,10 +101,10 @@ Do not create separate active-decision ADR/planning logs; replace the active dec
|
||||
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
|
||||
- block on any unrelated diff caused by the sync step
|
||||
- block 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 required report fields before accepting it
|
||||
- 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 blocked reason when the ownership gate fired
|
||||
- blocked outcomes must preserve the working tree as-is: no rollback, no post-block cleanup edits, and manual-review reporting of any remaining files
|
||||
- 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
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Truthmark Sync Report Template
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Report completion in this shape:
|
||||
```md
|
||||
@@ -9,11 +9,24 @@ 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/overview.md
|
||||
- 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.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Truthmark Sync Subagents And Leases
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
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
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
# 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"
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
# 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"
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
# 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"
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
# 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"
|
||||
|
||||
@@ -5,7 +5,7 @@ kind: local
|
||||
tools: [read_file, grep_search]
|
||||
---
|
||||
|
||||
# Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Manual invocation: @truth-claim-verifier
|
||||
|
||||
|
||||
@@ -5,7 +5,7 @@ kind: local
|
||||
tools: [read_file, grep_search]
|
||||
---
|
||||
|
||||
# Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Manual invocation: @truth-doc-reviewer
|
||||
|
||||
|
||||
@@ -5,7 +5,7 @@ kind: local
|
||||
tools: [read_file, grep_search, write_file]
|
||||
---
|
||||
|
||||
# Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
# 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.
|
||||
|
||||
|
||||
@@ -5,7 +5,7 @@ kind: local
|
||||
tools: [read_file, grep_search]
|
||||
---
|
||||
|
||||
# Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Manual invocation: @truth-route-auditor
|
||||
|
||||
|
||||
@@ -3,7 +3,6 @@ name: truthmark-check
|
||||
description: Use when the user asks to audit repository truth health, routing, ownership, or canonical docs. Not for normal lint/test/typecheck/code-review verification, finish-time Sync, or silently rewriting docs.
|
||||
argument-hint: Optional area, doc path, or audit focus
|
||||
user-invocable: true
|
||||
truthmark-version: 2.2.1
|
||||
---
|
||||
|
||||
# Truthmark Check
|
||||
@@ -23,6 +22,6 @@ Quick procedure:
|
||||
- Read support/report-template.md before the final report.
|
||||
|
||||
Progressive disclosure:
|
||||
- support/procedure.md — read before edits or detailed auditing; contains core quality gates
|
||||
- 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
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Truthmark Check Procedure
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
# Truthmark Check
|
||||
|
||||
@@ -20,7 +20,7 @@ Truth Check is agent-led:
|
||||
- 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 as blocked or routed to Truth Structure
|
||||
- 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:
|
||||
@@ -40,7 +40,7 @@ Truth Check is agent-led:
|
||||
- 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 Gate:
|
||||
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
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Truthmark Check Report Template
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Report completion in this shape:
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Truthmark Check Subagents And Leases
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
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
|
||||
|
||||
@@ -3,7 +3,6 @@ name: truthmark-document
|
||||
description: Use when the user asks to document existing implemented behavior, or Sync, Check, or Structure finds implemented behavior missing canonical truth. Not for functional-code changes, doc-first implementation, or topology repair that needs Structure.
|
||||
argument-hint: Optional implemented behavior, API endpoint, route, controller, package, or truth-doc area to document
|
||||
user-invocable: true
|
||||
truthmark-version: 2.2.1
|
||||
---
|
||||
|
||||
# Truthmark Document
|
||||
@@ -24,7 +23,7 @@ Quick procedure:
|
||||
- Read support/report-template.md before the final report.
|
||||
|
||||
Progressive disclosure:
|
||||
- support/procedure.md — read before edits or detailed auditing; contains core quality gates
|
||||
- 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
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
# Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
helpers:
|
||||
validate-document-report:
|
||||
optional: true
|
||||
runner: truthmark>=2.2.1
|
||||
runner: truthmark
|
||||
command:
|
||||
argv:
|
||||
- truthmark
|
||||
@@ -17,7 +17,7 @@ helpers:
|
||||
fallback: manually validate support/report-template.md required sections and structured Evidence checked entries
|
||||
validate-write-lease:
|
||||
optional: true
|
||||
runner: truthmark>=2.2.1
|
||||
runner: truthmark
|
||||
command:
|
||||
argv:
|
||||
- truthmark
|
||||
|
||||
@@ -1,18 +1,18 @@
|
||||
# Optional Helper CLI Policy
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
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 too old for a declared helper, continue manually using this procedure and report which helper was skipped. Helper output is derived evidence; it does not override direct checkout inspection, workflow write boundaries, or parent acceptance.
|
||||
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 the declared Truthmark CLI runner before invoking a helper.
|
||||
- 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 or version-mismatched, treat the helper as skipped and use the manual fallback.
|
||||
- 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>=2.2.1; manual fallback: manually validate support/report-template.md required sections and structured Evidence checked entries
|
||||
- validate-write-lease: optional truthmark>=2.2.1; manual fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files
|
||||
- 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:
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Truthmark Document Procedure
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
# Truthmark Document
|
||||
|
||||
@@ -19,13 +19,13 @@ Truth Document is manual and implementation-first:
|
||||
- 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 block or invoke Truth Structure instead of writing a mixed document
|
||||
- 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
|
||||
- block and recommend Truth Structure when routing repair is unsafe, ambiguous, or outside the task boundary
|
||||
- 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
|
||||
@@ -34,23 +34,23 @@ Truth Document is manual and implementation-first:
|
||||
- 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 gate:
|
||||
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 block and recommend Truth Structure
|
||||
- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Blocked reason as applicable
|
||||
Decision/Rationale preservation gate:
|
||||
- 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, block with manual-review files instead of deleting it or guessing
|
||||
- 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 Gate:
|
||||
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 block unsupported claims
|
||||
- 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.
|
||||
@@ -61,12 +61,12 @@ Treat the HTML comments under each template section as normative authoring guida
|
||||
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 gate:
|
||||
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 gate confirms the doc is the right bounded owner
|
||||
- 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 block unsupported or stale claims
|
||||
- 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.
|
||||
@@ -87,6 +87,6 @@ Helper status reporting:
|
||||
- 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
|
||||
- block 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 required report fields before accepting it
|
||||
- verify the final report records ownership review, structure requirement, restructure, routing update, or blocked reason when applicable
|
||||
- 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
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Truthmark Document Report Template
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Report completion in this shape:
|
||||
```md
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Truthmark Document Subagents And Leases
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
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
|
||||
|
||||
@@ -3,7 +3,6 @@ name: truthmark-preview
|
||||
description: Use when the user explicitly asks to preview likely workflow routing, target files, writes, or subagent use before edits. Not for validation, automatic gates, final correctness, or replacing Truth Check.
|
||||
argument-hint: Optional requested outcome, code area, doc path, or routing question
|
||||
user-invocable: true
|
||||
truthmark-version: 2.2.1
|
||||
---
|
||||
|
||||
# Truthmark Preview
|
||||
@@ -23,6 +22,6 @@ Quick procedure:
|
||||
- Hand off to the selected workflow after user approval.
|
||||
|
||||
Progressive disclosure:
|
||||
- support/procedure.md — read before edits or detailed auditing; contains core quality gates
|
||||
- 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
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Truthmark Preview Procedure
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
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.
|
||||
|
||||
@@ -9,7 +9,7 @@ Invocations: OpenCode /skill truthmark-preview; Codex /truthmark-preview or $tru
|
||||
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 blocking ambiguity before edits happen
|
||||
- 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
|
||||
@@ -27,7 +27,7 @@ Read:
|
||||
- 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 as blocked or routed to Truth Structure
|
||||
- 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:
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Truthmark Preview Report Template
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Report completion in this shape:
|
||||
```md
|
||||
@@ -35,7 +35,7 @@ Suggested subagent use:
|
||||
- write workers: none in Preview
|
||||
- leases needed: none in Preview
|
||||
|
||||
Blocking ambiguity:
|
||||
Manual handoff questions:
|
||||
- none identified in preview
|
||||
|
||||
Handoff:
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Truthmark Preview Subagents And Leases
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
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
|
||||
|
||||
@@ -3,7 +3,6 @@ name: truthmark-realize
|
||||
description: Use when the user explicitly asks to realize Truthmark truth docs into code, including /truthmark-realize, $truthmark-realize, or /truthmark:realize. Not for syncing docs after code changes, documenting existing code, topology repair, or truth audits.
|
||||
argument-hint: Optional truth doc path, area, or desired code behavior to realize
|
||||
user-invocable: true
|
||||
truthmark-version: 2.2.1
|
||||
---
|
||||
|
||||
# Truthmark Realize
|
||||
@@ -23,5 +22,5 @@ Quick procedure:
|
||||
- Read support/report-template.md before the final report.
|
||||
|
||||
Progressive disclosure:
|
||||
- support/procedure.md — read before edits or detailed auditing; contains core quality gates
|
||||
- support/procedure.md — read before edits or detailed auditing; contains core review questions
|
||||
- support/report-template.md — read before the final report
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Truthmark Realize Procedure
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
# Truthmark Realize
|
||||
|
||||
@@ -20,11 +20,11 @@ Workflow:
|
||||
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 gate:
|
||||
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, block before writing code and recommend Truth Structure or Truth Document
|
||||
- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Blocked reason as applicable
|
||||
- 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.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Truthmark Realize Report Template
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Report completion in this shape:
|
||||
|
||||
|
||||
@@ -3,7 +3,6 @@ name: truthmark-structure
|
||||
description: Use when routing or truth ownership is missing, stale, broad, overloaded, catch-all, unrouteable, mixed-owner, needs split/repair, or needs new area setup. Not for documenting implemented behavior, syncing a code diff, or realizing docs into code.
|
||||
argument-hint: Optional area, directory, or routing concern
|
||||
user-invocable: true
|
||||
truthmark-version: 2.2.1
|
||||
---
|
||||
|
||||
# Truthmark Structure
|
||||
@@ -23,6 +22,6 @@ Quick procedure:
|
||||
- Read support/report-template.md before the final report.
|
||||
|
||||
Progressive disclosure:
|
||||
- support/procedure.md — read before edits or detailed auditing; contains core quality gates
|
||||
- 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
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Truthmark Structure Procedure
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
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.
|
||||
@@ -14,7 +14,7 @@ Truth Structure is agent-native:
|
||||
- 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 block or invoke Truth Structure instead of writing a mixed document
|
||||
- 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
|
||||
@@ -39,7 +39,7 @@ Use when a user asks to onboard a new code area into Truthmark, a new package, c
|
||||
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 block for review
|
||||
- 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
|
||||
@@ -53,16 +53,16 @@ Do not:
|
||||
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 gate:
|
||||
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 block with manual-review files
|
||||
- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Blocked reason as applicable
|
||||
Decision/Rationale preservation gate:
|
||||
- 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, block with manual-review files instead of deleting it or guessing
|
||||
- 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/**
|
||||
@@ -90,17 +90,17 @@ Repair rules:
|
||||
- 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 gate:
|
||||
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 gate confirms the doc is the right bounded owner
|
||||
- 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 block unsupported or stale claims
|
||||
- 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 Gate:
|
||||
- apply the Evidence Gate before finishing when Truth Structure writes routed docs, ownership claims, lane-specific decisions, or rationale
|
||||
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 block unsupported claims
|
||||
- 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.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Truthmark Structure Report Template
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Report completion in this shape:
|
||||
```md
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Truthmark Structure Subagents And Leases
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
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
|
||||
|
||||
@@ -3,7 +3,6 @@ name: truthmark-sync
|
||||
description: Use automatically at finish-time after functional code changes, or explicit /truthmark-sync, $truthmark-sync, or /truthmark:sync. Skip docs-only, formatting-only, behavior-preserving renames, missing config, and no-code changes. Not for doc-first realization or manual topology design.
|
||||
argument-hint: Optional changed-code area, truth-doc area, or sync focus
|
||||
user-invocable: true
|
||||
truthmark-version: 2.2.1
|
||||
---
|
||||
|
||||
# Truthmark Sync
|
||||
@@ -25,7 +24,7 @@ Quick procedure:
|
||||
- Read support/report-template.md before the final report.
|
||||
|
||||
Progressive disclosure:
|
||||
- support/procedure.md — read before edits or detailed auditing; contains core quality gates
|
||||
- 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
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
# Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
helpers:
|
||||
validate-sync-report:
|
||||
optional: true
|
||||
runner: truthmark>=2.2.1
|
||||
runner: truthmark
|
||||
command:
|
||||
argv:
|
||||
- truthmark
|
||||
@@ -17,7 +17,7 @@ helpers:
|
||||
fallback: "manually validate support/report-template.md and check Evidence checked entries match Claim, indented Evidence, and Result: supported | narrowed | removed | blocked"
|
||||
validate-write-lease:
|
||||
optional: true
|
||||
runner: truthmark>=2.2.1
|
||||
runner: truthmark
|
||||
command:
|
||||
argv:
|
||||
- truthmark
|
||||
|
||||
@@ -1,18 +1,18 @@
|
||||
# Optional Helper CLI Policy
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
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 too old for a declared helper, continue manually using this procedure and report which helper was skipped. Helper output is derived evidence; it does not override direct checkout inspection, workflow write boundaries, or parent acceptance.
|
||||
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 the declared Truthmark CLI runner before invoking a helper.
|
||||
- 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 or version-mismatched, treat the helper as skipped and use the manual fallback.
|
||||
- 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>=2.2.1; 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>=2.2.1; manual fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files
|
||||
- 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:
|
||||
|
||||
|
||||
@@ -1,10 +1,10 @@
|
||||
# Truthmark Sync Procedure
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
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 reopen the finish-time requirement, and an earlier explicit run satisfies the finish gate only if no later functional-code changes occur.
|
||||
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.
|
||||
@@ -13,36 +13,46 @@ Parent workflow:
|
||||
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. Lane classification gate:
|
||||
- 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 block 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.
|
||||
6. Update engineering truth first after code changes. Update product truth only when implemented user-visible product promise or capability boundary changed and explicit source/user evidence supports it; otherwise report product-lane review needed.
|
||||
7. Code verification is parent-owned: follow repository instructions and task context, and report what ran or why it did not run.
|
||||
8. 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.
|
||||
Topology quality gate:
|
||||
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
|
||||
- block and recommend Truth Structure when topology repair is unsafe, ambiguous, or outside the current task boundary
|
||||
- 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 gate:
|
||||
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 block and recommend Truth Structure
|
||||
- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Blocked reason as applicable
|
||||
Decision/Rationale preservation gate:
|
||||
- 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, block with manual-review files instead of deleting it or guessing
|
||||
- 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.
|
||||
@@ -50,21 +60,21 @@ Treat the HTML comments under each template section as normative authoring guida
|
||||
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 gate:
|
||||
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 gate confirms the doc is the right bounded owner
|
||||
- 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 block unsupported or stale claims
|
||||
- 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 Gate:
|
||||
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 block unsupported claims
|
||||
- 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.
|
||||
@@ -91,10 +101,10 @@ Do not create separate active-decision ADR/planning logs; replace the active dec
|
||||
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
|
||||
- block on any unrelated diff caused by the sync step
|
||||
- block 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 required report fields before accepting it
|
||||
- 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 blocked reason when the ownership gate fired
|
||||
- blocked outcomes must preserve the working tree as-is: no rollback, no post-block cleanup edits, and manual-review reporting of any remaining files
|
||||
- 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
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Truthmark Sync Report Template
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Report completion in this shape:
|
||||
```md
|
||||
@@ -9,11 +9,24 @@ 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/overview.md
|
||||
- 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.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Truthmark Sync Subagents And Leases
|
||||
|
||||
Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
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
|
||||
|
||||
@@ -4,7 +4,7 @@ description: Read-only Truthmark claim verifier for checking canonical truth aga
|
||||
tools: [read, search]
|
||||
---
|
||||
|
||||
# Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades.
|
||||
# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
|
||||
|
||||
Stay read-only.
|
||||
Verify the behavior-bearing truth claims assigned by the parent against primary checkout evidence.
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user