@event4u/agent-config 16.1.0 → 16.3.0

package/src/scripts/_lib/release_migration_gate.ts

@@ -24,6 +24,7 @@ import * as path from 'node:path';
 import { REPO_ROOT } from '../release_env.js';
 import { die, run, type RunResult } from '../release_publication.js';
 import {
+    BREAKING_INDEX_PATH,
     MIGRATION_PATH as MAJOR_MIGRATION_PATH,
     pendingMajorFinding,
 } from '../lint_major_migration_sections.js';
@@ -148,8 +149,15 @@ export function assert_scheduled_deprecations_clear(
  * real run will refuse and returns, because `--dry-run exits 0` is a contract
  * this file's own tests assert.
  *
+ * A major owes TWO records and this seam reads both: the migration section and
+ * the by-major row in `BREAKING_CHANGES.md`. Checking only the first at cut
+ * time while the lint checks both would let a cut create the exact state the
+ * lint then reds `main` over — the gate arriving one merge too late, which is
+ * the shape `pendingMajorFinding` exists to avoid in the first place.
+ *
  * @param migrationReader Seam for the file read, so a test can drive the
  * refusal without mutating a tracked file.
+ * @param indexReader The same seam for the breaking-changes index.
  */
 export function assert_major_migration_section(
     target: string,
@@ -157,18 +165,23 @@ export function assert_major_migration_section(
     opts: { previewOnly?: boolean } = {},
     migrationReader: () => string = () =>
         fs.readFileSync(path.join(REPO_ROOT, MAJOR_MIGRATION_PATH), 'utf-8'),
+    indexReader: () => string = () =>
+        fs.readFileSync(path.join(REPO_ROOT, BREAKING_INDEX_PATH), 'utf-8'),
 ): void {
     let migration: string;
+    let index: string;
     try {
         migration = migrationReader();
+        index = indexReader();
     } catch (exc) {
         die(
-            `refusing the ${target} cut: cannot read ${MAJOR_MIGRATION_PATH} ` +
+            `refusing the ${target} cut: cannot read ${MAJOR_MIGRATION_PATH} or ` +
+                `${BREAKING_INDEX_PATH} ` +
                 `(${exc instanceof Error ? exc.message : String(exc)}). That is an environment ` +
                 'failure, not a finding — fix the checkout, then re-run.',
         );
     }
-    const finding = pendingMajorFinding(target, changelog_entry, migration);
+    const finding = pendingMajorFinding(target, changelog_entry, migration, index);
     if (finding === null) {
         return;
     }
@@ -180,5 +193,8 @@ export function assert_major_migration_section(
         );
         return;
     }
-    die(`refusing the ${target} cut: ${MAJOR_MIGRATION_PATH} has no section for ${target}.`);
+    die(
+        `refusing the ${target} cut: ${MAJOR_MIGRATION_PATH} or ${BREAKING_INDEX_PATH} ` +
+            `does not name ${target}.`,
+    );
 }

package/src/scripts/_lib/reserved_name_sweep.ts

@@ -0,0 +1,73 @@
+/**
+ * The reserved-name sweep over flat Claude Code command files.
+ *
+ * A flat command whose slug shadows a Claude Code built-in never ships on the
+ * claude-code anchor — the suite complements the host, it does not overlay its
+ * built-ins. The sweep that enforces this used to delete EVERY builtin-named
+ * `.md` in the anchor's `commands/` directory, including one another agent
+ * package or the consumer had put there. The consumer's own `/review` command
+ * disappeared at install time with no message, because the sweep's only
+ * question was the filename.
+ *
+ * The question it asks now is ownership: a file is removed when this package
+ * wrote it — the current deploy's own written set, or a path a previous
+ * install recorded in the installed-tools manifest. Anything else is FOREIGN:
+ * it stays on disk and is reported, so the consumer learns that a built-in
+ * name is shadowed by someone and can decide, rather than finding their file
+ * gone.
+ *
+ * Both halves of the sweep's original purpose survive: ours never ships under
+ * a reserved name, and the suite still never overlays a built-in with its own
+ * file. What it no longer does is enforce that on a file that is not its own.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+export interface ReservedSweepResult {
+    /** Slugs of OUR files removed because the name is a host built-in. */
+    reserved: string[];
+    /** Slugs left in place because nothing proves this package wrote them. */
+    foreign: string[];
+}
+
+/**
+ * Remove our builtin-named flat commands from `commandsDir`; keep foreign ones.
+ *
+ * Both ownership sets are anchor-relative, exactly as the deploy inventory
+ * records them. `currentFiles` is this deploy's written set — the live half,
+ * and the only one that exists on a first install. `recordedFiles` is what a
+ * previous deploy recorded under the same anchor, so a builtin-named file of
+ * ours left behind by an older version is still reaped rather than becoming
+ * permanently unprovable. A removed entry is dropped from `currentFiles` so
+ * the inventory record stays consistent with the tree, exactly as before.
+ */
+export function sweepReservedNames(
+    commandsDir: string,
+    currentFiles: Set<string>,
+    isBuiltinName: (slug: string) => boolean,
+    recordedFiles: ReadonlySet<string>,
+): ReservedSweepResult {
+    const reserved: string[] = [];
+    const foreign: string[] = [];
+    let entries: string[] = [];
+    try {
+        entries = fs.readdirSync(commandsDir).filter((f) => f.endsWith('.md'));
+    } catch {
+        return { reserved, foreign };
+    }
+    for (const fname of entries.sort()) {
+        const slug = fname.slice(0, -'.md'.length);
+        if (!isBuiltinName(slug)) continue;
+        const rel = `commands/${fname}`;
+        const ours = currentFiles.has(rel) || recordedFiles.has(rel);
+        if (!ours) {
+            foreign.push(slug);
+            continue;
+        }
+        fs.rmSync(path.join(commandsDir, fname), { force: true });
+        currentFiles.delete(rel);
+        reserved.push(slug);
+    }
+    return { reserved, foreign };
+}

