faberun 0.19.0 → 0.19.2

package/src/plan/pipeline.mjs

@@ -27,7 +27,7 @@ import { allowanceDelta, allowanceEventFields, sampleAllowance } from "../seat/a
 import { askPlanningRuntimes, refusePlanningSilence } from "./preflight.mjs";
 import { parseSpec, validateSpec } from "./spec.mjs";
 import { collectRepoFacts } from "./repo-facts.mjs";
-import { RISK_TIERS, buildPlanningContract, validateFindings, validatePlanOutput } from "./template.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";
@@ -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");
@@ -135,6 +140,12 @@ export async function runPlanningPipeline(options) {
   const repoFactsPath = join(scratchDir, "repo-facts.json");
   writeFileSync(repoFactsPath, `${JSON.stringify(repoFacts, null, 2)}\n`);
   const relativeRepoFactsPath = relative(cwd, repoFactsPath);
+  // The taskKind catalogue is staged like every other planning input. It used
+  // to be handed over as faberun's own `src/plan/template.mjs`, which resolves
+  // against the target repository and therefore exists in exactly one of them.
+  const cataloguePath = join(scratchDir, TASK_KIND_CATALOGUE_FILE);
+  writeFileSync(cataloguePath, renderTaskKindCatalogue());
+  const relativeCataloguePath = relative(cwd, cataloguePath);
   logStage("repo-facts", { gitHead: repoFacts.gitHead });
 
   let n = 0;
@@ -177,7 +188,7 @@ export async function runPlanningPipeline(options) {
     return { contract: validated, output };
   };
 
-  const draft = await runStage("draft", { specPath: relativeSpecPath, repoFactsPath: relativeRepoFactsPath });
+  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
@@ -247,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, {
@@ -365,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, 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.
@@ -754,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,25 +23,57 @@ 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, 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 */
 /** @typedef {{id: string, severity: "critical"|"major"|"minor", nodeId: string, text: string}} PlanFindingOutput */
 
-/**
- * The taskKind catalogue a draft or revise classifies against. Exported here,
- * not read from a separate document, so `TASK_KIND_CATALOGUE_PATH` (this
- * module's own repo-relative path) is a real, always-present file a
- * closed-context worker can be told to read for the authoritative list.
- */
+/** The taskKind catalogue a draft or revise classifies against. */
 export const TASK_KINDS = Object.freeze(["docs", "implement", "test", "refactor", "infra", "judge"]);
 
 /** The risk tiers a draft or revise classifies against. */
 export const RISK_TIERS = Object.freeze(["low", "standard", "high"]);
 
-/** This module's own repo-relative path: the taskKind catalogue's home. */
-export const TASK_KIND_CATALOGUE_PATH = "src/plan/template.mjs";
+/**
+ * The file name the planner stages the catalogue under, beside the spec and
+ * the repository facts it already stages.
+ *
+ * This used to be `src/plan/template.mjs` -- this module's own repo-relative
+ * path -- so that a closed-context worker had a real, always-present file to
+ * read for the authoritative list. It is always present in *this* repository.
+ * A planning contract's `readFiles` resolve against the target repository, and
+ * every other repository refuses the contract with `readFiles[2] does not
+ * exist: src/plan/template.mjs`, which made `faberun plan` able to plan only
+ * faberun. The catalogue is data, so it is written out like the other inputs
+ * instead of being pointed at across repository boundaries.
+ */
+export const TASK_KIND_CATALOGUE_FILE = "task-kinds.md";
+
+/**
+ * The catalogue document itself, rendered from the two exported lists so the
+ * file a worker reads and the values `validatePlanOutput` accepts cannot
+ * drift apart.
+ *
+ * @returns {string}
+ */
+export function renderTaskKindCatalogue() {
+  return [
+    "# taskKind and riskTier catalogue",
+    "",
+    "Written by `faberun plan` for this stage. These are the only values a plan may use;",
+    "any other value is rejected when the plan is validated.",
+    "",
+    "## taskKind",
+    "",
+    ...TASK_KINDS.map((kind) => `- ${kind}`),
+    "",
+    "## riskTier",
+    "",
+    ...RISK_TIERS.map((tier) => `- ${tier}`),
+    "",
+  ].join("\n");
+}
 
 /**
  * Which of the caller's `runtimeDefaults` roles resolves this contract's
@@ -62,8 +94,8 @@ const KIND_ROLE = Object.freeze({
 
 /** @type {Record<PlanningKind, string[]>} */
 const REQUIRED_INPUTS = Object.freeze({
-  draft: ["specPath", "repoFactsPath"],
-  revise: ["specPath", "repoFactsPath", "findingsPath"],
+  draft: ["specPath", "repoFactsPath", "cataloguePath"],
+  revise: ["specPath", "repoFactsPath", "cataloguePath", "findingsPath"],
   review: ["specPath", "repoFactsPath", "planPath"],
   "spec-author": ["notesPath"],
   "spec-review": ["specPath"],
@@ -86,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
@@ -110,7 +164,7 @@ const OBJECTIVES = Object.freeze({
 /** @type {Record<PlanningKind, string[]>} */
 const INSTRUCTIONS = Object.freeze({
   draft: [
-    `Consult ${TASK_KIND_CATALOGUE_PATH}'s exported TASK_KINDS before classifying any node; taskKind must be one of that catalogue and riskTier must be one of ${RISK_TIERS.join(", ")}.`,
+    `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.",
     ...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.`,
@@ -156,9 +210,9 @@ const NON_GOALS = Object.freeze({
  * @returns {string[]}
  */
 function readFilesForKind(kind, inputs) {
-  if (kind === "draft") return [/** @type {string} */ (inputs.specPath), /** @type {string} */ (inputs.repoFactsPath), TASK_KIND_CATALOGUE_PATH];
+  if (kind === "draft") return [/** @type {string} */ (inputs.specPath), /** @type {string} */ (inputs.repoFactsPath), /** @type {string} */ (inputs.cataloguePath)];
   if (kind === "revise") {
-    return [/** @type {string} */ (inputs.specPath), /** @type {string} */ (inputs.repoFactsPath), TASK_KIND_CATALOGUE_PATH, /** @type {string} */ (inputs.findingsPath)];
+    return [/** @type {string} */ (inputs.specPath), /** @type {string} */ (inputs.repoFactsPath), /** @type {string} */ (inputs.cataloguePath), /** @type {string} */ (inputs.findingsPath)];
   }
   if (kind === "review") return [/** @type {string} */ (inputs.specPath), /** @type {string} */ (inputs.repoFactsPath), /** @type {string} */ (inputs.planPath)];
   if (kind === "spec-author") return [/** @type {string} */ (inputs.notesPath)];
@@ -193,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: [],