@event4u/agent-config 14.9.0 → 14.11.0

package/src/scripts/_lib/lean_projection_mode.ts

@@ -0,0 +1,44 @@
+/**
+ * `lean_projection.mode` — ONE definition of what the three modes mean.
+ *
+ * The projector (`condense.ts`) resolves the value with a real YAML parse; the
+ * delivery concern (`hooks/rule_inject_hook.ts`) resolves it with an
+ * indentation-shaped read, because a hook must never fail a tool call because a
+ * parser could not load. Two readers is unavoidable. Two *normalisations* is
+ * not, and would be the defect worth preventing: a projector that writes thin
+ * files while the concern believes the mode is off delivers pointers and no
+ * bodies, which is exactly the 36.2 % arm the delivery mode exists to replace.
+ *
+ * So each side supplies the raw string from its own reader and this module
+ * decides what it means. Anything unrecognised — absent key, typo, `null`,
+ * a non-string — is `eager-all`, today's shipped behaviour: a mode nobody can
+ * spell must never silently thin the standing corpus.
+ */
+
+/** The three projection shapes. `eager-all` is the shipped default. */
+export type LeanProjectionMode = 'eager-all' | 'thin' | 'delivery';
+
+export const DEFAULT_LEAN_PROJECTION_MODE: LeanProjectionMode = 'eager-all';
+
+/** Map a raw settings value onto a mode. Unrecognised → `eager-all`. */
+export function normalizeLeanProjectionMode(raw: unknown): LeanProjectionMode {
+    const v = typeof raw === 'string' ? raw.trim().toLowerCase() : '';
+    if (v === 'thin') return 'thin';
+    if (v === 'delivery') return 'delivery';
+    return DEFAULT_LEAN_PROJECTION_MODE;
+}
+
+/**
+ * True when the projector writes pointer stubs instead of bodies.
+ *
+ * `delivery` is a superset of `thin`: it writes the same thin files AND binds
+ * the concern that delivers the bodies back on a trigger.
+ */
+export function writesThinFiles(mode: LeanProjectionMode): boolean {
+    return mode === 'thin' || mode === 'delivery';
+}
+
+/** True only in the mode where a hook delivers rule bodies at runtime. */
+export function deliversBodies(mode: LeanProjectionMode): boolean {
+    return mode === 'delivery';
+}

package/src/scripts/_lib/mcp_bridge.ts

