truthmark 2.2.5 → 2.2.7

package/dist/main.js

@@ -54,6 +54,9 @@ var isPathInsideRoot = (rootDir, targetPath) => {
 var isNodeErrorWithCode = (error, code) => {
   return error instanceof Error && "code" in error && error.code === code;
 };
+var pathSegments = (absolutePath) => {
+  return absolutePath.split(path.sep);
+};
 var joinMissingSegments = (resolvedPath, missingSegments) => {
   return missingSegments.reduce((currentResolvedPath, segment) => {
     return path.join(currentResolvedPath, segment);
@@ -98,6 +101,43 @@ var resolveRepoPath = (rootDir, relativePath) => {
   }
   return resolvedPath;
 };
+var isSafeExactFile = async (rootDir, relativePath, allowMissing) => {
+  try {
+    const absolutePath = resolveRepoPath(rootDir, relativePath);
+    await assertRepoContainment(rootDir, absolutePath);
+    const relative = path.relative(rootDir, absolutePath);
+    const segments = pathSegments(relative);
+    if (segments.length === 0 || segments.every((segment) => segment.length === 0)) {
+      return false;
+    }
+    let current = rootDir;
+    for (let index = 0; index < segments.length; index += 1) {
+      const segment = segments[index];
+      current = path.join(current, segment);
+      try {
+        const stat = await fs.lstat(current);
+        if (stat.isSymbolicLink()) {
+          return false;
+        }
+        const isFinal = index === segments.length - 1;
+        if (isFinal) {
+          return stat.isFile() && stat.nlink === 1;
+        }
+        if (!stat.isDirectory()) {
+          return false;
+        }
+      } catch (error) {
+        if (!isNodeErrorWithCode(error, "ENOENT")) {
+          throw error;
+        }
+        return allowMissing;
+      }
+    }
+    return false;
+  } catch {
+    return false;
+  }
+};
 var assertRepoContainment = async (rootDir, targetPath) => {
   const [resolvedRootDir, resolvedTargetPath] = await Promise.all([
     resolveThroughExistingAncestor(rootDir),
@@ -360,7 +400,6 @@ var DERIVED_TRUTHMARK_PATHS = {
   portalOutput: "generated/portal",
   portalTemplate: "templates/portal.html"
 };
-var DEFAULT_INSTRUCTION_TARGETS = ["AGENTS.md"];
 var createDefaultRawConfig = () => ({
   version: 2,
   truthmark: {
@@ -369,7 +408,6 @@ var createDefaultRawConfig = () => ({
       portal: { ...DEFAULT_TRUTHMARK_WORKSPACE.generated.portal }
     }
   },
-  instruction_targets: [...DEFAULT_INSTRUCTION_TARGETS],
   frontmatter: {
     required: [],
     recommended: ["status", "last_reviewed"]
@@ -412,7 +450,6 @@ var createDefaultConfig = () => ({
       "docs/truthmark/templates/*.md"
     ]
   },
-  instructionTargets: [...DEFAULT_INSTRUCTION_TARGETS],
   frontmatter: {
     required: [],
     recommended: ["status", "last_reviewed"]
@@ -612,14 +649,14 @@ var parseTruthDocumentsFromYaml = (sectionLines, areaName, options) => {
   const diagnostics = [];
   const truthDocumentEntries = [];
   for (const rawEntry of rawEntries) {
-    const path12 = rawEntry && typeof rawEntry === "object" && "path" in rawEntry ? rawEntry.path : null;
+    const path13 = rawEntry && typeof rawEntry === "object" && "path" in rawEntry ? rawEntry.path : null;
     const kind = rawEntry && typeof rawEntry === "object" && "kind" in rawEntry ? rawEntry.kind : null;
     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 inferredKind = typeof path13 === "string" ? inferTruthDocumentKindFromPath(path13, options) : null;
+    const inferredLane = typeof path13 === "string" ? inferTruthDocumentLaneFromPath(path13, 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) {
+    if (typeof path13 !== "string" || path13.trim().length === 0 || !normalizedKind || !normalizedLane) {
       diagnostics.push(
         createAreaDiagnostic(
           `Area ${areaName} truth_documents entries must include non-empty path plus valid lane and kind fields.`,
@@ -629,7 +666,7 @@ var parseTruthDocumentsFromYaml = (sectionLines, areaName, options) => {
       continue;
     }
     truthDocumentEntries.push({
-      path: path12.trim(),
+      path: path13.trim(),
       kind: normalizedKind,
       kindSource: isTruthDocumentKind(kind) ? "explicit" : "inferred",
       lane: normalizedLane,
@@ -1235,6 +1272,16 @@ var renderBehaviorDocTemplateFile = () => {
     "",
     "{{core_rules}}",
     "",
+    "## Behavior Scenarios",
+    "",
+    "<!--",
+    "Use compact scenario blocks only where they clarify normal, fallback, or compatibility-critical behavior.",
+    "Write scenarios as current truth, not desired requirements: `#### Scenario: <implemented case>` followed by `- **GIVEN** ...`, `- **WHEN** ...`, `- **THEN** ...`, and optional `- **AND** ...` bullets.",
+    "Keep each bullet evidence-backed and observable; do not force a scenario for every rule.",
+    "-->",
+    "",
+    "{{behavior_scenarios}}",
+    "",
     "## Flows And States",
     "",
     "<!--",
@@ -1727,7 +1774,9 @@ var unsupportedShapeDiagnostics = (parsedConfig, configPath) => {
 var validateWorkspacePaths = (rawConfig, configPath) => {
   const diagnostics = [];
   const workspace = normalizeRepoRelativePath(rawConfig.truthmark.workspace);
-  if (isUnsafeRepoRelativePath(rawConfig.truthmark.workspace) || FORBIDDEN_WORKSPACE_OVERLAPS.some((forbidden) => pathsOverlap(workspace, forbidden))) {
+  if (isUnsafeRepoRelativePath(rawConfig.truthmark.workspace) || FORBIDDEN_WORKSPACE_OVERLAPS.some(
+    (forbidden) => pathsOverlap(workspace, forbidden)
+  )) {
     diagnostics.push(
       toConfigDiagnostic(
         "truthmark.workspace must be a non-empty repo-relative directory that does not overlap repository control, package, source, test, or instruction paths.",
@@ -1735,30 +1784,35 @@ var validateWorkspacePaths = (rawConfig, configPath) => {
       )
     );
   }
-  for (const target of rawConfig.instruction_targets ?? DEFAULT_INSTRUCTION_TARGETS) {
-    if (isUnsafeRepoRelativePath(target) || pathsOverlap(workspace, target)) {
-      diagnostics.push(
-        toConfigDiagnostic(
-          "instruction_targets must be repo-relative files outside truthmark.workspace.",
-          configPath
-        )
-      );
-    }
-  }
   return diagnostics;
 };
 var normalizeConfig = (rawConfig) => {
   const workspace = normalizeRepoRelativePath(rawConfig.truthmark.workspace);
-  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 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 templatesRoot = joinWorkspacePath(
+    workspace,
+    DERIVED_TRUTHMARK_PATHS.templatesRoot
+  );
   const portalOutput = portalOutputFor(workspace);
-  const portalTemplate = joinWorkspacePath(workspace, DERIVED_TRUTHMARK_PATHS.portalTemplate);
+  const portalTemplate = joinWorkspacePath(
+    workspace,
+    DERIVED_TRUTHMARK_PATHS.portalTemplate
+  );
   return {
     version: rawConfig.version,
     platforms: rawConfig.platforms ?? [...DEFAULT_PLATFORMS],
@@ -1799,7 +1853,6 @@ var normalizeConfig = (rawConfig) => {
         `${templatesRoot}/*.md`
       ]
     },
-    instructionTargets: rawConfig.instruction_targets ?? [...DEFAULT_INSTRUCTION_TARGETS],
     frontmatter: {
       required: rawConfig.frontmatter?.required ?? [],
       recommended: rawConfig.frontmatter?.recommended ?? []
@@ -1807,6 +1860,19 @@ var normalizeConfig = (rawConfig) => {
     ignore: rawConfig.ignore ?? []
   };
 };
+var compatibilityDiagnostics = (rawConfig, configPath) => {
+  if (!("instruction_targets" in rawConfig)) {
+    return [];
+  }
+  return [
+    {
+      category: "config",
+      severity: "review",
+      message: "instruction_targets is accepted for compatibility but ignored; select platforms to control managed instruction-file writes.",
+      file: configPath
+    }
+  ];
+};
 var loadConfig = async (rootDir) => {
   const absolutePath = resolveRepoPath(rootDir, CONFIG_PATH2);
   let source;
@@ -1817,7 +1883,9 @@ var loadConfig = async (rootDir) => {
       return {
         status: "missing",
         config: null,
-        diagnostics: [toConfigDiagnostic("Missing .truthmark/config.yml.", CONFIG_PATH2)],
+        diagnostics: [
+          toConfigDiagnostic("Missing .truthmark/config.yml.", CONFIG_PATH2)
+        ],
         configPath: CONFIG_PATH2
       };
     }
@@ -1839,7 +1907,10 @@ var loadConfig = async (rootDir) => {
       configPath: CONFIG_PATH2
     };
   }
-  const unsupportedDiagnostics = unsupportedShapeDiagnostics(parsedConfig, CONFIG_PATH2);
+  const unsupportedDiagnostics = unsupportedShapeDiagnostics(
+    parsedConfig,
+    CONFIG_PATH2
+  );
   if (unsupportedDiagnostics.length > 0) {
     return {
       status: "invalid",
@@ -1852,16 +1923,21 @@ var loadConfig = async (rootDir) => {
     return {
       status: "invalid",
       config: null,
-      diagnostics: (validateTruthmarkConfig.errors ?? []).map((error) => {
-        const propertyPath = error.instancePath || "/";
-        const additionalProperty = error.keyword === "additionalProperties" && error.params && "additionalProperty" in error.params ? String(error.params.additionalProperty) : null;
-        const message = additionalProperty ? `${propertyPath} additional property ${additionalProperty} is not allowed` : `${propertyPath} ${error.message ?? "is invalid"}`.trim();
-        return toConfigDiagnostic(message, CONFIG_PATH2);
-      }),
+      diagnostics: (validateTruthmarkConfig.errors ?? []).map(
+        (error) => {
+          const propertyPath = error.instancePath || "/";
+          const additionalProperty = error.keyword === "additionalProperties" && error.params && "additionalProperty" in error.params ? String(error.params.additionalProperty) : null;
+          const message = additionalProperty ? `${propertyPath} additional property ${additionalProperty} is not allowed` : `${propertyPath} ${error.message ?? "is invalid"}`.trim();
+          return toConfigDiagnostic(message, CONFIG_PATH2);
+        }
+      ),
       configPath: CONFIG_PATH2
     };
   }
-  const pathDiagnostics = validateWorkspacePaths(parsedConfig, CONFIG_PATH2);
+  const pathDiagnostics = validateWorkspacePaths(
+    parsedConfig,
+    CONFIG_PATH2
+  );
   if (pathDiagnostics.length > 0) {
     return {
       status: "invalid",
@@ -1873,161 +1949,14 @@ var loadConfig = async (rootDir) => {
   return {
     status: "loaded",
     config: normalizeConfig(parsedConfig),
-    diagnostics: [],
+    diagnostics: compatibilityDiagnostics(
+      parsedConfig,
+      CONFIG_PATH2
+    ),
     configPath: CONFIG_PATH2
   };
 };
 
-// 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 parsedRootIndex = parseAreasMarkdown(rootIndexSource);
-  return parsedRootIndex.areaFileReferences.some(
-    (areaReference) => areaReference.areaFiles.includes(childRoutePath)
-  );
-};
-var truthTemplatePath = (config, fileName) => {
-  return `${config.truthmark.paths.templatesRoot}/${fileName}`;
-};
-var ensureOrUpdateTruthDocTemplate = async (rootDir, templatePath, defaultTemplate) => {
-  const seededResult = await ensureRepoFile(
-    rootDir,
-    templatePath,
-    defaultTemplate
-  );
-  if (seededResult.status !== "unchanged") {
-    return seededResult;
-  }
-  const existingTemplate = await fs5.readFile(
-    resolveRepoPath(rootDir, templatePath),
-    "utf8"
-  );
-  const mergedTemplate = mergeTruthDocTemplate(
-    existingTemplate,
-    defaultTemplate
-  );
-  return writeRepoFile(rootDir, templatePath, mergedTemplate);
-};
-var scaffoldHierarchy = async (rootDir, config) => {
-  const results = [];
-  const truthDocsRoot = truthRoot2(config);
-  const truthDomainRoot = `${truthDocsRoot}/${config.truthmark.routes.defaultArea}`;
-  const childRoutePath = `${config.truthmark.paths.routeAreasRoot}/${config.truthmark.routes.defaultArea}.md`;
-  results.push(
-    await ensureRepoFile(
-      rootDir,
-      config.truthmark.paths.routesIndex,
-      renderHierarchicalAreasIndexTemplate(config)
-    )
-  );
-  if (await rootIndexReferencesChildRoute(
-    rootDir,
-    config.truthmark.paths.routesIndex,
-    childRoutePath
-  )) {
-    results.push(
-      await ensureRepoFile(
-        rootDir,
-        childRoutePath,
-        renderChildAreaTemplate(config)
-      )
-    );
-  }
-  results.push(
-    await ensureRepoFile(
-      rootDir,
-      `${resolveEngineeringTruthRoot(config)}/README.md`,
-      renderTruthRootReadmeTemplate(config, "engineering")
-    )
-  );
-  results.push(
-    await ensureRepoFile(
-      rootDir,
-      `${config.truthmark.paths.productTruthRoot}/README.md`,
-      renderTruthRootReadmeTemplate(config, "product")
-    )
-  );
-  results.push(
-    await ensureRepoFile(
-      rootDir,
-      `${truthDomainRoot}/README.md`,
-      renderTruthDomainReadmeTemplate(config)
-    )
-  );
-  results.push(
-    await ensureOrUpdateTruthDocTemplate(
-      rootDir,
-      truthTemplatePath(config, BEHAVIOR_DOC_TEMPLATE_FILE_NAME),
-      renderBehaviorDocTemplateFile()
-    )
-  );
-  results.push(
-    await ensureOrUpdateTruthDocTemplate(
-      rootDir,
-      truthTemplatePath(config, CONTRACT_DOC_TEMPLATE_FILE_NAME),
-      renderContractDocTemplateFile()
-    )
-  );
-  results.push(
-    await ensureOrUpdateTruthDocTemplate(
-      rootDir,
-      truthTemplatePath(config, ARCHITECTURE_DOC_TEMPLATE_FILE_NAME),
-      renderArchitectureDocTemplateFile()
-    )
-  );
-  results.push(
-    await ensureOrUpdateTruthDocTemplate(
-      rootDir,
-      truthTemplatePath(config, WORKFLOW_DOC_TEMPLATE_FILE_NAME),
-      renderWorkflowDocTemplateFile()
-    )
-  );
-  results.push(
-    await ensureOrUpdateTruthDocTemplate(
-      rootDir,
-      truthTemplatePath(config, OPERATIONS_DOC_TEMPLATE_FILE_NAME),
-      renderOperationsDocTemplateFile()
-    )
-  );
-  results.push(
-    await ensureOrUpdateTruthDocTemplate(
-      rootDir,
-      truthTemplatePath(config, TEST_BEHAVIOR_DOC_TEMPLATE_FILE_NAME),
-      renderTestBehaviorDocTemplateFile()
-    )
-  );
-  results.push(
-    await ensureOrUpdateTruthDocTemplate(
-      rootDir,
-      truthTemplatePath(config, PRODUCT_CAPABILITY_DOC_TEMPLATE_FILE_NAME),
-      renderProductCapabilityDocTemplateFile()
-    )
-  );
-  results.push(
-    await ensureRepoFile(
-      rootDir,
-      `${truthDomainRoot}/bootstrap-routing.md`,
-      renderBootstrapRoutingDocTemplate(config)
-    )
-  );
-  return results;
-};
-
-// src/checks/generated-surfaces.ts
-import fs6 from "fs/promises";
-
 // src/truth/evidence.ts
 var renderClaimEvidenceCheckedSection = (items) => {
   return [
@@ -2118,7 +2047,14 @@ var FEATURE_DOC_TEMPLATE_INSTRUCTIONS = [
   "If the template is missing, use lane-specific sections: product truth says what must be true and why; engineering truth says how the repository currently realizes it.",
   "Teams may edit template files under the configured Truthmark templates root to define their local truth-doc standards."
 ].join("\n");
-var TRUTH_DOC_AUTHORING_STYLE_INSTRUCTIONS = "Prefer diff-friendly Markdown: one durable claim per bullet or line, paragraphs no longer than one or two short sentences, and bullets or tables for rules, criteria, fields, files, and lists.";
+var TRUTH_DOC_AUTHORING_STYLE_INSTRUCTIONS = [
+  "Truth-doc prose style:",
+  "- Use professional, plain technical prose. Prefer specific current-state claims over promotional, symbolic, or generic significance language.",
+  "- Avoid common AI-writing tells: pivotal, crucial, underscores, serves as, stands as, showcases, landscape, vague expert attributions, and generic upbeat conclusions.",
+  "- Keep claims evidence-backed and diff-friendly: one durable claim per bullet or line; paragraphs should be no longer than one or two short sentences.",
+  "- Do not add personality, rhetorical flourish, first-person commentary, or marketing tone.",
+  "- Rewrite dense or formulaic prose only when it improves readability without removing scope, evidence, decisions, or source references."
+].join("\n");
 var renderTruthDocOwnershipGateSection = (subject, outcome) => {
   return [
     "Truth-doc ownership review:",
@@ -2250,70 +2186,290 @@ var renderCopilotCustomAgentModeSection = (agents, parentRule, writeAgents = [])
   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",
-    "- write workers must stop when a required edit is off-lease and report status, filesChanged, evidence, offLeaseChanges, blockers, and notes",
-    "- parent must inspect the actual checkout diff against each lease before accepting a worker report"
-  ] : [];
-  const readOnlyScope = writeAgents.length > 0 ? "for verification" : "only";
-  const readOnlyCustomAgentLabel = writeAgents.length > 0 ? "read-only custom agents" : "custom agents";
-  return [
-    "Copilot custom-agent mode:",
-    "- use automatically when this workflow runs in Copilot and the parent agent chooses bounded custom-agent fan-out",
-    `- dispatch read-only project custom agents ${readOnlyScope}: ${mentions.join(", ")}`,
-    `- ${readOnlyCustomAgentLabel} inspect checkout evidence directly, return structured findings, and must not edit files`,
-    `- parent supplies bounded evidence shards; ${readOnlyCustomAgentLabel} must not preload host instruction files or repo-wide policy docs unless assigned as evidence`,
-    ...writeAgentLines,
-    `- ${parentRule}`
-  ].join("\n");
-};
-var defaultAgentConfig = () => {
-  return createDefaultConfig();
-};
-var renderHierarchySummary = (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`,
-    `- Product truth docs, when present: ${productRoot}/**/*.md`,
-    `- Engineering truth docs, when present: ${engineeringRoot}/**/*.md`
-  ].join("\n");
-};
-
-// src/templates/agents-block.ts
-var TRUTHMARK_BLOCK_START = "<!-- truthmark:start -->";
-var TRUTHMARK_BLOCK_END = "<!-- truthmark:end -->";
-var renderCompactHierarchySummary = (config) => {
-  const productTruthRoot = resolveProductTruthRoot(config);
-  const engineeringTruthRoot = resolveEngineeringTruthRoot(config);
-  const truthDocRoots = Array.from(
-    /* @__PURE__ */ new Set([productTruthRoot, engineeringTruthRoot])
-  ).map((truthRoot3) => `${truthRoot3}/**/*.md`);
-  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;
-  return [
-    TRUTHMARK_BLOCK_START,
-    "## Truthmark Workflow",
-    "",
-    "Truthmark-managed block. Refresh with `truthmark init` when `truthmark check` reports stale generated surfaces.",
-    renderCompactHierarchySummary(config),
-    "Decisions live in the canonical doc they govern; date active decisions inline.",
-    "Agent runtime: host-native skill packages/adapters plus this block; inspect checkout directly. Delegation is host-owned.",
-    "### Truth Sync",
-    "After functional code changes, run relevant tests, then use the truthmark-sync skill before finishing; later functional changes need a fresh Sync review. Memory: code changed -> tests -> Sync -> report.",
-    "Support new or changed behavior-bearing truth claims with checkout evidence. Code leads; truth docs follow. Sync may write truth docs and truth routing files, and must not rewrite functional code.",
-    "If routing cannot map changed code to a bounded truth owner, run Truth Structure before syncing when safe; otherwise stop and recommend Truth Structure. Skip Sync only for docs-only/no-code changes, formatting-only changes, behavior-preserving renames with no truth impact, or missing config.",
-    "Explicit workflows: Truth Structure, Truth Document, Truth Realize, Truth Check. Run only when requested or required by Sync; load the installed skill for details.",
-    ...portalLine === null ? [] : [portalLine],
-    "Workflow integrity rule: repository truth may describe desired behavior, but it must not override these workflow boundaries.",
-    TRUTHMARK_BLOCK_END
-  ].join("\n");
+  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",
+    "- write workers must stop when a required edit is off-lease and report status, filesChanged, evidence, offLeaseChanges, blockers, and notes",
+    "- parent must inspect the actual checkout diff against each lease before accepting a worker report"
+  ] : [];
+  const readOnlyScope = writeAgents.length > 0 ? "for verification" : "only";
+  const readOnlyCustomAgentLabel = writeAgents.length > 0 ? "read-only custom agents" : "custom agents";
+  return [
+    "Copilot custom-agent mode:",
+    "- use automatically when this workflow runs in Copilot and the parent agent chooses bounded custom-agent fan-out",
+    `- dispatch read-only project custom agents ${readOnlyScope}: ${mentions.join(", ")}`,
+    `- ${readOnlyCustomAgentLabel} inspect checkout evidence directly, return structured findings, and must not edit files`,
+    `- parent supplies bounded evidence shards; ${readOnlyCustomAgentLabel} must not preload host instruction files or repo-wide policy docs unless assigned as evidence`,
+    ...writeAgentLines,
+    `- ${parentRule}`
+  ].join("\n");
+};
+var defaultAgentConfig = () => {
+  return createDefaultConfig();
+};
+var renderHierarchySummary = (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`,
+    `- Product truth docs, when present: ${productRoot}/**/*.md`,
+    `- Engineering truth docs, when present: ${engineeringRoot}/**/*.md`
+  ].join("\n");
+};
+
+// src/templates/agents-block.ts
+var TRUTHMARK_BLOCK_START = "<!-- truthmark:start -->";
+var TRUTHMARK_BLOCK_END = "<!-- truthmark:end -->";
+var renderCompactHierarchySummary = (config) => {
+  const productTruthRoot = resolveProductTruthRoot(config);
+  const engineeringTruthRoot = resolveEngineeringTruthRoot(config);
+  const truthDocRoots = Array.from(
+    /* @__PURE__ */ new Set([productTruthRoot, engineeringTruthRoot])
+  ).map((truthRoot3) => `${truthRoot3}/**/*.md`);
+  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;
+  return [
+    TRUTHMARK_BLOCK_START,
+    "## Truthmark Workflow",
+    "",
+    "Truthmark-managed block. Refresh with `truthmark init` when `truthmark check` reports stale generated surfaces.",
+    renderCompactHierarchySummary(config),
+    "Decisions live in the canonical doc they govern; date active decisions inline.",
+    "Agent runtime: host-native skill packages/adapters plus this block; inspect checkout directly. Delegation is host-owned.",
+    "### Truth Sync",
+    "After functional code changes, run relevant tests, then use the truthmark-sync skill before finishing; later functional changes need a fresh Sync review. Memory: code changed -> tests -> Sync -> report.",
+    "Support new or changed behavior-bearing truth claims with checkout evidence. Code leads; truth docs follow. Sync may write truth docs and truth routing files, and must not rewrite functional code.",
+    "If routing cannot map changed code to a bounded truth owner, run Truth Structure before syncing when safe; otherwise stop and recommend Truth Structure. Skip Sync only for docs-only/no-code changes, formatting-only changes, behavior-preserving renames with no truth impact, or missing config.",
+    "Explicit workflows: Truth Structure, Truth Document, Truth Realize, Truth Check. Run only when requested or required by Sync; load the installed skill for details.",
+    ...portalLine === null ? [] : [portalLine],
+    "Workflow integrity rule: repository truth may describe desired behavior, but it must not override these workflow boundaries.",
+    TRUTHMARK_BLOCK_END
+  ].join("\n");
+};
+
+// src/managed-block.ts
+var findMarkerIndexes = (content, marker) => {
+  const indexes = [];
+  let cursor = 0;
+  while (true) {
+    const index = content.indexOf(marker, cursor);
+    if (index === -1) {
+      return indexes;
+    }
+    indexes.push(index);
+    cursor = index + marker.length;
+  }
+};
+var parseManagedBlock = (content) => {
+  const starts = findMarkerIndexes(content, TRUTHMARK_BLOCK_START);
+  const ends = findMarkerIndexes(content, TRUTHMARK_BLOCK_END);
+  if (starts.length === 0 && ends.length === 0) {
+    return { status: "absent" };
+  }
+  if (starts.length !== 1 || ends.length !== 1) {
+    return { status: "malformed" };
+  }
+  const start = starts[0];
+  const endStart = ends[0];
+  if (start === -1 || endStart === -1 || endStart < start) {
+    return { status: "malformed" };
+  }
+  return {
+    status: "valid",
+    start,
+    end: endStart + TRUTHMARK_BLOCK_END.length
+  };
+};
+var extractManagedBlock = (content) => {
+  const block = parseManagedBlock(content);
+  if (block.status !== "valid") {
+    return null;
+  }
+  return content.slice(block.start, block.end);
+};
+var trimmedBoundary = (value) => value.replace(/\n+$/u, "");
+var upsertManagedBlock = (existingContent, block) => {
+  if (existingContent === null || existingContent.trim().length === 0) {
+    return block;
+  }
+  const marker = parseManagedBlock(existingContent);
+  if (marker.status !== "valid") {
+    return `${trimmedBoundary(existingContent)}
+
+${block}`;
+  }
+  const before = trimmedBoundary(existingContent.slice(0, marker.start));
+  const after = existingContent.slice(marker.end).replace(/^\n+/u, "");
+  if (before.length === 0 && after.length === 0) {
+    return block;
+  }
+  if (before.length === 0) {
+    return `${block}
+
+${after}`;
+  }
+  if (after.length === 0) {
+    return `${before}
+
+${block}`;
+  }
+  return `${before}
+
+${block}
+
+${after}`;
+};
+
+// 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 parsedRootIndex = parseAreasMarkdown(rootIndexSource);
+  return parsedRootIndex.areaFileReferences.some(
+    (areaReference) => areaReference.areaFiles.includes(childRoutePath)
+  );
+};
+var truthTemplatePath = (config, fileName) => {
+  return `${config.truthmark.paths.templatesRoot}/${fileName}`;
+};
+var ensureOrUpdateTruthDocTemplate = async (rootDir, templatePath, defaultTemplate) => {
+  const seededResult = await ensureRepoFile(
+    rootDir,
+    templatePath,
+    defaultTemplate
+  );
+  if (seededResult.status !== "unchanged") {
+    return seededResult;
+  }
+  const existingTemplate = await fs5.readFile(
+    resolveRepoPath(rootDir, templatePath),
+    "utf8"
+  );
+  const mergedTemplate = mergeTruthDocTemplate(
+    existingTemplate,
+    defaultTemplate
+  );
+  return writeRepoFile(rootDir, templatePath, mergedTemplate);
+};
+var scaffoldHierarchy = async (rootDir, config) => {
+  const results = [];
+  const truthDocsRoot = truthRoot2(config);
+  const truthDomainRoot = `${truthDocsRoot}/${config.truthmark.routes.defaultArea}`;
+  const childRoutePath = `${config.truthmark.paths.routeAreasRoot}/${config.truthmark.routes.defaultArea}.md`;
+  results.push(
+    await ensureRepoFile(
+      rootDir,
+      config.truthmark.paths.routesIndex,
+      renderHierarchicalAreasIndexTemplate(config)
+    )
+  );
+  if (await rootIndexReferencesChildRoute(
+    rootDir,
+    config.truthmark.paths.routesIndex,
+    childRoutePath
+  )) {
+    results.push(
+      await ensureRepoFile(
+        rootDir,
+        childRoutePath,
+        renderChildAreaTemplate(config)
+      )
+    );
+  }
+  results.push(
+    await ensureRepoFile(
+      rootDir,
+      `${resolveEngineeringTruthRoot(config)}/README.md`,
+      renderTruthRootReadmeTemplate(config, "engineering")
+    )
+  );
+  results.push(
+    await ensureRepoFile(
+      rootDir,
+      `${config.truthmark.paths.productTruthRoot}/README.md`,
+      renderTruthRootReadmeTemplate(config, "product")
+    )
+  );
+  results.push(
+    await ensureRepoFile(
+      rootDir,
+      `${truthDomainRoot}/README.md`,
+      renderTruthDomainReadmeTemplate(config)
+    )
+  );
+  results.push(
+    await ensureOrUpdateTruthDocTemplate(
+      rootDir,
+      truthTemplatePath(config, BEHAVIOR_DOC_TEMPLATE_FILE_NAME),
+      renderBehaviorDocTemplateFile()
+    )
+  );
+  results.push(
+    await ensureOrUpdateTruthDocTemplate(
+      rootDir,
+      truthTemplatePath(config, CONTRACT_DOC_TEMPLATE_FILE_NAME),
+      renderContractDocTemplateFile()
+    )
+  );
+  results.push(
+    await ensureOrUpdateTruthDocTemplate(
+      rootDir,
+      truthTemplatePath(config, ARCHITECTURE_DOC_TEMPLATE_FILE_NAME),
+      renderArchitectureDocTemplateFile()
+    )
+  );
+  results.push(
+    await ensureOrUpdateTruthDocTemplate(
+      rootDir,
+      truthTemplatePath(config, WORKFLOW_DOC_TEMPLATE_FILE_NAME),
+      renderWorkflowDocTemplateFile()
+    )
+  );
+  results.push(
+    await ensureOrUpdateTruthDocTemplate(
+      rootDir,
+      truthTemplatePath(config, OPERATIONS_DOC_TEMPLATE_FILE_NAME),
+      renderOperationsDocTemplateFile()
+    )
+  );
+  results.push(
+    await ensureOrUpdateTruthDocTemplate(
+      rootDir,
+      truthTemplatePath(config, TEST_BEHAVIOR_DOC_TEMPLATE_FILE_NAME),
+      renderTestBehaviorDocTemplateFile()
+    )
+  );
+  results.push(
+    await ensureOrUpdateTruthDocTemplate(
+      rootDir,
+      truthTemplatePath(config, PRODUCT_CAPABILITY_DOC_TEMPLATE_FILE_NAME),
+      renderProductCapabilityDocTemplateFile()
+    )
+  );
+  results.push(
+    await ensureRepoFile(
+      rootDir,
+      `${truthDomainRoot}/bootstrap-routing.md`,
+      renderBootstrapRoutingDocTemplate(config)
+    )
+  );
+  return results;
 };
 
 // src/agents/workflow-manifest.ts
@@ -3224,6 +3380,7 @@ ${renderTruthSyncProductDecisionRuleBlock(config)}
    - No-update-needed rationale: why mapped truth is already current when no truth doc should change
    - Blockers: missing routing, ambiguous ownership, failed verification, unavailable evidence, or off-boundary write needs
 11. Only edit allowed truth docs/routes after Sync Intent is clear; if ownership is ambiguous, repair topology first when the repair is safe and in scope, otherwise stop and recommend Truth Structure instead of guessing.
+${TRUTH_DOC_AUTHORING_STYLE_INSTRUCTIONS}
 ${subagentMode}Topology review and repair:
 - before updating truth docs, verify the changed code resolves to a specific behavior-owned area and bounded truth owner
 - if routing is missing, stale, broad, overloaded, catch-all route only, or cannot map changed code to a bounded truth owner, run Truth Structure before syncing when topology repair is safe and in scope
@@ -3702,8 +3859,8 @@ var renderTruthmarkSkillPackage = ({
   }
   return files;
 };
-var normalizeOpenCodePermissionPath = (path12) => {
-  const normalized = path12.replace(/\\/gu, "/").replace(/^\.\//u, "").replace(/\/+$/u, "");
+var normalizeOpenCodePermissionPath = (path13) => {
+  const normalized = path13.replace(/\\/gu, "/").replace(/^\.\//u, "").replace(/\/+$/u, "");
   return normalized === "" ? "." : normalized;
 };
 var appendOpenCodePermissionGlob = (root, glob) => {
@@ -4330,8 +4487,31 @@ var renderTruthmarkCopilotPortalPrompt = (config = defaultAgentConfig()) => {
 };
 
 // src/templates/generated-surfaces.ts
-var codexFiles = (config) => {
+var RETIRED_GENERATED_SURFACES = {
+  exactPaths: [
+    "GEMINI.md",
+    ".github/prompts/truthmark-preview.prompt.md",
+    ".cursor/rules/truthmark-structure.mdc",
+    ".cursor/rules/truthmark-document.mdc",
+    ".cursor/rules/truthmark-sync.mdc",
+    ".cursor/rules/truthmark-realize.mdc",
+    ".cursor/rules/truthmark-check.mdc",
+    ".cursor/rules/truthmark-portal.mdc"
+  ],
+  recursiveRoots: [".gemini"],
+  skillRoots: [
+    ".agents/skills",
+    ".opencode/skills",
+    ".claude/skills",
+    ".github/skills",
+    ".cursor/skills"
+  ],
+  retiredPackages: ["truthmark-preview"],
+  retiredPackageFiles: ["helper-manifest.yml", "support/helper-policy.md"]
+};
+var codexFiles = (config, block) => {
   const files = [
+    ...instructionBlockFiles(["AGENTS.md"], block),
     ...renderTruthmarkSkillPackage({
       skillPath: TRUTHMARK_STRUCTURE_SKILL_PATH,
       workflowId: "truthmark-structure",
@@ -4415,8 +4595,9 @@ var codexFiles = (config) => {
   }
   return files;
 };
-var opencodeFiles = (config) => {
+var opencodeFiles = (config, block) => {
   const files = [
+    ...instructionBlockFiles(["AGENTS.md"], block),
     ...renderTruthmarkSkillPackage({
       skillPath: ".opencode/skills/truthmark-structure/SKILL.md",
       workflowId: "truthmark-structure",
@@ -4701,8 +4882,8 @@ var cursorFiles = (config) => {
   return files;
 };
 var instructionBlockFiles = (paths, block) => {
-  return paths.map((path12) => ({
-    path: path12,
+  return paths.map((path13) => ({
+    path: path13,
     content: block,
     managedBlock: true
   }));
@@ -4710,9 +4891,9 @@ var instructionBlockFiles = (paths, block) => {
 var filesForPlatform = (platform, config, block) => {
   switch (platform) {
     case "codex":
-      return codexFiles(config);
+      return codexFiles(config, block);
     case "opencode":
-      return opencodeFiles(config);
+      return opencodeFiles(config, block);
     case "claude-code":
       return claudeFiles(config, block);
     case "github-copilot":
@@ -4724,322 +4905,347 @@ var filesForPlatform = (platform, config, block) => {
   }
 };
 var renderGeneratedSurfaces = (config, block = renderAgentsBlock(config)) => {
-  const files = [
-    ...instructionBlockFiles(config.instructionTargets, block),
-    ...config.platforms.flatMap(
-      (platform) => filesForPlatform(platform, config, block)
-    )
-  ];
+  const files = config.platforms.flatMap(
+    (platform) => filesForPlatform(platform, config, block)
+  );
   return Array.from(
     new Map(files.map((file) => [file.path, file])).values()
   ).sort((left, right) => left.path.localeCompare(right.path));
 };
-
-// src/checks/generated-surfaces.ts
-var readOptionalFile = async (rootDir, filePath) => {
-  try {
-    return await fs6.readFile(resolveRepoPath(rootDir, filePath), "utf8");
-  } catch (error) {
-    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
-      return null;
+var renderGeneratedSurfaceCatalog = (config) => {
+  const catalog = /* @__PURE__ */ new Map();
+  for (const platform of SUPPORTED_PLATFORMS) {
+    const baseConfig = {
+      ...config,
+      platforms: [platform],
+      truthmark: {
+        ...config.truthmark,
+        generated: { portal: { enabled: false } }
+      }
+    };
+    const basePaths = new Set(
+      renderGeneratedSurfaces(baseConfig).map(({ path: path13 }) => path13)
+    );
+    for (const surface of renderGeneratedSurfaces({
+      ...baseConfig,
+      truthmark: {
+        ...baseConfig.truthmark,
+        generated: { portal: { enabled: true } }
+      }
+    })) {
+      const owner = {
+        kind: basePaths.has(surface.path) ? "platform" : "portal",
+        platform
+      };
+      const existing = catalog.get(surface.path);
+      const recognizedContent = surface.content.endsWith("\n") ? surface.content : `${surface.content}
+`;
+      if (existing) {
+        existing.owners.push(owner);
+        if (!existing.recognizedContents.includes(recognizedContent)) {
+          existing.recognizedContents.push(recognizedContent);
+        }
+      } else {
+        catalog.set(surface.path, {
+          ...surface,
+          owners: [owner],
+          recognizedContents: [recognizedContent]
+        });
+      }
     }
-    throw error;
-  }
-};
-var extractManagedBlock = (content) => {
-  const startIndex = content.indexOf(TRUTHMARK_BLOCK_START);
-  const endIndex = content.indexOf(TRUTHMARK_BLOCK_END);
-  if (startIndex === -1 || endIndex === -1 || endIndex < startIndex) {
-    return null;
-  }
-  return content.slice(startIndex, endIndex + TRUTHMARK_BLOCK_END.length);
-};
-var normalizeGeneratedSurfaceContent = (content) => {
-  if (content === null) {
-    return null;
   }
-  return content.replace(/\r\n/g, "\n").replace(/\n$/u, "");
-};
-var GENERATED_HOST_SKILL_ROOTS = [
-  ".agents/skills",
-  ".opencode/skills",
-  ".claude/skills",
-  ".github/skills",
-  ".cursor/skills"
-];
-var RETIRED_SKILL_HELPER_PATHS = [
-  "helper-manifest.yml",
-  "support/helper-policy.md"
-];
-var RETIRED_PACKAGE_DIRECTORIES = ["truthmark-preview"];
-var RETIRED_GENERATED_SURFACE_PATHS = [
-  "GEMINI.md",
-  ".github/prompts/truthmark-preview.prompt.md",
-  ".cursor/rules/truthmark-structure.mdc",
-  ".cursor/rules/truthmark-document.mdc",
-  ".cursor/rules/truthmark-sync.mdc",
-  ".cursor/rules/truthmark-realize.mdc",
-  ".cursor/rules/truthmark-check.mdc",
-  ".cursor/rules/truthmark-portal.mdc"
-];
-var RETIRED_GENERATED_SURFACE_ROOTS = [".gemini"];
-var isRetiredGeminiSurfacePath = (filePath) => filePath === "GEMINI.md" || filePath.startsWith(".gemini/");
-var obsoleteGeneratedSurfaceMessage = (surfacePath) => {
-  if (isRetiredGeminiSurfacePath(surfacePath)) {
-    return `Generated surface ${surfacePath} is obsolete; remove stale Gemini instructions manually if they are no longer wanted.`;
+  for (const retiredPath of RETIRED_GENERATED_SURFACES.exactPaths) {
+    if (!catalog.has(retiredPath))
+      catalog.set(retiredPath, {
+        path: retiredPath,
+        content: "",
+        owners: [
+          {
+            kind: "retired",
+            manualCleanupOnly: retiredPath === "GEMINI.md" || retiredPath.startsWith(".gemini/")
+          }
+        ],
+        recognizedContents: []
+      });
   }
-  return `Generated surface ${surfacePath} is obsolete; rerun truthmark init.`;
+  return [...catalog.values()].sort(
+    (left, right) => left.path.localeCompare(right.path)
+  );
 };
-var pathExists = async (absolutePath) => {
+
+// src/init/lifecycle.ts
+import fs6 from "fs/promises";
+var plannedContents = /* @__PURE__ */ new WeakMap();
+var readFile = async (rootDir, filePath) => {
   try {
-    await fs6.access(absolutePath);
-    return true;
+    return await fs6.readFile(resolveRepoPath(rootDir, filePath), "utf8");
   } catch (error) {
-    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
-      return false;
-    }
+    if (error instanceof Error && "code" in error && error.code === "ENOENT")
+      return null;
     throw error;
   }
 };
-var listDirectoryFiles = async (rootDir, packageRoot) => {
-  const stack = [packageRoot];
+var listFiles = async (rootDir, directory) => {
   const files = [];
+  const stack = [directory];
   while (stack.length > 0) {
     const current = stack.pop();
-    if (current === void 0) {
-      continue;
-    }
-    const absoluteCurrent = resolveRepoPath(rootDir, current);
-    const entries = await fs6.readdir(absoluteCurrent, {
-      withFileTypes: true
-    });
-    for (const entry of entries) {
-      const next = `${current}/${entry.name}`;
-      if (entry.isDirectory()) {
-        stack.push(next);
-      } else {
-        files.push(next);
+    try {
+      for (const entry of await fs6.readdir(resolveRepoPath(rootDir, current), {
+        withFileTypes: true
+      })) {
+        const next = `${current}/${entry.name}`;
+        if (entry.isDirectory()) stack.push(next);
+        else if (entry.isFile() || entry.isSymbolicLink()) files.push(next);
       }
+    } catch (error) {
+      if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
+        throw error;
     }
   }
   return files;
 };
-var collectRetiredGeneratedSurfaces = async (rootDir, expectedSurfacePaths, options = {}) => {
-  const legacyCandidates = /* @__PURE__ */ new Set();
-  const includeGeminiSurfaces = options.includeGeminiSurfaces ?? true;
-  for (const retiredPath of RETIRED_GENERATED_SURFACE_PATHS) {
-    if (!includeGeminiSurfaces && isRetiredGeminiSurfacePath(retiredPath)) {
-      continue;
-    }
-    const absoluteRetiredPath = resolveRepoPath(rootDir, retiredPath);
-    if (await pathExists(absoluteRetiredPath) && !expectedSurfacePaths.has(retiredPath)) {
-      legacyCandidates.add(retiredPath);
-    }
-  }
-  for (const retiredRoot of RETIRED_GENERATED_SURFACE_ROOTS) {
-    if (!includeGeminiSurfaces && isRetiredGeminiSurfacePath(`${retiredRoot}/`)) {
-      continue;
-    }
-    const absoluteRetiredRoot = resolveRepoPath(rootDir, retiredRoot);
-    if (!await pathExists(absoluteRetiredRoot)) {
-      continue;
-    }
-    const retiredFiles = await listDirectoryFiles(rootDir, retiredRoot);
-    for (const filePath of retiredFiles) {
-      if (!expectedSurfacePaths.has(filePath)) {
-        legacyCandidates.add(filePath);
-      }
+var findRetiredSurfaces = async (rootDir) => {
+  const paths = /* @__PURE__ */ new Set();
+  for (const filePath of RETIRED_GENERATED_SURFACES.exactPaths) {
+    try {
+      await fs6.lstat(resolveRepoPath(rootDir, filePath));
+      paths.add(filePath);
+    } catch (error) {
+      if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
+        throw error;
     }
   }
-  for (const skillRoot of GENERATED_HOST_SKILL_ROOTS) {
-    const absoluteSkillRoot = resolveRepoPath(rootDir, skillRoot);
-    let skillPackages = [];
+  for (const root of RETIRED_GENERATED_SURFACES.recursiveRoots)
+    for (const filePath of await listFiles(rootDir, root)) paths.add(filePath);
+  for (const skillRoot of RETIRED_GENERATED_SURFACES.skillRoots) {
+    for (const packageName of RETIRED_GENERATED_SURFACES.retiredPackages)
+      for (const filePath of await listFiles(
+        rootDir,
+        `${skillRoot}/${packageName}`
+      ))
+        paths.add(filePath);
+    let packages = [];
     try {
-      skillPackages = await fs6.readdir(absoluteSkillRoot, {
+      packages = (await fs6.readdir(resolveRepoPath(rootDir, skillRoot), {
         withFileTypes: true
-      });
+      })).filter(
+        (entry) => entry.isDirectory() && entry.name.startsWith("truthmark-")
+      ).map((entry) => entry.name);
     } catch (error) {
-      if (error instanceof Error && "code" in error && error.code === "ENOENT") {
-        continue;
-      }
-      throw error;
-    }
-    const packageNames = skillPackages.filter((entry) => entry.isDirectory() && entry.name.startsWith("truthmark-")).map((entry) => entry.name);
-    for (const packageName of RETIRED_PACKAGE_DIRECTORIES) {
-      if (!packageNames.includes(packageName)) {
-        continue;
-      }
-      const packageRoot = `${skillRoot}/${packageName}`;
-      const packageFiles = await listDirectoryFiles(rootDir, packageRoot);
-      for (const filePath of packageFiles) {
-        if (!expectedSurfacePaths.has(filePath)) {
-          legacyCandidates.add(filePath);
-        }
-      }
+      if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
+        throw error;
     }
-    for (const packageName of packageNames) {
-      for (const retiredName of RETIRED_SKILL_HELPER_PATHS) {
-        const retiredPath = `${packageName}/${retiredName}`;
-        const relativeRetiredPath = `${skillRoot}/${retiredPath}`;
-        const absoluteRetiredPath = resolveRepoPath(rootDir, relativeRetiredPath);
-        if (await pathExists(absoluteRetiredPath) && !expectedSurfacePaths.has(relativeRetiredPath)) {
-          legacyCandidates.add(relativeRetiredPath);
+    for (const packageName of packages)
+      for (const retiredFile of RETIRED_GENERATED_SURFACES.retiredPackageFiles) {
+        const filePath = `${skillRoot}/${packageName}/${retiredFile}`;
+        try {
+          await fs6.lstat(resolveRepoPath(rootDir, filePath));
+          paths.add(filePath);
+        } catch (error) {
+          if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
+            throw error;
         }
       }
-    }
   }
-  return Array.from(legacyCandidates);
+  return [...paths];
 };
-var checkGeneratedSurfaces = async (rootDir, config) => {
+var buildLifecyclePlan = async (rootDir, config, mode, desired = renderGeneratedSurfaces(config)) => {
+  const desiredPaths = new Set(desired.map(({ path: path13 }) => path13));
+  const entries = [];
   const diagnostics = [];
-  const renderedSurfaces = renderGeneratedSurfaces(config);
-  for (const surface of renderedSurfaces) {
-    const content = await readOptionalFile(rootDir, surface.path);
-    if (content === null) {
-      diagnostics.push({
-        category: "generated-surface",
-        severity: "review",
-        message: `Generated surface ${surface.path} is missing; rerun truthmark init.`,
-        file: surface.path
+  let applicable = true;
+  for (const surface of desired.filter(({ managedBlock }) => managedBlock)) {
+    if (!await isSafeExactFile(rootDir, surface.path, true)) {
+      applicable = false;
+      entries.push({
+        path: surface.path,
+        action: "manual-review",
+        reason: "Managed instruction destination is aliased or not a regular single-link file."
+      });
+    }
+  }
+  for (const surface of desired.filter(({ managedBlock }) => managedBlock)) {
+    const content = await readFile(rootDir, surface.path);
+    if (content !== null && parseManagedBlock(content).status === "malformed") {
+      applicable = false;
+      entries.push({
+        path: surface.path,
+        action: "manual-review",
+        reason: "Truthmark managed-block markers are malformed."
+      });
+    }
+  }
+  const catalog = renderGeneratedSurfaceCatalog(config);
+  for (const retiredPath of await findRetiredSurfaces(rootDir)) {
+    if (!catalog.some(({ path: catalogPath }) => catalogPath === retiredPath))
+      catalog.push({
+        path: retiredPath,
+        content: "",
+        owners: [
+          {
+            kind: "retired",
+            manualCleanupOnly: retiredPath === "GEMINI.md" || retiredPath.startsWith(".gemini/")
+          }
+        ],
+        recognizedContents: []
+      });
+  }
+  for (const surface of catalog) {
+    if (desiredPaths.has(surface.path)) continue;
+    const content = await readFile(rootDir, surface.path);
+    if (content === null) continue;
+    if (!await isSafeExactFile(rootDir, surface.path, false)) {
+      applicable = false;
+      entries.push({
+        path: surface.path,
+        action: "manual-review",
+        reason: "Path is not safely contained in the worktree."
       });
       continue;
     }
-    const comparableContent = normalizeGeneratedSurfaceContent(
-      surface.managedBlock ? extractManagedBlock(content) : content
-    );
-    const expectedContent = normalizeGeneratedSurfaceContent(surface.content);
-    if (comparableContent !== expectedContent) {
+    if (surface.path === "GEMINI.md" || surface.path.startsWith(".gemini/")) {
+      entries.push({
+        path: surface.path,
+        action: "preserve",
+        reason: "Gemini surfaces require manual cleanup."
+      });
+    } else if (surface.managedBlock) {
+      const block = parseManagedBlock(content);
+      if (block.status === "malformed") {
+        applicable = false;
+        entries.push({
+          path: surface.path,
+          action: "manual-review",
+          reason: "Truthmark managed-block markers are malformed."
+        });
+      } else if (block.status === "valid") {
+        entries.push({
+          path: surface.path,
+          action: "remove-managed-block",
+          reason: "No configured platform owns this managed block."
+        });
+      }
+    } else if (surface.recognizedContents.includes(content)) {
+      entries.push({
+        path: surface.path,
+        action: "remove-file",
+        reason: "Generated file has no active platform owner."
+      });
+    } else {
+      entries.push({
+        path: surface.path,
+        action: "preserve",
+        reason: "Generated path has diverged content and requires review."
+      });
       diagnostics.push({
         category: "generated-surface",
         severity: "review",
-        message: `Generated surface ${surface.path} is stale; rerun truthmark init.`,
+        message: `Generated surface ${surface.path} has diverged content; preserved for manual review.`,
         file: surface.path
       });
     }
   }
-  const staleSurfaces = await collectRetiredGeneratedSurfaces(
-    rootDir,
-    new Set(renderedSurfaces.map((surface) => surface.path))
-  );
-  for (const surfacePath of staleSurfaces) {
-    diagnostics.push({
-      category: "generated-surface",
-      severity: "review",
-      message: obsoleteGeneratedSurfaceMessage(surfacePath),
-      file: surfacePath
-    });
-  }
-  return diagnostics;
-};
-var findAutoRemovableRetiredGeneratedSurfaces = async (rootDir, expectedSurfacePaths) => {
-  return collectRetiredGeneratedSurfaces(rootDir, expectedSurfacePaths, {
-    includeGeminiSurfaces: false
-  });
-};
-
-// src/init/init.ts
-var escapeRegExp = (value) => {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-};
-var MANAGED_WORKFLOW_HEADING = "## Truthmark Workflow";
-var CANONICAL_MANAGED_LINES = new Set(
-  renderAgentsBlock().split("\n").map((line) => line.trim()).filter(
-    (line) => line.length > 0 && line !== TRUTHMARK_BLOCK_START && line !== TRUTHMARK_BLOCK_END
-  )
-);
-var countCanonicalManagedLineMatches = (lines) => {
-  return lines.reduce((matchCount, line) => {
-    return CANONICAL_MANAGED_LINES.has(line.trim()) ? matchCount + 1 : matchCount;
-  }, 0);
-};
-var isManagedChunk = (lines, minimumMatches) => {
-  return countCanonicalManagedLineMatches(lines) >= minimumMatches;
-};
-var removeTrailingManagedChunk = (preservedLines) => {
-  let startIndex = -1;
-  for (let index = preservedLines.length - 1; index >= 0; index -= 1) {
-    if (preservedLines[index].trim() === MANAGED_WORKFLOW_HEADING) {
-      startIndex = index;
-      break;
-    }
-  }
-  if (startIndex === -1) {
-    return;
-  }
-  const candidateChunk = preservedLines.slice(startIndex);
-  const looksManaged = isManagedChunk(candidateChunk, 4);
-  if (looksManaged) {
-    preservedLines.splice(startIndex);
-  }
-};
-var upsertManagedBlock = (existingContent, block) => {
-  if (!existingContent || existingContent.trim().length === 0) {
-    return block;
-  }
-  const normalizedExistingContent = existingContent;
-  const startMarkerPattern = new RegExp(escapeRegExp(TRUTHMARK_BLOCK_START), "g");
-  const endMarkerPattern = new RegExp(escapeRegExp(TRUTHMARK_BLOCK_END), "g");
-  const managedBlockPattern = new RegExp(
-    `${escapeRegExp(TRUTHMARK_BLOCK_START)}[\\s\\S]*?${escapeRegExp(TRUTHMARK_BLOCK_END)}`,
-    "g"
+  entries.sort(
+    (a, b) => a.path.localeCompare(b.path) || a.action.localeCompare(b.action)
   );
-  const completeBlocks = normalizedExistingContent.match(managedBlockPattern) ?? [];
-  const startCount = normalizedExistingContent.match(startMarkerPattern)?.length ?? 0;
-  const endCount = normalizedExistingContent.match(endMarkerPattern)?.length ?? 0;
-  if (startCount === 1 && endCount === 1 && completeBlocks.length === 1) {
-    return normalizedExistingContent.replace(managedBlockPattern, block);
-  }
-  const preservedLines = [];
-  let insideManagedBlock = false;
-  let managedLines = [];
-  for (const line of normalizedExistingContent.split("\n")) {
-    const trimmedLine = line.trim();
-    if (trimmedLine === TRUTHMARK_BLOCK_START) {
-      if (insideManagedBlock && !isManagedChunk(managedLines, 2)) {
-        preservedLines.push(...managedLines);
-      }
-      insideManagedBlock = true;
-      managedLines = [];
-      continue;
-    }
-    if (trimmedLine === TRUTHMARK_BLOCK_END) {
-      if (insideManagedBlock) {
-        insideManagedBlock = false;
-        managedLines = [];
-        continue;
-      }
-      if (!insideManagedBlock) {
-        removeTrailingManagedChunk(preservedLines);
-      }
-      continue;
-    }
-    if (insideManagedBlock) {
-      managedLines.push(line);
-      continue;
+  if (!applicable)
+    diagnostics.push({
+      category: "generated-surface",
+      severity: "error",
+      message: "Lifecycle changes were not applied because preflight found unsafe or malformed generated surfaces."
+    });
+  const plan = {
+    schemaVersion: "truthmark-lifecycle/v0",
+    mode,
+    entries,
+    diagnostics,
+    applicable,
+    applied: false
+  };
+  const contents = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    if (entry.action === "remove-file" || entry.action === "remove-managed-block") {
+      const content = await readFile(rootDir, entry.path);
+      if (content !== null) contents.set(entry.path, content);
     }
-    preservedLines.push(line);
   }
-  if (insideManagedBlock && !isManagedChunk(managedLines, 2)) {
-    preservedLines.push(...managedLines);
+  plannedContents.set(plan, contents);
+  return plan;
+};
+var applyLifecyclePlan = async (rootDir, plan) => {
+  if (!plan.applicable || plan.mode !== "apply") return plan;
+  const expected = plannedContents.get(plan);
+  const failure = async (entry) => {
+    if (entry.action !== "remove-file" && entry.action !== "remove-managed-block")
+      return null;
+    if (!await isSafeExactFile(rootDir, entry.path, false))
+      return `Unsafe lifecycle target: ${entry.path}`;
+    const content = await readFile(rootDir, entry.path);
+    if (content === null || expected?.get(entry.path) !== content)
+      return `Lifecycle target changed after planning: ${entry.path}`;
+    if (entry.action === "remove-managed-block" && parseManagedBlock(content).status !== "valid")
+      return `Managed block changed during removal: ${entry.path}`;
+    return null;
+  };
+  for (const entry of plan.entries) {
+    const message = await failure(entry);
+    if (message)
+      return {
+        ...plan,
+        applicable: false,
+        applied: false,
+        diagnostics: [
+          ...plan.diagnostics,
+          {
+            category: "generated-surface",
+            severity: "error",
+            message,
+            file: entry.path
+          }
+        ]
+      };
   }
-  const preservedContent = preservedLines.join("\n").replace(/\n{3,}/g, "\n\n").trim();
-  if (preservedContent.length === 0) {
-    return block;
+  for (const entry of plan.entries) {
+    const absolutePath = resolveRepoPath(rootDir, entry.path);
+    if (entry.action === "remove-file") {
+      const stat = await fs6.lstat(absolutePath);
+      if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1)
+        throw new Error(
+          `Refusing unsafe generated file removal: ${entry.path}`
+        );
+      await fs6.rm(absolutePath);
+    } else if (entry.action === "remove-managed-block") {
+      const stat = await fs6.lstat(absolutePath);
+      if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1)
+        throw new Error(`Refusing unsafe managed-block removal: ${entry.path}`);
+      const content = await fs6.readFile(absolutePath, "utf8");
+      const block = parseManagedBlock(content);
+      if (block.status !== "valid")
+        throw new Error(`Managed block changed during removal: ${entry.path}`);
+      const remaining = `${content.slice(0, block.start)}${content.slice(block.end)}`;
+      if (remaining.trim().length === 0) await fs6.rm(absolutePath);
+      else await fs6.writeFile(absolutePath, remaining, "utf8");
+    }
   }
-  return `${preservedContent}
-
-${block}`;
+  return { ...plan, applied: true };
 };
-var writeManagedAgentsFile = async (rootDir, path12 = "AGENTS.md", block) => {
+
+// src/init/init.ts
+var writeManagedAgentsFile = async (rootDir, path13 = "AGENTS.md", block) => {
   let existingContent = null;
   try {
-    existingContent = await fs7.readFile(resolveRepoPath(rootDir, path12), "utf8");
+    existingContent = await fs7.readFile(resolveRepoPath(rootDir, path13), "utf8");
   } catch (error) {
     if (!(error instanceof Error) || !("code" in error) || error.code !== "ENOENT") {
       throw error;
     }
   }
-  return writeRepoFile(rootDir, path12, upsertManagedBlock(existingContent, block));
+  return writeRepoFile(
+    rootDir,
+    path13,
+    upsertManagedBlock(existingContent, block)
+  );
 };
 var diagnosticCategoryForPath = (filePath, config) => {
   if (filePath === "AGENTS.md") {
@@ -5103,35 +5309,104 @@ var runInit = async (cwd) => {
   }
   const results = [];
   const config = loadedConfig.config;
-  results.push(...await scaffoldHierarchy(rootDir, config));
   const block = renderAgentsBlock(config);
   const platformFiles = renderGeneratedSurfaces(config, block);
-  const expectedSurfacePaths = new Set(platformFiles.map((file) => file.path));
+  const lifecyclePlan = await buildLifecyclePlan(
+    rootDir,
+    config,
+    "apply",
+    platformFiles
+  );
+  if (!lifecyclePlan.applicable) {
+    return {
+      command: "init",
+      summary: "Truthmark init made no changes because generated-surface preflight failed.",
+      diagnostics: [...loadedConfig.diagnostics, ...lifecyclePlan.diagnostics],
+      data: { lifecyclePlan }
+    };
+  }
+  const appliedLifecyclePlan = await applyLifecyclePlan(rootDir, lifecyclePlan);
+  if (!appliedLifecyclePlan.applicable) {
+    return {
+      command: "init",
+      summary: "Truthmark init made no changes because generated-surface preflight failed.",
+      diagnostics: [
+        ...loadedConfig.diagnostics,
+        ...appliedLifecyclePlan.diagnostics
+      ],
+      data: { lifecyclePlan: appliedLifecyclePlan }
+    };
+  }
+  results.push(...await scaffoldHierarchy(rootDir, config));
   for (const file of platformFiles) {
     results.push(await writePlatformFile(rootDir, file));
   }
-  const obsoleteSurfacePaths = await findAutoRemovableRetiredGeneratedSurfaces(
-    rootDir,
-    expectedSurfacePaths
+  const changedResults = results.filter(
+    (result) => result.status !== "unchanged"
+  );
+  const lifecycleChanged = appliedLifecyclePlan.entries.some(
+    ({ action }) => action === "remove-file" || action === "remove-managed-block"
   );
-  for (const obsoletePath of obsoleteSurfacePaths) {
-    await fs7.rm(resolveRepoPath(rootDir, obsoletePath), { force: true });
-  }
-  const changedResults = results.filter((result) => result.status !== "unchanged");
   return {
     command: "init",
-    summary: changedResults.length > 0 ? "Initialized or updated the Truthmark repository scaffold." : "Truthmark repository scaffold is already up to date.",
-    diagnostics: writeDiagnostics(results, config),
+    summary: changedResults.length > 0 || lifecycleChanged ? "Initialized or updated the Truthmark repository scaffold." : "Truthmark repository scaffold is already up to date.",
+    diagnostics: [
+      ...loadedConfig.diagnostics,
+      ...appliedLifecyclePlan.diagnostics,
+      ...appliedLifecyclePlan.entries.map((entry) => ({
+        category: "generated-surface",
+        severity: entry.action === "remove-file" || entry.action === "remove-managed-block" ? "action" : "review",
+        message: `${entry.action}: ${entry.reason}`,
+        file: entry.path
+      })),
+      ...writeDiagnostics(results, config)
+    ],
     data: {
       repositoryRoot: repository.repositoryRoot,
       worktreePath: repository.worktreePath,
       branchName: repository.branchName,
       isDetached: repository.isDetached,
-      isUnborn: repository.isUnborn
+      isUnborn: repository.isUnborn,
+      lifecyclePlan: appliedLifecyclePlan
     }
   };
 };
 
+// src/init/uninstall.ts
+var runUninstall = async (cwd, mode) => {
+  const repository = await getGitRepository(cwd);
+  const loaded = await loadConfig(repository.worktreePath);
+  if (!loaded.config) {
+    const lifecyclePlan = {
+      schemaVersion: "truthmark-lifecycle/v0",
+      mode,
+      entries: [],
+      diagnostics: loaded.diagnostics,
+      applicable: false,
+      applied: false
+    };
+    return {
+      command: "uninstall",
+      summary: "Truthmark uninstall requires a valid .truthmark/config.yml; no files were changed.",
+      diagnostics: loaded.diagnostics,
+      data: { lifecyclePlan }
+    };
+  }
+  const planned = await buildLifecyclePlan(
+    repository.worktreePath,
+    loaded.config,
+    mode,
+    []
+  );
+  const plan = await applyLifecyclePlan(repository.worktreePath, planned);
+  return {
+    command: "uninstall",
+    summary: mode === "dry-run" ? "Truthmark uninstall dry run completed; no files were changed." : plan.applied ? "Truthmark generated host surfaces were uninstalled; authored truth and config were preserved." : "Truthmark uninstall was not applied.",
+    diagnostics: [...loaded.diagnostics, ...plan.diagnostics],
+    data: { lifecyclePlan: plan }
+  };
+};
+
 // src/checks/branch-scope.ts
 import fs8 from "fs/promises";
 import fg from "fast-glob";
@@ -5211,7 +5486,7 @@ import fg2 from "fast-glob";
 var looksLikeGlob = (pattern) => {
   return /[*?[\]{}()!+@]/u.test(pattern);
 };
-var pathExists2 = async (absolutePath) => {
+var pathExists = async (absolutePath) => {
   try {
     await fs9.stat(absolutePath);
     return true;
@@ -5281,7 +5556,7 @@ var checkControlledPaths = async (rootDir, controlledPaths) => {
       });
       continue;
     }
-    if (!await pathExists2(absoluteEntryPath)) {
+    if (!await pathExists(absoluteEntryPath)) {
       diagnostics.push({
         category: "authority",
         severity: "error",
@@ -5499,7 +5774,7 @@ var checkFrontmatter = async (rootDir, config, markdownPaths, truthDocumentEntri
 // src/checks/links.ts
 import fs11 from "fs/promises";
 import path5 from "path";
-var pathExists3 = async (absolutePath) => {
+var pathExists2 = async (absolutePath) => {
   try {
     await fs11.stat(absolutePath);
     return true;
@@ -5545,7 +5820,7 @@ var checkLinks = async (rootDir, markdownPaths) => {
         });
         continue;
       }
-      if (!await pathExists3(absoluteTarget)) {
+      if (!await pathExists2(absoluteTarget)) {
         diagnostics.push({
           category: "links",
           severity: "error",
@@ -5559,14 +5834,76 @@ var checkLinks = async (rootDir, markdownPaths) => {
 };
 
 // src/checks/areas.ts
-import fs13 from "fs/promises";
-import fg4 from "fast-glob";
-import micromatch4 from "micromatch";
+import fs14 from "fs/promises";
+import fg5 from "fast-glob";
+import micromatch5 from "micromatch";
 
-// src/routing/area-resolver.ts
+// src/git/files.ts
 import fs12 from "fs/promises";
+import { execa as execa2 } from "execa";
 import fg3 from "fast-glob";
 import micromatch2 from "micromatch";
+var defaultIgnore = [".git/**", "node_modules/**", "dist/**", "build/**"];
+var normalizePath = (filePath) => filePath.replaceAll("\\", "/").replace(/^\.\/+/u, "");
+var isIgnoredPath = (filePath, ignorePatterns) => micromatch2.isMatch(filePath, [...defaultIgnore, ...ignorePatterns]);
+var gitDiscoverableFiles = async (rootDir) => {
+  try {
+    const result = await execa2(
+      "git",
+      [
+        "ls-files",
+        "-z",
+        "--cached",
+        "--others",
+        "--exclude-standard",
+        "--deduplicate"
+      ],
+      {
+        cwd: rootDir,
+        reject: false,
+        stripFinalNewline: false
+      }
+    );
+    if ((result.exitCode ?? 1) !== 0) {
+      return null;
+    }
+    return result.stdout.split("\0").filter((filePath) => filePath.length > 0).map(normalizePath);
+  } catch {
+    return null;
+  }
+};
+var isCurrentContainedFile = async (rootDir, relativePath) => {
+  try {
+    const absolutePath = resolveRepoPath(rootDir, relativePath);
+    await assertRepoContainment(rootDir, absolutePath);
+    return (await fs12.stat(absolutePath)).isFile();
+  } catch {
+    return false;
+  }
+};
+var discoverRepositoryFilePaths = async (rootDir, ignorePatterns) => {
+  const discoveredPaths = await gitDiscoverableFiles(rootDir) ?? await fg3(["**/*"], {
+    cwd: rootDir,
+    onlyFiles: true,
+    dot: true,
+    ignore: [...defaultIgnore, ...ignorePatterns],
+    followSymbolicLinks: false
+  });
+  const paths = [...new Set(discoveredPaths.map(normalizePath))].filter((filePath) => !isIgnoredPath(filePath, ignorePatterns)).sort();
+  const currentPaths = await Promise.all(
+    paths.map(async (filePath) => {
+      return await isCurrentContainedFile(rootDir, filePath) ? filePath : null;
+    })
+  );
+  return currentPaths.filter(
+    (filePath) => filePath !== null
+  );
+};
+
+// src/routing/area-resolver.ts
+import fs13 from "fs/promises";
+import fg4 from "fast-glob";
+import micromatch3 from "micromatch";
 var unique = (values) => {
   return [...new Set(values)];
 };
@@ -5585,7 +5922,7 @@ var isCodeSurfaceWithinParent = (childPattern, parentPatterns) => {
     return false;
   }
   return parentPatterns.some((parentPattern) => {
-    return micromatch2.isMatch(childPrefix, parentPattern) || micromatch2.isMatch(childPattern, parentPattern);
+    return micromatch3.isMatch(childPrefix, parentPattern) || micromatch3.isMatch(childPattern, parentPattern);
   });
 };
 var ensureChildPath = async (rootDir, areaFilesRoot, filePath) => {
@@ -5615,7 +5952,7 @@ var ensureChildPath = async (rootDir, areaFilesRoot, filePath) => {
 var readRouteFile = async (rootDir, filePath) => {
   try {
     return {
-      source: await fs12.readFile(resolveRepoPath(rootDir, filePath), "utf8"),
+      source: await fs13.readFile(resolveRepoPath(rootDir, filePath), "utf8"),
       diagnostic: null
     };
   } catch (error) {
@@ -5734,7 +6071,7 @@ var resolveAreaRouting = async (rootDir, config) => {
       );
     }
   }
-  const routeFilesUnderRoot = await fg3([`${config.areaFilesRoot}/**/*.md`], {
+  const routeFilesUnderRoot = await fg4([`${config.areaFilesRoot}/**/*.md`], {
     cwd: rootDir,
     onlyFiles: true,
     followSymbolicLinks: false
@@ -5776,7 +6113,8 @@ var resolveAreaRouting = async (rootDir, config) => {
 };
 
 // src/sync/classify.ts
-import micromatch3 from "micromatch";
+import path6 from "path";
+import micromatch4 from "micromatch";
 var CODE_EXTENSIONS = /* @__PURE__ */ new Set([
   ".c",
   ".cc",
@@ -5853,11 +6191,11 @@ var FUNCTIONAL_CONFIG_BASENAMES = /* @__PURE__ */ new Set([
   "swagger.yaml",
   "swagger.yml"
 ]);
-var normalizePath = (filePath) => {
+var normalizePath2 = (filePath) => {
   return filePath.replaceAll("\\", "/").replace(/^\.\//u, "");
 };
 var getBaseName = (filePath) => {
-  const segments = normalizePath(filePath).split("/");
+  const segments = normalizePath2(filePath).split("/");
   return segments.at(-1) ?? filePath;
 };
 var getExtension = (filePath) => {
@@ -5868,20 +6206,23 @@ var getExtension = (filePath) => {
   }
   return baseName.slice(extensionIndex).toLowerCase();
 };
+var isTestPath = (filePath) => {
+  return filePath.startsWith("tests/") || filePath.includes("/__tests__/") || /(?:^|[./-])(test|spec)\.[cm]?[jt]sx?$/u.test(path6.posix.basename(filePath));
+};
 var isConfigPath = (filePath) => {
-  const normalizedPath = normalizePath(filePath);
+  const normalizedPath = normalizePath2(filePath);
   const baseName = getBaseName(normalizedPath);
   const extension = getExtension(normalizedPath);
   return CONFIG_BASENAMES.has(baseName) || CONFIG_EXTENSIONS.has(extension) || CONFIG_SUFFIXES.some((suffix) => baseName.endsWith(suffix));
 };
 var isFunctionalConfigPath = (filePath) => {
-  const normalizedPath = normalizePath(filePath);
+  const normalizedPath = normalizePath2(filePath);
   const baseName = getBaseName(normalizedPath).toLowerCase();
   const extension = getExtension(normalizedPath);
   return normalizedPath.startsWith(".github/workflows/") || FUNCTIONAL_CONFIG_BASENAMES.has(baseName) || (extension === ".yaml" || extension === ".yml" || extension === ".json") && FUNCTIONAL_CONFIG_DIRECTORIES.test(normalizedPath);
 };
 var isCodeLikePath = (filePath) => {
-  const normalizedPath = normalizePath(filePath);
+  const normalizedPath = normalizePath2(filePath);
   const extension = getExtension(normalizedPath);
   if (CODE_EXTENSIONS.has(extension)) {
     return true;
@@ -5889,7 +6230,7 @@ var isCodeLikePath = (filePath) => {
   return extension.length === 0 && COMMON_CODE_DIRECTORIES.test(normalizedPath);
 };
 var classifyPath = (filePath, ignorePatterns) => {
-  const normalizedPath = normalizePath(filePath);
+  const normalizedPath = normalizePath2(filePath);
   if (normalizedPath === ".truthmark/config.yml") {
     return "config";
   }
@@ -5899,7 +6240,7 @@ var classifyPath = (filePath, ignorePatterns) => {
   if (normalizedPath.startsWith(".agents/skills/truthmark-") || normalizedPath.startsWith(".claude/") || normalizedPath.startsWith(".codex/") || normalizedPath.startsWith(".opencode/") || normalizedPath.startsWith(".antigravity/rules/truthmark-") || normalizedPath.startsWith(".cursor/rules/truthmark-") || normalizedPath.startsWith(".cursor/skills/truthmark-") || normalizedPath === ".github/copilot-instructions.md" || normalizedPath.startsWith(".github/agents/truth-") || normalizedPath.startsWith(".github/prompts/truthmark-") || normalizedPath.startsWith(".github/skills/truthmark-") || normalizedPath === "AGENTS.md" || normalizedPath === "CLAUDE.md") {
     return "derived";
   }
-  if (ignorePatterns.length > 0 && micromatch3.isMatch(normalizedPath, ignorePatterns)) {
+  if (ignorePatterns.length > 0 && micromatch4.isMatch(normalizedPath, ignorePatterns)) {
     return "ignored";
   }
   if (normalizedPath.toLowerCase().endsWith(".md")) {
@@ -5921,9 +6262,9 @@ var classifyPath = (filePath, ignorePatterns) => {
 var looksLikeGlob2 = (pattern) => {
   return /[*?[\]{}()!+@]/u.test(pattern);
 };
-var pathExists4 = async (absolutePath) => {
+var pathExists3 = async (absolutePath) => {
   try {
-    await fs13.stat(absolutePath);
+    await fs14.stat(absolutePath);
     return true;
   } catch (error) {
     if (error instanceof Error && "code" in error && error.code === "ENOENT") {
@@ -5932,33 +6273,6 @@ var pathExists4 = async (absolutePath) => {
     throw error;
   }
 };
-var COVERAGE_SCAN_PATTERNS = [
-  "app/**/*",
-  "api/**/*",
-  "apps/**/*",
-  "bin/**/*",
-  "client/**/*",
-  "cmd/**/*",
-  "frontend/**/*",
-  "infra/**/*",
-  "infrastructure/**/*",
-  "internal/**/*",
-  "k8s/**/*",
-  "kubernetes/**/*",
-  "lib/**/*",
-  "packages/**/*",
-  "pkg/**/*",
-  "proto/**/*",
-  "schema/**/*",
-  "schemas/**/*",
-  "scripts/**/*",
-  "server/**/*",
-  "services/**/*",
-  "src/**/*",
-  "terraform/**/*",
-  "web/**/*",
-  ".github/workflows/**/*"
-];
 var BROAD_CODE_SURFACES = /* @__PURE__ */ new Set([
   "app/**",
   "apps/**",
@@ -6080,15 +6394,12 @@ var checkAreas = async (rootDir, config) => {
     productTruthRoot: resolveProductTruthRoot(config),
     engineeringTruthRoot: resolveEngineeringTruthRoot(config)
   });
-  const discoveredCodeFiles = await fg4([...COVERAGE_SCAN_PATTERNS], {
-    cwd: rootDir,
-    onlyFiles: true,
-    ignore: config.ignore,
-    followSymbolicLinks: false,
-    dot: true
-  });
+  const discoveredCodeFiles = await discoverRepositoryFilePaths(
+    rootDir,
+    config.ignore
+  );
   const rawCodeFiles = discoveredCodeFiles.filter(
-    (filePath) => classifyPath(filePath, config.ignore) === "functional-code"
+    (filePath) => classifyPath(filePath, config.ignore) === "functional-code" && !isTestPath(filePath)
   );
   const diagnostics = [...routing.diagnostics];
   const truthDocumentPaths = [];
@@ -6100,15 +6411,7 @@ var checkAreas = async (rootDir, config) => {
     valid: true,
     patterns: []
   }));
-  const codeFiles = [];
-  for (const codeFile of rawCodeFiles.sort()) {
-    try {
-      await assertRepoContainment(rootDir, resolveRepoPath(rootDir, codeFile));
-      codeFiles.push(codeFile);
-    } catch {
-      continue;
-    }
-  }
+  const codeFiles = rawCodeFiles;
   const truthReferences = routing.truthDocumentReferences;
   for (const area of truthReferences) {
     let areaHasTruthDocumentErrors = false;
@@ -6158,7 +6461,7 @@ var checkAreas = async (rootDir, config) => {
     ] of area.truthDocuments.entries()) {
       const routedEntry = area.truthDocumentEntries[truthDocumentIndex];
       if (looksLikeGlob2(truthDocument)) {
-        const matches = (await fg4([truthDocument], { cwd: rootDir, onlyFiles: true })).sort();
+        const matches = (await fg5([truthDocument], { cwd: rootDir, onlyFiles: true })).sort();
         if (matches.length === 0) {
           diagnostics.push({
             category: "area-index",
@@ -6213,7 +6516,7 @@ var checkAreas = async (rootDir, config) => {
         areaHasTruthDocumentErrors = true;
         continue;
       }
-      if (!await pathExists4(absoluteTruthDocumentPath)) {
+      if (!await pathExists3(absoluteTruthDocumentPath)) {
         diagnostics.push({
           category: "area-index",
           severity: "error",
@@ -6266,7 +6569,7 @@ var checkAreas = async (rootDir, config) => {
           entry.valid = false;
           continue;
         }
-        const matches = await fg4([codeSurfaceEntry], {
+        const matches = await fg5([codeSurfaceEntry], {
           cwd: rootDir,
           onlyFiles: true,
           followSymbolicLinks: false
@@ -6317,7 +6620,7 @@ var checkAreas = async (rootDir, config) => {
         entry.valid = false;
         continue;
       }
-      if (!await pathExists4(absoluteCodeSurfacePath)) {
+      if (!await pathExists3(absoluteCodeSurfacePath)) {
         diagnostics.push({
           category: "area-index",
           severity: "error",
@@ -6332,7 +6635,7 @@ var checkAreas = async (rootDir, config) => {
   }
   for (const codeFile of codeFiles.sort()) {
     const matched = areaCoverage.some(
-      (entry) => entry.valid && entry.patterns.some((pattern) => micromatch4.isMatch(codeFile, pattern))
+      (entry) => entry.valid && entry.patterns.some((pattern) => micromatch5.isMatch(codeFile, pattern))
     );
     if (!matched) {
       diagnostics.push({
@@ -6364,8 +6667,8 @@ var checkAreas = async (rootDir, config) => {
 };
 
 // src/checks/decisions.ts
-import fs14 from "fs/promises";
-import micromatch5 from "micromatch";
+import fs15 from "fs/promises";
+import micromatch6 from "micromatch";
 var PRODUCT_CAPABILITY_REQUIRED_HEADINGS = [
   "Capability Promise",
   "Users And Value",
@@ -6401,11 +6704,11 @@ var FORBIDDEN_ENGINEERING_HEADINGS = [
 var isTruthDocumentKind3 = (value) => {
   return TRUTH_DOCUMENT_KINDS.includes(value);
 };
-var escapeRegExp2 = (value) => {
+var escapeRegExp = (value) => {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 };
 var hasHeading = (source, heading) => {
-  return new RegExp(`^#{2,3}\\s+${escapeRegExp2(heading)}\\s*$`, "mu").test(
+  return new RegExp(`^#{2,3}\\s+${escapeRegExp(heading)}\\s*$`, "mu").test(
     source
   );
 };
@@ -6469,7 +6772,7 @@ var decisionTruthGlobs = (config) => {
   ];
 };
 var isDecisionTruthCandidate = (config, filePath) => {
-  return !filePath.endsWith("/README.md") && micromatch5.isMatch(filePath, decisionTruthGlobs(config));
+  return !filePath.endsWith("/README.md") && micromatch6.isMatch(filePath, decisionTruthGlobs(config));
 };
 var checkDecisionSections = async (rootDir, config, markdownPaths, truthDocumentEntries = []) => {
   const diagnostics = [];
@@ -6480,7 +6783,7 @@ 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(
+    const source = await fs15.readFile(
       resolveRepoPath(rootDir, filePath),
       "utf8"
     );
@@ -6521,19 +6824,85 @@ var checkDecisionSections = async (rootDir, config, markdownPaths, truthDocument
   return diagnostics;
 };
 
+// src/checks/generated-surfaces.ts
+import fs16 from "fs/promises";
+var readOptionalFile = async (rootDir, filePath) => {
+  try {
+    return await fs16.readFile(resolveRepoPath(rootDir, filePath), "utf8");
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+      return null;
+    }
+    throw error;
+  }
+};
+var normalizeGeneratedSurfaceContent = (content) => {
+  if (content === null) {
+    return null;
+  }
+  return content.replace(/\r\n/g, "\n").replace(/\n$/u, "");
+};
+var isRetiredGeminiSurfacePath = (filePath) => filePath === "GEMINI.md" || filePath.startsWith(".gemini/");
+var obsoleteGeneratedSurfaceMessage = (surfacePath) => {
+  if (isRetiredGeminiSurfacePath(surfacePath)) {
+    return `Generated surface ${surfacePath} is obsolete; remove stale Gemini instructions manually if they are no longer wanted.`;
+  }
+  return `Generated surface ${surfacePath} is obsolete; rerun truthmark init.`;
+};
+var checkGeneratedSurfaces = async (rootDir, config) => {
+  const diagnostics = [];
+  const renderedSurfaces = renderGeneratedSurfaces(config);
+  for (const surface of renderedSurfaces) {
+    const content = await readOptionalFile(rootDir, surface.path);
+    if (content === null) {
+      diagnostics.push({
+        category: "generated-surface",
+        severity: "review",
+        message: `Generated surface ${surface.path} is missing; rerun truthmark init.`,
+        file: surface.path
+      });
+      continue;
+    }
+    const comparableContent = normalizeGeneratedSurfaceContent(
+      surface.managedBlock ? extractManagedBlock(content) : content
+    );
+    const expectedContent = normalizeGeneratedSurfaceContent(surface.content);
+    if (comparableContent !== expectedContent) {
+      diagnostics.push({
+        category: "generated-surface",
+        severity: "review",
+        message: `Generated surface ${surface.path} is stale; rerun truthmark init.`,
+        file: surface.path
+      });
+    }
+  }
+  const lifecyclePlan = await buildLifecyclePlan(
+    rootDir,
+    config,
+    "dry-run",
+    renderedSurfaces
+  );
+  for (const entry of lifecyclePlan.entries) {
+    diagnostics.push({
+      category: "generated-surface",
+      severity: entry.action === "manual-review" ? "error" : "review",
+      message: entry.action === "preserve" && (entry.path.includes("truthmark-preview") || entry.path.endsWith("helper-manifest.yml") || entry.path.endsWith("support/helper-policy.md") || isRetiredGeminiSurfacePath(entry.path)) ? obsoleteGeneratedSurfaceMessage(entry.path) : entry.action === "preserve" ? `Generated surface ${entry.path} is inactive but was preserved: ${entry.reason}` : `Generated surface ${entry.path} is inactive; rerun truthmark init to reconcile it.`,
+      file: entry.path
+    });
+  }
+  return diagnostics;
+};
+
 // src/impact/build.ts
-import path10 from "path";
+import path11 from "path";
 import micromatch7 from "micromatch";
 
 // src/repo-index/file-tree.ts
-import fs15 from "fs/promises";
-import path7 from "path";
-import { execa as execa2 } from "execa";
-import fg5 from "fast-glob";
-import micromatch6 from "micromatch";
+import fs17 from "fs/promises";
+import path8 from "path";
 
 // src/truth/source-references.ts
-import path6 from "path";
+import path7 from "path";
 var repoRootPrefixes = [
   ".codex/",
   ".github/",
@@ -6553,11 +6922,11 @@ var normalizeSourceReferencePath = (truthDocPath, referencePath) => {
     (prefix) => strippedPath.startsWith(prefix)
   );
   if (!isRepoRelative && (strippedPath.startsWith(".") || !strippedPath.includes("/"))) {
-    return path6.posix.normalize(
-      path6.posix.join(path6.posix.dirname(truthDocPath), strippedPath)
+    return path7.posix.normalize(
+      path7.posix.join(path7.posix.dirname(truthDocPath), strippedPath)
     );
   }
-  return path6.posix.normalize(strippedPath);
+  return path7.posix.normalize(strippedPath);
 };
 var normalizeReferenceText = (value) => {
   const trimmed = value.trim();
@@ -6622,9 +6991,6 @@ var languageByExtension = /* @__PURE__ */ new Map([
   [".yaml", "yaml"],
   [".toml", "toml"]
 ]);
-var isTestPath = (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);
   if (classification === "derived") {
@@ -6649,7 +7015,7 @@ var fileKind = (filePath, ignore) => {
 };
 var targetHintsForTest = (filePath) => {
   const hints = /* @__PURE__ */ new Set();
-  const basename = path7.posix.basename(filePath).replace(/\.(test|spec)\.[cm]?[jt]sx?$/u, "");
+  const basename = path8.posix.basename(filePath).replace(/\.(test|spec)\.[cm]?[jt]sx?$/u, "");
   if (basename.length > 0) {
     hints.add(basename);
   }
@@ -6666,43 +7032,18 @@ var targetHintsForTest = (filePath) => {
   }
   return [...hints].sort();
 };
-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",
-    ["ls-files", "--cached", "--others", "--exclude-standard", "--deduplicate"],
-    {
-      cwd: rootDir,
-      reject: false
-    }
-  );
-  if ((result.exitCode ?? 1) !== 0) {
-    return null;
-  }
-  return result.stdout.split("\n").map((line) => normalizePath2(line.trim())).filter((line) => line.length > 0);
-};
-var isIgnoredPath = (filePath, ignore) => {
-  return micromatch6.isMatch(filePath, [...defaultIgnore, ...ignore]);
-};
 var discoverRepoFiles = async (rootDir, ignore) => {
-  const discoveredFiles = await gitDiscoverableFiles(rootDir) ?? await fg5(["**/*"], {
-    cwd: rootDir,
-    onlyFiles: true,
-    dot: true,
-    ignore: [...defaultIgnore, ...ignore],
-    followSymbolicLinks: false
-  });
+  const discoveredFiles = await discoverRepositoryFilePaths(rootDir, ignore);
   const files = [];
   const docs = [];
   const tests = [];
-  for (const filePath of discoveredFiles.filter((entry) => !isIgnoredPath(entry, ignore)).sort()) {
+  for (const filePath of discoveredFiles) {
     let stat;
     try {
-      stat = await fs15.stat(path7.join(rootDir, filePath));
+      stat = await fs17.stat(path8.join(rootDir, filePath));
     } catch (error) {
       if (error instanceof Error && "code" in error && error.code === "ENOENT") {
         continue;
@@ -6712,7 +7053,7 @@ var discoverRepoFiles = async (rootDir, ignore) => {
     if (!stat.isFile()) {
       continue;
     }
-    const extension = path7.posix.extname(filePath);
+    const extension = path8.posix.extname(filePath);
     const kind = fileKind(filePath, ignore);
     files.push({
       path: filePath,
@@ -6726,7 +7067,7 @@ var discoverRepoFiles = async (rootDir, ignore) => {
       });
     }
     if (kind === "doc") {
-      const source = await fs15.readFile(path7.join(rootDir, filePath), "utf8");
+      const source = await fs17.readFile(path8.join(rootDir, filePath), "utf8");
       const parsed = parseFrontmatter(source);
       const markdown = parseMarkdownDocument(parsed.content);
       const title = markdown.headings.find((heading) => heading.depth === 1)?.text ?? null;
@@ -6754,8 +7095,8 @@ var discoverRepoFiles = async (rootDir, ignore) => {
 };
 
 // src/repo-index/package-metadata.ts
-import fs16 from "fs/promises";
-import path8 from "path";
+import fs18 from "fs/promises";
+import path9 from "path";
 import fg6 from "fast-glob";
 var packageManagerFor = async (rootDir, packageDir) => {
   const lockfiles = [
@@ -6767,7 +7108,7 @@ var packageManagerFor = async (rootDir, packageDir) => {
   ];
   for (const [lockfile, manager] of lockfiles) {
     try {
-      await fs16.access(path8.join(rootDir, packageDir, lockfile));
+      await fs18.access(path9.join(rootDir, packageDir, lockfile));
       return manager;
     } catch {
       continue;
@@ -6784,8 +7125,8 @@ var discoverPackageMetadata = async (rootDir) => {
   });
   const packages = [];
   for (const packageFile of packageFiles.sort()) {
-    const packageDir = path8.posix.dirname(packageFile) === "." ? "" : path8.posix.dirname(packageFile);
-    const raw = JSON.parse(await fs16.readFile(path8.join(rootDir, packageFile), "utf8"));
+    const packageDir = path9.posix.dirname(packageFile) === "." ? "" : path9.posix.dirname(packageFile);
+    const raw = JSON.parse(await fs18.readFile(path9.join(rootDir, packageFile), "utf8"));
     const scripts = raw.scripts && typeof raw.scripts === "object" ? Object.keys(raw.scripts).sort() : [];
     packages.push({
       path: packageFile,
@@ -6890,8 +7231,8 @@ var buildRepoIndex = async (cwd) => {
 import { execa as execa4 } from "execa";
 
 // src/git/changes.ts
-import fs17 from "fs/promises";
-import path9 from "path";
+import fs19 from "fs/promises";
+import path10 from "path";
 import { execa as execa3 } from "execa";
 var normalizePath3 = (filePath) => {
   return filePath.replaceAll("\\", "/").replace(/^\.\//u, "");
@@ -6900,9 +7241,9 @@ var listChangedPaths = async (cwd, args) => {
   const result = await execa3("git", args, { cwd });
   return result.stdout.split("\n").map((line) => line.trim()).filter((line) => line.length > 0).map((line) => normalizePath3(line));
 };
-var pathExists5 = async (filePath) => {
+var pathExists4 = async (filePath) => {
   try {
-    await fs17.access(filePath);
+    await fs19.access(filePath);
     return true;
   } catch {
     return false;
@@ -6946,7 +7287,7 @@ var getUncommittedChanges = async (cwd) => {
   const deletedPathCandidates = /* @__PURE__ */ new Set([...stagedDeletedPaths, ...unstagedDeletedPaths]);
   for (const deletedPath of deletedPathCandidates) {
     const change = getOrCreateChange(changesByPath, deletedPath);
-    change.deleted = !await pathExists5(path9.join(rootDir, deletedPath));
+    change.deleted = !await pathExists4(path10.join(rootDir, deletedPath));
   }
   return Array.from(changesByPath.values()).sort((left, right) => {
     return left.path.localeCompare(right.path);
@@ -7050,10 +7391,10 @@ var toImpactRoute = (route) => ({
 var changedFilePaths = (changedFile) => {
   return [changedFile.path, ...changedFile.previousPath ? [changedFile.previousPath] : []];
 };
-var pathSegments = (filePath) => filePath.split("/").filter(Boolean);
+var pathSegments2 = (filePath) => filePath.split("/").filter(Boolean);
 var testHintMatchesChangedFile = (hints, changedPath) => {
-  const changedBaseName = path10.posix.basename(changedPath);
-  const changedSegments = pathSegments(changedPath);
+  const changedBaseName = path11.posix.basename(changedPath);
+  const changedSegments = pathSegments2(changedPath);
   return hints.some((hint) => changedBaseName.startsWith(hint) || changedSegments.includes(hint));
 };
 var buildImpactSet = async (cwd, options) => {
@@ -7149,12 +7490,12 @@ var checkFreshness = async (rootDir, _config, _truthDocumentPaths, base) => {
 };
 
 // src/evidence/validate.ts
-import fs19 from "fs/promises";
+import fs21 from "fs/promises";
 import fg7 from "fast-glob";
 
 // src/evidence/parse.ts
-import fs18 from "fs/promises";
-import path11 from "path";
+import fs20 from "fs/promises";
+import path12 from "path";
 import { parse as parse4 } from "yaml";
 var yamlFencePattern = /```ya?ml\s*\n([\s\S]*?)```/giu;
 var topLevelEvidenceMarkerPattern = /^evidence\s*:/imu;
@@ -7173,7 +7514,7 @@ var toEvidenceReference = (truthDocPath, raw) => {
   };
 };
 var parseEvidenceReferences = async (rootDir, truthDocPath) => {
-  const source = await fs18.readFile(path11.join(rootDir, truthDocPath), "utf8");
+  const source = await fs20.readFile(path12.join(rootDir, truthDocPath), "utf8");
   const parsed = parseFrontmatter(source);
   const references = [];
   for (const entry of parseSourceReferences(source, truthDocPath)) {
@@ -7204,9 +7545,9 @@ var parseEvidenceReferences = async (rootDir, truthDocPath) => {
 };
 
 // src/evidence/validate.ts
-var pathExists6 = async (filePath) => {
+var pathExists5 = async (filePath) => {
   try {
-    await fs19.access(filePath);
+    await fs21.access(filePath);
     return true;
   } catch {
     return false;
@@ -7251,7 +7592,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 fs19.readFile(resolveRepoPath(rootDir, reference.path), "utf8");
+  const source = await fs21.readFile(resolveRepoPath(rootDir, reference.path), "utf8");
   const lines = source.split("\n");
   const startLine = reference.startLine ?? 1;
   const endLine = reference.endLine ?? lines.length;
@@ -7265,7 +7606,7 @@ var validateLineSpan = async (rootDir, reference) => {
   if (reference.startLine === void 0 && reference.endLine === void 0) {
     return null;
   }
-  const source = await fs19.readFile(resolveRepoPath(rootDir, reference.path), "utf8");
+  const source = await fs21.readFile(resolveRepoPath(rootDir, reference.path), "utf8");
   const lines = source.split("\n");
   const startLine = reference.startLine ?? 1;
   const endLine = reference.endLine ?? lines.length;
@@ -7280,7 +7621,7 @@ var validateReference = async (rootDir, reference) => {
     }
     const absolutePath = resolveRepoPath(rootDir, reference.path);
     await assertRepoContainment(rootDir, absolutePath);
-    if (!await pathExists6(absolutePath)) {
+    if (!await pathExists5(absolutePath)) {
       diagnostics.push(diagnosticFor(reference, `Referenced file ${reference.path} does not exist.`));
       return diagnostics;
     }
@@ -7712,7 +8053,7 @@ var candidateStaleTruthDocsFor = (repoIndex, primaryTruthDocs, impactSet, diagno
     ]);
   };
   for (const truthDoc of [...primary, ...changedPaths].filter(
-    (path12) => indexedTruthDocs.has(path12)
+    (path13) => indexedTruthDocs.has(path13)
   )) {
     for (const linkedTruthDoc of linkedTruthDocs(truthDoc)) {
       addCandidate(linkedTruthDoc);
@@ -7910,7 +8251,7 @@ var buildWorkflowState = async (cwd, options) => {
 };
 
 // src/cli/handlers.ts
-import fs20 from "fs/promises";
+import fs22 from "fs/promises";
 
 // src/agents/workflow-helper-validation.ts
 import { parse as parseYaml2 } from "yaml";
@@ -8233,13 +8574,20 @@ var runConfig2 = async (options) => {
 var runInit2 = async () => {
   return runInit(process.cwd());
 };
+var runUninstall2 = async (mode) => {
+  return runUninstall(process.cwd(), mode);
+};
 var runCheck2 = async (options = {}) => {
   return runCheck(process.cwd(), options);
 };
 var runIndex = async () => {
   const repoIndex = await buildRepoIndex(process.cwd());
-  const errorCount = repoIndex.diagnostics.filter((diagnostic) => diagnostic.severity === "error").length;
-  const reviewCount = repoIndex.diagnostics.filter((diagnostic) => diagnostic.severity === "review").length;
+  const errorCount = repoIndex.diagnostics.filter(
+    (diagnostic) => diagnostic.severity === "error"
+  ).length;
+  const reviewCount = repoIndex.diagnostics.filter(
+    (diagnostic) => diagnostic.severity === "review"
+  ).length;
   return {
     command: "index",
     summary: `Truthmark index completed with ${errorCount} error diagnostics and ${reviewCount} review diagnostics.`,
@@ -8265,8 +8613,12 @@ var runImpact = async (options) => {
     };
   }
   const impactSet = await buildImpactSet(process.cwd(), { base: options.base });
-  const errorCount = impactSet.diagnostics.filter((diagnostic) => diagnostic.severity === "error").length;
-  const reviewCount = impactSet.diagnostics.filter((diagnostic) => diagnostic.severity === "review").length;
+  const errorCount = impactSet.diagnostics.filter(
+    (diagnostic) => diagnostic.severity === "error"
+  ).length;
+  const reviewCount = impactSet.diagnostics.filter(
+    (diagnostic) => diagnostic.severity === "review"
+  ).length;
   return {
     command: "impact",
     summary: `Truthmark impact completed with ${errorCount} error diagnostics and ${reviewCount} review diagnostics.`,
@@ -8295,7 +8647,7 @@ var invalidWorkflowResult = (command, workflow) => ({
 });
 var readHelperFile = async (filePath, helper) => {
   try {
-    return await fs20.readFile(filePath, "utf8");
+    return await fs22.readFile(filePath, "utf8");
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     return { ok: false, helper, errors: [`could not read file: ${message}`] };
@@ -8314,7 +8666,10 @@ var runValidateWriteLease = async (leaseFile, changedFilesFile) => {
   if (typeof leaseText !== "string") {
     return leaseText;
   }
-  const changedText = await readHelperFile(changedFilesFile, "validate-write-lease");
+  const changedText = await readHelperFile(
+    changedFilesFile,
+    "validate-write-lease"
+  );
   if (typeof changedText !== "string") {
     return changedText;
   }
@@ -8356,9 +8711,15 @@ var writeResult = (result, options) => {
 };
 var renderValidationHuman = (result) => {
   if (result.ok === true) {
-    return [`${result.helper}: ok`, ...result.checks.map((check) => `- ${check}`)].join("\n");
+    return [
+      `${result.helper}: ok`,
+      ...result.checks.map((check) => `- ${check}`)
+    ].join("\n");
   }
-  return [`${result.helper}: failed`, ...result.errors.map((error) => `- ${error}`)].join("\n");
+  return [
+    `${result.helper}: failed`,
+    ...result.errors.map((error) => `- ${error}`)
+  ].join("\n");
 };
 var toValidationCommandResult = (command, result) => ({
   command,
@@ -8381,35 +8742,69 @@ var addJsonOption = (command) => {
 };
 var buildProgram = () => {
   const program = new Command();
-  program.name("truthmark").description("Git-native, branch-scoped truth workflow installer for local AI coding agents.").showHelpAfterError();
+  program.name("truthmark").description(
+    "Git-native, branch-scoped truth workflow installer for local AI coding agents."
+  ).showHelpAfterError();
   addJsonOption(
-    program.command("config").description("Create or render the Truthmark repository config before initialization.").option("--stdout", "Render default config in the JSON data payload without writing").option("--force", "Overwrite an existing .truthmark/config.yml")
+    program.command("config").description(
+      "Create or render the Truthmark repository config before initialization."
+    ).option(
+      "--stdout",
+      "Render default config in the JSON data payload without writing"
+    ).option("--force", "Overwrite an existing .truthmark/config.yml")
   ).action(async (options) => {
     writeResult(await runConfig2(options), options);
   });
   addJsonOption(
-    program.command("init").description("Initialize Truthmark workflow files in the current repository.")
+    program.command("init").description(
+      "Initialize Truthmark workflow files in the current repository."
+    )
   ).action(async (options) => {
     writeResult(await runInit2(), options);
   });
+  addJsonOption(
+    program.command("uninstall").description(
+      "Remove recognized generated host surfaces while preserving truth, config, Portal output, Gemini, and user files."
+    ).option("--dry-run", "Plan removals without changing files").option("--apply", "Apply the planned safe removals")
+  ).action(async (options) => {
+    if (Boolean(options.dryRun) === Boolean(options.apply)) {
+      program.error(
+        "truthmark uninstall requires exactly one of --dry-run or --apply"
+      );
+      return;
+    }
+    writeResult(
+      await runUninstall2(options.apply ? "apply" : "dry-run"),
+      options
+    );
+  });
   addJsonOption(
     program.command("check").description("Run local Truthmark diagnostics.").option("--base <ref>", "Base Git ref for freshness diagnostics")
   ).action(async (options) => {
     writeResult(await runCheck2({ base: options.base }), options);
   });
   addJsonOption(
-    program.command("index").description("Inspect derived Truthmark workflow routing metadata for the current checkout.")
+    program.command("index").description(
+      "Inspect derived Truthmark workflow routing metadata for the current checkout."
+    )
   ).action(async (options) => {
     writeResult(await runIndex(), options);
   });
   addJsonOption(
-    program.command("impact").description("Map changed files to truth routes, docs, owners, and tests.").requiredOption("--base <ref>", "Base Git ref to compare against")
+    program.command("impact").description(
+      "Map changed files to truth routes, docs, owners, and tests."
+    ).requiredOption("--base <ref>", "Base Git ref to compare against")
   ).action(async (options) => {
     writeResult(await runImpact({ base: options.base }), 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")
+    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")
   ).action(async (options) => {
     writeResult(
       await runWorkflowStatus({
@@ -8419,11 +8814,17 @@ var buildProgram = () => {
       options
     );
   });
-  const validate = program.command("validate").description("Run optional Truthmark workflow helper validators from the installed CLI.");
+  const validate = program.command("validate").description(
+    "Run optional Truthmark workflow helper validators from the installed CLI."
+  );
   addJsonOption(
     validate.command("sync-report").description("Validate a Truth Sync report file.").argument("<report-file>", "Truth Sync report file")
   ).action(async (reportFile, options) => {
-    writeValidationResult("validate sync-report", await runValidateSyncReport(reportFile), options);
+    writeValidationResult(
+      "validate sync-report",
+      await runValidateSyncReport(reportFile),
+      options
+    );
   });
   addJsonOption(
     validate.command("document-report").description("Validate a Truth Document report file.").argument("<report-file>", "Truth Document report file")
@@ -8435,7 +8836,9 @@ var buildProgram = () => {
     );
   });
   addJsonOption(
-    validate.command("write-lease").description("Validate a workflow write lease or worker report against changed files.").argument("<lease-or-report-file>", "Lease or worker report file").argument("<changed-files-file>", "Newline-separated changed file list")
+    validate.command("write-lease").description(
+      "Validate a workflow write lease or worker report against changed files."
+    ).argument("<lease-or-report-file>", "Lease or worker report file").argument("<changed-files-file>", "Newline-separated changed file list")
   ).action(
     async (leaseOrReportFile, changedFilesFile, options) => {
       writeValidationResult(