@codedology/code-forge 0.7.7 → 0.9.0

package/src/review/answers.mjs

@@ -0,0 +1,445 @@
+/**
+ * B71 (issue #9 b): an answers ticket — `review-file <answering file> --block <id> --answers <ids>
+ * --of <source>` — asks ONE fresh L2 reviewer session whether the answering file (`by_file`)
+ * resolves the open findings `<ids>` of the source file. The worker runs it through the engine
+ * seam (`reviewTicket` dispatches here on `kind: 'answers'`); `loop.mjs` has already checked the
+ * ticket's run, its tree and that the source still has the ticket's hash.
+ *
+ * Checks here (the ones that count; `review-file` only pre-checks the same rules, unverified):
+ *  - both files are owned by the block (`answers-not-owned`) and they are two files
+ *    (`answers-same-file`);
+ *  - each file is read ONCE: the answering file's bytes must hash to the ticket's `by_hash` (else
+ *    `stale`, `answering-file-changed`; absent or unreadable: `answers-file-missing`) and the
+ *    source's to its `content_hash` (else `stale`, `source-changed`); the packet is built from
+ *    those same bytes, so the row's `by_hash` is the hash of what the reviewer saw;
+ *  - every id is open on the source's CURRENT hash by the signed rows and not waived or answered
+ *    yet — `answerableFindings`, the close's own rules (`answers-not-open`).
+ * A refusal runs no session. The packet holds each finding (file, lines, severity, claim, evidence,
+ * fix — from the source's signed fix-loop state; only id and severity when the state has none),
+ * the source lines around it, and the answering file's diff against the block base (its full
+ * content when it is new). The reviewer answers per id `resolved` or `not_resolved` with a reason;
+ * a missing, repeated or broken verdict is `not_resolved`, and a session that fails (no result,
+ * not `ok`, a non-zero exit, a thrown spawn error: `session-error`) makes the ticket `unavailable`
+ * with no row. A packet that cannot be built (B79: a secret-like source or answering file too) is
+ * `packet-unreadable`; the whole packet stays within the `full_in` budget, and one whose fixed text
+ * alone is over it is refused `packet-too-large`. One that cannot be written to the work dir is
+ * `packet-write-failed`. All three are refusals (`unavailable`: never approval, no session, no row). For each resolved id the
+ * worker writes one signed `review.answered {block, file: source, content_hash: source hash,
+ * finding, by_file, by_hash, ticket}` row (`ctx.writeRow` stamps the block, the source and its
+ * hash). The ticket's result is `status: 'answers'`, never an approval: the gate never reads it
+ * as a verdict on the source (`neverReviewed`), the answering file still needs its own approval,
+ * and the source's fix-loop state is not touched.
+ *
+ * The worker's file and state readers come in through `io` (the worker passes its own
+ * `readRegularFileNoFollow`, `loadState` and `assertAnswers`), so this review-side module imports
+ * nothing from `src/worker/`.
+ */
+
+import { createHash, randomBytes } from 'node:crypto';
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { ownsFile } from '../state/registry.mjs';
+import { exec } from '../util/exec.mjs';
+import { redact } from '../util/redact.mjs';
+import { ANSWERED_EVENT, ANSWERS_STATUS, answerableFindings, ticketAnswered } from './gate-check.mjs';
+import { fixHunkDiff } from './fixloop.mjs';
+import { assertPacketPath, budgetFor, isSecretLike, plainGitEnv, reviewGitEnv } from './packet.mjs';
+import { spawnWithTimeoutRetry } from './session-retry.mjs';
+
+/** The answer the reviewer gives: one verdict per finding id. */
+export const ANSWERS_SCHEMA = Object.freeze({
+  type: 'object',
+  properties: {
+    verdicts: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          id: { type: 'string' },
+          verdict: { type: 'string', enum: ['resolved', 'not_resolved'] },
+          reason: { type: 'string' },
+        },
+        required: ['id', 'verdict', 'reason'],
+        additionalProperties: false,
+      },
+    },
+  },
+  required: ['verdicts'],
+  additionalProperties: false,
+});
+
+/** The system prompt of the answers session. */
+export const ANSWERS_LENS =
+  'You are a code reviewer for code-forge, judging whether a change in one file resolves findings a review raised about another file. ' +
+  'You have no tools and no files; everything you may use is in the message. Answer once, with a JSON object that matches the schema.';
+
+/** Lines of the source shown before and after each finding. */
+const AROUND = 5;
+
+/** A reason longer than this is cut (the reviewer's free text). */
+const REASON_MAX = 500;
+
+/** B79: what a part cut at the packet budget ends with. */
+export const TRUNCATED_MARKER = '[... truncated at the packet budget]';
+
+/** B79: what a cut part shows when its cap is too small for {@link TRUNCATED_MARKER}. */
+export const SHORT_MARKER = '[cut]';
+
+/** B79: the packet's fixed text (headings, labels, fences) alone is over the budget. */
+class PacketTooLarge extends Error {}
+
+/**
+ * @typedef {object} AnswersOutcome
+ * @property {string} status - `answers`, `stale` or `unavailable`.
+ * @property {boolean} approved - always false.
+ * @property {string} engine
+ * @property {string} [reason]
+ * @property {string} kind - `answers`.
+ * @property {Array<{id: string, severity: unknown, verdict: 'resolved' | 'not_resolved', reason: string}>} [findings]
+ * @property {Array<Record<string, any>>} sessions
+ */
+
+/**
+ * The ticket fields an answers ticket carries (`worker/queue.mjs` `enqueueAnswers`).
+ * @typedef {object} AnswersTicket
+ * @property {string} ticket
+ * @property {string} block
+ * @property {string} file - the source.
+ * @property {string} content_hash - the source's hash.
+ * @property {string} [by_file]
+ * @property {string} [by_hash]
+ * @property {string[]} [answers]
+ */
+
+/**
+ * What the worker's review context gives an answers ticket.
+ * @typedef {object} AnswersContext
+ * @property {string} repoRoot
+ * @property {string | null} [contentRoot] - the block's tree, when it has one.
+ * @property {string} runId
+ * @property {string} [runRootDir]
+ * @property {Buffer | null} [key]
+ * @property {Parameters<typeof budgetFor>[0]} cfg
+ * @property {Parameters<typeof spawnWithTimeoutRetry>[0]} spawn
+ * @property {() => Promise<Array<Record<string, any>>>} [readRows]
+ * @property {(row: Record<string, any>) => Promise<unknown>} [writeRow]
+ */
+
+/**
+ * The worker's readers (injected, see the module doc).
+ * @typedef {object} AnswersIo
+ * @property {(root: string, file: string) => Buffer | null} readFile - no symlinks; null when absent.
+ * @property {(opts: Record<string, any>) => {status: string, state?: Record<string, any> | null}} loadState - the signed fix-loop state, read only.
+ * @property {(answers: unknown) => string[]} assertAnswers - the queue's id-list rule (sorted, unique); throws when the list is bad.
+ */
+
+/**
+ * @param {string} status @param {string} reason @param {Array<Record<string, any>>} [sessions]
+ * @returns {AnswersOutcome}
+ */
+const outcome = (status, reason, sessions = []) => ({ status, reason, approved: false, engine: 'adaptive', kind: 'answers', sessions });
+
+/**
+ * Run one answers ticket.
+ * @param {AnswersTicket} ticket - `kind: 'answers'`.
+ * @param {AnswersContext} ctx - `contentRoot` is the block's tree.
+ * @param {{entry: {base: string | null, owned: string[], ownedKinds?: Record<string, string>}, workDir: string, io: AnswersIo}} opts
+ * @returns {Promise<AnswersOutcome>}
+ */
+export async function reviewAnswers(ticket, ctx, { entry, workDir, io }) {
+  const root = ctx.contentRoot ?? ctx.repoRoot;
+  const source = ticket.file;
+  const byFile = /** @type {string} */ (ticket.by_file);
+  // the id list, checked here too by the queue's own rule: 1 to 10 well-formed ids, none twice
+  /** @type {string[]} */
+  let ids;
+  try {
+    ids = io.assertAnswers(ticket.answers);
+  } catch {
+    return outcome(ANSWERS_STATUS, 'usage');
+  }
+  if (!Array.isArray(ticket.answers) || ids.length !== ticket.answers.length) return outcome(ANSWERS_STATUS, 'usage');
+  if (!ctx.key || !ctx.readRows || !ctx.writeRow) return outcome('unavailable', 'no-ledger');
+  if (typeof byFile !== 'string' || path.posix.normalize(byFile) === path.posix.normalize(source)) return outcome(ANSWERS_STATUS, 'answers-same-file');
+  if (!ownsFile(entry.owned, source, entry.ownedKinds) || !ownsFile(entry.owned, byFile, entry.ownedKinds)) return outcome(ANSWERS_STATUS, 'answers-not-owned');
+  // each file is read ONCE; the hashes and the packet come from these bytes
+  /** @type {Buffer | null} */
+  let byBytes;
+  /** @type {Buffer | null} */
+  let srcBytes;
+  try {
+    byBytes = io.readFile(root, byFile);
+  } catch {
+    byBytes = null;
+  }
+  if (byBytes === null) return outcome(ANSWERS_STATUS, 'answers-file-missing');
+  const byHash = hashOf(byBytes);
+  if (byHash !== ticket.by_hash) return outcome('stale', 'answering-file-changed');
+  try {
+    srcBytes = io.readFile(root, source);
+  } catch {
+    srcBytes = null;
+  }
+  if (srcBytes === null || hashOf(srcBytes) !== ticket.content_hash) return outcome('stale', 'source-changed');
+
+  let rows;
+  try {
+    rows = (await ctx.readRows()).filter((r) => r?.run === ctx.runId);
+  } catch {
+    return outcome('unavailable', 'ledger-unreadable');
+  }
+  const current = new Map([
+    [source, ticket.content_hash],
+    [byFile, byHash],
+  ]);
+  // this ticket's own rows do not close an id: a retry after a partial write finishes the rest
+  const open = answerableFindings({ block: ticket.block, runId: ctx.runId, rows, key: ctx.key, file: source, hash: ticket.content_hash, current, ticket: ticket.ticket });
+  if (!ids.every((id) => open.has(id))) return outcome(ANSWERS_STATUS, 'answers-not-open');
+
+  let text;
+  try {
+    text = await packetText({ ticket, ctx, rows, root, entry, open, io, ids, srcBytes, byBytes, workDir });
+  } catch (err) {
+    // B79: a packet whose fixed text alone is over the budget is refused like an unreadable one:
+    // never approval, no session, no row
+    if (err instanceof PacketTooLarge) return outcome('unavailable', 'packet-too-large');
+    return outcome('unavailable', 'packet-unreadable');
+  }
+  const promptPath = path.join(workDir, `answers-${randomBytes(6).toString('hex')}.md`);
+  try {
+    mkdirSync(workDir, { recursive: true, mode: 0o700 });
+    writeFileSync(promptPath, text, { mode: 0o600 });
+  } catch {
+    return outcome('unavailable', 'packet-write-failed');
+  }
+
+  const note = async (/** @type {Record<string, any>} */ row) => {
+    try {
+      await ctx.writeRow?.(row);
+    } catch {
+      // a note is best-effort
+    }
+  };
+  let res;
+  try {
+    ({ res } = await spawnWithTimeoutRetry(ctx.spawn, { level: 'L2', role: 'reviewer', promptPath, schema: ANSWERS_SCHEMA, systemPromptText: ANSWERS_LENS, rowExtra: { lens: 'answers' } }, note));
+  } catch {
+    // a spawn or adapter error is no verdict: retry the ticket
+    return outcome('unavailable', 'session-error');
+  } finally {
+    rmSync(promptPath, { force: true });
+  }
+  const sessions = [{ lens: 'answers', role: 'reviewer', level: 'L2', provider: res?.provider ?? null, model: res?.model ?? null, tokens_in: res?.usage?.tokens_in ?? null, tokens_out: res?.usage?.tokens_out ?? null }];
+  // a spawn that threw (`spawnWithTimeoutRetry` gives null) is `session-error`, like a throw above
+  if (!res) return outcome('unavailable', 'session-error', sessions);
+  if (res.status !== 'ok' || (res.exit_code !== undefined && res.exit_code !== 0)) return outcome('unavailable', typeof res.status === 'string' && res.status !== 'ok' ? res.status : 'exit', sessions);
+
+  const verdicts = verdictsOf(res.answer, ids);
+  /** @type {NonNullable<AnswersOutcome['findings']>} */
+  const findings = ids.map((id) => {
+    const v = verdicts.get(id) ?? { verdict: /** @type {const} */ ('not_resolved'), reason: 'no valid verdict' };
+    return { id, severity: open.get(id) ?? null, verdict: v.verdict, reason: v.reason };
+  });
+  // every verdict is built before any row is written; an id this ticket already answered (an
+  // earlier attempt whose later write failed) gets no second row, so a retry ends with one per id
+  const done = ticketAnswered({ block: ticket.block, runId: ctx.runId, rows, key: ctx.key, file: source, current, ticket: ticket.ticket });
+  for (const f of findings) {
+    if (f.verdict !== 'resolved' || done.has(f.id)) continue;
+    try {
+      await ctx.writeRow({ event: ANSWERED_EVENT, finding: f.id, by_file: byFile, by_hash: byHash, ticket: ticket.ticket });
+    } catch {
+      return outcome('unavailable', 'ledger-write-failed', sessions);
+    }
+  }
+  return { status: ANSWERS_STATUS, approved: false, engine: 'adaptive', kind: 'answers', findings, sessions };
+}
+
+/**
+ * The reviewer's verdict per requested id: only `{id, verdict: 'resolved' | 'not_resolved',
+ * reason: string}` entries count; an id given twice, an unknown id or a broken entry gives no
+ * verdict for that id (the caller reads it as `not_resolved`).
+ * @param {unknown} answer @param {string[]} ids
+ * @returns {Map<string, {verdict: 'resolved' | 'not_resolved', reason: string}>}
+ */
+export function verdictsOf(answer, ids) {
+  /** @type {Map<string, {verdict: 'resolved' | 'not_resolved', reason: string}>} */
+  const out = new Map();
+  let value = answer;
+  if (typeof value === 'string') {
+    try {
+      value = JSON.parse(value);
+    } catch {
+      return out;
+    }
+  }
+  const list = value && typeof value === 'object' && Array.isArray(/** @type {any} */ (value).verdicts) ? /** @type {unknown[]} */ (/** @type {any} */ (value).verdicts) : [];
+  /** @type {Set<string>} */
+  const seen = new Set();
+  /** @type {Set<string>} */
+  const repeated = new Set();
+  for (const v of list) {
+    const e = /** @type {Record<string, unknown>} */ (v);
+    if (!e || typeof e !== 'object' || typeof e.id !== 'string' || !ids.includes(e.id)) continue;
+    if (seen.has(e.id)) repeated.add(e.id);
+    seen.add(e.id);
+    if ((e.verdict === 'resolved' || e.verdict === 'not_resolved') && typeof e.reason === 'string') out.set(e.id, { verdict: e.verdict, reason: e.reason.slice(0, REASON_MAX) });
+  }
+  for (const id of repeated) out.delete(id);
+  return out;
+}
+
+/** The worker's content hash of bytes it read (`worker/ticket.mjs` `contentHash`: sha256, hex). */
+const hashOf = (/** @type {Buffer} */ bytes) => createHash('sha256').update(bytes).digest('hex');
+
+/**
+ * The answering file's change, built from the bytes that were hashed (never a second read): its
+ * diff against its text at the block base (`entry.base`, else HEAD), or its full content when the
+ * base has no such file. A secret-like path or a git failure throws (`packet-unreadable`).
+ * @param {{root: string, file: string, base: string | null, bytes: Buffer, workDir: string}} opts
+ * @returns {Promise<{kind: 'new' | 'tracked', text: string}>}
+ */
+async function answeringChange({ root, file, base, bytes, workDir }) {
+  const rel = assertPacketPath(root, file);
+  if (isSecretLike(rel)) throw new Error('secret-like path');
+  const ref = base ?? 'HEAD';
+  if (typeof ref !== 'string' || ref.length === 0 || ref.startsWith('-')) throw new Error('the base must be a commit id');
+  const git = { cwd: root, timeoutMs: 30000 };
+  const listed = await exec(['git', 'ls-tree', '-z', ref, '--', rel], { ...git, env: reviewGitEnv() });
+  if (listed.result !== 'ok') throw new Error(`git ls-tree failed (exit ${listed.code})`);
+  const current = bytes.toString('utf8');
+  if (listed.stdout.length === 0) return { kind: 'new', text: current };
+  const shown = await exec(['git', 'show', `${ref}:${rel}`], { ...git, env: plainGitEnv() });
+  if (shown.result !== 'ok') throw new Error(`git show failed (exit ${shown.code})`);
+  const diff = await fixHunkDiff({ file: rel, previous: shown.stdout, current, workDir });
+  return { kind: 'tracked', text: diff.diffText };
+}
+
+/**
+ * B79: `text` cut to at most `max` UTF-8 bytes, marker included — never more. The bytes are cut on
+ * the Buffer and the cut moves back to a character boundary (never half a character); a cut text
+ * ends with a newline and {@link TRUNCATED_MARKER}. When `max` is too small for that marker, the
+ * part's text is dropped for {@link SHORT_MARKER} (or for nothing, when even that does not fit).
+ * A text that fits is returned as it is.
+ * @param {string} text @param {number} max @returns {string}
+ */
+export function capBytes(text, max) {
+  const bytes = Buffer.from(text, 'utf8');
+  if (bytes.length <= max) return text;
+  const tail = `\n${TRUNCATED_MARKER}`;
+  const tailBytes = Buffer.byteLength(tail);
+  if (max < tailBytes) return max >= Buffer.byteLength(SHORT_MARKER) ? SHORT_MARKER : '';
+  let end = max - tailBytes;
+  // a UTF-8 continuation byte (10xxxxxx) never starts a character: step back to the lead byte
+  while (end > 0 && (bytes[end] & 0xc0) === 0x80) end -= 1;
+  return `${bytes.subarray(0, end).toString('utf8')}${tail}`;
+}
+
+/** The free-text fields of a finding the packet shows. */
+const FIELDS = /** @type {const} */ (['claim', 'evidence', 'fix']);
+
+/**
+ * The packet: the findings, the source lines around each, and the answering file's change — all
+ * from the bytes `reviewAnswers` read and hashed. Neither file may be secret-like (both refused the
+ * same way: `packet-unreadable`). B79: the WHOLE packet stays within the budget (`full_in` × 4
+ * bytes). Its fixed text (headings, labels, fences) is counted first — over the budget alone it is
+ * {@link PacketTooLarge}. Of the room left, the findings get half — per finding, each of claim,
+ * evidence and fix a fifth of its share and the source excerpt the rest — and the answering file's
+ * change what the findings leave. Each part is redacted BEFORE it is cut (a secret is never cut
+ * into a prefix redaction misses), and cut by {@link capBytes}: one marker per cut part, never over
+ * its cap. The fixed text is redacted before it is measured, so the joined packet is never cut: it
+ * ends with the change's closing fence. A joined packet redaction would still change (a secret
+ * across a part boundary) is refused, never cut — `packet-unreadable`.
+ * @param {{ticket: AnswersTicket, ctx: AnswersContext, rows: Array<Record<string, any>>, root: string, entry: {base: string | null}, open: Map<string, unknown>, io: AnswersIo, ids: string[], srcBytes: Buffer, byBytes: Buffer, workDir: string}} opts
+ * @returns {Promise<string>}
+ */
+async function packetText({ ticket, ctx, rows, root, entry, open, io, ids, srcBytes, byBytes, workDir }) {
+  const source = ticket.file;
+  const byFile = /** @type {string} */ (ticket.by_file);
+  if (isSecretLike(assertPacketPath(root, source))) throw new Error('secret-like path');
+  const details = findingDetails({ ticket, ctx, rows, root, io });
+  const lines = srcBytes.toString('utf8').split('\n');
+  const diff = await answeringChange({ root, file: byFile, base: entry.base, bytes: byBytes, workDir });
+  const limit = budgetFor(ctx.cfg, 'full_in') * 4;
+  // each finding: its fixed lines, and its free text (null: not recorded) and source excerpt (null: none)
+  const findings = ids.map((id) => {
+    const f = details.get(id) ?? null;
+    const start = Number.isInteger(f?.line_start) ? /** @type {number} */ (f?.line_start) : null;
+    const end = Number.isInteger(f?.line_end) ? /** @type {number} */ (f?.line_end) : start;
+    // the fixed text is redacted before it is measured: the joined packet never grows past its count
+    const head = [`## Finding ${id}`, '', `- file: ${source}`, `- lines: ${start === null ? 'unknown' : `${start}-${end}`}`, `- severity: ${String(f?.severity ?? open.get(id) ?? 'unknown')}`].map(redact);
+    /** @type {Record<typeof FIELDS[number], string | null>} */
+    const text = { claim: null, evidence: null, fix: null };
+    for (const k of FIELDS) text[k] = typeof f?.[k] === 'string' ? redact(f[k]) : null;
+    /** @type {{label: string, text: string} | null} */
+    let excerpt = null;
+    // a range recorded backwards (start after end) shows no lines, whatever the lines around it
+    if (start !== null && end !== null && start <= end && lines.length > 0) {
+      const from = Math.max(1, start - AROUND);
+      const to = Math.min(lines.length, end + AROUND);
+      // a recorded range past the end of the source, or a backwards one, shows no lines
+      if (from <= to) excerpt = { label: redact(`Source lines ${from}-${to}:`), text: redact(lines.slice(from - 1, to).map((l, i) => `${from + i}: ${l}`).join('\n')) };
+    }
+    return { head, text, excerpt };
+  });
+  const intro = [
+    '# Answered findings',
+    '',
+    `A review of \`${source}\` left the findings below open. The coder says the change in \`${byFile}\` resolves them.`,
+    'For EACH finding id, decide whether that change resolves it: `resolved` only when the change clearly removes the problem the finding names; otherwise `not_resolved`. Give a short reason for each.',
+    'Reply with ONE JSON object: {"verdicts": [{"id": string, "verdict": "resolved" | "not_resolved", "reason": string}]}, one entry per id below.',
+    '',
+  ].map(redact);
+  const changeHead = [`## The change in ${byFile}`, '', diff.kind === 'new' ? '(a new file: its full content)' : `(its diff against the block base)`, '```'].map(redact);
+  /**
+   * The packet with these part texts (`parts[i]`: finding i's fields and excerpt) and change.
+   * @param {Array<{claim: string, evidence: string, fix: string, excerpt: string}>} parts @param {string} change
+   */
+  const render = (parts, change) => {
+    const out = [...intro];
+    findings.forEach((f, i) => {
+      out.push(...f.head);
+      for (const k of FIELDS) out.push(`- ${k}: ${f.text[k] === null ? '(not recorded)' : parts[i][k]}`);
+      out.push('');
+      if (f.excerpt !== null) out.push(f.excerpt.label, '```', parts[i].excerpt, '```', '');
+    });
+    out.push(...changeHead, change, '```', '');
+    return out.join('\n');
+  };
+  const fixed = Buffer.byteLength(render(findings.map(() => ({ claim: '', evidence: '', fix: '', excerpt: '' })), ''));
+  if (fixed > limit) throw new PacketTooLarge('the packet fixed text is over the budget');
+  const share = Math.floor((limit - fixed) / 2 / Math.max(1, findings.length));
+  const textCap = Math.floor(share / 5);
+  const sourceCap = share - FIELDS.length * textCap;
+  const parts = findings.map((f) => ({
+    claim: capBytes(f.text.claim ?? '', textCap),
+    evidence: capBytes(f.text.evidence ?? '', textCap),
+    fix: capBytes(f.text.fix ?? '', textCap),
+    excerpt: capBytes(f.excerpt?.text ?? '', sourceCap),
+  }));
+  // the change gets what the fixed text and the findings leave
+  const used = Buffer.byteLength(render(parts, ''));
+  const packet = render(parts, capBytes(redact(diff.text), limit - used));
+  // every piece is redacted and counted: the packet is never cut here, only refused (fail closed)
+  if (Buffer.byteLength(packet) > limit) throw new PacketTooLarge('the packet is over the budget');
+  if (redact(packet) !== packet) throw new Error('a secret across a part boundary');
+  return packet;
+}
+
+/**
+ * The open findings' details from the source's signed fix-loop state (read only, never moved or
+ * restored here). A state that does not load gives none: the packet then names id and severity.
+ * @param {{ticket: AnswersTicket, ctx: AnswersContext, rows: Array<Record<string, any>>, root: string, io: AnswersIo}} opts
+ * @returns {Map<string, Record<string, any>>}
+ */
+function findingDetails({ ticket, ctx, rows, root, io }) {
+  /** @type {Map<string, Record<string, any>>} */
+  const out = new Map();
+  try {
+    const loaded = io.loadState({ runRootDir: ctx.runRootDir, runId: ctx.runId, block: ticket.block, file: ticket.file, key: /** @type {Buffer} */ (ctx.key), rows, contentRoot: root, migrate: false });
+    if (loaded.status !== 'ok' && loaded.status !== 'restored') return out;
+    for (const f of [...(loaded.state?.open ?? []), ...(loaded.state?.late ?? [])]) if (typeof f?.id === 'string' && !out.has(f.id)) out.set(f.id, f);
+  } catch {
+    // no details: id and severity only
+  }
+  return out;
+}

