@codedology/code-forge 0.10.0 → 0.12.0

package/src/cli/block.mjs

@@ -70,6 +70,21 @@
  * FAILED: no review-file ticket id for <files>` (skipped under `--no-require-reviews`, the human's
  * way out). It runs after the review rows and reuses their file set (listed once).
  *
+ * B96 (E1): the tool builds the close report. After the review gate passed, the close prints
+ * `reviewed <path> ticket <id>` for every file the gate accepted, sorted by path, before the
+ * `reviewed_by_waiver` lines and the closed line; the id is the queue's ticket for that file at the
+ * hash the gate accepted (`resolveTicket`: the tree of a worktree block is part of it). `--json`
+ * and the done file get `reviewed: [{file, ticket, via}]` (`via`: approved, waiver or answered —
+ * the gate's own verdict, `review/reviewed-lines.mjs`), only when there is a line. So `--report`
+ * needs no ticket line: a missing hand line refuses only for a file the tool has no line for, and a
+ * hand line that names another ticket prints `WARN report ticket mismatch <path>` on stderr while
+ * the close goes on (D1). A gate-accepted file with no ticket prints `WARN no ticket for <path>`
+ * (`WARN bad ticket for <path>` when the ticket is not 24 lowercase hex) and has no line; lines that
+ * cannot be built at all give no line and `WARN reviewed lines unavailable: <message>` — then
+ * `--report` needs a hand line for every file the gate accepted, as before B96. All four warnings
+ * are held and print only when the block closes. A waived or external-review close is unchanged:
+ * no line, no key.
+ *
  * B58 (issue #11): `review.external.required: true` in the run's config snapshot (the owner set it
  * before `run start`; `run reload` refuses to change it) is the owner's non-interactive way out
  * when an outside reviewer reviews the block: the per-file review checks and the `--report` ticket
@@ -200,12 +215,13 @@ import { validateConfig } from '../config/validate.mjs';
 import { migrateConfig } from '../config/migrate.mjs';
 import { exec } from '../util/exec.mjs';
 import { contentHash, gitChildEnv } from '../worker/ticket.mjs';
-import { clearDone } from '../worker/queue.mjs';
+import { clearDone, resolveTicket } from '../worker/queue.mjs';
 import { loadState } from '../worker/review-state.mjs';
 import { openBlockEntry, reopenFile } from '../review/reopen.mjs';
 import { checkFileForm, checkFindingId } from '../review/verb-forms.mjs';
 import { runRootPath } from '../util/tmp.mjs';
 import { missingReviewTickets, parseSentinel } from '../engines/sentinel.mjs';
+import { reportMismatches, reviewedLines } from '../review/reviewed-lines.mjs';
 import { blockEndHook, runBlockEndHook, writeDoneFile } from '../state/block-end.mjs';
 import { blockOpenFindings } from '../review/open-findings.mjs';
 import { hookForbidden, scanTranscript } from '../util/forbidden.mjs';
@@ -281,11 +297,14 @@ const FLAG_VALUES = ['run', 'level', 'acceptance', 'brief', 'attempt', 'base', '
  *   isTTY?: boolean, stdinIsTTY?: boolean, stdoutIsTTY?: boolean,
  *   ui?: {confirm: (o: {message: string, initialValue?: boolean}) => Promise<unknown>, isCancel: (v: unknown) => boolean},
  *   removeBlockTree?: typeof removeBlockTree,
+ *   resolveTicket?: typeof resolveTicket, reviewedLines?: typeof reviewedLines,
  * }} [deps] - `now` (B48): the clock of the autopilot expiry checks. `stdinIsTTY` / `stdoutIsTTY`
  *   (default `process.stdin.isTTY` / `process.stdout.isTTY`; `isTTY` sets both) and `ui` (default
  *   `@clack/prompts`): the human's confirmation (B52 `--no-require-reviews`, B80 `block waive` and
  *   `block reopen`), which needs both to be TTYs.
  *   `removeBlockTree` (B64b, tests only): the `--remove-worktree` step, default the real one.
+ *   `resolveTicket` / `reviewedLines` (B96, tests only): the queue's ticket rule and the reviewed
+ *   lines builder of the close, default the real ones.
  * @returns {Promise<number>}
  */
 export async function runBlock(args, deps = {}) {
@@ -344,7 +363,8 @@ export async function runBlock(args, deps = {}) {
     // then the owner's `hooks.on_block_end` from the run-start snapshot. Without the hook key the
     // done file is the only addition: no row, and every output stays exactly as before.
     const hook = blockEndHook(record);
-    const ended = async (/** @type {'closed' | 'stopped'} */ status, /** @type {string} */ event, /** @type {string | null} */ reason) => {
+    // B96: `reviewed` (the close's tool lines) joins the done file only when there is one
+    const ended = async (/** @type {'closed' | 'stopped'} */ status, /** @type {string} */ event, /** @type {string | null} */ reason, /** @type {import('../review/reviewed-lines.mjs').ReviewedLine[]} */ reviewed = []) => {
       // ruling (e): `ended` never throws — any failure here is the done-file warning and a null
       // `doneFile`, so the caller's try/finally still reaches the hook
       /** @type {string | null} */
@@ -358,6 +378,7 @@ export async function runBlock(args, deps = {}) {
           reason: typeof reason === 'string' ? redact(reason) : null,
           openFindings: (rows) => blockOpenFindings(record, rows, id),
           err,
+          ...(reviewed.length > 0 ? { reviewed } : {}),
         });
       } catch (thrown) {
         const code = /** @type {any} */ (thrown)?.code;
@@ -568,6 +589,9 @@ export async function runBlock(args, deps = {}) {
       // B70: a file whose review left only waived findings passes as `reviewed_by_waiver`; its signed
       // `gate.review_waived_all` row joins the close rows (written just before `block.close`, only
       // when the block closes — a refused close writes none)
+      // B96: whether the review gate passed — set from the gate's own result (below), so the files
+      // it checked are the ones it accepted and the tool can give their reviewed lines
+      let reviewsPassed = false;
       const onWaivedAll = (/** @type {import('../review/gate-check.mjs').WaivedAll[]} */ files) => {
         // idempotent: the waived rows are rebuilt from the final list, never appended per call
         // (closeBlock reads closeRows only after every extra check passed)
@@ -575,7 +599,7 @@ export async function runBlock(args, deps = {}) {
         const others = closeRows.filter((r) => r.event !== 'gate.review_waived_all');
         closeRows.splice(0, closeRows.length, ...others, ...files.map((f) => ({ event: 'gate.review_waived_all', block: id, file: f.file, content_hash: f.content_hash, findings: f.findings, by: f.by, ...(f.answered?.length ? { answered: f.answered } : {}) })));
       };
-      const reviews = reviewGateCheck(async () => {
+      const gate = reviewGateCheck(async () => {
         const transcript = await findTranscript(record, id, typeof flags.transcript === 'string' ? flags.transcript : null);
         if (transcript === null) {
           await writeSigned(runId, writeRow, { event: 'gate.transcript_missing', block: id });
@@ -625,7 +649,63 @@ export async function runBlock(args, deps = {}) {
           highPaths,
         };
       }, { onWaivedAll });
-      // B36: the coder's report names a review-file ticket for every changed file, or it is FAILED
+      // B96: `reviewsPassed` comes from the gate's own result, not from the onWaivedAll call. Each
+      // extra check runs at most once per close (`closeBlock`'s one loop, src/state/block.mjs:562,
+      // and `closeBlock` is called once below), so the gate's one pass is its final one.
+      const reviews = async () => {
+        const result = await gate();
+        reviewsPassed = result.ok;
+        return result;
+      };
+      // B96: the stderr warnings of the reviewed lines (`WARN no ticket for <path>`, `WARN bad
+      // ticket for <path>`, `WARN reviewed lines unavailable: <message>`, `WARN report ticket
+      // mismatch <path>`): kept here and printed only when the block closes, before the reviewed
+      // lines — a refused close prints none
+      /** @type {string[]} */
+      const lineWarnings = [];
+      // B96: the tool's reviewed lines — one per file the review gate accepted, with the queue's
+      // ticket for that file at the hash the gate accepted (`resolveTicket`, the queue's own rule:
+      // the same path check, tree resolution and ticket id); a file whose content moved since the
+      // gate hashed it, or whose ticket cannot be given, has no line (fail closed, `WARN no ticket
+      // for <path>`), and so has a file whose ticket is not 24 lowercase hex (`WARN bad ticket for
+      // <path>`). None when the reviews were waived (the human flag or `review.external`) or the
+      // gate has not passed — and that empty answer is never memoised: the lines are built once,
+      // from the gate's pass (its file set and hashes, its waivedAll). It never throws: an error
+      // gives no lines and one held `WARN reviewed lines unavailable: <message>`, so the done file
+      // and the on_block_end hook of a closed block always follow.
+      /** @type {Promise<import('../review/reviewed-lines.mjs').ReviewedLine[]> | undefined} */
+      let linesOnce;
+      const toolLines = async () => {
+        if (!reviewsPassed || reviewsWaived || external !== null) return [];
+        linesOnce ??= (async () => {
+          try {
+            const { mainTop, top, inTree, fileSet } = await tree();
+            const resolve = deps.resolveTicket ?? resolveTicket;
+            const ticketOf = (/** @type {{file: string, content_hash: string}} */ f) => {
+              try {
+                const t = resolve({ repoRoot: mainTop, run: runId, block: id, file: f.file, tree: inTree ? top : null });
+                return t.content_hash === f.content_hash ? t.ticket : null;
+              } catch {
+                return null;
+              }
+            };
+            return await (deps.reviewedLines ?? reviewedLines)({
+              files: fileSet,
+              waivedAll,
+              ticketOf,
+              onNoTicket: (file) => lineWarnings.push(`WARN no ticket for ${file}\n`),
+              onBadTicket: (file) => lineWarnings.push(`WARN bad ticket for ${file}\n`),
+            });
+          } catch (thrown) {
+            lineWarnings.push(`WARN reviewed lines unavailable: ${thrown instanceof Error ? thrown.message : String(thrown)}\n`);
+            return [];
+          }
+        })();
+        return linesOnce;
+      };
+      // B36 → B96: the coder's report. The tool gives the reviewed lines, so a missing hand line is
+      // a refusal only for a file the tool has no line for; a hand line that names another ticket
+      // is a warning and the close goes on (D1: the tool lines are the record)
       const report = async () => {
         if (typeof flags.report !== 'string' || reviewsWaived || external !== null) return { ok: true };
         let text;
@@ -635,8 +715,12 @@ export async function runBlock(args, deps = {}) {
           return { ok: false, reason: 'coder report FAILED: --report cannot be read' };
         }
         const { fileSet } = await tree();
-        const missing = missingReviewTickets(text, fileSet.map((f) => f.file));
-        return missing.length === 0 ? { ok: true } : { ok: false, reason: `coder report FAILED: no review-file ticket id for ${missing.join(', ')}` };
+        const lines = await toolLines();
+        const given = new Set(lines.map((l) => l.file));
+        const missing = missingReviewTickets(text, fileSet.map((f) => f.file)).filter((f) => !given.has(f));
+        if (missing.length > 0) return { ok: false, reason: `coder report FAILED: no review-file ticket id for ${missing.join(', ')}` };
+        for (const file of reportMismatches(text, lines)) lineWarnings.push(`WARN report ticket mismatch ${file}\n`);
+        return { ok: true };
       };
       /** @type {Array<() => Promise<{ok: boolean, reason?: string}>>} */
       const extraChecks = [reviews, report];
