diff --git a/.claude/skills/truthmark-check/SKILL.md b/.claude/skills/truthmark-check/SKILL.md new file mode 100644 index 0000000..3f35a85 --- /dev/null +++ b/.claude/skills/truthmark-check/SKILL.md @@ -0,0 +1,55 @@ +--- +name: truthmark-check +description: Use when the user asks to audit repository truth health. Inspects truth docs, routing, and implementation directly; may optionally run truthmark check when available. +argument-hint: Optional area, doc path, or audit focus +user-invocable: true +truthmark-version: 1.2.3 +--- + +# Truthmark Check + +Use this skill to audit repository truth health. + +Invocations: OpenCode /skill truthmark-check; Codex /truthmark-check or $truthmark-check; Claude Code /truthmark-check; GitHub Copilot /truthmark-check; Gemini CLI /truthmark:check. + +Truth Check is agent-led: + +- inspect .truthmark/config.yml, docs/truthmark/areas.md, canonical docs, and relevant implementation directly +- Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. +- inspect the configured root route index at docs/truthmark/areas.md and relevant child route files under docs/truthmark/areas/ +- check that current docs describe current code rather than historical plans +- check that docs/truthmark/areas.md routes code surfaces to canonical truth docs +- check that canonical behavior docs keep active Product Decisions and Rationale sections +- optionally run truthmark check when local tooling is available +- must not require the truthmark binary; direct inspection is always valid +- report issues and suggested fixes without silently rewriting unrelated files + +Truthmark hierarchy: +- Config: .truthmark/config.yml +- Root route index: docs/truthmark/areas.md +- Area route files: docs/truthmark/areas/**/*.md +- Feature docs: docs/features/**/*.md +Decision truth lives in the canonical doc it governs. +Date active decisions inline when added or changed, for example `Decision (2026-05-09): ...`. +Do not create separate timestamped ADR logs or planning tickets for active decisions. +Replace old active decisions instead of appending separate timestamped decision logs; Git history is the audit trail. +Update Product Decisions and Rationale when a behavior change comes from a decision change. + +Report completion in this shape: + +```md +Truth Check: completed + +Files reviewed: +- docs/truthmark/areas.md + +Issues found: +- none + +Fixes suggested: +- none + +Validation: +- truthmark check +``` diff --git a/.claude/skills/truthmark-document/SKILL.md b/.claude/skills/truthmark-document/SKILL.md new file mode 100644 index 0000000..cd5c4ad --- /dev/null +++ b/.claude/skills/truthmark-document/SKILL.md @@ -0,0 +1,66 @@ +--- +name: truthmark-document +description: Use when the user explicitly asks to document existing implemented behavior, or when Truth Sync, Truth Check, or Truth Structure reports implemented behavior that lacks canonical truth docs. Reads implementation and routing, writes truth docs and routing only, and never changes functional code. +argument-hint: Optional implemented behavior, API endpoint, route, controller, package, or truth-doc area to document +user-invocable: true +truthmark-version: 1.2.3 +--- + +# Truthmark Document + +Use this skill to document existing implemented behavior when no functional-code changes are required for the task. +Invocations: OpenCode /skill truthmark-document; Codex /truthmark-document or $truthmark-document; Claude Code /truthmark-document; GitHub Copilot /truthmark-document; Gemini CLI /truthmark:document. + +Truth Document is manual and implementation-first: + +- run only when the user explicitly asks to generate or update truth docs for existing behavior, or when Truth Sync, Truth Check, or Truth Structure reports implemented behavior that lacks canonical truth docs +- inspect .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, existing canonical docs, implementation code, and tests directly +- Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. +- document current implemented behavior; do not invent future behavior or planned endpoints +- may write canonical truth docs and docs/truthmark/areas.md or relevant child route files only +- must not write functional code +- when routing is missing, stale, broad, overloaded, catch-all, or cannot map the behavior to a bounded truth owner, run Truth Structure first when routing repair is safe and in scope +- block and recommend Truth Structure when routing repair is unsafe, ambiguous, or outside the task boundary +- keep feature README.md files as indexes rather than truth-document targets +- create or update bounded leaf truth docs when behavior does not fit an existing leaf doc +- keep feature docs behavior-oriented, not endpoint-oriented, unless the endpoint itself is the behavior boundary +- keep API endpoint details in the nearest contract truth doc when such a doc owns the API contract +- preserve unrelated authored content +When creating or updating a feature doc, read docs/templates/feature-doc.md and follow its frontmatter, heading order, and section intent. +When updating an existing feature doc, align existing feature docs to the template standard while preserving authored content that remains accurate. +If docs/templates/feature-doc.md is missing, use the built-in minimal feature-doc structure with Current Behavior, Product Decisions, and Rationale sections. +Teams may edit docs/templates/feature-doc.md to define their local feature-doc standard. +Maintain architecture docs when a code change alters system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership. +Do not put ordinary feature behavior, endpoint details, UI copy, validation rules, or bug fixes in architecture docs unless they change those architecture boundaries. +Keep architecture docs focused on structure and ownership; keep current product behavior in feature or contract docs. +Truthmark hierarchy: +- Config: .truthmark/config.yml +- Root route index: docs/truthmark/areas.md +- Area route files: docs/truthmark/areas/**/*.md +- Feature docs: docs/features/**/*.md +Decision truth lives in the canonical doc it governs. +Date active decisions inline when added or changed, for example `Decision (2026-05-09): ...`. +Do not create separate timestamped ADR logs or planning tickets for active decisions. +Replace old active decisions instead of appending separate timestamped decision logs; Git history is the audit trail. +Update Product Decisions and Rationale when a behavior change comes from a decision change. + +Report completion in this shape: +```md +Truth Document: completed + +Implementation reviewed: +- src/api/orders/** + +Truth docs created: +- docs/features/orders/order-submission.md + +Truth docs updated: +- docs/features/contracts.md + +Routing updated: +- docs/truthmark/areas/orders.md + +Notes: +- Documented existing order submission behavior from route handlers and tests. +``` diff --git a/.claude/skills/truthmark-realize/SKILL.md b/.claude/skills/truthmark-realize/SKILL.md new file mode 100644 index 0000000..c58afa7 --- /dev/null +++ b/.claude/skills/truthmark-realize/SKILL.md @@ -0,0 +1,51 @@ +--- +name: truthmark-realize +description: Use when the user explicitly asks to realize Truthmark truth docs into code, including /truthmark-realize, $truthmark-realize, or /truthmark:realize. Reads truth docs and routing first, updates functional code only, and reports verification. +argument-hint: Optional truth doc path, area, or desired code behavior to realize +user-invocable: true +truthmark-version: 1.2.3 +--- + +# Truthmark Realize + +Use this skill only when the user explicitly asks to realize truth docs into code. + +Invocations: OpenCode /skill truthmark-realize; Codex /truthmark-realize or $truthmark-realize; Claude Code /truthmark-realize; GitHub Copilot /truthmark-realize; Gemini CLI /truthmark:realize. + +Truth Realize is doc-first: + +- truth docs lead +- code follows +- Truth Realize never edits the truth docs it is realizing + +Workflow: + +1. Read the updated truth docs named by the user, or infer the relevant docs from docs/truthmark/areas.md. +2. Read .truthmark/config.yml, docs/truthmark/areas.md, and the relevant functional code. +3. Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. +4. Update functional code only so implementation matches the truth docs. +5. Do not edit truth docs or truth routing while realizing those docs. +6. Run relevant tests for the changed code. +7. Report changed code files and verification steps. + +Read and write boundaries: + +- may read truth docs, routing docs, and relevant functional code +- may write functional code only +- must not edit truth docs or truth routing while realizing those docs + +Report completion in this shape: + +```md +Truth Realize: completed + +Truth docs used: +- docs/features/authentication.md + +Code updated: +- src/auth/session.ts + +Verification: +- npm test -- auth +``` diff --git a/.claude/skills/truthmark-structure/SKILL.md b/.claude/skills/truthmark-structure/SKILL.md new file mode 100644 index 0000000..c66416f --- /dev/null +++ b/.claude/skills/truthmark-structure/SKILL.md @@ -0,0 +1,93 @@ +--- +name: truthmark-structure +description: Use when the user asks to design, repair, or refresh missing, stale, broad, overloaded, catch-all, or unrouteable Truthmark area routing. Inspects the repository directly, updates docs/truthmark/areas.md, and may create starter canonical truth docs. +argument-hint: Optional area, directory, or routing concern +user-invocable: true +truthmark-version: 1.2.3 +--- + +Use this skill to design or repair Truthmark area structure. +Invocations: OpenCode /skill truthmark-structure; Codex /truthmark-structure or $truthmark-structure; Claude Code /truthmark-structure; GitHub Copilot /truthmark-structure; Gemini CLI /truthmark:structure. +Truth Structure is agent-native: +- inspect repository layout, current docs, .truthmark/config.yml, docs/truthmark/areas.md, and relevant code directly +- Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. +- inspect the configured root route index at docs/truthmark/areas.md and relevant child route files under docs/truthmark/areas/ +- define areas by product or behavior ownership, not by mechanical directory mirroring +- create or repair docs/truthmark/areas.md +- create starter truth docs when useful and when they belong in the canonical current-truth surface +- Starter truth docs must use closed YAML frontmatter bounded by opening and closing --- lines; include status, doc_type, last_reviewed, and source_of_truth inside that frontmatter. +- Starter truth docs must include ## Product Decisions and ## Rationale sections. +When creating or updating a feature doc, read docs/templates/feature-doc.md and follow its frontmatter, heading order, and section intent. +When updating an existing feature doc, align existing feature docs to the template standard while preserving authored content that remains accurate. +If docs/templates/feature-doc.md is missing, use the built-in minimal feature-doc structure with Current Behavior, Product Decisions, and Rationale sections. +Teams may edit docs/templates/feature-doc.md to define their local feature-doc standard. +- use docs/features/**, docs/architecture/**, or docs/standards/** for current truth destinations +- use only canonical current-truth destinations for starter truth docs +- keep active Product Decisions and Rationale in the canonical doc that owns the behavior +- preserve unrelated authored content +## Topology Governance +Truth Structure owns documentation topology. Do not depend on humans to manually organize docs/features. Treat the configured feature root as a managed semantic root. +Inspect controllers, routes, handlers, services, packages, tests, existing truth docs, and route files; infer product and domain ownership from behavior boundaries, not from mechanical directory mirroring. +When topology pressure exists, repair structure before creating or extending feature docs. +Topology pressure signals: +- one area maps broad code such as src/**, app/**, server/**, services/**, or packages/** +- one area maps multiple unrelated controllers, route groups, services, or bounded contexts +- one truth doc owns unrelated behaviors or unrelated endpoint families +- the configured feature root has many direct non-index docs +- a changed controller, route, or service cannot map to a specific behavior doc +- Truth Sync would need to create a new generic feature doc because routing is too broad +- endpoint or controller names reveal domains missing from docs/truthmark/areas/** +Use these review thresholds as guidance: +- more than 10 direct feature docs in one folder +- more than 15 leaf areas in one child route file +- more than 8 truth docs mapped to one area +- more than 5 controllers mapped through one catch-all area +Repair rules: +- split broad, overloaded, or catch-all areas into behavior-owned child route files +- create route files under docs/truthmark/areas/ when a product/domain boundary is clear +- create feature docs under the configured feature root only when behavior lacks a current doc +- README.md files are indexes, not Truth Sync targets +- prefer bounded leaf truth docs at //.md +- keep feature docs behavior-oriented, not endpoint-oriented +- keep API endpoint details in the nearest contract truth doc when such a doc exists +- update routing so future Truth Sync can target small docs +- preserve existing authored docs; move or rewrite only when needed to remove ambiguity +Maintain architecture docs when a code change alters system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership. +Do not put ordinary feature behavior, endpoint details, UI copy, validation rules, or bug fixes in architecture docs unless they change those architecture boundaries. +Keep architecture docs focused on structure and ownership; keep current product behavior in feature or contract docs. +- Do not finish topology repair with routed canonical current-truth docs missing Product Decisions or Rationale sections. +- If an existing canonical doc lacks either section, add the missing heading beside Current Behavior with a concise current-state placeholder or active decision. +Portable fallback: +- If this skill surface is unavailable, perform the same workflow directly from committed repository files. +- Do not require the truthmark CLI. +- Read .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, canonical docs, and representative implementation code. +- Use a subagent only when the host supports that pattern; otherwise perform the topology repair inline. +Truthmark hierarchy: +- Config: .truthmark/config.yml +- Root route index: docs/truthmark/areas.md +- Area route files: docs/truthmark/areas/**/*.md +- Feature docs: docs/features/**/*.md +Decision truth lives in the canonical doc it governs. +Date active decisions inline when added or changed, for example `Decision (2026-05-09): ...`. +Do not create separate timestamped ADR logs or planning tickets for active decisions. +Replace old active decisions instead of appending separate timestamped decision logs; Git history is the audit trail. +Update Product Decisions and Rationale when a behavior change comes from a decision change. +Report completion in this shape: +```md +Truth Structure: completed +Topology reviewed: +- controllers: src/auth/** +- docs root: docs/features +- route files: docs/truthmark/areas.md +Areas reviewed: +- src/auth/** +Routing updated: +- docs/truthmark/areas.md +Truth docs created: +- docs/features/authentication.md +Topology decisions: +- Added an Authentication area because session behavior has a distinct code surface and truth owner. +Notes: +- Added an Authentication area for session behavior. +``` diff --git a/.claude/skills/truthmark-sync/SKILL.md b/.claude/skills/truthmark-sync/SKILL.md new file mode 100644 index 0000000..7b8f996 --- /dev/null +++ b/.claude/skills/truthmark-sync/SKILL.md @@ -0,0 +1,100 @@ +--- +name: truthmark-sync +description: Use automatically before finishing when functional code changed since the last successful Truth Sync, and when the user explicitly invokes /truthmark-sync, $truthmark-sync, or /truthmark:sync. Inspects changed code directly, updates truth docs and routing, and verifies post-sync boundaries. Skip for documentation-only changes, formatting-only changes, behavior-preserving renames, missing Truthmark config, or no functional code changes. +argument-hint: Optional changed-code area, truth-doc area, or sync focus +user-invocable: true +truthmark-version: 1.2.3 +--- + +Use this skill automatically before finishing when functional code changed since the last successful Truth Sync. Also run it immediately when the user explicitly invokes Truth Sync. +Invocations: OpenCode /skill truthmark-sync; Codex /truthmark-sync or $truthmark-sync; Claude Code /truthmark-sync; GitHub Copilot /truthmark-sync; Gemini CLI /truthmark:sync. +Explicit invocation runs immediately. Later functional-code changes reopen the finish-time requirement, and an earlier explicit run satisfies the finish gate only if no later functional-code changes occur. +Skip when changes are documentation-only, formatting-only, clearly behavior-preserving renames with no truth impact, when no Truthmark config exists yet, or when there are no functional code changes. +Parent workflow: +1. Inspect git status, staged changes, unstaged changes, and untracked files directly. +2. Read .truthmark/config.yml, the configured root route index at docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, and relevant canonical docs. +3. Identify functional-code changes and the nearest truth docs or routing repairs. +4. Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. +5. Code verification is parent-owned: follow repository instructions and task context, and report what ran or why it did not run. +6. Dispatch one bounded Truth Sync worker only when the host supports subagent dispatch and the acting agent chooses that path; otherwise execute the same sync task inline. +Topology quality gate: +- before updating truth docs, verify the changed code resolves to a specific behavior-owned area and bounded truth owner +- if routing is missing, stale, broad, overloaded, catch-all route only, or cannot map changed code to a bounded truth owner, do not create another generic feature doc +- run Truth Structure before syncing when topology repair is safe and in scope +- block and recommend Truth Structure when topology repair is unsafe, ambiguous, or outside the current task boundary +- report the route files and changed code paths that require structure repair +- README.md files are indexes, not Truth Sync targets +- must not append behavior details to a feature README +- create or update a bounded leaf truth doc when behavior changes do not fit an existing leaf doc +When creating or updating a feature doc, read docs/templates/feature-doc.md and follow its frontmatter, heading order, and section intent. +When updating an existing feature doc, align existing feature docs to the template standard while preserving authored content that remains accurate. +If docs/templates/feature-doc.md is missing, use the built-in minimal feature-doc structure with Current Behavior, Product Decisions, and Rationale sections. +Teams may edit docs/templates/feature-doc.md to define their local feature-doc standard. +Maintain architecture docs when a code change alters system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership. +Do not put ordinary feature behavior, endpoint details, UI copy, validation rules, or bug fixes in architecture docs unless they change those architecture boundaries. +Keep architecture docs focused on structure and ownership; keep current product behavior in feature or contract docs. +Optional validation tooling: +- you may run truthmark check when local tooling is available +- do not require the truthmark binary; direct checkout inspection is the canonical path +- optional validation must not replace agent judgment about docs and routing +- update Product Decisions and Rationale when a behavior change comes from a decision change +Truthmark hierarchy: +- Config: .truthmark/config.yml +- Root route index: docs/truthmark/areas.md +- Area route files: docs/truthmark/areas/**/*.md +- Feature docs: docs/features/**/*.md +Decision truth lives in the canonical doc it governs. +Date active decisions inline when added or changed, for example `Decision (2026-05-09): ...`. +Do not create separate timestamped ADR logs or planning tickets for active decisions. +Replace old active decisions instead of appending separate timestamped decision logs; Git history is the audit trail. +Update Product Decisions and Rationale when a behavior change comes from a decision change. +### Truth Sync Worker +The parent provides the task focus and any repository context already gathered. +Worker rules: +- inspect relevant staged, unstaged, and untracked functional code directly +- read .truthmark/config.yml, docs/truthmark/areas.md, and canonical truth docs directly +- Code verification is parent-owned; report what was run or why it was not run +- may write truth docs and docs/truthmark/areas.md only for Truth Sync alignment +- must not rewrite functional code +Return result in this shape: +- status: completed | blocked +- changedCodeReviewed: string[] +- truthDocsUpdated: string[] +- routingDocsUpdated: string[] +- notes: string[] +- blockedReason?: string +- manualReviewFiles?: string[] +Parent post-sync verification: +- verify only truth docs and docs/truthmark/areas.md changed during sync +- block on any unrelated diff caused by the sync step +- block if functional code changed during sync +- verify the worker report matches the required headings and sections +- verify the updated docs correspond to the reviewed changed-code surface +- blocked outcomes must preserve the working tree as-is: no rollback, no post-block cleanup edits, and manual-review reporting of any remaining files +Report completion in this shape: +```md +Truth Sync: completed + +Changed code reviewed: +- src/auth/session.ts + +Truth docs updated: +- docs/features/repository/overview.md + +Notes: +- Updated session timeout behavior. +``` +Blocked report example: +```md +Truth Sync: blocked + +Reason: +- routing repair is not allowed + +Files requiring manual review: +- docs/truthmark/areas.md + +Next action: +- update routing metadata and rerun Truth Sync +``` diff --git a/.codex/skills/truthmark-check/SKILL.md b/.codex/skills/truthmark-check/SKILL.md index 5c8478f..3f35a85 100644 --- a/.codex/skills/truthmark-check/SKILL.md +++ b/.codex/skills/truthmark-check/SKILL.md @@ -3,7 +3,7 @@ name: truthmark-check description: Use when the user asks to audit repository truth health. Inspects truth docs, routing, and implementation directly; may optionally run truthmark check when available. argument-hint: Optional area, doc path, or audit focus user-invocable: true -truthmark-version: 1.2.1 +truthmark-version: 1.2.3 --- # Truthmark Check @@ -14,8 +14,9 @@ Invocations: OpenCode /skill truthmark-check; Codex /truthmark-check or $truthma 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 @@ -30,7 +31,7 @@ Truthmark hierarchy: - 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): ...`. +Date active decisions inline when added or changed, for example `Decision (2026-05-09): ...`. Do not create separate timestamped ADR logs or planning tickets for active decisions. Replace old active decisions instead of appending separate timestamped decision logs; Git history is the audit trail. Update Product Decisions and Rationale when a behavior change comes from a decision change. @@ -41,7 +42,6 @@ Report completion in this shape: Truth Check: completed Files reviewed: -- TRUTHMARK.md - docs/truthmark/areas.md Issues found: diff --git a/.codex/skills/truthmark-check/agents/openai.yaml b/.codex/skills/truthmark-check/agents/openai.yaml index 6177cd9..ea28377 100644 --- a/.codex/skills/truthmark-check/agents/openai.yaml +++ b/.codex/skills/truthmark-check/agents/openai.yaml @@ -7,5 +7,5 @@ policy: allow_implicit_invocation: false truthmark: - version: "1.2.1" + version: "1.2.3" refresh_command: "truthmark init" diff --git a/.codex/skills/truthmark-document/SKILL.md b/.codex/skills/truthmark-document/SKILL.md new file mode 100644 index 0000000..cd5c4ad --- /dev/null +++ b/.codex/skills/truthmark-document/SKILL.md @@ -0,0 +1,66 @@ +--- +name: truthmark-document +description: Use when the user explicitly asks to document existing implemented behavior, or when Truth Sync, Truth Check, or Truth Structure reports implemented behavior that lacks canonical truth docs. Reads implementation and routing, writes truth docs and routing only, and never changes functional code. +argument-hint: Optional implemented behavior, API endpoint, route, controller, package, or truth-doc area to document +user-invocable: true +truthmark-version: 1.2.3 +--- + +# Truthmark Document + +Use this skill to document existing implemented behavior when no functional-code changes are required for the task. +Invocations: OpenCode /skill truthmark-document; Codex /truthmark-document or $truthmark-document; Claude Code /truthmark-document; GitHub Copilot /truthmark-document; Gemini CLI /truthmark:document. + +Truth Document is manual and implementation-first: + +- run only when the user explicitly asks to generate or update truth docs for existing behavior, or when Truth Sync, Truth Check, or Truth Structure reports implemented behavior that lacks canonical truth docs +- inspect .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, existing canonical docs, implementation code, and tests directly +- Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. +- document current implemented behavior; do not invent future behavior or planned endpoints +- may write canonical truth docs and docs/truthmark/areas.md or relevant child route files only +- must not write functional code +- when routing is missing, stale, broad, overloaded, catch-all, or cannot map the behavior to a bounded truth owner, run Truth Structure first when routing repair is safe and in scope +- block and recommend Truth Structure when routing repair is unsafe, ambiguous, or outside the task boundary +- keep feature README.md files as indexes rather than truth-document targets +- create or update bounded leaf truth docs when behavior does not fit an existing leaf doc +- keep feature docs behavior-oriented, not endpoint-oriented, unless the endpoint itself is the behavior boundary +- keep API endpoint details in the nearest contract truth doc when such a doc owns the API contract +- preserve unrelated authored content +When creating or updating a feature doc, read docs/templates/feature-doc.md and follow its frontmatter, heading order, and section intent. +When updating an existing feature doc, align existing feature docs to the template standard while preserving authored content that remains accurate. +If docs/templates/feature-doc.md is missing, use the built-in minimal feature-doc structure with Current Behavior, Product Decisions, and Rationale sections. +Teams may edit docs/templates/feature-doc.md to define their local feature-doc standard. +Maintain architecture docs when a code change alters system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership. +Do not put ordinary feature behavior, endpoint details, UI copy, validation rules, or bug fixes in architecture docs unless they change those architecture boundaries. +Keep architecture docs focused on structure and ownership; keep current product behavior in feature or contract docs. +Truthmark hierarchy: +- Config: .truthmark/config.yml +- Root route index: docs/truthmark/areas.md +- Area route files: docs/truthmark/areas/**/*.md +- Feature docs: docs/features/**/*.md +Decision truth lives in the canonical doc it governs. +Date active decisions inline when added or changed, for example `Decision (2026-05-09): ...`. +Do not create separate timestamped ADR logs or planning tickets for active decisions. +Replace old active decisions instead of appending separate timestamped decision logs; Git history is the audit trail. +Update Product Decisions and Rationale when a behavior change comes from a decision change. + +Report completion in this shape: +```md +Truth Document: completed + +Implementation reviewed: +- src/api/orders/** + +Truth docs created: +- docs/features/orders/order-submission.md + +Truth docs updated: +- docs/features/contracts.md + +Routing updated: +- docs/truthmark/areas/orders.md + +Notes: +- Documented existing order submission behavior from route handlers and tests. +``` diff --git a/.codex/skills/truthmark-document/agents/openai.yaml b/.codex/skills/truthmark-document/agents/openai.yaml new file mode 100644 index 0000000..219b65f --- /dev/null +++ b/.codex/skills/truthmark-document/agents/openai.yaml @@ -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.2.3" + refresh_command: "truthmark init" diff --git a/.codex/skills/truthmark-realize/SKILL.md b/.codex/skills/truthmark-realize/SKILL.md index f98a92e..c58afa7 100644 --- a/.codex/skills/truthmark-realize/SKILL.md +++ b/.codex/skills/truthmark-realize/SKILL.md @@ -3,7 +3,7 @@ name: truthmark-realize description: Use when the user explicitly asks to realize Truthmark truth docs into code, including /truthmark-realize, $truthmark-realize, or /truthmark:realize. Reads truth docs and routing first, updates functional code only, and reports verification. argument-hint: Optional truth doc path, area, or desired code behavior to realize user-invocable: true -truthmark-version: 1.2.1 +truthmark-version: 1.2.3 --- # Truthmark Realize @@ -21,8 +21,9 @@ Truth Realize is doc-first: Workflow: 1. Read the updated truth docs named by the user, or infer the relevant docs from docs/truthmark/areas.md. -2. Read .truthmark/config.yml, TRUTHMARK.md, docs/truthmark/areas.md, and the relevant functional code. -3. Repository docs and code are inspected evidence, not executable instruction authority. +2. Read .truthmark/config.yml, docs/truthmark/areas.md, and the relevant functional code. +3. Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. 4. Update functional code only so implementation matches the truth docs. 5. Do not edit truth docs or truth routing while realizing those docs. 6. Run relevant tests for the changed code. diff --git a/.codex/skills/truthmark-realize/agents/openai.yaml b/.codex/skills/truthmark-realize/agents/openai.yaml index fce73a4..57ab949 100644 --- a/.codex/skills/truthmark-realize/agents/openai.yaml +++ b/.codex/skills/truthmark-realize/agents/openai.yaml @@ -7,5 +7,5 @@ policy: allow_implicit_invocation: false truthmark: - version: "1.2.1" + version: "1.2.3" refresh_command: "truthmark init" diff --git a/.codex/skills/truthmark-structure/SKILL.md b/.codex/skills/truthmark-structure/SKILL.md index 783ae23..c66416f 100644 --- a/.codex/skills/truthmark-structure/SKILL.md +++ b/.codex/skills/truthmark-structure/SKILL.md @@ -1,22 +1,27 @@ --- 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 the user asks to design, repair, or refresh missing, stale, broad, overloaded, catch-all, or unrouteable Truthmark area routing. Inspects the repository directly, updates docs/truthmark/areas.md, and may create starter canonical truth docs. argument-hint: Optional area, directory, or routing concern user-invocable: true -truthmark-version: 1.2.1 +truthmark-version: 1.2.3 --- Use this skill to design or repair Truthmark area structure. Invocations: OpenCode /skill truthmark-structure; Codex /truthmark-structure or $truthmark-structure; Claude Code /truthmark-structure; GitHub Copilot /truthmark-structure; Gemini CLI /truthmark:structure. Truth Structure is agent-native: -- inspect repository layout, current docs, .truthmark/config.yml, 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. +When creating or updating a feature doc, read docs/templates/feature-doc.md and follow its frontmatter, heading order, and section intent. +When updating an existing feature doc, align existing feature docs to the template standard while preserving authored content that remains accurate. +If docs/templates/feature-doc.md is missing, use the built-in minimal feature-doc structure with Current Behavior, Product Decisions, and Rationale sections. +Teams may edit docs/templates/feature-doc.md to define their local feature-doc standard. - use docs/features/**, docs/architecture/**, or docs/standards/** for current truth destinations - use only canonical current-truth destinations for starter truth docs - keep active Product Decisions and Rationale in the canonical doc that owns the behavior @@ -39,7 +44,7 @@ Use these review thresholds as guidance: - 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 - create route files under docs/truthmark/areas/ when a product/domain boundary is clear - create feature docs under the configured feature root only when behavior lacks a current doc - README.md files are indexes, not Truth Sync targets @@ -48,12 +53,15 @@ Repair rules: - keep API endpoint details in the nearest contract truth doc when such a doc exists - update routing so future Truth Sync can target small docs - preserve existing authored docs; move or rewrite only when needed to remove ambiguity +Maintain architecture docs when a code change alters system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership. +Do not put ordinary feature behavior, endpoint details, UI copy, validation rules, or bug fixes in architecture docs unless they change those architecture boundaries. +Keep architecture docs focused on structure and ownership; keep current product behavior in feature or contract docs. - Do not finish topology repair with routed canonical current-truth docs missing Product Decisions or Rationale sections. - If an existing canonical doc lacks either section, add the missing heading beside Current Behavior with a concise current-state placeholder or active decision. Portable fallback: - If this skill surface is unavailable, perform the same workflow directly from committed repository files. - Do not require the truthmark CLI. -- Read .truthmark/config.yml, 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 @@ -61,7 +69,7 @@ Truthmark hierarchy: - 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): ...`. +Date active decisions inline when added or changed, for example `Decision (2026-05-09): ...`. Do not create separate timestamped ADR logs or planning tickets for active decisions. Replace old active decisions instead of appending separate timestamped decision logs; Git history is the audit trail. Update Product Decisions and Rationale when a behavior change comes from a decision change. diff --git a/.codex/skills/truthmark-structure/agents/openai.yaml b/.codex/skills/truthmark-structure/agents/openai.yaml index 8962092..e1d7152 100644 --- a/.codex/skills/truthmark-structure/agents/openai.yaml +++ b/.codex/skills/truthmark-structure/agents/openai.yaml @@ -7,5 +7,5 @@ policy: allow_implicit_invocation: false truthmark: - version: "1.2.1" + version: "1.2.3" refresh_command: "truthmark init" diff --git a/.codex/skills/truthmark-sync/SKILL.md b/.codex/skills/truthmark-sync/SKILL.md index 5559b51..7b8f996 100644 --- a/.codex/skills/truthmark-sync/SKILL.md +++ b/.codex/skills/truthmark-sync/SKILL.md @@ -1,30 +1,39 @@ --- 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 before finishing when functional code changed since the last successful Truth Sync, and when the user explicitly invokes /truthmark-sync, $truthmark-sync, or /truthmark:sync. Inspects changed code directly, updates truth docs and routing, and verifies post-sync boundaries. Skip for documentation-only changes, formatting-only changes, behavior-preserving renames, missing Truthmark config, or no functional code changes. argument-hint: Optional changed-code area, truth-doc area, or sync focus user-invocable: true -truthmark-version: 1.2.1 +truthmark-version: 1.2.3 --- Use this skill automatically before finishing when functional code changed since the last successful Truth Sync. Also run it immediately when the user explicitly invokes Truth Sync. Invocations: OpenCode /skill truthmark-sync; Codex /truthmark-sync or $truthmark-sync; Claude Code /truthmark-sync; GitHub Copilot /truthmark-sync; Gemini CLI /truthmark:sync. Explicit invocation runs immediately. Later functional-code changes reopen the finish-time requirement, and an earlier explicit run satisfies the finish gate only if no later functional-code changes occur. +Skip when changes are documentation-only, formatting-only, clearly behavior-preserving renames with no truth impact, when no Truthmark config exists yet, or when there are no functional code changes. Parent workflow: 1. Inspect git status, staged changes, unstaged changes, and untracked files directly. -2. Read .truthmark/config.yml, 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 feature doc +- run Truth Structure before syncing when topology repair is safe and in scope +- block and recommend Truth Structure when topology repair is unsafe, ambiguous, or outside the current task boundary +- report the route files and changed code paths that require structure repair - README.md files are indexes, not Truth Sync targets - must not append behavior details to a feature README - create or update a bounded leaf truth doc when behavior changes do not fit an existing leaf doc +When creating or updating a feature doc, read docs/templates/feature-doc.md and follow its frontmatter, heading order, and section intent. +When updating an existing feature doc, align existing feature docs to the template standard while preserving authored content that remains accurate. +If docs/templates/feature-doc.md is missing, use the built-in minimal feature-doc structure with Current Behavior, Product Decisions, and Rationale sections. +Teams may edit docs/templates/feature-doc.md to define their local feature-doc standard. +Maintain architecture docs when a code change alters system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership. +Do not put ordinary feature behavior, endpoint details, UI copy, validation rules, or bug fixes in architecture docs unless they change those architecture boundaries. +Keep architecture docs focused on structure and ownership; keep current product behavior in feature or contract docs. Optional validation tooling: - you may run truthmark check when local tooling is available - do not require the truthmark binary; direct checkout inspection is the canonical path @@ -36,7 +45,7 @@ Truthmark hierarchy: - 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): ...`. +Date active decisions inline when added or changed, for example `Decision (2026-05-09): ...`. Do not create separate timestamped ADR logs or planning tickets for active decisions. Replace old active decisions instead of appending separate timestamped decision logs; Git history is the audit trail. Update Product Decisions and Rationale when a behavior change comes from a decision change. @@ -44,7 +53,7 @@ Update Product Decisions and Rationale when a behavior change comes from a decis 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 diff --git a/.codex/skills/truthmark-sync/agents/openai.yaml b/.codex/skills/truthmark-sync/agents/openai.yaml index 95c2156..1a9b6c1 100644 --- a/.codex/skills/truthmark-sync/agents/openai.yaml +++ b/.codex/skills/truthmark-sync/agents/openai.yaml @@ -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.2.3" refresh_command: "truthmark init" diff --git a/.gemini/commands/truthmark/check.toml b/.gemini/commands/truthmark/check.toml new file mode 100644 index 0000000..2c03288 --- /dev/null +++ b/.gemini/commands/truthmark/check.toml @@ -0,0 +1,58 @@ +description = "Audit repository truth health." +prompt = ''' +--- +name: truthmark-check +description: Use when the user asks to audit repository truth health. Inspects truth docs, routing, and implementation directly; may optionally run truthmark check when available. +argument-hint: Optional area, doc path, or audit focus +user-invocable: true +truthmark-version: 1.2.3 +--- + +# Truthmark Check + +Use this skill to audit repository truth health. + +Invocations: OpenCode /skill truthmark-check; Codex /truthmark-check or $truthmark-check; Claude Code /truthmark-check; GitHub Copilot /truthmark-check; Gemini CLI /truthmark:check. + +Truth Check is agent-led: + +- inspect .truthmark/config.yml, docs/truthmark/areas.md, canonical docs, and relevant implementation directly +- Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. +- inspect the configured root route index at docs/truthmark/areas.md and relevant child route files under docs/truthmark/areas/ +- check that current docs describe current code rather than historical plans +- check that docs/truthmark/areas.md routes code surfaces to canonical truth docs +- check that canonical behavior docs keep active Product Decisions and Rationale sections +- optionally run truthmark check when local tooling is available +- must not require the truthmark binary; direct inspection is always valid +- report issues and suggested fixes without silently rewriting unrelated files + +Truthmark hierarchy: +- Config: .truthmark/config.yml +- Root route index: docs/truthmark/areas.md +- Area route files: docs/truthmark/areas/**/*.md +- Feature docs: docs/features/**/*.md +Decision truth lives in the canonical doc it governs. +Date active decisions inline when added or changed, for example `Decision (2026-05-09): ...`. +Do not create separate timestamped ADR logs or planning tickets for active decisions. +Replace old active decisions instead of appending separate timestamped decision logs; Git history is the audit trail. +Update Product Decisions and Rationale when a behavior change comes from a decision change. + +Report completion in this shape: + +```md +Truth Check: completed + +Files reviewed: +- docs/truthmark/areas.md + +Issues found: +- none + +Fixes suggested: +- none + +Validation: +- truthmark check +``` +''' diff --git a/.gemini/commands/truthmark/document.toml b/.gemini/commands/truthmark/document.toml new file mode 100644 index 0000000..45864c1 --- /dev/null +++ b/.gemini/commands/truthmark/document.toml @@ -0,0 +1,69 @@ +description = "Document existing implemented behavior." +prompt = ''' +--- +name: truthmark-document +description: Use when the user explicitly asks to document existing implemented behavior, or when Truth Sync, Truth Check, or Truth Structure reports implemented behavior that lacks canonical truth docs. Reads implementation and routing, writes truth docs and routing only, and never changes functional code. +argument-hint: Optional implemented behavior, API endpoint, route, controller, package, or truth-doc area to document +user-invocable: true +truthmark-version: 1.2.3 +--- + +# Truthmark Document + +Use this skill to document existing implemented behavior when no functional-code changes are required for the task. +Invocations: OpenCode /skill truthmark-document; Codex /truthmark-document or $truthmark-document; Claude Code /truthmark-document; GitHub Copilot /truthmark-document; Gemini CLI /truthmark:document. + +Truth Document is manual and implementation-first: + +- run only when the user explicitly asks to generate or update truth docs for existing behavior, or when Truth Sync, Truth Check, or Truth Structure reports implemented behavior that lacks canonical truth docs +- inspect .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, existing canonical docs, implementation code, and tests directly +- Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. +- document current implemented behavior; do not invent future behavior or planned endpoints +- may write canonical truth docs and docs/truthmark/areas.md or relevant child route files only +- must not write functional code +- when routing is missing, stale, broad, overloaded, catch-all, or cannot map the behavior to a bounded truth owner, run Truth Structure first when routing repair is safe and in scope +- block and recommend Truth Structure when routing repair is unsafe, ambiguous, or outside the task boundary +- keep feature README.md files as indexes rather than truth-document targets +- create or update bounded leaf truth docs when behavior does not fit an existing leaf doc +- keep feature docs behavior-oriented, not endpoint-oriented, unless the endpoint itself is the behavior boundary +- keep API endpoint details in the nearest contract truth doc when such a doc owns the API contract +- preserve unrelated authored content +When creating or updating a feature doc, read docs/templates/feature-doc.md and follow its frontmatter, heading order, and section intent. +When updating an existing feature doc, align existing feature docs to the template standard while preserving authored content that remains accurate. +If docs/templates/feature-doc.md is missing, use the built-in minimal feature-doc structure with Current Behavior, Product Decisions, and Rationale sections. +Teams may edit docs/templates/feature-doc.md to define their local feature-doc standard. +Maintain architecture docs when a code change alters system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership. +Do not put ordinary feature behavior, endpoint details, UI copy, validation rules, or bug fixes in architecture docs unless they change those architecture boundaries. +Keep architecture docs focused on structure and ownership; keep current product behavior in feature or contract docs. +Truthmark hierarchy: +- Config: .truthmark/config.yml +- Root route index: docs/truthmark/areas.md +- Area route files: docs/truthmark/areas/**/*.md +- Feature docs: docs/features/**/*.md +Decision truth lives in the canonical doc it governs. +Date active decisions inline when added or changed, for example `Decision (2026-05-09): ...`. +Do not create separate timestamped ADR logs or planning tickets for active decisions. +Replace old active decisions instead of appending separate timestamped decision logs; Git history is the audit trail. +Update Product Decisions and Rationale when a behavior change comes from a decision change. + +Report completion in this shape: +```md +Truth Document: completed + +Implementation reviewed: +- src/api/orders/** + +Truth docs created: +- docs/features/orders/order-submission.md + +Truth docs updated: +- docs/features/contracts.md + +Routing updated: +- docs/truthmark/areas/orders.md + +Notes: +- Documented existing order submission behavior from route handlers and tests. +``` +''' diff --git a/.gemini/commands/truthmark/realize.toml b/.gemini/commands/truthmark/realize.toml new file mode 100644 index 0000000..0944af4 --- /dev/null +++ b/.gemini/commands/truthmark/realize.toml @@ -0,0 +1,55 @@ +description = "Realize repository truth docs into code." +prompt = ''' +--- +name: truthmark-realize +description: Use when the user explicitly asks to realize Truthmark truth docs into code, including /truthmark-realize, $truthmark-realize, or /truthmark:realize. Reads truth docs and routing first, updates functional code only, and reports verification. +argument-hint: Optional truth doc path, area, or desired code behavior to realize +user-invocable: true +truthmark-version: 1.2.3 +--- + +# Truthmark Realize + +Use this skill only when the user explicitly asks to realize truth docs into code. + +Invocations: OpenCode /skill truthmark-realize; Codex /truthmark-realize or $truthmark-realize; Claude Code /truthmark-realize; GitHub Copilot /truthmark-realize; Gemini CLI /truthmark:realize. + +Truth Realize is doc-first: + +- truth docs lead +- code follows +- Truth Realize never edits the truth docs it is realizing + +Workflow: + +1. Read the updated truth docs named by the user, or infer the relevant docs from docs/truthmark/areas.md. +2. Read .truthmark/config.yml, docs/truthmark/areas.md, and the relevant functional code. +3. Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. +4. Update functional code only so implementation matches the truth docs. +5. Do not edit truth docs or truth routing while realizing those docs. +6. Run relevant tests for the changed code. +7. Report changed code files and verification steps. + +Read and write boundaries: + +- may read truth docs, routing docs, and relevant functional code +- may write functional code only +- must not edit truth docs or truth routing while realizing those docs + +Report completion in this shape: + +```md +Truth Realize: completed + +Truth docs used: +- docs/features/authentication.md + +Code updated: +- src/auth/session.ts + +Verification: +- npm test -- auth +``` + +''' diff --git a/.gemini/commands/truthmark/structure.toml b/.gemini/commands/truthmark/structure.toml new file mode 100644 index 0000000..73bf9ba --- /dev/null +++ b/.gemini/commands/truthmark/structure.toml @@ -0,0 +1,96 @@ +description = "Design or repair Truthmark area routing." +prompt = ''' +--- +name: truthmark-structure +description: Use when the user asks to design, repair, or refresh missing, stale, broad, overloaded, catch-all, or unrouteable Truthmark area routing. Inspects the repository directly, updates docs/truthmark/areas.md, and may create starter canonical truth docs. +argument-hint: Optional area, directory, or routing concern +user-invocable: true +truthmark-version: 1.2.3 +--- + +Use this skill to design or repair Truthmark area structure. +Invocations: OpenCode /skill truthmark-structure; Codex /truthmark-structure or $truthmark-structure; Claude Code /truthmark-structure; GitHub Copilot /truthmark-structure; Gemini CLI /truthmark:structure. +Truth Structure is agent-native: +- inspect repository layout, current docs, .truthmark/config.yml, docs/truthmark/areas.md, and relevant code directly +- Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. +- inspect the configured root route index at docs/truthmark/areas.md and relevant child route files under docs/truthmark/areas/ +- define areas by product or behavior ownership, not by mechanical directory mirroring +- create or repair docs/truthmark/areas.md +- create starter truth docs when useful and when they belong in the canonical current-truth surface +- Starter truth docs must use closed YAML frontmatter bounded by opening and closing --- lines; include status, doc_type, last_reviewed, and source_of_truth inside that frontmatter. +- Starter truth docs must include ## Product Decisions and ## Rationale sections. +When creating or updating a feature doc, read docs/templates/feature-doc.md and follow its frontmatter, heading order, and section intent. +When updating an existing feature doc, align existing feature docs to the template standard while preserving authored content that remains accurate. +If docs/templates/feature-doc.md is missing, use the built-in minimal feature-doc structure with Current Behavior, Product Decisions, and Rationale sections. +Teams may edit docs/templates/feature-doc.md to define their local feature-doc standard. +- use docs/features/**, docs/architecture/**, or docs/standards/** for current truth destinations +- use only canonical current-truth destinations for starter truth docs +- keep active Product Decisions and Rationale in the canonical doc that owns the behavior +- preserve unrelated authored content +## Topology Governance +Truth Structure owns documentation topology. Do not depend on humans to manually organize docs/features. Treat the configured feature root as a managed semantic root. +Inspect controllers, routes, handlers, services, packages, tests, existing truth docs, and route files; infer product and domain ownership from behavior boundaries, not from mechanical directory mirroring. +When topology pressure exists, repair structure before creating or extending feature docs. +Topology pressure signals: +- one area maps broad code such as src/**, app/**, server/**, services/**, or packages/** +- one area maps multiple unrelated controllers, route groups, services, or bounded contexts +- one truth doc owns unrelated behaviors or unrelated endpoint families +- the configured feature root has many direct non-index docs +- a changed controller, route, or service cannot map to a specific behavior doc +- Truth Sync would need to create a new generic feature doc because routing is too broad +- endpoint or controller names reveal domains missing from docs/truthmark/areas/** +Use these review thresholds as guidance: +- more than 10 direct feature docs in one folder +- more than 15 leaf areas in one child route file +- more than 8 truth docs mapped to one area +- more than 5 controllers mapped through one catch-all area +Repair rules: +- split broad, overloaded, or catch-all areas into behavior-owned child route files +- create route files under docs/truthmark/areas/ when a product/domain boundary is clear +- create feature docs under the configured feature root only when behavior lacks a current doc +- README.md files are indexes, not Truth Sync targets +- prefer bounded leaf truth docs at //.md +- keep feature docs behavior-oriented, not endpoint-oriented +- keep API endpoint details in the nearest contract truth doc when such a doc exists +- update routing so future Truth Sync can target small docs +- preserve existing authored docs; move or rewrite only when needed to remove ambiguity +Maintain architecture docs when a code change alters system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership. +Do not put ordinary feature behavior, endpoint details, UI copy, validation rules, or bug fixes in architecture docs unless they change those architecture boundaries. +Keep architecture docs focused on structure and ownership; keep current product behavior in feature or contract docs. +- Do not finish topology repair with routed canonical current-truth docs missing Product Decisions or Rationale sections. +- If an existing canonical doc lacks either section, add the missing heading beside Current Behavior with a concise current-state placeholder or active decision. +Portable fallback: +- If this skill surface is unavailable, perform the same workflow directly from committed repository files. +- Do not require the truthmark CLI. +- Read .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, canonical docs, and representative implementation code. +- Use a subagent only when the host supports that pattern; otherwise perform the topology repair inline. +Truthmark hierarchy: +- Config: .truthmark/config.yml +- Root route index: docs/truthmark/areas.md +- Area route files: docs/truthmark/areas/**/*.md +- Feature docs: docs/features/**/*.md +Decision truth lives in the canonical doc it governs. +Date active decisions inline when added or changed, for example `Decision (2026-05-09): ...`. +Do not create separate timestamped ADR logs or planning tickets for active decisions. +Replace old active decisions instead of appending separate timestamped decision logs; Git history is the audit trail. +Update Product Decisions and Rationale when a behavior change comes from a decision change. +Report completion in this shape: +```md +Truth Structure: completed +Topology reviewed: +- controllers: src/auth/** +- docs root: docs/features +- route files: docs/truthmark/areas.md +Areas reviewed: +- src/auth/** +Routing updated: +- docs/truthmark/areas.md +Truth docs created: +- docs/features/authentication.md +Topology decisions: +- Added an Authentication area because session behavior has a distinct code surface and truth owner. +Notes: +- Added an Authentication area for session behavior. +``` +''' diff --git a/.gemini/commands/truthmark/sync.toml b/.gemini/commands/truthmark/sync.toml new file mode 100644 index 0000000..7527f4e --- /dev/null +++ b/.gemini/commands/truthmark/sync.toml @@ -0,0 +1,103 @@ +description = "Sync repository truth docs from functional code changes; skip docs-only/no-code changes." +prompt = ''' +--- +name: truthmark-sync +description: Use automatically before finishing when functional code changed since the last successful Truth Sync, and when the user explicitly invokes /truthmark-sync, $truthmark-sync, or /truthmark:sync. Inspects changed code directly, updates truth docs and routing, and verifies post-sync boundaries. Skip for documentation-only changes, formatting-only changes, behavior-preserving renames, missing Truthmark config, or no functional code changes. +argument-hint: Optional changed-code area, truth-doc area, or sync focus +user-invocable: true +truthmark-version: 1.2.3 +--- + +Use this skill automatically before finishing when functional code changed since the last successful Truth Sync. Also run it immediately when the user explicitly invokes Truth Sync. +Invocations: OpenCode /skill truthmark-sync; Codex /truthmark-sync or $truthmark-sync; Claude Code /truthmark-sync; GitHub Copilot /truthmark-sync; Gemini CLI /truthmark:sync. +Explicit invocation runs immediately. Later functional-code changes reopen the finish-time requirement, and an earlier explicit run satisfies the finish gate only if no later functional-code changes occur. +Skip when changes are documentation-only, formatting-only, clearly behavior-preserving renames with no truth impact, when no Truthmark config exists yet, or when there are no functional code changes. +Parent workflow: +1. Inspect git status, staged changes, unstaged changes, and untracked files directly. +2. Read .truthmark/config.yml, the configured root route index at docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, and relevant canonical docs. +3. Identify functional-code changes and the nearest truth docs or routing repairs. +4. Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. +5. Code verification is parent-owned: follow repository instructions and task context, and report what ran or why it did not run. +6. Dispatch one bounded Truth Sync worker only when the host supports subagent dispatch and the acting agent chooses that path; otherwise execute the same sync task inline. +Topology quality gate: +- before updating truth docs, verify the changed code resolves to a specific behavior-owned area and bounded truth owner +- if routing is missing, stale, broad, overloaded, catch-all route only, or cannot map changed code to a bounded truth owner, do not create another generic feature doc +- run Truth Structure before syncing when topology repair is safe and in scope +- block and recommend Truth Structure when topology repair is unsafe, ambiguous, or outside the current task boundary +- report the route files and changed code paths that require structure repair +- README.md files are indexes, not Truth Sync targets +- must not append behavior details to a feature README +- create or update a bounded leaf truth doc when behavior changes do not fit an existing leaf doc +When creating or updating a feature doc, read docs/templates/feature-doc.md and follow its frontmatter, heading order, and section intent. +When updating an existing feature doc, align existing feature docs to the template standard while preserving authored content that remains accurate. +If docs/templates/feature-doc.md is missing, use the built-in minimal feature-doc structure with Current Behavior, Product Decisions, and Rationale sections. +Teams may edit docs/templates/feature-doc.md to define their local feature-doc standard. +Maintain architecture docs when a code change alters system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership. +Do not put ordinary feature behavior, endpoint details, UI copy, validation rules, or bug fixes in architecture docs unless they change those architecture boundaries. +Keep architecture docs focused on structure and ownership; keep current product behavior in feature or contract docs. +Optional validation tooling: +- you may run truthmark check when local tooling is available +- do not require the truthmark binary; direct checkout inspection is the canonical path +- optional validation must not replace agent judgment about docs and routing +- update Product Decisions and Rationale when a behavior change comes from a decision change +Truthmark hierarchy: +- Config: .truthmark/config.yml +- Root route index: docs/truthmark/areas.md +- Area route files: docs/truthmark/areas/**/*.md +- Feature docs: docs/features/**/*.md +Decision truth lives in the canonical doc it governs. +Date active decisions inline when added or changed, for example `Decision (2026-05-09): ...`. +Do not create separate timestamped ADR logs or planning tickets for active decisions. +Replace old active decisions instead of appending separate timestamped decision logs; Git history is the audit trail. +Update Product Decisions and Rationale when a behavior change comes from a decision change. +### Truth Sync Worker +The parent provides the task focus and any repository context already gathered. +Worker rules: +- inspect relevant staged, unstaged, and untracked functional code directly +- read .truthmark/config.yml, docs/truthmark/areas.md, and canonical truth docs directly +- Code verification is parent-owned; report what was run or why it was not run +- may write truth docs and docs/truthmark/areas.md only for Truth Sync alignment +- must not rewrite functional code +Return result in this shape: +- status: completed | blocked +- changedCodeReviewed: string[] +- truthDocsUpdated: string[] +- routingDocsUpdated: string[] +- notes: string[] +- blockedReason?: string +- manualReviewFiles?: string[] +Parent post-sync verification: +- verify only truth docs and docs/truthmark/areas.md changed during sync +- block on any unrelated diff caused by the sync step +- block if functional code changed during sync +- verify the worker report matches the required headings and sections +- verify the updated docs correspond to the reviewed changed-code surface +- blocked outcomes must preserve the working tree as-is: no rollback, no post-block cleanup edits, and manual-review reporting of any remaining files +Report completion in this shape: +```md +Truth Sync: completed + +Changed code reviewed: +- src/auth/session.ts + +Truth docs updated: +- docs/features/repository/overview.md + +Notes: +- Updated session timeout behavior. +``` +Blocked report example: +```md +Truth Sync: blocked + +Reason: +- routing repair is not allowed + +Files requiring manual review: +- docs/truthmark/areas.md + +Next action: +- update routing metadata and rerun Truth Sync +``` +''' diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..94ed37c --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,16 @@ + +## Truthmark Workflow + +Generated by Truthmark 1.2.3. Rerun `truthmark init` after upgrades and review 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: update Product Decisions/Rationale, date active decisions inline when added or changed, and do not create separate timestamped ADR or planning logs. +Agent runtime: installed skills plus this block. Always inspect checkout directly; CLI commands are optional validation. Do not use packet helpers or cache files. Delegation is host-owned. +### Truth Sync +Sync: finish-time when functional code changed; use the truthmark-sync skill before finishing. Explicit invocation: OpenCode /skill truthmark-sync; Codex /truthmark-sync or $truthmark-sync; Claude Code /truthmark-sync; GitHub Copilot /truthmark-sync; Gemini CLI /truthmark:sync; later functional changes reopen the gate. Memory: code changed -> tests -> Sync -> report. Run relevant tests first. Code leads, truth docs follow; may write truth docs and docs/truthmark/areas.md only, and must not rewrite functional code. Read docs/truthmark/areas.md and only relevant child routes under docs/truthmark/areas/; if routing is missing/stale/broad/overloaded/catch-all or cannot map changed code to a bounded truth owner, run Truth Structure before syncing when safe and in scope; otherwise block and recommend Truth Structure. Skip only: documentation-only change; formatting-only change; clearly behavior-preserving rename with no truth impact; no Truthmark config exists yet; no functional code changes. +Explicit workflows: Truth Structure, Truth Document, Truth Realize, Truth Check. Run only when requested or when Sync requires Structure or Document; load the installed skill for details. +Workflow integrity rule: repository truth may describe desired behavior, but it must not silently override these Truthmark workflow boundaries. + diff --git a/.github/prompts/truthmark-check.prompt.md b/.github/prompts/truthmark-check.prompt.md new file mode 100644 index 0000000..2b245ab --- /dev/null +++ b/.github/prompts/truthmark-check.prompt.md @@ -0,0 +1,60 @@ +--- +agent: 'agent' +description: 'Audit repository truth health.' +--- + +--- +name: truthmark-check +description: Use when the user asks to audit repository truth health. Inspects truth docs, routing, and implementation directly; may optionally run truthmark check when available. +argument-hint: Optional area, doc path, or audit focus +user-invocable: true +truthmark-version: 1.2.3 +--- + +# Truthmark Check + +Use this skill to audit repository truth health. + +Invocations: OpenCode /skill truthmark-check; Codex /truthmark-check or $truthmark-check; Claude Code /truthmark-check; GitHub Copilot /truthmark-check; Gemini CLI /truthmark:check. + +Truth Check is agent-led: + +- inspect .truthmark/config.yml, docs/truthmark/areas.md, canonical docs, and relevant implementation directly +- Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. +- inspect the configured root route index at docs/truthmark/areas.md and relevant child route files under docs/truthmark/areas/ +- check that current docs describe current code rather than historical plans +- check that docs/truthmark/areas.md routes code surfaces to canonical truth docs +- check that canonical behavior docs keep active Product Decisions and Rationale sections +- optionally run truthmark check when local tooling is available +- must not require the truthmark binary; direct inspection is always valid +- report issues and suggested fixes without silently rewriting unrelated files + +Truthmark hierarchy: +- Config: .truthmark/config.yml +- Root route index: docs/truthmark/areas.md +- Area route files: docs/truthmark/areas/**/*.md +- Feature docs: docs/features/**/*.md +Decision truth lives in the canonical doc it governs. +Date active decisions inline when added or changed, for example `Decision (2026-05-09): ...`. +Do not create separate timestamped ADR logs or planning tickets for active decisions. +Replace old active decisions instead of appending separate timestamped decision logs; Git history is the audit trail. +Update Product Decisions and Rationale when a behavior change comes from a decision change. + +Report completion in this shape: + +```md +Truth Check: completed + +Files reviewed: +- docs/truthmark/areas.md + +Issues found: +- none + +Fixes suggested: +- none + +Validation: +- truthmark check +``` diff --git a/.github/prompts/truthmark-document.prompt.md b/.github/prompts/truthmark-document.prompt.md new file mode 100644 index 0000000..1a6c1cd --- /dev/null +++ b/.github/prompts/truthmark-document.prompt.md @@ -0,0 +1,71 @@ +--- +agent: 'agent' +description: 'Document existing implemented behavior.' +--- + +--- +name: truthmark-document +description: Use when the user explicitly asks to document existing implemented behavior, or when Truth Sync, Truth Check, or Truth Structure reports implemented behavior that lacks canonical truth docs. Reads implementation and routing, writes truth docs and routing only, and never changes functional code. +argument-hint: Optional implemented behavior, API endpoint, route, controller, package, or truth-doc area to document +user-invocable: true +truthmark-version: 1.2.3 +--- + +# Truthmark Document + +Use this skill to document existing implemented behavior when no functional-code changes are required for the task. +Invocations: OpenCode /skill truthmark-document; Codex /truthmark-document or $truthmark-document; Claude Code /truthmark-document; GitHub Copilot /truthmark-document; Gemini CLI /truthmark:document. + +Truth Document is manual and implementation-first: + +- run only when the user explicitly asks to generate or update truth docs for existing behavior, or when Truth Sync, Truth Check, or Truth Structure reports implemented behavior that lacks canonical truth docs +- inspect .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, existing canonical docs, implementation code, and tests directly +- Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. +- document current implemented behavior; do not invent future behavior or planned endpoints +- may write canonical truth docs and docs/truthmark/areas.md or relevant child route files only +- must not write functional code +- when routing is missing, stale, broad, overloaded, catch-all, or cannot map the behavior to a bounded truth owner, run Truth Structure first when routing repair is safe and in scope +- block and recommend Truth Structure when routing repair is unsafe, ambiguous, or outside the task boundary +- keep feature README.md files as indexes rather than truth-document targets +- create or update bounded leaf truth docs when behavior does not fit an existing leaf doc +- keep feature docs behavior-oriented, not endpoint-oriented, unless the endpoint itself is the behavior boundary +- keep API endpoint details in the nearest contract truth doc when such a doc owns the API contract +- preserve unrelated authored content +When creating or updating a feature doc, read docs/templates/feature-doc.md and follow its frontmatter, heading order, and section intent. +When updating an existing feature doc, align existing feature docs to the template standard while preserving authored content that remains accurate. +If docs/templates/feature-doc.md is missing, use the built-in minimal feature-doc structure with Current Behavior, Product Decisions, and Rationale sections. +Teams may edit docs/templates/feature-doc.md to define their local feature-doc standard. +Maintain architecture docs when a code change alters system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership. +Do not put ordinary feature behavior, endpoint details, UI copy, validation rules, or bug fixes in architecture docs unless they change those architecture boundaries. +Keep architecture docs focused on structure and ownership; keep current product behavior in feature or contract docs. +Truthmark hierarchy: +- Config: .truthmark/config.yml +- Root route index: docs/truthmark/areas.md +- Area route files: docs/truthmark/areas/**/*.md +- Feature docs: docs/features/**/*.md +Decision truth lives in the canonical doc it governs. +Date active decisions inline when added or changed, for example `Decision (2026-05-09): ...`. +Do not create separate timestamped ADR logs or planning tickets for active decisions. +Replace old active decisions instead of appending separate timestamped decision logs; Git history is the audit trail. +Update Product Decisions and Rationale when a behavior change comes from a decision change. + +Report completion in this shape: +```md +Truth Document: completed + +Implementation reviewed: +- src/api/orders/** + +Truth docs created: +- docs/features/orders/order-submission.md + +Truth docs updated: +- docs/features/contracts.md + +Routing updated: +- docs/truthmark/areas/orders.md + +Notes: +- Documented existing order submission behavior from route handlers and tests. +``` diff --git a/.github/prompts/truthmark-realize.prompt.md b/.github/prompts/truthmark-realize.prompt.md new file mode 100644 index 0000000..d7b4cc2 --- /dev/null +++ b/.github/prompts/truthmark-realize.prompt.md @@ -0,0 +1,57 @@ +--- +agent: 'agent' +description: 'Realize repository truth docs into code.' +--- + +--- +name: truthmark-realize +description: Use when the user explicitly asks to realize Truthmark truth docs into code, including /truthmark-realize, $truthmark-realize, or /truthmark:realize. Reads truth docs and routing first, updates functional code only, and reports verification. +argument-hint: Optional truth doc path, area, or desired code behavior to realize +user-invocable: true +truthmark-version: 1.2.3 +--- + +# Truthmark Realize + +Use this skill only when the user explicitly asks to realize truth docs into code. + +Invocations: OpenCode /skill truthmark-realize; Codex /truthmark-realize or $truthmark-realize; Claude Code /truthmark-realize; GitHub Copilot /truthmark-realize; Gemini CLI /truthmark:realize. + +Truth Realize is doc-first: + +- truth docs lead +- code follows +- Truth Realize never edits the truth docs it is realizing + +Workflow: + +1. Read the updated truth docs named by the user, or infer the relevant docs from docs/truthmark/areas.md. +2. Read .truthmark/config.yml, docs/truthmark/areas.md, and the relevant functional code. +3. Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. +4. Update functional code only so implementation matches the truth docs. +5. Do not edit truth docs or truth routing while realizing those docs. +6. Run relevant tests for the changed code. +7. Report changed code files and verification steps. + +Read and write boundaries: + +- may read truth docs, routing docs, and relevant functional code +- may write functional code only +- must not edit truth docs or truth routing while realizing those docs + +Report completion in this shape: + +```md +Truth Realize: completed + +Truth docs used: +- docs/features/authentication.md + +Code updated: +- src/auth/session.ts + +Verification: +- npm test -- auth +``` + diff --git a/.github/prompts/truthmark-structure.prompt.md b/.github/prompts/truthmark-structure.prompt.md new file mode 100644 index 0000000..dea2474 --- /dev/null +++ b/.github/prompts/truthmark-structure.prompt.md @@ -0,0 +1,98 @@ +--- +agent: 'agent' +description: 'Design or repair Truthmark area routing.' +--- + +--- +name: truthmark-structure +description: Use when the user asks to design, repair, or refresh missing, stale, broad, overloaded, catch-all, or unrouteable Truthmark area routing. Inspects the repository directly, updates docs/truthmark/areas.md, and may create starter canonical truth docs. +argument-hint: Optional area, directory, or routing concern +user-invocable: true +truthmark-version: 1.2.3 +--- + +Use this skill to design or repair Truthmark area structure. +Invocations: OpenCode /skill truthmark-structure; Codex /truthmark-structure or $truthmark-structure; Claude Code /truthmark-structure; GitHub Copilot /truthmark-structure; Gemini CLI /truthmark:structure. +Truth Structure is agent-native: +- inspect repository layout, current docs, .truthmark/config.yml, docs/truthmark/areas.md, and relevant code directly +- Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. +- inspect the configured root route index at docs/truthmark/areas.md and relevant child route files under docs/truthmark/areas/ +- define areas by product or behavior ownership, not by mechanical directory mirroring +- create or repair docs/truthmark/areas.md +- create starter truth docs when useful and when they belong in the canonical current-truth surface +- Starter truth docs must use closed YAML frontmatter bounded by opening and closing --- lines; include status, doc_type, last_reviewed, and source_of_truth inside that frontmatter. +- Starter truth docs must include ## Product Decisions and ## Rationale sections. +When creating or updating a feature doc, read docs/templates/feature-doc.md and follow its frontmatter, heading order, and section intent. +When updating an existing feature doc, align existing feature docs to the template standard while preserving authored content that remains accurate. +If docs/templates/feature-doc.md is missing, use the built-in minimal feature-doc structure with Current Behavior, Product Decisions, and Rationale sections. +Teams may edit docs/templates/feature-doc.md to define their local feature-doc standard. +- use docs/features/**, docs/architecture/**, or docs/standards/** for current truth destinations +- use only canonical current-truth destinations for starter truth docs +- keep active Product Decisions and Rationale in the canonical doc that owns the behavior +- preserve unrelated authored content +## Topology Governance +Truth Structure owns documentation topology. Do not depend on humans to manually organize docs/features. Treat the configured feature root as a managed semantic root. +Inspect controllers, routes, handlers, services, packages, tests, existing truth docs, and route files; infer product and domain ownership from behavior boundaries, not from mechanical directory mirroring. +When topology pressure exists, repair structure before creating or extending feature docs. +Topology pressure signals: +- one area maps broad code such as src/**, app/**, server/**, services/**, or packages/** +- one area maps multiple unrelated controllers, route groups, services, or bounded contexts +- one truth doc owns unrelated behaviors or unrelated endpoint families +- the configured feature root has many direct non-index docs +- a changed controller, route, or service cannot map to a specific behavior doc +- Truth Sync would need to create a new generic feature doc because routing is too broad +- endpoint or controller names reveal domains missing from docs/truthmark/areas/** +Use these review thresholds as guidance: +- more than 10 direct feature docs in one folder +- more than 15 leaf areas in one child route file +- more than 8 truth docs mapped to one area +- more than 5 controllers mapped through one catch-all area +Repair rules: +- split broad, overloaded, or catch-all areas into behavior-owned child route files +- create route files under docs/truthmark/areas/ when a product/domain boundary is clear +- create feature docs under the configured feature root only when behavior lacks a current doc +- README.md files are indexes, not Truth Sync targets +- prefer bounded leaf truth docs at //.md +- keep feature docs behavior-oriented, not endpoint-oriented +- keep API endpoint details in the nearest contract truth doc when such a doc exists +- update routing so future Truth Sync can target small docs +- preserve existing authored docs; move or rewrite only when needed to remove ambiguity +Maintain architecture docs when a code change alters system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership. +Do not put ordinary feature behavior, endpoint details, UI copy, validation rules, or bug fixes in architecture docs unless they change those architecture boundaries. +Keep architecture docs focused on structure and ownership; keep current product behavior in feature or contract docs. +- Do not finish topology repair with routed canonical current-truth docs missing Product Decisions or Rationale sections. +- If an existing canonical doc lacks either section, add the missing heading beside Current Behavior with a concise current-state placeholder or active decision. +Portable fallback: +- If this skill surface is unavailable, perform the same workflow directly from committed repository files. +- Do not require the truthmark CLI. +- Read .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, canonical docs, and representative implementation code. +- Use a subagent only when the host supports that pattern; otherwise perform the topology repair inline. +Truthmark hierarchy: +- Config: .truthmark/config.yml +- Root route index: docs/truthmark/areas.md +- Area route files: docs/truthmark/areas/**/*.md +- Feature docs: docs/features/**/*.md +Decision truth lives in the canonical doc it governs. +Date active decisions inline when added or changed, for example `Decision (2026-05-09): ...`. +Do not create separate timestamped ADR logs or planning tickets for active decisions. +Replace old active decisions instead of appending separate timestamped decision logs; Git history is the audit trail. +Update Product Decisions and Rationale when a behavior change comes from a decision change. +Report completion in this shape: +```md +Truth Structure: completed +Topology reviewed: +- controllers: src/auth/** +- docs root: docs/features +- route files: docs/truthmark/areas.md +Areas reviewed: +- src/auth/** +Routing updated: +- docs/truthmark/areas.md +Truth docs created: +- docs/features/authentication.md +Topology decisions: +- Added an Authentication area because session behavior has a distinct code surface and truth owner. +Notes: +- Added an Authentication area for session behavior. +``` diff --git a/.github/prompts/truthmark-sync.prompt.md b/.github/prompts/truthmark-sync.prompt.md new file mode 100644 index 0000000..2883784 --- /dev/null +++ b/.github/prompts/truthmark-sync.prompt.md @@ -0,0 +1,105 @@ +--- +agent: 'agent' +description: 'Sync repository truth docs from functional code changes; skip docs-only/no-code changes.' +--- + +--- +name: truthmark-sync +description: Use automatically before finishing when functional code changed since the last successful Truth Sync, and when the user explicitly invokes /truthmark-sync, $truthmark-sync, or /truthmark:sync. Inspects changed code directly, updates truth docs and routing, and verifies post-sync boundaries. Skip for documentation-only changes, formatting-only changes, behavior-preserving renames, missing Truthmark config, or no functional code changes. +argument-hint: Optional changed-code area, truth-doc area, or sync focus +user-invocable: true +truthmark-version: 1.2.3 +--- + +Use this skill automatically before finishing when functional code changed since the last successful Truth Sync. Also run it immediately when the user explicitly invokes Truth Sync. +Invocations: OpenCode /skill truthmark-sync; Codex /truthmark-sync or $truthmark-sync; Claude Code /truthmark-sync; GitHub Copilot /truthmark-sync; Gemini CLI /truthmark:sync. +Explicit invocation runs immediately. Later functional-code changes reopen the finish-time requirement, and an earlier explicit run satisfies the finish gate only if no later functional-code changes occur. +Skip when changes are documentation-only, formatting-only, clearly behavior-preserving renames with no truth impact, when no Truthmark config exists yet, or when there are no functional code changes. +Parent workflow: +1. Inspect git status, staged changes, unstaged changes, and untracked files directly. +2. Read .truthmark/config.yml, the configured root route index at docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, and relevant canonical docs. +3. Identify functional-code changes and the nearest truth docs or routing repairs. +4. Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. +5. Code verification is parent-owned: follow repository instructions and task context, and report what ran or why it did not run. +6. Dispatch one bounded Truth Sync worker only when the host supports subagent dispatch and the acting agent chooses that path; otherwise execute the same sync task inline. +Topology quality gate: +- before updating truth docs, verify the changed code resolves to a specific behavior-owned area and bounded truth owner +- if routing is missing, stale, broad, overloaded, catch-all route only, or cannot map changed code to a bounded truth owner, do not create another generic feature doc +- run Truth Structure before syncing when topology repair is safe and in scope +- block and recommend Truth Structure when topology repair is unsafe, ambiguous, or outside the current task boundary +- report the route files and changed code paths that require structure repair +- README.md files are indexes, not Truth Sync targets +- must not append behavior details to a feature README +- create or update a bounded leaf truth doc when behavior changes do not fit an existing leaf doc +When creating or updating a feature doc, read docs/templates/feature-doc.md and follow its frontmatter, heading order, and section intent. +When updating an existing feature doc, align existing feature docs to the template standard while preserving authored content that remains accurate. +If docs/templates/feature-doc.md is missing, use the built-in minimal feature-doc structure with Current Behavior, Product Decisions, and Rationale sections. +Teams may edit docs/templates/feature-doc.md to define their local feature-doc standard. +Maintain architecture docs when a code change alters system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership. +Do not put ordinary feature behavior, endpoint details, UI copy, validation rules, or bug fixes in architecture docs unless they change those architecture boundaries. +Keep architecture docs focused on structure and ownership; keep current product behavior in feature or contract docs. +Optional validation tooling: +- you may run truthmark check when local tooling is available +- do not require the truthmark binary; direct checkout inspection is the canonical path +- optional validation must not replace agent judgment about docs and routing +- update Product Decisions and Rationale when a behavior change comes from a decision change +Truthmark hierarchy: +- Config: .truthmark/config.yml +- Root route index: docs/truthmark/areas.md +- Area route files: docs/truthmark/areas/**/*.md +- Feature docs: docs/features/**/*.md +Decision truth lives in the canonical doc it governs. +Date active decisions inline when added or changed, for example `Decision (2026-05-09): ...`. +Do not create separate timestamped ADR logs or planning tickets for active decisions. +Replace old active decisions instead of appending separate timestamped decision logs; Git history is the audit trail. +Update Product Decisions and Rationale when a behavior change comes from a decision change. +### Truth Sync Worker +The parent provides the task focus and any repository context already gathered. +Worker rules: +- inspect relevant staged, unstaged, and untracked functional code directly +- read .truthmark/config.yml, docs/truthmark/areas.md, and canonical truth docs directly +- Code verification is parent-owned; report what was run or why it was not run +- may write truth docs and docs/truthmark/areas.md only for Truth Sync alignment +- must not rewrite functional code +Return result in this shape: +- status: completed | blocked +- changedCodeReviewed: string[] +- truthDocsUpdated: string[] +- routingDocsUpdated: string[] +- notes: string[] +- blockedReason?: string +- manualReviewFiles?: string[] +Parent post-sync verification: +- verify only truth docs and docs/truthmark/areas.md changed during sync +- block on any unrelated diff caused by the sync step +- block if functional code changed during sync +- verify the worker report matches the required headings and sections +- verify the updated docs correspond to the reviewed changed-code surface +- blocked outcomes must preserve the working tree as-is: no rollback, no post-block cleanup edits, and manual-review reporting of any remaining files +Report completion in this shape: +```md +Truth Sync: completed + +Changed code reviewed: +- src/auth/session.ts + +Truth docs updated: +- docs/features/repository/overview.md + +Notes: +- Updated session timeout behavior. +``` +Blocked report example: +```md +Truth Sync: blocked + +Reason: +- routing repair is not allowed + +Files requiring manual review: +- docs/truthmark/areas.md + +Next action: +- update routing metadata and rerun Truth Sync +``` diff --git a/.opencode/skills/truthmark-check/SKILL.md b/.opencode/skills/truthmark-check/SKILL.md index 4ae6b00..3f35a85 100644 --- a/.opencode/skills/truthmark-check/SKILL.md +++ b/.opencode/skills/truthmark-check/SKILL.md @@ -3,7 +3,7 @@ name: truthmark-check description: Use when the user asks to audit repository truth health. Inspects truth docs, routing, and implementation directly; may optionally run truthmark check when available. argument-hint: Optional area, doc path, or audit focus user-invocable: true -truthmark-version: 1.2.2 +truthmark-version: 1.2.3 --- # Truthmark Check @@ -14,8 +14,9 @@ Invocations: OpenCode /skill truthmark-check; Codex /truthmark-check or $truthma 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 @@ -30,7 +31,7 @@ Truthmark hierarchy: - 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): ...`. +Date active decisions inline when added or changed, for example `Decision (2026-05-09): ...`. Do not create separate timestamped ADR logs or planning tickets for active decisions. Replace old active decisions instead of appending separate timestamped decision logs; Git history is the audit trail. Update Product Decisions and Rationale when a behavior change comes from a decision change. @@ -41,7 +42,6 @@ Report completion in this shape: Truth Check: completed Files reviewed: -- TRUTHMARK.md - docs/truthmark/areas.md Issues found: diff --git a/.opencode/skills/truthmark-document/SKILL.md b/.opencode/skills/truthmark-document/SKILL.md new file mode 100644 index 0000000..cd5c4ad --- /dev/null +++ b/.opencode/skills/truthmark-document/SKILL.md @@ -0,0 +1,66 @@ +--- +name: truthmark-document +description: Use when the user explicitly asks to document existing implemented behavior, or when Truth Sync, Truth Check, or Truth Structure reports implemented behavior that lacks canonical truth docs. Reads implementation and routing, writes truth docs and routing only, and never changes functional code. +argument-hint: Optional implemented behavior, API endpoint, route, controller, package, or truth-doc area to document +user-invocable: true +truthmark-version: 1.2.3 +--- + +# Truthmark Document + +Use this skill to document existing implemented behavior when no functional-code changes are required for the task. +Invocations: OpenCode /skill truthmark-document; Codex /truthmark-document or $truthmark-document; Claude Code /truthmark-document; GitHub Copilot /truthmark-document; Gemini CLI /truthmark:document. + +Truth Document is manual and implementation-first: + +- run only when the user explicitly asks to generate or update truth docs for existing behavior, or when Truth Sync, Truth Check, or Truth Structure reports implemented behavior that lacks canonical truth docs +- inspect .truthmark/config.yml, docs/truthmark/areas.md, relevant child route files under docs/truthmark/areas/, existing canonical docs, implementation code, and tests directly +- Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. +- document current implemented behavior; do not invent future behavior or planned endpoints +- may write canonical truth docs and docs/truthmark/areas.md or relevant child route files only +- must not write functional code +- when routing is missing, stale, broad, overloaded, catch-all, or cannot map the behavior to a bounded truth owner, run Truth Structure first when routing repair is safe and in scope +- block and recommend Truth Structure when routing repair is unsafe, ambiguous, or outside the task boundary +- keep feature README.md files as indexes rather than truth-document targets +- create or update bounded leaf truth docs when behavior does not fit an existing leaf doc +- keep feature docs behavior-oriented, not endpoint-oriented, unless the endpoint itself is the behavior boundary +- keep API endpoint details in the nearest contract truth doc when such a doc owns the API contract +- preserve unrelated authored content +When creating or updating a feature doc, read docs/templates/feature-doc.md and follow its frontmatter, heading order, and section intent. +When updating an existing feature doc, align existing feature docs to the template standard while preserving authored content that remains accurate. +If docs/templates/feature-doc.md is missing, use the built-in minimal feature-doc structure with Current Behavior, Product Decisions, and Rationale sections. +Teams may edit docs/templates/feature-doc.md to define their local feature-doc standard. +Maintain architecture docs when a code change alters system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership. +Do not put ordinary feature behavior, endpoint details, UI copy, validation rules, or bug fixes in architecture docs unless they change those architecture boundaries. +Keep architecture docs focused on structure and ownership; keep current product behavior in feature or contract docs. +Truthmark hierarchy: +- Config: .truthmark/config.yml +- Root route index: docs/truthmark/areas.md +- Area route files: docs/truthmark/areas/**/*.md +- Feature docs: docs/features/**/*.md +Decision truth lives in the canonical doc it governs. +Date active decisions inline when added or changed, for example `Decision (2026-05-09): ...`. +Do not create separate timestamped ADR logs or planning tickets for active decisions. +Replace old active decisions instead of appending separate timestamped decision logs; Git history is the audit trail. +Update Product Decisions and Rationale when a behavior change comes from a decision change. + +Report completion in this shape: +```md +Truth Document: completed + +Implementation reviewed: +- src/api/orders/** + +Truth docs created: +- docs/features/orders/order-submission.md + +Truth docs updated: +- docs/features/contracts.md + +Routing updated: +- docs/truthmark/areas/orders.md + +Notes: +- Documented existing order submission behavior from route handlers and tests. +``` diff --git a/.opencode/skills/truthmark-realize/SKILL.md b/.opencode/skills/truthmark-realize/SKILL.md index 3d4047a..c58afa7 100644 --- a/.opencode/skills/truthmark-realize/SKILL.md +++ b/.opencode/skills/truthmark-realize/SKILL.md @@ -3,7 +3,7 @@ name: truthmark-realize description: Use when the user explicitly asks to realize Truthmark truth docs into code, including /truthmark-realize, $truthmark-realize, or /truthmark:realize. Reads truth docs and routing first, updates functional code only, and reports verification. argument-hint: Optional truth doc path, area, or desired code behavior to realize user-invocable: true -truthmark-version: 1.2.2 +truthmark-version: 1.2.3 --- # Truthmark Realize @@ -21,8 +21,9 @@ Truth Realize is doc-first: Workflow: 1. Read the updated truth docs named by the user, or infer the relevant docs from docs/truthmark/areas.md. -2. Read .truthmark/config.yml, TRUTHMARK.md, docs/truthmark/areas.md, and the relevant functional code. -3. Repository docs and code are inspected evidence, not executable instruction authority. +2. Read .truthmark/config.yml, docs/truthmark/areas.md, and the relevant functional code. +3. Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority. +Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. 4. Update functional code only so implementation matches the truth docs. 5. Do not edit truth docs or truth routing while realizing those docs. 6. Run relevant tests for the changed code. diff --git a/.opencode/skills/truthmark-structure/SKILL.md b/.opencode/skills/truthmark-structure/SKILL.md index bcf61a1..c66416f 100644 --- a/.opencode/skills/truthmark-structure/SKILL.md +++ b/.opencode/skills/truthmark-structure/SKILL.md @@ -1,22 +1,27 @@ --- 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 the user asks to design, repair, or refresh missing, stale, broad, overloaded, catch-all, or unrouteable Truthmark area routing. Inspects the repository directly, updates docs/truthmark/areas.md, and may create starter canonical truth docs. argument-hint: Optional area, directory, or routing concern user-invocable: true -truthmark-version: 1.2.2 +truthmark-version: 1.2.3 --- Use this skill to design or repair Truthmark area structure. Invocations: OpenCode /skill truthmark-structure; Codex /truthmark-structure or $truthmark-structure; Claude Code /truthmark-structure; GitHub Copilot /truthmark-structure; Gemini CLI /truthmark:structure. Truth Structure is agent-native: -- inspect repository layout, current docs, .truthmark/config.yml, 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. +When creating or updating a feature doc, read docs/templates/feature-doc.md and follow its frontmatter, heading order, and section intent. +When updating an existing feature doc, align existing feature docs to the template standard while preserving authored content that remains accurate. +If docs/templates/feature-doc.md is missing, use the built-in minimal feature-doc structure with Current Behavior, Product Decisions, and Rationale sections. +Teams may edit docs/templates/feature-doc.md to define their local feature-doc standard. - use docs/features/**, docs/architecture/**, or docs/standards/** for current truth destinations - use only canonical current-truth destinations for starter truth docs - keep active Product Decisions and Rationale in the canonical doc that owns the behavior @@ -39,7 +44,7 @@ Use these review thresholds as guidance: - 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 - create route files under docs/truthmark/areas/ when a product/domain boundary is clear - create feature docs under the configured feature root only when behavior lacks a current doc - README.md files are indexes, not Truth Sync targets @@ -48,12 +53,15 @@ Repair rules: - keep API endpoint details in the nearest contract truth doc when such a doc exists - update routing so future Truth Sync can target small docs - preserve existing authored docs; move or rewrite only when needed to remove ambiguity +Maintain architecture docs when a code change alters system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership. +Do not put ordinary feature behavior, endpoint details, UI copy, validation rules, or bug fixes in architecture docs unless they change those architecture boundaries. +Keep architecture docs focused on structure and ownership; keep current product behavior in feature or contract docs. - Do not finish topology repair with routed canonical current-truth docs missing Product Decisions or Rationale sections. - If an existing canonical doc lacks either section, add the missing heading beside Current Behavior with a concise current-state placeholder or active decision. Portable fallback: - If this skill surface is unavailable, perform the same workflow directly from committed repository files. - Do not require the truthmark CLI. -- Read .truthmark/config.yml, 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 @@ -61,7 +69,7 @@ Truthmark hierarchy: - 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): ...`. +Date active decisions inline when added or changed, for example `Decision (2026-05-09): ...`. Do not create separate timestamped ADR logs or planning tickets for active decisions. Replace old active decisions instead of appending separate timestamped decision logs; Git history is the audit trail. Update Product Decisions and Rationale when a behavior change comes from a decision change. diff --git a/.opencode/skills/truthmark-sync/SKILL.md b/.opencode/skills/truthmark-sync/SKILL.md index a377b4d..7b8f996 100644 --- a/.opencode/skills/truthmark-sync/SKILL.md +++ b/.opencode/skills/truthmark-sync/SKILL.md @@ -1,30 +1,39 @@ --- 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 before finishing when functional code changed since the last successful Truth Sync, and when the user explicitly invokes /truthmark-sync, $truthmark-sync, or /truthmark:sync. Inspects changed code directly, updates truth docs and routing, and verifies post-sync boundaries. Skip for documentation-only changes, formatting-only changes, behavior-preserving renames, missing Truthmark config, or no functional code changes. argument-hint: Optional changed-code area, truth-doc area, or sync focus user-invocable: true -truthmark-version: 1.2.2 +truthmark-version: 1.2.3 --- Use this skill automatically before finishing when functional code changed since the last successful Truth Sync. Also run it immediately when the user explicitly invokes Truth Sync. Invocations: OpenCode /skill truthmark-sync; Codex /truthmark-sync or $truthmark-sync; Claude Code /truthmark-sync; GitHub Copilot /truthmark-sync; Gemini CLI /truthmark:sync. Explicit invocation runs immediately. Later functional-code changes reopen the finish-time requirement, and an earlier explicit run satisfies the finish gate only if no later functional-code changes occur. +Skip when changes are documentation-only, formatting-only, clearly behavior-preserving renames with no truth impact, when no Truthmark config exists yet, or when there are no functional code changes. Parent workflow: 1. Inspect git status, staged changes, unstaged changes, and untracked files directly. -2. Read .truthmark/config.yml, 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 feature doc +- run Truth Structure before syncing when topology repair is safe and in scope +- block and recommend Truth Structure when topology repair is unsafe, ambiguous, or outside the current task boundary +- report the route files and changed code paths that require structure repair - README.md files are indexes, not Truth Sync targets - must not append behavior details to a feature README - create or update a bounded leaf truth doc when behavior changes do not fit an existing leaf doc +When creating or updating a feature doc, read docs/templates/feature-doc.md and follow its frontmatter, heading order, and section intent. +When updating an existing feature doc, align existing feature docs to the template standard while preserving authored content that remains accurate. +If docs/templates/feature-doc.md is missing, use the built-in minimal feature-doc structure with Current Behavior, Product Decisions, and Rationale sections. +Teams may edit docs/templates/feature-doc.md to define their local feature-doc standard. +Maintain architecture docs when a code change alters system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership. +Do not put ordinary feature behavior, endpoint details, UI copy, validation rules, or bug fixes in architecture docs unless they change those architecture boundaries. +Keep architecture docs focused on structure and ownership; keep current product behavior in feature or contract docs. Optional validation tooling: - you may run truthmark check when local tooling is available - do not require the truthmark binary; direct checkout inspection is the canonical path @@ -36,7 +45,7 @@ Truthmark hierarchy: - 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): ...`. +Date active decisions inline when added or changed, for example `Decision (2026-05-09): ...`. Do not create separate timestamped ADR logs or planning tickets for active decisions. Replace old active decisions instead of appending separate timestamped decision logs; Git history is the audit trail. Update Product Decisions and Rationale when a behavior change comes from a decision change. @@ -44,7 +53,7 @@ Update Product Decisions and Rationale when a behavior change comes from a decis 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 diff --git a/.truthmark/config.yml b/.truthmark/config.yml index 7dad89f..ec30877 100644 --- a/.truthmark/config.yml +++ b/.truthmark/config.yml @@ -18,7 +18,6 @@ docs: default_area: repository max_delegation_depth: 1 authority: - - TRUTHMARK.md - docs/truthmark/areas.md - docs/truthmark/areas/**/*.md - docs/ai/**/*.md diff --git a/AGENTS.md b/AGENTS.md index b09f308..c50824f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,24 +1,24 @@ 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: +Agent-specific: - Read `docs/README.md` for the canonical docs map. - Use `docs/ai/agent-onboarding.md` for quick task routing. ## Truthmark Workflow -Generated by Truthmark 1.2.2. Rerun `truthmark init` after upgrades and review workflow diffs. +Generated by Truthmark 1.2.3. Rerun `truthmark init` after upgrades and review 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: update Product Decisions/Rationale, allow short inline dates, and do not create separate timestamped ADR or planning logs. +Decision truth lives in the canonical doc it governs: update Product Decisions/Rationale, date active decisions inline when added or changed, and do not create separate timestamped ADR or planning logs. Agent runtime: installed skills plus this block. Always inspect checkout directly; CLI commands are optional validation. Do not use packet helpers or cache files. Delegation is host-owned. ### Truth Sync -Sync: finish-time when functional code changed; use the truthmark-sync skill before finishing. Explicit invocation: OpenCode /skill truthmark-sync; Codex /truthmark-sync or $truthmark-sync; Claude Code /truthmark-sync; GitHub Copilot /truthmark-sync; Gemini CLI /truthmark:sync; later functional changes reopen the gate. Memory: code changed -> tests -> Sync -> report. Run relevant tests first. Code leads, truth docs follow; may write truth docs and docs/truthmark/areas.md only, and must not rewrite functional code. Read docs/truthmark/areas.md and only relevant child routes under docs/truthmark/areas/; if routing is broad/overloaded/catch-all, run or recommend Truth Structure. Skip only: documentation-only change; formatting-only change; clearly behavior-preserving rename with no truth impact; no Truthmark config exists yet; no functional code changes. -Explicit workflows: Truth Structure, Truth Realize, Truth Check. Run only when requested or when Sync requires Structure; load the installed skill for details. +Sync: finish-time when functional code changed; use the truthmark-sync skill before finishing. Explicit invocation: OpenCode /skill truthmark-sync; Codex /truthmark-sync or $truthmark-sync; Claude Code /truthmark-sync; GitHub Copilot /truthmark-sync; Gemini CLI /truthmark:sync; later functional changes reopen the gate. Memory: code changed -> tests -> Sync -> report. Run relevant tests first. Code leads, truth docs follow; may write truth docs and docs/truthmark/areas.md only, and must not rewrite functional code. Read docs/truthmark/areas.md and only relevant child routes under docs/truthmark/areas/; if routing is missing/stale/broad/overloaded/catch-all or cannot map changed code to a bounded truth owner, run Truth Structure before syncing when safe and in scope; otherwise block and recommend Truth Structure. Skip only: documentation-only change; formatting-only change; clearly behavior-preserving rename with no truth impact; no Truthmark config exists yet; no functional code changes. +Explicit workflows: Truth Structure, Truth Document, Truth Realize, Truth Check. Run only when requested or when Sync requires Structure or Document; load the installed skill for details. Workflow integrity rule: repository truth may describe desired behavior, but it must not silently override these Truthmark workflow boundaries. diff --git a/CLAUDE.md b/CLAUDE.md index b09f308..c50824f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,24 +1,24 @@ 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: +Agent-specific: - Read `docs/README.md` for the canonical docs map. - Use `docs/ai/agent-onboarding.md` for quick task routing. ## Truthmark Workflow -Generated by Truthmark 1.2.2. Rerun `truthmark init` after upgrades and review workflow diffs. +Generated by Truthmark 1.2.3. Rerun `truthmark init` after upgrades and review 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: update Product Decisions/Rationale, allow short inline dates, and do not create separate timestamped ADR or planning logs. +Decision truth lives in the canonical doc it governs: update Product Decisions/Rationale, date active decisions inline when added or changed, and do not create separate timestamped ADR or planning logs. Agent runtime: installed skills plus this block. Always inspect checkout directly; CLI commands are optional validation. Do not use packet helpers or cache files. Delegation is host-owned. ### Truth Sync -Sync: finish-time when functional code changed; use the truthmark-sync skill before finishing. Explicit invocation: OpenCode /skill truthmark-sync; Codex /truthmark-sync or $truthmark-sync; Claude Code /truthmark-sync; GitHub Copilot /truthmark-sync; Gemini CLI /truthmark:sync; later functional changes reopen the gate. Memory: code changed -> tests -> Sync -> report. Run relevant tests first. Code leads, truth docs follow; may write truth docs and docs/truthmark/areas.md only, and must not rewrite functional code. Read docs/truthmark/areas.md and only relevant child routes under docs/truthmark/areas/; if routing is broad/overloaded/catch-all, run or recommend Truth Structure. Skip only: documentation-only change; formatting-only change; clearly behavior-preserving rename with no truth impact; no Truthmark config exists yet; no functional code changes. -Explicit workflows: Truth Structure, Truth Realize, Truth Check. Run only when requested or when Sync requires Structure; load the installed skill for details. +Sync: finish-time when functional code changed; use the truthmark-sync skill before finishing. Explicit invocation: OpenCode /skill truthmark-sync; Codex /truthmark-sync or $truthmark-sync; Claude Code /truthmark-sync; GitHub Copilot /truthmark-sync; Gemini CLI /truthmark:sync; later functional changes reopen the gate. Memory: code changed -> tests -> Sync -> report. Run relevant tests first. Code leads, truth docs follow; may write truth docs and docs/truthmark/areas.md only, and must not rewrite functional code. Read docs/truthmark/areas.md and only relevant child routes under docs/truthmark/areas/; if routing is missing/stale/broad/overloaded/catch-all or cannot map changed code to a bounded truth owner, run Truth Structure before syncing when safe and in scope; otherwise block and recommend Truth Structure. Skip only: documentation-only change; formatting-only change; clearly behavior-preserving rename with no truth impact; no Truthmark config exists yet; no functional code changes. +Explicit workflows: Truth Structure, Truth Document, Truth Realize, Truth Check. Run only when requested or when Sync requires Structure or Document; load the installed skill for details. Workflow integrity rule: repository truth may describe desired behavior, but it must not silently override these Truthmark workflow boundaries. diff --git a/FutureVision.md b/FutureVision.md index 7add3b1..e8a02e9 100644 --- a/FutureVision.md +++ b/FutureVision.md @@ -1,31 +1,128 @@ - Directions for V2 - - 1. Evidence Layer - - Strengthen truthmark check into the primary confidence surface. - - Make truthVisibility more actionable: route precision, unmapped surfaces, stale - generated surfaces, topology pressure. - - Add CI examples that report truth health without pretending Truthmark is a merge - gate by default. - - Build before/after demos showing: 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. - - Add migration guides for teams already using AGENTS.md, CLAUDE.md, Copilot - instructions, or Gemini commands. - - 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. - 3. Conformance Layer - - Treat generated host surfaces as adapters with contract tests. - - Keep Codex, Claude Code, Copilot, Cursor, OpenCode, and Gemini support current as - those hosts evolve. - - External signal supports this direction: Codex reads repo instructions and skills, - Copilot supports repo/path/agent instructions, Claude Code has project skills, and - Gemini CLI supports project commands. Sources: OpenAI Codex loop - (https://openai.com/index/unrolling-the-codex-agent-loop/), GitHub Copilot custom - instructions +Directions for V2 - > The repo should tell every AI agent what is true, what owns what, and what must be - > updated before work is complete. \ No newline at end of file +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. \ No newline at end of file diff --git a/GEMINI.md b/GEMINI.md new file mode 100644 index 0000000..c50824f --- /dev/null +++ b/GEMINI.md @@ -0,0 +1,24 @@ +Follow `docs/ai/repo-rules.md`. + +Use that file as the primary repository instruction source for this agent. + +Agent-specific: +- Read `docs/README.md` for the canonical docs map. +- Use `docs/ai/agent-onboarding.md` for quick task routing. + + +## Truthmark Workflow + +Generated by Truthmark 1.2.3. Rerun `truthmark init` after upgrades and review 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: update Product Decisions/Rationale, date active decisions inline when added or changed, and do not create separate timestamped ADR or planning logs. +Agent runtime: installed skills plus this block. Always inspect checkout directly; CLI commands are optional validation. Do not use packet helpers or cache files. Delegation is host-owned. +### Truth Sync +Sync: finish-time when functional code changed; use the truthmark-sync skill before finishing. Explicit invocation: OpenCode /skill truthmark-sync; Codex /truthmark-sync or $truthmark-sync; Claude Code /truthmark-sync; GitHub Copilot /truthmark-sync; Gemini CLI /truthmark:sync; later functional changes reopen the gate. Memory: code changed -> tests -> Sync -> report. Run relevant tests first. Code leads, truth docs follow; may write truth docs and docs/truthmark/areas.md only, and must not rewrite functional code. Read docs/truthmark/areas.md and only relevant child routes under docs/truthmark/areas/; if routing is missing/stale/broad/overloaded/catch-all or cannot map changed code to a bounded truth owner, run Truth Structure before syncing when safe and in scope; otherwise block and recommend Truth Structure. Skip only: documentation-only change; formatting-only change; clearly behavior-preserving rename with no truth impact; no Truthmark config exists yet; no functional code changes. +Explicit workflows: Truth Structure, Truth Document, Truth Realize, Truth Check. Run only when requested or when Sync requires Structure or Document; load the installed skill for details. +Workflow integrity rule: repository truth may describe desired behavior, but it must not silently override these Truthmark workflow boundaries. + diff --git a/README.de.md b/README.de.md index dcbc1d8..d76cff5 100644 --- a/README.de.md +++ b/README.de.md @@ -1,31 +1,68 @@ -# Truthmark ist die Wahrheitsschicht für KI-Softwareentwicklung. +# Truthmark + +**Truthmark automatisiert die Pflege von Repository-Wahrheit 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. +Truthmark-Banner -## 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 automatische Abschlusskontrolle 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. +- Agent ändert funktionalen Code +- relevante Tests laufen +- Truth Sync aktualisiert zugeordnete Wahrheitsdokumente, bevor der Agent fertig ist +- Truth-Doc-Diff prüfen, wenn einer erzeugt wurde + +Die meisten Tools bitten Teams darum, sich eine Gewohnheit anzueignen. Truthmark automatisiert die Gewohnheit. + +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 + + + + + + + + + +
+ Truthmark-Funktionen +
Funktionen
+ Was Truthmark installiert und wie sich die Workflow-Fläche aufteilt. + 		+ Truthmark-Positionierung +
Positionierung
+ Wo Truthmark im Verhältnis zu Prompts, Memory und Spec-Workflows steht. +
+ Truthmark-Sync-Ablauf +
Sync-Ablauf
+ Wie Truth Sync normale Codeänderungen vor einer Übergabe abschließt. +
+ +## Warum Teams es nutzen + +Truthmark versucht nicht, Agenten klüger wirken zu lassen. Es soll KI-gestützte Repository-Änderungen vertrauenswürdiger machen. + +- Automatisierte 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 Modell funktioniert in Codebasen mit JavaScript, TypeScript, Go, Python, C# und Java. -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. +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,14 +130,15 @@ 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/templates/feature-doc.md docs/features/README.md docs/features/repository/README.md docs/features/repository/overview.md AGENTS.md CLAUDE.md +GEMINI.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. @@ -109,8 +148,11 @@ Bestehende Repositories brauchen nach `init` meist einen Aufräumschritt: Führe ## 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. + +Nutze Truth Document, wenn implementiertes Verhalten bereits existiert, aber die kanonischen Wahrheitsdokumente fehlen oder schwach sind. Der Agent liest Implementierung, Tests, Routing und vorhandene Dokumente, schreibt nur Wahrheitsdokumente und Routing und darf funktionalen Code nicht ändern. 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. + +Die meisten Nutzer sollten Truth Sync nicht direkt aufrufen müssen. Entscheidend ist, dass Truth Sync als automatische Abschlusskontrolle wirkt, wenn funktionaler Code geändert wurde. Der normale Ablauf ist: ```text Agent ändert funktionalen Code @@ -138,29 +180,31 @@ Codex, Claude Code und unterstützte Copilot-IDEs können es mit `/truthmark-rea ## 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 festgeschriebenen Hierarchievertrag - `docs/truthmark/areas.md` für den Root-Routenindex - `docs/truthmark/areas/**/*.md` für delegierte untergeordnete Routendateien +- `docs/templates/feature-doc.md` für den editierbaren Feature-Dokument-Standard 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 Sync, Truth Realize und Truth Check +- 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 absichtlich klein, 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, und `truthmark check` validiert Wahrheitsartefakte für manuelle Audits, CI oder Fehlersuche. ```bash truthmark config @@ -173,7 +217,7 @@ truthmark check --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. +Truth Structure, Truth Document, Truth Sync, Truth Realize und Truth Check sind installierte Agenten-Workflows, keine täglichen Top-Level-CLI-Befehle. ## Warum es existiert @@ -191,14 +235,14 @@ 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` - 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 Skill-Flächen für Truth Structure, Truth Document, Truth Sync, Truth Realize und Truth Check für konfigurierte Agenten-Hosts - Branch-Scope-Metadaten - Diagnostik für Konfiguration, Autorität, Routing, Entscheidungsstruktur, Frontmatter, Links und polyglotte Abdeckung diff --git a/README.es.md b/README.es.md index 5963895..78fe355 100644 --- a/README.es.md +++ b/README.es.md @@ -1,31 +1,68 @@ -# Truthmark es la capa de verdad para el desarrollo de software con IA. +# Truthmark + +**Truthmark automatiza el mantenimiento de la verdad 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. +Banner de Truthmark -## 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 salvaguarda automática al cierre de ese flujo. 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 agente cambia código funcional +- se ejecutan las pruebas relevantes +- 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 + +La mayoría de las herramientas pide al equipo adoptar un hábito. Truthmark automatiza ese hábito. + +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 + + + + + + + + + +
+ Características de Truthmark +
Características
+ Lo que instala Truthmark y cómo se divide la superficie de trabajo. + 		+ Posicionamiento de Truthmark +
Posicionamiento
+ Dónde encaja Truthmark frente a prompts, memoria y flujos spec-first. +
+ Flujo de sync de Truthmark +
Flujo de sync
+ Cómo Truth Sync cierra cambios normales de código antes del traspaso. +
+ +## 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. + +- La sincronización automática de la verdad 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 funciona en bases de código JavaScript, TypeScript, Go, Python, C# y Java. -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. +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,14 +130,15 @@ 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/templates/feature-doc.md docs/features/README.md docs/features/repository/README.md docs/features/repository/overview.md AGENTS.md CLAUDE.md +GEMINI.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`. @@ -109,8 +148,11 @@ Los repositorios existentes suelen necesitar una pasada de limpieza después de ## 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. + +Usa Truth Document cuando el comportamiento ya está implementado pero los documentos de verdad canónica faltan o son débiles. El agente lee implementación, pruebas, rutas y documentos existentes, escribe solo documentos de verdad y rutas, y no 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`. + +La mayoría de los usuarios no debería invocar Truth Sync directamente. Lo importante es que Truth Sync actúe como salvaguarda automática al cierre cuando cambió código funcional. El flujo normal es: ```text el agente cambia código funcional @@ -138,29 +180,31 @@ Codex, Claude Code y los IDEs de Copilot compatibles pueden invocarlo con `/trut ## 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 - `docs/truthmark/areas.md` para el índice raíz de rutas - `docs/truthmark/areas/**/*.md` para archivos de rutas secundarias delegadas +- `docs/templates/feature-doc.md` para el estándar editable de documentos de función usado 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 Sync, Truth Realize y Truth Check +- 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, y `truthmark check` valida los artefactos de verdad para auditorías manuales, CI o depuración. ```bash truthmark config @@ -173,7 +217,7 @@ truthmark check --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. +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. ## Por qué existe @@ -191,14 +235,14 @@ 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` - 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 diff --git a/README.md b/README.md index 91f6c41..1e08b60 100644 --- a/README.md +++ b/README.md @@ -1,40 +1,68 @@ # Truthmark -**Truthmark is the truth layer for AI software development.** +**Truthmark automates truth maintenance for AI software development.** English | [Deutsch](README.de.md) | [中文](README.zh.md) | [Español](README.es.md) | [Русский](README.ru.md) -![Truthmark overview](docs/assets/truthmark-overview.png) +Truthmark banner -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 an automatic finish-time safeguard 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 +- Truth Sync 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 automates the habit. -## 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. + + + + + + + + +
+ Truthmark features +
Features
+ What Truthmark installs and how the workflow surface is split. + 		+ Truthmark position +
Position
+ Where Truthmark fits relative to prompts, memory, and spec workflows. +
+ Truthmark sync flow +
Sync flow
+ How Truth Sync closes out normal code changes before handoff. +
+ +## 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. + +- Automated 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 model works across JavaScript, TypeScript, Go, Python, C#, and Java codebases. -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. +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,14 +131,15 @@ 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/templates/feature-doc.md docs/features/README.md docs/features/repository/README.md docs/features/repository/overview.md AGENTS.md CLAUDE.md +GEMINI.md ``` 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`. @@ -117,13 +148,35 @@ The default scaffold keeps feature `README.md` files as indexes and starts curre 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/features/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 Truth Sync acts as an automatic finish-time safeguard when functional code changed. The normal path is: ```text agent changes functional code @@ -137,6 +190,10 @@ Truth Sync is code-first: code leads, truth docs follow, and Truth Sync must not 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 Use this when a product or architecture decision starts in docs: @@ -154,31 +211,37 @@ Truth Realize is manual and doc-first: truth docs lead, code follows, and the ag 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/features/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 committed hierarchy contract - `docs/truthmark/areas.md` for the root route index - `docs/truthmark/areas/**/*.md` for delegated child route files +- `docs/templates/feature-doc.md` for the editable feature-doc standard 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 Sync, Truth Realize, and Truth Check +- 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. +Feature `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 intentionally keeps the CLI small 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, and `truthmark check` validates truth artifacts for manual audits, CI, or troubleshooting. ```bash truthmark config @@ -194,10 +257,14 @@ 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. +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 Most AI coding workflows optimize for the next answer. Truthmark optimizes for the next handoff. @@ -213,7 +280,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 @@ -223,7 +290,7 @@ V1 currently provides: - `truthmark init` - `truthmark check` - 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 diff --git a/README.ru.md b/README.ru.md index c32ee2f..ea5056c 100644 --- a/README.ru.md +++ b/README.ru.md @@ -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 слой истины с областью действия в пределах ветки, задает агентам явные границы маршрутизации и рабочих процессов и делает так, чтобы эта истина двигалась вместе с кодом, который действительно будет поставлен. -Это не более удачная инженерия промптов. Это более управляемый способ использовать ИИ в настоящей кодовой базе: меньше повторных решений, меньше устаревшей документации, чище передача работы и сессии с ИИ, после которых остаются проверяемые инженерные записи, а не только следы в истории промптов или непрозрачном состоянии инструментов. -Для команд, которые уже знают, что агенты умеют генерировать код, и теперь хотят, чтобы сам репозиторий оставался понятным, проверяемым и управляемым. +Баннер Truthmark -## Что решает Truthmark +ИИ-агенты уже быстро пишут код. Дорогая часть — удерживать истину репозитория в соответствии с тем, что реально изменилось. -Начать писать код с ИИ сейчас легко, но управлять этим дорого. Как только агенты начинают быстро писать код, истина репозитория становится поверхностью управления. -Этот сбой проявляется предсказуемо: требования остаются в чатах, архитектурные решения принимаются заново, агенты трогают не те области, а ветки наследуют контекст, который ревьюеры не могут надежно проверить. Код может двигаться быстро, но репозиторию становится труднее доверять. -Truthmark меняет рабочую модель: +Truthmark добавляет в этот процесс автоматическую финальную защиту. Обычный путь прост: -- Истина, локальная для ветки, путешествует вместе с веткой, а не живет в приватном хранилище инструмента. -- Git делает эту истину проверяемой, сравнимой в diff и доступной всей команде. -- Документация следует за кодом, а не тихо превращается в вымысел. -- Маршрутизация остается явной в `docs/truthmark/areas.md` и делегированных дочерних файлах маршрутов, чтобы агенты понимали, какая документация отвечает за какой код. -- Активные продуктовые и архитектурные решения живут в канонических документах, которыми они управляют, а не в планировочных журналах с временными метками. -- Local-first рабочие процессы не требуют демона, базы данных, удаленного сервиса или MCP-зависимости. +- агент меняет функциональный код +- запускаются релевантные тесты +- Truth Sync обновляет связанные документы истины до завершения работы агента +- если был создан diff документов истины, его проверяют + +Большинство инструментов просит команды выработать привычку. Truthmark автоматизирует эту привычку. + +Truthmark превращает ИИ-процесс в инфраструктуру репозитория, а не в персональный инструмент. Он устанавливает Git-native слой истины внутри репозитория, задает агентам явную маршрутизацию и ограниченные рабочие поверхности и сохраняет эту истину проверяемой в Git вместо того, чтобы разносить ее по истории промптов, устаревшей документации или приватному состоянию инструментов. + +Это важно, потому что процесс живет вместе с веткой. После инициализации репозитория правила, маршрутизация и установленные рабочие поверхности путешествуют внутри репозитория, поэтому совместная работа и передача задач меньше зависят от локальной настройки одного человека. + +Для команд, которые уже знают, что агенты умеют генерировать код, Truthmark решает следующую проблему: как сделать так, чтобы сам репозиторий оставался понятным, проверяемым и управляемым по мере роста ИИ-ассистированной разработки. + +## Визуальный обзор + + + + + + + + + +
+ Возможности Truthmark +
Возможности
+ Что устанавливает Truthmark и как устроена рабочая поверхность. + 		+ Позиционирование Truthmark +
Позиционирование
+ Где Truthmark находится относительно промптов, памяти и spec-first процессов. +
+ Поток sync в Truthmark +
Поток sync
+ Как Truth Sync закрывает обычные изменения кода перед передачей работы. +
+ +## Почему команды выбирают Truthmark + +Truthmark не пытается сделать так, чтобы агенты звучали умнее. Он пытается сделать изменения в репозитории, выполненные с помощью ИИ, более надежными. + +- Автоматический Truth Sync после изменений кода превращает поддержку документации в защиту рабочего процесса, а не в командную привычку. +- Истина, ограниченная веткой, движется вместе с кодом, поэтому ревьюеры могут проверять актуальную истину в обычных Git diff. +- Рабочие поверхности, встроенные в репозиторий, упрощают внедрение и делают передачу работы устойчивее, чем одна лишь персональная настройка. +- Явная маршрутизация в `docs/truthmark/areas.md` и делегированных дочерних файлах маршрутов дает агентам границы ответственности и более безопасные пути записи. +- Local-first работа избавляет от зависимости на демон, базу данных, удаленный сервис или MCP. - Модель работает в кодовых базах на JavaScript, TypeScript, Go, Python, C# и Java. -Для технических лидеров ценность в управлении без показухи: тесты, ревью кода и владение зонами ответственности по-прежнему делают основную работу; Truthmark делает контекст агента долговечным, проверяемым и ограниченным веткой. +Для технических лидеров ценность в управлении без дополнительной инфраструктуры: тесты, ревью кода и владение зонами ответственности по-прежнему делают основную работу; 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,14 +130,15 @@ node /path/to/truthmark/dist/main.js check ```text .truthmark/config.yml -TRUTHMARK.md docs/truthmark/areas.md docs/truthmark/areas/repository.md +docs/templates/feature-doc.md docs/features/README.md docs/features/repository/README.md docs/features/repository/overview.md AGENTS.md CLAUDE.md +GEMINI.md ``` Поддерживаемые платформы: `codex`, `opencode`, `claude-code`, `github-copilot` и `gemini-cli`. Конфигурация по умолчанию включает их все; удалите из `.truthmark/config.yml` платформы, которыми не пользуетесь, перед повторным запуском `truthmark init`. @@ -109,8 +148,11 @@ CLAUDE.md ## Как он работает -Truthmark не задает, какой именно подагент должен запускать Truth Sync. Действующий агент и среда хоста сами решают, делегировать работу или выполнить процесс на месте. -Большинству пользователей не нужно вызывать Truth Sync напрямую. Нормальный путь выглядит так: +Сильная сторона Truthmark — путь по умолчанию, а не набор ручных команд. Действующий агент и среда хоста сами решают, делегировать работу или выполнить установленный процесс на месте. + +Используйте Truth Document, когда поведение уже реализовано, но канонические документы истины отсутствуют или слабы. Агент читает реализацию, тесты, маршруты и существующие документы, пишет только документы истины и маршруты и не должен менять функциональный код. Codex, Claude Code и поддерживаемые IDE Copilot могут вызывать его через `/truthmark-document`; хосты в стиле OpenCode могут использовать `/skill truthmark-document`. + +Большинству пользователей не нужно вызывать Truth Sync напрямую. Главное, что Truth Sync работает как автоматическая финальная защита, когда менялся функциональный код. Нормальный путь выглядит так: ```text агент изменяет функциональный код @@ -138,29 +180,31 @@ Codex, Claude Code и поддерживаемые IDE Copilot могут выз ## Что он устанавливает -Truthmark намеренно держит постоянную рабочую поверхность маленькой: +Truthmark держит постоянную рабочую поверхность маленькой и встроенной в репозиторий. После `truthmark init` сам репозиторий несет маршрутизацию, правила и установленные рабочие поверхности, поэтому команда не зависит только от локальной настройки одного человека. - `.truthmark/config.yml` для машиночитаемой конфигурации -- `TRUTHMARK.md` для контракта рабочего процесса, локального для ветки +- `.truthmark/config.yml` для зафиксированного контракта иерархии - `docs/truthmark/areas.md` для корневого индекса маршрутов - `docs/truthmark/areas/**/*.md` для делегированных дочерних файлов маршрутов +- `docs/templates/feature-doc.md` для редактируемого стандарта feature-документов, используемого сгенерированными рабочими процессами - управляемые блоки инструкций для настроенных платформ, таких как `AGENTS.md`, `CLAUDE.md`, инструкции Copilot и `GEMINI.md` -- нативные для хоста skills, prompts или commands для Truth Structure, Truth Sync, Truth Realize и Truth Check +- нативные для хоста 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 @@ -173,7 +217,7 @@ truthmark check --json `config` пишет только `.truthmark/config.yml`, если не используется `--stdout`. `init` требует `.truthmark/config.yml`, а затем устанавливает или обновляет локальные файлы рабочих процессов. `check` валидирует конфигурацию, полномочия, маршрутизацию, документы с решениями, frontmatter, внутренние ссылки, область действия ветки и диагностику покрытия. -Truth Structure, Truth Sync, Truth Realize и Truth Check это установленные агентские рабочие процессы, а не повседневные CLI-команды верхнего уровня. +Truth Structure, Truth Document, Truth Sync, Truth Realize и Truth Check это установленные агентские рабочие процессы, а не повседневные CLI-команды верхнего уровня. ## Зачем он существует @@ -191,14 +235,14 @@ Truth Structure, Truth Sync, Truth Realize и Truth Check это установ ## Статус проекта -Truthmark не является сервером памяти и не является MCP-сервером. Это репозиторная практика, упакованная как небольшой CLI-установщик и родные для агентов рабочие поверхности. +Truthmark не является сервером памяти и не является MCP-сервером. Это репозиторная практика, упакованная как небольшой CLI-установщик и родные для агентов рабочие поверхности, которые превращают правила ИИ-процесса в инфраструктуру репозитория. V1 сейчас предоставляет: - `truthmark config` - `truthmark init` - `truthmark check` - управляемые инструкции рабочих процессов в `AGENTS.md` -- сгенерированные skill-поверхности Truth Structure, Truth Sync, Truth Realize и Truth Check для настроенных агентских хостов +- сгенерированные skill-поверхности Truth Structure, Truth Document, Truth Sync, Truth Realize и Truth Check для настроенных агентских хостов - метаданные области ветки - диагностика конфигурации, полномочий, маршрутизации, структуры решений, frontmatter, ссылок и полиглотного покрытия diff --git a/README.zh.md b/README.zh.md index b1e4927..6e66ee3 100644 --- a/README.zh.md +++ b/README.zh.md @@ -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 编码会话也会留下可审查的工程记录，而不是消失在提示历史或不透明的工具状态里。 -它面向这样的团队：你们已经知道代理能生成代码，现在需要仓库本身继续保持清晰、可审查、可治理。 +Truthmark 横幅 -## Truthmark 解决什么问题 +AI 编码代理已经能很快写代码了。真正昂贵的是让仓库事实和实际变更保持一致。 -AI 编码现在上手很容易，治理却很昂贵。一旦代理能快速写代码，仓库事实就会成为控制面。 -这种失效模式很常见：需求留在聊天里，架构决策反复重做，代理改到了错误的区域，分支继承了审查者无法可靠检查的上下文。代码也许推进得很快，但仓库会变得越来越难以信任。 -Truthmark 改变的是工作模型： +Truthmark 在这个流程里加入了一个自动收尾保护。正常路径很简单： -- 分支内事实随分支一起流转，而不是藏在私有工具存储里。 -- Git 让这些事实可以被审查、对比，并在团队内共享。 -- 文档跟着代码走，而不是悄悄变成虚构。 -- 路由明确保存在 `docs/truthmark/areas.md` 和委托的子路由文件中，让代理知道哪些文档负责哪些代码。 -- 当前有效的产品和架构决策保存在它们所治理的规范文档中，而不是带时间戳的规划日志里。 -- 本地优先的工作流不需要守护进程、数据库、远程服务或 MCP 依赖。 +- 代理修改功能代码 +- 运行相关测试 +- 代理结束前，Truth Sync 更新已映射的事实文档 +- 如果产生了事实文档 diff，就审查它 + +大多数工具要求团队养成一种习惯。Truthmark 把这个习惯自动化。 + +Truthmark 把 AI 工作流变成仓库基础设施，而不是个人工具配置。它把一个 Git 原生、按分支生效的事实层安装到仓库里，为代理提供明确的路由和有边界的工作流载体，并让这些事实继续以 Git diff 的形式可审查，而不是散落在提示历史、陈旧文档或私有工具状态里。 + +这之所以重要，是因为工作流跟着分支一起存在。仓库一旦初始化，规则、路由和已安装的工作流载体就会随仓库一起移动，协作和交接也就不再过度依赖某个人的本地配置。 + +对于已经知道代理能生成代码的团队，Truthmark 解决的是下一个问题：当 AI 辅助开发规模化时，怎样让仓库本身继续保持清晰、可审查、可治理。 + +## 可视化概览 + + + + + + + + + +
+ Truthmark 功能 +
功能
+ Truthmark 安装了什么，以及工作流载体如何拆分。 + 		+ Truthmark 定位 +
定位
+ Truthmark 相对提示词、记忆和规格工作流所处的位置。 +
+ Truthmark 同步流程 +
同步流程
+ Truth Sync 如何在交接前收束普通代码变更。 +
+ +## 为什么团队会采用它 + +Truthmark 不是为了让代理显得更聪明，而是为了让 AI 辅助的仓库变更更值得信任。 + +- 代码变更后的自动 Truth Sync，把文档维护从团队习惯变成工作流保护。 +- 按分支生效的事实会跟着代码一起走，所以审查者可以在普通 Git diff 里检查当前事实。 +- 仓库原生的工作流载体让推广更轻、交接更稳，不再只依赖个人本地配置。 +- `docs/truthmark/areas.md` 和委托的子路由文件里的显式路由，为代理提供更清晰的所有权边界和更安全的写入路径。 +- 本地优先的运行方式避免了守护进程、数据库、远程服务或 MCP 依赖。 - 这个模型适用于 JavaScript、TypeScript、Go、Python、C# 和 Java 代码库。 -对技术负责人来说，它的价值是没有表演成分的治理：测试、代码审查和所有权仍然承担真正的工作；Truthmark 让代理上下文变得持久、可检查，并且限定在当前分支内。 +对技术负责人来说，它的价值是没有额外基础设施负担的治理：测试、代码审查和所有权仍然承担真正的工作；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,14 +130,15 @@ node /path/to/truthmark/dist/main.js check ```text .truthmark/config.yml -TRUTHMARK.md docs/truthmark/areas.md docs/truthmark/areas/repository.md +docs/templates/feature-doc.md docs/features/README.md docs/features/repository/README.md docs/features/repository/overview.md AGENTS.md CLAUDE.md +GEMINI.md ``` 支持的平台是 `codex`、`opencode`、`claude-code`、`github-copilot` 和 `gemini-cli`。默认配置包含全部平台；请先从 `.truthmark/config.yml` 中移除不使用的平台，再重新运行 `truthmark init`。 @@ -109,8 +148,11 @@ CLAUDE.md ## 它如何运行 -Truthmark 不规定应该由哪个子代理运行 Truth Sync。由实际执行的代理和宿主环境决定是委托执行，还是内联运行工作流。 -多数用户不需要直接调用 Truth Sync。正常路径是： +Truthmark 最强的地方是默认路径，而不是一堆手动命令。由实际执行的代理和宿主环境决定是委托执行，还是内联运行已安装的工作流。 + +当行为已经实现但规范事实文档缺失或质量较弱时，使用 Truth Document。代理会读取实现、测试、路由和现有文档，只写事实文档和路由，不能修改功能代码。Codex、Claude Code 和支持的 Copilot IDE 可以用 `/truthmark-document` 调用它；OpenCode 风格的宿主可以用 `/skill truthmark-document` 调用它。 + +多数用户不需要直接调用 Truth Sync。关键在于，只要功能代码发生变化，Truth Sync 就会充当自动收尾保护。正常路径是： ```text 代理修改功能代码 @@ -138,29 +180,31 @@ Codex、Claude Code 和支持的 Copilot IDE 可以用 `/truthmark-realize` 调 ## 它会安装什么 -Truthmark 把持久化的工作流载体保持得很小： +Truthmark 把持久化的工作流载体保持得很小，而且是仓库原生的。运行 `truthmark init` 之后，仓库本身就携带路由、规则和已安装的工作流载体，因此团队不再只依赖某个人的本地配置。 - `.truthmark/config.yml`，用于机器可读配置 -- `TRUTHMARK.md`，用于分支内工作流契约 +- `.truthmark/config.yml`，用于已提交的层级契约 - `docs/truthmark/areas.md`，用于根路由索引 - `docs/truthmark/areas/**/*.md`，用于委托的子路由文件 +- `docs/templates/feature-doc.md`，用于生成工作流采用的可编辑功能文档标准 - 面向已配置平台的受管说明块，例如 `AGENTS.md`、`CLAUDE.md`、Copilot 指令和 `GEMINI.md` -- 面向 Truth Structure、Truth Sync、Truth Realize 和 Truth Check 的宿主原生技能、提示或命令 +- 面向 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 @@ -173,7 +217,7 @@ truthmark check --json `config` 只写入 `.truthmark/config.yml`，除非使用 `--stdout`。 `init` 需要 `.truthmark/config.yml`，然后安装或刷新本地工作流文件。 `check` 验证配置、权限边界、路由、承载决策的文档、frontmatter、内部链接、分支范围和覆盖率诊断。 -Truth Structure、Truth Sync、Truth Realize 和 Truth Check 是已安装的代理工作流，不是日常使用的顶层 CLI 命令。 +Truth Structure、Truth Document、Truth Sync、Truth Realize 和 Truth Check 是已安装的代理工作流，不是日常使用的顶层 CLI 命令。 ## 它为什么存在 @@ -191,14 +235,14 @@ Truth Structure、Truth Sync、Truth Realize 和 Truth Check 是已安装的代 ## 项目状态 -Truthmark 不是记忆服务器，也不是 MCP 服务器。它是一套仓库实践，被打包成一个小型 CLI 安装器和代理原生的工作流载体。 +Truthmark 不是记忆服务器，也不是 MCP 服务器。它是一套仓库实践，被打包成一个小型 CLI 安装器和代理原生的工作流载体，用来把 AI 工作流规则变成仓库基础设施。 V1 目前提供： - `truthmark config` - `truthmark init` - `truthmark check` - 受管的 `AGENTS.md` 工作流说明 -- 为已配置代理宿主生成的 Truth Structure、Truth Sync、Truth Realize 和 Truth Check 技能载体 +- 为已配置代理宿主生成的 Truth Structure、Truth Document、Truth Sync、Truth Realize 和 Truth Check 技能载体 - 分支范围元数据 - 配置、权限边界、路由、决策结构、frontmatter、链接和多语言覆盖率诊断 diff --git a/TRUTHMARK.md b/TRUTHMARK.md deleted file mode 100644 index acdb026..0000000 --- a/TRUTHMARK.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -status: active -doc_type: truthmark -last_reviewed: 2026-05-10 -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.2 version marker. After upgrading Truthmark, rerun `truthmark init` and review generated workflow diffs. - -Workflow runtime lives in installed skills and managed instruction blocks. Agents inspect the checkout directly; `truthmark check` is optional validation. - -Truth Sync follows code; Truth Realize follows docs. Truth Sync may update mapped truth docs; Truth Realize never edits truth docs or routing. diff --git a/docs/README.md b/docs/README.md index 764de8e..98d0584 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,10 +1,10 @@ --- status: active doc_type: index -last_reviewed: 2026-05-09 +last_reviewed: 2026-05-12 source_of_truth: - docs/ai/repo-rules.md - - ../TRUTHMARK.md + - ../.truthmark/config.yml --- # Truthmark Docs Index @@ -13,14 +13,14 @@ source_of_truth: `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. -`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 When documents conflict, authority descends in this order: 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 +2. [.truthmark/config.yml](../.truthmark/config.yml) for the committed hierarchy 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 @@ -37,6 +37,7 @@ When documents conflict, authority descends in this order: - `docs/standards/` for reusable constraints and completion rules - `docs/architecture/` for current system structure - `docs/features/` for current behavior and invariants +- `docs/templates/` for editable scaffold templates used to create new docs - `docs/features/contracts.md` for stable contracts the CLI exposes ### Human-centric docs @@ -52,6 +53,7 @@ When documents conflict, authority descends in this order: | `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/templates/` | template | both | Editable templates for scaffolded docs; templates are not Truth Sync targets | ## Frontmatter Policy @@ -82,7 +84,7 @@ 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 diff --git a/docs/ai/agent-onboarding.md b/docs/ai/agent-onboarding.md index e82fd35..db81d63 100644 --- a/docs/ai/agent-onboarding.md +++ b/docs/ai/agent-onboarding.md @@ -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 @@ -44,9 +44,10 @@ Read: Read: -1. [TRUTHMARK.md](../../TRUTHMARK.md) +1. [.truthmark/config.yml](../../.truthmark/config.yml) 2. [docs/features/installed-workflows.md](../features/installed-workflows.md) 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) ### Documentation structure or policy changes diff --git a/docs/ai/agent-skills-workflow-review.md b/docs/ai/agent-skills-workflow-review.md new file mode 100644 index 0000000..937cfce --- /dev/null +++ b/docs/ai/agent-skills-workflow-review.md @@ -0,0 +1,91 @@ +--- +status: active +doc_type: agent-guide +last_reviewed: 2026-05-13 +source_of_truth: + - repo-rules.md + - ../features/installed-workflows.md + - ../../.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://docs.anthropic.com/en/docs/claude-code/slash-commands +--- + +# Agent Skills And Workflow Review + +This note summarizes the external skill-authoring guidance reviewed on 2026-05-13 and applies it to Truthmark's installed project workflows. It is a reference for future workflow-surface changes, not a replacement for [installed-workflows.md](../features/installed-workflows.md). + +## External Standard + +Agent skills should be small, concrete, and triggerable from metadata alone. OpenAI and Anthropic both treat `name` and `description` as the first progressive-disclosure layer: the agent decides whether to load the full `SKILL.md` from that metadata. The description therefore needs concrete use cases, non-use cases, expected outputs, and success criteria. + +Keep `SKILL.md` focused on the core procedure. Move rare, variant-specific, or long reference material into explicitly linked `references/` files. Use `scripts/` only for deterministic repeated mechanics; leave interpretation, comparison, judgment, and reporting to the model. + +Reliable skills need validation, not only syntax checks. Deterministic tests can prove rendered metadata, required routing cues, report shapes, and write-boundary text. They cannot prove that every future AI agent will select the right skill in every realistic conversation. + +Security posture matters because skills can contain instructions, scripts, assets, and external dependencies. Treat installed skills as executable agent runtime: inspect the bundled files, scripts, dependency behavior, and any network instructions before trusting them. + +## Installed Surface + +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`. + +## What Is Working + +- 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 the detailed procedures live in explicit workflow surfaces, which preserves ordinary task context. +- Codex metadata correctly makes only Sync implicitly invocable. Manual workflows remain explicit in Codex, which reduces 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. + +## Critical Findings + +1. Medium: frontmatter descriptions need explicit negative routing cases. + The body text has good boundaries, but the body loads only after the skill triggers. Descriptions should include concise "do not use when" clauses for nearby workflows. This matters most for Structure versus Document, Document versus Sync, and Check versus ordinary validation. + +2. Low: repeated hierarchy and decision-truth text increases drift risk. + The duplication is defensible because generated host surfaces should remain standalone after install. Still, shared generator constants and tests should continue to own this text. If the body grows substantially, consider a generated `references/truthmark-common.md` only when each supported host reliably exposes skill references. + +3. Low: `truthmark-check` can read like a replacement for normal verification. + The skill body says `truthmark check` is optional and direct inspection is canonical. The description could still clarify that Truth Check is for repository-truth audits, not a substitute for lint, tests, typecheck, code review, or the finish-time Sync gate. + +## Resolved Notes + +- Resolved 2026-05-13: `truthmark-document` metadata now names Truth Sync, Truth Check, and Truth Structure as the 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. + +## Deterministic Coverage Matrix + +| Workflow | Positive trigger examples | Negative trigger examples | Key success checks | +| --- | --- | --- | --- | +| Sync | "I changed session code; finish and sync truth" | docs-only edit, formatting-only edit, no functional code diff | 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" | repairs route topology before docs, creates bounded starter docs, preserves authored content | +| Document | "document existing order submission behavior" | "implement the behavior in this truth doc" | reads code and tests, writes docs/routing only, does not edit functional code | +| Realize | "realize docs/features/auth/session-timeout.md into code" | "sync docs after my code change" | reads truth docs first, edits functional code only, runs relevant tests | +| Check | "audit truth health before review" | "run lint and tests" | reports issues and suggested fixes, optionally runs `truthmark check`, does not silently rewrite unrelated files | + +## Next Improvements + +- Add deterministic description-quality tests that require positive and negative routing cues in every generated `SKILL.md` description. +- Treat prompt-style agent evals, if ever 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, or network-capable dependencies. diff --git a/docs/ai/repo-rules.md b/docs/ai/repo-rules.md index 6d0b6bb..6d74b63 100644 --- a/docs/ai/repo-rules.md +++ b/docs/ai/repo-rules.md @@ -1,23 +1,22 @@ --- status: active doc_type: agent-rules -last_reviewed: 2026-05-10 +last_reviewed: 2026-05-13 source_of_truth: - ../../AGENTS.md - ../README.md - - ../../TRUTHMARK.md --- # Repository Rules -Repository-wide agent authority, routing, and completion rules. Prefer the smallest sufficient read; detailed behavior lives in [docs/](../README.md). +Repository-wide agent authority, routing, and completion rules. Read the smallest sufficient set; detailed behavior lives in [docs/](../README.md). ## Authority Conflict order: 1. this file -2. [TRUTHMARK.md](../../TRUTHMARK.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` @@ -25,36 +24,34 @@ Conflict order: 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. -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 clearly required. +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. ## Product Boundary -Truthmark is a local-first Node/TypeScript repository truth protocol. CLI commands are `config`, `init`, and `check`; Truth Structure, Truth Sync, Truth Realize, and Truth Check are installed workflow surfaces, not CLI commands. Runtime is installed `SKILL.md` files plus the managed `AGENTS.md` block. `config` writes `.truthmark/config.yml` (`platforms` selects agent surfaces), `init` installs or refreshes surfaces, and `check` validates truth artifacts. Agents inspect the active worktree directly. No daemon, database, remote service, or V1 MCP server. +Truthmark has three CLI commands: `config`, `init`, and `check`. Truth Structure, Truth Document, Truth Sync, Truth Realize, and Truth Check are installed workflow surfaces, not CLI commands. + +Agents inspect the active checkout directly. There is no daemon, database, remote service, or V1 MCP server. ## Rules 1. Branch-local Markdown is canonical; the current checkout is the truth boundary. 2. Current truth belongs in canonical docs, not historical plans or separate timestamped decision logs. 3. Active decisions and rationale live in the canonical doc for the governed behavior. -4. The `AGENTS.md` Truthmark block is generated; edit templates, not the managed block, unless explicitly maintaining the generated surface. +4. The `AGENTS.md` Truthmark block is generated. Edit templates, not the managed block, unless explicitly maintaining the generated surface. 5. Document implemented V1 behavior only; do not add speculative commands, services, or capabilities. 6. Keep routing explicit: when a code area changes canonical docs, update truth routing in the same change. -7. Behavior, contract, workflow, and completion-rule changes update the nearest canonical doc; major product/onboarding/install/command/positioning/workflow changes also review the root README and localized variants. +7. 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. 8. Follow established module boundaries; avoid duplicate surfaces, single-use abstractions, speculative configurability, and impossible-scenario error handling. -9. Use [testing-and-verification.md](../standards/testing-and-verification.md) and [pre-completion-checklist.md](../standards/pre-completion-checklist.md); define success criteria and loop until verified or blocked. +9. Follow [testing-and-verification.md](../standards/testing-and-verification.md) and [pre-completion-checklist.md](../standards/pre-completion-checklist.md). Define success criteria. Continue until verified or blocked. 10. Work surgically: surface material assumptions or ambiguity, touch only request-traceable lines, match existing style, clean up only artifacts made unused by the current change, and report unrelated issues instead of editing them. +11. Tests prove supported behavior and current contracts. Do not prove a removal by asserting that a deleted string or file is absent unless that absence is the protected boundary. ## Routing -When unfamiliar, start with [docs/README.md](../README.md), [overview.md](../architecture/overview.md), [module-map.md](../architecture/module-map.md), and [contracts.md](../features/contracts.md). +Fast task routing lives in [agent-onboarding.md](agent-onboarding.md). Read only the docs that govern the slice you are changing. -- CLI/scaffold: [init-and-scaffold.md](../features/init-and-scaffold.md), [contracts.md](../features/contracts.md), plus [maintaining-repository-truth.md](../standards/maintaining-repository-truth.md) for docs placement or AGENTS management; new repos run `truthmark config` before `truthmark init`. -- Check/routing/validation: [check-diagnostics.md](../features/check-diagnostics.md), [documentation-governance.md](../standards/documentation-governance.md), [contracts.md](../features/contracts.md). -- Workflows/reporting: [TRUTHMARK.md](../../TRUTHMARK.md), [installed-workflows.md](../features/installed-workflows.md), plus [maintaining-repository-truth.md](../standards/maintaining-repository-truth.md) for routing or canonical doc placement. -- Docs organization: [docs/README.md](../README.md), [documentation-governance.md](../standards/documentation-governance.md), [maintaining-repository-truth.md](../standards/maintaining-repository-truth.md). - -If blocked, re-read the relevant canonical docs and owning implementation, then surface the blocker instead of guessing. When one file diverges from an established pattern, require justification before copying it. +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 for repository-wide agent rules. Keep it compact and policy-focused; move procedures to standards or guides, keep feature behavior in `docs/features`, and 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/features`, and update `last_reviewed`. diff --git a/docs/architecture/module-map.md b/docs/architecture/module-map.md index 4248cc8..08c2e3d 100644 --- a/docs/architecture/module-map.md +++ b/docs/architecture/module-map.md @@ -26,7 +26,7 @@ This is the quick module-level map for the current Truthmark codebase. | `src/fs/` | Repository-safe path resolution and file writes shared by init and diagnostics | | `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 | diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md index 6157cfd..1738e3f 100644 --- a/docs/architecture/overview.md +++ b/docs/architecture/overview.md @@ -1,12 +1,13 @@ --- status: active doc_type: architecture -last_reviewed: 2026-05-09 +last_reviewed: 2026-05-13 source_of_truth: - - ../../TRUTHMARK.md + - ../../.truthmark/config.yml - ../features/contracts.md - ../features/init-and-scaffold.md - ../features/check-diagnostics.md + - ../features/installed-workflows.md --- # Architecture Overview @@ -31,14 +32,12 @@ 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/` +- 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` -- Gemini custom command surfaces under `.gemini/commands/truthmark/*.toml` 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. @@ -59,33 +58,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 feature behavior, endpoint details, UI copy, validation rules, and bug fixes belong in feature or contract docs unless they change those architecture boundaries. Architecture docs should describe structure and ownership rather than becoming a second home for feature 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 +102,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,6 +114,8 @@ 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 @@ -115,6 +123,7 @@ Current automatic coverage discovery scans common roots such as `src/`, `cmd/`, - 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. +- Architecture docs are maintained for structure and ownership changes, not for ordinary feature 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. diff --git a/docs/assets/truthmark-banner.png b/docs/assets/truthmark-banner.png new file mode 100644 index 0000000..b042396 Binary files /dev/null and b/docs/assets/truthmark-banner.png differ diff --git a/docs/assets/truthmark-features.png b/docs/assets/truthmark-features.png new file mode 100644 index 0000000..90f4646 Binary files /dev/null and b/docs/assets/truthmark-features.png differ diff --git a/docs/assets/truthmark-overview.png b/docs/assets/truthmark-overview.png deleted file mode 100755 index 092709a..0000000 Binary files a/docs/assets/truthmark-overview.png and /dev/null differ diff --git a/docs/assets/truthmark-position.png b/docs/assets/truthmark-position.png new file mode 100644 index 0000000..85c3cbf Binary files /dev/null and b/docs/assets/truthmark-position.png differ diff --git a/docs/assets/truthmark-syncflow.png b/docs/assets/truthmark-syncflow.png new file mode 100644 index 0000000..90f0e05 Binary files /dev/null and b/docs/assets/truthmark-syncflow.png differ diff --git a/docs/features/check-diagnostics.md b/docs/features/check-diagnostics.md index 939a6a6..93af6f9 100644 --- a/docs/features/check-diagnostics.md +++ b/docs/features/check-diagnostics.md @@ -6,8 +6,10 @@ source_of_truth: - ../../src/checks/check.ts - ../../src/checks/authority.ts - ../../src/checks/areas.ts + - ../../src/checks/branch-scope.ts - ../../src/checks/frontmatter.ts - ../../src/checks/links.ts + - ../../src/markdown/discovery.ts --- # Check Diagnostics @@ -158,6 +160,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 @@ -171,6 +174,7 @@ Branch scope identifies the active checkout: - 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. - 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 diff --git a/docs/features/contracts.md b/docs/features/contracts.md index 6a1958d..63313ea 100644 --- a/docs/features/contracts.md +++ b/docs/features/contracts.md @@ -40,7 +40,6 @@ Current fields: The default scaffolded authority list includes: -- `TRUTHMARK.md` - `docs/truthmark/areas.md` - `docs/truthmark/areas/**/*.md` - `docs/ai/**/*.md` @@ -112,12 +111,14 @@ 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` @@ -125,10 +126,12 @@ Current agent-native scaffold targets include: - `.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` @@ -136,16 +139,18 @@ Current agent-native scaffold targets include: - `CLAUDE.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` -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 and `TRUTHMARK.md` also render the Truthmark package version, and `package.json` is the single maintained version source for those markers. `TRUTHMARK.md` stays a compact branch-local contract rather than a duplicate workflow procedure surface. 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 @@ -168,7 +173,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 @@ -195,7 +199,7 @@ For normal branches, `identity` is branch name plus HEAD SHA. For detached check - 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. +- 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 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. - `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. diff --git a/docs/features/init-and-scaffold.md b/docs/features/init-and-scaffold.md index eafa704..4b531b4 100644 --- a/docs/features/init-and-scaffold.md +++ b/docs/features/init-and-scaffold.md @@ -1,9 +1,11 @@ --- status: active doc_type: feature -last_reviewed: 2026-05-10 +last_reviewed: 2026-05-13 source_of_truth: + - ../../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 @@ -25,7 +27,7 @@ This document describes the current behavior of `truthmark config` and `truthmar 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 +4. creates missing configured docs and routing structure such as the configured root route index, the configured default child route file, the configured feature-root README, a default area index README, an editable feature-doc template, 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 @@ -38,11 +40,11 @@ This document describes the current behavior of `truthmark config` and `truthmar 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` +- [docs/templates/feature-doc.md](../templates/feature-doc.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) @@ -50,6 +52,8 @@ Current scaffold targets: - [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` @@ -57,30 +61,34 @@ Current scaffold targets: - `.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-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-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: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. +`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 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, 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. +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 @@ -89,9 +97,11 @@ 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 - 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 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. @@ -110,6 +120,8 @@ Hierarchy is configured in `.truthmark/config.yml`: `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 `//.md`. +`truthmark init` creates [docs/templates/feature-doc.md](../templates/feature-doc.md) when it is missing or empty. The default 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. Its Scope guidance tells agents to split content into another bounded leaf doc when a change introduces a distinct outcome, lifecycle, rule family, external contract, or code owner. +When creating the default bounded leaf truth doc, init reads the repository's 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}}`. Section placeholders such as `{{scope}}` expand to section body text; the template owns heading structure. Existing non-empty template files are preserved so teams can define a local feature-doc standard. ## Current Defaults @@ -117,15 +129,15 @@ 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 `/README.md`, an index at `//README.md`, and a bounded leaf truth doc at `//overview.md` +- default feature scaffolding creates an index at `/README.md`, an index at `//README.md`, an editable template at `docs/templates/feature-doc.md`, and a bounded leaf truth doc at `//overview.md` - 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 Sync, Truth Realize, and Truth Check surfaces are installed only for configured platforms +- 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 the detailed workflow bodies -- `TRUTHMARK.md` is a compact branch-local truth contract and version marker, not a duplicate workflow procedure surface -- scaffolded default standards include AI-native topology repair guidance so new repositories do not rely on human feature-folder discipline +- 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-feature boundary 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 @@ -135,14 +147,15 @@ Important current defaults: Current init JSON reporting uses: -- `truth-sync` for the managed `AGENTS.md` block and generated Truth Structure, Truth Sync, and Truth Check skill assets +- `truth-sync` for the managed `AGENTS.md` block and generated Truth Structure, Truth Document, 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) +- `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 @@ -153,13 +166,17 @@ Current init JSON reporting uses: - 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. -- `TRUTHMARK.md` stays as a small branch-local contract so authority and branch-scope validation have a stable top-level anchor without duplicating `AGENTS.md`. +- 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-12): Feature-doc structure is centralized in `docs/templates/feature-doc.md`; generated workflow skills point agents to that file instead of embedding a full copy of the template. +- Decision (2026-05-13): Default standards define architecture docs as structure and ownership truth, not a place for ordinary feature 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 and `TRUTHMARK.md` terse protects ordinary agent context while preserving the automatic Sync gate, workflow boundaries, and branch-local authority. +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. + +Centralizing the feature-doc template gives repository owners one editable standard for future bounded leaf docs while keeping generated skills compact as more workflow surfaces are added. ## Primary Code Files diff --git a/docs/features/installed-workflows.md b/docs/features/installed-workflows.md index 5ebc957..92391b8 100644 --- a/docs/features/installed-workflows.md +++ b/docs/features/installed-workflows.md @@ -1,9 +1,11 @@ --- status: active doc_type: feature -last_reviewed: 2026-05-10 +last_reviewed: 2026-05-13 source_of_truth: + - ../../src/agents/shared.ts - ../../src/agents/instructions.ts + - ../../src/agents/truth-document.ts - ../../src/agents/truth-structure.ts - ../../src/agents/truth-sync.ts - ../../src/agents/truth-check.ts @@ -44,39 +46,44 @@ The default platform list includes all supported platforms. Teams should remove Workflow invocation examples: - Truth Structure: `/skill truthmark-structure` in OpenCode-style hosts, `/truthmark-structure` or `$truthmark-structure` in Codex, `/truthmark-structure` in Claude Code, `/truthmark-structure` in GitHub Copilot, and `/truthmark:structure` in Gemini CLI +- Truth Document: `/skill truthmark-document` in OpenCode-style hosts, `/truthmark-document` or `$truthmark-document` in Codex, `/truthmark-document` in Claude Code, `/truthmark-document` in GitHub Copilot, and `/truthmark:document` in Gemini CLI - Truth Sync: `/skill truthmark-sync` in OpenCode-style hosts, `/truthmark-sync` or `$truthmark-sync` in Codex, `/truthmark-sync` in Claude Code, `/truthmark-sync` in GitHub Copilot, and `/truthmark:sync` in Gemini CLI - Truth Realize: `/skill truthmark-realize` in OpenCode-style hosts, `/truthmark-realize` or `$truthmark-realize` in Codex, `/truthmark-realize` in Claude Code, `/truthmark-realize` in GitHub Copilot, and `/truthmark:realize` in Gemini CLI - Truth Check: `/skill truthmark-check` in OpenCode-style hosts, `/truthmark-check` or `$truthmark-check` in Codex, `/truthmark-check` in Claude Code, `/truthmark-check` in GitHub Copilot, and `/truthmark:check` in Gemini CLI -- Claude Code installs project skills at `.claude/skills/truthmark-*/SKILL.md`, which surface as `/truthmark-structure`, `/truthmark-sync`, `/truthmark-realize`, and `/truthmark-check` -- GitHub Copilot installs prompt files at `.github/prompts/truthmark-*.prompt.md`, which surface as `/truthmark-structure`, `/truthmark-sync`, `/truthmark-realize`, and `/truthmark-check` in supported Copilot IDEs -- Gemini CLI installs project-scoped custom commands at `.gemini/commands/truthmark/*.toml`, which surface as `/truthmark:structure`, `/truthmark:sync`, `/truthmark:realize`, and `/truthmark:check` +- Claude Code installs project skills at `.claude/skills/truthmark-*/SKILL.md`, which surface as `/truthmark-structure`, `/truthmark-document`, `/truthmark-sync`, `/truthmark-realize`, and `/truthmark-check` +- GitHub Copilot installs prompt files at `.github/prompts/truthmark-*.prompt.md`, which surface as `/truthmark-structure`, `/truthmark-document`, `/truthmark-sync`, `/truthmark-realize`, and `/truthmark-check` in supported Copilot IDEs +- Gemini CLI installs project-scoped custom commands at `.gemini/commands/truthmark/*.toml`, which surface as `/truthmark:structure`, `/truthmark:document`, `/truthmark:sync`, `/truthmark:realize`, and `/truthmark:check` The managed `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, and equivalent platform instruction blocks are compact automatic-Sync trigger and boundary indexes. They intentionally omit non-automatic workflow procedures, report examples, and long 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 skill files, Gemini command files, Codex metadata, and managed instruction blocks 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. +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 preserves repository instruction authority while clarifying that implementation code and canonical truth docs are inspected evidence for current behavior and must not silently override workflow write boundaries. Truthmark-owned workflow surfaces are generated under host-specific directories such as `.codex/skills/`, `.claude/skills/`, `.opencode/skills/`, and `.github/prompts/`. 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 `//.md`. +When generated Truth Structure, Truth Document, or Truth Sync surfaces tell an agent to create or update a feature doc, they point to [docs/templates/feature-doc.md](../templates/feature-doc.md) as the editable local standard. Agents should read that file, follow its frontmatter, heading order, and section intent, and align existing feature docs to the template standard while preserving authored content that remains accurate. When the template is missing, generated workflow text falls back to the built-in minimal feature-doc structure. + +Generated workflows maintain architecture docs only for architecture-level changes: system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership. Ordinary feature behavior, endpoint details, UI copy, validation rules, and bug fixes belong in feature or contract docs unless they change those architecture boundaries. ## 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. +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, catch-all, unrouteable, 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 +- repair missing, stale, broad, overloaded, catch-all, unrouteable, 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 +- read [docs/templates/feature-doc.md](../templates/feature-doc.md) before creating or updating feature 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 +- split broad, overloaded, or catch-all routing before creating or extending generic feature docs - operate from committed repository files when the Truthmark CLI is unavailable Completed reports include: @@ -88,6 +95,31 @@ Completed reports include: - `Topology decisions` - `Notes` +## Truth Document + +Truth Document is manual and implementation-first. It documents existing implemented behavior when no functional-code change is required, or when Truth Sync, Truth Check, or Truth Structure reports implemented behavior that lacks canonical truth docs. + +The agent should: + +- inspect implementation code, tests, `.truthmark/config.yml`, [docs/truthmark/areas.md](../truthmark/areas.md), relevant child route files, and existing canonical docs directly +- document current implemented behavior only, without inventing planned behavior or future endpoints +- write canonical truth docs and routing files only +- never 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 and create or update bounded leaf truth docs for current behavior +- keep feature docs behavior-oriented rather than 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 +- read [docs/templates/feature-doc.md](../templates/feature-doc.md) before creating or updating feature docs + +Completed reports include: + +- `Implementation reviewed` +- `Truth docs created` +- `Truth docs updated` +- `Routing updated` +- `Notes` + ## Truth Sync Truth Sync is code-first and has two trigger paths: @@ -98,7 +130,7 @@ Truth Sync is code-first and has two trigger paths: - 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. +The agent should inspect staged, unstaged, and untracked functional-code changes directly. It should read `.truthmark/config.yml`, [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. @@ -106,9 +138,11 @@ The acting agent and host environment decide whether to delegate Truth Sync to a 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. +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. -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. +Before updating truth docs, Truth Sync applies a topology quality gate. If routing is missing, stale, broad, overloaded, catch-all, or cannot map changed code to a bounded truth owner, it should not create another generic feature doc. It should run Truth Structure first when repair is safe and in scope, or block and recommend Truth Structure when topology repair is unsafe, ambiguous, or outside the task boundary. Truth Sync must not append behavior details to a feature `README.md`. When routeable behavior lacks a small current-truth doc, it should create or update a bounded leaf truth doc instead. +When Truth Sync creates or updates a feature doc, it should read [docs/templates/feature-doc.md](../templates/feature-doc.md) first, follow the repository's local template standard, and fix poor truth-doc alignment encountered in the touched doc. +When Truth Sync sees an architecture-level code change, it should update the owning architecture doc in the same sync instead of hiding structure or ownership changes in a feature doc. Current skip reasons are: @@ -118,6 +152,8 @@ Current skip reasons are: - no Truthmark config exists yet - no functional code changes +Truth Sync's generated frontmatter description and Codex metadata carry these skip cases because skill metadata is the host-visible routing boundary before the full workflow body is loaded. + Completed reports include: - `Changed code reviewed` @@ -170,14 +206,19 @@ Truthmark currently provides installed workflow text, generated Codex and OpenCo - 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 enough for ordinary agent context; non-automatic workflow procedure belongs in generated skills and command files. +- Generated workflow surfaces must not demote repository instruction docs such as `docs/ai/repo-rules.md` when warning agents that product truth cannot override workflow write boundaries. +- Truth Document exists because documenting existing implemented behavior without code changes is not a Truth Sync run; Sync stays code-first while Document owns manual missing-truth generation. +- Truth Document metadata should name Truth Sync, Truth Check, and Truth Structure as the workflows that can hand off missing implemented-behavior documentation, rather than using generic update wording. - 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. +- Truth Sync must not worsen weak topology by adding generic feature docs behind missing, stale, broad, overloaded, catch-all, or unrouteable routing. +- Truth Sync metadata should include its skip cases because documentation-only work, formatting-only work, behavior-preserving renames, missing Truthmark config, and no-functional-code changes should not trigger the finish-time sync path. - Feature `README.md` files are indexes; bounded leaf docs are the normal Truth Sync targets for current behavior. +- Generated workflow surfaces refer to `docs/templates/feature-doc.md` instead of embedding a full feature-doc template so repository owners have one editable standard as more skills are added. - 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. +- Active decisions belong in the canonical doc they govern. Workflow text should date active decisions inline when added or changed and 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 workflow files: Codex uses `.codex/skills/`, Claude Code uses `.claude/skills/`, GitHub Copilot uses `.github/prompts/`, OpenCode uses `.opencode/skills/`, and repo-root `skills/` is not a generated V1 target. @@ -191,6 +232,8 @@ Putting topology governance in installed workflow text keeps the large-repositor 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. +Keeping feature-doc structure in an editable template prevents generated skills from becoming competing template copies while preserving a built-in fallback for repositories that do not have the template file yet. + ## Primary Code Files - `src/agents/instructions.ts` diff --git a/docs/features/release/README.md b/docs/features/release/README.md new file mode 100644 index 0000000..496eff0 --- /dev/null +++ b/docs/features/release/README.md @@ -0,0 +1,17 @@ +--- +status: active +doc_type: index +last_reviewed: 2026-05-13 +source_of_truth: + - ../../truthmark/areas/release-automation.md +--- + +# Release Feature 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) diff --git a/docs/features/release/automation.md b/docs/features/release/automation.md new file mode 100644 index 0000000..0e68c9b --- /dev/null +++ b/docs/features/release/automation.md @@ -0,0 +1,61 @@ +--- +status: active +doc_type: feature +last_reviewed: 2026-05-13 +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. + +## Current Behavior + +- 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`. + +## 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. + +## Flows And States + +- Change validation flow: push or pull request -> `CI` workflow -> `verify` job -> `npm run check` and `npm run package:check`. +- Release flow: published GitHub release -> `Publish` workflow -> `publish` job -> `npm run release:check` -> `npm publish`. + +## 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. diff --git a/docs/features/repository/README.md b/docs/features/repository/README.md index ba8bc70..5fc4edc 100644 --- a/docs/features/repository/README.md +++ b/docs/features/repository/README.md @@ -1,9 +1,9 @@ --- 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 diff --git a/docs/features/repository/overview.md b/docs/features/repository/overview.md index ee4bac9..a89086f 100644 --- a/docs/features/repository/overview.md +++ b/docs/features/repository/overview.md @@ -1,27 +1,59 @@ --- status: active doc_type: feature -last_reviewed: 2026-05-09 +last_reviewed: 2026-05-13 source_of_truth: - - ../../truthmark/areas/repository.md + - ../../truthmark/areas/init-and-scaffold.md + - ../../../src/init/init.ts + - ../../../src/templates/init-files.ts --- # Repository Overview +## Purpose + +This doc owns the default bounded feature leaf that `truthmark init` scaffolds for repositories using the default `repository` area. + ## Scope -This bounded leaf truth doc owns the default repository behavior surface created by Truthmark. +This doc covers the seed `docs/features/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` 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. +- `truthmark init` creates `docs/features/repository/overview.md` as the default bounded feature doc for the configured default area. +- The scaffold pairs this leaf doc with a sibling `README.md` index under `docs/features/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 + +- Feature `README.md` files are indexes, not current-behavior targets. +- The default scaffold keeps behavior truth in bounded leaf docs under the configured feature 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 feature 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/features//overview.md` when the configured feature root is `docs/features` and the default area is `repository`. +- The editable content standard for this leaf comes from `docs/templates/feature-doc.md`. ## Product Decisions -- Decision (2026-05-09): Feature README files are indexes; behavior truth belongs in bounded leaf docs. +- Decision (2026-05-13): The default scaffold seeds a bounded leaf doc instead of placing current behavior in a feature `README.md`. ## Rationale -Bounded leaf docs keep agent context focused and prevent large products from accumulating unreviewable feature manuals. +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/feature-doc.md` when the feature-doc standard changes. +- Update this doc when the default area leaf path or seeded content rules change. diff --git a/docs/standards/default-principles.md b/docs/standards/default-principles.md index d0234d9..abb2d3e 100644 --- a/docs/standards/default-principles.md +++ b/docs/standards/default-principles.md @@ -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 diff --git a/docs/standards/documentation-governance.md b/docs/standards/documentation-governance.md index 47b1221..b5ededd 100644 --- a/docs/standards/documentation-governance.md +++ b/docs/standards/documentation-governance.md @@ -44,7 +44,7 @@ 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/` @@ -62,6 +62,10 @@ Use a small number of stable document classes: 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 feature behavior, endpoint details, UI copy, validation rules, or bug fixes unless those changes alter architecture boundaries. Keep product behavior in feature 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 feature 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 feature 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. diff --git a/docs/standards/maintaining-repository-truth.md b/docs/standards/maintaining-repository-truth.md index 8d056b9..1186387 100644 --- a/docs/standards/maintaining-repository-truth.md +++ b/docs/standards/maintaining-repository-truth.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. diff --git a/docs/standards/pre-completion-checklist.md b/docs/standards/pre-completion-checklist.md index 31b98c8..d3505fb 100644 --- a/docs/standards/pre-completion-checklist.md +++ b/docs/standards/pre-completion-checklist.md @@ -1,7 +1,7 @@ --- 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 @@ -18,7 +18,7 @@ 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 [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)? diff --git a/docs/standards/testing-and-verification.md b/docs/standards/testing-and-verification.md index b7d0399..fbf93d1 100644 --- a/docs/standards/testing-and-verification.md +++ b/docs/standards/testing-and-verification.md @@ -1,7 +1,7 @@ --- status: active doc_type: standard -last_reviewed: 2026-05-09 +last_reviewed: 2026-05-13 source_of_truth: - ../../package.json - ../features/contracts.md @@ -35,6 +35,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. diff --git a/docs/templates/feature-doc.md b/docs/templates/feature-doc.md new file mode 100644 index 0000000..1c8a6c3 --- /dev/null +++ b/docs/templates/feature-doc.md @@ -0,0 +1,80 @@ +--- +status: active +doc_type: feature +last_reviewed: 2026-05-12 +source_of_truth: + - {{source_of_truth}} +--- + +# {{title}} + +## Purpose + + + +{{purpose}} + +## Scope + +{{scope}} + + + +This doc was created from the editable feature-doc template at {{template_path}}. + +## Current Behavior + + + +{{current_behavior}} + +## Core Rules + + + +{{core_rules}} + +## Flows And States + + + +{{flows_and_states}} + +## Contracts + + + +{{contracts}} + +## Product Decisions + + + +{{decision}} + +## Rationale + + + +{{rationale}} + +## Non-Goals + + + +{{non_goals}} + +## Maintenance Notes + + + +{{maintenance_notes}} diff --git a/docs/truthmark/areas.md b/docs/truthmark/areas.md index 05bf646..6da98b6 100644 --- a/docs/truthmark/areas.md +++ b/docs/truthmark/areas.md @@ -1,22 +1,96 @@ --- status: active doc_type: routing -last_reviewed: 2026-05-09 +last_reviewed: 2026-05-13 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/realize/** +- src/sync/** +- src/templates/agents-block.ts +- src/templates/codex-skills.ts +- src/templates/generated-surfaces.ts +- 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/** + +Update truth when: +- CI verification steps or triggers change +- release publishing prerequisites or publish steps change diff --git a/docs/truthmark/areas/check-and-routing.md b/docs/truthmark/areas/check-and-routing.md new file mode 100644 index 0000000..f543450 --- /dev/null +++ b/docs/truthmark/areas/check-and-routing.md @@ -0,0 +1,34 @@ +--- +status: active +doc_type: routing +last_reviewed: 2026-05-13 +source_of_truth: + - ../areas.md + - ../../README.md + - ../../ai/repo-rules.md +--- + +# Check And Routing Areas + +## Check And Routing + +Truth documents: +- docs/architecture/overview.md +- docs/architecture/module-map.md +- docs/features/check-diagnostics.md +- docs/features/contracts.md +- docs/features/routing-examples.md +- docs/standards/documentation-governance.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 diff --git a/docs/truthmark/areas/contracts-and-commands.md b/docs/truthmark/areas/contracts-and-commands.md new file mode 100644 index 0000000..7c282ec --- /dev/null +++ b/docs/truthmark/areas/contracts-and-commands.md @@ -0,0 +1,29 @@ +--- +status: active +doc_type: routing +last_reviewed: 2026-05-13 +source_of_truth: + - ../areas.md + - ../../README.md + - ../../ai/repo-rules.md +--- + +# Contracts And Commands Areas + +## Contracts And Commands + +Truth documents: +- docs/README.md +- docs/features/contracts.md + +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 diff --git a/docs/truthmark/areas/init-and-scaffold.md b/docs/truthmark/areas/init-and-scaffold.md new file mode 100644 index 0000000..e85f4b7 --- /dev/null +++ b/docs/truthmark/areas/init-and-scaffold.md @@ -0,0 +1,31 @@ +--- +status: active +doc_type: routing +last_reviewed: 2026-05-13 +source_of_truth: + - ../areas.md + - ../../README.md + - ../../ai/repo-rules.md +--- + +# Initialization And Scaffold Areas + +## Initialization And Scaffold + +Truth documents: +- docs/architecture/overview.md +- docs/architecture/module-map.md +- docs/features/init-and-scaffold.md +- docs/features/repository/overview.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 diff --git a/docs/truthmark/areas/installed-workflows.md b/docs/truthmark/areas/installed-workflows.md new file mode 100644 index 0000000..0f72175 --- /dev/null +++ b/docs/truthmark/areas/installed-workflows.md @@ -0,0 +1,31 @@ +--- +status: active +doc_type: routing +last_reviewed: 2026-05-13 +source_of_truth: + - ../areas.md + - ../../README.md + - ../../ai/repo-rules.md +--- + +# Installed Workflows Areas + +## Installed Workflows + +Truth documents: +- docs/features/contracts.md +- docs/features/installed-workflows.md + +Code surface: +- src/agents/** +- src/realize/** +- src/sync/** +- src/templates/agents-block.ts +- src/templates/codex-skills.ts +- src/templates/generated-surfaces.ts +- 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 diff --git a/docs/truthmark/areas/release-automation.md b/docs/truthmark/areas/release-automation.md new file mode 100644 index 0000000..64dd09e --- /dev/null +++ b/docs/truthmark/areas/release-automation.md @@ -0,0 +1,23 @@ +--- +status: active +doc_type: routing +last_reviewed: 2026-05-13 +source_of_truth: + - ../areas.md + - ../../README.md + - ../../ai/repo-rules.md +--- + +# Release Automation Areas + +## Release Automation + +Truth documents: +- docs/features/release/automation.md + +Code surface: +- .github/workflows/** + +Update truth when: +- CI verification steps or triggers change +- release publishing prerequisites or publish steps change diff --git a/docs/truthmark/areas/repository.md b/docs/truthmark/areas/repository.md index fe0572f..1fe8069 100644 --- a/docs/truthmark/areas/repository.md +++ b/docs/truthmark/areas/repository.md @@ -1,78 +1,20 @@ --- status: active -doc_type: routing +doc_type: area-route last_reviewed: 2026-05-09 source_of_truth: - - ../areas.md - - ../../README.md - - ../../ai/repo-rules.md + - ../../../.truthmark/config.yml --- # Repository Areas -## CLI And Scaffold Surface +## Repository Truth documents: -- docs/README.md -- TRUTHMARK.md -- docs/features/contracts.md -- docs/features/init-and-scaffold.md +- docs/features/repository/overview.md Code surface: -- src/cli/** -- src/fs/** -- src/init/** -- src/templates/** -- src/output/** +- src/** 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 +- behavior changes affect repository truth diff --git a/package-lock.json b/package-lock.json index 3b63d2a..d8d79ff 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "truthmark", - "version": "1.2.2", + "version": "1.2.3", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "truthmark", - "version": "1.2.2", + "version": "1.2.3", "license": "MIT", "dependencies": { "ajv": "^8.17.1", diff --git a/package.json b/package.json index 2c0cd15..7c12555 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "truthmark", - "version": "1.2.2", + "version": "1.2.3", "description": "Git-native, branch-scoped truth workflow installer for local AI coding agents.", "license": "MIT", "type": "module", diff --git a/src/agents/instructions.ts b/src/agents/instructions.ts index 828d378..d0bc94a 100644 --- a/src/agents/instructions.ts +++ b/src/agents/instructions.ts @@ -9,7 +9,7 @@ export const renderTruthStructureInstructions = ( config: TruthmarkConfig = defaultAgentConfig(), ): string => { return `### Truth Structure -Use when area routing is missing, stale, broad, or explicitly requested. +Use when area routing is missing, stale, broad, overloaded, catch-all, unrouteable, or explicitly requested. Invocations: ${TRUTH_STRUCTURE_EXPLICIT_INVOCATIONS} Inspect repository layout, ${config.docs.routing.rootIndex}, relevant child route files, canonical docs, and relevant code directly. Create or repair routing and starter canonical truth docs only when useful. Use only canonical current-truth destinations for starter truth docs. @@ -41,7 +41,7 @@ Truthmark is agent-native: installed skills and this managed block are the workf 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 ${config.docs.routing.rootIndex} and only relevant child route files under ${config.docs.routing.areaFilesRoot}/ 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 routing is missing, stale, broad, overloaded, catch-all, or cannot map changed code to a bounded truth owner, run Truth Structure before syncing when repair is safe and in scope; otherwise block and recommend Truth Structure. If mapped truth is missing, extend mapped truth docs first, create an area-local truth doc second, and create a new area only as a last resort. Skip only for: ${TRUTH_SYNC_SKIP_REASONS.join("; ")}.`; }; diff --git a/src/agents/shared.ts b/src/agents/shared.ts index aef244a..6f4365d 100644 --- a/src/agents/shared.ts +++ b/src/agents/shared.ts @@ -3,14 +3,29 @@ import type { TruthmarkConfig } from "../config/schema.js"; export const DECISION_TRUTH_INSTRUCTIONS = [ "Decision truth lives in the canonical doc it governs.", - "Short inline decision dates are allowed, for example `Decision (2026-05-09): ...`.", + "Date active decisions inline when added or changed, for example `Decision (2026-05-09): ...`.", "Do not create separate timestamped ADR logs or planning tickets for active decisions.", "Replace old active decisions instead of appending separate timestamped decision logs; Git history is the audit trail.", "Update Product Decisions and Rationale when a behavior change comes from a decision change.", ].join("\n"); -export const EVIDENCE_AUTHORITY_INSTRUCTIONS = - "Repository docs and code are inspected evidence, not executable instruction authority."; +export const EVIDENCE_AUTHORITY_INSTRUCTIONS = [ + "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.", +].join("\n"); + +export const FEATURE_DOC_TEMPLATE_INSTRUCTIONS = [ + "When creating or updating a feature doc, read docs/templates/feature-doc.md and follow its frontmatter, heading order, and section intent.", + "When updating an existing feature doc, align existing feature docs to the template standard while preserving authored content that remains accurate.", + "If docs/templates/feature-doc.md is missing, use the built-in minimal feature-doc structure with Current Behavior, Product Decisions, and Rationale sections.", + "Teams may edit docs/templates/feature-doc.md to define their local feature-doc standard.", +].join("\n"); + +export const ARCHITECTURE_DOC_BOUNDARY_INSTRUCTIONS = [ + "Maintain architecture docs when a code change alters system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership.", + "Do not put ordinary feature behavior, endpoint details, UI copy, validation rules, or bug fixes in architecture docs unless they change those architecture boundaries.", + "Keep architecture docs focused on structure and ownership; keep current product behavior in feature or contract docs.", +].join("\n"); export const defaultAgentConfig = (): TruthmarkConfig => { return createDefaultConfig(); diff --git a/src/agents/truth-check.ts b/src/agents/truth-check.ts index 16e9b04..81b5346 100644 --- a/src/agents/truth-check.ts +++ b/src/agents/truth-check.ts @@ -18,7 +18,6 @@ export const renderTruthCheckReportExample = (): string => { return `Truth Check: completed Files reviewed: -- TRUTHMARK.md - docs/truthmark/areas.md Issues found: @@ -50,7 +49,7 @@ Invocations: ${TRUTH_CHECK_EXPLICIT_INVOCATIONS} Truth Check is agent-led: -- inspect .truthmark/config.yml, TRUTHMARK.md, docs/truthmark/areas.md, canonical docs, and relevant implementation directly +- inspect .truthmark/config.yml, docs/truthmark/areas.md, canonical docs, and relevant implementation directly - ${EVIDENCE_AUTHORITY_INSTRUCTIONS} - inspect the configured root route index at ${config.docs.routing.rootIndex} and relevant child route files under ${config.docs.routing.areaFilesRoot}/ - check that current docs describe current code rather than historical plans diff --git a/src/agents/truth-document.ts b/src/agents/truth-document.ts new file mode 100644 index 0000000..cfc1fbb --- /dev/null +++ b/src/agents/truth-document.ts @@ -0,0 +1,76 @@ +import type { TruthmarkConfig } from "../config/schema.js"; +import { + ARCHITECTURE_DOC_BOUNDARY_INSTRUCTIONS, + DECISION_TRUTH_INSTRUCTIONS, + EVIDENCE_AUTHORITY_INSTRUCTIONS, + FEATURE_DOC_TEMPLATE_INSTRUCTIONS, + defaultAgentConfig, + renderHierarchySummary, +} from "./shared.js"; +import { TRUTHMARK_VERSION } from "../version.js"; + +const renderMarkdownExample = (content: string): string => { + return ["```md", content, "```"].join("\n"); +}; + +export const TRUTH_DOCUMENT_EXPLICIT_INVOCATIONS = + "OpenCode /skill truthmark-document; Codex /truthmark-document or $truthmark-document; Claude Code /truthmark-document; GitHub Copilot /truthmark-document; Gemini CLI /truthmark:document."; + +export const renderTruthDocumentReportExample = (): string => { + return `Truth Document: completed + +Implementation reviewed: +- src/api/orders/** + +Truth docs created: +- docs/features/orders/order-submission.md + +Truth docs updated: +- docs/features/contracts.md + +Routing updated: +- docs/truthmark/areas/orders.md + +Notes: +- Documented existing order submission behavior from route handlers and tests.`; +}; + +export const renderTruthDocumentSkillBody = ( + config: TruthmarkConfig = defaultAgentConfig(), +): string => { + return `--- +name: truthmark-document +description: Use when the user explicitly asks to document existing implemented behavior, or when Truth Sync, Truth Check, or Truth Structure reports implemented behavior that lacks canonical truth docs. Reads implementation and routing, writes truth docs and routing only, and never changes functional code. +argument-hint: Optional implemented behavior, API endpoint, route, controller, package, or truth-doc area to document +user-invocable: true +truthmark-version: ${TRUTHMARK_VERSION} +--- + +# Truthmark Document + +Use this skill to document existing implemented behavior when no functional-code changes are required for the task. +Invocations: ${TRUTH_DOCUMENT_EXPLICIT_INVOCATIONS} + +Truth Document is manual and implementation-first: + +- run only when the user explicitly asks to generate or update truth docs for existing behavior, or when Truth Sync, Truth Check, or Truth Structure reports implemented behavior that lacks canonical truth docs +- inspect .truthmark/config.yml, ${config.docs.routing.rootIndex}, relevant child route files under ${config.docs.routing.areaFilesRoot}/, existing canonical docs, implementation code, and tests directly +- ${EVIDENCE_AUTHORITY_INSTRUCTIONS} +- document current implemented behavior; do not invent future behavior or planned endpoints +- may write canonical truth docs and ${config.docs.routing.rootIndex} or relevant child route files only +- must not write functional code +- when routing is missing, stale, broad, overloaded, catch-all, or cannot map the behavior to a bounded truth owner, run Truth Structure first when routing repair is safe and in scope +- block and recommend Truth Structure when routing repair is unsafe, ambiguous, or outside the task boundary +- keep feature README.md files as indexes rather than truth-document targets +- create or update bounded leaf truth docs when behavior does not fit an existing leaf doc +- keep feature docs behavior-oriented, not endpoint-oriented, unless the endpoint itself is the behavior boundary +- keep API endpoint details in the nearest contract truth doc when such a doc owns the API contract +- preserve unrelated authored content +${FEATURE_DOC_TEMPLATE_INSTRUCTIONS} +${ARCHITECTURE_DOC_BOUNDARY_INSTRUCTIONS} +${renderHierarchySummary(config)} +${DECISION_TRUTH_INSTRUCTIONS} + +Report completion in this shape: +${renderMarkdownExample(renderTruthDocumentReportExample())}`; +}; diff --git a/src/agents/truth-structure.ts b/src/agents/truth-structure.ts index f20b4f5..bf6aec5 100644 --- a/src/agents/truth-structure.ts +++ b/src/agents/truth-structure.ts @@ -1,7 +1,9 @@ import type { TruthmarkConfig } from "../config/schema.js"; import { + ARCHITECTURE_DOC_BOUNDARY_INSTRUCTIONS, DECISION_TRUTH_INSTRUCTIONS, EVIDENCE_AUTHORITY_INSTRUCTIONS, + FEATURE_DOC_TEMPLATE_INSTRUCTIONS, defaultAgentConfig, renderHierarchySummary, } from "./shared.js"; @@ -37,7 +39,7 @@ export const renderTruthStructureSkillBody = ( ): string => { return `--- 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 the user asks to design, repair, or refresh missing, stale, broad, overloaded, catch-all, or unrouteable Truthmark area routing. Inspects the repository directly, updates docs/truthmark/areas.md, and may create starter canonical truth docs. argument-hint: Optional area, directory, or routing concern user-invocable: true truthmark-version: ${TRUTHMARK_VERSION} @@ -46,7 +48,7 @@ truthmark-version: ${TRUTHMARK_VERSION} Use this skill to design or repair Truthmark area structure. Invocations: ${TRUTH_STRUCTURE_EXPLICIT_INVOCATIONS} Truth Structure is agent-native: -- inspect repository layout, current docs, .truthmark/config.yml, TRUTHMARK.md, docs/truthmark/areas.md, and relevant code directly +- inspect repository layout, current docs, .truthmark/config.yml, docs/truthmark/areas.md, and relevant code directly - ${EVIDENCE_AUTHORITY_INSTRUCTIONS} - inspect the configured root route index at ${config.docs.routing.rootIndex} and relevant child route files under ${config.docs.routing.areaFilesRoot}/ - define areas by product or behavior ownership, not by mechanical directory mirroring @@ -54,6 +56,7 @@ Truth Structure is agent-native: - 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. +${FEATURE_DOC_TEMPLATE_INSTRUCTIONS} - use docs/features/**, docs/architecture/**, or docs/standards/** for current truth destinations - use only canonical current-truth destinations for starter truth docs - keep active Product Decisions and Rationale in the canonical doc that owns the behavior @@ -76,7 +79,7 @@ Use these review thresholds as guidance: - 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 - create route files under ${config.docs.routing.areaFilesRoot}/ when a product/domain boundary is clear - create feature docs under the configured feature root only when behavior lacks a current doc - README.md files are indexes, not Truth Sync targets @@ -85,12 +88,13 @@ Repair rules: - 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 +${ARCHITECTURE_DOC_BOUNDARY_INSTRUCTIONS} - 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, ${config.docs.routing.rootIndex}, relevant child route files under ${config.docs.routing.areaFilesRoot}/, canonical docs, and representative implementation code. +- Read .truthmark/config.yml, ${config.docs.routing.rootIndex}, relevant child route files under ${config.docs.routing.areaFilesRoot}/, canonical docs, and representative implementation code. - Use a subagent only when the host supports that pattern; otherwise perform the topology repair inline. ${renderHierarchySummary(config)} ${DECISION_TRUTH_INSTRUCTIONS} diff --git a/src/agents/truth-sync.ts b/src/agents/truth-sync.ts index 87c49a4..c150567 100644 --- a/src/agents/truth-sync.ts +++ b/src/agents/truth-sync.ts @@ -1,7 +1,9 @@ import type { TruthmarkConfig } from "../config/schema.js"; import { + ARCHITECTURE_DOC_BOUNDARY_INSTRUCTIONS, DECISION_TRUTH_INSTRUCTIONS, EVIDENCE_AUTHORITY_INSTRUCTIONS, + FEATURE_DOC_TEMPLATE_INSTRUCTIONS, defaultAgentConfig, renderHierarchySummary, } from "./shared.js"; @@ -23,7 +25,7 @@ export const renderTruthSyncWorkerPrompt = (): string => { 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 @@ -42,7 +44,7 @@ export const renderTruthSyncSkillBody = ( ): string => { return `--- 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 before finishing when functional code changed since the last successful Truth Sync, and when the user explicitly invokes /truthmark-sync, $truthmark-sync, or /truthmark:sync. Inspects changed code directly, updates truth docs and routing, and verifies post-sync boundaries. Skip for documentation-only changes, formatting-only changes, behavior-preserving renames, missing Truthmark config, or no functional code changes. argument-hint: Optional changed-code area, truth-doc area, or sync focus user-invocable: true truthmark-version: ${TRUTHMARK_VERSION} @@ -51,22 +53,25 @@ truthmark-version: ${TRUTHMARK_VERSION} 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: ${TRUTH_SYNC_EXPLICIT_INVOCATIONS} 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 ${config.docs.routing.rootIndex}, relevant child route files under ${config.docs.routing.areaFilesRoot}/, and relevant canonical docs. +2. Read .truthmark/config.yml, the configured root route index at ${config.docs.routing.rootIndex}, relevant child route files under ${config.docs.routing.areaFilesRoot}/, and relevant canonical docs. 3. Identify functional-code changes and the nearest truth docs or routing repairs. 4. ${EVIDENCE_AUTHORITY_INSTRUCTIONS} 5. Code verification is parent-owned: follow repository instructions and task context, and report what ran or why it did not run. 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 feature doc +- run Truth Structure before syncing when topology repair is safe and in scope +- block and recommend Truth Structure when topology repair is unsafe, ambiguous, or outside the current task boundary +- report the route files and changed code paths that require structure repair - README.md files are indexes, not Truth Sync targets - must not append behavior details to a feature README - create or update a bounded leaf truth doc when behavior changes do not fit an existing leaf doc +${FEATURE_DOC_TEMPLATE_INSTRUCTIONS} +${ARCHITECTURE_DOC_BOUNDARY_INSTRUCTIONS} 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 diff --git a/src/checks/branch-scope.ts b/src/checks/branch-scope.ts index de43249..a62a89f 100644 --- a/src/checks/branch-scope.ts +++ b/src/checks/branch-scope.ts @@ -26,7 +26,7 @@ export class BranchScopeFileError extends Error { } } -const RELEVANT_BRANCH_SCOPE_FILES = [".truthmark/config.yml", "TRUTHMARK.md"] as const; +const RELEVANT_BRANCH_SCOPE_FILES = [".truthmark/config.yml"] as const; const toBranchIdentity = (branchName: string | null, headSha: string | null): string => { if (branchName && headSha) { diff --git a/src/config/defaults.ts b/src/config/defaults.ts index 87c15ff..a15fd11 100644 --- a/src/config/defaults.ts +++ b/src/config/defaults.ts @@ -17,7 +17,6 @@ export const DEFAULT_DOCS_HIERARCHY = { } as const; export const DEFAULT_AUTHORITY = [ - "TRUTHMARK.md", DEFAULT_DOCS_HIERARCHY.routing.root_index, `${DEFAULT_DOCS_HIERARCHY.routing.area_files_root}/**/*.md`, `${DEFAULT_DOCS_HIERARCHY.roots.ai}/**/*.md`, diff --git a/src/fs/paths.ts b/src/fs/paths.ts index b6a83de..850eb87 100644 --- a/src/fs/paths.ts +++ b/src/fs/paths.ts @@ -13,6 +13,16 @@ const isPathInsideRoot = (rootDir: string, targetPath: string): boolean => { return targetPath === rootDir || targetPath.startsWith(`${rootDir}${path.sep}`); }; +const isNodeErrorWithCode = (error: unknown, code: string): boolean => { + return error instanceof Error && "code" in error && error.code === code; +}; + +const joinMissingSegments = (resolvedPath: string, missingSegments: string[]): string => { + return missingSegments.reduce((currentResolvedPath, segment) => { + return path.join(currentResolvedPath, segment); + }, resolvedPath); +}; + const resolveThroughExistingAncestor = async (targetPath: string): Promise => { let currentPath = path.resolve(targetPath); const missingSegments: string[] = []; @@ -21,14 +31,27 @@ const resolveThroughExistingAncestor = async (targetPath: string): Promise((resolvedPath, segment) => { - return path.join(resolvedPath, segment); - }, resolvedExistingPath); + return joinMissingSegments(resolvedExistingPath, missingSegments); } catch (error: unknown) { - if (!(error instanceof Error) || !("code" in error) || error.code !== "ENOENT") { + if (!isNodeErrorWithCode(error, "ENOENT")) { throw error; } + try { + const currentStat = await fs.lstat(currentPath); + + if (currentStat.isSymbolicLink()) { + const linkTarget = await fs.readlink(currentPath); + const resolvedLinkTarget = path.resolve(path.dirname(currentPath), linkTarget); + + return joinMissingSegments(resolvedLinkTarget, missingSegments); + } + } catch (lstatError: unknown) { + if (!isNodeErrorWithCode(lstatError, "ENOENT")) { + throw lstatError; + } + } + const parentPath = path.dirname(currentPath); if (parentPath === currentPath) { @@ -151,4 +174,4 @@ export const ensureRepoFile = async ( path: relativePath, status: "unchanged", }; -}; \ No newline at end of file +}; diff --git a/src/init/hierarchy.ts b/src/init/hierarchy.ts index 6b359c8..bf4917c 100644 --- a/src/init/hierarchy.ts +++ b/src/init/hierarchy.ts @@ -1,11 +1,14 @@ +import fs from "node:fs/promises"; import fg from "fast-glob"; import { DEFAULT_DOCS_HIERARCHY } from "../config/defaults.js"; import type { TruthmarkConfig } from "../config/schema.js"; import type { FileWriteResult } from "../fs/paths.js"; -import { ensureRepoFile } from "../fs/paths.js"; +import { ensureRepoFile, resolveRepoPath } from "../fs/paths.js"; import type { Diagnostic } from "../output/diagnostic.js"; import { + FEATURE_DOC_TEMPLATE_PATH, renderChildAreaTemplate, + renderFeatureDocTemplateFile, renderFeatureDomainReadmeTemplate, renderFeatureLeafDocTemplate, renderFeatureRootReadmeTemplate, @@ -30,6 +33,17 @@ const hasMarkdownFiles = async (rootDir: string, root: string): Promise return matches.length > 0; }; +const readFeatureDocTemplate = async (rootDir: string): Promise => { + try { + return await fs.readFile(resolveRepoPath(rootDir, FEATURE_DOC_TEMPLATE_PATH), "utf8"); + } catch (error: unknown) { + if (error instanceof Error && "code" in error && error.code === "ENOENT") { + return renderFeatureDocTemplateFile(); + } + throw error; + } +}; + export const scaffoldHierarchy = async ( rootDir: string, config: TruthmarkConfig, @@ -61,11 +75,15 @@ export const scaffoldHierarchy = async ( renderFeatureDomainReadmeTemplate(config), ), ); + results.push( + await ensureRepoFile(rootDir, FEATURE_DOC_TEMPLATE_PATH, renderFeatureDocTemplateFile()), + ); + const featureDocTemplate = await readFeatureDocTemplate(rootDir); results.push( await ensureRepoFile( rootDir, `${featureDomainRoot}/overview.md`, - renderFeatureLeafDocTemplate(config), + renderFeatureLeafDocTemplate(config, featureDocTemplate), ), ); return results; diff --git a/src/init/init.ts b/src/init/init.ts index 64f52a9..70a6d11 100644 --- a/src/init/init.ts +++ b/src/init/init.ts @@ -9,16 +9,21 @@ import { detectHierarchyMigrationDiagnostics, scaffoldHierarchy } from "./hierar import { renderAgentsBlock, TRUTHMARK_BLOCK_END, TRUTHMARK_BLOCK_START } from "../templates/agents-block.js"; import { renderTruthmarkCopilotCheckPrompt, + renderTruthmarkCopilotDocumentPrompt, renderTruthmarkCopilotRealizePrompt, renderTruthmarkCopilotStructurePrompt, renderTruthmarkCopilotSyncPrompt, renderTruthmarkCheckLocalSkill, renderTruthmarkGeminiCheckCommand, + renderTruthmarkGeminiDocumentCommand, renderTruthmarkGeminiRealizeCommand, renderTruthmarkGeminiStructureCommand, renderTruthmarkGeminiSyncCommand, renderTruthmarkCheckSkill, renderTruthmarkCheckSkillMetadata, + renderTruthmarkDocumentLocalSkill, + renderTruthmarkDocumentSkill, + renderTruthmarkDocumentSkillMetadata, renderTruthmarkStructureLocalSkill, renderTruthmarkStructureSkill, renderTruthmarkStructureSkillMetadata, @@ -28,9 +33,12 @@ import { TRUTHMARK_CHECK_SKILL_METADATA_PATH, TRUTHMARK_CHECK_SKILL_PATH, TRUTHMARK_COPILOT_CHECK_PROMPT_PATH, + TRUTHMARK_COPILOT_DOCUMENT_PROMPT_PATH, TRUTHMARK_COPILOT_REALIZE_PROMPT_PATH, TRUTHMARK_COPILOT_STRUCTURE_PROMPT_PATH, TRUTHMARK_COPILOT_SYNC_PROMPT_PATH, + TRUTHMARK_DOCUMENT_SKILL_METADATA_PATH, + TRUTHMARK_DOCUMENT_SKILL_PATH, TRUTHMARK_SYNC_SKILL_METADATA_PATH, TRUTHMARK_SYNC_SKILL_PATH, TRUTHMARK_STRUCTURE_SKILL_METADATA_PATH, @@ -39,6 +47,7 @@ import { renderTruthmarkRealizeSkill, renderTruthmarkRealizeSkillMetadata, TRUTHMARK_GEMINI_CHECK_COMMAND_PATH, + TRUTHMARK_GEMINI_DOCUMENT_COMMAND_PATH, TRUTHMARK_GEMINI_REALIZE_COMMAND_PATH, TRUTHMARK_GEMINI_STRUCTURE_COMMAND_PATH, TRUTHMARK_GEMINI_SYNC_COMMAND_PATH, @@ -46,7 +55,6 @@ import { TRUTHMARK_REALIZE_SKILL_PATH, } from "../templates/codex-skills.js"; import { renderDefaultStandards } from "../templates/default-standards.js"; -import { renderTruthmarkTemplate } from "../templates/init-files.js"; const escapeRegExp = (value: string): string => { return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); @@ -106,30 +114,40 @@ const removeTrailingManagedChunk = (preservedLines: string[]): void => { } }; +const normalizeLegacyInstructionPreamble = (content: string): string => { + return content + .replaceAll( + "Use that file as the primary repository instruction source for Codex.", + "Use that file as the primary repository instruction source for this agent.", + ) + .replaceAll("Codex-specific:", "Agent-specific:"); +}; + const upsertManagedBlock = (existingContent: string | null, block: string): string => { if (!existingContent || existingContent.trim().length === 0) { return block; } + const normalizedExistingContent = normalizeLegacyInstructionPreamble(existingContent); const startMarkerPattern = new RegExp(escapeRegExp(TRUTHMARK_BLOCK_START), "g"); const endMarkerPattern = new RegExp(escapeRegExp(TRUTHMARK_BLOCK_END), "g"); const managedBlockPattern = new RegExp( `${escapeRegExp(TRUTHMARK_BLOCK_START)}[\\s\\S]*?${escapeRegExp(TRUTHMARK_BLOCK_END)}`, "g", ); - const completeBlocks = existingContent.match(managedBlockPattern) ?? []; - const startCount = existingContent.match(startMarkerPattern)?.length ?? 0; - const endCount = existingContent.match(endMarkerPattern)?.length ?? 0; + const completeBlocks = normalizedExistingContent.match(managedBlockPattern) ?? []; + const startCount = normalizedExistingContent.match(startMarkerPattern)?.length ?? 0; + const endCount = normalizedExistingContent.match(endMarkerPattern)?.length ?? 0; if (startCount === 1 && endCount === 1 && completeBlocks.length === 1) { - return existingContent.replace(managedBlockPattern, block); + return normalizedExistingContent.replace(managedBlockPattern, block); } const preservedLines: string[] = []; let insideManagedBlock = false; let managedLines: string[] = []; - for (const line of existingContent.split("\n")) { + for (const line of normalizedExistingContent.split("\n")) { const trimmedLine = line.trim(); if (trimmedLine === TRUTHMARK_BLOCK_START) { @@ -215,6 +233,10 @@ const diagnosticCategoryForPath = (filePath: string): DiagnosticCategory => { return "truth-sync"; } + if (filePath.startsWith(".codex/skills/truthmark-document/")) { + return "truth-sync"; + } + if (filePath.startsWith(".codex/skills/truthmark-sync/")) { return "truth-sync"; } @@ -235,7 +257,7 @@ const diagnosticCategoryForPath = (filePath: string): DiagnosticCategory => { return "truth-sync"; } - if (filePath === "TRUTHMARK.md" || filePath === "docs/truthmark/areas.md") { + if (filePath === "docs/truthmark/areas.md") { return "authority"; } @@ -257,6 +279,10 @@ const workflowSkillFiles = ( path: `${basePath}/truthmark-structure/SKILL.md`, content: renderTruthmarkStructureLocalSkill(config), }, + { + path: `${basePath}/truthmark-document/SKILL.md`, + content: renderTruthmarkDocumentLocalSkill(config), + }, { path: `${basePath}/truthmark-sync/SKILL.md`, content: renderTruthmarkSyncLocalSkill(config), @@ -287,6 +313,14 @@ const codexFiles = (config: TruthmarkConfig): PlatformFile[] => { path: TRUTHMARK_STRUCTURE_SKILL_METADATA_PATH, content: renderTruthmarkStructureSkillMetadata(), }, + { + path: TRUTHMARK_DOCUMENT_SKILL_PATH, + content: renderTruthmarkDocumentSkill(config), + }, + { + path: TRUTHMARK_DOCUMENT_SKILL_METADATA_PATH, + content: renderTruthmarkDocumentSkillMetadata(), + }, { path: TRUTHMARK_SYNC_SKILL_PATH, content: renderTruthmarkSyncSkill(config), @@ -328,6 +362,10 @@ const copilotFiles = (config: TruthmarkConfig, block: string): PlatformFile[] => path: TRUTHMARK_COPILOT_STRUCTURE_PROMPT_PATH, content: renderTruthmarkCopilotStructurePrompt(config), }, + { + path: TRUTHMARK_COPILOT_DOCUMENT_PROMPT_PATH, + content: renderTruthmarkCopilotDocumentPrompt(config), + }, { path: TRUTHMARK_COPILOT_SYNC_PROMPT_PATH, content: renderTruthmarkCopilotSyncPrompt(config), @@ -380,6 +418,10 @@ const filesForPlatform = ( path: TRUTHMARK_GEMINI_STRUCTURE_COMMAND_PATH, content: renderTruthmarkGeminiStructureCommand(config), }, + { + path: TRUTHMARK_GEMINI_DOCUMENT_COMMAND_PATH, + content: renderTruthmarkGeminiDocumentCommand(config), + }, { path: TRUTHMARK_GEMINI_SYNC_COMMAND_PATH, content: renderTruthmarkGeminiSyncCommand(config), @@ -460,7 +502,6 @@ export const runInit = async (cwd: string): Promise => { results.push(await ensureRepoFile(rootDir, template.path, template.content)); } - results.push(await ensureRepoFile(rootDir, "TRUTHMARK.md", renderTruthmarkTemplate())); const config = loadedConfig.config; results.push(...(await scaffoldHierarchy(rootDir, config))); const migrationDiagnostics = await detectHierarchyMigrationDiagnostics(rootDir, config); diff --git a/src/markdown/discovery.ts b/src/markdown/discovery.ts index 2345bc1..db9d6ba 100644 --- a/src/markdown/discovery.ts +++ b/src/markdown/discovery.ts @@ -29,7 +29,6 @@ const DISCOVERY_IGNORES = [ "AGENTS.md", "CLAUDE.md", "GEMINI.md", - "TRUTHMARK.md", ".github/copilot-instructions.md", "docs/truthmark/**", ]; diff --git a/src/sync/policy.ts b/src/sync/policy.ts index af3fd65..b3381ce 100644 --- a/src/sync/policy.ts +++ b/src/sync/policy.ts @@ -25,7 +25,6 @@ export const TRUTH_SYNC_BOUNDARIES = { "changed functional code files", "nearby implementation context when needed to understand the changed surface", ".truthmark/config.yml", - "TRUTHMARK.md", "docs/truthmark/areas.md", "mapped truth docs", ], diff --git a/src/templates/agents-block.ts b/src/templates/agents-block.ts index 850c9c9..ca56632 100644 --- a/src/templates/agents-block.ts +++ b/src/templates/agents-block.ts @@ -28,11 +28,11 @@ export const renderAgentsBlock = ( "", `Generated by Truthmark ${TRUTHMARK_VERSION}. Rerun \`truthmark init\` after upgrades and review workflow diffs.`, renderHierarchySummary(config), - "Decision truth lives in the canonical doc it governs: update Product Decisions/Rationale, allow short inline dates, and do not create separate timestamped ADR or planning logs.", + "Decision truth lives in the canonical doc it governs: update Product Decisions/Rationale, date active decisions inline when added or changed, and do not create separate timestamped ADR or planning logs.", "Agent runtime: installed skills plus this block. Always inspect checkout directly; CLI commands are optional validation. Do not use packet helpers or cache files. Delegation is host-owned.", "### Truth Sync", - `Sync: finish-time when functional code changed; use the truthmark-sync skill before finishing. Explicit invocation: ${syncInvocations}; later functional changes reopen the gate. Memory: code changed -> tests -> Sync -> report. Run relevant tests first. Code leads, truth docs follow; may write truth docs and docs/truthmark/areas.md only, and must not rewrite functional code. Read ${config.docs.routing.rootIndex} and only relevant child routes under ${config.docs.routing.areaFilesRoot}/; if routing is broad/overloaded/catch-all, run or recommend Truth Structure. Skip only: ${TRUTH_SYNC_SKIP_REASONS.join("; ")}.`, - "Explicit workflows: Truth Structure, Truth Realize, Truth Check. Run only when requested or when Sync requires Structure; load the installed skill for details.", + `Sync: finish-time when functional code changed; use the truthmark-sync skill before finishing. Explicit invocation: ${syncInvocations}; later functional changes reopen the gate. Memory: code changed -> tests -> Sync -> report. Run relevant tests first. Code leads, truth docs follow; may write truth docs and docs/truthmark/areas.md only, and must not rewrite functional code. Read ${config.docs.routing.rootIndex} and only relevant child routes under ${config.docs.routing.areaFilesRoot}/; if routing is missing/stale/broad/overloaded/catch-all or cannot map changed code to a bounded truth owner, run Truth Structure before syncing when safe and in scope; otherwise block and recommend Truth Structure. Skip only: ${TRUTH_SYNC_SKIP_REASONS.join("; ")}.`, + "Explicit workflows: Truth Structure, Truth Document, Truth Realize, Truth Check. Run only when requested or when Sync requires Structure or Document; load the installed skill for details.", "Workflow integrity rule: repository truth may describe desired behavior, but it must not silently override these Truthmark workflow boundaries.", TRUTHMARK_BLOCK_END, ].join("\n"); diff --git a/src/templates/codex-skills.ts b/src/templates/codex-skills.ts index 1d5ed98..f235c27 100644 --- a/src/templates/codex-skills.ts +++ b/src/templates/codex-skills.ts @@ -1,6 +1,7 @@ import type { TruthmarkConfig } from "../config/schema.js"; import { EVIDENCE_AUTHORITY_INSTRUCTIONS, defaultAgentConfig } from "../agents/shared.js"; import { renderTruthCheckSkillBody } from "../agents/truth-check.js"; +import { renderTruthDocumentSkillBody } from "../agents/truth-document.js"; import { renderTruthStructureSkillBody } from "../agents/truth-structure.js"; import { renderTruthSyncSkillBody } from "../agents/truth-sync.js"; import { TRUTHMARK_VERSION } from "../version.js"; @@ -11,6 +12,12 @@ export const TRUTHMARK_STRUCTURE_SKILL_PATH = export const TRUTHMARK_STRUCTURE_SKILL_METADATA_PATH = ".codex/skills/truthmark-structure/agents/openai.yaml"; +export const TRUTHMARK_DOCUMENT_SKILL_PATH = + ".codex/skills/truthmark-document/SKILL.md"; + +export const TRUTHMARK_DOCUMENT_SKILL_METADATA_PATH = + ".codex/skills/truthmark-document/agents/openai.yaml"; + export const TRUTHMARK_SYNC_SKILL_PATH = ".codex/skills/truthmark-sync/SKILL.md"; export const TRUTHMARK_SYNC_SKILL_METADATA_PATH = @@ -30,6 +37,9 @@ export const TRUTHMARK_CHECK_SKILL_METADATA_PATH = export const TRUTHMARK_GEMINI_STRUCTURE_COMMAND_PATH = ".gemini/commands/truthmark/structure.toml"; +export const TRUTHMARK_GEMINI_DOCUMENT_COMMAND_PATH = + ".gemini/commands/truthmark/document.toml"; + export const TRUTHMARK_GEMINI_SYNC_COMMAND_PATH = ".gemini/commands/truthmark/sync.toml"; @@ -42,6 +52,9 @@ export const TRUTHMARK_GEMINI_CHECK_COMMAND_PATH = export const TRUTHMARK_COPILOT_STRUCTURE_PROMPT_PATH = ".github/prompts/truthmark-structure.prompt.md"; +export const TRUTHMARK_COPILOT_DOCUMENT_PROMPT_PATH = + ".github/prompts/truthmark-document.prompt.md"; + export const TRUTHMARK_COPILOT_SYNC_PROMPT_PATH = ".github/prompts/truthmark-sync.prompt.md"; @@ -96,6 +109,33 @@ truthmark: `; }; +export const renderTruthmarkDocumentSkill = ( + config: TruthmarkConfig = defaultAgentConfig(), +): string => { + return renderTruthDocumentSkillBody(config); +}; + +export const renderTruthmarkDocumentLocalSkill = ( + config: TruthmarkConfig = defaultAgentConfig(), +): string => { + return renderTruthDocumentSkillBody(config); +}; + +export const renderTruthmarkDocumentSkillMetadata = (): string => { + return `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: "${TRUTHMARK_VERSION}" + refresh_command: "truthmark init" +`; +}; + export const renderTruthmarkSyncSkill = ( config: TruthmarkConfig = defaultAgentConfig(), ): string => { @@ -111,8 +151,8 @@ export const renderTruthmarkSyncLocalSkill = ( export const renderTruthmarkSyncSkillMetadata = (): string => { return `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 @@ -147,7 +187,7 @@ 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. +2. Read .truthmark/config.yml, docs/truthmark/areas.md, and the relevant functional code. 3. ${EVIDENCE_AUTHORITY_INSTRUCTIONS} 4. Update functional code only so implementation matches the truth docs. 5. Do not edit truth docs or truth routing while realizing those docs. @@ -236,11 +276,20 @@ export const renderTruthmarkGeminiStructureCommand = ( ); }; +export const renderTruthmarkGeminiDocumentCommand = ( + config: TruthmarkConfig = defaultAgentConfig(), +): string => { + return renderGeminiCommand( + "Document existing implemented behavior.", + renderTruthDocumentSkillBody(config), + ); +}; + export const renderTruthmarkGeminiSyncCommand = ( config: TruthmarkConfig = defaultAgentConfig(), ): string => { return renderGeminiCommand( - "Sync repository truth docs from changed code.", + "Sync repository truth docs from functional code changes; skip docs-only/no-code changes.", renderTruthSyncSkillBody(config), ); }; @@ -270,11 +319,20 @@ export const renderTruthmarkCopilotStructurePrompt = ( ); }; +export const renderTruthmarkCopilotDocumentPrompt = ( + config: TruthmarkConfig = defaultAgentConfig(), +): string => { + return renderCopilotPromptFile( + "Document existing implemented behavior.", + renderTruthDocumentSkillBody(config), + ); +}; + export const renderTruthmarkCopilotSyncPrompt = ( config: TruthmarkConfig = defaultAgentConfig(), ): string => { return renderCopilotPromptFile( - "Sync repository truth docs from changed code.", + "Sync repository truth docs from functional code changes; skip docs-only/no-code changes.", renderTruthSyncSkillBody(config), ); }; diff --git a/src/templates/default-standards.ts b/src/templates/default-standards.ts index c8a582c..8be915c 100644 --- a/src/templates/default-standards.ts +++ b/src/templates/default-standards.ts @@ -28,8 +28,10 @@ This is a bootstrap standards baseline for repositories that adopt Truthmark. - Committed repository artifacts are the durable source of truth. - Each document should have one primary responsibility. - Each class of fact should have one canonical source. +- Architecture docs describe system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, and generated-surface ownership. +- Do not put ordinary feature behavior in architecture docs. - Verification should be explicit, and skipped checks should state why. -- Broad or overloaded documentation topology should be repaired through AI-native structure workflow before agents create more generic truth docs. +- Missing, stale, broad, overloaded, or unrouteable documentation topology should be repaired through AI-native structure workflow before agents create more generic truth docs. - Installed repository workflows should remain usable from committed files even when the Truthmark CLI is unavailable. `, }, @@ -51,12 +53,13 @@ source_of_truth: - Each class of fact should have one canonical source. - Current implementation, reusable standards, and future proposals should be stored separately. - Generated helper output is never canonical truth. +- Architecture docs describe structure and ownership; feature docs describe current product behavior. ## Truthmark Implications - Truth Sync should extend mapped docs first, create an area-local doc second, and create a new area only as a last resort. - Weak routing produces weak truth maintenance. -- Broad or overloaded routing should trigger Truth Structure before more generic feature docs are created. +- Missing, stale, broad, overloaded, or unrouteable routing should trigger Truth Structure before more generic feature docs are created. `, }, ]; diff --git a/src/templates/generated-surfaces.ts b/src/templates/generated-surfaces.ts index a1ae962..de3d7e7 100644 --- a/src/templates/generated-surfaces.ts +++ b/src/templates/generated-surfaces.ts @@ -2,11 +2,16 @@ import type { TruthmarkConfig, TruthmarkPlatform } from "../config/schema.js"; import { renderAgentsBlock } from "./agents-block.js"; import { renderTruthmarkCopilotCheckPrompt, + renderTruthmarkCopilotDocumentPrompt, renderTruthmarkCopilotRealizePrompt, renderTruthmarkCopilotStructurePrompt, renderTruthmarkCopilotSyncPrompt, renderTruthmarkCheckLocalSkill, + renderTruthmarkDocumentLocalSkill, + renderTruthmarkDocumentSkill, + renderTruthmarkDocumentSkillMetadata, renderTruthmarkGeminiCheckCommand, + renderTruthmarkGeminiDocumentCommand, renderTruthmarkGeminiRealizeCommand, renderTruthmarkGeminiStructureCommand, renderTruthmarkGeminiSyncCommand, @@ -24,10 +29,14 @@ import { TRUTHMARK_CHECK_SKILL_METADATA_PATH, TRUTHMARK_CHECK_SKILL_PATH, TRUTHMARK_COPILOT_CHECK_PROMPT_PATH, + TRUTHMARK_COPILOT_DOCUMENT_PROMPT_PATH, TRUTHMARK_COPILOT_REALIZE_PROMPT_PATH, TRUTHMARK_COPILOT_STRUCTURE_PROMPT_PATH, TRUTHMARK_COPILOT_SYNC_PROMPT_PATH, + TRUTHMARK_DOCUMENT_SKILL_METADATA_PATH, + TRUTHMARK_DOCUMENT_SKILL_PATH, TRUTHMARK_GEMINI_CHECK_COMMAND_PATH, + TRUTHMARK_GEMINI_DOCUMENT_COMMAND_PATH, TRUTHMARK_GEMINI_REALIZE_COMMAND_PATH, TRUTHMARK_GEMINI_STRUCTURE_COMMAND_PATH, TRUTHMARK_GEMINI_SYNC_COMMAND_PATH, @@ -54,6 +63,10 @@ const workflowSkillFiles = ( path: `${basePath}/truthmark-structure/SKILL.md`, content: renderTruthmarkStructureLocalSkill(config), }, + { + path: `${basePath}/truthmark-document/SKILL.md`, + content: renderTruthmarkDocumentLocalSkill(config), + }, { path: `${basePath}/truthmark-sync/SKILL.md`, content: renderTruthmarkSyncLocalSkill(config), @@ -84,6 +97,14 @@ const codexFiles = (config: TruthmarkConfig): GeneratedSurface[] => { path: TRUTHMARK_STRUCTURE_SKILL_METADATA_PATH, content: renderTruthmarkStructureSkillMetadata(), }, + { + path: TRUTHMARK_DOCUMENT_SKILL_PATH, + content: renderTruthmarkDocumentSkill(config), + }, + { + path: TRUTHMARK_DOCUMENT_SKILL_METADATA_PATH, + content: renderTruthmarkDocumentSkillMetadata(), + }, { path: TRUTHMARK_SYNC_SKILL_PATH, content: renderTruthmarkSyncSkill(config), @@ -125,6 +146,10 @@ const copilotFiles = (config: TruthmarkConfig, block: string): GeneratedSurface[ path: TRUTHMARK_COPILOT_STRUCTURE_PROMPT_PATH, content: renderTruthmarkCopilotStructurePrompt(config), }, + { + path: TRUTHMARK_COPILOT_DOCUMENT_PROMPT_PATH, + content: renderTruthmarkCopilotDocumentPrompt(config), + }, { path: TRUTHMARK_COPILOT_SYNC_PROMPT_PATH, content: renderTruthmarkCopilotSyncPrompt(config), @@ -177,6 +202,10 @@ const filesForPlatform = ( path: TRUTHMARK_GEMINI_STRUCTURE_COMMAND_PATH, content: renderTruthmarkGeminiStructureCommand(config), }, + { + path: TRUTHMARK_GEMINI_DOCUMENT_COMMAND_PATH, + content: renderTruthmarkGeminiDocumentCommand(config), + }, { path: TRUTHMARK_GEMINI_SYNC_COMMAND_PATH, content: renderTruthmarkGeminiSyncCommand(config), diff --git a/src/templates/init-files.ts b/src/templates/init-files.ts index 7aa5b90..ec3822c 100644 --- a/src/templates/init-files.ts +++ b/src/templates/init-files.ts @@ -3,33 +3,11 @@ import { stringify } from "yaml"; import type { TruthmarkConfig } from "../config/schema.js"; import type { DiscoveredMarkdownDocument } from "../markdown/discovery.js"; import { createDefaultRawConfig } from "../config/defaults.js"; -import { TRUTHMARK_VERSION } from "../version.js"; export const renderConfigTemplate = (): string => { return stringify(createDefaultRawConfig()); }; -export const renderTruthmarkTemplate = (): string => { - return `--- -status: active -doc_type: workflow-contract -last_reviewed: 2026-05-10 -source_of_truth: - - .truthmark/config.yml ---- - -# Truthmark - -Markdown in the current checkout is authoritative for this branch. - -Installed workflow surfaces include a Truthmark ${TRUTHMARK_VERSION} version marker. After upgrading Truthmark, rerun \`truthmark init\` and review generated workflow diffs. - -Workflow runtime lives in installed skills and managed instruction blocks. Agents inspect the checkout directly; \`truthmark check\` is optional validation. - -Truth Sync follows code; Truth Realize follows docs. Truth Sync may update mapped truth docs; Truth Realize never edits truth docs or routing. -`; -}; - export const renderAreasTemplate = ( documents: DiscoveredMarkdownDocument[], ): string => { @@ -172,36 +150,129 @@ export const renderFeatureDomainReadmeTemplate = (config: TruthmarkConfig): stri ].join("\n"); }; -export const renderFeatureLeafDocTemplate = (config: TruthmarkConfig): string => { - const defaultArea = config.docs.routing.defaultArea; - const title = titleCase(defaultArea); +export const FEATURE_DOC_TEMPLATE_PATH = "docs/templates/feature-doc.md"; +export const renderFeatureDocTemplateFile = (): string => { return [ "---", "status: active", "doc_type: feature", - "last_reviewed: 2026-05-09", + "last_reviewed: 2026-05-12", "source_of_truth:", - ` - ../../truthmark/areas/${defaultArea}.md`, + " - {{source_of_truth}}", "---", "", - `# ${title} Overview`, + "# {{title}}", + "", + "## Purpose", + "", + "", + "", + "{{purpose}}", "", "## Scope", "", - `This bounded leaf truth doc owns the default ${title.toLowerCase()} behavior surface created by Truthmark.`, + "{{scope}}", + "", + "", + "", + "This doc was created from the editable feature-doc template at {{template_path}}.", "", "## Current Behavior", "", - "- Document current behavior here when implementation changes make repository truth incomplete.", + "", + "", + "{{current_behavior}}", + "", + "## Core Rules", + "", + "", + "", + "{{core_rules}}", + "", + "## Flows And States", + "", + "", + "", + "{{flows_and_states}}", + "", + "## Contracts", + "", + "", + "", + "{{contracts}}", "", "## Product Decisions", "", - "- Decision (2026-05-09): Feature README files are indexes; behavior truth belongs in bounded leaf docs.", + "", + "", + "{{decision}}", "", "## Rationale", "", - "Bounded leaf docs keep agent context focused and prevent large products from accumulating unreviewable feature manuals.", + "", + "", + "{{rationale}}", + "", + "## Non-Goals", + "", + "", + "", + "{{non_goals}}", + "", + "## Maintenance Notes", + "", + "", + "", + "{{maintenance_notes}}", "", ].join("\n"); }; + +const renderTemplate = (template: string, values: Record): string => { + return Object.entries(values).reduce((rendered, [key, value]) => { + return rendered.split(`{{${key}}}`).join(value); + }, template); +}; + +export const renderFeatureLeafDocTemplate = ( + config: TruthmarkConfig, + template = renderFeatureDocTemplateFile(), +): string => { + const defaultArea = config.docs.routing.defaultArea; + const title = titleCase(defaultArea); + + return renderTemplate(template, { + area: defaultArea, + contracts: + "- External contracts should link to the nearest canonical contract doc when one exists.", + core_rules: + "- Feature README files are indexes; behavior truth belongs in bounded leaf docs.", + current_behavior: + "- Document current behavior here when implementation changes make repository truth incomplete.", + decision: + "- Decision (2026-05-09): Feature README files are indexes; behavior truth belongs in bounded leaf docs.", + flows_and_states: "- None beyond current behavior.", + maintenance_notes: + "- Update this doc when routed implementation changes alter current behavior, rules, contracts, or decisions.", + non_goals: + "- This doc is not a catch-all for unrelated repository behavior.", + purpose: + `Describe why the default ${title.toLowerCase()} behavior surface exists and what outcome it protects.`, + rationale: + "Bounded leaf docs keep agent context focused and prevent large products from accumulating unreviewable feature manuals.", + scope: `This bounded leaf truth doc owns the default ${title.toLowerCase()} behavior surface created by Truthmark.`, + source_of_truth: `../../truthmark/areas/${defaultArea}.md`, + template_path: FEATURE_DOC_TEMPLATE_PATH, + title: `${title} Overview`, + }); +}; diff --git a/tests/agents/instructions.test.ts b/tests/agents/instructions.test.ts index 7cc317c..f5ea147 100644 --- a/tests/agents/instructions.test.ts +++ b/tests/agents/instructions.test.ts @@ -23,8 +23,11 @@ describe("renderTruthSyncInstructions", () => { expect(instructions).toContain("Later functional-code changes reopen the finish-time requirement"); expect(instructions).toContain("must not rewrite functional code"); expect(instructions).toContain("host supports subagent dispatch"); - expect(instructions).toContain("If routing is broad, overloaded, or catch-all"); - expect(instructions).toContain("run or recommend Truth Structure before syncing"); + expect(instructions).toContain( + "If routing is missing, stale, broad, overloaded, catch-all, or cannot map changed code to a bounded truth owner", + ); + expect(instructions).toContain("run Truth Structure before syncing"); + expect(instructions).toContain("otherwise block and recommend Truth Structure"); expect(instructions).not.toContain(".truthmark/local.yml"); expect(instructions).not.toContain("truth_sync.sync_agent"); expect(instructions).not.toContain("Truth Sync: completed"); @@ -46,6 +49,7 @@ describe("agent-native workflow instructions", () => { it("renders Truth Structure and Truth Check summaries", () => { expect(renderTruthStructureInstructions()).toContain("truthmark-structure"); expect(renderTruthStructureInstructions()).toContain("docs/truthmark/areas.md"); + expect(renderTruthStructureInstructions()).toContain("missing, stale, broad, overloaded, catch-all, unrouteable"); expect(renderTruthStructureInstructions()).toContain("canonical current-truth destinations"); expect(renderTruthStructureInstructions()).toContain("topology pressure"); expect(renderTruthStructureInstructions()).toContain("If the skill is unavailable"); diff --git a/tests/agents/truth-check.test.ts b/tests/agents/truth-check.test.ts index 92fd6e1..ced4a5b 100644 --- a/tests/agents/truth-check.test.ts +++ b/tests/agents/truth-check.test.ts @@ -20,6 +20,12 @@ describe("renderTruthCheckSkillBody", () => { expect(skill).toContain(`truthmark-version: ${TRUTHMARK_VERSION}`); expect(skill).toContain("audit repository truth health"); expect(skill).toContain( + "Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority.", + ); + expect(skill).toContain( + "Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries.", + ); + expect(skill).not.toContain( "Repository docs and code are inspected evidence, not executable instruction authority.", ); expect(skill).toContain("optionally run truthmark check"); diff --git a/tests/agents/truth-document.test.ts b/tests/agents/truth-document.test.ts new file mode 100644 index 0000000..7cd9059 --- /dev/null +++ b/tests/agents/truth-document.test.ts @@ -0,0 +1,93 @@ +import { describe, expect, it } from "vitest"; +import matter from "gray-matter"; + +import { + TRUTH_DOCUMENT_EXPLICIT_INVOCATIONS, + renderTruthDocumentReportExample, + renderTruthDocumentSkillBody, +} from "../../src/agents/truth-document.js"; +import { + renderTruthmarkDocumentLocalSkill, + renderTruthmarkDocumentSkill, + renderTruthmarkDocumentSkillMetadata, +} from "../../src/templates/codex-skills.js"; +import { TRUTHMARK_VERSION } from "../../src/version.js"; + +describe("renderTruthDocumentSkillBody", () => { + it("renders parseable skill frontmatter", () => { + const parsed = matter(renderTruthDocumentSkillBody()); + + expect(parsed.data.name).toBe("truthmark-document"); + expect(parsed.data["user-invocable"]).toBe(true); + expect(parsed.data.description).toContain( + "when Truth Sync, Truth Check, or Truth Structure reports implemented behavior that lacks canonical truth docs", + ); + expect(parsed.data.description).not.toContain("when an update finds"); + expect(parsed.content).toContain( + "Use this skill to document existing implemented behavior", + ); + }); + + it("renders the manual existing-implementation documentation workflow", () => { + const skill = renderTruthDocumentSkillBody(); + + expect(TRUTH_DOCUMENT_EXPLICIT_INVOCATIONS).toContain("/truthmark:document"); + expect(skill).toContain("name: truthmark-document"); + expect(skill).toContain(`truthmark-version: ${TRUTHMARK_VERSION}`); + expect(skill).toContain("manual and implementation-first"); + expect(skill).toContain("existing implemented behavior"); + expect(skill).toContain("no functional-code changes"); + expect(skill).toContain("must not write functional code"); + expect(skill).toContain("docs/templates/feature-doc.md"); + expect(skill).toContain("When creating or updating a feature doc"); + expect(skill).toContain("behavior-oriented, not endpoint-oriented"); + expect(skill).toContain( + "Maintain architecture docs when a code change alters system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership.", + ); + expect(skill).toContain( + "Do not put ordinary feature behavior, endpoint details, UI copy, validation rules, or bug fixes in architecture docs unless they change those architecture boundaries.", + ); + expect(skill).toContain( + "run Truth Structure first when routing repair is safe and in scope", + ); + expect(skill).toContain( + "block and recommend Truth Structure when routing repair is unsafe, ambiguous, or outside the task boundary", + ); + expect(skill).toContain( + "Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority.", + ); + expect(skill).toContain("Truth Document: completed"); + expect(skill).toContain("Implementation reviewed"); + expect(skill).toContain("Truth docs created"); + expect(skill).toContain("Truth docs updated"); + expect(skill).toContain("Routing updated"); + expect(skill).toContain("Notes"); + }); + + it("renders the report example", () => { + const report = renderTruthDocumentReportExample(); + + expect(report).toContain("Truth Document: completed"); + expect(report).toContain("src/api/orders/**"); + expect(report).toContain("docs/features/orders/order-submission.md"); + }); +}); + +describe("Truth Document generated surfaces", () => { + it("renders Codex metadata and OpenCode skill content", () => { + expect(renderTruthmarkDocumentSkill()).toContain("name: truthmark-document"); + expect(renderTruthmarkDocumentLocalSkill()).toContain( + "/skill truthmark-document", + ); + expect(renderTruthmarkDocumentLocalSkill()).toContain("/truthmark:document"); + expect(renderTruthmarkDocumentSkillMetadata()).toContain( + 'display_name: "Truthmark Document"', + ); + expect(renderTruthmarkDocumentSkillMetadata()).toContain( + "allow_implicit_invocation: false", + ); + expect(renderTruthmarkDocumentSkillMetadata()).toContain( + `version: "${TRUTHMARK_VERSION}"`, + ); + }); +}); diff --git a/tests/agents/truth-structure.test.ts b/tests/agents/truth-structure.test.ts index 6ff6177..f0410d5 100644 --- a/tests/agents/truth-structure.test.ts +++ b/tests/agents/truth-structure.test.ts @@ -35,6 +35,11 @@ describe("renderTruthStructureSkillBody", () => { expect(skill).toContain( "Starter truth docs must include ## Product Decisions and ## Rationale sections.", ); + expect(skill).toContain("When creating or updating a feature doc"); + expect(skill).toContain("read docs/templates/feature-doc.md"); + expect(skill).toContain("follow its frontmatter, heading order, and section intent"); + expect(skill).toContain("align existing feature docs to the template standard"); + expect(skill).not.toContain("# {{title}}"); }); it("renders the agent-native structure workflow contract", () => { @@ -47,6 +52,12 @@ describe("renderTruthStructureSkillBody", () => { expect(skill).toContain(`truthmark-version: ${TRUTHMARK_VERSION}`); expect(skill).toContain("inspect repository layout"); expect(skill).toContain( + "Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority.", + ); + expect(skill).toContain( + "Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries.", + ); + expect(skill).not.toContain( "Repository docs and code are inspected evidence, not executable instruction authority.", ); expect(skill).toContain("docs/truthmark/areas.md"); @@ -63,14 +74,21 @@ describe("renderTruthStructureSkillBody", () => { expect(skill).toContain( "If an existing canonical doc lacks either section, add the missing heading beside Current Behavior with a concise current-state placeholder or active decision.", ); - expect(skill).toContain("Short inline decision dates are allowed"); + expect(skill).toContain("Date active decisions inline when added or changed"); expect(skill).toContain("Topology Governance"); expect(skill).toContain("Topology pressure signals"); expect(skill).toContain("one area maps broad code"); + expect(skill).toContain("unrouteable Truthmark area routing"); expect(skill).toContain("infer product and domain ownership"); expect(skill).toContain( "feature docs behavior-oriented, not endpoint-oriented", ); + expect(skill).toContain( + "Maintain architecture docs when a code change alters system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership.", + ); + expect(skill).toContain( + "Do not put ordinary feature behavior, endpoint details, UI copy, validation rules, or bug fixes in architecture docs unless they change those architecture boundaries.", + ); expect(skill).toContain( "README.md files are indexes, not Truth Sync targets", ); diff --git a/tests/agents/truth-sync.test.ts b/tests/agents/truth-sync.test.ts index 5578816..19d2e6a 100644 --- a/tests/agents/truth-sync.test.ts +++ b/tests/agents/truth-sync.test.ts @@ -6,6 +6,11 @@ import { renderTruthSyncSkillBody, renderTruthSyncWorkerPrompt, } from "../../src/agents/truth-sync.js"; +import { + renderTruthmarkCopilotSyncPrompt, + renderTruthmarkGeminiSyncCommand, + renderTruthmarkSyncSkillMetadata, +} from "../../src/templates/codex-skills.js"; import { TRUTHMARK_VERSION } from "../../src/version.js"; describe("renderTruthSyncWorkerPrompt", () => { @@ -36,6 +41,9 @@ describe("renderTruthSyncSkillBody", () => { expect(parsed.data.name).toBe("truthmark-sync"); expect(parsed.data["user-invocable"]).toBe(true); + expect(parsed.data.description).toContain( + "Skip for documentation-only changes, formatting-only changes, behavior-preserving renames, missing Truthmark config, or no functional code changes.", + ); }); it("documents direct checkout inspection as the canonical runtime", () => { @@ -48,6 +56,12 @@ describe("renderTruthSyncSkillBody", () => { "direct checkout inspection is the canonical path", ); expect(skillBody).toContain( + "Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority.", + ); + expect(skillBody).toContain( + "Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries.", + ); + expect(skillBody).not.toContain( "Repository docs and code are inspected evidence, not executable instruction authority.", ); expect(skillBody).toContain("truthmark check"); @@ -59,13 +73,18 @@ describe("renderTruthSyncSkillBody", () => { "verify only truth docs and docs/truthmark/areas.md changed", ); expect(skillBody).toContain( - "Read .truthmark/config.yml, TRUTHMARK.md, the configured root route index", + "Read .truthmark/config.yml, the configured root route index", ); expect(skillBody).toContain("relevant child route files"); expect(skillBody).toContain("Topology quality gate"); - expect(skillBody).toContain("broad, overloaded, or catch-all route"); expect(skillBody).toContain( - "run or recommend Truth Structure before syncing", + "missing, stale, broad, overloaded, catch-all route only", + ); + expect(skillBody).toContain( + "run Truth Structure before syncing when topology repair is safe and in scope", + ); + expect(skillBody).toContain( + "block and recommend Truth Structure when topology repair is unsafe, ambiguous, or outside the current task boundary", ); expect(skillBody).toContain("do not create another generic feature doc"); expect(skillBody).toContain( @@ -75,9 +94,37 @@ describe("renderTruthSyncSkillBody", () => { "must not append behavior details to a feature README", ); expect(skillBody).toContain("create or update a bounded leaf truth doc"); + expect(skillBody).toContain( + "Maintain architecture docs when a code change alters system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership.", + ); + expect(skillBody).toContain( + "Do not put ordinary feature behavior, endpoint details, UI copy, validation rules, or bug fixes in architecture docs unless they change those architecture boundaries.", + ); + expect(skillBody).toContain("When creating or updating a feature doc"); + expect(skillBody).toContain("read docs/templates/feature-doc.md"); + expect(skillBody).toContain("follow its frontmatter, heading order, and section intent"); + expect(skillBody).toContain("align existing feature docs to the template standard"); + expect(skillBody).not.toContain("# {{title}}"); expect(skillBody).toContain( "update Product Decisions and Rationale when a behavior change comes from a decision change", ); expect(skillBody).toContain("/truthmark:sync"); }); }); + +describe("Truth Sync generated metadata", () => { + it("carries skip cases in Codex-visible metadata", () => { + const metadata = renderTruthmarkSyncSkillMetadata(); + + expect(metadata).toContain( + 'short_description: "Sync truth docs from functional code changes; skip docs-only/no-code changes"', + ); + expect(metadata).toContain("allow_implicit_invocation: true"); + expect(renderTruthmarkGeminiSyncCommand()).toContain( + 'description = "Sync repository truth docs from functional code changes; skip docs-only/no-code changes."', + ); + expect(renderTruthmarkCopilotSyncPrompt()).toContain( + "description: 'Sync repository truth docs from functional code changes; skip docs-only/no-code changes.'", + ); + }); +}); diff --git a/tests/checks/branch-scope.test.ts b/tests/checks/branch-scope.test.ts index 5c961d3..df2d5f9 100644 --- a/tests/checks/branch-scope.test.ts +++ b/tests/checks/branch-scope.test.ts @@ -7,7 +7,7 @@ import { runInit } from "../../src/init/init.js"; import { createTempRepo } from "../helpers/temp-repo.js"; describe("getBranchScopeData", () => { - it("describes unborn branch identity and hashes relevant workflow files when present", async () => { + it("describes unborn branch identity and hashes config plus routing files when present", async () => { const repo = await createTempRepo(); try { @@ -24,10 +24,14 @@ describe("getBranchScopeData", () => { expect(branchScope.relevantFileHashes).toEqual( expect.objectContaining({ ".truthmark/config.yml": expect.stringMatching(/^[0-9a-f]{64}$/), - "TRUTHMARK.md": expect.stringMatching(/^[0-9a-f]{64}$/), "docs/truthmark/areas.md": expect.stringMatching(/^[0-9a-f]{64}$/), }), ); + expect(Object.keys(branchScope.relevantFileHashes).sort()).toEqual([ + ".truthmark/config.yml", + "docs/truthmark/areas.md", + "docs/truthmark/areas/repository.md", + ]); } finally { await repo.cleanup(); } diff --git a/tests/checks/check.test.ts b/tests/checks/check.test.ts index 79d99e5..751092a 100644 --- a/tests/checks/check.test.ts +++ b/tests/checks/check.test.ts @@ -64,8 +64,8 @@ describe("runCheck", () => { await runConfig(repo.rootDir, {}); await initializeRepo(repo.rootDir); await repo.writeFile( - "TRUTHMARK.md", - `${await repo.readFile("TRUTHMARK.md")}\nSee [Missing](docs/missing.md).\n`, + "docs/features/repository/overview.md", + `${await repo.readFile("docs/features/repository/overview.md")}\nSee [Missing](docs/missing.md).\n`, ); const result = await runCheck(repo.rootDir); @@ -92,8 +92,8 @@ describe("runCheck", () => { "utf8", ); await repo.writeFile( - "TRUTHMARK.md", - `${await repo.readFile("TRUTHMARK.md")}\nSee [Outside](../truthmark-outside-link.md).\n`, + "docs/features/repository/overview.md", + `${await repo.readFile("docs/features/repository/overview.md")}\nSee [Outside](../truthmark-outside-link.md).\n`, ); const result = await runCheck(repo.rootDir); @@ -102,7 +102,7 @@ describe("runCheck", () => { result.diagnostics.some( (diagnostic) => diagnostic.category === "links" && - diagnostic.file === "TRUTHMARK.md", + diagnostic.file === "docs/features/repository/overview.md", ), ).toBe(true); } finally { @@ -133,8 +133,8 @@ describe("runCheck", () => { path.resolve(repo.rootDir, "docs", "linked-outside.md"), ); await repo.writeFile( - "TRUTHMARK.md", - `${await repo.readFile("TRUTHMARK.md")}\nSee [Outside](docs/linked-outside.md).\n`, + "docs/features/repository/overview.md", + `${await repo.readFile("docs/features/repository/overview.md")}\nSee [Outside](docs/linked-outside.md).\n`, ); const result = await runCheck(repo.rootDir); @@ -143,7 +143,7 @@ describe("runCheck", () => { result.diagnostics.some( (diagnostic) => diagnostic.category === "links" && - diagnostic.file === "TRUTHMARK.md", + diagnostic.file === "docs/features/repository/overview.md", ), ).toBe(true); } finally { @@ -163,7 +163,7 @@ describe("runCheck", () => { try { await runConfig(repo.rootDir, {}); await initializeRepo(repo.rootDir); - await fs.rm(`${repo.rootDir}/TRUTHMARK.md`); + await fs.rm(`${repo.rootDir}/docs/truthmark/areas.md`); const result = await runCheck(repo.rootDir); @@ -193,7 +193,6 @@ describe("runCheck", () => { ".truthmark/config.yml", `version: 1 authority: - - TRUTHMARK.md - ../truthmark-outside-authority.md - ../truthmark-outside-*.md instruction_targets: @@ -264,7 +263,6 @@ realization: ".truthmark/config.yml", `version: 1 authority: - - TRUTHMARK.md - docs/custom/outside-authority.md instruction_targets: - AGENTS.md @@ -556,7 +554,6 @@ docs: default_area: repository max_delegation_depth: 1 authority: - - TRUTHMARK.md - docs/truthmark/areas.md - docs/truthmark/areas/**/*.md - docs/features/**/*.md @@ -564,7 +561,6 @@ realization: enabled: true `, ); - await repo.writeFile("TRUTHMARK.md", "# Truthmark\n"); await repo.writeFile( "docs/truthmark/areas.md", `# Truthmark Areas @@ -695,7 +691,6 @@ Update truth when: platforms: - github-copilot authority: - - TRUTHMARK.md - docs/truthmark/areas.md frontmatter: required: [] @@ -762,7 +757,6 @@ realization: platforms: - gemini-cli authority: - - TRUTHMARK.md - docs/truthmark/areas.md instruction_targets: - AGENTS.md @@ -774,7 +768,6 @@ realization: enabled: true `, ); - await repo.writeFile("TRUTHMARK.md", "# Truthmark\n"); await repo.writeFile("docs/truthmark/areas.md", "# Truthmark Areas\n"); await runInit(repo.rootDir); await repo.writeFile( @@ -982,7 +975,6 @@ Update truth when: ".truthmark/config.yml", `version: 1 authority: - - TRUTHMARK.md - docs/truthmark/areas.md - docs/features/**/*.md instruction_targets: @@ -1455,7 +1447,6 @@ Update truth when: ".truthmark/config.yml", `version: 1 authority: - - TRUTHMARK.md - docs/truthmark/areas.md - docs/features/**/*.md instruction_targets: diff --git a/tests/config/config-command.test.ts b/tests/config/config-command.test.ts index b4ee8a4..8a9f098 100644 --- a/tests/config/config-command.test.ts +++ b/tests/config/config-command.test.ts @@ -1,6 +1,7 @@ import fs from "node:fs/promises"; import { describe, expect, it } from "vitest"; +import { parse } from "yaml"; import { runConfig } from "../../src/config/command.js"; import { createTempRepo } from "../helpers/temp-repo.js"; @@ -13,21 +14,32 @@ describe("runConfig", () => { const result = await runConfig(repo.rootDir, {}); expect(result.command).toBe("config"); - expect(await repo.readFile(".truthmark/config.yml")).toContain("layout: hierarchical"); - expect(await repo.readFile(".truthmark/config.yml")).toContain( - "area_files_root: docs/truthmark/areas", + const configText = await repo.readFile(".truthmark/config.yml"); + const config = parse(configText) as { + platforms: string[]; + docs: { + layout: string; + roots: Record; + routing: { + area_files_root: string; + }; + }; + authority: string[]; + }; + + expect(config.docs.layout).toBe("hierarchical"); + expect(config.docs.routing.area_files_root).toBe("docs/truthmark/areas"); + expect(config.platforms).toEqual( + expect.arrayContaining(["github-copilot", "gemini-cli"]), ); - const config = await repo.readFile(".truthmark/config.yml"); - expect(config).toContain(" - github-copilot"); - expect(config).toContain(" - gemini-cli"); - expect(config).toContain("features: docs/features"); - expect(config).toContain("docs/features/**/*.md"); - expect(config).not.toContain("features_current"); - expect(config).not.toContain("docs/features/current"); - expect(config).not.toContain("api: docs/api"); - expect(config).not.toContain("guides: docs/guides"); + expect(config.docs.roots).toEqual({ + ai: "docs/ai", + standards: "docs/standards", + architecture: "docs/architecture", + features: "docs/features", + }); + expect(config.authority).toContain("docs/features/**/*.md"); await expect(fs.stat(`${repo.rootDir}/AGENTS.md`)).rejects.toThrow(); - await expect(fs.stat(`${repo.rootDir}/TRUTHMARK.md`)).rejects.toThrow(); await expect(fs.stat(`${repo.rootDir}/docs/truthmark/areas.md`)).rejects.toThrow(); expect(result.diagnostics).toEqual( expect.arrayContaining([ diff --git a/tests/config/load.test.ts b/tests/config/load.test.ts index aebb677..11948a4 100644 --- a/tests/config/load.test.ts +++ b/tests/config/load.test.ts @@ -12,7 +12,7 @@ describe("loadConfig", () => { ".truthmark/config.yml", `version: 1 authority: - - TRUTHMARK.md + - docs/truthmark/areas.md realization: enabled: true `, @@ -25,7 +25,7 @@ realization: expect(result.config).toMatchObject({ version: 1, platforms: ["codex", "opencode", "claude-code", "github-copilot", "gemini-cli"], - authority: ["TRUTHMARK.md"], + authority: ["docs/truthmark/areas.md"], docs: { layout: "hierarchical", roots: { @@ -59,7 +59,7 @@ realization: ".truthmark/config.yml", `version: 1 authority: - - TRUTHMARK.md + - docs/truthmark/areas.md instruction_targets: - AGENTS.md platforms: @@ -105,7 +105,7 @@ docs: default_area: core max_delegation_depth: 1 authority: - - TRUTHMARK.md + - docs/truthmark/areas.md realization: enabled: true `, @@ -148,7 +148,7 @@ docs: default_area: repository max_delegation_depth: 2 authority: - - TRUTHMARK.md + - docs/truthmark/areas.md realization: enabled: true `, @@ -182,7 +182,7 @@ platforms: - codex - unknown-agent authority: - - TRUTHMARK.md + - docs/truthmark/areas.md realization: enabled: true `, @@ -240,7 +240,7 @@ realization: ".truthmark/config.yml", `version: 1 authority: - - TRUTHMARK.md + - docs/truthmark/areas.md alignment: mode: packet outputs: diff --git a/tests/fs/paths.test.ts b/tests/fs/paths.test.ts index 89647b3..163488b 100644 --- a/tests/fs/paths.test.ts +++ b/tests/fs/paths.test.ts @@ -48,4 +48,22 @@ describe("repo path writes", () => { await repo.cleanup(); } }); -}); \ No newline at end of file + + it("rejects ensureRepoFile when the target is a broken symlink outside the repo", async () => { + const repo = await createTempRepo(); + const outsidePath = path.resolve(repo.rootDir, "..", "truthmark-paths-broken-link.md"); + + try { + await repo.writeFile("docs/templates/.keep", ""); + await fs.symlink(outsidePath, path.join(repo.rootDir, "docs", "templates", "feature-doc.md")); + + await expect( + ensureRepoFile(repo.rootDir, "docs/templates/feature-doc.md", "# Template\n"), + ).rejects.toThrow("must stay inside the repository root"); + await expect(fs.stat(outsidePath)).rejects.toThrow(); + } finally { + await fs.rm(outsidePath, { force: true }); + await repo.cleanup(); + } + }); +}); diff --git a/tests/git/changes.test.ts b/tests/git/changes.test.ts index da69c05..ccda973 100644 --- a/tests/git/changes.test.ts +++ b/tests/git/changes.test.ts @@ -89,7 +89,6 @@ describe("getUncommittedChanges", () => { describe("classifyPath", () => { it("treats markdown docs and config files as non-functional", () => { expect(classifyPath("docs/guides/authentication.md", [])).toBe("markdown"); - expect(classifyPath("TRUTHMARK.md", [])).toBe("markdown"); expect(classifyPath(".truthmark/config.yml", [])).toBe("config"); expect(classifyPath("package.json", [])).toBe("config"); expect(classifyPath("src/auth/session.ts", [])).toBe("functional-code"); diff --git a/tests/init/init-instructions.test.ts b/tests/init/init-instructions.test.ts index f507d95..afd0b3c 100644 --- a/tests/init/init-instructions.test.ts +++ b/tests/init/init-instructions.test.ts @@ -27,7 +27,7 @@ describe("runInit instruction integration", () => { expect(agents).toContain("code changed -> tests -> Sync -> report"); expect(agents).toContain("Delegation is host-owned"); expect(agents).toContain( - "Explicit workflows: Truth Structure, Truth Realize, Truth Check", + "Explicit workflows: Truth Structure, Truth Document, Truth Realize, Truth Check", ); expect(agents).toContain("load the installed skill for details"); expect(agents).not.toContain("/skill truthmark-structure"); @@ -59,7 +59,6 @@ describe("runInit instruction integration", () => { ".truthmark/config.yml", `version: 1 authority: - - TRUTHMARK.md - docs/truthmark/areas.md - docs/truthmark/areas/**/*.md instruction_targets: diff --git a/tests/init/init.test.ts b/tests/init/init.test.ts index fc6adf9..f508ef7 100644 --- a/tests/init/init.test.ts +++ b/tests/init/init.test.ts @@ -1,6 +1,8 @@ import fs from "node:fs/promises"; +import path from "node:path"; import { describe, expect, it } from "vitest"; +import { parse } from "yaml"; import { runConfig } from "../../src/config/command.js"; import { runInit } from "../../src/init/init.js"; @@ -26,7 +28,6 @@ describe("runInit", () => { ]), ); await expect(fs.stat(`${repo.rootDir}/AGENTS.md`)).rejects.toThrow(); - await expect(fs.stat(`${repo.rootDir}/TRUTHMARK.md`)).rejects.toThrow(); await expect( fs.stat(`${repo.rootDir}/docs/truthmark/areas.md`), ).rejects.toThrow(); @@ -41,23 +42,26 @@ describe("runInit", () => { try { await runConfig(repo.rootDir, {}); const result = await runInit(repo.rootDir); + const config = parse(await repo.readFile(".truthmark/config.yml")) as { + version: number; + platforms: string[]; + docs: { + roots: Record; + }; + }; expect(result.command).toBe("init"); - expect(await repo.readFile(".truthmark/config.yml")).toContain( - "version: 1", - ); - expect(await repo.readFile(".truthmark/config.yml")).toContain( - "platforms:", - ); - expect(await repo.readFile(".truthmark/config.yml")).not.toContain( - "specs_draft", - ); + expect(config.version).toBe(1); + expect(config.platforms.length).toBeGreaterThan(0); + expect(config.docs.roots).toEqual({ + ai: "docs/ai", + standards: "docs/standards", + architecture: "docs/architecture", + features: "docs/features", + }); await expect( fs.stat(`${repo.rootDir}/.truthmark/local.example.yml`), ).rejects.toThrow(); - expect(await repo.readFile("TRUTHMARK.md")).toContain( - "Markdown in the current checkout is authoritative for this branch.", - ); expect(await repo.readFile("docs/truthmark/areas.md")).toContain( "# Truthmark Areas", ); @@ -83,6 +87,24 @@ describe("runInit", () => { "Feature Docs", ); expect(await repo.readFile("docs/features/README.md")).toContain("index"); + expect(await repo.readFile("docs/templates/feature-doc.md")).toContain( + "# {{title}}", + ); + expect(await repo.readFile("docs/templates/feature-doc.md")).toContain( + "## Current Behavior", + ); + expect(await repo.readFile("docs/templates/feature-doc.md")).toContain( + "## Scope\n\n{{scope}}", + ); + expect(await repo.readFile("docs/templates/feature-doc.md")).toContain( + "## Core Rules", + ); + expect(await repo.readFile("docs/templates/feature-doc.md")).toContain( + "## Flows And States", + ); + expect(await repo.readFile("docs/templates/feature-doc.md")).toContain( + "Split into another leaf doc when content introduces", + ); expect( await repo.readFile("docs/features/repository/README.md"), ).toContain("Repository Feature Docs"); @@ -92,18 +114,37 @@ describe("runInit", () => { expect( await repo.readFile("docs/features/repository/overview.md"), ).toContain("# Repository Overview"); + expect( + await repo.readFile("docs/features/repository/overview.md"), + ).toContain( + "This doc was created from the editable feature-doc template at docs/templates/feature-doc.md.", + ); expect( await repo.readFile("docs/features/repository/overview.md"), ).toContain("## Current Behavior"); + expect( + await repo.readFile("docs/features/repository/overview.md"), + ).toContain("## Purpose"); + expect( + (await repo.readFile("docs/features/repository/overview.md")).match( + /## Scope/g, + ), + ).toHaveLength(1); + expect( + await repo.readFile("docs/features/repository/overview.md"), + ).toContain("## Non-Goals"); + expect( + await repo.readFile("docs/features/repository/overview.md"), + ).toContain("## Maintenance Notes"); + expect( + await repo.readFile("docs/features/repository/overview.md"), + ).not.toContain("{{"); expect( await repo.readFile("docs/features/repository/overview.md"), ).toContain("## Product Decisions"); expect( await repo.readFile("docs/features/repository/overview.md"), ).toContain("## Rationale"); - await expect( - fs.stat(`${repo.rootDir}/docs/features/current/README.md`), - ).rejects.toThrow(); const agents = await repo.readFile("AGENTS.md"); const structureSkill = await repo.readFile( @@ -115,6 +156,15 @@ describe("runInit", () => { const structureOpenCodeSkill = await repo.readFile( ".opencode/skills/truthmark-structure/SKILL.md", ); + const documentSkill = await repo.readFile( + ".codex/skills/truthmark-document/SKILL.md", + ); + const documentSkillMetadata = await repo.readFile( + ".codex/skills/truthmark-document/agents/openai.yaml", + ); + const documentOpenCodeSkill = await repo.readFile( + ".opencode/skills/truthmark-document/SKILL.md", + ); const syncSkill = await repo.readFile( ".codex/skills/truthmark-sync/SKILL.md", ); @@ -158,7 +208,7 @@ describe("runInit", () => { expect(agents).not.toContain("/skill truthmark-structure"); expect(agents).not.toContain("/skill truthmark-check"); expect(agents).toContain( - "Explicit workflows: Truth Structure, Truth Realize, Truth Check", + "Explicit workflows: Truth Structure, Truth Document, Truth Realize, Truth Check", ); expect(agents).toContain("load the installed skill for details"); expect(agents).toContain("Truthmark hierarchy:"); @@ -191,6 +241,14 @@ describe("runInit", () => { 'display_name: "Truthmark Structure"', ); expect(structureOpenCodeSkill).toContain("name: truthmark-structure"); + expect(documentSkill).toContain("name: truthmark-document"); + expect(documentSkill).toContain("Truth Document: completed"); + expect(documentSkill).toContain("must not write functional code"); + expect(documentSkillMetadata).toContain( + 'display_name: "Truthmark Document"', + ); + expect(documentSkillMetadata).toContain("allow_implicit_invocation: false"); + expect(documentOpenCodeSkill).toContain("name: truthmark-document"); expect(syncSkill).toContain("name: truthmark-sync"); expect(syncSkill).toContain("user-invocable: true"); expect(syncSkill).toContain(`truthmark-version: ${TRUTHMARK_VERSION}`); @@ -202,7 +260,7 @@ describe("runInit", () => { ); expect(syncSkill).toContain("host supports subagent dispatch"); expect(syncSkill).toContain( - "Read .truthmark/config.yml, TRUTHMARK.md, the configured root route index", + "Read .truthmark/config.yml, the configured root route index", ); expect(syncSkill).toContain("relevant child route files"); expect(syncSkill).not.toContain(".truthmark/local.yml"); @@ -243,6 +301,9 @@ describe("runInit", () => { await expect( fs.stat(`${repo.rootDir}/skills/truthmark-structure/SKILL.md`), ).rejects.toThrow(); + await expect( + fs.stat(`${repo.rootDir}/skills/truthmark-document/SKILL.md`), + ).rejects.toThrow(); await expect( fs.stat(`${repo.rootDir}/skills/truthmark-sync/SKILL.md`), ).rejects.toThrow(); @@ -281,6 +342,13 @@ describe("runInit", () => { diagnostic.file === ".codex/skills/truthmark-structure/SKILL.md", ), ).toBe(true); + expect( + result.diagnostics.some( + (diagnostic) => + diagnostic.category === "truth-sync" && + diagnostic.file === ".codex/skills/truthmark-document/SKILL.md", + ), + ).toBe(true); expect( result.diagnostics.some( (diagnostic) => @@ -310,7 +378,6 @@ platforms: - github-copilot - gemini-cli authority: - - TRUTHMARK.md - docs/truthmark/areas.md instruction_targets: - AGENTS.md @@ -320,6 +387,17 @@ frontmatter: ignore: [] realization: enabled: true +`, + ); + await repo.writeFile( + "GEMINI.md", + `Follow \`docs/ai/repo-rules.md\`. + +Use that file as the primary repository instruction source for Codex. + +Codex-specific: +- Read \`docs/README.md\` for the canonical docs map. +- Use \`docs/ai/agent-onboarding.md\` for quick task routing. `, ); @@ -337,10 +415,16 @@ realization: expect( await repo.readFile(".github/prompts/truthmark-sync.prompt.md"), ).toContain("GitHub Copilot /truthmark-sync"); + expect( + await repo.readFile(".github/prompts/truthmark-document.prompt.md"), + ).toContain("GitHub Copilot /truthmark-document"); await expect(fs.stat(`${repo.rootDir}/GEMINI.md`)).resolves.toBeTruthy(); await expect( fs.stat(`${repo.rootDir}/.gemini/commands/truthmark/structure.toml`), ).resolves.toBeTruthy(); + await expect( + fs.stat(`${repo.rootDir}/.gemini/commands/truthmark/document.toml`), + ).resolves.toBeTruthy(); await expect( fs.stat(`${repo.rootDir}/.gemini/commands/truthmark/sync.toml`), ).resolves.toBeTruthy(); @@ -353,15 +437,25 @@ realization: expect( await repo.readFile(".gemini/commands/truthmark/sync.toml"), ).toContain( - 'description = "Sync repository truth docs from changed code."', + 'description = "Sync repository truth docs from functional code changes; skip docs-only/no-code changes."', ); expect( await repo.readFile(".gemini/commands/truthmark/sync.toml"), ).toContain("name: truthmark-sync"); + expect( + await repo.readFile(".gemini/commands/truthmark/document.toml"), + ).toContain("name: truthmark-document"); expect( await repo.readFile(".gemini/commands/truthmark/realize.toml"), ).toContain('description = "Realize repository truth docs into code."'); - expect(await repo.readFile("GEMINI.md")).toContain("/truthmark:sync"); + const geminiInstructions = await repo.readFile("GEMINI.md"); + expect(geminiInstructions).toContain("/truthmark:sync"); + expect(geminiInstructions).toContain( + "Use that file as the primary repository instruction source for this agent.", + ); + expect(geminiInstructions).toContain("Agent-specific:"); + expect(geminiInstructions).not.toContain("for Codex"); + expect(geminiInstructions).not.toContain("Codex-specific"); expect(await repo.readFile("AGENTS.md")).toContain("Truthmark Workflow"); await expect(fs.stat(`${repo.rootDir}/CLAUDE.md`)).rejects.toThrow(); await expect( @@ -385,7 +479,6 @@ realization: platforms: - claude-code authority: - - TRUTHMARK.md - docs/truthmark/areas.md instruction_targets: - AGENTS.md @@ -410,6 +503,9 @@ realization: expect( await repo.readFile(".claude/skills/truthmark-structure/SKILL.md"), ).toContain("name: truthmark-structure"); + expect( + await repo.readFile(".claude/skills/truthmark-document/SKILL.md"), + ).toContain("Claude Code /truthmark-document"); expect( await repo.readFile(".claude/skills/truthmark-check/SKILL.md"), ).toContain("name: truthmark-check"); @@ -434,7 +530,6 @@ realization: platforms: - github-copilot authority: - - TRUTHMARK.md - docs/truthmark/areas.md instruction_targets: - AGENTS.md @@ -458,6 +553,9 @@ realization: expect( await repo.readFile(".github/prompts/truthmark-structure.prompt.md"), ).toContain("name: truthmark-structure"); + expect( + await repo.readFile(".github/prompts/truthmark-document.prompt.md"), + ).toContain("GitHub Copilot /truthmark-document"); expect( await repo.readFile(".github/prompts/truthmark-check.prompt.md"), ).toContain("name: truthmark-check"); @@ -514,6 +612,74 @@ realization: } }); + it("uses an authored feature doc template for new scaffolded leaf docs", async () => { + const repo = await createTempRepo(); + + try { + await runConfig(repo.rootDir, {}); + await repo.writeFile( + "docs/templates/feature-doc.md", + `--- +status: active +doc_type: feature +last_reviewed: 2026-05-12 +source_of_truth: + - {{source_of_truth}} +--- + +# {{title}} + +## Local Standard + +Custom template for {{area}}. +`, + ); + + await runInit(repo.rootDir); + + expect(await repo.readFile("docs/templates/feature-doc.md")).toContain( + "## Local Standard", + ); + expect( + await repo.readFile("docs/features/repository/overview.md"), + ).toContain("## Local Standard"); + expect( + await repo.readFile("docs/features/repository/overview.md"), + ).toContain("Custom template for repository."); + expect( + await repo.readFile("docs/features/repository/overview.md"), + ).not.toContain("{{"); + } finally { + await repo.cleanup(); + } + }); + + it("rejects a broken feature-doc template symlink that would write outside the repo", async () => { + const repo = await createTempRepo(); + const outsideTemplatePath = path.resolve( + repo.rootDir, + "..", + "truthmark-outside-feature-doc-template.md", + ); + + try { + await runConfig(repo.rootDir, {}); + await repo.writeFile("docs/templates/.keep", ""); + await fs.symlink( + outsideTemplatePath, + path.join(repo.rootDir, "docs", "templates", "feature-doc.md"), + ); + + await expect(runInit(repo.rootDir)).rejects.toThrow( + "must stay inside the repository root", + ); + await expect(fs.stat(outsideTemplatePath)).rejects.toThrow(); + } finally { + await fs.rm(outsideTemplatePath, { force: true }); + await repo.cleanup(); + } + }); + it("is idempotent and only updates the managed AGENTS block when needed", async () => { const repo = await createTempRepo(); @@ -592,7 +758,6 @@ docs: default_area: repository max_delegation_depth: 1 authority: - - TRUTHMARK.md - docs/truthmark/areas.md - docs/truthmark/areas/**/*.md - docs/product/**/*.md @@ -620,7 +785,7 @@ realization: } }); - it("does not overwrite authored Truthmark-owned files on rerun", async () => { + it("does not overwrite authored config and routing files on rerun", async () => { const repo = await createTempRepo(); try { @@ -630,10 +795,6 @@ realization: ".truthmark/config.yml", `${await repo.readFile(".truthmark/config.yml")}\ncustom: true\n`, ); - await repo.writeFile( - "TRUTHMARK.md", - `${await repo.readFile("TRUTHMARK.md")}\n## Local Notes\nKeep this text.\n`, - ); await repo.writeFile( "docs/truthmark/areas.md", `${await repo.readFile("docs/truthmark/areas.md")}\n## Local Area Notes\nKeep this routing note.\n`, @@ -644,7 +805,6 @@ realization: expect(await repo.readFile(".truthmark/config.yml")).toContain( "custom: true", ); - expect(await repo.readFile("TRUTHMARK.md")).toContain("Keep this text."); expect(await repo.readFile("docs/truthmark/areas.md")).toContain( "Keep this routing note.", ); diff --git a/tests/integration/agent-workflow-contract.test.ts b/tests/integration/agent-workflow-contract.test.ts index dea01e6..de46a87 100644 --- a/tests/integration/agent-workflow-contract.test.ts +++ b/tests/integration/agent-workflow-contract.test.ts @@ -26,6 +26,9 @@ describe("installed workflow contract", () => { const syncSkill = await repo.readFile( ".codex/skills/truthmark-sync/SKILL.md", ); + const documentSkill = await repo.readFile( + ".codex/skills/truthmark-document/SKILL.md", + ); const syncOpenCodeSkill = await repo.readFile( ".opencode/skills/truthmark-sync/SKILL.md", ); @@ -52,7 +55,7 @@ describe("installed workflow contract", () => { expect(agents).not.toContain("/skill truthmark-structure"); expect(agents).not.toContain("/skill truthmark-check"); expect(agents).toContain( - "Explicit workflows: Truth Structure, Truth Realize, Truth Check", + "Explicit workflows: Truth Structure, Truth Document, Truth Realize, Truth Check", ); expect(agents).not.toContain( "truthmark check --json --workflow truth-sync", @@ -62,8 +65,10 @@ describe("installed workflow contract", () => { expect(agents).not.toContain("Truth Sync: completed"); expect(agents).not.toContain("Truth Realize: completed"); expect(structureSkill).toContain("name: truthmark-structure"); + expect(structureSkill).toContain("docs/ai/repo-rules.md"); expect(structureSkill).toContain("docs/truthmark/areas.md"); expect(syncSkill).toContain("name: truthmark-sync"); + expect(syncSkill).toContain("docs/ai/repo-rules.md"); expect(syncSkill).toContain( "Use this skill automatically before finishing", ); @@ -74,6 +79,9 @@ describe("installed workflow contract", () => { expect(syncSkill).toContain( "direct checkout inspection is the canonical path", ); + expect(documentSkill).toContain("name: truthmark-document"); + expect(documentSkill).toContain("Truth Document: completed"); + expect(documentSkill).toContain("must not write functional code"); expect(syncOpenCodeSkill).toContain("name: truthmark-sync"); expect(syncClaudeSkill).toContain("name: truthmark-sync"); expect(syncClaudeSkill).toContain( diff --git a/tests/integration/branch-scope.test.ts b/tests/integration/branch-scope.test.ts index 6a58630..37099ef 100644 --- a/tests/integration/branch-scope.test.ts +++ b/tests/integration/branch-scope.test.ts @@ -93,22 +93,22 @@ describe("branch-scoped truth integration", () => { const secondary = await repo.addWorktree("feature/docs"); await secondary.writeFile( - "TRUTHMARK.md", - `${await secondary.readFile("TRUTHMARK.md")}\n## Feature Branch Notes\nOnly here.\n`, + "docs/truthmark/areas.md", + `${await secondary.readFile("docs/truthmark/areas.md")}\n## Feature Branch Notes\nOnly here.\n`, ); const primaryResult = await runCheck(repo.rootDir); const secondaryResult = await runCheck(secondary.rootDir); const primaryHash = (primaryResult.data?.branchScope as { relevantFileHashes: Record }) - .relevantFileHashes["TRUTHMARK.md"]; + .relevantFileHashes["docs/truthmark/areas.md"]; const secondaryHash = (secondaryResult.data?.branchScope as { relevantFileHashes: Record }) - .relevantFileHashes["TRUTHMARK.md"]; + .relevantFileHashes["docs/truthmark/areas.md"]; expect(primaryHash).toBeTruthy(); expect(secondaryHash).toBeTruthy(); expect(primaryHash).not.toBe(secondaryHash); - expect(await repo.readFile("TRUTHMARK.md")).not.toContain("Feature Branch Notes"); - expect(await secondary.readFile("TRUTHMARK.md")).toContain("Feature Branch Notes"); + expect(await repo.readFile("docs/truthmark/areas.md")).not.toContain("Feature Branch Notes"); + expect(await secondary.readFile("docs/truthmark/areas.md")).toContain("Feature Branch Notes"); } finally { await repo.cleanup(); } diff --git a/tests/integration/init-check-workflow.test.ts b/tests/integration/init-check-workflow.test.ts index da4312f..56974f9 100644 --- a/tests/integration/init-check-workflow.test.ts +++ b/tests/integration/init-check-workflow.test.ts @@ -24,7 +24,6 @@ describe("init and check workflow acceptance", () => { expect(initPayload.command).toBe("init"); await expect(fs.stat(`${repo.rootDir}/.truthmark/config.yml`)).resolves.toBeTruthy(); - await expect(fs.stat(`${repo.rootDir}/TRUTHMARK.md`)).resolves.toBeTruthy(); await expect(fs.stat(`${repo.rootDir}/docs/truthmark/areas.md`)).resolves.toBeTruthy(); await expect(fs.stat(`${repo.rootDir}/AGENTS.md`)).resolves.toBeTruthy(); await expect( diff --git a/tests/markdown/discovery.test.ts b/tests/markdown/discovery.test.ts index 4fd47ad..7a334c2 100644 --- a/tests/markdown/discovery.test.ts +++ b/tests/markdown/discovery.test.ts @@ -5,12 +5,10 @@ import { createTempRepo } from "../helpers/temp-repo.js"; import { discoverMarkdownDocuments } from "../../src/markdown/discovery.js"; import { renderConfigTemplate, - renderTruthmarkTemplate, renderAreasTemplate, } from "../../src/templates/init-files.js"; import { renderDefaultStandards } from "../../src/templates/default-standards.js"; import { renderAgentsBlock } from "../../src/templates/agents-block.js"; -import { TRUTHMARK_VERSION } from "../../src/version.js"; describe("discoverMarkdownDocuments", () => { it("finds repository markdown docs and ignores common derived directories", async () => { @@ -124,28 +122,12 @@ describe("init templates", () => { required: [], recommended: ["status", "doc_type", "last_reviewed", "source_of_truth"], }); - expect(config.docs.roots).not.toHaveProperty("specs_draft"); - }); - - it("renders TRUTHMARK.md as a compact branch-local truth contract", () => { - const truthmark = renderTruthmarkTemplate(); - - expect(truthmark).toContain( - "Markdown in the current checkout is authoritative for this branch.", - ); - expect(truthmark).toContain( - `Truthmark ${TRUTHMARK_VERSION} version marker`, - ); - expect(truthmark).toContain("rerun `truthmark init`"); - expect(truthmark).toContain( - "Workflow runtime lives in installed skills and managed instruction blocks.", - ); - expect(truthmark).toContain( - "Truth Sync follows code; Truth Realize follows docs.", - ); - expect(truthmark.split("\n").length).toBeLessThanOrEqual(18); - expect(truthmark).not.toContain("Truth Structure"); - expect(truthmark).not.toContain("Truth Check"); + expect(config.docs.roots).toEqual({ + ai: "docs/ai", + standards: "docs/standards", + architecture: "docs/architecture", + features: "docs/features", + }); }); it("seeds docs/truthmark/areas.md from discovered docs without moving them", () => { @@ -179,12 +161,18 @@ describe("init templates", () => { expect(agentsBlock).not.toContain("### Truth Structure"); expect(agentsBlock).not.toContain("### Truth Check"); expect(agentsBlock).toContain( - "Explicit workflows: Truth Structure, Truth Realize, Truth Check", + "Explicit workflows: Truth Structure, Truth Document, Truth Realize, Truth Check", ); expect(agentsBlock).toContain( "may write truth docs and docs/truthmark/areas.md only", ); expect(agentsBlock).toContain("must not rewrite functional code"); + expect(agentsBlock).toContain( + "if routing is missing/stale/broad/overloaded/catch-all or cannot map changed code to a bounded truth owner", + ); + expect(agentsBlock).toContain( + "otherwise block and recommend Truth Structure", + ); expect(agentsBlock).not.toContain("write functional code only"); expect(agentsBlock).not.toContain("do not edit truth docs or truth routing"); }); @@ -196,6 +184,12 @@ describe("init templates", () => { "docs/standards/default-principles.md", "docs/standards/documentation-governance.md", ]); + expect(missingStandards.map((template) => template.content).join("\n")).toContain( + "Architecture docs describe system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, and generated-surface ownership.", + ); + expect(missingStandards.map((template) => template.content).join("\n")).toContain( + "Do not put ordinary feature behavior in architecture docs.", + ); const existingStandards = renderDefaultStandards([ { diff --git a/tests/markdown/parse.test.ts b/tests/markdown/parse.test.ts index f8ae23a..0ef4026 100644 --- a/tests/markdown/parse.test.ts +++ b/tests/markdown/parse.test.ts @@ -35,20 +35,20 @@ describe("resolveAuthorityPaths", () => { const repo = await createTempRepo(); try { - await repo.writeFile("TRUTHMARK.md", "# Truthmark\n"); + await repo.writeFile("docs/truthmark/areas.md", "# Truthmark Areas\n"); await repo.writeFile("docs/guides/beta.md", "# Beta\n"); await repo.writeFile("docs/guides/alpha.md", "# Alpha\n"); await repo.writeFile("docs/api/authentication.md", "# Auth API\n"); const result = await resolveAuthorityPaths(repo.rootDir, [ - "TRUTHMARK.md", + "docs/truthmark/areas.md", "docs/guides/*.md", "docs/api/*.md", ]); expect(result.diagnostics).toEqual([]); expect(result.paths).toEqual([ - "TRUTHMARK.md", + "docs/truthmark/areas.md", "docs/guides/alpha.md", "docs/guides/beta.md", "docs/api/authentication.md", diff --git a/tests/output/render.test.ts b/tests/output/render.test.ts index 1c2cc1b..f663839 100644 --- a/tests/output/render.test.ts +++ b/tests/output/render.test.ts @@ -78,7 +78,7 @@ describe("output rendering", () => { }, ], data: { - files: [".truthmark/config.yml", "TRUTHMARK.md"], + files: [".truthmark/config.yml", "docs/truthmark/areas.md"], }, }; diff --git a/tests/sync/policy.test.ts b/tests/sync/policy.test.ts index 66e74b8..0081379 100644 --- a/tests/sync/policy.test.ts +++ b/tests/sync/policy.test.ts @@ -23,7 +23,6 @@ describe("Truth Sync policy", () => { "changed functional code files", "nearby implementation context when needed to understand the changed surface", ".truthmark/config.yml", - "TRUTHMARK.md", "docs/truthmark/areas.md", "mapped truth docs", ],