From 1430805b3e20f12ad3f1f62dfe18f734b23e1d7d Mon Sep 17 00:00:00 2001 From: MerlinH Date: Thu, 28 May 2026 16:21:35 +0000 Subject: [PATCH] chore: add truthmark structure and runtime safeguards --- .codex/agents/truth-claim-verifier.toml | 18 + .codex/agents/truth-doc-reviewer.toml | 17 + .codex/agents/truth-doc-writer.toml | 18 + .codex/agents/truth-route-auditor.toml | 18 + .codex/skills/truthmark-check/SKILL.md | 28 + .../skills/truthmark-check/agents/openai.yaml | 11 + .../truthmark-check/support/procedure.md | 37 + .../support/report-template.md | 27 + .../support/subagents-and-leases.md | 10 + .codex/skills/truthmark-document/SKILL.md | 30 + .../truthmark-document/agents/openai.yaml | 11 + .../truthmark-document/helper-manifest.yml | 34 + .../support/helper-policy.md | 23 + .../truthmark-document/support/procedure.md | 79 + .../support/report-template.md | 37 + .../support/subagents-and-leases.md | 14 + .codex/skills/truthmark-preview/SKILL.md | 27 + .../truthmark-preview/agents/openai.yaml | 11 + .../truthmark-preview/support/procedure.md | 43 + .../support/report-template.md | 41 + .../support/subagents-and-leases.md | 10 + .codex/skills/truthmark-realize/SKILL.md | 26 + .../truthmark-realize/agents/openai.yaml | 11 + .../truthmark-realize/support/procedure.md | 42 + .../support/report-template.md | 18 + .codex/skills/truthmark-structure/SKILL.md | 27 + .../truthmark-structure/agents/openai.yaml | 11 + .../truthmark-structure/support/procedure.md | 109 ++ .../support/report-template.md | 35 + .../support/subagents-and-leases.md | 10 + .codex/skills/truthmark-sync/SKILL.md | 31 + .../skills/truthmark-sync/agents/openai.yaml | 11 + .../skills/truthmark-sync/helper-manifest.yml | 34 + .../truthmark-sync/support/helper-policy.md | 23 + .../truthmark-sync/support/procedure.md | 88 ++ .../truthmark-sync/support/report-template.md | 41 + .../support/subagents-and-leases.md | 14 + .github/agents/truth-claim-verifier.agent.md | 19 + .github/agents/truth-doc-reviewer.agent.md | 18 + .github/agents/truth-doc-writer.agent.md | 19 + .github/agents/truth-route-auditor.agent.md | 19 + .github/copilot-instructions.md | 14 + .github/prompts/truthmark-check.prompt.md | 77 + .github/prompts/truthmark-document.prompt.md | 132 ++ .github/prompts/truthmark-preview.prompt.md | 90 ++ .github/prompts/truthmark-realize.prompt.md | 67 + .github/prompts/truthmark-structure.prompt.md | 155 ++ .github/prompts/truthmark-sync.prompt.md | 144 ++ .github/skills/truthmark-check/SKILL.md | 30 + .../truthmark-check/support/procedure.md | 37 + .../support/report-template.md | 27 + .../support/subagents-and-leases.md | 10 + .github/skills/truthmark-document/SKILL.md | 32 + .../truthmark-document/helper-manifest.yml | 34 + .../support/helper-policy.md | 23 + .../truthmark-document/support/procedure.md | 79 + .../support/report-template.md | 37 + .../support/subagents-and-leases.md | 14 + .github/skills/truthmark-preview/SKILL.md | 29 + .../truthmark-preview/support/procedure.md | 43 + .../support/report-template.md | 41 + .../support/subagents-and-leases.md | 10 + .github/skills/truthmark-realize/SKILL.md | 28 + .../truthmark-realize/support/procedure.md | 42 + .../support/report-template.md | 18 + .github/skills/truthmark-structure/SKILL.md | 29 + .../truthmark-structure/support/procedure.md | 109 ++ .../support/report-template.md | 35 + .../support/subagents-and-leases.md | 10 + .github/skills/truthmark-sync/SKILL.md | 33 + .../skills/truthmark-sync/helper-manifest.yml | 34 + .../truthmark-sync/support/helper-policy.md | 23 + .../truthmark-sync/support/procedure.md | 88 ++ .../truthmark-sync/support/report-template.md | 41 + .../support/subagents-and-leases.md | 14 + .opencode/agents/truth-claim-verifier.md | 33 + .opencode/agents/truth-doc-reviewer.md | 32 + .opencode/agents/truth-doc-writer.md | 38 + .opencode/agents/truth-route-auditor.md | 33 + .opencode/skills/truthmark-check/SKILL.md | 28 + .../truthmark-check/support/procedure.md | 37 + .../support/report-template.md | 27 + .../support/subagents-and-leases.md | 10 + .opencode/skills/truthmark-document/SKILL.md | 30 + .../truthmark-document/helper-manifest.yml | 34 + .../support/helper-policy.md | 23 + .../truthmark-document/support/procedure.md | 79 + .../support/report-template.md | 37 + .../support/subagents-and-leases.md | 14 + .opencode/skills/truthmark-preview/SKILL.md | 27 + .../truthmark-preview/support/procedure.md | 43 + .../support/report-template.md | 41 + .../support/subagents-and-leases.md | 10 + .opencode/skills/truthmark-realize/SKILL.md | 26 + .../truthmark-realize/support/procedure.md | 42 + .../support/report-template.md | 18 + .opencode/skills/truthmark-structure/SKILL.md | 27 + .../truthmark-structure/support/procedure.md | 109 ++ .../support/report-template.md | 35 + .../support/subagents-and-leases.md | 10 + .opencode/skills/truthmark-sync/SKILL.md | 31 + .../skills/truthmark-sync/helper-manifest.yml | 34 + .../truthmark-sync/support/helper-policy.md | 23 + .../truthmark-sync/support/procedure.md | 88 ++ .../truthmark-sync/support/report-template.md | 41 + .../support/subagents-and-leases.md | 14 + .truthmark/config.yml | 38 + AGENTS.md | 19 + docs/ai/repo-rules.md | 29 + docs/architecture/repository-structure.md | 52 + docs/standards/default-principles.md | 25 + docs/standards/documentation-governance.md | 23 + docs/templates/architecture-doc.md | 58 + docs/templates/behavior-doc.md | 81 + docs/templates/contract-doc.md | 58 + docs/templates/operations-doc.md | 58 + docs/templates/test-behavior-doc.md | 58 + docs/templates/workflow-doc.md | 58 + docs/truth/README.md | 13 + docs/truth/codex/roles-and-workflows.md | 66 + docs/truth/codex/runtime-and-tasks.md | 86 ++ docs/truth/contracts/cli-and-validation.md | 75 + docs/truth/repository/README.md | 18 + docs/truthmark/areas.md | 28 + docs/truthmark/areas/repository.md | 101 ++ package-lock.json | 1345 +++++++++++++++++ package.json | 1 + src/runner.ts | 65 +- src/tasks.ts | 1 + src/verification.ts | 15 +- tests/runner.test.ts | 52 + tests/tasks.test.ts | 14 + tests/verification.test.ts | 15 + 133 files changed, 6273 insertions(+), 32 deletions(-) create mode 100644 .codex/agents/truth-claim-verifier.toml create mode 100644 .codex/agents/truth-doc-reviewer.toml create mode 100644 .codex/agents/truth-doc-writer.toml create mode 100644 .codex/agents/truth-route-auditor.toml create mode 100644 .codex/skills/truthmark-check/SKILL.md create mode 100644 .codex/skills/truthmark-check/agents/openai.yaml create mode 100644 .codex/skills/truthmark-check/support/procedure.md create mode 100644 .codex/skills/truthmark-check/support/report-template.md create mode 100644 .codex/skills/truthmark-check/support/subagents-and-leases.md create mode 100644 .codex/skills/truthmark-document/SKILL.md create mode 100644 .codex/skills/truthmark-document/agents/openai.yaml create mode 100644 .codex/skills/truthmark-document/helper-manifest.yml create mode 100644 .codex/skills/truthmark-document/support/helper-policy.md create mode 100644 .codex/skills/truthmark-document/support/procedure.md create mode 100644 .codex/skills/truthmark-document/support/report-template.md create mode 100644 .codex/skills/truthmark-document/support/subagents-and-leases.md create mode 100644 .codex/skills/truthmark-preview/SKILL.md create mode 100644 .codex/skills/truthmark-preview/agents/openai.yaml create mode 100644 .codex/skills/truthmark-preview/support/procedure.md create mode 100644 .codex/skills/truthmark-preview/support/report-template.md create mode 100644 .codex/skills/truthmark-preview/support/subagents-and-leases.md create mode 100644 .codex/skills/truthmark-realize/SKILL.md create mode 100644 .codex/skills/truthmark-realize/agents/openai.yaml create mode 100644 .codex/skills/truthmark-realize/support/procedure.md create mode 100644 .codex/skills/truthmark-realize/support/report-template.md create mode 100644 .codex/skills/truthmark-structure/SKILL.md create mode 100644 .codex/skills/truthmark-structure/agents/openai.yaml create mode 100644 .codex/skills/truthmark-structure/support/procedure.md create mode 100644 .codex/skills/truthmark-structure/support/report-template.md create mode 100644 .codex/skills/truthmark-structure/support/subagents-and-leases.md create mode 100644 .codex/skills/truthmark-sync/SKILL.md create mode 100644 .codex/skills/truthmark-sync/agents/openai.yaml create mode 100644 .codex/skills/truthmark-sync/helper-manifest.yml create mode 100644 .codex/skills/truthmark-sync/support/helper-policy.md create mode 100644 .codex/skills/truthmark-sync/support/procedure.md create mode 100644 .codex/skills/truthmark-sync/support/report-template.md create mode 100644 .codex/skills/truthmark-sync/support/subagents-and-leases.md create mode 100644 .github/agents/truth-claim-verifier.agent.md create mode 100644 .github/agents/truth-doc-reviewer.agent.md create mode 100644 .github/agents/truth-doc-writer.agent.md create mode 100644 .github/agents/truth-route-auditor.agent.md create mode 100644 .github/copilot-instructions.md create mode 100644 .github/prompts/truthmark-check.prompt.md create mode 100644 .github/prompts/truthmark-document.prompt.md create mode 100644 .github/prompts/truthmark-preview.prompt.md create mode 100644 .github/prompts/truthmark-realize.prompt.md create mode 100644 .github/prompts/truthmark-structure.prompt.md create mode 100644 .github/prompts/truthmark-sync.prompt.md create mode 100644 .github/skills/truthmark-check/SKILL.md create mode 100644 .github/skills/truthmark-check/support/procedure.md create mode 100644 .github/skills/truthmark-check/support/report-template.md create mode 100644 .github/skills/truthmark-check/support/subagents-and-leases.md create mode 100644 .github/skills/truthmark-document/SKILL.md create mode 100644 .github/skills/truthmark-document/helper-manifest.yml create mode 100644 .github/skills/truthmark-document/support/helper-policy.md create mode 100644 .github/skills/truthmark-document/support/procedure.md create mode 100644 .github/skills/truthmark-document/support/report-template.md create mode 100644 .github/skills/truthmark-document/support/subagents-and-leases.md create mode 100644 .github/skills/truthmark-preview/SKILL.md create mode 100644 .github/skills/truthmark-preview/support/procedure.md create mode 100644 .github/skills/truthmark-preview/support/report-template.md create mode 100644 .github/skills/truthmark-preview/support/subagents-and-leases.md create mode 100644 .github/skills/truthmark-realize/SKILL.md create mode 100644 .github/skills/truthmark-realize/support/procedure.md create mode 100644 .github/skills/truthmark-realize/support/report-template.md create mode 100644 .github/skills/truthmark-structure/SKILL.md create mode 100644 .github/skills/truthmark-structure/support/procedure.md create mode 100644 .github/skills/truthmark-structure/support/report-template.md create mode 100644 .github/skills/truthmark-structure/support/subagents-and-leases.md create mode 100644 .github/skills/truthmark-sync/SKILL.md create mode 100644 .github/skills/truthmark-sync/helper-manifest.yml create mode 100644 .github/skills/truthmark-sync/support/helper-policy.md create mode 100644 .github/skills/truthmark-sync/support/procedure.md create mode 100644 .github/skills/truthmark-sync/support/report-template.md create mode 100644 .github/skills/truthmark-sync/support/subagents-and-leases.md create mode 100644 .opencode/agents/truth-claim-verifier.md create mode 100644 .opencode/agents/truth-doc-reviewer.md create mode 100644 .opencode/agents/truth-doc-writer.md create mode 100644 .opencode/agents/truth-route-auditor.md create mode 100644 .opencode/skills/truthmark-check/SKILL.md create mode 100644 .opencode/skills/truthmark-check/support/procedure.md create mode 100644 .opencode/skills/truthmark-check/support/report-template.md create mode 100644 .opencode/skills/truthmark-check/support/subagents-and-leases.md create mode 100644 .opencode/skills/truthmark-document/SKILL.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-document/support/procedure.md create mode 100644 .opencode/skills/truthmark-document/support/report-template.md create mode 100644 .opencode/skills/truthmark-document/support/subagents-and-leases.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-realize/SKILL.md create mode 100644 .opencode/skills/truthmark-realize/support/procedure.md create mode 100644 .opencode/skills/truthmark-realize/support/report-template.md create mode 100644 .opencode/skills/truthmark-structure/SKILL.md create mode 100644 .opencode/skills/truthmark-structure/support/procedure.md create mode 100644 .opencode/skills/truthmark-structure/support/report-template.md create mode 100644 .opencode/skills/truthmark-structure/support/subagents-and-leases.md create mode 100644 .opencode/skills/truthmark-sync/SKILL.md create mode 100644 .opencode/skills/truthmark-sync/helper-manifest.yml create mode 100644 .opencode/skills/truthmark-sync/support/helper-policy.md create mode 100644 .opencode/skills/truthmark-sync/support/procedure.md create mode 100644 .opencode/skills/truthmark-sync/support/report-template.md create mode 100644 .opencode/skills/truthmark-sync/support/subagents-and-leases.md create mode 100644 .truthmark/config.yml create mode 100644 docs/ai/repo-rules.md create mode 100644 docs/architecture/repository-structure.md create mode 100644 docs/standards/default-principles.md create mode 100644 docs/standards/documentation-governance.md create mode 100644 docs/templates/architecture-doc.md create mode 100644 docs/templates/behavior-doc.md create mode 100644 docs/templates/contract-doc.md create mode 100644 docs/templates/operations-doc.md create mode 100644 docs/templates/test-behavior-doc.md create mode 100644 docs/templates/workflow-doc.md create mode 100644 docs/truth/README.md create mode 100644 docs/truth/codex/roles-and-workflows.md create mode 100644 docs/truth/codex/runtime-and-tasks.md create mode 100644 docs/truth/contracts/cli-and-validation.md create mode 100644 docs/truth/repository/README.md create mode 100644 docs/truthmark/areas.md create mode 100644 docs/truthmark/areas/repository.md create mode 100644 tests/runner.test.ts create mode 100644 tests/tasks.test.ts diff --git a/.codex/agents/truth-claim-verifier.toml b/.codex/agents/truth-claim-verifier.toml new file mode 100644 index 0000000..e52bcf2 --- /dev/null +++ b/.codex/agents/truth-claim-verifier.toml @@ -0,0 +1,18 @@ +# Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. +name = "truth_claim_verifier" +description = "Read-only Truthmark claim verifier for checking canonical truth against checkout evidence." +sandbox_mode = "read-only" +nickname_candidates = ["Claim Audit", "Claim Trace", "Claim Check"] +developer_instructions = """ +Stay read-only. +Verify the behavior-bearing truth claims assigned by the parent against primary checkout evidence. +Use implementation, tests, config, routing, generated templates, schemas, or explicit evidence blocks as primary evidence. +Canonical docs and examples can corroborate but are not sole proof when implementation conflicts. +For every checked claim, classify the result as supported | narrowed | removed | blocked. +Do not edit files, stage changes, or invent missing behavior. +Return JSON only with keys: scope, filesReviewed, claimsChecked, evidence, unsupportedClaims, confidence, recommendedWorkflow, notes. +Context boundary: +Do not preload AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, or repo-wide policy docs unless the parent explicitly assigns them as evidence. +Use only the parent-assigned shard plus required checkout evidence files. +Return findings only; the parent workflow owns repository-policy interpretation, final decisions, and all writes. +""" diff --git a/.codex/agents/truth-doc-reviewer.toml b/.codex/agents/truth-doc-reviewer.toml new file mode 100644 index 0000000..03ee31d --- /dev/null +++ b/.codex/agents/truth-doc-reviewer.toml @@ -0,0 +1,17 @@ +# Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. +name = "truth_doc_reviewer" +description = "Read-only Truthmark doc reviewer for shape, decision, rationale, and evidence hygiene." +sandbox_mode = "read-only" +nickname_candidates = ["Doc Audit", "Doc Shape", "Doc Check"] +developer_instructions = """ +Stay read-only. +Review assigned canonical truth docs for frontmatter, source_of_truth, required template sections, Evidence checked entries, Product Decisions, and Rationale. +Flag README.md files used as behavior truth targets, mixed-owner docs, and shape repairs that should move to Truth Structure. +Do not edit files, stage changes, or rewrite docs. +Return JSON only with keys: scope, filesReviewed, findings, evidence, confidence, recommendedWorkflow, notes. +recommendedWorkflow must be one of: none, truthmark-document, truthmark-structure. +Context boundary: +Do not preload AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, or repo-wide policy docs unless the parent explicitly assigns them as evidence. +Use only the parent-assigned shard plus required checkout evidence files. +Return findings only; the parent workflow owns repository-policy interpretation, final decisions, and all writes. +""" diff --git a/.codex/agents/truth-doc-writer.toml b/.codex/agents/truth-doc-writer.toml new file mode 100644 index 0000000..06af27e --- /dev/null +++ b/.codex/agents/truth-doc-writer.toml @@ -0,0 +1,18 @@ +# Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. +name = "truth_doc_writer" +description = "Write-capable Truthmark doc worker for one parent-leased truth-document shard." +sandbox_mode = "workspace-write" +nickname_candidates = ["Doc Writer", "Truth Writer", "Doc Sync"] +developer_instructions = """ +Write one leased Truthmark truth-document shard assigned by the parent. +Require an explicit write lease before editing. The lease must name workflow, worker, shard, objective, requiredReads, allowedWrites, forbiddenWrites, evidenceRequired, verification, and reportFields. +Read every requiredReads entry directly before editing. +Edit only leased canonical truth docs or leased truth routing files. Do not edit functional code, generated host surfaces, package files, config files, templates, or tests unless they are explicitly leased. +Do not expand your own write scope. If the task needs an off-lease file, stop and report blocked. +Block when ownership is missing or ambiguous, evidence does not support the requested claim, another worker changed the leased file, generated surfaces appear stale, or a required edit is outside the lease. +Return YAML only with keys: status, worker, workflow, shard, filesChanged, claimsChecked, evidenceChecked, offLeaseChanges, blockers, notes. +status must be completed or blocked. +filesChanged must list only files you actually changed. +offLeaseChanges must be empty for completed reports. +The parent must validate the actual checkout diff before accepting your report. +""" diff --git a/.codex/agents/truth-route-auditor.toml b/.codex/agents/truth-route-auditor.toml new file mode 100644 index 0000000..ba1b766 --- /dev/null +++ b/.codex/agents/truth-route-auditor.toml @@ -0,0 +1,18 @@ +# Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. +name = "truth_route_auditor" +description = "Read-only Truthmark route auditor for bounded routing and ownership verification." +sandbox_mode = "read-only" +nickname_candidates = ["Route Audit", "Route Trace", "Route Check"] +developer_instructions = """ +Stay read-only. +Audit one bounded Truthmark route, area, or doc shard assigned by the parent. +Inspect .truthmark/config.yml and route files only when they exist; then inspect mapped truth docs and relevant implementation files directly. +Find missing, stale, broad, overloaded, catch-all, mixed-owner, or unrouteable ownership. +Do not edit files, stage changes, or propose broad rewrites. +Return JSON only with keys: scope, filesReviewed, findings, evidence, confidence, recommendedWorkflow, notes. +recommendedWorkflow must be one of: none, truthmark-document, truthmark-structure. +Context boundary: +Do not preload AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, or repo-wide policy docs unless the parent explicitly assigns them as evidence. +Use only the parent-assigned shard plus required checkout evidence files. +Return findings only; the parent workflow owns repository-policy interpretation, final decisions, and all writes. +""" diff --git a/.codex/skills/truthmark-check/SKILL.md b/.codex/skills/truthmark-check/SKILL.md new file mode 100644 index 0000000..a81e78f --- /dev/null +++ b/.codex/skills/truthmark-check/SKILL.md @@ -0,0 +1,28 @@ +--- +name: truthmark-check +description: Use when the user asks to audit repository truth health, routing, ownership, or canonical docs. Not for normal lint/test/typecheck/code-review verification, finish-time Sync, or silently rewriting docs. +argument-hint: Optional area, doc path, or audit focus +user-invocable: true +truthmark-version: 1.6.0 +--- + +# Truthmark Check + +Use this skill to audit repository truth health. + + +Invocations: OpenCode /skill truthmark-check; Codex /truthmark-check or $truthmark-check; Claude Code /truthmark-check; GitHub Copilot /truthmark-check; Gemini CLI /truthmark:check. + +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/areas.md; docs/truthmark/areas/) only when they exist; then inspect canonical docs and relevant implementation directly. +- Report issues and suggested fixes; do not silently rewrite unrelated files. +- Direct checkout inspection is valid even when local tooling is unavailable. +- Read support/procedure.md before auditing details. +- Read support/subagents-and-leases.md before dispatching verifier subagents. +- Read support/report-template.md before the final report. + +Progressive disclosure: +- support/procedure.md +- support/report-template.md +- support/subagents-and-leases.md diff --git a/.codex/skills/truthmark-check/agents/openai.yaml b/.codex/skills/truthmark-check/agents/openai.yaml new file mode 100644 index 0000000..8a350a7 --- /dev/null +++ b/.codex/skills/truthmark-check/agents/openai.yaml @@ -0,0 +1,11 @@ +interface: + display_name: "Truthmark Check" + short_description: "Audit repository truth health" + default_prompt: "Use $truthmark-check to audit repository truth health." + +policy: + allow_implicit_invocation: false + +truthmark: + version: "1.6.0" + refresh_command: "truthmark init" diff --git a/.codex/skills/truthmark-check/support/procedure.md b/.codex/skills/truthmark-check/support/procedure.md new file mode 100644 index 0000000..33b7663 --- /dev/null +++ b/.codex/skills/truthmark-check/support/procedure.md @@ -0,0 +1,37 @@ +# Truthmark Check Procedure + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +# Truthmark Check + +Use this skill to audit repository truth health. + +Invocations: OpenCode /skill truthmark-check; Codex /truthmark-check or $truthmark-check; Claude Code /truthmark-check; GitHub Copilot /truthmark-check; Gemini CLI /truthmark:check. + +Truth Check is agent-led: + +- inspect .truthmark/config.yml and configured route files only when they exist; then inspect canonical docs and relevant implementation directly +- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. +Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. +- inspect the configured root route index at docs/truthmark/areas.md and relevant child route files under docs/truthmark/areas/ when they exist +- check that current docs describe current code rather than historical plans +- check that route files map code surfaces to canonical truth docs when route files exist +- check for broad, catch-all, index-like, or mixed-owner truth docs and report them as topology issues requiring Truth Structure +- check that canonical behavior docs keep active Product Decisions and Rationale sections +- optionally run truthmark check when local tooling is available +- must not require the truthmark binary; direct inspection is always valid +- report issues and suggested fixes without silently rewriting unrelated files +- if follow-up docs edits are needed for mixed-owner docs, run or recommend Truth Structure before editing +Evidence Gate: +- support each finding and suggested fix with evidence from config, route files, canonical docs, implementation, templates, or tests +- canonical docs are context, not sole proof when implementation conflicts +- remove unsupported findings or mark open questions; validate changed claims if you edit docs + +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md +Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. +Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. +Update Product Decisions and Rationale when a decision changes behavior. diff --git a/.codex/skills/truthmark-check/support/report-template.md b/.codex/skills/truthmark-check/support/report-template.md new file mode 100644 index 0000000..e98269e --- /dev/null +++ b/.codex/skills/truthmark-check/support/report-template.md @@ -0,0 +1,27 @@ +# Truthmark Check Report Template + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Report completion in this shape: + +```md +Truth Check: completed + +Files reviewed: +- docs/truthmark/areas.md + +Issues found: +- none + +Fixes suggested: +- none + +Evidence checked: +- Finding: The root route index is present and maps repository truth owners. + Evidence: docs/truthmark/areas.md:1 + Suggested fix: none + Confidence: high + +Validation: +- truthmark check +``` diff --git a/.codex/skills/truthmark-check/support/subagents-and-leases.md b/.codex/skills/truthmark-check/support/subagents-and-leases.md new file mode 100644 index 0000000..0f1a0a2 --- /dev/null +++ b/.codex/skills/truthmark-check/support/subagents-and-leases.md @@ -0,0 +1,10 @@ +# Truthmark Check Subagents And Leases + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Codex subagent mode: +- use automatically when this workflow runs in Codex and the parent agent chooses bounded subagent fan-out +- dispatch read-only project agents only: truth_route_auditor, truth_claim_verifier, truth_doc_reviewer +- workers inspect checkout evidence directly, return structured findings, and must not edit files +- parent supplies bounded evidence shards; workers must not preload host instruction files or repo-wide policy docs unless assigned as evidence +- Parent agent owns the final Truth Check report diff --git a/.codex/skills/truthmark-document/SKILL.md b/.codex/skills/truthmark-document/SKILL.md new file mode 100644 index 0000000..751caa5 --- /dev/null +++ b/.codex/skills/truthmark-document/SKILL.md @@ -0,0 +1,30 @@ +--- +name: truthmark-document +description: Use when the user asks to document existing implemented behavior, or Sync, Check, or Structure finds implemented behavior missing canonical truth. Not for functional-code changes, doc-first implementation, or topology repair that needs Structure. +argument-hint: Optional implemented behavior, API endpoint, route, controller, package, or truth-doc area to document +user-invocable: true +truthmark-version: 1.6.0 +--- + +# Truthmark Document + +Use this skill to document existing implemented behavior when no functional-code changes are required for the task. + + +Invocations: OpenCode /skill truthmark-document; Codex /truthmark-document or $truthmark-document; Claude Code /truthmark-document; GitHub Copilot /truthmark-document; Gemini CLI /truthmark:document. + +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/areas.md; docs/truthmark/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 before dispatching or accepting worker output. +- Read support/report-template.md before the final report. + +Progressive disclosure: +- support/procedure.md +- support/report-template.md +- support/subagents-and-leases.md +- helper-manifest.yml +- support/helper-policy.md diff --git a/.codex/skills/truthmark-document/agents/openai.yaml b/.codex/skills/truthmark-document/agents/openai.yaml new file mode 100644 index 0000000..8f286c1 --- /dev/null +++ b/.codex/skills/truthmark-document/agents/openai.yaml @@ -0,0 +1,11 @@ +interface: + display_name: "Truthmark Document" + short_description: "Document existing implemented behavior" + default_prompt: "Use $truthmark-document to document existing implemented behavior." + +policy: + allow_implicit_invocation: false + +truthmark: + version: "1.6.0" + refresh_command: "truthmark init" diff --git a/.codex/skills/truthmark-document/helper-manifest.yml b/.codex/skills/truthmark-document/helper-manifest.yml new file mode 100644 index 0000000..dc05fe5 --- /dev/null +++ b/.codex/skills/truthmark-document/helper-manifest.yml @@ -0,0 +1,34 @@ +# Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. +helpers: + validate-document-report: + optional: true + runner: truthmark>=1.6.0 + 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>=1.6.0 + 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/.codex/skills/truthmark-document/support/helper-policy.md b/.codex/skills/truthmark-document/support/helper-policy.md new file mode 100644 index 0000000..53b72b7 --- /dev/null +++ b/.codex/skills/truthmark-document/support/helper-policy.md @@ -0,0 +1,23 @@ +# Optional Helper CLI Policy + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Optional helper CLI commands may collect deterministic checkout facts or validate artifacts. If the Truthmark CLI is unavailable or too old for a declared helper, continue manually using this procedure and report which helper was skipped. Helper output is derived evidence; it does not override direct checkout inspection, workflow write boundaries, or parent acceptance. + +Runner detection: +- Check the declared Truthmark CLI runner before invoking a helper. +- Invoke helpers through the installed `truthmark validate ... --json` CLI command using argv-style arguments from helper-manifest.yml. +- If unavailable or version-mismatched, 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>=1.6.0; manual fallback: manually validate support/report-template.md required sections and structured Evidence checked entries +- validate-write-lease: optional truthmark>=1.6.0; 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/.codex/skills/truthmark-document/support/procedure.md b/.codex/skills/truthmark-document/support/procedure.md new file mode 100644 index 0000000..44d8eb3 --- /dev/null +++ b/.codex/skills/truthmark-document/support/procedure.md @@ -0,0 +1,79 @@ +# Truthmark Document Procedure + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +# Truthmark Document + +Use this skill to document existing implemented behavior when no functional-code changes are required for the task. +Invocations: OpenCode /skill truthmark-document; Codex /truthmark-document or $truthmark-document; Claude Code /truthmark-document; GitHub Copilot /truthmark-document; Gemini CLI /truthmark:document. + +Truth Document is manual and implementation-first: + +- run only when the user explicitly asks to generate or update truth docs for existing behavior, or when Truth Sync, Truth Check, or Truth Structure reports implemented behavior that lacks canonical truth docs +- inspect .truthmark/config.yml and configured route files only when they exist; then inspect existing canonical docs, implementation code, and tests directly +- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. +Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. +- document current implemented behavior; do not invent future behavior or planned endpoints +- may write canonical truth docs and docs/truthmark/areas.md or relevant child route files only +- must not write functional code +- when routing is missing, stale, broad, overloaded, catch-all, or cannot map the behavior to a bounded truth owner, run Truth Structure first when routing repair is safe and in scope +- block and recommend Truth Structure when routing repair is unsafe, ambiguous, or outside the task boundary +- keep feature README.md files as indexes rather than truth-document targets +- create or update bounded leaf truth docs when behavior does not fit an existing leaf doc +- keep behavior truth docs behavior-oriented, not endpoint-oriented, unless the endpoint itself is the behavior boundary +- keep API endpoint details in the nearest contract truth doc when such a doc owns the API contract +- preserve unrelated authored content +Truth-doc ownership gate: +- before editing or relying on the implemented behavior and candidate truth docs, verify each target/source truth doc is a bounded owner for the behavior +- if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it +- if the target doc is broad, mixed-owner, index-like, or the documented behavior spans independent owners, run Truth Structure first when safe and in scope; otherwise block and recommend Truth Structure +- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Blocked reason as applicable +Product Decisions/Rationale preservation gate: +- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions and Rationale sections in every source or touched truth doc +- preserve each current decision and rationale in the bounded owner doc it governs; when splitting, move it to the new owner doc rather than deleting it or leaving it in an index +- remove or narrow a decision or rationale only when checkout evidence shows it is stale or unsupported, and report the exact claim, evidence, and result +- if ownership of a decision or rationale is unclear, block with manual-review files instead of deleting it or guessing +- after the edit, verify every touched truth doc still has Product Decisions and Rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked +Evidence Gate: +- route-first: map the documented behavior to bounded route owners and primary canonical docs +- review new or changed behavior-bearing claims only in touched docs, route ownership, Product Decisions, and Rationale +- support claims with primary checkout evidence: implementation, config, routing, generated templates, schemas, or contract definitions +- tests/examples/canonical docs corroborate; they are not sole proof when implementation conflicts +- remove, narrow, or block unsupported claims +- if no truth doc changed, report why current truth was already sufficient or why documentation was blocked +Repository intelligence artifacts are optional derived context: RepoIndex, RouteMap, ImpactSet, and ContextPack may guide routing, context selection, and verification planning when available. +They do not override checkout evidence, canonical truth docs, route files, or workflow write boundaries. +If unavailable, inspect any present Truthmark config, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated. +When creating or updating a truth doc, inspect the routed truth kind and use the matching `docs/templates/-doc.md` template. +Supported kinds: behavior, contract, architecture, workflow, operations, and test-behavior. +Align existing docs to that template while preserving accurate authored content. +If the template is missing, use Scope, Product Decisions, Rationale, and the kind-specific current-truth section. +Teams may edit the template files under docs/templates/ to define their local truth-doc standards. +Truth-doc shape repair gate: +- Truth Document may restructure only truth docs for the implemented behavior being documented. +- repair shape in place only after the ownership gate confirms the doc is the right bounded owner +- use Truth Structure for ownership splits; do not treat broad or mixed-owner docs as in-place repair work +- repair shape when a narrow edit would make truth worse: missing template sections, stale evidence conflicts, cross-section updates within one owner, or wrong frontmatter/source/headings +- preserve supported claims; remove, narrow, or block unsupported or stale claims +- report docs restructured and why a narrow edit was not sufficient +Maintain architecture docs only for structure-level changes: system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership. +Keep ordinary behavior, endpoints, UI copy, validation rules, and bug fixes in behavior or contract docs unless they change those boundaries. +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md +Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. +Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. +Update Product Decisions and Rationale when a decision changes behavior. +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 +- block on functional code, generated host surfaces, or unrelated diffs caused by document work +- for each write lease, validate the worker report against the actual worker diff, allowedWrites, forbiddenWrites, identity fields, filesChanged, offLeaseChanges, blockers, and required report fields before accepting it +- verify the final report records ownership review, structure requirement, restructure, routing update, or blocked reason when applicable diff --git a/.codex/skills/truthmark-document/support/report-template.md b/.codex/skills/truthmark-document/support/report-template.md new file mode 100644 index 0000000..22741ff --- /dev/null +++ b/.codex/skills/truthmark-document/support/report-template.md @@ -0,0 +1,37 @@ +# Truthmark Document Report Template + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Report completion in this shape: +```md +Truth Document: completed + +Implementation reviewed: +- src/routing/area-resolver.ts + +Ownership reviewed: +- docs/truthmark/areas.md + +Truth docs created: +- docs/truth/contracts.md + +Truth docs updated: +- docs/truth/check-diagnostics.md + +Truth docs restructured: +- docs/truth/check-diagnostics.md + +Routing updated: +- docs/truthmark/areas.md + +Evidence checked: +- Claim: Route resolution behavior is documented in the contracts truth doc. + Evidence: src/routing/area-resolver.ts:14 / docs/truthmark/areas.md:9 + Result: supported + +Helper scripts: +- validate-write-lease: skipped, no write lease used + +Notes: +- Documented routing and behavior from route handlers and tests. +``` diff --git a/.codex/skills/truthmark-document/support/subagents-and-leases.md b/.codex/skills/truthmark-document/support/subagents-and-leases.md new file mode 100644 index 0000000..72ce420 --- /dev/null +++ b/.codex/skills/truthmark-document/support/subagents-and-leases.md @@ -0,0 +1,14 @@ +# Truthmark Document Subagents And Leases + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Codex subagent mode: +- use automatically when this workflow runs in Codex and the parent agent chooses bounded subagent fan-out +- dispatch read-only project agents for verification: truth_route_auditor, truth_claim_verifier +- read-only workers inspect checkout evidence directly, return structured findings, and must not edit files +- parent supplies bounded evidence shards; read-only workers must not preload host instruction files or repo-wide policy docs unless assigned as evidence +- dispatch write-capable project agents only with explicit write leases: truth_doc_writer +- each write lease must name objective, required reads, allowed writes, forbidden writes, evidence, verification, and report fields +- write workers must stop when a required edit is off-lease and report status, filesChanged, evidence, offLeaseChanges, blockers, and notes +- parent must inspect the actual checkout diff against each lease before accepting a worker report +- Parent agent owns Truth Document acceptance, lease validation, and final report diff --git a/.codex/skills/truthmark-preview/SKILL.md b/.codex/skills/truthmark-preview/SKILL.md new file mode 100644 index 0000000..05e0598 --- /dev/null +++ b/.codex/skills/truthmark-preview/SKILL.md @@ -0,0 +1,27 @@ +--- +name: truthmark-preview +description: Use when the user explicitly asks to preview likely workflow routing, target files, writes, or subagent use before edits. Not for validation, automatic gates, final correctness, or replacing Truth Check. +argument-hint: Optional requested outcome, code area, doc path, or routing question +user-invocable: true +truthmark-version: 1.6.0 +--- + +# Truthmark Preview + +Use this skill only when the user explicitly asks to preview Truthmark routing or workflow choice before edits. + + +Invocations: OpenCode /skill truthmark-preview; Codex /truthmark-preview or $truthmark-preview; Claude Code /truthmark-preview; GitHub Copilot /truthmark-preview; Gemini CLI /truthmark:preview. + +Quick procedure: +- Follow 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/areas.md; docs/truthmark/areas/) only when they exist; then inspect only the truth docs or implementation files needed to preview ownership. +- Truth Preview is read-only; this report is intended, not authorized. +- must not edit files and must not issue write leases; do not run Truth Sync automatically, replace Truth Check, claim final correctness, or mutate code. +- Use optional read-only route-auditor evidence only when it reduces context or clarifies ownership. +- Hand off to the selected workflow after user approval. + +Progressive disclosure: +- support/procedure.md +- support/report-template.md +- support/subagents-and-leases.md diff --git a/.codex/skills/truthmark-preview/agents/openai.yaml b/.codex/skills/truthmark-preview/agents/openai.yaml new file mode 100644 index 0000000..fadb6af --- /dev/null +++ b/.codex/skills/truthmark-preview/agents/openai.yaml @@ -0,0 +1,11 @@ +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: + version: "1.6.0" + refresh_command: "truthmark init" diff --git a/.codex/skills/truthmark-preview/support/procedure.md b/.codex/skills/truthmark-preview/support/procedure.md new file mode 100644 index 0000000..d419bf2 --- /dev/null +++ b/.codex/skills/truthmark-preview/support/procedure.md @@ -0,0 +1,43 @@ +# Truthmark Preview Procedure + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Use this skill only when the user explicitly asks to preview Truthmark routing or workflow choice before edits. + +Invocations: OpenCode /skill truthmark-preview; Codex /truthmark-preview or $truthmark-preview; Claude Code /truthmark-preview; GitHub Copilot /truthmark-preview; Gemini CLI /truthmark:preview. + +Truth Preview is read-only. Its report is intended, not authorized. + +Purpose: +- preview the likely Truthmark workflow, route owner, target files, expected write classes, suggested subagent use, and blocking ambiguity before edits happen +- hand off to the selected workflow after user approval +- keep the selector thin so agents can avoid loading or acting through heavier workflows prematurely + +Read: +- .truthmark/config.yml, only when present +- docs/truthmark/areas.md, only when present +- relevant child route files under docs/truthmark/areas/, only when present +- relevant truth docs and implementation files needed to preview ownership +- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. +Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. + +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/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md diff --git a/.codex/skills/truthmark-preview/support/report-template.md b/.codex/skills/truthmark-preview/support/report-template.md new file mode 100644 index 0000000..72cf72b --- /dev/null +++ b/.codex/skills/truthmark-preview/support/report-template.md @@ -0,0 +1,41 @@ +# Truthmark Preview Report Template + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Report completion in this shape: +```md +Truth Preview: completed + +Requested outcome: +- preview likely Truthmark workflow routing before edits + +Likely workflow: +- truthmark-document + +Why this workflow: +- positive trigger: document existing implemented behavior +- negative triggers considered: functional-code change, doc-first implementation, topology repair, truth audit +- forbidden adjacency considered: must not edit functional code + +Likely route owner: +- route file: docs/truthmark/areas.md +- truth doc: docs/truth/example.md +- confidence: medium + +Expected write classes: +- truth docs + +Expected target files: +- docs/truth/example.md + +Suggested subagent use: +- read-only verifiers: truth_route_auditor +- write workers: none in Preview +- leases needed: none in Preview + +Blocking ambiguity: +- none identified in preview + +Handoff: +- Run the selected Truthmark workflow after user approval. +``` diff --git a/.codex/skills/truthmark-preview/support/subagents-and-leases.md b/.codex/skills/truthmark-preview/support/subagents-and-leases.md new file mode 100644 index 0000000..edee679 --- /dev/null +++ b/.codex/skills/truthmark-preview/support/subagents-and-leases.md @@ -0,0 +1,10 @@ +# Truthmark Preview Subagents And Leases + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Codex subagent mode: +- use automatically when this workflow runs in Codex and the parent agent chooses bounded subagent fan-out +- 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/.codex/skills/truthmark-realize/SKILL.md b/.codex/skills/truthmark-realize/SKILL.md new file mode 100644 index 0000000..c91e02d --- /dev/null +++ b/.codex/skills/truthmark-realize/SKILL.md @@ -0,0 +1,26 @@ +--- +name: truthmark-realize +description: Use when the user explicitly asks to realize Truthmark truth docs into code, including /truthmark-realize, $truthmark-realize, or /truthmark:realize. Not for syncing docs after code changes, documenting existing code, topology repair, or truth audits. +argument-hint: Optional truth doc path, area, or desired code behavior to realize +user-invocable: true +truthmark-version: 1.6.0 +--- + +# Truthmark Realize + +Use this skill only when the user explicitly asks to realize truth docs into code. + + +Invocations: OpenCode /skill truthmark-realize; Codex /truthmark-realize or $truthmark-realize; Claude Code /truthmark-realize; GitHub Copilot /truthmark-realize; Gemini CLI /truthmark:realize. + +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/areas.md; docs/truthmark/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 +- support/report-template.md diff --git a/.codex/skills/truthmark-realize/agents/openai.yaml b/.codex/skills/truthmark-realize/agents/openai.yaml new file mode 100644 index 0000000..e06f4ed --- /dev/null +++ b/.codex/skills/truthmark-realize/agents/openai.yaml @@ -0,0 +1,11 @@ +interface: + display_name: "Truthmark Realize" + short_description: "Realize truth docs into code" + default_prompt: "Use $truthmark-realize to realize the updated truth docs into code." + +policy: + allow_implicit_invocation: false + +truthmark: + version: "1.6.0" + refresh_command: "truthmark init" diff --git a/.codex/skills/truthmark-realize/support/procedure.md b/.codex/skills/truthmark-realize/support/procedure.md new file mode 100644 index 0000000..aa9883b --- /dev/null +++ b/.codex/skills/truthmark-realize/support/procedure.md @@ -0,0 +1,42 @@ +# Truthmark Realize Procedure + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +# Truthmark Realize + +Use this skill only when the user explicitly asks to realize truth docs into code. + +Invocations: OpenCode /skill truthmark-realize; Codex /truthmark-realize or $truthmark-realize; Claude Code /truthmark-realize; GitHub Copilot /truthmark-realize; Gemini CLI /truthmark:realize. + +Truth Realize is doc-first: + +- truth docs lead +- code follows +- Truth Realize never edits the truth docs it is realizing + +Workflow: + +1. Read the updated truth docs named by the user, or infer the relevant docs from configured route files when present. +2. Inspect .truthmark/config.yml and configured route files (docs/truthmark/areas.md; docs/truthmark/areas/) only when they exist; then read tests and the relevant functional code. +3. 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. +Truth-doc ownership gate: +- before editing or relying on source truth docs before writing code, verify each target/source truth doc is a bounded owner for the behavior +- if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it +- if a source truth doc is broad, mixed-owner, index-like, unrouteable, stale, or conflicts with implementation evidence, block before writing code and recommend Truth Structure or Truth Document +- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Blocked reason as applicable +4. Update functional code only so implementation matches bounded, current truth claims from the source docs. +5. Do not edit truth docs or truth routing while realizing those docs. +6. Run relevant tests for the changed code. +7. Report changed code files and verification steps. +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md + +Read and write boundaries: + +- may read truth docs, routing docs, and relevant functional code +- may write functional code only +- must not edit truth docs or truth routing while realizing those docs diff --git a/.codex/skills/truthmark-realize/support/report-template.md b/.codex/skills/truthmark-realize/support/report-template.md new file mode 100644 index 0000000..e49dde5 --- /dev/null +++ b/.codex/skills/truthmark-realize/support/report-template.md @@ -0,0 +1,18 @@ +# Truthmark Realize Report Template + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Report completion in this shape: + +```md +Truth Realize: completed + +Truth docs used: +- docs/truth/authentication/session-timeout.md + +Code updated: +- src/auth/session.ts + +Verification: +- npm test -- auth +``` diff --git a/.codex/skills/truthmark-structure/SKILL.md b/.codex/skills/truthmark-structure/SKILL.md new file mode 100644 index 0000000..67f522b --- /dev/null +++ b/.codex/skills/truthmark-structure/SKILL.md @@ -0,0 +1,27 @@ +--- +name: truthmark-structure +description: Use when routing or truth ownership is missing, stale, broad, overloaded, catch-all, unrouteable, mixed-owner, needs split/repair, or needs new area setup. Not for documenting implemented behavior, syncing a code diff, or realizing docs into code. +argument-hint: Optional area, directory, or routing concern +user-invocable: true +truthmark-version: 1.6.0 +--- + +# Truthmark Structure + +Use this skill to design or repair Truthmark area structure. + + +Invocations: OpenCode /skill truthmark-structure; Codex /truthmark-structure or $truthmark-structure; Claude Code /truthmark-structure; GitHub Copilot /truthmark-structure; Gemini CLI /truthmark:structure. + +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/areas.md; docs/truthmark/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 +- support/report-template.md +- support/subagents-and-leases.md diff --git a/.codex/skills/truthmark-structure/agents/openai.yaml b/.codex/skills/truthmark-structure/agents/openai.yaml new file mode 100644 index 0000000..ec6a11b --- /dev/null +++ b/.codex/skills/truthmark-structure/agents/openai.yaml @@ -0,0 +1,11 @@ +interface: + display_name: "Truthmark Structure" + short_description: "Design, repair, or set up Truthmark area routing" + default_prompt: "Use $truthmark-structure to design, repair, or set up Truthmark area routing." + +policy: + allow_implicit_invocation: false + +truthmark: + version: "1.6.0" + refresh_command: "truthmark init" diff --git a/.codex/skills/truthmark-structure/support/procedure.md b/.codex/skills/truthmark-structure/support/procedure.md new file mode 100644 index 0000000..9104b33 --- /dev/null +++ b/.codex/skills/truthmark-structure/support/procedure.md @@ -0,0 +1,109 @@ +# Truthmark Structure Procedure + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Use this skill to design or repair Truthmark area structure. +Invocations: OpenCode /skill truthmark-structure; Codex /truthmark-structure or $truthmark-structure; Claude Code /truthmark-structure; GitHub Copilot /truthmark-structure; Gemini CLI /truthmark:structure. +Truth Structure is agent-native: +- inspect repository layout, current docs, Truthmark config and route files when present, and relevant code directly +- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. +Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. +- inspect the configured root route index at docs/truthmark/areas.md and relevant child route files under docs/truthmark/areas/ when they exist +- define areas by product or behavior ownership, not by mechanical directory mirroring +- create or repair docs/truthmark/areas.md +- create starter truth docs when useful and when they belong in the canonical current-truth surface +- Starter truth docs must use closed YAML frontmatter bounded by opening and closing --- lines; include status, doc_type, last_reviewed, and source_of_truth inside that frontmatter. +- Starter truth docs must include ## Product Decisions and ## Rationale sections. + +When creating or updating a truth doc, inspect the routed truth kind and use the matching `docs/templates/-doc.md` template. +Supported kinds: behavior, contract, architecture, workflow, operations, and test-behavior. +Align existing docs to that template while preserving accurate authored content. +If the template is missing, use Scope, Product Decisions, Rationale, and the kind-specific current-truth section. +Teams may edit the template files under docs/templates/ to define their local truth-doc standards. +- use docs/truth/**, docs/architecture/**, or docs/standards/** for current truth destinations +- use only canonical current-truth destinations for starter truth docs +- keep active Product Decisions and Rationale in the canonical doc that owns the behavior +- preserve unrelated authored content +## New area setup +Use when a user asks to onboard a new code area into Truthmark, a new package, controller, domain, or product area lacks bounded truth ownership, or a new product area needs routing and starter truth docs. +Do: +- inspect the named code area +- infer bounded product or behavior ownership +- choose the owning route when ownership is clear; otherwise propose the route and block for review +- create or update the child route entry or file +- create starter truth docs only where current truth is missing +- report the initial truth boundary +Do not: +- do not edit functional code +- do not perform full behavior documentation unless evidence is inspected and the task explicitly asks for it +- do not patch broad or mixed-owner docs in place +- do not create generic catch-all docs +- do not treat README files as Sync targets +## Topology Governance +Truth Structure owns documentation topology. Do not depend on humans to manually organize docs/truth. Treat the configured truth root as a managed semantic root. +Inspect controllers, routes, handlers, services, packages, tests, existing truth docs, and route files; infer product and domain ownership from behavior boundaries, not from mechanical directory mirroring. +When topology pressure exists, repair structure before creating or extending truth docs. +Truth-doc ownership gate: +- before editing or relying on candidate route owners and current truth docs, verify each target/source truth doc is a bounded owner for the behavior +- if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it +- if a truth doc mixes independent owners, route ownership is broad, or a split is required for bounded ownership, split and reroute into bounded truth docs when safe; otherwise block with manual-review files +- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Blocked reason as applicable +Product Decisions/Rationale preservation gate: +- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions and Rationale sections in every source or touched truth doc +- preserve each current decision and rationale in the bounded owner doc it governs; when splitting, move it to the new owner doc rather than deleting it or leaving it in an index +- remove or narrow a decision or rationale only when checkout evidence shows it is stale or unsupported, and report the exact claim, evidence, and result +- if ownership of a decision or rationale is unclear, block with manual-review files instead of deleting it or guessing +- after the edit, verify every touched truth doc still has Product Decisions and Rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked +Topology pressure signals: +- one area maps broad code such as src/**, app/**, server/**, services/**, or packages/** +- one area maps multiple unrelated controllers, route groups, services, or bounded contexts +- one truth doc owns unrelated behaviors or unrelated endpoint families +- the configured truth root has many direct non-index docs +- a changed controller, route, or service cannot map to a specific behavior doc +- Truth Sync would need to create a new generic truth doc because routing is too broad +- endpoint or controller names reveal domains missing from docs/truthmark/areas/** +Use these review thresholds as guidance: +- more than 10 direct truth docs in one folder +- more than 15 leaf areas in one child route file +- more than 8 truth docs mapped to one area +- more than 5 controllers mapped through one catch-all area +Repair rules: +- split broad, overloaded, or catch-all areas into behavior-owned child route files +- split mixed-owner truth docs into bounded owner docs before adding new behavior claims +- create route files under docs/truthmark/areas/ when a product/domain boundary is clear +- create behavior truth docs under the configured truth root only when behavior lacks a current doc +- README.md files are indexes, not Truth Sync targets +- prefer bounded leaf truth docs at //.md +- keep behavior truth docs behavior-oriented, not endpoint-oriented +- keep API endpoint details in the nearest contract truth doc when such a doc exists +- update routing so future Truth Sync can target small docs +- preserve existing authored docs; move or rewrite only when needed to remove ambiguity +- report Truth docs split when one broad or mixed-owner truth doc becomes multiple bounded docs +Truth-doc shape repair gate: +- Truth Structure may restructure broader routed docs when topology, ownership, or doc-shape repair is already in scope. +- repair shape in place only after the ownership gate confirms the doc is the right bounded owner +- use Truth Structure for ownership splits; do not treat broad or mixed-owner docs as in-place repair work +- repair shape when a narrow edit would make truth worse: missing template sections, stale evidence conflicts, cross-section updates within one owner, or wrong frontmatter/source/headings +- preserve supported claims; remove, narrow, or block unsupported or stale claims +- report docs restructured and why a narrow edit was not sufficient +Evidence Gate: +- apply the Evidence Gate before finishing when Truth Structure writes routed docs, ownership claims, Product Decisions, or Rationale +- support ownership/behavior claims with topology or primary checkout evidence from layout, implementation boundaries, docs, config, route files, tests, templates, schemas, or contracts +- tests/examples/canonical docs corroborate; remove, narrow, or block unsupported claims +Maintain architecture docs only for structure-level changes: system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership. +Keep ordinary behavior, endpoints, UI copy, validation rules, and bug fixes in behavior or contract docs unless they change those boundaries. +- Do not finish topology repair with routed canonical current-truth docs missing Product Decisions or Rationale sections. +- If an existing canonical doc lacks either section, add the missing heading beside Current Behavior with a concise current-state placeholder or active decision. +Portable fallback: +- If this skill surface is unavailable, perform the same workflow directly from committed repository files. +- Do not require the truthmark CLI. +- Inspect .truthmark/config.yml and configured route files only when they exist; then inspect canonical docs and representative implementation code. +- Use a subagent only when the host supports that pattern; otherwise perform the topology repair inline. +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md +Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. +Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. +Update Product Decisions and Rationale when a decision changes behavior. diff --git a/.codex/skills/truthmark-structure/support/report-template.md b/.codex/skills/truthmark-structure/support/report-template.md new file mode 100644 index 0000000..c104da3 --- /dev/null +++ b/.codex/skills/truthmark-structure/support/report-template.md @@ -0,0 +1,35 @@ +# Truthmark Structure Report Template + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Report completion in this shape: +```md +Truth Structure: completed +Topology reviewed: +- controllers: src/auth/** +- docs root: docs/truth +- route files: docs/truthmark/areas.md +Areas reviewed: +- src/auth/** +Routing updated: +- docs/truthmark/areas.md +Initial truth boundary: +- Area: Authentication +- Code: src/auth/** +- Truth owner: docs/truth/authentication/session.md +- Scope: session behavior only +Truth docs created: +- docs/truth/authentication/session.md +Truth docs split: +- docs/truth/authentication/README.md -> docs/truth/authentication/session.md +Truth docs restructured: +- docs/truth/authentication/README.md +Evidence checked: +- Claim: Session behavior belongs to a dedicated Authentication truth owner. + Evidence: src/auth/** / docs/truthmark/areas.md:7 + Result: supported +Topology decisions: +- Added an Authentication area because session behavior has a distinct code surface and truth owner. +Notes: +- Added an Authentication area for session behavior. +``` diff --git a/.codex/skills/truthmark-structure/support/subagents-and-leases.md b/.codex/skills/truthmark-structure/support/subagents-and-leases.md new file mode 100644 index 0000000..11d2d5e --- /dev/null +++ b/.codex/skills/truthmark-structure/support/subagents-and-leases.md @@ -0,0 +1,10 @@ +# Truthmark Structure Subagents And Leases + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Codex subagent mode: +- use automatically when this workflow runs in Codex and the parent agent chooses bounded subagent fan-out +- 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 all Truth Structure writes and final topology decisions diff --git a/.codex/skills/truthmark-sync/SKILL.md b/.codex/skills/truthmark-sync/SKILL.md new file mode 100644 index 0000000..651ffc3 --- /dev/null +++ b/.codex/skills/truthmark-sync/SKILL.md @@ -0,0 +1,31 @@ +--- +name: truthmark-sync +description: Use automatically at finish-time after functional code changes, or explicit /truthmark-sync, $truthmark-sync, or /truthmark:sync. Skip docs-only, formatting-only, behavior-preserving renames, missing config, and no-code changes. Not for doc-first realization or manual topology design. +argument-hint: Optional changed-code area, truth-doc area, or sync focus +user-invocable: true +truthmark-version: 1.6.0 +--- + +# Truthmark Sync + +Use this skill automatically before finishing when functional code changed since the last successful Truth Sync. Also run it immediately when the user explicitly invokes Truth Sync. + + +Invocations: OpenCode /skill truthmark-sync; Codex /truthmark-sync or $truthmark-sync; Claude Code /truthmark-sync; GitHub Copilot /truthmark-sync; Gemini CLI /truthmark:sync. + +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/areas.md; docs/truthmark/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 before dispatching or accepting worker output. +- Read support/report-template.md before the final report. + +Progressive disclosure: +- support/procedure.md +- support/report-template.md +- support/subagents-and-leases.md +- helper-manifest.yml +- support/helper-policy.md diff --git a/.codex/skills/truthmark-sync/agents/openai.yaml b/.codex/skills/truthmark-sync/agents/openai.yaml new file mode 100644 index 0000000..9e9e93c --- /dev/null +++ b/.codex/skills/truthmark-sync/agents/openai.yaml @@ -0,0 +1,11 @@ +interface: + display_name: "Truthmark Sync" + short_description: "Sync truth docs from functional code changes; skip docs-only/no-code changes" + default_prompt: "Use $truthmark-sync after functional code changes; skip docs-only/no-code changes." + +policy: + allow_implicit_invocation: true + +truthmark: + version: "1.6.0" + refresh_command: "truthmark init" diff --git a/.codex/skills/truthmark-sync/helper-manifest.yml b/.codex/skills/truthmark-sync/helper-manifest.yml new file mode 100644 index 0000000..ce58751 --- /dev/null +++ b/.codex/skills/truthmark-sync/helper-manifest.yml @@ -0,0 +1,34 @@ +# Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. +helpers: + validate-sync-report: + optional: true + runner: truthmark>=1.6.0 + 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>=1.6.0 + 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/.codex/skills/truthmark-sync/support/helper-policy.md b/.codex/skills/truthmark-sync/support/helper-policy.md new file mode 100644 index 0000000..c3d00c7 --- /dev/null +++ b/.codex/skills/truthmark-sync/support/helper-policy.md @@ -0,0 +1,23 @@ +# Optional Helper CLI Policy + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Optional helper CLI commands may collect deterministic checkout facts or validate artifacts. If the Truthmark CLI is unavailable or too old for a declared helper, continue manually using this procedure and report which helper was skipped. Helper output is derived evidence; it does not override direct checkout inspection, workflow write boundaries, or parent acceptance. + +Runner detection: +- Check the declared Truthmark CLI runner before invoking a helper. +- Invoke helpers through the installed `truthmark validate ... --json` CLI command using argv-style arguments from helper-manifest.yml. +- If unavailable or version-mismatched, 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>=1.6.0; manual fallback: manually validate support/report-template.md and check Evidence checked entries match Claim, indented Evidence, and Result: supported | narrowed | removed | blocked +- validate-write-lease: optional truthmark>=1.6.0; 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/.codex/skills/truthmark-sync/support/procedure.md b/.codex/skills/truthmark-sync/support/procedure.md new file mode 100644 index 0000000..a80e050 --- /dev/null +++ b/.codex/skills/truthmark-sync/support/procedure.md @@ -0,0 +1,88 @@ +# Truthmark Sync Procedure + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Use this skill automatically before finishing when functional code changed since the last successful Truth Sync. Also run it immediately when the user explicitly invokes Truth Sync. +Invocations: OpenCode /skill truthmark-sync; Codex /truthmark-sync or $truthmark-sync; Claude Code /truthmark-sync; GitHub Copilot /truthmark-sync; Gemini CLI /truthmark:sync. +Explicit invocation runs immediately. Later functional-code changes reopen the finish-time requirement, and an earlier explicit run satisfies the finish gate only if no later functional-code changes occur. +Skip when changes are documentation-only, formatting-only, clearly behavior-preserving renames with no truth impact, when no Truthmark config exists yet, or when there are no functional code changes. +Parent workflow: +1. Inspect git status, staged changes, unstaged changes, and untracked files directly. +2. Inspect .truthmark/config.yml and configured route files only when they exist; then inspect relevant canonical docs. +3. Identify functional-code changes and the nearest truth docs or routing repairs. +4. Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. +Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. +5. Code verification is parent-owned: follow repository instructions and task context, and report what ran or why it did not run. +6. Dispatch bounded Truth Sync workers only when the host supports subagent dispatch and the acting agent chooses that path; otherwise execute the same sync task inline. +Topology quality gate: +- before updating truth docs, verify the changed code resolves to a specific behavior-owned area and bounded truth owner +- if routing is missing, stale, broad, overloaded, catch-all route only, or cannot map changed code to a bounded truth owner, do not create another generic truth doc +- run Truth Structure before syncing when topology repair is safe and in scope +- block and recommend Truth Structure when topology repair is unsafe, ambiguous, or outside the current task boundary +- report the route files and changed code paths that require structure repair +- README.md files are indexes, not Truth Sync targets +- must not append behavior details to a README.md index +- create or update a bounded leaf truth doc when behavior changes do not fit an existing leaf doc +Truth-doc ownership gate: +- before editing or relying on changed functional files and impacted truth docs, verify each target/source truth doc is a bounded owner for the behavior +- if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it +- if an impacted doc is broad, mixed-owner, index-like, or the update spans independent behavior owners, run Truth Structure before syncing when safe and in scope; otherwise block and recommend Truth Structure +- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Blocked reason as applicable +Product Decisions/Rationale preservation gate: +- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions and Rationale sections in every source or touched truth doc +- preserve each current decision and rationale in the bounded owner doc it governs; when splitting, move it to the new owner doc rather than deleting it or leaving it in an index +- remove or narrow a decision or rationale only when checkout evidence shows it is stale or unsupported, and report the exact claim, evidence, and result +- if ownership of a decision or rationale is unclear, block with manual-review files instead of deleting it or guessing +- after the edit, verify every touched truth doc still has Product Decisions and Rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked +When creating or updating a truth doc, inspect the routed truth kind and use the matching `docs/templates/-doc.md` template. +Supported kinds: behavior, contract, architecture, workflow, operations, and test-behavior. +Align existing docs to that template while preserving accurate authored content. +If the template is missing, use Scope, Product Decisions, Rationale, and the kind-specific current-truth section. +Teams may edit the template files under docs/templates/ to define their local truth-doc standards. +Truth-doc shape repair gate: +- Truth Sync may restructure only truth docs impacted by the current functional-code change. +- repair shape in place only after the ownership gate confirms the doc is the right bounded owner +- use Truth Structure for ownership splits; do not treat broad or mixed-owner docs as in-place repair work +- repair shape when a narrow edit would make truth worse: missing template sections, stale evidence conflicts, cross-section updates within one owner, or wrong frontmatter/source/headings +- preserve supported claims; remove, narrow, or block unsupported or stale claims +- report docs restructured and why a narrow edit was not sufficient +Maintain architecture docs only for structure-level changes: system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership. +Keep ordinary behavior, endpoints, UI copy, validation rules, and bug fixes in behavior or contract docs unless they change those boundaries. +Evidence Gate: +- route-first: map changed functional files to bounded route owners and primary canonical docs +- review new or changed behavior-bearing claims only in touched docs, route ownership, Product Decisions, and Rationale +- support claims with primary checkout evidence: implementation, config, routing, generated templates, schemas, or contract definitions +- tests/examples/canonical docs corroborate; they are not sole proof when implementation conflicts +- remove, narrow, or block unsupported claims +- if no impacted doc changed, report why truth was already current or why sync was skipped +Repository intelligence artifacts are optional derived context: RepoIndex, RouteMap, ImpactSet, and ContextPack may guide routing, context selection, and verification planning when available. +They do not override checkout evidence, canonical truth docs, route files, or workflow write boundaries. +If unavailable, inspect any present Truthmark config, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated. +Optional validation tooling: +- you may run truthmark check when local tooling is available +- do not require the truthmark binary; direct checkout inspection is the canonical path +- optional validation must not replace agent judgment about docs and routing +- update Product Decisions and Rationale when a behavior change comes from a decision change +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/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md +Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. +Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. +Update Product Decisions and Rationale when a decision changes behavior. +Parent post-sync verification: +- verify only truth docs and leased truth routing files changed during sync +- block on any unrelated diff caused by the sync step +- block if functional code changed during sync +- for each write lease, validate the worker report against the actual worker diff, allowedWrites, forbiddenWrites, identity fields, filesChanged, offLeaseChanges, blockers, and required report fields before accepting it +- validate the final report against the structured Truth Sync report contract, including Claim, indented Evidence, and Result values supported, narrowed, removed, or blocked under Evidence checked +- verify the updated docs correspond to the reviewed changed-code surface +- verify the final report records ownership review, structure requirement, split, restructure, or blocked reason when the ownership gate fired +- blocked outcomes must preserve the working tree as-is: no rollback, no post-block cleanup edits, and manual-review reporting of any remaining files diff --git a/.codex/skills/truthmark-sync/support/report-template.md b/.codex/skills/truthmark-sync/support/report-template.md new file mode 100644 index 0000000..9bce186 --- /dev/null +++ b/.codex/skills/truthmark-sync/support/report-template.md @@ -0,0 +1,41 @@ +# Truthmark Sync Report Template + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Report completion in this shape: +```md +Truth Sync: completed + +Changed code reviewed: +- src/auth/session.ts + +Ownership reviewed: +- docs/truthmark/areas.md + +Truth docs updated: +- docs/truth/repository/overview.md + +Evidence checked: +- Claim: Session timeout behavior is documented in the mapped repository truth doc. + Evidence: src/auth/session.ts:12 / docs/truthmark/areas.md:11 + Result: supported + +Helper scripts: +- validate-write-lease: skipped, no write lease used + +Notes: +- Updated session timeout behavior. +``` +Blocked report example: +```md +Truth Sync: blocked + +Reason: +- routing repair is not allowed + +Files requiring manual review: +- docs/truthmark/areas.md + +Next action: +- update routing metadata and rerun Truth Sync +``` diff --git a/.codex/skills/truthmark-sync/support/subagents-and-leases.md b/.codex/skills/truthmark-sync/support/subagents-and-leases.md new file mode 100644 index 0000000..5730250 --- /dev/null +++ b/.codex/skills/truthmark-sync/support/subagents-and-leases.md @@ -0,0 +1,14 @@ +# Truthmark Sync Subagents And Leases + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Codex subagent mode: +- use automatically when this workflow runs in Codex and the parent agent chooses bounded subagent fan-out +- dispatch read-only project agents for verification: truth_route_auditor, truth_claim_verifier +- read-only workers inspect checkout evidence directly, return structured findings, and must not edit files +- parent supplies bounded evidence shards; read-only workers must not preload host instruction files or repo-wide policy docs unless assigned as evidence +- dispatch write-capable project agents only with explicit write leases: truth_doc_writer +- each write lease must name objective, required reads, allowed writes, forbidden writes, evidence, verification, and report fields +- write workers must stop when a required edit is off-lease and report status, filesChanged, evidence, offLeaseChanges, blockers, and notes +- parent must inspect the actual checkout diff against each lease before accepting a worker report +- Parent agent owns Truth Sync acceptance, lease validation, and final report diff --git a/.github/agents/truth-claim-verifier.agent.md b/.github/agents/truth-claim-verifier.agent.md new file mode 100644 index 0000000..0b026ff --- /dev/null +++ b/.github/agents/truth-claim-verifier.agent.md @@ -0,0 +1,19 @@ +--- +name: truth-claim-verifier +description: Read-only Truthmark claim verifier for checking canonical truth against checkout evidence. +tools: [read, search] +--- + +# Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Stay read-only. +Verify the behavior-bearing truth claims assigned by the parent against primary checkout evidence. +Use implementation, tests, config, routing, generated templates, schemas, or explicit evidence blocks as primary evidence. +Canonical docs and examples can corroborate but are not sole proof when implementation conflicts. +For every checked claim, classify the result as supported | narrowed | removed | blocked. +Do not edit files, stage changes, or invent missing behavior. +Return JSON only with keys: scope, filesReviewed, claimsChecked, evidence, unsupportedClaims, confidence, recommendedWorkflow, notes. +Context boundary: +Do not preload AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, or repo-wide policy docs unless the parent explicitly assigns them as evidence. +Use only the parent-assigned shard plus required checkout evidence files. +Return findings only; the parent workflow owns repository-policy interpretation, final decisions, and all writes. diff --git a/.github/agents/truth-doc-reviewer.agent.md b/.github/agents/truth-doc-reviewer.agent.md new file mode 100644 index 0000000..97e5c9e --- /dev/null +++ b/.github/agents/truth-doc-reviewer.agent.md @@ -0,0 +1,18 @@ +--- +name: truth-doc-reviewer +description: Read-only Truthmark doc reviewer for shape, decision, rationale, and evidence hygiene. +tools: [read, search] +--- + +# Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Stay read-only. +Review assigned canonical truth docs for frontmatter, source_of_truth, required template sections, Evidence checked entries, Product Decisions, and Rationale. +Flag README.md files used as behavior truth targets, mixed-owner docs, and shape repairs that should move to Truth Structure. +Do not edit files, stage changes, or rewrite docs. +Return JSON only with keys: scope, filesReviewed, findings, evidence, confidence, recommendedWorkflow, notes. +recommendedWorkflow must be one of: none, truthmark-document, truthmark-structure. +Context boundary: +Do not preload AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, or repo-wide policy docs unless the parent explicitly assigns them as evidence. +Use only the parent-assigned shard plus required checkout evidence files. +Return findings only; the parent workflow owns repository-policy interpretation, final decisions, and all writes. diff --git a/.github/agents/truth-doc-writer.agent.md b/.github/agents/truth-doc-writer.agent.md new file mode 100644 index 0000000..29352a9 --- /dev/null +++ b/.github/agents/truth-doc-writer.agent.md @@ -0,0 +1,19 @@ +--- +name: truth-doc-writer +description: Write-capable Truthmark doc worker for one parent-leased truth-document shard. +tools: [read, search, edit] +--- + +# Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Write one leased Truthmark truth-document shard assigned by the parent. +Require an explicit write lease before editing. The lease must name workflow, worker, shard, objective, requiredReads, allowedWrites, forbiddenWrites, evidenceRequired, verification, and reportFields. +Read every requiredReads entry directly before editing. +Edit only leased canonical truth docs or leased truth routing files. Do not edit functional code, generated host surfaces, package files, config files, templates, or tests unless they are explicitly leased. +Do not expand your own write scope. If the task needs an off-lease file, stop and report blocked. +Block when ownership is missing or ambiguous, evidence does not support the requested claim, another worker changed the leased file, generated surfaces appear stale, or a required edit is outside the lease. +Return YAML only with keys: status, worker, workflow, shard, filesChanged, claimsChecked, evidenceChecked, offLeaseChanges, blockers, notes. +status must be completed or blocked. +filesChanged must list only files you actually changed. +offLeaseChanges must be empty for completed reports. +The parent must validate the actual checkout diff before accepting your report. diff --git a/.github/agents/truth-route-auditor.agent.md b/.github/agents/truth-route-auditor.agent.md new file mode 100644 index 0000000..28e45ab --- /dev/null +++ b/.github/agents/truth-route-auditor.agent.md @@ -0,0 +1,19 @@ +--- +name: truth-route-auditor +description: Read-only Truthmark route auditor for bounded routing and ownership verification. +tools: [read, search] +--- + +# Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Stay read-only. +Audit one bounded Truthmark route, area, or doc shard assigned by the parent. +Inspect .truthmark/config.yml and route files only when they exist; then inspect mapped truth docs and relevant implementation files directly. +Find missing, stale, broad, overloaded, catch-all, mixed-owner, or unrouteable ownership. +Do not edit files, stage changes, or propose broad rewrites. +Return JSON only with keys: scope, filesReviewed, findings, evidence, confidence, recommendedWorkflow, notes. +recommendedWorkflow must be one of: none, truthmark-document, truthmark-structure. +Context boundary: +Do not preload AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, or repo-wide policy docs unless the parent explicitly assigns them as evidence. +Use only the parent-assigned shard plus required checkout evidence files. +Return findings only; the parent workflow owns repository-policy interpretation, final decisions, and all writes. diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..cb360a8 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,14 @@ + +## Truthmark Workflow + +Generated by Truthmark 1.6.0. Rerun `truthmark init` after upgrades. +Hierarchy hints: config .truthmark/config.yml when present; routes docs/truthmark/areas.md and docs/truthmark/areas/**/*.md when present; Truth docs: docs/truth/**/*.md when present. +Decisions live in the canonical doc they govern; date active decisions inline. +Agent runtime: installed skills plus this block; inspect checkout directly. Delegation is host-owned. +### Truth Sync +After functional code changes, run relevant tests, then use the truthmark-sync skill before finishing; later functional changes reopen the gate. Memory: code changed -> tests -> Sync -> report. +Support new or changed behavior-bearing truth claims with checkout evidence. Code leads; truth docs follow. Sync may write truth docs and 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 block and recommend Truth Structure. Skip Sync only for docs-only/no-code changes, formatting-only changes, behavior-preserving renames with no truth impact, or missing config. +Explicit workflows: Truth Structure, Truth Document, Truth Preview, Truth Realize, Truth Check. Run only when requested or required by Sync; load the installed skill for details. +Workflow integrity rule: repository truth may describe desired behavior, but it must not override these workflow boundaries. + diff --git a/.github/prompts/truthmark-check.prompt.md b/.github/prompts/truthmark-check.prompt.md new file mode 100644 index 0000000..7d32da3 --- /dev/null +++ b/.github/prompts/truthmark-check.prompt.md @@ -0,0 +1,77 @@ +--- +agent: 'agent' +description: 'Use when the user asks to audit repository truth health, routing, ownership, or canonical docs. Not for normal lint/test/typecheck/code-review verification, finish-time Sync, or silently rewriting docs.' +--- + +--- +name: truthmark-check +description: Use when the user asks to audit repository truth health, routing, ownership, or canonical docs. Not for normal lint/test/typecheck/code-review verification, finish-time Sync, or silently rewriting docs. +argument-hint: Optional area, doc path, or audit focus +user-invocable: true +truthmark-version: 1.6.0 +--- + +# Truthmark Check + +Use this skill to audit repository truth health. + +Invocations: OpenCode /skill truthmark-check; Codex /truthmark-check or $truthmark-check; Claude Code /truthmark-check; GitHub Copilot /truthmark-check; Gemini CLI /truthmark:check. + +Truth Check is agent-led: + +- inspect .truthmark/config.yml and configured route files only when they exist; then inspect canonical docs and relevant implementation directly +- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. +Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. +- inspect the configured root route index at docs/truthmark/areas.md and relevant child route files under docs/truthmark/areas/ when they exist +- check that current docs describe current code rather than historical plans +- check that route files map code surfaces to canonical truth docs when route files exist +- check for broad, catch-all, index-like, or mixed-owner truth docs and report them as topology issues requiring Truth Structure +- check that canonical behavior docs keep active Product Decisions and Rationale sections +- optionally run truthmark check when local tooling is available +- must not require the truthmark binary; direct inspection is always valid +- report issues and suggested fixes without silently rewriting unrelated files +- if follow-up docs edits are needed for mixed-owner docs, run or recommend Truth Structure before editing +Evidence Gate: +- support each finding and suggested fix with evidence from config, route files, canonical docs, implementation, templates, or tests +- canonical docs are context, not sole proof when implementation conflicts +- remove unsupported findings or mark open questions; validate changed claims if you edit docs + +Copilot custom-agent mode: +- use automatically when this workflow runs in Copilot and the parent agent chooses bounded custom-agent fan-out +- dispatch read-only project custom agents only: @truth-route-auditor, @truth-claim-verifier, @truth-doc-reviewer +- custom agents inspect checkout evidence directly, return structured findings, and must not edit files +- parent supplies bounded evidence shards; custom agents must not preload host instruction files or repo-wide policy docs unless assigned as evidence +- Parent agent owns the final Truth Check report + +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md +Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. +Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. +Update Product Decisions and Rationale when a decision changes behavior. + +Report completion in this shape: + +```md +Truth Check: completed + +Files reviewed: +- docs/truthmark/areas.md + +Issues found: +- none + +Fixes suggested: +- none + +Evidence checked: +- Finding: The root route index is present and maps repository truth owners. + Evidence: docs/truthmark/areas.md:1 + Suggested fix: none + Confidence: high + +Validation: +- truthmark check +``` diff --git a/.github/prompts/truthmark-document.prompt.md b/.github/prompts/truthmark-document.prompt.md new file mode 100644 index 0000000..d2946cd --- /dev/null +++ b/.github/prompts/truthmark-document.prompt.md @@ -0,0 +1,132 @@ +--- +agent: 'agent' +description: 'Use when the user asks to document existing implemented behavior, or Sync, Check, or Structure finds implemented behavior missing canonical truth. Not for functional-code changes, doc-first implementation, or topology repair that needs Structure.' +--- + +--- +name: truthmark-document +description: Use when the user asks to document existing implemented behavior, or Sync, Check, or Structure finds implemented behavior missing canonical truth. Not for functional-code changes, doc-first implementation, or topology repair that needs Structure. +argument-hint: Optional implemented behavior, API endpoint, route, controller, package, or truth-doc area to document +user-invocable: true +truthmark-version: 1.6.0 +--- + +# Truthmark Document + +Use this skill to document existing implemented behavior when no functional-code changes are required for the task. +Invocations: OpenCode /skill truthmark-document; Codex /truthmark-document or $truthmark-document; Claude Code /truthmark-document; GitHub Copilot /truthmark-document; Gemini CLI /truthmark:document. + +Truth Document is manual and implementation-first: + +- run only when the user explicitly asks to generate or update truth docs for existing behavior, or when Truth Sync, Truth Check, or Truth Structure reports implemented behavior that lacks canonical truth docs +- inspect .truthmark/config.yml and configured route files only when they exist; then inspect existing canonical docs, implementation code, and tests directly +- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. +Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. +- document current implemented behavior; do not invent future behavior or planned endpoints +- may write canonical truth docs and docs/truthmark/areas.md or relevant child route files only +- must not write functional code +- when routing is missing, stale, broad, overloaded, catch-all, or cannot map the behavior to a bounded truth owner, run Truth Structure first when routing repair is safe and in scope +- block and recommend Truth Structure when routing repair is unsafe, ambiguous, or outside the task boundary +- keep feature README.md files as indexes rather than truth-document targets +- create or update bounded leaf truth docs when behavior does not fit an existing leaf doc +- keep behavior truth docs behavior-oriented, not endpoint-oriented, unless the endpoint itself is the behavior boundary +- keep API endpoint details in the nearest contract truth doc when such a doc owns the API contract +- preserve unrelated authored content +Truth-doc ownership gate: +- before editing or relying on the implemented behavior and candidate truth docs, verify each target/source truth doc is a bounded owner for the behavior +- if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it +- if the target doc is broad, mixed-owner, index-like, or the documented behavior spans independent owners, run Truth Structure first when safe and in scope; otherwise block and recommend Truth Structure +- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Blocked reason as applicable +Product Decisions/Rationale preservation gate: +- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions and Rationale sections in every source or touched truth doc +- preserve each current decision and rationale in the bounded owner doc it governs; when splitting, move it to the new owner doc rather than deleting it or leaving it in an index +- remove or narrow a decision or rationale only when checkout evidence shows it is stale or unsupported, and report the exact claim, evidence, and result +- if ownership of a decision or rationale is unclear, block with manual-review files instead of deleting it or guessing +- after the edit, verify every touched truth doc still has Product Decisions and Rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked +Evidence Gate: +- route-first: map the documented behavior to bounded route owners and primary canonical docs +- review new or changed behavior-bearing claims only in touched docs, route ownership, Product Decisions, and Rationale +- support claims with primary checkout evidence: implementation, config, routing, generated templates, schemas, or contract definitions +- tests/examples/canonical docs corroborate; they are not sole proof when implementation conflicts +- remove, narrow, or block unsupported claims +- if no truth doc changed, report why current truth was already sufficient or why documentation was blocked +Copilot custom-agent mode: +- use automatically when this workflow runs in Copilot and the parent agent chooses bounded custom-agent fan-out +- dispatch read-only project custom agents for verification: @truth-route-auditor, @truth-claim-verifier +- read-only custom agents inspect checkout evidence directly, return structured findings, and must not edit files +- parent supplies bounded evidence shards; read-only custom agents must not preload host instruction files or repo-wide policy docs unless assigned as evidence +- dispatch write-capable project custom agents only with explicit write leases: @truth-doc-writer +- each write lease must name objective, required reads, allowed writes, forbidden writes, evidence, verification, and report fields +- write workers must stop when a required edit is off-lease and report status, filesChanged, evidence, offLeaseChanges, blockers, and notes +- parent must inspect the actual checkout diff against each lease before accepting a worker report +- Parent agent owns Truth Document acceptance, lease validation, and final report +Repository intelligence artifacts are optional derived context: RepoIndex, RouteMap, ImpactSet, and ContextPack may guide routing, context selection, and verification planning when available. +They do not override checkout evidence, canonical truth docs, route files, or workflow write boundaries. +If unavailable, inspect any present Truthmark config, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated. +When creating or updating a truth doc, inspect the routed truth kind and use the matching `docs/templates/-doc.md` template. +Supported kinds: behavior, contract, architecture, workflow, operations, and test-behavior. +Align existing docs to that template while preserving accurate authored content. +If the template is missing, use Scope, Product Decisions, Rationale, and the kind-specific current-truth section. +Teams may edit the template files under docs/templates/ to define their local truth-doc standards. +Truth-doc shape repair gate: +- Truth Document may restructure only truth docs for the implemented behavior being documented. +- repair shape in place only after the ownership gate confirms the doc is the right bounded owner +- use Truth Structure for ownership splits; do not treat broad or mixed-owner docs as in-place repair work +- repair shape when a narrow edit would make truth worse: missing template sections, stale evidence conflicts, cross-section updates within one owner, or wrong frontmatter/source/headings +- preserve supported claims; remove, narrow, or block unsupported or stale claims +- report docs restructured and why a narrow edit was not sufficient +Maintain architecture docs only for structure-level changes: system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership. +Keep ordinary behavior, endpoints, UI copy, validation rules, and bug fixes in behavior or contract docs unless they change those boundaries. +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md +Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. +Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. +Update Product Decisions and Rationale when a decision changes behavior. +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 +- block on functional code, generated host surfaces, or unrelated diffs caused by document work +- for each write lease, validate the worker report against the actual worker diff, allowedWrites, forbiddenWrites, identity fields, filesChanged, offLeaseChanges, blockers, and required report fields before accepting it +- verify the final report records ownership review, structure requirement, restructure, routing update, or blocked reason when applicable + +Report completion in this shape: +```md +Truth Document: completed + +Implementation reviewed: +- src/routing/area-resolver.ts + +Ownership reviewed: +- docs/truthmark/areas.md + +Truth docs created: +- docs/truth/contracts.md + +Truth docs updated: +- docs/truth/check-diagnostics.md + +Truth docs restructured: +- docs/truth/check-diagnostics.md + +Routing updated: +- docs/truthmark/areas.md + +Evidence checked: +- Claim: Route resolution behavior is documented in the contracts truth doc. + Evidence: src/routing/area-resolver.ts:14 / docs/truthmark/areas.md:9 + Result: supported + +Helper scripts: +- validate-write-lease: skipped, no write lease used + +Notes: +- Documented routing and behavior from route handlers and tests. +``` diff --git a/.github/prompts/truthmark-preview.prompt.md b/.github/prompts/truthmark-preview.prompt.md new file mode 100644 index 0000000..55da8ca --- /dev/null +++ b/.github/prompts/truthmark-preview.prompt.md @@ -0,0 +1,90 @@ +--- +agent: 'agent' +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.' +--- + +--- +name: truthmark-preview +description: Use when the user explicitly asks to preview likely workflow routing, target files, writes, or subagent use before edits. Not for validation, automatic gates, final correctness, or replacing Truth Check. +argument-hint: Optional requested outcome, code area, doc path, or routing question +user-invocable: true +truthmark-version: 1.6.0 +--- + +Use this skill only when the user explicitly asks to preview Truthmark routing or workflow choice before edits. + +Invocations: OpenCode /skill truthmark-preview; Codex /truthmark-preview or $truthmark-preview; Claude Code /truthmark-preview; GitHub Copilot /truthmark-preview; Gemini CLI /truthmark:preview. + +Truth Preview is read-only. Its report is intended, not authorized. + +Purpose: +- preview the likely Truthmark workflow, route owner, target files, expected write classes, suggested subagent use, and blocking ambiguity before edits happen +- hand off to the selected workflow after user approval +- keep the selector thin so agents can avoid loading or acting through heavier workflows prematurely + +Read: +- .truthmark/config.yml, only when present +- docs/truthmark/areas.md, only when present +- relevant child route files under docs/truthmark/areas/, only when present +- relevant truth docs and implementation files needed to preview ownership +- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. +Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. + +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/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md + +Report completion in this shape: +```md +Truth Preview: completed + +Requested outcome: +- preview likely Truthmark workflow routing before edits + +Likely workflow: +- truthmark-document + +Why this workflow: +- positive trigger: document existing implemented behavior +- negative triggers considered: functional-code change, doc-first implementation, topology repair, truth audit +- forbidden adjacency considered: must not edit functional code + +Likely route owner: +- route file: docs/truthmark/areas.md +- truth doc: docs/truth/example.md +- confidence: medium + +Expected write classes: +- truth docs + +Expected target files: +- docs/truth/example.md + +Suggested subagent use: +- read-only verifiers: truth_route_auditor +- write workers: none in Preview +- leases needed: none in Preview + +Blocking ambiguity: +- none identified in preview + +Handoff: +- Run the selected Truthmark workflow after user approval. +``` diff --git a/.github/prompts/truthmark-realize.prompt.md b/.github/prompts/truthmark-realize.prompt.md new file mode 100644 index 0000000..ae768d6 --- /dev/null +++ b/.github/prompts/truthmark-realize.prompt.md @@ -0,0 +1,67 @@ +--- +agent: 'agent' +description: 'Use when the user explicitly asks to realize Truthmark truth docs into code, including /truthmark-realize, $truthmark-realize, or /truthmark:realize. Not for syncing docs after code changes, documenting existing code, topology repair, or truth audits.' +--- + +--- +name: truthmark-realize +description: Use when the user explicitly asks to realize Truthmark truth docs into code, including /truthmark-realize, $truthmark-realize, or /truthmark:realize. Not for syncing docs after code changes, documenting existing code, topology repair, or truth audits. +argument-hint: Optional truth doc path, area, or desired code behavior to realize +user-invocable: true +truthmark-version: 1.6.0 +--- + +# Truthmark Realize + +Use this skill only when the user explicitly asks to realize truth docs into code. + +Invocations: OpenCode /skill truthmark-realize; Codex /truthmark-realize or $truthmark-realize; Claude Code /truthmark-realize; GitHub Copilot /truthmark-realize; Gemini CLI /truthmark:realize. + +Truth Realize is doc-first: + +- truth docs lead +- code follows +- Truth Realize never edits the truth docs it is realizing + +Workflow: + +1. Read the updated truth docs named by the user, or infer the relevant docs from configured route files when present. +2. Inspect .truthmark/config.yml and configured route files (docs/truthmark/areas.md; docs/truthmark/areas/) only when they exist; then read tests and the relevant functional code. +3. 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. +Truth-doc ownership gate: +- before editing or relying on source truth docs before writing code, verify each target/source truth doc is a bounded owner for the behavior +- if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it +- if a source truth doc is broad, mixed-owner, index-like, unrouteable, stale, or conflicts with implementation evidence, block before writing code and recommend Truth Structure or Truth Document +- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Blocked reason as applicable +4. Update functional code only so implementation matches bounded, current truth claims from the source docs. +5. Do not edit truth docs or truth routing while realizing those docs. +6. Run relevant tests for the changed code. +7. Report changed code files and verification steps. +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md + +Read and write boundaries: + +- may read truth docs, routing docs, and relevant functional code +- may write functional code only +- must not edit truth docs or truth routing while realizing those docs + +Report completion in this shape: + +```md +Truth Realize: completed + +Truth docs used: +- docs/truth/authentication/session-timeout.md + +Code updated: +- src/auth/session.ts + +Verification: +- npm test -- auth +``` + diff --git a/.github/prompts/truthmark-structure.prompt.md b/.github/prompts/truthmark-structure.prompt.md new file mode 100644 index 0000000..487eea8 --- /dev/null +++ b/.github/prompts/truthmark-structure.prompt.md @@ -0,0 +1,155 @@ +--- +agent: 'agent' +description: 'Use when routing or truth ownership is missing, stale, broad, overloaded, catch-all, unrouteable, mixed-owner, needs split/repair, or needs new area setup. Not for documenting implemented behavior, syncing a code diff, or realizing docs into code.' +--- + +--- +name: truthmark-structure +description: Use when routing or truth ownership is missing, stale, broad, overloaded, catch-all, unrouteable, mixed-owner, needs split/repair, or needs new area setup. Not for documenting implemented behavior, syncing a code diff, or realizing docs into code. +argument-hint: Optional area, directory, or routing concern +user-invocable: true +truthmark-version: 1.6.0 +--- + +Use this skill to design or repair Truthmark area structure. +Invocations: OpenCode /skill truthmark-structure; Codex /truthmark-structure or $truthmark-structure; Claude Code /truthmark-structure; GitHub Copilot /truthmark-structure; Gemini CLI /truthmark:structure. +Truth Structure is agent-native: +- inspect repository layout, current docs, Truthmark config and route files when present, and relevant code directly +- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. +Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. +- inspect the configured root route index at docs/truthmark/areas.md and relevant child route files under docs/truthmark/areas/ when they exist +- define areas by product or behavior ownership, not by mechanical directory mirroring +- create or repair docs/truthmark/areas.md +- create starter truth docs when useful and when they belong in the canonical current-truth surface +- Starter truth docs must use closed YAML frontmatter bounded by opening and closing --- lines; include status, doc_type, last_reviewed, and source_of_truth inside that frontmatter. +- Starter truth docs must include ## Product Decisions and ## Rationale sections. +Copilot custom-agent mode: +- use automatically when this workflow runs in Copilot and the parent agent chooses bounded custom-agent fan-out +- dispatch read-only project custom agents only: @truth-route-auditor +- custom agents inspect checkout evidence directly, return structured findings, and must not edit files +- parent supplies bounded evidence shards; custom agents must not preload host instruction files or repo-wide policy docs unless assigned as evidence +- Parent agent owns all Truth Structure writes and final topology decisions + +When creating or updating a truth doc, inspect the routed truth kind and use the matching `docs/templates/-doc.md` template. +Supported kinds: behavior, contract, architecture, workflow, operations, and test-behavior. +Align existing docs to that template while preserving accurate authored content. +If the template is missing, use Scope, Product Decisions, Rationale, and the kind-specific current-truth section. +Teams may edit the template files under docs/templates/ to define their local truth-doc standards. +- use docs/truth/**, docs/architecture/**, or docs/standards/** for current truth destinations +- use only canonical current-truth destinations for starter truth docs +- keep active Product Decisions and Rationale in the canonical doc that owns the behavior +- preserve unrelated authored content +## New area setup +Use when a user asks to onboard a new code area into Truthmark, a new package, controller, domain, or product area lacks bounded truth ownership, or a new product area needs routing and starter truth docs. +Do: +- inspect the named code area +- infer bounded product or behavior ownership +- choose the owning route when ownership is clear; otherwise propose the route and block for review +- create or update the child route entry or file +- create starter truth docs only where current truth is missing +- report the initial truth boundary +Do not: +- do not edit functional code +- do not perform full behavior documentation unless evidence is inspected and the task explicitly asks for it +- do not patch broad or mixed-owner docs in place +- do not create generic catch-all docs +- do not treat README files as Sync targets +## Topology Governance +Truth Structure owns documentation topology. Do not depend on humans to manually organize docs/truth. Treat the configured truth root as a managed semantic root. +Inspect controllers, routes, handlers, services, packages, tests, existing truth docs, and route files; infer product and domain ownership from behavior boundaries, not from mechanical directory mirroring. +When topology pressure exists, repair structure before creating or extending truth docs. +Truth-doc ownership gate: +- before editing or relying on candidate route owners and current truth docs, verify each target/source truth doc is a bounded owner for the behavior +- if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it +- if a truth doc mixes independent owners, route ownership is broad, or a split is required for bounded ownership, split and reroute into bounded truth docs when safe; otherwise block with manual-review files +- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Blocked reason as applicable +Product Decisions/Rationale preservation gate: +- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions and Rationale sections in every source or touched truth doc +- preserve each current decision and rationale in the bounded owner doc it governs; when splitting, move it to the new owner doc rather than deleting it or leaving it in an index +- remove or narrow a decision or rationale only when checkout evidence shows it is stale or unsupported, and report the exact claim, evidence, and result +- if ownership of a decision or rationale is unclear, block with manual-review files instead of deleting it or guessing +- after the edit, verify every touched truth doc still has Product Decisions and Rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked +Topology pressure signals: +- one area maps broad code such as src/**, app/**, server/**, services/**, or packages/** +- one area maps multiple unrelated controllers, route groups, services, or bounded contexts +- one truth doc owns unrelated behaviors or unrelated endpoint families +- the configured truth root has many direct non-index docs +- a changed controller, route, or service cannot map to a specific behavior doc +- Truth Sync would need to create a new generic truth doc because routing is too broad +- endpoint or controller names reveal domains missing from docs/truthmark/areas/** +Use these review thresholds as guidance: +- more than 10 direct truth docs in one folder +- more than 15 leaf areas in one child route file +- more than 8 truth docs mapped to one area +- more than 5 controllers mapped through one catch-all area +Repair rules: +- split broad, overloaded, or catch-all areas into behavior-owned child route files +- split mixed-owner truth docs into bounded owner docs before adding new behavior claims +- create route files under docs/truthmark/areas/ when a product/domain boundary is clear +- create behavior truth docs under the configured truth root only when behavior lacks a current doc +- README.md files are indexes, not Truth Sync targets +- prefer bounded leaf truth docs at //.md +- keep behavior truth docs behavior-oriented, not endpoint-oriented +- keep API endpoint details in the nearest contract truth doc when such a doc exists +- update routing so future Truth Sync can target small docs +- preserve existing authored docs; move or rewrite only when needed to remove ambiguity +- report Truth docs split when one broad or mixed-owner truth doc becomes multiple bounded docs +Truth-doc shape repair gate: +- Truth Structure may restructure broader routed docs when topology, ownership, or doc-shape repair is already in scope. +- repair shape in place only after the ownership gate confirms the doc is the right bounded owner +- use Truth Structure for ownership splits; do not treat broad or mixed-owner docs as in-place repair work +- repair shape when a narrow edit would make truth worse: missing template sections, stale evidence conflicts, cross-section updates within one owner, or wrong frontmatter/source/headings +- preserve supported claims; remove, narrow, or block unsupported or stale claims +- report docs restructured and why a narrow edit was not sufficient +Evidence Gate: +- apply the Evidence Gate before finishing when Truth Structure writes routed docs, ownership claims, Product Decisions, or Rationale +- support ownership/behavior claims with topology or primary checkout evidence from layout, implementation boundaries, docs, config, route files, tests, templates, schemas, or contracts +- tests/examples/canonical docs corroborate; remove, narrow, or block unsupported claims +Maintain architecture docs only for structure-level changes: system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership. +Keep ordinary behavior, endpoints, UI copy, validation rules, and bug fixes in behavior or contract docs unless they change those boundaries. +- Do not finish topology repair with routed canonical current-truth docs missing Product Decisions or Rationale sections. +- If an existing canonical doc lacks either section, add the missing heading beside Current Behavior with a concise current-state placeholder or active decision. +Portable fallback: +- If this skill surface is unavailable, perform the same workflow directly from committed repository files. +- Do not require the truthmark CLI. +- Inspect .truthmark/config.yml and configured route files only when they exist; then inspect canonical docs and representative implementation code. +- Use a subagent only when the host supports that pattern; otherwise perform the topology repair inline. +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md +Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. +Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. +Update Product Decisions and Rationale when a decision changes behavior. +Report completion in this shape: +```md +Truth Structure: completed +Topology reviewed: +- controllers: src/auth/** +- docs root: docs/truth +- route files: docs/truthmark/areas.md +Areas reviewed: +- src/auth/** +Routing updated: +- docs/truthmark/areas.md +Initial truth boundary: +- Area: Authentication +- Code: src/auth/** +- Truth owner: docs/truth/authentication/session.md +- Scope: session behavior only +Truth docs created: +- docs/truth/authentication/session.md +Truth docs split: +- docs/truth/authentication/README.md -> docs/truth/authentication/session.md +Truth docs restructured: +- docs/truth/authentication/README.md +Evidence checked: +- Claim: Session behavior belongs to a dedicated Authentication truth owner. + Evidence: src/auth/** / docs/truthmark/areas.md:7 + Result: supported +Topology decisions: +- Added an Authentication area because session behavior has a distinct code surface and truth owner. +Notes: +- Added an Authentication area for session behavior. +``` diff --git a/.github/prompts/truthmark-sync.prompt.md b/.github/prompts/truthmark-sync.prompt.md new file mode 100644 index 0000000..5bb83aa --- /dev/null +++ b/.github/prompts/truthmark-sync.prompt.md @@ -0,0 +1,144 @@ +--- +agent: 'agent' +description: 'Use automatically at finish-time after functional code changes, or explicit /truthmark-sync, $truthmark-sync, or /truthmark:sync. Skip docs-only, formatting-only, behavior-preserving renames, missing config, and no-code changes. Not for doc-first realization or manual topology design.' +--- + +--- +name: truthmark-sync +description: Use automatically at finish-time after functional code changes, or explicit /truthmark-sync, $truthmark-sync, or /truthmark:sync. Skip docs-only, formatting-only, behavior-preserving renames, missing config, and no-code changes. Not for doc-first realization or manual topology design. +argument-hint: Optional changed-code area, truth-doc area, or sync focus +user-invocable: true +truthmark-version: 1.6.0 +--- + +Use this skill automatically before finishing when functional code changed since the last successful Truth Sync. Also run it immediately when the user explicitly invokes Truth Sync. +Invocations: OpenCode /skill truthmark-sync; Codex /truthmark-sync or $truthmark-sync; Claude Code /truthmark-sync; GitHub Copilot /truthmark-sync; Gemini CLI /truthmark:sync. +Explicit invocation runs immediately. Later functional-code changes reopen the finish-time requirement, and an earlier explicit run satisfies the finish gate only if no later functional-code changes occur. +Skip when changes are documentation-only, formatting-only, clearly behavior-preserving renames with no truth impact, when no Truthmark config exists yet, or when there are no functional code changes. +Parent workflow: +1. Inspect git status, staged changes, unstaged changes, and untracked files directly. +2. Inspect .truthmark/config.yml and configured route files only when they exist; then inspect relevant canonical docs. +3. Identify functional-code changes and the nearest truth docs or routing repairs. +4. Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. +Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. +5. Code verification is parent-owned: follow repository instructions and task context, and report what ran or why it did not run. +6. Dispatch bounded Truth Sync workers only when the host supports subagent dispatch and the acting agent chooses that path; otherwise execute the same sync task inline. +Copilot custom-agent mode: +- use automatically when this workflow runs in Copilot and the parent agent chooses bounded custom-agent fan-out +- dispatch read-only project custom agents for verification: @truth-route-auditor, @truth-claim-verifier +- read-only custom agents inspect checkout evidence directly, return structured findings, and must not edit files +- parent supplies bounded evidence shards; read-only custom agents must not preload host instruction files or repo-wide policy docs unless assigned as evidence +- dispatch write-capable project custom agents only with explicit write leases: @truth-doc-writer +- each write lease must name objective, required reads, allowed writes, forbidden writes, evidence, verification, and report fields +- write workers must stop when a required edit is off-lease and report status, filesChanged, evidence, offLeaseChanges, blockers, and notes +- parent must inspect the actual checkout diff against each lease before accepting a worker report +- Parent agent owns Truth Sync acceptance, lease validation, and final report +Topology quality gate: +- before updating truth docs, verify the changed code resolves to a specific behavior-owned area and bounded truth owner +- if routing is missing, stale, broad, overloaded, catch-all route only, or cannot map changed code to a bounded truth owner, do not create another generic truth doc +- run Truth Structure before syncing when topology repair is safe and in scope +- block and recommend Truth Structure when topology repair is unsafe, ambiguous, or outside the current task boundary +- report the route files and changed code paths that require structure repair +- README.md files are indexes, not Truth Sync targets +- must not append behavior details to a README.md index +- create or update a bounded leaf truth doc when behavior changes do not fit an existing leaf doc +Truth-doc ownership gate: +- before editing or relying on changed functional files and impacted truth docs, verify each target/source truth doc is a bounded owner for the behavior +- if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it +- if an impacted doc is broad, mixed-owner, index-like, or the update spans independent behavior owners, run Truth Structure before syncing when safe and in scope; otherwise block and recommend Truth Structure +- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Blocked reason as applicable +Product Decisions/Rationale preservation gate: +- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions and Rationale sections in every source or touched truth doc +- preserve each current decision and rationale in the bounded owner doc it governs; when splitting, move it to the new owner doc rather than deleting it or leaving it in an index +- remove or narrow a decision or rationale only when checkout evidence shows it is stale or unsupported, and report the exact claim, evidence, and result +- if ownership of a decision or rationale is unclear, block with manual-review files instead of deleting it or guessing +- after the edit, verify every touched truth doc still has Product Decisions and Rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked +When creating or updating a truth doc, inspect the routed truth kind and use the matching `docs/templates/-doc.md` template. +Supported kinds: behavior, contract, architecture, workflow, operations, and test-behavior. +Align existing docs to that template while preserving accurate authored content. +If the template is missing, use Scope, Product Decisions, Rationale, and the kind-specific current-truth section. +Teams may edit the template files under docs/templates/ to define their local truth-doc standards. +Truth-doc shape repair gate: +- Truth Sync may restructure only truth docs impacted by the current functional-code change. +- repair shape in place only after the ownership gate confirms the doc is the right bounded owner +- use Truth Structure for ownership splits; do not treat broad or mixed-owner docs as in-place repair work +- repair shape when a narrow edit would make truth worse: missing template sections, stale evidence conflicts, cross-section updates within one owner, or wrong frontmatter/source/headings +- preserve supported claims; remove, narrow, or block unsupported or stale claims +- report docs restructured and why a narrow edit was not sufficient +Maintain architecture docs only for structure-level changes: system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership. +Keep ordinary behavior, endpoints, UI copy, validation rules, and bug fixes in behavior or contract docs unless they change those boundaries. +Evidence Gate: +- route-first: map changed functional files to bounded route owners and primary canonical docs +- review new or changed behavior-bearing claims only in touched docs, route ownership, Product Decisions, and Rationale +- support claims with primary checkout evidence: implementation, config, routing, generated templates, schemas, or contract definitions +- tests/examples/canonical docs corroborate; they are not sole proof when implementation conflicts +- remove, narrow, or block unsupported claims +- if no impacted doc changed, report why truth was already current or why sync was skipped +Repository intelligence artifacts are optional derived context: RepoIndex, RouteMap, ImpactSet, and ContextPack may guide routing, context selection, and verification planning when available. +They do not override checkout evidence, canonical truth docs, route files, or workflow write boundaries. +If unavailable, inspect any present Truthmark config, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated. +Optional validation tooling: +- you may run truthmark check when local tooling is available +- do not require the truthmark binary; direct checkout inspection is the canonical path +- optional validation must not replace agent judgment about docs and routing +- update Product Decisions and Rationale when a behavior change comes from a decision change +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/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md +Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. +Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. +Update Product Decisions and Rationale when a decision changes behavior. +Parent post-sync verification: +- verify only truth docs and leased truth routing files changed during sync +- block on any unrelated diff caused by the sync step +- block if functional code changed during sync +- for each write lease, validate the worker report against the actual worker diff, allowedWrites, forbiddenWrites, identity fields, filesChanged, offLeaseChanges, blockers, and required report fields before accepting it +- validate the final report against the structured Truth Sync report contract, including Claim, indented Evidence, and Result values supported, narrowed, removed, or blocked under Evidence checked +- verify the updated docs correspond to the reviewed changed-code surface +- verify the final report records ownership review, structure requirement, split, restructure, or blocked reason when the ownership gate fired +- blocked outcomes must preserve the working tree as-is: no rollback, no post-block cleanup edits, and manual-review reporting of any remaining files +Report completion in this shape: +```md +Truth Sync: completed + +Changed code reviewed: +- src/auth/session.ts + +Ownership reviewed: +- docs/truthmark/areas.md + +Truth docs updated: +- docs/truth/repository/overview.md + +Evidence checked: +- Claim: Session timeout behavior is documented in the mapped repository truth doc. + Evidence: src/auth/session.ts:12 / docs/truthmark/areas.md:11 + Result: supported + +Helper scripts: +- validate-write-lease: skipped, no write lease used + +Notes: +- Updated session timeout behavior. +``` +Blocked report example: +```md +Truth Sync: blocked + +Reason: +- routing repair is not allowed + +Files requiring manual review: +- docs/truthmark/areas.md + +Next action: +- update routing metadata and rerun Truth Sync +``` diff --git a/.github/skills/truthmark-check/SKILL.md b/.github/skills/truthmark-check/SKILL.md new file mode 100644 index 0000000..67d1482 --- /dev/null +++ b/.github/skills/truthmark-check/SKILL.md @@ -0,0 +1,30 @@ +--- +name: truthmark-check +description: Use when the user asks to audit repository truth health, routing, ownership, or canonical docs. Not for normal lint/test/typecheck/code-review verification, finish-time Sync, or silently rewriting docs. +argument-hint: Optional area, doc path, or audit focus +user-invocable: true +truthmark-version: 1.6.0 +--- + +# Truthmark Check + +Use this skill to audit repository truth health. + +Use as a Copilot agent skill. Prompt files remain available under `.github/prompts/` for command-style invocation in supported Copilot IDEs. + + +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/areas.md; docs/truthmark/areas/) only when they exist; then inspect canonical docs and relevant implementation directly. +- Report issues and suggested fixes; do not silently rewrite unrelated files. +- Direct checkout inspection is valid even when local tooling is unavailable. +- Read support/procedure.md before auditing details. +- Read support/subagents-and-leases.md before dispatching verifier subagents. +- Read support/report-template.md before the final report. + +Progressive disclosure: +- support/procedure.md +- support/report-template.md +- support/subagents-and-leases.md diff --git a/.github/skills/truthmark-check/support/procedure.md b/.github/skills/truthmark-check/support/procedure.md new file mode 100644 index 0000000..33b7663 --- /dev/null +++ b/.github/skills/truthmark-check/support/procedure.md @@ -0,0 +1,37 @@ +# Truthmark Check Procedure + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +# Truthmark Check + +Use this skill to audit repository truth health. + +Invocations: OpenCode /skill truthmark-check; Codex /truthmark-check or $truthmark-check; Claude Code /truthmark-check; GitHub Copilot /truthmark-check; Gemini CLI /truthmark:check. + +Truth Check is agent-led: + +- inspect .truthmark/config.yml and configured route files only when they exist; then inspect canonical docs and relevant implementation directly +- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. +Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. +- inspect the configured root route index at docs/truthmark/areas.md and relevant child route files under docs/truthmark/areas/ when they exist +- check that current docs describe current code rather than historical plans +- check that route files map code surfaces to canonical truth docs when route files exist +- check for broad, catch-all, index-like, or mixed-owner truth docs and report them as topology issues requiring Truth Structure +- check that canonical behavior docs keep active Product Decisions and Rationale sections +- optionally run truthmark check when local tooling is available +- must not require the truthmark binary; direct inspection is always valid +- report issues and suggested fixes without silently rewriting unrelated files +- if follow-up docs edits are needed for mixed-owner docs, run or recommend Truth Structure before editing +Evidence Gate: +- support each finding and suggested fix with evidence from config, route files, canonical docs, implementation, templates, or tests +- canonical docs are context, not sole proof when implementation conflicts +- remove unsupported findings or mark open questions; validate changed claims if you edit docs + +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md +Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. +Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. +Update Product Decisions and Rationale when a decision changes behavior. diff --git a/.github/skills/truthmark-check/support/report-template.md b/.github/skills/truthmark-check/support/report-template.md new file mode 100644 index 0000000..e98269e --- /dev/null +++ b/.github/skills/truthmark-check/support/report-template.md @@ -0,0 +1,27 @@ +# Truthmark Check Report Template + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Report completion in this shape: + +```md +Truth Check: completed + +Files reviewed: +- docs/truthmark/areas.md + +Issues found: +- none + +Fixes suggested: +- none + +Evidence checked: +- Finding: The root route index is present and maps repository truth owners. + Evidence: docs/truthmark/areas.md:1 + Suggested fix: none + Confidence: high + +Validation: +- truthmark check +``` diff --git a/.github/skills/truthmark-check/support/subagents-and-leases.md b/.github/skills/truthmark-check/support/subagents-and-leases.md new file mode 100644 index 0000000..a6522ec --- /dev/null +++ b/.github/skills/truthmark-check/support/subagents-and-leases.md @@ -0,0 +1,10 @@ +# Truthmark Check Subagents And Leases + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Copilot custom-agent mode: +- use automatically when this workflow runs in Copilot and the parent agent chooses bounded custom-agent fan-out +- dispatch read-only project custom agents only: @truth-route-auditor, @truth-claim-verifier, @truth-doc-reviewer +- custom agents inspect checkout evidence directly, return structured findings, and must not edit files +- parent supplies bounded evidence shards; custom agents must not preload host instruction files or repo-wide policy docs unless assigned as evidence +- Parent agent owns the final Truth Check report diff --git a/.github/skills/truthmark-document/SKILL.md b/.github/skills/truthmark-document/SKILL.md new file mode 100644 index 0000000..e1f4285 --- /dev/null +++ b/.github/skills/truthmark-document/SKILL.md @@ -0,0 +1,32 @@ +--- +name: truthmark-document +description: Use when the user asks to document existing implemented behavior, or Sync, Check, or Structure finds implemented behavior missing canonical truth. Not for functional-code changes, doc-first implementation, or topology repair that needs Structure. +argument-hint: Optional implemented behavior, API endpoint, route, controller, package, or truth-doc area to document +user-invocable: true +truthmark-version: 1.6.0 +--- + +# Truthmark Document + +Use this skill to document existing implemented behavior when no functional-code changes are required for the task. + +Use as a Copilot agent skill. Prompt files remain available under `.github/prompts/` for command-style invocation in supported Copilot IDEs. + + +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/areas.md; docs/truthmark/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 before dispatching or accepting worker output. +- Read support/report-template.md before the final report. + +Progressive disclosure: +- support/procedure.md +- support/report-template.md +- support/subagents-and-leases.md +- helper-manifest.yml +- support/helper-policy.md diff --git a/.github/skills/truthmark-document/helper-manifest.yml b/.github/skills/truthmark-document/helper-manifest.yml new file mode 100644 index 0000000..dc05fe5 --- /dev/null +++ b/.github/skills/truthmark-document/helper-manifest.yml @@ -0,0 +1,34 @@ +# Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. +helpers: + validate-document-report: + optional: true + runner: truthmark>=1.6.0 + 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>=1.6.0 + 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/.github/skills/truthmark-document/support/helper-policy.md b/.github/skills/truthmark-document/support/helper-policy.md new file mode 100644 index 0000000..53b72b7 --- /dev/null +++ b/.github/skills/truthmark-document/support/helper-policy.md @@ -0,0 +1,23 @@ +# Optional Helper CLI Policy + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Optional helper CLI commands may collect deterministic checkout facts or validate artifacts. If the Truthmark CLI is unavailable or too old for a declared helper, continue manually using this procedure and report which helper was skipped. Helper output is derived evidence; it does not override direct checkout inspection, workflow write boundaries, or parent acceptance. + +Runner detection: +- Check the declared Truthmark CLI runner before invoking a helper. +- Invoke helpers through the installed `truthmark validate ... --json` CLI command using argv-style arguments from helper-manifest.yml. +- If unavailable or version-mismatched, 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>=1.6.0; manual fallback: manually validate support/report-template.md required sections and structured Evidence checked entries +- validate-write-lease: optional truthmark>=1.6.0; 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/.github/skills/truthmark-document/support/procedure.md b/.github/skills/truthmark-document/support/procedure.md new file mode 100644 index 0000000..44d8eb3 --- /dev/null +++ b/.github/skills/truthmark-document/support/procedure.md @@ -0,0 +1,79 @@ +# Truthmark Document Procedure + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +# Truthmark Document + +Use this skill to document existing implemented behavior when no functional-code changes are required for the task. +Invocations: OpenCode /skill truthmark-document; Codex /truthmark-document or $truthmark-document; Claude Code /truthmark-document; GitHub Copilot /truthmark-document; Gemini CLI /truthmark:document. + +Truth Document is manual and implementation-first: + +- run only when the user explicitly asks to generate or update truth docs for existing behavior, or when Truth Sync, Truth Check, or Truth Structure reports implemented behavior that lacks canonical truth docs +- inspect .truthmark/config.yml and configured route files only when they exist; then inspect existing canonical docs, implementation code, and tests directly +- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. +Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. +- document current implemented behavior; do not invent future behavior or planned endpoints +- may write canonical truth docs and docs/truthmark/areas.md or relevant child route files only +- must not write functional code +- when routing is missing, stale, broad, overloaded, catch-all, or cannot map the behavior to a bounded truth owner, run Truth Structure first when routing repair is safe and in scope +- block and recommend Truth Structure when routing repair is unsafe, ambiguous, or outside the task boundary +- keep feature README.md files as indexes rather than truth-document targets +- create or update bounded leaf truth docs when behavior does not fit an existing leaf doc +- keep behavior truth docs behavior-oriented, not endpoint-oriented, unless the endpoint itself is the behavior boundary +- keep API endpoint details in the nearest contract truth doc when such a doc owns the API contract +- preserve unrelated authored content +Truth-doc ownership gate: +- before editing or relying on the implemented behavior and candidate truth docs, verify each target/source truth doc is a bounded owner for the behavior +- if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it +- if the target doc is broad, mixed-owner, index-like, or the documented behavior spans independent owners, run Truth Structure first when safe and in scope; otherwise block and recommend Truth Structure +- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Blocked reason as applicable +Product Decisions/Rationale preservation gate: +- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions and Rationale sections in every source or touched truth doc +- preserve each current decision and rationale in the bounded owner doc it governs; when splitting, move it to the new owner doc rather than deleting it or leaving it in an index +- remove or narrow a decision or rationale only when checkout evidence shows it is stale or unsupported, and report the exact claim, evidence, and result +- if ownership of a decision or rationale is unclear, block with manual-review files instead of deleting it or guessing +- after the edit, verify every touched truth doc still has Product Decisions and Rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked +Evidence Gate: +- route-first: map the documented behavior to bounded route owners and primary canonical docs +- review new or changed behavior-bearing claims only in touched docs, route ownership, Product Decisions, and Rationale +- support claims with primary checkout evidence: implementation, config, routing, generated templates, schemas, or contract definitions +- tests/examples/canonical docs corroborate; they are not sole proof when implementation conflicts +- remove, narrow, or block unsupported claims +- if no truth doc changed, report why current truth was already sufficient or why documentation was blocked +Repository intelligence artifacts are optional derived context: RepoIndex, RouteMap, ImpactSet, and ContextPack may guide routing, context selection, and verification planning when available. +They do not override checkout evidence, canonical truth docs, route files, or workflow write boundaries. +If unavailable, inspect any present Truthmark config, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated. +When creating or updating a truth doc, inspect the routed truth kind and use the matching `docs/templates/-doc.md` template. +Supported kinds: behavior, contract, architecture, workflow, operations, and test-behavior. +Align existing docs to that template while preserving accurate authored content. +If the template is missing, use Scope, Product Decisions, Rationale, and the kind-specific current-truth section. +Teams may edit the template files under docs/templates/ to define their local truth-doc standards. +Truth-doc shape repair gate: +- Truth Document may restructure only truth docs for the implemented behavior being documented. +- repair shape in place only after the ownership gate confirms the doc is the right bounded owner +- use Truth Structure for ownership splits; do not treat broad or mixed-owner docs as in-place repair work +- repair shape when a narrow edit would make truth worse: missing template sections, stale evidence conflicts, cross-section updates within one owner, or wrong frontmatter/source/headings +- preserve supported claims; remove, narrow, or block unsupported or stale claims +- report docs restructured and why a narrow edit was not sufficient +Maintain architecture docs only for structure-level changes: system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership. +Keep ordinary behavior, endpoints, UI copy, validation rules, and bug fixes in behavior or contract docs unless they change those boundaries. +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md +Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. +Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. +Update Product Decisions and Rationale when a decision changes behavior. +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 +- block on functional code, generated host surfaces, or unrelated diffs caused by document work +- for each write lease, validate the worker report against the actual worker diff, allowedWrites, forbiddenWrites, identity fields, filesChanged, offLeaseChanges, blockers, and required report fields before accepting it +- verify the final report records ownership review, structure requirement, restructure, routing update, or blocked reason when applicable diff --git a/.github/skills/truthmark-document/support/report-template.md b/.github/skills/truthmark-document/support/report-template.md new file mode 100644 index 0000000..22741ff --- /dev/null +++ b/.github/skills/truthmark-document/support/report-template.md @@ -0,0 +1,37 @@ +# Truthmark Document Report Template + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Report completion in this shape: +```md +Truth Document: completed + +Implementation reviewed: +- src/routing/area-resolver.ts + +Ownership reviewed: +- docs/truthmark/areas.md + +Truth docs created: +- docs/truth/contracts.md + +Truth docs updated: +- docs/truth/check-diagnostics.md + +Truth docs restructured: +- docs/truth/check-diagnostics.md + +Routing updated: +- docs/truthmark/areas.md + +Evidence checked: +- Claim: Route resolution behavior is documented in the contracts truth doc. + Evidence: src/routing/area-resolver.ts:14 / docs/truthmark/areas.md:9 + Result: supported + +Helper scripts: +- validate-write-lease: skipped, no write lease used + +Notes: +- Documented routing and behavior from route handlers and tests. +``` diff --git a/.github/skills/truthmark-document/support/subagents-and-leases.md b/.github/skills/truthmark-document/support/subagents-and-leases.md new file mode 100644 index 0000000..0bde5f6 --- /dev/null +++ b/.github/skills/truthmark-document/support/subagents-and-leases.md @@ -0,0 +1,14 @@ +# Truthmark Document Subagents And Leases + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Copilot custom-agent mode: +- use automatically when this workflow runs in Copilot and the parent agent chooses bounded custom-agent fan-out +- dispatch read-only project custom agents for verification: @truth-route-auditor, @truth-claim-verifier +- read-only custom agents inspect checkout evidence directly, return structured findings, and must not edit files +- parent supplies bounded evidence shards; read-only custom agents must not preload host instruction files or repo-wide policy docs unless assigned as evidence +- dispatch write-capable project custom agents only with explicit write leases: @truth-doc-writer +- each write lease must name objective, required reads, allowed writes, forbidden writes, evidence, verification, and report fields +- write workers must stop when a required edit is off-lease and report status, filesChanged, evidence, offLeaseChanges, blockers, and notes +- parent must inspect the actual checkout diff against each lease before accepting a worker report +- Parent agent owns Truth Document acceptance, lease validation, and final report diff --git a/.github/skills/truthmark-preview/SKILL.md b/.github/skills/truthmark-preview/SKILL.md new file mode 100644 index 0000000..06b91c9 --- /dev/null +++ b/.github/skills/truthmark-preview/SKILL.md @@ -0,0 +1,29 @@ +--- +name: truthmark-preview +description: Use when the user explicitly asks to preview likely workflow routing, target files, writes, or subagent use before edits. Not for validation, automatic gates, final correctness, or replacing Truth Check. +argument-hint: Optional requested outcome, code area, doc path, or routing question +user-invocable: true +truthmark-version: 1.6.0 +--- + +# Truthmark Preview + +Use this skill only when the user explicitly asks to preview Truthmark routing or workflow choice before edits. + +Use as a Copilot agent skill. Prompt files remain available under `.github/prompts/` for command-style invocation in supported Copilot IDEs. + + +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 configured route files (docs/truthmark/areas.md; docs/truthmark/areas/) only when they exist; then inspect only the truth docs or implementation files needed to preview ownership. +- Truth Preview is read-only; this report is intended, not authorized. +- must not edit files and must not issue write leases; do not run Truth Sync automatically, replace Truth Check, claim final correctness, or mutate code. +- Use optional read-only route-auditor evidence only when it reduces context or clarifies ownership. +- Hand off to the selected workflow after user approval. + +Progressive disclosure: +- support/procedure.md +- support/report-template.md +- support/subagents-and-leases.md diff --git a/.github/skills/truthmark-preview/support/procedure.md b/.github/skills/truthmark-preview/support/procedure.md new file mode 100644 index 0000000..d419bf2 --- /dev/null +++ b/.github/skills/truthmark-preview/support/procedure.md @@ -0,0 +1,43 @@ +# Truthmark Preview Procedure + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Use this skill only when the user explicitly asks to preview Truthmark routing or workflow choice before edits. + +Invocations: OpenCode /skill truthmark-preview; Codex /truthmark-preview or $truthmark-preview; Claude Code /truthmark-preview; GitHub Copilot /truthmark-preview; Gemini CLI /truthmark:preview. + +Truth Preview is read-only. Its report is intended, not authorized. + +Purpose: +- preview the likely Truthmark workflow, route owner, target files, expected write classes, suggested subagent use, and blocking ambiguity before edits happen +- hand off to the selected workflow after user approval +- keep the selector thin so agents can avoid loading or acting through heavier workflows prematurely + +Read: +- .truthmark/config.yml, only when present +- docs/truthmark/areas.md, only when present +- relevant child route files under docs/truthmark/areas/, only when present +- relevant truth docs and implementation files needed to preview ownership +- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. +Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. + +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/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md diff --git a/.github/skills/truthmark-preview/support/report-template.md b/.github/skills/truthmark-preview/support/report-template.md new file mode 100644 index 0000000..72cf72b --- /dev/null +++ b/.github/skills/truthmark-preview/support/report-template.md @@ -0,0 +1,41 @@ +# Truthmark Preview Report Template + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Report completion in this shape: +```md +Truth Preview: completed + +Requested outcome: +- preview likely Truthmark workflow routing before edits + +Likely workflow: +- truthmark-document + +Why this workflow: +- positive trigger: document existing implemented behavior +- negative triggers considered: functional-code change, doc-first implementation, topology repair, truth audit +- forbidden adjacency considered: must not edit functional code + +Likely route owner: +- route file: docs/truthmark/areas.md +- truth doc: docs/truth/example.md +- confidence: medium + +Expected write classes: +- truth docs + +Expected target files: +- docs/truth/example.md + +Suggested subagent use: +- read-only verifiers: truth_route_auditor +- write workers: none in Preview +- leases needed: none in Preview + +Blocking ambiguity: +- none identified in preview + +Handoff: +- Run the selected Truthmark workflow after user approval. +``` diff --git a/.github/skills/truthmark-preview/support/subagents-and-leases.md b/.github/skills/truthmark-preview/support/subagents-and-leases.md new file mode 100644 index 0000000..bdcaeea --- /dev/null +++ b/.github/skills/truthmark-preview/support/subagents-and-leases.md @@ -0,0 +1,10 @@ +# Truthmark Preview Subagents And Leases + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Copilot custom-agent mode: +- use automatically when this workflow runs in Copilot and the parent agent chooses bounded custom-agent fan-out +- dispatch read-only project custom agents only: @truth-route-auditor +- custom agents inspect checkout evidence directly, return structured findings, and must not edit files +- parent supplies bounded evidence shards; custom agents 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/.github/skills/truthmark-realize/SKILL.md b/.github/skills/truthmark-realize/SKILL.md new file mode 100644 index 0000000..7ce60a0 --- /dev/null +++ b/.github/skills/truthmark-realize/SKILL.md @@ -0,0 +1,28 @@ +--- +name: truthmark-realize +description: Use when the user explicitly asks to realize Truthmark truth docs into code, including /truthmark-realize, $truthmark-realize, or /truthmark:realize. Not for syncing docs after code changes, documenting existing code, topology repair, or truth audits. +argument-hint: Optional truth doc path, area, or desired code behavior to realize +user-invocable: true +truthmark-version: 1.6.0 +--- + +# Truthmark Realize + +Use this skill only when the user explicitly asks to realize truth docs into code. + +Use as a Copilot agent skill. Prompt files remain available under `.github/prompts/` for command-style invocation in supported Copilot IDEs. + + +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/areas.md; docs/truthmark/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 +- support/report-template.md diff --git a/.github/skills/truthmark-realize/support/procedure.md b/.github/skills/truthmark-realize/support/procedure.md new file mode 100644 index 0000000..aa9883b --- /dev/null +++ b/.github/skills/truthmark-realize/support/procedure.md @@ -0,0 +1,42 @@ +# Truthmark Realize Procedure + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +# Truthmark Realize + +Use this skill only when the user explicitly asks to realize truth docs into code. + +Invocations: OpenCode /skill truthmark-realize; Codex /truthmark-realize or $truthmark-realize; Claude Code /truthmark-realize; GitHub Copilot /truthmark-realize; Gemini CLI /truthmark:realize. + +Truth Realize is doc-first: + +- truth docs lead +- code follows +- Truth Realize never edits the truth docs it is realizing + +Workflow: + +1. Read the updated truth docs named by the user, or infer the relevant docs from configured route files when present. +2. Inspect .truthmark/config.yml and configured route files (docs/truthmark/areas.md; docs/truthmark/areas/) only when they exist; then read tests and the relevant functional code. +3. 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. +Truth-doc ownership gate: +- before editing or relying on source truth docs before writing code, verify each target/source truth doc is a bounded owner for the behavior +- if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it +- if a source truth doc is broad, mixed-owner, index-like, unrouteable, stale, or conflicts with implementation evidence, block before writing code and recommend Truth Structure or Truth Document +- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Blocked reason as applicable +4. Update functional code only so implementation matches bounded, current truth claims from the source docs. +5. Do not edit truth docs or truth routing while realizing those docs. +6. Run relevant tests for the changed code. +7. Report changed code files and verification steps. +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md + +Read and write boundaries: + +- may read truth docs, routing docs, and relevant functional code +- may write functional code only +- must not edit truth docs or truth routing while realizing those docs diff --git a/.github/skills/truthmark-realize/support/report-template.md b/.github/skills/truthmark-realize/support/report-template.md new file mode 100644 index 0000000..e49dde5 --- /dev/null +++ b/.github/skills/truthmark-realize/support/report-template.md @@ -0,0 +1,18 @@ +# Truthmark Realize Report Template + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Report completion in this shape: + +```md +Truth Realize: completed + +Truth docs used: +- docs/truth/authentication/session-timeout.md + +Code updated: +- src/auth/session.ts + +Verification: +- npm test -- auth +``` diff --git a/.github/skills/truthmark-structure/SKILL.md b/.github/skills/truthmark-structure/SKILL.md new file mode 100644 index 0000000..a378a21 --- /dev/null +++ b/.github/skills/truthmark-structure/SKILL.md @@ -0,0 +1,29 @@ +--- +name: truthmark-structure +description: Use when routing or truth ownership is missing, stale, broad, overloaded, catch-all, unrouteable, mixed-owner, needs split/repair, or needs new area setup. Not for documenting implemented behavior, syncing a code diff, or realizing docs into code. +argument-hint: Optional area, directory, or routing concern +user-invocable: true +truthmark-version: 1.6.0 +--- + +# Truthmark Structure + +Use this skill to design or repair Truthmark area structure. + +Use as a Copilot agent skill. Prompt files remain available under `.github/prompts/` for command-style invocation in supported Copilot IDEs. + + +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/areas.md; docs/truthmark/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 +- support/report-template.md +- support/subagents-and-leases.md diff --git a/.github/skills/truthmark-structure/support/procedure.md b/.github/skills/truthmark-structure/support/procedure.md new file mode 100644 index 0000000..9104b33 --- /dev/null +++ b/.github/skills/truthmark-structure/support/procedure.md @@ -0,0 +1,109 @@ +# Truthmark Structure Procedure + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Use this skill to design or repair Truthmark area structure. +Invocations: OpenCode /skill truthmark-structure; Codex /truthmark-structure or $truthmark-structure; Claude Code /truthmark-structure; GitHub Copilot /truthmark-structure; Gemini CLI /truthmark:structure. +Truth Structure is agent-native: +- inspect repository layout, current docs, Truthmark config and route files when present, and relevant code directly +- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. +Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. +- inspect the configured root route index at docs/truthmark/areas.md and relevant child route files under docs/truthmark/areas/ when they exist +- define areas by product or behavior ownership, not by mechanical directory mirroring +- create or repair docs/truthmark/areas.md +- create starter truth docs when useful and when they belong in the canonical current-truth surface +- Starter truth docs must use closed YAML frontmatter bounded by opening and closing --- lines; include status, doc_type, last_reviewed, and source_of_truth inside that frontmatter. +- Starter truth docs must include ## Product Decisions and ## Rationale sections. + +When creating or updating a truth doc, inspect the routed truth kind and use the matching `docs/templates/-doc.md` template. +Supported kinds: behavior, contract, architecture, workflow, operations, and test-behavior. +Align existing docs to that template while preserving accurate authored content. +If the template is missing, use Scope, Product Decisions, Rationale, and the kind-specific current-truth section. +Teams may edit the template files under docs/templates/ to define their local truth-doc standards. +- use docs/truth/**, docs/architecture/**, or docs/standards/** for current truth destinations +- use only canonical current-truth destinations for starter truth docs +- keep active Product Decisions and Rationale in the canonical doc that owns the behavior +- preserve unrelated authored content +## New area setup +Use when a user asks to onboard a new code area into Truthmark, a new package, controller, domain, or product area lacks bounded truth ownership, or a new product area needs routing and starter truth docs. +Do: +- inspect the named code area +- infer bounded product or behavior ownership +- choose the owning route when ownership is clear; otherwise propose the route and block for review +- create or update the child route entry or file +- create starter truth docs only where current truth is missing +- report the initial truth boundary +Do not: +- do not edit functional code +- do not perform full behavior documentation unless evidence is inspected and the task explicitly asks for it +- do not patch broad or mixed-owner docs in place +- do not create generic catch-all docs +- do not treat README files as Sync targets +## Topology Governance +Truth Structure owns documentation topology. Do not depend on humans to manually organize docs/truth. Treat the configured truth root as a managed semantic root. +Inspect controllers, routes, handlers, services, packages, tests, existing truth docs, and route files; infer product and domain ownership from behavior boundaries, not from mechanical directory mirroring. +When topology pressure exists, repair structure before creating or extending truth docs. +Truth-doc ownership gate: +- before editing or relying on candidate route owners and current truth docs, verify each target/source truth doc is a bounded owner for the behavior +- if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it +- if a truth doc mixes independent owners, route ownership is broad, or a split is required for bounded ownership, split and reroute into bounded truth docs when safe; otherwise block with manual-review files +- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Blocked reason as applicable +Product Decisions/Rationale preservation gate: +- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions and Rationale sections in every source or touched truth doc +- preserve each current decision and rationale in the bounded owner doc it governs; when splitting, move it to the new owner doc rather than deleting it or leaving it in an index +- remove or narrow a decision or rationale only when checkout evidence shows it is stale or unsupported, and report the exact claim, evidence, and result +- if ownership of a decision or rationale is unclear, block with manual-review files instead of deleting it or guessing +- after the edit, verify every touched truth doc still has Product Decisions and Rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked +Topology pressure signals: +- one area maps broad code such as src/**, app/**, server/**, services/**, or packages/** +- one area maps multiple unrelated controllers, route groups, services, or bounded contexts +- one truth doc owns unrelated behaviors or unrelated endpoint families +- the configured truth root has many direct non-index docs +- a changed controller, route, or service cannot map to a specific behavior doc +- Truth Sync would need to create a new generic truth doc because routing is too broad +- endpoint or controller names reveal domains missing from docs/truthmark/areas/** +Use these review thresholds as guidance: +- more than 10 direct truth docs in one folder +- more than 15 leaf areas in one child route file +- more than 8 truth docs mapped to one area +- more than 5 controllers mapped through one catch-all area +Repair rules: +- split broad, overloaded, or catch-all areas into behavior-owned child route files +- split mixed-owner truth docs into bounded owner docs before adding new behavior claims +- create route files under docs/truthmark/areas/ when a product/domain boundary is clear +- create behavior truth docs under the configured truth root only when behavior lacks a current doc +- README.md files are indexes, not Truth Sync targets +- prefer bounded leaf truth docs at //.md +- keep behavior truth docs behavior-oriented, not endpoint-oriented +- keep API endpoint details in the nearest contract truth doc when such a doc exists +- update routing so future Truth Sync can target small docs +- preserve existing authored docs; move or rewrite only when needed to remove ambiguity +- report Truth docs split when one broad or mixed-owner truth doc becomes multiple bounded docs +Truth-doc shape repair gate: +- Truth Structure may restructure broader routed docs when topology, ownership, or doc-shape repair is already in scope. +- repair shape in place only after the ownership gate confirms the doc is the right bounded owner +- use Truth Structure for ownership splits; do not treat broad or mixed-owner docs as in-place repair work +- repair shape when a narrow edit would make truth worse: missing template sections, stale evidence conflicts, cross-section updates within one owner, or wrong frontmatter/source/headings +- preserve supported claims; remove, narrow, or block unsupported or stale claims +- report docs restructured and why a narrow edit was not sufficient +Evidence Gate: +- apply the Evidence Gate before finishing when Truth Structure writes routed docs, ownership claims, Product Decisions, or Rationale +- support ownership/behavior claims with topology or primary checkout evidence from layout, implementation boundaries, docs, config, route files, tests, templates, schemas, or contracts +- tests/examples/canonical docs corroborate; remove, narrow, or block unsupported claims +Maintain architecture docs only for structure-level changes: system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership. +Keep ordinary behavior, endpoints, UI copy, validation rules, and bug fixes in behavior or contract docs unless they change those boundaries. +- Do not finish topology repair with routed canonical current-truth docs missing Product Decisions or Rationale sections. +- If an existing canonical doc lacks either section, add the missing heading beside Current Behavior with a concise current-state placeholder or active decision. +Portable fallback: +- If this skill surface is unavailable, perform the same workflow directly from committed repository files. +- Do not require the truthmark CLI. +- Inspect .truthmark/config.yml and configured route files only when they exist; then inspect canonical docs and representative implementation code. +- Use a subagent only when the host supports that pattern; otherwise perform the topology repair inline. +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md +Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. +Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. +Update Product Decisions and Rationale when a decision changes behavior. diff --git a/.github/skills/truthmark-structure/support/report-template.md b/.github/skills/truthmark-structure/support/report-template.md new file mode 100644 index 0000000..c104da3 --- /dev/null +++ b/.github/skills/truthmark-structure/support/report-template.md @@ -0,0 +1,35 @@ +# Truthmark Structure Report Template + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Report completion in this shape: +```md +Truth Structure: completed +Topology reviewed: +- controllers: src/auth/** +- docs root: docs/truth +- route files: docs/truthmark/areas.md +Areas reviewed: +- src/auth/** +Routing updated: +- docs/truthmark/areas.md +Initial truth boundary: +- Area: Authentication +- Code: src/auth/** +- Truth owner: docs/truth/authentication/session.md +- Scope: session behavior only +Truth docs created: +- docs/truth/authentication/session.md +Truth docs split: +- docs/truth/authentication/README.md -> docs/truth/authentication/session.md +Truth docs restructured: +- docs/truth/authentication/README.md +Evidence checked: +- Claim: Session behavior belongs to a dedicated Authentication truth owner. + Evidence: src/auth/** / docs/truthmark/areas.md:7 + Result: supported +Topology decisions: +- Added an Authentication area because session behavior has a distinct code surface and truth owner. +Notes: +- Added an Authentication area for session behavior. +``` diff --git a/.github/skills/truthmark-structure/support/subagents-and-leases.md b/.github/skills/truthmark-structure/support/subagents-and-leases.md new file mode 100644 index 0000000..80b7c90 --- /dev/null +++ b/.github/skills/truthmark-structure/support/subagents-and-leases.md @@ -0,0 +1,10 @@ +# Truthmark Structure Subagents And Leases + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Copilot custom-agent mode: +- use automatically when this workflow runs in Copilot and the parent agent chooses bounded custom-agent fan-out +- dispatch read-only project custom agents only: @truth-route-auditor +- custom agents inspect checkout evidence directly, return structured findings, and must not edit files +- parent supplies bounded evidence shards; custom agents must not preload host instruction files or repo-wide policy docs unless assigned as evidence +- Parent agent owns all Truth Structure writes and final topology decisions diff --git a/.github/skills/truthmark-sync/SKILL.md b/.github/skills/truthmark-sync/SKILL.md new file mode 100644 index 0000000..6856bf8 --- /dev/null +++ b/.github/skills/truthmark-sync/SKILL.md @@ -0,0 +1,33 @@ +--- +name: truthmark-sync +description: Use automatically at finish-time after functional code changes, or explicit /truthmark-sync, $truthmark-sync, or /truthmark:sync. Skip docs-only, formatting-only, behavior-preserving renames, missing config, and no-code changes. Not for doc-first realization or manual topology design. +argument-hint: Optional changed-code area, truth-doc area, or sync focus +user-invocable: true +truthmark-version: 1.6.0 +--- + +# Truthmark Sync + +Use this skill automatically before finishing when functional code changed since the last successful Truth Sync. Also run it immediately when the user explicitly invokes Truth Sync. + +Use as a Copilot agent skill. Prompt files remain available under `.github/prompts/` for command-style invocation in supported Copilot IDEs. + + +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/areas.md; docs/truthmark/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 before dispatching or accepting worker output. +- Read support/report-template.md before the final report. + +Progressive disclosure: +- support/procedure.md +- support/report-template.md +- support/subagents-and-leases.md +- helper-manifest.yml +- support/helper-policy.md diff --git a/.github/skills/truthmark-sync/helper-manifest.yml b/.github/skills/truthmark-sync/helper-manifest.yml new file mode 100644 index 0000000..ce58751 --- /dev/null +++ b/.github/skills/truthmark-sync/helper-manifest.yml @@ -0,0 +1,34 @@ +# Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. +helpers: + validate-sync-report: + optional: true + runner: truthmark>=1.6.0 + 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>=1.6.0 + 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/.github/skills/truthmark-sync/support/helper-policy.md b/.github/skills/truthmark-sync/support/helper-policy.md new file mode 100644 index 0000000..c3d00c7 --- /dev/null +++ b/.github/skills/truthmark-sync/support/helper-policy.md @@ -0,0 +1,23 @@ +# Optional Helper CLI Policy + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Optional helper CLI commands may collect deterministic checkout facts or validate artifacts. If the Truthmark CLI is unavailable or too old for a declared helper, continue manually using this procedure and report which helper was skipped. Helper output is derived evidence; it does not override direct checkout inspection, workflow write boundaries, or parent acceptance. + +Runner detection: +- Check the declared Truthmark CLI runner before invoking a helper. +- Invoke helpers through the installed `truthmark validate ... --json` CLI command using argv-style arguments from helper-manifest.yml. +- If unavailable or version-mismatched, 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>=1.6.0; manual fallback: manually validate support/report-template.md and check Evidence checked entries match Claim, indented Evidence, and Result: supported | narrowed | removed | blocked +- validate-write-lease: optional truthmark>=1.6.0; 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/.github/skills/truthmark-sync/support/procedure.md b/.github/skills/truthmark-sync/support/procedure.md new file mode 100644 index 0000000..a80e050 --- /dev/null +++ b/.github/skills/truthmark-sync/support/procedure.md @@ -0,0 +1,88 @@ +# Truthmark Sync Procedure + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Use this skill automatically before finishing when functional code changed since the last successful Truth Sync. Also run it immediately when the user explicitly invokes Truth Sync. +Invocations: OpenCode /skill truthmark-sync; Codex /truthmark-sync or $truthmark-sync; Claude Code /truthmark-sync; GitHub Copilot /truthmark-sync; Gemini CLI /truthmark:sync. +Explicit invocation runs immediately. Later functional-code changes reopen the finish-time requirement, and an earlier explicit run satisfies the finish gate only if no later functional-code changes occur. +Skip when changes are documentation-only, formatting-only, clearly behavior-preserving renames with no truth impact, when no Truthmark config exists yet, or when there are no functional code changes. +Parent workflow: +1. Inspect git status, staged changes, unstaged changes, and untracked files directly. +2. Inspect .truthmark/config.yml and configured route files only when they exist; then inspect relevant canonical docs. +3. Identify functional-code changes and the nearest truth docs or routing repairs. +4. Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. +Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. +5. Code verification is parent-owned: follow repository instructions and task context, and report what ran or why it did not run. +6. Dispatch bounded Truth Sync workers only when the host supports subagent dispatch and the acting agent chooses that path; otherwise execute the same sync task inline. +Topology quality gate: +- before updating truth docs, verify the changed code resolves to a specific behavior-owned area and bounded truth owner +- if routing is missing, stale, broad, overloaded, catch-all route only, or cannot map changed code to a bounded truth owner, do not create another generic truth doc +- run Truth Structure before syncing when topology repair is safe and in scope +- block and recommend Truth Structure when topology repair is unsafe, ambiguous, or outside the current task boundary +- report the route files and changed code paths that require structure repair +- README.md files are indexes, not Truth Sync targets +- must not append behavior details to a README.md index +- create or update a bounded leaf truth doc when behavior changes do not fit an existing leaf doc +Truth-doc ownership gate: +- before editing or relying on changed functional files and impacted truth docs, verify each target/source truth doc is a bounded owner for the behavior +- if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it +- if an impacted doc is broad, mixed-owner, index-like, or the update spans independent behavior owners, run Truth Structure before syncing when safe and in scope; otherwise block and recommend Truth Structure +- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Blocked reason as applicable +Product Decisions/Rationale preservation gate: +- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions and Rationale sections in every source or touched truth doc +- preserve each current decision and rationale in the bounded owner doc it governs; when splitting, move it to the new owner doc rather than deleting it or leaving it in an index +- remove or narrow a decision or rationale only when checkout evidence shows it is stale or unsupported, and report the exact claim, evidence, and result +- if ownership of a decision or rationale is unclear, block with manual-review files instead of deleting it or guessing +- after the edit, verify every touched truth doc still has Product Decisions and Rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked +When creating or updating a truth doc, inspect the routed truth kind and use the matching `docs/templates/-doc.md` template. +Supported kinds: behavior, contract, architecture, workflow, operations, and test-behavior. +Align existing docs to that template while preserving accurate authored content. +If the template is missing, use Scope, Product Decisions, Rationale, and the kind-specific current-truth section. +Teams may edit the template files under docs/templates/ to define their local truth-doc standards. +Truth-doc shape repair gate: +- Truth Sync may restructure only truth docs impacted by the current functional-code change. +- repair shape in place only after the ownership gate confirms the doc is the right bounded owner +- use Truth Structure for ownership splits; do not treat broad or mixed-owner docs as in-place repair work +- repair shape when a narrow edit would make truth worse: missing template sections, stale evidence conflicts, cross-section updates within one owner, or wrong frontmatter/source/headings +- preserve supported claims; remove, narrow, or block unsupported or stale claims +- report docs restructured and why a narrow edit was not sufficient +Maintain architecture docs only for structure-level changes: system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership. +Keep ordinary behavior, endpoints, UI copy, validation rules, and bug fixes in behavior or contract docs unless they change those boundaries. +Evidence Gate: +- route-first: map changed functional files to bounded route owners and primary canonical docs +- review new or changed behavior-bearing claims only in touched docs, route ownership, Product Decisions, and Rationale +- support claims with primary checkout evidence: implementation, config, routing, generated templates, schemas, or contract definitions +- tests/examples/canonical docs corroborate; they are not sole proof when implementation conflicts +- remove, narrow, or block unsupported claims +- if no impacted doc changed, report why truth was already current or why sync was skipped +Repository intelligence artifacts are optional derived context: RepoIndex, RouteMap, ImpactSet, and ContextPack may guide routing, context selection, and verification planning when available. +They do not override checkout evidence, canonical truth docs, route files, or workflow write boundaries. +If unavailable, inspect any present Truthmark config, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated. +Optional validation tooling: +- you may run truthmark check when local tooling is available +- do not require the truthmark binary; direct checkout inspection is the canonical path +- optional validation must not replace agent judgment about docs and routing +- update Product Decisions and Rationale when a behavior change comes from a decision change +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/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md +Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. +Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. +Update Product Decisions and Rationale when a decision changes behavior. +Parent post-sync verification: +- verify only truth docs and leased truth routing files changed during sync +- block on any unrelated diff caused by the sync step +- block if functional code changed during sync +- for each write lease, validate the worker report against the actual worker diff, allowedWrites, forbiddenWrites, identity fields, filesChanged, offLeaseChanges, blockers, and required report fields before accepting it +- validate the final report against the structured Truth Sync report contract, including Claim, indented Evidence, and Result values supported, narrowed, removed, or blocked under Evidence checked +- verify the updated docs correspond to the reviewed changed-code surface +- verify the final report records ownership review, structure requirement, split, restructure, or blocked reason when the ownership gate fired +- blocked outcomes must preserve the working tree as-is: no rollback, no post-block cleanup edits, and manual-review reporting of any remaining files diff --git a/.github/skills/truthmark-sync/support/report-template.md b/.github/skills/truthmark-sync/support/report-template.md new file mode 100644 index 0000000..9bce186 --- /dev/null +++ b/.github/skills/truthmark-sync/support/report-template.md @@ -0,0 +1,41 @@ +# Truthmark Sync Report Template + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Report completion in this shape: +```md +Truth Sync: completed + +Changed code reviewed: +- src/auth/session.ts + +Ownership reviewed: +- docs/truthmark/areas.md + +Truth docs updated: +- docs/truth/repository/overview.md + +Evidence checked: +- Claim: Session timeout behavior is documented in the mapped repository truth doc. + Evidence: src/auth/session.ts:12 / docs/truthmark/areas.md:11 + Result: supported + +Helper scripts: +- validate-write-lease: skipped, no write lease used + +Notes: +- Updated session timeout behavior. +``` +Blocked report example: +```md +Truth Sync: blocked + +Reason: +- routing repair is not allowed + +Files requiring manual review: +- docs/truthmark/areas.md + +Next action: +- update routing metadata and rerun Truth Sync +``` diff --git a/.github/skills/truthmark-sync/support/subagents-and-leases.md b/.github/skills/truthmark-sync/support/subagents-and-leases.md new file mode 100644 index 0000000..fbfd493 --- /dev/null +++ b/.github/skills/truthmark-sync/support/subagents-and-leases.md @@ -0,0 +1,14 @@ +# Truthmark Sync Subagents And Leases + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Copilot custom-agent mode: +- use automatically when this workflow runs in Copilot and the parent agent chooses bounded custom-agent fan-out +- dispatch read-only project custom agents for verification: @truth-route-auditor, @truth-claim-verifier +- read-only custom agents inspect checkout evidence directly, return structured findings, and must not edit files +- parent supplies bounded evidence shards; read-only custom agents must not preload host instruction files or repo-wide policy docs unless assigned as evidence +- dispatch write-capable project custom agents only with explicit write leases: @truth-doc-writer +- each write lease must name objective, required reads, allowed writes, forbidden writes, evidence, verification, and report fields +- write workers must stop when a required edit is off-lease and report status, filesChanged, evidence, offLeaseChanges, blockers, and notes +- parent must inspect the actual checkout diff against each lease before accepting a worker report +- Parent agent owns Truth Sync acceptance, lease validation, and final report diff --git a/.opencode/agents/truth-claim-verifier.md b/.opencode/agents/truth-claim-verifier.md new file mode 100644 index 0000000..80493a8 --- /dev/null +++ b/.opencode/agents/truth-claim-verifier.md @@ -0,0 +1,33 @@ +--- +description: Read-only Truthmark claim verifier for checking canonical truth against checkout evidence. +mode: subagent +permission: + edit: deny + task: deny + webfetch: deny + websearch: deny + external_directory: deny + bash: + "*": ask + "git status*": allow + "git diff*": allow + "git log*": allow + "rg *": allow + "grep *": allow +--- + +# Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Manual invocation: @truth-claim-verifier + +Stay read-only. +Verify the behavior-bearing truth claims assigned by the parent against primary checkout evidence. +Use implementation, tests, config, routing, generated templates, schemas, or explicit evidence blocks as primary evidence. +Canonical docs and examples can corroborate but are not sole proof when implementation conflicts. +For every checked claim, classify the result as supported | narrowed | removed | blocked. +Do not edit files, stage changes, or invent missing behavior. +Return JSON only with keys: scope, filesReviewed, claimsChecked, evidence, unsupportedClaims, confidence, recommendedWorkflow, notes. +Context boundary: +Do not preload AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, or repo-wide policy docs unless the parent explicitly assigns them as evidence. +Use only the parent-assigned shard plus required checkout evidence files. +Return findings only; the parent workflow owns repository-policy interpretation, final decisions, and all writes. diff --git a/.opencode/agents/truth-doc-reviewer.md b/.opencode/agents/truth-doc-reviewer.md new file mode 100644 index 0000000..c24e525 --- /dev/null +++ b/.opencode/agents/truth-doc-reviewer.md @@ -0,0 +1,32 @@ +--- +description: Read-only Truthmark doc reviewer for shape, decision, rationale, and evidence hygiene. +mode: subagent +permission: + edit: deny + task: deny + webfetch: deny + websearch: deny + external_directory: deny + bash: + "*": ask + "git status*": allow + "git diff*": allow + "git log*": allow + "rg *": allow + "grep *": allow +--- + +# Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Manual invocation: @truth-doc-reviewer + +Stay read-only. +Review assigned canonical truth docs for frontmatter, source_of_truth, required template sections, Evidence checked entries, Product Decisions, and Rationale. +Flag README.md files used as behavior truth targets, mixed-owner docs, and shape repairs that should move to Truth Structure. +Do not edit files, stage changes, or rewrite docs. +Return JSON only with keys: scope, filesReviewed, findings, evidence, confidence, recommendedWorkflow, notes. +recommendedWorkflow must be one of: none, truthmark-document, truthmark-structure. +Context boundary: +Do not preload AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, or repo-wide policy docs unless the parent explicitly assigns them as evidence. +Use only the parent-assigned shard plus required checkout evidence files. +Return findings only; the parent workflow owns repository-policy interpretation, final decisions, and all writes. diff --git a/.opencode/agents/truth-doc-writer.md b/.opencode/agents/truth-doc-writer.md new file mode 100644 index 0000000..ce3eb03 --- /dev/null +++ b/.opencode/agents/truth-doc-writer.md @@ -0,0 +1,38 @@ +--- +description: Write-capable Truthmark doc worker for one parent-leased truth-document shard. +mode: subagent +permission: + read: allow + list: allow + grep: allow + glob: allow + edit: + "*": deny + "docs/truth/**": allow + "docs/truthmark/areas.md": allow + "docs/truthmark/areas/**/*.md": allow + task: deny + webfetch: deny + websearch: deny + external_directory: deny + bash: + "*": ask + "git status*": allow + "git diff*": allow +--- + +# Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Manual invocation: @truth-doc-writer + +Write one leased Truthmark truth-document shard assigned by the parent. +Require an explicit write lease before editing. The lease must name workflow, worker, shard, objective, requiredReads, allowedWrites, forbiddenWrites, evidenceRequired, verification, and reportFields. +Read every requiredReads entry directly before editing. +Edit only leased canonical truth docs or leased truth routing files. Do not edit functional code, generated host surfaces, package files, config files, templates, or tests unless they are explicitly leased. +Do not expand your own write scope. If the task needs an off-lease file, stop and report blocked. +Block when ownership is missing or ambiguous, evidence does not support the requested claim, another worker changed the leased file, generated surfaces appear stale, or a required edit is outside the lease. +Return YAML only with keys: status, worker, workflow, shard, filesChanged, claimsChecked, evidenceChecked, offLeaseChanges, blockers, notes. +status must be completed or blocked. +filesChanged must list only files you actually changed. +offLeaseChanges must be empty for completed reports. +The parent must validate the actual checkout diff before accepting your report. diff --git a/.opencode/agents/truth-route-auditor.md b/.opencode/agents/truth-route-auditor.md new file mode 100644 index 0000000..e0cf811 --- /dev/null +++ b/.opencode/agents/truth-route-auditor.md @@ -0,0 +1,33 @@ +--- +description: Read-only Truthmark route auditor for bounded routing and ownership verification. +mode: subagent +permission: + edit: deny + task: deny + webfetch: deny + websearch: deny + external_directory: deny + bash: + "*": ask + "git status*": allow + "git diff*": allow + "git log*": allow + "rg *": allow + "grep *": allow +--- + +# Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Manual invocation: @truth-route-auditor + +Stay read-only. +Audit one bounded Truthmark route, area, or doc shard assigned by the parent. +Inspect .truthmark/config.yml and route files only when they exist; then inspect mapped truth docs and relevant implementation files directly. +Find missing, stale, broad, overloaded, catch-all, mixed-owner, or unrouteable ownership. +Do not edit files, stage changes, or propose broad rewrites. +Return JSON only with keys: scope, filesReviewed, findings, evidence, confidence, recommendedWorkflow, notes. +recommendedWorkflow must be one of: none, truthmark-document, truthmark-structure. +Context boundary: +Do not preload AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, or repo-wide policy docs unless the parent explicitly assigns them as evidence. +Use only the parent-assigned shard plus required checkout evidence files. +Return findings only; the parent workflow owns repository-policy interpretation, final decisions, and all writes. diff --git a/.opencode/skills/truthmark-check/SKILL.md b/.opencode/skills/truthmark-check/SKILL.md new file mode 100644 index 0000000..a81e78f --- /dev/null +++ b/.opencode/skills/truthmark-check/SKILL.md @@ -0,0 +1,28 @@ +--- +name: truthmark-check +description: Use when the user asks to audit repository truth health, routing, ownership, or canonical docs. Not for normal lint/test/typecheck/code-review verification, finish-time Sync, or silently rewriting docs. +argument-hint: Optional area, doc path, or audit focus +user-invocable: true +truthmark-version: 1.6.0 +--- + +# Truthmark Check + +Use this skill to audit repository truth health. + + +Invocations: OpenCode /skill truthmark-check; Codex /truthmark-check or $truthmark-check; Claude Code /truthmark-check; GitHub Copilot /truthmark-check; Gemini CLI /truthmark:check. + +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/areas.md; docs/truthmark/areas/) only when they exist; then inspect canonical docs and relevant implementation directly. +- Report issues and suggested fixes; do not silently rewrite unrelated files. +- Direct checkout inspection is valid even when local tooling is unavailable. +- Read support/procedure.md before auditing details. +- Read support/subagents-and-leases.md before dispatching verifier subagents. +- Read support/report-template.md before the final report. + +Progressive disclosure: +- support/procedure.md +- support/report-template.md +- support/subagents-and-leases.md diff --git a/.opencode/skills/truthmark-check/support/procedure.md b/.opencode/skills/truthmark-check/support/procedure.md new file mode 100644 index 0000000..33b7663 --- /dev/null +++ b/.opencode/skills/truthmark-check/support/procedure.md @@ -0,0 +1,37 @@ +# Truthmark Check Procedure + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +# Truthmark Check + +Use this skill to audit repository truth health. + +Invocations: OpenCode /skill truthmark-check; Codex /truthmark-check or $truthmark-check; Claude Code /truthmark-check; GitHub Copilot /truthmark-check; Gemini CLI /truthmark:check. + +Truth Check is agent-led: + +- inspect .truthmark/config.yml and configured route files only when they exist; then inspect canonical docs and relevant implementation directly +- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. +Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. +- inspect the configured root route index at docs/truthmark/areas.md and relevant child route files under docs/truthmark/areas/ when they exist +- check that current docs describe current code rather than historical plans +- check that route files map code surfaces to canonical truth docs when route files exist +- check for broad, catch-all, index-like, or mixed-owner truth docs and report them as topology issues requiring Truth Structure +- check that canonical behavior docs keep active Product Decisions and Rationale sections +- optionally run truthmark check when local tooling is available +- must not require the truthmark binary; direct inspection is always valid +- report issues and suggested fixes without silently rewriting unrelated files +- if follow-up docs edits are needed for mixed-owner docs, run or recommend Truth Structure before editing +Evidence Gate: +- support each finding and suggested fix with evidence from config, route files, canonical docs, implementation, templates, or tests +- canonical docs are context, not sole proof when implementation conflicts +- remove unsupported findings or mark open questions; validate changed claims if you edit docs + +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md +Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. +Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. +Update Product Decisions and Rationale when a decision changes behavior. diff --git a/.opencode/skills/truthmark-check/support/report-template.md b/.opencode/skills/truthmark-check/support/report-template.md new file mode 100644 index 0000000..e98269e --- /dev/null +++ b/.opencode/skills/truthmark-check/support/report-template.md @@ -0,0 +1,27 @@ +# Truthmark Check Report Template + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Report completion in this shape: + +```md +Truth Check: completed + +Files reviewed: +- docs/truthmark/areas.md + +Issues found: +- none + +Fixes suggested: +- none + +Evidence checked: +- Finding: The root route index is present and maps repository truth owners. + Evidence: docs/truthmark/areas.md:1 + Suggested fix: none + Confidence: high + +Validation: +- truthmark check +``` diff --git a/.opencode/skills/truthmark-check/support/subagents-and-leases.md b/.opencode/skills/truthmark-check/support/subagents-and-leases.md new file mode 100644 index 0000000..e97782a --- /dev/null +++ b/.opencode/skills/truthmark-check/support/subagents-and-leases.md @@ -0,0 +1,10 @@ +# Truthmark Check Subagents And Leases + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +OpenCode subagent mode: +- use automatically when this workflow runs in OpenCode and the parent agent chooses bounded subagent fan-out +- dispatch read-only project subagents only: @truth-route-auditor, @truth-claim-verifier, @truth-doc-reviewer +- workers inspect checkout evidence directly, return structured findings, and must not edit files +- parent supplies bounded evidence shards; workers must not preload host instruction files or repo-wide policy docs unless assigned as evidence +- Parent agent owns the final Truth Check report diff --git a/.opencode/skills/truthmark-document/SKILL.md b/.opencode/skills/truthmark-document/SKILL.md new file mode 100644 index 0000000..751caa5 --- /dev/null +++ b/.opencode/skills/truthmark-document/SKILL.md @@ -0,0 +1,30 @@ +--- +name: truthmark-document +description: Use when the user asks to document existing implemented behavior, or Sync, Check, or Structure finds implemented behavior missing canonical truth. Not for functional-code changes, doc-first implementation, or topology repair that needs Structure. +argument-hint: Optional implemented behavior, API endpoint, route, controller, package, or truth-doc area to document +user-invocable: true +truthmark-version: 1.6.0 +--- + +# Truthmark Document + +Use this skill to document existing implemented behavior when no functional-code changes are required for the task. + + +Invocations: OpenCode /skill truthmark-document; Codex /truthmark-document or $truthmark-document; Claude Code /truthmark-document; GitHub Copilot /truthmark-document; Gemini CLI /truthmark:document. + +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/areas.md; docs/truthmark/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 before dispatching or accepting worker output. +- Read support/report-template.md before the final report. + +Progressive disclosure: +- support/procedure.md +- support/report-template.md +- support/subagents-and-leases.md +- helper-manifest.yml +- support/helper-policy.md diff --git a/.opencode/skills/truthmark-document/helper-manifest.yml b/.opencode/skills/truthmark-document/helper-manifest.yml new file mode 100644 index 0000000..dc05fe5 --- /dev/null +++ b/.opencode/skills/truthmark-document/helper-manifest.yml @@ -0,0 +1,34 @@ +# Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. +helpers: + validate-document-report: + optional: true + runner: truthmark>=1.6.0 + 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>=1.6.0 + 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..53b72b7 --- /dev/null +++ b/.opencode/skills/truthmark-document/support/helper-policy.md @@ -0,0 +1,23 @@ +# Optional Helper CLI Policy + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Optional helper CLI commands may collect deterministic checkout facts or validate artifacts. If the Truthmark CLI is unavailable or too old for a declared helper, continue manually using this procedure and report which helper was skipped. Helper output is derived evidence; it does not override direct checkout inspection, workflow write boundaries, or parent acceptance. + +Runner detection: +- Check the declared Truthmark CLI runner before invoking a helper. +- Invoke helpers through the installed `truthmark validate ... --json` CLI command using argv-style arguments from helper-manifest.yml. +- If unavailable or version-mismatched, 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>=1.6.0; manual fallback: manually validate support/report-template.md required sections and structured Evidence checked entries +- validate-write-lease: optional truthmark>=1.6.0; 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 new file mode 100644 index 0000000..44d8eb3 --- /dev/null +++ b/.opencode/skills/truthmark-document/support/procedure.md @@ -0,0 +1,79 @@ +# Truthmark Document Procedure + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +# Truthmark Document + +Use this skill to document existing implemented behavior when no functional-code changes are required for the task. +Invocations: OpenCode /skill truthmark-document; Codex /truthmark-document or $truthmark-document; Claude Code /truthmark-document; GitHub Copilot /truthmark-document; Gemini CLI /truthmark:document. + +Truth Document is manual and implementation-first: + +- run only when the user explicitly asks to generate or update truth docs for existing behavior, or when Truth Sync, Truth Check, or Truth Structure reports implemented behavior that lacks canonical truth docs +- inspect .truthmark/config.yml and configured route files only when they exist; then inspect existing canonical docs, implementation code, and tests directly +- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. +Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. +- document current implemented behavior; do not invent future behavior or planned endpoints +- may write canonical truth docs and docs/truthmark/areas.md or relevant child route files only +- must not write functional code +- when routing is missing, stale, broad, overloaded, catch-all, or cannot map the behavior to a bounded truth owner, run Truth Structure first when routing repair is safe and in scope +- block and recommend Truth Structure when routing repair is unsafe, ambiguous, or outside the task boundary +- keep feature README.md files as indexes rather than truth-document targets +- create or update bounded leaf truth docs when behavior does not fit an existing leaf doc +- keep behavior truth docs behavior-oriented, not endpoint-oriented, unless the endpoint itself is the behavior boundary +- keep API endpoint details in the nearest contract truth doc when such a doc owns the API contract +- preserve unrelated authored content +Truth-doc ownership gate: +- before editing or relying on the implemented behavior and candidate truth docs, verify each target/source truth doc is a bounded owner for the behavior +- if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it +- if the target doc is broad, mixed-owner, index-like, or the documented behavior spans independent owners, run Truth Structure first when safe and in scope; otherwise block and recommend Truth Structure +- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Blocked reason as applicable +Product Decisions/Rationale preservation gate: +- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions and Rationale sections in every source or touched truth doc +- preserve each current decision and rationale in the bounded owner doc it governs; when splitting, move it to the new owner doc rather than deleting it or leaving it in an index +- remove or narrow a decision or rationale only when checkout evidence shows it is stale or unsupported, and report the exact claim, evidence, and result +- if ownership of a decision or rationale is unclear, block with manual-review files instead of deleting it or guessing +- after the edit, verify every touched truth doc still has Product Decisions and Rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked +Evidence Gate: +- route-first: map the documented behavior to bounded route owners and primary canonical docs +- review new or changed behavior-bearing claims only in touched docs, route ownership, Product Decisions, and Rationale +- support claims with primary checkout evidence: implementation, config, routing, generated templates, schemas, or contract definitions +- tests/examples/canonical docs corroborate; they are not sole proof when implementation conflicts +- remove, narrow, or block unsupported claims +- if no truth doc changed, report why current truth was already sufficient or why documentation was blocked +Repository intelligence artifacts are optional derived context: RepoIndex, RouteMap, ImpactSet, and ContextPack may guide routing, context selection, and verification planning when available. +They do not override checkout evidence, canonical truth docs, route files, or workflow write boundaries. +If unavailable, inspect any present Truthmark config, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated. +When creating or updating a truth doc, inspect the routed truth kind and use the matching `docs/templates/-doc.md` template. +Supported kinds: behavior, contract, architecture, workflow, operations, and test-behavior. +Align existing docs to that template while preserving accurate authored content. +If the template is missing, use Scope, Product Decisions, Rationale, and the kind-specific current-truth section. +Teams may edit the template files under docs/templates/ to define their local truth-doc standards. +Truth-doc shape repair gate: +- Truth Document may restructure only truth docs for the implemented behavior being documented. +- repair shape in place only after the ownership gate confirms the doc is the right bounded owner +- use Truth Structure for ownership splits; do not treat broad or mixed-owner docs as in-place repair work +- repair shape when a narrow edit would make truth worse: missing template sections, stale evidence conflicts, cross-section updates within one owner, or wrong frontmatter/source/headings +- preserve supported claims; remove, narrow, or block unsupported or stale claims +- report docs restructured and why a narrow edit was not sufficient +Maintain architecture docs only for structure-level changes: system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership. +Keep ordinary behavior, endpoints, UI copy, validation rules, and bug fixes in behavior or contract docs unless they change those boundaries. +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md +Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. +Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. +Update Product Decisions and Rationale when a decision changes behavior. +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 +- block on functional code, generated host surfaces, or unrelated diffs caused by document work +- for each write lease, validate the worker report against the actual worker diff, allowedWrites, forbiddenWrites, identity fields, filesChanged, offLeaseChanges, blockers, and required report fields before accepting it +- verify the final report records ownership review, structure requirement, restructure, routing update, or blocked reason when applicable diff --git a/.opencode/skills/truthmark-document/support/report-template.md b/.opencode/skills/truthmark-document/support/report-template.md new file mode 100644 index 0000000..22741ff --- /dev/null +++ b/.opencode/skills/truthmark-document/support/report-template.md @@ -0,0 +1,37 @@ +# Truthmark Document Report Template + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Report completion in this shape: +```md +Truth Document: completed + +Implementation reviewed: +- src/routing/area-resolver.ts + +Ownership reviewed: +- docs/truthmark/areas.md + +Truth docs created: +- docs/truth/contracts.md + +Truth docs updated: +- docs/truth/check-diagnostics.md + +Truth docs restructured: +- docs/truth/check-diagnostics.md + +Routing updated: +- docs/truthmark/areas.md + +Evidence checked: +- Claim: Route resolution behavior is documented in the contracts truth doc. + Evidence: src/routing/area-resolver.ts:14 / docs/truthmark/areas.md:9 + Result: supported + +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-document/support/subagents-and-leases.md b/.opencode/skills/truthmark-document/support/subagents-and-leases.md new file mode 100644 index 0000000..2ee223f --- /dev/null +++ b/.opencode/skills/truthmark-document/support/subagents-and-leases.md @@ -0,0 +1,14 @@ +# Truthmark Document Subagents And Leases + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +OpenCode subagent mode: +- use automatically when this workflow runs in OpenCode and the parent agent chooses bounded subagent fan-out +- dispatch read-only project subagents for verification: @truth-route-auditor, @truth-claim-verifier +- read-only workers inspect checkout evidence directly, return structured findings, and must not edit files +- parent supplies bounded evidence shards; read-only workers must not preload host instruction files or repo-wide policy docs unless assigned as evidence +- dispatch write-capable project subagents only with explicit write leases: @truth-doc-writer +- each write lease must name objective, required reads, allowed writes, forbidden writes, evidence, verification, and report fields +- write workers must stop when a required edit is off-lease and report status, filesChanged, evidence, offLeaseChanges, blockers, and notes +- parent must inspect the actual checkout diff against each lease before accepting a worker report +- Parent agent owns Truth Document acceptance, lease validation, and final report diff --git a/.opencode/skills/truthmark-preview/SKILL.md b/.opencode/skills/truthmark-preview/SKILL.md new file mode 100644 index 0000000..05e0598 --- /dev/null +++ b/.opencode/skills/truthmark-preview/SKILL.md @@ -0,0 +1,27 @@ +--- +name: truthmark-preview +description: Use when the user explicitly asks to preview likely workflow routing, target files, writes, or subagent use before edits. Not for validation, automatic gates, final correctness, or replacing Truth Check. +argument-hint: Optional requested outcome, code area, doc path, or routing question +user-invocable: true +truthmark-version: 1.6.0 +--- + +# Truthmark Preview + +Use this skill only when the user explicitly asks to preview Truthmark routing or workflow choice before edits. + + +Invocations: OpenCode /skill truthmark-preview; Codex /truthmark-preview or $truthmark-preview; Claude Code /truthmark-preview; GitHub Copilot /truthmark-preview; Gemini CLI /truthmark:preview. + +Quick procedure: +- Follow 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/areas.md; docs/truthmark/areas/) only when they exist; then inspect only the truth docs or implementation files needed to preview ownership. +- Truth Preview is read-only; this report is intended, not authorized. +- must not edit files and must not issue write leases; do not run Truth Sync automatically, replace Truth Check, claim final correctness, or mutate code. +- Use optional read-only route-auditor evidence only when it reduces context or clarifies ownership. +- Hand off to the selected workflow after user approval. + +Progressive disclosure: +- support/procedure.md +- support/report-template.md +- support/subagents-and-leases.md diff --git a/.opencode/skills/truthmark-preview/support/procedure.md b/.opencode/skills/truthmark-preview/support/procedure.md new file mode 100644 index 0000000..d419bf2 --- /dev/null +++ b/.opencode/skills/truthmark-preview/support/procedure.md @@ -0,0 +1,43 @@ +# Truthmark Preview Procedure + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Use this skill only when the user explicitly asks to preview Truthmark routing or workflow choice before edits. + +Invocations: OpenCode /skill truthmark-preview; Codex /truthmark-preview or $truthmark-preview; Claude Code /truthmark-preview; GitHub Copilot /truthmark-preview; Gemini CLI /truthmark:preview. + +Truth Preview is read-only. Its report is intended, not authorized. + +Purpose: +- preview the likely Truthmark workflow, route owner, target files, expected write classes, suggested subagent use, and blocking ambiguity before edits happen +- hand off to the selected workflow after user approval +- keep the selector thin so agents can avoid loading or acting through heavier workflows prematurely + +Read: +- .truthmark/config.yml, only when present +- docs/truthmark/areas.md, only when present +- relevant child route files under docs/truthmark/areas/, only when present +- relevant truth docs and implementation files needed to preview ownership +- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. +Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. + +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/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.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..72cf72b --- /dev/null +++ b/.opencode/skills/truthmark-preview/support/report-template.md @@ -0,0 +1,41 @@ +# Truthmark Preview Report Template + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Report completion in this shape: +```md +Truth Preview: completed + +Requested outcome: +- preview likely Truthmark workflow routing before edits + +Likely workflow: +- truthmark-document + +Why this workflow: +- positive trigger: document existing implemented behavior +- negative triggers considered: functional-code change, doc-first implementation, topology repair, truth audit +- forbidden adjacency considered: must not edit functional code + +Likely route owner: +- route file: docs/truthmark/areas.md +- truth doc: docs/truth/example.md +- confidence: medium + +Expected write classes: +- truth docs + +Expected target files: +- docs/truth/example.md + +Suggested subagent use: +- read-only verifiers: truth_route_auditor +- write workers: none in Preview +- leases needed: none in Preview + +Blocking ambiguity: +- none identified in preview + +Handoff: +- Run the selected Truthmark workflow after user approval. +``` 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..07a7a42 --- /dev/null +++ b/.opencode/skills/truthmark-preview/support/subagents-and-leases.md @@ -0,0 +1,10 @@ +# Truthmark Preview Subagents And Leases + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +OpenCode subagent mode: +- use automatically when this workflow runs in OpenCode and the parent agent chooses bounded subagent fan-out +- dispatch read-only project subagents only: @truth-route-auditor +- workers inspect checkout evidence directly, return structured findings, and must not edit files +- parent supplies bounded evidence shards; workers must not preload host instruction files or repo-wide policy docs unless assigned as evidence +- Parent agent owns the final Truth Preview report diff --git a/.opencode/skills/truthmark-realize/SKILL.md b/.opencode/skills/truthmark-realize/SKILL.md new file mode 100644 index 0000000..c91e02d --- /dev/null +++ b/.opencode/skills/truthmark-realize/SKILL.md @@ -0,0 +1,26 @@ +--- +name: truthmark-realize +description: Use when the user explicitly asks to realize Truthmark truth docs into code, including /truthmark-realize, $truthmark-realize, or /truthmark:realize. Not for syncing docs after code changes, documenting existing code, topology repair, or truth audits. +argument-hint: Optional truth doc path, area, or desired code behavior to realize +user-invocable: true +truthmark-version: 1.6.0 +--- + +# Truthmark Realize + +Use this skill only when the user explicitly asks to realize truth docs into code. + + +Invocations: OpenCode /skill truthmark-realize; Codex /truthmark-realize or $truthmark-realize; Claude Code /truthmark-realize; GitHub Copilot /truthmark-realize; Gemini CLI /truthmark:realize. + +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/areas.md; docs/truthmark/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 +- support/report-template.md diff --git a/.opencode/skills/truthmark-realize/support/procedure.md b/.opencode/skills/truthmark-realize/support/procedure.md new file mode 100644 index 0000000..aa9883b --- /dev/null +++ b/.opencode/skills/truthmark-realize/support/procedure.md @@ -0,0 +1,42 @@ +# Truthmark Realize Procedure + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +# Truthmark Realize + +Use this skill only when the user explicitly asks to realize truth docs into code. + +Invocations: OpenCode /skill truthmark-realize; Codex /truthmark-realize or $truthmark-realize; Claude Code /truthmark-realize; GitHub Copilot /truthmark-realize; Gemini CLI /truthmark:realize. + +Truth Realize is doc-first: + +- truth docs lead +- code follows +- Truth Realize never edits the truth docs it is realizing + +Workflow: + +1. Read the updated truth docs named by the user, or infer the relevant docs from configured route files when present. +2. Inspect .truthmark/config.yml and configured route files (docs/truthmark/areas.md; docs/truthmark/areas/) only when they exist; then read tests and the relevant functional code. +3. 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. +Truth-doc ownership gate: +- before editing or relying on source truth docs before writing code, verify each target/source truth doc is a bounded owner for the behavior +- if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it +- if a source truth doc is broad, mixed-owner, index-like, unrouteable, stale, or conflicts with implementation evidence, block before writing code and recommend Truth Structure or Truth Document +- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Blocked reason as applicable +4. Update functional code only so implementation matches bounded, current truth claims from the source docs. +5. Do not edit truth docs or truth routing while realizing those docs. +6. Run relevant tests for the changed code. +7. Report changed code files and verification steps. +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md + +Read and write boundaries: + +- may read truth docs, routing docs, and relevant functional code +- may write functional code only +- must not edit truth docs or truth routing while realizing those docs diff --git a/.opencode/skills/truthmark-realize/support/report-template.md b/.opencode/skills/truthmark-realize/support/report-template.md new file mode 100644 index 0000000..e49dde5 --- /dev/null +++ b/.opencode/skills/truthmark-realize/support/report-template.md @@ -0,0 +1,18 @@ +# Truthmark Realize Report Template + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Report completion in this shape: + +```md +Truth Realize: completed + +Truth docs used: +- docs/truth/authentication/session-timeout.md + +Code updated: +- src/auth/session.ts + +Verification: +- npm test -- auth +``` diff --git a/.opencode/skills/truthmark-structure/SKILL.md b/.opencode/skills/truthmark-structure/SKILL.md new file mode 100644 index 0000000..67f522b --- /dev/null +++ b/.opencode/skills/truthmark-structure/SKILL.md @@ -0,0 +1,27 @@ +--- +name: truthmark-structure +description: Use when routing or truth ownership is missing, stale, broad, overloaded, catch-all, unrouteable, mixed-owner, needs split/repair, or needs new area setup. Not for documenting implemented behavior, syncing a code diff, or realizing docs into code. +argument-hint: Optional area, directory, or routing concern +user-invocable: true +truthmark-version: 1.6.0 +--- + +# Truthmark Structure + +Use this skill to design or repair Truthmark area structure. + + +Invocations: OpenCode /skill truthmark-structure; Codex /truthmark-structure or $truthmark-structure; Claude Code /truthmark-structure; GitHub Copilot /truthmark-structure; Gemini CLI /truthmark:structure. + +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/areas.md; docs/truthmark/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 +- support/report-template.md +- support/subagents-and-leases.md diff --git a/.opencode/skills/truthmark-structure/support/procedure.md b/.opencode/skills/truthmark-structure/support/procedure.md new file mode 100644 index 0000000..9104b33 --- /dev/null +++ b/.opencode/skills/truthmark-structure/support/procedure.md @@ -0,0 +1,109 @@ +# Truthmark Structure Procedure + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Use this skill to design or repair Truthmark area structure. +Invocations: OpenCode /skill truthmark-structure; Codex /truthmark-structure or $truthmark-structure; Claude Code /truthmark-structure; GitHub Copilot /truthmark-structure; Gemini CLI /truthmark:structure. +Truth Structure is agent-native: +- inspect repository layout, current docs, Truthmark config and route files when present, and relevant code directly +- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. +Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. +- inspect the configured root route index at docs/truthmark/areas.md and relevant child route files under docs/truthmark/areas/ when they exist +- define areas by product or behavior ownership, not by mechanical directory mirroring +- create or repair docs/truthmark/areas.md +- create starter truth docs when useful and when they belong in the canonical current-truth surface +- Starter truth docs must use closed YAML frontmatter bounded by opening and closing --- lines; include status, doc_type, last_reviewed, and source_of_truth inside that frontmatter. +- Starter truth docs must include ## Product Decisions and ## Rationale sections. + +When creating or updating a truth doc, inspect the routed truth kind and use the matching `docs/templates/-doc.md` template. +Supported kinds: behavior, contract, architecture, workflow, operations, and test-behavior. +Align existing docs to that template while preserving accurate authored content. +If the template is missing, use Scope, Product Decisions, Rationale, and the kind-specific current-truth section. +Teams may edit the template files under docs/templates/ to define their local truth-doc standards. +- use docs/truth/**, docs/architecture/**, or docs/standards/** for current truth destinations +- use only canonical current-truth destinations for starter truth docs +- keep active Product Decisions and Rationale in the canonical doc that owns the behavior +- preserve unrelated authored content +## New area setup +Use when a user asks to onboard a new code area into Truthmark, a new package, controller, domain, or product area lacks bounded truth ownership, or a new product area needs routing and starter truth docs. +Do: +- inspect the named code area +- infer bounded product or behavior ownership +- choose the owning route when ownership is clear; otherwise propose the route and block for review +- create or update the child route entry or file +- create starter truth docs only where current truth is missing +- report the initial truth boundary +Do not: +- do not edit functional code +- do not perform full behavior documentation unless evidence is inspected and the task explicitly asks for it +- do not patch broad or mixed-owner docs in place +- do not create generic catch-all docs +- do not treat README files as Sync targets +## Topology Governance +Truth Structure owns documentation topology. Do not depend on humans to manually organize docs/truth. Treat the configured truth root as a managed semantic root. +Inspect controllers, routes, handlers, services, packages, tests, existing truth docs, and route files; infer product and domain ownership from behavior boundaries, not from mechanical directory mirroring. +When topology pressure exists, repair structure before creating or extending truth docs. +Truth-doc ownership gate: +- before editing or relying on candidate route owners and current truth docs, verify each target/source truth doc is a bounded owner for the behavior +- if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it +- if a truth doc mixes independent owners, route ownership is broad, or a split is required for bounded ownership, split and reroute into bounded truth docs when safe; otherwise block with manual-review files +- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Blocked reason as applicable +Product Decisions/Rationale preservation gate: +- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions and Rationale sections in every source or touched truth doc +- preserve each current decision and rationale in the bounded owner doc it governs; when splitting, move it to the new owner doc rather than deleting it or leaving it in an index +- remove or narrow a decision or rationale only when checkout evidence shows it is stale or unsupported, and report the exact claim, evidence, and result +- if ownership of a decision or rationale is unclear, block with manual-review files instead of deleting it or guessing +- after the edit, verify every touched truth doc still has Product Decisions and Rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked +Topology pressure signals: +- one area maps broad code such as src/**, app/**, server/**, services/**, or packages/** +- one area maps multiple unrelated controllers, route groups, services, or bounded contexts +- one truth doc owns unrelated behaviors or unrelated endpoint families +- the configured truth root has many direct non-index docs +- a changed controller, route, or service cannot map to a specific behavior doc +- Truth Sync would need to create a new generic truth doc because routing is too broad +- endpoint or controller names reveal domains missing from docs/truthmark/areas/** +Use these review thresholds as guidance: +- more than 10 direct truth docs in one folder +- more than 15 leaf areas in one child route file +- more than 8 truth docs mapped to one area +- more than 5 controllers mapped through one catch-all area +Repair rules: +- split broad, overloaded, or catch-all areas into behavior-owned child route files +- split mixed-owner truth docs into bounded owner docs before adding new behavior claims +- create route files under docs/truthmark/areas/ when a product/domain boundary is clear +- create behavior truth docs under the configured truth root only when behavior lacks a current doc +- README.md files are indexes, not Truth Sync targets +- prefer bounded leaf truth docs at //.md +- keep behavior truth docs behavior-oriented, not endpoint-oriented +- keep API endpoint details in the nearest contract truth doc when such a doc exists +- update routing so future Truth Sync can target small docs +- preserve existing authored docs; move or rewrite only when needed to remove ambiguity +- report Truth docs split when one broad or mixed-owner truth doc becomes multiple bounded docs +Truth-doc shape repair gate: +- Truth Structure may restructure broader routed docs when topology, ownership, or doc-shape repair is already in scope. +- repair shape in place only after the ownership gate confirms the doc is the right bounded owner +- use Truth Structure for ownership splits; do not treat broad or mixed-owner docs as in-place repair work +- repair shape when a narrow edit would make truth worse: missing template sections, stale evidence conflicts, cross-section updates within one owner, or wrong frontmatter/source/headings +- preserve supported claims; remove, narrow, or block unsupported or stale claims +- report docs restructured and why a narrow edit was not sufficient +Evidence Gate: +- apply the Evidence Gate before finishing when Truth Structure writes routed docs, ownership claims, Product Decisions, or Rationale +- support ownership/behavior claims with topology or primary checkout evidence from layout, implementation boundaries, docs, config, route files, tests, templates, schemas, or contracts +- tests/examples/canonical docs corroborate; remove, narrow, or block unsupported claims +Maintain architecture docs only for structure-level changes: system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership. +Keep ordinary behavior, endpoints, UI copy, validation rules, and bug fixes in behavior or contract docs unless they change those boundaries. +- Do not finish topology repair with routed canonical current-truth docs missing Product Decisions or Rationale sections. +- If an existing canonical doc lacks either section, add the missing heading beside Current Behavior with a concise current-state placeholder or active decision. +Portable fallback: +- If this skill surface is unavailable, perform the same workflow directly from committed repository files. +- Do not require the truthmark CLI. +- Inspect .truthmark/config.yml and configured route files only when they exist; then inspect canonical docs and representative implementation code. +- Use a subagent only when the host supports that pattern; otherwise perform the topology repair inline. +Truthmark hierarchy hints: +- Config, when present: .truthmark/config.yml +- Root route index, when present: docs/truthmark/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md +Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. +Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. +Update Product Decisions and Rationale when a decision changes behavior. diff --git a/.opencode/skills/truthmark-structure/support/report-template.md b/.opencode/skills/truthmark-structure/support/report-template.md new file mode 100644 index 0000000..c104da3 --- /dev/null +++ b/.opencode/skills/truthmark-structure/support/report-template.md @@ -0,0 +1,35 @@ +# Truthmark Structure Report Template + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Report completion in this shape: +```md +Truth Structure: completed +Topology reviewed: +- controllers: src/auth/** +- docs root: docs/truth +- route files: docs/truthmark/areas.md +Areas reviewed: +- src/auth/** +Routing updated: +- docs/truthmark/areas.md +Initial truth boundary: +- Area: Authentication +- Code: src/auth/** +- Truth owner: docs/truth/authentication/session.md +- Scope: session behavior only +Truth docs created: +- docs/truth/authentication/session.md +Truth docs split: +- docs/truth/authentication/README.md -> docs/truth/authentication/session.md +Truth docs restructured: +- docs/truth/authentication/README.md +Evidence checked: +- Claim: Session behavior belongs to a dedicated Authentication truth owner. + Evidence: src/auth/** / docs/truthmark/areas.md:7 + Result: supported +Topology decisions: +- Added an Authentication area because session behavior has a distinct code surface and truth owner. +Notes: +- Added an Authentication area for session behavior. +``` diff --git a/.opencode/skills/truthmark-structure/support/subagents-and-leases.md b/.opencode/skills/truthmark-structure/support/subagents-and-leases.md new file mode 100644 index 0000000..fa54016 --- /dev/null +++ b/.opencode/skills/truthmark-structure/support/subagents-and-leases.md @@ -0,0 +1,10 @@ +# Truthmark Structure Subagents And Leases + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +OpenCode subagent mode: +- use automatically when this workflow runs in OpenCode and the parent agent chooses bounded subagent fan-out +- dispatch read-only project subagents only: @truth-route-auditor +- workers inspect checkout evidence directly, return structured findings, and must not edit files +- parent supplies bounded evidence shards; workers must not preload host instruction files or repo-wide policy docs unless assigned as evidence +- Parent agent owns all Truth Structure writes and final topology decisions diff --git a/.opencode/skills/truthmark-sync/SKILL.md b/.opencode/skills/truthmark-sync/SKILL.md new file mode 100644 index 0000000..651ffc3 --- /dev/null +++ b/.opencode/skills/truthmark-sync/SKILL.md @@ -0,0 +1,31 @@ +--- +name: truthmark-sync +description: Use automatically at finish-time after functional code changes, or explicit /truthmark-sync, $truthmark-sync, or /truthmark:sync. Skip docs-only, formatting-only, behavior-preserving renames, missing config, and no-code changes. Not for doc-first realization or manual topology design. +argument-hint: Optional changed-code area, truth-doc area, or sync focus +user-invocable: true +truthmark-version: 1.6.0 +--- + +# Truthmark Sync + +Use this skill automatically before finishing when functional code changed since the last successful Truth Sync. Also run it immediately when the user explicitly invokes Truth Sync. + + +Invocations: OpenCode /skill truthmark-sync; Codex /truthmark-sync or $truthmark-sync; Claude Code /truthmark-sync; GitHub Copilot /truthmark-sync; Gemini CLI /truthmark:sync. + +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/areas.md; docs/truthmark/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 before dispatching or accepting worker output. +- Read support/report-template.md before the final report. + +Progressive disclosure: +- support/procedure.md +- support/report-template.md +- support/subagents-and-leases.md +- helper-manifest.yml +- support/helper-policy.md diff --git a/.opencode/skills/truthmark-sync/helper-manifest.yml b/.opencode/skills/truthmark-sync/helper-manifest.yml new file mode 100644 index 0000000..ce58751 --- /dev/null +++ b/.opencode/skills/truthmark-sync/helper-manifest.yml @@ -0,0 +1,34 @@ +# Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. +helpers: + validate-sync-report: + optional: true + runner: truthmark>=1.6.0 + 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>=1.6.0 + 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..c3d00c7 --- /dev/null +++ b/.opencode/skills/truthmark-sync/support/helper-policy.md @@ -0,0 +1,23 @@ +# Optional Helper CLI Policy + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Optional helper CLI commands may collect deterministic checkout facts or validate artifacts. If the Truthmark CLI is unavailable or too old for a declared helper, continue manually using this procedure and report which helper was skipped. Helper output is derived evidence; it does not override direct checkout inspection, workflow write boundaries, or parent acceptance. + +Runner detection: +- Check the declared Truthmark CLI runner before invoking a helper. +- Invoke helpers through the installed `truthmark validate ... --json` CLI command using argv-style arguments from helper-manifest.yml. +- If unavailable or version-mismatched, 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>=1.6.0; manual fallback: manually validate support/report-template.md and check Evidence checked entries match Claim, indented Evidence, and Result: supported | narrowed | removed | blocked +- validate-write-lease: optional truthmark>=1.6.0; 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 new file mode 100644 index 0000000..a80e050 --- /dev/null +++ b/.opencode/skills/truthmark-sync/support/procedure.md @@ -0,0 +1,88 @@ +# Truthmark Sync Procedure + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Use this skill automatically before finishing when functional code changed since the last successful Truth Sync. Also run it immediately when the user explicitly invokes Truth Sync. +Invocations: OpenCode /skill truthmark-sync; Codex /truthmark-sync or $truthmark-sync; Claude Code /truthmark-sync; GitHub Copilot /truthmark-sync; Gemini CLI /truthmark:sync. +Explicit invocation runs immediately. Later functional-code changes reopen the finish-time requirement, and an earlier explicit run satisfies the finish gate only if no later functional-code changes occur. +Skip when changes are documentation-only, formatting-only, clearly behavior-preserving renames with no truth impact, when no Truthmark config exists yet, or when there are no functional code changes. +Parent workflow: +1. Inspect git status, staged changes, unstaged changes, and untracked files directly. +2. Inspect .truthmark/config.yml and configured route files only when they exist; then inspect relevant canonical docs. +3. Identify functional-code changes and the nearest truth docs or routing repairs. +4. Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path. +Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries. +5. Code verification is parent-owned: follow repository instructions and task context, and report what ran or why it did not run. +6. Dispatch bounded Truth Sync workers only when the host supports subagent dispatch and the acting agent chooses that path; otherwise execute the same sync task inline. +Topology quality gate: +- before updating truth docs, verify the changed code resolves to a specific behavior-owned area and bounded truth owner +- if routing is missing, stale, broad, overloaded, catch-all route only, or cannot map changed code to a bounded truth owner, do not create another generic truth doc +- run Truth Structure before syncing when topology repair is safe and in scope +- block and recommend Truth Structure when topology repair is unsafe, ambiguous, or outside the current task boundary +- report the route files and changed code paths that require structure repair +- README.md files are indexes, not Truth Sync targets +- must not append behavior details to a README.md index +- create or update a bounded leaf truth doc when behavior changes do not fit an existing leaf doc +Truth-doc ownership gate: +- before editing or relying on changed functional files and impacted truth docs, verify each target/source truth doc is a bounded owner for the behavior +- if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it +- if an impacted doc is broad, mixed-owner, index-like, or the update spans independent behavior owners, run Truth Structure before syncing when safe and in scope; otherwise block and recommend Truth Structure +- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Blocked reason as applicable +Product Decisions/Rationale preservation gate: +- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions and Rationale sections in every source or touched truth doc +- preserve each current decision and rationale in the bounded owner doc it governs; when splitting, move it to the new owner doc rather than deleting it or leaving it in an index +- remove or narrow a decision or rationale only when checkout evidence shows it is stale or unsupported, and report the exact claim, evidence, and result +- if ownership of a decision or rationale is unclear, block with manual-review files instead of deleting it or guessing +- after the edit, verify every touched truth doc still has Product Decisions and Rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked +When creating or updating a truth doc, inspect the routed truth kind and use the matching `docs/templates/-doc.md` template. +Supported kinds: behavior, contract, architecture, workflow, operations, and test-behavior. +Align existing docs to that template while preserving accurate authored content. +If the template is missing, use Scope, Product Decisions, Rationale, and the kind-specific current-truth section. +Teams may edit the template files under docs/templates/ to define their local truth-doc standards. +Truth-doc shape repair gate: +- Truth Sync may restructure only truth docs impacted by the current functional-code change. +- repair shape in place only after the ownership gate confirms the doc is the right bounded owner +- use Truth Structure for ownership splits; do not treat broad or mixed-owner docs as in-place repair work +- repair shape when a narrow edit would make truth worse: missing template sections, stale evidence conflicts, cross-section updates within one owner, or wrong frontmatter/source/headings +- preserve supported claims; remove, narrow, or block unsupported or stale claims +- report docs restructured and why a narrow edit was not sufficient +Maintain architecture docs only for structure-level changes: system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership. +Keep ordinary behavior, endpoints, UI copy, validation rules, and bug fixes in behavior or contract docs unless they change those boundaries. +Evidence Gate: +- route-first: map changed functional files to bounded route owners and primary canonical docs +- review new or changed behavior-bearing claims only in touched docs, route ownership, Product Decisions, and Rationale +- support claims with primary checkout evidence: implementation, config, routing, generated templates, schemas, or contract definitions +- tests/examples/canonical docs corroborate; they are not sole proof when implementation conflicts +- remove, narrow, or block unsupported claims +- if no impacted doc changed, report why truth was already current or why sync was skipped +Repository intelligence artifacts are optional derived context: RepoIndex, RouteMap, ImpactSet, and ContextPack may guide routing, context selection, and verification planning when available. +They do not override checkout evidence, canonical truth docs, route files, or workflow write boundaries. +If unavailable, inspect any present Truthmark config, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated. +Optional validation tooling: +- you may run truthmark check when local tooling is available +- do not require the truthmark binary; direct checkout inspection is the canonical path +- optional validation must not replace agent judgment about docs and routing +- update Product Decisions and Rationale when a behavior change comes from a decision change +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/areas.md +- Area route files, when present: docs/truthmark/areas/**/*.md +- Truth docs, when present: docs/truth/**/*.md +Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed. +Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail. +Update Product Decisions and Rationale when a decision changes behavior. +Parent post-sync verification: +- verify only truth docs and leased truth routing files changed during sync +- block on any unrelated diff caused by the sync step +- block if functional code changed during sync +- for each write lease, validate the worker report against the actual worker diff, allowedWrites, forbiddenWrites, identity fields, filesChanged, offLeaseChanges, blockers, and required report fields before accepting it +- validate the final report against the structured Truth Sync report contract, including Claim, indented Evidence, and Result values supported, narrowed, removed, or blocked under Evidence checked +- verify the updated docs correspond to the reviewed changed-code surface +- verify the final report records ownership review, structure requirement, split, restructure, or blocked reason when the ownership gate fired +- blocked outcomes must preserve the working tree as-is: no rollback, no post-block cleanup edits, and manual-review reporting of any remaining files diff --git a/.opencode/skills/truthmark-sync/support/report-template.md b/.opencode/skills/truthmark-sync/support/report-template.md new file mode 100644 index 0000000..9bce186 --- /dev/null +++ b/.opencode/skills/truthmark-sync/support/report-template.md @@ -0,0 +1,41 @@ +# Truthmark Sync Report Template + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +Report completion in this shape: +```md +Truth Sync: completed + +Changed code reviewed: +- src/auth/session.ts + +Ownership reviewed: +- docs/truthmark/areas.md + +Truth docs updated: +- docs/truth/repository/overview.md + +Evidence checked: +- Claim: Session timeout behavior is documented in the mapped repository truth doc. + Evidence: src/auth/session.ts:12 / docs/truthmark/areas.md:11 + Result: supported + +Helper scripts: +- validate-write-lease: skipped, no write lease used + +Notes: +- Updated session timeout behavior. +``` +Blocked report example: +```md +Truth Sync: blocked + +Reason: +- routing repair is not allowed + +Files requiring manual review: +- docs/truthmark/areas.md + +Next action: +- update routing metadata and rerun Truth Sync +``` diff --git a/.opencode/skills/truthmark-sync/support/subagents-and-leases.md b/.opencode/skills/truthmark-sync/support/subagents-and-leases.md new file mode 100644 index 0000000..0cf4c73 --- /dev/null +++ b/.opencode/skills/truthmark-sync/support/subagents-and-leases.md @@ -0,0 +1,14 @@ +# Truthmark Sync Subagents And Leases + +Generated by Truthmark 1.6.0. Rerun truthmark init after upgrades. + +OpenCode subagent mode: +- use automatically when this workflow runs in OpenCode and the parent agent chooses bounded subagent fan-out +- dispatch read-only project subagents for verification: @truth-route-auditor, @truth-claim-verifier +- read-only workers inspect checkout evidence directly, return structured findings, and must not edit files +- parent supplies bounded evidence shards; read-only workers must not preload host instruction files or repo-wide policy docs unless assigned as evidence +- dispatch write-capable project subagents only with explicit write leases: @truth-doc-writer +- each write lease must name objective, required reads, allowed writes, forbidden writes, evidence, verification, and report fields +- write workers must stop when a required edit is off-lease and report status, filesChanged, evidence, offLeaseChanges, blockers, and notes +- parent must inspect the actual checkout diff against each lease before accepting a worker report +- Parent agent owns Truth Sync acceptance, lease validation, and final report diff --git a/.truthmark/config.yml b/.truthmark/config.yml new file mode 100644 index 0000000..82f06d9 --- /dev/null +++ b/.truthmark/config.yml @@ -0,0 +1,38 @@ +version: 1 +platforms: + - codex + - opencode + - github-copilot +docs: + layout: hierarchical + roots: + ai: docs/ai + standards: docs/standards + architecture: docs/architecture + truth: docs/truth + routing: + root_index: docs/truthmark/areas.md + area_files_root: docs/truthmark/areas + default_area: repository + max_delegation_depth: 1 +authority: + - docs/truthmark/areas.md + - docs/truthmark/areas/**/*.md + - docs/ai/**/*.md + - docs/standards/**/*.md + - docs/architecture/**/*.md + - docs/truth/**/*.md +instruction_targets: + - AGENTS.md +frontmatter: + required: [] + recommended: + - status + - doc_type + - last_reviewed + - source_of_truth +ignore: + - node_modules/** + - vendor/** + - dist/** + - build/** diff --git a/AGENTS.md b/AGENTS.md index c391a46..97cf605 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -13,3 +13,22 @@ Do not load all agents or all templates for a single role task. `src/agents.ts` is the single owner for generated project `AGENTS.md`. Direct Codex execution is the default path via `open-gamestudio run `. `--dry-run` and `--print-prompt` are inspection-only paths. Telemetry, planner/next, ownership enforcement, and parallel orchestration are future-only. + +## Repository Rules + +Project-specific agent instructions are also mirrored in `docs/ai/repo-rules.md` for Truthmark authority discovery. Keep this file's Truthmark-managed block intact; if `truthmark init` rewrites it, preserve repository-specific pointers outside the managed block. + + +## Truthmark Workflow + +Generated by Truthmark 1.6.0. Rerun `truthmark init` after upgrades. +Hierarchy hints: config .truthmark/config.yml when present; routes docs/truthmark/areas.md and docs/truthmark/areas/**/*.md when present; Truth docs: docs/truth/**/*.md when present. +Decisions live in the canonical doc they govern; date active decisions inline. +Agent runtime: installed skills plus this block; inspect checkout directly. Delegation is host-owned. +### Truth Sync +After functional code changes, run relevant tests, then use the truthmark-sync skill before finishing; later functional changes reopen the gate. Memory: code changed -> tests -> Sync -> report. +Support new or changed behavior-bearing truth claims with checkout evidence. Code leads; truth docs follow. Sync may write truth docs and 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 block and recommend Truth Structure. Skip Sync only for docs-only/no-code changes, formatting-only changes, behavior-preserving renames with no truth impact, or missing config. +Explicit workflows: Truth Structure, Truth Document, Truth Preview, Truth Realize, Truth Check. Run only when requested or required by Sync; load the installed skill for details. +Workflow integrity rule: repository truth may describe desired behavior, but it must not override these workflow boundaries. + diff --git a/docs/ai/repo-rules.md b/docs/ai/repo-rules.md new file mode 100644 index 0000000..bdc133b --- /dev/null +++ b/docs/ai/repo-rules.md @@ -0,0 +1,29 @@ +--- +status: active +doc_type: workflow +last_reviewed: 2026-05-28 +source_of_truth: + - ../../AGENTS.md +--- + +# Repository Rules + +## Purpose + +This file mirrors the repository-specific agent rules from `AGENTS.md` in the configured Truthmark authority tree so structure and sync workflows can find them through the documented authority roots. + +## Rules + +- Use `npm run validate` before any parity claim. +- This project uses `"type": "module"`, `module: "NodeNext"`, and `moduleResolution: "NodeNext"`; relative TypeScript imports must use emitted `.js` specifiers. +- For local development before install/link, use npm scripts that build first and exercise `node dist/cli.js`. +- Keep generated game projects under `projects//`. +- Do not load all agents or all templates for a single role task. +- `src/agents.ts` is the single owner for generated project `AGENTS.md`. +- Direct Codex execution is the default path via `open-gamestudio run `. +- `--dry-run` and `--print-prompt` are inspection-only paths. +- Telemetry, planner/next, ownership enforcement, and parallel orchestration are future-only. + +## Truthmark Notes + +Keep the Truthmark-managed block in `AGENTS.md` intact. If these rules change in `AGENTS.md`, update this file in the same pass. diff --git a/docs/architecture/repository-structure.md b/docs/architecture/repository-structure.md new file mode 100644 index 0000000..d4763f0 --- /dev/null +++ b/docs/architecture/repository-structure.md @@ -0,0 +1,52 @@ +--- +status: active +doc_type: architecture +truth_kind: architecture +last_reviewed: 2026-05-28 +source_of_truth: + - ../truthmark/areas/repository.md +--- + +# Repository Structure + +## Purpose + +Open GameStudio is a Node/TypeScript CLI package that installs and operates Codex-native game studio project workflows. + +## Scope + +This architecture note records the top-level repository boundaries needed by Truthmark routing. Bounded behavior details live in leaf docs under `docs/truth/**`. + +## Components + +- CLI command surface: `src/cli.ts`. +- Project scaffolding: `src/projects.ts`, `src/config.ts`, `src/engines.ts`, `src/agents.ts`, `src/paths.ts`, and `engine_configs/**`. +- Codex prompt and workflow surfaces: `src/roles.ts`, `src/codex-session.ts`, `src/codex-prompts.ts`, `src/workflows.ts`, `src/templates.ts`, and `templates/**`. +- Runtime/task execution: `src/runner.ts`, `src/tasks.ts`, `src/codex-runtime.ts`, and `src/verification.ts`. +- Validation: `src/validation.ts` plus the package metadata and smoke checks it verifies. + +## Boundaries + +Project scaffolding writes generated project files but does not execute Codex. Codex prompt/workflow modules render instructions but do not persist run state. Runtime/task modules execute or persist Codex runs but consume the prompt surfaces instead of defining role contracts. CLI/validation modules expose and verify the public package contract. + +## Current Structure + +- `src/cli.ts` owns the public CLI command wiring. +- `src/projects.ts`, `src/config.ts`, `src/engines.ts`, `src/agents.ts`, and `src/paths.ts` own project scaffolding and generated project surfaces. +- `src/roles.ts`, `src/codex-session.ts`, `src/codex-prompts.ts`, `src/workflows.ts`, and `src/templates.ts` own Codex role, prompt, workflow, and template surfaces. +- `src/runner.ts`, `src/tasks.ts`, `src/codex-runtime.ts`, and `src/verification.ts` own Codex execution, task persistence, runtime checks, and verification processes. +- `src/validation.ts` owns repository and generated-project validation checks. +- `engine_configs/**` and `templates/**` are package runtime assets. +- `tests/**` mirrors those behavior boundaries with Vitest coverage. + +## Product Decisions + +- Decision (2026-05-28): Route truth by behavior ownership rather than by mechanically mirroring every source file. + +## Rationale + +The package has a small source tree but multiple independent behavioral contracts. Truthmark routing keeps project scaffolding, prompt surfaces, runtime/task execution, and CLI/validation contracts separate so future syncs can update bounded docs instead of a catch-all repository overview. + +## Maintenance Notes + +Update this architecture note when source modules move across the behavior boundaries in `docs/truthmark/areas/repository.md`. diff --git a/docs/standards/default-principles.md b/docs/standards/default-principles.md new file mode 100644 index 0000000..94ee568 --- /dev/null +++ b/docs/standards/default-principles.md @@ -0,0 +1,25 @@ +--- +status: active +doc_type: standard +last_reviewed: 2026-05-03 +source_of_truth: + - README.md +--- + +# Default Principles + +## Scope + +This is a bootstrap standards baseline for repositories that adopt Truthmark. + +## Reusable Defaults + +- Authority order should be explicit. +- Committed repository artifacts are the durable source of truth. +- Each document should have one primary responsibility. +- Each class of fact should have one canonical source. +- Architecture docs describe system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, and generated-surface ownership. +- Do not put ordinary feature behavior in architecture docs. +- Verification should be explicit, and skipped checks should state why. +- Missing, stale, broad, overloaded, or unrouteable documentation topology should be repaired through AI-native structure workflow before agents create more generic truth docs. +- Installed repository workflows should remain usable from committed files even when the Truthmark CLI is unavailable. diff --git a/docs/standards/documentation-governance.md b/docs/standards/documentation-governance.md new file mode 100644 index 0000000..f47a4a9 --- /dev/null +++ b/docs/standards/documentation-governance.md @@ -0,0 +1,23 @@ +--- +status: active +doc_type: standard +last_reviewed: 2026-05-03 +source_of_truth: + - README.md +--- + +# Documentation Governance + +## Core Rules + +- Each document should have one primary responsibility. +- Each class of fact should have one canonical source. +- Current implementation, reusable standards, and future proposals should be stored separately. +- Generated helper output is never canonical truth. +- Architecture docs describe structure and ownership; truth docs describe current product behavior. + +## Truthmark Implications + +- Truth Sync should extend mapped docs first, create an area-local doc second, and create a new area only as a last resort. +- Weak routing produces weak truth maintenance. +- Missing, stale, broad, overloaded, or unrouteable routing should trigger Truth Structure before more generic truth docs are created. diff --git a/docs/templates/architecture-doc.md b/docs/templates/architecture-doc.md new file mode 100644 index 0000000..f7bb9ca --- /dev/null +++ b/docs/templates/architecture-doc.md @@ -0,0 +1,58 @@ +--- +status: active +doc_type: architecture +truth_kind: architecture +last_reviewed: 2026-05-28 +source_of_truth: + - {{source_of_truth}} +--- + +# {{title}} + +## Purpose + +{{purpose}} + +## Scope + +{{scope}} + +## System Role + +{{system_role}} + +## Boundaries + +{{boundaries}} + +## Components + +{{components}} + +## Data And Control Flow + +{{data_and_control_flow}} + +## Ownership + +{{ownership}} + +## Cross-Cutting Constraints + +{{cross_cutting_constraints}} + +## Product Decisions + +{{decision}} + +## Rationale + +{{rationale}} + +## Non-Goals + +{{non_goals}} + +## Maintenance Notes + +{{maintenance_notes}} diff --git a/docs/templates/behavior-doc.md b/docs/templates/behavior-doc.md new file mode 100644 index 0000000..f1a551e --- /dev/null +++ b/docs/templates/behavior-doc.md @@ -0,0 +1,81 @@ +--- +status: active +doc_type: behavior +truth_kind: behavior +last_reviewed: 2026-05-28 +source_of_truth: + - {{source_of_truth}} +--- + +# {{title}} + +## Purpose + + + +{{purpose}} + +## Scope + +{{scope}} + + + +This doc was created from the editable behavior-doc template at {{template_path}}. + +## Current Behavior + + + +{{current_behavior}} + +## Core Rules + + + +{{core_rules}} + +## Flows And States + + + +{{flows_and_states}} + +## Contracts + + + +{{contracts}} + +## Product Decisions + + + +{{decision}} + +## Rationale + + + +{{rationale}} + +## Non-Goals + + + +{{non_goals}} + +## Maintenance Notes + + + +{{maintenance_notes}} diff --git a/docs/templates/contract-doc.md b/docs/templates/contract-doc.md new file mode 100644 index 0000000..e984a80 --- /dev/null +++ b/docs/templates/contract-doc.md @@ -0,0 +1,58 @@ +--- +status: active +doc_type: contract +truth_kind: contract +last_reviewed: 2026-05-28 +source_of_truth: + - {{source_of_truth}} +--- + +# {{title}} + +## Purpose + +{{purpose}} + +## Scope + +{{scope}} + +## Contract Surface + +{{contract_surface}} + +## Inputs + +{{inputs}} + +## Outputs + +{{outputs}} + +## Errors And Diagnostics + +{{errors_and_diagnostics}} + +## Compatibility Rules + +{{compatibility_rules}} + +## Versioning And Migration + +{{versioning_and_migration}} + +## Product Decisions + +{{decision}} + +## Rationale + +{{rationale}} + +## Non-Goals + +{{non_goals}} + +## Maintenance Notes + +{{maintenance_notes}} diff --git a/docs/templates/operations-doc.md b/docs/templates/operations-doc.md new file mode 100644 index 0000000..42a996a --- /dev/null +++ b/docs/templates/operations-doc.md @@ -0,0 +1,58 @@ +--- +status: active +doc_type: behavior +truth_kind: operations +last_reviewed: 2026-05-28 +source_of_truth: + - {{source_of_truth}} +--- + +# {{title}} + +## Purpose + +{{purpose}} + +## Scope + +{{scope}} + +## Operational Surface + +{{operational_surface}} + +## Runtime Topology + +{{runtime_topology}} + +## Configuration + +{{configuration}} + +## Permissions + +{{permissions}} + +## Deployment And Rollback + +{{deployment_and_rollback}} + +## Availability And Observability + +{{availability_and_observability}} + +## Product Decisions + +{{decision}} + +## Rationale + +{{rationale}} + +## Non-Goals + +{{non_goals}} + +## Maintenance Notes + +{{maintenance_notes}} diff --git a/docs/templates/test-behavior-doc.md b/docs/templates/test-behavior-doc.md new file mode 100644 index 0000000..1717bc7 --- /dev/null +++ b/docs/templates/test-behavior-doc.md @@ -0,0 +1,58 @@ +--- +status: active +doc_type: behavior +truth_kind: test-behavior +last_reviewed: 2026-05-28 +source_of_truth: + - {{source_of_truth}} +--- + +# {{title}} + +## Purpose + +{{purpose}} + +## Scope + +{{scope}} + +## Test Surface + +{{test_surface}} + +## Fixtures And Data Model + +{{fixtures_and_data_model}} + +## Execution Model + +{{execution_model}} + +## Assertions And Invariants + +{{assertions_and_invariants}} + +## Isolation Rules + +{{isolation_rules}} + +## Reporting And Failure Semantics + +{{reporting_and_failure_semantics}} + +## Product Decisions + +{{decision}} + +## Rationale + +{{rationale}} + +## Non-Goals + +{{non_goals}} + +## Maintenance Notes + +{{maintenance_notes}} diff --git a/docs/templates/workflow-doc.md b/docs/templates/workflow-doc.md new file mode 100644 index 0000000..64613fe --- /dev/null +++ b/docs/templates/workflow-doc.md @@ -0,0 +1,58 @@ +--- +status: active +doc_type: behavior +truth_kind: workflow +last_reviewed: 2026-05-28 +source_of_truth: + - {{source_of_truth}} +--- + +# {{title}} + +## Purpose + +{{purpose}} + +## Scope + +{{scope}} + +## Triggers + +{{triggers}} + +## Inputs + +{{inputs}} + +## Execution Model + +{{execution_model}} + +## Steps + +{{steps}} + +## State, Retry, And Failure Behavior + +{{state_retry_and_failure_behavior}} + +## Outputs + +{{outputs}} + +## Product Decisions + +{{decision}} + +## Rationale + +{{rationale}} + +## Non-Goals + +{{non_goals}} + +## Maintenance Notes + +{{maintenance_notes}} diff --git a/docs/truth/README.md b/docs/truth/README.md new file mode 100644 index 0000000..d0f3d21 --- /dev/null +++ b/docs/truth/README.md @@ -0,0 +1,13 @@ +--- +status: active +doc_type: index +last_reviewed: 2026-05-28 +source_of_truth: + - ../truthmark/areas.md +--- + +# Truth Docs + +This directory is an index for current truth docs organized by the configured Truthmark hierarchy. + +README.md files are indexes, not Truth Sync targets. Keep bounded truth in leaf docs under `/.md`. diff --git a/docs/truth/codex/roles-and-workflows.md b/docs/truth/codex/roles-and-workflows.md new file mode 100644 index 0000000..5de672c --- /dev/null +++ b/docs/truth/codex/roles-and-workflows.md @@ -0,0 +1,66 @@ +--- +status: active +doc_type: behavior +truth_kind: behavior +last_reviewed: 2026-05-28 +source_of_truth: + - ../../truthmark/areas/repository.md +--- + +# Codex Roles And Workflows + +## Purpose + +Codex roles and workflows provide the role-specific prompt contracts, context boundaries, templates, and render-only workflow shortcuts that make Open GameStudio a Codex-native game-development layer. + +## Scope + +This bounded leaf truth doc owns studio role IDs, role package metadata, Codex session prompt rendering, workflow registry entries, template registry behavior, and generated workflow prompt content. It does not own process execution, task persistence, package installation, or generated project initialization side effects. + +This doc was created from the editable behavior-doc template at docs/templates/behavior-doc.md. + +## Current Behavior + +- The canonical studio role roster is defined by hyphenated Codex-native role IDs such as `producer`, `gameplay-programmer`, `qa-playtester`, and `studio-orchestrator`. +- Each role package contains a display name, system prompt, context strategy, expected outputs, handoff wording, and a review checklist. +- Codex session prompts render the role display name, role ID, phase, project root, objective, engine context, context files, expected outputs, verification command, review checklist, and completion-report instructions. +- The workflow registry defines vertical-slice, bugfix, playtest, market-analysis, analytics-setup, design-spec, game-feel-tuning, art-direction, ui-ux-review, production-milestone, handoff, review, and ship-check workflow prompts. +- Selected workflows include CLI aliases for render-only shortcuts, including market, analytics, design-spec, feel-review, art-direction, ui-review, milestone, and handoff. +- Template selection is task- and role-sensitive; template files are read from package assets and embedded into applicable workflow prompts. + +## Core Rules + +- Unknown role errors must point users toward Codex-native hyphenated role IDs rather than legacy agent names. +- Prompt rendering must include the role display name and project/session metadata needed by Codex to operate without hidden state. +- Templates that require Markdown sections must have non-empty required sections; the project config template must parse as JSON. +- Workflow shortcuts render prompts; they do not imply hidden parallel orchestration or future planner behavior. + +## Flows And States + +- Workflow prompt flow: read project engine from `.codex/studio.json`, look up the workflow registry entry, create a Codex studio session for the owning role and phase, render the standard prompt, then append any workflow template bodies. +- Template selection flow: match role and task text against bounded keyword rules and return only matching template IDs. + +## Contracts + +- Role IDs are stable strings exported from `src/roles.ts` and reused by config validation, project state, prompt generation, workflow routing, and task creation. +- Workflow IDs map to `.codex/workflows/.md` files and expected context-file lists. +- Template IDs map to package template paths, role applicability, tags, and required-section validation. + +## Product Decisions + +- Decision (2026-05-28): Use Codex-native hyphenated role IDs as the canonical user- and project-facing role contract. +- Decision (2026-05-28): Keep workflow shortcuts render-only for this pass; future planner, next, telemetry, ownership enforcement, and parallel orchestration surfaces remain hidden. + +## Rationale + +Role and workflow prompt generation is the user-facing contract that turns a generic Codex CLI into a specialized game-studio workflow. Keeping it render-only and declarative avoids overclaiming automation that is not implemented while still making the workflow packages inspectable and testable. + +## Non-Goals + +- This doc does not own whether Codex is installed or authenticated. +- This doc does not own task lifecycle mutations or verification command execution. + +## Maintenance Notes + +- Update this doc with changes to `src/roles.ts`, `src/codex-session.ts`, `src/codex-prompts.ts`, `src/workflows.ts`, `src/templates.ts`, or `templates/**`. +- Relevant verification includes role, Codex prompt/session, workflow, template, and functionality-gap tests. diff --git a/docs/truth/codex/runtime-and-tasks.md b/docs/truth/codex/runtime-and-tasks.md new file mode 100644 index 0000000..dd6b133 --- /dev/null +++ b/docs/truth/codex/runtime-and-tasks.md @@ -0,0 +1,86 @@ +--- +status: active +doc_type: behavior +truth_kind: workflow +last_reviewed: 2026-05-28 +source_of_truth: + - ../../truthmark/areas/repository.md +--- + +# Runtime And Task Execution + +## Purpose + +Runtime and task execution connect prepared Codex Game Studio prompts to the Codex CLI, preserve explicit task state, and run bounded verification/review/fix loops without hidden orchestration. + +## Scope + +This bounded leaf truth doc owns `run` preparation and execution, Codex command construction and availability checks, task-store persistence, review/fix lifecycle behavior, sandbox policy, and structured verification command execution. It does not own role prompt content, project scaffolding, or public CLI help wording except where runtime behavior depends on those options. + +## Triggers + +- A user invokes `run ... --project ` to render or execute a role prompt. +- A user creates or runs a file-backed task through `task create` or `task run`. +- A run includes structured verification, review, or bounded fix-pass options. + +## Inputs + +- A valid project root with `.codex/studio.json`. +- A studio role ID or task ID. +- A non-empty task/objective. +- Optional included artifacts, verification command/args, review flag, fix flag, and max fix-pass count. + +## Execution Model + +- `prepareRun` resolves the project, reads studio state, renders a Codex prompt, computes prompt and metadata cache paths, and builds Codex execution commands. +- `--print-prompt` and `--dry-run` are inspection-only paths and do not write prompt cache, metadata, task state, or run directories. +- Non-dry runs write prompt and metadata before executing Codex. +- Implementation and fix passes use a workspace-write Codex sandbox; review passes use a read-only Codex sandbox. +- Task runs mutate task status only for non-dry execution. + +## Steps + +1. Validate the requested role/task and project state. +2. Build context-file lists and render the Codex prompt. +3. For non-dry runs, write the prompt and metadata cache under `.codex/runs/`. +4. Check Codex availability before execution through the CLI path. +5. Execute the implementation prompt. +6. Run verification when configured. +7. Run review when requested and verification passes or is absent. +8. Run bounded fix passes when requested and blockers remain. +9. Report final status as `done` or `blocked`; task runs also persist final task status. + +## State, Retry, And Failure Behavior + +- Task stores live at `.codex/tasks.json` with schema version 1 and unique `task-###` IDs. +- `task create` requires a valid studio project before writing task state. +- Task statuses are `ready`, `running`, `blocked`, and `done`. +- Verification commands are spawned with bounded stdout/stderr capture, a default timeout, SIGTERM on timeout, and SIGKILL after the configured grace period. +- Malformed review JSON, non-zero Codex execution, failed verification, or review blockers leave the lifecycle blocked unless a later bounded fix pass clears the blocker. + +## Outputs + +- Dry-run output lists context files and the Codex command without writing cache files. +- Print-prompt output is the deterministic prompt body. +- Non-dry run output reports implementation, verification, review, fix-pass, and final-status summaries. +- Task creation prints the new task ID. + +## Product Decisions + +- Decision (2026-05-28): Make dry-run and print-prompt non-mutating inspection paths. +- Decision (2026-05-28): Force review prompts through a read-only sandbox while implementation/fix prompts retain workspace-write behavior. +- Decision (2026-05-28): Require a valid project before task-store writes. + +## Rationale + +Codex execution is intentionally explicit: users can inspect prompts without side effects, then run bounded implementation/review/fix loops with visible cache paths and verification output. Read-only review protects the review contract from accidentally becoming a second implementation pass. + +## Non-Goals + +- This workflow does not implement hidden parallel execution, telemetry, ownership enforcement, or a planner/next queue. +- This workflow does not choose role prompt content; it consumes the role and workflow surfaces owned by the Codex roles truth doc. + +## Maintenance Notes + +- Update this doc with changes to `src/runner.ts`, `src/tasks.ts`, `src/codex-runtime.ts`, or `src/verification.ts`. +- Relevant verification includes runner, task, verification, Codex runtime, and lifecycle-focused tests. diff --git a/docs/truth/contracts/cli-and-validation.md b/docs/truth/contracts/cli-and-validation.md new file mode 100644 index 0000000..d5bec55 --- /dev/null +++ b/docs/truth/contracts/cli-and-validation.md @@ -0,0 +1,75 @@ +--- +status: active +doc_type: contract +truth_kind: contract +last_reviewed: 2026-05-28 +source_of_truth: + - ../../truthmark/areas/repository.md +--- + +# CLI And Validation Contracts + +## Purpose + +The CLI and validation contracts define the public `open-gamestudio` command surface, package entrypoints, hard-failing validation checks, and future-surface guardrails for this repository. + +## Scope + +This bounded leaf truth doc owns the repository CLI command contract, package scripts/bin/files expectations, validation check behavior, and documented public-surface claims. It does not own the internal details of project scaffolding, role prompt content, or Codex runtime lifecycle beyond the options exposed through the CLI. + +## Contract Surface + +- Package name: `open-gamestudio`. +- Package bin: `open-gamestudio` points to `./dist/cli.js`. +- Primary scripts include `build`, `typecheck`, `test`, `validate`, `init`, `manage`, and `templates`. +- Public CLI command groups include initialization/status commands, template discovery, role run execution, file-backed tasks, and render-only workflow shortcuts. +- Repository validation is exposed through `open-gamestudio validate` and the `npm run validate` script. + +## Inputs + +- CLI options and arguments parsed by Commander in `src/cli.ts`. +- Repository files checked by validation, including package metadata, source files, templates, generated build output, engine configs, and optional project paths. +- Project validation input when `--project ` is supplied. + +## Outputs + +- CLI commands print human-readable status, prompt, task, validation, or workflow output. +- Validation emits one line per check in `STATUS id: message (path)` shape and exits non-zero when any check fails. +- Package smoke validation builds and exercises the packed package bin and template loading behavior. + +## Errors And Diagnostics + +- Unknown roles fail with a message naming Codex-native hyphenated role IDs. +- Missing package scripts, missing package bin/files, missing source files, unavailable Codex CLI, invalid templates, exposed future surfaces, missing build output, and package smoke failures are validation failures. +- Project validation fails for invalid `.codex/studio.json`, missing generated project files, missing workflow/prompt sections, forbidden generated surfaces, or read-only command mutations. + +## Compatibility Rules + +- 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. +- Packaged files must include `dist/`, `engine_configs/`, and `templates/` so the installed bin can load runtime assets. +- Future-only command surfaces such as `next`, `telemetry`, `parallel`, and ownership enforcement must stay hidden until implemented intentionally. + +## Versioning And Migration + +- Current package version is managed in `package.json` and rendered by Commander. +- CLI contract changes should update README claims, validation expectations, and tests in the same change. + +## Product Decisions + +- Decision (2026-05-28): Keep `validate` as the hard-failing parity gate before claiming repository or project readiness. +- Decision (2026-05-28): Document and test that future planner/telemetry/parallel/ownership surfaces are not exposed by the CLI. + +## Rationale + +The CLI is the stable integration boundary for humans, package installs, and generated project smoke checks. Validation makes those claims executable so prompt-surface and packaging drift fail before release or parity claims. + +## Non-Goals + +- This contract does not document every generated prompt body; those belong to the Codex role/workflow truth doc. +- This contract does not define npm audit remediation policy. + +## Maintenance Notes + +- Update this doc with changes to `src/cli.ts`, `src/validation.ts`, package metadata, README public command claims, or validation check IDs. +- Relevant verification includes `npm run validate`, CLI help smoke checks, validation tests, package dry-run/smoke checks, and future-surface guard tests. diff --git a/docs/truth/repository/README.md b/docs/truth/repository/README.md new file mode 100644 index 0000000..00f9f5a --- /dev/null +++ b/docs/truth/repository/README.md @@ -0,0 +1,18 @@ +--- +status: active +doc_type: index +last_reviewed: 2026-05-28 +source_of_truth: + - ../../truthmark/areas/repository.md +--- + +# Repository Truth Docs + +This directory is reserved for repository-level truth indexes. + +README.md files are indexes, not Truth Sync targets. Current bounded truth lives in: + +- [Project Scaffolding](../projects/project-scaffolding.md) +- [Codex Roles And Workflows](../codex/roles-and-workflows.md) +- [Runtime And Task Execution](../codex/runtime-and-tasks.md) +- [CLI And Validation Contracts](../contracts/cli-and-validation.md) diff --git a/docs/truthmark/areas.md b/docs/truthmark/areas.md new file mode 100644 index 0000000..bdfff52 --- /dev/null +++ b/docs/truthmark/areas.md @@ -0,0 +1,28 @@ +--- +status: active +doc_type: route-index +last_reviewed: 2026-05-28 +source_of_truth: + - ../../.truthmark/config.yml +--- + +# Truthmark Areas + +## Repository + +Area files: +- docs/truthmark/areas/repository.md + +Code surface: +- src/** +- tests/** +- engine_configs/** +- templates/** +- package.json +- package-lock.json +- README.md +- AGENTS.md + +Update truth when: +- repository CLI behavior, Codex prompt/workflow behavior, generated project layout, validation, packaging, or task execution changes +- code or tests move between bounded behavior owners diff --git a/docs/truthmark/areas/repository.md b/docs/truthmark/areas/repository.md new file mode 100644 index 0000000..e201c8d --- /dev/null +++ b/docs/truthmark/areas/repository.md @@ -0,0 +1,101 @@ +--- +status: active +doc_type: area-route +last_reviewed: 2026-05-28 +source_of_truth: + - ../../../.truthmark/config.yml +--- + +# Repository Areas + +## Project Scaffolding + +Truth documents: +```yaml +truth_documents: + - path: docs/truth/projects/project-scaffolding.md + kind: behavior +``` + +Code surface: +- src/projects.ts +- src/config.ts +- src/engines.ts +- src/agents.ts +- src/paths.ts +- engine_configs/** +- tests/project-workflow.test.ts +- tests/agents-templates.test.ts +- tests/engine-system.test.ts +- tests/codex-context-files.test.ts + +Update truth when: +- project initialization, generated project state, engine folder creation, role prompt materialization, or status/resume/freeze behavior changes +- generated project AGENTS.md or base prompt package ownership changes + +## Codex Role And Workflow Surfaces + +Truth documents: +```yaml +truth_documents: + - path: docs/truth/codex/roles-and-workflows.md + kind: behavior +``` + +Code surface: +- src/roles.ts +- src/codex-session.ts +- src/codex-prompts.ts +- src/workflows.ts +- src/templates.ts +- templates/** +- tests/roles.test.ts +- tests/codex-session.test.ts +- tests/codex-prompts.test.ts +- tests/functionality-gap-pass.test.ts + +Update truth when: +- studio role IDs, role contracts, workflow registry entries, prompt rendering, context strategies, or template selection rules change +- Codex-native workflow shortcuts or generated workflow prompt contents change + +## Runtime And Task Execution + +Truth documents: +```yaml +truth_documents: + - path: docs/truth/codex/runtime-and-tasks.md + kind: workflow +``` + +Code surface: +- src/runner.ts +- src/tasks.ts +- src/codex-runtime.ts +- src/verification.ts +- tests/runner.test.ts +- tests/tasks.test.ts +- tests/verification.test.ts +- tests/codex-runtime.test.ts + +Update truth when: +- Codex execution, dry-run or print-prompt mutation rules, review/fix lifecycle behavior, task-store persistence, or verification timeout behavior changes +- task status transitions or Codex sandbox policies change + +## CLI And Validation Contracts + +Truth documents: +```yaml +truth_documents: + - path: docs/truth/contracts/cli-and-validation.md + kind: contract +``` + +Code surface: +- src/cli.ts +- src/validation.ts +- tests/validation.test.ts +- tests/functionality-gap-pass.test.ts + +Update truth when: +- public CLI commands, package scripts/bin/files, validation check IDs, documentation claims, or package dependency contracts change +- future-only surfaces become exposed or are intentionally kept hidden diff --git a/package-lock.json b/package-lock.json index 9e027c9..bc18e62 100644 --- a/package-lock.json +++ b/package-lock.json @@ -17,6 +17,7 @@ }, "devDependencies": { "@types/node": "^20.19.25", + "truthmark": "^1.6.0", "tsx": "^4.20.6", "typescript": "^5.9.3", "vitest": "^1.6.1" @@ -459,6 +460,41 @@ "integrity": "sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og==", "dev": true }, + "node_modules/@nodelib/fs.scandir": { + "version": "2.1.5", + "resolved": "https://registry.npmjs.org/@nodelib/fs.scandir/-/fs.scandir-2.1.5.tgz", + "integrity": "sha512-vq24Bq3ym5HEQm2NKCr3yXDwjc7vTsEThRDnkp2DK9p1uqLR+DHurm/NOTo0KG7HYHU7eppKZj3MyqYuMBf62g==", + "dev": true, + "dependencies": { + "@nodelib/fs.stat": "2.0.5", + "run-parallel": "^1.1.9" + }, + "engines": { + "node": ">= 8" + } + }, + "node_modules/@nodelib/fs.stat": { + "version": "2.0.5", + "resolved": "https://registry.npmjs.org/@nodelib/fs.stat/-/fs.stat-2.0.5.tgz", + "integrity": "sha512-RkhPPp2zrqDAQA/2jNhnztcPAlv64XdhIp7a7454A5ovI7Bukxgt7MX7udwAu3zg1DcpPU0rz3VV1SeaqvY4+A==", + "dev": true, + "engines": { + "node": ">= 8" + } + }, + "node_modules/@nodelib/fs.walk": { + "version": "1.2.8", + "resolved": "https://registry.npmjs.org/@nodelib/fs.walk/-/fs.walk-1.2.8.tgz", + "integrity": "sha512-oGB+UxlgWcgQkgwo8GcEGwemoTFt3FIO9ababBmaGwXIoBKZ+GTy0pP185beGg7Llih/NSHSV2XAs1lnznocSg==", + "dev": true, + "dependencies": { + "@nodelib/fs.scandir": "2.1.5", + "fastq": "^1.6.0" + }, + "engines": { + "node": ">= 8" + } + }, "node_modules/@rollup/rollup-android-arm-eabi": { "version": "4.60.4", "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.60.4.tgz", @@ -784,18 +820,60 @@ "win32" ] }, + "node_modules/@sec-ant/readable-stream": { + "version": "0.4.1", + "resolved": "https://registry.npmjs.org/@sec-ant/readable-stream/-/readable-stream-0.4.1.tgz", + "integrity": "sha512-831qok9r2t8AlxLko40y2ebgSDhenenCatLVeW/uBtnHPyhHOvG0C7TvfgecV+wHzIm5KUICgzmVpWS+IMEAeg==", + "dev": true + }, "node_modules/@sinclair/typebox": { "version": "0.27.10", "resolved": "https://registry.npmjs.org/@sinclair/typebox/-/typebox-0.27.10.tgz", "integrity": "sha512-MTBk/3jGLNB2tVxv6uLlFh1iu64iYOQ2PbdOSK3NW8JZsmlaOh2q6sdtKowBhfw8QFLmYNzTW4/oK4uATIi6ZA==", "dev": true }, + "node_modules/@sindresorhus/merge-streams": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/@sindresorhus/merge-streams/-/merge-streams-4.0.0.tgz", + "integrity": "sha512-tlqY9xq5ukxTUZBmoOp+m61cqwQD5pHJtFY3Mn8CA8ps6yghLH/Hw8UPdqg4OLmFW3IFlcXnQNmo/dh8HzXYIQ==", + "dev": true, + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/@types/debug": { + "version": "4.1.13", + "resolved": "https://registry.npmjs.org/@types/debug/-/debug-4.1.13.tgz", + "integrity": "sha512-KSVgmQmzMwPlmtljOomayoR89W4FynCAi3E8PPs7vmDVPe84hT+vGPKkJfThkmXs0x0jAaa9U8uW8bbfyS2fWw==", + "dev": true, + "dependencies": { + "@types/ms": "*" + } + }, "node_modules/@types/estree": { "version": "1.0.9", "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.9.tgz", "integrity": "sha512-GhdPgy1el4/ImP05X05Uw4cw2/M93BCUmnEvWZNStlCzEKME4Fkk+YpoA5OiHNQmoS7Cafb8Xa3Pya8m1Qrzeg==", "dev": true }, + "node_modules/@types/mdast": { + "version": "4.0.4", + "resolved": "https://registry.npmjs.org/@types/mdast/-/mdast-4.0.4.tgz", + "integrity": "sha512-kGaNbPh1k7AFzgpud/gMdvIm5xuECykRR+JnWKQno9TAXVa6WIVCGTPvYGekIDL4uwCZQSYbUxNBSb1aUo79oA==", + "dev": true, + "dependencies": { + "@types/unist": "*" + } + }, + "node_modules/@types/ms": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/@types/ms/-/ms-2.1.0.tgz", + "integrity": "sha512-GsCCIZDE/p3i96vtEqx+7dBUGXrc7zeSK3wwPHIaRThS+9OhWIXRqzs4d6k1SVU8g91DrNRWxWUGhp5KXQb2VA==", + "dev": true + }, "node_modules/@types/node": { "version": "20.19.41", "resolved": "https://registry.npmjs.org/@types/node/-/node-20.19.41.tgz", @@ -805,6 +883,12 @@ "undici-types": "~6.21.0" } }, + "node_modules/@types/unist": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/@types/unist/-/unist-3.0.3.tgz", + "integrity": "sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==", + "dev": true + }, "node_modules/@vitest/expect": { "version": "1.6.1", "resolved": "https://registry.npmjs.org/@vitest/expect/-/expect-1.6.1.tgz", @@ -898,6 +982,22 @@ "node": ">=0.4.0" } }, + "node_modules/ajv": { + "version": "8.20.0", + "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.20.0.tgz", + "integrity": "sha512-Thbli+OlOj+iMPYFBVBfJ3OmCAnaSyNn4M1vz9T6Gka5Jt9ba/HIR56joy65tY6kx/FCF5VXNB819Y7/GUrBGA==", + "dev": true, + "dependencies": { + "fast-deep-equal": "^3.1.3", + "fast-uri": "^3.0.1", + "json-schema-traverse": "^1.0.0", + "require-from-string": "^2.0.2" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/epoberezkin" + } + }, "node_modules/ansi-styles": { "version": "5.2.0", "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-5.2.0.tgz", @@ -910,6 +1010,15 @@ "url": "https://github.com/chalk/ansi-styles?sponsor=1" } }, + "node_modules/argparse": { + "version": "1.0.10", + "resolved": "https://registry.npmjs.org/argparse/-/argparse-1.0.10.tgz", + "integrity": "sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg==", + "dev": true, + "dependencies": { + "sprintf-js": "~1.0.2" + } + }, "node_modules/assertion-error": { "version": "1.1.0", "resolved": "https://registry.npmjs.org/assertion-error/-/assertion-error-1.1.0.tgz", @@ -919,6 +1028,28 @@ "node": "*" } }, + "node_modules/bail": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/bail/-/bail-2.0.2.tgz", + "integrity": "sha512-0xO6mYd7JB2YesxDKplafRpsiOzPt9V02ddPCLbY1xYGPOX24NTyN50qnUxgCPcSoYMhKpAuBTjQoRZCAkUDRw==", + "dev": true, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/braces": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/braces/-/braces-3.0.3.tgz", + "integrity": "sha512-yQbXgO/OSZVD2IsiLlro+7Hf6Q18EJrKSEsdoMzKePKXct3gvD8oLcOQdIzGupr5Fj+EDe8gO/lxc1BzfMpxvA==", + "dev": true, + "dependencies": { + "fill-range": "^7.1.1" + }, + "engines": { + "node": ">=8" + } + }, "node_modules/cac": { "version": "6.7.14", "resolved": "https://registry.npmjs.org/cac/-/cac-6.7.14.tgz", @@ -946,6 +1077,16 @@ "node": ">=4" } }, + "node_modules/character-entities": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/character-entities/-/character-entities-2.0.2.tgz", + "integrity": "sha512-shx7oQ0Awen/BRIdkjkvz54PnEEI/EjwXDSIZp86/KKdbafHh1Df/RYGBhn4hbe2+uKC9FnT5UCEdyPz3ai9hQ==", + "dev": true, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, "node_modules/check-error": { "version": "1.0.3", "resolved": "https://registry.npmjs.org/check-error/-/check-error-1.0.3.tgz", @@ -1003,6 +1144,19 @@ } } }, + "node_modules/decode-named-character-reference": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/decode-named-character-reference/-/decode-named-character-reference-1.3.0.tgz", + "integrity": "sha512-GtpQYB283KrPp6nRw50q3U9/VfOutZOe103qlN7BPP6Ad27xYnOIWv4lPzo8HCAL+mMZofJ9KEy30fq6MfaK6Q==", + "dev": true, + "dependencies": { + "character-entities": "^2.0.0" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, "node_modules/deep-eql": { "version": "4.1.4", "resolved": "https://registry.npmjs.org/deep-eql/-/deep-eql-4.1.4.tgz", @@ -1015,6 +1169,28 @@ "node": ">=6" } }, + "node_modules/dequal": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/dequal/-/dequal-2.0.3.tgz", + "integrity": "sha512-0je+qPKHEMohvfRTCEo3CrPG6cAzAYgmzKyxRiYSSDkS6eGJdyVJm7WaYA5ECaAD9wLB2T4EEeymA5aFVcYXCA==", + "dev": true, + "engines": { + "node": ">=6" + } + }, + "node_modules/devlop": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/devlop/-/devlop-1.1.0.tgz", + "integrity": "sha512-RWmIqhcFf1lRYBvNmr7qTNuyCt/7/ns2jbpp1+PalgE/rDQcBT0fioSMUpJ93irlUhC5hrg4cYqe6U+0ImW0rA==", + "dev": true, + "dependencies": { + "dequal": "^2.0.0" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, "node_modules/diff-sequences": { "version": "29.6.3", "resolved": "https://registry.npmjs.org/diff-sequences/-/diff-sequences-29.6.3.tgz", @@ -1065,6 +1241,19 @@ "@esbuild/win32-x64": "0.28.0" } }, + "node_modules/esprima": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/esprima/-/esprima-4.0.1.tgz", + "integrity": "sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==", + "dev": true, + "bin": { + "esparse": "bin/esparse.js", + "esvalidate": "bin/esvalidate.js" + }, + "engines": { + "node": ">=4" + } + }, "node_modules/estree-walker": { "version": "3.0.3", "resolved": "https://registry.npmjs.org/estree-walker/-/estree-walker-3.0.3.tgz", @@ -1097,6 +1286,98 @@ "url": "https://github.com/sindresorhus/execa?sponsor=1" } }, + "node_modules/extend": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/extend/-/extend-3.0.2.tgz", + "integrity": "sha512-fjquC59cD7CyW6urNXK0FBufkZcoiGG80wTuPujX590cB5Ttln20E2UB4S/WARVqhXffZl2LNgS+gQdPIIim/g==", + "dev": true + }, + "node_modules/extend-shallow": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/extend-shallow/-/extend-shallow-2.0.1.tgz", + "integrity": "sha512-zCnTtlxNoAiDc3gqY2aYAWFx7XWWiasuF2K8Me5WbN8otHKTUKBwjPtNpRs/rbUZm7KxWAaNj7P1a/p52GbVug==", + "dev": true, + "dependencies": { + "is-extendable": "^0.1.0" + }, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/fast-deep-equal": { + "version": "3.1.3", + "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz", + "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==", + "dev": true + }, + "node_modules/fast-glob": { + "version": "3.3.3", + "resolved": "https://registry.npmjs.org/fast-glob/-/fast-glob-3.3.3.tgz", + "integrity": "sha512-7MptL8U0cqcFdzIzwOTHoilX9x5BrNqye7Z/LuC7kCMRio1EMSyqRK3BEAUD7sXRq4iT4AzTVuZdhgQ2TCvYLg==", + "dev": true, + "dependencies": { + "@nodelib/fs.stat": "^2.0.2", + "@nodelib/fs.walk": "^1.2.3", + "glob-parent": "^5.1.2", + "merge2": "^1.3.0", + "micromatch": "^4.0.8" + }, + "engines": { + "node": ">=8.6.0" + } + }, + "node_modules/fast-uri": { + "version": "3.1.2", + "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.2.tgz", + "integrity": "sha512-rVjf7ArG3LTk+FS6Yw81V1DLuZl1bRbNrev6Tmd/9RaroeeRRJhAt7jg/6YFxbvAQXUCavSoZhPPj6oOx+5KjQ==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/fastify" + }, + { + "type": "opencollective", + "url": "https://opencollective.com/fastify" + } + ] + }, + "node_modules/fastq": { + "version": "1.20.1", + "resolved": "https://registry.npmjs.org/fastq/-/fastq-1.20.1.tgz", + "integrity": "sha512-GGToxJ/w1x32s/D2EKND7kTil4n8OVk/9mycTc4VDza13lOvpUZTGX3mFSCtV9ksdGBVzvsyAVLM6mHFThxXxw==", + "dev": true, + "dependencies": { + "reusify": "^1.0.4" + } + }, + "node_modules/figures": { + "version": "6.1.0", + "resolved": "https://registry.npmjs.org/figures/-/figures-6.1.0.tgz", + "integrity": "sha512-d+l3qxjSesT4V7v2fh+QnmFnUWv9lSpjarhShNTgBOfA0ttejbQUAlHLitbjkoRiDulW0OPoQPYIGhIC8ohejg==", + "dev": true, + "dependencies": { + "is-unicode-supported": "^2.0.0" + }, + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/fill-range": { + "version": "7.1.1", + "resolved": "https://registry.npmjs.org/fill-range/-/fill-range-7.1.1.tgz", + "integrity": "sha512-YsGpe3WHLK8ZYi4tWDg2Jy3ebRz2rXowDxnld4bkQB00cc/1Zw9AWnC0i9ztDJitivtQvaI9KaLyKrc+hBW0yg==", + "dev": true, + "dependencies": { + "to-regex-range": "^5.0.1" + }, + "engines": { + "node": ">=8" + } + }, "node_modules/fsevents": { "version": "2.3.3", "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz", @@ -1132,6 +1413,33 @@ "url": "https://github.com/sponsors/sindresorhus" } }, + "node_modules/glob-parent": { + "version": "5.1.2", + "resolved": "https://registry.npmjs.org/glob-parent/-/glob-parent-5.1.2.tgz", + "integrity": "sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow==", + "dev": true, + "dependencies": { + "is-glob": "^4.0.1" + }, + "engines": { + "node": ">= 6" + } + }, + "node_modules/gray-matter": { + "version": "4.0.3", + "resolved": "https://registry.npmjs.org/gray-matter/-/gray-matter-4.0.3.tgz", + "integrity": "sha512-5v6yZd4JK3eMI3FqqCouswVqwugaA9r4dNZB1wwcmrD02QkV5H0y7XBQW8QwQqEaZY1pM9aqORSORhJRdNK44Q==", + "dev": true, + "dependencies": { + "js-yaml": "^3.13.1", + "kind-of": "^6.0.2", + "section-matter": "^1.0.0", + "strip-bom-string": "^1.0.0" + }, + "engines": { + "node": ">=6.0" + } + }, "node_modules/human-signals": { "version": "5.0.0", "resolved": "https://registry.npmjs.org/human-signals/-/human-signals-5.0.0.tgz", @@ -1141,6 +1449,57 @@ "node": ">=16.17.0" } }, + "node_modules/is-extendable": { + "version": "0.1.1", + "resolved": "https://registry.npmjs.org/is-extendable/-/is-extendable-0.1.1.tgz", + "integrity": "sha512-5BMULNob1vgFX6EjQw5izWDxrecWK9AM72rugNr0TFldMOi0fj6Jk+zeKIt0xGj4cEfQIJth4w3OKWOJ4f+AFw==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/is-extglob": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/is-extglob/-/is-extglob-2.1.1.tgz", + "integrity": "sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/is-glob": { + "version": "4.0.3", + "resolved": "https://registry.npmjs.org/is-glob/-/is-glob-4.0.3.tgz", + "integrity": "sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg==", + "dev": true, + "dependencies": { + "is-extglob": "^2.1.1" + }, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/is-number": { + "version": "7.0.0", + "resolved": "https://registry.npmjs.org/is-number/-/is-number-7.0.0.tgz", + "integrity": "sha512-41Cifkg6e8TylSpdtTpeLVMqvSBEVzTttHvERD741+pnZ8ANv0004MRL43QKPDlK9cGvNp6NZWZUBlbGXYxxng==", + "dev": true, + "engines": { + "node": ">=0.12.0" + } + }, + "node_modules/is-plain-obj": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/is-plain-obj/-/is-plain-obj-4.1.0.tgz", + "integrity": "sha512-+Pgi+vMuUNkJyExiMBt5IlFoMyKnr5zhJ4Uspz58WOhBF5QoIZkFyNHIbBAtHwzVAgk5RtndVNsDRN61/mmDqg==", + "dev": true, + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, "node_modules/is-stream": { "version": "3.0.0", "resolved": "https://registry.npmjs.org/is-stream/-/is-stream-3.0.0.tgz", @@ -1153,6 +1512,18 @@ "url": "https://github.com/sponsors/sindresorhus" } }, + "node_modules/is-unicode-supported": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/is-unicode-supported/-/is-unicode-supported-2.1.0.tgz", + "integrity": "sha512-mE00Gnza5EEB3Ds0HfMyllZzbBrmLOX3vfWoj9A9PEnTfratQ/BcaJOuMhnkhjXvb2+FkY3VuHqtAGpTPmglFQ==", + "dev": true, + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, "node_modules/isexe": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz", @@ -1165,6 +1536,34 @@ "integrity": "sha512-mxa9E9ITFOt0ban3j6L5MpjwegGz6lBQmM1IJkWeBZGcMxto50+eWdjC/52xDbS2vy0k7vIMK0Fe2wfL9OQSpQ==", "dev": true }, + "node_modules/js-yaml": { + "version": "3.14.2", + "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.14.2.tgz", + "integrity": "sha512-PMSmkqxr106Xa156c2M265Z+FTrPl+oxd/rgOQy2tijQeK5TxQ43psO1ZCwhVOSdnn+RzkzlRz/eY4BgJBYVpg==", + "dev": true, + "dependencies": { + "argparse": "^1.0.7", + "esprima": "^4.0.0" + }, + "bin": { + "js-yaml": "bin/js-yaml.js" + } + }, + "node_modules/json-schema-traverse": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz", + "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==", + "dev": true + }, + "node_modules/kind-of": { + "version": "6.0.3", + "resolved": "https://registry.npmjs.org/kind-of/-/kind-of-6.0.3.tgz", + "integrity": "sha512-dcS1ul+9tmeD95T+x28/ehLgd9mENa3LsvDTtzm3vyBEO7RPptvAD+t44WVXaUjTBRcrpFeFlC8WCruUR456hw==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, "node_modules/local-pkg": { "version": "0.5.1", "resolved": "https://registry.npmjs.org/local-pkg/-/local-pkg-0.5.1.tgz", @@ -1199,12 +1598,513 @@ "@jridgewell/sourcemap-codec": "^1.5.5" } }, + "node_modules/mdast-util-from-markdown": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/mdast-util-from-markdown/-/mdast-util-from-markdown-2.0.3.tgz", + "integrity": "sha512-W4mAWTvSlKvf8L6J+VN9yLSqQ9AOAAvHuoDAmPkz4dHf553m5gVj2ejadHJhoJmcmxEnOv6Pa8XJhpxE93kb8Q==", + "dev": true, + "dependencies": { + "@types/mdast": "^4.0.0", + "@types/unist": "^3.0.0", + "decode-named-character-reference": "^1.0.0", + "devlop": "^1.0.0", + "mdast-util-to-string": "^4.0.0", + "micromark": "^4.0.0", + "micromark-util-decode-numeric-character-reference": "^2.0.0", + "micromark-util-decode-string": "^2.0.0", + "micromark-util-normalize-identifier": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0", + "unist-util-stringify-position": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-to-string": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/mdast-util-to-string/-/mdast-util-to-string-4.0.0.tgz", + "integrity": "sha512-0H44vDimn51F0YwvxSJSm0eCDOJTRlmN0R1yBh4HLj9wiV1Dn0QoXGbvFAWj2hSItVTlCmBF1hqKlIyUBVFLPg==", + "dev": true, + "dependencies": { + "@types/mdast": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, "node_modules/merge-stream": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/merge-stream/-/merge-stream-2.0.0.tgz", "integrity": "sha512-abv/qOcuPfk3URPfDzmZU1LKmuw8kT+0nIHvKrKgFrwifol/doWcdA4ZqsWQ8ENrFKkd67Mfpo/LovbIUsbt3w==", "dev": true }, + "node_modules/merge2": { + "version": "1.4.1", + "resolved": "https://registry.npmjs.org/merge2/-/merge2-1.4.1.tgz", + "integrity": "sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg==", + "dev": true, + "engines": { + "node": ">= 8" + } + }, + "node_modules/micromark": { + "version": "4.0.2", + "resolved": "https://registry.npmjs.org/micromark/-/micromark-4.0.2.tgz", + "integrity": "sha512-zpe98Q6kvavpCr1NPVSCMebCKfD7CA2NqZ+rykeNhONIJBpc1tFKt9hucLGwha3jNTNI8lHpctWJWoimVF4PfA==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "dependencies": { + "@types/debug": "^4.0.0", + "debug": "^4.0.0", + "decode-named-character-reference": "^1.0.0", + "devlop": "^1.0.0", + "micromark-core-commonmark": "^2.0.0", + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-chunked": "^2.0.0", + "micromark-util-combine-extensions": "^2.0.0", + "micromark-util-decode-numeric-character-reference": "^2.0.0", + "micromark-util-encode": "^2.0.0", + "micromark-util-normalize-identifier": "^2.0.0", + "micromark-util-resolve-all": "^2.0.0", + "micromark-util-sanitize-uri": "^2.0.0", + "micromark-util-subtokenize": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-core-commonmark": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/micromark-core-commonmark/-/micromark-core-commonmark-2.0.3.tgz", + "integrity": "sha512-RDBrHEMSxVFLg6xvnXmb1Ayr2WzLAWjeSATAoxwKYJV94TeNavgoIdA0a9ytzDSVzBy2YKFK+emCPOEibLeCrg==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "dependencies": { + "decode-named-character-reference": "^1.0.0", + "devlop": "^1.0.0", + "micromark-factory-destination": "^2.0.0", + "micromark-factory-label": "^2.0.0", + "micromark-factory-space": "^2.0.0", + "micromark-factory-title": "^2.0.0", + "micromark-factory-whitespace": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-chunked": "^2.0.0", + "micromark-util-classify-character": "^2.0.0", + "micromark-util-html-tag-name": "^2.0.0", + "micromark-util-normalize-identifier": "^2.0.0", + "micromark-util-resolve-all": "^2.0.0", + "micromark-util-subtokenize": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-factory-destination": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-factory-destination/-/micromark-factory-destination-2.0.1.tgz", + "integrity": "sha512-Xe6rDdJlkmbFRExpTOmRj9N3MaWmbAgdpSrBQvCFqhezUn4AHqJHbaEnfbVYYiexVSs//tqOdY/DxhjdCiJnIA==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "dependencies": { + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-factory-label": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-factory-label/-/micromark-factory-label-2.0.1.tgz", + "integrity": "sha512-VFMekyQExqIW7xIChcXn4ok29YE3rnuyveW3wZQWWqF4Nv9Wk5rgJ99KzPvHjkmPXF93FXIbBp6YdW3t71/7Vg==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "dependencies": { + "devlop": "^1.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-factory-space": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-factory-space/-/micromark-factory-space-2.0.1.tgz", + "integrity": "sha512-zRkxjtBxxLd2Sc0d+fbnEunsTj46SWXgXciZmHq0kDYGnck/ZSGj9/wULTV95uoeYiK5hRXP2mJ98Uo4cq/LQg==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "dependencies": { + "micromark-util-character": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-factory-title": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-factory-title/-/micromark-factory-title-2.0.1.tgz", + "integrity": "sha512-5bZ+3CjhAd9eChYTHsjy6TGxpOFSKgKKJPJxr293jTbfry2KDoWkhBb6TcPVB4NmzaPhMs1Frm9AZH7OD4Cjzw==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "dependencies": { + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-factory-whitespace": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-factory-whitespace/-/micromark-factory-whitespace-2.0.1.tgz", + "integrity": "sha512-Ob0nuZ3PKt/n0hORHyvoD9uZhr+Za8sFoP+OnMcnWK5lngSzALgQYKMr9RJVOWLqQYuyn6ulqGWSXdwf6F80lQ==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "dependencies": { + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-util-character": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/micromark-util-character/-/micromark-util-character-2.1.1.tgz", + "integrity": "sha512-wv8tdUTJ3thSFFFJKtpYKOYiGP2+v96Hvk4Tu8KpCAsTMs6yi+nVmGh1syvSCsaxz45J6Jbw+9DD6g97+NV67Q==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "dependencies": { + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-util-chunked": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-chunked/-/micromark-util-chunked-2.0.1.tgz", + "integrity": "sha512-QUNFEOPELfmvv+4xiNg2sRYeS/P84pTW0TCgP5zc9FpXetHY0ab7SxKyAQCNCc1eK0459uoLI1y5oO5Vc1dbhA==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "dependencies": { + "micromark-util-symbol": "^2.0.0" + } + }, + "node_modules/micromark-util-classify-character": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-classify-character/-/micromark-util-classify-character-2.0.1.tgz", + "integrity": "sha512-K0kHzM6afW/MbeWYWLjoHQv1sgg2Q9EccHEDzSkxiP/EaagNzCm7T/WMKZ3rjMbvIpvBiZgwR3dKMygtA4mG1Q==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "dependencies": { + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-util-combine-extensions": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-combine-extensions/-/micromark-util-combine-extensions-2.0.1.tgz", + "integrity": "sha512-OnAnH8Ujmy59JcyZw8JSbK9cGpdVY44NKgSM7E9Eh7DiLS2E9RNQf0dONaGDzEG9yjEl5hcqeIsj4hfRkLH/Bg==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "dependencies": { + "micromark-util-chunked": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-util-decode-numeric-character-reference": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/micromark-util-decode-numeric-character-reference/-/micromark-util-decode-numeric-character-reference-2.0.2.tgz", + "integrity": "sha512-ccUbYk6CwVdkmCQMyr64dXz42EfHGkPQlBj5p7YVGzq8I7CtjXZJrubAYezf7Rp+bjPseiROqe7G6foFd+lEuw==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "dependencies": { + "micromark-util-symbol": "^2.0.0" + } + }, + "node_modules/micromark-util-decode-string": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-decode-string/-/micromark-util-decode-string-2.0.1.tgz", + "integrity": "sha512-nDV/77Fj6eH1ynwscYTOsbK7rR//Uj0bZXBwJZRfaLEJ1iGBR6kIfNmlNqaqJf649EP0F3NWNdeJi03elllNUQ==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "dependencies": { + "decode-named-character-reference": "^1.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-decode-numeric-character-reference": "^2.0.0", + "micromark-util-symbol": "^2.0.0" + } + }, + "node_modules/micromark-util-encode": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-encode/-/micromark-util-encode-2.0.1.tgz", + "integrity": "sha512-c3cVx2y4KqUnwopcO9b/SCdo2O67LwJJ/UyqGfbigahfegL9myoEFoDYZgkT7f36T0bLrM9hZTAaAyH+PCAXjw==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ] + }, + "node_modules/micromark-util-html-tag-name": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-html-tag-name/-/micromark-util-html-tag-name-2.0.1.tgz", + "integrity": "sha512-2cNEiYDhCWKI+Gs9T0Tiysk136SnR13hhO8yW6BGNyhOC4qYFnwF1nKfD3HFAIXA5c45RrIG1ub11GiXeYd1xA==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ] + }, + "node_modules/micromark-util-normalize-identifier": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-normalize-identifier/-/micromark-util-normalize-identifier-2.0.1.tgz", + "integrity": "sha512-sxPqmo70LyARJs0w2UclACPUUEqltCkJ6PhKdMIDuJ3gSf/Q+/GIe3WKl0Ijb/GyH9lOpUkRAO2wp0GVkLvS9Q==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "dependencies": { + "micromark-util-symbol": "^2.0.0" + } + }, + "node_modules/micromark-util-resolve-all": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-resolve-all/-/micromark-util-resolve-all-2.0.1.tgz", + "integrity": "sha512-VdQyxFWFT2/FGJgwQnJYbe1jjQoNTS4RjglmSjTUlpUMa95Htx9NHeYW4rGDJzbjvCsl9eLjMQwGeElsqmzcHg==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "dependencies": { + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-util-sanitize-uri": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-sanitize-uri/-/micromark-util-sanitize-uri-2.0.1.tgz", + "integrity": "sha512-9N9IomZ/YuGGZZmQec1MbgxtlgougxTodVwDzzEouPKo3qFWvymFHWcnDi2vzV1ff6kas9ucW+o3yzJK9YB1AQ==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "dependencies": { + "micromark-util-character": "^2.0.0", + "micromark-util-encode": "^2.0.0", + "micromark-util-symbol": "^2.0.0" + } + }, + "node_modules/micromark-util-subtokenize": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/micromark-util-subtokenize/-/micromark-util-subtokenize-2.1.0.tgz", + "integrity": "sha512-XQLu552iSctvnEcgXw6+Sx75GflAPNED1qx7eBJ+wydBb2KCbRZe+NwvIEEMM83uml1+2WSXpBAcp9IUCgCYWA==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "dependencies": { + "devlop": "^1.0.0", + "micromark-util-chunked": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/micromark-util-symbol": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-symbol/-/micromark-util-symbol-2.0.1.tgz", + "integrity": "sha512-vs5t8Apaud9N28kgCrRUdEed4UJ+wWNvicHLPxCa9ENlYuAY31M0ETy5y1vA33YoNPDFTghEbnh6efaE8h4x0Q==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ] + }, + "node_modules/micromark-util-types": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/micromark-util-types/-/micromark-util-types-2.0.2.tgz", + "integrity": "sha512-Yw0ECSpJoViF1qTU4DC6NwtC4aWGt1EkzaQB8KPPyCRR8z9TWeV0HbEFGTO+ZY1wB22zmxnJqhPyTpOVCpeHTA==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ] + }, + "node_modules/micromatch": { + "version": "4.0.8", + "resolved": "https://registry.npmjs.org/micromatch/-/micromatch-4.0.8.tgz", + "integrity": "sha512-PXwfBhYu0hBCPw8Dn0E+WDYb7af3dSLVWKi3HGv84IdF4TyFoC0ysxFd0Goxw7nSv4T/PzEJQxsYsEiFCKo2BA==", + "dev": true, + "dependencies": { + "braces": "^3.0.3", + "picomatch": "^2.3.1" + }, + "engines": { + "node": ">=8.6" + } + }, "node_modules/mimic-fn": { "version": "4.0.0", "resolved": "https://registry.npmjs.org/mimic-fn/-/mimic-fn-4.0.0.tgz", @@ -1316,6 +2216,18 @@ "url": "https://github.com/sponsors/sindresorhus" } }, + "node_modules/parse-ms": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/parse-ms/-/parse-ms-4.0.0.tgz", + "integrity": "sha512-TXfryirbmq34y8QBwgqCVLi+8oA3oWx2eAnSn62ITyEhEYaWRlVZ2DvMM9eZbMs/RfxPu/PK/aBLyGj4IrqMHw==", + "dev": true, + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, "node_modules/path-key": { "version": "3.1.1", "resolved": "https://registry.npmjs.org/path-key/-/path-key-3.1.1.tgz", @@ -1346,6 +2258,18 @@ "integrity": "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==", "dev": true }, + "node_modules/picomatch": { + "version": "2.3.2", + "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.2.tgz", + "integrity": "sha512-V7+vQEJ06Z+c5tSye8S+nHUfI51xoXIXjHQ99cQtKUkQqqO1kO/KCJUfZXuB47h/YBlDhah2H3hdUGXn8ie0oA==", + "dev": true, + "engines": { + "node": ">=8.6" + }, + "funding": { + "url": "https://github.com/sponsors/jonschlinkert" + } + }, "node_modules/pkg-types": { "version": "1.3.1", "resolved": "https://registry.npmjs.org/pkg-types/-/pkg-types-1.3.1.tgz", @@ -1405,12 +2329,82 @@ "node": "^14.15.0 || ^16.10.0 || >=18.0.0" } }, + "node_modules/pretty-ms": { + "version": "9.3.0", + "resolved": "https://registry.npmjs.org/pretty-ms/-/pretty-ms-9.3.0.tgz", + "integrity": "sha512-gjVS5hOP+M3wMm5nmNOucbIrqudzs9v/57bWRHQWLYklXqoXKrVfYW2W9+glfGsqtPgpiz5WwyEEB+ksXIx3gQ==", + "dev": true, + "dependencies": { + "parse-ms": "^4.0.0" + }, + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/queue-microtask": { + "version": "1.2.3", + "resolved": "https://registry.npmjs.org/queue-microtask/-/queue-microtask-1.2.3.tgz", + "integrity": "sha512-NuaNSa6flKT5JaSYQzJok04JzTL1CA6aGhv5rfLW3PgqA+M2ChpZQnAC8h8i4ZFkBS8X5RqkDBHA7r4hej3K9A==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/feross" + }, + { + "type": "patreon", + "url": "https://www.patreon.com/feross" + }, + { + "type": "consulting", + "url": "https://feross.org/support" + } + ] + }, "node_modules/react-is": { "version": "18.3.1", "resolved": "https://registry.npmjs.org/react-is/-/react-is-18.3.1.tgz", "integrity": "sha512-/LLMVyas0ljjAtoYiPqYiL8VWXzUUdThrmU5+n20DZv+a+ClRoevUzw5JxU+Ieh5/c87ytoTBV9G1FiKfNJdmg==", "dev": true }, + "node_modules/remark-parse": { + "version": "11.0.0", + "resolved": "https://registry.npmjs.org/remark-parse/-/remark-parse-11.0.0.tgz", + "integrity": "sha512-FCxlKLNGknS5ba/1lmpYijMUzX2esxW5xQqjWxw2eHFfS2MSdaHVINFmhjo+qN1WhZhNimq0dZATN9pH0IDrpA==", + "dev": true, + "dependencies": { + "@types/mdast": "^4.0.0", + "mdast-util-from-markdown": "^2.0.0", + "micromark-util-types": "^2.0.0", + "unified": "^11.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/require-from-string": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz", + "integrity": "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/reusify": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/reusify/-/reusify-1.1.0.tgz", + "integrity": "sha512-g6QUff04oZpHs0eG5p83rFLhHeV00ug/Yf9nZM6fLeUrPguBTkTQOdpAWWspMh55TZfVQDPaN3NQJfbVRAxdIw==", + "dev": true, + "engines": { + "iojs": ">=1.0.0", + "node": ">=0.10.0" + } + }, "node_modules/rollup": { "version": "4.60.4", "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.60.4.tgz", @@ -1461,6 +2455,42 @@ "integrity": "sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w==", "dev": true }, + "node_modules/run-parallel": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/run-parallel/-/run-parallel-1.2.0.tgz", + "integrity": "sha512-5l4VyZR86LZ/lDxZTR6jqL8AFE2S0IFLMP26AbjsLVADxHdhB/c0GUsH+y39UfCi3dzz8OlQuPmnaJOMoDHQBA==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/feross" + }, + { + "type": "patreon", + "url": "https://www.patreon.com/feross" + }, + { + "type": "consulting", + "url": "https://feross.org/support" + } + ], + "dependencies": { + "queue-microtask": "^1.2.2" + } + }, + "node_modules/section-matter": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/section-matter/-/section-matter-1.0.0.tgz", + "integrity": "sha512-vfD3pmTzGpufjScBh50YHKzEu2lxBWhVEHsNGoEXmCmn2hKGfeNLYMzCJpe8cD7gqX7TJluOVpBkAequ6dgMmA==", + "dev": true, + "dependencies": { + "extend-shallow": "^2.0.1", + "kind-of": "^6.0.0" + }, + "engines": { + "node": ">=4" + } + }, "node_modules/shebang-command": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz", @@ -1509,6 +2539,12 @@ "node": ">=0.10.0" } }, + "node_modules/sprintf-js": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/sprintf-js/-/sprintf-js-1.0.3.tgz", + "integrity": "sha512-D9cPgkvLlV3t3IzL0D0YLvGA9Ahk4PcvVwUbN0dSGr1aP0Nrt4AEnTUbuGvquEC0mA64Gqt1fzirlRs5ibXx8g==", + "dev": true + }, "node_modules/stackback": { "version": "0.0.2", "resolved": "https://registry.npmjs.org/stackback/-/stackback-0.0.2.tgz", @@ -1521,6 +2557,15 @@ "integrity": "sha512-5GS12FdOZNliM5mAOxFRg7Ir0pWz8MdpYm6AY6VPkGpbA7ZzmbzNcBJQ0GPvvyWgcY7QAhCgf9Uy89I03faLkg==", "dev": true }, + "node_modules/strip-bom-string": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/strip-bom-string/-/strip-bom-string-1.0.0.tgz", + "integrity": "sha512-uCC2VHvQRYu+lMh4My/sFNmF2klFymLX1wHJeXnbEJERpV/ZsVuonzerjfrGpIGF7LBVa1O7i9kjiWvJiFck8g==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, "node_modules/strip-final-newline": { "version": "3.0.0", "resolved": "https://registry.npmjs.org/strip-final-newline/-/strip-final-newline-3.0.0.tgz", @@ -1569,6 +2614,165 @@ "node": ">=14.0.0" } }, + "node_modules/to-regex-range": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/to-regex-range/-/to-regex-range-5.0.1.tgz", + "integrity": "sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ==", + "dev": true, + "dependencies": { + "is-number": "^7.0.0" + }, + "engines": { + "node": ">=8.0" + } + }, + "node_modules/trough": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/trough/-/trough-2.2.0.tgz", + "integrity": "sha512-tmMpK00BjZiUyVyvrBK7knerNgmgvcV/KLVyuma/SC+TQN167GrMRciANTz09+k3zW8L8t60jWO1GpfkZdjTaw==", + "dev": true, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/truthmark": { + "version": "1.6.0", + "resolved": "https://registry.npmjs.org/truthmark/-/truthmark-1.6.0.tgz", + "integrity": "sha512-d+4KVXMTqIj8lWgPnI+gvcbcWM8KLWkBTgVaveynpLdLroPx8LOg/pFoHvHuIvX3+MXAiiAgbzsImYu0oaJTgw==", + "dev": true, + "dependencies": { + "ajv": "^8.17.1", + "commander": "^14.0.1", + "execa": "^9.6.0", + "fast-glob": "^3.3.3", + "gray-matter": "^4.0.3", + "micromatch": "^4.0.8", + "remark-parse": "^11.0.0", + "typescript": "^5.9.3", + "unified": "^11.0.5", + "unist-util-visit": "^5.0.0", + "yaml": "^2.8.1" + }, + "bin": { + "truthmark": "dist/main.js" + }, + "engines": { + "node": ">=20" + } + }, + "node_modules/truthmark/node_modules/commander": { + "version": "14.0.3", + "resolved": "https://registry.npmjs.org/commander/-/commander-14.0.3.tgz", + "integrity": "sha512-H+y0Jo/T1RZ9qPP4Eh1pkcQcLRglraJaSLoyOtHxu6AapkjWVCy2Sit1QQ4x3Dng8qDlSsZEet7g5Pq06MvTgw==", + "dev": true, + "engines": { + "node": ">=20" + } + }, + "node_modules/truthmark/node_modules/execa": { + "version": "9.6.1", + "resolved": "https://registry.npmjs.org/execa/-/execa-9.6.1.tgz", + "integrity": "sha512-9Be3ZoN4LmYR90tUoVu2te2BsbzHfhJyfEiAVfz7N5/zv+jduIfLrV2xdQXOHbaD6KgpGdO9PRPM1Y4Q9QkPkA==", + "dev": true, + "dependencies": { + "@sindresorhus/merge-streams": "^4.0.0", + "cross-spawn": "^7.0.6", + "figures": "^6.1.0", + "get-stream": "^9.0.0", + "human-signals": "^8.0.1", + "is-plain-obj": "^4.1.0", + "is-stream": "^4.0.1", + "npm-run-path": "^6.0.0", + "pretty-ms": "^9.2.0", + "signal-exit": "^4.1.0", + "strip-final-newline": "^4.0.0", + "yoctocolors": "^2.1.1" + }, + "engines": { + "node": "^18.19.0 || >=20.5.0" + }, + "funding": { + "url": "https://github.com/sindresorhus/execa?sponsor=1" + } + }, + "node_modules/truthmark/node_modules/get-stream": { + "version": "9.0.1", + "resolved": "https://registry.npmjs.org/get-stream/-/get-stream-9.0.1.tgz", + "integrity": "sha512-kVCxPF3vQM/N0B1PmoqVUqgHP+EeVjmZSQn+1oCRPxd2P21P2F19lIgbR3HBosbB1PUhOAoctJnfEn2GbN2eZA==", + "dev": true, + "dependencies": { + "@sec-ant/readable-stream": "^0.4.1", + "is-stream": "^4.0.1" + }, + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/truthmark/node_modules/human-signals": { + "version": "8.0.1", + "resolved": "https://registry.npmjs.org/human-signals/-/human-signals-8.0.1.tgz", + "integrity": "sha512-eKCa6bwnJhvxj14kZk5NCPc6Hb6BdsU9DZcOnmQKSnO1VKrfV0zCvtttPZUsBvjmNDn8rpcJfpwSYnHBjc95MQ==", + "dev": true, + "engines": { + "node": ">=18.18.0" + } + }, + "node_modules/truthmark/node_modules/is-stream": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/is-stream/-/is-stream-4.0.1.tgz", + "integrity": "sha512-Dnz92NInDqYckGEUJv689RbRiTSEHCQ7wOVeALbkOz999YpqT46yMRIGtSNl2iCL1waAZSx40+h59NV/EwzV/A==", + "dev": true, + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/truthmark/node_modules/npm-run-path": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/npm-run-path/-/npm-run-path-6.0.0.tgz", + "integrity": "sha512-9qny7Z9DsQU8Ou39ERsPU4OZQlSTP47ShQzuKZ6PRXpYLtIFgl/DEBYEXKlvcEa+9tHVcK8CF81Y2V72qaZhWA==", + "dev": true, + "dependencies": { + "path-key": "^4.0.0", + "unicorn-magic": "^0.3.0" + }, + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/truthmark/node_modules/path-key": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/path-key/-/path-key-4.0.0.tgz", + "integrity": "sha512-haREypq7xkM7ErfgIyA0z+Bj4AGKlMSdlQE2jvJo6huWD1EdkKYV+G/T4nq0YEF2vgTT8kqMFKo1uHn950r4SQ==", + "dev": true, + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/truthmark/node_modules/strip-final-newline": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/strip-final-newline/-/strip-final-newline-4.0.0.tgz", + "integrity": "sha512-aulFJcD6YK8V1G7iRB5tigAP4TsHBZZrOV8pjV++zdUwmeV8uzbY7yn6h9MswN62adStNZFuCIx4haBnRuMDaw==", + "dev": true, + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, "node_modules/tsx": { "version": "4.22.3", "resolved": "https://registry.npmjs.org/tsx/-/tsx-4.22.3.tgz", @@ -1621,6 +2825,120 @@ "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==", "dev": true }, + "node_modules/unicorn-magic": { + "version": "0.3.0", + "resolved": "https://registry.npmjs.org/unicorn-magic/-/unicorn-magic-0.3.0.tgz", + "integrity": "sha512-+QBBXBCvifc56fsbuxZQ6Sic3wqqc3WWaqxs58gvJrcOuN83HGTCwz3oS5phzU9LthRNE9VrJCFCLUgHeeFnfA==", + "dev": true, + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/unified": { + "version": "11.0.5", + "resolved": "https://registry.npmjs.org/unified/-/unified-11.0.5.tgz", + "integrity": "sha512-xKvGhPWw3k84Qjh8bI3ZeJjqnyadK+GEFtazSfZv/rKeTkTjOJho6mFqh2SM96iIcZokxiOpg78GazTSg8+KHA==", + "dev": true, + "dependencies": { + "@types/unist": "^3.0.0", + "bail": "^2.0.0", + "devlop": "^1.0.0", + "extend": "^3.0.0", + "is-plain-obj": "^4.0.0", + "trough": "^2.0.0", + "vfile": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/unist-util-is": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/unist-util-is/-/unist-util-is-6.0.1.tgz", + "integrity": "sha512-LsiILbtBETkDz8I9p1dQ0uyRUWuaQzd/cuEeS1hoRSyW5E5XGmTzlwY1OrNzzakGowI9Dr/I8HVaw4hTtnxy8g==", + "dev": true, + "dependencies": { + "@types/unist": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/unist-util-stringify-position": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/unist-util-stringify-position/-/unist-util-stringify-position-4.0.0.tgz", + "integrity": "sha512-0ASV06AAoKCDkS2+xw5RXJywruurpbC4JZSm7nr7MOt1ojAzvyyaO+UxZf18j8FCF6kmzCZKcAgN/yu2gm2XgQ==", + "dev": true, + "dependencies": { + "@types/unist": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/unist-util-visit": { + "version": "5.1.0", + "resolved": "https://registry.npmjs.org/unist-util-visit/-/unist-util-visit-5.1.0.tgz", + "integrity": "sha512-m+vIdyeCOpdr/QeQCu2EzxX/ohgS8KbnPDgFni4dQsfSCtpz8UqDyY5GjRru8PDKuYn7Fq19j1CQ+nJSsGKOzg==", + "dev": true, + "dependencies": { + "@types/unist": "^3.0.0", + "unist-util-is": "^6.0.0", + "unist-util-visit-parents": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/unist-util-visit-parents": { + "version": "6.0.2", + "resolved": "https://registry.npmjs.org/unist-util-visit-parents/-/unist-util-visit-parents-6.0.2.tgz", + "integrity": "sha512-goh1s1TBrqSqukSc8wrjwWhL0hiJxgA8m4kFxGlQ+8FYQ3C/m11FcTs4YYem7V664AhHVvgoQLk890Ssdsr2IQ==", + "dev": true, + "dependencies": { + "@types/unist": "^3.0.0", + "unist-util-is": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/vfile": { + "version": "6.0.3", + "resolved": "https://registry.npmjs.org/vfile/-/vfile-6.0.3.tgz", + "integrity": "sha512-KzIbH/9tXat2u30jf+smMwFCsno4wHVdNmzFyL+T/L3UGqqk6JKfVqOFOZEpZSHADH1k40ab6NUIXZq422ov3Q==", + "dev": true, + "dependencies": { + "@types/unist": "^3.0.0", + "vfile-message": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/vfile-message": { + "version": "4.0.3", + "resolved": "https://registry.npmjs.org/vfile-message/-/vfile-message-4.0.3.tgz", + "integrity": "sha512-QTHzsGd1EhbZs4AsQ20JX1rC3cOlt/IWJruk893DfLRr57lcnOeMaWG4K0JrRta4mIJZKth2Au3mM3u03/JWKw==", + "dev": true, + "dependencies": { + "@types/unist": "^3.0.0", + "unist-util-stringify-position": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, "node_modules/vite": { "version": "5.4.21", "resolved": "https://registry.npmjs.org/vite/-/vite-5.4.21.tgz", @@ -2204,6 +3522,21 @@ "node": ">=8" } }, + "node_modules/yaml": { + "version": "2.9.0", + "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.9.0.tgz", + "integrity": "sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA==", + "dev": true, + "bin": { + "yaml": "bin.mjs" + }, + "engines": { + "node": ">= 14.6" + }, + "funding": { + "url": "https://github.com/sponsors/eemeli" + } + }, "node_modules/yocto-queue": { "version": "1.2.2", "resolved": "https://registry.npmjs.org/yocto-queue/-/yocto-queue-1.2.2.tgz", @@ -2216,6 +3549,18 @@ "url": "https://github.com/sponsors/sindresorhus" } }, + "node_modules/yoctocolors": { + "version": "2.1.2", + "resolved": "https://registry.npmjs.org/yoctocolors/-/yoctocolors-2.1.2.tgz", + "integrity": "sha512-CzhO+pFNo8ajLM2d2IW/R93ipy99LWjtwblvC1RsoSUMZgyLbYFr221TnSNT7GjGdYui6P459mw9JH/g/zW2ug==", + "dev": true, + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, "node_modules/zod": { "version": "3.25.76", "resolved": "https://registry.npmjs.org/zod/-/zod-3.25.76.tgz", diff --git a/package.json b/package.json index 616f147..6cb01fe 100644 --- a/package.json +++ b/package.json @@ -31,6 +31,7 @@ }, "devDependencies": { "@types/node": "^20.19.25", + "truthmark": "^1.6.0", "tsx": "^4.20.6", "typescript": "^5.9.3", "vitest": "^1.6.1" diff --git a/src/runner.ts b/src/runner.ts index a68c14a..8f8f4d4 100644 --- a/src/runner.ts +++ b/src/runner.ts @@ -33,6 +33,7 @@ export type PreparedRun = { contextFiles: string[]; verification?: VerificationCommand; codexCommand: { command: string; args: string[]; display: string }; + reviewCodexCommand?: { command: string; args: string[]; display: string }; output: string; reviewPrompt?: string; fixPrompt?: string; @@ -74,13 +75,13 @@ function requireTask(task: string): string { return task.trim(); } -export function codexExecInvocation(projectRoot: string, codexBin = resolveCodexCommand()): { command: string; args: string[]; display: string } { - const args = buildCodexExecArgs({ projectRoot, sandbox: "workspace-write" }); +export function codexExecInvocation(projectRoot: string, codexBin = resolveCodexCommand(), sandbox: "read-only" | "workspace-write" = "workspace-write"): { command: string; args: string[]; display: string } { + const args = buildCodexExecArgs({ projectRoot, sandbox }); return { command: codexBin, args, display: [codexBin, ...args.map((arg) => JSON.stringify(arg))].join(" ") }; } -export function executeCodexPromptSync(run: PreparedRun, prompt: string): CodexExecutionResult { - const result = spawnSync(run.codexCommand.command, run.codexCommand.args, { +export function executeCodexPromptSync(run: PreparedRun, prompt: string, command = run.codexCommand): CodexExecutionResult { + const result = spawnSync(command.command, command.args, { cwd: run.projectRoot, encoding: "utf8", input: prompt, @@ -133,7 +134,7 @@ export function parseReviewJson(raw: string): ReviewResult { function runReviewPass(run: PreparedRun, previousSummary = ""): ReviewPassResult | undefined { if (!run.reviewPrompt) return undefined; const prompt = `${run.reviewPrompt}\n\n# Implementation and verification output\n\n${previousSummary}\n`; - const execution = executeCodexPromptSync(run, prompt); + const execution = executeCodexPromptSync(run, prompt, run.reviewCodexCommand ?? run.codexCommand); const raw = execution.stdout.trim() || execution.stderr.trim(); if (executionFailed(execution)) return { execution, raw, malformed: execution.error?.message ?? `review exited with status ${execution.status}` }; try { @@ -287,38 +288,42 @@ export function prepareRun(roleInput: string, options: RunOptions, cwd = process : undefined; const runId = `${new Date().toISOString().replace(/[-:.TZ]/g, "").slice(0, 17)}-${process.pid}-${++runSequence}`; const runDir = path.join(projectRoot, ".codex", "runs", `${runId}-${role}`); - mkdirSync(runDir, { recursive: true }); const promptPath = path.join(runDir, "prompt.md"); const metadataPath = path.join(runDir, "metadata.json"); - writeFileSync(promptPath, prompt); - writeFileSync( - metadataPath, - `${JSON.stringify( - { - timestamp: new Date().toISOString(), - product: "codex-game-studio", - project: path.relative(cwd, projectRoot) || ".", - role, - task, - prompt_chars: prompt.length, - prompt_cache_path: path.relative(cwd, promptPath), - review: Boolean(reviewPrompt), - fix: Boolean(fixPrompt), - max_fix_passes: maxFixPasses - }, - null, - 2 - )}\n` - ); - const codexCommand = codexExecInvocation(projectRoot, options.codexBin ?? resolveCodexCommand()); + if (!options.printPrompt && !options.dryRun) { + mkdirSync(runDir, { recursive: true }); + writeFileSync(promptPath, prompt); + writeFileSync( + metadataPath, + `${JSON.stringify( + { + timestamp: new Date().toISOString(), + product: "codex-game-studio", + project: path.relative(cwd, projectRoot) || ".", + role, + task, + prompt_chars: prompt.length, + prompt_cache_path: path.relative(cwd, promptPath), + review: Boolean(reviewPrompt), + fix: Boolean(fixPrompt), + max_fix_passes: maxFixPasses + }, + null, + 2 + )}\n` + ); + } + const codexBin = options.codexBin ?? resolveCodexCommand(); + const codexCommand = codexExecInvocation(projectRoot, codexBin); + const reviewCodexCommand = reviewPrompt ? codexExecInvocation(projectRoot, codexBin, "read-only") : undefined; const dryRunExtra = [ - reviewPrompt ? `\n\nReview prompt:\n${reviewPrompt}\n\nExpected review JSON schema: {"blockers":[],"warnings":[],"summary":"","needsFix":false}` : "", + reviewPrompt ? `\n\nReview Codex command: ${reviewCodexCommand?.display}\n\nReview prompt:\n${reviewPrompt}\n\nExpected review JSON schema: {"blockers":[],"warnings":[],"summary":"","needsFix":false}` : "", fixPrompt ? `\n\nFix prompt (max passes: ${maxFixPasses}):\n${fixPrompt}` : "" ].join(""); const output = options.printPrompt ? prompt : options.dryRun - ? `Prompt cache: ${promptPath}\nMetadata: ${metadataPath}\nContext files:\n${contextFiles.map((f) => `- ${f}`).join("\n")}\nCodex command: ${codexCommand.display}${dryRunExtra}` + ? `Prompt cache (not written): ${promptPath}\nMetadata (not written): ${metadataPath}\nContext files:\n${contextFiles.map((f) => `- ${f}`).join("\n")}\nCodex command: ${codexCommand.display}${dryRunExtra}` : `Prompt cache written: ${promptPath}\nExecuting Codex: ${codexCommand.display}`; - return { prompt, promptPath, metadataPath, projectRoot, role, task, contextFiles, verification: options.verifyCommand, codexCommand, output, reviewPrompt, fixPrompt, maxFixPasses }; + return { prompt, promptPath, metadataPath, projectRoot, role, task, contextFiles, verification: options.verifyCommand, codexCommand, reviewCodexCommand, output, reviewPrompt, fixPrompt, maxFixPasses }; } diff --git a/src/tasks.ts b/src/tasks.ts index 39afab3..963ffb9 100644 --- a/src/tasks.ts +++ b/src/tasks.ts @@ -92,6 +92,7 @@ function getTask(store: TaskStore, taskId: string): StudioTask { export function createTask(projectRoot: string, input: { title: string; role: StudioRoleId; verification?: VerificationCommand; files?: string[] }): StudioTask { if (!input.title.trim()) throw new Error("task title is required"); + readStudioProject(projectRoot); const store = readTaskStore(projectRoot); const task: StudioTask = { id: nextTaskId(store.tasks), diff --git a/src/verification.ts b/src/verification.ts index 80c224c..12c63b1 100644 --- a/src/verification.ts +++ b/src/verification.ts @@ -19,6 +19,7 @@ export type VerificationResult = { export type RunVerificationOptions = { cwd: string; timeoutMs?: number; + killGraceMs?: number; maxOutputBytes?: number; }; @@ -32,6 +33,8 @@ export async function runVerificationCommand(command: VerificationCommand, optio if (!command.command.trim()) throw new Error("verification command is required"); const timeoutMs = options.timeoutMs ?? 30_000; if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) throw new Error("verification timeout must be finite and positive"); + const killGraceMs = options.killGraceMs ?? 1_000; + if (!Number.isFinite(killGraceMs) || killGraceMs < 0) throw new Error("verification kill grace must be finite and non-negative"); const maxOutputBytes = options.maxOutputBytes ?? 64_000; if (!Number.isFinite(maxOutputBytes) || maxOutputBytes <= 0) throw new Error("verification output bound must be finite and positive"); @@ -44,10 +47,18 @@ export async function runVerificationCommand(command: VerificationCommand, optio let stdout = ""; let stderr = ""; let timedOut = false; + let killTimer: NodeJS.Timeout | undefined; const timer = setTimeout(() => { timedOut = true; child.kill("SIGTERM"); + killTimer = setTimeout(() => { + child.kill("SIGKILL"); + }, killGraceMs); }, timeoutMs); + const clearTimers = (): void => { + clearTimeout(timer); + if (killTimer) clearTimeout(killTimer); + }; child.stdout.setEncoding("utf8"); child.stderr.setEncoding("utf8"); @@ -58,11 +69,11 @@ export async function runVerificationCommand(command: VerificationCommand, optio stderr = appendBounded(stderr, chunk, maxOutputBytes); }); child.on("error", (error) => { - clearTimeout(timer); + clearTimers(); resolve({ command: command.command, args: command.args, cwd: options.cwd, exitCode: null, signal: null, stdout, stderr: appendBounded(stderr, error.message, maxOutputBytes), timedOut }); }); child.on("close", (exitCode, signal) => { - clearTimeout(timer); + clearTimers(); resolve({ command: command.command, args: command.args, cwd: options.cwd, exitCode, signal, stdout, stderr, timedOut }); }); }); diff --git a/tests/runner.test.ts b/tests/runner.test.ts new file mode 100644 index 0000000..f8d23da --- /dev/null +++ b/tests/runner.test.ts @@ -0,0 +1,52 @@ +import { chmodSync, existsSync, mkdtempSync, readdirSync, readFileSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import path from "node:path"; +import { describe, expect, test } from "vitest"; +import { initProject } from "../src/projects.js"; +import { executeRunLifecycle, prepareRun } from "../src/runner.js"; + +describe("runner", () => { + test("inspection modes do not write run cache files", () => { + const cwd = mkdtempSync(path.join(tmpdir(), "ogs-runner-")); + const { projectRoot } = initProject({ name: "Inspect Game", engine: "godot", mode: "prototype", nonInteractive: true }, cwd); + const runsDir = path.join(projectRoot, ".codex", "runs"); + const before = readdirSync(runsDir); + + const dryRun = prepareRun("gameplay-programmer", { project: projectRoot, task: "Inspect movement", dryRun: true }, cwd); + const printPrompt = prepareRun("gameplay-programmer", { project: projectRoot, task: "Inspect movement", printPrompt: true }, cwd); + + expect(readdirSync(runsDir)).toEqual(before); + expect(existsSync(dryRun.promptPath)).toBe(false); + expect(existsSync(dryRun.metadataPath)).toBe(false); + expect(existsSync(printPrompt.promptPath)).toBe(false); + expect(existsSync(printPrompt.metadataPath)).toBe(false); + }); + + test("review passes execute Codex with a read-only sandbox", async () => { + const cwd = mkdtempSync(path.join(tmpdir(), "ogs-review-")); + const { projectRoot } = initProject({ name: "Review Game", engine: "godot", mode: "prototype", nonInteractive: true }, cwd); + const log = path.join(cwd, "codex-invocations.jsonl"); + const stub = path.join(cwd, "codex-stub.mjs"); + writeFileSync( + stub, + `#!/usr/bin/env node +import { appendFileSync, readFileSync } from "node:fs"; +const input = readFileSync(0, "utf8"); +appendFileSync(${JSON.stringify(log)}, JSON.stringify({ args: process.argv.slice(2), input }) + "\\n"); +console.log(JSON.stringify({ blockers: [], warnings: [], summary: "ok", needsFix: false })); +` + ); + chmodSync(stub, 0o755); + + const run = prepareRun("gameplay-programmer", { project: projectRoot, task: "Implement movement", review: true, codexBin: stub }, cwd); + await executeRunLifecycle(run); + + const invocations = readFileSync(log, "utf8") + .trim() + .split("\n") + .map((line) => JSON.parse(line) as { args: string[]; input: string }); + expect(invocations).toHaveLength(2); + expect(invocations[0].args).toEqual(expect.arrayContaining(["--sandbox", "workspace-write"])); + expect(invocations[1].args).toEqual(expect.arrayContaining(["--sandbox", "read-only"])); + }); +}); diff --git a/tests/tasks.test.ts b/tests/tasks.test.ts new file mode 100644 index 0000000..9f4fdb4 --- /dev/null +++ b/tests/tasks.test.ts @@ -0,0 +1,14 @@ +import { existsSync, mkdtempSync } from "node:fs"; +import { tmpdir } from "node:os"; +import path from "node:path"; +import { describe, expect, test } from "vitest"; +import { createTask } from "../src/tasks.js"; + +describe("tasks", () => { + test("task creation requires a valid Codex studio project", () => { + const projectRoot = mkdtempSync(path.join(tmpdir(), "ogs-task-")); + + expect(() => createTask(projectRoot, { title: "Implement jump", role: "gameplay-programmer" })).toThrow(); + expect(existsSync(path.join(projectRoot, ".codex", "tasks.json"))).toBe(false); + }); +}); diff --git a/tests/verification.test.ts b/tests/verification.test.ts index 667a4c7..af2031f 100644 --- a/tests/verification.test.ts +++ b/tests/verification.test.ts @@ -27,6 +27,21 @@ describe("verification runner", () => { expect(noisy.stdout.length).toBeLessThanOrEqual(20); }); + test("escalates timed-out children that ignore SIGTERM", async () => { + const cwd = mkdtempSync(path.join(tmpdir(), "ogs-verify-")); + const script = path.join(cwd, "ignore-term.mjs"); + writeFileSync(script, "process.on('SIGTERM', () => {}); setInterval(() => {}, 1000);\n"); + const result = await Promise.race([ + runVerificationCommand({ command: process.execPath, args: [script] }, { cwd, timeoutMs: 200, killGraceMs: 50 }), + new Promise<"hung">((resolve) => setTimeout(() => resolve("hung"), 500)) + ]); + expect(result).not.toBe("hung"); + if (result !== "hung") { + expect(result.timedOut).toBe(true); + expect(result.signal).toBe("SIGKILL"); + } + }); + test("does not require shell scripts", async () => { const cwd = mkdtempSync(path.join(tmpdir(), "ogs-verify-")); const script = path.join(cwd, "ok");