faberun 0.25.1 → 0.26.1

package/src/plan/preflight.mjs

@@ -10,6 +10,7 @@ import { preflightRuntimes } from "../engine/live-preflight.mjs";
 import { liveSilenceCause } from "../engine/live-silence.mjs";
 import { harnessCapabilities } from "../harnesses/index.mjs";
 import { assertRuntimeExecutesCommands, validateRuntime } from "../contract/runtime.mjs";
+import { effectiveProvider } from "../contract/provider.mjs";
 
 /**
  * The runtimes a planning run will spend, asked once before its first stage.
@@ -109,10 +110,11 @@ export function refuseUnplannableRuntimes(runtimes, runtimeDefaults, packageMode
   const seen = new Set();
   for (let id = /** @type {string|undefined} */ (worker); id && runtimes[id] && !seen.has(id); id = /** @type {string|undefined} */ (runtimes[id].fallback)) {
     seen.add(id);
-    if (typeof runtimes[id].vendor === "string") vendors.add(/** @type {string} */ (runtimes[id].vendor));
+    const provider = effectiveProvider(/** @type {import("../contract/provider.mjs").ProviderInput & {vendor?: string}} */ (runtimes[id]));
+    if (provider !== undefined) vendors.add(provider);
   }
-  const judgeVendor = runtimes[judge].vendor;
-  if (typeof judgeVendor === "string" && vendors.has(judgeVendor)) {
+  const judgeVendor = effectiveProvider(/** @type {import("../contract/provider.mjs").ProviderInput & {vendor?: string}} */ (runtimes[judge]));
+  if (judgeVendor !== undefined && vendors.has(judgeVendor)) {
     throw new Error(`--runtime-defaults judge=${judge} shares vendor ${judgeVendor} with worker ${worker} or its fallback, so no frozen node could route its judge; name a judge of another vendor`);
   }
 }

package/src/plan/proof-check.mjs

