@codedology/code-forge 0.11.0 → 0.12.0

package/skill/templates/coder-brief.md

@@ -13,10 +13,22 @@
 2. Your facts diff: every contradiction between this brief and the code, in one message.
 3. Your forecast: cases and lines.
 
+## Proof
+
+- Red→green: each new or changed test must FAIL on the old code first (red), then PASS on the new code (green). A red caused by an import, compile or crash error proves nothing; the red must be an assertion failure. `code-forge proof red-green` does this with the block's base code.
+- No hand mutations. Do not break the code on purpose to test the tests. Red→green is the proof.
+- One exact test per acceptance clause, plus one negative or boundary test where the clause can fail. Assertions say which element and how many, never only "it exists".
+- Proof scales with risk: a light-tier file needs red→green per new test; a high-tier file must have it at the gate. Do not add tests, mutants, layers, options or abstractions that the acceptance does not ask for.
+- A weak assertion is fixed by a stronger assertion, not by more tests or mutants.
+
 ## The file loop
 
 After you finish each file in `owned_files` (tests written and green) run `forge review-file <path> --block <id> --run <r>`; before the next file run `forge review-file --wait <ticket> [--max 90s]` and act on the packet. A finding whose fix belongs in another owned file (a missing test, say) is fixed there and sent with `forge review-file <that file> --block <id> --run <r> --answers <ids> --of <source>`. A `worker_down` answer ⇒ print `===BLOCK <id> FAILED: worker down===` (never approval).
 
+With `review.file_loop: overlap`, enqueue after each green file and continue coding. Before the completion sentinel, run `forge review-file --wait-block <id> --run <r> [--max 90s]`. It prints one JSON line `{block, files: [{file, ticket, status}], done}`. Inspect each finished ticket with `--wait <ticket>` and act on its findings; `done: true` means finished, not approved. A timeout has `done: false`, `reason: wait_timeout` and pending files (exit 0): wait again. `not_queued` names an owned changed file you must enqueue. Changed content with an earlier ticket is queued automatically; the worker marks an old pending ticket stale when it starts it. `worker_down` exits 3, always with `done: false`: print the FAILED sentinel. Without a `review.file_loop` setting, or with `wait`, use the per-file loop above. Fix rounds use the same selected loop before their sentinel.
+
+With `review.file_loop: watch` (B104), commit each owned file after its tests are green and continue coding. Watch replaces per-file enqueueing. Before the completion sentinel, including fix rounds, run `forge review-file --wait-block <id> --run <r> [--max 90s]`, inspect finished tickets with `--wait <ticket>`, and fix findings. The worker watches the block worktree HEAD (otherwise repository HEAD), queues owned content from git objects with the same ticket ids as a manual request, and marks older pending tickets `refused`, `reason: superseded`. A running ticket finishes for its old hash, which cannot approve newer bytes; `--wait-block` joins the current ticket per file. `--fresh` refuses a superseded marker; enqueueing that content again removes only its superseded marker so it can run, while a real result stays cached. `queue/watch/<block>.json` stores the last seen commit; missing or unreadable state restarts at `base_sha` with idempotent tickets. A rewound tick queues nothing and drops the last seen commit so the next tick restarts at `base_sha`. A `watch.skipped {block, reason}` row is written once per reason until a healthy head clears the skip reasons: `unreadable_head` (head, tree or objects cannot be read), `not_descendant` (head does not descend from the block base), `rewound` (head no longer descends from the last seen commit), or `unowned_path` (unowned paths are ignored; owned paths still queue). A skip never fails the block. After a `watch.skipped` row, use `forge review-file <path> --block <id> --run <r>` when the file needs a manual review; use `forge review-file <fix file> --block <id> --run <r> --answers <ids> --of <source>` for a fix in another owned file that answers findings. Set watch before starting the worker. With any `review.file_loop` value other than `watch` (`wait`, the default, or `overlap`), the worker does no watch work and runs no git for it.
+
 Proof is behaviour, not text: never read a source file in a test to assert on its text. Call the code and check what it does; a test may read a fixture. A test file that reads a source file and asserts on its text gets a `## test-quality` section in its review packet. The section is a hint, not a finding: the reviewer checks those lines and, when the test really reads source text to assert on it, raises a `warning` (unless the file read is a fixture).
 
 ## Final report — the close prints the ticket ids
@@ -36,17 +48,17 @@ The `TESTS` line stays ABOVE the sentinel; only the test summary comes after it.
 
 End with `===BLOCK <id> COMPLETE===`, the test summary and `git diff --stat`.
 
-The final report needs no `reviewed <path> ticket <id>` lines: `block close` prints one for every file the review gate accepts (approved, waived or answered), with the queue's ticket. The close prints the reviewed lines, then the `reviewed_by_waiver` lines, then the `closed` line. With `--report`, a hand line that names another ticket prints `WARN report ticket mismatch <path>` on stderr when the block closes, and the close goes on. A file with a `review.waived` finding still gets a line; only a close whose every review the human waived, or a `review.external` close, prints none. The printed line has no `via`: `--json` and the block's done file carry the lines as `reviewed: [{file, ticket, via}]`, with `via: approved` for a file with a signed approval, `via: waiver` when at least one of its open findings was waived (also when the others were answered), and `via: answered` when every one was answered. Every changed file still needs its `review-file` run: a file the review did not accept keeps the block open. "All findings addressed" is not a report.
+The final report needs no `reviewed <path> ticket <id>` lines: `block close` prints one for every file the review gate accepts (approved, waived or answered), with the queue's ticket. The close prints the reviewed lines, then the `reviewed_by_waiver` lines, then the `closed` line. With `--report`, a hand line that names another ticket prints `WARN report ticket mismatch <path>` on stderr when the block closes, and the close goes on. A file with a `review.waived` finding still gets a line; only a close whose every review the human waived, or a `review.external` close, prints none. The printed line has no `via`: `--json` and the block's done file carry the lines as `reviewed: [{file, ticket, via}]`, with `via: approved` for a file with a signed approval, `via: waiver` when at least one of its open findings was waived (also when the others were answered), and `via: answered` when every one was answered. Every changed file still needs a review through the selected file loop: a file the review did not accept keeps the block open. "All findings addressed" is not a report.
 
 Or `===BLOCK <id> FAILED: <reason>===`.
 
 ## Fix-round brief (round ≥ 2, or a respawn after a climb)
 
