diff --git a/.agents/skills/truthmark-check/SKILL.md b/.agents/skills/truthmark-check/SKILL.md index b8b5902..fba7a53 100644 --- a/.agents/skills/truthmark-check/SKILL.md +++ b/.agents/skills/truthmark-check/SKILL.md @@ -3,7 +3,7 @@ name: truthmark-check description: Use when the user asks to audit repository truth health, routing, ownership, or canonical docs. Not for normal lint/test/typecheck/code-review verification, finish-time Sync, or silently rewriting docs. argument-hint: Optional area, doc path, or audit focus user-invocable: true -truthmark-version: 2.1.0 +truthmark-version: 2.2.1 --- # Truthmark Check diff --git a/.agents/skills/truthmark-check/agents/openai.yaml b/.agents/skills/truthmark-check/agents/openai.yaml index 7156cc6..88a0e83 100644 --- a/.agents/skills/truthmark-check/agents/openai.yaml +++ b/.agents/skills/truthmark-check/agents/openai.yaml @@ -7,5 +7,5 @@ policy: allow_implicit_invocation: false truthmark: - version: "2.1.0" + version: "2.2.1" refresh_command: "truthmark init" diff --git a/.agents/skills/truthmark-check/support/procedure.md b/.agents/skills/truthmark-check/support/procedure.md index 6132ff9..3408f9b 100644 --- a/.agents/skills/truthmark-check/support/procedure.md +++ b/.agents/skills/truthmark-check/support/procedure.md @@ -1,6 +1,6 @@ # Truthmark Check Procedure -Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. # Truthmark Check @@ -11,13 +11,31 @@ Invocations: OpenCode /skill truthmark-check; Codex /truthmark-check or $truthma Truth Check is agent-led: - inspect .truthmark/config.yml and configured route files only when they exist; then inspect canonical docs and relevant implementation directly -- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. -Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. - inspect the configured root route index at docs/truthmark/routes/areas.md and relevant child route files under docs/truthmark/routes/areas/ when they exist +- Evidence authority: + - Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. + - Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. +- Lane classification: + - classify the request or changed surface as product-lane, engineering-lane, both-lane, or ambiguous for reporting only + - product-lane ownership belongs under docs/truthmark/product and describes product promises, boundaries, rationale, decisions, and success criteria + - engineering-lane ownership belongs under docs/truthmark/engineering and describes source-backed current realization, contracts, architecture, workflows, operations, or tests + - both-lane ownership uses separate product and engineering docs cross-linked in route YAML with realized_by and realizes, not in doc frontmatter + - ambiguous lane ownership should be reported as blocked or routed to Truth Structure + - Do not make product docs a summary of engineering docs. Do not make engineering docs a detailed version of product docs. Product truth says what must be true and why. Engineering truth says how the repository currently realizes it. - check that current docs describe current code rather than historical plans +- keep lane and cross-lane checks route-first and bounded: + - for a narrow audit, inspect only the routed area and directly linked counterpart docs + - for root-wide truth health, first build a cheap route-map/index from route files, then inspect only mismatches and linked leaves + - inspect product counterparts for engineering docs only when route YAML claims a product relationship, or when the user explicitly asks for user-visible product coverage +- check lane root/kind alignment for product truth under docs/truthmark/product and engineering truth under docs/truthmark/engineering +- check route YAML cross-lane realized_by and realizes links for existence and lane compatibility +- report missing product links for user-visible engineering docs only as a second-pass review diagnostic, not as default full-document reads or hard errors +- check product docs do not contain engineering execution flow, generated file inventories, or CLI envelope mechanics +- check engineering docs do not contain product promises, product rationale, or Product Decisions sections +- never judge whether a product decision is commercially correct, valuable, prioritized, or desirable - check that route files map code surfaces to canonical truth docs when route files exist - check for broad, catch-all, index-like, or mixed-owner truth docs and report them as topology issues requiring Truth Structure -- check that canonical behavior docs keep active Product Decisions and Rationale sections +- check that canonical docs keep lane-appropriate decisions and rationale sections - optionally run truthmark check when local tooling is available - must not require the truthmark binary; direct inspection is always valid - report issues and suggested fixes without silently rewriting unrelated files @@ -31,7 +49,8 @@ Truthmark hierarchy hints: - Config, when present: .truthmark/config.yml - Root route index, when present: docs/truthmark/routes/areas.md - Area route files, when present: docs/truthmark/routes/areas/**/*.md -- Truth docs, when present: docs/truthmark/truth/**/*.md +- Product truth docs, when present: docs/truthmark/product/**/*.md +- Engineering truth docs, when present: docs/truthmark/engineering/**/*.md Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. -Update Product Decisions and Rationale when a decision changes behavior. +Product decisions belong in product truth; engineering, architecture, contract, workflow, and operational decisions belong in engineering truth. diff --git a/.agents/skills/truthmark-check/support/report-template.md b/.agents/skills/truthmark-check/support/report-template.md index 00a3453..7253416 100644 --- a/.agents/skills/truthmark-check/support/report-template.md +++ b/.agents/skills/truthmark-check/support/report-template.md @@ -1,6 +1,6 @@ # Truthmark Check Report Template -Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. Report completion in this shape: diff --git a/.agents/skills/truthmark-check/support/subagents-and-leases.md b/.agents/skills/truthmark-check/support/subagents-and-leases.md index b55697f..05246e4 100644 --- a/.agents/skills/truthmark-check/support/subagents-and-leases.md +++ b/.agents/skills/truthmark-check/support/subagents-and-leases.md @@ -1,6 +1,6 @@ # Truthmark Check Subagents And Leases -Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. Codex subagent mode: - use automatically when this workflow runs in Codex and the parent agent chooses bounded subagent fan-out diff --git a/.agents/skills/truthmark-document/SKILL.md b/.agents/skills/truthmark-document/SKILL.md index 241a841..1caec9b 100644 --- a/.agents/skills/truthmark-document/SKILL.md +++ b/.agents/skills/truthmark-document/SKILL.md @@ -3,7 +3,7 @@ name: truthmark-document description: Use when the user asks to document existing implemented behavior, or Sync, Check, or Structure finds implemented behavior missing canonical truth. Not for functional-code changes, doc-first implementation, or topology repair that needs Structure. argument-hint: Optional implemented behavior, API endpoint, route, controller, package, or truth-doc area to document user-invocable: true -truthmark-version: 2.1.0 +truthmark-version: 2.2.1 --- # Truthmark Document diff --git a/.agents/skills/truthmark-document/agents/openai.yaml b/.agents/skills/truthmark-document/agents/openai.yaml index 1ed710a..a4cb871 100644 --- a/.agents/skills/truthmark-document/agents/openai.yaml +++ b/.agents/skills/truthmark-document/agents/openai.yaml @@ -7,5 +7,5 @@ policy: allow_implicit_invocation: false truthmark: - version: "2.1.0" + version: "2.2.1" refresh_command: "truthmark init" diff --git a/.agents/skills/truthmark-document/helper-manifest.yml b/.agents/skills/truthmark-document/helper-manifest.yml index 175e1a0..f7b749b 100644 --- a/.agents/skills/truthmark-document/helper-manifest.yml +++ b/.agents/skills/truthmark-document/helper-manifest.yml @@ -1,8 +1,8 @@ -# Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +# Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. helpers: validate-document-report: optional: true - runner: truthmark>=2.1.0 + runner: truthmark>=2.2.1 command: argv: - truthmark @@ -17,7 +17,7 @@ helpers: fallback: manually validate support/report-template.md required sections and structured Evidence checked entries validate-write-lease: optional: true - runner: truthmark>=2.1.0 + runner: truthmark>=2.2.1 command: argv: - truthmark diff --git a/.agents/skills/truthmark-document/support/helper-policy.md b/.agents/skills/truthmark-document/support/helper-policy.md index 2cb7bd6..9e87b00 100644 --- a/.agents/skills/truthmark-document/support/helper-policy.md +++ b/.agents/skills/truthmark-document/support/helper-policy.md @@ -1,6 +1,6 @@ # Optional Helper CLI Policy -Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. Optional helper CLI commands may collect deterministic checkout facts or validate artifacts. If the Truthmark CLI is unavailable or too old for a declared helper, continue manually using this procedure and report which helper was skipped. Helper output is derived evidence; it does not override direct checkout inspection, workflow write boundaries, or parent acceptance. @@ -11,8 +11,8 @@ Runner detection: - Do not fail the workflow solely because a helper cannot run. Available helpers: -- validate-document-report: optional truthmark>=2.1.0; manual fallback: manually validate support/report-template.md required sections and structured Evidence checked entries -- validate-write-lease: optional truthmark>=2.1.0; manual fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files +- validate-document-report: optional truthmark>=2.2.1; manual fallback: manually validate support/report-template.md required sections and structured Evidence checked entries +- validate-write-lease: optional truthmark>=2.2.1; manual fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files Final reports should include helper status when helpers are declared for this workflow: diff --git a/.agents/skills/truthmark-document/support/procedure.md b/.agents/skills/truthmark-document/support/procedure.md index be8590f..db0602c 100644 --- a/.agents/skills/truthmark-document/support/procedure.md +++ b/.agents/skills/truthmark-document/support/procedure.md @@ -1,6 +1,6 @@ # Truthmark Document Procedure -Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. # Truthmark Document @@ -11,8 +11,16 @@ Truth Document is manual and implementation-first: - run only when the user explicitly asks to generate or update truth docs for existing behavior, or when Truth Sync, Truth Check, or Truth Structure reports implemented behavior that lacks canonical truth docs - inspect .truthmark/config.yml and configured route files only when they exist; then inspect existing canonical docs, implementation code, and tests directly -- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. -Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. +- Evidence authority: + - Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. + - Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. +- Lane classification: + - before writing canonical truth docs, classify the request or change as product-lane, engineering-lane, both-lane, or ambiguous + - product-lane writes belong under docs/truthmark/product and state product promises, boundaries, rationale, decisions, and success criteria + - engineering-lane writes belong under docs/truthmark/engineering and state source-backed current realization, contracts, architecture, workflows, operations, or tests + - both-lane work must write separate product and engineering docs and cross-link them in route YAML with realized_by and realizes, not in doc frontmatter + - ambiguous lane ownership must block or invoke Truth Structure instead of writing a mixed document + - Do not make product docs a summary of engineering docs. Do not make engineering docs a detailed version of product docs. Product truth says what must be true and why. Engineering truth says how the repository currently realizes it. - document current implemented behavior; do not invent future behavior or planned endpoints - may write canonical truth docs and docs/truthmark/routes/areas.md or relevant child route files only - must not write functional code @@ -20,7 +28,10 @@ Implementation code and canonical truth docs are inspected evidence for current - block and recommend Truth Structure when routing repair is unsafe, ambiguous, or outside the task boundary - keep feature README.md files as indexes rather than truth-document targets - create or update bounded leaf truth docs when behavior does not fit an existing leaf doc -- keep behavior truth docs behavior-oriented, not endpoint-oriented, unless the endpoint itself is the behavior boundary +- write product capability/boundary truth under docs/truthmark/product when documenting product promise, boundary, rationale, or user/stakeholder value +- write engineering truth under docs/truthmark/engineering when documenting implementation behavior, contracts, architecture, workflows, operations, or tests +- for both-lane documentation requests, write separate product and engineering docs and cross-link them in route YAML with realized_by and realizes, not in doc frontmatter +- keep engineering behavior truth behavior-oriented, not endpoint-oriented, unless the endpoint itself is the behavior boundary - keep API endpoint details in the nearest contract truth doc when such a doc owns the API contract - preserve unrelated authored content Truth-doc ownership gate: @@ -28,27 +39,27 @@ Truth-doc ownership gate: - if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it - if the target doc is broad, mixed-owner, index-like, or the documented behavior spans independent owners, run Truth Structure first when safe and in scope; otherwise block and recommend Truth Structure - report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Blocked reason as applicable -Product Decisions/Rationale preservation gate: -- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions and Rationale sections in every source or touched truth doc -- preserve each current decision and rationale in the bounded owner doc it governs; when splitting, move it to the new owner doc rather than deleting it or leaving it in an index +Decision/Rationale preservation gate: +- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions, Engineering Decisions, and Rationale sections in every source or touched truth doc +- preserve each current decision and rationale in the correct product or engineering lane owner; when splitting, move it to the new owner doc rather than deleting it or leaving it in an index - remove or narrow a decision or rationale only when checkout evidence shows it is stale or unsupported, and report the exact claim, evidence, and result - if ownership of a decision or rationale is unclear, block with manual-review files instead of deleting it or guessing -- after the edit, verify every touched truth doc still has Product Decisions and Rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked +- after the edit, verify every touched truth doc keeps lane-appropriate decision/rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked Evidence Gate: - route-first: map the documented behavior to bounded route owners and primary canonical docs -- review new or changed behavior-bearing claims only in touched docs, route ownership, Product Decisions, and Rationale +- review new or changed behavior-bearing claims only in touched docs, route ownership, lane-specific decisions, and rationale - support claims with primary checkout evidence: implementation, config, routing, generated templates, schemas, or contract definitions - tests/examples/canonical docs corroborate; they are not sole proof when implementation conflicts - remove, narrow, or block unsupported claims - if no truth doc changed, report why current truth was already sufficient or why documentation was blocked -Repository intelligence artifacts are optional derived context: RepoIndex, RouteMap, ImpactSet, and ContextPack may guide routing, context selection, and verification planning when available. +Repository intelligence artifacts are optional derived context: RepoIndex, RouteMap, ImpactSet, and WorkflowState/action context may guide routing, write boundaries, and verification planning when available. They do not override checkout evidence, canonical truth docs, route files, or workflow write boundaries. If unavailable, inspect any present Truthmark config, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated. When creating or updating a truth doc, inspect the routed truth kind and use the matching template under the configured Truthmark templates root. -Supported kinds: behavior, contract, architecture, workflow, operations, and test-behavior. +Supported kinds: product-capability, engineering-behavior, engineering-contract, engineering-architecture, engineering-workflow, engineering-operations, and engineering-test-behavior. Treat the HTML comments under each template section as normative authoring guidance for that section. Align existing docs to that template and write or repair section content so it satisfies the comment guidance while preserving accurate authored content. -If the template is missing, use Scope, Product Decisions, Rationale, and the kind-specific current-truth section. +If the template is missing, use lane-specific sections: product truth says what must be true and why; engineering truth says how the repository currently realizes it. Teams may edit template files under the configured Truthmark templates root to define their local truth-doc standards. Truth-doc shape repair gate: - Truth Document may restructure only truth docs for the implemented behavior being documented. @@ -63,10 +74,11 @@ Truthmark hierarchy hints: - Config, when present: .truthmark/config.yml - Root route index, when present: docs/truthmark/routes/areas.md - Area route files, when present: docs/truthmark/routes/areas/**/*.md -- Truth docs, when present: docs/truthmark/truth/**/*.md +- Product truth docs, when present: docs/truthmark/product/**/*.md +- Engineering truth docs, when present: docs/truthmark/engineering/**/*.md Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. -Update Product Decisions and Rationale when a decision changes behavior. +Product decisions belong in product truth; engineering, architecture, contract, workflow, and operational decisions belong in engineering truth. Helper status reporting: - Validate the report body before adding this validator's own success status; the body may omit `validate-document-report` while validation is pending. - After `truthmark validate document-report --json` returns `data.validation.ok: true`, append or update `validate-document-report: ran, passed` in the final report. diff --git a/.agents/skills/truthmark-document/support/report-template.md b/.agents/skills/truthmark-document/support/report-template.md index 5e38b92..ae3ce4c 100644 --- a/.agents/skills/truthmark-document/support/report-template.md +++ b/.agents/skills/truthmark-document/support/report-template.md @@ -1,6 +1,6 @@ # Truthmark Document Report Template -Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. Report completion in this shape: ```md @@ -13,13 +13,13 @@ Ownership reviewed: - docs/truthmark/routes/areas.md Truth docs created: -- docs/truthmark/truth/contracts.md +- docs/truthmark/engineering/contracts/routing.md Truth docs updated: -- docs/truthmark/truth/check-diagnostics.md +- docs/truthmark/engineering/behaviors/check-diagnostics.md Truth docs restructured: -- docs/truthmark/truth/check-diagnostics.md +- docs/truthmark/engineering/behaviors/check-diagnostics.md Routing updated: - docs/truthmark/routes/areas.md diff --git a/.agents/skills/truthmark-document/support/subagents-and-leases.md b/.agents/skills/truthmark-document/support/subagents-and-leases.md index b15fea1..50de94b 100644 --- a/.agents/skills/truthmark-document/support/subagents-and-leases.md +++ b/.agents/skills/truthmark-document/support/subagents-and-leases.md @@ -1,6 +1,6 @@ # Truthmark Document Subagents And Leases -Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. Codex subagent mode: - use automatically when this workflow runs in Codex and the parent agent chooses bounded subagent fan-out diff --git a/.agents/skills/truthmark-portal/SKILL.md b/.agents/skills/truthmark-portal/SKILL.md index e8ace3c..2aa77d0 100644 --- a/.agents/skills/truthmark-portal/SKILL.md +++ b/.agents/skills/truthmark-portal/SKILL.md @@ -3,7 +3,7 @@ name: truthmark-portal description: Use when the user explicitly asks to generate, refresh, or update the Truthmark Portal static HTML site. Not for code change sync, route repair, truth validation/checking, documenting behavior, realizing docs into code, or machine-readable agent context. argument-hint: Optional portal generation focus user-invocable: true -truthmark-version: 2.1.0 +truthmark-version: 2.2.1 --- # Truthmark Portal diff --git a/.agents/skills/truthmark-portal/agents/openai.yaml b/.agents/skills/truthmark-portal/agents/openai.yaml index e8501e1..af506c4 100644 --- a/.agents/skills/truthmark-portal/agents/openai.yaml +++ b/.agents/skills/truthmark-portal/agents/openai.yaml @@ -7,5 +7,5 @@ policy: allow_implicit_invocation: false truthmark: - version: "2.1.0" + version: "2.2.1" refresh_command: "truthmark init" diff --git a/.agents/skills/truthmark-portal/support/procedure.md b/.agents/skills/truthmark-portal/support/procedure.md index 89d5c39..671435b 100644 --- a/.agents/skills/truthmark-portal/support/procedure.md +++ b/.agents/skills/truthmark-portal/support/procedure.md @@ -1,6 +1,6 @@ # Truthmark Portal Procedure -Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. # Truthmark Portal @@ -37,4 +37,5 @@ Truthmark hierarchy hints: - Config, when present: .truthmark/config.yml - Root route index, when present: docs/truthmark/routes/areas.md - Area route files, when present: docs/truthmark/routes/areas/**/*.md -- Truth docs, when present: docs/truthmark/truth/**/*.md +- Product truth docs, when present: docs/truthmark/product/**/*.md +- Engineering truth docs, when present: docs/truthmark/engineering/**/*.md diff --git a/.agents/skills/truthmark-portal/support/report-template.md b/.agents/skills/truthmark-portal/support/report-template.md index bd2d23d..ec72660 100644 --- a/.agents/skills/truthmark-portal/support/report-template.md +++ b/.agents/skills/truthmark-portal/support/report-template.md @@ -1,6 +1,6 @@ # Truthmark Portal Report Template -Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. Report completion in this shape: diff --git a/.agents/skills/truthmark-preview/SKILL.md b/.agents/skills/truthmark-preview/SKILL.md index 7db8d92..5a8a993 100644 --- a/.agents/skills/truthmark-preview/SKILL.md +++ b/.agents/skills/truthmark-preview/SKILL.md @@ -3,7 +3,7 @@ name: truthmark-preview description: Use when the user explicitly asks to preview likely workflow routing, target files, writes, or subagent use before edits. Not for validation, automatic gates, final correctness, or replacing Truth Check. argument-hint: Optional requested outcome, code area, doc path, or routing question user-invocable: true -truthmark-version: 2.1.0 +truthmark-version: 2.2.1 --- # Truthmark Preview @@ -14,7 +14,7 @@ Invocations: OpenCode /skill truthmark-preview; Codex /truthmark-preview or $tru Quick procedure: - Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists. -- Inspect .truthmark/config.yml and configured route files (docs/truthmark/routes/areas.md; docs/truthmark/routes/areas/) only when they exist; then inspect only the truth docs or implementation files needed to preview ownership. +- Inspect .truthmark/config.yml and the root route index (docs/truthmark/routes/areas.md) first when present; then inspect only child route files under docs/truthmark/routes/areas/ that are relevant to the selected scope or changed paths, plus the truth docs or implementation files needed to preview ownership. - Truth Preview is read-only; this report is intended, not authorized. - must not edit files and must not issue write leases; do not run Truth Sync automatically, replace Truth Check, claim final correctness, or mutate code. - Use optional read-only route-auditor evidence only when it reduces context or clarifies ownership. diff --git a/.agents/skills/truthmark-preview/agents/openai.yaml b/.agents/skills/truthmark-preview/agents/openai.yaml index fc75934..99e6561 100644 --- a/.agents/skills/truthmark-preview/agents/openai.yaml +++ b/.agents/skills/truthmark-preview/agents/openai.yaml @@ -7,5 +7,5 @@ policy: allow_implicit_invocation: false truthmark: - version: "2.1.0" + version: "2.2.1" refresh_command: "truthmark init" diff --git a/.agents/skills/truthmark-preview/support/procedure.md b/.agents/skills/truthmark-preview/support/procedure.md index 276926b..5d608e9 100644 --- a/.agents/skills/truthmark-preview/support/procedure.md +++ b/.agents/skills/truthmark-preview/support/procedure.md @@ -1,6 +1,6 @@ # Truthmark Preview Procedure -Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. Use this skill only when the user explicitly asks to preview Truthmark routing or workflow choice before edits. @@ -10,16 +10,25 @@ Truth Preview is read-only. Its report is intended, not authorized. Purpose: - preview the likely Truthmark workflow, route owner, target files, expected write classes, suggested subagent use, and blocking ambiguity before edits happen +- report likely product lane impact, engineering lane impact, target docs, and ambiguity before edits - hand off to the selected workflow after user approval - keep the selector thin so agents can avoid loading or acting through heavier workflows prematurely Read: - .truthmark/config.yml, only when present -- docs/truthmark/routes/areas.md, only when present -- relevant child route files under docs/truthmark/routes/areas/, only when present +- docs/truthmark/routes/areas.md, first, only when present +- relevant child route files under docs/truthmark/routes/areas/ for the selected scope or changed paths, only when present - relevant truth docs and implementation files needed to preview ownership -- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. -Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. +- Evidence authority: + - Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. + - Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. +- Lane classification: + - classify the request or changed surface as product-lane, engineering-lane, both-lane, or ambiguous for reporting only + - product-lane ownership belongs under docs/truthmark/product and describes product promises, boundaries, rationale, decisions, and success criteria + - engineering-lane ownership belongs under docs/truthmark/engineering and describes source-backed current realization, contracts, architecture, workflows, operations, or tests + - both-lane ownership uses separate product and engineering docs cross-linked in route YAML with realized_by and realizes, not in doc frontmatter + - ambiguous lane ownership should be reported as blocked or routed to Truth Structure + - Do not make product docs a summary of engineering docs. Do not make engineering docs a detailed version of product docs. Product truth says what must be true and why. Engineering truth says how the repository currently realizes it. Do not: - must not edit files @@ -40,4 +49,5 @@ Truthmark hierarchy hints: - Config, when present: .truthmark/config.yml - Root route index, when present: docs/truthmark/routes/areas.md - Area route files, when present: docs/truthmark/routes/areas/**/*.md -- Truth docs, when present: docs/truthmark/truth/**/*.md +- Product truth docs, when present: docs/truthmark/product/**/*.md +- Engineering truth docs, when present: docs/truthmark/engineering/**/*.md diff --git a/.agents/skills/truthmark-preview/support/report-template.md b/.agents/skills/truthmark-preview/support/report-template.md index bff96a9..9e697be 100644 --- a/.agents/skills/truthmark-preview/support/report-template.md +++ b/.agents/skills/truthmark-preview/support/report-template.md @@ -1,6 +1,6 @@ # Truthmark Preview Report Template -Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. Report completion in this shape: ```md @@ -19,14 +19,16 @@ Why this workflow: Likely route owner: - route file: docs/truthmark/routes/areas.md -- truth doc: docs/truthmark/truth/example.md +- likely lane impact: engineering-lane +- product target docs: none identified +- engineering target docs: docs/truthmark/engineering/behaviors/example.md - confidence: medium Expected write classes: - truth docs Expected target files: -- docs/truthmark/truth/example.md +- docs/truthmark/engineering/behaviors/example.md Suggested subagent use: - read-only verifiers: truth_route_auditor diff --git a/.agents/skills/truthmark-preview/support/subagents-and-leases.md b/.agents/skills/truthmark-preview/support/subagents-and-leases.md index 0b91ede..08c81ce 100644 --- a/.agents/skills/truthmark-preview/support/subagents-and-leases.md +++ b/.agents/skills/truthmark-preview/support/subagents-and-leases.md @@ -1,6 +1,6 @@ # Truthmark Preview Subagents And Leases -Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. Codex subagent mode: - use automatically when this workflow runs in Codex and the parent agent chooses bounded subagent fan-out diff --git a/.agents/skills/truthmark-realize/SKILL.md b/.agents/skills/truthmark-realize/SKILL.md index 8256b8e..bcf5912 100644 --- a/.agents/skills/truthmark-realize/SKILL.md +++ b/.agents/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. Not for syncing docs after code changes, documenting existing code, topology repair, or truth audits. argument-hint: Optional truth doc path, area, or desired code behavior to realize user-invocable: true -truthmark-version: 2.1.0 +truthmark-version: 2.2.1 --- # Truthmark Realize diff --git a/.agents/skills/truthmark-realize/agents/openai.yaml b/.agents/skills/truthmark-realize/agents/openai.yaml index b5bbffa..9710c28 100644 --- a/.agents/skills/truthmark-realize/agents/openai.yaml +++ b/.agents/skills/truthmark-realize/agents/openai.yaml @@ -7,5 +7,5 @@ policy: allow_implicit_invocation: false truthmark: - version: "2.1.0" + version: "2.2.1" refresh_command: "truthmark init" diff --git a/.agents/skills/truthmark-realize/support/procedure.md b/.agents/skills/truthmark-realize/support/procedure.md index c419a77..bc86afe 100644 --- a/.agents/skills/truthmark-realize/support/procedure.md +++ b/.agents/skills/truthmark-realize/support/procedure.md @@ -1,6 +1,6 @@ # Truthmark Realize Procedure -Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. # Truthmark Realize @@ -33,7 +33,8 @@ Truthmark hierarchy hints: - Config, when present: .truthmark/config.yml - Root route index, when present: docs/truthmark/routes/areas.md - Area route files, when present: docs/truthmark/routes/areas/**/*.md -- Truth docs, when present: docs/truthmark/truth/**/*.md +- Product truth docs, when present: docs/truthmark/product/**/*.md +- Engineering truth docs, when present: docs/truthmark/engineering/**/*.md Read and write boundaries: diff --git a/.agents/skills/truthmark-realize/support/report-template.md b/.agents/skills/truthmark-realize/support/report-template.md index b540f61..4e55a01 100644 --- a/.agents/skills/truthmark-realize/support/report-template.md +++ b/.agents/skills/truthmark-realize/support/report-template.md @@ -1,6 +1,6 @@ # Truthmark Realize Report Template -Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. Report completion in this shape: @@ -8,7 +8,8 @@ Report completion in this shape: Truth Realize: completed Truth docs used: -- docs/truthmark/truth/authentication/session-timeout.md +- docs/truthmark/product/capabilities/authentication-session.md +- docs/truthmark/engineering/behaviors/authentication-session.md Code updated: - src/auth/session.ts diff --git a/.agents/skills/truthmark-structure/SKILL.md b/.agents/skills/truthmark-structure/SKILL.md index 4e0d2ab..01b08c6 100644 --- a/.agents/skills/truthmark-structure/SKILL.md +++ b/.agents/skills/truthmark-structure/SKILL.md @@ -3,7 +3,7 @@ name: truthmark-structure description: Use when routing or truth ownership is missing, stale, broad, overloaded, catch-all, unrouteable, mixed-owner, needs split/repair, or needs new area setup. Not for documenting implemented behavior, syncing a code diff, or realizing docs into code. argument-hint: Optional area, directory, or routing concern user-invocable: true -truthmark-version: 2.1.0 +truthmark-version: 2.2.1 --- # Truthmark Structure diff --git a/.agents/skills/truthmark-structure/agents/openai.yaml b/.agents/skills/truthmark-structure/agents/openai.yaml index 3e5ec08..7e22cda 100644 --- a/.agents/skills/truthmark-structure/agents/openai.yaml +++ b/.agents/skills/truthmark-structure/agents/openai.yaml @@ -7,5 +7,5 @@ policy: allow_implicit_invocation: false truthmark: - version: "2.1.0" + version: "2.2.1" refresh_command: "truthmark init" diff --git a/.agents/skills/truthmark-structure/support/procedure.md b/.agents/skills/truthmark-structure/support/procedure.md index 5112d6e..1588ce5 100644 --- a/.agents/skills/truthmark-structure/support/procedure.md +++ b/.agents/skills/truthmark-structure/support/procedure.md @@ -1,29 +1,38 @@ # Truthmark Structure Procedure -Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. Use this skill to design or repair Truthmark area structure. Invocations: OpenCode /skill truthmark-structure; Codex /truthmark-structure or $truthmark-structure; Claude Code /truthmark-structure; GitHub Copilot /truthmark-structure; Gemini CLI /truthmark:structure. Truth Structure is agent-native: - inspect repository layout, current docs, Truthmark config and route files when present, and relevant code directly -- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. -Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. +- Evidence authority: + - Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. + - Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. +- Lane classification: + - before writing canonical truth docs, classify the request or change as product-lane, engineering-lane, both-lane, or ambiguous + - product-lane writes belong under docs/truthmark/product and state product promises, boundaries, rationale, decisions, and success criteria + - engineering-lane writes belong under docs/truthmark/engineering and state source-backed current realization, contracts, architecture, workflows, operations, or tests + - both-lane work must write separate product and engineering docs and cross-link them in route YAML with realized_by and realizes, not in doc frontmatter + - ambiguous lane ownership must block or invoke Truth Structure instead of writing a mixed document + - Do not make product docs a summary of engineering docs. Do not make engineering docs a detailed version of product docs. Product truth says what must be true and why. Engineering truth says how the repository currently realizes it. - inspect the configured root route index at docs/truthmark/routes/areas.md and relevant child route files under docs/truthmark/routes/areas/ when they exist - define areas by product or behavior ownership, not by mechanical directory mirroring - create or repair docs/truthmark/routes/areas.md - create starter truth docs when useful and when they belong in the canonical current-truth surface -- Starter truth docs must use closed YAML frontmatter bounded by opening and closing --- lines; include status, doc_type, last_reviewed, and source_of_truth inside that frontmatter. -- Starter truth docs must include ## Product Decisions and ## Rationale sections. +- Starter truth docs must use closed YAML frontmatter bounded by opening and closing --- lines; include status, truth_kind, and last_reviewed inside that frontmatter. Put source references in the final ## Source References section, not in frontmatter. +- Starter truth docs must use lane-specific templates and keep product and engineering truth in separate files. When creating or updating a truth doc, inspect the routed truth kind and use the matching template under the configured Truthmark templates root. -Supported kinds: behavior, contract, architecture, workflow, operations, and test-behavior. +Supported kinds: product-capability, engineering-behavior, engineering-contract, engineering-architecture, engineering-workflow, engineering-operations, and engineering-test-behavior. Treat the HTML comments under each template section as normative authoring guidance for that section. Align existing docs to that template and write or repair section content so it satisfies the comment guidance while preserving accurate authored content. -If the template is missing, use Scope, Product Decisions, Rationale, and the kind-specific current-truth section. +If the template is missing, use lane-specific sections: product truth says what must be true and why; engineering truth says how the repository currently realizes it. Teams may edit template files under the configured Truthmark templates root to define their local truth-doc standards. -- use docs/truthmark/truth/** for current truth destinations +- use docs/truthmark/product/** for product truth destinations +- use docs/truthmark/engineering/** for engineering truth destinations - use only canonical current-truth destinations for starter truth docs -- keep active Product Decisions and Rationale in the canonical doc that owns the behavior +- keep active Product Decisions in product truth and Engineering Decisions in engineering truth - preserve unrelated authored content ## New area setup Use when a user asks to onboard a new code area into Truthmark, a new package, controller, domain, or product area lacks bounded truth ownership, or a new product area needs routing and starter truth docs. @@ -41,7 +50,7 @@ Do not: - do not create generic catch-all docs - do not treat README files as Sync targets ## Topology Governance -Truth Structure owns documentation topology. Do not depend on humans to manually organize docs/truthmark/truth. Treat the configured truth root as a managed semantic root. +Truth Structure owns documentation topology, lane splits, decision relocation, and relationship repair. Do not depend on humans to manually organize docs/truthmark/product or docs/truthmark/engineering. Treat both configured lane roots as managed semantic roots. Inspect controllers, routes, handlers, services, packages, tests, existing truth docs, and route files; infer product and domain ownership from behavior boundaries, not from mechanical directory mirroring. When topology pressure exists, repair structure before creating or extending truth docs. Truth-doc ownership gate: @@ -49,17 +58,17 @@ Truth-doc ownership gate: - if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it - if a truth doc mixes independent owners, route ownership is broad, or a split is required for bounded ownership, split and reroute into bounded truth docs when safe; otherwise block with manual-review files - report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Blocked reason as applicable -Product Decisions/Rationale preservation gate: -- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions and Rationale sections in every source or touched truth doc -- preserve each current decision and rationale in the bounded owner doc it governs; when splitting, move it to the new owner doc rather than deleting it or leaving it in an index +Decision/Rationale preservation gate: +- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions, Engineering Decisions, and Rationale sections in every source or touched truth doc +- preserve each current decision and rationale in the correct product or engineering lane owner; when splitting, move it to the new owner doc rather than deleting it or leaving it in an index - remove or narrow a decision or rationale only when checkout evidence shows it is stale or unsupported, and report the exact claim, evidence, and result - if ownership of a decision or rationale is unclear, block with manual-review files instead of deleting it or guessing -- after the edit, verify every touched truth doc still has Product Decisions and Rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked +- after the edit, verify every touched truth doc keeps lane-appropriate decision/rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked Topology pressure signals: - one area maps broad code such as src/**, app/**, server/**, services/**, or packages/** - one area maps multiple unrelated controllers, route groups, services, or bounded contexts - one truth doc owns unrelated behaviors or unrelated endpoint families -- the configured truth root has many direct non-index docs +- either configured lane root has many direct non-index docs - a changed controller, route, or service cannot map to a specific behavior doc - Truth Sync would need to create a new generic truth doc because routing is too broad - endpoint or controller names reveal domains missing from docs/truthmark/routes/areas/** @@ -72,9 +81,10 @@ Repair rules: - split broad, overloaded, or catch-all areas into behavior-owned child route files - split mixed-owner truth docs into bounded owner docs before adding new behavior claims - create route files under docs/truthmark/routes/areas/ when a product/domain boundary is clear -- create behavior truth docs under the configured truth root only when behavior lacks a current doc +- create engineering behavior truth docs under docs/truthmark/engineering only when behavior lacks a current doc +- create product truth docs under docs/truthmark/product only when product promise, boundary, rationale, or user-visible capability truth is in scope - README.md files are indexes, not Truth Sync targets -- prefer bounded leaf truth docs at //.md +- prefer bounded product docs under product/capabilities or product/decisions and engineering docs under engineering//.md - keep behavior truth docs behavior-oriented, not endpoint-oriented - keep API endpoint details in the nearest contract truth doc when such a doc exists - update routing so future Truth Sync can target small docs @@ -88,13 +98,13 @@ Truth-doc shape repair gate: - preserve supported claims; remove, narrow, or block unsupported or stale claims - report docs restructured and why a narrow edit was not sufficient Evidence Gate: -- apply the Evidence Gate before finishing when Truth Structure writes routed docs, ownership claims, Product Decisions, or Rationale +- apply the Evidence Gate before finishing when Truth Structure writes routed docs, ownership claims, lane-specific decisions, or rationale - support ownership/behavior claims with topology or primary checkout evidence from layout, implementation boundaries, docs, config, route files, tests, templates, schemas, or contracts - tests/examples/canonical docs corroborate; remove, narrow, or block unsupported claims Maintain architecture docs only for structure-level changes: system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership. Keep ordinary behavior, endpoints, UI copy, validation rules, and bug fixes in behavior or contract docs unless they change those boundaries. -- Do not finish topology repair with routed canonical current-truth docs missing Product Decisions or Rationale sections. -- If an existing canonical doc lacks either section, add the missing heading beside Current Behavior with a concise current-state placeholder or active decision. +- Do not finish topology repair with mixed product/engineering authority in a single canonical truth doc. +- If an existing canonical doc has wrong-lane sections, split or move them into the correct product or engineering lane. Portable fallback: - If this skill surface is unavailable, perform the same workflow directly from committed repository files. - Do not require the truthmark CLI. @@ -104,7 +114,8 @@ Truthmark hierarchy hints: - Config, when present: .truthmark/config.yml - Root route index, when present: docs/truthmark/routes/areas.md - Area route files, when present: docs/truthmark/routes/areas/**/*.md -- Truth docs, when present: docs/truthmark/truth/**/*.md +- Product truth docs, when present: docs/truthmark/product/**/*.md +- Engineering truth docs, when present: docs/truthmark/engineering/**/*.md Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. -Update Product Decisions and Rationale when a decision changes behavior. +Product decisions belong in product truth; engineering, architecture, contract, workflow, and operational decisions belong in engineering truth. diff --git a/.agents/skills/truthmark-structure/support/report-template.md b/.agents/skills/truthmark-structure/support/report-template.md index 1be260b..5dc74e8 100644 --- a/.agents/skills/truthmark-structure/support/report-template.md +++ b/.agents/skills/truthmark-structure/support/report-template.md @@ -1,13 +1,14 @@ # Truthmark Structure Report Template -Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. Report completion in this shape: ```md Truth Structure: completed Topology reviewed: - controllers: src/auth/** -- docs root: docs/truthmark/truth +- product docs root: docs/truthmark/product +- engineering docs root: docs/truthmark/engineering - route files: docs/truthmark/routes/areas.md Areas reviewed: - src/auth/** @@ -16,12 +17,14 @@ Routing updated: Initial truth boundary: - Area: Authentication - Code: src/auth/** -- Truth owner: docs/truthmark/truth/authentication/session.md +- Product owner: docs/truthmark/product/capabilities/authentication-session.md +- Engineering owner: docs/truthmark/engineering/behaviors/authentication-session.md - Scope: session behavior only Truth docs created: -- docs/truthmark/truth/authentication/session.md +- docs/truthmark/product/capabilities/authentication-session.md +- docs/truthmark/engineering/behaviors/authentication-session.md Truth docs split: -- docs/truthmark/truth/authentication/README.md -> docs/truthmark/truth/authentication/session.md +- docs/truthmark/truth/authentication/README.md -> docs/truthmark/product/capabilities/authentication-session.md and docs/truthmark/engineering/behaviors/authentication-session.md Truth docs restructured: - docs/truthmark/truth/authentication/README.md Evidence checked: diff --git a/.agents/skills/truthmark-structure/support/subagents-and-leases.md b/.agents/skills/truthmark-structure/support/subagents-and-leases.md index a5b4f52..5fd0e5c 100644 --- a/.agents/skills/truthmark-structure/support/subagents-and-leases.md +++ b/.agents/skills/truthmark-structure/support/subagents-and-leases.md @@ -1,6 +1,6 @@ # Truthmark Structure Subagents And Leases -Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. Codex subagent mode: - use automatically when this workflow runs in Codex and the parent agent chooses bounded subagent fan-out diff --git a/.agents/skills/truthmark-sync/SKILL.md b/.agents/skills/truthmark-sync/SKILL.md index ff1d4eb..47b6826 100644 --- a/.agents/skills/truthmark-sync/SKILL.md +++ b/.agents/skills/truthmark-sync/SKILL.md @@ -3,7 +3,7 @@ name: truthmark-sync description: Use automatically at finish-time after functional code changes, or explicit /truthmark-sync, $truthmark-sync, or /truthmark:sync. Skip docs-only, formatting-only, behavior-preserving renames, missing config, and no-code changes. Not for doc-first realization or manual topology design. argument-hint: Optional changed-code area, truth-doc area, or sync focus user-invocable: true -truthmark-version: 2.1.0 +truthmark-version: 2.2.1 --- # Truthmark Sync diff --git a/.agents/skills/truthmark-sync/agents/openai.yaml b/.agents/skills/truthmark-sync/agents/openai.yaml index acb82ec..e9dbc24 100644 --- a/.agents/skills/truthmark-sync/agents/openai.yaml +++ b/.agents/skills/truthmark-sync/agents/openai.yaml @@ -7,5 +7,5 @@ policy: allow_implicit_invocation: true truthmark: - version: "2.1.0" + version: "2.2.1" refresh_command: "truthmark init" diff --git a/.agents/skills/truthmark-sync/helper-manifest.yml b/.agents/skills/truthmark-sync/helper-manifest.yml index dd0153a..36c0434 100644 --- a/.agents/skills/truthmark-sync/helper-manifest.yml +++ b/.agents/skills/truthmark-sync/helper-manifest.yml @@ -1,8 +1,8 @@ -# Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +# Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. helpers: validate-sync-report: optional: true - runner: truthmark>=2.1.0 + runner: truthmark>=2.2.1 command: argv: - truthmark @@ -17,7 +17,7 @@ helpers: fallback: "manually validate support/report-template.md and check Evidence checked entries match Claim, indented Evidence, and Result: supported | narrowed | removed | blocked" validate-write-lease: optional: true - runner: truthmark>=2.1.0 + runner: truthmark>=2.2.1 command: argv: - truthmark diff --git a/.agents/skills/truthmark-sync/support/helper-policy.md b/.agents/skills/truthmark-sync/support/helper-policy.md index 6c44128..d1831d6 100644 --- a/.agents/skills/truthmark-sync/support/helper-policy.md +++ b/.agents/skills/truthmark-sync/support/helper-policy.md @@ -1,6 +1,6 @@ # Optional Helper CLI Policy -Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. Optional helper CLI commands may collect deterministic checkout facts or validate artifacts. If the Truthmark CLI is unavailable or too old for a declared helper, continue manually using this procedure and report which helper was skipped. Helper output is derived evidence; it does not override direct checkout inspection, workflow write boundaries, or parent acceptance. @@ -11,8 +11,8 @@ Runner detection: - Do not fail the workflow solely because a helper cannot run. Available helpers: -- validate-sync-report: optional truthmark>=2.1.0; manual fallback: manually validate support/report-template.md and check Evidence checked entries match Claim, indented Evidence, and Result: supported | narrowed | removed | blocked -- validate-write-lease: optional truthmark>=2.1.0; manual fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files +- validate-sync-report: optional truthmark>=2.2.1; manual fallback: manually validate support/report-template.md and check Evidence checked entries match Claim, indented Evidence, and Result: supported | narrowed | removed | blocked +- validate-write-lease: optional truthmark>=2.2.1; manual fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files Final reports should include helper status when helpers are declared for this workflow: diff --git a/.agents/skills/truthmark-sync/support/procedure.md b/.agents/skills/truthmark-sync/support/procedure.md index ff0f6f7..6270aab 100644 --- a/.agents/skills/truthmark-sync/support/procedure.md +++ b/.agents/skills/truthmark-sync/support/procedure.md @@ -1,6 +1,6 @@ # Truthmark Sync Procedure -Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. Use this skill automatically before finishing when functional code changed since the last successful Truth Sync. Also run it immediately when the user explicitly invokes Truth Sync. Invocations: OpenCode /skill truthmark-sync; Codex /truthmark-sync or $truthmark-sync; Claude Code /truthmark-sync; GitHub Copilot /truthmark-sync; Gemini CLI /truthmark:sync. @@ -10,10 +10,19 @@ Parent workflow: 1. Inspect git status, staged changes, unstaged changes, and untracked files directly. 2. Inspect .truthmark/config.yml and configured route files only when they exist; then inspect relevant canonical docs. 3. Identify functional-code changes and the nearest truth docs or routing repairs. -4. Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. -Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. -5. Code verification is parent-owned: follow repository instructions and task context, and report what ran or why it did not run. -6. Dispatch bounded Truth Sync workers only when the host supports subagent dispatch and the acting agent chooses that path; otherwise execute the same sync task inline. +4. Evidence authority: + - Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. + - Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. +5. Lane classification gate: + - before writing canonical truth docs, classify the request or change as product-lane, engineering-lane, both-lane, or ambiguous + - product-lane writes belong under docs/truthmark/product and state product promises, boundaries, rationale, decisions, and success criteria + - engineering-lane writes belong under docs/truthmark/engineering and state source-backed current realization, contracts, architecture, workflows, operations, or tests + - both-lane work must write separate product and engineering docs and cross-link them in route YAML with realized_by and realizes, not in doc frontmatter + - ambiguous lane ownership must block or invoke Truth Structure instead of writing a mixed document + - Do not make product docs a summary of engineering docs. Do not make engineering docs a detailed version of product docs. Product truth says what must be true and why. Engineering truth says how the repository currently realizes it. +6. Update engineering truth first after code changes. Update product truth only when implemented user-visible product promise or capability boundary changed and explicit source/user evidence supports it; otherwise report product-lane review needed. +7. Code verification is parent-owned: follow repository instructions and task context, and report what ran or why it did not run. +8. Dispatch bounded Truth Sync workers only when the host supports subagent dispatch and the acting agent chooses that path; otherwise execute the same sync task inline. Topology quality gate: - before updating truth docs, verify the changed code resolves to a specific behavior-owned area and bounded truth owner - if routing is missing, stale, broad, overloaded, catch-all route only, or cannot map changed code to a bounded truth owner, do not create another generic truth doc @@ -23,25 +32,26 @@ Topology quality gate: - README.md files are indexes, not Truth Sync targets - must not append behavior details to a README.md index - create or update a bounded leaf truth doc when behavior changes do not fit an existing leaf doc +- write engineering truth under docs/truthmark/engineering; product truth updates under docs/truthmark/product are allowed only for explicit current product behavior changes Truth-doc ownership gate: - before editing or relying on changed functional files and impacted truth docs, verify each target/source truth doc is a bounded owner for the behavior - if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it - if an impacted doc is broad, mixed-owner, index-like, or the update spans independent behavior owners, run Truth Structure before syncing when safe and in scope; otherwise block and recommend Truth Structure - report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Blocked reason as applicable -Product Decisions/Rationale preservation gate: -- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions and Rationale sections in every source or touched truth doc -- preserve each current decision and rationale in the bounded owner doc it governs; when splitting, move it to the new owner doc rather than deleting it or leaving it in an index +Decision/Rationale preservation gate: +- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions, Engineering Decisions, and Rationale sections in every source or touched truth doc +- preserve each current decision and rationale in the correct product or engineering lane owner; when splitting, move it to the new owner doc rather than deleting it or leaving it in an index - remove or narrow a decision or rationale only when checkout evidence shows it is stale or unsupported, and report the exact claim, evidence, and result - if ownership of a decision or rationale is unclear, block with manual-review files instead of deleting it or guessing -- after the edit, verify every touched truth doc still has Product Decisions and Rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked +- after the edit, verify every touched truth doc keeps lane-appropriate decision/rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked When creating or updating a truth doc, inspect the routed truth kind and use the matching template under the configured Truthmark templates root. -Supported kinds: behavior, contract, architecture, workflow, operations, and test-behavior. +Supported kinds: product-capability, engineering-behavior, engineering-contract, engineering-architecture, engineering-workflow, engineering-operations, and engineering-test-behavior. Treat the HTML comments under each template section as normative authoring guidance for that section. Align existing docs to that template and write or repair section content so it satisfies the comment guidance while preserving accurate authored content. -If the template is missing, use Scope, Product Decisions, Rationale, and the kind-specific current-truth section. +If the template is missing, use lane-specific sections: product truth says what must be true and why; engineering truth says how the repository currently realizes it. Teams may edit template files under the configured Truthmark templates root to define their local truth-doc standards. Truth-doc shape repair gate: -- Truth Sync may restructure only truth docs impacted by the current functional-code change. +- Truth Sync may restructure leased canonical truth docs when the current sync evidence shows repository truth is stale, even when the doc is outside the initially affected route focus. - repair shape in place only after the ownership gate confirms the doc is the right bounded owner - use Truth Structure for ownership splits; do not treat broad or mixed-owner docs as in-place repair work - repair shape when a narrow edit would make truth worse: missing template sections, stale evidence conflicts, cross-section updates within one owner, or wrong frontmatter/source/headings @@ -51,19 +61,19 @@ Maintain architecture docs only for structure-level changes: system structure, m Keep ordinary behavior, endpoints, UI copy, validation rules, and bug fixes in behavior or contract docs unless they change those boundaries. Evidence Gate: - route-first: map changed functional files to bounded route owners and primary canonical docs -- review new or changed behavior-bearing claims only in touched docs, route ownership, Product Decisions, and Rationale +- review new or changed behavior-bearing claims only in touched docs, route ownership, lane-specific decisions, and rationale - support claims with primary checkout evidence: implementation, config, routing, generated templates, schemas, or contract definitions - tests/examples/canonical docs corroborate; they are not sole proof when implementation conflicts - remove, narrow, or block unsupported claims - if no impacted doc changed, report why truth was already current or why sync was skipped -Repository intelligence artifacts are optional derived context: RepoIndex, RouteMap, ImpactSet, and ContextPack may guide routing, context selection, and verification planning when available. +Repository intelligence artifacts are optional derived context: RepoIndex, RouteMap, ImpactSet, and WorkflowState/action context may guide routing, write boundaries, and verification planning when available. They do not override checkout evidence, canonical truth docs, route files, or workflow write boundaries. If unavailable, inspect any present Truthmark config, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated. Optional validation tooling: - you may run truthmark check when local tooling is available - do not require the truthmark binary; direct checkout inspection is the canonical path - optional validation must not replace agent judgment about docs and routing -- update Product Decisions and Rationale when a behavior change comes from a decision change +- update Product Decisions only in product truth and Engineering Decisions only in engineering truth when evidence supports the lane-specific decision change Helper status reporting: - Validate the report body before adding this validator's own success status; the body may omit `validate-sync-report` while validation is pending. - After `truthmark validate sync-report --json` returns `data.validation.ok: true`, append or update `validate-sync-report: ran, passed` in the final report. @@ -74,16 +84,17 @@ Truthmark hierarchy hints: - Config, when present: .truthmark/config.yml - Root route index, when present: docs/truthmark/routes/areas.md - Area route files, when present: docs/truthmark/routes/areas/**/*.md -- Truth docs, when present: docs/truthmark/truth/**/*.md +- Product truth docs, when present: docs/truthmark/product/**/*.md +- Engineering truth docs, when present: docs/truthmark/engineering/**/*.md Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. -Update Product Decisions and Rationale when a decision changes behavior. +Product decisions belong in product truth; engineering, architecture, contract, workflow, and operational decisions belong in engineering truth. Parent post-sync verification: - verify only truth docs and leased truth routing files changed during sync - block on any unrelated diff caused by the sync step - block if functional code changed during sync - for each write lease, validate the worker report against the actual worker diff, allowedWrites, forbiddenWrites, identity fields, filesChanged, offLeaseChanges, blockers, and required report fields before accepting it - validate the final report against the structured Truth Sync report contract, including Claim, indented Evidence, and Result values supported, narrowed, removed, or blocked under Evidence checked -- verify the updated docs correspond to the reviewed changed-code surface +- verify the updated docs correspond to reviewed checkout evidence, changed-code impact, or a recorded stale-truth correction made within the sync write lease - verify the final report records ownership review, structure requirement, split, restructure, or blocked reason when the ownership gate fired - blocked outcomes must preserve the working tree as-is: no rollback, no post-block cleanup edits, and manual-review reporting of any remaining files diff --git a/.agents/skills/truthmark-sync/support/report-template.md b/.agents/skills/truthmark-sync/support/report-template.md index 4dfa42d..52f0ec1 100644 --- a/.agents/skills/truthmark-sync/support/report-template.md +++ b/.agents/skills/truthmark-sync/support/report-template.md @@ -1,6 +1,6 @@ # Truthmark Sync Report Template -Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. Report completion in this shape: ```md @@ -13,7 +13,7 @@ Ownership reviewed: - docs/truthmark/routes/areas.md Truth docs updated: -- docs/truthmark/truth/repository/overview.md +- docs/truthmark/engineering/repository/overview.md Evidence checked: - Claim: Session timeout behavior is documented in the mapped repository truth doc. diff --git a/.agents/skills/truthmark-sync/support/subagents-and-leases.md b/.agents/skills/truthmark-sync/support/subagents-and-leases.md index d29ded4..4884d81 100644 --- a/.agents/skills/truthmark-sync/support/subagents-and-leases.md +++ b/.agents/skills/truthmark-sync/support/subagents-and-leases.md @@ -1,6 +1,6 @@ # Truthmark Sync Subagents And Leases -Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. Codex subagent mode: - use automatically when this workflow runs in Codex and the parent agent chooses bounded subagent fan-out diff --git a/.codex/agents/truth-claim-verifier.toml b/.codex/agents/truth-claim-verifier.toml index 3ca3986..0acb30b 100644 --- a/.codex/agents/truth-claim-verifier.toml +++ b/.codex/agents/truth-claim-verifier.toml @@ -1,4 +1,4 @@ -# Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +# Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. name = "truth_claim_verifier" description = "Read-only Truthmark claim verifier for checking canonical truth against checkout evidence." sandbox_mode = "read-only" diff --git a/.codex/agents/truth-doc-reviewer.toml b/.codex/agents/truth-doc-reviewer.toml index 189d62b..8ccb2d1 100644 --- a/.codex/agents/truth-doc-reviewer.toml +++ b/.codex/agents/truth-doc-reviewer.toml @@ -1,11 +1,11 @@ -# Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +# Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. name = "truth_doc_reviewer" description = "Read-only Truthmark doc reviewer for shape, decision, rationale, and evidence hygiene." sandbox_mode = "read-only" nickname_candidates = ["Doc Audit", "Doc Shape", "Doc Check"] developer_instructions = """ Stay read-only. -Review assigned canonical truth docs for frontmatter, source_of_truth, required template sections, Evidence checked entries, Product Decisions, and Rationale. +Review assigned canonical truth docs for compact frontmatter, required template sections, final Source References entries, Evidence checked entries, and lane-appropriate decision sections (Product Decisions in product truth, Engineering Decisions in engineering truth). Flag README.md files used as behavior truth targets, mixed-owner docs, and shape repairs that should move to Truth Structure. Do not edit files, stage changes, or rewrite docs. Return JSON only with keys: scope, filesReviewed, findings, evidence, confidence, recommendedWorkflow, notes. diff --git a/.codex/agents/truth-doc-writer.toml b/.codex/agents/truth-doc-writer.toml index a6a9607..7f60371 100644 --- a/.codex/agents/truth-doc-writer.toml +++ b/.codex/agents/truth-doc-writer.toml @@ -1,4 +1,4 @@ -# Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +# Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. name = "truth_doc_writer" description = "Write-capable Truthmark doc worker for one parent-leased truth-document shard." sandbox_mode = "workspace-write" diff --git a/.codex/agents/truth-route-auditor.toml b/.codex/agents/truth-route-auditor.toml index 54edecd..678c1b3 100644 --- a/.codex/agents/truth-route-auditor.toml +++ b/.codex/agents/truth-route-auditor.toml @@ -1,4 +1,4 @@ -# Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +# Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. name = "truth_route_auditor" description = "Read-only Truthmark route auditor for bounded routing and ownership verification." sandbox_mode = "read-only" @@ -7,7 +7,14 @@ developer_instructions = """ Stay read-only. Audit one bounded Truthmark route, area, or doc shard assigned by the parent. Inspect .truthmark/config.yml and route files only when they exist; then inspect mapped truth docs and relevant implementation files directly. +Use a route-first bounded strategy: narrow audits inspect only the routed area and directly linked counterpart docs; root-wide health first builds a cheap route-map/index from route files, then inspects only mismatches and linked leaves. Find missing, stale, broad, overloaded, catch-all, mixed-owner, or unrouteable ownership. +Validate route ownership against lane-specific roots and route kind: +- confirm mapped truth docs resolve to the correct lane root (product or engineering) for their kind +- flag mismatch between assigned route kind and resolved doc kind (for example, product-capability routed to engineering paths) +- verify route-doc linkage for lane pairings via realized_by and realizes before recommending edits +- inspect product counterparts for engineering docs only when route YAML claims a product relationship, or when the parent explicitly asks for user-visible product coverage +- treat missing product links for user-visible engineering docs as a second-pass diagnostic, not a default full-document read. Do not edit files, stage changes, or propose broad rewrites. Return JSON only with keys: scope, filesReviewed, findings, evidence, confidence, recommendedWorkflow, notes. recommendedWorkflow must be one of: none, truthmark-document, truthmark-structure. diff --git a/.gitignore b/.gitignore index d326297..3120c20 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,5 @@ node_modules/ dist/ -projects/ +/projects/ +.hermes/ *.tgz diff --git a/.opencode/agents/truth-claim-verifier.md b/.opencode/agents/truth-claim-verifier.md index 604da61..6948e19 100644 --- a/.opencode/agents/truth-claim-verifier.md +++ b/.opencode/agents/truth-claim-verifier.md @@ -16,7 +16,7 @@ permission: "grep *": allow --- -# Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +# Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. Manual invocation: @truth-claim-verifier diff --git a/.opencode/agents/truth-doc-reviewer.md b/.opencode/agents/truth-doc-reviewer.md index 6f1fbea..3facc10 100644 --- a/.opencode/agents/truth-doc-reviewer.md +++ b/.opencode/agents/truth-doc-reviewer.md @@ -16,12 +16,12 @@ permission: "grep *": allow --- -# Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +# Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. Manual invocation: @truth-doc-reviewer Stay read-only. -Review assigned canonical truth docs for frontmatter, source_of_truth, required template sections, Evidence checked entries, Product Decisions, and Rationale. +Review assigned canonical truth docs for compact frontmatter, required template sections, final Source References entries, Evidence checked entries, and lane-appropriate decision sections (Product Decisions in product truth, Engineering Decisions in engineering truth). Flag README.md files used as behavior truth targets, mixed-owner docs, and shape repairs that should move to Truth Structure. Do not edit files, stage changes, or rewrite docs. Return JSON only with keys: scope, filesReviewed, findings, evidence, confidence, recommendedWorkflow, notes. diff --git a/.opencode/agents/truth-doc-writer.md b/.opencode/agents/truth-doc-writer.md index a0539af..49d03c1 100644 --- a/.opencode/agents/truth-doc-writer.md +++ b/.opencode/agents/truth-doc-writer.md @@ -8,7 +8,8 @@ permission: glob: allow edit: "*": deny - "docs/truthmark/truth/**": allow + "docs/truthmark/product/**": allow + "docs/truthmark/engineering/**": allow "docs/truthmark/routes/areas.md": allow "docs/truthmark/routes/areas/**/*.md": allow task: deny @@ -21,7 +22,7 @@ permission: "git diff*": allow --- -# Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +# Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. Manual invocation: @truth-doc-writer diff --git a/.opencode/agents/truth-route-auditor.md b/.opencode/agents/truth-route-auditor.md index 938ca1a..5e060d5 100644 --- a/.opencode/agents/truth-route-auditor.md +++ b/.opencode/agents/truth-route-auditor.md @@ -16,14 +16,21 @@ permission: "grep *": allow --- -# Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +# Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. Manual invocation: @truth-route-auditor Stay read-only. Audit one bounded Truthmark route, area, or doc shard assigned by the parent. Inspect .truthmark/config.yml and route files only when they exist; then inspect mapped truth docs and relevant implementation files directly. +Use a route-first bounded strategy: narrow audits inspect only the routed area and directly linked counterpart docs; root-wide health first builds a cheap route-map/index from route files, then inspects only mismatches and linked leaves. Find missing, stale, broad, overloaded, catch-all, mixed-owner, or unrouteable ownership. +Validate route ownership against lane-specific roots and route kind: +- confirm mapped truth docs resolve to the correct lane root (product or engineering) for their kind +- flag mismatch between assigned route kind and resolved doc kind (for example, product-capability routed to engineering paths) +- verify route-doc linkage for lane pairings via realized_by and realizes before recommending edits +- inspect product counterparts for engineering docs only when route YAML claims a product relationship, or when the parent explicitly asks for user-visible product coverage +- treat missing product links for user-visible engineering docs as a second-pass diagnostic, not a default full-document read. Do not edit files, stage changes, or propose broad rewrites. Return JSON only with keys: scope, filesReviewed, findings, evidence, confidence, recommendedWorkflow, notes. recommendedWorkflow must be one of: none, truthmark-document, truthmark-structure. diff --git a/.opencode/skills/truthmark-check/SKILL.md b/.opencode/skills/truthmark-check/SKILL.md index b8b5902..fba7a53 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, routing, ownership, or canonical docs. Not for normal lint/test/typecheck/code-review verification, finish-time Sync, or silently rewriting docs. argument-hint: Optional area, doc path, or audit focus user-invocable: true -truthmark-version: 2.1.0 +truthmark-version: 2.2.1 --- # Truthmark Check diff --git a/.opencode/skills/truthmark-check/support/procedure.md b/.opencode/skills/truthmark-check/support/procedure.md index 6132ff9..3408f9b 100644 --- a/.opencode/skills/truthmark-check/support/procedure.md +++ b/.opencode/skills/truthmark-check/support/procedure.md @@ -1,6 +1,6 @@ # Truthmark Check Procedure -Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. # Truthmark Check @@ -11,13 +11,31 @@ Invocations: OpenCode /skill truthmark-check; Codex /truthmark-check or $truthma Truth Check is agent-led: - inspect .truthmark/config.yml and configured route files only when they exist; then inspect canonical docs and relevant implementation directly -- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. -Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. - inspect the configured root route index at docs/truthmark/routes/areas.md and relevant child route files under docs/truthmark/routes/areas/ when they exist +- Evidence authority: + - Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. + - Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. +- Lane classification: + - classify the request or changed surface as product-lane, engineering-lane, both-lane, or ambiguous for reporting only + - product-lane ownership belongs under docs/truthmark/product and describes product promises, boundaries, rationale, decisions, and success criteria + - engineering-lane ownership belongs under docs/truthmark/engineering and describes source-backed current realization, contracts, architecture, workflows, operations, or tests + - both-lane ownership uses separate product and engineering docs cross-linked in route YAML with realized_by and realizes, not in doc frontmatter + - ambiguous lane ownership should be reported as blocked or routed to Truth Structure + - Do not make product docs a summary of engineering docs. Do not make engineering docs a detailed version of product docs. Product truth says what must be true and why. Engineering truth says how the repository currently realizes it. - check that current docs describe current code rather than historical plans +- keep lane and cross-lane checks route-first and bounded: + - for a narrow audit, inspect only the routed area and directly linked counterpart docs + - for root-wide truth health, first build a cheap route-map/index from route files, then inspect only mismatches and linked leaves + - inspect product counterparts for engineering docs only when route YAML claims a product relationship, or when the user explicitly asks for user-visible product coverage +- check lane root/kind alignment for product truth under docs/truthmark/product and engineering truth under docs/truthmark/engineering +- check route YAML cross-lane realized_by and realizes links for existence and lane compatibility +- report missing product links for user-visible engineering docs only as a second-pass review diagnostic, not as default full-document reads or hard errors +- check product docs do not contain engineering execution flow, generated file inventories, or CLI envelope mechanics +- check engineering docs do not contain product promises, product rationale, or Product Decisions sections +- never judge whether a product decision is commercially correct, valuable, prioritized, or desirable - check that route files map code surfaces to canonical truth docs when route files exist - check for broad, catch-all, index-like, or mixed-owner truth docs and report them as topology issues requiring Truth Structure -- check that canonical behavior docs keep active Product Decisions and Rationale sections +- check that canonical docs keep lane-appropriate decisions and rationale sections - optionally run truthmark check when local tooling is available - must not require the truthmark binary; direct inspection is always valid - report issues and suggested fixes without silently rewriting unrelated files @@ -31,7 +49,8 @@ Truthmark hierarchy hints: - Config, when present: .truthmark/config.yml - Root route index, when present: docs/truthmark/routes/areas.md - Area route files, when present: docs/truthmark/routes/areas/**/*.md -- Truth docs, when present: docs/truthmark/truth/**/*.md +- Product truth docs, when present: docs/truthmark/product/**/*.md +- Engineering truth docs, when present: docs/truthmark/engineering/**/*.md Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. -Update Product Decisions and Rationale when a decision changes behavior. +Product decisions belong in product truth; engineering, architecture, contract, workflow, and operational decisions belong in engineering truth. diff --git a/.opencode/skills/truthmark-check/support/report-template.md b/.opencode/skills/truthmark-check/support/report-template.md index 00a3453..7253416 100644 --- a/.opencode/skills/truthmark-check/support/report-template.md +++ b/.opencode/skills/truthmark-check/support/report-template.md @@ -1,6 +1,6 @@ # Truthmark Check Report Template -Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. Report completion in this shape: diff --git a/.opencode/skills/truthmark-check/support/subagents-and-leases.md b/.opencode/skills/truthmark-check/support/subagents-and-leases.md index 74eb60a..c20665b 100644 --- a/.opencode/skills/truthmark-check/support/subagents-and-leases.md +++ b/.opencode/skills/truthmark-check/support/subagents-and-leases.md @@ -1,6 +1,6 @@ # Truthmark Check Subagents And Leases -Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. OpenCode subagent mode: - use automatically when this workflow runs in OpenCode and the parent agent chooses bounded subagent fan-out diff --git a/.opencode/skills/truthmark-document/SKILL.md b/.opencode/skills/truthmark-document/SKILL.md index 241a841..1caec9b 100644 --- a/.opencode/skills/truthmark-document/SKILL.md +++ b/.opencode/skills/truthmark-document/SKILL.md @@ -3,7 +3,7 @@ name: truthmark-document description: Use when the user asks to document existing implemented behavior, or Sync, Check, or Structure finds implemented behavior missing canonical truth. Not for functional-code changes, doc-first implementation, or topology repair that needs Structure. argument-hint: Optional implemented behavior, API endpoint, route, controller, package, or truth-doc area to document user-invocable: true -truthmark-version: 2.1.0 +truthmark-version: 2.2.1 --- # Truthmark Document diff --git a/.opencode/skills/truthmark-document/helper-manifest.yml b/.opencode/skills/truthmark-document/helper-manifest.yml index 175e1a0..f7b749b 100644 --- a/.opencode/skills/truthmark-document/helper-manifest.yml +++ b/.opencode/skills/truthmark-document/helper-manifest.yml @@ -1,8 +1,8 @@ -# Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +# Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. helpers: validate-document-report: optional: true - runner: truthmark>=2.1.0 + runner: truthmark>=2.2.1 command: argv: - truthmark @@ -17,7 +17,7 @@ helpers: fallback: manually validate support/report-template.md required sections and structured Evidence checked entries validate-write-lease: optional: true - runner: truthmark>=2.1.0 + runner: truthmark>=2.2.1 command: argv: - truthmark diff --git a/.opencode/skills/truthmark-document/support/helper-policy.md b/.opencode/skills/truthmark-document/support/helper-policy.md index 2cb7bd6..9e87b00 100644 --- a/.opencode/skills/truthmark-document/support/helper-policy.md +++ b/.opencode/skills/truthmark-document/support/helper-policy.md @@ -1,6 +1,6 @@ # Optional Helper CLI Policy -Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. Optional helper CLI commands may collect deterministic checkout facts or validate artifacts. If the Truthmark CLI is unavailable or too old for a declared helper, continue manually using this procedure and report which helper was skipped. Helper output is derived evidence; it does not override direct checkout inspection, workflow write boundaries, or parent acceptance. @@ -11,8 +11,8 @@ Runner detection: - Do not fail the workflow solely because a helper cannot run. Available helpers: -- validate-document-report: optional truthmark>=2.1.0; manual fallback: manually validate support/report-template.md required sections and structured Evidence checked entries -- validate-write-lease: optional truthmark>=2.1.0; manual fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files +- validate-document-report: optional truthmark>=2.2.1; manual fallback: manually validate support/report-template.md required sections and structured Evidence checked entries +- validate-write-lease: optional truthmark>=2.2.1; manual fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files Final reports should include helper status when helpers are declared for this workflow: diff --git a/.opencode/skills/truthmark-document/support/procedure.md b/.opencode/skills/truthmark-document/support/procedure.md index be8590f..db0602c 100644 --- a/.opencode/skills/truthmark-document/support/procedure.md +++ b/.opencode/skills/truthmark-document/support/procedure.md @@ -1,6 +1,6 @@ # Truthmark Document Procedure -Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. # Truthmark Document @@ -11,8 +11,16 @@ Truth Document is manual and implementation-first: - run only when the user explicitly asks to generate or update truth docs for existing behavior, or when Truth Sync, Truth Check, or Truth Structure reports implemented behavior that lacks canonical truth docs - inspect .truthmark/config.yml and configured route files only when they exist; then inspect existing canonical docs, implementation code, and tests directly -- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. -Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. +- Evidence authority: + - Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. + - Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. +- Lane classification: + - before writing canonical truth docs, classify the request or change as product-lane, engineering-lane, both-lane, or ambiguous + - product-lane writes belong under docs/truthmark/product and state product promises, boundaries, rationale, decisions, and success criteria + - engineering-lane writes belong under docs/truthmark/engineering and state source-backed current realization, contracts, architecture, workflows, operations, or tests + - both-lane work must write separate product and engineering docs and cross-link them in route YAML with realized_by and realizes, not in doc frontmatter + - ambiguous lane ownership must block or invoke Truth Structure instead of writing a mixed document + - Do not make product docs a summary of engineering docs. Do not make engineering docs a detailed version of product docs. Product truth says what must be true and why. Engineering truth says how the repository currently realizes it. - document current implemented behavior; do not invent future behavior or planned endpoints - may write canonical truth docs and docs/truthmark/routes/areas.md or relevant child route files only - must not write functional code @@ -20,7 +28,10 @@ Implementation code and canonical truth docs are inspected evidence for current - block and recommend Truth Structure when routing repair is unsafe, ambiguous, or outside the task boundary - keep feature README.md files as indexes rather than truth-document targets - create or update bounded leaf truth docs when behavior does not fit an existing leaf doc -- keep behavior truth docs behavior-oriented, not endpoint-oriented, unless the endpoint itself is the behavior boundary +- write product capability/boundary truth under docs/truthmark/product when documenting product promise, boundary, rationale, or user/stakeholder value +- write engineering truth under docs/truthmark/engineering when documenting implementation behavior, contracts, architecture, workflows, operations, or tests +- for both-lane documentation requests, write separate product and engineering docs and cross-link them in route YAML with realized_by and realizes, not in doc frontmatter +- keep engineering behavior truth behavior-oriented, not endpoint-oriented, unless the endpoint itself is the behavior boundary - keep API endpoint details in the nearest contract truth doc when such a doc owns the API contract - preserve unrelated authored content Truth-doc ownership gate: @@ -28,27 +39,27 @@ Truth-doc ownership gate: - if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it - if the target doc is broad, mixed-owner, index-like, or the documented behavior spans independent owners, run Truth Structure first when safe and in scope; otherwise block and recommend Truth Structure - report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Blocked reason as applicable -Product Decisions/Rationale preservation gate: -- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions and Rationale sections in every source or touched truth doc -- preserve each current decision and rationale in the bounded owner doc it governs; when splitting, move it to the new owner doc rather than deleting it or leaving it in an index +Decision/Rationale preservation gate: +- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions, Engineering Decisions, and Rationale sections in every source or touched truth doc +- preserve each current decision and rationale in the correct product or engineering lane owner; when splitting, move it to the new owner doc rather than deleting it or leaving it in an index - remove or narrow a decision or rationale only when checkout evidence shows it is stale or unsupported, and report the exact claim, evidence, and result - if ownership of a decision or rationale is unclear, block with manual-review files instead of deleting it or guessing -- after the edit, verify every touched truth doc still has Product Decisions and Rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked +- after the edit, verify every touched truth doc keeps lane-appropriate decision/rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked Evidence Gate: - route-first: map the documented behavior to bounded route owners and primary canonical docs -- review new or changed behavior-bearing claims only in touched docs, route ownership, Product Decisions, and Rationale +- review new or changed behavior-bearing claims only in touched docs, route ownership, lane-specific decisions, and rationale - support claims with primary checkout evidence: implementation, config, routing, generated templates, schemas, or contract definitions - tests/examples/canonical docs corroborate; they are not sole proof when implementation conflicts - remove, narrow, or block unsupported claims - if no truth doc changed, report why current truth was already sufficient or why documentation was blocked -Repository intelligence artifacts are optional derived context: RepoIndex, RouteMap, ImpactSet, and ContextPack may guide routing, context selection, and verification planning when available. +Repository intelligence artifacts are optional derived context: RepoIndex, RouteMap, ImpactSet, and WorkflowState/action context may guide routing, write boundaries, and verification planning when available. They do not override checkout evidence, canonical truth docs, route files, or workflow write boundaries. If unavailable, inspect any present Truthmark config, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated. When creating or updating a truth doc, inspect the routed truth kind and use the matching template under the configured Truthmark templates root. -Supported kinds: behavior, contract, architecture, workflow, operations, and test-behavior. +Supported kinds: product-capability, engineering-behavior, engineering-contract, engineering-architecture, engineering-workflow, engineering-operations, and engineering-test-behavior. Treat the HTML comments under each template section as normative authoring guidance for that section. Align existing docs to that template and write or repair section content so it satisfies the comment guidance while preserving accurate authored content. -If the template is missing, use Scope, Product Decisions, Rationale, and the kind-specific current-truth section. +If the template is missing, use lane-specific sections: product truth says what must be true and why; engineering truth says how the repository currently realizes it. Teams may edit template files under the configured Truthmark templates root to define their local truth-doc standards. Truth-doc shape repair gate: - Truth Document may restructure only truth docs for the implemented behavior being documented. @@ -63,10 +74,11 @@ Truthmark hierarchy hints: - Config, when present: .truthmark/config.yml - Root route index, when present: docs/truthmark/routes/areas.md - Area route files, when present: docs/truthmark/routes/areas/**/*.md -- Truth docs, when present: docs/truthmark/truth/**/*.md +- Product truth docs, when present: docs/truthmark/product/**/*.md +- Engineering truth docs, when present: docs/truthmark/engineering/**/*.md Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. -Update Product Decisions and Rationale when a decision changes behavior. +Product decisions belong in product truth; engineering, architecture, contract, workflow, and operational decisions belong in engineering truth. Helper status reporting: - Validate the report body before adding this validator's own success status; the body may omit `validate-document-report` while validation is pending. - After `truthmark validate document-report --json` returns `data.validation.ok: true`, append or update `validate-document-report: ran, passed` in the final report. diff --git a/.opencode/skills/truthmark-document/support/report-template.md b/.opencode/skills/truthmark-document/support/report-template.md index 5e38b92..ae3ce4c 100644 --- a/.opencode/skills/truthmark-document/support/report-template.md +++ b/.opencode/skills/truthmark-document/support/report-template.md @@ -1,6 +1,6 @@ # Truthmark Document Report Template -Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. Report completion in this shape: ```md @@ -13,13 +13,13 @@ Ownership reviewed: - docs/truthmark/routes/areas.md Truth docs created: -- docs/truthmark/truth/contracts.md +- docs/truthmark/engineering/contracts/routing.md Truth docs updated: -- docs/truthmark/truth/check-diagnostics.md +- docs/truthmark/engineering/behaviors/check-diagnostics.md Truth docs restructured: -- docs/truthmark/truth/check-diagnostics.md +- docs/truthmark/engineering/behaviors/check-diagnostics.md Routing updated: - docs/truthmark/routes/areas.md diff --git a/.opencode/skills/truthmark-document/support/subagents-and-leases.md b/.opencode/skills/truthmark-document/support/subagents-and-leases.md index b4f7b6a..274c450 100644 --- a/.opencode/skills/truthmark-document/support/subagents-and-leases.md +++ b/.opencode/skills/truthmark-document/support/subagents-and-leases.md @@ -1,6 +1,6 @@ # Truthmark Document Subagents And Leases -Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. OpenCode subagent mode: - use automatically when this workflow runs in OpenCode and the parent agent chooses bounded subagent fan-out diff --git a/.opencode/skills/truthmark-portal/SKILL.md b/.opencode/skills/truthmark-portal/SKILL.md index e8ace3c..2aa77d0 100644 --- a/.opencode/skills/truthmark-portal/SKILL.md +++ b/.opencode/skills/truthmark-portal/SKILL.md @@ -3,7 +3,7 @@ name: truthmark-portal description: Use when the user explicitly asks to generate, refresh, or update the Truthmark Portal static HTML site. Not for code change sync, route repair, truth validation/checking, documenting behavior, realizing docs into code, or machine-readable agent context. argument-hint: Optional portal generation focus user-invocable: true -truthmark-version: 2.1.0 +truthmark-version: 2.2.1 --- # Truthmark Portal diff --git a/.opencode/skills/truthmark-portal/support/procedure.md b/.opencode/skills/truthmark-portal/support/procedure.md index 89d5c39..671435b 100644 --- a/.opencode/skills/truthmark-portal/support/procedure.md +++ b/.opencode/skills/truthmark-portal/support/procedure.md @@ -1,6 +1,6 @@ # Truthmark Portal Procedure -Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. # Truthmark Portal @@ -37,4 +37,5 @@ Truthmark hierarchy hints: - Config, when present: .truthmark/config.yml - Root route index, when present: docs/truthmark/routes/areas.md - Area route files, when present: docs/truthmark/routes/areas/**/*.md -- Truth docs, when present: docs/truthmark/truth/**/*.md +- Product truth docs, when present: docs/truthmark/product/**/*.md +- Engineering truth docs, when present: docs/truthmark/engineering/**/*.md diff --git a/.opencode/skills/truthmark-portal/support/report-template.md b/.opencode/skills/truthmark-portal/support/report-template.md index bd2d23d..ec72660 100644 --- a/.opencode/skills/truthmark-portal/support/report-template.md +++ b/.opencode/skills/truthmark-portal/support/report-template.md @@ -1,6 +1,6 @@ # Truthmark Portal Report Template -Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. Report completion in this shape: diff --git a/.opencode/skills/truthmark-preview/SKILL.md b/.opencode/skills/truthmark-preview/SKILL.md index 7db8d92..5a8a993 100644 --- a/.opencode/skills/truthmark-preview/SKILL.md +++ b/.opencode/skills/truthmark-preview/SKILL.md @@ -3,7 +3,7 @@ name: truthmark-preview description: Use when the user explicitly asks to preview likely workflow routing, target files, writes, or subagent use before edits. Not for validation, automatic gates, final correctness, or replacing Truth Check. argument-hint: Optional requested outcome, code area, doc path, or routing question user-invocable: true -truthmark-version: 2.1.0 +truthmark-version: 2.2.1 --- # Truthmark Preview @@ -14,7 +14,7 @@ Invocations: OpenCode /skill truthmark-preview; Codex /truthmark-preview or $tru Quick procedure: - Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists. -- Inspect .truthmark/config.yml and configured route files (docs/truthmark/routes/areas.md; docs/truthmark/routes/areas/) only when they exist; then inspect only the truth docs or implementation files needed to preview ownership. +- Inspect .truthmark/config.yml and the root route index (docs/truthmark/routes/areas.md) first when present; then inspect only child route files under docs/truthmark/routes/areas/ that are relevant to the selected scope or changed paths, plus the truth docs or implementation files needed to preview ownership. - Truth Preview is read-only; this report is intended, not authorized. - must not edit files and must not issue write leases; do not run Truth Sync automatically, replace Truth Check, claim final correctness, or mutate code. - Use optional read-only route-auditor evidence only when it reduces context or clarifies ownership. diff --git a/.opencode/skills/truthmark-preview/support/procedure.md b/.opencode/skills/truthmark-preview/support/procedure.md index 276926b..5d608e9 100644 --- a/.opencode/skills/truthmark-preview/support/procedure.md +++ b/.opencode/skills/truthmark-preview/support/procedure.md @@ -1,6 +1,6 @@ # Truthmark Preview Procedure -Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. Use this skill only when the user explicitly asks to preview Truthmark routing or workflow choice before edits. @@ -10,16 +10,25 @@ Truth Preview is read-only. Its report is intended, not authorized. Purpose: - preview the likely Truthmark workflow, route owner, target files, expected write classes, suggested subagent use, and blocking ambiguity before edits happen +- report likely product lane impact, engineering lane impact, target docs, and ambiguity before edits - hand off to the selected workflow after user approval - keep the selector thin so agents can avoid loading or acting through heavier workflows prematurely Read: - .truthmark/config.yml, only when present -- docs/truthmark/routes/areas.md, only when present -- relevant child route files under docs/truthmark/routes/areas/, only when present +- docs/truthmark/routes/areas.md, first, only when present +- relevant child route files under docs/truthmark/routes/areas/ for the selected scope or changed paths, only when present - relevant truth docs and implementation files needed to preview ownership -- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. -Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. +- Evidence authority: + - Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. + - Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. +- Lane classification: + - classify the request or changed surface as product-lane, engineering-lane, both-lane, or ambiguous for reporting only + - product-lane ownership belongs under docs/truthmark/product and describes product promises, boundaries, rationale, decisions, and success criteria + - engineering-lane ownership belongs under docs/truthmark/engineering and describes source-backed current realization, contracts, architecture, workflows, operations, or tests + - both-lane ownership uses separate product and engineering docs cross-linked in route YAML with realized_by and realizes, not in doc frontmatter + - ambiguous lane ownership should be reported as blocked or routed to Truth Structure + - Do not make product docs a summary of engineering docs. Do not make engineering docs a detailed version of product docs. Product truth says what must be true and why. Engineering truth says how the repository currently realizes it. Do not: - must not edit files @@ -40,4 +49,5 @@ Truthmark hierarchy hints: - Config, when present: .truthmark/config.yml - Root route index, when present: docs/truthmark/routes/areas.md - Area route files, when present: docs/truthmark/routes/areas/**/*.md -- Truth docs, when present: docs/truthmark/truth/**/*.md +- Product truth docs, when present: docs/truthmark/product/**/*.md +- Engineering truth docs, when present: docs/truthmark/engineering/**/*.md diff --git a/.opencode/skills/truthmark-preview/support/report-template.md b/.opencode/skills/truthmark-preview/support/report-template.md index bff96a9..9e697be 100644 --- a/.opencode/skills/truthmark-preview/support/report-template.md +++ b/.opencode/skills/truthmark-preview/support/report-template.md @@ -1,6 +1,6 @@ # Truthmark Preview Report Template -Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. Report completion in this shape: ```md @@ -19,14 +19,16 @@ Why this workflow: Likely route owner: - route file: docs/truthmark/routes/areas.md -- truth doc: docs/truthmark/truth/example.md +- likely lane impact: engineering-lane +- product target docs: none identified +- engineering target docs: docs/truthmark/engineering/behaviors/example.md - confidence: medium Expected write classes: - truth docs Expected target files: -- docs/truthmark/truth/example.md +- docs/truthmark/engineering/behaviors/example.md Suggested subagent use: - read-only verifiers: truth_route_auditor diff --git a/.opencode/skills/truthmark-preview/support/subagents-and-leases.md b/.opencode/skills/truthmark-preview/support/subagents-and-leases.md index 896c506..91679c8 100644 --- a/.opencode/skills/truthmark-preview/support/subagents-and-leases.md +++ b/.opencode/skills/truthmark-preview/support/subagents-and-leases.md @@ -1,6 +1,6 @@ # Truthmark Preview Subagents And Leases -Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. OpenCode subagent mode: - use automatically when this workflow runs in OpenCode and the parent agent chooses bounded subagent fan-out diff --git a/.opencode/skills/truthmark-realize/SKILL.md b/.opencode/skills/truthmark-realize/SKILL.md index 8256b8e..bcf5912 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. Not for syncing docs after code changes, documenting existing code, topology repair, or truth audits. argument-hint: Optional truth doc path, area, or desired code behavior to realize user-invocable: true -truthmark-version: 2.1.0 +truthmark-version: 2.2.1 --- # Truthmark Realize diff --git a/.opencode/skills/truthmark-realize/support/procedure.md b/.opencode/skills/truthmark-realize/support/procedure.md index c419a77..bc86afe 100644 --- a/.opencode/skills/truthmark-realize/support/procedure.md +++ b/.opencode/skills/truthmark-realize/support/procedure.md @@ -1,6 +1,6 @@ # Truthmark Realize Procedure -Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. # Truthmark Realize @@ -33,7 +33,8 @@ Truthmark hierarchy hints: - Config, when present: .truthmark/config.yml - Root route index, when present: docs/truthmark/routes/areas.md - Area route files, when present: docs/truthmark/routes/areas/**/*.md -- Truth docs, when present: docs/truthmark/truth/**/*.md +- Product truth docs, when present: docs/truthmark/product/**/*.md +- Engineering truth docs, when present: docs/truthmark/engineering/**/*.md Read and write boundaries: diff --git a/.opencode/skills/truthmark-realize/support/report-template.md b/.opencode/skills/truthmark-realize/support/report-template.md index b540f61..4e55a01 100644 --- a/.opencode/skills/truthmark-realize/support/report-template.md +++ b/.opencode/skills/truthmark-realize/support/report-template.md @@ -1,6 +1,6 @@ # Truthmark Realize Report Template -Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. Report completion in this shape: @@ -8,7 +8,8 @@ Report completion in this shape: Truth Realize: completed Truth docs used: -- docs/truthmark/truth/authentication/session-timeout.md +- docs/truthmark/product/capabilities/authentication-session.md +- docs/truthmark/engineering/behaviors/authentication-session.md Code updated: - src/auth/session.ts diff --git a/.opencode/skills/truthmark-structure/SKILL.md b/.opencode/skills/truthmark-structure/SKILL.md index 4e0d2ab..01b08c6 100644 --- a/.opencode/skills/truthmark-structure/SKILL.md +++ b/.opencode/skills/truthmark-structure/SKILL.md @@ -3,7 +3,7 @@ name: truthmark-structure description: Use when routing or truth ownership is missing, stale, broad, overloaded, catch-all, unrouteable, mixed-owner, needs split/repair, or needs new area setup. Not for documenting implemented behavior, syncing a code diff, or realizing docs into code. argument-hint: Optional area, directory, or routing concern user-invocable: true -truthmark-version: 2.1.0 +truthmark-version: 2.2.1 --- # Truthmark Structure diff --git a/.opencode/skills/truthmark-structure/support/procedure.md b/.opencode/skills/truthmark-structure/support/procedure.md index 5112d6e..1588ce5 100644 --- a/.opencode/skills/truthmark-structure/support/procedure.md +++ b/.opencode/skills/truthmark-structure/support/procedure.md @@ -1,29 +1,38 @@ # Truthmark Structure Procedure -Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. Use this skill to design or repair Truthmark area structure. Invocations: OpenCode /skill truthmark-structure; Codex /truthmark-structure or $truthmark-structure; Claude Code /truthmark-structure; GitHub Copilot /truthmark-structure; Gemini CLI /truthmark:structure. Truth Structure is agent-native: - inspect repository layout, current docs, Truthmark config and route files when present, and relevant code directly -- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. -Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. +- Evidence authority: + - Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. + - Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. +- Lane classification: + - before writing canonical truth docs, classify the request or change as product-lane, engineering-lane, both-lane, or ambiguous + - product-lane writes belong under docs/truthmark/product and state product promises, boundaries, rationale, decisions, and success criteria + - engineering-lane writes belong under docs/truthmark/engineering and state source-backed current realization, contracts, architecture, workflows, operations, or tests + - both-lane work must write separate product and engineering docs and cross-link them in route YAML with realized_by and realizes, not in doc frontmatter + - ambiguous lane ownership must block or invoke Truth Structure instead of writing a mixed document + - Do not make product docs a summary of engineering docs. Do not make engineering docs a detailed version of product docs. Product truth says what must be true and why. Engineering truth says how the repository currently realizes it. - inspect the configured root route index at docs/truthmark/routes/areas.md and relevant child route files under docs/truthmark/routes/areas/ when they exist - define areas by product or behavior ownership, not by mechanical directory mirroring - create or repair docs/truthmark/routes/areas.md - create starter truth docs when useful and when they belong in the canonical current-truth surface -- Starter truth docs must use closed YAML frontmatter bounded by opening and closing --- lines; include status, doc_type, last_reviewed, and source_of_truth inside that frontmatter. -- Starter truth docs must include ## Product Decisions and ## Rationale sections. +- Starter truth docs must use closed YAML frontmatter bounded by opening and closing --- lines; include status, truth_kind, and last_reviewed inside that frontmatter. Put source references in the final ## Source References section, not in frontmatter. +- Starter truth docs must use lane-specific templates and keep product and engineering truth in separate files. When creating or updating a truth doc, inspect the routed truth kind and use the matching template under the configured Truthmark templates root. -Supported kinds: behavior, contract, architecture, workflow, operations, and test-behavior. +Supported kinds: product-capability, engineering-behavior, engineering-contract, engineering-architecture, engineering-workflow, engineering-operations, and engineering-test-behavior. Treat the HTML comments under each template section as normative authoring guidance for that section. Align existing docs to that template and write or repair section content so it satisfies the comment guidance while preserving accurate authored content. -If the template is missing, use Scope, Product Decisions, Rationale, and the kind-specific current-truth section. +If the template is missing, use lane-specific sections: product truth says what must be true and why; engineering truth says how the repository currently realizes it. Teams may edit template files under the configured Truthmark templates root to define their local truth-doc standards. -- use docs/truthmark/truth/** for current truth destinations +- use docs/truthmark/product/** for product truth destinations +- use docs/truthmark/engineering/** for engineering truth destinations - use only canonical current-truth destinations for starter truth docs -- keep active Product Decisions and Rationale in the canonical doc that owns the behavior +- keep active Product Decisions in product truth and Engineering Decisions in engineering truth - preserve unrelated authored content ## New area setup Use when a user asks to onboard a new code area into Truthmark, a new package, controller, domain, or product area lacks bounded truth ownership, or a new product area needs routing and starter truth docs. @@ -41,7 +50,7 @@ Do not: - do not create generic catch-all docs - do not treat README files as Sync targets ## Topology Governance -Truth Structure owns documentation topology. Do not depend on humans to manually organize docs/truthmark/truth. Treat the configured truth root as a managed semantic root. +Truth Structure owns documentation topology, lane splits, decision relocation, and relationship repair. Do not depend on humans to manually organize docs/truthmark/product or docs/truthmark/engineering. Treat both configured lane roots as managed semantic roots. Inspect controllers, routes, handlers, services, packages, tests, existing truth docs, and route files; infer product and domain ownership from behavior boundaries, not from mechanical directory mirroring. When topology pressure exists, repair structure before creating or extending truth docs. Truth-doc ownership gate: @@ -49,17 +58,17 @@ Truth-doc ownership gate: - if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it - if a truth doc mixes independent owners, route ownership is broad, or a split is required for bounded ownership, split and reroute into bounded truth docs when safe; otherwise block with manual-review files - report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Blocked reason as applicable -Product Decisions/Rationale preservation gate: -- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions and Rationale sections in every source or touched truth doc -- preserve each current decision and rationale in the bounded owner doc it governs; when splitting, move it to the new owner doc rather than deleting it or leaving it in an index +Decision/Rationale preservation gate: +- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions, Engineering Decisions, and Rationale sections in every source or touched truth doc +- preserve each current decision and rationale in the correct product or engineering lane owner; when splitting, move it to the new owner doc rather than deleting it or leaving it in an index - remove or narrow a decision or rationale only when checkout evidence shows it is stale or unsupported, and report the exact claim, evidence, and result - if ownership of a decision or rationale is unclear, block with manual-review files instead of deleting it or guessing -- after the edit, verify every touched truth doc still has Product Decisions and Rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked +- after the edit, verify every touched truth doc keeps lane-appropriate decision/rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked Topology pressure signals: - one area maps broad code such as src/**, app/**, server/**, services/**, or packages/** - one area maps multiple unrelated controllers, route groups, services, or bounded contexts - one truth doc owns unrelated behaviors or unrelated endpoint families -- the configured truth root has many direct non-index docs +- either configured lane root has many direct non-index docs - a changed controller, route, or service cannot map to a specific behavior doc - Truth Sync would need to create a new generic truth doc because routing is too broad - endpoint or controller names reveal domains missing from docs/truthmark/routes/areas/** @@ -72,9 +81,10 @@ Repair rules: - split broad, overloaded, or catch-all areas into behavior-owned child route files - split mixed-owner truth docs into bounded owner docs before adding new behavior claims - create route files under docs/truthmark/routes/areas/ when a product/domain boundary is clear -- create behavior truth docs under the configured truth root only when behavior lacks a current doc +- create engineering behavior truth docs under docs/truthmark/engineering only when behavior lacks a current doc +- create product truth docs under docs/truthmark/product only when product promise, boundary, rationale, or user-visible capability truth is in scope - README.md files are indexes, not Truth Sync targets -- prefer bounded leaf truth docs at //.md +- prefer bounded product docs under product/capabilities or product/decisions and engineering docs under engineering//.md - keep behavior truth docs behavior-oriented, not endpoint-oriented - keep API endpoint details in the nearest contract truth doc when such a doc exists - update routing so future Truth Sync can target small docs @@ -88,13 +98,13 @@ Truth-doc shape repair gate: - preserve supported claims; remove, narrow, or block unsupported or stale claims - report docs restructured and why a narrow edit was not sufficient Evidence Gate: -- apply the Evidence Gate before finishing when Truth Structure writes routed docs, ownership claims, Product Decisions, or Rationale +- apply the Evidence Gate before finishing when Truth Structure writes routed docs, ownership claims, lane-specific decisions, or rationale - support ownership/behavior claims with topology or primary checkout evidence from layout, implementation boundaries, docs, config, route files, tests, templates, schemas, or contracts - tests/examples/canonical docs corroborate; remove, narrow, or block unsupported claims Maintain architecture docs only for structure-level changes: system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership. Keep ordinary behavior, endpoints, UI copy, validation rules, and bug fixes in behavior or contract docs unless they change those boundaries. -- Do not finish topology repair with routed canonical current-truth docs missing Product Decisions or Rationale sections. -- If an existing canonical doc lacks either section, add the missing heading beside Current Behavior with a concise current-state placeholder or active decision. +- Do not finish topology repair with mixed product/engineering authority in a single canonical truth doc. +- If an existing canonical doc has wrong-lane sections, split or move them into the correct product or engineering lane. Portable fallback: - If this skill surface is unavailable, perform the same workflow directly from committed repository files. - Do not require the truthmark CLI. @@ -104,7 +114,8 @@ Truthmark hierarchy hints: - Config, when present: .truthmark/config.yml - Root route index, when present: docs/truthmark/routes/areas.md - Area route files, when present: docs/truthmark/routes/areas/**/*.md -- Truth docs, when present: docs/truthmark/truth/**/*.md +- Product truth docs, when present: docs/truthmark/product/**/*.md +- Engineering truth docs, when present: docs/truthmark/engineering/**/*.md Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. -Update Product Decisions and Rationale when a decision changes behavior. +Product decisions belong in product truth; engineering, architecture, contract, workflow, and operational decisions belong in engineering truth. diff --git a/.opencode/skills/truthmark-structure/support/report-template.md b/.opencode/skills/truthmark-structure/support/report-template.md index 1be260b..5dc74e8 100644 --- a/.opencode/skills/truthmark-structure/support/report-template.md +++ b/.opencode/skills/truthmark-structure/support/report-template.md @@ -1,13 +1,14 @@ # Truthmark Structure Report Template -Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. Report completion in this shape: ```md Truth Structure: completed Topology reviewed: - controllers: src/auth/** -- docs root: docs/truthmark/truth +- product docs root: docs/truthmark/product +- engineering docs root: docs/truthmark/engineering - route files: docs/truthmark/routes/areas.md Areas reviewed: - src/auth/** @@ -16,12 +17,14 @@ Routing updated: Initial truth boundary: - Area: Authentication - Code: src/auth/** -- Truth owner: docs/truthmark/truth/authentication/session.md +- Product owner: docs/truthmark/product/capabilities/authentication-session.md +- Engineering owner: docs/truthmark/engineering/behaviors/authentication-session.md - Scope: session behavior only Truth docs created: -- docs/truthmark/truth/authentication/session.md +- docs/truthmark/product/capabilities/authentication-session.md +- docs/truthmark/engineering/behaviors/authentication-session.md Truth docs split: -- docs/truthmark/truth/authentication/README.md -> docs/truthmark/truth/authentication/session.md +- docs/truthmark/truth/authentication/README.md -> docs/truthmark/product/capabilities/authentication-session.md and docs/truthmark/engineering/behaviors/authentication-session.md Truth docs restructured: - docs/truthmark/truth/authentication/README.md Evidence checked: diff --git a/.opencode/skills/truthmark-structure/support/subagents-and-leases.md b/.opencode/skills/truthmark-structure/support/subagents-and-leases.md index ac1129b..fb8efa0 100644 --- a/.opencode/skills/truthmark-structure/support/subagents-and-leases.md +++ b/.opencode/skills/truthmark-structure/support/subagents-and-leases.md @@ -1,6 +1,6 @@ # Truthmark Structure Subagents And Leases -Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. OpenCode subagent mode: - use automatically when this workflow runs in OpenCode and the parent agent chooses bounded subagent fan-out diff --git a/.opencode/skills/truthmark-sync/SKILL.md b/.opencode/skills/truthmark-sync/SKILL.md index ff1d4eb..47b6826 100644 --- a/.opencode/skills/truthmark-sync/SKILL.md +++ b/.opencode/skills/truthmark-sync/SKILL.md @@ -3,7 +3,7 @@ name: truthmark-sync description: Use automatically at finish-time after functional code changes, or explicit /truthmark-sync, $truthmark-sync, or /truthmark:sync. Skip docs-only, formatting-only, behavior-preserving renames, missing config, and no-code changes. Not for doc-first realization or manual topology design. argument-hint: Optional changed-code area, truth-doc area, or sync focus user-invocable: true -truthmark-version: 2.1.0 +truthmark-version: 2.2.1 --- # Truthmark Sync diff --git a/.opencode/skills/truthmark-sync/helper-manifest.yml b/.opencode/skills/truthmark-sync/helper-manifest.yml index dd0153a..36c0434 100644 --- a/.opencode/skills/truthmark-sync/helper-manifest.yml +++ b/.opencode/skills/truthmark-sync/helper-manifest.yml @@ -1,8 +1,8 @@ -# Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +# Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. helpers: validate-sync-report: optional: true - runner: truthmark>=2.1.0 + runner: truthmark>=2.2.1 command: argv: - truthmark @@ -17,7 +17,7 @@ helpers: fallback: "manually validate support/report-template.md and check Evidence checked entries match Claim, indented Evidence, and Result: supported | narrowed | removed | blocked" validate-write-lease: optional: true - runner: truthmark>=2.1.0 + runner: truthmark>=2.2.1 command: argv: - truthmark diff --git a/.opencode/skills/truthmark-sync/support/helper-policy.md b/.opencode/skills/truthmark-sync/support/helper-policy.md index 6c44128..d1831d6 100644 --- a/.opencode/skills/truthmark-sync/support/helper-policy.md +++ b/.opencode/skills/truthmark-sync/support/helper-policy.md @@ -1,6 +1,6 @@ # Optional Helper CLI Policy -Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. Optional helper CLI commands may collect deterministic checkout facts or validate artifacts. If the Truthmark CLI is unavailable or too old for a declared helper, continue manually using this procedure and report which helper was skipped. Helper output is derived evidence; it does not override direct checkout inspection, workflow write boundaries, or parent acceptance. @@ -11,8 +11,8 @@ Runner detection: - Do not fail the workflow solely because a helper cannot run. Available helpers: -- validate-sync-report: optional truthmark>=2.1.0; manual fallback: manually validate support/report-template.md and check Evidence checked entries match Claim, indented Evidence, and Result: supported | narrowed | removed | blocked -- validate-write-lease: optional truthmark>=2.1.0; manual fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files +- validate-sync-report: optional truthmark>=2.2.1; manual fallback: manually validate support/report-template.md and check Evidence checked entries match Claim, indented Evidence, and Result: supported | narrowed | removed | blocked +- validate-write-lease: optional truthmark>=2.2.1; manual fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files Final reports should include helper status when helpers are declared for this workflow: diff --git a/.opencode/skills/truthmark-sync/support/procedure.md b/.opencode/skills/truthmark-sync/support/procedure.md index ff0f6f7..6270aab 100644 --- a/.opencode/skills/truthmark-sync/support/procedure.md +++ b/.opencode/skills/truthmark-sync/support/procedure.md @@ -1,6 +1,6 @@ # Truthmark Sync Procedure -Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. Use this skill automatically before finishing when functional code changed since the last successful Truth Sync. Also run it immediately when the user explicitly invokes Truth Sync. Invocations: OpenCode /skill truthmark-sync; Codex /truthmark-sync or $truthmark-sync; Claude Code /truthmark-sync; GitHub Copilot /truthmark-sync; Gemini CLI /truthmark:sync. @@ -10,10 +10,19 @@ Parent workflow: 1. Inspect git status, staged changes, unstaged changes, and untracked files directly. 2. Inspect .truthmark/config.yml and configured route files only when they exist; then inspect relevant canonical docs. 3. Identify functional-code changes and the nearest truth docs or routing repairs. -4. Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. -Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. -5. Code verification is parent-owned: follow repository instructions and task context, and report what ran or why it did not run. -6. Dispatch bounded Truth Sync workers only when the host supports subagent dispatch and the acting agent chooses that path; otherwise execute the same sync task inline. +4. Evidence authority: + - Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. + - Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. +5. Lane classification gate: + - before writing canonical truth docs, classify the request or change as product-lane, engineering-lane, both-lane, or ambiguous + - product-lane writes belong under docs/truthmark/product and state product promises, boundaries, rationale, decisions, and success criteria + - engineering-lane writes belong under docs/truthmark/engineering and state source-backed current realization, contracts, architecture, workflows, operations, or tests + - both-lane work must write separate product and engineering docs and cross-link them in route YAML with realized_by and realizes, not in doc frontmatter + - ambiguous lane ownership must block or invoke Truth Structure instead of writing a mixed document + - Do not make product docs a summary of engineering docs. Do not make engineering docs a detailed version of product docs. Product truth says what must be true and why. Engineering truth says how the repository currently realizes it. +6. Update engineering truth first after code changes. Update product truth only when implemented user-visible product promise or capability boundary changed and explicit source/user evidence supports it; otherwise report product-lane review needed. +7. Code verification is parent-owned: follow repository instructions and task context, and report what ran or why it did not run. +8. Dispatch bounded Truth Sync workers only when the host supports subagent dispatch and the acting agent chooses that path; otherwise execute the same sync task inline. Topology quality gate: - before updating truth docs, verify the changed code resolves to a specific behavior-owned area and bounded truth owner - if routing is missing, stale, broad, overloaded, catch-all route only, or cannot map changed code to a bounded truth owner, do not create another generic truth doc @@ -23,25 +32,26 @@ Topology quality gate: - README.md files are indexes, not Truth Sync targets - must not append behavior details to a README.md index - create or update a bounded leaf truth doc when behavior changes do not fit an existing leaf doc +- write engineering truth under docs/truthmark/engineering; product truth updates under docs/truthmark/product are allowed only for explicit current product behavior changes Truth-doc ownership gate: - before editing or relying on changed functional files and impacted truth docs, verify each target/source truth doc is a bounded owner for the behavior - if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it - if an impacted doc is broad, mixed-owner, index-like, or the update spans independent behavior owners, run Truth Structure before syncing when safe and in scope; otherwise block and recommend Truth Structure - report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Blocked reason as applicable -Product Decisions/Rationale preservation gate: -- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions and Rationale sections in every source or touched truth doc -- preserve each current decision and rationale in the bounded owner doc it governs; when splitting, move it to the new owner doc rather than deleting it or leaving it in an index +Decision/Rationale preservation gate: +- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions, Engineering Decisions, and Rationale sections in every source or touched truth doc +- preserve each current decision and rationale in the correct product or engineering lane owner; when splitting, move it to the new owner doc rather than deleting it or leaving it in an index - remove or narrow a decision or rationale only when checkout evidence shows it is stale or unsupported, and report the exact claim, evidence, and result - if ownership of a decision or rationale is unclear, block with manual-review files instead of deleting it or guessing -- after the edit, verify every touched truth doc still has Product Decisions and Rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked +- after the edit, verify every touched truth doc keeps lane-appropriate decision/rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked When creating or updating a truth doc, inspect the routed truth kind and use the matching template under the configured Truthmark templates root. -Supported kinds: behavior, contract, architecture, workflow, operations, and test-behavior. +Supported kinds: product-capability, engineering-behavior, engineering-contract, engineering-architecture, engineering-workflow, engineering-operations, and engineering-test-behavior. Treat the HTML comments under each template section as normative authoring guidance for that section. Align existing docs to that template and write or repair section content so it satisfies the comment guidance while preserving accurate authored content. -If the template is missing, use Scope, Product Decisions, Rationale, and the kind-specific current-truth section. +If the template is missing, use lane-specific sections: product truth says what must be true and why; engineering truth says how the repository currently realizes it. Teams may edit template files under the configured Truthmark templates root to define their local truth-doc standards. Truth-doc shape repair gate: -- Truth Sync may restructure only truth docs impacted by the current functional-code change. +- Truth Sync may restructure leased canonical truth docs when the current sync evidence shows repository truth is stale, even when the doc is outside the initially affected route focus. - repair shape in place only after the ownership gate confirms the doc is the right bounded owner - use Truth Structure for ownership splits; do not treat broad or mixed-owner docs as in-place repair work - repair shape when a narrow edit would make truth worse: missing template sections, stale evidence conflicts, cross-section updates within one owner, or wrong frontmatter/source/headings @@ -51,19 +61,19 @@ Maintain architecture docs only for structure-level changes: system structure, m Keep ordinary behavior, endpoints, UI copy, validation rules, and bug fixes in behavior or contract docs unless they change those boundaries. Evidence Gate: - route-first: map changed functional files to bounded route owners and primary canonical docs -- review new or changed behavior-bearing claims only in touched docs, route ownership, Product Decisions, and Rationale +- review new or changed behavior-bearing claims only in touched docs, route ownership, lane-specific decisions, and rationale - support claims with primary checkout evidence: implementation, config, routing, generated templates, schemas, or contract definitions - tests/examples/canonical docs corroborate; they are not sole proof when implementation conflicts - remove, narrow, or block unsupported claims - if no impacted doc changed, report why truth was already current or why sync was skipped -Repository intelligence artifacts are optional derived context: RepoIndex, RouteMap, ImpactSet, and ContextPack may guide routing, context selection, and verification planning when available. +Repository intelligence artifacts are optional derived context: RepoIndex, RouteMap, ImpactSet, and WorkflowState/action context may guide routing, write boundaries, and verification planning when available. They do not override checkout evidence, canonical truth docs, route files, or workflow write boundaries. If unavailable, inspect any present Truthmark config, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated. Optional validation tooling: - you may run truthmark check when local tooling is available - do not require the truthmark binary; direct checkout inspection is the canonical path - optional validation must not replace agent judgment about docs and routing -- update Product Decisions and Rationale when a behavior change comes from a decision change +- update Product Decisions only in product truth and Engineering Decisions only in engineering truth when evidence supports the lane-specific decision change Helper status reporting: - Validate the report body before adding this validator's own success status; the body may omit `validate-sync-report` while validation is pending. - After `truthmark validate sync-report --json` returns `data.validation.ok: true`, append or update `validate-sync-report: ran, passed` in the final report. @@ -74,16 +84,17 @@ Truthmark hierarchy hints: - Config, when present: .truthmark/config.yml - Root route index, when present: docs/truthmark/routes/areas.md - Area route files, when present: docs/truthmark/routes/areas/**/*.md -- Truth docs, when present: docs/truthmark/truth/**/*.md +- Product truth docs, when present: docs/truthmark/product/**/*.md +- Engineering truth docs, when present: docs/truthmark/engineering/**/*.md Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. -Update Product Decisions and Rationale when a decision changes behavior. +Product decisions belong in product truth; engineering, architecture, contract, workflow, and operational decisions belong in engineering truth. Parent post-sync verification: - verify only truth docs and leased truth routing files changed during sync - block on any unrelated diff caused by the sync step - block if functional code changed during sync - for each write lease, validate the worker report against the actual worker diff, allowedWrites, forbiddenWrites, identity fields, filesChanged, offLeaseChanges, blockers, and required report fields before accepting it - validate the final report against the structured Truth Sync report contract, including Claim, indented Evidence, and Result values supported, narrowed, removed, or blocked under Evidence checked -- verify the updated docs correspond to the reviewed changed-code surface +- verify the updated docs correspond to reviewed checkout evidence, changed-code impact, or a recorded stale-truth correction made within the sync write lease - verify the final report records ownership review, structure requirement, split, restructure, or blocked reason when the ownership gate fired - blocked outcomes must preserve the working tree as-is: no rollback, no post-block cleanup edits, and manual-review reporting of any remaining files diff --git a/.opencode/skills/truthmark-sync/support/report-template.md b/.opencode/skills/truthmark-sync/support/report-template.md index 4dfa42d..52f0ec1 100644 --- a/.opencode/skills/truthmark-sync/support/report-template.md +++ b/.opencode/skills/truthmark-sync/support/report-template.md @@ -1,6 +1,6 @@ # Truthmark Sync Report Template -Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. Report completion in this shape: ```md @@ -13,7 +13,7 @@ Ownership reviewed: - docs/truthmark/routes/areas.md Truth docs updated: -- docs/truthmark/truth/repository/overview.md +- docs/truthmark/engineering/repository/overview.md Evidence checked: - Claim: Session timeout behavior is documented in the mapped repository truth doc. diff --git a/.opencode/skills/truthmark-sync/support/subagents-and-leases.md b/.opencode/skills/truthmark-sync/support/subagents-and-leases.md index 57c829b..f7fe73d 100644 --- a/.opencode/skills/truthmark-sync/support/subagents-and-leases.md +++ b/.opencode/skills/truthmark-sync/support/subagents-and-leases.md @@ -1,6 +1,6 @@ # Truthmark Sync Subagents And Leases -Generated by Truthmark 2.1.0. Rerun truthmark init after upgrades. +Generated by Truthmark 2.2.1. Rerun truthmark init after upgrades. OpenCode subagent mode: - use automatically when this workflow runs in OpenCode and the parent agent chooses bounded subagent fan-out diff --git a/.truthmark/config.yml b/.truthmark/config.yml index b82fa05..3a84124 100644 --- a/.truthmark/config.yml +++ b/.truthmark/config.yml @@ -4,15 +4,6 @@ platforms: - opencode truthmark: workspace: docs/truthmark - routes: - index: routes/areas.md - areas: routes/areas - default_area: repository - max_delegation_depth: 1 - truth: - root: truth - templates: - root: templates generated: portal: enabled: true @@ -22,9 +13,7 @@ frontmatter: required: [] recommended: - status - - doc_type - last_reviewed - - source_of_truth ignore: - node_modules/** - vendor/** diff --git a/AGENTS.md b/AGENTS.md index 8fdaa81..5901bf1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -18,11 +18,13 @@ Direct Codex execution is the default path via `opengamestudio run `. `--d Project-specific agent instructions are also mirrored in `docs/ai/repo-rules.md` for Truthmark authority discovery. Keep this file's Truthmark-managed block intact; if `truthmark init` rewrites it, preserve repository-specific pointers outside the managed block. +Read `docs/architecture/product-boundary.md` before creating or revising designs, implementation plans, OpenSpec changes, generated project surfaces, role/workflow expansions, approval/write-policy behavior, or runtime execution behavior. + ## Truthmark Workflow -Generated by Truthmark 2.1.0. Rerun `truthmark init` after upgrades. -Hierarchy hints: config .truthmark/config.yml when present; routes docs/truthmark/routes/areas.md and docs/truthmark/routes/areas/**/*.md when present; Truth docs: docs/truthmark/truth/**/*.md when present. +Generated by Truthmark 2.2.1. Rerun `truthmark init` after upgrades. +Hierarchy hints: config .truthmark/config.yml when present; routes docs/truthmark/routes/areas.md and docs/truthmark/routes/areas/**/*.md when present; Truth docs: docs/truthmark/product/**/*.md and docs/truthmark/engineering/**/*.md when present. Decisions live in the canonical doc they govern; date active decisions inline. Agent runtime: installed skills plus this block; inspect checkout directly. Delegation is host-owned. ### Truth Sync diff --git a/docs/ai/repo-rules.md b/docs/ai/repo-rules.md index a20b44c..05fdca7 100644 --- a/docs/ai/repo-rules.md +++ b/docs/ai/repo-rules.md @@ -23,6 +23,7 @@ This file mirrors the repository-specific agent rules from `AGENTS.md` in the co - Direct Codex execution is the default path via `opengamestudio run `. - `--dry-run` and `--print-prompt` are inspection-only paths. - Telemetry, planner/next, ownership enforcement, and parallel orchestration are future-only. +- Read `docs/architecture/product-boundary.md` before creating or revising designs, implementation plans, OpenSpec changes, generated project surfaces, role/workflow expansions, approval/write-policy behavior, or runtime execution behavior. ## Truthmark Notes diff --git a/docs/architecture/flows/README.md b/docs/architecture/flows/README.md index 9376c1a..180ea47 100644 --- a/docs/architecture/flows/README.md +++ b/docs/architecture/flows/README.md @@ -5,7 +5,7 @@ truth_kind: architecture last_reviewed: 2026-05-30 source_of_truth: - ../repository-structure.md - - ../../truthmark/truth/repository/overview.md + - ../../truthmark/engineering/repository/overview.md --- # Architecture Flow Guides @@ -29,7 +29,7 @@ Truthmark truth docs own canonical behavior claims. Architecture flow guides own | Layer | Purpose | Example | | --- | --- | --- | -| Truth docs | Bounded, canonical behavior/reference claims | `docs/truthmark/truth/codex/runtime-and-tasks.md` | +| Truth docs | Bounded, canonical behavior/reference claims | `docs/truthmark/engineering/codex/runtime-and-tasks.md` | | Flow guides | Cross-cutting runtime scenarios, branches, and debugging paths | `docs/architecture/flows/role-run-lifecycle.md` | | Portal | Generated non-canonical presentation | `docs/truthmark/generated/portal/` | @@ -39,10 +39,10 @@ If a flow guide conflicts with source code or a truth doc, the source code and o | Flow guide | Scenario | Primary truth docs | | --- | --- | --- | -| [Project Initialization](project-initialization.md) | `init` / `new` creates a deterministic generated game project. | `docs/truthmark/truth/projects/project-scaffolding.md` | -| [Role Run Lifecycle](role-run-lifecycle.md) | `run ` renders, executes, verifies, reviews, and optionally fixes a Codex role run. | `docs/truthmark/truth/codex/runtime-and-tasks.md`, `docs/truthmark/truth/codex/roles-and-workflows.md` | -| [Workflow Prompt Rendering](workflow-prompt-rendering.md) | Workflow shortcut commands render deterministic prompts without executing Codex. | `docs/truthmark/truth/codex/roles-and-workflows.md` | -| [Validation And Repository Truth](validation-and-repository-truth.md) | Repository/project validation and injected Truthmark repository-truth workflows around behavior changes. | `docs/truthmark/truth/contracts/cli-and-validation.md`, `docs/truthmark/truth/repository/overview.md` | +| [Project Initialization](project-initialization.md) | `init` / `new` creates a deterministic generated game project. | `docs/truthmark/engineering/projects/project-scaffolding.md` | +| [Role Run Lifecycle](role-run-lifecycle.md) | `run ` renders, executes, verifies, reviews, and optionally fixes a Codex role run. | `docs/truthmark/engineering/codex/runtime-and-tasks.md`, `docs/truthmark/engineering/codex/roles-and-workflows.md` | +| [Workflow Prompt Rendering](workflow-prompt-rendering.md) | Workflow shortcut commands render deterministic prompts without executing Codex. | `docs/truthmark/engineering/codex/roles-and-workflows.md` | +| [Validation And Repository Truth](validation-and-repository-truth.md) | Repository/project validation and injected Truthmark repository-truth workflows around behavior changes. | `docs/truthmark/engineering/contracts/cli-and-validation.md`, `docs/truthmark/engineering/repository/overview.md` | ## Guide Template diff --git a/docs/architecture/flows/project-initialization.md b/docs/architecture/flows/project-initialization.md index db8dcfa..3a75d23 100644 --- a/docs/architecture/flows/project-initialization.md +++ b/docs/architecture/flows/project-initialization.md @@ -4,8 +4,8 @@ doc_type: architecture truth_kind: architecture last_reviewed: 2026-05-30 source_of_truth: - - ../../truthmark/truth/projects/project-scaffolding.md - - ../../truthmark/truth/repository/overview.md + - ../../truthmark/engineering/projects/project-scaffolding.md + - ../../truthmark/engineering/repository/overview.md - ../repository-structure.md --- @@ -101,11 +101,11 @@ flowchart TD | Condition | Branch | Behavior | User-visible result | Owning code/truth | | --- | --- | --- | --- | --- | -| Required option missing | CLI parse failure | Stop before initialization. | Commander error. | `src/cli.ts`; `docs/truthmark/truth/contracts/cli-and-validation.md` | -| `--non-interactive` missing | Determinism guard | Stop before writing. | Required option error. | `src/cli.ts`; `docs/truthmark/truth/projects/project-scaffolding.md` | -| Engine is unknown | Engine registry guard | Stop before writing. | Invalid engine/lookup failure. | `src/engines.ts`; `docs/truthmark/truth/projects/project-scaffolding.md` | -| Target path exists | Collision guard | Stop before mutating target. | Existing project/path error. | `src/projects.ts`; `docs/truthmark/truth/projects/project-scaffolding.md` | -| Collision checks pass | Happy path | Write generated project surfaces. | `Created at `. | `src/projects.ts`; `docs/truthmark/truth/projects/project-scaffolding.md` | +| Required option missing | CLI parse failure | Stop before initialization. | Commander error. | `src/cli.ts`; `docs/truthmark/engineering/contracts/cli-and-validation.md` | +| `--non-interactive` missing | Determinism guard | Stop before writing. | Required option error. | `src/cli.ts`; `docs/truthmark/engineering/projects/project-scaffolding.md` | +| Engine is unknown | Engine registry guard | Stop before writing. | Invalid engine/lookup failure. | `src/engines.ts`; `docs/truthmark/engineering/projects/project-scaffolding.md` | +| Target path exists | Collision guard | Stop before mutating target. | Existing project/path error. | `src/projects.ts`; `docs/truthmark/engineering/projects/project-scaffolding.md` | +| Collision checks pass | Happy path | Write generated project surfaces. | `Created at `. | `src/projects.ts`; `docs/truthmark/engineering/projects/project-scaffolding.md` | ## Generated Outputs @@ -154,9 +154,9 @@ A bounded initialization flow gives users and agents a stable project scaffold w ## Truth Sources -- `docs/truthmark/truth/projects/project-scaffolding.md` -- `docs/truthmark/truth/repository/overview.md` -- `docs/truthmark/truth/contracts/cli-and-validation.md` +- `docs/truthmark/engineering/projects/project-scaffolding.md` +- `docs/truthmark/engineering/repository/overview.md` +- `docs/truthmark/engineering/contracts/cli-and-validation.md` - `docs/truthmark/routes/areas/repository.md` ## Verification diff --git a/docs/architecture/flows/role-run-lifecycle.md b/docs/architecture/flows/role-run-lifecycle.md index c355158..32db5e1 100644 --- a/docs/architecture/flows/role-run-lifecycle.md +++ b/docs/architecture/flows/role-run-lifecycle.md @@ -4,9 +4,9 @@ doc_type: architecture truth_kind: architecture last_reviewed: 2026-05-30 source_of_truth: - - ../../truthmark/truth/codex/runtime-and-tasks.md - - ../../truthmark/truth/codex/roles-and-workflows.md - - ../../truthmark/truth/contracts/cli-and-validation.md + - ../../truthmark/engineering/codex/runtime-and-tasks.md + - ../../truthmark/engineering/codex/roles-and-workflows.md + - ../../truthmark/engineering/contracts/cli-and-validation.md --- # Role Run Lifecycle Flow Guide @@ -146,7 +146,7 @@ flowchart TD | Failure | Likely cause | Inspect | | --- | --- | --- | -| Unknown role | Role ID typo or role registry drift. | `src/roles.ts`, `docs/truthmark/truth/codex/roles-and-workflows.md`. | +| Unknown role | Role ID typo or role registry drift. | `src/roles.ts`, `docs/truthmark/engineering/codex/roles-and-workflows.md`. | | Empty objective | User omitted objective and `--task`. | `src/cli.ts`, `src/runner.ts`. | | Codex unavailable | CLI missing, unauthenticated, or command path invalid. | `src/codex-runtime.ts`. | | Verification timeout/failure | Verification command failed or exceeded timeout. | `src/verification.ts`, command output. | @@ -177,9 +177,9 @@ Separating inspection, implementation, verification, review, and fix branches ma ## Truth Sources -- `docs/truthmark/truth/codex/runtime-and-tasks.md` -- `docs/truthmark/truth/codex/roles-and-workflows.md` -- `docs/truthmark/truth/contracts/cli-and-validation.md` +- `docs/truthmark/engineering/codex/runtime-and-tasks.md` +- `docs/truthmark/engineering/codex/roles-and-workflows.md` +- `docs/truthmark/engineering/contracts/cli-and-validation.md` - `docs/truthmark/routes/areas/repository.md` ## Verification diff --git a/docs/architecture/flows/validation-and-repository-truth.md b/docs/architecture/flows/validation-and-repository-truth.md index 08417d5..639a584 100644 --- a/docs/architecture/flows/validation-and-repository-truth.md +++ b/docs/architecture/flows/validation-and-repository-truth.md @@ -4,8 +4,8 @@ doc_type: architecture truth_kind: architecture last_reviewed: 2026-05-30 source_of_truth: - - ../../truthmark/truth/contracts/cli-and-validation.md - - ../../truthmark/truth/repository/overview.md + - ../../truthmark/engineering/contracts/cli-and-validation.md + - ../../truthmark/engineering/repository/overview.md - ../../truthmark/routes/areas/repository.md --- @@ -38,7 +38,7 @@ Repository validation is an Open Game Studio package behavior implemented by the | `npm run validate` | Repository readiness gate that builds/tests/validates through package scripts. | `package.json` | | `npx truthmark check --json` | Injected repository-truth consistency check. | Truthmark tooling, `.truthmark/config.yml` | | Truthmark route files | Map code surfaces to bounded truth docs. | `docs/truthmark/routes/areas.md`, `docs/truthmark/routes/areas/repository.md` | -| Truth docs | Canonical bounded behavior/reference docs. | `docs/truthmark/truth/**` | +| Truth docs | Canonical bounded behavior/reference docs. | `docs/truthmark/engineering/**` | ## Preconditions @@ -54,7 +54,7 @@ Repository validation is an Open Game Studio package behavior implemented by the | Project path | `--project` | no | Adds generated-project validation checks. | | Truthmark config | `.truthmark/config.yml` | for Truthmark checks | Configures doc roots, routes, and generated surfaces. | | Route docs | `docs/truthmark/routes/areas*.md` | for Truthmark checks | Map code/doc surfaces to bounded truth docs. | -| Truth docs | `docs/truthmark/truth/**` | for Truthmark checks | Canonical behavior/reference claims. | +| Truth docs | `docs/truthmark/engineering/**` | for Truthmark checks | Canonical behavior/reference claims. | ## Happy Path Sequence @@ -109,7 +109,7 @@ flowchart TD | --- | --- | --- | --- | --- | | Source/package behavior changed | Functional validation branch | Run relevant tests and `npm run validate`. | Failing package/project check if contract is broken. | Open Game Studio repo | | Generated project behavior changed | Project validation branch | Validate generated-project contracts. | Missing/invalid generated surface diagnostic. | `src/validation.ts` and scaffold owners | -| Public CLI claim changed | CLI contract branch | Update contract truth doc and validation/readme claims together. | Validation or doc drift if missed. | `docs/truthmark/truth/contracts/cli-and-validation.md` | +| Public CLI claim changed | CLI contract branch | Update contract truth doc and validation/readme claims together. | Validation or doc drift if missed. | `docs/truthmark/engineering/contracts/cli-and-validation.md` | | Behavior claim changed | Truth sync branch | Update owning bounded truth doc. | Truthmark may flag stale/unmapped surfaces. | Truthmark docs workflow | | Flow comprehension changed | Runtime-view branch | Update affected architecture flow guide after truth doc. | Stale walkthrough if missed. | `docs/architecture/flows/**` | | Truthmark generated surface changed | Injected workflow branch | Preserve managed blocks and run Truthmark check/init only when appropriate. | Generated surface diagnostic. | Truthmark tooling layer | @@ -121,7 +121,7 @@ flowchart TD | Validation check fails | Package metadata, source, templates, build output, or project scaffold drift. | `src/validation.ts`, failing check ID. | | Future-surface guard fails | CLI/docs exposed unimplemented planner/telemetry/parallel/ownership surface. | `src/cli.ts`, README/docs, validation tests. | | Truthmark reports route/topology issue | Code or docs moved outside bounded route ownership. | `docs/truthmark/routes/areas.md`, `docs/truthmark/routes/areas/repository.md`. | -| Truth doc and flow guide diverge | Flow guide was updated without updating canonical truth or vice versa. | Owning `docs/truthmark/truth/**` file and affected `docs/architecture/flows/**` file. | +| Truth doc and flow guide diverge | Flow guide was updated without updating canonical truth or vice versa. | Owning `docs/truthmark/engineering/**` file and affected `docs/architecture/flows/**` file. | | Portal output stale | Generated non-canonical site not refreshed after Markdown changes. | `docs/truthmark/generated/portal/` and portal provenance. | ## Code And Document Traceability @@ -130,10 +130,10 @@ flowchart TD | --- | --- | | CLI validation command wiring | `src/cli.ts` | | Validation checks and project contract diagnostics | `src/validation.ts` | -| Package scripts/bin/files contract | `package.json`, `docs/truthmark/truth/contracts/cli-and-validation.md` | +| Package scripts/bin/files contract | `package.json`, `docs/truthmark/engineering/contracts/cli-and-validation.md` | | Truthmark config and generated workflow surfaces | `.truthmark/config.yml`, generated agent files | | Truth routing | `docs/truthmark/routes/areas.md`, `docs/truthmark/routes/areas/repository.md` | -| Bounded canonical behavior docs | `docs/truthmark/truth/**` | +| Bounded canonical behavior docs | `docs/truthmark/engineering/**` | | Cross-cutting runtime scenario explanations | `docs/architecture/flows/**` | | Generated presentation output | `docs/truthmark/generated/portal/` | @@ -149,8 +149,8 @@ Keeping validation and repository-truth checks adjacent but distinct prevents in ## Truth Sources -- `docs/truthmark/truth/contracts/cli-and-validation.md` -- `docs/truthmark/truth/repository/overview.md` +- `docs/truthmark/engineering/contracts/cli-and-validation.md` +- `docs/truthmark/engineering/repository/overview.md` - `docs/truthmark/routes/areas/repository.md` - `.truthmark/config.yml` diff --git a/docs/architecture/flows/workflow-prompt-rendering.md b/docs/architecture/flows/workflow-prompt-rendering.md index 018ad4b..8e80722 100644 --- a/docs/architecture/flows/workflow-prompt-rendering.md +++ b/docs/architecture/flows/workflow-prompt-rendering.md @@ -4,8 +4,8 @@ doc_type: architecture truth_kind: architecture last_reviewed: 2026-05-30 source_of_truth: - - ../../truthmark/truth/codex/roles-and-workflows.md - - ../../truthmark/truth/contracts/cli-and-validation.md + - ../../truthmark/engineering/codex/roles-and-workflows.md + - ../../truthmark/engineering/contracts/cli-and-validation.md --- # Workflow Prompt Rendering Flow Guide @@ -118,7 +118,7 @@ flowchart TD | Project resolution failure | Missing or invalid `.codex/studio.json`. | `src/tasks.ts`, generated project state. | | Alias drift | CLI alias and workflow registry diverged. | `src/cli.ts`, `src/workflows.ts`. | | Missing template content | Package asset drift or template registry error. | `src/templates.ts`, `templates/**`, package files. | -| Prompt claim overstates automation | Documentation or prompt text implies unimplemented planner/execution behavior. | `src/workflows.ts`, `docs/truthmark/truth/codex/roles-and-workflows.md`. | +| Prompt claim overstates automation | Documentation or prompt text implies unimplemented planner/execution behavior. | `src/workflows.ts`, `docs/truthmark/engineering/codex/roles-and-workflows.md`. | ## Code Traceability @@ -141,9 +141,9 @@ Keeping workflow commands render-only lets users inspect and hand off workflow p ## Truth Sources -- `docs/truthmark/truth/codex/roles-and-workflows.md` -- `docs/truthmark/truth/contracts/cli-and-validation.md` -- `docs/truthmark/truth/repository/overview.md` +- `docs/truthmark/engineering/codex/roles-and-workflows.md` +- `docs/truthmark/engineering/contracts/cli-and-validation.md` +- `docs/truthmark/engineering/repository/overview.md` - `docs/truthmark/routes/areas/repository.md` ## Verification diff --git a/docs/architecture/product-boundary.md b/docs/architecture/product-boundary.md new file mode 100644 index 0000000..7e087e2 --- /dev/null +++ b/docs/architecture/product-boundary.md @@ -0,0 +1,107 @@ +--- +status: active +doc_type: architecture +truth_kind: architecture +last_reviewed: 2026-06-13 +source_of_truth: + - ../../README.md + - ../../AGENTS.md + - ../truthmark/engineering/repository/overview.md + - ../truthmark/engineering/codex/runtime-and-tasks.md + - ../truthmark/engineering/codex/roles-and-workflows.md + - ../truthmark/engineering/contracts/cli-and-validation.md +--- + +# Open Game Studio Product Boundary + +**Audience:** humans and agents designing, planning, or changing Open Game Studio. + +**Use:** read this before creating or revising product designs, implementation plans, OpenSpec changes, role/workflow expansions, approval policy, generated project surfaces, or runtime execution behavior. + +## Mission + +Open Game Studio helps developers use Codex as a practical game-development studio inside a local repository. + +The product should make it easier to start, plan, build, review, and ship games by providing a package-friendly TypeScript CLI that creates project scaffolds, renders bounded Codex prompts, manages game-studio roles and workflows, records auditable project state, and validates the generated surfaces. + +The product exists to expand what a developer can do with Codex for game creation. It must not turn game development into mandatory studio ceremony, hide the developer's intent behind an opaque orchestrator, or replace human creative and technical judgment. + +## Product Shape + +Open Game Studio is: + +- a local-first CLI and package for game-development repository workflows; +- Codex-native in its primary execution path; +- oriented around generated project files such as `AGENTS.md`, `.codex/**`, templates, tasks, and validation output; +- useful for both solo/prototype work and more structured studio-style work; +- explicit about when it is rendering prompts, running Codex, mutating project state, or only inspecting planned behavior. + +Open Game Studio is not: + +- a game engine or replacement for engine tooling; +- a hosted service, daemon, IDE, or background workflow controller; +- a general-purpose agent orchestrator or arbitrary workflow DAG engine; +- a hidden memory, checkpoint, telemetry, or analytics platform; +- a CI, merge-approval, or release-enforcement product; +- a requirements-management system or heavyweight studio-process mandate; +- a clone of any reference game-studio framework or workflow library. + +External tools, reference workflows, and comparison projects may inspire improvements, but designs must translate those ideas into Open Game Studio's local, Codex-native, package-friendly boundary. + +## Core Behavior Expectations + +1. **Codex-native by default.** Direct Codex execution through `opengamestudio run ` remains the primary runtime path. Inspection paths such as `--dry-run` and `--print-prompt` must stay non-mutating. +2. **Local repository files stay reviewable.** Project state, prompts, tasks, approvals, templates, and validation evidence should be visible in the working tree or deterministic CLI output, not hidden in off-repo services. +3. **Developer control comes first.** Studio depth is optional and mode-controlled. Fast prototype workflows must remain lightweight; strict approval flows must be explicit rather than silently imposed on every project. +4. **Project stage and studio strictness are separate.** Lifecycle stage (`design`, `prototype`, `development`) must not be collapsed into process strictness (`fast-prototype`, `guided-studio`, `strict-studio`). +5. **Generated instructions use `AGENTS.md` and `.codex/**`.** Do not add `CODEX.md`, legacy generated-project compatibility shims, or alternate instruction contracts unless a future boundary update explicitly changes this rule. +6. **Depth comes from selected context, not prompt bloat.** Registries may contain rich roles, workflows, engine references, and rules, but generated prompts should include only relevant selected material. +7. **Mutation is policy-gated and visible.** Any design that lets Codex or the CLI mutate files must specify write policy, approval/override behavior, sandbox selection, dry-run diagnostics, and where provenance is recorded. +8. **Future-only surfaces must remain absent until built.** Planner/next, telemetry, parallel orchestration, hard output-ownership enforcement, and similar surfaces must not appear as user-facing behavior before they have implementation, tests, and docs. +9. **Validation is part of the product.** New generated surfaces, package assets, CLI commands, and behavior-bearing docs need repo-native validation and tests before readiness or parity claims. +10. **Truthmark is repository workflow tooling here, not the product.** Truthmark-backed docs may guard Open Game Studio's repository truth, but Open Game Studio should not present Truthmark workflow mechanics as game-studio product features. + +## In Scope + +Designs and plans may expand or refine: + +- CLI commands for project initialization, status, templates, validation, tasks, approvals, role runs, and bounded workflow shortcuts; +- generated game project files under the project root, especially `AGENTS.md`, `.codex/**`, templates, tasks, approvals, context manifests, and selected runtime docs; +- role and workflow registries that improve game-development coverage while keeping materialized prompts bounded; +- engine references for Godot, Unity, and Unreal when they are packaged, validated, reviewed, and selected by relevance; +- approval and write-policy primitives that explain or gate mutating behavior; +- project validation, package smoke tests, and human-readable documentation that keep generated surfaces honest. + +## Out Of Scope Unless This Boundary Changes + +Designs and plans must not introduce these as required product behavior: + +- server-side orchestration, hosted accounts, daemons, schedulers, or background autonomous loops; +- hidden long-term memory or opaque state outside the project/repository files; +- mandatory heavyweight studio process for small prototypes; +- non-Codex execution hosts as first-class runtime replacements; +- general task management, PR approval, CI enforcement, or release governance outside the game-studio CLI boundary; +- broad prompt generation that loads all agents, all templates, all engine references, or all docs for a single role task; +- compatibility layers for stale generated project formats unless an explicit migration design is approved. + +Optional integrations are acceptable only when the local Codex-native workflow remains understandable, reviewable, and usable without them. + +## Required Product Boundary Check For Designs And Plans + +Every design, plan, or OpenSpec change should answer these questions before implementation starts: + +- Which part of the mission does this improve for a game developer? +- Which in-scope product surface changes: CLI, generated project files, role/workflow registry, approval policy, validation, package assets, or docs? +- Does the design preserve lightweight prototype use, or does it force unnecessary studio ceremony? +- Does it preserve Codex-native execution and the `AGENTS.md` / `.codex/**` generated-surface contract? +- What local files or deterministic outputs let a human review the change? +- What writes are allowed, what writes are forbidden, and what fails closed? +- What context is selected, and what prevents loading everything by default? +- Does it accidentally introduce a hosted service, daemon, orchestrator, hidden memory layer, CI gate, or heavyweight lifecycle platform? +- What tests, validation commands, and behavior-bearing docs prove the boundary remains intact? + +If a design or plan cannot answer these questions, it is not ready to implement. + +## Maintenance Notes + +Update this boundary when Open Game Studio's mission, runtime model, generated-surface contract, approval/write-policy model, package boundary, or explicit non-goals change. Keep it human-facing: concise enough to read before planning, concrete enough to stop product drift. diff --git a/docs/architecture/repository-structure.md b/docs/architecture/repository-structure.md index c9c6373..b9abd3b 100644 --- a/docs/architecture/repository-structure.md +++ b/docs/architecture/repository-structure.md @@ -15,7 +15,7 @@ Open Game Studio is a Node/TypeScript CLI package that installs and operates Cod ## Scope -This architecture note records the top-level repository boundaries needed by Truthmark routing. Bounded behavior details live in leaf docs under `docs/truthmark/truth/**`; cross-cutting runtime scenario walkthroughs live in `docs/architecture/flows/**`. +This architecture note records the top-level repository boundaries needed by Truthmark routing. Product mission and non-goal guardrails live in `docs/architecture/product-boundary.md`. Bounded behavior details live in leaf docs under `docs/truthmark/engineering/**`; cross-cutting runtime scenario walkthroughs live in `docs/architecture/flows/**`. ## Components diff --git a/docs/plans/2026-05-28-codex-game-studio-functionality-gap-pass.md b/docs/plans/2026-05-28-codex-game-studio-functionality-gap-pass.md deleted file mode 100644 index c3639de..0000000 --- a/docs/plans/2026-05-28-codex-game-studio-functionality-gap-pass.md +++ /dev/null @@ -1,1394 +0,0 @@ -# Codex Game Studio Functionality Gap Pass Implementation Plan - -> **For Hermes:** Do not implement this plan until Merlin explicitly approves it. When approved, use subagent-driven-development skill to implement this plan task-by-task. Do not rewrite git history, push commits, or rename the package/repo unless Merlin explicitly asks. - -**Goal:** Fill the five major functionality gaps versus the Claude Game Studio baseline while preserving the Codex-native architecture: role roster parity, project-specific role materialization, market/analytics workflows, studio orchestration, and richer studio workflow depth. - -**Architecture:** Keep `.codex/studio.json` authoritative and `AGENTS.md` as the primary Codex instruction surface. Add richer Codex-native role packages and workflow specs rather than restoring legacy `.gamestudio` state, legacy agent aliases, or `project_orchestrator.md`. Keep the implementation file-backed, deterministic, package-friendly, and test-driven; telemetry, planner/`next`, hard ownership enforcement, and parallel orchestration remain future-only unless explicitly introduced by a later plan. - -**Tech Stack:** TypeScript, NodeNext ESM, npm CLI package, Vitest, Codex CLI, file-backed JSON/Markdown project state. - ---- - -## Scope - -This pass addresses the first five functionality gaps identified in the Claude Game Studio comparison: - -1. **Agent roster parity:** add missing specialized studio functions in Codex-native form. -2. **Project-specific agent materialization:** generate project-aware role prompt files, not just generic prompt stubs. -3. **Market/analytics workflows:** make market and analytics first-class renderable workflow prompts and role-owned inspection loops, not just templates selected by producer tasks. Workflow shortcut commands remain render-only in this pass; executable workflow lifecycle support is explicitly deferred. -4. **Studio orchestration:** add a Codex-native orchestration role/workflow without restoring legacy `project_orchestrator.md`. -5. **Workflow depth:** expand workflow files and CLI surfaces from thin prompt renderers into practical studio operating loops. - -## Non-Goals - -- Do not restore legacy `.gamestudio/*` state. -- Do not make `project-config.json` authoritative again. -- Do not add backwards-compatible legacy role aliases such as `producer_agent` or `qa_agent`. -- Do not generate `project_orchestrator.md`. -- Do not add interactive `menu` or `startover`. -- Do not add database-backed task storage. -- Do not add parallel orchestration. -- Do not add `opengamestudio next`, telemetry, changed-file tracking, or hard output-ownership enforcement in this pass. -- Do not eagerly generate full competitor reports during `init`; full reports belong to the market workflow. - -## Design Decisions - -### Role IDs - -Decision: use the expanded 16-role Codex-native superset and retain the existing `narrative-designer` role for compatibility and story/content coverage. This yields 17 total roles: the 16-role functionality-gap superset plus the retained current Codex-native narrative role. - -Keep Codex-native role IDs, but expand coverage to preserve the upstream functional roles while avoiding a silent compatibility cut: - -```ts -export const studioRoleIds = [ - "studio-orchestrator", - "producer", - "market-analyst", - "data-scientist", - "creative-director", - "senior-game-designer", - "game-designer", - "narrative-designer", - "game-feel-designer", - "gameplay-programmer", - "engine-programmer", - "tools-programmer", - "senior-game-artist", - "technical-artist", - "ui-ux-designer", - "qa-playtester", - "release-manager" -] as const; -``` - -Rationale: - -- This keeps existing Codex-native IDs where they already make sense. -- It adds explicit equivalents for upstream `master_orchestrator`, `market_analyst`, `data_scientist`, `game_feel_developer`, `sr_game_artist`, and `ui_ux_agent`. -- It splits senior/implementation design coverage without restoring underscore legacy names. -- It retains the existing Codex-native `narrative-designer` role so current projects, tests, and story/content workflows do not lose a first-class owner. -- It keeps existing `creative-director`, `engine-programmer`, `tools-programmer`, and `release-manager` as Codex-native value-add roles. - -### Parity Crosswalk and Legacy Alias Cut - -Decision: document functional parity as a role/function crosswalk, not as legacy role-ID compatibility. The implementation must reject representative legacy underscore aliases with clear guidance instead of silently accepting them. - -| Upstream / baseline function | Codex-native owner(s) | Compatibility decision | -|---|---|---| -| `master_orchestrator` / studio routing | `studio-orchestrator` | No `master_orchestrator` or `project_orchestrator.md`; use `handoff` workflow. | -| `producer_agent` / production planning | `producer`, `studio-orchestrator` | No `producer_agent` alias; use `producer`. | -| market research / competitor analysis | `market-analyst` | First-class renderable `market-analysis` workflow and `market` shortcut. | -| analytics / metrics / experiments | `data-scientist` | First-class renderable `analytics-setup` workflow and `analytics` shortcut. | -| creative direction | `creative-director` | Keep Codex-native hyphenated ID. | -| senior systems / economy / progression design | `senior-game-designer` | New explicit senior design owner. | -| feature / acceptance design | `game-designer` | Keep as implementation-level design owner. | -| story / world / content | `narrative-designer` | Retained Codex-native compatibility role. | -| game feel / controls / juice | `game-feel-designer` | New explicit feel owner. | -| gameplay implementation | `gameplay-programmer` | Keep Codex-native hyphenated ID. | -| engine/platform implementation | `engine-programmer` | Keep Codex-native value-add role. | -| internal tools/editor automation | `tools-programmer` | Keep Codex-native value-add role. | -| senior art direction / asset quality bar | `senior-game-artist` | New explicit senior art owner. | -| technical art / pipeline constraints | `technical-artist` | Keep Codex-native value-add role. | -| UI/UX / onboarding / accessibility | `ui-ux-designer` | New explicit UI/UX owner. | -| `qa_agent` / playtest / QA review | `qa-playtester` | No `qa_agent` alias; use `qa-playtester`. | -| release / ship readiness | `release-manager` | Keep Codex-native value-add role. | - -Acceptance tests must verify the Codex-native role IDs exist and representative legacy aliases such as `producer_agent`, `qa_agent`, and `master_orchestrator` are not treated as valid `StudioRoleId` values. - -### Active Roles by Mode - -Use functional parity with the upstream mode intent, adapted to Codex-native IDs: - -```ts -always: - studio-orchestrator - producer - market-analyst - data-scientist - -design: - creative-director - senior-game-designer - game-designer - narrative-designer - senior-game-artist - ui-ux-designer - -prototype: - senior-game-designer - game-designer - game-feel-designer - gameplay-programmer - qa-playtester - -development: - senior-game-designer - game-designer - game-feel-designer - gameplay-programmer - engine-programmer - tools-programmer - qa-playtester - senior-game-artist - technical-artist - ui-ux-designer - release-manager -``` - -### Authoritative Studio State Contract - -Decision: `.codex/studio.json` must distinguish the full available roster from mode-active roles. Keep `roles` as the full expanded role roster for discoverability, add an explicit `activeRoles` field for `activeAgentsForMode(mode)`, and populate `workflows` from `Object.keys(workflowRegistry)` after the canonical registry exists. - -Use this generated state contract or an equivalent typed shape: - -```ts -export type StudioProjectState = { - // existing fields omitted - roles: StudioRoleId[]; // full available Codex-native roster - activeRoles: StudioRoleId[]; // mode-active roles from activeAgentsForMode(mode) - workflows: WorkflowId[]; // generated from workflowRegistry keys -}; -``` - -`statusProject` should print `activeRoles` as active roles, not the full roster. Project validation must assert `roles` equals `studioRoleIds`, `activeRoles` equals `activeAgentsForMode(studio.mode)`, and `workflows` equals the canonical workflow registry keys. - -### Project Prompt Materialization - -Generated projects should contain project-aware prompt files: - -```text -projects// - AGENTS.md - .codex/ - studio.json - prompts/ - studio-orchestrator.md - producer.md - market-analyst.md - data-scientist.md - creative-director.md - senior-game-designer.md - game-designer.md - narrative-designer.md - game-feel-designer.md - gameplay-programmer.md - engine-programmer.md - tools-programmer.md - senior-game-artist.md - technical-artist.md - ui-ux-designer.md - qa-playtester.md - release-manager.md - workflows/ - vertical-slice.md - bugfix.md - playtest.md - market-analysis.md - analytics-setup.md - design-spec.md - game-feel-tuning.md - art-direction.md - ui-ux-review.md - production-milestone.md - handoff.md - review.md - ship-check.md -``` - -Only `src/agents.ts` owns generated project `AGENTS.md`. Project-specific prompt body generation may live in `src/agents.ts` or a new helper imported by it; do not put `AGENTS.md` body text in `src/projects.ts`. - -### Template Delivery for Workflow Prompts - -Decision: keep package templates as the source of truth and inline only the selected template bodies into rendered workflow prompts. Do not rely on project-relative `templates/...` paths unless a future customization feature deliberately materializes project-local template overrides. - -Use this contract: - -- Project context files remain project-relative and listed as context files, for example `AGENTS.md`, `.codex/studio.json`, `.codex/workflows/.md`, `documentation/design/gdd.md`, and `resources/market-research/market-overview.md`. -- Workflow templates are package assets selected by deterministic template IDs such as `market_analysis`, `analytics_setup`, `feature_spec`, and `handoff`. -- `renderWorkflowPrompt` must append a `## Workflow Templates` section containing only the selected template IDs and bodies. -- Each inlined template section must include both the template ID and package source path, for example: - -```markdown -## Workflow Templates - -### Template: market_analysis -Source: package:templates/market_analysis_template.md - -