truthmark 1.6.0 → 1.6.1

package/README.de.md

@@ -155,6 +155,8 @@ Das installiert oder aktualisiert:
 - verwaltete Instruktionsblöcke
 - KI-orientierte Workflow-Oberflächen für konfigurierte Plattformen
 
+Die Standardvorlagen für Truth-Dokumente werden in [Template Standards](docs/standards/template-standards.md) begründet. Dort werden sie anerkannten Software-Engineering-Referenzen wie ISO/IEC/IEEE 42010, ISO/IEC/IEEE 29148, ISO/IEC/IEEE 12207, ISO/IEC 25010, C4, arc42, OpenAPI, SemVer, Google SRE und Diátaxis zugeordnet.
+
 ### Das Setup validieren
 
 ```bash

package/README.es.md

@@ -155,6 +155,8 @@ Esto instala o refresca:
 - bloques de instrucciones administrados
 - superficies de flujo orientadas a IA para las plataformas configuradas
 
+Las plantillas predeterminadas de documentos de verdad se justifican en [Template Standards](docs/standards/template-standards.md), que las mapea a referencias reconocidas de ingeniería de software como ISO/IEC/IEEE 42010, ISO/IEC/IEEE 29148, ISO/IEC/IEEE 12207, ISO/IEC 25010, C4, arc42, OpenAPI, SemVer, Google SRE y Diátaxis.
+
 ### Validar la configuración
 
 ```bash

package/README.md

@@ -155,6 +155,8 @@ This installs or refreshes:
 - managed instruction blocks
 - AI-facing workflow surfaces for configured platforms
 
+Default truth-doc templates are justified in [Template Standards](docs/standards/template-standards.md), which maps them to recognized software engineering references such as ISO/IEC/IEEE 42010, ISO/IEC/IEEE 29148, ISO/IEC/IEEE 12207, ISO/IEC 25010, C4, arc42, OpenAPI, SemVer, Google SRE, and Diátaxis.
+
 ### Validate the setup
 
 ```bash

package/README.ru.md

@@ -155,6 +155,8 @@ truthmark init
 - управляемые блоки инструкций
 - поверхности рабочих процессов для ИИ для настроенных платформ
 
+Обоснование стандартных шаблонов документов истины находится в [Template Standards](docs/standards/template-standards.md). В документе показано, как они соотносятся с признанными источниками по инженерии ПО, включая ISO/IEC/IEEE 42010, ISO/IEC/IEEE 29148, ISO/IEC/IEEE 12207, ISO/IEC 25010, C4, arc42, OpenAPI, SemVer, Google SRE и Diátaxis.
+
 ### Проверить настройку
 
 ```bash

package/README.zh.md

@@ -155,6 +155,8 @@ truthmark init
 - 受管说明块
 - 已配置平台的面向 AI 工作流表面
 