-The open findings by id, the fix history, the files they sit in. Fix only those hunks, then run `forge review-file <path> --block <id> --run <r>` and `--wait` on **every file the round changed** — a fix the reviewer never saw is not a fix. A fix made in another owned file is sent with `--answers <ids> --of <source>` (The file loop). The round's final report follows the same rule as the first: it needs no ticket lines. Re-run the block's test command after the fixes and print a fresh `TESTS <command> exit=<n>` line just before the round's sentinel: a TESTS line from an earlier report does not count.
+The open findings by id, the fix history, the files they sit in. Fix only those hunks, then follow the selected file loop on **every file the round changed** (`wait`: run `forge review-file <path> --block <id> --run <r>` and `--wait`; `overlap`: enqueue each green file and continue; `watch`: commit each green file; both `overlap` and `watch`: run `forge review-file --wait-block <id> --run <r>` before the sentinel) — a fix the reviewer never saw is not a fix. A fix made in another owned file is sent with `--answers <ids> --of <source>` (The file loop). The round's final report follows the same rule as the first: it needs no ticket lines. Re-run the block's test command after the fixes and print a fresh `TESTS <command> exit=<n>` line just before the round's sentinel: a TESTS line from an earlier report does not count. In a fix round, you may use `code-forge gates run --run <r> --block <id> --changed` as the block's test command; the TESTS line names the command actually run (substitute the run and block ids). Any green `code-forge gates run --run <r> --block <id>` records the owned file hashes on `gate.done`, including runs without `--changed`; when `--slug` is omitted, these rows go to the run's project ledger. More than 200 owned files means no record, so the next `--changed` falls back with `no_baseline`; unreadable inputs also leave no record. `{test_files}` expands to changed tests and stem-paired tests of changed sources; `{changed_files}` expands to changed lint/format paths. Deleted files still count for pairing and the threshold, but both tokens receive only files that exist now. Both tokens must be whole argv items and cannot be the command or the only item; config validation refuses a gate whose command or only item is `{changed_files}`. Without `--changed`, `{changed_files}` is dropped. Gates without tokens run as before. Rows carry `scope: changed`, including fallback rows with a `reason`: `no_baseline` uses today's scope, `unpaired` uses today's test scope when a changed source has no test pair, `threshold` runs the full suite above `gates.full_suite_threshold_files` changed files, and `no_changes` uses today's scope when nothing is left to run. The orchestrator runs the full `code-forge gates run` before `block close` (D2).
 
 ## Context pack
 
-<!-- the block's context pack, pasted as text: the block header (run, block, level, owned and test files, worktree), the project's build, test, lint and format commands, the rules files and the lessons file. `forge context pack --run <r> --block <id>` writes it; paste its contents, never its run-root path (`references/code.md` §3). Without a `context` key, leave this section out. -->
+<!-- the block's context pack, pasted as text: the block header (run, block, level, owned and test files, worktree), the project's build, test, lint and format commands, the built-in proof rule, the rules files and the lessons file. `forge context pack --run <r> --block <id>` writes it; paste its contents, never its run-root path (`references/code.md` §3). Without a `context` key, leave this section out. -->
 
 ## Project rules
 

package/src/cli/block.mjs

@@ -847,6 +847,20 @@ async function coderTests(reportFlag, id) {
   }
   const sentinel = parseSentinel(text, id);
   if (sentinel?.status !== 'complete') return { ok: false, reason: `coder report FAILED: no ===BLOCK ${id} COMPLETE=== sentinel` };
+  // Keep diagnostics in the same segment as parseSentinel: any block's sentinel ends it.
+  let malformed = null;
+  let lastMalformed = null;
+  for (const rawLine of text.split('\n')) {
+    const line = rawLine.trim();
+    const end = parseSentinel(line);
+    if (end) {
+      if (end.blockId === id) lastMalformed = malformed;
+      malformed = null;
+    } else if (line.startsWith('TESTS ') && !parseSentinel(`${line}\n===BLOCK ${id} COMPLETE===`, id)?.tests) {
+      malformed = line.slice(0, 120);
+    }
+  }
+  if (lastMalformed !== null) return { ok: false, reason: `coder report FAILED: TESTS line malformed: ${lastMalformed}` };
   if (!sentinel.tests) return { ok: false, reason: 'coder report FAILED: no TESTS line' };
   if (sentinel.tests.exit !== 0) return { ok: false, reason: `coder report FAILED: TESTS exit=${sentinel.tests.exit}` };
   return { ok: true, command: sentinel.tests.command, exit: 0 };

package/src/cli/gates.mjs

@@ -39,7 +39,7 @@ import { writeSafe, redactJSON } from '../util/redact.mjs';
 import { appendRow } from '../ledger/write.mjs';
 import { loadProjectConfig } from '../config/load.mjs';
 import { detectGates } from '../gates/detect.mjs';
-import { printableGates, thresholdOf } from '../gates/expand.mjs';
+import { printableGates, scopeFields, thresholdOf } from '../gates/expand.mjs';
 import { runGates } from '../gates/run.mjs';
 import { runGatesGuarded } from '../proof/lock.mjs';
 import { blockTree } from '../proof/worktree.mjs';
