@kontourai/flow-agents 3.12.0 → 4.0.0

package/dist/opencode/build/src/cli/workflow-sidecar.js

@@ -14,7 +14,8 @@ import { flowAgentsPackageRoot, flowAgentsPackageVersion } from "../lib/package-
 import { pinnedFlowAgentsCommand } from "../lib/pinned-cli-command.js";
 import { runObservedCommand } from "../lib/observed-command.js";
 import { captureReviewWorkspaceSnapshot, startBuilderFlowSession, syncBuilderFlowSession } from "../builder-flow-runtime.js";
-import { WORKFLOW_CRITIQUE_STATUSES } from "./public-contracts.js";
+import { NARRATIVE_NAMESPACE_ROOT } from "./narrative-sources.js";
+import { EVIDENCE_REF_FIELD_SCHEMAS, EVIDENCE_REF_KINDS, EVIDENCE_REF_RULES, NARRATIVE_PROMOTE_OPERATION, WORKFLOW_ACCEPTANCE_STATUSES, WORKFLOW_CRITIQUE_STATUSES, } from "./public-contracts.js";
 // #291 Wave 1 Task 1.1 exports: ensure-session's ownership guard reuses the EXACT same
 // assignment ⋈ liveness join / claim / supersede logic #290 already ships for the
 // `assignment-provider` CLI, rather than reimplementing a second, parallel join (static ESM
@@ -391,62 +392,23 @@ export async function validateTrustBundle(bundle) {
         return { valid: false, errors: [message], available: true };
     }
 }
-// Validate a single InquiryRecord against the hachure inquiry-record.schema.json.
-// Uses a separate AJV instance compiled against that schema (not the trust-bundle schema).
-let _hachureInquiryRecordValidator;
-function getHachureInquiryRecordValidator() {
-    if (_hachureInquiryRecordValidator !== undefined)
-        return _hachureInquiryRecordValidator;
-    try {
-        const _require = createRequire(import.meta.url);
-        const hachureDir = path.dirname(_require.resolve("hachure"));
-        const schemasDir = path.join(hachureDir, "schemas");
-        const Ajv = _require("ajv/dist/2020");
-        const schemas = {};
-        for (const file of fs.readdirSync(schemasDir)) {
-            if (!file.endsWith(".schema.json"))
-                continue;
-            schemas[file] = JSON.parse(fs.readFileSync(path.join(schemasDir, file), "utf8"));
-        }
-        const inquiryRecordSchema = schemas["inquiry-record.schema.json"];
-        if (!inquiryRecordSchema) {
-            _hachureInquiryRecordValidator = null;
-            return null;
-        }
-        const ajv = new Ajv({ strict: false, allErrors: true });
-        for (const [filename, schema] of Object.entries(schemas)) {
-            if (filename === "inquiry-record.schema.json")
-                continue;
-            ajv.addSchema(schema, filename);
-        }
-        const validate = ajv.compile(inquiryRecordSchema);
-        _hachureInquiryRecordValidator = (record) => {
-            const valid = validate(record);
-            if (valid)
-                return { valid: true, errors: [] };
-            const errors = (validate.errors ?? []).map((err) => {
-                const loc = err.instancePath || err.schemaPath || "";
-                return `${loc} ${err.message ?? "invalid"}`.trim();
-            });
-            return { valid: false, errors };
-        };
-        return _hachureInquiryRecordValidator;
-    }
-    catch {
-        _hachureInquiryRecordValidator = null;
-        return null;
-    }
-}
 /**
- * Validate a record against the canonical hachure inquiry-record.schema.json
- * (https://kontourai.io/schemas/surface/inquiry-record.schema.json).
- * Returns `{ valid, errors, available }`. Fail-open when hachure is not installed.
+ * Validate a record against the canonical InquiryRecord schema via
+ * @kontourai/surface's `validateInquiryRecord` (symmetric to `validateTrustBundle`).
+ * Returns `{ valid, errors, available }`. Fail-open when Surface is unavailable.
  */