+默认事实文档模板的依据见 [Template Standards](docs/standards/template-standards.md)。该文档说明这些模板如何对齐 ISO/IEC/IEEE 42010、ISO/IEC/IEEE 29148、ISO/IEC/IEEE 12207、ISO/IEC 25010、C4、arc42、OpenAPI、SemVer、Google SRE 和 Diátaxis 等公认软件工程参考。
+
 ### 验证设置
 
 ```bash

package/dist/main.js

@@ -884,6 +884,102 @@ var ARCHITECTURE_DOC_TEMPLATE_PATH = "docs/templates/architecture-doc.md";
 var WORKFLOW_DOC_TEMPLATE_PATH = "docs/templates/workflow-doc.md";
 var OPERATIONS_DOC_TEMPLATE_PATH = "docs/templates/operations-doc.md";
 var TEST_BEHAVIOR_DOC_TEMPLATE_PATH = "docs/templates/test-behavior-doc.md";
+var renderTemplateSection = (section) => {
+  return [
+    section.heading,
+    "",
+    "<!--",
+    ...section.guidance,
+    "-->",
+    "",
+    `{{${section.placeholder}}}`,
+    ""
+  ];
+};
+var titleToPlaceholder = (title) => {
+  return title.replace(/^#+\s+/u, "").toLowerCase().replaceAll(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+};
+var findTemplateSectionHeadings = (template) => {
+  const matches = [];
+  let fencedCodeMarker = null;
+  let fencedCodeLength = 0;
+  for (const lineMatch of template.matchAll(/^.*(?:\r?\n|$)/gm)) {
+    const rawLine = lineMatch[0];
+    if (rawLine.length === 0) {
+      continue;
+    }
+    const line = rawLine.replace(/\r?\n$/u, "");
+    const fenceMatch = /^(?: {0,3})(`{3,}|~{3,})/u.exec(line);
+    if (fenceMatch) {
+      const marker = fenceMatch[1]?.[0];
+      const length = fenceMatch[1]?.length ?? 0;
+      if (fencedCodeMarker === null) {
+        fencedCodeMarker = marker;
+        fencedCodeLength = length;
+      } else if (marker === fencedCodeMarker && length >= fencedCodeLength) {
+        fencedCodeMarker = null;
+        fencedCodeLength = 0;
+      }
+      continue;
+    }
+    if (fencedCodeMarker === null && /^## .+$/u.test(line)) {
+      matches.push({ heading: line.trim(), index: lineMatch.index });
+    }
+  }
+  return matches;
+};
+var parseTemplateSections = (template) => {
+  const matches = findTemplateSectionHeadings(template);
+  if (matches.length === 0) {
+    return { preamble: template.trimEnd(), sections: [] };
+  }
+  const sections = matches.map((match, index) => {
+    const start = match.index;
+    const next = matches[index + 1];
+    const end = next?.index ?? template.length;
+    return {
+      heading: match.heading,
+      block: template.slice(start, end).trimEnd()
+    };
+  });
+  return {
+    preamble: template.slice(0, matches[0]?.index ?? 0).trimEnd(),
+    sections
+  };
+};
+var mergeTruthDocTemplate = (existingTemplate, defaultTemplate) => {
+  if (existingTemplate.trim().length === 0) {
+    return defaultTemplate;
+  }
+  const defaultParsed = parseTemplateSections(defaultTemplate);
+  const existingParsed = parseTemplateSections(existingTemplate);
+  const defaultHeadings = new Set(defaultParsed.sections.map((section) => section.heading));
+  const customBeforeDefault = /* @__PURE__ */ new Map();
+  const trailingCustomSections = [];
+  existingParsed.sections.forEach((section, index) => {
+    if (defaultHeadings.has(section.heading)) {
+      return;
+    }
+    const nextDefaultSection = existingParsed.sections.slice(index + 1).find((candidate) => defaultHeadings.has(candidate.heading));
+    if (nextDefaultSection) {
+      const bucket = customBeforeDefault.get(nextDefaultSection.heading) ?? [];
+      bucket.push(section);
+      customBeforeDefault.set(nextDefaultSection.heading, bucket);
+      return;
+    }
+    trailingCustomSections.push(section);
+  });
+  const mergedSections = defaultParsed.sections.flatMap((section) => [
+    ...customBeforeDefault.get(section.heading) ?? [],
+    section
+  ]);
+  return [
+    existingParsed.preamble,
+    ...mergedSections.map((section) => section.block),
+    ...trailingCustomSections.map((section) => section.block),
+    ""
+  ].filter((block) => block.length > 0).join("\n\n");
+};
 var renderBehaviorDocTemplateFile = () => {
   return [
     "---",
@@ -899,81 +995,130 @@ var renderBehaviorDocTemplateFile = () => {
     "",
     "## Purpose",
     "",
-    "<!-- State why this feature 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}}",
     ""
   ].join("\n");
 };
+var sectionSpec = (heading, guidance, placeholder = titleToPlaceholder(heading)) => ({ heading, guidance, placeholder });
+var PURPOSE_SECTION = sectionSpec("## 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."
+]);
+var SCOPE_SECTION = sectionSpec("## 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."
+]);
+var PRODUCT_DECISIONS_SECTION = sectionSpec("## 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");
+var RATIONALE_SECTION = sectionSpec("## 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."
+]);
+var NON_GOALS_SECTION = sectionSpec("## 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."
+]);
+var MAINTENANCE_NOTES_SECTION = sectionSpec("## 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."
+]);
 var renderTypedTruthDocTemplate = (truthKind, docType, title, sections) => {
-  const placeholderNameForSection = (section) => {
-    return section.replace(/^#+\s+/u, "").toLowerCase().replaceAll(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
-  };
   return [
     "---",
     "status: active",
@@ -986,86 +1131,153 @@ var renderTypedTruthDocTemplate = (truthKind, docType, title, sections) => {
     "",
     `# ${title}`,
     "",
-    "## Purpose",
-    "",
-    "{{purpose}}",
-    "",
-    "## Scope",
-    "",
-    "{{scope}}",
-    "",
-    ...sections.flatMap((section) => [
-      section,
-      "",
-      `{{${placeholderNameForSection(section)}}}`,
-      ""
-    ]),
-    "## Product Decisions",
-    "",
-    "{{decision}}",
-    "",
-    "## Rationale",
-    "",
-    "{{rationale}}",
-    "",
-    "## Non-Goals",
-    "",
-    "{{non_goals}}",
-    "",
-    "## Maintenance Notes",
-    "",
-    "{{maintenance_notes}}",
-    ""
+    ...renderTemplateSection(PURPOSE_SECTION),
+    ...renderTemplateSection(SCOPE_SECTION),
+    ...sections.flatMap(renderTemplateSection),
+    ...renderTemplateSection(PRODUCT_DECISIONS_SECTION),
+    ...renderTemplateSection(RATIONALE_SECTION),
+    ...renderTemplateSection(NON_GOALS_SECTION),
+    ...renderTemplateSection(MAINTENANCE_NOTES_SECTION)
   ].join("\n");
 };
 var renderContractDocTemplateFile = () => {
   return renderTypedTruthDocTemplate("contract", "contract", "{{title}}", [
-    "## Contract Surface",
-    "## Inputs",
-    "## Outputs",
-    "## Errors And Diagnostics",
-    "## Compatibility Rules",
-    "## Versioning And Migration"
+    sectionSpec("## 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."
+    ]),
+    sectionSpec("## Inputs", [
+      "Document accepted parameters, payloads, files, environment/config keys, permissions, and validation rules.",
+      "Include required/optional status, defaults, constraints, and normalization behavior."
+    ]),
+    sectionSpec("## Outputs", [
+      "Document returned values, emitted files/events, state changes, side effects, and success diagnostics.",
+      "Make externally observable behavior explicit enough for compatibility review."
+    ]),
+    sectionSpec("## 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."
+    ]),
+    sectionSpec("## 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."
+    ]),
+    sectionSpec("## 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."
+    ])
   ]);
 };
 var renderArchitectureDocTemplateFile = () => {
   return renderTypedTruthDocTemplate("architecture", "architecture", "{{title}}", [
-    "## System Role",
-    "## Boundaries",
-    "## Components",
-    "## Data And Control Flow",
-    "## Ownership",
-    "## Cross-Cutting Constraints"
+    sectionSpec("## 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."
+    ]),
+    sectionSpec("## 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."
+    ]),
+    sectionSpec("## 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."
+    ]),
+    sectionSpec("## 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."
+    ]),
+    sectionSpec("## 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."
+    ]),
+    sectionSpec("## 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."
+    ])
   ]);
 };
 var renderWorkflowDocTemplateFile = () => {
   return renderTypedTruthDocTemplate("workflow", "behavior", "{{title}}", [
-    "## Triggers",
-    "## Inputs",
-    "## Execution Model",
-    "## Steps",
-    "## State, Retry, And Failure Behavior",
-    "## Outputs"
+    sectionSpec("## 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."
+    ]),
+    sectionSpec("## Inputs", [
+      "Document data, files, config, context, credentials, and environmental assumptions consumed by the workflow.",
+      "Include validation, defaults, and normalization that happen before execution."
+    ]),
+    sectionSpec("## 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."
+    ]),
+    sectionSpec("## 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."
+    ]),
+    sectionSpec("## 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."
+    ]),
+    sectionSpec("## 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."
+    ])
   ]);
 };
 var renderOperationsDocTemplateFile = () => {
   return renderTypedTruthDocTemplate("operations", "behavior", "{{title}}", [
-    "## Operational Surface",
-    "## Runtime Topology",
-    "## Configuration",
-    "## Permissions",
-    "## Deployment And Rollback",
-    "## Availability And Observability"
+    sectionSpec("## 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."
+    ]),
+    sectionSpec("## 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."
+    ]),
+    sectionSpec("## 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."
+    ]),
+    sectionSpec("## Permissions", [
+      "Document required identities, roles, scopes, filesystem/network permissions, and least-privilege boundaries.",
+      "Include user-facing authorization behavior and operator access requirements when relevant."
+    ]),
+    sectionSpec("## 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."
+    ]),
+    sectionSpec("## 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."
+    ])
   ]);
 };
 var renderTestBehaviorDocTemplateFile = () => {
   return renderTypedTruthDocTemplate("test-behavior", "behavior", "{{title}}", [
-    "## Test Surface",
-    "## Fixtures And Data Model",
-    "## Execution Model",
-    "## Assertions And Invariants",
-    "## Isolation Rules",
-    "## Reporting And Failure Semantics"
+    sectionSpec("## 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."
+    ]),
+    sectionSpec("## 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."
+    ]),
+    sectionSpec("## 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."
+    ]),
+    sectionSpec("## 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."
+    ]),
+    sectionSpec("## 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."
+    ]),
+    sectionSpec("## 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."
+    ])
   ]);
 };
 var renderTemplate = (template, values) => {
@@ -1394,6 +1606,15 @@ var readBehaviorDocTemplate = async (rootDir) => {
     throw error;
   }
 };
