@event4u/agent-config 14.18.0 → 14.20.0

package/src/scripts/check_enforcement_denominator.ts

@@ -39,9 +39,26 @@
  * Escape hatch: `<!-- enforcement-count-ok: <reason> -->` on the line, reason
  * mandatory. A bare marker stays a finding.
  *
+ * THE SECOND HALF — the projection owes the split. Exempting the generated file
+ * settles WHERE the number may be published; it says nothing about whether the
+ * published number is readable. `undeclared` quoted bare reads as a backlog
+ * somebody forgot to wire, and for nine of them that is not what it is:
+ * `block_kernel_rule_writes` refuses an `enforced_by` write on a kernel rule
+ * with no agent-accessible override, so those cannot declare one at all. The
+ * resolver has always computed `kernel_denied`; the published line dropped it
+ * and appended the word `yet`, promising a future that does not exist for that
+ * nine. So a line in the sanctioned projection that states an `undeclared`
+ * figure without its kernel-denied split is the SAME class of failure as a
+ * hand-written count elsewhere: a figure the reader cannot resolve.
+ *
+ * This deliberately does NOT check the split's value, for the same reason the
+ * first half does not check the count's — the resolver is the only source, and
+ * a value comparison here would be a second place the number lives.
+ *
  * Exit codes:
- *   0 — no hand-written enforcement count in the published corpus
- *   1 — at least one (or a marker with no reason)
+ *   0 — no hand-written enforcement count in the published corpus, and every
+ *       published `undeclared` figure carries its kernel-denied split
+ *   1 — at least one (or a marker with no reason, or a split-less figure)
  *   2 — the gate could not run (dead scan scope, bad args)
  */
 import * as fs from 'node:fs';
@@ -57,8 +74,8 @@ const _HERE = fileURLToPath(import.meta.url);
 const DEFAULT_ROOT = path.join(path.dirname(_HERE), '..', '..');
 const SELF = 'src/scripts/check_enforcement_denominator.ts';
 
-const SELF_TEST_MIN_CASES = 7;
-const SELF_TEST_MIN_REJECT = 3;
+const SELF_TEST_MIN_CASES = 10;
+const SELF_TEST_MIN_REJECT = 5;
 
 /** Roots walked, repo-relative. */
 const SCAN_ROOTS = ['docs', 'README.md'] as const;
@@ -82,6 +99,19 @@ const MARKER = 'enforcement-count-ok:';
 const ENFORCEMENT_KEYWORDS =
     /undeclared|enforced_by|enforcement coverage|carry a backstop|backstop that fails/;
 
