fix(cli): fail on error diagnostics (#11)

* fix(cli): fail on error diagnostics

* chore: release 1.6.1

* feat(init): refresh truth doc templates

* fix(init): preserve custom template preambles

* ci: limit GitHub token permissions

* ci: update setup-node action

---------

Co-authored-by: MerlinH <merlinh221@gmail.com>

docs/standards/default-principles.md

@@ -100,6 +100,8 @@ When a repository has no explicit standards yet, a small default baseline is rea
 
 Truthmark can bootstrap only part of that baseline automatically today. Repositories may need to add richer standards after initialization.
 
+The default truth-document template rationale lives in [template-standards.md](template-standards.md); it maps Truthmark's template shapes to recognized software engineering references without claiming external certification.
+
 Projects may keep that baseline, replace it, or extend it with their own standards.
 
 ## Override Model

docs/standards/template-standards.md

@@ -0,0 +1,101 @@
+---
+status: active
+doc_type: standard
+last_reviewed: 2026-05-30
+source_of_truth:
+  - default-principles.md
+  - documentation-governance.md
+  - testing-and-verification.md
+  - https://www.iso.org/standard/74393.html
+  - https://www.iso.org/standard/72089.html
+  - https://www.iso.org/standard/63712.html
+  - https://www.iso.org/standard/78176.html
+  - https://c4model.com/
+  - https://docs.arc42.org/home/
+  - https://sre.google/sre-book/monitoring-distributed-systems/
+  - https://spec.openapis.org/oas/latest.html
+  - https://semver.org/
+  - https://diataxis.fr/
+---
+
+# Template Standards
+
+## Scope
+
+This standard explains why Truthmark's default truth-document templates are suitable bootstrap templates for professional software engineering repositories.
+
+The templates are not certifications, and Truthmark does not claim that a generated repository is compliant with any external standard by installing them. The templates are intentionally lightweight Markdown scaffolds that align with widely recognized software engineering documentation practices while leaving project-specific standards in the adopting repository.
+
+## Default Template Baseline
+
+Truthmark's default truth-document templates cover six common engineering documentation surfaces:
+
+- behavior docs for implemented product or system behavior
+- contract docs for API, CLI, file, event, or integration contracts
+- architecture docs for system structure, boundaries, components, and cross-cutting constraints
+- workflow docs for triggers, inputs, execution steps, retry behavior, and outputs
+- operations docs for runtime topology, configuration, permissions, deployment, rollback, availability, and observability
+- test-behavior docs for fixtures, execution model, assertions, isolation, and failure semantics
+
+Every default template includes the same governance foundation:
+
+- frontmatter status and review metadata
+- a declared source-of-truth list
+- purpose and scope
+- evidence-oriented guidance for default sections
+- explicit current-state content rather than roadmap content
+- active decisions and rationale
+- non-goals to prevent scope creep
+- maintenance notes for future reviewers and agents
+
+`truthmark init` may refresh these Truthmark-owned default template sections as the baseline improves. Existing template preambles/frontmatter are preserved on rerun so repository-owned metadata, titles, and local introductory guidance do not churn or get replaced just because the default baseline changed. Repository-specific custom `##` sections are not part of the default baseline; init preserves them and keeps their authored order relative to the next default section that followed them.
+
+This foundation follows Truthmark's repository-truth model: current implementation, reusable standards, architecture, and future proposals must not compete as parallel sources of authority.
+
+## External Standard Alignment
+
+| Truthmark template surface | External practice or standard alignment | Why the alignment matters |
+| --- | --- | --- |
+| Architecture | ISO/IEC/IEEE 42010, arc42, C4 Model | Architecture docs should make system role, boundaries, components, ownership, and quality constraints explicit instead of mixing structure with ordinary feature behavior. |
+| Behavior | ISO/IEC/IEEE 29148, ISO/IEC/IEEE 12207, Diátaxis | Behavior docs should state current system behavior, rules, states, and constraints in a form maintainers can review and agents can update with implementation changes. |
+| Contract | ISO/IEC/IEEE 29148, OpenAPI Specification, Semantic Versioning | Contract docs should separate inputs, outputs, diagnostics, compatibility rules, and migration/versioning expectations so external interfaces remain reviewable. |
+| Workflow | ISO/IEC/IEEE 12207, Diátaxis | Workflow docs should capture triggers, inputs, steps, failure behavior, and outputs as current operational behavior rather than as hidden process memory. |
+| Operations | ISO/IEC/IEEE 25010, Google SRE practices | Operations docs should make runtime topology, configuration, permissions, rollback, availability, and observability visible as maintainable repository truth. |
+| Test behavior | ISO/IEC/IEEE 12207, Truthmark testing-and-verification standard | Test-behavior docs should describe the test surface, data model, assertions, isolation rules, and failure semantics needed to keep verification meaningful. |
+
+## Justification For The Template Shape
+
+Truthmark defaults are justified because they optimize for the reviewable artifacts software teams need after AI-assisted changes:
+
+1. **Traceability:** `source_of_truth` metadata and routing docs make it clear which code, docs, or standards support a claim.
+2. **Single responsibility:** each template asks for a bounded document scope so one file does not become a feature manual, architecture note, changelog, and operations runbook at once.
+3. **Current-state authority:** sections are written for implemented behavior and active decisions, not historical plans or desired futures.
+4. **Decision capture:** `Product Decisions` and `Rationale` preserve non-obvious tradeoffs without requiring a separate ADR process for every small behavior decision.
+5. **Interface discipline:** contract templates isolate inputs, outputs, diagnostics, compatibility, and migration rules, matching how professional teams review public interfaces.
+6. **Operational readiness:** operations templates include configuration, permissions, deployment, rollback, availability, and observability because production behavior is part of repository truth.
+7. **Verification discipline:** test-behavior templates and the testing standard keep assertions, fixtures, isolation, and failure semantics explicit.
+8. **Override safety:** defaults are bootstrap guidance only; mature projects should replace or extend them with project-specific standards when those standards are clearer.
+
+## Reference Notes
+
+- ISO/IEC/IEEE 42010 supports the architecture-template focus on concerns, boundaries, viewpoints, and architecture rationale.
+- ISO/IEC/IEEE 29148 supports the behavior and contract-template focus on requirements, constraints, interfaces, and traceable statements.
+- ISO/IEC/IEEE 12207 supports the lifecycle-template focus on processes, implementation, verification, operation, and maintenance.
+- ISO/IEC 25010 supports cross-cutting quality attributes such as maintainability, reliability, usability, security, and portability.
+- C4 and arc42 provide practical, industry-adopted architecture-documentation shapes that map well to Truthmark's architecture sections.
+- OpenAPI and Semantic Versioning provide practical anchors for contract shape, compatibility, and migration language.
+- Google SRE practices justify keeping availability, observability, rollback, and operational behavior explicit.
+- Diátaxis reinforces the separation between explanation, reference, how-to, and tutorial content; Truthmark uses that principle to avoid mixed-purpose truth docs.
+
+## Non-Goals
+
+- Truthmark templates do not replace project-specific engineering standards.
+- Truthmark templates do not certify compliance with ISO, IEEE, OpenAPI, SRE, C4, arc42, SemVer, or Diátaxis.
+- Truthmark templates do not require every repository to keep every document kind.
+- Truthmark templates do not make roadmap proposals canonical current truth.
+
+## Maintenance Notes
+
+Update this standard when Truthmark adds, removes, renames, or materially changes default truth-document templates, or when the references behind the default template rationale change.
+
+When changing default template content, keep `docs/templates/*.md`, `src/templates/init-files.ts`, `docs/standards/default-principles.md`, and this standard aligned.

docs/templates/architecture-doc.md

@@ -2,7 +2,7 @@
 status: active
 doc_type: architecture
 truth_kind: architecture
-last_reviewed: 2026-05-14
+last_reviewed: 2026-05-30
 source_of_truth:
   - {{source_of_truth}}
 ---
@@ -11,48 +11,110 @@ source_of_truth:
 
 ## Purpose
 
+<!--
+State the software-engineering outcome this document protects and why the documented surface exists.
+Include durable value, impacted users/systems, and the problem boundary; exclude roadmap, implementation plans, and historical narrative.
+Keep claims traceable to source_of_truth evidence rather than prose-only assertion.
+-->
+
 {{purpose}}
 
 ## Scope
 
+<!--
+Define the one coherent surface this document owns, including actors, entrypoints, owned state/data, and handoffs to neighboring truth docs.
+Call out important out-of-scope boundaries here or in Non-Goals; split the doc when it mixes distinct outcomes, lifecycles, contracts, or owners.
+-->
+
 {{scope}}
 
 ## System Role
 
+<!--
+Describe the current architectural role of this subsystem/component in the larger system.
+State the primary responsibilities, consumers, providers, and why this boundary exists now.
+-->
+
 {{system_role}}
 
 ## Boundaries
 
+<!--
+Define owned code/config/data, external dependencies, trust boundaries, and interfaces crossed by this architecture.
+Name what is deliberately outside the boundary and link neighboring architecture or contract docs when they own it.
+-->
+
 {{boundaries}}
 
 ## Components
 
+<!--
+List the major runtime/build-time components, modules, services, jobs, or generated artifacts and their responsibilities.
+Keep the component list current and evidence-backed; avoid speculative target architecture.
+-->
+
 {{components}}
 
 ## Data And Control Flow
 
+<!--
+Describe important data movement, command/control paths, synchronization points, state ownership, and failure paths.
+Call out persistence, queues, caches, external calls, and security-sensitive transitions where relevant.
+-->
+
 {{data_and_control_flow}}
 
 ## Ownership
 
+<!--
+Document team/module ownership, review responsibility, operational responsibility, and escalation paths if known.
+If ownership is inferred from codeowners, config, or repository structure, cite that evidence.
+-->
+
 {{ownership}}
 
 ## Cross-Cutting Constraints
 
+<!--
+Record active constraints such as security, privacy, reliability, performance, portability, maintainability, compliance, and cost.
+Tie constraints to source evidence, tests, standards, or operational requirements where available.
+-->
+
 {{cross_cutting_constraints}}
 
 ## Product Decisions
 
+<!--
+Keep active decisions only, dated inline when added or changed.
+Capture decisions that shape behavior, interfaces, boundaries, compatibility, risk acceptance, or migration constraints.
+Replace stale decisions instead of appending historical logs.
+-->
+
 {{decision}}
 
 ## Rationale
 
+<!--
+Explain why the current behavior, structure, or contract is this way, including tradeoffs and constraints.
+Tie rationale to evidence-backed facts and active decisions; do not use this as a changelog.
+-->
+
 {{rationale}}
 
 ## Non-Goals
 
+<!--
+Name adjacent behavior, responsibilities, interfaces, or future expansions this doc intentionally does not own.
+Use this section to prevent scope creep and duplicate truth ownership.
+-->
+
 {{non_goals}}
 
 ## Maintenance Notes
 
-{{maintenance_notes}}
+<!--
+List related tests, routing cautions, migration notes, compatibility risks, evidence drift risks, and review triggers for future maintainers or agents.
+Keep this operational and current-state focused, not historical.
+-->
+
+{{maintenance_notes}}

docs/templates/behavior-doc.md

@@ -2,7 +2,7 @@
 status: active
 doc_type: behavior
 truth_kind: behavior
-last_reviewed: 2026-05-14
+last_reviewed: 2026-05-30
 source_of_truth:
   - {{source_of_truth}}
 ---
@@ -11,71 +11,96 @@ source_of_truth:
 
 ## Purpose
 
-<!-- State why this behavior exists, the user or system outcome it protects, and the problem it solves. Keep roadmap or implementation plans out of this section. -->
+<!--
+State the user/system outcome this behavior protects and why it exists.
+Include the problem boundary and durable value; exclude roadmap, implementation plan, and historical narrative.
+List the code, config, docs, or tests that support the claim in source_of_truth rather than prose-only assertion.
+-->
 
 {{purpose}}
 
 ## Scope
 
-{{scope}}
-
 <!--
-This doc must own one coherent behavior surface.
-Split into another leaf doc when content introduces:
-- a distinct user or system outcome
-- a separate lifecycle or state machine
-- an unrelated rule family
-- a different external contract
-- code that should route through a different owner
+Define the one coherent behavior surface this document owns.
+Include in-scope actors, entrypoints, state/data owned by this doc, and explicit handoffs to neighboring truth docs.
+Split into another leaf doc when content introduces a distinct outcome, state machine, rule family, external contract, or route owner.
 Keep README.md files as indexes only.
 -->
 
+{{scope}}
+
 This doc was created from the editable behavior-doc template at {{template_path}}.
 
 ## Current Behavior
 
-<!-- Describe implemented behavior in present tense. Do not include desired future behavior. -->
+<!--
+Describe only current implemented behavior in present tense.
+Cover observable behavior, important defaults, and user/system-visible effects; exclude desired future behavior and speculative design.
+Every non-obvious claim should be checkable from source_of_truth evidence.
+-->
 
 {{current_behavior}}
 
 ## Core Rules
 
-<!-- Capture stable business rules, invariants, precedence rules, validation rules, and must-never constraints. Omit incidental implementation details. -->
+<!--
+Capture stable business rules, invariants, precedence rules, validation rules, and must-never constraints.
+Separate rules from incidental implementation details; cite current implementation or tests for rule enforcement.
+-->
 
 {{core_rules}}
 
 ## Flows And States
 
-<!-- Use for route switches, state transitions, lifecycle stages, retries, fallbacks, and important error paths. Write 'None beyond current behavior.' when no distinct flow or state model exists. -->
+<!--
+Document state transitions, lifecycle stages, retries, fallbacks, route switches, and important error paths.
+State 'None beyond current behavior.' when this behavior has no distinct flow or state model.
+-->
 
 {{flows_and_states}}
 
 ## Contracts
 
-<!-- Capture user-visible or integration contracts: CLI/API shape, inputs, outputs, diagnostics, files, events, permissions, or links to canonical contract docs. Avoid duplicating a separate canonical contract doc. -->
+<!--
+Capture user-visible or integration contracts: CLI/API shape, inputs, outputs, diagnostics, files, events, permissions, or links to canonical contract docs.
+Avoid duplicating a separate canonical contract doc; link to it when contract ownership lives elsewhere.
+-->
 
 {{contracts}}
 
 ## Product Decisions
 
-<!-- Keep active decisions only. Replace stale decisions instead of appending historical logs. -->
+<!--
+Keep active decisions only, dated inline when added or changed.
+Explain decisions that shape behavior, boundaries, rejected alternatives, or migration constraints; replace stale decisions instead of appending historical logs.
+-->
 
 {{decision}}
 
 ## Rationale
 
-<!-- Explain why the current behavior and active decisions are this way, including tradeoffs. -->
+<!--
+Explain why the current behavior and active decisions are this way, including tradeoffs and constraints.
+Tie rationale to evidence-backed behavior; do not use this as a changelog.
+-->
 
 {{rationale}}
 
 ## Non-Goals
 
-<!-- Name adjacent behavior this doc intentionally does not own, especially tempting future expansions. -->
+<!--
+Name adjacent behavior this doc intentionally does not own, especially tempting future expansions or neighboring route owners.
+Use this section to prevent scope creep and duplicate truth ownership.
+-->
 
 {{non_goals}}
 
 ## Maintenance Notes
 
-<!-- List related tests, routing cautions, migration notes, and common drift risks for future agents. Keep this operational, not historical. -->
+<!--
+List related tests, routing cautions, migration notes, evidence drift risks, and review triggers for future maintainers or agents.
+Keep this operational and current-state focused, not historical.
+-->
 
-{{maintenance_notes}}
+{{maintenance_notes}}

docs/templates/contract-doc.md

@@ -2,7 +2,7 @@
 status: active
 doc_type: contract
 truth_kind: contract
-last_reviewed: 2026-05-14
+last_reviewed: 2026-05-30
 source_of_truth:
   - {{source_of_truth}}
 ---
@@ -11,48 +11,110 @@ source_of_truth:
 
 ## Purpose
 
+<!--
+State the software-engineering outcome this document protects and why the documented surface exists.
+Include durable value, impacted users/systems, and the problem boundary; exclude roadmap, implementation plans, and historical narrative.
+Keep claims traceable to source_of_truth evidence rather than prose-only assertion.
+-->
+
 {{purpose}}
 
 ## Scope
 
+<!--
+Define the one coherent surface this document owns, including actors, entrypoints, owned state/data, and handoffs to neighboring truth docs.
+Call out important out-of-scope boundaries here or in Non-Goals; split the doc when it mixes distinct outcomes, lifecycles, contracts, or owners.
+-->
+
 {{scope}}
 
 ## Contract Surface
 
+<!--
+Identify the owned API, CLI, file format, event, protocol, permission boundary, or integration surface.
+State consumers/producers, stability level, and the source files/tests that define the contract.
+-->
+
 {{contract_surface}}
 
 ## Inputs
 
+<!--
+Document accepted parameters, payloads, files, environment/config keys, permissions, and validation rules.
+Include required/optional status, defaults, constraints, and normalization behavior.
+-->
+
 {{inputs}}
 
 ## Outputs
 
+<!--
+Document returned values, emitted files/events, state changes, side effects, and success diagnostics.
+Make externally observable behavior explicit enough for compatibility review.
+-->
+
 {{outputs}}
 
 ## Errors And Diagnostics
 
+<!--
+List error classes, exit/status codes, user-facing diagnostics, retries, and recoverability expectations.
+Distinguish validation errors, dependency failures, authorization failures, and internal faults when applicable.
+-->
+
 {{errors_and_diagnostics}}
 
 ## Compatibility Rules
 
+<!--
+State backward/forward compatibility guarantees, tolerated inputs, deprecation rules, and breaking-change triggers.
+Include compatibility tests or review gates that protect the contract.
+-->
+
 {{compatibility_rules}}
 
 ## Versioning And Migration
 
+<!--
+Document version negotiation, schema/API version fields, rollout requirements, migration steps, and rollback expectations.
+State 'Not versioned' only when the implementation truly has no versioning or migration surface.
+-->
+
 {{versioning_and_migration}}
 
 ## Product Decisions
 
+<!--
+Keep active decisions only, dated inline when added or changed.
+Capture decisions that shape behavior, interfaces, boundaries, compatibility, risk acceptance, or migration constraints.
+Replace stale decisions instead of appending historical logs.
+-->
+
 {{decision}}
 
 ## Rationale
 
+<!--
+Explain why the current behavior, structure, or contract is this way, including tradeoffs and constraints.
+Tie rationale to evidence-backed facts and active decisions; do not use this as a changelog.
+-->
+
 {{rationale}}
 
 ## Non-Goals
 
+<!--
+Name adjacent behavior, responsibilities, interfaces, or future expansions this doc intentionally does not own.
+Use this section to prevent scope creep and duplicate truth ownership.
+-->
+
 {{non_goals}}
 
 ## Maintenance Notes
 
-{{maintenance_notes}}
+<!--
+List related tests, routing cautions, migration notes, compatibility risks, evidence drift risks, and review triggers for future maintainers or agents.
+Keep this operational and current-state focused, not historical.
+-->
+
+{{maintenance_notes}}

docs/templates/operations-doc.md

@@ -2,7 +2,7 @@
 status: active
 doc_type: behavior
 truth_kind: operations
-last_reviewed: 2026-05-14
+last_reviewed: 2026-05-30
 source_of_truth:
   - {{source_of_truth}}
 ---
@@ -11,48 +11,110 @@ source_of_truth:
 
 ## Purpose
 
+<!--
+State the software-engineering outcome this document protects and why the documented surface exists.
+Include durable value, impacted users/systems, and the problem boundary; exclude roadmap, implementation plans, and historical narrative.
+Keep claims traceable to source_of_truth evidence rather than prose-only assertion.
+-->
+
 {{purpose}}
 
 ## Scope
 
+<!--
+Define the one coherent surface this document owns, including actors, entrypoints, owned state/data, and handoffs to neighboring truth docs.
+Call out important out-of-scope boundaries here or in Non-Goals; split the doc when it mixes distinct outcomes, lifecycles, contracts, or owners.
+-->
+
 {{scope}}
 
 ## Operational Surface
 
+<!--
+Describe what operators, maintainers, or automated systems can observe or control for this surface.
+Include commands, dashboards, alerts, runbooks, jobs, or operational APIs that define current operations.
+-->
+
 {{operational_surface}}
 
 ## Runtime Topology
 
+<!--
+Document services, processes, containers, hosts, regions, dependencies, queues, stores, and network boundaries involved at runtime.
+State single-node/local behavior explicitly when there is no distributed topology.
+-->
+
 {{runtime_topology}}
 
 ## Configuration
 
+<!--
+List operational config, environment variables, feature flags, secrets references, defaults, and reload/restart requirements.
+Do not include secret values; describe storage and rotation expectations instead.
+-->
+
 {{configuration}}
 
 ## Permissions
 
+<!--
+Document required identities, roles, scopes, filesystem/network permissions, and least-privilege boundaries.
+Include user-facing authorization behavior and operator access requirements when relevant.
+-->
+
 {{permissions}}
 
 ## Deployment And Rollback
 
+<!--
+Describe deployment mechanism, migration ordering, compatibility windows, rollback path, and known irreversible operations.
+Call out manual gates, smoke checks, and post-deploy verification responsibilities.
+-->
+
 {{deployment_and_rollback}}
 
 ## Availability And Observability
 
+<!--
+Capture availability expectations, health checks, metrics, logs, traces, alerts, SLO/error-budget signals, and known blind spots.
+Include what maintainers should inspect first during incidents or degraded behavior.
+-->
+
 {{availability_and_observability}}
 
 ## Product Decisions
 
+<!--
+Keep active decisions only, dated inline when added or changed.
+Capture decisions that shape behavior, interfaces, boundaries, compatibility, risk acceptance, or migration constraints.
+Replace stale decisions instead of appending historical logs.
+-->
+
 {{decision}}
 
 ## Rationale
 
+<!--
+Explain why the current behavior, structure, or contract is this way, including tradeoffs and constraints.
+Tie rationale to evidence-backed facts and active decisions; do not use this as a changelog.
+-->
+
 {{rationale}}
 
 ## Non-Goals
 
+<!--
+Name adjacent behavior, responsibilities, interfaces, or future expansions this doc intentionally does not own.
+Use this section to prevent scope creep and duplicate truth ownership.
+-->
+
 {{non_goals}}
 
 ## Maintenance Notes
 
-{{maintenance_notes}}
+<!--
+List related tests, routing cautions, migration notes, compatibility risks, evidence drift risks, and review triggers for future maintainers or agents.
+Keep this operational and current-state focused, not historical.
+-->
+
+{{maintenance_notes}}

docs/templates/test-behavior-doc.md

@@ -2,7 +2,7 @@
 status: active
 doc_type: behavior
 truth_kind: test-behavior
-last_reviewed: 2026-05-14
+last_reviewed: 2026-05-30
 source_of_truth:
   - {{source_of_truth}}
 ---
@@ -11,48 +11,110 @@ source_of_truth:
 
 ## Purpose
 
+<!--
+State the software-engineering outcome this document protects and why the documented surface exists.
+Include durable value, impacted users/systems, and the problem boundary; exclude roadmap, implementation plans, and historical narrative.
+Keep claims traceable to source_of_truth evidence rather than prose-only assertion.
+-->
+
 {{purpose}}
 
 ## Scope
 
+<!--
+Define the one coherent surface this document owns, including actors, entrypoints, owned state/data, and handoffs to neighboring truth docs.
+Call out important out-of-scope boundaries here or in Non-Goals; split the doc when it mixes distinct outcomes, lifecycles, contracts, or owners.
+-->
+
 {{scope}}
 
 ## Test Surface
 
+<!--
+Define the behavior, contract, architecture, or workflow surface these tests verify.
+Link the canonical truth docs and code paths the tests are meant to protect.
+-->
+
 {{test_surface}}
 
 ## Fixtures And Data Model
 
+<!--
+Document fixtures, factories, seeds, mocks/fakes, test repositories, external-service substitutes, and data lifecycle rules.
+Include cleanup, determinism, privacy, and cross-test contamination constraints.
+-->
+
 {{fixtures_and_data_model}}
 
 ## Execution Model
 
+<!--
+Describe how tests run: command, framework, parallelism, isolation, network/filesystem assumptions, and required services.
+State whether tests are unit, integration, e2e, contract, smoke, regression, or generated checks.
+-->
+
 {{execution_model}}
 
 ## Assertions And Invariants
 
+<!--
+List the critical assertions, invariants, failure modes, and negative cases that make the tests meaningful.
+Tie assertions to product/contract rules rather than incidental implementation details.
+-->
+
 {{assertions_and_invariants}}
 
 ## Isolation Rules
 
+<!--
+Document transaction boundaries, temp directories, fake clocks, network blocking, shared resources, and teardown rules.
+Call out known order dependencies or flake risks and how they are controlled.
+-->
+
 {{isolation_rules}}
 
 ## Reporting And Failure Semantics
 
+<!--
+Describe diagnostics, snapshots, logs, coverage signals, retry policy, and how maintainers should interpret failures.
+Include escalation or quarantine criteria for flaky or environment-sensitive tests.
+-->
+
 {{reporting_and_failure_semantics}}
 
 ## Product Decisions
 
+<!--
+Keep active decisions only, dated inline when added or changed.
+Capture decisions that shape behavior, interfaces, boundaries, compatibility, risk acceptance, or migration constraints.
+Replace stale decisions instead of appending historical logs.
+-->
+
 {{decision}}
 
 ## Rationale
 
+<!--
+Explain why the current behavior, structure, or contract is this way, including tradeoffs and constraints.
+Tie rationale to evidence-backed facts and active decisions; do not use this as a changelog.
+-->
+
 {{rationale}}
 
 ## Non-Goals
 
+<!--
+Name adjacent behavior, responsibilities, interfaces, or future expansions this doc intentionally does not own.
+Use this section to prevent scope creep and duplicate truth ownership.
+-->
+
 {{non_goals}}
 
 ## Maintenance Notes
 
-{{maintenance_notes}}
+<!--
+List related tests, routing cautions, migration notes, compatibility risks, evidence drift risks, and review triggers for future maintainers or agents.
+Keep this operational and current-state focused, not historical.
+-->
+
+{{maintenance_notes}}

docs/templates/workflow-doc.md

@@ -2,7 +2,7 @@
 status: active
 doc_type: behavior
 truth_kind: workflow
-last_reviewed: 2026-05-14
+last_reviewed: 2026-05-30
 source_of_truth:
   - {{source_of_truth}}
 ---
@@ -11,48 +11,110 @@ source_of_truth:
 
 ## Purpose
 
+<!--
+State the software-engineering outcome this document protects and why the documented surface exists.
+Include durable value, impacted users/systems, and the problem boundary; exclude roadmap, implementation plans, and historical narrative.
+Keep claims traceable to source_of_truth evidence rather than prose-only assertion.
+-->
+
 {{purpose}}
 
 ## Scope
 
+<!--
+Define the one coherent surface this document owns, including actors, entrypoints, owned state/data, and handoffs to neighboring truth docs.
+Call out important out-of-scope boundaries here or in Non-Goals; split the doc when it mixes distinct outcomes, lifecycles, contracts, or owners.
+-->
+
 {{scope}}
 
 ## Triggers
 
+<!--
+List events, commands, schedules, user actions, webhooks, or dependency signals that start this workflow.
+Include preconditions, authorization requirements, debounce/coalescing behavior, and disabled states when applicable.
+-->
+
 {{triggers}}
 
 ## Inputs
 
+<!--
+Document data, files, config, context, credentials, and environmental assumptions consumed by the workflow.
+Include validation, defaults, and normalization that happen before execution.
+-->
+
 {{inputs}}
 
 ## Execution Model
 
+<!--
+Describe synchronous/asynchronous execution, concurrency, locking, leases, batching, ordering, and idempotency behavior.
+State whether the workflow is user-blocking, background, distributed, or delegated to another system.
+-->
+
 {{execution_model}}
 
 ## Steps
 
+<!--
+Capture the current ordered steps or phases at a level useful for maintenance and review.
+Reference implementation entrypoints instead of duplicating line-by-line code behavior.
+-->
+
 {{steps}}
 
 ## State, Retry, And Failure Behavior
 
+<!--
+Document state transitions, retries, timeouts, compensation, fallback, partial-success, and terminal-failure behavior.
+Make externally visible failure semantics and recovery responsibilities clear.
+-->
+
 {{state_retry_and_failure_behavior}}
 
 ## Outputs
 
+<!--
+List artifacts, state changes, notifications, logs, metrics, diagnostics, and downstream triggers produced by the workflow.
+Include success criteria and handoff points to other truth docs or systems.
+-->
+
 {{outputs}}
 
 ## Product Decisions
 
+<!--
+Keep active decisions only, dated inline when added or changed.
+Capture decisions that shape behavior, interfaces, boundaries, compatibility, risk acceptance, or migration constraints.
+Replace stale decisions instead of appending historical logs.
+-->
+
 {{decision}}
 
 ## Rationale
 
+<!--
+Explain why the current behavior, structure, or contract is this way, including tradeoffs and constraints.
+Tie rationale to evidence-backed facts and active decisions; do not use this as a changelog.
+-->
+
 {{rationale}}
 
 ## Non-Goals
 
+<!--
+Name adjacent behavior, responsibilities, interfaces, or future expansions this doc intentionally does not own.
+Use this section to prevent scope creep and duplicate truth ownership.
+-->
+
 {{non_goals}}
 
 ## Maintenance Notes
 
-{{maintenance_notes}}
+<!--
+List related tests, routing cautions, migration notes, compatibility risks, evidence drift risks, and review triggers for future maintainers or agents.
+Keep this operational and current-state focused, not historical.
+-->
+
+{{maintenance_notes}}

docs/truth/contracts.md

@@ -117,7 +117,7 @@ Diagnostic fields:
 - `area`: optional area name from `docs/truthmark/areas.md`
 - `data`: optional machine-readable extras
 
-Human-rendered output is intended for people. JSON output is the machine-facing contract.
+Human-rendered output is intended for people. JSON output is the machine-facing contract. CLI invocations that render a `CommandResult` set a non-zero process exit code when any diagnostic has `severity: "error"`; `info`, `action`, and `review` diagnostics do not make the process fail.
 
 `truthmark index --json` returns `data.repoIndex` with `schemaVersion: repo-index/v0` and `data.routeMap` with `schemaVersion: route-map/v0`.
 

docs/truth/init-and-scaffold.md

@@ -160,7 +160,7 @@ Current scaffold targets:
 `instruction_targets` controls shared managed-instruction files such as `AGENTS.md`. These targets are written or refreshed whenever `truthmark init` runs with a valid config, independent of the configured platform list.
 `platforms` controls which platform-specific surfaces are written or refreshed. Defaults include all supported platforms: `codex`, `opencode`, `claude-code`, `github-copilot`, and `gemini-cli`. Teams should remove unused platforms from `.truthmark/config.yml` before rerunning `truthmark init`. Claude Code installs `CLAUDE.md`, project skills under `.claude/skills/`, and verifier plus leased doc-writer subagents under `.claude/agents/`; skills surface as `/truthmark-structure`, `/truthmark-document`, `/truthmark-sync`, `/truthmark-preview`, `/truthmark-realize`, and `/truthmark-check`, plus `/truthmark-portal` when Portal is enabled, while the generated project subagents provide bounded evidence checks and parent-leased truth-doc writes. GitHub Copilot installs `.github/copilot-instructions.md`, agent skills under `.github/skills/`, prompt files under `.github/prompts/`, and verifier plus leased doc-writer custom agents under `.github/agents/`; prompts and skills surface as `/truthmark-structure`, `/truthmark-document`, `/truthmark-sync`, `/truthmark-preview`, `/truthmark-realize`, and `/truthmark-check`, plus `/truthmark-portal` when Portal is enabled, in supported Copilot IDEs, while Copilot CLI can dispatch the generated `@truth-*` custom agents for bounded evidence checks or parent-leased doc shards. Gemini installs `GEMINI.md`, Agent Skills under `.gemini/skills/`, project-scoped TOML commands under `.gemini/commands/truthmark/`, and project subagents under `.gemini/agents/`; commands surface as `/truthmark:structure`, `/truthmark:document`, `/truthmark:sync`, `/truthmark:preview`, `/truthmark:realize`, and `/truthmark:check`, plus `/truthmark:portal` when Portal is enabled, in Gemini CLI and append `User focus or arguments: {{args}}` near the end of each TOML prompt. Unknown platform names are config errors. Removing a platform stops future refreshes for that platform, but `init` does not delete previously generated files.
 
-`ensureRepoFile` is intentionally conservative: existing non-empty files are left alone. The AGENTS managed block is the exception because Truthmark owns that block and may refresh it to match current template behavior.
+`ensureRepoFile` is intentionally conservative: existing non-empty scaffold files are left alone unless the file is one of Truthmark's managed update surfaces. Managed update surfaces include instruction blocks, generated workflow assets, and truth-doc templates under `docs/templates/*.md`; template reruns refresh Truthmark-owned default sections while preserving project-specific custom sections and their authored order.
 
 The generated Truth Structure, Truth Document, Truth Sync, Truth Preview, Truth Realize, and Truth Check explicit surfaces are also managed by Truthmark and may be refreshed on rerun so the Codex skills, metadata, Claude Code project skills, GitHub Copilot skills/prompts/custom agents, Gemini skills/commands/subagents, and OpenCode skills keep matching the installed workflow contract. Generated skill packages keep `SKILL.md` compact and write heavy procedure, report-template, and subagent or lease reference material into sibling `support/*.md` files. Optional helper manifests and helper policy files are emitted only for workflows that declare helpers and only for configured skill-package platforms; helper manifests invoke installed Truthmark CLI validators such as `truthmark validate sync-report <report-file> --json`, `truthmark validate document-report <report-file> --json`, and `truthmark validate write-lease <lease-or-report-file> <changed-files-file> --json`. Generated packages do not bundle repo-local `scripts/*.mjs` helper copies. GitHub Copilot prompts and Gemini commands remain standalone entrypoints; their report examples mark helper packages unavailable unless the matching generated skill package is being used. Generated skills, support files, Codex metadata, Copilot prompt files, Copilot custom-agent files, Gemini command files, Gemini subagent files, and managed instruction blocks include the Truthmark package version that rendered them; `package.json` is the single maintained version source. After upgrading Truthmark, rerun `truthmark init` and review generated workflow diffs.
 
@@ -197,8 +197,8 @@ Hierarchy is configured in `.truthmark/config.yml`:
 
 `truthmark init` creates missing structure for that hierarchy, but child route files stay governed by the root route index: if an authored non-empty root index no longer delegates the configured default child route, rerunning init does not recreate that unreferenced child route. Init does not silently move, delete, or reinterpret existing truth docs when teams change the configured roots. Those cases produce review diagnostics for manual migration.
 The default scaffold treats truth `README.md` files as indexes. Current behavior truth belongs in bounded leaf docs under the configured truth root, such as `<truth-root>/<domain>/<behavior>.md`.
-`truthmark init` creates [docs/templates/behavior-doc.md](../templates/behavior-doc.md) when it is missing or empty and also seeds [docs/templates/contract-doc.md](../templates/contract-doc.md), [docs/templates/architecture-doc.md](../templates/architecture-doc.md), [docs/templates/workflow-doc.md](../templates/workflow-doc.md), [docs/templates/operations-doc.md](../templates/operations-doc.md), and [docs/templates/test-behavior-doc.md](../templates/test-behavior-doc.md) when they are missing or empty. The default behavior template includes Purpose, Scope, Current Behavior, Core Rules, Flows And States, Contracts, Product Decisions, Rationale, Non-Goals, and Maintenance Notes sections, with inline scope criteria for agents. Kind-specific templates add the required anchors for contract, architecture, workflow, operations, and test-behavior truth surfaces. The default child route references the seeded leaf truth doc with fenced YAML `truth_documents` metadata and `kind: behavior` rather than relying on path inference.
-When creating the default bounded behavior truth doc, init reads the repository's behavior template and expands supported placeholders such as `{{title}}`, `{{area}}`, `{{source_of_truth}}`, `{{purpose}}`, `{{scope}}`, `{{current_behavior}}`, `{{core_rules}}`, `{{flows_and_states}}`, `{{contracts}}`, `{{decision}}`, `{{rationale}}`, `{{non_goals}}`, `{{maintenance_notes}}`, and `{{template_path}}`. The seeded leaf uses `doc_type: behavior` and `truth_kind: behavior`. Existing non-empty template files are preserved so teams can define local truth-doc standards.
+`truthmark init` creates [docs/templates/behavior-doc.md](../templates/behavior-doc.md) when it is missing or empty and refreshes all six templates under `docs/templates/*.md` on rerun. Template refreshes replace Truthmark-owned default sections with the current professional guidance baseline, including evidence, boundary, current-state, contract, operational, verification, decision, rationale, non-goal, and maintenance prompts. Existing template preambles/frontmatter are preserved so repository-owned metadata, custom titles, source-of-truth defaults, and local introductory guidance do not churn during section refresh. Project-specific custom `##` sections are preserved and reinserted before the next default section that followed them in the authored file; trailing custom sections remain trailing. Fenced code blocks are ignored while finding `##` template sections, so examples can contain Markdown headings without being split or mistaken for Truthmark-owned sections. The default child route references the seeded leaf truth doc with fenced YAML `truth_documents` metadata and `kind: behavior` rather than relying on path inference.
+When creating the default bounded behavior truth doc, init reads the repository's merged behavior template and expands supported placeholders such as `{{title}}`, `{{area}}`, `{{source_of_truth}}`, `{{purpose}}`, `{{scope}}`, `{{current_behavior}}`, `{{core_rules}}`, `{{flows_and_states}}`, `{{contracts}}`, `{{decision}}`, `{{rationale}}`, `{{non_goals}}`, `{{maintenance_notes}}`, and `{{template_path}}`. The seeded leaf uses `doc_type: behavior` and `truth_kind: behavior`. Existing non-empty truth docs are preserved; existing template files are merged rather than blindly overwritten so teams can keep local truth-doc standard sections while receiving updated default guidance.
 
 ## Current Defaults
 
@@ -206,7 +206,7 @@ Important current defaults:
 
 - default authority includes the canonical doc classes under `docs/`
 - default code surface in the scaffolded root and child route files starts as `src/**`
-- default truth scaffolding creates an index at `<truth-root>/README.md`, an index at `<truth-root>/<default-area>/README.md`, six editable templates under `docs/templates/*.md`, and a bounded leaf truth doc at `<truth-root>/<default-area>/overview.md` routed through explicit `{ path, kind }` metadata
+- default truth scaffolding creates an index at `<truth-root>/README.md`, an index at `<truth-root>/<default-area>/README.md`, six editable and refreshable templates under `docs/templates/*.md`, and a bounded leaf truth doc at `<truth-root>/<default-area>/overview.md` routed through explicit `{ path, kind }` metadata
 - default platforms are `codex`, `opencode`, `claude-code`, `github-copilot`, and `gemini-cli`
 - shared instruction targets are refreshed independently of platform-specific surfaces
 - explicit Truth Structure, Truth Document, Truth Sync, Truth Preview, Truth Realize, and Truth Check surfaces are installed only for configured platforms
@@ -235,7 +235,7 @@ Current init JSON reporting uses:
 
 - all generated paths must remain inside the active repository root
 - generated path containment must reject symlinks that resolve outside the repository, including broken symlink leaves that would otherwise be created outside the worktree
-- init must be idempotent for existing non-empty scaffold files except for the managed AGENTS block
+- init must be idempotent for existing non-empty scaffold files except for managed update surfaces such as instruction blocks, generated workflow assets, and merged `docs/templates/*.md` default sections
 - the command should remain safe to run repeatedly in the same repository
 
 ## Product Decisions
@@ -248,6 +248,7 @@ Current init JSON reporting uses:
 - Decision (2026-05-15): Repository instruction preambles make docs-map and onboarding reads conditional, and managed instruction blocks omit platform-specific workflow invocation strings so ordinary sessions load less context.
 - Decision (2026-05-13): `.truthmark/config.yml` and route files are the committed hierarchy contract, so init no longer creates a low-value top-level note.
 - Decision (2026-05-14): Truth-doc templates are kind-specific under `docs/templates/*.md`; `docs/templates/behavior-doc.md` is the default bounded behavior template and the other five typed templates carry kind-specific required sections.
+- Decision (2026-05-30): `truthmark init` refreshes Truthmark-owned default sections in existing `docs/templates/*.md` files while preserving project-specific custom `##` sections and their authored relative order.
 - Decision (2026-05-14): Truth Realize stays manual-only through explicit generated surfaces and is no longer configurable with `realization.enabled`.
 - Decision (2026-05-13): Default standards define architecture docs as structure and ownership truth, not a place for ordinary product behavior.
 
@@ -257,7 +258,7 @@ This split makes the hierarchy reviewable before generated workflow behavior lan
 
 Keeping host-specific detail in generated skills and Gemini command files prevents the repository root from accumulating parallel instruction files that drift from the managed workflow contract. Keeping managed blocks terse protects ordinary agent context while preserving the automatic Sync gate, workflow boundaries, and branch-local authority. Conditional docs-map and onboarding reads keep routing guidance available without forcing every normal session to load it.
 
-Keeping typed truth-doc templates in `docs/templates/` gives repository owners one local standard surface per truth kind while keeping generated workflow text compact as more workflow surfaces are added.
+Keeping typed truth-doc templates in `docs/templates/` gives repository owners one local standard surface per truth kind while keeping generated workflow text compact as more workflow surfaces are added. Refreshing default template sections on `truthmark init` keeps those local standard surfaces aligned with current professional guidance, while preserving custom sections prevents product-specific review gates from being erased by package upgrades.
 
 ## Primary Code Files