@dzhechkov/harness-core 0.5.3 → 0.6.0

package/src/feature-adr-routing.ts

@@ -1243,9 +1243,13 @@ export function codexDispatchMode(stage: string): CodexDispatch {
  * 56-line adversarial code review answered in 14s. The stalls are INTERMITTENT latency — the same
  * input hung at 60s and answered at 14s minutes apart. Size is not the variable.
  *
- * So the real guard is the bounded timeout plus the CODEX_UNAVAILABLE sentinel: a slow exec becomes
- * an explicit "unavailable", never a passed review. This constant only stops us from shipping an
- * absurdly large prompt.
+ * DEMOTED 2026-08-21 (feature qe-scoped-review, ADR 001). This constant used to be described as the
+ * stall guard. That is now REFUTED by measurement: a 19 038-char QE prompt sat under this 24 000
+ * ceiling with ~5 000 chars of headroom and still spent 280 s / exit 124 producing no verdict, twice.
+ * The variable is not SIZE, it is whether the model is allowed to roam the tree. The defence is
+ * SCOPE — `codexReviewCommand` (the diff defines it) and `scopedQePrompt` ("read ONLY these files").
+ * This constant is retained as a sanity bound on an absurd payload, and is no longer claimed as the
+ * thing that prevents a stall.
  */
 export const CODEX_EXEC_PROMPT_CEILING_CHARS = 24_000;
 
@@ -1256,6 +1260,15 @@ export interface CodexExecPlanInput {
   readonly stage: string;
   readonly promptChars: number;
   readonly probedId: string | null;
+  /**
+   * TRUE only when the prompt was built by `scopedQePrompt` — i.e. it NAMES the files to read and
+   * forbids exploring. Absent/false on the `qe` stage routes to Claude instead of `exec`.
+   *
+   * MEASURED 2026-08-21: an unscoped 19 038-char QE prompt spent 280 s and exit 124 on
+   * reconnaissance and returned no verdict, TWICE (the retry ran at a 1500 s ceiling). The ceiling
+   * did not stop it — 19 038 sat under 24 000. Scope is the guard; this input is where it binds.
+   */
+  readonly scoped?: boolean;
 }
 
 export interface CodexExecPlanResult {
@@ -1271,6 +1284,17 @@ export function codexExecPlan(input: CodexExecPlanInput): CodexExecPlanResult {
   if (!input.probedId) {
     return { mode: 'claude', reason: 'no codex model id answered the probe' };
   }
+  // The `qe` stage is the one whose deliverable is a VERDICT, and the one measured to time out
+  // unscoped. An unscoped exec here is not merely slow — it returns null, the belt runs a Claude
+  // reviewer, and cross-family QE is lost silently. So it must not be dispatchable at all.
+  if (input.stage === 'qe' && input.scoped !== true) {
+    return {
+      mode: 'claude',
+      reason:
+        'qe prompt is not SCOPED — an unscoped codex exec QE buys reconnaissance, not review ' +
+        '(MEASURED 2026-08-21: 19038 chars, 280s, exit 124, no verdict)',
+    };
+  }
   if (input.promptChars > CODEX_EXEC_PROMPT_CEILING_CHARS) {
     return {
       mode: 'claude',
@@ -1353,6 +1377,452 @@ export function parseCodexExecResult(text: string | null | undefined): CodexExec
   return { ok: true, text: t, reason: 'codex answered' };
 }
 
+// ── SCOPED CODEX QE (feature qe-scoped-review, ADR 001) ─────────────────────
+//
+// MEASURED 2026-08-21, one question, one model (`gpt-5.6-sol`, effort `high`), three dispatches:
+//   1. `codex exec`, UNSCOPED, 19 038-char prompt → 280 s, exit 124, 416 KB / 4 583 lines, NO verdict
+//      (retried at a 1500 s ceiling: still no verdict).
+//   2. `codex exec`, SCOPED ("read ONLY these two files"), 1 461-char prompt → 41 s, exit 0, `Grade: B`.
+//   3. `codex review --commit <SHA>` → 146 s, exit 0, verdict + findings, scope derived from the diff.
+//
+// The budget went on RECONNAISSANCE of the tree, not on reasoning about the change. So raising the
+// timeout buys more reconnaissance, and the old working hypothesis — that
+// `CODEX_EXEC_PROMPT_CEILING_CHARS` was the binding constraint — is REFUTED: 19 038 sat under the
+// 24 000 ceiling with ~5 000 chars to spare. The defence is SCOPE. The ceiling is now a sanity bound.
+//
+// Why this matters beyond wall-clock: on timeout the dispatch returns null, the belt runs a Claude
+// reviewer, and the cross-family QE property is lost SILENTLY on exactly the large features that need
+// it most. Everything below exists so that loss is (a) rarer and (b) always attributable.
+
+/** Mode-A wall-clock bound. Run 3 measured 146 s; 600 s is ~4× headroom and still bounded. */
+export const CODEX_REVIEW_TIMEOUT_SECONDS = 600;
+/** MEASURED (probe 0.3): `codex review` accepts and echoes `reasoning effort: high`. */
+export const CODEX_REVIEW_DEFAULT_EFFORT = 'high';
+/** The sentinel a wrapper returns when the command hit its `timeout` — distinct from CODEX_UNAVAILABLE. */
+export const CODEX_TIMEOUT = 'CODEX_TIMEOUT';
+/** Machine sentinel appended by the dispatch command itself (grammar of the Step-7.5 landing signal). */
+export const CODEX_QE_SIGNAL_PREFIX = 'CODEX-QE-SIGNAL';
+/** Mode-B bounds, set FROM the measurement above (run 2 = 2 files / 1 461 chars), not from the ceiling. */
+export const SCOPED_QE_MAX_FILES = 3;
+export const SCOPED_QE_MAX_QUESTIONS = 4;
+export const SCOPED_QE_MAX_PATH_CHARS = 200;
+export const SCOPED_QE_MAX_QUESTION_CHARS = 200;
+export const SCOPED_QE_PROMPT_MAX_CHARS = 2000;
+
+/**
+ * A git ref reaches a shell command, exactly like a model id does. Same discipline as
+ * {@link isSafeCodexId}: plain refs only, and single-quoted at the call site anyway.
+ *
+ * Deliberately STRICTER than git: `HEAD~1`, `a..b` with `~`/`^`, and any leading `-` (which the CLI
+ * would read as a flag) are rejected. A rejected ref returns `{cmd: null}` → mode A is skipped and
+ * mode B / the Claude belt runs. Refusing to build is always cheaper than building something odd.
+ */
+export function isSafeCodexRef(ref: string): boolean {
+  return /^[A-Za-z0-9][A-Za-z0-9._\/-]{0,199}$/.test(String(ref));
+}
+
+export interface CodexReviewCommandInput {
+  /** `'commit' | 'base' | 'uncommitted'`. Default `'uncommitted'` — see the scope note below. */
+  readonly scope?: string | null;
+  readonly ref?: string | null;
+  readonly modelId?: string | null;
+  readonly reasoning?: string | null;
+  /**
+   * Accepted and DELIBERATELY IGNORED. MEASURED 2026-08-21: every scope flag refuses a positional
+   * prompt — `--commit`, `--base <BRANCH>` and `--uncommitted` each exit 2 with
+   * "the argument '<flag>' cannot be used with '[PROMPT]'". Silently appending one would present as
+   * a review that never happened. Our own questions go to mode B ({@link scopedQePrompt}).
+   */
+  readonly prompt?: string | null;
+  readonly timeoutSeconds?: number | null;
+}
+
+export interface CodexReviewCommandResult {
+  readonly cmd: string | null;
+  /** Always `false` today, and KEPT as a field: it is the one boolean a future CLI would flip. */
+  readonly carriesPrompt: boolean;
+  readonly scope: string;
+  readonly reason: string | null;
+}
+
+/**
+ * Build the mode-A command. The diff defines the scope, so Codex computes for free the thing we were
+ * paying a model to do badly.
+ *
+ * Two refusals are load-bearing, both measured (exit 2 = a silent review failure, since the pipeline
+ * would read "no output" as "codex unavailable"):
+ *   • never emit `-m` — `codex review` rejects it; the model goes through `-c model=`;
+ *   • never append a positional prompt — no scope flag accepts one.
+ *
+ * Default scope is `uncommitted` (probe 0.4b: it and `--base HEAD` reviewed the identical uncommitted
+ * diff, and `uncommitted` needs no ref, so it has no ref-injection surface at all).
+ */
+export function codexReviewCommand(input: CodexReviewCommandInput): CodexReviewCommandResult {
+  const o = input || ({} as CodexReviewCommandInput);
+  const scope = o.scope === undefined || o.scope === null || o.scope === '' ? 'uncommitted' : String(o.scope);
+  if (scope !== 'commit' && scope !== 'base' && scope !== 'uncommitted') {
+    return { cmd: null, carriesPrompt: false, scope: scope, reason: 'unknown review scope ' + scope };
+  }
+  const modelId = String(o.modelId === undefined || o.modelId === null ? '' : o.modelId);
+  if (!isSafeCodexId(modelId)) {
+    return { cmd: null, carriesPrompt: false, scope: scope, reason: 'unsafe id or ref' };
+  }
+  const effort = o.reasoning === undefined || o.reasoning === null || o.reasoning === '' ? CODEX_REVIEW_DEFAULT_EFFORT : String(o.reasoning);
+  if (!VALID_REASONING[effort]) {
+    return { cmd: null, carriesPrompt: false, scope: scope, reason: 'unknown reasoning effort ' + effort };
+  }
+  const ref = String(o.ref === undefined || o.ref === null ? '' : o.ref);
+  if (scope !== 'uncommitted' && !isSafeCodexRef(ref)) {
+    return { cmd: null, carriesPrompt: false, scope: scope, reason: 'unsafe id or ref' };
+  }
+  const raw = Number(o.timeoutSeconds);
+  const seconds = raw === raw && raw !== Infinity && raw > 0 ? Math.floor(raw) : CODEX_REVIEW_TIMEOUT_SECONDS;
+  let cmd = 'timeout ' + seconds + " codex review -c model='" + modelId + "' -c model_reasoning_effort='" + effort + "'";
+  if (scope === 'commit') cmd += " --commit '" + ref + "'";
+  else if (scope === 'base') cmd += " --base '" + ref + "'";
+  else cmd += ' --uncommitted';
+  cmd += ' < /dev/null';
+  return { cmd: cmd, carriesPrompt: false, scope: scope, reason: null };
+}
+
+export interface ScopedQePromptInput {
+  readonly files?: readonly string[] | null;
+  readonly questions?: readonly string[] | null;
+  readonly slug?: string | null;
+}
+
+/**
+ * Build the mode-B narrow prompt. The "do NOT open any other file" clause is LOAD-BEARING TEXT: it is
+ * the difference between the 41 s graded run and the 280 s ungraded one, at comparable model effort.
+ *
+ * An empty file list returns `''` — the caller treats that as "do not dispatch". An unscoped mode-B
+ * exec is precisely the failure this feature removes, so it must not be CONSTRUCTIBLE.
+ */
+export function scopedQePrompt(input: ScopedQePromptInput): string {
+  const o = input || ({} as ScopedQePromptInput);
+  const rawFiles = Array.isArray(o.files) ? o.files : [];
+  const files: string[] = [];
+  for (const f of rawFiles) {
+    const s = String(f === undefined || f === null ? '' : f).trim();
+    if (s === '') continue;
+    if (files.indexOf(s) !== -1) continue;
+    files.push(s.slice(0, SCOPED_QE_MAX_PATH_CHARS));
+    if (files.length >= SCOPED_QE_MAX_FILES) break;
+  }
+  if (files.length === 0) return '';
+  const rawQuestions = Array.isArray(o.questions) ? o.questions : [];
+  const questions: string[] = [];
+  for (const q of rawQuestions) {
+    const s = String(q === undefined || q === null ? '' : q).trim().replace(/\s+/g, ' ');
+    if (s === '') continue;
+    questions.push(s.slice(0, SCOPED_QE_MAX_QUESTION_CHARS));
+    if (questions.length >= SCOPED_QE_MAX_QUESTIONS) break;
+  }
+  if (questions.length === 0) {
+    questions.push('Is this change correct, and does the test named by its ADR actually DISCRIMINATE (would it fail if the protection were deleted)?');
+  }
+  const slug = String(o.slug === undefined || o.slug === null ? '' : o.slug).trim().slice(0, 60);
+  let out = 'Read ONLY these files: ' + files.join(', ') + '. Do NOT open any other file and do NOT explore the repository.';
+  if (slug !== '') out += ' They are the changed files of feature ' + slug + '.';
+  out += '\n\nAnswer these ' + questions.length + ' questions about them:\n';
+  for (let i = 0; i < questions.length; i++) out += i + 1 + '. ' + questions[i] + '\n';
+  out += '\nFinish with a single final line: Grade: <A|B|C|D>';
+  return out;
+}
+
+/**
+ * Wrap a command so its EXIT CODE survives the shell agent that runs it.
+ *
+ * The old wrapper collapsed every failure to `CODEX_UNAVAILABLE`, so a timeout (narrow the scope) and
+ * a broken invocation (fix the command) arrived indistinguishable — and `codex review` output is
+ * prose, not JSON, so the exit code is the only reliable discriminator there is. The emitted line is
+ * the grammar {@link parseCodexReviewSignal} reads back, and the two are round-trip tested against a
+ * REAL shell rather than against each other's regexes.
+ *
+ * The SUBSHELL around `inner` is load-bearing, and the round-trip test is what earned it: without it
+ * the `> "$o" 2>&1` redirect binds only to the last command of a compound `inner`, and an `exit`
+ * inside `inner` terminates the wrapper BEFORE the sentinel is echoed — producing exactly the
+ * "signal missing" state that must mean "the command did not demonstrably run".
+ */
+export function codexQeSignalCommand(inner: string, outPath?: string | null): string {
+  const raw = String(outPath === undefined || outPath === null ? '' : outPath);
+  // `JSON.stringify` is JSON quoting, not SHELL quoting — inside the double quotes it emits, `$`,
+  // backtick and `\` all keep their shell meaning, so a path carrying one would break out of the
+  // assignment. Found by the first live mode-A review of this feature (P1, 2026-08-21). The path is
+  // ours to construct, so the fix is an allowlist plus single-quoting, not an escaper: anything that
+  // is not a plain POSIX path falls back to the default rather than being cleverly escaped.
+  const o = /^\/[A-Za-z0-9._\/-]{1,200}$/.test(raw) ? raw : '/tmp/dz-codex-qe.out';
+  return "o='" + o + "'; start=$(date +%s); ( " + String(inner) + ' ) > "$o" 2>&1; rc=$?; cat "$o"; echo; echo "' + CODEX_QE_SIGNAL_PREFIX + ' exit=$rc elapsed=$(( $(date +%s) - start ))s bytes=$(wc -c < \"$o\" | tr -d \" \")"';
+}
+
+export interface ParsedCodexQeSignal {
+  readonly exit: number | null;
+  readonly elapsedSeconds: number | null;
+  readonly bytes: number | null;
+  readonly body: string;
+  readonly signalPresent: boolean;
+}
+
+/**
+ * Split the machine sentinel from the reviewer's own words.
+ *
+ * `codex review` output is prose, not JSON, so the EXIT CODE is the only reliable discriminator — and
+ * today the shell-agent wrapper throws it away. The dispatch command now appends
+ * `CODEX-QE-SIGNAL exit=<n> elapsed=<n>s bytes=<n>`, the same grammar as the Step-7.5 landing signal.
+ *
+ * A MISSING sentinel yields `exit: null` and `signalPresent: false` — never a defaulted 0. Defaulting
+ * to 0 would let "the wrapper never ran the command" read as "the command succeeded".
+ */
+export function parseCodexReviewSignal(text: string | null | undefined): ParsedCodexQeSignal {
+  const t = typeof text === 'string' ? text : '';
+  const re = /^CODEX-QE-SIGNAL exit=(-?\d+) elapsed=(\d+)s bytes=(\d+)[ \t]*$/gm;
+  let m: RegExpExecArray | null = null;
+  let last: RegExpExecArray | null = null;
+  while ((m = re.exec(t)) !== null) last = m;
+  if (last === null) {
+    return { exit: null, elapsedSeconds: null, bytes: null, body: t.trim(), signalPresent: false };
+  }
+  const body = (t.slice(0, last.index) + t.slice(last.index + last[0].length)).trim();
+  return { exit: Number(last[1]), elapsedSeconds: Number(last[2]), bytes: Number(last[3]), body: body, signalPresent: true };
+}
+
+export interface CodexQeFinding {
+  readonly severity: string;
+  readonly title: string;
+  readonly location: string;
+}
+
+/**
+ * Parse mode-A findings out of non-JSON review output, driven by a REAL saved capture
+ * (`test/fixtures/codex-review-2026-08-21.txt`), never by invented text.
+ *
+ * Observed shape: `- [P1] <title> — <abs-path>:<line>-<line>`, and Codex prints the whole finding
+ * block TWICE (once as the summary, once as the final message), hence the dedup.
+ *
+ * Zero parsed findings is a DATA POINT (`[]`), never "clean" — that judgment belongs to
+ * {@link gradeFromReviewFindings}, which refuses to make it.
+ */
+export function parseCodexReviewFindings(body: string | null | undefined): CodexQeFinding[] {
+  const t = String(body === undefined || body === null ? '' : body);
+  const out: CodexQeFinding[] = [];
+  const seen = new Set<string>();
+  for (const rawLine of t.split('\n')) {
+    const line = rawLine.trim();
+    const m = /^[-*]\s*\[(P[0-4])\]\s*(.+)$/.exec(line);
+    if (!m) continue;
+    const severity = String(m[1]);
+    let title = String(m[2]).trim();
+    let location = '';
+    const sep = title.lastIndexOf(' — ');
+    if (sep !== -1) {
+      const cand = title.slice(sep + 3).trim();
+      if (/:\d/.test(cand) || cand.indexOf('/') !== -1) {
+        location = cand;
+        title = title.slice(0, sep).trim();
+      }
+    }
+    if (title === '') continue;
+    const key = severity + '|' + title + '|' + location;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push({ severity: severity, title: title, location: location });
+  }
+  return out;
+}
+
+/**
+ * Derive a grade from what the reviewer actually found — used ONLY on the mode-A path, where the CLI
+ * structurally forbids asking for a letter (measured: every scope flag rejects `[PROMPT]`).
+ *
+ * Two honesty rules, and they are the highest-severity lines in this feature:
+ *   1. an empty or unparseable finding set returns `null`, NEVER a default letter. MEASURED
+ *      (probe 0.6): `codex review --uncommitted` on a CLEAN tree exits 0 with a polite, well-formed,
+ *      completely empty review. Mapping that to `'A'` would turn a review of NOTHING into a clean
+ *      bill of health — the exact `{grade:'codex-review', gaps: []}` fabrication ADR-001 deleted once;
+ *   2. `'A'` is UNREACHABLE by derivation for every input. "Nothing was found" is not evidence of
+ *      quality when the reviewer's own findings are the only evidence we have; only a reviewer that
+ *      STATES `Grade: A` (mode B, where we can ask) may produce one.
+ */
+export function gradeFromReviewFindings(findings: readonly CodexQeFinding[] | null | undefined): string | null {
+  const list = Array.isArray(findings) ? findings : [];
+  let worst: number | null = null;
+  for (const f of list) {
+    const s = String(f && f.severity ? f.severity : '').toUpperCase();
+    if (!/^P[0-4]$/.test(s)) continue;
+    const n = Number(s.slice(1));
+    if (worst === null || n < worst) worst = n;
+  }
+  if (worst === null) return null;
+  if (worst === 0) return 'D';
+  if (worst === 1) return 'C';
+  return 'B';
+}
+
+/**
+ * The LOCKED decline taxonomy. A `kind` outside this set is a bug, not a new case — which is why
+ * {@link codexQeDeclineReason} throws on one rather than rendering something plausible.
+ */
+export const CODEX_QE_DECLINE_KINDS: readonly string[] = ['timeout', 'no-verdict', 'tool-error', 'unusable-output', 'unavailable', 'over-ceiling'];
+
+export interface ClassifyCodexQeInput {
+  readonly exit?: number | null;
+  readonly body?: string | null;
+  readonly grade?: string | null;
+  readonly findings?: readonly CodexQeFinding[] | null;
+  /**
+   * TRUE (the default) when the caller dispatched through the sentinel-emitting wrapper, so a missing
+   * sentinel means the command never ran → `tool-error`. FALSE only when parsing RAW reviewer text
+   * that was never wrapped (a saved fixture, a file on disk), where content is all there is.
+   */
+  readonly signalExpected?: boolean;
+}
+
+/**
+ * Classify one Codex QE dispatch. The property this whole feature exists to protect lives here:
+ * a TIMEOUT and an UNUSABLE OUTPUT must never collapse into the same kind, because the operator's
+ * next move differs — `timeout` ⇒ narrow the scope; `tool-error` ⇒ fix the command; `unavailable` ⇒
+ * fix the account/model.
+ *
+ * Order is deliberate. `exit === 124` wins over EVERY content rule, because the measured timeout body
+ * was 416 KB of exploration — very much non-empty, and an empty-body rule would have mislabelled it
+ * `unusable-output` and told the operator to fix a tool that is working fine.
+ *
+ * `exit !== 0` is `tool-error` — but only for exits outside {0, 124}. MEASURED (probe 0.2): a review
+ * that finds a real P1 blocker still exits 0. A BAD review is a SUCCESSFUL cross-family review.
+ */
+export function classifyCodexQeOutcome(input: ClassifyCodexQeInput): { kind: string } {
+  const o = input || ({} as ClassifyCodexQeInput);
+  const body = String(o.body === undefined || o.body === null ? '' : o.body);
+  const exit = o.exit === undefined || o.exit === null ? null : Number(o.exit);
+  const grade = o.grade === undefined || o.grade === null || o.grade === '' ? null : String(o.grade);
+  const signalExpected = o.signalExpected === undefined ? true : !!o.signalExpected;
+  if (exit === 124) return { kind: 'timeout' };
+  if (body.trim() === '') return { kind: 'unusable-output' };
+  // The TEXT sentinels are evidence only when there is NO machine signal. FOUND BY THE FIRST LIVE
+  // MODE-A RUN (2026-08-21): `codex review --uncommitted` over this very feature's diff exited 0 in
+  // 482 s with six real findings, and was classified `timeout` — because the DIFF ITSELF contains the
+  // line `CODEX_TIMEOUT = 'CODEX_TIMEOUT'`. A reviewer quoting the code under review is the normal
+  // case for a diff-scoped review, so a content sentinel that outranks the exit code turns any review
+  // of this file into a fake timeout. When the exit code is known it is authoritative.
+  if (exit === null) {
+    if (body.indexOf(CODEX_TIMEOUT) !== -1) return { kind: 'timeout' };
+    if (body.indexOf(CODEX_UNAVAILABLE) !== -1) return { kind: 'unavailable' };
+    if (signalExpected) return { kind: 'tool-error' };
+  } else if (exit !== 0) {
+    return { kind: 'tool-error' };
+  }
+  if (grade !== null) return { kind: 'verdict' };
+  return { kind: 'no-verdict' };
+}
+
+export interface CodexQeDeclineDetail {
+  readonly elapsedSeconds?: number | string | null;
+  readonly seconds?: number | string | null;
+  readonly ref?: string | null;
+  readonly files?: readonly unknown[] | number | null;
+  readonly exit?: number | null;
+  readonly chars?: number | null;
+  readonly detail?: string | null;
+  readonly reason?: string | null;
+}
+
+/**
+ * Render the operator-facing decline reason — the string the workflow assigns to `lastCodexDecline`
+ * and that `crossFamilyQe` prints inside `opus (cross-family QE DID NOT happen — …)`.
+ *
+ * Before this feature every decline rendered as `codex exec unusable — codex exec returned no text`,
+ * so a timeout (narrow the scope) and a broken invocation (fix the command) produced an identical,
+ * unactionable alarm. The two `unusable-output` / `unavailable` strings are preserved VERBATIM from
+ * the two pre-existing call sites so the change adds precision without rewriting history.
+ *
+ * `'empty'` and `'ceiling'` are accepted as aliases (the ADR's vocabulary) of `'unusable-output'` and
+ * `'over-ceiling'` (the taxonomy's). Anything else THROWS: a kind outside the locked set is a bug,
+ * and rendering a plausible sentence for it would hide that bug behind a readable label.
+ */
+export function codexQeDeclineReason(kind: string | null | undefined, detail?: CodexQeDeclineDetail | null): string {
+  const d = detail || ({} as CodexQeDeclineDetail);
+  const k = String(kind === undefined || kind === null ? '' : kind);
+  const canonical = k === 'empty' ? 'unusable-output' : k === 'ceiling' ? 'over-ceiling' : k;
+  const secs = d.elapsedSeconds === undefined || d.elapsedSeconds === null ? d.seconds : d.elapsedSeconds;
+  const elapsed = secs === undefined || secs === null ? '?' : String(secs);
+  const ref = d.ref === undefined || d.ref === null || String(d.ref) === '' ? 'unknown' : String(d.ref);
+  const files = d.files === undefined || d.files === null ? '?' : String(Array.isArray(d.files) ? d.files.length : d.files);
+  const exit = d.exit === undefined || d.exit === null ? '?' : String(d.exit);
+  const chars = d.chars === undefined || d.chars === null ? '?' : String(d.chars);
+  const extra = d.detail === undefined || d.detail === null || String(d.detail) === '' ? 'no detail' : String(d.detail);
+  if (canonical === 'timeout') {
+    return 'codex review timed out after ' + elapsed + 's on scope ' + ref + ' (' + files + ' files) — NARROW the scope (this is reconnaissance cost, not thinking time)';
+  }
+  if (canonical === 'no-verdict') {
+    return 'codex answered in ' + elapsed + 's but named no grade — not a verdict';
+  }
+  if (canonical === 'tool-error') {
+    return 'codex review exited ' + exit + ' — FIX the invocation (' + extra + ')';
+  }
+  if (canonical === 'unusable-output') {
+    return 'codex exec unusable — ' + (d.reason === undefined || d.reason === null || String(d.reason) === '' ? 'codex exec returned no text' : String(d.reason));
+  }
+  if (canonical === 'unavailable') {
+    return 'codex not used — ' + (d.reason === undefined || d.reason === null || String(d.reason) === '' ? 'codex exec reported it could not run' : String(d.reason));
+  }
+  if (canonical === 'over-ceiling') {
+    return 'prompt is ' + chars + ' chars / unscoped — refused before dispatch';
+  }
+  throw new Error('codexQeDeclineReason: unknown kind ' + k);
+}
+
+/**
+ * The ADR's spelling of {@link codexQeDeclineReason}. Accepts BOTH call shapes — the ADR's
+ * `({kind, seconds, detail})` object and the taxonomy's positional `(kind, detail)` — so both cited
+ * call sites resolve to one implementation instead of two that can drift.
+ */
+export function codexDeclineReason(a: unknown, b?: CodexQeDeclineDetail | null): string {
+  if (a && typeof a === 'object') {
+    const o = a as CodexQeDeclineDetail & { kind?: string | null };
+    return codexQeDeclineReason(o.kind, o);
+  }
+  return codexQeDeclineReason(a as string, b);
+}
+
+export interface CodexReviewResult {
+  readonly ok: boolean;
+  readonly grade: string | null;
+  readonly kind: string;
+  readonly gradeSource: string | null;
+  readonly findings: CodexQeFinding[];
+  readonly reason: string | null;
+}
+
+/**
+ * The ADR's one-call parser over RAW reviewer text: signal-split → findings → grade → classify.
+ * Pure composition; every rule it applies belongs to one of the four helpers above.
+ *
+ * `signalExpected` is passed as `sig.signalPresent` ON PURPOSE, and it is the one line here worth
+ * reading twice. This function's input is text that may never have been wrapped (a saved fixture, a
+ * report on disk), so a missing sentinel means "no machine signal exists", not "the tool failed".
+ * The PIPELINE must not use this leniency: the workflow dispatches through the sentinel-emitting
+ * wrapper and calls {@link classifyCodexQeOutcome} directly with `signalExpected: true`, so a
+ * swallowed sentinel there is a `tool-error` and never a pass. A wiring test pins that.
+ */
+export function parseCodexReviewResult(text: string | null | undefined): CodexReviewResult {
+  const sig = parseCodexReviewSignal(text);
+  const findings = parseCodexReviewFindings(sig.body);
+  const stated = parseCodexGrade(sig.body);
+  const grade = stated !== null ? stated : gradeFromReviewFindings(findings);
+  const outcome = classifyCodexQeOutcome({ exit: sig.exit, body: sig.body, grade: grade, findings: findings, signalExpected: sig.signalPresent });
+  const kind = outcome.kind === 'unusable-output' ? 'empty' : outcome.kind;
+  const ok = kind === 'verdict';
+  const reason = ok ? null : codexQeDeclineReason(kind, { elapsedSeconds: sig.elapsedSeconds, exit: sig.exit, chars: sig.body.length });
+  return {
+    ok: ok,
+    grade: ok ? grade : null,
+    kind: kind,
+    gradeSource: ok ? (stated !== null ? 'stated' : 'derived-from-findings') : null,
+    findings: findings,
+    reason: reason,
+  };
+}
+
 /** CX-3: a workflow that names an agent type the harness does not have must fall back, not die. */
 export function isAgentTypeMissingError(err: unknown): boolean {
   const msg = err instanceof Error ? err.message : String(err ?? '');
@@ -1503,10 +1973,65 @@ export interface PlanGateVerdict {
  * silently empty) and the `K2_EXIT=` trailer carries the exit code back through an agent that can
  * only return text.
  */
-export function planCompletenessGateCmd(repo: string, featureDir: string, tier?: string | null): string {
+export interface PlanGateCmdOpts {
+  /** An explicit ABSOLUTE path to the gate script. Validated at build time; never silently demoted. */
+  gateScript?: string
+  /** Pin the workspace root instead of resolving it live with `pwd -P` (tests; deterministic pins). */
+  workspace?: string
+}
+
+/** Both interpolated knobs are shell-spliced, so both get the same build-time shape check. */
+function assertAbsoluteNoTraversal(value: unknown, knob: string): string {
+  if (typeof value !== 'string' || value === '') throw new Error('planCompletenessGateCmd: opts.' + knob + ' must be a non-empty absolute path')
+  if (value.charAt(0) !== '/') throw new Error('planCompletenessGateCmd: opts.' + knob + ' must be an ABSOLUTE path, got ' + JSON.stringify(value))
+  if (/(^|\/)\.\.(\/|$)/.test(value)) throw new Error("planCompletenessGateCmd: opts." + knob + " must not contain a '..' segment, got " + JSON.stringify(value))
+  return value
+}
+
+/**
+ * The EXACT command the gate agent runs. `2>&1` folds stderr in (a crash must be visible, not
+ * silently empty) and the `K2_EXIT=` trailer carries the exit code back through an agent that can
+ * only return text.
+ *
+ * P16/D2 — WHERE the script is looked up. The skill is installed in the WORKSPACE; the command
+ * `cd`s into the TARGET repo, so a repo-relative `node .claude/skills/…` resolved against the target
+ * and died with `Cannot find module` on every repo that is not itself a feature-adr install (field
+ * report P16: K2_EXIT=1, verdict not-established, reason no-verdict-line). The fix is an ordered
+ * candidate chain, WORKSPACE BEFORE REPO on purpose: the verdict contract is defined by the PARSER
+ * inside the running workflow, so only the copy from that same installation is known to speak it —
+ * a target repo may carry an older copy that prints `K2: NOT-ESTABLISHED — …`, a prefix this
+ * parser does not match (a live example lives at
+ * features/wave1-instrument-repair/check-plan-completeness.mjs). Nothing found ⇒ a LOUD
+ * `tooling-missing` refusal with every tried path echoed — never a skip, never a pass.
+ *
+ * Called with three arguments the emitted string is byte-identical to the pre-P16 command; the
+ * search chain appears only when `opts` is supplied. That 3-arg form exists so the pre-existing
+ * byte-pin can keep asserting the OLD shape (a test-fixture role, not an API promise — the shipped
+ * caller always passes `opts`).
+ */
+export function planCompletenessGateCmd(repo: string, featureDir: string, tier?: string | null, opts?: PlanGateCmdOpts): string {
   const q = (s: string) => "'" + String(s).replace(/'/g, "'\\''") + "'"
   const t = (typeof tier === 'string' && tier !== '') ? ' --tier=' + q(tier) : ''
-  return 'cd ' + q(repo) + ' && node ' + q(PLAN_GATE_SCRIPT) + ' ' + q(featureDir) + t + ' 2>&1; echo K2_EXIT=$?'
+  if (opts === undefined || opts === null) {
+    return 'cd ' + q(repo) + ' && node ' + q(PLAN_GATE_SCRIPT) + ' ' + q(featureDir) + t + ' 2>&1; echo K2_EXIT=$?'
+  }
+  const explicit = (opts.gateScript === undefined || opts.gateScript === null) ? null : assertAbsoluteNoTraversal(opts.gateScript, 'gateScript')
+  const ws = (opts.workspace === undefined || opts.workspace === null) ? null : assertAbsoluteNoTraversal(opts.workspace, 'workspace')
+  // WS is captured BEFORE the cd — that ordering is the whole point; a 'pwd -P' after the cd would
+  // report the target repo and the chain would collapse back into the defect it fixes.
+  const wsAssign = ws === null ? 'WS=$(pwd -P)' : 'WS=' + q(ws)
+  return [
+    wsAssign + "; GS=''",
+    'C1=' + (explicit === null ? "''" : q(explicit)) + '; C2="$WS/' + PLAN_GATE_SCRIPT + '"; C3=' + q(repo + '/' + PLAN_GATE_SCRIPT),
+    'for c in "$C1" "$C2" "$C3"; do [ -n "$c" ] && [ -f "$c" ] && { GS="$c"; break; }; done',
+    // Audit lines, printed ALWAYS and BEFORE any verdict line: which copy ran, and what was tried.
+    // They are deliberately not verdict-shaped, so the parser's last-match anchoring is untouched,
+    // and the tried paths live OUTSIDE the verdict line so no path can smuggle a second verdict word
+    // into it.
+    'echo "K2_GATE_SCRIPT=${GS:-none}"',
+    'echo "K2_GATE_TRIED=${C1:-(none)} | $C2 | $C3"',
+    'if [ -z "$GS" ]; then echo "K2 plan-completeness: NOT-ESTABLISHED — tooling-missing: no gate script at any candidate on the K2_GATE_TRIED line above"; echo "K2_EXIT=3"; else cd ' + q(repo) + ' && node "$GS" ' + q(featureDir) + t + ' 2>&1; echo "K2_EXIT=$?"; fi',
+  ].join('\n')
 }
 
 /**
@@ -1532,5 +2057,325 @@ export function parsePlanGateVerdict(raw: string | null | undefined): PlanGateVe
   const byExit = exitCode === 0 ? 'pass' : (exitCode === 1 ? 'fail' : (exitCode === 3 ? 'not-established' : null))
   if (byExit === null) return { verdict: 'not-established', exit: exitCode, reason: 'unknown-exit-code', output: output }
   if (byExit !== byName) return { verdict: 'not-established', exit: exitCode, reason: 'verdict-exit-mismatch', output: output }
-  return { verdict: byName, exit: exitCode, reason: 'script-verdict', output: output }
+  // P16/D2: a REFINEMENT of the reason, not a new verdict. The verdict vocabulary stays three values,
+  // so every banner and exit-code table pinned by tests keeps meaning what it meant. A forged
+  // K2_EXIT=0 under a NOT-ESTABLISHED line still returns verdict-exit-mismatch above — the new
+  // reason is read only after both halves already agree.
+  const lastAt = text.lastIndexOf(lastVerdict)
+  const nl = text.indexOf('\n', lastAt)
+  const lastLine = nl < 0 ? text.slice(lastAt) : text.slice(lastAt, nl)
+  const reason = (byName === 'not-established' && /tooling-missing:/.test(lastLine)) ? 'tooling-missing' : 'script-verdict'
+  return { verdict: byName, exit: exitCode, reason: reason, output: output }
+}
+
+/**
+ * The operator note a refused plan gate carries — ONE reason→text table, so the workflow's inline
+ * copy cannot drift into telling an operator to fix a plan that is not broken.
+ *
+ * AM-2/AM-7: before P16 this text was inline and UNCONDITIONAL ("exit 1 ⇒ fix the FAIL lines"),
+ * which is actively wrong for a gate that never RAN. Existence of a branch is not proof it fires,
+ * so the table is exported and unit-tested on both reasons.
+ */
+export function refusalNoteFor(planGate: PlanGateVerdict, slug: string): string {
+  const exitTxt = planGate.exit === null ? 'unknown' : String(planGate.exit)
+  const head = 'REFUSED at the Step-6/7 boundary: the K2 plan-completeness gate returned ' + String(planGate.verdict).toUpperCase() + ' (exit=' + exitTxt + ', reason=' + planGate.reason + '). Step 7 was NOT dispatched. '
+  if (planGate.reason === 'tooling-missing') {
+    return head + 'The gate could not be RUN. This is NOT a plan defect — do NOT edit the plan. Reinstall the feature-adr skill into the workspace this run started in, or re-invoke with args.gateScript=<absolute path to check-plan-completeness.mjs>. Every path that was tried is on the K2_GATE_TRIED line of the gate output below. The plan stage is checkpointed, so once the gate is reachable a bare re-invoke resumes it and nothing is re-planned. Gate output:\n' + planGate.output
+  }
+  return head + 'exit 1 ⇒ fix the plan per the FAIL lines below and re-invoke; exit 3 / not-established ⇒ INCONCLUSIVE, the gate could not read its inputs (fix them and rerun) — it is never a pass. HOW TO REPAIR (the plan stage is checkpointed, so a bare re-invoke RESUMES this same failing plan): edit features/' + slug + "/06_implementation_plan.md to fix the FAIL lines and re-invoke — the plan checkpoint is keyed on run INPUTS, not on the file, so your edit is NOT re-planned away; to force a fresh plan instead, re-invoke with args.resume='never' (or delete features/" + slug + '/.fa-state/). Gate output:\n' + planGate.output
+}
+
+/**
+ * ADR-003 — pin a RELATIVE `args.dzBin` to the workspace root once, at the point of definition.
+ *
+ * `DZ` is spliced into commands that first `cd` into the target repo, into the brain, or into
+ * nothing at all (the usage probe), so a relative binary path resolves against three different
+ * bases and silently returns nothing on at least two of them — and a null usage probe is read
+ * upstream as "the limit was hit", which fail-safe-switches a healthy run to Codex.
+ * A bare `dz` (no slash) keeps PATH resolution; an already-absolute value is returned untouched.
+ */
+export function normalizeDzBin(raw: string | null | undefined, ws: string | null | undefined): string {
+  const r = (typeof raw === 'string' && raw.length > 0) ? raw : 'dz'
+  if (r.indexOf('/') < 0) return r
+  if (r.charAt(0) === '/') return r
+  const base = (typeof ws === 'string' && ws.length > 0) ? ws.replace(/\/+$/, '') : ''
+  return base === '' ? r : base + '/' + r
+}
+
+/** What cross-family QE was asked for, what actually reviewed, and — when they differ — why. */
+export interface CrossFamilyQeReport {
+  /** The QE spec routing resolved, e.g. `codex:gpt-5.6-sol:high`. */
+  readonly requested: string | null;
+  /** The model label that actually produced the review, e.g. `opus`. */
+  readonly actual: string;
+  readonly coderFamily: string;
+  readonly reviewerFamily: string;
+  /** TRUE only when the reviewer's family differs from the coder's. */
+  readonly happened: boolean;
+  /** Why cross-family QE did not happen. `null` when it did. */
+  readonly reason: string | null;
+}
+
+/**
+ * Report — and LABEL — whether cross-family QE actually happened.
+ *
+ * The 2026-08-20 P16 run is the reason this exists. Routing correctly resolved QE to
+ * `codex:gpt-5.6-sol:high` (MEASURED: `resolveQeSpec` returns exactly that for a Claude coder), the
+ * codex dispatch returned null, the cross-model belt correctly fell back to a Claude reviewer so the
+ * run would not block — and the result reported `modelsUsed.qe = "opus"` with nothing anywhere saying
+ * the independent review had not taken place. The belt worked; its FAILURE was invisible. The only
+ * reason anyone noticed is that the Claude reviewer volunteered it in prose.
+ *
+ * A safety property that silently degrades to its own absence is worse than one that is absent, because
+ * the absence is believed to be presence. So the label carries the degradation and the caller returns
+ * the report — self-review must never be able to pass for independent review by omission.
+ *
+ * HONEST SCOPE — what this does NOT do, named because a reader would otherwise assume it does (the
+ * cross-family reviewer that graded the first version B asked for exactly this paragraph):
+ *   • it does not verify the declared reviewer ACTUALLY RAN — only what the caller declares;
+ *   • it does not establish genuine independence: two Claude models are one family here, and a
+ *     caller free to mislabel a family can still misreport;
+ *   • it does not validate the decline reason's provenance — any non-blank caller text is taken
+ *     verbatim, so a stale reason from an earlier dispatch would be reported as this one's (the
+ *     workflow clears `lastCodexDecline` per dispatch for exactly this reason; that discipline
+ *     lives at the call site, not here);
+ *   • it does not force a caller to surface the report at all.
+ * It normalises family names and refuses to call an unnameable side cross-family. Beyond that it is
+ * honest only when wired with truthful inputs — a REPORTING helper, not an authentication mechanism.
+ */
+export function crossFamilyQe(opts: {
+  requestedSpec: string | null;
+  actualLabel: string;
+  coderFamily: string;
+  reviewerFamily: string;
+  declineReason?: string | null;
+}): { report: CrossFamilyQeReport; label: string } {
+  // NORMALISE before comparing. A cross-family reviewer graded the first version B and named this:
+  // families were compared as RAW strings, so `reviewerFamily: 'Claude'` against
+  // `coderFamily: 'claude'` reported happened:true with a clean label — the same loss this helper
+  // exists to expose, walking back in through letter case.
+  const norm = (f: string): string => String(f ?? '').trim().toLowerCase();
+  const coderFamily = norm(opts.coderFamily);
+  const reviewerFamily = norm(opts.reviewerFamily);
+  // An empty family is not a family. Calling '' different from 'claude' would report a cross-family
+  // review nobody can name, so an unnameable side counts as NOT cross-family.
+  const nameable = coderFamily !== '' && reviewerFamily !== '';
+  const happened = nameable && coderFamily !== reviewerFamily;
+  const stated = opts.declineReason !== null && opts.declineReason !== undefined && String(opts.declineReason).trim() !== ''
+    ? String(opts.declineReason).trim()
+    : null;
+  const reason = happened
+    ? null
+    : (stated ?? (nameable ? 'reviewer family equals coder family' : 'reviewer or coder family not named'));
+  const report: CrossFamilyQeReport = {
+    requested: opts.requestedSpec ?? null,
+    actual: opts.actualLabel,
+    coderFamily,
+    reviewerFamily,
+    happened,
+    reason,
+  };
+  // The label is what a human skims. It must not read clean when the property was lost.
+  const label = happened
+    ? opts.actualLabel
+    : `${opts.actualLabel} (cross-family QE DID NOT happen — ${reason})`;
+  return { report, label };
+}
+
+/** Whether a scoped (mode-B) cross-family review may run, and over WHICH files. */
+export type ModeBScopeVerdict =
+  | { readonly ok: true; readonly files: readonly string[]; readonly dropped: readonly string[] }
+  | { readonly ok: false; readonly reason: string };
+
+/**
+ * Decide the scope of a scoped cross-family QE review — or refuse it.
+ *
+ * The defect this closes (cross-family review of `qe-scoped-review`, 2026-08-21, its own first P1):
+ * mode B built its file list from the PLANNED targets and never once consulted what actually changed.
+ * On a run where Step 7 produced nothing, mode A reviews an empty diff and declines, mode B then
+ * points the reviewer at unchanged pre-feature files and asks for a closing letter — and mode B is
+ * the ONLY path that may return a STATED grade, the only one on which `A` is reachable at all. The
+ * reviewer's headline stands quoted because it is exact: *"the patch can record a successful QE
+ * verdict without reviewing the actual change."*
+ *
+ * So scope is derived from the MEASURED change set intersected with what the plan declared, and two
+ * states refuse outright rather than review something else:
+ *   • `genuinely-not-landed` — the landing barrier already established the code is not there;
+ *   • an unknown change set — the probe could not measure. Inconclusive is never a pass, and here the
+ *     honest consequence is that cross-family QE does not happen and says so, which `crossFamilyQe`
+ *     now surfaces, rather than a confident grade over the wrong files.
+ *
+ * `dropped` is the planned-but-unchanged remainder. Callers must NOT report it as reviewed: recording
+ * files the reviewer never saw is the same lie one level down (that is the report's MEDIUM-1).
+ */
+export function decideModeBScope(opts: {
+  planned: readonly string[];
+  changed: readonly string[] | null;
+  landingStatus?: string | null;
+}): ModeBScopeVerdict {
+  if (opts.landingStatus === 'genuinely-not-landed') {
+    return { ok: false, reason: 'the landing barrier established the code did not land — there is nothing to review' };
+  }
+  if (opts.changed === null || opts.changed === undefined) {
+    return { ok: false, reason: 'the change set could not be measured — scope is NOT ESTABLISHED, which is never a pass' };
+  }
+  const planned = opts.planned.map((p) => String(p)).filter((p) => p !== '');
+  if (planned.length === 0) {
+    return { ok: false, reason: 'no declared targets — a scoped review needs a declared scope' };
+  }
+  const changedSet = new Set(opts.changed.map((c) => String(c)));
+  const files = planned.filter((p) => changedSet.has(p));
+  const dropped = planned.filter((p) => !changedSet.has(p));
+  if (files.length === 0) {
+    return { ok: false, reason: 'none of the ' + planned.length + ' declared target(s) actually changed — the review would be of unchanged code' };
+  }
+  return { ok: true, files, dropped };
+}
+
+/** Findings split by whether they belong to the feature under review. */
+export interface PartitionedFindings {
+  readonly inScope: readonly CodexQeFinding[];
+  /** Real findings about OTHER work that happened to be dirty. Reported, never graded. */
+  readonly outOfScope: readonly CodexQeFinding[];
+  /**
+   * Findings whose location could not be MATCHED either way — no location at all, or a shape the
+   * matcher does not parse (`src/a.ts line 10`). They are NOT out-of-scope: nothing proves they
+   * concern another file. Suppressing them would drop a possibly-blocking finding from the grade on
+   * the strength of a parsing failure, which is the "unknown counted as clean" mistake this whole
+   * wave exists to remove — and which I reproduced here until cross-family review caught it.
+   */
+  readonly unlocatable: readonly CodexQeFinding[];
+  /** True when scope could not be established, so nothing may be attributed either way. */
+  readonly unscoped: boolean;
+}
+
+/**
+ * Separate a mode-A review's findings into this feature's and the rest of the dirty worktree's.
+ *
+ * `codex review --uncommitted` reviews EVERY staged, unstaged and untracked change, and
+ * `gradeFromReviewFindings` takes the worst severity over all of them. So an unrelated P0 sitting
+ * dirty in the tree grades this feature D — indistinguishable from a D it earned.
+ *
+ * Not theoretical. In the saved live self-review fixture
+ * (`test/fixtures/codex-review-selfreview-slices-2026-08-21.txt`), ONE of the six P1s is
+ * `features/talk-ai-assistants/demo-site/site/dist/index.html:57-58` — unrelated work that merely
+ * happened to be uncommitted at the time.
+ *
+ * Out-of-scope findings are NOT discarded: they are real, and dropping them silently would be its own
+ * dishonesty. They are returned separately so the caller can report them as what they are.
+ *
+ * @param inScopePaths the MEASURED change set for this feature (repo-relative). Empty ⇒ `unscoped`,
+ *        and the caller must not attribute anything — inconclusive is never a pass, and it is not a
+ *        fail either.
+ */
+export function partitionReviewFindings(
+  findings: readonly CodexQeFinding[] | null | undefined,
+  inScopePaths: readonly string[] | null | undefined,
+): PartitionedFindings {
+  const list = Array.isArray(findings) ? findings : [];
+  const paths = (inScopePaths ?? []).map((p) => String(p)).filter((p) => p !== '');
+  if (paths.length === 0) return { inScope: [], outOfScope: [], unlocatable: list, unscoped: true };
+  const belongs = (loc: string): boolean => {
+    const l = String(loc ?? '');
+    // A location is `<path>:<line>` or `<abs-path>:<line>-<line>`; match on the path SEGMENT so an
+    // absolute location still matches its repo-relative target, and a mere substring cannot.
+    if (paths.some((p) => l === p || l.startsWith(p + ':') || l.includes('/' + p + ':') || l.endsWith('/' + p))) return true;
+    // A location whose SHAPE we can parse (`<path>:<line>`) has already had its say above — a loose
+    // substring must not override it, or `other/src/a.ts.bak:3` would be claimed by `src/a.ts`.
+    // But a shape we CANNOT parse yet which names an in-scope file is ours (`src/a.ts line 10`):
+    // reading "I could not parse this" as "it belongs to someone else" is how a finding about our own
+    // file would quietly leave the grade.
+    if (/[\w./-]+:\d/.test(l)) return false;
+    return paths.some((p) => l.includes(p));
+  };
+  const inScope: CodexQeFinding[] = [];
+  const outOfScope: CodexQeFinding[] = [];
+  const unlocatable: CodexQeFinding[] = [];
+  // A location we can PARSE and that names another file is out of scope. A location we cannot parse
+  // proves nothing, so it goes to `unlocatable` and the caller must not rescore without it.
+  // Purely about SHAPE now: does the location name some file at some line? If it does and it is not
+  // ours, it is another file's. If it does not, we know nothing.
+  const parseable = (loc: string): boolean => /[\w./-]+:\d/.test(String(loc ?? ''));
+  for (const f of list) {
+    const loc = f && f.location ? f.location : '';
+    if (belongs(loc)) inScope.push(f);
+    else if (parseable(loc)) outOfScope.push(f);
+    else unlocatable.push(f);
+  }
+  return { inScope, outOfScope, unlocatable, unscoped: false };
+}
+
+/** A path → content-hash snapshot; `null` means the file was ABSENT when the snapshot was taken. */
+export type FileHashSnapshot = ReadonlyMap<string, string | null>;
+
+/**
+ * Parse a `sha256sum` probe into a snapshot, tolerating the "no such file" lines it prints to stderr.
+ *
+ * Presence is not the question — CONTENT is. A file that was already dirty before Step 7 and then
+ * edited by Step 7 must count as changed, and `git status` cannot tell those apart: it reports the
+ * file as dirty in both cases. That is one half of why the old probe measured the wrong thing.
+ */
+export function parseHashProbe(text: string | null | undefined, declared: readonly string[]): FileHashSnapshot {
+  const out = new Map<string, string | null>();
+  for (const p of declared) out.set(String(p), null);
+  for (const raw of String(text ?? '').split('\n')) {
+    const line = raw.trim();
+    if (line === '') continue;
+    const m = /^([0-9a-f]{64})\s+(.+)$/.exec(line);
+    if (m === null || m[1] === undefined || m[2] === undefined) continue;
+    const path = m[2].trim().replace(/^\.\//, '');
+    if (out.has(path)) out.set(path, m[1]);
+  }
+  return out;
+}
+
+/**
+ * Which declared targets actually changed between two snapshots.
+ *
+ * Returns `null` when either snapshot is missing — an unmeasured delta is NOT an empty delta, and the
+ * callers treat null as "scope not established", which is never a pass.
+ */
+export function changedFromHashes(before: FileHashSnapshot | null, after: FileHashSnapshot | null): string[] | null {
+  if (before === null || before === undefined || after === null || after === undefined) return null;
+  const changed: string[] = [];
+  for (const [path, afterHash] of after) {
+    const beforeHash = before.has(path) ? before.get(path) ?? null : null;
+    if (beforeHash !== (afterHash ?? null)) changed.push(path);
+  }
+  return changed.sort();
+}
+
+/**
+ * Build the probe that measures a change set, MATCHED to the review scope.
+ *
+ * The old code ran one `git status --porcelain` regardless of scope, which is wrong in both
+ * directions (cross-family review of the 2026-08-21 wave, P1):
+ *   • `uncommitted` — a target already dirty BEFORE Step 7 is reported as this run's change, so mode B
+ *     could certify work the coder never touched. Hence the baseline pair rather than a single look.
+ *   • `commit` / `base` — real COMMITTED changes produce no status entry at all, so the set came back
+ *     empty and the scoped review was disabled on a run whose code demonstrably exists.
+ *
+ * @returns the shell command, or `null` when the scope needs a ref it was not given — the caller must
+ *          then treat the scope as unmeasured rather than substituting a different question.
+ */
+export function changeSetProbeCmd(opts: {
+  scope: string;
+  ref?: string | null;
+  paths: readonly string[];
+  quote: (s: string) => string;
+}): string | null {
+  const paths = opts.paths.map((p) => String(p)).filter((p) => p !== '');
+  if (paths.length === 0) return null;
+  const quoted = paths.map(opts.quote).join(' ');
+  const ref = String(opts.ref ?? '').trim();
+  if (opts.scope === 'commit') {
+    if (ref === '') return null;
+    return 'git diff --name-only ' + opts.quote(ref) + '~1 ' + opts.quote(ref) + ' -- ' + quoted;
+  }
+  if (opts.scope === 'base') {
+    if (ref === '') return null;
+    return 'git diff --name-only ' + opts.quote(ref) + '...HEAD -- ' + quoted;
+  }
+  // uncommitted: hash the declared targets; the caller pairs this with a pre-code baseline.
+  return 'sha256sum -- ' + quoted + ' 2>/dev/null || true';
 }