vigiles 5.0.1 → 5.2.0

package/dist/cli.js

@@ -19,10 +19,14 @@ const cli_flags_js_1 = require("./cli-flags.js");
 const setup_plan_js_1 = require("./setup-plan.js");
 const types_js_1 = require("./core/types.js");
 const test_coverage_js_1 = require("./test-coverage.js");
+const scaffold_test_js_1 = require("./scaffold-test.js");
 const scan_js_1 = require("./scan.js");
+const score_explainer_js_1 = require("./score-explainer.js");
+const scan_behavioral_js_1 = require("./scan-behavioral.js");
 const adapter_registry_js_1 = require("./adapter-registry.js");
 const skill_harness_js_1 = require("./skill-harness.js");
 const leaderboard_js_1 = require("./leaderboard.js");
+const optimize_js_1 = require("./optimize.js");
 const compile_js_1 = require("./core/compile.js");
 const proofs_js_1 = require("./core/proofs.js");
 const inline_js_1 = require("./core/inline.js");
@@ -32,6 +36,7 @@ const compose_js_1 = require("./core/compose.js");
 const compile_generator_js_1 = require("./core/compile-generator.js");
 const action_gate_js_1 = require("./action-gate.js");
 const agent_runtime_js_1 = require("./adapters/claude-code/agent-runtime.js");
+const effect_region_js_1 = require("./adapters/claude-code/effect-region.js");
 const tool_intercept_js_1 = require("./tool-intercept.js");
 const refs_js_1 = require("./core/refs.js");
 const mcp_js_1 = require("./core/mcp.js");
@@ -633,6 +638,17 @@ function lintExitCode(report) {
         report.integrityErrors > 0 ||
         report.coverageErrors > 0 ||
         report.untestedErrors > 0 ||
+        report.toolContractErrors > 0 ||
+        report.hookEventErrors > 0 ||
+        report.frontmatterSchemaErrors > 0 ||
+        report.mcpConfigErrors > 0 ||
+        report.skillFrontmatterErrors > 0 ||
+        report.mcpToolErrors > 0 ||
+        report.hookScriptErrors > 0 ||
+        report.disallowedToolErrors > 0 ||
+        report.descriptionOverlapErrors > 0 ||
+        report.frontmatterValidErrors > 0 ||
+        report.mcpHookErrors > 0 ||
         report.symbolRefErrors > 0 ||
         report.mcpRefErrors > 0)
         return 2;
