@event4u/agent-config 14.12.0 → 14.14.0

package/src/scripts/bench_ab_v2_stats.ts

@@ -36,6 +36,15 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+// `mcnemar_exact` and `cohens_h` live in `_lib/paired_stats.ts` and are
+// re-exported here, so every existing importer of this module is unchanged.
+// Extracted rather than left in place: this file sits above the 1500-line
+// ceiling `check_source_size_budget` charges, so lines added to it are paid
+// back by extraction rather than by raising a baseline.
+import { cohens_h, mcnemar_exact, _pyRound, _pyRoundNoArg, wilcoxon } from './_lib/paired_stats.js';
+
+export { cohens_h, mcnemar_exact, wilcoxon };
+
 import { cost_usd, tier_for_model, type TierRates } from './_lib/bench_ab_activation.js';
 import { load_pricing } from './_lib/bench_cost.js';
 
@@ -80,180 +89,10 @@ const COMPARISONS: Array<[string, string, string]> = [
 
 // ── CPython math.erf / math.comb ports ────────────────────────────────────
 //
-// CPython's `m_erf` (Modules/mathmodule.c): a Maclaurin series for |x| < 1.5
-// and 1 - erfc for larger |x|; `m_erfc` uses a continued-fraction expansion.
-// Ported verbatim so `_phi(z)` matches python3 to full double precision.
-
-const _ERF_SERIES_CUTOFF = 1.5;
-const _ERF_SERIES_TERMS = 25;
-const _ERFC_CONTFRAC_CUTOFF = 30.0;
-const _ERFC_CONTFRAC_TERMS = 50;
-const _SQRTPI = 1.772453850905516027298167483341145182798;
-
-function _m_erf_series(x: number): number {
-    // erf(x) = 2/sqrt(pi) * x * sum_{k>=0} (-x^2)^k / (k! (2k+1))
-    let x2 = x * x;
-    let acc = 0.0;
-    let fk = _ERF_SERIES_TERMS + 0.5;
-    for (let i = 0; i < _ERF_SERIES_TERMS; i += 1) {
-        acc = 2.0 + (x2 * acc) / fk;
-        fk -= 1.0;
-    }
-    return (acc * x * Math.exp(-x2)) / _SQRTPI;
-}
-
-function _m_erfc_contfrac(x: number): number {
-    if (x >= _ERFC_CONTFRAC_CUTOFF) {
-        return 0.0;
-    }
-    const x2 = x * x;
-    let a = 0.0;
-    let da = 0.5;
-    let p = 1.0;
-    let p_last = 0.0;
-    let q = da + x2;
-    let q_last = 1.0;
-    for (let i = 0; i < _ERFC_CONTFRAC_TERMS; i += 1) {
-        a += da;
-        da += 2.0;
-        const b = da + x2;
-        const temp_p = b * p - a * p_last;
-        p_last = p;
-        p = temp_p;
-        const temp_q = b * q - a * q_last;
-        q_last = q;
-        q = temp_q;
-    }
-    return (((p / q) * x) * Math.exp(-x2)) / _SQRTPI;
-}
-
-function _erf(x: number): number {
-    if (Number.isNaN(x)) {
-        return x;
-    }
-    const absx = Math.abs(x);
-    if (absx < _ERF_SERIES_CUTOFF) {
-        return _m_erf_series(x);
-    }
-    const cf = _m_erfc_contfrac(absx);
-    return x > 0.0 ? 1.0 - cf : cf - 1.0;
-}
-
-/** Python `math.comb(n, k)` — exact non-negative integer (BigInt → Number). */
-function _comb(n: number, k: number): number {
-    if (k < 0 || k > n) {
-        return 0;
-    }
-    let kk = BigInt(Math.min(k, n - k));
-    if (kk === 0n) {
-        return 1;
-    }
-    const N = BigInt(n);
-    let result = 1n;
-    let i = 0n;
-    while (i < kk) {
-        result = (result * (N - i)) / (i + 1n);
-        i += 1n;
-    }
-    return Number(result);
-}
+// The erf/normal-CDF port and `wilcoxon` live in `_lib/paired_stats.ts`,
+// re-exported above. Same reason as the two functions beside them: this file
+// is over the 1500-line ceiling, so additions are paid back by extraction.
 
-function _phi(z: number): number {
-    // Standard-normal CDF via erf.
-    return 0.5 * (1.0 + _erf(z / Math.sqrt(2.0)));
-}
-
-export function mcnemar_exact(b: number, c: number): number {
-    // Two-sided exact McNemar p-value (binomial on discordant pairs).
-    const n = b + c;
-    if (n === 0) {
-        return 1.0;
-    }
-    const k = Math.min(b, c);
-    let tail = 0;
-    for (let i = 0; i <= k; i += 1) {
-        tail += _comb(n, i);
-    }
-    tail = tail * 0.5 ** n;
-    return Math.min(1.0, 2.0 * tail);
-}
-
-export function cohens_h(p1: number, p2: number): number {
-    return (
-        2 * Math.asin(Math.sqrt(Math.max(0, Math.min(1, p1)))) -
-        2 * Math.asin(Math.sqrt(Math.max(0, Math.min(1, p2))))
-    );
-}
-
-interface WilcoxonResult {
-    n: number;
-    W_plus: number; // PyFloat-flagged at dump for the rounded case
-    W_minus: number;
-    p: number;
-    rank_biserial: number;
-}
-
-export function wilcoxon(diffs: number[]): WilcoxonResult {
-    // Wilcoxon signed-rank on paired differences (treatment - baseline).
-    // Returns W+, W-, normal-approx two-sided p (continuity-corrected), and
-    // rank-biserial effect size. Zeros are dropped.
-    const nz = diffs.filter((d) => Math.abs(d) > 1e-9);
-    const n = nz.length;
-    if (n === 0) {
-        return { n: 0, W_plus: 0, W_minus: 0, p: 1.0, rank_biserial: 0.0 };
-    }
-    // order = sorted(range(n), key=lambda i: abs(nz[i])) — stable sort.
-    const order = Array.from({ length: n }, (_, i) => i).sort((x, y) => {
-        const ax = Math.abs(nz[x] as number);
-        const ay = Math.abs(nz[y] as number);
-        return ax < ay ? -1 : ax > ay ? 1 : x - y; // stable on tie
-    });
-    const ranks: number[] = new Array(n).fill(0.0);
-    let i = 0;
-    while (i < n) {
-        let j = i;
-        while (j + 1 < n && Math.abs(nz[order[j + 1] as number] as number) === Math.abs(nz[order[i] as number] as number)) {
-            j += 1;
-        }
-        const avg = (i + 1 + j + 1) / 2.0; // average rank for ties (1-based)
-        for (let k = i; k <= j; k += 1) {
-            ranks[order[k] as number] = avg;
-        }
-        i = j + 1;
-    }
-    let w_plus = 0.0;
-    let w_minus = 0.0;
-    for (let idx = 0; idx < n; idx += 1) {
-        if ((nz[idx] as number) > 0) {
-            w_plus += ranks[idx] as number;
-        } else if ((nz[idx] as number) < 0) {
-            w_minus += ranks[idx] as number;
-        }
-    }
-    const total = w_plus + w_minus;
-    const rb = total ? (w_plus - w_minus) / total : 0.0;
-    // Normal approximation (ok-ish for n>=10; for small n it's conservative —
-    // we surface n so the reader can weight it).
-    const mean = (n * (n + 1)) / 4.0;
-    const sd = Math.sqrt((n * (n + 1) * (2 * n + 1)) / 24.0);
-    const w = Math.min(w_plus, w_minus);
-    let p: number;
-    if (sd === 0) {
-        p = 1.0;
-    } else {
-        const z = (w - mean + 0.5) / sd;
-        p = Math.min(1.0, 2.0 * _phi(z));
-    }
-    return {
-        n,
-        // W_plus / W_minus are not surfaced in JSON/markdown (compare() drops
-        // them), so plain numbers suffice; p / rank_biserial are floats.
-        W_plus: _pyRound(w_plus, 1),
-        W_minus: _pyRound(w_minus, 1),
-        p: _pyRound(p, 4),
-        rank_biserial: _pyRound(rb, 4),
-    };
-}
 
 /** Wrap a `round(...)`/float result so it renders `1.0` not `1` (Python float). */
 function PF(x: number): PyFloat {
@@ -478,6 +317,14 @@ function _paired_median_block(t: number[], b: number[], diffs: number[]): Dict {
     // Percent change of the medians. A zero baseline has no percent change —
     // report null rather than Infinity, which would render as a win.
     const pct = mb === 0 ? null : PF(_pyRound(((mt - mb) / Math.abs(mb)) * 100, 4));
+    // Direction counts, ADDITIVE (Phase-3 PREREG amendment v2, 2026-08-26).
+    // The significance half of the size verdict now reads these rather than
+    // `wilcoxon_p`; every pre-existing key is untouched, so a consumer reading
+    // named keys is unaffected. Tie epsilon matches `wilcoxon`'s own 1e-9 zero
+    // drop, so "non-tied" means the same thing to both tests — two definitions
+    // of a tie in one report is how the numbers start disagreeing.
+    const wins = diffs.filter((d) => d < -1e-9).length;
+    const losses = diffs.filter((d) => d > 1e-9).length;
     return {
         measured: true,
         n_pairs: diffs.length,
@@ -488,6 +335,13 @@ function _paired_median_block(t: number[], b: number[], diffs: number[]): Dict {
         wilcoxon_p: PF(wil.p),
         rank_biserial: PF(wil.rank_biserial),
         n_nonzero: wil.n,
+        // "Win" is DIRECTION-OF-INTEREST, not sign: for added lines and for
+        // cognitive complexity a NEGATIVE delta is the improvement. Naming them
+        // wins/losses here rather than positive/negative keeps the verdict from
+        // having to know which endpoint it is looking at.
+        direction_wins: wins,
+        direction_losses: losses,
+        direction_ties: diffs.length - wins - losses,
     };
 }
 
@@ -733,6 +587,15 @@ function _toContinuous(block: Dict): PairedContinuous {
         median_delta_pct: block['median_delta_pct'] == null ? null : _pyFloat(block['median_delta_pct']),
         median_delta: _pyFloat(block['median_delta']),
         wilcoxon_p: _pyFloat(block['wilcoxon_p']),
+        // Optional-absent rather than defaulted to 0: an older report carries
+        // no direction counts, and zeroing them would read as "no trial went
+        // either way", which is a measurement rather than a missing field.
+        ...(block['direction_wins'] === undefined
+            ? {}
+            : {
+                  direction_wins: _pyFloat(block['direction_wins']),
+                  direction_losses: _pyFloat(block['direction_losses']),
+              }),
     };
 }
 
@@ -813,7 +676,7 @@ export function to_markdown(analysis: Dict, payload: Dict): string {
     L.push('# Discipline-Axis Wrapper-Lift Benchmark (v2)');
     L.push('');
     L.push(
-        '> Generated by `scripts/bench_ab_v2_stats.py --markdown`. Source: ' +
+        '> Generated by `bench_ab_v2_stats --markdown`. Do not edit. Source: ' +
             '`internal/bench/reports/ab-v2/`. Re-render with `task bench:ab:v2:diff`.',
     );
     L.push('');
@@ -1366,46 +1229,10 @@ function _pyStr(v: unknown): string {
     return String(v);
 }
 
-/** Python `round(x)` (no ndigits) → int, round-half-to-even. */
-function _pyRoundNoArg(x: number): number {
-    if (!Number.isFinite(x)) return x;
-    const floor = Math.floor(x);
-    const frac = x - floor;
-    if (frac < 0.5) return floor;
-    if (frac > 0.5) return floor + 1;
-    return floor % 2 === 0 ? floor : floor + 1;
-}
+// `_pyRound` / `_pyRoundNoArg` live in `_lib/paired_stats.ts` (imported above):
+// `wilcoxon` needs them and moved there, and two copies of a float-parity
+// rounder is how byte-stable output stops being byte-stable.
 
-/** Python `round(x, ndigits)` — round-half-to-even on the exact double. */
-function _pyRound(value: number, ndigits: number): number {
-    if (!Number.isFinite(value) || value === 0) {
-        return value;
-    }
-    const neg = value < 0;
-    const abs = Math.abs(value);
-    const exact = abs.toFixed(40);
-    const dot = exact.indexOf('.');
-    const intPart = dot === -1 ? exact : exact.slice(0, dot);
-    const fracPart = dot === -1 ? '' : exact.slice(dot + 1);
-    const keepFrac = fracPart.slice(0, ndigits).padEnd(ndigits, '0');
-    const rest = fracPart.slice(ndigits);
-    const scaledStr = (intPart + keepFrac).replace(/^0+(?=\d)/, '');
-    let scaled = BigInt(scaledStr === '' ? '0' : scaledStr);
-    if (rest.length > 0) {
-        const firstRest = rest.charCodeAt(0) - 48;
-        const hasMore = /[1-9]/.test(rest.slice(1));
-        if (firstRest > 5 || (firstRest === 5 && hasMore)) {
-            scaled += 1n;
-        } else if (firstRest === 5 && !hasMore) {
-            if (scaled % 2n === 1n) {
-                scaled += 1n;
-            }
-        }
-    }
-    const factor = 10 ** ndigits;
-    const result = Number(scaled) / factor;
-    return neg ? -result : result;
-}
 
 /** `format(x, '.Nf')` — round-half-even on the exact double, fixed N decimals. */
 function _pyFixed(x: number, ndigits: number): string {

package/src/scripts/build_archive_index.ts

@@ -249,7 +249,7 @@ export function renderJson(entries: readonly ArchiveEntry[]): string {
     return (
         JSON.stringify(
             {
-                generated_by: 'src/scripts/build_archive_index.ts',
+                generated_by: 'build_archive_index',
                 source: ARCHIVE_REL,
                 count: entries.length,
                 entries,

package/src/scripts/build_linear_digest.ts

@@ -171,7 +171,7 @@ export function render_digest(layer: string, entries: RuleEntry[]): [string, Dig
     const parts: string[] = [];
     parts.push(`# event4u/agent-config — Linear AI ${_title(layer)} Digest\n`);
     parts.push(
-        '> Auto-generated by `scripts/build_linear_digest.py` from ' +
+        '> Generated by `build_linear_digest`. Do not edit. From ' +
             '`dist/agent-src/rules/` (condensed source) plus the inclusion list ' +
             'at `docs/contracts/linear-ai-rules-inclusion.md`. Do not edit ' +
             'this file by hand — re-run `task build-linear-digest` to ' +

package/src/scripts/build_proof.ts

@@ -157,7 +157,7 @@ function render(): string {
     const resolvedNull = entries.filter((e) => e.status === 'resolved-null');
 
     const L: string[] = [];
-    L.push('<!-- GENERATED by src/scripts/build_proof.ts — do NOT hand-edit.');
+    L.push('<!-- GENERATED by build_proof — do NOT hand-edit.');
     L.push('     Drift-checked in CI (`task build-proof-check`). Regenerate with');
     L.push('     `./scripts-run src/scripts/build_proof` after editing docs/CLAIMS.md. -->');
     L.push('');
@@ -449,11 +449,18 @@ function render(): string {
                 `${nulls} resolved-null.`,
         );
         L.push('');
-        L.push('| Claim id | Kind | Status | Evidence pointer |');
-        L.push('|---|---|---|---|');
+        // `Measured on` exists because a status alone cannot say that a real
+        // measurement describes a build that no longer exists — and an AI
+        // council (2026-08-26, 2/2) required the binding to reach every index,
+        // not only the detailed entry, since a prose-only qualification drifts
+        // from the structured record it qualifies. Empty for every claim that
+        // describes the current tree, which is almost all of them.
+        L.push('| Claim id | Kind | Status | Measured on | Evidence pointer |');
+        L.push('|---|---|---|---|---|');
         for (const e of ledger) {
             const ev = e.evidence.length > 0 ? `\`${e.evidence.replace(/\|/g, '\\|')}\`` : '—';
-            L.push(`| \`${e.id}\` | ${e.kind} | ${e.status} | ${ev} |`);
+            const on = e.measured_on.length > 0 ? e.measured_on.replace(/\|/g, '\\|') : '—';
+            L.push(`| \`${e.id}\` | ${e.kind} | ${e.status} | ${on} | ${ev} |`);
         }
     }
     L.push('');

package/src/scripts/build_rule_trigger_matrix.ts

@@ -340,7 +340,7 @@ function emit(): number {
     lines.push('');
     lines.push('**Source:** Phase 1 of `road-to-rule-hardening.md` (self-check audit) +');
     lines.push('Phase 1 of `road-to-context-layer-maturity.md` (`load_context:` inventory).');
-    lines.push('**Generated by:** `src/scripts/build_rule_trigger_matrix.ts` — re-run after rule');
+    lines.push('**Generated by:** `build_rule_trigger_matrix` — re-run after rule');
     lines.push("set changes. Manual classifications live in the script's `CLASSIFICATION`");
     lines.push('table; size and context-chain columns are derived from the rule files.');
     lines.push('');

package/src/scripts/build_source_digests.ts

@@ -0,0 +1,157 @@
+#!/usr/bin/env tsx
+/**
+ * build_source_digests — derive the tracked deny digests from the private
+ * master (`road-to-source-silence` Phase 1.1, resolution (c)).
+ *
+ * ## The shape the council chose
+ *
+ * Humans edit a readable list; the repository never sees it.
+ *
+ *   src/scripts/external_sources_denylist.private.json   ← gitignored MASTER
+ *            │  { "deny": ["<readable pattern>", …] }
+ *            ▼  build_source_digests  (needs SOURCE_DENY_KEY)
+ *   src/scripts/external_sources_denylist.json           ← tracked, DERIVED
+ *               { "deny_digests": ["<64 hex>", …] }
+ *
+ * "Plaintext in the tree" becomes structurally impossible rather than
+ * disciplined away: the tracked artefact is derivational, and the readable list
+ * exists in exactly one place, which is private.
+ *
+ * ## STATUS: this ships DORMANT and changes nothing by itself
+ *
+ * Running it is one quarter of the maintainer's atomic cutover. The other three
+ * quarters — provisioning the CI secret, deleting the tracked plaintext `deny`
+ * array, and switching CI to strict mode — are NOT in this change and must not
+ * be split from each other. `docs/maintainers/source-deny-digests.md` is the
+ * recipe. Until then `deny_digests` is empty, the plaintext gate stays in force,
+ * and the digest code path does nothing.
+ *
+ * Modes:
+ *   (default)   write digests into the tracked config from the private master
+ *   --check     verify the tracked digests match the master; exit 1 on drift
+ *   --stdout    print the digest array instead of writing (for inspection)
+ *
+ * Exit codes: 0 = done / in sync, 1 = drift (--check), 2 = usage or missing
+ * input, 3 = no key (`SOURCE_DENY_KEY` unset).
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { digest, DIGEST_RE, EXIT_NO_KEY, KEY_ENV, normalise } from './_lib/source_digest.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+const DIR = path.dirname(_HERE);
+export const TRACKED_CONFIG = path.join(DIR, 'external_sources_denylist.json');
+export const PRIVATE_MASTER = path.join(DIR, 'external_sources_denylist.private.json');
+
+interface Master {
+    deny: string[];
+}
+
+/**
+ * Digests for a master list, sorted and deduplicated.
+ *
+ * Sorted so the tracked artefact's diff shows an ADDITION as one line rather
+ * than a reshuffle, and so two maintainers with the same master produce the
+ * same file. Deduplicated because two spellings of one name fold to one digest
+ * — `normalise` is not injective and must not be assumed to be.
+ */
+export function digestsFor(deny: readonly string[], key: string): string[] {
+    const out = new Set<string>();
+    for (const raw of deny) {
+        const bare = normalise(raw.replace(/\\b/g, ''));
+        if (bare.length < 3) continue;
+        out.add(digest(bare, key));
+    }
+    return [...out].sort();
+}
+
+function readMaster(): Master {
+    const raw = fs.readFileSync(PRIVATE_MASTER, 'utf-8');
+    const parsed = JSON.parse(raw) as Partial<Master>;
+    if (!Array.isArray(parsed.deny) || parsed.deny.length === 0) {
+        throw new Error('private master has no non-empty `deny` array');
+    }
+    return { deny: parsed.deny };
+}
+
+export function main(argv: readonly string[]): number {
+    const check = argv.includes('--check');
+    const toStdout = argv.includes('--stdout');
+
+    const key = process.env[KEY_ENV] ?? '';
+    if (key === '') {
+        process.stderr.write(
+            `❌  ${KEY_ENV} is unset. The digest construction is KEYED on purpose: the candidate\n` +
+                '    space is public repository slugs, so an unsalted hash of a slug is a lookup,\n' +
+                '    not a secret. Nothing is written without the key.\n',
+        );
+        return EXIT_NO_KEY;
+    }
+
+    let master: Master;
+    try {
+        master = readMaster();
+    } catch (exc) {
+        process.stderr.write(
+            `❌  cannot read the private master at ${path.basename(PRIVATE_MASTER)}: ` +
+                `${(exc as Error).message}\n` +
+                '    It is gitignored by design and must be created by the maintainer — see\n' +
+                '    docs/maintainers/source-deny-digests.md.\n',
+        );
+        return 2;
+    }
+
+    const digests = digestsFor(master.deny, key);
+    if (!digests.every((d) => DIGEST_RE.test(d))) {
+        process.stderr.write('❌  internal error: a produced digest is not 64 lowercase hex chars\n');
+        return 2;
+    }
+
+    if (toStdout) {
+        process.stdout.write(JSON.stringify(digests, null, 2) + '\n');
+        return 0;
+    }
+
+    const cfg = JSON.parse(fs.readFileSync(TRACKED_CONFIG, 'utf-8')) as Record<string, unknown>;
+    const current = Array.isArray(cfg.deny_digests) ? (cfg.deny_digests as string[]) : [];
+
+    if (check) {
+        const same = current.length === digests.length && current.every((d, i) => d === digests[i]);
+        if (same) {
+            process.stdout.write(`✅  ${String(digests.length)} deny digest(s) in sync with the private master.\n`);
+            return 0;
+        }
+        process.stderr.write(
+            `❌  deny_digests drift: tracked ${String(current.length)}, derived ${String(digests.length)}.\n` +
+                '    Re-run without --check to regenerate.\n',
+        );
+        return 1;
+    }
+
+    cfg.deny_digests = digests;
+    fs.writeFileSync(TRACKED_CONFIG, JSON.stringify(cfg, null, 2) + '\n', 'utf-8');
+    process.stdout.write(`✅  wrote ${String(digests.length)} deny digest(s) to ${path.basename(TRACKED_CONFIG)}.\n`);
+    process.stdout.write(
+        '    This is ONE QUARTER of the cutover. The CI secret, the deletion of the plaintext\n' +
+            '    deny array and the switch to strict mode ship in the SAME change or not at all.\n',
+    );
+    return 0;
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) return false;
+    if (import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) return true;
+    try {
+        return fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    process.exit(main(process.argv.slice(2)));
+}

package/src/scripts/cache_realization_report.ts

@@ -36,6 +36,8 @@ import { homedir } from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { buildReport as buildDriftReport } from './orchestration_payload_hash_drift.js';
+import type { PayloadHashDriftReport } from './_lib/payload_hash_drift.js';
 import {
     aggregateByBucket,
     billableInputTokens,
@@ -635,6 +637,7 @@ export interface Options {
     councilRoot: string;
     userRulesDir: string;
     projectRulesDir: string;
+    auditDir: string;
 }
 
 function defaultOptions(): Options {
@@ -646,6 +649,7 @@ function defaultOptions(): Options {
         councilRoot: REPO_ROOT,
         userRulesDir: path.join(homedir(), '.claude', 'rules'),
         projectRulesDir: path.join(REPO_ROOT, 'dist', 'agent-src', 'rules'),
+        auditDir: path.join(REPO_ROOT, 'agents', 'runtime', 'state', 'audit'),
     };
 }
 
@@ -668,11 +672,82 @@ export function parseArgs(argv: string[]): Options {
         else if (a.startsWith('--user-rules-dir=')) opts.userRulesDir = a.slice('--user-rules-dir='.length);
         else if (a === '--project-rules-dir') opts.projectRulesDir = argv[++i] ?? opts.projectRulesDir;
         else if (a.startsWith('--project-rules-dir=')) opts.projectRulesDir = a.slice('--project-rules-dir='.length);
+        else if (a === '--audit-dir') opts.auditDir = argv[++i] ?? opts.auditDir;
+        else if (a.startsWith('--audit-dir=')) opts.auditDir = a.slice('--audit-dir='.length);
     }
     if (opts.format !== 'text' && opts.format !== 'json') opts.format = 'text';
     return opts;
 }
 
+/**
+ * Prefix-stability verdict, carried in the cost report rather than left latent
+ * in a separate CLI (`road-to-runtime-context-floors` step 1.3).
+ *
+ * `_lib/payload_hash_drift` already splits dispatches into a STABLE cohort
+ * (repeat occurrences of one payload hash) and an UNSTABLE one (hashes seen
+ * once). Nothing read the split, so the one outcome that matters — a stable
+ * cohort whose cache-read share is BELOW its unstable cohort, which means the
+ * prefix is being rewritten between repeats — was measurable and unreported.
+ *
+ * `verdict` is deliberately three-valued. `insufficient-data` is not a number
+ * and must never be rendered as one: with either cohort empty there is no
+ * comparison to make, and printing `0.0%` for "nothing was measured" is the
+ * shape that turns a blind report into a believed one.
+ */
+export type PrefixStabilityVerdict = 'stable-higher' | 'inverted' | 'insufficient-data';
+
+export interface PrefixStabilityResult {
+    verdict: PrefixStabilityVerdict;
+    /** Why, in one sentence — always populated, including for `insufficient-data`. */
+    reason: string;
+    stable_cohort: { n: number; read_share: number | null };
+    unstable_cohort: { n: number; read_share: number | null };
+    lines_with_data: number;
+}
+
+export function computePrefixStability(drift: PayloadHashDriftReport): PrefixStabilityResult {
+    const stable = { n: drift.stable_cohort.n, read_share: drift.stable_cohort.hit_rate };
+    const unstable = { n: drift.unstable_cohort.n, read_share: drift.unstable_cohort.hit_rate };
+
+    if (stable.read_share === null || unstable.read_share === null) {
+        const empty = [stable.read_share === null ? 'stable' : null, unstable.read_share === null ? 'unstable' : null]
+            .filter((x) => x !== null)
+            .join(' and ');
+        const plural = empty.includes(' and ') ? 'cohorts are' : 'cohort is';
+        return {
+            verdict: 'insufficient-data',
+            reason:
+                `the ${empty} ${plural} empty (${drift.lines_with_data} audit line(s) carry both ` +
+                'payload_hash and cache_hit) — no comparison exists, and a share is not reported for one',
+            stable_cohort: stable,
+            unstable_cohort: unstable,
+            lines_with_data: drift.lines_with_data,
+        };
+    }
+    if (stable.read_share < unstable.read_share) {
+        return {
+            verdict: 'inverted',
+            reason:
+                `repeat dispatches of the same payload shape hit the cache LESS often ` +
+                `(${(stable.read_share * 100).toFixed(1)}%) than one-off shapes ` +
+                `(${(unstable.read_share * 100).toFixed(1)}%) — a prefix-stable surface is being ` +
+                'rewritten between repeats',
+            stable_cohort: stable,
+            unstable_cohort: unstable,
+            lines_with_data: drift.lines_with_data,
+        };
+    }
+    return {
+        verdict: 'stable-higher',
+        reason:
+            `repeat dispatches hit the cache at ${(stable.read_share * 100).toFixed(1)}% against ` +
+            `${(unstable.read_share * 100).toFixed(1)}% for one-off shapes, which is the expected ordering`,
+        stable_cohort: stable,
+        unstable_cohort: unstable,
+        lines_with_data: drift.lines_with_data,
+    };
+}
+
 export interface Report {
     schema: 'cache-realization-report/v1';
     host_version: string;
@@ -688,6 +763,7 @@ export interface Report {
     duplicate_scope: DuplicateScopeResult;
     council_mispricing: CouncilMispricingResult;
     worktree_fragmentation: WorktreeFragmentationResult;
+    prefix_stability: PrefixStabilityResult;
     claims: Claim[];
 }
 
@@ -709,6 +785,22 @@ export function buildReport(opts: Options): Report {
     const worktreePaths = listGitWorktrees(opts.repoRoot);
     const worktreeFragmentation = computeWorktreeFragmentation(opts.root, worktreePaths, opts.maxAgeDays);
 
+    // A missing or unreadable audit directory is a real, expected state — the
+    // two fields are lean-init extensions and no caller wires them yet — so it
+    // resolves to `insufficient-data` with a reason, never to a fabricated share.
+    let prefixStability: PrefixStabilityResult;
+    try {
+        prefixStability = computePrefixStability(buildDriftReport(opts.auditDir));
+    } catch (err) {
+        prefixStability = {
+            verdict: 'insufficient-data',
+            reason: `the audit ledger at ${opts.auditDir} could not be read: ${(err as Error).message}`,
+            stable_cohort: { n: 0, read_share: null },
+            unstable_cohort: { n: 0, read_share: null },
+            lines_with_data: 0,
+        };
+    }
+
     const claims = buildClaims({ subagentColdStart, duplicateScope, councilMispricing, worktreeFragmentation });
 
     return {
@@ -729,6 +821,7 @@ export function buildReport(opts: Options): Report {
         duplicate_scope: duplicateScope,
         council_mispricing: councilMispricing,
         worktree_fragmentation: worktreeFragmentation,
+        prefix_stability: prefixStability,
         claims,
     };
 }
@@ -748,6 +841,16 @@ export function renderText(r: Report): string {
     out.push(`  dedup: ${r.deduped_count}/${r.total_seen} unique records kept (dedup_ratio ${pct(r.dedup_ratio)})`);
     out.push('');
 
+    const ps = r.prefix_stability;
+    const share = (v: number | null): string => (v === null ? 'insufficient data' : pct(v));
+    const mark = ps.verdict === 'inverted' ? '⚠️ ' : '';
+    out.push('Prefix stability (payload_hash × cache_hit):');
+    out.push(`  ${mark}verdict: ${ps.verdict}`);
+    out.push(`  stable cohort:   n=${ps.stable_cohort.n} read_share=${share(ps.stable_cohort.read_share)}`);
+    out.push(`  unstable cohort: n=${ps.unstable_cohort.n} read_share=${share(ps.unstable_cohort.read_share)}`);
+    out.push(`  ${ps.reason}`);
+    out.push('');
+
     out.push('By bucket:');
     for (const bucket of ['main', 'subagent'] as const) {
         const b = r.buckets[bucket];