@kontourai/flow-agents 1.3.0 → 2.0.0

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

@@ -2,27 +2,86 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import { createRequire } from "node:module";
-const statuses = new Set(["new", "planning", "planned", "in_progress", "blocked", "verifying", "verified", "needs_decision", "not_verified", "failed", "delivered", "accepted", "archived"]);
-const phases = ["idea", "backlog", "pickup", "planning", "execution", "verification", "goal_fit", "evidence", "release", "learning", "done"];
-const checkKinds = new Set(["build", "types", "lint", "test", "security", "diff", "browser", "runtime", "policy", "external"]);
-const checkStatuses = new Set(["pass", "fail", "not_verified", "skip"]);
-const verdicts = new Set(["pass", "partial", "fail", "not_verified"]);
+import { fileURLToPath } from "node:url";
+// ADR 0016 Abstraction A: shared FlowDefinition resolver (P-a)
+import { resolveActiveFlowStep, resolveFlowFilePath, resolvePhaseMap } from "../lib/flow-resolver.js";
+export const statuses = new Set(["new", "planning", "planned", "in_progress", "blocked", "verifying", "verified", "needs_decision", "not_verified", "failed", "delivered", "accepted", "archived"]);
+export const phases = ["idea", "backlog", "pickup", "planning", "execution", "verification", "goal_fit", "evidence", "release", "learning", "done"];
+export const checkKinds = new Set(["build", "types", "lint", "test", "security", "diff", "browser", "runtime", "policy", "external"]);
+export const checkStatuses = new Set(["pass", "fail", "not_verified", "skip"]);
+export const verdicts = new Set(["pass", "partial", "fail", "not_verified"]);
 function now() { return new Date().toISOString().replace(/\.\d{3}Z$/, "Z"); }
 function read(file) { return fs.readFileSync(file, "utf8"); }
