@event4u/agent-config 16.1.0 → 16.3.0

package/src/scripts/self_review_gate.ts

@@ -34,7 +34,13 @@ import { appendFileSync, existsSync, readFileSync, writeFileSync } from 'node:fs
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-import { AnthropicClient, load_anthropic_key } from './ai_council/clients.js';
+import { CLI_CONSUMER_SELF_REVIEW } from './ai_council/cli_call_budget.js';
+import {
+    AnthropicClient,
+    AnthropicCliClient,
+    type ExternalAIClient,
+    load_anthropic_key,
+} from './ai_council/clients.js';
 import { independenceFields } from './_lib/review_independence.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -50,6 +56,15 @@ export interface Finding {
     title: string;
     detail: string;
     file?: string;
+    /**
+     * Set when the tree mechanically DISPROVES the finding's premise — today
+     * only for the deletion class: the finding says an artifact was removed,
+     * the range deletes nothing by that name, and the artifact is still in the
+     * tree. Carries the disproof, so the finding stays readable rather than
+     * disappearing. A finding carrying this is not merge-blocking; see
+     * `classifyBlocking`.
+     */
+    contradicted?: string;
 }
 
 /**
@@ -74,6 +89,13 @@ export function findingId(f: Pick<Finding, 'kind' | 'title' | 'file'>): string {
  * block ONLY on the narrow security/claim × {critical,high} intersection.
  */
 export function classifyBlocking(f: Finding): boolean {
+    // A premise the tree DISPROVES cannot block a merge. This is not leniency
+    // and not a heuristic: `contradicted` is set only where a deletion claim
+    // was checked against `git diff --name-status base...HEAD` AND against the
+    // working tree, and both said the named artifact is present and undeleted.
+    // See `contradictedByTree` for why this class needed a mechanical disproof
+    // rather than one more sentence in the prompt.
+    if ((f.contradicted ?? '').trim() !== '') return false;
     return (f.kind === 'security' || f.kind === 'claim') && (f.severity === 'critical' || f.severity === 'high');
 }
 
@@ -120,6 +142,271 @@ function changedFiles(baseRef: string, cwd: string = REPO_ROOT): string[] {
         .filter(isReviewablePath);
 }
 
