truthmark 2.1.0 → 2.2.1

package/dist/main.js

@@ -284,38 +284,11 @@ var truthmarkConfigSchema = {
     truthmark: {
       type: "object",
       additionalProperties: false,
-      required: ["workspace", "routes", "truth", "templates", "generated"],
+      required: ["workspace", "generated"],
       properties: {
         workspace: {
           type: "string"
         },
-        routes: {
-          type: "object",
-          additionalProperties: false,
-          required: ["index", "areas", "default_area", "max_delegation_depth"],
-          properties: {
-            index: { type: "string" },
-            areas: { type: "string" },
-            default_area: { type: "string" },
-            max_delegation_depth: { type: "integer", const: 1 }
-          }
-        },
-        truth: {
-          type: "object",
-          additionalProperties: false,
-          required: ["root"],
-          properties: {
-            root: { type: "string" }
-          }
-        },
-        templates: {
-          type: "object",
-          additionalProperties: false,
-          required: ["root"],
-          properties: {
-            root: { type: "string" }
-          }
-        },
         generated: {
           type: "object",
           additionalProperties: false,
@@ -375,33 +348,29 @@ var truthmarkConfigSchema = {
 // src/config/defaults.ts
 var DEFAULT_TRUTHMARK_WORKSPACE = {
   workspace: "docs/truthmark",
-  routes: {
-    index: "routes/areas.md",
-    areas: "routes/areas",
-    default_area: "repository",
-    max_delegation_depth: 1
-  },
-  truth: {
-    root: "truth"
-  },
-  templates: {
-    root: "templates"
-  },
   generated: {
     portal: {
       enabled: false
     }
   }
 };
+var DERIVED_TRUTHMARK_PATHS = {
+  routesIndex: "routes/areas.md",
+  routeAreasRoot: "routes/areas",
+  defaultArea: "repository",
+  maxDelegationDepth: 1,
+  productTruthRoot: "product",
+  engineeringTruthRoot: "engineering",
+  templatesRoot: "templates",
+  portalOutput: "generated/portal",
+  portalTemplate: "templates/portal.html"
+};
 var DEFAULT_INSTRUCTION_TARGETS = ["AGENTS.md"];
 var createDefaultRawConfig = () => ({
   version: 2,
   platforms: [...DEFAULT_PLATFORMS],
   truthmark: {
     workspace: DEFAULT_TRUTHMARK_WORKSPACE.workspace,
-    routes: { ...DEFAULT_TRUTHMARK_WORKSPACE.routes },
-    truth: { ...DEFAULT_TRUTHMARK_WORKSPACE.truth },
-    templates: { ...DEFAULT_TRUTHMARK_WORKSPACE.templates },
     generated: {
       portal: { ...DEFAULT_TRUTHMARK_WORKSPACE.generated.portal }
     }
@@ -409,7 +378,7 @@ var createDefaultRawConfig = () => ({
   instruction_targets: [...DEFAULT_INSTRUCTION_TARGETS],
   frontmatter: {
     required: [],
-    recommended: ["status", "doc_type", "last_reviewed", "source_of_truth"]
+    recommended: ["status", "last_reviewed"]
   },
   ignore: ["node_modules/**", "vendor/**", "dist/**", "build/**"]
 });
@@ -419,20 +388,24 @@ var createDefaultConfig = () => ({
   truthmark: {
     workspace: DEFAULT_TRUTHMARK_WORKSPACE.workspace,
     routes: {
-      index: DEFAULT_TRUTHMARK_WORKSPACE.routes.index,
-      areas: DEFAULT_TRUTHMARK_WORKSPACE.routes.areas,
-      defaultArea: DEFAULT_TRUTHMARK_WORKSPACE.routes.default_area,
-      maxDelegationDepth: DEFAULT_TRUTHMARK_WORKSPACE.routes.max_delegation_depth
+      index: DERIVED_TRUTHMARK_PATHS.routesIndex,
+      areas: DERIVED_TRUTHMARK_PATHS.routeAreasRoot,
+      defaultArea: DERIVED_TRUTHMARK_PATHS.defaultArea,
+      maxDelegationDepth: DERIVED_TRUTHMARK_PATHS.maxDelegationDepth
+    },
+    truth: {
+      productRoot: DERIVED_TRUTHMARK_PATHS.productTruthRoot,
+      engineeringRoot: DERIVED_TRUTHMARK_PATHS.engineeringTruthRoot
     },
-    truth: { root: DEFAULT_TRUTHMARK_WORKSPACE.truth.root },
-    templates: { root: DEFAULT_TRUTHMARK_WORKSPACE.templates.root },
+    templates: { root: DERIVED_TRUTHMARK_PATHS.templatesRoot },
     generated: {
       portal: { ...DEFAULT_TRUTHMARK_WORKSPACE.generated.portal }
     },
     paths: {
       routesIndex: "docs/truthmark/routes/areas.md",
       routeAreasRoot: "docs/truthmark/routes/areas",
-      truthRoot: "docs/truthmark/truth",
+      productTruthRoot: "docs/truthmark/product",
+      engineeringTruthRoot: "docs/truthmark/engineering",
       templatesRoot: "docs/truthmark/templates",
       portalOutput: "docs/truthmark/generated/portal",
       portalTemplate: "docs/truthmark/templates/portal.html"
@@ -440,14 +413,15 @@ var createDefaultConfig = () => ({
     controlledPaths: [
       "docs/truthmark/routes/areas.md",
       "docs/truthmark/routes/areas/**/*.md",
-      "docs/truthmark/truth/**/*.md",
+      "docs/truthmark/product/**/*.md",
+      "docs/truthmark/engineering/**/*.md",
       "docs/truthmark/templates/*.md"
     ]
   },
   instructionTargets: [...DEFAULT_INSTRUCTION_TARGETS],
   frontmatter: {
     required: [],
-    recommended: ["status", "doc_type", "last_reviewed", "source_of_truth"]
+    recommended: ["status", "last_reviewed"]
   },
   ignore: ["node_modules/**", "vendor/**", "dist/**", "build/**"]
 });
@@ -455,14 +429,23 @@ var createDefaultConfig = () => ({
 // src/routing/areas.ts
 import { parse } from "yaml";
 var TRUTH_DOCUMENT_KINDS = [
-  "behavior",
-  "contract",
-  "architecture",
-  "workflow",
-  "operations",
-  "test-behavior"
+  "product-capability",
+  "engineering-behavior",
+  "engineering-contract",
+  "engineering-workflow",
+  "engineering-architecture",
+  "engineering-operations",
+  "engineering-test-behavior"
 ];
-var DEFAULT_WORKSPACE_TRUTH_DOCS_ROOT = "docs/truthmark/truth";
+var uniqueSorted = (values) => [...new Set(values)].sort();
+var mergeTruthDocumentEntryRelationships = (first, second) => ({
+  ...first,
+  realizedBy: uniqueSorted([...first.realizedBy, ...second.realizedBy]),
+  realizes: uniqueSorted([...first.realizes, ...second.realizes]),
+  dependsOn: uniqueSorted([...first.dependsOn, ...second.dependsOn])
+});
+var DEFAULT_PRODUCT_TRUTH_DOCS_ROOT = "docs/truthmark/product";
+var DEFAULT_ENGINEERING_TRUTH_DOCS_ROOT = "docs/truthmark/engineering";
 var slugify = (value) => {
   return value.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 };
@@ -482,12 +465,54 @@ var isTruthDocumentKind = (value) => {
 };
 var inferTruthDocumentKindFromPath = (documentPath, options = {}) => {
   const normalizedPath = documentPath.replaceAll("\\", "/");
-  const truthDocsRoot = (options.truthDocsRoot ?? DEFAULT_WORKSPACE_TRUTH_DOCS_ROOT)?.replaceAll("\\", "/").replace(/\/+$/u, "");
-  if (truthDocsRoot && normalizedPath.startsWith(`${truthDocsRoot}/`)) {
-    return "behavior";
+  const productTruthRoot = (options.productTruthRoot ?? DEFAULT_PRODUCT_TRUTH_DOCS_ROOT)?.replaceAll("\\", "/").replace(/\/+$/u, "");
+  const engineeringTruthRoot = (options.engineeringTruthRoot ?? options.truthDocsRoot ?? DEFAULT_ENGINEERING_TRUTH_DOCS_ROOT)?.replaceAll("\\", "/").replace(/\/+$/u, "");
+  if (productTruthRoot && normalizedPath.startsWith(`${productTruthRoot}/`)) {
+    return "product-capability";
+  }
+  if (engineeringTruthRoot && normalizedPath.startsWith(`${engineeringTruthRoot}/`)) {
+    if (normalizedPath.includes("/contracts/")) return "engineering-contract";
+    if (normalizedPath.includes("/workflows/")) return "engineering-workflow";
+    if (normalizedPath.includes("/architecture/"))
+      return "engineering-architecture";
+    if (normalizedPath.includes("/operations/"))
+      return "engineering-operations";
+    if (normalizedPath.includes("/tests/")) return "engineering-test-behavior";
+    return "engineering-behavior";
+  }
+  return null;
+};
+var inferTruthDocumentLaneFromPath = (documentPath, options = {}) => {
+  const normalizedPath = documentPath.replaceAll("\\", "/");
+  const productTruthRoot = (options.productTruthRoot ?? DEFAULT_PRODUCT_TRUTH_DOCS_ROOT).replaceAll("\\", "/").replace(/\/+$/u, "");
+  const engineeringTruthRoot = (options.engineeringTruthRoot ?? options.truthDocsRoot ?? DEFAULT_ENGINEERING_TRUTH_DOCS_ROOT).replaceAll("\\", "/").replace(/\/+$/u, "");
+  if (normalizedPath.startsWith(`${productTruthRoot}/`)) {
+    return "product";
+  }
+  if (normalizedPath.startsWith(`${engineeringTruthRoot}/`)) {
+    return "engineering";
   }
   return null;
 };
+var laneForTruthDocumentKind = (kind) => {
+  return kind.startsWith("product-") ? "product" : "engineering";
+};
+var docTypeForTruthDocumentKind = (kind) => {
+  if (kind.startsWith("product-")) {
+    return "product";
+  }
+  return kind.slice("engineering-".length);
+};
+var parseStringListField = (rawEntry, field) => {
+  if (!rawEntry || typeof rawEntry !== "object" || !(field in rawEntry)) {
+    return [];
+  }
+  const value = rawEntry[field];
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.filter((entry) => typeof entry === "string");
+};
 var findTruthDocumentsYamlFenceRange = (sectionLines) => {
   const trimmedLines = sectionLines.map((line) => line.trim());
   const openingFenceIndex = trimmedLines.findIndex(
@@ -509,6 +534,7 @@ var parseTruthDocumentsFromList = (sectionLines, areaName, options) => {
   const truthDocuments = parseListSection(sectionLines);
   const truthDocumentEntries = truthDocuments.map((documentPath) => {
     const inferredKind = inferTruthDocumentKindFromPath(documentPath, options);
+    const inferredLane = inferTruthDocumentLaneFromPath(documentPath, options);
     if (!inferredKind) {
       diagnostics.push(
         createAreaDiagnostic(
@@ -520,8 +546,13 @@ var parseTruthDocumentsFromList = (sectionLines, areaName, options) => {
     }
     return {
       path: documentPath,
-      kind: inferredKind ?? "behavior",
-      kindSource: inferredKind ? "inferred" : "defaulted"
+      kind: inferredKind ?? "engineering-behavior",
+      kindSource: inferredKind ? "inferred" : "defaulted",
+      lane: inferredLane ?? "engineering",
+      laneSource: inferredLane ? "inferred" : "defaulted",
+      realizedBy: [],
+      realizes: [],
+      dependsOn: []
     };
   });
   return {
@@ -530,7 +561,7 @@ var parseTruthDocumentsFromList = (sectionLines, areaName, options) => {
     diagnostics
   };
 };
-var parseTruthDocumentsFromYaml = (sectionLines, areaName) => {
+var parseTruthDocumentsFromYaml = (sectionLines, areaName, options) => {
   const yamlFenceRange = findTruthDocumentsYamlFenceRange(sectionLines);
   if (!yamlFenceRange) {
     return {
@@ -587,21 +618,31 @@ var parseTruthDocumentsFromYaml = (sectionLines, areaName) => {
   const diagnostics = [];
   const truthDocumentEntries = [];
   for (const rawEntry of rawEntries) {
-    const path13 = rawEntry && typeof rawEntry === "object" && "path" in rawEntry ? rawEntry.path : null;
+    const path12 = rawEntry && typeof rawEntry === "object" && "path" in rawEntry ? rawEntry.path : null;
     const kind = rawEntry && typeof rawEntry === "object" && "kind" in rawEntry ? rawEntry.kind : null;
-    if (typeof path13 !== "string" || path13.trim().length === 0 || !isTruthDocumentKind(kind)) {
+    const lane = rawEntry && typeof rawEntry === "object" && "lane" in rawEntry ? rawEntry.lane : null;
+    const inferredKind = typeof path12 === "string" ? inferTruthDocumentKindFromPath(path12, options) : null;
+    const inferredLane = typeof path12 === "string" ? inferTruthDocumentLaneFromPath(path12, options) : null;
+    const normalizedKind = isTruthDocumentKind(kind) ? kind : inferredKind;
+    const normalizedLane = lane === "product" || lane === "engineering" ? lane : normalizedKind ? laneForTruthDocumentKind(normalizedKind) : inferredLane;
+    if (typeof path12 !== "string" || path12.trim().length === 0 || !normalizedKind || !normalizedLane) {
       diagnostics.push(
         createAreaDiagnostic(
-          `Area ${areaName} truth_documents entries must include non-empty path and valid kind fields.`,
+          `Area ${areaName} truth_documents entries must include non-empty path plus valid lane and kind fields.`,
           areaName
         )
       );
       continue;
     }
     truthDocumentEntries.push({
-      path: path13.trim(),
-      kind,
-      kindSource: "explicit"
+      path: path12.trim(),
+      kind: normalizedKind,
+      kindSource: isTruthDocumentKind(kind) ? "explicit" : "inferred",
+      lane: normalizedLane,
+      laneSource: lane === "product" || lane === "engineering" ? "explicit" : "inferred",
+      realizedBy: parseStringListField(rawEntry, "realized_by"),
+      realizes: parseStringListField(rawEntry, "realizes"),
+      dependsOn: parseStringListField(rawEntry, "depends_on")
     });
   }
   return {
@@ -615,7 +656,11 @@ var parseTruthDocumentsSection = (sectionLines, areaName, options) => {
   if (!yamlFenceRange) {
     return parseTruthDocumentsFromList(sectionLines, areaName, options);
   }
-  const yamlResult = parseTruthDocumentsFromYaml(sectionLines, areaName);
+  const yamlResult = parseTruthDocumentsFromYaml(
+    sectionLines,
+    areaName,
+    options
+  );
   if (yamlResult.diagnostics.length > 0 || yamlFenceRange.closingFenceIndex === null) {
     return yamlResult;
   }
@@ -697,8 +742,9 @@ var parseAreasMarkdown = (source, options = {}) => {
   for (const line of lines) {
     const areaHeadingMatch = line.match(/^\s{0,3}##\s+(.*)$/u);
     if (areaHeadingMatch) {
+      const heading = areaHeadingMatch[1]?.trim() ?? null;
       flushArea();
-      currentAreaName = areaHeadingMatch[1]?.trim() ?? null;
+      currentAreaName = heading === "Source References" ? null : heading;
       continue;
     }
     if (!currentAreaName) {
@@ -726,7 +772,13 @@ var parseAreasMarkdown = (source, options = {}) => {
 
 // src/truth/docs.ts
 var resolveTruthDocsRoot = (config) => {
-  return config.truthmark.paths.truthRoot;
+  return config.truthmark.paths.engineeringTruthRoot;
+};
+var resolveProductTruthRoot = (config) => {
+  return config.truthmark.paths.productTruthRoot;
+};
+var resolveEngineeringTruthRoot = (config) => {
+  return config.truthmark.paths.engineeringTruthRoot;
 };
 
 // src/templates/init-files.ts
@@ -737,7 +789,25 @@ var currentDate = () => (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
 var resolveRelativePath = (fromPath, toPath) => {
   return asRelativePath(path3.relative(path3.dirname(fromPath), toPath));
 };
-var truthRoot = resolveTruthDocsRoot;
+var truthRoot = resolveEngineeringTruthRoot;
+var renderLaneRootReadmeSummary = (lane) => {
+  if (lane === "product") {
+    return [
+      "Product truth owns capability promises, boundaries, decisions, and acceptance criteria.",
+      "Product lane docs state what must be true, why it matters, and what success means."
+    ].join(" ");
+  }
+  return [
+    "Engineering truth owns current realization, contracts, architecture, workflows, operations, and tests.",
+    "Engineering lane docs describe how the repository currently implements and operates the behavior."
+  ].join(" ");
+};
+var renderLaneRootLeafDocGuidance = (lane) => {
+  if (lane === "product") {
+    return "README.md files are indexes, not Truth Sync targets. Keep product truth in bounded capability docs.";
+  }
+  return "README.md files are indexes, not Truth Sync targets. Keep engineering truth in bounded behavior, contract, architecture, workflow, operations, and test docs.";
+};
 var renderConfigTemplate = () => {
   return stringify(createDefaultRawConfig());
 };
@@ -757,8 +827,6 @@ var renderHierarchicalAreasIndexTemplate = (config) => {
     "status: active",
     "doc_type: route-index",
     `last_reviewed: ${currentDate()}`,
-    "source_of_truth:",
-    `  - ${sourceOfTruth}`,
     "---",
     "",
     "# Truthmark Areas",
@@ -774,6 +842,10 @@ var renderHierarchicalAreasIndexTemplate = (config) => {
     "Update truth when:",
     "- behavior changes affect the routed truth documents",
     "- API contracts or current feature behavior changes",
+    "",
+    "## Source References",
+    "",
+    `- ${sourceOfTruth}`,
     ""
   ].join("\n");
 };
@@ -783,14 +855,15 @@ var renderChildAreaTemplate = (config) => {
   const truthDocsRoot = truthRoot(config);
   const leafTruthDoc = `${truthDocsRoot}/${defaultArea}/overview.md`;
   const templatePath = `${config.truthmark.paths.routeAreasRoot}/${defaultArea}.md`;
-  const sourceOfTruth = resolveRelativePath(templatePath, ".truthmark/config.yml");
+  const sourceOfTruth = resolveRelativePath(
+    templatePath,
+    ".truthmark/config.yml"
+  );
   return [
     "---",
     "status: active",
     "doc_type: area-route",
     `last_reviewed: ${currentDate()}`,
-    "source_of_truth:",
-    `  - ${sourceOfTruth}`,
     "---",
     "",
     `# ${title} Areas`,
@@ -801,7 +874,8 @@ var renderChildAreaTemplate = (config) => {
     "```yaml",
     "truth_documents:",
     `  - path: ${leafTruthDoc}`,
-    "    kind: behavior",
+    "    kind: engineering-behavior",
+    "    lane: engineering",
     "```",
     "",
     "Code surface:",
@@ -809,11 +883,15 @@ var renderChildAreaTemplate = (config) => {
     "",
     "Update truth when:",
     "- behavior changes affect repository truth",
+    "",
+    "## Source References",
+    "",
+    `- ${sourceOfTruth}`,
     ""
   ].join("\n");
 };
-var renderTruthRootReadmeTemplate = (config = createDefaultConfig()) => {
-  const templatePath = `${truthRoot(config)}/README.md`;
+var renderTruthRootReadmeTemplate = (config = createDefaultConfig(), lane = "engineering") => {
+  const templatePath = `${lane === "product" ? resolveProductTruthRoot(config) : resolveEngineeringTruthRoot(config)}/README.md`;
   const sourceOfTruth = resolveRelativePath(
     templatePath,
     config.truthmark.paths.routesIndex
@@ -823,15 +901,19 @@ var renderTruthRootReadmeTemplate = (config = createDefaultConfig()) => {
     "status: active",
     "doc_type: index",
     `last_reviewed: ${currentDate()}`,
-    "source_of_truth:",
-    `  - ${sourceOfTruth}`,
     "---",
     "",
     "# Truth Docs",
     "",
     "This directory is an index for current truth docs organized by the configured Truthmark hierarchy.",
     "",
-    "README.md files are indexes, not Truth Sync targets. Keep bounded truth in leaf docs under `<domain>/<behavior>.md`.",
+    renderLaneRootReadmeSummary(lane),
+    "",
+    renderLaneRootLeafDocGuidance(lane),
+    "",
+    "## Source References",
+    "",
+    `- ${sourceOfTruth}`,
     ""
   ].join("\n");
 };
@@ -848,8 +930,6 @@ var renderTruthDomainReadmeTemplate = (config) => {
     "status: active",
     "doc_type: index",
     `last_reviewed: ${currentDate()}`,
-    "source_of_truth:",
-    `  - ${sourceOfTruth}`,
     "---",
     "",
     `# ${title} Truth Docs`,
@@ -861,10 +941,14 @@ var renderTruthDomainReadmeTemplate = (config) => {
     "Current leaf docs:",
     "",
     "- [Overview](overview.md)",
+    "",
+    "## Source References",
+    "",
+    `- ${sourceOfTruth}`,
     ""
   ].join("\n");
 };
-var BEHAVIOR_DOC_TEMPLATE_PATH = "docs/truthmark/templates/behavior-doc.md";
+var BEHAVIOR_DOC_TEMPLATE_PATH = "docs/truthmark/templates/engineering-behavior.md";
 var renderTemplateSection = (section) => {
   return [
     section.heading,
@@ -928,24 +1012,68 @@ var parseTemplateSections = (template) => {
     sections
   };
 };
+var LEGACY_MANAGED_TEMPLATE_HEADINGS = /* @__PURE__ */ new Map([
+  ["## Current Behavior", "## Current Implementation Behavior"],
+  ["## Source Evidence", "## Source References"]
+]);
+var resolveManagedTemplateHeading = (heading) => {
+  return LEGACY_MANAGED_TEMPLATE_HEADINGS.get(heading) ?? heading;
+};
+var stripManagedFrontmatterFields = (preamble) => {
+  if (!preamble.startsWith("---\n")) {
+    return preamble;
+  }
+  const lines = preamble.split("\n");
+  const closingIndex = lines.findIndex(
+    (line, index) => index > 0 && line.trim() === "---"
+  );
+  if (closingIndex < 0) {
+    return preamble;
+  }
+  const fieldsToRemove = /* @__PURE__ */ new Set(["source_of_truth", "doc_type", "truth_lane"]);
+  const keptFrontmatterLines = [];
+  let skippingManagedField = false;
+  for (const line of lines.slice(1, closingIndex)) {
+    const keyMatch = /^([A-Za-z0-9_-]+):(\s|$)/u.exec(line);
+    if (keyMatch) {
+      skippingManagedField = fieldsToRemove.has(keyMatch[1] ?? "");
+    }
+    if (!skippingManagedField) {
+      keptFrontmatterLines.push(line);
+    }
+  }
+  return [
+    "---",
+    ...keptFrontmatterLines,
+    "---",
+    ...lines.slice(closingIndex + 1)
+  ].join("\n").trimEnd();
+};
 var mergeTruthDocTemplate = (existingTemplate, defaultTemplate) => {
   if (existingTemplate.trim().length === 0) {
     return defaultTemplate;
   }
   const defaultParsed = parseTemplateSections(defaultTemplate);
   const existingParsed = parseTemplateSections(existingTemplate);
-  const defaultHeadings = new Set(defaultParsed.sections.map((section) => section.heading));
+  const defaultHeadings = new Set(
+    defaultParsed.sections.map((section) => section.heading)
+  );
   const customBeforeDefault = /* @__PURE__ */ new Map();
   const trailingCustomSections = [];
   existingParsed.sections.forEach((section, index) => {
-    if (defaultHeadings.has(section.heading)) {
+    if (defaultHeadings.has(resolveManagedTemplateHeading(section.heading))) {
       return;
     }
-    const nextDefaultSection = existingParsed.sections.slice(index + 1).find((candidate) => defaultHeadings.has(candidate.heading));
+    const nextDefaultSection = existingParsed.sections.slice(index + 1).find(
+      (candidate) => defaultHeadings.has(resolveManagedTemplateHeading(candidate.heading))
+    );
     if (nextDefaultSection) {
-      const bucket = customBeforeDefault.get(nextDefaultSection.heading) ?? [];
+      const nextDefaultHeading = resolveManagedTemplateHeading(
+        nextDefaultSection.heading
+      );
+      const bucket = customBeforeDefault.get(nextDefaultHeading) ?? [];
       bucket.push(section);
-      customBeforeDefault.set(nextDefaultSection.heading, bucket);
+      customBeforeDefault.set(nextDefaultHeading, bucket);
       return;
     }
     trailingCustomSections.push(section);
@@ -955,7 +1083,7 @@ var mergeTruthDocTemplate = (existingTemplate, defaultTemplate) => {
     section
   ]);
   return [
-    existingParsed.preamble,
+    stripManagedFrontmatterFields(existingParsed.preamble),
     ...mergedSections.map((section) => section.block),
     ...trailingCustomSections.map((section) => section.block),
     ""
@@ -965,11 +1093,8 @@ var renderBehaviorDocTemplateFile = () => {
   return [
     "---",
     "status: active",
-    "doc_type: behavior",
-    "truth_kind: behavior",
+    "truth_kind: engineering-behavior",
     `last_reviewed: ${currentDate()}`,
-    "source_of_truth:",
-    "  - {{source_of_truth}}",
     "---",
     "",
     "# {{title}}",
@@ -979,7 +1104,7 @@ var renderBehaviorDocTemplateFile = () => {
     "<!--",
     "State the user/system outcome this behavior protects and why it exists.",
     "Include the problem boundary and durable value; exclude roadmap, implementation plan, and historical narrative.",
-    "List the code, config, docs, or tests that support the claim in source_of_truth rather than prose-only assertion.",
+    "List the code, config, docs, or tests that support the claim in Source References rather than prose-only assertion.",
     "-->",
     "",
     "{{purpose}}",
@@ -995,17 +1120,17 @@ var renderBehaviorDocTemplateFile = () => {
     "",
     "{{scope}}",
     "",
-    "This doc was created from the editable behavior-doc template at {{template_path}}.",
+    "This doc was created from the editable engineering-behavior template at {{template_path}}.",
     "",
-    "## Current Behavior",
+    "## Current Implementation Behavior",
     "",
     "<!--",
     "Describe only current implemented behavior in present tense.",
     "Cover observable behavior, important defaults, and user/system-visible effects; exclude desired future behavior and speculative design.",
-    "Every non-obvious claim should be checkable from source_of_truth evidence.",
+    "Every non-obvious claim should be checkable from Source References.",
     "-->",
     "",
-    "{{current_behavior}}",
+    "{{current_implementation_behavior}}",
     "",
     "## Core Rules",
     "",
@@ -1034,14 +1159,23 @@ var renderBehaviorDocTemplateFile = () => {
     "",
     "{{contracts}}",
     "",
-    "## Product Decisions",
+    "## Product Truth Links",
+    "",
+    "<!--",
+    "List product truth docs this engineering doc realizes; author canonical realizes links in route YAML, not doc frontmatter.",
+    "Use 'None.' when this is purely internal engineering behavior.",
+    "-->",
+    "",
+    "{{product_truth_links}}",
+    "",
+    "## Engineering Decisions",
     "",
     "<!--",
     "Keep active decisions only, dated inline when added or changed.",
     "Explain decisions that shape behavior, boundaries, rejected alternatives, or migration constraints; replace stale decisions instead of appending historical logs.",
     "-->",
     "",
-    "{{decision}}",
+    "{{engineering_decisions}}",
     "",
     "## Rationale",
     "",
@@ -1069,6 +1203,14 @@ var renderBehaviorDocTemplateFile = () => {
     "-->",
     "",
     "{{maintenance_notes}}",
+    "",
+    "## Source References",
+    "",
+    "<!--",
+    "List source files, tests, configs, generated templates, route files, or product instructions that support current claims.",
+    "-->",
+    "",
+    "{{source_references}}",
     ""
   ].join("\n");
 };
@@ -1076,17 +1218,30 @@ var sectionSpec = (heading, guidance, placeholder = titleToPlaceholder(heading))
 var PURPOSE_SECTION = sectionSpec("## Purpose", [
   "State the software-engineering outcome this document protects and why the documented surface exists.",
   "Include durable value, impacted users/systems, and the problem boundary; exclude roadmap, implementation plans, and historical narrative.",
-  "Keep claims traceable to source_of_truth evidence rather than prose-only assertion."
+  "Keep claims traceable to Source References rather than prose-only assertion."
 ]);
 var SCOPE_SECTION = sectionSpec("## Scope", [
   "Define the one coherent surface this document owns, including actors, entrypoints, owned state/data, and handoffs to neighboring truth docs.",
   "Call out important out-of-scope boundaries here or in Non-Goals; split the doc when it mixes distinct outcomes, lifecycles, contracts, or owners."
 ]);
-var PRODUCT_DECISIONS_SECTION = sectionSpec("## Product Decisions", [
-  "Keep active decisions only, dated inline when added or changed.",
-  "Capture decisions that shape behavior, interfaces, boundaries, compatibility, risk acceptance, or migration constraints.",
-  "Replace stale decisions instead of appending historical logs."
-], "decision");
+var PRODUCT_DECISIONS_SECTION = sectionSpec(
+  "## Product Decisions",
+  [
+    "Keep active decisions only, dated inline when added or changed.",
+    "Capture decisions that shape behavior, interfaces, boundaries, compatibility, risk acceptance, or migration constraints.",
+    "Replace stale decisions instead of appending historical logs."
+  ],
+  "decision"
+);
+var ENGINEERING_DECISIONS_SECTION = sectionSpec(
+  "## Engineering Decisions",
+  [
+    "Keep active engineering, architecture, contract, workflow, or operational decisions only, dated inline when added or changed.",
+    "Do not restate product promises, product rationale, or business decisions here; link product truth instead.",
+    "Replace stale decisions instead of appending historical logs."
+  ],
+  "engineering_decisions"
+);
 var RATIONALE_SECTION = sectionSpec("## Rationale", [
   "Explain why the current behavior, structure, or contract is this way, including tradeoffs and constraints.",
   "Tie rationale to evidence-backed facts and active decisions; do not use this as a changelog."
@@ -1099,15 +1254,19 @@ var MAINTENANCE_NOTES_SECTION = sectionSpec("## Maintenance Notes", [
   "List related tests, routing cautions, migration notes, compatibility risks, evidence drift risks, and review triggers for future maintainers or agents.",
   "Keep this operational and current-state focused, not historical."
 ]);
-var renderTypedTruthDocTemplate = (truthKind, docType, title, sections) => {
+var SOURCE_REFERENCES_SECTION = sectionSpec(
+  "## Source References",
+  [
+    "List source files, tests, configs, generated templates, route files, or product instructions that support current claims."
+  ],
+  "source_references"
+);
+var renderTypedTruthDocTemplate = (truthKind, title, sections) => {
   return [
     "---",
     "status: active",
-    `doc_type: ${docType}`,
     `truth_kind: ${truthKind}`,
     `last_reviewed: ${currentDate()}`,
-    "source_of_truth:",
-    "  - {{source_of_truth}}",
     "---",
     "",
     `# ${title}`,
@@ -1115,14 +1274,77 @@ var renderTypedTruthDocTemplate = (truthKind, docType, title, sections) => {
     ...renderTemplateSection(PURPOSE_SECTION),
     ...renderTemplateSection(SCOPE_SECTION),
     ...sections.flatMap(renderTemplateSection),
-    ...renderTemplateSection(PRODUCT_DECISIONS_SECTION),
+    ...renderTemplateSection(ENGINEERING_DECISIONS_SECTION),
     ...renderTemplateSection(RATIONALE_SECTION),
     ...renderTemplateSection(NON_GOALS_SECTION),
-    ...renderTemplateSection(MAINTENANCE_NOTES_SECTION)
+    ...renderTemplateSection(MAINTENANCE_NOTES_SECTION),
+    ...renderTemplateSection(SOURCE_REFERENCES_SECTION)
+  ].join("\n");
+};
+var CORE_LANE_INVARIANT = "Do not make product docs a summary of engineering docs. Do not make engineering docs a detailed version of product docs. Product truth says what must be true and why. Engineering truth says how the repository currently realizes it.";
+var renderProductTruthDocTemplate = (truthKind, title, sections, includeNonGoals) => {
+  return [
+    "---",
+    "status: active",
+    `truth_kind: ${truthKind}`,
+    `last_reviewed: ${currentDate()}`,
+    "---",
+    "",
+    `# ${title}`,
+    "",
+    "<!--",
+    CORE_LANE_INVARIANT,
+    "Product docs may cite code directly when code proves current product behavior, but keep implementation flow, renderer internals, CLI envelopes, and generated file inventories in engineering truth.",
+    "-->",
+    "",
+    ...sections.flatMap(renderTemplateSection),
+    ...renderTemplateSection(PRODUCT_DECISIONS_SECTION),
+    ...renderTemplateSection(
+      sectionSpec(
+        "## Engineering Realization Links",
+        [
+          "List engineering truth that realizes this product truth; author canonical realized_by links in route YAML, not doc frontmatter.",
+          "Do not summarize those engineering docs."
+        ],
+        "engineering_realization_links"
+      )
+    ),
+    ...includeNonGoals ? renderTemplateSection(NON_GOALS_SECTION) : [],
+    ...renderTemplateSection(SOURCE_REFERENCES_SECTION)
   ].join("\n");
 };
+var renderProductCapabilityDocTemplateFile = () => {
+  return renderProductTruthDocTemplate(
+    "product-capability",
+    "{{title}}",
+    [
+      sectionSpec("## Capability Promise", [
+        "State the single user-visible capability and what must be true for users or stakeholders.",
+        "Do not describe implementation mechanics here."
+      ]),
+      sectionSpec("## Users And Value", [
+        "Describe who benefits from the capability and the durable value it protects.",
+        "Tie claims to repository evidence, explicit user instruction, or current behavior."
+      ]),
+      sectionSpec("## Capability Scope", [
+        "Define what this capability includes and excludes, including product boundary constraints and adjacent systems.",
+        "Capture important scope limits, ownership boundaries, and non-goal pointers here; keep technical contracts in engineering truth."
+      ]),
+      sectionSpec("## Current Product Behavior", [
+        "Describe current implemented user-visible behavior in present tense.",
+        "Code files may appear in Source References when they directly prove current behavior."
+      ]),
+      sectionSpec("## Acceptance Criteria", [
+        "List observable criteria that show the capability promise is currently satisfied.",
+        "Include criteria that review whether the capability stays within its stated scope and boundary.",
+        "Use criteria that can be reviewed from repository evidence or explicit product instruction."
+      ])
+    ],
+    true
+  );
+};
 var renderContractDocTemplateFile = () => {
-  return renderTypedTruthDocTemplate("contract", "contract", "{{title}}", [
+  return renderTypedTruthDocTemplate("engineering-contract", "{{title}}", [
     sectionSpec("## Contract Surface", [
       "Identify the owned API, CLI, file format, event, protocol, permission boundary, or integration surface.",
       "State consumers/producers, stability level, and the source files/tests that define the contract."
@@ -1150,7 +1372,7 @@ var renderContractDocTemplateFile = () => {
   ]);
 };
 var renderArchitectureDocTemplateFile = () => {
-  return renderTypedTruthDocTemplate("architecture", "architecture", "{{title}}", [
+  return renderTypedTruthDocTemplate("engineering-architecture", "{{title}}", [
     sectionSpec("## System Role", [
       "Describe the current architectural role of this subsystem/component in the larger system.",
       "State the primary responsibilities, consumers, providers, and why this boundary exists now."
@@ -1178,7 +1400,7 @@ var renderArchitectureDocTemplateFile = () => {
   ]);
 };
 var renderWorkflowDocTemplateFile = () => {
-  return renderTypedTruthDocTemplate("workflow", "behavior", "{{title}}", [
+  return renderTypedTruthDocTemplate("engineering-workflow", "{{title}}", [
     sectionSpec("## Triggers", [
       "List events, commands, schedules, user actions, webhooks, or dependency signals that start this workflow.",
       "Include preconditions, authorization requirements, debounce/coalescing behavior, and disabled states when applicable."
@@ -1206,7 +1428,7 @@ var renderWorkflowDocTemplateFile = () => {
   ]);
 };
 var renderOperationsDocTemplateFile = () => {
-  return renderTypedTruthDocTemplate("operations", "behavior", "{{title}}", [
+  return renderTypedTruthDocTemplate("engineering-operations", "{{title}}", [
     sectionSpec("## Operational Surface", [
       "Describe what operators, maintainers, or automated systems can observe or control for this surface.",
       "Include commands, dashboards, alerts, runbooks, jobs, or operational APIs that define current operations."
@@ -1234,7 +1456,7 @@ var renderOperationsDocTemplateFile = () => {
   ]);
 };
 var renderTestBehaviorDocTemplateFile = () => {
-  return renderTypedTruthDocTemplate("test-behavior", "behavior", "{{title}}", [
+  return renderTypedTruthDocTemplate("engineering-test-behavior", "{{title}}", [
     sectionSpec("## Test Surface", [
       "Define the behavior, contract, architecture, or workflow surface these tests verify.",
       "Link the canonical truth docs and code paths the tests are meant to protect."
@@ -1279,18 +1501,19 @@ var renderBehaviorLeafDocTemplate = (config, template = renderBehaviorDocTemplat
     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_behavior: "- Document current behavior here when implementation changes make repository truth incomplete.",
-    decision: `- Decision (${today}): 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_of_truth: sourceOfTruth,
+    source_references: `- ${sourceOfTruth}`,
     template_path: BEHAVIOR_DOC_TEMPLATE_PATH,
     title: `${title} Overview`,
-    truth_kind: "behavior"
+    truth_kind: "engineering-behavior"
   });
 };
 
@@ -1399,8 +1622,7 @@ var isUnsafeRepoRelativePath = (value) => {
 var joinWorkspacePath = (workspace, childPath) => {
   return normalizeRepoRelativePath(`${workspace}/${childPath}`);
 };
-var portalOutputFor = (workspace) => joinWorkspacePath(workspace, "generated/portal");
-var portalTemplateFor = (templatesRoot) => joinWorkspacePath(templatesRoot, "portal.html");
+var portalOutputFor = (workspace) => joinWorkspacePath(workspace, DERIVED_TRUTHMARK_PATHS.portalOutput);
 var pathsOverlap = (left, right) => {
   const normalizedLeft = normalizeRepoRelativePath(left);
   const normalizedRight = normalizeRepoRelativePath(right);
@@ -1444,12 +1666,6 @@ var unsupportedShapeDiagnostics = (parsedConfig, configPath) => {
 var validateWorkspacePaths = (rawConfig, configPath) => {
   const diagnostics = [];
   const workspace = normalizeRepoRelativePath(rawConfig.truthmark.workspace);
-  const childPaths = [
-    ["truthmark.routes.index", rawConfig.truthmark.routes.index],
-    ["truthmark.routes.areas", rawConfig.truthmark.routes.areas],
-    ["truthmark.truth.root", rawConfig.truthmark.truth.root],
-    ["truthmark.templates.root", rawConfig.truthmark.templates.root]
-  ];
   if (isUnsafeRepoRelativePath(rawConfig.truthmark.workspace) || FORBIDDEN_WORKSPACE_OVERLAPS.some((forbidden) => pathsOverlap(workspace, forbidden))) {
     diagnostics.push(
       toConfigDiagnostic(
@@ -1458,33 +1674,6 @@ var validateWorkspacePaths = (rawConfig, configPath) => {
       )
     );
   }
-  for (const [name, value] of childPaths) {
-    if (isUnsafeRepoRelativePath(value)) {
-      diagnostics.push(
-        toConfigDiagnostic(
-          `${name} must be a non-empty path relative to truthmark.workspace without absolute or parent traversal segments.`,
-          configPath
-        )
-      );
-    }
-  }
-  const portalOutput = normalizeRepoRelativePath("generated/portal");
-  const controlledWorkspaceChildren = [
-    ["truthmark.routes.index", rawConfig.truthmark.routes.index],
-    ["truthmark.routes.areas", rawConfig.truthmark.routes.areas],
-    ["truthmark.truth.root", rawConfig.truthmark.truth.root],
-    ["truthmark.templates.root", rawConfig.truthmark.templates.root]
-  ];
-  for (const [name, value] of controlledWorkspaceChildren) {
-    if (pathsOverlap(portalOutput, value)) {
-      diagnostics.push(
-        toConfigDiagnostic(
-          `Truthmark Portal output ${portalOutputFor(workspace)} must not overlap ${name}; Portal output is generated and must stay outside controlled truth, routing, and template paths.`,
-          configPath
-        )
-      );
-    }
-  }
   for (const target of rawConfig.instruction_targets ?? DEFAULT_INSTRUCTION_TARGETS) {
     if (isUnsafeRepoRelativePath(target) || pathsOverlap(workspace, target)) {
       diagnostics.push(
@@ -1499,28 +1688,33 @@ var validateWorkspacePaths = (rawConfig, configPath) => {
 };
 var normalizeConfig = (rawConfig) => {
   const workspace = normalizeRepoRelativePath(rawConfig.truthmark.workspace);
-  const routesIndex = joinWorkspacePath(workspace, rawConfig.truthmark.routes.index);
-  const routeAreasRoot = joinWorkspacePath(workspace, rawConfig.truthmark.routes.areas);
-  const truthRoot3 = joinWorkspacePath(workspace, rawConfig.truthmark.truth.root);
-  const templatesRoot = joinWorkspacePath(workspace, rawConfig.truthmark.templates.root);
+  const routesIndex = joinWorkspacePath(workspace, DERIVED_TRUTHMARK_PATHS.routesIndex);
+  const routeAreasRoot = joinWorkspacePath(workspace, DERIVED_TRUTHMARK_PATHS.routeAreasRoot);
+  const productTruthRoot = joinWorkspacePath(workspace, DERIVED_TRUTHMARK_PATHS.productTruthRoot);
+  const engineeringTruthRoot = joinWorkspacePath(
+    workspace,
+    DERIVED_TRUTHMARK_PATHS.engineeringTruthRoot
+  );
+  const templatesRoot = joinWorkspacePath(workspace, DERIVED_TRUTHMARK_PATHS.templatesRoot);
   const portalOutput = portalOutputFor(workspace);
-  const portalTemplate = portalTemplateFor(templatesRoot);
+  const portalTemplate = joinWorkspacePath(workspace, DERIVED_TRUTHMARK_PATHS.portalTemplate);
   return {
     version: rawConfig.version,
     platforms: rawConfig.platforms ?? [...DEFAULT_PLATFORMS],
     truthmark: {
       workspace,
       routes: {
-        index: normalizeRepoRelativePath(rawConfig.truthmark.routes.index),
-        areas: normalizeRepoRelativePath(rawConfig.truthmark.routes.areas),
-        defaultArea: rawConfig.truthmark.routes.default_area,
-        maxDelegationDepth: rawConfig.truthmark.routes.max_delegation_depth
+        index: DERIVED_TRUTHMARK_PATHS.routesIndex,
+        areas: DERIVED_TRUTHMARK_PATHS.routeAreasRoot,
+        defaultArea: DERIVED_TRUTHMARK_PATHS.defaultArea,
+        maxDelegationDepth: DERIVED_TRUTHMARK_PATHS.maxDelegationDepth
       },
       truth: {
-        root: normalizeRepoRelativePath(rawConfig.truthmark.truth.root)
+        productRoot: DERIVED_TRUTHMARK_PATHS.productTruthRoot,
+        engineeringRoot: DERIVED_TRUTHMARK_PATHS.engineeringTruthRoot
       },
       templates: {
-        root: normalizeRepoRelativePath(rawConfig.truthmark.templates.root)
+        root: DERIVED_TRUTHMARK_PATHS.templatesRoot
       },
       generated: {
         portal: {
@@ -1530,7 +1724,8 @@ var normalizeConfig = (rawConfig) => {
       paths: {
         routesIndex,
         routeAreasRoot,
-        truthRoot: truthRoot3,
+        productTruthRoot,
+        engineeringTruthRoot,
         templatesRoot,
         portalOutput,
         portalTemplate
@@ -1538,7 +1733,8 @@ var normalizeConfig = (rawConfig) => {
       controlledPaths: [
         routesIndex,
         `${routeAreasRoot}/**/*.md`,
-        `${truthRoot3}/**/*.md`,
+        `${productTruthRoot}/**/*.md`,
+        `${engineeringTruthRoot}/**/*.md`,
         `${templatesRoot}/*.md`
       ]
     },
@@ -1624,8 +1820,18 @@ var loadConfig = async (rootDir) => {
 // src/init/hierarchy.ts
 import fs5 from "fs/promises";
 var truthRoot2 = resolveTruthDocsRoot;
+var BEHAVIOR_DOC_TEMPLATE_FILE_NAME = "engineering-behavior.md";
+var CONTRACT_DOC_TEMPLATE_FILE_NAME = "engineering-contract.md";
+var ARCHITECTURE_DOC_TEMPLATE_FILE_NAME = "engineering-architecture.md";
+var WORKFLOW_DOC_TEMPLATE_FILE_NAME = "engineering-workflow.md";
+var OPERATIONS_DOC_TEMPLATE_FILE_NAME = "engineering-operations.md";
+var TEST_BEHAVIOR_DOC_TEMPLATE_FILE_NAME = "engineering-test-behavior.md";
+var PRODUCT_CAPABILITY_DOC_TEMPLATE_FILE_NAME = "product-capability.md";
 var rootIndexReferencesChildRoute = async (rootDir, rootIndexPath, childRoutePath) => {
-  const rootIndexSource = await fs5.readFile(resolveRepoPath(rootDir, rootIndexPath), "utf8");
+  const rootIndexSource = await fs5.readFile(
+    resolveRepoPath(rootDir, rootIndexPath),
+    "utf8"
+  );
   const parsedRootIndex = parseAreasMarkdown(rootIndexSource);
   return parsedRootIndex.areaFileReferences.some(
     (areaReference) => areaReference.areaFiles.includes(childRoutePath)
@@ -1637,7 +1843,10 @@ var truthTemplatePath = (config, fileName) => {
 var readBehaviorDocTemplate = async (rootDir, config) => {
   try {
     return await fs5.readFile(
-      resolveRepoPath(rootDir, truthTemplatePath(config, "behavior-doc.md")),
+      resolveRepoPath(
+        rootDir,
+        truthTemplatePath(config, BEHAVIOR_DOC_TEMPLATE_FILE_NAME)
+      ),
       "utf8"
     );
   } catch (error) {
@@ -1648,12 +1857,22 @@ var readBehaviorDocTemplate = async (rootDir, config) => {
   }
 };
 var ensureOrUpdateTruthDocTemplate = async (rootDir, templatePath, defaultTemplate) => {
-  const seededResult = await ensureRepoFile(rootDir, templatePath, defaultTemplate);
+  const seededResult = await ensureRepoFile(
+    rootDir,
+    templatePath,
+    defaultTemplate
+  );
   if (seededResult.status !== "unchanged") {
     return seededResult;
   }
-  const existingTemplate = await fs5.readFile(resolveRepoPath(rootDir, templatePath), "utf8");
-  const mergedTemplate = mergeTruthDocTemplate(existingTemplate, defaultTemplate);
+  const existingTemplate = await fs5.readFile(
+    resolveRepoPath(rootDir, templatePath),
+    "utf8"
+  );
+  const mergedTemplate = mergeTruthDocTemplate(
+    existingTemplate,
+    defaultTemplate
+  );
   return writeRepoFile(rootDir, templatePath, mergedTemplate);
 };
 var scaffoldHierarchy = async (rootDir, config) => {
@@ -1668,14 +1887,31 @@ var scaffoldHierarchy = async (rootDir, config) => {
       renderHierarchicalAreasIndexTemplate(config)
     )
   );
-  if (await rootIndexReferencesChildRoute(rootDir, config.truthmark.paths.routesIndex, childRoutePath)) {
-    results.push(await ensureRepoFile(rootDir, childRoutePath, renderChildAreaTemplate(config)));
+  if (await rootIndexReferencesChildRoute(
+    rootDir,
+    config.truthmark.paths.routesIndex,
+    childRoutePath
+  )) {
+    results.push(
+      await ensureRepoFile(
+        rootDir,
+        childRoutePath,
+        renderChildAreaTemplate(config)
+      )
+    );
   }
   results.push(
     await ensureRepoFile(
       rootDir,
-      `${truthDocsRoot}/README.md`,
-      renderTruthRootReadmeTemplate(config)
+      `${resolveEngineeringTruthRoot(config)}/README.md`,
+      renderTruthRootReadmeTemplate(config, "engineering")
+    )
+  );
+  results.push(
+    await ensureRepoFile(
+      rootDir,
+      `${config.truthmark.paths.productTruthRoot}/README.md`,
+      renderTruthRootReadmeTemplate(config, "product")
     )
   );
   results.push(
@@ -1688,45 +1924,52 @@ var scaffoldHierarchy = async (rootDir, config) => {
   results.push(
     await ensureOrUpdateTruthDocTemplate(
       rootDir,
-      truthTemplatePath(config, "behavior-doc.md"),
+      truthTemplatePath(config, BEHAVIOR_DOC_TEMPLATE_FILE_NAME),
       renderBehaviorDocTemplateFile()
     )
   );
   results.push(
     await ensureOrUpdateTruthDocTemplate(
       rootDir,
-      truthTemplatePath(config, "contract-doc.md"),
+      truthTemplatePath(config, CONTRACT_DOC_TEMPLATE_FILE_NAME),
       renderContractDocTemplateFile()
     )
   );
   results.push(
     await ensureOrUpdateTruthDocTemplate(
       rootDir,
-      truthTemplatePath(config, "architecture-doc.md"),
+      truthTemplatePath(config, ARCHITECTURE_DOC_TEMPLATE_FILE_NAME),
       renderArchitectureDocTemplateFile()
     )
   );
   results.push(
     await ensureOrUpdateTruthDocTemplate(
       rootDir,
-      truthTemplatePath(config, "workflow-doc.md"),
+      truthTemplatePath(config, WORKFLOW_DOC_TEMPLATE_FILE_NAME),
       renderWorkflowDocTemplateFile()
     )
   );
   results.push(
     await ensureOrUpdateTruthDocTemplate(
       rootDir,
-      truthTemplatePath(config, "operations-doc.md"),
+      truthTemplatePath(config, OPERATIONS_DOC_TEMPLATE_FILE_NAME),
       renderOperationsDocTemplateFile()
     )
   );
   results.push(
     await ensureOrUpdateTruthDocTemplate(
       rootDir,
-      truthTemplatePath(config, "test-behavior-doc.md"),
+      truthTemplatePath(config, TEST_BEHAVIOR_DOC_TEMPLATE_FILE_NAME),
       renderTestBehaviorDocTemplateFile()
     )
   );
+  results.push(
+    await ensureOrUpdateTruthDocTemplate(
+      rootDir,
+      truthTemplatePath(config, PRODUCT_CAPABILITY_DOC_TEMPLATE_FILE_NAME),
+      renderProductCapabilityDocTemplateFile()
+    )
+  );
   const behaviorDocTemplate = await readBehaviorDocTemplate(rootDir, config);
   results.push(
     await ensureRepoFile(
@@ -1766,26 +2009,66 @@ var renderAuditEvidenceCheckedSection = (items) => {
 };
 
 // src/agents/shared.ts
+var renderBulletLine = (line) => {
+  const normalized = line.trim().replace(/^-\s*/u, "");
+  return `- ${normalized}`;
+};
+var renderBulletBlock = (lines, indent = "  ") => {
+  return lines.split(/\n/u).map((line) => line.trim()).filter((line) => line.length > 0).map((line) => `${indent}${renderBulletLine(line)}`).join("\n");
+};
+var renderLaneClassificationRuleBlock = (config = defaultAgentConfig(), indent = "  ") => {
+  const [, ...rules] = renderLaneClassificationInstructions(config).split(/\n/u);
+  return renderBulletBlock(rules.join("\n"), indent);
+};
+var renderReadOnlyLaneClassificationRuleBlock = (config = defaultAgentConfig(), indent = "  ") => {
+  const productTruthRoot = resolveProductTruthRoot(config);
+  const engineeringTruthRoot = resolveEngineeringTruthRoot(config);
+  return renderBulletBlock(
+    [
+      "classify the request or changed surface as product-lane, engineering-lane, both-lane, or ambiguous for reporting only",
+      `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",
+      LANE_INVARIANT
+    ].join("\n"),
+    indent
+  );
+};
 var DECISION_TRUTH_INSTRUCTIONS = [
   "Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed.",
   "Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail.",
-  "Update Product Decisions and Rationale when a decision changes behavior."
+  "Product decisions belong in product truth; engineering, architecture, contract, workflow, and operational decisions belong in engineering truth."
 ].join("\n");
+var LANE_INVARIANT = "Do not make product docs a summary of engineering docs. Do not make engineering docs a detailed version of product docs. Product truth says what must be true and why. Engineering truth says how the repository currently realizes it.";
+var renderLaneClassificationInstructions = (config = defaultAgentConfig()) => {
+  const productTruthRoot = resolveProductTruthRoot(config);
+  const engineeringTruthRoot = resolveEngineeringTruthRoot(config);
+  return [
+    "Lane classification gate:",
+    "- 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",
+    `- ${LANE_INVARIANT}`
+  ].join("\n");
+};
 var EVIDENCE_AUTHORITY_INSTRUCTIONS = [
   "Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path.",
   "Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries."
 ].join("\n");
 var REPOSITORY_INTELLIGENCE_INSTRUCTIONS = [
-  "Repository intelligence artifacts are optional derived context: RepoIndex, RouteMap, ImpactSet, and ContextPack may guide routing, context selection, and verification planning when available.",
+  "Repository intelligence artifacts are optional derived context: RepoIndex, RouteMap, ImpactSet, and WorkflowState/action context may guide routing, write boundaries, and verification planning when available.",
   "They do not override checkout evidence, canonical truth docs, route files, or workflow write boundaries.",
   "If unavailable, inspect any present Truthmark config, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated."
 ].join("\n");
 var FEATURE_DOC_TEMPLATE_INSTRUCTIONS = [
   "When creating or updating a truth doc, inspect the routed truth kind and use the matching template under the configured Truthmark templates root.",
-  "Supported kinds: behavior, contract, architecture, workflow, operations, and test-behavior.",
+  "Supported kinds: product-capability, engineering-behavior, engineering-contract, engineering-architecture, engineering-workflow, engineering-operations, and engineering-test-behavior.",
   "Treat the HTML comments under each template section as normative authoring guidance for that section.",
   "Align existing docs to that template and write or repair section content so it satisfies the comment guidance while preserving accurate authored content.",
-  "If the template is missing, use Scope, Product Decisions, Rationale, and the kind-specific current-truth section.",
+  "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 renderTruthDocOwnershipGateSection = (subject, outcome) => {
@@ -1798,12 +2081,12 @@ var renderTruthDocOwnershipGateSection = (subject, outcome) => {
   ].join("\n");
 };
 var TRUTH_DOC_DECISION_RATIONALE_PRESERVATION_INSTRUCTIONS = [
-  "Product Decisions/Rationale preservation gate:",
-  "- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions and Rationale sections in every source or touched truth doc",
-  "- preserve each current decision and rationale in the bounded owner doc it governs; when splitting, move it to the new owner doc rather than deleting it or leaving it in an index",
+  "Decision/Rationale preservation gate:",
+  "- 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",
-  "- after the edit, verify every touched truth doc still has Product Decisions and Rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked"
+  "- 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 [
@@ -1824,7 +2107,7 @@ var renderRouteFirstEvidenceGateSection = (subject, noImpactedDocOutcome) => {
   return [
     "Evidence Gate:",
     `- 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, Product Decisions, and Rationale",
+    "- 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",
@@ -1834,7 +2117,7 @@ var renderRouteFirstEvidenceGateSection = (subject, noImpactedDocOutcome) => {
 var renderTopologyEvidenceGateSection = () => {
   return [
     "Evidence Gate:",
-    "- apply the Evidence Gate before finishing when Truth Structure writes routed docs, ownership claims, Product Decisions, or Rationale",
+    "- apply the Evidence Gate 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"
   ].join("\n");
@@ -1868,7 +2151,9 @@ var renderCodexSubagentModeSection = (agents, parentRule, writeAgents = []) => {
 };
 var renderOpenCodeSubagentModeSection = (agents, parentRule, writeAgents = []) => {
   const mentions = agents.map((agent) => `@${agent.replace(/_/gu, "-")}`);
-  const writeMentions = writeAgents.map((agent) => `@${agent.replace(/_/gu, "-")}`);
+  const writeMentions = writeAgents.map(
+    (agent) => `@${agent.replace(/_/gu, "-")}`
+  );
   const writeAgentLines = writeMentions.length > 0 ? [
     `- dispatch write-capable project subagents only with explicit write leases: ${writeMentions.join(", ")}`,
     "- each write lease must name objective, required reads, allowed writes, forbidden writes, evidence, verification, and report fields",
@@ -1888,7 +2173,9 @@ var renderOpenCodeSubagentModeSection = (agents, parentRule, writeAgents = []) =
   ].join("\n");
 };
 var renderClaudeSubagentModeSection = (agents, parentRule, writeAgents = []) => {
-  const mentions = agents.map((agent) => `${agent.replace(/_/gu, "-")} subagent`);
+  const mentions = agents.map(
+    (agent) => `${agent.replace(/_/gu, "-")} subagent`
+  );
   const writeMentions = writeAgents.map(
     (agent) => `${agent.replace(/_/gu, "-")} subagent`
   );
@@ -1912,7 +2199,9 @@ var renderClaudeSubagentModeSection = (agents, parentRule, writeAgents = []) =>
 };
 var renderCopilotCustomAgentModeSection = (agents, parentRule, writeAgents = []) => {
   const mentions = agents.map((agent) => `@${agent.replace(/_/gu, "-")}`);
-  const writeMentions = writeAgents.map((agent) => `@${agent.replace(/_/gu, "-")}`);
+  const writeMentions = writeAgents.map(
+    (agent) => `@${agent.replace(/_/gu, "-")}`
+  );
   const writeAgentLines = writeMentions.length > 0 ? [
     `- dispatch write-capable project custom agents only with explicit write leases: ${writeMentions.join(", ")}`,
     "- each write lease must name objective, required reads, allowed writes, forbidden writes, evidence, verification, and report fields",
@@ -1933,7 +2222,9 @@ var renderCopilotCustomAgentModeSection = (agents, parentRule, writeAgents = [])
 };
 var renderGeminiSubagentModeSection = (agents, parentRule, writeAgents = []) => {
   const mentions = agents.map((agent) => `@${agent.replace(/_/gu, "-")}`);
-  const writeMentions = writeAgents.map((agent) => `@${agent.replace(/_/gu, "-")}`);
+  const writeMentions = writeAgents.map(
+    (agent) => `@${agent.replace(/_/gu, "-")}`
+  );
   const writeAgentLines = writeMentions.length > 0 ? [
     `- dispatch write-capable project subagents only with explicit write leases: ${writeMentions.join(", ")}`,
     "- each write lease must name objective, required reads, allowed writes, forbidden writes, evidence, verification, and report fields",
@@ -1956,13 +2247,15 @@ var defaultAgentConfig = () => {
   return createDefaultConfig();
 };
 var renderHierarchySummary = (config) => {
-  const truthRoot3 = resolveTruthDocsRoot(config);
+  const productRoot = resolveProductTruthRoot(config);
+  const engineeringRoot = resolveEngineeringTruthRoot(config);
   return [
     "Truthmark hierarchy hints:",
     "- Config, when present: .truthmark/config.yml",
     `- Root route index, when present: ${config.truthmark.paths.routesIndex}`,
     `- Area route files, when present: ${config.truthmark.paths.routeAreasRoot}/**/*.md`,
-    `- Truth docs, when present: ${truthRoot3}/**/*.md`
+    `- Product truth docs, when present: ${productRoot}/**/*.md`,
+    `- Engineering truth docs, when present: ${engineeringRoot}/**/*.md`
   ].join("\n");
 };
 
@@ -1977,8 +2270,12 @@ var TRUTHMARK_VERSION = packageJson.version;
 var TRUTHMARK_BLOCK_START = "<!-- truthmark:start -->";
 var TRUTHMARK_BLOCK_END = "<!-- truthmark:end -->";
 var renderCompactHierarchySummary = (config) => {
-  const truthRoot3 = resolveTruthDocsRoot(config);
-  return `Hierarchy hints: config .truthmark/config.yml when present; routes ${config.truthmark.paths.routesIndex} and ${config.truthmark.paths.routeAreasRoot}/**/*.md when present; Truth docs: ${truthRoot3}/**/*.md when present.`;
+  const productTruthRoot = resolveProductTruthRoot(config);
+  const engineeringTruthRoot = resolveEngineeringTruthRoot(config);
+  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()) => {
   const portalLine = config.truthmark.generated.portal.enabled ? `Truthmark Portal is a separate manual-only presentation workflow. Run it only when explicitly requested; it writes generated non-canonical static files under ${config.truthmark.paths.portalOutput}/. Markdown remains canonical.` : null;
@@ -2071,7 +2368,8 @@ var TRUTHMARK_WORKFLOW_MANIFEST = {
     requiredGates: [
       "topology quality",
       "truth-doc ownership",
-      "Product Decisions/Rationale preservation",
+      "lane classification",
+      "Decision/Rationale preservation",
       "truth-doc shape repair when restructuring",
       "Evidence Gate"
     ],
@@ -2114,7 +2412,9 @@ var TRUTHMARK_WORKFLOW_MANIFEST = {
     ],
     requiredGates: [
       "truth-doc ownership",
-      "Product Decisions/Rationale preservation",
+      "lane classification",
+      "Decision/Rationale preservation",
+      "lane split and relationship repair",
       "truth-doc shape repair when restructuring",
       "Evidence Gate"
     ],
@@ -2155,7 +2455,8 @@ var TRUTHMARK_WORKFLOW_MANIFEST = {
     ],
     requiredGates: [
       "truth-doc ownership",
-      "Product Decisions/Rationale preservation",
+      "lane classification",
+      "Decision/Rationale preservation",
       "Evidence Gate",
       "truth-doc shape repair when restructuring"
     ],
@@ -2191,10 +2492,10 @@ var TRUTHMARK_WORKFLOW_MANIFEST = {
       "truth audit"
     ],
     forbiddenAdjacency: [
-      "must not edit truth docs",
-      "must not edit truth routing"
+      "must not edit truth docs except through follow-up Truth Sync",
+      "must not edit truth routing except through follow-up Truth Sync"
     ],
-    requiredGates: ["truth-doc ownership"],
+    requiredGates: ["lane classification", "truth-doc ownership"],
     allowedWrites: ["functional code"],
     reportSections: ["Truth docs used", "Code updated", "Verification"]
   },
@@ -2326,9 +2627,6 @@ var getTruthmarkWorkflow = (id) => {
 };
 
 // src/agents/truth-check.ts
-var renderMarkdownExample = (content) => {
-  return ["```md", content, "```"].join("\n");
-};
 var TRUTH_CHECK_EXPLICIT_INVOCATIONS = "OpenCode /skill truthmark-check; Codex /truthmark-check or $truthmark-check; Claude Code /truthmark-check; GitHub Copilot /truthmark-check; Gemini CLI /truthmark:check.";
 var renderTruthCheckReportExample = (config = defaultAgentConfig()) => {
   const rootRouteIndex = config.truthmark.paths.routesIndex;
@@ -2355,7 +2653,7 @@ ${renderAuditEvidenceCheckedSection([
 Validation:
 - truthmark check`;
 };
-var renderTruthCheckSkillBody = (config = defaultAgentConfig(), options = {}) => {
+var renderTruthCheckProcedureBody = (config = defaultAgentConfig(), options = {}) => {
   const workflow = getTruthmarkWorkflow("truthmark-check");
   const claudeSubagentMode = options.includeClaudeSubagentMode ? `${renderClaudeSubagentModeSection(
     workflow.subagents ?? [],
@@ -2382,15 +2680,7 @@ var renderTruthCheckSkillBody = (config = defaultAgentConfig(), options = {}) =>
 
 ` : "";
   const subagentMode = `${claudeSubagentMode}${codexSubagentMode}${copilotCustomAgentMode}${openCodeSubagentMode}`;
-  return `---
-name: truthmark-check
-description: ${workflow.description}
-argument-hint: Optional area, doc path, or audit focus
-user-invocable: true
-truthmark-version: ${TRUTHMARK_VERSION}
----
-
-# Truthmark Check
+  return `# Truthmark Check
 
 Use this skill to audit repository truth health.
 
@@ -2399,12 +2689,25 @@ Invocations: ${TRUTH_CHECK_EXPLICIT_INVOCATIONS}
 Truth Check is agent-led:
 
 - inspect .truthmark/config.yml and configured route files only when they exist; then inspect canonical docs and relevant implementation directly
-- ${EVIDENCE_AUTHORITY_INSTRUCTIONS}
 - inspect the configured root route index at ${config.truthmark.paths.routesIndex} and relevant child route files under ${config.truthmark.paths.routeAreasRoot}/ when they exist
+- Evidence authority:
+${renderBulletBlock(EVIDENCE_AUTHORITY_INSTRUCTIONS)}
+- Lane classification:
+${renderReadOnlyLaneClassificationRuleBlock(config)}
 - check that current docs describe current code rather than historical plans
+- keep lane and cross-lane checks route-first and bounded:
+  - for a narrow audit, inspect only the routed area and directly linked counterpart docs
+  - for root-wide truth health, first build a cheap route-map/index from route files, then inspect only mismatches and linked leaves
+  - inspect product counterparts for engineering docs only when route YAML claims a product relationship, or when the user explicitly asks for user-visible product coverage
+- check lane root/kind alignment for product truth under ${config.truthmark.paths.productTruthRoot} and engineering truth under ${config.truthmark.paths.engineeringTruthRoot}
+- check route YAML cross-lane realized_by and realizes links for existence and lane compatibility
+- report missing product links for user-visible engineering docs only as a second-pass review diagnostic, not as default full-document reads or hard errors
+- check product docs do not contain engineering execution flow, generated file inventories, or CLI envelope mechanics
+- check engineering docs do not contain product promises, product rationale, or Product Decisions sections
+- never judge whether a product decision is commercially correct, valuable, prioritized, or desirable
 - check that route files map code surfaces to canonical truth docs when route files exist
 - check for broad, catch-all, index-like, or mixed-owner truth docs and report them as topology issues requiring Truth Structure
-- check that canonical behavior docs keep active Product Decisions and Rationale sections
+- check that canonical docs keep lane-appropriate decisions and rationale sections
 - optionally run truthmark check when local tooling is available
 - must not require the truthmark binary; direct inspection is always valid
 - report issues and suggested fixes without silently rewriting unrelated files
@@ -2412,20 +2715,13 @@ Truth Check is agent-led:
 ${renderAuditEvidenceGateSection()}
 
 ${subagentMode}${renderHierarchySummary(config)}
-${DECISION_TRUTH_INSTRUCTIONS}
-
-Report completion in this shape:
-
-${renderMarkdownExample(renderTruthCheckReportExample(config))}`;
+${DECISION_TRUTH_INSTRUCTIONS}`;
 };
 
 // src/agents/truth-document.ts
-var renderMarkdownExample2 = (content) => {
-  return ["```md", content, "```"].join("\n");
-};
 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 truthDocsRoot = resolveTruthDocsRoot(config);
+  const engineeringTruthRoot = resolveEngineeringTruthRoot(config);
   const helperScripts = ["validate-write-lease: skipped, no write lease used"];
   return `Truth Document: completed
 
@@ -2436,13 +2732,13 @@ Ownership reviewed:
 - ${config.truthmark.paths.routesIndex}
 
 Truth docs created:
-- ${truthDocsRoot}/contracts.md
+- ${engineeringTruthRoot}/contracts/routing.md
 
 Truth docs updated:
-- ${truthDocsRoot}/check-diagnostics.md
+- ${engineeringTruthRoot}/behaviors/check-diagnostics.md
 
 Truth docs restructured:
-- ${truthDocsRoot}/check-diagnostics.md
+- ${engineeringTruthRoot}/behaviors/check-diagnostics.md
 
 Routing updated:
 - ${config.truthmark.paths.routesIndex}
@@ -2464,7 +2760,7 @@ ${helperScripts.map((helperScript) => `- ${helperScript}`).join("\n")}
 Notes:
 - Documented routing and behavior from route handlers and tests.`;
 };
-var renderTruthDocumentSkillBody = (config = defaultAgentConfig(), options = {}) => {
+var renderTruthDocumentProcedureBody = (config = defaultAgentConfig(), options = {}) => {
   const workflow = getTruthmarkWorkflow("truthmark-document");
   const claudeSubagentMode = options.includeClaudeSubagentMode ? `${renderClaudeSubagentModeSection(
     workflow.subagents ?? [],
@@ -2491,15 +2787,7 @@ var renderTruthDocumentSkillBody = (config = defaultAgentConfig(), options = {})
   )}
 ` : "";
   const subagentMode = `${claudeSubagentMode}${codexSubagentMode}${copilotCustomAgentMode}${openCodeSubagentMode}`;
-  return `---
-name: truthmark-document
-description: ${workflow.description}
-argument-hint: Optional implemented behavior, API endpoint, route, controller, package, or truth-doc area to document
-user-invocable: true
-truthmark-version: ${TRUTHMARK_VERSION}
----
-
-# Truthmark Document
+  return `# Truthmark Document
 
 Use this skill to document existing implemented behavior when no functional-code changes are required for the task.
 Invocations: ${TRUTH_DOCUMENT_EXPLICIT_INVOCATIONS}
@@ -2508,7 +2796,10 @@ Truth Document is manual and implementation-first:
 
 - run only when the user explicitly asks to generate or update truth docs for existing behavior, or when Truth Sync, Truth Check, or Truth Structure reports implemented behavior that lacks canonical truth docs
 - inspect .truthmark/config.yml and configured route files only when they exist; then inspect existing canonical docs, implementation code, and tests directly
-- ${EVIDENCE_AUTHORITY_INSTRUCTIONS}
+- Evidence authority:
+${renderBulletBlock(EVIDENCE_AUTHORITY_INSTRUCTIONS)}
+- Lane classification:
+${renderLaneClassificationRuleBlock(config)}
 - document current implemented behavior; do not invent future behavior or planned endpoints
 - may write canonical truth docs and ${config.truthmark.paths.routesIndex} or relevant child route files only
 - must not write functional code
@@ -2516,7 +2807,10 @@ Truth Document is manual and implementation-first:
 - block and recommend Truth Structure when routing repair is unsafe, ambiguous, or outside the task boundary
 - keep feature README.md files as indexes rather than truth-document targets
 - create or update bounded leaf truth docs when behavior does not fit an existing leaf doc
-- keep behavior truth docs behavior-oriented, not endpoint-oriented, unless the endpoint itself is the behavior boundary
+- write product capability/boundary truth under ${config.truthmark.paths.productTruthRoot} when documenting product promise, boundary, rationale, or user/stakeholder value
+- write engineering truth under ${config.truthmark.paths.engineeringTruthRoot} when documenting implementation behavior, contracts, architecture, workflows, operations, or tests
+- for both-lane documentation requests, write separate product and engineering docs and cross-link them in route YAML with realized_by and realizes, not in doc frontmatter
+- keep engineering behavior truth behavior-oriented, not endpoint-oriented, unless the endpoint itself is the behavior boundary
 - keep API endpoint details in the nearest contract truth doc when such a doc owns the API contract
 - preserve unrelated authored content
 ${renderTruthDocOwnershipGateSection(
@@ -2546,19 +2840,12 @@ Parent post-document verification:
 - verify only truth docs and leased truth routing files changed during document work
 - block on functional code, generated host surfaces, or unrelated diffs caused by document work
 - for each write lease, validate the worker report against the actual worker diff, allowedWrites, forbiddenWrites, identity fields, filesChanged, offLeaseChanges, blockers, and required report fields before accepting it
-- verify the final report records ownership review, structure requirement, restructure, routing update, or blocked reason when applicable
-
-Report completion in this shape:
-${renderMarkdownExample2(renderTruthDocumentReportExample(config))}`;
+- verify the final report records ownership review, structure requirement, restructure, routing update, or blocked reason when applicable`;
 };
 
 // src/agents/truth-preview.ts
-var renderMarkdownExample3 = (content) => {
-  return ["```md", content, "```"].join("\n");
-};
 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 renderTruthPreviewReportExample = (config = defaultAgentConfig()) => {
-  const truthDocsRoot = resolveTruthDocsRoot(config);
   return `Truth Preview: completed
 
 Requested outcome:
@@ -2574,14 +2861,16 @@ Why this workflow:
 
 Likely route owner:
 - route file: ${config.truthmark.paths.routesIndex}
-- truth doc: ${truthDocsRoot}/example.md
+- likely lane impact: engineering-lane
+- product target docs: none identified
+- engineering target docs: ${config.truthmark.paths.engineeringTruthRoot}/behaviors/example.md
 - confidence: medium
 
 Expected write classes:
 - truth docs
 
 Expected target files:
-- ${truthDocsRoot}/example.md
+- ${config.truthmark.paths.engineeringTruthRoot}/behaviors/example.md
 
 Suggested subagent use:
 - read-only verifiers: truth_route_auditor
@@ -2594,17 +2883,8 @@ Blocking ambiguity:
 Handoff:
 - Run the selected Truthmark workflow after user approval.`;
 };
-var renderTruthPreviewSkillBody = (config = defaultAgentConfig()) => {
-  const workflow = getTruthmarkWorkflow("truthmark-preview");
-  return `---
-name: truthmark-preview
-description: ${workflow.description}
-argument-hint: Optional requested outcome, code area, doc path, or routing question
-user-invocable: true
-truthmark-version: ${TRUTHMARK_VERSION}
----
-
-Use this skill only when the user explicitly asks to preview Truthmark routing or workflow choice before edits.
+var renderTruthPreviewProcedureBody = (config = defaultAgentConfig()) => {
+  return `Use this skill only when the user explicitly asks to preview Truthmark routing or workflow choice before edits.
 
 Invocations: ${TRUTH_PREVIEW_EXPLICIT_INVOCATIONS}
 
@@ -2612,15 +2892,19 @@ 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
+- 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
 
 Read:
 - .truthmark/config.yml, only when present
-- ${config.truthmark.paths.routesIndex}, only when present
-- relevant child route files under ${config.truthmark.paths.routeAreasRoot}/, only when present
+- ${config.truthmark.paths.routesIndex}, first, only when present
+- relevant child route files under ${config.truthmark.paths.routeAreasRoot}/ for the selected scope or changed paths, only when present
 - relevant truth docs and implementation files needed to preview ownership
-- ${EVIDENCE_AUTHORITY_INSTRUCTIONS}
+- Evidence authority:
+${renderBulletBlock(EVIDENCE_AUTHORITY_INSTRUCTIONS)}
+- Lane classification:
+${renderReadOnlyLaneClassificationRuleBlock(config)}
 
 Do not:
 - must not edit files
@@ -2637,27 +2921,15 @@ Suggested subagent use:
 - write workers: none
 - leases needed: none
 
-${renderHierarchySummary(config)}
-
-Report completion in this shape:
-${renderMarkdownExample3(renderTruthPreviewReportExample(config))}`;
+${renderHierarchySummary(config)}`;
 };
 
 // src/agents/truthmark-portal.ts
 var TRUTHMARK_PORTAL_EXPLICIT_INVOCATIONS = "OpenCode /skill truthmark-portal; Codex /truthmark-portal or $truthmark-portal; Claude Code /truthmark-portal; GitHub Copilot /truthmark-portal; Gemini CLI /truthmark:portal.";
-var renderTruthmarkPortalSkillBody = (config = defaultAgentConfig()) => {
-  const workflow = getTruthmarkWorkflow("truthmark-portal");
+var renderTruthmarkPortalProcedureBody = (config = defaultAgentConfig()) => {
   const output = config.truthmark.paths.portalOutput;
   const template = config.truthmark.paths.portalTemplate;
-  return `---
-name: truthmark-portal
-description: ${workflow.description}
-argument-hint: Optional portal generation focus
-user-invocable: true
-truthmark-version: ${TRUTHMARK_VERSION}
----
-
-# Truthmark Portal
+  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.
 
@@ -2688,48 +2960,19 @@ Workflow:
 5. Replace or write only under ${output}; do not edit canonical Markdown, routing, source code, or instruction files unless the user explicitly changes scope.
 6. Generate the multi-page static site with local assets/search metadata and visible source provenance.
 7. Validate entry page, links where practical, provenance/disclaimers, local-only assets, and that metadata remains under ${output}/assets.
-${renderHierarchySummary(config)}
-
-Report completion in this shape:
-
-\`\`\`md
-Truthmark Portal: completed
-
-Output path:
-- ${output}
-
-Page count:
-- <count>
-
-Diagrams/assets:
-- <generated diagrams/assets or none>
-
-Source docs reviewed:
-- <source markdown paths>
-
-Skipped/ambiguous docs:
-- <paths and reason, or none>
-
-Validation:
-- <checks performed>
-
-Markdown canonical statement:
-- Markdown remains canonical; generated Portal HTML is non-canonical presentation only.
-\`\`\`
-`;
+${renderHierarchySummary(config)}`;
 };
 
 // src/agents/truth-structure.ts
-var renderMarkdownExample4 = (content) => {
-  return ["```md", content, "```"].join("\n");
-};
 var TRUTH_STRUCTURE_EXPLICIT_INVOCATIONS = "OpenCode /skill truthmark-structure; Codex /truthmark-structure or $truthmark-structure; Claude Code /truthmark-structure; GitHub Copilot /truthmark-structure; Gemini CLI /truthmark:structure.";
 var renderTruthStructureReportExample = (config = defaultAgentConfig()) => {
-  const truthDocsRoot = resolveTruthDocsRoot(config);
+  const productTruthRoot = resolveProductTruthRoot(config);
+  const engineeringTruthRoot = resolveEngineeringTruthRoot(config);
   return `Truth Structure: completed
 Topology reviewed:
 - controllers: src/auth/**
-- docs root: ${truthDocsRoot}
+- product docs root: ${productTruthRoot}
+- engineering docs root: ${engineeringTruthRoot}
 - route files: ${config.truthmark.paths.routesIndex}
 Areas reviewed:
 - src/auth/**
@@ -2738,14 +2981,16 @@ Routing updated:
 Initial truth boundary:
 - Area: Authentication
 - Code: src/auth/**
-- Truth owner: ${truthDocsRoot}/authentication/session.md
+- Product owner: ${productTruthRoot}/capabilities/authentication-session.md
+- Engineering owner: ${engineeringTruthRoot}/behaviors/authentication-session.md
 - Scope: session behavior only
 Truth docs created:
-- ${truthDocsRoot}/authentication/session.md
+- ${productTruthRoot}/capabilities/authentication-session.md
+- ${engineeringTruthRoot}/behaviors/authentication-session.md
 Truth docs split:
-- ${truthDocsRoot}/authentication/README.md -> ${truthDocsRoot}/authentication/session.md
+- docs/truthmark/truth/authentication/README.md -> ${productTruthRoot}/capabilities/authentication-session.md and ${engineeringTruthRoot}/behaviors/authentication-session.md
 Truth docs restructured:
-- ${truthDocsRoot}/authentication/README.md
+- docs/truthmark/truth/authentication/README.md
 ${renderClaimEvidenceCheckedSection([
     {
       claim: "Session behavior belongs to a dedicated Authentication truth owner.",
@@ -2758,8 +3003,9 @@ Topology decisions:
 Notes:
 - Added an Authentication area for session behavior.`;
 };
-var renderTruthStructureSkillBody = (config = defaultAgentConfig(), options = {}) => {
-  const truthDocsRoot = resolveTruthDocsRoot(config);
+var renderTruthStructureProcedureBody = (config = defaultAgentConfig(), options = {}) => {
+  const productTruthRoot = resolveProductTruthRoot(config);
+  const engineeringTruthRoot = resolveEngineeringTruthRoot(config);
   const workflow = getTruthmarkWorkflow("truthmark-structure");
   const claudeSubagentMode = options.includeClaudeSubagentMode ? `${renderClaudeSubagentModeSection(
     workflow.subagents ?? [],
@@ -2772,30 +3018,26 @@ var renderTruthStructureSkillBody = (config = defaultAgentConfig(), options = {}
   )}
 ` : "";
   const subagentMode = `${claudeSubagentMode}${copilotCustomAgentMode}`;
-  return `---
-name: truthmark-structure
-description: ${workflow.description}
-argument-hint: Optional area, directory, or routing concern
-user-invocable: true
-truthmark-version: ${TRUTHMARK_VERSION}
----
-
-Use this skill to design or repair Truthmark area structure.
+  return `Use this skill to design or repair Truthmark area structure.
 Invocations: ${TRUTH_STRUCTURE_EXPLICIT_INVOCATIONS}
 Truth Structure is agent-native:
 - inspect repository layout, current docs, Truthmark config and route files when present, and relevant code directly
-- ${EVIDENCE_AUTHORITY_INSTRUCTIONS}
+- Evidence authority:
+${renderBulletBlock(EVIDENCE_AUTHORITY_INSTRUCTIONS)}
+- Lane classification:
+${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
-- Starter truth docs must use closed YAML frontmatter bounded by opening and closing --- lines; include status, doc_type, last_reviewed, and source_of_truth inside that frontmatter.
-- Starter truth docs must include ## Product Decisions and ## Rationale sections.
+- 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.
 ${subagentMode}
 ${FEATURE_DOC_TEMPLATE_INSTRUCTIONS}
-- use ${truthDocsRoot}/** for current truth destinations
+- 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 and Rationale in the canonical doc that owns the behavior
+- keep active Product Decisions in product truth and Engineering Decisions in engineering truth
 - 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.
@@ -2813,7 +3055,7 @@ Do not:
 - do not create generic catch-all docs
 - do not treat README files as Sync targets
 ## Topology Governance
-Truth Structure owns documentation topology. Do not depend on humans to manually organize ${truthDocsRoot}. Treat the configured truth root as a managed semantic root.
+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.
 ${renderTruthDocOwnershipGateSection(
@@ -2825,7 +3067,7 @@ Topology pressure signals:
 - one area maps broad code such as src/**, app/**, server/**, services/**, or packages/**
 - one area maps multiple unrelated controllers, route groups, services, or bounded contexts
 - one truth doc owns unrelated behaviors or unrelated endpoint families
-- the configured truth root has many direct non-index docs
+- either configured lane root has many direct non-index docs
 - a changed controller, route, or service cannot map to a specific behavior doc
 - Truth Sync would need to create a new generic truth doc because routing is too broad
 - endpoint or controller names reveal domains missing from ${config.truthmark.paths.routeAreasRoot}/**
@@ -2838,9 +3080,10 @@ Repair rules:
 - split broad, overloaded, or catch-all areas into behavior-owned child route files
 - split mixed-owner truth docs into bounded owner docs before adding new behavior claims
 - create route files under ${config.truthmark.paths.routeAreasRoot}/ when a product/domain boundary is clear
-- create behavior truth docs under the configured truth root only when behavior lacks a current doc
+- 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
 - README.md files are indexes, not Truth Sync targets
-- prefer bounded leaf truth docs at <truth-root>/<domain>/<behavior>.md
+- 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
 - keep API endpoint details in the nearest contract truth doc when such a doc exists
 - update routing so future Truth Sync can target small docs
@@ -2851,17 +3094,15 @@ ${renderTruthDocRestructureGateSection(
   )}
 ${renderTopologyEvidenceGateSection()}
 ${ARCHITECTURE_DOC_BOUNDARY_INSTRUCTIONS}
-- Do not finish topology repair with routed canonical current-truth docs missing Product Decisions or Rationale sections.
-- If an existing canonical doc lacks either section, add the missing heading beside Current Behavior with a concise current-state placeholder or active decision.
+- 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.
 Portable fallback:
 - If this skill surface is unavailable, perform the same workflow directly from committed repository files.
 - Do not require the truthmark CLI.
 - Inspect .truthmark/config.yml and configured route files only when they exist; then inspect canonical docs and representative implementation code.
 - Use a subagent only when the host supports that pattern; otherwise perform the topology repair inline.
 ${renderHierarchySummary(config)}
-${DECISION_TRUTH_INSTRUCTIONS}
-Report completion in this shape:
-${renderMarkdownExample4(renderTruthStructureReportExample(config))}`;
+${DECISION_TRUTH_INSTRUCTIONS}`;
 };
 
 // src/sync/report.ts
@@ -2975,13 +3216,8 @@ 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 renderMarkdownExample5 = (content) => {
-  return ["```md", content, "```"].join("\n");
-};
-var renderTruthSyncSkillBody = (config = defaultAgentConfig(), options = {}) => {
-  const truthDocsRoot = resolveTruthDocsRoot(config);
+var renderTruthSyncProcedureBody = (config = defaultAgentConfig(), options = {}) => {
   const workflow = getTruthmarkWorkflow("truthmark-sync");
-  const helperScripts = ["validate-write-lease: skipped, no write lease used"];
   const claudeSubagentMode = options.includeClaudeSubagentMode ? `${renderClaudeSubagentModeSection(
     workflow.subagents ?? [],
     "Parent agent owns Truth Sync acceptance, lease validation, and final report",
@@ -3007,15 +3243,7 @@ var renderTruthSyncSkillBody = (config = defaultAgentConfig(), options = {}) =>
   )}
 ` : "";
   const subagentMode = `${claudeSubagentMode}${codexSubagentMode}${copilotCustomAgentMode}${openCodeSubagentMode}`;
-  return `---
-name: truthmark-sync
-description: ${workflow.description}
-argument-hint: Optional changed-code area, truth-doc area, or sync focus
-user-invocable: true
-truthmark-version: ${TRUTHMARK_VERSION}
----
-
-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.
+  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.
 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.
@@ -3023,9 +3251,13 @@ Parent workflow:
 1. Inspect git status, staged changes, unstaged changes, and untracked files directly.
 2. Inspect .truthmark/config.yml and configured route files only when they exist; then inspect relevant canonical docs.
 3. Identify functional-code changes and the nearest truth docs or routing repairs.
-4. ${EVIDENCE_AUTHORITY_INSTRUCTIONS}
-5. Code verification is parent-owned: follow repository instructions and task context, and report what ran or why it did not run.
-6. Dispatch bounded Truth Sync workers only when the host supports subagent dispatch and the acting agent chooses that path; otherwise execute the same sync task inline.
+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:
 - 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
@@ -3035,6 +3267,7 @@ ${subagentMode}Topology quality gate:
 - 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"
@@ -3042,7 +3275,7 @@ ${renderTruthDocOwnershipGateSection(
 ${TRUTH_DOC_DECISION_RATIONALE_PRESERVATION_INSTRUCTIONS}
 ${FEATURE_DOC_TEMPLATE_INSTRUCTIONS}
 ${renderTruthDocRestructureGateSection(
-    "Truth Sync may restructure only truth docs impacted by the current functional-code change."
+    "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(
@@ -3054,7 +3287,7 @@ Optional validation tooling:
 - you may run truthmark check when local tooling is available
 - do not require the truthmark binary; direct checkout inspection is the canonical path
 - optional validation must not replace agent judgment about docs and routing
-- update Product Decisions and Rationale when a behavior change comes from a decision change
+- 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.
@@ -3069,34 +3302,9 @@ Parent post-sync verification:
 - block if functional code changed during sync
 - for each write lease, validate the worker report against the actual worker diff, allowedWrites, forbiddenWrites, identity fields, filesChanged, offLeaseChanges, blockers, and required report fields before accepting it
 - validate the final report against the structured Truth Sync report contract, including Claim, indented Evidence, and Result values supported, narrowed, removed, or blocked under Evidence checked
-- verify the updated docs correspond to the reviewed changed-code surface
+- verify the 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
-Report completion in this shape:
-${renderMarkdownExample5(
-    renderTruthSyncCompletedReport({
-      changedCode: ["src/auth/session.ts"],
-      ownershipReviewed: [config.truthmark.paths.routesIndex],
-      truthDocsUpdated: [`${truthDocsRoot}/repository/overview.md`],
-      evidenceChecked: [
-        {
-          claim: "Session timeout behavior is documented in the mapped repository truth doc.",
-          evidence: ["src/auth/session.ts:12", `${config.truthmark.paths.routesIndex}:11`],
-          result: "supported"
-        }
-      ],
-      helperScripts,
-      notes: ["Updated session timeout behavior."]
-    })
-  )}
-Blocked report example:
-${renderMarkdownExample5(
-    renderTruthSyncBlockedReport({
-      reason: "routing repair is not allowed",
-      manualReviewFiles: [config.truthmark.paths.routesIndex],
-      nextAction: "update routing metadata and rerun Truth Sync"
-    })
-  )}`;
+- blocked 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
@@ -3182,7 +3390,31 @@ description: '${description}'
 ${prompt}
 `;
 };
-var renderTomlString = (value) => {
+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"] : []
+  ];
+};
+var renderWorkflowCommandAdapterInstructions = (workflowId, root, hostName, surfaceKind) => {
+  const definition = WORKFLOW_PACKAGE_DEFINITIONS[workflowId];
+  const canonicalFiles = ["SKILL.md", ...workflowSupportFiles(workflowId)].map((supportFile) => `- ${root}/${supportFile}`).join("\n");
+  return `This ${surfaceKind} is the ${hostName} entrypoint for ${definition.title}.
+
+Do not invoke another Truthmark command from here.
+
+Read these host-local files in order only as needed:
+${canonicalFiles}
+
+If skill entrypoints are unavailable, use the host's direct evidence-first manual fallback procedure.`;
+};
+var renderTomlString = (value) => {
   return `"${value.replace(/\\/gu, "\\\\").replace(/"/gu, '\\"')}"`;
 };
 var renderTomlStringArray = (values) => {
@@ -3246,7 +3478,7 @@ var WORKFLOW_PACKAGE_DEFINITIONS = {
     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.",
-      `Inspect .truthmark/config.yml and configured route files (${routeFilesHint(config)}) only when they exist; then inspect only the truth docs or implementation files needed to preview ownership.`,
+      `Inspect .truthmark/config.yml and the root route index (${config.truthmark.paths.routesIndex}) first when present; then inspect only child route files under ${config.truthmark.paths.routeAreasRoot}/ that are relevant to the selected scope or changed paths, plus the truth docs or implementation files needed to preview ownership.`,
       "Truth Preview is read-only; this report is intended, not authorized.",
       "must not edit files and must not issue write leases; do not run Truth Sync automatically, replace Truth Check, claim final correctness, or mutate code.",
       "Use optional read-only route-auditor evidence only when it reduces context or clarifies ownership.",
@@ -3302,22 +3534,110 @@ var WORKFLOW_PACKAGE_DEFINITIONS = {
     ]
   }
 };
-var stripWorkflowSkillFrontmatter = (body) => {
-  return body.replace(/^---\n[\s\S]*?\n---\n\n?/u, "").trim();
+var renderMarkdownExample = (content) => {
+  return ["```md", content, "```"].join("\n");
 };
-var splitWorkflowSupport = (body) => {
-  const stripped = stripWorkflowSkillFrontmatter(body);
-  const marker = "Report completion in this shape:";
-  const markerIndex = stripped.indexOf(marker);
-  if (markerIndex === -1) {
-    return {
-      procedure: stripped,
-      reportTemplate: "Report completion in the workflow-specific shape."
-    };
+var renderWorkflowReportTemplate = (workflowId, config) => {
+  const productTruthRoot = resolveProductTruthRoot(config);
+  const engineeringTruthRoot = resolveEngineeringTruthRoot(config);
+  switch (workflowId) {
+    case "truthmark-structure":
+      return `Report completion in this shape:
+${renderMarkdownExample(
+        renderTruthStructureReportExample(config)
+      )}`;
+    case "truthmark-document":
+      return `Report completion in this shape:
+${renderMarkdownExample(
+        renderTruthDocumentReportExample(config)
+      )}`;
+    case "truthmark-sync":
+      return `Report completion in this shape:
+${renderMarkdownExample(
+        renderTruthSyncCompletedReport({
+          changedCode: ["src/auth/session.ts"],
+          ownershipReviewed: [config.truthmark.paths.routesIndex],
+          truthDocsUpdated: [`${engineeringTruthRoot}/repository/overview.md`],
+          evidenceChecked: [
+            {
+              claim: "Session timeout behavior is documented in the mapped repository truth doc.",
+              evidence: [
+                "src/auth/session.ts:12",
+                `${config.truthmark.paths.routesIndex}:11`
+              ],
+              result: "supported"
+            }
+          ],
+          helperScripts: [
+            "validate-write-lease: skipped, no write lease used"
+          ],
+          notes: ["Updated session timeout behavior."]
+        })
+      )}
+Blocked report example:
+${renderMarkdownExample(
+        renderTruthSyncBlockedReport({
+          reason: "routing repair is not allowed",
+          manualReviewFiles: [config.truthmark.paths.routesIndex],
+          nextAction: "update routing metadata and rerun Truth Sync"
+        })
+      )}`;
+    case "truthmark-preview":
+      return `Report completion in this shape:
+${renderMarkdownExample(
+        renderTruthPreviewReportExample(config)
+      )}`;
+    case "truthmark-realize":
+      return `Report completion in this shape:
+
+${renderMarkdownExample(`Truth Realize: completed
+
+Truth docs used:
+- ${productTruthRoot}/capabilities/authentication-session.md
+- ${engineeringTruthRoot}/behaviors/authentication-session.md
+
+Code updated:
+- src/auth/session.ts
+
+Verification:
+- npm test -- auth`)}`;
+    case "truthmark-check":
+      return `Report completion in this shape:
+
+${renderMarkdownExample(
+        renderTruthCheckReportExample(config)
+      )}`;
+    case "truthmark-portal":
+      return `Report completion in this shape:
+
+${renderMarkdownExample(`Truthmark Portal: completed
+
+Output path:
+- ${config.truthmark.paths.portalOutput}
+
+Page count:
+- <count>
+
+Diagrams/assets:
+- <generated diagrams/assets or none>
+
+Source docs reviewed:
+- <source markdown paths>
+
+Skipped/ambiguous docs:
+- <paths and reason, or none>
+
+Validation:
+- <checks performed>
+
+Markdown canonical statement:
+- Markdown remains canonical; generated Portal HTML is non-canonical presentation only.`)}`;
   }
+};
+var renderWorkflowSupportParts = (workflowId, config) => {
   return {
-    procedure: stripped.slice(0, markerIndex).trim(),
-    reportTemplate: stripped.slice(markerIndex).trim()
+    procedure: renderWorkflowProcedure(workflowId, config),
+    reportTemplate: renderWorkflowReportTemplate(workflowId, config)
   };
 };
 var renderSkillSupportFile = (title, body) => {
@@ -3378,22 +3698,22 @@ Helper scripts:
 \`\`\``
   );
 };
-var renderStandaloneWorkflowSkillBody = (workflowId, config) => {
+var renderWorkflowProcedure = (workflowId, config) => {
   switch (workflowId) {
     case "truthmark-structure":
-      return renderTruthStructureSkillBody(config);
+      return renderTruthStructureProcedureBody(config);
     case "truthmark-document":
-      return renderTruthDocumentSkillBody(config);
+      return renderTruthDocumentProcedureBody(config);
     case "truthmark-sync":
-      return renderTruthSyncSkillBody(config);
+      return renderTruthSyncProcedureBody(config);
     case "truthmark-preview":
-      return renderTruthPreviewSkillBody(config);
+      return renderTruthPreviewProcedureBody(config);
     case "truthmark-realize":
-      return renderTruthmarkRealizeSkillBody(config);
+      return renderTruthmarkRealizeProcedureBody(config);
     case "truthmark-check":
-      return renderTruthCheckSkillBody(config);
+      return renderTruthCheckProcedureBody(config);
     case "truthmark-portal":
-      return renderTruthmarkPortalSkillBody(config);
+      return renderTruthmarkPortalProcedureBody(config);
   }
 };
 var renderWorkflowEntrypoint = (workflowId, config, supportFiles, host) => {
@@ -3494,17 +3814,13 @@ var renderTruthmarkSkillPackage = ({
 }) => {
   const skillDirectory = skillPath.replace(/\/SKILL\.md$/u, "");
   const supportDirectory = `${skillDirectory}/support`;
-  const { procedure, reportTemplate } = splitWorkflowSupport(
-    renderStandaloneWorkflowSkillBody(workflowId, config)
+  const { procedure, reportTemplate } = renderWorkflowSupportParts(
+    workflowId,
+    config
   );
   const subagents = renderWorkflowSubagentSupport(workflowId, host);
   const helpers = getTruthmarkWorkflow(workflowId).helpers ?? [];
-  const supportFiles = [
-    "support/procedure.md",
-    "support/report-template.md",
-    ...subagents === void 0 ? [] : ["support/subagents-and-leases.md"],
-    ...helpers.length === 0 ? [] : ["helper-manifest.yml", "support/helper-policy.md"]
-  ];
+  const supportFiles = workflowSupportFiles(workflowId);
   const definition = WORKFLOW_PACKAGE_DEFINITIONS[workflowId];
   const files = [
     {
@@ -3549,16 +3865,19 @@ var renderTruthmarkSkillPackage = ({
   }
   return files;
 };
-var normalizeOpenCodePermissionPath = (path13) => {
-  const normalized = path13.replace(/\\/gu, "/").replace(/^\.\//u, "").replace(/\/+$/u, "");
+var normalizeOpenCodePermissionPath = (path12) => {
+  const normalized = path12.replace(/\\/gu, "/").replace(/^\.\//u, "").replace(/\/+$/u, "");
   return normalized === "" ? "." : normalized;
 };
 var appendOpenCodePermissionGlob = (root, glob) => {
   return root === "." ? glob.replace(/^\//u, "") : `${root}${glob}`;
 };
 var renderOpenCodeWriterEditAllowRules = (config) => {
-  const truthDocsRoot = normalizeOpenCodePermissionPath(
-    resolveTruthDocsRoot(config)
+  const truthDocRoots = Array.from(
+    /* @__PURE__ */ new Set([
+      normalizeOpenCodePermissionPath(resolveProductTruthRoot(config)),
+      normalizeOpenCodePermissionPath(resolveEngineeringTruthRoot(config))
+    ])
   );
   const rootRouteIndex = normalizeOpenCodePermissionPath(
     config.truthmark.paths.routesIndex
@@ -3567,7 +3886,7 @@ var renderOpenCodeWriterEditAllowRules = (config) => {
     config.truthmark.paths.routeAreasRoot
   );
   const allowedPatterns = [
-    appendOpenCodePermissionGlob(truthDocsRoot, "/**"),
+    ...truthDocRoots.map((root) => appendOpenCodePermissionGlob(root, "/**")),
     rootRouteIndex,
     appendOpenCodePermissionGlob(areaFilesRoot, "/**/*.md")
   ];
@@ -3590,7 +3909,14 @@ var TRUTHMARK_SUBAGENT_PROFILES = {
     instructions: `Stay read-only.
 Audit one bounded Truthmark route, area, or doc shard assigned by the parent.
 Inspect .truthmark/config.yml and route files only when they exist; then inspect mapped truth docs and relevant implementation files directly.
+Use a route-first bounded strategy: narrow audits inspect only the routed area and directly linked counterpart docs; root-wide health first builds a cheap route-map/index from route files, then inspects only mismatches and linked leaves.
 Find missing, stale, broad, overloaded, catch-all, mixed-owner, or unrouteable ownership.
+Validate route ownership against lane-specific roots and route kind:
+- confirm mapped truth docs resolve to the correct lane root (product or engineering) for their kind
+- flag mismatch between assigned route kind and resolved doc kind (for example, product-capability routed to engineering paths)
+- verify route-doc linkage for lane pairings via realized_by and realizes before recommending edits
+- inspect product counterparts for engineering docs only when route YAML claims a product relationship, or when the parent explicitly asks for user-visible product coverage
+- treat missing product links for user-visible engineering docs as a second-pass diagnostic, not a default full-document read.
 Do not edit files, stage changes, or propose broad rewrites.
 Return JSON only with keys: scope, filesReviewed, findings, evidence, confidence, recommendedWorkflow, notes.
 recommendedWorkflow must be one of: none, truthmark-document, truthmark-structure.`
@@ -3614,7 +3940,7 @@ Return JSON only with keys: scope, filesReviewed, claimsChecked, evidence, unsup
     description: "Read-only Truthmark doc reviewer for shape, decision, rationale, and evidence hygiene.",
     nicknameCandidates: ["Doc Audit", "Doc Shape", "Doc Check"],
     instructions: `Stay read-only.
-Review assigned canonical truth docs for frontmatter, source_of_truth, required template sections, Evidence checked entries, Product Decisions, and Rationale.
+Review assigned canonical truth docs for compact frontmatter, required template sections, final Source References entries, Evidence checked entries, and lane-appropriate decision sections (Product Decisions in product truth, Engineering Decisions in engineering truth).
 Flag README.md files used as behavior truth targets, mixed-owner docs, and shape repairs that should move to Truth Structure.
 Do not edit files, stage changes, or rewrite docs.
 Return JSON only with keys: scope, filesReviewed, findings, evidence, confidence, recommendedWorkflow, notes.
@@ -4027,18 +4353,8 @@ truthmark:
   refresh_command: "truthmark init"
 `;
 };
-var renderTruthmarkRealizeSkillBody = (config = defaultAgentConfig()) => {
-  const truthDocsRoot = resolveTruthDocsRoot(config);
-  const workflow = getTruthmarkWorkflow("truthmark-realize");
-  return `---
-name: truthmark-realize
-description: ${workflow.description}
-argument-hint: Optional truth doc path, area, or desired code behavior to realize
-user-invocable: true
-truthmark-version: ${TRUTHMARK_VERSION}
----
-
-# Truthmark Realize
+var renderTruthmarkRealizeProcedureBody = (config = defaultAgentConfig()) => {
+  return `# Truthmark Realize
 
 Use this skill only when the user explicitly asks to realize truth docs into code.
 
@@ -4069,23 +4385,7 @@ Read and write boundaries:
 
 - may read truth docs, routing docs, and relevant functional code
 - may write functional code only
-- must not edit truth docs or truth routing while realizing those docs
-
-Report completion in this shape:
-
-\`\`\`md
-Truth Realize: completed
-
-Truth docs used:
-- ${truthDocsRoot}/authentication/session-timeout.md
-
-Code updated:
-- src/auth/session.ts
-
-Verification:
-- npm test -- auth
-\`\`\`
-`;
+- must not edit truth docs or truth routing while realizing those docs`;
 };
 var renderTruthmarkRealizeSkillMetadata = () => {
   const workflow = getTruthmarkWorkflow("truthmark-realize");
@@ -4147,110 +4447,126 @@ truthmark:
   refresh_command: "truthmark init"
 `;
 };
-var renderTruthmarkGeminiStructureCommand = (config = defaultAgentConfig()) => {
-  const workflow = getTruthmarkWorkflow("truthmark-structure");
+var renderGeminiWorkflowCommand = (workflowId, root) => {
+  const workflow = getTruthmarkWorkflow(workflowId);
   return renderGeminiCommand(
     workflow.description,
-    renderTruthStructureSkillBody(config)
+    renderWorkflowCommandAdapterInstructions(
+      workflowId,
+      root,
+      "Gemini CLI",
+      "command"
+    )
   );
 };
-var renderTruthmarkGeminiDocumentCommand = (config = defaultAgentConfig()) => {
-  const workflow = getTruthmarkWorkflow("truthmark-document");
-  return renderGeminiCommand(
+var renderCopilotWorkflowPrompt = (workflowId, root) => {
+  const workflow = getTruthmarkWorkflow(workflowId);
+  return renderCopilotPromptFile(
     workflow.description,
-    renderTruthDocumentSkillBody(config)
+    renderWorkflowCommandAdapterInstructions(
+      workflowId,
+      root,
+      "GitHub Copilot",
+      "prompt"
+    )
+  );
+};
+var renderTruthmarkGeminiStructureCommand = (config = defaultAgentConfig()) => {
+  void config;
+  return renderGeminiWorkflowCommand(
+    "truthmark-structure",
+    ".gemini/skills/truthmark-structure"
+  );
+};
+var renderTruthmarkGeminiDocumentCommand = (config = defaultAgentConfig()) => {
+  void config;
+  return renderGeminiWorkflowCommand(
+    "truthmark-document",
+    ".gemini/skills/truthmark-document"
   );
 };
 var renderTruthmarkGeminiSyncCommand = (config = defaultAgentConfig()) => {
-  const workflow = getTruthmarkWorkflow("truthmark-sync");
-  return renderGeminiCommand(
-    workflow.description,
-    renderTruthSyncSkillBody(config)
+  void config;
+  return renderGeminiWorkflowCommand(
+    "truthmark-sync",
+    ".gemini/skills/truthmark-sync"
   );
 };
 var renderTruthmarkGeminiRealizeCommand = (config = defaultAgentConfig()) => {
-  const workflow = getTruthmarkWorkflow("truthmark-realize");
-  return renderGeminiCommand(
-    workflow.description,
-    renderTruthmarkRealizeSkillBody(config)
+  void config;
+  return renderGeminiWorkflowCommand(
+    "truthmark-realize",
+    ".gemini/skills/truthmark-realize"
   );
 };
 var renderTruthmarkGeminiCheckCommand = (config = defaultAgentConfig()) => {
-  const workflow = getTruthmarkWorkflow("truthmark-check");
-  return renderGeminiCommand(
-    workflow.description,
-    renderTruthCheckSkillBody(config)
+  void config;
+  return renderGeminiWorkflowCommand(
+    "truthmark-check",
+    ".gemini/skills/truthmark-check"
   );
 };
 var renderTruthmarkGeminiPreviewCommand = (config = defaultAgentConfig()) => {
-  const workflow = getTruthmarkWorkflow("truthmark-preview");
-  return renderGeminiCommand(
-    workflow.description,
-    renderTruthPreviewSkillBody(config)
+  void config;
+  return renderGeminiWorkflowCommand(
+    "truthmark-preview",
+    ".gemini/skills/truthmark-preview"
   );
 };
 var renderTruthmarkGeminiPortalCommand = (config = defaultAgentConfig()) => {
-  const workflow = getTruthmarkWorkflow("truthmark-portal");
-  return renderGeminiCommand(
-    workflow.description,
-    renderTruthmarkPortalSkillBody(config)
+  void config;
+  return renderGeminiWorkflowCommand(
+    "truthmark-portal",
+    ".gemini/skills/truthmark-portal"
   );
 };
 var renderTruthmarkCopilotStructurePrompt = (config = defaultAgentConfig()) => {
-  const workflow = getTruthmarkWorkflow("truthmark-structure");
-  return renderCopilotPromptFile(
-    workflow.description,
-    renderTruthStructureSkillBody(config, {
-      includeCopilotCustomAgentMode: true
-    })
+  void config;
+  return renderCopilotWorkflowPrompt(
+    "truthmark-structure",
+    ".github/skills/truthmark-structure"
   );
 };
 var renderTruthmarkCopilotDocumentPrompt = (config = defaultAgentConfig()) => {
-  const workflow = getTruthmarkWorkflow("truthmark-document");
-  return renderCopilotPromptFile(
-    workflow.description,
-    renderTruthDocumentSkillBody(config, {
-      includeCopilotCustomAgentMode: true
-    })
+  void config;
+  return renderCopilotWorkflowPrompt(
+    "truthmark-document",
+    ".github/skills/truthmark-document"
   );
 };
 var renderTruthmarkCopilotSyncPrompt = (config = defaultAgentConfig()) => {
-  const workflow = getTruthmarkWorkflow("truthmark-sync");
-  return renderCopilotPromptFile(
-    workflow.description,
-    renderTruthSyncSkillBody(config, {
-      includeCopilotCustomAgentMode: true
-    })
+  void config;
+  return renderCopilotWorkflowPrompt(
+    "truthmark-sync",
+    ".github/skills/truthmark-sync"
   );
 };
 var renderTruthmarkCopilotRealizePrompt = (config = defaultAgentConfig()) => {
-  const workflow = getTruthmarkWorkflow("truthmark-realize");
-  return renderCopilotPromptFile(
-    workflow.description,
-    renderTruthmarkRealizeSkillBody(config)
+  void config;
+  return renderCopilotWorkflowPrompt(
+    "truthmark-realize",
+    ".github/skills/truthmark-realize"
   );
 };
 var renderTruthmarkCopilotCheckPrompt = (config = defaultAgentConfig()) => {
-  const workflow = getTruthmarkWorkflow("truthmark-check");
-  return renderCopilotPromptFile(
-    workflow.description,
-    renderTruthCheckSkillBody(config, {
-      includeCopilotCustomAgentMode: true
-    })
+  void config;
+  return renderCopilotWorkflowPrompt(
+    "truthmark-check",
+    ".github/skills/truthmark-check"
   );
 };
 var renderTruthmarkCopilotPreviewPrompt = (config = defaultAgentConfig()) => {
-  const workflow = getTruthmarkWorkflow("truthmark-preview");
-  return renderCopilotPromptFile(
-    workflow.description,
-    renderTruthPreviewSkillBody(config)
+  void config;
+  return renderCopilotWorkflowPrompt(
+    "truthmark-preview",
+    ".github/skills/truthmark-preview"
   );
 };
 var renderTruthmarkCopilotPortalPrompt = (config = defaultAgentConfig()) => {
-  const workflow = getTruthmarkWorkflow("truthmark-portal");
-  return renderCopilotPromptFile(
-    workflow.description,
-    renderTruthmarkPortalSkillBody(config)
+  void config;
+  return renderCopilotWorkflowPrompt(
+    "truthmark-portal",
+    ".github/skills/truthmark-portal"
   );
 };
 
@@ -4678,8 +4994,8 @@ var geminiFiles = (config, block) => {
   return files;
 };
 var instructionBlockFiles = (paths, block) => {
-  return paths.map((path13) => ({
-    path: path13,
+  return paths.map((path12) => ({
+    path: path12,
     content: block,
     managedBlock: true
   }));
@@ -4803,16 +5119,16 @@ var upsertManagedBlock = (existingContent, block) => {
 
 ${block}`;
 };
-var writeManagedAgentsFile = async (rootDir, path13 = "AGENTS.md", block) => {
+var writeManagedAgentsFile = async (rootDir, path12 = "AGENTS.md", block) => {
   let existingContent = null;
   try {
-    existingContent = await fs7.readFile(resolveRepoPath(rootDir, path13), "utf8");
+    existingContent = await fs7.readFile(resolveRepoPath(rootDir, path12), "utf8");
   } catch (error) {
     if (!(error instanceof Error) || !("code" in error) || error.code !== "ENOENT") {
       throw error;
     }
   }
-  return writeRepoFile(rootDir, path13, upsertManagedBlock(existingContent, block));
+  return writeRepoFile(rootDir, path12, upsertManagedBlock(existingContent, block));
 };
 var diagnosticCategoryForPath = (filePath, config) => {
   if (filePath === "AGENTS.md") {
@@ -5078,8 +5394,53 @@ var checkAuthority = async (rootDir, config) => {
 // src/checks/frontmatter.ts
 import fs10 from "fs/promises";
 
+// src/markdown/frontmatter.ts
+import { parse as parse3 } from "yaml";
+var openingDelimiterPattern = /^(?:\uFEFF)?---[ \t]*(?:\r?\n|$)/u;
+var closingDelimiterPattern = /^---[ \t]*(?:\r?\n|$)/mu;
+var asRecord = (value) => {
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    return value;
+  }
+  return {};
+};
+var parseFrontmatter = (source, options = {}) => {
+  const openingMatch = openingDelimiterPattern.exec(source);
+  if (!openingMatch) {
+    return {
+      data: {},
+      content: source.replace(/^\uFEFF/u, "")
+    };
+  }
+  const bodyStart = openingMatch[0].length;
+  const bodyAndContent = source.slice(bodyStart);
+  const closingMatch = closingDelimiterPattern.exec(bodyAndContent);
+  if (!closingMatch || typeof closingMatch.index !== "number") {
+    return {
+      data: {},
+      content: source.replace(/^\uFEFF/u, "")
+    };
+  }
+  const yamlSource = bodyAndContent.slice(0, closingMatch.index);
+  const content = bodyAndContent.slice(closingMatch.index + closingMatch[0].length);
+  let data = {};
+  if (yamlSource.trim().length > 0) {
+    try {
+      data = asRecord(parse3(yamlSource));
+    } catch (error) {
+      if (options.throwOnInvalid) {
+        throw error;
+      }
+      data = {};
+    }
+  }
+  return {
+    data,
+    content
+  };
+};
+
 // src/markdown/parse.ts
-import matter from "gray-matter";
 import { unified } from "unified";
 import remarkParse from "remark-parse";
 import { visit } from "unist-util-visit";
@@ -5093,7 +5454,7 @@ var isInternalLink = (url) => {
   return url.startsWith("#") || !url.includes("://") && !url.startsWith("mailto:");
 };
 var parseMarkdownDocument = (source) => {
-  const parsed = matter(source);
+  const parsed = parseFrontmatter(source);
   const tree = unified().use(remarkParse).parse(parsed.content);
   const headings = [];
   const internalLinks = [];
@@ -5117,6 +5478,11 @@ var parseMarkdownDocument = (source) => {
 
 // src/checks/frontmatter.ts
 var isTruthDocumentKind2 = (value) => TRUTH_DOCUMENT_KINDS.includes(value);
+var ROUTE_RELATIONSHIP_FRONTMATTER_FIELDS = [
+  "realized_by",
+  "realizes",
+  "depends_on"
+];
 var checkFrontmatter = async (rootDir, config, markdownPaths, truthDocumentEntries = []) => {
   const diagnostics = [];
   const truthDocumentMap = new Map(
@@ -5131,6 +5497,7 @@ var checkFrontmatter = async (rootDir, config, markdownPaths, truthDocumentEntri
     const source = await fs10.readFile(absolutePath, "utf8");
     let document;
     try {
+      parseFrontmatter(source, { throwOnInvalid: true });
       document = parseMarkdownDocument(source);
     } catch (error) {
       diagnostics.push({
@@ -5163,6 +5530,28 @@ var checkFrontmatter = async (rootDir, config, markdownPaths, truthDocumentEntri
     }
     const routedTruthDocument = truthDocumentMap.get(markdownPath);
     const truthKind = document.frontmatter.truth_kind;
+    const truthLane = document.frontmatter.truth_lane;
+    const isTruthDocument = routedTruthDocument !== void 0 || truthKind !== void 0;
+    if (isTruthDocument) {
+      for (const field of ROUTE_RELATIONSHIP_FRONTMATTER_FIELDS) {
+        if (field in document.frontmatter) {
+          diagnostics.push({
+            category: "frontmatter",
+            severity: "error",
+            message: `Frontmatter field ${field} is not allowed on truth documents; author relationship metadata in fenced route YAML entries instead.`,
+            file: markdownPath
+          });
+        }
+      }
+    }
+    if (truthLane !== void 0 && truthLane !== "product" && truthLane !== "engineering") {
+      diagnostics.push({
+        category: "frontmatter",
+        severity: "error",
+        message: "Frontmatter truth_lane must be product or engineering.",
+        file: markdownPath
+      });
+    }
     if (truthKind !== void 0) {
       if (typeof truthKind !== "string" || !isTruthDocumentKind2(truthKind)) {
         diagnostics.push({
@@ -5181,6 +5570,14 @@ var checkFrontmatter = async (rootDir, config, markdownPaths, truthDocumentEntri
           file: markdownPath
         });
       }
+      if (typeof truthKind === "string" && isTruthDocumentKind2(truthKind) && truthLane !== void 0 && (truthLane === "product" || truthLane === "engineering") && truthLane !== laneForTruthDocumentKind(truthKind)) {
+        diagnostics.push({
+          category: "frontmatter",
+          severity: "error",
+          message: `Frontmatter truth_lane ${truthLane} must match truth_kind ${truthKind}.`,
+          file: markdownPath
+        });
+      }
     }
   }
   return diagnostics;
@@ -5340,7 +5737,9 @@ var resolveAreaRouting = async (rootDir, config) => {
     };
   }
   const rootParsed = parseAreasMarkdown(rootRead.source ?? "", {
-    truthDocsRoot: config.truthDocsRoot
+    truthDocsRoot: config.truthDocsRoot,
+    productTruthRoot: config.productTruthRoot,
+    engineeringTruthRoot: config.engineeringTruthRoot
   });
   diagnostics.push(
     ...rootParsed.diagnostics.map((diagnostic) => ({
@@ -5379,7 +5778,9 @@ var resolveAreaRouting = async (rootDir, config) => {
       }
       routeFiles.push(areaFile);
       const childParsed = parseAreasMarkdown(childRead.source ?? "", {
-        truthDocsRoot: config.truthDocsRoot
+        truthDocsRoot: config.truthDocsRoot,
+        productTruthRoot: config.productTruthRoot,
+        engineeringTruthRoot: config.engineeringTruthRoot
       });
       diagnostics.push(
         ...childParsed.diagnostics.map((diagnostic) => ({
@@ -5656,11 +6057,115 @@ var BROAD_CODE_SURFACES = /* @__PURE__ */ new Set([
 var isBroadCodeSurface = (pattern) => {
   return BROAD_CODE_SURFACES.has(pattern.replace(/\/\*\*\/\*$/u, "/**"));
 };
+var PRODUCT_LINK_REVIEW_KINDS = /* @__PURE__ */ new Set([
+  "engineering-behavior",
+  "engineering-workflow",
+  "engineering-contract"
+]);
+var normalizeRoot = (value) => value.replaceAll("\\", "/").replace(/\/+$/u, "");
+var validateLaneShape = (entry, config, areaName) => {
+  const diagnostics = [];
+  const productRoot = normalizeRoot(resolveProductTruthRoot(config));
+  const engineeringRoot = normalizeRoot(resolveEngineeringTruthRoot(config));
+  const normalizedPath = entry.path.replaceAll("\\", "/");
+  const expectedLane = laneForTruthDocumentKind(entry.kind);
+  if (entry.lane !== expectedLane) {
+    diagnostics.push({
+      category: "lane-shape",
+      severity: "error",
+      message: `Truth document ${entry.path} declares ${entry.kind} in ${entry.lane} lane; ${entry.kind} belongs to the ${expectedLane} lane.`,
+      area: areaName,
+      file: entry.path
+    });
+  }
+  if (entry.lane === "product" && !normalizedPath.startsWith(`${productRoot}/`)) {
+    diagnostics.push({
+      category: "lane-shape",
+      severity: "error",
+      message: `Product truth document ${entry.path} must live under ${productRoot}.`,
+      area: areaName,
+      file: entry.path
+    });
+  }
+  if (entry.lane === "engineering" && !normalizedPath.startsWith(`${engineeringRoot}/`)) {
+    diagnostics.push({
+      category: "lane-shape",
+      severity: "error",
+      message: `Engineering truth document ${entry.path} must live under ${engineeringRoot}.`,
+      area: areaName,
+      file: entry.path
+    });
+  }
+  return diagnostics;
+};
+var validateRelationshipTargets = (entries) => {
+  const diagnostics = [];
+  const byPath = new Map(entries.map((entry) => [entry.path, entry]));
+  for (const entry of entries) {
+    for (const target of entry.realizedBy) {
+      const targetEntry = byPath.get(target);
+      if (!targetEntry) {
+        diagnostics.push({
+          category: "traceability",
+          severity: "error",
+          message: `Product truth document ${entry.path} declares missing engineering realization ${target}.`,
+          file: entry.path
+        });
+      } else if (targetEntry.lane !== "engineering") {
+        diagnostics.push({
+          category: "traceability",
+          severity: "error",
+          message: `Product truth document ${entry.path} realized_by target ${target} must point to engineering truth.`,
+          file: entry.path
+        });
+      }
+    }
+    for (const target of entry.realizes) {
+      const targetEntry = byPath.get(target);
+      if (!targetEntry) {
+        diagnostics.push({
+          category: "traceability",
+          severity: "error",
+          message: `Engineering truth document ${entry.path} declares missing product truth ${target}.`,
+          file: entry.path
+        });
+      } else if (targetEntry.lane !== "product") {
+        diagnostics.push({
+          category: "traceability",
+          severity: "error",
+          message: `Engineering truth document ${entry.path} realizes target ${target} must point to product truth.`,
+          file: entry.path
+        });
+      }
+    }
+  }
+  return diagnostics;
+};
+var validateMissingProductLinkReviews = (entries, reportedPaths) => {
+  const diagnostics = [];
+  const hasProductTruth = entries.some((entry) => entry.lane === "product");
+  if (!hasProductTruth) {
+    return diagnostics;
+  }
+  for (const entry of entries) {
+    if (entry.lane === "engineering" && PRODUCT_LINK_REVIEW_KINDS.has(entry.kind) && entry.realizes.length === 0 && !reportedPaths.has(entry.path)) {
+      reportedPaths.add(entry.path);
+      diagnostics.push({
+        category: "traceability",
+        severity: "review",
+        message: `User-visible engineering truth document ${entry.path} should link product truth with realizes when it implements a product capability.`,
+        file: entry.path
+      });
+    }
+  }
+  return diagnostics;
+};
 var checkAreas = async (rootDir, config) => {
   const routing = await resolveAreaRouting(rootDir, {
     rootIndex: config.truthmark.paths.routesIndex,
     areaFilesRoot: config.truthmark.paths.routeAreasRoot,
-    truthDocsRoot: resolveTruthDocsRoot(config)
+    productTruthRoot: resolveProductTruthRoot(config),
+    engineeringTruthRoot: resolveEngineeringTruthRoot(config)
   });
   const discoveredCodeFiles = await fg4([...COVERAGE_SCAN_PATTERNS], {
     cwd: rootDir,
@@ -5676,6 +6181,7 @@ var checkAreas = async (rootDir, config) => {
   const truthDocumentPaths = [];
   const seenTruthDocumentPaths = /* @__PURE__ */ new Set();
   const truthDocumentEntryMap = /* @__PURE__ */ new Map();
+  const reportedMissingProductLinkPaths = /* @__PURE__ */ new Set();
   const areaCoverage = routing.areas.map((area) => ({
     area,
     valid: true,
@@ -5693,6 +6199,7 @@ var checkAreas = async (rootDir, config) => {
   const truthReferences = routing.truthDocumentReferences;
   for (const area of truthReferences) {
     let areaHasTruthDocumentErrors = false;
+    const areaTruthDocumentEntries = [];
     const registerTruthDocumentEntry = (truthDocumentEntry) => {
       const existingEntry = truthDocumentEntryMap.get(truthDocumentEntry.path);
       if (existingEntry && existingEntry.kind !== truthDocumentEntry.kind) {
@@ -5705,16 +6212,39 @@ var checkAreas = async (rootDir, config) => {
         });
         return false;
       }
+      if (existingEntry && existingEntry.lane !== truthDocumentEntry.lane) {
+        diagnostics.push({
+          category: "area-index",
+          severity: "error",
+          message: `Truth document ${truthDocumentEntry.path} is routed with conflicting lanes ${existingEntry.lane} and ${truthDocumentEntry.lane}.`,
+          area: area.name,
+          file: truthDocumentEntry.path
+        });
+        return false;
+      }
       if (!existingEntry) {
         truthDocumentEntryMap.set(truthDocumentEntry.path, truthDocumentEntry);
+      } else {
+        truthDocumentEntryMap.set(
+          truthDocumentEntry.path,
+          mergeTruthDocumentEntryRelationships(
+            existingEntry,
+            truthDocumentEntry
+          )
+        );
       }
+      areaTruthDocumentEntries.push(truthDocumentEntry);
+      diagnostics.push(
+        ...validateLaneShape(truthDocumentEntry, config, area.name)
+      );
       return true;
     };
-    for (const truthDocument of area.truthDocuments) {
+    for (const [
+      truthDocumentIndex,
+      truthDocument
+    ] of area.truthDocuments.entries()) {
+      const routedEntry = area.truthDocumentEntries[truthDocumentIndex];
       if (looksLikeGlob2(truthDocument)) {
-        const routedGlobEntry = area.truthDocumentEntries.find(
-          (entry) => entry.path === truthDocument
-        );
         const matches = (await fg4([truthDocument], { cwd: rootDir, onlyFiles: true })).sort();
         if (matches.length === 0) {
           diagnostics.push({
@@ -5746,8 +6276,8 @@ var checkAreas = async (rootDir, config) => {
             seenTruthDocumentPaths.add(match);
             truthDocumentPaths.push(match);
           }
-          if (routedGlobEntry && !registerTruthDocumentEntry({
-            ...routedGlobEntry,
+          if (routedEntry && !registerTruthDocumentEntry({
+            ...routedEntry,
             path: match
           })) {
             areaHasTruthDocumentErrors = true;
@@ -5785,7 +6315,6 @@ var checkAreas = async (rootDir, config) => {
         seenTruthDocumentPaths.add(truthDocument);
         truthDocumentPaths.push(truthDocument);
       }
-      const routedEntry = area.truthDocumentEntries.find((entry) => entry.path === truthDocument);
       if (routedEntry && !registerTruthDocumentEntry(routedEntry)) {
         areaHasTruthDocumentErrors = true;
       }
@@ -5800,6 +6329,12 @@ var checkAreas = async (rootDir, config) => {
         matchingArea.valid = false;
       }
     }
+    diagnostics.push(
+      ...validateMissingProductLinkReviews(
+        areaTruthDocumentEntries,
+        reportedMissingProductLinkPaths
+      )
+    );
   }
   for (const entry of areaCoverage) {
     const { area } = entry;
@@ -5826,7 +6361,10 @@ var checkAreas = async (rootDir, config) => {
         let containedMatches = 0;
         for (const match of matches) {
           try {
-            await assertRepoContainment(rootDir, resolveRepoPath(rootDir, match));
+            await assertRepoContainment(
+              rootDir,
+              resolveRepoPath(rootDir, match)
+            );
             containedMatches += 1;
           } catch {
             diagnostics.push({
@@ -5898,10 +6436,12 @@ var checkAreas = async (rootDir, config) => {
   const topologyPressureCount = broadAreaCount + diagnostics.filter(
     (diagnostic) => diagnostic.category === "area-index" && diagnostic.severity === "review"
   ).length;
+  const truthDocumentEntries = [...truthDocumentEntryMap.values()];
+  diagnostics.push(...validateRelationshipTargets(truthDocumentEntries));
   return {
     diagnostics,
     truthDocumentPaths,
-    truthDocumentEntries: [...truthDocumentEntryMap.values()],
+    truthDocumentEntries,
     routePrecision: {
       leafAreaCount: routing.areas.length,
       broadAreaCount
@@ -5913,7 +6453,38 @@ var checkAreas = async (rootDir, config) => {
 // src/checks/decisions.ts
 import fs14 from "fs/promises";
 import micromatch5 from "micromatch";
-var REQUIRED_DECISION_HEADINGS = ["Scope", "Product Decisions", "Rationale"];
+var PRODUCT_CAPABILITY_REQUIRED_HEADINGS = [
+  "Capability Promise",
+  "Users And Value",
+  "Capability Scope",
+  "Current Product Behavior",
+  "Acceptance Criteria",
+  "Product Decisions",
+  "Engineering Realization Links",
+  "Non-Goals"
+];
+var ENGINEERING_REQUIRED_HEADINGS = [
+  "Purpose",
+  "Scope",
+  "Current Implementation Behavior",
+  "Source References",
+  "Product Truth Links",
+  "Maintenance Notes"
+];
+var FORBIDDEN_PRODUCT_HEADINGS = [
+  "Execution Flow",
+  "Execution Model",
+  "Generated File Inventory",
+  "CLI Envelope Details",
+  "Data And Control Flow"
+];
+var FORBIDDEN_ENGINEERING_HEADINGS = [
+  "Product Promise",
+  "User / Stakeholder Value",
+  "Product Decisions",
+  "Product Rationale",
+  "Business Boundary"
+];
 var isTruthDocumentKind3 = (value) => {
   return TRUTH_DOCUMENT_KINDS.includes(value);
 };
@@ -5921,16 +6492,18 @@ var escapeRegExp2 = (value) => {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 };
 var hasHeading = (source, heading) => {
-  return new RegExp(`^#{2,3}\\s+${escapeRegExp2(heading)}\\s*$`, "mu").test(source);
+  return new RegExp(`^#{2,3}\\s+${escapeRegExp2(heading)}\\s*$`, "mu").test(
+    source
+  );
 };
 var kindSpecificHeadingMessages = (source, kind) => {
   if (kind === null) {
     return [];
   }
-  if (kind === "behavior") {
-    return hasHeading(source, "Current Behavior") ? [] : ["Current Behavior"];
+  if (kind === "engineering-behavior") {
+    return hasHeading(source, "Current Implementation Behavior") ? [] : ["Current Implementation Behavior"];
   }
-  if (kind === "contract") {
+  if (kind === "engineering-contract") {
     const missingMessages = [];
     if (!hasHeading(source, "Contract Surface")) {
       missingMessages.push("Contract Surface");
@@ -5940,10 +6513,10 @@ var kindSpecificHeadingMessages = (source, kind) => {
     }
     return missingMessages;
   }
-  if (kind === "architecture") {
+  if (kind === "engineering-architecture") {
     return hasHeading(source, "Boundaries") || hasHeading(source, "Components") ? [] : ["Boundaries or Components"];
   }
-  if (kind === "workflow") {
+  if (kind === "engineering-workflow") {
     const missingMessages = [];
     if (!hasHeading(source, "Triggers")) {
       missingMessages.push("Triggers");
@@ -5953,23 +6526,34 @@ var kindSpecificHeadingMessages = (source, kind) => {
     }
     return missingMessages;
   }
-  if (kind === "operations") {
+  if (kind === "engineering-operations") {
     return hasHeading(source, "Runtime Topology") || hasHeading(source, "Configuration") ? [] : ["Runtime Topology or Configuration"];
   }
-  if (kind === "test-behavior") {
+  if (kind === "engineering-test-behavior") {
     const missingMessages = [];
     if (!hasHeading(source, "Execution Model")) {
       missingMessages.push("Execution Model");
     }
     if (!hasHeading(source, "Fixtures And Data Model") && !hasHeading(source, "Assertions And Invariants")) {
-      missingMessages.push("Fixtures And Data Model or Assertions And Invariants");
+      missingMessages.push(
+        "Fixtures And Data Model or Assertions And Invariants"
+      );
     }
     return missingMessages;
   }
   return [];
 };
+var productRequiredHeadings = (kind) => {
+  if (kind === "product-capability") {
+    return PRODUCT_CAPABILITY_REQUIRED_HEADINGS;
+  }
+  return PRODUCT_CAPABILITY_REQUIRED_HEADINGS;
+};
 var decisionTruthGlobs = (config) => {
-  return [`${resolveTruthDocsRoot(config)}/**/*.md`];
+  return [
+    `${resolveProductTruthRoot(config)}/**/*.md`,
+    `${resolveEngineeringTruthRoot(config)}/**/*.md`
+  ];
 };
 var isDecisionTruthCandidate = (config, filePath) => {
   return !filePath.endsWith("/README.md") && micromatch5.isMatch(filePath, decisionTruthGlobs(config));
@@ -5983,25 +6567,43 @@ var checkDecisionSections = async (rootDir, config, markdownPaths, truthDocument
     (filePath) => truthDocumentMap.has(filePath) || isDecisionTruthCandidate(config, filePath)
   ).sort();
   for (const filePath of candidatePaths) {
-    const source = await fs14.readFile(resolveRepoPath(rootDir, filePath), "utf8");
+    const source = await fs14.readFile(
+      resolveRepoPath(rootDir, filePath),
+      "utf8"
+    );
     const document = parseMarkdownDocument(source);
     const routedTruthDocument = truthDocumentMap.get(filePath);
     const frontmatterTruthKind = typeof document.frontmatter.truth_kind === "string" ? document.frontmatter.truth_kind : null;
     const routedTruthKind = routedTruthDocument?.kindSource === "defaulted" ? null : routedTruthDocument?.kind;
     const truthKind = routedTruthKind ?? (frontmatterTruthKind && isTruthDocumentKind3(frontmatterTruthKind) ? frontmatterTruthKind : inferTruthDocumentKindFromPath(filePath));
-    const missingHeadings = REQUIRED_DECISION_HEADINGS.filter(
+    const lane = routedTruthDocument?.lane ?? (truthKind ? laneForTruthDocumentKind(truthKind) : filePath.startsWith(resolveProductTruthRoot(config)) ? "product" : "engineering");
+    const requiredHeadings = lane === "product" ? productRequiredHeadings(truthKind) : ENGINEERING_REQUIRED_HEADINGS;
+    const missingHeadings = requiredHeadings.filter(
       (heading) => !hasHeading(source, heading)
     );
-    missingHeadings.push(...kindSpecificHeadingMessages(source, truthKind));
-    if (missingHeadings.length === 0) {
+    if (lane === "engineering") {
+      missingHeadings.push(...kindSpecificHeadingMessages(source, truthKind));
+    }
+    const forbiddenHeadings = (lane === "product" ? FORBIDDEN_PRODUCT_HEADINGS : FORBIDDEN_ENGINEERING_HEADINGS).filter((heading) => hasHeading(source, heading));
+    if (missingHeadings.length === 0 && forbiddenHeadings.length === 0) {
       continue;
     }
-    diagnostics.push({
-      category: "doc-structure",
-      severity: "review",
-      message: `Canonical truth doc ${filePath} should include ${missingHeadings.join(" and ")} section(s). Decisions should live beside current behavior, not in timestamped planning logs.`,
-      file: filePath
-    });
+    if (missingHeadings.length > 0) {
+      diagnostics.push({
+        category: "doc-structure",
+        severity: "review",
+        message: `Canonical ${lane} truth doc ${filePath} should include ${missingHeadings.join(" and ")} section(s). Product truth says what must be true and why; engineering truth says how the repository currently realizes it.`,
+        file: filePath
+      });
+    }
+    if (forbiddenHeadings.length > 0) {
+      diagnostics.push({
+        category: "lane-drift",
+        severity: "error",
+        message: `Canonical ${lane} truth doc ${filePath} contains wrong-lane section(s): ${forbiddenHeadings.join(", ")}.`,
+        file: filePath
+      });
+    }
   }
   return diagnostics;
 };
@@ -6093,17 +6695,90 @@ var checkGeneratedSurfaces = async (rootDir, config) => {
 import path10 from "path";
 import micromatch7 from "micromatch";
 
-// src/repo-index/build.ts
-import fs18 from "fs/promises";
-import path8 from "path";
-
 // src/repo-index/file-tree.ts
 import fs16 from "fs/promises";
-import path6 from "path";
+import path7 from "path";
 import { execa as execa2 } from "execa";
 import fg5 from "fast-glob";
-import matter2 from "gray-matter";
 import micromatch6 from "micromatch";
+
+// src/truth/source-references.ts
+import path6 from "path";
+var repoRootPrefixes = [
+  ".codex/",
+  ".github/",
+  ".truthmark/",
+  "docs/",
+  "src/",
+  "tests/"
+];
+var sourceReferencesHeadingPattern = /^##\s+Source References\s*$/imu;
+var nextSecondLevelHeadingPattern = /^##\s+/imu;
+var bulletReferencePattern = /^\s*[-*]\s+(.+?)\s*$/u;
+var markdownLinkPattern = /^\s*\[[^\]]+\]\(([^)]+)\)\s*$/u;
+var backtickPathPattern = /^\s*`([^`]+)`\s*$/u;
+var normalizeSourceReferencePath = (truthDocPath, referencePath) => {
+  const strippedPath = referencePath.split("#")[0]?.trim() ?? "";
+  const isRepoRelative = repoRootPrefixes.some(
+    (prefix) => strippedPath.startsWith(prefix)
+  );
+  if (!isRepoRelative && (strippedPath.startsWith(".") || !strippedPath.includes("/"))) {
+    return path6.posix.normalize(
+      path6.posix.join(path6.posix.dirname(truthDocPath), strippedPath)
+    );
+  }
+  return path6.posix.normalize(strippedPath);
+};
+var normalizeReferenceText = (value) => {
+  const trimmed = value.trim();
+  const markdownLinkMatch = markdownLinkPattern.exec(trimmed);
+  if (markdownLinkMatch) {
+    return markdownLinkMatch[1]?.trim() ?? "";
+  }
+  const backtickMatch = backtickPathPattern.exec(trimmed);
+  if (backtickMatch) {
+    return backtickMatch[1]?.trim() ?? "";
+  }
+  return trimmed;
+};
+var parseSourceReferencesSection = (content) => {
+  const headingMatch = sourceReferencesHeadingPattern.exec(content);
+  if (!headingMatch || typeof headingMatch.index !== "number") {
+    return [];
+  }
+  const sectionStart = headingMatch.index + headingMatch[0].length;
+  const afterHeading = content.slice(sectionStart);
+  const nextHeadingMatch = nextSecondLevelHeadingPattern.exec(afterHeading);
+  const section = nextHeadingMatch ? afterHeading.slice(0, nextHeadingMatch.index) : afterHeading;
+  const references = [];
+  for (const line of section.split("\n")) {
+    const bulletMatch = bulletReferencePattern.exec(line);
+    if (!bulletMatch) {
+      continue;
+    }
+    const reference = normalizeReferenceText(bulletMatch[1] ?? "");
+    if (reference.length > 0 && !reference.startsWith("{{")) {
+      references.push(reference);
+    }
+  }
+  return references;
+};
+var parseSourceReferences = (source, truthDocPath) => {
+  const parsed = parseFrontmatter(source);
+  const references = /* @__PURE__ */ new Set();
+  const frontmatterSourceOfTruth = Array.isArray(parsed.data.source_of_truth) ? parsed.data.source_of_truth : [];
+  for (const entry of frontmatterSourceOfTruth) {
+    if (typeof entry === "string") {
+      references.add(normalizeSourceReferencePath(truthDocPath, entry));
+    }
+  }
+  for (const entry of parseSourceReferencesSection(parsed.content)) {
+    references.add(normalizeSourceReferencePath(truthDocPath, entry));
+  }
+  return [...references].sort();
+};
+
+// src/repo-index/file-tree.ts
 var languageByExtension = /* @__PURE__ */ new Map([
   [".ts", "typescript"],
   [".tsx", "typescript"],
@@ -6117,12 +6792,8 @@ var languageByExtension = /* @__PURE__ */ new Map([
   [".yaml", "yaml"],
   [".toml", "toml"]
 ]);
-var sourceExtensions = /* @__PURE__ */ new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
-var isJavaScriptLikePath = (filePath) => {
-  return sourceExtensions.has(path6.posix.extname(filePath));
-};
 var isTestPath = (filePath) => {
-  return filePath.startsWith("tests/") || filePath.includes("/__tests__/") || /(?:^|[./-])(test|spec)\.[cm]?[jt]sx?$/u.test(path6.posix.basename(filePath));
+  return filePath.startsWith("tests/") || filePath.includes("/__tests__/") || /(?:^|[./-])(test|spec)\.[cm]?[jt]sx?$/u.test(path7.posix.basename(filePath));
 };
 var fileKind = (filePath, ignore) => {
   const classification = classifyPath(filePath, ignore);
@@ -6148,12 +6819,14 @@ var fileKind = (filePath, ignore) => {
 };
 var targetHintsForTest = (filePath) => {
   const hints = /* @__PURE__ */ new Set();
-  const basename = path6.posix.basename(filePath).replace(/\.(test|spec)\.[cm]?[jt]sx?$/u, "");
+  const basename = path7.posix.basename(filePath).replace(/\.(test|spec)\.[cm]?[jt]sx?$/u, "");
   if (basename.length > 0) {
     hints.add(basename);
   }
   const segments = filePath.split("/");
-  const testRootIndex = segments.findIndex((segment) => segment === "tests" || segment === "__tests__");
+  const testRootIndex = segments.findIndex(
+    (segment) => segment === "tests" || segment === "__tests__"
+  );
   if (testRootIndex >= 0) {
     for (const segment of segments.slice(testRootIndex + 1, -1)) {
       if (segment.length > 0) {
@@ -6165,6 +6838,9 @@ var targetHintsForTest = (filePath) => {
 };
 var defaultIgnore = [".git/**", "node_modules/**", "dist/**", "build/**"];
 var normalizePath2 = (filePath) => filePath.replaceAll("\\", "/").replace(/^\.\/+/u, "");
+var isTruthDocumentKind4 = (value) => {
+  return typeof value === "string" && TRUTH_DOCUMENT_KINDS.includes(value);
+};
 var gitDiscoverableFiles = async (rootDir) => {
   const result = await execa2(
     "git",
@@ -6196,7 +6872,7 @@ var discoverRepoFiles = async (rootDir, ignore) => {
   for (const filePath of discoveredFiles.filter((entry) => !isIgnoredPath(entry, ignore)).sort()) {
     let stat;
     try {
-      stat = await fs16.stat(path6.join(rootDir, filePath));
+      stat = await fs16.stat(path7.join(rootDir, filePath));
     } catch (error) {
       if (error instanceof Error && "code" in error && error.code === "ENOENT") {
         continue;
@@ -6206,7 +6882,7 @@ var discoverRepoFiles = async (rootDir, ignore) => {
     if (!stat.isFile()) {
       continue;
     }
-    const extension = path6.posix.extname(filePath);
+    const extension = path7.posix.extname(filePath);
     const kind = fileKind(filePath, ignore);
     files.push({
       path: filePath,
@@ -6220,17 +6896,23 @@ var discoverRepoFiles = async (rootDir, ignore) => {
       });
     }
     if (kind === "doc") {
-      const source = await fs16.readFile(path6.join(rootDir, filePath), "utf8");
-      const parsed = matter2(source);
+      const source = await fs16.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;
-      const sourceOfTruth = Array.isArray(parsed.data.source_of_truth) ? parsed.data.source_of_truth.filter((entry) => typeof entry === "string") : [];
+      const sourceOfTruth = parseSourceReferences(source, filePath);
+      const truthKind = typeof parsed.data.truth_kind === "string" ? parsed.data.truth_kind : null;
+      const derivedTruthKind = isTruthDocumentKind4(truthKind) ? truthKind : null;
       docs.push({
         path: filePath,
         title,
-        docType: typeof parsed.data.doc_type === "string" ? parsed.data.doc_type : null,
-        truthKind: typeof parsed.data.truth_kind === "string" ? parsed.data.truth_kind : null,
-        sourceOfTruth: sourceOfTruth.sort()
+        docType: typeof parsed.data.doc_type === "string" ? parsed.data.doc_type : derivedTruthKind ? docTypeForTruthDocumentKind(derivedTruthKind) : null,
+        truthKind,
+        truthLane: typeof parsed.data.truth_lane === "string" ? parsed.data.truth_lane : derivedTruthKind ? laneForTruthDocumentKind(derivedTruthKind) : null,
+        sourceOfTruth: sourceOfTruth.sort(),
+        realizedBy: [],
+        realizes: [],
+        dependsOn: []
       });
     }
   }
@@ -6243,7 +6925,7 @@ var discoverRepoFiles = async (rootDir, ignore) => {
 
 // src/repo-index/package-metadata.ts
 import fs17 from "fs/promises";
-import path7 from "path";
+import path8 from "path";
 import fg6 from "fast-glob";
 var packageManagerFor = async (rootDir, packageDir) => {
   const lockfiles = [
@@ -6255,7 +6937,7 @@ var packageManagerFor = async (rootDir, packageDir) => {
   ];
   for (const [lockfile, manager] of lockfiles) {
     try {
-      await fs17.access(path7.join(rootDir, packageDir, lockfile));
+      await fs17.access(path8.join(rootDir, packageDir, lockfile));
       return manager;
     } catch {
       continue;
@@ -6272,8 +6954,8 @@ var discoverPackageMetadata = async (rootDir) => {
   });
   const packages = [];
   for (const packageFile of packageFiles.sort()) {
-    const packageDir = path7.posix.dirname(packageFile) === "." ? "" : path7.posix.dirname(packageFile);
-    const raw = JSON.parse(await fs17.readFile(path7.join(rootDir, packageFile), "utf8"));
+    const packageDir = path8.posix.dirname(packageFile) === "." ? "" : path8.posix.dirname(packageFile);
+    const raw = JSON.parse(await fs17.readFile(path8.join(rootDir, packageFile), "utf8"));
     const scripts = raw.scripts && typeof raw.scripts === "object" ? Object.keys(raw.scripts).sort() : [];
     packages.push({
       path: packageFile,
@@ -6288,6 +6970,21 @@ var discoverPackageMetadata = async (rootDir) => {
 };
 
 // src/repo-index/route-map.ts
+var mergedEntryMap = (entries) => {
+  const byPath = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    const existingEntry = byPath.get(entry.path);
+    if (existingEntry && existingEntry.kind === entry.kind && existingEntry.lane === entry.lane) {
+      byPath.set(
+        entry.path,
+        mergeTruthDocumentEntryRelationships(existingEntry, entry)
+      );
+    } else if (!existingEntry) {
+      byPath.set(entry.path, entry);
+    }
+  }
+  return byPath;
+};
 var buildRouteMap = async (rootDir) => {
   const loadResult = await loadConfig(rootDir);
   if (!loadResult.config) {
@@ -6300,8 +6997,12 @@ var buildRouteMap = async (rootDir) => {
   const routing = await resolveAreaRouting(rootDir, {
     rootIndex: loadResult.config.truthmark.paths.routesIndex,
     areaFilesRoot: loadResult.config.truthmark.paths.routeAreasRoot,
-    truthDocsRoot: resolveTruthDocsRoot(loadResult.config)
+    productTruthRoot: resolveProductTruthRoot(loadResult.config),
+    engineeringTruthRoot: resolveEngineeringTruthRoot(loadResult.config)
   });
+  const mergedTruthDocumentEntries = mergedEntryMap(
+    routing.areas.flatMap((area) => area.truthDocumentEntries)
+  );
   return {
     schemaVersion: "route-map/v0",
     routes: routing.areas.map((area) => ({
@@ -6312,102 +7013,20 @@ var buildRouteMap = async (rootDir) => {
       parentName: area.parentName,
       codeSurface: [...area.codeSurface].sort(),
       truthDocs: [...area.truthDocuments].sort(),
+      truthDocumentEntries: [
+        ...new Map(
+          area.truthDocumentEntries.map((entry) => [
+            entry.path,
+            mergedTruthDocumentEntries.get(entry.path) ?? entry
+          ])
+        ).values()
+      ].sort((left, right) => left.path.localeCompare(right.path)),
       updateTruthWhen: [...area.updateTruthWhen]
     })).sort((left, right) => left.key.localeCompare(right.key)),
     diagnostics: routing.diagnostics
   };
 };
 
-// src/repo-index/typescript-symbols.ts
-import ts from "typescript";
-var sortStrings = (values) => [...new Set(values)].sort();
-var hasExportModifier = (node) => {
-  return Boolean(
-    ts.canHaveModifiers(node) && ts.getModifiers(node)?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)
-  );
-};
-var declarationName = (node) => {
-  if (!node.name || !ts.isIdentifier(node.name)) {
-    return null;
-  }
-  return node.name.text;
-};
-var addExport = (exports, publicSymbols, path13, name, kind) => {
-  if (!name) {
-    return;
-  }
-  const entry = { path: path13, name, kind };
-  exports.push(entry);
-  publicSymbols.push(entry);
-};
-var analyzeTypeScriptSource = (path13, source) => {
-  const sourceFile = ts.createSourceFile(path13, source, ts.ScriptTarget.Latest, true);
-  const imports = [];
-  const exports = [];
-  const publicSymbols = [];
-  for (const statement of sourceFile.statements) {
-    if (ts.isImportDeclaration(statement) && ts.isStringLiteral(statement.moduleSpecifier)) {
-      const imported = [];
-      const clause = statement.importClause;
-      if (clause?.name) {
-        imported.push("default");
-      }
-      if (clause?.namedBindings && ts.isNamespaceImport(clause.namedBindings)) {
-        imported.push("*");
-      }
-      if (clause?.namedBindings && ts.isNamedImports(clause.namedBindings)) {
-        for (const element of clause.namedBindings.elements) {
-          imported.push(element.propertyName?.text ?? element.name.text);
-        }
-      }
-      imports.push({
-        from: path13,
-        specifier: statement.moduleSpecifier.text,
-        imported: sortStrings(imported)
-      });
-      continue;
-    }
-    if (ts.isExportDeclaration(statement)) {
-      if (statement.exportClause && ts.isNamedExports(statement.exportClause)) {
-        for (const element of statement.exportClause.elements) {
-          addExport(exports, publicSymbols, path13, element.name.text, "re-export");
-        }
-      }
-      continue;
-    }
-    if (ts.isFunctionDeclaration(statement) && hasExportModifier(statement)) {
-      addExport(exports, publicSymbols, path13, declarationName(statement), "function");
-      continue;
-    }
-    if (ts.isClassDeclaration(statement) && hasExportModifier(statement)) {
-      addExport(exports, publicSymbols, path13, declarationName(statement), "class");
-      continue;
-    }
-    if (ts.isInterfaceDeclaration(statement) && hasExportModifier(statement)) {
-      addExport(exports, publicSymbols, path13, declarationName(statement), "interface");
-      continue;
-    }
-    if (ts.isTypeAliasDeclaration(statement) && hasExportModifier(statement)) {
-      addExport(exports, publicSymbols, path13, declarationName(statement), "type");
-      continue;
-    }
-    if (ts.isEnumDeclaration(statement) && hasExportModifier(statement)) {
-      addExport(exports, publicSymbols, path13, declarationName(statement), "enum");
-      continue;
-    }
-    if (ts.isVariableStatement(statement) && hasExportModifier(statement)) {
-      for (const declaration of statement.declarationList.declarations) {
-        addExport(exports, publicSymbols, path13, declarationName(declaration), "const");
-      }
-    }
-  }
-  return {
-    imports: imports.sort((left, right) => left.specifier.localeCompare(right.specifier)),
-    exports: exports.sort((left, right) => left.name.localeCompare(right.name)),
-    publicSymbols: publicSymbols.sort((left, right) => left.name.localeCompare(right.name))
-  };
-};
-
 // src/repo-index/build.ts
 var buildRepoIndex = async (cwd) => {
   const repository = await getGitRepository(cwd);
@@ -6420,20 +7039,7 @@ var buildRepoIndex = async (cwd) => {
     discoverRepoFiles(rootDir, ignore),
     buildRouteMap(rootDir)
   ]);
-  const imports = [];
-  const exports = [];
-  const publicSymbols = [];
   diagnostics.push(...routeMap.diagnostics);
-  for (const file of fileTree.files) {
-    if (!isJavaScriptLikePath(file.path)) {
-      continue;
-    }
-    const source = await fs18.readFile(path8.join(rootDir, file.path), "utf8");
-    const analysis = analyzeTypeScriptSource(file.path, source);
-    imports.push(...analysis.imports);
-    exports.push(...analysis.exports);
-    publicSymbols.push(...analysis.publicSymbols);
-  }
   return {
     schemaVersion: "repo-index/v0",
     repository: {
@@ -6445,11 +7051,6 @@ var buildRepoIndex = async (cwd) => {
     files: fileTree.files,
     docs: fileTree.docs,
     tests: fileTree.tests,
-    imports: imports.sort((left, right) => `${left.from}:${left.specifier}`.localeCompare(`${right.from}:${right.specifier}`)),
-    exports: exports.sort((left, right) => `${left.path}:${left.name}`.localeCompare(`${right.path}:${right.name}`)),
-    publicSymbols: publicSymbols.sort(
-      (left, right) => `${left.path}:${left.name}`.localeCompare(`${right.path}:${right.name}`)
-    ),
     routeMap,
     diagnostics
   };
@@ -6459,7 +7060,7 @@ var buildRepoIndex = async (cwd) => {
 import { execa as execa4 } from "execa";
 
 // src/git/changes.ts
-import fs19 from "fs/promises";
+import fs18 from "fs/promises";
 import path9 from "path";
 import { execa as execa3 } from "execa";
 var normalizePath3 = (filePath) => {
@@ -6471,7 +7072,7 @@ var listChangedPaths = async (cwd, args) => {
 };
 var pathExists4 = async (filePath) => {
   try {
-    await fs19.access(filePath);
+    await fs18.access(filePath);
     return true;
   } catch {
     return false;
@@ -6599,17 +7200,9 @@ var getChangedFiles = async (cwd, base) => {
     diagnostics
   };
 };
-var readBaseFile = async (cwd, base, filePath) => {
-  const repository = await getGitRepository(cwd);
-  const result = await execa4("git", ["show", `${base}:${filePath}`], {
-    cwd: repository.worktreePath,
-    reject: false
-  });
-  return (result.exitCode ?? 1) === 0 ? result.stdout : null;
-};
 
 // src/impact/build.ts
-var uniqueSorted = (values) => [...new Set(values)].sort();
+var uniqueSorted2 = (values) => [...new Set(values)].sort();
 var routeMatchesFile = (route, filePath) => {
   return route.codeSurface.some((pattern) => micromatch7.isMatch(filePath, pattern));
 };
@@ -6624,65 +7217,15 @@ var toImpactRoute = (route) => ({
   truthDocs: [...route.truthDocs].sort(),
   codeSurface: [...route.codeSurface].sort()
 });
-var changedPathSet = (changedFiles) => {
-  return new Set(
-    changedFiles.flatMap((file) => [file.path, ...file.previousPath ? [file.previousPath] : []])
-  );
-};
 var changedFilePaths = (changedFile) => {
   return [changedFile.path, ...changedFile.previousPath ? [changedFile.previousPath] : []];
 };
-var resolveImportPath = (importEdge) => {
-  if (!importEdge.specifier.startsWith(".")) {
-    return null;
-  }
-  const basePath = path10.posix.normalize(path10.posix.join(path10.posix.dirname(importEdge.from), importEdge.specifier));
-  const withoutExtension = basePath.replace(/\.[cm]?[jt]sx?$/u, "");
-  return withoutExtension;
-};
-var importTargetsChangedFile = (importEdge, changedPath) => {
-  const resolved = resolveImportPath(importEdge);
-  if (!resolved) {
-    return false;
-  }
-  return changedPath.replace(/\.[cm]?[jt]sx?$/u, "") === resolved;
-};
 var pathSegments = (filePath) => filePath.split("/").filter(Boolean);
 var testHintMatchesChangedFile = (hints, changedPath) => {
   const changedBaseName = path10.posix.basename(changedPath);
   const changedSegments = pathSegments(changedPath);
   return hints.some((hint) => changedBaseName.startsWith(hint) || changedSegments.includes(hint));
 };
-var changedSymbolsFor = async (cwd, base, basePath, currentPath, currentExports) => {
-  if (!isJavaScriptLikePath(basePath) && !isJavaScriptLikePath(currentPath)) {
-    return [];
-  }
-  const baseSource = await readBaseFile(cwd, base, basePath);
-  const baseExports = baseSource ? analyzeTypeScriptSource(basePath, baseSource).exports : [];
-  const currentByName = new Map(currentExports.map((entry) => [entry.name, entry]));
-  const baseByName = new Map(baseExports.map((entry) => [entry.name, entry]));
-  const changes = [];
-  if (basePath !== currentPath) {
-    for (const entry of currentExports) {
-      changes.push({ path: currentPath, name: entry.name, kind: entry.kind, change: "added" });
-    }
-    for (const entry of baseExports) {
-      changes.push({ path: basePath, name: entry.name, kind: entry.kind, change: "removed" });
-    }
-    return changes;
-  }
-  for (const [name, entry] of currentByName) {
-    if (!baseByName.has(name)) {
-      changes.push({ path: currentPath, name, kind: entry.kind, change: "added" });
-    }
-  }
-  for (const [name, entry] of baseByName) {
-    if (!currentByName.has(name)) {
-      changes.push({ path: basePath, name, kind: entry.kind, change: "removed" });
-    }
-  }
-  return changes;
-};
 var buildImpactSet = async (cwd, options) => {
   const repository = await getGitRepository(cwd);
   const rootDir = repository.worktreePath;
@@ -6697,7 +7240,6 @@ var buildImpactSet = async (cwd, options) => {
   const affectedRoutes = /* @__PURE__ */ new Map();
   const affectedTruthDocs = [];
   const affectedTests = [];
-  const changedPublicSymbols = [];
   const knownTestPaths = new Set(repoIndex.tests.map((test) => test.path));
   for (const changedFile of changedFiles) {
     const routeCandidatePaths = changedFilePaths(changedFile);
@@ -6730,60 +7272,15 @@ var buildImpactSet = async (cwd, options) => {
         file: changedFile.path
       });
     }
-    const currentExports = repoIndex.exports.filter((entry) => entry.path === changedFile.path);
-    changedPublicSymbols.push(
-      ...await changedSymbolsFor(
-        rootDir,
-        options.base,
-        changedFile.previousPath ?? changedFile.path,
-        changedFile.path,
-        currentExports
-      )
-    );
-  }
-  const uniqueAffectedTruthDocs = uniqueSorted(affectedTruthDocs);
-  const changedPaths = changedPathSet(changedFiles);
-  for (const symbol of changedPublicSymbols) {
-    if (uniqueAffectedTruthDocs.length === 0) {
-      diagnostics.push({
-        category: "impact",
-        severity: "review",
-        message: `Changed public symbol ${symbol.name} in ${symbol.path} has no affected truth document.`,
-        file: symbol.path,
-        data: {
-          symbol: symbol.name,
-          change: symbol.change
-        }
-      });
-      continue;
-    }
-    if (!uniqueAffectedTruthDocs.some((truthDoc) => changedPaths.has(truthDoc))) {
-      diagnostics.push({
-        category: "impact",
-        severity: "review",
-        message: `Changed public symbol ${symbol.name} in ${symbol.path} has affected truth docs but none were changed in this impact set.`,
-        file: symbol.path,
-        data: {
-          symbol: symbol.name,
-          change: symbol.change,
-          affectedTruthDocs: uniqueAffectedTruthDocs
-        }
-      });
-    }
   }
+  const uniqueAffectedTruthDocs = uniqueSorted2(affectedTruthDocs);
   for (const test of repoIndex.tests) {
-    const testImports = repoIndex.imports.filter((edge) => edge.from === test.path);
-    const importsChangedFile = changedFiles.some(
-      (changedFile) => changedFilePaths(changedFile).some(
-        (filePath) => testImports.some((importEdge) => importTargetsChangedFile(importEdge, filePath))
-      )
-    );
     const hintMatchesChangedFile = changedFiles.some(
       (changedFile) => changedFilePaths(changedFile).some(
         (filePath) => testHintMatchesChangedFile(test.targetHints, filePath)
       )
     );
-    if (importsChangedFile || hintMatchesChangedFile) {
+    if (hintMatchesChangedFile) {
       affectedTests.push(test.path);
     }
   }
@@ -6796,10 +7293,7 @@ var buildImpactSet = async (cwd, options) => {
       (left, right) => left.key.localeCompare(right.key)
     ),
     affectedTruthDocs: uniqueAffectedTruthDocs,
-    affectedTests: uniqueSorted(affectedTests),
-    changedPublicSymbols: changedPublicSymbols.sort(
-      (left, right) => `${left.path}:${left.name}:${left.change}`.localeCompare(`${right.path}:${right.name}:${right.change}`)
-    ),
+    affectedTests: uniqueSorted2(affectedTests),
     diagnostics
   };
 };
@@ -6825,32 +7319,22 @@ var checkFreshness = async (rootDir, _config, _truthDocumentPaths, base) => {
 };
 
 // src/evidence/validate.ts
-import fs21 from "fs/promises";
+import fs20 from "fs/promises";
 import fg7 from "fast-glob";
 
 // src/evidence/parse.ts
-import fs20 from "fs/promises";
+import fs19 from "fs/promises";
 import path11 from "path";
-import matter3 from "gray-matter";
-import { parse as parse3 } from "yaml";
+import { parse as parse4 } from "yaml";
 var yamlFencePattern = /```ya?ml\s*\n([\s\S]*?)```/giu;
 var topLevelEvidenceMarkerPattern = /^evidence\s*:/imu;
-var repoRootPrefixes = [".codex/", ".github/", ".truthmark/", "docs/", "src/", "tests/"];
-var normalizeReferencePath = (truthDocPath, referencePath) => {
-  const strippedPath = referencePath.split("#")[0]?.trim() ?? "";
-  const isRepoRelative = repoRootPrefixes.some((prefix) => strippedPath.startsWith(prefix));
-  if (!isRepoRelative && (strippedPath.startsWith(".") || !strippedPath.includes("/"))) {
-    return path11.posix.normalize(path11.posix.join(path11.posix.dirname(truthDocPath), strippedPath));
-  }
-  return path11.posix.normalize(strippedPath);
-};
 var toEvidenceReference = (truthDocPath, raw) => {
   if (!raw || typeof raw !== "object" || !("path" in raw) || typeof raw.path !== "string") {
     return null;
   }
   return {
     truthDocPath,
-    path: normalizeReferencePath(truthDocPath, raw.path),
+    path: normalizeSourceReferencePath(truthDocPath, raw.path),
     symbol: "symbol" in raw && typeof raw.symbol === "string" ? raw.symbol : void 0,
     startLine: "start_line" in raw && typeof raw.start_line === "number" ? raw.start_line : void 0,
     endLine: "end_line" in raw && typeof raw.end_line === "number" ? raw.end_line : void 0,
@@ -6859,18 +7343,14 @@ var toEvidenceReference = (truthDocPath, raw) => {
   };
 };
 var parseEvidenceReferences = async (rootDir, truthDocPath) => {
-  const source = await fs20.readFile(path11.join(rootDir, truthDocPath), "utf8");
-  const parsed = matter3(source);
+  const source = await fs19.readFile(path11.join(rootDir, truthDocPath), "utf8");
+  const parsed = parseFrontmatter(source);
   const references = [];
-  const sourceOfTruth = Array.isArray(parsed.data.source_of_truth) ? parsed.data.source_of_truth : [];
-  for (const entry of sourceOfTruth) {
-    if (typeof entry !== "string") {
-      continue;
-    }
+  for (const entry of parseSourceReferences(source, truthDocPath)) {
     references.push({
       truthDocPath,
-      path: normalizeReferencePath(truthDocPath, entry),
-      source: "frontmatter"
+      path: entry,
+      source: "source-references"
     });
   }
   for (const match of parsed.content.matchAll(yamlFencePattern)) {
@@ -6878,7 +7358,7 @@ var parseEvidenceReferences = async (rootDir, truthDocPath) => {
     if (!topLevelEvidenceMarkerPattern.test(yamlBlock)) {
       continue;
     }
-    const block = parse3(yamlBlock);
+    const block = parse4(yamlBlock);
     const rawEvidence = block && typeof block === "object" && "evidence" in block ? block.evidence : null;
     if (!Array.isArray(rawEvidence)) {
       continue;
@@ -6896,7 +7376,7 @@ var parseEvidenceReferences = async (rootDir, truthDocPath) => {
 // src/evidence/validate.ts
 var pathExists5 = async (filePath) => {
   try {
-    await fs21.access(filePath);
+    await fs20.access(filePath);
     return true;
   } catch {
     return false;
@@ -6934,15 +7414,6 @@ var validateGlob = async (rootDir, reference) => {
   });
   return matches.length > 0 ? null : diagnosticFor(reference, `Referenced file pattern ${reference.path} does not match any file.`);
 };
-var validateSymbol = async (rootDir, reference) => {
-  if (!reference.symbol || !isJavaScriptLikePath(reference.path)) {
-    return null;
-  }
-  const source = await fs21.readFile(resolveRepoPath(rootDir, reference.path), "utf8");
-  const analysis = analyzeTypeScriptSource(reference.path, source);
-  const hasSymbol = analysis.publicSymbols.some((symbol) => symbol.name === reference.symbol);
-  return hasSymbol ? null : diagnosticFor(reference, `Evidence symbol ${reference.symbol} was not found in ${reference.path}.`);
-};
 var validateHash = async (rootDir, reference) => {
   if (!reference.contentHash) {
     return null;
@@ -6950,7 +7421,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 fs21.readFile(resolveRepoPath(rootDir, reference.path), "utf8");
+  const source = await fs20.readFile(resolveRepoPath(rootDir, reference.path), "utf8");
   const lines = source.split("\n");
   const startLine = reference.startLine ?? 1;
   const endLine = reference.endLine ?? lines.length;
@@ -6964,7 +7435,7 @@ var validateLineSpan = async (rootDir, reference) => {
   if (reference.startLine === void 0 && reference.endLine === void 0) {
     return null;
   }
-  const source = await fs21.readFile(resolveRepoPath(rootDir, reference.path), "utf8");
+  const source = await fs20.readFile(resolveRepoPath(rootDir, reference.path), "utf8");
   const lines = source.split("\n");
   const startLine = reference.startLine ?? 1;
   const endLine = reference.endLine ?? lines.length;
@@ -6983,10 +7454,6 @@ var validateReference = async (rootDir, reference) => {
       diagnostics.push(diagnosticFor(reference, `Referenced file ${reference.path} does not exist.`));
       return diagnostics;
     }
-    const symbolDiagnostic = await validateSymbol(rootDir, reference);
-    if (symbolDiagnostic) {
-      diagnostics.push(symbolDiagnostic);
-    }
     const lineSpanDiagnostic = await validateLineSpan(rootDir, reference);
     if (lineSpanDiagnostic) {
       diagnostics.push(lineSpanDiagnostic);
@@ -7243,190 +7710,6 @@ var runCheck = async (cwd, options = {}) => {
   };
 };
 
-// src/context-pack/build.ts
-import fs22 from "fs/promises";
-import path12 from "path";
-import fg8 from "fast-glob";
-var uniqueSorted2 = (values) => [...new Set(values)].sort();
-var repoRootPrefixes2 = [".codex/", ".github/", ".truthmark/", "docs/", "src/", "tests/"];
-var isGlobReference2 = (referencePath) => /[*?[\]{}()]/u.test(referencePath);
-var normalizeDocReferencePath = (docPath, referencePath) => {
-  const strippedPath = referencePath.split("#")[0]?.trim() ?? "";
-  if (strippedPath.length === 0 || strippedPath.startsWith("/")) {
-    return null;
-  }
-  const isRepoRelative = repoRootPrefixes2.some((prefix) => strippedPath.startsWith(prefix));
-  const normalized = isRepoRelative ? path12.posix.normalize(strippedPath) : path12.posix.normalize(path12.posix.join(path12.posix.dirname(docPath), strippedPath));
-  return normalized === ".." || normalized.startsWith("../") ? null : normalized;
-};
-var readIfExists = async (rootDir, filePath) => {
-  try {
-    return await fs22.readFile(path12.join(rootDir, filePath), "utf8");
-  } catch {
-    return null;
-  }
-};
-var boundContent = (content) => {
-  const lines = content.split("\n");
-  if (lines.length <= 200) {
-    return { content, truncated: false };
-  }
-  return {
-    content: [...lines.slice(0, 80), "...", ...lines.slice(-40)].join("\n"),
-    truncated: true
-  };
-};
-var boundedContent = (filePath, content, warnings) => {
-  const bounded = boundContent(content);
-  if (!bounded.truncated) {
-    return { path: filePath, content, truncated: false };
-  }
-  warnings.push({
-    category: "context-pack",
-    severity: "review",
-    message: `Context source file ${filePath} was truncated to fit ContextPack v0 bounds.`,
-    file: filePath
-  });
-  return {
-    path: filePath,
-    content: bounded.content,
-    truncated: true
-  };
-};
-var documentsFor = async (rootDir, paths, warnings) => {
-  const documents = [];
-  for (const filePath of uniqueSorted2(paths)) {
-    const content = await readIfExists(rootDir, filePath);
-    if (content !== null) {
-      const bounded = boundContent(content);
-      if (bounded.truncated) {
-        warnings.push({
-          category: "context-pack",
-          severity: "review",
-          message: `Context truth doc ${filePath} was truncated to fit ContextPack v0 bounds.`,
-          file: filePath
-        });
-      }
-      documents.push({ path: filePath, content: bounded.content, truncated: bounded.truncated });
-    }
-  }
-  return documents;
-};
-var sourceFilesFor = async (rootDir, paths, warnings) => {
-  const sourceFiles = [];
-  for (const filePath of uniqueSorted2(paths)) {
-    const content = await readIfExists(rootDir, filePath);
-    if (content !== null) {
-      sourceFiles.push(boundedContent(filePath, content, warnings));
-    }
-  }
-  return sourceFiles;
-};
-var sourceOfTruthPathsFor = async (rootDir, docs, truthDocPaths) => {
-  const selectedTruthDocs = new Set(truthDocPaths);
-  const sourcePaths = [];
-  for (const doc of docs) {
-    if (!selectedTruthDocs.has(doc.path)) {
-      continue;
-    }
-    for (const referencePath of doc.sourceOfTruth) {
-      const normalizedPath = normalizeDocReferencePath(doc.path, referencePath);
-      if (!normalizedPath) {
-        continue;
-      }
-      if (isGlobReference2(normalizedPath)) {
-        sourcePaths.push(
-          ...await fg8(normalizedPath, {
-            cwd: rootDir,
-            dot: true,
-            onlyFiles: true,
-            followSymbolicLinks: false
-          })
-        );
-      } else {
-        sourcePaths.push(normalizedPath);
-      }
-    }
-  }
-  return uniqueSorted2(sourcePaths);
-};
-var writePathsFor = (workflow, routeIndexPath, truthDocs, routes) => {
-  if (workflow === "truth-sync") {
-    return uniqueSorted2([routeIndexPath, ...truthDocs]);
-  }
-  if (workflow === "truth-document") {
-    return uniqueSorted2([routeIndexPath, ...truthDocs]);
-  }
-  return uniqueSorted2(routes.flatMap((route) => route.codeSurface));
-};
-var testCommandsFor = (affectedTests) => {
-  return affectedTests.length === 0 ? ["npm test"] : [`npm test -- ${affectedTests.join(" ")}`];
-};
-var buildContextPack = async (cwd, options) => {
-  const repoIndex = await buildRepoIndex(cwd);
-  const rootDir = repoIndex.repository.root;
-  const loadResult = await loadConfig(rootDir);
-  const config = loadResult.config ?? (loadResult.status === "missing" ? createDefaultConfig() : null);
-  const impactSet = options.base ? await buildImpactSet(rootDir, { base: options.base }) : null;
-  const routeMap = impactSet ? repoIndex.routeMap : repoIndex.routeMap;
-  const warnings = loadResult.status === "invalid" ? [...loadResult.diagnostics] : [];
-  const truthDocPaths = impactSet?.affectedTruthDocs ?? (options.workflow === "truth-realize" ? [] : routeMap.routes.flatMap((route) => route.truthDocs));
-  const contextRoutes = impactSet?.affectedRoutes ?? (options.workflow === "truth-realize" ? [] : routeMap.routes);
-  if (options.workflow === "truth-realize" && !impactSet) {
-    warnings.push({
-      category: "context-pack",
-      severity: "review",
-      message: "truth-realize requires --base to derive bounded allowed write paths."
-    });
-  }
-  const sourceOfTruthPaths = await sourceOfTruthPathsFor(rootDir, repoIndex.docs, truthDocPaths);
-  const sourceFilePaths = uniqueSorted2([
-    ...impactSet?.changedFiles.filter((file) => !file.deleted).map((file) => file.path) ?? [],
-    ...sourceOfTruthPaths
-  ]);
-  return {
-    schemaVersion: "context-pack/v0",
-    workflow: options.workflow,
-    base: options.base ?? null,
-    impactSet,
-    routeMap,
-    allowedWritePaths: config === null ? [] : writePathsFor(
-      options.workflow,
-      config.truthmark.paths.routesIndex,
-      truthDocPaths,
-      contextRoutes
-    ),
-    truthDocs: await documentsFor(rootDir, truthDocPaths, warnings),
-    sourceFiles: await sourceFilesFor(rootDir, sourceFilePaths, warnings),
-    testCommands: testCommandsFor(impactSet?.affectedTests ?? []),
-    warnings
-  };
-};
-
-// src/context-pack/render.ts
-var renderContextPackMarkdown = (pack) => {
-  const lines = [
-    `# Truthmark ContextPack (${pack.workflow})`,
-    "",
-    `Schema: ${pack.schemaVersion}`,
-    `Base: ${pack.base ?? "none"}`,
-    "",
-    "## Allowed Write Paths",
-    ...pack.allowedWritePaths.map((filePath) => `- ${filePath}`),
-    "",
-    "## Truth Docs",
-    ...pack.truthDocs.map((doc) => `- ${doc.path}${doc.truncated ? " (truncated)" : ""}`),
-    "",
-    "## Source Files",
-    ...pack.sourceFiles.map((file) => `- ${file.path}${file.truncated ? " (truncated)" : ""}`),
-    "",
-    "## Test Commands",
-    ...pack.testCommands.map((command) => `- ${command}`)
-  ];
-  return `${lines.join("\n")}
-`;
-};
-
 // src/workflow-state/build.ts
 import { execa as execa5 } from "execa";
 
@@ -7533,7 +7816,7 @@ var applicabilityFor = (workflow, diagnostics, impactSet) => {
     return { state: isWriteCapable(workflow) ? "blocked" : "not_applicable", reasons };
   }
   if (workflow === "truthmark-sync" && !impactSet) {
-    reasons.push("truthmark-sync requires --base to derive bounded truth-doc write paths.");
+    reasons.push("truthmark-sync requires --base to derive changed-file impact before exposing sync write paths.");
     return { state: "blocked", reasons };
   }
   if (workflow === "truthmark-realize" && !impactSet) {
@@ -7555,9 +7838,8 @@ var contextDataFor = (workflow, repoIndex, config, impactSet) => {
     return {};
   }
   const routeFiles = routeFilesFor(repoIndex);
-  const truthDocs = uniqueSorted4(
-    impactSet?.affectedTruthDocs ?? repoIndex.routeMap.routes.flatMap((route) => route.truthDocs)
-  );
+  const indexedTruthDocs = uniqueSorted4(repoIndex.routeMap.routes.flatMap((route) => route.truthDocs));
+  const truthDocs = workflow === "truthmark-sync" ? indexedTruthDocs : uniqueSorted4(impactSet?.affectedTruthDocs ?? indexedTruthDocs);
   return {
     routeIndexPath: config.truthmark.paths.routesIndex,
     routeFiles,
@@ -7576,7 +7858,7 @@ var nextStepsFor = (workflow, applicability, comparisonBase) => {
   }
   if ((workflow === "truthmark-sync" || workflow === "truthmark-realize") && applicability.state === "blocked" && !comparisonBase) {
     return [
-      workflow === "truthmark-sync" ? "Rerun with --base <ref> so Truthmark can derive bounded truth-doc write paths." : "Rerun with --base <ref> so Truthmark can derive bounded allowed code-write paths."
+      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."
     ];
   }
   return [];
@@ -7612,7 +7894,8 @@ var buildWorkflowState = async (cwd, options) => {
     checks: {
       required: [...manifestEntry.requiredGates],
       recommended: [...manifestEntry.positiveTriggers],
-      helpers: helperCommandsFor2(options.workflow)
+      helpers: helperCommandsFor2(options.workflow),
+      affectedTests: impactSet?.affectedTests ?? []
     },
     nextSteps: nextStepsFor(options.workflow, applicability, comparisonBase),
     reportSections: [...manifestEntry.reportSections]
@@ -7620,7 +7903,7 @@ var buildWorkflowState = async (cwd, options) => {
 };
 
 // src/cli/handlers.ts
-import fs23 from "fs/promises";
+import fs21 from "fs/promises";
 
 // src/agents/workflow-helper-validation.ts
 import { parse as parseYaml2 } from "yaml";
@@ -7982,12 +8265,6 @@ var runImpact = async (options) => {
     }
   };
 };
-var isContextPackWorkflow = (value) => {
-  return value === "truth-sync" || value === "truth-document" || value === "truth-realize";
-};
-var isContextMarkdownFormat = (value) => {
-  return value === void 0 || value === "markdown";
-};
 var isTruthmarkWorkflowId = (value) => {
   return typeof value === "string" && TRUTHMARK_WORKFLOW_IDS.includes(value);
 };
@@ -8007,7 +8284,7 @@ var invalidWorkflowResult = (command, workflow) => ({
 });
 var readHelperFile = async (filePath, helper) => {
   try {
-    return await fs23.readFile(filePath, "utf8");
+    return await fs21.readFile(filePath, "utf8");
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     return { ok: false, helper, errors: [`could not read file: ${message}`] };
@@ -8032,63 +8309,6 @@ var runValidateWriteLease = async (leaseFile, changedFilesFile) => {
   }
   return validateWriteLeaseText(leaseText, changedText);
 };
-var runContext = async (options) => {
-  if (!isContextPackWorkflow(options.workflow)) {
-    return {
-      command: "context",
-      summary: "Truthmark context requires a supported --workflow value.",
-      diagnostics: [
-        {
-          category: "context-pack",
-          severity: "error",
-          message: "truthmark context requires --workflow truth-sync, truth-document, or truth-realize."
-        }
-      ]
-    };
-  }
-  if (options.format === "json") {
-    return {
-      command: "context",
-      summary: "Truthmark context no longer supports JSON ContextPack output.",
-      diagnostics: [
-        {
-          category: "context-pack",
-          severity: "error",
-          message: "JSON ContextPack output was removed in v2; use --format markdown."
-        }
-      ]
-    };
-  }
-  if (!isContextMarkdownFormat(options.format)) {
-    return {
-      command: "context",
-      summary: "Truthmark context requires a supported --format value.",
-      diagnostics: [
-        {
-          category: "context-pack",
-          severity: "error",
-          message: "truthmark context supports only --format markdown; JSON ContextPack output was removed in v2."
-        }
-      ]
-    };
-  }
-  const contextPack = await buildContextPack(process.cwd(), {
-    workflow: options.workflow,
-    base: options.base
-  });
-  const diagnostics = contextPack.warnings;
-  const summary = `Truthmark context generated ${contextPack.workflow} ContextPack with ${diagnostics.length} warnings.`;
-  const markdown = renderContextPackMarkdown(contextPack);
-  return {
-    command: "context",
-    summary,
-    diagnostics,
-    data: {
-      markdown,
-      summary
-    }
-  };
-};
 var runWorkflowStatus = async (options) => {
   if (!isTruthmarkWorkflowId(options.workflow)) {
     return invalidWorkflowResult("workflow status", options.workflow);
@@ -8123,14 +8343,6 @@ var writeResult = (result, options) => {
 `);
   markFailedWhenErrorDiagnosticsExist(result);
 };
-var writeContextResult = (result, options) => {
-  if (!options.json && typeof result.data?.markdown === "string") {
-    process.stdout.write(result.data.markdown);
-    markFailedWhenErrorDiagnosticsExist(result);
-    return;
-  }
-  writeResult(result, options);
-};
 var renderValidationHuman = (result) => {
   if (result.ok === true) {
     return [`${result.helper}: ok`, ...result.checks.map((check) => `- ${check}`)].join("\n");
@@ -8175,7 +8387,7 @@ var buildProgram = () => {
     writeResult(await runCheck2({ base: options.base }), options);
   });
   addJsonOption(
-    program.command("index").description("Build the deterministic Truthmark repository index.")
+    program.command("index").description("Inspect derived Truthmark workflow routing metadata for the current checkout.")
   ).action(async (options) => {
     writeResult(await runIndex(), options);
   });
@@ -8184,18 +8396,6 @@ var buildProgram = () => {
   ).action(async (options) => {
     writeResult(await runImpact({ base: options.base }), options);
   });
-  addJsonOption(
-    program.command("context").description("Generate a bounded workflow context pack.").requiredOption("--workflow <workflow>", "Workflow name: truth-sync, truth-document, or truth-realize").option("--base <ref>", "Base Git ref for impact-backed packs").option("--format <format>", "Output format: markdown", "markdown")
-  ).action(async (options) => {
-    writeContextResult(
-      await runContext({
-        workflow: options.workflow,
-        base: options.base,
-        format: options.format
-      }),
-      options
-    );
-  });
   const workflow = program.command("workflow").description("Inspect agent-facing Truthmark workflow state.");
   addJsonOption(
     workflow.command("status").description("Return schema-versioned workflow state for a canonical workflow ID.").option("--workflow <workflow>", "Canonical workflow ID, such as truthmark-sync").option("--base <ref>", "Base Git ref for impact-backed workflow state")