faberun 0.28.0 → 0.30.0

package/src/plan/rounds.mjs

@@ -27,11 +27,12 @@ import { writeJsonAtomic } from "../run/store.mjs";
 import { stableJson } from "../util.mjs";
 import { assertTimeoutsCoverMeasured, raiseTimeoutsToMeasured } from "./freeze.mjs";
 import { assertFilteredProofsNameTheirTest, declareDirectoryGuards } from "./proof-scope.mjs";
-import { validateFindings, validatePlanOutput } from "./template.mjs";
+import { applyPlanPatch, validateFindings, validatePlanOutput } from "./template.mjs";
 
 /** @typedef {import("../contract/index.mjs").JsonObject} JsonObject */
 /** @typedef {import("../contract/index.mjs").ValidatedContract} ValidatedContract */
 /** @typedef {import("./template.mjs").PlanOutput} PlanOutput */
+/** @typedef {import("./template.mjs").PlanOutputNode} PlanOutputNode */
 /** @typedef {import("./template.mjs").PlanFindingOutput} PlanFindingOutput */
 /** @typedef {import("./template.mjs").PlanningKind} PlanningKind */
 /** @typedef {import("./contest.mjs").ContestedPipelineResult} ContestedPipelineResult */
@@ -288,21 +289,44 @@ export async function runReviewRounds(options) {
     // the findings redrafted the plan from scratch, renamed files and dropped
     // six writes, and its retry fixed one validator error while introducing
     // another.
-    const revise = await runStage("revise", {
-      specPath: relativeSpecPath, repoFactsPath: relativeRepoFactsPath, cataloguePath: relativeCataloguePath, findingsPath: relative(cwd, path), planPath: relativeWorkingPlanPath, packageMode,
-    });
+    //
+    // RM-110: a revise returns a patch over the nodes it changes rather than
+    // the whole plan, so answering one finding costs the size of that
+    // finding's nodes instead of the phase's. Two calls died on the full-plan
+    // shape at 65,932 and 66,821 output tokens against the 65,536 ceiling.
+    // The patch is only asked for when there is a validated plan to apply it
+    // to: a first round whose draft never validated has no node list to patch,
+    // and that round's revise returns a whole plan.
+    const base = plan;
+    const patchMode = base !== null;
+    const stageInputs = { specPath: relativeSpecPath, repoFactsPath: relativeRepoFactsPath, cataloguePath: relativeCataloguePath, packageMode, ...(patchMode ? { revisePatch: true } : {}) };
+    const revise = await runStage("revise", { ...stageInputs, findingsPath: relative(cwd, path), planPath: relativeWorkingPlanPath });
+    /**
+     * The plan a revise's output produced, before any validation: the merged
+     * patch when the reviser patched a plan, its own `output.plan` when there
+     * was no plan to patch. Null only when the merge itself was refused, so
+     * the retry falls back to the plan the first attempt read.
+     *
+     * @param {unknown} onto
+     * @param {Record<string, unknown>} output
+     * @returns {unknown}
+     */
+    const revisionFrom = (onto, output) => (patchMode ? applyPlanPatch(/** @type {{nodes: PlanOutputNode[]} & Record<string, unknown>} */ (onto), output.patch) : output.plan);
     // The whole deterministic check R14 names runs on the revise's output:
     // the shape validator, and the freeze pre-flight a review round would
     // otherwise only reach a round later. Measured 2026-09-26 on the 3a gate:
     // four rounds with no critical from review each contested on a
     // scope-closure gap the same revise had just opened, because the revise
     // learned of it only after the next review had spent its round.
+    /** @type {{nodes: PlanOutputNode[]} & Record<string, unknown>|null} */
+    let revision = null;
     /** @type {PlanOutput|null} */
     let structurallyValid = null;
     /** @type {PlanFindingOutput} */
     let firstInvalid;
     try {
-      structurallyValid = validatePlanOutput(revise.output.plan);
+      revision = /** @type {{nodes: PlanOutputNode[]} & Record<string, unknown>} */ (revisionFrom(base, revise.output));
+      structurallyValid = validatePlanOutput(revision);
       const preflightError = freezePreflightError(structurallyValid);
       if (preflightError === null) return { plan: structurallyValid, runId: revise.contract.id, firstInvalid: null };
       firstInvalid = invalidPlanFinding(`revise-r${round}-attempt1`, preflightError);
@@ -311,18 +335,18 @@ export async function runReviewRounds(options) {
     }
     const retryPath = join(scratchDir, `findings-round-${round}-retry.json`);
     writeJsonAtomic(retryPath, [...findingsForRevise, firstInvalid]);
-    // The retry repairs the output the check refused, not the plan before
-    // it: that output already carries this round's resolutions, and only the
+    // The retry repairs the revision the check refused, not the plan before
+    // it: that revision already carries this round's resolutions, and only the
     // check's message is left to answer.
     const retryPlanPath = join(scratchDir, `plan-round-${round}-rejected.json`);
-    writeJsonAtomic(retryPlanPath, revise.output.plan ?? null);
-    const retry = await runStage("revise", {
-      specPath: relativeSpecPath, repoFactsPath: relativeRepoFactsPath, cataloguePath: relativeCataloguePath, findingsPath: relative(cwd, retryPath), planPath: relative(cwd, retryPlanPath), packageMode,
-    });
+    writeJsonAtomic(retryPlanPath, revision ?? base);
+    const retry = await runStage("revise", { ...stageInputs, findingsPath: relative(cwd, retryPath), planPath: relative(cwd, retryPlanPath) });
     try {
       // A retry that validates goes to review even if the freeze pre-flight
-      // still refuses it: that round's own pre-flight raises it again.
-      return { plan: validatePlanOutput(retry.output.plan), runId: retry.contract.id, firstInvalid };
+      // still refuses it: that round's own pre-flight raises it again. Its
+      // patch applies to the revision the first attempt produced, which is
+      // the plan the retry was handed.
+      return { plan: validatePlanOutput(revisionFrom(revision ?? base, retry.output)), runId: retry.contract.id, firstInvalid };
     } catch (secondError) {
       // The first attempt still validated: it goes to review rather than
       // contesting a round over a retry that made things worse.

package/src/plan/sizing.mjs

@@ -11,6 +11,7 @@
  */
 
 import { dirname } from "node:path";
+import { VERIFICATION_LIMITS } from "../contract/verification.mjs";
 
 /** @typedef {import("../contract/definition-of-done.mjs").DefinitionOfDoneItem} DefinitionOfDoneItem */
 
@@ -18,7 +19,7 @@ import { dirname } from "node:path";
 /** @typedef {{writeFiles?: string[], writeRoots?: string[], verification: SizingVerificationCommand[], [key: string]: unknown}} SizingTaskPacket */
 /** @typedef {{id: string, dependsOn?: string[], taskKind?: string, riskTier?: string, taskPacket: SizingTaskPacket, definitionOfDone?: DefinitionOfDoneItem[], parallel?: boolean, [key: string]: unknown}} PlanNode */
 /** @typedef {{nodes: PlanNode[], justification?: string, [key: string]: unknown}} Plan */
-/** @typedef {{path: string, covers: string|null}} SizingTestFileEntry */
+/** @typedef {{path: string, covers: string[]}} SizingTestFileEntry */
 /** @typedef {{testFiles?: SizingTestFileEntry[]}} SizingFacts */
 /** @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 */
@@ -374,6 +375,13 @@ function flagOverTurnCeiling(nodes, ceiling, transformations) {
  * place instead (a repeat pass never re-flags an already-flagged command, nor
  * re-splits a command that no longer carries a measured duration).
  *
+ * A covering set larger than the contract's own command budget (RM-109) is
+ * flagged, not split: a module almost every test references has that many
+ * covering files because the change is genuinely wide, and replacing one
+ * command with more than `maxCommands` of them freezes a contract that cannot
+ * validate. The flag names the count, and the answer for that shape is the
+ * phase-terminal suite (`finalVerification`), which runs the whole tree once.
+ *
  * @param {PlanNode[]} nodes
  * @param {number} nodeBudgetMs
  * @param {SizingFacts} facts
@@ -393,8 +401,9 @@ function splitOverBudgetVerification(nodes, nodeBudgetMs, facts, transformations
         verification.push(command);
         continue;
       }
-      const candidates = dedupe(testFiles.filter((file) => file.covers !== null && writeFiles.includes(file.covers)).map((file) => file.path));
-      if (candidates.length > 0) {
+      const candidates = dedupe(testFiles.filter((file) => coversSomething(file, writeFiles)).map((file) => file.path));
+      const overflow = candidates.length > VERIFICATION_LIMITS.maxCommands;
+      if (candidates.length > 0 && !overflow) {
         transformations.push({
           rule: "over-budget-verification-split",
           nodes: [node.id],
@@ -406,7 +415,9 @@ function splitOverBudgetVerification(nodes, nodeBudgetMs, facts, transformations
         transformations.push({
           rule: "over-budget-verification-flagged",
           nodes: [node.id],
-          detail: `${command.argv.join(" ")} measured ${command.measuredMs}ms over the ${nodeBudgetMs}ms budget; no repo-facts test file covers this node's writeFiles`,
+          detail: overflow
+            ? `${command.argv.join(" ")} measured ${command.measuredMs}ms over the ${nodeBudgetMs}ms budget; ${candidates.length} test files reference this node's writeFiles, above the contract's ${VERIFICATION_LIMITS.maxCommands}-command budget: prove them once on the phase-terminal node instead of naming each here`
+            : `${command.argv.join(" ")} measured ${command.measuredMs}ms over the ${nodeBudgetMs}ms budget; no repo-facts test file covers this node's writeFiles`,
         });
         changed = true;
         verification.push({ ...command, flaggedOverBudget: true });
@@ -416,6 +427,11 @@ function splitOverBudgetVerification(nodes, nodeBudgetMs, facts, transformations
   });
 }
 
+/** @param {SizingTestFileEntry} file @param {string[]} writeFiles @returns {boolean} */
+function coversSomething(file, writeFiles) {
+  return file.covers.some((module) => writeFiles.includes(module));
+}
+
 /**
  * A node with no dependsOn, that no other node depends on, and whose
  * writeFiles shares nothing with any other node's, may run in parallel with

package/src/plan/spec.mjs

@@ -6,11 +6,14 @@
  * schedules, or reaches a provider — this module invokes no model.
  */
 import { git } from "../repo/worktree.mjs";
+import { shellWords } from "../util.mjs";
+import { nodeTestShape } from "./proof-scope.mjs";
 import { proveRequirements } from "./proof-run.mjs";
 
 /** @typedef {"command"|"path"|"judgment"} ProofKind */
 /** @typedef {{kind: ProofKind, ref?: string}} SpecProof */
-/** @typedef {{id: string|null, title: string, statement: string|null, proof: SpecProof|null, measure: SpecProof|null, constraints: string|null, line: number}} SpecRequirement */
+/** @typedef {{key: string, line: number}} UnknownBulletKey */
+/** @typedef {{id: string|null, title: string, statement: string|null, proof: SpecProof|null, measure: SpecProof|null, constraints: string|null, unknownBulletKeys: UnknownBulletKey[], line: number}} SpecRequirement */
 /** @typedef {Record<string, string>} SpecFrontMatter */
 /** @typedef {{heading: string, body: string, line: number}} SpecSection */
 /** @typedef {{frontMatter: SpecFrontMatter|null, sections: Map<string, SpecSection>, requirements: SpecRequirement[]}} ParsedSpec */
@@ -98,25 +101,41 @@ function extractSections(lines, startIndex) {
  * A `- **key:** value` bullet, and any following non-blank, non-bullet line as
  * its wrapped continuation.
  *
+ * A bullet whose key does not match is *not* a continuation of the one above
+ * it: measured 2026-09-27 (AP14 of safe-to-hand-to-a-friend), a
+ * `- **esclarecimento (27/09):**` line right after `- **proof:**` was dropped
+ * and the lines under it were appended to the proof above, so R8 read as
+ * having no proof while the text said otherwise. The dropped key is returned
+ * so `validateSpec` can name it instead of letting it vanish.
+ *
  * @param {string[]} lines
- * @returns {Map<string, string>}
+ * @returns {{bullets: Map<string, string>, unknownKeys: Array<{key: string, offset: number}>}}
  */
 function parseBullets(lines) {
   /** @type {Map<string, string>} */
   const bullets = new Map();
+  /** @type {Array<{key: string, offset: number}>} */
+  const unknownKeys = [];
   let currentKey = null;
-  for (const line of lines) {
+  for (let offset = 0; offset < lines.length; offset += 1) {
+    const line = lines[offset];
     const match = /^-\s+\*\*([a-zA-Z-]+):\*\*\s?(.*)$/u.exec(line);
     if (match) {
       currentKey = match[1].toLowerCase();
       bullets.set(currentKey, match[2].trim());
       continue;
     }
+    const unrecognized = /^-\s+\*\*(.+?):\*\*\s?/u.exec(line);
+    if (unrecognized) {
+      unknownKeys.push({ key: unrecognized[1], offset });
+      currentKey = null;
+      continue;
+    }
     const trimmed = line.trim();
     if (!trimmed) { currentKey = null; continue; }
     if (currentKey && !trimmed.startsWith("-")) bullets.set(currentKey, `${bullets.get(currentKey)} ${trimmed}`.trim());
   }
-  return bullets;
+  return { bullets, unknownKeys };
 }
 
 /**
@@ -137,6 +156,44 @@ function parseProof(raw) {
   return kind === "judgment" ? { kind } : { kind, ref: match[2].trim() };
 }
 
+/**
+ * A requirement proof that filters `node:test` by name without naming the file
+ * the test lives in, or null. The same shape the frozen contract refuses
+ * (`plan/proof-scope.mjs`, AP1 of safe-to-hand-to-a-friend); raised here so a
+ * spec author sees it when the spec is written, rather than a plan later.
+ * Measured 2026-09-27 (AP8): R1 to R7 of the `safe-to-hand-to-a-friend` spec
+ * each wrote `--test-name-pattern="<title>"` with no file, and only the
+ * planner's own nodes were refused for it.
+ *
+ * @param {SpecProof|null} proof
+ * @returns {string|null}
+ */
+function proofWithoutNamedTestFile(proof) {
+  if (proof?.kind !== "command" || typeof proof.ref !== "string") return null;
+  const shape = nodeTestShape(shellWords(proof.ref));
+  if (!shape || shape.nameFilters.length === 0 || shape.paths.length > 0) return null;
+  return proof.ref;
+}
+
+/**
+ * The one finding `strict` does not promote. Measured 2026-09-28: 105 of the
+ * 237 `--test-name-pattern` proofs in the 109 documents under
+ * `docs/campaigns/` name no test file, across 20 documents. Every one of them
+ * is the record of a run that already happened, and the repository forbids
+ * editing that record to satisfy a rule written later, so promoting this to
+ * blocking would retroactively refuse twenty specs that were accepted when
+ * they were written. The shape is refused where it costs something anyway:
+ * `assertFilteredProofsNameTheirTest` (plan/proof-scope.mjs) fails the freeze
+ * of any plan that carries it, so a plan cannot be built from a fresh spec
+ * with this proof whatever the spec validator says about it.
+ *
+ * @param {SpecFinding} finding
+ * @returns {boolean}
+ */
+function promotableUnderStrict(finding) {
+  return finding.rule !== "proof-filter-names-no-file";
+}
+
 /**
  * @param {SpecSection|undefined} section
  * @returns {SpecRequirement[]}
@@ -154,7 +211,8 @@ function extractRequirements(section) {
     const blockLine = section.line + i + 1;
     let end = i + 1;
     while (end < lines.length && !/^###\s+/u.test(lines[end])) end += 1;
-    const bullets = parseBullets(lines.slice(i + 1, end));
+    const body = lines.slice(i + 1, end);
+    const { bullets, unknownKeys } = parseBullets(body);
     const idMatch = /^(R\d+)\.\s*(.*)$/u.exec(heading);
     requirements.push({
       id: idMatch ? idMatch[1] : null,
@@ -163,6 +221,7 @@ function extractRequirements(section) {
       proof: parseProof(bullets.get("proof")),
       measure: parseProof(bullets.get("measure")),
       constraints: bullets.get("constraints") ?? null,
+      unknownBulletKeys: unknownKeys.map(({ key, offset }) => ({ key, line: blockLine + offset })),
       line: blockLine,
     });
     i = end;
@@ -318,6 +377,23 @@ export function validateSpec(text, options = {}) {
     if (!requirement.proof) {
       findings.push({ rule: "requirement-missing-proof", severity: "advisory", message: `requirement ${requirement.id ?? requirement.title} has no proof`, line: requirement.line });
     }
+    for (const { key, line } of requirement.unknownBulletKeys) {
+      findings.push({
+        rule: "requirement-unknown-bullet-key",
+        severity: "advisory",
+        message: `requirement ${requirement.id ?? requirement.title} has a bullet keyed "${key}", which the format does not read: a key is letters and hyphens (statement, proof, measure, constraints), so this bullet and the lines under it are dropped instead of reaching the requirement. Reword the bullet or use one of the four keys.`,
+        line,
+      });
+    }
+    const unbacked = proofWithoutNamedTestFile(requirement.proof);
+    if (unbacked !== null) {
+      findings.push({
+        rule: "proof-filter-names-no-file",
+        severity: "advisory",
+        message: `requirement ${requirement.id ?? requirement.title}'s proof "${unbacked}" filters node:test by name but names no test file: with no path node --test runs every test file in the tree, each file the filter selects nothing in prints a zero plan, and the plan's own freeze refuses the shape. Name the file that holds the test, as in node --test --test-name-pattern="<title>" test/<area>/<file>.test.mjs.`,
+        line: requirement.line,
+      });
+    }
   }
   const successCriteria = parsed.sections.get("success criteria");
   if (successCriteria) findings.push(...baselineColumnFindings(successCriteria));
@@ -340,6 +416,6 @@ export function validateSpec(text, options = {}) {
       });
     }
   }
-  const graded = findings.map((finding) => (strict ? { ...finding, severity: /** @type {const} */ ("blocking") } : finding));
+  const graded = findings.map((finding) => (strict && promotableUnderStrict(finding) ? { ...finding, severity: /** @type {const} */ ("blocking") } : finding));
   return { class: "structured", ok: !graded.some((finding) => finding.severity === "blocking"), findings: graded };
 }