cool-workflow 0.1.97 → 0.2.0

package/dist/shell/collaboration-io.js

@@ -0,0 +1,264 @@
+"use strict";
+// shell/collaboration-io.ts — the impure wrapper around
+// core/multi-agent/collaboration.ts's pure record builders + review-state
+// projection: recordApproval/recordComment/recordHandoff/setReviewPolicy/
+// deriveReviewState/reviewGateErrors, plus the read-only reports.
+//
+// MILESTONE 9. Byte-exact port of the impure half of the old build's
+// src/collaboration.ts: trust-audit recording + saveCheckpoint.
+//
+// Evidence: SPEC/multi-agent.md section F; plugins/cool-workflow/src/
+// collaboration.ts (byte-exact source for the wiring sequence).
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatReviewStatus = void 0;
+exports.ensureCollaborationState = ensureCollaborationState;
+exports.recordApproval = recordApproval;
+exports.recordComment = recordComment;
+exports.recordHandoff = recordHandoff;
+exports.setReviewPolicy = setReviewPolicy;
+exports.resolveReviewPolicy = resolveReviewPolicy;
+exports.selfActorIdsForCandidate = selfActorIdsForCandidate;
+exports.deriveReviewState = deriveReviewState;
+exports.reviewGateErrors = reviewGateErrors;
+exports.commitReviewProvenance = commitReviewProvenance;
+exports.buildReviewStatusReport = buildReviewStatusReport;
+exports.listComments = listComments;
+exports.deriveOwner = deriveOwner;
+exports.formatCommentList = formatCommentList;
+const trust_audit_1 = require("./trust-audit");
+const run_store_1 = require("./run-store");
+const collab = __importStar(require("../core/multi-agent/collaboration"));
+function now() {
+    return new Date().toISOString();
+}
+function auditTargetFields(target) {
+    switch (target.kind) {
+        case "candidate":
+            return { candidateId: target.id };
+        case "selection":
+            return { selectionId: target.id };
+        case "commit":
+            return { commitId: target.id };
+        case "node":
+            return { nodeId: target.id };
+        case "task":
+            return { taskId: target.id };
+        default:
+            return {};
+    }
+}
+function compact(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+}
+function ensureCollaborationState(run) {
+    const existing = run.collaboration;
+    const state = existing || collab.emptyCollaborationState();
+    if (!Array.isArray(state.approvals))
+        state.approvals = [];
+    if (!Array.isArray(state.comments))
+        state.comments = [];
+    if (!Array.isArray(state.handoffs))
+        state.handoffs = [];
+    run.collaboration = state;
+    return state;
+}
+function persist(run, options) {
+    if (options.persist === false)
+        return;
+    (0, run_store_1.saveCheckpoint)(run);
+}
+function recordApproval(run, input, options = {}) {
+    const state = ensureCollaborationState(run);
+    const actor = collab.normalizeActor(input);
+    const target = collab.normalizeTarget(input.target);
+    const decision = input.decision === "reject" ? "reject" : "approve";
+    const audit = (0, trust_audit_1.recordTrustAuditEvent)(run, {
+        kind: decision === "approve" ? "collaboration.approval" : "collaboration.rejection",
+        decision: decision === "approve" ? "accepted" : "rejected",
+        source: actor.source,
+        actor: actor.id,
+        ...auditTargetFields(target),
+        agentRoleId: actor.roleId,
+        metadata: compact({ decision, rationale: input.rationale, roleId: actor.roleId, attestation: actor.attestation, targetKind: target.kind, supersedes: input.supersedes }),
+    });
+    const record = collab.buildApproval(input, state.approvals.length, run.id, now(), audit.id);
+    state.approvals.push(record);
+    persist(run, options);
+    return record;
+}
+function recordComment(run, input, options = {}) {
+    const state = ensureCollaborationState(run);
+    const actor = collab.normalizeActor(input);
+    const target = collab.normalizeTarget(input.target);
+    const threadId = input.threadId?.trim() || `${target.kind}:${target.id}`;
+    const audit = (0, trust_audit_1.recordTrustAuditEvent)(run, { kind: "collaboration.comment", decision: "recorded", source: actor.source, actor: actor.id, ...auditTargetFields(target), agentRoleId: actor.roleId, metadata: compact({ threadId, parentId: input.parentId, targetKind: target.kind }) });
+    const record = collab.buildComment(input, state.comments.length, run.id, now(), audit.id);
+    state.comments.push(record);
+    persist(run, options);
+    return record;
+}
+function recordHandoff(run, input, options = {}) {
+    const state = ensureCollaborationState(run);
+    const recorder = collab.normalizeActor(input);
+    const fromActor = input.fromActor ? collab.normalizeActor({ actor: input.fromActor, actorKind: input.fromActorKind, role: input.fromRole, attested: input.attested }) : recorder;
+    const toActor = collab.normalizeActor({ actor: input.toActor, actorKind: input.toActorKind, role: input.toRole, displayName: input.toDisplayName, attested: input.toAttested });
+    const target = collab.normalizeTarget(input.target);
+    const reason = input.reason?.trim() || "handoff";
+    const audit = (0, trust_audit_1.recordTrustAuditEvent)(run, { kind: "collaboration.handoff", decision: "recorded", source: recorder.source, actor: recorder.id, ...auditTargetFields(target), metadata: compact({ from: fromActor.id, to: toActor.id, reason, targetKind: target.kind }) });
+    const record = collab.buildHandoff(input, state.handoffs.length, run.id, now(), audit.id);
+    state.handoffs.push(record);
+    persist(run, options);
+    return record;
+}
+/** First defined value among a set of option-name aliases (old wrapper's
+ *  `firstDefined`) — lets a caller pass any of `requiredApprovals`/`required`,
+ *  `authorizedRoles`/`roles`, `allowSelfApproval`/`allow-self-approval`, etc. */
+function firstDefined(source, ...keys) {
+    for (const key of keys) {
+        if (source[key] !== undefined)
+            return source[key];
+    }
+    return undefined;
+}
+function setReviewPolicy(run, input, options = {}) {
+    const state = ensureCollaborationState(run);
+    // Resolve the old wrapper's option-name aliases before building the policy,
+    // so `required`/`roles`/`allow-self-approval`/... reach buildReviewPolicy on
+    // the canonical keys. Values are Boolean/number-coerced inside
+    // buildReviewPolicy; undefined aliases fall through to existing/defaults.
+    const raw = input;
+    const resolved = {
+        requiredApprovals: firstDefined(raw, "requiredApprovals", "required-approvals", "required", "approvals"),
+        authorizedRoles: firstDefined(raw, "authorizedRoles", "authorized-roles", "roles"),
+        allowSelfApproval: firstDefined(raw, "allowSelfApproval", "allow-self-approval"),
+        requireAttestedActor: firstDefined(raw, "requireAttestedActor", "require-attested-actor"),
+        appliesTo: firstDefined(raw, "appliesTo", "applies-to", "targets"),
+    };
+    const policy = collab.buildReviewPolicy(resolved, state.policy, now());
+    state.policy = policy;
+    (0, trust_audit_1.recordTrustAuditEvent)(run, { kind: "collaboration.review-policy", decision: "recorded", source: "operator-recorded", metadata: compact({ policyId: policy.id, requiredApprovals: policy.requiredApprovals, authorizedRoles: policy.authorizedRoles, allowSelfApproval: policy.allowSelfApproval, requireAttestedActor: policy.requireAttestedActor, appliesTo: policy.appliesTo }) });
+    persist(run, options);
+    return { ...policy, surface: "collaboration", runId: run.id, policy };
+}
+function resolveReviewPolicy(run, policy) {
+    return policy || ensureCollaborationState(run).policy || undefined;
+}
+function relatedTargetsFor(run, target) {
+    if (target.kind !== "commit")
+        return [target];
+    const commit = (run.commits || []).find((entry) => entry.id === target.id);
+    const related = [target];
+    if (commit?.selectionId)
+        related.push({ kind: "selection", id: commit.selectionId });
+    if (commit?.candidateId)
+        related.push({ kind: "candidate", id: commit.candidateId });
+    return related;
+}
+function candidateWorkerId(run, candidateId) {
+    const candidate = candidateId ? (run.candidates || []).find((entry) => entry.id === candidateId) : undefined;
+    return candidate?.workerId;
+}
+function selectedByForCandidate(run, candidateId, selectionId) {
+    const selections = (run.candidateSelections || []).filter((selection) => (selectionId && selection.id === selectionId) || (candidateId && selection.candidateId === candidateId));
+    return selections.map((selection) => selection.selectedBy).filter((id) => Boolean(id));
+}
+function selfActorIdsForCandidate(run, candidateId, selectionId) {
+    return collab.selfActorIdsForCandidate(candidateWorkerId(run, candidateId), selectedByForCandidate(run, candidateId, selectionId));
+}
+function selfActorIdsForTarget(run, target) {
+    if (target.kind === "candidate")
+        return selfActorIdsForCandidate(run, target.id);
+    if (target.kind === "selection") {
+        const selection = (run.candidateSelections || []).find((entry) => entry.id === target.id);
+        return selfActorIdsForCandidate(run, selection?.candidateId, target.id);
+    }
+    if (target.kind === "commit") {
+        const commit = (run.commits || []).find((entry) => entry.id === target.id);
+        return selfActorIdsForCandidate(run, commit?.candidateId, commit?.selectionId);
+    }
+    return [];
+}
+function deriveReviewState(run, target, options = {}) {
+    const state = ensureCollaborationState(run);
+    const policy = resolveReviewPolicy(run, options.policy);
+    return collab.deriveReviewState(run.id, state.approvals, target, { ...options, policy });
+}
+function reviewGateErrors(run, input) {
+    const state = ensureCollaborationState(run);
+    const policy = resolveReviewPolicy(run, input.policy);
+    return collab.reviewGateErrors(run.id, state.approvals, { ...input, policy }, now());
+}
+function commitReviewProvenance(run, input) {
+    const state = ensureCollaborationState(run);
+    const policy = resolveReviewPolicy(run, input.policy);
+    return collab.commitReviewProvenance(run.id, state.approvals, { ...input, policy });
+}
+function buildReviewStatusReport(run, options) {
+    const state = ensureCollaborationState(run);
+    const targets = options.target ? [collab.normalizeTarget(options.target)] : collab.distinctTargets(state);
+    const reviewStates = targets.map((target) => deriveReviewState(run, target, { policy: state.policy, relatedTargets: relatedTargetsFor(run, target), selfActorIds: selfActorIdsForTarget(run, target) }));
+    const owner = collab.deriveOwner(state.handoffs);
+    const timeline = collab.buildTimeline(state);
+    return {
+        schemaVersion: 1,
+        surface: "collaboration",
+        runId: run.id,
+        generatedAt: options.now,
+        policy: state.policy,
+        owner,
+        targets: reviewStates,
+        counts: { approvals: state.approvals.filter((record) => record.decision === "approve").length, rejections: state.approvals.filter((record) => record.decision === "reject").length, comments: state.comments.length, handoffs: state.handoffs.length },
+        timeline,
+        nextActions: collab.buildNextActions(run.id, reviewStates, state.policy),
+    };
+}
+function listComments(run, target) {
+    const normalized = target ? collab.normalizeTarget(target) : undefined;
+    const comments = collab.listComments(ensureCollaborationState(run), normalized);
+    return { schemaVersion: 1, surface: "collaboration", runId: run.id, ...(normalized ? { target: normalized } : {}), count: comments.length, comments };
+}
+function deriveOwner(run) {
+    return collab.deriveOwner(ensureCollaborationState(run).handoffs);
+}
+exports.formatReviewStatus = collab.formatReviewStatus;
+/** Format the comment list for humans. Accepts either the bare record array
+ *  (the core formatter's shape) or the `CommentListReport` envelope this
+ *  module now returns, so a caller that passes `listComments(run)` straight
+ *  through still renders the comments (never the envelope's own keys). */
+function formatCommentList(input) {
+    const comments = Array.isArray(input) ? input : input.comments;
+    return collab.formatCommentList(comments);
+}

