@event4u/agent-config 9.29.0 → 9.31.0

package/src/scripts/install-hooks.sh

@@ -145,7 +145,7 @@ fi
 # Roadmap dashboard sync — only fires when staged changes touch a roadmap
 # file or the dashboard itself, so unrelated commits stay fast.
 if git diff --cached --name-only | grep -qE '^agents/roadmaps(-progress\.md|/)'; then
-    ./scripts-run .augment/scripts/update_roadmap_progress --check
+    ./scripts-run src/scripts/roadmap_progress_hook --check
     rstatus=$?
     if [ $rstatus -ne 0 ]; then
         # The check fails for THREE distinct reasons and prints the real one

package/src/scripts/language_mirror_hook.ts

@@ -72,7 +72,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
-import { atomic_write_json } from "./hooks/state_io.js";
+import { atomic_write_json, atomic_write_text, is_replay_mode } from "./hooks/state_io.js";
 import { readHookStdin } from "./hooks/hook_stdin.js";
 import { humanAuthoredLead, isSyntheticPrompt } from "./_lib/prompt_shape.js";
 
@@ -87,6 +87,27 @@ const EXIT_WARN = 2;
 
 export const STATE_FILE = path.join("agents", "state", "language-mirror.json");
 
+/**
+ * Marker written at `pre_compact` and cleared by the single `post_tool_use`
+ * re-emit that follows it (round-5 § 6.1). Its existence — not a counter — is
+ * what bounds the re-injection to ONE per compaction event.
+ */
+export const PIN_LOST_DIR = path.join("agents", "state", "language-mirror.pin-lost");
+
+/**
+ * Per-SESSION marker path. R2 finding 10: a single shared marker made the
+ * mechanism cross-talk between concurrent sessions — the normal shape for this
+ * repo's worktree workflow. Session B's next `post_tool_use` consumed the marker
+ * session A's compaction had set, so A never got the one re-emit that is the
+ * whole point of the mechanism, and B got a pin notice derived from whichever
+ * session last wrote the shared state. An empty id degrades to a literal
+ * bucket rather than colliding silently.
+ */
+export function pinLostMarker(session_id: string): string {
+  const safe = (session_id || "unknown-session").replace(/[^A-Za-z0-9._-]/g, "_");
+  return path.join(PIN_LOST_DIR, `${safe}.marker`);
+}
+
 type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
 type JsonObject = { [k: string]: JsonValue };
 
@@ -380,6 +401,103 @@ function _extractPrompt(payload: JsonObject): string {
   return "";
 }
 