@@ -666,14 +750,19 @@ export async function runBlock(args, deps = {}) {
       const result = await closeBlock({ runId, id, rows, writeRow, livePid: intFlag(flags['worker-pid'], 'worker-pid'), probe, extraChecks, closeRows });
       // B64b: the block ended (closed, or stopped by a worker pin event or ledger.tamper) — its rows
       // are written and the run lock released; the done file is written before the tree is removed
-      const end = result.status === 'closed' || result.status === 'stopped' ? await ended(result.status, result.event ?? (result.status === 'stopped' ? 'block.stop' : 'block.close'), result.reason ?? null) : null;
+      // B96: the tool's reviewed lines of a block that closed (also kept in its done file)
+      const reviewedJson = result.ok ? await toolLines() : [];
+      const end = result.status === 'closed' || result.status === 'stopped' ? await ended(result.status, result.event ?? (result.status === 'stopped' ? 'block.stop' : 'block.close'), result.reason ?? null, reviewedJson) : null;
       // B64b ruling (e): the hook runs exactly once for this end, after everything else the verb
       // does — also when a later step (the output, `--remove-worktree`) throws; it never changes
       // the exit code or stdout (`runHook` never throws)
       try {
+        // B96: the reviewed lines (sorted by path) come first, then the reviewed_by_waiver lines
         // B70: each file that passed as reviewed_by_waiver is named before the closed line
         // B71: an answered finding is named as answered; a file with only answered findings has no `by`
         if (result.ok) {
+          for (const w of lineWarnings) err(w);
+          for (const l of reviewedJson) say(`reviewed ${l.file} ticket ${l.ticket}\n`);
           for (const f of waivedAll) {
             const parts = f.findings.length > 0 ? [`${f.findings.join(', ')}; by ${f.by}`] : [];
             if (f.answered?.length) parts.push(`answered ${f.answered.join(', ')}`);
@@ -692,6 +781,8 @@ export async function runBlock(args, deps = {}) {
           ...(end?.json ?? {}),
           // B70: only when a file passed as reviewed_by_waiver (otherwise the output is unchanged)
           ...(result.ok && waivedAll.length > 0 ? { reviewed_by_waiver: waivedAll.map((f) => ({ file: f.file, content_hash: f.content_hash, status: f.status, findings: f.findings, by: f.by, ...(f.answered?.length ? { answered: f.answered } : {}) })) } : {}),
+          // B96: only when the tool gave reviewed lines (a waived or external close is unchanged)
+          ...(reviewedJson.length > 0 ? { reviewed: reviewedJson } : {}),
         };
         if (!result.ok || !removeTree) {
           if (json && result.ok) emit(closedJson);
@@ -756,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,13 +5,15 @@
  *   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}
  *   review-file <path> --block <id> --fresh        B75: re-run a cached result that never counted
  *
- * The same content enqueued again after an `unavailable` result is a fresh attempt (`retry: true`),
- * not the old result.
+ * The same content enqueued again after an `unavailable` or round-1 `split_required` result is a
+ * fresh attempt (`retry: true`), not the old result.
  * A done result that is not approved and carries open findings adds `fix_list` (what the coder
  * fixes before re-running `review-file <path>`, which is then a round-2 recheck of the fix hunks,
  * §4.11); a result the loop stopped adds `stop` with the reason (`review_cap`, …) and (B73)
@@ -28,8 +30,9 @@
  * down on two polls in a row, and a worker whose pid is alive with a fresh heartbeat is never down
  * (`liveWorker`, B30). Output is one JSON line on stdout.
  * B75: `--fresh` drops the cached done marker of the file's current content and queues the ticket
- * again ONLY when that result never counted as a review: `stale`, `unavailable`, or `refused` with
- * `other-run`, `context-unreadable` or a `worktree-*` reason (an allow-list, fail closed). Any
+ * again ONLY when that result never counted as a review: `stale`, `unavailable`, round-1
+ * `split_required`, or `refused` with `other-run`, `context-unreadable` or a `worktree-*` reason
+ * (an allow-list, fail closed). Any
  * other cached result — a round ran (findings, approved, stopped), `review-state-lost`, an answers
  * result, an unknown status or reason, an unreadable marker — is refused `fresh-needs-reopen`
  * (exit 1, `exits: [block reopen, block waive]`, the marker kept byte-for-byte); a
@@ -66,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;
@@ -129,8 +134,9 @@ const FRESH_REFUSED = new Set(['other-run', 'context-unreadable']);
 
 /**
  * B75: may `--fresh` drop this cached result? An allow-list, fail closed: `rerun` only for a
- * result that never counted as a review — `stale`, `unavailable`, or `refused` with a reason that
- * is not a verdict (`other-run`, `context-unreadable`, `worktree-*`) — whose marker names the same
+ * result that never counted as a review — `stale`, `unavailable`, round-1 `split_required`, or
+ * `refused` with a reason that is not a verdict (`other-run`, `context-unreadable`, `worktree-*`)
+ * — whose marker names the same
  * status. `tampered` for `refused review-state-tampered`; `counted` for everything else (a round
  * ran, `review-state-lost`, an answers result, an unknown status or reason, an unreadable marker or
  * result).
@@ -145,7 +151,7 @@ export function freshVerdict(text, result) {
     return 'counted';
   }
   if (result === null || marker === null || typeof marker !== 'object' || marker.status !== result.status) return 'counted';
-  if (result.status === 'stale' || result.status === 'unavailable') return 'rerun';
+  if (result.status === 'stale' || result.status === 'unavailable' || result.status === 'split_required') return 'rerun';
   if (result.status !== 'refused' || typeof result.reason !== 'string') return 'counted';
   if (result.reason === 'review-state-tampered') return 'tampered';
   return FRESH_REFUSED.has(result.reason) || result.reason.startsWith('worktree-') ? 'rerun' : 'counted';
@@ -166,10 +172,11 @@ export const FRESH_EXITS = Object.freeze(['block reopen', 'block waive']);
  * crash between the drop and the enqueue leaves only a re-runnable pending ticket. Anything else is refused and the marker kept byte-for-byte:
  * `fresh-needs-reopen` (names `block reopen` and `block waive`) or `fresh-tampered` (names only
  * the owner's `block close --no-require-reviews`; reopen refuses a tampered state).
- * @param {{repoRoot: string, run: string, block: string, file: string, where: {tree?: string}, say: (obj: Record<string, any>) => unknown, dropDone?: typeof dropDoneIf}} opts
+ * B110: a plain cached round-1 `split_required` uses the same claim, with `retry: true`.
+ * @param {{repoRoot: string, run: string, block: string, file: string, where: {tree?: string}, say: (obj: Record<string, any>) => unknown, dropDone?: typeof dropDoneIf, retry?: boolean}} opts
  * @returns {number} the exit code.
  */
-function freshTicket({ repoRoot, run, block, file, where, say, dropDone = dropDoneIf }) {
+function freshTicket({ repoRoot, run, block, file, where, say, dropDone = dropDoneIf, retry = false }) {
   const { ticket } = resolveTicket({ repoRoot, run, block, file, tree: where.tree ?? null });
   const markerPath = path.join(queueDir(repoRoot), `${ticket}.done`);
   /** @type {'rerun' | 'tampered' | 'counted'} */
@@ -210,7 +217,7 @@ function freshTicket({ repoRoot, run, block, file, where, say, dropDone = dropDo
     // dropped: queue it again now (a crash right here leaves a pending ticket with no marker, which
     // the next review-file queues anyway); gone: another caller took the marker, a normal enqueue
     const queued = enqueue({ repoRoot, run, block, file, ...where });
-    say(outcome === 'dropped' ? { ...queued, fresh: true } : queued);
+    say(outcome === 'dropped' ? { ...queued, ...(retry ? { retry: true } : { fresh: true }) } : queued);
     return 0;
   }
   if (verdict === 'tampered') {
@@ -223,7 +230,7 @@ function freshTicket({ repoRoot, run, block, file, where, say, dropDone = dropDo
     ticket,
     file,
     exits: [...FRESH_EXITS],
-    message: `fresh-needs-reopen: the cached result of ${file} counts as a review (or cannot be read, or kept changing under the claim); --fresh re-runs only stale, unavailable or refused other-run/worktree-*/context-unreadable results; the human's ways out are block reopen and block waive; the cached result was kept`,
+    message: `fresh-needs-reopen: the cached result of ${file} counts as a review (or cannot be read, or kept changing under the claim); --fresh re-runs only stale, unavailable, round-1 split_required or refused other-run/worktree-*/context-unreadable results; the human's ways out are block reopen and block waive; the cached result was kept`,
   });
   return 1;
 }
@@ -352,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.
@@ -363,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);
@@ -410,6 +511,9 @@ export async function runReviewFile(args, deps = {}) {
     const where = realpathSync(tree) === realpathSync(repoRoot) ? {} : { tree };
     if (flags.fresh === true) return freshTicket({ repoRoot, run: worker.run, block, file, where, say, ...(deps.dropDone ? { dropDone: deps.dropDone } : {}) });
     const queued = enqueue({ repoRoot, run: worker.run, block, file, ...where });
+    if (queued.status === 'done' && doneResult(repoRoot, queued.ticket)?.status === 'split_required') {
+      return freshTicket({ repoRoot, run: worker.run, block, file, where, say, retry: true, ...(deps.dropDone ? { dropDone: deps.dropDone } : {}) });
+    }
     if (queued.status === 'done' && doneResult(repoRoot, queued.ticket)?.status === 'unavailable') {
       // `unavailable` is never approval AND never final: drop the done marker so the worker runs
       // the ticket again (the fix loop re-runs its pending round); the signed result is replaced.

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 });