vigiles 6.0.0 → 8.0.0

package/dist/scan-behavioral.js

@@ -17,12 +17,17 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.probePluginTriggersWith = probePluginTriggersWith;
 exports.probePluginTriggers = probePluginTriggers;
 exports.formatBehavioralReport = formatBehavioralReport;
+exports.buildSelectionReport = buildSelectionReport;
+exports.measurePluginSelectionWith = measurePluginSelectionWith;
+exports.measurePluginSelection = measurePluginSelection;
+exports.formatSelectionReport = formatSelectionReport;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const scan_js_1 = require("./scan.js");
 const eval_js_1 = require("./eval.js");
 const harness_assert_js_1 = require("./harness-assert.js");
 const harness_test_js_1 = require("./harness-test.js");
+const plugin_loader_js_1 = require("./adapters/claude-code/plugin-loader.js");
 const eval_js_2 = require("./adapters/codex/eval.js");
 const driver_js_1 = require("./adapters/codex/driver.js");
 function buildProbe(dir, harness) {
@@ -56,6 +61,39 @@ function pluginName(dir) {
         return null;
     }
 }
+/**
+ * Does the plugin declare a SessionStart hook? The STUBBED measurement path rebuilds
+ * the plugin to skills-only (`packageSkillsDir`), DROPPING `hooks/` — so a SessionStart
+ * hook that primes skill selection (e.g. superpowers' `using-superpowers` gateway
+ * injection) is silently lost, and a recall collapse to 0 under stubbing is then a
+ * measurement ARTIFACT, not a real miss. Detect it to LABEL honestly (Layer 1) rather
+ * than report a misleading 0%. See `research/plugin-selection-collision.md`.
+ */
+function hasSessionStartHook(dir) {
+    try {
+        const hooks = (0, plugin_loader_js_1.loadPlugin)(dir).settings.hooks;
+        return hooks !== undefined && Object.keys(hooks).includes("SessionStart");
+    }
+    catch {
+        return false;
+    }
+}
+const HOOK_PRIMED_NOTE = "hook-primed — the stubbed run dropped the plugin's SessionStart hook (which can " +
+    "prime skill selection), so 0% recall is likely a measurement artifact; re-run " +
+    "against the full plugin install to measure faithfully";
+/**
+ * Layer-1 honesty: a STUBBED run on a SessionStart-hooked plugin where EVERY measured
+ * skill sits at recall 0 is the dropped-hook artifact — not a real result. The
+ * all-zero gate keeps a genuine single-skill miss reported as real (if siblings fired,
+ * the hook ran or wasn't needed). Applied to both the trigger column and the matrix.
+ */
+function isStubbedHookArtifact(dir, stub, recalls) {
+    if (!stub || recalls.length === 0)
+        return false;
+    if (!recalls.every((r) => r === 0))
+        return false;
+    return hasSessionStartHook(dir);
+}
 /** Probe one skill via the harness probe's eval driver → result, never throwing. */
 async function probeSkill(ctx, name, ps) {
     try {
@@ -108,7 +146,19 @@ async function probePluginTriggersWith(dir, promptSet, probe, opts = {}) {
         }
         results.push(await probeSkill(ctx, s.name, ps));
     }
-    return { available: true, results };
+    return {
+        available: true,
+        results: relabelTriggerArtifact(dir, probe, results),
+    };
+}
+/** Relabel an all-zero-recall stubbed run on a hooked plugin as unmeasured (Layer 1). */
+function relabelTriggerArtifact(dir, probe, results) {
+    const recalls = results.filter((r) => r.measured).map((r) => r.recall ?? 0);
+    if (!isStubbedHookArtifact(dir, probe.stub, recalls))
+        return [...results];
+    return results.map((r) => r.measured && (r.recall ?? 0) === 0
+        ? { skill: r.skill, measured: false, note: HOOK_PRIMED_NOTE }
+        : r);
 }
 /**
  * Probe a plugin's skills against the real harness (default Claude Code; Codex via
@@ -147,4 +197,192 @@ function formatBehavioralReport(b) {
     }
     return lines.join("\n");
 }
+/** Map a namespaced skill id (`ns:name`) to its bare name. */
+function bareSkillName(id) {
+    const i = id.lastIndexOf(":");
+    return i >= 0 ? id.slice(i + 1) : id;
+}
+function emptySelection(skills) {
+    return {
+        available: true,
+        skills,
+        matrix: skills.map(() => []),
+        perSkill: [],
+        collisionRate: 0,
+        n: 0,
+    };
+}
+function buildSkillStat(a) {
+    const { skill, i, skills, row, n, collisions } = a;
+    const collidesWith = skills
+        .map((s, j) => ({ skill: s, rate: n > 0 ? row[j] / n : 0 }))
+        .filter((c) => c.skill !== skill && c.rate > 0)
+        .sort((x, y) => y.rate - x.rate);
+    return {
+        skill,
+        recall: n > 0 ? row[i] / n : 0,
+        collisionRate: n > 0 ? collisions / n : 0,
+        n,
+        collidesWith,
+    };
+}
+/**
+ * Pure aggregation: fold per-run fired-skill sets into the N×N selection matrix +
+ * per-skill recall/collision + the plugin-level collision rate. Separated from the
+ * model-driving so it's unit-testable with synthetic runs (no model).
+ */
+function buildSelectionReport(skills, runs) {
+    const index = new Map(skills.map((s, i) => [s, i]));
+    const n = skills.length;
+    const matrix = skills.map(() => new Array(n).fill(0));
+    const nBy = new Array(n).fill(0);
+    const collisionBy = new Array(n).fill(0);
+    let collisionTotal = 0;
+    for (const run of runs) {
+        const i = index.get(run.intended);
+        if (i === undefined)
+            continue;
+        nBy[i] += 1;
+        let collided = false;
+        for (const fb of run.firedBare) {
+            const j = index.get(fb);
+            if (j === undefined)
+                continue;
+            matrix[i][j] += 1;
+            if (j !== i)
+                collided = true;
+        }
+        if (collided) {
+            collisionBy[i] += 1;
+            collisionTotal += 1;
+        }
+    }
+    const total = nBy.reduce((a, b) => a + b, 0);
+    return {
+        available: true,
+        skills,
+        matrix,
+        perSkill: skills.map((s, i) => buildSkillStat({
+            skill: s,
+            i,
+            skills,
+            row: matrix[i],
+            n: nBy[i],
+            collisions: collisionBy[i],
+        })),
+        collisionRate: total > 0 ? collisionTotal / total : 0,
+        n: total,
+    };
+}
+/** Build the prompts × trials work list across every skill that has prompts. */
+function selectionJobs(candidates, promptSet, trials) {
+    return candidates.flatMap((c) => {
+        const ps = promptSet[c.name];
+        if (!ps || ps.prompts.length === 0)
+            return [];
+        return ps.prompts.flatMap((prompt) => Array.from({ length: trials }, () => ({ intended: c.name, prompt })));
+    });
+}
+/** The injectable core (for tests): drive the matrix via a fake/real probe. */
+async function measurePluginSelectionWith(dir, promptSet, probe, opts = {}) {
+    const candidates = (0, scan_js_1.scanPlugin)(dir).skills.filter((s) => !s.userInvoked && s.hasDescription);
+    const skills = candidates.map((c) => c.name);
+    if (skills.length < 2) {
+        return {
+            ...emptySelection(skills),
+            note: "needs ≥2 model-invocable skills to measure cross-skill collision",
+        };
+    }
+    const own = new Set(skills);
+    const jobs = selectionJobs(candidates, promptSet, Math.max(1, opts.trials ?? 1));
+    if (jobs.length === 0) {
+        return {
+            ...emptySelection(skills),
+            note: "no prompts supplied for any skill",
+        };
+    }
+    // Selection is decided at the frontmatter (the selector picks BEFORE the body
+    // loads), so stub each body to a no-op: the run stops AT selection instead of
+    // executing the whole workflow — the same affordability trick trigger-rate uses.
+    const pluginDir = probe.stub ? (0, eval_js_1.stubbedPluginDir)(dir) : dir;
+    try {
+        const d = probe.evalDriver;
+        const outcomes = await (0, eval_js_1.runPool)(jobs, Math.max(1, opts.concurrency ?? 1), (job) => (0, eval_js_1.runSkillSelectionTrial)({
+            prompt: job.prompt,
+            pluginDir,
+            runner: d.runner,
+            parse: d.parse,
+            runError: d.runError,
+            model: opts.model ?? "sonnet",
+        }));
+        const runs = [];
+        jobs.forEach((job, k) => {
+            if (outcomes[k].errored)
+                return;
+            runs.push({
+                intended: job.intended,
+                firedBare: outcomes[k].fired
+                    .map(bareSkillName)
+                    .filter((b) => own.has(b)),
+            });
+        });
+        const report = buildSelectionReport(skills, runs);
+        // Layer-1 honesty: an all-zero-recall stubbed run on a hooked plugin is the
+        // dropped-hook artifact — flag it instead of presenting a 0%-collision result
+        // computed from a plugin that never fired.
+        const recalls = report.perSkill.filter((s) => s.n > 0).map((s) => s.recall);
+        return isStubbedHookArtifact(dir, probe.stub, recalls)
+            ? { ...report, note: HOOK_PRIMED_NOTE }
+            : report;
+    }
+    finally {
+        if (probe.stub)
+            (0, node_fs_1.rmSync)(pluginDir, { recursive: true, force: true });
+    }
+}
+/**
+ * Measure a plugin's cross-skill selection-collision matrix against the real
+ * harness (Claude Code only — Codex has no skill-selection event). Needs the
+ * `claude` CLI + model auth; degrades to `available: false` otherwise.
+ */
+async function measurePluginSelection(dir, promptSet, opts = {}) {
+    const harness = opts.harness ?? "claude-code";
+    if (harness !== "claude-code") {
+        return {
+            ...emptySelection([]),
+            available: false,
+            note: `selection-collision is Claude Code only (no skill-selection event on ${harness})`,
+        };
+    }
+    const probe = buildProbe(dir, harness);
+    if (!probe.available()) {
+        return {
+            ...emptySelection([]),
+            available: false,
+            note: "needs the claude CLI + model auth",
+        };
+    }
+    return measurePluginSelectionWith(dir, promptSet, probe, opts);
+}
+/** Format the selection-collision matrix as a scan-report section. */
+function formatSelectionReport(r) {
+    if (!r.available)
+        return `Selection-collision: unavailable — ${r.note ?? "n/a"}`;
+    if (r.n === 0)
+        return `Selection-collision: ${r.note ?? "not measured"}`;
+    const lines = [
+        `Selection-collision: ${pct(r.collisionRate)} of ${String(r.n)} runs hit a sibling skill`,
+    ];
+    if (r.note)
+        lines.push(`  ⓘ ${r.note}`);
+    for (const s of r.perSkill) {
+        if (s.n === 0)
+            continue;
+        const mark = s.collisionRate === 0 ? "✓" : "⚠";
+        const top = s.collidesWith[0];
+        const tail = top ? ` — top collider: ${top.skill} ${pct(top.rate)}` : "";
+        lines.push(`  ${mark} ${s.skill} — recall ${pct(s.recall)}, collision ${pct(s.collisionRate)}${tail}`);
+    }
+    return lines.join("\n");
+}
 //# sourceMappingURL=scan-behavioral.js.map