@@ -854,6 +870,17 @@ async function runLint(restArgs, flags, config) {
     const json = flags.includes("--json");
     const silent = summary || json;
     const files = findInstructionFiles(restArgs);
+    // Resolve the active harness ONCE so the harness-specific checks below run
+    // against the right adapter's dialect (tool/event catalogs) and surfaces —
+    // not a hard-coded Claude Code default. A subagent-surface rule reports n/a
+    // on a harness without subagents (Codex) rather than scanning nothing.
+    const harnessFlag = harnessFlagFrom(flags);
+    const lintSelection = (0, adapter_registry_js_1.resolveHarnessSelection)({
+        root: process.cwd(),
+        flag: harnessFlag,
+        configHarness: (0, adapter_registry_js_1.normalizeHarnessList)(config?.harness),
+    });
+    const adapter = lintSelection.adapter;
     // 1. Verify hashes and structure
     if (!silent) {
         if (files.length > 0) {
@@ -912,7 +939,41 @@ async function runLint(restArgs, flags, config) {
     // 7b. Untested-surface check — skills/agents/hooks shipping without a test or
     // eval. Warning by default (a nudge, exit 0); set rules.untested-{skill,agent,
     // hook} to "error" to gate CI. See src/test-coverage.ts and docs/rules/.
-    const untested = checkUntestedSurfaces(config, silent);
+    const untested = checkUntestedSurfaces(config, silent, adapter);
+    // 7c. Subagent tool-contract check — cross-reference each subagent's `tools:`
+    // rail against the harness catalog (the moat). n/a on a harness with no
+    // subagents. Off by default unless a severity is configured; warning surfaces
+    // a typo/never-available tool, error gates CI.
+    const toolContract = checkSubagentToolContracts(config, silent, adapter);
+    // 7d. Hook-event check — a hook registered under an event the harness doesn't
+    // define never fires. High-precision (close typos only). Off unless configured.
+    const hookEvents = checkHookEvents(config, silent, adapter);
+    // 7e. Subagent-frontmatter check — a subagent missing required frontmatter
+    // (name + description) won't register. n/a on a harness with no subagents.
+    const frontmatter = checkFrontmatterSchema(config, silent, adapter);
+    // 7f. MCP-config check — a declared MCP server with no command/url can't start.
+    const mcpConfig = checkMcpConfig(config, silent, adapter);
+    // 7g. Skill-frontmatter — RECOMMEND explicit name/description on skills (a
+    // reliable trigger surface). Best-practice nudge; skills load without it.
+    const skillFm = checkSkillFrontmatter(config, silent, adapter);
+    // 7h. MCP tool-resolution — an `mcp__server__tool` in a contract whose server
+    // the plugin doesn't declare can't resolve (the MCP half of the tool moat).
+    const mcpToolResolves = checkMcpToolResolves(config, silent, adapter);
+    // 7i. Hook-script existence — a hook command referencing a missing script file
+    // never runs (matches Anthropic's own `claude plugin validate`).
+    const hookScripts = checkHookScriptExists(config, silent, adapter);
+    // 7j. Disallowed-tools — a `disallowedTools:` block-list typo blocks nothing
+    // (the deny-side mirror of subagent-tool-contract; close-typo only).
+    const disallowedTools = checkDisallowedTools(config, silent, adapter);
+    // 7k. Description-overlap — two model-invocable skills with near-identical
+    // descriptions collide in the selector (deterministic NCD precision proxy).
+    const descriptionOverlap = checkDescriptionOverlap(config, silent, adapter);
+    // 7l. Frontmatter-valid — a `---` block that isn't valid YAML (warn; js-yaml is
+    // stricter than some loaders, so verify before enforcing).
+    const frontmatterValid = checkFrontmatterValid(config, silent, adapter);
+    // 7m. MCP hook-target — a `type: mcp_tool` hook action that's incomplete or
+    // targets an undeclared server (the moat applied to the hook surface).
+    const mcpHookTargets = checkMcpHookTargets(config, silent, adapter);
     // 8. Validate vigiles builder calls inside markdown code blocks. Default
     // is to validate every ref; illustrative blocks opt out via
     // `<!-- vigiles:ignore -->` (single block) or
@@ -956,6 +1017,28 @@ async function runLint(restArgs, flags, config) {
         orphanCount: orphanReport.orphans.length,
         untestedSurfaces: untested.untested,
         untestedErrors: untested.errors,
+        toolContractIssues: toolContract.issues,
+        toolContractErrors: toolContract.errors,
+        hookEventIssues: hookEvents.issues,
+        hookEventErrors: hookEvents.errors,
+        frontmatterSchemaIssues: frontmatter.issues,
+        frontmatterSchemaErrors: frontmatter.errors,
+        mcpConfigIssues: mcpConfig.issues,
+        mcpConfigErrors: mcpConfig.errors,
+        skillFrontmatterIssues: skillFm.issues,
+        skillFrontmatterErrors: skillFm.errors,
+        mcpToolIssues: mcpToolResolves.issues,
+        mcpToolErrors: mcpToolResolves.errors,
+        hookScriptIssues: hookScripts.issues,
+        hookScriptErrors: hookScripts.errors,
+        disallowedToolIssues: disallowedTools.issues,
+        disallowedToolErrors: disallowedTools.errors,
+        descriptionOverlapIssues: descriptionOverlap.issues,
+        descriptionOverlapErrors: descriptionOverlap.errors,
+        frontmatterValidIssues: frontmatterValid.issues,
+        frontmatterValidErrors: frontmatterValid.errors,
+        mcpHookIssues: mcpHookTargets.issues,
+        mcpHookErrors: mcpHookTargets.errors,
         docRefErrors: docRefReport.errors.length,
         symbolRefErrors,
         mcpRefErrors,
@@ -1524,7 +1607,7 @@ function redirectSyncToolTargets(cwd, targets) {
 }
 /** Pillar 1 — specs + types + schema + compile. Scaffolds a spec for every
  * instruction file (so `--lint` always delivers a spec), but never compiles
- * OVER a hand-written file — that is left to the migrate-to-spec skill. */
+ * OVER a hand-written file — that is left to the adopt-spec skill. */
 async function setupPillar1(detected, targetValue, harnesses) {
     const cwd = process.cwd();
     const written = [];
@@ -1549,7 +1632,7 @@ async function setupPillar1(detected, targetValue, harnesses) {
         }
         if (targetExists && !targetHasHash((0, node_path_1.resolve)(cwd, target))) {
             needsMigration.push(target);
-            console.log(`  ${target} already has content — port it into the spec with the migrate-to-spec skill, then \`vigiles compile\`.`);
+            console.log(`  ${target} already has content — adopt it into a spec with the adopt-spec skill, then \`vigiles compile\`.`);
         }
     }
     // Generate types + schema.
@@ -1741,7 +1824,7 @@ function printSetupSummary(opts) {
     console.log("\n---\nSetup complete.\n");
     const nextSteps = [];
     if (needsMigration.length > 0) {
-        nextSteps.push(`Port ${needsMigration.join(", ")} into its spec with the migrate-to-spec skill, then \`npx vigiles compile\``);
+        nextSteps.push(`Adopt ${needsMigration.join(", ")} into a spec with the adopt-spec skill, then \`npx vigiles compile\``);
     }
     else if (specPathsList.length > 0) {
         nextSteps.push(`Edit ${specPathsList.join(", ")} — add your conventions, then \`/strengthen\``);
@@ -1888,16 +1971,16 @@ function checkIntegrityForFiles(files, severity, silent) {
     return severity === "error" ? errorCount : 0;
 }
 /**
- * Apply the per-kind `untested-skill` / `untested-agent` / `untested-hook` rules:
+ * Apply the per-kind `untested-skill` / `untested-subagent` / `untested-hook` rules:
  * find skills/agents/hooks with no test or eval (see src/test-coverage.ts). Each
  * kind is gated by its OWN rule severity — a kind set to `false` is not scanned;
  * "warn" prints but never fails CI; "error" fails (exit 2). Returns the raw
  * untested count plus the severity-gated error count.
  */
-function checkUntestedSurfaces(config, silent) {
+function checkUntestedSurfaces(config, silent, adapter) {
     const rules = config?.rules;
     const skillSev = (0, types_js_1.ruleSeverity)(rules?.["untested-skill"]);
-    const agentSev = (0, types_js_1.ruleSeverity)(rules?.["untested-agent"]);
+    const agentSev = (0, types_js_1.ruleSeverity)(rules?.["untested-subagent"]);
     const hookSev = (0, types_js_1.ruleSeverity)(rules?.["untested-hook"]);
     if (!skillSev && !agentSev && !hookSev)
         return { untested: 0, errors: 0 };
@@ -1906,11 +1989,12 @@ function checkUntestedSurfaces(config, silent) {
     // whichever of the three rules carries them.
     const opts = {
         ...(0, types_js_1.ruleOptions)(rules?.["untested-skill"]),
-        ...(0, types_js_1.ruleOptions)(rules?.["untested-agent"]),
+        ...(0, types_js_1.ruleOptions)(rules?.["untested-subagent"]),
         ...(0, types_js_1.ruleOptions)(rules?.["untested-hook"]),
     };
     const report = (0, test_coverage_js_1.findUntestedSurfaces)({
         basePath: process.cwd(),
+        layout: adapter.layout,
         skills: skillSev !== false,
         agents: agentSev !== false,
         hooks: hookSev !== false,
@@ -1931,6 +2015,363 @@ function checkUntestedSurfaces(config, silent) {
         errors: report.untested.filter((s) => sevFor(s.kind) === "error").length,
     };
 }
+/**
+ * A surface-scoped rule (subagent / shell-hook) is configured, but the active
+ * harness doesn't have that surface. Report it as **n/a** — loud, not silent (the
+ * no-silent-skips ethos): the rule isn't failing and isn't passing, it simply
+ * doesn't apply to this harness. Never counts toward issues/errors.
+ */
+function reportNotApplicable(check, surface, adapter, silent) {
+    if (silent)
+        return;
+    console.log(`\n${check}:\n`);
+    console.log(`  – n/a — ${adapter.name} has no ${surface}`);
+}
+/**
+ * Apply the `subagent-tool-contract` rule: cross-reference every subagent's `tools:`
+ * rail against the harness tool catalog (the moat — "valid is not true"). Flags
+ * only the HIGH-CONFIDENCE issues (a never-available tool, or a close typo) via
+ * the shared `confidentToolIssues` detector — the same code `scan` and
+ * `compileAgent` use (one-detector-no-drift), so a bare unrecognized tool
+ * (plugin/MCP-provided) is never a false alarm. Warning by default; set
+ * `subagent-tool-contract: "error"` to gate CI. Returns the issue + error counts.
+ */
+function checkSubagentToolContracts(config, silent, adapter) {
+    const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["subagent-tool-contract"]);
+    if (!sev)
+        return { issues: 0, errors: 0 };
+    if (!adapter.capabilities.subagents) {
+        reportNotApplicable("Subagent tool-contract check", "subagents", adapter, silent);
+        return { issues: 0, errors: 0 };
+    }
+    // Reuse the loader's already-resolved, layout+dialect-driven agents (the same
+    // `scan` detector — one-detector-no-drift) instead of re-globbing a hard-coded
+    // `agents/` path, so a harness with a different subagent dir Just Works.
+    let agents;
+    try {
+        agents = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).agents;
+    }
+    catch {
+        return { issues: 0, errors: 0 };
+    }
+    let issues = 0;
+    let printedHeader = false;
+    for (const agent of agents) {
+        if (agent.toolIssues.length === 0)
+            continue;
+        issues += agent.toolIssues.length;
+        if (!silent) {
+            if (!printedHeader) {
+                console.log("\nSubagent tool-contract check:\n");
+                printedHeader = true;
+            }
+            for (const issue of agent.toolIssues) {
+                console.log(`  ${sev === "error" ? "✗" : "⚠"} ${agent.path}: ${issue.message}`);
+                ghAnnotate(sev === "error" ? "error" : "warning", issue.message, agent.path);
+            }
+        }
+    }
+    return { issues, errors: sev === "error" ? issues : 0 };
+}
+/**
+ * Apply the `hook-events` rule: flag a hook registered under an event name the
+ * harness doesn't define (a typo → the hook never fires). Reuses `scanPlugin`'s
+ * `hookEventIssues` (the shared detector, high-precision: close typos only, never
+ * a framework/custom event). Warning by default; "error" gates CI.
+ */
+function checkHookEvents(config, silent, adapter) {
+    const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["hook-events"]);
+    if (!sev)
+        return { issues: 0, errors: 0 };
+    if (!adapter.capabilities.shellHooks) {
+        reportNotApplicable("Hook-event check", "shell hooks", adapter, silent);
+        return { issues: 0, errors: 0 };
+    }
+    let found;
+    try {
+        found = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).hookEventIssues;
+    }
+    catch {
+        return { issues: 0, errors: 0 };
+    }
+    if (found.length > 0 && !silent) {
+        console.log("\nHook-event check:\n");
+        for (const issue of found) {
+            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${issue.message}`);
+            ghAnnotate(sev === "error" ? "error" : "warning", issue.message);
+        }
+    }
+    return { issues: found.length, errors: sev === "error" ? found.length : 0 };
+}
+/**
+ * Apply the `subagent-frontmatter` rule. Two kinds of subagent-frontmatter defect, one
+ * rule: (1) a subagent MISSING a required field (`name`/`description`) — it won't
+ * register; (2) a subagent with an INVALID `model:`/`color:` value (a close typo
+ * of a real one) — it silently falls back / is ignored. Reuses `scanPlugin`'s
+ * `frontmatterIssues` + `frontmatterValueIssues`. Warning by default; "error" gates CI.
+ */
+function checkFrontmatterSchema(config, silent, adapter) {
+    const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["subagent-frontmatter"]);
+    if (!sev)
+        return { issues: 0, errors: 0 };
+    if (!adapter.capabilities.subagents) {
+        reportNotApplicable("Subagent-frontmatter check", "subagents", adapter, silent);
+        return { issues: 0, errors: 0 };
+    }
+    let found;
+    try {
+        const r = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect);
+        found = [...r.frontmatterIssues, ...r.frontmatterValueIssues];
+    }
+    catch {
+        return { issues: 0, errors: 0 };
+    }
+    if (found.length > 0 && !silent) {
+        console.log("\nFrontmatter-schema check:\n");
+        for (const issue of found) {
+            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${issue.message}`);
+            ghAnnotate(sev === "error" ? "error" : "warning", issue.message, issue.path);
+        }
+    }
+    return { issues: found.length, errors: sev === "error" ? found.length : 0 };
+}
+/**
+ * Apply the `skill-frontmatter` rule: RECOMMEND (not require) that a SKILL.md
+ * declares an explicit `name` + `description` rather than relying on the
+ * dir-name / first-paragraph fallbacks — a more reliable trigger surface. The
+ * skill still LOADS without them, so this is a best-practice nudge: warn by
+ * default; set "error" to enforce it on your own skills. Reuses `scanPlugin`'s
+ * `skillMetaIssues`.
+ */
+function checkSkillFrontmatter(config, silent, adapter) {
+    const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["skill-frontmatter"]);
+    if (!sev)
+        return { issues: 0, errors: 0 };
+    let found;
+    try {
+        found = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).skillMetaIssues;
+    }
+    catch {
+        return { issues: 0, errors: 0 };
+    }
+    if (found.length > 0 && !silent) {
+        console.log("\nSkill-frontmatter check:\n");
+        for (const issue of found) {
+            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${issue.message}`);
+            ghAnnotate(sev === "error" ? "error" : "warning", issue.message, issue.path);
+        }
+    }
+    return { issues: found.length, errors: sev === "error" ? found.length : 0 };
+}
+/**
+ * Apply the `mcp-config` rule: a declared MCP server with neither a `command`
+ * (stdio) nor a `url` (http/sse) can't start. Reuses `scanPlugin`'s `mcpIssues`.
+ * Warning by default; "error" gates CI.
+ */
+function checkMcpConfig(config, silent, adapter) {
+    const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["mcp-config"]);
+    if (!sev)
+        return { issues: 0, errors: 0 };
+    let found;
+    try {
+        found = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).mcpIssues;
+    }
+    catch {
+        return { issues: 0, errors: 0 };
+    }
+    if (found.length > 0 && !silent) {
+        console.log("\nMCP-config check:\n");
+        for (const issue of found) {
+            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${issue.message}`);
+            ghAnnotate(sev === "error" ? "error" : "warning", issue.message);
+        }
+    }
+    return { issues: found.length, errors: sev === "error" ? found.length : 0 };
+}
+/**
+ * Apply the `disallowed-tools-contract` rule: a subagent's `disallowedTools:`
+ * block-list entry that's a close typo of a real tool blocks NOTHING — the tool
+ * it was meant to deny stays available, silently. Reuses `scanPlugin`'s per-agent
+ * `disallowedToolIssues` (close-typo only — high-precision). Warning by default;
+ * "error" gates CI.
+ */
+function checkDisallowedTools(config, silent, adapter) {
+    const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["disallowed-tools-contract"]);
+    if (!sev)
+        return { issues: 0, errors: 0 };
+    if (!adapter.capabilities.subagents) {
+        reportNotApplicable("Disallowed-tools check", "subagents", adapter, silent);
+        return { issues: 0, errors: 0 };
+    }
+    let found;
+    try {
+        found = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).agents.flatMap((a) => a.disallowedToolIssues.map((i) => ({ message: i.message, path: a.path })));
+    }
+    catch {
+        return { issues: 0, errors: 0 };
+    }
+    if (found.length > 0 && !silent) {
+        console.log("\nDisallowed-tools check:\n");
+        for (const issue of found) {
+            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${issue.path}: ${issue.message}`);
+            ghAnnotate(sev === "error" ? "error" : "warning", issue.message, issue.path);
+        }
+    }
+    return { issues: found.length, errors: sev === "error" ? found.length : 0 };
+}
+/**
+ * Apply the `frontmatter-valid` rule: a skill/agent `---` block that EXISTS but
+ * isn't valid YAML — fields may not parse as intended. Reuses `scanPlugin`'s
+ * `malformedFrontmatter`. HONEST caveat (see docs/rules/frontmatter-valid.md):
+ * js-yaml is stricter than some loaders, so a one-line `description:` with a
+ * colon / `<example>` is flagged though it may still load — hence WARN by default
+ * (verify before setting "error").
+ */
+function checkFrontmatterValid(config, silent, adapter) {
+    const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["frontmatter-valid"]);
+    if (!sev)
+        return { issues: 0, errors: 0 };
+    let found;
+    try {
+        found = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).malformedFrontmatter;
+    }
+    catch {
+        return { issues: 0, errors: 0 };
+    }
+    if (found.length > 0 && !silent) {
+        console.log("\nFrontmatter-validity check:\n");
+        for (const issue of found) {
+            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${issue.message}`);
+            ghAnnotate(sev === "error" ? "error" : "warning", issue.message, issue.path);
+        }
+    }
+    return { issues: found.length, errors: sev === "error" ? found.length : 0 };
+}
+/**
+ * Apply the `description-overlap` rule: two model-invocable skills with
+ * near-identical descriptions collide in the selector — the wrong one fires. A
+ * deterministic NCD proxy for a `--trigger`-class precision bug. Reuses
+ * `scanPlugin`'s `descriptionOverlaps` (calibrated FP-safe: only basically
+ * identical text). Warning by default; "error" gates CI.
+ */
+function checkDescriptionOverlap(config, silent, adapter) {
+    const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["description-overlap"]);
+    if (!sev)
+        return { issues: 0, errors: 0 };
+    let found;
+    try {
+        found = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).descriptionOverlaps;
+    }
+    catch {
+        return { issues: 0, errors: 0 };
+    }
+    if (found.length > 0 && !silent) {
+        console.log("\nDescription-overlap check:\n");
+        for (const issue of found) {
+            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${issue.message}`);
+            ghAnnotate(sev === "error" ? "error" : "warning", issue.message);
+        }
+    }
+    return { issues: found.length, errors: sev === "error" ? found.length : 0 };
+}
+/**
+ * Apply the `mcp-hook-target-resolves` rule: a `type: "mcp_tool"` hook action
+ * that's incomplete (no `server`/`tool`) or targets a server the plugin doesn't
+ * declare — the hook silently never dispatches. Reuses `scanPlugin`'s
+ * `mcpHookIssues` (high-precision: declared-set gated, built-ins allowlisted).
+ * Warning by default; "error" gates CI.
+ */
+function checkMcpHookTargets(config, silent, adapter) {
+    const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["mcp-hook-target-resolves"]);
+    if (!sev)
+        return { issues: 0, errors: 0 };
+    if (!adapter.capabilities.shellHooks) {
+        reportNotApplicable("MCP hook-target check", "shell hooks", adapter, silent);
+        return { issues: 0, errors: 0 };
+    }
+    let found;
+    try {
+        found = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).mcpHookIssues;
+    }
+    catch {
+        return { issues: 0, errors: 0 };
+    }
+    if (found.length > 0 && !silent) {
+        console.log("\nMCP hook-target check:\n");
+        for (const issue of found) {
+            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${issue.message}`);
+            ghAnnotate(sev === "error" ? "error" : "warning", issue.message);
+        }
+    }
+    return { issues: found.length, errors: sev === "error" ? found.length : 0 };
+}
+/**
+ * Apply the `hook-script-exists` rule: a hook command references a script file
+ * that doesn't exist on disk (with `${CLAUDE_PLUGIN_ROOT}` resolved) → the hook
+ * silently never runs. Reuses `scanPlugin`'s `hooks` (status "missing"); the
+ * shared resolver already excludes the FP-prone cases (unresolved vars,
+ * existence-guarded one-liners, inline commands). Matches Anthropic's own
+ * `claude plugin validate`. Warning by default; "error" gates CI.
+ */
+function checkHookScriptExists(config, silent, adapter) {
+    const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["hook-script-exists"]);
+    if (!sev)
+        return { issues: 0, errors: 0 };
+    if (!adapter.capabilities.shellHooks) {
+        reportNotApplicable("Hook-script existence check", "shell hooks", adapter, silent);
+        return { issues: 0, errors: 0 };
+    }
+    let missing;
+    try {
+        missing = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).hooks.filter((h) => h.status === "missing");
+    }
+    catch {
+        return { issues: 0, errors: 0 };
+    }
+    if (missing.length > 0 && !silent) {
+        console.log("\nHook-script existence check:\n");
+        for (const h of missing) {
+            const msg = `hook script "${h.script}" is referenced but missing — the hook never runs.`;
+            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${msg}`);
+            ghAnnotate(sev === "error" ? "error" : "warning", msg);
+        }
+    }
+    return {
+        issues: missing.length,
+        errors: sev === "error" ? missing.length : 0,
+    };
+}
+/**
+ * Apply the `mcp-tool-resolves` rule: an `mcp__server__tool` in a subagent's
+ * contract whose server isn't in the plugin's declared `mcpServers` can't resolve
+ * (the MCP half of the tool moat). Reuses `scanPlugin`'s per-agent `mcpToolIssues`
+ * — high-precision (gated on a declared set, built-ins allowlisted, the
+ * plugin-namespaced form skipped). Warning by default; "error" gates CI.
+ */
+function checkMcpToolResolves(config, silent, adapter) {
+    const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["mcp-tool-resolves"]);
+    if (!sev)
+        return { issues: 0, errors: 0 };
+    if (!adapter.capabilities.subagents) {
+        reportNotApplicable("MCP tool-resolution check", "subagents", adapter, silent);
+        return { issues: 0, errors: 0 };
+    }
+    let found;
+    try {
+        found = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).agents.flatMap((a) => a.mcpToolIssues.map((i) => ({ message: i.message, path: a.path })));
+    }
+    catch {
+        return { issues: 0, errors: 0 };
+    }
+    if (found.length > 0 && !silent) {
+        console.log("\nMCP tool-resolution check:\n");
+        for (const issue of found) {
+            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${issue.path}: ${issue.message}`);
+            ghAnnotate(sev === "error" ? "error" : "warning", issue.message, issue.path);
+        }
+    }
+    return { issues: found.length, errors: sev === "error" ? found.length : 0 };
+}
 /**
  * Apply the configured coverage thresholds. Returns the number of failing
  * thresholds (so the lint can fail CI when severity is "error").
@@ -2008,6 +2449,43 @@ function findInstructionFiles(restArgs) {
     }
     return files;
 }
+/** Value of a `--flag=value` arg (the `=` form, so it never collides with a positional). */
+function flagValue(args, name) {
+    return args.find((a) => a.startsWith(`${name}=`))?.slice(name.length + 1);
+}
+/**
+ * The `scan --trigger` behavioral column: load the author-supplied per-skill
+ * prompt sets, probe the plugin's model-invocable skills, print the column.
+ * Model-gated and opt-in — the structural scan above stays deterministic.
+ */
+async function handleScanTrigger(root, args, json, harness) {
+    const promptsPath = flagValue(args, "--prompts");
+    if (!promptsPath) {
+        console.error("scan --trigger needs --prompts=<file.json> (a map of skill name → { prompts, irrelevant }).");
+        process.exitCode = 2;
+        return;
+    }
+    let promptSet;
+    try {
+        promptSet = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.resolve)(promptsPath), "utf-8"));
+    }
+    catch (e) {
+        console.error(`scan --trigger: could not read --prompts file "${promptsPath}": ${e instanceof Error ? e.message : String(e)}`);
+        process.exitCode = 2;
+        return;
+    }
+    const concurrencyRaw = flagValue(args, "--concurrency");
+    const minPromptsRaw = flagValue(args, "--min-prompts");
+    const report = await (0, scan_behavioral_js_1.probePluginTriggers)(root, promptSet, {
+        concurrency: concurrencyRaw ? Number(concurrencyRaw) : undefined,
+        minPrompts: minPromptsRaw ? Number(minPromptsRaw) : undefined,
+        model: flagValue(args, "--model"),
+        harness,
+    });
+    console.log(json
+        ? JSON.stringify(report, null, 2)
+        : `\n${(0, scan_behavioral_js_1.formatBehavioralReport)(report)}`);
+}
 function handleGenerateTypes(args, restArgs) {
     const checkOnly = args.includes("--check");
     const outPath = restArgs[0] ?? ".vigiles/generated.d.ts";
@@ -2154,6 +2632,129 @@ function handleRunScripts(kind, args, restArgs) {
         process.exit(1);
     }
 }
