@event4u/agent-config 14.12.0 → 14.14.0

package/src/scripts/_lib/role_split.ts

@@ -0,0 +1,338 @@
+/**
+ * Three roles, three prompts, three input sets — and a judge that cannot see
+ * outcome truth.
+ *
+ * `road-to-governed-harness-evolution` Phase 5, step 5.3.
+ *
+ * > *Split the roles: analyzer, curator, proposer. Do not collapse them into
+ * > one unconstrained rewrite prompt. An optional judge model grades rubric
+ * > questions only, under a frozen evaluator contract.*
+ * > verify: **the three roles are separate prompts with separate input sets,
+ * > and the judge cannot see outcome truth.**
+ *
+ * ## Separate input sets, enforced at the boundary rather than by convention
+ *
+ * {@link ROLE_INPUTS} declares which input kinds each role may receive, and
+ * {@link buildPrompt} REFUSES an input whose kind is not in that role's set.
+ * Separation therefore survives a caller who assembles one bag of everything
+ * and hands it to all three, which is precisely how three roles collapse back
+ * into one unconstrained rewrite prompt in practice: nobody decides to collapse
+ * them, the input set just widens one field at a time until the roles differ
+ * only in their preamble.
+ *
+ * The sets are deliberately not disjoint — every role sees `defect-observation`,
+ * because a curator deciding `RETIRE` without the evidence that motivated it is
+ * guessing. What no role sees is the UNION, and a test pins that: the widest
+ * role's set is a strict subset of the vocabulary.
+ *
+ * ## The judge, and why "absent" was not good enough
+ *
+ * The load-bearing half of the verify clause is that the judge cannot see
+ * outcome truth. A judge that merely is not GIVEN the outcome is one careless
+ * spread away from seeing it, and the spread reads as harmless in review. So
+ * the property is structural in two independent layers:
+ *
+ *   1. {@link JudgeInput} has no field capable of carrying an outcome. It is
+ *      three fields — a contract id, rubric question ids, and the artifact text
+ *      — and none of them can hold a verdict, an arm label, a metric, or a
+ *      winner. `tests/scripts/role_split.test.ts` scans the declared interface
+ *      for the outcome-truth field vocabulary, and proves the scanner fires on
+ *      a synthetic interface before trusting it to be silent on this one.
+ *   2. {@link buildJudgePrompt} rejects any key outside {@link JUDGE_INPUT_KEYS}.
+ *      Types vanish at runtime, so a caller casting a wider object through
+ *      `as JudgeInput` would defeat layer 1 alone; layer 2 throws on that
+ *      object rather than quietly serialising the surplus field into the prompt.
+ *
+ * The judge's own output vocabulary is closed and outcome-free
+ * ({@link JUDGE_GRADES}): it answers a rubric question, and there is no value it
+ * can return that names an arm or declares a winner.
+ *
+ * ## The frozen evaluator contract is the one that already exists
+ *
+ * The contract id travels on the prompt, and {@link promoteJudgeContract} is the
+ * only way to change it — it delegates to
+ * `evaluator_promotion.assertEvaluatorPromotable`, so a judge-contract change
+ * inherits the cross-grade and discrimination-plant requirements step 4.7
+ * already built rather than getting a second, weaker gate of its own.
+ */
+import { CURATOR_OPS } from './curator_ops.js';
+import { assertEvaluatorPromotable, type EvaluatorChange } from './evaluator_promotion.js';
+import { classifyOverfit } from './judge_hygiene.js';
+
+/** The three roles. The judge is deliberately NOT one of them — it is optional. */
+export const ROLES = ['analyzer', 'curator', 'proposer'] as const;
+export type Role = (typeof ROLES)[number];
+
+/** The closed vocabulary of input kinds a role may be given. */
+export const INPUT_KINDS = [
+    'defect-observation',
+    'trigger-census',
+    'corpus-inventory',
+    'lifecycle-history',
+    'analyzer-finding',
+    'curator-decision',
+    'authoring-contract',
+] as const;
+export type InputKind = (typeof INPUT_KINDS)[number];
+
+export interface RoleInput {
+    kind: InputKind;
+    id: string;
+    text: string;
+}
+
+/**
+ * Which input kinds each role may receive.
+ *
+ * The analyzer reads evidence and nothing about the corpus, so it cannot
+ * propose a lifecycle op. The curator reads the corpus and the analyzer's
+ * findings, so it decides WHICH artifact changes without ever seeing the
+ * authoring contract that would let it write one. The proposer reads the
+ * curator's decision and the authoring contract, so it writes text for a
+ * decision that was already made elsewhere.
+ */
+export const ROLE_INPUTS: Readonly<Record<Role, readonly InputKind[]>> = {
+    analyzer: ['defect-observation', 'trigger-census'],
+    curator: ['defect-observation', 'corpus-inventory', 'lifecycle-history', 'analyzer-finding'],
+    proposer: ['defect-observation', 'curator-decision', 'authoring-contract'],
+};
+
+/** What each role is asked to produce. One sentence, and they do not overlap. */
+const ROLE_TASK: Readonly<Record<Role, string>> = {
+    analyzer:
+        'Name the defect classes the evidence supports, each with the observation ids that carry it. ' +
+        'Do not name an artifact to change and do not propose text.',
+    curator:
+        `Choose exactly one lifecycle operation from ${CURATOR_OPS.join(' / ')} per finding, with its targets. ` +
+        'Do not write the artifact body — that decision is not yours to author.',
+    proposer:
+        'Write the candidate body for the curator decision you were given, against the authoring contract. ' +
+        'Do not revisit the operation, the targets, or whether the change is warranted.',
+};
+
+export class RoleContractViolation extends Error {
+    readonly reasons: readonly string[];
+    constructor(reasons: readonly string[]) {
+        super(`role contract violated: ${reasons.join('; ')}`);
+        this.name = 'RoleContractViolation';
+        this.reasons = reasons;
+    }
+}
+
+export interface RolePrompt {
+    role: Role;
+    text: string;
+    /** The kinds actually supplied, sorted — the prompt's declared input set. */
+    input_kinds: readonly InputKind[];
+}
+
+/**
+ * Build one role's prompt, refusing any input kind outside that role's set.
+ *
+ * Fail-closed by construction: there is no option object that widens a role's
+ * set, so a caller who wants to feed the curator an authoring contract has to
+ * edit {@link ROLE_INPUTS}, which is visible in a diff.
+ */
+export function buildPrompt(role: Role, inputs: readonly RoleInput[]): RolePrompt {
+    const allowed = new Set<InputKind>(ROLE_INPUTS[role]);
+    const rejected = inputs.filter((i) => !allowed.has(i.kind));
+    if (rejected.length > 0) {
+        throw new RoleContractViolation(
+            rejected.map(
+                (i) =>
+                    `role '${role}' may not receive input kind '${i.kind}' (input '${i.id}') — ` +
+                    `its set is ${[...allowed].join(', ')}`,
+            ),
+        );
+    }
+    const kinds = [...new Set(inputs.map((i) => i.kind))].sort((a, b) => a.localeCompare(b));
+    const body = inputs
+        .map((i) => `[${i.kind}:${i.id}]\n${i.text}`)
+        .sort((a, b) => a.localeCompare(b))
+        .join('\n\n');
+    return {
+        role,
+        text: `## Role: ${role}\n\n${ROLE_TASK[role]}\n\n## Inputs\n\n${body}`,
+        input_kinds: kinds,
+    };
+}
+
+/* ─────────────────────────── the optional judge ─────────────────────────── */
+
+/**
+ * Every key a judge prompt may be built from. Frozen, and checked at runtime,
+ * because a cast defeats the type but not this list.
+ */
+export const JUDGE_INPUT_KEYS = ['evaluator_contract_id', 'rubric_question_ids', 'artifact_text'] as const;
+
+/**
+ * The judge's entire view.
+ *
+ * No field here can carry an outcome: not a verdict, not an arm label, not a
+ * metric, not a winner, not a ground-truth label. That is the point, and it is
+ * asserted mechanically rather than left to review.
+ */
+export interface JudgeInput {
+    evaluator_contract_id: string;
+    rubric_question_ids: readonly string[];
+    artifact_text: string;
+}
+
+/** The judge's closed answer vocabulary. Nothing here names an arm or a winner. */
+export const JUDGE_GRADES = ['yes', 'no', 'not-assessable'] as const;
+export type JudgeGrade = (typeof JUDGE_GRADES)[number];
+
+export class EvaluatorContractViolation extends Error {
+    readonly reasons: readonly string[];
+    constructor(reasons: readonly string[]) {
+        super(`evaluator contract violated: ${reasons.join('; ')}`);
+        this.name = 'EvaluatorContractViolation';
+        this.reasons = reasons;
+    }
+}
+
+/**
+ * Words that would make a rubric question an outcome question.
+ *
+ * A rubric question asks a property of ONE artifact. The moment it asks which
+ * of two did better, the judge is grading the experiment rather than the text,
+ * and its answer becomes a second verdict beside `paired_verdict` — Risk 1 on
+ * this roadmap.
+ */
+const OUTCOME_QUESTION_MARKERS = [
+    'which arm',
+    'which candidate',
+    'which version',
+    'treatment',
+    'control arm',
+    'baseline arm',
+    'winner',
+    'won',
+    'better than',
+    'outperform',
+    'ground truth',
+    'correct answer',
+    'passed the eval',
+    'regression',
+];
+
+export interface RubricQuestion {
+    id: string;
+    text: string;
+}
+
+export interface RubricAudit {
+    /** Advisory shape per `judge_hygiene.classifyOverfit`. Gates nothing. */
+    shapes: readonly { id: string; shape: string; reason: string }[];
+}
+
+/**
+ * Throw {@link EvaluatorContractViolation} on any question that asks about
+ * outcome truth, and return the advisory shape audit for the rest.
+ */
+export function assertRubricOnly(questions: readonly RubricQuestion[]): RubricAudit {
+    const reasons: string[] = [];
+    for (const q of questions) {
+        const lower = q.text.toLowerCase();
+        const hit = OUTCOME_QUESTION_MARKERS.find((m) => lower.includes(m));
+        if (hit !== undefined) {
+            reasons.push(`question '${q.id}' asks about outcome truth ("${hit}") — the judge grades text, not runs`);
+        }
+    }
+    if (reasons.length > 0) throw new EvaluatorContractViolation(reasons);
+    return {
+        shapes: questions.map((q) => {
+            const c = classifyOverfit(q.text);
+            return { id: q.id, shape: c.shape, reason: c.reason };
+        }),
+    };
+}
+
+export interface JudgePrompt {
+    /** Deliberately not a {@link Role}: the judge is optional and outside the split. */
+    role: 'judge';
+    evaluator_contract_id: string;
+    text: string;
+}
+
+/**
+ * Build the judge prompt from the allowlist and nothing else.
+ *
+ * The surplus-key check is the layer that survives a cast. `JudgeInput` cannot
+ * DECLARE an outcome field, but `x as JudgeInput` can still carry one at
+ * runtime, and a builder that spread its input would serialise it into the
+ * prompt. This one enumerates {@link JUDGE_INPUT_KEYS} and refuses anything else.
+ */
+export function buildJudgePrompt(input: JudgeInput, questions: readonly RubricQuestion[]): JudgePrompt {
+    const allowed = new Set<string>(JUDGE_INPUT_KEYS);
+    const surplus = Object.keys(input as unknown as Record<string, unknown>).filter((k) => !allowed.has(k));
+    if (surplus.length > 0) {
+        throw new EvaluatorContractViolation(
+            surplus.map((k) => `judge input carries '${k}', which is outside the frozen key set`),
+        );
+    }
+    assertRubricOnly(questions);
+    const asked = questions
+        .filter((q) => input.rubric_question_ids.includes(q.id))
+        .map((q) => `- ${q.id}: ${q.text}`)
+        .join('\n');
+    return {
+        role: 'judge',
+        evaluator_contract_id: input.evaluator_contract_id,
+        text:
+            `## Role: judge (contract ${input.evaluator_contract_id})\n\n` +
+            `Answer each rubric question with exactly one of ${JUDGE_GRADES.join(' / ')}. ` +
+            'You are grading one artifact against the question. You are not told how any run went, ' +
+            'and no answer you can give names an arm or a winner.\n\n' +
+            `## Rubric\n\n${asked}\n\n## Artifact\n\n${input.artifact_text}`,
+    };
+}
+
+/** Refuse a judge prompt built against a contract id other than the frozen one. */
+export function assertJudgeContractFrozen(prompt: JudgePrompt, frozenId: string): void {
+    if (prompt.evaluator_contract_id !== frozenId) {
+        throw new EvaluatorContractViolation([
+            `judge prompt cites contract '${prompt.evaluator_contract_id}' but the frozen contract is ` +
+                `'${frozenId}' — change it through promoteJudgeContract, not by editing the prompt`,
+        ]);
+    }
+}
+
+/**
+ * The only way to move the frozen judge contract forward.
+ *
+ * Delegates to step 4.7's `assertEvaluatorPromotable`, so a judge-contract
+ * change requires the same cross-grade over a frozen candidate set and the same
+ * discrimination plants as any other evaluator change. Returns the new id only
+ * once that gate has passed.
+ */
+export function promoteJudgeContract(change: EvaluatorChange): string {
+    assertEvaluatorPromotable(change);
+    return change.to;
+}
+
+/* ───────────────────────────── the pipeline ─────────────────────────────── */
+
+export interface SplitPipeline {
+    prompts: readonly RolePrompt[];
+    /** `null` when no judge is configured — the judge is optional, per the step. */
+    judge: JudgePrompt | null;
+}
+
+/**
+ * Assemble the three role prompts, each from its own input set, plus the
+ * optional judge.
+ *
+ * `inputsFor` is called once per role and its result passes through
+ * {@link buildPrompt}, so a supplier that returns one undifferentiated bag is
+ * refused rather than silently accepted.
+ */
+export function buildSplitPipeline(
+    inputsFor: (role: Role) => readonly RoleInput[],
+    judge: { input: JudgeInput; questions: readonly RubricQuestion[] } | null = null,
+): SplitPipeline {
+    return {
+        prompts: ROLES.map((r) => buildPrompt(r, inputsFor(r))),
+        judge: judge === null ? null : buildJudgePrompt(judge.input, judge.questions),
+    };
+}