package/src/review/deletion.mjs

@@ -0,0 +1,106 @@
+/**
+ * The deletion note (block B74, issue #8): a packet for a pure deletion (the file is gone from the
+ * reviewed tree, its diff is all `-` lines) gets a `## deleted file` section before the diff. It
+ * says the file is deleted and lists the tree paths that still name the file's basename, so the
+ * reviewer checks for dangling references.
+ *
+ * The reviewed tree is the working tree the review engine diffs (`reviewFile`'s `repoRoot`: the
+ * block's worktree, or the main tree), never a commit: the paths come from ONE
+ * `git grep -l -z --untracked -F -e <basename> -- .` run with that tree as cwd (argv only, the
+ * review git env `reviewGitEnv`: no inherited `GIT_*` variable, `GIT_CONFIG_NOSYSTEM=1`,
+ * `GIT_CONFIG_GLOBAL` the null device, `GIT_LITERAL_PATHSPECS=1`). `--untracked` adds the files a
+ * block created and has not committed yet (never ignored ones). The list is sorted, never names the
+ * deleted path itself or a secret-like path (`isSecretLike`), and stops at {@link MAX_REFERENCES}
+ * paths; a path with a control character (it could break the packet layout) is never printed, only
+ * counted with the paths past the cap (`(<n> more not listed)`). No match ⇒ `no references found`.
+ * A basename shorter than {@link MIN_BASENAME} characters is not grepped, nor is a deleted path
+ * with a control character (it is printed JSON-escaped), and a grep that fails (or times out) is
+ * not trusted: all say `references not checked`. The note is a hint, never an exemption: a
+ * deletion is reviewed and needs a signed approval like any other change (a grep cannot prove that
+ * nothing depends on a file).
+ */
+
+import path from 'node:path';
+import { exec } from '../util/exec.mjs';
+import { isSecretLike, reviewGitEnv } from './packet.mjs';
+
+/** At most this many referencing paths are listed. */
+export const MAX_REFERENCES = 20;
+
+/** A basename shorter than this matches too much to be a useful hint: it is not grepped. */
+export const MIN_BASENAME = 3;
+
+export const NO_REFERENCES = 'no references found';
+export const NOT_CHECKED = 'references not checked';
+
+const GREP_TIMEOUT_MS = 30000;
+
+const CONTROL = /[\x00-\x1f\x7f]/;
+
+/** @param {string} p @returns {boolean} whether `p` has a control character. */
+const hasControl = (p) => CONTROL.test(p);
+
+/**
+ * @typedef {object} References
+ * @property {'found' | 'none' | 'not_checked'} status
+ * @property {string[]} paths - sorted, at most {@link MAX_REFERENCES}.
+ * @property {number} more - matching paths not listed: past the cap, or with a control character.
+ */
+
+/** @type {References} */
+const NOT_CHECKED_REFS = Object.freeze({ status: 'not_checked', paths: [], more: 0 });
+
+/**
+ * The paths of the reviewed tree (`repoRoot`, the grep's cwd) that still name `file`'s basename.
+ * @param {{repoRoot: string, file: string, run?: typeof exec}} opts - `run`: the child runner
+ *   (default `exec`; a test seam).
+ * @returns {Promise<References>}
+ */
+export async function findReferences({ repoRoot, file, run = exec }) {
+  const base = path.posix.basename(file);
+  if (base.length < MIN_BASENAME || hasControl(file)) return { ...NOT_CHECKED_REFS, paths: [] };
+  let res;
+  try {
+    res = await run(['git', 'grep', '-l', '-z', '--untracked', '-F', '-e', base, '--', '.'], { cwd: repoRoot, env: reviewGitEnv(), timeoutMs: GREP_TIMEOUT_MS, okExitCodes: [0, 1] });
+  } catch {
+    return { ...NOT_CHECKED_REFS, paths: [] };
+  }
+  if (res?.result !== 'ok' || (res.code !== 0 && res.code !== 1) || typeof res.stdout !== 'string') return { ...NOT_CHECKED_REFS, paths: [] };
+  const matched = [...new Set(res.stdout.split('\0').filter((p) => p.length > 0 && p !== file && !isSecretLike(p)))];
+  const unsafe = matched.filter(hasControl).length;
+  const clean = matched.filter((p) => !hasControl(p)).sort();
+  if (clean.length === 0 && unsafe === 0) return { status: 'none', paths: [], more: 0 };
+  return { status: 'found', paths: clean.slice(0, MAX_REFERENCES), more: Math.max(0, clean.length - MAX_REFERENCES) + unsafe };
+}
+
+/**
+ * The `## deleted file` section (heading included) for a deleted `file`. A name with a control
+ * character is printed JSON-escaped, never raw.
+ * @param {string} file @param {References} refs @returns {string}
+ */
+export function renderDeletionNote(file, refs) {
+  const shown = hasControl(file) ? JSON.stringify(file) : file;
+  const out = ['## deleted file', `this file is deleted: ${shown}`, `check that nothing still depends on it. tree paths that still name ${JSON.stringify(path.posix.basename(file))}:`];
+  if (refs.status === 'not_checked') out.push(NOT_CHECKED);
+  else if (refs.status === 'none') out.push(NO_REFERENCES);
+  else {
+    out.push(...refs.paths.map((p) => `- ${p}`));
+    if (refs.more > 0) out.push(`(${refs.more} more not listed)`);
+  }
+  return out.join('\n');
+}
+
+/**
+ * The deletion note for `file`, its references read in `repoRoot` (the reviewed tree). Never
+ * rejects: anything that fails is `references not checked`.
+ * @param {{repoRoot: string, file: string, run?: typeof exec}} opts @returns {Promise<string>}
+ */
+export async function deletionNote(opts) {
+  let refs;
+  try {
+    refs = await findReferences(opts);
+  } catch {
+    refs = NOT_CHECKED_REFS;
+  }
+  return renderDeletionNote(opts.file, refs);
+}