package/src/scripts/_lib/retrieval_sanitize.ts

@@ -16,26 +16,58 @@
  * Codepoint classes are shared with `lint_hidden_unicode` (one source of truth
  * for what counts as a hidden-instruction vector).
  *
- * WHERE IT ACTUALLY RUNS — measured end-to-end, not asserted. Keep this list
- * honest: an earlier version of this header named surfaces by intent, and the
- * legacy-envelope gap below went unnoticed for exactly that reason. Every
- * claim here is backed by a probe row in
- * `agents/evidence/reports/sanitize-floor-wiring.md`:
+ * WHERE IT ACTUALLY RUNS — read the table, which is GENERATED:
  *
- *   - `retrieve_v1()`     — yes (`memory_lookup.ts` calls `sanitize_entry`)
- *   - `memory_get_v1()`   — yes (same)
- *   - MCP `memory_lookup` / `memory_get` tools — inherited from the two above
- *   - `retrieve()` / `retrieve_with_meta()` — yes, since the S0.0 wiring fix;
- *     before it they emitted every vector intact, and so did the CLI default
- *     (`--envelope legacy`), which is the path the rules document
- *   - inter-agent channels (`ai_team` / `ai_council` model replies) — the
- *     inbound parse choke point only; the subagent boundary itself is a HOST
- *     primitive this package cannot reach (see the report, § S0.0b)
+ *     docs/contracts/retrieval-read-surfaces.md
  *