package/dist/shell/commit-summary.js

@@ -0,0 +1,104 @@
+"use strict";
+// shell/commit-summary.ts — `cw commit summary` / `cw_commit_summary`.
+//
+// GAP #26 port: v2 dropped the CLI binding + shell body for commit.summary,
+// keeping only the MCP tool row. This restores the old build's
+// `summarizeOperatorCommits` (src/operator-ux.ts:339-349) + `formatCommitRow`
+// (src/operator-ux.ts:683-696) byte-for-byte, plus the `commitSummaryCli`
+// thin adapter both front doors call (mirrors feedbackSummaryCli /
+// candidateSummaryCli shape). Impure: reads run state from disk.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.summarizeOperatorCommits = summarizeOperatorCommits;
+exports.commitSummaryCli = commitSummaryCli;
+exports.formatCommitSummaryText = formatCommitSummaryText;
+const path = __importStar(require("node:path"));
+const run_store_1 = require("./run-store");
+function formatCommitRow(commit) {
+    return {
+        id: commit.id,
+        kind: commit.verifierGated ? "verifier-gated" : "checkpoint",
+        reason: commit.reason,
+        createdAt: commit.createdAt,
+        snapshotPath: commit.snapshotPath,
+        stateNodeId: commit.stateNodeId,
+        verifierNodeId: commit.verifierNodeId,
+        candidateId: commit.candidateId,
+        selectionId: commit.selectionId,
+        evidenceCount: commit.evidence?.length || 0,
+    };
+}
+/** Byte-exact port of the old build's `summarizeOperatorCommits`
+ *  (src/operator-ux.ts:339-349). */
+function summarizeOperatorCommits(run) {
+    const commits = [...(run.commits || [])].sort((left, right) => left.createdAt.localeCompare(right.createdAt) || left.id.localeCompare(right.id));
+    const rows = commits.map(formatCommitRow);
+    return {
+        total: rows.length,
+        verifierGated: rows.filter((commit) => commit.kind === "verifier-gated").length,
+        checkpoints: rows.filter((commit) => commit.kind === "checkpoint").length,
+        latest: rows.at(-1),
+        commits: rows,
+    };
+}
+function req(value, label) {
+    const s = value === undefined || value === null ? "" : String(value);
+    if (!s)
+        throw new Error(`Missing ${label}`);
+    return s;
+}
+function cwdFor(args) {
+    return typeof args.cwd === "string" && args.cwd.trim() ? path.resolve(args.cwd) : process.cwd();
+}
+/** Thin adapter both front doors call (mirrors the old build's orchestrator
+ *  `summarizeCommitRecords(runId)` = `summarizeOperatorCommits(loadRun(runId))`). */
+function commitSummaryCli(args) {
+    const run = (0, run_store_1.loadRunFromCwd)(req(args.runId, "run id"), cwdFor(args));
+    return summarizeOperatorCommits(run);
+}
+/** `cw commit summary <run>` human text — port of the old build's
+ *  formatCommitPanel (operator-ux/format.ts): a `Commits` rollup with the
+ *  verifier-gated / checkpoint counts and the latest commit. */
+function formatCommitSummaryText(summary) {
+    const lines = [
+        "Commits",
+        `  total=${summary.total}; verifier-gated=${summary.verifierGated}; checkpoints=${summary.checkpoints}`,
+        `  latest=${summary.latest ? `${summary.latest.id} (${summary.latest.kind}) ${summary.latest.snapshotPath}` : "none"}`,
+    ];
+    for (const commit of summary.commits.slice(-8)) {
+        lines.push(`  ${commit.id}: ${commit.kind}, reason=${commit.reason}`);
+    }
+    return lines.join("\n");
+}