@@ -0,0 +1,161 @@
+/**
+ * A deterministic stage between the draft and the first review round (R15):
+ * finds a Definition of Done proof no node can satisfy, without invoking a
+ * model. Two shapes of unsatisfiable proof are checked: a
+ * `--test-name-pattern` naming no test the tree has and no test file any
+ * node's `writeFiles` promises to add, and a bare `grep`/`grep -c` proof whose
+ * own DoD text claims the absence of what it greps for — grep exits 1 when
+ * nothing matches, so a proof shaped that way cannot exit 0 in the very state
+ * the node promises. Lives apart from `rounds.mjs` because both the pipeline
+ * (before any round) and every later round's own findings feed off the same
+ * plan-wide scan; this module owns none of the round bookkeeping.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { shellWords } from "../util.mjs";
+import { NAME_PATTERN_FLAG } from "./proof-run.mjs";
+
+/** @typedef {import("./template.mjs").PlanOutput} PlanOutput */
+/** @typedef {import("./template.mjs").PlanOutputNode} PlanOutputNode */
+/** @typedef {import("./template.mjs").PlanFindingOutput} PlanFindingOutput */
+/** @typedef {import("../contract/definition-of-done.mjs").DefinitionOfDoneItem} DefinitionOfDoneItem */
+/** @typedef {import("./repo-facts.mjs").RepoFacts} RepoFacts */
+
+/**
+ * A test title inside a `test(...)`/`test.only(...)`/`test.skip(...)` call,
+ * quoted with any of the three ordinary JS quote characters.
+ */
+const TEST_TITLE = /\btest(?:\.\w+)?\(\s*(["'`])((?:\\.|(?!\1).)*)\1/gu;
+
+/**
+ * Words an English Definition of Done uses to promise that something is
+ * gone, not present — the direction in which a bare `grep` cannot exit 0.
+ * Text-based and therefore inexact, but the same restraint the rest of this
+ * pipeline already accepts for a deterministic check: a plain `grep` proving
+ * presence (the ordinary case) is left alone, because flagging every `grep`
+ * regardless of direction would drown the one finding this stage exists for.
+ */
+const ABSENCE_CLAIM = /\b(?:no longer|not |never |removed|absent|without |must not|should not|does ?n[o']t|isn['’]t|no more|zero (?:occurrences|matches|instances)|nowhere)\b/iu;
+
+/**
+ * The command text a DoD proof actually runs: `kind: "command"` carries it
+ * verbatim, `kind: "verification"` carries the (already index-normalized,
+ * see `contract/definition-of-done.mjs`) position of one of the node's own
+ * `verification` entries. `kind: "path"` has no command at all.
+ *
+ * @param {PlanOutputNode} node
+ * @param {DefinitionOfDoneItem["proof"]} proof
+ * @returns {string|null}
+ */
+function proofCommandText(node, proof) {
+  if (!proof) return null;
+  if (proof.kind === "command") return proof.ref;
+  if (proof.kind === "verification") {
+    const command = node.verification[Number(proof.ref)];
+    return command ? command.argv.join(" ") : null;
+  }
+  return null;
+}
+
+/**
+ * Whether `pattern` (a `--test-name-pattern` value, a regular expression) is
+ * satisfied by a test title already declared in one of `repoFacts.testFiles`
+ * — read straight off disk, since repo facts records only the path, never
+ * the titles inside it.
+ *
+ * @param {string} cwd
+ * @param {RepoFacts} repoFacts
+ * @param {string} pattern
+ * @returns {boolean}
+ */
+function matchesAnExistingTest(cwd, repoFacts, pattern) {
+  /** @type {RegExp} */
+  let regex;
+  try {
+    regex = new RegExp(pattern, "u");
+  } catch {
+    return false;
+  }
+  for (const entry of repoFacts.testFiles) {
+    /** @type {string} */
+    let source;
+    try {
+      source = readFileSync(join(cwd, entry.path), "utf8");
+    } catch {
+      continue;
+    }
+    for (const match of source.matchAll(TEST_TITLE)) {
+      if (regex.test(match[2])) return true;
+    }
+  }
+  return false;
+}
+
+/** @param {PlanOutput} plan @returns {boolean} */
+function someNodeWritesATestFile(plan) {
+  return plan.nodes.some((node) => node.writeFiles.some((path) => /^test\/.*\.test\.mjs$/u.test(path)));
+}
+
+/**
+ * Whether `commandText` is a `grep` proof no revise can protect against
+ * failing in the state it promises: the base command is `grep` (optionally
+ * `-c`), and it carries neither of the two shapes that make its exit code
+ * mean what a proof needs (`! grep -q …`, or a trailing `|| true`, which
+ * always exits 0 whatever grep found).
+ *
+ * @param {string} commandText
+ * @returns {boolean}
+ */
+function isUnguardedGrep(commandText) {
+  const tokens = shellWords(commandText);
+  if (tokens.length === 0) return false;
+  const negated = tokens[0] === "!";
+  const base = negated ? tokens[1] : tokens[0];
+  if (base !== "grep") return false;
+  if (negated && tokens.includes("-q")) return false;
+  if (tokens.length >= 2 && tokens[tokens.length - 2] === "||" && tokens[tokens.length - 1] === "true") return false;
+  return true;
+}
+
+/**
+ * Every DoD proof in `plan` no node can satisfy, checked without a model:
+ * see the module header for the two shapes this looks for. Returns one
+ * finding per unsatisfiable proof, in plan order, ready to merge into the
+ * findings the first review round already carries.
+ *
+ * @param {PlanOutput} plan
+ * @param {RepoFacts} repoFacts
+ * @param {string} cwd
+ * @returns {PlanFindingOutput[]}
+ */
+export function checkPlanProofs(plan, repoFacts, cwd) {
+  /** @type {PlanFindingOutput[]} */
+  const findings = [];
+  for (const node of plan.nodes) {
+    for (const item of node.definitionOfDone) {
+      const commandText = proofCommandText(node, item.proof);
+      if (commandText === null) continue;
+      const nameFlag = NAME_PATTERN_FLAG.exec(commandText);
+      if (nameFlag) {
+        const pattern = nameFlag[1] ?? nameFlag[2] ?? nameFlag[3];
+        if (matchesAnExistingTest(cwd, repoFacts, pattern) || someNodeWritesATestFile(plan)) continue;
+        findings.push({
+          id: `proof-unmet-${node.id}-${item.id}`,
+          severity: "critical",
+          nodeId: node.id,
+          text: `Node ${node.id}'s Definition of Done item "${item.id}" proves itself with --test-name-pattern="${pattern}", which matches no test already in the tree and no test file any node's writeFiles declares. Either name a test that already exists, or have some node's writeFiles add the test file this pattern will match.`,
+        });
+        continue;
+      }
+      if (isUnguardedGrep(commandText) && ABSENCE_CLAIM.test(item.text)) {
+        findings.push({
+          id: `proof-unmet-${node.id}-${item.id}`,
+          severity: "critical",
+          nodeId: node.id,
+          text: `Node ${node.id}'s Definition of Done item "${item.id}" claims an absence ("${item.text}") but proves it with a bare grep ("${commandText}"): grep exits 1 when nothing matches, so this proof cannot exit 0 in the state the node promises. Write it as "! grep -q …" instead.`,
+        });
+      }
+    }
+  }
+  return findings;
+}

package/src/plan/proof-run.mjs

@@ -106,8 +106,12 @@ function runShellFull(cwd, command, probes = {}, timeoutMs = MEASURE_TIMEOUT_MS)
   return { output: combined, exitCode: result.status, truncated: Buffer.byteLength(combined, "utf8") > MEASURE_OUTPUT_CAP_BYTES, timedOut };
 }
 
-/** `--test-name-pattern` in a shell command, quoted or bare, `=` or space. */
-const NAME_PATTERN_FLAG = /--test-name-pattern(?:=|\s+)(?:"([^"]*)"|'([^']*)'|(\S+))/u;
+/**
+ * `--test-name-pattern` in a shell command, quoted or bare, `=` or space.
+ * Exported for `proof-check.mjs`, whose pre-review stage extracts the same
+ * flag from a DoD proof's own command text to judge it before any node runs.
+ */
+export const NAME_PATTERN_FLAG = /--test-name-pattern(?:=|\s+)(?:"([^"]*)"|'([^']*)'|(\S+))/u;
 /** A passing test as the spec reporter (`✔ name (1ms)`) or TAP (`ok 1 - name`) prints it. */
 const PASSING_TEST_LINE = /^\s*(?:\u2714\s+|ok \d+ - )(.+?)(?:\s+\(\d[\d.]*m?s\))?\s*$/gmu;
 