+/**
+ * Shapes that state the `undeclared` figure itself. Narrower than
+ * {@link COUNT_SHAPES} on purpose: this is the ONE figure whose split is
+ * load-bearing, and a wider net would demand the split beside `blocking`.
+ */
+const UNDECLARED_FIGURE_SHAPES: readonly RegExp[] = [
+    /\b\d+\s+undeclared\b/i,
+    /\bundeclared\s+rules?\s*\(\s*\d+/i,
+];
+
+/** The split that makes the figure readable. Presence is checked, never value. */
+const SPLIT_TOKEN = /kernel[-_]denied/i;
+
 const COUNT_SHAPES: readonly RegExp[] = [
     /\b\d+\s+of\s+\d+\s+(?:governed\s+)?rules?\b/,
     /\b\d+\s+(?:governed\s+)?rules?\b/,
@@ -93,8 +123,12 @@ export interface Finding {
     file: string;
     line: number;
     excerpt: string;
-    /** `raw` — an unmarked count. `bare-marker` — a marker with no reason. */
-    kind: 'raw' | 'bare-marker';
+    /**
+     * `raw` — an unmarked count. `bare-marker` — a marker with no reason.
+     * `missing-split` — the projection states `undeclared` without its
+     * kernel-denied split.
+     */
+    kind: 'raw' | 'bare-marker' | 'missing-split';
 }
 
 function markerOn(line: string): 'none' | 'bare' | 'reasoned' {
@@ -123,6 +157,30 @@ export function scanText(relPath: string, text: string): Finding[] {
     return out;
 }
 
+/**
+ * The projection's own obligation: every line stating an `undeclared` figure
+ * carries the kernel-denied split. Run INSTEAD of {@link scanText} on a
+ * generated file — that file is allowed to state the number, and is the only
+ * one that owes the split.
+ */
+export function scanGenerated(relPath: string, text: string): Finding[] {
+    const out: Finding[] = [];
+    const lines = text.split('\n');
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i] ?? '';
+        if (!UNDECLARED_FIGURE_SHAPES.some((re) => re.test(line))) continue;
+        if (SPLIT_TOKEN.test(line)) continue;
+        if (markerOn(line) === 'reasoned') continue;
+        out.push({
+            file: relPath,
+            line: i + 1,
+            excerpt: line.trim().slice(0, 120),
+            kind: 'missing-split',
+        });
+    }
+    return out;
+}
+
 /** `true` when the file declares itself generated — i.e. it IS the projection. */
 export function isGenerated(text: string): boolean {
     return text.split('\n', GENERATED_HEAD_LINES).join('\n').includes(GENERATED_MARKER);
@@ -177,7 +235,13 @@ export function check(root: string): { code: number; findings: Finding[]; scanne
         for (const rel of files) {
             const text = fs.readFileSync(path.join(root, rel), 'utf-8');
             if (isGenerated(text)) {
-                ledger.complete(rel);
+                const split = scanGenerated(rel, text);
+                if (split.length > 0) {
+                    findings.push(...split);
+                    ledger.fail(rel, `${String(split.length)} undeclared figure(s) without the split`);
+                } else {
+                    ledger.complete(rel);
+                }
                 continue;
             }
             const found = scanText(rel, text);
@@ -259,8 +323,21 @@ export function selfTest(): number {
                 }),
         },
         {
-            name: "accepts the resolver's own generated projection",
+            name: "accepts the resolver's own generated projection when it carries the split",
             expect: 'accept',
+            run: () =>
+                run({
+                    'docs/proof.md':
+                        `<!-- ${GENERATED_MARKER} src/scripts/build_proof.ts -->\n\n` +
+                        '120 rules · 15 blocking · 86 undeclared — of which 9 kernel-denied.\n',
+                }),
+        },
+        {
+            // DENIAL POLARITY for the split half. Same file, same exemption, the
+            // split removed: the projection is allowed to state the number and is
+            // still a finding when it states it bare.
+            name: 'rejects the generated projection when the kernel-denied split is removed',
+            expect: 'reject',
             run: () =>
                 run({
                     'docs/proof.md':
@@ -268,6 +345,26 @@ export function selfTest(): number {
                         '120 rules · 15 blocking · 86 undeclared (no enforced_by yet).\n',
                 }),
         },
+        {
+            name: 'rejects a bare "Undeclared rules (N)" restatement in the projection',
+            expect: 'reject',
+            run: () =>
+                run({
+                    'docs/proof.md':
+                        `<!-- ${GENERATED_MARKER} src/scripts/build_proof.ts -->\n\n` +
+                        'Undeclared rules (86) carry no row.\n',
+                }),
+        },
+        {
+            name: 'accepts a generated line about enforcement that states no undeclared figure',
+            expect: 'accept',
+            run: () =>
+                run({
+                    'docs/proof.md':
+                        `<!-- ${GENERATED_MARKER} src/scripts/build_proof.ts -->\n\n` +
+                        '120 rules · 15 blocking · the resolver prints its own frame.\n',
+                }),
+        },
         {
             name: 'accepts a dated ADR record (docs/decisions/ is excluded)',
             expect: 'accept',
@@ -318,12 +415,25 @@ export function main(argv?: readonly string[]): number {
     if (code === 2) return 2;
 
     if (findings.length > 0) {
-        process.stdout.write('❌  hand-written enforcement count(s) in a published doc:\n\n');
+        process.stdout.write('❌  unresolvable enforcement figure(s) in a published doc:\n\n');
         for (const f of findings) {
             const why =
-                f.kind === 'bare-marker' ? `\`${MARKER}\` with no reason` : 'hand-written count';
+                f.kind === 'bare-marker'
+                    ? `\`${MARKER}\` with no reason`
+                    : f.kind === 'missing-split'
+                      ? 'published `undeclared` figure with no kernel-denied split'
+                      : 'hand-written count';
             process.stdout.write(`  ${f.file}:${String(f.line)} — ${why}\n      ${f.excerpt}\n`);
         }
+        if (findings.some((f) => f.kind === 'missing-split')) {
+            process.stdout.write(
+                '\nThe projection may state the `undeclared` figure — it is the only surface\n' +
+                    'that may — but not bare. Nine of those rules are kernel-denied:\n' +
+                    '`block_kernel_rule_writes` refuses an `enforced_by` write with no\n' +
+                    'agent-accessible override, so for them there is no *yet*. Print\n' +
+                    "`summary.kernel_denied` on the same line (`build_proof.ts` § 4b does).\n",
+            );
+        }
         process.stdout.write(
             '\nExactly one enforcement denominator is quotable, and it comes from\n' +
                 '`check_enforcement_coverage` — which resolves rather than counts, and prints\n' +
@@ -362,4 +472,4 @@ if (_isCliEntry() || process.argv[1] === _HERE) {
     process.exit(main());
 }
 
-export { SCAN_ROOTS, EXCLUDED_PREFIXES, MARKER };
+export { SCAN_ROOTS, EXCLUDED_PREFIXES, MARKER, SPLIT_TOKEN, UNDECLARED_FIGURE_SHAPES };

package/src/scripts/check_finding_dispositions.ts

@@ -50,12 +50,22 @@
  * not override either, so in CI the local tag list is EMPTY. See releaseStatus
  * for the asymmetry and the remote fallback.
  *
+ * AN EMPTY LEDGER MUST SAY WHY IT IS EMPTY. The released/unreleased split above
+ * closed the missing-file half; it left the other half open, because
+ * `findings: []` still passed while asserting nothing. A writer could satisfy
+ * the gate by creating an empty file, which is the same silence wearing the
+ * shape of a record. `no_findings_reason` is now required whenever the file
+ * exists and the array is empty — see empty_ledger_problem for what the reason
+ * has to distinguish.
+ *
  * A future reader changing allowEmpty below is the person this is addressed to:
- * the EMPTY_VALID waiver still covers a ledger that exists and is empty, and an
- * unreleased version. It no longer covers a released version with no ledger.
+ * the EMPTY_VALID waiver now covers only an EXPLAINED empty ledger and an
+ * unreleased version. It covers neither a released version with no ledger nor an
+ * empty ledger with no reason.
  *
  * Exit codes: 0 complete · 1 missing/incomplete dispositions (an absent ledger
- * for a RELEASED version is one of them) · 2 usage error, schema error, or an
+ * for a RELEASED version and an unexplained empty ledger are both among them) ·
+ * 2 usage error, schema error, or an
  * undeterminable release status. Deliberately NOT fail-open: this script never calls a model;
  * a broken ledger file is a hard error, not a neutral skip.
  */
@@ -65,7 +75,7 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 
-import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+import { DeadScopeError, reportScanned } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
@@ -91,6 +101,8 @@ export interface Ledger {
     schema_version: number;
     release: string;
     findings: LedgerFinding[];
+    /** Why the finding set is empty. Required when it is; see empty_ledger_problem. */
+    no_findings_reason?: string;
 }
 
 /** Mirrors self_review_gate.classifyBlocking — security/claim × critical/high. */
@@ -136,6 +148,36 @@ export function missing_dispositions(findings: readonly LedgerFinding[]): string
     return problems;
 }
 
+/**
+ * An empty finding set must say why it is empty.
+ *
+ * `findings: []` and a missing file made the same claim to every reader — "nothing
+ * to disposition" — and only one of them is evidence. Worse, they collapse two
+ * states that differ entirely: a review that ran and reported nothing, and a review
+ * that never ran at all. The reason field is what forces the writer to pick one and
+ * makes the pick falsifiable, so a fabricated empty ledger has to assert something
+ * a reader can check rather than merely occupy the path the gate looks at.
+ *
+ * Applies ONLY to a ledger file that exists. An absent ledger on an unreleased
+ * version is the normal in-flight state and has nothing to carry a reason.
+ */
+export function empty_ledger_problem(
+    ledger: Pick<Ledger, 'findings' | 'no_findings_reason'>,
+): string | null {
+    if (ledger.findings.length > 0) {
+        return null;
+    }
+    if ((ledger.no_findings_reason ?? '').trim() !== '') {
+        return null;
+    }
+    return (
+        'the ledger exists with an empty `findings` array and no `no_findings_reason`. '
+        + 'An unexplained empty ledger is indistinguishable from an absent one — state '
+        + 'whether the review ran and reported nothing, or did not run, and how a reader '
+        + 'can check that.'
+    );
+}
+
 export type ReleaseStatus = 'released' | 'unreleased' | 'undeterminable';
 export type RemoteReleaseAnswer = 'released' | 'unreleased' | 'unavailable';
 
@@ -410,6 +452,19 @@ function main(argv: readonly string[]): number {
         }
     }
 
+    // An existing ledger that records nothing must say why. Checked here rather
+    // than in the schema because the requirement is conditional on the finding
+    // count, which the repo's Draft-07 subset validator cannot express.
+    if (fs.existsSync(ledgerPath)) {
+        const emptyProblem = empty_ledger_problem(ledger);
+        if (emptyProblem !== null) {
+            process.stderr.write(
+                `❌  ${path.relative(REPO_ROOT, ledgerPath)}: ${emptyProblem}\n`,
+            );
+            return 1;
+        }
+    }
+
     // Scope declaration, not a scope guard. The ledger is written per release by
     // `--ingest`, so "no <release>.json" is the normal state of a release whose
     // self-review reported nothing — the gate's own success line says so. That
@@ -418,7 +473,7 @@ function main(argv: readonly string[]): number {
     // durable trigger for an un-ingested finding is `--pr` mode, which compares
     // the ledger against what the self-review actually reported.
     try {
-        assertScanned({
+        reportScanned({
             gate: 'check_finding_dispositions',
             scanned: ledger.findings.length,
             units: 'recorded finding(s)',
@@ -426,11 +481,13 @@ function main(argv: readonly string[]): number {
             allowEmpty:
                 'EMPTY_VALID: zero recorded findings IS the pass state for a release whose '
                 + 'self-review reported none — the ledger file is created on first --ingest, so a '
-                + 'clean release legitimately has no <version>.json. NARROWED: this no longer '
+                + 'clean release legitimately has no <version>.json. NARROWED TWICE: it no longer '
                 + 'covers a RELEASED version with no ledger, which returns 1 above on the '
-                + 'released/unreleased split; the waiver now covers an empty-but-present ledger '
-                + 'and an unreleased version. Un-ingested findings on an in-flight release are '
-                + 'caught by --pr (unrecorded_findings), never by this count.',
+                + 'released/unreleased split, and it no longer covers an empty ledger that does '
+                + 'not say why it is empty, which returns 1 above via empty_ledger_problem. What '
+                + 'remains is an EXPLAINED empty ledger and an unreleased version. Un-ingested '
+                + 'findings on an in-flight release are caught by --pr (unrecorded_findings), '
+                + 'never by this count.',
         });
     } catch (exc) {
         if (exc instanceof DeadScopeError) {

package/src/scripts/check_gate_coverage.ts

@@ -113,6 +113,21 @@ export interface GateSpec {
    * `pending` is reported instead of hidden.
    */
   unavailable_exit?: number;
+  /**
+   * Repo-relative workflow file this row's `argv` is pinned to.
+   *
+   * Rule 2 of this manifest — CI-IDENTICAL INVOCATION — was an instruction to
+   * the author and nothing else: the guard runs whatever `argv` says and never
+   * looked at how CI calls the gate, so a row could drift from its workflow, or
+   * the workflow step could be deleted outright, and this file would keep
+   * reporting healthy coverage for a gate CI no longer runs.
+   *
+   * Opt-in per row, because most gates here have several CI invocations with
+   * different arguments and one `argv` cannot be identical to all of them. Where
+   * a row DOES name a workflow, that workflow must contain an invocation of the
+   * gate whose argument list equals `argv` exactly.
+   */
+  ci_invocation?: string;
   note?: string;
 }
 
@@ -191,6 +206,9 @@ export function load_manifest(file = MANIFEST): GateSpec[] {
       ...(e['unavailable_exit'] === undefined
         ? {}
         : { unavailable_exit: _require_int(e['unavailable_exit'], id, i) }),
+      ...(e['ci_invocation'] === undefined
+        ? {}
+        : { ci_invocation: _require_str(e['ci_invocation'], 'ci_invocation', id, i) }),
       ...(e['note'] === undefined ? {} : { note: String(e['note']) }),
       ...(e['canary'] === undefined ? {} : { canary: _require_canary(e['canary'], id, i) }),
       ...(e['no_canary_reason'] === undefined
@@ -405,6 +423,73 @@ function report_negative_control_inventory(specs: readonly GateSpec[]): void {
   }
 }
 
+/**
+ * Invocations of `src/scripts/<id>` in a workflow, each as its argument list.
+ *
+ * Deliberately a text scan rather than a YAML walk: an invocation lives inside a
+ * `run:` block scalar, so parsing the workflow buys nothing and costs the ability
+ * to see a call split across a line continuation, which is how the release job
+ * writes this very gate. Backslash-newline joins are folded before matching for
+ * that reason.
+ */
+export function ci_invocations(workflowText: string, id: string): string[][] {
+  const folded = workflowText.replace(/\\\n\s*/gu, ' ');
+  const out: string[][] = [];
+  const re = new RegExp(String.raw`src/scripts/${id}(?![A-Za-z0-9_])([^\n]*)`, 'gu');
+  for (const m of folded.matchAll(re)) {
+    out.push(
+      (m[1] ?? '')
+        .trim()
+        .split(/\s+/u)
+        .filter((t) => t !== ''),
+    );
+  }
+  return out;
+}
+
+/**
+ * The row's `argv` must be reproducible from the workflow it pins.
+ *
+ * Both directions are failures and they are different defects: no matching
+ * invocation means the manifest probes the gate in a way CI does not (or CI
+ * stopped calling it at all), which is the drift rule 2 asks for and nothing
+ * enforced.
+ */
+export function ci_invocation_problem(
+  workflowText: string,
+  id: string,
+  argv: readonly string[],
+): string | null {
+  const found = ci_invocations(workflowText, id);
+  if (found.length === 0) {
+    return `no invocation of src/scripts/${id} — the workflow does not call this gate`;
+  }
+  const want = argv.join(' ');
+  if (found.some((a) => a.join(' ') === want)) {
+    return null;
+  }
+  return (
+    `argv [${want}] matches no invocation there; the workflow calls it as ` +
+    found.map((a) => `[${a.join(' ')}]`).join(', ')
+  );
+}
+
+/** Rows whose `ci_invocation` no longer describes their workflow. */
+export function ci_invocation_drift(specs: readonly GateSpec[], repoRoot = REPO_ROOT): string[] {
+  const problems: string[] = [];
+  for (const s of specs) {
+    if (s.ci_invocation === undefined) continue;
+    const file = path.join(repoRoot, s.ci_invocation);
+    if (!fs.existsSync(file)) {
+      problems.push(`${s.id}: ci_invocation ${s.ci_invocation} does not exist`);
+      continue;
+    }
+    const problem = ci_invocation_problem(fs.readFileSync(file, 'utf-8'), s.id, s.argv);
+    if (problem !== null) problems.push(`${s.id}: ${s.ci_invocation} — ${problem}`);
+  }
+  return problems;
+}
+
 export function main(argv: readonly string[]): number {
   const wantJson = argv.includes('--format') && argv[argv.indexOf('--format') + 1] === 'json';
   const listOnly = argv.includes('--list');
@@ -523,12 +608,23 @@ export function main(argv: readonly string[]): number {
     );
   }
   report_negative_control_inventory(specs);
+  const drift = ci_invocation_drift(specs);
+  for (const d of drift) {
+    process.stdout.write(`  ❌ ${d}\n`);
+  }
   const hardening = report_hardening_ratchet();
   const selfTest = report_self_test_ratchet();
   if (failed.length > 0) {
     process.stdout.write(`❌  ${String(failed.length)} gate(s) failed the coverage floor.\n`);
     return 1;
   }
+  if (drift.length > 0) {
+    process.stdout.write(
+      `❌  ${String(drift.length)} row(s) declare a ci_invocation their workflow no longer matches — ` +
+        `the manifest probes the gate differently from CI, or CI stopped calling it.\n`,
+    );
+    return 1;
+  }
   if (hardening !== 0) {
     return hardening;
   }

package/src/scripts/check_mcp_doc_drift.ts

@@ -0,0 +1,217 @@
+#!/usr/bin/env tsx
+/**
+ * The documented MCP client snippets must match the entry the installer writes.
+ *
+ * `docs/mcp-server.md` documented an absolute `tsx` path in four snippets while
+ * the installer wrote an `npx` invocation, so a consumer who followed the docs
+ * and a consumer who ran the installer landed on two different servers — for
+ * long enough that nobody noticed either was wrong.
+ *
+ * Scope is two literals in this tree. It asserts NOTHING about host behaviour:
+ * that a host reads the file at all is a separate question this gate does not
+ * touch and must not be cited for.
+ *
+ * Exit codes: 0 in sync · 1 drift · 2 a source is missing or unreadable.
+ */
+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 { runGateCli, runSelfTest } from './_lib/gate_self_test.js';
+import { MCP_PACKAGE_NAME, MCP_SERVER_KEY, mcpBridgeEntry } from './_lib/mcp_bridge.js';
+import { reportScanned } from './_lib/scan_scope.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+const DOC_REL = 'docs/mcp-server.md';
+
+/**
+ * A snippet is any fenced block naming our server key.
+ *
+ * Deliberately not a JSON/YAML parse: the four documented clients use three
+ * different shapes (`command` as a string, `command` as an object with `path`,
+ * and a YAML list), and a parser per shape would drift from the docs as surely
+ * as the docs drifted from the installer. The two facts that matter — the
+ * runner and the package spec — are the same literals in all three.
+ */
+export function snippetBlocks(text: string): string[] {
+    const out: string[] = [];
+    const lines = text.split('\n');
+    let open: string[] | null = null;
+    for (const line of lines) {
+        if (line.startsWith('```')) {
+            if (open === null) open = [];
+            else {
+                const body = open.join('\n');
+                if (body.includes(MCP_SERVER_KEY) || body.includes('mcpServers')) out.push(body);
+                open = null;
+            }
+            continue;
+        }
+        if (open !== null) open.push(line);
+    }
+    return out;
+}
+
+export interface DocFinding {
+    snippet: number;
+    reason: string;
+}
+
+export function checkSnippets(text: string, packageRoot: string): DocFinding[] {
+    const server = (mcpBridgeEntry(packageRoot)['mcpServers'] as Record<string, unknown>)[
+        MCP_SERVER_KEY
+    ] as { command: string; args: string[] };
+    const findings: DocFinding[] = [];
+
+    snippetBlocks(text).forEach((body, i) => {
+        // Only blocks that actually configure the server — a block that merely
+        // mentions `mcpServers` in prose is not a client configuration.
+        if (!body.includes('command')) return;
+        if (!body.includes(server.command)) {
+            findings.push({
+                snippet: i + 1,
+                reason: `does not use the installer's runner \`${server.command}\``,
+            });
+        }
+        if (!body.includes(MCP_PACKAGE_NAME)) {
+            findings.push({
+                snippet: i + 1,
+                reason: `does not name the package \`${MCP_PACKAGE_NAME}\``,
+            });
+        }
+        // QUOTED, not a substring: `mcp-server` contains `serve`, so a plain
+        // `includes` reported a snippet as current after the entry had been
+        // changed to `serve` and the doc had not — measured, on this gate's own
+        // sensitivity probe. Every documented shape quotes the token.
+        const subcommand = server.args[server.args.length - 1] as string;
+        if (!body.includes(`"${subcommand}"`)) {
+            findings.push({
+                snippet: i + 1,
+                reason: `does not invoke \`${subcommand}\``,
+            });
+        }
+        if (body.includes('node_modules/.bin/tsx')) {
+            findings.push({
+                snippet: i + 1,
+                reason: 'documents an absolute tsx path the installer never writes',
+            });
+        }
+    });
+    return findings;
+}
+
+function main(): number {
+    if (process.argv.slice(2).includes('--self-test')) return selfTest();
+    const rootIdx = process.argv.indexOf('--root');
+    const root = rootIdx === -1 ? ROOT : (process.argv[rootIdx + 1] ?? ROOT);
+    const doc = path.join(root, DOC_REL);
+    if (!fs.existsSync(doc)) {
+        process.stderr.write(`❌  ${DOC_REL} not found under ${root}\n`);
+        return 2;
+    }
+    const text = fs.readFileSync(doc, 'utf-8');
+    const blocks = snippetBlocks(text).filter((b) => b.includes('command'));
+    const findings = checkSnippets(text, root);
+
+    reportScanned({
+        gate: 'check_mcp_doc_drift',
+        scanned: blocks.length,
+        units: 'documented client snippet(s)',
+        roots: [DOC_REL],
+    });
+
+    if (findings.length > 0) {
+        for (const f of findings) {
+            process.stdout.write(`❌  ${DOC_REL} snippet ${String(f.snippet)}: ${f.reason}\n`);
+        }
+        process.stdout.write(
+            `\n${String(findings.length)} finding(s). The documented entry and the entry ` +
+                '`mcpBridgeEntry()` writes have drifted apart.\n',
+        );
+        return 1;
+    }
+    process.stdout.write(
+        `✅  check_mcp_doc_drift: ${String(blocks.length)} documented snippet(s) match the ` +
+            'installer entry.\n',
+    );
+    return 0;
+}
+
+/** One rejecting case per way the two literals can drift. */
+function selfTest(): number {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'mcp-doc-drift-'));
+    const write = (name: string, doc: string): string => {
+        const dir = path.join(tmp, name);
+        fs.mkdirSync(path.join(dir, 'docs'), { recursive: true });
+        fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({ version: '1.0.0' }));
+        fs.writeFileSync(path.join(dir, DOC_REL), doc, 'utf-8');
+        return dir;
+    };
+    const run = (root: string): number =>
+        runGateCli(ROOT, 'src/scripts/check_mcp_doc_drift.ts', ['--root', root], root);
+
+    const good = [
+        '```json',
+        '{ "mcpServers": { "agent-config": {',
+        '  "command": "npx",',
+        '  "args": ["-y", "@event4u/agent-config@<version>", "mcp-server"] } } }',
+        '```',
+        '',
+    ].join('\n');
+    const tsxPath = good.replace('"npx"', '"/abs/agent-config/node_modules/.bin/tsx"');
+    const noPackage = good.replace('@event4u/agent-config@<version>', 'some-other-package');
+    const noSubcommand = good.replace('"mcp-server"', '"serve"');
+
+    try {
+        return runSelfTest({
+            gate: 'check_mcp_doc_drift',
+            minCases: 4,
+            minRejectCases: 3,
+            cases: [
+                {
+                    name: 'an absolute tsx path is rejected',
+                    expect: 'reject',
+                    run: () => run(write('tsx', tsxPath)),
+                },
+                {
+                    name: 'a snippet naming another package is rejected',
+                    expect: 'reject',
+                    run: () => run(write('pkg', noPackage)),
+                },
+                {
+                    name: 'a snippet invoking another subcommand is rejected',
+                    expect: 'reject',
+                    run: () => run(write('sub', noSubcommand)),
+                },
+                {
+                    name: 'the installer-shaped snippet passes',
+                    expect: 'accept',
+                    run: () => run(write('good', good)),
+                },
+            ],
+        });
+    } finally {
+        fs.rmSync(tmp, { recursive: true, force: true });
+    }
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) return false;
+    if (import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) return true;
+    try {
+        return (
+            fs.realpathSync(fileURLToPath(import.meta.url)) ===
+            fs.realpathSync(path.resolve(process.argv[1]))
+        );
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
+    process.exit(main());
+}
+
+export { DOC_REL, main };