@event4u/agent-config 8.3.0 → 8.4.0

package/src/scripts/condense.ts

@@ -1810,65 +1810,96 @@ export function generate_subagent_host_contexts(): number {
     return count;
 }
 
+// Bootstrap shim (road-to-install-path-convergence): the Claude Code plugin
+// ships ZERO content skills. It carries only hooks/hooks.json (byte-identical
+// to the managed settings block, so Claude Code dedupes) plus this single
+// pointer skill whose description names the canonical install command.
+export const PLUGIN_POINTER_SLUG = 'install-agent-config';
+export const PLUGIN_POINTER_SKILL_BODY = `---
+name: install-agent-config
+description: >-
+  Install or upgrade the event4u agent-config suite. This marketplace plugin
+  is a bootstrap shim — it ships hooks plus this pointer only; ALL skills,
+  rules, and commands are installed via \`npx -y @event4u/agent-config init\`.
+  Use when the user asks to install, set up, or upgrade agent-config, or
+  wonders why this plugin contains no other skills.
+---
+
+# Install agent-config
+
+This plugin is a **bootstrap shim**. It exists so the marketplace listing
+stays discoverable and existing plugin installs keep working hooks — the
+content surface (skills, rules, commands, personas) is distributed as a
+file projection, not through this plugin.
+
+## Install (canonical, one command)
+
+\`\`\`bash
+npx -y @event4u/agent-config init
+\`\`\`
+
+The installer writes the full content projection, registers the dispatcher
+hooks as a managed block in \`~/.claude/settings.json\` (byte-identical to
+this plugin's hooks, so nothing double-fires), and keeps everything
+upgradeable via \`agent-config upgrade\`.
+
+## Already installed both?
+
+Run \`agent-config doctor\` to check for duplicate surfaces, and
+\`agent-config converge\` to clean up consented duplicates.
+`;
+
 export function generate_plugin_command_skills(): number {
     if (!_isDir(path.join(MODULE_STATE.PROJECT_ROOT, 'src', 'domains'))) {
         return 0;
     }
     _mkdirp(MODULE_STATE.PLUGIN_SKILLS_DIR);
 
-    let skill_names = new Set<string>();
-    if (_exists(MODULE_STATE.SKILLS_SOURCE)) {
-        skill_names = new Set(
-            _iterdirSorted(MODULE_STATE.SKILLS_SOURCE)
-                .filter((p) => _isDir(p))
-                .map((p) => path.basename(p)),
-        );
+    // 1. Materialize the pointer skill (idempotent overwrite-on-drift).
+    const pointer_dir = path.join(MODULE_STATE.PLUGIN_SKILLS_DIR, PLUGIN_POINTER_SLUG);
+    _mkdirp(pointer_dir);
+    const pointer_file = path.join(pointer_dir, 'SKILL.md');
+    if (_isSymlink(pointer_file)) {
+        fs.unlinkSync(pointer_file);
     }
-
-    const current_slugs = new Set<string>();
-    let count = 0;
-    for (const [source_file, slug] of iterCommands()) {
-        if (skill_names.has(slug)) {
-            continue;
-        }
-        current_slugs.add(slug);
-        const skill_dir = path.join(MODULE_STATE.PLUGIN_SKILLS_DIR, slug);
-        _mkdirp(skill_dir);
-        const skill_file = path.join(skill_dir, 'SKILL.md');
-        if (_existsOrSymlink(skill_file)) {
-            fs.unlinkSync(skill_file);
-        }
-        const rel_path = _relativeToPosix(source_file, MODULE_STATE.PROJECT_ROOT);
-        const rel_target = path.join('../../..', rel_path);
-        fs.symlinkSync(rel_target, skill_file);
-        count += 1;
+    if (!_isFile(pointer_file) || fs.readFileSync(pointer_file, 'utf-8') !== PLUGIN_POINTER_SKILL_BODY) {
+        fs.writeFileSync(pointer_file, PLUGIN_POINTER_SKILL_BODY);
     }
 
+    // 2. Prune every other skill dir so the tree converges to shim shape
+    //    from any prior state. Removable = every entry is a symlink (the
+    //    generated projection shape — SKILL.md and optional evals links into
+    //    src/), or the dir holds only a single SKILL.md file (the old sweep's
+    //    rule). Dirs with real extra files are never touched.
     let removed_dirs = 0;
     for (const item of _iterdirSorted(MODULE_STATE.PLUGIN_SKILLS_DIR)) {
         if (!_isDirNoFollow(item) || _isSymlink(item)) {
             continue;
         }
-        if (current_slugs.has(path.basename(item))) {
+        if (path.basename(item) === PLUGIN_POINTER_SLUG) {
             continue;
         }
-        const skill_md = path.join(item, 'SKILL.md');
-        if (_isSymlink(skill_md) || _isFile(skill_md)) {
-            const entries = _iterdirSorted(item);
-            if (entries.length === 1 && path.basename(entries[0] as string) === 'SKILL.md') {
-                fs.unlinkSync(skill_md);
-                fs.rmdirSync(item);
-                removed_dirs += 1;
+        const entries = _iterdirSorted(item);
+        const all_symlinks = entries.length > 0 && entries.every((e) => _isSymlink(e));
+        const single_skill_md =
+            entries.length === 1 &&
+            path.basename(entries[0] as string) === 'SKILL.md' &&
+            _isFile(entries[0] as string);
+        if (all_symlinks || single_skill_md) {
+            for (const e of entries) {
+                fs.unlinkSync(e);
             }
+            fs.rmdirSync(item);
+            removed_dirs += 1;
         }
     }
 
-    let msg = `  ✅  Created ${count} command entries in .claude-plugin/skills/`;
+    let msg = '  ✅  Plugin skills: bootstrap shim (1 pointer skill) in .claude-plugin/skills/';
     if (removed_dirs) {
-        msg += ` (${removed_dirs} stale dirs removed)`;
+        msg += ` (${removed_dirs} content entries pruned)`;
     }
     info(msg);
-    return count;
+    return 1;
 }
 
 export function generate_persona_symlinks(): number {

package/src/scripts/hook_manifest.yaml

@@ -125,17 +125,26 @@ concerns:
     script: src/scripts/wrapper_freshness_hook.ts
     args: []
     fail_closed: false
+  # road-to-install-path-convergence Phase 4 — duplicate-surface probe.
+  # Reads src/config/surface-matrix.yml, existence-checks declared duplicate
+  # classes, nudges ONCE per day (state: agents/runtime/state/
+  # surface-probe.json). Fail-open, never blocking; silent when clean or
+  # when install.auto_converge is already set.
+  surface-probe:
+    script: src/scripts/surface_probe_hook.ts
+    args: []
+    fail_closed: false
 
 platforms:
   augment:
-    session_start:    [chat-history, hot-context, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness]
+    session_start:    [chat-history, hot-context, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness, surface-probe]
     session_end:      [chat-history]
     stop:             [chat-history, hot-context, verify-before-complete]
     pre_tool_use:     [block-no-verify, rtk-wrap, design-slop]
     post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan]
 
   claude:
-    session_start:    [chat-history, hot-context, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness]
+    session_start:    [chat-history, hot-context, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness, surface-probe]
     session_end:      [chat-history]
     stop:             [chat-history, hot-context, verify-before-complete]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff]
@@ -157,7 +166,7 @@ platforms:
   # Decision matrix + upstream blockers tracked in
   # agents/settings/contexts/chat-history-platform-hooks.md § Cowork.
   cowork:
-    session_start:    [chat-history, hot-context, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness]
+    session_start:    [chat-history, hot-context, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness, surface-probe]
     session_end:      [chat-history]
     stop:             [chat-history, hot-context, verify-before-complete]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff]
@@ -172,7 +181,7 @@ platforms:
   # IDE-only — CLI-only users fall back to /checkpoint per
   # agents/settings/contexts/chat-history-platform-hooks.md.
   cursor:
-    session_start:      [chat-history, hot-context, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness]
+    session_start:      [chat-history, hot-context, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness, surface-probe]
     session_end:        [chat-history]
     stop:               [chat-history, hot-context, verify-before-complete]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff]
@@ -187,7 +196,7 @@ platforms:
   # both map to session_start. TaskCancel maps to stop because the
   # session is interrupted with partial state (mirrors Augment Stop).
   cline:
-    session_start:      [chat-history, hot-context, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness]
+    session_start:      [chat-history, hot-context, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness, surface-probe]
     session_end:        [chat-history]
     stop:               [chat-history, hot-context, verify-before-complete]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff]
@@ -206,7 +215,7 @@ platforms:
   # surface to record verification commands; documented limitation).
   # minimal-safe-diff is omitted entirely on Windsurf for the same reason.
   windsurf:
-    session_start:      [chat-history, hot-context, first-run-gate, onboarding-gate, verify-before-complete, profile-staleness, wrapper-freshness]
+    session_start:      [chat-history, hot-context, first-run-gate, onboarding-gate, verify-before-complete, profile-staleness, wrapper-freshness, surface-probe]
     stop:               [chat-history, hot-context, verify-before-complete]
     user_prompt_submit: [chat-history, verify-before-complete]
 
@@ -221,7 +230,7 @@ platforms:
   # turn-check semantics. AfterAgent fires when the agent loop ends
   # — this is our `stop` slot.
   gemini:
-    session_start:      [chat-history, hot-context, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness]
+    session_start:      [chat-history, hot-context, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness, surface-probe]
     session_end:        [chat-history]
     stop:               [chat-history, hot-context, verify-before-complete]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff]