- * Anything not on that list is uncovered. Do not widen the list without a
- * probe row to back it.
+ * This header used to carry that list inline, and the list was wrong in BOTH
+ * directions: a path that reaches the outside world and IS sanitized was
+ * absent from it, and two paths carrying fetched bytes toward a model-facing
+ * surface were neither listed nor covered. An earlier version had already
+ * failed the same way — it named surfaces by intent, and the legacy-envelope
+ * gap went unnoticed for exactly that reason. Twice is a property of the
+ * mechanism, not of the entries, which is why the list is now derived from the
+ * import graph by `check_read_surface_coverage` and this header points at it
+ * instead of copying it. A divergence between the two FAILS that gate; two
+ * copies is how it went stale.
+ *
+ * Anything absent from the table is uncovered, and a module the generator
+ * cannot classify appears there as an `unclassified` ROW rather than being
+ * omitted — a missing row would read as no surface at all.
+ *
+ * One boundary the table cannot move: the subagent boundary itself is a HOST
+ * primitive this package cannot reach, so the inter-agent channels are covered
+ * at the inbound parse choke point and nowhere else.
+ *
+ * loss_class: ephemeral-lossy
+ *
+ * `sanitize_text` drops hidden-instruction codepoints, control-char noise and
+ * invisible fillers, and caps the result at MAX_FIELD_CHARS. None of that is
+ * reconstructible from the output, and for the dropped vectors the
+ * unrecoverability IS the guarantee — a retrieval path that could hand back
+ * the vector it stripped would not be a floor. So the class is
+ * `ephemeral-lossy` for the module, even though `sanitize_markup` below
+ * returns structured removals for the layer it composes: a class names what a
+ * caller can recover from the output, and `sanitize_text` returns a string.
+ *
+ * THE STRUCTURAL LAYER IS A SEPARATE MODULE. Everything below is a CODEPOINT
+ * floor. Fetched markup also hides content STRUCTURALLY — an HTML comment, a
+ * `<template>` block, a `style="display:none"` span — which no codepoint
+ * predicate can see. That class is covered by `_lib/structural_hiding.ts`,
+ * composed with this floor by `sanitize_markup` below, and it is covered for
+ * fetched MARKUP only: a caller holding plain text needs nothing from it.
+ *
+ * WHAT THAT LAYER STILL DOES NOT SEE is a register in its own file —
+ * `STRUCTURAL_HIDING_GAPS` — and every surface claiming the coverage cites the
+ * register alongside the claim, because a detector cited without its gaps is
+ * how the claim becomes a false green. No recall or coverage percentage is
+ * published for it anywhere; a rate needs a frozen corpus and none exists.
+ * `aria-hidden` is deliberately NOT one of its channels
+ * (`STRUCTURAL_HIDING_NON_CHANNELS` says why).
  */
 import { _classify } from '../lint_hidden_unicode.js';
+import { strip_structural_hiding } from './structural_hiding.js';
+import type { StructuralRemoval } from './structural_hiding.js';
 import { TOKEN_RE, classifyToken } from './confusables.js';
 
 /** Hard per-field length cap — bounds a runaway/adversarial body. */
@@ -85,6 +117,35 @@ export function sanitize_text(s: string): string {
     return out.length > MAX_FIELD_CHARS ? out.slice(0, MAX_FIELD_CHARS) : out;
 }
 
