faberun 0.19.1 → 0.19.2

package/src/engine/dispatch.mjs

@@ -25,6 +25,7 @@ import { attemptWorkspace, createAttemptWorktree, sealAttempt } from "../repo/wo
 import { attemptWorktreePath } from "../run/paths.mjs";
 import { basename, dirname, join } from "node:path";
 import { errorCode, errorMessage } from "../util.mjs";
+import { gateProofTimeoutMs } from "../contract/final-verification.mjs";
 import { captureWorkspaceScope, captureWorkspaceSnapshot } from "../repo/workspace.mjs";
 import { deterministicGate, judgeReaskReason, judgeRequired, judgeSkippedByScope } from "./judge-gate.mjs";
 import { emptyScope, persistedScopeBoundary, workerScope } from "./scope.mjs";
@@ -459,7 +460,7 @@ export async function startJudge(contract, node, state, runDir, running, workerR
     node,
     workspace,
     reask,
-    Math.max(1_000, Math.min((node.timeoutSec ?? contract.timeoutSec ?? 60) * 1000, 120_000)),
+    gateProofTimeoutMs(node, contract),
     /** @type {import("../contract/index.mjs").VerificationState|null} */ (state.verification),
   );
   state.review = reviewMode(node.gate);

package/src/engine/process.mjs

@@ -36,7 +36,7 @@ import { killTarget } from "../host/platform.mjs";
 /** @typedef {{prompt: string|null, stdout: string, stderr: string}} PathSet */
 /** @typedef {{id: string, pid: number, processGroupId: number|null, processStartToken: string|null, harness: string, runtimeId: string|null, runtimeFingerprint?: string, revision?: number, phase: string, promptPath: string|null, stdoutPath: string, stderrPath: string, startedAt: string, deadlineAt: string|null, updatedAt: string, closedAt: string|null, exitCode: number|null, signal: string|null, status: "active"|"closed"|"terminated", executable: string, snapshotPath?: string, usage?: Usage, usageEstimated?: boolean, costUsd?: number|null, costProvenance?: "priced", runId?: string, campaignId?: string, nodeId?: string, attempt?: number, workspace?: string, worktreeBranch?: string|null, worktreeBaseSha?: string|null, planPhase?: string, role?: "worker"|"judge", model?: string, reasoning?: string|null, sandbox?: string|null, continuationId?: string|null, continuationMode?: "fresh"|"reuse"|"rotate", session?: import("../harnesses/session-metrics.mjs").SessionLedger|null}} Invocation */
 /** @typedef {{pid: number|null, processGroupId?: number|null, processStartToken?: string|null}} InvocationProbe */