@@ -189,6 +189,7 @@ function realOrResolved(p) {
  */
 function scopeOf({ scope, test_count: testCount, reason }) {
   if (scope === undefined) return {};
+  if (scope === 'changed') return { scope, test_count: testCount, ...(reason ? { reason } : {}) };
   return scope === 'related' ? { scope, test_count: testCount } : { scope, reason };
 }
 
@@ -251,6 +252,11 @@ export async function runGatesVerb(args, deps = {}) {
         err('gates run: --run <id> and --block <id> go together, each with a value\n');
         return 2;
       }
+      const changed = args.includes('--changed');
+      if (changed && runFlag.value === undefined) {
+        err('gates run: --changed needs --run <id> and --block <id>\n');
+        return 2;
+      }
 
       // B62b: a block with a worktree runs its gates in that tree, configured by the main workspace
       const placed = runFlag.value !== undefined && blockFlag.value !== undefined ? await blockWorktree(runFlag.value, blockFlag.value) : null;
@@ -273,29 +279,32 @@ export async function runGatesVerb(args, deps = {}) {
       let ran;
       if (runFlag.value !== undefined && blockFlag.value !== undefined) {
         const threshold = thresholdOf(configured?.full_suite_threshold_files);
-        const guarded = await runGatesGuarded({ runId: runFlag.value, blockId: blockFlag.value, gates, cwd, threshold, ...(timeoutMs ? { timeoutMs } : {}) });
+        const guarded = await runGatesGuarded({ runId: runFlag.value, blockId: blockFlag.value, gates, cwd, threshold, changed, slug, ...(timeoutMs ? { timeoutMs } : {}) });
         if (guarded.result === 'proof.busy') {
           out({ result: 'proof.busy', holder: /** @type {{holder: string}} */ (guarded).holder });
           return 1;
         }
-        ran = /** @type {{value: {results: any[], allOk: boolean}}} */ (guarded).value;
+        ran = /** @type {{value: {results: any[], allOk: boolean, ledger_slug?: string, files?: Record<string, string>, changed_scope?: import('../gates/expand.mjs').ChangedScope}}} */ (guarded).value;
       } else {
         ran = await runGates(gates, { cwd, ...(timeoutMs ? { timeoutMs } : {}) });
       }
       const { results, allOk } = ran;
 
-      if (slug) {
+      const ledgerSlug = slug ?? ran.ledger_slug;
+      if (ledgerSlug) {
         // B60: with --run/--block the rows name the run and the block, so the run's binnacle reads them
         const owner = runFlag.value !== undefined ? { run: runFlag.value, block: blockFlag.value, ...inTree } : {};
         for (const result of results) {
           if (!result.skipped && !result.ok) {
-            await appendRow({ ...owner, event: 'gate.red', gate: result.gate, code: result.code, ...scopeOf(result) }, { slug });
+            await appendRow({ ...owner, event: 'gate.red', gate: result.gate, code: result.code, ...scopeOf(result) }, { slug: ledgerSlug });
           }
         }
         // B60: one scope per run (every `{test_files}` gate shares it), named on gate.done too;
         // without --run/--block that is `scope: full, reason: no_tests`
         const scoped = results.find((r) => r.scope !== undefined);
-        await appendRow({ ...owner, event: 'gate.done', stack: gates.stack, all_ok: allOk, ...(scoped ? scopeOf(scoped) : {}) }, { slug });
+        await appendRow({ ...owner, event: 'gate.done', stack: gates.stack, all_ok: allOk,
+          ...(ran.changed_scope ? scopeFields(ran.changed_scope) : scoped ? scopeOf(scoped) : {}),
+          ...(ran.files ? { files: ran.files } : {}) }, { slug: ledgerSlug });
       }
       out({ stack: gates.stack, ...inTree, results, allOk });
       return allOk ? 0 : 1;

package/src/cli/review-file.mjs

@@ -5,6 +5,8 @@
  *   review-file --wait <ticket> [--max <90s>]      poll; prints {ticket, status: done, result} or
  *                                                  {ticket, status: pending, reason: wait_timeout}
  *                                                  when --max elapses (the review is still running)
+ *   review-file --wait-block <id> --run <id>       join owned changed files' current tickets;
+ *                                                  prints {block, files, done}; never reviews here
  *   review-file <answering file> --block <id> --answers <ids> --of <source> [--run <id>]
  *                                                  B71: enqueue an answers ticket; prints {ticket,
  *                                                  status, kind: answers, file: source, by_file, answers}
@@ -67,20 +69,22 @@
 
 import { readFileSync, realpathSync, rmSync } from 'node:fs';
 import path from 'node:path';
-import { answersTicketId, assertAnswers, dropDoneIf, enqueue, enqueueAnswers, isDone, liveWorker, MAX_ANSWERS, queueDir, resolveTicket } from '../worker/queue.mjs';
+import { answersTicketId, assertAnswers, blockTickets, dropDoneIf, enqueue, enqueueAnswers, isDone, liveWorker, MAX_ANSWERS, queueDir, resolveTicket } from '../worker/queue.mjs';
 import { assertBlockId, assertInsideRoot, assertTicketId, contentHash, mainRootOf, normalizeRequestPath, repoRootOf, WorkerError } from '../worker/ticket.mjs';
-import { namedOnHash } from '../review/gate-check.mjs';
+import { blockFileSet, namedOnHash } from '../review/gate-check.mjs';
 import { STOP_EXITS } from '../review/stop-exits.mjs';
 import { ownsFile } from '../state/registry.mjs';
 import { readAllRows } from '../ledger/write.mjs';
 import { parseFlags } from '../state/cli-args.mjs';
 import { StateError } from '../state/paths.mjs';
+import { assertRunId } from '../state/paths.mjs';
 import { readRun } from '../state/run.mjs';
 import { blockTree } from '../proof/worktree.mjs';
 import { writeSafe } from '../util/redact.mjs';
 
 const USAGE =
   'usage: code-forge review-file <path> --block <id> [--run <id>] [--fresh] | review-file --wait <ticket> [--max <seconds>s]\n' +
+  '       code-forge review-file --wait-block <id> --run <id> [--max <seconds>s]\n' +
   '       code-forge review-file <answering file> --block <id> --answers <id,id,…> --of <source> [--run <id>]\n';
 
 export const DEFAULT_WAIT_MS = 90_000;
@@ -355,6 +359,93 @@ export function fixList(result) {
   return out;
 }
 
+/**
+ * B100: read block scope from the workspace mirror, never the private run record. This is a
+ * progress summary, not an approval: block close still verifies the authoritative signed rows.
+ * @param {string} repoRoot @param {string} cwd @param {string} run @param {string} block
+ * @returns {Promise<{entry: Record<string, any>, tree: string}>}
+ */
+async function waitBlockScope(repoRoot, cwd, run, block) {
+  const top = await repoRootOf(cwd);
+  const candidates = new Set([repoRoot]);
+  for (let dir = realpathSync(cwd); ; dir = path.dirname(dir)) {
+    candidates.add(dir);
+    if (dir === top || dir === path.dirname(dir)) break;
+  }
+  for (const dir of candidates) {
+    let record;
+    try {
+      record = JSON.parse(readFileSync(path.join(dir, '.code-forge', 'runs', `${run}.json`), 'utf8'));
+    } catch (err) {
+      if (err.code === 'ENOENT') continue;
+      throw new WorkerError('block-scope-unreadable', 'the block scope cannot be read');
+    }
+    const entry = record?.blocks?.[block];
+    if (record?.run_id !== run || !entry || !Array.isArray(entry.owned_files) || entry.owned_files.length === 0) {
+      throw new WorkerError('block-scope-unreadable', 'the block scope cannot be read');
+    }
+    const tree = (await blockTree(record.workspace, entry))?.top ?? repoRoot;
+    return { entry, tree };
+  }
+  throw new WorkerError('block-scope-unreadable', 'the block scope cannot be read');
+}
+
+/** A block wait reads only the marker, never review results or the signing key.
+ * @param {string} repoRoot @param {string} ticket @returns {boolean}
+ */
+function blockTicketDone(repoRoot, ticket) {
+  try {
+    const marker = JSON.parse(readFileSync(path.join(queueDir(repoRoot), `${ticket}.done`), 'utf8'));
+    if (marker?.ticket === ticket && typeof marker.status === 'string' && marker.status.length > 0) return true;
+  } catch (err) {
+    if (err.code === 'ENOENT') return false;
+  }
+  throw new WorkerError('result-unreadable', 'a ticket completion marker cannot be read');
+}
+
+/**
+ * Join current-content tickets only. Re-scan on every poll, including before returning done,
+ * so a file edited while waiting gets a new ticket. The worker alone finishes old tickets.
+ * @param {{repoRoot: string, cwd: string, block: string, run: string, maxMs: number, pollMs: number, say: (obj: Record<string, any>) => unknown}} opts
+ */
+async function waitBlock({ repoRoot, cwd, block, run, maxMs, pollMs, say }) {
+  const { entry, tree } = await waitBlockScope(repoRoot, cwd, run, block);
+  const where = realpathSync(tree) === realpathSync(repoRoot) ? {} : { tree: realpathSync(tree) };
+  const deadline = Date.now() + maxMs;
+  let downPolls = 0;
+  for (;;) {
+    const worker = liveWorker(repoRoot);
+    const live = worker?.run === run;
+    downPolls = live ? 0 : downPolls + 1;
+    const tickets = blockTickets({ repoRoot, run, block, ...where });
+    const current = await blockFileSet({ repoRoot: tree, base: entry.base_sha, owned: entry.owned_files, ownedKinds: entry.owned_kinds });
+    const files = current.map(({ file }) => {
+      const opts = { repoRoot, run, block, file, ...where };
+      const { ticket } = resolveTicket(opts);
+      const previous = tickets.filter((t) => t.file === file);
+      let present = previous.find((t) => t.ticket === ticket);
+      if (!present && previous.length > 0 && live) {
+        enqueue(opts);
+        present = { ...previous[previous.length - 1], ticket };
+      }
+      return { file, ticket: present ? ticket : null, status: !present ? 'not_queued' : blockTicketDone(repoRoot, ticket) ? 'done' : 'pending' };
+    });
+    if (downPolls >= 2) {
+      say({ block, files, done: false, status: 'worker_down' });
+      return 3;
+    }
+    if (live && files.every((f) => f.status === 'done')) {
+      say({ block, files, done: true });
+      return 0;
+    }
+    if (live && (files.some((f) => f.status === 'not_queued') || Date.now() >= deadline)) {
+      say({ block, files, done: false, reason: files.some((f) => f.status === 'not_queued') ? 'not_queued' : 'wait_timeout' });
+      return 0;
+    }
+    await new Promise((resolve) => setTimeout(resolve, pollMs));
+  }
+}
+
 /**
  * @param {string[]} args
  * @param {{stdout?: {write: (s: string) => unknown}, stderr?: {write: (s: string) => unknown}, cwd?: string, pollMs?: number, dropDone?: typeof dropDoneIf}} [deps] - `dropDone`: B75's claim, for tests.
@@ -366,10 +457,17 @@ export async function runReviewFile(args, deps = {}) {
   const say = (/** @type {Record<string, any>} */ obj) => writeSafe(stdout, `${JSON.stringify(obj)}\n`);
   const cwd = deps.cwd ?? process.cwd();
   try {
-    const { flags, positionals } = parseFlags(args, { values: ['block', 'run', 'wait', 'max', 'answers', 'of'], booleans: ['fresh'] });
+    const { flags, positionals } = parseFlags(args, { values: ['block', 'run', 'wait', 'wait-block', 'max', 'answers', 'of'], booleans: ['fresh'] });
     // the queue and the worker: the main tree, also from inside a block's worktree
     const repoRoot = await mainRootOf(cwd);
 
+    if (flags['wait-block'] !== undefined) {
+      if (positionals.length > 0 || flags.block !== undefined || flags.wait !== undefined || flags.answers !== undefined || flags.of !== undefined || flags.fresh === true || typeof flags.run !== 'string') {
+        throw new WorkerError('usage', '--wait-block takes a block, --run and --max only');
+      }
+      return await waitBlock({ repoRoot, cwd, block: assertBlockId(flags['wait-block']), run: assertRunId(flags.run), maxMs: flags.max === undefined ? DEFAULT_WAIT_MS : parseMax(flags.max), pollMs: deps.pollMs ?? POLL_MS, say });
+    }
+
     if (typeof flags.wait === 'string') {
       if (positionals.length > 0 || flags.block !== undefined || flags.answers !== undefined || flags.of !== undefined || flags.fresh === true) throw new WorkerError('usage', '--wait takes only a ticket and --max');
       const ticket = assertTicketId(flags.wait);

package/src/config/validate.mjs

@@ -66,7 +66,7 @@
 import { Ajv2020 } from 'ajv/dist/2020.js';
 import schema from '../../schema/code-forge.schema.json' with { type: 'json' };
 import { redact } from '../util/redact.mjs';
-import { TEST_FILES_TOKEN } from '../util/gate-token.mjs';
+import { TEST_FILES_TOKEN, CHANGED_FILES_TOKEN } from '../util/gate-token.mjs';
 import { checkEffort, displayEffort } from '../engines/efforts.mjs';
 import { CLOSED_BOOK_LEVELS, CODEX_CLOSED_BOOK_REFUSAL, isNoClosedBookProvider, OPEN_BOOK_CODEX_WARNING, openBookCodexAllowed } from './closed-book.mjs';
 import { isKnownId, resolveLevel } from './known-ids.mjs';
@@ -484,10 +484,10 @@ function gateMessages(key, value) {
   // full-suite run would be an empty argv
   /** @param {string[]} argv @returns {string[]} */
   const tokenMessages = (argv) =>
-    argv.length === 1 && argv[0] === TEST_FILES_TOKEN
-      ? [`gates.${key}: '${TEST_FILES_TOKEN}' cannot be the only item (the full suite would run an empty command)`]
-      : argv[0] === TEST_FILES_TOKEN
-        ? [`gates.${key}: '${TEST_FILES_TOKEN}' cannot be the command (argv[0])`]
+    argv.length === 1 && [TEST_FILES_TOKEN, CHANGED_FILES_TOKEN].includes(argv[0])
+      ? [`gates.${key}: '${argv[0]}' cannot be the only item (the full suite would run an empty command)`]
+      : [TEST_FILES_TOKEN, CHANGED_FILES_TOKEN].includes(argv[0])
+        ? [`gates.${key}: '${argv[0]}' cannot be the command (argv[0])`]
         : [];
   if (typeof value !== 'object' || Array.isArray(value)) {
     if (!isArgvArray(value)) return [`gates.${key} must be a non-empty argv array of strings, an {argv, env} object, or null`];
@@ -1162,3 +1162,10 @@ export function validateConfig(cfg, opts = {}) {
 }
 
 export { schema as configSchema };
+
+/** The effective file loop for a validated config, including opt-in commit watch.
+ * @param {Record<string, any>} cfg @returns {string}
+ */
+export function reviewFileLoop(cfg) {
+  return cfg?.review?.file_loop ?? 'wait';
+}

package/src/context/pack.mjs

@@ -12,11 +12,11 @@
  *
  * `assemblePack` turns it into ONE pack for a block, in this order: the header (run, block, level,
  * owned files, test files when the block has them, worktree path and branch when it has one), the
- * commands (never run; each argv shown POSIX shell-quoted, so a pasted line expands nothing), each
- * rules file, then the lessons file — every file section headed by its source path (an empty
- * file: the heading alone). Over `max_lines` the lessons are cut first, then the
+ * commands (never run; each argv shown POSIX shell-quoted, so a pasted line expands nothing), the
+ * built-in proof rule, each rules file, then the lessons file — every file section headed by its
+ * source path (an empty file: the heading alone). Over `max_lines` the lessons are cut first, then the
  * rules from the last file backwards, each cut section ending in `[cut: N lines dropped]`; the
- * header and the commands are never cut.
+ * header, commands and proof rule are never cut; all count toward the budget.
  *
  * `reviewDigest` is the ONE builder of the review packets' rules digest (`## project rules`, ≤ 60
  * lines, `packet.mjs`): the rules files' text, then a `### lessons` subheading and the lessons.
@@ -41,6 +41,7 @@ import path from 'node:path';
 import { estimateTokens } from '../review/packet.mjs';
 import { splitLines } from '../review/context.mjs';
 import { redact } from '../util/redact.mjs';
+import { PROOF_RULE } from '../proof/rule.mjs';
 
 /** The pack's line cap when `context.max_lines` is not set. */
 export const DEFAULT_MAX_LINES = 300;
@@ -272,6 +273,8 @@ export function assemblePack({ settings, sources, block }) {
   // a command line can name a secret (a token in an argv): it is redacted as rules and lessons are
   for (const k of keys) header.push(`${k}: ${redact(argvText(settings.commands[k]))}`);
 
+  header.push(...splitLines(PROOF_RULE));
+
   /** @type {Array<{heading: string, body: string[], dropped: number}>} */
   const sections = sources.rules.map((r) => ({ heading: `## rules: ${r.path}`, body: [...r.lines], dropped: 0 }));
   if (sources.lessons) sections.push({ heading: `## lessons: ${sources.lessons.path}`, body: [...sources.lessons.lines], dropped: 0 });

package/src/gates/expand.mjs

@@ -1,6 +1,7 @@
 /**
  * B60 (issue #13 item 3): run only the block's related tests, and give a gate its own environment.
- * Pure — no filesystem, no child process. A gate argv item that is EXACTLY {@link TEST_FILES_TOKEN}
+ * Scope and argv rules are pure; B99's fileBaseline reads bounded hashes from the workspace.
+ * A gate argv item that is EXACTLY {@link TEST_FILES_TOKEN}
  * (one whole item, never a substring, never a shell string) stands for the block's test files:
  *
  *  - the block's `test_files` (`block open --tests`), else its owned entries that are concrete
@@ -20,8 +21,14 @@
  * `CI=1` or `MODE=test` would otherwise mask unrelated text (`npm test`).
  */
 
-import { isExactEntry } from '../state/registry.mjs';
-import { TEST_FILES_TOKEN } from '../util/gate-token.mjs';
+import { createHash } from 'node:crypto';
+import { access, lstat, readFile, realpath } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { isExactEntry, ownsFile } from '../state/registry.mjs';
+import { pairsFor } from '../review/paired.mjs';
+import { exec } from '../util/exec.mjs';
+import { TEST_FILES_TOKEN, CHANGED_FILES_TOKEN } from '../util/gate-token.mjs';
 
 export { TEST_FILES_TOKEN };
 
@@ -67,6 +74,7 @@ const isConcreteFile = (p) => typeof p === 'string' && p.length > 0 && isExactEn
 
 /**
  * @typedef {{scope: 'related', files: string[]} | {scope: 'full', reason: 'threshold' | 'no_tests'}} TestScope
+ * @typedef {{scope: 'changed', files: string[], changedFiles: string[], reason?: 'no_baseline'|'unpaired'|'threshold'|'no_changes'}} ChangedScope
  */
 
 /** A gate run with no block: no test file is known. */
@@ -108,30 +116,115 @@ export function hasTestFilesItem(gates) {
   return Object.values(gates ?? {}).some((command) => argvOf(command)?.includes(TEST_FILES_TOKEN) === true);
 }
 
+/** @param {Record<string, unknown> | null | undefined} gates @returns {boolean} */
+export function hasScopeItem(gates) {
+  return hasTestFilesItem(gates) || Object.values(gates ?? {}).some((command) => argvOf(command)?.includes(CHANGED_FILES_TOKEN));
+}
+
+/** A safe repo-relative path that cannot turn into an argv option. @param {string} file */
+function safeFile(file) {
+  return file.length > 0 && !file.startsWith('-') && !path.isAbsolute(file) && !/[\\\x00-\x1f]/.test(file) && !file.split('/').some((s) => s === '' || s === '.' || s === '..');
+}
+
+/**
+ * Bounded content baseline. Missing listed files are omitted from hashes and candidates; an
+ * owned entry with no current file has no hash. More than 200 owned files, a symlink, a
+ * non-regular owned file, a path outside the root or another read error means no record;
+ * callers retain the old scope. Git sees only argv and an isolated git environment.
+ * @param {string} cwd @param {string[]} owned @param {Record<string, string>} [kinds]
+ * @returns {Promise<{files: Record<string, string>, candidates: string[]} | null>}
+ */
+export async function fileBaseline(cwd, owned, kinds) {
+  const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('GIT_')));
+  env.GIT_CONFIG_NOSYSTEM = '1';
+  env.GIT_CONFIG_GLOBAL = os.devNull;
+  const listed = await exec(['git', 'ls-files', '-z', '--cached', '--others', '--exclude-standard'], { cwd, env, timeoutMs: 30000 });
+  if (listed.result !== 'ok') return null;
+  const listedFiles = [...new Set(listed.stdout.split('\0').filter(Boolean))].sort();
+  const candidates = [];
+  const files = /** @type {Record<string, string>} */ (Object.create(null));
+  try {
+    const root = await realpath(cwd);
+    for (const file of listedFiles) {
+      const isOwned = ownsFile(owned, file, kinds);
+      if (isOwned && !safeFile(file)) return null;
+      const absolute = path.join(root, file);
+      if (!isOwned) {
+        const exists = await access(absolute).then(() => true).catch((error) => {
+          if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return false;
+          throw error;
+        });
+        if (exists) candidates.push(file);
+        continue;
+      }
+      const stat = await lstat(absolute).catch((error) => {
+        if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return null;
+        throw error;
+      });
+      if (stat === null) continue;
+      candidates.push(file);
+      if (Object.keys(files).length >= 200 || !stat.isFile() || !(await realpath(absolute)).startsWith(root + path.sep)) return null;
+      files[file] = createHash('sha256').update(await readFile(absolute)).digest('hex');
+    }
+  } catch { return null; }
+  return { files, candidates };
+}
+
+/**
+ * Compare the last green record. A source without a stem pair cannot narrow the test gate.
+ * @param {{baseline: unknown, current: Awaited<ReturnType<typeof fileBaseline>>, fallback: TestScope, threshold?: number, owned?: string[], kinds?: Record<string, string>}} opts
+ * @returns {ChangedScope}
+ */
+export function changedScope({ baseline, current, fallback, threshold = DEFAULT_FULL_SUITE_THRESHOLD, owned, kinds }) {
+  const old = /** @type {Record<string, string> | null} */ (baseline);
+  const candidates = new Set(current?.candidates);
+  const fallbackFiles = fallback.scope === 'related' ? fallback.files.filter((file) => !current || candidates.has(file)) : [];
+  if (!current || !old || typeof old !== 'object' || Array.isArray(old) || Object.keys(old).length > 200 ||
+      Object.entries(old).some(([file, hash]) => !safeFile(file) || (owned && !ownsFile(owned, file, kinds)) || typeof hash !== 'string' || !/^[a-f0-9]{64}$/.test(hash))) {
+    return { scope: 'changed', files: fallbackFiles, changedFiles: [], reason: 'no_baseline' };
+  }
+  const changes = [...new Set([...Object.keys(old), ...Object.keys(current.files)])].filter((file) => old[file] !== current.files[file]).sort();
+  if (changes.length > threshold) return { scope: 'changed', files: [], changedFiles: [], reason: 'threshold' };
+  const changedFiles = changes.filter((file) => candidates.has(file));
+  // B97 also pairs Swift Tests names outside lowercase test directories.
+  const isChangedTest = (/** @type {string} */ file) => isTestPath(file) || file.endsWith('Tests.swift');
+  const tests = new Set(changedFiles.filter(isChangedTest));
+  for (const file of changes.filter((f) => !isChangedTest(f))) {
+    const pairs = pairsFor(file, current.candidates).filter(isChangedTest);
+    if (pairs.length === 0) return { scope: 'changed', files: fallbackFiles, changedFiles, reason: 'unpaired' };
+    for (const paired of pairs) tests.add(paired);
+  }
+  if (tests.size === 0) return { scope: 'changed', files: fallbackFiles, changedFiles, reason: 'no_changes' };
+  return { scope: 'changed', files: [...tests].sort(), changedFiles };
+}
+
 /**
  * One gate argv with every item that is exactly {@link TEST_FILES_TOKEN} replaced by the related
  * test files, or dropped for a full run. Always a new array; `scoped` is false (and the items
  * unchanged) when the gate has no such item.
- * @param {ReadonlyArray<string>} argv @param {TestScope} scope
+ * @param {ReadonlyArray<string>} argv @param {TestScope | ChangedScope} scope
  * @returns {{argv: string[], scoped: boolean}}
  * @throws {TypeError} a test path that starts with `-` (it would be read as an option; `block
  *   open --tests` refuses one too).
  */
 export function expandArgv(argv, scope) {
-  if (!argv.includes(TEST_FILES_TOKEN)) return { argv: [...argv], scoped: false };
-  const files = scope.scope === 'related' ? scope.files : [];
+  if (!argv.includes(TEST_FILES_TOKEN) && !argv.includes(CHANGED_FILES_TOKEN)) return { argv: [...argv], scoped: false };
+  const files = scope.scope === 'full' ? [] : scope.files;
+  const changed = scope.scope === 'changed' ? scope.changedFiles : [];
+  if (changed.some((file) => !safeFile(file))) throw new TypeError('expandArgv: unsafe changed path');
   const dashed = files.find((f) => f.startsWith('-'));
   if (dashed !== undefined) throw new TypeError(`expandArgv: test path ${JSON.stringify(dashed)} starts with "-"`);
-  return { argv: argv.flatMap((item) => (item === TEST_FILES_TOKEN ? files : [item])), scoped: true };
+  return { argv: argv.flatMap((item) => item === TEST_FILES_TOKEN ? files : item === CHANGED_FILES_TOKEN ? changed : [item]), scoped: true };
 }
 
 /**
  * The fields a scoped gate's result and ledger row carry: `scope`, plus `test_count` when related
  * or `reason` when full.
- * @param {TestScope} scope
- * @returns {{scope: 'related', test_count: number} | {scope: 'full', reason: 'threshold' | 'no_tests'}}
+ * @param {TestScope | ChangedScope} scope
+ * @returns {{scope: 'changed', test_count: number, reason?: 'no_baseline'|'unpaired'|'threshold'|'no_changes'} | {scope: 'related', test_count: number} | {scope: 'full', reason: 'threshold'|'no_tests'}}
  */
 export function scopeFields(scope) {
+  if (scope.scope === 'changed') return { scope: 'changed', test_count: scope.files.length, ...(scope.reason ? { reason: scope.reason } : {}) };
   return scope.scope === 'related' ? { scope: 'related', test_count: scope.files.length } : { scope: 'full', reason: scope.reason };
 }
 

package/src/gates/run.mjs

@@ -8,6 +8,7 @@
 
 import { exec } from '../util/exec.mjs';
 import { registerSecret } from '../util/redact.mjs';
+import { CHANGED_FILES_TOKEN } from '../util/gate-token.mjs';
 import { NO_BLOCK_SCOPE, envOf, expandArgv, maskableEnvValues, scopeFields } from './expand.mjs';
 
 /** @typedef {import('./detect.mjs').Gate} Gate */
@@ -25,9 +26,9 @@ import { NO_BLOCK_SCOPE, envOf, expandArgv, maskableEnvValues, scopeFields } fro
  * @property {number | null} code
  * @property {string} stdout
  * @property {string} stderr
- * @property {'related'|'full'} [scope] - B60: only on a gate whose argv has the `{test_files}` item.
+ * @property {'related'|'full'|'changed'} [scope] - only on a gate with a scope token.
  * @property {number} [test_count] - B60: with `scope: related`, how many test files it ran.
- * @property {'threshold'|'no_tests'} [reason] - B60: with `scope: full`, why the item was dropped.
+ * @property {'threshold'|'no_tests'|'no_baseline'|'unpaired'|'no_changes'} [reason] - why narrowing fell back.
  * @property {string[]} [env_keys] - B60: only on a gate given with a non-empty `env`: the variable
  *   NAMES, sorted (the values are never in a result).
  */
@@ -53,7 +54,7 @@ function normalizeCommand(command) {
  * no test file is known (`scope: full, reason: no_tests`). A gate with `env` runs with those
  * variables added to the inherited environment; a gate with neither runs exactly as before B60.
  * @param {{test?: Gate, lint?: Gate, types?: Gate, format?: Gate}} gates
- * @param {{cwd: string, timeoutMs?: number, scope?: TestScope}} opts
+ * @param {{cwd: string, timeoutMs?: number, scope?: TestScope | import('./expand.mjs').ChangedScope}} opts
  * @returns {Promise<{results: GateResult[], allOk: boolean}>}
  */
 export async function runGates(gates, opts) {
@@ -77,8 +78,9 @@ export async function runGates(gates, opts) {
     const command = gates[gate] ?? null;
     if (command === null) return { gate, command: null };
     const normalized = normalizeCommand(command);
+    if (normalized.argv[0] === CHANGED_FILES_TOKEN) throw new TypeError(`gates.${gate}: '{changed_files}' cannot be the command (argv[0])`);
     const { argv, scoped } = expandArgv(normalized.argv, scope);
-    if (argv.length === 0 && normalized.argv.length > 0) throw new TypeError(`gates.${gate}: the argv is empty once '{test_files}' is dropped for the full suite — put the test command before it`);
+    if (argv.length === 0 && normalized.argv.length > 0) throw new TypeError(`gates.${gate}: the argv is empty once ${normalized.argv.map((item) => `'${item}'`).join(' and ')} is dropped for the full suite — put the test command before it`);
     return { gate, command: { argv, scoped, failOnStdout: normalized.failOnStdout, env: normalized.env } };
   });
   /** @type {GateResult[]} */

package/src/install/wizard/flags.mjs

@@ -3,7 +3,7 @@
  * wizard answer (`ANSWER_FLAGS` maps flag -> answer key); `--no-interaction` is a mode switch and
  * overrides no answer.
  *
- * **Q16 = cut (Ricardo, 2026-09-25):** step 8 asks no mutation-tool or nightly question, so the
+ * **Q16 = cut (the owner, 2026-09-25):** step 8 asks no mutation-tool or nightly question, so the
  * v1.2 `--no-nightly` flag is gone and `--proof` takes only the keys the schema still has
  * (`isolation`, `high`, `link_dirs`, `copy_untracked`). With `-g` and `-p` counted as two flags
  * (two tokens that each set the scope answer) there are 21 answer flags: B65 added

package/src/proof/lock.mjs

@@ -16,7 +16,8 @@
  * with `isolation: lock` through the B6 writer.
  */
 
-import { hasTestFilesItem, testScope } from '../gates/expand.mjs';
+import { changedScope, fileBaseline, hasScopeItem, testScope } from '../gates/expand.mjs';
+import { readAllRows } from '../ledger/write.mjs';
 import { ownedFileCount } from '../gates/owned-count.mjs';
 import { runGates } from '../gates/run.mjs';
 import { StateError } from '../state/paths.mjs';
@@ -139,23 +140,35 @@ export async function withGateSlot({ runId, blockId, fn, pid = process.pid }) {
  * run record once the slot is taken). The full suite runs instead when the block owns more than
  * `threshold` (`gates.full_suite_threshold_files`) files, or when no test file is known. The
  * owned files are counted by `ownedFileCount` over the tracked and new (not ignored) files at
- * `cwd`. Gates with no `{test_files}` item run exactly as before B60: the run record is not read
- * and nothing is counted.
- * @param {{runId: string, blockId: string, gates: Parameters<typeof runGates>[0], cwd: string, timeoutMs?: number, threshold?: number}} opts
+ * `cwd`. Plain gates without --changed retain the old path. B99 records bounded owned hashes
+ * after green scoped runs; --changed uses the last green record and B97's stem pairs.
+ * @param {{runId: string, blockId: string, gates: Parameters<typeof runGates>[0], cwd: string, timeoutMs?: number, threshold?: number, changed?: boolean, slug?: string}} opts
  */
-export async function runGatesGuarded({ runId, blockId, gates, cwd, timeoutMs, threshold }) {
+export async function runGatesGuarded({ runId, blockId, gates, cwd, timeoutMs, threshold, changed = false, slug }) {
   return withGateSlot({
     runId,
     blockId,
     fn: async () => {
-      // plain gates (no `{test_files}` item) run exactly as before B60: no scope is worked out
-      if (!hasTestFilesItem(gates)) return runGates(gates, { cwd, ...(timeoutMs ? { timeoutMs } : {}) });
+      // Plain gates without --changed need no scope or baseline.
+      if (!hasScopeItem(gates) && !changed) return runGates(gates, { cwd, ...(timeoutMs ? { timeoutMs } : {}) });
       // the slot checked the block is open; it may still be gone by the time it is read again
-      const block = (await readRun(runId)).blocks?.[blockId];
+      const record = await readRun(runId);
+      const block = record.blocks?.[blockId];
       if (!block) throw new StateError('no-block', `block ${blockId} is not in run ${runId}`);
       const ownedFiles = await ownedFileCount(cwd, block.owned_files, block.owned_kinds);
-      const scope = testScope({ testFiles: block.test_files, owned: block.owned_files, ownedFiles, ...(threshold === undefined ? {} : { threshold }) });
-      return runGates(gates, { cwd, ...(timeoutMs ? { timeoutMs } : {}), scope });
+      const fallback = testScope({ testFiles: block.test_files, owned: block.owned_files, ownedFiles, ...(threshold === undefined ? {} : { threshold }) });
+      const current = await fileBaseline(cwd, block.owned_files, block.owned_kinds);
+      let baseline;
+      if (changed) {
+        const rows = await readAllRows(slug ?? record.project);
+        baseline = rows.filter((row) => row.event === 'gate.done' && row.run === runId && row.block === blockId && row.all_ok === true && row.worktree === block.worktree?.path).at(-1)?.files;
+      }
+      const scope = changed ? changedScope({ baseline, current, fallback, owned: block.owned_files, kinds: block.owned_kinds, ...(threshold === undefined ? {} : { threshold }) }) : fallback;
+      const ran = await runGates(gates, { cwd, ...(timeoutMs ? { timeoutMs } : {}), scope });
+      // A command that changed an input did not measure the resulting bytes. Do not baseline it.
+      const after = ran.allOk && current ? await fileBaseline(cwd, block.owned_files, block.owned_kinds) : null;
+      const files = after && JSON.stringify(current?.files) === JSON.stringify(after.files) ? after.files : undefined;
+      return { ...ran, ledger_slug: slug ?? record.project, ...(files ? { files } : {}), ...(changed ? { changed_scope: scope } : {}) };
     },
   });
 }