-function writeJson(file, payload) { fs.mkdirSync(path.dirname(file), { recursive: true }); fs.writeFileSync(file, `${JSON.stringify(payload, null, 2)}\n`); }
+export function writeJson(file, payload) { fs.mkdirSync(path.dirname(file), { recursive: true }); fs.writeFileSync(file, `${JSON.stringify(payload, null, 2)}\n`); }
 function printJson(payload) { console.log(JSON.stringify(payload).replace(/":/g, '": ').replace(/,"/g, ', "')); }
-function loadJson(file, fallback = {}) { return fs.existsSync(file) ? JSON.parse(read(file)) : { ...fallback }; }
-function appendJsonl(file, payload) {
+export function loadJson(file, fallback = {}) { return fs.existsSync(file) ? JSON.parse(read(file)) : { ...fallback }; }
+export function appendJsonl(file, payload) {
     fs.mkdirSync(path.dirname(file), { recursive: true });
     const line = JSON.stringify(payload, Object.keys(payload).sort()).replace(/":/g, '": ').replace(/,"/g, ', "');
     fs.appendFileSync(file, `${line}\n`);
 }
 function die(message) { throw new Error(message); }
 function slugify(value, fallback) { return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || fallback; }
-// Optional Hachure trust-bundle validation. No-ops gracefully when hachure is not installed.
-// Install hachure (^0.4.0) as an optional dependency to enable schema validation.
-function tryLoadHachureValidator() {
+/** Derives a deterministic, filesystem-safe slug from a canonical work-item ref like `kontourai/flow-agents#161`.
+ * Format: `<owner>-<repo>-<id>` e.g. `kontourai-flow-agents-161`.
+ * Reuses slugify() for normalization. Validates that the id is a numeric GitHub issue number. */
+function workItemSlug(ref) {
+    const hashIdx = ref.indexOf("#");
+    if (hashIdx < 0 || hashIdx === ref.length - 1)
+        die("--work-item must be in owner/repo#id format");
+    const repoPath = ref.slice(0, hashIdx);
+    const id = ref.slice(hashIdx + 1);
+    if (!/^\d+$/.test(id))
+        die("--work-item id must be a numeric issue number");
+    const parts = repoPath.split("/");
+    if (parts.length !== 2 || !parts[0] || !parts[1])
+        die("--work-item repo must be owner/repo format");
+    const [owner, repo] = parts;
+    return slugify(`${owner}-${repo}-${id}`, "work-item");
+}
+/**
+ * Validate a Hachure trust.bundle using @kontourai/surface's canonical validator
+ * (surface is the authoritative owner of trust-bundle schema validation per ADR 0010 / ADR 0015).
+ * Returns `{ valid, errors, available }`. When @kontourai/surface is unavailable,
+ * `available` is false and `valid` is true (fail-open) so callers can choose to treat
+ * unvalidated bundles as acceptable or gate on `available`. Surface is REQUIRED for
+ * bundle writes per ADR 0010 Phase 4c — `assertBundleWritten` enforces this on the
+ * write path. Surface's validator is equivalent-or-stronger than the prior hachure
+ * JSON-Schema validator: it validates the same structural constraints plus cross-reference
+ * integrity (evidence/event → claim references) that the JSON schema did not enforce.
+ */
+export async function validateTrustBundle(bundle) {
+    // Use the already-loaded surface module when available (zero-cost re-entry after first load).
+    // When called standalone (fresh process, surface not yet loaded), attempt a one-shot import.
+    let surfaceValidate;
+    if (_surfaceModule !== undefined) {
+        // Module has been attempted: use cached result (null = unavailable).
+        surfaceValidate = _surfaceModule?.validateTrustBundle ?? undefined;
+    }
+    else {
+        // Not yet attempted — load now for standalone callers (e.g. library consumers, tests).
+        const m = await tryLoadSurface();
+        surfaceValidate = m?.validateTrustBundle ?? undefined;
+    }
+    if (!surfaceValidate)
+        return { valid: true, errors: [], available: false };
+    try {
+        surfaceValidate(bundle);
+        return { valid: true, errors: [], available: true };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        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"));
@@ -34,18 +93,20 @@ function tryLoadHachureValidator() {
                 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 === "trust-bundle.schema.json")
+            if (filename === "inquiry-record.schema.json")
                 continue;
             ajv.addSchema(schema, filename);
         }
-        const trustBundleSchema = schemas["trust-bundle.schema.json"];
-        if (!trustBundleSchema)
-            return null;
-        const validate = ajv.compile(trustBundleSchema);
-        return (bundle) => {
-            const valid = validate(bundle);
+        const validate = ajv.compile(inquiryRecordSchema);
+        _hachureInquiryRecordValidator = (record) => {
+            const valid = validate(record);
             if (valid)
                 return { valid: true, errors: [] };
             const errors = (validate.errors ?? []).map((err) => {
@@ -54,17 +115,412 @@ function tryLoadHachureValidator() {
             });
             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.
+ */
+export function validateInquiryRecord(record) {
+    const validate = getHachureInquiryRecordValidator();
+    if (!validate)
+        return { valid: true, errors: [], available: false };
+    return { ...validate(record), available: true };
+}
+let _surfaceModule; // undefined = not tried yet; null = unavailable
+async function tryLoadSurface() {
+    // Test/diagnostic seam: simulate a degraded environment where Surface is unavailable,
+    // to exercise the fail-loud (no silent data loss) path without disturbing node_modules.
+    if (process.env.FLOW_AGENTS_SURFACE_UNAVAILABLE === "1")
+        return null;
+    if (_surfaceModule !== undefined)
+        return _surfaceModule;
+    try {
+        const m = await import("@kontourai/surface");
+        _surfaceModule = m;
+        return _surfaceModule;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`[trust-bundle] @kontourai/surface unavailable — bundle write skipped: ${message}\n`);
+        _surfaceModule = null;
+        return null;
+    }
+}
+/** Map a workflow check status to the Surface VerificationEvent status. */
+function checkStatusToEventStatus(status) {
+    if (status === "pass")
+        return "verified";
+    if (status === "fail")
+        return "disputed";
+    if (status === "skip")
+        return "assumed";
+    return null; // not_verified / unknown → no event → Surface returns "unknown"
+}
+/** Map an acceptance criterion status to the Surface VerificationEvent status. */
+function criterionStatusToEventStatus(status) {
+    if (status === "pass")
+        return "verified";
+    if (status === "fail")
+        return "disputed";
+    if (status === "accepted_gap")
+        return "assumed";
+    return null; // pending / not_verified → no event → Surface returns "unknown"
+}
+/** Map a critique verdict to the Surface VerificationEvent status. */
+function critiqueToEventStatus(verdict, findings) {
+    if (verdict === "fail")
+        return "disputed";
+    const hasOpenFinding = Array.isArray(findings) && findings.some((f) => f.status === "open");
+    if (verdict === "pass" && hasOpenFinding)
+        return "disputed";
+    if (verdict === "pass")
+        return "verified";
+    if (verdict === "comment")
+        return "assumed";
+    return null; // not_verified or unknown → no event → Surface returns "unknown"
+}
+/**
+ * Build a Hachure trust.bundle from raw check/criterion/critique inputs.
+ * trust.bundle is the PRIMARY artifact (ADR 0010 Phase 4a producer inversion).
+ * Callers pass raw inputs directly — not bespoke-sidecar-shaped objects.
+ * Derives claim statuses using @kontourai/surface's canonical versioned function.
+ * Returns null when Surface is unavailable (caller skips the bundle write).
+ * @param slug       Task slug (used as subjectId prefix)
+ * @param timestamp  ISO-8601 timestamp for createdAt / updatedAt / observedAt
+ * @param checks     Normalized check objects (from record-evidence --check-json / --surface-trust-json)
+ * @param criteria   Acceptance criteria objects (from acceptance.json .criteria array)
+ * @param critiques  Critique objects (from critique.json .critiques array)
+ * @param commandLog Optional parsed command-log.jsonl entries (capture-authoritative fold)
+ */
+export async function buildTrustBundle(slug, timestamp, checks, criteria, critiques, commandLog, flowAgentsDir) {
+    const surface = await tryLoadSurface();
+    if (!surface)
+        return null;
+    const { deriveClaimStatus, generateClaimId, statusFunctionVersion } = surface;
+    // ADR 0016 Abstraction A (P-b): resolve active flow step for dual-emit.
+    // When flowAgentsDir is provided AND current.json carries active_flow_id/active_step_id,
+    // each produced claim gets a DECLARED primary claim (kit-typed) plus a legacy shadow
+    // (workflow.* type, claimId suffix "-legacy") for backward compatibility. When null,
+    // only the existing workflow.* claims are produced (zero behavior change).
+    const activeStep = flowAgentsDir ? resolveActiveFlowStep(flowAgentsDir) : null;
+    const claims = [];
+    const evidenceItems = [];
+    const events = [];
+    const ts = timestamp || new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+    // One VerificationPolicy per distinct claimType, so status is policy-governed
+    // (not derived against an empty policy set). Maximal-fidelity per ADR 0010.
+    const policies = new Map();
+    const ensurePolicy = (claimType, impactLevel, requiredEvidence) => {
+        let p = policies.get(claimType);
+        if (!p) {
+            p = { id: `policy:${claimType}`, claimType, requiredEvidence, acceptanceCriteria: [`A verified verification event must support a ${claimType} claim.`], reviewAuthority: "system", validityRule: { kind: "manual" }, stalenessTriggers: [], conflictRules: [], impactLevel };
+            policies.set(claimType, p);
+        }
+        return p;
+    };
+    // Index the deterministic capture log by normalized command (a single FAIL wins),
+    // so a claimed-pass check whose command actually FAILED becomes authoritative here.
+    const captureByCommand = new Map();
+    for (const entry of Array.isArray(commandLog) ? commandLog : []) {
+        if (!entry || typeof entry.command !== "string")
+            continue;
+        const key = entry.command.replace(/\s+/g, " ").trim();
+        if (!key)
+            continue;
+        const failed = entry.observedResult === "fail" || (Number.isInteger(entry.exitCode) && entry.exitCode !== 0);
+        const prev = captureByCommand.get(key);
+        captureByCommand.set(key, { observedResult: failed || (prev && prev.observedResult === "fail") ? "fail" : "pass", exitCode: Number.isInteger(entry.exitCode) ? entry.exitCode : (prev ? prev.exitCode : null) });
+    }
+    // ─── P-b dual-emit helper ──────────────────────────────────────────────────
+    // Semantic matching table (ADR 0016 Abstraction A P-b):
+    //   check (non-policy kind) → expects[] entry where claimType does NOT contain
+    //     "acceptance" AND subjectType is NOT "decision". Preference: subjectType=
+    //     "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.
+    //
+    // The DECLARED claim is primary (kit-typed claimType + subjectType).
+    // The legacy claim uses the existing workflow.* claimType (suffix "-legacy") as
+    // a backward-compat shadow. Both cite the same evidence. Status is derived by
+    // Surface from that evidence (never hand-set).
+    //
+    // Per-gate producibility (ADR 0016 P-d):
+    //   (a) Already handled via subjectType=flow-step preference:
+    //       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):
+    //       builder.plan.implementation   (plan-gate, subjectType=artifact)
+    //       builder.execute.scope         (execute-gate, subjectType=change)
+    //       builder.merge-ready.readiness (merge-ready-gate, subjectType=change)
+    //       builder.merge-ready-ci.readiness (merge-ready-ci-gate, subjectType=pull-request)
+    //   (c) No natural producer — required:false in build.flow.json (ADR 0016 P-d plan):
+    //       builder.pull-work.selected        (pull-work-gate, subjectType=work-item)
+    //       builder.design-probe.pickup-readiness (design-probe-gate, subjectType=work-item)
+    //       builder.design-probe.decisions    (design-probe-gate, subjectType=decision)
+    //       builder.pr-open.pull-request      (pr-open-gate, subjectType=pull-request)
+    //       builder.learn.decisions           (learn-gate, subjectType=decision)
+    //       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.
+    function matchExpectsEntry(kind, checkKindVal, expectationId) {
+        if (!activeStep || activeStep.gateExpects.length === 0)
+            return null;
+        const expects = activeStep.gateExpects;
+        if (kind === "check") {
+            // ADR 0016 P-d Increment 2: when an explicit expectation id is given (from record-gate-claim
+            // --expectation), bypass heuristics and do exact lookup. This ensures multi-expects[] gates
+            // (learn-gate: decision + release; design-probe-gate: work-item + decision) produce the
+            // correct declared claimType rather than the heuristic-selected one.
+            if (expectationId) {
+                const exact = expects.find((e) => e.id === expectationId);
+                if (exact)
+                    return { claimType: exact.bundle_claim.claimType, subjectType: exact.bundle_claim.subjectType };
+            }
+            const isPolicy = checkKindVal === "policy";
+            if (isPolicy) {
+                const match = expects.find((e) => {
+                    const ct = e.bundle_claim.claimType.toLowerCase();
+                    return ct.includes("compliance") || ct.includes("policy");
+                });
+                if (match)
+                    return { claimType: match.bundle_claim.claimType, subjectType: match.bundle_claim.subjectType };
+            }
+            // Non-policy: prefer flow-step subjectType, exclude decision/acceptance entries
+            const preferred = expects.find((e) => {
+                const ct = e.bundle_claim.claimType.toLowerCase();
+                return e.bundle_claim.subjectType !== "decision" && !ct.includes("acceptance") && e.bundle_claim.subjectType === "flow-step";
+            });
+            if (preferred)
+                return { claimType: preferred.bundle_claim.claimType, subjectType: preferred.bundle_claim.subjectType };
+            const fallback = expects.find((e) => {
+                const ct = e.bundle_claim.claimType.toLowerCase();
+                return e.bundle_claim.subjectType !== "decision" && !ct.includes("acceptance");
+            });
+            if (fallback)
+                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();
+                return e.bundle_claim.subjectType === "artifact" && (ct.includes("policy") || ct.includes("compliance"));
+            });
+            if (match)
+                return { claimType: match.bundle_claim.claimType, subjectType: match.bundle_claim.subjectType };
+            const last = expects[expects.length - 1];
+            return { claimType: last.bundle_claim.claimType, subjectType: last.bundle_claim.subjectType };
+        }
         return null;
     }
+    // ────────────────────────────────────────────────────────────────────────────
+    // Evidence checks → claims + evidence items + events. Capture is authoritative.
+    for (const check of Array.isArray(checks) ? checks : []) {
+        if (!check.id)
+            continue;
+        const subjectId = `${slug}/${check.id}`;
+        const fieldOrBehavior = String(check.summary ?? check.id);
+        const claimId = generateClaimId(subjectId, "flow-agents.workflow", fieldOrBehavior);
+        const evId = `ev:${claimId}`;
+        const legacyClaimType = `workflow.check.${check.kind ?? "external"}`;
+        const policy = ensurePolicy(legacyClaimType, "high", ["test_output"]);
+        const cmd = typeof check.command === "string" ? check.command.replace(/\s+/g, " ").trim() : "";
+        const captured = cmd ? captureByCommand.get(cmd) : undefined;
+        const effectiveStatus = captured ? captured.observedResult : String(check.status ?? "");
+        const evStatus = checkStatusToEventStatus(effectiveStatus);
+        const claimEvents = [];
+        if (evStatus) {
+            const evt = { id: `evt:${claimId}`, claimId, status: evStatus, actor: "flow-agents/workflow-sidecar", method: "validation", evidenceIds: [evId], createdAt: ts, verifiedAt: ts };
+            events.push(evt);
+            claimEvents.push(evt);
+        }
+        const evItem = { id: evId, claimId, evidenceType: "test_output", method: "validation", sourceRef: `${slug}/evidence.json`, excerptOrSummary: fieldOrBehavior, observedAt: ts, collectedBy: "flow-agents/workflow-sidecar", passing: effectiveStatus === "pass" };
+        if (captured) {
+            evItem.sourceRef = `${slug}/command-log.jsonl`;
+            evItem.collectedBy = "flow-agents/evidence-capture";
+            evItem.execution = { runner: "bash", label: cmd, isError: captured.observedResult === "fail", ...(captured.exitCode != null ? { exitCode: captured.exitCode } : {}) };
+        }
+        evidenceItems.push(evItem);
+        // P-d: declared-only when active flow/step present (shadow retired); no-flow path unchanged.
+        // When record-gate-claim sets _gate_claim_expectation_id, pass it for exact lookup (ADR 0016 P-d Increment 2).
+        const declared = matchExpectsEntry("check", check.kind, typeof check._gate_claim_expectation_id === "string" ? check._gate_claim_expectation_id : undefined);
+        if (declared) {
+            // Declared kit-typed claim only — no legacy shadow (ADR 0016 P-d).
+            const declaredPolicy = ensurePolicy(declared.claimType, "high", ["test_output"]);
+            const declaredClaimObj = { id: claimId, subjectType: declared.subjectType, subjectId, surface: "flow-agents.workflow", claimType: declared.claimType, fieldOrBehavior, value: effectiveStatus, createdAt: ts, updatedAt: ts, impactLevel: "high", verificationPolicyId: declaredPolicy.id };
+            const { status: declaredStatus } = deriveClaimStatus({ claim: declaredClaimObj, evidence: [evItem], 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-check", subjectId, surface: "flow-agents.workflow", claimType: legacyClaimType, fieldOrBehavior, value: effectiveStatus, createdAt: ts, updatedAt: ts, impactLevel: "high", verificationPolicyId: policy.id };
+            const { status: derivedStatus } = deriveClaimStatus({ claim: claimObj, evidence: [evItem], events: claimEvents, policies: [policy] });
+            claims.push({ ...claimObj, status: derivedStatus });
+        }
+    }
+    // Acceptance criteria → claims + events
+    for (const criterion of Array.isArray(criteria) ? criteria : []) {
+        if (!criterion.id)
+            continue;
+        const subjectId = `${slug}/${criterion.id}`;
+        const fieldOrBehavior = String(criterion.description ?? criterion.id);
+        const claimId = generateClaimId(subjectId, "flow-agents.workflow", fieldOrBehavior);
+        const legacyClaimType = "workflow.acceptance.criterion";
+        const policy = ensurePolicy(legacyClaimType, "high", []);
+        const evStatus = criterionStatusToEventStatus(String(criterion.status ?? ""));
+        const claimEvents = [];
+        if (evStatus) {
+            const evt = { id: `evt:${claimId}`, claimId, status: evStatus, actor: "flow-agents/workflow-sidecar", method: "validation", evidenceIds: [], createdAt: ts, verifiedAt: ts };
+            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, surface: "flow-agents.workflow", claimType: declared.claimType, fieldOrBehavior, value: criterion.status, createdAt: ts, updatedAt: ts, impactLevel: "high", verificationPolicyId: declaredPolicy.id };
+            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, surface: "flow-agents.workflow", claimType: legacyClaimType, fieldOrBehavior, value: criterion.status, createdAt: ts, updatedAt: ts, impactLevel: "high", verificationPolicyId: policy.id };
+            const { status: derivedStatus } = deriveClaimStatus({ claim: claimObj, evidence: [], events: claimEvents, policies: [policy] });
+            claims.push({ ...claimObj, status: derivedStatus });
+        }
+    }
+    // Critique entries → claims + events
+    for (const c of Array.isArray(critiques) ? critiques : []) {
+        if (!c.id)
+            continue;
+        const subjectId = `${slug}/${c.id}`;
+        const fieldOrBehavior = String(c.summary ?? c.verdict ?? c.id);
+        const claimId = generateClaimId(subjectId, "flow-agents.workflow", fieldOrBehavior);
+        const legacyClaimType = "workflow.critique.review";
+        const policy = ensurePolicy(legacyClaimType, "medium", []);
+        const evStatus = critiqueToEventStatus(String(c.verdict ?? ""), c.findings ?? []);
+        const claimEvents = [];
+        if (evStatus) {
+            const evt = { id: `evt:${claimId}`, claimId, status: evStatus, actor: "flow-agents/workflow-sidecar", method: "validation", evidenceIds: [], createdAt: ts, verifiedAt: ts };
+            events.push(evt);
+            claimEvents.push(evt);
+        }
+        // P-d: declared-only when active flow/step present (shadow retired); no-flow path unchanged.
+        const declared = matchExpectsEntry("critique");
+        if (declared) {
+            // Declared kit-typed claim only — no legacy shadow (ADR 0016 P-d).
+            const declaredPolicy = ensurePolicy(declared.claimType, "medium", []);
+            const declaredClaimObj = { id: claimId, subjectType: declared.subjectType, subjectId, surface: "flow-agents.workflow", claimType: declared.claimType, fieldOrBehavior, value: c.verdict, createdAt: ts, updatedAt: ts, impactLevel: "medium", verificationPolicyId: declaredPolicy.id };
+            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-critique", subjectId, surface: "flow-agents.workflow", claimType: legacyClaimType, fieldOrBehavior, value: c.verdict, createdAt: ts, updatedAt: ts, impactLevel: "medium", verificationPolicyId: policy.id };
+            const { status: derivedStatus } = deriveClaimStatus({ claim: claimObj, evidence: [], events: claimEvents, policies: [policy] });
+            claims.push({ ...claimObj, status: derivedStatus });
+        }
+    }
+    return {
+        schemaVersion: 3,
+        source: `flow-agents/workflow-sidecar;statusFunctionVersion=${statusFunctionVersion}`,
+        claims,
+        evidence: evidenceItems,
+        policies: [...policies.values()],
+        events,
+    };
+}
+/**
+ * Fail-open wrapper: builds (via Surface), validates, and writes a trust.bundle.
+ * Accepts raw check/criterion/critique inputs directly (ADR 0010 Phase 4a).
+ * trust.bundle is written as the PRIMARY artifact; bespoke sidecars are the
+ * caller's responsibility to emit as back-compat projections AFTER this call.
+ * ANY error is caught and logged to stderr — this function NEVER throws and
+ * NEVER affects the exit code of its caller.
+ * Returns { written: false } if Surface is unavailable (fail-open; does NOT
+ * fall back to hand-rolled status derivation).
+ * @param checks     Normalized check objects (same as buildTrustBundle)
+ * @param criteria   Acceptance criteria objects (same as buildTrustBundle)
+ * @param critiques  Critique objects (same as buildTrustBundle)
+ */
+export async function writeTrustBundle(dir, slug, timestamp, checks, criteria, critiques) {
+    try {
+        // Fold the deterministic capture log (PostToolUse evidence-capture) into the
+        // bundle so capture is authoritative over claimed status. Best-effort read.
+        let commandLog = [];
+        try {
+            const raw = fs.readFileSync(path.join(dir, "command-log.jsonl"), "utf8");
+            commandLog = raw.split("\n").map((l) => l.trim()).filter(Boolean).map((l) => { try {
+                return JSON.parse(l);
+            }
+            catch {
+                return null;
+            } }).filter((x) => x !== null);
+        }
+        catch { /* no capture log — fine */ }
+        // ADR 0016 Abstraction A (P-d): pass the .flow-agents dir ONLY when current.json
+        // points to this session (scoped active-flow guard). If current.json.artifact_dir
+        // resolves to a different session, pass null — no active-flow claim mapping for this bundle.
+        const _flowAgentsDir = path.dirname(dir);
+        let _scopedFlowAgentsDir = undefined;
+        try {
+            const _currentRaw = JSON.parse(fs.readFileSync(path.join(_flowAgentsDir, "current.json"), "utf8"));
+            const _artDir = typeof _currentRaw["artifact_dir"] === "string" ? _currentRaw["artifact_dir"] : null;
+            if (_artDir && path.resolve(_flowAgentsDir, _artDir) === path.resolve(dir)) {
+                _scopedFlowAgentsDir = _flowAgentsDir;
+            }
+        }
+        catch { /* current.json absent or unreadable — no scoping */ }
+        const bundle = await buildTrustBundle(slug, timestamp, checks, criteria, critiques, commandLog, _scopedFlowAgentsDir);
+        if (!bundle)
+            return { written: false, errors: [] }; // Surface unavailable — fail-open, skip write
+        const result = await validateTrustBundle(bundle);
+        if (result.available && !result.valid) {
+            process.stderr.write(`[trust-bundle] schema validation failed: ${result.errors.join("; ")}\n`);
+            return { written: false, errors: result.errors };
+        }
+        writeJson(path.join(dir, "trust.bundle"), bundle);
+        return { written: true, errors: [] };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`[trust-bundle] write failed: ${message}\n`);
+        return { written: false, errors: [message] };
+    }
 }
-let _hachureValidator;
-function getHachureValidator() {
-    if (_hachureValidator === undefined)
-        _hachureValidator = tryLoadHachureValidator();
-    return _hachureValidator;
+// Phase 4c safety: the trust.bundle is the ONLY store (bespoke sidecars retired), so a
+// fail-open write = SILENT DATA LOSS. Data-persisting writers must fail loudly when the
+// bundle was not written (Surface unavailable, validation, or I/O) instead of exiting 0
+// and dropping the record. (Was masked as a "flaky" concurrent-critique test.)
+function assertBundleWritten(result) {
+    if (result.written)
+        return;
+    const reason = result.errors.length
+        ? result.errors.join("; ")
+        : "@kontourai/surface is unavailable — it is REQUIRED to persist the trust.bundle (bundle-only workspace, ADR 0010 Phase 4c). Install it (>= 1.2) and retry.";
+    die(`trust.bundle was NOT written — the record was not persisted: ${reason}`);
 }
+// ─────────────────────────────────────────────────────────────────────────────
 function safeRepoIdentifier(value) {
     const trimmed = value.trim().replace(/\.git$/, "");
     if (!trimmed || trimmed.length > 120)
@@ -119,7 +575,7 @@ function repoIdentifier() {
     }
     return safeRepoIdentifier(path.basename(process.cwd())) || "workspace";
 }
-function sidecarBase(slug) {
+export function sidecarBase(slug) {
     return { schema_version: "1.0", task_slug: slug, repo: repoIdentifier() };
 }
 function parseArgs(argv) {
@@ -197,7 +653,7 @@ async function withLock(dir, create, command, body) {
     if (create)
         fs.mkdirSync(dir, { recursive: true });
     if (!fs.existsSync(dir))
-        return body();
+        return await body();
     const lockDir = path.join(dir, ".workflow-sidecar.lockdir");
     const staleMs = Number(process.env.FLOW_AGENTS_WORKFLOW_SIDECAR_STALE_LOCK_MS ?? 5 * 60 * 1000);
     const deadline = Date.now() + 30000;
@@ -232,7 +688,7 @@ async function withLock(dir, create, command, body) {
         const delay = process.env.FLOW_AGENTS_WORKFLOW_SIDECAR_LOCK_DELAY;
         if (delay)
             await new Promise((resolve) => setTimeout(resolve, Number(delay) * 1000));
-        return body();
+        return await body();
     }
     finally {
         fs.rmSync(lockDir, { recursive: true, force: true });
@@ -305,7 +761,63 @@ function validateAgentId(agent) {
         die("--agent-id must be a conservative slug");
     return agent;
 }
-function writeCurrent(root, dir, timestamp, owner, source) {
+/**
+ * Find the repository root by walking upward from a starting directory to locate
+ * the nearest ancestor containing a kits/ subdirectory. Mirrors flow-resolver.ts
+ * findRepoRoot, but callable from workflow-sidecar.ts without re-importing the
+ * internal helper.
+ *
+ * ADR 0016 Abstraction A (P-d): used by advance-state and ensure-session to
+ * derive repoRoot for resolvePhaseMap calls.
+ */
+function findRepoRootFromDir(startDir) {
+    let dir = startDir;
+    for (let i = 0; i < 16; i++) {
+        if (fs.existsSync(path.join(dir, "kits")))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return process.cwd();
+}
+/**
+ * Resolve the first step id from a FlowDefinition's steps[] list.
+ * Returns null when the flow cannot be loaded or has no steps.
+ * Used by ensure-session to default active_step_id when --flow-id is
+ * provided without --step-id (Q2 decision, P-d Increment 1).
+ */
+function resolveFirstStep(flowId, repoRoot) {
+    if (!flowId)
+        return null;
+    const dotIdx = flowId.indexOf(".");
+    if (dotIdx < 1)
+        return null;
+    const kitId = flowId.slice(0, dotIdx);
+    const flowName = flowId.slice(dotIdx + 1);
+    if (!kitId || !flowName)
+        return null;
+    // Use resolveFlowFilePath for SLUG_RE validation + path-containment check — the same
+    // defense used by resolveFlowStep and resolvePhaseMap (single implementation, DRY).
+    // Returns null for any traversal attempt (e.g. flowName="../../secret") so the
+    // caller gets a clean null return matching the existing null-contract.
+    const flowFilePath = resolveFlowFilePath(kitId, flowName, flowId, repoRoot);
+    if (!flowFilePath)
+        return null;
+    try {
+        const raw = fs.readFileSync(flowFilePath, "utf8");
+        const flowDef = JSON.parse(raw);
+        if (!flowDef || !Array.isArray(flowDef.steps) || flowDef.steps.length === 0)
+            return null;
+        const first = flowDef.steps[0];
+        return (first && typeof first.id === "string" && first.id !== "done") ? first.id : null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeCurrent(root, dir, timestamp, owner, source, flowId, stepId) {
     writeJson(path.join(root, "current.json"), {
         schema_version: "1.0",
         active_slug: path.basename(dir),
@@ -314,6 +826,11 @@ function writeCurrent(root, dir, timestamp, owner, source) {
         owner,
         source,
         active_agents: [],
+        // ADR 0016 Abstraction A (P-a): optional FlowDefinition routing keys for the producer
+        // and enforcer. Both fields are optional and backward-compatible — sessions without a
+        // FlowDefinition omit them and fall through to the workflow.* claim type path.
+        ...(flowId ? { active_flow_id: flowId } : {}),
+        ...(stepId ? { active_step_id: stepId } : {}),
     });
 }
 function loadCurrent(root) {
@@ -358,7 +875,7 @@ function initSidecars(dir, slug, sourceRequest, summary, nextAction, timestamp,
 }
 function ensureSession(p) {
     const root = path.resolve(opt(p, "artifact-root", ".flow-agents"));
-    const slug = opt(p, "task-slug") || die("--task-slug is required");
+    const slug = opt(p, "task-slug") || (opt(p, "work-item") ? workItemSlug(opt(p, "work-item")) : die("--task-slug is required (or pass --work-item to derive it)"));
     const dir = sessionDirFor(root, slug);
     fs.mkdirSync(dir, { recursive: true });
     const timestamp = opt(p, "timestamp", now());
@@ -370,7 +887,22 @@ function ensureSession(p) {
     if (!fs.existsSync(path.join(dir, "state.json")) || !fs.existsSync(path.join(dir, "acceptance.json")) || !fs.existsSync(path.join(dir, "handoff.json"))) {
         initSidecars(dir, slug, opt(p, "source-request"), opt(p, "summary"), opt(p, "next-action", "Continue."), timestamp, md);
     }
-    writeCurrent(root, dir, timestamp, "workflow-sidecar", "ensure-session");
+    // ADR 0016 Abstraction A (P-a): optional --flow-id / --step-id flags persist FlowDefinition
+    // routing keys into current.json for the producer (P-b) and enforcer (P-c) to consume.
+    // When absent, behavior is unchanged — the workflow.* claim type path is used as before.
+    // P-d Increment 1 (Q2 decision): when --flow-id is given without --step-id, default
+    // active_step_id to the FIRST step in the FlowDefinition's steps[] list. This ensures
+    // ensure-session --flow-id builder.build produces a FlowDefinition-driven session even
+    // before the first advance-state call.
+    const flowId = opt(p, "flow-id");
+    let stepId = opt(p, "step-id");
+    if (flowId && !stepId) {
+        const repoRoot = findRepoRootFromDir(dir);
+        const firstStep = resolveFirstStep(flowId, repoRoot);
+        if (firstStep)
+            stepId = firstStep;
+    }
+    writeCurrent(root, dir, timestamp, "workflow-sidecar", "ensure-session", flowId || undefined, stepId || undefined);
     console.log(dir);
     return 0;
 }
@@ -406,6 +938,7 @@ function initPlan(p) {
     const dir = artifactDirFrom(artifact);
     const slug = taskSlugFor(dir, opt(p, "task-slug"));
     initSidecars(dir, slug, opt(p, "source-request"), opt(p, "summary"), opt(p, "next-action"), opt(p, "timestamp", now()), read(artifact));
+    livenessLifecycle(dir, slug, "claim", opt(p, "timestamp", now()));
     return 0;
 }
 function parseJson(value, label) {
@@ -428,7 +961,7 @@ function hasNonEmptyString(value) {
 function hasPositiveInteger(value) {
     return Number.isInteger(value) && Number(value) >= 1;
 }
-function validateEvidenceRef(ref, label) {
+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`);
     for (const key of Object.keys(ref))
@@ -458,7 +991,7 @@ function validateEvidenceRef(ref, label) {
         die(`${label} ${ref.kind} refs require url`);
     return ref;
 }
-function normalizeEvidenceRefs(raw, label) {
+export function normalizeEvidenceRefs(raw, label) {
     if (!Array.isArray(raw))
         die(`${label} must be an array`);
     return raw.map((ref) => {
@@ -469,7 +1002,7 @@ function normalizeEvidenceRefs(raw, label) {
         return validateEvidenceRef({ ...ref }, label);
     });
 }
-function normalizeCheck(raw) {
+export function normalizeCheck(raw) {
     const check = { ...raw };
     if (!check.id || !check.kind || !check.status || !check.summary)
         die("check requires id, kind, status, and summary");
@@ -490,7 +1023,10 @@ function normalizeCheck(raw) {
 function normalizeSurfaceRefs(refs) {
     if (!Array.isArray(refs))
         die("surface_trust_refs must be an array");
-    const hachureValidate = getHachureValidator();
+    // Use the cached @kontourai/surface module for advisory inline validation of referenced
+    // trust.bundle files. Fail-open when surface is not yet loaded (surface loads on first
+    // bundle write via tryLoadSurface; normalizeSurfaceRefs may run before that).
+    const surfaceValidateFn = _surfaceModule?.validateTrustBundle ?? null;
     return refs.map((ref) => {
         const keys = JSON.stringify(ref).match(/"([^"]+)":/g) ?? [];
         for (const key of keys.map((k) => k.slice(1, -2)))
@@ -500,19 +1036,21 @@ function normalizeSurfaceRefs(refs) {
         // 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");
-        // When hachure is installed, validate the referenced trust artifact if it is a local file
-        if (hachureValidate && out.artifact_ref && typeof out.artifact_ref === "string" && fs.existsSync(out.artifact_ref)) {
+        // When surface is loaded, validate the referenced trust artifact if it is a local file.
+        // Advisory: surface's throw-based validator wraps into a fail-loud error on schema failure.
+        if (surfaceValidateFn && out.artifact_ref && typeof out.artifact_ref === "string" && fs.existsSync(out.artifact_ref)) {
             try {
                 const bundle = JSON.parse(fs.readFileSync(out.artifact_ref, "utf8"));
-                const result = hachureValidate(bundle);
-                if (!result.valid) {
-                    const errorSummary = result.errors.slice(0, 3).join("; ");
-                    die(`trust.bundle artifact at ${out.artifact_ref} failed Hachure schema validation: ${errorSummary}`);
-                }
+                surfaceValidateFn(bundle);
             }
             catch (err) {
-                if (err instanceof Error && err.message.includes("failed Hachure schema validation"))
-                    throw err;
+                if (err instanceof Error) {
+                    // Re-throw schema validation failures (surface throws on invalid); swallow read/parse errors.
+                    const msg = err.message;
+                    const isSchemaError = !msg.startsWith("ENOENT") && !msg.startsWith("SyntaxError") && !msg.toLowerCase().startsWith("unexpected");
+                    if (isSchemaError)
+                        die(`trust.bundle artifact at ${out.artifact_ref} failed schema validation: ${msg}`);
+                }
                 // File read or parse errors are not re-thrown: the artifact_ref validation path is advisory
             }
         }
@@ -555,17 +1093,6 @@ function surfaceCheckFromArtifact(file, index) {
     }
     return { id: `surface-trust-${index + 1}`, kind: "policy", status: ref.status, summary: ref.summary, surface_trust_refs: [ref] };
 }
-function updateAcceptance(dir, verdict) {
-    const file = path.join(dir, "acceptance.json");
-    if (!fs.existsSync(file))
-        return;
-    const data = loadJson(file);
-    const status = verdict === "pass" ? "pass" : verdict === "fail" ? "fail" : "not_verified";
-    if (Array.isArray(data.criteria))
-        data.criteria = data.criteria.map((c) => ({ ...c, status }));
-    data.goal_fit = { ...(data.goal_fit ?? {}), status, summary: verdict === "pass" ? "Evidence passed." : "Evidence requires follow-up." };
-    writeJson(file, data);
-}
 function validateAcceptanceEvidenceRefs(dir) {
     const file = path.join(dir, "acceptance.json");
     if (!fs.existsSync(file))
@@ -578,10 +1105,120 @@ function validateAcceptanceEvidenceRefs(dir) {
             normalizeEvidenceRefs(criterion.evidence_refs, `acceptance.criteria[${index}].evidence_refs`);
     });
 }
-function writeState(dir, slug, status, phase, timestamp, summary, next = "continue") {
+export function writeState(dir, slug, status, phase, timestamp, summary, next = "continue") {
     writeJson(path.join(dir, "state.json"), { ...loadJson(path.join(dir, "state.json")), ...sidecarBase(slug), status, phase, updated_at: timestamp, artifact_paths: relArtifacts(dir), next_action: { status: next, summary } });
 }
-function recordEvidence(p) {
+// ─── Phase 4c: bundle-only helpers ───────────────────────────────────────────
+// After 4c, evidence.json and critique.json are no longer written.
+// Extract checks and critiques from the existing trust.bundle for callers that
+// need to rebuild the bundle (e.g. record-critique, record-learning).
+// ADR 0016 Abstraction A (Step 0 Q3 carry-forward): build the set of declared
+// claimTypes from the active flow step for the session at `dir`. When no active
+// flow is present (workflow.* sessions), returns an empty set so every existing
+// predicate is unchanged. When a FlowDefinition-driven session (builder.build)
+// is active, the set contains the kit-typed claimTypes (e.g. "builder.verify.tests",
+// "builder.verify.policy-compliance") so round-trip helpers broaden their filters
+// to include declared claims alongside the legacy workflow.* ones.
+//
+// Safety guard: current.json in the .flow-agents dir records the CURRENTLY ACTIVE
+// session via artifact_dir. If current.json points to a different session than `dir`
+// (e.g. another session was the last to call advance-state --flow-definition), we
+// return an empty set so declared-type predicates are NOT applied to the wrong session.
+// This prevents a cross-session active_flow_id from broadening claim filters for
+// unrelated sessions (which would cause spurious evidence/critique check behavior).
+function declaredClaimTypesFor(dir) {
+    const flowAgentsDir = path.dirname(dir);
+    // Verify that current.json points to `dir` before reading active flow step.
+    // If it points to a different session, return empty set (zero behavior change).
+    const currentFile = path.join(flowAgentsDir, "current.json");
+    try {
+        const current = JSON.parse(fs.readFileSync(currentFile, "utf8"));
+        const artDir = typeof current["artifact_dir"] === "string" ? current["artifact_dir"] : null;
+        if (!artDir)
+            return new Set();
+        const resolvedCurrent = path.resolve(flowAgentsDir, artDir);
+        if (path.resolve(dir) !== resolvedCurrent)
+            return new Set();
+    }
+    catch {
+        return new Set();
+    }
+    const activeStep = resolveActiveFlowStep(flowAgentsDir);
+    if (!activeStep || activeStep.gateExpects.length === 0)
+        return new Set();
+    return new Set(activeStep.gateExpects.map((e) => e.bundle_claim.claimType));
+}
+function checksFromBundle(dir, declaredClaimTypes = new Set()) {
+    const bundle = loadJson(path.join(dir, "trust.bundle"));
+    if (!Array.isArray(bundle.evidence))
+        return [];
+    const allClaims = Array.isArray(bundle.claims) ? bundle.claims : [];
+    const claimById = new Map();
+    for (const c of allClaims)
+        if (c && c.id)
+            claimById.set(c.id, c);
+    const seen = new Set();
+    const checks = [];
+    for (const ev of bundle.evidence) {
+        if (!ev || !ev.claimId)
+            continue;
+        const claim = claimById.get(ev.claimId);
+        if (!claim)
+            continue;
+        const ct = String(claim.claimType || "");
+        // ADR 0016 Step 0: broaden to include declared kit-typed claims alongside workflow.check.*
+        if (!ct.startsWith("workflow.check.") && !declaredClaimTypes.has(ct))
+            continue;
+        if (seen.has(ev.claimId))
+            continue;
+        seen.add(ev.claimId);
+        const kind = ct.startsWith("workflow.check.") ? (ct.replace("workflow.check.", "") || "external") : (ct.split(".").pop() || "external");
+        const status = claim.value ?? "not_verified";
+        const check = { id: String(claim.subjectId || "").split("/").pop() || ev.claimId, kind, status, summary: claim.fieldOrBehavior || "" };
+        if (ev.execution && typeof ev.execution.label === "string")
+            check.command = ev.execution.label;
+        if (ev.evidenceType)
+            check.evidenceType = ev.evidenceType;
+        checks.push(check);
+    }
+    // Also include check claims that have no evidence item (surface_trust_refs style)
+    for (const claim of allClaims) {
+        if (!claim)
+            continue;
+        const ct = String(claim.claimType || "");
+        // ADR 0016 Step 0: broaden to include declared kit-typed claims alongside workflow.check.*
+        if (!ct.startsWith("workflow.check.") && !declaredClaimTypes.has(ct))
+            continue;
+        if (seen.has(claim.id))
+            continue;
+        seen.add(claim.id);
+        const kind = ct.startsWith("workflow.check.") ? (ct.replace("workflow.check.", "") || "external") : (ct.split(".").pop() || "external");
+        checks.push({ id: String(claim.subjectId || "").split("/").pop() || claim.id, kind, status: claim.value ?? "not_verified", summary: claim.fieldOrBehavior || "" });
+    }
+    return checks;
+}
+function critiquesFromBundle(dir, declaredClaimTypes = new Set()) {
+    const bundle = loadJson(path.join(dir, "trust.bundle"));
+    if (!Array.isArray(bundle.claims))
+        return [];
+    // ADR 0016 Step 0: broaden to include declared kit-typed critique claims alongside workflow.critique.review.
+    // P-d: exclude claims that have evidence items (evidence = check claims, not critique claims).
+    // This prevents check-type declared claims (e.g. builder.verify.tests) from being read back
+    // as critiques when declaredClaimTypes includes all gate expects[] types.
+    const evidenceClaimIds = new Set(Array.isArray(bundle.evidence) ? bundle.evidence.map((e) => e?.claimId).filter((id) => typeof id === "string") : []);
+    const critiqueClaims = bundle.claims.filter((c) => c && (c.claimType === "workflow.critique.review" || declaredClaimTypes.has(c.claimType)) && !evidenceClaimIds.has(c.id));
+    return critiqueClaims.map((c) => ({
+        id: String(c.subjectId || "").split("/").pop() || c.id,
+        verdict: c.value ?? "not_verified",
+        summary: c.fieldOrBehavior || "",
+        findings: [],
+        reviewer: "tool-code-reviewer",
+        reviewed_at: c.updatedAt || c.createdAt || now(),
+        artifact_refs: [],
+    }));
+}
+// ─────────────────────────────────────────────────────────────────────────────
+async function recordEvidence(p) {
     const dir = artifactDirFrom(p.positional[0] || die("artifact directory is required"));
     const verdict = opt(p, "verdict") || die("--verdict is required");
     if (!verdicts.has(verdict))
@@ -591,11 +1228,15 @@ function recordEvidence(p) {
     if (!checks.length && opts(p, "surface-trust-json").length === 0)
         die("record-evidence requires at least one --check-json or --surface-trust-json");
     validateAcceptanceEvidenceRefs(dir);
-    const payload = { ...sidecarBase(slug), verdict, checks, not_verified_gaps: opts(p, "gap") };
-    writeJson(path.join(dir, "evidence.json"), payload);
-    updateAcceptance(dir, verdict);
+    // Phase 4c: bundle is the sole verification artifact — stop writing evidence.json and acceptance.json update.
+    const ts = opt(p, "timestamp", now());
+    const _existingAcceptance = loadJson(path.join(dir, "acceptance.json"));
+    const _existingCriteria = Array.isArray(_existingAcceptance.criteria) ? _existingAcceptance.criteria : [];
+    const _criteriaStatus = verdict === "pass" ? "pass" : verdict === "fail" ? "fail" : "not_verified";
+    const _criteriaForBundle = _existingCriteria.map((c) => ({ ...c, status: _criteriaStatus }));
+    assertBundleWritten(await writeTrustBundle(dir, slug, ts, checks, _criteriaForBundle, []));
     const stateStatus = verdict === "pass" ? "verified" : verdict === "fail" ? "failed" : "not_verified";
-    writeState(dir, slug, stateStatus, "verification", opt(p, "timestamp", now()), "Evidence recorded.");
+    writeState(dir, slug, stateStatus, "verification", ts, "Evidence recorded.");
     return 0;
 }
 function diagnostic(dir, code, summary) {
@@ -603,7 +1244,90 @@ function diagnostic(dir, code, summary) {
     appendJsonl(path.join(dir, "transition-diagnostics.jsonl"), payload);
     die(`${code}: ${summary}`);
 }
-function advanceState(p) {
+/**
+ * record-gate-claim — Generic gate-claim producer for skills (ADR 0016 P-d Increment 1).
+ *
+ * Allows a skill to record a claim that satisfies a SPECIFIC gate expectation at the
+ * active step. The caller passes:
+ *   --status <pass|fail|not_verified>  (required)
+ *   --summary <text>                   (required)
+ *   --expectation <id>                 (optional; auto-resolved when the gate has one entry)
+ *   --evidence-json <json>             (optional; structured evidence refs)
+ *
+ * The producer emits a check of kind="external" targeting the gate expectation's declared
+ * claimType + subjectType from the active step's expects[]. This populates the trust.bundle
+ * with a correctly-typed claim derived by Surface, suitable for gate enforcement.
+ *
+ * When the gate has exactly ONE expects[] entry, --expectation is optional (auto-resolve).
+ * When the gate has multiple entries, --expectation <id> is required.
+ *
+ * This is what Increment 2's 6 skills will call to satisfy the category (c) gates
+ * (pull-work.selected, design-probe.*, pr-open.pull-request, learn.*) once producers are added.
+ *
+ * Error cases:
+ *   - No active flow/step in current.json → die with actionable message
+ *   - --expectation not found in expects[] → die
+ *   - Multiple expects[] entries and --expectation omitted → die
+ *   - Surface unavailable → assertBundleWritten fails loud (no silent data loss)
+ */
+async function recordGateClaim(p) {
+    const dir = artifactDirFrom(p.positional[0] || die("artifact directory is required"));
+    const slug = taskSlugFor(dir, opt(p, "task-slug"));
+    const ts = opt(p, "timestamp", now());
+    const statusVal = opt(p, "status");
+    if (!["pass", "fail", "not_verified"].includes(statusVal))
+        die("--status must be one of: pass, fail, not_verified");
+    const summary = opt(p, "summary") || die("--summary is required");
+    const expectationId = opt(p, "expectation");
+    // Resolve the active flow step from current.json
+    const flowAgentsDir = path.dirname(dir);
+    const activeStep = resolveActiveFlowStep(flowAgentsDir);
+    if (!activeStep)
+        die("record-gate-claim requires an active flow step in current.json (set via ensure-session --flow-id or advance-state --flow-definition)");
+    const expects = activeStep.gateExpects;
+    if (expects.length === 0)
+        die(`record-gate-claim: active step "${activeStep.stepId}" gate "${activeStep.gateId}" has no expects[] entries`);
+    // Resolve the target expects entry
+    let targetExpectation;
+    if (expectationId) {
+        targetExpectation = expects.find((e) => e.id === expectationId);
+        if (!targetExpectation)
+            die(`record-gate-claim: --expectation "${expectationId}" not found in gate "${activeStep.gateId}" expects[]. Available: ${expects.map((e) => e.id).join(", ")}`);
+    }
+    else if (expects.length === 1) {
+        targetExpectation = expects[0];
+    }
+    else {
+        die(`record-gate-claim: gate "${activeStep.gateId}" has ${expects.length} expects[] entries; --expectation <id> is required. Available: ${expects.map((e) => e.id).join(", ")}`);
+    }
+    const { claimType, subjectType } = targetExpectation.bundle_claim;
+    // Build a synthetic external check that will be matched by matchExpectsEntry to produce
+    // a correctly-typed claim. We use kind="external" so it routes through the non-policy,
+    // non-flow-step fallback path. The subjectType on the resulting claim comes from the
+    // expects[] entry via matchExpectsEntry.
+    const checkId = expectationId || targetExpectation.id;
+    // Build a minimal "external" check. Include _gate_claim_expectation_id so that
+    // matchExpectsEntry can do an exact lookup for multi-expects[] gates (ADR 0016 P-d Increment 2).
+    // normalizeCheck preserves extra underscore-prefixed fields without stripping them.
+    const check = {
+        id: `gate-claim-${checkId}`,
+        kind: "external",
+        status: statusVal,
+        summary,
+        _gate_claim_expectation_id: targetExpectation.id,
+    };
+    // Include structured evidence refs if provided
+    const evidenceRefs = opts(p, "evidence-ref-json").map((v) => validateEvidenceRef(parseJson(v, "--evidence-ref-json"), "--evidence-ref-json"));
+    if (evidenceRefs.length > 0) {
+        check.artifact_refs = evidenceRefs;
+    }
+    const checkNormalized = normalizeCheck(check);
+    // Log the targeted gate expectation for transparency (goes to stderr only)
+    process.stderr.write(`[record-gate-claim] targeting ${activeStep.stepId}/${activeStep.gateId}/${targetExpectation.id} → claimType=${claimType} subjectType=${subjectType}\n`);
+    assertBundleWritten(await writeTrustBundle(dir, slug, ts, [checkNormalized], [], []));
+    return 0;
+}
+async function advanceState(p) {
     const dir = artifactDirFrom(p.positional[0] || die("artifact directory is required"));
     const status = opt(p, "status");
     const phase = opt(p, "phase");
@@ -635,29 +1359,50 @@ function advanceState(p) {
     const timestamp = opt(p, "timestamp", now());
     writeState(dir, slug, status, phase, timestamp, opt(p, "summary"));
     writeJson(path.join(dir, "handoff.json"), { ...loadJson(path.join(dir, "handoff.json")), ...sidecarBase(slug), summary: opt(p, "summary"), current_state_ref: "state.json", next_steps: [opt(p, "next-action")].filter(Boolean), blockers: [], warnings: [] });
+    // ADR 0016 Abstraction A (P-d, Increment 1): when --flow-definition is provided,
+    // resolve the phase→step mapping from the FlowDefinition and write active_step_id
+    // into current.json. This is the single setter — no skill needs to call ensure-session
+    // --step-id individually. The repoRoot is derived by walking up from dir to find kits/.
+    if (flow) {
+        const root = path.resolve(opt(p, "artifact-root", path.dirname(dir)));
+        const repoRoot = findRepoRootFromDir(dir);
+        const phaseMap = resolvePhaseMap(flow, repoRoot);
+        const stepId = phaseMap?.[phase] ?? undefined;
+        if (stepId) {
+            writeCurrent(root, dir, timestamp, "workflow-sidecar", "advance-state", flow, stepId);
+        }
+    }
+    livenessLifecycle(dir, slug, LIVENESS_TERMINAL.has(status) ? "release" : "heartbeat", timestamp);
+    // Trust checkpoint: when advancing to a terminal delivered status, seal the checkpoint.
+    if (status === "delivered") {
+        await sealTrustCheckpoint(dir, slug, timestamp, status, "release").catch(() => { });
+        // Publish delivery bundle: best-effort copy to delivery/ for CI trust-reconcile.
+        await publishDelivery(dir, findRepoRootFromDir(dir)).catch(() => { });
+    }
     return 0;
 }
-function normalizeFinding(raw) {
+export function normalizeFinding(raw) {
     if (raw.file_refs !== undefined && !Array.isArray(raw.file_refs))
         die("file_refs must be an array");
     return raw;
 }
-function critiqueStatus(critiques, required) {
-    if (!required && critiques.length === 0)
-        return "not_required";
-    if (critiques.some((c) => c.verdict === "fail" || (Array.isArray(c.findings) && c.findings.some((f) => f.status === "open"))))
-        return "fail";
-    return "pass";
-}
-function recordCritique(p) {
+async function recordCritique(p) {
     const dir = artifactDirFrom(p.positional[0] || die("artifact directory is required"));
     const slug = taskSlugFor(dir, opt(p, "task-slug"));
-    const existing = loadJson(path.join(dir, "critique.json"), { critiques: [] });
+    // Phase 4c: accumulate existing critiques from trust.bundle (critique.json no longer written).
+    // Fall back to critique.json for legacy sessions that still have it on disk.
+    const existingCritiqueJson = loadJson(path.join(dir, "critique.json"), { critiques: [] });
+    const legacyCritiques = Array.isArray(existingCritiqueJson.critiques) ? existingCritiqueJson.critiques : [];
+    const _dctCritique = declaredClaimTypesFor(dir);
+    const bundleCritiques = legacyCritiques.length === 0 ? critiquesFromBundle(dir, _dctCritique) : legacyCritiques;
     const critique = { id: opt(p, "id") || "review", reviewer: opt(p, "reviewer", "tool-code-reviewer"), reviewed_at: opt(p, "timestamp", now()), verdict: opt(p, "verdict", "pass"), summary: opt(p, "summary"), artifact_refs: opts(p, "artifact-ref"), findings: opts(p, "finding-json").map((v) => normalizeFinding(parseJson(v, "--finding-json"))) };
-    const critiques = [...(Array.isArray(existing.critiques) ? existing.critiques : []), critique];
+    const critiques = [...bundleCritiques, critique];
     if (critique.verdict === "pass" && critique.findings.some((f) => f.status === "open"))
         die("required critique must pass");
-    writeJson(path.join(dir, "critique.json"), { ...sidecarBase(slug), status: critiqueStatus(critiques, true), required: true, updated_at: critique.reviewed_at, critiques });
+    // Phase 4c: build bundle from raw inputs; read checks from trust.bundle (evidence.json no longer written).
+    const _critiqueEvChecks = checksFromBundle(dir, _dctCritique);
+    const _critiqueAccCriteria = Array.isArray(loadJson(path.join(dir, "acceptance.json")).criteria) ? loadJson(path.join(dir, "acceptance.json")).criteria : [];
+    assertBundleWritten(await writeTrustBundle(dir, slug, critique.reviewed_at, _critiqueEvChecks, _critiqueAccCriteria, critiques));
     return 0;
 }
 function frontmatter(text, key) {
@@ -668,7 +1413,7 @@ function frontmatter(text, key) {
         return "";
     return new RegExp(`^${key}:\\s*(.+)$`, "m").exec(text.slice(0, end))?.[1]?.trim() ?? "";
 }
-function importCritique(p) {
+async function importCritique(p) {
     const dir = artifactDirFrom(p.positional[0] || die("artifact directory is required"));
     const review = p.positional[1] || die("review artifact is required");
     const text = read(review);
@@ -684,12 +1429,12 @@ function importCritique(p) {
         findings.push({ id: slugify(title, `finding-${findings.length + 1}`), severity: (m.groups?.severity ?? "info").toLowerCase(), status: opt(p, "finding-status", verdict === "pass" ? "fixed" : "open"), description: title, file_refs: [m.groups?.target ?? review] });
     }
     const parsed = { ...p, positional: [dir], opts: { ...p.opts, id: [slugify(path.basename(review).replace(/\.md$/, ""), "review")], reviewer: ["tool-code-reviewer"], verdict: [verdict], summary: [`Imported critique from ${path.basename(review)}`], "finding-json": findings.map((f) => JSON.stringify(f)) }, flags: p.flags };
-    const result = recordCritique(parsed);
+    const result = await recordCritique(parsed);
     if (verdict !== "pass")
         die("required critique must pass");
     return result;
 }
-function recordRelease(p) {
+async function recordRelease(p) {
     const dir = artifactDirFrom(p.positional[0] || die("artifact directory is required"));
     const slug = taskSlugFor(dir, opt(p, "task-slug"));
     const decision = opt(p, "decision");
@@ -702,9 +1447,267 @@ function recordRelease(p) {
     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);
+    // Trust checkpoint: seal at the "delivered" moment (the natural terminal mark for record-release).
+    await sealTrustCheckpoint(dir, slug, payload.updated_at, "delivered", "release").catch(() => { });
+    // Publish delivery bundle: best-effort copy to delivery/ for CI trust-reconcile.
+    await publishDelivery(dir, findRepoRootFromDir(dir)).catch(() => { });
+    return 0;
+}
+// ─── Trust Checkpoint (Increment A) ──────────────────────────────────────────
+// Per-run frozen snapshot of verified trust state at completion. Written to
+// trust.checkpoint.json alongside the other workflow sidecars.
+// Surface owns the DerivationCheckpoint shape; flow-agents wraps it in an
+// ENVELOPE that adds per-run context surface does not carry.
+//
+// Envelope shape:
+//   {
+//     schema_version: "1.0",
+//     slug: string,
+//     work_item: string | null,
+//     status: string,
+//     phase: string,
+//     sealed_at: ISO-8601,
+//     commit_sha: string | null,
+//     checkpoint: DerivationCheckpoint   ← surface owns this
+//   }
+//
+// Idempotent: re-running advance-state / record-release to the same terminal
+// status overwrites with the latest snapshot.
+// Fail-open: if no trust.bundle exists, or Surface is unavailable, the write
+// is skipped gracefully (no error surfaced to the caller).
+/** Derive the current git HEAD sha — null if unavailable (not in a repo, git absent). */
+function resolveCommitSha() {
+    try {
+        return execFileSync("git", ["rev-parse", "HEAD"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Build and write trust.checkpoint.json for a completed run.
+ * Skips silently when:
+ *   - trust.bundle is absent (no evidence recorded yet)
+ *   - Surface is unavailable (checkpointFromReport not found)
+ * The caller wraps this in .catch() so it never breaks the parent command.
+ *
+ * Increment B1 — checkpoint signing at the release boundary:
+ * After the checkpoint is written, attempts Sigstore keyless signing (OIDC).
+ *   - CI/OIDC available:   writes trust.checkpoint.sig.json (cosign-verifiable DSSE envelope)
+ *                          and writes attestation:{status:"signed",...} to trust.checkpoint.attestation.json.
+ *   - Local (no OIDC):     writes trust.checkpoint.intoto.json (unsigned in-toto statement)
+ *                          and writes attestation:{status:"unsigned",...} to trust.checkpoint.attestation.json.
+ * Signing is ALWAYS fail-open — a signing failure never breaks the seal.
+ */
+export async function sealTrustCheckpoint(dir, slug, sealedAt, status, phase) {
+    const bundlePath = path.join(dir, "trust.bundle");
+    if (!fs.existsSync(bundlePath))
+        return; // no bundle — skip gracefully
+    const surface = await tryLoadSurface();
+    if (!surface || typeof surface.checkpointFromReport !== "function" || typeof surface.buildTrustReport !== "function")
+        return; // Surface unavailable
+    const bundle = JSON.parse(fs.readFileSync(bundlePath, "utf8"));
+    const report = surface.buildTrustReport(bundle);
+    const checkpoint = surface.checkpointFromReport(report);
+    // Derive work_item from state.json if present (best-effort)
+    let workItem = null;
+    try {
+        const stateRaw = loadJson(path.join(dir, "state.json"));
+        if (typeof stateRaw.work_item === "string")
+            workItem = stateRaw.work_item;
+    }
+    catch { /* ignored */ }
+    const checkpointPath = path.join(dir, "trust.checkpoint.json");
+    const envelope = {
+        schema_version: "1.0",
+        slug,
+        work_item: workItem,
+        status,
+        phase,
+        sealed_at: sealedAt,
+        commit_sha: resolveCommitSha(),
+        checkpoint,
+    };
+    writeJson(checkpointPath, envelope);
+    // ─── Increment B1: sign the checkpoint at the release boundary ───────────────
+    // Additive: if surface lacks in-toto/sigstore primitives, skip silently.
+    // The .catch() at the call site already guards the parent command; this inner
+    // catch is defense-in-depth so signing never propagates an error upward.
+    await signCheckpointAttestation(dir, surface, bundle, checkpointPath).catch((err) => {
+        process.stderr.write(`[checkpoint-signing] signing skipped due to error: ${err instanceof Error ? err.message : String(err)}\n`);
+    });
+}
+/**
+ * Increment B1 — Sign the trust checkpoint with in-toto/Sigstore.
+ *
+ * Called from sealTrustCheckpoint AFTER trust.checkpoint.json is written.
+ * Computes the sha256 digest of the checkpoint file, builds an in-toto Statement
+ * (predicate = trust bundle), and attempts Sigstore keyless signing.
+ *
+ *   - Signed (CI/OIDC):  writes trust.checkpoint.sig.json (DSSE envelope, cosign-verifiable).
+ *   - Unsigned (local):  writes trust.checkpoint.intoto.json (unsigned statement).
+ *   - Always writes:     trust.checkpoint.attestation.json with attestation:{status,path,...}.
+ *                        trust.checkpoint.json is NOT modified after its digest is computed.
+ *
+ * NEVER throws — all errors are caught and surfaced as stderr warnings.
+ * Skips silently when Surface's toInTotoStatement / signStatementWithSigstore are absent.
+ *
+ * @param dir            Session artifact directory.
+ * @param surface        Loaded Surface module (may or may not have in-toto/sigstore exports).
+ * @param bundle         Parsed trust.bundle (becomes the in-toto predicate).
+ * @param checkpointPath Absolute path to the already-written trust.checkpoint.json.
+ */
+async function signCheckpointAttestation(dir, surface, bundle, checkpointPath) {
+    // Guard: both primitives must be present (consumed from Surface, never reimplemented).
+    if (typeof surface.toInTotoStatement !== "function" || typeof surface.signStatementWithSigstore !== "function") {
+        process.stderr.write("[checkpoint-signing] Surface in-toto/sigstore primitives unavailable — skipping attestation\n");
+        return;
+    }
+    // Step A: compute sha256 digest of trust.checkpoint.json (the SUBJECT).
+    // The checkpoint is self-evidencing — its digest is the external anchor.
+    const checkpointBytes = fs.readFileSync(checkpointPath);
+    const sha256hex = createHash("sha256").update(checkpointBytes).digest("hex");
+    // Step B: build the in-toto Statement.
+    //   subject  = the checkpoint file (what we are attesting TO)
+    //   predicate = the trust bundle   (what the checkpoint CONTAINS)
+    const subjects = [{ name: "trust.checkpoint.json", digest: { sha256: sha256hex } }];
+    const statement = surface.toInTotoStatement(bundle, { subjects });
+    // Step C: attempt Sigstore keyless signing (PRIMARY path).
+    // signStatementWithSigstore returns null when no ambient OIDC credential is available
+    // (local development, no ACTIONS_ID_TOKEN_REQUEST_URL). This is the expected local case.
+    let signed = null;
+    try {
+        signed = await surface.signStatementWithSigstore(statement);
+    }
+    catch (err) {
+        // signStatementWithSigstore may throw on unexpected failures (network error, config error);
+        // treat as fail-open: fall through to the unsigned path.
+        process.stderr.write(`[checkpoint-signing] signStatementWithSigstore threw: ${err instanceof Error ? err.message : String(err)}\n`);
+        signed = null;
+    }
+    let attestation;
+    if (signed) {
+        // CI/OIDC path: write the cosign-verifiable DSSE envelope.
+        const sigPath = path.join(dir, "trust.checkpoint.sig.json");
+        writeJson(sigPath, signed.envelope);
+        const keyid = signed.envelope.signatures[0]?.keyid ?? "";
+        attestation = {
+            status: "signed",
+            path: "trust.checkpoint.sig.json",
+            keyid,
+        };
+        process.stderr.write(`[checkpoint-signing] checkpoint signed with Sigstore — envelope written to ${sigPath}\n`);
+    }
+    else {
+        // Local/unsigned path: write the unsigned in-toto statement for audit purposes.
+        const unsignedPath = path.join(dir, "trust.checkpoint.intoto.json");
+        writeJson(unsignedPath, statement);
+        attestation = {
+            status: "unsigned",
+            path: "trust.checkpoint.intoto.json",
+            reason: "no ambient signing identity",
+        };
+        process.stderr.write("[checkpoint-signing] no ambient OIDC identity — unsigned in-toto statement written (expected locally)\n");
+    }
+    // Step D: write the attestation record to a SEPARATE companion file.
+    // trust.checkpoint.json is NOT modified — it must remain byte-identical to what was signed.
+    // The companion file carries the pointer/status; the subject-digest binding in the
+    // in-toto statement ties it back to the checkpoint without breaking the digest.
+    const attestationPath = path.join(dir, "trust.checkpoint.attestation.json");
+    writeJson(attestationPath, attestation);
+}
+/**
+ * seal-checkpoint <dir> [--timestamp <iso>]
+ *
+ * Explicit seal of the trust checkpoint for the given artifact dir.
+ * Equivalent to the seal that fires automatically at record-release / advance-state
+ * to delivered. Useful for the deliver skill or a human to seal explicitly without
+ * re-running advance-state.
+ *
+ * Usage: workflow-sidecar seal-checkpoint <artifactDir> [--timestamp <iso>]
+ */
+async function sealCheckpoint(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 stateRaw = loadJson(path.join(dir, "state.json"));
+    const status = typeof stateRaw.status === "string" ? stateRaw.status : "delivered";
+    const phase = typeof stateRaw.phase === "string" ? stateRaw.phase : "release";
+    const bundlePath = path.join(dir, "trust.bundle");
+    if (!fs.existsSync(bundlePath)) {
+        process.stderr.write(`[seal-checkpoint] no trust.bundle at ${bundlePath} — skipping (nothing to seal)
+`);
+        return 0;
+    }
+    await sealTrustCheckpoint(dir, slug, timestamp, status, phase);
+    const checkpointPath = path.join(dir, "trust.checkpoint.json");
+    if (fs.existsSync(checkpointPath)) {
+        console.log(checkpointPath);
+    }
+    else {
+        process.stderr.write(`[seal-checkpoint] checkpoint was not written — @kontourai/surface may be unavailable
+`);
+    }
+    return 0;
+}
+// ─── Publish Delivery Bundle ──────────────────────────────────────────────────
+// Copies the session's trust.bundle (+ checkpoint companions) from the gitignored
+// session artifact dir (.flow-agents/<slug>/) to the committed delivery/ transport
+// path so the CI trust-reconcile job can reconcile it against fresh CI results.
+//
+// Fail-soft: if trust.bundle is absent (no evidence recorded yet), does nothing.
+// Idempotent: overwrites on re-delivery.
+// Called automatically from recordRelease and advanceState→delivered (best-effort).
+// Also exposed as the `publish-delivery <artifact-dir>` subcommand for explicit use.
+/**
+ * Publish the session's trust artifacts to the committed delivery/ path.
+ *
+ * Copies trust.bundle, trust.checkpoint.json, and (if present)
+ * trust.checkpoint.intoto.json / trust.checkpoint.sig.json from the
+ * session artifact dir to <repoRoot>/delivery/.
+ *
+ * Fail-soft: if trust.bundle is absent, returns without throwing.
+ * Idempotent: overwrites on re-delivery.
+ */
+export async function publishDelivery(dir, repoRoot) {
+    const bundleSrc = path.join(dir, "trust.bundle");
+    if (!fs.existsSync(bundleSrc))
+        return; // no bundle — skip gracefully
+    const deliveryDir = path.join(repoRoot, "delivery");
+    fs.mkdirSync(deliveryDir, { recursive: true });
+    // Required: trust.bundle (the CI anchor)
+    fs.copyFileSync(bundleSrc, path.join(deliveryDir, "trust.bundle"));
+    // Optional companions: checkpoint + signing artifacts
+    const companions = [
+        "trust.checkpoint.json",
+        "trust.checkpoint.intoto.json",
+        "trust.checkpoint.sig.json",
+    ];
+    for (const filename of companions) {
+        const src = path.join(dir, filename);
+        if (fs.existsSync(src)) {
+            fs.copyFileSync(src, path.join(deliveryDir, filename));
+        }
+    }
+    process.stderr.write(`[publish-delivery] published trust.bundle and companions to ${deliveryDir}\n`);
+}
+/**
+ * publish-delivery <artifact-dir> [--repo-root <path>]
+ *
+ * Explicit publish of the session trust bundle to the committed delivery/ path.
+ * Equivalent to the publish that fires automatically at record-release /
+ * advance-state to delivered. Useful for the deliver skill or a human to
+ * publish explicitly.
+ *
+ * Usage: workflow-sidecar publish-delivery <artifactDir> [--repo-root <path>]
+ */
+async function publishDeliveryCmd(p) {
+    const dir = artifactDirFrom(p.positional[0] || die("artifact directory is required"));
+    const repoRoot = opt(p, "repo-root") || findRepoRootFromDir(dir);
+    await publishDelivery(dir, repoRoot);
     return 0;
 }
-function validateLearningCorrection(record) {
+export function validateLearningCorrection(record) {
     const correction = record.correction;
     if (correction === undefined)
         return;
@@ -747,7 +1750,7 @@ 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");
 }
-function normalizeLearning(raw, timestamp) {
+export function normalizeLearning(raw, timestamp) {
     if (!Array.isArray(raw.source_refs))
         die("source_refs must be an array");
     if (!Array.isArray(raw.facts))
@@ -759,7 +1762,7 @@ function normalizeLearning(raw, timestamp) {
     validateLearningCorrection(raw);
     return { recorded_at: timestamp, ...raw };
 }
-function recordLearning(p) {
+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());
@@ -771,9 +1774,35 @@ function recordLearning(p) {
         die("learning status learned requires every record to include correction.needed");
     writeJson(path.join(dir, "learning.json"), { ...sidecarBase(slug), status, updated_at: timestamp, records });
     writeState(dir, slug, "accepted", "learning", timestamp, opt(p, "summary"));
+    // Phase 4c: build bundle from raw inputs; read checks/critiques from trust.bundle (bespoke sidecars no longer written).
+    // ADR 0016 Step 0: pass declaredClaimTypes so declared builder.* claims survive the round-trip.
+    const _dctLearning = declaredClaimTypesFor(dir);
+    const _learningChecks = checksFromBundle(dir, _dctLearning);
+    const _learningCriteria = Array.isArray(loadJson(path.join(dir, "acceptance.json")).criteria) ? loadJson(path.join(dir, "acceptance.json")).criteria : [];
+    const _learningCritiques = critiquesFromBundle(dir, _dctLearning);
+    assertBundleWritten(await writeTrustBundle(dir, slug, timestamp, _learningChecks, _learningCriteria, _learningCritiques));
     return 0;
 }
-function evidenceClean(dir) {
+function evidenceClean(dir, declaredClaimTypes = new Set()) {
+    // Phase 4c: read from trust.bundle (sole verification artifact); fall back to evidence.json for legacy sessions.
+    // ADR 0016 Step 0: declaredClaimTypes broadens the filter to include kit-typed check claims
+    // (e.g. builder.verify.tests) in addition to workflow.check.* for FlowDefinition-driven sessions.
+    const bundle = loadJson(path.join(dir, "trust.bundle"));
+    if (Array.isArray(bundle.claims)) {
+        const checkClaims = bundle.claims.filter((c) => {
+            if (!c)
+                return false;
+            const ct = String(c.claimType || "");
+            return ct.startsWith("workflow.check.") || declaredClaimTypes.has(ct);
+        });
+        if (checkClaims.length === 0)
+            return false;
+        return checkClaims.every((c) => {
+            const v = String(c.value || "");
+            return v === "pass" || v === "skip";
+        });
+    }
+    // Legacy fallback: evidence.json
     const e = loadJson(path.join(dir, "evidence.json"), {});
     return e.verdict === "pass" && Array.isArray(e.checks) && e.checks.length > 0 && e.checks.every((c) => {
         if (!(c.status === "pass" || c.status === "skip"))
@@ -781,7 +1810,21 @@ function evidenceClean(dir) {
         return !Array.isArray(c.standard_refs) || c.standard_refs.every((r) => ["junit", "sarif", "coverage", "veritas"].includes(r.standard));
     });
 }
-function critiqueClean(dir) {
+function critiqueClean(dir, declaredClaimTypes = new Set()) {
+    // Phase 4c: read from trust.bundle (sole verification artifact); fall back to critique.json for legacy sessions.
+    // ADR 0016 Step 0: declaredClaimTypes broadens the filter to include kit-typed critique claims
+    // (e.g. builder.verify.policy-compliance) in addition to workflow.critique.review.
+    const bundle = loadJson(path.join(dir, "trust.bundle"));
+    if (Array.isArray(bundle.claims)) {
+        const critiqueClaims = bundle.claims.filter((c) => c && (c.claimType === "workflow.critique.review" || declaredClaimTypes.has(c.claimType)));
+        if (critiqueClaims.length === 0)
+            return false; // no critique written yet
+        return critiqueClaims.every((c) => {
+            const v = String(c.value || "");
+            return v !== "fail" && c.status !== "disputed" && c.status !== "rejected";
+        });
+    }
+    // Legacy fallback: critique.json
     const c = loadJson(path.join(dir, "critique.json"), {});
     return c.status === "pass" && Array.isArray(c.critiques) && c.critiques.every((x) => x.verdict !== "fail" && (!Array.isArray(x.findings) || x.findings.every((f) => f.status !== "open" && (f.file_refs === undefined || Array.isArray(f.file_refs)))));
 }
@@ -804,7 +1847,7 @@ function assertExistingLearningValid(dir) {
             die("learning status learned requires every record to include correction.needed");
     }
 }
-function dogfoodPass(p) {
+async function dogfoodPass(p) {
     const root = path.resolve(opt(p, "artifact-root", ".flow-agents"));
     const dir = path.resolve(opt(p, "artifact-dir") || currentDir(root) || "");
     requireArtifactDirUnderRoot(dir, root);
@@ -814,9 +1857,16 @@ function dogfoodPass(p) {
         const checks = opts(p, "check-json").map((v) => normalizeCheck(parseJson(v, "--check-json")));
         if (checks.some((c) => c.status !== "pass" && c.status !== "skip"))
             die("clean evidence requires all non-skipped checks to pass");
-        if (fs.existsSync(path.join(dir, "evidence.json")) && !evidenceClean(dir))
+        // Phase 4c: evidence check reads from trust.bundle (sole verification artifact); legacy evidence.json fallback in evidenceClean.
+        // ADR 0016 Step 0: pass declaredClaimTypes so builder.* check/critique claims count as clean evidence.
+        const _dctDogfood = declaredClaimTypesFor(dir);
+        const _hasBundleEvidence = fs.existsSync(path.join(dir, "trust.bundle")) && evidenceClean(dir, _dctDogfood);
+        const _hasLegacyEvidence = fs.existsSync(path.join(dir, "evidence.json")) && evidenceClean(dir, _dctDogfood);
+        if (!_hasBundleEvidence && !_hasLegacyEvidence && fs.existsSync(path.join(dir, "trust.bundle")))
             die("cannot mark clean without passing evidence");
-        if (!fs.existsSync(path.join(dir, "evidence.json")) && checks.length === 0)
+        if (!_hasBundleEvidence && !_hasLegacyEvidence && !fs.existsSync(path.join(dir, "trust.bundle")) && fs.existsSync(path.join(dir, "evidence.json")))
+            die("cannot mark clean without passing evidence");
+        if (!_hasBundleEvidence && !_hasLegacyEvidence && !fs.existsSync(path.join(dir, "trust.bundle")) && !fs.existsSync(path.join(dir, "evidence.json")) && checks.length === 0)
             die("cannot mark clean without passing evidence");
         if (p.flags.has("require-critique") || opt(p, "release-decision")) {
             const newCritiqueVerdict = opt(p, "critique-verdict", "pass");
@@ -824,9 +1874,10 @@ function dogfoodPass(p) {
                 normalizeFinding(parseJson(value, "--finding-json"));
             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))
+            if (!opt(p, "critique-id") && !critiqueClean(dir, _dctDogfood))
                 die("requires passing critique");
-            if (fs.existsSync(path.join(dir, "critique.json")) && !critiqueClean(dir))
+            // Phase 4c: if existing state has a dirty critique (in bundle or legacy critique.json), block even when adding a new critique-id.
+            if (!critiqueClean(dir, _dctDogfood) && (fs.existsSync(path.join(dir, "trust.bundle")) || fs.existsSync(path.join(dir, "critique.json"))))
                 die(opt(p, "release-decision") ? "requires clean critique" : "requires clean critique before recording pass evidence");
         }
     }
@@ -836,11 +1887,11 @@ function dogfoodPass(p) {
     if (opt(p, "learning-status") === "learned" && learningRecords.some((r) => r.correction === undefined))
         die("learned status requires every learning record to include correction.needed");
     if (opts(p, "check-json").length)
-        recordEvidence({ ...p, positional: [dir], opts: { ...p.opts, verdict: [verdict] }, flags: p.flags });
+        await recordEvidence({ ...p, positional: [dir], opts: { ...p.opts, verdict: [verdict] }, flags: p.flags });
     if (p.flags.has("require-critique") && opt(p, "critique-id"))
-        recordCritique({ ...p, positional: [dir], opts: { ...p.opts, id: [opt(p, "critique-id")], verdict: [opt(p, "critique-verdict", "pass")], summary: [opt(p, "critique-summary", opt(p, "summary"))] }, flags: p.flags });
+        await recordCritique({ ...p, positional: [dir], opts: { ...p.opts, id: [opt(p, "critique-id")], verdict: [opt(p, "critique-verdict", "pass")], summary: [opt(p, "critique-summary", opt(p, "summary"))] }, flags: p.flags });
     if (learningRecords.length)
-        recordLearning({ ...p, positional: [dir], opts: { ...p.opts, status: [opt(p, "learning-status", "learned")], "record-json": opts(p, "learning-record-json"), summary: [opt(p, "learning-summary", opt(p, "summary"))] }, flags: p.flags });
+        await recordLearning({ ...p, positional: [dir], opts: { ...p.opts, status: [opt(p, "learning-status", "learned")], "record-json": opts(p, "learning-record-json"), summary: [opt(p, "learning-summary", opt(p, "summary"))] }, flags: p.flags });
     if (opt(p, "release-decision")) {
         recordRelease({ ...p, positional: [dir], opts: { ...p.opts, decision: [opt(p, "release-decision")], scope: [opt(p, "release-scope")], summary: [opt(p, "release-summary", opt(p, "summary"))], "gate-json": ['{"name":"merge","status":"pass","summary":"Dogfood release gate passed."}'], "evidence-ref": ["evidence.json"], "docs-json": [`{"status":"updated","summary":"Docs updated.","refs":["${opt(p, "release-doc-ref", "docs/workflow-usage-guide.md")}"]}`] }, flags: p.flags });
         printJson({ release_decision: opt(p, "release-decision") });
@@ -853,14 +1904,821 @@ function dogfoodPass(p) {
         writeJson(path.join(dir, "handoff.json"), handoff);
     }
     writeState(dir, taskSlugFor(dir, opt(p, "task-slug")), stateStatus, "verification", opt(p, "timestamp", now()), opt(p, "summary"), verdict === "pass" ? "continue" : "blocked");
+    // Phase 4c: bundle was already written by recordEvidence/recordCritique above (if called).
+    // If neither ran (e.g. verdict=fail with no check-json), re-build from bundle (no bespoke sidecars).
     printJson({ state_status: stateStatus });
     return 0;
 }
+/**
+ * Read the gate block signal from .flow-agents/.goal-fit-block-streak.json
+ * (written by scripts/hooks/stop-goal-fit.js when block mode fires).
+ * The file sits at <artifact-root>/.goal-fit-block-streak.json — one level
+ * above the session artifact dir. Fail-open: returns { blocked: false } when
+ * the file is absent or unreadable.
+ *
+ * @param artifactRoot  The .flow-agents root dir (parent of session slug dir).
+ */
+export function readGateBlockSignal(artifactRoot) {
+    const streakFile = path.join(artifactRoot, ".goal-fit-block-streak.json");
+    try {
+        if (!fs.existsSync(streakFile))
+            return { blocked: false, hash: null, count: 0 };
+        const raw = JSON.parse(fs.readFileSync(streakFile, "utf8"));
+        const count = Number(raw?.count ?? 0);
+        const hash = typeof raw?.hash === "string" ? raw.hash : null;
+        return { blocked: count >= 1, hash, count };
+    }
+    catch {
+        return { blocked: false, hash: null, count: 0 };
+    }
+}
+/**
+ * Derive the gate-review calibration from a resolved InquiryRecord and the
+ * block signal.  Pure function — no I/O.
+ *
+ * Mapping (mirrors SKILL.md Bundle-Claim to Classification table):
+ *   outcome="matched", status="disputed"|"rejected", blocked=true  → correct
+ *   outcome="matched", status="verified"|"assumed",  blocked=true  → false_block
+ *   outcome="matched", status="assumed",             blocked=true  → false_block
+ *   outcome="matched", status="stale"|"unknown",     blocked=false → missed_block
+ *   outcome="matched", status="proposed",            any          → missed_block
+ *   outcome="unsupported" (absent claim),            any          → missed_block
+ *   outcome="derived",   satisfied=true,             any          → correct/false_block by blocked flag
+ *   fallthrough                                                    → missed_block
+ */
+export function deriveGateCalibration(outcome, answerStatus, blocked) {
+    if (outcome === "unsupported")
+        return "missed_block";
+    if (outcome === "matched" || outcome === "derived") {
+        const s = answerStatus ?? "unknown";
+        if (blocked) {
+            if (s === "disputed" || s === "rejected")
+                return "correct";
+            if (s === "verified" || s === "assumed")
+                return "false_block";
+            // stale/unknown/proposed while blocked — gate fired without solid evidence
+            return "false_block";
+        }
+        else {
+            // Not blocked
+            if (s === "stale" || s === "unknown" || s === "proposed")
+                return "missed_block";
+            // verified/assumed and no block — correct (no block warranted, none issued)
+            return "correct";
+        }
+    }
+    return "missed_block";
+}
+/**
+ * Compose the advisory proposed-fix string for a gate-review finding.
+ * Pure function — no I/O.
+ */
+export function gateAdvisoryFix(calibration, claimId, answerStatus) {
+    const s = answerStatus ?? "unknown";
+    if (calibration === "correct") {
+        return `No gate change needed — block was warranted. Resolve the failure in claim \`${claimId}\` (status: \`${s}\`) and re-run gate-review to confirm the gate clears.`;
+    }
+    if (calibration === "false_block") {
+        return `Investigate why the gate blocked when claim \`${claimId}\` has status \`${s}\`. Check whether stop-goal-fit evaluated a stale bundle snapshot or whether the block trigger was unrelated to bundle claims. If the block was spurious, add a freshness check to the gate evaluation loop.`;
+    }
+    // missed_block
+    if (s === "stale") {
+        return `Refresh the stale claim \`${claimId}\` by re-running the evidence capture step, then re-run gate-review to confirm the gate fires on updated data.`;
+    }
+    if (s === "absent") {
+        return `Ensure \`workflow-sidecar record-evidence\` writes a bundle claim for \`${claimId}\` before \`stop-goal-fit\` evaluates. Currently no claim exists in the bundle — the gate has nothing to evaluate.`;
+    }
+    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.
+ * 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 }.
+ */
+function toSchemaInquiryRecord(raw, calibration, advisoryFix, blocked, slug) {
+    const resolutionPath = { claimIds: raw.resolutionPath.claimIds };
+    if (raw.resolutionPath.ruleId !== undefined)
+        resolutionPath["ruleId"] = raw.resolutionPath.ruleId;
+    if (raw.resolutionPath.ruleVersion !== undefined)
+        resolutionPath["ruleVersion"] = raw.resolutionPath.ruleVersion;
+    const record = {
+        id: raw.id,
+        inquiry: raw.inquiry,
+        outcome: raw.outcome,
+        resolutionPath,
+        inputSnapshot: raw.inputSnapshot,
+        statusFunctionVersion: raw.statusFunctionVersion,
+        resolvedAt: raw.resolvedAt,
+    };
+    // answer carries the canonical trust status AND gate-review's value-add advisory fix.
+    // answer.status = derived TrustStatus from the resolved claim (or "unknown" when absent).
+    // answer.value = { calibration, advisoryFix, gateFired, sessionSlug } — gate-review advisory.
+    const answerStatus = raw.answer?.status ?? "unknown";
+    record["answer"] = {
+        status: answerStatus,
+        value: {
+            calibration,
+            advisoryFix,
+            gateFired: blocked,
+            sessionSlug: slug,
+        },
+    };
+    return record;
+}
+/**
+ * Build an array of canonical InquiryRecords for all gate-fire and missed-block
+ * candidates in the bundle, using Surface's resolveInquiry.  Returns null when
+ * Surface is unavailable (caller skips the output file — no fork fallback).
+ *
+ * @param bundle              Parsed trust.bundle (BundleFile shape)
+ * @param blockSignal         Result of readGateBlockSignal()
+ * @param slug                Task slug (used in inquiry ids and session_slug)
+ * @param expectedCriterionIds Optional list of expected criterion IDs to check
+ *                            for absent claims (missed_block detection).
+ * @param surface             Loaded Surface module (must have resolveInquiry)
+ * @param now                 Optional timestamp override for deterministic tests
+ */
+export function buildGateInquiryRecords(bundle, blockSignal, slug, expectedCriterionIds, surface, now) {
+    const records = [];
+    let idx = 0;
+    const askedAt = (now ?? new Date()).toISOString();
+    const bundleRecord = bundle;
+    const claims = Array.isArray(bundle?.claims) ? bundle.claims : [];
+    // Build a set of subjectIds already covered by bundle claims
+    const claimSubjectIds = new Set(claims.map((c) => c.subjectId));
+    // ── Step 1: resolve each bundle claim via resolveInquiry ──────────────────
+    for (const claim of claims) {
+        idx += 1;
+        const inquiryId = `${slug}-gr-${idx}`;
+        const inquiry = {
+            id: inquiryId,
+            question: `Was gate action on claim ${claim.id} (status: ${claim.status}) justified given the trust state?`,
+            askedBy: "gate-review",
+            askedAt,
+            target: {
+                subjectType: claim.subjectType,
+                subjectId: claim.subjectId,
+                fieldOrBehavior: claim.fieldOrBehavior,
+            },
+            metadata: { sessionSlug: slug, claimId: claim.id, blocked: blockSignal.blocked },
+        };
+        const rawRecord = surface.resolveInquiry(bundleRecord, inquiry, { now });
+        const calibration = deriveGateCalibration(rawRecord.outcome, rawRecord.answer?.status, blockSignal.blocked);
+        const advisoryFix = gateAdvisoryFix(calibration, claim.id, rawRecord.answer?.status ?? claim.status);
+        records.push(toSchemaInquiryRecord(rawRecord, calibration, advisoryFix, blockSignal.blocked, slug));
+    }
+    // ── Step 2: resolve absent expected criteria (missed_block candidates) ────
+    for (const criterionId of expectedCriterionIds) {
+        const subjectId = `${slug}/${criterionId}`;
+        // Skip if there's already a bundle claim for this criterion
+        if (claimSubjectIds.has(subjectId) || claimSubjectIds.has(criterionId))
+            continue;
+        idx += 1;
+        const inquiryId = `${slug}-gr-${idx}`;
+        const inquiry = {
+            id: inquiryId,
+            question: `Was acceptance criterion "${criterionId}" claimed in the trust.bundle before gate evaluation?`,
+            askedBy: "gate-review",
+            askedAt,
+            target: {
+                subjectType: "workflow-check",
+                subjectId,
+                fieldOrBehavior: criterionId,
+            },
+            metadata: { sessionSlug: slug, criterionId, blocked: blockSignal.blocked, expectedCriterion: true },
+        };
+        const rawRecord = surface.resolveInquiry(bundleRecord, inquiry, { now });
+        // outcome will be "unsupported" since no claim matches the absent criterion
+        const calibration = deriveGateCalibration(rawRecord.outcome, rawRecord.answer?.status, blockSignal.blocked);
+        const advisoryFix = gateAdvisoryFix(calibration, subjectId, "absent");
+        records.push(toSchemaInquiryRecord(rawRecord, calibration, advisoryFix, blockSignal.blocked, slug));
+    }
+    // ── Step 3: if still empty (no claims, no expected criteria), emit one record
+    if (records.length === 0) {
+        idx += 1;
+        const inquiryId = `${slug}-gr-${idx}`;
+        const inquiry = {
+            id: inquiryId,
+            question: `Does the trust.bundle for session "${slug}" contain any claims for gate evaluation?`,
+            askedBy: "gate-review",
+            askedAt,
+            // No target — natural-language-only inquiry → resolveInquiry returns "unsupported"
+            metadata: { sessionSlug: slug, blocked: blockSignal.blocked, reason: "empty-bundle" },
+        };
+        const rawRecord = surface.resolveInquiry(bundleRecord, inquiry, { now });
+        const advisoryFix = `Ensure \`workflow-sidecar record-evidence\` writes at least one claim to the trust.bundle for session \`${slug}\` before gate-review is invoked.`;
+        records.push(toSchemaInquiryRecord(rawRecord, "missed_block", advisoryFix, blockSignal.blocked, slug));
+    }
+    return records;
+}
+/**
+ * gate-review <artifact-dir>
+ *
+ * Reads the session's trust.bundle and the gate block signal, classifies each
+ * gate fire or suspected miss using Surface's resolveInquiry, and emits
+ * gate-review.inquiries.json as an array of canonical InquiryRecords.
+ * ADVISORY ONLY — never modifies scripts/hooks/. Issue #119.
+ *
+ * The block signal is read from <artifact-root>/.goal-fit-block-streak.json,
+ * written by scripts/hooks/stop-goal-fit.js when block mode fires. The file
+ * lives one level above the session slug dir (the .flow-agents root).
+ *
+ * If @kontourai/surface is unavailable, logs a warning and returns 0
+ * (fail-open — no bespoke fork fallback).
+ */
+async function gateReview(p) {
+    const dir = artifactDirFrom(p.positional[0] || die("artifact directory is required"));
+    if (!fs.existsSync(dir))
+        die(`artifact directory does not exist: ${dir}`);
+    const slug = taskSlugFor(dir, opt(p, "task-slug"));
+    // Locate trust.bundle — required per SKILL.md contract
+    const bundlePath = path.join(dir, "trust.bundle");
+    if (!fs.existsSync(bundlePath)) {
+        process.stderr.write(`[gate-review] trust.bundle absent at ${bundlePath} — NOT_VERIFIED. Build ADR 0010 Phase 1 first.\n`);
+        return 1;
+    }
+    // Load Surface (ESM, fail-open)
+    const surface = await tryLoadSurface();
+    if (!surface || typeof surface.resolveInquiry !== "function") {
+        process.stderr.write(`[gate-review] @kontourai/surface unavailable or missing resolveInquiry — gate-review skipped (no fork fallback)\n`);
+        return 0;
+    }
+    const bundle = JSON.parse(fs.readFileSync(bundlePath, "utf8"));
+    // Read gate block signal from .flow-agents root (one level above session dir)
+    const artifactRoot = path.dirname(dir);
+    const blockSignal = readGateBlockSignal(artifactRoot);
+    // Enumerate expected criterion IDs: primary = bundle claims (workflow.acceptance.criterion),
+    // fallback = acceptance.json (back-compat for sessions without an up-to-date bundle).
+    const criterionClaims = Array.isArray(bundle.claims)
+        ? bundle.claims.filter((c) => c.claimType === "workflow.acceptance.criterion")
+        : [];
+    let expectedCriterionIds;
+    if (criterionClaims.length > 0) {
+        // Extract the final segment of subjectId (e.g. "slug/AC1" → "AC1")
+        expectedCriterionIds = criterionClaims
+            .map((c) => String(c.subjectId ?? "").split("/").pop() ?? "")
+            .filter(Boolean);
+    }
+    else {
+        // Fallback: read acceptance.json (back-compat for sessions without criterion claims)
+        const acceptancePath = path.join(dir, "acceptance.json");
+        const acceptance = fs.existsSync(acceptancePath) ? loadJson(acceptancePath) : null;
+        expectedCriterionIds = Array.isArray(acceptance?.criteria)
+            ? acceptance.criteria.map((c) => String(c.id ?? "")).filter(Boolean)
+            : [];
+    }
+    const records = buildGateInquiryRecords(bundle, blockSignal, slug, expectedCriterionIds, surface);
+    // Validate each record against the hachure inquiry-record.schema.json (fail-open)
+    const validator = getHachureInquiryRecordValidator();
+    let schemaValid = true;
+    const validationErrors = [];
+    for (const record of records) {
+        if (validator) {
+            const result = validator(record);
+            if (!result.valid) {
+                schemaValid = false;
+                validationErrors.push(...result.errors.map((e) => `${record["id"] ?? "?"}: ${e}`));
+            }
+        }
+    }
+    if (!schemaValid) {
+        process.stderr.write(`[gate-review] InquiryRecord schema validation errors:\n${validationErrors.join("\n")}\n`);
+    }
+    const outputPath = path.join(dir, "gate-review.inquiries.json");
+    writeJson(outputPath, records);
+    // Build summary counts by calibration
+    const counts = {};
+    for (const r of records) {
+        const cal = r["answer"]?.["value"]?.["calibration"] ?? "unknown";
+        counts[cal] = (counts[cal] ?? 0) + 1;
+    }
+    const summary = Object.entries(counts)
+        .filter(([, n]) => n > 0)
+        .map(([k, n]) => `${k}=${n}`)
+        .join(", ");
+    const schemaTag = validator ? (schemaValid ? " schema:valid" : " schema:INVALID") : " schema:unavailable";
+    console.log(`gate-review: ${records.length} InquiryRecord(s) [${summary}]${schemaTag} → ${outputPath}`);
+    return 0;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// ─── ADR 0010 Phase 3: project the local trust.bundle to the Surface Trust Panel ──
+// Surface owns derivation (buildTrustReport) AND rendering (the dependency-free
+// <surface-trust-panel> element). Flow Agents only assembles a standalone HTML
+// shell — no trust logic or rendering reimplemented (consume-never-fork).
+/** Locate Surface's self-contained, dependency-free panel element (ESM, no require). */
+function loadSurfacePanelJs() {
+    let d = path.dirname(fileURLToPath(import.meta.url));
+    for (let i = 0; i < 12; i += 1) {
+        try {
+            return fs.readFileSync(path.join(d, "node_modules/@kontourai/surface/dist/src/trust-panel/surface-trust-panel.js"), "utf8");
+        }
+        catch { /* walk up */ }
+        const parent = path.dirname(d);
+        if (parent === d)
+            break;
+        d = parent;
+    }
+    die("could not locate @kontourai/surface trust-panel element (dist/src/trust-panel/surface-trust-panel.js)");
+    return "";
+}
+async function renderTrustPanel(p) {
+    const root = path.resolve(opt(p, "artifact-root", ".flow-agents"));
+    const dir = p.positional[0] ? artifactDirFrom(p.positional[0]) : currentDir(root);
+    if (!dir)
+        die("render-trust-panel requires a workflow dir or a recorded current session");
+    let bundle = null;
+    try {
+        bundle = JSON.parse(fs.readFileSync(path.join(dir, "trust.bundle"), "utf8"));
+    }
+    catch {
+        bundle = null;
+    }
+    if (!bundle)
+        die(`no trust.bundle at ${path.join(dir, "trust.bundle")} — run record-evidence first`);
+    const surface = (await import("@kontourai/surface"));
+    if (typeof surface.buildTrustReport !== "function")
+        die("@kontourai/surface buildTrustReport unavailable — cannot derive the trust report");
+    const report = surface.buildTrustReport(bundle);
+    // diffFreshness on resume: if a prior trust.checkpoint.json exists, surface the
+    // fresh→stale transitions so the user sees what has gone stale since the last seal.
+    const checkpointFile = path.join(dir, "trust.checkpoint.json");
+    if (fs.existsSync(checkpointFile) && typeof surface.diffFreshness === "function") {
+        try {
+            const envelope = JSON.parse(fs.readFileSync(checkpointFile, "utf8"));
+            const priorCheckpoint = envelope.checkpoint;
+            if (priorCheckpoint && typeof priorCheckpoint === "object") {
+                const transitions = surface.diffFreshness(priorCheckpoint, report);
+                const staleTransitions = transitions.filter((t) => t["to"] === "stale");
+                if (staleTransitions.length > 0) {
+                    const claimIds = staleTransitions.map((t) => String(t["claimId"] ?? "")).filter(Boolean);
+                    process.stderr.write(`[trust-checkpoint] ${staleTransitions.length} claim(s) went stale since the last checkpoint (sealed ${String(envelope.sealed_at ?? "unknown")}):\n${claimIds.map((id) => `  - ${id}`).join("\n")}\n`);
+                }
+                else {
+                    process.stderr.write(`[trust-checkpoint] 0 claims went stale since the last checkpoint (sealed ${String(envelope.sealed_at ?? "unknown")}).\n`);
+                }
+            }
+        }
+        catch {
+            /* diffFreshness is advisory — never block the panel render */
+        }
+    }
+    const panelJs = loadSurfacePanelJs();
+    const heading = `Flow Agents trust — ${String(path.basename(dir)).replace(/[<>"&]/g, "")}`;
+    const reportJson = JSON.stringify(report).replace(/</g, "\\u003c");
+    const html = `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${heading}</title></head>
+<body style="margin:0;padding:1.5rem;background:#f4f1e6">
+<script type="module">
+${panelJs}
+</script>
+<surface-trust-panel heading="${heading}"></surface-trust-panel>
+<script id="trust-report" type="application/json">${reportJson}</script>
+<script type="module">document.querySelector("surface-trust-panel").report = JSON.parse(document.getElementById("trust-report").textContent);</script>
+</body></html>
+`;
+    const out = opt(p, "out") || path.join(dir, "trust-panel.html");
+    fs.writeFileSync(out, html);
+    // Also emit the derived report as a first-class artifact — the universal input for
+    // Surface's hosted Snapshot Viewer and a bare `<surface-trust-panel src=…>` (the HTML
+    // above already embeds it). Suppress with --no-report.
+    let reportOut = "";
+    if (!p.flags.has("no-report")) {
+        reportOut = opt(p, "report-out") || path.join(dir, "trust-report.json");
+        fs.writeFileSync(reportOut, `${JSON.stringify(report, null, 2)}\n`);
+    }
+    console.log(out);
+    if (reportOut)
+        console.log(reportOut);
+    return 0;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// ─── flow-agents#137 / ADR 0011: wire Surface's MCP to surface trust reports ──
+// Flow Agents produces the bundle; Surface's MCP projects it. `--mode print` is the
+// zero-write default (output the snippet). `enable`/`disable` edit a runtime JSON MCP
+// config (e.g. Claude Code `.mcp.json`) via a *conventional managed key* — idempotent,
+// reversible, and only ever our own entry (never auto-injected; opt-in only).
+const TRUST_MCP_SERVER = "flow-agents-surface-trust";
+function trustMcpRegistration() {
+    // No static `--input` (a single file can't follow many per-task bundles or a moving
+    // current); the skill passes the active task's bundle as a per-call `path` arg.
+    return { command: "npx", args: ["-y", "@kontourai/surface", "mcp"] };
+}
+function trustMcp(p) {
+    const mode = opt(p, "mode", "print");
+    if (mode === "print") {
+        console.log(JSON.stringify({ mcpServers: { [TRUST_MCP_SERVER]: trustMcpRegistration() } }, null, 2));
+        process.stderr.write(`\n# Paste the above into your runtime MCP config (e.g. .mcp.json). Flow Agents does NOT write it for you unless you run: trust-mcp --mode enable\n`);
+        process.stderr.write(`# To view a task's trust inline, call surface_summary with path=<.flow-agents/<slug>/trust.bundle>.\n`);
+        return 0;
+    }
+    if (mode !== "enable" && mode !== "disable")
+        die("trust-mcp --mode must be print|enable|disable");
+    const configPath = path.resolve(opt(p, "config", ".mcp.json"));
+    let config = {};
+    try {
+        config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+    }
+    catch {
+        config = {};
+    }
+    if (typeof config !== "object" || config === null || Array.isArray(config))
+        die(`${configPath} is not a JSON object — refusing to edit`);
+    if (!config.mcpServers || typeof config.mcpServers !== "object" || Array.isArray(config.mcpServers))
+        config.mcpServers = {};
+    if (mode === "enable") {
+        config.mcpServers[TRUST_MCP_SERVER] = trustMcpRegistration();
+        fs.mkdirSync(path.dirname(configPath), { recursive: true });
+        fs.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`);
+        console.log(`enabled ${TRUST_MCP_SERVER} in ${configPath} (remove with: trust-mcp --mode disable)`);
+        return 0;
+    }
+    // disable: remove only our own conventional entry; leave everything else untouched.
+    if (Object.prototype.hasOwnProperty.call(config.mcpServers, TRUST_MCP_SERVER)) {
+        delete config.mcpServers[TRUST_MCP_SERVER];
+        fs.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`);
+        console.log(`disabled ${TRUST_MCP_SERVER} in ${configPath}`);
+    }
+    else {
+        console.log(`${TRUST_MCP_SERVER} not present in ${configPath} — nothing to remove`);
+    }
+    return 0;
+}
+// ─── ADR 0012: agent coordination as liveness claims (policy-centered) ──────────
+// A work-claim is a regular Hachure claim governed by a *liveness policy* (ttl +
+// heartbeat → held/stale/released), keyed by the work-item subjectId, appended to a
+// shared stream all agents read. Status is RECOMPUTED via Surface's deriveTrustStatus
+// (no forked logic). Advisory, not a lock. The liveness policy is a general archetype
+// (not use-case-specific) and is a candidate to graduate upstream into Surface.
+const LIVENESS_POLICY = {
+    id: "policy:liveness.hold",
+    claimType: "liveness.hold",
+    requiredEvidence: [],
+    acceptanceCriteria: ["A heartbeat within ttlSeconds holds the claim; a lapse or release frees it."],
+    reviewAuthority: "system",
+    validityRule: { kind: "duration", durationDays: 1 },
+    stalenessTriggers: [],
+    conflictRules: [],
+    impactLevel: "medium",
+};
+function livenessStreamFile(root) { return path.join(root, "liveness", "events.jsonl"); }
+function appendLivenessEvent(root, evt) {
+    const file = livenessStreamFile(root);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.appendFileSync(file, `${JSON.stringify(evt)}\n`);
+}
+function readLivenessEvents(root) {
+    // Delegate to the shared pure-CJS helper (scripts/hooks/lib/liveness-read.js).
+    // Using createRequire so the ESM sidecar can load a CJS module without bundling it.
+    try {
+        const _req = createRequire(import.meta.url);
+        const helperPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../scripts/hooks/lib/liveness-read.js");
+        const helper = _req(helperPath);
+        return helper.readLivenessEvents(livenessStreamFile(root));
+    }
+    catch {
+        // Fallback: read inline (keeps sidecar self-sufficient if helper is unavailable)
+        let raw = "";
+        try {
+            raw = fs.readFileSync(livenessStreamFile(root), "utf8");
+        }
+        catch {
+            return [];
+        }
+        return raw.split("\n").map((l) => l.trim()).filter(Boolean).map((l) => { try {
+            return JSON.parse(l);
+        }
+        catch {
+            return null;
+        } }).filter((x) => x !== null);
+    }
+}
+function livenessLabel(status) {
+    if (status === "verified")
+        return "held";
+    if (status === "stale" || status === "revoked")
+        return "free"; // reclaimable: lapsed or released
+    if (status === "superseded")
+        return "superseded";
+    return status;
+}
+// ─── ADR 0012 lifecycle-driven liveness (opt-in via FLOW_AGENTS_LIVENESS) ──────
+// init-plan claims the work-item; advance-state heartbeats (or releases on terminal),
+// so the workflow lifecycle itself maintains the liveness claim — no manual liveness calls.
+// Additive + fail-open: a liveness-emit failure never affects the workflow command.
+const LIVENESS_TERMINAL = new Set(["delivered", "accepted", "archived"]);
+function resolveLivenessActor() { return (process.env.FLOW_AGENTS_ACTOR || "").trim() || "local"; }
+function livenessEnabled() { const v = String(process.env.FLOW_AGENTS_LIVENESS || "").trim().toLowerCase(); return v === "on" || v === "1" || v === "true"; }
+function livenessLifecycle(taskDir, slug, kind, timestamp) {
+    if (!livenessEnabled())
+        return;
+    try {
+        const root = path.dirname(taskDir); // .flow-agents/<slug> → .flow-agents (the shared liveness stream lives here)
+        const evt = { type: kind, subjectId: slug, actor: resolveLivenessActor(), at: timestamp, source: "lifecycle" };
+        if (kind === "claim")
+            evt.ttlSeconds = 1800;
+        appendLivenessEvent(root, evt);
+    }
+    catch { /* best-effort; liveness is advisory and must never break the workflow */ }
+}
+async function liveness(p) {
+    const root = path.resolve(opt(p, "artifact-root", ".flow-agents"));
+    const action = p.positional[0] || "";
+    const subjectId = p.positional[1] || "";
+    const actor = opt(p, "actor", process.env.FLOW_AGENTS_ACTOR || "unknown");
+    const nowIso = new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+    if (action === "claim" || action === "heartbeat" || action === "release") {
+        if (!subjectId)
+            die(`liveness ${action} requires a subjectId`);
+        const evt = { type: action, subjectId, actor, at: opt(p, "at") || nowIso };
+        if (action === "claim")
+            evt.ttlSeconds = Number.parseInt(opt(p, "ttl", "1800"), 10) || 1800;
+        appendLivenessEvent(root, evt);
+        console.log(`liveness ${action}: ${subjectId} by ${actor}`);
+        return 0;
+    }
+    if (action === "status") {
+        const surface = (await import("@kontourai/surface"));
+        if (typeof surface.deriveTrustStatus !== "function")
+            die("@kontourai/surface deriveTrustStatus unavailable — requires surface >= 1.2");
+        const subjectFilter = opt(p, "subject");
+        const now = opt(p, "now") ? new Date(opt(p, "now")) : new Date();
+        // Group events by subjectId::actor — one liveness claim per holder of a subject.
+        const groups = new Map();
+        for (const e of readLivenessEvents(root)) {
+            if (!e.subjectId || !e.actor)
+                continue;
+            const key = `${e.subjectId}::${e.actor}`;
+            let g = groups.get(key);
+            if (!g) {
+                g = { subjectId: String(e.subjectId), actor: String(e.actor), ttlSeconds: 1800, created: String(e.at), updated: String(e.at), events: [] };
+                groups.set(key, g);
+            }
+            g.updated = String(e.at);
+            if (e.type === "claim") {
+                g.ttlSeconds = Number(e.ttlSeconds) || g.ttlSeconds;
+                g.events.push({ id: `c:${key}:${e.at}`, claimId: key, status: "verified", actor: g.actor, method: "observation", evidenceIds: [], createdAt: e.at, verifiedAt: e.at });
+            }
+            else if (e.type === "heartbeat") {
+                g.events.push({ id: `h:${key}:${e.at}`, claimId: key, status: "verified", actor: g.actor, method: "observation", evidenceIds: [], createdAt: e.at, verifiedAt: e.at });
+            }
+            else if (e.type === "release") {
+                g.events.push({ id: `r:${key}:${e.at}`, claimId: key, status: "revoked", type: "invalidation", actor: g.actor, method: "observation", evidenceIds: [], createdAt: e.at, verifiedAt: e.at });
+            }
+        }
+        const rows = [];
+        for (const g of groups.values()) {
+            if (subjectFilter && g.subjectId !== subjectFilter)
+                continue;
+            const claim = { id: `${g.subjectId}::${g.actor}`, subjectType: "work-item", subjectId: g.subjectId, surface: "flow.liveness", claimType: "liveness.hold", fieldOrBehavior: "held-by", value: g.actor, createdAt: g.created, updatedAt: g.updated, ttlSeconds: g.ttlSeconds, verificationPolicyId: LIVENESS_POLICY.id };
+            const status = surface.deriveTrustStatus({ claim, evidence: [], policy: LIVENESS_POLICY, events: g.events, now });
+            rows.push({ subjectId: g.subjectId, actor: g.actor, status, label: livenessLabel(status) });
+        }
+        if (p.flags.has("json")) {
+            console.log(JSON.stringify(rows, null, 2));
+            return 0;
+        }
+        for (const r of rows)
+            console.log(`${r.subjectId}\t${r.actor}\t${r.label}`);
+        return 0;
+    }
+    die("liveness action must be one of: claim | heartbeat | release | status");
+    return 1;
+}
+/**
+ * Build a structured explanation for a specific claim.
+ * PURE: report + bundle + id in, structured explanation out.
+ * No fs, no CLI, no .flow-agents paths. Promotable to Surface #171.
+ *
+ * @param report   TrustReport from buildTrustReport(bundle) — required for derived status
+ * @param bundle   Raw parsed trust.bundle (BundleFile shape)
+ * @param claimId  The claim id to explain
+ */
+export function buildClaimExplanation(report, bundle, claimId) {
+    const reportClaims = Array.isArray(report.claims) ? report.claims : [];
+    const reportClaim = reportClaims.find((c) => c.id === claimId);
+    if (!reportClaim) {
+        return {
+            found: false,
+            status: "unknown",
+            value: "",
+            claimType: "",
+            evidence: [],
+            policy: null,
+            why: { directInputs: [], leafClaims: [], diagnostics: [], transparencyGaps: [], changeRecords: [] },
+        };
+    }
+    const bundleClaims = Array.isArray(bundle.claims) ? bundle.claims : [];
+    const bundleClaim = bundleClaims.find((c) => c.id === claimId) ?? reportClaim;
+    const bundlePolicies = Array.isArray(bundle.policies) ? bundle.policies : [];
+    const bundleEvidence = Array.isArray(bundle.evidence) ? bundle.evidence : [];
+    // Governing policy — follow verificationPolicyId into bundle.policies[]
+    const verificationPolicyId = typeof bundleClaim.verificationPolicyId === "string" ? bundleClaim.verificationPolicyId : undefined;
+    const rawPolicy = verificationPolicyId ? bundlePolicies.find((p) => p.id === verificationPolicyId) : undefined;
+    const policy = rawPolicy
+        ? {
+            id: String(rawPolicy.id ?? ""),
+            requiredEvidence: Array.isArray(rawPolicy.requiredEvidence) ? rawPolicy.requiredEvidence : [],
+            requiredMethods: Array.isArray(rawPolicy.requiredMethods) ? rawPolicy.requiredMethods : undefined,
+            acceptanceCriteria: Array.isArray(rawPolicy.acceptanceCriteria) ? rawPolicy.acceptanceCriteria : [],
+            reviewAuthority: String(rawPolicy.reviewAuthority ?? ""),
+        }
+        : null;
+    // Evidence enhancement: pull evidence items for this claim, surface the execution block
+    const claimEvidenceItems = bundleEvidence.filter((ev) => ev && ev.claimId === claimId);
+    const evidence = claimEvidenceItems.map((ev) => {
+        const exec = ev.execution && typeof ev.execution === "object" ? ev.execution : null;
+        const execution = exec
+            ? {
+                runner: String(exec.runner ?? exec.label ?? ""),
+                label: String(exec.label ?? exec.runner ?? ""),
+                isError: Boolean(exec.isError ?? (typeof exec.exitCode === "number" && exec.exitCode !== 0)),
+                exitCode: typeof exec.exitCode === "number" ? exec.exitCode : null,
+            }
+            : null;
+        return {
+            evidenceType: String(ev.evidenceType ?? ev.type ?? "unknown"),
+            label: String(ev.label ?? ev.excerptOrSummary ?? ev.sourceRef ?? ev.id ?? ""),
+            execution,
+            passing: execution ? !execution.isError : String(ev.status ?? "") !== "disputed",
+            summary: String(ev.excerptOrSummary ?? ev.summary ?? ev.label ?? ""),
+        };
+    });
+    // Drilldown: extract from report structure (report.transparencyGaps, report.changeRecords)
+    const allGaps = Array.isArray(report.transparencyGaps) ? report.transparencyGaps : [];
+    const allChanges = Array.isArray(report.changeRecords) ? report.changeRecords : [];
+    const transparencyGaps = allGaps.filter((g) => g && g.claimId === claimId);
+    const changeRecords = allChanges.filter((c) => c && c.claimId === claimId);
+    return {
+        found: true,
+        status: String(reportClaim.status ?? "unknown"),
+        value: String(bundleClaim.value ?? reportClaim.value ?? ""),
+        claimType: String(bundleClaim.claimType ?? reportClaim.claimType ?? ""),
+        evidence,
+        policy,
+        why: {
+            directInputs: [], // populated by buildDerivationDrilldown if non-leaf
+            leafClaims: [],
+            diagnostics: [],
+            transparencyGaps,
+            changeRecords,
+        },
+    };
+}
+/**
+ * claim <id> <dir>
+ *
+ * Look up a specific claim in the session's trust.bundle and print:
+ *   - Derived status and raw value
+ *   - Failing evidence items (with execution block: runner, exitCode, isError)
+ *   - Governing VerificationPolicy (how-to-verify)
+ *   - Derivation drilldown / transparency gaps (why it is in that state)
+ *
+ * --json  Emit the structured ClaimExplanation object instead of text.
+ *
+ * Usage: workflow-sidecar claim <claimId> <artifactDir>
+ */
+async function claimLookup(p) {
+    const claimId = p.positional[0] || die("claim id is required (first positional argument)");
+    const rawDir = p.positional[1] || die("artifact directory is required (second positional argument)");
+    const dir = path.resolve(rawDir);
+    const bundlePath = path.join(dir, "trust.bundle");
+    if (!fs.existsSync(bundlePath)) {
+        process.stderr.write(`[claim] no trust.bundle at ${bundlePath} — run record-evidence first
+`);
+        return 1;
+    }
+    const bundle = JSON.parse(fs.readFileSync(bundlePath, "utf8"));
+    const bundleClaims = Array.isArray(bundle.claims) ? bundle.claims : [];
+    const bundleClaim = bundleClaims.find((c) => c.id === claimId);
+    if (!bundleClaim) {
+        const available = bundleClaims.map((c) => c.id).join("\n  ");
+        process.stderr.write(`[claim] unknown claim id: ${claimId}
+Available claim ids:
+  ${available || "(none — bundle has no claims)"}
+`);
+        return 1;
+    }
+    // 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
+`);
+        return 0; // fail-open, consistent with gate-review pattern
+    }
+    // Build TrustReport (required — buildDerivationDrilldown needs TrustReport, not TrustBundle)
+    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
+    }
+    if (p.flags.has("json")) {
+        console.log(JSON.stringify(explanation, null, 2));
+        return 0;
+    }
+    // ── Human-readable output ───────────────────────────────────────────────────
+    const lines = [];
+    lines.push(`Claim:  ${claimId}`);
+    lines.push(`Status: ${explanation.status}   Value: ${explanation.value}`);
+    lines.push(`Type:   ${explanation.claimType}`);
+    lines.push("");
+    // Evidence section — failing items are the concrete "why disputed"
+    const failingEvidence = explanation.evidence.filter((ev) => !ev.passing);
+    const allEvidence = explanation.evidence;
+    if (allEvidence.length > 0) {
+        lines.push("Evidence:");
+        for (const ev of allEvidence) {
+            const passMark = ev.passing ? "pass" : "FAIL";
+            const execStr = ev.execution
+                ? ` [runner: ${ev.execution.runner}, exitCode: ${ev.execution.exitCode ?? "?"}, isError: ${ev.execution.isError}]`
+                : "";
+            lines.push(`  [${passMark}] ${ev.evidenceType}: ${ev.label || ev.summary}${execStr}`);
+        }
+        if (failingEvidence.length > 0) {
+            lines.push("");
+            lines.push(`Failing evidence (disputed because):`);
+            for (const ev of failingEvidence) {
+                const execStr = ev.execution
+                    ? ` ${ev.execution.runner} exited ${ev.execution.exitCode ?? "?"} (isError: ${ev.execution.isError})`
+                    : "";
+                lines.push(`  ${ev.evidenceType}: ${ev.label || ev.summary}${execStr}`);
+            }
+        }
+    }
+    else {
+        lines.push("Evidence: (none recorded for this claim)");
+    }
+    lines.push("");
+    // Policy section — how-to-verify
+    if (explanation.policy) {
+        const pol = explanation.policy;
+        lines.push(`Governing Policy (${pol.id}):`);
+        lines.push(`  requiredEvidence:   [${pol.requiredEvidence.join(", ")}]`);
+        if (pol.requiredMethods && pol.requiredMethods.length > 0) {
+            lines.push(`  requiredMethods:    [${pol.requiredMethods.join(", ")}]`);
+        }
+        lines.push(`  acceptanceCriteria: [${pol.acceptanceCriteria.join(" | ")}]`);
+        lines.push(`  reviewAuthority:    ${pol.reviewAuthority}`);
+    }
+    else {
+        lines.push("Governing Policy: (none — claim has no verificationPolicyId or policy not found in bundle)");
+    }
+    lines.push("");
+    // Why section — derivation drilldown + transparency gaps
+    lines.push("Derivation Drilldown:");
+    if (explanation.why.directInputs.length > 0) {
+        lines.push(`  Direct inputs: ${explanation.why.directInputs.length} claim(s)`);
+        for (const inp of explanation.why.directInputs) {
+            const inpStatus = typeof inp.claim === "object" && inp.claim ? String(inp.claim.status ?? "?") : "?";
+            lines.push(`    - ${inp.inputClaimId ?? "?"} (status: ${inpStatus})`);
+        }
+    }
+    else {
+        lines.push("  Direct inputs: (none — leaf claim)");
+    }
+    if (explanation.why.leafClaims.length > 0) {
+        lines.push(`  Leaf claims: ${explanation.why.leafClaims.length} claim(s)`);
+    }
+    if (explanation.why.diagnostics.length > 0) {
+        lines.push(`  Diagnostics: ${explanation.why.diagnostics.length}`);
+        for (const d of explanation.why.diagnostics) {
+            lines.push(`    - ${d.type ?? "?"}: ${d.message ?? ""}`);
+        }
+    }
+    if (explanation.why.transparencyGaps.length > 0) {
+        lines.push(`  Transparency gaps: ${explanation.why.transparencyGaps.length}`);
+        for (const g of explanation.why.transparencyGaps) {
+            lines.push(`    - [${g.severity ?? "?"}] ${g.type ?? "?"}: ${g.message ?? ""}`);
+        }
+    }
+    else {
+        lines.push("  Transparency gaps: (none)");
+    }
+    if (explanation.why.changeRecords.length > 0) {
+        lines.push(`  Change records: ${explanation.why.changeRecords.length}`);
+        for (const cr of explanation.why.changeRecords) {
+            lines.push(`    - ${cr.action ?? "?"} at ${cr.at ?? cr.createdAt ?? "?"}`);
+        }
+    }
+    console.log(lines.join("\n"));
+    return 0;
+}
+// ─────────────────────────────────────────────────────────────────────────────
 async function main() {
     const p = parseArgs(process.argv.slice(2));
     if (!p.command)
         die("workflow-sidecar command is required");
-    const lockRoot = ["ensure-session", "current", "dogfood-pass"].includes(p.command) ? path.resolve(opt(p, "artifact-root", ".flow-agents")) : p.command === "record-agent-event" ? explicitArtifactRoot(p) : p.positional[0] ? artifactDirFrom(p.positional[0]) : "";
+    const lockRoot = ["ensure-session", "current", "dogfood-pass", "liveness"].includes(p.command) ? path.resolve(opt(p, "artifact-root", ".flow-agents")) : p.command === "record-agent-event" ? explicitArtifactRoot(p) : p.command === "claim" ? (p.positional[1] ? path.resolve(p.positional[1]) : "") : p.positional[0] ? artifactDirFrom(p.positional[0]) : "";
     return withLock(lockRoot, ["ensure-session", "record-agent-event", "dogfood-pass"].includes(p.command), p.command, () => {
         switch (p.command) {
             case "ensure-session": return ensureSession(p);
@@ -868,14 +2726,39 @@ async function main() {
             case "record-agent-event": return recordAgentEvent(p);
             case "init-plan": return initPlan(p);
             case "record-evidence": return recordEvidence(p);
+            case "record-gate-claim": return recordGateClaim(p);
             case "advance-state": return advanceState(p);
             case "record-critique": return recordCritique(p);
             case "import-critique": return importCritique(p);
             case "record-release": return recordRelease(p);
             case "record-learning": return recordLearning(p);
             case "dogfood-pass": return dogfoodPass(p);
+            case "gate-review": return gateReview(p);
+            case "render-trust-panel": return renderTrustPanel(p);
+            case "trust-mcp": return trustMcp(p);
+            case "liveness": return liveness(p);
+            case "claim": return claimLookup(p);
+            case "seal-checkpoint": return sealCheckpoint(p);
+            case "publish-delivery": return publishDeliveryCmd(p);
             default: die(`unknown command: ${p.command}`);
         }
     });
 }
-main().then((code) => process.exit(code)).catch((error) => { console.error(error instanceof Error ? error.message : String(error)); process.exit(1); });
+// Run the CLI only when executed directly, not when imported as a library.
+// Resolve real paths to handle symlinks (e.g. /tmp -> /private/tmp on macOS) so the
+// entry-point guard fires correctly when the module is loaded directly as a script.
+const _selfRealPath = (() => { try {
+    return fs.realpathSync(fileURLToPath(import.meta.url));
+}
+catch {
+    return fileURLToPath(import.meta.url);
+} })();
+const _argv1RealPath = (() => { try {
+    return fs.realpathSync(process.argv[1]);
+}
+catch {
+    return process.argv[1];
+} })();
+if (_selfRealPath === _argv1RealPath) {
+    main().then((code) => process.exit(code)).catch((error) => { console.error(error instanceof Error ? error.message : String(error)); process.exit(1); });
+}