truthmark 1.4.0 → 1.6.0

package/dist/main.js

@@ -334,6 +334,22 @@ var truthmarkConfigSchema = {
         type: "string"
       }
     },
+    "truthmark-portal": {
+      type: "object",
+      additionalProperties: false,
+      required: [],
+      properties: {
+        enabled: {
+          type: "boolean"
+        },
+        output: {
+          type: "string"
+        },
+        template: {
+          type: "string"
+        }
+      }
+    },
     frontmatter: {
       type: "object",
       nullable: true,
@@ -391,6 +407,11 @@ var DEFAULT_AUTHORITY = [
   `${DEFAULT_DOCS_HIERARCHY.roots.truth}/**/*.md`
 ];
 var DEFAULT_INSTRUCTION_TARGETS = ["AGENTS.md"];
+var DEFAULT_TRUTHMARK_PORTAL = {
+  enabled: false,
+  output: "docs/truthmark-portal",
+  template: "default"
+};
 var createDefaultRawConfig = () => ({
   version: 1,
   platforms: [...DEFAULT_PLATFORMS],
@@ -422,6 +443,7 @@ var createDefaultConfig = () => ({
   },
   authority: [...DEFAULT_AUTHORITY],
   instructionTargets: [...DEFAULT_INSTRUCTION_TARGETS],
+  truthmarkPortal: { ...DEFAULT_TRUTHMARK_PORTAL },
   frontmatter: {
     required: [],
     recommended: ["status", "doc_type", "last_reviewed", "source_of_truth"]
@@ -578,9 +600,9 @@ var parseTruthDocumentsFromYaml = (sectionLines, areaName) => {
   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;
-    if (typeof path12 !== "string" || path12.trim().length === 0 || !isTruthDocumentKind(kind)) {
+    if (typeof path13 !== "string" || path13.trim().length === 0 || !isTruthDocumentKind(kind)) {
       diagnostics.push(
         createAreaDiagnostic(
           `Area ${areaName} truth_documents entries must include non-empty path and valid kind fields.`,
@@ -590,7 +612,7 @@ var parseTruthDocumentsFromYaml = (sectionLines, areaName) => {
       continue;
     }
     truthDocumentEntries.push({
-      path: path12.trim(),
+      path: path13.trim(),
       kind,
       kindSource: "explicit"
     });
@@ -1160,6 +1182,7 @@ import fs7 from "fs/promises";
 
 // src/config/load.ts
 import fs4 from "fs/promises";
+import path4 from "path";
 import { Ajv } from "ajv";
 import { parse as parse2 } from "yaml";
 var ajv = new Ajv({ allErrors: true });
@@ -1172,6 +1195,69 @@ var toConfigDiagnostic = (message, file) => {
     file
   };
 };
+var normalizeRepoRelativePath = (value) => {
+  const slashNormalized = value.replace(/\\/gu, "/");
+  const pathNormalized = path4.posix.normalize(slashNormalized).replace(/\/+$/u, "");
+  return pathNormalized;
+};
+var isUnsafeRepoRelativePath = (value) => {
+  const slashNormalized = value.replace(/\\/gu, "/");
+  const normalized = normalizeRepoRelativePath(value);
+  const parts = slashNormalized.split("/");
+  return normalized.length === 0 || normalized === "." || normalized === ".." || path4.isAbsolute(value) || path4.posix.isAbsolute(slashNormalized) || path4.win32.isAbsolute(value) || /^[A-Za-z]:/u.test(value) || normalized.startsWith("../") || parts.includes("..");
+};
+var pathsOverlap = (left, right) => {
+  const normalizedLeft = normalizeRepoRelativePath(left);
+  const normalizedRight = normalizeRepoRelativePath(right);
+  return normalizedLeft === normalizedRight || normalizedLeft.startsWith(`${normalizedRight}/`) || normalizedRight.startsWith(`${normalizedLeft}/`);
+};
+var portalForbiddenOutputRoots = (rawConfig) => {
+  const rawDocs = rawConfig.docs;
+  const docsRoots = rawDocs?.roots ?? {};
+  const routing = rawDocs?.routing ?? DEFAULT_DOCS_HIERARCHY.routing;
+  return [
+    "src",
+    DEFAULT_DOCS_HIERARCHY.roots.ai,
+    DEFAULT_DOCS_HIERARCHY.roots.standards,
+    DEFAULT_DOCS_HIERARCHY.roots.architecture,
+    DEFAULT_DOCS_HIERARCHY.roots.truth,
+    ...Object.values(docsRoots),
+    routing.root_index,
+    routing.area_files_root,
+    ".truthmark/config.yml",
+    "AGENTS.md",
+    "CLAUDE.md",
+    "GEMINI.md",
+    ".github/copilot-instructions.md",
+    ...rawConfig.instruction_targets ?? DEFAULT_INSTRUCTION_TARGETS
+  ];
+};
+var validatePortalConfig = (rawConfig, configPath) => {
+  const portal = rawConfig["truthmark-portal"];
+  if (portal === void 0) {
+    return [];
+  }
+  const diagnostics = [];
+  const output = portal.output ?? DEFAULT_TRUTHMARK_PORTAL.output;
+  const template = portal.template ?? DEFAULT_TRUTHMARK_PORTAL.template;
+  if (isUnsafeRepoRelativePath(output) || portalForbiddenOutputRoots(rawConfig).some((forbidden) => pathsOverlap(output, forbidden))) {
+    diagnostics.push(
+      toConfigDiagnostic(
+        "truthmark-portal.output must be a non-empty repo-relative directory that does not overlap source, instruction, routing, or canonical docs roots.",
+        configPath
+      )
+    );
+  }
+  if (template !== "default" && isUnsafeRepoRelativePath(template)) {
+    diagnostics.push(
+      toConfigDiagnostic(
+        "truthmark-portal.template must be 'default' or a non-empty repo-relative template path without absolute or parent traversal segments.",
+        configPath
+      )
+    );
+  }
+  return diagnostics;
+};
 var normalizeConfig = (rawConfig) => {
   const rawDocs = rawConfig.docs ?? {
     layout: DEFAULT_DOCS_HIERARCHY.layout,
@@ -1194,6 +1280,11 @@ var normalizeConfig = (rawConfig) => {
     },
     authority: rawConfig.authority,
     instructionTargets: rawConfig.instruction_targets ?? [...DEFAULT_INSTRUCTION_TARGETS],
+    truthmarkPortal: {
+      enabled: rawConfig["truthmark-portal"]?.enabled ?? DEFAULT_TRUTHMARK_PORTAL.enabled,
+      output: rawConfig["truthmark-portal"]?.output ?? DEFAULT_TRUTHMARK_PORTAL.output,
+      template: rawConfig["truthmark-portal"]?.template ?? DEFAULT_TRUTHMARK_PORTAL.template
+    },
     frontmatter: {
       required: rawConfig.frontmatter?.required ?? [],
       recommended: rawConfig.frontmatter?.recommended ?? []
@@ -1247,6 +1338,18 @@ var loadConfig = async (rootDir) => {
       configPath
     };
   }
+  const portalDiagnostics = validatePortalConfig(
+    parsedConfig,
+    configPath
+  );
+  if (portalDiagnostics.length > 0) {
+    return {
+      status: "invalid",
+      config: null,
+      diagnostics: portalDiagnostics,
+      configPath
+    };
+  }
   return {
     status: "loaded",
     config: normalizeConfig(parsedConfig),
@@ -1409,13 +1512,13 @@ var DECISION_TRUTH_INSTRUCTIONS = [
   "Update Product Decisions and Rationale when a decision changes behavior."
 ].join("\n");
 var EVIDENCE_AUTHORITY_INSTRUCTIONS = [
-  "Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority.",
+  "Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path.",
   "Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries."
 ].join("\n");
 var REPOSITORY_INTELLIGENCE_INSTRUCTIONS = [
   "Repository intelligence artifacts are optional derived context: RepoIndex, RouteMap, ImpactSet, and ContextPack may guide routing, context selection, and verification planning when available.",
   "They do not override checkout evidence, canonical truth docs, route files, or workflow write boundaries.",
-  "If unavailable, inspect .truthmark/config.yml, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated."
+  "If unavailable, inspect any present Truthmark config, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated."
 ].join("\n");
 var FEATURE_DOC_TEMPLATE_INSTRUCTIONS = [
   "When creating or updating a truth doc, inspect the routed truth kind and use the matching `docs/templates/<kind>-doc.md` template.",
@@ -1567,17 +1670,38 @@ var renderCopilotCustomAgentModeSection = (agents, parentRule, writeAgents = [])
     `- ${parentRule}`
   ].join("\n");
 };
+var renderGeminiSubagentModeSection = (agents, parentRule, writeAgents = []) => {
+  const mentions = agents.map((agent) => `@${agent.replace(/_/gu, "-")}`);
+  const writeMentions = writeAgents.map((agent) => `@${agent.replace(/_/gu, "-")}`);
+  const writeAgentLines = writeMentions.length > 0 ? [
+    `- dispatch write-capable project subagents only with explicit write leases: ${writeMentions.join(", ")}`,
+    "- each write lease must name objective, required reads, allowed writes, forbidden writes, evidence, verification, and report fields",
+    "- 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 readOnlySubagentLabel = writeAgents.length > 0 ? "read-only subagents" : "subagents";
+  return [
+    "Gemini CLI subagent mode:",
+    "- use automatically when this workflow runs in Gemini CLI and the parent agent chooses bounded project subagent fan-out",
+    `- dispatch read-only project subagents ${readOnlyScope}: ${mentions.join(", ")}`,
+    `- ${readOnlySubagentLabel} inspect checkout evidence directly, return structured findings, and must not edit files`,
+    `- parent supplies bounded evidence shards; ${readOnlySubagentLabel} 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 truthRoot3 = resolveTruthDocsRoot(config);
   return [
-    "Truthmark hierarchy:",
-    "- Config: .truthmark/config.yml",
-    `- Root route index: ${config.docs.routing.rootIndex}`,
-    `- Area route files: ${config.docs.routing.areaFilesRoot}/**/*.md`,
-    `- Truth docs: ${truthRoot3}/**/*.md`
+    "Truthmark hierarchy hints:",
+    "- Config, when present: .truthmark/config.yml",
+    `- Root route index, when present: ${config.docs.routing.rootIndex}`,
+    `- Area route files, when present: ${config.docs.routing.areaFilesRoot}/**/*.md`,
+    `- Truth docs, when present: ${truthRoot3}/**/*.md`
   ].join("\n");
 };
 
@@ -1593,9 +1717,10 @@ var TRUTHMARK_BLOCK_START = "<!-- truthmark:start -->";
 var TRUTHMARK_BLOCK_END = "<!-- truthmark:end -->";
 var renderCompactHierarchySummary = (config) => {
   const truthRoot3 = resolveTruthDocsRoot(config);
-  return `Hierarchy: config .truthmark/config.yml; routes ${config.docs.routing.rootIndex} and ${config.docs.routing.areaFilesRoot}/**/*.md; Truth docs: ${truthRoot3}/**/*.md.`;
+  return `Hierarchy hints: config .truthmark/config.yml when present; routes ${config.docs.routing.rootIndex} and ${config.docs.routing.areaFilesRoot}/**/*.md when present; Truth docs: ${truthRoot3}/**/*.md when present.`;
 };
 var renderAgentsBlock = (config = defaultAgentConfig()) => {
+  const portalLine = config.truthmarkPortal.enabled ? `Truthmark Portal is a separate manual-only presentation workflow. Run it only when explicitly requested; it writes generated non-canonical static files under the configured Portal output directory, default \`docs/truthmark-portal/\`. Markdown remains canonical.` : null;
   return [
     TRUTHMARK_BLOCK_START,
     "## Truthmark Workflow",
@@ -1609,6 +1734,7 @@ var renderAgentsBlock = (config = defaultAgentConfig()) => {
     "Support new or changed behavior-bearing truth claims with checkout evidence. Code leads; truth docs follow. Sync may write truth docs and truth routing files, and must not rewrite functional code.",
     "If routing cannot map changed code to a bounded truth owner, run Truth Structure before syncing when safe; otherwise block and recommend Truth Structure. Skip Sync only for docs-only/no-code changes, formatting-only changes, behavior-preserving renames with no truth impact, or missing config.",
     "Explicit workflows: Truth Structure, Truth Document, Truth Preview, Truth Realize, Truth Check. Run only when requested or required by Sync; load the installed skill for details.",
+    ...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");
@@ -1678,7 +1804,50 @@ var renderDefaultStandards = (documents) => {
   return DEFAULT_STANDARDS.filter((template) => !existingPaths.has(template.path));
 };
 
+// src/templates/workflow-surfaces.ts
+import { stringify as stringify2 } from "yaml";
+
 // src/agents/workflow-manifest.ts
+var TRUTHMARK_CLI_RUNNER = `truthmark>=${TRUTHMARK_VERSION}`;
+var VALIDATE_SYNC_REPORT_HELPER = {
+  id: "validate-sync-report",
+  optional: true,
+  runner: TRUTHMARK_CLI_RUNNER,
+  command: { argv: ["truthmark", "validate", "sync-report", "<report-file>", "--json"] },
+  inputs: ["sync report file"],
+  output: "json",
+  writes: false,
+  fallback: "manually validate support/report-template.md and check Evidence checked entries match Claim, indented Evidence, and Result: supported | narrowed | removed | blocked"
+};
+var VALIDATE_DOCUMENT_REPORT_HELPER = {
+  id: "validate-document-report",
+  optional: true,
+  runner: TRUTHMARK_CLI_RUNNER,
+  command: { argv: ["truthmark", "validate", "document-report", "<report-file>", "--json"] },
+  inputs: ["document report file"],
+  output: "json",
+  writes: false,
+  fallback: "manually validate support/report-template.md required sections and structured Evidence checked entries"
+};
+var VALIDATE_WRITE_LEASE_HELPER = {
+  id: "validate-write-lease",
+  optional: true,
+  runner: TRUTHMARK_CLI_RUNNER,
+  command: {
+    argv: [
+      "truthmark",
+      "validate",
+      "write-lease",
+      "<lease-or-report-file>",
+      "<changed-files-file>",
+      "--json"
+    ]
+  },
+  inputs: ["lease or worker report yaml", "changed file list"],
+  output: "json",
+  writes: false,
+  fallback: "manually compare declared allowedWrites and forbiddenWrites with the actual changed files"
+};
 var TRUTHMARK_WORKFLOW_MANIFEST = {
   "truthmark-sync": {
     id: "truthmark-sync",
@@ -1717,10 +1886,12 @@ var TRUTHMARK_WORKFLOW_MANIFEST = {
       "Truth docs updated",
       "Truth docs split",
       "Evidence checked",
+      "Helper scripts",
       "Notes"
     ],
     subagents: ["truth_route_auditor", "truth_claim_verifier"],
-    writeSubagents: ["truth_doc_writer"]
+    writeSubagents: ["truth_doc_writer"],
+    helpers: [VALIDATE_SYNC_REPORT_HELPER, VALIDATE_WRITE_LEASE_HELPER]
   },
   "truthmark-structure": {
     id: "truthmark-structure",
@@ -1801,10 +1972,12 @@ var TRUTHMARK_WORKFLOW_MANIFEST = {
       "Truth docs restructured",
       "Routing updated",
       "Evidence checked",
+      "Helper scripts",
       "Notes"
     ],
     subagents: ["truth_route_auditor", "truth_claim_verifier"],
-    writeSubagents: ["truth_doc_writer"]
+    writeSubagents: ["truth_doc_writer"],
+    helpers: [VALIDATE_DOCUMENT_REPORT_HELPER, VALIDATE_WRITE_LEASE_HELPER]
   },
   "truthmark-realize": {
     id: "truthmark-realize",
@@ -1902,6 +2075,50 @@ var TRUTHMARK_WORKFLOW_MANIFEST = {
       "truth_claim_verifier",
       "truth_doc_reviewer"
     ]
+  },
+  "truthmark-portal": {
+    id: "truthmark-portal",
+    displayName: "Truthmark Portal",
+    description: "Use when the user explicitly asks to generate, refresh, or update the Truthmark Portal static HTML site. Not for code change sync, route repair, truth validation/checking, documenting behavior, realizing docs into code, or machine-readable agent context.",
+    shortDescription: "Generate a committed static HTML Truthmark Portal",
+    defaultPrompt: "Use $truthmark-portal only when explicitly asked to generate or refresh the committed static HTML Portal.",
+    allowImplicitInvocation: false,
+    positiveTriggers: [
+      "generate the Truthmark Portal",
+      "refresh the committed HTML docs site",
+      "create a browsable project map from Truthmark docs",
+      "update docs/truthmark-portal",
+      "make a human-readable static site from the truth docs"
+    ],
+    negativeTriggers: [
+      "code change sync",
+      "route ownership repair",
+      "truth validation or checking",
+      "document implemented behavior",
+      "realize docs into code",
+      "machine-readable agent context"
+    ],
+    forbiddenAdjacency: [
+      "must not run as a completion gate",
+      "must not replace Truth Sync, Truth Check, Truth Document, Truth Realize, or Truth Structure",
+      "must not write outside the configured Portal output directory unless the user changes scope"
+    ],
+    requiredGates: [
+      "manual-only invocation",
+      "Portal output containment",
+      "Markdown canonical statement",
+      "source provenance"
+    ],
+    allowedWrites: ["configured Portal output directory only"],
+    reportSections: [
+      "Output path",
+      "Page count",
+      "Diagrams/assets",
+      "Source docs reviewed",
+      "Skipped/ambiguous docs",
+      "Validation",
+      "Markdown canonical statement"
+    ]
   }
 };
 var TRUTHMARK_WORKFLOW_IDS = Object.keys(
@@ -1932,7 +2149,7 @@ Fixes suggested:
 ${renderAuditEvidenceCheckedSection([
     {
       finding: "The root route index is present and maps repository truth owners.",
-      evidence: [".truthmark/config.yml:1", `${rootRouteIndex}:1`],
+      evidence: [`${rootRouteIndex}:1`],
       suggestedFix: "none",
       confidence: "high"
     }
@@ -1984,11 +2201,11 @@ Invocations: ${TRUTH_CHECK_EXPLICIT_INVOCATIONS}
 
 Truth Check is agent-led:
 
-- inspect .truthmark/config.yml, ${config.docs.routing.rootIndex}, canonical docs, and relevant implementation directly
+- inspect .truthmark/config.yml and configured route files only when they exist; then inspect canonical docs and relevant implementation directly
 - ${EVIDENCE_AUTHORITY_INSTRUCTIONS}
-- inspect the configured root route index at ${config.docs.routing.rootIndex} and relevant child route files under ${config.docs.routing.areaFilesRoot}/
+- inspect the configured root route index at ${config.docs.routing.rootIndex} and relevant child route files under ${config.docs.routing.areaFilesRoot}/ when they exist
 - check that current docs describe current code rather than historical plans
-- check that ${config.docs.routing.rootIndex} routes code surfaces to canonical truth docs
+- check that route files map code surfaces to canonical truth docs when route files exist
 - check for broad, catch-all, index-like, or mixed-owner truth docs and report them as topology issues requiring Truth Structure
 - check that canonical behavior docs keep active Product Decisions and Rationale sections
 - optionally run truthmark check when local tooling is available
@@ -2012,11 +2229,15 @@ var renderMarkdownExample2 = (content) => {
 var TRUTH_DOCUMENT_EXPLICIT_INVOCATIONS = "OpenCode /skill truthmark-document; Codex /truthmark-document or $truthmark-document; Claude Code /truthmark-document; GitHub Copilot /truthmark-document; Gemini CLI /truthmark:document.";
 var renderTruthDocumentReportExample = (config = defaultAgentConfig()) => {
   const truthDocsRoot = resolveTruthDocsRoot(config);
+  const helperScripts = ["validate-write-lease: skipped, no write lease used"];
   return `Truth Document: completed
 
 Implementation reviewed:
 - src/routing/area-resolver.ts
 
+Ownership reviewed:
+- ${config.docs.routing.rootIndex}
+
 Truth docs created:
 - ${truthDocsRoot}/contracts.md
 
@@ -2040,6 +2261,9 @@ ${renderClaimEvidenceCheckedSection([
     }
   ])}
 
+Helper scripts:
+${helperScripts.map((helperScript) => `- ${helperScript}`).join("\n")}
+
 Notes:
 - Documented routing and behavior from route handlers and tests.`;
 };
@@ -2086,7 +2310,7 @@ Invocations: ${TRUTH_DOCUMENT_EXPLICIT_INVOCATIONS}
 Truth Document is manual and implementation-first:
 
 - run only when the user explicitly asks to generate or update truth docs for existing behavior, or when Truth Sync, Truth Check, or Truth Structure reports implemented behavior that lacks canonical truth docs
-- inspect .truthmark/config.yml, ${config.docs.routing.rootIndex}, relevant child route files under ${config.docs.routing.areaFilesRoot}/, existing canonical docs, implementation code, and tests directly
+- inspect .truthmark/config.yml and configured route files only when they exist; then inspect existing canonical docs, implementation code, and tests directly
 - ${EVIDENCE_AUTHORITY_INSTRUCTIONS}
 - document current implemented behavior; do not invent future behavior or planned endpoints
 - may write canonical truth docs and ${config.docs.routing.rootIndex} or relevant child route files only
@@ -2115,6 +2339,12 @@ ${renderTruthDocRestructureGateSection(
 ${ARCHITECTURE_DOC_BOUNDARY_INSTRUCTIONS}
 ${renderHierarchySummary(config)}
 ${DECISION_TRUTH_INSTRUCTIONS}
+Helper status reporting:
+- Validate the report body before adding this validator's own success status; the body may omit \`validate-document-report\` while validation is pending.
+- After \`truthmark validate document-report <report-file> --json\` returns \`data.validation.ok: true\`, append or update \`validate-document-report: ran, passed\` in the final report.
+- If the installed Truthmark CLI is unavailable or the helper is skipped, record \`validate-document-report: skipped, <reason>\` and manually validate the report shape.
+- Record \`validate-write-lease: ran, passed\` only after validating a concrete write lease; otherwise use a truthful skipped status such as \`skipped, no write lease used\`.
+- Helper output is derived evidence and never replaces direct checkout inspection, evidence review, or parent acceptance.
 Parent post-document verification:
 - verify only truth docs and leased truth routing files changed during document work
 - block on functional code, generated host surfaces, or unrelated diffs caused by document work
@@ -2189,9 +2419,9 @@ Purpose:
 - keep the selector thin so agents can avoid loading or acting through heavier workflows prematurely
 
 Read:
-- .truthmark/config.yml
-- ${config.docs.routing.rootIndex}
-- relevant child route files under ${config.docs.routing.areaFilesRoot}/
+- .truthmark/config.yml, only when present
+- ${config.docs.routing.rootIndex}, only when present
+- relevant child route files under ${config.docs.routing.areaFilesRoot}/, only when present
 - relevant truth docs and implementation files needed to preview ownership
 - ${EVIDENCE_AUTHORITY_INSTRUCTIONS}
 
@@ -2216,6 +2446,82 @@ Report completion in this shape:
 ${renderMarkdownExample3(renderTruthPreviewReportExample(config))}`;
 };
 
+// src/agents/truthmark-portal.ts
+var TRUTHMARK_PORTAL_EXPLICIT_INVOCATIONS = "OpenCode /skill truthmark-portal; Codex /truthmark-portal or $truthmark-portal; Claude Code /truthmark-portal; GitHub Copilot /truthmark-portal; Gemini CLI /truthmark:portal.";
+var renderTruthmarkPortalSkillBody = (config = defaultAgentConfig()) => {
+  const workflow = getTruthmarkWorkflow("truthmark-portal");
+  const output = config.truthmarkPortal.output;
+  const template = config.truthmarkPortal.template;
+  return `---
+name: truthmark-portal
+description: ${workflow.description}
+argument-hint: Optional output path, template, or portal generation focus
+user-invocable: true
+truthmark-version: ${TRUTHMARK_VERSION}
+---
+
+# Truthmark Portal
+
+Truthmark Portal is a manual-only presentation workflow. It is never a completion gate, never Truth Sync, and runs only when the user explicitly asks to generate, refresh, or update the committed static HTML Portal.
+
+Invocations: ${TRUTHMARK_PORTAL_EXPLICIT_INVOCATIONS}
+
+Core rules:
+
+- Markdown remains canonical; generated HTML is presentation only.
+- Read Markdown directly from the checkout; the workflow does not require the truthmark CLI or package.
+- truthmark check/index may be used only as optional supporting evidence when available.
+- Default output is docs/truthmark-portal; configured output is ${output}.
+- Configured template is ${template}; use default built-in template instructions when the template is default.
+- The workflow may replace the entire output directory, but writes are limited to the configured Portal output directory only unless the user changes scope.
+- Portal writes are generated non-canonical static files for human browsing.
+- Generate a committed multi-page static HTML site with local CSS, JavaScript, assets, and search metadata under the output directory.
+- Use no remote dependencies by default: no remote scripts, analytics, fonts, CSS, or CDN assets.
+- Include source provenance and the Markdown canonical disclaimer on every page.
+- Store manifest and search data under output/assets only.
+- There is no .truthmark/index.json dependency; do not require or create it as infrastructure.
+- Pictures and screenshots require an explicit user or template request.
+
+Workflow:
+
+1. Confirm the user explicitly requested Portal generation or refresh.
+2. Inspect .truthmark/config.yml and configured route docs only when they exist; read repository instruction files when present, truth docs, architecture docs, standards docs, and the configured Portal template when it is a repo-relative file.
+3. Validate the selected output path is repo-relative, non-empty, inside the repository, and does not overlap canonical docs, source roots, routing files, or instruction targets.
+4. Plan the generated page inventory, diagrams/assets, source docs reviewed, and skipped or ambiguous docs.
+5. Replace or write only under ${output}; do not edit canonical Markdown, routing, source code, or instruction files unless the user explicitly changes scope.
+6. Generate the multi-page static site with local assets/search metadata and visible source provenance.
+7. Validate entry page, links where practical, provenance/disclaimers, local-only assets, and that metadata remains under ${output}/assets.
+${renderHierarchySummary(config)}
+
+Report completion in this shape:
+
+\`\`\`md
+Truthmark Portal: completed
+
+Output path:
+- ${output}
+
+Page count:
+- <count>
+
+Diagrams/assets:
+- <generated diagrams/assets or none>
+
+Source docs reviewed:
+- <source markdown paths>
+
+Skipped/ambiguous docs:
+- <paths and reason, or none>
+
+Validation:
+- <checks performed>
+
+Markdown canonical statement:
+- Markdown remains canonical; generated Portal HTML is non-canonical presentation only.
+\`\`\`
+`;
+};
+
 // src/agents/truth-structure.ts
 var renderMarkdownExample4 = (content) => {
   return ["```md", content, "```"].join("\n");
@@ -2280,9 +2586,9 @@ truthmark-version: ${TRUTHMARK_VERSION}
 Use this skill to design or repair Truthmark area structure.
 Invocations: ${TRUTH_STRUCTURE_EXPLICIT_INVOCATIONS}
 Truth Structure is agent-native:
-- inspect repository layout, current docs, .truthmark/config.yml, ${config.docs.routing.rootIndex}, and relevant code directly
+- inspect repository layout, current docs, Truthmark config and route files when present, and relevant code directly
 - ${EVIDENCE_AUTHORITY_INSTRUCTIONS}
-- inspect the configured root route index at ${config.docs.routing.rootIndex} and relevant child route files under ${config.docs.routing.areaFilesRoot}/
+- inspect the configured root route index at ${config.docs.routing.rootIndex} and relevant child route files under ${config.docs.routing.areaFilesRoot}/ when they exist
 - define areas by product or behavior ownership, not by mechanical directory mirroring
 - create or repair ${config.docs.routing.rootIndex}
 - create starter truth docs when useful and when they belong in the canonical current-truth surface
@@ -2353,7 +2659,7 @@ ${ARCHITECTURE_DOC_BOUNDARY_INSTRUCTIONS}
 Portable fallback:
 - If this skill surface is unavailable, perform the same workflow directly from committed repository files.
 - Do not require the truthmark CLI.
-- Read .truthmark/config.yml, ${config.docs.routing.rootIndex}, relevant child route files under ${config.docs.routing.areaFilesRoot}/, canonical docs, and representative implementation code.
+- Inspect .truthmark/config.yml and configured route files only when they exist; then inspect canonical docs and representative implementation code.
 - Use a subagent only when the host supports that pattern; otherwise perform the topology repair inline.
 ${renderHierarchySummary(config)}
 ${DECISION_TRUTH_INSTRUCTIONS}
@@ -2366,24 +2672,105 @@ var renderBulletSection = (title, items) => {
   return `${title}:
 ${items.map((item) => `- ${item}`).join("\n")}`;
 };
+var findSection = (source, title) => {
+  return source.split("\n\n").find((candidate) => candidate.startsWith(`${title}:
+`));
+};
+var parseBulletLines = (section) => {
+  return section.split("\n").slice(1).map((line) => {
+    const match = line.match(/^-\s+(.*)$/);
+    return match?.[1];
+  }).filter((line) => line !== void 0);
+};
+var parseBulletSection = (source, title) => {
+  const section = findSection(source, title);
+  if (!section) {
+    return [];
+  }
+  return parseBulletLines(section);
+};
+var parseOptionalBulletSection = (source, title) => {
+  const section = findSection(source, title);
+  if (!section) {
+    return void 0;
+  }
+  return parseBulletLines(section);
+};
+var isClaimEvidenceResult = (value) => {
+  return ["supported", "narrowed", "removed", "blocked"].includes(value);
+};
+var hasContent = (value) => value.trim().length > 0;
+var parseEvidenceCheckedSection = (source) => {
+  const section = source.split("\n\n").find((candidate) => candidate.startsWith("Evidence checked:\n"));
+  if (!section) {
+    throw new Error("Evidence checked section is required.");
+  }
+  const lines = section.split("\n").slice(1);
+  const items = [];
+  for (let index = 0; index < lines.length; index += 3) {
+    const claimLine = lines[index];
+    const evidenceLine = lines[index + 1];
+    const resultLine = lines[index + 2];
+    if (!claimLine?.startsWith("- Claim: ") || !evidenceLine?.startsWith("  Evidence: ") || !resultLine?.startsWith("  Result: ")) {
+      throw new Error("Evidence checked entries must include Claim, Evidence, and Result fields.");
+    }
+    const result = resultLine.slice("  Result: ".length);
+    const claim = claimLine.slice("- Claim: ".length).trim();
+    const evidence = evidenceLine.slice("  Evidence: ".length).split(" / ").map((value) => value.trim());
+    if (!hasContent(claim)) {
+      throw new Error("Evidence checked claim is required.");
+    }
+    if (evidence.length === 0 || evidence.some((value) => !hasContent(value))) {
+      throw new Error("Evidence checked evidence is required.");
+    }
+    if (!isClaimEvidenceResult(result)) {
+      throw new Error("Evidence checked result is invalid.");
+    }
+    items.push({
+      claim,
+      evidence,
+      result
+    });
+  }
+  return items;
+};
 var renderTruthSyncCompletedReport = (input) => {
   return [
     "Truth Sync: completed",
     renderBulletSection("Changed code reviewed", input.changedCode),
+    renderBulletSection("Ownership reviewed", input.ownershipReviewed),
     renderBulletSection("Truth docs updated", input.truthDocsUpdated),
     renderClaimEvidenceCheckedSection(input.evidenceChecked),
+    ...input.helperScripts === void 0 ? [] : [renderBulletSection("Helper scripts", input.helperScripts)],
     renderBulletSection("Notes", input.notes)
   ].join("\n\n");
 };
+var parseTruthSyncReport = (source) => {
+  if (!source.startsWith("Truth Sync: completed")) {
+    throw new Error("Only completed Truth Sync reports can be parsed.");
+  }
+  const helperScripts = parseOptionalBulletSection(source, "Helper scripts");
+  return {
+    status: "completed",
+    changedCode: parseBulletSection(source, "Changed code reviewed"),
+    ownershipReviewed: parseBulletSection(source, "Ownership reviewed"),
+    truthDocsUpdated: parseBulletSection(source, "Truth docs updated"),
+    evidenceChecked: parseEvidenceCheckedSection(source),
+    ...helperScripts === void 0 ? {} : { helperScripts },
+    notes: parseBulletSection(source, "Notes")
+  };
+};
 var renderTruthSyncBlockedReport = (input) => {
+  const manualReviewFiles = input.manualReviewFiles.filter((file) => file.trim().length > 0);
+  if (manualReviewFiles.length === 0) {
+    throw new Error("Files requiring manual review must include at least one file.");
+  }
   const sections = [
     "Truth Sync: blocked",
-    renderBulletSection("Reason", [input.reason])
+    renderBulletSection("Reason", [input.reason]),
+    renderBulletSection("Files requiring manual review", manualReviewFiles),
+    renderBulletSection("Next action", [input.nextAction])
   ];
-  if ((input.manualReviewFiles?.length ?? 0) > 0) {
-    sections.push(renderBulletSection("Files requiring manual review", input.manualReviewFiles));
-  }
-  sections.push(renderBulletSection("Next action", [input.nextAction]));
   return [
     ...sections
   ].join("\n\n");
@@ -2397,6 +2784,7 @@ var renderMarkdownExample5 = (content) => {
 var renderTruthSyncSkillBody = (config = defaultAgentConfig(), options = {}) => {
   const truthDocsRoot = resolveTruthDocsRoot(config);
   const workflow = getTruthmarkWorkflow("truthmark-sync");
+  const helperScripts = ["validate-write-lease: skipped, no write lease used"];
   const claudeSubagentMode = options.includeClaudeSubagentMode ? `${renderClaudeSubagentModeSection(
     workflow.subagents ?? [],
     "Parent agent owns Truth Sync acceptance, lease validation, and final report",
@@ -2436,7 +2824,7 @@ Explicit invocation runs immediately. Later functional-code changes reopen the f
 Skip when changes are documentation-only, formatting-only, clearly behavior-preserving renames with no truth impact, when no Truthmark config exists yet, or when there are no functional code changes.
 Parent workflow:
 1. Inspect git status, staged changes, unstaged changes, and untracked files directly.
-2. Read .truthmark/config.yml, the configured root route index at ${config.docs.routing.rootIndex}, relevant child route files under ${config.docs.routing.areaFilesRoot}/, and relevant canonical docs.
+2. Inspect .truthmark/config.yml and configured route files only when they exist; then inspect relevant canonical docs.
 3. Identify functional-code changes and the nearest truth docs or routing repairs.
 4. ${EVIDENCE_AUTHORITY_INSTRUCTIONS}
 5. Code verification is parent-owned: follow repository instructions and task context, and report what ran or why it did not run.
@@ -2470,6 +2858,12 @@ Optional validation tooling:
 - do not require the truthmark binary; direct checkout inspection is the canonical path
 - optional validation must not replace agent judgment about docs and routing
 - update Product Decisions and Rationale when a behavior change comes from a decision change
+Helper status reporting:
+- Validate the report body before adding this validator's own success status; the body may omit \`validate-sync-report\` while validation is pending.
+- After \`truthmark validate sync-report <report-file> --json\` returns \`data.validation.ok: true\`, append or update \`validate-sync-report: ran, passed\` in the final report.
+- If the installed Truthmark CLI is unavailable or the helper is skipped, record \`validate-sync-report: skipped, <reason>\` and manually validate the report shape.
+- Record \`validate-write-lease: ran, passed\` only after validating a concrete write lease; otherwise use a truthful skipped status such as \`skipped, no write lease used\`.
+- Helper output is derived evidence and never replaces direct checkout inspection, evidence review, or parent acceptance.
 ${renderHierarchySummary(config)}
 ${DECISION_TRUTH_INSTRUCTIONS}
 Parent post-sync verification:
@@ -2477,7 +2871,7 @@ Parent post-sync verification:
 - block on any unrelated diff caused by the sync step
 - block if functional code changed during sync
 - for each write lease, validate the worker report against the actual worker diff, allowedWrites, forbiddenWrites, identity fields, filesChanged, offLeaseChanges, blockers, and required report fields before accepting it
-- validate the final report against the structured Truth Sync report contract, including Claim, Evidence, and Result entries under Evidence checked
+- validate the final report against the structured Truth Sync report contract, including Claim, indented Evidence, and Result values supported, narrowed, removed, or blocked under Evidence checked
 - verify the updated docs correspond to the reviewed changed-code surface
 - verify the final report records ownership review, structure requirement, split, restructure, or blocked reason when the ownership gate fired
 - blocked outcomes must preserve the working tree as-is: no rollback, no post-block cleanup edits, and manual-review reporting of any remaining files
@@ -2485,6 +2879,7 @@ Report completion in this shape:
 ${renderMarkdownExample5(
     renderTruthSyncCompletedReport({
       changedCode: ["src/auth/session.ts"],
+      ownershipReviewed: [config.docs.routing.rootIndex],
       truthDocsUpdated: [`${truthDocsRoot}/repository/overview.md`],
       evidenceChecked: [
         {
@@ -2493,6 +2888,7 @@ ${renderMarkdownExample5(
           result: "supported"
         }
       ],
+      helperScripts,
       notes: ["Updated session timeout behavior."]
     })
   )}
@@ -2535,6 +2931,8 @@ var TRUTHMARK_CHECK_SKILL_PATH = ".codex/skills/truthmark-check/SKILL.md";
 var TRUTHMARK_CHECK_SKILL_METADATA_PATH = ".codex/skills/truthmark-check/agents/openai.yaml";
 var TRUTHMARK_PREVIEW_SKILL_PATH = ".codex/skills/truthmark-preview/SKILL.md";
 var TRUTHMARK_PREVIEW_SKILL_METADATA_PATH = ".codex/skills/truthmark-preview/agents/openai.yaml";
+var TRUTHMARK_PORTAL_SKILL_PATH = ".codex/skills/truthmark-portal/SKILL.md";
+var TRUTHMARK_PORTAL_SKILL_METADATA_PATH = ".codex/skills/truthmark-portal/agents/openai.yaml";
 var TRUTHMARK_ROUTE_AUDITOR_AGENT_PATH = ".codex/agents/truth-route-auditor.toml";
 var TRUTHMARK_CLAIM_VERIFIER_AGENT_PATH = ".codex/agents/truth-claim-verifier.toml";
 var TRUTHMARK_DOC_REVIEWER_AGENT_PATH = ".codex/agents/truth-doc-reviewer.toml";
@@ -2553,20 +2951,28 @@ var TRUTHMARK_GEMINI_SYNC_COMMAND_PATH = ".gemini/commands/truthmark/sync.toml";
 var TRUTHMARK_GEMINI_REALIZE_COMMAND_PATH = ".gemini/commands/truthmark/realize.toml";
 var TRUTHMARK_GEMINI_CHECK_COMMAND_PATH = ".gemini/commands/truthmark/check.toml";
 var TRUTHMARK_GEMINI_PREVIEW_COMMAND_PATH = ".gemini/commands/truthmark/preview.toml";
+var TRUTHMARK_GEMINI_PORTAL_COMMAND_PATH = ".gemini/commands/truthmark/portal.toml";
+var TRUTHMARK_GEMINI_ROUTE_AUDITOR_AGENT_PATH = ".gemini/agents/truth-route-auditor.md";
+var TRUTHMARK_GEMINI_CLAIM_VERIFIER_AGENT_PATH = ".gemini/agents/truth-claim-verifier.md";
+var TRUTHMARK_GEMINI_DOC_REVIEWER_AGENT_PATH = ".gemini/agents/truth-doc-reviewer.md";
+var TRUTHMARK_GEMINI_DOC_WRITER_AGENT_PATH = ".gemini/agents/truth-doc-writer.md";
 var TRUTHMARK_COPILOT_STRUCTURE_PROMPT_PATH = ".github/prompts/truthmark-structure.prompt.md";
 var TRUTHMARK_COPILOT_DOCUMENT_PROMPT_PATH = ".github/prompts/truthmark-document.prompt.md";
 var TRUTHMARK_COPILOT_SYNC_PROMPT_PATH = ".github/prompts/truthmark-sync.prompt.md";
 var TRUTHMARK_COPILOT_REALIZE_PROMPT_PATH = ".github/prompts/truthmark-realize.prompt.md";
 var TRUTHMARK_COPILOT_CHECK_PROMPT_PATH = ".github/prompts/truthmark-check.prompt.md";
 var TRUTHMARK_COPILOT_PREVIEW_PROMPT_PATH = ".github/prompts/truthmark-preview.prompt.md";
+var TRUTHMARK_COPILOT_PORTAL_PROMPT_PATH = ".github/prompts/truthmark-portal.prompt.md";
 var TRUTHMARK_COPILOT_ROUTE_AUDITOR_AGENT_PATH = ".github/agents/truth-route-auditor.agent.md";
 var TRUTHMARK_COPILOT_CLAIM_VERIFIER_AGENT_PATH = ".github/agents/truth-claim-verifier.agent.md";
 var TRUTHMARK_COPILOT_DOC_REVIEWER_AGENT_PATH = ".github/agents/truth-doc-reviewer.agent.md";
 var TRUTHMARK_COPILOT_DOC_WRITER_AGENT_PATH = ".github/agents/truth-doc-writer.agent.md";
 var renderGeminiCommand = (description, prompt) => {
+  const promptWithArgs = `${prompt.trimEnd()}
+User focus or arguments: {{args}}`;
   return `description = "${description}"
 prompt = '''
-${prompt}
+${promptWithArgs}
 '''
 `;
 };
@@ -2586,6 +2992,7 @@ var renderTomlStringArray = (values) => {
   return `[${values.map(renderTomlString).join(", ")}]`;
 };
 var TRUTH_REALIZE_EXPLICIT_INVOCATIONS = "OpenCode /skill truthmark-realize; Codex /truthmark-realize or $truthmark-realize; Claude Code /truthmark-realize; GitHub Copilot /truthmark-realize; Gemini CLI /truthmark:realize.";
+var routeFilesHint = (config) => `${config.docs.routing.rootIndex}; ${config.docs.routing.areaFilesRoot}/`;
 var WORKFLOW_PACKAGE_DEFINITIONS = {
   "truthmark-structure": {
     title: "Truthmark Structure",
@@ -2593,8 +3000,8 @@ var WORKFLOW_PACKAGE_DEFINITIONS = {
     invocations: TRUTH_STRUCTURE_EXPLICIT_INVOCATIONS,
     use: () => "Use this skill to design or repair Truthmark area structure.",
     quickRules: (config) => [
-      "Follow docs/ai/repo-rules.md as the repository instruction authority.",
-      `Read .truthmark/config.yml, ${config.docs.routing.rootIndex}, relevant child route files under ${config.docs.routing.areaFilesRoot}/, current docs, and relevant code directly.`,
+      "Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists.",
+      `Inspect .truthmark/config.yml and configured route files (${routeFilesHint(config)}) only when they exist; then inspect current docs and relevant code directly.`,
       "Define areas by product or behavior ownership, not by mechanical directory mirroring.",
       "Do not edit functional code.",
       "Read support/procedure.md before writing route or starter truth-doc changes.",
@@ -2608,8 +3015,8 @@ var WORKFLOW_PACKAGE_DEFINITIONS = {
     invocations: TRUTH_DOCUMENT_EXPLICIT_INVOCATIONS,
     use: () => "Use this skill to document existing implemented behavior when no functional-code changes are required for the task.",
     quickRules: (config) => [
-      "Follow docs/ai/repo-rules.md as the repository instruction authority.",
-      `Read .truthmark/config.yml, ${config.docs.routing.rootIndex}, relevant child route files under ${config.docs.routing.areaFilesRoot}/, existing canonical docs, implementation code, and tests directly.`,
+      "Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists.",
+      `Inspect .truthmark/config.yml and configured route files (${routeFilesHint(config)}) only when they exist; then inspect existing canonical docs, implementation code, and tests directly.`,
       "Document current implemented behavior; do not invent future behavior.",
       "May write canonical truth docs and truth routing files only; must not write functional code.",
       "Read support/procedure.md before editing truth docs.",
@@ -2624,9 +3031,9 @@ var WORKFLOW_PACKAGE_DEFINITIONS = {
     invocations: TRUTH_SYNC_EXPLICIT_INVOCATIONS,
     use: () => "Use this skill automatically before finishing when functional code changed since the last successful Truth Sync. Also run it immediately when the user explicitly invokes Truth Sync.",
     quickRules: (config) => [
-      "Follow docs/ai/repo-rules.md as the repository instruction authority.",
+      "Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists.",
       "Skip docs-only, formatting-only, behavior-preserving renames with no truth impact, missing config, and no-code changes.",
-      `Read .truthmark/config.yml, the configured root route index at ${config.docs.routing.rootIndex}, relevant child route files under ${config.docs.routing.areaFilesRoot}/, and relevant canonical docs.`,
+      `Inspect .truthmark/config.yml and configured route files (${routeFilesHint(config)}) only when they exist; then inspect relevant canonical docs directly.`,
       "direct checkout inspection is the canonical path; do not require the truthmark binary.",
       "May write canonical truth docs and truth routing files only; must not rewrite functional code.",
       "Read support/procedure.md before editing truth docs.",
@@ -2641,8 +3048,8 @@ var WORKFLOW_PACKAGE_DEFINITIONS = {
     invocations: TRUTH_PREVIEW_EXPLICIT_INVOCATIONS,
     use: () => "Use this skill only when the user explicitly asks to preview Truthmark routing or workflow choice before edits.",
     quickRules: (config) => [
-      "Follow docs/ai/repo-rules.md as the repository instruction authority.",
-      `Read .truthmark/config.yml, ${config.docs.routing.rootIndex}, relevant child route files under ${config.docs.routing.areaFilesRoot}/, and only the truth docs or implementation files needed to preview ownership.`,
+      "Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists.",
+      `Inspect .truthmark/config.yml and configured route files (${routeFilesHint(config)}) only when they exist; then inspect only the truth docs or implementation files needed to preview ownership.`,
       "Truth Preview is read-only; this report is intended, not authorized.",
       "must not edit files and must not issue write leases; do not run Truth Sync automatically, replace Truth Check, claim final correctness, or mutate code.",
       "Use optional read-only route-auditor evidence only when it reduces context or clarifies ownership.",
@@ -2656,8 +3063,8 @@ var WORKFLOW_PACKAGE_DEFINITIONS = {
     invocations: TRUTH_REALIZE_EXPLICIT_INVOCATIONS,
     use: () => "Use this skill only when the user explicitly asks to realize truth docs into code.",
     quickRules: (config) => [
-      "Follow docs/ai/repo-rules.md as the repository instruction authority.",
-      `Read the source truth docs, .truthmark/config.yml, ${config.docs.routing.rootIndex}, relevant child route files, tests, and relevant functional code directly.`,
+      "Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists.",
+      `Read the source truth docs, inspect .truthmark/config.yml and configured route files (${routeFilesHint(config)}) only when they exist, then inspect tests and relevant functional code directly.`,
       "Truth docs lead; code follows.",
       "may write functional code only; must not edit truth docs or truth routing while realizing those docs.",
       "Read support/procedure.md before changing code.",
@@ -2670,8 +3077,8 @@ var WORKFLOW_PACKAGE_DEFINITIONS = {
     invocations: TRUTH_CHECK_EXPLICIT_INVOCATIONS,
     use: () => "Use this skill to audit repository truth health.",
     quickRules: (config) => [
-      "Follow docs/ai/repo-rules.md as the repository instruction authority.",
-      `Read .truthmark/config.yml, ${config.docs.routing.rootIndex}, relevant child route files under ${config.docs.routing.areaFilesRoot}/, canonical docs, and relevant implementation directly.`,
+      "Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists.",
+      `Inspect .truthmark/config.yml and configured route files (${routeFilesHint(config)}) only when they exist; then inspect canonical docs and relevant implementation directly.`,
       "Report issues and suggested fixes; do not silently rewrite unrelated files.",
       "Direct checkout inspection is valid even when local tooling is unavailable.",
       "Read support/procedure.md before auditing details.",
@@ -2679,6 +3086,24 @@ var WORKFLOW_PACKAGE_DEFINITIONS = {
       "Read support/report-template.md before the final report."
     ],
     parentRule: "Parent agent owns the final Truth Check report"
+  },
+  "truthmark-portal": {
+    title: "Truthmark Portal",
+    argumentHint: "Optional output path, template, or portal generation focus",
+    invocations: TRUTHMARK_PORTAL_EXPLICIT_INVOCATIONS,
+    use: () => "Use this skill only when the user explicitly asks to generate or refresh the committed static HTML Truthmark Portal.",
+    quickRules: (config) => [
+      "Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists.",
+      "Truthmark Portal is manual-only; never run it as a completion gate and never treat it as Truth Sync.",
+      "Markdown remains canonical; generated HTML is non-canonical presentation only.",
+      "Read Markdown directly; the workflow does not require the truthmark CLI or package.",
+      "Generate committed, generated non-canonical static files for humans.",
+      `Write only under configured Portal output ${config.truthmarkPortal.output}; default output is docs/truthmark-portal.`,
+      `Use configured Portal template ${config.truthmarkPortal.template}; no .truthmark/index.json dependency.`,
+      "Use no remote dependencies by default and include source provenance on every page.",
+      "Read support/procedure.md before generating Portal output.",
+      "Read support/report-template.md before the final report."
+    ]
   }
 };
 var stripWorkflowSkillFrontmatter = (body) => {
@@ -2707,6 +3132,56 @@ Generated by Truthmark ${TRUTHMARK_VERSION}. Rerun truthmark init after upgrades
 ${body}
 `;
 };
+var renderHelperManifest = (helpers) => {
+  const manifest = {
+    helpers: Object.fromEntries(
+      helpers.map((helper) => [
+        helper.id,
+        {
+          optional: helper.optional,
+          runner: helper.runner,
+          command: helper.command,
+          inputs: helper.inputs,
+          output: helper.output,
+          writes: helper.writes,
+          ...helper.allowedWrites === void 0 ? {} : { allowedWrites: helper.allowedWrites },
+          fallback: helper.fallback
+        }
+      ])
+    )
+  };
+  return [
+    `# Generated by Truthmark ${TRUTHMARK_VERSION}. Rerun truthmark init after upgrades.`,
+    stringify2(manifest, { lineWidth: 0 })
+  ].join("\n");
+};
+var renderHelperPolicySupport = (helpers) => {
+  const reportHelperId = helpers.find((helper) => helper.id.endsWith("-report"))?.id ?? helpers[0]?.id;
+  const helperLines = helpers.map(
+    (helper) => `- ${helper.id}: optional ${helper.runner}; manual fallback: ${helper.fallback}`
+  ).join("\n");
+  return renderSkillSupportFile(
+    "Optional Helper CLI Policy",
+    `Optional helper CLI commands may collect deterministic checkout facts or validate artifacts. If the Truthmark CLI is unavailable or too old for a declared helper, continue manually using this procedure and report which helper was skipped. Helper output is derived evidence; it does not override direct checkout inspection, workflow write boundaries, or parent acceptance.
+
+Runner detection:
+- Check the declared Truthmark CLI runner before invoking a helper.
+- Invoke helpers through the installed \`truthmark validate ... --json\` CLI command using argv-style arguments from helper-manifest.yml.
+- If unavailable or version-mismatched, treat the helper as skipped and use the manual fallback.
+- Do not fail the workflow solely because a helper cannot run.
+
+Available helpers:
+${helperLines}
+
+Final reports should include helper status when helpers are declared for this workflow:
+
+\`\`\`md
+Helper scripts:
+- ${reportHelperId}: ran, passed
+- validate-write-lease: skipped, no write lease used
+\`\`\``
+  );
+};
 var renderStandaloneWorkflowSkillBody = (workflowId, config) => {
   switch (workflowId) {
     case "truthmark-structure":
@@ -2721,12 +3196,15 @@ var renderStandaloneWorkflowSkillBody = (workflowId, config) => {
       return renderTruthmarkRealizeSkillBody(config);
     case "truthmark-check":
       return renderTruthCheckSkillBody(config);
+    case "truthmark-portal":
+      return renderTruthmarkPortalSkillBody(config);
   }
 };
-var renderWorkflowEntrypoint = (workflowId, config, supportFiles) => {
+var renderWorkflowEntrypoint = (workflowId, config, supportFiles, host) => {
   const workflow = getTruthmarkWorkflow(workflowId);
   const definition = WORKFLOW_PACKAGE_DEFINITIONS[workflowId];
   const supportFileList = supportFiles.map((supportFile) => `- ${supportFile}`).join("\n");
+  const hostUsage = host === "github-copilot" ? "Use as a Copilot agent skill. Prompt files remain available under `.github/prompts/` for command-style invocation in supported Copilot IDEs." : host === "gemini-cli" ? "Use as a Gemini CLI Agent Skill; commands remain available under `/truthmark:*` for command-first invocation." : void 0;
   return `---
 name: ${workflowId}
 description: ${workflow.description}
@@ -2738,6 +3216,9 @@ truthmark-version: ${TRUTHMARK_VERSION}
 # ${definition.title}
 
 ${definition.use(config)}
+${hostUsage === void 0 ? "" : `
+${hostUsage}
+`}
 
 Invocations: ${definition.invocations}
 
@@ -2778,6 +3259,18 @@ var renderWorkflowSubagentSupport = (workflowId, host) => {
         definition.parentRule,
         writeAgents
       );
+    case "github-copilot":
+      return renderCopilotCustomAgentModeSection(
+        readAgents,
+        definition.parentRule,
+        writeAgents
+      );
+    case "gemini-cli":
+      return renderGeminiSubagentModeSection(
+        readAgents,
+        definition.parentRule,
+        writeAgents
+      );
   }
 };
 var renderTruthmarkSkillPackage = ({
@@ -2792,16 +3285,18 @@ var renderTruthmarkSkillPackage = ({
     renderStandaloneWorkflowSkillBody(workflowId, config)
   );
   const subagents = renderWorkflowSubagentSupport(workflowId, host);
+  const helpers = getTruthmarkWorkflow(workflowId).helpers ?? [];
   const supportFiles = [
     "support/procedure.md",
     "support/report-template.md",
-    ...subagents === void 0 ? [] : ["support/subagents-and-leases.md"]
+    ...subagents === void 0 ? [] : ["support/subagents-and-leases.md"],
+    ...helpers.length === 0 ? [] : ["helper-manifest.yml", "support/helper-policy.md"]
   ];
   const definition = WORKFLOW_PACKAGE_DEFINITIONS[workflowId];
   const files = [
     {
       path: skillPath,
-      content: renderWorkflowEntrypoint(workflowId, config, supportFiles)
+      content: renderWorkflowEntrypoint(workflowId, config, supportFiles, host)
     },
     {
       path: `${supportDirectory}/procedure.md`,
@@ -2827,10 +3322,22 @@ var renderTruthmarkSkillPackage = ({
       )
     });
   }
+  if (helpers.length > 0) {
+    files.push(
+      {
+        path: `${skillDirectory}/helper-manifest.yml`,
+        content: renderHelperManifest(helpers)
+      },
+      {
+        path: `${supportDirectory}/helper-policy.md`,
+        content: renderHelperPolicySupport(helpers)
+      }
+    );
+  }
   return files;
 };
-var normalizeOpenCodePermissionPath = (path12) => {
-  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) => {
@@ -2869,7 +3376,7 @@ var TRUTHMARK_SUBAGENT_PROFILES = {
     nicknameCandidates: ["Route Audit", "Route Trace", "Route Check"],
     instructions: `Stay read-only.
 Audit one bounded Truthmark route, area, or doc shard assigned by the parent.
-Read .truthmark/config.yml, the root route index, relevant child route files, mapped truth docs, and relevant implementation files directly.
+Inspect .truthmark/config.yml and route files only when they exist; then inspect mapped truth docs and relevant implementation files directly.
 Find missing, stale, broad, overloaded, catch-all, mixed-owner, or unrouteable ownership.
 Do not edit files, stage changes, or propose broad rewrites.
 Return JSON only with keys: scope, filesReviewed, findings, evidence, confidence, recommendedWorkflow, notes.
@@ -2982,6 +3489,45 @@ tools: [read, search, edit]
 
 # Generated by Truthmark ${TRUTHMARK_VERSION}. Rerun truthmark init after upgrades.
 
+${instructions}
+`;
+};
+var renderGeminiReadOnlyAgent = ({
+  copilotName,
+  description,
+  instructions
+}) => {
+  const agentInstructions = renderReadOnlySubagentInstructions(instructions);
+  return `---
+name: ${copilotName}
+description: ${description}
+kind: local
+tools: [read_file, grep_search]
+---
+
+# Generated by Truthmark ${TRUTHMARK_VERSION}. Rerun truthmark init after upgrades.
+
+Manual invocation: @${copilotName}
+
+${agentInstructions}
+`;
+};
+var renderGeminiWriteAgent = ({
+  copilotName,
+  description,
+  instructions
+}) => {
+  return `---
+name: ${copilotName}
+description: ${description}
+kind: local
+tools: [read_file, grep_search, write_file]
+---
+
+# Generated by Truthmark ${TRUTHMARK_VERSION}. Rerun truthmark init after upgrades.
+
+Manual invocation: @${copilotName} with an explicit parent write lease.
+
 ${instructions}
 `;
 };
@@ -3084,6 +3630,26 @@ var renderTruthmarkCopilotDocWriterAgent = () => {
     TRUTHMARK_WRITE_SUBAGENT_PROFILES.truth_doc_writer
   );
 };
+var renderTruthmarkGeminiRouteAuditorAgent = () => {
+  return renderGeminiReadOnlyAgent(
+    TRUTHMARK_SUBAGENT_PROFILES.truth_route_auditor
+  );
+};
+var renderTruthmarkGeminiClaimVerifierAgent = () => {
+  return renderGeminiReadOnlyAgent(
+    TRUTHMARK_SUBAGENT_PROFILES.truth_claim_verifier
+  );
+};
+var renderTruthmarkGeminiDocReviewerAgent = () => {
+  return renderGeminiReadOnlyAgent(
+    TRUTHMARK_SUBAGENT_PROFILES.truth_doc_reviewer
+  );
+};
+var renderTruthmarkGeminiDocWriterAgent = () => {
+  return renderGeminiWriteAgent(
+    TRUTHMARK_WRITE_SUBAGENT_PROFILES.truth_doc_writer
+  );
+};
 var renderTruthmarkClaudeRouteAuditorAgent = () => {
   return renderClaudeReadOnlyAgent(
     TRUTHMARK_SUBAGENT_PROFILES.truth_route_auditor
@@ -3273,8 +3839,8 @@ Truth Realize is doc-first:
 
 Workflow:
 
-1. Read the updated truth docs named by the user, or infer the relevant docs from ${config.docs.routing.rootIndex}.
-2. Read .truthmark/config.yml, ${config.docs.routing.rootIndex}, relevant child route files, tests, and the relevant functional code.
+1. Read the updated truth docs named by the user, or infer the relevant docs from configured route files when present.
+2. Inspect .truthmark/config.yml and configured route files (${routeFilesHint(config)}) only when they exist; then read tests and the relevant functional code.
 3. ${EVIDENCE_AUTHORITY_INSTRUCTIONS}
 ${renderTruthDocOwnershipGateSection(
     "source truth docs before writing code",
@@ -3348,6 +3914,21 @@ var renderTruthmarkCheckSkillMetadata = () => {
 policy:
   allow_implicit_invocation: ${workflow.allowImplicitInvocation}
 
+truthmark:
+  version: "${TRUTHMARK_VERSION}"
+  refresh_command: "truthmark init"
+`;
+};
+var renderTruthmarkPortalSkillMetadata = () => {
+  const workflow = getTruthmarkWorkflow("truthmark-portal");
+  return `interface:
+  display_name: "${workflow.displayName}"
+  short_description: "${workflow.shortDescription}"
+  default_prompt: "${workflow.defaultPrompt}"
+
+policy:
+  allow_implicit_invocation: ${workflow.allowImplicitInvocation}
+
 truthmark:
   version: "${TRUTHMARK_VERSION}"
   refresh_command: "truthmark init"
@@ -3395,6 +3976,13 @@ var renderTruthmarkGeminiPreviewCommand = (config = defaultAgentConfig()) => {
     renderTruthPreviewSkillBody(config)
   );
 };
+var renderTruthmarkGeminiPortalCommand = (config = defaultAgentConfig()) => {
+  const workflow = getTruthmarkWorkflow("truthmark-portal");
+  return renderGeminiCommand(
+    workflow.description,
+    renderTruthmarkPortalSkillBody(config)
+  );
+};
 var renderTruthmarkCopilotStructurePrompt = (config = defaultAgentConfig()) => {
   const workflow = getTruthmarkWorkflow("truthmark-structure");
   return renderCopilotPromptFile(
@@ -3445,6 +4033,13 @@ var renderTruthmarkCopilotPreviewPrompt = (config = defaultAgentConfig()) => {
     renderTruthPreviewSkillBody(config)
   );
 };
+var renderTruthmarkCopilotPortalPrompt = (config = defaultAgentConfig()) => {
+  const workflow = getTruthmarkWorkflow("truthmark-portal");
+  return renderCopilotPromptFile(
+    workflow.description,
+    renderTruthmarkPortalSkillBody(config)
+  );
+};
 
 // src/templates/generated-surfaces.ts
 var codexFiles = (config) => {
@@ -3526,10 +4121,24 @@ var codexFiles = (config) => {
       content: renderTruthmarkDocWriterAgent()
     }
   ];
+  if (config.truthmarkPortal.enabled) {
+    files.push(
+      ...renderTruthmarkSkillPackage({
+        skillPath: TRUTHMARK_PORTAL_SKILL_PATH,
+        workflowId: "truthmark-portal",
+        host: "codex",
+        config
+      }),
+      {
+        path: TRUTHMARK_PORTAL_SKILL_METADATA_PATH,
+        content: renderTruthmarkPortalSkillMetadata()
+      }
+    );
+  }
   return files;
 };
 var opencodeFiles = (config) => {
-  return [
+  const files = [
     ...renderTruthmarkSkillPackage({
       skillPath: ".opencode/skills/truthmark-structure/SKILL.md",
       workflowId: "truthmark-structure",
@@ -3583,9 +4192,20 @@ var opencodeFiles = (config) => {
       content: renderTruthmarkOpenCodeDocWriterAgent(config)
     }
   ];
+  if (config.truthmarkPortal.enabled) {
+    files.push(
+      ...renderTruthmarkSkillPackage({
+        skillPath: ".opencode/skills/truthmark-portal/SKILL.md",
+        workflowId: "truthmark-portal",
+        host: "opencode",
+        config
+      })
+    );
+  }
+  return files;
 };
 var claudeFiles = (config, block) => {
-  return [
+  const files = [
     ...instructionBlockFiles(["CLAUDE.md"], block),
     ...renderTruthmarkSkillPackage({
       skillPath: ".claude/skills/truthmark-structure/SKILL.md",
@@ -3640,10 +4260,57 @@ var claudeFiles = (config, block) => {
       content: renderTruthmarkClaudeDocWriterAgent()
     }
   ];
+  if (config.truthmarkPortal.enabled) {
+    files.push(
+      ...renderTruthmarkSkillPackage({
+        skillPath: ".claude/skills/truthmark-portal/SKILL.md",
+        workflowId: "truthmark-portal",
+        host: "claude-code",
+        config
+      })
+    );
+  }
+  return files;
 };
 var copilotFiles = (config, block) => {
   const files = [
     ...instructionBlockFiles([".github/copilot-instructions.md"], block),
+    ...renderTruthmarkSkillPackage({
+      skillPath: ".github/skills/truthmark-structure/SKILL.md",
+      workflowId: "truthmark-structure",
+      host: "github-copilot",
+      config
+    }),
+    ...renderTruthmarkSkillPackage({
+      skillPath: ".github/skills/truthmark-document/SKILL.md",
+      workflowId: "truthmark-document",
+      host: "github-copilot",
+      config
+    }),
+    ...renderTruthmarkSkillPackage({
+      skillPath: ".github/skills/truthmark-sync/SKILL.md",
+      workflowId: "truthmark-sync",
+      host: "github-copilot",
+      config
+    }),
+    ...renderTruthmarkSkillPackage({
+      skillPath: ".github/skills/truthmark-preview/SKILL.md",
+      workflowId: "truthmark-preview",
+      host: "github-copilot",
+      config
+    }),
+    ...renderTruthmarkSkillPackage({
+      skillPath: ".github/skills/truthmark-check/SKILL.md",
+      workflowId: "truthmark-check",
+      host: "github-copilot",
+      config
+    }),
+    ...renderTruthmarkSkillPackage({
+      skillPath: ".github/skills/truthmark-realize/SKILL.md",
+      workflowId: "truthmark-realize",
+      host: "github-copilot",
+      config
+    }),
     {
       path: TRUTHMARK_COPILOT_STRUCTURE_PROMPT_PATH,
       content: renderTruthmarkCopilotStructurePrompt(config)
@@ -3685,11 +4352,121 @@ var copilotFiles = (config, block) => {
       content: renderTruthmarkCopilotDocWriterAgent()
     }
   ];
+  if (config.truthmarkPortal.enabled) {
+    files.push(
+      ...renderTruthmarkSkillPackage({
+        skillPath: ".github/skills/truthmark-portal/SKILL.md",
+        workflowId: "truthmark-portal",
+        host: "github-copilot",
+        config
+      }),
+      {
+        path: TRUTHMARK_COPILOT_PORTAL_PROMPT_PATH,
+        content: renderTruthmarkCopilotPortalPrompt(config)
+      }
+    );
+  }
+  return files;
+};
+var geminiFiles = (config, block) => {
+  const files = [
+    ...instructionBlockFiles(["GEMINI.md"], block),
+    ...renderTruthmarkSkillPackage({
+      skillPath: ".gemini/skills/truthmark-structure/SKILL.md",
+      workflowId: "truthmark-structure",
+      host: "gemini-cli",
+      config
+    }),
+    ...renderTruthmarkSkillPackage({
+      skillPath: ".gemini/skills/truthmark-document/SKILL.md",
+      workflowId: "truthmark-document",
+      host: "gemini-cli",
+      config
+    }),
+    ...renderTruthmarkSkillPackage({
+      skillPath: ".gemini/skills/truthmark-sync/SKILL.md",
+      workflowId: "truthmark-sync",
+      host: "gemini-cli",
+      config
+    }),
+    ...renderTruthmarkSkillPackage({
+      skillPath: ".gemini/skills/truthmark-preview/SKILL.md",
+      workflowId: "truthmark-preview",
+      host: "gemini-cli",
+      config
+    }),
+    ...renderTruthmarkSkillPackage({
+      skillPath: ".gemini/skills/truthmark-check/SKILL.md",
+      workflowId: "truthmark-check",
+      host: "gemini-cli",
+      config
+    }),
+    ...renderTruthmarkSkillPackage({
+      skillPath: ".gemini/skills/truthmark-realize/SKILL.md",
+      workflowId: "truthmark-realize",
+      host: "gemini-cli",
+      config
+    }),
+    {
+      path: TRUTHMARK_GEMINI_STRUCTURE_COMMAND_PATH,
+      content: renderTruthmarkGeminiStructureCommand(config)
+    },
+    {
+      path: TRUTHMARK_GEMINI_DOCUMENT_COMMAND_PATH,
+      content: renderTruthmarkGeminiDocumentCommand(config)
+    },
+    {
+      path: TRUTHMARK_GEMINI_SYNC_COMMAND_PATH,
+      content: renderTruthmarkGeminiSyncCommand(config)
+    },
+    {
+      path: TRUTHMARK_GEMINI_PREVIEW_COMMAND_PATH,
+      content: renderTruthmarkGeminiPreviewCommand(config)
+    },
+    {
+      path: TRUTHMARK_GEMINI_CHECK_COMMAND_PATH,
+      content: renderTruthmarkGeminiCheckCommand(config)
+    },
+    {
+      path: TRUTHMARK_GEMINI_REALIZE_COMMAND_PATH,
+      content: renderTruthmarkGeminiRealizeCommand(config)
+    },
+    {
+      path: TRUTHMARK_GEMINI_ROUTE_AUDITOR_AGENT_PATH,
+      content: renderTruthmarkGeminiRouteAuditorAgent()
+    },
+    {
+      path: TRUTHMARK_GEMINI_CLAIM_VERIFIER_AGENT_PATH,
+      content: renderTruthmarkGeminiClaimVerifierAgent()
+    },
+    {
+      path: TRUTHMARK_GEMINI_DOC_REVIEWER_AGENT_PATH,
+      content: renderTruthmarkGeminiDocReviewerAgent()
+    },
+    {
+      path: TRUTHMARK_GEMINI_DOC_WRITER_AGENT_PATH,
+      content: renderTruthmarkGeminiDocWriterAgent()
+    }
+  ];
+  if (config.truthmarkPortal.enabled) {
+    files.push(
+      ...renderTruthmarkSkillPackage({
+        skillPath: ".gemini/skills/truthmark-portal/SKILL.md",
+        workflowId: "truthmark-portal",
+        host: "gemini-cli",
+        config
+      }),
+      {
+        path: TRUTHMARK_GEMINI_PORTAL_COMMAND_PATH,
+        content: renderTruthmarkGeminiPortalCommand(config)
+      }
+    );
+  }
   return files;
 };
 var instructionBlockFiles = (paths, block) => {
-  return paths.map((path12) => ({
-    path: path12,
+  return paths.map((path13) => ({
+    path: path13,
     content: block,
     managedBlock: true
   }));
@@ -3705,33 +4482,7 @@ var filesForPlatform = (platform, config, block) => {
     case "github-copilot":
       return copilotFiles(config, block);
     case "gemini-cli":
-      return [
-        ...instructionBlockFiles(["GEMINI.md"], block),
-        {
-          path: TRUTHMARK_GEMINI_STRUCTURE_COMMAND_PATH,
-          content: renderTruthmarkGeminiStructureCommand(config)
-        },
-        {
-          path: TRUTHMARK_GEMINI_DOCUMENT_COMMAND_PATH,
-          content: renderTruthmarkGeminiDocumentCommand(config)
-        },
-        {
-          path: TRUTHMARK_GEMINI_SYNC_COMMAND_PATH,
-          content: renderTruthmarkGeminiSyncCommand(config)
-        },
-        {
-          path: TRUTHMARK_GEMINI_PREVIEW_COMMAND_PATH,
-          content: renderTruthmarkGeminiPreviewCommand(config)
-        },
-        {
-          path: TRUTHMARK_GEMINI_CHECK_COMMAND_PATH,
-          content: renderTruthmarkGeminiCheckCommand(config)
-        },
-        {
-          path: TRUTHMARK_GEMINI_REALIZE_COMMAND_PATH,
-          content: renderTruthmarkGeminiRealizeCommand(config)
-        }
-      ];
+      return geminiFiles(config, block);
   }
 };
 var renderGeneratedSurfaces = (config, block = renderAgentsBlock(config)) => {
@@ -3790,16 +4541,39 @@ var removeTrailingManagedChunk = (preservedLines) => {
     preservedLines.splice(startIndex);
   }
 };
+var LEGACY_REPO_RULES_PATH = ["docs", "ai", `repo-${"rules.md"}`].join("/");
+var LEGACY_AGENT_ONBOARDING_PATH = ["docs", "ai", `agent-${"onboarding.md"}`].join(
+  "/"
+);
+var LEGACY_PRIMARY_REPO_INSTRUCTION_PHRASE = [
+  "primary repository",
+  "instruction source"
+].join(" ");
 var normalizeLegacyInstructionPreamble = (content) => {
   return content.replaceAll(
-    "Use that file as the primary repository instruction source for Codex.",
-    "Use that file as the primary repository instruction source for this agent."
+    `Follow \`${LEGACY_REPO_RULES_PATH}\`.`,
+    "Follow repository instruction files that are present in this checkout; do not assume optional policy docs exist."
+  ).replaceAll(
+    `Follow \`${LEGACY_REPO_RULES_PATH}\` as the ${LEGACY_PRIMARY_REPO_INSTRUCTION_PHRASE}.`,
+    "Follow repository instruction files that are present in this checkout; do not assume optional policy docs exist."
+  ).replaceAll(
+    `Use that file as the ${LEGACY_PRIMARY_REPO_INSTRUCTION_PHRASE} for Codex.`,
+    "Use explicitly configured repository policy docs only when they exist in this checkout."
+  ).replaceAll(
+    `Use that file as the ${LEGACY_PRIMARY_REPO_INSTRUCTION_PHRASE} for this agent.`,
+    "Use explicitly configured repository policy docs only when they exist in this checkout."
   ).replaceAll("Codex-specific:", "Agent-specific:").replaceAll(
     "- Read `docs/README.md` for the canonical docs map.",
-    "- Read `docs/README.md` only when choosing or updating canonical docs."
+    "- Read the configured Truthmark routing files when choosing or updating canonical docs."
+  ).replaceAll(
+    "- Read `docs/README.md` only when choosing or updating canonical docs.",
+    "- Read the configured Truthmark routing files when choosing or updating canonical docs."
   ).replaceAll(
-    "- Use `docs/ai/agent-onboarding.md` for quick task routing.",
-    "- Use `docs/ai/agent-onboarding.md` only when task routing is unclear or cross-area."
+    `- Use \`${LEGACY_AGENT_ONBOARDING_PATH}\` for quick task routing.`,
+    "- Use repository onboarding or docs-map files only when present and needed for unclear or cross-area routing."
+  ).replaceAll(
+    `- Use \`${LEGACY_AGENT_ONBOARDING_PATH}\` only when task routing is unclear or cross-area.`,
+    "- Use repository onboarding or docs-map files only when present and needed for unclear or cross-area routing."
   );
 };
 var upsertManagedBlock = (existingContent, block) => {
@@ -3860,48 +4634,36 @@ var upsertManagedBlock = (existingContent, block) => {
 
 ${block}`;
 };
-var writeManagedAgentsFile = async (rootDir, path12 = "AGENTS.md", block) => {
+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") {
     return "truth-sync";
   }
-  if (filePath === "CLAUDE.md" || filePath === "GEMINI.md" || filePath === ".github/copilot-instructions.md" || filePath.startsWith(".github/prompts/truthmark-") || filePath.startsWith(".github/agents/truth-") || filePath.startsWith(".claude/agents/truth-") || filePath.startsWith(".claude/skills/truthmark-") || filePath.startsWith(".opencode/skills/truthmark-") || filePath.startsWith(".opencode/agents/") || filePath.startsWith(".codex/agents/")) {
-    return "truth-sync";
-  }
-  if (filePath.startsWith(".codex/skills/truthmark-structure/")) {
-    return "truth-sync";
-  }
-  if (filePath.startsWith(".codex/skills/truthmark-document/")) {
-    return "truth-sync";
+  if (filePath === ".github/prompts/truthmark-realize.prompt.md" || filePath.startsWith(".github/skills/truthmark-realize/") || filePath.startsWith(".claude/skills/truthmark-realize/") || filePath.startsWith(".opencode/skills/truthmark-realize/") || filePath.startsWith(".codex/skills/truthmark-realize/") || filePath.startsWith(".gemini/skills/truthmark-realize/")) {
+    return "realization";
   }
-  if (filePath.startsWith(".codex/skills/truthmark-sync/")) {
+  if (filePath === "CLAUDE.md" || filePath === "GEMINI.md" || filePath === ".github/copilot-instructions.md" || filePath.startsWith(".github/prompts/truthmark-") || filePath.startsWith(".github/agents/truth-") || filePath.startsWith(".github/skills/truthmark-") || filePath.startsWith(".claude/agents/truth-") || filePath.startsWith(".claude/skills/truthmark-") || filePath.startsWith(".opencode/skills/truthmark-") || filePath.startsWith(".opencode/agents/") || filePath.startsWith(".codex/agents/") || filePath.startsWith(".gemini/agents/truth-") || filePath.startsWith(".gemini/skills/truthmark-")) {
     return "truth-sync";
   }
-  if (filePath.startsWith(".codex/skills/truthmark-preview/")) {
+  if (filePath.startsWith(".codex/skills/truthmark-")) {
     return "truth-sync";
   }
-  if (filePath.startsWith(".codex/skills/truthmark-realize/")) {
-    return "realization";
-  }
   if (filePath.startsWith(".gemini/commands/truthmark/realize")) {
     return "realization";
   }
   if (filePath.startsWith(".gemini/commands/truthmark/")) {
     return "truth-sync";
   }
-  if (filePath.startsWith(".codex/skills/truthmark-check/")) {
-    return "truth-sync";
-  }
   if (filePath === config.docs.routing.rootIndex) {
     return "authority";
   }
@@ -4258,7 +5020,7 @@ var checkFrontmatter = async (rootDir, config, markdownPaths, truthDocumentEntri
 
 // src/checks/links.ts
 import fs11 from "fs/promises";
-import path4 from "path";
+import path5 from "path";
 var pathExists2 = async (absolutePath) => {
   try {
     await fs11.stat(absolutePath);
@@ -4292,7 +5054,7 @@ var checkLinks = async (rootDir, markdownPaths) => {
       if (targetPath.length === 0) {
         continue;
       }
-      const absoluteTarget = path4.resolve(path4.dirname(absolutePath), targetPath);
+      const absoluteTarget = path5.resolve(path5.dirname(absolutePath), targetPath);
       const relativeTarget = toRepoRelativePath(rootDir, absoluteTarget);
       try {
         await assertRepoContainment(rootDir, absoluteTarget);
@@ -5164,16 +5926,16 @@ var checkGeneratedSurfaces = async (rootDir, config) => {
 };
 
 // src/impact/build.ts
-import path9 from "path";
+import path10 from "path";
 import micromatch7 from "micromatch";
 
 // src/repo-index/build.ts
 import fs18 from "fs/promises";
-import path7 from "path";
+import path8 from "path";
 
 // src/repo-index/file-tree.ts
 import fs16 from "fs/promises";
-import path5 from "path";
+import path6 from "path";
 import { execa as execa2 } from "execa";
 import fg6 from "fast-glob";
 import matter2 from "gray-matter";
@@ -5193,10 +5955,10 @@ var languageByExtension = /* @__PURE__ */ new Map([
 ]);
 var sourceExtensions = /* @__PURE__ */ new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
 var isJavaScriptLikePath = (filePath) => {
-  return sourceExtensions.has(path5.posix.extname(filePath));
+  return sourceExtensions.has(path6.posix.extname(filePath));
 };
 var isTestPath = (filePath) => {
-  return filePath.startsWith("tests/") || filePath.includes("/__tests__/") || /(?:^|[./-])(test|spec)\.[cm]?[jt]sx?$/u.test(path5.posix.basename(filePath));
+  return filePath.startsWith("tests/") || filePath.includes("/__tests__/") || /(?:^|[./-])(test|spec)\.[cm]?[jt]sx?$/u.test(path6.posix.basename(filePath));
 };
 var fileKind = (filePath, ignore) => {
   const classification = classifyPath(filePath, ignore);
@@ -5222,7 +5984,7 @@ var fileKind = (filePath, ignore) => {
 };
 var targetHintsForTest = (filePath) => {
   const hints = /* @__PURE__ */ new Set();
-  const basename = path5.posix.basename(filePath).replace(/\.(test|spec)\.[cm]?[jt]sx?$/u, "");
+  const basename = path6.posix.basename(filePath).replace(/\.(test|spec)\.[cm]?[jt]sx?$/u, "");
   if (basename.length > 0) {
     hints.add(basename);
   }
@@ -5268,7 +6030,19 @@ var discoverRepoFiles = async (rootDir, ignore) => {
   const docs = [];
   const tests = [];
   for (const filePath of discoveredFiles.filter((entry) => !isIgnoredPath(entry, ignore)).sort()) {
-    const extension = path5.posix.extname(filePath);
+    let stat;
+    try {
+      stat = await fs16.stat(path6.join(rootDir, filePath));
+    } catch (error) {
+      if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+        continue;
+      }
+      throw error;
+    }
+    if (!stat.isFile()) {
+      continue;
+    }
+    const extension = path6.posix.extname(filePath);
     const kind = fileKind(filePath, ignore);
     files.push({
       path: filePath,
@@ -5282,7 +6056,7 @@ var discoverRepoFiles = async (rootDir, ignore) => {
       });
     }
     if (kind === "doc") {
-      const source = await fs16.readFile(path5.join(rootDir, filePath), "utf8");
+      const source = await fs16.readFile(path6.join(rootDir, filePath), "utf8");
       const parsed = matter2(source);
       const markdown = parseMarkdownDocument(parsed.content);
       const title = markdown.headings.find((heading) => heading.depth === 1)?.text ?? null;
@@ -5305,7 +6079,7 @@ var discoverRepoFiles = async (rootDir, ignore) => {
 
 // src/repo-index/package-metadata.ts
 import fs17 from "fs/promises";
-import path6 from "path";
+import path7 from "path";
 import fg7 from "fast-glob";
 var packageManagerFor = async (rootDir, packageDir) => {
   const lockfiles = [
@@ -5317,7 +6091,7 @@ var packageManagerFor = async (rootDir, packageDir) => {
   ];
   for (const [lockfile, manager] of lockfiles) {
     try {
-      await fs17.access(path6.join(rootDir, packageDir, lockfile));
+      await fs17.access(path7.join(rootDir, packageDir, lockfile));
       return manager;
     } catch {
       continue;
@@ -5334,8 +6108,8 @@ var discoverPackageMetadata = async (rootDir) => {
   });
   const packages = [];
   for (const packageFile of packageFiles.sort()) {
-    const packageDir = path6.posix.dirname(packageFile) === "." ? "" : path6.posix.dirname(packageFile);
-    const raw = JSON.parse(await fs17.readFile(path6.join(rootDir, packageFile), "utf8"));
+    const packageDir = path7.posix.dirname(packageFile) === "." ? "" : path7.posix.dirname(packageFile);
+    const raw = JSON.parse(await fs17.readFile(path7.join(rootDir, packageFile), "utf8"));
     const scripts = raw.scripts && typeof raw.scripts === "object" ? Object.keys(raw.scripts).sort() : [];
     packages.push({
       path: packageFile,
@@ -5394,16 +6168,16 @@ var declarationName = (node) => {
   }
   return node.name.text;
 };
-var addExport = (exports, publicSymbols, path12, name, kind) => {
+var addExport = (exports, publicSymbols, path13, name, kind) => {
   if (!name) {
     return;
   }
-  const entry = { path: path12, name, kind };
+  const entry = { path: path13, name, kind };
   exports.push(entry);
   publicSymbols.push(entry);
 };
-var analyzeTypeScriptSource = (path12, source) => {
-  const sourceFile = ts.createSourceFile(path12, source, ts.ScriptTarget.Latest, true);
+var analyzeTypeScriptSource = (path13, source) => {
+  const sourceFile = ts.createSourceFile(path13, source, ts.ScriptTarget.Latest, true);
   const imports = [];
   const exports = [];
   const publicSymbols = [];
@@ -5423,7 +6197,7 @@ var analyzeTypeScriptSource = (path12, source) => {
         }
       }
       imports.push({
-        from: path12,
+        from: path13,
         specifier: statement.moduleSpecifier.text,
         imported: sortStrings(imported)
       });
@@ -5432,34 +6206,34 @@ var analyzeTypeScriptSource = (path12, source) => {
     if (ts.isExportDeclaration(statement)) {
       if (statement.exportClause && ts.isNamedExports(statement.exportClause)) {
         for (const element of statement.exportClause.elements) {
-          addExport(exports, publicSymbols, path12, element.name.text, "re-export");
+          addExport(exports, publicSymbols, path13, element.name.text, "re-export");
         }
       }
       continue;
     }
     if (ts.isFunctionDeclaration(statement) && hasExportModifier(statement)) {
-      addExport(exports, publicSymbols, path12, declarationName(statement), "function");
+      addExport(exports, publicSymbols, path13, declarationName(statement), "function");
       continue;
     }
     if (ts.isClassDeclaration(statement) && hasExportModifier(statement)) {
-      addExport(exports, publicSymbols, path12, declarationName(statement), "class");
+      addExport(exports, publicSymbols, path13, declarationName(statement), "class");
       continue;
     }
     if (ts.isInterfaceDeclaration(statement) && hasExportModifier(statement)) {
-      addExport(exports, publicSymbols, path12, declarationName(statement), "interface");
+      addExport(exports, publicSymbols, path13, declarationName(statement), "interface");
       continue;
     }
     if (ts.isTypeAliasDeclaration(statement) && hasExportModifier(statement)) {
-      addExport(exports, publicSymbols, path12, declarationName(statement), "type");
+      addExport(exports, publicSymbols, path13, declarationName(statement), "type");
       continue;
     }
     if (ts.isEnumDeclaration(statement) && hasExportModifier(statement)) {
-      addExport(exports, publicSymbols, path12, declarationName(statement), "enum");
+      addExport(exports, publicSymbols, path13, declarationName(statement), "enum");
       continue;
     }
     if (ts.isVariableStatement(statement) && hasExportModifier(statement)) {
       for (const declaration of statement.declarationList.declarations) {
-        addExport(exports, publicSymbols, path12, declarationName(declaration), "const");
+        addExport(exports, publicSymbols, path13, declarationName(declaration), "const");
       }
     }
   }
@@ -5490,7 +6264,7 @@ var buildRepoIndex = async (cwd) => {
     if (!isJavaScriptLikePath(file.path)) {
       continue;
     }
-    const source = await fs18.readFile(path7.join(rootDir, file.path), "utf8");
+    const source = await fs18.readFile(path8.join(rootDir, file.path), "utf8");
     const analysis = analyzeTypeScriptSource(file.path, source);
     imports.push(...analysis.imports);
     exports.push(...analysis.exports);
@@ -5522,7 +6296,7 @@ import { execa as execa4 } from "execa";
 
 // src/git/changes.ts
 import fs19 from "fs/promises";
-import path8 from "path";
+import path9 from "path";
 import { execa as execa3 } from "execa";
 var normalizePath3 = (filePath) => {
   return filePath.replaceAll("\\", "/").replace(/^\.\//u, "");
@@ -5577,7 +6351,7 @@ var getUncommittedChanges = async (cwd) => {
   const deletedPathCandidates = /* @__PURE__ */ new Set([...stagedDeletedPaths, ...unstagedDeletedPaths]);
   for (const deletedPath of deletedPathCandidates) {
     const change = getOrCreateChange(changesByPath, deletedPath);
-    change.deleted = !await pathExists4(path8.join(rootDir, deletedPath));
+    change.deleted = !await pathExists4(path9.join(rootDir, deletedPath));
   }
   return Array.from(changesByPath.values()).sort((left, right) => {
     return left.path.localeCompare(right.path);
@@ -5698,7 +6472,7 @@ var resolveImportPath = (importEdge) => {
   if (!importEdge.specifier.startsWith(".")) {
     return null;
   }
-  const basePath = path9.posix.normalize(path9.posix.join(path9.posix.dirname(importEdge.from), importEdge.specifier));
+  const basePath = path10.posix.normalize(path10.posix.join(path10.posix.dirname(importEdge.from), importEdge.specifier));
   const withoutExtension = basePath.replace(/\.[cm]?[jt]sx?$/u, "");
   return withoutExtension;
 };
@@ -5711,7 +6485,7 @@ var importTargetsChangedFile = (importEdge, changedPath) => {
 };
 var pathSegments = (filePath) => filePath.split("/").filter(Boolean);
 var testHintMatchesChangedFile = (hints, changedPath) => {
-  const changedBaseName = path9.posix.basename(changedPath);
+  const changedBaseName = path10.posix.basename(changedPath);
   const changedSegments = pathSegments(changedPath);
   return hints.some((hint) => changedBaseName.startsWith(hint) || changedSegments.includes(hint));
 };
@@ -5872,7 +6646,7 @@ import fg8 from "fast-glob";
 
 // src/evidence/parse.ts
 import fs20 from "fs/promises";
-import path10 from "path";
+import path11 from "path";
 import matter3 from "gray-matter";
 import { parse as parse3 } from "yaml";
 var evidenceBlockPattern = /```ya?ml\s*\n([\s\S]*?)```/giu;
@@ -5881,9 +6655,9 @@ var normalizeReferencePath = (truthDocPath, referencePath) => {
   const strippedPath = referencePath.split("#")[0]?.trim() ?? "";
   const isRepoRelative = repoRootPrefixes.some((prefix) => strippedPath.startsWith(prefix));
   if (!isRepoRelative && (strippedPath.startsWith(".") || !strippedPath.includes("/"))) {
-    return path10.posix.normalize(path10.posix.join(path10.posix.dirname(truthDocPath), strippedPath));
+    return path11.posix.normalize(path11.posix.join(path11.posix.dirname(truthDocPath), strippedPath));
   }
-  return path10.posix.normalize(strippedPath);
+  return path11.posix.normalize(strippedPath);
 };
 var toEvidenceReference = (truthDocPath, raw) => {
   if (!raw || typeof raw !== "object" || !("path" in raw) || typeof raw.path !== "string") {
@@ -5900,7 +6674,7 @@ var toEvidenceReference = (truthDocPath, raw) => {
   };
 };
 var parseEvidenceReferences = async (rootDir, truthDocPath) => {
-  const source = await fs20.readFile(path10.join(rootDir, truthDocPath), "utf8");
+  const source = await fs20.readFile(path11.join(rootDir, truthDocPath), "utf8");
   const parsed = matter3(source);
   const references = [];
   const sourceOfTruth = Array.isArray(parsed.data.source_of_truth) ? parsed.data.source_of_truth : [];
@@ -6138,7 +6912,7 @@ var runCheck = async (cwd, options = {}) => {
 
 // src/context-pack/build.ts
 import fs22 from "fs/promises";
-import path11 from "path";
+import path12 from "path";
 import fg9 from "fast-glob";
 var uniqueSorted2 = (values) => [...new Set(values)].sort();
 var repoRootPrefixes2 = [".codex/", ".github/", ".truthmark/", "docs/", "src/", "tests/"];
@@ -6149,12 +6923,12 @@ var normalizeDocReferencePath = (docPath, referencePath) => {
     return null;
   }
   const isRepoRelative = repoRootPrefixes2.some((prefix) => strippedPath.startsWith(prefix));
-  const normalized = isRepoRelative ? path11.posix.normalize(strippedPath) : path11.posix.normalize(path11.posix.join(path11.posix.dirname(docPath), strippedPath));
+  const normalized = isRepoRelative ? path12.posix.normalize(strippedPath) : path12.posix.normalize(path12.posix.join(path12.posix.dirname(docPath), strippedPath));
   return normalized === ".." || normalized.startsWith("../") ? null : normalized;
 };
 var readIfExists = async (rootDir, filePath) => {
   try {
-    return await fs22.readFile(path11.join(rootDir, filePath), "utf8");
+    return await fs22.readFile(path12.join(rootDir, filePath), "utf8");
   } catch {
     return null;
   }
@@ -6294,6 +7068,319 @@ var renderContextPackMarkdown = (pack) => {
 `;
 };
 
+// src/cli/handlers.ts
+import fs23 from "fs/promises";
+
+// src/agents/workflow-helper-validation.ts
+import { parse as parseYaml2 } from "yaml";
+var escapeRegex = (value) => value.split("").map((char) => ".+*?^$()[]{}|\\".includes(char) ? `\\${char}` : char).join("");
+var hasLabel = (text, label) => {
+  const escaped = escapeRegex(label);
+  return new RegExp(String.raw`(^|\n)\s*(?:#{1,6}\s*)?${escaped}\s*:?\s*(\n|$)`, "iu").test(
+    text
+  );
+};
+var getSection = (text, label) => {
+  const lines = text.split(/\r?\n/u);
+  const labelPattern = new RegExp(String.raw`^(?:#{1,6}\s*)?${escapeRegex(label)}\s*:?\s*$`, "iu");
+  const sectionHeaderPattern = /^(?:#{1,6}\s*)?[A-Z][A-Za-z0-9 ]+:\s*$/u;
+  const startIndex = lines.findIndex((line) => labelPattern.test(line));
+  if (startIndex === -1) {
+    return null;
+  }
+  const nextSectionOffset = lines.slice(startIndex + 1).findIndex((line) => sectionHeaderPattern.test(line));
+  const endIndex = nextSectionOffset === -1 ? lines.length : startIndex + 1 + nextSectionOffset;
+  return lines.slice(startIndex + 1, endIndex).join("\n").trim();
+};
+var requireBulletSection = (text, label, errors, checks) => {
+  const section = getSection(text, label);
+  if (section === null) {
+    errors.push(`missing required section: ${label}`);
+    return;
+  }
+  if (!/^-\s+\S/mu.test(section)) {
+    errors.push(`${label} must include at least one bullet`);
+    return;
+  }
+  checks.push(label);
+};
+var validateEvidenceChecked = (text, errors, checks) => {
+  const section = getSection(text, "Evidence checked");
+  if (section === null || section === "") {
+    errors.push("Evidence checked must include at least one structured entry");
+    return;
+  }
+  const entries = section.split(/\n(?=-\s+)/u).map((entry) => entry.trim()).filter(Boolean);
+  if (entries.length === 0) {
+    errors.push("Evidence checked must include at least one structured entry");
+    return;
+  }
+  const entryPattern = /^- Claim:\s*\S[^\n]*\n {2,}Evidence:\s*\S[^\n]*\n {2,}Result:\s*(supported|narrowed|removed|blocked)\s*$/iu;
+  for (const [index, entry] of entries.entries()) {
+    if (!entryPattern.test(entry)) {
+      errors.push(
+        `Evidence checked entry ${index + 1} must match '- Claim: ...' followed by indented 'Evidence: ...' and 'Result: supported | narrowed | removed | blocked'`
+      );
+    }
+  }
+  if (errors.length === 0) {
+    checks.push(
+      "Evidence checked entries include Claim:, Evidence:, and Result: supported | narrowed | removed | blocked"
+    );
+  }
+};
+var validateHelperScriptEntries = (entries, requiredHelpers, errors, checks) => {
+  if (entries === void 0 || entries.length === 0) {
+    errors.push("Helper scripts must include status for optional helpers");
+    return;
+  }
+  const statusPattern = /^(?:-\s*)?([a-z0-9-]+):\s*(?:ran,\s*passed|skipped,\s*\S.*)$/iu;
+  const validHelperIds = /* @__PURE__ */ new Set();
+  for (const entry of entries) {
+    const match = entry.trim().match(statusPattern);
+    if (match === null) {
+      errors.push(
+        "Helper scripts entries must match '- helper-id: ran, passed' or '- helper-id: skipped, reason'; ran, failed is not valid for completed reports"
+      );
+      continue;
+    }
+    validHelperIds.add(match[1].toLowerCase());
+  }
+  for (const helperId of requiredHelpers) {
+    if (!validHelperIds.has(helperId.toLowerCase())) {
+      errors.push(`missing Helper scripts status: ${helperId}`);
+    }
+  }
+  if (errors.length === 0) {
+    checks.push(`Helper scripts statuses include ${requiredHelpers.join(", ")}`);
+  }
+};
+var validateHelperScripts = (text, requiredHelpers, errors, checks) => {
+  const section = getSection(text, "Helper scripts");
+  const entries = section?.split(/\n/u).map((entry) => entry.trim()).filter(Boolean);
+  validateHelperScriptEntries(entries, requiredHelpers, errors, checks);
+};
+var validateTruthSyncReportText = (text) => {
+  const helper = "validate-sync-report";
+  const statusMatch = text.match(/^\s*Truth Sync:\s*(completed|blocked|skipped)\b/imu);
+  if (statusMatch === null) {
+    return {
+      ok: false,
+      helper,
+      errors: ["missing Truth Sync status: expected completed, blocked, or skipped"]
+    };
+  }
+  const status = statusMatch[1].toLowerCase();
+  const checks = [`status: ${status}`];
+  const errors = [];
+  if (status === "completed") {
+    try {
+      const report = parseTruthSyncReport(text.trimStart());
+      for (const [label, items] of [
+        ["Changed code reviewed", report.changedCode],
+        ["Ownership reviewed", report.ownershipReviewed],
+        ["Truth docs updated", report.truthDocsUpdated],
+        ["Notes", report.notes]
+      ]) {
+        if (items.length === 0) {
+          errors.push(`${label} must include at least one bullet`);
+        } else {
+          checks.push(label);
+        }
+      }
+      if (report.evidenceChecked.length === 0) {
+        errors.push("Evidence checked must include at least one structured entry");
+      } else {
+        checks.push(
+          "Evidence checked entries include Claim:, Evidence:, and Result: supported | narrowed | removed | blocked"
+        );
+      }
+      validateHelperScriptEntries(
+        report.helperScripts,
+        ["validate-write-lease"],
+        errors,
+        checks
+      );
+    } catch (error) {
+      errors.push(error instanceof Error ? error.message : "invalid Truth Sync report");
+    }
+  } else if (status === "skipped") {
+    requireBulletSection(text, "Reason", errors, checks);
+  } else if (status === "blocked") {
+    requireBulletSection(text, "Reason", errors, checks);
+    requireBulletSection(text, "Files requiring manual review", errors, checks);
+    requireBulletSection(text, "Next action", errors, checks);
+  }
+  return errors.length > 0 ? { ok: false, helper, errors } : { ok: true, helper, checks };
+};
+var validateTruthDocumentReportText = (text) => {
+  const helper = "validate-document-report";
+  const statusMatch = text.match(/^\s*Truth Document:\s*(completed|blocked)\b/imu);
+  if (statusMatch === null) {
+    return {
+      ok: false,
+      helper,
+      errors: ["missing Truth Document status: expected completed or blocked"]
+    };
+  }
+  const status = statusMatch[1].toLowerCase();
+  const checks = [`status: ${status}`];
+  const errors = [];
+  if (status === "completed") {
+    for (const label of ["Implementation reviewed", "Ownership reviewed", "Notes"]) {
+      requireBulletSection(text, label, errors, checks);
+    }
+    if (hasLabel(text, "Evidence checked")) {
+      checks.push("Evidence checked");
+    } else {
+      errors.push("missing required section: Evidence checked");
+    }
+    if (hasLabel(text, "Helper scripts")) {
+      checks.push("Helper scripts");
+    } else {
+      errors.push("missing required section: Helper scripts");
+    }
+    const truthDocsUpdated = getSection(text, "Truth docs updated");
+    const truthDocsCreated = getSection(text, "Truth docs created");
+    if (truthDocsUpdated === null && truthDocsCreated === null) {
+      errors.push("missing required section: Truth docs updated or Truth docs created");
+    } else if (![truthDocsUpdated, truthDocsCreated].some(
+      (section) => section !== null && /^-\s+\S/mu.test(section)
+    )) {
+      errors.push("Truth docs updated or Truth docs created must include at least one bullet");
+    } else {
+      checks.push("Truth docs updated or created");
+    }
+    validateEvidenceChecked(text, errors, checks);
+    validateHelperScripts(text, ["validate-write-lease"], errors, checks);
+  } else if (status === "blocked") {
+    requireBulletSection(text, "Reason", errors, checks);
+  }
+  return errors.length > 0 ? { ok: false, helper, errors } : { ok: true, helper, checks };
+};
+var cleanPathValue = (value) => value.trim().replace(/^["']|["']$/gu, "");
+var normalizePath5 = (value) => cleanPathValue(value).replace(/^\.\//u, "");
+var windowsDriveAbsolutePattern = /^[A-Za-z]:[\\/]/u;
+var uncPathPattern = /^[/\\]{2}[^/\\]+[/\\]+[^/\\]+/u;
+var isUnsafePathValue = (value) => {
+  const cleanValue = cleanPathValue(value);
+  const pathValue = cleanValue.endsWith("/**") ? cleanValue.slice(0, -3) : cleanValue;
+  return pathValue.startsWith("/") || pathValue.startsWith("\\") || windowsDriveAbsolutePattern.test(pathValue) || uncPathPattern.test(pathValue) || pathValue.split(/[\\/]+/u).includes("..");
+};
+var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var findWriteLeaseRecord = (value) => {
+  if (!isRecord(value)) {
+    return null;
+  }
+  if (Object.prototype.hasOwnProperty.call(value, "allowedWrites") || Object.prototype.hasOwnProperty.call(value, "forbiddenWrites")) {
+    return value;
+  }
+  for (const nestedKey of ["writeLease", "lease"]) {
+    const nested = value[nestedKey];
+    if (isRecord(nested)) {
+      return nested;
+    }
+  }
+  return value;
+};
+var readStringArray = (record, field, errors) => {
+  const value = record[field];
+  if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) {
+    errors.push(`${field} must be an array of strings`);
+    return [];
+  }
+  return value;
+};
+var parseListFields = (text) => {
+  const errors = [];
+  let parsed;
+  try {
+    parsed = parseYaml2(text);
+  } catch (error) {
+    return {
+      allowedWrites: [],
+      forbiddenWrites: [],
+      errors: [
+        `manual-validation required: invalid write lease YAML${error instanceof Error ? `: ${error.message}` : ""}`
+      ]
+    };
+  }
+  const record = findWriteLeaseRecord(parsed);
+  if (record === null) {
+    return {
+      allowedWrites: [],
+      forbiddenWrites: [],
+      errors: ["write lease YAML must be an object"]
+    };
+  }
+  return {
+    allowedWrites: readStringArray(record, "allowedWrites", errors),
+    forbiddenWrites: readStringArray(record, "forbiddenWrites", errors),
+    errors
+  };
+};
+var isSupportedPattern = (pattern) => {
+  const withoutTrailingGlob = pattern.endsWith("/**") ? pattern.slice(0, -3) : pattern;
+  return !/[?*[\]{}]/u.test(withoutTrailingGlob);
+};
+var matchesPattern = (filePath, pattern) => {
+  if (pattern.endsWith("/**")) {
+    const prefix = pattern.slice(0, -3).replace(/\/+$/u, "");
+    return filePath === prefix || filePath.startsWith(`${prefix}/`);
+  }
+  return filePath === pattern;
+};
+var validateWriteLeaseText = (leaseText, changedText) => {
+  const helper = "validate-write-lease";
+  const parsed = parseListFields(leaseText);
+  const rawAllowedWrites = parsed.allowedWrites.map(cleanPathValue).filter(Boolean);
+  const rawForbiddenWrites = parsed.forbiddenWrites.map(cleanPathValue).filter(Boolean);
+  const rawChangedFiles = changedText.split(/\r?\n/u).map(cleanPathValue).filter(Boolean);
+  const allowedWrites = rawAllowedWrites.map(normalizePath5).filter(Boolean);
+  const forbiddenWrites = rawForbiddenWrites.map(normalizePath5).filter(Boolean);
+  const changedFiles = rawChangedFiles.map(normalizePath5).filter(Boolean);
+  const checks = [];
+  const errors = [...parsed.errors];
+  for (const pattern of rawAllowedWrites) {
+    if (isUnsafePathValue(pattern)) {
+      errors.push(`invalid allowedWrites path: ${pattern}`);
+    }
+  }
+  for (const pattern of rawForbiddenWrites) {
+    if (isUnsafePathValue(pattern)) {
+      errors.push(`invalid forbiddenWrites path: ${pattern}`);
+    }
+  }
+  for (const filePath of rawChangedFiles) {
+    if (isUnsafePathValue(filePath)) {
+      errors.push(`invalid changed file path: ${filePath}`);
+    }
+  }
+  for (const pattern of [...allowedWrites, ...forbiddenWrites]) {
+    if (!isSupportedPattern(pattern)) {
+      errors.push(`manual-validation required: unsupported write pattern ${pattern}`);
+    }
+  }
+  if (allowedWrites.length === 0) {
+    errors.push("manual-validation required: no allowedWrites entries found");
+  }
+  if (errors.length === 0) {
+    for (const filePath of changedFiles) {
+      if (!allowedWrites.some((pattern) => matchesPattern(filePath, pattern))) {
+        errors.push(`${filePath} is outside allowedWrites`);
+        continue;
+      }
+      const forbiddenPattern = forbiddenWrites.find((pattern) => matchesPattern(filePath, pattern));
+      if (forbiddenPattern !== void 0) {
+        errors.push(`${filePath} matches forbiddenWrites pattern ${forbiddenPattern}`);
+        continue;
+      }
+      checks.push(filePath);
+    }
+  }
+  return errors.length > 0 ? { ok: false, helper, errors } : { ok: true, helper, checks };
+};
+
 // src/cli/handlers.ts
 var runConfig2 = async (options) => {
   return runConfig(process.cwd(), options);
@@ -6350,6 +7437,33 @@ var isContextPackWorkflow = (value) => {
 var isContextPackFormat = (value) => {
   return value === void 0 || value === "json" || value === "markdown";
 };
+var readHelperFile = async (filePath, helper) => {
+  try {
+    return await fs23.readFile(filePath, "utf8");
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { ok: false, helper, errors: [`could not read file: ${message}`] };
+  }
+};
+var runValidateSyncReport = async (reportFile) => {
+  const text = await readHelperFile(reportFile, "validate-sync-report");
+  return typeof text === "string" ? validateTruthSyncReportText(text) : text;
+};
+var runValidateDocumentReport = async (reportFile) => {
+  const text = await readHelperFile(reportFile, "validate-document-report");
+  return typeof text === "string" ? validateTruthDocumentReportText(text) : text;
+};
+var runValidateWriteLease = async (leaseFile, changedFilesFile) => {
+  const leaseText = await readHelperFile(leaseFile, "validate-write-lease");
+  if (typeof leaseText !== "string") {
+    return leaseText;
+  }
+  const changedText = await readHelperFile(changedFilesFile, "validate-write-lease");
+  if (typeof changedText !== "string") {
+    return changedText;
+  }
+  return validateWriteLeaseText(leaseText, changedText);
+};
 var runContext = async (options) => {
   if (!isContextPackWorkflow(options.workflow)) {
     return {
@@ -6406,6 +7520,28 @@ var writeContextResult = (result, options) => {
   }
   writeResult(result, options);
 };
+var renderValidationHuman = (result) => {
+  if (result.ok === true) {
+    return [`${result.helper}: ok`, ...result.checks.map((check) => `- ${check}`)].join("\n");
+  }
+  return [`${result.helper}: failed`, ...result.errors.map((error) => `- ${error}`)].join("\n");
+};
+var toValidationCommandResult = (command, result) => ({
+  command,
+  summary: result.ok ? "Validation passed" : "Validation failed",
+  diagnostics: [],
+  data: {
+    validation: result
+  }
+});
+var writeValidationResult = (command, result, options) => {
+  const output = options.json ? renderJson(toValidationCommandResult(command, result)) : renderValidationHuman(result);
+  process.stdout.write(`${output}
+`);
+  if (!result.ok) {
+    process.exitCode = 1;
+  }
+};
 var addJsonOption = (command) => {
   return command.option("--json", "Render command output as JSON");
 };
@@ -6449,6 +7585,32 @@ var buildProgram = () => {
       options
     );
   });
+  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);
+  });
+  addJsonOption(
+    validate.command("document-report").description("Validate a Truth Document report file.").argument("<report-file>", "Truth Document report file")
+  ).action(async (reportFile, options) => {
+    writeValidationResult(
+      "validate document-report",
+      await runValidateDocumentReport(reportFile),
+      options
+    );
+  });
+  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")
+  ).action(
+    async (leaseOrReportFile, changedFilesFile, options) => {
+      writeValidationResult(
+        "validate write-lease",
+        await runValidateWriteLease(leaseOrReportFile, changedFilesFile),
+        options
+      );
+    }
+  );
   return program;
 };