@codedology/code-forge 0.9.0 → 0.11.0

package/src/review/fixloop.mjs

@@ -93,11 +93,12 @@ import { contentHash, gitChildEnv } from '../worker/ticket.mjs';
 import { parseDiff } from './context.mjs';
 import { assemblePacket, assertPacketPath, diffOnlyTokens, readFileDiff } from './packet.mjs';
 import { movedText, movesFor, peerDiffReader } from './moved.mjs';
+import { pairedContext } from './engine.mjs';
 import { isMarkdownFile, packSections, sectionFindings, sectionGroups, sectionOf } from './sections.mjs';
 import { cameFromJudge, resolvedBand, triageFindings } from './triage.mjs';
 import { FINDING_SCHEMA, minTokensOut, validateReview } from './validate-review.mjs';
 import { spawnWithTimeoutRetry } from './session-retry.mjs';
-import { afterSchemaMiss, logSecondLevelMiss } from './schema-fallback.mjs';
+import { afterSchemaMiss, logSecondLevelMiss, packetHash } from './schema-fallback.mjs';
 
 /** @typedef {import('./triage.mjs').Finding} Finding */
 /** @typedef {import('./context.mjs').Hunk} Hunk */
@@ -144,6 +145,9 @@ import { afterSchemaMiss, logSecondLevelMiss } from './schema-fallback.mjs';
  * @property {(req: {file: string, level: 'L3', open: Finding[]}) => Promise<unknown>} [patch] - the L3 patch rung (≤ 80 lines, owned files only).
  * @property {string | null} [base] - the block base (`recheck_scope: file`, and the B56 moved-code diff).
  * @property {ReadonlyArray<string>} [peers] - B56: the block's other changed files (moved-code hints).
+ * @property {ReadonlyArray<string>} [ownedFiles] - concrete paths owned by this block.
+ * @property {ReadonlyArray<string>} [changedFiles] - concrete changed paths of the same block.
+ * @property {ReadonlyArray<string>} [testFiles] - the block's explicit test_files.
  * @property {() => Promise<import('./moved.mjs').PeerDiff[]>} [peerDiffs] - B56: a memoised reader of their diffs (`peerDiffReader`); wins over `peers`.
  * @property {string} [rulesDigest] @property {string} [factsExcerpt]
  * @property {number} [extraRounds] - B47: rounds past `review.max_rounds_per_file` granted by autopilot (`extraRoundsFor`).
