@event4u/agent-config 14.12.0 → 14.14.0

package/src/scripts/_lib/judge_hygiene.ts

@@ -0,0 +1,228 @@
+/**
+ * Judge hygiene — what an assertion is worth, and what a pass verdict must show.
+ *
+ * `road-to-skill-ecosystem-eval-integrity` Phase 3, Steps 3–6. Steps 1 and 2
+ * (blinding and the order-swap) were already met by
+ * `check_quality_regression.evaluatePair`, which judges every pair in both
+ * orders and resolves a flip to `inconsistent` rather than to a winner — that
+ * is stronger than the step's own "default to a tie", because a flagged tie is
+ * still a tie in a denominator while `inconsistent` is its own bucket with its
+ * own reported rate.
+ *
+ * ── Why an assertion that always passes is worse than no assertion ──────────
+ * It inflates the treatment pass rate without reflecting any value: both arms
+ * satisfy it, so it contributes a guaranteed point to each and narrows nothing.
+ * The reverse — an assertion that always fails — is not noise but a broken
+ * check or an impossible expectation, and it is worth finding for a different
+ * reason. The interesting set is neither: the assertions that pass in treatment
+ * and fail in control ARE the measurement, and everything else is overhead
+ * masquerading as coverage.
+ */
+
+/** How a rubric item or assertion is phrased, which is what overfitting looks like. */
+export type OverfitShape = 'outcome' | 'technique' | 'vocabulary';
+
+export interface OverfitClassification {
+    shape: OverfitShape;
+    /** Why this shape, in one clause, printable in an advisory report. */
+    reason: string;
+}
+
+/**
+ * Phrases that name HOW rather than WHAT.
+ *
+ * `technique` is an assertion that prescribes a mechanism — it passes only for
+ * an implementation that took the route the author had in mind, so a better
+ * solution scores lower. `vocabulary` is narrower and worse: it checks that a
+ * particular WORD appears, which any arm can satisfy by saying the word.
+ */
+const TECHNIQUE_MARKERS = [
+    'using ',
+    'by calling',
+    'via ',
+    'with the helper',
+    'implemented as',
+    'should call',
+    'must call',
+    'invokes',
+];
+
+const VOCABULARY_MARKERS = [
+    'mentions',
+    'contains the word',
+    'uses the term',
+    'the phrase',
+    'says ',
+    'literally',
+];
+
+/**
+ * Classify one criterion by shape. ADVISORY — this gates nothing.
+ *
+ * Deliberately a keyword heuristic and deliberately never a verdict input. A
+ * classifier that decided anything would need to be right, and no phrase list
+ * is right about natural language; what it can do honestly is put a shape
+ * beside each item so a human reviewing a rubric sees that nine of twelve items
+ * check vocabulary. That is a real finding and it costs nothing to be wrong
+ * about one of them.
+ */
+export function classifyOverfit(criterion: string): OverfitClassification {
+    const c = criterion.toLowerCase();
+    for (const m of VOCABULARY_MARKERS) {
+        if (c.includes(m)) {
+            return {
+                shape: 'vocabulary',
+                reason: `phrased around wording ("${m.trim()}") — any arm passes by saying the word`,
+            };
+        }
+    }
+    for (const m of TECHNIQUE_MARKERS) {
+        if (c.includes(m)) {
+            return {
+                shape: 'technique',
+                reason: `prescribes a mechanism ("${m.trim()}") — a better route scores lower`,
+            };
+        }
+    }
+    return { shape: 'outcome', reason: 'phrased as a result rather than a route or a wording' };
+}
+
+/** One assertion's behaviour across both arms of a paired run. */
+export interface AssertionObservation {
+    id: string;
+    /** Trials where this assertion passed in the treatment arm. */
+    treatment_passes: number;
+    /** Trials where it passed in the control arm. */
+    control_passes: number;
+    trials: number;
+}
+
+export type AssertionVerdict =
+    | 'discriminating'
+    | 'non-discriminating-always-pass'
+    | 'non-discriminating-always-fail'
+    | 'inverted'
+    | 'partial';
+
+export interface AssertionFinding {
+    id: string;
+    verdict: AssertionVerdict;
+    /** The prescribed action, so the report does not stop at a label. */
+    action: string;
+}
+
+/**
+ * Classify an assertion by whether it separates the arms.
+ *
+ * The pruning rule of Step 5 is expressed HERE rather than as prose in a
+ * document, because a rule that lives only in a document is applied by whoever
+ * remembers it:
+ *
+ *   · always passes in both  → REMOVE or replace. It is pure inflation.
+ *   · always fails in both   → INVESTIGATE. A broken check or an impossible bar.
+ *   · treatment > control    → KEEP. This is where the value is.
+ *   · control > treatment    → KEEP and read it. An inverted assertion is a
+ *                              finding about the treatment, not a defect here.
+ */
+export function classifyAssertion(o: AssertionObservation): AssertionFinding {
+    if (o.trials <= 0) {
+        return {
+            id: o.id,
+            verdict: 'partial',
+            action: 'no trials — the assertion was never exercised, which is not a result',
+        };
+    }
+    const allT = o.treatment_passes === o.trials;
+    const allC = o.control_passes === o.trials;
+    const noneT = o.treatment_passes === 0;
+    const noneC = o.control_passes === 0;
+    if (allT && allC) {
+        return {
+            id: o.id,
+            verdict: 'non-discriminating-always-pass',
+            action:
+                'remove or replace — it passes in both arms, so it adds a guaranteed point to each ' +
+                'and inflates the treatment pass rate without reflecting value',
+        };
+    }
+    if (noneT && noneC) {
+        return {
+            id: o.id,
+            verdict: 'non-discriminating-always-fail',
+            action:
+                'investigate — an assertion nothing satisfies is a broken check or an impossible ' +
+                'expectation, not a measurement of the treatment',
+        };
+    }
+    if (o.treatment_passes > o.control_passes) {
+        return { id: o.id, verdict: 'discriminating', action: 'keep — this is where the value is' };
+    }
+    if (o.control_passes > o.treatment_passes) {
+        return {
+            id: o.id,
+            verdict: 'inverted',
+            action:
+                'keep and read it — the control satisfies this more often, which is a finding about ' +
+                'the treatment rather than a defect in the assertion',
+        };
+    }
+    return {
+        id: o.id,
+        verdict: 'partial',
+        action: 'keep — equal pass counts but not saturated, so it still carries information',
+    };
+}
+
+/** Summary a report can print, with the inflation number named. */
+export interface AssertionAudit {
+    findings: readonly AssertionFinding[];
+    discriminating: number;
+    non_discriminating: number;
+    /** Points every arm is guaranteed by always-pass assertions. */
+    guaranteed_points: number;
+}
+
+export function auditAssertions(obs: readonly AssertionObservation[]): AssertionAudit {
+    const findings = obs.map(classifyAssertion);
+    const nd = findings.filter((f) => f.verdict.startsWith('non-discriminating')).length;
+    return {
+        findings,
+        discriminating: findings.filter((f) => f.verdict === 'discriminating').length,
+        non_discriminating: nd,
+        guaranteed_points: findings.filter((f) => f.verdict === 'non-discriminating-always-pass').length,
+    };
+}
+
+/**
+ * Does a section carry EVIDENCE, or only the label a pass was looking for?
+ *
+ * Step 6. The failure it names is specific and common: a section headed with the
+ * expected label followed by one vague sentence scores as a pass, because the
+ * label being present was mistaken for the substance being present. The check is
+ * deliberately crude — a length floor plus a concreteness signal — because the
+ * alternative is a judge, and a judge is the thing whose output this is meant to
+ * check.
+ *
+ * Returns `null` when the section passes, or the reason it does not.
+ */
+export function evidenceDeficit(section: string, opts: { minWords?: number } = {}): string | null {
+    const minWords = opts.minWords ?? 25;
+    const body = section.replace(/^#{1,6} .*$/gm, '').trim();
+    const words = body.split(/\s+/).filter((w) => w !== '').length;
+    if (words < minWords) {
+        return `carries ${String(words)} word(s) of body, below the ${String(minWords)}-word floor — ` +
+            'the label is present and the substance is not';
+    }
+    // A concrete claim cites something a reader can check: a path, a number, a
+    // command, an identifier. Prose with none of those is an assertion about
+    // itself.
+    const concrete =
+        /[\w./-]+\.(?:ts|js|md|json|ya?ml|py|sh)\b/.test(body) ||
+        /\b\d+(?:\.\d+)?\s*(?:%|ms|s|MB|KB|lines?|files?|cases?|trials?)\b/.test(body) ||
+        /`[^`]+`/.test(body);
+    if (!concrete) {
+        return 'no checkable reference — no path, no measured figure, no identifier. A section that ' +
+            'cites nothing is a claim about itself.';
+    }
+    return null;
+}

package/src/scripts/_lib/legacy_boundary_map.ts

@@ -0,0 +1,228 @@
+/**
+ * A per-path legacy/modern verdict for a half-migrated repository.
+ *
+ * `road-to-consumer-repo-reality` Phase 4, step 4.1. Incremental replacement of
+ * a legacy system alongside the system it replaces is a named, published
+ * migration pattern; the artifact that pattern needs and nobody produces is a
+ * decidable answer to *"which conventions hold HERE"*.
+ *
+ * Current guidance says to respect existing patterns and to keep diffs minimal.
+ * Neither is decidable without this: in a tree that is two-fifths namespaced,
+ * strict-typed, PSR-shaped code and three-fifths an older include-and-dispatch
+ * module system, "the existing pattern" is not a property of the repository.
+ *
+ * A MIXED VERDICT IS NOT A REFUSAL TO DECIDE. That is the step's own wording and
+ * it is the hardest requirement here: a verdict that says only "mixed" leaves
+ * the caller exactly where it started. So a mixed file reports WHICH convention
+ * governs WHICH REGION, by line range, and `conventionAt(verdict, line)` answers
+ * the only question an editor actually has — *what must my edit at this point
+ * follow?*
+ *
+ * WHAT THIS MAY AND MAY NOT ENCODE. The phase states the trap in its own body:
+ * 4.2 and 4.3 were each observed in exactly one tree, so what may be encoded is
+ * the QUESTION, never the particular mechanism that tree happened to use. 4.1 is
+ * not in that category — namespaces, strict-type declarations and PSR-4
+ * autoloading are language-level and specification-level facts, not one
+ * repository's arrangement — but the same restraint is applied anyway: the
+ * signals below are all language constructs, and none is a project-specific
+ * naming convention, directory layout or framework marker.
+ *
+ * PER PATH, NEVER PER REPOSITORY. A repository-wide verdict is the thing that
+ * makes this artifact useless: the whole point is that the answer differs by
+ * file, and inside a file by region.
+ */
+import * as fs from 'node:fs';
+
+/** Which convention governs. `unknown` is returned rather than guessed. */
+export type Convention = 'modern' | 'legacy' | 'mixed' | 'unknown';
+
+/** A contiguous run of lines governed by one convention. */
+export interface Region {
+    /** 1-indexed, inclusive. */
+    startLine: number;
+    /** 1-indexed, inclusive. */
+    endLine: number;
+    convention: 'modern' | 'legacy';
+    /** The construct that decided it. Never empty. */
+    signal: string;
+}
+
+export interface PathVerdict {
+    /** The path as given. */
+    path: string;
+    convention: Convention;
+    /**
+     * Populated for EVERY verdict that is not `unknown`, including a
+     * single-convention file — a caller should not need two code paths.
+     */
+    regions: Region[];
+    /**
+     * A single foreign signal inside an otherwise uniform file — one `$GLOBALS`
+     * read in a namespaced class, one class-like declaration in an
+     * include-and-dispatch file. Reported as a POINT and deliberately not as a
+     * region: a lone signal says something true about ITS line and nothing about
+     * the lines after it, and letting it open a region made every line to the end
+     * of the file inherit a convention it does not have.
+     */
+    foreignPoints: { line: number; convention: 'modern' | 'legacy'; signal: string }[];
+    /** One sentence naming what decided it. Never empty. */
+    reason: string;
+}
+
+/**
+ * Signals, as language constructs only.
+ *
+ * `modern` markers are things the older include-and-dispatch style cannot
+ * express; `legacy` markers are things the namespaced style does not use. A line
+ * matching neither is inherited from the enclosing region rather than guessed —
+ * most lines in any file carry no signal at all.
+ */
+const MODERN: readonly { re: RegExp; signal: string }[] = [
+    { re: /^\s*declare\s*\(\s*strict_types\s*=\s*1\s*\)/, signal: 'declare(strict_types=1)' },
+    { re: /^\s*namespace\s+[A-Za-z_]/, signal: 'namespace declaration' },
+    { re: /^\s*use\s+[A-Za-z_][A-Za-z0-9_]*\\/, signal: 'namespaced use statement' },
+    { re: /^\s*(?:final\s+|abstract\s+)?(?:readonly\s+)?(?:class|interface|trait|enum)\s+/, signal: 'class-like declaration' },
+];
+
+const LEGACY: readonly { re: RegExp; signal: string }[] = [
+    { re: /^\s*(?:require|include)(?:_once)?\s*[\s(]/, signal: 'require/include' },
+    { re: /^\s*global\s+\$/, signal: 'global statement' },
+    { re: /\$GLOBALS\s*\[/, signal: '$GLOBALS access' },
+    { re: /^\s*function\s+[a-z][A-Za-z0-9_]*\s*\(/, signal: 'unnamespaced snake/camel function' },
+];
+
+/**
+ * Requiring the Composer autoloader is the MODERN ecosystem's own bootstrap, not
+ * the include-and-dispatch pattern. Without this exception the canonical PSR-4
+ * entry point — `require __DIR__ . '/../vendor/autoload.php';` — makes every
+ * modern application's front controller come back `mixed`, which is the single
+ * most common file shape in the ecosystem this module is meant to classify.
+ */
+const AUTOLOAD_REQUIRE = /vendor\/autoload\.php/;
+
+/**
+ * A line that is only a comment carries no convention. `// never touch
+ * $GLOBALS['x']` is advice ABOUT legacy code, and reading it as legacy code
+ * flips the region a reader is standing in. Block-comment interiors are not
+ * tracked — that needs a lexer — so only whole-line `//`, `#` and `*`
+ * continuations are skipped.
+ */
+const COMMENT_ONLY = /^\s*(?:\/\/|#|\*|\/\*)/;
+
+function _signalFor(line: string): { convention: 'modern' | 'legacy'; signal: string } | null {
+    if (COMMENT_ONLY.test(line)) return null;
+    for (const { re, signal } of MODERN) if (re.test(line)) return { convention: 'modern', signal };
+    if (AUTOLOAD_REQUIRE.test(line)) return null;
+    for (const { re, signal } of LEGACY) if (re.test(line)) return { convention: 'legacy', signal };
+    return null;
+}
+
+/**
+ * Classify one file's text into regions.
+ *
+ * A signal starts a region that runs until the next signal of the OTHER
+ * convention. Lines before the first signal belong to the first region, so every
+ * line of a classified file is covered — a caller asking about line 1 of a file
+ * whose first signal is on line 3 gets an answer rather than a hole.
+ */
+export function classifyText(pathName: string, text: string): PathVerdict {
+    const lines = text.split('\n');
+    const hits: { line: number; convention: 'modern' | 'legacy'; signal: string }[] = [];
+    for (let i = 0; i < lines.length; i += 1) {
+        const hit = _signalFor(lines[i] ?? '');
+        if (hit !== null) hits.push({ line: i + 1, ...hit });
+    }
+
+    // A lone signal of one convention, against two or more of the other, is a
+    // POINT rather than a region boundary. Two is the threshold because one
+    // occurrence is as likely to be an artifact — a legacy global read inside a
+    // modern service, a single class declaration in an old dispatch file — as a
+    // statement about the surrounding code.
+    const counts = { modern: 0, legacy: 0 };
+    for (const h of hits) counts[h.convention] += 1;
+    const isolated: 'modern' | 'legacy' | null =
+        counts.modern === 1 && counts.legacy >= 2 ? 'modern'
+        : counts.legacy === 1 && counts.modern >= 2 ? 'legacy'
+        : null;
+    const foreignPoints = isolated === null ? [] : hits.filter((h) => h.convention === isolated);
+    const structural = isolated === null ? hits : hits.filter((h) => h.convention !== isolated);
+
+    const regions: Region[] = [];
+    for (const hit of structural) {
+        const i = hit.line - 1;
+        const last = regions[regions.length - 1];
+        if (last !== undefined && last.convention === hit.convention) {
+            last.endLine = i + 1;
+            continue;
+        }
+        regions.push({ startLine: i + 1, endLine: i + 1, convention: hit.convention, signal: hit.signal });
+    }
+
+    if (regions.length === 0) {
+        return {
+            path: pathName,
+            convention: 'unknown',
+            regions: [],
+            foreignPoints,
+            reason: 'no convention signal found — neither a namespaced construct nor an include-and-dispatch one',
+        };
+    }
+
+    // Extend each region to meet the next, and the first back to line 1, so the
+    // whole file is covered and `conventionAt` never returns a hole.
+    const first = regions[0] as Region;
+    first.startLine = 1;
+    for (let i = 0; i < regions.length - 1; i += 1) {
+        (regions[i] as Region).endLine = (regions[i + 1] as Region).startLine - 1;
+    }
+    (regions[regions.length - 1] as Region).endLine = Math.max(lines.length, 1);
+
+    const kinds = new Set(regions.map((r) => r.convention));
+    if (kinds.size === 1) {
+        const only = [...kinds][0] as 'modern' | 'legacy';
+        return {
+            path: pathName,
+            convention: only,
+            regions,
+            foreignPoints,
+            reason:
+                `every structural signal in this file is ${only} (${regions.map((r) => r.signal).join(', ')})` +
+                (foreignPoints.length === 0
+                    ? ''
+                    : `. One isolated ${isolated} signal at L${foreignPoints.map((f) => f.line).join(', L')} ` +
+                      `(${foreignPoints.map((f) => f.signal).join(', ')}) — true of that line, not of the lines after it`),
+        };
+    }
+    return {
+        path: pathName,
+        convention: 'mixed',
+        regions,
+        foreignPoints,
+        reason:
+            `both conventions appear in this file, in ${regions.length} regions. ` +
+            regions.map((r) => `L${r.startLine}-${r.endLine} ${r.convention} (${r.signal})`).join('; ') +
+            '. An edit follows the convention of the region it lands in, not the file as a whole.',
+    };
+}
+
+/** Read and classify one file. An unreadable file is `unknown`, never guessed. */
+export function classifyPath(absPath: string, displayPath = absPath): PathVerdict {
+    try {
+        return classifyText(displayPath, fs.readFileSync(absPath, 'utf8'));
+    } catch {
+        return { path: displayPath, convention: 'unknown', regions: [], foreignPoints: [], reason: 'unreadable' };
+    }
+}
+
+/**
+ * The only question an editor actually has: what must an edit at THIS line
+ * follow? Returns `null` when the file carries no signal at all — which is a
+ * real answer, and different from "modern by default".
+ */
+export function conventionAt(verdict: PathVerdict, line: number): 'modern' | 'legacy' | null {
+    for (const f of verdict.foreignPoints) if (f.line === line) return f.convention;
+    for (const r of verdict.regions) {
+        if (line >= r.startLine && line <= r.endLine) return r.convention;
+    }
+    return null;
+}

package/src/scripts/_lib/lexical_shortlist.ts

@@ -0,0 +1,215 @@
+/**
+ * A lexical shortlist over the existing BM25 core — a SHORTLIST, never a decider.
+ *
+ * `road-to-governed-harness-evolution` Phase 6, step 6.3.
+ *
+ * > *6.3 Only then consider a lexical shortlist, and only as a shortlist. Over
+ * > the existing BM25 core. No embeddings […]. The skipped parent proposed the
+ * > shortlist and explicitly refused it as final truth.*
+ * > verify: **the shortlist feeds a later stage and never decides alone.**
+ *
+ * ## No embeddings, and the citation this step carried had moved
+ *
+ * The step's own text cites `docs/contracts/no-runtime-boundary.md:40` for the
+ * classification. That file is now a **superseded pointer** (ADR-249,
+ * 2026-08-27) and line 40 no longer says it. The substance survived the move
+ * intact and is quoted from its live home instead:
+ * `docs/contracts/resident-process-governance.md:82` — *"A code-graph cache
+ * passes; a vector index fails"*, under the P3 state-store test, with P4
+ * separately prohibiting any index build requiring network or model calls.
+ * So this module builds over `_lib/lexical_index.ts` — hand-rolled BM25, pure
+ * Node stdlib, the core ADR-061 already sanctions. A static scan in
+ * `tests/scripts/_lib/lexical_shortlist.test.ts` asserts this module and that
+ * core reach no embedding construct, no vector store and no model call. The
+ * construct list lives in the test rather than here for a mechanical reason:
+ * a scanner whose banned literals sit in the file it scans matches its own
+ * declaration and can never pass — the same reason
+ * `tests/scripts/governed_harness_no_live_harness.test.ts` keeps its banned set
+ * on the test side.
+ *
+ * ## "Never decides alone", made mechanical rather than promised
+ *
+ * A shortlist decides alone in exactly two ways, and both are closed here by
+ * construction rather than by a caller's discipline:
+ *
+ *   1. **By addition** — delivering something the authoritative matcher did not
+ *      fire on. Impossible: {@link orderByShortlist} takes the matcher's output
+ *      as its input domain and returns a PERMUTATION of it. Ids the shortlist
+ *      ranks that the matcher did not return are dropped on the floor, and
+ *      {@link selectForInjection}'s tie-break argument is consulted only to
+ *      order ids that are already in `matches`.
+ *   2. **By subtraction** — silently removing a matcher hit, which is a
+ *      decision dressed as a filter. Impossible: the same permutation
+ *      invariant. {@link ShortlistDecidedAloneError} is thrown when the output
+ *      id multiset differs from the input's in either direction, so a future
+ *      edit that turns the reordering into a filter fails loudly instead of
+ *      quietly losing recall.
+ *
+ * The shortlist's actual job is the third thing, and it is a real one: when the
+ * per-prompt byte cap BINDS, something has to choose which matched bodies
+ * survive it. Today that is the matcher's trigger-hit count and then router
+ * declaration order — and the hit count is a coarse integer on which most rules
+ * tie, so the surviving set is decided by declaration order, which is not a
+ * relevance signal at all. The shortlist supplies one, subordinate to the
+ * matcher score and never above it.
+ *
+ * ## Subordination is an ORDER of comparison keys, and the order is the contract
+ *
+ * `score desc → shortlist rank → router order`. The matcher's verdict is read
+ * first and the shortlist only breaks its ties. Promoting the shortlist above
+ * `score` would let a lexically-similar rule outrank one the matcher fired on
+ * twice, which is the shortlist deciding — a test pins the key order and is
+ * proved to go red when it is inverted.
+ *
+ * ## What this module does NOT claim
+ *
+ * That the shortlist improves anything. Whether a lexical tie-break beats
+ * declaration order under a binding cap is a MEASUREMENT, and step 6.4 is where
+ * the loss ceiling for it gets pre-registered. `model_rule_injection
+ * --three-arm --shortlist` runs the arm with it, default OFF, so 6.1's recorded
+ * figures are reproducible unchanged.
+ */
+import { LexicalIndex, type IndexDoc } from './lexical_index.js';
+import { allTierRules, loadRuleBody, type Router, type TierRuleMatch } from './rule_injection.js';
+
+/**
+ * How many ids a shortlist may carry.
+ *
+ * A STATED default, not a measured optimum, and deliberately generous: this
+ * shortlist narrows nothing (it reorders), so `k` bounds only how far down the
+ * BM25 ranking a tie-break signal is available before router order takes over.
+ * Revisit-if 6.4 measures a cap-drop the shortlist could have prevented at a
+ * rank beyond it.
+ */
+export const SHORTLIST_SIZE = 40;
+
+export class ShortlistDecidedAloneError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'ShortlistDecidedAloneError';
+    }
+}
+
+/**
+ * Index every tier rule that has a projected body.
+ *
+ * Kernel rules are excluded for the same reason `_lib/rule_injection.ts`
+ * excludes them from injection: they are standing context by definition, so
+ * they are never candidates for a cap that only ever binds on injected bodies.
+ * `allTierRules` already returns the non-kernel set.
+ */
+export function buildRuleIndex(repoRoot: string, router: Router): LexicalIndex {
+    const docs: IndexDoc[] = [];
+    for (const r of allTierRules(router)) {
+        const body = loadRuleBody(repoRoot, r.id);
+        if (body === null) continue;
+        // The id is joined into the text on purpose: a rule's own name is the
+        // single most reliable lexical signal it carries, and hyphenated ids
+        // tokenise into exactly the words a prompt about that rule would use.
+        docs.push({ id: r.id, text: `${r.id.split('-').join(' ')}\n${body}` });
+    }
+    return new LexicalIndex(docs);
+}
+
+/**
+ * The ranked shortlist for one prompt. BM25 only; no model call, no embedding.
+ *
+ * Returns ids in descending relevance, capped at `k`. An empty result is a real
+ * answer — it means no indexed body shares a scoring term with the prompt, and
+ * the caller then falls back to router order exactly as it does today.
+ */
+export function shortlistIds(
+    index: LexicalIndex,
+    prompt: string,
+    k: number = SHORTLIST_SIZE,
+): string[] {
+    if (k <= 0) return [];
+    return index.rank([prompt]).slice(0, k).map((r) => r.id);
+}
+
+/**
+ * Rank lookup: id → position in the shortlist, or `Infinity` for absent.
+ *
+ * `Infinity` rather than a large integer so an unshortlisted id can never sort
+ * above a shortlisted one by arithmetic accident.
+ */
+export function shortlistRanks(ranked: readonly string[]): Map<string, number> {
+    const m = new Map<string, number>();
+    for (const [i, id] of ranked.entries()) {
+        if (!m.has(id)) m.set(id, i);
+    }
+    return m;
+}
+
+/**
+ * Reorder the matcher's output by the shortlist — a PERMUTATION, always.
+ *
+ * This is the function that makes "never decides alone" checkable. It takes the
+ * matcher's verdict as its input domain, applies the same key order
+ * {@link selectForInjection} applies (`score desc → shortlist rank → router
+ * order`), and REFUSES to return anything whose id multiset differs from what
+ * it was given.
+ *
+ * @throws {ShortlistDecidedAloneError} when the result would add or drop an id.
+ */
+export function orderByShortlist(
+    matches: readonly TierRuleMatch[],
+    ranked: readonly string[],
+): TierRuleMatch[] {
+    const rank = shortlistRanks(ranked);
+    const out = [...matches].sort(
+        (a, b) =>
+            b.score - a.score ||
+            (rank.get(a.id) ?? Infinity) - (rank.get(b.id) ?? Infinity) ||
+            a.order - b.order,
+    );
+    assertPermutation(matches, out);
+    return out;
+}
+
+/** Same-multiset assertion, in both directions. Exported so a test can drive it. */
+export function assertPermutation(
+    before: readonly TierRuleMatch[],
+    after: readonly TierRuleMatch[],
+): void {
+    const count = (xs: readonly TierRuleMatch[]): Map<string, number> => {
+        const m = new Map<string, number>();
+        for (const x of xs) m.set(x.id, (m.get(x.id) ?? 0) + 1);
+        return m;
+    };
+    const a = count(before);
+    const b = count(after);
+    const added: string[] = [];
+    const dropped: string[] = [];
+    for (const [id, n] of b) {
+        if ((a.get(id) ?? 0) < n) added.push(id);
+    }
+    for (const [id, n] of a) {
+        if ((b.get(id) ?? 0) < n) dropped.push(id);
+    }
+    if (added.length > 0 || dropped.length > 0) {
+        throw new ShortlistDecidedAloneError(
+            'the shortlist changed the matcher`s set instead of ordering it' +
+                (added.length > 0 ? ` — added ${added.sort().join(', ')}` : '') +
+                (dropped.length > 0 ? ` — dropped ${dropped.sort().join(', ')}` : '') +
+                '. A shortlist that adds delivers what the matcher never fired on; one that ' +
+                'drops decides by subtraction. Both are the shortlist deciding alone.',
+        );
+    }
+}
+
+/**
+ * A per-prompt shortlist function, bound to one repo root and router.
+ *
+ * The index is built ONCE and reused for every prompt — building it per prompt
+ * would make the cheap stage the expensive one, which is the opposite of what a
+ * shortlist is for.
+ */
+export function makePromptShortlist(
+    repoRoot: string,
+    router: Router,
+    k: number = SHORTLIST_SIZE,
+): (prompt: string) => readonly string[] {
+    const index = buildRuleIndex(repoRoot, router);
+    return (prompt: string) => shortlistIds(index, prompt, k);
+}