+/**
+ * The paths the range actually DELETES, from `git diff --name-status`.
+ *
+ * Deliberately NOT filtered by `isReviewablePath`: the question this answers is
+ * "did the range remove this artifact", and a removal under `dist/agent-src/`
+ * is a removal even though the projection is never sent to the reviewer. A
+ * filter here would turn a real deletion into a disproof of itself.
+ *
+ * Renames are reported by `--name-status` as `R<score>\told\tnew`, and the old
+ * path IS gone, so it is counted. A roadmap moved into `archive/` shows up as a
+ * genuine deletion of its old path, which is exactly the reading a finding
+ * about that path deserves.
+ */
+export function rangeDeletions(baseRef: string, cwd: string = REPO_ROOT): Set<string> {
+    return parseDeletions(nameStatusText(baseRef, cwd));
+}
+
+/**
+ * The paths the range MODIFIES, adds, or renames TO — everything it touched
+ * that still has a path afterwards.
+ *
+ * The complement of `rangeDeletions` over the same `--name-status` output, and
+ * the input `contradictedByTree` needs to tell "the range did not touch this"
+ * from "the range changed the inside of this". Unfiltered for the same reason
+ * `rangeDeletions` is: the question is what the RANGE did, not what the
+ * reviewer was sent.
+ */
+export function rangeModifications(baseRef: string, cwd: string = REPO_ROOT): Set<string> {
+    return parseModifications(nameStatusText(baseRef, cwd));
+}
+
+/** One `--name-status` read, shared by both parses so the range is read once. */
+function nameStatusText(baseRef: string, cwd: string = REPO_ROOT): string {
+    const r = spawnSync('git', ['-c', 'core.quotePath=false', 'diff', '--name-status', `${baseRef}...HEAD`], {
+        cwd,
+        encoding: 'utf8',
+    });
+    if (r.status !== 0) {
+        throw new Error(`git diff --name-status failed: ${(r.stderr ?? '').toString().slice(0, 300)}`);
+    }
+    return r.stdout ?? '';
+}
+
+/** Pure core of `rangeDeletions`, so the parse is testable without a repo. */
+export function parseDeletions(nameStatus: string): Set<string> {
+    const out = new Set<string>();
+    for (const line of nameStatus.split('\n')) {
+        const cols = line.split('\t');
+        const status = (cols[0] ?? '').trim();
+        if (status === '') continue;
+        if (status === 'D' && cols[1]) out.add(cols[1].trim());
+        // A rename removes its OLD path; `R100\told\tnew` puts it in column 1.
+        if (status.startsWith('R') && cols[1]) out.add(cols[1].trim());
+    }
+    return out;
+}
+
+/**
+ * Pure core of `rangeModifications` — every path the range left standing.
+ *
+ * A `D` row contributes nothing. A rename contributes its NEW path (column 2),
+ * never its old one: the old path is a deletion and is parsed as such. Every
+ * other status (`M`, `A`, `C`, `T`, and the `U` of an unmerged path) has its
+ * path in column 1 and that path exists after the range.
+ */
+export function parseModifications(nameStatus: string): Set<string> {
+    const out = new Set<string>();
+    for (const line of nameStatus.split('\n')) {
+        const cols = line.split('\t');
+        const status = (cols[0] ?? '').trim();
+        if (status === '' || status === 'D') continue;
+        // `R<score>\told\tnew` / `C<score>\tsrc\tdest` — the surviving path is column 2.
+        const col = status.startsWith('R') || status.startsWith('C') ? cols[2] : cols[1];
+        if (col) out.add(col.trim());
+    }
+    return out;
+}
+
+/**
+ * Names a finding points at: its `file`, plus every backticked token in the
+ * title and detail that could be a path or an artifact directory name.
+ *
+ * Backticks are the convention the review prompt asks for and the one every
+ * measured finding used, so this reads what the model actually writes rather
+ * than guessing at prose.
+ */
+export function namedArtifacts(f: Pick<Finding, 'title' | 'detail' | 'file'>): string[] {
+    const out = new Set<string>();
+    if (f.file) out.add(f.file);
+    for (const m of `${f.title}\n${f.detail}`.matchAll(/`([^`\n]{2,120})`/g)) {
+        const tok = (m[1] ?? '').trim();
+        // A token with whitespace is prose in backticks, not a name.
+        if (tok !== '' && !/\s/.test(tok)) out.add(tok);
+    }
+    return [...out];
+}
+
+/** Does the finding's text assert that something was removed from the tree? */
+export function assertsDeletion(f: Pick<Finding, 'title' | 'detail'>): boolean {
+    return /\b(deleted|removed|deletion|removal)\b/i.test(`${f.title}\n${f.detail}`);
+}
+
+/**
+ * The disproof, or null when there is none.
+ *
+ * WHY THIS IS MECHANICAL AND NOT A PROMPT LINE. The review runs over a
+ * per-file PARTITION of the span and, on a large release, over only part of it
+ * — 202 of 401 files at the 16.1.0 cut. A reviewer holding half the files
+ * cannot distinguish "this artifact is absent from my chunk" from "this
+ * artifact was deleted", and on that cut it reported two `critical security`
+ * deletions of skills the range never touched. Both blocked the release and
+ * cost a full adjudication cycle each.
+ *
+ * The prompt already carries a sentence for the neighbouring class ("Do NOT
+ * report a feature as not in the diff when it is present in the release
+ * range") and the same run violated it, which is the evidence that a sentence
+ * is not the control here.
+ *
+ * The test is conservative in the direction that matters: a disproof needs a
+ * named artifact that is BOTH absent from the range's deletion set AND present
+ * in the tree AND untouched by the range.
+ *
+ * THE THIRD HALF, AND WHY IT WAS MISSING. The first two were written against
+ * WHOLE-FILE deletion, where "a genuine deletion satisfies neither half" is
+ * true. It is false for a removal asserted INSIDE a file: "digest verification
+ * was removed in `install.ts`" names a path the range MODIFIED, so the path is
+ * absent from the deletion set and present in the tree, and the finding was
+ * de-blocked as though it had been checked. A path the range modified is
+ * evidence the range touched that artifact — the opposite of this disproof's
+ * premise — so it can no longer carry one.
+ *
+ * WHAT THIS GATE STILL CANNOT DECIDE, and says nothing about. The disproof is
+ * built entirely out of PATHS: the deletion set, the modification set, and the
+ * working tree. A claim about something that has no path of its own — a
+ * symbol, an export, a config key, a behaviour, a sentence inside a surviving
+ * file — cannot be resolved to a candidate, so no half of the test applies and
+ * the finding is returned unannotated. That is the intended reading: the gate
+ * cannot decide such a claim, it is not asserting the claim is true, and an
+ * operator adjudicating the block is reading an UNCHECKED finding rather than
+ * an unrefuted one. Widening the test to cover that class would mean deciding
+ * a claim from the same partition the reviewer had, which is the fabrication
+ * this mechanism exists to absorb.
+ */
+export function contradictedByTree(
+    f: Pick<Finding, 'title' | 'detail' | 'file'>,
+    deleted: ReadonlySet<string>,
+    exists: (p: string) => boolean,
+    modified: ReadonlySet<string> = new Set<string>(),
+): string | null {
+    if (!assertsDeletion(f)) return null;
+    for (const name of namedArtifacts(f)) {
+        // Any deletion whose path mentions the token leaves the claim standing.
+        if ([...deleted].some((d) => d === name || d.includes(name))) continue;
+        const candidates = [name, `src/skills/${name}/SKILL.md`, `src/rules/${name}.md`, `src/scripts/${name}`];
+        // The range touched something this token resolves to — a whole-artifact
+        // disproof cannot be read off a path the range changed. Checked over
+        // EVERY candidate, not only the one `exists` happens to hit first: the
+        // conservative direction is fewer disproofs, never more.
+        if (candidates.some((c) => modified.has(c))) continue;
+        const hit = candidates.find((c) => exists(c));
+        if (hit !== undefined) {
+            return (
+                `the range deletes nothing matching \`${name}\`, and \`${hit}\` is present in the tree — ` +
+                'checked against `git diff --name-status base...HEAD` and the working tree, not against the review chunk.'
+            );
+        }
+    }
+    return null;
+}
+
+/**
+ * The two counts road-to-a-fact-plane Step 2.3 pre-registers as its falsifier,
+ * written into the findings artifact so the next cut can be read rather than
+ * recomputed.
+ *
+ * `asserting_removal` is the population — findings that make a checkable
+ * factual claim of the deletion class. `disproved_by_tree` is how many of them
+ * the range and the tree refuted. The premise of the fact block is that
+ * supplying the range's facts lowers the first and, with it, the second; a
+ * `disproved_by_tree` that does not fall after the block ships is the honest
+ * null, and the roadmap records that result rather than widening the mechanism
+ * to chase it.
+ *
+ * Every recorded cut so far reports `disproved_by_tree` as 0 for a reason that
+ * is not a measurement: the annotation pass landed after the last of them, so
+ * the number was never produced. The baseline is "never observed", not
+ * "observed as zero", and the first cut after this change is the first reading.
+ */
+export function factClaimCounts(findings: readonly Finding[]): {
+    asserting_removal: number;
+    disproved_by_tree: number;
+} {
+    return {
+        asserting_removal: findings.filter((f) => assertsDeletion(f)).length,
+        disproved_by_tree: findings.filter((f) => (f.contradicted ?? '').trim() !== '').length,
+    };
+}
+
+/** Render one list of the fact block, or an explicit `(none)`. */
+function factList(label: string, paths: readonly string[]): string {
+    const head = `${label} — ${String(paths.length)}:`;
+    return paths.length === 0 ? `${head}\n  (none)` : `${head}\n${paths.map((p) => `  ${p}`).join('\n')}`;
+}
+
+/**
+ * The range's facts, serialised for the reviewer.
+ *
+ * WHY THE REVIEWER IS HANDED THESE RATHER THAN LEFT TO INFER THEM. The review
+ * runs over a per-file PARTITION of the span and, on a large release, over only
+ * part of it — 202 of 401 files at the 16.1.0 cut. From inside one chunk, "this
+ * path is not in front of me" and "this path was deleted" are the same
+ * observation, and on that cut the model resolved the ambiguity the wrong way
+ * twice, in `critical security` findings that each cost an adjudication cycle.
+ * `contradictedByTree` catches that class AFTER the spend; this block removes
+ * the inference that produces it.
+ *
+ * Exactly three lists, all of them already computed by this gate: the paths the
+ * range deleted, the paths it changed and left standing, and the working tree's
+ * presence check over both — reported by its EXCEPTIONS, because the normal
+ * case is empty and a third full copy of the same paths would spend budget on
+ * a line the reviewer can derive. Nothing else is added: the block is paths, so
+ * it scales with file count and not with change size, and the six-request
+ * ceiling stays a budget question this does not reopen.
+ */
+export function factBlock(
+    deleted: ReadonlySet<string>,
+    modified: ReadonlySet<string>,
+    exists: (p: string) => boolean,
+): string {
+    const del = [...deleted].sort();
+    const mod = [...modified].sort();
+    return [
+        '=== RANGE FACTS (AUTHORITATIVE) ===',
+        'Read from `git diff --name-status <base>...HEAD` and from the working tree,',
+        'NOT from the diff below. The diff below is ONE PARTITION of this range: a',
+        'path missing from it is a path outside your chunk, never a deleted path.',
+        'A claim that contradicts these lists is a defect in the finding, not a',
+        'finding about the tree — do not report it.',
+        '',
+        factList('DELETED BY THIS RANGE', del),
+        '',
+        factList('CHANGED BY THIS RANGE, AND THE TREE HOLDS THEM', mod),
+        '',
+        'PRESENCE CHECK (exceptions to the two lists above):',
+        factList('  deleted, yet still present in the working tree', del.filter((p) => exists(p))),
+        factList('  changed, yet absent from the working tree', mod.filter((p) => !exists(p))),
+        '=== END RANGE FACTS ===',
+        '',
+        '',
+    ].join('\n');
+}
+
+/** Annotate every finding the tree disproves. Pure given `deleted` + `exists`. */
+export function annotateContradicted(
+    findings: readonly Finding[],
+    deleted: ReadonlySet<string>,
+    exists: (p: string) => boolean,
+    modified: ReadonlySet<string> = new Set<string>(),
+): Finding[] {
+    return findings.map((f) => {
+        const why = contradictedByTree(f, deleted, exists, modified);
+        return why === null ? f : { ...f, contradicted: why };
+    });
+}
+
 function diffText(baseRef: string, files: string[], cwd: string = REPO_ROOT): string {
     if (files.length === 0) return '';
     const r = spawnSync('git', ['diff', `${baseRef}...HEAD`, '--', ...files], {
@@ -459,6 +746,14 @@ export interface ReviewPlan {
      * it thrown away.
      */
     partition: DiffPartition;
+    /**
+     * The range facts prepended to EVERY request — see `factBlock`.
+     *
+     * Computed in the plan rather than at send time so `--dry-run` can print
+     * the request the live run would send, and so the partition budget can
+     * reserve the block's length instead of discovering it after the split.
+     */
+    facts: string;
     /** Model calls the live run will make — one per budgeted chunk. */
     requests: number;
     /** Files no request will carry, with the reason. */
@@ -499,22 +794,33 @@ export function buildPlan(baseRef: string, cwd: string = REPO_ROOT): ReviewPlan
     // REQUEST COUNT rather than only a token estimate. This gate spends money
     // per request, and a plan that reports "~N tokens" without saying how many
     // calls that becomes hides the number the maintainer is deciding about.
-    const partition = partitionDiff(perFileDiffs(analysisBase, files, cwd));
+    // The facts ride on every request, so the per-request diff budget has to
+    // pay for them. Reserving here rather than at send time is what keeps the
+    // block from silently pushing a chunk over the provider's cap — the exact
+    // failure four consecutive releases already spent a review on.
+    const facts = factBlock(rangeDeletions(analysisBase, cwd), rangeModifications(analysisBase, cwd), (p) =>
+        existsSync(path.join(cwd, p)),
+    );
+    const partition = partitionDiff(
+        perFileDiffs(analysisBase, files, cwd),
+        Math.max(1, PROMPT_BUDGET_CHARS - facts.length),
+    );
     return {
         partition,
+        facts,
         requests: partition.chunks.length,
         unreviewed: partition.unreviewed,
         skills: [...REVIEW_SKILLS],
         files,
         analysisBase,
         ...(release ? { release } : {}),
-        promptChars: systemPrompt.length + diff.length,
+        promptChars: systemPrompt.length + facts.length + diff.length,
         escalation,
         note:
             files.length === 0
                 ? 'No reviewable (non-generated) files changed — the live review would no-op.'
                 : `${files.length} reviewable file(s); live review would send ~${Math.ceil(
-                      (systemPrompt.length * Math.max(1, partition.chunks.length) + diff.length) /
+                      ((systemPrompt.length + facts.length) * Math.max(1, partition.chunks.length) + diff.length) /
                           BUDGET_CHARS_PER_TOKEN,
                   )} input tokens across ${partition.chunks.length} request(s)` +
                   (partition.unreviewed.length > 0
@@ -639,7 +945,11 @@ export function renderReview(findings: Finding[], enforce: boolean, escalation:
     // read as inconsistent with the narrow `blocking.length` verdict count.
     const rows = findings
         .map((f) => {
-            const marker = classifyBlocking(f) ? 'Blocking' : 'Advisory';
+            const marker = (f.contradicted ?? '') !== ''
+                ? 'Contradicted'
+                : classifyBlocking(f)
+                    ? 'Blocking'
+                    : 'Advisory';
             return `| ${findingId(f)} | ${f.severity} (${marker}) | ${f.kind} | ${f.file ?? '—'} | ${f.title} |`;
         })
         .join('\n');
@@ -653,6 +963,12 @@ export function renderReview(findings: Finding[], enforce: boolean, escalation:
     // 12-hex id looks exactly like a short SHA, so the rendered comment now says
     // what it is and where its disposition lives. This is the only place a reader
     // of the comment can learn it without opening the source.
+    const contradicted = findings.filter((f) => (f.contradicted ?? '') !== '');
+    const contradictedNote = contradicted.length === 0
+        ? ''
+        : '\n\n**Contradicted by the tree** — these assert a removal the range does not contain, '
+            + 'so they are reported and NOT counted as blocking:\n'
+            + contradicted.map((f) => `- \`${findingId(f)}\` ${f.title} — ${f.contradicted ?? ''}`).join('\n');
     const idNote =
         '\n\n`id` above is a FINDING id — the first 12 hex of sha256(kind|title|file), '
         + '**not a commit SHA**. Searching the git log for it finds nothing, by design. '
@@ -662,9 +978,20 @@ export function renderReview(findings: Finding[], enforce: boolean, escalation:
     // demands committed dispositions. The comment is transport, never the
     // record — the record is `agents/evidence/release-findings/<version>.json`.
     const machine = `\n\n<!-- release-findings-json: ${JSON.stringify(
-        findings.map((f) => ({ finding_id: findingId(f), severity: f.severity, kind: f.kind, title: f.title, file: f.file ?? null })),
+        findings.map((f) => ({
+            finding_id: findingId(f),
+            severity: f.severity,
+            kind: f.kind,
+            title: f.title,
+            file: f.file ?? null,
+            // Carried into the trigger block, not only the rendered table: the
+            // PR-comment path of `check_finding_dispositions` reads THIS, and
+            // would otherwise demand a disposition for a claim the tree already
+            // disproved.
+            ...((f.contradicted ?? '') !== '' ? { contradicted: f.contradicted } : {}),
+        })),
     )} -->`;
-    return `${banner}\n\n${verdictLine}\n\n| id | severity | kind | file | finding |\n|---|---|---|---|---|\n${rows}${idNote}${cov}${esc}${machine}`;
+    return `${banner}\n\n${verdictLine}\n\n| id | severity | kind | file | finding |\n|---|---|---|---|---|\n${rows}${contradictedNote}${idNote}${cov}${esc}${machine}`;
 }
 
 function postReview(body: string): void {
@@ -691,6 +1018,49 @@ function resolveKey(): string | null {
     }
 }
 
+/** The transport a reviewer was reached on, for the run's own report. */
+interface Reviewer {
+    client: ExternalAIClient;
+    transport: 'cli' | 'api';
+    how: string;
+}
+
+/**
+ * Resolve the review client CLI-FIRST — the subscription transport before the
+ * metered one, which is the ordering the rest of this suite already uses for
+ * coding work and which the council has used since it grew a `mode: cli`.
+ *
+ * The ordering is not a preference. An API key is a METERED resource with a
+ * balance that runs out, and when it does the gate reports NEUTRAL — a release
+ * then carries no review at all. That is not hypothetical: it is how 16.3.0
+ * stalled, with six chunks returning `credit balance is too low` and the
+ * release step refusing for want of a findings artefact. A vendor CLI backed by
+ * a subscription has no balance to exhaust, so trying it first removes the one
+ * failure mode that has actually produced an unreviewed release here.
+ *
+ * `AnthropicCliClient`'s constructor THROWS when `claude` is not on PATH, which
+ * is the probe: a hosted GitHub runner has no vendor CLI and falls straight
+ * through to the API transport, so this change costs CI nothing and buys every
+ * local and self-hosted run a free review. The catch is deliberately broad —
+ * anything that goes wrong reaching for the CLI resolves to the API path rather
+ * than to a NEUTRAL, because a reviewed release beats a diagnosed one.
+ *
+ * Calls book against `CLI_CONSUMER_SELF_REVIEW` so the daily CLI counter can
+ * tell a review apart from a council round; without the attribution the gate's
+ * six chunks would read as unexplained council spend.
+ */
+function resolveReviewer(): Reviewer | null {
+    try {
+        const client = new AnthropicCliClient({ consumer: CLI_CONSUMER_SELF_REVIEW });
+        return { client, transport: 'cli', how: `vendor CLI (${client.binary}), subscription` };
+    } catch {
+        // No `claude` on PATH, or the client refused to construct. Fall through.
+    }
+    const key = resolveKey();
+    if (!key) return null;
+    return { client: new AnthropicClient({ api_key: key }), transport: 'api', how: 'ANTHROPIC_API_KEY' };
+}
+
 // ── CLI ───────────────────────────────────────────────────────────────
 export function main(argv: string[]): 0 | 2 {
     const dryRun = argv.includes('--dry-run');
@@ -700,6 +1070,16 @@ export function main(argv: string[]): 0 | 2 {
 
     const plan = buildPlan(baseRef);
 
+    // The request the live run would send, verbatim and unspent. A summary
+    // would be this script's description of the request rather than the
+    // request, and the whole point of the fact block is that what the reviewer
+    // is handed can be read rather than inferred — including by a maintainer.
+    if (argv.includes('--print-request')) {
+        const first = plan.partition.chunks[0];
+        process.stdout.write(plan.facts + (first?.text ?? '(no chunk — nothing to review in this range)\n'));
+        return 0;
+    }
+
     if (dryRun) {
         process.stdout.write(
             `self-review-gate (dry-run — no spend, advisory):\n` +
@@ -756,22 +1136,28 @@ export function main(argv: string[]): 0 | 2 {
         return 0;
     }
 
-    const key = resolveKey();
-    if (!key) {
+    const reviewer = resolveReviewer();
+    if (!reviewer) {
         // Explicit NEUTRAL state — never a bare green that reads as "reviewed".
+        // BOTH transports are named, because naming only the API one is what
+        // made the CLI path invisible: an operator reading this warning set the
+        // secret and never learned a logged-in `claude` would also have served.
         process.stdout.write(
-            '::warning::self-review-gate NEUTRAL — no ANTHROPIC_API_KEY configured, NOTHING was reviewed. ' +
-                'Set the repo secret to enable the live dogfooded review.\n',
+            '::warning::self-review-gate NEUTRAL — no reviewer reachable (no `claude` CLI on PATH, ' +
+                'no ANTHROPIC_API_KEY), NOTHING was reviewed. Log in to the vendor CLI or set the ' +
+                'repo secret to enable the live dogfooded review.\n',
         );
         const summary = process.env.GITHUB_STEP_SUMMARY;
         if (summary) {
             appendFileSync(
                 summary,
-                '### Self-review gate: NEUTRAL\n\nNo `ANTHROPIC_API_KEY` secret — nothing was reviewed. This is not a pass.\n',
+                '### Self-review gate: NEUTRAL\n\nNo reviewer reachable — neither the `claude` CLI ' +
+                    '(subscription) nor `ANTHROPIC_API_KEY` (metered). Nothing was reviewed. This is not a pass.\n',
             );
         }
         return 0;
     }
+    process.stdout.write(`::notice::self-review-gate — transport: ${reviewer.transport} (${reviewer.how}).\n`);
 
     // Belt-and-suspenders: the WHOLE live path is wrapped so that ANYTHING going
     // wrong — no API credit / balance (HTTP 402), rate-limit (429), network error,
@@ -780,7 +1166,7 @@ export function main(argv: string[]): 0 | 2 {
     // gate is advisory by design. (Only an --enforce run with real blocking
     // findings returns 2 — an error is not a finding.)
     try {
-        const client = new AnthropicClient({ api_key: key });
+        const client = reviewer.client;
         const systemPrompt = buildSystemPrompt(plan.release, baseRef);
         const partition = plan.partition;
 
@@ -812,7 +1198,10 @@ export function main(argv: string[]): 0 | 2 {
         let reviewedChunks = 0;
         let filesRead = 0;
         for (const [i, chunk] of partition.chunks.entries()) {
-            const resp = client.ask(systemPrompt, chunk.text, 4096);
+            // Facts FIRST, then the partition. The reviewer reads what the
+            // range did before it reads the fragment it was given, so "absent
+            // from my chunk" can no longer be mistaken for "deleted".
+            const resp = client.ask(systemPrompt, plan.facts + chunk.text, 4096);
             if (resp.error) {
                 process.stdout.write(
                     `::warning::self-review-gate — chunk ${String(i + 1)}/` +
@@ -854,6 +1243,16 @@ export function main(argv: string[]): 0 | 2 {
             filesTotal: plan.files.length,
             unreviewed,
         };
+        // Ground-truth pass, ONCE, before anything reads the finding set. A
+        // deletion claim the range and the tree both disprove is annotated
+        // here and stops being merge-blocking; it is still written to the
+        // artifact and still rendered, carrying its disproof.
+        const reviewed = annotateContradicted(
+            dedupeFindings(findings),
+            rangeDeletions(baseRef),
+            (p) => existsSync(path.join(REPO_ROOT, p)),
+            rangeModifications(baseRef),
+        );
         const outIdx = argv.indexOf('--findings-out');
         if (outIdx >= 0 && argv[outIdx + 1]) {
             // Durable ingestion input for the disposition ledger (release-truth
@@ -869,7 +1268,12 @@ export function main(argv: string[]): 0 | 2 {
                         schema_version: 1,
                         ...independenceFields(['anthropic']),
                         coverage,
-                        findings: dedupeFindings(findings).map((f) => ({
+                        // Readable, not recomputable: the falsifier for the
+                        // supplied-facts change is a count over the NEXT cut,
+                        // and a number a reader has to re-derive from 50
+                        // findings is a number nobody checks.
+                        fact_claims: factClaimCounts(reviewed),
+                        findings: reviewed.map((f) => ({
                             finding_id: findingId(f),
                             ...f,
                         })),
@@ -879,10 +1283,10 @@ export function main(argv: string[]): 0 | 2 {
                 ) + '\n',
             );
         }
-        const body = renderReview(dedupeFindings(findings), enforce, plan.escalation, coverage);
+        const body = renderReview(reviewed, enforce, plan.escalation, coverage);
         postReview(body);
 
-        const code = gateVerdict(dedupeFindings(findings), { enforce });
+        const code = gateVerdict(reviewed, { enforce });
         if (code === 2) {
             process.stdout.write('::error::self-review-gate — merge-blocking findings under enforce mode.\n');
         }