faberun 0.20.0 → 0.22.0

package/src/plan/pipeline.mjs

@@ -30,7 +30,8 @@ import { collectRepoFacts } from "./repo-facts.mjs";
 import { RISK_TIERS, TASK_KIND_CATALOGUE_FILE, buildPlanningContract, renderTaskKindCatalogue, validateFindings, validatePlanOutput } from "./template.mjs";
 import { MIN_WRITE_FILES, applySizingRules, provenParallelism } from "./sizing.mjs";
 import { resolveRuntimes } from "./routing.mjs";
-import { freezePlan } from "./freeze.mjs";
+import { assertTimeoutsCoverMeasured, contentDigest, freezePlan, writeFrozenPlanRecord } from "./freeze.mjs";
+import { availabilityOf, fileLineCount, highestOf, modelOf, toContractNode, toSizingNode } from "./pipeline-shape.mjs";
 import { campaignTree, runDirectory } from "../run/paths.mjs";
 
 /** @typedef {import("../contract/index.mjs").JsonObject} JsonObject */
@@ -39,8 +40,9 @@ import { campaignTree, runDirectory } from "../run/paths.mjs";
 /** @typedef {{sharedVerification?: VerificationCommand[], finalVerification?: VerificationCommand[]}} VerificationSuites */
 /** @typedef {import("./template.mjs").PlanOutput} PlanOutput */
 /** @typedef {import("./template.mjs").PlanFindingOutput} PlanFindingOutput */
+/** @typedef {import("./template.mjs").PlanPhase} PlanPhase */
 /** @typedef {import("./sizing.mjs").PlanNode & {objective: string}} SizedPlanNode */
-/** @typedef {{sizing: import("./sizing.mjs").SizingResult, routing: import("./routing.mjs").RoutingResult, nodes: JsonObject[]}} AssembledPlan */
+/** @typedef {{sizing: import("./sizing.mjs").SizingResult, routing: import("./routing.mjs").RoutingResult, nodes: JsonObject[], phases?: PlanPhase[]}} AssembledPlan */
 /** @typedef {"standard"|"high"|"none"} ApproveBelow */
 /** @typedef {(contractPath: string, contract: ValidatedContract) => Promise<void>|void} LaunchFn */
 /** @typedef {(runtimes: Record<string, JsonObject>, runtimeDefaults: {worker?: string, judge?: string}, cwd: string) => Promise<import("../harnesses/index.mjs").ProbeResult[]>} AskFn */
