@event4u/agent-config 16.3.0 → 16.5.0

package/src/scripts/_lib/neighbour_tool_use.ts

@@ -3,7 +3,7 @@
  * reader in the neighbour census.
  *
  * WHY A MODULE OF ITS OWN, AND NOT A CONSTANT IN EITHER SIDE. The writer lives
- * in `hooks/telemetry_usage_hook.ts`, which is inlined into the shared hook
+ * in `hooks/mcp_usage_observation_hook.ts`, which is inlined into the shared hook
  * bundle `check_hook_bundle_composition` caps; the reader lives in
  * `_lib/neighbour_census.ts`, which is not. Putting the pair here lets esbuild
  * tree-shake {@link toolsUsedByServer} out of the hook bundle while both sides
@@ -113,16 +113,14 @@ export function toolBelongsTo(tool: string, segment: string): boolean {
 /**
  * The directory the store lives under, from any directory inside the project.
  *
- * The WRITER roots the store at the directory holding `.agent-settings.yml`
- * (`telemetry_usage_hook.readSettingsFor`), because a session started in a
- * subdirectory would otherwise scatter one store per directory it happened to
- * start in. The reader has to resolve the same way or it looks in the wrong
- * place: a monorepo with settings at the repo root and `.mcp.json` under
- * `packages/web` would report `0` for a server in daily use. The two walks are
- * pinned equal by a fixture rather than by assertion.
+ * Both the writer and the reader call this one function, so the store is
+ * rooted at the directory holding `.agent-settings.yml` on both sides: a
+ * session started in a subdirectory would otherwise scatter one store per
+ * directory, and a monorepo with settings at the repo root and `.mcp.json`
+ * under `packages/web` would read `0` for a server in daily use. A fixture
+ * still pins the two sides equal end to end.
  *
- * No settings file on any ancestor → `start`, matching the writer's own
- * fallback.
+ * No settings file on any ancestor → `start`.
  */
 export function resolveStoreRoot(start: string): string {
     let dir = path.resolve(start);

package/src/scripts/_lib/ratification_artifact.ts

@@ -96,10 +96,227 @@ export interface RatificationProblem {
         | 'no-providers'
         | 'diversity-required'
         | 'diversity-unverifiable'
-        | 'bad-effective-after';
+        | 'bad-effective-after'
+        | 'no-seats'
+        | 'malformed-seats'
+        | 'bad-seat-provider'
+        | 'unknown-seat-verdict'
+        | 'seat-dissent'
+        | 'providers-exceed-seats'
+        | 'header-not-derived';
     message: string;
 }
 
+/** A seat that closed, timed out or was absent at the last round gave no final verdict. */
+export const SEAT_NO_FINAL_VERDICT = 'no-final-verdict';
+export type SeatVerdict = RatificationVerdict | typeof SEAT_NO_FINAL_VERDICT;
+/** Every value a seat's final verdict may take — shared by the writer and the reader. */
+export const SEAT_VERDICTS: readonly string[] = [...RATIFICATION_VERDICTS, SEAT_NO_FINAL_VERDICT];
+
+/**
+ * A provider id as a seat key: lower-case, no whitespace and no YAML
+ * metacharacter, so a rendered header cannot be split or extended by a name
+ * and two spellings of one provider cannot collide after normalisation.
+ */
+export const SEAT_PROVIDER_RE = /^[a-z0-9][a-z0-9._-]*$/u;
+
+export type SeatsReading =
+    | { kind: 'absent' }
+    | { kind: 'invalid'; problems: RatificationProblem[] }
+    | { kind: 'present'; seats: Map<string, SeatVerdict> };
+
+/**
+ * The `seats:` map — provider id to that seat's FINAL verdict — in source
+ * order, which is the order `providers` is derived in.
+ *
+ * Absent and present-but-unusable are reported apart: a missing key and a
+ * `seats:` key that is empty, a scalar, a list, or carries a bad id or verdict
+ * are both refusals, with different codes.
+ */
+export function readSeats(fm: AdrFrontmatter, text = ''): SeatsReading {
+    const duplicates = duplicateSeatKeys(text);
+    if (duplicates.length > 0) {
+        return {
+            kind: 'invalid',
+            problems: [
+                {
+                    code: 'bad-seat-provider',
+                    message: `seat \`${duplicates.join('`, `')}\` is recorded more than once — the parser keeps only the last`,
+                },
+            ],
+        };
+    }
+    const hasScalar = Object.prototype.hasOwnProperty.call(fm.scalars, 'seats');
+    const node = fm.nested['seats'];
+    if (node === undefined && !hasScalar) {
+        return { kind: 'absent' };
+    }
+    if (node === undefined || typeof node === 'string' || Array.isArray(node)) {
+        return {
+            kind: 'invalid',
+            problems: [{ code: 'malformed-seats', message: '`seats:` is present but is not a provider-to-verdict map' }],
+        };
+    }
+    const problems: RatificationProblem[] = [];
+    const seats = new Map<string, SeatVerdict>();
+    for (const [provider, verdict] of Object.entries(node)) {
+        if (!SEAT_PROVIDER_RE.test(provider)) {
+            problems.push({
+                code: 'bad-seat-provider',
+                message: `seat key \`${provider}\` is not a provider id (${String(SEAT_PROVIDER_RE)})`,
+            });
+            continue;
+        }
+        if (typeof verdict !== 'string' || !SEAT_VERDICTS.includes(verdict.trim())) {
+            problems.push({
+                code: 'unknown-seat-verdict',
+                message: `seat \`${provider}\` records \`${String(verdict)}\`, not one of ${SEAT_VERDICTS.join(', ')}`,
+            });
+            continue;
+        }
+        seats.set(provider, verdict.trim() as SeatVerdict);
+    }
+    if (problems.length === 0 && seats.size === 0) {
+        problems.push({ code: 'malformed-seats', message: '`seats:` is present and empty' });
+    }
+    return problems.length > 0 ? { kind: 'invalid', problems } : { kind: 'present', seats };
+}
+
+/** Keys repeated inside the frontmatter `seats:` block, read from the raw text. */
+function duplicateSeatKeys(text: string): string[] {
+    if (!text.startsWith('---\n')) return [];
+    const end = text.indexOf('\n---\n', 4);
+    const lines = text.slice(4, end === -1 ? undefined : end).split('\n');
+    const start = lines.findIndex((l) => /^seats:\s*$/u.test(l));
+    if (start === -1) return [];
+    const seen = new Set<string>();
+    const dup = new Set<string>();
+    for (const line of lines.slice(start + 1)) {
+        if (!/^\s/u.test(line)) break;
+        // Compared by the identity a YAML parser would give the key, so a quoted
+        // spelling cannot hide a second entry for the same seat.
+        const key = line
+            .slice(0, line.indexOf(':') === -1 ? undefined : line.indexOf(':'))
+            .trim()
+            .replace(/^(["'])(.*)\1$/u, '$2')
+            .trim();
+        if (key === '' || key.startsWith('#')) continue;
+        if (seen.has(key)) dup.add(key);
+        seen.add(key);
+    }
+    return [...dup];
+}
+
+/**
+ * The header a set of seat verdicts supports, and no more.
+ *
+ * `providers` is every seat that gave a final verdict — a closed seat is not a
+ * provider the verdict came from. Any refusing seat makes the verdict `refused`,
+ * any non-convergent one `non-convergent`; only when every final seat passed is
+ * the verdict passing, and then `ratified` if any seat said so. No final seat at
+ * all is `non-convergent`: a review that ended without a verdict did not pass.
+ */
+export function deriveRatificationHeader(
+    seats: ReadonlyMap<string, SeatVerdict> | Readonly<Record<string, SeatVerdict>>,
+): { providers: string[]; verdict: RatificationVerdict } {
+    const entries = seats instanceof Map ? [...seats.entries()] : Object.entries(seats);
+    const final = entries.filter(([, v]) => v !== SEAT_NO_FINAL_VERDICT) as [string, RatificationVerdict][];
+    const verdicts = final.map(([, v]) => v);
+    let verdict: RatificationVerdict;
+    if (verdicts.includes('refused')) {
+        verdict = 'refused';
+    } else if (final.length === 0 || verdicts.includes('non-convergent')) {
+        verdict = 'non-convergent';
+    } else {
+        verdict = verdicts.includes('ratified') ? 'ratified' : 'confirmed-non-expanding';
+    }
+    return { providers: final.map(([p]) => p), verdict };
+}
+
+/**
+ * The `providers:`, `verdict:` and `seats:` frontmatter lines, derived — never
+ * typed. Throws on a provider id outside {@link SEAT_PROVIDER_RE}: a name that
+ * could carry YAML syntax is refused rather than escaped.
+ */
+export function renderRatificationHeader(
+    seats: ReadonlyMap<string, SeatVerdict> | Readonly<Record<string, SeatVerdict>>,
+): string {
+    const entries = seats instanceof Map ? [...seats.entries()] : Object.entries(seats);
+    for (const [p, v] of entries) {
+        if (!SEAT_PROVIDER_RE.test(p)) throw new Error(`not a provider id: ${JSON.stringify(p)}`);
+        if (!SEAT_VERDICTS.includes(v)) throw new Error(`not a seat verdict: ${JSON.stringify(v)}`);
+    }
+    const { providers, verdict } = deriveRatificationHeader(seats);
+    return [
+        `providers: [${providers.join(', ')}]`,
+        `verdict: ${verdict}`,
+        'seats:',
+        ...entries.map(([p, v]) => `  ${p}: ${v}`),
+    ].join('\n');
+}
+
+/**
+ * The header claims the seats do not support.
+ *
+ * `seats:` is required. Optional, it left `providers` and `verdict` free-written
+ * for every author who omitted it, which is the defect it exists to close; the
+ * round-2 ratification review refused that shape. The gate reads only the
+ * artifacts in the diff under review, so an artifact merged before the field
+ * existed is never re-read and needs no migration to stay valid.
+ *
+ * The recorded header must EQUAL the derived one; the two named overclaims get
+ * their own codes so a reader sees which one it was.
+ */
+function seatProblems(reading: SeatsReading, providers: readonly string[], verdict: string | null): RatificationProblem[] {
+    if (reading.kind === 'absent') {
+        return [
+            {
+                code: 'no-seats',
+                message:
+                    'missing `seats:` — `providers` and `verdict` are derived from the per-seat final ' +
+                    'verdicts, never typed (print all three with `ratification_header`)',
+            },
+        ];
+    }
+    if (reading.kind === 'invalid') return reading.problems;
+    const seats = reading.seats;
+    const problems: RatificationProblem[] = [];
+    if (verdict !== null && PASSING_VERDICTS.has(verdict)) {
+        const dissent = [...seats].filter(([, v]) => v === 'refused' || v === 'non-convergent');
+        if (dissent.length > 0) {
+            problems.push({
+                code: 'seat-dissent',
+                message:
+                    `verdict \`${verdict}\` while ${dissent.map(([p, v]) => `${p} was \`${v}\``).join(', ')} ` +
+                    'at the final round — a header cannot say more than its seats said',
+            });
+        }
+    }
+    const derived = deriveRatificationHeader(seats);
+    const extra = providers.filter((p) => !derived.providers.includes(p));
+    if (extra.length > 0) {
+        problems.push({
+            code: 'providers-exceed-seats',
+            message:
+                `providers names ${extra.join(', ')}, which gave no final verdict ` +
+                `(${String(derived.providers.length)} seat(s) did) — diversity is counted over seats that answered`,
+        });
+    }
+    if (
+        problems.length === 0 &&
+        (verdict !== derived.verdict || providers.join('\u0000') !== derived.providers.join('\u0000'))
+    ) {
+        problems.push({
+            code: 'header-not-derived',
+            message:
+                `recorded providers [${providers.join(', ')}] / verdict \`${String(verdict)}\` differ from the ` +
+                `header the seats derive: [${derived.providers.join(', ')}] / \`${derived.verdict}\` ` +
+                '(print it with `ratification_header`)',
+        });
+    }
+    return problems;
+}
+
 export interface RatificationReading {
     artifact: RatificationArtifact | null;
     problems: RatificationProblem[];
@@ -208,6 +425,8 @@ export function readRatification(
         }
     }
 
+    problems.push(...seatProblems(readSeats(fm, text), providers, verdict));
+
     // Diversity, against the REQUIRED count.
     //
     // Round 1 refused the previous shape: the count came from the user-global

package/src/scripts/_lib/ratification_subject.ts

@@ -0,0 +1,92 @@
+/**
+ * ratification_subject — the digest a ratification record carries over the
+ * gated content it reviewed.
+ *
+ * `road-to-self-modification-that-a-council-must-pass` step 2.1, the half that
+ * does not touch the gate. The record says WHO reviewed; without a digest it
+ * does not say WHAT, so a gated file edited after its review still ships under
+ * a record that approved something else.
+ *
+ * WHY IT RE-ASSEMBLES THE LIST RATHER THAN RE-DECIDING IT. The gate's
+ * `classifyPaths` returns the kernel rules, hooks and plumbing by name but
+ * reports the self surface as a BOOLEAN, so the gated list cannot be read back
+ * out of it. This module therefore imports the gate's own path constants and
+ * re-assembles — it never restates the membership rule, because a second
+ * definition of "gated" is a second thing to keep in step, and the first time
+ * the two diverged a file would be reviewed by one and digested by the other.
+ *
+ * NO BASE DIFF. The digest is over the tree as it stands, so it is the same on
+ * a branch and on the merged checkout CI judges — unless the base changed a
+ * gated file the change also touches, and then the content that would land is
+ * not the content that was reviewed, which is precisely what should move it.
+ */
+
+import { createHash } from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import {
+    ANCHOR_PATHS,
+    CLOSURE_READER_PATH,
+    POLICY_PATH,
+    READER_PATH,
+    SELF_PATH,
+    WORKFLOW_PATH,
+    classifyPaths,
+} from '../check_kernel_edit_ratified.js';
+
+/**
+ * Stands in for the content of a gated file the change deletes. A deleted file
+ * is ENTERED, never skipped: skipping would make "this file was removed"
+ * digest-identical to "this file was never gated", and removing a governance
+ * hook is exactly the change the record most needs to be bound to.
+ */
+export const DELETED_MARKER = '\u0000deleted\u0000';
+
+/** The self surface, by the gate's own constants rather than a copy of them. */
+const SELF_SET: ReadonlySet<string> = new Set<string>([
+    SELF_PATH,
+    READER_PATH,
+    CLOSURE_READER_PATH,
+    POLICY_PATH,
+    WORKFLOW_PATH,
+    ...ANCHOR_PATHS,
+]);
+
+/**
+ * The gated subset of a changed-file list: sorted, deduplicated, and stable
+ * against the order the caller happened to collect the paths in.
+ */
+export function gatedFilesOf(
+    files: readonly string[],
+    derived?: readonly string[],
+): readonly string[] {
+    const normalized = files.map((f) => f.replace(/\\/g, '/').trim()).filter((f) => f !== '');
+    const g = derived === undefined ? classifyPaths(normalized) : classifyPaths(normalized, derived);
+    const out = new Set<string>([...g.kernelRules, ...g.governanceHooks, ...g.plumbing]);
+    for (const f of normalized) {
+        if (SELF_SET.has(f)) out.add(f);
+    }
+    return [...out].sort();
+}
+
+/**
+ * One digest over the sorted paths AND contents of the gated files, read from
+ * `root`.
+ *
+ * The path is hashed alongside its content, so two files with identical bytes
+ * do not collide and a rename moves the digest — a gated file moved to another
+ * gated path is a different change, not the same one.
+ */
+export function subjectDigest(root: string, files: readonly string[]): string {
+    const h = createHash('sha256');
+    for (const rel of gatedFilesOf(files)) {
+        const abs = path.join(root, rel);
+        const content = fs.existsSync(abs) ? fs.readFileSync(abs) : Buffer.from(DELETED_MARKER);
+        h.update(rel);
+        h.update('\u0000');
+        h.update(createHash('sha256').update(content).digest('hex'));
+        h.update('\n');
+    }
+    return h.digest('hex');
+}

package/src/scripts/_lib/release_findings_ingest.ts

@@ -160,7 +160,9 @@ export function dispositionStopMessage(
     resumeCmd: string,
 ): string {
     const count =
-        blocking > 0 ? `  ${blocking} of them are blocking findings with no status yet.\n` : '';
+        blocking > 0
+            ? `  ${blocking} of them are blocking findings with no disposition yet (no status, or still_open).\n`
+            : '';
     return (
         `the disposition gate refuses ${version}. Its own report:\n` +
         `${gateOutput.trim() || '  (the gate printed nothing — run it directly to see why)'}\n` +
@@ -296,7 +298,7 @@ export function settleFindingsLedger(
                 // the operator `scanned: N` and discarded the entire reason the
                 // release stopped.
                 [verdict.stdout, verdict.stderr].map((s) => s.trim()).filter(Boolean).join('\n'),
-                blockingWithoutDisposition(path.join(deps.repoRoot, rel)),
+                blockingWithoutDisposition(path.join(deps.repoRoot, rel), version),
                 'task release -- --resume --yes',
             ),
         );
@@ -304,20 +306,26 @@ export function settleFindingsLedger(
 }
 
 /**
- * How many blocking findings carry no status — a figure for the stop message,
- * never the reason for it.
+ * How many blocking findings carry no disposition — no status, or `still_open`,
+ * which a blocking row may not rest on — a figure for the stop message, never
+ * the reason for it.
  *
  * The gate refuses for more shapes than this counts (an unknown status, an
  * empty rationale or verifier, a `fixed` with no commit, a malformed ledger),
- * which is why the gate's own output is what the operator is shown.
+ * which is why the gate's own output is what the operator is shown. It
+ * classifies against the version being released, the same input the gate
+ * reads from `--release`, not the ledger file's own `release` field.
  */
-function blockingWithoutDisposition(ledgerAbs: string): number {
+export function blockingWithoutDisposition(ledgerAbs: string, version: string): number {
     if (!fs.existsSync(ledgerAbs)) {
         return 0;
     }
     try {
         const ledger = parse_ledger(fs.readFileSync(ledgerAbs, 'utf-8'), ledgerAbs);
-        return ledger.findings.filter((f) => isBlocking(f) && !f.status).length;
+        return ledger.findings.filter((f) => {
+            const status = (f.status ?? '').trim();
+            return isBlocking(f, version) && (status === '' || status === 'still_open');
+        }).length;
     } catch {
         return 0;
     }

package/src/scripts/_lib/release_highlights.ts

@@ -610,6 +610,11 @@ const TEST_FOOTER_RE = /^Tests: \d+/mu;
  */
 export interface MixObligation {
     level: string;
+    /** The resolved ends the counts were read on; the rendered level names both. */
+    from_sha?: string;
+    to_sha?: string;
+    governance_only?: number;
+    consumer_only?: number;
 }
 
 /** Labels whose curated value is still the generator's unedited draft. */

package/src/scripts/_lib/rule_law_section.ts

@@ -25,7 +25,7 @@
  * 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
+ * `report_obligation_carriers` plus the ids in `src/config/rule-obligations.json` is where
  * that question already lives.
  */
 import * as fs from 'node:fs';

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_]+)+$/;
 
 /**