package/src/scripts/lint_marketplace.ts

@@ -6,16 +6,20 @@
  * Wave 4b). Mirrors the Python CLI contract exactly: same cwd-relative scan
  * roots, finding messages, stdout output, and exit codes.
  *
- * Validates the Claude Code Plugin Marketplace manifest against the canonical
- * manifest shape:
+ * Validates the Claude Code Plugin Marketplace manifest against the
+ * BOOTSTRAP-SHIM shape (road-to-install-path-convergence): the plugin ships
+ * ONLY hooks plus a single install-pointer skill — content skills are
+ * distributed via the npx file projection, never through this plugin.
  *
  *   - Required top-level fields: name, owner, metadata, plugins
  *   - owner must have name + email
  *   - metadata must have description + version
  *   - metadata.version must match package.json (single source of truth)
- *   - every plugins[].skills[] entry must exist on disk and carry a SKILL.md
- *   - every SKILL.md on disk under the committed skill sources must be listed
- *     in some plugin's skills[] (drift detection)
+ *   - the union of plugins[].skills[] must be EXACTLY the pointer skill
+ *     (./.claude-plugin/skills/install-agent-config) — a repopulated
+ *     content-skill list FAILS by design
+ *   - the pointer entry must exist on disk and carry a SKILL.md
+ *   - .claude-plugin/skills/ on disk must contain ONLY the pointer dir
  *
  * Exit codes: 0 = clean, 1 = problems found, 3 = internal error.
  */
