@event4u/agent-config 8.8.0 → 8.10.0

package/src/scripts/consumer_matrix.ts

@@ -0,0 +1,353 @@
+#!/usr/bin/env tsx
+/**
+ * Consumer-proof release matrix — road-to-proof-under-real-conditions Phase 1.
+ *
+ * Exercises the PUBLISHED TARBALL the way a consumer does: pack → fresh
+ * global install (isolated prefix) → `init` into a fresh project → doctor →
+ * conformance → MCP stdio handshake → hook health → projection presence →
+ * uninstall. Optional upgrade leg: install the last published minor from the
+ * registry, then upgrade to the packed tarball and assert doctor stays green.
+ *
+ * Why this exists: the release-PR gate skips source-level matrices (soundly —
+ * a version-bump diff cannot regress source behaviour), but nothing between
+ * merge and tag exercised the tarball shape. Two published minors shipped
+ * without `src/install/` while published code imported from it; `tsx` was
+ * missing from the published package; each manifested only at publish time.
+ * Every leg here asserts exit code + an expected artifact, no LLM calls.
+ *
+ * Usage:
+ *   npx tsx src/scripts/consumer_matrix.ts [--tarball <path>] [--only leg1,leg2]
+ *       [--skip-registry] [--keep-tmp] [--json]
+ *
+ * Without --tarball the script runs `npm pack` itself (requires a built
+ * tree — `npm ci && npm run build` first; CI does this, local carve-out
+ * runs do it once).
+ *
+ * Exit codes: 0 all requested legs green · 1 leg failure · 2 usage/env.
+ */
+
+import { spawnSync, spawn } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+const PKG_NAME = '@event4u/agent-config';
+
+interface Ctx {
+    tmpRoot: string;
+    prefix: string; // isolated npm global prefix
+    projectDir: string; // fresh consumer project
+    tarball: string;
+    bin: string; // installed agent-config binary
+    keepTmp: boolean;
+    skipRegistry: boolean;
+    results: LegResult[];
+}
+
+interface LegResult {
+    leg: string;
+    ok: boolean;
+    detail: string;
+    durationMs: number;
+}
+
+function log(msg: string): void {
+    process.stderr.write(`${msg}\n`);
+}
+
+function run(
+    cmd: string,
+    args: string[],
+    opts: { cwd?: string; env?: NodeJS.ProcessEnv; timeoutMs?: number } = {},
+): { status: number; stdout: string; stderr: string } {
+    const r = spawnSync(cmd, args, {
+        cwd: opts.cwd ?? REPO_ROOT,
+        env: { ...process.env, ...opts.env },
+        encoding: 'utf8',
+        timeout: opts.timeoutMs ?? 600_000,
+        maxBuffer: 32 * 1024 * 1024,
+    });
+    return { status: r.status ?? 1, stdout: r.stdout ?? '', stderr: r.stderr ?? '' };
+}
+
+function fail(msg: string): never {
+    log(`❌  consumer-matrix: ${msg}`);
+    process.exit(1);
+}
+
+/**
+ * Env for running the installed binary against the isolated prefix.
+ * HOME is redirected into the tmp root so the simulation is a FRESH
+ * MACHINE even on a maintainer host: without this, an existing global
+ * install (~/.event4u, ~/.claude, …) trips the cross-scope drift guard
+ * inside `init` and the leg fails on developer machines while passing
+ * on clean CI runners — the opposite of what a consumer gate is for.
+ */
+function binEnv(ctx: Ctx): NodeJS.ProcessEnv {
+    const home = path.join(ctx.tmpRoot, 'home');
+    fs.mkdirSync(home, { recursive: true });
+    return {
+        PATH: `${path.join(ctx.prefix, 'bin')}${path.delimiter}${process.env.PATH ?? ''}`,
+        npm_config_prefix: ctx.prefix,
+        npm_config_cache: path.join(ctx.tmpRoot, 'npm-cache'),
+        HOME: home,
+        // Never let a maintainer checkout leak into the consumer simulation.
+        AGENT_CONFIG_DEV_MODE: '',
+    };
+}
+
+// ── legs ────────────────────────────────────────────────────────────
+
+function legPack(ctx: Ctx): string {
+    if (ctx.tarball) {
+        if (!fs.existsSync(ctx.tarball)) fail(`--tarball not found: ${ctx.tarball}`);
+        return `reused ${path.basename(ctx.tarball)}`;
+    }
+    const r = run('npm', ['pack', '--ignore-scripts', '--silent', '--pack-destination', ctx.tmpRoot]);
+    if (r.status !== 0) throw new Error(`npm pack failed: ${r.stderr.slice(-400)}`);
+    const name = r.stdout.trim().split('\n').pop() ?? '';
+    ctx.tarball = path.join(ctx.tmpRoot, name);
+    if (!fs.existsSync(ctx.tarball)) throw new Error(`packed tarball missing: ${ctx.tarball}`);
+    return path.basename(ctx.tarball);
+}
+
+function legFreshInstall(ctx: Ctx): string {
+    const r = run('npm', ['install', '-g', '--prefix', ctx.prefix, ctx.tarball], { timeoutMs: 900_000 });
+    if (r.status !== 0) throw new Error(`global install failed: ${r.stderr.slice(-600)}`);
+    ctx.bin = path.join(ctx.prefix, 'bin', 'agent-config');
+    if (!fs.existsSync(ctx.bin)) throw new Error(`installed binary missing at ${ctx.bin}`);
+    const v = run(ctx.bin, ['--version'], { env: binEnv(ctx) });
+    if (v.status !== 0) throw new Error(`--version failed (missing runtime dep in tarball?): ${v.stderr.slice(-400)}`);
+    return `bin ok, version ${v.stdout.trim()}`;
+}
+
+function legInit(ctx: Ctx): string {
+    fs.mkdirSync(ctx.projectDir, { recursive: true });
+    run('git', ['init', '-q', '.'], { cwd: ctx.projectDir });
+    // --scope=auto is the working headless consumer invocation. The bare
+    // default ('project default for backward compatibility') hard-fails on
+    // a fresh machine with '--scope=project is reserved for maintainers'
+    // (ADR-020) — a real trap this matrix documents; see
+    // docs/distribution/consumer-matrix.md § Headless default-scope trap.
+    const r = run(ctx.bin, ['init', '--tools=claude-code,cursor,windsurf', '--scope=auto', '--yes'], {
+        cwd: ctx.projectDir,
+        env: binEnv(ctx),
+        timeoutMs: 600_000,
+    });
+    if (r.status !== 0) throw new Error(`init failed: ${(r.stderr + r.stdout).slice(-600)}`);
+    // ADR-020: consumer installs are GLOBAL-only — assert the global trees.
+    const home = path.join(ctx.tmpRoot, 'home');
+    for (const p of ['.claude', '.cursor', '.codeium/windsurf', '.event4u']) {
+        if (!fs.existsSync(path.join(home, p))) throw new Error(`init did not write ~/${p}`);
+    }
+    return 'init --scope=auto wrote global ~/.claude, ~/.cursor, ~/.codeium/windsurf, ~/.event4u';
+}
+
+function legConformance(ctx: Ctx): string {
+    const r = run(ctx.bin, ['conformance'], { cwd: ctx.projectDir, env: binEnv(ctx) });
+    if (r.status !== 0) throw new Error(`conformance exit ${r.status}: ${(r.stdout + r.stderr).slice(-600)}`);
+    return 'conformance green (embeds doctor --ci + installed-and-firing checks)';
+}
+
+async function legMcpHandshake(ctx: Ctx): Promise<string> {
+    // Newline-delimited JSON-RPC per src/cli/mcp/stdio.ts.
+    return await new Promise<string>((resolve, reject) => {
+        const child = spawn(ctx.bin, ['mcp-server'], {
+            cwd: ctx.projectDir,
+            env: { ...process.env, ...binEnv(ctx) },
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        let out = '';
+        const timer = setTimeout(() => {
+            child.kill();
+            reject(new Error(`no initialize response within 20s; stdout so far: ${out.slice(0, 300)}`));
+        }, 20_000);
+        child.stdout.on('data', (d: Buffer) => {
+            out += d.toString();
+            const line = out.split('\n').find((l) => l.trim().startsWith('{'));
+            if (line) {
+                try {
+                    const msg = JSON.parse(line) as { id?: number; result?: unknown; error?: unknown };
+                    clearTimeout(timer);
+                    child.kill();
+                    if (msg.id === 1 && msg.result && !msg.error) {
+                        resolve('initialize handshake ok');
+                    } else {
+                        reject(new Error(`unexpected first message: ${line.slice(0, 300)}`));
+                    }
+                } catch {
+                    /* partial line — keep buffering */
+                }
+            }
+        });
+        child.on('error', (e) => {
+            clearTimeout(timer);
+            reject(e);
+        });
+        child.on('exit', (code) => {
+            if (out === '') {
+                clearTimeout(timer);
+                reject(new Error(`mcp-server exited (${code}) before responding`));
+            }
+        });
+        child.stdin.write(
+            `${JSON.stringify({
+                jsonrpc: '2.0',
+                id: 1,
+                method: 'initialize',
+                params: {
+                    protocolVersion: '2025-03-26',
+                    capabilities: {},
+                    clientInfo: { name: 'consumer-matrix', version: '0' },
+                },
+            })}\n`,
+        );
+    });
+}
+
+function legHooks(ctx: Ctx): string {
+    const r = run(ctx.bin, ['hooks:doctor'], { cwd: ctx.projectDir, env: binEnv(ctx) });
+    if (r.status !== 0) throw new Error(`hooks:doctor exit ${r.status}: ${(r.stdout + r.stderr).slice(-600)}`);
+    return 'hooks:doctor green';
+}
+
+function legProjections(ctx: Ctx): string {
+    const home = path.join(ctx.tmpRoot, 'home');
+    const missing = ['.cursor/rules', '.codeium/windsurf', '.claude/skills']
+        .filter((p) => !fs.existsSync(path.join(home, p)))
+        .join(', ');
+    if (missing) throw new Error(`global projection trees missing: ${missing}`);
+    return 'cursor + windsurf + claude projection trees present in global scope';
+}
+
+function legUninstall(ctx: Ctx): string {
+    const r = run(ctx.bin, ['uninstall', '--global', '--tools=claude-code,cursor,windsurf', '--force'], {
+        cwd: ctx.projectDir,
+        env: binEnv(ctx),
+    });
+    if (r.status !== 0) throw new Error(`uninstall exit ${r.status}: ${(r.stdout + r.stderr).slice(-600)}`);
+    const lock = path.join(ctx.tmpRoot, 'home', '.event4u', 'agent-config', 'installed.lock');
+    if (fs.existsSync(lock)) throw new Error(`global lockfile still present after uninstall: ${lock}`);
+    return 'uninstall --global green, lockfile removed';
+}
+
+function legUpgrade(ctx: Ctx): string {
+    if (ctx.skipRegistry) return 'skipped (--skip-registry)';
+    // Last published version from the registry (network).
+    const view = run('npm', ['view', PKG_NAME, 'version'], { timeoutMs: 120_000 });
+    if (view.status !== 0) throw new Error(`npm view failed: ${view.stderr.slice(-300)}`);
+    const published = view.stdout.trim();
+    const upPrefix = path.join(ctx.tmpRoot, 'prefix-upgrade');
+    const upProject = path.join(ctx.tmpRoot, 'project-upgrade');
+    fs.mkdirSync(upProject, { recursive: true });
+    const upHome = path.join(ctx.tmpRoot, 'home-upgrade');
+    fs.mkdirSync(upHome, { recursive: true });
+    const env = {
+        PATH: `${path.join(upPrefix, 'bin')}${path.delimiter}${process.env.PATH ?? ''}`,
+        npm_config_prefix: upPrefix,
+        npm_config_cache: path.join(ctx.tmpRoot, 'npm-cache'),
+        HOME: upHome,
+        AGENT_CONFIG_DEV_MODE: '',
+    };
+    let r = run('npm', ['install', '-g', '--prefix', upPrefix, `${PKG_NAME}@${published}`], { timeoutMs: 900_000 });
+    if (r.status !== 0) throw new Error(`registry install of ${published} failed: ${r.stderr.slice(-400)}`);
+    const bin = path.join(upPrefix, 'bin', 'agent-config');
+    r = run(bin, ['init', '--tools=claude-code', '--scope=auto', '--yes'], { cwd: upProject, env, timeoutMs: 600_000 });
+    if (r.status !== 0) throw new Error(`init on ${published} failed: ${(r.stderr + r.stdout).slice(-400)}`);
+    // Upgrade: overwrite the global install with the packed tarball.
+    r = run('npm', ['install', '-g', '--prefix', upPrefix, ctx.tarball], { timeoutMs: 900_000 });
+    if (r.status !== 0) throw new Error(`tarball upgrade failed: ${r.stderr.slice(-400)}`);
+    r = run(bin, ['conformance'], { cwd: upProject, env });
+    if (r.status !== 0) {
+        throw new Error(`conformance red after ${published} → tarball upgrade: ${(r.stdout + r.stderr).slice(-600)}`);
+    }
+    return `upgrade ${published} → packed tarball, conformance green`;
+}
+
+// ── main ────────────────────────────────────────────────────────────
+
+const LEGS: Array<{ name: string; fn: (ctx: Ctx) => string | Promise<string> }> = [
+    { name: 'pack', fn: legPack },
+    { name: 'fresh-install', fn: legFreshInstall },
+    { name: 'init', fn: legInit },
+    { name: 'conformance', fn: legConformance },
+    { name: 'mcp-handshake', fn: legMcpHandshake },
+    { name: 'hooks', fn: legHooks },
+    { name: 'projections', fn: legProjections },
+    { name: 'uninstall', fn: legUninstall },
+    { name: 'upgrade', fn: legUpgrade },
+];
+
+async function main(): Promise<number> {
+    const argv = process.argv.slice(2);
+    const getOpt = (flag: string): string | undefined => {
+        const i = argv.indexOf(flag);
+        return i >= 0 ? argv[i + 1] : undefined;
+    };
+    const only = getOpt('--only')?.split(',').map((s) => s.trim());
+    const unknownLeg = only?.find((l) => !LEGS.some((x) => x.name === l));
+    if (unknownLeg) {
+        log(`❌  unknown leg '${unknownLeg}'. Legs: ${LEGS.map((l) => l.name).join(', ')}`);
+        return 2;
+    }
+
+    const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'consumer-matrix-'));
+    const ctx: Ctx = {
+        tmpRoot,
+        prefix: path.join(tmpRoot, 'prefix'),
+        projectDir: path.join(tmpRoot, 'project'),
+        tarball: getOpt('--tarball') ?? '',
+        bin: '',
+        keepTmp: argv.includes('--keep-tmp'),
+        skipRegistry: argv.includes('--skip-registry'),
+        results: [],
+    };
+    fs.mkdirSync(ctx.prefix, { recursive: true });
+    log(`consumer-matrix · tmp ${tmpRoot} · node ${process.version}`);
+
+    let failed = false;
+    for (const leg of LEGS) {
+        if (only && !only.includes(leg.name)) continue;
+        // Legs after a hard dependency failure cannot run meaningfully.
+        if (failed) {
+            ctx.results.push({ leg: leg.name, ok: false, detail: 'skipped (earlier leg failed)', durationMs: 0 });
+            continue;
+        }
+        const t0 = Date.now();
+        try {
+            const detail = await leg.fn(ctx);
+            ctx.results.push({ leg: leg.name, ok: true, detail, durationMs: Date.now() - t0 });
+            log(`  ✅  ${leg.name} — ${detail}`);
+        } catch (err) {
+            ctx.results.push({
+                leg: leg.name,
+                ok: false,
+                detail: (err as Error).message,
+                durationMs: Date.now() - t0,
+            });
+            log(`  ❌  ${leg.name} — ${(err as Error).message}`);
+            failed = true;
+        }
+    }
+
+    if (argv.includes('--json')) {
+        process.stdout.write(`${JSON.stringify({ ok: !failed, results: ctx.results }, null, 2)}\n`);
+    }
+    if (!ctx.keepTmp) {
+        fs.rmSync(tmpRoot, { recursive: true, force: true });
+    } else {
+        log(`kept tmp: ${tmpRoot}`);
+    }
+    return failed ? 1 : 0;
+}
+
+main().then(
+    (code) => process.exit(code),
+    (err) => {
+        log(`❌  consumer-matrix crashed: ${(err as Error).stack ?? err}`);
+        process.exit(2);
+    },
+);