+/**
+ * The fetched-markup floor: structural pre-pass, then the codepoint floor.
+ *
+ * ORDER IS LOAD-BEARING. The structural pass runs FIRST, because a codepoint
+ * floor applied first would sanitize text that is about to be discarded and,
+ * worse, would leave a hidden subtree looking clean. Running it second means
+ * every byte that survives the structural pass still clears the codepoint
+ * floor — including the text that was only reachable once markup was removed.
+ *
+ * Use this for fetched MARKUP. For plain text `sanitize_text` is the whole
+ * floor and this adds nothing but a parse.
+ *
+ * The removals are RETURNED, not logged and not swallowed: a caller debugging
+ * a corrupted result needs to know what went and where it was. See the removal
+ * policy in `structural_hiding.ts`.
+ */
+export function sanitize_markup(markup: string): {
+    text: string;
+    removals: readonly StructuralRemoval[];
+    truncated: boolean;
+} {
+    const stripped = strip_structural_hiding(markup);
+    return {
+        text: sanitize_text(stripped.text),
+        removals: stripped.removals,
+        truncated: stripped.truncated,
+    };
+}
+
 /**
  * Report the INVISIBLE layer without removing it.
  *

package/src/scripts/_lib/review_coverage.ts

@@ -0,0 +1,134 @@
+/**
+ * How much of a release the self-review actually read, stated where the record
+ * is read.
+ *
+ * `self_review_gate` writes a `coverage` block — `{chunks, filesReviewed,
+ * filesTotal, unreviewed[]}` — into the findings artifact, `--ingest` carries it
+ * into the per-release ledger named by {@link LEDGER_DIR}, and from there NOBODY
+ * reads `filesReviewed` back. The 16.2.0 ledger records `filesReviewed: 65,
+ * filesTotal: 678`: the review saw under a tenth of the change. Every consumer
+ * of that record — the disposition gate's success line, the release-highlights
+ * gate, a human opening the file — saw output that said nothing about it.
+ *
+ * A finding count over 9.6 % of a diff and the same count over all of it are
+ * different claims, and the record spelled them identically.
+ *
+ * A LABEL, NEVER A FLOOR, and the distinction is the decision.
+ *
+ * Nothing here refuses. `coverageLabel` returns a string or `null`; no caller
+ * turns it into an exit code, and none may. Raising what a review reads costs
+ * one more paid model request per chunk per cut, which is a spend decision
+ * belonging to the owner. A gate that failed a cut on partial coverage would
+ * force that decision through the back door — the operator would either pay or
+ * be unable to release — which is exactly the move the roadmap's decision D1
+ * records as rejected.
+ *
+ * The honest cost of that choice, stated rather than left to be discovered: a
+ * release can ship with 9.6 % coverage and this module will only have said so.
+ * Saying so is the whole claim.
+ *
+ * It lives in its own module because two consumers read it — `check_finding_dispositions` on the ledger and
+ * `check_release_highlights` beside the Known-limitations field — and a label
+ * the two spell differently is a label a reader cannot compare across the two
+ * places they meet it. One definition is also the seam the unit tests use, so
+ * the arithmetic is checked without either CLI in the loop.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/** Where the per-release ledgers live, relative to the repository root. */
+export const LEDGER_DIR = path.join('agents', 'evidence', 'release-findings');
+
+/**
+ * The coverage block as the gate writes it. Every field optional: this type
+ * describes an artifact read back off disk, which may be from an older writer
+ * or hand-edited, so the reader's job is to decide whether it can answer rather
+ * than to assume it can.
+ */
+export interface ReviewCoverage {
+    readonly chunks?: unknown;
+    readonly filesReviewed?: unknown;
+    readonly filesTotal?: unknown;
+    readonly unreviewed?: unknown;
+}
+
+function _finite(v: unknown): number | null {
+    return typeof v === 'number' && Number.isFinite(v) ? v : null;
+}
+
+/**
+ * The one sentence both gates print, or `null` when there is nothing to say.
+ *
+ * `null` covers three cases deliberately collapsed into one, because they lead
+ * to the same output: full coverage (nothing to warn about), an absent block (an
+ * older ledger, written before the gate recorded coverage), and a malformed one
+ * (a string where a number belongs, a zero total). A reader who sees no label
+ * learns "this record makes no partial-coverage claim" — which is true of all
+ * three — and never a fabricated percentage derived from a field that was not
+ * a number.
+ *
+ * `filesTotal === 0` is `null` rather than `0 of 0 (partial)`: a change set with
+ * no files was fully read by any definition, and dividing by it says nothing.
+ */
+export function coverageLabel(coverage: unknown): string | null {
+    if (coverage === null || typeof coverage !== 'object') {
+        return null;
+    }
+    const c = coverage as ReviewCoverage;
+    const reviewed = _finite(c.filesReviewed);
+    const total = _finite(c.filesTotal);
+    if (reviewed === null || total === null || total <= 0 || reviewed >= total) {
+        return null;
+    }
+    return `self-review read ${String(reviewed)} of ${String(total)} changed files (partial)`;
+}
+
+/**
+ * The `coverage` block of a committed ledger, or `undefined`.
+ *
+ * Never throws. A missing ledger is the normal state of an in-flight release and
+ * a corrupt one is already the business of the gate that parses it properly —
+ * a label is not the place to discover either, and a reader that threw here
+ * would turn an informational line into a crash on a release branch.
+ */
+export function readLedgerCoverage(root: string, release: string): unknown {
+    const file = path.join(root, LEDGER_DIR, `${release}.json`);
+    try {
+        const parsed: unknown = JSON.parse(fs.readFileSync(file, 'utf-8'));
+        if (parsed === null || typeof parsed !== 'object') {
+            return undefined;
+        }
+        return (parsed as Record<string, unknown>)['coverage'];
+    } catch {
+        return undefined;
+    }
+}
+
+/** `coverageLabel` over the committed ledger for `release`. */
+export function ledgerCoverageLabel(root: string, release: string): string | null {
+    return coverageLabel(readLedgerCoverage(root, release));
+}
+
+/**
+ * The same label as a Known-limitations line, for the release-highlights gate.
+ *
+ * It carries the label plus the sentence that keeps a reader from mistaking it
+ * for a refusal, because the field it prints beside is one the gate CAN refuse
+ * on. Without that sentence the next person to read the output reasonably
+ * concludes the gate is about to start failing cuts on coverage, and the cheapest
+ * way to make the message go away becomes raising the ceiling — which is the
+ * owner's spend decision, taken by whoever happened to read the line.
+ *
+ * Returns `null` when there is nothing to say, so the caller prints nothing
+ * rather than a reassuring sentence about a number it does not have.
+ */
+export function coverageLimitationNote(label: string | null): string | null {
+    if (label === null) {
+        return null;
+    }
+    return (
+        `ℹ️  ${label} — a limitation of the RECORD, not a verdict on the release. ` +
+        'Stated, never enforced:\n    what the review reads is a spend decision and this ' +
+        'gate does not take it.'
+    );
+}

