vigiles 5.1.0 → 5.2.0

package/dist/cli.js

@@ -19,14 +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 tool_contract_js_1 = require("./core/tool-contract.js");
-const agent_runtime_js_1 = require("./adapters/claude-code/agent-runtime.js");
-const dialect_js_1 = require("./adapters/claude-code/dialect.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");
@@ -35,7 +35,8 @@ const generate_schema_js_1 = require("./core/generate-schema.js");
 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_2 = require("./adapters/claude-code/agent-runtime.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");
@@ -869,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) {
@@ -927,40 +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);
-    // 7c. Agent tool-contract check — cross-reference each subagent's `tools:` rail
-    // against the harness catalog (the moat). Off by default unless a severity is
-    // configured; warning surfaces a typo/never-available tool, error gates CI.
-    const toolContract = checkAgentToolContracts(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);
-    // 7e. Frontmatter-schema check — a skill/agent missing required frontmatter
-    // (name; agents also description) won't load/register. High-confidence.
-    const frontmatter = checkFrontmatterSchema(config, silent);
+    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);
+    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);
+    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);
+    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);
+    const hookScripts = checkHookScriptExists(config, silent, adapter);
     // 7j. Disallowed-tools — a `disallowedTools:` block-list typo blocks nothing
-    // (the deny-side mirror of agent-tool-contract; close-typo only).
-    const disallowedTools = checkDisallowedTools(config, silent);
+    // (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);
+    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);
+    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);
+    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
@@ -1594,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 = [];
@@ -1619,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.
@@ -1811,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\``);
@@ -1958,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 };
@@ -1976,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,
@@ -2002,47 +2016,58 @@ function checkUntestedSurfaces(config, silent) {
     };
 }
 /**
- * Apply the `agent-tool-contract` rule: cross-reference every subagent's `tools:`
+ * 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
- * `agent-tool-contract: "error"` to gate CI. Returns the issue + error counts.
+ * `subagent-tool-contract: "error"` to gate CI. Returns the issue + error counts.
  */
-function checkAgentToolContracts(config, silent) {
-    const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["agent-tool-contract"]);
+function checkSubagentToolContracts(config, silent, adapter) {
+    const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["subagent-tool-contract"]);
     if (!sev)
         return { issues: 0, errors: 0 };
-    const files = (0, glob_1.globSync)(["agents/*.md", ".claude/agents/*.md"], {
-        cwd: process.cwd(),
-        ignore: ["**/*.spec.ts"],
-    });
+    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 rel of files.sort()) {
-        let md;
-        try {
-            md = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(process.cwd(), rel), "utf-8");
-        }
-        catch {
-            continue;
-        }
-        const tools = (0, agent_runtime_js_1.parseAgentTools)(md);
-        if (tools === null)
-            continue; // no contract → inherits all (a different rule)
-        const found = (0, tool_contract_js_1.confidentToolIssues)((0, tool_contract_js_1.verifyToolContract)(tools, dialect_js_1.claudeCodeDialect));
-        if (found.length === 0)
+    for (const agent of agents) {
+        if (agent.toolIssues.length === 0)
             continue;
-        issues += found.length;
+        issues += agent.toolIssues.length;
         if (!silent) {
             if (!printedHeader) {
-                console.log("\nAgent tool-contract check:\n");
+                console.log("\nSubagent tool-contract check:\n");
                 printedHeader = true;
             }
-            for (const issue of found) {
-                console.log(`  ${sev === "error" ? "✗" : "⚠"} ${rel}: ${issue.message}`);
-                ghAnnotate(sev === "error" ? "error" : "warning", issue.message, rel);
+            for (const issue of agent.toolIssues) {
+                console.log(`  ${sev === "error" ? "✗" : "⚠"} ${agent.path}: ${issue.message}`);
+                ghAnnotate(sev === "error" ? "error" : "warning", issue.message, agent.path);
             }
         }
     }
@@ -2054,13 +2079,17 @@ function checkAgentToolContracts(config, silent) {
  * `hookEventIssues` (the shared detector, high-precision: close typos only, never
  * a framework/custom event). Warning by default; "error" gates CI.
  */
-function checkHookEvents(config, silent) {
+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()).hookEventIssues;
+        found = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).hookEventIssues;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -2075,19 +2104,23 @@ function checkHookEvents(config, silent) {
     return { issues: found.length, errors: sev === "error" ? found.length : 0 };
 }
 /**
- * Apply the `agent-frontmatter` rule. Two kinds of agent-frontmatter defect, one
+ * 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) {
-    const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["agent-frontmatter"]);
+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());
+        const r = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect);
         found = [...r.frontmatterIssues, ...r.frontmatterValueIssues];
     }
     catch {
@@ -2110,13 +2143,13 @@ function checkFrontmatterSchema(config, silent) {
  * default; set "error" to enforce it on your own skills. Reuses `scanPlugin`'s
  * `skillMetaIssues`.
  */
-function checkSkillFrontmatter(config, silent) {
+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()).skillMetaIssues;
+        found = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).skillMetaIssues;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -2135,13 +2168,13 @@ function checkSkillFrontmatter(config, silent) {
  * (stdio) nor a `url` (http/sse) can't start. Reuses `scanPlugin`'s `mcpIssues`.
  * Warning by default; "error" gates CI.
  */
-function checkMcpConfig(config, silent) {
+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()).mcpIssues;
+        found = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).mcpIssues;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -2162,13 +2195,17 @@ function checkMcpConfig(config, silent) {
  * `disallowedToolIssues` (close-typo only — high-precision). Warning by default;
  * "error" gates CI.
  */
-function checkDisallowedTools(config, silent) {
+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()).agents.flatMap((a) => a.disallowedToolIssues.map((i) => ({ message: i.message, path: a.path })));
+        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 };
@@ -2190,13 +2227,13 @@ function checkDisallowedTools(config, silent) {
  * colon / `<example>` is flagged though it may still load — hence WARN by default
  * (verify before setting "error").
  */
-function checkFrontmatterValid(config, silent) {
+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()).malformedFrontmatter;
+        found = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).malformedFrontmatter;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -2217,13 +2254,13 @@ function checkFrontmatterValid(config, silent) {
  * `scanPlugin`'s `descriptionOverlaps` (calibrated FP-safe: only basically
  * identical text). Warning by default; "error" gates CI.
  */