@@ -0,0 +1,199 @@
+/**
+ * mcp_bridge — `.mcp.json` registration and the skill-tier projection lever.
+ *
+ * Extracted from `install.ts` by Phase 2.2 of `road-to-skill-delivery-over-mcp`,
+ * for a mechanical reason worth stating: `check_source_size_budget` is a ratchet
+ * over every line in a file above 1,500, `install.ts` is 5,466 of them, and the
+ * gate's own message says a new violation is fixed and never baselined away. So
+ * the feature lives here and `install.ts` keeps one-line call sites.
+ *
+ * Everything here is a pure function of its arguments or of the file system.
+ * `ensureMcpBridge` is the one exception and takes its writer by injection —
+ * `merge_json_file` lives in `install.ts` (eight other bridges use it) and
+ * importing it back would make the cycle.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/** `install.ts`'s deploy tuple: [written, skipped, status, paths]. */
+export type DeployTuple = [number, number, string, string[]];
+
+/** The `merge_json_file` signature this module is handed. */
+export type MergeJsonFile = (
+    p: string,
+    new_data: Record<string, unknown>,
+    force: boolean,
+    label: string,
+) => Record<string, unknown>[];
+
+/**
+ * The project-scope MCP server entry Claude Code reads from `.mcp.json`.
+ *
+ * Shape is fixed by `docs/getting-started-local-stdio.md` — the documented
+ * end-user path — so a consumer who followed the docs and a consumer who ran the
+ * installer end up with the same entry rather than two that drift.
+ */
+export const MCP_SERVER_KEY = 'agent-config';
+export const MCP_BRIDGE_ENTRY = {
+    mcpServers: {
+        [MCP_SERVER_KEY]: {
+            command: 'npx',
+            args: ['-y', '@event4u/agent-config', 'mcp-server'],
+        },
+    },
+};
+
+/**
+ * `.mcp.json` — the project-scope MCP config Claude Code reads.
+ *
+ * WHY THE INSTALLER OWNS THIS FILE AND `mcp_render` DOES NOT. `mcp_render`
+ * projects the consumer's OWN root `mcp.json` onto per-tool configs by
+ * overwriting them (`write_target`), which is correct for a file the renderer
+ * generates in full and wrong for one the consumer also edits: a render would
+ * delete both this entry and any server they added by hand. `merge_json_file`
+ * writes only our key, records it as an RFC-6901 pointer in
+ * `agents/installed-tools.lock`, and lets uninstall subtract exactly that key.
+ * `mcp:check` validates the file without ever writing it.
+ *
+ * Default ON for `claude-code`, because `rules/missing-skill-recovery.md` makes
+ * `suggest_skill_for_task` an Iron Law for every consumer and a rule that is
+ * unfulfillable by default is a defect, not a feature. Opting out is the same
+ * lever as every other bridge — deselect the tool (`--tools`), which is the gate
+ * the caller applies; `.agent-tools.yml` is deliberately NOT that lever, it is a
+ * maintainer-side projection-generator allowlist the installer cannot see and
+ * whose tool ids differ from `_VALID_TOOLS`.
+ */
+export function makeEnsureMcpBridge(
+    mergeJsonFile: MergeJsonFile,
+): (projectRoot: string, force: boolean) => Record<string, unknown>[] {
+    return (projectRoot, force) =>
+        mergeJsonFile(path.join(projectRoot, '.mcp.json'), MCP_BRIDGE_ENTRY, force, '.mcp.json');
+}
+
+/**
+ * The three projection modes.
+ *
+ * `legacy-all` ships everything and stays the default. `scoped` narrows to the
+ * active packs. `tiered` narrows to the skills predicted to reach the model WITH
+ * their description, on the theory that a skill the host lists bare is better
+ * served by the MCP recovery tool than by a catalogue entry nobody can read.
+ *
+ * `tiered` is OPT-IN and stays opt-in until the roadmap's Phase 4.4 decides on
+ * evidence — which it did, at `measured-null`. The reason is stated rather than
+ * implied: the split usually comes from an ALPHABETICAL fallback order
+ * (`agents/runtime/metrics/skill-usage.jsonl` is absent on most machines), and
+ * the one real host observation this repo has disagrees with that fallback on
+ * four of eight sampled entries. Defaulting to `tiered` would hide skills on a
+ * prediction the tree itself can show to be wrong — strictly worse than the
+ * bare-but-listed defect it fixes (roadmap risk 4).
+ */
+export type ProjectionMode = 'scoped' | 'legacy-all' | 'tiered';
+
+/** Resolve a raw `projection.mode` value. Anything unrecognised is `legacy-all`. */
+export function projectionModeOf(raw: unknown): ProjectionMode {
+    return raw === 'scoped' ? 'scoped' : raw === 'tiered' ? 'tiered' : 'legacy-all';
+}
+
+/**
+ * Tier B skill names, or `null` when no split exists on this machine.
+ *
+ * `null` is load-bearing: it means "nobody computed a split here", and a
+ * `tiered` install that finds it must ship the FULL surface rather than prune on
+ * an empty set — pruning on absence would delete the entire catalogue. A
+ * malformed file is `null` for the same reason.
+ */
+export function resolveTierB(packageRoot: string): ReadonlySet<string> | null {
+    const p = path.join(packageRoot, 'agents', 'runtime', 'state', 'skill-tiers.json');
+    if (!fs.existsSync(p)) return null;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(p, 'utf-8')) as { tier_b?: unknown };
+        if (!Array.isArray(parsed.tier_b)) return null;
+        return new Set(parsed.tier_b.filter((n): n is string => typeof n === 'string'));
+    } catch {
+        return null;
+    }
+}
+
+/** Predicate for `_prune_modules_by`: is this SKILL.md a Tier B skill? */
+export function tierBPrunePredicate(
+    tierB: ReadonlySet<string>,
+): (mdPath: string) => boolean {
+    return (mdPath) => tierB.has(path.basename(path.dirname(mdPath)));
+}
+
+/**
+ * The consumer-side alternative to tiering, surfaced as a recommendation only.
+ *
+ * Claude Code's listing budget is settable: `skillListingBudgetFraction` raises
+ * the fraction of the context window spent on skill DESCRIPTIONS, restoring them
+ * at a measured token price instead of withholding skills from the catalogue.
+ * That is the other lever, and for many consumers the better one — a description
+ * they can read beats a tool call they have to make.
+ *
+ * Returns `null` unless a tier split exists AND Tier B is non-empty: with no
+ * split there is nothing to recommend against, and an empty Tier B means the
+ * host already describes everything. This NEVER writes the consumer's
+ * `settings.json` — the setting is theirs, the token cost is theirs, and an
+ * installer that edited a host's own config to buy itself context would be
+ * taking that decision in their name.
+ */
+export function tierBAdvisory(packageRoot: string): string | null {
+    const tierB = resolveTierB(packageRoot);
+    if (tierB === null || tierB.size === 0) return null;
+    return (
+        `ℹ️  ${tierB.size} skill(s) are predicted to reach the model WITHOUT their ` +
+        'description on a default 200k window.\n' +
+        '   Two levers, neither applied for you:\n' +
+        '   • raise `skillListingBudgetFraction` in your Claude Code settings — ' +
+        'restores descriptions at a token cost (100% delivery of this catalogue ' +
+        'measures ~13,003 tok)\n' +
+        '   • or set `projection.mode: tiered` to withhold them from the catalogue ' +
+        'and reach them via the MCP server instead (opt-in, still unproven — see ' +
+        'docs/mcp-server.md)'
+    );
+}
+
+export interface TieredPruneOutcome {
+    deployResults: Record<string, DeployTuple>;
+    /** One line for the caller to print, or `null` when QUIET. */
+    message: string | null;
+    /** `warn` when no split exists, `info` when a prune happened. */
+    level: 'warn' | 'info';
+}
+
+/**
+ * Apply the Tier-B prune to a completed deploy.
+ *
+ * Takes `pruneBy` rather than importing it, so the prune mechanics stay in one
+ * place and this module does not become a second implementation of them.
+ */
+export function applyTieredPrune(
+    deployResults: Record<string, DeployTuple>,
+    packageRoot: string,
+    pruneBy: (
+        dr: Record<string, DeployTuple>,
+        isPruned: (mdPath: string) => boolean,
+    ) => [number, Record<string, DeployTuple>],
+): TieredPruneOutcome {
+    const tierB = resolveTierB(packageRoot);
+    if (tierB === null || tierB.size === 0) {
+        return {
+            deployResults,
+            level: 'warn',
+            message:
+                'projection.mode: tiered but no skill-tier split exists ' +
+                '(agents/runtime/state/skill-tiers.json) — shipping the full surface. ' +
+                'Compute one with `./scripts-run src/scripts/compute_skill_tiers` first.',
+        };
+    }
+    const [pruned, adjusted] = pruneBy(deployResults, tierBPrunePredicate(tierB));
+    return {
+        deployResults: adjusted,
+        level: 'info',
+        message:
+            `🧹 Tiered install: pruned ${pruned} Tier-B skill artefact(s) — still ` +
+            "reachable via the MCP server's suggest_skill_for_task / read_skill. " +
+            'Set projection.mode: legacy-all to restore the full surface.',
+    };
+}

