@event4u/agent-config 16.2.0 → 16.3.0

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;
 }
 
 /**

package/src/scripts/_lib/rule_law_section.ts

@@ -0,0 +1,147 @@
+/**
+ * One spelling of "a rule's law section" — the unit three gates and one
+ * projector all price.
+ *
+ * A **law section** is a heading whose title matches `\biron\s+laws?\b` plus
+ * everything under it up to the next heading of the same or a shallower depth.
+ * A rule may carry several (`direct-answers` has three, `no-cheap-questions`
+ * six); the rule's law is all of them, joined by a blank line, because each one
+ * states an obligation and a stub carrying only the first would ship a rule
+ * whose other laws silently vanished.
+ *
+ * WHY A SHARED MODULE RATHER THAN A REGEX PER CALLER. The projector
+ * (`project_thin_rules.ts`) byte-copies this text into a stub and digests it;
+ * the lint (`lint_rule_law_section.ts`) holds it under a ceiling. If those two
+ * disagreed about where a section ends, the lint would certify a length the
+ * projection does not carry — the exact drift `THIN_ENTRY_MARKER`'s own comment
+ * argues against one file over.
+ *
+ * The heading regex is deliberately the SAME one `check_iron_law_prominence.ts`
+ * uses, so "has a law section" here and "is an Iron Law heading" there cannot
+ * diverge. That gate owns prominence (H2, near the top); this module owns
+ * extent and size.
+ *
+ * WHAT THIS DOES NOT CLAIM. Not that the extracted text IS the rule's obligation. A rule can state its
+ * law in bold prose or a bare fence under no heading at all — several of the 35
+ * routed rules without a heading match do exactly that. A heading match is a
+ * STRUCTURAL property, checkable; "this sentence is the obligation" is not, and
+ * `report_obligation_carriers` plus the `# obligation: line N` marker is where
+ * that question already lives.
+ */
+import * as fs from 'node:fs';
+
+/** Same literal as `check_iron_law_prominence.ts` — one definition, two readers. */
+export const IRON_LAW_RE = /\biron\s+laws?\b/i;
+
+const HEADING_RE = /^(#{1,6})\s+(.+?)\s*$/;
+const FENCE_RE = /^\s*```/;
+
+export interface LawSection {
+    /** Heading title, verbatim. */
+    title: string;
+    /** Heading depth (1–6). */
+    depth: number;
+    /** 1-based line of the heading within the body. */
+    line: number;
+    /** Heading line plus its section, trimmed. */
+    text: string;
+}
+
+/** Return `[frontmatter_including_fences, body]`. Empty frontmatter if none. */
+export function splitFrontmatter(text: string): [string, string] {
+    if (text.startsWith('---\n')) {
+        const end = text.indexOf('\n---\n', 4);
+        if (end !== -1) {
+            return [text.slice(0, end + 5), text.slice(end + 5)];
+        }
+    }
+    return ['', text];
+}
+
+/**
+ * The body a runtime delivery carries: frontmatter removed, HTML comments
+ * removed, trimmed.
+ *
+ * Comments are stripped because they are authoring scaffolding
+ * (`<!-- risk-review: … -->`, `<!-- harvest:… -->`, `ref-ignore` markers) that
+ * no host renders to a model, so charging a rule for them would price the wrong
+ * thing. Frontmatter is excluded for the reason `check_rule_stub_ceiling` gives
+ * for the same exclusion: it is the routing surface, and a rule that gains a
+ * trigger must not trip a ceiling whose message tells the author to move prose.
+ */
+export function ruleBody(text: string): string {
+    const [, body] = splitFrontmatter(text);
+    return body.replace(/<!--[\s\S]*?-->/g, '').trim();
+}
+
+/** Every law section in a rule body, in document order. */
+export function lawSections(body: string): LawSection[] {
+    const lines = body.split('\n');
+    let inFence = false;
+    const headings: Array<{ i: number; depth: number; title: string }> = [];
+    for (let i = 0; i < lines.length; i += 1) {
+        const raw = lines[i] as string;
+        if (FENCE_RE.test(raw)) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence) continue;
+        const m = HEADING_RE.exec(raw);
+        if (m) headings.push({ i, depth: (m[1] as string).length, title: (m[2] as string).trim() });
+    }
+    const out: LawSection[] = [];
+    for (let k = 0; k < headings.length; k += 1) {
+        const h = headings[k] as { i: number; depth: number; title: string };
+        if (!IRON_LAW_RE.test(h.title)) continue;
+        let end = lines.length;
+        for (let j = k + 1; j < headings.length; j += 1) {
+            const n = headings[j] as { i: number; depth: number; title: string };
+            if (n.depth <= h.depth) {
+                end = n.i;
+                break;
+            }
+        }
+        out.push({
+            title: h.title,
+            depth: h.depth,
+            line: h.i + 1,
+            text: lines.slice(h.i, end).join('\n').trim(),
+        });
+    }
+    return out;
+}
+
+/**
+ * The rule's law, as one byte string — all sections joined by a blank line.
+ * `null` when the rule has none, which is a different answer from `''`.
+ */
+export function lawText(body: string): string | null {
+    const sections = lawSections(body);
+    if (sections.length === 0) return null;
+    return sections.map((s) => s.text).join('\n\n');
+}
+
+export interface RuleLawMeasure {
+    id: string;
+    /** Characters of the law text, 0 when there is none. */
+    lawChars: number;
+    /** Number of law sections found. */
+    sections: number;
+    /** Characters of the comment-stripped body. */
+    bodyChars: number;
+    /** The law text itself, `null` when absent. */
+    law: string | null;
+}
+
+/** Measure one rule file. */
+export function measureRuleFile(id: string, filePath: string): RuleLawMeasure {
+    const body = ruleBody(fs.readFileSync(filePath, 'utf-8'));
+    const law = lawText(body);
+    return {
+        id,
+        lawChars: law === null ? 0 : law.length,
+        sections: lawSections(body).length,
+        bodyChars: body.length,
+        law,
+    };
+}

package/src/scripts/_lib/rule_layer_overlap.ts

@@ -25,6 +25,7 @@
  */
 
 import * as fs from 'node:fs';
+import * as os from 'node:os';
 import * as path from 'node:path';
 
 /**
@@ -140,6 +141,63 @@ export function compareLayers(
     };
 }
 
+/**
+ * The two directories Claude Code loads rules from, user layer first.
+ *
+ * ONE SOURCE OF TRUTH FOR SCOPE (`road-to-a-rule-carrier-that-works-outside-the-repo`
+ * step 1.3). Two readers need this pair and both used to spell it out inline:
+ * the installer's overlap gate, and — once the carrier started resolving bodies
+ * from the package rather than from the workspace — the delivery scope itself.
+ * A carrier scoping on one list while the installer gates on another would
+ * deliver a rule the install never wrote, which is the state step 1.3 exists to
+ * end.
+ *
+ * It is a UNION and not a precedence chain. The host loads both with no dedup —
+ * that is the whole reason this module exists — so a rule present in either
+ * layer is loaded, and "what the install carries" is the union of the two.
+ *
+ * `os.homedir()` rather than a settings key: the installer resolves the user
+ * layer the same way, and a second spelling of "where is home" is a second
+ * thing to disagree about.
+ */
+export function hostRuleLayerDirs(projectRoot: string): [string, string] {
+    return [
+        path.join(os.homedir(), '.claude', 'rules'),
+        path.join(projectRoot, '.claude', 'rules'),
+    ];
+}
+
+/**
+ * Rule ids present in either host rule layer, or `null` when NEITHER directory
+ * exists.
+ *
+ * `null` IS A DIFFERENT ANSWER FROM AN EMPTY SET, and the difference is the
+ * contract. An empty set means the install wrote a rule layer and it carries
+ * nothing, so nothing is in scope. `null` means no rule layer exists to declare
+ * a scope at all: a maintainer checkout, or a host this install writes no rules
+ * directory for. Scoping to the empty set there would re-create exactly the
+ * silence step 1.1 repaired, so the caller applies no filter instead.
+ *
+ * Names only, never bodies. This runs on the `user_prompt_submit` hot path, and
+ * {@link readRuleLayer} beside it reads every file's contents because ITS
+ * caller compares them. A scope check never needs a byte of any of them.
+ */
+export function hostRuleLayerIds(projectRoot: string): Set<string> | null {
+    const ids = new Set<string>();
+    let found = false;
+    for (const dir of hostRuleLayerDirs(projectRoot)) {
+        let names: string[];
+        try {
+            names = fs.readdirSync(dir);
+        } catch {
+            continue;
+        }
+        found = true;
+        for (const n of names) if (n.endsWith('.md')) ids.add(n.slice(0, -3));
+    }
+    return found ? ids : null;
+}
+
 /**
  * Read every `.md` in `dir` into a {@link RuleLayer}, or `null` when the
  * directory does not exist.