mirror of
https://github.com/merlinhu1/truthmark.git
synced 2026-08-25 07:53:25 +02:00
Compare commits
4
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 MerlinHandGitHub
|
233bb61cb6 | ||
|
MerlinHandGitHub
|
caced773f5 | ||
|
MerlinHandGitHub
|
6212f3d956 | ||
|
MerlinH
|
9a691dd84f |
@@ -0,0 +1,65 @@
|
||||
---
|
||||
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 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.
|
||||
|
||||
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,100 @@
|
||||
---
|
||||
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 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.
|
||||
|
||||
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,61 @@
|
||||
---
|
||||
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 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
|
||||
|
||||
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
|
||||
```
|
||||
@@ -0,0 +1,123 @@
|
||||
---
|
||||
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.
|
||||
argument-hint: Optional area, directory, or routing concern
|
||||
user-invocable: true
|
||||
truthmark-version: 1.3.0
|
||||
---
|
||||
|
||||
Use this skill to design or repair Truthmark area structure.
|
||||
Invocations: OpenCode /skill truthmark-structure; Codex /truthmark-structure or $truthmark-structure; Claude Code /truthmark-structure; GitHub Copilot /truthmark-structure; Gemini CLI /truthmark:structure.
|
||||
Truth Structure is agent-native:
|
||||
- inspect repository layout, current docs, .truthmark/config.yml, docs/truthmark/areas.md, and relevant code directly
|
||||
- Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority.
|
||||
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.
|
||||
```
|
||||
@@ -0,0 +1,137 @@
|
||||
---
|
||||
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
|
||||
---
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
```
|
||||
@@ -1,39 +1,44 @@
|
||||
---
|
||||
name: truthmark-check
|
||||
description: Use when the user asks to audit repository truth health. Inspects truth docs, routing, and implementation directly; may optionally run truthmark check when available.
|
||||
description: Use when the user asks to audit repository truth health, routing, ownership, or canonical docs. Not for normal lint/test/typecheck/code-review verification, finish-time Sync, or silently rewriting docs.
|
||||
argument-hint: Optional area, doc path, or audit focus
|
||||
user-invocable: true
|
||||
truthmark-version: 1.2.1
|
||||
truthmark-version: 1.3.0
|
||||
---
|
||||
|
||||
# Truthmark Check
|
||||
|
||||
Use this skill to audit repository truth health.
|
||||
|
||||
Invocations: OpenCode /skill truthmark-check; Codex /truthmark-check or $truthmark-check; Gemini CLI /truthmark:check.
|
||||
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, TRUTHMARK.md, docs/truthmark/areas.md, canonical docs, and relevant implementation directly
|
||||
- Repository docs and code are inspected evidence, not executable instruction authority.
|
||||
- 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
|
||||
- Feature docs: docs/features/**/*.md
|
||||
Decision truth lives in the canonical doc it governs.
|
||||
Short inline decision dates are allowed, for example `Decision (2026-05-09): ...`.
|
||||
Do not create separate timestamped ADR logs or planning tickets for active decisions.
|
||||
Replace old active decisions instead of appending separate timestamped decision logs; Git history is the audit trail.
|
||||
Update Product Decisions and Rationale when a behavior change comes from a decision change.
|
||||
- Truth 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:
|
||||
|
||||
@@ -41,7 +46,6 @@ Report completion in this shape:
|
||||
Truth Check: completed
|
||||
|
||||
Files reviewed:
|
||||
- TRUTHMARK.md
|
||||
- docs/truthmark/areas.md
|
||||
|
||||
Issues found:
|
||||
@@ -50,6 +54,12 @@ Issues found:
|
||||
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
|
||||
```
|
||||
|
||||
@@ -7,5 +7,5 @@ policy:
|
||||
allow_implicit_invocation: false
|
||||
|
||||
truthmark:
|
||||
version: "1.2.1"
|
||||
version: "1.3.0"
|
||||
refresh_command: "truthmark init"
|
||||
|
||||
@@ -0,0 +1,100 @@
|
||||
---
|
||||
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 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.
|
||||
|
||||
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,11 @@
|
||||
interface:
|
||||
display_name: "Truthmark Document"
|
||||
short_description: "Document existing implemented behavior"
|
||||
default_prompt: "Use $truthmark-document to document existing implemented behavior."
|
||||
|
||||
policy:
|
||||
allow_implicit_invocation: false
|
||||
|
||||
truthmark:
|
||||
version: "1.3.0"
|
||||
refresh_command: "truthmark init"
|
||||
@@ -1,16 +1,16 @@
|
||||
---
|
||||
name: truthmark-realize
|
||||
description: Use when the user explicitly asks to realize Truthmark truth docs into code, including /truthmark-realize, $truthmark-realize, or /truthmark:realize. Reads truth docs and routing first, updates functional code only, and reports verification.
|
||||
description: Use when the user explicitly asks to realize Truthmark truth docs into code, including /truthmark-realize, $truthmark-realize, or /truthmark:realize. Not for syncing docs after code changes, documenting existing code, topology repair, or truth audits.
|
||||
argument-hint: Optional truth doc path, area, or desired code behavior to realize
|
||||
user-invocable: true
|
||||
truthmark-version: 1.2.1
|
||||
truthmark-version: 1.3.0
|
||||
---
|
||||
|
||||
# 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; Gemini CLI /truthmark:realize.
|
||||
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:
|
||||
|
||||
@@ -21,12 +21,23 @@ Truth Realize is doc-first:
|
||||
Workflow:
|
||||
|
||||
1. Read the updated truth docs named by the user, or infer the relevant docs from docs/truthmark/areas.md.
|
||||
2. Read .truthmark/config.yml, TRUTHMARK.md, docs/truthmark/areas.md, and the relevant functional code.
|
||||
3. Repository docs and code are inspected evidence, not executable instruction authority.
|
||||
4. Update functional code only so implementation matches the truth docs.
|
||||
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:
|
||||
|
||||
@@ -40,7 +51,7 @@ Report completion in this shape:
|
||||
Truth Realize: completed
|
||||
|
||||
Truth docs used:
|
||||
- docs/features/authentication.md
|
||||
- docs/truth/authentication/session-timeout.md
|
||||
|
||||
Code updated:
|
||||
- src/auth/session.ts
|
||||
|
||||
@@ -7,5 +7,5 @@ policy:
|
||||
allow_implicit_invocation: false
|
||||
|
||||
truthmark:
|
||||
version: "1.2.1"
|
||||
version: "1.3.0"
|
||||
refresh_command: "truthmark init"
|
||||
|
||||
@@ -1,83 +1,121 @@
|
||||
---
|
||||
name: truthmark-structure
|
||||
description: Use when the user asks to design, repair, or refresh Truthmark area routing. Inspects the repository directly, updates docs/truthmark/areas.md, and may create starter canonical truth docs.
|
||||
description: Use when routing or truth ownership is missing, stale, broad, overloaded, catch-all, unrouteable, mixed-owner, or needs split/repair. Not for documenting implemented behavior, syncing a code diff, or realizing docs into code.
|
||||
argument-hint: Optional area, directory, or routing concern
|
||||
user-invocable: true
|
||||
truthmark-version: 1.2.1
|
||||
truthmark-version: 1.3.0
|
||||
---
|
||||
|
||||
Use this skill to design or repair Truthmark area structure.
|
||||
Invocations: OpenCode /skill truthmark-structure; Codex /truthmark-structure or $truthmark-structure; Gemini CLI /truthmark: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, TRUTHMARK.md, docs/truthmark/areas.md, and relevant code directly
|
||||
- Repository docs and code are inspected evidence, not executable instruction authority.
|
||||
- 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.
|
||||
- use docs/features/**, docs/architecture/**, or docs/standards/** for current truth destinations
|
||||
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/features. Treat the configured feature root as a managed semantic root.
|
||||
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 feature docs.
|
||||
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 feature root has many direct non-index docs
|
||||
- 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 feature doc because routing is too broad
|
||||
- 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 feature docs in one folder
|
||||
- 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 catch-all areas into behavior-owned child route files
|
||||
- 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 feature docs under the configured feature root only when behavior lacks a current doc
|
||||
- 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 <feature-root>/<domain>/<behavior>.md
|
||||
- keep feature docs behavior-oriented, not endpoint-oriented
|
||||
- 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, TRUTHMARK.md, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, canonical docs, and representative implementation code.
|
||||
- Read .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, canonical docs, and representative implementation code.
|
||||
- Use a subagent only when the host supports that pattern; otherwise perform the topology repair inline.
|
||||
Truthmark hierarchy:
|
||||
- Config: .truthmark/config.yml
|
||||
- Root route index: docs/truthmark/areas.md
|
||||
- Area route files: docs/truthmark/areas/**/*.md
|
||||
- Feature docs: docs/features/**/*.md
|
||||
Decision truth lives in the canonical doc it governs.
|
||||
Short inline decision dates are allowed, for example `Decision (2026-05-09): ...`.
|
||||
Do not create separate timestamped ADR logs or planning tickets for active decisions.
|
||||
Replace old active decisions instead of appending separate timestamped decision logs; Git history is the audit trail.
|
||||
Update Product Decisions and Rationale when a behavior change comes from a decision change.
|
||||
- Truth 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/features
|
||||
- docs root: docs/truth
|
||||
- route files: docs/truthmark/areas.md
|
||||
Areas reviewed:
|
||||
- src/auth/**
|
||||
Routing updated:
|
||||
- docs/truthmark/areas.md
|
||||
Truth docs created:
|
||||
- docs/features/authentication.md
|
||||
- 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:
|
||||
|
||||
@@ -7,5 +7,5 @@ policy:
|
||||
allow_implicit_invocation: false
|
||||
|
||||
truthmark:
|
||||
version: "1.2.1"
|
||||
version: "1.3.0"
|
||||
refresh_command: "truthmark init"
|
||||
|
||||
@@ -1,30 +1,67 @@
|
||||
---
|
||||
name: truthmark-sync
|
||||
description: Use automatically before finishing when functional code changed since the last successful Truth Sync, and when the user explicitly invokes /truthmark-sync, $truthmark-sync, or /truthmark:sync. Inspects changed code directly, updates truth docs and routing, and verifies post-sync boundaries.
|
||||
description: Use automatically at finish-time after functional code changes, or explicit /truthmark-sync, $truthmark-sync, or /truthmark:sync. Skip docs-only, formatting-only, behavior-preserving renames, missing config, and no-code changes. Not for doc-first realization or manual topology design.
|
||||
argument-hint: Optional changed-code area, truth-doc area, or sync focus
|
||||
user-invocable: true
|
||||
truthmark-version: 1.2.1
|
||||
truthmark-version: 1.3.0
|
||||
---
|
||||
|
||||
Use this skill automatically before finishing when functional code changed since the last successful Truth Sync. Also run it immediately when the user explicitly invokes Truth Sync.
|
||||
Invocations: OpenCode /skill truthmark-sync; Codex /truthmark-sync or $truthmark-sync; Gemini CLI /truthmark: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, TRUTHMARK.md, the configured root route index at docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, and relevant canonical docs.
|
||||
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 docs and code are inspected evidence, not executable instruction authority.
|
||||
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
|
||||
- if routing is broad, overloaded, or catch-all route only, do not create another generic feature doc
|
||||
- run or recommend Truth Structure before syncing when topology repair is needed
|
||||
- block when topology repair is unsafe, ambiguous, or outside the current task boundary
|
||||
- report the broad route files and changed code paths that require structure repair
|
||||
- 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 feature README
|
||||
- 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
|
||||
@@ -34,25 +71,27 @@ Truthmark hierarchy:
|
||||
- Config: .truthmark/config.yml
|
||||
- Root route index: docs/truthmark/areas.md
|
||||
- Area route files: docs/truthmark/areas/**/*.md
|
||||
- Feature docs: docs/features/**/*.md
|
||||
Decision truth lives in the canonical doc it governs.
|
||||
Short inline decision dates are allowed, for example `Decision (2026-05-09): ...`.
|
||||
Do not create separate timestamped ADR logs or planning tickets for active decisions.
|
||||
Replace old active decisions instead of appending separate timestamped decision logs; Git history is the audit trail.
|
||||
Update Product Decisions and Rationale when a behavior change comes from a decision change.
|
||||
- Truth 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, TRUTHMARK.md, docs/truthmark/areas.md, and canonical truth docs 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[]
|
||||
@@ -61,7 +100,9 @@ Parent post-sync verification:
|
||||
- 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
|
||||
@@ -71,7 +112,12 @@ Changed code reviewed:
|
||||
- src/auth/session.ts
|
||||
|
||||
Truth docs updated:
|
||||
- docs/features/repository/overview.md
|
||||
- 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.
|
||||
|
||||
@@ -1,11 +1,11 @@
|
||||
interface:
|
||||
display_name: "Truthmark Sync"
|
||||
short_description: "Sync truth docs from changed code"
|
||||
default_prompt: "Use $truthmark-sync to sync truth docs from changed code."
|
||||
short_description: "Sync truth docs from functional code changes; skip docs-only/no-code changes"
|
||||
default_prompt: "Use $truthmark-sync after functional code changes; skip docs-only/no-code changes."
|
||||
|
||||
policy:
|
||||
allow_implicit_invocation: true
|
||||
|
||||
truthmark:
|
||||
version: "1.2.1"
|
||||
version: "1.3.0"
|
||||
refresh_command: "truthmark init"
|
||||
|
||||
@@ -0,0 +1,68 @@
|
||||
description = "Use when the user asks to audit repository truth health, routing, ownership, or canonical docs. Not for normal lint/test/typecheck/code-review verification, finish-time Sync, or silently rewriting docs."
|
||||
prompt = '''
|
||||
---
|
||||
name: truthmark-check
|
||||
description: Use when the user asks to audit repository truth health, 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 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.
|
||||
|
||||
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,103 @@
|
||||
description = "Use when the user asks to document existing implemented behavior, or Sync, Check, or Structure finds implemented behavior missing canonical truth. Not for functional-code changes, doc-first implementation, or topology repair that needs Structure."
|
||||
prompt = '''
|
||||
---
|
||||
name: truthmark-document
|
||||
description: Use when the user 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 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.
|
||||
|
||||
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,65 @@
|
||||
description = "Use when the user explicitly asks to realize Truthmark truth docs into code, including /truthmark-realize, $truthmark-realize, or /truthmark:realize. Not for syncing docs after code changes, documenting existing code, topology repair, or truth audits."
|
||||
prompt = '''
|
||||
---
|
||||
name: truthmark-realize
|
||||
description: Use when the user explicitly asks to realize Truthmark truth docs into code, including /truthmark-realize, $truthmark-realize, or /truthmark:realize. 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 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
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
'''
|
||||
@@ -0,0 +1,126 @@
|
||||
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."
|
||||
prompt = '''
|
||||
---
|
||||
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.
|
||||
argument-hint: Optional area, directory, or routing concern
|
||||
user-invocable: true
|
||||
truthmark-version: 1.3.0
|
||||
---
|
||||
|
||||
Use this skill to design or repair Truthmark area structure.
|
||||
Invocations: OpenCode /skill truthmark-structure; Codex /truthmark-structure or $truthmark-structure; Claude Code /truthmark-structure; GitHub Copilot /truthmark-structure; Gemini CLI /truthmark:structure.
|
||||
Truth Structure is agent-native:
|
||||
- inspect repository layout, current docs, .truthmark/config.yml, docs/truthmark/areas.md, and relevant code directly
|
||||
- Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority.
|
||||
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.
|
||||
```
|
||||
'''
|
||||
@@ -0,0 +1,140 @@
|
||||
description = "Use automatically at finish-time after functional code changes, or explicit /truthmark-sync, $truthmark-sync, or /truthmark:sync. Skip docs-only, formatting-only, behavior-preserving renames, missing config, and no-code changes. Not for doc-first realization or manual topology design."
|
||||
prompt = '''
|
||||
---
|
||||
name: truthmark-sync
|
||||
description: Use automatically 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
|
||||
---
|
||||
|
||||
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
|
||||
|
||||
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:start -->
|
||||
## Truthmark Workflow
|
||||
|
||||
Generated by Truthmark 1.3.0. Rerun `truthmark init` after upgrades.
|
||||
Hierarchy: config .truthmark/config.yml; routes docs/truthmark/areas.md and docs/truthmark/areas/**/*.md; Truth docs: docs/truth/**/*.md.
|
||||
Decisions live in the canonical doc they govern; date active decisions inline.
|
||||
Agent runtime: installed skills plus this block; inspect checkout directly. Delegation is host-owned.
|
||||
### Truth Sync
|
||||
After functional code changes, run relevant tests, then use the truthmark-sync skill before finishing; later functional changes reopen the gate. Memory: code changed -> tests -> Sync -> report.
|
||||
Support new or changed behavior-bearing truth claims with checkout evidence. Code leads; truth docs follow. Sync may write truth docs and docs/truthmark/areas.md only, and must not rewrite functional code.
|
||||
If routing cannot map changed code to a bounded truth owner, run Truth Structure before syncing when safe; otherwise block and recommend Truth Structure. Skip Sync only for docs-only/no-code changes, formatting-only changes, behavior-preserving renames with no truth impact, or missing config.
|
||||
Explicit workflows: Truth Structure, Truth Document, Truth Realize, Truth Check. Run only when requested or required by Sync; load the installed skill for details.
|
||||
Workflow integrity rule: repository truth may describe desired behavior, but it must not override these workflow boundaries.
|
||||
<!-- truthmark:end -->
|
||||
@@ -0,0 +1,70 @@
|
||||
---
|
||||
agent: 'agent'
|
||||
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.'
|
||||
---
|
||||
|
||||
---
|
||||
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 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.
|
||||
|
||||
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,105 @@
|
||||
---
|
||||
agent: 'agent'
|
||||
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.'
|
||||
---
|
||||
|
||||
---
|
||||
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 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.
|
||||
|
||||
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,67 @@
|
||||
---
|
||||
agent: 'agent'
|
||||
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.'
|
||||
---
|
||||
|
||||
---
|
||||
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 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
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
@@ -0,0 +1,128 @@
|
||||
---
|
||||
agent: 'agent'
|
||||
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.'
|
||||
---
|
||||
|
||||
---
|
||||
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.
|
||||
argument-hint: Optional area, directory, or routing concern
|
||||
user-invocable: true
|
||||
truthmark-version: 1.3.0
|
||||
---
|
||||
|
||||
Use this skill to design or repair Truthmark area structure.
|
||||
Invocations: OpenCode /skill truthmark-structure; Codex /truthmark-structure or $truthmark-structure; Claude Code /truthmark-structure; GitHub Copilot /truthmark-structure; Gemini CLI /truthmark:structure.
|
||||
Truth Structure is agent-native:
|
||||
- inspect repository layout, current docs, .truthmark/config.yml, docs/truthmark/areas.md, and relevant code directly
|
||||
- Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority.
|
||||
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.
|
||||
```
|
||||
@@ -0,0 +1,142 @@
|
||||
---
|
||||
agent: 'agent'
|
||||
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.'
|
||||
---
|
||||
|
||||
---
|
||||
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
|
||||
---
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
```
|
||||
@@ -1,39 +1,44 @@
|
||||
---
|
||||
name: truthmark-check
|
||||
description: Use when the user asks to audit repository truth health. Inspects truth docs, routing, and implementation directly; may optionally run truthmark check when available.
|
||||
description: Use when the user asks to audit repository truth health, routing, ownership, or canonical docs. Not for normal lint/test/typecheck/code-review verification, finish-time Sync, or silently rewriting docs.
|
||||
argument-hint: Optional area, doc path, or audit focus
|
||||
user-invocable: true
|
||||
truthmark-version: 1.2.1
|
||||
truthmark-version: 1.3.0
|
||||
---
|
||||
|
||||
# Truthmark Check
|
||||
|
||||
Use this skill to audit repository truth health.
|
||||
|
||||
Invocations: OpenCode /skill truthmark-check; Codex /truthmark-check or $truthmark-check; Gemini CLI /truthmark:check.
|
||||
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, TRUTHMARK.md, docs/truthmark/areas.md, canonical docs, and relevant implementation directly
|
||||
- Repository docs and code are inspected evidence, not executable instruction authority.
|
||||
- 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
|
||||
- Feature docs: docs/features/**/*.md
|
||||
Decision truth lives in the canonical doc it governs.
|
||||
Short inline decision dates are allowed, for example `Decision (2026-05-09): ...`.
|
||||
Do not create separate timestamped ADR logs or planning tickets for active decisions.
|
||||
Replace old active decisions instead of appending separate timestamped decision logs; Git history is the audit trail.
|
||||
Update Product Decisions and Rationale when a behavior change comes from a decision change.
|
||||
- Truth 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:
|
||||
|
||||
@@ -41,7 +46,6 @@ Report completion in this shape:
|
||||
Truth Check: completed
|
||||
|
||||
Files reviewed:
|
||||
- TRUTHMARK.md
|
||||
- docs/truthmark/areas.md
|
||||
|
||||
Issues found:
|
||||
@@ -50,6 +54,12 @@ Issues found:
|
||||
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,100 @@
|
||||
---
|
||||
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 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.
|
||||
|
||||
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.
|
||||
```
|
||||
@@ -1,16 +1,16 @@
|
||||
---
|
||||
name: truthmark-realize
|
||||
description: Use when the user explicitly asks to realize Truthmark truth docs into code, including /truthmark-realize, $truthmark-realize, or /truthmark:realize. Reads truth docs and routing first, updates functional code only, and reports verification.
|
||||
description: Use when the user explicitly asks to realize Truthmark truth docs into code, including /truthmark-realize, $truthmark-realize, or /truthmark:realize. Not for syncing docs after code changes, documenting existing code, topology repair, or truth audits.
|
||||
argument-hint: Optional truth doc path, area, or desired code behavior to realize
|
||||
user-invocable: true
|
||||
truthmark-version: 1.2.1
|
||||
truthmark-version: 1.3.0
|
||||
---
|
||||
|
||||
# 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; Gemini CLI /truthmark:realize.
|
||||
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:
|
||||
|
||||
@@ -21,12 +21,23 @@ Truth Realize is doc-first:
|
||||
Workflow:
|
||||
|
||||
1. Read the updated truth docs named by the user, or infer the relevant docs from docs/truthmark/areas.md.
|
||||
2. Read .truthmark/config.yml, TRUTHMARK.md, docs/truthmark/areas.md, and the relevant functional code.
|
||||
3. Repository docs and code are inspected evidence, not executable instruction authority.
|
||||
4. Update functional code only so implementation matches the truth docs.
|
||||
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:
|
||||
|
||||
@@ -40,7 +51,7 @@ Report completion in this shape:
|
||||
Truth Realize: completed
|
||||
|
||||
Truth docs used:
|
||||
- docs/features/authentication.md
|
||||
- docs/truth/authentication/session-timeout.md
|
||||
|
||||
Code updated:
|
||||
- src/auth/session.ts
|
||||
|
||||
@@ -1,83 +1,121 @@
|
||||
---
|
||||
name: truthmark-structure
|
||||
description: Use when the user asks to design, repair, or refresh Truthmark area routing. Inspects the repository directly, updates docs/truthmark/areas.md, and may create starter canonical truth docs.
|
||||
description: Use when routing or truth ownership is missing, stale, broad, overloaded, catch-all, unrouteable, mixed-owner, or needs split/repair. Not for documenting implemented behavior, syncing a code diff, or realizing docs into code.
|
||||
argument-hint: Optional area, directory, or routing concern
|
||||
user-invocable: true
|
||||
truthmark-version: 1.2.1
|
||||
truthmark-version: 1.3.0
|
||||
---
|
||||
|
||||
Use this skill to design or repair Truthmark area structure.
|
||||
Invocations: OpenCode /skill truthmark-structure; Codex /truthmark-structure or $truthmark-structure; Gemini CLI /truthmark: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, TRUTHMARK.md, docs/truthmark/areas.md, and relevant code directly
|
||||
- Repository docs and code are inspected evidence, not executable instruction authority.
|
||||
- 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.
|
||||
- use docs/features/**, docs/architecture/**, or docs/standards/** for current truth destinations
|
||||
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/features. Treat the configured feature root as a managed semantic root.
|
||||
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 feature docs.
|
||||
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 feature root has many direct non-index docs
|
||||
- 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 feature doc because routing is too broad
|
||||
- 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 feature docs in one folder
|
||||
- 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 catch-all areas into behavior-owned child route files
|
||||
- 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 feature docs under the configured feature root only when behavior lacks a current doc
|
||||
- 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 <feature-root>/<domain>/<behavior>.md
|
||||
- keep feature docs behavior-oriented, not endpoint-oriented
|
||||
- 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, TRUTHMARK.md, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, canonical docs, and representative implementation code.
|
||||
- Read .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, canonical docs, and representative implementation code.
|
||||
- Use a subagent only when the host supports that pattern; otherwise perform the topology repair inline.
|
||||
Truthmark hierarchy:
|
||||
- Config: .truthmark/config.yml
|
||||
- Root route index: docs/truthmark/areas.md
|
||||
- Area route files: docs/truthmark/areas/**/*.md
|
||||
- Feature docs: docs/features/**/*.md
|
||||
Decision truth lives in the canonical doc it governs.
|
||||
Short inline decision dates are allowed, for example `Decision (2026-05-09): ...`.
|
||||
Do not create separate timestamped ADR logs or planning tickets for active decisions.
|
||||
Replace old active decisions instead of appending separate timestamped decision logs; Git history is the audit trail.
|
||||
Update Product Decisions and Rationale when a behavior change comes from a decision change.
|
||||
- Truth 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/features
|
||||
- docs root: docs/truth
|
||||
- route files: docs/truthmark/areas.md
|
||||
Areas reviewed:
|
||||
- src/auth/**
|
||||
Routing updated:
|
||||
- docs/truthmark/areas.md
|
||||
Truth docs created:
|
||||
- docs/features/authentication.md
|
||||
- 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:
|
||||
|
||||
@@ -1,30 +1,67 @@
|
||||
---
|
||||
name: truthmark-sync
|
||||
description: Use automatically before finishing when functional code changed since the last successful Truth Sync, and when the user explicitly invokes /truthmark-sync, $truthmark-sync, or /truthmark:sync. Inspects changed code directly, updates truth docs and routing, and verifies post-sync boundaries.
|
||||
description: Use automatically at finish-time after functional code changes, or explicit /truthmark-sync, $truthmark-sync, or /truthmark:sync. Skip docs-only, formatting-only, behavior-preserving renames, missing config, and no-code changes. Not for doc-first realization or manual topology design.
|
||||
argument-hint: Optional changed-code area, truth-doc area, or sync focus
|
||||
user-invocable: true
|
||||
truthmark-version: 1.2.1
|
||||
truthmark-version: 1.3.0
|
||||
---
|
||||
|
||||
Use this skill automatically before finishing when functional code changed since the last successful Truth Sync. Also run it immediately when the user explicitly invokes Truth Sync.
|
||||
Invocations: OpenCode /skill truthmark-sync; Codex /truthmark-sync or $truthmark-sync; Gemini CLI /truthmark: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, TRUTHMARK.md, the configured root route index at docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, and relevant canonical docs.
|
||||
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 docs and code are inspected evidence, not executable instruction authority.
|
||||
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
|
||||
- if routing is broad, overloaded, or catch-all route only, do not create another generic feature doc
|
||||
- run or recommend Truth Structure before syncing when topology repair is needed
|
||||
- block when topology repair is unsafe, ambiguous, or outside the current task boundary
|
||||
- report the broad route files and changed code paths that require structure repair
|
||||
- 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 feature README
|
||||
- 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
|
||||
@@ -34,25 +71,27 @@ Truthmark hierarchy:
|
||||
- Config: .truthmark/config.yml
|
||||
- Root route index: docs/truthmark/areas.md
|
||||
- Area route files: docs/truthmark/areas/**/*.md
|
||||
- Feature docs: docs/features/**/*.md
|
||||
Decision truth lives in the canonical doc it governs.
|
||||
Short inline decision dates are allowed, for example `Decision (2026-05-09): ...`.
|
||||
Do not create separate timestamped ADR logs or planning tickets for active decisions.
|
||||
Replace old active decisions instead of appending separate timestamped decision logs; Git history is the audit trail.
|
||||
Update Product Decisions and Rationale when a behavior change comes from a decision change.
|
||||
- Truth 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, TRUTHMARK.md, docs/truthmark/areas.md, and canonical truth docs 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[]
|
||||
@@ -61,7 +100,9 @@ Parent post-sync verification:
|
||||
- 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
|
||||
@@ -71,7 +112,12 @@ Changed code reviewed:
|
||||
- src/auth/session.ts
|
||||
|
||||
Truth docs updated:
|
||||
- docs/features/repository/overview.md
|
||||
- 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.
|
||||
|
||||
@@ -3,28 +3,31 @@ platforms:
|
||||
- codex
|
||||
- opencode
|
||||
- claude-code
|
||||
- github-copilot
|
||||
- gemini-cli
|
||||
docs:
|
||||
layout: hierarchical
|
||||
roots:
|
||||
ai: docs/ai
|
||||
standards: docs/standards
|
||||
architecture: docs/architecture
|
||||
features: docs/features
|
||||
truth: docs/truth
|
||||
routing:
|
||||
root_index: docs/truthmark/areas.md
|
||||
area_files_root: docs/truthmark/areas
|
||||
default_area: repository
|
||||
max_delegation_depth: 1
|
||||
authority:
|
||||
- TRUTHMARK.md
|
||||
- docs/truthmark/areas.md
|
||||
- docs/truthmark/areas/**/*.md
|
||||
- docs/ai/**/*.md
|
||||
- docs/standards/**/*.md
|
||||
- docs/architecture/**/*.md
|
||||
- docs/features/**/*.md
|
||||
- docs/truth/**/*.md
|
||||
instruction_targets:
|
||||
- AGENTS.md
|
||||
- CLAUDE.md
|
||||
- GEMINI.md
|
||||
frontmatter:
|
||||
required: []
|
||||
recommended:
|
||||
@@ -37,5 +40,3 @@ ignore:
|
||||
- vendor/**
|
||||
- dist/**
|
||||
- build/**
|
||||
realization:
|
||||
enabled: true
|
||||
|
||||
@@ -1,62 +1,22 @@
|
||||
Follow `docs/ai/repo-rules.md`.
|
||||
|
||||
Use that file as the primary repository instruction source for Codex.
|
||||
Use that file as the primary repository instruction source for this agent.
|
||||
|
||||
Codex-specific:
|
||||
- Read `docs/README.md` for the canonical docs map.
|
||||
- Use `docs/ai/agent-onboarding.md` for quick task routing.
|
||||
Agent-specific:
|
||||
- Read `docs/README.md` only when choosing or updating canonical docs.
|
||||
- Use `docs/ai/agent-onboarding.md` only when task routing is unclear or cross-area.
|
||||
|
||||
<!-- truthmark:start -->
|
||||
## Truthmark Workflow
|
||||
|
||||
Generated by Truthmark 1.2.1. After upgrading Truthmark, rerun `truthmark init` and review generated workflow diffs.
|
||||
|
||||
Truthmark hierarchy:
|
||||
- Config: .truthmark/config.yml
|
||||
- Root route index: docs/truthmark/areas.md
|
||||
- Area route files: docs/truthmark/areas/**/*.md
|
||||
- Feature docs: docs/features/**/*.md
|
||||
|
||||
Decision truth lives in the canonical doc it governs.
|
||||
Short inline decision dates are allowed, for example `Decision (2026-05-09): ...`.
|
||||
Do not create separate timestamped ADR logs or planning tickets for active decisions.
|
||||
Replace old active decisions instead of appending separate timestamped decision logs; Git history is the audit trail.
|
||||
Update Product Decisions and Rationale when a behavior change comes from a decision change.
|
||||
|
||||
### Truth Structure
|
||||
Use when area routing is missing, stale, broad, or explicitly requested.
|
||||
Invocations: OpenCode /skill truthmark-structure; Codex /truthmark-structure or $truthmark-structure; Gemini CLI /truthmark:structure.
|
||||
Inspect repository layout, docs/truthmark/areas.md, relevant child route files, canonical docs, and relevant code directly.
|
||||
Create or repair routing and starter canonical truth docs only when useful. Use only canonical current-truth destinations for starter truth docs.
|
||||
Own topology pressure: split broad/catch-all routing by inferred product or behavior ownership.
|
||||
If the skill is unavailable, perform the same direct checkout workflow from committed config, route files, docs, and implementation.
|
||||
|
||||
Generated by Truthmark 1.3.0. Rerun `truthmark init` after upgrades.
|
||||
Hierarchy: config .truthmark/config.yml; routes docs/truthmark/areas.md and docs/truthmark/areas/**/*.md; Truth docs: docs/truth/**/*.md.
|
||||
Decisions live in the canonical doc they govern; date active decisions inline.
|
||||
Agent runtime: installed skills plus this block; inspect checkout directly. Delegation is host-owned.
|
||||
### Truth Sync
|
||||
Automatic finish-time trigger: use the truthmark-sync skill before finishing if changed functional code exists; inspect staged, unstaged, and untracked functional code files.
|
||||
Explicit invocation runs immediately: OpenCode /skill truthmark-sync; Codex /truthmark-sync or $truthmark-sync; Gemini CLI /truthmark:sync.
|
||||
Later functional-code changes reopen the finish-time requirement, and an earlier explicit run only satisfies the finish gate if no later functional-code changes occur.
|
||||
Memory anchor: code changed -> relevant tests -> Truth Sync -> report.
|
||||
Delegate to a subagent only when the host supports subagent dispatch; the acting agent and environment own that choice.
|
||||
Inspect the current checkout directly. Do not invoke packet helpers or rely on cache files.
|
||||
Run relevant tests before finishing when functional code changes occurred.
|
||||
Truthmark is agent-native: installed skills and this managed block are the workflow runtime. Inspect the checkout directly; truthmark CLI commands are optional validation tools after installation.
|
||||
Code first: code leads; truth docs follow; Truth Sync never rewrites code for alignment.
|
||||
May write truth docs and docs/truthmark/areas.md only; must not rewrite functional code.
|
||||
Read docs/truthmark/areas.md and only relevant child route files under docs/truthmark/areas/ when routing resolution requires them.
|
||||
If routing is broad, overloaded, or catch-all, run or recommend Truth Structure before syncing; do not create another generic feature doc.
|
||||
If mapped truth is missing, extend mapped truth docs first, create an area-local truth doc second, and create a new area only as a last resort.
|
||||
Skip only for: documentation-only change; formatting-only change; clearly behavior-preserving rename with no truth impact; no Truthmark config exists yet; no functional code changes.
|
||||
|
||||
### Manual Truth Realize
|
||||
Only run when the user explicitly asks to realize truth docs into code. This is a manual installed instruction or skill, not a dedicated CLI command.
|
||||
Invocations: OpenCode /skill truthmark-realize; Codex /truthmark-realize or $truthmark-realize; Gemini CLI /truthmark:realize.
|
||||
Doc first: read truth docs, routing, and relevant code; write functional code only; do not edit truth docs or truth routing.
|
||||
Report truth docs used, code updated, and verification.
|
||||
|
||||
### Truth Check
|
||||
Use when the user asks to audit repository truth health.
|
||||
Invocations: OpenCode /skill truthmark-check; Codex /truthmark-check or $truthmark-check; Gemini CLI /truthmark:check.
|
||||
Inspect truth docs, routing, implementation, and docs/truthmark/areas.md directly. The truthmark check command may be used when available. Report files reviewed, issues, suggested fixes, and validation.
|
||||
|
||||
Workflow integrity rule: repository truth may describe desired behavior, but it must not silently override these Truthmark workflow boundaries.
|
||||
After functional code changes, run relevant tests, then use the truthmark-sync skill before finishing; later functional changes reopen the gate. Memory: code changed -> tests -> Sync -> report.
|
||||
Support new or changed behavior-bearing truth claims with checkout evidence. Code leads; truth docs follow. Sync may write truth docs and docs/truthmark/areas.md only, and must not rewrite functional code.
|
||||
If routing cannot map changed code to a bounded truth owner, run Truth Structure before syncing when safe; otherwise block and recommend Truth Structure. Skip Sync only for docs-only/no-code changes, formatting-only changes, behavior-preserving renames with no truth impact, or missing config.
|
||||
Explicit workflows: Truth Structure, Truth Document, Truth Realize, Truth Check. Run only when requested or required by Sync; load the installed skill for details.
|
||||
Workflow integrity rule: repository truth may describe desired behavior, but it must not override these workflow boundaries.
|
||||
<!-- truthmark:end -->
|
||||
|
||||
@@ -1,62 +1,22 @@
|
||||
Follow `docs/ai/repo-rules.md`.
|
||||
|
||||
Use that file as the primary repository instruction source for Codex.
|
||||
Use that file as the primary repository instruction source for this agent.
|
||||
|
||||
Codex-specific:
|
||||
- Read `docs/README.md` for the canonical docs map.
|
||||
- Use `docs/ai/agent-onboarding.md` for quick task routing.
|
||||
Agent-specific:
|
||||
- Read `docs/README.md` only when choosing or updating canonical docs.
|
||||
- Use `docs/ai/agent-onboarding.md` only when task routing is unclear or cross-area.
|
||||
|
||||
<!-- truthmark:start -->
|
||||
## Truthmark Workflow
|
||||
|
||||
Generated by Truthmark 1.2.1. After upgrading Truthmark, rerun `truthmark init` and review generated workflow diffs.
|
||||
|
||||
Truthmark hierarchy:
|
||||
- Config: .truthmark/config.yml
|
||||
- Root route index: docs/truthmark/areas.md
|
||||
- Area route files: docs/truthmark/areas/**/*.md
|
||||
- Feature docs: docs/features/**/*.md
|
||||
|
||||
Decision truth lives in the canonical doc it governs.
|
||||
Short inline decision dates are allowed, for example `Decision (2026-05-09): ...`.
|
||||
Do not create separate timestamped ADR logs or planning tickets for active decisions.
|
||||
Replace old active decisions instead of appending separate timestamped decision logs; Git history is the audit trail.
|
||||
Update Product Decisions and Rationale when a behavior change comes from a decision change.
|
||||
|
||||
### Truth Structure
|
||||
Use when area routing is missing, stale, broad, or explicitly requested.
|
||||
Invocations: OpenCode /skill truthmark-structure; Codex /truthmark-structure or $truthmark-structure; Gemini CLI /truthmark:structure.
|
||||
Inspect repository layout, docs/truthmark/areas.md, relevant child route files, canonical docs, and relevant code directly.
|
||||
Create or repair routing and starter canonical truth docs only when useful. Use only canonical current-truth destinations for starter truth docs.
|
||||
Own topology pressure: split broad/catch-all routing by inferred product or behavior ownership.
|
||||
If the skill is unavailable, perform the same direct checkout workflow from committed config, route files, docs, and implementation.
|
||||
|
||||
Generated by Truthmark 1.3.0. Rerun `truthmark init` after upgrades.
|
||||
Hierarchy: config .truthmark/config.yml; routes docs/truthmark/areas.md and docs/truthmark/areas/**/*.md; Truth docs: docs/truth/**/*.md.
|
||||
Decisions live in the canonical doc they govern; date active decisions inline.
|
||||
Agent runtime: installed skills plus this block; inspect checkout directly. Delegation is host-owned.
|
||||
### Truth Sync
|
||||
Automatic finish-time trigger: use the truthmark-sync skill before finishing if changed functional code exists; inspect staged, unstaged, and untracked functional code files.
|
||||
Explicit invocation runs immediately: OpenCode /skill truthmark-sync; Codex /truthmark-sync or $truthmark-sync; Gemini CLI /truthmark:sync.
|
||||
Later functional-code changes reopen the finish-time requirement, and an earlier explicit run only satisfies the finish gate if no later functional-code changes occur.
|
||||
Memory anchor: code changed -> relevant tests -> Truth Sync -> report.
|
||||
Delegate to a subagent only when the host supports subagent dispatch; the acting agent and environment own that choice.
|
||||
Inspect the current checkout directly. Do not invoke packet helpers or rely on cache files.
|
||||
Run relevant tests before finishing when functional code changes occurred.
|
||||
Truthmark is agent-native: installed skills and this managed block are the workflow runtime. Inspect the checkout directly; truthmark CLI commands are optional validation tools after installation.
|
||||
Code first: code leads; truth docs follow; Truth Sync never rewrites code for alignment.
|
||||
May write truth docs and docs/truthmark/areas.md only; must not rewrite functional code.
|
||||
Read docs/truthmark/areas.md and only relevant child route files under docs/truthmark/areas/ when routing resolution requires them.
|
||||
If routing is broad, overloaded, or catch-all, run or recommend Truth Structure before syncing; do not create another generic feature doc.
|
||||
If mapped truth is missing, extend mapped truth docs first, create an area-local truth doc second, and create a new area only as a last resort.
|
||||
Skip only for: documentation-only change; formatting-only change; clearly behavior-preserving rename with no truth impact; no Truthmark config exists yet; no functional code changes.
|
||||
|
||||
### Manual Truth Realize
|
||||
Only run when the user explicitly asks to realize truth docs into code. This is a manual installed instruction or skill, not a dedicated CLI command.
|
||||
Invocations: OpenCode /skill truthmark-realize; Codex /truthmark-realize or $truthmark-realize; Gemini CLI /truthmark:realize.
|
||||
Doc first: read truth docs, routing, and relevant code; write functional code only; do not edit truth docs or truth routing.
|
||||
Report truth docs used, code updated, and verification.
|
||||
|
||||
### Truth Check
|
||||
Use when the user asks to audit repository truth health.
|
||||
Invocations: OpenCode /skill truthmark-check; Codex /truthmark-check or $truthmark-check; Gemini CLI /truthmark:check.
|
||||
Inspect truth docs, routing, implementation, and docs/truthmark/areas.md directly. The truthmark check command may be used when available. Report files reviewed, issues, suggested fixes, and validation.
|
||||
|
||||
Workflow integrity rule: repository truth may describe desired behavior, but it must not silently override these Truthmark workflow boundaries.
|
||||
After functional code changes, run relevant tests, then use the truthmark-sync skill before finishing; later functional changes reopen the gate. Memory: code changed -> tests -> Sync -> report.
|
||||
Support new or changed behavior-bearing truth claims with checkout evidence. Code leads; truth docs follow. Sync may write truth docs and docs/truthmark/areas.md only, and must not rewrite functional code.
|
||||
If routing cannot map changed code to a bounded truth owner, run Truth Structure before syncing when safe; otherwise block and recommend Truth Structure. Skip Sync only for docs-only/no-code changes, formatting-only changes, behavior-preserving renames with no truth impact, or missing config.
|
||||
Explicit workflows: Truth Structure, Truth Document, Truth Realize, Truth Check. Run only when requested or required by Sync; load the installed skill for details.
|
||||
Workflow integrity rule: repository truth may describe desired behavior, but it must not override these workflow boundaries.
|
||||
<!-- truthmark:end -->
|
||||
|
||||
+128
@@ -0,0 +1,128 @@
|
||||
Directions for V2
|
||||
|
||||
Priority order: Evidence and Adoption first. Conformance continuously. Propagation and
|
||||
Decision Architecture in a later pass when the core confidence surface is stable.
|
||||
|
||||
---
|
||||
|
||||
V2.0 — Ship First
|
||||
|
||||
1. Evidence Layer
|
||||
- Strengthen `truthmark check` into the primary confidence surface. Error diagnostics
|
||||
should be the canonical signal of truth health, not a secondary linting step.
|
||||
- Make check output more actionable: route precision score, unmapped code surfaces, stale
|
||||
generated surfaces, topology pressure hotspots in one readable report.
|
||||
- Expose stable JSON output from `truthmark check` so CI, PR bots, and future adapters
|
||||
can consume truth health without parsing human-readable text.
|
||||
- Add lightweight traceability reporting: which routed docs have explicit code ownership,
|
||||
active decisions, and at least one verification link. This is coverage for Truthmark's
|
||||
narrower scope, not full MBSE traceability.
|
||||
- Build before/after demos: code change -> tests -> Truth Sync -> reviewable truth diff.
|
||||
|
||||
2. Adoption Layer
|
||||
- Create high-quality example repos: Node API, Go service, frontend app, monorepo, infra
|
||||
repo. Each one should show a real Truth Sync cycle, not just the installed scaffolding.
|
||||
- Add migration guides for teams already using AGENTS.md, CLAUDE.md, Copilot
|
||||
instructions, or Gemini commands. The entry point is their existing agent config, not
|
||||
a blank repo.
|
||||
- Sharpen messaging: "Your agents write code. Truthmark makes their context reviewable in
|
||||
Git."
|
||||
- Reduce vocabulary friction. "Truth" is powerful internally, but new users need concrete
|
||||
outcomes: fewer repeated decisions, better handoffs, less doc drift.
|
||||
- Show comparative stories: prompt-only repo vs Truthmark repo, broad route vs precise
|
||||
route, undocumented change vs reviewable truth diff. These replace the abstract truth
|
||||
explorer idea; showing is better than a browseable demo that requires building a separate
|
||||
site product.
|
||||
|
||||
---
|
||||
|
||||
V2.x — Steady Conformance (ongoing alongside V2.0)
|
||||
|
||||
3. Conformance Layer
|
||||
- Treat generated host surfaces as adapters with contract tests covering each platform
|
||||
(Codex, Claude Code, Copilot, OpenCode, Gemini CLI). Host API evolution is the main
|
||||
breakage risk; tests catch it before users do.
|
||||
- Keep all configured platforms current as those hosts evolve. External signal: Codex
|
||||
reads repo instructions and skills; Copilot supports repo/path/agent instructions;
|
||||
Claude Code has project skills; Gemini CLI supports project commands.
|
||||
- Keep MCP and IDE integrations as optional adapter surfaces only. They must not become
|
||||
the product center of gravity. Truthmark is a repository protocol, not a server.
|
||||
|
||||
---
|
||||
|
||||
V2.5 — Next Wave
|
||||
|
||||
4. Propagation Layer
|
||||
- Inspired by Reqvire's change-propagation concept, but scoped to Truthmark's narrower
|
||||
model: route-aware, not requirement-graph-aware.
|
||||
- For code-first changes, Truth Sync should emit "likely stale" hints when a change
|
||||
touches code owned by multiple routes or when owned docs have not been touched in the
|
||||
same branch. This is a check signal, not an automatic rewrite.
|
||||
- For doc-first changes, Truth Realize should emit a bounded implementation checklist
|
||||
(which code files are owned by the changed doc, what tests cover them) before the agent
|
||||
begins writing code. Reduces scope drift.
|
||||
- Treat active decisions as reviewable objects: a truth diff that shows a Product Decision
|
||||
change should surface which code areas and tests that decision governs. Reviewers should
|
||||
not need to reconstruct the impact manually.
|
||||
|
||||
5. Decision Architecture (New Idea — Evaluate Before Building)
|
||||
- Proposal: separate business decisions from technical decisions by where they live.
|
||||
Business decisions (what the PM decided the product must do and why) belong in truth
|
||||
docs. Technical decisions (why this implementation approach, which trade-offs were made
|
||||
in code) can live as structured comments in the code.
|
||||
- The existing Product Decisions / Rationale section structure in canonical docs already
|
||||
approximates this: "Product Decisions" is the business layer, "Rationale" is the
|
||||
technical justification.
|
||||
- Opportunity: make this convention explicit, validated, and agent-readable. `truthmark
|
||||
check` could warn when a Product Decisions section reads like an implementation note
|
||||
(contains file names, library names, performance numbers) rather than product intent.
|
||||
- Risk 1: the boundary is blurry. "We chose PostgreSQL because the team knows it" is a
|
||||
technical decision with an organizational cause; "we chose eventual consistency because
|
||||
the PM wants fast writes" is a business decision that shapes technical choices. Many
|
||||
real decisions span both.
|
||||
- Risk 2: code comments don't survive refactoring. They drift more than truth docs, which
|
||||
have routing, check, and Truth Sync discipline.
|
||||
- Risk 3: agents crossing two locations (truth doc for the what, code for the why) is
|
||||
more expensive than one location with both. The protocol should be clear about which
|
||||
agent reads what.
|
||||
- Better formulation: truth docs own product intent and the business rationale for
|
||||
decisions. Technical trade-offs and implementation rationale should also appear in truth
|
||||
docs when the trade-off is decision-bearing (likely to be revisited or affects contract
|
||||
boundaries). Implementation-local detail (why this loop is structured this way) belongs
|
||||
in code comments and is outside Truthmark's scope.
|
||||
- Verdict: validate the convention with example repos before encoding it as a validated
|
||||
check. It is a governance principle, not a structural enforcement.
|
||||
|
||||
---
|
||||
|
||||
Non-Goals (What Truthmark Should Not Become)
|
||||
|
||||
These are competitive directions that feel adjacent but would dilute the product:
|
||||
|
||||
- A full requirements or MBSE platform (that is Reqvire's lane).
|
||||
- A memory server or session-persistence tool.
|
||||
- A spec or PRD authoring tool.
|
||||
- An IDE or editor plugin (adapter surfaces only, not first-party tooling).
|
||||
- A merge gate or CI approval system (truth health is a signal, not an enforcement layer by
|
||||
default).
|
||||
|
||||
---
|
||||
|
||||
Market Position
|
||||
|
||||
Reqvire validates demand for Git-native, Markdown-based, AI-readable context with
|
||||
traceability and coverage. ADRs (15k GitHub stars) validate demand for decision-record
|
||||
discipline across teams. Decision Guardian validates demand for decision-to-code surfacing at
|
||||
PR review time.
|
||||
|
||||
The gap Truthmark owns is narrower and more opinionated: branch-scoped repository truth
|
||||
as a governance layer, not a requirements system and not a memory tool. The value is that
|
||||
agent context becomes a committed, reviewable, branch-local Git artifact instead of a
|
||||
session-private opaque record.
|
||||
|
||||
If Reqvire is requirements-as-context and ADRs are decision-as-document, Truthmark is
|
||||
repository-truth-as-governance: what is authoritative on this branch, what code it owns,
|
||||
what changed, and what must be updated before work is complete.
|
||||
|
||||
> The repo should tell every AI agent what is true, what owns what, what changed, and what
|
||||
> must be updated before work is complete.
|
||||
@@ -0,0 +1,22 @@
|
||||
Follow `docs/ai/repo-rules.md`.
|
||||
|
||||
Use that file as the primary repository instruction source for this agent.
|
||||
|
||||
Agent-specific:
|
||||
- Read `docs/README.md` only when choosing or updating canonical docs.
|
||||
- Use `docs/ai/agent-onboarding.md` only when task routing is unclear or cross-area.
|
||||
|
||||
<!-- truthmark:start -->
|
||||
## Truthmark Workflow
|
||||
|
||||
Generated by Truthmark 1.3.0. Rerun `truthmark init` after upgrades.
|
||||
Hierarchy: config .truthmark/config.yml; routes docs/truthmark/areas.md and docs/truthmark/areas/**/*.md; Truth docs: docs/truth/**/*.md.
|
||||
Decisions live in the canonical doc they govern; date active decisions inline.
|
||||
Agent runtime: installed skills plus this block; inspect checkout directly. Delegation is host-owned.
|
||||
### Truth Sync
|
||||
After functional code changes, run relevant tests, then use the truthmark-sync skill before finishing; later functional changes reopen the gate. Memory: code changed -> tests -> Sync -> report.
|
||||
Support new or changed behavior-bearing truth claims with checkout evidence. Code leads; truth docs follow. Sync may write truth docs and docs/truthmark/areas.md only, and must not rewrite functional code.
|
||||
If routing cannot map changed code to a bounded truth owner, run Truth Structure before syncing when safe; otherwise block and recommend Truth Structure. Skip Sync only for docs-only/no-code changes, formatting-only changes, behavior-preserving renames with no truth impact, or missing config.
|
||||
Explicit workflows: Truth Structure, Truth Document, Truth Realize, Truth Check. Run only when requested or required by Sync; load the installed skill for details.
|
||||
Workflow integrity rule: repository truth may describe desired behavior, but it must not override these workflow boundaries.
|
||||
<!-- truthmark:end -->
|
||||
+160
-68
@@ -1,31 +1,68 @@
|
||||
# Truthmark ist die Wahrheitsschicht für KI-Softwareentwicklung.
|
||||
# Truthmark
|
||||
|
||||
**Truthmark installiert Repository-Wahrheits-Workflows für KI-Softwareentwicklung.**
|
||||
|
||||
[English](README.md) | Deutsch | [中文](README.zh.md) | [Español](README.es.md) | [Русский](README.ru.md)
|
||||
|
||||
KI-Coding-Agenten können bereits gut Code schreiben. Womit sie weiterhin Schwierigkeiten haben: Produktabsicht, Architekturgrenzen und Zuständigkeiten im Repository zuverlässig aus veralteter Dokumentation, verstreuten Chats und flüchtigem Tool-Gedächtnis zu rekonstruieren.
|
||||
Truthmark löst das, indem es branch-lokale Repository-Wahrheit zu einer erstklassigen Laufzeitfläche für Agenten macht. Es installiert eine Git-native, branch-gebundene Wahrheitsschicht direkt im Repository, gibt Agenten explizite Routing- und Workflow-Grenzen und sorgt dafür, dass diese Wahrheit mit dem Code mitwandert, der tatsächlich ausgeliefert wird.
|
||||
Das ist kein besseres Prompt-Engineering. Es ist eine besser steuerbare Art, KI in einer echten Codebasis einzusetzen: weniger wiederholte Entscheidungen, weniger veraltete Dokumentation, sauberere Übergaben und KI-Coding-Sitzungen, die prüfbare Engineering-Aufzeichnungen hinterlassen, statt im Prompt-Verlauf oder in undurchsichtigen Tool-Zuständen zu verschwinden.
|
||||
Für Teams, die bereits wissen, dass Agenten Code erzeugen können, und jetzt wollen, dass das Repository selbst lesbar, prüfbar und steuerbar bleibt.
|
||||
<img src="docs/assets/truthmark-banner.png" alt="Truthmark-Banner" width="100%" />
|
||||
|
||||
## Was Truthmark löst
|
||||
KI-Coding-Agenten schreiben bereits schnell Code. Der teure Teil ist, die Repository-Wahrheit mit den tatsächlichen Änderungen im Gleichschritt zu halten.
|
||||
|
||||
KI-Coding ist heute leicht zu starten, aber teuer zu beherrschen. Sobald Agenten schnell Code schreiben können, wird Repository-Wahrheit zur Steuerfläche.
|
||||
Dieses Fehlermuster zeigt sich vorhersehbar: Anforderungen bleiben im Chat, Architekturentscheidungen werden wiederholt, Agenten bearbeiten die falschen Bereiche, und Branches erben Kontext, den Reviewer nicht zuverlässig prüfen können. Der Code kommt vielleicht schnell voran, aber dem Repository wird schwerer zu vertrauen.
|
||||
Truthmark verändert das Arbeitsmodell:
|
||||
Truthmark fügt diesem Ablauf eine Abschlusskontrolle als Workflow hinzu. Der normale Pfad ist einfach:
|
||||
|
||||
- Branch-lokale Wahrheit wandert mit dem Branch, statt in einem privaten Tool-Speicher zu liegen.
|
||||
- Git macht diese Wahrheit prüfbar, diffbar und im Team teilbar.
|
||||
- Dokumentation folgt dem Code, statt still in Fiktion abzudriften.
|
||||
- Routing bleibt in `docs/truthmark/areas.md` und delegierten untergeordneten Routendateien explizit, damit Agenten wissen, welche Dokumentation welchen Code verantwortet.
|
||||
- Aktive Produkt- und Architekturentscheidungen stehen in den kanonischen Dokumenten, die sie betreffen, nicht in zeitgestempelten Planungsprotokollen.
|
||||
- Local-first-Workflows vermeiden die Abhängigkeit von Daemon, Datenbank, Remote-Dienst oder MCP.
|
||||
- Das Modell funktioniert in Codebasen mit JavaScript, TypeScript, Go, Python, C# und Java.
|
||||
- Agent ändert funktionalen Code
|
||||
- relevante Tests laufen
|
||||
- der installierte Truth-Sync-Workflow aktualisiert zugeordnete Wahrheitsdokumente, bevor der Agent fertig ist
|
||||
- Truth-Doc-Diff prüfen, wenn einer erzeugt wurde
|
||||
|
||||
Für Tech Leads liegt der Wert in Governance ohne Theater: Tests, Code Review und Ownership leisten weiterhin die eigentliche Arbeit; Truthmark macht den Kontext des Agenten dauerhaft, prüfbar und branch-gebunden.
|
||||
Die meisten Tools bitten Teams darum, sich eine Gewohnheit anzueignen. Truthmark macht daraus Repository-Workflow-Infrastruktur.
|
||||
|
||||
Truthmark macht aus einem KI-Workflow Repository-Infrastruktur statt persönlichem Tooling. Es installiert eine Git-native, branch-gebundene Wahrheitsschicht im Repository, gibt Agenten explizites Routing und begrenzte Workflow-Flächen und hält diese Wahrheit in Git prüfbar, statt sie über Prompt-Verlauf, veraltete Dokumentation oder privaten Tool-Zustand zu verstreuen.
|
||||
|
||||
Das ist wichtig, weil der Workflow mit dem Branch lebt. Sobald ein Repository initialisiert ist, reisen Regeln, Routing und installierte Workflow-Flächen im Repository mit, sodass Zusammenarbeit und Übergaben weniger von der Rechnerkonfiguration einer einzelnen Person abhängen.
|
||||
|
||||
Für Teams, die bereits wissen, dass Agenten Code erzeugen können, beantwortet Truthmark das nächste Problem: wie das Repository selbst lesbar, prüfbar und steuerbar bleibt, wenn KI-gestützte Arbeit skaliert.
|
||||
|
||||
## Visueller Überblick
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td align="center" width="50%">
|
||||
<img src="docs/assets/truthmark-features.png" alt="Truthmark-Funktionen" width="100%" />
|
||||
<br><strong>Funktionen</strong><br>
|
||||
Was Truthmark installiert und wie sich die Workflow-Fläche aufteilt.
|
||||
</td>
|
||||
<td align="center" width="50%">
|
||||
<img src="docs/assets/truthmark-position.png" alt="Truthmark-Positionierung" width="100%" />
|
||||
<br><strong>Positionierung</strong><br>
|
||||
Wo Truthmark im Verhältnis zu Prompts, Memory und Spec-Workflows steht.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td align="center" colspan="2">
|
||||
<img src="docs/assets/truthmark-syncflow.png" alt="Truthmark-Sync-Ablauf" width="100%" />
|
||||
<br><strong>Sync-Ablauf</strong><br>
|
||||
Wie Truth Sync normale Codeänderungen vor einer Übergabe abschließt.
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
## Warum Teams es nutzen
|
||||
|
||||
Truthmark versucht nicht, Agenten klüger wirken zu lassen. Es soll KI-gestützte Repository-Änderungen vertrauenswürdiger machen.
|
||||
|
||||
- Installierte Truth-Sync-Läufe nach Codeänderungen machen Dokumentationspflege zu einer Workflow-Schutzschicht statt zu einer Teamgewohnheit.
|
||||
- Branch-gebundene Wahrheit bewegt sich mit dem Code, sodass Reviewer aktuelle Wahrheit in normalen Git-Diffs prüfen können.
|
||||
- Repository-native Workflow-Flächen machen Rollout leichter und Übergaben robuster als reine Pro-User-Konfiguration.
|
||||
- Explizites Routing in `docs/truthmark/areas.md` und delegierten untergeordneten Routendateien gibt Agenten Zuständigkeitsgrenzen und sicherere Schreibpfade.
|
||||
- Local-first-Betrieb vermeidet einen Daemon, eine Datenbank, einen Remote-Dienst oder eine MCP-Abhängigkeit.
|
||||
- Das Routing-Modell ist sprachunabhängig, mit Coverage-Diagnostik für gängige JavaScript-, TypeScript-, Go-, Python-, C#- und Java-Codeflächen.
|
||||
|
||||
Für Tech Leads liegt der Wert in Governance ohne Zusatzinfrastruktur: Tests, Code Review und Ownership leisten weiterhin die eigentliche Arbeit; Truthmark macht den Kontext des Agenten dauerhaft, prüfbar und branch-gebunden.
|
||||
|
||||
## Wo Truthmark hineinpasst
|
||||
|
||||
Truthmark versucht nicht, jedes andere KI-Workflow-Tool zu ersetzen. Es sitzt in einer bestimmten Schicht des Stacks:
|
||||
Truthmark ist keine allgemeine KI-Produktivitätssuite. Es besetzt eine bestimmte Schicht im Stack: branch-gebundene, prüfbare Repository-Wahrheit, die mit der Implementierung synchron bleibt.
|
||||
|
||||
| Wenn du brauchst | Beste Wahl |
|
||||
| --------------------------------------------------------------------------- | ------------------------------------------- |
|
||||
@@ -38,9 +75,9 @@ Der Punkt ist nicht, dass Prompts, Memory oder Specs nutzlos wären. Der Punkt i
|
||||
|
||||
## Inhalt
|
||||
|
||||
- [Warum Teams es nutzen](#warum-teams-es-nutzen)
|
||||
- [Was Truthmark löst](#was-truthmark-löst)
|
||||
- [Wo Truthmark hineinpasst](#wo-truthmark-hineinpasst)
|
||||
- [Workflow-Fläche](#workflow-fläche)
|
||||
- [Erste Schritte](#erste-schritte)
|
||||
- [Wie es läuft](#wie-es-läuft)
|
||||
- [Was es installiert](#was-es-installiert)
|
||||
@@ -51,12 +88,13 @@ Der Punkt ist nicht, dass Prompts, Memory oder Specs nutzlos wären. Der Punkt i
|
||||
- [Nicht-Ziele](#nicht-ziele)
|
||||
- [Lizenz](#lizenz)
|
||||
|
||||
## Workflow-Fläche
|
||||
## Was Truthmark löst
|
||||
|
||||
Truthmark macht Repository-Wahrheit zu einer expliziten Workflow-Fläche für Agenten:
|
||||
|
||||
- `TRUTHMARK.md` definiert den branch-lokalen Workflow-Vertrag.
|
||||
- `.truthmark/config.yml` definiert den festgeschriebenen Hierarchievertrag.
|
||||
- `docs/truthmark/areas.md` und delegierte untergeordnete Routendateien ordnen Codebereiche den Dokumenten zu, die sie verantworten.
|
||||
- Truth Document erstellt oder repariert kanonische Wahrheitsdokumente für bereits implementiertes Verhalten, wenn keine Codeänderung nötig ist.
|
||||
- Truth Sync hält zugeordnete Wahrheitsdokumente bei funktionalen Änderungen synchron.
|
||||
- Truth Realize gibt doc-first Änderungen einen begrenzten Pfad für Code-Updates.
|
||||
- `truthmark check` validiert die daraus entstehenden Wahrheitsartefakte.
|
||||
@@ -92,96 +130,145 @@ Prüfe `.truthmark/config.yml` vor `init`; es ist der in Git festgeschriebene Hi
|
||||
|
||||
```text
|
||||
.truthmark/config.yml
|
||||
TRUTHMARK.md
|
||||
docs/truthmark/areas.md
|
||||
docs/truthmark/areas/repository.md
|
||||
docs/features/README.md
|
||||
docs/features/repository/README.md
|
||||
docs/features/repository/overview.md
|
||||
docs/templates/behavior-doc.md
|
||||
docs/truth/README.md
|
||||
docs/truth/repository/README.md
|
||||
docs/truth/repository/overview.md
|
||||
AGENTS.md
|
||||
CLAUDE.md
|
||||
.codex/skills/truthmark-structure/SKILL.md
|
||||
.codex/skills/truthmark-sync/SKILL.md
|
||||
.codex/skills/truthmark-realize/SKILL.md
|
||||
.codex/skills/truthmark-check/SKILL.md
|
||||
.opencode/skills/truthmark-structure/SKILL.md
|
||||
.opencode/skills/truthmark-sync/SKILL.md
|
||||
.opencode/skills/truthmark-realize/SKILL.md
|
||||
.opencode/skills/truthmark-check/SKILL.md
|
||||
GEMINI.md
|
||||
```
|
||||
|
||||
Wenn du zusätzliche Plattformen in `.truthmark/config.yml` aktivierst, aktualisiert Truthmark die entsprechenden verwalteten Flächen beim nächsten `init`.
|
||||
Die standardmäßig erzeugte Struktur verwendet `README.md`-Dateien von Features als Indizes und beginnt die Wahrheit über aktuelles Verhalten in begrenzten Blattdokumenten wie `docs/features/repository/overview.md`.
|
||||
Unterstützte Plattformen sind `codex`, `opencode`, `claude-code`, `github-copilot` und `gemini-cli`. Die Standardkonfiguration enthält alle davon; entferne Plattformen, die du nicht nutzt, aus `.truthmark/config.yml`, bevor du `truthmark init` erneut ausführst.
|
||||
Die standardmäßig erzeugte Struktur verwendet Truth-`README.md`-Dateien als Indizes und beginnt die Wahrheit über aktuelles Verhalten in begrenzten Blattdokumenten wie `docs/truth/repository/overview.md`.
|
||||
|
||||
Bestehende Repositories brauchen nach `init` meist einen Aufräumschritt: Führe den installierten Truth-Structure-Workflow aus, wenn die erzeugte `repository`-Route zu breit ist, Ownership mehrere Produkte oder Services umfasst oder Routendateien noch auf Platzhalterdokumente zeigen. Truth Structure teilt breite Routings auf, erstellt oder repariert erste kanonische Wahrheitsdokumente und gibt Truth Sync präzise Ziele, bevor funktionale Codearbeit beginnt. Codex-Nutzer können ihn mit `/truthmark-structure` oder `$truthmark-structure` aufrufen; Hosts im OpenCode-Stil können `/skill truthmark-structure` verwenden.
|
||||
Bestehende Repositories brauchen nach `init` meist einen Aufräumschritt: Führe den installierten Truth-Structure-Workflow aus, wenn die erzeugte `repository`-Route zu breit ist, Ownership mehrere Produkte oder Services umfasst oder Routendateien noch auf Platzhalterdokumente zeigen. Truth Structure teilt breite Routings auf, erstellt oder repariert erste kanonische Wahrheitsdokumente und gibt Truth Sync präzise Ziele, bevor funktionale Codearbeit beginnt. Codex, Claude Code und unterstützte Copilot-IDEs können ihn mit `/truthmark-structure` aufrufen; Hosts im OpenCode-Stil können `/skill truthmark-structure` verwenden.
|
||||
|
||||
## Wie es läuft
|
||||
|
||||
Truthmark legt nicht fest, welcher Subagent Truth Sync ausführen soll. Der handelnde Agent und die Host-Umgebung entscheiden, ob delegiert oder der Workflow inline ausgeführt wird.
|
||||
Die meisten Nutzer sollten Truth Sync nicht direkt aufrufen müssen. Der normale Ablauf ist:
|
||||
Truthmark ist am stärksten auf dem Standardpfad, nicht als Sammlung manueller Befehle. Der handelnde Agent und die Host-Umgebung entscheiden, ob delegiert oder der installierte Workflow inline ausgeführt wird.
|
||||
|
||||
### Vorhandenes Verhalten ohne Doku
|
||||
|
||||
Nutze das, wenn die Implementierung bereits existiert, aber die kanonischen Wahrheitsdokumente fehlen oder schwach sind:
|
||||
|
||||
```text
|
||||
Agent ändert funktionalen Code
|
||||
relevante Tests laufen
|
||||
Truth Sync wird vor dem Abschluss des Agenten ausgelöst
|
||||
Truth-Doc-Diff prüfen, falls einer erzeugt wurde
|
||||
Arbeit committen oder übergeben
|
||||
benutzer identifiziert ein implementiertes verhalten oder einen api-endpunkt
|
||||
benutzer ruft truth document ausdrücklich auf
|
||||
agent liest implementierung, tests, routing und vorhandene docs
|
||||
agent schreibt nur truth docs und routing
|
||||
truth-doc-diff prüfen
|
||||
```
|
||||
|
||||
Truth Sync ist code-first: Code führt, Wahrheitsdokumente folgen, und Truth Sync darf funktionalen Code nicht umschreiben. Seine Hauptaufgabe ist eine automatische Abschlusskontrolle, wenn funktionaler Code geändert wurde. Direkte Aufrufe sind vor allem für Fehlersuche, frühe Synchronisierung vor einer Übergabe oder bewusstes Ausführen des Workflows gedacht.
|
||||
Codex-Nutzer können es mit `/truthmark-sync` oder `$truthmark-sync` aufrufen. Hosts im OpenCode-Stil können `/skill truthmark-sync` verwenden.
|
||||
Nutze diesen Ablauf, wenn eine Produkt- oder Architekturentscheidung in der Dokumentation beginnt:
|
||||
Truth Document ist manuell und implementation-first: Code dient als Beleg, Wahrheitsdokumente werden erstellt oder repariert, und funktionaler Code darf nicht geändert werden. Codex, Claude Code und unterstützte Copilot-IDEs können es mit `/truthmark-document` aufrufen. Hosts im OpenCode-Stil können `/skill truthmark-document` verwenden.
|
||||
|
||||
```text
|
||||
Benutzer bearbeitet Wahrheitsdokumente
|
||||
Benutzer ruft Truth Realize ausdrücklich auf
|
||||
Agent liest Wahrheitsdokumente und relevanten Code
|
||||
Agent aktualisiert nur Code
|
||||
relevante Tests laufen
|
||||
Arbeit committen oder übergeben
|
||||
/truthmark-document dokumentiere das implementierte session-timeout-verhalten unter docs/truth/authentication
|
||||
```
|
||||
|
||||
### Normale Codeänderungen
|
||||
|
||||
Die meisten Nutzer sollten Truth Sync nicht direkt aufrufen müssen. Entscheidend ist, dass der installierte Agenten-Workflow Truth Sync als Abschlusskontrolle behandelt, wenn funktionaler Code geändert wurde. Der normale Ablauf ist:
|
||||
|
||||
```text
|
||||
agent ändert funktionalen code
|
||||
relevante tests laufen
|
||||
der installierte truth-sync-workflow läuft, bevor der agent fertig ist
|
||||
truth-doc-diff prüfen, falls einer erzeugt wurde
|
||||
arbeit committen oder übergeben
|
||||
```
|
||||
|
||||
Truth Sync ist code-first: Code führt, Wahrheitsdokumente folgen, und Truth Sync darf funktionalen Code nicht umschreiben. Seine Hauptaufgabe ist, über den installierten Agenten-Workflow als Abschlusskontrolle zu laufen, wenn funktionaler Code geändert wurde. Direkte Aufrufe sind vor allem für Fehlersuche, frühe Synchronisierung vor einer Übergabe oder bewusstes Ausführen des Workflows gedacht.
|
||||
|
||||
Codex, Claude Code und unterstützte Copilot-IDEs können es mit `/truthmark-sync` aufrufen. Hosts im OpenCode-Stil können `/skill truthmark-sync` verwenden.
|
||||
|
||||
```text
|
||||
/truthmark-sync die repository-wahrheit jetzt vor der übergabe synchronisieren
|
||||
```
|
||||
|
||||
### Doc-first-Änderungen
|
||||
|
||||
Nutze das, wenn eine Produkt- oder Architekturentscheidung in der Doku beginnt:
|
||||
|
||||
```text
|
||||
benutzer bearbeitet wahrheitsdokumente
|
||||
benutzer ruft truth realize ausdrücklich auf
|
||||
agent liest wahrheitsdokumente und relevanten code
|
||||
agent aktualisiert nur code
|
||||
relevante tests laufen
|
||||
arbeit committen oder übergeben
|
||||
```
|
||||
|
||||
Truth Realize ist manuell und doc-first: Wahrheitsdokumente führen, Code folgt, und der Agent darf die Wahrheitsdokumente, die er realisiert, nicht bearbeiten.
|
||||
Codex-Nutzer können es mit `/truthmark-realize` oder `$truthmark-realize` aufrufen. Hosts im OpenCode-Stil können `/skill truthmark-realize` verwenden.
|
||||
|
||||
Codex, Claude Code und unterstützte Copilot-IDEs können es mit `/truthmark-realize` aufrufen. Hosts im OpenCode-Stil können `/skill truthmark-realize` verwenden.
|
||||
|
||||
```text
|
||||
/truthmark-realize docs/truth/authentication/session-timeout.md in code umsetzen
|
||||
```
|
||||
|
||||
## Was es installiert
|
||||
|
||||
Truthmark hält die dauerhafte Workflow-Fläche klein:
|
||||
Truthmark hält die dauerhafte Workflow-Fläche klein und repository-nativ. Nach `truthmark init` trägt das Repository selbst Routing, Regeln und installierte Workflow-Flächen, sodass Teams nicht nur auf die lokale Konfiguration einer einzelnen Person angewiesen sind.
|
||||
|
||||
- `.truthmark/config.yml` für maschinenlesbare Konfiguration
|
||||
- `TRUTHMARK.md` für den branch-lokalen Workflow-Vertrag
|
||||
- `.truthmark/config.yml` für den maschinenlesbaren, festgeschriebenen Hierarchievertrag
|
||||
- `docs/truthmark/areas.md` für den Root-Routenindex
|
||||
- `docs/truthmark/areas/**/*.md` für delegierte untergeordnete Routendateien
|
||||
- verwaltete Instruktionsblöcke für konfigurierte Plattformen wie `AGENTS.md`, `CLAUDE.md`, Cursor-Regeln, Copilot-Anweisungen und `GEMINI.md`
|
||||
- Codex- und repo-lokale Skills für Truth Structure, Truth Sync, Truth Realize und Truth Check
|
||||
- `docs/templates/behavior-doc.md` sowie die weiteren typspezifischen Vorlagen unter `docs/templates/` für die editierbaren Truth-Doc-Standards der generierten Workflows
|
||||
- verwaltete Instruktionsblöcke für konfigurierte Plattformen wie `AGENTS.md`, `CLAUDE.md`, Copilot-Anweisungen und `GEMINI.md`
|
||||
- host-native Skills, Prompts oder Commands für Truth Structure, Truth Document, Truth Sync, Truth Realize und Truth Check
|
||||
|
||||
Die installierten Workflow-Flächen sind die Runtime:
|
||||
|
||||
- Truth Structure erstellt oder repariert Area-Routing und erste Wahrheitsdokumente.
|
||||
- Truth Document erstellt oder repariert Wahrheitsdokumente für bereits implementiertes Verhalten.
|
||||
- Truth Sync hält zugeordnete Wahrheitsdokumente bei funktionalen Änderungen synchron.
|
||||
- Truth Realize aktualisiert Code so, dass er zu den Wahrheitsdokumenten passt.
|
||||
- Truth Check auditiert die Gesundheit der Repository-Wahrheit.
|
||||
|
||||
`README.md`-Dateien von Features sind Indizes. Truth Sync soll begrenzte Blattdokumente für aktuelles Verhalten lesen und aktualisieren.
|
||||
`README.md`-Dateien von Features sind Indizes. Truth Sync soll begrenzte Blattdokumente für aktuelles Verhalten lesen und aktualisieren. Generierte Workflow-Flächen bewahren die Autorität der Repository-Regeln, während sie Implementierungscode und kanonische Wahrheitsdokumente als Belege für aktuelles Verhalten behandeln.
|
||||
|
||||
Generierte Flächen werden von Truthmark verwaltet, enthalten einen Versionsmarker und können mit `truthmark init` aktualisiert werden.
|
||||
|
||||
## Befehle
|
||||
|
||||
Truthmark V1 hält die CLI absichtlich klein. In nachgelagerten Repositories erzeugt `truthmark config` den in Git festgeschriebenen Hierarchievertrag, `truthmark init` installiert und aktualisiert Workflow-Flächen aus dieser geprüften Konfiguration, und `truthmark check` validiert Wahrheitsartefakte für manuelle Audits, CI oder Fehlersuche.
|
||||
Truthmark V1 hält die CLI fokussiert, weil der laufende Workflow in den installierten Agenten-Flächen leben soll und nicht in einer langen Liste täglicher manueller Befehle. In nachgelagerten Repositories erzeugt `truthmark config` den in Git festgeschriebenen Hierarchievertrag, `truthmark init` installiert und aktualisiert Workflow-Flächen aus dieser geprüften Konfiguration, `truthmark check` validiert Wahrheitsartefakte für manuelle Audits, CI oder Fehlersuche, und die Repository-Intelligence-Befehle erzeugen abgeleitete Prüfarbeitsstände, wenn lokale Werkzeuge verfügbar sind.
|
||||
|
||||
```bash
|
||||
truthmark config
|
||||
truthmark init
|
||||
truthmark check
|
||||
truthmark index
|
||||
truthmark impact --base main
|
||||
truthmark context --workflow truth-sync --base main
|
||||
truthmark config --json
|
||||
truthmark check --json
|
||||
truthmark index --json
|
||||
truthmark impact --base main --json
|
||||
truthmark context --workflow truth-sync --base main --json
|
||||
```
|
||||
|
||||
`config` schreibt nur `.truthmark/config.yml`, außer `--stdout` wird verwendet.
|
||||
|
||||
`init` benötigt `.truthmark/config.yml` und installiert oder aktualisiert anschließend die lokalen Workflow-Dateien.
|
||||
|
||||
`check` validiert Konfiguration, Autorität, Routing, entscheidungstragende Dokumente, Frontmatter, interne Links, Branch-Scope und Coverage-Diagnostik.
|
||||
Truth Structure, Truth Sync, Truth Realize und Truth Check sind installierte Agenten-Workflows, keine täglichen Top-Level-CLI-Befehle.
|
||||
|
||||
`index` baut RepoIndex- und RouteMap-JSON für den aktiven Checkout.
|
||||
|
||||
`impact --base <ref>` ordnet geänderte Dateien den gerouteten Truth-Dokumenten, Routen, nahen Tests und öffentlichen Symbolen zu.
|
||||
|
||||
`context --workflow <workflow> [--base <ref>]` erzeugt ein begrenztes ContextPack für Truth Sync, Truth Document oder Truth Realize. `--format markdown` rendert eine menschenlesbare Fassung.
|
||||
|
||||
Truth Structure, Truth Document, Truth Sync, Truth Realize und Truth Check sind installierte Agenten-Workflows, keine täglichen Top-Level-CLI-Befehle.
|
||||
|
||||
Sie laufen über die konfigurierten Agenten-Host-Flächen, zum Beispiel Codex/Claude/Copilot `/truthmark-*`, OpenCode `/skill truthmark-*` oder Gemini `/truthmark:*`.
|
||||
|
||||
```text
|
||||
/truthmark-check routing und truth-abdeckung vor der review prüfen
|
||||
```
|
||||
|
||||
## Warum es existiert
|
||||
|
||||
@@ -199,16 +286,21 @@ Es geht davon aus, dass ernsthafte Teams Folgendes brauchen:
|
||||
|
||||
## Projektstatus
|
||||
|
||||
Truthmark ist kein Memory-Server und kein MCP-Server. Es ist eine Repository-Praxis, verpackt als kleiner CLI-Installer plus agent-native Workflow-Flächen.
|
||||
Truthmark ist kein Memory-Server und kein MCP-Server. Es ist eine Repository-Praxis, verpackt als kleiner CLI-Installer plus agent-native Workflow-Flächen, die KI-Workflow-Regeln in Repository-Infrastruktur verwandeln.
|
||||
|
||||
V1 bietet derzeit:
|
||||
|
||||
- `truthmark config`
|
||||
- `truthmark init`
|
||||
- `truthmark check`
|
||||
- `truthmark index`
|
||||
- `truthmark impact`
|
||||
- `truthmark context`
|
||||
- verwaltete `AGENTS.md`-Workflow-Anweisungen
|
||||
- generierte Skill-Flächen für Truth Structure, Truth Sync, Truth Realize und Truth Check für konfigurierte Agenten-Hosts
|
||||
- generierte Truth Structure-, Truth Document-, Truth Sync-, Truth Realize- und Truth Check-Skill-Flächen für konfigurierte Agenten-Hosts
|
||||
- Branch-Scope-Metadaten
|
||||
- Diagnostik für Konfiguration, Autorität, Routing, Entscheidungsstruktur, Frontmatter, Links und polyglotte Abdeckung
|
||||
- Diagnostik für Konfiguration, Autorität, Routing, Entscheidungsstruktur, Frontmatter, Links, Freshness und polyglotte Abdeckung
|
||||
- abgeleitete RepoIndex-, RouteMap-, ImpactSet- und ContextPack-Artefakte für schnellere lokale Prüfung, wenn die CLI verfügbar ist
|
||||
|
||||
## Dokumentation
|
||||
|
||||
@@ -216,10 +308,10 @@ Die Root-README ist für Menschen gedacht, die das Paket evaluieren und ausprobi
|
||||
|
||||
- [Dokumentationsindex](docs/README.md)
|
||||
- [Architekturüberblick](docs/architecture/overview.md)
|
||||
- [API- und CLI-Verträge](docs/features/contracts.md)
|
||||
- [Init- und Scaffold-Verhalten](docs/features/init-and-scaffold.md)
|
||||
- [Check-Diagnostik](docs/features/check-diagnostics.md)
|
||||
- [Installierte Workflows](docs/features/installed-workflows.md)
|
||||
- [API- und CLI-Verträge](docs/truth/contracts.md)
|
||||
- [Init- und Scaffold-Verhalten](docs/truth/init-and-scaffold.md)
|
||||
- [Check-Diagnostik](docs/truth/check-diagnostics.md)
|
||||
- [Installierte Workflows](docs/truth/workflows/overview.md)
|
||||
- [Leitfaden zur Pflege von Repository-Wahrheit](docs/standards/maintaining-repository-truth.md)
|
||||
|
||||
Aktuelles Verhalten gehört in den oben genannten kanonischen Dokumentationsbaum.
|
||||
|
||||
+154
-62
@@ -1,31 +1,68 @@
|
||||
# Truthmark es la capa de verdad para el desarrollo de software con IA.
|
||||
# Truthmark
|
||||
|
||||
**Truthmark instala flujos de verdad del repositorio para el desarrollo de software con IA.**
|
||||
|
||||
[English](README.md) | [Deutsch](README.de.md) | [中文](README.zh.md) | Español | [Русский](README.ru.md)
|
||||
|
||||
Los agentes de programación con IA ya escriben código bastante bien. Lo que todavía hacen mal es reconstruir de forma fiable la intención del producto, los límites de arquitectura y la responsabilidad sobre cada parte del repositorio a partir de documentación obsoleta, conversaciones dispersas y memoria temporal de herramientas.
|
||||
<img src="docs/assets/truthmark-banner.png" alt="Banner de Truthmark" width="100%" />
|
||||
|
||||
## Qué resuelve Truthmark
|
||||
Los agentes de programación con IA ya escriben código rápido. La parte costosa es mantener alineada la verdad del repositorio con lo que realmente cambió.
|
||||
|
||||
Truthmark lo resuelve convirtiendo la verdad local de cada rama en una superficie de ejecución de primera clase para los agentes. Instala una capa de verdad nativa de Git, acotada a la rama, directamente dentro del repositorio; da a los agentes rutas y límites de flujo de trabajo explícitos; y hace que esa verdad viaje con el código que realmente se entrega.
|
||||
Esto no es mejor ingeniería de prompts. Es una forma más gobernable de usar IA en una base de código real: menos decisiones repetidas, menos documentación obsoleta, traspasos más limpios y sesiones de programación con IA que dejan registros de ingeniería revisables en lugar de desaparecer en el historial de prompts o en estados opacos de herramientas.
|
||||
Está pensado para equipos que ya saben que los agentes pueden generar código y ahora necesitan que el repositorio siga siendo legible, revisable y gobernable.
|
||||
Empezar a programar con IA ya es fácil; gobernarlo es lo costoso. Cuando los agentes pueden escribir código rápido, la verdad del repositorio se convierte en la superficie de control.
|
||||
Ese fallo aparece de forma predecible: los requisitos se quedan en chats, las decisiones de arquitectura se repiten, los agentes tocan las zonas equivocadas y las ramas heredan contexto que los revisores no pueden inspeccionar con confianza. El código puede avanzar rápido, pero el repositorio se vuelve más difícil de confiar.
|
||||
Truthmark cambia el modelo de trabajo:
|
||||
Truthmark añade una guarda de cierre basada en flujo de trabajo. El camino normal es simple:
|
||||
|
||||
- La verdad local de la rama viaja con la rama, en lugar de vivir en un almacén privado de herramientas.
|
||||
- Git hace que esa verdad sea revisable, comparable y compartible con el equipo.
|
||||
- La documentación sigue al código en lugar de derivar silenciosamente hacia la ficción.
|
||||
- El enrutamiento permanece explícito en `docs/truthmark/areas.md` y en archivos de rutas secundarias delegadas, para que los agentes sepan qué documentación gobierna qué código.
|
||||
- Las decisiones activas de producto y arquitectura viven en los documentos canónicos que gobiernan, no en registros de planificación con marca de tiempo.
|
||||
- Los flujos de trabajo locales evitan depender de un demonio, una base de datos, un servicio remoto o MCP.
|
||||
- El modelo funciona en bases de código JavaScript, TypeScript, Go, Python, C# y Java.
|
||||
- el agente cambia código funcional
|
||||
- se ejecutan las pruebas relevantes
|
||||
- el flujo instalado Truth Sync actualiza los documentos de verdad asignados antes de que el agente termine
|
||||
- se revisa el diff de documentos de verdad si se produjo uno
|
||||
|
||||
Para responsables técnicos, el valor es gobernanza sin teatro: las pruebas, la revisión de código y la propiedad siguen haciendo el trabajo real; Truthmark vuelve el contexto del agente duradero, inspeccionable y acotado a la rama.
|
||||
La mayoría de las herramientas pide al equipo adoptar un hábito. Truthmark convierte ese hábito en infraestructura de flujo del repositorio.
|
||||
|
||||
Truthmark convierte un flujo de trabajo con IA en infraestructura del repositorio, no en tooling personal. Instala una capa de verdad nativa de Git y acotada a la rama dentro del propio repositorio, da a los agentes rutas explícitas y superficies de trabajo acotadas, y mantiene esa verdad revisable en Git en lugar de dispersarla por el historial de prompts, documentación obsoleta o estado privado de herramientas.
|
||||
|
||||
Eso importa porque el flujo vive con la rama. Una vez inicializado un repositorio, las reglas, el enrutamiento y las superficies instaladas viajan dentro del repo, así que la colaboración y los traspasos dependen menos de la configuración local de una sola persona.
|
||||
|
||||
Para equipos que ya saben que los agentes pueden generar código, Truthmark responde al siguiente problema: cómo hacer que el repositorio siga siendo legible, revisable y gobernable a medida que crece el trabajo asistido por IA.
|
||||
|
||||
## Resumen visual
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td align="center" width="50%">
|
||||
<img src="docs/assets/truthmark-features.png" alt="Características de Truthmark" width="100%" />
|
||||
<br><strong>Características</strong><br>
|
||||
Lo que instala Truthmark y cómo se divide la superficie de trabajo.
|
||||
</td>
|
||||
<td align="center" width="50%">
|
||||
<img src="docs/assets/truthmark-position.png" alt="Posicionamiento de Truthmark" width="100%" />
|
||||
<br><strong>Posicionamiento</strong><br>
|
||||
Dónde encaja Truthmark frente a prompts, memoria y flujos spec-first.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td align="center" colspan="2">
|
||||
<img src="docs/assets/truthmark-syncflow.png" alt="Flujo de sync de Truthmark" width="100%" />
|
||||
<br><strong>Flujo de sync</strong><br>
|
||||
Cómo Truth Sync cierra cambios normales de código antes del traspaso.
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
## Por qué los equipos lo adoptan
|
||||
|
||||
Truthmark no intenta hacer que los agentes suenen más inteligentes. Intenta que los cambios de repositorio asistidos por IA sean más confiables.
|
||||
|
||||
- El flujo instalado Truth Sync tras cambios de código convierte el mantenimiento de documentación en una salvaguarda del flujo, no en un hábito del equipo.
|
||||
- La verdad acotada a la rama viaja con el código, de modo que quienes revisan pueden inspeccionar la verdad actual en diffs normales de Git.
|
||||
- Las superficies de flujo nativas del repositorio hacen el despliegue más ligero y los traspasos más resistentes que una simple configuración por usuario.
|
||||
- El enrutamiento explícito en `docs/truthmark/areas.md` y en archivos de rutas secundarias delegadas da a los agentes límites de responsabilidad y rutas de escritura más seguras.
|
||||
- La operación local-first evita depender de un demonio, una base de datos, un servicio remoto o MCP.
|
||||
- El modelo de enrutamiento es independiente del lenguaje, con diagnósticos de cobertura para superficies comunes de código JavaScript, TypeScript, Go, Python, C# y Java.
|
||||
|
||||
Para responsables técnicos, el valor es gobernanza sin infraestructura extra: las pruebas, la revisión de código y la propiedad siguen haciendo el trabajo real; Truthmark vuelve el contexto del agente duradero, inspeccionable y acotado a la rama.
|
||||
|
||||
## Dónde encaja Truthmark
|
||||
|
||||
Truthmark no intenta reemplazar todas las demás herramientas de flujo de trabajo con IA. Ocupa una capa concreta de la pila:
|
||||
Truthmark no es una suite general de productividad para IA. Ocupa una capa concreta de la pila: verdad de repositorio revisable, acotada a la rama y alineada con la implementación.
|
||||
|
||||
| Si necesitas | Mejor opción |
|
||||
| ------------------------------------------------------------------------------ | -------------------------------------------- |
|
||||
@@ -38,9 +75,9 @@ La idea no es que los prompts, la memoria o las especificaciones no sirvan. La i
|
||||
|
||||
## Contenido
|
||||
|
||||
- [Por qué los equipos lo adoptan](#por-qué-los-equipos-lo-adoptan)
|
||||
- [Qué resuelve Truthmark](#qué-resuelve-truthmark)
|
||||
- [Dónde encaja Truthmark](#dónde-encaja-truthmark)
|
||||
- [Superficie de flujo](#superficie-de-flujo)
|
||||
- [Primeros pasos](#primeros-pasos)
|
||||
- [Cómo se ejecuta](#cómo-se-ejecuta)
|
||||
- [Qué instala](#qué-instala)
|
||||
@@ -51,12 +88,13 @@ La idea no es que los prompts, la memoria o las especificaciones no sirvan. La i
|
||||
- [No objetivos](#no-objetivos)
|
||||
- [Licencia](#licencia)
|
||||
|
||||
## Superficie de flujo
|
||||
## Qué resuelve Truthmark
|
||||
|
||||
Truthmark convierte la verdad del repositorio en una superficie explícita de flujo de trabajo para agentes:
|
||||
|
||||
- `TRUTHMARK.md` define el contrato de flujo de trabajo local a la rama.
|
||||
- `.truthmark/config.yml` define el contrato de jerarquía confirmado en el repositorio.
|
||||
- `docs/truthmark/areas.md` y los archivos de rutas secundarias delegadas asignan áreas de código a los documentos que las gobiernan.
|
||||
- Truth Document genera o repara documentos de verdad canónica para comportamiento ya implementado cuando no hace falta cambiar código.
|
||||
- Truth Sync mantiene alineados los documentos de verdad asignados cuando hay cambios funcionales.
|
||||
- Truth Realize ofrece a los cambios que empiezan en documentación una ruta acotada para actualizar código.
|
||||
- `truthmark check` valida los artefactos de verdad resultantes.
|
||||
@@ -92,96 +130,145 @@ Revisa `.truthmark/config.yml` antes de `init`; es el contrato de jerarquía con
|
||||
|
||||
```text
|
||||
.truthmark/config.yml
|
||||
TRUTHMARK.md
|
||||
docs/truthmark/areas.md
|
||||
docs/truthmark/areas/repository.md
|
||||
docs/features/README.md
|
||||
docs/features/repository/README.md
|
||||
docs/features/repository/overview.md
|
||||
docs/templates/behavior-doc.md
|
||||
docs/truth/README.md
|
||||
docs/truth/repository/README.md
|
||||
docs/truth/repository/overview.md
|
||||
AGENTS.md
|
||||
CLAUDE.md
|
||||
.codex/skills/truthmark-structure/SKILL.md
|
||||
.codex/skills/truthmark-sync/SKILL.md
|
||||
.codex/skills/truthmark-realize/SKILL.md
|
||||
.codex/skills/truthmark-check/SKILL.md
|
||||
.opencode/skills/truthmark-structure/SKILL.md
|
||||
.opencode/skills/truthmark-sync/SKILL.md
|
||||
.opencode/skills/truthmark-realize/SKILL.md
|
||||
.opencode/skills/truthmark-check/SKILL.md
|
||||
GEMINI.md
|
||||
```
|
||||
|
||||
Si habilitas plataformas adicionales en `.truthmark/config.yml`, Truthmark actualizará las superficies administradas correspondientes en el siguiente `init`.
|
||||
La estructura generada por defecto usa los `README.md` de funciones como índices y empieza la verdad sobre el comportamiento actual en documentos hoja acotados, como `docs/features/repository/overview.md`.
|
||||
Las plataformas compatibles son `codex`, `opencode`, `claude-code`, `github-copilot` y `gemini-cli`. La configuración predeterminada las incluye todas; elimina de `.truthmark/config.yml` las plataformas que no uses antes de volver a ejecutar `truthmark init`.
|
||||
La estructura generada por defecto usa los `README.md` de verdad como índices y empieza la verdad sobre el comportamiento actual en documentos hoja acotados, como `docs/truth/repository/overview.md`.
|
||||
|
||||
Los repositorios existentes suelen necesitar una pasada de limpieza después de `init`: ejecuta el flujo instalado Truth Structure cuando la ruta `repository` generada sea demasiado amplia, la propiedad abarque varios productos o servicios, o los archivos de rutas sigan apuntando a documentos de marcador de posición. Truth Structure divide rutas amplias, crea o repara documentos de verdad canónica iniciales y da a Truth Sync destinos precisos antes de que empiece el trabajo de código funcional. Los usuarios de Codex pueden invocarlo con `/truthmark-structure` o `$truthmark-structure`; los hosts de estilo OpenCode pueden usar `/skill truthmark-structure`.
|
||||
Los repositorios existentes suelen necesitar una pasada de limpieza después de `init`: ejecuta el flujo instalado Truth Structure cuando la ruta `repository` generada sea demasiado amplia, la propiedad abarque varios productos o servicios, o los archivos de rutas sigan apuntando a documentos de marcador de posición. Truth Structure divide rutas amplias, crea o repara documentos de verdad canónica iniciales y da a Truth Sync destinos precisos antes de que empiece el trabajo de código funcional. Codex, Claude Code y los IDEs de Copilot compatibles pueden invocarlo con `/truthmark-structure`; los hosts de estilo OpenCode pueden usar `/skill truthmark-structure`.
|
||||
|
||||
## Cómo se ejecuta
|
||||
|
||||
Truthmark no especifica qué subagente debe ejecutar Truth Sync. El agente que actúa y el entorno anfitrión deciden si delegan o ejecutan el flujo en línea.
|
||||
La mayoría de los usuarios no debería invocar Truth Sync directamente. El flujo normal es:
|
||||
Truthmark es más fuerte en el camino por defecto, no como un conjunto de comandos manuales. El agente que actúa y el entorno anfitrión deciden si delegan o ejecutan el flujo instalado en línea.
|
||||
|
||||
### Comportamiento existente sin docs
|
||||
|
||||
Usa esto cuando la implementación ya existe pero faltan o son débiles los documentos de verdad canónica:
|
||||
|
||||
```text
|
||||
el usuario identifica un comportamiento implementado o un endpoint de api
|
||||
el usuario invoca explícitamente truth document
|
||||
el agente lee implementación, pruebas, rutas y docs existentes
|
||||
el agente solo escribe truth docs y rutas
|
||||
revisar el diff de truth docs
|
||||
```
|
||||
|
||||
Truth Document es manual y con prioridad de implementación: el código sirve como evidencia, los documentos de verdad se crean o reparan, y no se debe cambiar código funcional. Codex, Claude Code y los IDEs de Copilot compatibles pueden invocarlo con `/truthmark-document`; los hosts de estilo OpenCode pueden usar `/skill truthmark-document`.
|
||||
|
||||
```text
|
||||
/truthmark-document documenta el comportamiento implementado del timeout de sesión en docs/truth/authentication
|
||||
```
|
||||
|
||||
### Cambios de código normales
|
||||
|
||||
La mayoría de los usuarios no debería invocar Truth Sync directamente. Lo importante es que el flujo instalado del agente trate Truth Sync como una guarda de cierre cuando cambió código funcional. El flujo normal es:
|
||||
|
||||
```text
|
||||
el agente cambia código funcional
|
||||
se ejecutan las pruebas relevantes
|
||||
Truth Sync se dispara antes de que el agente termine
|
||||
se revisa el diff de documentos de verdad si se produjo uno
|
||||
se confirma o se entrega el trabajo
|
||||
el flujo instalado truth sync se ejecuta antes de que el agente termine
|
||||
revisar el diff de truth docs si se produjo uno
|
||||
confirmar o entregar el trabajo
|
||||
```
|
||||
|
||||
Truth Sync es code-first: el código lidera, los documentos de verdad siguen, y Truth Sync no debe reescribir código funcional. Su tarea principal es actuar como salvaguarda automática al cierre cuando cambió código funcional. La invocación directa se usa sobre todo para depurar, forzar una sincronización temprana antes de entregar el trabajo o ejecutar el flujo de forma intencional.
|
||||
Los usuarios de Codex pueden invocarlo con `/truthmark-sync` o `$truthmark-sync`. Los hosts de estilo OpenCode pueden usar `/skill truthmark-sync`.
|
||||
Truth Sync es code-first: el código lidera, los documentos de verdad siguen, y Truth Sync no debe reescribir código funcional. Su tarea principal es ejecutarse mediante el flujo instalado del agente como guarda de cierre cuando cambió código funcional. La invocación directa se usa sobre todo para depurar, forzar una sincronización temprana antes de entregar el trabajo o ejecutar el flujo de forma intencional.
|
||||
|
||||
Codex, Claude Code y los IDEs de Copilot compatibles pueden invocarlo con `/truthmark-sync`. Los hosts de estilo OpenCode pueden usar `/skill truthmark-sync`.
|
||||
|
||||
```text
|
||||
/truthmark-sync sincroniza ahora la verdad del repositorio antes de la entrega
|
||||
```
|
||||
|
||||
### Cambios doc-first
|
||||
|
||||
Usa este flujo cuando una decisión de producto o arquitectura empieza en la documentación:
|
||||
|
||||
```text
|
||||
el usuario edita los documentos de verdad
|
||||
el usuario invoca explícitamente Truth Realize
|
||||
el agente lee los documentos de verdad y el código relevante
|
||||
el usuario edita truth docs
|
||||
el usuario invoca explícitamente truth realize
|
||||
el agente lee truth docs y el código relevante
|
||||
el agente actualiza solo el código
|
||||
se ejecutan las pruebas relevantes
|
||||
se confirma o se entrega el trabajo
|
||||
confirmar o entregar el trabajo
|
||||
```
|
||||
|
||||
Truth Realize es manual y doc-first: los documentos de verdad lideran, el código sigue, y el agente no debe editar los documentos de verdad que está realizando.
|
||||
Los usuarios de Codex pueden invocarlo con `/truthmark-realize` o `$truthmark-realize`. Los hosts de estilo OpenCode pueden usar `/skill truthmark-realize`.
|
||||
|
||||
Codex, Claude Code y los IDEs de Copilot compatibles pueden invocarlo con `/truthmark-realize`. Los hosts de estilo OpenCode pueden usar `/skill truthmark-realize`.
|
||||
|
||||
```text
|
||||
/truthmark-realize realiza docs/truth/authentication/session-timeout.md como código
|
||||
```
|
||||
|
||||
## Qué instala
|
||||
|
||||
Truthmark mantiene pequeña la superficie duradera de flujo de trabajo:
|
||||
Truthmark mantiene pequeña y nativa del repositorio la superficie duradera de flujo de trabajo. Después de `truthmark init`, el propio repositorio lleva el enrutamiento, las reglas y las superficies instaladas, así que el equipo no depende solo de la configuración local de una persona.
|
||||
|
||||
- `.truthmark/config.yml` para configuración legible por máquina
|
||||
- `TRUTHMARK.md` para el contrato de flujo de trabajo local a la rama
|
||||
- `.truthmark/config.yml` para el contrato de jerarquía confirmado y legible por máquina
|
||||
- `docs/truthmark/areas.md` para el índice raíz de rutas
|
||||
- `docs/truthmark/areas/**/*.md` para archivos de rutas secundarias delegadas
|
||||
- bloques de instrucciones administrados para plataformas configuradas como `AGENTS.md`, `CLAUDE.md`, reglas de Cursor, instrucciones de Copilot y `GEMINI.md`
|
||||
- skills locales del repositorio y de Codex para Truth Structure, Truth Sync, Truth Realize y Truth Check
|
||||
- `docs/templates/behavior-doc.md` y las demás plantillas específicas por tipo bajo `docs/templates/` para los estándares editables de truth docs usados por los flujos generados
|
||||
- bloques de instrucciones administrados para plataformas configuradas como `AGENTS.md`, `CLAUDE.md`, instrucciones de Copilot y `GEMINI.md`
|
||||
- skills, prompts o comandos nativos del host para Truth Structure, Truth Document, Truth Sync, Truth Realize y Truth Check
|
||||
|
||||
Las superficies de flujo de trabajo instaladas son el entorno de ejecución:
|
||||
|
||||
- Truth Structure crea o repara el enrutamiento de áreas y documentos de verdad iniciales.
|
||||
- Truth Document crea o repara documentos de verdad para comportamiento ya implementado.
|
||||
- Truth Sync mantiene alineados los documentos de verdad asignados con los cambios funcionales.
|
||||
- Truth Realize actualiza el código para que coincida con los documentos de verdad.
|
||||
- Truth Check audita la salud de la verdad del repositorio.
|
||||
|
||||
Los `README.md` de funciones son índices. Se espera que Truth Sync lea y actualice documentos hoja acotados para el comportamiento actual.
|
||||
Los `README.md` de funciones son índices. Se espera que Truth Sync lea y actualice documentos hoja acotados para el comportamiento actual. Las superficies de flujo generadas preservan la autoridad de las reglas del repositorio mientras tratan el código de implementación y los documentos canónicos de verdad como evidencia del comportamiento actual.
|
||||
|
||||
Las superficies generadas son administradas por Truthmark, incluyen un marcador de versión y pueden refrescarse con `truthmark init`.
|
||||
|
||||
## Comandos
|
||||
|
||||
Truthmark V1 mantiene la CLI pequeña a propósito. En repositorios derivados, `truthmark config` crea el contrato de jerarquía confirmado en Git, `truthmark init` instala y refresca superficies de flujo de trabajo a partir de esa configuración revisada, y `truthmark check` valida los artefactos de verdad para auditorías manuales, CI o depuración.
|
||||
Truthmark V1 mantiene la CLI pequeña a propósito porque el flujo continuo debe vivir en las superficies instaladas del agente, no en una lista larga de comandos manuales de uso diario. En repositorios derivados, `truthmark config` crea el contrato de jerarquía confirmado en Git, `truthmark init` instala y refresca superficies de flujo de trabajo a partir de esa configuración revisada, `truthmark check` valida los artefactos de verdad para auditorías manuales, CI o depuración, y los comandos de inteligencia del repositorio generan artefactos derivados de revisión cuando hay herramientas locales disponibles.
|
||||
|
||||
```bash
|
||||
truthmark config
|
||||
truthmark init
|
||||
truthmark check
|
||||
truthmark index
|
||||
truthmark impact --base main
|
||||
truthmark context --workflow truth-sync --base main
|
||||
truthmark config --json
|
||||
truthmark check --json
|
||||
truthmark index --json
|
||||
truthmark impact --base main --json
|
||||
truthmark context --workflow truth-sync --base main --json
|
||||
```
|
||||
|
||||
`config` solo escribe `.truthmark/config.yml`, salvo que se use `--stdout`.
|
||||
|
||||
`init` requiere `.truthmark/config.yml` y luego instala o refresca los archivos locales de flujo de trabajo.
|
||||
|
||||
`check` valida configuración, autoridad, enrutamiento, documentos que contienen decisiones, frontmatter, enlaces internos, alcance de rama y diagnósticos de cobertura.
|
||||
Truth Structure, Truth Sync, Truth Realize y Truth Check son flujos de trabajo instalados para agentes, no comandos CLI principales de uso diario.
|
||||
|
||||
`index` construye JSON de RepoIndex y RouteMap para el checkout activo.
|
||||
|
||||
`impact --base <ref>` mapea los archivos cambiados a los truth docs enrutados, rutas propietarias, pruebas cercanas y símbolos públicos.
|
||||
|
||||
`context --workflow <workflow> [--base <ref>]` genera un ContextPack acotado para Truth Sync, Truth Document o Truth Realize. `--format markdown` lo renderiza en un formato legible para personas.
|
||||
|
||||
Truth Structure, Truth Document, Truth Sync, Truth Realize y Truth Check son flujos de trabajo instalados para agentes, no comandos CLI principales de uso diario.
|
||||
|
||||
Se ejecutan a través de las superficies configuradas del host agente, por ejemplo Codex/Claude/Copilot `/truthmark-*`, OpenCode `/skill truthmark-*` o Gemini `/truthmark:*`.
|
||||
|
||||
```text
|
||||
/truthmark-check audita el enrutamiento y la cobertura de verdad antes de la revisión
|
||||
```
|
||||
|
||||
## Por qué existe
|
||||
|
||||
@@ -199,16 +286,21 @@ Asume que los equipos serios necesitan:
|
||||
|
||||
## Estado del proyecto
|
||||
|
||||
Truthmark no es un servidor de memoria ni un servidor MCP. Es una práctica de repositorio empaquetada como un pequeño instalador CLI más superficies de flujo de trabajo nativas para agentes.
|
||||
Truthmark no es un servidor de memoria ni un servidor MCP. Es una práctica de repositorio empaquetada como un pequeño instalador CLI más superficies de flujo de trabajo nativas para agentes que convierten las reglas del flujo de IA en infraestructura del repositorio.
|
||||
|
||||
V1 actualmente ofrece:
|
||||
|
||||
- `truthmark config`
|
||||
- `truthmark init`
|
||||
- `truthmark check`
|
||||
- `truthmark index`
|
||||
- `truthmark impact`
|
||||
- `truthmark context`
|
||||
- instrucciones de flujo de trabajo administradas en `AGENTS.md`
|
||||
- superficies de skill generadas para Truth Structure, Truth Sync, Truth Realize y Truth Check en los anfitriones de agentes configurados
|
||||
- superficies de skill generadas para Truth Structure, Truth Document, Truth Sync, Truth Realize y Truth Check en los anfitriones de agentes configurados
|
||||
- metadatos de alcance de rama
|
||||
- diagnósticos de configuración, autoridad, enrutamiento, estructura de decisiones, frontmatter, enlaces y cobertura políglota
|
||||
- artefactos derivados de RepoIndex, RouteMap, ImpactSet y ContextPack para una revisión local más rápida cuando la CLI está disponible
|
||||
|
||||
## Documentación
|
||||
|
||||
@@ -216,10 +308,10 @@ El README raíz es para personas que evalúan y prueban el paquete. Las especifi
|
||||
|
||||
- [Índice de documentación](docs/README.md)
|
||||
- [Resumen de arquitectura](docs/architecture/overview.md)
|
||||
- [Contratos de API y CLI](docs/features/contracts.md)
|
||||
- [Comportamiento de init y scaffold](docs/features/init-and-scaffold.md)
|
||||
- [Diagnósticos de check](docs/features/check-diagnostics.md)
|
||||
- [Flujos de trabajo instalados](docs/features/installed-workflows.md)
|
||||
- [Contratos de API y CLI](docs/truth/contracts.md)
|
||||
- [Comportamiento de init y scaffold](docs/truth/init-and-scaffold.md)
|
||||
- [Diagnósticos de check](docs/truth/check-diagnostics.md)
|
||||
- [Flujos de trabajo instalados](docs/truth/workflows/overview.md)
|
||||
- [Guía para mantener la verdad del repositorio](docs/standards/maintaining-repository-truth.md)
|
||||
|
||||
El comportamiento actual pertenece al árbol canónico de documentación anterior.
|
||||
|
||||
@@ -1,40 +1,68 @@
|
||||
# Truthmark
|
||||
|
||||
**Truthmark is the truth layer for AI software development.**
|
||||
**Truthmark installs repository truth workflows for AI software development.**
|
||||
|
||||
English | [Deutsch](README.de.md) | [中文](README.zh.md) | [Español](README.es.md) | [Русский](README.ru.md)
|
||||
|
||||
|
||||
<img src="docs/assets/truthmark-banner.png" alt="Truthmark banner" width="100%" />
|
||||
|
||||
AI coding agents are already good at writing code. They are still bad at reliably reconstructing product intent, architecture boundaries, and repository ownership from stale docs, scattered chats, and ephemeral tool memory.
|
||||
AI coding agents already write code fast. The expensive part is keeping repository truth aligned with what changed.
|
||||
|
||||
Truthmark fixes that by turning branch-local repository truth into a first-class runtime surface for agents. It installs a Git-native, branch-scoped truth layer directly inside the repo, gives agents explicit routing and workflow boundaries, and makes that truth move with the code that actually ships.
|
||||
Truthmark adds a finish-time workflow guard to that workflow. The normal path is simple:
|
||||
|
||||
This is not better prompt engineering. It is a more governable way to use AI in a real codebase: fewer repeated decisions, fewer stale docs, cleaner handoffs, and AI coding sessions that leave behind reviewable engineering records instead of disappearing into prompt history or opaque tool state.
|
||||
- agent changes functional code
|
||||
- run relevant tests
|
||||
- the installed Truth Sync workflow updates mapped truth docs before the agent finishes
|
||||
- review the truth-doc diff if one was produced
|
||||
|
||||
For teams who already know agents can generate code, and now need the repository itself to stay legible, reviewable, and governable.
|
||||
Most tools ask teams to adopt a habit. Truthmark turns the habit into repository workflow infrastructure.
|
||||
|
||||
## Why teams try it
|
||||
Truthmark turns an AI workflow into repo infrastructure, not personal tooling. It installs a Git-native, branch-scoped truth layer inside the repository, gives agents explicit routing and bounded workflow surfaces, and keeps that truth reviewable in Git instead of scattering it across prompt history, stale docs, or private tool memory.
|
||||
|
||||
AI coding is now easy to start and expensive to govern. Once agents can write code quickly, repository truth becomes the control surface.
|
||||
That matters because the workflow lives with the branch. Once a repository is initialized, the rules, routing, and installed workflow surfaces travel in-repo, so collaboration and handoffs are less dependent on one person's machine setup.
|
||||
|
||||
That failure mode shows up in predictable ways: requirements live in chat, architecture decisions get repeated, agents touch the wrong surfaces, and branches inherit context that reviewers cannot reliably inspect. The code may move fast, but the repository gets harder to trust.
|
||||
For teams who already know agents can generate code, Truthmark answers the next problem: how to keep the repository itself legible, reviewable, and governable as AI-assisted work scales.
|
||||
|
||||
Truthmark changes the working model:
|
||||
## Visual overview
|
||||
|
||||
- Branch-local truth travels with the branch instead of living in a private tool store.
|
||||
- Git makes that truth reviewable, diffable, and shareable across the team.
|
||||
- Docs follow code instead of drifting quietly into fiction.
|
||||
- Routing stays explicit in `docs/truthmark/areas.md` and delegated child route files so agents know which docs own which code.
|
||||
- Active product and architecture decisions live in the canonical docs they govern instead of in timestamped planning logs.
|
||||
- Local-first workflows avoid a daemon, database, remote service, or MCP dependency.
|
||||
- The model works across JavaScript, TypeScript, Go, Python, C#, and Java codebases.
|
||||
<table>
|
||||
<tr>
|
||||
<td align="center" width="50%">
|
||||
<img src="docs/assets/truthmark-features.png" alt="Truthmark features" width="100%" />
|
||||
<br><strong>Features</strong><br>
|
||||
What Truthmark installs and how the workflow surface is split.
|
||||
</td>
|
||||
<td align="center" width="50%">
|
||||
<img src="docs/assets/truthmark-position.png" alt="Truthmark position" width="100%" />
|
||||
<br><strong>Position</strong><br>
|
||||
Where Truthmark fits relative to prompts, memory, and spec workflows.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td align="center" colspan="2">
|
||||
<img src="docs/assets/truthmark-syncflow.png" alt="Truthmark sync flow" width="100%" />
|
||||
<br><strong>Sync flow</strong><br>
|
||||
How Truth Sync closes out normal code changes before handoff.
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
For tech leads, the value is governance without theater: tests, code review, and ownership still do the real work; Truthmark makes the agent's context durable, inspectable, and branch-scoped.
|
||||
## Why teams adopt it
|
||||
|
||||
Truthmark is not trying to make agents sound smarter. It is trying to make AI-assisted repository change easier to trust.
|
||||
|
||||
- Installed Truth Sync after code changes turns documentation maintenance into a workflow safeguard instead of a team habit.
|
||||
- Branch-scoped truth moves with the code, so reviewers can inspect current truth in ordinary Git diffs.
|
||||
- Repository-native workflow surfaces make rollout lighter and handoffs more resilient than per-user setup alone.
|
||||
- Explicit routing in `docs/truthmark/areas.md` and delegated child route files gives agents ownership boundaries and safer write paths.
|
||||
- Local-first operation avoids a daemon, database, remote service, or MCP dependency.
|
||||
- The routing model is language-agnostic, with coverage diagnostics for common JavaScript, TypeScript, Go, Python, C#, and Java code surfaces.
|
||||
|
||||
For tech leads, the value is governance without extra infrastructure: tests, code review, and ownership still do the real work; Truthmark makes the agent's context durable, inspectable, and branch-scoped.
|
||||
|
||||
## Where Truthmark fits
|
||||
|
||||
Truthmark is not trying to replace every other AI workflow tool. It sits in a specific layer of the stack:
|
||||
Truthmark is not a general AI productivity suite. It occupies a specific layer of the stack: branch-scoped, reviewable repository truth that stays aligned with implementation.
|
||||
|
||||
| If you need | Best fit |
|
||||
| --------------------------------------------------------------------- | --------------------------------------- |
|
||||
@@ -47,6 +75,7 @@ The point is not that prompts, memory, or specs are useless. The point is that n
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Why teams adopt it](#why-teams-adopt-it)
|
||||
- [What Truthmark solves](#what-truthmark-solves)
|
||||
- [Where Truthmark fits](#where-truthmark-fits)
|
||||
- [Get started](#get-started)
|
||||
@@ -63,8 +92,9 @@ The point is not that prompts, memory, or specs are useless. The point is that n
|
||||
|
||||
Truthmark turns repository truth into an explicit workflow surface for agents:
|
||||
|
||||
- `TRUTHMARK.md` defines the branch-local workflow contract.
|
||||
- `.truthmark/config.yml` defines the committed hierarchy contract.
|
||||
- `docs/truthmark/areas.md` and delegated child route files map code areas to the docs that own them.
|
||||
- Truth Document generates or repairs canonical truth docs for existing implemented behavior when no code change is needed.
|
||||
- Truth Sync keeps mapped truth docs aligned with functional changes.
|
||||
- Truth Realize gives doc-first changes a bounded code-update path.
|
||||
- `truthmark check` validates the resulting truth artifacts.
|
||||
@@ -101,49 +131,68 @@ Review `.truthmark/config.yml` before `init`; it is the committed hierarchy cont
|
||||
|
||||
```text
|
||||
.truthmark/config.yml
|
||||
TRUTHMARK.md
|
||||
docs/truthmark/areas.md
|
||||
docs/truthmark/areas/repository.md
|
||||
docs/features/README.md
|
||||
docs/features/repository/README.md
|
||||
docs/features/repository/overview.md
|
||||
docs/templates/behavior-doc.md
|
||||
docs/truth/README.md
|
||||
docs/truth/repository/README.md
|
||||
docs/truth/repository/overview.md
|
||||
AGENTS.md
|
||||
CLAUDE.md
|
||||
.codex/skills/truthmark-structure/SKILL.md
|
||||
.codex/skills/truthmark-sync/SKILL.md
|
||||
.codex/skills/truthmark-realize/SKILL.md
|
||||
.codex/skills/truthmark-check/SKILL.md
|
||||
.opencode/skills/truthmark-structure/SKILL.md
|
||||
.opencode/skills/truthmark-sync/SKILL.md
|
||||
.opencode/skills/truthmark-realize/SKILL.md
|
||||
.opencode/skills/truthmark-check/SKILL.md
|
||||
GEMINI.md
|
||||
```
|
||||
|
||||
If you enable additional platforms in `.truthmark/config.yml`, Truthmark refreshes the corresponding managed surfaces on the next `init`.
|
||||
Supported platforms are `codex`, `opencode`, `claude-code`, `github-copilot`, and `gemini-cli`. The default config includes all of them; remove platforms you do not use from `.truthmark/config.yml` before rerunning `truthmark init`.
|
||||
|
||||
The default scaffold keeps feature `README.md` files as indexes and starts current behavior truth in bounded leaf docs such as `docs/features/repository/overview.md`.
|
||||
The default scaffold keeps truth `README.md` files as indexes and starts current behavior truth in bounded leaf docs such as `docs/truth/repository/overview.md`.
|
||||
|
||||
Existing repositories usually need one cleanup pass after `init`: run the installed Truth Structure workflow when the generated `repository` route is too broad, ownership spans multiple products or services, or route files still point at placeholder docs. Truth Structure splits broad routing, creates or repairs starter canonical truth docs, and gives Truth Sync precise destinations before functional-code work begins. Codex users can invoke it with `/truthmark-structure` or `$truthmark-structure`; OpenCode-style hosts can invoke `/skill truthmark-structure`.
|
||||
Existing repositories usually need one cleanup pass after `init`: run the installed Truth Structure workflow when the generated `repository` route is too broad, ownership spans multiple products or services, or route files still point at placeholder docs. Truth Structure splits broad routing, creates or repairs starter canonical truth docs, and gives Truth Sync precise destinations before functional-code work begins. Codex, Claude Code, and supported Copilot IDEs can invoke it with `/truthmark-structure`; OpenCode-style hosts can invoke `/skill truthmark-structure`.
|
||||
|
||||
```text
|
||||
/truthmark-structure split the broad repository area into auth, billing, and notifications
|
||||
```
|
||||
|
||||
## How it runs
|
||||
|
||||
Truthmark does not specify which subagent should run Truth Sync. The acting agent and host environment decide whether to delegate or run the workflow inline.
|
||||
Truthmark is strongest on the default path, not as a pile of manual commands. The acting agent and host environment decide whether to delegate or run the installed workflow inline.
|
||||
|
||||
### Existing behavior without docs
|
||||
|
||||
Use this when implementation already exists but the canonical truth docs are missing or weak:
|
||||
|
||||
```text
|
||||
user identifies an implemented behavior or API endpoint
|
||||
user explicitly invokes Truth Document
|
||||
agent reads implementation, tests, routing, and existing docs
|
||||
agent writes truth docs and routing only
|
||||
review the truth-doc diff
|
||||
```
|
||||
|
||||
Truth Document is manual and implementation-first: code is inspected as evidence, truth docs are created or repaired, and functional code must not be changed. Codex, Claude Code, and supported Copilot IDEs can invoke it with `/truthmark-document`. OpenCode-style hosts can invoke `/skill truthmark-document`.
|
||||
|
||||
```text
|
||||
/truthmark-document document the implemented session timeout behavior under docs/truth/authentication
|
||||
```
|
||||
|
||||
### Normal code changes
|
||||
|
||||
Most users should not need to invoke Truth Sync directly. The normal path is:
|
||||
Most users should not need to invoke Truth Sync directly. The important behavior is that the installed agent workflow treats Truth Sync as a finish-time guard when functional code changed. The normal path is:
|
||||
|
||||
```text
|
||||
agent changes functional code
|
||||
run relevant tests
|
||||
Truth Sync triggers before the agent finishes
|
||||
the installed Truth Sync workflow runs before the agent finishes
|
||||
review the truth-doc diff if one was produced
|
||||
commit or hand off the work
|
||||
```
|
||||
|
||||
Truth Sync is code-first: code leads, truth docs follow, and Truth Sync must not rewrite functional code. Its main job is to act as an automatic finish-time safeguard when functional code changed. Direct invocation is mainly for troubleshooting, forcing an early sync before handoff, or running the workflow intentionally.
|
||||
Truth Sync is code-first: code leads, truth docs follow, and Truth Sync must not rewrite functional code. Its main job is to run through the installed agent workflow as a finish-time guard when functional code changed. Direct invocation is mainly for troubleshooting, forcing an early sync before handoff, or running the workflow intentionally.
|
||||
|
||||
Codex users can invoke it with `/truthmark-sync` or `$truthmark-sync`. OpenCode-style hosts can invoke `/skill truthmark-sync`.
|
||||
Codex, Claude Code, and supported Copilot IDEs can invoke it with `/truthmark-sync`. OpenCode-style hosts can invoke `/skill truthmark-sync`.
|
||||
|
||||
```text
|
||||
/truthmark-sync sync the repository truth now before handoff
|
||||
```
|
||||
|
||||
### Doc-first changes
|
||||
|
||||
@@ -160,40 +209,51 @@ commit or hand off the work
|
||||
|
||||
Truth Realize is manual and doc-first: truth docs lead, code follows, and the agent must not edit the truth docs it is realizing.
|
||||
|
||||
Codex users can invoke it with `/truthmark-realize` or `$truthmark-realize`. OpenCode-style hosts can invoke `/skill truthmark-realize`.
|
||||
Codex, Claude Code, and supported Copilot IDEs can invoke it with `/truthmark-realize`. OpenCode-style hosts can invoke `/skill truthmark-realize`.
|
||||
|
||||
```text
|
||||
/truthmark-realize realize docs/truth/authentication/session-timeout.md into code
|
||||
```
|
||||
|
||||
## What it installs
|
||||
|
||||
Truthmark keeps the durable workflow surface small:
|
||||
Truthmark keeps the durable workflow surface small and repository-native. After `truthmark init`, the repo itself carries the routing, rules, and installed workflow surfaces, so teams are not relying only on one operator's local setup.
|
||||
|
||||
- `.truthmark/config.yml` for machine-readable configuration
|
||||
- `TRUTHMARK.md` for the branch-local workflow contract
|
||||
- `.truthmark/config.yml` for the machine-readable committed hierarchy contract
|
||||
- `docs/truthmark/areas.md` for the root route index
|
||||
- `docs/truthmark/areas/**/*.md` for delegated child route files
|
||||
- managed instruction blocks for configured platforms such as `AGENTS.md`, `CLAUDE.md`, Cursor rules, Copilot instructions, and `GEMINI.md`
|
||||
- Codex and OpenCode skills for Truth Structure, Truth Sync, Truth Realize, and Truth Check
|
||||
- `docs/templates/behavior-doc.md` plus the other kind-specific templates under `docs/templates/` for the editable truth-doc standards used by generated workflows
|
||||
- managed instruction blocks for configured platforms such as `AGENTS.md`, `CLAUDE.md`, Copilot instructions, and `GEMINI.md`
|
||||
- host-native skills, prompts, or commands for Truth Structure, Truth Document, Truth Sync, Truth Realize, and Truth Check
|
||||
|
||||
The installed workflow surfaces are the runtime:
|
||||
|
||||
- Truth Structure creates or repairs area routing and starter truth docs.
|
||||
- Truth Document creates or repairs truth docs for existing implemented behavior.
|
||||
- Truth Sync keeps mapped truth docs aligned with functional changes.
|
||||
- Truth Realize updates code to match truth docs.
|
||||
- Truth Check audits repository truth health.
|
||||
|
||||
Feature `README.md` files are indexes. Truth Sync is expected to read and update bounded leaf docs for current behavior.
|
||||
Truth `README.md` files are indexes. Truth Sync is expected to read and update bounded leaf docs for current behavior. Generated workflow surfaces preserve repository-rule authority while treating implementation code and canonical truth docs as evidence for current behavior.
|
||||
|
||||
Generated surfaces are managed by Truthmark, include a version marker, and may be refreshed by `truthmark init`.
|
||||
|
||||
## Commands
|
||||
|
||||
Truthmark V1 intentionally keeps the CLI small. In downstream repositories, `truthmark config` creates the committed hierarchy contract, `truthmark init` installs and refreshes workflow surfaces from that reviewed config, and `truthmark check` validates truth artifacts for manual audits, CI, or troubleshooting.
|
||||
Truthmark V1 keeps the CLI focused because the ongoing workflow is meant to live in the installed agent surfaces, not in a long list of daily manual commands. In downstream repositories, `truthmark config` creates the committed hierarchy contract, `truthmark init` installs and refreshes workflow surfaces from that reviewed config, `truthmark check` validates truth artifacts for manual audits, CI, or troubleshooting, and the repository-intelligence commands generate derived review artifacts when local tooling is available.
|
||||
|
||||
```bash
|
||||
truthmark config
|
||||
truthmark init
|
||||
truthmark check
|
||||
truthmark index
|
||||
truthmark impact --base main
|
||||
truthmark context --workflow truth-sync --base main
|
||||
truthmark config --json
|
||||
truthmark check --json
|
||||
truthmark index --json
|
||||
truthmark impact --base main --json
|
||||
truthmark context --workflow truth-sync --base main --json
|
||||
```
|
||||
|
||||
`config` writes only `.truthmark/config.yml` unless `--stdout` is used.
|
||||
@@ -202,7 +262,19 @@ truthmark check --json
|
||||
|
||||
`check` validates configuration, authority, routing, decision-bearing docs, frontmatter, internal links, branch scope, and coverage diagnostics.
|
||||
|
||||
Truth Structure, Truth Sync, Truth Realize, and Truth Check are installed agent workflows, not top-level daily CLI commands.
|
||||
`index` builds RepoIndex and RouteMap JSON for the active checkout.
|
||||
|
||||
`impact --base <ref>` maps changed files to routed truth docs, owning routes, nearby tests, and public symbols.
|
||||
|
||||
`context --workflow <workflow> [--base <ref>]` generates a bounded ContextPack for Truth Sync, Truth Document, or Truth Realize. `--format markdown` renders a human-readable pack.
|
||||
|
||||
Truth Structure, Truth Document, Truth Sync, Truth Realize, and Truth Check are installed agent workflows, not top-level daily CLI commands.
|
||||
|
||||
They run through the configured agent host surfaces, for example Codex/Claude/Copilot `/truthmark-*`, OpenCode `/skill truthmark-*`, or Gemini `/truthmark:*`.
|
||||
|
||||
```text
|
||||
/truthmark-check audit routing and truth coverage before review
|
||||
```
|
||||
|
||||
## Why it exists
|
||||
|
||||
@@ -219,7 +291,7 @@ It assumes serious teams need:
|
||||
- truth that travels with the branch instead of living in hidden session state
|
||||
- workflows that still work when the package is not installed globally
|
||||
|
||||
Truthmark is not a memory server and it is not an MCP server. It is a repository practice packaged as a small CLI installer plus agent-native workflow surfaces.
|
||||
Truthmark is not a memory server and it is not an MCP server. It is a repository practice packaged as a small CLI installer plus agent-native workflow surfaces that turn AI workflow rules into repo infrastructure.
|
||||
|
||||
## Project status
|
||||
|
||||
@@ -228,10 +300,14 @@ V1 currently provides:
|
||||
- `truthmark config`
|
||||
- `truthmark init`
|
||||
- `truthmark check`
|
||||
- `truthmark index`
|
||||
- `truthmark impact`
|
||||
- `truthmark context`
|
||||
- managed `AGENTS.md` workflow instructions
|
||||
- generated Truth Structure, Truth Sync, Truth Realize, and Truth Check skill surfaces for configured agent hosts
|
||||
- generated Truth Structure, Truth Document, Truth Sync, Truth Realize, and Truth Check skill surfaces for configured agent hosts
|
||||
- branch-scope metadata
|
||||
- config, authority, routing, decision-structure, frontmatter, link, and polyglot coverage diagnostics
|
||||
- config, authority, routing, decision-structure, frontmatter, link, freshness, and polyglot coverage diagnostics
|
||||
- derived RepoIndex, RouteMap, ImpactSet, and ContextPack artifacts for faster local review when the CLI is available
|
||||
|
||||
## Documentation
|
||||
|
||||
@@ -239,10 +315,10 @@ The root README is for people evaluating and trying the package. Detailed functi
|
||||
|
||||
- [Docs index](docs/README.md)
|
||||
- [Architecture overview](docs/architecture/overview.md)
|
||||
- [API and CLI contracts](docs/features/contracts.md)
|
||||
- [Init and scaffold behavior](docs/features/init-and-scaffold.md)
|
||||
- [Check diagnostics](docs/features/check-diagnostics.md)
|
||||
- [Installed workflows](docs/features/installed-workflows.md)
|
||||
- [API and CLI contracts](docs/truth/contracts.md)
|
||||
- [Init and scaffold behavior](docs/truth/init-and-scaffold.md)
|
||||
- [Check diagnostics](docs/truth/check-diagnostics.md)
|
||||
- [Installed workflows](docs/truth/workflows/overview.md)
|
||||
- [Repository truth maintenance guide](docs/standards/maintaining-repository-truth.md)
|
||||
|
||||
Current behavior belongs in the canonical docs tree above.
|
||||
|
||||
+153
-61
@@ -1,31 +1,68 @@
|
||||
# Truthmark это слой истины для разработки ПО с ИИ.
|
||||
# Truthmark
|
||||
|
||||
**Truthmark устанавливает рабочие процессы истины репозитория для разработки ПО с ИИ.**
|
||||
|
||||
[English](README.md) | [Deutsch](README.de.md) | [中文](README.zh.md) | [Español](README.es.md) | Русский
|
||||
|
||||
ИИ-агенты для разработки уже неплохо пишут код. Но они все еще плохо восстанавливают намерения продукта, архитектурные границы и зоны ответственности в репозитории по устаревшей документации, разрозненным чатам и недолговечной памяти инструментов.
|
||||
Truthmark решает эту проблему: он превращает истину репозитория, локальную для ветки, в полноценную поверхность выполнения для агентов. Он устанавливает прямо в репозиторий Git-native слой истины с областью действия в пределах ветки, задает агентам явные границы маршрутизации и рабочих процессов и делает так, чтобы эта истина двигалась вместе с кодом, который действительно будет поставлен.
|
||||
Это не более удачная инженерия промптов. Это более управляемый способ использовать ИИ в настоящей кодовой базе: меньше повторных решений, меньше устаревшей документации, чище передача работы и сессии с ИИ, после которых остаются проверяемые инженерные записи, а не только следы в истории промптов или непрозрачном состоянии инструментов.
|
||||
Для команд, которые уже знают, что агенты умеют генерировать код, и теперь хотят, чтобы сам репозиторий оставался понятным, проверяемым и управляемым.
|
||||
<img src="docs/assets/truthmark-banner.png" alt="Баннер Truthmark" width="100%" />
|
||||
|
||||
## Что решает Truthmark
|
||||
ИИ-агенты уже быстро пишут код. Дорогая часть — удерживать истину репозитория в соответствии с тем, что реально изменилось.
|
||||
|
||||
Начать писать код с ИИ сейчас легко, но управлять этим дорого. Как только агенты начинают быстро писать код, истина репозитория становится поверхностью управления.
|
||||
Этот сбой проявляется предсказуемо: требования остаются в чатах, архитектурные решения принимаются заново, агенты трогают не те области, а ветки наследуют контекст, который ревьюеры не могут надежно проверить. Код может двигаться быстро, но репозиторию становится труднее доверять.
|
||||
Truthmark меняет рабочую модель:
|
||||
Truthmark добавляет в этот процесс финальную защиту на уровне рабочего процесса. Обычный путь прост:
|
||||
|
||||
- Истина, локальная для ветки, путешествует вместе с веткой, а не живет в приватном хранилище инструмента.
|
||||
- Git делает эту истину проверяемой, сравнимой в diff и доступной всей команде.
|
||||
- Документация следует за кодом, а не тихо превращается в вымысел.
|
||||
- Маршрутизация остается явной в `docs/truthmark/areas.md` и делегированных дочерних файлах маршрутов, чтобы агенты понимали, какая документация отвечает за какой код.
|
||||
- Активные продуктовые и архитектурные решения живут в канонических документах, которыми они управляют, а не в планировочных журналах с временными метками.
|
||||
- Local-first рабочие процессы не требуют демона, базы данных, удаленного сервиса или MCP-зависимости.
|
||||
- Модель работает в кодовых базах на JavaScript, TypeScript, Go, Python, C# и Java.
|
||||
- агент меняет функциональный код
|
||||
- запускаются релевантные тесты
|
||||
- установленный рабочий процесс Truth Sync обновляет связанные документы истины до завершения работы агента
|
||||
- если был создан diff документов истины, его проверяют
|
||||
|
||||
Для технических лидеров ценность в управлении без показухи: тесты, ревью кода и владение зонами ответственности по-прежнему делают основную работу; Truthmark делает контекст агента долговечным, проверяемым и ограниченным веткой.
|
||||
Большинство инструментов просит команды выработать привычку. Truthmark превращает эту привычку в инфраструктуру рабочего процесса репозитория.
|
||||
|
||||
Truthmark превращает ИИ-процесс в инфраструктуру репозитория, а не в персональный инструмент. Он устанавливает Git-native слой истины внутри репозитория, задает агентам явную маршрутизацию и ограниченные рабочие поверхности и сохраняет эту истину проверяемой в Git вместо того, чтобы разносить ее по истории промптов, устаревшей документации или приватному состоянию инструментов.
|
||||
|
||||
Это важно, потому что процесс живет вместе с веткой. После инициализации репозитория правила, маршрутизация и установленные рабочие поверхности путешествуют внутри репозитория, поэтому совместная работа и передача задач меньше зависят от локальной настройки одного человека.
|
||||
|
||||
Для команд, которые уже знают, что агенты умеют генерировать код, Truthmark решает следующую проблему: как сделать так, чтобы сам репозиторий оставался понятным, проверяемым и управляемым по мере роста ИИ-ассистированной разработки.
|
||||
|
||||
## Визуальный обзор
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td align="center" width="50%">
|
||||
<img src="docs/assets/truthmark-features.png" alt="Возможности Truthmark" width="100%" />
|
||||
<br><strong>Возможности</strong><br>
|
||||
Что устанавливает Truthmark и как устроена рабочая поверхность.
|
||||
</td>
|
||||
<td align="center" width="50%">
|
||||
<img src="docs/assets/truthmark-position.png" alt="Позиционирование Truthmark" width="100%" />
|
||||
<br><strong>Позиционирование</strong><br>
|
||||
Где Truthmark находится относительно промптов, памяти и spec-first процессов.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td align="center" colspan="2">
|
||||
<img src="docs/assets/truthmark-syncflow.png" alt="Поток sync в Truthmark" width="100%" />
|
||||
<br><strong>Поток sync</strong><br>
|
||||
Как Truth Sync закрывает обычные изменения кода перед передачей работы.
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
## Почему команды выбирают Truthmark
|
||||
|
||||
Truthmark не пытается сделать так, чтобы агенты звучали умнее. Он пытается сделать изменения в репозитории, выполненные с помощью ИИ, более надежными.
|
||||
|
||||
- Установленный Truth Sync после изменений кода превращает поддержку документации в защиту рабочего процесса, а не в командную привычку.
|
||||
- Истина, ограниченная веткой, движется вместе с кодом, поэтому ревьюеры могут проверять актуальную истину в обычных Git diff.
|
||||
- Рабочие поверхности, встроенные в репозиторий, упрощают внедрение и делают передачу работы устойчивее, чем одна лишь персональная настройка.
|
||||
- Явная маршрутизация в `docs/truthmark/areas.md` и делегированных дочерних файлах маршрутов дает агентам границы ответственности и более безопасные пути записи.
|
||||
- Local-first работа избавляет от зависимости на демон, базу данных, удаленный сервис или MCP.
|
||||
- Модель маршрутизации не зависит от языка и дает диагностику покрытия для распространенных поверхностей кода JavaScript, TypeScript, Go, Python, C# и Java.
|
||||
|
||||
Для технических лидеров ценность в управлении без дополнительной инфраструктуры: тесты, ревью кода и владение зонами ответственности по-прежнему делают основную работу; Truthmark делает контекст агента долговечным, проверяемым и ограниченным веткой.
|
||||
|
||||
## Где уместен Truthmark
|
||||
|
||||
Truthmark не пытается заменить все остальные инструменты для ИИ-процессов. Он занимает конкретный слой в стеке:
|
||||
Truthmark не является универсальным набором ИИ-инструментов для продуктивности. Он занимает конкретный слой в стеке: проверяемая истина репозитория, ограниченная веткой и выровненная с реализацией.
|
||||
|
||||
| Если вам нужно | Лучший выбор |
|
||||
| ------------------------------------------------------------------------------------------------ | ---------------------------------------------- |
|
||||
@@ -38,9 +75,9 @@ Truthmark не пытается заменить все остальные ин
|
||||
|
||||
## Содержание
|
||||
|
||||
- [Почему команды выбирают Truthmark](#почему-команды-выбирают-truthmark)
|
||||
- [Что решает Truthmark](#что-решает-truthmark)
|
||||
- [Где уместен Truthmark](#где-уместен-truthmark)
|
||||
- [Рабочая поверхность](#рабочая-поверхность)
|
||||
- [Начало работы](#начало-работы)
|
||||
- [Как он работает](#как-он-работает)
|
||||
- [Что он устанавливает](#что-он-устанавливает)
|
||||
@@ -51,12 +88,13 @@ Truthmark не пытается заменить все остальные ин
|
||||
- [Не-цели](#не-цели)
|
||||
- [Лицензия](#лицензия)
|
||||
|
||||
## Рабочая поверхность
|
||||
## Что решает Truthmark
|
||||
|
||||
Truthmark превращает истину репозитория в явную рабочую поверхность для агентов:
|
||||
|
||||
- `TRUTHMARK.md` определяет контракт рабочего процесса, локальный для ветки.
|
||||
- `.truthmark/config.yml` определяет зафиксированный контракт иерархии.
|
||||
- `docs/truthmark/areas.md` и делегированные дочерние файлы маршрутов сопоставляют области кода с документами, которые за них отвечают.
|
||||
- Truth Document создает или исправляет канонические документы истины для уже реализованного поведения, когда изменение кода не нужно.
|
||||
- Truth Sync поддерживает синхронизацию сопоставленных документов истины при функциональных изменениях.
|
||||
- Truth Realize дает изменениям, начинающимся с документации, ограниченный путь для обновления кода.
|
||||
- `truthmark check` валидирует получившиеся артефакты истины.
|
||||
@@ -92,96 +130,145 @@ node /path/to/truthmark/dist/main.js check
|
||||
|
||||
```text
|
||||
.truthmark/config.yml
|
||||
TRUTHMARK.md
|
||||
docs/truthmark/areas.md
|
||||
docs/truthmark/areas/repository.md
|
||||
docs/features/README.md
|
||||
docs/features/repository/README.md
|
||||
docs/features/repository/overview.md
|
||||
docs/templates/behavior-doc.md
|
||||
docs/truth/README.md
|
||||
docs/truth/repository/README.md
|
||||
docs/truth/repository/overview.md
|
||||
AGENTS.md
|
||||
CLAUDE.md
|
||||
.codex/skills/truthmark-structure/SKILL.md
|
||||
.codex/skills/truthmark-sync/SKILL.md
|
||||
.codex/skills/truthmark-realize/SKILL.md
|
||||
.codex/skills/truthmark-check/SKILL.md
|
||||
.opencode/skills/truthmark-structure/SKILL.md
|
||||
.opencode/skills/truthmark-sync/SKILL.md
|
||||
.opencode/skills/truthmark-realize/SKILL.md
|
||||
.opencode/skills/truthmark-check/SKILL.md
|
||||
GEMINI.md
|
||||
```
|
||||
|
||||
Если вы включите дополнительные платформы в `.truthmark/config.yml`, Truthmark обновит соответствующие управляемые поверхности при следующем `init`.
|
||||
Стандартная шаблонная структура использует `README.md` функциональных разделов как индексы и начинает описывать истину текущего поведения в ограниченных листовых документах, например `docs/features/repository/overview.md`.
|
||||
Поддерживаемые платформы: `codex`, `opencode`, `claude-code`, `github-copilot` и `gemini-cli`. Конфигурация по умолчанию включает их все; удалите из `.truthmark/config.yml` платформы, которыми не пользуетесь, перед повторным запуском `truthmark init`.
|
||||
Стандартная шаблонная структура использует truth-`README.md` как индексы и начинает описывать истину текущего поведения в ограниченных листовых документах, например `docs/truth/repository/overview.md`.
|
||||
|
||||
Существующим репозиториям обычно нужен один этап очистки после `init`: запустите установленный рабочий процесс Truth Structure, если созданный маршрут `repository` слишком широкий, владение охватывает несколько продуктов или сервисов, либо файлы маршрутов все еще указывают на документы-заглушки. Truth Structure разделяет широкие маршруты, создает или исправляет начальные канонические документы истины и дает Truth Sync точные цели до начала работы с функциональным кодом. Пользователи Codex могут вызвать его через `/truthmark-structure` или `$truthmark-structure`; хосты в стиле OpenCode могут использовать `/skill truthmark-structure`.
|
||||
Существующим репозиториям обычно нужен один этап очистки после `init`: запустите установленный рабочий процесс Truth Structure, если созданный маршрут `repository` слишком широкий, владение охватывает несколько продуктов или сервисов, либо файлы маршрутов все еще указывают на документы-заглушки. Truth Structure разделяет широкие маршруты, создает или исправляет начальные канонические документы истины и дает Truth Sync точные цели до начала работы с функциональным кодом. Codex, Claude Code и поддерживаемые IDE Copilot могут вызвать его через `/truthmark-structure`; хосты в стиле OpenCode могут использовать `/skill truthmark-structure`.
|
||||
|
||||
## Как он работает
|
||||
|
||||
Truthmark не задает, какой именно подагент должен запускать Truth Sync. Действующий агент и среда хоста сами решают, делегировать работу или выполнить процесс на месте.
|
||||
Большинству пользователей не нужно вызывать Truth Sync напрямую. Нормальный путь выглядит так:
|
||||
Сильная сторона Truthmark — путь по умолчанию, а не набор ручных команд. Действующий агент и среда хоста сами решают, делегировать работу или выполнить установленный процесс на месте.
|
||||
|
||||
### Существующее поведение без документации
|
||||
|
||||
Используйте это, когда реализация уже есть, но канонические документы истины отсутствуют или слабы:
|
||||
|
||||
```text
|
||||
пользователь определяет реализованное поведение или api-эндпоинт
|
||||
пользователь явно вызывает truth document
|
||||
агент читает реализацию, тесты, маршрутизацию и существующие docs
|
||||
агент пишет только truth docs и маршрутизацию
|
||||
проверить diff truth docs
|
||||
```
|
||||
|
||||
Truth Document — это ручной процесс с приоритетом реализации: код служит доказательством, документы истины создаются или исправляются, и функциональный код менять нельзя. Codex, Claude Code и поддерживаемые IDE Copilot могут вызывать его через `/truthmark-document`; хосты в стиле OpenCode могут использовать `/skill truthmark-document`.
|
||||
|
||||
```text
|
||||
/truthmark-document документирует реализованное поведение session timeout в docs/truth/authentication
|
||||
```
|
||||
|
||||
### Обычные изменения кода
|
||||
|
||||
Большинству пользователей не нужно напрямую вызывать Truth Sync. Главное, что установленный агентский процесс рассматривает Truth Sync как финальную защиту, когда менялся функциональный код. Нормальный путь выглядит так:
|
||||
|
||||
```text
|
||||
агент изменяет функциональный код
|
||||
запускаются релевантные тесты
|
||||
Truth Sync срабатывает до завершения работы агента
|
||||
если был создан diff документов истины, он проверяется
|
||||
установленный truth sync workflow запускается до завершения агента
|
||||
если был создан diff truth docs, он проверяется
|
||||
работа коммитится или передается дальше
|
||||
```
|
||||
|
||||
Truth Sync работает по принципу code-first: сначала идет код, затем документы истины, и Truth Sync не должен переписывать функциональный код. Его основная задача быть автоматической финальной проверкой, когда менялся функциональный код. Прямой вызов нужен в основном для отладки, ранней синхронизации перед передачей работы или намеренного запуска рабочего процесса.
|
||||
Пользователи Codex могут вызывать его через `/truthmark-sync` или `$truthmark-sync`. Хосты в стиле OpenCode могут использовать `/skill truthmark-sync`.
|
||||
Truth Sync работает по принципу code-first: сначала идет код, затем документы истины, и Truth Sync не должен переписывать функциональный код. Его основная задача - выполняться через установленный агентский процесс как финальная защита, когда менялся функциональный код. Прямой вызов нужен в основном для отладки, ранней синхронизации перед передачей работы или намеренного запуска рабочего процесса.
|
||||
|
||||
Codex, Claude Code и поддерживаемые IDE Copilot могут вызывать его через `/truthmark-sync`. Хосты в стиле OpenCode могут использовать `/skill truthmark-sync`.
|
||||
|
||||
```text
|
||||
/truthmark-sync синхронизируй истину репозитория прямо сейчас перед передачей
|
||||
```
|
||||
|
||||
### Doc-first изменения
|
||||
|
||||
Используйте этот путь, когда продуктовое или архитектурное решение начинается в документации:
|
||||
|
||||
```text
|
||||
пользователь редактирует документы истины
|
||||
пользователь явно вызывает Truth Realize
|
||||
агент читает документы истины и связанный код
|
||||
пользователь редактирует truth docs
|
||||
пользователь явно вызывает truth realize
|
||||
агент читает truth docs и связанный код
|
||||
агент обновляет только код
|
||||
запускаются релевантные тесты
|
||||
работа коммитится или передается дальше
|
||||
```
|
||||
|
||||
Truth Realize это ручной процесс по принципу doc-first: документы истины идут первыми, код следует за ними, и агент не должен редактировать документы истины, которые он реализует.
|
||||
Пользователи Codex могут вызывать его через `/truthmark-realize` или `$truthmark-realize`. Хосты в стиле OpenCode могут использовать `/skill truthmark-realize`.
|
||||
Truth Realize — это ручной doc-first процесс: документы истины идут первыми, код следует за ними, и агент не должен редактировать документы истины, которые он реализует.
|
||||
|
||||
Codex, Claude Code и поддерживаемые IDE Copilot могут вызывать его через `/truthmark-realize`. Хосты в стиле OpenCode могут использовать `/skill truthmark-realize`.
|
||||
|
||||
```text
|
||||
/truthmark-realize реализуй docs/truth/authentication/session-timeout.md в код
|
||||
```
|
||||
|
||||
## Что он устанавливает
|
||||
|
||||
Truthmark намеренно держит постоянную рабочую поверхность маленькой:
|
||||
Truthmark держит постоянную рабочую поверхность маленькой и встроенной в репозиторий. После `truthmark init` сам репозиторий несет маршрутизацию, правила и установленные рабочие поверхности, поэтому команда не зависит только от локальной настройки одного человека.
|
||||
|
||||
- `.truthmark/config.yml` для машиночитаемой конфигурации
|
||||
- `TRUTHMARK.md` для контракта рабочего процесса, локального для ветки
|
||||
- `.truthmark/config.yml` для машиночитаемого зафиксированного контракта иерархии
|
||||
- `docs/truthmark/areas.md` для корневого индекса маршрутов
|
||||
- `docs/truthmark/areas/**/*.md` для делегированных дочерних файлов маршрутов
|
||||
- управляемые блоки инструкций для настроенных платформ, таких как `AGENTS.md`, `CLAUDE.md`, правила Cursor, инструкции Copilot и `GEMINI.md`
|
||||
- Codex- и OpenCode skills для Truth Structure, Truth Sync, Truth Realize и Truth Check
|
||||
- `docs/templates/behavior-doc.md` и другие шаблоны по видам под `docs/templates/` для редактируемых стандартов truth docs, используемых сгенерированными рабочими процессами
|
||||
- управляемые блоки инструкций для настроенных платформ, таких как `AGENTS.md`, `CLAUDE.md`, инструкции Copilot и `GEMINI.md`
|
||||
- нативные для хоста skills, prompts или commands для Truth Structure, Truth Document, Truth Sync, Truth Realize и Truth Check
|
||||
|
||||
Установленные рабочие поверхности и есть среда выполнения:
|
||||
|
||||
- Truth Structure создает или исправляет маршрутизацию областей и стартовые документы истины.
|
||||
- Truth Document создает или исправляет документы истины для уже реализованного поведения.
|
||||
- Truth Sync поддерживает синхронизацию сопоставленных документов истины с функциональными изменениями.
|
||||
- Truth Realize обновляет код так, чтобы он соответствовал документам истины.
|
||||
- Truth Check аудитирует здоровье истины репозитория.
|
||||
|
||||
`README.md` функциональных разделов это индексы. Ожидается, что Truth Sync будет читать и обновлять ограниченные листовые документы для текущего поведения.
|
||||
`README.md` функциональных разделов это индексы. Ожидается, что Truth Sync будет читать и обновлять ограниченные листовые документы для текущего поведения. Сгенерированные рабочие поверхности сохраняют приоритет правил репозитория, рассматривая код реализации и канонические документы истины как свидетельства текущего поведения.
|
||||
|
||||
Сгенерированные поверхности управляются Truthmark, содержат маркер версии и могут обновляться через `truthmark init`.
|
||||
|
||||
## Команды
|
||||
|
||||
Truthmark V1 намеренно держит CLI небольшим. В нижестоящих репозиториях `truthmark config` создает зафиксированный контракт иерархии, `truthmark init` устанавливает и обновляет рабочие поверхности на основе этой проверенной конфигурации, а `truthmark check` валидирует артефакты истины для ручных аудитов, CI или отладки.
|
||||
Truthmark V1 намеренно держит CLI небольшим, потому что постоянный рабочий процесс должен жить в установленных агентских поверхностях, а не в длинном списке ежедневных ручных команд. В нижестоящих репозиториях `truthmark config` создает зафиксированный контракт иерархии, `truthmark init` устанавливает и обновляет рабочие поверхности на основе этой проверенной конфигурации, `truthmark check` валидирует артефакты истины для ручных аудитов, CI или отладки, а команды репозиторной аналитики создают производные артефакты для проверки, когда доступны локальные инструменты.
|
||||
|
||||
```bash
|
||||
truthmark config
|
||||
truthmark init
|
||||
truthmark check
|
||||
truthmark index
|
||||
truthmark impact --base main
|
||||
truthmark context --workflow truth-sync --base main
|
||||
truthmark config --json
|
||||
truthmark check --json
|
||||
truthmark index --json
|
||||
truthmark impact --base main --json
|
||||
truthmark context --workflow truth-sync --base main --json
|
||||
```
|
||||
|
||||
`config` пишет только `.truthmark/config.yml`, если не используется `--stdout`.
|
||||
|
||||
`init` требует `.truthmark/config.yml`, а затем устанавливает или обновляет локальные файлы рабочих процессов.
|
||||
|
||||
`check` валидирует конфигурацию, полномочия, маршрутизацию, документы с решениями, frontmatter, внутренние ссылки, область действия ветки и диагностику покрытия.
|
||||
Truth Structure, Truth Sync, Truth Realize и Truth Check это установленные агентские рабочие процессы, а не повседневные CLI-команды верхнего уровня.
|
||||
|
||||
`index` строит JSON RepoIndex и RouteMap для активного checkout.
|
||||
|
||||
`impact --base <ref>` сопоставляет измененные файлы с routed truth docs, owning routes, nearby tests и public symbols.
|
||||
|
||||
`context --workflow <workflow> [--base <ref>]` генерирует ограниченный ContextPack для Truth Sync, Truth Document или Truth Realize. `--format markdown` рендерит его в читаемый человеком вид.
|
||||
|
||||
Truth Structure, Truth Document, Truth Sync, Truth Realize и Truth Check это установленные агентские рабочие процессы, а не повседневные CLI-команды верхнего уровня.
|
||||
|
||||
Они запускаются через настроенные поверхности хоста агента, например Codex/Claude/Copilot `/truthmark-*`, OpenCode `/skill truthmark-*` или Gemini `/truthmark:*`.
|
||||
|
||||
```text
|
||||
/truthmark-check проверь маршрутизацию и покрытие truth перед review
|
||||
```
|
||||
|
||||
## Зачем он существует
|
||||
|
||||
@@ -199,16 +286,21 @@ Truth Structure, Truth Sync, Truth Realize и Truth Check это установ
|
||||
|
||||
## Статус проекта
|
||||
|
||||
Truthmark не является сервером памяти и не является MCP-сервером. Это репозиторная практика, упакованная как небольшой CLI-установщик и родные для агентов рабочие поверхности.
|
||||
Truthmark не является сервером памяти и не является MCP-сервером. Это репозиторная практика, упакованная как небольшой CLI-установщик и родные для агентов рабочие поверхности, которые превращают правила ИИ-процесса в инфраструктуру репозитория.
|
||||
|
||||
V1 сейчас предоставляет:
|
||||
|
||||
- `truthmark config`
|
||||
- `truthmark init`
|
||||
- `truthmark check`
|
||||
- `truthmark index`
|
||||
- `truthmark impact`
|
||||
- `truthmark context`
|
||||
- управляемые инструкции рабочих процессов в `AGENTS.md`
|
||||
- сгенерированные skill-поверхности Truth Structure, Truth Sync, Truth Realize и Truth Check для настроенных агентских хостов
|
||||
- сгенерированные skill-поверхности Truth Structure, Truth Document, Truth Sync, Truth Realize и Truth Check для настроенных агентских хостов
|
||||
- метаданные области ветки
|
||||
- диагностика конфигурации, полномочий, маршрутизации, структуры решений, frontmatter, ссылок и полиглотного покрытия
|
||||
- производные артефакты RepoIndex, RouteMap, ImpactSet и ContextPack для более быстрой локальной проверки, когда CLI доступен
|
||||
|
||||
## Документация
|
||||
|
||||
@@ -216,10 +308,10 @@ V1 сейчас предоставляет:
|
||||
|
||||
- [Индекс документации](docs/README.md)
|
||||
- [Обзор архитектуры](docs/architecture/overview.md)
|
||||
- [Контракты API и CLI](docs/features/contracts.md)
|
||||
- [Поведение init и scaffold](docs/features/init-and-scaffold.md)
|
||||
- [Диагностика check](docs/features/check-diagnostics.md)
|
||||
- [Установленные workflow](docs/features/installed-workflows.md)
|
||||
- [Контракты API и CLI](docs/truth/contracts.md)
|
||||
- [Поведение init и scaffold](docs/truth/init-and-scaffold.md)
|
||||
- [Диагностика check](docs/truth/check-diagnostics.md)
|
||||
- [Установленные workflow](docs/truth/workflows/overview.md)
|
||||
- [Руководство по поддержанию истины репозитория](docs/standards/maintaining-repository-truth.md)
|
||||
|
||||
Текущее поведение должно жить в каноническом дереве документации выше.
|
||||
|
||||
+151
-59
@@ -1,31 +1,68 @@
|
||||
# Truthmark 是 AI 软件开发的事实层。
|
||||
# Truthmark
|
||||
|
||||
**Truthmark 为 AI 软件开发安装仓库事实工作流。**
|
||||
|
||||
[English](README.md) | [Deutsch](README.de.md) | 中文 | [Español](README.es.md) | [Русский](README.ru.md)
|
||||
|
||||
AI 编码代理已经很会写代码了。它们仍然不擅长从过时文档、零散聊天和短暂的工具记忆中，可靠还原产品意图、架构边界和仓库归属。
|
||||
Truthmark 通过把分支内的仓库事实变成代理运行时的一等载体来解决这个问题。它把一个 Git 原生、按分支生效的事实层直接安装到仓库里，为代理明确路由和工作流边界，并让这些事实随真正交付的代码一起移动。
|
||||
这不是更好的提示词工程，而是在真实代码库中更可治理地使用 AI 的方式：少一些重复决策，少一些陈旧文档，交接更清楚，AI 编码会话也会留下可审查的工程记录，而不是消失在提示历史或不透明的工具状态里。
|
||||
它面向这样的团队：你们已经知道代理能生成代码，现在需要仓库本身继续保持清晰、可审查、可治理。
|
||||
<img src="docs/assets/truthmark-banner.png" alt="Truthmark 横幅" width="100%" />
|
||||
|
||||
## Truthmark 解决什么问题
|
||||
AI 编码代理已经能很快写代码了。真正昂贵的是让仓库事实和实际变更保持一致。
|
||||
|
||||
AI 编码现在上手很容易，治理却很昂贵。一旦代理能快速写代码，仓库事实就会成为控制面。
|
||||
这种失效模式很常见：需求留在聊天里，架构决策反复重做，代理改到了错误的区域，分支继承了审查者无法可靠检查的上下文。代码也许推进得很快，但仓库会变得越来越难以信任。
|
||||
Truthmark 改变的是工作模型：
|
||||
Truthmark 在这个流程里加入了一个收尾阶段的工作流保护。正常路径很简单：
|
||||
|
||||
- 分支内事实随分支一起流转，而不是藏在私有工具存储里。
|
||||
- Git 让这些事实可以被审查、对比，并在团队内共享。
|
||||
- 文档跟着代码走，而不是悄悄变成虚构。
|
||||
- 路由明确保存在 `docs/truthmark/areas.md` 和委托的子路由文件中，让代理知道哪些文档负责哪些代码。
|
||||
- 当前有效的产品和架构决策保存在它们所治理的规范文档中，而不是带时间戳的规划日志里。
|
||||
- 本地优先的工作流不需要守护进程、数据库、远程服务或 MCP 依赖。
|
||||
- 这个模型适用于 JavaScript、TypeScript、Go、Python、C# 和 Java 代码库。
|
||||
- 代理修改功能代码
|
||||
- 运行相关测试
|
||||
- 代理结束前，已安装的 Truth Sync 工作流更新已映射的事实文档
|
||||
- 如果产生了事实文档 diff，就审查它
|
||||
|
||||
对技术负责人来说，它的价值是没有表演成分的治理：测试、代码审查和所有权仍然承担真正的工作；Truthmark 让代理上下文变得持久、可检查，并且限定在当前分支内。
|
||||
大多数工具要求团队养成一种习惯。Truthmark 把这个习惯变成仓库工作流基础设施。
|
||||
|
||||
Truthmark 把 AI 工作流变成仓库基础设施，而不是个人工具配置。它把一个 Git 原生、按分支生效的事实层安装到仓库里，为代理提供明确的路由和有边界的工作流载体，并让这些事实继续以 Git diff 的形式可审查，而不是散落在提示历史、陈旧文档或私有工具状态里。
|
||||
|
||||
这之所以重要，是因为工作流跟着分支一起存在。仓库一旦初始化，规则、路由和已安装的工作流载体就会随仓库一起移动，协作和交接也就不再过度依赖某个人的本地配置。
|
||||
|
||||
对于已经知道代理能生成代码的团队，Truthmark 解决的是下一个问题：当 AI 辅助开发规模化时，怎样让仓库本身继续保持清晰、可审查、可治理。
|
||||
|
||||
## 可视化概览
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td align="center" width="50%">
|
||||
<img src="docs/assets/truthmark-features.png" alt="Truthmark 功能" width="100%" />
|
||||
<br><strong>功能</strong><br>
|
||||
Truthmark 安装了什么，以及工作流载体如何拆分。
|
||||
</td>
|
||||
<td align="center" width="50%">
|
||||
<img src="docs/assets/truthmark-position.png" alt="Truthmark 定位" width="100%" />
|
||||
<br><strong>定位</strong><br>
|
||||
Truthmark 相对提示词、记忆和规格工作流所处的位置。
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td align="center" colspan="2">
|
||||
<img src="docs/assets/truthmark-syncflow.png" alt="Truthmark 同步流程" width="100%" />
|
||||
<br><strong>同步流程</strong><br>
|
||||
Truth Sync 如何在交接前收束普通代码变更。
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
## 为什么团队会采用它
|
||||
|
||||
Truthmark 不是为了让代理显得更聪明，而是为了让 AI 辅助的仓库变更更值得信任。
|
||||
|
||||
- 代码变更后的已安装 Truth Sync 工作流，把文档维护从团队习惯变成工作流保护。
|
||||
- 按分支生效的事实会跟着代码一起走，所以审查者可以在普通 Git diff 里检查当前事实。
|
||||
- 仓库原生的工作流载体让推广更轻、交接更稳，不再只依赖个人本地配置。
|
||||
- `docs/truthmark/areas.md` 和委托的子路由文件里的显式路由，为代理提供更清晰的所有权边界和更安全的写入路径。
|
||||
- 本地优先的运行方式避免了守护进程、数据库、远程服务或 MCP 依赖。
|
||||
- 路由模型与语言无关，并为常见的 JavaScript、TypeScript、Go、Python、C# 和 Java 代码表面提供覆盖率诊断。
|
||||
|
||||
对技术负责人来说，它的价值是没有额外基础设施负担的治理：测试、代码审查和所有权仍然承担真正的工作；Truthmark 让代理上下文变得持久、可检查，并且限定在当前分支内。
|
||||
|
||||
## Truthmark 适合放在哪里
|
||||
|
||||
Truthmark 并不想取代所有其他 AI 工作流工具。它位于工具栈中的一个特定层级：
|
||||
Truthmark 不是一套通用 AI 生产力套件。它占据的是工具栈里的一个特定层级：随实现保持一致、按分支生效、可审查的仓库事实。
|
||||
|
||||
| 如果你需要 | 最合适的选择 |
|
||||
| -------------------------------------------- | ------------------------------ |
|
||||
@@ -38,9 +75,9 @@ Truthmark 并不想取代所有其他 AI 工作流工具。它位于工具栈中
|
||||
|
||||
## 目录
|
||||
|
||||
- [为什么团队会采用它](#为什么团队会采用它)
|
||||
- [Truthmark 解决什么问题](#truthmark-解决什么问题)
|
||||
- [Truthmark 适合放在哪里](#truthmark-适合放在哪里)
|
||||
- [工作流载体](#工作流载体)
|
||||
- [快速开始](#快速开始)
|
||||
- [它如何运行](#它如何运行)
|
||||
- [它会安装什么](#它会安装什么)
|
||||
@@ -51,12 +88,13 @@ Truthmark 并不想取代所有其他 AI 工作流工具。它位于工具栈中
|
||||
- [非目标](#非目标)
|
||||
- [许可证](#许可证)
|
||||
|
||||
## 工作流载体
|
||||
## Truthmark 解决什么问题
|
||||
|
||||
Truthmark 把仓库事实变成代理可见的显式工作流载体：
|
||||
|
||||
- `TRUTHMARK.md` 定义分支内工作流契约。
|
||||
- `.truthmark/config.yml` 定义已提交的层级契约。
|
||||
- `docs/truthmark/areas.md` 和委托的子路由文件把代码区域映射到负责它们的文档。
|
||||
- Truth Document 在无需修改代码时，为已实现行为生成或修复规范事实文档。
|
||||
- Truth Sync 在功能性变更发生时，让已映射的事实文档保持同步。
|
||||
- Truth Realize 为文档优先的变更提供有边界的代码更新路径。
|
||||
- `truthmark check` 验证最终形成的事实产物。
|
||||
@@ -92,96 +130,145 @@ node /path/to/truthmark/dist/main.js check
|
||||
|
||||
```text
|
||||
.truthmark/config.yml
|
||||
TRUTHMARK.md
|
||||
docs/truthmark/areas.md
|
||||
docs/truthmark/areas/repository.md
|
||||
docs/features/README.md
|
||||
docs/features/repository/README.md
|
||||
docs/features/repository/overview.md
|
||||
docs/templates/behavior-doc.md
|
||||
docs/truth/README.md
|
||||
docs/truth/repository/README.md
|
||||
docs/truth/repository/overview.md
|
||||
AGENTS.md
|
||||
CLAUDE.md
|
||||
.codex/skills/truthmark-structure/SKILL.md
|
||||
.codex/skills/truthmark-sync/SKILL.md
|
||||
.codex/skills/truthmark-realize/SKILL.md
|
||||
.codex/skills/truthmark-check/SKILL.md
|
||||
.opencode/skills/truthmark-structure/SKILL.md
|
||||
.opencode/skills/truthmark-sync/SKILL.md
|
||||
.opencode/skills/truthmark-realize/SKILL.md
|
||||
.opencode/skills/truthmark-check/SKILL.md
|
||||
GEMINI.md
|
||||
```
|
||||
|
||||
如果你在 `.truthmark/config.yml` 中启用更多平台，Truthmark 会在下一次 `init` 时刷新对应的受管载体。
|
||||
默认脚手架把功能 `README.md` 作为索引，并把当前行为事实放在有边界的叶子文档中，例如 `docs/features/repository/overview.md`。
|
||||
支持的平台是 `codex`、`opencode`、`claude-code`、`github-copilot` 和 `gemini-cli`。默认配置包含全部平台；请先从 `.truthmark/config.yml` 中移除不使用的平台，再重新运行 `truthmark init`。
|
||||
默认脚手架把 truth `README.md` 作为索引，并把当前行为事实放在有边界的叶子文档中，例如 `docs/truth/repository/overview.md`。
|
||||
|
||||
现有仓库通常需要在 `init` 之后做一次清理：当生成的 `repository` 路由过宽、所有权跨越多个产品或服务，或路由文件仍指向占位文档时，运行已安装的 Truth Structure 工作流。Truth Structure 会拆分过宽的路由，创建或修复初始的规范事实文档，并在功能代码工作开始前为 Truth Sync 提供精确目标。Codex 用户可以用 `/truthmark-structure` 或 `$truthmark-structure` 调用它；OpenCode 风格的宿主可以用 `/skill truthmark-structure` 调用它。
|
||||
现有仓库通常需要在 `init` 之后做一次清理：当生成的 `repository` 路由过宽、所有权跨越多个产品或服务，或路由文件仍指向占位文档时，运行已安装的 Truth Structure 工作流。Truth Structure 会拆分过宽的路由，创建或修复初始的规范事实文档，并在功能代码工作开始前为 Truth Sync 提供精确目标。Codex、Claude Code 和支持的 Copilot IDE 可以用 `/truthmark-structure` 调用它；OpenCode 风格的宿主可以用 `/skill truthmark-structure` 调用它。
|
||||
|
||||
## 它如何运行
|
||||
|
||||
Truthmark 不规定应该由哪个子代理运行 Truth Sync。由实际执行的代理和宿主环境决定是委托执行，还是内联运行工作流。
|
||||
多数用户不需要直接调用 Truth Sync。正常路径是：
|
||||
Truthmark 最强的地方是默认路径，而不是一堆手动命令。由实际执行的代理和宿主环境决定是委托执行，还是内联运行已安装的工作流。
|
||||
|
||||
### 已实现但无文档的行为
|
||||
|
||||
当实现已经存在，但规范事实文档缺失或较弱时，使用这个流程：
|
||||
|
||||
```text
|
||||
用户识别一个已实现的行为或 API 端点
|
||||
用户显式调用 Truth Document
|
||||
代理读取实现、测试、路由和现有文档
|
||||
代理只写 truth docs 和路由
|
||||
审查 truth-doc diff
|
||||
```
|
||||
|
||||
Truth Document 是手动、implementation-first 的流程：代码作为证据，事实文档被创建或修复，且不能修改功能代码。Codex、Claude Code 和支持的 Copilot IDE 可以用 `/truthmark-document` 调用它；OpenCode 风格的宿主可以用 `/skill truthmark-document` 调用它。
|
||||
|
||||
```text
|
||||
/truthmark-document 在 docs/truth/authentication 下记录已实现的会话超时行为
|
||||
```
|
||||
|
||||
### 常规代码变更
|
||||
|
||||
多数用户不需要直接调用 Truth Sync。关键在于，只要功能代码发生变化，已安装的代理工作流就会把 Truth Sync 当作收尾保护。正常路径是：
|
||||
|
||||
```text
|
||||
代理修改功能代码
|
||||
运行相关测试
|
||||
代理结束前触发 Truth Sync
|
||||
如果生成了事实文档 diff，就审查它
|
||||
已安装的 Truth Sync 工作流在代理结束前运行
|
||||
如果生成了 truth-doc diff，就审查它
|
||||
提交或交接工作
|
||||
```
|
||||
|
||||
Truth Sync 是 code-first：代码在前，事实文档跟随，且 Truth Sync 不能重写功能代码。它的主要职责是在功能代码发生变化时，作为收尾阶段的自动安全检查。直接调用主要用于排查问题、交接前提前同步，或有意运行这套工作流。
|
||||
Codex 用户可以用 `/truthmark-sync` 或 `$truthmark-sync` 调用它。OpenCode 风格的宿主可以用 `/skill truthmark-sync` 调用它。
|
||||
Truth Sync 是 code-first：代码在前，事实文档跟随，且 Truth Sync 不能重写功能代码。它的主要职责是在功能代码发生变化时，通过已安装的代理工作流充当收尾保护。直接调用主要用于排查问题、交接前提前同步，或有意运行这套工作流。
|
||||
|
||||
Codex、Claude Code 和支持的 Copilot IDE 可以用 `/truthmark-sync` 调用它。OpenCode 风格的宿主可以用 `/skill truthmark-sync` 调用它。
|
||||
|
||||
```text
|
||||
/truthmark-sync 现在同步仓库 truth，然后再交接
|
||||
```
|
||||
|
||||
### 文档优先变更
|
||||
|
||||
当产品或架构决策从文档开始时，使用这个流程：
|
||||
|
||||
```text
|
||||
用户编辑事实文档
|
||||
用户编辑 truth docs
|
||||
用户显式调用 Truth Realize
|
||||
代理读取事实文档和相关代码
|
||||
代理读取 truth docs 和相关代码
|
||||
代理只更新代码
|
||||
运行相关测试
|
||||
提交或交接工作
|
||||
```
|
||||
|
||||
Truth Realize 是手动、文档优先的流程：事实文档在前，代码跟随，代理不能编辑它正在实现的事实文档。
|
||||
Codex 用户可以用 `/truthmark-realize` 或 `$truthmark-realize` 调用它。OpenCode 风格的宿主可以用 `/skill truthmark-realize` 调用它。
|
||||
|
||||
Codex、Claude Code 和支持的 Copilot IDE 可以用 `/truthmark-realize` 调用它。OpenCode 风格的宿主可以用 `/skill truthmark-realize` 调用它。
|
||||
|
||||
```text
|
||||
/truthmark-realize 将 docs/truth/authentication/session-timeout.md 实现为代码
|
||||
```
|
||||
|
||||
## 它会安装什么
|
||||
|
||||
Truthmark 把持久化的工作流载体保持得很小：
|
||||
Truthmark 把持久化的工作流载体保持得很小，而且是仓库原生的。运行 `truthmark init` 之后，仓库本身就携带路由、规则和已安装的工作流载体，因此团队不再只依赖某个人的本地配置。
|
||||
|
||||
- `.truthmark/config.yml`，用于机器可读配置
|
||||
- `TRUTHMARK.md`，用于分支内工作流契约
|
||||
- `.truthmark/config.yml`，用于机器可读的已提交层级契约
|
||||
- `docs/truthmark/areas.md`，用于根路由索引
|
||||
- `docs/truthmark/areas/**/*.md`，用于委托的子路由文件
|
||||
- 面向已配置平台的受管说明块，例如 `AGENTS.md`、`CLAUDE.md`、Cursor 规则、Copilot 指令和 `GEMINI.md`
|
||||
- 面向 Truth Structure、Truth Sync、Truth Realize 和 Truth Check 的 Codex 技能与仓库本地技能
|
||||
- `docs/templates/behavior-doc.md` 以及 `docs/templates/` 下其他按类型划分的模板，用作生成工作流采用的可编辑 truth doc 标准
|
||||
- 面向已配置平台的受管说明块，例如 `AGENTS.md`、`CLAUDE.md`、Copilot 指令和 `GEMINI.md`
|
||||
- 面向 Truth Structure、Truth Document、Truth Sync、Truth Realize 和 Truth Check 的宿主原生技能、提示或命令
|
||||
|
||||
安装后的工作流载体就是运行时：
|
||||
|
||||
- Truth Structure 创建或修复区域路由和起始事实文档。
|
||||
- Truth Document 为已实现行为创建或修复事实文档。
|
||||
- Truth Sync 在功能性变更发生时，让已映射的事实文档保持同步。
|
||||
- Truth Realize 更新代码，使其符合事实文档。
|
||||
- Truth Check 审计仓库事实的健康状况。
|
||||
|
||||
功能 `README.md` 是索引。Truth Sync 预期读取并更新用于描述当前行为的有边界叶子文档。
|
||||
功能 `README.md` 是索引。Truth Sync 预期读取并更新用于描述当前行为的有边界叶子文档。生成的工作流载体会保留仓库规则的权威性，同时把实现代码和规范事实文档当作当前行为的证据。
|
||||
|
||||
生成的载体由 Truthmark 管理，包含版本标记，并可通过 `truthmark init` 刷新。
|
||||
|
||||
## 命令
|
||||
|
||||
Truthmark V1 有意保持 CLI 很小。在下游仓库中，`truthmark config` 创建已提交的层级契约，`truthmark init` 根据这份已审查的配置安装和刷新工作流载体，`truthmark check` 则为人工审计、CI 或问题排查验证事实产物。
|
||||
Truthmark V1 有意保持 CLI 很小，因为持续运行的工作流应该活在已安装的代理载体里，而不是一长串日常手动命令里。在下游仓库中，`truthmark config` 创建已提交的层级契约，`truthmark init` 根据这份已审查的配置安装和刷新工作流载体，`truthmark check` 则为人工审计、CI 或问题排查验证事实产物，而仓库情报命令会在有本地工具时生成派生审查产物。
|
||||
|
||||
```bash
|
||||
truthmark config
|
||||
truthmark init
|
||||
truthmark check
|
||||
truthmark index
|
||||
truthmark impact --base main
|
||||
truthmark context --workflow truth-sync --base main
|
||||
truthmark config --json
|
||||
truthmark check --json
|
||||
truthmark index --json
|
||||
truthmark impact --base main --json
|
||||
truthmark context --workflow truth-sync --base main --json
|
||||
```
|
||||
|
||||
`config` 只写入 `.truthmark/config.yml`，除非使用 `--stdout`。
|
||||
|
||||
`init` 需要 `.truthmark/config.yml`，然后安装或刷新本地工作流文件。
|
||||
|
||||
`check` 验证配置、权限边界、路由、承载决策的文档、frontmatter、内部链接、分支范围和覆盖率诊断。
|
||||
Truth Structure、Truth Sync、Truth Realize 和 Truth Check 是已安装的代理工作流，不是日常使用的顶层 CLI 命令。
|
||||
|
||||
`index` 为当前 checkout 构建 RepoIndex 和 RouteMap JSON。
|
||||
|
||||
`impact --base <ref>` 会把变更文件映射到已路由的 truth docs、所属路由、附近测试和 public symbols。
|
||||
|
||||
`context --workflow <workflow> [--base <ref>]` 会为 Truth Sync、Truth Document 或 Truth Realize 生成一个受限的 ContextPack。`--format markdown` 会把它渲染成可读文本。
|
||||
|
||||
Truth Structure、Truth Document、Truth Sync、Truth Realize 和 Truth Check 是已安装的代理工作流，不是日常使用的顶层 CLI 命令。
|
||||
|
||||
它们通过已配置的代理宿主表面运行，例如 Codex/Claude/Copilot 的 `/truthmark-*`、OpenCode 的 `/skill truthmark-*`，或者 Gemini 的 `/truthmark:*`。
|
||||
|
||||
```text
|
||||
/truthmark-check 在 review 前审计路由和 truth 覆盖
|
||||
```
|
||||
|
||||
## 它为什么存在
|
||||
|
||||
@@ -199,16 +286,21 @@ Truth Structure、Truth Sync、Truth Realize 和 Truth Check 是已安装的代
|
||||
|
||||
## 项目状态
|
||||
|
||||
Truthmark 不是记忆服务器，也不是 MCP 服务器。它是一套仓库实践，被打包成一个小型 CLI 安装器和代理原生的工作流载体。
|
||||
Truthmark 不是记忆服务器，也不是 MCP 服务器。它是一套仓库实践，被打包成一个小型 CLI 安装器和代理原生的工作流载体，用来把 AI 工作流规则变成仓库基础设施。
|
||||
|
||||
V1 目前提供：
|
||||
|
||||
- `truthmark config`
|
||||
- `truthmark init`
|
||||
- `truthmark check`
|
||||
- `truthmark index`
|
||||
- `truthmark impact`
|
||||
- `truthmark context`
|
||||
- 受管的 `AGENTS.md` 工作流说明
|
||||
- 为已配置代理宿主生成的 Truth Structure、Truth Sync、Truth Realize 和 Truth Check 技能载体
|
||||
- 为已配置代理宿主生成的 Truth Structure、Truth Document、Truth Sync、Truth Realize 和 Truth Check 技能载体
|
||||
- 分支范围元数据
|
||||
- 配置、权限边界、路由、决策结构、frontmatter、链接和多语言覆盖率诊断
|
||||
- RepoIndex、RouteMap、ImpactSet 和 ContextPack 派生产物，可在 CLI 可用时加快本地检查
|
||||
|
||||
## 文档
|
||||
|
||||
@@ -216,10 +308,10 @@ V1 目前提供：
|
||||
|
||||
- [文档索引](docs/README.md)
|
||||
- [架构概览](docs/architecture/overview.md)
|
||||
- [API 和 CLI 契约](docs/features/contracts.md)
|
||||
- [Init 和脚手架行为](docs/features/init-and-scaffold.md)
|
||||
- [Check 诊断](docs/features/check-diagnostics.md)
|
||||
- [已安装工作流](docs/features/installed-workflows.md)
|
||||
- [API 和 CLI 契约](docs/truth/contracts.md)
|
||||
- [Init 和脚手架行为](docs/truth/init-and-scaffold.md)
|
||||
- [Check 诊断](docs/truth/check-diagnostics.md)
|
||||
- [已安装工作流](docs/truth/workflows/overview.md)
|
||||
- [仓库事实维护指南](docs/standards/maintaining-repository-truth.md)
|
||||
|
||||
当前行为应放在上面的规范文档树中。
|
||||
|
||||
@@ -1,31 +0,0 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: truthmark
|
||||
last_reviewed: 2026-05-08
|
||||
source_of_truth:
|
||||
- README.md
|
||||
- docs/ai/repo-rules.md
|
||||
- docs/truthmark/areas.md
|
||||
---
|
||||
|
||||
# Truthmark
|
||||
|
||||
Markdown in the current checkout is authoritative for this branch.
|
||||
|
||||
Installed workflow surfaces include a Truthmark 1.2.1 version marker. After upgrading Truthmark, rerun `truthmark init` and review generated workflow diffs.
|
||||
|
||||
Truth Sync runs automatically before finishing when functional code changes exist, and updates truth docs.
|
||||
|
||||
Truth Sync can also be invoked explicitly through installed truthmark-sync skill surfaces.
|
||||
|
||||
Truth Structure is manual and updates area routing plus starter truth docs.
|
||||
|
||||
Truth Check is manual and audits repository truth health.
|
||||
|
||||
Installed skills and the managed AGENTS block are the workflow runtime. Agents inspect the checkout directly and may use `truthmark check` only as optional validation.
|
||||
|
||||
Truth Realize is manual and updates code to match truth docs.
|
||||
|
||||
Truth Sync may create or extend mapped truth docs when implementation would otherwise remain undocumented.
|
||||
|
||||
Truth Realize never edits truth docs.
|
||||
@@ -0,0 +1,15 @@
|
||||
# Short Change Title
|
||||
|
||||
Version action: none|patch|minor|major
|
||||
|
||||
## PR Summary
|
||||
|
||||
- Concise maintainer-facing summary.
|
||||
|
||||
## Release Note
|
||||
|
||||
- None; internal-only change.
|
||||
|
||||
## Verification
|
||||
|
||||
- Not run yet.
|
||||
@@ -0,0 +1,16 @@
|
||||
# Internal Change Notes Flow
|
||||
|
||||
Version action: none
|
||||
|
||||
## PR Summary
|
||||
|
||||
- Added an internal `changes/` note flow so agents can produce reusable PR and release source text.
|
||||
- Linked package version decisions to change notes without making the flow a user-facing product feature.
|
||||
|
||||
## Release Note
|
||||
|
||||
- None; internal-only repository maintenance standard.
|
||||
|
||||
## Verification
|
||||
|
||||
- `npm run dev -- check`
|
||||
@@ -0,0 +1,16 @@
|
||||
# Repository Intelligence CLI
|
||||
|
||||
Version action: minor
|
||||
|
||||
## PR Summary
|
||||
|
||||
- Added public `truthmark index`, `truthmark impact`, and `truthmark context` commands with RepoIndex, RouteMap, ImpactSet, and ContextPack JSON contracts.
|
||||
- Added freshness diagnostics and workflow-facing repository-intelligence guidance while preserving direct checkout inspection as the source of authority.
|
||||
|
||||
## Release Note
|
||||
|
||||
- Added repository-intelligence commands for derived index, impact, and context-pack output: `truthmark index`, `truthmark impact --base <ref>`, and `truthmark context --workflow <workflow>`.
|
||||
|
||||
## Verification
|
||||
|
||||
- `npm test -- tests/context-pack/build.test.ts tests/repo-index/build.test.ts tests/impact/build.test.ts tests/cli/index-impact-context.test.ts`
|
||||
+35
-26
@@ -1,32 +1,29 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: index
|
||||
last_reviewed: 2026-05-09
|
||||
last_reviewed: 2026-05-15
|
||||
source_of_truth:
|
||||
- docs/ai/repo-rules.md
|
||||
- ../TRUTHMARK.md
|
||||
- ../.truthmark/config.yml
|
||||
---
|
||||
|
||||
# Truthmark Docs Index
|
||||
|
||||
## Purpose
|
||||
|
||||
`docs/` is Truthmark's canonical repository documentation tree. It keeps repository-wide agent rules, reusable standards, current architecture, and current feature behavior separate from onboarding copy and historical planning notes.
|
||||
`docs/` is Truthmark's canonical repository documentation tree. It keeps repository-wide agent rules, reusable standards, current architecture, and current truth docs separate from onboarding copy and historical planning notes.
|
||||
|
||||
`AGENTS.md` is the agent entry point, but it delegates repository-wide rules to [docs/ai/repo-rules.md](ai/repo-rules.md). [README.md](../README.md) remains the human onboarding and product entry point. [TRUTHMARK.md](../TRUTHMARK.md) remains the top-level branch-local workflow contract.
|
||||
`AGENTS.md` is the agent entry point, but it delegates repository-wide rules to [docs/ai/repo-rules.md](ai/repo-rules.md). [README.md](../README.md) remains the human onboarding and product entry point. `.truthmark/config.yml` defines the committed hierarchy contract.
|
||||
|
||||
## Authority Order
|
||||
## Scope
|
||||
|
||||
When documents conflict, authority descends in this order:
|
||||
This doc defines the current structure, navigation map, and maintenance expectations of Truthmark's canonical `docs/` tree.
|
||||
|
||||
1. [docs/ai/repo-rules.md](ai/repo-rules.md) for repository-wide agent rules and completion policy
|
||||
2. [TRUTHMARK.md](../TRUTHMARK.md) for the top-level truth-workflow contract
|
||||
3. [docs/truthmark/areas.md](truthmark/areas.md) and `docs/truthmark/areas/**/*.md` for code-to-doc routing metadata
|
||||
4. `docs/standards/**/*.md` for reusable repository standards
|
||||
5. `docs/architecture/**/*.md` for current structure and module boundaries
|
||||
6. `docs/features/**/*.md` for current product behavior and contracts
|
||||
## Authority Source
|
||||
|
||||
[README.md](../README.md) may help with onboarding and positioning, but it must not override current-state docs.
|
||||
Repository-wide conflict order and completion policy live in [docs/ai/repo-rules.md](ai/repo-rules.md). Use this index for navigation and document-class guidance; it does not restate the full authority hierarchy.
|
||||
|
||||
[README.md](../README.md) may help with onboarding and positioning, but it must not override current-state docs or repository-wide agent rules.
|
||||
|
||||
## Audience Split
|
||||
|
||||
@@ -36,8 +33,9 @@ When documents conflict, authority descends in this order:
|
||||
- `docs/truthmark/` for routing metadata
|
||||
- `docs/standards/` for reusable constraints and completion rules
|
||||
- `docs/architecture/` for current system structure
|
||||
- `docs/features/` for current behavior and invariants
|
||||
- `docs/features/contracts.md` for stable contracts the CLI exposes
|
||||
- `docs/truth/` for current behavior and invariants
|
||||
- `docs/templates/` for editable scaffold templates used to create new docs
|
||||
- `docs/truth/contracts.md` for stable contracts the CLI exposes
|
||||
|
||||
### Human-centric docs
|
||||
|
||||
@@ -51,7 +49,8 @@ When documents conflict, authority descends in this order:
|
||||
| `docs/truthmark/` | routing | both | Truth-routing metadata such as `areas.md` and `areas/**/*.md` |
|
||||
| `docs/standards/` | standard | agent | Reusable constraints, verification rules, completion gates |
|
||||
| `docs/architecture/` | architecture | agent | Current structure and module boundaries |
|
||||
| `docs/features/` | feature | agent | Current behavior for init, check, contracts, and installed workflows |
|
||||
| `docs/truth/` | truth | agent | Current behavior for init, check, contracts, and installed workflows |
|
||||
| `docs/templates/` | template | both | Editable templates for scaffolded docs; templates are not Truth Sync targets |
|
||||
|
||||
## Frontmatter Policy
|
||||
|
||||
@@ -66,11 +65,13 @@ Canonical docs should include frontmatter and keep these fields current:
|
||||
|
||||
- When repository-wide agent policy changes, update [docs/ai/repo-rules.md](ai/repo-rules.md).
|
||||
- When code-to-doc routing changes, update [docs/truthmark/areas.md](truthmark/areas.md) in the same change.
|
||||
- When `truthmark init` or scaffolded files change, update the relevant feature or architecture doc, not only [README.md](../README.md).
|
||||
- When `truthmark check` changes what it validates or how it reports diagnostics, update both the current feature doc and the contract doc.
|
||||
- When package versions or release/version policy change, apply [docs/standards/versioning.md](standards/versioning.md) before accepting the version.
|
||||
- When PR or release source text is needed, write a `changes/` note using [docs/standards/change-notes.md](standards/change-notes.md).
|
||||
- When `truthmark init` or scaffolded files change, update the relevant truth or architecture doc, not only [README.md](../README.md).
|
||||
- When `truthmark check` changes what it validates or how it reports diagnostics, update both the current truth doc and the contract doc.
|
||||
- When major product, onboarding, install, command, positioning, or workflow behavior changes, review the root [README.md](../README.md) and update it if the human entry point would otherwise be stale.
|
||||
- Keep planning or proposal material outside the canonical current-state docs until it becomes implemented truth.
|
||||
- When current behavior changes for architecture, contracts, or features, update the owning canonical doc's `Product Decisions` and `Rationale` sections in the same change.
|
||||
- When current behavior changes for architecture, contracts, or truth docs, update the owning canonical doc's `Product Decisions` and `Rationale` sections in the same change.
|
||||
- Do not keep parallel documentation trees for the same subject.
|
||||
|
||||
## Important Truthmark-Specific Caveat
|
||||
@@ -82,21 +83,29 @@ New repositories should run `truthmark config` before `truthmark init` so teams
|
||||
### For humans
|
||||
|
||||
1. [README.md](../README.md)
|
||||
2. [TRUTHMARK.md](../TRUTHMARK.md)
|
||||
2. [.truthmark/config.yml](../.truthmark/config.yml)
|
||||
3. [docs/ai/repo-rules.md](ai/repo-rules.md)
|
||||
4. [docs/architecture/overview.md](architecture/overview.md)
|
||||
5. the relevant feature or standard doc for the area being changed
|
||||
5. the relevant truth or standard doc for the area being changed
|
||||
|
||||
### For agents
|
||||
|
||||
1. [docs/ai/repo-rules.md](ai/repo-rules.md)
|
||||
2. [docs/ai/agent-onboarding.md](ai/agent-onboarding.md)
|
||||
3. [docs/truthmark/areas.md](truthmark/areas.md)
|
||||
4. [docs/architecture/module-map.md](architecture/module-map.md)
|
||||
5. the relevant standard and feature docs for the task
|
||||
2. [docs/ai/agent-onboarding.md](ai/agent-onboarding.md), when routing is unclear or cross-area
|
||||
3. [docs/truthmark/areas.md](truthmark/areas.md), when mapping code to canonical truth
|
||||
4. [docs/architecture/module-map.md](architecture/module-map.md), when changing module boundaries
|
||||
5. the relevant standard and truth docs for the task
|
||||
|
||||
Use [docs/features/routing-examples.md](features/routing-examples.md) when designing areas for larger API, frontend, infrastructure, or monorepo repositories.
|
||||
Use [docs/truth/routing-examples.md](truth/routing-examples.md) when designing areas for larger API, frontend, infrastructure, or monorepo repositories.
|
||||
|
||||
## Maintenance Principle
|
||||
|
||||
The canonical tree should stay small, explicit, and current. Historical notes are useful for traceability, but current behavior belongs in the nearest maintained document class, not in old plans or chat summaries.
|
||||
|
||||
## Product Decisions
|
||||
|
||||
- Decision (2026-05-15): The docs index owns navigation and document-class guidance for the canonical tree, while [docs/ai/repo-rules.md](ai/repo-rules.md) owns repository-wide authority order and completion policy.
|
||||
|
||||
## Rationale
|
||||
|
||||
Keeping the docs index focused on navigation avoids loading duplicated authority prose while still giving agents and maintainers one stable place to resolve where current truth should live before they edit deeper canonical docs.
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: agent-guide
|
||||
last_reviewed: 2026-05-06
|
||||
last_reviewed: 2026-05-13
|
||||
source_of_truth:
|
||||
- repo-rules.md
|
||||
- ../README.md
|
||||
@@ -28,25 +28,41 @@ Read:
|
||||
|
||||
1. [docs/architecture/overview.md](../architecture/overview.md)
|
||||
2. [docs/architecture/module-map.md](../architecture/module-map.md)
|
||||
3. [docs/features/init-and-scaffold.md](../features/init-and-scaffold.md)
|
||||
4. [docs/features/contracts.md](../features/contracts.md)
|
||||
3. [docs/truth/init-and-scaffold.md](../truth/init-and-scaffold.md)
|
||||
4. [docs/truth/contracts.md](../truth/contracts.md)
|
||||
|
||||
### Diagnostics, routing, or containment checks
|
||||
|
||||
Read:
|
||||
|
||||
1. [docs/architecture/module-map.md](../architecture/module-map.md)
|
||||
2. [docs/features/check-diagnostics.md](../features/check-diagnostics.md)
|
||||
2. [docs/truth/check-diagnostics.md](../truth/check-diagnostics.md)
|
||||
3. [docs/standards/documentation-governance.md](../standards/documentation-governance.md)
|
||||
4. [docs/features/contracts.md](../features/contracts.md)
|
||||
4. [docs/truth/contracts.md](../truth/contracts.md)
|
||||
|
||||
### Installed workflow, prompt, or reporting changes
|
||||
|
||||
Read:
|
||||
|
||||
1. [TRUTHMARK.md](../../TRUTHMARK.md)
|
||||
2. [docs/features/installed-workflows.md](../features/installed-workflows.md)
|
||||
1. [.truthmark/config.yml](../../.truthmark/config.yml)
|
||||
2. [docs/truth/workflows/overview.md](../truth/workflows/overview.md) and the relevant workflow leaf doc under `docs/truth/workflows/`
|
||||
3. [docs/standards/maintaining-repository-truth.md](../standards/maintaining-repository-truth.md)
|
||||
4. [docs/ai/agent-skills-workflow-review.md](agent-skills-workflow-review.md)
|
||||
|
||||
### Package version changes
|
||||
|
||||
Read:
|
||||
|
||||
1. [docs/standards/versioning.md](../standards/versioning.md)
|
||||
2. [docs/standards/change-notes.md](../standards/change-notes.md)
|
||||
3. [docs/standards/testing-and-verification.md](../standards/testing-and-verification.md)
|
||||
|
||||
### PR or release text
|
||||
|
||||
Read:
|
||||
|
||||
1. [docs/standards/change-notes.md](../standards/change-notes.md)
|
||||
2. [docs/standards/versioning.md](../standards/versioning.md), only when package version changes are in scope
|
||||
|
||||
### Documentation structure or policy changes
|
||||
|
||||
@@ -61,8 +77,10 @@ Read:
|
||||
Do:
|
||||
|
||||
- treat [docs/ai/repo-rules.md](repo-rules.md) as the primary authority for repository-wide rules
|
||||
- route code changes to the nearest maintained architecture, contract, and feature docs
|
||||
- route code changes to the nearest maintained architecture, contract, and truth docs
|
||||
- update [docs/truthmark/areas.md](../truthmark/areas.md) when canonical routing changes
|
||||
- apply [docs/standards/versioning.md](../standards/versioning.md) before changing or accepting a package version
|
||||
- write `changes/` notes from [docs/standards/change-notes.md](../standards/change-notes.md) when PR or release text is needed
|
||||
- preserve the generated Truthmark block in [AGENTS.md](../../AGENTS.md) unless the template behavior itself is changing
|
||||
- keep non-canonical planning notes separate from current-state docs
|
||||
|
||||
|
||||
@@ -0,0 +1,124 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: agent-guide
|
||||
last_reviewed: 2026-05-15
|
||||
source_of_truth:
|
||||
- repo-rules.md
|
||||
- ../truth/workflows/overview.md
|
||||
- ../truth/workflows/shared-gates.md
|
||||
- ../../src/agents/workflow-manifest.ts
|
||||
- ../../.codex/skills/truthmark-sync/SKILL.md
|
||||
- ../../.codex/skills/truthmark-structure/SKILL.md
|
||||
- ../../.codex/skills/truthmark-document/SKILL.md
|
||||
- ../../.codex/skills/truthmark-realize/SKILL.md
|
||||
- ../../.codex/skills/truthmark-check/SKILL.md
|
||||
- https://developers.openai.com/codex/skills
|
||||
- https://developers.openai.com/blog/eval-skills
|
||||
- https://developers.openai.com/blog/skills-shell-tips
|
||||
- https://developers.openai.com/blog/skills-agents-sdk
|
||||
- https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
|
||||
- https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf
|
||||
- https://code.claude.com/docs/en/slash-commands
|
||||
- https://agentskills.io/specification
|
||||
- https://research.perplexity.ai/articles/designing-refining-and-maintaining-agent-skills-at-perplexity
|
||||
---
|
||||
|
||||
This note summarizes external skill-authoring guidance reviewed on 2026-05-15 and applies it to Truthmark's installed project workflows. It is a reference for future workflow-surface changes, not a replacement for [workflow overview](../truth/workflows/overview.md) and the bounded workflow truth docs under `docs/truth/workflows/`.
|
||||
|
||||
## External Links Reviewed
|
||||
|
||||
All external links in `source_of_truth` resolved on 2026-05-15. The previous Anthropic Claude Code slash-command URL redirects to `https://code.claude.com/docs/en/slash-commands`; use the canonical redirected URL in this doc.
|
||||
|
||||
The Perplexity review adds a stricter standard than this doc previously stated: description metadata is routing logic, not a compact summary of the workflow. Expected outputs and success criteria belong in the body, report contract, or eval rubric.
|
||||
|
||||
## Skill Design Standard
|
||||
|
||||
Agent skills are context packages, not human manuals. Every skill is a tax paid by every session at the metadata layer and by every loaded conversation at the body layer. Add or grow a skill only when representative agents fail, behave inconsistently, or need durable project-specific context that the base model would not reliably infer.
|
||||
|
||||
Use progressive disclosure:
|
||||
|
||||
- metadata: `name` and `description` decide whether the skill loads
|
||||
- body: the short core procedure, boundaries, gotchas, and report shape
|
||||
- bundled files: scripts, references, assets, or config loaded only when needed
|
||||
|
||||
Descriptions are the hardest line. They should be short routing triggers, ideally 50 words or fewer, written as "Use when..." or "Load when..." with user intent, symptoms, and adjacent-workflow exclusions. They must not summarize the workflow steps, duplicate the body, or promise outputs.
|
||||
|
||||
Skill bodies should skip obvious mechanics the model already knows. Keep opinionated boundaries, gotchas, failure modes, negative examples, and high-value judgment rules. Move heavy, rare, or mutually exclusive material into explicitly named reference files only when each supported host can expose and load those files reliably.
|
||||
|
||||
Use scripts only for deterministic repeated mechanics the agent would otherwise reinvent. Leave interpretation, comparison, ownership decisions, and reporting to the model unless a deterministic checker can enforce them better than prose.
|
||||
|
||||
## Evaluation Standard
|
||||
|
||||
Reliable skills need evals before or alongside skill changes, not only syntax checks. For workflow-surface changes, maintain three classes of cases:
|
||||
|
||||
- positive routing: the workflow loads when its real trigger appears
|
||||
- negative routing: the workflow stays unloaded for nearby but wrong tasks
|
||||
- forbidden adjacency: the workflow does not steal requests from a sibling workflow
|
||||
|
||||
Useful eval suites cover loading precision/recall, required file reads, forbidden loads, progressive reference reads, end-to-end task completion, and cross-host behavior where hosts differ. Deterministic tests can prove rendered metadata, required routing cues, report headings, write-boundary text, and stale-surface diagnostics. Prompt-style agent evals are smoke checks and examples, not proof of universal routing correctness.
|
||||
|
||||
Maintenance should be append-mostly. Add gotchas when agents fail, tighten descriptions only with routing evals, and re-check nearby workflows when any description changes. A changed description can break workflows that were not edited.
|
||||
|
||||
Security posture matters because skills can contain instructions, scripts, assets, dependencies, and network instructions. Treat installed skills as executable agent runtime: inspect bundled files, scripts, dependency behavior, and any network instruction before trusting them.
|
||||
|
||||
## Truthmark Workflow Inventory
|
||||
|
||||
Truthmark currently installs five workflows across host-specific surfaces:
|
||||
|
||||
| Workflow | Main purpose | Codex implicit policy |
|
||||
| --- | --- | --- |
|
||||
| `truthmark-sync` | Finish-time code-to-truth synchronization after functional code changes | `allow_implicit_invocation: true` |
|
||||
| `truthmark-structure` | Design or repair truth routing topology | `allow_implicit_invocation: false` |
|
||||
| `truthmark-document` | Document existing implemented behavior without code changes | `allow_implicit_invocation: false` |
|
||||
| `truthmark-realize` | Realize truth docs into functional code | `allow_implicit_invocation: false` |
|
||||
| `truthmark-check` | Audit repository truth health | `allow_implicit_invocation: false` |
|
||||
|
||||
Generated runtime surfaces include `.codex/skills/`, `.claude/skills/`, `.opencode/skills/`, `.github/prompts/`, `.gemini/commands/truthmark/`, and compact managed instruction blocks in files such as `AGENTS.md`.
|
||||
|
||||
Current strengths:
|
||||
|
||||
- The workflow split is coherent: Structure owns topology, Document owns implemented behavior without code changes, Sync owns code-first finish-time alignment, Realize owns doc-first code changes, and Check owns audit.
|
||||
- Write boundaries are unusually clear. The skills repeatedly state which docs, routing files, or functional code may be changed.
|
||||
- The runtime is agent-native. Skills tell agents to inspect the checkout directly and treat the CLI as optional validation rather than a required orchestration bridge.
|
||||
- The managed instruction block is compact while detailed procedures live in explicit workflow surfaces, preserving ordinary task context.
|
||||
- Codex metadata correctly makes only Sync implicitly invocable. Manual workflows remain explicit in Codex, reducing accidental Structure, Document, Realize, or Check runs.
|
||||
- Generated-surface tests cover parseable frontmatter, required phrases, report headings, host paths, version markers, and stale-surface diagnostics.
|
||||
|
||||
## Current Findings
|
||||
|
||||
1. Medium: workflow evals should test routing, not just rendered text.
|
||||
Existing deterministic tests prove surfaces contain required words. Add positive, negative, and forbidden-adjacency cases for each workflow description before changing metadata. A useful first suite can run against generated descriptions without invoking a live model.
|
||||
|
||||
2. Medium: body growth must stay progressive.
|
||||
Repeated hierarchy, decision-truth, ownership, evidence, and preservation gates are defensible because generated host surfaces must stand alone. If bodies grow substantially, split shared guidance into generated references only after every supported host reliably exposes those references and tests prove agents read them when needed.
|
||||
|
||||
3. Low: external links should stay canonical and dated.
|
||||
Link review should update redirects, add review dates, and keep volatile external guidance in this reference doc rather than embedded directly in runtime workflow bodies.
|
||||
|
||||
Resolved:
|
||||
|
||||
- Resolved 2026-05-13: `truthmark-document` metadata now names Truth Sync, Truth Check, and Truth Structure as workflows that can hand off missing implemented-behavior documentation.
|
||||
- Resolved 2026-05-13: `truthmark-sync` frontmatter and Codex metadata now include skip cases for documentation-only changes, formatting-only changes, behavior-preserving renames, missing Truthmark config, and no functional code changes.
|
||||
- Resolved 2026-05-15: external source links were reviewed, the Claude Code slash-command link was canonicalized, and the Perplexity skill-maintenance standard was incorporated.
|
||||
- Resolved 2026-05-15: workflow frontmatter descriptions now include adjacent-workflow exclusions without summarizing the full workflow body.
|
||||
- Resolved 2026-05-15: workflow metadata and routing-eval expectations now live in a typed manifest consumed by generated surfaces and deterministic tests.
|
||||
|
||||
## Routing Eval Matrix
|
||||
|
||||
| Workflow | Positive trigger examples | Negative trigger examples | Forbidden adjacency | Key success checks |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| Sync | "I changed session code; finish and sync truth" | docs-only edit, formatting-only edit, no functional code diff | must not handle doc-first implementation or manual topology design | reads changed code and routing, updates only truth docs or routing, reports skipped or blocked correctly |
|
||||
| Structure | "split broad repository routing into auth and billing" | "document current auth behavior" | must not implement code or patch mixed-owner docs as shape repair | repairs route topology before docs, creates bounded starter docs, preserves authored content and decisions/rationale |
|
||||
| Document | "document existing order submission behavior" | "implement the behavior in this truth doc" | must not handle functional-code changes that require Sync | reads code and tests, writes docs/routing only, does not edit functional code |
|
||||
| Realize | "realize docs/truth/auth/session-timeout.md into code" | "sync docs after my code change" | must not edit truth docs or routing | reads truth docs first, blocks on stale/mixed-owner source truth, edits functional code only, runs relevant tests |
|
||||
| Check | "audit truth health before review" | "run lint and tests" | must not replace ordinary verification or finish-time Sync | reports issues and suggested fixes, optionally runs `truthmark check`, does not silently rewrite unrelated files |
|
||||
|
||||
## Maintenance Rules
|
||||
|
||||
- Add deterministic description-quality tests that require positive, negative, and forbidden-adjacency routing cues in every generated `SKILL.md` description.
|
||||
- Keep generated workflow descriptions, Codex metadata, routing examples, gate lists, write boundaries, and report-section expectations in the typed workflow manifest.
|
||||
- Treat prompt-style agent evals, if added, as smoke checks and examples rather than proof of universal routing correctness.
|
||||
- Tighten `truthmark-check` descriptions before adding more workflows.
|
||||
- Keep generated skill bodies below the point where common guidance crowds out workflow-specific procedure.
|
||||
- Re-audit security posture before any Truthmark skill gains scripts, assets, network-capable dependencies, or generated reference files.
|
||||
- When an agent failure reveals a workflow gotcha, add the gotcha to the smallest owning workflow body or shared gate rather than rewriting broad instructions.
|
||||
+31
-159
@@ -1,188 +1,60 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: agent-rules
|
||||
last_reviewed: 2026-05-09
|
||||
last_reviewed: 2026-05-15
|
||||
source_of_truth:
|
||||
- ../../AGENTS.md
|
||||
- ../README.md
|
||||
- ../../TRUTHMARK.md
|
||||
---
|
||||
|
||||
# Repository Rules
|
||||
|
||||
## Scope
|
||||
Repository-wide agent authority, routing, and completion rules. Read the smallest sufficient set; detailed behavior lives in [docs/](../README.md).
|
||||
|
||||
This document defines repository-wide agent rules, authority order, and completion requirements for Truthmark.
|
||||
## Authority
|
||||
|
||||
Detailed standards, current architecture, contracts, and current feature behavior live under [docs/](../README.md).
|
||||
|
||||
## Authority and Context
|
||||
|
||||
### Authority Order
|
||||
|
||||
When sources conflict, authority descends in this order:
|
||||
Conflict order:
|
||||
|
||||
1. this file
|
||||
2. [TRUTHMARK.md](../../TRUTHMARK.md)
|
||||
3. [docs/truthmark/areas.md](../truthmark/areas.md)
|
||||
2. [.truthmark/config.yml](../../.truthmark/config.yml)
|
||||
3. [docs/truthmark/areas.md](../truthmark/areas.md) and `docs/truthmark/areas/**/*.md`
|
||||
4. `docs/standards/**/*.md`
|
||||
5. `docs/architecture/**/*.md`
|
||||
6. `docs/features/**/*.md`
|
||||
6. `docs/truth/**/*.md`
|
||||
|
||||
[README.md](../../README.md) may help with onboarding and positioning context, but it does not override the canonical current-state docs above.
|
||||
Authoritative context is the current checkout plus user-provided session context; chat, external notes, and off-repo memory are non-authoritative unless committed or supplied now.
|
||||
|
||||
### Context Boundaries
|
||||
Code is the implementation. On code/doc conflict, inspect code, decide whether code is intentional or docs are stale, update stale docs for intentional behavior, and change code to match docs only when requested or required.
|
||||
|
||||
Authoritative context is limited to committed repository artifacts plus user-provided session context:
|
||||
## Product Boundary
|
||||
|
||||
- code
|
||||
- docs
|
||||
- tests
|
||||
- config
|
||||
- generated artifacts that are checked into the repo intentionally
|
||||
Truthmark public CLI commands are `config`, `init`, `check`, `index`, `impact`, and `context`. Truth Structure, Truth Document, Truth Sync, Truth Realize, and Truth Check are installed workflow surfaces, not CLI commands.
|
||||
|
||||
Treat chat history, external notes, and off-repo memories as non-authoritative unless the user provides them in the current session or the information has been committed into the repository.
|
||||
Agents inspect the active checkout directly. There is no daemon, database, remote service, or V1 MCP server.
|
||||
|
||||
### Code-vs-Docs Rule
|
||||
## Rules
|
||||
|
||||
Code is the current implementation.
|
||||
1. Workflow and skill quality, performance, dispatch clarity, and agent effectiveness are the highest-priority repo concerns. Treat workflows and skills as the core product surface of this agent-native project; when tradeoffs conflict, optimize them before secondary structure, convenience, or polish.
|
||||
2. Rules in this file are a compact behavior contract for observed repository failure modes. Prefer replacing weak or stale rules over accumulating generic prompts, identity statements, examples, or tool-dependent ceremony.
|
||||
3. Branch-local Markdown is canonical; the current checkout is the truth boundary.
|
||||
4. Current truth belongs in canonical docs, not historical plans or separate timestamped decision logs.
|
||||
5. Active decisions and rationale live in the canonical doc for the governed behavior.
|
||||
6. Read owning surfaces before writing: for workflows, skills, prompts, commands, generated instructions, or managed blocks, inspect the nearest canonical doc plus the source renderer, template, schema, or parser before editing.
|
||||
7. Generated surfaces are products, not source authority. Edit templates and renderers by default; patch generated output only when explicitly maintaining that generated surface.
|
||||
8. Claims about commands, platforms, runtime topology, services, generated surfaces, or workflow capabilities require primary checkout evidence. Surface desired-vs-implemented conflicts instead of averaging patterns or inventing future behavior.
|
||||
9. Deterministic policy belongs in code, schemas, parsers, templates, or checks when the repository can enforce it. Use model-facing workflow prose to guide agents, not as the only guard for repeatable routing, ownership, parsing, or generation decisions.
|
||||
10. Keep routing explicit: when a code area changes canonical docs, update truth routing in the same change.
|
||||
11. Behavior, contract, workflow, and completion-rule changes update the nearest canonical doc. Major product/onboarding/install/command/positioning/workflow changes also update the root README. A material root README change blocks completion until the localized root READMEs change in the same working change.
|
||||
12. Follow established module boundaries and existing generated-surface patterns; avoid duplicate surfaces, single-use abstractions, speculative configurability, and impossible-scenario error handling.
|
||||
13. Verify the text and file contracts that changed with the narrowest evidence that can falsify them: generated diffs, structured parsers, snapshots, fixture round-trips, build/package/check commands, or focused tests. Do not run broad tests as ceremony when they add no evidence; state skipped checks.
|
||||
14. Work surgically and fail visibly: surface assumptions, conflicts, skipped files, blocked ownership, and unverified claims; touch only request-traceable lines, match existing style, checkpoint long workflow or skill edits, and report unrelated issues instead of editing them.
|
||||
|
||||
If code and docs conflict:
|
||||
## Routing
|
||||
|
||||
1. inspect the relevant code path
|
||||
2. determine whether the code is intentional or the doc is stale
|
||||
3. update the stale doc when behavior is intentional
|
||||
4. only change code to match docs when the user explicitly wants that outcome or the docs clearly reflect the intended requirement
|
||||
Fast task routing lives in [agent-onboarding.md](agent-onboarding.md). Read only the docs that govern the slice you are changing.
|
||||
|
||||
## Project Intent
|
||||
|
||||
Truthmark is an agent-native repository truth protocol packaged with a local-first Node and TypeScript installer and validator.
|
||||
|
||||
Current product boundaries:
|
||||
|
||||
- user-facing CLI commands are `config`, `init`, and `check`
|
||||
- installed `SKILL.md` files and the managed `AGENTS.md` block are the runtime for truth workflows
|
||||
- Truth Structure, Truth Sync, Truth Realize, and Truth Check are installed workflow surfaces, not top-level CLI commands
|
||||
- `truthmark config` writes the committed hierarchy contract before workflow installation
|
||||
- `.truthmark/config.yml` `platforms` controls which agent harness surfaces `truthmark init` installs or refreshes
|
||||
- agents inspect the checkout directly and make semantic judgments about area structure, routing, sync, realization, and truth health
|
||||
- `truthmark init` installs or refreshes workflow surfaces
|
||||
- `truthmark check` validates repository truth artifacts after agent work
|
||||
- the tool operates on the active Git worktree and does not require a daemon, database, or remote service
|
||||
- V1 does not ship an MCP server
|
||||
|
||||
## Non-Negotiable Rules
|
||||
|
||||
1. **Branch-local Markdown is canonical**
|
||||
- The current checkout is the truth boundary.
|
||||
|
||||
2. **Keep current truth separate from history**
|
||||
- Current behavior belongs in configured canonical roots such as `docs/architecture/**` and `docs/features/**`.
|
||||
- Historical planning artifacts do not become current truth automatically; rewrite current decisions into the canonical docs they govern.
|
||||
|
||||
3. **Keep active decisions in canonical docs**
|
||||
- Active decisions and rationale belong in the same canonical doc as the behavior they govern.
|
||||
- Short inline decision dates are allowed; do not create separate timestamped decision-ticket folders for current decisions.
|
||||
|
||||
4. **The managed Truthmark block stays managed**
|
||||
- The block in [AGENTS.md](../../AGENTS.md) between `<!-- truthmark:start -->` and `<!-- truthmark:end -->` is a generated surface.
|
||||
- Manual repository-specific guidance belongs outside that block.
|
||||
|
||||
5. **Document actual V1 behavior only**
|
||||
- Do not add speculative CLI commands, hosted services, or product capabilities that are not implemented.
|
||||
|
||||
6. **Areas routing must stay explicit**
|
||||
- If the canonical docs for a code area change, update [docs/truthmark/areas.md](../truthmark/areas.md) in the same change.
|
||||
|
||||
7. **Docs change with behavior**
|
||||
- If a behavior, contract, workflow, or completion rule changes, update the nearest canonical doc in the same working change.
|
||||
- For major product, onboarding, install, command, positioning, or workflow changes, review the root [README.md](../../README.md) in the same working change and update stale user-facing claims, examples, or command sequences.
|
||||
- When the root README changes materially, update the localized README variants in the same working change or explicitly confirm why they remain intentionally different.
|
||||
|
||||
8. **Keep onboarding honest**
|
||||
- The root README is not the canonical behavior spec, but it is the human entry point. It must not lag behind major product changes that affect how people understand, install, or use Truthmark.
|
||||
|
||||
9. **Prefer established module boundaries**
|
||||
- Follow the current directory responsibilities before introducing new abstractions or duplicate surfaces.
|
||||
|
||||
10. **Testing policy is centralized**
|
||||
- Follow [docs/standards/testing-and-verification.md](../standards/testing-and-verification.md) for commands.
|
||||
|
||||
11. **Completion policy is centralized**
|
||||
- Use [docs/standards/pre-completion-checklist.md](../standards/pre-completion-checklist.md) as the completion gate.
|
||||
|
||||
12. **Scope changes narrowly**
|
||||
- Do not mix unrelated refactors or speculative cleanup into a focused task.
|
||||
|
||||
## Documentation Routing
|
||||
|
||||
Start here when working in an unfamiliar area:
|
||||
|
||||
- [docs/README.md](../README.md)
|
||||
- [docs/architecture/overview.md](../architecture/overview.md)
|
||||
- [docs/architecture/module-map.md](../architecture/module-map.md)
|
||||
- [docs/features/contracts.md](../features/contracts.md)
|
||||
|
||||
### CLI or scaffold changes
|
||||
|
||||
Read:
|
||||
|
||||
1. [docs/features/init-and-scaffold.md](../features/init-and-scaffold.md)
|
||||
2. [docs/features/contracts.md](../features/contracts.md)
|
||||
3. [docs/standards/maintaining-repository-truth.md](../standards/maintaining-repository-truth.md) when the change affects docs placement or AGENTS management
|
||||
|
||||
Run `truthmark config` before `truthmark init` in new repositories so teams can review the hierarchy before generated agent behavior is installed.
|
||||
|
||||
### Check, routing, or validation changes
|
||||
|
||||
Read:
|
||||
|
||||
1. [docs/features/check-diagnostics.md](../features/check-diagnostics.md)
|
||||
2. [docs/standards/documentation-governance.md](../standards/documentation-governance.md)
|
||||
3. [docs/features/contracts.md](../features/contracts.md)
|
||||
|
||||
### Installed workflow or reporting changes
|
||||
|
||||
Read:
|
||||
|
||||
1. [TRUTHMARK.md](../../TRUTHMARK.md)
|
||||
2. [docs/features/installed-workflows.md](../features/installed-workflows.md)
|
||||
3. [docs/standards/maintaining-repository-truth.md](../standards/maintaining-repository-truth.md) if routing or canonical docs placement changes
|
||||
|
||||
### Documentation-only organization changes
|
||||
|
||||
Read:
|
||||
|
||||
1. [docs/README.md](../README.md)
|
||||
2. [docs/standards/documentation-governance.md](../standards/documentation-governance.md)
|
||||
3. [docs/standards/maintaining-repository-truth.md](../standards/maintaining-repository-truth.md)
|
||||
|
||||
## Guardrails
|
||||
|
||||
### Anti-drift rules
|
||||
|
||||
- do not create a shadow documentation tree
|
||||
- do not treat historical plans as current implementation docs
|
||||
- do not keep editing the managed Truthmark block manually unless the template behavior itself is changing
|
||||
- do not broaden current-state docs with draft or aspirational behavior
|
||||
- do not leave doc routing ambiguous when code moves or new code surfaces are added
|
||||
- do not finish a major product or workflow change without checking whether the root README still tells the truth
|
||||
|
||||
### Divergence rule
|
||||
|
||||
When several files follow an established pattern and one diverges, assume the diverging file needs justification before copying it.
|
||||
|
||||
### When blocked
|
||||
|
||||
Re-read the relevant canonical docs, inspect the owning implementation, and then change approach. If the blocker remains, surface the blocker explicitly instead of guessing.
|
||||
If blocked, re-read the relevant canonical docs and owning implementation, then surface the blocker instead of guessing. If one file diverges from an established pattern, require justification before copying it.
|
||||
|
||||
## Maintenance
|
||||
|
||||
Update this file only when repository-wide agent rules change.
|
||||
|
||||
When updating it:
|
||||
|
||||
- keep it concise and policy-focused
|
||||
- move detailed procedures into standards or guides
|
||||
- keep current feature behavior in `docs/features`
|
||||
- update `last_reviewed`
|
||||
Update this file only for repository-wide agent rules. Keep it compact and policy-focused. Put procedures in standards or guides, feature behavior in `docs/truth`, and update `last_reviewed`.
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: architecture
|
||||
last_reviewed: 2026-05-09
|
||||
last_reviewed: 2026-05-14
|
||||
source_of_truth:
|
||||
- overview.md
|
||||
---
|
||||
@@ -12,6 +12,17 @@ source_of_truth:
|
||||
|
||||
This is the quick module-level map for the current Truthmark codebase.
|
||||
|
||||
## Scope
|
||||
|
||||
This doc covers the current module grouping of the Truthmark codebase and the primary canonical docs that pair with those modules.
|
||||
|
||||
## Components
|
||||
|
||||
- CLI and config loading: `src/cli/`, `src/config/`, and shared result rendering.
|
||||
- Scaffold and generated surfaces: `src/init/`, `src/templates/`, and containment-safe write helpers in `src/fs/`.
|
||||
- Routing and checks: `src/routing/`, `src/checks/`, `src/markdown/`, and repository discovery in `src/git/`.
|
||||
- Installed workflow support: `src/agents/`, `src/generation/`, `src/sync/`, `src/realize/`, and neutral truth helpers in `src/truth/`.
|
||||
|
||||
## Source Layout
|
||||
|
||||
| Path | Responsibility |
|
||||
@@ -24,9 +35,11 @@ This is the quick module-level map for the current Truthmark codebase.
|
||||
| `src/routing/` | Parsing of the root route index and delegated child route files |
|
||||
| `src/markdown/` | Markdown discovery, parsing, and hashing helpers |
|
||||
| `src/fs/` | Repository-safe path resolution and file writes shared by init and diagnostics |
|
||||
| `src/generation/` | Source-internal content prompt contracts, JSON-safe prompt rendering, and structured draft validation |
|
||||
| `src/truth/` | Neutral helpers for truth root resolution and evidence report formatting shared by scaffold, checks, sync, and agent renderers |
|
||||
| `src/git/` | Git repository and worktree resolution plus change listing |
|
||||
| `src/sync/` | Truth Sync policy and completed, skipped, or blocked report rendering |
|
||||
| `src/agents/` | Installed Truth Structure, Truth Sync, Truth Realize, and Truth Check instruction text plus shared worker and skill contract fragments |
|
||||
| `src/agents/` | Installed Truth Structure, Truth Document, Truth Sync, Truth Realize, and Truth Check instruction text plus shared worker and skill contract fragments |
|
||||
| `src/realize/` | Truth Realize report rendering |
|
||||
| `src/output/` | Diagnostic types plus human and JSON rendering shared by CLI and check flows |
|
||||
| `src/types/` | Local type shims |
|
||||
@@ -36,21 +49,25 @@ This is the quick module-level map for the current Truthmark codebase.
|
||||
|
||||
- If the change affects scaffolded file contents or generated skill surfaces, start in `src/templates/` and `src/init/`.
|
||||
- If the change affects diagnostics, start in `src/checks/` and `src/output/`.
|
||||
- If the change affects installed workflow text or explicit skill surfaces, start in `src/agents/`, `src/sync/`, `src/realize/`, and `src/templates/`.
|
||||
- If the change affects installed workflow text, content prompt contracts, or explicit skill surfaces, start in `src/agents/`, `src/generation/`, `src/sync/`, `src/realize/`, and `src/templates/`.
|
||||
- If the change affects path safety or repository detection, start in `src/fs/` and `src/git/`.
|
||||
|
||||
## Documentation Pairings
|
||||
|
||||
- `src/init/`, `src/templates/`, and the write-path parts of `src/fs/` pair with [docs/features/init-and-scaffold.md](../features/init-and-scaffold.md)
|
||||
- `src/checks/`, `src/routing/`, `src/config/`, `src/output/`, and the containment-path parts of `src/fs/` pair with [docs/features/check-diagnostics.md](../features/check-diagnostics.md)
|
||||
- `src/agents/`, `src/sync/`, `src/realize/`, and installed workflow skill templates under `src/templates/` pair with [docs/features/installed-workflows.md](../features/installed-workflows.md)
|
||||
- `src/init/`, `src/templates/`, and the write-path parts of `src/fs/` pair with [docs/truth/init-and-scaffold.md](../truth/init-and-scaffold.md)
|
||||
- `src/checks/`, `src/routing/`, `src/config/`, `src/output/`, and the containment-path parts of `src/fs/` pair with [docs/truth/check-diagnostics.md](../truth/check-diagnostics.md)
|
||||
- `src/agents/`, `src/generation/`, `src/sync/`, `src/realize/`, `src/truth/`, and installed workflow skill templates under `src/templates/` pair with [docs/truth/workflows/overview.md](../truth/workflows/overview.md) and bounded workflow docs under `docs/truth/workflows/`
|
||||
|
||||
## Product Decisions
|
||||
|
||||
- Route ownership stays in Markdown route files rather than being duplicated into config objects.
|
||||
- `src/agents/` and `src/templates/` render configured hierarchy and decision-truth guidance directly into installed workflow surfaces.
|
||||
- Content-generation prompt contracts live outside `src/agents/` so workflow authority and draft-content shaping remain separate.
|
||||
- `src/checks/decisions.ts` belongs with the validation layer because decision-bearing canonical docs are a truth-health concern, not an authoring convenience.
|
||||
- Shared truth-root and evidence formatting helpers live in `src/truth/` so scaffold, checks, sync reports, and generated agent text do not duplicate the same domain defaults.
|
||||
|
||||
## Rationale
|
||||
|
||||
This split keeps layout contract, route ownership, validation, and generated workflow text in predictable places. Agents and maintainers can change one surface without rediscovering unrelated behavior hidden elsewhere.
|
||||
|
||||
The generation layer is source-internal in this slice because current packaging builds only the CLI entrypoint. Keeping prompt contracts separate from installed workflow renderers preserves the existing workflow authority model while giving future workflow code a tested draft-contract layer to consume.
|
||||
|
||||
@@ -1,12 +1,14 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: architecture
|
||||
last_reviewed: 2026-05-09
|
||||
last_reviewed: 2026-05-13
|
||||
source_of_truth:
|
||||
- ../../TRUTHMARK.md
|
||||
- ../features/contracts.md
|
||||
- ../features/init-and-scaffold.md
|
||||
- ../features/check-diagnostics.md
|
||||
- ../../.truthmark/config.yml
|
||||
- ../truth/contracts.md
|
||||
- ../truth/init-and-scaffold.md
|
||||
- ../truth/check-diagnostics.md
|
||||
- ../truth/workflows/overview.md
|
||||
- ../truth/workflows/shared-gates.md
|
||||
---
|
||||
|
||||
# Architecture Overview
|
||||
@@ -31,24 +33,28 @@ Truthmark does not currently include:
|
||||
The durable surfaces are ordinary repository files:
|
||||
|
||||
- `.truthmark/config.yml`
|
||||
- [TRUTHMARK.md](../../TRUTHMARK.md)
|
||||
- [docs/truthmark/areas.md](../truthmark/areas.md)
|
||||
- canonical docs under `docs/`
|
||||
- the managed Truthmark block inside [AGENTS.md](../../AGENTS.md)
|
||||
- the generated Codex Truth Structure, Truth Sync, Truth Realize, and Truth Check skills under `.codex/skills/`
|
||||
- the generated OpenCode Truth Structure, Truth Sync, Truth Realize, and Truth Check skills under `.opencode/skills/`
|
||||
- configured platform instruction files such as [AGENTS.md](../../AGENTS.md), `CLAUDE.md`, `.cursor/rules/truthmark.mdc`, `.github/copilot-instructions.md`, and `GEMINI.md`
|
||||
- Gemini custom command surfaces under `.gemini/commands/truthmark/*.toml`
|
||||
- generated Truth Structure, Truth Document, Truth Sync, Truth Realize, and Truth Check surfaces under `.codex/skills/`, `.opencode/skills/`, `.claude/skills/`, `.github/prompts/`, and `.gemini/commands/truthmark/`
|
||||
- Codex workflow metadata under `.codex/skills/truthmark-*/agents/openai.yaml`
|
||||
- configured platform instruction files such as [AGENTS.md](../../AGENTS.md), `CLAUDE.md`, `.github/copilot-instructions.md`, and `GEMINI.md`
|
||||
|
||||
Generated workflow surfaces are committed repository files with Truthmark version markers. The V1 upgrade path is to upgrade the package, rerun `truthmark init`, and review the generated diffs.
|
||||
|
||||
## Boundaries
|
||||
|
||||
- The CLI owns committed config, routing, diagnostics, scaffolded files, and generated workflow surfaces inside the active repository.
|
||||
- Repository truth stays in Git-tracked Markdown and managed instruction surfaces rather than off-repo caches, daemons, or hosted services.
|
||||
- Architecture docs own structure and ownership boundaries; behavior and contract docs own ordinary product behavior and machine-facing contracts.
|
||||
|
||||
## Core Pipelines
|
||||
|
||||
### Config and init pipeline
|
||||
|
||||
`truthmark config` writes the committed hierarchy contract to `.truthmark/config.yml`.
|
||||
|
||||
`truthmark init` requires that config, resolves the active repository, creates missing structural files for the configured hierarchy, reads the configured `platforms` list, writes or refreshes only those platform surfaces, and returns a structured list of created, updated, or unchanged files plus any migration-review diagnostics. The default scaffold creates feature `README.md` files as indexes and seeds current behavior truth in bounded leaf docs such as `<feature-root>/<default-area>/overview.md`. It does not delete platform files when a platform is removed from config, and it does not silently move existing truth docs when hierarchy changes.
|
||||
`truthmark init` requires that config, resolves the active repository, creates missing structural files for the configured hierarchy, reads the configured `platforms` list, writes or refreshes only those platform surfaces, and returns a structured list of created, updated, or unchanged files plus any migration-review diagnostics. The default scaffold creates truth `README.md` files as indexes and seeds current behavior truth in bounded leaf docs such as `<truth-root>/<default-area>/overview.md`. It does not delete platform files when a platform is removed from config, and it does not silently move existing truth docs when hierarchy changes.
|
||||
|
||||
Key implementation surfaces:
|
||||
|
||||
@@ -59,33 +65,40 @@ Key implementation surfaces:
|
||||
|
||||
### Check pipeline
|
||||
|
||||
`truthmark check` resolves branch-scope metadata, loads config, then validates authority entries, area mappings, frontmatter, and internal links before returning diagnostics plus branch-scope data.
|
||||
`truthmark check` resolves branch-scope metadata, loads config, then validates authority entries, area mappings, frontmatter, internal links, decision structure, generated surfaces, and unmapped coverage before returning diagnostics plus branch-scope data.
|
||||
|
||||
Key implementation surfaces:
|
||||
|
||||
- `src/checks/*` for individual validation passes
|
||||
- `src/config/*` for config loading and schema validation
|
||||
- `src/routing/areas.ts` for `docs/truthmark/areas.md` parsing
|
||||
- `src/routing/*` for `docs/truthmark/areas.md` parsing and area resolution
|
||||
- `src/markdown/*` for document parsing and hashing
|
||||
- `src/output/*` for result rendering
|
||||
|
||||
### Installed workflow support
|
||||
|
||||
Truthmark also contains support primitives for the installed Truth Structure, Truth Sync, Truth Realize, and Truth Check workflows:
|
||||
Truthmark also contains support primitives for the installed Truth Structure, Truth Document, Truth Sync, Truth Realize, and Truth Check workflows:
|
||||
|
||||
- `src/agents/*` renders the installed instruction text used in the managed AGENTS block
|
||||
- `src/templates/codex-skills.ts` renders the generated Codex and OpenCode skills for explicit workflow invocation
|
||||
- `src/templates/agents-block.ts` renders compact managed instruction blocks
|
||||
- `src/agents/*` renders detailed workflow and skill text for explicit workflow invocation
|
||||
- `src/templates/codex-skills.ts` renders generated skill, prompt, command, and metadata content for configured platforms
|
||||
- `src/templates/generated-surfaces.ts` assembles configured platform surfaces from the renderers
|
||||
- `src/sync/*` classifies functional-code paths and renders Truth Sync reports
|
||||
- `src/realize/report.ts` renders the Truth Realize completion report shape
|
||||
|
||||
These modules support the installed workflow contract even though V1 does not expose dedicated CLI entrypoints for structure, sync, realization, or check workflows.
|
||||
These modules support the installed workflow contract even though V1 does not expose dedicated CLI entrypoints for the installed Truth Structure, Truth Document, Truth Sync, Truth Realize, or Truth Check workflows.
|
||||
|
||||
## Architecture Doc Boundary
|
||||
|
||||
Truthmark should maintain architecture docs when a change alters system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership.
|
||||
|
||||
Ordinary product behavior, endpoint details, UI copy, validation rules, and bug fixes belong in behavior or contract docs unless they change those architecture boundaries. Architecture docs should describe structure and ownership rather than becoming a second home for product truth.
|
||||
|
||||
## Branch Scope
|
||||
|
||||
Branch scope is computed from the active Git worktree, current branch or detached HEAD, and hashes of the core Truthmark control files:
|
||||
|
||||
- `.truthmark/config.yml`
|
||||
- [TRUTHMARK.md](../../TRUTHMARK.md)
|
||||
- the configured root route index plus configured child route files
|
||||
|
||||
This keeps routing and diagnostics tied to the active checkout rather than to external memory.
|
||||
@@ -96,7 +109,7 @@ Normal branch checkouts are identified by branch name plus HEAD SHA. Detached ch
|
||||
|
||||
Truth Sync path classification is multi-language and path-based. `truthmark check` coverage diagnostics reuse the same functional-code classifier across common code roots so V1 can support Go, Python, C#, and Java repositories at a minimum, in addition to JavaScript and TypeScript projects.
|
||||
|
||||
Current automatic coverage discovery scans common roots such as `src/`, `cmd/`, `internal/`, `pkg/`, `scripts/`, `server/`, `services/`, `app/`, `lib/`, and `bin/`. Area mappings remain the authority for which truth docs own each code surface.
|
||||
Current automatic coverage discovery scans common roots such as `src/`, `api/`, `app/`, `apps/`, `cmd/`, `frontend/`, `infra/`, `internal/`, `k8s/`, `lib/`, `packages/`, `proto/`, `schema/`, `scripts/`, `server/`, `services/`, `terraform/`, `web/`, and `.github/workflows/`. Area mappings remain the authority for which truth docs own each code surface.
|
||||
|
||||
## Primary Code Files
|
||||
|
||||
@@ -108,13 +121,16 @@ Current automatic coverage discovery scans common roots such as `src/`, `cmd/`,
|
||||
- `src/sync/surfaces.ts`
|
||||
- `src/agents/instructions.ts`
|
||||
- `src/templates/codex-skills.ts`
|
||||
- `src/templates/generated-surfaces.ts`
|
||||
- `src/templates/agents-block.ts`
|
||||
|
||||
## Product Decisions
|
||||
|
||||
- Truthmark is config-first: repositories review committed hierarchy before installed workflow surfaces are generated.
|
||||
- Hierarchical routing is the only scaffold model in V1, with one child delegation level from the root route index.
|
||||
- Default feature scaffolding uses index `README.md` files plus bounded leaf truth docs so Truth Sync has a small current-behavior target from the first init.
|
||||
- Current architecture and feature docs carry their own active decisions and rationale instead of delegating that truth to historical ADR-style logs.
|
||||
- Default truth scaffolding uses index `README.md` files plus bounded leaf truth docs so Truth Sync has a small current-behavior target from the first init.
|
||||
- Current architecture and truth docs carry their own active decisions and rationale instead of delegating that truth to historical ADR-style logs.
|
||||
- Architecture docs are maintained for structure and ownership changes, not for ordinary product behavior.
|
||||
- The current checkout is the truth boundary; Truthmark does not create off-repo memory, packet files, or cache files that compete with branch-local Markdown.
|
||||
- Branch identity is diagnostic metadata, not an external authority source. It helps agents and humans see which checkout was validated without moving truth outside Git.
|
||||
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 1.5 MiB |
Binary file not shown.
|
After Width: | Height: | Size: 1.4 MiB |
Binary file not shown.
|
Before Width: | Height: | Size: 1.2 MiB |
Binary file not shown.
|
After Width: | Height: | Size: 1.4 MiB |
Binary file not shown.
|
After Width: | Height: | Size: 1.4 MiB |
@@ -1,160 +0,0 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: feature
|
||||
last_reviewed: 2026-05-09
|
||||
source_of_truth:
|
||||
- ../../src/init/init.ts
|
||||
- ../../src/templates/init-files.ts
|
||||
- ../../src/templates/agents-block.ts
|
||||
- ../../src/templates/codex-skills.ts
|
||||
- ../../src/templates/generated-surfaces.ts
|
||||
---
|
||||
|
||||
# Init And Scaffold
|
||||
|
||||
## Scope
|
||||
|
||||
This document describes the current behavior of `truthmark config` and `truthmark init`.
|
||||
|
||||
## Current Behavior
|
||||
|
||||
`truthmark config` is the required first step in a new repository. It writes only `.truthmark/config.yml` unless `--stdout` is used.
|
||||
|
||||
`truthmark init` operates on the active Git worktree and does all of the following in one pass:
|
||||
|
||||
1. resolves the active repository and worktree
|
||||
2. requires an existing valid `.truthmark/config.yml`
|
||||
3. creates default standards only when they are missing or empty
|
||||
4. creates missing configured docs and routing structure such as [TRUTHMARK.md](../../TRUTHMARK.md), the configured root route index, the configured default child route file, the configured feature-root README, a default area index README, and a default bounded leaf truth doc
|
||||
5. loads the configured `platforms` list
|
||||
6. writes or refreshes configured instruction targets and configured platform surfaces
|
||||
7. rewrites managed Truthmark instruction blocks while preserving manual content outside those blocks
|
||||
8. writes generated skill surfaces for configured skill-based platforms
|
||||
9. reports migration risks instead of moving existing truth docs when hierarchy changes imply manual migration
|
||||
10. reports each touched file as `created`, `updated`, or `unchanged`
|
||||
|
||||
## Scaffolded Files
|
||||
|
||||
Current scaffold targets:
|
||||
|
||||
- `.truthmark/config.yml` via `truthmark config`
|
||||
- [TRUTHMARK.md](../../TRUTHMARK.md)
|
||||
- [docs/truthmark/areas.md](../truthmark/areas.md)
|
||||
- configured child route files under `docs/truthmark/areas/**/*.md`
|
||||
- configured feature-root README files such as `docs/features/README.md`
|
||||
- configured default-area index README files such as `docs/features/repository/README.md`
|
||||
- configured default-area bounded leaf truth docs such as `docs/features/repository/overview.md`
|
||||
- [docs/standards/default-principles.md](../standards/default-principles.md)
|
||||
- [docs/standards/documentation-governance.md](../standards/documentation-governance.md)
|
||||
- the managed block inside [AGENTS.md](../../AGENTS.md)
|
||||
- [CLAUDE.md](../../CLAUDE.md)
|
||||
- `.codex/skills/truthmark-structure/SKILL.md`
|
||||
- `.codex/skills/truthmark-structure/agents/openai.yaml`
|
||||
- `.codex/skills/truthmark-sync/SKILL.md`
|
||||
- `.codex/skills/truthmark-sync/agents/openai.yaml`
|
||||
- `.codex/skills/truthmark-realize/SKILL.md`
|
||||
- `.codex/skills/truthmark-realize/agents/openai.yaml`
|
||||
- `.codex/skills/truthmark-check/SKILL.md`
|
||||
- `.codex/skills/truthmark-check/agents/openai.yaml`
|
||||
- `.opencode/skills/truthmark-structure/SKILL.md`
|
||||
- `.opencode/skills/truthmark-sync/SKILL.md`
|
||||
- `.opencode/skills/truthmark-realize/SKILL.md`
|
||||
- `.opencode/skills/truthmark-check/SKILL.md`
|
||||
- `.cursor/rules/truthmark.mdc`
|
||||
- `.github/copilot-instructions.md`
|
||||
- `GEMINI.md`
|
||||
- `.gemini/commands/truthmark/structure.toml`
|
||||
- `.gemini/commands/truthmark/sync.toml`
|
||||
- `.gemini/commands/truthmark/realize.toml`
|
||||
- `.gemini/commands/truthmark/check.toml`
|
||||
|
||||
`instruction_targets` controls shared managed-instruction files such as `AGENTS.md`. These targets are written or refreshed whenever `truthmark init` runs with a valid config, independent of the configured platform list.
|
||||
`platforms` controls which platform-specific surfaces are written or refreshed. Defaults are `codex`, `opencode`, and `claude-code`. Teams may add `cursor`, `github-copilot`, or `gemini-cli` and rerun `truthmark init` to add those files. Gemini installs both `GEMINI.md` and project-scoped TOML commands under `.gemini/commands/truthmark/`, which surface as `/truthmark:structure`, `/truthmark:sync`, `/truthmark:realize`, and `/truthmark:check` in Gemini CLI. Unknown platform names are config errors. Removing a platform stops future refreshes for that platform, but `init` does not delete previously generated files.
|
||||
|
||||
`ensureRepoFile` is intentionally conservative: existing non-empty files are left alone. The AGENTS managed block is the exception because Truthmark owns that block and may refresh it to match current template behavior.
|
||||
|
||||
The generated Truth Structure, Truth Sync, Truth Realize, and Truth Check explicit surfaces are also managed by Truthmark and may be refreshed on rerun so the Codex skills, metadata, and OpenCode skills keep matching the installed workflow contract. Generated skills, Codex metadata, managed instruction blocks, and `TRUTHMARK.md` include the Truthmark package version that rendered them; `package.json` is the single maintained version source. After upgrading Truthmark, rerun `truthmark init` and review generated workflow diffs.
|
||||
|
||||
## AGENTS Management Rules
|
||||
|
||||
The current managed-instruction update behavior is:
|
||||
|
||||
- replace an existing managed Truthmark block when it is well formed
|
||||
- remove older managed-looking chunks when possible
|
||||
- preserve manual text outside the managed block
|
||||
- append the managed block when no block exists
|
||||
- keep the generated workflow block compact and front-loaded so it does not consume unnecessary model context in long legacy instruction files
|
||||
- keep detailed report examples and long workflow procedure in explicit generated skill files instead of host instruction blocks
|
||||
|
||||
Repository-specific instructions should therefore live outside the managed block.
|
||||
|
||||
Truthmark does not create `OPENCODE.md` in V1. OpenCode-compatible behavior is installed through shared `AGENTS.md` guidance and project skill files under `.opencode/skills/`.
|
||||
|
||||
## Hierarchy Behavior
|
||||
|
||||
Hierarchy is configured in `.truthmark/config.yml`:
|
||||
|
||||
- `docs.layout` is currently `hierarchical`
|
||||
- `docs.roots` names the canonical doc roots
|
||||
- `docs.routing.root_index` is the root route index path
|
||||
- `docs.routing.area_files_root` is the directory for child route files
|
||||
- `docs.routing.default_area` is the scaffolded child route basename
|
||||
- `docs.routing.max_delegation_depth` must currently be `1`
|
||||
|
||||
`truthmark init` creates missing structure for that hierarchy, but it does not silently move, delete, or reinterpret existing truth docs when teams change the configured roots. Those cases produce review diagnostics for manual migration.
|
||||
The default scaffold treats feature `README.md` files as indexes. Current behavior truth belongs in bounded leaf docs under the configured feature root, such as `<feature-root>/<domain>/<behavior>.md`.
|
||||
|
||||
## Current Defaults
|
||||
|
||||
Important current defaults:
|
||||
|
||||
- default authority includes the canonical doc classes under `docs/`
|
||||
- default code surface in the scaffolded root and child route files starts as `src/**`
|
||||
- default feature scaffolding creates an index at `<feature-root>/README.md`, an index at `<feature-root>/<default-area>/README.md`, and a bounded leaf truth doc at `<feature-root>/<default-area>/overview.md`
|
||||
- default platforms are `codex`, `opencode`, and `claude-code`
|
||||
- shared instruction targets are refreshed independently of platform-specific surfaces
|
||||
- explicit Truth Structure, Truth Sync, Truth Realize, and Truth Check surfaces are installed only for configured platforms
|
||||
- installed workflows are agent-native; generated skills tell agents to inspect the checkout directly
|
||||
- generated workflow surfaces leave Truth Sync subagent selection to the acting agent and host environment
|
||||
- generated workflow surfaces include a configured hierarchy summary and decision-truth guidance
|
||||
- scaffolded default standards include AI-native topology repair guidance so new repositories do not rely on human feature-folder discipline
|
||||
- Truth Sync is the only generated skill with implicit invocation enabled because it is the automatic finish-time workflow
|
||||
- `truthmark check` is optional validation for agent workflows, not a required workflow preflight
|
||||
- realization is enabled as generated Codex and OpenCode explicit surfaces plus an installed instruction surface, not as a dedicated CLI subcommand
|
||||
- Gemini CLI support uses `GEMINI.md` for hierarchical memory and `.gemini/commands/truthmark/*.toml` for explicit workflow commands instead of introducing Truthmark-specific top-level CLI verbs
|
||||
|
||||
## Init Diagnostics
|
||||
|
||||
Current init JSON reporting uses:
|
||||
|
||||
- `truth-sync` for the managed `AGENTS.md` block and generated Truth Structure, Truth Sync, and Truth Check skill assets
|
||||
- `realization` for generated Truth Realize skill assets
|
||||
- `authority` for [TRUTHMARK.md](../../TRUTHMARK.md) and [docs/truthmark/areas.md](../truthmark/areas.md)
|
||||
- `config` for the remaining scaffolded files
|
||||
|
||||
## Invariants
|
||||
|
||||
- all generated paths must remain inside the active repository root
|
||||
- init must be idempotent for existing non-empty scaffold files except for the managed AGENTS block
|
||||
- the command should remain safe to run repeatedly in the same repository
|
||||
|
||||
## Product Decisions
|
||||
|
||||
- `truthmark config` owns the committed layout contract and must happen before `truthmark init`.
|
||||
- Hierarchical routing is the only scaffold model, and route ownership stays in Markdown route files rather than config.
|
||||
- Init reports migration risk instead of rewriting existing truth doc placement on the user's behalf.
|
||||
- V1 uses configured shared instruction targets such as `AGENTS.md` plus generated skill or command surfaces for host compatibility instead of creating host-specific top-level instruction files for every adapter.
|
||||
|
||||
## Rationale
|
||||
|
||||
This split makes the hierarchy reviewable before generated workflow behavior lands in the repo. Keeping route ownership in Markdown preserves local editing ergonomics. Refusing silent migrations avoids accidental truth loss when a repository reshapes its canonical docs tree.
|
||||
|
||||
Keeping host-specific detail in generated skills and Gemini command files prevents the repository root from accumulating parallel instruction files that drift from the managed workflow contract.
|
||||
|
||||
## Primary Code Files
|
||||
|
||||
- `src/init/init.ts`
|
||||
- `src/templates/init-files.ts`
|
||||
- `src/templates/agents-block.ts`
|
||||
- `src/templates/codex-skills.ts`
|
||||
- `src/fs/paths.ts`
|
||||
@@ -1,202 +0,0 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: feature
|
||||
last_reviewed: 2026-05-09
|
||||
source_of_truth:
|
||||
- ../../src/agents/instructions.ts
|
||||
- ../../src/agents/truth-structure.ts
|
||||
- ../../src/agents/truth-sync.ts
|
||||
- ../../src/agents/truth-check.ts
|
||||
- ../../src/agents/prompts.ts
|
||||
- ../../src/templates/codex-skills.ts
|
||||
- ../../src/sync/report.ts
|
||||
- ../../src/realize/report.ts
|
||||
---
|
||||
|
||||
# Installed Workflows
|
||||
|
||||
## Scope
|
||||
|
||||
This document describes the current installed Truthmark workflow contract written into [AGENTS.md](../../AGENTS.md) and generated `SKILL.md` files.
|
||||
|
||||
## Product Model
|
||||
|
||||
Truthmark is agent-native. Installed skills and the managed `AGENTS.md` block are the runtime.
|
||||
|
||||
Agents are expected to inspect the checkout directly, make semantic judgments, update repository truth, and report what they changed. The `truthmark` CLI installs and refreshes workflow surfaces, and `truthmark check` validates artifacts after agent work. The CLI is not required to prepare workflow context before an agent can run.
|
||||
|
||||
Truthmark assumes capable acting AI models. Weak model performance is a host or user choice, not a reason for the product to make the CLI the workflow orchestrator.
|
||||
|
||||
## Installed Surfaces
|
||||
|
||||
Current explicit workflow surfaces are installed per configured platform in `.truthmark/config.yml`.
|
||||
|
||||
Supported platform values:
|
||||
|
||||
- `codex`
|
||||
- `opencode`
|
||||
- `claude-code`
|
||||
- `cursor`
|
||||
- `github-copilot`
|
||||
- `gemini-cli`
|
||||
|
||||
The default platform list is `codex`, `opencode`, and `claude-code`. Teams can add more platforms later and rerun `truthmark init`.
|
||||
|
||||
Workflow invocation examples:
|
||||
|
||||
- Truth Structure: `/skill truthmark-structure` in OpenCode-style hosts, `/truthmark-structure` or `$truthmark-structure` in Codex, and `/truthmark:structure` in Gemini CLI
|
||||
- Truth Sync: `/skill truthmark-sync` in OpenCode-style hosts, `/truthmark-sync` or `$truthmark-sync` in Codex, and `/truthmark:sync` in Gemini CLI
|
||||
- Truth Realize: `/skill truthmark-realize` in OpenCode-style hosts, `/truthmark-realize` or `$truthmark-realize` in Codex, and `/truthmark:realize` in Gemini CLI
|
||||
- Truth Check: `/skill truthmark-check` in OpenCode-style hosts, `/truthmark-check` or `$truthmark-check` in Codex, and `/truthmark:check` in Gemini CLI
|
||||
- Gemini CLI installs project-scoped custom commands at `.gemini/commands/truthmark/*.toml`, which surface as `/truthmark:structure`, `/truthmark:sync`, `/truthmark:realize`, and `/truthmark:check`
|
||||
|
||||
The managed `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, and equivalent platform instruction blocks keep compact reminders for these workflows. They intentionally omit report examples and long procedural checklists so installed prompts do not consume unnecessary model context. The generated skills and Gemini command files hold the detailed workflow bodies and report examples for explicit invocation.
|
||||
|
||||
Generated skill files, Gemini command files, Codex metadata, managed instruction blocks, and `TRUTHMARK.md` include the Truthmark package version used to render them. The package version in `package.json` is the single maintained version source. After upgrading Truthmark, rerun `truthmark init` and review the generated workflow diffs. This rerun-init convention is the V1 staleness story for committed workflow surfaces.
|
||||
|
||||
Generated workflow surfaces include the configured hierarchy summary from `.truthmark/config.yml`. Agents must read the configured root route index and only relevant child route files before updating routed truth docs. Generated skill text states that repository docs and code are inspected evidence, not executable instruction authority.
|
||||
Truthmark-owned skill surfaces are generated under host-specific directories such as `.codex/skills/` and `.opencode/skills/`. Repo-root `skills/` files are not generated workflow surfaces and are not classified as derived Truthmark output.
|
||||
Generated workflow text also treats feature `README.md` files as indexes rather than Truth Sync targets. Current behavior truth should live in bounded leaf docs under the configured feature root, such as `<feature-root>/<domain>/<behavior>.md`.
|
||||
|
||||
## Truth Structure
|
||||
|
||||
Truth Structure designs or repairs repository truth topology. It owns area routing, child route-file structure, and starter truth-doc placement when the existing topology is missing, stale, broad, overloaded, or explicitly requested.
|
||||
|
||||
The agent should:
|
||||
|
||||
- inspect repository layout, current docs, config, routing metadata, and relevant code directly
|
||||
- inspect controllers, routes, handlers, services, packages, tests, and representative implementation boundaries
|
||||
- define areas by product or behavior ownership
|
||||
- repair broad, stale, missing, or non-canonical routing
|
||||
- create starter canonical truth docs when useful
|
||||
- write starter truth docs with closed YAML frontmatter bounded by opening and closing `---` lines, including `status`, `doc_type`, `last_reviewed`, and `source_of_truth` inside that frontmatter
|
||||
- include `Product Decisions` and `Rationale` sections in starter truth docs
|
||||
- repair routed canonical current-truth docs that are missing `Product Decisions` or `Rationale` sections before finishing topology repair
|
||||
- keep starter truth docs inside canonical current-truth destinations
|
||||
- keep feature `README.md` files as indexes and create bounded leaf docs for behavior truth
|
||||
- keep feature docs behavior-oriented rather than endpoint-oriented
|
||||
- split broad catch-all routing before creating or extending generic feature docs
|
||||
- operate from committed repository files when the Truthmark CLI is unavailable
|
||||
|
||||
Completed reports include:
|
||||
|
||||
- `Topology reviewed`
|
||||
- `Areas reviewed`
|
||||
- `Routing updated`
|
||||
- `Truth docs created`
|
||||
- `Topology decisions`
|
||||
- `Notes`
|
||||
|
||||
## Truth Sync
|
||||
|
||||
Truth Sync is code-first and has two trigger paths:
|
||||
|
||||
- code leads
|
||||
- truth docs follow
|
||||
- functional code must not be rewritten during sync
|
||||
- automatic finish-time trigger when functional code changed since the last successful Truth Sync
|
||||
- explicit trigger when the user invokes `/skill truthmark-sync`, `/truthmark-sync`, or `$truthmark-sync`
|
||||
|
||||
The agent should inspect staged, unstaged, and untracked functional-code changes directly. It should read `.truthmark/config.yml`, [TRUTHMARK.md](../../TRUTHMARK.md), [docs/truthmark/areas.md](../truthmark/areas.md), nearby implementation, and relevant canonical truth docs.
|
||||
|
||||
Committed history, hidden conversation state, host memory, and off-repo notes are not Truth Sync inputs unless the user provides them in the current session and they are verified against the checkout. Truth Sync must not rely on packet helpers, cache files, or generated context artifacts.
|
||||
|
||||
The acting agent and host environment decide whether to delegate Truth Sync to a subagent or execute it inline. Generated workflow surfaces must not name a preferred subagent.
|
||||
|
||||
Truth Sync may update routed truth docs and [docs/truthmark/areas.md](../truthmark/areas.md) when routing repair is needed. It may create missing canonical truth docs when implementation would otherwise remain undocumented and configuration allows missing-truth updates.
|
||||
|
||||
Truth Sync updates active decisions and rationale in the routed canonical doc when implementation changes are driven by a decision change. It may keep a short inline date on the active decision, but it replaces stale active decisions rather than appending separate timestamped decision notes.
|
||||
|
||||
Before updating truth docs, Truth Sync applies a topology quality gate. If changed code maps only through a broad, overloaded, or catch-all route, it should not create another generic feature doc. It should run or recommend Truth Structure first, or block when topology repair is unsafe, ambiguous, or outside the task boundary. Truth Sync must not append behavior details to a feature `README.md`. When no small routed doc exists, it should create or update a bounded leaf truth doc instead.
|
||||
|
||||
Current skip reasons are:
|
||||
|
||||
- documentation-only change
|
||||
- formatting-only change
|
||||
- clearly behavior-preserving rename with no truth impact
|
||||
- no Truthmark config exists yet
|
||||
- no functional code changes
|
||||
|
||||
Completed reports include:
|
||||
|
||||
- `Changed code reviewed`
|
||||
- `Truth docs updated`
|
||||
- `Notes`
|
||||
|
||||
Skipped reports include:
|
||||
|
||||
- `Reason`
|
||||
|
||||
Blocked reports include:
|
||||
|
||||
- `Reason`
|
||||
- `Files requiring manual review`
|
||||
- `Next action`
|
||||
|
||||
## Truth Realize
|
||||
|
||||
Truth Realize is doc-first and manual:
|
||||
|
||||
- truth docs lead
|
||||
- code follows
|
||||
- the agent may write functional code only
|
||||
- the agent must not edit truth docs or truth routing while realizing those docs
|
||||
|
||||
Completion reports include:
|
||||
|
||||
- `Truth docs used`
|
||||
- `Code updated`
|
||||
- `Verification`
|
||||
|
||||
## Truth Check
|
||||
|
||||
Truth Check is an agent-led audit of repository truth health.
|
||||
|
||||
The agent should inspect config, the configured root route index, relevant child route files, canonical docs, and relevant implementation directly. It may optionally run `truthmark check` when local tooling is available, but installed workflows must not depend on the binary being present.
|
||||
|
||||
Completed reports include:
|
||||
|
||||
- `Files reviewed`
|
||||
- `Issues found`
|
||||
- `Fixes suggested`
|
||||
- `Validation`
|
||||
|
||||
## Current Boundary
|
||||
|
||||
Truthmark currently provides installed workflow text, generated Codex and OpenCode-compatible skill surfaces, report renderers, and validation diagnostics. It does not provide autonomous background execution or top-level `truthmark sync`, `truthmark realize`, `truthmark structure`, or `truthmark audit` CLI subcommands.
|
||||
|
||||
## Product Decisions
|
||||
|
||||
- Installed skills and managed agent blocks are the workflow runtime; the CLI installs and validates those surfaces but does not orchestrate Truth Sync itself.
|
||||
- Generated instruction blocks must stay compact, while generated skills may carry detailed workflow bodies and report examples.
|
||||
- Gemini CLI uses generated `.gemini/commands/truthmark/*.toml` files for explicit workflow entrypoints because its native host surface is namespaced custom commands rather than `SKILL.md`.
|
||||
- Generated workflow surfaces must render the configured hierarchy and decision-truth guidance once because those surfaces shape future agent behavior.
|
||||
- Truth Structure owns AI-native topology governance so large repositories do not depend on humans manually organizing `docs/features`.
|
||||
- Truth Structure must satisfy canonical decision-section expectations for both new starter docs and repaired routed docs; `doc-structure` review diagnostics are a signal for topology repair, not only a separate checker concern.
|
||||
- Truth Sync must not worsen weak topology by adding generic feature docs behind broad catch-all routing.
|
||||
- Feature `README.md` files are indexes; bounded leaf docs are the normal Truth Sync targets for current behavior.
|
||||
- Truth Sync delegation is host-owned: generated workflow surfaces may describe when delegation is allowed, but must not name a preferred subagent or project-local subagent preference file.
|
||||
- Active decisions belong in the canonical doc they govern. Short inline decision dates are allowed, but workflow text should reject separate ADR-style drift.
|
||||
- Direct checkout inspection is the workflow authority. `truthmark check` may validate artifacts after or around agent work, but installed workflows must not require a helper payload before acting.
|
||||
- Truthmark follows current host discovery paths for generated skills: Codex uses `.codex/skills/`, OpenCode uses `.opencode/skills/`, and repo-root `skills/` is not a generated V1 target.
|
||||
|
||||
## Rationale
|
||||
|
||||
This keeps installed repositories usable even when the Truthmark package is unavailable at execution time. Keeping host instruction blocks small protects the model context window during ordinary work, while explicit skills remain available when an agent needs the full procedure. Leaving subagent selection to the acting agent and host environment avoids turning repository truth into a runtime preference system. It also keeps the workflow contract aligned with the repo's own truth model, so agents learn where to read and where to write without reconstructing policy from scattered historical notes.
|
||||
|
||||
Rejecting helper-payload dependency preserves the product boundary from the agent-native reshape: Truthmark packages workflow instructions and validation, not a mandatory execution bridge.
|
||||
|
||||
Putting topology governance in installed workflow text keeps the large-repository behavior portable to AI environments that have repository access and agents but do not have the Truthmark binary installed.
|
||||
|
||||
Requiring Truth Structure to add missing decision-section headings keeps repair output aligned with `truthmark check` without weakening the checker's canonical-doc quality signal.
|
||||
|
||||
## Primary Code Files
|
||||
|
||||
- `src/agents/instructions.ts`
|
||||
- `src/agents/truth-structure.ts`
|
||||
- `src/agents/truth-sync.ts`
|
||||
- `src/agents/truth-check.ts`
|
||||
- `src/agents/prompts.ts`
|
||||
- `src/templates/codex-skills.ts`
|
||||
- `src/sync/report.ts`
|
||||
- `src/realize/report.ts`
|
||||
@@ -1,27 +0,0 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: feature
|
||||
last_reviewed: 2026-05-09
|
||||
source_of_truth:
|
||||
- ../../truthmark/areas/repository.md
|
||||
---
|
||||
|
||||
# Repository Overview
|
||||
|
||||
## Scope
|
||||
|
||||
This bounded leaf truth doc owns the default repository behavior surface created by Truthmark.
|
||||
|
||||
## Current Behavior
|
||||
|
||||
- `truthmark init` scaffolds this doc as the default bounded leaf truth doc for the configured default area.
|
||||
- The default scaffold treats feature `README.md` files as indexes and expects current behavior truth to live in bounded leaf docs such as this one.
|
||||
- Downstream repositories are expected to replace this seed content with repository-specific current behavior as the mapped code surface evolves.
|
||||
|
||||
## Product Decisions
|
||||
|
||||
- Decision (2026-05-09): Feature README files are indexes; behavior truth belongs in bounded leaf docs.
|
||||
|
||||
## Rationale
|
||||
|
||||
Bounded leaf docs keep agent context focused and prevent large products from accumulating unreviewable feature manuals.
|
||||
@@ -0,0 +1,76 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: standard
|
||||
last_reviewed: 2026-05-16
|
||||
source_of_truth:
|
||||
- versioning.md
|
||||
- pre-completion-checklist.md
|
||||
---
|
||||
|
||||
# Change Notes
|
||||
|
||||
## Trigger
|
||||
|
||||
Use this standard when a change needs PR text, release text, or a package version decision.
|
||||
|
||||
Required triggers:
|
||||
|
||||
- `package.json` version changes
|
||||
- root package entries in `package-lock.json` change because the package version changed
|
||||
- the user asks for PR, release, changelog, or handoff text
|
||||
- the working change alters published package behavior
|
||||
|
||||
Optional trigger:
|
||||
|
||||
- internal-only maintenance that would benefit from a reusable PR summary
|
||||
|
||||
## Folder
|
||||
|
||||
Write change notes under `changes/`.
|
||||
|
||||
Use one file per cohesive working change:
|
||||
|
||||
```text
|
||||
changes/YYYY-MM-DD-short-slug.md
|
||||
```
|
||||
|
||||
Use dates from the current local session date. Keep slugs short, lowercase, and grep-friendly.
|
||||
|
||||
## Required Shape
|
||||
|
||||
Each change note must use this structure:
|
||||
|
||||
```markdown
|
||||
# Short Change Title
|
||||
|
||||
Version action: none|patch|minor|major
|
||||
|
||||
## PR Summary
|
||||
|
||||
- Concise maintainer-facing summary.
|
||||
|
||||
## Release Note
|
||||
|
||||
- User-facing release text, or `None; internal-only change.`
|
||||
|
||||
## Verification
|
||||
|
||||
- Command run, or skipped check with reason.
|
||||
```
|
||||
|
||||
## Rules
|
||||
|
||||
- `Version action` must match [versioning.md](versioning.md).
|
||||
- If `Version action` is `patch`, `minor`, or `major`, the package version must change in the same working change.
|
||||
- If the package version changes, a matching change note is required because Truthmark releases whenever the package version changes.
|
||||
- Internal-only repository standards may use `Version action: none`.
|
||||
- Release notes describe published package behavior, not private repo maintenance.
|
||||
- Keep notes compact; they are source material for PR and release descriptions, not canonical product truth.
|
||||
|
||||
## Agent Output
|
||||
|
||||
When reporting change-note work, state only:
|
||||
|
||||
- change note path
|
||||
- version action
|
||||
- whether release text is present or intentionally `None`
|
||||
@@ -94,7 +94,7 @@ Truthmark can provide places for those rules to live, but the content should bel
|
||||
When a repository has no explicit standards yet, a small default baseline is reasonable:
|
||||
|
||||
- a documentation governance standard
|
||||
- an authority and routing entrypoint such as `TRUTHMARK.md`
|
||||
- authority and routing entrypoints such as `.truthmark/config.yml` and `docs/truthmark/areas.md`
|
||||
- a verification standard with canonical commands and skip rules
|
||||
- a completion checklist or equivalent completion gate
|
||||
|
||||
|
||||
@@ -44,9 +44,9 @@ Small repositories are in scope. A project does not need a large documentation p
|
||||
Truthmark's minimal canonical surface is:
|
||||
|
||||
- `docs/ai/repo-rules.md` as the repository-wide agent policy source
|
||||
- `TRUTHMARK.md` as the human and agent-readable truth-workflow entrypoint
|
||||
- `.truthmark/config.yml` as the committed hierarchy contract
|
||||
- `docs/truthmark/areas.md` as the primary routing surface
|
||||
- the project's canonical truth docs under directories such as `docs/standards/`, `docs/architecture/`, and `docs/features/`
|
||||
- the project's canonical truth docs under directories such as `docs/standards/`, `docs/architecture/`, and `docs/truth/`
|
||||
|
||||
By default, instruction files such as `AGENTS.md` install workflow behavior. They do not outrank the canonical truth surface unless a project opts into that explicitly.
|
||||
|
||||
@@ -58,10 +58,14 @@ Use a small number of stable document classes:
|
||||
|
||||
- standards for reusable rules and governance
|
||||
- architecture for current structural decisions
|
||||
- features for current feature behavior and invariants
|
||||
- truth docs for current behavior and invariants
|
||||
|
||||
Projects do not need every class on day one. They do need a clear separation between current truth and future proposals.
|
||||
|
||||
Architecture docs describe system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, and generated-surface ownership.
|
||||
|
||||
Architecture docs should not carry ordinary product behavior, endpoint details, UI copy, validation rules, or bug fixes unless those changes alter architecture boundaries. Keep product behavior in behavior or contract docs.
|
||||
|
||||
## Decision-Bearing Truth Docs
|
||||
|
||||
Active decisions are part of current truth. They live in the canonical doc for the feature, contract, architecture surface, or standard they govern.
|
||||
@@ -70,7 +74,7 @@ Use `Product Decisions` and `Rationale` sections for decisions that explain non-
|
||||
|
||||
When a decision changes, replace the old active decision in the same canonical doc. Git history is the historical decision log.
|
||||
|
||||
Short inline dates are allowed on active decisions, for example `Decision (2026-05-09): keep routing agent-native`. The date is context on the active decision, not a separate historical log.
|
||||
Date active decisions inline when added or changed, for example `Decision (2026-05-09): keep routing agent-native`. The date is context on the active decision, not a separate historical log.
|
||||
|
||||
Do not create separate timestamped ADR folders, planning tickets, or historical design notes as the current decision source. Historical notes may remain supplementary only after the active decision is promoted into the canonical doc.
|
||||
|
||||
@@ -80,7 +84,9 @@ Do not create separate timestamped ADR folders, planning tickets, or historical
|
||||
- Major product, onboarding, install, command, positioning, or workflow changes should include a root README review in the same working change. Update the README when its human-facing claims, examples, or command sequences are stale.
|
||||
- When the root README has localized variants, keep them aligned with the English README for materially changed install, command, positioning, and workflow guidance in the same working change, or explicitly document why a variant intentionally differs.
|
||||
- When routing changes, update `docs/truthmark/areas.md` and any affected canonical docs together.
|
||||
- When routing is broad, overloaded, or catch-all, run Truth Structure before adding more generic feature docs.
|
||||
- When routing is missing, stale, broad, overloaded, catch-all, or cannot map changed code to a bounded truth owner, run Truth Structure before adding more generic truth docs.
|
||||
- When a code change alters system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership, update the owning architecture doc in the same change.
|
||||
- Do not update architecture docs for ordinary product behavior unless that behavior changes an architecture boundary.
|
||||
- When a document stops being canonical, supersede or demote it explicitly.
|
||||
- If Truth Sync is skipped, the skip reason should be stated clearly.
|
||||
- If Truth Sync creates missing truth, it should avoid duplicating facts that are already canonical elsewhere.
|
||||
@@ -96,7 +102,7 @@ Do not create separate timestamped ADR folders, planning tickets, or historical
|
||||
- historical planning docs treated as if they were current product truth
|
||||
- generated helper output committed to Git or treated as authority
|
||||
- area mappings that are so broad that agents cannot identify which docs actually matter
|
||||
- generic feature docs created because topology was too broad to resolve a specific behavior owner
|
||||
- generic truth docs created because topology was too broad to resolve a specific behavior owner
|
||||
- current decisions stored only in separate timestamped plans, ADR logs, or draft specs
|
||||
- old and new decisions coexisting as parallel active truth
|
||||
|
||||
@@ -106,7 +112,15 @@ Do not create separate timestamped ADR folders, planning tickets, or historical
|
||||
- Does each class of fact have one canonical source?
|
||||
- Is this fact stored in the correct document class?
|
||||
- Does `docs/truthmark/areas.md` route the changed area to the right truth docs?
|
||||
- If routing is broad or overloaded, has Truth Structure repaired topology before new feature docs were created?
|
||||
- If routing is broad or overloaded, has Truth Structure repaired topology before new truth docs were created?
|
||||
- Are duplicated or shadow documentation paths being avoided?
|
||||
- Is generated helper output still treated as non-authoritative rather than truth?
|
||||
- If historical notes exist, have they stayed clearly separate from the current canonical tree?
|
||||
|
||||
## Product Decisions
|
||||
|
||||
- Decision (2026-05-14): Documentation governance remains a canonical standard doc rather than moving into agent instructions or the root README.
|
||||
|
||||
## Rationale
|
||||
|
||||
Keeping governance in a standard doc preserves one reusable authority for routing, truth-sync, README parity, and decision-bearing doc maintenance without scattering those rules across workflow surfaces.
|
||||
|
||||
@@ -16,9 +16,9 @@ This guide is for humans maintaining Truthmark's own docs tree.
|
||||
|
||||
## When To Update Which Docs
|
||||
|
||||
- Change to scaffolded files or AGENTS management: update [docs/features/init-and-scaffold.md](../features/init-and-scaffold.md)
|
||||
- Change to diagnostics, routing, containment, or branch scope: update [docs/features/check-diagnostics.md](../features/check-diagnostics.md)
|
||||
- Change to installed workflow text, skip reasons, or report shape: update [docs/features/installed-workflows.md](../features/installed-workflows.md)
|
||||
- Change to scaffolded files or AGENTS management: update [docs/truth/init-and-scaffold.md](../truth/init-and-scaffold.md)
|
||||
- Change to diagnostics, routing, containment, or branch scope: update [docs/truth/check-diagnostics.md](../truth/check-diagnostics.md)
|
||||
- Change to installed workflow text, skip reasons, report shape, or ownership gates: update [docs/truth/workflows/overview.md](../truth/workflows/overview.md) and the relevant bounded doc under `docs/truth/workflows/`
|
||||
- Change to repository-wide rules or completion policy: update [docs/ai/repo-rules.md](../ai/repo-rules.md) or the relevant standard
|
||||
|
||||
## Maintaining AGENTS.md
|
||||
@@ -59,7 +59,7 @@ When hierarchy changes:
|
||||
|
||||
When a product or architecture decision changes, edit the `Product Decisions` and `Rationale` sections in the owning canonical doc in the same change as code and routing updates.
|
||||
|
||||
Short inline dates on active decisions are allowed when they help readers understand recency, for example `Decision (2026-05-09): ...`.
|
||||
Date active decisions inline when added or changed, for example `Decision (2026-05-09): ...`.
|
||||
|
||||
Do not preserve the old active decision in a parallel file. Git history preserves it.
|
||||
|
||||
|
||||
@@ -1,10 +1,12 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: standard
|
||||
last_reviewed: 2026-05-09
|
||||
last_reviewed: 2026-05-13
|
||||
source_of_truth:
|
||||
- testing-and-verification.md
|
||||
- documentation-governance.md
|
||||
- versioning.md
|
||||
- change-notes.md
|
||||
---
|
||||
|
||||
# Pre-Completion Checklist
|
||||
@@ -18,8 +20,10 @@ Use this checklist before declaring Truthmark work complete.
|
||||
- Did the change stay within the requested scope?
|
||||
- If behavior, contracts, or workflow text changed, did the nearest canonical docs change in the same working change?
|
||||
- If this was a major product, onboarding, install, command, positioning, or workflow change, did you review the root [README.md](../../README.md) and update stale user-facing claims, examples, or command sequences?
|
||||
- If the root README changed materially, did the localized README variants change in the same working change, or did you explicitly confirm why they remain intentionally different?
|
||||
- If the root README changed materially, did the localized README variants change in the same working change? If not, stop unless you have an explicit repo-authorized reason they intentionally remain different, and state that reason. A passing verification command does not waive this gate.
|
||||
- If canonical routing changed, did [docs/truthmark/areas.md](../truthmark/areas.md) change too?
|
||||
- If the change is PR-worthy, release-worthy, or changes the package version, did you add or update a `changes/` note using [docs/standards/change-notes.md](change-notes.md)?
|
||||
- If any package version or release/version policy changed, did you apply [docs/standards/versioning.md](versioning.md) before accepting the version?
|
||||
- If [AGENTS.md](../../AGENTS.md) changed, did manual edits stay outside the managed Truthmark block?
|
||||
- Did you run the narrowest meaningful verification command from [docs/standards/testing-and-verification.md](testing-and-verification.md)?
|
||||
- If a normally expected verification step was skipped, did you state the reason explicitly?
|
||||
|
||||
@@ -1,10 +1,11 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: standard
|
||||
last_reviewed: 2026-05-09
|
||||
last_reviewed: 2026-05-13
|
||||
source_of_truth:
|
||||
- ../../package.json
|
||||
- ../features/contracts.md
|
||||
- ../truth/contracts.md
|
||||
- versioning.md
|
||||
---
|
||||
|
||||
# Testing And Verification
|
||||
@@ -35,6 +36,8 @@ If a linked `truthmark` binary points at this checkout's `dist/main.js`, `truthm
|
||||
|
||||
- Prefer the narrowest command that can falsify the change.
|
||||
- If a single test file or focused slice exists, run that before broad repo-wide verification.
|
||||
- Tests should prove current supported behavior or contracts.
|
||||
- Do not use the absence of a removed string or removed file as the primary proof of a change unless that absence is itself the boundary under test.
|
||||
- Run `npm run typecheck` when TypeScript source changes.
|
||||
- Run `npm run lint` when adding or changing TypeScript source, tests, or lint configuration.
|
||||
- Run `npm run format:check` when touching package or release-check surfaces covered by the Prettier check.
|
||||
@@ -42,6 +45,7 @@ If a linked `truthmark` binary points at this checkout's `dist/main.js`, `truthm
|
||||
- Run `npm run dev -- check` when canonical docs, authority order, or areas routing changes.
|
||||
- Run `npm run check` before closing out broader code changes unless a narrower command is the only relevant one.
|
||||
- Run `npm run release:check` before publishing or handing off release-sensitive packaging changes.
|
||||
- Run `npm run dev -- init --json`, inspect generated version-marker diffs, and then run `npm run dev -- check` when the package version changes.
|
||||
|
||||
## Documentation-Only Changes
|
||||
|
||||
|
||||
@@ -0,0 +1,83 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: standard
|
||||
last_reviewed: 2026-05-16
|
||||
source_of_truth:
|
||||
- ../../package.json
|
||||
- ../../package-lock.json
|
||||
- change-notes.md
|
||||
- https://semver.org/
|
||||
---
|
||||
|
||||
# Versioning
|
||||
|
||||
## Trigger
|
||||
|
||||
Use this standard only when a task changes or asks whether to change:
|
||||
|
||||
- `package.json` version
|
||||
- root package entries in `package-lock.json`
|
||||
- release/version policy
|
||||
- a `changes/` note with `Version action: patch`, `minor`, or `major`
|
||||
|
||||
Do not load this standard for ordinary docs, workflow text, generated-surface, or code changes unless a package version decision is in scope.
|
||||
|
||||
## Goal
|
||||
|
||||
Choose Truthmark's own package version using Semantic Versioning 2.0.0. Normal committed versions use `MAJOR.MINOR.PATCH`.
|
||||
|
||||
`package.json` is the maintained version source. `package-lock.json` follows it. Generated version markers follow the package version only after `truthmark init` is rerun.
|
||||
|
||||
This is an internal repository maintenance standard. It is not a user-facing feature, installed workflow feature, or generated workflow capability.
|
||||
|
||||
## First Gate
|
||||
|
||||
If the change does not alter published package behavior, do not bump the package version.
|
||||
|
||||
No bump examples:
|
||||
|
||||
- internal standards for this repository
|
||||
- agent routing guidance for maintainers
|
||||
- documentation corrections with no published behavior change
|
||||
- tests, refactors, formatting, or cleanup with no published behavior change
|
||||
|
||||
## Decision Table
|
||||
|
||||
| Change | Version action |
|
||||
| --- | --- |
|
||||
| Backward-incompatible public API or shipped workflow change | `MAJOR + 1`, reset `MINOR` and `PATCH` to `0` |
|
||||
| Backward-compatible public API addition, generated-surface capability, shipped workflow capability, deprecation, or substantial user-visible improvement | `MINOR + 1`, reset `PATCH` to `0` |
|
||||
| Backward-compatible bug fix, diagnostic correction, packaging fix, or published documentation correction | `PATCH + 1` |
|
||||
| Internal-only maintenance with no published package behavior change | no version change |
|
||||
|
||||
Do not use prerelease or build metadata in the committed package version unless the release task explicitly asks for it.
|
||||
|
||||
## Public API For Bump Decisions
|
||||
|
||||
Treat these as published package behavior:
|
||||
|
||||
- CLI command names, options, exit behavior, result envelopes, and diagnostics contracts
|
||||
- `.truthmark/config.yml` schema and hierarchy behavior
|
||||
- generated instruction blocks, skill metadata, prompt files, and version markers produced by the package
|
||||
- installed workflow boundaries, trigger contracts, report shapes, and completion gates as shipped package behavior
|
||||
- runtime compatibility and npm package contents
|
||||
|
||||
## Version Change Procedure
|
||||
|
||||
When changing a version number:
|
||||
|
||||
1. Decide the bump class before editing the version and state the rationale in the handoff, PR, or release note.
|
||||
2. Create or update the matching `changes/` note from [change-notes.md](change-notes.md).
|
||||
3. Update `package.json` and the root package entries in `package-lock.json` together.
|
||||
4. Rerun `truthmark init` only when the package version actually changes, then inspect generated version-marker diffs.
|
||||
5. Run the focused verification required by [testing-and-verification.md](testing-and-verification.md). For release-sensitive package version changes, `npm run release:check` is the default final gate.
|
||||
|
||||
## Agent Output
|
||||
|
||||
When reporting a package version decision, state only:
|
||||
|
||||
- chosen version action
|
||||
- one-line SemVer rationale
|
||||
- files changed or intentionally left unchanged
|
||||
- matching change note path when a version changes
|
||||
- verification run or explicitly skipped
|
||||
Vendored
+58
@@ -0,0 +1,58 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: architecture
|
||||
truth_kind: architecture
|
||||
last_reviewed: 2026-05-14
|
||||
source_of_truth:
|
||||
- {{source_of_truth}}
|
||||
---
|
||||
|
||||
# {{title}}
|
||||
|
||||
## Purpose
|
||||
|
||||
{{purpose}}
|
||||
|
||||
## Scope
|
||||
|
||||
{{scope}}
|
||||
|
||||
## System Role
|
||||
|
||||
{{system_role}}
|
||||
|
||||
## Boundaries
|
||||
|
||||
{{boundaries}}
|
||||
|
||||
## Components
|
||||
|
||||
{{components}}
|
||||
|
||||
## Data And Control Flow
|
||||
|
||||
{{data_and_control_flow}}
|
||||
|
||||
## Ownership
|
||||
|
||||
{{ownership}}
|
||||
|
||||
## Cross-Cutting Constraints
|
||||
|
||||
{{cross_cutting_constraints}}
|
||||
|
||||
## Product Decisions
|
||||
|
||||
{{decision}}
|
||||
|
||||
## Rationale
|
||||
|
||||
{{rationale}}
|
||||
|
||||
## Non-Goals
|
||||
|
||||
{{non_goals}}
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
{{maintenance_notes}}
|
||||
Vendored
+81
@@ -0,0 +1,81 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: behavior
|
||||
truth_kind: behavior
|
||||
last_reviewed: 2026-05-14
|
||||
source_of_truth:
|
||||
- {{source_of_truth}}
|
||||
---
|
||||
|
||||
# {{title}}
|
||||
|
||||
## Purpose
|
||||
|
||||
<!-- State why this behavior exists, the user or system outcome it protects, and the problem it solves. Keep roadmap or implementation plans out of this section. -->
|
||||
|
||||
{{purpose}}
|
||||
|
||||
## Scope
|
||||
|
||||
{{scope}}
|
||||
|
||||
<!--
|
||||
This doc must own one coherent behavior surface.
|
||||
Split into another leaf doc when content introduces:
|
||||
- a distinct user or system outcome
|
||||
- a separate lifecycle or state machine
|
||||
- an unrelated rule family
|
||||
- a different external contract
|
||||
- code that should route through a different owner
|
||||
Keep README.md files as indexes only.
|
||||
-->
|
||||
|
||||
This doc was created from the editable behavior-doc template at {{template_path}}.
|
||||
|
||||
## Current Behavior
|
||||
|
||||
<!-- Describe implemented behavior in present tense. Do not include desired future behavior. -->
|
||||
|
||||
{{current_behavior}}
|
||||
|
||||
## Core Rules
|
||||
|
||||
<!-- Capture stable business rules, invariants, precedence rules, validation rules, and must-never constraints. Omit incidental implementation details. -->
|
||||
|
||||
{{core_rules}}
|
||||
|
||||
## Flows And States
|
||||
|
||||
<!-- Use for route switches, state transitions, lifecycle stages, retries, fallbacks, and important error paths. Write 'None beyond current behavior.' when no distinct flow or state model exists. -->
|
||||
|
||||
{{flows_and_states}}
|
||||
|
||||
## Contracts
|
||||
|
||||
<!-- Capture user-visible or integration contracts: CLI/API shape, inputs, outputs, diagnostics, files, events, permissions, or links to canonical contract docs. Avoid duplicating a separate canonical contract doc. -->
|
||||
|
||||
{{contracts}}
|
||||
|
||||
## Product Decisions
|
||||
|
||||
<!-- Keep active decisions only. Replace stale decisions instead of appending historical logs. -->
|
||||
|
||||
{{decision}}
|
||||
|
||||
## Rationale
|
||||
|
||||
<!-- Explain why the current behavior and active decisions are this way, including tradeoffs. -->
|
||||
|
||||
{{rationale}}
|
||||
|
||||
## Non-Goals
|
||||
|
||||
<!-- Name adjacent behavior this doc intentionally does not own, especially tempting future expansions. -->
|
||||
|
||||
{{non_goals}}
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
<!-- List related tests, routing cautions, migration notes, and common drift risks for future agents. Keep this operational, not historical. -->
|
||||
|
||||
{{maintenance_notes}}
|
||||
Vendored
+58
@@ -0,0 +1,58 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: contract
|
||||
truth_kind: contract
|
||||
last_reviewed: 2026-05-14
|
||||
source_of_truth:
|
||||
- {{source_of_truth}}
|
||||
---
|
||||
|
||||
# {{title}}
|
||||
|
||||
## Purpose
|
||||
|
||||
{{purpose}}
|
||||
|
||||
## Scope
|
||||
|
||||
{{scope}}
|
||||
|
||||
## Contract Surface
|
||||
|
||||
{{contract_surface}}
|
||||
|
||||
## Inputs
|
||||
|
||||
{{inputs}}
|
||||
|
||||
## Outputs
|
||||
|
||||
{{outputs}}
|
||||
|
||||
## Errors And Diagnostics
|
||||
|
||||
{{errors_and_diagnostics}}
|
||||
|
||||
## Compatibility Rules
|
||||
|
||||
{{compatibility_rules}}
|
||||
|
||||
## Versioning And Migration
|
||||
|
||||
{{versioning_and_migration}}
|
||||
|
||||
## Product Decisions
|
||||
|
||||
{{decision}}
|
||||
|
||||
## Rationale
|
||||
|
||||
{{rationale}}
|
||||
|
||||
## Non-Goals
|
||||
|
||||
{{non_goals}}
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
{{maintenance_notes}}
|
||||
Vendored
+58
@@ -0,0 +1,58 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: behavior
|
||||
truth_kind: operations
|
||||
last_reviewed: 2026-05-14
|
||||
source_of_truth:
|
||||
- {{source_of_truth}}
|
||||
---
|
||||
|
||||
# {{title}}
|
||||
|
||||
## Purpose
|
||||
|
||||
{{purpose}}
|
||||
|
||||
## Scope
|
||||
|
||||
{{scope}}
|
||||
|
||||
## Operational Surface
|
||||
|
||||
{{operational_surface}}
|
||||
|
||||
## Runtime Topology
|
||||
|
||||
{{runtime_topology}}
|
||||
|
||||
## Configuration
|
||||
|
||||
{{configuration}}
|
||||
|
||||
## Permissions
|
||||
|
||||
{{permissions}}
|
||||
|
||||
## Deployment And Rollback
|
||||
|
||||
{{deployment_and_rollback}}
|
||||
|
||||
## Availability And Observability
|
||||
|
||||
{{availability_and_observability}}
|
||||
|
||||
## Product Decisions
|
||||
|
||||
{{decision}}
|
||||
|
||||
## Rationale
|
||||
|
||||
{{rationale}}
|
||||
|
||||
## Non-Goals
|
||||
|
||||
{{non_goals}}
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
{{maintenance_notes}}
|
||||
Vendored
+58
@@ -0,0 +1,58 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: behavior
|
||||
truth_kind: test-behavior
|
||||
last_reviewed: 2026-05-14
|
||||
source_of_truth:
|
||||
- {{source_of_truth}}
|
||||
---
|
||||
|
||||
# {{title}}
|
||||
|
||||
## Purpose
|
||||
|
||||
{{purpose}}
|
||||
|
||||
## Scope
|
||||
|
||||
{{scope}}
|
||||
|
||||
## Test Surface
|
||||
|
||||
{{test_surface}}
|
||||
|
||||
## Fixtures And Data Model
|
||||
|
||||
{{fixtures_and_data_model}}
|
||||
|
||||
## Execution Model
|
||||
|
||||
{{execution_model}}
|
||||
|
||||
## Assertions And Invariants
|
||||
|
||||
{{assertions_and_invariants}}
|
||||
|
||||
## Isolation Rules
|
||||
|
||||
{{isolation_rules}}
|
||||
|
||||
## Reporting And Failure Semantics
|
||||
|
||||
{{reporting_and_failure_semantics}}
|
||||
|
||||
## Product Decisions
|
||||
|
||||
{{decision}}
|
||||
|
||||
## Rationale
|
||||
|
||||
{{rationale}}
|
||||
|
||||
## Non-Goals
|
||||
|
||||
{{non_goals}}
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
{{maintenance_notes}}
|
||||
Vendored
+58
@@ -0,0 +1,58 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: behavior
|
||||
truth_kind: workflow
|
||||
last_reviewed: 2026-05-14
|
||||
source_of_truth:
|
||||
- {{source_of_truth}}
|
||||
---
|
||||
|
||||
# {{title}}
|
||||
|
||||
## Purpose
|
||||
|
||||
{{purpose}}
|
||||
|
||||
## Scope
|
||||
|
||||
{{scope}}
|
||||
|
||||
## Triggers
|
||||
|
||||
{{triggers}}
|
||||
|
||||
## Inputs
|
||||
|
||||
{{inputs}}
|
||||
|
||||
## Execution Model
|
||||
|
||||
{{execution_model}}
|
||||
|
||||
## Steps
|
||||
|
||||
{{steps}}
|
||||
|
||||
## State, Retry, And Failure Behavior
|
||||
|
||||
{{state_retry_and_failure_behavior}}
|
||||
|
||||
## Outputs
|
||||
|
||||
{{outputs}}
|
||||
|
||||
## Product Decisions
|
||||
|
||||
{{decision}}
|
||||
|
||||
## Rationale
|
||||
|
||||
{{rationale}}
|
||||
|
||||
## Non-Goals
|
||||
|
||||
{{non_goals}}
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
{{maintenance_notes}}
|
||||
@@ -6,8 +6,8 @@ source_of_truth:
|
||||
- ../truthmark/areas.md
|
||||
---
|
||||
|
||||
# Feature Docs
|
||||
# Truth Docs
|
||||
|
||||
This directory contains current feature behavior docs organized by the configured Truthmark hierarchy.
|
||||
This directory contains current truth docs organized by the configured Truthmark hierarchy.
|
||||
|
||||
`README.md` files in this tree are indexes. Keep current behavior truth in bounded leaf docs under domain folders such as `repository/overview.md`.
|
||||
@@ -1,13 +1,19 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: feature
|
||||
last_reviewed: 2026-05-09
|
||||
doc_type: behavior
|
||||
truth_kind: behavior
|
||||
last_reviewed: 2026-05-14
|
||||
source_of_truth:
|
||||
- ../../src/checks/check.ts
|
||||
- ../../src/checks/authority.ts
|
||||
- ../../src/checks/areas.ts
|
||||
- ../../src/checks/branch-scope.ts
|
||||
- ../../src/freshness/check.ts
|
||||
- ../../src/impact/build.ts
|
||||
- ../../src/evidence/validate.ts
|
||||
- ../../src/checks/frontmatter.ts
|
||||
- ../../src/checks/links.ts
|
||||
- ../../src/markdown/discovery.ts
|
||||
---
|
||||
|
||||
# Check Diagnostics
|
||||
@@ -26,12 +32,15 @@ The command:
|
||||
2. computes branch-scope metadata
|
||||
3. loads `.truthmark/config.yml`
|
||||
4. runs authority, area, decision-structure, frontmatter, internal-link, generated-surface, and coverage diagnostics when config is valid
|
||||
5. returns a human summary or the shared JSON envelope
|
||||
5. when `--base <ref>` is supplied, builds an ImpactSet and adds freshness diagnostics for changed code without route ownership, stale evidence, invalid base comparisons, and changed public API without docs sync
|
||||
6. returns a human summary or the shared JSON envelope
|
||||
|
||||
There is no supported `--workflow` helper mode. Agent workflows inspect the checkout directly and may run `truthmark check` only as optional validation.
|
||||
|
||||
The command reports repository truth health for the active checkout. It does not prepare mandatory workflow context, choose verification commands, or decide whether a coding task can finish.
|
||||
|
||||
`truthmark check` without `--base` keeps the existing checkout-health behavior and does not compute ImpactSet. `truthmark check --base <ref>` adds branch-impact freshness diagnostics and includes `data.impactSet` in JSON output.
|
||||
|
||||
Topology repair remains an installed workflow responsibility. `truthmark check` may expose routing or coverage symptoms, but AI agents must be able to perform Truth Structure directly from committed config, route files, docs, and implementation when the Truthmark binary is unavailable.
|
||||
|
||||
## Validation Passes
|
||||
@@ -58,11 +67,14 @@ Each resolved leaf area must define:
|
||||
- `Code surface`
|
||||
- `Update truth when`
|
||||
|
||||
`Truth documents` may be expressed either as a legacy Markdown list of document paths or as a fenced YAML block with a `truth_documents` array of `{ path, kind }` entries. Explicit route metadata is authoritative and owns the section, so legacy list lines in the same section are ignored. Legacy lists fall back to path-based kind inference such as the configured truth root, `docs/truth/** -> behavior`, `docs/contracts/**` or `docs/api/** -> contract`, `docs/architecture/** -> architecture`, `docs/workflows/** -> workflow`, `docs/operations/** -> operations`, and `docs/testing/** -> test-behavior`. When an explicit route entry is a glob, Truthmark expands it to concrete truth document entries before frontmatter and doc-structure checks so the routed kind applies to every matched file.
|
||||
|
||||
Current severity behavior:
|
||||
|
||||
- malformed or incomplete root or child area block: `error`
|
||||
- missing truth document: `error`
|
||||
- out-of-repository truth document or code surface: `error`
|
||||
- conflicting routed kinds for the same truth document path: `error`
|
||||
- child route file outside the configured area-files root: `error`
|
||||
- nested delegation inside a child route file: `error`
|
||||
- duplicate resolved leaf area key: `error`
|
||||
@@ -113,6 +125,8 @@ Current severity behavior:
|
||||
|
||||
- invalid frontmatter: `error`
|
||||
- missing configured required field: `error`
|
||||
- invalid `truth_kind`: `error`
|
||||
- present `truth_kind` that disagrees with routed truth kind metadata: `error`
|
||||
- missing configured recommended field: `review`
|
||||
|
||||
### Internal Links
|
||||
@@ -126,12 +140,19 @@ Current severity behavior:
|
||||
|
||||
### Decision Structure
|
||||
|
||||
Decision-structure checks review configured architecture and current feature docs that are part of the routed truth surface.
|
||||
Decision-structure checks review configured architecture docs and routed truth docs that are part of the current truth surface.
|
||||
|
||||
Current severity behavior:
|
||||
|
||||
- canonical doc missing `Scope`: `review`
|
||||
- canonical doc missing active `Product Decisions`: `review`
|
||||
- canonical doc missing active `Rationale`: `review`
|
||||
- behavior doc missing `Current Behavior`: `review`
|
||||
- contract doc missing `Contract Surface` or all contract-detail sections: `review`
|
||||
- architecture doc missing both `Boundaries` and `Components`: `review`
|
||||
- workflow doc missing `Triggers` or `Execution Model`: `review`
|
||||
- operations doc missing both `Runtime Topology` and `Configuration`: `review`
|
||||
- test-behavior doc missing `Execution Model` or both `Fixtures And Data Model` and `Assertions And Invariants`: `review`
|
||||
|
||||
### Generated Surfaces
|
||||
|
||||
@@ -145,12 +166,29 @@ Current severity behavior:
|
||||
- configured generated surface content stale: `review`
|
||||
- generated Truthmark version marker differs from the current package version: `review`
|
||||
|
||||
### Freshness
|
||||
|
||||
Freshness checks run only when `--base <ref>` is supplied.
|
||||
|
||||
Current severity behavior:
|
||||
|
||||
- changed functional code with no route owner: `review`
|
||||
- changed public API with no affected truth document: `review`
|
||||
- changed public API with affected truth docs that were not changed in the impact set: `review`
|
||||
- invalid base ref or failed base comparison: `error`
|
||||
- deleted `source_of_truth` or evidence reference: `error`
|
||||
- `source_of_truth` glob reference with no matching files: `error`
|
||||
- evidence reference outside the repository root: `error`
|
||||
- missing evidence symbol, invalid evidence span, or stale evidence hash: `error`
|
||||
- evidence line spans are validated even when the evidence block does not include a content hash
|
||||
|
||||
## Result Shape
|
||||
|
||||
- human output reports the number of `error` and `review` diagnostics
|
||||
- JSON output returns the shared command envelope
|
||||
- JSON output includes `data.branchScope`
|
||||
- JSON output includes `data.truthVisibility`
|
||||
- JSON output includes `data.impactSet` only when `--base <ref>` is supplied
|
||||
- JSON output does not include workflow payloads
|
||||
|
||||
Branch scope identifies the active checkout:
|
||||
@@ -158,6 +196,7 @@ Branch scope identifies the active checkout:
|
||||
- normal branches use branch name plus HEAD SHA
|
||||
- detached checkouts use the commit SHA
|
||||
- worktree path is reported separately for parallel worktrees
|
||||
- relevant file hashes track `.truthmark/config.yml`, the configured root route index, and configured child route files
|
||||
|
||||
## Practical Meaning
|
||||
|
||||
@@ -167,10 +206,11 @@ Branch scope identifies the active checkout:
|
||||
## Product Decisions
|
||||
|
||||
- `truthmark check` validates current truth health, but installed workflows remain agent-led and do not depend on the binary.
|
||||
- Area resolution follows the configured hierarchy contract instead of assuming a flat `docs/features/*.md` world.
|
||||
- Area resolution follows the configured hierarchy contract instead of assuming a flat current-behavior-doc tree.
|
||||
- Decision-bearing canonical docs are part of truth health because missing rationale weakens future reconstruction.
|
||||
- Topology pressure is handled by Truth Structure rather than by asking teams to manually maintain feature-folder shape.
|
||||
- Topology pressure is handled by Truth Structure rather than by asking teams to manually maintain truth-folder shape.
|
||||
- Branch-scope data is advisory metadata for the current checkout; it is not a cache, packet, or off-repo memory layer.
|
||||
- Decision (2026-05-13): Branch-scope hashes follow the committed config and route files rather than a separate root workflow note.
|
||||
|
||||
## Rationale
|
||||
|
||||
@@ -1,21 +1,36 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: feature
|
||||
last_reviewed: 2026-05-09
|
||||
doc_type: contract
|
||||
truth_kind: contract
|
||||
last_reviewed: 2026-05-16
|
||||
source_of_truth:
|
||||
- ../../src/config/schema.ts
|
||||
- ../../src/checks/check.ts
|
||||
- ../../src/templates/init-files.ts
|
||||
- ../../src/templates/generated-surfaces.ts
|
||||
- ../../src/init/init.ts
|
||||
- ../../src/output/diagnostic.ts
|
||||
- ../../src/output/render.ts
|
||||
- ../../src/cli/handlers.ts
|
||||
---
|
||||
|
||||
# Contracts
|
||||
|
||||
## Scope
|
||||
|
||||
This document defines the current machine-facing contracts exposed by Truthmark: the config file shape and the CLI result envelope.
|
||||
This document defines the current machine-facing contracts exposed by Truthmark: the config file shape, route metadata, repository-intelligence artifacts, and the CLI result envelope.
|
||||
|
||||
## Contract Surface
|
||||
|
||||
- The committed `.truthmark/config.yml` schema and defaults.
|
||||
- Route metadata under `docs/truthmark/areas.md` and delegated child route files.
|
||||
- The JSON result envelope emitted by `truthmark config`, `truthmark init`, `truthmark check`, `truthmark index`, `truthmark impact`, and `truthmark context`.
|
||||
|
||||
## Inputs
|
||||
|
||||
- Committed config fields under `.truthmark/config.yml`.
|
||||
- Routed truth-document metadata from `docs/truthmark/areas.md` and `docs/truthmark/areas/**/*.md`.
|
||||
- CLI options such as `--json`, `--stdout`, and command-specific flags.
|
||||
|
||||
## Config Contract
|
||||
|
||||
@@ -24,9 +39,9 @@ Truthmark loads `.truthmark/config.yml` and validates it against the current sch
|
||||
Current fields:
|
||||
|
||||
- `version`: must be `1`
|
||||
- `platforms`: optional list of agent harnesses to initialize; defaults to `codex`, `opencode`, and `claude-code`
|
||||
- `platforms`: optional list of agent harnesses to initialize; defaults to all supported platforms
|
||||
- `docs.layout`: currently `hierarchical`
|
||||
- `docs.roots`: named canonical doc roots
|
||||
- `docs.roots`: named canonical doc roots; omitted root names are filled from current defaults
|
||||
- `docs.routing.root_index`: root area index path
|
||||
- `docs.routing.area_files_root`: child area route directory
|
||||
- `docs.routing.default_area`: default child route file basename used by scaffold
|
||||
@@ -36,24 +51,43 @@ Current fields:
|
||||
- `frontmatter.required`: frontmatter fields that produce `error` diagnostics when missing
|
||||
- `frontmatter.recommended`: frontmatter fields that produce `review` diagnostics when missing
|
||||
- `ignore`: glob patterns excluded from relevant checks and routing logic
|
||||
- `realization.enabled`: whether doc-first realization is enabled
|
||||
|
||||
The default scaffolded authority list includes:
|
||||
|
||||
- `TRUTHMARK.md`
|
||||
- `docs/truthmark/areas.md`
|
||||
- `docs/truthmark/areas/**/*.md`
|
||||
- `docs/ai/**/*.md`
|
||||
- `docs/standards/**/*.md`
|
||||
- `docs/architecture/**/*.md`
|
||||
- `docs/features/**/*.md`
|
||||
- `docs/truth/**/*.md`
|
||||
|
||||
## Route Metadata Contract
|
||||
|
||||
Route files may express `Truth documents` in either of these forms:
|
||||
|
||||
- a legacy Markdown list of document paths
|
||||
- a fenced YAML block with a `truth_documents` array of `{ path, kind }` entries
|
||||
|
||||
New scaffolded child route files use the fenced YAML form so routed truth kind is explicit from the first generated route. The legacy list form remains a compatibility input for existing repositories.
|
||||
|
||||
Supported routed truth kinds are:
|
||||
|
||||
- `behavior`
|
||||
- `contract`
|
||||
- `architecture`
|
||||
- `workflow`
|
||||
- `operations`
|
||||
- `test-behavior`
|
||||
|
||||
When explicit `kind` metadata is present, it is the authoritative routed kind and the fenced metadata block owns the `Truth documents` section. Legacy list lines in the same section are ignored. When route files use the legacy list form, Truthmark falls back to path-based kind inference such as `<configured truth root>/**` or `docs/truth/** -> behavior`, `docs/contracts/**` or `docs/api/** -> contract`, `docs/architecture/** -> architecture`, `docs/workflows/** -> workflow`, `docs/operations/** -> operations`, and `docs/testing/** -> test-behavior`.
|
||||
|
||||
Canonical truth docs may include optional `truth_kind` frontmatter. When present, it must match the routed kind.
|
||||
|
||||
Supported `platforms` values are:
|
||||
|
||||
- `codex`
|
||||
- `opencode`
|
||||
- `claude-code`
|
||||
- `cursor`
|
||||
- `github-copilot`
|
||||
- `gemini-cli`
|
||||
|
||||
@@ -72,7 +106,7 @@ Current shape:
|
||||
|
||||
Diagnostic fields:
|
||||
|
||||
- `category`: one of `config`, `authority`, `frontmatter`, `links`, `area-index`, `coverage`, `truth-sync`, `realization`, `doc-structure`, or `generated-surface`
|
||||
- `category`: one of `config`, `authority`, `frontmatter`, `links`, `area-index`, `coverage`, `truth-sync`, `realization`, `doc-structure`, `generated-surface`, `repo-index`, `impact`, `freshness`, or `context-pack`
|
||||
- `severity`: one of `info`, `action`, `review`, or `error`
|
||||
- `message`: human-readable detail
|
||||
- `file`: optional repository-relative file path
|
||||
@@ -81,6 +115,22 @@ Diagnostic fields:
|
||||
|
||||
Human-rendered output is intended for people. JSON output is the machine-facing contract.
|
||||
|
||||
`truthmark index --json` returns `data.repoIndex` with `schemaVersion: repo-index/v0` and `data.routeMap` with `schemaVersion: route-map/v0`.
|
||||
|
||||
`truthmark impact --base <ref> --json` returns `data.impactSet` with `schemaVersion: impact-set/v0`.
|
||||
|
||||
`truthmark context --workflow <workflow> [--base <ref>] --json` returns `data.contextPack` with `schemaVersion: context-pack/v0`. `--workflow` accepts `truth-sync`, `truth-document`, and `truth-realize`. `--format` accepts `json` or `markdown`; unsupported formats return a `context-pack` error diagnostic. `--format markdown` renders a deterministic Markdown ContextPack for human review, and `--json --format markdown` includes that Markdown under `data.markdown`.
|
||||
|
||||
RepoIndex, RouteMap, ImpactSet, and ContextPack are derived from the active checkout. They do not override route files, source files, truth docs, or installed workflow write boundaries.
|
||||
|
||||
## Compatibility Rules
|
||||
|
||||
- `version` remains `1` in the committed config contract.
|
||||
- `docs.roots.truth` is the configured root for behavior truth docs.
|
||||
- Repositories refresh generated workflow surfaces through `truthmark init`; removing a platform from config stops future refreshes but does not delete previously generated files.
|
||||
- Truth Realize has no config switch; selected platforms receive its explicit manual workflow surface.
|
||||
- There is no `.truthmark/local.yml` compatibility surface in the current implementation.
|
||||
|
||||
## Config Result Data
|
||||
|
||||
`truthmark config --json` writes only `.truthmark/config.yml` unless `--stdout` is used.
|
||||
@@ -113,33 +163,46 @@ The command emits `action` diagnostics describing whether each scaffolded file w
|
||||
`truthmark init` requires an existing valid `.truthmark/config.yml`. It does not create config; `truthmark config` is the required first step in a new repository.
|
||||
Configured `instruction_targets` are generated or refreshed independently of platform-specific surfaces, so `AGENTS.md` remains managed even when `claude-code` is not in `platforms`.
|
||||
|
||||
Generated Truth Structure, Truth Sync, and Truth Check surfaces and the managed `AGENTS.md` block use the `truth-sync` diagnostic category.
|
||||
Generated Truth Structure, Truth Document, Truth Sync, and Truth Check surfaces and the managed `AGENTS.md` block use the `truth-sync` diagnostic category.
|
||||
|
||||
Current agent-native scaffold targets include:
|
||||
|
||||
- `.codex/skills/truthmark-structure/SKILL.md`
|
||||
- `.codex/skills/truthmark-structure/agents/openai.yaml`
|
||||
- `.codex/skills/truthmark-document/SKILL.md`
|
||||
- `.codex/skills/truthmark-document/agents/openai.yaml`
|
||||
- `.codex/skills/truthmark-sync/SKILL.md`
|
||||
- `.codex/skills/truthmark-sync/agents/openai.yaml`
|
||||
- `.codex/skills/truthmark-realize/SKILL.md`
|
||||
- `.codex/skills/truthmark-realize/agents/openai.yaml`
|
||||
- `.codex/skills/truthmark-check/SKILL.md`
|
||||
- `.codex/skills/truthmark-check/agents/openai.yaml`
|
||||
- `.claude/skills/truthmark-structure/SKILL.md`
|
||||
- `.claude/skills/truthmark-document/SKILL.md`
|
||||
- `.claude/skills/truthmark-sync/SKILL.md`
|
||||
- `.claude/skills/truthmark-realize/SKILL.md`
|
||||
- `.claude/skills/truthmark-check/SKILL.md`
|
||||
- `.opencode/skills/truthmark-structure/SKILL.md`
|
||||
- `.opencode/skills/truthmark-document/SKILL.md`
|
||||
- `.opencode/skills/truthmark-sync/SKILL.md`
|
||||
- `.opencode/skills/truthmark-realize/SKILL.md`
|
||||
- `.opencode/skills/truthmark-check/SKILL.md`
|
||||
- `AGENTS.md`
|
||||
- `CLAUDE.md`
|
||||
- `.cursor/rules/truthmark.mdc`
|
||||
- `.github/copilot-instructions.md`
|
||||
- `.github/prompts/truthmark-structure.prompt.md`
|
||||
- `.github/prompts/truthmark-document.prompt.md`
|
||||
- `.github/prompts/truthmark-sync.prompt.md`
|
||||
- `.github/prompts/truthmark-realize.prompt.md`
|
||||
- `.github/prompts/truthmark-check.prompt.md`
|
||||
- `GEMINI.md`
|
||||
- `.gemini/commands/truthmark/structure.toml`
|
||||
- `.gemini/commands/truthmark/document.toml`
|
||||
- `.gemini/commands/truthmark/sync.toml`
|
||||
- `.gemini/commands/truthmark/realize.toml`
|
||||
- `.gemini/commands/truthmark/check.toml`
|
||||
|
||||
Generated `SKILL.md` files use closed YAML frontmatter with `name`, `description`, `argument-hint`, `user-invocable`, and `truthmark-version` fields so Codex-style skill indexers can parse every generated workflow surface. Generated Codex metadata includes a `truthmark.version` marker plus `truthmark.refresh_command: "truthmark init"`. Managed instruction blocks and `TRUTHMARK.md` also render the Truthmark package version, and `package.json` is the single maintained version source for those markers. Generated Gemini command files use project-scoped TOML custom commands so `truthmark init` can install `/truthmark:structure`, `/truthmark:sync`, `/truthmark:realize`, and `/truthmark:check` alongside `GEMINI.md`. Re-running `truthmark init` after a package upgrade refreshes configured committed surfaces and exposes staleness through ordinary Git diffs. Removing a platform from config stops future refreshes for that platform; it does not delete previously generated files.
|
||||
Generated `SKILL.md` files use closed YAML frontmatter with `name`, `description`, `argument-hint`, `user-invocable`, and `truthmark-version` fields so Codex-style, Claude Code, and OpenCode-style skill indexers can parse every generated workflow surface. Generated Copilot prompt files use `.github/prompts/*.prompt.md` files with `agent` and `description` frontmatter so supported Copilot IDEs can expose `/truthmark-*` prompts. Generated Codex metadata includes a `truthmark.version` marker plus `truthmark.refresh_command: "truthmark init"`. Managed instruction blocks also render the Truthmark package version, and `package.json` is the single maintained version source for those markers. Generated Gemini command files use project-scoped TOML custom commands so `truthmark init` can install `/truthmark:structure`, `/truthmark:document`, `/truthmark:sync`, `/truthmark:realize`, and `/truthmark:check` alongside `GEMINI.md`. Re-running `truthmark init` after a package upgrade refreshes configured committed surfaces and exposes staleness through ordinary Git diffs. Removing a platform from config stops future refreshes for that platform; it does not delete previously generated files.
|
||||
|
||||
## Check Result Data
|
||||
|
||||
@@ -162,7 +225,6 @@ For normal branches, `identity` is branch name plus HEAD SHA. For detached check
|
||||
`relevantFileHashes` currently tracks hashes for:
|
||||
|
||||
- `.truthmark/config.yml`
|
||||
- `TRUTHMARK.md`
|
||||
- the configured root route index
|
||||
- configured child route files under the configured area-files root
|
||||
|
||||
@@ -183,18 +245,20 @@ For normal branches, `identity` is branch name plus HEAD SHA. For detached check
|
||||
- Missing authority files are `error` diagnostics.
|
||||
- Authority globs and code-surface globs that match nothing are `review` diagnostics.
|
||||
- Coverage diagnostics discover unmapped functional code across common code roots with the same path classifier used by Truth Sync. V1 coverage must include Go, Python, C#, Java, JavaScript, TypeScript, frontend roots, monorepo app or package roots, Terraform, Kubernetes manifests, CI workflows, OpenAPI or Swagger, GraphQL, and protobuf surfaces within those roots.
|
||||
- `doc-structure` emits `review` diagnostics when configured architecture or current feature docs are missing active `Product Decisions` or `Rationale` sections.
|
||||
- `frontmatter` emits `error` diagnostics when `truth_kind` is invalid or present and disagrees with routed truth-kind metadata.
|
||||
- `doc-structure` emits `review` diagnostics when configured architecture or routed truth docs are missing `Scope`, active `Product Decisions`, active `Rationale`, or the kind-specific required headings for their routed truth kind.
|
||||
|
||||
## Product Decisions
|
||||
|
||||
- The committed config file owns the documentation hierarchy contract, while route files own domain-to-doc mappings.
|
||||
- `truthmark config` and `truthmark init` are separate contracts so repositories can review hierarchy before workflow installation.
|
||||
- Active decisions stay in the canonical doc they govern instead of in separate timestamped decision logs. Short inline decision dates are allowed on the active decision itself.
|
||||
- The V1 user-facing CLI surface is limited to `config`, `init`, and `check`; workflow verbs such as `sync`, `realize`, `structure`, `audit`, `packet`, `review`, `scan`, `doctor`, `build`, and `context` are not top-level commands.
|
||||
- Active decisions stay in the canonical doc they govern instead of in separate timestamped decision logs. Date active decisions inline when added or changed.
|
||||
- The V1 user-facing CLI surface is `config`, `init`, `check`, `index`, `impact`, and `context`; workflow verbs such as `sync`, `realize`, `structure`, `audit`, `packet`, `review`, `scan`, `doctor`, and `build` are not top-level commands.
|
||||
- `gemini-cli` installs both hierarchical `GEMINI.md` context and project-scoped `.gemini/commands/truthmark/*.toml` custom commands so Gemini users get the same explicit workflow entrypoints without adding top-level CLI verbs.
|
||||
- Decision (2026-05-14): Truth Realize is manually invoked through installed workflow surfaces and is not controlled by `realization.enabled` or any other config key.
|
||||
|
||||
## Rationale
|
||||
|
||||
Separating config from init keeps repository layout reviewable and predictable. Keeping decisions with the owning feature, contract, or architecture doc prevents agents from having to infer which historical note is still active.
|
||||
Separating config from init keeps repository layout reviewable and predictable. Keeping decisions with the owning behavior, contract, or architecture doc prevents agents from having to infer which historical note is still active.
|
||||
|
||||
Keeping workflow verbs out of the CLI preserves the agent-native model: installed skills and instruction blocks run the workflows, while the CLI installs and validates repository artifacts.
|
||||
@@ -0,0 +1,197 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: behavior
|
||||
truth_kind: behavior
|
||||
last_reviewed: 2026-05-14
|
||||
source_of_truth:
|
||||
- ../../src/config/defaults.ts
|
||||
- ../../src/fs/paths.ts
|
||||
- ../../src/init/init.ts
|
||||
- ../../src/init/hierarchy.ts
|
||||
- ../../src/templates/init-files.ts
|
||||
- ../../src/templates/agents-block.ts
|
||||
- ../../src/templates/codex-skills.ts
|
||||
- ../../src/templates/generated-surfaces.ts
|
||||
---
|
||||
|
||||
# Init And Scaffold
|
||||
|
||||
## Scope
|
||||
|
||||
This document describes the current behavior of `truthmark config` and `truthmark init`.
|
||||
|
||||
## Current Behavior
|
||||
|
||||
`truthmark config` is the required first step in a new repository. It writes only `.truthmark/config.yml` unless `--stdout` is used.
|
||||
|
||||
`truthmark init` operates on the active Git worktree and does all of the following in one pass:
|
||||
|
||||
1. resolves the active repository and worktree
|
||||
2. requires an existing valid `.truthmark/config.yml`
|
||||
3. creates default standards only when they are missing or empty
|
||||
4. creates missing configured docs and routing structure such as the configured root route index, the configured default child route file with explicit truth kind metadata when the root route index delegates it, the configured truth-root README, a default area index README, six editable typed truth-doc templates, and a default bounded behavior truth doc
|
||||
5. loads the configured `platforms` list
|
||||
6. writes or refreshes configured instruction targets and configured platform surfaces
|
||||
7. rewrites managed Truthmark instruction blocks while preserving manual content outside those blocks
|
||||
8. writes generated skill surfaces for configured skill-based platforms
|
||||
9. reports migration risks instead of moving existing truth docs when hierarchy changes imply manual migration
|
||||
10. reports each touched file as `created`, `updated`, or `unchanged`
|
||||
|
||||
## Scaffolded Files
|
||||
|
||||
Current scaffold targets:
|
||||
|
||||
- `.truthmark/config.yml` via `truthmark config`
|
||||
- [docs/truthmark/areas.md](../truthmark/areas.md)
|
||||
- configured child route files referenced by the root route index under `docs/truthmark/areas/**/*.md`
|
||||
- configured truth-root README files such as `docs/truth/README.md`
|
||||
- configured default-area index README files such as `docs/truth/repository/README.md`
|
||||
- [docs/templates/behavior-doc.md](../templates/behavior-doc.md)
|
||||
- [docs/templates/contract-doc.md](../templates/contract-doc.md)
|
||||
- [docs/templates/architecture-doc.md](../templates/architecture-doc.md)
|
||||
- [docs/templates/workflow-doc.md](../templates/workflow-doc.md)
|
||||
- [docs/templates/operations-doc.md](../templates/operations-doc.md)
|
||||
- [docs/templates/test-behavior-doc.md](../templates/test-behavior-doc.md)
|
||||
- configured default-area bounded leaf truth docs such as `docs/truth/repository/overview.md`
|
||||
- [docs/standards/default-principles.md](../standards/default-principles.md)
|
||||
- [docs/standards/documentation-governance.md](../standards/documentation-governance.md)
|
||||
- the managed block inside [AGENTS.md](../../AGENTS.md)
|
||||
- [CLAUDE.md](../../CLAUDE.md)
|
||||
- `.codex/skills/truthmark-structure/SKILL.md`
|
||||
- `.codex/skills/truthmark-structure/agents/openai.yaml`
|
||||
- `.codex/skills/truthmark-document/SKILL.md`
|
||||
- `.codex/skills/truthmark-document/agents/openai.yaml`
|
||||
- `.codex/skills/truthmark-sync/SKILL.md`
|
||||
- `.codex/skills/truthmark-sync/agents/openai.yaml`
|
||||
- `.codex/skills/truthmark-realize/SKILL.md`
|
||||
- `.codex/skills/truthmark-realize/agents/openai.yaml`
|
||||
- `.codex/skills/truthmark-check/SKILL.md`
|
||||
- `.codex/skills/truthmark-check/agents/openai.yaml`
|
||||
- `.opencode/skills/truthmark-structure/SKILL.md`
|
||||
- `.opencode/skills/truthmark-document/SKILL.md`
|
||||
- `.opencode/skills/truthmark-sync/SKILL.md`
|
||||
- `.opencode/skills/truthmark-realize/SKILL.md`
|
||||
- `.opencode/skills/truthmark-check/SKILL.md`
|
||||
- `.claude/skills/truthmark-structure/SKILL.md`
|
||||
- `.claude/skills/truthmark-document/SKILL.md`
|
||||
- `.claude/skills/truthmark-sync/SKILL.md`
|
||||
- `.claude/skills/truthmark-realize/SKILL.md`
|
||||
- `.claude/skills/truthmark-check/SKILL.md`
|
||||
- `.github/copilot-instructions.md`
|
||||
- `.github/prompts/truthmark-structure.prompt.md`
|
||||
- `.github/prompts/truthmark-document.prompt.md`
|
||||
- `.github/prompts/truthmark-sync.prompt.md`
|
||||
- `.github/prompts/truthmark-realize.prompt.md`
|
||||
- `.github/prompts/truthmark-check.prompt.md`
|
||||
- `GEMINI.md`
|
||||
- `.gemini/commands/truthmark/structure.toml`
|
||||
- `.gemini/commands/truthmark/document.toml`
|
||||
- `.gemini/commands/truthmark/sync.toml`
|
||||
- `.gemini/commands/truthmark/realize.toml`
|
||||
- `.gemini/commands/truthmark/check.toml`
|
||||
|
||||
`instruction_targets` controls shared managed-instruction files such as `AGENTS.md`. These targets are written or refreshed whenever `truthmark init` runs with a valid config, independent of the configured platform list.
|
||||
`platforms` controls which platform-specific surfaces are written or refreshed. Defaults include all supported platforms: `codex`, `opencode`, `claude-code`, `github-copilot`, and `gemini-cli`. Teams should remove unused platforms from `.truthmark/config.yml` before rerunning `truthmark init`. Claude Code installs both `CLAUDE.md` and project skills under `.claude/skills/`, which surface as `/truthmark-structure`, `/truthmark-document`, `/truthmark-sync`, `/truthmark-realize`, and `/truthmark-check`. GitHub Copilot installs both `.github/copilot-instructions.md` and prompt files under `.github/prompts/`, which surface as `/truthmark-structure`, `/truthmark-document`, `/truthmark-sync`, `/truthmark-realize`, and `/truthmark-check` in supported Copilot IDEs. Gemini installs both `GEMINI.md` and project-scoped TOML commands under `.gemini/commands/truthmark/`, which surface as `/truthmark:structure`, `/truthmark:document`, `/truthmark:sync`, `/truthmark:realize`, and `/truthmark:check` in Gemini CLI. Unknown platform names are config errors. Removing a platform stops future refreshes for that platform, but `init` does not delete previously generated files.
|
||||
|
||||
`ensureRepoFile` is intentionally conservative: existing non-empty files are left alone. The AGENTS managed block is the exception because Truthmark owns that block and may refresh it to match current template behavior.
|
||||
|
||||
The generated Truth Structure, Truth Document, Truth Sync, Truth Realize, and Truth Check explicit surfaces are also managed by Truthmark and may be refreshed on rerun so the Codex skills, metadata, Claude Code project skills, GitHub Copilot prompt files, and OpenCode skills keep matching the installed workflow contract. Generated skills, Codex metadata, Copilot prompt files, and managed instruction blocks include the Truthmark package version that rendered them; `package.json` is the single maintained version source. After upgrading Truthmark, rerun `truthmark init` and review generated workflow diffs.
|
||||
|
||||
## AGENTS Management Rules
|
||||
|
||||
The current managed-instruction update behavior is:
|
||||
|
||||
- replace an existing managed Truthmark block when it is well formed
|
||||
- remove older managed-looking chunks when possible
|
||||
- preserve manual text outside the managed block
|
||||
- normalize the known legacy `Codex` preamble wording to host-neutral agent wording when refreshing an instruction file
|
||||
- normalize legacy unconditional docs-map and onboarding preamble lines to conditional reads so normal sessions do not load routing docs before they are needed
|
||||
- append the managed block when no block exists
|
||||
- keep the generated workflow block as a compact automatic-Sync trigger and boundary index so it does not consume unnecessary model context in long legacy instruction files
|
||||
- keep detailed report examples, platform-specific invocation strings, and long workflow procedure in explicit generated skill files instead of host instruction blocks
|
||||
- preserve repository instruction authority while clarifying that implementation code and canonical truth docs are behavior evidence, not a way to override workflow write boundaries
|
||||
|
||||
Repository-specific instructions should therefore live outside the managed block.
|
||||
|
||||
Truthmark does not create `OPENCODE.md` in V1. OpenCode-compatible behavior is installed through shared `AGENTS.md` guidance and project skill files under `.opencode/skills/`.
|
||||
|
||||
## Hierarchy Behavior
|
||||
|
||||
Hierarchy is configured in `.truthmark/config.yml`:
|
||||
|
||||
- `docs.layout` is currently `hierarchical`
|
||||
- `docs.roots` names the canonical doc roots and partial root maps are merged over current defaults
|
||||
- `docs.routing.root_index` is the root route index path
|
||||
- `docs.routing.area_files_root` is the directory for child route files
|
||||
- `docs.routing.default_area` is the initial scaffolded child route basename
|
||||
- `docs.routing.max_delegation_depth` must currently be `1`
|
||||
|
||||
`truthmark init` creates missing structure for that hierarchy, but child route files stay governed by the root route index: if an authored non-empty root index no longer delegates the configured default child route, rerunning init does not recreate that unreferenced child route. Init does not silently move, delete, or reinterpret existing truth docs when teams change the configured roots. Those cases produce review diagnostics for manual migration.
|
||||
The default scaffold treats truth `README.md` files as indexes. Current behavior truth belongs in bounded leaf docs under the configured truth root, such as `<truth-root>/<domain>/<behavior>.md`.
|
||||
`truthmark init` creates [docs/templates/behavior-doc.md](../templates/behavior-doc.md) when it is missing or empty and also seeds [docs/templates/contract-doc.md](../templates/contract-doc.md), [docs/templates/architecture-doc.md](../templates/architecture-doc.md), [docs/templates/workflow-doc.md](../templates/workflow-doc.md), [docs/templates/operations-doc.md](../templates/operations-doc.md), and [docs/templates/test-behavior-doc.md](../templates/test-behavior-doc.md) when they are missing or empty. The default behavior template includes Purpose, Scope, Current Behavior, Core Rules, Flows And States, Contracts, Product Decisions, Rationale, Non-Goals, and Maintenance Notes sections, with inline scope criteria for agents. Kind-specific templates add the required anchors for contract, architecture, workflow, operations, and test-behavior truth surfaces. The default child route references the seeded leaf truth doc with fenced YAML `truth_documents` metadata and `kind: behavior` rather than relying on path inference.
|
||||
When creating the default bounded behavior truth doc, init reads the repository's behavior template and expands supported placeholders such as `{{title}}`, `{{area}}`, `{{source_of_truth}}`, `{{purpose}}`, `{{scope}}`, `{{current_behavior}}`, `{{core_rules}}`, `{{flows_and_states}}`, `{{contracts}}`, `{{decision}}`, `{{rationale}}`, `{{non_goals}}`, `{{maintenance_notes}}`, and `{{template_path}}`. The seeded leaf uses `doc_type: behavior` and `truth_kind: behavior`. Existing non-empty template files are preserved so teams can define local truth-doc standards.
|
||||
|
||||
## Current Defaults
|
||||
|
||||
Important current defaults:
|
||||
|
||||
- default authority includes the canonical doc classes under `docs/`
|
||||
- default code surface in the scaffolded root and child route files starts as `src/**`
|
||||
- default truth scaffolding creates an index at `<truth-root>/README.md`, an index at `<truth-root>/<default-area>/README.md`, six editable templates under `docs/templates/*.md`, and a bounded leaf truth doc at `<truth-root>/<default-area>/overview.md` routed through explicit `{ path, kind }` metadata
|
||||
- default platforms are `codex`, `opencode`, `claude-code`, `github-copilot`, and `gemini-cli`
|
||||
- shared instruction targets are refreshed independently of platform-specific surfaces
|
||||
- explicit Truth Structure, Truth Document, Truth Sync, Truth Realize, and Truth Check surfaces are installed only for configured platforms
|
||||
- installed workflows are agent-native; generated skills tell agents to inspect the checkout directly
|
||||
- generated workflow surfaces leave Truth Sync subagent selection to the acting agent and host environment
|
||||
- managed instruction blocks include only compact hierarchy, decision-truth, automatic-Sync trigger, boundary reminders, and a pointer to explicit workflows; generated skills carry invocation strings and detailed workflow bodies
|
||||
- generated workflow surfaces must not demote repository instruction docs such as [docs/ai/repo-rules.md](../ai/repo-rules.md) when warning agents that product truth cannot override workflow write boundaries
|
||||
- scaffolded default standards include AI-native topology repair guidance and an architecture-vs-behavior boundary so new repositories do not rely on human folder discipline
|
||||
- Truth Sync is the only generated skill with implicit invocation enabled because it is the automatic finish-time workflow
|
||||
- `truthmark check` is optional validation for agent workflows, not a required workflow preflight
|
||||
- Truth Realize is always installed as an explicit manual surface for configured platforms; it has no separate config toggle and no dedicated CLI subcommand
|
||||
- Gemini CLI support uses `GEMINI.md` for hierarchical memory and `.gemini/commands/truthmark/*.toml` for explicit workflow commands instead of introducing Truthmark-specific top-level CLI verbs
|
||||
|
||||
## Init Diagnostics
|
||||
|
||||
Current init JSON reporting uses:
|
||||
|
||||
- `truth-sync` for the managed `AGENTS.md` block and generated Truth Structure, Truth Document, Truth Sync, and Truth Check assets
|
||||
- `realization` for generated Truth Realize assets
|
||||
- `authority` for [docs/truthmark/areas.md](../truthmark/areas.md)
|
||||
- `config` for the remaining scaffolded files
|
||||
|
||||
## Invariants
|
||||
|
||||
- all generated paths must remain inside the active repository root
|
||||
- generated path containment must reject symlinks that resolve outside the repository, including broken symlink leaves that would otherwise be created outside the worktree
|
||||
- init must be idempotent for existing non-empty scaffold files except for the managed AGENTS block
|
||||
- the command should remain safe to run repeatedly in the same repository
|
||||
|
||||
## Product Decisions
|
||||
|
||||
- `truthmark config` owns the committed layout contract and must happen before `truthmark init`.
|
||||
- Hierarchical routing is the only scaffold model, and route ownership stays in Markdown route files rather than config.
|
||||
- Init reports migration risk instead of rewriting existing truth doc placement on the user's behalf.
|
||||
- V1 uses configured shared instruction targets such as `AGENTS.md` plus generated skill or command surfaces for host compatibility instead of creating host-specific top-level instruction files for every adapter.
|
||||
- Managed instruction blocks are compact automatic-Sync indexes; generated skills and command files own explicit workflow procedure.
|
||||
- Decision (2026-05-15): Repository instruction preambles make docs-map and onboarding reads conditional, and managed instruction blocks omit platform-specific workflow invocation strings so ordinary sessions load less context.
|
||||
- Decision (2026-05-13): `.truthmark/config.yml` and route files are the committed hierarchy contract, so init no longer creates a low-value top-level note.
|
||||
- Decision (2026-05-14): Truth-doc templates are kind-specific under `docs/templates/*.md`; `docs/templates/behavior-doc.md` is the default bounded behavior template and the other five typed templates carry kind-specific required sections.
|
||||
- Decision (2026-05-14): Truth Realize stays manual-only through explicit generated surfaces and is no longer configurable with `realization.enabled`.
|
||||
- Decision (2026-05-13): Default standards define architecture docs as structure and ownership truth, not a place for ordinary product behavior.
|
||||
|
||||
## Rationale
|
||||
|
||||
This split makes the hierarchy reviewable before generated workflow behavior lands in the repo. Keeping route ownership in Markdown preserves local editing ergonomics. Refusing silent migrations avoids accidental truth loss when a repository reshapes its canonical docs tree.
|
||||
|
||||
Keeping host-specific detail in generated skills and Gemini command files prevents the repository root from accumulating parallel instruction files that drift from the managed workflow contract. Keeping managed blocks terse protects ordinary agent context while preserving the automatic Sync gate, workflow boundaries, and branch-local authority. Conditional docs-map and onboarding reads keep routing guidance available without forcing every normal session to load it.
|
||||
|
||||
Keeping typed truth-doc templates in `docs/templates/` gives repository owners one local standard surface per truth kind while keeping generated workflow text compact as more workflow surfaces are added.
|
||||
|
||||
## Primary Code Files
|
||||
|
||||
- `src/init/init.ts`
|
||||
- `src/templates/init-files.ts`
|
||||
- `src/templates/agents-block.ts`
|
||||
- `src/templates/codex-skills.ts`
|
||||
- `src/fs/paths.ts`
|
||||
@@ -0,0 +1,17 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: index
|
||||
last_reviewed: 2026-05-13
|
||||
source_of_truth:
|
||||
- ../../truthmark/areas/release-automation.md
|
||||
---
|
||||
|
||||
# Release Truth Docs
|
||||
|
||||
This directory indexes bounded release and automation truth docs.
|
||||
|
||||
README.md files are indexes, not Truth Sync targets. Keep behavior truth in bounded leaf docs in this directory.
|
||||
|
||||
Current leaf docs:
|
||||
|
||||
- [Automation](automation.md)
|
||||
@@ -0,0 +1,87 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: behavior
|
||||
truth_kind: workflow
|
||||
last_reviewed: 2026-05-14
|
||||
source_of_truth:
|
||||
- ../../truthmark/areas/release-automation.md
|
||||
- ../../../.github/workflows/ci.yml
|
||||
- ../../../.github/workflows/publish.yml
|
||||
---
|
||||
|
||||
# Release Automation
|
||||
|
||||
## Purpose
|
||||
|
||||
This doc owns the repository automation that verifies Truthmark changes in pull requests and publishes the package from GitHub releases.
|
||||
|
||||
## Scope
|
||||
|
||||
This doc covers the committed GitHub Actions workflows under `.github/workflows/`. It does not redefine the `truthmark` CLI contracts or the detailed behavior of `check`, `init`, or installed workflows.
|
||||
|
||||
## Triggers
|
||||
|
||||
- Pushes to `main`
|
||||
- Pull requests
|
||||
- Published GitHub releases
|
||||
|
||||
## Inputs
|
||||
|
||||
- The checked-out repository contents
|
||||
- GitHub Actions event context for pushes, pull requests, and releases
|
||||
- npm registry credentials and release-environment configuration for publishing
|
||||
|
||||
## Execution Model
|
||||
|
||||
Release automation runs through the committed GitHub Actions workflows under `.github/workflows/`. The `CI` workflow verifies repository changes, and the `Publish` workflow revalidates release state before publishing to npm.
|
||||
|
||||
The repository also ships `examples/github-actions/truthmark-impact.yml` as a consumer example. It is not a release workflow for this repository. The example shows a non-blocking PR mode that comments with `truthmark impact --base` and `truthmark check --base` results, uploads the JSON reports, and a blocking mode controlled by `TRUTHMARK_BLOCKING`.
|
||||
|
||||
## Steps
|
||||
|
||||
- The `CI` workflow runs on pushes to `main` and on every pull request.
|
||||
- The `verify` job checks out the repository, installs Node 24 with npm caching, runs `npm ci`, then runs `npm run check` and `npm run package:check`.
|
||||
- The `Publish` workflow runs when a GitHub release is published.
|
||||
- The `publish` job checks out the repository, installs Node 24 with the npm registry configured, runs `npm ci`, runs `npm run release:check`, and then runs `npm publish`.
|
||||
|
||||
## State, Retry, And Failure Behavior
|
||||
|
||||
- Failed verification or release-check steps stop the current job and prevent later publish steps from running.
|
||||
- Publishing occurs only for the GitHub release event path; branch pushes and pull requests do not publish.
|
||||
- GitHub Actions reruns remain host-managed; Truthmark owns the committed workflow definitions, not GitHub's execution controls.
|
||||
- The example ImpactSet workflow is intentionally opt-in and consumer-copied; it does not run unless a repository installs it.
|
||||
|
||||
## Outputs
|
||||
|
||||
- CI verification results for pushes and pull requests
|
||||
- npm publication after a successful release-triggered publish job
|
||||
|
||||
## Core Rules
|
||||
|
||||
- Pull request and main-branch automation must verify linting, types, tests, build output, and package-file integrity through the existing npm scripts.
|
||||
- Publish automation must re-run the full release verification before publishing.
|
||||
- Publishing is triggered from a GitHub release event, not from branch pushes alone.
|
||||
|
||||
## Contracts
|
||||
|
||||
- Both workflows currently run on `ubuntu-latest`.
|
||||
- Both workflows install Node 24 through `actions/setup-node@v4`.
|
||||
- The publish workflow requires npm registry access through the configured GitHub Actions environment.
|
||||
|
||||
## Product Decisions
|
||||
|
||||
- Decision (2026-05-13): Repository automation stays script-driven and reuses committed npm verification commands instead of duplicating verification logic inline in GitHub Actions.
|
||||
|
||||
## Rationale
|
||||
|
||||
Keeping workflow steps thin makes repository automation follow the same verification contract developers run locally. That reduces drift between local validation, CI validation, and release publishing.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- This doc does not own release-note authoring or GitHub release drafting policy.
|
||||
- This doc does not define npm package contents beyond invoking the existing package checks.
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
- Update this doc when workflow triggers, Node versions, or verification commands change.
|
||||
- Keep this doc aligned with `package.json` scripts used by the workflows.
|
||||
@@ -1,14 +1,14 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: index
|
||||
last_reviewed: 2026-05-09
|
||||
last_reviewed: 2026-05-13
|
||||
source_of_truth:
|
||||
- ../../truthmark/areas/repository.md
|
||||
- ../../truthmark/areas/init-and-scaffold.md
|
||||
---
|
||||
|
||||
# Repository Feature Docs
|
||||
# Repository Truth Docs
|
||||
|
||||
This directory indexes bounded repository feature truth docs.
|
||||
This directory indexes bounded repository truth docs.
|
||||
|
||||
README.md files are indexes, not Truth Sync targets. Keep behavior truth in bounded leaf docs in this directory.
|
||||
|
||||
@@ -0,0 +1,51 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: behavior
|
||||
truth_kind: behavior
|
||||
last_reviewed: 2026-05-16
|
||||
source_of_truth:
|
||||
- ../../../src/context-pack/build.ts
|
||||
- ../../../src/context-pack/render.ts
|
||||
- ../../../src/impact/build.ts
|
||||
---
|
||||
|
||||
# ContextPack
|
||||
|
||||
## Scope
|
||||
|
||||
This document owns ContextPack v0 behavior for Truth Sync, Truth Document, and Truth Realize workflows.
|
||||
|
||||
## Current Behavior
|
||||
|
||||
`truthmark context --workflow <workflow> [--base <ref>] --json` generates a bounded context artifact for a workflow. `--format markdown` renders a deterministic human-readable pack, and `--json --format markdown` includes the rendered Markdown in `data.markdown`. ContextPack rejects unsupported `--format` values with a `context-pack` error diagnostic. ContextPack includes route ownership, affected truth docs, selected source files, related tests, warnings, and allowed write paths.
|
||||
|
||||
ContextPack output includes `schemaVersion: context-pack/v0`. It is generated from the active checkout and, when a base ref is supplied, ImpactSet.
|
||||
|
||||
## Core Rules
|
||||
|
||||
- ContextPack is optional generated context and does not replace direct checkout inspection.
|
||||
- ContextPack write paths restate workflow boundaries; they do not create new permissions.
|
||||
- Truth Sync and Truth Document write paths include the route index and selected truth docs. Truth Realize write paths include the matched route code surfaces because Realize may write functional code but not truth docs or routing.
|
||||
- Truth Realize without `--base` cannot infer matched code surfaces, so selected truth docs, source files, and `allowedWritePaths` are empty and ContextPack emits a review warning instead of widening to every route.
|
||||
- Source files include changed files from ImpactSet when a base ref is supplied and `source_of_truth` references from selected truth docs. Glob references are expanded against the checkout.
|
||||
- ContextPack-only text is not evidence. Generated docs must cite checkout files, route files, truth docs, tests, schemas, or explicit evidence blocks.
|
||||
- If ContextPack conflicts with the current checkout, the checkout wins.
|
||||
|
||||
## Runtime Dependency Boundary
|
||||
|
||||
ContextPack requires the Truthmark CLI or an equivalent local runner. If unavailable, agents must follow the installed workflow manually by reading route files, truth docs, source files, and tests directly. Completion reports must say ContextPack was not generated.
|
||||
|
||||
## Product Decisions
|
||||
|
||||
- Decision (2026-05-16): ContextPack v0 is a bounded review artifact, not memory and not a source of authority.
|
||||
- Decision (2026-05-16): No-CLI workflow execution remains supported, but with weaker automation and explicit reporting.
|
||||
|
||||
## Rationale
|
||||
|
||||
ContextPack makes agent context auditable without making hidden retrieval or stale generated artifacts authoritative. Keeping it derived prevents a fast path from changing ownership or write behavior.
|
||||
|
||||
## Primary Code Files
|
||||
|
||||
- `src/context-pack/build.ts`
|
||||
- `src/context-pack/render.ts`
|
||||
- `src/impact/build.ts`
|
||||
@@ -0,0 +1,55 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: behavior
|
||||
truth_kind: behavior
|
||||
last_reviewed: 2026-05-16
|
||||
source_of_truth:
|
||||
- ../../../src/impact/build.ts
|
||||
- ../../../src/impact/git-diff.ts
|
||||
- ../../../src/repo-index/build.ts
|
||||
---
|
||||
|
||||
# ImpactSet
|
||||
|
||||
## Scope
|
||||
|
||||
This document owns ImpactSet v0 behavior. ImpactSet maps Git changes to Truthmark routes, truth docs, owning areas, related tests, and public symbol changes.
|
||||
|
||||
## Current Behavior
|
||||
|
||||
`truthmark impact --base <ref> --json` compares the active checkout to the supplied base ref and returns `schemaVersion: impact-set/v0`. The command combines Git diff data with RepoIndex and RouteMap data.
|
||||
|
||||
ImpactSet reports changed files, affected routes, affected truth docs, affected tests, changed public symbols, and diagnostics. It includes staged, unstaged, and untracked worktree changes so local agent work can be evaluated before commit.
|
||||
|
||||
## Core Rules
|
||||
|
||||
- Changed functional code is mapped through `Code surface` entries in Truthmark route files.
|
||||
- Changed routed truth docs are mapped back to their owning routes and included in `affectedTruthDocs`.
|
||||
- Renamed files preserve `previousPath`, map both old and new paths to route ownership, and report moved exports as removed from the old path and added at the new path.
|
||||
- Changed test files are reported as affected tests instead of missing truth-route diagnostics.
|
||||
- Related tests are selected from direct imports, basename hints, and package-level test path conventions.
|
||||
- Public symbol changes are computed from JavaScript/TypeScript exports in v0.
|
||||
- Missing or invalid base refs produce an `impact` error diagnostic instead of silently returning an empty comparison.
|
||||
- Changed public symbols produce review diagnostics when no affected truth doc exists or when affected truth docs exist but were not changed in the impact set.
|
||||
- ImpactSet is derived. It does not grant write permission and does not replace route ownership.
|
||||
|
||||
## Runtime Dependency Boundary
|
||||
|
||||
ImpactSet requires the Truthmark CLI or an equivalent local runner. If unavailable, agents must inspect Git changes and route ownership directly. The workflow may proceed manually, but completion reports must say ImpactSet was not generated.
|
||||
|
||||
If an ImpactSet conflicts with the current checkout, agents must trust the checkout and rerun or ignore the artifact.
|
||||
|
||||
## Product Decisions
|
||||
|
||||
- Decision (2026-05-16): ImpactSet v0 uses Git plus route ownership as the review boundary instead of a background cache.
|
||||
- Decision (2026-05-16): Public API impact starts with JavaScript and TypeScript exports because this repository's first implementation stack is TypeScript.
|
||||
|
||||
## Rationale
|
||||
|
||||
ImpactSet gives Truth Sync and CI a stable, reviewable way to explain what code changed and which truth surfaces are affected without making a model decide ownership.
|
||||
|
||||
## Primary Code Files
|
||||
|
||||
- `src/impact/build.ts`
|
||||
- `src/impact/git-diff.ts`
|
||||
- `src/repo-index/build.ts`
|
||||
@@ -0,0 +1,60 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: behavior
|
||||
truth_kind: behavior
|
||||
last_reviewed: 2026-05-14
|
||||
source_of_truth:
|
||||
- ../../truthmark/areas/init-and-scaffold.md
|
||||
- ../../../src/init/init.ts
|
||||
- ../../../src/templates/init-files.ts
|
||||
---
|
||||
|
||||
# Repository Overview
|
||||
|
||||
## Purpose
|
||||
|
||||
This doc owns the default bounded behavior leaf that `truthmark init` scaffolds for repositories using the default `repository` area.
|
||||
|
||||
## Scope
|
||||
|
||||
This doc covers the seed `docs/truth/repository/overview.md` behavior only. Broader init flow, routing files, and generated workflow surfaces stay in the main scaffold and workflow docs.
|
||||
|
||||
## Current Behavior
|
||||
|
||||
- `truthmark init` creates `docs/truth/repository/overview.md` as the default bounded behavior truth doc for the configured default area.
|
||||
- The scaffold pairs this leaf doc with a sibling `README.md` index under `docs/truth/repository/`.
|
||||
- The generated content is starter truth. Repositories are expected to replace it with repository-specific current behavior as their mapped code surface evolves.
|
||||
|
||||
## Core Rules
|
||||
|
||||
- Truth `README.md` files are indexes, not current-behavior targets.
|
||||
- The default scaffold keeps behavior truth in bounded leaf docs under the configured truth root.
|
||||
- The seeded repository leaf stays intentionally small so later Truth Sync runs can replace it instead of appending to an index file.
|
||||
|
||||
## Flows And States
|
||||
|
||||
- `truthmark init` creates the truth root index, the default area index, and this bounded leaf when those files are missing.
|
||||
- Later repository work may update or replace the seeded leaf doc without changing the scaffold contract.
|
||||
|
||||
## Contracts
|
||||
|
||||
- The default leaf path is `docs/truth/<default-area>/overview.md` when the configured truth root is `docs/truth` and the default area is `repository`.
|
||||
- The editable content standard for this leaf comes from `docs/templates/behavior-doc.md`.
|
||||
|
||||
## Product Decisions
|
||||
|
||||
- Decision (2026-05-14): The default scaffold seeds a bounded behavior truth doc instead of placing current behavior in a truth `README.md`.
|
||||
|
||||
## Rationale
|
||||
|
||||
Bounded seed docs give new repositories an immediately routeable truth target while keeping index files stable and small.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- This doc does not own the full `truthmark init` workflow.
|
||||
- This doc does not define repository-specific behavior after downstream teams rewrite the seed content.
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
- Keep this doc aligned with `docs/templates/behavior-doc.md` when the behavior-doc standard changes.
|
||||
- Update this doc when the default area leaf path or seeded content rules change.
|
||||
@@ -0,0 +1,55 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: behavior
|
||||
truth_kind: behavior
|
||||
last_reviewed: 2026-05-16
|
||||
source_of_truth:
|
||||
- ../../../src/repo-index/build.ts
|
||||
- ../../../src/repo-index/file-tree.ts
|
||||
- ../../../src/repo-index/route-map.ts
|
||||
- ../../../src/repo-index/types.ts
|
||||
---
|
||||
|
||||
# RepoIndex
|
||||
|
||||
## Scope
|
||||
|
||||
This document owns RepoIndex v0 and RouteMap v0 behavior. RepoIndex describes the current checkout's files, docs, packages, tests, JavaScript/TypeScript imports and exports, public symbols, and Truthmark route ownership.
|
||||
|
||||
## Current Behavior
|
||||
|
||||
`truthmark index --json` builds a deterministic repository index from the active checkout. The command reads local files and Git metadata only. It does not start a daemon, call a remote service, use a model, or write generated artifacts by default.
|
||||
|
||||
RepoIndex output includes `schemaVersion: repo-index/v0`. RouteMap output includes `schemaVersion: route-map/v0` and is derived from `.truthmark/config.yml`, `docs/truthmark/areas.md`, and `docs/truthmark/areas/**/*.md`.
|
||||
|
||||
## Core Rules
|
||||
|
||||
- Paths are repository-relative POSIX paths.
|
||||
- Arrays are sorted lexicographically unless source order is part of the contract.
|
||||
- File discovery honors Git ignore rules through `git ls-files --exclude-standard` and then applies Truthmark config ignores, so ignored local artifacts are not indexed.
|
||||
- Symbol extraction v0 covers JavaScript and TypeScript source files.
|
||||
- Managed agent Markdown surfaces such as `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, and Copilot instructions are classified as generated files rather than ordinary docs.
|
||||
- Route ownership comes from Truthmark area files, not from package structure or import graphs.
|
||||
- RepoIndex and RouteMap are derived artifacts. They speed up routing and review, but they do not override source files, route files, or truth docs.
|
||||
|
||||
## Runtime Dependency Boundary
|
||||
|
||||
RepoIndex requires the Truthmark CLI or an equivalent local runner to compute. If the CLI is unavailable, agents must inspect `.truthmark/config.yml`, route files, changed source files, and routed truth docs directly. Workflows may proceed manually, but completion reports must say RepoIndex and RouteMap were not generated.
|
||||
|
||||
If a RepoIndex or RouteMap artifact conflicts with the current checkout, the checkout wins. Agents must rerun the CLI when available or ignore the stale artifact when it cannot be regenerated.
|
||||
|
||||
## Product Decisions
|
||||
|
||||
- Decision (2026-05-16): RepoIndex v0 is a local deterministic acceleration layer, not a source of truth.
|
||||
- Decision (2026-05-16): RouteMap v0 is aligned to `docs/truthmark/areas.md` instead of introducing a parallel ownership schema.
|
||||
|
||||
## Rationale
|
||||
|
||||
Keeping repository intelligence derived preserves Truthmark's branch-local review boundary. Teams can use fast machine-readable context when the CLI is available without making installed workflows unusable in constrained agent environments.
|
||||
|
||||
## Primary Code Files
|
||||
|
||||
- `src/repo-index/build.ts`
|
||||
- `src/repo-index/file-tree.ts`
|
||||
- `src/repo-index/route-map.ts`
|
||||
- `src/repo-index/types.ts`
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: feature
|
||||
doc_type: behavior
|
||||
truth_kind: behavior
|
||||
last_reviewed: 2026-05-09
|
||||
source_of_truth:
|
||||
- ../../src/checks/areas.ts
|
||||
@@ -12,11 +13,20 @@ source_of_truth:
|
||||
|
||||
This document gives examples for designing explicit Truthmark areas in larger repositories. The examples are patterns, not required folder names.
|
||||
|
||||
## Scope
|
||||
|
||||
This doc covers example routing patterns for larger repositories so agents and maintainers can split route ownership by behavior rather than by broad directory mirroring.
|
||||
|
||||
## Current Behavior
|
||||
|
||||
- Truthmark treats frontend, API schema, workflow, infrastructure, and monorepo service paths as functional surfaces when they change production behavior, contracts, or operational ownership.
|
||||
- Route design should produce bounded truth owners that map changed code to a small set of canonical docs.
|
||||
|
||||
## Express, Nest, And Fastify
|
||||
|
||||
Large Node API apps should route by product behavior rather than by framework layer. For example, route `src/modules/billing/**`, `src/routes/billing/**`, or `apps/api/src/billing/**` to a billing truth doc instead of routing all controllers through `src/**`.
|
||||
|
||||
API schema files are functional surfaces when they define behavior or contracts. Route `api/openapi.yaml`, `schema/**/*.graphql`, and `proto/**/*.proto` to the nearest contract or feature truth doc.
|
||||
API schema files are functional surfaces when they define behavior or contracts. Route `api/openapi.yaml`, `schema/**/*.graphql`, and `proto/**/*.proto` to the nearest contract or behavior truth doc.
|
||||
|
||||
## Frontend Apps
|
||||
|
||||
@@ -0,0 +1,55 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: behavior
|
||||
truth_kind: workflow
|
||||
last_reviewed: 2026-05-15
|
||||
source_of_truth:
|
||||
- ../../../src/generation/**
|
||||
---
|
||||
|
||||
# Workflow Content Generation
|
||||
|
||||
## Purpose
|
||||
|
||||
Content-generation prompt contracts shape draft truth-doc updates without becoming workflow authority.
|
||||
|
||||
## Scope
|
||||
|
||||
This document owns source-internal draft prompt contracts used by Truthmark workflow code.
|
||||
|
||||
## Triggers
|
||||
|
||||
- renderer or schema changes under `src/generation/**`
|
||||
|
||||
## Inputs
|
||||
|
||||
- JSON-backed evidence context
|
||||
- structured output schemas
|
||||
- workflow-authorized target docs
|
||||
|
||||
## Execution Model
|
||||
|
||||
Workflow prompts grant permissions and set write boundaries. Content-generation prompt contracts may render evidence context and validate structured draft output, but they do not grant permission to write files or replace direct checkout inspection.
|
||||
|
||||
Generated draft content remains advisory until a workflow-authorized agent applies it to canonical docs.
|
||||
|
||||
## Current Behavior
|
||||
|
||||
Truthmark keeps content-generation contracts separate from installed workflow authority. Agents still inspect the checkout directly and use installed workflow surfaces for permissions, boundaries, and reporting.
|
||||
|
||||
## Product Decisions
|
||||
|
||||
- Decision (2026-05-15): Content-generation prompt contracts are source-internal draft helpers, not workflow authority.
|
||||
|
||||
## Rationale
|
||||
|
||||
Separating draft generation from workflow authority prevents helper prompts from bypassing ownership gates or write boundaries.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no permission grants from draft prompts
|
||||
- no replacement for direct checkout inspection
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
Update this doc when `src/generation/**` changes prompt contracts, schemas, validation, or runtime relationship to installed workflows.
|
||||
@@ -0,0 +1,87 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: behavior
|
||||
truth_kind: workflow
|
||||
last_reviewed: 2026-05-15
|
||||
source_of_truth:
|
||||
- ../../../.truthmark/config.yml
|
||||
- ../../../src/agents/instructions.ts
|
||||
- ../../../src/agents/workflow-manifest.ts
|
||||
- ../../../src/templates/codex-skills.ts
|
||||
- ../../../src/templates/generated-surfaces.ts
|
||||
---
|
||||
|
||||
# Installed Workflow Overview
|
||||
|
||||
## Purpose
|
||||
|
||||
Truthmark installs agent-native workflow surfaces into configured AI hosts. Those surfaces define invocation, write boundaries, report shapes, and where agents must read before acting.
|
||||
|
||||
## Scope
|
||||
|
||||
This document owns the shared installed-workflow runtime model and generated host surface inventory. Individual workflow behavior lives in sibling workflow docs.
|
||||
|
||||
## Triggers
|
||||
|
||||
- `truthmark init` refreshes managed instruction blocks and explicit workflow surfaces after configuration or renderer changes.
|
||||
- Explicit host invocations run manual workflows.
|
||||
- Truth Sync is the only automatic finish-time workflow trigger.
|
||||
|
||||
## Inputs
|
||||
|
||||
- `.truthmark/config.yml`
|
||||
- generated host surfaces under configured platform directories
|
||||
- the package version from `package.json`
|
||||
|
||||
## Execution Model
|
||||
|
||||
Installed skills, prompts, commands, and managed instruction blocks are the workflow runtime. The `truthmark` CLI installs and refreshes those surfaces and may validate artifacts afterward, but it does not orchestrate workflow execution or prepare required workflow payloads before an agent can act.
|
||||
|
||||
Agents inspect the checkout directly, apply workflow boundaries from committed surfaces, update only workflow-allowed files, and report what changed.
|
||||
|
||||
## Current Behavior
|
||||
|
||||
The default platform list includes every supported platform. Teams should remove unused platforms from `.truthmark/config.yml` before rerunning `truthmark init`.
|
||||
|
||||
| Platform | Generated surface | Invocation shape |
|
||||
| --- | --- | --- |
|
||||
| `codex` | `.codex/skills/truthmark-*/SKILL.md` plus Codex metadata | `/truthmark-*` or `$truthmark-*` |
|
||||
| `opencode` | `.opencode/skills/truthmark-*/SKILL.md` | `/skill truthmark-*` |
|
||||
| `claude-code` | `.claude/skills/truthmark-*/SKILL.md` | `/truthmark-*` |
|
||||
| `github-copilot` | `.github/prompts/truthmark-*.prompt.md` | `/truthmark-*` in supported Copilot IDEs |
|
||||
| `gemini-cli` | `.gemini/commands/truthmark/*.toml` | `/truthmark:*` |
|
||||
|
||||
Generated skill files, Gemini command files, Codex metadata, and managed instruction blocks include the package version from `package.json`. After upgrading Truthmark, rerun `truthmark init` and review generated workflow diffs.
|
||||
|
||||
Generated workflow descriptions are routing triggers. They use short positive trigger language plus adjacent-workflow exclusions, and they leave detailed procedure, write boundaries, and report shape to the workflow body.
|
||||
|
||||
The typed workflow manifest owns generated description text, Codex-facing short descriptions and default prompts, implicit-invocation policy, positive and negative routing examples, forbidden-adjacent cases, required gates, write boundaries, and report-section expectations. Generated host surfaces and deterministic routing tests should consume that manifest rather than duplicating workflow metadata in renderer code.
|
||||
|
||||
Truthmark-owned workflow surfaces are generated under host-specific directories. Repo-root `skills/` files are not generated V1 workflow surfaces.
|
||||
|
||||
Managed instruction blocks are compact automatic-Sync trigger and boundary indexes. They intentionally omit platform-specific invocation strings, non-automatic workflow procedures, report examples, and long checklists. Detailed invocations and procedures live in generated skills, prompts, and command files.
|
||||
|
||||
## Product Decisions
|
||||
|
||||
- Decision (2026-05-15): Installed skills, prompts, commands, and managed instruction blocks are the workflow runtime. The CLI installs and validates those surfaces but does not orchestrate Truth Sync or require helper payloads before agents can act.
|
||||
- Decision (2026-05-15): Managed instruction blocks stay compact enough for ordinary agent context. Non-automatic workflow procedure belongs in generated skills, prompts, and command files.
|
||||
- Decision (2026-05-15): Managed instruction blocks omit platform-specific invocation strings; host-specific generated workflow files remain the canonical place for invocation detail.
|
||||
- Decision (2026-05-15): Truthmark follows current host discovery paths for generated workflow files: Codex uses `.codex/skills/`, Claude Code uses `.claude/skills/`, GitHub Copilot uses `.github/prompts/`, OpenCode uses `.opencode/skills/`, Gemini CLI uses `.gemini/commands/`, and repo-root `skills/` is not a generated V1 target.
|
||||
- Decision (2026-05-15): Workflow descriptions are routing triggers rather than workflow summaries; adjacent-workflow exclusions belong in metadata when they prevent wrong workflow loading.
|
||||
- Decision (2026-05-15): Workflow metadata and routing-eval expectations live in a typed manifest so generated descriptions, host metadata, and deterministic routing tests share one structural source.
|
||||
|
||||
## Rationale
|
||||
|
||||
Keeping workflow execution agent-native makes installed repositories usable even when the Truthmark package is unavailable at execution time. Agents can read committed surfaces, inspect the checkout, and act without depending on a daemon, database, or mandatory generated payload.
|
||||
|
||||
Compact managed instruction blocks protect ordinary model context while explicit workflow surfaces remain available when the agent needs a full procedure.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no autonomous background workflow execution
|
||||
- no required helper payload, packet helper, cache file, daemon, database, or remote service
|
||||
- no generated repo-root `skills/` workflow surface
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
Update this doc when supported platforms, generated surface locations, invocation shapes, description routing behavior, or the installed runtime model change.
|
||||
@@ -0,0 +1,108 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: behavior
|
||||
truth_kind: workflow
|
||||
last_reviewed: 2026-05-15
|
||||
source_of_truth:
|
||||
- ../../../src/agents/shared.ts
|
||||
- ../../../src/truth/**
|
||||
- ../../../src/sync/report.ts
|
||||
---
|
||||
|
||||
# Shared Workflow Gates
|
||||
|
||||
## Purpose
|
||||
|
||||
Shared workflow gates ensure agents choose the correct truth owner before validating claims or repairing document shape.
|
||||
|
||||
## Scope
|
||||
|
||||
This document owns shared ownership, evidence, shape-repair, architecture-boundary, template, and decision-truth guidance rendered into installed workflows.
|
||||
|
||||
## Triggers
|
||||
|
||||
The gates apply whenever Truth Structure, Truth Document, Truth Sync, Truth Realize, or Truth Check reads, writes, audits, or relies on canonical truth docs.
|
||||
|
||||
## Inputs
|
||||
|
||||
- `.truthmark/config.yml`
|
||||
- route files under `docs/truthmark/`
|
||||
- routed truth docs
|
||||
- implementation, config, generated templates, schemas, and contract definitions
|
||||
- tests and existing canonical docs as corroboration
|
||||
|
||||
## Execution Model
|
||||
|
||||
Ownership comes first. Evidence review and shape repair are valid only after the target or source truth doc is confirmed as a bounded owner for the behavior.
|
||||
|
||||
## Ownership Gate
|
||||
|
||||
Before editing or relying on a truth doc, the workflow verifies that each target or source truth doc is a bounded owner for the behavior. If a doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, the workflow must not patch or repair it in place.
|
||||
|
||||
Truth Sync and Truth Document switch to Truth Structure when ownership repair is safe and in scope; otherwise they block and recommend Truth Structure. Truth Realize blocks before writing code when source truth is broad, mixed-owner, stale, unrouteable, or conflicting. Truth Check reports mixed-owner truth docs as topology issues. Truth Structure owns split and reroute repair.
|
||||
|
||||
Reports name the ownership result: `Ownership reviewed`, `Structure required`, `Truth docs split`, `Truth docs restructured`, or `Blocked reason`.
|
||||
|
||||
## Product Decisions/Rationale Preservation Gate
|
||||
|
||||
Before any truth-doc split, restructure, or shape repair, the workflow inventories existing `Product Decisions` and `Rationale` sections in every source or touched truth doc.
|
||||
|
||||
Current decisions and rationale are preserved in the bounded owner doc they govern. When a doc is split, the workflow moves each entry to the new owner doc instead of deleting it or leaving it stranded in an index.
|
||||
|
||||
A decision or rationale may be removed or narrowed only when checkout evidence shows it is stale or unsupported, and the report names the claim, evidence, and result. If ownership is unclear, the workflow blocks with manual-review files rather than guessing or deleting the entry.
|
||||
|
||||
After the edit, every touched truth doc must still have `Product Decisions` and `Rationale` sections, and every pre-existing entry must be preserved, moved, narrowed, removed with evidence, or blocked.
|
||||
|
||||
## Evidence Gate
|
||||
|
||||
Truth Structure, Truth Document, and Truth Sync validate new or changed behavior-bearing claims only. Agents map the changed or documented behavior to bounded route owners and primary canonical docs, support changed claims with primary checkout evidence, use tests and existing docs only as corroboration when implementation conflicts, and remove, narrow, or block unsupported claims.
|
||||
|
||||
Primary checkout evidence includes implementation, config, routing, generated-surface templates, schemas, and contract definitions.
|
||||
|
||||
Truth Check uses an audit-shaped gate: findings and suggested fixes need evidence from config, route files, canonical docs, implementation, templates, or tests. Unsupported findings are removed or marked as open questions with confidence. If an audit edits docs, changed claims pass through the claim-level gate before completion.
|
||||
|
||||
Truth Sync completed reports have a deterministic structured parser for Markdown reports with `Evidence checked` entries containing `Claim`, `Evidence`, and `Result` fields.
|
||||
|
||||
## Repository Intelligence Boundary
|
||||
|
||||
RepoIndex, RouteMap, ImpactSet, and ContextPack are derived acceleration artifacts. They may guide routing, context selection, evidence review, and verification planning, but they do not own truth, route authority, or write permissions.
|
||||
|
||||
When the Truthmark CLI is unavailable, workflows must inspect `.truthmark/config.yml`, `docs/truthmark/areas.md`, child area files, changed source files, and routed truth docs directly. The workflow may proceed manually, but the completion report must say that RepoIndex, ImpactSet, ContextPack, and freshness diagnostics were not generated.
|
||||
|
||||
If a repository-intelligence artifact conflicts with the current checkout, the checkout wins. Agents rerun the CLI when available or ignore the stale artifact when it cannot be regenerated. ContextPack-only content is not evidence; generated truth docs must cite checkout files, route files, truth docs, tests, schemas, or explicit evidence blocks.
|
||||
|
||||
## Shape Repair Gate
|
||||
|
||||
Shape repair is in-place cleanup inside an already-bounded truth owner. It covers missing template sections, stale evidence conflicts, cross-section updates within one owner, or wrong frontmatter/source/headings.
|
||||
|
||||
Shape repair does not cover ownership splits. Broad or mixed-owner docs require Truth Structure before claim updates.
|
||||
|
||||
## Template And Decision Guidance
|
||||
|
||||
Generated workflows point to the routed truth kind's matching template under `docs/templates/`, rendered as `docs/templates/<kind>-doc.md`. Agents inspect the routed truth kind, align existing docs to the template while preserving accurate authored content, and fall back to the built-in minimal truth-doc structure only when the matching template is missing.
|
||||
|
||||
Decision truth lives in the canonical doc it governs. Active decisions are dated inline when added or changed; separate active-decision ADR or planning logs are rejected.
|
||||
|
||||
## Product Decisions
|
||||
|
||||
- Decision (2026-05-15): Shared generated workflow gates are correctness gates first. Compactness is allowed only after ownership routing, evidence validation, and report obligations remain explicit.
|
||||
- Decision (2026-05-15): Ownership repair is not shape repair. Mixed-owner truth docs require Truth Structure, split/reroute, or a blocked report.
|
||||
- Decision (2026-05-15): Evidence validation is changed-claim-only and requires primary checkout evidence.
|
||||
- Decision (2026-05-15): Generated workflow surfaces refer to routed truth-doc templates instead of embedding full template text.
|
||||
- Decision (2026-05-15): Truth-doc split, restructure, and shape repair must preserve, move, explicitly narrow/remove with evidence, or block every pre-existing Product Decision and Rationale entry.
|
||||
|
||||
## Rationale
|
||||
|
||||
The product is the workflow. Agents must choose the correct owner before making local edits, otherwise evidence-backed prose can still preserve the wrong truth boundary.
|
||||
|
||||
Keeping ownership, evidence, and shape repair separate prevents broad-doc cleanup from hiding topology drift.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no inline evidence ledger in canonical docs by default
|
||||
- no in-place repair for mixed-owner truth docs
|
||||
- no full truth-doc template embedding inside generated workflow prompts
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
Update this doc when shared gate wording, template rules, decision-truth behavior, evidence reporting, or ownership/split behavior changes.
|
||||
@@ -0,0 +1,64 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: behavior
|
||||
truth_kind: workflow
|
||||
last_reviewed: 2026-05-15
|
||||
source_of_truth:
|
||||
- ../../../src/agents/truth-check.ts
|
||||
- ../../../src/checks/**
|
||||
- ../../../src/agents/shared.ts
|
||||
---
|
||||
|
||||
# Truth Check Workflow
|
||||
|
||||
## Purpose
|
||||
|
||||
Truth Check audits repository truth health.
|
||||
|
||||
## Scope
|
||||
|
||||
Truth Check owns agent-led truth-health review. It reports issues and suggested fixes without silently rewriting unrelated files.
|
||||
|
||||
## Triggers
|
||||
|
||||
- explicit user invocation through the installed host surface
|
||||
|
||||
## Inputs
|
||||
|
||||
- `.truthmark/config.yml`
|
||||
- root and child route files
|
||||
- canonical docs
|
||||
- relevant implementation code
|
||||
- optional local `truthmark check` output
|
||||
|
||||
## Execution Model
|
||||
|
||||
Truth Check inspects the checkout directly and may optionally run `truthmark check` when local tooling is available. Installed workflows must not depend on the binary being present.
|
||||
|
||||
## Current Behavior
|
||||
|
||||
Truth Check verifies that current docs describe current code rather than historical plans, route files map code surfaces to canonical truth docs, canonical behavior docs keep active Product Decisions and Rationale sections, and broad, catch-all, index-like, or mixed-owner truth docs are reported as topology issues requiring Truth Structure.
|
||||
|
||||
Truth Check supports each finding and suggested fix with evidence from config, route files, canonical docs, implementation, templates, or tests. Unsupported findings are removed or marked as open questions with confidence.
|
||||
|
||||
If follow-up docs edits are needed for mixed-owner docs, Truth Check runs or recommends Truth Structure before editing.
|
||||
|
||||
Completed reports include `Files reviewed`, `Issues found`, `Fixes suggested`, `Evidence checked`, and `Validation`.
|
||||
|
||||
## Product Decisions
|
||||
|
||||
- Decision (2026-05-15): Truth Check is an audit workflow, not a substitute for lint, tests, typecheck, code review, or Truth Sync.
|
||||
- Decision (2026-05-15): Truth Check reports mixed-owner truth docs as topology issues and does not silently repair them outside the proper workflow.
|
||||
|
||||
## Rationale
|
||||
|
||||
Audits must identify ownership drift, not only stale claims. Reporting mixed-owner docs pushes repair into Truth Structure, where routing and split decisions are allowed.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no silent rewrite of unrelated files
|
||||
- no replacement for normal code verification
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
Update this doc when Check audit scope, evidence requirements, topology finding behavior, or report shape changes.
|
||||
@@ -0,0 +1,69 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: behavior
|
||||
truth_kind: workflow
|
||||
last_reviewed: 2026-05-15
|
||||
source_of_truth:
|
||||
- ../../../src/agents/truth-document.ts
|
||||
- ../../../src/agents/shared.ts
|
||||
---
|
||||
|
||||
# Truth Document Workflow
|
||||
|
||||
## Purpose
|
||||
|
||||
Truth Document records existing implemented behavior when no functional-code change is required.
|
||||
|
||||
## Scope
|
||||
|
||||
Truth Document owns manual missing-truth generation for implemented behavior. It may write canonical truth docs and routing files only.
|
||||
|
||||
## Triggers
|
||||
|
||||
- explicit user request to document existing implemented behavior
|
||||
- handoff from Truth Sync, Truth Check, or Truth Structure when implemented behavior lacks canonical truth docs
|
||||
|
||||
## Inputs
|
||||
|
||||
- implementation code and tests
|
||||
- `.truthmark/config.yml`
|
||||
- root and child route files
|
||||
- existing canonical docs
|
||||
|
||||
## Execution Model
|
||||
|
||||
Truth Document is implementation-first and never writes functional code. It documents current implemented behavior only and does not invent future behavior or planned endpoints.
|
||||
|
||||
## Current Behavior
|
||||
|
||||
Truth Document applies the ownership gate before writing. If routing is missing, stale, broad, overloaded, catch-all, or cannot map behavior to a bounded truth owner, it runs Truth Structure first when repair is safe and in scope. If repair is unsafe, ambiguous, or outside the task boundary, it blocks and recommends Truth Structure.
|
||||
|
||||
If the candidate truth doc is broad, mixed-owner, index-like, or the documented behavior spans independent owners, Truth Document does not repair it in place. It switches to Truth Structure or blocks.
|
||||
|
||||
When ownership is bounded, Truth Document creates or updates leaf truth docs, keeps behavior truth docs behavior-oriented, keeps API endpoint details in the nearest contract truth doc when that doc owns the contract, and preserves unrelated authored content.
|
||||
|
||||
When Truth Document restructures a bounded truth doc or runs Structure first, it inventories Product Decisions and Rationale before editing. Existing entries must be preserved in or moved to their bounded owner docs, narrowed or removed only with checkout evidence, or blocked for manual review when ownership is unclear.
|
||||
|
||||
ContextPack may be used to gather bounded source context when available. It does not replace checkout inspection, does not create write permission, and cannot be cited as evidence unless it points to real checkout files, tests, route files, truth docs, schemas, or explicit evidence blocks. If ContextPack is unavailable, Truth Document proceeds manually and reports that repository-intelligence artifacts were not generated.
|
||||
|
||||
Completed reports include `Implementation reviewed`, `Ownership reviewed`, `Structure required` when applicable, `Truth docs created`, `Truth docs updated`, `Truth docs restructured`, `Routing updated`, `Evidence checked`, and `Notes`.
|
||||
|
||||
## Product Decisions
|
||||
|
||||
- Decision (2026-05-15): Truth Document exists because documenting existing implemented behavior without code changes is not a Truth Sync run.
|
||||
- Decision (2026-05-15): Truth Document must switch to Truth Structure rather than patching mixed-owner truth docs.
|
||||
- Decision (2026-05-15): Truth Document must not lose Product Decisions or Rationale during bounded shape repair or Structure handoff.
|
||||
|
||||
## Rationale
|
||||
|
||||
Documentation-only work can still damage repository truth if it appends implemented behavior to the wrong owner. The ownership gate keeps Document from turning broad docs into larger broad docs.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no functional-code edits
|
||||
- no planned behavior documentation
|
||||
- no in-place ownership repair for mixed-owner docs
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
Update this doc when Truth Document triggers, write boundaries, ownership handoff behavior, or report shape changes.
|
||||
@@ -0,0 +1,64 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: behavior
|
||||
truth_kind: workflow
|
||||
last_reviewed: 2026-05-15
|
||||
source_of_truth:
|
||||
- ../../../src/agents/prompts.ts
|
||||
- ../../../src/templates/codex-skills.ts
|
||||
- ../../../src/realize/report.ts
|
||||
---
|
||||
|
||||
# Truth Realize Workflow
|
||||
|
||||
## Purpose
|
||||
|
||||
Truth Realize implements functional code from existing canonical truth docs.
|
||||
|
||||
## Scope
|
||||
|
||||
Truth Realize is doc-first and manual. Truth docs lead, code follows, and the agent may write functional code only.
|
||||
|
||||
## Triggers
|
||||
|
||||
- explicit user invocation through the installed host surface
|
||||
|
||||
## Inputs
|
||||
|
||||
- source truth docs
|
||||
- route metadata
|
||||
- relevant implementation code and tests
|
||||
- `.truthmark/config.yml`
|
||||
|
||||
## Execution Model
|
||||
|
||||
Truth Realize must read source truth docs, routing, and relevant code before writing functional code. It must not edit truth docs or truth routing.
|
||||
|
||||
## Current Behavior
|
||||
|
||||
Truth Realize applies the ownership gate to source truth docs before writing code. If a source truth doc is broad, mixed-owner, index-like, unrouteable, stale, or conflicts with implementation evidence, Truth Realize blocks before writing code and recommends Truth Structure or Truth Document.
|
||||
|
||||
When source truth is bounded and current, Truth Realize implements only the bounded current truth claims from the source docs and reports changed code files plus verification.
|
||||
|
||||
Completion reports include `Truth docs used`, `Code updated`, and `Verification`.
|
||||
|
||||
ContextPack may be used to collect bounded implementation context when available. It does not replace checkout inspection, does not grant write permission outside the workflow boundary, and cannot override source truth docs or current code. If ContextPack is unavailable, Truth Realize proceeds manually and reports that repository-intelligence artifacts were not generated.
|
||||
|
||||
## Product Decisions
|
||||
|
||||
- Decision (2026-05-15): Truth Realize remains available only through explicit user invocation and is always generated for configured platforms instead of being gated by a config toggle.
|
||||
- Decision (2026-05-15): Truth Realize must not implement from broad, mixed-owner, stale, or unrouteable truth docs.
|
||||
|
||||
## Rationale
|
||||
|
||||
Doc-first implementation is only reliable when the source truth has a bounded owner. Implementing ambiguous truth turns documentation drift into code behavior.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no truth-doc edits
|
||||
- no routing edits
|
||||
- no implementation from ambiguous source truth
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
Update this doc when Realize invocation, source-doc checks, write boundaries, or report shape changes.
|
||||
@@ -0,0 +1,71 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: behavior
|
||||
truth_kind: workflow
|
||||
last_reviewed: 2026-05-15
|
||||
source_of_truth:
|
||||
- ../../../src/agents/truth-structure.ts
|
||||
- ../../../src/agents/shared.ts
|
||||
- ../../../src/routing/**
|
||||
---
|
||||
|
||||
# Truth Structure Workflow
|
||||
|
||||
## Purpose
|
||||
|
||||
Truth Structure designs or repairs repository truth topology.
|
||||
|
||||
## Scope
|
||||
|
||||
Truth Structure owns area routing, child route-file structure, ownership splits, and starter truth-doc placement when topology is missing, stale, broad, overloaded, catch-all, unrouteable, or explicitly requested.
|
||||
|
||||
## Triggers
|
||||
|
||||
- explicit user invocation
|
||||
- handoff from Truth Sync or Truth Document when routing or truth ownership is unsafe
|
||||
- handoff from Truth Check when audit findings require topology repair
|
||||
|
||||
## Inputs
|
||||
|
||||
- repository layout
|
||||
- `.truthmark/config.yml`
|
||||
- root and child route files
|
||||
- current canonical docs
|
||||
- representative implementation boundaries and tests
|
||||
|
||||
## Execution Model
|
||||
|
||||
Truth Structure inspects the checkout directly and defines areas by product or behavior ownership, not mechanical directory mirroring.
|
||||
|
||||
## Current Behavior
|
||||
|
||||
When topology pressure exists, Truth Structure repairs structure before creating or extending truth docs.
|
||||
|
||||
Topology pressure includes broad code mappings, overloaded child route files, multiple unrelated controllers or bounded contexts in one area, mixed-owner truth docs, too many direct truth docs in one folder, catch-all routing, or changed code that cannot map to a specific behavior doc.
|
||||
|
||||
Truth Structure splits broad, overloaded, catch-all, or mixed-owner areas into behavior-owned route files and bounded leaf truth docs when safe. It updates routing so future Truth Sync can target small docs. If a split is unsafe or ambiguous, it blocks with manual-review files.
|
||||
|
||||
Before splitting or restructuring truth docs, Truth Structure inventories Product Decisions and Rationale in every source doc. It moves each current entry into the bounded owner doc it governs, removes or narrows entries only with checkout evidence, and blocks with manual-review files when ownership is unclear.
|
||||
|
||||
Starter truth docs use closed YAML frontmatter with `status`, `doc_type`, `last_reviewed`, and `source_of_truth`, and include `Product Decisions` and `Rationale` sections.
|
||||
|
||||
Completed reports include `Topology reviewed`, `Areas reviewed`, `Routing updated`, `Truth docs created`, `Truth docs split`, `Truth docs restructured`, `Evidence checked`, `Topology decisions`, and `Notes`.
|
||||
|
||||
## Product Decisions
|
||||
|
||||
- Decision (2026-05-15): Truth Structure owns ownership repair. Mixed-owner docs must be split/rerouted when safe, not repaired in place by Sync or Document.
|
||||
- Decision (2026-05-15): Truth Structure must satisfy canonical decision-section expectations for new starter docs and repaired routed docs.
|
||||
- Decision (2026-05-15): Truth Structure must preserve or explicitly account for Product Decisions and Rationale when splitting or restructuring truth docs.
|
||||
|
||||
## Rationale
|
||||
|
||||
Ownership repair needs a workflow that can change route topology and create bounded docs. Letting Sync or Document patch broad docs preserves drift.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no mechanical directory mirroring when behavior ownership is clearer
|
||||
- no generic truth docs behind broad catch-all routing
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
Update this doc when topology pressure signals, split behavior, starter-doc requirements, or Structure report shape changes.
|
||||
@@ -0,0 +1,85 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: behavior
|
||||
truth_kind: workflow
|
||||
last_reviewed: 2026-05-15
|
||||
source_of_truth:
|
||||
- ../../../src/agents/truth-sync.ts
|
||||
- ../../../src/sync/report.ts
|
||||
- ../../../src/agents/shared.ts
|
||||
---
|
||||
|
||||
# Truth Sync Workflow
|
||||
|
||||
## Purpose
|
||||
|
||||
Truth Sync aligns canonical truth docs with functional-code changes.
|
||||
|
||||
## Scope
|
||||
|
||||
Truth Sync is code-first. Code leads, truth docs follow, and functional code must not be rewritten during sync.
|
||||
|
||||
## Triggers
|
||||
|
||||
- automatic finish-time trigger after functional code changes since the last successful Truth Sync
|
||||
- explicit user invocation through the installed host surface
|
||||
|
||||
## Inputs
|
||||
|
||||
- staged, unstaged, and untracked functional-code changes
|
||||
- `.truthmark/config.yml`
|
||||
- root and child route files
|
||||
- relevant canonical docs and nearby implementation
|
||||
|
||||
## Execution Model
|
||||
|
||||
Truth Sync may update routed truth docs and routing when routing repair is needed. It may create missing canonical truth docs when routeable implementation would otherwise remain undocumented.
|
||||
|
||||
## Current Behavior
|
||||
|
||||
Before updating truth docs, Truth Sync applies the topology and ownership gates. If routing is missing, stale, broad, overloaded, catch-all, or cannot map changed code to a bounded truth owner, it must not create another generic truth doc. It runs Truth Structure first when repair is safe and in scope, or blocks and recommends Truth Structure when topology repair is unsafe, ambiguous, or outside the task boundary.
|
||||
|
||||
If an impacted truth doc is broad, mixed-owner, index-like, or the code change spans independent behavior owners, Truth Sync switches to Truth Structure when safe and in scope. Otherwise it blocks and reports manual-review files.
|
||||
|
||||
Truth Sync updates active decisions and rationale in the routed canonical doc when implementation changes are driven by a decision change. It dates active decisions inline when added or changed and replaces stale active decisions rather than appending separate timestamped decision notes.
|
||||
|
||||
When Truth Sync restructures a bounded truth doc or runs Structure inline, it inventories Product Decisions and Rationale before editing. Existing entries must be preserved in or moved to their bounded owner docs, narrowed or removed only with checkout evidence, or blocked for manual review when ownership is unclear.
|
||||
|
||||
Truth Sync updates architecture docs in the same sync when changed code alters architecture-level structure or ownership.
|
||||
|
||||
ContextPack may be used to accelerate Truth Sync when available. It does not replace checkout inspection, does not create write permission, and cannot be cited as evidence unless it points to real checkout files, tests, route files, truth docs, schemas, or explicit evidence blocks. If ContextPack or ImpactSet is unavailable, Truth Sync proceeds manually and reports that repository-intelligence artifacts were not generated.
|
||||
|
||||
Completed reports include `Changed code reviewed`, `Ownership reviewed`, `Structure required` when applicable, `Truth docs updated`, `Truth docs split` when Structure is run inline, `Evidence checked`, and `Notes`. Skipped reports include `Reason`. Blocked reports include `Reason`, `Files requiring manual review`, and `Next action`.
|
||||
|
||||
Current skip reasons are:
|
||||
|
||||
- documentation-only change
|
||||
- formatting-only change
|
||||
- clearly behavior-preserving rename with no truth impact
|
||||
- no Truthmark config exists yet
|
||||
- no functional code changes
|
||||
|
||||
Truth Sync's generated frontmatter description and Codex metadata carry those skip cases because skill metadata is the host-visible routing boundary before the full workflow body is loaded.
|
||||
|
||||
Truth Sync delegation is host-owned. Generated workflow surfaces may describe when delegation is allowed, but must not name a preferred subagent or project-local subagent preference file.
|
||||
|
||||
## Product Decisions
|
||||
|
||||
- Decision (2026-05-15): Truth Sync metadata carries skip cases because docs-only, formatting-only, behavior-preserving rename, missing-config, and no-code changes should not trigger the finish-time sync path.
|
||||
- Decision (2026-05-15): Truth Sync must not worsen weak topology by adding generic truth docs behind missing, stale, broad, overloaded, catch-all, or unrouteable routing.
|
||||
- Decision (2026-05-15): Truth Sync must switch to Truth Structure or block when impacted truth docs are mixed-owner or broad.
|
||||
- Decision (2026-05-15): Truth Sync must not lose Product Decisions or Rationale during bounded shape repair or inline Structure handoff.
|
||||
|
||||
## Rationale
|
||||
|
||||
Truth Sync is the finish-time bridge from code to truth, so it must protect route ownership before claim evidence. Otherwise it can accurately document behavior in the wrong place.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no functional-code rewrites during sync
|
||||
- no generic docs behind weak routing
|
||||
- no preferred subagent baked into generated surfaces
|
||||
|
||||
## Maintenance Notes
|
||||
|
||||
Update this doc when Sync triggers, skip reasons, report shape, delegation language, or ownership handoff behavior changes.
|
||||
+99
-6
@@ -1,22 +1,115 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: routing
|
||||
last_reviewed: 2026-05-09
|
||||
last_reviewed: 2026-05-14
|
||||
source_of_truth:
|
||||
- ../README.md
|
||||
- ../ai/repo-rules.md
|
||||
- ../../TRUTHMARK.md
|
||||
- ../../.truthmark/config.yml
|
||||
---
|
||||
|
||||
# Truthmark Areas
|
||||
|
||||
## Repository
|
||||
The root route index delegates Truthmark's main behavior surfaces to smaller area files.
|
||||
|
||||
## Contracts And Commands
|
||||
|
||||
Area files:
|
||||
- docs/truthmark/areas/repository.md
|
||||
- docs/truthmark/areas/contracts-and-commands.md
|
||||
|
||||
Code surface:
|
||||
- src/**
|
||||
- src/cli/**
|
||||
- src/config/command.ts
|
||||
- src/config/defaults.ts
|
||||
- src/config/schema.ts
|
||||
- src/output/**
|
||||
|
||||
Update truth when:
|
||||
- repository routing ownership changes
|
||||
- config file or command contracts change
|
||||
- supported platforms or generated surface contract fields change
|
||||
- user-visible result envelopes, diagnostics, or command options change
|
||||
|
||||
## Initialization And Scaffold
|
||||
|
||||
Area files:
|
||||
- docs/truthmark/areas/init-and-scaffold.md
|
||||
|
||||
Code surface:
|
||||
- src/fs/paths.ts
|
||||
- src/init/**
|
||||
- src/templates/default-standards.ts
|
||||
- src/templates/generated-surfaces.ts
|
||||
- src/templates/init-files.ts
|
||||
|
||||
Update truth when:
|
||||
- `truthmark init` scaffolds or refreshes files differently
|
||||
- default canonical docs or generated surface lists change
|
||||
- hierarchy migration review behavior changes
|
||||
|
||||
## Check And Routing
|
||||
|
||||
Area files:
|
||||
- docs/truthmark/areas/check-and-routing.md
|
||||
|
||||
Code surface:
|
||||
- src/checks/**
|
||||
- src/config/load.ts
|
||||
- src/git/**
|
||||
- src/markdown/**
|
||||
- src/routing/**
|
||||
- src/types/**
|
||||
|
||||
Update truth when:
|
||||
- validation or area-resolution behavior changes
|
||||
- branch-scope or repository discovery behavior changes
|
||||
- routed code coverage expectations change
|
||||
|
||||
## Installed Workflows
|
||||
|
||||
Area files:
|
||||
- docs/truthmark/areas/installed-workflows.md
|
||||
|
||||
Code surface:
|
||||
- src/agents/**
|
||||
- src/generation/**
|
||||
- src/realize/**
|
||||
- src/sync/**
|
||||
- src/templates/agents-block.ts
|
||||
- src/templates/codex-skills.ts
|
||||
- src/templates/generated-surfaces.ts
|
||||
- src/truth/**
|
||||
- src/version.ts
|
||||
|
||||
Update truth when:
|
||||
- installed workflow boundaries or report shapes change
|
||||
- generated instruction block or skill content changes
|
||||
- workflow version markers or sync classification behavior changes
|
||||
|
||||
## Release Automation
|
||||
|
||||
Area files:
|
||||
- docs/truthmark/areas/release-automation.md
|
||||
|
||||
Code surface:
|
||||
- .github/workflows/**
|
||||
- src/templates/github-action.ts
|
||||
|
||||
Update truth when:
|
||||
- CI verification steps or triggers change
|
||||
- release publishing prerequisites or publish steps change
|
||||
|
||||
## Repository Intelligence
|
||||
|
||||
Area files:
|
||||
- docs/truthmark/areas/repository-intelligence.md
|
||||
|
||||
Code surface:
|
||||
- src/repo-index/**
|
||||
- src/impact/**
|
||||
- src/evidence/**
|
||||
- src/freshness/**
|
||||
- src/context-pack/**
|
||||
|
||||
Update truth when:
|
||||
- repository indexing, route-map, impact analysis, evidence validation, freshness checks, or context-pack behavior changes
|
||||
- `truthmark index`, `truthmark impact`, or `truthmark context` result shapes change
|
||||
|
||||
@@ -0,0 +1,41 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: routing
|
||||
last_reviewed: 2026-05-14
|
||||
source_of_truth:
|
||||
- ../areas.md
|
||||
- ../../README.md
|
||||
- ../../ai/repo-rules.md
|
||||
---
|
||||
|
||||
# Check And Routing Areas
|
||||
|
||||
## Check And Routing
|
||||
|
||||
Truth documents:
|
||||
```yaml
|
||||
truth_documents:
|
||||
- path: docs/truth/contracts.md
|
||||
kind: contract
|
||||
- path: docs/architecture/overview.md
|
||||
kind: architecture
|
||||
- path: docs/architecture/module-map.md
|
||||
kind: architecture
|
||||
- path: docs/truth/check-diagnostics.md
|
||||
kind: behavior
|
||||
- path: docs/truth/routing-examples.md
|
||||
kind: behavior
|
||||
```
|
||||
|
||||
Code surface:
|
||||
- src/checks/**
|
||||
- src/config/load.ts
|
||||
- src/git/**
|
||||
- src/markdown/**
|
||||
- src/routing/**
|
||||
- src/types/**
|
||||
|
||||
Update truth when:
|
||||
- validation or area-resolution behavior changes
|
||||
- branch-scope or repository discovery behavior changes
|
||||
- routed code coverage expectations change
|
||||
@@ -0,0 +1,32 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: routing
|
||||
last_reviewed: 2026-05-14
|
||||
source_of_truth:
|
||||
- ../areas.md
|
||||
- ../../README.md
|
||||
- ../../ai/repo-rules.md
|
||||
---
|
||||
|
||||
# Contracts And Commands Areas
|
||||
|
||||
## Contracts And Commands
|
||||
|
||||
Truth documents:
|
||||
```yaml
|
||||
truth_documents:
|
||||
- path: docs/truth/contracts.md
|
||||
kind: contract
|
||||
```
|
||||
|
||||
Code surface:
|
||||
- src/cli/**
|
||||
- src/config/command.ts
|
||||
- src/config/defaults.ts
|
||||
- src/config/schema.ts
|
||||
- src/output/**
|
||||
|
||||
Update truth when:
|
||||
- config file shape or defaults change
|
||||
- command names, options, or JSON envelope contracts change
|
||||
- diagnostic categories or severities exposed to users change
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: routing
|
||||
last_reviewed: 2026-05-14
|
||||
source_of_truth:
|
||||
- ../areas.md
|
||||
- ../../README.md
|
||||
- ../../ai/repo-rules.md
|
||||
---
|
||||
|
||||
# Initialization And Scaffold Areas
|
||||
|
||||
## Initialization And Scaffold
|
||||
|
||||
Truth documents:
|
||||
```yaml
|
||||
truth_documents:
|
||||
- path: docs/architecture/overview.md
|
||||
kind: architecture
|
||||
- path: docs/architecture/module-map.md
|
||||
kind: architecture
|
||||
- path: docs/truth/init-and-scaffold.md
|
||||
kind: behavior
|
||||
- path: docs/truth/repository/overview.md
|
||||
kind: behavior
|
||||
```
|
||||
|
||||
Code surface:
|
||||
- src/fs/paths.ts
|
||||
- src/init/**
|
||||
- src/templates/default-standards.ts
|
||||
- src/templates/generated-surfaces.ts
|
||||
- src/templates/init-files.ts
|
||||
|
||||
Update truth when:
|
||||
- `truthmark init` scaffolds or refreshes files differently
|
||||
- default canonical docs or generated surface lists change
|
||||
- hierarchy migration review behavior changes
|
||||
@@ -0,0 +1,53 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: routing
|
||||
last_reviewed: 2026-05-15
|
||||
source_of_truth:
|
||||
- ../areas.md
|
||||
- ../../README.md
|
||||
- ../../ai/repo-rules.md
|
||||
---
|
||||
|
||||
# Installed Workflows Areas
|
||||
|
||||
## Installed Workflows
|
||||
|
||||
Truth documents:
|
||||
```yaml
|
||||
truth_documents:
|
||||
- path: docs/truth/contracts.md
|
||||
kind: contract
|
||||
- path: docs/truth/workflows/overview.md
|
||||
kind: workflow
|
||||
- path: docs/truth/workflows/shared-gates.md
|
||||
kind: workflow
|
||||
- path: docs/truth/workflows/truth-structure.md
|
||||
kind: workflow
|
||||
- path: docs/truth/workflows/truth-document.md
|
||||
kind: workflow
|
||||
- path: docs/truth/workflows/truth-sync.md
|
||||
kind: workflow
|
||||
- path: docs/truth/workflows/truth-realize.md
|
||||
kind: workflow
|
||||
- path: docs/truth/workflows/truth-check.md
|
||||
kind: workflow
|
||||
- path: docs/truth/workflows/content-generation.md
|
||||
kind: workflow
|
||||
```
|
||||
|
||||
Code surface:
|
||||
- src/agents/**
|
||||
- src/generation/**
|
||||
- src/realize/**
|
||||
- src/sync/**
|
||||
- src/templates/agents-block.ts
|
||||
- src/templates/codex-skills.ts
|
||||
- src/templates/generated-surfaces.ts
|
||||
- src/truth/**
|
||||
- src/version.ts
|
||||
|
||||
Update truth when:
|
||||
- installed workflow boundaries or report shapes change
|
||||
- generated instruction block or skill content changes
|
||||
- workflow version markers or sync classification behavior changes
|
||||
- ownership gates, evidence gates, Product Decisions/Rationale preservation gates, or truth-doc split behavior changes
|
||||
@@ -0,0 +1,29 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: routing
|
||||
last_reviewed: 2026-05-14
|
||||
source_of_truth:
|
||||
- ../areas.md
|
||||
- ../../README.md
|
||||
- ../../ai/repo-rules.md
|
||||
---
|
||||
|
||||
# Release Automation Areas
|
||||
|
||||
## Release Automation
|
||||
|
||||
Truth documents:
|
||||
```yaml
|
||||
truth_documents:
|
||||
- path: docs/truth/release/automation.md
|
||||
kind: workflow
|
||||
```
|
||||
|
||||
Code surface:
|
||||
- .github/workflows/**
|
||||
- src/templates/github-action.ts
|
||||
|
||||
Update truth when:
|
||||
- CI verification steps or triggers change
|
||||
- release publishing prerequisites or publish steps change
|
||||
- GitHub Action examples or action template rendering changes
|
||||
@@ -0,0 +1,35 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: routing
|
||||
last_reviewed: 2026-05-16
|
||||
source_of_truth:
|
||||
- ../areas.md
|
||||
- ../../README.md
|
||||
- ../../ai/repo-rules.md
|
||||
---
|
||||
|
||||
# Repository Intelligence Areas
|
||||
|
||||
## Repository Intelligence
|
||||
|
||||
Truth documents:
|
||||
```yaml
|
||||
truth_documents:
|
||||
- path: docs/truth/repository/repo-index.md
|
||||
kind: behavior
|
||||
- path: docs/truth/repository/impact-set.md
|
||||
kind: behavior
|
||||
- path: docs/truth/repository/context-pack.md
|
||||
kind: behavior
|
||||
```
|
||||
|
||||
Code surface:
|
||||
- src/repo-index/**
|
||||
- src/impact/**
|
||||
- src/evidence/**
|
||||
- src/freshness/**
|
||||
- src/context-pack/**
|
||||
|
||||
Update truth when:
|
||||
- RepoIndex, RouteMap, ImpactSet, evidence validation, freshness diagnostics, or ContextPack behavior changes
|
||||
- repository-intelligence command output changes
|
||||
@@ -1,78 +0,0 @@
|
||||
---
|
||||
status: active
|
||||
doc_type: routing
|
||||
last_reviewed: 2026-05-09
|
||||
source_of_truth:
|
||||
- ../areas.md
|
||||
- ../../README.md
|
||||
- ../../ai/repo-rules.md
|
||||
---
|
||||
|
||||
# Repository Areas
|
||||
|
||||
## CLI And Scaffold Surface
|
||||
|
||||
Truth documents:
|
||||
- docs/README.md
|
||||
- TRUTHMARK.md
|
||||
- docs/features/contracts.md
|
||||
- docs/features/init-and-scaffold.md
|
||||
|
||||
Code surface:
|
||||
- src/cli/**
|
||||
- src/fs/**
|
||||
- src/init/**
|
||||
- src/templates/**
|
||||
- src/output/**
|
||||
|
||||
Update truth when:
|
||||
- command surface or scaffold behavior changes
|
||||
- generated AGENTS block behavior changes
|
||||
- human or JSON command output shape changes
|
||||
|
||||
## Diagnostics And Routing Surface
|
||||
|
||||
Truth documents:
|
||||
- docs/README.md
|
||||
- docs/features/contracts.md
|
||||
- docs/architecture/overview.md
|
||||
- docs/architecture/module-map.md
|
||||
- docs/features/check-diagnostics.md
|
||||
- docs/features/routing-examples.md
|
||||
- docs/standards/documentation-governance.md
|
||||
|
||||
Code surface:
|
||||
- src/checks/**
|
||||
- src/config/**
|
||||
- src/fs/**
|
||||
- src/git/**
|
||||
- src/markdown/**
|
||||
- src/output/**
|
||||
- src/routing/**
|
||||
- src/types/**
|
||||
|
||||
Update truth when:
|
||||
- authority, frontmatter, internal-link, or area-validation rules change
|
||||
- branch-scope, repository-detection, or containment behavior changes
|
||||
- routed code coverage expectations change
|
||||
|
||||
## Installed Workflow Surface
|
||||
|
||||
Truth documents:
|
||||
- docs/README.md
|
||||
- TRUTHMARK.md
|
||||
- docs/features/contracts.md
|
||||
- docs/features/installed-workflows.md
|
||||
|
||||
Code surface:
|
||||
- src/agents/**
|
||||
- src/realize/**
|
||||
- src/sync/**
|
||||
- src/templates/codex-skills.ts
|
||||
- src/version.ts
|
||||
|
||||
Update truth when:
|
||||
- Truth Sync or Truth Realize boundaries change
|
||||
- changed-file classification or changed-surface collection changes
|
||||
- installed report shape, generated skill content, or skip reasons change
|
||||
- generated workflow version markers change
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user