From 15b8bb94e9f2c094ddc17105f87e4cfbdf8dc650 Mon Sep 17 00:00:00 2001 From: Merlin's Cat Date: Sat, 27 Jun 2026 00:05:15 +1000 Subject: [PATCH] chore: prepare Truthmark 2.2.6 (#28) * feat: add compact truth-doc prose guidance * chore: prepare Truthmark 2.2.6 * fix: preserve truth doc line discipline * docs: emphasize ongoing truth curation * docs(truth): add behavior scenarios to truth docs --------- Co-authored-by: MerlinH --- .../truthmark-document/support/procedure.md | 7 +- .../truthmark-sync/support/procedure.md | 6 + .antigravity/rules/truthmark-document.md | 7 +- .antigravity/rules/truthmark-sync.md | 6 + .../truthmark-document/support/procedure.md | 7 +- .../truthmark-sync/support/procedure.md | 6 + .../truthmark-document/support/procedure.md | 7 +- .../truthmark-sync/support/procedure.md | 6 + .../truthmark-document/support/procedure.md | 7 +- .../truthmark-sync/support/procedure.md | 6 + .../truthmark-document/support/procedure.md | 7 +- .../truthmark-sync/support/procedure.md | 6 + README.md | 8 +- changes/2026-06-26-version-2-2-6.md | 23 ++++ docs/architecture/product-boundary.md | 9 +- .../behaviors/check-diagnostics.md | 44 +++++-- .../behaviors/init-and-scaffold.md | 39 +++++- .../engineering/repository/README.md | 10 +- .../repository/bootstrap-routing.md | 7 +- .../engineering/repository/overview.md | 111 +++++++----------- .../repository/repository-intelligence.md | 57 ++++++--- .../workflows/installed-workflow-runtime.md | 14 ++- .../agent-native-workflow-injection.md | 13 +- .../templates/engineering-behavior.md | 10 ++ package-lock.json | 4 +- package.json | 2 +- src/agents/shared.ts | 10 +- src/agents/truth-sync.ts | 2 + src/templates/init-files.ts | 10 ++ tests/agents/truth-document.test.ts | 12 +- tests/agents/truth-sync.test.ts | 9 ++ tests/init/truth-doc-templates.test.ts | 42 +++++++ 32 files changed, 391 insertions(+), 123 deletions(-) create mode 100644 changes/2026-06-26-version-2-2-6.md create mode 100644 tests/init/truth-doc-templates.test.ts diff --git a/.agents/skills/truthmark-document/support/procedure.md b/.agents/skills/truthmark-document/support/procedure.md index eecba04..0698bab 100644 --- a/.agents/skills/truthmark-document/support/procedure.md +++ b/.agents/skills/truthmark-document/support/procedure.md @@ -60,7 +60,12 @@ Treat the HTML comments under each template section as normative authoring guida Align existing docs to that template and write or repair section content so it satisfies the comment guidance while preserving accurate authored content. If the template is missing, use lane-specific sections: product truth says what must be true and why; engineering truth says how the repository currently realizes it. Teams may edit template files under the configured Truthmark templates root to define their local truth-doc standards. -Prefer diff-friendly Markdown: one durable claim per bullet or line, paragraphs no longer than one or two short sentences, and bullets or tables for rules, criteria, fields, files, and lists. +Truth-doc prose style: +- Use professional, plain technical prose. Prefer specific current-state claims over promotional, symbolic, or generic significance language. +- Avoid common AI-writing tells: pivotal, crucial, underscores, serves as, stands as, showcases, landscape, vague expert attributions, and generic upbeat conclusions. +- Keep claims evidence-backed and diff-friendly: one durable claim per bullet or line; paragraphs should be no longer than one or two short sentences. +- Do not add personality, rhetorical flourish, first-person commentary, or marketing tone. +- Rewrite dense or formulaic prose only when it improves readability without removing scope, evidence, decisions, or source references. Truth-doc shape repair review: - Truth Document may restructure only truth docs for the implemented behavior being documented. - repair shape in place only after the ownership review confirms the doc is the right bounded owner diff --git a/.agents/skills/truthmark-sync/support/procedure.md b/.agents/skills/truthmark-sync/support/procedure.md index 29f5a3c..32ab187 100644 --- a/.agents/skills/truthmark-sync/support/procedure.md +++ b/.agents/skills/truthmark-sync/support/procedure.md @@ -32,6 +32,12 @@ Parent workflow: - No-update-needed rationale: why mapped truth is already current when no truth doc should change - Blockers: missing routing, ambiguous ownership, failed verification, unavailable evidence, or off-boundary write needs 11. Only edit allowed truth docs/routes after Sync Intent is clear; if ownership is ambiguous, repair topology first when the repair is safe and in scope, otherwise stop and recommend Truth Structure instead of guessing. +Truth-doc prose style: +- Use professional, plain technical prose. Prefer specific current-state claims over promotional, symbolic, or generic significance language. +- Avoid common AI-writing tells: pivotal, crucial, underscores, serves as, stands as, showcases, landscape, vague expert attributions, and generic upbeat conclusions. +- Keep claims evidence-backed and diff-friendly: one durable claim per bullet or line; paragraphs should be no longer than one or two short sentences. +- Do not add personality, rhetorical flourish, first-person commentary, or marketing tone. +- Rewrite dense or formulaic prose only when it improves readability without removing scope, evidence, decisions, or source references. Topology review and repair: - before updating truth docs, verify the changed code resolves to a specific behavior-owned area and bounded truth owner - if routing is missing, stale, broad, overloaded, catch-all route only, or cannot map changed code to a bounded truth owner, run Truth Structure before syncing when topology repair is safe and in scope diff --git a/.antigravity/rules/truthmark-document.md b/.antigravity/rules/truthmark-document.md index 6f58103..aae56c4 100644 --- a/.antigravity/rules/truthmark-document.md +++ b/.antigravity/rules/truthmark-document.md @@ -72,7 +72,12 @@ Treat the HTML comments under each template section as normative authoring guida Align existing docs to that template and write or repair section content so it satisfies the comment guidance while preserving accurate authored content. If the template is missing, use lane-specific sections: product truth says what must be true and why; engineering truth says how the repository currently realizes it. Teams may edit template files under the configured Truthmark templates root to define their local truth-doc standards. -Prefer diff-friendly Markdown: one durable claim per bullet or line, paragraphs no longer than one or two short sentences, and bullets or tables for rules, criteria, fields, files, and lists. +Truth-doc prose style: +- Use professional, plain technical prose. Prefer specific current-state claims over promotional, symbolic, or generic significance language. +- Avoid common AI-writing tells: pivotal, crucial, underscores, serves as, stands as, showcases, landscape, vague expert attributions, and generic upbeat conclusions. +- Keep claims evidence-backed and diff-friendly: one durable claim per bullet or line; paragraphs should be no longer than one or two short sentences. +- Do not add personality, rhetorical flourish, first-person commentary, or marketing tone. +- Rewrite dense or formulaic prose only when it improves readability without removing scope, evidence, decisions, or source references. Truth-doc shape repair review: - Truth Document may restructure only truth docs for the implemented behavior being documented. - repair shape in place only after the ownership review confirms the doc is the right bounded owner diff --git a/.antigravity/rules/truthmark-sync.md b/.antigravity/rules/truthmark-sync.md index d44e168..67cc658 100644 --- a/.antigravity/rules/truthmark-sync.md +++ b/.antigravity/rules/truthmark-sync.md @@ -44,6 +44,12 @@ Parent workflow: - No-update-needed rationale: why mapped truth is already current when no truth doc should change - Blockers: missing routing, ambiguous ownership, failed verification, unavailable evidence, or off-boundary write needs 11. Only edit allowed truth docs/routes after Sync Intent is clear; if ownership is ambiguous, repair topology first when the repair is safe and in scope, otherwise stop and recommend Truth Structure instead of guessing. +Truth-doc prose style: +- Use professional, plain technical prose. Prefer specific current-state claims over promotional, symbolic, or generic significance language. +- Avoid common AI-writing tells: pivotal, crucial, underscores, serves as, stands as, showcases, landscape, vague expert attributions, and generic upbeat conclusions. +- Keep claims evidence-backed and diff-friendly: one durable claim per bullet or line; paragraphs should be no longer than one or two short sentences. +- Do not add personality, rhetorical flourish, first-person commentary, or marketing tone. +- Rewrite dense or formulaic prose only when it improves readability without removing scope, evidence, decisions, or source references. Topology review and repair: - before updating truth docs, verify the changed code resolves to a specific behavior-owned area and bounded truth owner - if routing is missing, stale, broad, overloaded, catch-all route only, or cannot map changed code to a bounded truth owner, run Truth Structure before syncing when topology repair is safe and in scope diff --git a/.claude/skills/truthmark-document/support/procedure.md b/.claude/skills/truthmark-document/support/procedure.md index eecba04..0698bab 100644 --- a/.claude/skills/truthmark-document/support/procedure.md +++ b/.claude/skills/truthmark-document/support/procedure.md @@ -60,7 +60,12 @@ Treat the HTML comments under each template section as normative authoring guida Align existing docs to that template and write or repair section content so it satisfies the comment guidance while preserving accurate authored content. If the template is missing, use lane-specific sections: product truth says what must be true and why; engineering truth says how the repository currently realizes it. Teams may edit template files under the configured Truthmark templates root to define their local truth-doc standards. -Prefer diff-friendly Markdown: one durable claim per bullet or line, paragraphs no longer than one or two short sentences, and bullets or tables for rules, criteria, fields, files, and lists. +Truth-doc prose style: +- Use professional, plain technical prose. Prefer specific current-state claims over promotional, symbolic, or generic significance language. +- Avoid common AI-writing tells: pivotal, crucial, underscores, serves as, stands as, showcases, landscape, vague expert attributions, and generic upbeat conclusions. +- Keep claims evidence-backed and diff-friendly: one durable claim per bullet or line; paragraphs should be no longer than one or two short sentences. +- Do not add personality, rhetorical flourish, first-person commentary, or marketing tone. +- Rewrite dense or formulaic prose only when it improves readability without removing scope, evidence, decisions, or source references. Truth-doc shape repair review: - Truth Document may restructure only truth docs for the implemented behavior being documented. - repair shape in place only after the ownership review confirms the doc is the right bounded owner diff --git a/.claude/skills/truthmark-sync/support/procedure.md b/.claude/skills/truthmark-sync/support/procedure.md index 29f5a3c..32ab187 100644 --- a/.claude/skills/truthmark-sync/support/procedure.md +++ b/.claude/skills/truthmark-sync/support/procedure.md @@ -32,6 +32,12 @@ Parent workflow: - No-update-needed rationale: why mapped truth is already current when no truth doc should change - Blockers: missing routing, ambiguous ownership, failed verification, unavailable evidence, or off-boundary write needs 11. Only edit allowed truth docs/routes after Sync Intent is clear; if ownership is ambiguous, repair topology first when the repair is safe and in scope, otherwise stop and recommend Truth Structure instead of guessing. +Truth-doc prose style: +- Use professional, plain technical prose. Prefer specific current-state claims over promotional, symbolic, or generic significance language. +- Avoid common AI-writing tells: pivotal, crucial, underscores, serves as, stands as, showcases, landscape, vague expert attributions, and generic upbeat conclusions. +- Keep claims evidence-backed and diff-friendly: one durable claim per bullet or line; paragraphs should be no longer than one or two short sentences. +- Do not add personality, rhetorical flourish, first-person commentary, or marketing tone. +- Rewrite dense or formulaic prose only when it improves readability without removing scope, evidence, decisions, or source references. Topology review and repair: - before updating truth docs, verify the changed code resolves to a specific behavior-owned area and bounded truth owner - if routing is missing, stale, broad, overloaded, catch-all route only, or cannot map changed code to a bounded truth owner, run Truth Structure before syncing when topology repair is safe and in scope diff --git a/.cursor/skills/truthmark-document/support/procedure.md b/.cursor/skills/truthmark-document/support/procedure.md index eecba04..0698bab 100644 --- a/.cursor/skills/truthmark-document/support/procedure.md +++ b/.cursor/skills/truthmark-document/support/procedure.md @@ -60,7 +60,12 @@ Treat the HTML comments under each template section as normative authoring guida Align existing docs to that template and write or repair section content so it satisfies the comment guidance while preserving accurate authored content. If the template is missing, use lane-specific sections: product truth says what must be true and why; engineering truth says how the repository currently realizes it. Teams may edit template files under the configured Truthmark templates root to define their local truth-doc standards. -Prefer diff-friendly Markdown: one durable claim per bullet or line, paragraphs no longer than one or two short sentences, and bullets or tables for rules, criteria, fields, files, and lists. +Truth-doc prose style: +- Use professional, plain technical prose. Prefer specific current-state claims over promotional, symbolic, or generic significance language. +- Avoid common AI-writing tells: pivotal, crucial, underscores, serves as, stands as, showcases, landscape, vague expert attributions, and generic upbeat conclusions. +- Keep claims evidence-backed and diff-friendly: one durable claim per bullet or line; paragraphs should be no longer than one or two short sentences. +- Do not add personality, rhetorical flourish, first-person commentary, or marketing tone. +- Rewrite dense or formulaic prose only when it improves readability without removing scope, evidence, decisions, or source references. Truth-doc shape repair review: - Truth Document may restructure only truth docs for the implemented behavior being documented. - repair shape in place only after the ownership review confirms the doc is the right bounded owner diff --git a/.cursor/skills/truthmark-sync/support/procedure.md b/.cursor/skills/truthmark-sync/support/procedure.md index 29f5a3c..32ab187 100644 --- a/.cursor/skills/truthmark-sync/support/procedure.md +++ b/.cursor/skills/truthmark-sync/support/procedure.md @@ -32,6 +32,12 @@ Parent workflow: - No-update-needed rationale: why mapped truth is already current when no truth doc should change - Blockers: missing routing, ambiguous ownership, failed verification, unavailable evidence, or off-boundary write needs 11. Only edit allowed truth docs/routes after Sync Intent is clear; if ownership is ambiguous, repair topology first when the repair is safe and in scope, otherwise stop and recommend Truth Structure instead of guessing. +Truth-doc prose style: +- Use professional, plain technical prose. Prefer specific current-state claims over promotional, symbolic, or generic significance language. +- Avoid common AI-writing tells: pivotal, crucial, underscores, serves as, stands as, showcases, landscape, vague expert attributions, and generic upbeat conclusions. +- Keep claims evidence-backed and diff-friendly: one durable claim per bullet or line; paragraphs should be no longer than one or two short sentences. +- Do not add personality, rhetorical flourish, first-person commentary, or marketing tone. +- Rewrite dense or formulaic prose only when it improves readability without removing scope, evidence, decisions, or source references. Topology review and repair: - before updating truth docs, verify the changed code resolves to a specific behavior-owned area and bounded truth owner - if routing is missing, stale, broad, overloaded, catch-all route only, or cannot map changed code to a bounded truth owner, run Truth Structure before syncing when topology repair is safe and in scope diff --git a/.github/skills/truthmark-document/support/procedure.md b/.github/skills/truthmark-document/support/procedure.md index eecba04..0698bab 100644 --- a/.github/skills/truthmark-document/support/procedure.md +++ b/.github/skills/truthmark-document/support/procedure.md @@ -60,7 +60,12 @@ Treat the HTML comments under each template section as normative authoring guida Align existing docs to that template and write or repair section content so it satisfies the comment guidance while preserving accurate authored content. If the template is missing, use lane-specific sections: product truth says what must be true and why; engineering truth says how the repository currently realizes it. Teams may edit template files under the configured Truthmark templates root to define their local truth-doc standards. -Prefer diff-friendly Markdown: one durable claim per bullet or line, paragraphs no longer than one or two short sentences, and bullets or tables for rules, criteria, fields, files, and lists. +Truth-doc prose style: +- Use professional, plain technical prose. Prefer specific current-state claims over promotional, symbolic, or generic significance language. +- Avoid common AI-writing tells: pivotal, crucial, underscores, serves as, stands as, showcases, landscape, vague expert attributions, and generic upbeat conclusions. +- Keep claims evidence-backed and diff-friendly: one durable claim per bullet or line; paragraphs should be no longer than one or two short sentences. +- Do not add personality, rhetorical flourish, first-person commentary, or marketing tone. +- Rewrite dense or formulaic prose only when it improves readability without removing scope, evidence, decisions, or source references. Truth-doc shape repair review: - Truth Document may restructure only truth docs for the implemented behavior being documented. - repair shape in place only after the ownership review confirms the doc is the right bounded owner diff --git a/.github/skills/truthmark-sync/support/procedure.md b/.github/skills/truthmark-sync/support/procedure.md index 29f5a3c..32ab187 100644 --- a/.github/skills/truthmark-sync/support/procedure.md +++ b/.github/skills/truthmark-sync/support/procedure.md @@ -32,6 +32,12 @@ Parent workflow: - No-update-needed rationale: why mapped truth is already current when no truth doc should change - Blockers: missing routing, ambiguous ownership, failed verification, unavailable evidence, or off-boundary write needs 11. Only edit allowed truth docs/routes after Sync Intent is clear; if ownership is ambiguous, repair topology first when the repair is safe and in scope, otherwise stop and recommend Truth Structure instead of guessing. +Truth-doc prose style: +- Use professional, plain technical prose. Prefer specific current-state claims over promotional, symbolic, or generic significance language. +- Avoid common AI-writing tells: pivotal, crucial, underscores, serves as, stands as, showcases, landscape, vague expert attributions, and generic upbeat conclusions. +- Keep claims evidence-backed and diff-friendly: one durable claim per bullet or line; paragraphs should be no longer than one or two short sentences. +- Do not add personality, rhetorical flourish, first-person commentary, or marketing tone. +- Rewrite dense or formulaic prose only when it improves readability without removing scope, evidence, decisions, or source references. Topology review and repair: - before updating truth docs, verify the changed code resolves to a specific behavior-owned area and bounded truth owner - if routing is missing, stale, broad, overloaded, catch-all route only, or cannot map changed code to a bounded truth owner, run Truth Structure before syncing when topology repair is safe and in scope diff --git a/.opencode/skills/truthmark-document/support/procedure.md b/.opencode/skills/truthmark-document/support/procedure.md index eecba04..0698bab 100644 --- a/.opencode/skills/truthmark-document/support/procedure.md +++ b/.opencode/skills/truthmark-document/support/procedure.md @@ -60,7 +60,12 @@ Treat the HTML comments under each template section as normative authoring guida Align existing docs to that template and write or repair section content so it satisfies the comment guidance while preserving accurate authored content. If the template is missing, use lane-specific sections: product truth says what must be true and why; engineering truth says how the repository currently realizes it. Teams may edit template files under the configured Truthmark templates root to define their local truth-doc standards. -Prefer diff-friendly Markdown: one durable claim per bullet or line, paragraphs no longer than one or two short sentences, and bullets or tables for rules, criteria, fields, files, and lists. +Truth-doc prose style: +- Use professional, plain technical prose. Prefer specific current-state claims over promotional, symbolic, or generic significance language. +- Avoid common AI-writing tells: pivotal, crucial, underscores, serves as, stands as, showcases, landscape, vague expert attributions, and generic upbeat conclusions. +- Keep claims evidence-backed and diff-friendly: one durable claim per bullet or line; paragraphs should be no longer than one or two short sentences. +- Do not add personality, rhetorical flourish, first-person commentary, or marketing tone. +- Rewrite dense or formulaic prose only when it improves readability without removing scope, evidence, decisions, or source references. Truth-doc shape repair review: - Truth Document may restructure only truth docs for the implemented behavior being documented. - repair shape in place only after the ownership review confirms the doc is the right bounded owner diff --git a/.opencode/skills/truthmark-sync/support/procedure.md b/.opencode/skills/truthmark-sync/support/procedure.md index 29f5a3c..32ab187 100644 --- a/.opencode/skills/truthmark-sync/support/procedure.md +++ b/.opencode/skills/truthmark-sync/support/procedure.md @@ -32,6 +32,12 @@ Parent workflow: - No-update-needed rationale: why mapped truth is already current when no truth doc should change - Blockers: missing routing, ambiguous ownership, failed verification, unavailable evidence, or off-boundary write needs 11. Only edit allowed truth docs/routes after Sync Intent is clear; if ownership is ambiguous, repair topology first when the repair is safe and in scope, otherwise stop and recommend Truth Structure instead of guessing. +Truth-doc prose style: +- Use professional, plain technical prose. Prefer specific current-state claims over promotional, symbolic, or generic significance language. +- Avoid common AI-writing tells: pivotal, crucial, underscores, serves as, stands as, showcases, landscape, vague expert attributions, and generic upbeat conclusions. +- Keep claims evidence-backed and diff-friendly: one durable claim per bullet or line; paragraphs should be no longer than one or two short sentences. +- Do not add personality, rhetorical flourish, first-person commentary, or marketing tone. +- Rewrite dense or formulaic prose only when it improves readability without removing scope, evidence, decisions, or source references. Topology review and repair: - before updating truth docs, verify the changed code resolves to a specific behavior-owned area and bounded truth owner - if routing is missing, stale, broad, overloaded, catch-all route only, or cannot map changed code to a bounded truth owner, run Truth Structure before syncing when topology repair is safe and in scope diff --git a/README.md b/README.md index 33c4367..73cf5c7 100644 --- a/README.md +++ b/README.md @@ -59,10 +59,12 @@ AI coding agents are incredible at writing code fast. But this speed creates a d ## 🎯 The Solution: Truthmark -**Truthmark** installs a Git-native workflow layer into your repository. It fixes the part of AI development that usually breaks: helping the documentation stay aligned with the code. +**Truthmark** installs a Git-native workflow layer into your repository. It fixes the part of AI development that usually breaks: keeping documentation aligned with code after the first draft. Instead of hoping humans and AI agents remember to update docs, Truthmark makes documentation a systematic, reviewable habit right inside your repo. +Truthmark is not a one-shot docs generator. It is an ongoing truth-doc curation loop that keeps human-facing docs small, owned, evidence-backed, and reviewable as agents keep changing code. + ### ✨ Why Truthmark is Unique Truthmark isn't just another documentation tool. It is deeply integrated into the AI workflow: @@ -70,6 +72,7 @@ Truthmark isn't just another documentation tool. It is deeply integrated into th * **🚫 Zero Vendor Lock-in:** No hosted services, no hidden databases, no extra servers to operate. * **🌳 100% Git-Native:** Everything lives in your repository. The truth moves with your branch. * **🤝 Human-owned, agent-followed contract:** Maintainers own the repo contract; agents follow the installed instructions while coding. +* **🧭 Ongoing truth curation:** Broad or messy docs are routed toward Structure instead of becoming giant catch-all files. * **✅ Trust Through Verification:** AI work becomes easier to trust because behavior-changing work includes a human-reviewable truth-doc decision or diff. ## 🔄 How It Works @@ -122,6 +125,7 @@ Truth Structure is not a day-to-day command; it repairs routing or ownership onl | Human CLI | Gives maintainers setup, refresh, validation, and inspection commands. | | Installed agent guidance | Tells coding agents when to document, test, sync truth, audit, or stop for review. | | Explicit routing | Maps code areas to canonical truth docs. | +| Durable truth curation | Keeps docs bounded, evidence-backed, and reviewable instead of letting them grow into catch-all files. | | Reviewable handoffs | Produces ordinary Git diffs for both code and truth docs. | | Local-first operation | Requires no hosted service, daemon, database, or MCP server. | | Safer write boundaries | Separates code-first, doc-first, read-only, and doc-only workflows. | @@ -154,6 +158,8 @@ Not governance as ceremony. Governance as a simple question: Truthmark helps teams answer that with committed files, explicit routing, and reviewable diffs. +Most AI tools can draft documentation. Truthmark keeps repository truth curated after the draft, after the next code change, and after the doc starts getting too broad. + It is useful when you need: - less documentation drift diff --git a/changes/2026-06-26-version-2-2-6.md b/changes/2026-06-26-version-2-2-6.md new file mode 100644 index 0000000..8be211c --- /dev/null +++ b/changes/2026-06-26-version-2-2-6.md @@ -0,0 +1,23 @@ +# Version 2.2.6 + +Previous version: 2.2.5 +New version: 2.2.6 +Diff basis: release/2.2.5-2..HEAD plus working tree +Version action: patch +SemVer rationale: This release is a backward-compatible patch that improves shipped workflow guidance for truth-doc prose without changing CLI command shape, config schema, or report contracts. + +Release payload: +- Add compact professional prose guidance to Truth Document and Truth Sync so generated truth-doc edits avoid AI-style padding, keep one durable claim per bullet or line, and limit paragraphs to one or two short sentences. +- Regenerate configured host workflow procedures for Codex, OpenCode, Claude Code, GitHub Copilot, Antigravity, and Cursor. +- Record the compact-humanizer adaptation decision in product and engineering truth docs. +- Emphasize ongoing truth-doc curation in the English README and product truth docs; localized README variants intentionally remain for a later translation pass. + +User-facing release text: +- Truth Document and Truth Sync now guide agents toward plain professional truth-doc prose, avoiding AI-sounding filler without importing a token-heavy humanizer prompt or changing workflow contracts. +- The README now presents ongoing truth-doc curation as Truthmark's main differentiator: keeping docs bounded, evidence-backed, and reviewable after each code change. + +Verification: +- `npm run release:check` passed: lint, format check, typecheck, 337 tests, build, package check, and audit with 0 vulnerabilities. +- `npx vitest run tests/product-boundary.test.ts tests/truth/docs.test.ts tests/package-files.test.ts` passed: 6 tests. +- `npx tsx src/cli/main.ts check --json` passed with no diagnostics. +- `npx tsx src/cli/main.ts index --json` passed with no diagnostics. diff --git a/docs/architecture/product-boundary.md b/docs/architecture/product-boundary.md index 97ab9e1..0f74e88 100644 --- a/docs/architecture/product-boundary.md +++ b/docs/architecture/product-boundary.md @@ -1,7 +1,7 @@ --- status: active doc_type: architecture -last_reviewed: 2026-06-12 +last_reviewed: 2026-06-26 source_of_truth: - ../../README.md - ../truthmark/product/capabilities/agent-native-workflow-injection.md @@ -33,6 +33,10 @@ Truthmark keeps repository documentation aligned with agent-made code changes so Canonical truth documents are human-facing Git-review artifacts. Human maintainers are the primary reviewers; agents write and maintain truth docs, but agents are not the only consumers. +Truthmark's product value is ongoing truth-doc curation, not one-shot documentation generation. + +Truthmark keeps truth docs bounded, evidence-backed, and reviewable as agents continue changing code. + Truth-doc structure, wording, and style must be friendly for humans to read and understand. Human-friendly truth docs: @@ -86,6 +90,7 @@ Optional integrations are acceptable only when they preserve host-native agent w 6. **Human review stays central.** Truthmark produces reviewable documentation changes, not silent approval or merge authority. 7. **Local-first simplicity wins.** Add dependencies, services, or runtime layers only when they preserve the no-blockade repository-file workflow. 8. **Truth docs stay human-friendly.** Truth docs must be structured and written for maintainers to review, scan, and understand before they are optimized for agent or machine consumption. +9. **Curation beats generation.** Truthmark should route overgrown or mixed-owner docs toward Structure instead of rewarding more appended prose. ## Required Product Boundary Check @@ -107,6 +112,8 @@ A plan that cannot answer these questions is not ready for implementation. - Decision (2026-06-12): Repository rules cite this document so agents must check product boundaries before generating new designs or plans. - Decision (2026-06-12): Truthmark workflows must stay 100% operational from repository files and host-native agent surfaces; missing packages, CLIs, daemons, services, or plugins must not block normal workflow execution. - Decision (2026-06-12): Human-facing readability is part of the Truthmark product boundary for canonical truth documents. +- Decision (2026-06-26): Ongoing truth-doc curation is a primary product value. + - Marketing should emphasize bounded ownership, evidence-backed updates, Git-reviewable docs, and Structure handoff for overgrown docs instead of generic documentation generation. ## Maintenance Notes diff --git a/docs/truthmark/engineering/behaviors/check-diagnostics.md b/docs/truthmark/engineering/behaviors/check-diagnostics.md index c276f73..dff9ce4 100644 --- a/docs/truthmark/engineering/behaviors/check-diagnostics.md +++ b/docs/truthmark/engineering/behaviors/check-diagnostics.md @@ -1,7 +1,7 @@ --- status: active truth_kind: engineering-behavior -last_reviewed: 2026-06-20 +last_reviewed: 2026-06-26 --- # Check Diagnostics @@ -49,6 +49,29 @@ It covers route coverage, lane shape, lane drift, traceability, frontmatter, gen - Duplicate route entries for the same path, kind, and lane merge `realized_by`, `realizes`, and `depends_on` by unique sorted set. - Check reports structure and evidence only; it does not judge product strategy. +## Behavior Scenarios + +#### Scenario: Generated surface drift is review-only + +- **GIVEN** a committed generated workflow surface differs from the current renderer output +- **WHEN** `truthmark check` compares rendered surfaces with checked-in files +- **THEN** it reports a `generated-surface` review diagnostic for the stale path +- **AND** it does not mutate files during the check + +#### Scenario: Route relationship metadata stays in route YAML + +- **GIVEN** a truth document frontmatter block declares `realized_by`, `realizes`, or `depends_on` +- **WHEN** `truthmark check` validates frontmatter +- **THEN** it reports the relationship metadata as invalid frontmatter +- **AND** keeps relationship authority in fenced route YAML entries + +#### Scenario: Duplicate route entries merge compatible relationships + +- **GIVEN** route files contain duplicate entries for the same truth document path, kind, and lane +- **WHEN** Check validates route traceability +- **THEN** it merges `realized_by`, `realizes`, and `depends_on` metadata by unique sorted set +- **AND** conflicting duplicate kinds or lanes remain area-index errors. + ## Flows And States - Check loads config and routed truth docs from the active checkout. @@ -91,13 +114,12 @@ Update when check categories, severity rules, lane audit behavior, or product ki ## Source References -- ../../../../src/checks/check.ts -- ../../../../src/checks/areas.ts -- ../../../../src/checks/decisions.ts -- ../../../../src/checks/frontmatter.ts -- ../../../../tests/checks/frontmatter.test.ts -- `src/checks/areas.ts` -- `src/checks/decisions.ts` -- `src/checks/frontmatter.ts` -- `tests/checks/frontmatter.test.ts` -- `src/output/diagnostic.ts` +- src/checks/check.ts +- src/checks/areas.ts +- src/checks/decisions.ts +- src/checks/frontmatter.ts +- src/checks/generated-surfaces.ts +- src/output/diagnostic.ts +- tests/checks/check.test.ts +- tests/checks/frontmatter.test.ts +- tests/templates/generated-surfaces.test.ts diff --git a/docs/truthmark/engineering/behaviors/init-and-scaffold.md b/docs/truthmark/engineering/behaviors/init-and-scaffold.md index 5fdc9f6..2ebed5c 100644 --- a/docs/truthmark/engineering/behaviors/init-and-scaffold.md +++ b/docs/truthmark/engineering/behaviors/init-and-scaffold.md @@ -1,7 +1,7 @@ --- status: active truth_kind: engineering-behavior -last_reviewed: 2026-06-21 +last_reviewed: 2026-06-26 --- # Init And Scaffold @@ -61,6 +61,13 @@ Those files may contain user-owned instructions alongside old Truthmark injectio Generated truth-doc templates keep kind-specific and section-specific authoring comments in the template files. +Engineering behavior templates include a `Behavior Scenarios` section after `Core Rules`: + +- Scenario blocks are optional and clarify normal, fallback, or compatibility-critical behavior. +- Scenario bullets use `GIVEN`, `WHEN`, `THEN`, and optional `AND` labels. +- Scenario guidance frames entries as current implemented truth rather than future requirements. +- Scenario bullets do not replace source-backed behavior claims or Source References. + Global diff-friendly authoring style lives in the Truth Document workflow procedure rather than in every template preamble: - Prefer one durable claim per bullet or line. @@ -92,9 +99,33 @@ Capability docs own: - Scaffolded paths derive from `truthmark.workspace`. - Template filenames match `truth_kind` values. +- Engineering behavior templates provide optional current-state scenario blocks for normal, fallback, or compatibility-critical behavior. - Fresh configs do not assume any AI host platform. - Global prose style guidance belongs in writer-facing workflow procedures, not every truth-doc template preamble. +## Behavior Scenarios + +#### Scenario: Fresh config does not assume a host platform + +- **GIVEN** a repository uses the default generated Truthmark config +- **WHEN** `truthmark init` creates or refreshes the scaffold +- **THEN** `platforms` remains omitted by default +- **AND** host-specific workflow surfaces require explicit platform configuration + +#### Scenario: Retired Gemini surfaces are preserved for manual cleanup + +- **GIVEN** a repository contains retired Gemini instruction or command surfaces +- **WHEN** `truthmark init` removes auto-removable retired generated artifacts +- **THEN** it leaves `GEMINI.md` and `.gemini/**` in place +- **AND** check diagnostics tell maintainers to review stale Gemini guidance manually + +#### Scenario: Engineering behavior templates support compact scenarios + +- **GIVEN** Truthmark renders the editable `engineering-behavior.md` template +- **WHEN** maintainers create or refresh truth-doc templates +- **THEN** the template includes an optional `Behavior Scenarios` section after `Core Rules` +- **AND** the guidance frames scenarios as current implemented truth rather than `SHALL`-style future requirements + ## Flows And States - `truthmark init` creates or refreshes workspace scaffold files. @@ -121,11 +152,16 @@ Capability docs own: - Decision (2026-06-18): Fresh configs omit `platforms` by default. - Truthmark does not infer Codex, OpenCode, or any other host from a fresh checkout; host-native workflow surfaces require explicit platform configuration. - Decision (2026-06-21): Init does not delete retired Gemini surfaces automatically; users remove stale injected Gemini guidance manually after reviewing `GEMINI.md` and `.gemini/**`. +- Decision (2026-06-26): Engineering behavior templates may use compact scenario blocks for behavior clarity. + - Scenario guidance adopts the useful requirement/scenario shape from specification formats while preserving Truthmark's current-state, evidence-backed truth-doc role. + - The template avoids `SHALL`-style future requirements and does not require a scenario for every rule. ## Rationale Fixed workspace-derived scaffold paths keep Truthmark predictable while route files provide the semantic ownership layer. +Optional scenario blocks make normal and fallback behavior easier to review in Git without turning truth docs into future-looking requirement specs. + Keeping templates kind-specific and moving global prose style into workflow guidance reduces generated-template bloat. ## Non-Goals @@ -145,3 +181,4 @@ Update when init writes new files, changes default paths, changes template filen - ../../../../src/init/hierarchy.ts - ../../../../src/templates/init-files.ts - ../../../../tests/init/init-instructions.test.ts +- ../../../../tests/init/truth-doc-templates.test.ts diff --git a/docs/truthmark/engineering/repository/README.md b/docs/truthmark/engineering/repository/README.md index 3034d8d..45d6587 100644 --- a/docs/truthmark/engineering/repository/README.md +++ b/docs/truthmark/engineering/repository/README.md @@ -1,6 +1,6 @@ --- status: active -last_reviewed: 2026-06-14 +last_reviewed: 2026-06-26 --- # Repository Truth Docs @@ -11,8 +11,12 @@ README.md files are indexes, not Truth Sync targets. Keep bounded truth in leaf Current leaf docs: -- [Overview](overview.md) +- [Repository Bootstrap Routing](bootstrap-routing.md) — provisional broad-route handoff for fresh or under-structured repositories. +- [Repository Intelligence](repository-intelligence.md) — RepoIndex, RouteMap, ImpactSet, evidence, freshness, and WorkflowState behavior. +- [Repository Overview](overview.md) — guardrail that prevents broad repository overviews from becoming catch-all implementation truth. ## Source References -- ../../routes/areas/repository.md +- docs/truthmark/engineering/repository/bootstrap-routing.md +- docs/truthmark/engineering/repository/repository-intelligence.md +- docs/truthmark/engineering/repository/overview.md diff --git a/docs/truthmark/engineering/repository/bootstrap-routing.md b/docs/truthmark/engineering/repository/bootstrap-routing.md index 2d12bb7..1fe0e9a 100644 --- a/docs/truthmark/engineering/repository/bootstrap-routing.md +++ b/docs/truthmark/engineering/repository/bootstrap-routing.md @@ -1,7 +1,7 @@ --- status: active truth_kind: engineering-workflow -last_reviewed: 2026-06-17 +last_reviewed: 2026-06-26 --- # Repository Bootstrap Routing @@ -81,5 +81,6 @@ Keep this doc short. When a repository has real bounded routes, prefer updating ## Source References -- ../../routes/areas/repository.md -- ../../../../.truthmark/config.yml +- docs/truthmark/engineering/behaviors/init-and-scaffold.md +- src/templates/init-files.ts +- .truthmark/config.yml diff --git a/docs/truthmark/engineering/repository/overview.md b/docs/truthmark/engineering/repository/overview.md index e7b72db..4530408 100644 --- a/docs/truthmark/engineering/repository/overview.md +++ b/docs/truthmark/engineering/repository/overview.md @@ -1,111 +1,90 @@ --- status: active truth_kind: engineering-behavior -last_reviewed: 2026-06-20 +last_reviewed: 2026-06-26 --- # Repository Overview ## Purpose - - -Describe why the default repository behavior surface exists and what outcome it protects. +This doc records the repository-directory guardrail that broad repository docs are indexes or handoffs, not catch-all implementation truth. ## Scope - +It covers the repository truth-doc directory shape and the handoff away from legacy broad overview ownership. -This bounded leaf truth doc owns the default repository behavior surface created by Truthmark. - -This doc was created from the editable engineering-behavior template at docs/truthmark/templates/engineering-behavior.md. +It does not own implementation behavior under `src/**`, route-map behavior, or repository-intelligence output details. ## Current Implementation Behavior - - -- Document current behavior here when implementation changes make repository truth incomplete. +- Truthmark no longer treats this file as the default behavior owner for broad repository code surfaces. +- Init uses `engineering/repository/bootstrap-routing.md` as the provisional broad-route handoff when a fresh repository needs initial routeability. +- Normal behavior truth belongs in bounded route-owned leaf docs after Truth Structure identifies the durable owner. +- Repository-intelligence behavior lives in `engineering/repository/repository-intelligence.md`. +- README files in truth-doc directories remain indexes instead of Truth Sync targets. ## Core Rules - +- Do not append unrelated implementation behavior to this overview. +- Use `bootstrap-routing.md` when the repository still needs a provisional broad-route handoff. +- Use bounded route-owned truth docs for real implementation behavior. +- Use `repository-intelligence.md` for RepoIndex, RouteMap, ImpactSet, evidence, freshness, and WorkflowState behavior. -- Truth README files are indexes; behavior truth belongs in bounded leaf docs. +## Behavior Scenarios + +#### Scenario: Broad default routing does not expand the overview + +- **GIVEN** a real code change maps only to a provisional broad repository route +- **WHEN** Truth Sync cannot identify a bounded truth owner safely +- **THEN** agents run or recommend Truth Structure before updating behavior truth +- **AND** they do not append implementation claims to this overview + +#### Scenario: Repository truth docs stay indexable by bounded owner + +- **GIVEN** a maintainer opens the repository truth-doc directory +- **WHEN** they choose a target truth doc for repository behavior +- **THEN** the directory index points to bounded leaf docs and bootstrap handoffs +- **AND** this overview remains a guardrail against catch-all behavior prose ## Flows And States - - -- None beyond current behavior. +- None beyond the broad-overview-to-bounded-owner handoff described above. ## Contracts - - -- External contracts should link to the nearest canonical contract doc when one exists. +- Route metadata and check diagnostics are owned by `docs/truthmark/engineering/contracts/config-route-and-check-contracts.md`. +- Repository-intelligence JSON contracts are owned by `docs/truthmark/engineering/contracts/config-route-and-check-contracts.md`. ## Product Truth Links -- None. +- None. This is an internal engineering guardrail. ## Engineering Decisions - - -- Decision (2026-06-14): Truth README files are indexes; behavior truth belongs in bounded leaf docs. +- Decision (2026-06-26): The repository overview is a guardrail against catch-all truth ownership, not the default behavior owner. + - Init creates `bootstrap-routing.md` for provisional broad routes. + - Truth Structure creates or repairs bounded owners before normal Truth Sync writes behavior details. ## Rationale - +Broad overview docs tend to accumulate unrelated behavior and become hard to review in Git. -Bounded leaf docs keep agent context focused and prevent large products from accumulating unreviewable feature manuals. +Keeping this file as a narrow guardrail preserves the old path's intent while directing real behavior to bounded owners. ## Non-Goals - - -- This doc is not a catch-all for unrelated repository behavior. +- This doc is not a catch-all for repository behavior. +- This doc is not a route-map, impact, or workflow-state behavior owner. +- This doc is not a product capability or external contract. ## Maintenance Notes - - -- Update this doc when routed implementation changes alter current behavior, rules, contracts, or decisions. +Update this doc only when repository-directory ownership, bootstrap handoff behavior, or broad-overview retirement behavior changes. ## Source References -- ../../routes/areas/repository.md +- docs/truthmark/engineering/repository/bootstrap-routing.md +- docs/truthmark/engineering/repository/repository-intelligence.md +- docs/truthmark/engineering/behaviors/init-and-scaffold.md +- docs/truthmark/engineering/repository/README.md diff --git a/docs/truthmark/engineering/repository/repository-intelligence.md b/docs/truthmark/engineering/repository/repository-intelligence.md index fbe530f..484a340 100644 --- a/docs/truthmark/engineering/repository/repository-intelligence.md +++ b/docs/truthmark/engineering/repository/repository-intelligence.md @@ -1,7 +1,7 @@ --- status: active truth_kind: engineering-behavior -last_reviewed: 2026-06-21 +last_reviewed: 2026-06-26 --- # Repository Intelligence @@ -69,6 +69,29 @@ It covers RepoIndex, RouteMap, ImpactSet, evidence validation, freshness, and Wo - WorkflowState and ImpactSet expose paths, metadata, diagnostics, and checklists without embedding source-file or truth-doc bodies. - Route relationships remain route-local metadata. +## Behavior Scenarios + +#### Scenario: Impact maps branch changes to review focus + +- **GIVEN** a branch changes source, test, route, or truth-document paths +- **WHEN** Truthmark builds an ImpactSet for the branch +- **THEN** it reports affected routes, affected truth docs, affected tests, and unmapped functional-code diagnostics +- **AND** it does not infer TypeScript public-symbol changes through language import parsing + +#### Scenario: Workflow status keeps stale candidates signal-based + +- **GIVEN** a changed file maps to primary truth docs and no concrete stale-truth signal names another doc +- **WHEN** Sync action context is built +- **THEN** `candidateStaleTruthDocs` remains empty +- **AND** agents may still inspect another document only when direct checkout evidence reveals a stale claim + +#### Scenario: Evidence validation stays repository-contained + +- **GIVEN** truth evidence names a repository path, glob, line span, or `sha256:` hash +- **WHEN** Truthmark validates evidence +- **THEN** it checks repository containment and referenced file or glob existence +- **AND** it treats optional `symbol` metadata as non-normative metadata rather than TypeScript-specific proof + ## Flows And States - RepoIndex and RouteMap are built from committed repository files. @@ -119,21 +142,17 @@ Update when index, route-map, impact, evidence, freshness, or workflow-state out ## Source References -- ../../../../src/repo-index/build.ts -- ../../../../src/repo-index/file-tree.ts -- ../../../../src/repo-index/route-map.ts -- ../../../../src/repo-index/types.ts -- ../../../../src/impact/build.ts -- ../../../../src/impact/types.ts -- ../../../../src/evidence/validate.ts -- ../../../../src/workflow-state/action-context.ts -- ../../../../src/workflow-state/build.ts -- ../../../../src/workflow-state/types.ts -- ../../../../src/checks/generated-surfaces.ts -- ../../../../tests/workflow-state/build.test.ts -- `src/repo-index/build.ts` -- `src/repo-index/file-tree.ts` -- `src/repo-index/route-map.ts` -- `src/repo-index/types.ts` -- `src/impact/build.ts` -- `src/workflow-state/build.ts` +- src/repo-index/build.ts +- src/repo-index/file-tree.ts +- src/repo-index/route-map.ts +- src/repo-index/types.ts +- src/impact/build.ts +- src/impact/types.ts +- src/evidence/validate.ts +- src/workflow-state/action-context.ts +- src/workflow-state/build.ts +- src/workflow-state/types.ts +- src/checks/generated-surfaces.ts +- tests/impact/build.test.ts +- tests/evidence/validate.test.ts +- tests/workflow-state/build.test.ts diff --git a/docs/truthmark/engineering/workflows/installed-workflow-runtime.md b/docs/truthmark/engineering/workflows/installed-workflow-runtime.md index 00a34cb..d58eef1 100644 --- a/docs/truthmark/engineering/workflows/installed-workflow-runtime.md +++ b/docs/truthmark/engineering/workflows/installed-workflow-runtime.md @@ -1,7 +1,7 @@ --- status: active truth_kind: engineering-workflow -last_reviewed: 2026-06-21 +last_reviewed: 2026-06-26 --- # Installed Workflow Runtime @@ -92,11 +92,13 @@ Truth Sync performs decision context capture from the current task conversation: - Supported context is placed in the correct product or engineering truth lane. - The report records whether context was placed, skipped because none was provided, or handed off for manual review. -Truth Document procedures tell agents to write diff-friendly truth docs: +Truth Document and Truth Sync procedures tell agents to write professional, readable truth docs without importing a full external writing prompt: -- Prefer one durable claim per bullet or line. -- Keep paragraphs to one or two short sentences. -- Use bullets or tables for rules, criteria, fields, files, and lists. +- Prefer specific current-state claims over promotional, symbolic, or generic significance language. +- Avoid common AI-writing tells such as vague expert attribution, generic upbeat conclusions, and stock words like "pivotal", "crucial", "underscores", "serves as", "stands as", "showcases", and "landscape". +- Keep claims evidence-backed and diff-friendly: one durable claim per bullet or line; paragraphs should be no longer than one or two short sentences. +- Do not add personality, rhetorical flourish, first-person commentary, or marketing tone. +- Rewrite dense or formulaic prose only when readability improves without removing scope, evidence, decisions, or source references. Truth Structure stays topology-first: @@ -221,6 +223,8 @@ Committed workflow files are the runtime contract. The CLI installs and validate - Bootstrap-only mappings are blocked topology handoffs until Truth Structure assigns a bounded owner. - Decision (2026-06-21): Cursor workflow generation uses Agent Skill project packages under `.cursor/skills/truthmark-*`, not dynamic `.cursor/rules` files. - Agent Skills are the single current native Cursor workflow representation because they provide description-based selection plus package-local resources. +- Decision (2026-06-26): Truth-doc prose guidance uses a compact professional checklist instead of vendoring a full humanizer prompt into generated workflows. + - Truthmark keeps the benefit of avoiding AI-style padding while controlling token cost and preserving evidence-backed documentation tone. ## Rationale diff --git a/docs/truthmark/product/capabilities/agent-native-workflow-injection.md b/docs/truthmark/product/capabilities/agent-native-workflow-injection.md index 2ceb6ce..db6db8b 100644 --- a/docs/truthmark/product/capabilities/agent-native-workflow-injection.md +++ b/docs/truthmark/product/capabilities/agent-native-workflow-injection.md @@ -1,7 +1,7 @@ --- status: active truth_kind: product-capability -last_reviewed: 2026-06-20 +last_reviewed: 2026-06-26 --- # Agent-Native Workflow Injection @@ -16,6 +16,10 @@ last_reviewed: 2026-06-20 Repository maintainers and agents can follow the checked-in workflow contract without relying on a live Truthmark daemon, hidden runtime state, or off-repo packet. +Truthmark turns AI documentation from one-shot generation into ongoing truth-doc curation. + +Maintainers get bounded, evidence-backed, Git-reviewable truth docs that stay connected to code changes. + ## Capability Scope This capability covers: @@ -55,6 +59,7 @@ This capability covers: - Truth Sync status separates impacted `primaryTruthDocs`, `candidateStaleTruthDocs`, and `routeFiles`. - Agents start with affected route owners. - Evidence-backed stale repository-truth correction remains available beyond the initially affected route set. +- Broad, catch-all, mixed-owner, or overgrown truth docs are treated as curation problems that require Structure instead of more appended prose. ## Acceptance Criteria @@ -70,6 +75,8 @@ This capability covers: - Truth Sync routes supported context to the correct truth lane. - Truth Sync reports placement, skip, or manual handoff. - Workflows that create, structure, or audit truth docs still preserve product and engineering truth as separate lanes. +- Truth Document and Truth Sync carry compact professional prose guidance for truth-doc edits without embedding a full external humanizer prompt in generated workflow surfaces. +- Truthmark positions ongoing truth-doc curation as a core product value rather than presenting itself as a one-shot documentation generator. ## Product Decisions @@ -96,6 +103,10 @@ This capability covers: - Safe repairs happen inside Sync before normal truth syncing; manual Truth Structure handoff is only for unsafe, ambiguous, or out-of-scope topology changes. - Decision (2026-06-21): Cursor uses Agent Skill project packages under `.cursor/skills/truthmark-*`, not dynamic `.cursor/rules` files. - Cursor Agent Skills are the single current native Cursor workflow representation for Truthmark because they support description-based selection plus package-local support resources. +- Decision (2026-06-26): Humanizer-style cleanup is adapted only as a compact professional prose checklist. + - The workflow must avoid token-heavy prompt imports and must not push truth docs toward personal, rhetorical, or marketing tone. +- Decision (2026-06-26): Ongoing truth-doc curation is a primary product value. + - Marketing should emphasize bounded ownership, evidence-backed updates, Git-reviewable docs, and Structure handoff for overgrown docs rather than claiming generic documentation generation. ## Engineering Realization Links diff --git a/docs/truthmark/templates/engineering-behavior.md b/docs/truthmark/templates/engineering-behavior.md index 4603ce1..1b1aa55 100644 --- a/docs/truthmark/templates/engineering-behavior.md +++ b/docs/truthmark/templates/engineering-behavior.md @@ -48,6 +48,16 @@ Separate rules from incidental implementation details; cite current implementati {{core_rules}} +## Behavior Scenarios + + + +{{behavior_scenarios}} + ## Flows And States ", + "", + "{{behavior_scenarios}}", + "", "## Flows And States", "", "