package/src/plan/proof-scope.mjs

@@ -0,0 +1,175 @@
+/**
+ * Proof and scope coherence decided when a plan freezes, before any worker
+ * attempt is spent on a node that cannot pass: a name-filtered node:test proof
+ * must name the file its test lives in (AP1 of safe-to-hand-to-a-friend), and
+ * a node that creates a file in a directory a test enumerates by name must be
+ * allowed to edit that test (AP2). Separate from `freeze.mjs` because both
+ * read the target repository's test sources, which the freeze's contract and
+ * timeout checks never do, and from `proof-check.mjs` because that stage only
+ * raises findings for a review round, while these run on the frozen shape.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { shellWords } from "../util.mjs";
+
+/** @typedef {import("./template.mjs").PlanOutput} PlanOutput */
+/** @typedef {import("../contract/index.mjs").ValidatedContract} ValidatedContract */
+
+/** `node` options whose value is the next argument, so it is not a path. */
+export const NODE_VALUE_OPTIONS = new Set(["--import", "--require", "-r", "--loader", "--experimental-loader", "--env-file", "--test-reporter", "--test-reporter-destination", "--test-name-pattern", "--test-skip-pattern", "--test-concurrency", "--test-timeout"]);
+
+const NAME_FILTER_FLAGS = ["--test-name-pattern", "--test-skip-pattern"];
+
+/** A test title in a `test(…)`/`it(…)`/`describe(…)` call, any of the three JS quotes. */
+const TEST_TITLE = /\b(?:test|it|describe)(?:\.\w+)?\(\s*(["'`])((?:\\.|(?!\1).)*)\1/gu;
+
+/**
+ * The name filters and path arguments of a `node --test` command, or null
+ * when the command is not one.
+ *
+ * @param {string[]} argv
+ * @returns {{nameFilters: Array<{flag: string, value: string}>, paths: string[]}|null}
+ */
+function nodeTestShape(argv) {
+  if (argv[0] !== "node" || !argv.includes("--test")) return null;
+  /** @type {Array<{flag: string, value: string}>} */
+  const nameFilters = [];
+  /** @type {string[]} */
+  const paths = [];
+  for (let index = 1; index < argv.length; index += 1) {
+    const token = argv[index];
+    const inline = NAME_FILTER_FLAGS.find((flag) => token.startsWith(`${flag}=`));
+    if (inline) nameFilters.push({ flag: inline, value: token.slice(inline.length + 1) });
+    else if (NAME_FILTER_FLAGS.includes(token)) nameFilters.push({ flag: token, value: argv[index + 1] ?? "" });
+    if (NODE_VALUE_OPTIONS.has(token)) index += 1;
+    else if (!token.startsWith("-")) paths.push(token);
+  }
+  return { nameFilters, paths };
+}
+
+/**
+ * Refuse a contract with a name-filtered `node --test` proof that cannot
+ * select the test it names. Checked on every Definition of Done command proof
+ * and every packet verification command. Measured 2026-09-26 on node v26.8.1:
+ * with no path, `node --test` runs every test file in the tree, and every
+ * file the filter selects nothing in prints its own zero plan, so a proof
+ * with no file both costs the whole suite and reads as having measured
+ * nothing. A named file that some node writes is accepted as the test to be
+ * written; a named file nobody writes must already hold a test the pattern
+ * selects.
+ *
+ * @param {ValidatedContract} contract
+ * @returns {void}
+ */
+export function assertFilteredProofsNameTheirTest(contract) {
+  const written = new Set(contract.nodes.flatMap((node) => node.taskPacket.writeFiles));
+  /** @type {string[]} */
+  const problems = [];
+  for (const node of contract.nodes) {
+    const commands = [
+      ...(node.definitionOfDone ?? []).flatMap((item) => (item.proof?.kind === "command" ? [{ argv: shellWords(item.proof.ref), cwd: contract.cwd }] : [])),
+      ...(node.taskPacket.verification ?? []).map((command) => ({ argv: command.argv, cwd: resolve(contract.cwd, command.cwd ?? ".") })),
+    ];
+    for (const { argv, cwd } of commands) {
+      const shape = nodeTestShape(argv);
+      if (!shape || shape.nameFilters.length === 0) continue;
+      const shown = argv.join(" ");
+      if (shape.paths.length === 0) {
+        problems.push(`${node.id}: "${shown}" filters node:test by name but names no test file; with no path node --test runs every test file in the tree and each file the filter selects nothing in prints a zero plan. Name the file that holds the test, as in node --test --test-name-pattern="<title>" test/<file>.test.mjs`);
+        continue;
+      }
+      const namePattern = shape.nameFilters.find(({ flag }) => flag === "--test-name-pattern")?.value;
+      if (namePattern === undefined) continue;
+      for (const path of shape.paths) {
+        const absolute = resolve(cwd, path);
+        if (written.has(path) || !existsSync(absolute) || !statSync(absolute).isFile()) continue;
+        if (!fileHasMatchingTest(absolute, namePattern)) {
+          problems.push(`${node.id}: "${shown}" selects no test in ${path}: no test title there matches --test-name-pattern "${namePattern}", and no node writes ${path}`);
+        }
+      }
+    }
+  }
+  if (problems.length) throw new TypeError(`name-filtered proofs cannot select their test: ${problems.join("; ")}`);
+}
+
+/**
+ * @param {string} path
+ * @param {string} pattern
+ * @returns {boolean}
+ */
+function fileHasMatchingTest(path, pattern) {
+  /** @type {RegExp} */
+  let regex;
+  try {
+    regex = new RegExp(pattern, "u");
+  } catch {
+    // node --test would reject the pattern too; nothing it names can match.
+    return false;
+  }
+  return [...readFileSync(path, "utf8").matchAll(TEST_TITLE)].some((match) => regex.test(match[2]));
+}
+
+/**
+ * Declare, in the writeFiles of every node that creates a file in a
+ * directory, each test that enumerates that directory by name — a test whose
+ * source names the directory and every entry it holds today. Such a test
+ * cannot pass once the directory gains an entry unless it is edited too, and
+ * the gate refuses an edit to a file a proof cites that the node did not
+ * declare. Measured 2026-09-26 (AP2 of safe-to-hand-to-a-friend): the node
+ * adding skills/faberun/references/local-env.md failed on
+ * test/docs/docs-diet.test.mjs, which lists references/ exactly. The repair
+ * has one answer, so it is applied rather than raised; each one is returned
+ * with its reason so the caller can print it. A directory with fewer than two
+ * entries is skipped: naming one file is not evidence of an exact listing.
+ *
+ * @param {PlanOutput} plan
+ * @param {{testFiles: Array<{path: string}>}} repoFacts
+ * @param {string} cwd
+ * @returns {{plan: PlanOutput, declared: string[]}}
+ */
+export function declareDirectoryGuards(plan, repoFacts, cwd) {
+  /** @type {Map<string, string>} */
+  const sources = new Map();
+  /** @param {string} path @returns {string} */
+  const sourceOf = (path) => {
+    if (!sources.has(path)) {
+      /** @type {string} */
+      let text = "";
+      try {
+        text = readFileSync(join(cwd, path), "utf8");
+      } catch {
+        // A listed test file that is gone enumerates nothing.
+      }
+      sources.set(path, text);
+    }
+    return /** @type {string} */ (sources.get(path));
+  };
+  /** @type {string[]} */
+  const declared = [];
+  const nodes = plan.nodes.map((node) => {
+    const added = new Set();
+    for (const path of node.writeFiles) {
+      if (existsSync(join(cwd, path))) continue;
+      const directory = dirname(path);
+      if (directory === "." || !existsSync(join(cwd, directory))) continue;
+      const entries = readdirSync(join(cwd, directory));
+      if (entries.length < 2) continue;
+      for (const { path: testPath } of repoFacts.testFiles) {
+        if (node.writeFiles.includes(testPath) || added.has(testPath)) continue;
+        const source = sourceOf(testPath);
+        if (!source.includes(directory) && !source.includes(directory.slice(directory.lastIndexOf("/") + 1) + "/")) continue;
+        if (!entries.every((entry) => source.includes(`'${entry}'`) || source.includes(`"${entry}"`) || source.includes(`\`${entry}\``))) continue;
+        added.add(testPath);
+        declared.push(`${node.id}: declared ${testPath} in writeFiles: it lists every entry of ${directory}/ by name, and this node creates ${path} there`);
+      }
+    }
+    if (added.size === 0) return node;
+    return {
+      ...node,
+      readFiles: node.readFiles.filter((path) => !added.has(path)),
+      scopeAcknowledged: node.scopeAcknowledged.filter((path) => !added.has(path)),
+      writeFiles: [...node.writeFiles, ...added],
+    };
+  });
+  return { plan: declared.length ? { ...plan, nodes } : plan, declared };
+}

package/src/plan/resolve.mjs

@@ -0,0 +1,182 @@
+/**
+ * `faberun plan --resolve` (R9): the operator's answer to a contested plan.
+ * A contest already lists every critical finding with its id, the node or
+ * requirement it concerns, and what would resolve it (`plan.json`, written by
+ * `contest.mjs`); this module reads that record back, requires an
+ * `accept`/`reject` decision for each critical finding, records every
+ * decision on the campaign journal, and resumes at the review stage's own
+ * exit — straight into the same sizing/routing/freeze assembly a fresh plan
+ * runs through (`assembleFrozenPlan`/`frozenContractRawOf` in
+ * `pipeline.mjs`) — without redrafting or asking a provider anything. The
+ * operator's decision is what a review round would otherwise have to
+ * produce: `accept` proceeds despite the finding, `reject:<reason>` dismisses
+ * it with the operator's own reasoning; either way the finding stops
+ * blocking freeze once it is answered. Separate from `pipeline.mjs` because
+ * it starts from a `plan.json` a previous run already wrote instead of an
+ * empty scratch directory, and needs none of that module's draft or provider
+ * seams.
+ */
+import { readFileSync, rmSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { readCampaign } from "../campaign/record.mjs";
+import { campaignCli } from "../cli/campaign.mjs";
+import { campaignTree } from "../run/paths.mjs";
+import { appendJsonl, readJson } from "../run/store.mjs";
+import { freezePlan } from "./freeze.mjs";
+import { collectHumanSteps } from "./human-step.mjs";
+import { highestOf, modelOf } from "./pipeline-shape.mjs";
+import { reviewerProvenanceOf } from "./reviewer.mjs";
+import { PLANNER_SESSION_ID, assembleFrozenPlan, frozenContractRawOf, invalidPlanFinding, writeFrozenPlan } from "./pipeline.mjs";
+import { contestPlan } from "./contest.mjs";
+import { parseSpec } from "./spec.mjs";
+import { RISK_TIERS } from "./template.mjs";
+
+/** @typedef {import("./template.mjs").PlanOutput} PlanOutput */
+/** @typedef {import("./template.mjs").PlanFindingOutput} PlanFindingOutput */
+/** @typedef {import("./contest.mjs").ContestedPlanRecord} ContestedPlanRecord */
+/** @typedef {import("./contest.mjs").ContestedPipelineResult} ContestedPipelineResult */
+/** @typedef {import("./pipeline.mjs").FrozenPipelineResult} FrozenPipelineResult */
+/** @typedef {{decision: "accept"|"reject", reason?: string}} FindingAnswer */
+
+/**
+ * `--answer <finding-id>=accept` or `--answer <finding-id>=reject:<reason>`,
+ * one flag per critical finding, split on the first `=`. `reject` further
+ * splits on the first `:` for its reason, which may itself contain `:`, and
+ * the reason must not be empty — a bare `reject` names no rationale to record.
+ *
+ * @param {string[]} rawAnswers
+ * @returns {Map<string, FindingAnswer>}
+ */
+export function parseAnswerFlags(rawAnswers) {
+  /** @type {Map<string, FindingAnswer>} */
+  const answers = new Map();
+  for (const raw of rawAnswers) {
+    const eq = raw.indexOf("=");
+    if (eq < 0) throw new Error(`--answer must be <finding-id>=accept or <finding-id>=reject:<reason>: ${raw}`);
+    const findingId = raw.slice(0, eq);
+    const rest = raw.slice(eq + 1);
+    if (!findingId) throw new Error(`--answer finding id must not be empty: ${raw}`);
+    if (rest === "accept") {
+      answers.set(findingId, { decision: "accept" });
+      continue;
+    }
+    if (rest === "reject" || rest.startsWith("reject:")) {
+      const reason = rest === "reject" ? "" : rest.slice("reject:".length);
+      if (!reason) throw new Error(`--answer reject requires a reason: ${raw}`);
+      answers.set(findingId, { decision: "reject", reason });
+      continue;
+    }
+    throw new Error(`--answer must be <finding-id>=accept or <finding-id>=reject:<reason>: ${raw}`);
+  }
+  return answers;
+}
+
+/**
+ * The decision text one operator answer becomes on the campaign journal:
+ * bounded and self-contained, never the finding's own text — that already
+ * lives in `plan.json`, and repeating it here is exactly the shape of
+ * over-long note RM-105 fixed in `contest.mjs`.
+ *
+ * @param {PlanFindingOutput} finding
+ * @param {FindingAnswer} answer
+ * @returns {string}
+ */
+function decisionText(finding, answer) {
+  const verb = answer.decision === "accept" ? "Accepted" : "Rejected";
+  return answer.reason ? `${verb} finding ${finding.id} (${finding.nodeId}): ${answer.reason}` : `${verb} finding ${finding.id} (${finding.nodeId}).`;
+}
+
+/**
+ * Resume a contested plan from the operator's answers.
+ *
+ * @param {{plansDir: string, cwd: string, answers: Map<string, FindingAnswer>}} options
+ * @returns {Promise<FrozenPipelineResult|ContestedPipelineResult>}
+ */
+export async function resolvePlanningPipeline({ plansDir, cwd, answers }) {
+  const planPath = join(plansDir, "plan.json");
+  const record = /** @type {ContestedPlanRecord} */ (/** @type {unknown} */ (readJson(planPath)));
+  if (record.status !== "contested") throw new Error(`plan at ${planPath} is not contested (status: ${record.status})`);
+  if (!record.plan) throw new Error(`plan at ${planPath} has no plan to resume: the draft or revise that produced it never validated; run faberun plan again instead of --resolve`);
+  if (!record.resume) throw new Error(`plan at ${planPath} predates faberun plan --resolve and carries no resume context; run faberun plan again`);
+  const { campaignId, phase, specPath, specDigest, runtimeDefaults, reviewers, runtimes, verification, packageMode, targetedFix, approveBelow, repoFacts } = record.resume;
+  // R16: recomputed from the same spec bytes the contest recorded, so a plan
+  // resumed through --resolve carries the same declared operator steps a
+  // fresh freeze would.
+  const humanSteps = collectHumanSteps(parseSpec(readFileSync(resolve(cwd, specPath), "utf8")).requirements);
+  const plan = /** @type {PlanOutput} */ (record.plan);
+  const findings = /** @type {PlanFindingOutput[]} */ (record.findings ?? []);
+  const round = record.rounds ?? 0;
+
+  const campaignPath = campaignTree(cwd, campaignId);
+  const campaign = readCampaign(campaignPath);
+  if (campaign.status !== "active") throw new Error(`campaign is closed: ${campaignId}`);
+
+  const criticalFindings = findings.filter((finding) => finding.severity === "critical");
+  const criticalIds = new Set(criticalFindings.map((finding) => finding.id));
+  const unknown = [...answers.keys()].filter((id) => !criticalIds.has(id));
+  if (unknown.length > 0) throw new Error(`--answer names finding(s) that are not open critical findings on this plan: ${unknown.join(", ")}`);
+  const missing = criticalFindings.filter((finding) => !answers.has(finding.id)).map((finding) => finding.id);
+  if (missing.length > 0) throw new Error(`every critical finding needs an --answer before the plan can resolve: ${missing.join(", ")}`);
+
+  const pipelineLog = join(plansDir, "pipeline.jsonl");
+  /** @param {string} stage @param {Record<string, unknown>} [extra] */
+  const logStage = (stage, extra = {}) => appendJsonl(pipelineLog, { type: "plan.stage", at: new Date().toISOString(), campaignId, phase, stage, ...extra });
+
+  for (const finding of criticalFindings) {
+    const answer = /** @type {FindingAnswer} */ (answers.get(finding.id));
+    await campaignCli([
+      "note", campaignId, "--cwd", cwd, "--session-id", PLANNER_SESSION_ID,
+      "--kind", "decision", "--decision-id", `plan-${phase}-${finding.id}`,
+      "--text", decisionText(finding, answer),
+    ]);
+  }
+  logStage("resolve", { round, answered: criticalFindings.length });
+
+  const freezeWarnings = verification.sharedVerification || verification.finalVerification
+    ? []
+    : ["the frozen contract carries neither sharedVerification nor finalVerification, so no repository ratchet runs on its nodes and no final check closes the phase; pass --verification <file> if the target repository has ratchets every node must run"];
+  let stage = "sizing";
+  try {
+    const assembled = assembleFrozenPlan(plan, { repoFacts, packageMode, targetedFix, phase, cwd, runtimes, runtimeDefaults });
+    stage = "freeze";
+    logStage("sizing", { transformations: assembled.sizing.transformations.length, nodeCount: assembled.sizing.plan.nodes.length, overheadMinutes: assembled.sizing.estimate.overheadMinutes });
+    logStage("routing", { assignments: Object.keys(assembled.routing.assignments).length });
+    const highestRiskTier = highestOf(assembled.sizing.plan.nodes.map((node) => node.riskTier ?? RISK_TIERS[0]));
+    const frozen = freezePlan(frozenContractRawOf(assembled, { campaignId, phase, campaignGoal: campaign.goal, cwd, plansDir, runtimes, runtimeDefaults, verification }), {
+      outDir: plansDir,
+      phases: assembled.phases,
+      spec: { path: specPath, digest: specDigest },
+      humanSteps,
+      facts: repoFacts,
+      provenance: {
+        targetGitHead: repoFacts.gitHead,
+        planner: { runtimeId: runtimeDefaults.worker ?? "", model: modelOf(runtimes, runtimeDefaults.worker) },
+        reviewer: reviewerProvenanceOf(reviewers, runtimes),
+        sizing: assembled.sizing.transformations,
+        findings,
+      },
+    });
+    logStage("freeze", { contractId: `${campaignId}-${phase}`, highestRiskTier, ...(freezeWarnings.length ? { warnings: freezeWarnings } : {}) });
+
+    const approved = approveBelow === "high" ? true : approveBelow === "none" ? false : highestRiskTier !== "high";
+    writeFrozenPlan(plansDir, frozen, { status: "frozen", approved });
+    if (!approved) {
+      await campaignCli([
+        "note", campaignId, "--cwd", cwd, "--session-id", PLANNER_SESSION_ID,
+        "--kind", "open-question", "--question-id", `plan-${phase}-approval`,
+        "--text", `Plan for phase ${phase} carries a ${highestRiskTier}-risk node; approval is required under --approve-below ${approveBelow}.`,
+      ]);
+    }
+    logStage("approval", { approved, approveBelow, highestRiskTier });
+    return { status: "frozen", plansDir, planPath, contractPath: join(plansDir, "contract.json"), approved, findings, warnings: freezeWarnings };
+  } catch (error) {
+    const failedStage = /** @type {{planStage?: string}} */ (error)?.planStage ?? stage;
+    logStage(failedStage, { failed: error instanceof Error ? error.message : String(error) });
+    const failureFinding = invalidPlanFinding(failedStage, error);
+    rmSync(join(plansDir, "contract.json"), { force: true });
+    return await contestPlan({
+      campaignId, phase, cwd, plansDir, sessionId: PLANNER_SESSION_ID,
+      findings: [...findings, failureFinding], round, plan, resume: record.resume, logStage,
+    });
+  }
+}

package/src/plan/reviewer.mjs

@@ -0,0 +1,82 @@
+/**
+ * R19: the planner's own ordered reviewer list, kept separate from R18's
+ * judge list (`src/engine/judge-list.mjs`) even when an operator names the
+ * same runtime in both. The frozen contract's judge is chosen at run time,
+ * per node, from the judge list; the plan's own `review`/`spec-review` stage
+ * is chosen once per stage, from this list, by `firstEligibleReviewer` alone
+ * -- no cross-vendor rule runs here, because a plan reviewer grades a
+ * planning artefact rather than a worker's node (D11), so vendor
+ * independence from a worker is not the property this list protects.
+ *
+ * Lives beside the pipeline rather than inside `judge-list.mjs` so the two
+ * lists cannot accidentally converge on one resolver: `judge-list.mjs` reads
+ * `contract.judges`/`config.judges`, this module reads `reviewers` from the
+ * CLI and `config.reviewers`, and neither import the other.
+ */
+import { validateRuntime } from "../contract/runtime.mjs";
+import { getHarness } from "../harnesses/index.mjs";
+import { availabilityKey, readRefusal } from "../run/availability.mjs";
+import { modelOf } from "./pipeline-shape.mjs";
+
+/** @typedef {import("../contract/index.mjs").JsonObject} JsonObject */
+/** @typedef {{runtimeId: string, model: string}} ReviewerProvenance */
+
+/**
+ * The reviewer list a plan pipeline reads: `--reviewers` wins over the
+ * machine default, exactly as `resolveJudgeList` (R18) prefers a contract's
+ * own list over the machine's.
+ *
+ * @param {{reviewers?: string[]}} options
+ * @param {{reviewers?: string[]}|null|undefined} config
+ * @returns {string[]|undefined}
+ */
+export function resolveReviewerList(options, config) {
+  return options.reviewers ?? config?.reviewers ?? undefined;
+}
+
+/**
+ * The first eligible entry of an ordered reviewer list: declared in the
+ * runtimes catalogue and carrying no recorded refusal. Unlike `selectListJudge`
+ * (R18), this never excludes a candidate for sharing the worker's provider --
+ * a plan reviewer is not judging the worker that authored the plan, so that
+ * independence rule does not apply here (D11).
+ *
+ * @param {string[]} list
+ * @param {Record<string, JsonObject>} runtimes
+ * @param {number} [now]
+ * @returns {string|null}
+ */
+export function firstEligibleReviewer(list, runtimes, now = Date.now()) {
+  for (const id of list) {
+    const raw = runtimes[id];
+    if (raw === undefined) continue;
+    /** @type {import("../contract/index.mjs").ValidatedRuntime} */
+    let runtime;
+    try {
+      runtime = validateRuntime(id, raw);
+    } catch {
+      continue;
+    }
+    const key = availabilityKey({ harness: runtime.harness, model: runtime.model, executable: getHarness(runtime.harness).executable(runtime) });
+    if (readRefusal(key, now)) continue;
+    return id;
+  }
+  return null;
+}
+
+/**
+ * The reviewer fact a frozen plan's provenance records: the first eligible
+ * entry of the list at the moment of freezing, and its model. An empty or
+ * exhausted list records an empty runtime id, exactly as an unset
+ * `runtimeDefaults.judge` did before R19 -- freezing never refuses on this
+ * alone, since a plan with no reviewer configured is legitimate.
+ *
+ * @param {string[]|undefined} reviewers
+ * @param {Record<string, JsonObject>} runtimes
+ * @param {number} [now]
+ * @returns {ReviewerProvenance}
+ */
+export function reviewerProvenanceOf(reviewers, runtimes, now = Date.now()) {
+  const id = firstEligibleReviewer(reviewers ?? [], runtimes, now);
+  return { runtimeId: id ?? "", model: modelOf(runtimes, id ?? undefined) };
+}