package/src/review/engine.mjs

@@ -40,12 +40,15 @@
  *     (`moved.mjs`, B56). The peers' diffs are read once per review (`input.peerDiffs`, or a
  *     reader built from `input.peers`). It is extra text: every hunk still goes to the reviewer,
  *     and it counts toward the budget in the same measure.
+ *  9. a pure deletion (the file is gone from the reviewed tree) gets a `## deleted file` note in
+ *     every packet — reviewers and judge — naming up to 20 tree paths that still name its basename
+ *     (`deletion.mjs`, B74). It is a hint, never an exemption: the deletion still needs approval.
  * Approval (until B12b's triage lands) = the final answer (the judge's in dual/consensus mode, else
  * the single reviewer's) passed the guard, says `passed: true`, and carries no `critical` or
  * `warning` finding.
  */
 
-import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { lstatSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { randomBytes } from 'node:crypto';
 import path from 'node:path';
 import { resolveLevel } from '../config/known-ids.mjs';
@@ -55,6 +58,7 @@ import { isMigrationPath, isPolicyPath } from '../decide/lane-facts.mjs';
 import { tierFor } from '../proof/tiers.mjs';
 import { assembleJudgePacket, assemblePacket, attachFiles, budgetFor, diffOnlyTokens, readFileDiff } from './packet.mjs';
 import { movedText, movesFor, peerDiffReader } from './moved.mjs';
+import { deletionNote, renderDeletionNote } from './deletion.mjs';
 import { isMarkdownFile, packSections, sectionFindings, sectionGroups } from './sections.mjs';
 import { FINDING_SCHEMA, minTokensOut, validateReview } from './validate-review.mjs';
 import { spawnWithTimeoutRetry } from './session-retry.mjs';
@@ -182,6 +186,8 @@ export function rulesRisk({ file, plusCount, cfg }) {
  * @property {(row: Record<string, any>) => Promise<unknown>} [writeRow] - ledger rows
  *   (`review.plan`, `review.unavailable`, `review.schema_invalid`, `review.schema_fallback`); a
  *   failed write never fails the review (a failed `review.schema_fallback` write means no try).
+ * @property {(opts: {repoRoot: string, file: string}) => Promise<string>} [deletionNote] - B74: the
+ *   deletion note reader (default `deletionNote`, `deletion.mjs`); a throw gives `references not checked`.
  * @property {import('./schema-fallback.mjs').SchemaHistory} [schemaHistory] - B55: the packet's
  *   signed schema-miss history (the worker's); absent ⇒ no second-level try.
  */
@@ -233,8 +239,22 @@ export async function reviewFile(input, deps) {
   } catch {
     moves = null; // no hint; the review goes on
   }
+  // B74: a pure deletion gets the `## deleted file` note in every packet, read once; it is extra
+  // text like the moved code, counted in the same measure. "Deleted" is explicit: the diff is not
+  // empty (checked above), the reader found no content (`readFileDiff` gives null ONLY for a path
+  // not on disk: a binary file is decoded text, an unreadable one throws) AND the path is absent
+  // from the reviewed tree now. The references are read in that same tree (`repoRoot`).
+  let deleted = '';
+  if (diff.content === null && isAbsent(repoRoot, diff.file)) {
+    const note = deps.deletionNote ?? deletionNote;
+    try {
+      deleted = await note({ repoRoot, file: diff.file });
+    } catch {
+      deleted = renderDeletionNote(diff.file, { status: 'not_checked', paths: [], more: 0 }); // the review goes on
+    }
+  }
   /** @param {ReadonlyArray<number> | null} keys - a Markdown section's group keys; null ⇒ the whole file. */
-  const movedOf = (keys) => movedText(moves, diff.content, keys);
+  const movedOf = (keys) => [deleted, movedText(moves, diff.content, keys)].filter((t) => typeof t === 'string' && t.length > 0).join('\n');
   const min = minTokensOut(cfg);
   // B55: never in consensus mode — its providers (two reviewers, the judge) are the check itself
   const schemaFallback = plan.mode !== 'consensus';
@@ -466,6 +486,20 @@ async function runOne(spec, text, packet, { deps, workDir, min, cfg, schemaFallb
   return { ...meta, status: 'ok', reason: null, review: verdict.review };
 }
 
+/**
+ * B74: whether `file` is absent from the tree at `repoRoot` (lstat says ENOENT or ENOTDIR).
+ * @param {string} repoRoot @param {string} file @returns {boolean}
+ */
+function isAbsent(repoRoot, file) {
+  try {
+    lstatSync(path.join(repoRoot, file));
+    return false;
+  } catch (err) {
+    const code = /** @type {NodeJS.ErrnoException} */ (err).code;
+    return code === 'ENOENT' || code === 'ENOTDIR';
+  }
+}
+
 /**
  * Two token counts added; a missing one (not a number) adds nothing, both missing ⇒ null.
  * @param {unknown} a @param {unknown} b @returns {number | null}