package/dist/scan-trigger-suggest.d.ts

@@ -0,0 +1,54 @@
+/**
+ * scan → trigger-tier nudge. When a plugin ships model-invocable skills AND a
+ * real model is reachable, surface the (real-model) `scan --trigger` tier that
+ * measures whether those skills actually FIRE (recall + precision). Pure
+ * decision + helpers; the IO (prompt / scaffold write / running the measure)
+ * lives in the CLI. Honors `great-agent-flow`: an agent (non-TTY / `--json` /
+ * `--no-interactive`) is HINTED, never prompted — a `scan` must never hang.
+ */
+/** Only the env vars that signal a reachable model (parse, don't validate). */
+export interface ModelEnv {
+    readonly ANTHROPIC_API_KEY?: string;
+    readonly CLAUDECODE?: string;
+    readonly CLAUDE_CODE_ENTRYPOINT?: string;
+}
+/**
+ * Is a real model reachable for the eval / trigger tier? Either a metered API
+ * key (`ANTHROPIC_API_KEY`), OR an authenticated Claude Code session
+ * (`CLAUDECODE=1` / `CLAUDE_CODE_ENTRYPOINT`, web/desktop/CLI) — the latter
+ * drives the `claude` CLI on the user's subscription, no key needed. Keeping
+ * this a tiny, env-only predicate (not a live probe) means it never spends a
+ * token just to decide whether to suggest spending one.
+ */
+export declare function hasModelAccess(env: ModelEnv): boolean;
+export type TriggerSuggestion = "prompt" | "hint" | "none";
+export interface SuggestOpts {
+    /** A real model is reachable (`hasModelAccess`). */
+    readonly modelAccess: boolean;
+    /** stdout is an interactive terminal (a human is watching). */
+    readonly isTTY: boolean;
+    /** Count of model-invocable, described skills worth measuring. */
+    readonly triggerableSkills: number;
+    /** `--json` — machine output; never decorate or prompt. */
+    readonly json: boolean;
+    /** `--no-interactive` — explicit agent/CI mode; hint, never prompt. */
+    readonly noInteractive: boolean;
+}
+/**
+ * Decide how `scan` surfaces the trigger tier after its report:
+ * - `"none"`   — no model-invocable skills, no model access, or `--json`.
+ * - `"hint"`   — model access + skills but non-interactive (agent / CI / non-TTY
+ *                / `--no-interactive`): a one-line, non-blocking hint.
+ * - `"prompt"` — model access + skills + a human at a TTY: offer to set it up.
+ */
+export declare function decideTriggerSuggestion(o: SuggestOpts): TriggerSuggestion;
+/** The one-line, non-blocking hint (the agent/CI surface). */
+export declare function formatTriggerHint(dir: string, triggerableSkills: number): string;
+/**
+ * A starter `--prompts` file (the real `TriggerPromptSet` shape: bare skill name
+ * → `{ prompts, irrelevant }`). One entry per triggerable skill, with TODO
+ * placeholders the user replaces with real requests. Deterministic; written
+ * only on an explicit human "yes" so a plain `scan` never spends a token.
+ */
+export declare function scaffoldTriggerPrompts(skillNames: readonly string[]): string;
+//# sourceMappingURL=scan-trigger-suggest.d.ts.map