-/** @typedef {{child: ChildProcess, contract: ValidatedContract, node: ValidatedNode, state: NodeSnapshot, runtime: HarnessRuntime & {id: string|null}, cwd: string, paths: PathSet, phase: string, invocation: Invocation, startedAt: string, startedTicks: bigint, progressTicks: bigint, lastOutputAt: number, closed: boolean, exitCode: number|null, signal: string|null, spawnError: Error|null, terminating: Promise<void>|null, gateConfigPath: string, gateReleasePath: string, scopeBaseline?: unknown, scopeChecked?: boolean, scopeViolation?: boolean, resultMaterialization?: boolean, recoveryBaseline?: unknown, observeTimer?: ReturnType<typeof setInterval>, monitorOffset?: number, monitorParser?: import("../harnesses/session-metrics.mjs").SessionMetricsParser, lastEventCount?: number, lastMonitorOffset?: number, observedOnce?: boolean, onClose?: (invocation: Invocation) => void, onInvocationUpdate?: (invocation: Invocation) => void, onProgress?: (state: NodeSnapshot) => void}} Job */
+/** @typedef {{child: ChildProcess, contract: ValidatedContract, node: ValidatedNode, state: NodeSnapshot, runtime: HarnessRuntime & {id: string|null}, cwd: string, paths: PathSet, phase: string, invocation: Invocation, startedAt: string, startedTicks: bigint, progressTicks: bigint, lastOutputAt: number, closed: boolean, exitCode: number|null, signal: string|null, spawnError: Error|null, terminating: Promise<void>|null, gateConfigPath: string, gateReleasePath: string, scopeBaseline?: unknown, scopeChecked?: boolean, scopeViolation?: boolean, resultMaterialization?: boolean, recoveryBaseline?: unknown, observeTimer?: ReturnType<typeof setInterval>, monitorOffset?: number, monitorParser?: import("../harnesses/session-metrics.mjs").SessionMetricsParser, lastEventCount?: number, lastMonitorOffset?: number, observedOnce?: boolean, turnCapWarned?: boolean, onClose?: (invocation: Invocation) => void, onInvocationUpdate?: (invocation: Invocation) => void, onProgress?: (state: NodeSnapshot) => void}} Job */
 /** @typedef {{graceMs?: number, killGraceMs?: number, escalate?: boolean, runDir?: string, kill?: (pid: number, signal: string|number) => unknown, child?: ChildProcess|null}} TerminateOptions */
 
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -278,6 +278,14 @@ export async function terminateInvocation(invocation, options = {}) {
  */
 const SEAL_BEFORE_KILL_CODES = new Set(["wall_clock_timeout", "stall_timeout", "turn_limit"]);
 
+/**
+ * How far into its request ceiling an attempt gets before it says so. Four
+ * fifths: late enough that an ordinary attempt never mentions it (measured
+ * 2026-09-20 over 200 completed claude worker turns, p90 was 83 of a 150
+ * default), early enough that the remaining fifth is still room to act in.
+ */
+const TURN_CAP_WARN_FRACTION = 0.8;
+
 /**
  * How long a `SIGSTOP`ped process group is given to actually stop before the
  * seal begins. The stop is asynchronous; this bounded settle keeps the seal
@@ -468,6 +476,18 @@ export async function detectStalls(contract, running, onTimeout, onProgress, onB
       // (`turns` counts provider requests for claude, dsh and agy; codex
       // reports whole turns, so its cap is in effect a turn count.)
       const turnCap = job.node?.maxTurns ?? contract.maxTurns;
+      // The ceiling used to arrive only as the kill. `maxTurns` appeared once
+      // in the whole documentation set and not at all in the contract
+      // reference, so the author of a long-running contract raised
+      // `timeoutSec` and `stallTimeoutSec` -- everything they knew existed --
+      // and left this at its default; two Opus attempts at maximum effort
+      // were then cut mid-turn with `turn_limit`, after the cost was already
+      // paid. Said once per attempt as the ceiling comes into view, it is a
+      // decision the operator can still make.
+      if (typeof turnCap === "number" && job.turnCapWarned !== true && monitored.turns >= Math.floor(turnCap * TURN_CAP_WARN_FRACTION)) {
+        job.turnCapWarned = true;
+        process.stdout.write(`[node] ${nodeId} ${job.phase} · ${monitored.turns} of the attempt's maxTurns of ${turnCap} provider requests · raise maxTurns to give it more\n`);
+      }
       if (typeof turnCap === "number" && monitored.turns >= turnCap) {
         const limit = {
           code: "turn_limit",

package/src/engine/scheduler.mjs

@@ -42,7 +42,7 @@ import { operationNextState, providerReceipts, settleInvocation } from "../run/o
 import { appendUsageRecord, invocationCost, invocationUsage, recordInvocationUsage } from "../run/usage.mjs";
 import { captureNodeScopeBoundaries, checkWorkerScope, emptyScope } from "./scope.mjs";
 import { validateContractForLaunch } from "../campaign/chain.mjs";
-import { finalVerificationCommands, sharedVerificationCommands } from "../contract/final-verification.mjs";
+import { finalVerificationCommands, gateProofTimeoutMs, sharedVerificationCommands } from "../contract/final-verification.mjs";
 import { startJudge, startWorker } from "./dispatch.mjs";
 import { assertEnvironmentReady, captureRunIdentity, createRunMetadata, serializableContract, statesFingerprint } from "./run-identity.mjs";
 import { blockDependents, runtimeAssignments } from "./assignment.mjs";
@@ -118,7 +118,7 @@ export function nodeBudgetBasisMs(contract, node) {
   // finalVerification set with each.
   const attemptMs = packetMs + sharedMs;
   const candidateMs = attemptMs + finalMs;
-  const gateTimeoutMs = Math.max(1_000, Math.min(defaultTimeoutMs, 120_000));
+  const gateTimeoutMs = gateProofTimeoutMs(node, contract);
   const commandProofs = (node.definitionOfDone ?? []).filter((item) => item.proof?.kind === "command").length;
   return defaultTimeoutMs + attemptMs + candidateMs + commandProofs * gateTimeoutMs + finalMs;
 }

package/src/plan/pipeline.mjs

@@ -82,7 +82,7 @@ export const DEFAULT_NODE_BUDGET_MS = 600_000;
 const APPROVE_BELOW_VALUES = new Set(["standard", "high", "none"]);
 
 /**
- * @param {{specPath: string, campaignId: string, phase: string, cwd?: string, reviewRounds?: number, approveBelow?: ApproveBelow, runtimeDefaults?: {worker?: string, judge?: string}, runtimes: Record<string, JsonObject>, verification?: VerificationSuites, launch: LaunchFn, wait: WaitFn, ask?: AskFn}} options
+ * @param {{specPath: string, campaignId: string, phase: string, cwd?: string, reviewRounds?: number, approveBelow?: ApproveBelow, runtimeDefaults?: {worker?: string, judge?: string}, runtimes: Record<string, JsonObject>, verification?: VerificationSuites, packageMode?: import("./sizing.mjs").PackageMode, launch: LaunchFn, wait: WaitFn, ask?: AskFn}} options
  * @returns {Promise<FrozenPipelineResult|ContestedPipelineResult>}
  */
 export async function runPlanningPipeline(options) {
@@ -91,6 +91,11 @@ export async function runPlanningPipeline(options) {
     reviewRounds = 2, runtimeDefaults = {}, verification = {},
   } = options;
   const ask = options.ask ?? askPlanningRuntimes;
+  // Implementation work is sized by what it writes; exploratory work -- an
+  // audit, a review, a survey -- by what it reads, because it writes one
+  // findings file whatever surface it covers.
+  const packageMode = /** @type {import("./sizing.mjs").PackageMode} */ (options.packageMode ?? "implementation");
+  if (packageMode !== "implementation" && packageMode !== "exploratory") throw new TypeError(`packageMode must be implementation or exploratory: ${String(packageMode)}`);
   const approveBelow = /** @type {ApproveBelow} */ (options.approveBelow ?? "standard");
   if (!APPROVE_BELOW_VALUES.has(approveBelow)) throw new TypeError(`approveBelow must be one of ${[...APPROVE_BELOW_VALUES].join(", ")}`);
   if (typeof launch !== "function") throw new TypeError("runPlanningPipeline requires a launch seam");
@@ -183,7 +188,7 @@ export async function runPlanningPipeline(options) {
     return { contract: validated, output };
   };
 
-  const draft = await runStage("draft", { specPath: relativeSpecPath, repoFactsPath: relativeRepoFactsPath, cataloguePath: relativeCataloguePath });
+  const draft = await runStage("draft", { specPath: relativeSpecPath, repoFactsPath: relativeRepoFactsPath, cataloguePath: relativeCataloguePath, packageMode });
   /** @type {PlanOutput|null} */
   let plan = null;
   // Everything still open against the plan in hand, accumulated across rounds
@@ -253,7 +258,7 @@ export async function runPlanningPipeline(options) {
     stage = "sizing";
     const sizing = applySizingRules(
       { nodes: currentPlan.nodes.map(toSizingNode), justification: currentPlan.justification },
-      { nodeBudgetMs: DEFAULT_NODE_BUDGET_MS, facts: repoFacts, minWriteFiles: MIN_WRITE_FILES, turnCeiling: DEFAULT_MAX_TURNS },
+      { nodeBudgetMs: DEFAULT_NODE_BUDGET_MS, facts: repoFacts, minWriteFiles: MIN_WRITE_FILES, turnCeiling: DEFAULT_MAX_TURNS, packageMode, readVolume: (path) => fileLineCount(join(cwd, path)) },
     );
     stage = "routing";
     const routing = resolveRuntimes(sizing.plan.nodes, {
@@ -371,7 +376,7 @@ export async function runPlanningPipeline(options) {
     const findingsPath = join(scratchDir, `findings-round-${round}.json`);
     writeJsonAtomic(findingsPath, findings);
     const revise = await runStage("revise", {
-      specPath: relativeSpecPath, repoFactsPath: relativeRepoFactsPath, cataloguePath: relativeCataloguePath, findingsPath: relative(cwd, findingsPath),
+      specPath: relativeSpecPath, repoFactsPath: relativeRepoFactsPath, cataloguePath: relativeCataloguePath, findingsPath: relative(cwd, findingsPath), packageMode,
     });
     // Kept for the write-drop comparison: the plan the revise revised, against
     // the plan it produced.
@@ -760,3 +765,21 @@ function toContractNode(node, phase, assignment) {
     gate,
   };
 }
+
+/**
+ * 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.
+ *
+ * @param {string} path
+ * @returns {number|null}
+ */
+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;
+  }
+}

package/src/plan/proof-run.mjs

@@ -0,0 +1,121 @@
+/**
+ * Running a spec's declared commands against the repository as it stands:
+ * the `measure` a planning fact is collected from, and the `proof` a
+ * requirement claims. One spawn shape serves both, because they are the same
+ * act — read the repository by running what the author wrote — and only the
+ * caller's question differs.
+ *
+ * It lives apart from `repo-facts.mjs` for one measurable reason: `spec
+ * validate` invokes no model, and the suite proves it by walking
+ * `plan/spec.mjs`'s runtime import graph and refusing any reach into
+ * `engine/` or `harnesses/`. `repo-facts.mjs` reaches `host/preflight.mjs`
+ * for its verification timings, and that reaches every harness adapter. This
+ * module imports node builtins and two environment variable names, so the
+ * validator can run a proof without the graph growing a harness.
+ */
+import { Buffer } from "node:buffer";
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { NOTIFY_BIN_ENV } from "../notify/index.mjs";
+import { NOTIFY_SESSION_ENV } from "../notify/session.mjs";
+
+/** @typedef {import("./spec.mjs").SpecRequirement} SpecRequirement */
+/** @typedef {{now?: () => number, run?: typeof import("node:child_process").spawnSync, pathExists?: (target: string) => boolean}} MeasureProbes */
+/** @typedef {{requirementId: string|null, kind: "command"|"path", ref: string, pass: boolean, detail: string}} RequirementProofResult */
+
+export const MEASURE_TIMEOUT_MS = 30_000;
+export const MEASURE_OUTPUT_CAP_BYTES = 4096;
+
+/** How much of a failing proof's own output a finding carries: enough to name the failure, never the whole log. */
+const PROOF_DETAIL_CAP = 200;
+
+/**
+ * The same named few `timeVerificationCommands` subtracts before spawning a
+ * measurement (SIDE_EFFECT_ENV_KEYS in src/host/preflight.mjs, which is
+ * module-private and could not be edited by the node that added this): a
+ * measure must not notify a human and must not be redirectable at a live,
+ * paid harness binary. A subtraction of a named few, not an allowlist — PATH,
+ * HOME and every ordinary variable still pass through unchanged.
+ */
+export const MEASURE_SIDE_EFFECT_ENV_KEYS = [
+  NOTIFY_BIN_ENV,
+  NOTIFY_SESSION_ENV,
+  "FABERUN_CODEX_BIN",
+  "FABERUN_CLAUDE_BIN",
+  "FABERUN_AGY_BIN",
+  "FABERUN_DSH_BIN",
+  "FABERUN_ZCODE_BIN",
+  "FABERUN_EXEC_JSONL_BIN",
+];
+
+/**
+ * The shell-capture core every declared command goes through: stripped
+ * side-effect environment, an injectable `run` for tests, a hard timeout, and
+ * output capped and reported as truncated rather than silently cut.
+ *
+ * The command goes through the shell (`spawnSync` with `shell: true`), so a
+ * spec author's own pipe — `| wc -l`, `| grep -v …` — works exactly as typed
+ * at a terminal. A non-zero exit is returned, never thrown: whether that is a
+ * fact or a failure is the caller's question, not this function's.
+ *
+ * @param {string} cwd
+ * @param {string} command
+ * @param {MeasureProbes} [probes]
+ * @returns {{output: string, exitCode: number|null, truncated: boolean}}
+ */
+export function runShellCapture(cwd, command, probes = {}) {
+  const run = probes.run ?? spawnSync;
+  const env = { ...process.env };
+  for (const key of MEASURE_SIDE_EFFECT_ENV_KEYS) delete env[key];
+  const result = run(command, { shell: true, cwd, timeout: MEASURE_TIMEOUT_MS, encoding: "utf8", env });
+  const combined = `${result.stdout ?? ""}${result.stderr ?? ""}`;
+  const bytes = Buffer.from(combined, "utf8");
+  const truncated = bytes.length > MEASURE_OUTPUT_CAP_BYTES;
+  return {
+    output: truncated ? bytes.subarray(0, MEASURE_OUTPUT_CAP_BYTES).toString("utf8") : combined,
+    exitCode: result.status,
+    truncated,
+  };
+}
+
+/**
+ * Run every requirement's declared `proof` against the repository as it
+ * stands right now. `spec validate`'s traceability rule only checks that
+ * `requirement.proof` is present, never that it passes, so a proof anchored
+ * to a form the artifact no longer has still reads as covered. Measured
+ * 2026-09-22: two requirements of one campaign's spec named a proof neither
+ * could satisfy and `--strict-traceability` said nothing about either,
+ * because it never ran them.
+ *
+ * A `judgment` proof cannot run without a model and is left unattempted —
+ * absent from the results rather than reported as passing — the same
+ * restraint `measureRequirements` already applies to its own unwired kinds.
+ *
+ * @param {string} cwd
+ * @param {SpecRequirement[]} requirements
+ * @param {MeasureProbes} [probes]
+ * @returns {RequirementProofResult[]}
+ */
+export function proveRequirements(cwd, requirements, probes = {}) {
+  /** @type {RequirementProofResult[]} */
+  const results = [];
+  for (const requirement of requirements) {
+    const proof = requirement.proof;
+    if (!proof?.ref) continue;
+    if (proof.kind === "command") {
+      const { output, exitCode } = runShellCapture(cwd, proof.ref, probes);
+      const detail = exitCode === 0
+        ? "exit 0"
+        : `exit ${exitCode ?? "no exit code (killed or never started)"}${output.trim() ? `: ${output.trim().slice(0, PROOF_DETAIL_CAP)}` : ""}`;
+      results.push({ requirementId: requirement.id, kind: "command", ref: proof.ref, pass: exitCode === 0, detail });
+      continue;
+    }
+    if (proof.kind === "path") {
+      const target = isAbsolute(proof.ref) ? proof.ref : join(cwd, proof.ref);
+      const exists = probes.pathExists ? probes.pathExists(target) : existsSync(target);
+      results.push({ requirementId: requirement.id, kind: "path", ref: proof.ref, pass: exists, detail: exists ? "exists" : "no such path" });
+    }
+  }
+  return results;
+}

package/src/plan/repo-facts.mjs

@@ -14,46 +14,23 @@
  * injected measurer's own numbers) is what makes two calls at the same HEAD
  * byte-identical.
  */
-import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { timeVerificationCommands } from "../host/preflight.mjs";
-import { NOTIFY_BIN_ENV } from "../notify/index.mjs";
-import { NOTIFY_SESSION_ENV } from "../notify/session.mjs";
 import { boundedGitSync, gitHead } from "../repo/worktree.mjs";
+import { runShellCapture } from "./proof-run.mjs";
 
 /** @typedef {import("./spec.mjs").SpecRequirement} SpecRequirement */
+/** @typedef {import("./proof-run.mjs").MeasureProbes} MeasureProbes */
 /** @typedef {{requirementId: string|null, command: string, output: string, exitCode: number|null, truncated: boolean}} RequirementMeasurement */
 /** @typedef {{argv: string[], measuredMs: number, eligible: boolean}} VerificationCandidate */
 /** @typedef {{path: string, covers: string|null}} TestFileEntry */
 /** @typedef {{formatVersion: number, gitHead: string|null, paths: string[], truncated: boolean, scripts: Record<string, string>, verificationCandidates: VerificationCandidate[], testFiles: TestFileEntry[], requirementMeasurements: RequirementMeasurement[]}} RepoFacts */
-/** @typedef {{now?: () => number, run?: typeof import("node:child_process").spawnSync}} MeasureProbes */
 
 const FORMAT_VERSION = 1;
 const DEFAULT_MAX_PATHS = 2000;
 const ELIGIBLE_MS_CEILING = 600_000;
 const CANDIDATE_TIMEOUT_SEC = ELIGIBLE_MS_CEILING / 1_000;
-const MEASURE_TIMEOUT_MS = 30_000;
-const MEASURE_OUTPUT_CAP_BYTES = 4096;
-
-/**
- * The same named few `timeVerificationCommands` subtracts before spawning a
- * measurement (SIDE_EFFECT_ENV_KEYS in src/host/preflight.mjs, which is
- * module-private and could not be edited by the node that added this): a
- * measure must not notify a human and must not be redirectable at a live,
- * paid harness binary. A subtraction of a named few, not an allowlist — PATH,
- * HOME and every ordinary variable still pass through unchanged.
- */
-const MEASURE_SIDE_EFFECT_ENV_KEYS = [
-  NOTIFY_BIN_ENV,
-  NOTIFY_SESSION_ENV,
-  "FABERUN_CODEX_BIN",
-  "FABERUN_CLAUDE_BIN",
-  "FABERUN_AGY_BIN",
-  "FABERUN_DSH_BIN",
-  "FABERUN_ZCODE_BIN",
-  "FABERUN_EXEC_JSONL_BIN",
-];
 
 /**
  * Every path git tracks at HEAD, sorted. The bounded spawn is the same
@@ -177,9 +154,6 @@ function measureCandidates(cwd, commands, probes) {
  */
 export function measureRequirements(cwd, requirements, probes = {}) {
   if (requirements.length === 0) return [];
-  const run = probes.run ?? spawnSync;
-  const env = { ...process.env };
-  for (const key of MEASURE_SIDE_EFFECT_ENV_KEYS) delete env[key];
   /** @type {RequirementMeasurement[]} */
   const measurements = [];
   for (const requirement of requirements) {
@@ -188,21 +162,13 @@ export function measureRequirements(cwd, requirements, probes = {}) {
     // rather than guessed at.
     if (requirement.measure?.kind !== "command" || !requirement.measure.ref) continue;
     const command = requirement.measure.ref;
-    const result = run(command, { shell: true, cwd, timeout: MEASURE_TIMEOUT_MS, encoding: "utf8", env });
-    const combined = `${result.stdout ?? ""}${result.stderr ?? ""}`;
-    const bytes = Buffer.from(combined, "utf8");
-    const truncated = bytes.length > MEASURE_OUTPUT_CAP_BYTES;
-    measurements.push({
-      requirementId: requirement.id,
-      command,
-      output: truncated ? bytes.subarray(0, MEASURE_OUTPUT_CAP_BYTES).toString("utf8") : combined,
-      exitCode: result.status,
-      truncated,
-    });
+    const { output, exitCode, truncated } = runShellCapture(cwd, command, probes);
+    measurements.push({ requirementId: requirement.id, command, output, exitCode, truncated });
   }
   return measurements;
 }
 
+
 /**
  * @param {string} cwd
  * @param {{measure?: MeasureProbes, maxPaths?: number, requirements?: SpecRequirement[]}} [options]

package/src/plan/sizing.mjs

@@ -20,7 +20,8 @@ import { dirname } from "node:path";
 /** @typedef {{nodes: PlanNode[], justification?: string, [key: string]: unknown}} Plan */
 /** @typedef {{path: string, covers: string|null}} SizingTestFileEntry */
 /** @typedef {{testFiles?: SizingTestFileEntry[]}} SizingFacts */
-/** @typedef {{nodeBudgetMs: number, targetedFix?: boolean, facts?: SizingFacts, minWriteFiles?: number, maxMergedWriteFiles?: number, turnCeiling?: number}} SizingOptions */
+/** @typedef {"implementation"|"exploratory"} PackageMode */
+/** @typedef {{nodeBudgetMs: number, targetedFix?: boolean, facts?: SizingFacts, minWriteFiles?: number, maxMergedWriteFiles?: number, turnCeiling?: number, packageMode?: PackageMode, readVolume?: (path: string) => number|null}} SizingOptions */
 /** @typedef {{rule: string, nodes: string[], detail: string}} SizingTransformation */
 /** @typedef {{plan: Plan, transformations: SizingTransformation[], estimate: {nodes: number, overheadMinutes: number}}} SizingResult */
 
@@ -56,12 +57,22 @@ export function applySizingRules(plan, options) {
 
   let nodes = structuredClone(plan.nodes);
 
-  nodes = mergeNoMechanicalProof(nodes, transformations);
-  nodes = mergeContainedWriteSet(nodes, transformations);
-  nodes = mergeUnderfilledSiblings(nodes, options.minWriteFiles ?? null, options.maxMergedWriteFiles ?? MAX_MERGED_WRITE_FILES, transformations);
+  // Every merge rule below reasons about the write set, which is the right
+  // question for implementation work and the wrong one for exploratory work:
+  // an audit or review node writes one findings file whatever surface it
+  // covers, so a floor of four write files either merges nodes that have
+  // nothing to do with each other or refuses the plan outright. That is why
+  // the audit of 2026-09-22 was written by hand as 50 KB of JSON instead of
+  // planned. In exploratory mode the write set says nothing, and what a node
+  // must read is what it is judged on.
+  const exploratory = options.packageMode === "exploratory";
+  nodes = exploratory ? nodes : mergeNoMechanicalProof(nodes, transformations);
+  nodes = exploratory ? nodes : mergeContainedWriteSet(nodes, transformations);
+  nodes = mergeUnderfilledSiblings(nodes, exploratory ? null : options.minWriteFiles ?? null, options.maxMergedWriteFiles ?? MAX_MERGED_WRITE_FILES, transformations);
   nodes = splitOverBudgetVerification(nodes, nodeBudgetMs, facts, transformations);
   nodes = markParallelisable(nodes, transformations);
   nodes = flagOverTurnCeiling(nodes, options.turnCeiling ?? null, transformations);
+  if (exploratory) nodes = flagReadVolumeImbalance(nodes, options.readVolume ?? null, transformations);
 
   if (nodes.length === 1 && !targetedFix) {
     throw new Error(`sizing_single_node_plan: node ${nodes[0].id} is the plan's only node; pass options.targetedFix to allow a single-node plan`);
@@ -495,3 +506,60 @@ function longestChainDepth(nodes) {
   };
   return nodes.length === 0 ? 0 : Math.max(...nodes.map((node) => depthOf(node.id)));
 }
+
+/**
+ * How far a node's read volume may sit from its siblings' median before the
+ * imbalance is worth naming. Three times: measured 2026-09-22 on an audit
+ * whose nodes were sized by write set (they each wrote one findings file, so
+ * nothing merged and nothing split), one node read about 3,970 lines and cost
+ * $2.00 for 2 findings while another cost $0.57 for 4. The ratio between them
+ * was close to four, and nothing in the plan said so before either ran.
+ */
+const READ_VOLUME_IMBALANCE_RATIO = 3;
+
+/**
+ * Exploratory work is sized by what a node must read, not by what it writes.
+ * An audit node writes one findings file whatever it covers, so every rule
+ * that reasons about the write set is silent here, and the surface a node
+ * carries is the thing that can be unbalanced.
+ *
+ * Advisory, never a transformation of the plan: which files a reviewer must
+ * read together is a judgment this cannot make, so it reports the imbalance
+ * and leaves the split to the author.
+ *
+ * @param {PlanNode[]} nodes
+ * @param {((path: string) => number|null)|null} readVolume lines in a declared read path, or null when it cannot be measured
+ * @param {SizingTransformation[]} transformations
+ * @returns {PlanNode[]}
+ */
+function flagReadVolumeImbalance(nodes, readVolume, transformations) {
+  if (!readVolume || nodes.length < 2) return nodes;
+  const volumes = nodes.map((node) => {
+    const paths = /** @type {string[]} */ (node.taskPacket.readFiles ?? []);
+    let total = 0;
+    let measured = false;
+    for (const path of paths) {
+      const lines = readVolume(path);
+      if (lines === null) continue;
+      measured = true;
+      total += lines;
+    }
+    return { id: node.id, total, measured };
+  }).filter((entry) => entry.measured);
+  if (volumes.length < 2) return nodes;
+
+  const sorted = [...volumes].sort((left, right) => left.total - right.total);
+  const middle = Math.floor(sorted.length / 2);
+  const median = sorted.length % 2 === 0 ? (sorted[middle - 1].total + sorted[middle].total) / 2 : sorted[middle].total;
+  if (median <= 0) return nodes;
+
+  for (const entry of volumes) {
+    if (entry.total <= median * READ_VOLUME_IMBALANCE_RATIO) continue;
+    transformations.push({
+      rule: "read-volume-imbalance",
+      nodes: [entry.id],
+      detail: `${entry.id} reads ${entry.total} lines against a median of ${median} across this plan; exploratory work is paid for by what it reads, so this node costs several times what its siblings do and is worth splitting`,
+    });
+  }
+  return nodes;
+}

package/src/plan/spec.mjs

@@ -6,6 +6,7 @@
  * schedules, or reaches a provider — this module invokes no model.
  */
 import { git } from "../repo/worktree.mjs";
+import { proveRequirements } from "./proof-run.mjs";
 
 /** @typedef {"command"|"path"|"judgment"} ProofKind */
 /** @typedef {{kind: ProofKind, ref?: string}} SpecProof */
@@ -280,8 +281,18 @@ function targetMatchesOrigin(cwd, target) {
  * Advisory by default — every violation is recorded and `ok` stays `true` —
  * and blocking under `strict`, where any violation makes `ok` `false`.
  *
+ * `runProofs` is the exception to "no model call, ever ... never executes
+ * a proof": it opts into actually running each requirement's `proof`
+ * (`proveRequirements`, the same shell-capture path `measure` already has),
+ * because a proof that is merely present is not a proof that passes.
+ * Measured 2026-09-22: two requirements anchored their proof to a form the
+ * artifact no longer had, and `--strict-traceability` alone never noticed,
+ * since it only checks that `proof` exists. A failed proof is blocking
+ * regardless of `strict` — nothing about "the proof does not run" is an
+ * advisory nicety like a missing Non-goals section.
+ *
  * @param {string} text
- * @param {{cwd?: string, strict?: boolean}} [options]
+ * @param {{cwd?: string, strict?: boolean, runProofs?: boolean, proofProbes?: import("./proof-run.mjs").MeasureProbes}} [options]
  * @returns {SpecValidation}
  */
 export function validateSpec(text, options = {}) {
@@ -316,6 +327,19 @@ export function validateSpec(text, options = {}) {
   if (typeof parsed.frontMatter.target === "string" && !targetMatchesOrigin(cwd, parsed.frontMatter.target)) {
     findings.push({ rule: "target-unresolved", severity: "advisory", message: `target "${parsed.frontMatter.target}" does not match the origin remote`, line: 1 });
   }
+  if (options.runProofs === true) {
+    const byId = new Map(parsed.requirements.map((requirement) => [requirement.id, requirement]));
+    for (const result of proveRequirements(cwd, parsed.requirements, options.proofProbes)) {
+      if (result.pass) continue;
+      const requirement = result.requirementId === null ? null : byId.get(result.requirementId);
+      findings.push({
+        rule: "requirement-proof-failed",
+        severity: "blocking",
+        message: `requirement ${result.requirementId ?? requirement?.title ?? "?"}'s proof does not pass (${result.kind}: ${result.ref}): ${result.detail}`,
+        line: requirement?.line ?? 1,
+      });
+    }
+  }
   const graded = findings.map((finding) => (strict ? { ...finding, severity: /** @type {const} */ ("blocking") } : finding));
   return { class: "structured", ok: !graded.some((finding) => finding.severity === "blocking"), findings: graded };
 }

package/src/plan/template.mjs

@@ -23,7 +23,7 @@ import { validateVerificationCommands } from "../contract/verification.mjs";
 /** @typedef {import("../contract/index.mjs").JsonObject} JsonObject */
 /** @typedef {"draft"|"review"|"revise"|"spec-author"|"spec-review"} PlanningKind */
 /** @typedef {"low"|"standard"|"high"} RiskTier */
-/** @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, planPath?: string, findingsPath?: string, notesPath?: string}} PlanningContractInputs */
+/** @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 */
@@ -118,8 +118,30 @@ const PLAN_OUTPUT_SHAPE = '{nodes: [{id, objective, taskKind, riskTier, dependsO
  * 150 requests.
  */
 const SIZING_INSTRUCTION = "Size nodes to 4 to 6 write files where the work allows, and give every node an expectedTurns: the provider requests one worker needs to finish it end to end (measured median 49 for 4 to 6 files). A smaller node pays the same orientation and about 15 minutes of verification, judge and integration for less delivered work; a node you expect past 150 requests must be split, because a run cuts an attempt there.";
+/**
+ * The exploratory counterpart to the sizing guidance above: sizing by what a
+ * node reads, because that is what exploratory work is paid for. An audit
+ * node writes one findings file whatever surface it covers, so the write-set
+ * sentence would size every node in such a package identically and wrongly --
+ * which is why the audit of 2026-09-22 was written by hand as 50 KB of JSON
+ * instead of planned.
+ */
+const EXPLORATORY_SIZING_INSTRUCTION = "Size nodes by what each must read and by risk, never by what it writes: one write file is the normal shape for a finding, a review or an audit. Give every node an expectedTurns (the provider requests one worker needs end to end), keep the read volume of the nodes within the same order of each other so one does not cost several times its siblings, and split a node you expect past 150 requests, because a run cuts an attempt there.";
 const FINDINGS_SHAPE = "[{id, severity, nodeId, text}]";
 
+/**
+ * The instruction list is a frozen table because it is the same for every
+ * campaign; only the sizing sentence depends on what kind of package this is.
+ *
+ * @param {PlanningKind} kind
+ * @param {PlanningContractInputs} inputs
+ * @returns {string[]}
+ */
+function instructionsFor(kind, inputs) {
+  if (inputs.packageMode !== "exploratory") return INSTRUCTIONS[kind];
+  return INSTRUCTIONS[kind].map((line) => (line === SIZING_INSTRUCTION ? EXPLORATORY_SIZING_INSTRUCTION : line));
+}
+
 // The rule every planned packet is held to at freeze time, worded from
 // AGENTS.md's Faberun protocol and src/repo/scope-closure.mjs ("reading it
 // cannot fix it"): a first draft that ignores it produces a plan that fails
@@ -225,7 +247,7 @@ export function buildPlanningContract(kind, inputs) {
   const taskPacket = {
     mode: "discovery",
     objective: OBJECTIVES[kind],
-    instructions: INSTRUCTIONS[kind],
+    instructions: instructionsFor(kind, inputs),
     readFiles,
     writeFiles: [],
     symbols: [],