package/src/scripts/_lib/rule_consequence_class.ts

@@ -0,0 +1,71 @@
+/**
+ * The high-consequence rule class — one reader for the config, the projector
+ * and the test.
+ *
+ * The criterion itself is prose and lives where an author meets it: the
+ * `consequence_class` property of `src/scripts/schemas/rule.schema.json`. This
+ * module does not restate it. It reads the list the criterion produced
+ * (`src/config/rule-consequence-class.json`), joins it to what each rule file
+ * actually declares, and answers the one question `project_thin_rules` asks:
+ * may this rule's stub carry its own law, and if not, has that been declared?
+ *
+ * WHY A DECLARED `no_stub` SUBSET RATHER THAN A SHORTER CLASS. A member whose
+ * law section is missing or over the ceiling cannot ship as stub-plus-law —
+ * there is nothing short enough to copy. Two ways to handle that: drop it from
+ * the class, or keep it in the class and record why it cannot stand. Dropping
+ * it makes the class shrinkable by NOT writing a law, which is the incentive a
+ * criterion must not create. Keeping it leaves the obligation visible and costs
+ * only a full-bodied projection, which is what those rules get today anyway.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+export const CLASS_CONFIG_REL = 'src/config/rule-consequence-class.json';
+
+export const CLAUSES = ['irreversible-external', 'security-boundary', 'authority-bypass'] as const;
+export type Clause = (typeof CLAUSES)[number];
+
+export interface ClassMember {
+    clause: Clause;
+    /** What this rule's own law obligates, and what violating it costs. */
+    why: string;
+}
+
+export interface NoStubEntry extends ClassMember {
+    /** Why the law cannot stand in a stub today. */
+    reason: string;
+}
+
+export interface ConsequenceClassConfig {
+    criterion_ref: string;
+    members: Record<string, ClassMember>;
+    /** Subset of `members` that projects full-bodied, each with its reason. */
+    no_stub: Record<string, NoStubEntry>;
+    /** Near misses the criterion rejected, each with the reason it was rejected. */
+    excluded: Record<string, string>;
+}
+
+export function readConsequenceClass(repoRoot: string): ConsequenceClassConfig {
+    const raw = JSON.parse(fs.readFileSync(path.join(repoRoot, CLASS_CONFIG_REL), 'utf-8')) as Partial<
+        ConsequenceClassConfig
+    >;
+    return {
+        criterion_ref: raw.criterion_ref ?? '',
+        members: raw.members ?? {},
+        no_stub: raw.no_stub ?? {},
+        excluded: raw.excluded ?? {},
+    };
+}
+
+/** Ids whose stub carries their law — members minus the declared `no_stub` set. */
+export function stubLawIds(cfg: ConsequenceClassConfig): Set<string> {
+    return new Set(Object.keys(cfg.members).filter((id) => cfg.no_stub[id] === undefined));
+}
+
+/** The `consequence_class:` value a rule file declares, or `null`. */
+export function declaredClause(ruleText: string): Clause | null {
+    const m = /^consequence_class:\s*"?([a-z-]+)"?\s*$/m.exec(ruleText);
+    if (m === null) return null;
+    const v = m[1] as string;
+    return (CLAUSES as readonly string[]).includes(v) ? (v as Clause) : null;
+}