package/src/scripts/external_sources_denylist.json

@@ -54,7 +54,10 @@
     "gztchan",
     "amaancoderx",
     "npxskillui",
-    "\\bskillui\\b"
+    "\\bskillui\\b",
+    "\\bgraphify\\b",
+    "graphify-labs",
+    "penpax"
   ],
   "skip_paths": [
     "src/scripts/check_no_external_sources.py",

package/src/scripts/generate_index.ts

@@ -24,6 +24,7 @@ import {
     iter_commands,
     strip_source_prefix,
 } from './_lib/agent_src.js';
+import { computeStatus as domainSoundnessStatus } from './domain_soundness_status.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 
@@ -398,6 +399,7 @@ export function _render_catalog(
     const publicRules = rules.filter((r) => !INTERNAL_RULES.has(r.name));
     const publicCommands = commands.filter((c) => c.kind === 'command');
     const total = skills.length + publicRules.length + publicCommands.length + guidelines.length;
+    const ds = domainSoundnessStatus();
     const parts = [
         '# agent-config — Public Catalog',
         '',
@@ -419,8 +421,10 @@ export function _render_catalog(
         '',
         '> **Non-coding domain correctness is scoped, not proven.** The',
         '> `finance` / `founder` / `ops` / `content` skills are forged on TS/PHP',
-        '> codebases; their embedded domain heuristics are labeled `unvalidated`',
-        '> until they pass a sourced `evals/domain-truth.json` fixture',
+        `> codebases; ${ds.validated} of ${ds.total} default-surface domain skills carry a sourced`,
+        '> `evals/domain-truth.json` fixture (deterministic targets with keys from',
+        '> cited formulas, or rubric targets matching a named external practice);',
+        '> the rest are labeled `unvalidated` until they pass one',
         '> (`./scripts-run src/scripts/domain_soundness_status`). A disclaimer',
         '> floor bounds liability, not correctness — see [the proof page](proof.md).',
         '',

package/src/scripts/install-hooks.sh

@@ -42,6 +42,31 @@ if ! ./scripts-run src/scripts/check_no_conflict_markers --quiet; then
     fail=1
 fi
 
+# Changed-files static pass (typecheck + lint) — the deterministic backstop to
+# the behavioural verify-before-complete rule (#818). Catches the compile/lint
+# errors that reach remote CI "Static Checks" (e.g. TS18048). Runs only when
+# the push touches .ts, so docs-only pushes stay fast. Skip a genuine WIP push
+# with AGENT_CONFIG_SKIP_PREPUSH_STATIC=1 (the agent cannot use --no-verify).
+echo "🔍 Static check on changed TypeScript (typecheck + lint)..."
+if [ "${AGENT_CONFIG_SKIP_PREPUSH_STATIC:-}" = "1" ]; then
+    echo "⏭️  skipped via AGENT_CONFIG_SKIP_PREPUSH_STATIC=1"
+else
+    base="$(git merge-base HEAD origin/main 2>/dev/null || echo HEAD~1)"
+    changed_ts="$(git diff --name-only --diff-filter=d "$base"...HEAD -- '*.ts' 2>/dev/null || true)"
+    if [ -n "$changed_ts" ]; then
+        if ! npx eslint $changed_ts; then
+            echo "❌  ESLint failed on changed TypeScript. Fix before pushing (or AGENT_CONFIG_SKIP_PREPUSH_STATIC=1 for a WIP push)."
+            fail=1
+        fi
+        if ! npm run --silent typecheck; then
+            echo "❌  Typecheck (tsc) failed — this is the class of error remote CI 'Static Checks' catches (#818). Fix before pushing."
+            fail=1
+        fi
+    else
+        echo "⏭️  no changed .ts vs origin/main — skipping."
+    fi
+fi
+
 if [ $fail -ne 0 ]; then
     echo ""
     echo "   Push blocked — fix the failures above and re-push."

package/src/scripts/install.ts

@@ -72,6 +72,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import type * as YamlModule from 'yaml';
 
 import { build_merge_entries } from './_lib/json_pointers.js';
+import { is_claude_builtin_name } from './_lib/claude_builtin_names.js';
 import * as installed_lock from './_lib/installed_lock.js';
 import * as surface_tiers from './_lib/surface_tiers.js';
 import * as global_deploy_inventory from './_lib/global_deploy_inventory.js';
@@ -2847,15 +2848,40 @@ function _deploy_claude_desktop(
  * discovery (revert = one package release, no per-machine gating).
  * Tier-2/internal flat commands stay command files. A command whose name
  * collides with a real skill is skipped (the skill already owns `/name`).
+ *
+ * Reserved-name floor: a flat `/name` that equals a Claude Code BUILT-IN
+ * command or bundled skill (see `_lib/claude_builtin_names.ts`) would shadow
+ * the built-in — e.g. a `review` wrapper hides Claude Code's own `/review`.
+ * Such slugs get NEITHER a skill wrapper NOR a flat command file on this
+ * anchor (their nested `/cluster:sub` commands are untouched); the flat file
+ * is removed so a future upstream flat-discovery fix cannot resurrect the
+ * shadowing. The suite complements the host — it never overlays built-ins.
  */
 const _CLAUDE_FLAT_WRAPPER_EXTRA = new Set(['commit']); // essential; absent from the manifest
 export function _apply_claude_flat_command_wrappers(
     anchor: string,
     package_root: string,
     current_files: Set<string>,
-): { wrapped: string[]; collisions: string[] } {
+): { wrapped: string[]; collisions: string[]; reserved: string[] } {
     const wrapped: string[] = [];
     const collisions: string[] = [];
+    const reserved: string[] = [];
+    // Reserved-name sweep over ALL flat command files (any tier): a name
+    // shadowing a Claude Code built-in never ships on the claude-code anchor.
+    const commands_dir = path.join(anchor, 'commands');
+    let flat_entries: string[] = [];
+    try {
+        flat_entries = fs.readdirSync(commands_dir).filter((f) => f.endsWith('.md'));
+    } catch {
+        // No commands dir → nothing to sweep.
+    }
+    for (const fname of flat_entries.sort()) {
+        const slug = fname.slice(0, -'.md'.length);
+        if (!is_claude_builtin_name(slug)) continue;
+        fs.rmSync(path.join(commands_dir, fname), { force: true });
+        current_files.delete(`commands/${fname}`);
+        reserved.push(slug);
+    }
     // Tier-0/1 visible command slugs from the locked discovery manifest.
     const eligible = new Set<string>(_CLAUDE_FLAT_WRAPPER_EXTRA);
     try {
@@ -2892,7 +2918,7 @@ export function _apply_claude_flat_command_wrappers(
         current_files.add(`skills/${slug}/SKILL.md`);
         wrapped.push(slug);
     }
-    return { wrapped, collisions };
+    return { wrapped, collisions, reserved };
 }
 
 function _deploy_global_content(
@@ -2949,6 +2975,13 @@ function _deploy_global_content(
                         'skill wrappers (Claude Code flat-command discovery workaround)',
                 );
             }
+            if (res.reserved.length > 0 && !state.QUIET) {
+                info(
+                    `  claude-code: ${res.reserved.length} flat command(s) withheld — name is a ` +
+                        `Claude Code built-in (${res.reserved.join(', ')}); nested /cluster:sub ` +
+                        'commands remain available',
+                );
+            }
         }
 
         const missing_targets = _verify_deploy_targets(anchor, plan);

package/src/scripts/lint_agent_skill_names.ts

@@ -14,6 +14,7 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { command_slug } from './_lib/agent_src.js';
+import { is_claude_builtin_name } from './_lib/claude_builtin_names.js';
 
 const SCRIPTS_DIR = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.dirname(path.dirname(SCRIPTS_DIR));
@@ -97,6 +98,18 @@ function frontmatterNameFromFile(p: string): string | null {
     return _frontmatter_name(fs.readFileSync(p, 'utf-8'));
 }
 
+const USER_INVOCABLE_FALSE_RE = /^user-invocable:\s*false\s*$/m;
+
+/** True when the SKILL.md opts out of slash registration (`user-invocable: false`). */
+export function _opts_out_of_slash(text: string): boolean {
+    if (!text.startsWith('---')) {
+        return false;
+    }
+    const end = text.indexOf('\n---', 3);
+    const block = end !== -1 ? text.slice(3, end) : text;
+    return USER_INVOCABLE_FALSE_RE.test(block);
+}
+
 export function _spec_violation(name: string): string | null {
     if (name.length > MAX_NAME_LEN) {
         return `longer than ${MAX_NAME_LEN} chars`;
@@ -178,6 +191,22 @@ export function check_skills(): string[] {
                     'requires the folder name to match the `name:` field',
             );
         }
+        // Reserved-name floor: a skill named after a Claude Code built-in
+        // command / bundled skill shadows the built-in when projected as
+        // `/name` (e.g. a `mcp` skill hides Claude Code's own /mcp dialog).
+        // Opting out of slash registration (`user-invocable: false`) keeps
+        // the skill model-loadable while the host retains the /name.
+        // Reserved set: src/scripts/_lib/claude_builtin_names.ts.
+        if (
+            is_claude_builtin_name(dirname) &&
+            !_opts_out_of_slash(fs.readFileSync(md, 'utf-8'))
+        ) {
+            violations.push(
+                `${rel}: \`${dirname}\` is a Claude Code built-in command name — ` +
+                    'add `user-invocable: false` (model-only invocation) or rename ' +
+                    'the skill; the suite must never shadow a host built-in',
+            );
+        }
     }
     return violations;
 }