package/dist/scan-trigger-suggest.js

@@ -0,0 +1,70 @@
+"use strict";
+/**
+ * scan → trigger-tier nudge. When a plugin ships model-invocable skills AND a
+ * real model is reachable, surface the (real-model) `scan --trigger` tier that
+ * measures whether those skills actually FIRE (recall + precision). Pure
+ * decision + helpers; the IO (prompt / scaffold write / running the measure)
+ * lives in the CLI. Honors `great-agent-flow`: an agent (non-TTY / `--json` /
+ * `--no-interactive`) is HINTED, never prompted — a `scan` must never hang.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasModelAccess = hasModelAccess;
+exports.decideTriggerSuggestion = decideTriggerSuggestion;
+exports.formatTriggerHint = formatTriggerHint;
+exports.scaffoldTriggerPrompts = scaffoldTriggerPrompts;
+/**
+ * Is a real model reachable for the eval / trigger tier? Either a metered API
+ * key (`ANTHROPIC_API_KEY`), OR an authenticated Claude Code session
+ * (`CLAUDECODE=1` / `CLAUDE_CODE_ENTRYPOINT`, web/desktop/CLI) — the latter
+ * drives the `claude` CLI on the user's subscription, no key needed. Keeping
+ * this a tiny, env-only predicate (not a live probe) means it never spends a
+ * token just to decide whether to suggest spending one.
+ */
+function hasModelAccess(env) {
+    return Boolean(env.ANTHROPIC_API_KEY ||
+        env.CLAUDECODE === "1" ||
+        env.CLAUDE_CODE_ENTRYPOINT);
+}
+/**
+ * Decide how `scan` surfaces the trigger tier after its report:
+ * - `"none"`   — no model-invocable skills, no model access, or `--json`.
+ * - `"hint"`   — model access + skills but non-interactive (agent / CI / non-TTY
+ *                / `--no-interactive`): a one-line, non-blocking hint.
+ * - `"prompt"` — model access + skills + a human at a TTY: offer to set it up.
+ */
+function decideTriggerSuggestion(o) {
+    if (o.json || o.triggerableSkills < 1 || !o.modelAccess)
+        return "none";
+    if (o.noInteractive || !o.isTTY)
+        return "hint";
+    return "prompt";
+}
+/** The one-line, non-blocking hint (the agent/CI surface). */
+function formatTriggerHint(dir, triggerableSkills) {
+    const n = triggerableSkills;
+    return (`ℹ ${String(n)} model-invocable skill${n === 1 ? "" : "s"} + model access detected — ` +
+        `measure whether they actually FIRE (recall + precision) with:\n` +
+        `    vigiles scan ${dir} --trigger --prompts=trigger-prompts.json`);
+}
+/**
+ * A starter `--prompts` file (the real `TriggerPromptSet` shape: bare skill name
+ * → `{ prompts, irrelevant }`). One entry per triggerable skill, with TODO
+ * placeholders the user replaces with real requests. Deterministic; written
+ * only on an explicit human "yes" so a plain `scan` never spends a token.
+ */
+function scaffoldTriggerPrompts(skillNames) {
+    const obj = {};
+    for (const name of skillNames) {
+        obj[name] = {
+            prompts: [
+                `TODO: a request that SHOULD trigger "${name}"`,
+                `TODO: a differently-phrased request that should also trigger it`,
+            ],
+            irrelevant: [
+                `TODO: an unrelated request that should NOT trigger "${name}"`,
+            ],
+        };
+    }
+    return JSON.stringify(obj, null, 2) + "\n";
+}
+//# sourceMappingURL=scan-trigger-suggest.js.map