-function checkDescriptionOverlap(config, silent) {
+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()).descriptionOverlaps;
+        found = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).descriptionOverlaps;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -2244,13 +2281,17 @@ function checkDescriptionOverlap(config, silent) {
  * `mcpHookIssues` (high-precision: declared-set gated, built-ins allowlisted).
  * Warning by default; "error" gates CI.
  */
-function checkMcpHookTargets(config, silent) {
+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()).mcpHookIssues;
+        found = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).mcpHookIssues;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -2272,13 +2313,17 @@ function checkMcpHookTargets(config, silent) {
  * existence-guarded one-liners, inline commands). Matches Anthropic's own
  * `claude plugin validate`. Warning by default; "error" gates CI.
  */
-function checkHookScriptExists(config, silent) {
+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()).hooks.filter((h) => h.status === "missing");
+        missing = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).hooks.filter((h) => h.status === "missing");
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -2303,13 +2348,17 @@ function checkHookScriptExists(config, silent) {
  * — 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) {
+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()).agents.flatMap((a) => a.mcpToolIssues.map((i) => ({ message: i.message, path: a.path })));
+        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 };
@@ -2583,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("");
@@ -2592,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");
@@ -2701,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
@@ -2716,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_2.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);
@@ -2760,7 +2975,7 @@ function agentStartCommand(target) {
         console.error("Usage: vigiles agent-start <agents/<name>.md>");
         process.exit(2);
     }
-    (0, agent_runtime_js_2.setActiveAgent)(process.cwd(), target);
+    (0, agent_runtime_js_1.setActiveAgent)(process.cwd(), target);
     console.log(`Active agent: ${target}`);
 }
 /** Dispatch the skill-runtime subcommands. Returns false if unrecognized. */
@@ -2778,11 +2993,14 @@ 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;
         case "agent-done":
-            (0, agent_runtime_js_2.clearActiveAgent)(process.cwd());
+            (0, agent_runtime_js_1.clearActiveAgent)(process.cwd());
             return true;
         case "agent-hook":
             agentHookCommand();
@@ -2799,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;
     }
@@ -2969,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) {
@@ -3033,9 +3256,7 @@ async function main() {
             }
             else {
                 const root = (0, node_path_1.resolve)(targets[0]);
-                const harnessFlag = args
-                    .find((a) => a.startsWith("--harness="))
-                    ?.slice("--harness=".length);
+                const harnessFlag = harnessFlagFrom(args);
                 const det = (0, adapter_registry_js_1.detectAdapterResult)(root);
                 const adapter = harnessFlag
                     ? (0, adapter_registry_js_1.resolveAdapter)(root, harnessFlag)
@@ -3048,7 +3269,15 @@ 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);
@@ -3056,6 +3285,12 @@ async function main() {
             }
             break;
         }
+        case "explain":
+            handleExplain(restArgs, args);
+            break;
+        case "scaffold-test":
+            handleScaffoldTest(restArgs, args);
+            break;
         // --- Plumbing ---
         case "generate-types":
             handleGenerateTypes(args, restArgs);