@@ -26,14 +30,13 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 const ROOT = ".";
 const MARKETPLACE = path.join(ROOT, ".claude-plugin", "marketplace.json");
 const PACKAGE_JSON = path.join(ROOT, "package.json");
-// Committed marketplace skill sources (git-consumed): real skills resolve to
-// dist/agent-src/skills/<name>; command-as-skill entries to the committed
-// .claude-plugin/skills/<slug> projection. .claude/skills/ is a gitignored
-// local channel and is intentionally NOT a marketplace source.
-const SKILL_SOURCE_DIRS = [
-  path.join(ROOT, "dist/agent-src", "skills"),
-  path.join(ROOT, ".claude-plugin", "skills"),
-];
+// Bootstrap shim: the ONLY skill the plugin may list. Content skills live in
+// the npx file projection (dist/agent-src/skills/ ships in the npm package,
+// not through the marketplace). .claude/skills/ is a gitignored local channel
+// and is intentionally NOT a marketplace source.
+const POINTER_SKILL_ENTRY = "./.claude-plugin/skills/install-agent-config";
+const PLUGIN_SKILLS_DIR = path.join(ROOT, ".claude-plugin", "skills");
+const POINTER_SKILL_DIRNAME = "install-agent-config";
 
 type JsonValue =
   | string
@@ -174,6 +177,18 @@ export function main(): number {
       }
       seen.add(p);
 