package/src/scripts/_lib/routing_corpus.ts

@@ -0,0 +1,307 @@
+/**
+ * The corpus and catalogue substrate for the two routing measurements of
+ * `road-to-governed-harness-evolution` — step 5.1 (description vs body) and
+ * step 6.4 (delivery sets).
+ *
+ * ONE LOADER, TWO MEASUREMENTS. Both runs need the same three things: the
+ * frozen train/holdout partition, the trigger cases, and the skill catalogue
+ * the prompts are ranked against. Two loaders over one corpus is how two
+ * measurements start disagreeing about what they measured, so there is one.
+ *
+ * THE SEAL IS ENFORCED BY REFUSAL, NOT BY FILTERING. The holdout partition
+ * frozen in `agents/evidence/analysis/trigger-corpus-holdout-2026-08-30.md`
+ * says: no analyzer authored in Phase 5 may read the sealed corpora. So
+ * `loadTrainCases` never opens a holdout `evals/triggers.json` at all — the
+ * partition is computed from the DIRECTORY NAME, before any file is read.
+ * Filtering after the read would satisfy the letter and not the seal.
+ *
+ * The seal covers the corpus files and not the catalogue: a holdout skill's
+ * `SKILL.md` is still ranked against, because removing it would measure a
+ * catalogue that does not exist. The boundary is stated in the 5.1
+ * pre-registration rather than left to be inferred here.
+ *
+ * NO SCORER OF ITS OWN. Every score comes from `src/shared/skillRanking.ts`,
+ * the module the production ranker and the MCP handler already share. A second
+ * scorer in a measurement module would measure the measurement.
+ *
+ * Pure of network and of clock; reads files and nothing else.
+ */
+import * as fs from 'node:fs';
+import { createHash } from 'node:crypto';
+import * as path from 'node:path';
+
+import { scoreSkill, tokenize, type RankableSkill } from '../../shared/skillRanking.js';
+
+/**
+ * The partition constant the freeze artefact fixes. Changing it re-partitions
+ * the corpus and voids every result measured under the old one, which is why
+ * it is a named export a test can pin rather than a literal.
+ */
+export const HOLDOUT_CEILING = 51;
+
+export type Partition = 'holdout' | 'train';
+
+/** `holdout iff sha256(<skill-directory-name>)[0] < 51`, from the freeze artefact. */
+export function partitionOf(skill: string): Partition {
+    const bucket = parseInt(createHash('sha256').update(skill).digest('hex').slice(0, 2), 16);
+    return bucket < HOLDOUT_CEILING ? 'holdout' : 'train';
+}
+
+/** One adjudicated case: a prompt, and whether the owning skill must be delivered. */
+export interface CorpusCase {
+    readonly skill: string;
+    readonly prompt: string;
+    /** `true` = positive (must be delivered) · `false` = negative (must not). */
+    readonly expect: boolean;
+    /** Step 2.3's vocabulary where the file declares it; 876 of 931 cases do not. */
+    readonly caseClass: 'exemplar' | 'near-miss' | 'counterexample' | null;
+    readonly language: string | null;
+}
+
+interface RawQuery {
+    q?: unknown;
+    trigger?: unknown;
+    class?: unknown;
+    language?: unknown;
+}
+
+/**
+ * The two corpus shapes this tree carries.
+ *
+ * `queries[]` is the modern one. Two train files — `brand-asset-generation` and
+ * `estimate-ticket` — are the legacy `should_trigger` / `should_not_trigger`
+ * pair that step 2.3 grandfathered, and `lint_skill_trigger_corpus` returns
+ * before its class rules for exactly those two. A reader that understood only
+ * the modern shape would drop them SILENTLY, which is worse than refusing them:
+ * the run would report 80 train corpora where the partition says 82 and nothing
+ * would say which two were missing. So both shapes are read, and
+ * `legacyShaped` records which file used which.
+ */
+interface RawCorpus {
+    queries?: RawQuery[];
+    should_trigger?: unknown;
+    should_not_trigger?: unknown;
+}
+
+export function skillsDir(repoRoot: string): string {
+    return path.join(repoRoot, 'src', 'skills');
+}
+
+/**
+ * Is this `src/skills/<name>` entry test scaffolding rather than a skill?
+ *
+ * A `__`-prefixed directory is scaffolding by convention, and a real skill can
+ * never be named one: `skill.schema.json` pins `name` to `^[a-z][a-z0-9-]*$`
+ * and requires it to match the parent directory, so a leading underscore fails
+ * `validate_frontmatter`. This predicate therefore cannot hide a shipped skill.
+ *
+ * WHY IT EXISTS, measured rather than assumed.
+ * `tests/scripts/lint_originality.test.ts:64` writes a re-skin fixture to
+ * `src/skills/__origtest_reskin_fixture/SKILL.md` in the REAL tree and removes
+ * it in `afterEach`, because the linter resolves its corpus from a
+ * module-level ROOT and takes no root argument. During that window any
+ * concurrently-running test file that counts the catalogue sees 300 where the
+ * commit holds 299 — which is what failed
+ * `tests/scripts/routing_signal_measurement.test.ts` on
+ * `Node Tests (ubuntu-latest, shard 2/4)` in runs 33418425604 and 33424783559,
+ * intermittently, while passing in isolation and passing on the next run over
+ * two markdown files nothing reads.
+ *
+ * Reproduced locally before this line was written: with the fixture present on
+ * disk the assertion fails `300` vs `299`, character for character the CI
+ * message; with this predicate active it passes.
+ *
+ * Excluding the prefix here rather than threading a root through the linter is
+ * the smaller change by an order of magnitude: ROOT is baked into ten
+ * module-level constants there, and refactoring a shipped gate to suit a test
+ * is a worse trade than a naming convention the tree already follows.
+ */
+export function isScaffoldingSkillDir(name: string): boolean {
+    return name.startsWith('__');
+}
+
+/** Every skill directory that carries a trigger corpus, with its partition. */
+export function corpusSkills(repoRoot: string): { skill: string; partition: Partition }[] {
+    const dir = skillsDir(repoRoot);
+    if (!fs.existsSync(dir)) return [];
+    return fs
+        .readdirSync(dir)
+        .sort()
+        .filter((skill) => !isScaffoldingSkillDir(skill))
+        .filter((skill) => fs.existsSync(path.join(dir, skill, 'evals', 'triggers.json')))
+        .map((skill) => ({ skill, partition: partitionOf(skill) }));
+}
+
+/**
+ * The train cases. A holdout corpus is never opened — the partition is decided
+ * from the directory name and the sealed path is skipped before any read.
+ */
+export function loadTrainCases(repoRoot: string): CorpusCase[] {
+    const dir = skillsDir(repoRoot);
+    const out: CorpusCase[] = [];
+    for (const { skill, partition } of corpusSkills(repoRoot)) {
+        if (partition === 'holdout') continue;
+        const raw = JSON.parse(
+            fs.readFileSync(path.join(dir, skill, 'evals', 'triggers.json'), 'utf8'),
+        ) as RawCorpus;
+        if (Array.isArray(raw.queries)) {
+            for (const q of raw.queries) {
+                if (typeof q.q !== 'string' || typeof q.trigger !== 'boolean') continue;
+                const declared = typeof q.class === 'string' ? q.class : null;
+                out.push({
+                    skill,
+                    prompt: q.q,
+                    expect: q.trigger,
+                    caseClass:
+                        declared === 'exemplar' ||
+                        declared === 'near-miss' ||
+                        declared === 'counterexample'
+                            ? declared
+                            : null,
+                    language: typeof q.language === 'string' ? q.language : null,
+                });
+            }
+            continue;
+        }
+        for (const [key, expect] of [
+            ['should_trigger', true],
+            ['should_not_trigger', false],
+        ] as const) {
+            const list = raw[key];
+            if (!Array.isArray(list)) continue;
+            for (const prompt of list) {
+                if (typeof prompt !== 'string') continue;
+                out.push({ skill, prompt, expect, caseClass: null, language: null });
+            }
+        }
+    }
+    return out;
+}
+
+/** Which train corpora use the legacy shape. Reported so the count is explainable. */
+export function legacyShaped(repoRoot: string): string[] {
+    const dir = skillsDir(repoRoot);
+    const out: string[] = [];
+    for (const { skill, partition } of corpusSkills(repoRoot)) {
+        if (partition === 'holdout') continue;
+        const raw = JSON.parse(
+            fs.readFileSync(path.join(dir, skill, 'evals', 'triggers.json'), 'utf8'),
+        ) as RawCorpus;
+        if (!Array.isArray(raw.queries)) out.push(skill);
+    }
+    return out;
+}
+
+/** A catalogue entry: what the ranker sees, plus the body the 5.1 arm adds. */
+export interface CatalogueEntry extends RankableSkill {
+    readonly name: string;
+    readonly description: string;
+    readonly personas: readonly string[];
+    /** SKILL.md with its frontmatter removed. Empty when the file has none. */
+    readonly body: string;
+}
+
+/** Minimal frontmatter split. Returns `[block, body]`; `['', text]` when absent. */
+export function splitFrontmatter(text: string): [string, string] {
+    if (!text.startsWith('---')) return ['', text];
+    const end = text.indexOf('\n---', 3);
+    if (end === -1) return ['', text];
+    return [text.slice(3, end), text.slice(end + 4)];
+}
+
+/** `name`, `description` and `personas` out of a frontmatter block. */
+export function readMeta(block: string): { name: string; description: string; personas: string[] } {
+    let name = '';
+    let description = '';
+    const personas: string[] = [];
+    let inPersonas = false;
+    for (const raw of block.split('\n')) {
+        const line = raw.replace(/\s+$/, '');
+        if (inPersonas && /^ {2}- /.test(line)) {
+            personas.push(line.slice(4).trim().replace(/^["']|["']$/g, ''));
+            continue;
+        }
+        inPersonas = false;
+        const m = /^([a-zA-Z_][\w-]*)[ \t]*:[ \t]*(.*)$/.exec(line);
+        if (!m) continue;
+        const key = m[1] as string;
+        const value = (m[2] as string).trim().replace(/^["']|["']$/g, '');
+        if (key === 'personas' && value === '') inPersonas = true;
+        else if (key === 'name') name = value;
+        else if (key === 'description') description = value;
+    }
+    return { name, description, personas };
+}
+
+/** Every skill directory`s `SKILL.md`, name-sorted. The ranking universe. */
+export function loadCatalogue(repoRoot: string): CatalogueEntry[] {
+    const dir = skillsDir(repoRoot);
+    if (!fs.existsSync(dir)) return [];
+    const out: CatalogueEntry[] = [];
+    for (const skill of fs.readdirSync(dir).sort()) {
+        if (isScaffoldingSkillDir(skill)) continue;
+        const file = path.join(dir, skill, 'SKILL.md');
+        if (!fs.existsSync(file)) continue;
+        const [block, body] = splitFrontmatter(fs.readFileSync(file, 'utf8'));
+        const meta = readMeta(block);
+        out.push({
+            name: meta.name || skill,
+            description: meta.description,
+            personas: meta.personas,
+            body,
+        });
+    }
+    return out;
+}
+
+/** The two 5.1 arms. `description` is today's production condition. */
+export const ARMS = ['description', 'description+body'] as const;
+export type Arm = (typeof ARMS)[number];
+
+/**
+ * The indexed term set per arm.
+ *
+ * The `description` arm reproduces `skillTerms(skill, {})` exactly — same
+ * inputs, same tokenizer — so the control arm IS the shipped behaviour rather
+ * than a re-implementation of it.
+ */
+export function armTerms(entry: CatalogueEntry, arm: Arm): Set<string> {
+    const parts = [entry.name, entry.description];
+    if (arm === 'description+body') parts.push(entry.body);
+    return tokenize(parts.join(' '));
+}
+
+export interface RankedName {
+    readonly name: string;
+    readonly score: number;
+}
+
+/**
+ * Top-k by score, ties broken on name — the total order `rankSkills` already
+ * defines. Zero scores are dropped, because a skill the scorer gives 0 is not
+ * delivered by the shipped ranker either.
+ */
+export function topK(
+    prompt: string,
+    catalogue: readonly CatalogueEntry[],
+    terms: ReadonlyMap<string, Set<string>>,
+    k: number,
+): RankedName[] {
+    const taskTerms = tokenize(prompt);
+    const rows: RankedName[] = [];
+    for (const entry of catalogue) {
+        const t = terms.get(entry.name);
+        if (t === undefined) continue;
+        const score = scoreSkill(taskTerms, entry, t);
+        if (score > 0) rows.push({ name: entry.name, score });
+    }
+    rows.sort((a, b) => b.score - a.score || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    return rows.slice(0, k);
+}
+
+/** Term sets for one arm, keyed by the name `topK` ranks on. */
+export function termIndex(catalogue: readonly CatalogueEntry[], arm: Arm): Map<string, Set<string>> {
+    const index = new Map<string, Set<string>>();
+    for (const entry of catalogue) index.set(entry.name, armTerms(entry, arm));
+    return index;
+}