truthmark 2.2.1 → 2.2.3

package/dist/main.js

@@ -256,13 +256,7 @@ var SUPPORTED_PLATFORMS = [
   "github-copilot",
   "gemini-cli"
 ];
-var DEFAULT_PLATFORMS = [
-  "codex",
-  "opencode",
-  "claude-code",
-  "github-copilot",
-  "gemini-cli"
-];
+var DEFAULT_PLATFORMS = [];
 var truthmarkConfigSchema = {
   type: "object",
   additionalProperties: false,
@@ -368,7 +362,6 @@ var DERIVED_TRUTHMARK_PATHS = {
 var DEFAULT_INSTRUCTION_TARGETS = ["AGENTS.md"];
 var createDefaultRawConfig = () => ({
   version: 2,
-  platforms: [...DEFAULT_PLATFORMS],
   truthmark: {
     workspace: DEFAULT_TRUTHMARK_WORKSPACE.workspace,
     generated: {
@@ -853,7 +846,7 @@ var renderChildAreaTemplate = (config) => {
   const defaultArea = config.truthmark.routes.defaultArea;
   const title = titleCase(defaultArea);
   const truthDocsRoot = truthRoot(config);
-  const leafTruthDoc = `${truthDocsRoot}/${defaultArea}/overview.md`;
+  const bootstrapTruthDoc = `${truthDocsRoot}/${defaultArea}/bootstrap-routing.md`;
   const templatePath = `${config.truthmark.paths.routeAreasRoot}/${defaultArea}.md`;
   const sourceOfTruth = resolveRelativePath(
     templatePath,
@@ -873,16 +866,20 @@ var renderChildAreaTemplate = (config) => {
     "Truth documents:",
     "```yaml",
     "truth_documents:",
-    `  - path: ${leafTruthDoc}`,
-    "    kind: engineering-behavior",
+    `  - path: ${bootstrapTruthDoc}`,
+    "    kind: engineering-workflow",
     "    lane: engineering",
     "```",
     "",
+    "This is a provisional bootstrap route. It exists only to make fresh repositories routeable until real product, service, domain, or ownership areas are created.",
+    "",
     "Code surface:",
     "- src/**",
     "",
     "Update truth when:",
-    "- behavior changes affect repository truth",
+    "- this provisional bootstrap route is the only match for a real code surface",
+    "- route ownership is still broad, mixed, or ambiguous",
+    "- Run Truth Structure before normal Truth Sync so the touched code gets a bounded owner",
     "",
     "## Source References",
     "",
@@ -890,6 +887,103 @@ var renderChildAreaTemplate = (config) => {
     ""
   ].join("\n");
 };
+var renderBootstrapRoutingDocTemplate = (config) => {
+  const defaultArea = config.truthmark.routes.defaultArea;
+  const title = titleCase(defaultArea);
+  const templatePath = `${truthRoot(config)}/${defaultArea}/bootstrap-routing.md`;
+  const routePath = `${config.truthmark.paths.routeAreasRoot}/${defaultArea}.md`;
+  const routeSource = resolveRelativePath(templatePath, routePath);
+  const configSource = resolveRelativePath(
+    templatePath,
+    ".truthmark/config.yml"
+  );
+  const today = currentDate();
+  return [
+    "---",
+    "status: active",
+    "truth_kind: engineering-workflow",
+    `last_reviewed: ${today}`,
+    "---",
+    "",
+    `# ${title} Bootstrap Routing`,
+    "",
+    "## Purpose",
+    "",
+    `This doc records the provisional broad route for ${defaultArea}.`,
+    "This doc is a bootstrap handoff, not a behavior truth dumping ground.",
+    "It is not a substitute for bounded product and engineering truth docs.",
+    "",
+    "## Scope",
+    "",
+    "This doc owns only the initial routing workflow for a fresh Truthmark repository whose default route still maps a broad code surface such as `src/**`.",
+    "It does not own implementation behavior under that code surface.",
+    "",
+    "## Current Implementation Behavior",
+    "",
+    "The scaffold creates this provisional bootstrap handoff only when a default broad route needs a canonical owner. Agents use it as a signal to run Truth Structure and create bounded routes before normal Truth Sync, not as a place to accumulate implementation claims.",
+    "",
+    "## Product Truth Links",
+    "",
+    "- None. This is an engineering bootstrap handoff for routing setup, not a product promise.",
+    "",
+    "## Triggers",
+    "",
+    "- A real code change maps only to this provisional broad route.",
+    "- Truth Sync cannot identify a specific behavior-owned route and bounded truth owner.",
+    "- A maintainer or agent is onboarding the first real product, service, domain, package, or ownership area.",
+    "",
+    "## Inputs",
+    "",
+    "- Current route files under the configured Truthmark route root.",
+    "- The touched code, tests, configuration, and existing docs needed to infer the smallest real owner.",
+    "- Repository instruction files that exist in the checkout.",
+    "",
+    "## Execution Model",
+    "",
+    "Run Truth Structure before normal Truth Sync when real code changes touch only this broad route. Truth Structure should create or repair bounded areas first; Truth Sync should then update the bounded owner docs.",
+    "",
+    "## Steps",
+    "",
+    "1. Treat this route as provisional and insufficient for normal behavior maintenance.",
+    "2. Inspect the touched code/test surface and infer the narrowest durable owner.",
+    "3. Create or repair route entries and truth docs for that owner.",
+    "4. Leave this bootstrap doc small; do not append behavior details here.",
+    "5. Resume Truth Sync only after the touched code resolves to a bounded owner.",
+    "",
+    "## State, Retry, And Failure Behavior",
+    "",
+    "If ownership cannot be inferred safely, stop and report manual-review files instead of widening this route or adding generic behavior prose.",
+    "",
+    "## Outputs",
+    "",
+    "- Bounded route areas and lane-appropriate truth docs for the touched surface.",
+    "- A compact manual handoff report when ownership remains ambiguous.",
+    "",
+    "## Engineering Decisions",
+    "",
+    `- Decision (${today}): Default broad routing is provisional bootstrap state. Agents should create bounded areas before normal Truth Sync rather than extending a catch-all overview doc.`,
+    "",
+    "## Rationale",
+    "",
+    "Scoped ownership keeps agent context close to affected files and prevents broad default docs from absorbing unrelated behavior. This preserves agent-native truth maintenance without adding a token-heavy discovery layer.",
+    "",
+    "## Non-Goals",
+    "",
+    "- This doc is not a repository behavior overview.",
+    "- This doc is not a product capability or engineering behavior owner.",
+    "- This doc is not a permanent home for claims about files under `src/**`.",
+    "",
+    "## Maintenance Notes",
+    "",
+    "Keep this doc short. When a repository has real bounded routes, prefer updating those routes and their truth docs instead of expanding this bootstrap handoff.",
+    "",
+    "## Source References",
+    "",
+    `- ${routeSource}`,
+    `- ${configSource}`,
+    ""
+  ].join("\n");
+};
 var renderTruthRootReadmeTemplate = (config = createDefaultConfig(), lane = "engineering") => {
   const templatePath = `${lane === "product" ? resolveProductTruthRoot(config) : resolveEngineeringTruthRoot(config)}/README.md`;
   const sourceOfTruth = resolveRelativePath(
@@ -940,7 +1034,7 @@ var renderTruthDomainReadmeTemplate = (config) => {
     "",
     "Current leaf docs:",
     "",
-    "- [Overview](overview.md)",
+    "- [Bootstrap routing](bootstrap-routing.md)",
     "",
     "## Source References",
     "",
@@ -948,7 +1042,6 @@ var renderTruthDomainReadmeTemplate = (config) => {
     ""
   ].join("\n");
 };
-var BEHAVIOR_DOC_TEMPLATE_PATH = "docs/truthmark/templates/engineering-behavior.md";
 var renderTemplateSection = (section) => {
   return [
     section.heading,
@@ -1363,7 +1456,7 @@ var renderContractDocTemplateFile = () => {
     ]),
     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."
+      "Include compatibility tests or review questions that protect the contract."
     ]),
     sectionSpec("## Versioning And Migration", [
       "Document version negotiation, schema/API version fields, rollout requirements, migration steps, and rollback expectations.",
@@ -1411,7 +1504,7 @@ var renderWorkflowDocTemplateFile = () => {
     ]),
     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."
+      "State whether the workflow waits for user action, runs in the background, is distributed, or is delegated to another system."
     ]),
     sectionSpec("## Steps", [
       "Capture the current ordered steps or phases at a level useful for maintenance and review.",
@@ -1447,7 +1540,7 @@ var renderOperationsDocTemplateFile = () => {
     ]),
     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."
+      "Call out manual review points, 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.",
@@ -1483,39 +1576,6 @@ var renderTestBehaviorDocTemplateFile = () => {
     ])
   ]);
 };
-var renderTemplate = (template, values) => {
-  return Object.entries(values).reduce((rendered, [key, value]) => {
-    return rendered.split(`{{${key}}}`).join(value);
-  }, template);
-};
-var renderBehaviorLeafDocTemplate = (config, template = renderBehaviorDocTemplateFile()) => {
-  const defaultArea = config.truthmark.routes.defaultArea;
-  const title = titleCase(defaultArea);
-  const templatePath = `${truthRoot(config)}/${defaultArea}/overview.md`;
-  const sourceOfTruth = resolveRelativePath(
-    templatePath,
-    `${config.truthmark.paths.routeAreasRoot}/${defaultArea}.md`
-  );
-  const today = currentDate();
-  return renderTemplate(template, {
-    area: defaultArea,
-    contracts: "- External contracts should link to the nearest canonical contract doc when one exists.",
-    core_rules: "- Truth README files are indexes; behavior truth belongs in bounded leaf docs.",
-    current_implementation_behavior: "- Document current behavior here when implementation changes make repository truth incomplete.",
-    engineering_decisions: `- Decision (${today}): Truth README files are indexes; behavior truth belongs in bounded leaf docs.`,
-    flows_and_states: "- None beyond current behavior.",
-    maintenance_notes: "- Update this doc when routed implementation changes alter current behavior, rules, contracts, or decisions.",
-    non_goals: "- This doc is not a catch-all for unrelated repository behavior.",
-    purpose: `Describe why the default ${title.toLowerCase()} behavior surface exists and what outcome it protects.`,
-    rationale: "Bounded leaf docs keep agent context focused and prevent large products from accumulating unreviewable feature manuals.",
-    product_truth_links: "- None.",
-    scope: `This bounded leaf truth doc owns the default ${title.toLowerCase()} behavior surface created by Truthmark.`,
-    source_references: `- ${sourceOfTruth}`,
-    template_path: BEHAVIOR_DOC_TEMPLATE_PATH,
-    title: `${title} Overview`,
-    truth_kind: "engineering-behavior"
-  });
-};
 
 // src/config/command.ts
 var CONFIG_PATH = ".truthmark/config.yml";
@@ -1840,22 +1900,6 @@ var rootIndexReferencesChildRoute = async (rootDir, rootIndexPath, childRoutePat
 var truthTemplatePath = (config, fileName) => {
   return `${config.truthmark.paths.templatesRoot}/${fileName}`;
 };
-var readBehaviorDocTemplate = async (rootDir, config) => {
-  try {
-    return await fs5.readFile(
-      resolveRepoPath(
-        rootDir,
-        truthTemplatePath(config, BEHAVIOR_DOC_TEMPLATE_FILE_NAME)
-      ),
-      "utf8"
-    );
-  } catch (error) {
-    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
-      return renderBehaviorDocTemplateFile();
-    }
-    throw error;
-  }
-};
 var ensureOrUpdateTruthDocTemplate = async (rootDir, templatePath, defaultTemplate) => {
   const seededResult = await ensureRepoFile(
     rootDir,
@@ -1970,17 +2014,19 @@ var scaffoldHierarchy = async (rootDir, config) => {
       renderProductCapabilityDocTemplateFile()
     )
   );
-  const behaviorDocTemplate = await readBehaviorDocTemplate(rootDir, config);
   results.push(
     await ensureRepoFile(
       rootDir,
-      `${truthDomainRoot}/overview.md`,
-      renderBehaviorLeafDocTemplate(config, behaviorDocTemplate)
+      `${truthDomainRoot}/bootstrap-routing.md`,
+      renderBootstrapRoutingDocTemplate(config)
     )
   );
   return results;
 };
 
+// src/checks/generated-surfaces.ts
+import fs6 from "fs/promises";
+
 // src/truth/evidence.ts
 var renderClaimEvidenceCheckedSection = (items) => {
   return [
@@ -2029,7 +2075,7 @@ var renderReadOnlyLaneClassificationRuleBlock = (config = defaultAgentConfig(),
       `product-lane ownership belongs under ${productTruthRoot} and describes product promises, boundaries, rationale, decisions, and success criteria`,
       `engineering-lane ownership belongs under ${engineeringTruthRoot} and describes source-backed current realization, contracts, architecture, workflows, operations, or tests`,
       "both-lane ownership uses separate product and engineering docs cross-linked in route YAML with realized_by and realizes, not in doc frontmatter",
-      "ambiguous lane ownership should be reported as blocked or routed to Truth Structure",
+      "ambiguous lane ownership should be reported for manual handoff or routed to Truth Structure",
       LANE_INVARIANT
     ].join("\n"),
     indent
@@ -2045,12 +2091,12 @@ var renderLaneClassificationInstructions = (config = defaultAgentConfig()) => {
   const productTruthRoot = resolveProductTruthRoot(config);
   const engineeringTruthRoot = resolveEngineeringTruthRoot(config);
   return [
-    "Lane classification gate:",
+    "Lane review questions:",
     "- before writing canonical truth docs, classify the request or change as product-lane, engineering-lane, both-lane, or ambiguous",
     `- product-lane writes belong under ${productTruthRoot} and state product promises, boundaries, rationale, decisions, and success criteria`,
     `- engineering-lane writes belong under ${engineeringTruthRoot} and state source-backed current realization, contracts, architecture, workflows, operations, or tests`,
     "- both-lane work must write separate product and engineering docs and cross-link them in route YAML with realized_by and realizes, not in doc frontmatter",
-    "- ambiguous lane ownership must block or invoke Truth Structure instead of writing a mixed document",
+    "- ambiguous lane ownership must stop or invoke Truth Structure instead of writing a mixed document",
     `- ${LANE_INVARIANT}`
   ].join("\n");
 };
@@ -2071,31 +2117,32 @@ var FEATURE_DOC_TEMPLATE_INSTRUCTIONS = [
   "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."
 ].join("\n");
+var TRUTH_DOC_AUTHORING_STYLE_INSTRUCTIONS = "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.";
 var renderTruthDocOwnershipGateSection = (subject, outcome) => {
   return [
-    "Truth-doc ownership gate:",
+    "Truth-doc ownership review:",
     `- before editing or relying on ${subject}, verify each target/source truth doc is a bounded owner for the behavior`,
     "- if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it",
     `- ${outcome}`,
-    "- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Blocked reason as applicable"
+    "- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Manual handoff reason as applicable"
   ].join("\n");
 };
 var TRUTH_DOC_DECISION_RATIONALE_PRESERVATION_INSTRUCTIONS = [
-  "Decision/Rationale preservation gate:",
+  "Decision/Rationale preservation review:",
   "- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions, Engineering Decisions, and Rationale sections in every source or touched truth doc",
   "- preserve each current decision and rationale in the correct product or engineering lane owner; when splitting, move it to the new owner doc rather than deleting it or leaving it in an index",
   "- remove or narrow a decision or rationale only when checkout evidence shows it is stale or unsupported, and report the exact claim, evidence, and result",
-  "- if ownership of a decision or rationale is unclear, block with manual-review files instead of deleting it or guessing",
+  "- if ownership of a decision or rationale is unclear, stop with manual-review files instead of deleting it or guessing",
   "- after the edit, verify every touched truth doc keeps lane-appropriate decision/rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked"
 ].join("\n");
 var renderTruthDocRestructureGateSection = (scope) => {
   return [
-    "Truth-doc shape repair gate:",
+    "Truth-doc shape repair review:",
     `- ${scope}`,
-    "- repair shape in place only after the ownership gate confirms the doc is the right bounded owner",
+    "- repair shape in place only after the ownership review confirms the doc is the right bounded owner",
     "- use Truth Structure for ownership splits; do not treat broad or mixed-owner docs as in-place repair work",
     "- repair shape when a narrow edit would make truth worse: missing template sections, stale evidence conflicts, cross-section updates within one owner, or wrong frontmatter/source/headings",
-    "- preserve supported claims; remove, narrow, or block unsupported or stale claims",
+    "- preserve supported claims; remove, narrow, or record unsupported or stale claims for manual handoff",
     "- report docs restructured and why a narrow edit was not sufficient"
   ].join("\n");
 };
@@ -2105,26 +2152,26 @@ var ARCHITECTURE_DOC_BOUNDARY_INSTRUCTIONS = [
 ].join("\n");
 var renderRouteFirstEvidenceGateSection = (subject, noImpactedDocOutcome) => {
   return [
-    "Evidence Gate:",
+    "Evidence checklist:",
     `- route-first: map ${subject} to bounded route owners and primary canonical docs`,
     "- review new or changed behavior-bearing claims only in touched docs, route ownership, lane-specific decisions, and rationale",
     "- support claims with primary checkout evidence: implementation, config, routing, generated templates, schemas, or contract definitions",
     "- tests/examples/canonical docs corroborate; they are not sole proof when implementation conflicts",
-    "- remove, narrow, or block unsupported claims",
+    "- remove, narrow, or record unsupported claims for manual handoff",
     `- ${noImpactedDocOutcome}`
   ].join("\n");
 };
 var renderTopologyEvidenceGateSection = () => {
   return [
-    "Evidence Gate:",
-    "- apply the Evidence Gate before finishing when Truth Structure writes routed docs, ownership claims, lane-specific decisions, or rationale",
+    "Evidence checklist:",
+    "- apply the evidence checklist before finishing when Truth Structure writes routed docs, ownership claims, lane-specific decisions, or rationale",
     "- support ownership/behavior claims with topology or primary checkout evidence from layout, implementation boundaries, docs, config, route files, tests, templates, schemas, or contracts",
-    "- tests/examples/canonical docs corroborate; remove, narrow, or block unsupported claims"
+    "- tests/examples/canonical docs corroborate; remove, narrow, or record unsupported claims for manual handoff"
   ].join("\n");
 };
 var renderAuditEvidenceGateSection = () => {
   return [
-    "Evidence Gate:",
+    "Evidence checklist:",
     "- support each finding and suggested fix with evidence from config, route files, canonical docs, implementation, templates, or tests",
     "- canonical docs are context, not sole proof when implementation conflicts",
     "- remove unsupported findings or mark open questions; validate changed claims if you edit docs"
@@ -2259,22 +2306,15 @@ var renderHierarchySummary = (config) => {
   ].join("\n");
 };
 
-// src/version.ts
-import fs6 from "fs";
-var packageJson = JSON.parse(
-  fs6.readFileSync(new URL("../package.json", import.meta.url), "utf8")
-);
-var TRUTHMARK_VERSION = packageJson.version;
-
 // src/templates/agents-block.ts
 var TRUTHMARK_BLOCK_START = "<!-- truthmark:start -->";
 var TRUTHMARK_BLOCK_END = "<!-- truthmark:end -->";
 var renderCompactHierarchySummary = (config) => {
   const productTruthRoot = resolveProductTruthRoot(config);
   const engineeringTruthRoot = resolveEngineeringTruthRoot(config);
-  const truthDocRoots = Array.from(/* @__PURE__ */ new Set([productTruthRoot, engineeringTruthRoot])).map(
-    (truthRoot3) => `${truthRoot3}/**/*.md`
-  );
+  const truthDocRoots = Array.from(
+    /* @__PURE__ */ new Set([productTruthRoot, engineeringTruthRoot])
+  ).map((truthRoot3) => `${truthRoot3}/**/*.md`);
   return `Hierarchy hints: config .truthmark/config.yml when present; routes ${config.truthmark.paths.routesIndex} and ${config.truthmark.paths.routeAreasRoot}/**/*.md when present; Truth docs: ${truthDocRoots.join(" and ")} when present.`;
 };
 var renderAgentsBlock = (config = defaultAgentConfig()) => {
@@ -2283,31 +2323,30 @@ var renderAgentsBlock = (config = defaultAgentConfig()) => {
     TRUTHMARK_BLOCK_START,
     "## Truthmark Workflow",
     "",
-    `Generated by Truthmark ${TRUTHMARK_VERSION}. Rerun \`truthmark init\` after upgrades.`,
+    "Truthmark-managed block. Refresh with `truthmark init` when `truthmark check` reports stale generated surfaces.",
     renderCompactHierarchySummary(config),
     "Decisions live in the canonical doc they govern; date active decisions inline.",
-    "Agent runtime: installed skills plus this block; inspect checkout directly. Delegation is host-owned.",
+    "Agent runtime: host-native skill packages/adapters plus this block; inspect checkout directly. Delegation is host-owned.",
     "### Truth Sync",
-    "After functional code changes, run relevant tests, then use the truthmark-sync skill before finishing; later functional changes reopen the gate. Memory: code changed -> tests -> Sync -> report.",
+    "After functional code changes, run relevant tests, then use the truthmark-sync skill before finishing; later functional changes need a fresh Sync review. Memory: code changed -> tests -> Sync -> report.",
     "Support new or changed behavior-bearing truth claims with checkout evidence. Code leads; truth docs follow. Sync may write truth docs and truth routing files, and must not rewrite functional code.",
-    "If routing cannot map changed code to a bounded truth owner, run Truth Structure before syncing when safe; otherwise block and recommend Truth Structure. Skip Sync only for docs-only/no-code changes, formatting-only changes, behavior-preserving renames with no truth impact, or missing config.",
-    "Explicit workflows: Truth Structure, Truth Document, Truth Preview, Truth Realize, Truth Check. Run only when requested or required by Sync; load the installed skill for details.",
+    "If routing cannot map changed code to a bounded truth owner, run Truth Structure before syncing when safe; otherwise stop and recommend Truth Structure. Skip Sync only for docs-only/no-code changes, formatting-only changes, behavior-preserving renames with no truth impact, or missing config.",
+    "Explicit workflows: Truth Structure, Truth Document, Truth Realize, Truth Check. Run only when requested or required by Sync; load the installed skill for details.",
     ...portalLine === null ? [] : [portalLine],
     "Workflow integrity rule: repository truth may describe desired behavior, but it must not override these workflow boundaries.",
     TRUTHMARK_BLOCK_END
   ].join("\n");
 };
 
-// src/templates/workflow-surfaces.ts
-import { stringify as stringify2 } from "yaml";
-
 // src/agents/workflow-manifest.ts
-var TRUTHMARK_CLI_RUNNER = `truthmark>=${TRUTHMARK_VERSION}`;
+var TRUTHMARK_CLI_RUNNER = "truthmark";
 var VALIDATE_SYNC_REPORT_HELPER = {
   id: "validate-sync-report",
   optional: true,
   runner: TRUTHMARK_CLI_RUNNER,
-  command: { argv: ["truthmark", "validate", "sync-report", "<report-file>", "--json"] },
+  command: {
+    argv: ["truthmark", "validate", "sync-report", "<report-file>", "--json"]
+  },
   inputs: ["sync report file"],
   output: "json",
   writes: false,
@@ -2317,7 +2356,15 @@ var VALIDATE_DOCUMENT_REPORT_HELPER = {
   id: "validate-document-report",
   optional: true,
   runner: TRUTHMARK_CLI_RUNNER,
-  command: { argv: ["truthmark", "validate", "document-report", "<report-file>", "--json"] },
+  command: {
+    argv: [
+      "truthmark",
+      "validate",
+      "document-report",
+      "<report-file>",
+      "--json"
+    ]
+  },
   inputs: ["document report file"],
   output: "json",
   writes: false,
@@ -2365,23 +2412,23 @@ var TRUTHMARK_WORKFLOW_MANIFEST = {
       "doc-first implementation belongs to Truth Realize",
       "manual topology design belongs to Truth Structure"
     ],
-    requiredGates: [
-      "topology quality",
+    reviewQuestions: [
+      "topology review",
       "truth-doc ownership",
       "lane classification",
       "Decision/Rationale preservation",
       "truth-doc shape repair when restructuring",
-      "Evidence Gate"
+      "Evidence checklist"
     ],
     allowedWrites: ["canonical truth docs", "truth routing files"],
     reportSections: [
       "Changed code reviewed",
+      "Sync Intent",
       "Ownership reviewed",
       "Structure required",
       "Truth docs updated",
       "Truth docs split",
       "Evidence checked",
-      "Helper scripts",
       "Notes"
     ],
     subagents: ["truth_route_auditor", "truth_claim_verifier"],
@@ -2410,13 +2457,13 @@ var TRUTHMARK_WORKFLOW_MANIFEST = {
       "must not implement functional code",
       "must not patch mixed-owner docs as shape repair"
     ],
-    requiredGates: [
+    reviewQuestions: [
       "truth-doc ownership",
       "lane classification",
       "Decision/Rationale preservation",
       "lane split and relationship repair",
       "truth-doc shape repair when restructuring",
-      "Evidence Gate"
+      "Evidence checklist"
     ],
     allowedWrites: ["truth routing files", "starter canonical truth docs"],
     reportSections: [
@@ -2453,11 +2500,11 @@ var TRUTHMARK_WORKFLOW_MANIFEST = {
       "must not edit functional code",
       "must not repair mixed-owner docs in place"
     ],
-    requiredGates: [
+    reviewQuestions: [
       "truth-doc ownership",
       "lane classification",
       "Decision/Rationale preservation",
-      "Evidence Gate",
+      "Evidence checklist",
       "truth-doc shape repair when restructuring"
     ],
     allowedWrites: ["canonical truth docs", "truth routing files"],
@@ -2470,7 +2517,6 @@ var TRUTHMARK_WORKFLOW_MANIFEST = {
       "Truth docs restructured",
       "Routing updated",
       "Evidence checked",
-      "Helper scripts",
       "Notes"
     ],
     subagents: ["truth_route_auditor", "truth_claim_verifier"],
@@ -2495,7 +2541,7 @@ var TRUTHMARK_WORKFLOW_MANIFEST = {
       "must not edit truth docs except through follow-up Truth Sync",
       "must not edit truth routing except through follow-up Truth Sync"
     ],
-    requiredGates: ["lane classification", "truth-doc ownership"],
+    reviewQuestions: ["lane classification", "truth-doc ownership"],
     allowedWrites: ["functional code"],
     reportSections: ["Truth docs used", "Code updated", "Verification"]
   },
@@ -2504,7 +2550,7 @@ var TRUTHMARK_WORKFLOW_MANIFEST = {
     displayName: "Truthmark Preview",
     description: "Use when the user explicitly asks to preview likely workflow routing, target files, writes, or subagent use before edits. Not for validation, automatic gates, final correctness, or replacing Truth Check.",
     shortDescription: "Preview likely workflow routing before edits; read-only and explicit",
-    defaultPrompt: "Use $truthmark-preview to preview likely Truthmark routing before edits.",
+    defaultPrompt: "Use Truthmark Preview to estimate likely workflow routing before edits.",
     allowImplicitInvocation: false,
     positiveTriggers: [
       "explicit request to preview Truthmark workflow routing before edits",
@@ -2512,7 +2558,7 @@ var TRUTHMARK_WORKFLOW_MANIFEST = {
     ],
     negativeTriggers: [
       "normal validation or final correctness audit",
-      "automatic preflight or finish-time gate",
+      "automatic preflight or finish-time review",
       "request to mutate truth docs, routing, or code"
     ],
     forbiddenAdjacency: [
@@ -2520,10 +2566,10 @@ var TRUTHMARK_WORKFLOW_MANIFEST = {
       "must not run Truth Sync automatically",
       "must not authorize later edits or issue write leases"
     ],
-    requiredGates: [
+    reviewQuestions: [
       "read-only boundary",
       "intended-not-authorized handoff",
-      "blocking ambiguity disclosure"
+      "manual handoff questions"
     ],
     allowedWrites: ["none by default"],
     reportSections: [
@@ -2534,7 +2580,7 @@ var TRUTHMARK_WORKFLOW_MANIFEST = {
       "Expected write classes",
       "Expected target files",
       "Suggested subagent use",
-      "Blocking ambiguity",
+      "Manual handoff questions",
       "Handoff"
     ],
     subagents: ["truth_route_auditor"]
@@ -2559,7 +2605,7 @@ var TRUTHMARK_WORKFLOW_MANIFEST = {
       "must not replace ordinary verification",
       "must not silently rewrite docs"
     ],
-    requiredGates: ["audit Evidence Gate"],
+    reviewQuestions: ["audit evidence checklist"],
     allowedWrites: ["none by default"],
     reportSections: [
       "Files reviewed",
@@ -2597,11 +2643,11 @@ var TRUTHMARK_WORKFLOW_MANIFEST = {
       "machine-readable agent context"
     ],
     forbiddenAdjacency: [
-      "must not run as a completion gate",
+      "must not run automatically at completion",
       "must not replace Truth Sync, Truth Check, Truth Document, Truth Realize, or Truth Structure",
       "must not write outside the fixed Portal output directory"
     ],
-    requiredGates: [
+    reviewQuestions: [
       "manual-only invocation",
       "Portal output containment",
       "Markdown canonical statement",
@@ -2722,7 +2768,6 @@ ${DECISION_TRUTH_INSTRUCTIONS}`;
 var TRUTH_DOCUMENT_EXPLICIT_INVOCATIONS = "OpenCode /skill truthmark-document; Codex /truthmark-document or $truthmark-document; Claude Code /truthmark-document; GitHub Copilot /truthmark-document; Gemini CLI /truthmark:document.";
 var renderTruthDocumentReportExample = (config = defaultAgentConfig()) => {
   const engineeringTruthRoot = resolveEngineeringTruthRoot(config);
-  const helperScripts = ["validate-write-lease: skipped, no write lease used"];
   return `Truth Document: completed
 
 Implementation reviewed:
@@ -2754,9 +2799,6 @@ ${renderClaimEvidenceCheckedSection([
     }
   ])}
 
-Helper scripts:
-${helperScripts.map((helperScript) => `- ${helperScript}`).join("\n")}
-
 Notes:
 - Documented routing and behavior from route handlers and tests.`;
 };
@@ -2804,7 +2846,7 @@ ${renderLaneClassificationRuleBlock(config)}
 - may write canonical truth docs and ${config.truthmark.paths.routesIndex} or relevant child route files only
 - must not write functional code
 - when routing is missing, stale, broad, overloaded, catch-all, or cannot map the behavior to a bounded truth owner, run Truth Structure first when routing repair is safe and in scope
-- block and recommend Truth Structure when routing repair is unsafe, ambiguous, or outside the task boundary
+- stop and recommend Truth Structure when routing repair is unsafe, ambiguous, or outside the task boundary
 - keep feature README.md files as indexes rather than truth-document targets
 - create or update bounded leaf truth docs when behavior does not fit an existing leaf doc
 - write product capability/boundary truth under ${config.truthmark.paths.productTruthRoot} when documenting product promise, boundary, rationale, or user/stakeholder value
@@ -2815,7 +2857,7 @@ ${renderLaneClassificationRuleBlock(config)}
 - preserve unrelated authored content
 ${renderTruthDocOwnershipGateSection(
     "the implemented behavior and candidate truth docs",
-    "if the target doc is broad, mixed-owner, index-like, or the documented behavior spans independent owners, run Truth Structure first when safe and in scope; otherwise block and recommend Truth Structure"
+    "if the target doc is broad, mixed-owner, index-like, or the documented behavior spans independent owners, run Truth Structure first when safe and in scope; otherwise stop and recommend Truth Structure"
   )}
 ${TRUTH_DOC_DECISION_RATIONALE_PRESERVATION_INSTRUCTIONS}
 ${renderRouteFirstEvidenceGateSection(
@@ -2824,27 +2866,26 @@ ${renderRouteFirstEvidenceGateSection(
   )}
 ${subagentMode}${REPOSITORY_INTELLIGENCE_INSTRUCTIONS}
 ${FEATURE_DOC_TEMPLATE_INSTRUCTIONS}
+${TRUTH_DOC_AUTHORING_STYLE_INSTRUCTIONS}
 ${renderTruthDocRestructureGateSection(
     "Truth Document may restructure only truth docs for the implemented behavior being documented."
   )}
 ${ARCHITECTURE_DOC_BOUNDARY_INSTRUCTIONS}
 ${renderHierarchySummary(config)}
 ${DECISION_TRUTH_INSTRUCTIONS}
-Helper status reporting:
-- Validate the report body before adding this validator's own success status; the body may omit \`validate-document-report\` while validation is pending.
-- After \`truthmark validate document-report <report-file> --json\` returns \`data.validation.ok: true\`, append or update \`validate-document-report: ran, passed\` in the final report.
-- If the installed Truthmark CLI is unavailable or the helper is skipped, record \`validate-document-report: skipped, <reason>\` and manually validate the report shape.
-- Record \`validate-write-lease: ran, passed\` only after validating a concrete write lease; otherwise use a truthful skipped status such as \`skipped, no write lease used\`.
-- Helper output is derived evidence and never replaces direct checkout inspection, evidence review, or parent acceptance.
+Optional validation: when local tooling is available, you may validate the final report with \`truthmark validate document-report <report-file> --json\`; direct checkout inspection and evidence review remain authoritative.
 Parent post-document verification:
 - verify only truth docs and leased truth routing files changed during document work
-- block on functional code, generated host surfaces, or unrelated diffs caused by document work
-- for each write lease, validate the worker report against the actual worker diff, allowedWrites, forbiddenWrites, identity fields, filesChanged, offLeaseChanges, blockers, and required report fields before accepting it
-- verify the final report records ownership review, structure requirement, restructure, routing update, or blocked reason when applicable`;
+- stop on functional code, generated host surfaces, or unrelated diffs caused by document work
+- for each write lease, validate the worker report against the actual worker diff, allowedWrites, forbiddenWrites, identity fields, filesChanged, offLeaseChanges, blockers, and expected report fields before accepting it
+- verify the final report records ownership review, structure requirement, restructure, routing update, or manual handoff reason when applicable`;
 };
 
 // src/agents/truth-preview.ts
-var TRUTH_PREVIEW_EXPLICIT_INVOCATIONS = "OpenCode /skill truthmark-preview; Codex /truthmark-preview or $truthmark-preview; Claude Code /truthmark-preview; GitHub Copilot /truthmark-preview; Gemini CLI /truthmark:preview.";
+var TRUTH_PREVIEW_EXPLICIT_INVOCATIONS = {
+  copilot: "GitHub Copilot /truthmark-preview.",
+  gemini: "Gemini CLI /truthmark:preview."
+};
 var renderTruthPreviewReportExample = (config = defaultAgentConfig()) => {
   return `Truth Preview: completed
 
@@ -2877,21 +2918,34 @@ Suggested subagent use:
 - write workers: none in Preview
 - leases needed: none in Preview
 
-Blocking ambiguity:
+Manual handoff questions:
 - none identified in preview
 
 Handoff:
 - Run the selected Truthmark workflow after user approval.`;
 };
-var renderTruthPreviewProcedureBody = (config = defaultAgentConfig()) => {
-  return `Use this skill only when the user explicitly asks to preview Truthmark routing or workflow choice before edits.
+var renderTruthPreviewAdapterReportFields = () => {
+  return `Return a concise Truth Preview report with these fields:
+- requested outcome
+- likely workflow
+- why this workflow
+- likely route owner and lane impact
+- expected write classes
+- expected target files
+- suggested subagent use
+- manual handoff questions
+- handoff recommendation`;
+};
+var renderTruthPreviewProcedureBody = (config = defaultAgentConfig(), host) => {
+  const invocationLine = host === void 0 ? "" : `Invocations: ${TRUTH_PREVIEW_EXPLICIT_INVOCATIONS[host]}
 
-Invocations: ${TRUTH_PREVIEW_EXPLICIT_INVOCATIONS}
+`;
+  return `Use this skill only when the user explicitly asks to preview Truthmark routing or workflow choice before edits.
 
-Truth Preview is read-only. Its report is intended, not authorized.
+${invocationLine}Truth Preview is read-only. Its report is intended, not authorized.
 
 Purpose:
-- preview the likely Truthmark workflow, route owner, target files, expected write classes, suggested subagent use, and blocking ambiguity before edits happen
+- preview the likely Truthmark workflow, route owner, target files, expected write classes, suggested subagent use, and manual handoff questions before edits happen
 - report likely product lane impact, engineering lane impact, target docs, and ambiguity before edits
 - hand off to the selected workflow after user approval
 - keep the selector thin so agents can avoid loading or acting through heavier workflows prematurely
@@ -2931,7 +2985,7 @@ var renderTruthmarkPortalProcedureBody = (config = defaultAgentConfig()) => {
   const template = config.truthmark.paths.portalTemplate;
   return `# Truthmark Portal
 
-Truthmark Portal is a manual-only presentation workflow. It is never a completion gate, never Truth Sync, and runs only when the user explicitly asks to generate, refresh, or update the committed static HTML Portal.
+Truthmark Portal is a manual-only presentation workflow. It is never an automatic completion workflow, never Truth Sync, and runs only when the user explicitly asks to generate, refresh, or update the committed static HTML Portal.
 
 Invocations: ${TRUTHMARK_PORTAL_EXPLICIT_INVOCATIONS}
 
@@ -3029,22 +3083,22 @@ ${renderLaneClassificationRuleBlock(config)}
 - inspect the configured root route index at ${config.truthmark.paths.routesIndex} and relevant child route files under ${config.truthmark.paths.routeAreasRoot}/ when they exist
 - define areas by product or behavior ownership, not by mechanical directory mirroring
 - create or repair ${config.truthmark.paths.routesIndex}
-- create starter truth docs when useful and when they belong in the canonical current-truth surface
+- create skeletal starter truth docs only when missing ownership would otherwise block future workflows
 - Starter truth docs must use closed YAML frontmatter bounded by opening and closing --- lines; include status, truth_kind, and last_reviewed inside that frontmatter. Put source references in the final ## Source References section, not in frontmatter.
-- Starter truth docs must use lane-specific templates and keep product and engineering truth in separate files.
+- Starter truth docs are ownership anchors, not behavior writeups: include only the title, bounded area/scope, and Source References needed to make routing explicit.
+- Starter truth docs must keep product and engineering truth in separate files; leave substantive behavior, contract, architecture, workflow, operations, or test prose to Truth Document.
 ${subagentMode}
-${FEATURE_DOC_TEMPLATE_INSTRUCTIONS}
 - use ${productTruthRoot}/** for product truth destinations
 - use ${engineeringTruthRoot}/** for engineering truth destinations
 - use only canonical current-truth destinations for starter truth docs
-- keep active Product Decisions in product truth and Engineering Decisions in engineering truth
+- keep Product Decisions in product truth and Engineering Decisions in engineering truth when selecting destinations; report any relocation need instead of rewriting decision prose during topology review
 - preserve unrelated authored content
 ## New area setup
 Use when a user asks to onboard a new code area into Truthmark, a new package, controller, domain, or product area lacks bounded truth ownership, or a new product area needs routing and starter truth docs.
 Do:
 - inspect the named code area
 - infer bounded product or behavior ownership
-- choose the owning route when ownership is clear; otherwise propose the route and block for review
+- choose the owning route when ownership is clear; otherwise propose the route and stop for manual review
 - create or update the child route entry or file
 - create starter truth docs only where current truth is missing
 - report the initial truth boundary
@@ -3057,12 +3111,11 @@ Do not:
 ## Topology Governance
 Truth Structure owns documentation topology, lane splits, decision relocation, and relationship repair. Do not depend on humans to manually organize ${productTruthRoot} or ${engineeringTruthRoot}. Treat both configured lane roots as managed semantic roots.
 Inspect controllers, routes, handlers, services, packages, tests, existing truth docs, and route files; infer product and domain ownership from behavior boundaries, not from mechanical directory mirroring.
-When topology pressure exists, repair structure before creating or extending truth docs.
+When topology pressure exists, repair route structure before creating or extending truth ownership anchors.
 ${renderTruthDocOwnershipGateSection(
     "candidate route owners and current truth docs",
-    "if a truth doc mixes independent owners, route ownership is broad, or a split is required for bounded ownership, split and reroute into bounded truth docs when safe; otherwise block with manual-review files"
+    "if a truth doc mixes independent owners, route ownership is broad, or a split is required for bounded ownership, split or reroute only the ownership topology when safe; otherwise stop with manual-review files"
   )}
-${TRUTH_DOC_DECISION_RATIONALE_PRESERVATION_INSTRUCTIONS}
 Topology pressure signals:
 - one area maps broad code such as src/**, app/**, server/**, services/**, or packages/**
 - one area maps multiple unrelated controllers, route groups, services, or bounded contexts
@@ -3078,10 +3131,10 @@ Use these review thresholds as guidance:
 - more than 5 controllers mapped through one catch-all area
 Repair rules:
 - split broad, overloaded, or catch-all areas into behavior-owned child route files
-- split mixed-owner truth docs into bounded owner docs before adding new behavior claims
+- split or flag mixed-owner truth docs for bounded owners before any workflow adds new behavior claims
 - create route files under ${config.truthmark.paths.routeAreasRoot}/ when a product/domain boundary is clear
-- create engineering behavior truth docs under ${engineeringTruthRoot} only when behavior lacks a current doc
-- create product truth docs under ${productTruthRoot} only when product promise, boundary, rationale, or user-visible capability truth is in scope
+- create skeletal engineering ownership anchors under ${engineeringTruthRoot} only when behavior lacks a current owner
+- create skeletal product ownership anchors under ${productTruthRoot} only when product promise, boundary, rationale, or user-visible capability ownership is in scope
 - README.md files are indexes, not Truth Sync targets
 - prefer bounded product docs under product/capabilities or product/decisions and engineering docs under engineering/<kind>/<surface>.md
 - keep behavior truth docs behavior-oriented, not endpoint-oriented
@@ -3089,13 +3142,9 @@ Repair rules:
 - update routing so future Truth Sync can target small docs
 - preserve existing authored docs; move or rewrite only when needed to remove ambiguity
 - report Truth docs split when one broad or mixed-owner truth doc becomes multiple bounded docs
-${renderTruthDocRestructureGateSection(
-    "Truth Structure may restructure broader routed docs when topology, ownership, or doc-shape repair is already in scope."
-  )}
 ${renderTopologyEvidenceGateSection()}
-${ARCHITECTURE_DOC_BOUNDARY_INSTRUCTIONS}
 - Do not finish topology repair with mixed product/engineering authority in a single canonical truth doc.
-- If an existing canonical doc has wrong-lane sections, split or move them into the correct product or engineering lane.
+- If an existing canonical doc has wrong-lane sections, report the lane repair needed and only move content when the topology split explicitly requires it.
 Portable fallback:
 - If this skill surface is unavailable, perform the same workflow directly from committed repository files.
 - Do not require the truthmark CLI.
@@ -3134,6 +3183,60 @@ var parseOptionalBulletSection = (source, title) => {
   }
   return parseBulletLines(section);
 };
+var parseRequiredBulletSection = (source, title) => {
+  const section = findSection(source, title);
+  if (!section) {
+    throw new Error(`${title} section is required.`);
+  }
+  const entries = parseBulletLines(section);
+  if (entries.length === 0) {
+    throw new Error(`${title} must include at least one bullet.`);
+  }
+  return entries;
+};
+var formatIntentValues = (values) => values.join(" / ");
+var renderSyncIntentSection = (intent) => {
+  return [
+    "Sync Intent:",
+    `- Changed code reviewed: ${formatIntentValues(intent.changedCodeReviewed)}`,
+    `- Affected route/truth owner: ${formatIntentValues(intent.affectedRouteOrTruthOwner)}`,
+    `- Target truth docs: ${formatIntentValues(intent.targetTruthDocs)}`,
+    `- Intended update: ${formatIntentValues(intent.intendedUpdate)}`,
+    `- Evidence to verify: ${formatIntentValues(intent.evidenceToVerify)}`,
+    `- User-provided decisions/rationale: ${formatIntentValues(intent.userProvidedDecisionRationale)}`,
+    `- No-update-needed rationale: ${formatIntentValues(intent.noUpdateNeededRationale)}`,
+    `- Blockers: ${formatIntentValues(intent.blockers)}`
+  ].join("\n");
+};
+var parseIntentValues = (value) => {
+  return value.split(" / ").map((item) => item.trim()).filter(hasContent);
+};
+var parseSyncIntentSection = (source) => {
+  const entries = parseOptionalBulletSection(source, "Sync Intent");
+  if (entries === void 0) {
+    return void 0;
+  }
+  const values = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    const separator = entry.indexOf(":");
+    if (separator === -1) {
+      continue;
+    }
+    values.set(entry.slice(0, separator), entry.slice(separator + 1).trim());
+  }
+  return {
+    changedCodeReviewed: parseIntentValues(values.get("Changed code reviewed") ?? ""),
+    affectedRouteOrTruthOwner: parseIntentValues(values.get("Affected route/truth owner") ?? ""),
+    targetTruthDocs: parseIntentValues(values.get("Target truth docs") ?? ""),
+    intendedUpdate: parseIntentValues(values.get("Intended update") ?? ""),
+    evidenceToVerify: parseIntentValues(values.get("Evidence to verify") ?? ""),
+    userProvidedDecisionRationale: parseIntentValues(
+      values.get("User-provided decisions/rationale") ?? ""
+    ),
+    noUpdateNeededRationale: parseIntentValues(values.get("No-update-needed rationale") ?? ""),
+    blockers: parseIntentValues(values.get("Blockers") ?? "")
+  };
+};
 var isClaimEvidenceResult = (value) => {
   return ["supported", "narrowed", "removed", "blocked"].includes(value);
 };
@@ -3176,8 +3279,13 @@ var renderTruthSyncCompletedReport = (input) => {
   return [
     "Truth Sync: completed",
     renderBulletSection("Changed code reviewed", input.changedCode),
+    ...input.syncIntent === void 0 ? [] : [renderSyncIntentSection(input.syncIntent)],
     renderBulletSection("Ownership reviewed", input.ownershipReviewed),
     renderBulletSection("Truth docs updated", input.truthDocsUpdated),
+    renderBulletSection(
+      "Decision/rationale captured",
+      input.decisionRationaleCaptured ?? ["none provided in task conversation"]
+    ),
     renderClaimEvidenceCheckedSection(input.evidenceChecked),
     ...input.helperScripts === void 0 ? [] : [renderBulletSection("Helper scripts", input.helperScripts)],
     renderBulletSection("Notes", input.notes)
@@ -3188,11 +3296,17 @@ var parseTruthSyncReport = (source) => {
     throw new Error("Only completed Truth Sync reports can be parsed.");
   }
   const helperScripts = parseOptionalBulletSection(source, "Helper scripts");
+  const syncIntent = parseSyncIntentSection(source);
   return {
     status: "completed",
     changedCode: parseBulletSection(source, "Changed code reviewed"),
+    ...syncIntent === void 0 ? {} : { syncIntent },
     ownershipReviewed: parseBulletSection(source, "Ownership reviewed"),
     truthDocsUpdated: parseBulletSection(source, "Truth docs updated"),
+    decisionRationaleCaptured: parseRequiredBulletSection(
+      source,
+      "Decision/rationale captured"
+    ),
     evidenceChecked: parseEvidenceCheckedSection(source),
     ...helperScripts === void 0 ? {} : { helperScripts },
     notes: parseBulletSection(source, "Notes")
@@ -3216,6 +3330,17 @@ var renderTruthSyncBlockedReport = (input) => {
 
 // src/agents/truth-sync.ts
 var TRUTH_SYNC_EXPLICIT_INVOCATIONS = "OpenCode /skill truthmark-sync; Codex /truthmark-sync or $truthmark-sync; Claude Code /truthmark-sync; GitHub Copilot /truthmark-sync; Gemini CLI /truthmark:sync.";
+var renderTruthSyncProductDecisionRuleBlock = (config) => {
+  return renderBulletBlock(
+    [
+      "ask whether a user-visible promise, capability boundary, API contract, acceptance criterion, or explicit user/product evidence changed",
+      `if yes, update or route product truth under ${config.truthmark.paths.productTruthRoot} as well as engineering truth under ${config.truthmark.paths.engineeringTruthRoot}`,
+      `if no, default to engineering truth under ${config.truthmark.paths.engineeringTruthRoot} for internal implementation changes`,
+      "when both lanes change, keep separate product and engineering docs cross-linked through route YAML with realized_by and realizes",
+      "when ownership is ambiguous, stop or route to Truth Structure instead of writing a mixed document"
+    ].join("\n")
+  );
+};
 var renderTruthSyncProcedureBody = (config = defaultAgentConfig(), options = {}) => {
   const workflow = getTruthmarkWorkflow("truthmark-sync");
   const claudeSubagentMode = options.includeClaudeSubagentMode ? `${renderClaudeSubagentModeSection(
@@ -3245,7 +3370,7 @@ var renderTruthSyncProcedureBody = (config = defaultAgentConfig(), options = {})
   const subagentMode = `${claudeSubagentMode}${codexSubagentMode}${copilotCustomAgentMode}${openCodeSubagentMode}`;
   return `Use this skill automatically before finishing when functional code changed since the last successful Truth Sync. Also run it immediately when the user explicitly invokes Truth Sync.
 Invocations: ${TRUTH_SYNC_EXPLICIT_INVOCATIONS}
-Explicit invocation runs immediately. Later functional-code changes reopen the finish-time requirement, and an earlier explicit run satisfies the finish gate only if no later functional-code changes occur.
+Explicit invocation runs immediately. Later functional-code changes need a fresh finish-time review, and an earlier explicit run satisfies the finish-time review only if no later functional-code changes occur.
 Skip when changes are documentation-only, formatting-only, clearly behavior-preserving renames with no truth impact, when no Truthmark config exists yet, or when there are no functional code changes.
 Parent workflow:
 1. Inspect git status, staged changes, unstaged changes, and untracked files directly.
@@ -3253,58 +3378,47 @@ Parent workflow:
 3. Identify functional-code changes and the nearest truth docs or routing repairs.
 4. Evidence authority:
 ${renderBulletBlock(EVIDENCE_AUTHORITY_INSTRUCTIONS)}
-5. Lane classification gate:
-${renderLaneClassificationRuleBlock(config)}
-6. Update engineering truth first after code changes. Update product truth only when implemented user-visible product promise or capability boundary changed and explicit source/user evidence supports it; otherwise report product-lane review needed.
-7. Code verification is parent-owned: follow repository instructions and task context, and report what ran or why it did not run.
-8. Dispatch bounded Truth Sync workers only when the host supports subagent dispatch and the acting agent chooses that path; otherwise execute the same sync task inline.
-${subagentMode}Topology quality gate:
+5. Product truth decision:
+${renderTruthSyncProductDecisionRuleBlock(config)}
+6. Capture decision context from the task conversation: ask whether the user provided a product or technical decision, rationale, constraint, tradeoff, rejection reason, or scope boundary. Preserve concise user-provided decision rationale in Sync Intent before truth edits, route it to Product Decisions, Engineering Decisions, Rationale, Capability Scope, Non-Goals, Maintenance Notes, or the relevant workflow/contract section, and report whether it was placed, skipped because none was provided, or needs manual handoff.
+7. Update engineering truth first after code changes. Product truth is opt-in for externally visible promises, product boundaries, APIs, acceptance criteria, or explicit user/product evidence.
+8. Code verification is parent-owned: follow repository instructions and task context, and report what ran or why it did not run.
+9. Dispatch bounded Truth Sync workers only when the host supports subagent dispatch and the acting agent chooses that path; otherwise execute the same sync task inline.
+10. Fill Sync Intent before editing truth docs or truth routing files:
+   - Changed code reviewed: functional files, tests, configs, generated outputs, or other implementation evidence inspected
+   - Affected route/truth owner: bounded route area or canonical truth owner that maps the change
+   - Target truth docs: docs expected to change, or docs reviewed and left unchanged
+   - Intended update: claim/doc/routing update planned before writing
+   - Evidence to verify: checkout evidence that will support, narrow, remove, or record each claim for manual handoff
+   - User-provided decisions/rationale: decisions, rationale, constraints, tradeoffs, rejection reasons, or scope boundaries from the current task conversation, or "none provided"
+   - No-update-needed rationale: why mapped truth is already current when no truth doc should change
+   - Blockers: missing routing, ambiguous ownership, failed verification, unavailable evidence, or off-boundary write needs
+11. Only edit allowed truth docs/routes after Sync Intent is clear; if ownership is ambiguous, repair topology first when the repair is safe and in scope, otherwise stop and recommend Truth Structure instead of guessing.
+${subagentMode}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, do not create another generic truth doc
-- run Truth Structure before syncing when topology repair is safe and in scope
-- block and recommend Truth Structure when topology repair is unsafe, ambiguous, or outside the current task boundary
-- report the route files and changed code paths that require structure repair
+- if routing is missing, stale, broad, overloaded, catch-all route only, or cannot map changed code to a bounded truth owner, run Truth Structure before syncing when topology repair is safe and in scope
+- safe in-scope topology repair may update truth routing files and create or update bounded leaf truth docs needed to map the changed functional code; keep the repair limited to the affected route owner
+- stop and recommend Truth Structure only when topology repair is unsafe, ambiguous, or outside the current task boundary
+- report the route files and changed code paths that required structure repair
+- do not create another generic truth doc
 - README.md files are indexes, not Truth Sync targets
 - must not append behavior details to a README.md index
-- create or update a bounded leaf truth doc when behavior changes do not fit an existing leaf doc
 - write engineering truth under ${config.truthmark.paths.engineeringTruthRoot}; product truth updates under ${config.truthmark.paths.productTruthRoot} are allowed only for explicit current product behavior changes
-${renderTruthDocOwnershipGateSection(
-    "changed functional files and impacted truth docs",
-    "if an impacted doc is broad, mixed-owner, index-like, or the update spans independent behavior owners, run Truth Structure before syncing when safe and in scope; otherwise block and recommend Truth Structure"
-  )}
-${TRUTH_DOC_DECISION_RATIONALE_PRESERVATION_INSTRUCTIONS}
-${FEATURE_DOC_TEMPLATE_INSTRUCTIONS}
-${renderTruthDocRestructureGateSection(
-    "Truth Sync may restructure leased canonical truth docs when the current sync evidence shows repository truth is stale, even when the doc is outside the initially affected route focus."
-  )}
-${ARCHITECTURE_DOC_BOUNDARY_INSTRUCTIONS}
-${renderRouteFirstEvidenceGateSection(
-    "changed functional files",
-    "if no impacted doc changed, report why truth was already current or why sync was skipped"
-  )}
-${REPOSITORY_INTELLIGENCE_INSTRUCTIONS}
 Optional validation tooling:
 - you may run truthmark check when local tooling is available
+- you may validate the final report with \`truthmark validate sync-report <report-file> --json\` when available
 - do not require the truthmark binary; direct checkout inspection is the canonical path
 - optional validation must not replace agent judgment about docs and routing
 - update Product Decisions only in product truth and Engineering Decisions only in engineering truth when evidence supports the lane-specific decision change
-Helper status reporting:
-- Validate the report body before adding this validator's own success status; the body may omit \`validate-sync-report\` while validation is pending.
-- After \`truthmark validate sync-report <report-file> --json\` returns \`data.validation.ok: true\`, append or update \`validate-sync-report: ran, passed\` in the final report.
-- If the installed Truthmark CLI is unavailable or the helper is skipped, record \`validate-sync-report: skipped, <reason>\` and manually validate the report shape.
-- Record \`validate-write-lease: ran, passed\` only after validating a concrete write lease; otherwise use a truthful skipped status such as \`skipped, no write lease used\`.
-- Helper output is derived evidence and never replaces direct checkout inspection, evidence review, or parent acceptance.
 ${renderHierarchySummary(config)}
-${DECISION_TRUTH_INSTRUCTIONS}
 Parent post-sync verification:
 - verify only truth docs and leased truth routing files changed during sync
-- block on any unrelated diff caused by the sync step
-- block if functional code changed during sync
-- for each write lease, validate the worker report against the actual worker diff, allowedWrites, forbiddenWrites, identity fields, filesChanged, offLeaseChanges, blockers, and required report fields before accepting it
+- stop on any unrelated diff caused by the sync step
+- stop if functional code changed during sync
 - validate the final report against the structured Truth Sync report contract, including Claim, indented Evidence, and Result values supported, narrowed, removed, or blocked under Evidence checked
 - verify the updated docs correspond to reviewed checkout evidence, changed-code impact, or a recorded stale-truth correction made within the sync write lease
-- verify the final report records ownership review, structure requirement, split, restructure, or blocked reason when the ownership gate fired
-- blocked outcomes must preserve the working tree as-is: no rollback, no post-block cleanup edits, and manual-review reporting of any remaining files`;
+- verify the final report records ownership review, structure requirement, split, restructure, or manual handoff reason when the ownership review applies
+- manual handoff outcomes must preserve the working tree as-is: no rollback, no post-block cleanup edits, and manual-review reporting of any remaining files`;
 };
 
 // src/agents/write-lease.ts
@@ -3334,8 +3448,6 @@ var TRUTHMARK_REALIZE_SKILL_PATH = ".agents/skills/truthmark-realize/SKILL.md";
 var TRUTHMARK_REALIZE_SKILL_METADATA_PATH = ".agents/skills/truthmark-realize/agents/openai.yaml";
 var TRUTHMARK_CHECK_SKILL_PATH = ".agents/skills/truthmark-check/SKILL.md";
 var TRUTHMARK_CHECK_SKILL_METADATA_PATH = ".agents/skills/truthmark-check/agents/openai.yaml";
-var TRUTHMARK_PREVIEW_SKILL_PATH = ".agents/skills/truthmark-preview/SKILL.md";
-var TRUTHMARK_PREVIEW_SKILL_METADATA_PATH = ".agents/skills/truthmark-preview/agents/openai.yaml";
 var TRUTHMARK_PORTAL_SKILL_PATH = ".agents/skills/truthmark-portal/SKILL.md";
 var TRUTHMARK_PORTAL_SKILL_METADATA_PATH = ".agents/skills/truthmark-portal/agents/openai.yaml";
 var TRUTHMARK_ROUTE_AUDITOR_AGENT_PATH = ".codex/agents/truth-route-auditor.toml";
@@ -3394,12 +3506,10 @@ var workflowSupportFiles = (workflowId) => {
   const workflow = getTruthmarkWorkflow(workflowId);
   const definition = WORKFLOW_PACKAGE_DEFINITIONS[workflowId];
   const hasSubagentSupport = definition.parentRule !== void 0 && ((workflow.subagents?.length ?? 0) > 0 || (workflow.writeSubagents?.length ?? 0) > 0);
-  const hasHelperSupport = (workflow.helpers?.length ?? 0) > 0;
   return [
     "support/procedure.md",
     "support/report-template.md",
-    ...hasSubagentSupport ? ["support/subagents-and-leases.md"] : [],
-    ...hasHelperSupport ? ["helper-manifest.yml", "support/helper-policy.md"] : []
+    ...hasSubagentSupport ? ["support/subagents-and-leases.md"] : []
   ];
 };
 var renderWorkflowCommandAdapterInstructions = (workflowId, root, hostName, surfaceKind) => {
@@ -3474,7 +3584,7 @@ var WORKFLOW_PACKAGE_DEFINITIONS = {
   "truthmark-preview": {
     title: "Truthmark Preview",
     argumentHint: "Optional requested outcome, code area, doc path, or routing question",
-    invocations: TRUTH_PREVIEW_EXPLICIT_INVOCATIONS,
+    invocations: TRUTH_PREVIEW_EXPLICIT_INVOCATIONS.copilot,
     use: () => "Use this skill only when the user explicitly asks to preview Truthmark routing or workflow choice before edits.",
     quickRules: (config) => [
       "Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists.",
@@ -3522,7 +3632,7 @@ var WORKFLOW_PACKAGE_DEFINITIONS = {
     use: () => "Use this skill only when the user explicitly asks to generate or refresh the committed static HTML Truthmark Portal.",
     quickRules: (config) => [
       "Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists.",
-      "Truthmark Portal is manual-only; never run it as a completion gate and never treat it as Truth Sync.",
+      "Truthmark Portal is manual-only; never run it automatically at completion and never treat it as Truth Sync.",
       "Markdown remains canonical; generated HTML is non-canonical presentation only.",
       "Read Markdown directly; the workflow does not require the truthmark CLI or package.",
       "Generate committed, generated non-canonical static files for humans.",
@@ -3556,8 +3666,27 @@ ${renderMarkdownExample(
 ${renderMarkdownExample(
         renderTruthSyncCompletedReport({
           changedCode: ["src/auth/session.ts"],
+          syncIntent: {
+            changedCodeReviewed: ["src/auth/session.ts"],
+            affectedRouteOrTruthOwner: [config.truthmark.paths.routesIndex],
+            targetTruthDocs: [
+              `${engineeringTruthRoot}/repository/bootstrap-routing.md`
+            ],
+            intendedUpdate: ["Update session timeout behavior."],
+            evidenceToVerify: [
+              "src/auth/session.ts:12",
+              `${config.truthmark.paths.routesIndex}:11`
+            ],
+            userProvidedDecisionRationale: [
+              "User rationale: session timeout behavior changed for internal implementation consistency"
+            ],
+            noUpdateNeededRationale: ["not applicable; mapped truth is stale"],
+            blockers: ["none"]
+          },
           ownershipReviewed: [config.truthmark.paths.routesIndex],
-          truthDocsUpdated: [`${engineeringTruthRoot}/repository/overview.md`],
+          truthDocsUpdated: [
+            `${engineeringTruthRoot}/repository/bootstrap-routing.md`
+          ],
           evidenceChecked: [
             {
               claim: "Session timeout behavior is documented in the mapped repository truth doc.",
@@ -3568,8 +3697,8 @@ ${renderMarkdownExample(
               result: "supported"
             }
           ],
-          helperScripts: [
-            "validate-write-lease: skipped, no write lease used"
+          decisionRationaleCaptured: [
+            "Placed user rationale in the mapped engineering truth doc under Engineering Decisions/Rationale."
           ],
           notes: ["Updated session timeout behavior."]
         })
@@ -3643,61 +3772,11 @@ var renderWorkflowSupportParts = (workflowId, config) => {
 var renderSkillSupportFile = (title, body) => {
   return `# ${title}
 
-Generated by Truthmark ${TRUTHMARK_VERSION}. Rerun truthmark init after upgrades.
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
 
 ${body}
 `;
 };
-var renderHelperManifest = (helpers) => {
-  const manifest = {
-    helpers: Object.fromEntries(
-      helpers.map((helper) => [
-        helper.id,
-        {
-          optional: helper.optional,
-          runner: helper.runner,
-          command: helper.command,
-          inputs: helper.inputs,
-          output: helper.output,
-          writes: helper.writes,
-          ...helper.allowedWrites === void 0 ? {} : { allowedWrites: helper.allowedWrites },
-          fallback: helper.fallback
-        }
-      ])
-    )
-  };
-  return [
-    `# Generated by Truthmark ${TRUTHMARK_VERSION}. Rerun truthmark init after upgrades.`,
-    stringify2(manifest, { lineWidth: 0 })
-  ].join("\n");
-};
-var renderHelperPolicySupport = (helpers) => {
-  const reportHelperId = helpers.find((helper) => helper.id.endsWith("-report"))?.id ?? helpers[0]?.id;
-  const helperLines = helpers.map(
-    (helper) => `- ${helper.id}: optional ${helper.runner}; manual fallback: ${helper.fallback}`
-  ).join("\n");
-  return renderSkillSupportFile(
-    "Optional Helper CLI Policy",
-    `Optional helper CLI commands may collect deterministic checkout facts or validate artifacts. If the Truthmark CLI is unavailable or too old for a declared helper, continue manually using this procedure and report which helper was skipped. Helper output is derived evidence; it does not override direct checkout inspection, workflow write boundaries, or parent acceptance.
-
-Runner detection:
-- Check the declared Truthmark CLI runner before invoking a helper.
-- Invoke helpers through the installed \`truthmark validate ... --json\` CLI command using argv-style arguments from helper-manifest.yml.
-- If unavailable or version-mismatched, treat the helper as skipped and use the manual fallback.
-- Do not fail the workflow solely because a helper cannot run.
-
-Available helpers:
-${helperLines}
-
-Final reports should include helper status when helpers are declared for this workflow:
-
-\`\`\`md
-Helper scripts:
-- ${reportHelperId}: ran, passed
-- validate-write-lease: skipped, no write lease used
-\`\`\``
-  );
-};
 var renderWorkflowProcedure = (workflowId, config) => {
   switch (workflowId) {
     case "truthmark-structure":
@@ -3721,7 +3800,7 @@ var renderWorkflowEntrypoint = (workflowId, config, supportFiles, host) => {
   const definition = WORKFLOW_PACKAGE_DEFINITIONS[workflowId];
   const supportFileUsage = (supportFile) => {
     if (supportFile === "support/procedure.md") {
-      return "read before edits or detailed auditing; contains core quality gates";
+      return "read before edits or detailed auditing; contains core review questions";
     }
     if (supportFile === "support/report-template.md") {
       return "read before the final report";
@@ -3729,12 +3808,6 @@ var renderWorkflowEntrypoint = (workflowId, config, supportFiles, host) => {
     if (supportFile === "support/subagents-and-leases.md") {
       return "read only when using subagents, leases, or accepting worker output";
     }
-    if (supportFile === "support/helper-policy.md") {
-      return "read only when invoking helper validators or reporting helper status";
-    }
-    if (supportFile === "helper-manifest.yml") {
-      return "read only when invoking helper validators or validating helper registration";
-    }
     return "available when relevant to the current step";
   };
   const supportFileList = supportFiles.map((supportFile) => `- ${supportFile} \u2014 ${supportFileUsage(supportFile)}`).join("\n");
@@ -3744,7 +3817,6 @@ name: ${workflowId}
 description: ${workflow.description}
 argument-hint: ${definition.argumentHint}
 user-invocable: true
-truthmark-version: ${TRUTHMARK_VERSION}
 ---
 
 # ${definition.title}
@@ -3819,7 +3891,6 @@ var renderTruthmarkSkillPackage = ({
     config
   );
   const subagents = renderWorkflowSubagentSupport(workflowId, host);
-  const helpers = getTruthmarkWorkflow(workflowId).helpers ?? [];
   const supportFiles = workflowSupportFiles(workflowId);
   const definition = WORKFLOW_PACKAGE_DEFINITIONS[workflowId];
   const files = [
@@ -3851,18 +3922,6 @@ var renderTruthmarkSkillPackage = ({
       )
     });
   }
-  if (helpers.length > 0) {
-    files.push(
-      {
-        path: `${skillDirectory}/helper-manifest.yml`,
-        content: renderHelperManifest(helpers)
-      },
-      {
-        path: `${supportDirectory}/helper-policy.md`,
-        content: renderHelperPolicySupport(helpers)
-      }
-    );
-  }
   return files;
 };
 var normalizeOpenCodePermissionPath = (path12) => {
@@ -3972,7 +4031,7 @@ var renderCodexReadOnlyAgent = ({
   nicknameCandidates,
   developerInstructions
 }) => {
-  return `# Generated by Truthmark ${TRUTHMARK_VERSION}. Rerun truthmark init after upgrades.
+  return `# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
 name = ${renderTomlString(name)}
 description = ${renderTomlString(description)}
 sandbox_mode = "read-only"
@@ -3988,7 +4047,7 @@ var renderCodexWriteAgent = ({
   nicknameCandidates,
   developerInstructions
 }) => {
-  return `# Generated by Truthmark ${TRUTHMARK_VERSION}. Rerun truthmark init after upgrades.
+  return `# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
 name = ${renderTomlString(name)}
 description = ${renderTomlString(description)}
 sandbox_mode = "workspace-write"
@@ -4010,7 +4069,7 @@ description: ${description}
 tools: [read, search]
 ---
 
-# Generated by Truthmark ${TRUTHMARK_VERSION}. Rerun truthmark init after upgrades.
+# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
 
 ${agentInstructions}
 `;
@@ -4026,7 +4085,7 @@ description: ${description}
 tools: [read, search, edit]
 ---
 
-# Generated by Truthmark ${TRUTHMARK_VERSION}. Rerun truthmark init after upgrades.
+# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
 
 ${instructions}
 `;
@@ -4044,7 +4103,7 @@ kind: local
 tools: [read_file, grep_search]
 ---
 
-# Generated by Truthmark ${TRUTHMARK_VERSION}. Rerun truthmark init after upgrades.
+# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
 
 Manual invocation: @${copilotName}
 
@@ -4063,7 +4122,7 @@ kind: local
 tools: [read_file, grep_search, write_file]
 ---
 
-# Generated by Truthmark ${TRUTHMARK_VERSION}. Rerun truthmark init after upgrades.
+# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
 
 Manual invocation: @${copilotName} with an explicit parent write lease.
 
@@ -4082,7 +4141,7 @@ description: ${description}
 tools: Read, Grep, Glob, LS
 ---
 
-# Generated by Truthmark ${TRUTHMARK_VERSION}. Rerun truthmark init after upgrades.
+# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
 
 Manual invocation: use the ${copilotName} subagent.
 
@@ -4100,7 +4159,7 @@ description: ${description}
 tools: Read, Grep, Glob, LS, Edit, MultiEdit
 ---
 
-# Generated by Truthmark ${TRUTHMARK_VERSION}. Rerun truthmark init after upgrades.
+# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
 
 Manual invocation: use the ${copilotName} subagent with an explicit parent write lease.
 
@@ -4233,7 +4292,7 @@ permission:
     "grep *": allow
 ---
 
-# Generated by Truthmark ${TRUTHMARK_VERSION}. Rerun truthmark init after upgrades.
+# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
 
 Manual invocation: @${invocation}
 
@@ -4268,7 +4327,7 @@ ${editAllowRules}
     "git diff*": allow
 ---
 
-# Generated by Truthmark ${TRUTHMARK_VERSION}. Rerun truthmark init after upgrades.
+# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
 
 Manual invocation: @${invocation}
 
@@ -4319,7 +4378,6 @@ policy:
   allow_implicit_invocation: ${workflow.allowImplicitInvocation}
 
 truthmark:
-  version: "${TRUTHMARK_VERSION}"
   refresh_command: "truthmark init"
 `;
 };
@@ -4334,7 +4392,6 @@ policy:
   allow_implicit_invocation: ${workflow.allowImplicitInvocation}
 
 truthmark:
-  version: "${TRUTHMARK_VERSION}"
   refresh_command: "truthmark init"
 `;
 };
@@ -4349,7 +4406,6 @@ policy:
   allow_implicit_invocation: ${workflow.allowImplicitInvocation}
 
 truthmark:
-  version: "${TRUTHMARK_VERSION}"
   refresh_command: "truthmark init"
 `;
 };
@@ -4373,7 +4429,7 @@ Workflow:
 3. ${EVIDENCE_AUTHORITY_INSTRUCTIONS}
 ${renderTruthDocOwnershipGateSection(
     "source truth docs before writing code",
-    "if a source truth doc is broad, mixed-owner, index-like, unrouteable, stale, or conflicts with implementation evidence, block before writing code and recommend Truth Structure or Truth Document"
+    "if a source truth doc is broad, mixed-owner, index-like, unrouteable, stale, or conflicts with implementation evidence, stop before writing code and recommend Truth Structure or Truth Document"
   )}
 4. Update functional code only so implementation matches bounded, current truth claims from the source docs.
 5. Do not edit truth docs or truth routing while realizing those docs.
@@ -4398,22 +4454,6 @@ policy:
   allow_implicit_invocation: ${workflow.allowImplicitInvocation}
 
 truthmark:
-  version: "${TRUTHMARK_VERSION}"
-  refresh_command: "truthmark init"
-`;
-};
-var renderTruthmarkPreviewSkillMetadata = () => {
-  const workflow = getTruthmarkWorkflow("truthmark-preview");
-  return `interface:
-  display_name: "${workflow.displayName}"
-  short_description: "${workflow.shortDescription}"
-  default_prompt: "${workflow.defaultPrompt}"
-
-policy:
-  allow_implicit_invocation: ${workflow.allowImplicitInvocation}
-
-truthmark:
-  version: "${TRUTHMARK_VERSION}"
   refresh_command: "truthmark init"
 `;
 };
@@ -4428,7 +4468,6 @@ policy:
   allow_implicit_invocation: ${workflow.allowImplicitInvocation}
 
 truthmark:
-  version: "${TRUTHMARK_VERSION}"
   refresh_command: "truthmark init"
 `;
 };
@@ -4443,7 +4482,6 @@ policy:
   allow_implicit_invocation: ${workflow.allowImplicitInvocation}
 
 truthmark:
-  version: "${TRUTHMARK_VERSION}"
   refresh_command: "truthmark init"
 `;
 };
@@ -4507,10 +4545,15 @@ var renderTruthmarkGeminiCheckCommand = (config = defaultAgentConfig()) => {
   );
 };
 var renderTruthmarkGeminiPreviewCommand = (config = defaultAgentConfig()) => {
-  void config;
-  return renderGeminiWorkflowCommand(
-    "truthmark-preview",
-    ".gemini/skills/truthmark-preview"
+  const workflow = getTruthmarkWorkflow("truthmark-preview");
+  return renderGeminiCommand(
+    workflow.description,
+    `This command is the Gemini CLI entrypoint for Truthmark Preview.
+
+Truth Preview is read-only and explicit. Do not invoke another Truthmark command from here.
+
+${renderTruthPreviewProcedureBody(config, "gemini")}
+${renderTruthPreviewAdapterReportFields()}`
   );
 };
 var renderTruthmarkGeminiPortalCommand = (config = defaultAgentConfig()) => {
@@ -4556,10 +4599,15 @@ var renderTruthmarkCopilotCheckPrompt = (config = defaultAgentConfig()) => {
   );
 };
 var renderTruthmarkCopilotPreviewPrompt = (config = defaultAgentConfig()) => {
-  void config;
-  return renderCopilotWorkflowPrompt(
-    "truthmark-preview",
-    ".github/skills/truthmark-preview"
+  const workflow = getTruthmarkWorkflow("truthmark-preview");
+  return renderCopilotPromptFile(
+    workflow.description,
+    `This prompt is the GitHub Copilot entrypoint for Truthmark Preview.
+
+Truth Preview is read-only and explicit. Do not invoke another Truthmark command from here.
+
+${renderTruthPreviewProcedureBody(config, "copilot")}
+${renderTruthPreviewAdapterReportFields()}`
   );
 };
 var renderTruthmarkCopilotPortalPrompt = (config = defaultAgentConfig()) => {
@@ -4603,16 +4651,6 @@ var codexFiles = (config) => {
       path: TRUTHMARK_SYNC_SKILL_METADATA_PATH,
       content: renderTruthmarkSyncSkillMetadata()
     },
-    ...renderTruthmarkSkillPackage({
-      skillPath: TRUTHMARK_PREVIEW_SKILL_PATH,
-      workflowId: "truthmark-preview",
-      host: "codex",
-      config
-    }),
-    {
-      path: TRUTHMARK_PREVIEW_SKILL_METADATA_PATH,
-      content: renderTruthmarkPreviewSkillMetadata()
-    },
     ...renderTruthmarkSkillPackage({
       skillPath: TRUTHMARK_CHECK_SKILL_PATH,
       workflowId: "truthmark-check",
@@ -4686,12 +4724,6 @@ var opencodeFiles = (config) => {
       host: "opencode",
       config
     }),
-    ...renderTruthmarkSkillPackage({
-      skillPath: ".opencode/skills/truthmark-preview/SKILL.md",
-      workflowId: "truthmark-preview",
-      host: "opencode",
-      config
-    }),
     ...renderTruthmarkSkillPackage({
       skillPath: ".opencode/skills/truthmark-check/SKILL.md",
       workflowId: "truthmark-check",
@@ -4754,12 +4786,6 @@ var claudeFiles = (config, block) => {
       host: "claude-code",
       config
     }),
-    ...renderTruthmarkSkillPackage({
-      skillPath: ".claude/skills/truthmark-preview/SKILL.md",
-      workflowId: "truthmark-preview",
-      host: "claude-code",
-      config
-    }),
     ...renderTruthmarkSkillPackage({
       skillPath: ".claude/skills/truthmark-check/SKILL.md",
       workflowId: "truthmark-check",
@@ -4822,12 +4848,6 @@ var copilotFiles = (config, block) => {
       host: "github-copilot",
       config
     }),
-    ...renderTruthmarkSkillPackage({
-      skillPath: ".github/skills/truthmark-preview/SKILL.md",
-      workflowId: "truthmark-preview",
-      host: "github-copilot",
-      config
-    }),
     ...renderTruthmarkSkillPackage({
       skillPath: ".github/skills/truthmark-check/SKILL.md",
       workflowId: "truthmark-check",
@@ -4918,12 +4938,6 @@ var geminiFiles = (config, block) => {
       host: "gemini-cli",
       config
     }),
-    ...renderTruthmarkSkillPackage({
-      skillPath: ".gemini/skills/truthmark-preview/SKILL.md",
-      workflowId: "truthmark-preview",
-      host: "gemini-cli",
-      config
-    }),
     ...renderTruthmarkSkillPackage({
       skillPath: ".gemini/skills/truthmark-check/SKILL.md",
       workflowId: "truthmark-check",
@@ -5026,6 +5040,163 @@ var renderGeneratedSurfaces = (config, block = renderAgentsBlock(config)) => {
   ).sort((left, right) => left.path.localeCompare(right.path));
 };
 
+// src/checks/generated-surfaces.ts
+var readOptionalFile = async (rootDir, filePath) => {
+  try {
+    return await fs6.readFile(resolveRepoPath(rootDir, filePath), "utf8");
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+      return null;
+    }
+    throw error;
+  }
+};
+var extractManagedBlock = (content) => {
+  const startIndex = content.indexOf(TRUTHMARK_BLOCK_START);
+  const endIndex = content.indexOf(TRUTHMARK_BLOCK_END);
+  if (startIndex === -1 || endIndex === -1 || endIndex < startIndex) {
+    return null;
+  }
+  return content.slice(startIndex, endIndex + TRUTHMARK_BLOCK_END.length);
+};
+var normalizeGeneratedSurfaceContent = (content) => {
+  if (content === null) {
+    return null;
+  }
+  return content.replace(/\r\n/g, "\n").replace(/\n$/u, "");
+};
+var GENERATED_HOST_SKILL_ROOTS = [
+  ".agents/skills",
+  ".opencode/skills",
+  ".claude/skills",
+  ".github/skills",
+  ".gemini/skills"
+];
+var RETIRED_SKILL_HELPER_PATHS = [
+  "helper-manifest.yml",
+  "support/helper-policy.md"
+];
+var RETIRED_PACKAGE_DIRECTORIES = ["truthmark-preview"];
+var pathExists = async (absolutePath) => {
+  try {
+    await fs6.access(absolutePath);
+    return true;
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+      return false;
+    }
+    throw error;
+  }
+};
+var listDirectoryFiles = async (rootDir, packageRoot) => {
+  const stack = [packageRoot];
+  const files = [];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    if (current === void 0) {
+      continue;
+    }
+    const absoluteCurrent = resolveRepoPath(rootDir, current);
+    const entries = await fs6.readdir(absoluteCurrent, {
+      withFileTypes: true
+    });
+    for (const entry of entries) {
+      const next = `${current}/${entry.name}`;
+      if (entry.isDirectory()) {
+        stack.push(next);
+      } else {
+        files.push(next);
+      }
+    }
+  }
+  return files;
+};
+var collectRetiredGeneratedSurfaces = async (rootDir, expectedSurfacePaths) => {
+  const legacyCandidates = /* @__PURE__ */ new Set();
+  for (const skillRoot of GENERATED_HOST_SKILL_ROOTS) {
+    const absoluteSkillRoot = resolveRepoPath(rootDir, skillRoot);
+    let skillPackages = [];
+    try {
+      skillPackages = await fs6.readdir(absoluteSkillRoot, {
+        withFileTypes: true
+      });
+    } catch (error) {
+      if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+        continue;
+      }
+      throw error;
+    }
+    const packageNames = skillPackages.filter((entry) => entry.isDirectory() && entry.name.startsWith("truthmark-")).map((entry) => entry.name);
+    for (const packageName of RETIRED_PACKAGE_DIRECTORIES) {
+      if (!packageNames.includes(packageName)) {
+        continue;
+      }
+      const packageRoot = `${skillRoot}/${packageName}`;
+      const packageFiles = await listDirectoryFiles(rootDir, packageRoot);
+      for (const filePath of packageFiles) {
+        if (!expectedSurfacePaths.has(filePath)) {
+          legacyCandidates.add(filePath);
+        }
+      }
+    }
+    for (const packageName of packageNames) {
+      for (const retiredName of RETIRED_SKILL_HELPER_PATHS) {
+        const retiredPath = `${packageName}/${retiredName}`;
+        const relativeRetiredPath = `${skillRoot}/${retiredPath}`;
+        const absoluteRetiredPath = resolveRepoPath(rootDir, relativeRetiredPath);
+        if (await pathExists(absoluteRetiredPath) && !expectedSurfacePaths.has(relativeRetiredPath)) {
+          legacyCandidates.add(relativeRetiredPath);
+        }
+      }
+    }
+  }
+  return Array.from(legacyCandidates);
+};
+var checkGeneratedSurfaces = async (rootDir, config) => {
+  const diagnostics = [];
+  const renderedSurfaces = renderGeneratedSurfaces(config);
+  for (const surface of renderedSurfaces) {
+    const content = await readOptionalFile(rootDir, surface.path);
+    if (content === null) {
+      diagnostics.push({
+        category: "generated-surface",
+        severity: "review",
+        message: `Generated surface ${surface.path} is missing; rerun truthmark init.`,
+        file: surface.path
+      });
+      continue;
+    }
+    const comparableContent = normalizeGeneratedSurfaceContent(
+      surface.managedBlock ? extractManagedBlock(content) : content
+    );
+    const expectedContent = normalizeGeneratedSurfaceContent(surface.content);
+    if (comparableContent !== expectedContent) {
+      diagnostics.push({
+        category: "generated-surface",
+        severity: "review",
+        message: `Generated surface ${surface.path} is stale; rerun truthmark init.`,
+        file: surface.path
+      });
+    }
+  }
+  const staleSurfaces = await collectRetiredGeneratedSurfaces(
+    rootDir,
+    new Set(renderedSurfaces.map((surface) => surface.path))
+  );
+  for (const surfacePath of staleSurfaces) {
+    diagnostics.push({
+      category: "generated-surface",
+      severity: "review",
+      message: `Generated surface ${surfacePath} is obsolete; rerun truthmark init.`,
+      file: surfacePath
+    });
+  }
+  return diagnostics;
+};
+var findRetiredGeneratedSurfaces = async (rootDir, expectedSurfacePaths) => {
+  return collectRetiredGeneratedSurfaces(rootDir, expectedSurfacePaths);
+};
+
 // src/init/init.ts
 var escapeRegExp = (value) => {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -5201,9 +5372,17 @@ var runInit = async (cwd) => {
   results.push(...await scaffoldHierarchy(rootDir, config));
   const block = renderAgentsBlock(config);
   const platformFiles = renderGeneratedSurfaces(config, block);
+  const expectedSurfacePaths = new Set(platformFiles.map((file) => file.path));
   for (const file of platformFiles) {
     results.push(await writePlatformFile(rootDir, file));
   }
+  const obsoleteSurfacePaths = await findRetiredGeneratedSurfaces(
+    rootDir,
+    expectedSurfacePaths
+  );
+  for (const obsoletePath of obsoleteSurfacePaths) {
+    await fs7.rm(resolveRepoPath(rootDir, obsoletePath), { force: true });
+  }
   const changedResults = results.filter((result) => result.status !== "unchanged");
   return {
     command: "init",
@@ -5298,7 +5477,7 @@ import fg2 from "fast-glob";
 var looksLikeGlob = (pattern) => {
   return /[*?[\]{}()!+@]/u.test(pattern);
 };
-var pathExists = async (absolutePath) => {
+var pathExists2 = async (absolutePath) => {
   try {
     await fs9.stat(absolutePath);
     return true;
@@ -5368,7 +5547,7 @@ var checkControlledPaths = async (rootDir, controlledPaths) => {
       });
       continue;
     }
-    if (!await pathExists(absoluteEntryPath)) {
+    if (!await pathExists2(absoluteEntryPath)) {
       diagnostics.push({
         category: "authority",
         severity: "error",
@@ -5586,7 +5765,7 @@ var checkFrontmatter = async (rootDir, config, markdownPaths, truthDocumentEntri
 // src/checks/links.ts
 import fs11 from "fs/promises";
 import path5 from "path";
-var pathExists2 = async (absolutePath) => {
+var pathExists3 = async (absolutePath) => {
   try {
     await fs11.stat(absolutePath);
     return true;
@@ -5632,7 +5811,7 @@ var checkLinks = async (rootDir, markdownPaths) => {
         });
         continue;
       }
-      if (!await pathExists2(absoluteTarget)) {
+      if (!await pathExists3(absoluteTarget)) {
         diagnostics.push({
           category: "links",
           severity: "error",
@@ -6008,7 +6187,7 @@ var classifyPath = (filePath, ignorePatterns) => {
 var looksLikeGlob2 = (pattern) => {
   return /[*?[\]{}()!+@]/u.test(pattern);
 };
-var pathExists3 = async (absolutePath) => {
+var pathExists4 = async (absolutePath) => {
   try {
     await fs13.stat(absolutePath);
     return true;
@@ -6300,7 +6479,7 @@ var checkAreas = async (rootDir, config) => {
         areaHasTruthDocumentErrors = true;
         continue;
       }
-      if (!await pathExists3(absoluteTruthDocumentPath)) {
+      if (!await pathExists4(absoluteTruthDocumentPath)) {
         diagnostics.push({
           category: "area-index",
           severity: "error",
@@ -6404,7 +6583,7 @@ var checkAreas = async (rootDir, config) => {
         entry.valid = false;
         continue;
       }
-      if (!await pathExists3(absoluteCodeSurfacePath)) {
+      if (!await pathExists4(absoluteCodeSurfacePath)) {
         diagnostics.push({
           category: "area-index",
           severity: "error",
@@ -6608,95 +6787,12 @@ var checkDecisionSections = async (rootDir, config, markdownPaths, truthDocument
   return diagnostics;
 };
 
-// src/checks/generated-surfaces.ts
-import fs15 from "fs/promises";
-var readOptionalFile = async (rootDir, filePath) => {
-  try {
-    return await fs15.readFile(resolveRepoPath(rootDir, filePath), "utf8");
-  } catch (error) {
-    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
-      return null;
-    }
-    throw error;
-  }
-};
-var extractManagedBlock = (content) => {
-  const startIndex = content.indexOf(TRUTHMARK_BLOCK_START);
-  const endIndex = content.indexOf(TRUTHMARK_BLOCK_END);
-  if (startIndex === -1 || endIndex === -1 || endIndex < startIndex) {
-    return null;
-  }
-  return content.slice(startIndex, endIndex + TRUTHMARK_BLOCK_END.length);
-};
-var normalizeGeneratedSurfaceContent = (content) => {
-  if (content === null) {
-    return null;
-  }
-  return content.replace(/\r\n/g, "\n").replace(/\n$/u, "");
-};
-var versionMarkers = (content) => {
-  const markers = [];
-  const patterns = [
-    /truthmark-version:\s*([^\s]+)/gu,
-    /Generated by Truthmark\s+([^\s.]+(?:\.[^\s.]+){1,2})/gu,
-    /^version:\s*"(\d+\.\d+\.\d+)"\s*$/gmu
-  ];
-  for (const pattern of patterns) {
-    for (const match of content.matchAll(pattern)) {
-      if (match[1]) {
-        markers.push(match[1]);
-      }
-    }
-  }
-  return markers;
-};
-var checkGeneratedSurfaces = async (rootDir, config) => {
-  const diagnostics = [];
-  for (const surface of renderGeneratedSurfaces(config)) {
-    const content = await readOptionalFile(rootDir, surface.path);
-    if (content === null) {
-      diagnostics.push({
-        category: "generated-surface",
-        severity: "review",
-        message: `Generated surface ${surface.path} is missing; rerun truthmark init.`,
-        file: surface.path
-      });
-      continue;
-    }
-    const comparableContent = normalizeGeneratedSurfaceContent(
-      surface.managedBlock ? extractManagedBlock(content) : content
-    );
-    const expectedContent = normalizeGeneratedSurfaceContent(surface.content);
-    if (comparableContent !== expectedContent) {
-      diagnostics.push({
-        category: "generated-surface",
-        severity: "review",
-        message: `Generated surface ${surface.path} is stale; rerun truthmark init.`,
-        file: surface.path
-      });
-    }
-    const versionContent = surface.managedBlock ? comparableContent ?? "" : content;
-    const mismatchedVersions = versionMarkers(versionContent).filter(
-      (version) => version !== TRUTHMARK_VERSION
-    );
-    if (mismatchedVersions.length > 0) {
-      diagnostics.push({
-        category: "generated-surface",
-        severity: "review",
-        message: `Generated surface ${surface.path} has Truthmark version ${mismatchedVersions[0]} but current version is ${TRUTHMARK_VERSION}; rerun truthmark init.`,
-        file: surface.path
-      });
-    }
-  }
-  return diagnostics;
-};
-
 // src/impact/build.ts
 import path10 from "path";
 import micromatch7 from "micromatch";
 
 // src/repo-index/file-tree.ts
-import fs16 from "fs/promises";
+import fs15 from "fs/promises";
 import path7 from "path";
 import { execa as execa2 } from "execa";
 import fg5 from "fast-glob";
@@ -6872,7 +6968,7 @@ var discoverRepoFiles = async (rootDir, ignore) => {
   for (const filePath of discoveredFiles.filter((entry) => !isIgnoredPath(entry, ignore)).sort()) {
     let stat;
     try {
-      stat = await fs16.stat(path7.join(rootDir, filePath));
+      stat = await fs15.stat(path7.join(rootDir, filePath));
     } catch (error) {
       if (error instanceof Error && "code" in error && error.code === "ENOENT") {
         continue;
@@ -6896,7 +6992,7 @@ var discoverRepoFiles = async (rootDir, ignore) => {
       });
     }
     if (kind === "doc") {
-      const source = await fs16.readFile(path7.join(rootDir, filePath), "utf8");
+      const source = await fs15.readFile(path7.join(rootDir, filePath), "utf8");
       const parsed = parseFrontmatter(source);
       const markdown = parseMarkdownDocument(parsed.content);
       const title = markdown.headings.find((heading) => heading.depth === 1)?.text ?? null;
@@ -6924,7 +7020,7 @@ var discoverRepoFiles = async (rootDir, ignore) => {
 };
 
 // src/repo-index/package-metadata.ts
-import fs17 from "fs/promises";
+import fs16 from "fs/promises";
 import path8 from "path";
 import fg6 from "fast-glob";
 var packageManagerFor = async (rootDir, packageDir) => {
@@ -6937,7 +7033,7 @@ var packageManagerFor = async (rootDir, packageDir) => {
   ];
   for (const [lockfile, manager] of lockfiles) {
     try {
-      await fs17.access(path8.join(rootDir, packageDir, lockfile));
+      await fs16.access(path8.join(rootDir, packageDir, lockfile));
       return manager;
     } catch {
       continue;
@@ -6955,7 +7051,7 @@ var discoverPackageMetadata = async (rootDir) => {
   const packages = [];
   for (const packageFile of packageFiles.sort()) {
     const packageDir = path8.posix.dirname(packageFile) === "." ? "" : path8.posix.dirname(packageFile);
-    const raw = JSON.parse(await fs17.readFile(path8.join(rootDir, packageFile), "utf8"));
+    const raw = JSON.parse(await fs16.readFile(path8.join(rootDir, packageFile), "utf8"));
     const scripts = raw.scripts && typeof raw.scripts === "object" ? Object.keys(raw.scripts).sort() : [];
     packages.push({
       path: packageFile,
@@ -7060,7 +7156,7 @@ var buildRepoIndex = async (cwd) => {
 import { execa as execa4 } from "execa";
 
 // src/git/changes.ts
-import fs18 from "fs/promises";
+import fs17 from "fs/promises";
 import path9 from "path";
 import { execa as execa3 } from "execa";
 var normalizePath3 = (filePath) => {
@@ -7070,9 +7166,9 @@ var listChangedPaths = async (cwd, args) => {
   const result = await execa3("git", args, { cwd });
   return result.stdout.split("\n").map((line) => line.trim()).filter((line) => line.length > 0).map((line) => normalizePath3(line));
 };
-var pathExists4 = async (filePath) => {
+var pathExists5 = async (filePath) => {
   try {
-    await fs18.access(filePath);
+    await fs17.access(filePath);
     return true;
   } catch {
     return false;
@@ -7116,7 +7212,7 @@ var getUncommittedChanges = async (cwd) => {
   const deletedPathCandidates = /* @__PURE__ */ new Set([...stagedDeletedPaths, ...unstagedDeletedPaths]);
   for (const deletedPath of deletedPathCandidates) {
     const change = getOrCreateChange(changesByPath, deletedPath);
-    change.deleted = !await pathExists4(path9.join(rootDir, deletedPath));
+    change.deleted = !await pathExists5(path9.join(rootDir, deletedPath));
   }
   return Array.from(changesByPath.values()).sort((left, right) => {
     return left.path.localeCompare(right.path);
@@ -7319,11 +7415,11 @@ var checkFreshness = async (rootDir, _config, _truthDocumentPaths, base) => {
 };
 
 // src/evidence/validate.ts
-import fs20 from "fs/promises";
+import fs19 from "fs/promises";
 import fg7 from "fast-glob";
 
 // src/evidence/parse.ts
-import fs19 from "fs/promises";
+import fs18 from "fs/promises";
 import path11 from "path";
 import { parse as parse4 } from "yaml";
 var yamlFencePattern = /```ya?ml\s*\n([\s\S]*?)```/giu;
@@ -7343,7 +7439,7 @@ var toEvidenceReference = (truthDocPath, raw) => {
   };
 };
 var parseEvidenceReferences = async (rootDir, truthDocPath) => {
-  const source = await fs19.readFile(path11.join(rootDir, truthDocPath), "utf8");
+  const source = await fs18.readFile(path11.join(rootDir, truthDocPath), "utf8");
   const parsed = parseFrontmatter(source);
   const references = [];
   for (const entry of parseSourceReferences(source, truthDocPath)) {
@@ -7374,9 +7470,9 @@ var parseEvidenceReferences = async (rootDir, truthDocPath) => {
 };
 
 // src/evidence/validate.ts
-var pathExists5 = async (filePath) => {
+var pathExists6 = async (filePath) => {
   try {
-    await fs20.access(filePath);
+    await fs19.access(filePath);
     return true;
   } catch {
     return false;
@@ -7421,7 +7517,7 @@ var validateHash = async (rootDir, reference) => {
   if (!reference.contentHash.startsWith("sha256:")) {
     return diagnosticFor(reference, `Evidence hash for ${reference.path} must use sha256:.`);
   }
-  const source = await fs20.readFile(resolveRepoPath(rootDir, reference.path), "utf8");
+  const source = await fs19.readFile(resolveRepoPath(rootDir, reference.path), "utf8");
   const lines = source.split("\n");
   const startLine = reference.startLine ?? 1;
   const endLine = reference.endLine ?? lines.length;
@@ -7435,7 +7531,7 @@ var validateLineSpan = async (rootDir, reference) => {
   if (reference.startLine === void 0 && reference.endLine === void 0) {
     return null;
   }
-  const source = await fs20.readFile(resolveRepoPath(rootDir, reference.path), "utf8");
+  const source = await fs19.readFile(resolveRepoPath(rootDir, reference.path), "utf8");
   const lines = source.split("\n");
   const startLine = reference.startLine ?? 1;
   const endLine = reference.endLine ?? lines.length;
@@ -7450,7 +7546,7 @@ var validateReference = async (rootDir, reference) => {
     }
     const absolutePath = resolveRepoPath(rootDir, reference.path);
     await assertRepoContainment(rootDir, absolutePath);
-    if (!await pathExists5(absolutePath)) {
+    if (!await pathExists6(absolutePath)) {
       diagnostics.push(diagnosticFor(reference, `Referenced file ${reference.path} does not exist.`));
       return diagnostics;
     }
@@ -7721,25 +7817,49 @@ var helperCommandsFor = (manifestEntry) => (manifestEntry.helpers ?? []).map((he
   argv: [...helper.command.argv],
   optional: helper.optional
 }));
-var evidenceFor = (manifestEntry) => manifestEntry.requiredGates.filter((gate) => /evidence|ownership|containment/iu.test(gate));
-var baseContext = (manifestEntry, mode, allowedWritePaths, forbiddenWritePaths, writeLeaseRequired) => ({
+var evidenceFor = (manifestEntry) => manifestEntry.reviewQuestions.filter(
+  (question) => /evidence|ownership|containment/iu.test(question)
+);
+var baseContext = (manifestEntry, mode, allowedWritePaths, routeFiles, primaryTruthDocs, candidateStaleTruthDocs, forbiddenWritePaths, writeLeaseRequired) => ({
   mode,
   allowedWritePaths: uniqueSorted3(allowedWritePaths),
+  routeFiles: uniqueSorted3(routeFiles),
+  primaryTruthDocs: uniqueSorted3(primaryTruthDocs),
+  candidateStaleTruthDocs: uniqueSorted3(candidateStaleTruthDocs),
   forbiddenWritePaths: uniqueSorted3(forbiddenWritePaths),
-  stopConditions: [...manifestEntry.negativeTriggers, ...manifestEntry.forbiddenAdjacency],
-  requiredEvidence: evidenceFor(manifestEntry),
+  stopConditions: [
+    ...manifestEntry.negativeTriggers,
+    ...manifestEntry.forbiddenAdjacency
+  ],
+  evidencePrompts: uniqueSorted3([
+    ...evidenceFor(manifestEntry),
+    ...candidateStaleTruthDocs.length > 0 ? [
+      "Record checkout evidence and the reason before touching a candidate stale truth doc outside primaryTruthDocs."
+    ] : []
+  ]),
   helperValidationCommands: helperCommandsFor(manifestEntry),
   writeLeaseRequired
 });
 var buildWorkflowActionContext = (manifestEntry, data = {}) => {
   if (manifestEntry.id === "truthmark-preview" || manifestEntry.id === "truthmark-check") {
-    return baseContext(manifestEntry, "read-only", [], [], false);
+    return baseContext(manifestEntry, "read-only", [], [], [], [], [], false);
   }
   if (manifestEntry.id === "truthmark-sync" || manifestEntry.id === "truthmark-document") {
+    const routeFiles = data.routeFiles ?? [];
+    const primaryTruthDocs = data.primaryTruthDocs ?? data.truthDocs ?? [];
+    const candidateStaleTruthDocs = data.candidateStaleTruthDocs ?? [];
     return baseContext(
       manifestEntry,
       "truth-doc-write",
-      [...data.routeIndexPath ? [data.routeIndexPath] : [], ...data.routeFiles ?? [], ...data.truthDocs ?? []],
+      [
+        ...data.routeIndexPath ? [data.routeIndexPath] : [],
+        ...routeFiles,
+        ...primaryTruthDocs,
+        ...candidateStaleTruthDocs
+      ],
+      routeFiles,
+      primaryTruthDocs,
+      candidateStaleTruthDocs,
       [],
       true
     );
@@ -7753,6 +7873,9 @@ var buildWorkflowActionContext = (manifestEntry, data = {}) => {
         ...data.routeFiles ?? [],
         ...data.starterTruthDocs ?? []
       ],
+      data.routeFiles ?? [],
+      data.starterTruthDocs ?? [],
+      [],
       [],
       true
     );
@@ -7762,6 +7885,9 @@ var buildWorkflowActionContext = (manifestEntry, data = {}) => {
       manifestEntry,
       "code-write",
       data.codeWritePaths ?? [],
+      data.routeFiles ?? [],
+      data.truthDocs ?? [],
+      [],
       [
         ...data.routeIndexPath ? [data.routeIndexPath] : [],
         ...data.routeFiles ?? [],
@@ -7776,6 +7902,9 @@ var buildWorkflowActionContext = (manifestEntry, data = {}) => {
     "portal-write",
     data.portalEnabled && data.portalOutputPath ? [`${data.portalOutputPath}/**`] : [],
     [],
+    [],
+    [],
+    [],
     false
   );
 };
@@ -7789,16 +7918,26 @@ var helperCommandsFor2 = (workflow) => (TRUTHMARK_WORKFLOW_MANIFEST[workflow].he
 }));
 var uniqueSorted4 = (values) => [...new Set(values.filter((value) => value.length > 0))].sort();
 var isWriteCapable = (workflow) => !["truthmark-preview", "truthmark-check"].includes(workflow);
-var DEFAULT_BASE_CANDIDATES = ["@{upstream}", "origin/main", "main", "origin/master", "master"];
+var DEFAULT_BASE_CANDIDATES = [
+  "@{upstream}",
+  "origin/main",
+  "main",
+  "origin/master",
+  "master"
+];
 var selectComparisonBase = async (rootDir, suppliedBase) => {
   if (suppliedBase) {
     return suppliedBase;
   }
   for (const candidate of DEFAULT_BASE_CANDIDATES) {
-    const result = await execa5("git", ["rev-parse", "--verify", `${candidate}^{commit}`], {
-      cwd: rootDir,
-      reject: false
-    });
+    const result = await execa5(
+      "git",
+      ["rev-parse", "--verify", `${candidate}^{commit}`],
+      {
+        cwd: rootDir,
+        reject: false
+      }
+    );
     if ((result.exitCode ?? 1) === 0) {
       return candidate;
     }
@@ -7806,59 +7945,110 @@ var selectComparisonBase = async (rootDir, suppliedBase) => {
   return null;
 };
 var routeFilesFor = (repoIndex) => uniqueSorted4(repoIndex.routeMap.routes.map((route) => route.sourcePath));
+var candidateStaleTruthDocsFor = (indexedTruthDocs, primaryTruthDocs) => {
+  const primary = new Set(primaryTruthDocs);
+  return indexedTruthDocs.filter((truthDoc) => !primary.has(truthDoc));
+};
 var hasUnmappedFunctionalChange = (impactSet) => impactSet?.diagnostics.some(
-  (diagnostic) => diagnostic.category === "impact" && /not mapped to a Truthmark route|no affected truth document/u.test(diagnostic.message)
+  (diagnostic) => diagnostic.category === "impact" && /not mapped to a Truthmark route|no affected truth document/u.test(
+    diagnostic.message
+  )
 ) ?? false;
 var applicabilityFor = (workflow, diagnostics, impactSet) => {
   const reasons = [];
-  if (diagnostics.some((diagnostic) => diagnostic.message.includes("Missing .truthmark/config.yml"))) {
+  if (diagnostics.some(
+    (diagnostic) => diagnostic.message.includes("Missing .truthmark/config.yml")
+  )) {
     reasons.push("Missing .truthmark/config.yml.");
-    return { state: isWriteCapable(workflow) ? "blocked" : "not_applicable", reasons };
+    return {
+      state: isWriteCapable(workflow) ? "needs_manual_review" : "not_applicable",
+      reasons
+    };
   }
   if (workflow === "truthmark-sync" && !impactSet) {
-    reasons.push("truthmark-sync requires --base to derive changed-file impact before exposing sync write paths.");
-    return { state: "blocked", reasons };
+    reasons.push(
+      "Choose a comparison base with --base <ref> when workflow status cannot infer one automatically."
+    );
+    return { state: "needs_manual_review", reasons };
   }
   if (workflow === "truthmark-realize" && !impactSet) {
-    reasons.push("truthmark-realize requires --base to derive bounded allowed write paths.");
-    return { state: "blocked", reasons };
+    reasons.push(
+      "Choose a comparison base with --base <ref> so the helper can suggest bounded code-write paths."
+    );
+    return { state: "needs_manual_review", reasons };
   }
   if (hasUnmappedFunctionalChange(impactSet)) {
-    reasons.push("Changed functional files have ambiguous or missing Truthmark route ownership.");
-    return { state: "ambiguous", reasons };
+    reasons.push(
+      "Changed functional files need route ownership review before truth-doc suggestions are reliable."
+    );
+    return { state: "needs_routing_review", reasons };
   }
   if (diagnostics.some((diagnostic) => diagnostic.severity === "error")) {
-    reasons.push("Existing diagnostics contain errors that block safe workflow execution.");
-    return { state: "blocked", reasons };
+    reasons.push(
+      "Existing diagnostics need manual review before using helper write suggestions."
+    );
+    return { state: "needs_manual_review", reasons };
   }
-  return { state: "applicable", reasons };
+  return { state: "ready", reasons };
+};
+var workflowCardFor = (workflow, applicability, diagnostics, impactSet) => {
+  const helpers = helperCommandsFor2(workflow);
+  const diagnosticQuestions = diagnostics.filter((diagnostic) => diagnostic.severity === "error").map((diagnostic) => diagnostic.message);
+  return {
+    affectedFiles: uniqueSorted4(
+      impactSet?.changedFiles.map((file) => file.path) ?? []
+    ),
+    likelyRouteOwners: uniqueSorted4(
+      impactSet?.affectedRoutes.map((route) => route.sourcePath) ?? []
+    ),
+    suggestedTruthDocs: applicability.state === "needs_routing_review" ? [] : uniqueSorted4(impactSet?.affectedTruthDocs ?? []),
+    openQuestions: uniqueSorted4([
+      ...applicability.reasons,
+      ...diagnosticQuestions
+    ]),
+    skippedHelperStatus: helpers.map((helper) => ({
+      helper: helper.id,
+      status: "skipped",
+      reason: "workflow status does not run optional helpers; inspect the checkout directly or run the helper manually when useful."
+    }))
+  };
 };
 var contextDataFor = (workflow, repoIndex, config, impactSet) => {
   if (!config) {
     return {};
   }
   const routeFiles = routeFilesFor(repoIndex);
-  const indexedTruthDocs = uniqueSorted4(repoIndex.routeMap.routes.flatMap((route) => route.truthDocs));
-  const truthDocs = workflow === "truthmark-sync" ? indexedTruthDocs : uniqueSorted4(impactSet?.affectedTruthDocs ?? indexedTruthDocs);
+  const indexedTruthDocs = uniqueSorted4(
+    repoIndex.routeMap.routes.flatMap((route) => route.truthDocs)
+  );
+  const primaryTruthDocs = uniqueSorted4(impactSet?.affectedTruthDocs ?? []);
+  const candidateStaleTruthDocs = workflow === "truthmark-sync" ? candidateStaleTruthDocsFor(indexedTruthDocs, primaryTruthDocs) : [];
+  const truthDocs = workflow === "truthmark-sync" ? uniqueSorted4([...primaryTruthDocs, ...candidateStaleTruthDocs]) : uniqueSorted4(impactSet?.affectedTruthDocs ?? indexedTruthDocs);
   return {
     routeIndexPath: config.truthmark.paths.routesIndex,
     routeFiles,
     truthRoot: config.truthmark.paths.truthRoot,
     truthDocs,
+    primaryTruthDocs: workflow === "truthmark-sync" ? primaryTruthDocs : truthDocs,
+    candidateStaleTruthDocs,
     starterTruthDocs: workflow === "truthmark-structure" ? truthDocs : [],
-    codeWritePaths: workflow === "truthmark-realize" ? uniqueSorted4(impactSet?.affectedRoutes.flatMap((route) => route.codeSurface) ?? []) : [],
+    codeWritePaths: workflow === "truthmark-realize" ? uniqueSorted4(
+      impactSet?.affectedRoutes.flatMap((route) => route.codeSurface) ?? []
+    ) : [],
     portalEnabled: config.truthmark.generated.portal.enabled,
     portalOutputPath: config.truthmark.paths.portalOutput,
     routes: repoIndex.routeMap.routes
   };
 };
 var nextStepsFor = (workflow, applicability, comparisonBase) => {
-  if (applicability.state === "ambiguous") {
-    return ["Run Truth Structure or repair route ownership before writing truth docs."];
+  if (applicability.state === "needs_routing_review") {
+    return [
+      "Run Truth Structure or repair route ownership before writing truth docs."
+    ];
   }
-  if ((workflow === "truthmark-sync" || workflow === "truthmark-realize") && applicability.state === "blocked" && !comparisonBase) {
+  if ((workflow === "truthmark-sync" || workflow === "truthmark-realize") && applicability.state === "needs_manual_review" && !comparisonBase) {
     return [
-      workflow === "truthmark-sync" ? "Rerun with --base <ref> so Truthmark can derive changed-file impact before exposing sync write paths." : "Rerun with --base <ref> so Truthmark can derive bounded allowed code-write paths."
+      workflow === "truthmark-sync" ? "Rerun with --base <ref> so the helper can suggest changed-file impact." : "Rerun with --base <ref> so the helper can suggest bounded code-write paths."
     ];
   }
   return [];
@@ -7873,26 +8063,44 @@ var buildWorkflowState = async (cwd, options) => {
   const loadResult = await loadConfig(rootDir);
   const comparisonBase = options.base ? options.base : options.workflow === "truthmark-sync" ? await selectComparisonBase(rootDir) : null;
   const impactSet = comparisonBase ? await buildImpactSet(rootDir, { base: comparisonBase }) : null;
-  const checkResult = await runCheck(cwd, comparisonBase ? { base: comparisonBase } : {});
+  const checkResult = await runCheck(
+    cwd,
+    comparisonBase ? { base: comparisonBase } : {}
+  );
   const diagnostics = [
     ...loadResult.diagnostics,
     ...repoIndex.diagnostics,
     ...impactSet?.diagnostics ?? [],
     ...checkResult.diagnostics
   ];
-  const applicability = applicabilityFor(options.workflow, diagnostics, impactSet);
-  const actionData = applicability.state === "blocked" || applicability.state === "ambiguous" ? {} : contextDataFor(options.workflow, repoIndex, loadResult.config, impactSet);
+  const applicability = applicabilityFor(
+    options.workflow,
+    diagnostics,
+    impactSet
+  );
+  const actionData = applicability.state === "needs_manual_review" || applicability.state === "needs_routing_review" ? {} : contextDataFor(
+    options.workflow,
+    repoIndex,
+    loadResult.config,
+    impactSet
+  );
   return {
     schemaVersion: "truthmark-workflow/v0",
     workflow: options.workflow,
     applicability,
     actionContext: buildWorkflowActionContext(manifestEntry, actionData),
+    workflowCard: workflowCardFor(
+      options.workflow,
+      applicability,
+      diagnostics,
+      impactSet
+    ),
     changedFiles: impactSet?.changedFiles ?? [],
     affectedRoutes: impactSet?.affectedRoutes ?? [],
-    targetTruthDocs: applicability.state === "ambiguous" ? [] : impactSet?.affectedTruthDocs ?? [],
+    targetTruthDocs: applicability.state === "needs_routing_review" ? [] : impactSet?.affectedTruthDocs ?? [],
     diagnostics,
     checks: {
-      required: [...manifestEntry.requiredGates],
+      reviewChecklist: [...manifestEntry.reviewQuestions],
       recommended: [...manifestEntry.positiveTriggers],
       helpers: helperCommandsFor2(options.workflow),
       affectedTests: impactSet?.affectedTests ?? []
@@ -7903,7 +8111,7 @@ var buildWorkflowState = async (cwd, options) => {
 };
 
 // src/cli/handlers.ts
-import fs21 from "fs/promises";
+import fs20 from "fs/promises";
 
 // src/agents/workflow-helper-validation.ts
 import { parse as parseYaml2 } from "yaml";
@@ -7965,7 +8173,6 @@ var validateEvidenceChecked = (text, errors, checks) => {
 };
 var validateHelperScriptEntries = (entries, requiredHelpers, errors, checks) => {
   if (entries === void 0 || entries.length === 0) {
-    errors.push("Helper scripts must include status for optional helpers");
     return;
   }
   const statusPattern = /^(?:-\s*)?([a-z0-9-]+):\s*(?:ran,\s*passed|skipped,\s*\S.*)$/iu;
@@ -7985,7 +8192,7 @@ var validateHelperScriptEntries = (entries, requiredHelpers, errors, checks) =>
       errors.push(`missing Helper scripts status: ${helperId}`);
     }
   }
-  if (errors.length === 0) {
+  if (errors.length === 0 && requiredHelpers.length > 0) {
     checks.push(`Helper scripts statuses include ${requiredHelpers.join(", ")}`);
   }
 };
@@ -8014,6 +8221,7 @@ var validateTruthSyncReportText = (text) => {
         ["Changed code reviewed", report.changedCode],
         ["Ownership reviewed", report.ownershipReviewed],
         ["Truth docs updated", report.truthDocsUpdated],
+        ["Decision/rationale captured", report.decisionRationaleCaptured],
         ["Notes", report.notes]
       ]) {
         if (items.length === 0) {
@@ -8029,12 +8237,10 @@ var validateTruthSyncReportText = (text) => {
           "Evidence checked entries include Claim:, Evidence:, and Result: supported | narrowed | removed | blocked"
         );
       }
-      validateHelperScriptEntries(
-        report.helperScripts,
-        ["validate-write-lease"],
-        errors,
-        checks
-      );
+      if (report.syncIntent !== void 0) {
+        checks.push("Sync Intent");
+      }
+      validateHelperScriptEntries(report.helperScripts, [], errors, checks);
     } catch (error) {
       errors.push(error instanceof Error ? error.message : "invalid Truth Sync report");
     }
@@ -8069,11 +8275,6 @@ var validateTruthDocumentReportText = (text) => {
     } else {
       errors.push("missing required section: Evidence checked");
     }
-    if (hasLabel(text, "Helper scripts")) {
-      checks.push("Helper scripts");
-    } else {
-      errors.push("missing required section: Helper scripts");
-    }
     const truthDocsUpdated = getSection(text, "Truth docs updated");
     const truthDocsCreated = getSection(text, "Truth docs created");
     if (truthDocsUpdated === null && truthDocsCreated === null) {
@@ -8086,7 +8287,7 @@ var validateTruthDocumentReportText = (text) => {
       checks.push("Truth docs updated or created");
     }
     validateEvidenceChecked(text, errors, checks);
-    validateHelperScripts(text, ["validate-write-lease"], errors, checks);
+    validateHelperScripts(text, [], errors, checks);
   } else if (status === "blocked") {
     requireBulletSection(text, "Reason", errors, checks);
   }
@@ -8284,7 +8485,7 @@ var invalidWorkflowResult = (command, workflow) => ({
 });
 var readHelperFile = async (filePath, helper) => {
   try {
-    return await fs21.readFile(filePath, "utf8");
+    return await fs20.readFile(filePath, "utf8");
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     return { ok: false, helper, errors: [`could not read file: ${message}`] };