+      // Bootstrap-shim invariant: any entry other than the pointer skill is
+      // a repopulated content-skill list and must FAIL.
+      if (p !== POINTER_SKILL_ENTRY) {
+        errors.push(
+          `${entry} violates the bootstrap shim: the plugin must not ship ` +
+            `content skills (only \`${POINTER_SKILL_ENTRY}\` is allowed), ` +
+            `got \`${p}\` — content is distributed via ` +
+            "`npx -y @event4u/agent-config init`",
+        );
+        continue;
+      }
+
       // Resolve path relative to repo root (strip leading "./" only,
       // NOT every "." and "/" character)
       const rel = removePrefix(p, "./");
@@ -189,9 +204,7 @@ export function main(): number {
     }
   }
 
-  // Reverse-completeness: every SKILL.md on disk under the committed skill
-  // sources (dist/agent-src/skills/ + .claude-plugin/skills/) must appear in
-  // some plugin's skills[].
+  // Shim completeness: the pointer skill must be listed by some plugin.
   const listed = new Set<string>();
   for (const plugin of plugins) {
     if (!isObject(plugin)) {
@@ -201,43 +214,38 @@ export function main(): number {
     if (Array.isArray(skills)) {
       for (const p of skills) {
         if (typeof p === "string") {
-          listed.add(removePrefix(p, "./"));
+          listed.add(p);
         }
       }
     }
   }
+  if (plugins.length > 0 && !listed.has(POINTER_SKILL_ENTRY)) {
+    errors.push(
+      `bootstrap shim: pointer skill \`${POINTER_SKILL_ENTRY}\` is not ` +
+        "listed in any plugin's skills[]",
+    );
+  }
 
-  for (const sourceDir of SKILL_SOURCE_DIRS) {
-    if (!_exists(sourceDir)) {
-      continue;
-    }
-    // source_dir.relative_to(ROOT).as_posix() — ROOT is ".", so this is the
-    // dir spelled relative to cwd with POSIX separators.
-    const prefix = relPosix(sourceDir, ROOT);
-    let entries: fs.Dirent[];
+  // Shim disk shape: .claude-plugin/skills/ must contain ONLY the pointer
+  // dir — a repopulated symlink tree (e.g. from a stale generator) FAILS.
+  if (_exists(PLUGIN_SKILLS_DIR)) {
+    let entries: fs.Dirent[] = [];
     try {
-      entries = fs.readdirSync(sourceDir, { withFileTypes: true });
+      entries = fs.readdirSync(PLUGIN_SKILLS_DIR, { withFileTypes: true });
     } catch {
-      continue;
+      /* unreadable → nothing to assert */
     }
-    // sorted(source_dir.iterdir()) — full-path string sort.
-    const dirs = entries
-      .map((e) => ({ name: e.name, full: path.join(sourceDir, e.name) }))
-      .sort((a, b) => (a.full < b.full ? -1 : a.full > b.full ? 1 : 0));
-    for (const d of dirs) {
-      if (!_isDir(d.full)) {
-        continue;
-      }
-      if (!_exists(path.join(d.full, "SKILL.md"))) {
-        continue;
-      }
-      const rel = `${prefix}/${d.name}`;
-      if (!listed.has(rel)) {
-        errors.push(
-          "skill exists on disk but is not listed in marketplace.json: " +
-            `\`./${rel}\``,
-        );
-      }
+    const extra = entries
+      .filter((e) => _isDir(path.join(PLUGIN_SKILLS_DIR, e.name)))
+      .map((e) => e.name)
+      .filter((name) => name !== POINTER_SKILL_DIRNAME)
+      .sort();
+    for (const name of extra) {
+      errors.push(
+        "bootstrap shim: unexpected skill dir on disk (plugin ships no " +
+          `content skills): \`.claude-plugin/skills/${name}\` — remove it ` +
+          "or re-run the generator",
+      );
     }
   }
 
@@ -246,15 +254,9 @@ export function main(): number {
   }
 
   const pluginCount = plugins.length;
-  let skillCount = 0;
-  for (const p of plugins) {
-    if (isObject(p) && Array.isArray(p["skills"])) {
-      skillCount += p["skills"].length;
-    }
-  }
   process.stdout.write(
     `✅  marketplace.json (${pluginCount} plugin` +
-      `${pluginCount !== 1 ? "s" : ""}, ${skillCount} skills total)\n`,
+      `${pluginCount !== 1 ? "s" : ""}, bootstrap shim: 1 pointer skill)\n`,
   );
   process.stdout.write("  No issues found.\n");
   return 0;
@@ -268,10 +270,6 @@ function _isDir(p: string): boolean {
   }
 }
 
-function relPosix(child: string, base: string): string {
-  return path.relative(base, child).split(path.sep).join("/");
-}
-
 function _isCliEntry(): boolean {
     if (process.argv[1] === undefined) {
         return false;

package/src/scripts/lint_surface_matrix.ts

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+/**
+ * Lint src/config/surface-matrix.yml — the machine-checked per-tool
+ * canonical-surface inventory (road-to-install-path-convergence Phase 2).
+ *
+ * Guarantees:
+ *   - every tool in install.ts::USER_SCOPE_PATHS has a matrix entry, and the
+ *     matrix declares no tool the installer does not know (set equality)
+ *   - each entry's scope_path matches USER_SCOPE_PATHS (drift fails)
+ *   - surface / hooks values come from the closed enums
+ *   - duplicate.detect.all_of paths are user-scope (~/) or repo-relative
+ *     (./); repo-relative paths must resolve on disk
+ *   - a defined duplicate class must carry a converge action, and the
+ *     claude-code converge command must name the real plugin id (drift guard
+ *     against _lib/claude_plugin.ts)
+ *
+ * Exit codes: 0 = clean, 1 = problems found, 3 = internal error.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import YAML from 'yaml';
+
+import { USER_SCOPE_PATHS } from './install.js';
+import { CLAUDE_MARKETPLACE_NAME, CLAUDE_PLUGIN_ID } from './_lib/claude_plugin.js';
+
+const REPO_ROOT = path.resolve(fileURLToPath(import.meta.url), '..', '..', '..');
+export const MATRIX_PATH = path.join(REPO_ROOT, 'src', 'config', 'surface-matrix.yml');
+
+const SURFACE_VALUES = new Set(['projection', 'plugin', 'bundles', 'export-only']);
+const HOOKS_VALUES = new Set(['managed-settings-block', 'settings-hooks-opt-in', 'plugin', 'none']);
+
+type JsonObject = Record<string, unknown>;
+
+function isObject(v: unknown): v is JsonObject {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+export interface SurfaceMatrixTool {
+    surface: string;
+    scope_path: string;
+    hooks: string;
+    duplicate?: {
+        description?: string;
+        pending_evidence?: string;
+        detect?: { all_of?: string[] };
+    };
+    converge?: { action?: string; command?: string; reaps?: string[] };
+    notes?: string;
+}
+
+export function load_surface_matrix(matrixPath: string = MATRIX_PATH): Record<string, SurfaceMatrixTool> {
+    const raw = YAML.parse(fs.readFileSync(matrixPath, 'utf-8'), { version: '1.1' }) as JsonObject;
+    const tools = raw['tools'];
+    if (!isObject(tools)) {
+        throw new Error('surface-matrix.yml: `tools` must be a mapping');
+    }
+    return tools as unknown as Record<string, SurfaceMatrixTool>;
+}
+
+export function main(): number {
+    if (!fs.existsSync(MATRIX_PATH)) {
+        process.stdout.write(`❌  ${MATRIX_PATH} not found\n`);
+        return 1;
+    }
+
+    const errors: string[] = [];
+    let tools: Record<string, SurfaceMatrixTool>;
+    try {
+        tools = load_surface_matrix();
+    } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        process.stdout.write(`❌  surface-matrix.yml unreadable: ${msg}\n`);
+        return 1;
+    }
+
+    // Coverage — set equality with the installer's tool inventory.
+    const matrixIds = new Set(Object.keys(tools));
+    const installerIds = new Set(Object.keys(USER_SCOPE_PATHS));
+    for (const id of installerIds) {
+        if (!matrixIds.has(id)) {
+            errors.push(`tool \`${id}\` is in USER_SCOPE_PATHS but has no surface-matrix entry`);
+        }
+    }
+    for (const id of matrixIds) {
+        if (!installerIds.has(id)) {
+            errors.push(`tool \`${id}\` is in the surface matrix but not in USER_SCOPE_PATHS`);
+        }
+    }
+
+    for (const [id, entry] of Object.entries(tools)) {
+        const where = `tools.${id}`;
+        if (!isObject(entry)) {
+            errors.push(`${where} must be a mapping`);
+            continue;
+        }
+        if (!SURFACE_VALUES.has(entry.surface)) {
+            errors.push(`${where}.surface \`${String(entry.surface)}\` not in {${[...SURFACE_VALUES].join(', ')}}`);
+        }
+        if (!HOOKS_VALUES.has(entry.hooks)) {
+            errors.push(`${where}.hooks \`${String(entry.hooks)}\` not in {${[...HOOKS_VALUES].join(', ')}}`);
+        }
+        const expectedPath = USER_SCOPE_PATHS[id];
+        if (expectedPath && entry.scope_path !== expectedPath) {
+            errors.push(
+                `${where}.scope_path \`${String(entry.scope_path)}\` drifted from ` +
+                    `USER_SCOPE_PATHS \`${expectedPath}\``,
+            );
+        }
+
+        const dup = entry.duplicate;
+        if (dup !== undefined) {
+            if (!isObject(dup)) {
+                errors.push(`${where}.duplicate must be a mapping`);
+                continue;
+            }
+            const detect = dup.detect;
+            if (detect !== undefined) {
+                const allOf = isObject(detect) ? detect['all_of'] : undefined;
+                if (!Array.isArray(allOf) || allOf.length === 0) {
+                    errors.push(`${where}.duplicate.detect.all_of must be a non-empty list`);
+                } else {
+                    for (const p of allOf) {
+                        if (typeof p !== 'string' || !(p.startsWith('~/') || p.startsWith('./'))) {
+                            errors.push(
+                                `${where}.duplicate.detect path \`${String(p)}\` must start with ~/ or ./`,
+                            );
+                            continue;
+                        }
+                        if (p.startsWith('./') && !fs.existsSync(path.join(REPO_ROOT, p.slice(2)))) {
+                            errors.push(`${where}.duplicate.detect repo path does not resolve: \`${p}\``);
+                        }
+                    }
+                }
+                // A defined (non-pending) duplicate class needs a converge action.
+                const conv = entry.converge;
+                if (!isObject(conv) || typeof conv['command'] !== 'string' || conv['command'] === '') {
+                    errors.push(`${where} defines a duplicate class but no converge.command`);
+                }
+            } else if (typeof dup['pending_evidence'] !== 'string') {
+                errors.push(
+                    `${where}.duplicate must carry either detect.all_of or pending_evidence`,
+                );
+            }
+        }
+    }
+
+    // Drift guard: the claude-code converge command must name the real
+    // plugin id + marketplace name from _lib/claude_plugin.ts.
+    const claude = tools['claude-code'];
+    const claudeCmd = claude && isObject(claude.converge) ? String(claude.converge['command'] ?? '') : '';
+    const expectedRef = `${CLAUDE_PLUGIN_ID}@${CLAUDE_MARKETPLACE_NAME}`;
+    if (claudeCmd !== '' && !claudeCmd.includes(expectedRef)) {
+        errors.push(
+            `tools.claude-code.converge.command must reference \`${expectedRef}\` ` +
+                `(got \`${claudeCmd}\`)`,
+        );
+    }
+
+    if (errors.length > 0) {
+        process.stdout.write('❌  surface-matrix.yml has problems:\n');
+        for (const e of errors) {
+            process.stdout.write(`  - ${e}\n`);
+        }
+        return 1;
+    }
+
+    process.stdout.write(
+        `✅  surface-matrix.yml (${matrixIds.size} tools, coverage matches USER_SCOPE_PATHS)\n`,
+    );
+    process.stdout.write('  No issues found.\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;
+    }
+    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()) {
+    try {
+        process.exit(main());
+    } catch (exc) {
+        const msg = exc instanceof Error ? exc.message : String(exc);
+        process.stderr.write(`❌  internal error: ${msg}\n`);
+        process.exit(3);
+    }
+}