@event4u/agent-config 9.6.0 → 9.8.0

package/src/scripts/hooks/code_graph_nudge_hook.ts

@@ -0,0 +1,184 @@
+#!/usr/bin/env tsx
+/**
+ * PreToolUse code-graph nudge (ADR-124 Phase 4) — deterministic, warn-only.
+ *
+ * When a code-graph source is available and the agent is about to search or
+ * read source files, surface a one-line reminder to query the graph first.
+ * NEVER blocks (dispatcher contract: 0 allow · 2 warn) — Source G's strict
+ * block-the-first-read mode is deliberately NOT ported (blocking reads on a
+ * possibly-stale index violates the minimal-safe-diff posture). Once per
+ * session (a latch keyed by session id), so it cannot nag.
+ *
+ * Default-OFF. Fires only when `hooks.code_graph.enabled: true`. Disabled /
+ * missing / already-latched → no-op exit 0. fail_closed: false — any error
+ * returns allow; a token optimisation must never break a tool call.
+ *
+ * Branches (first eligible search/read this session):
+ *   present + fresh → "query the graph first"
+ *   present + stale → "index N commits behind — rebuild"
+ *   absent          → "no graph — build one?"
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { detectSources, pickSource } from '../code_graph/detect.js';
+
+const SETTINGS_FILE = '.agent-settings.yml';
+const EXIT_ALLOW = 0;
+const EXIT_WARN = 2;
+const CODE_EXT = /\.(php|ts|tsx|mts|cts|js|jsx|mjs|cjs)$/i;
+
+type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
+type JsonObject = { [k: string]: JsonValue };
+
+function isObject(v: unknown): v is JsonObject {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/** `hooks.code_graph.enabled: true` mini-parser (mirrors rtk_wrap_hook). */
+export function enabled(root: string): boolean {
+    const f = path.join(root, SETTINGS_FILE);
+    let text: string;
+    try {
+        if (!fs.statSync(f).isFile()) return false;
+        text = fs.readFileSync(f, 'utf-8');
+    } catch {
+        return false;
+    }
+    let inHooks = false;
+    let inCg = false;
+    for (const raw of text.split(/\r\n|\r|\n/)) {
+        const line = raw.replace(/\s+$/, '');
+        if (!line || line.replace(/^\s+/, '').startsWith('#')) continue;
+        if (!(line.startsWith(' ') || line.startsWith('\t'))) {
+            inHooks = /^hooks\s*:\s*$/.test(line);
+            inCg = false;
+            continue;
+        }
+        if (inHooks) {
+            if (/^\s+code_graph\s*:\s*$/.test(line)) {
+                inCg = true;
+                continue;
+            }
+            if (inCg && /^\s{0,3}\S/.test(line)) inCg = false;
+        }
+        if (inCg && /^\s+enabled\s*:\s*true\b/.test(line)) return true;
+    }
+    return false;
+}
+
+interface ToolIntent {
+    isSearch: boolean;
+    isCodeRead: boolean;
+}
+
+/** Best-effort read of the intercepted tool + its target from the envelope. */
+export function classifyTool(envelope: JsonObject): ToolIntent {
+    const payload = isObject(envelope['payload']) ? envelope['payload'] : envelope;
+    const nameVal =
+        payload['tool_name'] ?? payload['toolName'] ?? payload['tool'] ?? envelope['tool_name'] ?? envelope['tool'];
+    const name = typeof nameVal === 'string' ? nameVal : '';
+    const ti = (isObject(payload['tool_input']) ? payload['tool_input'] : envelope['tool_input']) as
+        | JsonObject
+        | undefined;
+    const isSearch = name === 'Grep' || name === 'Glob';
+    let isCodeRead = false;
+    if (name === 'Read' && isObject(ti)) {
+        const fp = ti['file_path'] ?? ti['path'];
+        if (typeof fp === 'string') isCodeRead = CODE_EXT.test(fp);
+    }
+    return { isSearch, isCodeRead };
+}
+
+function sessionId(envelope: JsonObject): string {
+    const s = envelope['session_id'] ?? envelope['sessionId'];
+    return typeof s === 'string' && s ? s : 'default';
+}
+
+function latchFile(root: string): string {
+    return path.join(root, 'agents', 'runtime', 'state', 'code-graph-nudge.json');
+}
+function alreadyNudged(root: string, session: string): boolean {
+    try {
+        const state = JSON.parse(fs.readFileSync(latchFile(root), 'utf-8')) as Record<string, boolean>;
+        return state[session] === true;
+    } catch {
+        return false;
+    }
+}
+function latch(root: string, session: string): void {
+    try {
+        const p = latchFile(root);
+        let state: Record<string, boolean> = {};
+        try {
+            state = JSON.parse(fs.readFileSync(p, 'utf-8')) as Record<string, boolean>;
+        } catch {
+            /* fresh */
+        }
+        state[session] = true;
+        fs.mkdirSync(path.dirname(p), { recursive: true });
+        fs.writeFileSync(p, JSON.stringify(state));
+    } catch {
+        /* fail-open: a persistence failure must not break the tool call */
+    }
+}
+
+const NATIVE_CACHE = path.join('agents', 'runtime', 'state', 'code-graph-v1.json');
+
+/** The nudge line for the current source state (≤40 tokens, one line). */
+export function nudgeReason(root: string): string {
+    const verdicts = detectSources(root, path.join(root, NATIVE_CACHE));
+    const picked = pickSource(verdicts);
+    if (!picked) {
+        return 'No code-graph found. For "who calls / where used / impact" run `code_graph build` once, then `code_graph query <symbol>` instead of grepping blind.';
+    }
+    if (picked.stale) {
+        return `code-graph is ${picked.commits_behind ?? 'N'} commit(s) behind — rebuild with \`code_graph build --update\` before trusting relationship answers.`;
+    }
+    return 'A fresh code-graph is present — for structure questions run `code_graph query|affected <symbol>` first; grep is the fallback (say which answered).';
+}
+
+export function main(): number {
+    let envelope: JsonValue;
+    try {
+        const raw = process.stdin.isTTY ? '' : fs.readFileSync(0, 'utf-8');
+        envelope = raw.trim() ? (JSON.parse(raw) as JsonValue) : {};
+    } catch {
+        return EXIT_ALLOW;
+    }
+    if (!isObject(envelope)) return EXIT_ALLOW;
+
+    const cwd = envelope['cwd'];
+    const pr = envelope['workspace_root'] ?? envelope['project_root'];
+    const root = typeof cwd === 'string' && cwd ? cwd : typeof pr === 'string' && pr ? pr : '.';
+    if (!enabled(root)) return EXIT_ALLOW;
+
+    const { isSearch, isCodeRead } = classifyTool(envelope);
+    if (!isSearch && !isCodeRead) return EXIT_ALLOW;
+
+    const session = sessionId(envelope);
+    if (alreadyNudged(root, session)) return EXIT_ALLOW; // once per session
+
+    let reason: string;
+    try {
+        reason = nudgeReason(root);
+    } catch {
+        return EXIT_ALLOW;
+    }
+    latch(root, session);
+    process.stdout.write(`${JSON.stringify({ decision: 'warn', reason })}\n`);
+    return EXIT_WARN;
+}
+
+function isCliEntry(): boolean {
+    if (process.argv[1] === undefined) return false;
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) return true;
+    try {
+        return fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+if (isCliEntry()) process.exit(main());

package/src/scripts/hooks/dispatch_hook.ts

@@ -35,6 +35,7 @@ import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { parse as parseYaml } from "yaml";
 
+import { hardenedSpawnEnv } from "../_lib/spawn_env.js";
 import {
   atomic_write_json,
   feedback_dir,
@@ -500,7 +501,10 @@ function _run_concern(concern: ConcernDef, envelope: JsonObject): RunResult {
   // Pass the package root so concerns can locate package-shipped
   // distributed content (ADR-020 global-only consumers carry no
   // project-local copy). REPO_ROOT is the dispatcher's own resolved root.
-  const concern_env = { ...process.env, AGENT_CONFIG_PACKAGE_ROOT: REPO_ROOT };
+  // Consumer-runtime concern dispatch: scrub code-execution-injection env
+  // vectors (loader / git-config / NODE_OPTIONS / …) before spawning each
+  // concern, then set the package-root marker as an explicit override.
+  const concern_env = hardenedSpawnEnv({ AGENT_CONFIG_PACKAGE_ROOT: REPO_ROOT });
 
   const started = performance.now();
   const { command, args: spawnArgs } = _resolve_tsx_invocation(script, cmd.slice(1));

package/src/scripts/iron_law_sha.ts

@@ -26,6 +26,7 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { artefact_roots } from './_lib/agent_src.js';
+import { KERNEL_RULE_IDS } from './_lib/kernel_rules.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 
@@ -60,18 +61,8 @@ function _isFile(p: string): boolean {
     }
 }
 
-// Locked kernel set — kept in sync with measure_rule_budget.KERNEL_RULES.
-const KERNEL_RULES: readonly string[] = [
-    'agent-authority',
-    'ask-when-uncertain',
-    'commit-policy',
-    'direct-answers',
-    'language-and-tone',
-    'no-cheap-questions',
-    'non-destructive-by-default',
-    'scope-control',
-    'verify-before-complete',
-];
+// Locked kernel set — single-sourced in _lib/kernel_rules.ts.
+const KERNEL_RULES: readonly string[] = KERNEL_RULE_IDS;
 
 // Python: re.compile(r"```(?:[^\n]*\n)([\s\S]*?)```")
 const _FENCE_RE = /```(?:[^\n]*\n)([\s\S]*?)```/g;

package/src/scripts/lint_override_kernel_guard.ts

@@ -0,0 +1,219 @@
+#!/usr/bin/env tsx
+/**
+ * Override audit — kernel-rule overrides, reported rather than policed.
+ *
+ * The obvious design for this file was a build-failing lint on any kernel-named
+ * file under `agents/overrides/rules/`. The council talked us out of it, and the
+ * argument holds: the override layer is resolved by the *agent reading the
+ * instructions*, not by a loader, so a consumer who wants a kernel rule relaxed
+ * has other routes — a persona file, host-level agent config, a line in the
+ * prompt. Failing the build on route one does not shrink that surface; it moves
+ * the override to a route with no visibility at all, while the red X reads as
+ * coverage. That is the exact "claims enforcement it does not have" defect this
+ * whole roadmap exists to remove, pointed at ourselves.
+ *
+ * So the default output is a REPORT. A consumer reading "0 kernel overrides" or
+ * "2 kernel overrides, both registered" learns something true.
+ *
+ * Two things do hard-fail, because on our own authoring surface the coverage
+ * claim IS true:
+ *   1. a `Mode: replace` override on a kernel / safety-floor rule — the class is
+ *      non-replaceable, and this is mechanically decidable from the header;
+ *   2. an `extend` on one with no entry in `agents/overrides/kernel-exceptions.yml`
+ *      — tightening is allowed, going unrecorded is not.
+ *
+ * Honest limit, stated in-band: an `extend` block whose prose says "ignore
+ * everything above" passes this check. No linter reads intent. The registry
+ * entry is where a human records it, and the report is what makes it reviewable.
+ *
+ * Usage:
+ *   ./scripts-run src/scripts/lint_override_kernel_guard            # report
+ *   ./scripts-run src/scripts/lint_override_kernel_guard --json
+ *   ./scripts-run src/scripts/lint_override_kernel_guard --strict   # + hard-fails
+ *
+ * Exit codes: 0 clean · 1 violation (--strict) · 2 usage/env error.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { KERNEL_RULE_IDS, is_kernel_rule } from './_lib/kernel_rules.js';
+
+const _HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(_HERE, '..', '..');
+const OVERRIDES_RULES = path.join(REPO_ROOT, 'agents', 'overrides', 'rules');
+const REGISTRY = path.join(REPO_ROOT, 'agents', 'overrides', 'kernel-exceptions.yml');
+const RULES_DIR = path.join(REPO_ROOT, 'src', 'rules');
+
+export interface OverrideRow {
+    rule: string;
+    file: string;
+    mode: 'extend' | 'replace' | 'unknown';
+    kernel: boolean;
+    safety_floor: boolean;
+    registered: boolean;
+    cited: boolean;
+    violations: string[];
+}
+
+/** `**Mode:** \`extend\`` — the header form the override contract specifies. */
+export function parse_mode(text: string): 'extend' | 'replace' | 'unknown' {
+    const m = /^\s*\*\*Mode:\*\*\s*`?(extend|replace)`?\s*$/im.exec(text);
+    return m ? (m[1] as 'extend' | 'replace') : 'unknown';
+}
+
+/** `> Overrides: <rule> §<section> — <reason>` — the citation obligation. */
+export function has_citation(text: string): boolean {
+    return /^>\s*Overrides:\s*\S+.*—.+$/im.test(text);
+}
+
+/** Rule ids carrying `tier: safety-floor`, read from the rule sources. */
+export function safety_floor_ids(rules_dir: string): Set<string> {
+    const out = new Set<string>();
+    if (!fs.existsSync(rules_dir)) return out;
+    for (const name of fs.readdirSync(rules_dir)) {
+        if (!name.endsWith('.md')) continue;
+        const head = fs.readFileSync(path.join(rules_dir, name), 'utf-8').slice(0, 2000);
+        if (/^tier:\s*"?safety-floor"?\s*$/im.test(head)) out.add(name.replace(/\.md$/, ''));
+    }
+    return out;
+}
+
+/**
+ * Rule ids with a registered exception.
+ *
+ * Narrow reader, not a YAML dependency: the registry is a fixed two-level shape
+ * and the only fact needed is which rules appear under `exceptions:`. Anything
+ * more permissive would let a malformed registry read as coverage.
+ */
+export function registered_rules(text: string): Set<string> {
+    const out = new Set<string>();
+    let in_exceptions = false;
+    for (const raw of text.split('\n')) {
+        const line = raw.replace(/\s+$/, '');
+        if (/^exceptions:\s*$/.test(line)) { in_exceptions = true; continue; }
+        if (!in_exceptions) continue;
+        if (/^\S/.test(line)) break;
+        const rule_name = /^\s*-?\s*rule:\s*"?([a-z0-9-]+)"?\s*$/i.exec(line)?.[1];
+        if (rule_name !== undefined) out.add(rule_name);
+    }
+    return out;
+}
+
+export function audit(): OverrideRow[] {
+    if (!fs.existsSync(OVERRIDES_RULES)) return [];
+    const floor = safety_floor_ids(RULES_DIR);
+    const registered = fs.existsSync(REGISTRY)
+        ? registered_rules(fs.readFileSync(REGISTRY, 'utf-8'))
+        : new Set<string>();
+
+    const rows: OverrideRow[] = [];
+    for (const name of fs.readdirSync(OVERRIDES_RULES).sort()) {
+        if (!name.endsWith('.md')) continue;
+        const rule = name.replace(/\.md$/, '');
+        const kernel = is_kernel_rule(rule);
+        const is_floor = floor.has(rule);
+        if (!kernel && !is_floor) continue; // ordinary override — not this gate's business
+
+        const text = fs.readFileSync(path.join(OVERRIDES_RULES, name), 'utf-8');
+        const mode = parse_mode(text);
+        const cited = has_citation(text);
+        const is_registered = registered.has(rule);
+
+        const violations: string[] = [];
+        if (mode === 'replace') {
+            violations.push(
+                `\`replace\` on a ${kernel ? 'kernel' : 'safety-floor'} rule — this class may be tightened, never replaced`,
+            );
+        }
+        if (mode === 'unknown') {
+            violations.push(
+                'no readable `**Mode:**` header — an override on this class must declare its mode',
+            );
+        }
+        if (mode === 'extend' && !is_registered) {
+            violations.push(
+                `\`extend\` on a ${kernel ? 'kernel' : 'safety-floor'} rule with no entry in agents/overrides/kernel-exceptions.yml`,
+            );
+        }
+        if (!cited) {
+            violations.push('missing `> Overrides: <rule> §<section> — <reason>` citation');
+        }
+
+        rows.push({
+            rule,
+            file: path.relative(REPO_ROOT, path.join(OVERRIDES_RULES, name)),
+            mode,
+            kernel,
+            safety_floor: is_floor,
+            registered: is_registered,
+            cited,
+            violations,
+        });
+    }
+    return rows;
+}
+
+function main(argv: string[]): number {
+    const as_json = argv.includes('--json');
+    const strict = argv.includes('--strict');
+    const rows = audit();
+
+    if (as_json) {
+        process.stdout.write(JSON.stringify({ kernel_overrides: rows }, null, 2) + '\n');
+        return 0;
+    }
+
+    const bad = rows.filter((r) => r.violations.length > 0);
+
+    if (rows.length === 0) {
+        process.stdout.write(
+            `✅  override audit: 0 kernel / safety-floor overrides present ` +
+                `(${KERNEL_RULE_IDS.length} kernel rules, none overridden)\n`,
+        );
+        return 0;
+    }
+
+    const lines: string[] = [];
+    lines.push(
+        `override audit: ${rows.length} kernel / safety-floor override(s) · ` +
+            `${rows.filter((r) => r.registered).length} registered · ${bad.length} with findings`,
+    );
+    for (const r of rows) {
+        const tag = r.kernel ? 'kernel' : 'safety-floor';
+        lines.push(`  · ${r.rule} [${tag}] mode=${r.mode} registered=${r.registered ? 'yes' : 'NO'}`);
+        for (const v of r.violations) lines.push(`      ❌ ${v}`);
+    }
+    lines.push('');
+    lines.push(
+        '  Limit: this audits files under agents/overrides/. A rule can also be ' +
+            'relaxed through a persona, host config, or a direct instruction — ' +
+            'those routes are not visible here and are not claimed to be covered.',
+    );
+    process.stdout.write(lines.join('\n') + '\n');
+
+    if (strict && bad.length > 0) {
+        process.stderr.write(
+            `❌  lint_override_kernel_guard: ${bad.length} override(s) violate the non-overridable class\n`,
+        );
+        return 1;
+    }
+    return 0;
+}
+
+// Main-guard (realpath-compared, mirrors the repo convention).
+if (process.argv[1] !== undefined) {
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv1 = fs.realpathSync(path.resolve(process.argv[1]));
+        if (here === argv1) {
+            process.exit(main(process.argv.slice(2)));
+        }
+    } catch {
+        const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+        if (import.meta.url === argvUrl) {
+            process.exit(main(process.argv.slice(2)));
+        }
+    }
+}

package/src/scripts/lint_readme_serial_comma.ts

@@ -0,0 +1,169 @@
+#!/usr/bin/env tsx
+/**
+ * CI guard for the no-serial-comma house style in README.md prose.
+ *
+ * House style: prose never puts a comma directly before a final "and" / "or"
+ * (no Oxford / serial comma). `skills, commands and rules` — NOT
+ * `skills, commands, and rules`. README.md is the public claim surface for a
+ * package whose whole pitch is "every headline claim is machine-checked", so a
+ * drifting comma style in the copy is the same class of defect as a drifting
+ * number: this guard turns a one-off copy fix into a permanent build gate.
+ *
+ * Prose only. Fenced code, inline `backtick` spans, HTML comments (claim
+ * markers), URLs, and Markdown table rows are masked before matching so the
+ * guard never trips on code, data, or link syntax.
+ *
+ * Exit codes: 0 clean · 1 violation found / README missing.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const _HERE = fileURLToPath(import.meta.url);
+
+const README = 'README.md';
+
+// A comma, whitespace, then a final coordinating conjunction as a whole word.
+const SERIAL_COMMA = /,[ \t]+(and|or)\b/gi;
+
+/** Python str.splitlines() — drops the trailing empty element. */
+function _splitlines(text: string): string[] {
+    if (text === '') {
+        return [];
+    }
+    const normalised = text.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+    const parts = normalised.split('\n');
+    if (parts[parts.length - 1] === '') {
+        parts.pop();
+    }
+    return parts;
+}
+
+/**
+ * Return per-line content with everything that is not prose masked out.
+ *
+ * Order matters: HTML comments and fenced regions blank the whole line; on a
+ * surviving prose line we then blank inline backtick spans, URLs, and — for a
+ * Markdown table row — the whole line, so a `, and` inside code, a link, or a
+ * data cell never counts as a style violation.
+ */
+function _stripNoise(lines: string[]): string[] {
+    const urlRe = /https?:\/\/\S+|\(\.[\w./-]+\)/g;
+    const backtickRe = /`[^`]*`/g;
+    const cleaned: string[] = [];
+    let inFence = false;
+    let inHtml = false;
+    for (const raw of lines) {
+        const line = raw;
+        if (line.includes('<!--') && !line.includes('-->')) {
+            inHtml = true;
+        }
+        if (inHtml) {
+            cleaned.push('');
+            if (line.includes('-->')) {
+                inHtml = false;
+            }
+            continue;
+        }
+        const stripped = line.trim();
+        if (stripped.startsWith('```')) {
+            inFence = !inFence;
+            cleaned.push('');
+            continue;
+        }
+        if (inFence) {
+            cleaned.push('');
+            continue;
+        }
+        // Single-line HTML comment (e.g. a claim marker) — blank it.
+        let content = line.replace(/<!--[\s\S]*?-->/g, ' ');
+        // Markdown table row — data, not prose.
+        if (content.trim().startsWith('|')) {
+            cleaned.push('');
+            continue;
+        }
+        // Mask code spans / URLs with a word-char placeholder (not a space):
+        // a space would let a `code`-span sitting between a list comma and the
+        // final "and" / "or" collapse into a phantom ", or" (the first list
+        // comma is legitimate — only a comma *directly* before and/or counts).
+        content = content.replace(backtickRe, 'x').replace(urlRe, 'x');
+        cleaned.push(content);
+    }
+    return cleaned;
+}
+
+interface Hit {
+    line: number;
+    match: string;
+}
+
+function collect_hits(text: string): Hit[] {
+    const lines = _stripNoise(_splitlines(text));
+    const hits: Hit[] = [];
+    lines.forEach((content, idx) => {
+        SERIAL_COMMA.lastIndex = 0;
+        let m: RegExpExecArray | null;
+        while ((m = SERIAL_COMMA.exec(content)) !== null) {
+            hits.push({ line: idx + 1, match: m[0].trim() });
+            if (m.index === SERIAL_COMMA.lastIndex) {
+                SERIAL_COMMA.lastIndex += 1;
+            }
+        }
+    });
+    return hits;
+}
+
+function main(): number {
+    const quiet = process.argv.slice(2).includes('--quiet');
+    if (!fs.existsSync(README)) {
+        process.stderr.write(`error: ${README} not found\n`);
+        return 1;
+    }
+
+    const hits = collect_hits(fs.readFileSync(README, 'utf-8'));
+
+    if (hits.length > 0) {
+        process.stdout.write(
+            `FAIL  ${README}: ${hits.length} serial-comma violation(s) in prose ` +
+                `(house style: no comma before a final "and" / "or").\n`,
+        );
+        for (const { line, match } of hits) {
+            const lineStr = String(line).padStart(4, ' ');
+            process.stdout.write(`  L${lineStr}  -> "${match}"\n`);
+        }
+        process.stdout.write('\nFix: drop the comma before the final "and" / "or".\n');
+        return 1;
+    }
+
+    if (!quiet) {
+        process.stdout.write(`OK    ${README}: no serial-comma violations in prose.\n`);
+    }
+    return 0;
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    // A symlinked invocation (installed `.augment/` projection, or macOS
+    // /var → /private/var temp dirs) makes the raw URLs differ. Compare
+    // realpaths so the entry guard still fires under a symlink.
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
+    process.exit(main());
+}
+
+export { README, SERIAL_COMMA, collect_hits, main };

