@event4u/agent-config 16.3.0 → 16.4.0

package/src/scripts/report_required_checks_drift.ts

@@ -0,0 +1,196 @@
+#!/usr/bin/env tsx
+/**
+ * Required-check drift report — compares the live ruleset to the contract.
+ *
+ * `print_required_checks.ts` carries the list of status contexts the `main
+ * protection` ruleset requires, and it is contractually offline: it never calls
+ * `gh`. So nothing compared that list to the ruleset, and it drifted — it named
+ * one required context for a month after the ruleset gained a second. This
+ * report is the comparison: it reads the ruleset through `gh api`, extracts the
+ * required status contexts, and exits non-zero when they differ from
+ * `ENFORCED_CHECKS`.
+ *
+ * READ-ONLY. It writes nothing and changes nothing on the ruleset. It is run by
+ * hand or on a schedule and is NOT wired as a required check — a network read
+ * cannot sit on the path of every pull request, and the token it needs is a
+ * repository-read token, not something each PR should depend on.
+ *
+ * Usage:
+ *   ./scripts-run src/scripts/report_required_checks_drift
+ *   ./scripts-run src/scripts/report_required_checks_drift --repo <owner/name>
+ *   ./scripts-run src/scripts/report_required_checks_drift --from-json <file>
+ *
+ * `--from-json` reads a ruleset object (the shape `gh api
+ * repos/{owner}/{repo}/rulesets/{id}` returns) from a file instead of the
+ * network, so the comparison itself is testable offline.
+ *
+ * Exit codes: 0 the lists agree · 1 they differ · 2 usage error, or the ruleset
+ * could not be read or carries no required-status-checks rule.
+ */
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { ENFORCED_CHECKS } from './print_required_checks.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+
+export const RULESET_NAME = 'main protection';
+const DEFAULT_REPO = 'event4u-app/agent-config';
+
+export interface Drift {
+    readonly missingFromContract: readonly string[];
+    readonly missingFromRuleset: readonly string[];
+}
+
+class ReadError extends Error {}
+
+/** The required status contexts of one ruleset object, sorted. */
+export function requiredContexts(ruleset: unknown): string[] {
+    const rules = (ruleset as { rules?: unknown }).rules;
+    if (!Array.isArray(rules)) {
+        throw new ReadError('the ruleset object carries no `rules` array');
+    }
+    const lists = rules
+        .filter(
+            (r): r is { parameters?: { required_status_checks?: unknown } } =>
+                typeof r === 'object' && r !== null && (r as { type?: unknown }).type === 'required_status_checks',
+        )
+        .map((r) => r.parameters?.required_status_checks)
+        .filter((c): c is unknown[] => Array.isArray(c));
+    if (lists.length === 0) {
+        throw new ReadError('the ruleset has no `required_status_checks` rule');
+    }
+    // Every such rule counts: a context required by any of them blocks the merge.
+    const contexts = new Set(
+        lists
+            .flat()
+            .map((c) => (c as { context?: unknown }).context)
+            .filter((c): c is string => typeof c === 'string'),
+    );
+    return [...contexts].sort();
+}
+
+/** Set difference in both directions; empty both ways means agreement. */
+export function compare(live: readonly string[], contract: readonly string[]): Drift {
+    const liveSet = new Set(live);
+    const contractSet = new Set(contract);
+    return {
+        missingFromContract: live.filter((c) => !contractSet.has(c)).sort(),
+        missingFromRuleset: contract.filter((c) => !liveSet.has(c)).sort(),
+    };
+}
+
+function ghJson(endpoint: string, paginate = false): unknown {
+    const args = paginate ? ['api', '--paginate', '--slurp', endpoint] : ['api', endpoint];
+    const r = spawnSync('gh', args, { encoding: 'utf-8', maxBuffer: 16 * 1024 * 1024 });
+    if (r.status !== 0) {
+        throw new ReadError(`gh api ${endpoint} failed: ${(r.stderr ?? '').trim() || `exit ${String(r.status)}`}`);
+    }
+    return JSON.parse(r.stdout) as unknown;
+}
+
+function readLiveRuleset(repo: string): unknown {
+    // --paginate --slurp: one array per page, so a ruleset past the first page
+    // of 30 is still found.
+    const pages = ghJson(`repos/${repo}/rulesets`, true);
+    if (!Array.isArray(pages) || !pages.every((p) => Array.isArray(p))) {
+        throw new ReadError('the rulesets listing is not an array of pages');
+    }
+    const list = (pages as unknown[][]).flat();
+    const hit = list.find((r) => (r as { name?: unknown }).name === RULESET_NAME) as { id?: unknown } | undefined;
+    if (hit === undefined || typeof hit.id !== 'number') {
+        throw new ReadError(`no ruleset named "${RULESET_NAME}" on ${repo}`);
+    }
+    return ghJson(`repos/${repo}/rulesets/${String(hit.id)}`);
+}
+
+interface Options {
+    repo: string;
+    fromJson: string | null;
+}
+
+function parseArgs(argv: readonly string[]): Options | string {
+    let repo = DEFAULT_REPO;
+    let fromJson: string | null = null;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i] as string;
+        if (a === '--repo' || a === '--from-json') {
+            const v = argv[i + 1];
+            if (v === undefined || v.startsWith('--')) {
+                return `${a} needs a value`;
+            }
+            if (a === '--repo') {
+                repo = v;
+            } else {
+                fromJson = v;
+            }
+            i++;
+        } else {
+            return `unknown argument: ${a}`;
+        }
+    }
+    return { repo, fromJson };
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    const opts = parseArgs(argv);
+    if (typeof opts === 'string') {
+        process.stderr.write(`❌  report_required_checks_drift: ${opts}\n`);
+        process.stderr.write('usage: report_required_checks_drift [--repo OWNER/NAME] [--from-json FILE]\n');
+        return 2;
+    }
+    let live: string[];
+    try {
+        const ruleset =
+            opts.fromJson === null
+                ? readLiveRuleset(opts.repo)
+                : (JSON.parse(fs.readFileSync(opts.fromJson, 'utf-8')) as unknown);
+        live = requiredContexts(ruleset);
+    } catch (e) {
+        process.stderr.write(`❌  report_required_checks_drift: ${e instanceof Error ? e.message : String(e)}\n`);
+        return 2;
+    }
+    const drift = compare(live, ENFORCED_CHECKS);
+    const source = opts.fromJson === null ? `${opts.repo} ruleset "${RULESET_NAME}"` : opts.fromJson;
+    process.stdout.write(`required contexts read from ${source}: ${String(live.length)}\n`);
+    for (const c of live) {
+        process.stdout.write(`  - ${c}\n`);
+    }
+    if (drift.missingFromContract.length === 0 && drift.missingFromRuleset.length === 0) {
+        process.stdout.write(
+            '✅  agrees with ENFORCED_CHECKS in src/scripts/print_required_checks.ts\n',
+        );
+        return 0;
+    }
+    for (const c of drift.missingFromContract) {
+        process.stdout.write(`  ❌ required by the ruleset, absent from the contract: ${c}\n`);
+    }
+    for (const c of drift.missingFromRuleset) {
+        process.stdout.write(`  ❌ named by the contract, not required by the ruleset: ${c}\n`);
+    }
+    process.stdout.write(
+        '❌  drift — update ENFORCED_CHECKS and docs/contracts/branch-protection-policy.md ' +
+            'together, with the date the ruleset was read.\n',
+    );
+    return 1;
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    if (pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url) {
+        return true;
+    }
+    try {
+        return fs.realpathSync(path.resolve(process.argv[1])) === fs.realpathSync(_HERE);
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    process.exitCode = main();
+}