@@ -113,6 +115,9 @@ export async function runPlanningPipeline(options) {
 
   const relativeSpecPath = repoRelativePath(cwd, specPath, "specPath");
   const specText = readFileSync(resolve(cwd, relativeSpecPath), "utf8");
+  // Pinned now, from the same bytes every planning stage reads, so the frozen
+  // record names the exact structured spec it was planned from.
+  const specDigest = contentDigest(specText);
   const specValidation = validateSpec(specText, { cwd, strict: true });
   if (specValidation.class === "structured" && !specValidation.ok) {
     const detail = specValidation.findings.map((finding) => `${finding.rule}: ${finding.message}`).join("; ");
@@ -276,6 +281,11 @@ export async function runPlanningPipeline(options) {
       sizing,
       routing,
       nodes: sizing.plan.nodes.map((node) => toContractNode(/** @type {SizedPlanNode} */ (node), phase, routing.assignments[node.id])),
+      // The declarations a reviewer saw, remapped onto the nodes sizing
+      // actually produced: a merge removes a node id, and a declaration that
+      // named it must now name the node that absorbed it or freeze would see
+      // an unknown assignment.
+      phases: carryPhaseDeclarations(currentPlan.phases, sizing.transformations),
     };
   };
 
@@ -354,7 +364,7 @@ export async function runPlanningPipeline(options) {
       /** @type {PlanFindingOutput|null} */
       let freezeFailure = null;
       try {
-        validateContract(frozenContractRaw(assembleFrozenNodes(plan)), join(plansDir, "contract.json"));
+        assertTimeoutsCoverMeasured(validateContract(frozenContractRaw(assembleFrozenNodes(plan)), join(plansDir, "contract.json")), repoFacts);
       } catch (error) {
         freezeFailure = invalidPlanFinding(`freeze-r${round}`, error);
         findings = [...findings, freezeFailure];
@@ -443,6 +453,11 @@ export async function runPlanningPipeline(options) {
     highestRiskTier = highestOf(assembled.sizing.plan.nodes.map((node) => node.riskTier ?? RISK_TIERS[0]));
     frozen = freezePlan(frozenContractRaw(assembled), {
       outDir: plansDir,
+      phases: assembled.phases,
+      // The pipeline's own pinned spec bytes: a wrong or missing digest is the
+      // first thing the Campaign Brief refuses on, never a summary.
+      spec: { path: relativeSpecPath, digest: specDigest },
+      facts: repoFacts,
       provenance: {
         targetGitHead: repoFacts.gitHead,
         planner: { runtimeId: runtimeDefaults.worker ?? "", model: modelOf(runtimes, runtimeDefaults.worker) },
@@ -490,7 +505,10 @@ export async function runPlanningPipeline(options) {
 
   const approved = approveBelow === "high" ? true : approveBelow === "none" ? false : highestRiskTier !== "high";
   const planPath = join(plansDir, "plan.json");
-  writeJsonAtomic(planPath, { ...frozen, status: "frozen", approved });
+  // The final bytes — status and approval included — are written first; the
+  // sidecar then covers exactly those bytes, and nothing rewrites the plan
+  // afterward. The written record is the plan.json the brief will read.
+  writeFrozenPlan(plansDir, /** @type {import("./freeze.mjs").FrozenPlan} */ (frozen), { status: "frozen", approved });
   if (!approved) {
     await campaignCli([
       "note", campaignId, "--cwd", cwd, "--session-id", PLANNER_SESSION_ID,
@@ -666,124 +684,58 @@ export function droppedWriteFindings(previousPlan, revisedPlan) {
 }
 
 /**
- * Every declared runtime treated as available. Live discovery (probing a
- * harness for real exhaustion) is a separate concern this pipeline does not
- * take on; a campaign that needs it can inject a table row and prune its
- * `runtimes` catalogue instead.
+ * The phase declarations a reviewer saw, remapped onto the nodes sizing
+ * actually produced. `applySizingRules` is the only stage that changes the
+ * node set, and it only ever folds one node into another — a declaration that
+ * named the folded-away node must name the node that absorbed it, or freeze
+ * would refuse the record as an unknown assignment. A two-entry transformation
+ * is a merge (`[child, parent]`); every one-entry transformation edits a node
+ * in place. Resolution follows a chain, so a node folded into another that was
+ * itself folded lands on the final owner, and duplicates collapse so a
+ * declaration never lists the same node twice. A declaration in the legacy
+ * shape (no `nodeIds`) is returned untouched.
  *
- * @param {Record<string, JsonObject>} runtimes
- * @returns {Record<string, {available: true, exhaustedUntil: null}>}
+ * @param {PlanPhase[]|undefined} phases
+ * @param {import("./sizing.mjs").SizingTransformation[]|undefined} transformations
+ * @returns {PlanPhase[]|undefined}
  */
-function availabilityOf(runtimes) {
-  return Object.fromEntries(Object.keys(runtimes).map((id) => [id, { available: true, exhaustedUntil: null }]));
-}
-
-/**
- * @param {Record<string, JsonObject>} runtimes
- * @param {string|undefined} id
- * @returns {string}
- */
-function modelOf(runtimes, id) {
-  const model = id ? runtimes[id]?.model : undefined;
-  return typeof model === "string" ? model : "";
-}
-
-/**
- * @param {string[]} riskTiers
- * @returns {string}
- */
-function highestOf(riskTiers) {
-  return riskTiers.reduce((highest, tier) => (RISK_TIERS.indexOf(tier) > RISK_TIERS.indexOf(highest) ? tier : highest), RISK_TIERS[0]);
-}
-
-/**
- * A draft or revise output node (flat `readFiles`/`writeFiles`/`verification`)
- * turned into the shape `applySizingRules` merges and splits: those fields move
- * under `taskPacket`, alongside `sizing.mjs`'s own `writeFiles`/`verification`
- * expectations, while `objective` rides along as a passthrough field a merge
- * never touches.
- *
- * @param {import("./template.mjs").PlanOutputNode} node
- * @returns {SizedPlanNode}
- */
-function toSizingNode(node) {
-  return /** @type {SizedPlanNode} */ ({
-    id: node.id,
-    dependsOn: node.dependsOn,
-    taskKind: node.taskKind,
-    riskTier: node.riskTier,
-    objective: node.objective,
-    expectedTurns: node.expectedTurns,
-    definitionOfDone: node.definitionOfDone,
-    taskPacket: {
-      readFiles: node.readFiles,
-      writeFiles: node.writeFiles,
-      scopeAcknowledged: node.scopeAcknowledged,
-      verification: node.verification,
-    },
-  });
-}
-
-/**
- * A sized plan node's classification and shape, turned into the contract node
- * `freezePlan` validates. `riskTier: "low"` gets no gate; `standard` an
- * advisory one; `high` a blocking one, which `validateGate` requires `major`
- * in `failOn` for.
- *
- * @param {SizedPlanNode} node
- * @param {string} phase
- * @param {{worker: string|null, judge: string|null}|undefined} assignment
- * @returns {JsonObject}
- */
-function toContractNode(node, phase, assignment) {
-  const riskTier = /** @type {string} */ (node.riskTier);
-  const gate = riskTier === "low"
-    ? false
-    : {
-      review: riskTier === "high" ? "blocking" : "advisory",
-      failOn: riskTier === "high" ? ["major", "critical"] : ["critical"],
-      ...(assignment?.judge ? { runtime: assignment.judge } : {}),
-    };
-  return {
-    id: node.id,
-    type: node.taskKind,
-    phase,
-    dependsOn: node.dependsOn ?? [],
-    ...(assignment?.worker ? { runtime: assignment.worker } : {}),
-    taskPacket: {
-      mode: "execution",
-      objective: node.objective,
-      instructions: [node.objective],
-      readFiles: node.taskPacket.readFiles ?? [],
-      writeFiles: node.taskPacket.writeFiles ?? [],
-      // Carried, never computed here: the drafter decided which importers it
-      // will not change, and scope closure exists to force that decision on a
-      // person rather than answer it for them (src/repo/scope-closure.mjs).
-      scopeAcknowledged: node.taskPacket.scopeAcknowledged ?? [],
-      symbols: [],
-      decisions: [],
-      nonGoals: [],
-      verification: node.taskPacket.verification,
-    },
-    definitionOfDone: node.definitionOfDone ?? [],
-    gate,
+export function carryPhaseDeclarations(phases, transformations) {
+  if (!phases || phases.length === 0) return phases;
+  /** @type {Map<string, string>} */
+  const parentOf = new Map();
+  for (const transformation of transformations ?? []) {
+    const nodes = transformation?.nodes;
+    if (Array.isArray(nodes) && nodes.length === 2 && typeof nodes[0] === "string" && typeof nodes[1] === "string") {
+      parentOf.set(nodes[0], nodes[1]);
+    }
+  }
+  if (parentOf.size === 0) return phases;
+  /** @param {string} id @returns {string} */
+  const resolve = (id) => {
+    let current = id;
+    const seen = new Set();
+    while (parentOf.has(current) && !seen.has(current)) {
+      seen.add(current);
+      current = /** @type {string} */ (parentOf.get(current));
+    }
+    return current;
   };
+  return phases.map((phase) => {
+    if (phase.nodeIds === undefined) return phase;
+    return { ...phase, nodeIds: [...new Set(phase.nodeIds.map(resolve))] };
+  });
 }
 
 /**
- * Lines in a file the plan declares as a read, or null when it cannot be
- * counted (absent, a directory, unreadable). Exploratory sizing is measured
- * against this: what a node must read is what it is paid for.
+ * Write the pipeline's final frozen plan record and the `plan.json.sha256`
+ * sidecar over those exact bytes. This is the last write to plan.json: after
+ * it returns, the sidecar and the plan agree, and neither may be rewritten.
  *
- * @param {string} path
- * @returns {number|null}
+ * @param {string} outDir
+ * @param {import("./freeze.mjs").FrozenPlan} frozen
+ * @param {{status: "frozen", approved: boolean}} outcome
+ * @returns {import("./freeze.mjs").FrozenPlan}
  */
-function fileLineCount(path) {
-  try {
-    const text = readFileSync(path, "utf8");
-    if (text === "") return 0;
-    return text.split("\n").length - (text.endsWith("\n") ? 1 : 0);
-  } catch {
-    return null;
-  }
+export function writeFrozenPlan(outDir, frozen, outcome) {
+  return writeFrozenPlanRecord(outDir, { ...frozen, ...outcome });
 }

package/src/plan/template.mjs

@@ -10,10 +10,12 @@
  * artefact under review, never the author's packet, transcript or summary.
  *
  * The plan output validator also owns requirement traceability: a plan
- * declares, per phase, the requirement ids it satisfies and its one-sentence
- * deliverable, and a phase associated with no requirement is reported as a
- * finding — never a silent pass, never a refusal. freeze.mjs imports the same
- * phase check for the frozen plan record.
+ * declares, per phase, the requirement ids it satisfies, the node ids it
+ * assigns, and its one-sentence deliverable. A planned node belongs to exactly
+ * one declaration, so a missing, duplicate, or unknown node assignment is a
+ * refusal. A legacy declaration that names no requirements and no nodes is
+ * still reported as a finding, never a silent pass. freeze.mjs imports the
+ * same phase check for the frozen plan record.
  */
 import { assertObject, positiveInteger, rejectUnknown, requireId, requireString, requireStringArray } from "../contract/assert.mjs";
 import { CONTRACT_VERSION, PROTOCOL_SCHEMA_VERSION } from "../contract/index.mjs";
@@ -26,7 +28,7 @@ import { validateVerificationCommands } from "../contract/verification.mjs";
 /** @typedef {{campaignId: string, phase: string, n: number, goal?: string, cwd?: string, runtimes: Record<string, JsonObject>, runtimeDefaults: {worker?: string, judge?: string}, specPath?: string, repoFactsPath?: string, cataloguePath?: string, packageMode?: import("./sizing.mjs").PackageMode, planPath?: string, findingsPath?: string, notesPath?: string}} PlanningContractInputs */
 /** @typedef {{id: string, objective: string, taskKind: string, riskTier: RiskTier, dependsOn: string[], readFiles: string[], writeFiles: string[], scopeAcknowledged: string[], definitionOfDone: import("../contract/definition-of-done.mjs").DefinitionOfDoneItem[], verification: import("../contract/verification.mjs").VerificationCommand[], expectedTurns?: number}} PlanOutputNode */
 /** @typedef {{nodes: PlanOutputNode[], phases?: PlanPhase[], findings?: PlanFindingOutput[], justification?: string}} PlanOutput */
-/** @typedef {{id: string, requirementIds: string[], deliverable: string}} PlanPhase */
+/** @typedef {{id: string, requirementIds: string[], nodeIds?: string[], deliverable: string}} PlanPhase */
 /** @typedef {{id: string, severity: "critical"|"major"|"minor", nodeId: string, text: string}} PlanFindingOutput */
 
 /** The taskKind catalogue a draft or revise classifies against. */
@@ -109,7 +111,7 @@ const REQUIRED_INPUTS = Object.freeze({
 // run had already succeeded. The id charset is requireId's
 // (contract/assert.mjs) verbatim, because an id that is present but invalid
 // fails that same validator just as late.
-const PLAN_OUTPUT_SHAPE = '{nodes: [{id, objective, taskKind, riskTier, dependsOn, readFiles, writeFiles, scopeAcknowledged, definitionOfDone: [{id, text, proof?: {kind: "command"|"path"|"verification", ref}, judgment?: true}], verification: [{argv: [string], cwd?, timeoutSec?, repeat?, env?, mutation?: {threshold}}], expectedTurns?}], phases?: [{id, requirementIds?: [string], deliverable}], justification?}; every id in it (node, phase, and definitionOfDone item) must match [A-Za-z0-9._-]+ and never be exactly "." or ".."';
+const PLAN_OUTPUT_SHAPE = '{nodes: [{id, objective, taskKind, riskTier, dependsOn, readFiles, writeFiles, scopeAcknowledged, definitionOfDone: [{id, text, proof?: {kind: "command"|"path"|"verification", ref}, judgment?: true}], verification: [{argv: [string], cwd?, timeoutSec?, repeat?, env?, mutation?: {threshold}}], expectedTurns?}], phases?: [{id, requirementIds: [string], nodeIds: [string], deliverable}], justification?}; every id in it (node, phase, node assignment, and definitionOfDone item) must match [A-Za-z0-9._-]+ and never be exactly "." or ".."';
 /**
  * The size guidance every draft and revise carries. measured 2026-09-20 over
  * stored runs: median 49 provider requests per worker turn; cost per turn
@@ -165,7 +167,7 @@ const OBJECTIVES = Object.freeze({
 const INSTRUCTIONS = Object.freeze({
   draft: [
     `Consult the ${TASK_KIND_CATALOGUE_FILE} in readFiles before classifying any node; taskKind must be one of that catalogue and riskTier must be one of ${RISK_TIERS.join(", ")}.`,
-    "Declare every phase the plan serves in output.plan.phases: the requirement ids (R<n> from the spec) the phase satisfies and the deliverable it produces in one sentence. A phase associated with no requirement is reported as a finding, not refused.",
+    "Declare every phase the plan serves in output.plan.phases: the requirement ids (R<n> from the spec) the phase satisfies, the planned node ids it assigns, and the deliverable it produces in one sentence. Every planned node must appear in exactly one phase's nodeIds; a missing, duplicate, or unknown node assignment is refused.",
     ...SCOPE_CLOSURE_RULE,
     `Return exactly one worker-result JSON object. Put the plan in output.plan as ${PLAN_OUTPUT_SHAPE} and nothing else in output.`,
     "Never name a runtime, harness, model, or vendor anywhere in output.plan. taskKind and riskTier are the only classification a draft makes; a routing table assigns a runtime afterward, from those two fields alone.",
@@ -173,7 +175,7 @@ const INSTRUCTIONS = Object.freeze({
   ],
   revise: [
     "Read the findings and resolve every one; do not leave a critical or major finding unaddressed.",
-    "Declare every phase the plan serves in output.plan.phases: the requirement ids (R<n> from the spec) the phase satisfies and the deliverable it produces in one sentence. A phase associated with no requirement is reported as a finding, not refused.",
+    "Declare every phase the plan serves in output.plan.phases: the requirement ids (R<n> from the spec) the phase satisfies, the planned node ids it assigns, and the deliverable it produces in one sentence. Every planned node must appear in exactly one phase's nodeIds; a missing, duplicate, or unknown node assignment is refused.",
     ...SCOPE_CLOSURE_RULE,
     `Return exactly one worker-result JSON object. Put the revised plan in output.plan as ${PLAN_OUTPUT_SHAPE} and nothing else in output.`,
     "Never name a runtime, harness, model, or vendor anywhere in output.plan.",
@@ -344,7 +346,7 @@ export function validatePlanOutput(plan) {
     });
   });
   if (record.justification !== undefined) requireString(record.justification, "plan.justification");
-  const phases = validatePlanPhases(record.phases);
+  const phases = validatePlanPhases(record.phases, nodes.map((node) => node.id));
   const findings = (phases ?? [])
     .filter((phase) => phase.requirementIds.length === 0)
     .map((phase) => /** @type {PlanFindingOutput} */ ({
@@ -364,41 +366,102 @@ export function validatePlanOutput(plan) {
   };
 }
 
-// The fields a phase declaration carries beyond its id: requirementIds|deliverable —
-// which spec requirements the phase satisfies, and the one sentence naming its result.
-const PLAN_PHASE_FIELDS = new Set(["id", "requirementIds", "deliverable"]);
+// The fields a phase declaration carries beyond its id: requirementIds|nodeIds|deliverable —
+// which spec requirements the phase satisfies, which planned nodes it assigns, and the one
+// sentence naming its result.
+const PLAN_PHASE_FIELDS = new Set(["id", "requirementIds", "nodeIds", "deliverable"]);
 
 /**
- * Validate a plan's `phases` — the per-phase requirement declarations: the
- * requirement ids (R<n> from the spec) each phase satisfies and the
- * deliverable it produces in one sentence. Absent, empty, and requirement-less
- * are legal here: a support phase with no requirement is the caller's finding
- * to report (validatePlanOutput does), so the gap stays visible without a
- * malformed-but-honest plan being refused. Shared with freeze.mjs, which holds
- * the same declarations on the frozen plan record.
+ * Validate a plan's `phases` — the per-phase requirement declarations. The
+ * current shape `{id, requirementIds, nodeIds, deliverable}` assigns every
+ * planned node to exactly one declaration: `plannedNodeIds` is the plan's own
+ * node-id list, and a node no declaration names, a node two declarations both
+ * name, or a declared node absent from the plan is refused. A declaration in
+ * the older `{id, requirementIds, deliverable}` shape (no `nodeIds` at all)
+ * stays legal so a plan frozen before node assignment existed still reads; in
+ * that shape an empty `requirementIds` is the caller's finding to report
+ * (validatePlanOutput does), not a refusal. Mixing the two shapes is refused
+ * because it would leave some nodes silently unattributed. Shared with
+ * freeze.mjs, which holds the same declarations on the frozen plan record.
  *
  * @param {unknown} phases
+ * @param {string[]|undefined} [plannedNodeIds] the plan's node ids, when the caller has them
  * @returns {PlanPhase[]|undefined} the normalized declarations, or undefined when none were given
  */
-export function validatePlanPhases(phases) {
+export function validatePlanPhases(phases, plannedNodeIds) {
   if (phases === undefined) return undefined;
   if (!Array.isArray(phases)) throw new TypeError("plan.phases must be an array of phase declarations");
   if (phases.length === 0) return undefined;
-  return phases.map((phase, index) => {
+
+  /** @type {Set<string>} */
+  const ids = new Set();
+  const declarations = phases.map((phase, index) => {
     const label = `plan.phases[${index}]`;
     assertObject(phase, label);
     const record = /** @type {Record<string, unknown>} */ (phase);
     rejectUnknown(record, PLAN_PHASE_FIELDS, label);
     requireId(record.id, `${label}.id`);
+    const id = /** @type {string} */ (record.id);
+    if (ids.has(id)) throw new TypeError(`plan.phases has duplicate phase id ${id}`);
+    ids.add(id);
     requireString(record.deliverable, `${label}.deliverable`);
-    const requirementIds = record.requirementIds ?? [];
+    const requirementIds = /** @type {string[]} */ (record.requirementIds ?? []);
     requireStringArray(requirementIds, `${label}.requirementIds`);
-    return {
-      id: /** @type {string} */ (record.id),
+    /** @type {string[]|undefined} */
+    let nodeIds;
+    if (record.nodeIds !== undefined) {
+      requireStringArray(record.nodeIds, `${label}.nodeIds`);
+      nodeIds = /** @type {string[]} */ (record.nodeIds);
+      if (nodeIds.length === 0) throw new TypeError(`${label}.nodeIds must name at least one planned node`);
+      if (requirementIds.length === 0) throw new TypeError(`${label}.requirementIds must name at least one requirement when the declaration assigns nodes`);
+    }
+    return /** @type {PlanPhase} */ ({
+      id,
       requirementIds: /** @type {string[]} */ (requirementIds),
+      ...(nodeIds === undefined ? {} : { nodeIds }),
       deliverable: /** @type {string} */ (record.deliverable),
-    };
+    });
   });
+
+  const assigned = declarations.filter((declaration) => declaration.nodeIds !== undefined);
+  if (assigned.length > 0 && assigned.length !== declarations.length) {
+    throw new TypeError("plan.phases must assign nodeIds on every declaration or on none: mixing the two leaves the nodes named by the other declarations unattributed");
+  }
+  if (assigned.length > 0 && plannedNodeIds !== undefined) {
+    validateNodeAssignments(assigned, plannedNodeIds);
+  }
+  return declarations;
+}
+
+/**
+ * Refuse a node assignment that does not cover the plan exactly once. Called
+ * only for the nodeIds shape, where every declaration already names at least
+ * one node and at least one requirement.
+ *
+ * @param {PlanPhase[]} declarations
+ * @param {string[]} plannedNodeIds
+ * @returns {void}
+ */
+function validateNodeAssignments(declarations, plannedNodeIds) {
+  const planned = new Set(plannedNodeIds);
+  /** @type {Map<string, string>} */
+  const owner = new Map();
+  for (const declaration of declarations) {
+    for (const nodeId of declaration.nodeIds ?? []) {
+      if (!planned.has(nodeId)) {
+        throw new TypeError(`plan.phases: phase ${declaration.id} assigns unknown node ${nodeId}, which is not one of the plan's nodes`);
+      }
+      const previous = owner.get(nodeId);
+      if (previous !== undefined) {
+        throw new TypeError(`plan.phases assigns node ${nodeId} to both ${previous} and ${declaration.id}; every planned node belongs to exactly one phase`);
+      }
+      owner.set(nodeId, declaration.id);
+    }
+  }
+  const missing = [...planned].filter((nodeId) => !owner.has(nodeId));
+  if (missing.length > 0) {
+    throw new TypeError(`plan.phases leaves planned node(s) assigned to no phase: ${missing.join(", ")}`);
+  }
 }
 
 const FINDING_FIELDS = new Set(["id", "severity", "nodeId", "text"]);

package/src/repo/declared-paths.mjs

@@ -17,6 +17,7 @@ import { join, resolve } from "node:path";
 import { lstatSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { RUNS_DIR_NAME } from "../run/paths.mjs";
+import { isIgnoreSource } from "./workspace.mjs";
 
 /** @typedef {import("../contract/index.mjs").ValidatedNode} ValidatedNode */
 
@@ -49,6 +50,21 @@ export function unsnapshottedWriteWarnings(node, index, cwd) {
     `nodes[${index}] (${node.id}): ${path.includes("/") ? `${kind} under ${root}/` : `${kind} ${path}`} are outside the workspace snapshot, so the closed-scope gate cannot observe them`,
   );
 }
+/**
+ * `writes_ignore_source`: a declared write the workspace snapshot fingerprints
+ * as an ignore source. The node fails with `snapshot_ignore_changed` the
+ * moment the worker changes it, and two campaigns each lost a node learning
+ * that (RM-051), so the author hears it before dispatch.
+ *
+ * @param {ValidatedNode} node
+ * @param {number} index
+ * @returns {string[]}
+ */
+export function ignoreSourceWriteWarnings(node, index) {
+  const sources = (node.taskPacket.writeFiles ?? []).filter(isIgnoreSource);
+  if (!sources.length) return [];
+  return [`nodes[${index}] (${node.id}): writes_ignore_source: writeFiles ${sources.join(", ")} ${sources.length === 1 ? "is an ignore source" : "are ignore sources"} the workspace snapshot fingerprints; a worker that changes one fails the node with snapshot_ignore_changed, so make that edit outside the run`];
+}
 /**
  * @param {string|undefined} cwd
  * @param {string} declaredPath

package/src/repo/workspace.mjs

@@ -53,7 +53,7 @@ export function captureWorkspaceSnapshot(cwd, expectedIgnoreSources) {
   const root = realpathSync(cwd);
   const ignoreSources = captureIgnoreSources(root);
   if (expectedIgnoreSources !== undefined && !sameSnapshotEntries(expectedIgnoreSources, ignoreSources)) {
-    throw fail("snapshot_ignore_changed", "workspace ignore sources changed during worker execution");
+    throw ignoreSourcesChanged(expectedIgnoreSources, ignoreSources);
   }
   /** @type {SnapshotEntry[]} */
   const entries = [];
@@ -123,7 +123,7 @@ export function compareWorkspaceSnapshot(before, cwd, scope = {}) {
     });
   const after = captureWorkspaceSnapshot(cwd, before.ignoreSources);
   if (!sameSnapshotEntries(before.ignoreSources, after.ignoreSources)) {
-    throw fail("snapshot_ignore_changed", "workspace ignore sources changed during worker execution");
+    throw ignoreSourcesChanged(before.ignoreSources, after.ignoreSources);
   }
   const prior = new Map(before.entries.map((/** @type {SnapshotEntry} */ entry) => [entry.path, JSON.stringify(entry)]));
   const current = new Map(after.entries.map((/** @type {SnapshotEntry} */ entry) => [entry.path, JSON.stringify(entry)]));
@@ -262,6 +262,45 @@ export function validateWorkspaceScopeBoundary(cwd, boundary, declared = {}) {
     rootOrigins,
   };
 }
+/** Directories `captureIgnoreSources` skips at any depth. */
+const SKIPPED_SOURCE_DIRS = new Set([".git", RUNS_DIR_NAME, "node_modules", ".venv", "venv"]);
+
+/** The ignore sources `captureIgnoreSources` always fingerprints at the root. */
+const ROOT_IGNORE_SOURCES = [".faberunignore", ".gitignore", ".git/config"];
+
+/**
+ * Whether a workspace-relative path is one `captureIgnoreSources` fingerprints,
+ * so a worker that changes it fails its node with `snapshot_ignore_changed`.
+ * A `.gitignore` counts at any depth outside the directories the walk skips.
+ *
+ * @param {string} path
+ * @returns {boolean}
+ */
+export function isIgnoreSource(path) {
+  const normalized = path.replaceAll("\\", "/").replace(/^\.\//u, "");
+  if (ROOT_IGNORE_SOURCES.includes(normalized) || normalized === ".git/info/exclude" || normalized === ".git") return true;
+  const segments = normalized.split("/");
+  // The same directories `captureIgnoreSources` never walks.
+  if (segments.some((segment) => SKIPPED_SOURCE_DIRS.has(segment)) || [".claude", ".codex"].includes(segments[0])) return false;
+  return basename(normalized) === ".gitignore";
+}
+
+/**
+ * The `snapshot_ignore_changed` failure, naming every source that moved.
+ * Measured on `rec-audit-remediation`: the message named none, and the
+ * operator had to diff the worktree to learn it was one `.gitignore` line.
+ *
+ * @param {SnapshotEntry[]} before
+ * @param {SnapshotEntry[]} after
+ * @returns {Error}
+ */
+function ignoreSourcesChanged(before, after) {
+  const prior = new Map(before.map((entry) => [entry.path, JSON.stringify(entry)]));
+  const current = new Map(after.map((entry) => [entry.path, JSON.stringify(entry)]));
+  const changed = [...new Set([...prior.keys(), ...current.keys()])].filter((path) => prior.get(path) !== current.get(path)).sort();
+  return fail("snapshot_ignore_changed", `workspace ignore sources changed during worker execution: ${changed.join(", ")}`);
+}
+
 /**
  * Snapshot the files Git can use to hide workspace changes. These entries are
  * kept separate from the relevant-file entry cap. A worker cannot replace
@@ -273,7 +312,7 @@ export function validateWorkspaceScopeBoundary(cwd, boundary, declared = {}) {
  */
 function captureIgnoreSources(root) {
   /** @type {Set<string>} */
-  const paths = new Set([".faberunignore", ".gitignore", ".git/config"]);
+  const paths = new Set(ROOT_IGNORE_SOURCES);
   /** @type {Map<string, string>} */
   const gitPaths = new Map();
   /** @param {string} name @param {string} logical @returns {string|null} */

package/src/repo/worktree.mjs

@@ -322,10 +322,27 @@ function gitTracks(repo, read) {
 }
 
 /**
- * @param {{repo: string, path: string, baseSha: string|null, runId: string, nodeId: string, attempt: number}} args
+ * Every untracked, unignored path in a worktree, outside the runner's own
+ * `.runs` tree and the linked `node_modules`: the same exclusions the seal
+ * applies, so the two agree on what "left in the worktree" means.
+ *
+ * @param {string} path
+ * @returns {string[]}
+ */
+export function untrackedPaths(path) {
+  const listed = git(path, ["status", "--porcelain=v1", "-z", "--untracked-files=all", "--", ".", `:(exclude)${RUNS_DIR_NAME}`, ":(exclude)node_modules"]);
+  return listed.split("\0").filter((entry) => entry.startsWith("?? ")).map((entry) => entry.slice(3)).sort();
+}
+
+/**
+ * `exclude` names paths the attempt holds but must not seal: what the
+ * controller's own verification left behind (`verificationArtifacts`). They
+ * stay on disk and out of the commit.
+ *
+ * @param {{repo: string, path: string, baseSha: string|null, runId: string, nodeId: string, attempt: number, exclude?: string[]}} args
  * @returns {SealedAttempt}
  */
-export function sealAttempt({ repo, path, baseSha, runId, nodeId, attempt }) {
+export function sealAttempt({ repo, path, baseSha, runId, nodeId, attempt, exclude = [] }) {
   // The attempt-local `.runs` result sidecar must never enter the attempt
   // commit. Naming it through an exclude pathspec makes `git add` exit 1 with
   // advice.addIgnoredFile as soon as the sidecar exists in a repository that
@@ -345,6 +362,11 @@ export function sealAttempt({ repo, path, baseSha, runId, nodeId, attempt }) {
     // node_modules is linked into the worktree as a symlink, which `node_modules/`
     // in .gitignore does not match; never let the link into the attempt commit.
     runGit(["-C", path, "rm", "-r", "-q", "--cached", "--ignore-unmatch", "--", RUNS_DIR_NAME, "node_modules"]);
+    if (exclude.length) runGit(["-C", path, "rm", "-q", "--cached", "--ignore-unmatch", "--", ...exclude.map((item) => `:(literal)${item}`)]);
+  }
+  // A worktree whose only change was an excluded artifact stages nothing, and
+  // an empty commit exits 1; the attempt's head is then its seal.
+  if (dirty && !stagedNothing(path)) {
     runGit([
       "-C", path,
       "-c", "user.email=runner@example.test",
@@ -371,6 +393,16 @@ export function sealAttempt({ repo, path, baseSha, runId, nodeId, attempt }) {
   return { sha, empty };
 }
 
+/** @param {string} path @returns {boolean} */
+function stagedNothing(path) {
+  try {
+    runGit(["-C", path, "diff", "--cached", "--quiet"]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 /** @param {string} repo @param {string} base @param {string} head @returns {boolean} */
 export function gitDiffEmpty(repo, base, head) {
   try {