package/src/scripts/_lib/rule_injection.ts

@@ -72,8 +72,115 @@ export interface TierRuleMatch {
 /** Kinds of trigger a prompt alone can never fire. */
 export const PATH_TRIGGER_KINDS = ['path_prefix', 'file_pattern'] as const;
 
+/**
+ * Set by `dispatch_hook` to its own resolved package root. Read here rather
+ * than threaded through every caller — see `ruleSourceDirs`.
+ */
+export const PACKAGE_ROOT_ENV = 'AGENT_CONFIG_PACKAGE_ROOT';
+
+function statKind(p: string): 'dir' | 'file' | null {
+    try {
+        const s = fs.statSync(p);
+        return s.isDirectory() ? 'dir' : s.isFile() ? 'file' : null;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Every tree a rule body may come from, highest precedence first.
+ *
+ * THE DEFECT THIS CLOSES, reproduced at `main` @ `9bc8cd4f2` and again on
+ * 2026-10-01. This module resolved bodies and the router under ONE root, and
+ * the carrier passed the envelope's workspace or `process.cwd()`. In this
+ * checkout those are the same directory and everything works. In a consumer
+ * project they are not: there is no `dist/` under the consumer's tree at all,
+ * so `loadRouter` threw, the carrier caught it and returned allow, and the
+ * concern delivered NOTHING while reporting no error. Every consumer runs it
+ * in someone else's project, so the shipped carrier was silent for every
+ * consumer and loud only for its author. `dispatch_hook.ts:722` has passed
+ * `AGENT_CONFIG_PACKAGE_ROOT` to every concern since the ADR-020 global-only
+ * install landed — the fix was one environment read away and nothing read it.
+ *
+ * THE ORDER IS THE CONTRACT:
+ *
+ *   1. `<root>/agents/overrides/<id>.md` — the developer's own layer.
+ *      `agents_overlay.ts` already makes `overrides/` the one cascade kind
+ *      that is both project- and user-global-eligible, and a consumer who has
+ *      overridden a rule means it. It wins, which is what step 1.1's "with
+ *      `agents/overrides/` keeping precedence" asks for.
+ *   2. `<root>/dist/agent-src/rules/<id>.md` — the maintainer checkout. Kept
+ *      AHEAD of the package root and not behind it, so this repository's own
+ *      behaviour is byte-identical to what it was before. A change that
+ *      repairs consumers by moving the maintainer tree is one nobody can
+ *      review against a known-good reading.
+ *   3. `<packageRoot>/dist/agent-src/rules/<id>.md` — the install. The only
+ *      one of the three that exists in a foreign project.
+ *
+ * WHY THE ENVIRONMENT IS READ HERE rather than passed in. Nine call sites
+ * across the model, the shortlist, the arm experiment and two hooks pass a
+ * single `repoRoot`, and none of them has a second tree to offer. Threading a
+ * resolved source object through all of them would be a wide diff whose only
+ * real consumer is the carrier, and it costs runtime bytes in the composed
+ * hook bundle — which every hook event on every slot loads, under a hard
+ * ceiling (`src/config/hook-bundle-budget.json`). `roadmap_progress_hook`
+ * already reads this same variable this same way; this follows it rather than
+ * inventing a second convention. No `~` expansion: the one writer is
+ * `dispatch_hook`, which sets it from a `path.resolve` result.
+ */
+export interface RuleSources {
+    /** Body directories, highest precedence first. */
+    readonly dirs: readonly string[];
+    /** The resolved package root, or `null` when the variable named nothing. */
+    readonly pkg: string | null;
+    /** The `dist/router.json` to route against, or `null`. */
+    readonly router: string | null;
+    /**
+     * One line naming why nothing resolved, or `null` when something did.
+     *
+     * A caller that found nothing must be able to SAY so. An empty delivery is
+     * indistinguishable from "no rule matched", which is exactly the silence
+     * this chain exists to end; reproducing it one layer up would be the whole
+     * defect again. The three wordings are distinguishable because the
+     * operator's next action differs: the variable was never set (a host or
+     * wrapper problem), it points somewhere that is gone (a move after
+     * install), or both resolved and the package carries no built corpus.
+     */
+    readonly gap: string | null;
+}
+
+/** Resolve the body dirs, the router and the gap wording in ONE filesystem pass. */
+export function ruleSources(repoRoot: string): RuleSources {
+    const env = (process.env[PACKAGE_ROOT_ENV] ?? '').trim();
+    const pkg = env ? path.resolve(env) : null;
+    const dirs: string[] = [];
+    const add = (d: string): void => {
+        if (statKind(d) === 'dir' && !dirs.includes(d)) dirs.push(d);
+    };
+    add(path.join(repoRoot, 'agents', 'overrides'));
+    add(path.join(repoRoot, 'dist', 'agent-src', 'rules'));
+    if (pkg !== null) add(path.join(pkg, 'dist', 'agent-src', 'rules'));
+
+    const local = path.join(repoRoot, 'dist', 'router.json');
+    let router: string | null = statKind(local) === 'file' ? local : null;
+    if (router === null && pkg !== null) {
+        const shipped = path.join(pkg, 'dist', 'router.json');
+        if (statKind(shipped) === 'file') router = shipped;
+    }
+
+    let gap: string | null = null;
+    if (router === null || dirs.length === 0) {
+        const miss =
+            pkg === null
+                ? `${PACKAGE_ROOT_ENV} unset`
+                : `no ${router === null ? 'dist/router.json' : 'dist/agent-src/rules'} under ${repoRoot} or ${pkg}`;
+        gap = `rule-inject: no rule source — ${miss}`;
+    }
+    return { dirs, pkg, router, gap };
+}
+
 export function loadRouter(repoRoot: string): Router {
-    const p = path.join(repoRoot, 'dist', 'router.json');
+    const p = ruleSources(repoRoot).router ?? path.join(repoRoot, 'dist', 'router.json');
     return JSON.parse(fs.readFileSync(p, 'utf8')) as Router;
 }
 
@@ -163,16 +270,29 @@ export function matchTierRules(
     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. */
+/**
+ * The projected body from the highest-precedence tree carrying it, or `null`.
+ *
+ * `ruleBodyPath` used to sit in front of this and is gone: it returned the
+ * single-root path unconditionally, this diff changed its contract to "the
+ * first tree that has the file", and nothing outside this module ever called
+ * it. An exported helper whose last caller disappeared in the same diff is an
+ * own-orphan, and the composed hook bundle charges for it on every dispatch
+ * (`src/config/hook-bundle-budget.json`), so it is removed rather than left as
+ * a wrapper nobody uses.
+ */
 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');
+    for (const dir of ruleSources(repoRoot).dirs) {
+        const p = path.join(dir, `${id}.md`);
+        if (statKind(p) === 'file') {
+            try {
+                return fs.readFileSync(p, 'utf8');
+            } catch {
+                return null;
+            }
+        }
+    }
+    return null;
 }
 
 /**