package/src/scripts/report_skill_ranker_confusion.ts

@@ -55,7 +55,7 @@ import {
     sliceForId,
     sliceSizes,
 } from './measure_skill_ranker_baseline.js';
-import { _globSkillMd, rank, type RankRow } from './skill_tools/score_skill_relevance.js';
+import { _globSkillMd, rank, rankDetailed, type RankRow } from './skill_tools/score_skill_relevance.js';
 
 /** How deep "outside the top ten" is. 1.3's own number, not a derived one. */
 export const DEEP_MISS_DEPTH = 10;
@@ -92,6 +92,38 @@ export interface RowReading {
     rankedFirst: string | null;
     topScore: number;
     rankOfExpected: number;
+    /** An expected skill shares the winner's integer score (hit or miss). */
+    expectedInTopScoreBlock: boolean;
+    /** An expected skill shares the winner's whole ordering key and loses on name. */
+    lostOnTie: boolean;
+}
+
+/**
+ * The two tie readings for one ranking.
+ *
+ * `inBlock` asks whether an expected skill scored the winner's INTEGER — the
+ * block the alphabet orders under `keyword-v1`. `lostOnTie` asks whether the
+ * row was a top-1 miss that nothing but the name decided: the expected skill
+ * shares the winner's integer score and, under `tieBreakUnrounded`, its
+ * unrounded score too. Without the flag the two keys coincide, so `lostOnTie`
+ * is the evidence page's "scored exactly the winner's score and lost on its
+ * initial" class; with it, `lostOnTie` is what the unrounded score left.
+ */
+export function tieReading(
+    rows: readonly RankRow[],
+    raw: ReadonlyMap<string, number>,
+    expected: readonly string[],
+    tieBreakUnrounded: boolean,
+): { inBlock: boolean; lostOnTie: boolean } {
+    const first = rows[0];
+    if (!first) return { inBlock: false, lostOnTie: false };
+    const block = rows.filter((r) => r[1] === first[1]);
+    const inBlock = block.some((r) => expected.includes(r[0]));
+    if (!inBlock || expected.includes(first[0])) return { inBlock, lostOnTie: false };
+    const lostOnTie = block.some(
+        (r) => expected.includes(r[0]) && (!tieBreakUnrounded || raw.get(r[0]) === raw.get(first[0])),
+    );
+    return { inBlock, lostOnTie };
 }
 
 export function readRows(
@@ -101,13 +133,16 @@ export function readRows(
 ): RowReading[] {
     const opts = rankOptionsFor(ranker);
     return prompts.map((p) => {
-        const rows = rank(p.prompt, skillsDir, opts);
+        const { rows, raw } = rankDetailed(p.prompt, skillsDir, opts);
+        const tie = tieReading(rows, raw, p.expected, Boolean(opts.tieBreakUnrounded));
         return {
             id: p.id,
             expected: p.expected,
             rankedFirst: rows[0]?.[0] ?? null,
             topScore: rows[0]?.[1] ?? 0,
             rankOfExpected: firstExpectedRank(rows, p.expected),
+            expectedInTopScoreBlock: tie.inBlock,
+            lostOnTie: tie.lostOnTie,
         };
     });
 }
@@ -262,6 +297,41 @@ export function falseActivation(
     };
 }
 