+var ensureOrUpdateTruthDocTemplate = async (rootDir, templatePath, defaultTemplate) => {
+  const seededResult = await ensureRepoFile(rootDir, templatePath, defaultTemplate);
+  if (seededResult.status !== "unchanged") {
+    return seededResult;
+  }
+  const existingTemplate = await fs5.readFile(resolveRepoPath(rootDir, templatePath), "utf8");
+  const mergedTemplate = mergeTruthDocTemplate(existingTemplate, defaultTemplate);
+  return writeRepoFile(rootDir, templatePath, mergedTemplate);
+};
 var scaffoldHierarchy = async (rootDir, config) => {
   const results = [];
   const truthDocsRoot = truthRoot2(config);
@@ -1424,26 +1645,42 @@ var scaffoldHierarchy = async (rootDir, config) => {
     )
   );
   results.push(
-    await ensureRepoFile(rootDir, BEHAVIOR_DOC_TEMPLATE_PATH, renderBehaviorDocTemplateFile())
+    await ensureOrUpdateTruthDocTemplate(
+      rootDir,
+      BEHAVIOR_DOC_TEMPLATE_PATH,
+      renderBehaviorDocTemplateFile()
+    )
   );
   results.push(
-    await ensureRepoFile(rootDir, CONTRACT_DOC_TEMPLATE_PATH, renderContractDocTemplateFile())
+    await ensureOrUpdateTruthDocTemplate(
+      rootDir,
+      CONTRACT_DOC_TEMPLATE_PATH,
+      renderContractDocTemplateFile()
+    )
   );
   results.push(
-    await ensureRepoFile(
+    await ensureOrUpdateTruthDocTemplate(
       rootDir,
       ARCHITECTURE_DOC_TEMPLATE_PATH,
       renderArchitectureDocTemplateFile()
     )
   );
   results.push(
-    await ensureRepoFile(rootDir, WORKFLOW_DOC_TEMPLATE_PATH, renderWorkflowDocTemplateFile())
+    await ensureOrUpdateTruthDocTemplate(
+      rootDir,
+      WORKFLOW_DOC_TEMPLATE_PATH,
+      renderWorkflowDocTemplateFile()
+    )
   );
   results.push(
-    await ensureRepoFile(rootDir, OPERATIONS_DOC_TEMPLATE_PATH, renderOperationsDocTemplateFile())
+    await ensureOrUpdateTruthDocTemplate(
+      rootDir,
+      OPERATIONS_DOC_TEMPLATE_PATH,
+      renderOperationsDocTemplateFile()
+    )
   );
   results.push(
-    await ensureRepoFile(
+    await ensureOrUpdateTruthDocTemplate(
       rootDir,
       TEST_BEHAVIOR_DOC_TEMPLATE_PATH,
       renderTestBehaviorDocTemplateFile()
@@ -1523,7 +1760,8 @@ var REPOSITORY_INTELLIGENCE_INSTRUCTIONS = [
 var FEATURE_DOC_TEMPLATE_INSTRUCTIONS = [
   "When creating or updating a truth doc, inspect the routed truth kind and use the matching `docs/templates/<kind>-doc.md` template.",
   "Supported kinds: behavior, contract, architecture, workflow, operations, and test-behavior.",
-  "Align existing docs to that template while preserving accurate authored content.",
+  "Treat the HTML comments under each template section as normative authoring guidance for that section.",
+  "Align existing docs to that template and write or repair section content so it satisfies the comment guidance while preserving accurate authored content.",
   "If the template is missing, use Scope, Product Decisions, Rationale, and the kind-specific current-truth section.",
   "Teams may edit the template files under docs/templates/ to define their local truth-doc standards."
 ].join("\n");
@@ -7508,14 +7746,21 @@ var runContext = async (options) => {
 };
 
 // src/cli/program.ts
+var markFailedWhenErrorDiagnosticsExist = (result) => {
+  if (result.diagnostics.some((diagnostic) => diagnostic.severity === "error")) {
+    process.exitCode = 1;
+  }
+};
 var writeResult = (result, options) => {
   const output = options.json ? renderJson(result) : renderHuman(result);
   process.stdout.write(`${output}
 `);
+  markFailedWhenErrorDiagnosticsExist(result);
 };
 var writeContextResult = (result, options) => {
   if (!options.json && options.format === "markdown" && typeof result.data?.markdown === "string") {
     process.stdout.write(result.data.markdown);
+    markFailedWhenErrorDiagnosticsExist(result);
     return;
   }
   writeResult(result, options);