package/dist/shell/commit.js

@@ -0,0 +1,290 @@
+"use strict";
+// shell/commit.ts — commitState: the imperative wrapper around
+// core/pipeline/commit-gate.ts's pure gate resolution.
+//
+// MILESTONE 6+7 (combined). Byte-exact port of the old build's
+// src/commit.ts's IO half (snapshot write, git-head read, the commit
+// node's disk write via the pipeline runner).
+//
+// Evidence: SPEC/pipeline-run.md "Commit gate — src/commit.ts".
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommitGateError = void 0;
+exports.commitState = commitState;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+const fs_atomic_1 = require("./fs-atomic");
+const commit_gate_1 = require("../core/pipeline/commit-gate");
+const contract_1 = require("../core/pipeline/contract");
+const runner_1 = require("../core/pipeline/runner");
+const node_store_1 = require("./node-store");
+const state_node_1 = require("../core/state/state-node");
+const trust_audit_1 = require("./trust-audit");
+const evidence_grounding_1 = require("../core/trust/evidence-grounding");
+const collaboration_io_1 = require("./collaboration-io");
+const error_feedback_io_1 = require("./error-feedback-io");
+class CommitGateError extends Error {
+    structured;
+    feedbackId;
+    stateNodeId;
+    constructor(error, options = {}) {
+        super(error.message);
+        this.name = "CommitGateError";
+        this.structured = error;
+        this.feedbackId = options.feedbackId;
+        this.stateNodeId = options.stateNodeId;
+    }
+}
+exports.CommitGateError = CommitGateError;
+function normalizeCommitOptions(input) {
+    if (typeof input === "string")
+        return { reason: input || "manual", source: "runtime" };
+    // Fold facade-style bare nouns (verifier/candidate/selection) into the *Id
+    // fields so a host/MCP-shaped payload gates the same as a CLI-shaped one. When
+    // any gate option is supplied, the commit is verifier-gated by construction —
+    // mirrors commitRun()'s hasGateOption, so calling commitState directly with
+    // { selection } gates exactly as `cw commit --selection` does.
+    const verifierNodeId = input.verifierNodeId || input.verifier || input.verifierNode;
+    const candidateId = input.candidateId || input.candidate;
+    const selectionId = input.selectionId || input.selection;
+    const hasGateOption = Boolean(verifierNodeId || candidateId || selectionId);
+    return {
+        ...input,
+        reason: input.reason || "manual",
+        source: input.source || "runtime",
+        verifierNodeId,
+        candidateId,
+        selectionId,
+        verifierGated: input.verifierGated || (hasGateOption && !input.allowUnverifiedCheckpoint),
+    };
+}
+function readGitHead(cwd) {
+    try {
+        return (0, node_child_process_1.execFileSync)("git", ["rev-parse", "HEAD"], { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 5000 }).trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+function findNode(run, nodeId) {
+    return (run.nodes || []).find((n) => n.id === nodeId);
+}
+function backingResultFor(run, verifierNodeId) {
+    if (!verifierNodeId)
+        return { result: undefined, requiresEvidence: undefined };
+    const marker = ":verifier:";
+    const idx = verifierNodeId.indexOf(marker);
+    const taskId = idx >= 0 ? verifierNodeId.slice(idx + marker.length) : undefined;
+    const task = taskId ? run.tasks.find((t) => t.id === taskId) : undefined;
+    if (!task)
+        return { result: undefined, requiresEvidence: undefined };
+    return { result: task.result, requiresEvidence: Boolean(task.requiresEvidence) };
+}
+/** commitState(run, input) — resolves the gate, writes the failure node +
+ *  throws on any error; on success writes the snapshot + commit node and
+ *  pushes the commit. */
+function commitState(run, input) {
+    const options = normalizeCommitOptions(input);
+    const now = new Date().toISOString();
+    const { result: backingResult, requiresEvidence } = backingResultFor(run, options.verifierNodeId || (options.reason.startsWith("result:") ? run.tasks.find((t) => t.id === options.reason.slice(7))?.verifierNodeId : undefined));
+    const gate = (0, commit_gate_1.resolveCommitGate)(run, options, {
+        now,
+        backingResult,
+        taskRequiresEvidence: requiresEvidence,
+        unresolvedFileEvidence: (0, evidence_grounding_1.requireResolvableEvidence)()
+            ? (evidence) => (0, evidence_grounding_1.unresolvedFileEvidence)(evidence, Array.from(new Set([run.cwd, process.cwd(), run.paths.runDir])), { exists: fs.existsSync, isAbsolute: path.isAbsolute, resolve: (base, rel) => path.resolve(base, rel) })
+            : undefined,
+    });
+    // Stack the review gate ON TOP of the verifier gate. An applicable review
+    // policy can only ADD required-approval constraints from authorized roles; it
+    // never relaxes verifier acceptance. Fail closed: a verifier-passing but
+    // un-approved commit is BLOCKED here. Provenance (who approved the shipped
+    // commit) is stamped only when NO errors remain. The old build wired this
+    // inside resolveVerifierGate; v2's resolver is pure, so it layers in the
+    // shell where the run's approval state lives.
+    let reviewProvenance;
+    if (gate.verifierGated) {
+        const reviewInput = {
+            targetKind: "commit",
+            candidateId: gate.candidateId,
+            selectionId: gate.selectionId,
+            selfActorIds: (0, collaboration_io_1.selfActorIdsForCandidate)(run, gate.candidateId, gate.selectionId),
+        };
+        const reviewErrors = (0, collaboration_io_1.reviewGateErrors)(run, reviewInput);
+        if (reviewErrors.length)
+            gate.errors.push(...reviewErrors);
+        else
+            reviewProvenance = (0, collaboration_io_1.commitReviewProvenance)(run, reviewInput);
+    }
+    if (gate.errors.length) {
+        throw recordCommitGateFailure(run, options, gate);
+    }
+    fs.mkdirSync(run.paths.commitsDir, { recursive: true });
+    const id = (0, commit_gate_1.formatCommitId)((run.commits || []).length + 1);
+    const snapshotPath = path.join(run.paths.commitsDir, `${id}.json`);
+    const rationale = gate.acceptanceRationale;
+    const audit = gate.verifierGated
+        ? (0, trust_audit_1.recordTrustAuditEvent)(run, { kind: "commit.gate", decision: "accepted", source: "cw-validated", workerId: rationale?.workerId, nodeId: gate.verifierNodeId, candidateId: gate.candidateId, selectionId: gate.selectionId, commitId: id, sandboxProfileId: rationale?.sandboxProfileId, evidence: gate.evidence, metadata: rationale })
+        : undefined;
+    const evidence = (0, trust_audit_1.normalizeEvidence)(run, gate.evidence, { source: gate.verifierGated ? "cw-validated" : "runtime-derived", workerId: rationale?.workerId, verifierNodeId: gate.verifierNodeId, candidateId: gate.candidateId, selectionId: gate.selectionId, commitId: id, auditEventIds: audit ? [audit.id] : [] });
+    const commit = {
+        id,
+        createdAt: now,
+        reason: options.reason,
+        loopStage: run.loopStage,
+        statePath: run.paths.state,
+        reportPath: run.paths.report,
+        snapshotPath,
+        gitHead: readGitHead(run.cwd),
+        verifierGated: gate.verifierGated,
+        checkpoint: !gate.verifierGated,
+        verifierNodeId: gate.verifierNodeId,
+        candidateId: gate.candidateId,
+        selectionId: gate.selectionId,
+        evidence,
+        // Acceptance rationale rides on the commit so `report`/`metrics`/audit can
+        // explain WHY it was accepted. commitGateResult reflects whether the gate
+        // ran (passed) or this was an unverified checkpoint; audit event id is
+        // threaded so the rationale points back at its own audit record.
+        ...(rationale
+            ? {
+                acceptanceRationale: {
+                    ...rationale,
+                    commitGateResult: gate.verifierGated ? "passed" : "checkpoint",
+                    auditEventIds: audit ? [...(rationale.auditEventIds || []), audit.id] : rationale.auditEventIds,
+                },
+            }
+            : {}),
+        metadata: { ...(options.metadata || {}), ...gate.metadata },
+        ...(reviewProvenance ? { review: reviewProvenance } : {}),
+    };
+    const commitNodeId = recordCommitNode(run, commit, options, gate);
+    if (commitNodeId)
+        commit.stateNodeId = commitNodeId;
+    // A verifier-gated commit is the run's checkpoint — advance the run-level loop
+    // stage. Guard on verifierGated so the initial plan/unverified checkpoint does
+    // NOT prematurely move the run off "interpret".
+    if (gate.verifierGated)
+        run.loopStage = "checkpoint";
+    (0, fs_atomic_1.writeJson)(snapshotPath, { commit, run });
+    run.commits.push(commit);
+    return commit;
+}
+function recordCommitNode(run, commit, options, gate) {
+    const verifierNode = gate.verifierNodeId ? findNode(run, gate.verifierNodeId) : undefined;
+    if (commit.verifierGated && verifierNode) {
+        const commitResult = (0, runner_1.runPipelineStage)(run, "commit", verifierNode.id, {
+            outputNodeId: `${run.id}:commit:${commit.id}`,
+            outputStatus: "committed",
+            loopStage: "checkpoint",
+            outputs: { snapshotPath: commit.snapshotPath, gitHead: commit.gitHead, verifierGated: true, verifierNodeId: verifierNode.id, candidateId: gate.candidateId, selectionId: gate.selectionId },
+            artifacts: [{ id: "snapshot", kind: "json", path: commit.snapshotPath }],
+            evidence: commit.evidence || verifierNode.evidence,
+            metadata: { ...(options.metadata || {}), reason: options.reason, commitId: commit.id, verifierGated: true, checkpoint: false, verifierNodeId: verifierNode.id, candidateId: gate.candidateId, selectionId: gate.selectionId, selectionNodeId: gate.selectionNodeId },
+        }, { persist: false, persistNode: node_store_1.writeRunNode });
+        if (gate.selectionNodeId && commitResult.outputNodeId)
+            linkAdditionalParent(run, gate.selectionNodeId, commitResult.outputNodeId);
+        return commitResult.outputNodeId;
+    }
+    const checkpointNode = (0, state_node_1.createStateNode)({
+        id: `${run.id}:checkpoint:${commit.id}`,
+        kind: "commit",
+        status: "completed",
+        loopStage: "checkpoint",
+        inputs: { reason: options.reason, commitId: commit.id },
+        outputs: { snapshotPath: commit.snapshotPath, gitHead: commit.gitHead, verifierGated: false, checkpoint: true },
+        artifacts: [{ id: "snapshot", kind: "json", path: commit.snapshotPath }],
+        contractId: contract_1.DEFAULT_PIPELINE_CONTRACT_ID,
+        metadata: { ...(options.metadata || {}), verifierGated: false, checkpoint: true },
+    });
+    (0, node_store_1.appendRunNode)(run, checkpointNode);
+    return checkpointNode.id;
+}
+function recordCommitGateFailure(run, options, gate) {
+    const first = gate.errors[0] || { code: "commit-gate-blocked", message: "Verifier-gated commit blocked", at: new Date().toISOString(), retryable: false };
+    const node = (0, state_node_1.recordNodeError)((0, state_node_1.createStateNode)({
+        id: `${run.id}:commit-gate-failed:${(0, commit_gate_1.gateFailureSeq)(run)}`,
+        kind: "error",
+        status: "pending",
+        loopStage: "checkpoint",
+        inputs: { reason: options.reason, verifierNodeId: gate.verifierNodeId, candidateId: gate.candidateId, selectionId: gate.selectionId },
+        evidence: gate.evidence,
+        contractId: contract_1.DEFAULT_PIPELINE_CONTRACT_ID,
+        metadata: {
+            ...(options.metadata || {}),
+            verifierGated: true,
+            checkpoint: false,
+            failureCount: gate.errors.length,
+            failures: gate.errors.map((entry) => ({ code: entry.code, message: entry.message, nodeId: entry.nodeId })),
+            gate: gate.metadata,
+        },
+    }), first);
+    const persisted = (0, node_store_1.appendRunNode)(run, node);
+    for (const parentId of [gate.selectionNodeId, gate.verifierNodeId].filter(Boolean)) {
+        linkAdditionalParent(run, parentId, persisted.id);
+    }
+    // Record the block as append-only operator feedback so the codes
+    // (commit-verifier-not-found / missing-evidence / review-gate-missing-
+    // approvals / …) are not lost — the old build did this and the commit gate's
+    // failure must surface visibly, not silently.
+    const feedback = (0, error_feedback_io_1.recordFeedback)(run, {
+        source: options.source === "cli" ? "cli" : "verifier",
+        error: first,
+        nodeId: persisted.id,
+        stageId: "commit",
+        contractId: contract_1.DEFAULT_PIPELINE_CONTRACT_ID,
+        retryable: false,
+        evidence: gate.evidence,
+        artifacts: [],
+        metadata: {
+            reason: options.reason,
+            verifierNodeId: gate.verifierNodeId,
+            candidateId: gate.candidateId,
+            selectionId: gate.selectionId,
+            failures: gate.errors.map((entry) => ({ code: entry.code, message: entry.message, nodeId: entry.nodeId })),
+        },
+    });
+    return new CommitGateError(first, { feedbackId: feedback.id, stateNodeId: persisted.id });
+}
+function linkAdditionalParent(run, parentId, childId) {
+    const parent = findNode(run, parentId);
+    const child = findNode(run, childId);
+    if (!parent || !child)
+        return;
+    const [linkedParent, linkedChild] = (0, state_node_1.linkStateNodes)(parent, child);
+    (0, node_store_1.appendRunNode)(run, linkedParent);
+    (0, node_store_1.appendRunNode)(run, linkedChild);
+}