@event4u/agent-config 12.0.0 → 13.0.0

package/src/scripts/_lib/bench_ab_search_adherence.ts

@@ -0,0 +1,423 @@
+/**
+ * T5 — search adherence, rubric-judged at k=2.
+ *
+ * The pre-registration (`internal/bench/ab-v2-phase3-PREREG.md` § Thresholds)
+ * defines T5 as *"search-adherence (rubric-judged, k=2)"* with the rationale
+ * from F8: the ladder enforces a **search** discipline, while lines-of-code
+ * measures output volume. A run can shrink a diff without anyone having looked
+ * for an existing mechanism, so a size-only report measures the wrong
+ * hypothesis. This module scores the question the roadmap asks — *did the run
+ * demonstrably consider a cheaper existing mechanism before writing new code* —
+ * off the trial's own transcript.
+ *
+ * WHY A RUBRIC HERE AND AN EXECUTION PROBE FOR T4. The two endpoints are not
+ * the same shape and the pre-registration already says so, tagging only this
+ * one `rubric-judged`. T4 asks whether a property still holds in the running
+ * code, which an interpreter answers. T5 asks what the run *did before it
+ * wrote* — an act with no residue in the final tree at all. There is nothing to
+ * execute; the transcript is the only evidence, and reading it is a judgement.
+ *
+ * WHY k=2 AND WHY THE AGGREGATION IS CONSERVATIVE. One judge on a
+ * judgement-shaped rubric is a single point of failure whose error is invisible.
+ * Two judges make disagreement observable, and `resolveK2` counts an item as
+ * satisfied only when **both** agree it was — the same asymmetry
+ * `_lib/anchor_eval.ts` uses, and for the same reason: the failure that matters
+ * is crediting adherence that did not happen. Crediting it needs unanimity;
+ * denying it needs one.
+ *
+ * NULL, NEVER ZERO. A judge that cannot answer after its one retry makes the
+ * TRIAL unmeasured, not zero-scoring. A zero would say "this run looked for
+ * nothing", which is a claim about the run; the truth is a claim about the
+ * measurement. `compare()` requires the metric on both sides of a pair, so an
+ * unmeasured trial removes its pair rather than biasing it.
+ *
+ * PURE BY CONSTRUCTION. Nothing here imports a model client. The judge arrives
+ * as an injected `AskFn`, which is what lets every property below be pinned in
+ * a unit test with no key, no network, and no spend — the idiom
+ * `bench_quality_run.ts` and `anchor_eval.ts` already use.
+ */
+import { ALPHA, type PairedContinuous } from './bench_ab_size_claim.js';
+
+/** The three rubric items, in the order the prompt presents them. */
+export const SEARCH_RUBRIC_ITEMS = ['named', 'inspected', 'justified'] as const;
+export type SearchRubricItem = (typeof SEARCH_RUBRIC_ITEMS)[number];
+
+/** Pre-registered judge count. */
+export const SEARCH_ADHERENCE_K = 2;
+
+/** A judge: one prompt in, one raw completion out. */
+export type AskFn = (prompt: string) => string;
+
+export interface JudgeReading {
+    /** Per item: `true` satisfied, `false` not, `null` unparseable. */
+    items: Record<SearchRubricItem, boolean | null>;
+    /** True when every item parsed to a boolean. */
+    complete: boolean;
+}
+
+export interface SearchAdherenceResult {
+    /** Fraction of rubric items both judges credited, or `null` if unmeasured. */
+    score: number | null;
+    readings: JudgeReading[];
+    reason: string;
+}
+
+/**
+ * Delimiters around the transcript inside the judge prompt.
+ *
+ * They exist because the RUBRIC that follows the transcript necessarily
+ * contains the very words the rubric asks about — "reuse", "existing", "read",
+ * "grepped", "because". Any reader that slices the prompt at `TRANSCRIPT:` and
+ * takes the rest is therefore reading the instrument, not the evidence, and
+ * scores every input at the ceiling. That is not hypothetical: the dry-run
+ * judge did exactly this on its first pass and its own test caught it.
+ *
+ * The hazard runs in BOTH directions and only one of them is a parsing bug. A
+ * transcript is untrusted model output pasted into a judge prompt, and
+ * delimiters are the only separation there is — nothing stops transcript text
+ * from addressing the judge directly. That is `untrusted-input-defense`'s
+ * territory rather than this module's, and it is named here so a reader does not
+ * mistake the delimiters for a containment guarantee they are not.
+ */
+export const TRANSCRIPT_OPEN = '--- BEGIN TRANSCRIPT ---';
+export const TRANSCRIPT_CLOSE = '--- END TRANSCRIPT ---';
+
+/**
+ * Extract the transcript back out of a built prompt.
+ *
+ * Returns `''` when the delimiters are absent, which yields a credit-nothing
+ * reading rather than a ceiling one — the safe direction for a rubric whose
+ * failure mode is crediting adherence that did not happen.
+ */
+export function transcriptFromPrompt(prompt: string): string {
+    const start = prompt.indexOf(TRANSCRIPT_OPEN);
+    // LAST close, not the first: a transcript is untrusted model output and may
+    // contain the delimiter literally. Taking the first occurrence would let a
+    // transcript truncate the evidence a reader extracts from it.
+    const end = prompt.lastIndexOf(TRANSCRIPT_CLOSE);
+    if (start === -1 || end === -1 || end <= start) return '';
+    return prompt.slice(start + TRANSCRIPT_OPEN.length, end);
+}
+
+/**
+ * Build the judge prompt.
+ *
+ * Three properties are deliberate. The rubric is **stated as evidence tests**,
+ * not as a quality opinion — each item asks whether a specific thing appears in
+ * the transcript, so two judges are reading for the same artefact rather than
+ * forming the same taste. The output shape is a fixed three-line block, which
+ * makes an incomplete answer detectable instead of silently half-parsed. And it
+ * says explicitly not to reward brevity: T5 exists precisely because a shorter
+ * diff is not evidence of a search, so a judge rewarding shortness here would
+ * launder T1 into T5 and destroy the independence the pair depends on.
+ */
+export function searchAdherencePrompt(taskPrompt: string, transcript: string): string {
+    return [
+        'You are scoring one transcript against a three-item evidence rubric.',
+        'Answer only from what the transcript shows. Do not infer intent, and do',
+        'not reward or penalise how long, short, or elegant the resulting change is.',
+        '',
+        'TASK GIVEN TO THE RUN:',
+        taskPrompt,
+        '',
+        TRANSCRIPT_OPEN,
+        transcript,
+        TRANSCRIPT_CLOSE,
+        '',
+        'RUBRIC — for each item answer yes or no:',
+        'NAMED: before writing new code, the run named a specific existing mechanism',
+        '  it could reuse instead (a file, function, class, library, or built-in).',
+        '  A generic statement that something might already exist is NOT enough.',
+        'INSPECTED: the run actually looked at that mechanism — read, listed, grepped,',
+        '  or opened it — rather than only mentioning it.',
+        'JUSTIFIED: the run stated why it did or did not reuse what it found.',
+        '',
+        'Answer with exactly these three lines and nothing else:',
+        'NAMED: yes|no',
+        'INSPECTED: yes|no',
+        'JUSTIFIED: yes|no',
+    ].join('\n');
+}
+
+// Leading whitespace is tolerated on purpose: a judge that indents its block,
+// or emits it inside a list, has still answered. Anchoring hard at column 0
+// dropped exactly that item to `null`, which then reads as "incomplete reading"
+// and discards a trial for a formatting habit.
+const _LINE = /^[ \t>*-]*(NAMED|INSPECTED|JUSTIFIED)\s*:\s*(yes|no)\b/gim;
+const _KEY_TO_ITEM: Record<string, SearchRubricItem> = {
+    NAMED: 'named',
+    INSPECTED: 'inspected',
+    JUSTIFIED: 'justified',
+};
+
+/**
+ * Parse one judge completion.
+ *
+ * Unmatched items stay `null` and `complete` goes false — the caller retries
+ * once and then gives up on the trial. Defaulting a missing line to `no` would
+ * be the cheap read and the wrong one: it converts "the judge did not answer"
+ * into "the run did not search", which is a different claim and the one this
+ * endpoint is measuring.
+ */
+export function parseSearchVerdict(text: string): JudgeReading {
+    const items: Record<SearchRubricItem, boolean | null> = {
+        named: null,
+        inspected: null,
+        justified: null,
+    };
+    _LINE.lastIndex = 0;
+    let m: RegExpExecArray | null = _LINE.exec(text ?? '');
+    while (m !== null) {
+        const item = _KEY_TO_ITEM[(m[1] ?? '').toUpperCase()];
+        if (item !== undefined && items[item] === null) {
+            items[item] = (m[2] ?? '').toLowerCase() === 'yes';
+        }
+        m = _LINE.exec(text ?? '');
+    }
+    const complete = SEARCH_RUBRIC_ITEMS.every((k) => items[k] !== null);
+    return { items, complete };
+}
+
+/**
+ * Combine two readings — an item counts only when both judges credit it.
+ *
+ * Returns the satisfied-item count, never a score, so the caller owns the
+ * denominator. A `null` on either side is not a credit, which is the same
+ * direction as a `no`: the burden is on evidence of a search, not on evidence
+ * of its absence.
+ */
+export function resolveK2(a: JudgeReading, b: JudgeReading): number {
+    let credited = 0;
+    for (const key of SEARCH_RUBRIC_ITEMS) {
+        if (a.items[key] === true && b.items[key] === true) credited += 1;
+    }
+    return credited;
+}
+
+/**
+ * Ask one judge, with exactly one retry on an unparseable or partial answer.
+ *
+ * One retry, not a loop: a judge that produced half a block twice is telling us
+ * something about the prompt or the model, and burning further calls on it
+ * would spend money to keep a bad reading warm.
+ */
+export function askWithRetry(ask: AskFn, prompt: string): JudgeReading {
+    let reading: JudgeReading;
+    try {
+        reading = parseSearchVerdict(ask(prompt));
+    } catch {
+        reading = { items: { named: null, inspected: null, justified: null }, complete: false };
+    }
+    if (reading.complete) return reading;
+    try {
+        return parseSearchVerdict(ask(prompt));
+    } catch {
+        return { items: { named: null, inspected: null, justified: null }, complete: false };
+    }
+}
+
+/**
+ * Score one trial at k=2.
+ *
+ * `asks` carries one judge per element — two distinct judges is the pre-
+ * registered shape, and passing the SAME function twice is accepted rather than
+ * rejected because that is the legitimate degraded case (one vendor reachable);
+ * the caller records which it used. Fewer than two, or any judge that never
+ * produced a complete reading, yields `null`.
+ */
+export function scoreSearchAdherence(opts: {
+    asks: AskFn[];
+    taskPrompt: string;
+    transcript: string;
+}): SearchAdherenceResult {
+    const { asks, taskPrompt, transcript } = opts;
+    if (asks.length < SEARCH_ADHERENCE_K) {
+        return { score: null, readings: [], reason: `fewer than k=${SEARCH_ADHERENCE_K} judges supplied` };
+    }
+    if (!transcript || transcript.trim() === '') {
+        return { score: null, readings: [], reason: 'no transcript recorded for this trial' };
+    }
+    const prompt = searchAdherencePrompt(taskPrompt, transcript);
+    const readings = asks.slice(0, SEARCH_ADHERENCE_K).map((ask) => askWithRetry(ask, prompt));
+    const incomplete = readings.filter((r) => !r.complete).length;
+    if (incomplete > 0) {
+        return {
+            score: null,
+            readings,
+            reason: `${incomplete} of ${readings.length} judges returned an incomplete reading after one retry`,
+        };
+    }
+    const credited = resolveK2(readings[0] as JudgeReading, readings[1] as JudgeReading);
+    return {
+        score: credited / SEARCH_RUBRIC_ITEMS.length,
+        readings,
+        reason: `${credited}/${SEARCH_RUBRIC_ITEMS.length} rubric items credited by both judges`,
+    };
+}
+
+export interface SearchClaimInput {
+    arm_treatment: string | null;
+    arm_baseline: string | null;
+    search: PairedContinuous;
+}
+
+export interface SearchClaimVerdict {
+    arm_treatment: string | null;
+    arm_baseline: string | null;
+    verdict: 'PASS' | 'REFUSED-SEARCH-REGRESSION' | 'INCONCLUSIVE';
+    reason: string;
+    search_measured: boolean;
+}
+
+/**
+ * Evaluate T5 for one comparison.
+ *
+ * The pre-registered threshold is *no significant regression*, two-sided at
+ * p < 0.05 in the harmful direction — so `PASS` is "the test did not reject",
+ * NOT "the treatment scored higher". Reading a non-rejection as a win is the
+ * mistake this comment exists to prevent: T5 is a guard on the size claim, not
+ * a second thing the ladder gets to win.
+ *
+ * An unmeasured endpoint is `INCONCLUSIVE`, never a pass — the same contract
+ * `evaluateSizeClaim` holds for T1/T2/T4.
+ */
+export function evaluateSearchAdherence(input: SearchClaimInput): SearchClaimVerdict {
+    const { search } = input;
+    const base = { arm_treatment: input.arm_treatment, arm_baseline: input.arm_baseline };
+    if (!search.measured) {
+        return {
+            ...base,
+            verdict: 'INCONCLUSIVE',
+            reason: 'T5 search-adherence not measured — no analysed pair carried it on both sides',
+            search_measured: false,
+        };
+    }
+    if (search.median_delta < 0 && search.wilcoxon_p < ALPHA) {
+        return {
+            ...base,
+            verdict: 'REFUSED-SEARCH-REGRESSION',
+            reason:
+                'search adherence fell significantly (T5) — the ladder enforces a search ' +
+                'discipline, so a size result bought by skipping it is not the hypothesis under test',
+            search_measured: true,
+        };
+    }
+    return {
+        ...base,
+        verdict: 'PASS',
+        reason: 'no significant regression in search adherence (T5)',
+        search_measured: true,
+    };
+}
+
+/** Render the T5 section of the stats report. */
+export function renderSearchAdherenceSection(verdicts: readonly SearchClaimVerdict[]): string[] {
+    const L: string[] = [];
+    L.push('## T5 — search adherence (rubric-judged, k=2)');
+    L.push('');
+    if (verdicts.length === 0) {
+        L.push('No comparison produced a search-adherence verdict.');
+        return L;
+    }
+    L.push('| treatment | baseline | verdict | reason |');
+    L.push('|---|---|---|---|');
+    for (const v of verdicts) {
+        L.push(
+            `| ${v.arm_treatment ?? '-'} | ${v.arm_baseline ?? '-'} | ${v.verdict} | ${v.reason} |`,
+        );
+    }
+    L.push('');
+    L.push(
+        '`PASS` means the pre-registered test did not reject in the harmful direction. ' +
+            'It is not a claim that the treatment searched *more*.',
+    );
+    return L;
+}
+
+/**
+ * Adapters for the report pipeline — the `Dict`-shaped objects
+ * `bench_ab_v2_stats` speaks, coerced into the typed input above.
+ *
+ * They live here rather than in the stats module for the same reason the
+ * verdict does: the dependency runs one way (stats imports this; this imports
+ * nothing from stats), and the size ratchet over `src/**` counts every line
+ * added to an already-large file. Extraction is the shrink-only ratchet's
+ * intended move; trimming the prose out of a comment is not.
+ */
+type Dict = Record<string, unknown>;
+
+/**
+ * Coerce a report value to a number, unwrapping the stats module's float box.
+ *
+ * `_paired_median_block` wraps every figure in a `PyFloat` so integers render
+ * with a trailing `.0`, and `Number(thatObject)` is `NaN`. Reading it as `0`
+ * turned a −1 median delta into no delta at all, so T5 reported PASS on a
+ * corpus where adherence had collapsed — the adapter test caught it, which is
+ * what that test exists for. The check is structural rather than an
+ * `instanceof`: the class is private to the stats module, and importing it here
+ * would reverse the dependency direction this file is careful to keep one-way.
+ */
+function _num(v: unknown): number {
+    const raw =
+        v !== null && typeof v === 'object' && 'value' in (v as Record<string, unknown>)
+            ? (v as { value: unknown }).value
+            : v;
+    const n = Number(raw);
+    return Number.isFinite(n) ? n : 0;
+}
+
+function _dict(v: unknown): Dict {
+    return v && typeof v === 'object' && !Array.isArray(v) ? (v as Dict) : {};
+}
+
+/** The Phase-3 T5 verdict for one `compare()` block. */
+export function searchClaimVerdict(comparison: Dict): Dict {
+    const block = _dict(comparison['search']);
+    return evaluateSearchAdherence({
+        arm_treatment: comparison['arm_treatment'] == null ? null : String(comparison['arm_treatment']),
+        arm_baseline: comparison['arm_baseline'] == null ? null : String(comparison['arm_baseline']),
+        search: {
+            measured: block['measured'] === true,
+            n_pairs: _num(block['n_pairs']),
+            median_delta_pct: block['median_delta_pct'] == null ? null : _num(block['median_delta_pct']),
+            median_delta: _num(block['median_delta']),
+            wilcoxon_p: _num(block['wilcoxon_p']),
+        },
+    }) as unknown as Dict;
+}
+
+/** The T5 section for one `analyse()` payload. */
+export function searchClaimSection(analysis: Dict): string[] {
+    const claims = Array.isArray(analysis['search_claims'])
+        ? (analysis['search_claims'] as unknown as SearchClaimVerdict[])
+        : [];
+    return renderSearchAdherenceSection(claims);
+}
+
+/**
+ * A paired-sample accumulator for T5's continuous endpoint.
+ *
+ * `compare()` collects three parallel arrays per endpoint; T5 needs the same
+ * three and nothing more, so they live behind one object rather than as three
+ * more locals in a module the size ratchet already flags. `addPair` keeps the
+ * both-sides-or-neither rule in one place: a metric present on only one side of
+ * a pair contributes nothing, because half a pair is no observation.
+ */
+export interface PairedSample {
+    t: number[];
+    b: number[];
+    diffs: number[];
+}
+
+export function newPairedSample(): PairedSample {
+    return { t: [], b: [], diffs: [] };
+}
+
+export function addPair(sample: PairedSample, treatment: unknown, baseline: unknown): void {
+    const a = typeof treatment === 'number' && Number.isFinite(treatment) ? treatment : null;
+    const b = typeof baseline === 'number' && Number.isFinite(baseline) ? baseline : null;
+    if (a === null || b === null) return;
+    sample.t.push(a);
+    sample.b.push(b);
+    sample.diffs.push(a - b);
+}

