mirror of
https://github.com/merlinhu1/truthmark.git
synced 2026-08-25 07:53:25 +02:00
Workflow Verifier And Writer Agents v1.4.0 (#5)
* feat(workflows): add verifier agent surfaces Generate project-scoped read-only verifier agents for Codex, Claude Code, GitHub Copilot, and OpenCode. Wire workflow manifests, generated surfaces, init diagnostics, sync classification, docs, and tests through the new subagent contract. * feat(workflows): add leased truth doc writer agents Add write-capable truth-doc-writer generated surfaces for Codex, Claude, Copilot, and OpenCode, guarded by explicit write leases. Tighten Truth Sync and Truth Document subagent contracts so parents validate leases, changed files, and worker reports before accepting doc updates. * feat(workflows): add Truth Preview and workflow support files Add the explicit read-only Truth Preview workflow across the manifest, generated host surfaces, docs, and tests. Move generated skill hosts to compact SKILL.md entrypoints with support procedure, report, and lease files, and add write-worker report acceptance validation against actual lease diffs.
This commit is contained in:
MerlinH
@@ -0,0 +1,33 @@
|
||||
---
|
||||
description: Read-only Truthmark claim verifier for checking canonical truth against checkout evidence.
|
||||
mode: subagent
|
||||
permission:
|
||||
edit: deny
|
||||
task: deny
|
||||
webfetch: deny
|
||||
websearch: deny
|
||||
external_directory: deny
|
||||
bash:
|
||||
"*": ask
|
||||
"git status*": allow
|
||||
"git diff*": allow
|
||||
"git log*": allow
|
||||
"rg *": allow
|
||||
"grep *": allow
|
||||
---
|
||||
|
||||
# Generated by Truthmark 1.4.0. Rerun truthmark init after upgrades.
|
||||
|
||||
Manual invocation: @truth-claim-verifier
|
||||
|
||||
Stay read-only.
|
||||
Verify the behavior-bearing truth claims assigned by the parent against primary checkout evidence.
|
||||
Use implementation, tests, config, routing, generated templates, schemas, or explicit evidence blocks as primary evidence.
|
||||
Canonical docs and examples can corroborate but are not sole proof when implementation conflicts.
|
||||
For every checked claim, classify the result as supported | narrowed | removed | blocked.
|
||||
Do not edit files, stage changes, or invent missing behavior.
|
||||
Return JSON only with keys: scope, filesReviewed, claimsChecked, evidence, unsupportedClaims, confidence, recommendedWorkflow, notes.
|
||||
Context boundary:
|
||||
Do not preload AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, or repo-wide policy docs unless the parent explicitly assigns them as evidence.
|
||||
Use only the parent-assigned shard plus required checkout evidence files.
|
||||
Return findings only; the parent workflow owns repository-policy interpretation, final decisions, and all writes.
|
||||
@@ -0,0 +1,32 @@
|
||||
---
|
||||
description: Read-only Truthmark doc reviewer for shape, decision, rationale, and evidence hygiene.
|
||||
mode: subagent
|
||||
permission:
|
||||
edit: deny
|
||||
task: deny
|
||||
webfetch: deny
|
||||
websearch: deny
|
||||
external_directory: deny
|
||||
bash:
|
||||
"*": ask
|
||||
"git status*": allow
|
||||
"git diff*": allow
|
||||
"git log*": allow
|
||||
"rg *": allow
|
||||
"grep *": allow
|
||||
---
|
||||
|
||||
# Generated by Truthmark 1.4.0. Rerun truthmark init after upgrades.
|
||||
|
||||
Manual invocation: @truth-doc-reviewer
|
||||
|
||||
Stay read-only.
|
||||
Review assigned canonical truth docs for frontmatter, source_of_truth, required template sections, Evidence checked entries, Product Decisions, and Rationale.
|
||||
Flag README.md files used as behavior truth targets, mixed-owner docs, and shape repairs that should move to Truth Structure.
|
||||
Do not edit files, stage changes, or rewrite docs.
|
||||
Return JSON only with keys: scope, filesReviewed, findings, evidence, confidence, recommendedWorkflow, notes.
|
||||
recommendedWorkflow must be one of: none, truthmark-document, truthmark-structure.
|
||||
Context boundary:
|
||||
Do not preload AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, or repo-wide policy docs unless the parent explicitly assigns them as evidence.
|
||||
Use only the parent-assigned shard plus required checkout evidence files.
|
||||
Return findings only; the parent workflow owns repository-policy interpretation, final decisions, and all writes.
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
description: Write-capable Truthmark doc worker for one parent-leased truth-document shard.
|
||||
mode: subagent
|
||||
permission:
|
||||
read: allow
|
||||
list: allow
|
||||
grep: allow
|
||||
glob: allow
|
||||
edit:
|
||||
"*": deny
|
||||
"docs/truth/**": allow
|
||||
"docs/truthmark/areas.md": allow
|
||||
"docs/truthmark/areas/**/*.md": allow
|
||||
task: deny
|
||||
webfetch: deny
|
||||
websearch: deny
|
||||
external_directory: deny
|
||||
bash:
|
||||
"*": ask
|
||||
"git status*": allow
|
||||
"git diff*": allow
|
||||
---
|
||||
|
||||
# Generated by Truthmark 1.4.0. Rerun truthmark init after upgrades.
|
||||
|
||||
Manual invocation: @truth-doc-writer
|
||||
|
||||
Write one leased Truthmark truth-document shard assigned by the parent.
|
||||
Require an explicit write lease before editing. The lease must name workflow, worker, shard, objective, requiredReads, allowedWrites, forbiddenWrites, evidenceRequired, verification, and reportFields.
|
||||
Read every requiredReads entry directly before editing.
|
||||
Edit only leased canonical truth docs or leased truth routing files. Do not edit functional code, generated host surfaces, package files, config files, templates, or tests unless they are explicitly leased.
|
||||
Do not expand your own write scope. If the task needs an off-lease file, stop and report blocked.
|
||||
Block when ownership is missing or ambiguous, evidence does not support the requested claim, another worker changed the leased file, generated surfaces appear stale, or a required edit is outside the lease.
|
||||
Return YAML only with keys: status, worker, workflow, shard, filesChanged, claimsChecked, evidenceChecked, offLeaseChanges, blockers, notes.
|
||||
status must be completed or blocked.
|
||||
filesChanged must list only files you actually changed.
|
||||
offLeaseChanges must be empty for completed reports.
|
||||
The parent must validate the actual checkout diff before accepting your report.
|
||||
@@ -0,0 +1,33 @@
|
||||
---
|
||||
description: Read-only Truthmark route auditor for bounded routing and ownership verification.
|
||||
mode: subagent
|
||||
permission:
|
||||
edit: deny
|
||||
task: deny
|
||||
webfetch: deny
|
||||
websearch: deny
|
||||
external_directory: deny
|
||||
bash:
|
||||
"*": ask
|
||||
"git status*": allow
|
||||
"git diff*": allow
|
||||
"git log*": allow
|
||||
"rg *": allow
|
||||
"grep *": allow
|
||||
---
|
||||
|
||||
# Generated by Truthmark 1.4.0. Rerun truthmark init after upgrades.
|
||||
|
||||
Manual invocation: @truth-route-auditor
|
||||
|
||||
Stay read-only.
|
||||
Audit one bounded Truthmark route, area, or doc shard assigned by the parent.
|
||||
Read .truthmark/config.yml, the root route index, relevant child route files, mapped truth docs, and relevant implementation files directly.
|
||||
Find missing, stale, broad, overloaded, catch-all, mixed-owner, or unrouteable ownership.
|
||||
Do not edit files, stage changes, or propose broad rewrites.
|
||||
Return JSON only with keys: scope, filesReviewed, findings, evidence, confidence, recommendedWorkflow, notes.
|
||||
recommendedWorkflow must be one of: none, truthmark-document, truthmark-structure.
|
||||
Context boundary:
|
||||
Do not preload AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, or repo-wide policy docs unless the parent explicitly assigns them as evidence.
|
||||
Use only the parent-assigned shard plus required checkout evidence files.
|
||||
Return findings only; the parent workflow owns repository-policy interpretation, final decisions, and all writes.
|
||||
@@ -3,7 +3,7 @@ name: truthmark-check
|
||||
description: Use when the user asks to audit repository truth health, routing, ownership, or canonical docs. Not for normal lint/test/typecheck/code-review verification, finish-time Sync, or silently rewriting docs.
|
||||
argument-hint: Optional area, doc path, or audit focus
|
||||
user-invocable: true
|
||||
truthmark-version: 1.3.0
|
||||
truthmark-version: 1.4.0
|
||||
---
|
||||
|
||||
# Truthmark Check
|
||||
@@ -12,54 +12,16 @@ Use this skill to audit repository truth health.
|
||||
|
||||
Invocations: OpenCode /skill truthmark-check; Codex /truthmark-check or $truthmark-check; Claude Code /truthmark-check; GitHub Copilot /truthmark-check; Gemini CLI /truthmark:check.
|
||||
|
||||
Truth Check is agent-led:
|
||||
Quick procedure:
|
||||
- Follow docs/ai/repo-rules.md as the repository instruction authority.
|
||||
- Read .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, canonical docs, and relevant implementation directly.
|
||||
- Report issues and suggested fixes; do not silently rewrite unrelated files.
|
||||
- Direct checkout inspection is valid even when local tooling is unavailable.
|
||||
- Read support/procedure.md before auditing details.
|
||||
- Read support/subagents-and-leases.md before dispatching verifier subagents.
|
||||
- Read support/report-template.md before the final report.
|
||||
|
||||
- inspect .truthmark/config.yml, docs/truthmark/areas.md, canonical docs, and relevant implementation directly
|
||||
- Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority.
|
||||
Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries.
|
||||
- inspect the configured root route index at docs/truthmark/areas.md and relevant child route files under docs/truthmark/areas/
|
||||
- check that current docs describe current code rather than historical plans
|
||||
- check that docs/truthmark/areas.md routes code surfaces to canonical truth docs
|
||||
- check for broad, catch-all, index-like, or mixed-owner truth docs and report them as topology issues requiring Truth Structure
|
||||
- check that canonical behavior docs keep active Product Decisions and Rationale sections
|
||||
- optionally run truthmark check when local tooling is available
|
||||
- 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:
|
||||
- support each finding and suggested fix with evidence from config, route files, canonical docs, implementation, templates, or tests
|
||||
- canonical docs are context, not sole proof when implementation conflicts
|
||||
- remove unsupported findings or mark open questions; validate changed claims if you edit docs
|
||||
|
||||
Truthmark hierarchy:
|
||||
- Config: .truthmark/config.yml
|
||||
- Root route index: docs/truthmark/areas.md
|
||||
- Area route files: docs/truthmark/areas/**/*.md
|
||||
- Truth docs: docs/truth/**/*.md
|
||||
Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed.
|
||||
Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail.
|
||||
Update Product Decisions and Rationale when a decision changes behavior.
|
||||
|
||||
Report completion in this shape:
|
||||
|
||||
```md
|
||||
Truth Check: completed
|
||||
|
||||
Files reviewed:
|
||||
- docs/truthmark/areas.md
|
||||
|
||||
Issues found:
|
||||
- none
|
||||
|
||||
Fixes suggested:
|
||||
- none
|
||||
|
||||
Evidence checked:
|
||||
- Finding: The root route index is present and maps repository truth owners.
|
||||
Evidence: .truthmark/config.yml:1 / docs/truthmark/areas.md:1
|
||||
Suggested fix: none
|
||||
Confidence: high
|
||||
|
||||
Validation:
|
||||
- truthmark check
|
||||
```
|
||||
Progressive disclosure:
|
||||
- support/procedure.md
|
||||
- support/report-template.md
|
||||
- support/subagents-and-leases.md
|
||||
|
||||
@@ -0,0 +1,37 @@
|
||||
# Truthmark Check Procedure
|
||||
|
||||
Generated by Truthmark 1.4.0. Rerun truthmark init after upgrades.
|
||||
|
||||
# Truthmark Check
|
||||
|
||||
Use this skill to audit repository truth health.
|
||||
|
||||
Invocations: OpenCode /skill truthmark-check; Codex /truthmark-check or $truthmark-check; Claude Code /truthmark-check; GitHub Copilot /truthmark-check; Gemini CLI /truthmark:check.
|
||||
|
||||
Truth Check is agent-led:
|
||||
|
||||
- inspect .truthmark/config.yml, docs/truthmark/areas.md, canonical docs, and relevant implementation directly
|
||||
- Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority.
|
||||
Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries.
|
||||
- inspect the configured root route index at docs/truthmark/areas.md and relevant child route files under docs/truthmark/areas/
|
||||
- check that current docs describe current code rather than historical plans
|
||||
- check that docs/truthmark/areas.md routes code surfaces to canonical truth docs
|
||||
- check for broad, catch-all, index-like, or mixed-owner truth docs and report them as topology issues requiring Truth Structure
|
||||
- check that canonical behavior docs keep active Product Decisions and Rationale sections
|
||||
- optionally run truthmark check when local tooling is available
|
||||
- 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:
|
||||
- support each finding and suggested fix with evidence from config, route files, canonical docs, implementation, templates, or tests
|
||||
- canonical docs are context, not sole proof when implementation conflicts
|
||||
- remove unsupported findings or mark open questions; validate changed claims if you edit docs
|
||||
|
||||
Truthmark hierarchy:
|
||||
- Config: .truthmark/config.yml
|
||||
- Root route index: docs/truthmark/areas.md
|
||||
- Area route files: docs/truthmark/areas/**/*.md
|
||||
- Truth docs: docs/truth/**/*.md
|
||||
Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed.
|
||||
Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail.
|
||||
Update Product Decisions and Rationale when a decision changes behavior.
|
||||
@@ -0,0 +1,27 @@
|
||||
# Truthmark Check Report Template
|
||||
|
||||
Generated by Truthmark 1.4.0. Rerun truthmark init after upgrades.
|
||||
|
||||
Report completion in this shape:
|
||||
|
||||
```md
|
||||
Truth Check: completed
|
||||
|
||||
Files reviewed:
|
||||
- docs/truthmark/areas.md
|
||||
|
||||
Issues found:
|
||||
- none
|
||||
|
||||
Fixes suggested:
|
||||
- none
|
||||
|
||||
Evidence checked:
|
||||
- Finding: The root route index is present and maps repository truth owners.
|
||||
Evidence: .truthmark/config.yml:1 / docs/truthmark/areas.md:1
|
||||
Suggested fix: none
|
||||
Confidence: high
|
||||
|
||||
Validation:
|
||||
- truthmark check
|
||||
```
|
||||
@@ -0,0 +1,10 @@
|
||||
# Truthmark Check Subagents And Leases
|
||||
|
||||
Generated by Truthmark 1.4.0. Rerun truthmark init after upgrades.
|
||||
|
||||
OpenCode subagent mode:
|
||||
- use automatically when this workflow runs in OpenCode and the parent agent chooses bounded subagent fan-out
|
||||
- dispatch read-only project subagents only: @truth-route-auditor, @truth-claim-verifier, @truth-doc-reviewer
|
||||
- workers inspect checkout evidence directly, return structured findings, and must not edit files
|
||||
- parent supplies bounded evidence shards; workers must not preload host instruction files or repo-wide policy docs unless assigned as evidence
|
||||
- Parent agent owns the final Truth Check report
|
||||
@@ -3,98 +3,25 @@ name: truthmark-document
|
||||
description: Use when the user asks to document existing implemented behavior, or Sync, Check, or Structure finds implemented behavior missing canonical truth. Not for functional-code changes, doc-first implementation, or topology repair that needs Structure.
|
||||
argument-hint: Optional implemented behavior, API endpoint, route, controller, package, or truth-doc area to document
|
||||
user-invocable: true
|
||||
truthmark-version: 1.3.0
|
||||
truthmark-version: 1.4.0
|
||||
---
|
||||
|
||||
# Truthmark Document
|
||||
|
||||
Use this skill to document existing implemented behavior when no functional-code changes are required for the task.
|
||||
|
||||
Invocations: OpenCode /skill truthmark-document; Codex /truthmark-document or $truthmark-document; Claude Code /truthmark-document; GitHub Copilot /truthmark-document; Gemini CLI /truthmark:document.
|
||||
|
||||
Truth Document is manual and implementation-first:
|
||||
Quick procedure:
|
||||
- Follow docs/ai/repo-rules.md as the repository instruction authority.
|
||||
- Read .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, existing canonical docs, implementation code, and tests directly.
|
||||
- Document current implemented behavior; do not invent future behavior.
|
||||
- May write canonical truth docs and truth routing files only; must not write functional code.
|
||||
- Read support/procedure.md before editing truth docs.
|
||||
- Read support/subagents-and-leases.md before dispatching or accepting worker output.
|
||||
- Read support/report-template.md before the final report.
|
||||
|
||||
- run only when the user explicitly asks to generate or update truth docs for existing behavior, or when Truth Sync, Truth Check, or Truth Structure reports implemented behavior that lacks canonical truth docs
|
||||
- inspect .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, existing canonical docs, implementation code, and tests directly
|
||||
- Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority.
|
||||
Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries.
|
||||
- document current implemented behavior; do not invent future behavior or planned endpoints
|
||||
- may write canonical truth docs and docs/truthmark/areas.md or relevant child route files only
|
||||
- must not write functional code
|
||||
- when routing is missing, stale, broad, overloaded, catch-all, or cannot map the behavior to a bounded truth owner, run Truth Structure first when routing repair is safe and in scope
|
||||
- block and recommend Truth Structure when routing repair is unsafe, ambiguous, or outside the task boundary
|
||||
- keep feature README.md files as indexes rather than truth-document targets
|
||||
- create or update bounded leaf truth docs when behavior does not fit an existing leaf doc
|
||||
- keep behavior truth docs behavior-oriented, not endpoint-oriented, unless the endpoint itself is the behavior boundary
|
||||
- keep API endpoint details in the nearest contract truth doc when such a doc owns the API contract
|
||||
- preserve unrelated authored content
|
||||
Truth-doc ownership gate:
|
||||
- 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
|
||||
Product Decisions/Rationale preservation gate:
|
||||
- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions and Rationale sections in every source or touched truth doc
|
||||
- preserve each current decision and rationale in the bounded owner doc it governs; 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
|
||||
- after the edit, verify every touched truth doc still has Product Decisions and Rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked
|
||||
Evidence Gate:
|
||||
- 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, Product 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
|
||||
- if no truth doc changed, report why current truth was already sufficient or why documentation was blocked
|
||||
Repository intelligence artifacts are optional derived context: RepoIndex, RouteMap, ImpactSet, and ContextPack may guide routing, context selection, and verification planning when available.
|
||||
They do not override checkout evidence, canonical truth docs, route files, or workflow write boundaries.
|
||||
If unavailable, inspect .truthmark/config.yml, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated.
|
||||
When creating or updating a truth doc, inspect the routed truth kind and use the matching `docs/templates/<kind>-doc.md` template.
|
||||
Supported kinds: behavior, contract, architecture, workflow, operations, and test-behavior.
|
||||
Align existing docs to that template while preserving accurate authored content.
|
||||
If the template is missing, use Scope, Product Decisions, Rationale, and the kind-specific current-truth section.
|
||||
Teams may edit the template files under docs/templates/ to define their local truth-doc standards.
|
||||
Truth-doc shape repair gate:
|
||||
- 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
|
||||
- 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
|
||||
- report docs restructured and why a narrow edit was not sufficient
|
||||
Maintain architecture docs only for structure-level changes: system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership.
|
||||
Keep ordinary behavior, endpoints, UI copy, validation rules, and bug fixes in behavior or contract docs unless they change those boundaries.
|
||||
Truthmark hierarchy:
|
||||
- Config: .truthmark/config.yml
|
||||
- Root route index: docs/truthmark/areas.md
|
||||
- Area route files: docs/truthmark/areas/**/*.md
|
||||
- Truth docs: docs/truth/**/*.md
|
||||
Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed.
|
||||
Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail.
|
||||
Update Product Decisions and Rationale when a decision changes behavior.
|
||||
|
||||
Report completion in this shape:
|
||||
```md
|
||||
Truth Document: completed
|
||||
|
||||
Implementation reviewed:
|
||||
- src/routing/area-resolver.ts
|
||||
|
||||
Truth docs created:
|
||||
- docs/truth/contracts.md
|
||||
|
||||
Truth docs updated:
|
||||
- docs/truth/check-diagnostics.md
|
||||
|
||||
Truth docs restructured:
|
||||
- docs/truth/check-diagnostics.md
|
||||
|
||||
Routing updated:
|
||||
- docs/truthmark/areas.md
|
||||
|
||||
Evidence checked:
|
||||
- Claim: Route resolution behavior is documented in the contracts truth doc.
|
||||
Evidence: src/routing/area-resolver.ts:14 / docs/truthmark/areas.md:9
|
||||
Result: supported
|
||||
|
||||
Notes:
|
||||
- Documented routing and behavior from route handlers and tests.
|
||||
```
|
||||
Progressive disclosure:
|
||||
- support/procedure.md
|
||||
- support/report-template.md
|
||||
- support/subagents-and-leases.md
|
||||
|
||||
@@ -0,0 +1,73 @@
|
||||
# Truthmark Document Procedure
|
||||
|
||||
Generated by Truthmark 1.4.0. Rerun truthmark init after upgrades.
|
||||
|
||||
# Truthmark Document
|
||||
|
||||
Use this skill to document existing implemented behavior when no functional-code changes are required for the task.
|
||||
Invocations: OpenCode /skill truthmark-document; Codex /truthmark-document or $truthmark-document; Claude Code /truthmark-document; GitHub Copilot /truthmark-document; Gemini CLI /truthmark:document.
|
||||
|
||||
Truth Document is manual and implementation-first:
|
||||
|
||||
- run only when the user explicitly asks to generate or update truth docs for existing behavior, or when Truth Sync, Truth Check, or Truth Structure reports implemented behavior that lacks canonical truth docs
|
||||
- inspect .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, existing canonical docs, implementation code, and tests directly
|
||||
- Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority.
|
||||
Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries.
|
||||
- document current implemented behavior; do not invent future behavior or planned endpoints
|
||||
- may write canonical truth docs and docs/truthmark/areas.md or relevant child route files only
|
||||
- must not write functional code
|
||||
- when routing is missing, stale, broad, overloaded, catch-all, or cannot map the behavior to a bounded truth owner, run Truth Structure first when routing repair is safe and in scope
|
||||
- block and recommend Truth Structure when routing repair is unsafe, ambiguous, or outside the task boundary
|
||||
- keep feature README.md files as indexes rather than truth-document targets
|
||||
- create or update bounded leaf truth docs when behavior does not fit an existing leaf doc
|
||||
- keep behavior truth docs behavior-oriented, not endpoint-oriented, unless the endpoint itself is the behavior boundary
|
||||
- keep API endpoint details in the nearest contract truth doc when such a doc owns the API contract
|
||||
- preserve unrelated authored content
|
||||
Truth-doc ownership gate:
|
||||
- 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
|
||||
Product Decisions/Rationale preservation gate:
|
||||
- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions and Rationale sections in every source or touched truth doc
|
||||
- preserve each current decision and rationale in the bounded owner doc it governs; 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
|
||||
- after the edit, verify every touched truth doc still has Product Decisions and Rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked
|
||||
Evidence Gate:
|
||||
- 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, Product 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
|
||||
- if no truth doc changed, report why current truth was already sufficient or why documentation was blocked
|
||||
Repository intelligence artifacts are optional derived context: RepoIndex, RouteMap, ImpactSet, and ContextPack may guide routing, context selection, and verification planning when available.
|
||||
They do not override checkout evidence, canonical truth docs, route files, or workflow write boundaries.
|
||||
If unavailable, inspect .truthmark/config.yml, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated.
|
||||
When creating or updating a truth doc, inspect the routed truth kind and use the matching `docs/templates/<kind>-doc.md` template.
|
||||
Supported kinds: behavior, contract, architecture, workflow, operations, and test-behavior.
|
||||
Align existing docs to that template while preserving accurate authored content.
|
||||
If the template is missing, use Scope, Product Decisions, Rationale, and the kind-specific current-truth section.
|
||||
Teams may edit the template files under docs/templates/ to define their local truth-doc standards.
|
||||
Truth-doc shape repair gate:
|
||||
- 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
|
||||
- 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
|
||||
- report docs restructured and why a narrow edit was not sufficient
|
||||
Maintain architecture docs only for structure-level changes: system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership.
|
||||
Keep ordinary behavior, endpoints, UI copy, validation rules, and bug fixes in behavior or contract docs unless they change those boundaries.
|
||||
Truthmark hierarchy:
|
||||
- Config: .truthmark/config.yml
|
||||
- Root route index: docs/truthmark/areas.md
|
||||
- Area route files: docs/truthmark/areas/**/*.md
|
||||
- Truth docs: docs/truth/**/*.md
|
||||
Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed.
|
||||
Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail.
|
||||
Update Product Decisions and Rationale when a decision changes behavior.
|
||||
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
|
||||
@@ -0,0 +1,31 @@
|
||||
# Truthmark Document Report Template
|
||||
|
||||
Generated by Truthmark 1.4.0. Rerun truthmark init after upgrades.
|
||||
|
||||
Report completion in this shape:
|
||||
```md
|
||||
Truth Document: completed
|
||||
|
||||
Implementation reviewed:
|
||||
- src/routing/area-resolver.ts
|
||||
|
||||
Truth docs created:
|
||||
- docs/truth/contracts.md
|
||||
|
||||
Truth docs updated:
|
||||
- docs/truth/check-diagnostics.md
|
||||
|
||||
Truth docs restructured:
|
||||
- docs/truth/check-diagnostics.md
|
||||
|
||||
Routing updated:
|
||||
- docs/truthmark/areas.md
|
||||
|
||||
Evidence checked:
|
||||
- Claim: Route resolution behavior is documented in the contracts truth doc.
|
||||
Evidence: src/routing/area-resolver.ts:14 / docs/truthmark/areas.md:9
|
||||
Result: supported
|
||||
|
||||
Notes:
|
||||
- Documented routing and behavior from route handlers and tests.
|
||||
```
|
||||
@@ -0,0 +1,14 @@
|
||||
# Truthmark Document Subagents And Leases
|
||||
|
||||
Generated by Truthmark 1.4.0. Rerun truthmark init after upgrades.
|
||||
|
||||
OpenCode subagent mode:
|
||||
- use automatically when this workflow runs in OpenCode and the parent agent chooses bounded subagent fan-out
|
||||
- dispatch read-only project subagents for verification: @truth-route-auditor, @truth-claim-verifier
|
||||
- read-only workers inspect checkout evidence directly, return structured findings, and must not edit files
|
||||
- parent supplies bounded evidence shards; read-only workers must not preload host instruction files or repo-wide policy docs unless assigned as evidence
|
||||
- dispatch write-capable project subagents only with explicit write leases: @truth-doc-writer
|
||||
- each write lease must name objective, required reads, allowed writes, forbidden writes, evidence, verification, and report fields
|
||||
- write workers must stop when a required edit is off-lease and report status, filesChanged, evidence, offLeaseChanges, blockers, and notes
|
||||
- parent must inspect the actual checkout diff against each lease before accepting a worker report
|
||||
- Parent agent owns Truth Document acceptance, lease validation, and final report
|
||||
@@ -0,0 +1,26 @@
|
||||
---
|
||||
name: truthmark-preview
|
||||
description: Use when the user explicitly asks to preview likely workflow routing, target files, writes, or subagent use before edits. Not for validation, automatic gates, final correctness, or replacing Truth Check.
|
||||
argument-hint: Optional requested outcome, code area, doc path, or routing question
|
||||
user-invocable: true
|
||||
truthmark-version: 1.4.0
|
||||
---
|
||||
|
||||
# Truthmark Preview
|
||||
|
||||
Use this skill only when the user explicitly asks to preview Truthmark routing or workflow choice before edits.
|
||||
|
||||
Invocations: OpenCode /skill truthmark-preview; Codex /truthmark-preview or $truthmark-preview; Claude Code /truthmark-preview; GitHub Copilot /truthmark-preview; Gemini CLI /truthmark:preview.
|
||||
|
||||
Quick procedure:
|
||||
- Follow docs/ai/repo-rules.md as the repository instruction authority.
|
||||
- Read .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, and only the truth docs or implementation files needed to preview ownership.
|
||||
- Truth Preview is read-only; this report is intended, not authorized.
|
||||
- must not edit files and must not issue write leases; do not run Truth Sync automatically, replace Truth Check, claim final correctness, or mutate code.
|
||||
- Use optional read-only route-auditor evidence only when it reduces context or clarifies ownership.
|
||||
- Hand off to the selected workflow after user approval.
|
||||
|
||||
Progressive disclosure:
|
||||
- support/procedure.md
|
||||
- support/report-template.md
|
||||
- support/subagents-and-leases.md
|
||||
@@ -0,0 +1,43 @@
|
||||
# Truthmark Preview Procedure
|
||||
|
||||
Generated by Truthmark 1.4.0. Rerun truthmark init after upgrades.
|
||||
|
||||
Use this skill only when the user explicitly asks to preview Truthmark routing or workflow choice before edits.
|
||||
|
||||
Invocations: OpenCode /skill truthmark-preview; Codex /truthmark-preview or $truthmark-preview; Claude Code /truthmark-preview; GitHub Copilot /truthmark-preview; Gemini CLI /truthmark:preview.
|
||||
|
||||
Truth Preview is read-only. Its report is intended, not authorized.
|
||||
|
||||
Purpose:
|
||||
- preview the likely Truthmark workflow, route owner, target files, expected write classes, suggested subagent use, and blocking ambiguity before edits happen
|
||||
- hand off to the selected workflow after user approval
|
||||
- keep the selector thin so agents can avoid loading or acting through heavier workflows prematurely
|
||||
|
||||
Read:
|
||||
- .truthmark/config.yml
|
||||
- docs/truthmark/areas.md
|
||||
- relevant child route files under docs/truthmark/areas/
|
||||
- relevant truth docs and implementation files needed to preview ownership
|
||||
- Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority.
|
||||
Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries.
|
||||
|
||||
Do not:
|
||||
- must not edit files
|
||||
- must not create truth docs
|
||||
- must not update routing
|
||||
- must not run Truth Sync automatically
|
||||
- must not replace Truth Check
|
||||
- must not claim final correctness
|
||||
- must not issue write leases
|
||||
- must not mutate code
|
||||
|
||||
Suggested subagent use:
|
||||
- optional read-only verifier: truth_route_auditor
|
||||
- write workers: none
|
||||
- leases needed: none
|
||||
|
||||
Truthmark hierarchy:
|
||||
- Config: .truthmark/config.yml
|
||||
- Root route index: docs/truthmark/areas.md
|
||||
- Area route files: docs/truthmark/areas/**/*.md
|
||||
- Truth docs: docs/truth/**/*.md
|
||||
@@ -0,0 +1,41 @@
|
||||
# Truthmark Preview Report Template
|
||||
|
||||
Generated by Truthmark 1.4.0. Rerun truthmark init after upgrades.
|
||||
|
||||
Report completion in this shape:
|
||||
```md
|
||||
Truth Preview: completed
|
||||
|
||||
Requested outcome:
|
||||
- preview likely Truthmark workflow routing before edits
|
||||
|
||||
Likely workflow:
|
||||
- truthmark-document
|
||||
|
||||
Why this workflow:
|
||||
- positive trigger: document existing implemented behavior
|
||||
- negative triggers considered: functional-code change, doc-first implementation, topology repair, truth audit
|
||||
- forbidden adjacency considered: must not edit functional code
|
||||
|
||||
Likely route owner:
|
||||
- route file: docs/truthmark/areas.md
|
||||
- truth doc: docs/truth/example.md
|
||||
- confidence: medium
|
||||
|
||||
Expected write classes:
|
||||
- truth docs
|
||||
|
||||
Expected target files:
|
||||
- docs/truth/example.md
|
||||
|
||||
Suggested subagent use:
|
||||
- read-only verifiers: truth_route_auditor
|
||||
- write workers: none in Preview
|
||||
- leases needed: none in Preview
|
||||
|
||||
Blocking ambiguity:
|
||||
- none identified in preview
|
||||
|
||||
Handoff:
|
||||
- Run the selected Truthmark workflow after user approval.
|
||||
```
|
||||
@@ -0,0 +1,10 @@
|
||||
# Truthmark Preview Subagents And Leases
|
||||
|
||||
Generated by Truthmark 1.4.0. Rerun truthmark init after upgrades.
|
||||
|
||||
OpenCode subagent mode:
|
||||
- use automatically when this workflow runs in OpenCode and the parent agent chooses bounded subagent fan-out
|
||||
- dispatch read-only project subagents only: @truth-route-auditor
|
||||
- workers inspect checkout evidence directly, return structured findings, and must not edit files
|
||||
- parent supplies bounded evidence shards; workers must not preload host instruction files or repo-wide policy docs unless assigned as evidence
|
||||
- Parent agent owns the final Truth Preview report
|
||||
@@ -3,7 +3,7 @@ name: truthmark-realize
|
||||
description: Use when the user explicitly asks to realize Truthmark truth docs into code, including /truthmark-realize, $truthmark-realize, or /truthmark:realize. Not for syncing docs after code changes, documenting existing code, topology repair, or truth audits.
|
||||
argument-hint: Optional truth doc path, area, or desired code behavior to realize
|
||||
user-invocable: true
|
||||
truthmark-version: 1.3.0
|
||||
truthmark-version: 1.4.0
|
||||
---
|
||||
|
||||
# Truthmark Realize
|
||||
@@ -12,50 +12,14 @@ Use this skill only when the user explicitly asks to realize truth docs into cod
|
||||
|
||||
Invocations: OpenCode /skill truthmark-realize; Codex /truthmark-realize or $truthmark-realize; Claude Code /truthmark-realize; GitHub Copilot /truthmark-realize; Gemini CLI /truthmark:realize.
|
||||
|
||||
Truth Realize is doc-first:
|
||||
Quick procedure:
|
||||
- Follow docs/ai/repo-rules.md as the repository instruction authority.
|
||||
- Read the source truth docs, .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files, tests, and relevant functional code directly.
|
||||
- Truth docs lead; code follows.
|
||||
- may write functional code only; must not edit truth docs or truth routing while realizing those docs.
|
||||
- Read support/procedure.md before changing code.
|
||||
- Read support/report-template.md before the final report.
|
||||
|
||||
- truth docs lead
|
||||
- code follows
|
||||
- Truth Realize never edits the truth docs it is realizing
|
||||
|
||||
Workflow:
|
||||
|
||||
1. Read the updated truth docs named by the user, or infer the relevant docs from docs/truthmark/areas.md.
|
||||
2. Read .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files, tests, and the relevant functional code.
|
||||
3. Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority.
|
||||
Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries.
|
||||
Truth-doc ownership gate:
|
||||
- before editing or relying on source truth docs before writing code, verify each target/source truth doc is a bounded owner for the behavior
|
||||
- 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
|
||||
4. Update functional code only so implementation matches bounded, current truth claims from the source docs.
|
||||
5. Do not edit truth docs or truth routing while realizing those docs.
|
||||
6. Run relevant tests for the changed code.
|
||||
7. Report changed code files and verification steps.
|
||||
Truthmark hierarchy:
|
||||
- Config: .truthmark/config.yml
|
||||
- Root route index: docs/truthmark/areas.md
|
||||
- Area route files: docs/truthmark/areas/**/*.md
|
||||
- Truth docs: docs/truth/**/*.md
|
||||
|
||||
Read and write boundaries:
|
||||
|
||||
- may read truth docs, routing docs, and relevant functional code
|
||||
- may write functional code only
|
||||
- must not edit truth docs or truth routing while realizing those docs
|
||||
|
||||
Report completion in this shape:
|
||||
|
||||
```md
|
||||
Truth Realize: completed
|
||||
|
||||
Truth docs used:
|
||||
- docs/truth/authentication/session-timeout.md
|
||||
|
||||
Code updated:
|
||||
- src/auth/session.ts
|
||||
|
||||
Verification:
|
||||
- npm test -- auth
|
||||
```
|
||||
Progressive disclosure:
|
||||
- support/procedure.md
|
||||
- support/report-template.md
|
||||
|
||||
@@ -0,0 +1,42 @@
|
||||
# Truthmark Realize Procedure
|
||||
|
||||
Generated by Truthmark 1.4.0. Rerun truthmark init after upgrades.
|
||||
|
||||
# Truthmark Realize
|
||||
|
||||
Use this skill only when the user explicitly asks to realize truth docs into code.
|
||||
|
||||
Invocations: OpenCode /skill truthmark-realize; Codex /truthmark-realize or $truthmark-realize; Claude Code /truthmark-realize; GitHub Copilot /truthmark-realize; Gemini CLI /truthmark:realize.
|
||||
|
||||
Truth Realize is doc-first:
|
||||
|
||||
- truth docs lead
|
||||
- code follows
|
||||
- Truth Realize never edits the truth docs it is realizing
|
||||
|
||||
Workflow:
|
||||
|
||||
1. Read the updated truth docs named by the user, or infer the relevant docs from docs/truthmark/areas.md.
|
||||
2. Read .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files, tests, and the relevant functional code.
|
||||
3. Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority.
|
||||
Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries.
|
||||
Truth-doc ownership gate:
|
||||
- before editing or relying on source truth docs before writing code, verify each target/source truth doc is a bounded owner for the behavior
|
||||
- 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
|
||||
4. Update functional code only so implementation matches bounded, current truth claims from the source docs.
|
||||
5. Do not edit truth docs or truth routing while realizing those docs.
|
||||
6. Run relevant tests for the changed code.
|
||||
7. Report changed code files and verification steps.
|
||||
Truthmark hierarchy:
|
||||
- Config: .truthmark/config.yml
|
||||
- Root route index: docs/truthmark/areas.md
|
||||
- Area route files: docs/truthmark/areas/**/*.md
|
||||
- Truth docs: docs/truth/**/*.md
|
||||
|
||||
Read and write boundaries:
|
||||
|
||||
- may read truth docs, routing docs, and relevant functional code
|
||||
- may write functional code only
|
||||
- must not edit truth docs or truth routing while realizing those docs
|
||||
@@ -0,0 +1,18 @@
|
||||
# Truthmark Realize Report Template
|
||||
|
||||
Generated by Truthmark 1.4.0. Rerun truthmark init after upgrades.
|
||||
|
||||
Report completion in this shape:
|
||||
|
||||
```md
|
||||
Truth Realize: completed
|
||||
|
||||
Truth docs used:
|
||||
- docs/truth/authentication/session-timeout.md
|
||||
|
||||
Code updated:
|
||||
- src/auth/session.ts
|
||||
|
||||
Verification:
|
||||
- npm test -- auth
|
||||
```
|
||||
@@ -1,123 +1,26 @@
|
||||
---
|
||||
name: truthmark-structure
|
||||
description: Use when routing or truth ownership is missing, stale, broad, overloaded, catch-all, unrouteable, mixed-owner, or needs split/repair. Not for documenting implemented behavior, syncing a code diff, or realizing docs into code.
|
||||
description: Use when routing or truth ownership is missing, stale, broad, overloaded, catch-all, unrouteable, mixed-owner, needs split/repair, or needs new area setup. Not for documenting implemented behavior, syncing a code diff, or realizing docs into code.
|
||||
argument-hint: Optional area, directory, or routing concern
|
||||
user-invocable: true
|
||||
truthmark-version: 1.3.0
|
||||
truthmark-version: 1.4.0
|
||||
---
|
||||
|
||||
# Truthmark Structure
|
||||
|
||||
Use this skill to design or repair Truthmark area structure.
|
||||
|
||||
Invocations: OpenCode /skill truthmark-structure; Codex /truthmark-structure or $truthmark-structure; Claude Code /truthmark-structure; GitHub Copilot /truthmark-structure; Gemini CLI /truthmark:structure.
|
||||
Truth Structure is agent-native:
|
||||
- inspect repository layout, current docs, .truthmark/config.yml, docs/truthmark/areas.md, and relevant code directly
|
||||
- Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority.
|
||||
Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries.
|
||||
- inspect the configured root route index at docs/truthmark/areas.md and relevant child route files under docs/truthmark/areas/
|
||||
- define areas by product or behavior ownership, not by mechanical directory mirroring
|
||||
- create or repair docs/truthmark/areas.md
|
||||
- create starter truth docs when useful and when they belong in the canonical current-truth surface
|
||||
- Starter truth docs must use closed YAML frontmatter bounded by opening and closing --- lines; include status, doc_type, last_reviewed, and source_of_truth inside that frontmatter.
|
||||
- Starter truth docs must include ## Product Decisions and ## Rationale sections.
|
||||
When creating or updating a truth doc, inspect the routed truth kind and use the matching `docs/templates/<kind>-doc.md` template.
|
||||
Supported kinds: behavior, contract, architecture, workflow, operations, and test-behavior.
|
||||
Align existing docs to that template while preserving accurate authored content.
|
||||
If the template is missing, use Scope, Product Decisions, Rationale, and the kind-specific current-truth section.
|
||||
Teams may edit the template files under docs/templates/ to define their local truth-doc standards.
|
||||
- use docs/truth/**, docs/architecture/**, or docs/standards/** for current truth destinations
|
||||
- use only canonical current-truth destinations for starter truth docs
|
||||
- keep active Product Decisions and Rationale in the canonical doc that owns the behavior
|
||||
- preserve unrelated authored content
|
||||
## Topology Governance
|
||||
Truth Structure owns documentation topology. Do not depend on humans to manually organize docs/truth. Treat the configured truth root as a managed semantic root.
|
||||
Inspect controllers, routes, handlers, services, packages, tests, existing truth docs, and route files; infer product and domain ownership from behavior boundaries, not from mechanical directory mirroring.
|
||||
When topology pressure exists, repair structure before creating or extending truth docs.
|
||||
Truth-doc ownership gate:
|
||||
- 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
|
||||
Product Decisions/Rationale preservation gate:
|
||||
- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions and Rationale sections in every source or touched truth doc
|
||||
- preserve each current decision and rationale in the bounded owner doc it governs; 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
|
||||
- after the edit, verify every touched truth doc still has Product Decisions and Rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked
|
||||
Topology pressure signals:
|
||||
- one area maps broad code such as src/**, app/**, server/**, services/**, or packages/**
|
||||
- one area maps multiple unrelated controllers, route groups, services, or bounded contexts
|
||||
- one truth doc owns unrelated behaviors or unrelated endpoint families
|
||||
- the configured truth root has many direct non-index docs
|
||||
- a changed controller, route, or service cannot map to a specific behavior doc
|
||||
- Truth Sync would need to create a new generic truth doc because routing is too broad
|
||||
- endpoint or controller names reveal domains missing from docs/truthmark/areas/**
|
||||
Use these review thresholds as guidance:
|
||||
- more than 10 direct truth docs in one folder
|
||||
- more than 15 leaf areas in one child route file
|
||||
- more than 8 truth docs mapped to one area
|
||||
- more than 5 controllers mapped through one catch-all area
|
||||
Repair rules:
|
||||
- split broad, overloaded, or catch-all areas into behavior-owned child route files
|
||||
- split mixed-owner truth docs into bounded owner docs before adding new behavior claims
|
||||
- create route files under docs/truthmark/areas/ when a product/domain boundary is clear
|
||||
- create behavior truth docs under the configured truth root only when behavior lacks a current doc
|
||||
- README.md files are indexes, not Truth Sync targets
|
||||
- prefer bounded leaf truth docs at <truth-root>/<domain>/<behavior>.md
|
||||
- keep behavior truth docs behavior-oriented, not endpoint-oriented
|
||||
- keep API endpoint details in the nearest contract truth doc when such a doc exists
|
||||
- update routing so future Truth Sync can target small docs
|
||||
- preserve existing authored docs; move or rewrite only when needed to remove ambiguity
|
||||
- report Truth docs split when one broad or mixed-owner truth doc becomes multiple bounded docs
|
||||
Truth-doc shape repair gate:
|
||||
- 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
|
||||
- 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
|
||||
- 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, Product 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
|
||||
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 routed canonical current-truth docs missing Product Decisions or Rationale sections.
|
||||
- If an existing canonical doc lacks either section, add the missing heading beside Current Behavior with a concise current-state placeholder or active decision.
|
||||
Portable fallback:
|
||||
- If this skill surface is unavailable, perform the same workflow directly from committed repository files.
|
||||
- Do not require the truthmark CLI.
|
||||
- Read .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, canonical docs, and representative implementation code.
|
||||
- Use a subagent only when the host supports that pattern; otherwise perform the topology repair inline.
|
||||
Truthmark hierarchy:
|
||||
- Config: .truthmark/config.yml
|
||||
- Root route index: docs/truthmark/areas.md
|
||||
- Area route files: docs/truthmark/areas/**/*.md
|
||||
- Truth docs: docs/truth/**/*.md
|
||||
Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed.
|
||||
Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail.
|
||||
Update Product Decisions and Rationale when a decision changes behavior.
|
||||
Report completion in this shape:
|
||||
```md
|
||||
Truth Structure: completed
|
||||
Topology reviewed:
|
||||
- controllers: src/auth/**
|
||||
- docs root: docs/truth
|
||||
- route files: docs/truthmark/areas.md
|
||||
Areas reviewed:
|
||||
- src/auth/**
|
||||
Routing updated:
|
||||
- docs/truthmark/areas.md
|
||||
Truth docs created:
|
||||
- docs/truth/authentication/session.md
|
||||
Truth docs split:
|
||||
- docs/truth/authentication/README.md -> docs/truth/authentication/session.md
|
||||
Truth docs restructured:
|
||||
- docs/truth/authentication/README.md
|
||||
Evidence checked:
|
||||
- Claim: Session behavior belongs to a dedicated Authentication truth owner.
|
||||
Evidence: src/auth/** / docs/truthmark/areas.md:7
|
||||
Result: supported
|
||||
Topology decisions:
|
||||
- Added an Authentication area because session behavior has a distinct code surface and truth owner.
|
||||
Notes:
|
||||
- Added an Authentication area for session behavior.
|
||||
```
|
||||
|
||||
Quick procedure:
|
||||
- Follow docs/ai/repo-rules.md as the repository instruction authority.
|
||||
- Read .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, current docs, and relevant code directly.
|
||||
- Define areas by product or behavior ownership, not by mechanical directory mirroring.
|
||||
- Do not edit functional code.
|
||||
- Read support/procedure.md before writing route or starter truth-doc changes.
|
||||
- Read support/report-template.md before the final report.
|
||||
|
||||
Progressive disclosure:
|
||||
- support/procedure.md
|
||||
- support/report-template.md
|
||||
- support/subagents-and-leases.md
|
||||
|
||||
@@ -0,0 +1,109 @@
|
||||
# Truthmark Structure Procedure
|
||||
|
||||
Generated by Truthmark 1.4.0. Rerun truthmark init after upgrades.
|
||||
|
||||
Use this skill to design or repair Truthmark area structure.
|
||||
Invocations: OpenCode /skill truthmark-structure; Codex /truthmark-structure or $truthmark-structure; Claude Code /truthmark-structure; GitHub Copilot /truthmark-structure; Gemini CLI /truthmark:structure.
|
||||
Truth Structure is agent-native:
|
||||
- inspect repository layout, current docs, .truthmark/config.yml, docs/truthmark/areas.md, and relevant code directly
|
||||
- Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority.
|
||||
Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries.
|
||||
- inspect the configured root route index at docs/truthmark/areas.md and relevant child route files under docs/truthmark/areas/
|
||||
- define areas by product or behavior ownership, not by mechanical directory mirroring
|
||||
- create or repair docs/truthmark/areas.md
|
||||
- create starter truth docs when useful and when they belong in the canonical current-truth surface
|
||||
- Starter truth docs must use closed YAML frontmatter bounded by opening and closing --- lines; include status, doc_type, last_reviewed, and source_of_truth inside that frontmatter.
|
||||
- Starter truth docs must include ## Product Decisions and ## Rationale sections.
|
||||
|
||||
When creating or updating a truth doc, inspect the routed truth kind and use the matching `docs/templates/<kind>-doc.md` template.
|
||||
Supported kinds: behavior, contract, architecture, workflow, operations, and test-behavior.
|
||||
Align existing docs to that template while preserving accurate authored content.
|
||||
If the template is missing, use Scope, Product Decisions, Rationale, and the kind-specific current-truth section.
|
||||
Teams may edit the template files under docs/templates/ to define their local truth-doc standards.
|
||||
- use docs/truth/**, docs/architecture/**, or docs/standards/** for current truth destinations
|
||||
- use only canonical current-truth destinations for starter truth docs
|
||||
- keep active Product Decisions and Rationale in the canonical doc that owns the behavior
|
||||
- preserve unrelated authored content
|
||||
## New area setup
|
||||
Use when a user asks to onboard a new code area into Truthmark, a new package, controller, domain, or product area lacks bounded truth ownership, or a new product area needs routing and starter truth docs.
|
||||
Do:
|
||||
- inspect the named code area
|
||||
- infer bounded product or behavior ownership
|
||||
- choose the owning route when ownership is clear; otherwise propose the route and block for review
|
||||
- create or update the child route entry or file
|
||||
- create starter truth docs only where current truth is missing
|
||||
- report the initial truth boundary
|
||||
Do not:
|
||||
- do not edit functional code
|
||||
- do not perform full behavior documentation unless evidence is inspected and the task explicitly asks for it
|
||||
- do not patch broad or mixed-owner docs in place
|
||||
- do not create generic catch-all docs
|
||||
- do not treat README files as Sync targets
|
||||
## Topology Governance
|
||||
Truth Structure owns documentation topology. Do not depend on humans to manually organize docs/truth. Treat the configured truth root as a managed semantic root.
|
||||
Inspect controllers, routes, handlers, services, packages, tests, existing truth docs, and route files; infer product and domain ownership from behavior boundaries, not from mechanical directory mirroring.
|
||||
When topology pressure exists, repair structure before creating or extending truth docs.
|
||||
Truth-doc ownership gate:
|
||||
- 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
|
||||
Product Decisions/Rationale preservation gate:
|
||||
- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions and Rationale sections in every source or touched truth doc
|
||||
- preserve each current decision and rationale in the bounded owner doc it governs; 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
|
||||
- after the edit, verify every touched truth doc still has Product Decisions and Rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked
|
||||
Topology pressure signals:
|
||||
- one area maps broad code such as src/**, app/**, server/**, services/**, or packages/**
|
||||
- one area maps multiple unrelated controllers, route groups, services, or bounded contexts
|
||||
- one truth doc owns unrelated behaviors or unrelated endpoint families
|
||||
- the configured truth root has many direct non-index docs
|
||||
- a changed controller, route, or service cannot map to a specific behavior doc
|
||||
- Truth Sync would need to create a new generic truth doc because routing is too broad
|
||||
- endpoint or controller names reveal domains missing from docs/truthmark/areas/**
|
||||
Use these review thresholds as guidance:
|
||||
- more than 10 direct truth docs in one folder
|
||||
- more than 15 leaf areas in one child route file
|
||||
- more than 8 truth docs mapped to one area
|
||||
- more than 5 controllers mapped through one catch-all area
|
||||
Repair rules:
|
||||
- split broad, overloaded, or catch-all areas into behavior-owned child route files
|
||||
- split mixed-owner truth docs into bounded owner docs before adding new behavior claims
|
||||
- create route files under docs/truthmark/areas/ when a product/domain boundary is clear
|
||||
- create behavior truth docs under the configured truth root only when behavior lacks a current doc
|
||||
- README.md files are indexes, not Truth Sync targets
|
||||
- prefer bounded leaf truth docs at <truth-root>/<domain>/<behavior>.md
|
||||
- keep behavior truth docs behavior-oriented, not endpoint-oriented
|
||||
- keep API endpoint details in the nearest contract truth doc when such a doc exists
|
||||
- update routing so future Truth Sync can target small docs
|
||||
- preserve existing authored docs; move or rewrite only when needed to remove ambiguity
|
||||
- report Truth docs split when one broad or mixed-owner truth doc becomes multiple bounded docs
|
||||
Truth-doc shape repair gate:
|
||||
- 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
|
||||
- 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
|
||||
- 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, Product 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
|
||||
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 routed canonical current-truth docs missing Product Decisions or Rationale sections.
|
||||
- If an existing canonical doc lacks either section, add the missing heading beside Current Behavior with a concise current-state placeholder or active decision.
|
||||
Portable fallback:
|
||||
- If this skill surface is unavailable, perform the same workflow directly from committed repository files.
|
||||
- Do not require the truthmark CLI.
|
||||
- Read .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, canonical docs, and representative implementation code.
|
||||
- Use a subagent only when the host supports that pattern; otherwise perform the topology repair inline.
|
||||
Truthmark hierarchy:
|
||||
- Config: .truthmark/config.yml
|
||||
- Root route index: docs/truthmark/areas.md
|
||||
- Area route files: docs/truthmark/areas/**/*.md
|
||||
- Truth docs: docs/truth/**/*.md
|
||||
Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed.
|
||||
Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail.
|
||||
Update Product Decisions and Rationale when a decision changes behavior.
|
||||
@@ -0,0 +1,35 @@
|
||||
# Truthmark Structure Report Template
|
||||
|
||||
Generated by Truthmark 1.4.0. Rerun truthmark init after upgrades.
|
||||
|
||||
Report completion in this shape:
|
||||
```md
|
||||
Truth Structure: completed
|
||||
Topology reviewed:
|
||||
- controllers: src/auth/**
|
||||
- docs root: docs/truth
|
||||
- route files: docs/truthmark/areas.md
|
||||
Areas reviewed:
|
||||
- src/auth/**
|
||||
Routing updated:
|
||||
- docs/truthmark/areas.md
|
||||
Initial truth boundary:
|
||||
- Area: Authentication
|
||||
- Code: src/auth/**
|
||||
- Truth owner: docs/truth/authentication/session.md
|
||||
- Scope: session behavior only
|
||||
Truth docs created:
|
||||
- docs/truth/authentication/session.md
|
||||
Truth docs split:
|
||||
- docs/truth/authentication/README.md -> docs/truth/authentication/session.md
|
||||
Truth docs restructured:
|
||||
- docs/truth/authentication/README.md
|
||||
Evidence checked:
|
||||
- Claim: Session behavior belongs to a dedicated Authentication truth owner.
|
||||
Evidence: src/auth/** / docs/truthmark/areas.md:7
|
||||
Result: supported
|
||||
Topology decisions:
|
||||
- Added an Authentication area because session behavior has a distinct code surface and truth owner.
|
||||
Notes:
|
||||
- Added an Authentication area for session behavior.
|
||||
```
|
||||
@@ -0,0 +1,10 @@
|
||||
# Truthmark Structure Subagents And Leases
|
||||
|
||||
Generated by Truthmark 1.4.0. Rerun truthmark init after upgrades.
|
||||
|
||||
OpenCode subagent mode:
|
||||
- use automatically when this workflow runs in OpenCode and the parent agent chooses bounded subagent fan-out
|
||||
- dispatch read-only project subagents only: @truth-route-auditor
|
||||
- workers inspect checkout evidence directly, return structured findings, and must not edit files
|
||||
- parent supplies bounded evidence shards; workers must not preload host instruction files or repo-wide policy docs unless assigned as evidence
|
||||
- Parent agent owns all Truth Structure writes and final topology decisions
|
||||
@@ -3,135 +3,26 @@ name: truthmark-sync
|
||||
description: Use automatically at finish-time after functional code changes, or explicit /truthmark-sync, $truthmark-sync, or /truthmark:sync. Skip docs-only, formatting-only, behavior-preserving renames, missing config, and no-code changes. Not for doc-first realization or manual topology design.
|
||||
argument-hint: Optional changed-code area, truth-doc area, or sync focus
|
||||
user-invocable: true
|
||||
truthmark-version: 1.3.0
|
||||
truthmark-version: 1.4.0
|
||||
---
|
||||
|
||||
# Truthmark Sync
|
||||
|
||||
Use this skill automatically before finishing when functional code changed since the last successful Truth Sync. Also run it immediately when the user explicitly invokes Truth Sync.
|
||||
|
||||
Invocations: OpenCode /skill truthmark-sync; Codex /truthmark-sync or $truthmark-sync; Claude Code /truthmark-sync; GitHub Copilot /truthmark-sync; Gemini CLI /truthmark:sync.
|
||||
Explicit invocation runs immediately. Later functional-code changes reopen the finish-time requirement, and an earlier explicit run satisfies the finish gate only if no later functional-code changes occur.
|
||||
Skip when changes are documentation-only, formatting-only, clearly behavior-preserving renames with no truth impact, when no Truthmark config exists yet, or when there are no functional code changes.
|
||||
Parent workflow:
|
||||
1. Inspect git status, staged changes, unstaged changes, and untracked files directly.
|
||||
2. Read .truthmark/config.yml, the configured root route index at docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, and relevant canonical docs.
|
||||
3. Identify functional-code changes and the nearest truth docs or routing repairs.
|
||||
4. Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority.
|
||||
Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries.
|
||||
5. Code verification is parent-owned: follow repository instructions and task context, and report what ran or why it did not run.
|
||||
6. Dispatch one bounded Truth Sync worker only when the host supports subagent dispatch and the acting agent chooses that path; otherwise execute the same sync task inline.
|
||||
Topology quality gate:
|
||||
- before updating truth docs, verify the changed code resolves to a specific behavior-owned area and bounded truth owner
|
||||
- if routing is missing, stale, broad, overloaded, catch-all route only, or cannot map changed code to a bounded truth owner, do not create another generic 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
|
||||
- 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
|
||||
Truth-doc ownership gate:
|
||||
- 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
|
||||
Product Decisions/Rationale preservation gate:
|
||||
- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions and Rationale sections in every source or touched truth doc
|
||||
- preserve each current decision and rationale in the bounded owner doc it governs; 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
|
||||
- after the edit, verify every touched truth doc still has Product Decisions and 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 `docs/templates/<kind>-doc.md` template.
|
||||
Supported kinds: behavior, contract, architecture, workflow, operations, and test-behavior.
|
||||
Align existing docs to that template while preserving accurate authored content.
|
||||
If the template is missing, use Scope, Product Decisions, Rationale, and the kind-specific current-truth section.
|
||||
Teams may edit the template files under docs/templates/ to define their local truth-doc standards.
|
||||
Truth-doc shape repair gate:
|
||||
- Truth Sync may restructure only truth docs impacted by the current functional-code change.
|
||||
- repair shape in place only after the ownership gate 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
|
||||
- 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:
|
||||
- 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, Product 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
|
||||
- if no impacted doc changed, report why truth was already current or why sync was skipped
|
||||
Repository intelligence artifacts are optional derived context: RepoIndex, RouteMap, ImpactSet, and ContextPack may guide routing, context selection, and verification planning when available.
|
||||
They do not override checkout evidence, canonical truth docs, route files, or workflow write boundaries.
|
||||
If unavailable, inspect .truthmark/config.yml, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated.
|
||||
Optional validation tooling:
|
||||
- you may run truthmark check when local tooling is available
|
||||
- do not require the truthmark binary; direct checkout inspection is the canonical path
|
||||
- optional validation must not replace agent judgment about docs and routing
|
||||
- update Product Decisions and Rationale when a behavior change comes from a decision change
|
||||
Truthmark hierarchy:
|
||||
- Config: .truthmark/config.yml
|
||||
- Root route index: docs/truthmark/areas.md
|
||||
- Area route files: docs/truthmark/areas/**/*.md
|
||||
- Truth docs: docs/truth/**/*.md
|
||||
Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed.
|
||||
Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail.
|
||||
Update Product Decisions and Rationale when a decision changes behavior.
|
||||
### Truth Sync Worker
|
||||
The parent provides the task focus and any repository context already gathered.
|
||||
Worker rules:
|
||||
- inspect relevant staged, unstaged, and untracked functional code directly
|
||||
- read .truthmark/config.yml, docs/truthmark/areas.md, and canonical truth docs directly
|
||||
- Code verification is parent-owned; report what was run or why it was not run
|
||||
- may write truth docs and docs/truthmark/areas.md only for Truth Sync alignment
|
||||
- must not rewrite functional code
|
||||
Return result in this shape:
|
||||
- status: completed | blocked
|
||||
- changedCodeReviewed: string[]
|
||||
- ownershipReviewed: string[]
|
||||
- structureRequired?: string[]
|
||||
- truthDocsUpdated: string[]
|
||||
- routingDocsUpdated: string[]
|
||||
- truthDocsSplit?: string[]
|
||||
- evidenceChecked: { claim: string; evidence: string[]; result: supported | narrowed | removed | blocked }[]
|
||||
- notes: string[]
|
||||
- blockedReason?: string
|
||||
- manualReviewFiles?: string[]
|
||||
Parent post-sync verification:
|
||||
- verify only truth docs and docs/truthmark/areas.md changed during sync
|
||||
- block on any unrelated diff caused by the sync step
|
||||
- block if functional code changed during sync
|
||||
- verify the worker report matches the required headings and sections
|
||||
- validate the final report against the structured Truth Sync report contract, including Claim, Evidence, and Result entries under Evidence checked
|
||||
- verify the updated docs correspond to the reviewed changed-code surface
|
||||
- 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
|
||||
Report completion in this shape:
|
||||
```md
|
||||
Truth Sync: completed
|
||||
|
||||
Changed code reviewed:
|
||||
- src/auth/session.ts
|
||||
Quick procedure:
|
||||
- Follow docs/ai/repo-rules.md as the repository instruction authority.
|
||||
- Skip docs-only, formatting-only, behavior-preserving renames with no truth impact, missing config, and no-code changes.
|
||||
- Read .truthmark/config.yml, the configured root route index at docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, and relevant canonical docs.
|
||||
- direct checkout inspection is the canonical path; do not require the truthmark binary.
|
||||
- May write canonical truth docs and truth routing files only; must not rewrite functional code.
|
||||
- Read support/procedure.md before editing truth docs.
|
||||
- Read support/subagents-and-leases.md before dispatching or accepting worker output.
|
||||
- Read support/report-template.md before the final report.
|
||||
|
||||
Truth docs updated:
|
||||
- docs/truth/repository/overview.md
|
||||
|
||||
Evidence checked:
|
||||
- Claim: Session timeout behavior is documented in the mapped repository truth doc.
|
||||
Evidence: src/auth/session.ts:12 / docs/truthmark/areas.md:11
|
||||
Result: supported
|
||||
|
||||
Notes:
|
||||
- Updated session timeout behavior.
|
||||
```
|
||||
Blocked report example:
|
||||
```md
|
||||
Truth Sync: blocked
|
||||
|
||||
Reason:
|
||||
- routing repair is not allowed
|
||||
|
||||
Files requiring manual review:
|
||||
- docs/truthmark/areas.md
|
||||
|
||||
Next action:
|
||||
- update routing metadata and rerun Truth Sync
|
||||
```
|
||||
Progressive disclosure:
|
||||
- support/procedure.md
|
||||
- support/report-template.md
|
||||
- support/subagents-and-leases.md
|
||||
|
||||
@@ -0,0 +1,82 @@
|
||||
# Truthmark Sync Procedure
|
||||
|
||||
Generated by Truthmark 1.4.0. Rerun truthmark init after upgrades.
|
||||
|
||||
Use this skill automatically before finishing when functional code changed since the last successful Truth Sync. Also run it immediately when the user explicitly invokes Truth Sync.
|
||||
Invocations: OpenCode /skill truthmark-sync; Codex /truthmark-sync or $truthmark-sync; Claude Code /truthmark-sync; GitHub Copilot /truthmark-sync; Gemini CLI /truthmark:sync.
|
||||
Explicit invocation runs immediately. Later functional-code changes reopen the finish-time requirement, and an earlier explicit run satisfies the finish gate only if no later functional-code changes occur.
|
||||
Skip when changes are documentation-only, formatting-only, clearly behavior-preserving renames with no truth impact, when no Truthmark config exists yet, or when there are no functional code changes.
|
||||
Parent workflow:
|
||||
1. Inspect git status, staged changes, unstaged changes, and untracked files directly.
|
||||
2. Read .truthmark/config.yml, the configured root route index at docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, and relevant canonical docs.
|
||||
3. Identify functional-code changes and the nearest truth docs or routing repairs.
|
||||
4. Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority.
|
||||
Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries.
|
||||
5. Code verification is parent-owned: follow repository instructions and task context, and report what ran or why it did not run.
|
||||
6. Dispatch 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:
|
||||
- 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
|
||||
- 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
|
||||
Truth-doc ownership gate:
|
||||
- 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
|
||||
Product Decisions/Rationale preservation gate:
|
||||
- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions and Rationale sections in every source or touched truth doc
|
||||
- preserve each current decision and rationale in the bounded owner doc it governs; 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
|
||||
- after the edit, verify every touched truth doc still has Product Decisions and 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 `docs/templates/<kind>-doc.md` template.
|
||||
Supported kinds: behavior, contract, architecture, workflow, operations, and test-behavior.
|
||||
Align existing docs to that template while preserving accurate authored content.
|
||||
If the template is missing, use Scope, Product Decisions, Rationale, and the kind-specific current-truth section.
|
||||
Teams may edit the template files under docs/templates/ to define their local truth-doc standards.
|
||||
Truth-doc shape repair gate:
|
||||
- Truth Sync may restructure only truth docs impacted by the current functional-code change.
|
||||
- repair shape in place only after the ownership gate 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
|
||||
- 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:
|
||||
- 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, Product 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
|
||||
- if no impacted doc changed, report why truth was already current or why sync was skipped
|
||||
Repository intelligence artifacts are optional derived context: RepoIndex, RouteMap, ImpactSet, and ContextPack may guide routing, context selection, and verification planning when available.
|
||||
They do not override checkout evidence, canonical truth docs, route files, or workflow write boundaries.
|
||||
If unavailable, inspect .truthmark/config.yml, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated.
|
||||
Optional validation tooling:
|
||||
- you may run truthmark check when local tooling is available
|
||||
- do not require the truthmark binary; direct checkout inspection is the canonical path
|
||||
- optional validation must not replace agent judgment about docs and routing
|
||||
- update Product Decisions and Rationale when a behavior change comes from a decision change
|
||||
Truthmark hierarchy:
|
||||
- Config: .truthmark/config.yml
|
||||
- Root route index: docs/truthmark/areas.md
|
||||
- Area route files: docs/truthmark/areas/**/*.md
|
||||
- Truth docs: docs/truth/**/*.md
|
||||
Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed.
|
||||
Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail.
|
||||
Update Product Decisions and Rationale when a decision changes behavior.
|
||||
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
|
||||
- validate the final report against the structured Truth Sync report contract, including Claim, Evidence, and Result entries under Evidence checked
|
||||
- verify the updated docs correspond to the reviewed changed-code surface
|
||||
- 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
|
||||
@@ -0,0 +1,35 @@
|
||||
# Truthmark Sync Report Template
|
||||
|
||||
Generated by Truthmark 1.4.0. Rerun truthmark init after upgrades.
|
||||
|
||||
Report completion in this shape:
|
||||
```md
|
||||
Truth Sync: completed
|
||||
|
||||
Changed code reviewed:
|
||||
- src/auth/session.ts
|
||||
|
||||
Truth docs updated:
|
||||
- docs/truth/repository/overview.md
|
||||
|
||||
Evidence checked:
|
||||
- Claim: Session timeout behavior is documented in the mapped repository truth doc.
|
||||
Evidence: src/auth/session.ts:12 / docs/truthmark/areas.md:11
|
||||
Result: supported
|
||||
|
||||
Notes:
|
||||
- Updated session timeout behavior.
|
||||
```
|
||||
Blocked report example:
|
||||
```md
|
||||
Truth Sync: blocked
|
||||
|
||||
Reason:
|
||||
- routing repair is not allowed
|
||||
|
||||
Files requiring manual review:
|
||||
- docs/truthmark/areas.md
|
||||
|
||||
Next action:
|
||||
- update routing metadata and rerun Truth Sync
|
||||
```
|
||||
@@ -0,0 +1,14 @@
|
||||
# Truthmark Sync Subagents And Leases
|
||||
|
||||
Generated by Truthmark 1.4.0. Rerun truthmark init after upgrades.
|
||||
|
||||
OpenCode subagent mode:
|
||||
- use automatically when this workflow runs in OpenCode and the parent agent chooses bounded subagent fan-out
|
||||
- dispatch read-only project subagents for verification: @truth-route-auditor, @truth-claim-verifier
|
||||
- read-only workers inspect checkout evidence directly, return structured findings, and must not edit files
|
||||
- parent supplies bounded evidence shards; read-only workers must not preload host instruction files or repo-wide policy docs unless assigned as evidence
|
||||
- dispatch write-capable project subagents only with explicit write leases: @truth-doc-writer
|
||||
- each write lease must name objective, required reads, allowed writes, forbidden writes, evidence, verification, and report fields
|
||||
- write workers must stop when a required edit is off-lease and report status, filesChanged, evidence, offLeaseChanges, blockers, and notes
|
||||
- parent must inspect the actual checkout diff against each lease before accepting a worker report
|
||||
- Parent agent owns Truth Sync acceptance, lease validation, and final report
|
||||
Reference in New Issue
Block a user