-export function validateInquiryRecord(record) {
-    const validate = getHachureInquiryRecordValidator();
-    if (!validate)
+export async function validateInquiryRecord(record) {
+    const m = await tryLoadSurface();
+    if (!m || typeof m.validateInquiryRecord !== "function") {
         return { valid: true, errors: [], available: false };
-    return { ...validate(record), available: true };
+    }
+    try {
+        m.validateInquiryRecord(record);
+        return { valid: true, errors: [], available: true };
+    }
+    catch (err) {
+        return { valid: false, errors: [err instanceof Error ? err.message : String(err)], available: true };
+    }
 }
 let _surfaceModule; // undefined = not tried yet; null = unavailable
 async function tryLoadSurface() {
@@ -488,6 +450,15 @@ function criterionStatusToEventStatus(status) {
         return "assumed";
     return null; // pending / not_verified → no event → Surface returns "unknown"
 }
+const ACCEPTANCE_CRITERION_STATUSES = new Set(WORKFLOW_ACCEPTANCE_STATUSES);
+const CANONICALLY_OBSERVED_ACCEPTANCE_CRITERIA = new WeakSet();
+function markCanonicallyObservedCriterion(criterion) {
+    CANONICALLY_OBSERVED_ACCEPTANCE_CRITERIA.add(criterion);
+    return criterion;
+}
+function normalizeCriterionStatus(status) {
+    return typeof status === "string" && ACCEPTANCE_CRITERION_STATUSES.has(status) ? status : "pending";
+}
 /**
  * WS8 (ADR 0020): Derive Surface evidence classification (evidenceType + method)
  * from a workflow check's kind, replacing the previous hardcoded `test_output`.
@@ -599,7 +570,23 @@ export function reduceCaptureLogByCommand(commandLog) {
             else
                 merged = "ambiguous";
         }
-        const mergedExitCode = exitCode !== null ? exitCode : (prev ? prev.exitCode : null);
+        // #634 review finding: the exit code must travel with the WINNING status, never a
+        // losing entry's — [hook fail exit 1, writer pass exit 0] must fold to fail/1, not
+        // fail/0 (contradictory isError:true, exitCode:0 evidence). When both entries carry
+        // the winning status, prefer the newer non-null code.
+        let mergedExitCode;
+        if (!prev) {
+            mergedExitCode = exitCode;
+        }
+        else if (merged === result && merged === prev.observedResult) {
+            mergedExitCode = exitCode !== null ? exitCode : prev.exitCode;
+        }
+        else if (merged === result) {
+            mergedExitCode = exitCode;
+        }
+        else {
+            mergedExitCode = prev.exitCode;
+        }
         captureByCommand.set(key, { observedResult: merged, exitCode: mergedExitCode });
     }
     return captureByCommand;
@@ -790,8 +777,6 @@ export async function buildTrustBundle(slug, timestamp, checks, criteria, critiq
     //     "flow-step". Fallback: first non-decision, non-acceptance entry.
     //   check (kind=policy)     → expects[] entry whose claimType contains
     //     "compliance" or "policy". Fallback: same as non-policy.
-    //   acceptance criterion    → expects[] entry whose subjectType is "flow-step"
-    //     OR claimType contains "tests" OR "compliance". Fallback: first entry.
     //   critique                → expects[] entry whose claimType contains "policy"
     //     OR "compliance" AND subjectType is "artifact". Fallback: last entry.
     //
@@ -801,7 +786,7 @@ export async function buildTrustBundle(slug, timestamp, checks, criteria, critiq
     // Surface from that evidence (never hand-set).
     //
     // Per-gate producibility (ADR 0016 P-d):
-    //   (a) Already handled via subjectType=flow-step preference:
+    //   (a) Already handled via subjectType=flow-step preference for checks:
     //       builder.verify.tests       (verify-gate, subjectType=flow-step)
     //       builder.verify.policy-compliance (verify-gate, kind=policy match)
     //   (b) Producible via fallback (non-decision, non-acceptance, first match):
@@ -818,6 +803,9 @@ export async function buildTrustBundle(slug, timestamp, checks, criteria, critiq
     //       builder.learn.evidence            (learn-gate, subjectType=release)
     //   For category (c): record-gate-claim subcommand allows skills to target a specific
     //   expects[] entry by --expectation <id>, bypassing this semantic match entirely.
+    //
+    // Acceptance criteria do not participate in this matching table. They are durable Work Item
+    // facts with invariant workflow.acceptance.criterion/flow-step identity across every gate.
     function matchExpectsEntry(kind, checkKindVal, expectationId) {
         if (!activeStep || activeStep.gateExpects.length === 0)
             return null;
@@ -856,15 +844,6 @@ export async function buildTrustBundle(slug, timestamp, checks, criteria, critiq
                 return { claimType: fallback.bundle_claim.claimType, subjectType: fallback.bundle_claim.subjectType };
             return null;
         }
-        if (kind === "acceptance") {
-            const match = expects.find((e) => {
-                const ct = e.bundle_claim.claimType.toLowerCase();
-                return e.bundle_claim.subjectType === "flow-step" || ct.includes("tests") || ct.includes("compliance");
-            });
-            if (match)
-                return { claimType: match.bundle_claim.claimType, subjectType: match.bundle_claim.subjectType };
-            return { claimType: expects[0].bundle_claim.claimType, subjectType: expects[0].bundle_claim.subjectType };
-        }
         if (kind === "critique") {
             const match = expects.find((e) => {
                 const ct = e.bundle_claim.claimType.toLowerCase();
@@ -1059,33 +1038,71 @@ export async function buildTrustBundle(slug, timestamp, checks, criteria, critiq
             continue;
         const subjectId = `${slug}/${criterion.id}`;
         const fieldOrBehavior = String(criterion.description ?? criterion.id);
+        const normalizedCriterionStatus = normalizeCriterionStatus(criterion.status);
         const criterionIdentityVersion = criterion.identity_version === 2 ? 2 : 1;
         const criterionVerifiedAt = criterionIdentityVersion === 2 && typeof criterion.verified_at === "string" ? criterion.verified_at : null;
+        const criterionEvidenceRefs = Array.isArray(criterion.evidence_refs) ? criterion.evidence_refs : [];
+        const commandRefs = criterionEvidenceRefs
+            .filter((ref) => ref?.kind === "command")
+            .map((ref) => commandFromEvidenceRef(ref))
+            .filter((command) => command.length > 0);
+        const rawObservedCommands = Array.isArray(criterion._observed_commands) ? criterion._observed_commands : [];
+        const observedCommands = rawObservedCommands.filter((observation) => typeof observation?.command === "string"
+            && commandRefs.includes(observation.command)
+            && observation.exit_code === 0
+            && typeof observation.output_sha256 === "string"
+            && /^[a-f0-9]{64}$/i.test(observation.output_sha256)
+            && Number.isSafeInteger(observation.test_count)
+            && observation.test_count > 0
+            && observation.execution_proof?.kind === "local-process-exit");
+        const hasObservedCommandProvenance = CANONICALLY_OBSERVED_ACCEPTANCE_CRITERIA.has(criterion)
+            && criterionIdentityVersion === 2
+            && criterionVerifiedAt !== null
+            && Number.isFinite(Date.parse(criterionVerifiedAt))
+            && observedCommands.length === rawObservedCommands.length
+            && observedCommands.length > 0
+            && commandRefs.every((command) => observedCommands.some((observation) => observation.command === command));
+        const criterionStatus = normalizedCriterionStatus === "pass" && !hasObservedCommandProvenance
+            ? "pending"
+            : normalizedCriterionStatus;
+        const criterionClaimTimestamp = criterionStatus === "pass" && criterionVerifiedAt ? criterionVerifiedAt : ts;
         const claimId = generateClaimId(subjectId, "flow-agents.workflow", criterionVerifiedAt ? `${fieldOrBehavior}::verified::${criterionVerifiedAt}` : fieldOrBehavior);
-        const legacyClaimType = "workflow.acceptance.criterion";
-        const policy = ensurePolicy(legacyClaimType, "high", []);
-        const evStatus = criterionStatusToEventStatus(String(criterion.status ?? ""));
+        const claimType = "workflow.acceptance.criterion";
+        const criterionEvidenceIds = [];
+        if (criterionStatus === "pass") {
+            for (const observation of observedCommands) {
+                const evidenceId = `ev:${claimId}:${createHash("sha256").update(observation.command).digest("hex").slice(0, 16)}`;
+                criterionEvidenceIds.push(evidenceId);
+                evidenceItems.push({
+                    id: evidenceId,
+                    claimId,
+                    evidenceType: "test_output",
+                    method: "validation",
+                    sourceRef: `${slug}/observed-command`,
+                    excerptOrSummary: observation.command,
+                    observedAt: criterionVerifiedAt,
+                    collectedBy: "flow-agents/workflow-sidecar",
+                    passing: true,
+                    execution: { runner: "bash", label: observation.command, isError: false, exitCode: 0 },
+                });
+            }
+        }
+        const policy = ensurePolicy(claimType, "high", criterionEvidenceIds.length > 0 ? ["test_output"] : []);
+        const evStatus = criterionStatusToEventStatus(criterionStatus);
         const claimEvents = [];
         if (evStatus) {
-            const evt = { id: `evt:${claimId}`, claimId, status: evStatus, actor: "flow-agents/workflow-sidecar", method: "validation", evidenceIds: [], createdAt: ts, verifiedAt: ts };
+            const evt = { id: `evt:${claimId}`, claimId, status: evStatus, actor: "flow-agents/workflow-sidecar", method: "validation", evidenceIds: criterionEvidenceIds, createdAt: criterionClaimTimestamp, verifiedAt: criterionClaimTimestamp };
             events.push(evt);
             claimEvents.push(evt);
         }
-        // P-d: declared-only when active flow/step present (shadow retired); no-flow path unchanged.
-        const declared = matchExpectsEntry("acceptance");
-        if (declared) {
-            // Declared kit-typed claim only — no legacy shadow (ADR 0016 P-d).
-            const declaredPolicy = ensurePolicy(declared.claimType, "high", []);
-            const declaredClaimObj = { id: claimId, subjectType: declared.subjectType, subjectId, facet: "flow-agents.workflow", claimType: declared.claimType, fieldOrBehavior, value: criterion.status, createdAt: ts, updatedAt: ts, impactLevel: "high", verificationPolicyId: declaredPolicy.id, metadata: { origin: "acceptance", criterion: { id: criterion.id, description: criterion.description ?? criterion.id, status: criterion.status, evidence_refs: Array.isArray(criterion.evidence_refs) ? criterion.evidence_refs : [], ...(criterionIdentityVersion === 2 ? { identity_version: 2 } : {}), ...(criterionVerifiedAt ? { verified_at: criterionVerifiedAt } : {}) }, ...(workflowSubjectRef ? { workflow_subject_ref: workflowSubjectRef } : {}) } };
-            const { status: declaredStatus } = deriveClaimStatus({ claim: declaredClaimObj, evidence: [], events: claimEvents, policies: [declaredPolicy] });
-            claims.push({ ...declaredClaimObj, status: declaredStatus });
-        }
-        else {
-            // No active flow step — only the workflow.* primary claim (legitimate no-flow fallback path).
-            const claimObj = { id: claimId, subjectType: "workflow-acceptance-criterion", subjectId, facet: "flow-agents.workflow", claimType: legacyClaimType, fieldOrBehavior, value: criterion.status, createdAt: ts, updatedAt: ts, impactLevel: "high", verificationPolicyId: policy.id, metadata: { origin: "acceptance", criterion: { id: criterion.id, description: criterion.description ?? criterion.id, status: criterion.status, evidence_refs: Array.isArray(criterion.evidence_refs) ? criterion.evidence_refs : [] } } };
-            const { status: derivedStatus } = deriveClaimStatus({ claim: claimObj, evidence: [], events: claimEvents, policies: [policy] });
-            claims.push({ ...claimObj, status: derivedStatus });
-        }
+        // Acceptance criteria are durable Work Item facts. Their identity must not change when a
+        // bundle is rebuilt at a different active gate. Missing or invalid status is conservatively
+        // projected as pending so direct artifact edits can never manufacture a pass or invalidate
+        // the Hachure claim shape.
+        const claimObj = { id: claimId, subjectType: "flow-step", subjectId, facet: "flow-agents.workflow", claimType, fieldOrBehavior, value: criterionStatus, createdAt: criterionClaimTimestamp, updatedAt: criterionClaimTimestamp, impactLevel: "high", verificationPolicyId: policy.id, metadata: { origin: "acceptance", criterion: { id: criterion.id, description: criterion.description ?? criterion.id, status: criterionStatus, evidence_refs: criterionEvidenceRefs, ...(observedCommands.length > 0 ? { observed_commands: observedCommands } : {}), ...(criterionIdentityVersion === 2 ? { identity_version: 2 } : {}), ...(criterionVerifiedAt ? { verified_at: criterionVerifiedAt } : {}) }, ...(workflowSubjectRef ? { workflow_subject_ref: workflowSubjectRef } : {}) } };
+        const criterionEvidence = evidenceItems.filter((evidence) => evidence.claimId === claimId);
+        const { status: derivedStatus } = deriveClaimStatus({ claim: claimObj, evidence: criterionEvidence, events: claimEvents, policies: [policy] });
+        claims.push({ ...claimObj, status: derivedStatus });
     }
     // Critique entries → claims + events
     for (const c of Array.isArray(critiques) ? critiques : []) {
@@ -2432,11 +2449,11 @@ function hasNonEmptyString(value) {
 function hasPositiveInteger(value) {
     return Number.isInteger(value) && Number(value) >= 1;
 }
-export function validateEvidenceRef(ref, label) {
-    if (!["source", "command", "artifact", "provider", "external"].includes(ref.kind))
-        die(`${label} entry kind must be one of: source, command, artifact, provider, external`);
+export function validateEvidenceRef(ref, label, projectRoot = process.cwd()) {
+    if (!EVIDENCE_REF_KINDS.includes(ref.kind))
+        die(`${label} entry kind must be one of: ${EVIDENCE_REF_KINDS.join(", ")}`);
     for (const key of Object.keys(ref))
-        if (!["kind", "url", "file", "line_start", "line_end", "excerpt", "summary"].includes(key))
+        if (!Object.hasOwn(EVIDENCE_REF_FIELD_SCHEMAS, key))
             die(`${label} entries contain unsupported field: ${key}`);
     if (ref.url !== undefined && !hasNonEmptyString(ref.url))
         die(`${label} entry url must be a non-empty string`);
@@ -2450,19 +2467,26 @@ export function validateEvidenceRef(ref, label) {
         die(`${label} entry line_start must be a positive integer`);
     if (ref.line_end !== undefined && !hasPositiveInteger(ref.line_end))
         die(`${label} entry line_end must be a positive integer`);
-    if (ref.kind === "source" && (!hasNonEmptyString(ref.file) || !hasPositiveInteger(ref.line_start) || !hasPositiveInteger(ref.line_end) || !hasNonEmptyString(ref.excerpt)))
-        die(`${label} source refs require file, line_start, line_end, and excerpt`);
-    if (ref.kind === "artifact" && (!hasNonEmptyString(ref.file) && !hasNonEmptyString(ref.url)))
-        die(`${label} artifact refs require file or url`);
-    if (ref.kind === "artifact" && (!hasNonEmptyString(ref.summary) && !hasNonEmptyString(ref.excerpt)))
-        die(`${label} artifact refs require summary or excerpt`);
-    if (ref.kind === "command" && (!hasNonEmptyString(ref.summary) && !hasNonEmptyString(ref.excerpt) && !hasNonEmptyString(ref.url)))
-        die(`${label} command refs require summary, excerpt, or url`);
-    if ((ref.kind === "provider" || ref.kind === "external") && !hasNonEmptyString(ref.url))
-        die(`${label} ${ref.kind} refs require url`);
+    rejectNarrativeReference(projectRoot, ref.file, `${label} entry file`);
+    rejectNarrativeReference(projectRoot, ref.url, `${label} entry url`);
+    rejectNarrativeReference(projectRoot, ref.excerpt, `${label} entry excerpt`);
+    const rules = EVIDENCE_REF_RULES[ref.kind];
+    for (const rule of rules) {
+        const present = (field) => field === "line_start" || field === "line_end"
+            ? hasPositiveInteger(ref[field])
+            : hasNonEmptyString(ref[field]);
+        const valid = rule.mode === "all" ? rule.fields.every(present) : rule.fields.some(present);
+        if (!valid) {
+            const separator = rule.fields.length > 2 ? ", " : " ";
+            const joined = rule.fields.length > 1
+                ? `${rule.fields.slice(0, -1).join(separator)}${rule.fields.length > 2 ? "," : ""} or ${rule.fields.at(-1)}`
+                : rule.fields[0];
+            die(`${label} ${ref.kind} refs require ${rule.mode === "all" && rule.fields.length > 1 ? joined.replace(/ or ([^,]+)$/, " and $1") : joined}`);
+        }
+    }
     return ref;
 }
-export function normalizeEvidenceRefs(raw, label) {
+export function normalizeEvidenceRefs(raw, label, projectRoot = process.cwd()) {
     if (!Array.isArray(raw))
         die(`${label} must be an array`);
     return raw.map((ref) => {
@@ -2470,7 +2494,7 @@ export function normalizeEvidenceRefs(raw, label) {
             die(`${label} entries must be structured evidence reference objects; legacy string refs are not supported`);
         if (!ref || typeof ref !== "object" || Array.isArray(ref))
             die(`${label} entries must be objects`);
-        return validateEvidenceRef({ ...ref }, label);
+        return validateEvidenceRef({ ...ref }, label, projectRoot);
     });
 }
 function canonicalProjectRootForSession(dir) {
@@ -2484,14 +2508,180 @@ function canonicalProjectRootForSession(dir) {
         die("gate evidence project root must be a non-symlink directory");
     return projectRoot;
 }
+// #619: the narrative isolation guard must run for EVERY session layout (canonical,
+// tmp, or legacy .flow-agents/) without imposing the canonical-session requirement that
+// canonicalProjectRootForSession enforces. It only needs a best-effort project root to
+// resolve relative evidence paths; the namespace regex and content-shape checks are
+// location-independent. It mirrors canonicalProjectRootForSession's path computation for a
+// canonical .kontourai/flow-agents/<slug> session (project root is three levels up), handles
+// the legacy .flow-agents/<slug> layout (two levels up), and never dies on any layout.
+function narrativeGuardRoot(dir) {
+    const artifactRoot = path.dirname(dir);
+    const parentRoot = path.dirname(artifactRoot);
+    if (path.basename(artifactRoot) === "flow-agents" && path.basename(parentRoot) === ".kontourai") {
+        return path.dirname(parentRoot);
+    }
+    if (path.basename(artifactRoot) === ".flow-agents") {
+        return parentRoot;
+    }
+    // Unknown/tmp layout: best-effort. Relative-path resolution may be imperfect, but the
+    // namespace regex and content-shape checks are location-independent, so the isolation
+    // guarantee holds regardless.
+    return artifactRoot;
+}
 function pathIsWithinRoot(candidate, root) {
     const relative = path.relative(root, candidate);
     return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
 }
+export const NARRATIVE_TRUST_ISOLATION_DIAGNOSTIC = "narrative trust isolation (#619): narrative namespace artifacts cannot be used as workflow evidence";
+function decodeNarrativeReference(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value;
+    }
+}
+function realpathWithExistingPrefix(candidate) {
+    let cursor = path.resolve(candidate);
+    const suffix = [];
+    while (!fs.existsSync(cursor)) {
+        const parent = path.dirname(cursor);
+        if (parent === cursor)
+            break;
+        suffix.unshift(path.basename(cursor));
+        cursor = parent;
+    }
+    let canonical = cursor;
+    try {
+        canonical = (fs.realpathSync.native ?? fs.realpathSync)(cursor);
+    }
+    catch { /* resolved lexical prefix is the fallback */ }
+    return path.resolve(canonical, ...suffix);
+}
+export function isNarrativeNamespacePath(projectRoot, resolvedPath) {
+    const decoded = decodeNarrativeReference(resolvedPath);
+    const normalized = decoded.replaceAll("\\", "/").toLowerCase();
+    if (/(?:^|[^a-z0-9._-])\.kontourai(?:\/[^/\s"'`]+)*\/narrative(?:$|[/\s"'`])/.test(normalized))
+        return true;
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(decoded) && !decoded.toLowerCase().startsWith("file://"))
+        return false;
+    let local = decoded;
+    if (decoded.toLowerCase().startsWith("file://")) {
+        try {
+            local = fileURLToPath(decoded);
+        }
+        catch {
+            return false;
+        }
+    }
+    const canonicalRoot = realpathWithExistingPrefix(path.resolve(projectRoot, NARRATIVE_NAMESPACE_ROOT)).toLowerCase();
+    const candidate = realpathWithExistingPrefix(path.resolve(projectRoot, local)).toLowerCase();
+    return pathIsWithinRoot(candidate, canonicalRoot);
+}
+export function isNarrativeArtifactContent(fileBytes) {
+    const text = Buffer.isBuffer(fileBytes) ? fileBytes.toString("utf8") : fileBytes;
+    try {
+        const parsed = JSON.parse(text);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return false;
+        const value = parsed;
+        if (value.schema_version === "grounded-execution-narrative/v1")
+            return true;
+        if (value.schema_version === "grounded-runtime-projection/v1")
+            return true;
+        if (value.schema_version === "1.0"
+            && hasNonEmptyString(value.narrative_id)
+            && hasNonEmptyString(value.captured_at)
+            && value.compiler && typeof value.compiler === "object"
+            && value.capture_completeness && typeof value.capture_completeness === "object"
+            && Array.isArray(value.sources))
+            return true;
+        return false;
+    }
+    catch {
+        return text.includes("flow-agents-narrative-composer")
+            && text.includes("# Grounded Execution Narrative")
+            && text.includes("## Authority provenance");
+    }
+}
+function localPathTokens(value) {
+    const decoded = decodeNarrativeReference(value);
+    const tokens = decoded.match(/(?:file:\/\/[^\s"'`]+)|(?:[A-Za-z]:[\\/][^\s"'`]+)|(?:\.{0,2}[\\/][^\s"'`]+)|(?:[^\s"'`]+[\\/][^\s"'`]+)/g) ?? [];
+    return tokens.map((token) => token.replace(/^[([{<]+/, "").replace(/[\])}>;,]+$/, ""));
+}
+function referencesComposedNarrativePath(projectRoot, value) {
+    const decoded = decodeNarrativeReference(value);
+    const folded = decoded.replaceAll("\\", "/").toLowerCase();
+    if (folded.includes(".kontourai/narrative"))
+        return true;
+    // Static shell inspection cannot decide arbitrary runtime variable composition such as
+    // `base=.kontourai; test -f "$base/narrative/..."`. The compensating invariant is that a
+    // command check persists only its command plus exit/observed-output digest; it never reads file
+    // bytes into trust.bundle. Every channel that DOES materialize a file is independently guarded
+    // by canonical path and narrative content shape. Keep that invariant covered end-to-end.
+    const cdPattern = /(?:^|[;&|]\s*)cd\s+(?:"([^"]+)"|'([^']+)'|([^\s;&|]+))\s*&&([\s\S]*)/gi;
+    for (const match of decoded.matchAll(cdPattern)) {
+        const cdTarget = match[1] ?? match[2] ?? match[3] ?? "";
+        const remainder = (match[4] ?? "").replaceAll("\\", "/").toLowerCase();
+        if (!/(?:^|[^a-z0-9._-])narrative\//.test(remainder))
+            continue;
+        const canonicalTarget = realpathWithExistingPrefix(path.resolve(projectRoot, decodeNarrativeReference(cdTarget)))
+            .replaceAll("\\", "/")
+            .toLowerCase();
+        const canonicalKontourai = realpathWithExistingPrefix(path.resolve(projectRoot, ".kontourai"))
+            .replaceAll("\\", "/")
+            .toLowerCase();
+        if (canonicalTarget === canonicalKontourai
+            || canonicalTarget.startsWith(`${canonicalKontourai}/`)
+            || /(?:^|\/)\.kontourai(?:\/|$)/.test(canonicalTarget))
+            return true;
+    }
+    return false;
+}
+function narrativeCandidateFile(projectRoot, raw) {
+    let decoded = decodeNarrativeReference(raw);
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(decoded)) {
+        if (!decoded.toLowerCase().startsWith("file://"))
+            return null;
+        try {
+            decoded = fileURLToPath(decoded);
+        }
+        catch {
+            return null;
+        }
+    }
+    const candidate = path.isAbsolute(decoded) ? decoded : path.resolve(projectRoot, decoded);
+    try {
+        const canonical = (fs.realpathSync.native ?? fs.realpathSync)(candidate);
+        const stat = fs.statSync(canonical);
+        return stat.isFile() ? canonical : null;
+    }
+    catch {
+        return null;
+    }
+}
+function rejectNarrativeReference(projectRoot, value, label) {
+    if (typeof value !== "string")
+        return;
+    const decoded = decodeNarrativeReference(value);
+    if (referencesComposedNarrativePath(projectRoot, decoded))
+        die(`${label}: ${NARRATIVE_TRUST_ISOLATION_DIAGNOSTIC}`);
+    const candidates = [decoded, ...localPathTokens(decoded)];
+    for (const candidate of new Set(candidates)) {
+        if (isNarrativeNamespacePath(projectRoot, candidate))
+            die(`${label}: ${NARRATIVE_TRUST_ISOLATION_DIAGNOSTIC}`);
+        const file = narrativeCandidateFile(projectRoot, candidate);
+        if (file && isNarrativeArtifactContent(fs.readFileSync(file))) {
+            die(`${label}: ${NARRATIVE_TRUST_ISOLATION_DIAGNOSTIC}`);
+        }
+    }
+}
 function validateLocalEvidenceFile(projectRoot, raw, label) {
     const candidate = path.resolve(projectRoot, raw);
     if (!pathIsWithinRoot(candidate, projectRoot))
         die(`${label} must remain inside the canonical project root`);
+    rejectNarrativeReference(projectRoot, raw, label);
     let stat;
     try {
         stat = fs.lstatSync(candidate);
@@ -2509,6 +2699,12 @@ function globMatches(pattern, relative) {
     const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replaceAll("**", "::GLOBSTAR::").replaceAll("*", "[^/]*").replaceAll("::GLOBSTAR::", ".*");
     return new RegExp(`^${escaped}$`).test(relative);
 }
+export function rejectOperationBoundExpectation(expectationId, operation) {
+    const completion = operation === NARRATIVE_PROMOTE_OPERATION
+        ? "authenticated external narrative provider completion"
+        : "authenticated external ChangeProvider completion";
+    die(`record-gate-claim cannot satisfy operation-bound expectation ${expectationId}; ${operation} requires ${completion}`);
+}
 function expectedGateProducer(flowId, stepId, expectationId) {
     const manifest = loadJson(path.join(flowAgentsPackageRoot(), "kits", "builder", "kit.json"));
     const actions = Array.isArray(manifest.flow_step_actions) ? manifest.flow_step_actions : [];
@@ -2520,7 +2716,7 @@ function expectedGateProducer(flowId, stepId, expectationId) {
         : undefined;
     if (binding?.interface === "operation") {
         const operation = typeof binding.operation === "string" ? binding.operation : "the declared external operation";
-        die(`record-gate-claim cannot satisfy operation-bound expectation ${expectationId}; ${operation} requires authenticated external ChangeProvider completion`);
+        rejectOperationBoundExpectation(expectationId, operation);
     }
     const skills = Array.isArray(action.skills) ? action.skills.filter((value) => typeof value === "string") : [];
     const roles = Array.isArray(manifest.skill_roles) ? manifest.skill_roles : [];
@@ -2775,6 +2971,131 @@ async function normalizeObservedCommands(commands, projectRoot, requireTestInten
         die("every --command requires a corresponding --observed-command-json");
     return commands.map((command) => byCommand.get(command));
 }
+// #634: the canonical writer's own execution is a first-class observation. On hosts whose
+// PostToolUse capture never surfaces exit codes, every hook-captured entry is "ambiguous",
+// the independent capture can never confirm a pass, and the verify gate dead-ends. The writer
+// just ran the command itself — a real process exit, not an inference — so it appends that
+// observation to the SAME hash-chained command-log, under the SAME lock protocol the capture
+// hook uses, visibly attributed via source: "canonical-writer-execution". Precedence stays
+// honest in the fold (reduceCaptureLogByCommand): any observed fail beats any pass, so a
+// writer pass can lift ambiguity but can never bury a hook-observed failure. The append is
+// fail-open with a stderr note: losing the supplementary observation must never fail the
+// gate-claim write itself. Decision record: docs/decisions/writer-observed-execution.md.
+export const WRITER_OBSERVATION_SOURCE = "canonical-writer-execution";
+const WRITER_LOCK_RETRY_MS = 5;
+const WRITER_LOCK_MAX_TRIES = 200;
+const WRITER_LOCK_STALE_MS = 10000;
+function loadCommandLogChain() {
+    const _req = createRequire(import.meta.url);
+    const chainPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../scripts/lib/command-log-chain.js");
+    return _req(chainPath);
+}
+function writerSleepSync(ms) {
+    try {
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+    }
+    catch { /* SharedArrayBuffer/Atomics unavailable — skip the backoff */ }
+}
+function writerAcquireLock(lockFile) {
+    for (let i = 0; i < WRITER_LOCK_MAX_TRIES; i++) {
+        try {
+            const fd = fs.openSync(lockFile, "wx");
+            try {
+                fs.writeSync(fd, String(process.pid));
+            }
+            catch { /* pid is advisory only */ }
+            return fd;
+        }
+        catch (err) {
+            if (!err || err.code !== "EEXIST")
+                return null;
+            try {
+                const st = fs.statSync(lockFile);
+                if (Date.now() - st.mtimeMs > WRITER_LOCK_STALE_MS) {
+                    fs.unlinkSync(lockFile);
+                    continue;
+                }
+            }
+            catch {
+                continue;
+            }
+            writerSleepSync(WRITER_LOCK_RETRY_MS);
+        }
+    }
+    return null;
+}
+function writerReadLastChainState(logFile, genesis) {
+    let raw = "";
+    try {
+        raw = fs.readFileSync(logFile, "utf8");
+    }
+    catch {
+        return { seq: -1, hash: genesis };
+    }
+    const lines = raw.split("\n").filter((l) => l.trim());
+    for (let i = lines.length - 1; i >= 0; i--) {
+        let entry;
+        try {
+            entry = JSON.parse(lines[i]);
+        }
+        catch {
+            continue;
+        }
+        if (entry && entry._chain && typeof entry._chain.hash === "string" && typeof entry._chain.seq === "number") {
+            return { seq: entry._chain.seq, hash: entry._chain.hash };
+        }
+    }
+    return { seq: -1, hash: genesis };
+}
+export function appendWriterObservedCommands(dir, observed, timestamp) {
+    if (observed.length === 0)
+        return;
+    try {
+        const chain = loadCommandLogChain();
+        const logFile = path.join(dir, "command-log.jsonl");
+        const lockFile = `${logFile}.lock`;
+        const fd = writerAcquireLock(lockFile);
+        try {
+            let { seq, hash: prevHash } = writerReadLastChainState(logFile, chain.CHAIN_GENESIS);
+            const lines = [];
+            for (const entry of observed) {
+                const record = {
+                    command: entry.command,
+                    observedResult: entry.exit_code === 0 ? "pass" : "fail",
+                    exitCode: entry.exit_code,
+                    capturedAt: timestamp,
+                    source: WRITER_OBSERVATION_SOURCE,
+                    writer: {
+                        output_sha256: entry.output_sha256,
+                        ...(Number.isSafeInteger(entry.test_count) ? { test_count: entry.test_count } : {}),
+                        ...(entry.execution_proof ? { execution_proof: entry.execution_proof } : {}),
+                    },
+                };
+                seq += 1;
+                const hashValue = chain.computeChainHash(prevHash, record);
+                record._chain = { seq, prevHash, hash: hashValue };
+                prevHash = hashValue;
+                lines.push(JSON.stringify(record));
+            }
+            fs.appendFileSync(logFile, `${lines.join("\n")}\n`);
+        }
+        finally {
+            if (fd !== null) {
+                try {
+                    fs.closeSync(fd);
+                }
+                catch { /* closed */ }
+                try {
+                    fs.unlinkSync(lockFile);
+                }
+                catch { /* removed */ }
+            }
+        }
+    }
+    catch (error) {
+        process.stderr.write(`[record-gate-claim] writer observation append failed (fail-open, capture unaffected): ${error instanceof Error ? error.message : String(error)}\n`);
+    }
+}
 function requireObservedCommandRefs(refs, observedCommands, label, requireAll = false) {
     const commandRefs = refs.filter((ref) => ref.kind === "command");
     if (commandRefs.length === 0)
@@ -2789,7 +3110,7 @@ function requireObservedCommandRefs(refs, observedCommands, label, requireAll =
             die(`${label} requires a top-level command evidence ref for every successful observed command`);
     }
 }
-function completePassingCriteria(existing, raw, observedCommands, verifiedAt) {
+function completePassingCriteria(existing, raw, observedCommands, verifiedAt, projectRoot) {
     if (raw.length === 0)
         die("record-gate-claim requires --criterion-json for a passing tests-evidence claim");
     const incoming = raw.map((value) => parseJson(value, "--criterion-json"));
@@ -2804,21 +3125,24 @@ function completePassingCriteria(existing, raw, observedCommands, verifiedAt) {
     if (new Set(ids).size !== ids.length || ids.length !== expectedIds.length || ids.some((id) => !expectedIds.includes(id))) {
         die(`--criterion-json must cover every declared acceptance criterion exactly once (expected: ${expectedIds.join(", ") || "none"}; received: ${ids.join(", ") || "none"})`);
     }
+    const observedCommandNames = new Set(observedCommands.map((observation) => observation.command));
     return incoming.map((criterion, index) => {
         if (Object.keys(criterion).some((key) => !["id", "status", "evidence_refs"].includes(key)))
             die(`criterion ${ids[index]} may update only id, status, and evidence_refs`);
         if (criterion.status !== "pass")
             die(`criterion ${ids[index]} must have status pass for a passing tests-evidence claim`);
-        const refs = normalizeEvidenceRefs(criterion.evidence_refs, `criterion ${ids[index]} evidence_refs`);
+        const refs = normalizeEvidenceRefs(criterion.evidence_refs, `criterion ${ids[index]} evidence_refs`, projectRoot);
         if (refs.length === 0)
             die(`criterion ${ids[index]} requires reviewable evidence_refs`);
-        requireObservedCommandRefs(refs, observedCommands, `criterion ${ids[index]}`);
-        return { ...expectedById.get(ids[index]), status: "pass", evidence_refs: refs, identity_version: 2, verified_at: verifiedAt };
+        requireObservedCommandRefs(refs, observedCommandNames, `criterion ${ids[index]}`);
+        const referencedCommands = new Set(refs.filter((ref) => ref.kind === "command").map(commandFromEvidenceRef));
+        const criterionObservedCommands = observedCommands.filter((observation) => referencedCommands.has(observation.command));
+        return markCanonicallyObservedCriterion({ ...expectedById.get(ids[index]), status: "pass", evidence_refs: refs, identity_version: 2, verified_at: verifiedAt, _observed_commands: criterionObservedCommands });
     });
 }
 const critiqueStatuses = new Set(WORKFLOW_CRITIQUE_STATUSES);
 const safeCritiqueId = /^[a-z][a-z0-9_-]*$/;
-function normalizeCritiqueLanes(raw) {
+function normalizeCritiqueLanes(raw, projectRoot) {
     if (raw.length === 0)
         die("record-critique requires at least one --lane-json");
     const lanes = raw.map((value, index) => {
@@ -2832,7 +3156,7 @@ function normalizeCritiqueLanes(raw) {
             die(`--lane-json ${index} status must be one of: pass, fail, not_verified`);
         if (!hasNonEmptyString(lane.summary))
             die(`--lane-json ${index} summary must be non-empty`);
-        const evidenceRefs = normalizeEvidenceRefs(lane.evidence_refs, `--lane-json ${index} evidence_refs`);
+        const evidenceRefs = normalizeEvidenceRefs(lane.evidence_refs, `--lane-json ${index} evidence_refs`, projectRoot);
         if (evidenceRefs.length === 0)
             die(`--lane-json ${index} requires structured reviewable evidence_refs`);
         return { id: lane.id, status: lane.status, summary: lane.summary, evidence_refs: evidenceRefs };
@@ -2851,6 +3175,13 @@ function reviewTargetArtifacts(dir, rawPaths, label) {
     return files.map((file) => ({ file, sha256: createHash("sha256").update(fs.readFileSync(path.join(projectRoot, file))).digest("hex") }));
 }
 function reviewTargetArtifactsMatch(dir, reviewTarget) {
+    if (reviewTarget && typeof reviewTarget === "object" && !Array.isArray(reviewTarget)) {
+        const projectRoot = narrativeGuardRoot(dir);
+        const artifacts = reviewTarget.artifacts;
+        if (Array.isArray(artifacts)) {
+            artifacts.forEach((artifact, index) => rejectNarrativeReference(projectRoot, artifact?.file, `critique review_target artifact ${index}`));
+        }
+    }
     try {
         if (!reviewTarget || typeof reviewTarget !== "object" || Array.isArray(reviewTarget))
             return false;
@@ -2925,7 +3256,7 @@ function critiqueIsCleanAndCurrent(dir, critique) {
 // BEFORE normalizeCheck runs — see applyGateClaimStamp). This does not weaken new-mint
 // enforcement: a NOVEL gate-claim-* id (not already present at all) is still rejected exactly as
 // before, and superseding a STAMPED existing id is now rejected too.
-export function normalizeCheck(raw, allowGateClaimPrefix = false, existingCheckStampById) {
+export function normalizeCheck(raw, allowGateClaimPrefix = false, existingCheckStampById, projectRoot = process.cwd()) {
     const check = { ...raw };
     if (!check.id || !check.kind || !check.status || !check.summary)
         die("check requires id, kind, status, and summary");
@@ -2940,18 +3271,21 @@ export function normalizeCheck(raw, allowGateClaimPrefix = false, existingCheckS
         die("kind must be one of: build, types, lint, test, command, security, diff, browser, runtime, policy, external");
     if (!checkStatuses.has(check.status))
         die("status must be one of: pass, fail, not_verified, skip");
+    rejectNarrativeReference(projectRoot, check.command, `check ${String(check.id)} command`);
     validateRunnableCheckCommand(check, `check ${String(check.id)}`);
     if (Array.isArray(check.standard_refs))
-        for (const ref of check.standard_refs)
+        for (const ref of check.standard_refs) {
             if (!["junit", "sarif", "coverage", "veritas"].includes(ref.standard))
                 die("standard must be one of");
+            rejectNarrativeReference(projectRoot, ref.ref, `check ${String(check.id)} standard_ref`);
+        }
     if (check.artifact_refs)
-        check.artifact_refs = normalizeEvidenceRefs(check.artifact_refs, "artifact_refs");
+        check.artifact_refs = normalizeEvidenceRefs(check.artifact_refs, "artifact_refs", projectRoot);
     if (check.surface_trust_refs)
-        check.surface_trust_refs = normalizeSurfaceRefs(check.surface_trust_refs);
+        check.surface_trust_refs = normalizeSurfaceRefs(check.surface_trust_refs, projectRoot);
     return check;
 }
-function normalizeSurfaceRefs(refs) {
+function normalizeSurfaceRefs(refs, projectRoot) {
     if (!Array.isArray(refs))
         die("surface_trust_refs must be an array");
     // Use the cached @kontourai/surface module for advisory inline validation of referenced
@@ -2964,6 +3298,7 @@ function normalizeSurfaceRefs(refs) {
             if (key.toLowerCase().includes("veritas"))
                 die(`unsupported field in Surface trust ref: ${key}`);
         const out = { ...ref };
+        rejectNarrativeReference(projectRoot, out.artifact_ref, "surface trust artifact_ref");
         // trust.bundle is the canonical Hachure-aligned artifact kind; TrustReport/Trust Snapshot are legacy aliases
         if (!["trust.bundle", "TrustReport", "Trust Snapshot"].includes(out.artifact_kind))
             die("artifact_kind must be one of: trust.bundle, TrustReport, Trust Snapshot");
@@ -3048,17 +3383,19 @@ export function kitIdentityFromBundle(raw, bundleFile) {
     // 3. Genuinely unknown — never fallback to "builder".
     return { claimType: "unknown.trust.bundle", kitId: "unknown", subject: "unknown-kit", gateId: "unknown.trust.bundle" };
 }
-function surfaceCheckFromArtifact(file, index) {
-    const raw = JSON.parse(read(file));
+function surfaceCheckFromArtifact(file, index, projectRoot = process.cwd()) {
+    rejectNarrativeReference(projectRoot, file, `--surface-trust-json ${index}`);
+    const resolvedFile = path.isAbsolute(file) ? file : path.resolve(projectRoot, decodeNarrativeReference(file));
+    const raw = JSON.parse(read(resolvedFile));
     const lower = JSON.stringify(raw).toLowerCase();
     // Structurally read kit identity from the bundle — never hardcode "builder".
-    const { claimType: bundleClaimType, subject: bundleSubject, gateId: bundleGateId } = kitIdentityFromBundle(raw, file);
+    const { claimType: bundleClaimType, subject: bundleSubject, gateId: bundleGateId } = kitIdentityFromBundle(raw, resolvedFile);
     let ref;
     if (lower.includes("provider") && lower.includes("absent")) {
-        ref = { artifact_kind: "trust.bundle", artifact_ref: file, gate_id: "provider.unavailable", claim_type: bundleClaimType, claim_status: "unknown", subject: bundleSubject, freshness: { status: "unknown", summary: "No trust provider is configured" }, authority: { producer: "unknown", summary: "No trust provider is configured" }, integrity: { status: "unknown", summary: "Unknown" }, status: "not_verified", summary: "No trust provider is configured" };
+        ref = { artifact_kind: "trust.bundle", artifact_ref: resolvedFile, gate_id: "provider.unavailable", claim_type: bundleClaimType, claim_status: "unknown", subject: bundleSubject, freshness: { status: "unknown", summary: "No trust provider is configured" }, authority: { producer: "unknown", summary: "No trust provider is configured" }, integrity: { status: "unknown", summary: "Unknown" }, status: "not_verified", summary: "No trust provider is configured" };
     }
     else if (lower.includes("artifact") && lower.includes("absent")) {
-        ref = { artifact_kind: "trust.bundle", artifact_ref: file, gate_id: "artifact.unavailable", claim_type: bundleClaimType, claim_status: "unknown", subject: bundleSubject, freshness: { status: "unknown", summary: "Artifact not readable" }, authority: { producer: "unknown", summary: "Artifact not readable" }, integrity: { status: "unknown", summary: "Artifact not readable" }, status: "not_verified", summary: "artifact not readable" };
+        ref = { artifact_kind: "trust.bundle", artifact_ref: resolvedFile, gate_id: "artifact.unavailable", claim_type: bundleClaimType, claim_status: "unknown", subject: bundleSubject, freshness: { status: "unknown", summary: "Artifact not readable" }, authority: { producer: "unknown", summary: "Artifact not readable" }, integrity: { status: "unknown", summary: "Artifact not readable" }, status: "not_verified", summary: "artifact not readable" };
     }
     else {
         const claimStatus = lower.includes("rejected") ? "rejected" : "accepted";
@@ -3066,7 +3403,7 @@ function surfaceCheckFromArtifact(file, index) {
         const producer = lower.includes("missing-authority") ? "unknown" : "surface-local";
         const integrity = lower.includes("mismatch") ? "mismatch" : "matched";
         // Use trust.bundle as the canonical Hachure-aligned artifact_kind for all trust-backed evidence refs
-        ref = { artifact_kind: "trust.bundle", artifact_ref: file, gate_id: bundleGateId, claim_type: bundleClaimType, claim_status: claimStatus, subject: bundleSubject, freshness: { status: freshness, summary: freshness === "fresh" ? "fresh" : "not currently verifiable" }, authority: { producer, summary: producer === "unknown" ? "missing authority" : "Local Surface trust producer." }, integrity: { status: integrity, summary: integrity === "matched" ? "matched" : "integrity mismatch" } };
+        ref = { artifact_kind: "trust.bundle", artifact_ref: resolvedFile, gate_id: bundleGateId, claim_type: bundleClaimType, claim_status: claimStatus, subject: bundleSubject, freshness: { status: freshness, summary: freshness === "fresh" ? "fresh" : "not currently verifiable" }, authority: { producer, summary: producer === "unknown" ? "missing authority" : "Local Surface trust producer." }, integrity: { status: integrity, summary: integrity === "matched" ? "matched" : "integrity mismatch" } };
         ref.status = deriveSurfaceStatus(ref);
         ref.summary = ref.status === "pass" ? "accepted" : ref.status === "not_verified" ? "not currently verifiable" : (claimStatus === "rejected" ? "rejected" : producer === "unknown" ? "missing authority" : "integrity mismatch");
     }
@@ -3084,9 +3421,10 @@ function surfaceCheckFromArtifact(file, index) {
  * not the first thing an agent reaches for.
  */
 function validateAcceptanceEvidenceRefs(dir, p) {
-    if (p?.flags.has("skip-evidence-ref-runnability-guard")) {
+    const projectRoot = narrativeGuardRoot(dir);
+    const skipRunnabilityGuard = p?.flags.has("skip-evidence-ref-runnability-guard") ?? false;
+    if (skipRunnabilityGuard) {
         process.stderr.write("[record-evidence] evidence-ref runnability guard skipped via --skip-evidence-ref-runnability-guard\n");
-        return;
     }
     const file = path.join(dir, "acceptance.json");
     if (!fs.existsSync(file))
@@ -3098,7 +3436,9 @@ function validateAcceptanceEvidenceRefs(dir, p) {
     data.criteria.forEach((criterion, index) => {
         if (criterion.evidence_refs === undefined)
             return;
-        const refs = normalizeEvidenceRefs(criterion.evidence_refs, `acceptance.criteria[${index}].evidence_refs`);
+        const refs = normalizeEvidenceRefs(criterion.evidence_refs, `acceptance.criteria[${index}].evidence_refs`, projectRoot);
+        if (skipRunnabilityGuard)
+            return;
         // #412 (AC8): a kind:"command" ref's command source (excerpt, falling back to url when that
         // is where the command string lives) must be a literally runnable shell command, not prose
         // describing a manual verification step — reject at RECORD time instead of letting it reach
@@ -3170,8 +3510,15 @@ function requireStampedClaim(claim, dir) {
     }
     return origin;
 }
+function loadTrustBundleForTrustMachinery(dir) {
+    const bundleFile = path.join(dir, "trust.bundle");
+    if (fs.existsSync(bundleFile) && isNarrativeArtifactContent(fs.readFileSync(bundleFile))) {
+        die(`trust.bundle in ${dir}: ${NARRATIVE_TRUST_ISOLATION_DIAGNOSTIC}; restore a genuine trust.bundle and keep rendered narratives under ${NARRATIVE_NAMESPACE_ROOT}`);
+    }
+    return loadJson(bundleFile);
+}
 function checksFromBundle(dir) {
-    const bundle = loadJson(path.join(dir, "trust.bundle"));
+    const bundle = loadTrustBundleForTrustMachinery(dir);
     const allClaims = Array.isArray(bundle.claims) ? bundle.claims : [];
     // Validate stamps on every claim up front — any unstamped claim anywhere in the bundle marks
     // it pre-supersession, regardless of whether it is check/acceptance/critique-typed.
@@ -3395,10 +3742,20 @@ function readBundleState(dir) {
     const acceptance = loadJson(path.join(dir, "acceptance.json"));
     const bundledCriteria = criteriaFromBundle(dir);
     const acceptedCriteria = Array.isArray(acceptance.criteria) ? acceptance.criteria : [];
+    if (acceptedCriteria.some((criterion) => !hasNonEmptyString(criterion?.id) || !hasNonEmptyString(criterion?.description))) {
+        die("acceptance.json contains a criterion without a non-empty id and description — refusing to rebuild trust.bundle without durable acceptance identity");
+    }
+    const acceptedIds = acceptedCriteria.map((criterion) => String(criterion.id));
+    if (new Set(acceptedIds).size !== acceptedIds.length) {
+        die("acceptance.json criterion ids must be unique — refusing to rebuild trust.bundle with ambiguous acceptance identity");
+    }
     const contractSignature = (criteria) => JSON.stringify(criteria.map((criterion) => ({
         id: criterion.id ?? null,
         description: criterion.description ?? null,
     })));
+    // Planning may establish or refine a valid criterion contract after session startup. Once the
+    // signatures agree, the bundle remains authoritative for verified status and observed-command
+    // provenance; artifact status edits alone cannot manufacture completion.
     const criteria = acceptedCriteria.length > 0 && contractSignature(acceptedCriteria) !== contractSignature(bundledCriteria)
         ? acceptedCriteria
         : (bundledCriteria.length > 0 ? bundledCriteria : acceptedCriteria);
@@ -3426,7 +3783,7 @@ function mergeChecksById(existing, incoming) {
     return [...byId.values()];
 }
 function critiquesFromBundle(dir) {
-    const bundle = loadJson(path.join(dir, "trust.bundle"));
+    const bundle = loadTrustBundleForTrustMachinery(dir);
     if (!Array.isArray(bundle.claims))
         return [];
     for (const c of bundle.claims)
@@ -3453,7 +3810,7 @@ function critiquesFromBundle(dir) {
     });
 }
 function criteriaFromBundle(dir) {
-    const bundle = loadJson(path.join(dir, "trust.bundle"));
+    const bundle = loadTrustBundleForTrustMachinery(dir);
     if (!Array.isArray(bundle.claims))
         return [];
     for (const claim of bundle.claims)
@@ -3463,14 +3820,28 @@ function criteriaFromBundle(dir) {
         .map((claim) => {
         const md = claim.metadata && typeof claim.metadata === "object" && !Array.isArray(claim.metadata) ? claim.metadata : {};
         const saved = md.criterion && typeof md.criterion === "object" && !Array.isArray(md.criterion) ? md.criterion : {};
-        return {
+        const criterion = {
             id: typeof saved.id === "string" ? saved.id : String(claim.subjectId || "").split("/").pop(),
             description: typeof saved.description === "string" ? saved.description : (claim.fieldOrBehavior || ""),
             status: typeof saved.status === "string" ? saved.status : (claim.value ?? "not_verified"),
             evidence_refs: Array.isArray(saved.evidence_refs) ? saved.evidence_refs : [],
+            ...(Array.isArray(saved.observed_commands) ? { _observed_commands: saved.observed_commands } : {}),
             ...(typeof saved.verified_at === "string" ? { verified_at: saved.verified_at } : {}),
             ...(saved.identity_version === 2 ? { identity_version: 2 } : {}),
         };
+        const observedCommands = Array.isArray(saved.observed_commands) ? saved.observed_commands : [];
+        const evidence = Array.isArray(bundle.evidence) ? bundle.evidence.filter((item) => item?.claimId === claim.id) : [];
+        const event = Array.isArray(bundle.events) ? bundle.events.find((item) => item?.claimId === claim.id && item.status === "verified") : null;
+        const evidenceIds = new Set(evidence.map((item) => item.id));
+        const hasCanonicalEvidence = claim.value === "pass"
+            && claim.status === "verified"
+            && observedCommands.length > 0
+            && evidence.length === observedCommands.length
+            && evidence.every((item) => item.evidenceType === "test_output" && item.passing === true && observedCommands.some((observation) => observation.command === item.execution?.label))
+            && Array.isArray(event?.evidenceIds)
+            && event.evidenceIds.length === evidenceIds.size
+            && event.evidenceIds.every((id) => evidenceIds.has(id));
+        return hasCanonicalEvidence ? markCanonicallyObservedCriterion(criterion) : criterion;
     })
         .filter((criterion) => typeof criterion.id === "string" && criterion.id.length > 0);
 }
@@ -3508,7 +3879,11 @@ async function recordEvidence(p) {
     // (not re-read) as _existingState for the compose-safe merge — one readBundleState call.
     const _existingState = readBundleState(dir);
     const _existingCheckStampById = existingCheckStampMap(_existingState.checks);
-    const _checksRaw = [...opts(p, "check-json").map((v) => normalizeCheck(parseJson(v, "--check-json"), false, _existingCheckStampById)), ...opts(p, "surface-trust-json").map(surfaceCheckFromArtifact)];
+    const projectRoot = narrativeGuardRoot(dir);
+    const _checksRaw = [
+        ...opts(p, "check-json").map((v) => normalizeCheck(parseJson(v, "--check-json"), false, _existingCheckStampById, projectRoot)),
+        ...opts(p, "surface-trust-json").map((file, index) => surfaceCheckFromArtifact(file, index, projectRoot)),
+    ];
     // WS8 (AC4, iteration 2): a command-backed check reconciles against CI or fails — it can
     // NEVER be waived. Reject --accepted-gap-reason/--waived-by on any check whose evidence
     // classifies as test_output (build/types/lint/test/command, and security/browser/runtime
@@ -3600,6 +3975,7 @@ async function recordCheck(p, commandArgv) {
     if (commandArgv?.length && commandString)
         die("record-check: pass the command via EITHER `-- <command...>` OR --command, not both");
     const repoRoot = findRepoRootFromDir(dir);
+    rejectNarrativeReference(repoRoot, commandArgv?.join(" ") ?? commandString, "record-check command");
     let displayCommand;
     let exitCode;
     let stdout = "";
@@ -3681,7 +4057,7 @@ ${stderr}` : ""}`.trim());
         status,
         summary,
         command: displayCommand,
-    }, false, _existingCheckStampById);
+    }, false, _existingCheckStampById, repoRoot);
     if (outputSha256)
         check._output_sha256 = outputSha256;
     const _mergedChecks = mergeChecksById(_existingState.checks, [check]);
@@ -3792,10 +4168,20 @@ async function recordGateClaim(p) {
     const observedCommandRaw = opts(p, "observed-command-json");
     if (mustRunTests && gateCommands.length === 0)
         die("record-gate-claim requires at least one --command for a passing tests-evidence claim");
-    const projectRoot = gateCommands.length > 0 ? canonicalProjectRootForSession(dir) : null;
+    // #619: the narrative evidence-ref guards (validateEvidenceRef / normalizeCheck /
+    // completePassingCriteria) need a non-null, location-independent project root that never
+    // dies on a non-canonical session. normalizeObservedCommands still requires the strict
+    // canonical root, but only when there are commands to normalize.
+    const projectRoot = narrativeGuardRoot(dir);
+    const canonicalRoot = gateCommands.length > 0 ? canonicalProjectRootForSession(dir) : null;
+    for (const command of gateCommands)
+        rejectNarrativeReference(projectRoot, command, "record-gate-claim command");
     const observedCommands = gateCommands.length > 0
-        ? await normalizeObservedCommands(gateCommands, projectRoot, mustRunTests, statusVal)
+        ? await normalizeObservedCommands(gateCommands, canonicalRoot, mustRunTests, statusVal)
         : [];
+    // #634: persist the writer's real executions into the hash-chained command-log so the
+    // capture fold has a deterministic observation even on exit-code-blind hosts.
+    appendWriterObservedCommands(dir, observedCommands, ts);
     const observedCommandNames = new Set(observedCommands.map((entry) => entry.command));
     let outputSha256 = null;
     if (!mustRunTests && gateCommands.length > 1)
@@ -3826,7 +4212,7 @@ async function recordGateClaim(p) {
         ...(routeReason ? { _gate_claim_route_reason: routeReason } : {}),
     };
     // Include structured evidence refs if provided
-    const evidenceRefs = opts(p, "evidence-ref-json").map((v) => validateEvidenceRef(parseJson(v, "--evidence-ref-json"), "--evidence-ref-json"));
+    const evidenceRefs = opts(p, "evidence-ref-json").map((v) => validateEvidenceRef(parseJson(v, "--evidence-ref-json"), "--evidence-ref-json", projectRoot));
     const producer = expectedGateProducer(exactFlowContext?.flowId ?? activeStep.flowId, activeStep.stepId, targetExpectation.id);
     if (statusVal === "pass")
         validateReviewableGateEvidence(dir, slug, evidenceRefs, producer, `gate claim ${targetExpectation.id}`);
@@ -3849,7 +4235,7 @@ async function recordGateClaim(p) {
         check.command = gateCommand;
     if (observedCommands.length > 0)
         check._observed_commands = observedCommands;
-    const checkNormalized = normalizeCheck(check, /* allowGateClaimPrefix */ true);
+    const checkNormalized = normalizeCheck(check, /* allowGateClaimPrefix */ true, undefined, projectRoot);
     if (outputSha256)
         checkNormalized._output_sha256 = outputSha256;
     // WS8 (ADR 0020): honor the accepted-gap waiver flags for a gate claim too.
@@ -3864,7 +4250,7 @@ async function recordGateClaim(p) {
     // SAME expectation id supersedes the earlier check for that expectation (mergeChecksById); a
     // gate claim against a different expectation is additive.
     const _existingState = readBundleState(dir);
-    const criteria = mustRunTests ? completePassingCriteria(_existingState.criteria, opts(p, "criterion-json"), observedCommandNames, ts) : _existingState.criteria;
+    const criteria = mustRunTests ? completePassingCriteria(_existingState.criteria, opts(p, "criterion-json"), observedCommands, ts, projectRoot) : _existingState.criteria;
     if (mustRunTests) {
         const liveCritiques = _existingState.critiques.filter((critique) => !critique.superseded_by);
         if (liveCritiques.length === 0 || liveCritiques.some((critique) => !critiqueIsCleanAndCurrent(dir, critique))) {
@@ -3923,6 +4309,7 @@ async function promote(p) {
     // repo-relative paths when the ref lives under the repo, so the claim is portable.
     const targets = [];
     for (const raw of rawPaths) {
+        rejectNarrativeReference(repoRoot, raw, "promote --evidence-path");
         const abs = path.isAbsolute(raw) ? raw : path.resolve(repoRoot, raw);
         if (!fs.existsSync(abs))
             die(`promote --evidence-path does not exist on disk: ${raw} (resolved: ${abs}). Promotion evidence refs must point at durable docs that were actually written.`);
@@ -4053,21 +4440,27 @@ async function advanceState(p) {
     }
     return 0;
 }
-export function normalizeFinding(raw) {
+export function normalizeFinding(raw, projectRoot = process.cwd()) {
     if (raw.file_refs !== undefined && !Array.isArray(raw.file_refs))
         die("file_refs must be an array");
+    for (const ref of raw.file_refs ?? []) {
+        if (typeof ref !== "string")
+            die("file_refs entries must be strings");
+        rejectNarrativeReference(projectRoot, ref, "finding file_ref");
+    }
     return raw;
 }
 async function recordCritique(p) {
     const dir = artifactDirFrom(p.positional[0] || die("artifact directory is required"));
     const slug = taskSlugFor(dir, opt(p, "task-slug"));
+    const projectRoot = canonicalProjectRootForSession(dir);
     const verdict = opt(p, "verdict");
     if (!critiqueStatuses.has(verdict))
         die("record-critique requires --verdict pass, fail, or not_verified");
     const summary = opt(p, "summary");
     if (!hasNonEmptyString(summary))
         die("record-critique requires --summary");
-    const lanes = normalizeCritiqueLanes(opts(p, "lane-json"));
+    const lanes = normalizeCritiqueLanes(opts(p, "lane-json"), projectRoot);
     const reviewArtifacts = reviewTargetArtifacts(dir, opts(p, "artifact-ref"), "record-critique review_target");
     if (verdict === "pass" && (lanes.some((lane) => lane.status !== "pass") || reviewArtifacts.length === 0)) {
         die("a passing critique requires every lane to pass and at least one local reviewed --artifact-ref");
@@ -4097,10 +4490,10 @@ async function recordCritique(p) {
         lanes,
         review_target: {
             artifacts: reviewArtifacts,
-            workspace_snapshot: captureReviewWorkspaceSnapshot(canonicalProjectRootForSession(dir), reviewArtifacts.map((artifact) => ({ file: String(artifact.file), sha256: String(artifact.sha256) }))),
+            workspace_snapshot: captureReviewWorkspaceSnapshot(projectRoot, reviewArtifacts.map((artifact) => ({ file: String(artifact.file), sha256: String(artifact.sha256) }))),
         },
         artifact_refs: reviewArtifacts.map((artifact) => artifact.file),
-        findings: opts(p, "finding-json").map((v) => normalizeFinding(parseJson(v, "--finding-json"))),
+        findings: opts(p, "finding-json").map((v) => normalizeFinding(parseJson(v, "--finding-json"), projectRoot)),
     };
     if (critique.verdict === "pass" && critique.findings.some((f) => f.status === "open"))
         die("required critique must pass");
@@ -4175,16 +4568,46 @@ async function importCritique(p) {
         die("required critique must pass");
     return result;
 }
+function rejectNarrativeReleaseReferences(projectRoot, value, label, referenceField = false) {
+    if (typeof value === "string") {
+        if (referenceField)
+            rejectNarrativeReference(projectRoot, value, label);
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const entry of value)
+            rejectNarrativeReleaseReferences(projectRoot, entry, label, referenceField);
+        return;
+    }
+    if (!value || typeof value !== "object")
+        return;
+    for (const [key, entry] of Object.entries(value)) {
+        const isReferenceField = /^(?:refs?|files?|paths?|(?:evidence|artifact|source)_(?:refs?|files?|paths?))$/.test(key);
+        rejectNarrativeReleaseReferences(projectRoot, entry, `${label}.${key}`, isReferenceField);
+    }
+}
 async function recordRelease(p) {
     const dir = artifactDirFrom(p.positional[0] || die("artifact directory is required"));
     const slug = taskSlugFor(dir, opt(p, "task-slug"));
+    const projectRoot = narrativeGuardRoot(dir);
     const decision = opt(p, "decision");
     if (!["merge", "release", "deploy", "hold", "rollback_required"].includes(decision))
         die("decision must be one of: merge, release, deploy, hold, rollback_required");
     const gates = opts(p, "gate-json").map((v) => parseJson(v, "--gate-json"));
     if (["merge", "release", "deploy"].includes(decision) && !gates.some((g) => g.name === decision && g.status === "pass"))
         die(`positive release decision requires ${decision} gate to pass`);
-    const payload = { ...sidecarBase(slug), decision: opt(p, "decision"), updated_at: opt(p, "timestamp", now()), scope: opt(p, "scope"), evidence_ref: opt(p, "evidence-ref"), gates: opts(p, "gate-json").map((v) => parseJson(v, "--gate-json")), rollback_plan: parseJson(opt(p, "rollback-json", '{"status":"not_required","summary":"Not required.","owner":"maintainer"}'), "--rollback-json"), observability_plan: parseJson(opt(p, "observability-json", '{"status":"not_required","summary":"Not required."}'), "--observability-json"), post_deploy_checks: opts(p, "post-deploy-json").map((v) => parseJson(v, "--post-deploy-json")), docs: parseJson(opt(p, "docs-json", '{"status":"not_needed","summary":"Not needed."}'), "--docs-json") };
+    const evidenceRef = opt(p, "evidence-ref");
+    const rollbackPlan = parseJson(opt(p, "rollback-json", '{"status":"not_required","summary":"Not required.","owner":"maintainer"}'), "--rollback-json");
+    const observabilityPlan = parseJson(opt(p, "observability-json", '{"status":"not_required","summary":"Not required."}'), "--observability-json");
+    const postDeployChecks = opts(p, "post-deploy-json").map((v) => parseJson(v, "--post-deploy-json"));
+    const docs = parseJson(opt(p, "docs-json", '{"status":"not_needed","summary":"Not needed."}'), "--docs-json");
+    rejectNarrativeReference(projectRoot, evidenceRef, "release evidence_ref");
+    rejectNarrativeReleaseReferences(projectRoot, gates, "release gates");
+    rejectNarrativeReleaseReferences(projectRoot, rollbackPlan, "release rollback_plan");
+    rejectNarrativeReleaseReferences(projectRoot, observabilityPlan, "release observability_plan");
+    rejectNarrativeReleaseReferences(projectRoot, postDeployChecks, "release post_deploy_checks");
+    rejectNarrativeReleaseReferences(projectRoot, docs, "release docs");
+    const payload = { ...sidecarBase(slug), decision: opt(p, "decision"), updated_at: opt(p, "timestamp", now()), scope: opt(p, "scope"), evidence_ref: evidenceRef, gates, rollback_plan: rollbackPlan, observability_plan: observabilityPlan, post_deploy_checks: postDeployChecks, docs };
     const stateSummary = opt(p, "summary").trim() || `Release readiness recorded for ${decision}.`;
     writeJson(path.join(dir, "release.json"), payload);
     writeState(dir, slug, "delivered", "release", payload.updated_at, stateSummary);
@@ -5460,9 +5883,14 @@ function validateLearningPrevention(prevention) {
     if (!["open", "completed", "accepted", "deferred", "rejected"].includes(value.status))
         die("correction.prevention.status must be one of: open, completed, accepted, deferred, rejected");
 }
-export function normalizeLearning(raw, timestamp) {
+export function normalizeLearning(raw, timestamp, projectRoot = process.cwd()) {
     if (!Array.isArray(raw.source_refs))
         die("source_refs must be an array");
+    for (const ref of raw.source_refs) {
+        if (typeof ref !== "string")
+            die("source_refs entries must be strings");
+        rejectNarrativeReference(projectRoot, ref, "learning source_ref");
+    }
     if (!Array.isArray(raw.facts))
         die("facts must be an array");
     if (!Array.isArray(raw.routing))
@@ -5476,7 +5904,8 @@ async function recordLearning(p) {
     const dir = artifactDirFrom(p.positional[0] || die("artifact directory is required"));
     const slug = taskSlugFor(dir, opt(p, "task-slug"));
     const timestamp = opt(p, "timestamp", now());
-    const records = opts(p, "record-json").map((v) => normalizeLearning(parseJson(v, "--record-json"), timestamp));
+    const projectRoot = narrativeGuardRoot(dir);
+    const records = opts(p, "record-json").map((v) => normalizeLearning(parseJson(v, "--record-json"), timestamp, projectRoot));
     const status = opt(p, "status", "learned");
     if (status === "learned" && records.some((r) => r.routing.some((x) => x.status === "open")))
         die("learning status learned cannot have open routing");
@@ -5498,7 +5927,7 @@ function evidenceClean(dir) {
     // legacy (pre-bundle-era) sessions that never wrote a trust.bundle at all — unrelated to origin
     // stamping. When a trust.bundle IS present, every claim must be stamped (requireStampedClaim);
     // there is no claimType-derivation fallback for an unstamped claim (#268/#344).
-    const bundle = loadJson(path.join(dir, "trust.bundle"));
+    const bundle = loadTrustBundleForTrustMachinery(dir);
     if (Array.isArray(bundle.claims)) {
         for (const c of bundle.claims)
             requireStampedClaim(c, dir);
@@ -5520,7 +5949,7 @@ function evidenceClean(dir) {
 }
 function critiqueClean(dir) {
     // trust.bundle is the sole critique artifact. Legacy critique.json must not influence gates.
-    const bundle = loadJson(path.join(dir, "trust.bundle"));
+    const bundle = loadTrustBundleForTrustMachinery(dir);
     if (Array.isArray(bundle.claims)) {
         for (const c of bundle.claims)
             requireStampedClaim(c, dir);
@@ -5545,11 +5974,17 @@ function assertExistingLearningValid(dir) {
     if (!fs.existsSync(file))
         return;
     const data = loadJson(file);
+    const projectRoot = narrativeGuardRoot(dir);
     if (!Array.isArray(data.records))
         die("learning records must be an array");
     for (const record of data.records) {
         if (!Array.isArray(record.source_refs))
             die("source_refs must be an array");
+        for (const ref of record.source_refs) {
+            if (typeof ref !== "string")
+                die("source_refs entries must be strings");
+            rejectNarrativeReference(projectRoot, ref, "learning source_ref");
+        }
         if (!Array.isArray(record.facts))
             die("facts must be an array");
         if (!Array.isArray(record.routing))
@@ -5563,6 +5998,7 @@ async function dogfoodPass(p) {
     const root = opt(p, "artifact-root") ? path.resolve(opt(p, "artifact-root")) : defaultArtifactRootForRead();
     const dir = path.resolve(opt(p, "artifact-dir") || currentDir(root) || "");
     requireArtifactDirUnderRoot(dir, root);
+    const projectRoot = narrativeGuardRoot(dir);
     assertExistingLearningValid(dir);
     const verdict = opt(p, "verdict");
     if (verdict === "pass") {
@@ -5575,7 +6011,7 @@ async function dogfoodPass(p) {
         // trust.bundle does not yet exist (loadJson falls back to {}), exactly as
         // recordEvidence/recordCheck rely on.
         const _dogfoodExistingCheckStampById = existingCheckStampMap(readBundleState(dir).checks);
-        const checks = opts(p, "check-json").map((v) => normalizeCheck(parseJson(v, "--check-json"), false, _dogfoodExistingCheckStampById));
+        const checks = opts(p, "check-json").map((v) => normalizeCheck(parseJson(v, "--check-json"), false, _dogfoodExistingCheckStampById, projectRoot));
         if (checks.some((c) => c.status !== "pass" && c.status !== "skip"))
             die("clean evidence requires all non-skipped checks to pass");
         // Phase 4c: evidence check reads from trust.bundle (sole verification artifact); legacy evidence.json fallback in evidenceClean.
@@ -5591,7 +6027,7 @@ async function dogfoodPass(p) {
         if (p.flags.has("require-critique") || opt(p, "release-decision")) {
             const newCritiqueVerdict = opt(p, "critique-verdict", "pass");
             for (const value of opts(p, "finding-json"))
-                normalizeFinding(parseJson(value, "--finding-json"));
+                normalizeFinding(parseJson(value, "--finding-json"), projectRoot);
             if (newCritiqueVerdict !== "pass")
                 die(opt(p, "release-decision") ? "requires clean critique" : "requires clean critique before recording pass evidence");
             if (!opt(p, "critique-id") && !critiqueClean(dir))
@@ -5600,7 +6036,7 @@ async function dogfoodPass(p) {
                 die(opt(p, "release-decision") ? "requires clean critique" : "requires clean critique before recording pass evidence");
         }
     }
-    const learningRecords = opts(p, "learning-record-json").map((v) => normalizeLearning(parseJson(v, "--learning-record-json"), opt(p, "timestamp", now())));
+    const learningRecords = opts(p, "learning-record-json").map((v) => normalizeLearning(parseJson(v, "--learning-record-json"), opt(p, "timestamp", now()), projectRoot));
     if (opt(p, "learning-status") === "learned" && learningRecords.some((r) => r.routing.some((x) => x.status === "open")))
         die("learned status cannot have open learning routing");
     if (opt(p, "learning-status") === "learned" && learningRecords.some((r) => r.correction === undefined))
@@ -5710,7 +6146,7 @@ export function gateAdvisoryFix(calibration, claimId, answerStatus) {
     return `Ensure \`workflow-sidecar record-evidence\` writes a definitive event for claim \`${claimId}\` (currently \`${s}\`) before \`stop-goal-fit\` evaluates. The gate had no resolved evidence to act on.`;
 }
 /**
- * Build a schema-conformant InquiryRecord for the hachure inquiry-record.schema.json.
+ * Build a schema-conformant InquiryRecord for @kontourai/surface's canonical InquiryRecord schema.
  * Strips Surface-internal fields (identityLinkIds, transitiveRuleIds) from
  * resolutionPath that are valid in the TS type but not in the JSON schema.
  * Sets answer.value to the gate-review value-add: { calibration, advisoryFix, gateFired, sessionSlug }.
@@ -5888,16 +6324,18 @@ async function gateReview(p) {
             : [];
     }
     const records = buildGateInquiryRecords(bundle, blockSignal, slug, expectedCriterionIds, surface);
-    // Validate each record against the hachure inquiry-record.schema.json (fail-open)
-    const validator = getHachureInquiryRecordValidator();
+    // Validate each record against the canonical InquiryRecord schema via Surface (fail-open)
     let schemaValid = true;
     const validationErrors = [];
-    for (const record of records) {
-        if (validator) {
-            const result = validator(record);
-            if (!result.valid) {
+    const inquiryValidator = surface?.validateInquiryRecord;
+    if (typeof inquiryValidator === "function") {
+        for (const record of records) {
+            try {
+                inquiryValidator(record);
+            }
+            catch (err) {
                 schemaValid = false;
-                validationErrors.push(...result.errors.map((e) => `${record["id"] ?? "?"}: ${e}`));
+                validationErrors.push(`${record["id"] ?? "?"}: ${err instanceof Error ? err.message : String(err)}`);
             }
         }
     }
@@ -5916,7 +6354,7 @@ async function gateReview(p) {
         .filter(([, n]) => n > 0)
         .map(([k, n]) => `${k}=${n}`)
         .join(", ");
-    const schemaTag = validator ? (schemaValid ? " schema:valid" : " schema:INVALID") : " schema:unavailable";
+    const schemaTag = typeof inquiryValidator === "function" ? (schemaValid ? " schema:valid" : " schema:INVALID") : " schema:unavailable";
     console.log(`gate-review: ${records.length} InquiryRecord(s) [${summary}]${schemaTag} → ${outputPath}`);
     return 0;
 }
@@ -6432,14 +6870,6 @@ async function liveness(p) {
     die("liveness action must be one of: claim | heartbeat | release | status | whoami | verdict");
     return 1;
 }
-// ─────────────────────────────────────────────────────────────────────────────
-// ─── Claim Lookup — pure helper (promotable to Surface #171) ─────────────────
-// buildClaimExplanation + its types are extracted to ./sidecar-claim-explain.ts
-// (ops#22): a PURE projection (report + bundle + id in, structured explanation out)
-// with no fs/CLI/shared state, unit-tested in isolation. Re-exported here so the
-// library facade (src/index.ts) and the IO `claimLookup` handler below are unchanged.
-export { buildClaimExplanation } from "./sidecar-claim-explain.js";
-import { buildClaimExplanation } from "./sidecar-claim-explain.js";
 /**
  * claim <id> <dir>
  *
@@ -6476,27 +6906,16 @@ Available claim ids:
     }
     // Load Surface via tryLoadSurface() (ESM, cached, fail-open pattern)
     const surface = await tryLoadSurface();
-    if (!surface || typeof surface.buildTrustReport !== "function" || typeof surface.buildDerivationDrilldown !== "function") {
-        process.stderr.write(`[claim] @kontourai/surface unavailable or missing buildTrustReport/buildDerivationDrilldown
+    if (!surface || typeof surface.buildTrustReport !== "function" || typeof surface.explainClaim !== "function") {
+        process.stderr.write(`[claim] @kontourai/surface unavailable or missing buildTrustReport/explainClaim (needs >=2.10)
 `);
         return 0; // fail-open, consistent with gate-review pattern
     }
-    // Build TrustReport (required — buildDerivationDrilldown needs TrustReport, not TrustBundle)
+    // Build TrustReport, then the structured explanation — Surface's explainClaim
+    // (#171 lift) composes the derivation drilldown internally, fail-soft, exactly
+    // as the retired local helper + caller-side enrichment did.
     const report = surface.buildTrustReport(bundle);
-    // Build the structured explanation (pure, promotable to #171)
-    const explanation = buildClaimExplanation(report, bundle, claimId);
-    // Enrich the why.directInputs/leafClaims/diagnostics from the drilldown
-    try {
-        const drilldown = surface.buildDerivationDrilldown(report, claimId);
-        if (drilldown) {
-            explanation.why.directInputs = Array.isArray(drilldown.directInputs) ? drilldown.directInputs : [];
-            explanation.why.leafClaims = Array.isArray(drilldown.leafClaims) ? drilldown.leafClaims : [];
-            explanation.why.diagnostics = Array.isArray(drilldown.diagnostics) ? drilldown.diagnostics : [];
-        }
-    }
-    catch {
-        // buildDerivationDrilldown threw (e.g. claim not in report) — proceed without drilldown
-    }
+    const explanation = surface.explainClaim(report, claimId);
     if (p.flags.has("json")) {
         console.log(JSON.stringify(explanation, null, 2));
         return 0;