@event4u/agent-config 16.2.0 → 16.4.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 ids in `src/config/rule-obligations.json` 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.

package/src/scripts/_lib/rule_obligations.ts

@@ -0,0 +1,205 @@
+/**
+ * Stable obligation ids per rule, and which `enforced_by` entry refuses which.
+ *
+ * A rule holds several obligations, and `enforced_by` used to credit all of
+ * them for whatever one gate refuses: `git-history-discipline` counted as gated
+ * because a hook refuses `--no-verify`, while its laws against unsolicited
+ * rebase and dropped commits are refused by nothing. The inventory names each
+ * obligation `<rule>.<obligation>` so a gate is credited with the ids it
+ * actually refuses and nothing else.
+ *
+ * WHY A SIDECAR AND NOT RULE FRONTMATTER. `check_preamble_payload_budget`
+ * measures every byte of every projected rule file, frontmatter included, as
+ * per-spawn payload, and holds it at zero net growth. Some 290 ids in
+ * frontmatter would have been payload no model needs. The ids are routing and
+ * accounting data, so they live with the rest of that data in `src/config/`.
+ *
+ * WHY THE ID IS NOT DERIVED FROM THE LAW TEXT. A hash or an excerpt changes
+ * when the law is reworded, and an id that moves on every reword is not stable.
+ * The slug names the clause; the law text is free to change under it. That is
+ * also why the `# obligation: line N` frontmatter marker is retired: a line
+ * number drifts on every edit above it, and at retirement 34 of the 68 markers
+ * on rules with a law section no longer pointed inside that section.
+ *
+ * BINDINGS. `bindings` maps an `enforced_by` entry, spelled exactly as in the
+ * rule's frontmatter, to the ids it refuses. An entry with no key here is
+ * UNBOUND: it keeps the rule-level credit it always had and is counted
+ * separately, never as obligation-level coverage. An entry bound to `[]` is a
+ * recorded finding that it refuses none of this rule's obligations.
+ *
+ * The nine kernel rules are absent by construction: agents cannot write them,
+ * and they stay at rule granularity.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { parse as parseYaml } from 'yaml';
+
+import { KERNEL_RULE_ID_SET } from './kernel_rules.js';
+import { lawSections, ruleBody, splitFrontmatter } from './rule_law_section.js';
+
+export const RULE_OBLIGATIONS_PATH = 'src/config/rule-obligations.json';
+
+const SLUG = '[a-z0-9]+(?:-[a-z0-9]+)*';
+
+/** `<rule>.<obligation>`, both halves kebab-case. */
+export const OBLIGATION_ID_RE = new RegExp(`^(${SLUG})\\.(${SLUG})$`);
+
+/** The retired per-rule pointer. Kept only so the lint can refuse its return. */
+export const OBLIGATION_MARKER_RE = /^#\s*obligation:\s*line\s+\d+\s*$/m;
+
+export interface RuleObligationEntry {
+    obligations: string[];
+    bindings?: Record<string, string[]>;
+}
+
+export interface RuleObligationInventory {
+    rules: Record<string, RuleObligationEntry>;
+}
+
+export function loadRuleObligations(root: string): RuleObligationInventory {
+    const file = path.join(root, RULE_OBLIGATIONS_PATH);
+    const raw = JSON.parse(fs.readFileSync(file, 'utf-8')) as Partial<RuleObligationInventory>;
+    return { rules: raw.rules ?? {} };
+}
+
+/** What the lint needs to know about one rule file. */
+export interface RuleFacts {
+    id: string;
+    kernel: boolean;
+    hasLawSection: boolean;
+    enforcedBy: string[];
+    hasMarker: boolean;
+}
+
+export function readRuleFacts(id: string, text: string): RuleFacts {
+    const [fmBlock] = splitFrontmatter(text);
+    let enforcedBy: string[] = [];
+    if (fmBlock !== '') {
+        const inner = fmBlock.replace(/^---\n/, '').replace(/\n---\n$/, '');
+        const fm = (parseYaml(inner) ?? {}) as Record<string, unknown>;
+        const raw = fm['enforced_by'];
+        if (Array.isArray(raw)) enforcedBy = raw.map(String);
+        else if (typeof raw === 'string' && raw !== '') enforcedBy = [raw];
+    }
+    return {
+        id,
+        kernel: KERNEL_RULE_ID_SET.has(id),
+        hasLawSection: lawSections(ruleBody(text)).length > 0,
+        enforcedBy,
+        hasMarker: OBLIGATION_MARKER_RE.test(fmBlock),
+    };
+}
+
+export function collectRuleFacts(rulesDir: string): RuleFacts[] {
+    return fs
+        .readdirSync(rulesDir)
+        .filter((n) => n.endsWith('.md'))
+        .sort()
+        .map((n) => readRuleFacts(n.slice(0, -3), fs.readFileSync(path.join(rulesDir, n), 'utf-8')));
+}
+
+export interface ObligationFinding {
+    rule: string;
+    code:
+        | 'unknown-rule'
+        | 'kernel-declared'
+        | 'missing'
+        | 'empty'
+        | 'bad-id'
+        | 'wrong-prefix'
+        | 'duplicate'
+        | 'binding-entry-not-declared'
+        | 'binding-id-unknown'
+        | 'marker-present';
+    message: string;
+}
+
+/**
+ * Every finding the inventory and the rule tree produce together.
+ *
+ * Required: every non-kernel rule with a law section has an entry. A rule
+ * without one MAY have an entry, and if it does the same checks apply.
+ */
+export function lintRuleObligations(
+    inventory: RuleObligationInventory,
+    facts: readonly RuleFacts[],
+): ObligationFinding[] {
+    const out: ObligationFinding[] = [];
+    const byId = new Map(facts.map((f) => [f.id, f]));
+    const seen = new Map<string, string>();
+
+    for (const f of facts) {
+        if (f.hasMarker) {
+            out.push({
+                rule: f.id,
+                code: 'marker-present',
+                message:
+                    'carries a `# obligation: line N` marker; it is retired — the ids in ' +
+                    `${RULE_OBLIGATIONS_PATH} name the obligation`,
+            });
+        }
+        if (!f.kernel && f.hasLawSection && inventory.rules[f.id] === undefined) {
+            out.push({
+                rule: f.id,
+                code: 'missing',
+                message: `has a law section and no entry in ${RULE_OBLIGATIONS_PATH}`,
+            });
+        }
+    }
+
+    for (const [rule, entry] of Object.entries(inventory.rules)) {
+        const fact = byId.get(rule);
+        if (fact === undefined) {
+            out.push({ rule, code: 'unknown-rule', message: 'no such rule under src/rules/' });
+            continue;
+        }
+        if (fact.kernel) {
+            out.push({
+                rule,
+                code: 'kernel-declared',
+                message: 'kernel rules stay at rule granularity and carry no obligation ids',
+            });
+        }
+        const ids = Array.isArray(entry.obligations) ? entry.obligations : [];
+        if (ids.length === 0) {
+            out.push({ rule, code: 'empty', message: 'declares no obligations' });
+        }
+        const own = new Set<string>();
+        for (const id of ids) {
+            const m = OBLIGATION_ID_RE.exec(id);
+            if (m === null) {
+                out.push({ rule, code: 'bad-id', message: `\`${id}\` is not \`<rule>.<obligation>\` kebab-case` });
+                continue;
+            }
+            if (m[1] !== rule) {
+                out.push({ rule, code: 'wrong-prefix', message: `\`${id}\` is not prefixed with \`${rule}.\`` });
+            }
+            const prior = seen.get(id);
+            if (prior !== undefined) {
+                out.push({ rule, code: 'duplicate', message: `\`${id}\` is declared twice (also under ${prior})` });
+            }
+            seen.set(id, rule);
+            own.add(id);
+        }
+        for (const [entryName, bound] of Object.entries(entry.bindings ?? {})) {
+            if (!fact.enforcedBy.includes(entryName)) {
+                out.push({
+                    rule,
+                    code: 'binding-entry-not-declared',
+                    message: `binds \`${entryName}\`, which is not in the rule's enforced_by`,
+                });
+            }
+            for (const id of bound) {
+                if (!own.has(id)) {
+                    out.push({
+                        rule,
+                        code: 'binding-id-unknown',
+                        message: `\`${entryName}\` binds \`${id}\`, which this rule does not declare`,
+                    });
+                }
+            }
+        }
+    }
+    return out;
+}

package/src/scripts/_lib/self_repair.ts

@@ -322,7 +322,7 @@ function stemOf(token: string): string {
     return base.replace(/\.md$/, '');
 }
 
-/** Dotted settings-key shape — `personal.autonomy`, `tokens.rich_skills`, … */
+/** Dotted settings-key shape — `personal.autonomy`, `memory.redact_patterns`, … */
 const DOTTED_KEY_RE = /^[a-z0-9_]+(\.[a-z0-9_]+)+$/;
 
 /**