@@ -362,11 +366,11 @@ export function recheckTokens(diff, open, moved = '') {
 /**
  * The recheck packet: the `recheck` lens on the fix hunks (hunk form, never the whole file), then
  * the open findings by id. Over budget ⇒ `minimal` (see the module doc).
- * @param {{diff: import('./packet.mjs').FileDiff, open: Finding[], cfg?: Record<string, any>, contextMode?: 'auto' | 'recheck', rulesDigest?: string, factsExcerpt?: string, moved?: string}} opts -
+ * @param {{diff: import('./packet.mjs').FileDiff, open: Finding[], cfg?: Record<string, any>, contextMode?: 'auto' | 'recheck', rulesDigest?: string, factsExcerpt?: string, moved?: string, paired?: string}} opts -
  *   `moved`: the file's `## moved code` section (B56), '' for none.
  */
-export function buildRecheckPacket({ diff, open, cfg, contextMode = 'recheck', rulesDigest, factsExcerpt, moved = '' }) {
-  const packet = assemblePacket({ diff, lens: 'recheck', cfg, contextMode, rulesDigest, factsExcerpt, moved });
+export function buildRecheckPacket({ diff, open, cfg, contextMode = 'recheck', rulesDigest, factsExcerpt, moved = '', paired = '' }) {
+  const packet = assemblePacket({ diff, lens: 'recheck', cfg, contextMode, rulesDigest, factsExcerpt, moved, paired });
   if (packet.status !== 'ok') return packet;
   const text = `${packet.text}${openFindingsText(open)}`;
   return { ...packet, text, tokensIn: packet.tokensIn + Math.ceil(Buffer.byteLength(text.slice(packet.text.length)) / 4) };
@@ -431,25 +435,49 @@ export function insideHunks(f, hunks) {
 }
 
 /**
- * One recheck session through the stub guard — and, on a `schema` miss, the B55 second-level try
- * on the same packet (`schema-fallback.mjs`; rechecks and the patch_check alike).
+ * One recheck session through the stub guard — and, on a `schema` miss or (B91) a timed-out
+ * attempt that is the packet's second broken result, the B55 second-level try on the same packet
+ * (`schema-fallback.mjs`; rechecks and the patch_check alike).
  * @param {{text: string, hunkHeaders: string[], tokensIn: number, contextMode: string}} packet
  * @param {LoopDeps} deps
+ * @param {ReadonlyArray<Finding>} open - only the findings listed in this packet.
  */
-async function recheckSession(packet, deps) {
+async function recheckSession(packet, deps, open) {
   mkdirSync(deps.workDir, { recursive: true, mode: 0o700 });
   const promptPath = path.join(deps.workDir, `recheck-${randomBytes(6).toString('hex')}.md`);
   writeFileSync(promptPath, packet.text, { mode: 0o600 });
   const min = minTokensOut(deps.cfg);
+  /** @param {Record<string, any> | null} result @returns {import('./validate-review.mjs').Verdict} */
+  const validate = (result) => {
+    const verdict = validateReview(result, { hunkHeaders: packet.hunkHeaders, minTokensOut: min });
+    if (!verdict.ok) return verdict;
+    const ids = new Set((verdict.review?.resolved ?? []).map((/** @type {{id: string}} */ entry) => entry.id));
+    if (open.some((finding) => !ids.has(finding.id))) return { ok: false, reason: 'schema', detail: 'resolved does not cover the packet open findings' };
+    return verdict;
+  };
   const session = { lens: 'recheck', role: 'reviewer', level: 'L2' };
-  /** @param {Record<string, any> | undefined} cfg */
+  // no ledger writer ⇒ nothing logged, nothing tried; every row goes through the same writer
+  // (each helper handles its own failed write)
+  const write = deps.writeRow ? (/** @type {Record<string, any>} */ row) => /** @type {NonNullable<LoopDeps['writeRow']>} */ (deps.writeRow)(row) : undefined;
+  const hash = packetHash(packet.text);
+  /** @param {Record<string, any> | null} missed @param {'schema' | 'timeout'} trigger */
+  const tryNext = (missed, trigger) =>
+    afterSchemaMiss({ res: missed, session, packetText: packet.text, cfg: deps.cfg ?? {}, allowed: true /* rechecks are never consensus; the budget gate is inside the spawn */, history: deps.schemaHistory, writeRow: write, spawnAt: attempt, trigger });
+  /**
+   * @param {Record<string, any> | undefined} cfg - set only for the second-level try (B91: its
+   *   timeouts never count and never try again).
+   * @returns {Promise<{res: Record<string, any> | null, attempts: number, to?: Record<string, any>, broken?: Record<string, any>}>}
+   */
   const attempt = async (cfg) =>
     deps.spawn
-      ? // a `timeout` is spawned once more on the same packet and level (B30)
+      ? // a `timeout` is spawned once more on the same packet and level (B30); B91: the packet's
+        // second broken result tries the second level instead
         spawnWithTimeoutRetry(
           deps.spawn,
           { level: 'L2', role: 'reviewer', promptPath, schema: FINDING_SCHEMA, rowExtra: { lens: 'recheck', context_mode: packet.contextMode, ctx_tokens_in: packet.tokensIn }, ...(cfg ? { cfg } : {}) },
           (row) => note(deps, row),
+          undefined,
+          cfg ? { packetHash: hash, secondLevel: true } : { packetHash: hash, onBroken: (r) => tryNext(r, 'timeout') },
         )
       : { res: null, attempts: 0 };
   /** @type {Record<string, any> | null} */
@@ -462,23 +490,40 @@ async function recheckSession(packet, deps) {
   let tokensOut = null;
   // the packet file is removed on every path, and only after the second-level try (which reads it)
   try {
+    /** @type {{res: Record<string, any> | null, attempts: number, to?: Record<string, any>, broken?: Record<string, any>} | null} */
+    let first = null;
     try {
-      res = (await attempt(undefined)).res;
+      first = await attempt(undefined);
+      res = first.res;
     } catch {
       res = null; // the helper never throws; if it ever did, it is still an `exit` failure
     }
-    tokensIn = res?.usage?.tokens_in ?? null;
-    tokensOut = res?.usage?.tokens_out ?? null;
-    verdict = validateReview(res, { hunkHeaders: packet.hunkHeaders, minTokensOut: min });
-    if (!verdict.ok && verdict.reason === 'schema') {
+    verdict = validate(res);
+    if (first?.to) {
+      // B91: a timed-out attempt was the packet's second broken result; the second level ran. The
+      // verdict is already set: whatever throws after it leaves that verdict, never an exception
+      // the second level's miss is logged first, in its own try, so no sum error can skip it
       try {
-        // no ledger writer ⇒ nothing logged, nothing tried; every row goes through the same writer
-        // (each helper handles its own failed write)
-        const write = deps.writeRow ? (/** @type {Record<string, any>} */ row) => /** @type {NonNullable<LoopDeps['writeRow']>} */ (deps.writeRow)(row) : undefined;
-        const second = await afterSchemaMiss({ res, session, packetText: packet.text, cfg: deps.cfg ?? {}, allowed: true /* rechecks are never consensus; the budget gate is inside the spawn */, history: deps.schemaHistory, writeRow: write, spawnAt: attempt });
+        if (!verdict.ok && verdict.reason === 'schema') await logSecondLevelMiss({ res, session, packetText: packet.text, writeRow: write });
+      } catch {
+        // defensive only: the helper never throws; the verdict above stands (never approval)
+      }
+      try {
+        tokensIn = sum(first.broken?.usage?.tokens_in ?? null, res?.usage?.tokens_in);
+        tokensOut = sum(first.broken?.usage?.tokens_out ?? null, res?.usage?.tokens_out);
+      } catch {
+        // defensive only, as on the schema path below
+      }
+    } else {
+      tokensIn = res?.usage?.tokens_in ?? null;
+      tokensOut = res?.usage?.tokens_out ?? null;
+    }
+    if (!first?.to && !verdict.ok && verdict.reason === 'schema') {
+      try {
+        const second = await tryNext(res, 'schema');
         if (second) {
           // compute everything first, then assign together, so a throw never leaves a mixed state
-          const secondVerdict = validateReview(second.res, { hunkHeaders: packet.hunkHeaders, minTokensOut: min });
+          const secondVerdict = validate(second.res);
           const sumIn = sum(tokensIn, second.res?.usage?.tokens_in);
           const sumOut = sum(tokensOut, second.res?.usage?.tokens_out);
           res = second.res;
@@ -632,6 +677,11 @@ export async function runRound(state, deps, opts = {}) {
       s.scope === 'file'
         ? await readFileDiff({ repoRoot: deps.repoRoot, file: current.rel, base: deps.base ?? null })
         : await fixHunkDiff({ file: current.rel, previous: state.reviewed_content ?? '', current: current.content, workDir: deps.workDir });
+    if (kind === 'recheck' && (current.content === state.reviewed_content || diff.hunks.length === 0)) {
+      state.next = { action: 'fix', level: state.level, trigger: null, reason: 'no-fix-hunks' };
+      state.pending_kind = null;
+      return state;
+    }
     if (diff.hunks.length > 0) {
       /** @type {Finding[]} */
       const pending = [];
@@ -644,7 +694,8 @@ export async function runRound(state, deps, opts = {}) {
       if (pending.length > 0) {
         const contextMode = s.scope === 'file' ? 'auto' : 'recheck';
         const moves = await recheckMoves(deps, current.rel, s.scope === 'file' ? diff : null);
-        const whole = buildRecheckPacket({ diff, open: pending, cfg: deps.cfg, contextMode, rulesDigest: deps.rulesDigest, factsExcerpt: deps.factsExcerpt, moved: movedText(moves, diff.content, null) });
+        const paired = pairedContext({ ...deps, file: current.rel });
+        const whole = buildRecheckPacket({ diff, open: pending, cfg: deps.cfg, contextMode, rulesDigest: deps.rulesDigest, factsExcerpt: deps.factsExcerpt, moved: movedText(moves, diff.content, null), paired });
         /** @type {Array<{index: number | null, heading: string | null, diff: import('./packet.mjs').FileDiff, open: Finding[], keys: number[] | null}>} */
         let parts = [{ index: null, heading: null, diff, open: pending, keys: null }];
         if (whole.status !== 'ok') {
@@ -665,7 +716,7 @@ export async function runRound(state, deps, opts = {}) {
             continue;
           }
           const moved = movedText(moves, diff.content, part.keys);
-          const packet = buildRecheckPacket({ diff: part.diff, open: part.open, cfg: deps.cfg, contextMode, rulesDigest: deps.rulesDigest, factsExcerpt: deps.factsExcerpt, moved });
+          const packet = buildRecheckPacket({ diff: part.diff, open: part.open, cfg: deps.cfg, contextMode, rulesDigest: deps.rulesDigest, factsExcerpt: deps.factsExcerpt, moved, paired });
           // a packet that fails to build stops with ITS status (and size, when it has one)
           if (packet.status !== 'ok') return stopBeforeRound(state, deps, kind, current.rel, { ...packet, section: part.heading });
           const size = recheckTokens(part.diff, part.open, moved);
@@ -681,7 +732,7 @@ export async function runRound(state, deps, opts = {}) {
         for (const [i, part] of parts.entries()) {
           const packet = /** @type {any} */ (built[i]);
           packetInfo = mergePacketInfo(packetInfo, packet);
-          const session = await recheckSession(packet, deps);
+          const session = await recheckSession(packet, deps, part.open);
           tokensIn = sum(tokensIn, session.tokens_in);
           tokensOut = sum(tokensOut, session.tokens_out);
           if (!session.verdict.ok) {
@@ -711,7 +762,7 @@ export async function runRound(state, deps, opts = {}) {
         draft.open = [...stillOpen, ...triaged.fix_now, ...blocking];
       }
     }
-    // no fix hunks (the content did not change): nothing closes — the round stalls
+    // A patch_check with no fix hunks closed nothing: B73 still stops it.
   }
 
   if (kind !== 'patch_check') {
@@ -796,6 +847,7 @@ export async function converge(state, deps) {
     }
     await deps.fix?.({ file: state.file, round: state.round + 1, level: state.level, open: [...state.open], l3_patch: state.l3_rung_used });
     await runRound(state, deps);
+    if (state.next?.reason === 'no-fix-hunks') return state;
   }
   return state;
 }

package/src/review/gate-check.mjs

@@ -93,6 +93,7 @@ import { tierFor } from '../proof/tiers.mjs';
 import { DELETED_HASH, contentHash, gitChildEnv } from '../worker/ticket.mjs';
 import { verifyResult } from '../worker/queue.mjs';
 import { stopExitsLine } from './stop-exits.mjs';
+import { checkFileForm, checkFindingId } from './verb-forms.mjs';
 
 /**
  * @typedef {{file: string, content_hash: string, status: 'reviewed_by_waiver', findings: string[], by: 'human' | 'autopilot' | null, answered?: string[]}} WaivedAll
@@ -1055,10 +1056,10 @@ export function reviewGateCheck(load, { onWaivedAll } = {}) {
  * @returns {Promise<Record<string, any>>} the signed row.
  */
 export async function waiveFinding({ runId, id, finding, reason, file, writeRow }) {
-  if (typeof finding !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$/.test(finding)) throw new StateError('usage', 'a finding id is required (letters, digits, . _ : -)');
+  checkFindingId(finding);
   if (typeof reason !== 'string' || reason.trim().length === 0) throw new StateError('usage', 'block waive needs --reason');
   if (typeof file !== 'string' || file.length === 0) throw new StateError('usage', 'block waive needs --file <path>');
-  if (path.isAbsolute(file) || file.split('/').includes('..') || file.startsWith('./')) throw new StateError('usage', '--file must be repo-root-relative');
+  checkFileForm(file, { normalized: false });
   const record = await readRun(runId);
   if (!record.blocks?.[id]) throw new StateError('unknown_block', `block ${id} is not in run ${runId}`);
   const row = { event: 'review.waived', block: id, file, finding, reason: reason.trim(), by: 'human' };

package/src/review/lenses/A.md

@@ -14,9 +14,11 @@ You work blind: you do not see the other reviewer's answer.
 ## Rules for every answer
 
 - Judge only what is in the packet; if you need a file you cannot see, return it in `needs_file` instead of guessing.
+- A test named in `## paired` exists; do not report it as unseen; use `needs_file` when its body matters.
 - You have no tools and no project files. The packet is everything you get.
 - `reviewed_hunks`: copy every `@@ … @@` hunk header listed under "hunks" in the packet, exactly and in the same order. A review whose `reviewed_hunks` does not match is discarded.
 - Answer with ONE JSON object that matches the answer schema: `passed`, `summary` (≤ 300 chars), `reviewed_hunks`, `findings[]`, and `needs_file[]` (empty when you need nothing).
 - Every finding names `file`, `line_start`, `line_end` (line numbers of the CURRENT file, as numbered in the context), `severity` (`critical` = wrong behaviour, data loss, security; `warning` = a real defect that is not critical; `nit` = style or preference), a short `category`, the `claim`, the `evidence` you read in the packet, and the `fix`. Each of `claim`, `evidence`, `fix` ≤ 300 chars.
 - `passed` is true only when you found no `critical` and no `warning`.
 - Do not invent a problem to look thorough. An empty `findings` list is a valid answer.
+- A `## test-quality` section names lines of a test that reads a source file and asserts on its text. Check those lines: such a test is a `warning` with the claim "test reads source text; prove behaviour instead", unless the read file is a fixture. The section is a hint, not a finding.

package/src/review/lenses/B.md

@@ -15,9 +15,11 @@ You work blind: you do not see the other reviewer's answer.
 ## Rules for every answer
 
 - Judge only what is in the packet; if you need a file you cannot see, return it in `needs_file` instead of guessing.
+- A test named in `## paired` exists; do not report it as unseen; use `needs_file` when its body matters.
 - You have no tools and no project files. The packet is everything you get.
 - `reviewed_hunks`: copy every `@@ … @@` hunk header listed under "hunks" in the packet, exactly and in the same order. A review whose `reviewed_hunks` does not match is discarded.
 - Answer with ONE JSON object that matches the answer schema: `passed`, `summary` (≤ 300 chars), `reviewed_hunks`, `findings[]`, and `needs_file[]` (empty when you need nothing).
 - Every finding names `file`, `line_start`, `line_end` (line numbers of the CURRENT file, as numbered in the context), `severity` (`critical` = wrong behaviour, data loss, security; `warning` = a real defect that is not critical; `nit` = style or preference), a short `category`, the `claim`, the `evidence` you read in the packet, and the `fix`. Each of `claim`, `evidence`, `fix` ≤ 300 chars.
 - `passed` is true only when you found no `critical` and no `warning`.
 - Do not invent a problem to look thorough. An empty `findings` list is a valid answer.
+- A `## test-quality` section names lines of a test that reads a source file and asserts on its text. Check those lines: such a test is a `warning` with the claim "test reads source text; prove behaviour instead", unless the read file is a fixture. The section is a hint, not a finding.

package/src/review/lenses/full.md

@@ -15,9 +15,11 @@ Report each real defect once, at the lines where it lives.
 ## Rules for every answer
 
 - Judge only what is in the packet; if you need a file you cannot see, return it in `needs_file` instead of guessing.
+- A test named in `## paired` exists; do not report it as unseen; use `needs_file` when its body matters.
 - You have no tools and no project files. The packet is everything you get.
 - `reviewed_hunks`: copy every `@@ … @@` hunk header listed under "hunks" in the packet, exactly and in the same order. A review whose `reviewed_hunks` does not match is discarded.
 - Answer with ONE JSON object that matches the answer schema: `passed`, `summary` (≤ 300 chars), `reviewed_hunks`, `findings[]`, and `needs_file[]` (empty when you need nothing).
 - Every finding names `file`, `line_start`, `line_end` (line numbers of the CURRENT file, as numbered in the context), `severity` (`critical` = wrong behaviour, data loss, security; `warning` = a real defect that is not critical; `nit` = style or preference), a short `category`, the `claim`, the `evidence` you read in the packet, and the `fix`. Each of `claim`, `evidence`, `fix` ≤ 300 chars.
 - `passed` is true only when you found no `critical` and no `warning`.
 - Do not invent a problem to look thorough. An empty `findings` list is a valid answer.
+- A `## test-quality` section names lines of a test that reads a source file and asserts on its text. Check those lines: such a test is a `warning` with the claim "test reads source text; prove behaviour instead", unless the read file is a fixture. The section is a hint, not a finding.

package/src/review/lenses/quick.md

@@ -19,3 +19,4 @@ Skip style, naming and structure unless it hides a bug. Keep `findings` short.
 - Every finding names `file`, `line_start`, `line_end` (line numbers of the CURRENT file, as numbered in the context), `severity` (`critical` = wrong behaviour, data loss, security; `warning` = a real defect that is not critical; `nit` = style or preference), a short `category`, the `claim`, the `evidence` you read in the packet, and the `fix`. Each of `claim`, `evidence`, `fix` ≤ 300 chars.
 - `passed` is true only when you found no `critical` and no `warning`.
 - Do not invent a problem to look thorough. An empty `findings` list is a valid answer.
+- A `## test-quality` section names lines of a test that reads a source file and asserts on its text. Check those lines: such a test is a `warning` with the claim "test reads source text; prove behaviour instead", unless the read file is a fixture. The section is a hint, not a finding.

package/src/review/lenses/recheck.md

@@ -18,6 +18,8 @@ that changed since that round, each with a window of the current file around it.
 ## Rules for every answer
 
 - Judge only what is in the packet; if you need a file you cannot see, return it in `needs_file` instead of guessing.
+- A test named in `## paired` exists; do not report it as unseen; use `needs_file` when its body matters.
 - You have no tools and no project files. The packet is everything you get.
 - `reviewed_hunks`: copy every `@@ … @@` hunk header listed under "hunks" in the packet, exactly and in the same order.
 - Answer with ONE JSON object that matches the answer schema.
+- A `## test-quality` section names lines of a test that reads a source file and asserts on its text. Check those lines: such a test is a `warning` with the claim "test reads source text; prove behaviour instead", unless the read file is a fixture. The section is a hint, not a finding.

package/src/review/packet.mjs

@@ -10,6 +10,7 @@
  *   ## project rules   the rules digest (≤ 60 lines)
  *   ## facts           the facts-sheet excerpt
  *   ## context         the current file (whole, or hunk windows — `context.mjs`)
+ *   ## paired          optional paired-file names and summary (B97), dropped first over budget
  *   ## moved code      only when code moved to/from another file of the block (`moved.mjs`, B56)
  *   ## diff            `file:`, the `hunks:` list the reviewer must echo, then the diff
  *
@@ -20,7 +21,7 @@
  * Budget (§4.3): `review.budgets.full_in` (`quick_in` for the quick lens), in tokens estimated as
  * bytes / 4. A diff that alone exceeds it ⇒ `split_required` (a Markdown file is then reviewed
  * section by section — `sections.mjs`, B54). Otherwise over budget ⇒ the context shrinks to
- * ± `min_context_lines` (`minimal`) FIRST, then the digest is trimmed from the end; the diff is
+ * ± `min_context_lines` (`minimal`) after dropping paired, then the digest is trimmed from the end; the diff is
  * never cut. The `## moved code` section (B56) is part of that measure: it is counted in the diff-only
  * size (`diffOnlyTokens`, `split_required`) and never trimmed.
  *
@@ -190,11 +191,11 @@ export async function readFileDiff({ repoRoot, file, base }) {
  * Assemble a reviewer packet (pure).
  * @param {{
  *   diff: FileDiff, lens: string, rulesDigest?: string, factsExcerpt?: string,
- *   cfg?: Record<string, any>, contextMode?: 'auto' | 'recheck', budget?: number, moved?: string,
+ *   cfg?: Record<string, any>, contextMode?: 'auto' | 'recheck', budget?: number, moved?: string, paired?: string,
  * }} opts - `moved`: the file's `## moved code` section (`moved.mjs`), '' for none.
  * @returns {Packet | {status: 'split_required', tokensIn: number, budget: number}}
  */
-export function assemblePacket({ diff, lens, rulesDigest = '', factsExcerpt = '', cfg, contextMode = 'auto', budget, moved = '' }) {
+export function assemblePacket({ diff, lens, rulesDigest = '', factsExcerpt = '', cfg, contextMode = 'auto', budget, moved = '', paired = '' }) {
   const lensText = loadLens(lens);
   const limit = budget ?? budgetFor(cfg, lens === 'quick' ? 'quick_in' : 'full_in');
   const hunkHeaders = diff.hunks.map((h) => h.header);
@@ -204,7 +205,12 @@ export function assemblePacket({ diff, lens, rulesDigest = '', factsExcerpt = ''
 
   let digest = splitLines(rulesDigest).slice(0, DIGEST_MAX_LINES);
   let ctx = buildContext({ file: diff.file, content: diff.content, hunks: diff.hunks, cfg, mode: contextMode });
-  let text = render(lensText, digest, factsExcerpt, ctx.text, diffSection, moved);
+  let pairedSection = boundedPaired(paired, budgetFor(cfg, 'full_in'));
+  let text = render(lensText, digest, factsExcerpt, ctx.text, diffSection, moved, pairedSection);
+  if (estimateTokens(text) > limit && pairedSection.length > 0) {
+    pairedSection = '';
+    text = render(lensText, digest, factsExcerpt, ctx.text, diffSection, moved);
+  }
   if (estimateTokens(text) > limit) {
     ctx = buildContext({ file: diff.file, content: diff.content, hunks: diff.hunks, cfg, mode: 'minimal' });
     text = render(lensText, digest, factsExcerpt, ctx.text, diffSection, moved);
@@ -217,6 +223,22 @@ export function assemblePacket({ diff, lens, rulesDigest = '', factsExcerpt = ''
   return { status: 'ok', text, hunkHeaders, contextMode: ctx.mode, contextLines: ctx.lineCount, digestLines: digest.length, tokensIn, budget: limit, overBudget: tokensIn > limit };
 }
 
+/** Cap the entire section at full_in / 16 tokens, without cutting a UTF-8 character.
+ * @param {string} paired @param {number} fullIn @returns {string}
+ */
+function boundedPaired(paired, fullIn) {
+  if (paired.trim().length === 0) return '';
+  const heading = '## paired\n';
+  let left = Math.floor(fullIn / 16) * 4 - Buffer.byteLength(heading) - 1;
+  let body = '';
+  for (const char of paired) {
+    left -= Buffer.byteLength(char);
+    if (left < 0) break;
+    body += char;
+  }
+  return body.length > 0 ? heading + body.trimEnd() : '';
+}
+
 /**
  * The tokens of the diff-only packet (lens + moved code + diff, no digest, facts or context): what
  * `assemblePacket` holds against the budget before it says `split_required`. Pass the SAME `moved`
@@ -244,8 +266,9 @@ function diffSectionOf(diff) {
 /**
  * @param {string} lensText @param {string[]} digest @param {string} facts @param {string} context
  * @param {string} diffSection @param {string} [moved] - the `## moved code` section (heading included), '' for none.
+ * @param {string} [paired] - the bounded `## paired` section (heading included).
  */
-function render(lensText, digest, facts, context, diffSection, moved = '') {
+function render(lensText, digest, facts, context, diffSection, moved = '', paired = '') {
   return [
     '# code-forge review packet',
     '## lens',
@@ -256,6 +279,7 @@ function render(lensText, digest, facts, context, diffSection, moved = '') {
     facts.trim().length > 0 ? facts.trimEnd() : '(none)',
     '## context',
     context.length > 0 ? context : '(none)',
+    ...(paired.length > 0 ? [paired] : []),
     ...(moved.length > 0 ? [moved] : []),
     '## diff',
     diffSection,
@@ -319,9 +343,10 @@ function readRepoText(repoRoot, rel) {
 
 /**
  * Why `rel` may not be attached, or null.
- * @param {string} repoRoot @param {string} rel @returns {Promise<string | null>}
+ * @param {string} repoRoot @param {string} rel @param {ReadonlyArray<string>} ownedFiles
+ * @param {ReadonlyArray<string>} changedFiles @returns {Promise<string | null>}
  */
-async function attachRefusal(repoRoot, rel) {
+async function attachRefusal(repoRoot, rel, ownedFiles, changedFiles) {
   if (isSecretLike(rel)) return 'refused: secret-like path';
   let st;
   try {
@@ -330,20 +355,29 @@ async function attachRefusal(repoRoot, rel) {
     return 'missing';
   }
   if (!st.isFile()) return 'not a file';
-  const res = await exec(['git', 'ls-files', '-z', '--error-unmatch', '--', rel], { cwd: repoRoot, env: reviewGitEnv(), timeoutMs: GIT_TIMEOUT_MS });
-  if (res.result !== 'ok' || res.stdout.length === 0) return 'refused: not tracked by git';
+  const res = await exec(['git', 'ls-files', '-z', '--', rel], { cwd: repoRoot, env: reviewGitEnv(), timeoutMs: GIT_TIMEOUT_MS });
+  if (res.result !== 'ok') return 'refused: git failed';
+  if (res.stdout === `${rel}\0`) return null;
+  if (res.stdout.length > 0) return 'refused: git failed';
+  if (!ownedFiles.includes(rel)) return 'refused: untracked, not owned by this block';
+  if (!changedFiles.includes(rel)) return 'refused: untracked, not changed in this block';
+  const ignored = await exec(['git', 'check-ignore', '-q', '--', rel], { cwd: repoRoot, env: plainGitEnv(), timeoutMs: GIT_TIMEOUT_MS, okExitCodes: [0, 1] });
+  if (ignored.result !== 'ok' || (ignored.code !== 0 && ignored.code !== 1)) return 'refused: git failed';
+  if (ignored.code === 0) return 'refused: gitignored';
   return null;
 }
 
 /**
  * The `needs_file` follow-up (§4.2): the requested files, read-only, appended AFTER the packet
- * (the stable prefix stays stable). Only regular files git TRACKS are attached — an untracked or
- * ignored file (`.env`, a key) never reaches a provider — and secret-like paths are refused even
+ * (the stable prefix stays stable). Regular tracked files, or untracked files present in BOTH
+ * concrete path lists of this block, are attached. Ignored untracked files never reach a provider,
+ * and secret-like paths are refused even
  * when tracked; every refusal is named in the section. The attachment is trimmed to `budgetTokens`.
- * @param {{repoRoot: string, paths: ReadonlyArray<unknown>, budgetTokens: number}} opts
+ * @param {{repoRoot: string, paths: ReadonlyArray<unknown>, budgetTokens: number, ownedFiles?: ReadonlyArray<string>, changedFiles?: ReadonlyArray<string>}} opts
+ * `ownedFiles` and `changedFiles`: resolved paths from the SAME block in this repoRoot; no globs.
  * @returns {Promise<string>} the section to append.
  */
-export async function attachFiles({ repoRoot, paths, budgetTokens }) {
+export async function attachFiles({ repoRoot, paths, budgetTokens, ownedFiles = [], changedFiles = [] }) {
   const out = ['## attached files (read-only, requested in needs_file)'];
   let left = budgetTokens * 4;
   for (const raw of paths.slice(0, 10)) {
@@ -356,7 +390,7 @@ export async function attachFiles({ repoRoot, paths, budgetTokens }) {
       out.push(notFile ? `### ${String(raw)} (not a file)` : '### (refused: not a repo-relative path)');
       continue;
     }
-    const refusal = await attachRefusal(repoRoot, rel);
+    const refusal = await attachRefusal(repoRoot, rel, ownedFiles, changedFiles);
     if (refusal) {
       out.push(`### ${rel} (${refusal})`);
       continue;

package/src/review/paired.mjs

@@ -0,0 +1,80 @@
+/** Stem pairs and bounded names for closed-book review packets (B97). No file reads. */
+import path from 'node:path';
+import { findSecret } from '../util/gh.mjs';
+import { redact } from '../util/redact.mjs';
+
+/** @param {string} file */
+function identity(file) {
+  if (typeof file !== 'string' || file.startsWith('/') || /[\\\x00-\x1f]/.test(file) || file.split('/').some((s) => s === '.' || s === '..' || s === '')) return null;
+  const ext = path.posix.extname(file);
+  let stem = path.posix.basename(file, ext);
+  let test = /(^|\/)(?:test|tests)\//.test(file);
+  if (ext === '.mjs' || ext === '.ts') {
+    if (/\.(test|spec)$/.test(stem)) { test = true; stem = stem.replace(/\.(test|spec)$/, ''); }
+  } else if (ext === '.php') {
+    if (stem.endsWith('Test')) { test = true; stem = stem.slice(0, -4); }
+  } else if (ext === '.go') {
+    if (stem.endsWith('_test')) { test = true; stem = stem.slice(0, -5); }
+  } else if (ext === '.py') {
+    if (stem.startsWith('test_')) { test = true; stem = stem.slice(5); }
+  } else if (ext === '.swift') {
+    if (stem.endsWith('Tests')) { test = true; stem = stem.slice(0, -5); }
+  } else return null;
+  return { ext, stem, test };
+}
+
+/** @param {string} file @param {ReadonlyArray<string>} candidates @returns {string[]} */
+export function pairsFor(file, candidates) {
+  const source = identity(file);
+  if (!source) return [];
+  return [...new Set(candidates)].filter((candidate) => {
+    const other = identity(candidate);
+    return candidate !== file && other?.ext === source.ext && other.stem === source.stem && other.test !== source.test;
+  });
+}
+
+/**
+ * A best-effort list, not a parser or proof of coverage. Names only, never function bodies.
+ * Redact before truncating so a token crossing the 120-character boundary cannot leak.
+ * @param {string} text @param {string} file @returns {string[]}
+ */
+export function summarize(text, file) {
+  const id = identity(file);
+  if (!id) return [];
+  /** @type {Set<string>} */
+  const names = new Set();
+  for (const line of text.split(/\r?\n/)) {
+    /** @type {RegExpMatchArray | null} */
+    let match = null;
+    if (id.test) {
+      if (id.ext === '.mjs' || id.ext === '.ts' || id.ext === '.php') {
+        match = line.match(/^\s*(?:await\s+)?(?:test|it)(?:\.(?:only|skip|todo))?\(\s*(['"`])([^\r\n]+?)\1/);
+        if (match) { names.add(match[2]); match = null; }
+        else if (id.ext === '.php') match = line.match(/^\s*(?:(?:public|protected)\s+)?function\s+(test\w+)\s*\(/);
+        else continue;
+      } else if (id.ext === '.go') match = line.match(/^\s*func\s+(Test\w+)\s*\(/);
+      else if (id.ext === '.py') match = line.match(/^\s*(?:async\s+)?def\s+(test_\w+)\s*\(/);
+      else if (id.ext === '.swift') match = line.match(/^\s*func\s+(test\w+)\s*\(/);
+    } else {
+      if (id.ext === '.mjs' || id.ext === '.ts') {
+        match = line.match(/^\s*export\s+(?:default\s+)?(?:async\s+)?(?:function\*?|class|const|let|var|interface|type|enum)\s+(\w+)/);
+        const list = line.match(/^\s*export\s*\{([^}]+)\}/);
+        if (list) {
+          for (const item of list[1].split(',')) {
+            const symbol = item.trim().match(/^(?:type\s+)?(\w+)(?:\s+as\s+(\w+))?$/);
+            if (symbol) names.add(symbol[2] ?? symbol[1]);
+          }
+        }
+      } else if (id.ext === '.php') match = line.match(/^\s*(?:(?:public|protected|private|static|final|abstract)\s+)*(?:function|class|interface|trait)\s+(\w+)/);
+      else if (id.ext === '.go') match = line.match(/^\s*(?:func\s+(?:\([^)]*\)\s+)?|(?:type|var|const)\s+)([A-Z]\w*)/);
+      else if (id.ext === '.py') match = line.match(/^\s*(?:async\s+)?(?:def|class)\s+([a-zA-Z]\w*)/);
+      else if (id.ext === '.swift') match = line.match(/^\s*(?:public|open)\s+(?:final\s+)?(?:func|class|struct|enum|protocol|let|var)\s+(\w+)/);
+    }
+    if (match) names.add(match[1]);
+    if (names.size >= 40) break;
+  }
+  return [...names].slice(0, 40).map((name) => {
+    const safe = redact(name);
+    return Array.from(findSecret(safe) ? '[REDACTED]' : safe).slice(0, 120).join('');
+  });
+}

package/src/review/reopen.mjs

@@ -8,8 +8,8 @@
  * Human-only like `block waive`: the verb is on `CODER_ONLY_FORBIDDEN` (`src/util/forbidden.mjs`)
  * and its row is signed with the run key, `by: human` (`block waive` has no other in-verb guard,
  * so neither has this). The verb (`reopenFile`) refuses, writing no row, with a stable code:
- *  - `usage` (exit 2) — no `--file`, no `--reason`, or a path that is not a normalised
- *    repo-root-relative path;
+ *  - `usage` (exit 2) — no `--file`, no `--reason`, or a path with a control character or that is
+ *    not a normalised repo-root-relative path (`checkFileForm`, shared with `block waive`);
  *  - `unknown_block` — the run does not know the block (the code `block waive` uses);
  *  - `reopen-block-not-open` — the block is not open (stopped or closed);
  *  - `reopen-not-owned` — the block does not own the file;
@@ -42,9 +42,9 @@
  *
  * This file imports nothing from `src/worker/`: the fix-loop state is read through `io`.
  */
-import path from 'node:path';
 import { StateError } from '../state/paths.mjs';
 import { verifyRow } from '../state/signer.mjs';
+import { checkFileForm } from './verb-forms.mjs';
 
 export const REOPENED_EVENT = 'review.reopened';
 
@@ -177,9 +177,7 @@ export function reopenRowFor(rows, { runId, block, file, key, status, state, seq
 export async function reopenFile({ runId, id, file, reason, record, rows, key, writeRow, writeSigned, io }) {
   if (typeof file !== 'string' || file.length === 0) throw new StateError('usage', 'block reopen needs --file <path>');
   if (typeof reason !== 'string' || reason.trim().length === 0) throw new StateError('usage', 'block reopen needs --reason');
-  if (path.isAbsolute(file) || file.split('/').includes('..') || file.startsWith('./') || path.posix.normalize(file) !== file) {
-    throw new StateError('usage', '--file must be repo-root-relative');
-  }
+  checkFileForm(file, { normalized: true });
   const entry = openBlockEntry(record, runId, id);
   const owned = Array.isArray(entry.owned_files) ? entry.owned_files : [];
   if (!io.owns(owned, file, entry.owned_kinds)) throw new StateError('reopen-not-owned', `reopen-not-owned: block ${id} does not own ${file}; nothing was recorded`);