@dzhechkov/harness-core 0.5.4 → 0.6.0

package/dist/feature-adr-routing.js

@@ -1009,9 +1009,13 @@ export function codexDispatchMode(stage) {
  * 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;
 /** The sentinel an exec agent returns when the command failed, timed out, or Codex refused. */
@@ -1024,6 +1028,16 @@ export function codexExecPlan(input) {
     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',
@@ -1088,6 +1102,388 @@ export function parseCodexExecResult(text) {
     }
     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) {
+    return /^[A-Za-z0-9][A-Za-z0-9._\/-]{0,199}$/.test(String(ref));
+}
+/**
+ * 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) {
+    const o = input || {};
+    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 };
+}
+/**
+ * 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) {
+    const o = input || {};
+    const rawFiles = Array.isArray(o.files) ? o.files : [];
+    const files = [];
+    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 = [];
+    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, outPath) {
+    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 \" \")"';
+}
+/**
+ * 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) {
+    const t = typeof text === 'string' ? text : '';
+    const re = /^CODEX-QE-SIGNAL exit=(-?\d+) elapsed=(\d+)s bytes=(\d+)[ \t]*$/gm;
+    let m = null;
+    let last = 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 };
+}
+/**
+ * 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) {
+    const t = String(body === undefined || body === null ? '' : body);
+    const out = [];
+    const seen = new Set();
+    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) {
+    const list = Array.isArray(findings) ? findings : [];
+    let worst = 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 = ['timeout', 'no-verdict', 'tool-error', 'unusable-output', 'unavailable', 'over-ceiling'];
+/**
+ * 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) {
+    const o = input || {};
+    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' };
+}
+/**
+ * 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, detail) {
+    const d = detail || {};
+    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, b) {
+    if (a && typeof a === 'object') {
+        const o = a;
+        return codexQeDeclineReason(o.kind, o);
+    }
+    return codexQeDeclineReason(a, b);
+}
+/**
+ * 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) {
+    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) {
     const msg = err instanceof Error ? err.message : String(err ?? '');
@@ -1206,15 +1602,60 @@ export function checkArtifactRoot(root) {
 // copies (drift-guarded), because the workflow sandbox cannot import.
 /** The one path the pipeline calls. Repo-relative — the command `cd`s into the repo root first. */
 export const PLAN_GATE_SCRIPT = '.claude/skills/feature-adr/scripts/check-plan-completeness.mjs';
+/** Both interpolated knobs are shell-spliced, so both get the same build-time shape check. */
+function assertAbsoluteNoTraversal(value, knob) {
+    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, featureDir, tier) {
+export function planCompletenessGateCmd(repo, featureDir, tier, opts) {
     const q = (s) => "'" + 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');
 }
 /**
  * PARSE-NEVER-SYNTHESIZE. An empty reply, a reply with no verdict line, a missing/unknown exit code,
@@ -1243,6 +1684,278 @@ export function parsePlanGateVerdict(raw) {
         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, slug) {
+    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, ws) {
+    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;
+}
+/**
+ * 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) {
+    // 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(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 = {
+        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 };
+}
+/**
+ * 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) {
+    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 };
+}
+/**
+ * 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, inScopePaths) {
+    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) => {
+        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 = [];
+    const outOfScope = [];
+    const unlocatable = [];
+    // 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) => /[\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 };
+}
+/**
+ * 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, declared) {
+    const out = new Map();
+    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, after) {
+    if (before === null || before === undefined || after === null || after === undefined)
+        return null;
+    const changed = [];
+    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) {
+    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';
 }
 //# sourceMappingURL=feature-adr-routing.js.map