+/** The envelope's session id, or a literal bucket when the host sends none. */
+function _sessionId(envelope: JsonObject): string {
+  const v = envelope["session_id"];
+  return typeof v === "string" && v.trim() !== "" ? v : "unknown-session";
+}
+
+/**
+ * Record that compaction is about to drop the context copy of the pin.
+ *
+ * R2 finding 14: this used to write with a raw `mkdirSync` + `writeFileSync`,
+ * bypassing both conventions the surrounding code follows — the module's own
+ * atomic writer, and the `is_replay_mode()` guard that keeps a replayed event
+ * from mutating live state. A replayed compaction wrote the marker for real.
+ */
+/**
+ * The pre-R2 layout wrote a single FILE at the path that is now a DIRECTORY.
+ * A consumer upgrading with a leftover legacy marker — compaction happened, no
+ * `post_tool_use` followed — hits `EEXIST` on the mkdir and `ENOTDIR` on the
+ * write (reproduced against Node), which the catch below swallows as
+ * "observability only". The failure would then be silent AND permanent for that
+ * root: `existsSync` always false, so the mechanism is dead with no diagnostic.
+ * One unlink at the moment of collision, and only when the path is a file.
+ */
+function _migrateLegacyMarker(consumer_root: string): void {
+  const legacy = path.join(consumer_root, PIN_LOST_DIR);
+  try {
+    if (fs.statSync(legacy).isFile()) {
+      fs.rmSync(legacy, { force: true });
+    }
+  } catch {
+    // Absent, already a directory, or unreadable — nothing to migrate.
+  }
+}
+
+export function _setPinLost(consumer_root: string, session_id: string): void {
+  if (is_replay_mode()) return;
+  _migrateLegacyMarker(consumer_root);
+  try {
+    atomic_write_text(path.join(consumer_root, pinLostMarker(session_id)), new Date().toISOString());
+  } catch {
+    // Observability only — a failed marker write costs one un-restored pin,
+    // never a broken turn.
+  }
+}
+
+export function _pinLost(consumer_root: string, session_id: string): boolean {
+  try {
+    return fs.existsSync(path.join(consumer_root, pinLostMarker(session_id)));
+  } catch {
+    return false;
+  }
+}
+
+function _clearPinLost(consumer_root: string, session_id: string): void {
+  // R2 round 2, finding 8: the replay guard covered only the WRITE. A replayed
+  // `post_tool_use` therefore deleted a live marker it was forbidden to create,
+  // and the real session lost the single re-emit this whole mechanism exists to
+  // deliver — replay destroying live state while blocked from writing it, which
+  // is worse than either direction alone.
+  if (is_replay_mode()) return;
+  try {
+    fs.rmSync(path.join(consumer_root, pinLostMarker(session_id)), { force: true });
+  } catch {
+    // If it cannot be cleared the next tool call re-emits once more. One
+    // duplicate line is the failure mode; a loop is not, because the marker
+    // is only ever SET by a compaction event.
+  }
+}
+
+/**
+ * The `post_tool_use` half. Emits the pin exactly once per compaction event
+ * and only when a pin actually exists — an absent or undetermined pin is not
+ * an obligation, and inventing one here would be worse than the gap.
+ */
+export function _reEmitAfterCompaction(consumer_root: string, session_id: string): number {
+  if (!_pinLost(consumer_root, session_id)) {
+    return EXIT_ALLOW;
+  }
+  const previous = _loadState(path.join(consumer_root, STATE_FILE));
+  const language = previous.language as Verdict | undefined;
+  const source: PinSource = previous.source === "system-locale" ? "system-locale" : "prompt";
+  // Clear FIRST: if the write below throws, the marker must not survive to
+  // re-fire on every subsequent tool call — that is the shape § 6.2 refuses.
+  _clearPinLost(consumer_root, session_id);
+  if (language !== "de" && language !== "en") {
+    return EXIT_ALLOW;
+  }
+  process.stdout.write(
+    `${JSON.stringify({
+      decision: "warn",
+      reason: noticeText(language, source),
+      additional_context: pinText(language, source),
+    })}\n`,
+  );
+  return EXIT_WARN;
+}
+
 export function run(
   stdin_text: string,
   options: { consumer_root: string; env?: NodeJS.ProcessEnv },
@@ -397,6 +515,30 @@ export function run(
   }
 
   const payload = _isObject(envelope["payload"]) ? (envelope["payload"] as JsonObject) : envelope;
+
+  // round-5 § 6.1 — the compaction boundary.
+  //
+  // 4 of the 23 post-merge violations happened with NO pin in context: a
+  // `compact_boundary` fired and the first violation followed 26 seconds
+  // later. Compaction removes the context copy of the pin, not this hook's
+  // state file — so this is a state defect with a deterministic fix, aimed
+  // only at the subset where the pin was measurably MISSING, never at the 19
+  // where it was measurably ignored.
+  //
+  // The guard IS the design, and is not optional: `pre_compact` sets a
+  // marker, `post_tool_use` re-emits once while it is set and clears it. That
+  // is one extra injection per compaction EVENT. A re-pin on every tool call
+  // is what § 6.2 refuses — "the same failed mechanism running more often" —
+  // and this marker is the entire difference between the two.
+  const event = typeof envelope["event"] === "string" ? envelope["event"] : "";
+  if (event === "pre_compact") {
+    _setPinLost(options.consumer_root, _sessionId(envelope));
+    return EXIT_ALLOW;
+  }
+  if (event === "post_tool_use") {
+    return _reEmitAfterCompaction(options.consumer_root, _sessionId(envelope));
+  }
+
   const prompt = _extractPrompt(payload);
   if (!prompt) {
     return EXIT_ALLOW;

package/src/scripts/lint_decision_impact.ts

@@ -41,6 +41,7 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { parse as parseYaml } from 'yaml';
 
+import { GateLedger } from './_lib/gate_ledger.js';
 import { runGateCli, runSelfTest } from './_lib/gate_self_test.js';
 import { reportScanned } from './_lib/scan_scope.js';
 
@@ -188,15 +189,26 @@ export function main(argv?: readonly string[]): number {
         names = [];
     }
 
+    // Per-rule completeness: every listed rule reaches exactly one outcome, so
+    // the frontmatter-less `continue` below is a named skip, not a silent one.
+    const ledger = new GateLedger('lint_decision_impact');
+    ledger.plan(names);
     const violations: Violation[] = [];
     let scanned = 0;
     for (const n of names) {
         const fm = frontmatterOf(fs.readFileSync(path.join(dir, n), 'utf-8'));
         if (fm === null) {
+            ledger.skip(n, 'not_applicable_kind');
             continue;
         }
         scanned += 1;
-        violations.push(...checkRule(n.slice(0, -3), fm));
+        const found = checkRule(n.slice(0, -3), fm);
+        violations.push(...found);
+        if (found.length > 0) {
+            ledger.fail(n, `${String(found.length)} issue(s)`);
+        } else {
+            ledger.complete(n);
+        }
     }
 
     if (violations.length > 0) {
@@ -214,6 +226,7 @@ export function main(argv?: readonly string[]): number {
         );
     }
 
+    ledger.report();
     reportScanned({
         gate: 'lint_decision_impact',
         scanned,

package/src/scripts/lint_hook_manifest.ts

@@ -318,6 +318,87 @@ function _check_dead_concerns(
   }
 }
 
+/**
+ * Role-axis validation (road-to-token-economy-dispatch Phase 2). Errors on:
+ *   - a `roles` block that is not a mapping of role → { drop: [names] }
+ *   - a drop entry naming an unknown concern
+ *   - a drop entry naming a concern bound to ANY platform's `pre_tool_use`
+ *     slot — the safety-guard slot is undroppable (Phase 2.3: "the manifest
+ *     diff must show zero pre_tool_use guard removals, CI-checked"). The
+ *     dispatcher also refuses pre_tool_use drops at runtime; this check
+ *     makes the attempt a red build instead of a silent no-op.
+ */
+export function _check_roles(
+  manifest: YamlObject,
+  concernNames: Set<string>,
+  errors: string[],
+): void {
+  const rolesRaw = manifest["roles"];
+  if (rolesRaw === undefined || rolesRaw === null) {
+    return; // no role axis — valid (every chain is the orchestrator default)
+  }
+  if (!isObject(rolesRaw)) {
+    errors.push(`roles: must be a mapping, got ${pyTypeName(rolesRaw)}`);
+    return;
+  }
+  // Concerns bound on any platform's pre_tool_use slot — the undroppable set.
+  const guardBound = new Set<string>();
+  const platformsRaw = manifest["platforms"];
+  if (isObject(platformsRaw)) {
+    for (const block of Object.values(platformsRaw)) {
+      if (!isObject(block)) continue;
+      const pre = block["pre_tool_use"];
+      if (Array.isArray(pre)) {
+        for (const n of pre) {
+          if (typeof n === "string") guardBound.add(n);
+        }
+      }
+    }
+  }
+  for (const [role, spec] of Object.entries(rolesRaw)) {
+    if (!isObject(spec)) {
+      errors.push(`roles.${role}: must be a mapping, got ${pyTypeName(spec)}`);
+      continue;
+    }
+    const drop = spec["drop"];
+    if (drop === undefined || drop === null) {
+      continue; // a role without a drop list is a no-op entry — allowed
+    }
+    if (!Array.isArray(drop)) {
+      errors.push(`roles.${role}: 'drop' must be a list, got ${pyTypeName(drop)}`);
+      continue;
+    }
+    for (const name of drop) {
+      if (typeof name !== "string" || !concernNames.has(name)) {
+        errors.push(`roles.${role}: drop entry '${String(name)}' is not a known concern`);
+        continue;
+      }
+      if (guardBound.has(name)) {
+        errors.push(
+          `roles.${role}: drop entry '${name}' is bound to a pre_tool_use slot — ` +
+            `safety guards are undroppable on every role`,
+        );
+      }
+      // Severity-based twin of the slot check (review hardening 2026-08-10):
+      // a fail_closed or non-advisory concern is guard-shaped regardless of
+      // which slot it binds to — dropping one from a role chain would be a
+      // safety removal wearing an economy label.
+      const concernsRaw = manifest["concerns"];
+      const spec = isObject(concernsRaw) ? concernsRaw[name] : undefined;
+      if (isObject(spec)) {
+        const advisory = String(spec["severity"] ?? "").trim().toLowerCase() === "advisory";
+        const failClosed = spec["fail_closed"] === true;
+        if (failClosed || !advisory) {
+          errors.push(
+            `roles.${role}: drop entry '${name}' is ${failClosed ? "fail_closed" : "not severity: advisory"} — ` +
+              `only advisory, fail-open concerns may be role-dropped`,
+          );
+        }
+      }
+    }
+  }
+}
+
 export function lint(manifestPath: string, strict: boolean): number {
   if (!_isFile(manifestPath)) {
     process.stderr.write(
@@ -342,6 +423,7 @@ export function lint(manifestPath: string, strict: boolean): number {
   const warnings: string[] = [];
   const concernNames = _check_concerns(manifest, errors);
   const bound = _check_platforms(manifest, concernNames, errors, warnings);
+  _check_roles(manifest, concernNames, errors);
   _check_aliases(manifest, errors);
   _check_orphan_trampolines(manifest, errors);
   _check_dead_concerns(concernNames, bound, warnings);

package/src/scripts/lint_readme_serial_comma.ts

@@ -22,6 +22,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { assertWatchlistResolves, DeadScopeError } from './_lib/scan_scope.js';
 
+// ledger-exempt: single-artefact prose scan — the whole corpus is the one file README.md, and every hit is a line offset inside it that the failure output already prints in full; there is no enumerated target collection whose members could be silently continued past, and the file-absent / wrong-cwd case is a hard failure via assertWatchlistResolves rather than a green run over zero targets.
 const _HERE = fileURLToPath(import.meta.url);
 
 const README = 'README.md';

package/src/scripts/lint_rule_enforcement_declaration.ts

@@ -0,0 +1,347 @@
+#!/usr/bin/env node
+/**
+ * `enforced_by`-declaration ratchet — a NEW rule states its enforcement, or
+ * states the gap; only the legacy set may stay silent.
+ *
+ * The enforcement-coverage number moved backwards across 9.23→9.29 (13.5% →
+ * 12.9%) for exactly one reason: rules were added faster than backstops, and
+ * nothing required a new rule to even *declare* where it stands. Coverage
+ * itself cannot be gated (whether a backstop is buildable is a per-rule
+ * judgment), but the *declaration* can: `enforced_by:` accepts an honest
+ * `none`, so requiring the key costs a new rule's author one line of truth,
+ * never a mechanism.
+ *
+ * Ratchet shape (the established baseline-the-legacy pattern):
+ *   - The 84 rules that predate this gate are recorded in
+ *     `src/config/rule-enforcement-baseline.json`. They stay legal while
+ *     undeclared; the list may only shrink.
+ *   - A rule NOT in the baseline must carry `enforced_by:` — a validator/
+ *     hook/test/observer reference, or the explicit `none`.
+ *   - A rule declaring `none` must also state the gap in its body (the
+ *     `enforced_by: none` honesty convention the existing none-rules use) —
+ *     a frontmatter-only `none` nobody reads is a silent gap again.
+ *   - A baseline entry whose rule gained a declaration (or was deleted) must
+ *     leave the baseline in the same change — a stale entry is a freed slot
+ *     a later silent rule could hide in.
+ *
+ * Deliberately NOT checked here: whether a declared validator resolves, is
+ * wired, or can fail a build — that is `check_enforcement_coverage`'s job
+ * (resolution), and `check_backstop_debt`'s (red backstops). This gate owns
+ * the declaration boundary only, on `src/rules/` only — gate scripts and
+ * their `// ledger-exempt:` markers are a different surface
+ * (`check_gate_completeness`) and are not read here.
+ *
+ * **Where the baseline lives, and why it ships.** `src/config/` is a directory
+ * entry in `package.json`'s `files[]`, so `rule-enforcement-baseline.json` is in
+ * the published tarball alongside its nine siblings — `gate-violation-baselines`,
+ * the four `*-budget` files, and the rest. All ten are repo-internal gate state:
+ * this gate is their consumer, it ships too (via `src/scripts/`), and in a
+ * consumer checkout it finds no `src/rules/` and does nothing. That is inert, not
+ * orphaned, and it is the pre-existing shape rather than something this file
+ * introduced — an automated review flagged it as "ships into dist with no
+ * consumer", which is doubly wrong: the file is not in `dist/` at all, and the
+ * consumer is this script. Whether ten repo-internal baselines belong in the
+ * tarball is a real packaging question; it is one decision about ten files, not a
+ * carve-out for the tenth.
+ *
+ * CLI contract: exit 0 = clean, 1 = a finding (or dead scan root), 2 = usage.
+ * `--quiet` mutes the clean-path line; `--root <dir>` re-roots for fixtures;
+ * `--write-baseline` records the current undeclared set (bootstrap/re-anchor —
+ * a deliberate maintainer act, never CI).
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { read_frontmatter } from './check_enforcement_coverage.js';
+import { GateLedger } from './_lib/gate_ledger.js';
+import { runGateCli, runSelfTest } from './_lib/gate_self_test.js';
+import { is_kernel_rule } from './_lib/kernel_rules.js';
+import { DeadScopeError, reportScanned } from './_lib/scan_scope.js';
+
+const GATE = 'lint_rule_enforcement_declaration';
+
+const QUIET = process.argv.slice(2).includes('--quiet');
+
+const _HERE = path.resolve(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+const RULES_RELATIVE = path.join('src', 'rules');
+const BASELINE_RELATIVE = path.join('src', 'config', 'rule-enforcement-baseline.json');
+
+function _rootOverride(argv: readonly string[]): string | null {
+    const i = argv.indexOf('--root');
+    const value = i === -1 ? undefined : argv[i + 1];
+    return value === undefined ? null : path.resolve(value);
+}
+
+/** enforced_by as declared, normalised to a string array; null = absent. */
+function _declaration(fm: Record<string, string | string[]>): string[] | null {
+    const raw = fm['enforced_by'];
+    if (raw === undefined) return null;
+    const list = Array.isArray(raw) ? raw : [raw];
+    return list.length === 0 ? null : list;
+}
+
+/** The body must state a `none` gap in prose — the honesty convention. */
+function _bodyStatesNone(text: string): boolean {
+    const end = text.indexOf('\n---\n', 4);
+    const body = end === -1 ? text : text.slice(end + 5);
+    return body.includes('enforced_by: none') || body.includes('`enforced_by: none`');
+}
+
+function _readBaseline(root: string): string[] | null {
+    try {
+        const parsed: unknown = JSON.parse(fs.readFileSync(path.join(root, BASELINE_RELATIVE), 'utf-8'));
+        if (!Array.isArray(parsed) || !parsed.every((e) => typeof e === 'string')) return null;
+        return parsed as string[];
+    } catch {
+        return null;
+    }
+}
+
+interface Findings {
+    findings: string[];
+    undeclared: string[];
+}
+
+function _scan(root: string, baseline: ReadonlySet<string>, ledger: GateLedger | null): Findings {
+    const rulesDir = path.join(root, RULES_RELATIVE);
+    const files = fs
+        .readdirSync(rulesDir)
+        .filter((f) => f.endsWith('.md'))
+        .sort();
+    ledger?.plan(files);
+
+    const findings: string[] = [];
+    const undeclared: string[] = [];
+    const seen = new Set<string>();
+
+    for (const file of files) {
+        seen.add(file);
+        const text = fs.readFileSync(path.join(rulesDir, file), 'utf-8');
+        const decl = _declaration(read_frontmatter(text));
+
+        if (decl === null) {
+            undeclared.push(file);
+            if (baseline.has(file)) {
+                ledger?.outOfScope(file, 'declared_exemption');
+                continue;
+            }
+            const f =
+                `src/rules/${file}  declares no \`enforced_by:\`. A new rule states its enforcement ` +
+                `(validator:/hook:/test:/observer:) or states the gap (\`none\` + a body line saying so). ` +
+                `The baseline covers only rules that predate this gate.`;
+            findings.push(f);
+            ledger?.fail(file, f);
+            continue;
+        }
+
+        // Kernel rules are exempt from the body-prose convention, derived from
+        // _lib/kernel_rules.ts (never a hardcoded list) so the exemption closes
+        // itself the moment a rule leaves the kernel — the same self-closing
+        // shape validate_frontmatter uses for obligation_frequency. Their
+        // projected bytes are stability-gated, so requiring a prose line here
+        // would force an un-editable edit.
+        if (decl.includes('none') && !_bodyStatesNone(text) && !is_kernel_rule(file)) {
+            const f =
+                `src/rules/${file}  declares \`enforced_by: none\` in frontmatter but never states the gap ` +
+                `in its body — the honesty convention is one prose line naming \`enforced_by: none\`, so a ` +
+                `reader of the rule sees the gap, not only a machine.`;
+            findings.push(f);
+            ledger?.fail(file, f);
+            continue;
+        }
+
+        ledger?.complete(file);
+    }
+
+    for (const entry of [...baseline].sort()) {
+        if (!seen.has(entry)) {
+            findings.push(
+                `${BASELINE_RELATIVE}  baseline entry \`${entry}\` names no existing rule — remove it in the ` +
+                    `same change that renamed/deleted the rule. A stale entry is a freed slot a later ` +
+                    `undeclared rule could silently occupy.`,
+            );
+            continue;
+        }
+        if (!undeclared.includes(entry)) {
+            findings.push(
+                `${BASELINE_RELATIVE}  baseline entry \`${entry}\` now declares \`enforced_by:\` — remove it ` +
+                    `from the baseline in the same change. The list may only shrink.`,
+            );
+        }
+    }
+
+    return { findings, undeclared };
+}
+
+/** Prove against the real CLI that the ratchet rejects what it must. */
+export function selfTest(): number {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'lred-selftest-'));
+    const declared = '---\ntype: "auto"\nenforced_by:\n  - "validator:src/scripts/example.ts"\n---\n\n# R\n\nBody.\n';
+    const noneHonest =
+        '---\ntype: "auto"\nenforced_by:\n  - "none"\n---\n\n# R\n\nThis rule ships `enforced_by: none` — the obligation is model-carried.\n';
+    const noneSilent = '---\ntype: "auto"\nenforced_by:\n  - "none"\n---\n\n# R\n\nBody with no gap statement.\n';
+    const silent = '---\ntype: "auto"\n---\n\n# R\n\nBody.\n';
+
+    const seed = (name: string, rules: Record<string, string>, baseline: string[]): string => {
+        const root = path.join(tmp, name);
+        fs.mkdirSync(path.join(root, RULES_RELATIVE), { recursive: true });
+        fs.mkdirSync(path.join(root, 'src', 'config'), { recursive: true });
+        for (const [file, text] of Object.entries(rules)) {
+            fs.writeFileSync(path.join(root, RULES_RELATIVE, file), text, 'utf-8');
+        }
+        fs.writeFileSync(path.join(root, BASELINE_RELATIVE), `${JSON.stringify(baseline, null, 2)}\n`, 'utf-8');
+        return root;
+    };
+    const run = (cwd: string): number =>
+        runGateCli(REPO_ROOT, `src/scripts/${GATE}.ts`, ['--quiet', '--root', cwd], REPO_ROOT);
+
+    try {
+        return runSelfTest({
+            gate: GATE,
+            minCases: 6,
+            minRejectCases: 4,
+            cases: [
+                {
+                    name: 'a declared new rule and a baselined legacy rule pass',
+                    expect: 'accept',
+                    run: () => run(seed('clean', { 'a.md': declared, 'legacy.md': silent }, ['legacy.md'])),
+                },
+                {
+                    name: 'an honest none (frontmatter + body gap line) passes',
+                    expect: 'accept',
+                    run: () => run(seed('none-honest', { 'a.md': noneHonest }, [])),
+                },
+                {
+                    name: 'a NEW rule without enforced_by is rejected',
+                    expect: 'reject',
+                    run: () => run(seed('new-silent', { 'a.md': silent }, [])),
+                },
+                {
+                    name: 'a none declaration without the body gap line is rejected',
+                    expect: 'reject',
+                    run: () => run(seed('none-silent', { 'a.md': noneSilent }, [])),
+                },
+                {
+                    name: 'a stale baseline entry (rule deleted/renamed) is rejected',
+                    expect: 'reject',
+                    run: () => run(seed('stale', { 'a.md': declared }, ['gone.md'])),
+                },
+                {
+                    name: 'a baseline entry whose rule gained a declaration is rejected until removed',
+                    expect: 'reject',
+                    run: () => run(seed('shrink', { 'a.md': declared }, ['a.md'])),
+                },
+                {
+                    name: 'a dead scan root is rejected, never passed as nothing-to-check',
+                    expect: 'reject',
+                    run: () => run(path.join(tmp, 'dead-root-does-not-exist')),
+                },
+            ],
+        });
+    } finally {
+        fs.rmSync(tmp, { recursive: true, force: true });
+    }
+}
+
+function main(): number {
+    const argv = process.argv.slice(2);
+    if (argv.includes('--self-test')) {
+        return selfTest();
+    }
+    const root = _rootOverride(argv) ?? REPO_ROOT;
+
+    const rulesDir = path.join(root, RULES_RELATIVE);
+    let isDir = false;
+    try {
+        isDir = fs.statSync(rulesDir).isDirectory();
+    } catch {
+        isDir = false;
+    }
+    if (!isDir) {
+        process.stderr.write(`❌  ${GATE}: rules dir not found at ${RULES_RELATIVE} — the scan root is dead.\n`);
+        return 1;
+    }
+
+    if (argv.includes('--write-baseline')) {
+        const { undeclared } = _scan(root, new Set(), null);
+        fs.writeFileSync(
+            path.join(root, BASELINE_RELATIVE),
+            `${JSON.stringify(undeclared, null, 2)}\n`,
+            'utf-8',
+        );
+        process.stdout.write(`${GATE}: baseline written — ${undeclared.length} legacy undeclared rule(s).\n`);
+        return 0;
+    }
+
+    const baseline = _readBaseline(root);
+    if (baseline === null) {
+        process.stderr.write(
+            `❌  ${GATE}: ${BASELINE_RELATIVE} missing or not a string array — run --write-baseline once ` +
+                `(a deliberate maintainer act) or restore the committed file.\n`,
+        );
+        return 1;
+    }
+
+    const ledger = new GateLedger(GATE);
+    const { findings } = _scan(root, new Set(baseline), ledger);
+
+    try {
+        reportScanned({
+            gate: GATE,
+            scanned: fs.readdirSync(rulesDir).filter((f) => f.endsWith('.md')).length,
+            units: 'rule file(s)',
+            roots: [RULES_RELATIVE],
+        });
+    } catch (e) {
+        if (e instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${e.message}\n`);
+            return 1;
+        }
+        throw e;
+    }
+    ledger.report();
+
+    if (findings.length > 0) {
+        for (const f of findings) {
+            process.stderr.write(`❌  ${f}\n`);
+        }
+        return 1;
+    }
+    if (!QUIET) {
+        process.stdout.write(
+            `✅  ${GATE}: every non-baselined rule declares its enforcement (baseline: ${baseline.length}, shrink-only).\n`,
+        );
+    }
+    return 0;
+}
+
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+function _isCliEntry(): boolean {
+    if (typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__) {
+        return false;
+    }
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv1 = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv1;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    process.exit(main());
+}
+
+export { GATE, REPO_ROOT, BASELINE_RELATIVE, main };