+export interface AbstentionReading {
+    empties: number;
+    /** Empties whose top score is 0 — the ranker already abstains. */
+    noSkill: number;
+    threshold: number | null;
+    /** Empties whose top score is below `threshold`. */
+    abstainedEmpties: number;
+    correctHits: number;
+    /** Correct top-1 hits whose top score is below `threshold`. */
+    hitsLost: number;
+}
+
+/**
+ * What abstaining below one threshold buys on the empties and costs on the hits.
+ *
+ * A `null` threshold reads the no-skill rate only: with no correct hit there is
+ * no recall to cost, and inventing a cutoff would put a number chosen here
+ * beside a measured one.
+ */
+export function abstentionReading(
+    labelled: readonly RowReading[],
+    emptyTopScores: readonly number[],
+    threshold: number | null,
+): AbstentionReading {
+    const hits = labelled.filter((r) => r.rankOfExpected === 1);
+    return {
+        empties: emptyTopScores.length,
+        noSkill: emptyTopScores.filter((s) => s === 0).length,
+        threshold,
+        abstainedEmpties: threshold === null ? 0 : emptyTopScores.filter((s) => s < threshold).length,
+        correctHits: hits.length,
+        hitsLost: threshold === null ? 0 : hits.filter((r) => r.topScore < threshold).length,
+    };
+}
+
 function interval(successes: number, trials: number): string {
     const raw = wilsonInterval(successes, trials);
     return `${round3(raw.lower).toFixed(3)} – ${round3(raw.upper).toFixed(3)}`;
@@ -286,6 +356,8 @@ export function renderReport(opts: {
     const misses = readings.filter((r) => r.rankOfExpected !== 1);
     const deep = misses.filter((r) => r.rankOfExpected === 0 || r.rankOfExpected > DEEP_MISS_DEPTH).length;
     const mrr = meanReciprocalRank(readings);
+    const tieLoss = readings.filter((r) => r.lostOnTie).length;
+    const inBlock = readings.filter((r) => r.expectedInTopScoreBlock).length;
 
     const empties = emptyRowIds(opts.repo, opts.slice);
     const rankOpts = rankOptionsFor(opts.ranker);
@@ -368,6 +440,18 @@ export function renderReport(opts: {
     L.push('of the existing signal can recover a skill the formula never surfaces. The two');
     L.push('take different fixes, which is why the split is reported rather than an average.');
     L.push('');
+    L.push('## Ties');
+    L.push('');
+    L.push('| metric | rows | share of rows read |');
+    L.push('|---|---:|---:|');
+    L.push(`| \`top1_loss_due_to_tie\` | ${String(tieLoss)} | ${pct(tieLoss, n)} |`);
+    L.push(`| \`expected_in_top_score_block\` | ${String(inBlock)} | ${pct(inBlock, n)} |`);
+    L.push('');
+    L.push('`top1_loss_due_to_tie` counts top-1 misses where an expected skill shares the');
+    L.push('winner\'s whole ordering key and loses on the name alone — the integer score, and');
+    L.push('under `tieBreakUnrounded` the unrounded score as well. `expected_in_top_score_block`');
+    L.push('counts rows, hit or miss, whose expected skill scores the winner\'s integer.');
+    L.push('');
     L.push('## False activation on the no-skill prompts');
     L.push('');
     L.push('| | |');
@@ -393,6 +477,23 @@ export function renderReport(opts: {
     L.push('populations at all. A share near one half means it does not: a prompt a seat');
     L.push('judged to have no skill answer is scored as confidently as a prompt it got right.');
     L.push('');
+    const ab = abstentionReading(readings, emptyScores, fa.correct_hits > 0 ? fa.median_correct_hit_score : null);
+    L.push('## Abstention, beside its cost');
+    L.push('');
+    L.push('| | |');
+    L.push('|---|---:|');
+    L.push(`| empties the ranker already returns nothing for (no-skill rate) | ${String(ab.noSkill)} of ${String(ab.empties)} (${pct(ab.noSkill, ab.empties)}) |`);
+    if (ab.threshold === null) {
+        L.push('| abstention threshold | n/a — no correct top-1 hit, so no threshold |');
+    } else {
+        L.push(`| abstention threshold (abstain below the median correct-hit score) | ${String(ab.threshold)} |`);
+        L.push(`| empties that threshold abstains on | ${String(ab.abstainedEmpties)} of ${String(ab.empties)} (${pct(ab.abstainedEmpties, ab.empties)}) |`);
+        L.push(`| correct top-1 hits it would suppress (recall cost) | ${String(ab.hitsLost)} of ${String(ab.correctHits)} (${pct(ab.hitsLost, ab.correctHits)}) |`);
+    }
+    L.push('');
+    L.push('One threshold, the same median the false-activation table compares against, so');
+    L.push('the gain on the empties and the recall it costs are read off one number.');
+    L.push('');
     L.push(`## Per-pack top-1, worst first`);
     L.push('');
     L.push('| pack | labelled rows | top-1 |');

package/src/scripts/report_standing_payload_by_host.ts

@@ -229,7 +229,7 @@ export const HOST_SURFACES: readonly HostSurface[] = [
     },
     {
         host: 'codex', surface: '.codex/agent-config.md', perRuleTree: false,
-        writer: 'src/scripts/install.ts:1382',
+        writer: 'src/scripts/install.ts:1377',
         // Scoped to `.codex` rather than the bare filename: nine other lines in
         // `install.ts` write an `agent-config.md` for some other host, so the
         // unscoped anchor would have accepted a drift onto any of them — the

package/src/scripts/routing_doctor.ts

@@ -355,10 +355,10 @@ export function collect_orchestration(
   platform_assumed: boolean,
 ): OrchestrationReport {
   const settings = load_agent_settings({ cwd: workspace_root });
-  const sub = (settings["subagents"] ?? {}) as Record<string, unknown>;
   const emergency = (settings["emergency"] ?? {}) as Record<string, unknown>;
   const halted = emergency["orchestration_halt"] === true;
-  const downshift = sub["downshift"] !== false;
+  // Fixed on: the `subagents.downshift` key was retired with this default.
+  const downshift = true;
   const { manifest: host_manifest, sources: host_manifest_sources } =
     describeHostCapabilities(platform);
   const activationInputs: ActivationInputs = {

package/src/scripts/schemas/agent-settings.schema.json

@@ -11,17 +11,6 @@
       "enum": ["minimal", "balanced", "full", "custom"],
       "description": "Rule-tier loading footprint. See docs/contracts/cost-profile-defaults.md and docs/contracts/rule-router.md. NOT a memory or model lever."
     },
-    "memory": {
-      "type": "object",
-      "additionalProperties": true,
-      "properties": {
-        "cadence": {
-          "type": "string",
-          "enum": ["auto", "always", "never"],
-          "description": "Cadence of the 🧠 memory-visibility line. See docs/contracts/memory-visibility-v1.md. Owns its own key since the 2026-06-01 untangle; previously collided with rule_loading_tier."
-        }
-      }
-    },
     "model": {
       "type": "object",
       "additionalProperties": true,
@@ -79,25 +68,34 @@
         }
       }
     },
-    "design": {
+    "git": {
       "type": "object",
       "additionalProperties": true,
       "properties": {
-        "fidelity_mode": {
+        "commit_format": {
           "type": "string",
-          "enum": ["strict", "structural", "hard-floor"],
-          "description": "How strictly the agent must follow a user-provided prototype / mockup / design system. Consumed by the design-fidelity rule. strict = build 1:1, every visible deviation needs confirmation; structural = structure locked, silent gaps fillable with a stated assumption; hard-floor = any deviation is never autonomous."
+          "enum": ["ticket-scope", "ticket-conventional"],
+          "description": "Where a ticket id goes in a commit subject. ticket-scope (default) = `feat(DEV-1234): …`; ticket-conventional = `DEV-1234 feat(area): …`, a ticket is never a scope."
+        },
+        "branch_pattern": {
+          "type": "string",
+          "description": "Shape of a branch name the agent creates. Placeholders {type}, {ticket}, {slug}. Default {type}/{slug}."
+        },
+        "update_strategy": {
+          "type": "string",
+          "enum": ["merge", "rebase"],
+          "description": "How a feature branch is brought up to date with its base. merge (default) = merge the base in; rebase = rebase onto origin/<base> and push with --force-with-lease, still asked for each time per git-history-discipline."
         }
       }
     },
-    "consistency": {
+    "design": {
       "type": "object",
       "additionalProperties": true,
       "properties": {
-        "cross_source": {
+        "fidelity_mode": {
           "type": "string",
-          "enum": ["on", "auto", "off"],
-          "description": "Consumed by the cross-source-consistency rule. When the agent works from multiple sources (ticket text, an attached image/mockup, the spec, the codebase) it checks them against each other and asks before proceeding on a discrepancy. on (default) = surface every real cross-source contradiction / silent-scope-expansion as one question; auto = surface only high-confidence contradictions, state low-confidence as an assumption; off = no cross-source checking."
+          "enum": ["strict", "structural", "hard-floor"],
+          "description": "How strictly the agent must follow a user-provided prototype / mockup / design system. Consumed by the design-fidelity rule. strict = build 1:1, every visible deviation needs confirmation; structural = structure locked, silent gaps fillable with a stated assumption; hard-floor = any deviation is never autonomous."
         }
       }
     },
@@ -158,18 +156,6 @@
         }
       }
     },
-    "tokens": {
-      "type": "object",
-      "additionalProperties": true,
-      "description": "Token-spend governance for skills marked token_budget_class: rich. See token-budget-discipline rule.",
-      "properties": {
-        "rich_skills": {
-          "type": "string",
-          "enum": ["on", "ask", "off"],
-          "description": "Controls whether skills marked token_budget_class: rich may load in full (exempt from telegraph-speak and thin-projector trimming). on = allowed (default); off = fall back to standard condensed behavior; ask = surface an estimated token delta (tokens, not dollars) and ask the user once per session before loading."
-        }
-      }
-    },
     "commands": {
       "type": "object",
       "additionalProperties": true,

package/src/scripts/schemas/command.schema.json

@@ -306,7 +306,7 @@
     },
     "auto_detect": {
       "type": "boolean",
-      "description": "6.1.0 orchestrator auto-detection opt-in (Step 1, non-interactive-contract). When true, the orchestrator auto-detects its sub-command per the confidence-tiered detection table instead of always showing the menu, honoring the non-interactive-contract (TTY/CI detection, --yes/--json, abort schemas). Per-orchestrator kill-switch: set false to always show the menu; overridable globally via commands.auto_detect in .agent-settings.yml and per-invocation via --no-auto-detect. Only orchestrators (type: orchestrator) carry it."
+      "description": "6.1.0 orchestrator auto-detection opt-in (Step 1, non-interactive-contract). When true, the orchestrator auto-detects its sub-command per the confidence-tiered detection table instead of always showing the menu, honoring the non-interactive-contract (TTY/CI detection, --yes/--json, abort schemas). Per-orchestrator kill-switch: set false to always show the menu; per-invocation override via --no-auto-detect (there is no global settings switch). Only orchestrators (type: orchestrator) carry it."
     }
   }
 }

package/src/scripts/schemas/skill.schema.json

@@ -505,7 +505,7 @@
         "standard",
         "rich"
       ],
-      "description": "Token-cost class for this skill. `lean` (default): subject to telegraph-speak condensation and thin-projector trimming; optimize for <500 tokens. `standard`: balanced guidance, normal condensation. `rich`: exempt from telegraph-speak and thin-projector trimming; detailed examples preserved; eager-load eligible; ≤15% of skills in a suite may be `rich` (CI-enforced). A `rich` skill MUST carry a '## Why this skill is rich' section explaining the irreducible complexity that makes condensation harmful. Governed by `token-budget-discipline` rule + `tokens.rich_skills` consumer setting. See docs/guidelines/token-budget-governance.md."
+      "description": "Token-cost class for this skill. `lean` (default): subject to telegraph-speak condensation and thin-projector trimming; optimize for <500 tokens. `standard`: balanced guidance, normal condensation. `rich`: exempt from telegraph-speak and thin-projector trimming; detailed examples preserved; eager-load eligible; ≤15% of skills in a suite may be `rich` (CI-enforced). A `rich` skill MUST carry a '## Why this skill is rich' section explaining the irreducible complexity that makes condensation harmful. Governed by the `token-budget-discipline` rule; rich skills always load in full. See docs/guidelines/token-budget-governance.md."
     },
     "parallelizable": {
       "type": "string",

package/src/scripts/self_review_gate.ts

@@ -116,12 +116,30 @@ export function gateVerdict(findings: readonly Finding[], opts: { enforce: boole
 const SKIP_PREFIXES = ['dist/agent-src/', '.augment/', '.claude/', '.cursor/', '.clinerules/'];
 const SKIP_EXACT = new Set(['.windsurfrules', 'GEMINI.md', 'package-lock.json']);
 
+/**
+ * Review artefacts, `.review-input/` copies included: a copy of a diff that was
+ * already reviewed. The R2 reviewer excludes the same tree
+ * (`REVIEW_SCOPE_EXCLUDES` in `dispatch_r2_reviewer.ts`); here they used to
+ * compete for `MAX_REVIEW_CHUNKS` — 154 of 16.3.0's 603 unreviewed paths sat
+ * under it. Counted separately in the coverage record, never as unreviewed.
+ */
+export const REVIEW_COPY_PREFIX = 'agents/evidence/reviews/';
+
+export function isReviewCopyPath(p: string): boolean {
+    return p.startsWith(REVIEW_COPY_PREFIX);
+}
+
 export function isReviewablePath(p: string): boolean {
     if (SKIP_EXACT.has(p)) return false;
+    if (isReviewCopyPath(p)) return false;
     return !SKIP_PREFIXES.some((pre) => p.startsWith(pre));
 }
 
 function changedFiles(baseRef: string, cwd: string = REPO_ROOT): string[] {
+    return allChangedFiles(baseRef, cwd).filter(isReviewablePath);
+}
+
+function allChangedFiles(baseRef: string, cwd: string = REPO_ROOT): string[] {
     // `-c core.quotePath=false`: by default git renders a non-ASCII path as an
     // escaped, QUOTED string (`"gr\303\274e.ts"`), which then matches no
     // pathspec when fed back to `git diff`. The file was silently skipped by
@@ -138,8 +156,7 @@ function changedFiles(baseRef: string, cwd: string = REPO_ROOT): string[] {
     return (r.stdout ?? '')
         .split('\n')
         .map((s) => s.trim())
-        .filter(Boolean)
-        .filter(isReviewablePath);
+        .filter(Boolean);
 }
 
 /**
@@ -758,6 +775,8 @@ export interface ReviewPlan {
     requests: number;
     /** Files no request will carry, with the reason. */
     unreviewed: { path: string; reason: string }[];
+    /** Changed paths under `REVIEW_COPY_PREFIX` — copies of a reviewed diff, sent to no request. */
+    reviewCopies: string[];
     promptChars: number;
     note: string;
     escalation: string[];
@@ -787,6 +806,7 @@ export function buildPlan(baseRef: string, cwd: string = REPO_ROOT): ReviewPlan
     }
 
     const files = analysisBase === baseRef ? packagingFiles : changedFiles(analysisBase, cwd);
+    const reviewCopies = allChangedFiles(analysisBase, cwd).filter(isReviewCopyPath);
     const diff = diffText(analysisBase, files, cwd);
     const escalation = escalationReasons(files, changedLineCount(analysisBase, files, cwd));
     const systemPrompt = buildSystemPrompt(release, baseRef);
@@ -810,6 +830,7 @@ export function buildPlan(baseRef: string, cwd: string = REPO_ROOT): ReviewPlan
         facts,
         requests: partition.chunks.length,
         unreviewed: partition.unreviewed,
+        reviewCopies,
         skills: [...REVIEW_SKILLS],
         files,
         analysisBase,
@@ -904,6 +925,12 @@ export function coverageBlock(coverage?: ReviewCoverage): string {
         `\n\n**Coverage.** ${String(coverage.chunks)} request(s) over ` +
             `${String(coverage.filesReviewed)} of ${String(coverage.filesTotal)} changed file(s).`,
     ];
+    if ((coverage.reviewCopies ?? 0) > 0) {
+        parts.push(
+            ` ${String(coverage.reviewCopies)} further path(s) under \`${REVIEW_COPY_PREFIX}\` are ` +
+                'copies of an already-reviewed diff and were not re-read.',
+        );
+    }
     if (coverage.unreviewed.length > 0) {
         parts.push(
             ` **NOT reviewed (${String(coverage.unreviewed.length)}):**\n` +
@@ -927,6 +954,12 @@ export interface ReviewCoverage {
     /** Files the span changed, so the reader sees the fraction, not a bare count. */
     filesTotal: number;
     unreviewed: { path: string; reason: string }[];
+    /**
+     * Changed paths under `REVIEW_COPY_PREFIX`, not re-read because each is a
+     * copy of a diff already reviewed. Neither reviewed nor unreviewed, and not
+     * in `filesTotal`. Optional: a record written before this field has none.
+     */
+    reviewCopies?: number;
 }
 
 export function renderReview(findings: Finding[], enforce: boolean, escalation: readonly string[] = [], coverage?: ReviewCoverage): string {
@@ -1089,6 +1122,9 @@ export function main(argv: string[]): 0 | 2 {
                       `packaging diff ${plan.release.packagingFiles.length} file(s))\n`
                     : '') +
                 `  files:  ${plan.files.length}\n` +
+                (plan.reviewCopies.length > 0
+                    ? `  review copies (not re-read): ${String(plan.reviewCopies.length)}\n`
+                    : '') +
                 `  calls:  ${plan.requests} (budget ${String(PROMPT_BUDGET_CHARS)} chars/request, ` +
                 `ceiling ${String(MAX_REVIEW_CHUNKS)})\n` +
                 (plan.unreviewed.length > 0
@@ -1242,6 +1278,7 @@ export function main(argv: string[]): 0 | 2 {
             filesReviewed: filesRead,
             filesTotal: plan.files.length,
             unreviewed,
+            reviewCopies: plan.reviewCopies.length,
         };
         // Ground-truth pass, ONCE, before anything reads the finding set. A
         // deletion claim the range and the tree both disprove is annotated