package/src/scripts/_lib/review_independence.ts

@@ -27,6 +27,26 @@ const PROVIDER_FAMILY: Readonly<Record<string, string>> = {
 export type ReviewIndependence = 'cross-family' | 'same-family' | 'single-member' | 'unknown';
 export type AcceptanceStatus = 'accepted' | 'provisional';
 
+/**
+ * How the reviewer relates to the AUTHOR — a second axis, added 2026-08-23 by
+ * `road-to-review-independence` step 2.1.
+ *
+ * Model family and author relation are different questions, and the type carried only
+ * the first. **A cross-family pair that both read the implementer's envelope is not
+ * independent in the sense that matters here**: they disagree about the model, and they
+ * share the framing of what the change is for and what counts as done.
+ *
+ * - `fresh` — no implementation context. A separate dispatch that received the diff and
+ *   the scope, and not the author's envelope.
+ * - `same-session` — ran inside the author's session, with the implementation context in
+ *   scope. The common path today, and the one this axis exists to make visible.
+ * - `unknown` — not recorded. Treated as `same-session` for derivation, because an
+ *   unrecorded relation is not evidence of freshness and the safe direction on an
+ *   integrity field is the weaker claim (the same reasoning `unknown` already gets on
+ *   the family axis).
+ */
+export type ContextRelation = 'fresh' | 'same-session' | 'unknown';
+
 /**
  * How much INDEPENDENT evidence backs the verdict — deliberately orthogonal to
  * how much effort the reviewer spent.
@@ -54,30 +74,56 @@ export function reviewIndependence(memberNames: readonly string[]): ReviewIndepe
  * is not evidence of independence, and the safe direction on an integrity field
  * is the weaker claim.
  */
-export function acceptanceStatus(independence: ReviewIndependence): AcceptanceStatus {
-    return independence === 'cross-family' ? 'accepted' : 'provisional';
+export function acceptanceStatus(
+    independence: ReviewIndependence,
+    relation: ContextRelation = 'unknown',
+): AcceptanceStatus {
+    if (independence !== 'cross-family') return 'provisional';
+    // BOTH axes, and this is the whole point of step 2.1: a cross-family pair that both
+    // sat in the author's session shares the framing even though it disagrees about the
+    // model. `unknown` falls here too — an unrecorded relation is not evidence of
+    // freshness. The parameter defaults to `unknown` so every existing caller keeps
+    // compiling and gets the SAFER answer rather than the old one.
+    return relation === 'fresh' ? 'accepted' : 'provisional';
 }
 
-export function assuranceFor(independence: ReviewIndependence): Assurance {
-    if (independence === 'cross-family') return 'independent';
+export function assuranceFor(
+    independence: ReviewIndependence,
+    relation: ContextRelation = 'unknown',
+): Assurance {
     if (independence === 'unknown') return 'unreviewed';
+    // `independent` requires both axes, for the same reason `accepted` does.
+    if (independence === 'cross-family' && relation === 'fresh') return 'independent';
     return 'single-pass';
 }
 
 export interface IndependenceFields {
     readonly review_independence: ReviewIndependence;
+    /** The recorded second axis. Derived fields below follow from BOTH. */
+    readonly context_relation: ContextRelation;
     readonly acceptance_status: AcceptanceStatus;
     readonly assurance: Assurance;
     readonly reviewers: readonly string[];
 }
 
-/** The three fields plus the member set they were derived from. */
-export function independenceFields(memberNames: readonly string[]): IndependenceFields {
+/**
+ * The recorded axes plus the fields derived from them.
+ *
+ * `context_relation` defaults to `unknown` so an existing caller that names only its
+ * members keeps compiling — and gets `provisional` rather than the `accepted` it used to
+ * get. That direction is deliberate: a producer that has not said whether its reviewer
+ * was fresh has not earned the stronger claim.
+ */
+export function independenceFields(
+    memberNames: readonly string[],
+    relation: ContextRelation = 'unknown',
+): IndependenceFields {
     const independence = reviewIndependence(memberNames);
     return {
         review_independence: independence,
-        acceptance_status: acceptanceStatus(independence),
-        assurance: assuranceFor(independence),
+        context_relation: relation,
+        acceptance_status: acceptanceStatus(independence, relation),
+        assurance: assuranceFor(independence, relation),
         reviewers: [...memberNames],
     };
 }
@@ -97,13 +143,19 @@ export function independenceViolations(doc: Record<string, unknown>): string[] {
         out.push('review_independence is absent — an artifact that does not declare its independence reads as acceptance by default');
         return out;
     }
-    const expectedAccept = acceptanceStatus(indep as ReviewIndependence);
+    // The recorded relation, not a default: `independenceViolations` judges an artifact
+    // that already carries the fields, so reading `unknown` when the artifact says
+    // `fresh` would flag a correct producer.
+    const relRaw = doc['context_relation'];
+    const rel: ContextRelation =
+        relRaw === 'fresh' || relRaw === 'same-session' ? relRaw : 'unknown';
+    const expectedAccept = acceptanceStatus(indep as ReviewIndependence, rel);
     if (accept !== expectedAccept) {
         out.push(
             `acceptance_status is ${String(accept)} but review_independence ${String(indep)} derives ${expectedAccept}`,
         );
     }
-    const expectedAssur = assuranceFor(indep as ReviewIndependence);
+    const expectedAssur = assuranceFor(indep as ReviewIndependence, rel);
     if (assur !== undefined && assur !== expectedAssur) {
         out.push(`assurance is ${String(assur)} but review_independence ${String(indep)} derives ${expectedAssur}`);
     }

package/src/scripts/_lib/rule_injection.ts

@@ -0,0 +1,239 @@
+/**
+ * Rule-injection core — THE single module both the offline model and the
+ * runtime concern read.
+ *
+ * WHY ONE MODULE. `road-to-trigger-delivered-rule-bodies` step 0.5 states the
+ * failure this prevents in as many words: *an experiment whose offline pricing
+ * and runtime delivery use different matchers measures nothing*. So the price /
+ * recall model (`src/scripts/model_rule_injection.ts`) and the delivery concern
+ * (`src/scripts/hooks/rule_inject_hook.ts`) both import THIS file, and neither
+ * re-implements selection, ordering, capping, or body loading.
+ *
+ * IT OWNS NO MATCHER. Trigger semantics belong to
+ * [`_lib/router_match.ts`](router_match.ts), which is already the single
+ * implementation for every surface that answers "which rules fire on this
+ * prompt?" and is pinned by `tests/scripts/router_match_parity.test.ts`. A
+ * second matcher here would be the violation that test exists to catch, so
+ * `matchTierRules` is a thin, deterministic wrapper over `match_prompt` and
+ * nothing more. Step 0.3's pre-registered comparison found no reason to write
+ * one — see `model_rule_injection.ts`'s header for the measured verdict.
+ *
+ * KERNEL IS NEVER INJECTED. The nine kernel rules are in standing context by
+ * definition; injecting one would be paying twice for a body that is already
+ * there. `match_prompt` returns kernel ids in `activated_rules` because kernel
+ * rules are always active — this module filters them out by construction rather
+ * than relying on a caller to remember.
+ *
+ * IT IMPORTS NO TOKENIZER, AND THAT IS A HOT-PATH FACT RATHER THAN A STYLE
+ * CHOICE. `_lib/token_count.ts` resolves `js-tiktoken` AT MODULE LOAD, and the
+ * concern that imports this file is statically reachable from
+ * `concern_registry.ts` — so importing it here made every hook dispatch on
+ * every slot pay a tokenizer load for a concern that is default-OFF and emits
+ * nothing. Measured on this tree: unbinding the concern moved the
+ * `pre_tool_use` p95 from 202 ms to 196 ms, and the CI latency gate went red on
+ * the branch that introduced it while passing on main.
+ *
+ * So the runtime cap is in BYTES. That is not a weaker bound — it is the same
+ * bound in the unit the budget actually enforces: `hook-token-budget.json`
+ * measures "bytes of concern stdout payload fields", so the cap and its
+ * registered row are now the same number instead of two units that need a
+ * conversion factor to compare. The offline model keeps exact-BPE tokens for
+ * its price table, where the tokenizer is the point and nothing is on a hot
+ * path.
+ *
+ * DETERMINISM IS THE CONTRACT, and the collision cases are the reason it needs
+ * stating. Two triggers on the SAME rule collapse to one entry (a rule is
+ * delivered once, however many of its triggers fired) while the trigger count
+ * survives as `score`. Two DIFFERENT rules both firing are returned in router
+ * declaration order, tier_1 before tier_2 — never in match order, which would
+ * make the output depend on trigger authoring order inside a rule. Capping
+ * sorts by descending score with router order as the tie-break, so the same
+ * prompt against the same router always yields the same bytes.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { match_prompt, type Router, type Trigger } from './router_match.js';
+
+export type { Router, Trigger };
+
+/** Tier a matched rule came from. Kernel is never a value here. */
+export type Tier = 'tier_1' | 'tier_2';
+
+export interface TierRuleMatch {
+    id: string;
+    tier: Tier;
+    /** How many of this rule's triggers matched. Ties break on router order. */
+    score: number;
+    /** Router declaration index within its tier — the deterministic tie-break. */
+    order: number;
+}
+
+/** Kinds of trigger a prompt alone can never fire. */
+export const PATH_TRIGGER_KINDS = ['path_prefix', 'file_pattern'] as const;
+
+export function loadRouter(repoRoot: string): Router {
+    const p = path.join(repoRoot, 'dist', 'router.json');
+    return JSON.parse(fs.readFileSync(p, 'utf8')) as Router;
+}
+
+/** Kernel rule ids, as declared by the router. */
+export function kernelIds(router: Router): Set<string> {
+    const k = Array.isArray(router['kernel']) ? router['kernel'] : [];
+    return new Set(k.map((x) => String(x)));
+}
+
+function tierEntries(router: Router, tier: Tier): Array<{ id: string; triggers: Trigger[] }> {
+    const raw = router[tier];
+    if (!Array.isArray(raw)) return [];
+    return (raw as unknown as Array<Record<string, unknown>>).map((r) => ({
+        id: String(r['id'] ?? ''),
+        triggers: Array.isArray(r['triggers']) ? (r['triggers'] as Trigger[]) : [],
+    }));
+}
+
+/** Every tier rule declared by the router, with its trigger list. */
+export function allTierRules(router: Router): Array<{ id: string; tier: Tier; triggers: Trigger[] }> {
+    const out: Array<{ id: string; tier: Tier; triggers: Trigger[] }> = [];
+    for (const tier of ['tier_1', 'tier_2'] as Tier[]) {
+        for (const e of tierEntries(router, tier)) out.push({ ...e, tier });
+    }
+    return out;
+}
+
+/** Rules whose triggers are ALL path-shaped — unreachable from a prompt alone. */
+export function pathOnlyRuleIds(router: Router): Set<string> {
+    const ids = new Set<string>();
+    for (const r of allTierRules(router)) {
+        if (r.triggers.length === 0) continue;
+        const allPath = r.triggers.every((t) =>
+            PATH_TRIGGER_KINDS.some((k) => k in t),
+        );
+        if (allPath) ids.add(r.id);
+    }
+    return ids;
+}
+
+/** Rules declaring at least one path-shaped trigger. */
+export function pathCapableRuleIds(router: Router): Set<string> {
+    const ids = new Set<string>();
+    for (const r of allTierRules(router)) {
+        if (r.triggers.some((t) => PATH_TRIGGER_KINDS.some((k) => k in t))) ids.add(r.id);
+    }
+    return ids;
+}
+
+/** Rules declaring no trigger at all — cannot be delivered, must stay eager. */
+export function triggerlessRuleIds(router: Router): string[] {
+    return allTierRules(router)
+        .filter((r) => r.triggers.length === 0)
+        .map((r) => r.id);
+}
+
+/**
+ * Which tier rules fire on this prompt (+ optional open files / command).
+ *
+ * Kernel is excluded. Order is router declaration order, tier_1 first.
+ */
+export function matchTierRules(
+    router: Router,
+    prompt: string,
+    openFiles?: Iterable<string> | null,
+    command?: string | null,
+): TierRuleMatch[] {
+    const kernel = kernelIds(router);
+    const res = match_prompt(router, prompt, 'full', openFiles, command);
+    const scores = new Map<string, number>();
+    for (const mt of res.matched_triggers) {
+        const id = String(mt.rule ?? '');
+        if (id === '' || kernel.has(id)) continue;
+        scores.set(id, (scores.get(id) ?? 0) + 1);
+    }
+    const out: TierRuleMatch[] = [];
+    let order = 0;
+    for (const r of allTierRules(router)) {
+        const s = scores.get(r.id);
+        if (s === undefined) {
+            order += 1;
+            continue;
+        }
+        out.push({ id: r.id, tier: r.tier, score: s, order });
+        order += 1;
+    }
+    return out;
+}
+
+/** Where the projected body of a rule lives. */
+export function ruleBodyPath(repoRoot: string, id: string): string {
+    return path.join(repoRoot, 'dist', 'agent-src', 'rules', `${id}.md`);
+}
+
+/** The projected body, or `null` when the rule has no projected file. */
+export function loadRuleBody(repoRoot: string, id: string): string | null {
+    const p = ruleBodyPath(repoRoot, id);
+    if (!fs.existsSync(p)) return null;
+    return fs.readFileSync(p, 'utf8');
+}
+
+/**
+ * UTF-8 byte length — the runtime measure, dependency-free by design.
+ *
+ * Deliberately NOT a token count: see the header. Bytes are exact, need no
+ * tokenizer, and are the unit `hook-token-budget.json` enforces.
+ */
+export function bytesOf(text: string): number {
+    return Buffer.byteLength(text, 'utf8');
+}
+
+export interface SelectionResult {
+    selected: TierRuleMatch[];
+    /** Matched but dropped because the byte cap was reached. */
+    dropped: TierRuleMatch[];
+    /** Byte sum of the selected bodies. */
+    bytes: number;
+    /** Per-rule body byte counts, keyed by id, for every MATCHED rule. */
+    bodyBytes: Map<string, number>;
+}
+
+/**
+ * Apply the per-prompt BYTE cap.
+ *
+ * Highest score first, router order as tie-break; a rule whose body would push
+ * the running total past `capBytes` is dropped and the walk continues, so one
+ * oversized body cannot starve the rest. The returned `selected` list is
+ * re-sorted back into router order — cap order is a budgeting concern, delivery
+ * order is not.
+ *
+ * ONE selection for both callers. The offline model and the runtime concern
+ * call THIS function with THE SAME cap, so the set the price table prices is
+ * byte-for-byte the set the concern delivers. That is step 0.5's requirement,
+ * and expressing the cap in bytes makes it hold without a token/byte
+ * conversion sitting between the two arms.
+ */
+export function selectForInjection(
+    repoRoot: string,
+    matches: TierRuleMatch[],
+    capBytes: number,
+): SelectionResult {
+    const bodyBytes = new Map<string, number>();
+    for (const m of matches) {
+        const body = loadRuleBody(repoRoot, m.id);
+        bodyBytes.set(m.id, body === null ? 0 : bytesOf(body));
+    }
+    const ranked = [...matches].sort((a, b) => b.score - a.score || a.order - b.order);
+    const selected: TierRuleMatch[] = [];
+    const dropped: TierRuleMatch[] = [];
+    let total = 0;
+    for (const m of ranked) {
+        const t = bodyBytes.get(m.id) ?? 0;
+        if (total + t > capBytes && selected.length > 0) {
+            dropped.push(m);
+            continue;
+        }
+        selected.push(m);
+        total += t;
+    }
+    selected.sort((a, b) => a.order - b.order);
+    dropped.sort((a, b) => a.order - b.order);
+    return { selected, dropped, bytes: total, bodyBytes };
+}