From 164bae7ca34d7aaa0fb58085e4e8f9c3e28e2862 Mon Sep 17 00:00:00 2001 From: MerlinH Date: Thu, 25 Jun 2026 14:52:52 +0000 Subject: [PATCH] chore: require node 24 runtime --- .agents/skills/truthmark-check/SKILL.md | 5 ++ .../truthmark-check/support/procedure.md | 2 + .agents/skills/truthmark-document/SKILL.md | 7 ++ .../truthmark-document/helper-manifest.yml | 34 ++++++++++ .../support/helper-policy.md | 23 +++++++ .../truthmark-document/support/procedure.md | 9 ++- .../support/report-template.md | 3 + .agents/skills/truthmark-portal/SKILL.md | 4 ++ .../truthmark-portal/support/procedure.md | 2 + .agents/skills/truthmark-preview/SKILL.md | 25 ++++++++ .../truthmark-preview/agents/openai.yaml | 10 +++ .../truthmark-preview/support/procedure.md | 53 +++++++++++++++ .../support/report-template.md | 43 +++++++++++++ .../support/subagents-and-leases.md | 10 +++ .agents/skills/truthmark-realize/SKILL.md | 4 ++ .../truthmark-realize/support/procedure.md | 2 + .agents/skills/truthmark-structure/SKILL.md | 4 ++ .../truthmark-structure/support/procedure.md | 42 ++++++++---- .agents/skills/truthmark-sync/SKILL.md | 7 ++ .../skills/truthmark-sync/helper-manifest.yml | 34 ++++++++++ .../truthmark-sync/support/helper-policy.md | 23 +++++++ .../truthmark-sync/support/procedure.md | 64 ++++++++++++++++--- .../truthmark-sync/support/report-template.md | 26 ++++---- .codex/agents/truth-claim-verifier.toml | 2 +- .codex/agents/truth-doc-reviewer.toml | 2 +- .codex/agents/truth-route-auditor.toml | 2 +- .opencode/agents/truth-claim-verifier.md | 2 +- .opencode/agents/truth-doc-reviewer.md | 2 +- .opencode/agents/truth-route-auditor.md | 2 +- .opencode/skills/truthmark-check/SKILL.md | 5 ++ .../truthmark-check/support/procedure.md | 2 + .opencode/skills/truthmark-document/SKILL.md | 7 ++ .../truthmark-document/helper-manifest.yml | 34 ++++++++++ .../support/helper-policy.md | 23 +++++++ .../truthmark-document/support/procedure.md | 9 ++- .../support/report-template.md | 3 + .opencode/skills/truthmark-portal/SKILL.md | 4 ++ .../truthmark-portal/support/procedure.md | 2 + .opencode/skills/truthmark-preview/SKILL.md | 25 ++++++++ .../truthmark-preview/support/procedure.md | 53 +++++++++++++++ .../support/report-template.md | 43 +++++++++++++ .../support/subagents-and-leases.md | 10 +++ .opencode/skills/truthmark-realize/SKILL.md | 4 ++ .../truthmark-realize/support/procedure.md | 2 + .opencode/skills/truthmark-structure/SKILL.md | 4 ++ .../truthmark-structure/support/procedure.md | 42 ++++++++---- .opencode/skills/truthmark-sync/SKILL.md | 7 ++ .../skills/truthmark-sync/helper-manifest.yml | 34 ++++++++++ .../truthmark-sync/support/helper-policy.md | 23 +++++++ .../truthmark-sync/support/procedure.md | 64 ++++++++++++++++--- .../truthmark-sync/support/report-template.md | 26 ++++---- AGENTS.md | 2 +- CONTRIBUTING.md | 2 +- README.md | 4 +- docs/setup.md | 2 +- .../contracts/cli-and-validation.md | 2 +- package-lock.json | 32 +++++----- package.json | 6 +- src/validation.ts | 2 +- 59 files changed, 827 insertions(+), 99 deletions(-) create mode 100644 .agents/skills/truthmark-document/helper-manifest.yml create mode 100644 .agents/skills/truthmark-document/support/helper-policy.md create mode 100644 .agents/skills/truthmark-preview/SKILL.md create mode 100644 .agents/skills/truthmark-preview/agents/openai.yaml create mode 100644 .agents/skills/truthmark-preview/support/procedure.md create mode 100644 .agents/skills/truthmark-preview/support/report-template.md create mode 100644 .agents/skills/truthmark-preview/support/subagents-and-leases.md create mode 100644 .agents/skills/truthmark-sync/helper-manifest.yml create mode 100644 .agents/skills/truthmark-sync/support/helper-policy.md create mode 100644 .opencode/skills/truthmark-document/helper-manifest.yml create mode 100644 .opencode/skills/truthmark-document/support/helper-policy.md create mode 100644 .opencode/skills/truthmark-preview/SKILL.md create mode 100644 .opencode/skills/truthmark-preview/support/procedure.md create mode 100644 .opencode/skills/truthmark-preview/support/report-template.md create mode 100644 .opencode/skills/truthmark-preview/support/subagents-and-leases.md create mode 100644 .opencode/skills/truthmark-sync/helper-manifest.yml create mode 100644 .opencode/skills/truthmark-sync/support/helper-policy.md diff --git a/.agents/skills/truthmark-check/SKILL.md b/.agents/skills/truthmark-check/SKILL.md index 9f1c778..657657b 100644 --- a/.agents/skills/truthmark-check/SKILL.md +++ b/.agents/skills/truthmark-check/SKILL.md @@ -9,10 +9,15 @@ user-invocable: true Use this skill to audit repository truth health. +Invocations: OpenCode /skill truthmark-check; Codex /truthmark-check or $truthmark-check; Claude Code /truthmark-check; GitHub Copilot /truthmark-check; Gemini CLI /truthmark:check. + 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 canonical docs and relevant implementation directly. - Report issues and suggested fixes; do not silently rewrite unrelated files. +- Read support/procedure.md before auditing details. +- Read support/subagents-and-leases.md only when dispatching verifier subagents. +- Read support/report-template.md before the final report. Progressive disclosure: - support/procedure.md — read before edits or detailed auditing; contains core review questions diff --git a/.agents/skills/truthmark-check/support/procedure.md b/.agents/skills/truthmark-check/support/procedure.md index 9c5779f..35ef887 100644 --- a/.agents/skills/truthmark-check/support/procedure.md +++ b/.agents/skills/truthmark-check/support/procedure.md @@ -6,6 +6,8 @@ Truthmark-managed generated file. Refresh with truthmark init when truthmark che Use this skill to audit repository truth health. +Invocations: OpenCode /skill truthmark-check; Codex /truthmark-check or $truthmark-check; Claude Code /truthmark-check; GitHub Copilot /truthmark-check; Gemini CLI /truthmark:check. + Truth Check is agent-led: - inspect .truthmark/config.yml and configured route files only when they exist; then inspect canonical docs and relevant implementation directly diff --git a/.agents/skills/truthmark-document/SKILL.md b/.agents/skills/truthmark-document/SKILL.md index d5dec2f..3b346c9 100644 --- a/.agents/skills/truthmark-document/SKILL.md +++ b/.agents/skills/truthmark-document/SKILL.md @@ -9,13 +9,20 @@ user-invocable: true Use this skill to document existing implemented behavior when no functional-code changes are required for the task. +Invocations: OpenCode /skill truthmark-document; Codex /truthmark-document or $truthmark-document; Claude Code /truthmark-document; GitHub Copilot /truthmark-document; Gemini CLI /truthmark:document. + 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 existing canonical docs, implementation code, and tests directly. - Document current implemented behavior; do not invent future behavior. - May write canonical truth docs and truth routing files only; must not write functional code. +- Read support/procedure.md before editing truth docs. +- Read support/subagents-and-leases.md only when dispatching or accepting worker output. +- Read support/report-template.md before the final report. Progressive disclosure: - support/procedure.md — read before edits or detailed auditing; contains core review questions - support/report-template.md — read before the final report - support/subagents-and-leases.md — read only when using subagents, leases, or accepting worker output +- helper-manifest.yml — read only when invoking helper validators or validating helper registration +- support/helper-policy.md — read only when invoking helper validators or reporting helper status diff --git a/.agents/skills/truthmark-document/helper-manifest.yml b/.agents/skills/truthmark-document/helper-manifest.yml new file mode 100644 index 0000000..397d3f0 --- /dev/null +++ b/.agents/skills/truthmark-document/helper-manifest.yml @@ -0,0 +1,34 @@ +# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces. +helpers: + validate-document-report: + optional: true + runner: truthmark + command: + argv: + - truthmark + - validate + - document-report + - + - --json + inputs: + - document report file + output: json + writes: false + fallback: manually validate support/report-template.md required sections and structured Evidence checked entries + validate-write-lease: + optional: true + runner: truthmark + command: + argv: + - truthmark + - validate + - write-lease + - + - + - --json + inputs: + - lease or worker report yaml + - changed file list + output: json + writes: false + fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files diff --git a/.agents/skills/truthmark-document/support/helper-policy.md b/.agents/skills/truthmark-document/support/helper-policy.md new file mode 100644 index 0000000..671d0c4 --- /dev/null +++ b/.agents/skills/truthmark-document/support/helper-policy.md @@ -0,0 +1,23 @@ +# Optional Helper CLI Policy + +Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces. + +Optional helper CLI commands may collect deterministic checkout facts or validate artifacts. If the Truthmark CLI is unavailable or cannot return the declared helper output, continue manually using this procedure and report which helper was skipped. Helper output is derived evidence; it does not override direct checkout inspection, workflow write boundaries, or parent acceptance. + +Runner detection: +- Check that the declared Truthmark CLI runner is available before invoking a helper. +- Invoke helpers through the installed `truthmark validate ... --json` CLI command using argv-style arguments from helper-manifest.yml. +- If unavailable, failing, or returning incompatible output, treat the helper as skipped and use the manual fallback. +- Do not fail the workflow solely because a helper cannot run. + +Available helpers: +- validate-document-report: optional truthmark; manual fallback: manually validate support/report-template.md required sections and structured Evidence checked entries +- validate-write-lease: optional truthmark; manual fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files + +Final reports should include helper status when helpers are declared for this workflow: + +```md +Helper scripts: +- validate-document-report: ran, passed +- validate-write-lease: skipped, no write lease used +``` diff --git a/.agents/skills/truthmark-document/support/procedure.md b/.agents/skills/truthmark-document/support/procedure.md index eecba04..bbf485a 100644 --- a/.agents/skills/truthmark-document/support/procedure.md +++ b/.agents/skills/truthmark-document/support/procedure.md @@ -5,6 +5,7 @@ Truthmark-managed generated file. Refresh with truthmark init when truthmark che # Truthmark Document Use this skill to document existing implemented behavior when no functional-code changes are required for the task. +Invocations: OpenCode /skill truthmark-document; Codex /truthmark-document or $truthmark-document; Claude Code /truthmark-document; GitHub Copilot /truthmark-document; Gemini CLI /truthmark:document. Truth Document is manual and implementation-first: @@ -60,7 +61,6 @@ Treat the HTML comments under each template section as normative authoring guida Align existing docs to that template and write or repair section content so it satisfies the comment guidance while preserving accurate authored content. If the template is missing, use lane-specific sections: product truth says what must be true and why; engineering truth says how the repository currently realizes it. Teams may edit template files under the configured Truthmark templates root to define their local truth-doc standards. -Prefer diff-friendly Markdown: one durable claim per bullet or line, paragraphs no longer than one or two short sentences, and bullets or tables for rules, criteria, fields, files, and lists. Truth-doc shape repair review: - Truth Document may restructure only truth docs for the implemented behavior being documented. - repair shape in place only after the ownership review confirms the doc is the right bounded owner @@ -79,7 +79,12 @@ Truthmark hierarchy hints: 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. Product decisions belong in product truth; engineering, architecture, contract, workflow, and operational decisions belong in engineering truth. -Optional validation: when local tooling is available, you may validate the final report with `truthmark validate document-report --json`; direct checkout inspection and evidence review remain authoritative. +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. +- If the installed Truthmark CLI is unavailable or the helper is skipped, record `validate-document-report: skipped, ` and manually validate the report shape. +- Record `validate-write-lease: ran, passed` only after validating a concrete write lease; otherwise use a truthful skipped status such as `skipped, no write lease used`. +- Helper output is derived evidence and never replaces direct checkout inspection, evidence review, or parent acceptance. Parent post-document verification: - verify only truth docs and leased truth routing files changed during document work - stop on functional code, generated host surfaces, or unrelated diffs caused by document work diff --git a/.agents/skills/truthmark-document/support/report-template.md b/.agents/skills/truthmark-document/support/report-template.md index 29677aa..b0b05df 100644 --- a/.agents/skills/truthmark-document/support/report-template.md +++ b/.agents/skills/truthmark-document/support/report-template.md @@ -29,6 +29,9 @@ Evidence checked: Evidence: src/routing/area-resolver.ts:14 / docs/truthmark/routes/areas.md:9 Result: supported +Helper scripts: +- validate-write-lease: skipped, no write lease used + Notes: - Documented routing and behavior from route handlers and tests. ``` diff --git a/.agents/skills/truthmark-portal/SKILL.md b/.agents/skills/truthmark-portal/SKILL.md index e925915..75aaabb 100644 --- a/.agents/skills/truthmark-portal/SKILL.md +++ b/.agents/skills/truthmark-portal/SKILL.md @@ -9,6 +9,8 @@ user-invocable: true Use this skill only when the user explicitly asks to generate or refresh the committed static HTML Truthmark Portal. +Invocations: OpenCode /skill truthmark-portal; Codex /truthmark-portal or $truthmark-portal; Claude Code /truthmark-portal; GitHub Copilot /truthmark-portal; Gemini CLI /truthmark:portal. + Quick procedure: - Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists. - Truthmark Portal is manual-only; never run it automatically at completion and never treat it as Truth Sync. @@ -18,6 +20,8 @@ Quick procedure: - Write only under fixed Portal output docs/truthmark/generated/portal. - Use determined Portal template docs/truthmark/templates/portal.html when present; no .truthmark/index.json dependency. - Use no remote dependencies by default and include source provenance on every page. +- Read support/procedure.md before generating Portal output. +- Read support/report-template.md before the final report. Progressive disclosure: - support/procedure.md — read before edits or detailed auditing; contains core review questions diff --git a/.agents/skills/truthmark-portal/support/procedure.md b/.agents/skills/truthmark-portal/support/procedure.md index 02b217b..f04d2d1 100644 --- a/.agents/skills/truthmark-portal/support/procedure.md +++ b/.agents/skills/truthmark-portal/support/procedure.md @@ -6,6 +6,8 @@ Truthmark-managed generated file. Refresh with truthmark init when truthmark che Truthmark Portal is a manual-only presentation workflow. It is never an automatic completion workflow, never Truth Sync, and runs only when the user explicitly asks to generate, refresh, or update the committed static HTML Portal. +Invocations: OpenCode /skill truthmark-portal; Codex /truthmark-portal or $truthmark-portal; Claude Code /truthmark-portal; GitHub Copilot /truthmark-portal; Gemini CLI /truthmark:portal. + Core rules: - Markdown remains canonical; generated HTML is presentation only. diff --git a/.agents/skills/truthmark-preview/SKILL.md b/.agents/skills/truthmark-preview/SKILL.md new file mode 100644 index 0000000..2364bd6 --- /dev/null +++ b/.agents/skills/truthmark-preview/SKILL.md @@ -0,0 +1,25 @@ +--- +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 Preview + +Use this skill only when the user explicitly asks to preview Truthmark routing or workflow choice before edits. + +Invocations: OpenCode /skill truthmark-preview; Codex /truthmark-preview or $truthmark-preview; Claude Code /truthmark-preview; GitHub Copilot /truthmark-preview; Gemini CLI /truthmark:preview. + +Quick procedure: +- Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists. +- 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. +- Hand off to the selected workflow after user approval. + +Progressive disclosure: +- support/procedure.md — read before edits or detailed auditing; contains core review questions +- support/report-template.md — read before the final report +- support/subagents-and-leases.md — read only when using subagents, leases, or accepting worker output diff --git a/.agents/skills/truthmark-preview/agents/openai.yaml b/.agents/skills/truthmark-preview/agents/openai.yaml new file mode 100644 index 0000000..2e411a2 --- /dev/null +++ b/.agents/skills/truthmark-preview/agents/openai.yaml @@ -0,0 +1,10 @@ +interface: + display_name: "Truthmark Preview" + short_description: "Preview likely workflow routing before edits; read-only and explicit" + default_prompt: "Use $truthmark-preview to preview likely Truthmark routing before edits." + +policy: + allow_implicit_invocation: false + +truthmark: + refresh_command: "truthmark init" diff --git a/.agents/skills/truthmark-preview/support/procedure.md b/.agents/skills/truthmark-preview/support/procedure.md new file mode 100644 index 0000000..828cbda --- /dev/null +++ b/.agents/skills/truthmark-preview/support/procedure.md @@ -0,0 +1,53 @@ +# Truthmark Preview Procedure + +Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces. + +Use this skill only when the user explicitly asks to preview Truthmark routing or workflow choice before edits. + +Invocations: OpenCode /skill truthmark-preview; Codex /truthmark-preview or $truthmark-preview; Claude Code /truthmark-preview; GitHub Copilot /truthmark-preview; Gemini CLI /truthmark:preview. + +Truth Preview is read-only. Its report is intended, not authorized. + +Purpose: +- preview the likely Truthmark workflow, route owner, target files, expected write classes, suggested subagent use, and manual handoff questions before edits happen +- report likely product lane impact, engineering lane impact, target docs, and ambiguity before edits +- hand off to the selected workflow after user approval +- keep the selector thin so agents can avoid loading or acting through heavier workflows prematurely + +Read: +- .truthmark/config.yml, 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 +- 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 for manual handoff or routed to Truth Structure + - Do not make product docs a summary of engineering docs. Do not make engineering docs a detailed version of product docs. Product truth says what must be true and why. Engineering truth says how the repository currently realizes it. + +Do not: +- must not edit files +- must not create truth docs +- must not update routing +- must not run Truth Sync automatically +- must not replace Truth Check +- must not claim final correctness +- must not issue write leases +- must not mutate code + +Suggested subagent use: +- optional read-only verifier: truth_route_auditor +- write workers: none +- leases needed: none + +Truthmark hierarchy 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 +- 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 new file mode 100644 index 0000000..e0531b4 --- /dev/null +++ b/.agents/skills/truthmark-preview/support/report-template.md @@ -0,0 +1,43 @@ +# Truthmark Preview Report Template + +Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces. + +Report completion in this shape: +```md +Truth Preview: completed + +Requested outcome: +- preview likely Truthmark workflow routing before edits + +Likely workflow: +- truthmark-document + +Why this workflow: +- positive trigger: document existing implemented behavior +- negative triggers considered: functional-code change, doc-first implementation, topology repair, truth audit +- forbidden adjacency considered: must not edit functional code + +Likely route owner: +- route file: docs/truthmark/routes/areas.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/engineering/behaviors/example.md + +Suggested subagent use: +- read-only verifiers: truth_route_auditor +- write workers: none in Preview +- leases needed: none in Preview + +Manual handoff questions: +- none identified in preview + +Handoff: +- Run the selected Truthmark workflow after user approval. +``` diff --git a/.agents/skills/truthmark-preview/support/subagents-and-leases.md b/.agents/skills/truthmark-preview/support/subagents-and-leases.md new file mode 100644 index 0000000..bdc7347 --- /dev/null +++ b/.agents/skills/truthmark-preview/support/subagents-and-leases.md @@ -0,0 +1,10 @@ +# Truthmark Preview Subagents And Leases + +Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces. + +Codex subagent mode: +- use automatically when this workflow runs in Codex and the parent agent chooses bounded subagent fan-out +- dispatch read-only project agents only: truth_route_auditor +- workers inspect checkout evidence directly, return structured findings, and must not edit files +- parent supplies bounded evidence shards; workers must not preload host instruction files or repo-wide policy docs unless assigned as evidence +- Parent agent owns the final Truth Preview report diff --git a/.agents/skills/truthmark-realize/SKILL.md b/.agents/skills/truthmark-realize/SKILL.md index 1577854..494bd1a 100644 --- a/.agents/skills/truthmark-realize/SKILL.md +++ b/.agents/skills/truthmark-realize/SKILL.md @@ -9,11 +9,15 @@ user-invocable: true Use this skill only when the user explicitly asks to realize truth docs into code. +Invocations: OpenCode /skill truthmark-realize; Codex /truthmark-realize or $truthmark-realize; Claude Code /truthmark-realize; GitHub Copilot /truthmark-realize; Gemini CLI /truthmark:realize. + Quick procedure: - Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists. - Read the source truth docs, inspect .truthmark/config.yml and configured route files (docs/truthmark/routes/areas.md; docs/truthmark/routes/areas/) only when they exist, then inspect tests and relevant functional code directly. - Truth docs lead; code follows. - may write functional code only; must not edit truth docs or truth routing while realizing those docs. +- Read support/procedure.md before changing code. +- Read support/report-template.md before the final report. Progressive disclosure: - support/procedure.md — read before edits or detailed auditing; contains core review questions diff --git a/.agents/skills/truthmark-realize/support/procedure.md b/.agents/skills/truthmark-realize/support/procedure.md index f6b3200..f587ef7 100644 --- a/.agents/skills/truthmark-realize/support/procedure.md +++ b/.agents/skills/truthmark-realize/support/procedure.md @@ -6,6 +6,8 @@ Truthmark-managed generated file. Refresh with truthmark init when truthmark che Use this skill only when the user explicitly asks to realize truth docs into code. +Invocations: OpenCode /skill truthmark-realize; Codex /truthmark-realize or $truthmark-realize; Claude Code /truthmark-realize; GitHub Copilot /truthmark-realize; Gemini CLI /truthmark:realize. + Truth Realize is doc-first: - truth docs lead diff --git a/.agents/skills/truthmark-structure/SKILL.md b/.agents/skills/truthmark-structure/SKILL.md index aec71ae..4dccdce 100644 --- a/.agents/skills/truthmark-structure/SKILL.md +++ b/.agents/skills/truthmark-structure/SKILL.md @@ -9,11 +9,15 @@ user-invocable: true 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. + 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 current docs and relevant code directly. - Define areas by product or behavior ownership, not by mechanical directory mirroring. - Do not edit functional code. +- Read support/procedure.md before writing route or starter truth-doc changes. +- Read support/report-template.md before the final report. Progressive disclosure: - support/procedure.md — read before edits or detailed auditing; contains core review questions diff --git a/.agents/skills/truthmark-structure/support/procedure.md b/.agents/skills/truthmark-structure/support/procedure.md index 16f39e5..2a8ecb6 100644 --- a/.agents/skills/truthmark-structure/support/procedure.md +++ b/.agents/skills/truthmark-structure/support/procedure.md @@ -3,7 +3,7 @@ Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces. Use this skill to design or repair Truthmark area structure. - +Invocations: OpenCode /skill truthmark-structure; Codex /truthmark-structure or $truthmark-structure; Claude Code /truthmark-structure; GitHub Copilot /truthmark-structure; Gemini CLI /truthmark:structure. Truth Structure is agent-native: - inspect repository layout, current docs, Truthmark config and route files when present, and relevant code directly - Evidence authority: @@ -19,15 +19,20 @@ Truth Structure is agent-native: - 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 skeletal starter truth docs only when missing ownership would otherwise block future workflows +- 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, truth_kind, and last_reviewed inside that frontmatter. Put source references in the final ## Source References section, not in frontmatter. -- Starter truth docs are ownership anchors, not behavior writeups: include only the title, bounded area/scope, and Source References needed to make routing explicit. -- Starter truth docs must keep product and engineering truth in separate files; leave substantive behavior, contract, architecture, workflow, operations, or test prose to Truth Document. +- 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: 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 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/product/** for product truth destinations - use docs/truthmark/engineering/** for engineering truth destinations - use only canonical current-truth destinations for starter truth docs -- keep Product Decisions in product truth and Engineering Decisions in engineering truth when selecting destinations; report any relocation need instead of rewriting decision prose during topology review +- 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. @@ -47,12 +52,18 @@ Do not: ## Topology Governance 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 route structure before creating or extending truth ownership anchors. +When topology pressure exists, repair structure before creating or extending truth docs. Truth-doc ownership review: - before editing or relying on candidate route owners and current truth docs, verify each target/source truth doc is a bounded owner for the behavior - if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it -- if a truth doc mixes independent owners, route ownership is broad, or a split is required for bounded ownership, split or reroute only the ownership topology when safe; otherwise stop with manual-review files +- if a truth doc mixes independent owners, route ownership is broad, or a split is required for bounded ownership, split and reroute into bounded truth docs when safe; otherwise stop with manual-review files - report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Manual handoff reason as applicable +Decision/Rationale preservation review: +- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions, Engineering Decisions, and Rationale sections in every source or touched truth doc +- preserve each current decision and rationale in the correct product or engineering lane owner; when splitting, move it to the new owner doc rather than deleting it or leaving it in an index +- remove or narrow a decision or rationale only when checkout evidence shows it is stale or unsupported, and report the exact claim, evidence, and result +- if ownership of a decision or rationale is unclear, stop with manual-review files instead of deleting it or guessing +- after the edit, verify every touched truth doc keeps lane-appropriate decision/rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked Topology pressure signals: - one area maps broad code such as src/**, app/**, server/**, services/**, or packages/** - one area maps multiple unrelated controllers, route groups, services, or bounded contexts @@ -68,10 +79,10 @@ Use these review thresholds as guidance: - more than 5 controllers mapped through one catch-all area Repair rules: - split broad, overloaded, or catch-all areas into behavior-owned child route files -- split or flag mixed-owner truth docs for bounded owners before any workflow adds new behavior claims +- 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 skeletal engineering ownership anchors under docs/truthmark/engineering only when behavior lacks a current owner -- create skeletal product ownership anchors under docs/truthmark/product only when product promise, boundary, rationale, or user-visible capability ownership is in scope +- 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 product docs under product/capabilities or product/decisions and engineering docs under engineering//.md - keep behavior truth docs behavior-oriented, not endpoint-oriented @@ -79,12 +90,21 @@ Repair rules: - update routing so future Truth Sync can target small docs - preserve existing authored docs; move or rewrite only when needed to remove ambiguity - report Truth docs split when one broad or mixed-owner truth doc becomes multiple bounded docs +Truth-doc shape repair review: +- Truth Structure may restructure broader routed docs when topology, ownership, or doc-shape repair is already in scope. +- repair shape in place only after the ownership review confirms the doc is the right bounded owner +- use Truth Structure for ownership splits; do not treat broad or mixed-owner docs as in-place repair work +- repair shape when a narrow edit would make truth worse: missing template sections, stale evidence conflicts, cross-section updates within one owner, or wrong frontmatter/source/headings +- preserve supported claims; remove, narrow, or record unsupported or stale claims for manual handoff +- report docs restructured and why a narrow edit was not sufficient Evidence checklist: - apply the evidence checklist before finishing when Truth Structure writes routed docs, ownership claims, lane-specific decisions, or rationale - support ownership/behavior claims with topology or primary checkout evidence from layout, implementation boundaries, docs, config, route files, tests, templates, schemas, or contracts - tests/examples/canonical docs corroborate; remove, narrow, or record unsupported claims for manual handoff +Maintain architecture docs only for structure-level changes: system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership. +Keep ordinary behavior, endpoints, UI copy, validation rules, and bug fixes in behavior or contract docs unless they change those boundaries. - Do not finish topology repair with mixed product/engineering authority in a single canonical truth doc. -- If an existing canonical doc has wrong-lane sections, report the lane repair needed and only move content when the topology split explicitly requires it. +- 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. diff --git a/.agents/skills/truthmark-sync/SKILL.md b/.agents/skills/truthmark-sync/SKILL.md index 21ea858..ecf0b61 100644 --- a/.agents/skills/truthmark-sync/SKILL.md +++ b/.agents/skills/truthmark-sync/SKILL.md @@ -9,14 +9,21 @@ user-invocable: true 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. + Quick procedure: - Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists. - Skip docs-only, formatting-only, behavior-preserving renames with no truth impact, missing config, and no-code changes. - Inspect .truthmark/config.yml and configured route files (docs/truthmark/routes/areas.md; docs/truthmark/routes/areas/) only when they exist; then inspect relevant canonical docs directly. - direct checkout inspection is the canonical path; do not require the truthmark binary. - May write canonical truth docs and truth routing files only; must not rewrite functional code. +- Read support/procedure.md before editing truth docs. +- Read support/subagents-and-leases.md only when dispatching or accepting worker output. +- Read support/report-template.md before the final report. Progressive disclosure: - support/procedure.md — read before edits or detailed auditing; contains core review questions - support/report-template.md — read before the final report - support/subagents-and-leases.md — read only when using subagents, leases, or accepting worker output +- helper-manifest.yml — read only when invoking helper validators or validating helper registration +- support/helper-policy.md — read only when invoking helper validators or reporting helper status diff --git a/.agents/skills/truthmark-sync/helper-manifest.yml b/.agents/skills/truthmark-sync/helper-manifest.yml new file mode 100644 index 0000000..64191b3 --- /dev/null +++ b/.agents/skills/truthmark-sync/helper-manifest.yml @@ -0,0 +1,34 @@ +# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces. +helpers: + validate-sync-report: + optional: true + runner: truthmark + command: + argv: + - truthmark + - validate + - sync-report + - + - --json + inputs: + - sync report file + output: json + writes: false + 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 + command: + argv: + - truthmark + - validate + - write-lease + - + - + - --json + inputs: + - lease or worker report yaml + - changed file list + output: json + writes: false + fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files diff --git a/.agents/skills/truthmark-sync/support/helper-policy.md b/.agents/skills/truthmark-sync/support/helper-policy.md new file mode 100644 index 0000000..4394d9d --- /dev/null +++ b/.agents/skills/truthmark-sync/support/helper-policy.md @@ -0,0 +1,23 @@ +# Optional Helper CLI Policy + +Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces. + +Optional helper CLI commands may collect deterministic checkout facts or validate artifacts. If the Truthmark CLI is unavailable or cannot return the declared helper output, continue manually using this procedure and report which helper was skipped. Helper output is derived evidence; it does not override direct checkout inspection, workflow write boundaries, or parent acceptance. + +Runner detection: +- Check that the declared Truthmark CLI runner is available before invoking a helper. +- Invoke helpers through the installed `truthmark validate ... --json` CLI command using argv-style arguments from helper-manifest.yml. +- If unavailable, failing, or returning incompatible output, treat the helper as skipped and use the manual fallback. +- Do not fail the workflow solely because a helper cannot run. + +Available helpers: +- validate-sync-report: optional truthmark; manual fallback: manually validate support/report-template.md and check Evidence checked entries match Claim, indented Evidence, and Result: supported | narrowed | removed | blocked +- validate-write-lease: optional truthmark; manual fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files + +Final reports should include helper status when helpers are declared for this workflow: + +```md +Helper scripts: +- validate-sync-report: ran, passed +- validate-write-lease: skipped, no write lease used +``` diff --git a/.agents/skills/truthmark-sync/support/procedure.md b/.agents/skills/truthmark-sync/support/procedure.md index 29f5a3c..988dc1f 100644 --- a/.agents/skills/truthmark-sync/support/procedure.md +++ b/.agents/skills/truthmark-sync/support/procedure.md @@ -3,7 +3,8 @@ Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces. Use this skill automatically before finishing when functional code changed since the last successful Truth Sync. Also run it immediately when the user explicitly invokes Truth Sync. -Explicit invocation runs immediately when the user directly requests this workflow. Later functional-code changes need a fresh finish-time review, and an earlier explicit run satisfies the finish-time review only if no later functional-code changes occur. +Invocations: OpenCode /skill truthmark-sync; Codex /truthmark-sync or $truthmark-sync; Claude Code /truthmark-sync; GitHub Copilot /truthmark-sync; Gemini CLI /truthmark:sync. +Explicit invocation runs immediately. Later functional-code changes need a fresh finish-time review, and an earlier explicit run satisfies the finish-time review only if no later functional-code changes occur. Skip when changes are documentation-only, formatting-only, clearly behavior-preserving renames with no truth impact, when no Truthmark config exists yet, or when there are no functional code changes. Parent workflow: 1. Inspect git status, staged changes, unstaged changes, and untracked files directly. @@ -31,33 +32,78 @@ Parent workflow: - User-provided decisions/rationale: decisions, rationale, constraints, tradeoffs, rejection reasons, or scope boundaries from the current task conversation, or "none provided" - No-update-needed rationale: why mapped truth is already current when no truth doc should change - Blockers: missing routing, ambiguous ownership, failed verification, unavailable evidence, or off-boundary write needs -11. Only edit allowed truth docs/routes after Sync Intent is clear; if ownership is ambiguous, repair topology first when the repair is safe and in scope, otherwise stop and recommend Truth Structure instead of guessing. -Topology review and repair: +11. Only edit allowed truth docs/routes after Sync Intent is clear; if ownership is ambiguous, stop and recommend Truth Structure instead of guessing. +Topology review: - before updating truth docs, verify the changed code resolves to a specific behavior-owned area and bounded truth owner -- if routing is missing, stale, broad, overloaded, catch-all route only, or cannot map changed code to a bounded truth owner, run Truth Structure before syncing when topology repair is safe and in scope -- safe in-scope topology repair may update truth routing files and create or update bounded leaf truth docs needed to map the changed functional code; keep the repair limited to the affected route owner -- stop and recommend Truth Structure only when topology repair is unsafe, ambiguous, or outside the current task boundary -- report the route files and changed code paths that required structure repair -- do not create another generic truth doc +- if routing is missing, stale, broad, overloaded, catch-all route only, or cannot map changed code to a bounded truth owner, do not create another generic truth doc +- run Truth Structure before syncing when topology repair is safe and in scope +- stop and recommend Truth Structure when topology repair is unsafe, ambiguous, or outside the current task boundary +- report the route files and changed code paths that require structure repair - README.md files are indexes, not Truth Sync targets - must not append behavior details to a README.md index +- create or update a bounded leaf truth doc when behavior changes do not fit an existing leaf doc - write engineering truth under docs/truthmark/engineering; product truth updates under docs/truthmark/product are allowed only for explicit current product behavior changes +Truth-doc ownership review: +- before editing or relying on changed functional files and impacted truth docs, verify each target/source truth doc is a bounded owner for the behavior +- if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it +- if an impacted doc is broad, mixed-owner, index-like, or the update spans independent behavior owners, run Truth Structure before syncing when safe and in scope; otherwise stop and recommend Truth Structure +- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Manual handoff reason as applicable +Decision/Rationale preservation review: +- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions, Engineering Decisions, and Rationale sections in every source or touched truth doc +- preserve each current decision and rationale in the correct product or engineering lane owner; when splitting, move it to the new owner doc rather than deleting it or leaving it in an index +- remove or narrow a decision or rationale only when checkout evidence shows it is stale or unsupported, and report the exact claim, evidence, and result +- if ownership of a decision or rationale is unclear, stop with manual-review files instead of deleting it or guessing +- after the edit, verify every touched truth doc keeps lane-appropriate decision/rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked +When creating or updating a truth doc, inspect the routed truth kind and use the matching template under the configured Truthmark templates root. +Supported kinds: product-capability, engineering-behavior, engineering-contract, engineering-architecture, engineering-workflow, engineering-operations, and engineering-test-behavior. +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 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 review: +- Truth Sync may restructure leased canonical truth docs when the current sync evidence shows repository truth is stale, even when the doc is outside the initially affected route focus. +- repair shape in place only after the ownership review confirms the doc is the right bounded owner +- use Truth Structure for ownership splits; do not treat broad or mixed-owner docs as in-place repair work +- repair shape when a narrow edit would make truth worse: missing template sections, stale evidence conflicts, cross-section updates within one owner, or wrong frontmatter/source/headings +- preserve supported claims; remove, narrow, or record unsupported or stale claims for manual handoff +- report docs restructured and why a narrow edit was not sufficient +Maintain architecture docs only for structure-level changes: system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership. +Keep ordinary behavior, endpoints, UI copy, validation rules, and bug fixes in behavior or contract docs unless they change those boundaries. +Evidence checklist: +- route-first: map changed functional files to bounded route owners and primary canonical docs +- review new or changed behavior-bearing claims only in touched docs, route ownership, lane-specific decisions, and rationale +- support claims with primary checkout evidence: implementation, config, routing, generated templates, schemas, or contract definitions +- tests/examples/canonical docs corroborate; they are not sole proof when implementation conflicts +- remove, narrow, or record unsupported claims for manual handoff +- if no impacted doc changed, report why truth was already current or why sync was skipped +Repository intelligence artifacts are optional derived context: RepoIndex, RouteMap, ImpactSet, and WorkflowState/action context may guide routing, write boundaries, and verification planning when available. +They do not override checkout evidence, canonical truth docs, route files, or workflow write boundaries. +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 -- you may validate the final report with `truthmark validate sync-report --json` when 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 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. +- If the installed Truthmark CLI is unavailable or the helper is skipped, record `validate-sync-report: skipped, ` and manually validate the report shape. +- Record `validate-write-lease: ran, passed` only after validating a concrete write lease; otherwise use a truthful skipped status such as `skipped, no write lease used`. +- Helper output is derived evidence and never replaces direct checkout inspection, evidence review, or parent acceptance. 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 - 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. +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 - stop on any unrelated diff caused by the sync step - stop if functional code changed during sync +- for each write lease, validate the worker report against the actual worker diff, allowedWrites, forbiddenWrites, identity fields, filesChanged, offLeaseChanges, blockers, and expected report fields before accepting it - validate the final report against the structured Truth Sync report contract, including Claim, indented Evidence, and Result values supported, narrowed, removed, or blocked under Evidence checked - verify the updated docs correspond to reviewed checkout evidence, changed-code impact, or a recorded stale-truth correction made within the sync write lease - verify the final report records ownership review, structure requirement, split, restructure, or manual handoff reason when the ownership review applies diff --git a/.agents/skills/truthmark-sync/support/report-template.md b/.agents/skills/truthmark-sync/support/report-template.md index d682cc5..d290cc5 100644 --- a/.agents/skills/truthmark-sync/support/report-template.md +++ b/.agents/skills/truthmark-sync/support/report-template.md @@ -11,28 +11,31 @@ Changed code reviewed: Sync Intent: - Changed code reviewed: src/auth/session.ts -- Affected route/truth owner: docs/truthmark/routes/areas/authentication.md -- Target truth docs: docs/truthmark/engineering/behaviors/session-timeout.md +- Affected route/truth owner: docs/truthmark/routes/areas.md +- Target truth docs: docs/truthmark/engineering/repository/bootstrap-routing.md - Intended update: Update session timeout behavior. -- Evidence to verify: src/auth/session.ts:12 / docs/truthmark/routes/areas/authentication.md:11 +- Evidence to verify: src/auth/session.ts:12 / docs/truthmark/routes/areas.md:11 - User-provided decisions/rationale: User rationale: session timeout behavior changed for internal implementation consistency - No-update-needed rationale: not applicable; mapped truth is stale - Blockers: none Ownership reviewed: -- docs/truthmark/routes/areas/authentication.md +- docs/truthmark/routes/areas.md Truth docs updated: -- docs/truthmark/engineering/behaviors/session-timeout.md +- docs/truthmark/engineering/repository/bootstrap-routing.md Decision/rationale captured: -- Placed user rationale in the bounded authentication behavior truth doc under Engineering Decisions/Rationale. +- Placed user rationale in the mapped engineering truth doc under Engineering Decisions/Rationale. Evidence checked: -- Claim: Session timeout behavior is documented in the bounded authentication behavior truth doc. - Evidence: src/auth/session.ts:12 / docs/truthmark/routes/areas/authentication.md:11 +- Claim: Session timeout behavior is documented in the mapped repository truth doc. + Evidence: src/auth/session.ts:12 / docs/truthmark/routes/areas.md:11 Result: supported +Helper scripts: +- validate-write-lease: skipped, no write lease used + Notes: - Updated session timeout behavior. ``` @@ -41,12 +44,11 @@ Blocked report example: Truth Sync: blocked Reason: -- Changed code maps only to the provisional bootstrap route. +- routing repair is not allowed Files requiring manual review: -- src/auth/** -- docs/truthmark/routes/areas/repository.md +- docs/truthmark/routes/areas.md Next action: -- Run Truth Structure for src/auth/** before updating behavior truth. +- update routing metadata and rerun Truth Sync ``` diff --git a/.codex/agents/truth-claim-verifier.toml b/.codex/agents/truth-claim-verifier.toml index 429f677..8a53f7f 100644 --- a/.codex/agents/truth-claim-verifier.toml +++ b/.codex/agents/truth-claim-verifier.toml @@ -12,7 +12,7 @@ For every checked claim, classify the result as supported | narrowed | removed | Do not edit files, stage changes, or invent missing behavior. Return JSON only with keys: scope, filesReviewed, claimsChecked, evidence, unsupportedClaims, confidence, recommendedWorkflow, notes. Context boundary: -Do not preload AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .cursor/skills, .antigravity/rules, or repo-wide policy docs unless the parent explicitly assigns them as evidence. +Do not preload AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, or repo-wide policy docs unless the parent explicitly assigns them as evidence. Use only the parent-assigned shard plus required checkout evidence files. Return findings only; the parent workflow owns repository-policy interpretation, final decisions, and all writes. """ diff --git a/.codex/agents/truth-doc-reviewer.toml b/.codex/agents/truth-doc-reviewer.toml index b8cae62..2095560 100644 --- a/.codex/agents/truth-doc-reviewer.toml +++ b/.codex/agents/truth-doc-reviewer.toml @@ -11,7 +11,7 @@ Do not edit files, stage changes, or rewrite docs. Return JSON only with keys: scope, filesReviewed, findings, evidence, confidence, recommendedWorkflow, notes. recommendedWorkflow must be one of: none, truthmark-document, truthmark-structure. Context boundary: -Do not preload AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .cursor/skills, .antigravity/rules, or repo-wide policy docs unless the parent explicitly assigns them as evidence. +Do not preload AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, or repo-wide policy docs unless the parent explicitly assigns them as evidence. Use only the parent-assigned shard plus required checkout evidence files. Return findings only; the parent workflow owns repository-policy interpretation, final decisions, and all writes. """ diff --git a/.codex/agents/truth-route-auditor.toml b/.codex/agents/truth-route-auditor.toml index ef56782..2a83b53 100644 --- a/.codex/agents/truth-route-auditor.toml +++ b/.codex/agents/truth-route-auditor.toml @@ -19,7 +19,7 @@ Do not edit files, stage changes, or propose broad rewrites. Return JSON only with keys: scope, filesReviewed, findings, evidence, confidence, recommendedWorkflow, notes. recommendedWorkflow must be one of: none, truthmark-document, truthmark-structure. Context boundary: -Do not preload AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .cursor/skills, .antigravity/rules, or repo-wide policy docs unless the parent explicitly assigns them as evidence. +Do not preload AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, or repo-wide policy docs unless the parent explicitly assigns them as evidence. Use only the parent-assigned shard plus required checkout evidence files. Return findings only; the parent workflow owns repository-policy interpretation, final decisions, and all writes. """ diff --git a/.opencode/agents/truth-claim-verifier.md b/.opencode/agents/truth-claim-verifier.md index 48c66c1..ea65f86 100644 --- a/.opencode/agents/truth-claim-verifier.md +++ b/.opencode/agents/truth-claim-verifier.md @@ -28,6 +28,6 @@ For every checked claim, classify the result as supported | narrowed | removed | Do not edit files, stage changes, or invent missing behavior. Return JSON only with keys: scope, filesReviewed, claimsChecked, evidence, unsupportedClaims, confidence, recommendedWorkflow, notes. Context boundary: -Do not preload AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .cursor/skills, .antigravity/rules, or repo-wide policy docs unless the parent explicitly assigns them as evidence. +Do not preload AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, or repo-wide policy docs unless the parent explicitly assigns them as evidence. Use only the parent-assigned shard plus required checkout evidence files. Return findings only; the parent workflow owns repository-policy interpretation, final decisions, and all writes. diff --git a/.opencode/agents/truth-doc-reviewer.md b/.opencode/agents/truth-doc-reviewer.md index 6818431..2b5f30b 100644 --- a/.opencode/agents/truth-doc-reviewer.md +++ b/.opencode/agents/truth-doc-reviewer.md @@ -27,6 +27,6 @@ Do not edit files, stage changes, or rewrite docs. Return JSON only with keys: scope, filesReviewed, findings, evidence, confidence, recommendedWorkflow, notes. recommendedWorkflow must be one of: none, truthmark-document, truthmark-structure. Context boundary: -Do not preload AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .cursor/skills, .antigravity/rules, or repo-wide policy docs unless the parent explicitly assigns them as evidence. +Do not preload AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, or repo-wide policy docs unless the parent explicitly assigns them as evidence. Use only the parent-assigned shard plus required checkout evidence files. Return findings only; the parent workflow owns repository-policy interpretation, final decisions, and all writes. diff --git a/.opencode/agents/truth-route-auditor.md b/.opencode/agents/truth-route-auditor.md index 4047877..e9813f9 100644 --- a/.opencode/agents/truth-route-auditor.md +++ b/.opencode/agents/truth-route-auditor.md @@ -35,6 +35,6 @@ Do not edit files, stage changes, or propose broad rewrites. Return JSON only with keys: scope, filesReviewed, findings, evidence, confidence, recommendedWorkflow, notes. recommendedWorkflow must be one of: none, truthmark-document, truthmark-structure. Context boundary: -Do not preload AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .cursor/skills, .antigravity/rules, or repo-wide policy docs unless the parent explicitly assigns them as evidence. +Do not preload AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, or repo-wide policy docs unless the parent explicitly assigns them as evidence. Use only the parent-assigned shard plus required checkout evidence files. Return findings only; the parent workflow owns repository-policy interpretation, final decisions, and all writes. diff --git a/.opencode/skills/truthmark-check/SKILL.md b/.opencode/skills/truthmark-check/SKILL.md index 9f1c778..657657b 100644 --- a/.opencode/skills/truthmark-check/SKILL.md +++ b/.opencode/skills/truthmark-check/SKILL.md @@ -9,10 +9,15 @@ user-invocable: true Use this skill to audit repository truth health. +Invocations: OpenCode /skill truthmark-check; Codex /truthmark-check or $truthmark-check; Claude Code /truthmark-check; GitHub Copilot /truthmark-check; Gemini CLI /truthmark:check. + 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 canonical docs and relevant implementation directly. - Report issues and suggested fixes; do not silently rewrite unrelated files. +- Read support/procedure.md before auditing details. +- Read support/subagents-and-leases.md only when dispatching verifier subagents. +- Read support/report-template.md before the final report. Progressive disclosure: - support/procedure.md — read before edits or detailed auditing; contains core review questions diff --git a/.opencode/skills/truthmark-check/support/procedure.md b/.opencode/skills/truthmark-check/support/procedure.md index 9c5779f..35ef887 100644 --- a/.opencode/skills/truthmark-check/support/procedure.md +++ b/.opencode/skills/truthmark-check/support/procedure.md @@ -6,6 +6,8 @@ Truthmark-managed generated file. Refresh with truthmark init when truthmark che Use this skill to audit repository truth health. +Invocations: OpenCode /skill truthmark-check; Codex /truthmark-check or $truthmark-check; Claude Code /truthmark-check; GitHub Copilot /truthmark-check; Gemini CLI /truthmark:check. + Truth Check is agent-led: - inspect .truthmark/config.yml and configured route files only when they exist; then inspect canonical docs and relevant implementation directly diff --git a/.opencode/skills/truthmark-document/SKILL.md b/.opencode/skills/truthmark-document/SKILL.md index d5dec2f..3b346c9 100644 --- a/.opencode/skills/truthmark-document/SKILL.md +++ b/.opencode/skills/truthmark-document/SKILL.md @@ -9,13 +9,20 @@ user-invocable: true Use this skill to document existing implemented behavior when no functional-code changes are required for the task. +Invocations: OpenCode /skill truthmark-document; Codex /truthmark-document or $truthmark-document; Claude Code /truthmark-document; GitHub Copilot /truthmark-document; Gemini CLI /truthmark:document. + 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 existing canonical docs, implementation code, and tests directly. - Document current implemented behavior; do not invent future behavior. - May write canonical truth docs and truth routing files only; must not write functional code. +- Read support/procedure.md before editing truth docs. +- Read support/subagents-and-leases.md only when dispatching or accepting worker output. +- Read support/report-template.md before the final report. Progressive disclosure: - support/procedure.md — read before edits or detailed auditing; contains core review questions - support/report-template.md — read before the final report - support/subagents-and-leases.md — read only when using subagents, leases, or accepting worker output +- helper-manifest.yml — read only when invoking helper validators or validating helper registration +- support/helper-policy.md — read only when invoking helper validators or reporting helper status diff --git a/.opencode/skills/truthmark-document/helper-manifest.yml b/.opencode/skills/truthmark-document/helper-manifest.yml new file mode 100644 index 0000000..397d3f0 --- /dev/null +++ b/.opencode/skills/truthmark-document/helper-manifest.yml @@ -0,0 +1,34 @@ +# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces. +helpers: + validate-document-report: + optional: true + runner: truthmark + command: + argv: + - truthmark + - validate + - document-report + - + - --json + inputs: + - document report file + output: json + writes: false + fallback: manually validate support/report-template.md required sections and structured Evidence checked entries + validate-write-lease: + optional: true + runner: truthmark + command: + argv: + - truthmark + - validate + - write-lease + - + - + - --json + inputs: + - lease or worker report yaml + - changed file list + output: json + writes: false + fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files diff --git a/.opencode/skills/truthmark-document/support/helper-policy.md b/.opencode/skills/truthmark-document/support/helper-policy.md new file mode 100644 index 0000000..671d0c4 --- /dev/null +++ b/.opencode/skills/truthmark-document/support/helper-policy.md @@ -0,0 +1,23 @@ +# Optional Helper CLI Policy + +Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces. + +Optional helper CLI commands may collect deterministic checkout facts or validate artifacts. If the Truthmark CLI is unavailable or cannot return the declared helper output, continue manually using this procedure and report which helper was skipped. Helper output is derived evidence; it does not override direct checkout inspection, workflow write boundaries, or parent acceptance. + +Runner detection: +- Check that the declared Truthmark CLI runner is available before invoking a helper. +- Invoke helpers through the installed `truthmark validate ... --json` CLI command using argv-style arguments from helper-manifest.yml. +- If unavailable, failing, or returning incompatible output, treat the helper as skipped and use the manual fallback. +- Do not fail the workflow solely because a helper cannot run. + +Available helpers: +- validate-document-report: optional truthmark; manual fallback: manually validate support/report-template.md required sections and structured Evidence checked entries +- validate-write-lease: optional truthmark; manual fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files + +Final reports should include helper status when helpers are declared for this workflow: + +```md +Helper scripts: +- validate-document-report: ran, passed +- validate-write-lease: skipped, no write lease used +``` diff --git a/.opencode/skills/truthmark-document/support/procedure.md b/.opencode/skills/truthmark-document/support/procedure.md index eecba04..bbf485a 100644 --- a/.opencode/skills/truthmark-document/support/procedure.md +++ b/.opencode/skills/truthmark-document/support/procedure.md @@ -5,6 +5,7 @@ Truthmark-managed generated file. Refresh with truthmark init when truthmark che # Truthmark Document Use this skill to document existing implemented behavior when no functional-code changes are required for the task. +Invocations: OpenCode /skill truthmark-document; Codex /truthmark-document or $truthmark-document; Claude Code /truthmark-document; GitHub Copilot /truthmark-document; Gemini CLI /truthmark:document. Truth Document is manual and implementation-first: @@ -60,7 +61,6 @@ Treat the HTML comments under each template section as normative authoring guida Align existing docs to that template and write or repair section content so it satisfies the comment guidance while preserving accurate authored content. If the template is missing, use lane-specific sections: product truth says what must be true and why; engineering truth says how the repository currently realizes it. Teams may edit template files under the configured Truthmark templates root to define their local truth-doc standards. -Prefer diff-friendly Markdown: one durable claim per bullet or line, paragraphs no longer than one or two short sentences, and bullets or tables for rules, criteria, fields, files, and lists. Truth-doc shape repair review: - Truth Document may restructure only truth docs for the implemented behavior being documented. - repair shape in place only after the ownership review confirms the doc is the right bounded owner @@ -79,7 +79,12 @@ Truthmark hierarchy hints: 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. Product decisions belong in product truth; engineering, architecture, contract, workflow, and operational decisions belong in engineering truth. -Optional validation: when local tooling is available, you may validate the final report with `truthmark validate document-report --json`; direct checkout inspection and evidence review remain authoritative. +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. +- If the installed Truthmark CLI is unavailable or the helper is skipped, record `validate-document-report: skipped, ` and manually validate the report shape. +- Record `validate-write-lease: ran, passed` only after validating a concrete write lease; otherwise use a truthful skipped status such as `skipped, no write lease used`. +- Helper output is derived evidence and never replaces direct checkout inspection, evidence review, or parent acceptance. Parent post-document verification: - verify only truth docs and leased truth routing files changed during document work - stop on functional code, generated host surfaces, or unrelated diffs caused by document work diff --git a/.opencode/skills/truthmark-document/support/report-template.md b/.opencode/skills/truthmark-document/support/report-template.md index 29677aa..b0b05df 100644 --- a/.opencode/skills/truthmark-document/support/report-template.md +++ b/.opencode/skills/truthmark-document/support/report-template.md @@ -29,6 +29,9 @@ Evidence checked: Evidence: src/routing/area-resolver.ts:14 / docs/truthmark/routes/areas.md:9 Result: supported +Helper scripts: +- validate-write-lease: skipped, no write lease used + Notes: - Documented routing and behavior from route handlers and tests. ``` diff --git a/.opencode/skills/truthmark-portal/SKILL.md b/.opencode/skills/truthmark-portal/SKILL.md index e925915..75aaabb 100644 --- a/.opencode/skills/truthmark-portal/SKILL.md +++ b/.opencode/skills/truthmark-portal/SKILL.md @@ -9,6 +9,8 @@ user-invocable: true Use this skill only when the user explicitly asks to generate or refresh the committed static HTML Truthmark Portal. +Invocations: OpenCode /skill truthmark-portal; Codex /truthmark-portal or $truthmark-portal; Claude Code /truthmark-portal; GitHub Copilot /truthmark-portal; Gemini CLI /truthmark:portal. + Quick procedure: - Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists. - Truthmark Portal is manual-only; never run it automatically at completion and never treat it as Truth Sync. @@ -18,6 +20,8 @@ Quick procedure: - Write only under fixed Portal output docs/truthmark/generated/portal. - Use determined Portal template docs/truthmark/templates/portal.html when present; no .truthmark/index.json dependency. - Use no remote dependencies by default and include source provenance on every page. +- Read support/procedure.md before generating Portal output. +- Read support/report-template.md before the final report. Progressive disclosure: - support/procedure.md — read before edits or detailed auditing; contains core review questions diff --git a/.opencode/skills/truthmark-portal/support/procedure.md b/.opencode/skills/truthmark-portal/support/procedure.md index 02b217b..f04d2d1 100644 --- a/.opencode/skills/truthmark-portal/support/procedure.md +++ b/.opencode/skills/truthmark-portal/support/procedure.md @@ -6,6 +6,8 @@ Truthmark-managed generated file. Refresh with truthmark init when truthmark che Truthmark Portal is a manual-only presentation workflow. It is never an automatic completion workflow, never Truth Sync, and runs only when the user explicitly asks to generate, refresh, or update the committed static HTML Portal. +Invocations: OpenCode /skill truthmark-portal; Codex /truthmark-portal or $truthmark-portal; Claude Code /truthmark-portal; GitHub Copilot /truthmark-portal; Gemini CLI /truthmark:portal. + Core rules: - Markdown remains canonical; generated HTML is presentation only. diff --git a/.opencode/skills/truthmark-preview/SKILL.md b/.opencode/skills/truthmark-preview/SKILL.md new file mode 100644 index 0000000..2364bd6 --- /dev/null +++ b/.opencode/skills/truthmark-preview/SKILL.md @@ -0,0 +1,25 @@ +--- +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 Preview + +Use this skill only when the user explicitly asks to preview Truthmark routing or workflow choice before edits. + +Invocations: OpenCode /skill truthmark-preview; Codex /truthmark-preview or $truthmark-preview; Claude Code /truthmark-preview; GitHub Copilot /truthmark-preview; Gemini CLI /truthmark:preview. + +Quick procedure: +- Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists. +- 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. +- Hand off to the selected workflow after user approval. + +Progressive disclosure: +- support/procedure.md — read before edits or detailed auditing; contains core review questions +- support/report-template.md — read before the final report +- support/subagents-and-leases.md — read only when using subagents, leases, or accepting worker output diff --git a/.opencode/skills/truthmark-preview/support/procedure.md b/.opencode/skills/truthmark-preview/support/procedure.md new file mode 100644 index 0000000..828cbda --- /dev/null +++ b/.opencode/skills/truthmark-preview/support/procedure.md @@ -0,0 +1,53 @@ +# Truthmark Preview Procedure + +Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces. + +Use this skill only when the user explicitly asks to preview Truthmark routing or workflow choice before edits. + +Invocations: OpenCode /skill truthmark-preview; Codex /truthmark-preview or $truthmark-preview; Claude Code /truthmark-preview; GitHub Copilot /truthmark-preview; Gemini CLI /truthmark:preview. + +Truth Preview is read-only. Its report is intended, not authorized. + +Purpose: +- preview the likely Truthmark workflow, route owner, target files, expected write classes, suggested subagent use, and manual handoff questions before edits happen +- report likely product lane impact, engineering lane impact, target docs, and ambiguity before edits +- hand off to the selected workflow after user approval +- keep the selector thin so agents can avoid loading or acting through heavier workflows prematurely + +Read: +- .truthmark/config.yml, 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 +- 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 for manual handoff or routed to Truth Structure + - Do not make product docs a summary of engineering docs. Do not make engineering docs a detailed version of product docs. Product truth says what must be true and why. Engineering truth says how the repository currently realizes it. + +Do not: +- must not edit files +- must not create truth docs +- must not update routing +- must not run Truth Sync automatically +- must not replace Truth Check +- must not claim final correctness +- must not issue write leases +- must not mutate code + +Suggested subagent use: +- optional read-only verifier: truth_route_auditor +- write workers: none +- leases needed: none + +Truthmark hierarchy 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 +- 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 new file mode 100644 index 0000000..e0531b4 --- /dev/null +++ b/.opencode/skills/truthmark-preview/support/report-template.md @@ -0,0 +1,43 @@ +# Truthmark Preview Report Template + +Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces. + +Report completion in this shape: +```md +Truth Preview: completed + +Requested outcome: +- preview likely Truthmark workflow routing before edits + +Likely workflow: +- truthmark-document + +Why this workflow: +- positive trigger: document existing implemented behavior +- negative triggers considered: functional-code change, doc-first implementation, topology repair, truth audit +- forbidden adjacency considered: must not edit functional code + +Likely route owner: +- route file: docs/truthmark/routes/areas.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/engineering/behaviors/example.md + +Suggested subagent use: +- read-only verifiers: truth_route_auditor +- write workers: none in Preview +- leases needed: none in Preview + +Manual handoff questions: +- none identified in preview + +Handoff: +- Run the selected Truthmark workflow after user approval. +``` diff --git a/.opencode/skills/truthmark-preview/support/subagents-and-leases.md b/.opencode/skills/truthmark-preview/support/subagents-and-leases.md new file mode 100644 index 0000000..34620b6 --- /dev/null +++ b/.opencode/skills/truthmark-preview/support/subagents-and-leases.md @@ -0,0 +1,10 @@ +# Truthmark Preview Subagents And Leases + +Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces. + +OpenCode subagent mode: +- use automatically when this workflow runs in OpenCode and the parent agent chooses bounded subagent fan-out +- dispatch read-only project subagents only: @truth-route-auditor +- workers inspect checkout evidence directly, return structured findings, and must not edit files +- parent supplies bounded evidence shards; workers must not preload host instruction files or repo-wide policy docs unless assigned as evidence +- Parent agent owns the final Truth Preview report diff --git a/.opencode/skills/truthmark-realize/SKILL.md b/.opencode/skills/truthmark-realize/SKILL.md index 1577854..494bd1a 100644 --- a/.opencode/skills/truthmark-realize/SKILL.md +++ b/.opencode/skills/truthmark-realize/SKILL.md @@ -9,11 +9,15 @@ user-invocable: true Use this skill only when the user explicitly asks to realize truth docs into code. +Invocations: OpenCode /skill truthmark-realize; Codex /truthmark-realize or $truthmark-realize; Claude Code /truthmark-realize; GitHub Copilot /truthmark-realize; Gemini CLI /truthmark:realize. + Quick procedure: - Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists. - Read the source truth docs, inspect .truthmark/config.yml and configured route files (docs/truthmark/routes/areas.md; docs/truthmark/routes/areas/) only when they exist, then inspect tests and relevant functional code directly. - Truth docs lead; code follows. - may write functional code only; must not edit truth docs or truth routing while realizing those docs. +- Read support/procedure.md before changing code. +- Read support/report-template.md before the final report. Progressive disclosure: - support/procedure.md — read before edits or detailed auditing; contains core review questions diff --git a/.opencode/skills/truthmark-realize/support/procedure.md b/.opencode/skills/truthmark-realize/support/procedure.md index f6b3200..f587ef7 100644 --- a/.opencode/skills/truthmark-realize/support/procedure.md +++ b/.opencode/skills/truthmark-realize/support/procedure.md @@ -6,6 +6,8 @@ Truthmark-managed generated file. Refresh with truthmark init when truthmark che Use this skill only when the user explicitly asks to realize truth docs into code. +Invocations: OpenCode /skill truthmark-realize; Codex /truthmark-realize or $truthmark-realize; Claude Code /truthmark-realize; GitHub Copilot /truthmark-realize; Gemini CLI /truthmark:realize. + Truth Realize is doc-first: - truth docs lead diff --git a/.opencode/skills/truthmark-structure/SKILL.md b/.opencode/skills/truthmark-structure/SKILL.md index aec71ae..4dccdce 100644 --- a/.opencode/skills/truthmark-structure/SKILL.md +++ b/.opencode/skills/truthmark-structure/SKILL.md @@ -9,11 +9,15 @@ user-invocable: true 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. + 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 current docs and relevant code directly. - Define areas by product or behavior ownership, not by mechanical directory mirroring. - Do not edit functional code. +- Read support/procedure.md before writing route or starter truth-doc changes. +- Read support/report-template.md before the final report. Progressive disclosure: - support/procedure.md — read before edits or detailed auditing; contains core review questions diff --git a/.opencode/skills/truthmark-structure/support/procedure.md b/.opencode/skills/truthmark-structure/support/procedure.md index 16f39e5..2a8ecb6 100644 --- a/.opencode/skills/truthmark-structure/support/procedure.md +++ b/.opencode/skills/truthmark-structure/support/procedure.md @@ -3,7 +3,7 @@ Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces. Use this skill to design or repair Truthmark area structure. - +Invocations: OpenCode /skill truthmark-structure; Codex /truthmark-structure or $truthmark-structure; Claude Code /truthmark-structure; GitHub Copilot /truthmark-structure; Gemini CLI /truthmark:structure. Truth Structure is agent-native: - inspect repository layout, current docs, Truthmark config and route files when present, and relevant code directly - Evidence authority: @@ -19,15 +19,20 @@ Truth Structure is agent-native: - 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 skeletal starter truth docs only when missing ownership would otherwise block future workflows +- 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, truth_kind, and last_reviewed inside that frontmatter. Put source references in the final ## Source References section, not in frontmatter. -- Starter truth docs are ownership anchors, not behavior writeups: include only the title, bounded area/scope, and Source References needed to make routing explicit. -- Starter truth docs must keep product and engineering truth in separate files; leave substantive behavior, contract, architecture, workflow, operations, or test prose to Truth Document. +- 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: 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 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/product/** for product truth destinations - use docs/truthmark/engineering/** for engineering truth destinations - use only canonical current-truth destinations for starter truth docs -- keep Product Decisions in product truth and Engineering Decisions in engineering truth when selecting destinations; report any relocation need instead of rewriting decision prose during topology review +- 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. @@ -47,12 +52,18 @@ Do not: ## Topology Governance 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 route structure before creating or extending truth ownership anchors. +When topology pressure exists, repair structure before creating or extending truth docs. Truth-doc ownership review: - before editing or relying on candidate route owners and current truth docs, verify each target/source truth doc is a bounded owner for the behavior - if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it -- if a truth doc mixes independent owners, route ownership is broad, or a split is required for bounded ownership, split or reroute only the ownership topology when safe; otherwise stop with manual-review files +- if a truth doc mixes independent owners, route ownership is broad, or a split is required for bounded ownership, split and reroute into bounded truth docs when safe; otherwise stop with manual-review files - report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Manual handoff reason as applicable +Decision/Rationale preservation review: +- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions, Engineering Decisions, and Rationale sections in every source or touched truth doc +- preserve each current decision and rationale in the correct product or engineering lane owner; when splitting, move it to the new owner doc rather than deleting it or leaving it in an index +- remove or narrow a decision or rationale only when checkout evidence shows it is stale or unsupported, and report the exact claim, evidence, and result +- if ownership of a decision or rationale is unclear, stop with manual-review files instead of deleting it or guessing +- after the edit, verify every touched truth doc keeps lane-appropriate decision/rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked Topology pressure signals: - one area maps broad code such as src/**, app/**, server/**, services/**, or packages/** - one area maps multiple unrelated controllers, route groups, services, or bounded contexts @@ -68,10 +79,10 @@ Use these review thresholds as guidance: - more than 5 controllers mapped through one catch-all area Repair rules: - split broad, overloaded, or catch-all areas into behavior-owned child route files -- split or flag mixed-owner truth docs for bounded owners before any workflow adds new behavior claims +- 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 skeletal engineering ownership anchors under docs/truthmark/engineering only when behavior lacks a current owner -- create skeletal product ownership anchors under docs/truthmark/product only when product promise, boundary, rationale, or user-visible capability ownership is in scope +- 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 product docs under product/capabilities or product/decisions and engineering docs under engineering//.md - keep behavior truth docs behavior-oriented, not endpoint-oriented @@ -79,12 +90,21 @@ Repair rules: - update routing so future Truth Sync can target small docs - preserve existing authored docs; move or rewrite only when needed to remove ambiguity - report Truth docs split when one broad or mixed-owner truth doc becomes multiple bounded docs +Truth-doc shape repair review: +- Truth Structure may restructure broader routed docs when topology, ownership, or doc-shape repair is already in scope. +- repair shape in place only after the ownership review confirms the doc is the right bounded owner +- use Truth Structure for ownership splits; do not treat broad or mixed-owner docs as in-place repair work +- repair shape when a narrow edit would make truth worse: missing template sections, stale evidence conflicts, cross-section updates within one owner, or wrong frontmatter/source/headings +- preserve supported claims; remove, narrow, or record unsupported or stale claims for manual handoff +- report docs restructured and why a narrow edit was not sufficient Evidence checklist: - apply the evidence checklist before finishing when Truth Structure writes routed docs, ownership claims, lane-specific decisions, or rationale - support ownership/behavior claims with topology or primary checkout evidence from layout, implementation boundaries, docs, config, route files, tests, templates, schemas, or contracts - tests/examples/canonical docs corroborate; remove, narrow, or record unsupported claims for manual handoff +Maintain architecture docs only for structure-level changes: system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership. +Keep ordinary behavior, endpoints, UI copy, validation rules, and bug fixes in behavior or contract docs unless they change those boundaries. - Do not finish topology repair with mixed product/engineering authority in a single canonical truth doc. -- If an existing canonical doc has wrong-lane sections, report the lane repair needed and only move content when the topology split explicitly requires it. +- 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. diff --git a/.opencode/skills/truthmark-sync/SKILL.md b/.opencode/skills/truthmark-sync/SKILL.md index 21ea858..ecf0b61 100644 --- a/.opencode/skills/truthmark-sync/SKILL.md +++ b/.opencode/skills/truthmark-sync/SKILL.md @@ -9,14 +9,21 @@ user-invocable: true 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. + Quick procedure: - Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists. - Skip docs-only, formatting-only, behavior-preserving renames with no truth impact, missing config, and no-code changes. - Inspect .truthmark/config.yml and configured route files (docs/truthmark/routes/areas.md; docs/truthmark/routes/areas/) only when they exist; then inspect relevant canonical docs directly. - direct checkout inspection is the canonical path; do not require the truthmark binary. - May write canonical truth docs and truth routing files only; must not rewrite functional code. +- Read support/procedure.md before editing truth docs. +- Read support/subagents-and-leases.md only when dispatching or accepting worker output. +- Read support/report-template.md before the final report. Progressive disclosure: - support/procedure.md — read before edits or detailed auditing; contains core review questions - support/report-template.md — read before the final report - support/subagents-and-leases.md — read only when using subagents, leases, or accepting worker output +- helper-manifest.yml — read only when invoking helper validators or validating helper registration +- support/helper-policy.md — read only when invoking helper validators or reporting helper status diff --git a/.opencode/skills/truthmark-sync/helper-manifest.yml b/.opencode/skills/truthmark-sync/helper-manifest.yml new file mode 100644 index 0000000..64191b3 --- /dev/null +++ b/.opencode/skills/truthmark-sync/helper-manifest.yml @@ -0,0 +1,34 @@ +# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces. +helpers: + validate-sync-report: + optional: true + runner: truthmark + command: + argv: + - truthmark + - validate + - sync-report + - + - --json + inputs: + - sync report file + output: json + writes: false + 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 + command: + argv: + - truthmark + - validate + - write-lease + - + - + - --json + inputs: + - lease or worker report yaml + - changed file list + output: json + writes: false + fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files diff --git a/.opencode/skills/truthmark-sync/support/helper-policy.md b/.opencode/skills/truthmark-sync/support/helper-policy.md new file mode 100644 index 0000000..4394d9d --- /dev/null +++ b/.opencode/skills/truthmark-sync/support/helper-policy.md @@ -0,0 +1,23 @@ +# Optional Helper CLI Policy + +Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces. + +Optional helper CLI commands may collect deterministic checkout facts or validate artifacts. If the Truthmark CLI is unavailable or cannot return the declared helper output, continue manually using this procedure and report which helper was skipped. Helper output is derived evidence; it does not override direct checkout inspection, workflow write boundaries, or parent acceptance. + +Runner detection: +- Check that the declared Truthmark CLI runner is available before invoking a helper. +- Invoke helpers through the installed `truthmark validate ... --json` CLI command using argv-style arguments from helper-manifest.yml. +- If unavailable, failing, or returning incompatible output, treat the helper as skipped and use the manual fallback. +- Do not fail the workflow solely because a helper cannot run. + +Available helpers: +- validate-sync-report: optional truthmark; manual fallback: manually validate support/report-template.md and check Evidence checked entries match Claim, indented Evidence, and Result: supported | narrowed | removed | blocked +- validate-write-lease: optional truthmark; manual fallback: manually compare declared allowedWrites and forbiddenWrites with the actual changed files + +Final reports should include helper status when helpers are declared for this workflow: + +```md +Helper scripts: +- validate-sync-report: ran, passed +- validate-write-lease: skipped, no write lease used +``` diff --git a/.opencode/skills/truthmark-sync/support/procedure.md b/.opencode/skills/truthmark-sync/support/procedure.md index 29f5a3c..988dc1f 100644 --- a/.opencode/skills/truthmark-sync/support/procedure.md +++ b/.opencode/skills/truthmark-sync/support/procedure.md @@ -3,7 +3,8 @@ Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces. Use this skill automatically before finishing when functional code changed since the last successful Truth Sync. Also run it immediately when the user explicitly invokes Truth Sync. -Explicit invocation runs immediately when the user directly requests this workflow. Later functional-code changes need a fresh finish-time review, and an earlier explicit run satisfies the finish-time review only if no later functional-code changes occur. +Invocations: OpenCode /skill truthmark-sync; Codex /truthmark-sync or $truthmark-sync; Claude Code /truthmark-sync; GitHub Copilot /truthmark-sync; Gemini CLI /truthmark:sync. +Explicit invocation runs immediately. Later functional-code changes need a fresh finish-time review, and an earlier explicit run satisfies the finish-time review only if no later functional-code changes occur. Skip when changes are documentation-only, formatting-only, clearly behavior-preserving renames with no truth impact, when no Truthmark config exists yet, or when there are no functional code changes. Parent workflow: 1. Inspect git status, staged changes, unstaged changes, and untracked files directly. @@ -31,33 +32,78 @@ Parent workflow: - User-provided decisions/rationale: decisions, rationale, constraints, tradeoffs, rejection reasons, or scope boundaries from the current task conversation, or "none provided" - No-update-needed rationale: why mapped truth is already current when no truth doc should change - Blockers: missing routing, ambiguous ownership, failed verification, unavailable evidence, or off-boundary write needs -11. Only edit allowed truth docs/routes after Sync Intent is clear; if ownership is ambiguous, repair topology first when the repair is safe and in scope, otherwise stop and recommend Truth Structure instead of guessing. -Topology review and repair: +11. Only edit allowed truth docs/routes after Sync Intent is clear; if ownership is ambiguous, stop and recommend Truth Structure instead of guessing. +Topology review: - before updating truth docs, verify the changed code resolves to a specific behavior-owned area and bounded truth owner -- if routing is missing, stale, broad, overloaded, catch-all route only, or cannot map changed code to a bounded truth owner, run Truth Structure before syncing when topology repair is safe and in scope -- safe in-scope topology repair may update truth routing files and create or update bounded leaf truth docs needed to map the changed functional code; keep the repair limited to the affected route owner -- stop and recommend Truth Structure only when topology repair is unsafe, ambiguous, or outside the current task boundary -- report the route files and changed code paths that required structure repair -- do not create another generic truth doc +- if routing is missing, stale, broad, overloaded, catch-all route only, or cannot map changed code to a bounded truth owner, do not create another generic truth doc +- run Truth Structure before syncing when topology repair is safe and in scope +- stop and recommend Truth Structure when topology repair is unsafe, ambiguous, or outside the current task boundary +- report the route files and changed code paths that require structure repair - README.md files are indexes, not Truth Sync targets - must not append behavior details to a README.md index +- create or update a bounded leaf truth doc when behavior changes do not fit an existing leaf doc - write engineering truth under docs/truthmark/engineering; product truth updates under docs/truthmark/product are allowed only for explicit current product behavior changes +Truth-doc ownership review: +- before editing or relying on changed functional files and impacted truth docs, verify each target/source truth doc is a bounded owner for the behavior +- if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it +- if an impacted doc is broad, mixed-owner, index-like, or the update spans independent behavior owners, run Truth Structure before syncing when safe and in scope; otherwise stop and recommend Truth Structure +- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Manual handoff reason as applicable +Decision/Rationale preservation review: +- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions, Engineering Decisions, and Rationale sections in every source or touched truth doc +- preserve each current decision and rationale in the correct product or engineering lane owner; when splitting, move it to the new owner doc rather than deleting it or leaving it in an index +- remove or narrow a decision or rationale only when checkout evidence shows it is stale or unsupported, and report the exact claim, evidence, and result +- if ownership of a decision or rationale is unclear, stop with manual-review files instead of deleting it or guessing +- after the edit, verify every touched truth doc keeps lane-appropriate decision/rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked +When creating or updating a truth doc, inspect the routed truth kind and use the matching template under the configured Truthmark templates root. +Supported kinds: product-capability, engineering-behavior, engineering-contract, engineering-architecture, engineering-workflow, engineering-operations, and engineering-test-behavior. +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 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 review: +- Truth Sync may restructure leased canonical truth docs when the current sync evidence shows repository truth is stale, even when the doc is outside the initially affected route focus. +- repair shape in place only after the ownership review confirms the doc is the right bounded owner +- use Truth Structure for ownership splits; do not treat broad or mixed-owner docs as in-place repair work +- repair shape when a narrow edit would make truth worse: missing template sections, stale evidence conflicts, cross-section updates within one owner, or wrong frontmatter/source/headings +- preserve supported claims; remove, narrow, or record unsupported or stale claims for manual handoff +- report docs restructured and why a narrow edit was not sufficient +Maintain architecture docs only for structure-level changes: system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership. +Keep ordinary behavior, endpoints, UI copy, validation rules, and bug fixes in behavior or contract docs unless they change those boundaries. +Evidence checklist: +- route-first: map changed functional files to bounded route owners and primary canonical docs +- review new or changed behavior-bearing claims only in touched docs, route ownership, lane-specific decisions, and rationale +- support claims with primary checkout evidence: implementation, config, routing, generated templates, schemas, or contract definitions +- tests/examples/canonical docs corroborate; they are not sole proof when implementation conflicts +- remove, narrow, or record unsupported claims for manual handoff +- if no impacted doc changed, report why truth was already current or why sync was skipped +Repository intelligence artifacts are optional derived context: RepoIndex, RouteMap, ImpactSet, and WorkflowState/action context may guide routing, write boundaries, and verification planning when available. +They do not override checkout evidence, canonical truth docs, route files, or workflow write boundaries. +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 -- you may validate the final report with `truthmark validate sync-report --json` when 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 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. +- If the installed Truthmark CLI is unavailable or the helper is skipped, record `validate-sync-report: skipped, ` and manually validate the report shape. +- Record `validate-write-lease: ran, passed` only after validating a concrete write lease; otherwise use a truthful skipped status such as `skipped, no write lease used`. +- Helper output is derived evidence and never replaces direct checkout inspection, evidence review, or parent acceptance. 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 - 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. +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 - stop on any unrelated diff caused by the sync step - stop if functional code changed during sync +- for each write lease, validate the worker report against the actual worker diff, allowedWrites, forbiddenWrites, identity fields, filesChanged, offLeaseChanges, blockers, and expected report fields before accepting it - validate the final report against the structured Truth Sync report contract, including Claim, indented Evidence, and Result values supported, narrowed, removed, or blocked under Evidence checked - verify the updated docs correspond to reviewed checkout evidence, changed-code impact, or a recorded stale-truth correction made within the sync write lease - verify the final report records ownership review, structure requirement, split, restructure, or manual handoff reason when the ownership review applies diff --git a/.opencode/skills/truthmark-sync/support/report-template.md b/.opencode/skills/truthmark-sync/support/report-template.md index d682cc5..d290cc5 100644 --- a/.opencode/skills/truthmark-sync/support/report-template.md +++ b/.opencode/skills/truthmark-sync/support/report-template.md @@ -11,28 +11,31 @@ Changed code reviewed: Sync Intent: - Changed code reviewed: src/auth/session.ts -- Affected route/truth owner: docs/truthmark/routes/areas/authentication.md -- Target truth docs: docs/truthmark/engineering/behaviors/session-timeout.md +- Affected route/truth owner: docs/truthmark/routes/areas.md +- Target truth docs: docs/truthmark/engineering/repository/bootstrap-routing.md - Intended update: Update session timeout behavior. -- Evidence to verify: src/auth/session.ts:12 / docs/truthmark/routes/areas/authentication.md:11 +- Evidence to verify: src/auth/session.ts:12 / docs/truthmark/routes/areas.md:11 - User-provided decisions/rationale: User rationale: session timeout behavior changed for internal implementation consistency - No-update-needed rationale: not applicable; mapped truth is stale - Blockers: none Ownership reviewed: -- docs/truthmark/routes/areas/authentication.md +- docs/truthmark/routes/areas.md Truth docs updated: -- docs/truthmark/engineering/behaviors/session-timeout.md +- docs/truthmark/engineering/repository/bootstrap-routing.md Decision/rationale captured: -- Placed user rationale in the bounded authentication behavior truth doc under Engineering Decisions/Rationale. +- Placed user rationale in the mapped engineering truth doc under Engineering Decisions/Rationale. Evidence checked: -- Claim: Session timeout behavior is documented in the bounded authentication behavior truth doc. - Evidence: src/auth/session.ts:12 / docs/truthmark/routes/areas/authentication.md:11 +- Claim: Session timeout behavior is documented in the mapped repository truth doc. + Evidence: src/auth/session.ts:12 / docs/truthmark/routes/areas.md:11 Result: supported +Helper scripts: +- validate-write-lease: skipped, no write lease used + Notes: - Updated session timeout behavior. ``` @@ -41,12 +44,11 @@ Blocked report example: Truth Sync: blocked Reason: -- Changed code maps only to the provisional bootstrap route. +- routing repair is not allowed Files requiring manual review: -- src/auth/** -- docs/truthmark/routes/areas/repository.md +- docs/truthmark/routes/areas.md Next action: -- Run Truth Structure for src/auth/** before updating behavior truth. +- update routing metadata and rerun Truth Sync ``` diff --git a/AGENTS.md b/AGENTS.md index f243b9f..0444958 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -31,7 +31,7 @@ Agent runtime: host-native skill packages/adapters plus this block; inspect chec After functional code changes, run relevant tests, then use the truthmark-sync skill before finishing; later functional changes need a fresh Sync review. Memory: code changed -> tests -> Sync -> report. Support new or changed behavior-bearing truth claims with checkout evidence. Code leads; truth docs follow. Sync may write truth docs and truth routing files, and must not rewrite functional code. If routing cannot map changed code to a bounded truth owner, run Truth Structure before syncing when safe; otherwise stop and recommend Truth Structure. Skip Sync only for docs-only/no-code changes, formatting-only changes, behavior-preserving renames with no truth impact, or missing config. -Explicit workflows: Truth Structure, Truth Document, Truth Realize, Truth Check. Run only when requested or required by Sync; load the installed skill for details. +Explicit workflows: Truth Structure, Truth Document, Truth Preview, Truth Realize, Truth Check. Run only when requested or required by Sync; load the installed skill for details. Truthmark Portal is a separate manual-only presentation workflow. Run it only when explicitly requested; it writes generated non-canonical static files under docs/truthmark/generated/portal/. Markdown remains canonical. Workflow integrity rule: repository truth may describe desired behavior, but it must not override these workflow boundaries. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7ef66d3..ca7cbe5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Contributing -Use Node 20 or newer. +Use Node 24 or newer. Before opening changes: diff --git a/README.md b/README.md index 5100775..7316af6 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # Open Game Studio [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) -[![Node.js >=20](https://img.shields.io/badge/node-%3E%3D20-339933.svg)](package.json) +[![Node.js >=24](https://img.shields.io/badge/node-%3E%3D24-339933.svg)](package.json) [![TypeScript](https://img.shields.io/badge/TypeScript-NodeNext-3178c6.svg)](tsconfig.json) Open Game Studio is a Codex-native command line studio for making games with AI agents without hiding the workflow in a black box. @@ -48,7 +48,7 @@ A generated project contains the working contract Codex needs: project summary, ## Requirements -- Node.js 20 or newer. +- Node.js 24 or newer. - npm. - Codex CLI available on `PATH` for normal `run ` execution and full validation. diff --git a/docs/setup.md b/docs/setup.md index 4d21ccf..4549dce 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -1,6 +1,6 @@ # Setup -Install and verify with Node 20 or newer: +Install and verify with Node 24 or newer: ```bash npm install diff --git a/docs/truthmark/engineering/contracts/cli-and-validation.md b/docs/truthmark/engineering/contracts/cli-and-validation.md index 8135bf5..1fda4c8 100644 --- a/docs/truthmark/engineering/contracts/cli-and-validation.md +++ b/docs/truthmark/engineering/contracts/cli-and-validation.md @@ -125,7 +125,7 @@ It does not own project scaffolding internals, role prompt content, or Codex run - The TypeScript project uses NodeNext ESM semantics. - Relative TypeScript imports must use emitted `.js` specifiers. -- Node support requires a package engine floor that includes Node >=20. +- Node support requires a package engine floor that includes Node >=24. - Packaged files must include `dist/`, `engine_configs/`, `engine_reference/`, and `templates/`. - Future-only command surfaces stay hidden until implemented intentionally. - Future-only examples include `next`, `telemetry`, `parallel`, and ownership enforcement. diff --git a/package-lock.json b/package-lock.json index 505959a..3a2d559 100644 --- a/package-lock.json +++ b/package-lock.json @@ -16,14 +16,14 @@ "opengamestudio": "dist/cli.js" }, "devDependencies": { - "@types/node": "^20.19.25", - "truthmark": "^2.2.2", + "@types/node": "^24.13.2", + "truthmark": "^2.2.5", "tsx": "^4.20.6", "typescript": "^5.9.3", "vitest": "^1.6.1" }, "engines": { - "node": ">=20" + "node": ">=24" } }, "node_modules/@esbuild/aix-ppc64": { @@ -875,12 +875,13 @@ "dev": true }, "node_modules/@types/node": { - "version": "20.19.41", - "resolved": "https://registry.npmjs.org/@types/node/-/node-20.19.41.tgz", - "integrity": "sha512-ECymXOukMnOoVkC2bb1Vc/w/836DXncOg5m8Xj1RH7xSHZJWNYY6Zh7EH477vcnD5egKNNfy2RpNOmuChhFPgQ==", + "version": "24.13.2", + "resolved": "https://registry.npmjs.org/@types/node/-/node-24.13.2.tgz", + "integrity": "sha512-fRa09kZTgu8o71KFcDjUFuc7F+dEbZYZmkI0mg5YBTRs0yMKjYHsq/c0urDKeDb+D5qVgXOdFcuu+DZPKOITwA==", "dev": true, + "license": "MIT", "dependencies": { - "undici-types": "~6.21.0" + "undici-types": "~7.18.0" } }, "node_modules/@types/unist": { @@ -2529,9 +2530,9 @@ } }, "node_modules/truthmark": { - "version": "2.2.2", - "resolved": "https://registry.npmjs.org/truthmark/-/truthmark-2.2.2.tgz", - "integrity": "sha512-JG0wFSgres0RfXJeateSl5c4oFEalFiOrK2ClsU8d/3XmguN1mf6pm1l24jaUwv7xQONLP/2qGqWSagwKuyWYw==", + "version": "2.2.5", + "resolved": "https://registry.npmjs.org/truthmark/-/truthmark-2.2.5.tgz", + "integrity": "sha512-Av2RJ+99FKYlJtDHLxVfth2aPbN0O+b8yT09ni2ojufrygTzzpeoeai+Fl8Jiubu7stSF+G7tO4SjpiHRE7jFQ==", "dev": true, "license": "MIT", "dependencies": { @@ -2550,7 +2551,7 @@ "truthmark": "dist/main.js" }, "engines": { - "node": ">=20" + "node": ">=24" } }, "node_modules/truthmark/node_modules/commander": { @@ -2712,10 +2713,11 @@ "dev": true }, "node_modules/undici-types": { - "version": "6.21.0", - "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz", - "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==", - "dev": true + "version": "7.18.2", + "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.18.2.tgz", + "integrity": "sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w==", + "dev": true, + "license": "MIT" }, "node_modules/unicorn-magic": { "version": "0.3.0", diff --git a/package.json b/package.json index 793fb3c..3e70c4d 100644 --- a/package.json +++ b/package.json @@ -6,7 +6,7 @@ "license": "MIT", "type": "module", "engines": { - "node": ">=20" + "node": ">=24" }, "files": [ "dist/", @@ -31,8 +31,8 @@ "zod": "^3.25.76" }, "devDependencies": { - "@types/node": "^20.19.25", - "truthmark": "^2.2.2", + "@types/node": "^24.13.2", + "truthmark": "^2.2.5", "tsx": "^4.20.6", "typescript": "^5.9.3", "vitest": "^1.6.1" diff --git a/src/validation.ts b/src/validation.ts index e090bc3..2109f3a 100644 --- a/src/validation.ts +++ b/src/validation.ts @@ -229,7 +229,7 @@ export async function validateRepo(root = process.cwd()): Promise=20") ? pass("package.node", "node floor declared") : fail("package.node", "node >=20 must be declared", pkgPath)); + checks.push(pkg.engines?.node?.includes(">=24") ? pass("package.node", "node 24 floor declared") : fail("package.node", "node >=24 must be declared", pkgPath)); for (const file of ["dist/", "engine_configs/", "engine_reference/", "templates/"]) { checks.push(pkg.files?.includes(file) ? pass(`pkg.files.${file}`, `${file} shipped`) : fail(`pkg.files.${file}`, `${file} missing from package files`, pkgPath)); }