package/src/scripts/_lib/bench_ab_size_claim.ts

@@ -0,0 +1,206 @@
+/**
+ * The Phase-3 size claim — the metric pair (T1 + T2) and the T4 disqualifier.
+ *
+ * Split out of `bench_ab_v2_stats.ts` because the size verdict is decision
+ * logic, not statistics: it consumes already-computed paired blocks and answers
+ * one question — may this arm claim a size win. Keeping it here makes it a pure
+ * function over typed input with no dependency on the report pipeline, which is
+ * also what keeps the dependency one-directional (stats imports this; this
+ * imports nothing from stats).
+ *
+ * Thresholds are the pre-registered ones
+ * (`internal/bench/ab-v2-phase3-PREREG.md` § Thresholds); they live here so a
+ * change to either has to touch the record and the code together.
+ */
+
+/** T1 — median added lines must fall by at least this much. */
+export const T1_MEDIAN_LINES_PCT = -10;
+/** Two-sided significance for every endpoint in the pair. */
+export const ALPHA = 0.05;
+
+/** A paired continuous endpoint (added lines, cognitive complexity). */
+export interface PairedContinuous {
+    measured: boolean;
+    n_pairs: number;
+    /** `null` when the baseline median is 0 — no percent change exists. */
+    median_delta_pct: number | null;
+    median_delta: number;
+    wilcoxon_p: number;
+}
+
+/** A paired binary endpoint (the safety tier). */
+export interface PairedRate {
+    measured: boolean;
+    n_pairs: number;
+    rate_treatment: number;
+    rate_baseline: number;
+    mcnemar_p: number;
+}
+
+export interface SizeClaimInput {
+    arm_treatment: string | null;
+    arm_baseline: string | null;
+    size: PairedContinuous;
+    complexity: PairedContinuous;
+    safety: PairedRate;
+}
+
+export interface SizeClaimVerdict {
+    arm_treatment: string | null;
+    arm_baseline: string | null;
+    verdict: 'PASS' | 'NO-SIZE-WIN' | 'REFUSED-GOLFING' | 'REFUSED-SAFETY-REGRESSION' | 'INCONCLUSIVE';
+    reason: string;
+    lines_fell?: boolean;
+    size_measured: boolean;
+    complexity_measured: boolean;
+    safety_measured: boolean;
+}
+
+/**
+ * Evaluate the size claim for one comparison — binding, and structurally unable
+ * to report a win on size alone.
+ *
+ * Four properties, each a refusal the caller cannot route around:
+ *
+ *   1. **An unmeasured endpoint is never a pass.** If added lines, complexity,
+ *      or the safety tier is absent, the verdict is `INCONCLUSIVE` naming which.
+ *      Half a pair is no result, not a partial one — so this cannot silently
+ *      degrade into the lines-only report F9 exists to forbid.
+ *   2. **Safety is checked FIRST and is a disqualifier**, not a side metric. An
+ *      arm that saves a line and drops a guard has lost; there is no ordering of
+ *      the other two endpoints that can overturn it.
+ *   2b. **Golfing is refused as soon as T2 shows it** — before the
+ *      unmeasured-endpoint check, and independently of T4. The two disqualifiers
+ *      answer different questions and neither waits for the other; ordering them
+ *      the other way made `REFUSED-GOLFING` unreachable on real data, because no
+ *      safety-tier producer exists in the tree.
+ *   3. **`PASS` is reachable through exactly one path** — all three measured,
+ *      the complexity sample covering the size sample, neither disqualifier
+ *      fired, and T1 met. That is the Goodhart guard in code rather than in
+ *      prose: there is no branch that ranks on size while a safety regression
+ *      stands.
+ */
+export function evaluateSizeClaim(input: SizeClaimInput): SizeClaimVerdict {
+    const { size, complexity: cx, safety: saf } = input;
+    const base = { arm_treatment: input.arm_treatment, arm_baseline: input.arm_baseline };
+
+    // (2) The disqualifier runs before anything else can produce a win.
+    if (saf.measured && saf.rate_treatment < saf.rate_baseline && saf.mcnemar_p < ALPHA) {
+        return {
+            ...base,
+            verdict: 'REFUSED-SAFETY-REGRESSION',
+            reason:
+                'safety tier regressed significantly (T4) — a size result is ' +
+                'not reportable for this arm at all',
+            size_measured: size.measured,
+            complexity_measured: cx.measured,
+            safety_measured: true,
+        };
+    }
+
+    const cx_rose = cx.measured && cx.median_delta > 0 && cx.wilcoxon_p < ALPHA;
+    const pct = size.measured ? size.median_delta_pct : null;
+    const lines_fell = pct !== null && pct <= T1_MEDIAN_LINES_PCT && size.wilcoxon_p < ALPHA;
+
+    // (2b) Golfing is refused as soon as T2 shows it, and does NOT wait for T4.
+    //
+    // This ordering was wrong on the first pass and the completion review caught
+    // it: the unmeasured-endpoint branch ran first, so with no safety-tier
+    // producer in the tree — and there is none; T4's scorer is rubric-judged and
+    // unimplemented — every real run returned INCONCLUSIVE and `REFUSED-GOLFING`
+    // was reachable only from a synthetic fixture. A refusal that exists only in
+    // its own test is not a gate.
+    if (cx_rose) {
+        return {
+            ...base,
+            verdict: 'REFUSED-GOLFING',
+            reason:
+                'median cognitive complexity per changed function rose significantly (T2); ' +
+                'lines down and complexity up fails the size criterion even at p<0.05 on lines alone',
+            lines_fell,
+            size_measured: size.measured,
+            complexity_measured: true,
+            safety_measured: saf.measured,
+        };
+    }
+
+    const missing: string[] = [];
+    if (!size.measured) missing.push('T1 added-lines');
+    if (!cx.measured) missing.push('T2 cognitive-complexity');
+    if (!saf.measured) missing.push('T4 safety-tier');
+    if (missing.length > 0) {
+        return {
+            ...base,
+            verdict: 'INCONCLUSIVE',
+            reason: `endpoint(s) not measured: ${missing.join(', ')} — half a pair is no result`,
+            size_measured: size.measured,
+            complexity_measured: cx.measured,
+            safety_measured: saf.measured,
+        };
+    }
+
+    // (3) T1 and T2 are collected pair-wise and independently, so a trial that
+    // carries added lines but no complexity enters one sample and not the other.
+    // A win claimed on 30 pairs whose golfing check saw 4 is not a checked win —
+    // the guard would be policing a subset of the claim.
+    if (cx.n_pairs < size.n_pairs) {
+        return {
+            ...base,
+            verdict: 'INCONCLUSIVE',
+            reason:
+                `complexity sample (${cx.n_pairs} pairs) does not cover the size sample ` +
+                `(${size.n_pairs}) — the anti-golfing check would police a strict subset`,
+            lines_fell,
+            size_measured: true,
+            complexity_measured: true,
+            safety_measured: true,
+        };
+    }
+
+    return {
+        ...base,
+        verdict: lines_fell ? 'PASS' : 'NO-SIZE-WIN',
+        reason: lines_fell
+            ? `median added lines ${pct}% at p=${size.wilcoxon_p} with no significant complexity rise and no safety regression`
+            : `T1 not met (median added lines ${pct}% at p=${size.wilcoxon_p}; bar is <= ${T1_MEDIAN_LINES_PCT}% at p<${ALPHA})`,
+        lines_fell,
+        size_measured: true,
+        complexity_measured: true,
+        safety_measured: true,
+    };
+}
+
+/**
+ * The size-claim block of the rendered report.
+ *
+ * Rendered unconditionally — including when every endpoint is absent, because
+ * "the pair was not measurable" is the finding a reader needs in order not to
+ * quote a lines number from Table 1 as a size result.
+ */
+export function renderSizeClaimSection(claims: readonly SizeClaimVerdict[]): string[] {
+    const L: string[] = [];
+    L.push('## Size claim (T1 + T2 pair, T4 disqualifier)');
+    L.push('');
+    L.push(
+        '> A size metric is a **measurement**, never a scored target. An arm may ' +
+            'claim a size win only when median added lines fell **and** median ' +
+            'cognitive complexity per changed function did not rise **and** the ' +
+            'safety tier did not regress. An unmeasured endpoint is never a pass.',
+    );
+    L.push('');
+    if (claims.length === 0) {
+        L.push('_No comparison rendered — no arms to compare._');
+        L.push('');
+        return L;
+    }
+    L.push('| comparison | verdict | why |');
+    L.push('|---|---|---|');
+    for (const c of claims) {
+        L.push(
+            `| \`${c.arm_treatment}\` vs \`${c.arm_baseline}\` ` +
+                `| **${c.verdict}** | ${c.reason} |`,
+        );
+    }
+    L.push('');
+    return L;
+}