+/** Parse the `--harness=<name>` override out of an argv list (the one definition). */
+function harnessFlagFrom(argv) {
+    return argv
+        .find((a) => a.startsWith("--harness="))
+        ?.slice("--harness=".length);
+}
+/**
+ * `vigiles explain <dir> [name]` — the deterministic WHY behind a low score (C4):
+ * scan a plugin and surface the structural CAUSE of a behavioral symptom + the
+ * one-line fix. No model — it reads the same `ScanReport` `scan` computes. An
+ * optional surface name narrows to one underperforming skill/agent (the
+ * optimizer's call). `--json` for the agent-consumable shape, `--harness=` to
+ * override detection.
+ */
+function handleExplain(restArgs, args) {
+    const dir = (0, node_path_1.resolve)(restArgs[0] ?? ".");
+    const surface = restArgs[1];
+    const json = args.includes("--json");
+    const harnessFlag = harnessFlagFrom(args);
+    const adapter = harnessFlag
+        ? (0, adapter_registry_js_1.resolveAdapter)(dir, harnessFlag)
+        : (0, adapter_registry_js_1.detectAdapterResult)(dir).adapter;
+    const report = (0, scan_js_1.scanPlugin)(dir, adapter.layout, adapter.dialect);
+    const exps = surface ? (0, score_explainer_js_1.explainSurface)(report, surface) : (0, score_explainer_js_1.explainScore)(report);
+    if (json) {
+        console.log(JSON.stringify(exps, null, 2));
+        return;
+    }
+    if (surface)
+        console.log(`Explaining "${surface}":\n`);
+    console.log((0, score_explainer_js_1.formatExplanations)(exps));
+}
+/**
+ * The plugin's declared name for the namespaced skill id, read from the layout's
+ * manifest (adapter-aware path, not a hardcoded `.claude-plugin/`), falling back to
+ * the dir basename. JSON manifests only for now (a TOML/Codex manifest → basename).
+ */
+function pluginNameFor(dir, manifestPath) {
+    try {
+        const manifest = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.resolve)(dir, manifestPath), "utf-8"));
+        if (typeof manifest.name === "string" && manifest.name)
+            return manifest.name;
+    }
+    catch {
+        /* missing / non-JSON manifest → fall back */
+    }
+    return (0, node_path_1.basename)(dir);
+}
+/** Enrich an untested Surface with the metadata the right template needs. */
+function scaffoldInputFor(s, report, pluginName) {
+    const base = { kind: s.kind, name: s.name, path: s.path };
+    switch (s.kind) {
+        case "skill": {
+            const sk = report.skills.find((x) => x.name === s.name);
+            return { ...base, pluginName, userInvoked: sk?.userInvoked };
+        }
+        case "agent": {
+            const ag = report.agents.find((x) => x.name === s.name);
+            return { ...base, tools: ag?.tools ?? null };
+        }
+        case "hook":
+            return { ...base, hookCommand: `bash ${s.path}` };
+    }
+}
+/**
+ * `vigiles scaffold-test [dir]` — generate a runnable STARTER test for each
+ * untested skill/agent/hook (B1, test-gen from free-form). Reuses the
+ * untested-surface detector for the list + `scan` for the metadata, then emits the
+ * cheapest meaningful tier per kind (hook → `runHook`, skill → `measureTriggerRate`,
+ * subagent → `runHarnessTest`) at the surface's suggested test path. Dry-run by
+ * default (prints the scaffolds); `--write` creates the files (never clobbering an
+ * existing one); `--json` for the agent-consumable `{ path, content }[]`.
+ */
+function handleScaffoldTest(restArgs, args) {
+    const dir = (0, node_path_1.resolve)(restArgs[0] ?? ".");
+    const write = args.includes("--write");
+    const json = args.includes("--json");
+    const harnessFlag = harnessFlagFrom(args);
+    const adapter = harnessFlag
+        ? (0, adapter_registry_js_1.resolveAdapter)(dir, harnessFlag)
+        : (0, adapter_registry_js_1.detectAdapterResult)(dir).adapter;
+    const { untested } = (0, test_coverage_js_1.findUntestedSurfaces)({
+        basePath: dir,
+        layout: adapter.layout,
+    });
+    const report = (0, scan_js_1.scanPlugin)(dir, adapter.layout, adapter.dialect);
+    const pluginName = pluginNameFor(dir, adapter.layout.manifestPath);
+    const scaffolds = untested.map((s) => (0, scaffold_test_js_1.scaffoldTest)(scaffoldInputFor(s, report, pluginName)));
+    if (json) {
+        console.log(JSON.stringify(scaffolds, null, 2));
+        return;
+    }
+    if (!write) {
+        console.log((0, scaffold_test_js_1.formatScaffolds)(scaffolds));
+        for (const s of scaffolds) {
+            console.log(`\n# ${s.path}\n`);
+            console.log(s.content);
+        }
+        if (scaffolds.length > 0) {
+            console.log("Re-run with --write to create these files.");
+        }
+        return;
+    }
+    const written = [];
+    const skipped = [];
+    for (const s of scaffolds) {
+        const target = (0, node_path_1.resolve)(dir, s.path);
+        if ((0, node_fs_1.existsSync)(target)) {
+            skipped.push(s.path);
+            continue;
+        }
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(target), { recursive: true });
+        (0, node_fs_1.writeFileSync)(target, s.content);
+        written.push(s.path);
+    }
+    for (const p of written)
+        console.log(`✓ wrote ${p}`);
+    for (const p of skipped)
+        console.log(`⊘ skipped ${p} (already exists)`);
+    if (written.length === 0 && skipped.length === 0) {
+        console.log("Nothing to scaffold — every surface already has a test.");
+    }
+}
 function printUsage(command) {
     console.log("vigiles — compile typed specs to instruction files");
     console.log("");
@@ -2163,6 +2764,8 @@ function printUsage(command) {
     console.log("  vigiles lint [files...]        Verify references, find gaps in instruction files");
     console.log("  vigiles test [files...]        Run *.harness.mjs deterministic harness tests");
     console.log("  vigiles eval [files...]        Run *.eval.mjs real-model harness evals (--trials=N, --min=N, --no-skip)");
+    console.log("  vigiles explain <dir> [name]   Deterministic WHY a skill/agent underperforms + the fix (--json, --harness=)");
+    console.log("  vigiles scaffold-test [dir]    Generate a starter test for each untested skill/agent/hook (--write, --json)");
     console.log("");
     console.log("Examples:");
     console.log("  vigiles init                 Auto-detect project, create specs, wire CI");
@@ -2272,6 +2875,42 @@ function skillStartCommand(target) {
     (0, skill_runtime_js_1.setActiveSkill)(process.cwd(), target);
     console.log(`Active skill: ${target}`);
 }
+/**
+ * PreToolUse-hook entrypoint: enforce the active skill's declared purity floor.
+ * Reads the tool event on stdin, parses the `vigiles:purity:` marker from the
+ * active skill's compiled SKILL.md, and blocks (exit 2 + reason on stderr) any
+ * tool call that violates the declared floor — refining `Bash` by the live
+ * command via `isReadOnlyBash`. Skills have no tools-allowlist rail; this gate
+ * is purity-only. Mirrors `agentHookCommand` for skills.
+ */
+function skillToolHookCommand() {
+    let raw = "";
+    try {
+        raw = (0, node_fs_1.readFileSync)(0, "utf-8");
+    }
+    catch {
+        /* no stdin */
+    }
+    let tool = "";
+    let command;
+    try {
+        const parsed = JSON.parse(raw);
+        tool = parsed.tool_name ?? "";
+        if (typeof parsed.tool_input?.command === "string") {
+            command = parsed.tool_input.command;
+        }
+    }
+    catch {
+        /* malformed input → no tool, allow */
+    }
+    if (!tool)
+        return;
+    const decision = (0, skill_runtime_js_1.evaluateSkillPreToolUse)(process.cwd(), tool, command);
+    if (!decision.allow) {
+        console.error(decision.message);
+        process.exit(2);
+    }
+}
 /**
  * PreToolUse-hook entrypoint: enforce the active subagent's allowed-tools
  * contract. Reads the tool event on stdin, parses the active agent's compiled
@@ -2287,15 +2926,20 @@ function agentHookCommand() {
         /* no stdin */
     }
     let tool = "";
+    let command;
     try {
-        tool = JSON.parse(raw).tool_name ?? "";
+        const parsed = JSON.parse(raw);
+        tool = parsed.tool_name ?? "";
+        if (typeof parsed.tool_input?.command === "string") {
+            command = parsed.tool_input.command;
+        }
     }
     catch {
         /* malformed input → no tool, allow */
     }
     if (!tool)
         return;
-    const decision = (0, agent_runtime_js_1.evaluatePreToolUse)(process.cwd(), tool);
+    const decision = (0, agent_runtime_js_1.evaluatePreToolUse)(process.cwd(), tool, command);
     if (!decision.allow) {
         console.error(decision.message);
         process.exit(2);
@@ -2349,6 +2993,9 @@ function handleSkillCommand(command, restArgs) {
         case "skill-hook":
             skillHookCommand();
             return true;
+        case "skill-tool-hook":
+            skillToolHookCommand();
+            return true;
         case "agent-start":
             agentStartCommand(restArgs[0]);
             return true;
@@ -2370,6 +3017,13 @@ function handleSkillCommand(command, restArgs) {
         case "refs-hook":
             refsHookCommand();
             return true;
+        case "effect-enter":
+            (0, effect_region_js_1.setEffectActive)(process.cwd());
+            console.log("Effect boundary entered.");
+            return true;
+        case "effect-exit":
+            (0, effect_region_js_1.clearEffectActive)(process.cwd());
+            return true;
         default:
             return false;
     }
@@ -2540,9 +3194,7 @@ async function main() {
                 console.log("Run `vigiles init` to create one.");
                 process.exit(0);
             }
-            const harnessFlag = args
-                .find((a) => a.startsWith("--harness="))
-                ?.slice("--harness=".length);
+            const harnessFlag = harnessFlagFrom(args);
             const valid = await compile(specs, config, { harnessFlag });
             console.log("");
             if (valid) {
@@ -2574,21 +3226,42 @@ async function main() {
         case "scan": {
             const dirs = restArgs.length > 0 ? restArgs : ["."];
             const json = args.includes("--json");
-            if (dirs.length > 1) {
+            // A single dir that's a marketplace (e.g. wshobson/agents' 80+ plugins
+            // under one marketplace.json) expands into its members and ranks them.
+            const market = dirs.length === 1 ? (0, scan_js_1.inspectMarketplace)((0, node_path_1.resolve)(dirs[0])) : null;
+            const targets = market && market.onDisk.length > 0 ? [...market.onDisk] : dirs;
+            const wantTrigger = args.includes("--trigger");
+            if (market && market.onDisk.length === 0 && market.total > 0) {
+                // A CURATED marketplace — every member is an external git/url plugin, so
+                // there's nothing on disk to scan. Say so honestly instead of falling
+                // through to a misleading "empty machine / no structural issues" report
+                // (obra/superpowers-marketplace, anthropics/claude-plugins-community).
+                if (json) {
+                    console.log(JSON.stringify(market, null, 2));
+                }
+                else {
+                    console.log(`Marketplace "${market.name}": ${String(market.total)} plugin(s), all external ` +
+                        `(url/git sources, not on disk).\n` +
+                        `Nothing to scan here — clone a member plugin and scan that, or scan a ` +
+                        `marketplace that vendors its plugins in-tree.`);
+                }
+            }
+            else if (targets.length > 1) {
                 // Multiple targets → rank them (the leaderboard engine).
-                const scores = (0, leaderboard_js_1.rankPlugins)(dirs);
+                const scores = (0, leaderboard_js_1.rankPlugins)(targets);
                 console.log(json ? JSON.stringify(scores, null, 2) : (0, leaderboard_js_1.formatLeaderboard)(scores));
+                if (wantTrigger) {
+                    console.log("\n⚠ --trigger (behavioral column) runs per single plugin; not yet wired into the leaderboard. Scan one plugin dir to probe it.");
+                }
             }
             else {
-                const root = (0, node_path_1.resolve)(dirs[0]);
-                const harnessFlag = args
-                    .find((a) => a.startsWith("--harness="))
-                    ?.slice("--harness=".length);
+                const root = (0, node_path_1.resolve)(targets[0]);
+                const harnessFlag = harnessFlagFrom(args);
                 const det = (0, adapter_registry_js_1.detectAdapterResult)(root);
                 const adapter = harnessFlag
                     ? (0, adapter_registry_js_1.resolveAdapter)(root, harnessFlag)
                     : det.adapter;
-                const report = (0, scan_js_1.scanPlugin)(dirs[0], adapter.layout);
+                const report = (0, scan_js_1.scanPlugin)(targets[0], adapter.layout, adapter.dialect);
                 if (!json) {
                     console.log(`Detected harness: ${adapter.name}`);
                     if (!harnessFlag && det.ambiguousWith.length > 0) {
@@ -2596,10 +3269,28 @@ async function main() {
                     }
                     console.log("");
                 }
-                console.log(json ? JSON.stringify(report, null, 2) : (0, scan_js_1.formatScanReport)(report));
+                if (args.includes("--fix-plan")) {
+                    // The deterministic optimization lens on the SAME report: health score
+                    // + the ranked free fixes to clear before measuring (the A2 spine).
+                    const plan = (0, optimize_js_1.optimize)(report);
+                    console.log(json ? JSON.stringify(plan, null, 2) : (0, optimize_js_1.formatOptimize)(plan));
+                }
+                else {
+                    console.log(json ? JSON.stringify(report, null, 2) : (0, scan_js_1.formatScanReport)(report));
+                }
+                if (wantTrigger) {
+                    const harness = adapter.name === "codex" ? "codex" : "claude-code";
+                    await handleScanTrigger(root, args, json, harness);
+                }
             }
             break;
         }
+        case "explain":
+            handleExplain(restArgs, args);
+            break;
+        case "scaffold-test":
+            handleScaffoldTest(restArgs, args);
+            break;
         // --- Plumbing ---
         case "generate-types":
             handleGenerateTypes(args, restArgs);