package/src/scripts/measure_rule_budget.ts

@@ -29,6 +29,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { artefact_roots } from './_lib/agent_src.js';
 import * as token_count from './_lib/token_count.js';
+import { KERNEL_RULE_ID_SET } from './_lib/kernel_rules.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 // src/scripts/measure_rule_budget.ts → parents[2] is the repo root (mirrors
@@ -47,18 +48,8 @@ const PER_RULE_HARD = 2_500;
 const PER_RULE_TARGET = 2_000;
 const PER_RULE_OVERRIDE_CEILING = 4_000; // Iron-Law-override ADR ceiling.
 
-// Locked kernel set — docs/contracts/kernel-membership.md § 4.
-const KERNEL_RULES: ReadonlySet<string> = new Set([
-    'agent-authority',
-    'ask-when-uncertain',
-    'commit-policy',
-    'direct-answers',
-    'language-and-tone',
-    'no-cheap-questions',
-    'non-destructive-by-default',
-    'scope-control',
-    'verify-before-complete',
-]);
+// Locked kernel set — single-sourced in _lib/kernel_rules.ts (contract: docs/contracts/kernel-membership.md § 4).
+const KERNEL_RULES: ReadonlySet<string> = KERNEL_RULE_ID_SET;
 
 export interface RuleMeasure {
     id: string;