package/dist/scan.d.ts

@@ -18,6 +18,7 @@ import { type HookEventIssue } from "./core/hook-events.js";
 import { type McpIssue } from "./core/mcp-config.js";
 import { type DescriptionOverlap } from "./core/description-overlap.js";
 import { type McpToolIssue } from "./core/mcp-tool.js";
+import { type McpContractToolError } from "./core/mcp.js";
 import { type McpHookIssue } from "./core/mcp-hook.js";
 import { type PurityLevel, type EffectSurface } from "./core/effects.js";
 /** A named writing system. The label `unexpectedScript` reports + the config's expectation parse into this. */
@@ -93,7 +94,7 @@ export interface ScanHook {
  * Every cc/codex repo has one even when it ships no plugin surface, so `scan`
  * reports it — otherwise a plain instruction-only repo looks empty. `hasSpec` is
  * the deterministic fact that a `<file>.spec.ts` sits beside it (spec-managed vs
- * hand-written); it is informational, NOT the `require-spec` gate (that's lint).
+ * hand-written); it is informational, NOT the `require-instructions-spec` gate (that's lint).
  */
 export interface ScanInstructions {
     readonly file: string;
@@ -108,6 +109,13 @@ export interface ScanReport {
     readonly hooks: readonly ScanHook[];
     /** Hook entries with no script file (inline shell one-liners) — can't be path-checked. */
     readonly inlineHooks: number;
+    /**
+     * Hand-written hook commands that are NOT compiled `vigiles/hook` artifacts (a
+     * compiled hook's command invokes `vigiles hook-runtime run-program`). The basis
+     * for the `prefer-compiled-hooks` recommendation — a single nudge regardless of
+     * count. Zero when there are no hooks or every hook is vigiles-managed.
+     */
+    readonly manualHookCount: number;
     readonly commands: number;
     readonly mcp: boolean;
     /**
@@ -174,8 +182,30 @@ export interface SurfaceClassifier {
  * no drift). The ≥20% guard avoids a near-empty string tripping on one letter.
  */
 export declare function unexpectedScript(text: string, expected?: Script): Script | null;
+/**
+ * A compiled `vigiles/hook` artifact runs through the `hook-runtime run-program`
+ * runtime entrypoint; any other hook command is hand-written (a shell script or
+ * an inline one-liner) the author maintains directly. The basis for the
+ * `prefer-compiled-hooks` nudge.
+ */
+export declare function isManagedHookCommand(command: string): boolean;
+/** The `prefer-compiled-hooks` recommendation message (shared by `lint` + `scan`). */
+export declare function preferCompiledHooksMessage(count: number): string;
 /** Scan a plugin/repo directory and report its surfaces + structural issues. */
 export declare function scanPlugin(dir: string, layout?: PluginLayout, dialect?: HarnessDialect): ScanReport;
+/**
+ * LIVE MCP tool resolution for a scanned plugin — the opt-in (`scan --verify-mcp`)
+ * dynamic check no static linter can do: it STARTS each declared MCP server and
+ * checks every `mcp__server__tool` the plugin's agents reference actually exists on
+ * it (catching rename/removal rot, e.g. `create_issue`→`issue_write`). Reuses the
+ * already-computed `report` (its agents' tool lists) + the declared server configs;
+ * returns `[]` when the plugin declares no MCP servers (nothing to start). Async +
+ * side-effecting (spawns servers) — which is exactly why it's opt-in, not a default
+ * lint rule. See `verifyMcpContractTools` (core/mcp.ts).
+ */
+export declare function verifyLiveMcpTools(report: ScanReport, layout: PluginLayout, dialect: HarnessDialect, timeoutMs?: number): Promise<McpContractToolError[]>;
+/** Render the live MCP tool-check result (human-readable). */
+export declare function formatMcpContractReport(errors: readonly McpContractToolError[]): string;
 /**
  * A plugin MARKETPLACE (`.claude-plugin/marketplace.json`) decomposed into its
  * members. A marketplace either VENDORS its plugins in-tree (string `source`

package/dist/scan.js

@@ -14,7 +14,11 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.unexpectedScript = unexpectedScript;
+exports.isManagedHookCommand = isManagedHookCommand;
+exports.preferCompiledHooksMessage = preferCompiledHooksMessage;
 exports.scanPlugin = scanPlugin;
+exports.verifyLiveMcpTools = verifyLiveMcpTools;
+exports.formatMcpContractReport = formatMcpContractReport;
 exports.inspectMarketplace = inspectMarketplace;
 exports.expandMarketplace = expandMarketplace;
 exports.formatScanReport = formatScanReport;
@@ -31,6 +35,7 @@ const linters_js_1 = require("./core/linters.js");
 const frontmatter_read_js_1 = require("./core/frontmatter-read.js");
 const description_overlap_js_1 = require("./core/description-overlap.js");
 const mcp_tool_js_1 = require("./core/mcp-tool.js");
+const mcp_js_1 = require("./core/mcp.js");
 const mcp_hook_js_1 = require("./core/mcp-hook.js");
 const agent_runtime_js_1 = require("./adapters/claude-code/agent-runtime.js");
 const test_coverage_js_1 = require("./test-coverage.js");
@@ -262,10 +267,32 @@ function resolveScript(token, root, pluginRootToken) {
 // target is INTENTIONAL, not a broken reference. Don't flag scripts in such a
 // command as MISSING (a false positive caught on gmickel/flow-next's ralph-guard).
 const EXISTENCE_GUARD = /(?:\[\[?\s*!?\s*-[efsx]\s)|(?:\btest\s+!?\s*-[efsx]\s)/;
+/**
+ * A compiled `vigiles/hook` artifact runs through the `hook-runtime run-program`
+ * runtime entrypoint; any other hook command is hand-written (a shell script or
+ * an inline one-liner) the author maintains directly. The basis for the
+ * `prefer-compiled-hooks` nudge.
+ */
+function isManagedHookCommand(command) {
+    return /\bhook-runtime\b/.test(command);
+}
+/** The `prefer-compiled-hooks` recommendation message (shared by `lint` + `scan`). */
+function preferCompiledHooksMessage(count) {
+    return (`${String(count)} hand-written hook command(s) — if any gate the agent ` +
+        `(a block/deny decision), compiled hooks (\`vigiles/hook\`) make whole hook ` +
+        `bug classes unrepresentable at authoring time, and \`guardrail-check\` proves ` +
+        `an existing one blocks. See docs/compiled-hooks.md.`);
+}
 /** Pull script-file hook commands out of the resolved settings; count inline ones. */
 function scanHooks(settings, root, pluginRootToken) {
     const text = JSON.stringify(settings.hooks ?? {});
     const commands = [...text.matchAll(/"command":\s*"((?:[^"\\]|\\.)*)"/g)].map((m) => m[1]);
+    // A hand-written hook is any non-empty command that isn't a vigiles-managed
+    // (compiled) hook-runtime invocation — the basis for the prefer-compiled-hooks nudge.
+    const manual = commands.filter((c) => {
+        const u = c.replace(/\\(.)/g, "$1").trim();
+        return u !== "" && !isManagedHookCommand(u);
+    }).length;
     const byScript = new Map();
     let inline = 0;
     for (const cmd of commands) {
@@ -287,7 +314,7 @@ function scanHooks(settings, root, pluginRootToken) {
         }
     }
     const hooks = [...byScript.values()].sort((a, b) => a.script.localeCompare(b.script));
-    return { hooks, inline };
+    return { hooks, inline, manual };
 }
 // ---------------------------------------------------------------------------
 // Public API
@@ -484,7 +511,7 @@ function scanPlugin(dir, layout, dialect = dialect_js_1.claudeCodeDialect) {
     const lay = layout ?? layout_js_1.claudeCodeLayout;
     const cls = makeClassifier(lay);
     const loaded = (0, plugin_loader_js_1.loadPlugin)(dir, lay);
-    const { hooks, inline } = scanHooks(loaded.settings, (0, node_path_1.resolve)(dir), lay.pluginRootToken);
+    const { hooks, inline, manual } = scanHooks(loaded.settings, (0, node_path_1.resolve)(dir), lay.pluginRootToken);
     // Hook-event keys are a CLOSED platform set — an unrecognized one is a dead
     // registration (the hook never fires), so flag every unknown (not just typos).
     // ONLY for the canonical object-keyed-by-event shape: a plugin shipping a
@@ -518,6 +545,7 @@ function scanPlugin(dir, layout, dialect = dialect_js_1.claudeCodeDialect) {
         agents,
         hooks,
         inlineHooks: inline,
+        manualHookCount: manual,
         commands: Object.keys(loaded.files).filter(cls.isCommand).length,
         mcp: loaded.warnings.some((w) => w.includes("MCP server")),
         danglingRefs: (0, plugin_loader_js_2.danglingRefs)((0, node_path_1.resolve)(dir), lay),
@@ -535,6 +563,35 @@ function scanPlugin(dir, layout, dialect = dialect_js_1.claudeCodeDialect) {
         puritySummary,
     };
 }
+/**
+ * LIVE MCP tool resolution for a scanned plugin — the opt-in (`scan --verify-mcp`)
+ * dynamic check no static linter can do: it STARTS each declared MCP server and
+ * checks every `mcp__server__tool` the plugin's agents reference actually exists on
+ * it (catching rename/removal rot, e.g. `create_issue`→`issue_write`). Reuses the
+ * already-computed `report` (its agents' tool lists) + the declared server configs;
+ * returns `[]` when the plugin declares no MCP servers (nothing to start). Async +
+ * side-effecting (spawns servers) — which is exactly why it's opt-in, not a default
+ * lint rule. See `verifyMcpContractTools` (core/mcp.ts).
+ */
+async function verifyLiveMcpTools(report, layout, dialect, timeoutMs = 10000) {
+    // collectMcpServers yields the raw JSON server entries; a malformed one (no
+    // command) just fails to start → server-unreachable (handled), so the cast is safe.
+    const servers = collectMcpServers((0, node_path_1.resolve)(report.dir), layout);
+    if (Object.keys(servers).length === 0)
+        return [];
+    const tools = report.agents.flatMap((a) => a.tools ?? []);
+    return (0, mcp_js_1.verifyMcpContractTools)(tools, servers, dialect, timeoutMs);
+}
+/** Render the live MCP tool-check result (human-readable). */
+function formatMcpContractReport(errors) {
+    if (errors.length === 0) {
+        return "Live MCP tool check: every referenced mcp__server__tool resolves ✓";
+    }
+    const lines = [`Live MCP tool check — ${String(errors.length)} issue(s):`];
+    for (const e of errors)
+        lines.push("  ✗ " + (0, mcp_js_1.mcpContractToolMessage)(e));
+    return lines.join("\n");
+}
 /**
  * Read a `marketplace.json` beside the layout's plugin manifest and classify its
  * members into on-disk vs external. Returns `null` when `dir` is not a
@@ -710,13 +767,18 @@ function formatScanReport(r) {
     // verdict — it points at the behavioral column, it doesn't fail the scan.
     const mismatched = r.skills.filter((s) => s.descriptionScript);
     if (mismatched.length > 0) {
-        out.push(`⚠ ${String(mismatched.length)} skill(s) have descriptions in an unexpected script (cross-language trigger risk) — measure with \`scan --trigger\``, "");
+        out.push(`⚠ ${String(mismatched.length)} skill(s) have descriptions in an unexpected script (cross-language trigger risk) — measure with \`vigiles measure\``, "");
     }
     // Skill-metadata is a RECOMMENDATION, not a structural defect (the skill loads
     // via fallbacks) — reported as a soft note, never counted in the verdict.
     if (r.skillMetaIssues.length > 0) {
         out.push(`ℹ ${String(r.skillMetaIssues.length)} skill(s) lack an explicit frontmatter name/description (recommended for a reliable trigger surface) — they still load via fallback`, "");
     }
+    // One discovery nudge toward compiled hooks (never per-hook); the hand-written
+    // shell lane stays first-class, so this is a recommendation, not a defect.
+    if (r.manualHookCount > 0) {
+        out.push(`ℹ ${preferCompiledHooksMessage(r.manualHookCount)}`, "");
+    }
     // Malformed-YAML frontmatter is INFORMATIONAL, not a structural defect: js-yaml
     // is stricter than some loaders (a colon/quote/<example> in a one-line
     // description trips it though the file may still load), and the other fields are

package/dist/score-explainer.js

@@ -155,7 +155,7 @@ function explainSurface(report, surface) {
 /** Render explanations for a CLI/report — grouped under the symptom, fix called out. */
 function formatExplanations(exps) {
     if (exps.length === 0) {
-        return "No deterministic cause found — the cause is likely behavioral (measure with `scan --trigger` / an eval).";
+        return "No deterministic cause found — the cause is likely behavioral (measure with `vigiles measure` / an eval).";
     }
     const lines = [];
     for (const e of exps) {

package/dist/self-command-refs.d.ts

@@ -0,0 +1,21 @@
+export interface CommandRefIssue {
+    readonly file: string;
+    readonly line: number;
+    /** The offending invocation, e.g. `vigiles compile-hook`. */
+    readonly ref: string;
+    readonly reason: string;
+}
+export interface KnownCommands {
+    readonly verbs: readonly string[];
+    readonly kinds: readonly string[];
+}
+/**
+ * Find stale/unknown vigiles command references across the given files. Pure —
+ * the caller supplies file contents (so it works over the repo in a test, or any
+ * file set).
+ */
+export declare function findStaleCommandRefs(files: readonly {
+    readonly path: string;
+    readonly content: string;
+}[], known?: KnownCommands): CommandRefIssue[];
+//# sourceMappingURL=self-command-refs.d.ts.map