vigiles 5.1.0 → 5.2.0

package/dist/scan.js

@@ -34,6 +34,7 @@ const mcp_tool_js_1 = require("./core/mcp-tool.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");
+const effects_js_1 = require("./core/effects.js");
 // ---------------------------------------------------------------------------
 // Internals
 // ---------------------------------------------------------------------------
@@ -51,14 +52,24 @@ function frontmatter(md) {
         color: (0, frontmatter_read_js_1.frontmatterScalar)(fm, "color"),
     };
 }
-// Anchor each surface on a real path boundary (start-of-path or a `/`), so a
-// directory whose NAME merely ends in the keyword isn't misclassified — e.g.
-// the skill `skills/dispatching-parallel-agents/SKILL.md` must NOT register as
-// an agent named "SKILL" (the `-agents/` substring), which real plugins like
-// obra/superpowers ship. See scan.test.ts for the regression cases.
-const isSkill = (f) => /(?:^|\/)skills\/[^/]+\/SKILL\.md$/.test(f);
-const isAgent = (f) => /(?:^|\/)agents\/[^/]+\.md$/.test(f) && !f.endsWith(".spec.ts");
-const isCommand = (f) => /(?:^|\/)commands\/.+\.md$/.test(f);
+function escapeRe(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function makeClassifier(layout) {
+    // An empty dir means "this harness has no such surface" → never matches.
+    const at = (dir) => dir ? `(?:^|/)${escapeRe(dir)}/` : null;
+    const skill = at(layout.skillDir);
+    const agent = at(layout.agentDir);
+    const command = at(layout.commandDir);
+    const skillRe = skill ? new RegExp(`${skill}[^/]+/SKILL\\.md$`) : null;
+    const agentRe = agent ? new RegExp(`${agent}[^/]+\\.md$`) : null;
+    const commandRe = command ? new RegExp(`${command}.+\\.md$`) : null;
+    return {
+        isSkill: (f) => skillRe?.test(f) ?? false,
+        isAgent: (f) => (agentRe?.test(f) ?? false) && !f.endsWith(".spec.ts"),
+        isCommand: (f) => commandRe?.test(f) ?? false,
+    };
+}
 function skillName(path) {
     return (path
         .replace(/\/SKILL\.md$/, "")
@@ -137,10 +148,10 @@ function firstBodyParagraph(md) {
     }
     return para.join(" ").trim() || undefined;
 }
-function scanSkills(files) {
+function scanSkills(files, cls) {
     const out = [];
     for (const [path, md] of Object.entries(files)) {
-        if (!isSkill(path))
+        if (!cls.isSkill(path))
             continue;
         const fm = frontmatter(md);
         // A skill's trigger surface is its frontmatter `description` OR — when that's
@@ -165,10 +176,10 @@ function scanSkills(files) {
  * logic as `scanSkills` (frontmatter `description` ← first body paragraph), then
  * the NCD precision-proxy. See description-overlap.ts.
  */
-function descriptionOverlapsFor(files) {
+function descriptionOverlapsFor(files, cls) {
     const surfaces = [];
     for (const [path, md] of Object.entries(files)) {
-        if (!isSkill(path))
+        if (!cls.isSkill(path))
             continue;
         if (/^\s*disable-model-invocation:\s*true\s*$/m.test(md))
             continue;
@@ -180,12 +191,16 @@ function descriptionOverlapsFor(files) {
     }
     return (0, description_overlap_js_1.findDescriptionOverlaps)(surfaces);
 }
-function scanAgents(files, dialect, declaredServers) {
+function scanAgents(files, dialect, declaredServers, cls) {
     const out = [];
     for (const [path, md] of Object.entries(files)) {
-        if (!isAgent(path))
+        if (!cls.isAgent(path))
             continue;
         const tools = (0, agent_runtime_js_1.parseAgentTools)(md);
+        // An inherits-all agent (no `tools:` line) grants access to every tool
+        // including every side-effecting one — pass the wildcard sentinel so
+        // effectSurface correctly classifies it as `"unrestricted"`.
+        const surface = (0, effects_js_1.effectSurface)(tools ?? ["*"], dialect);
         out.push({
             name: (0, node_path_1.basename)(path, ".md"),
             path,
@@ -206,21 +221,31 @@ function scanAgents(files, dialect, declaredServers) {
             // The block-list mirror: a `disallowedTools:` entry that's a typo of a real
             // tool blocks nothing (close-typo only — high-precision). See tool-contract.ts.
             disallowedToolIssues: (0, tool_contract_js_1.disallowedToolIssues)((0, agent_runtime_js_1.parseAgentToolList)(md, "disallowedTools") ?? [], dialect),
+            purity: surface.purity,
+            effectBuckets: {
+                readOnly: surface.readOnly,
+                sideEffecting: surface.sideEffecting,
+                unknown: surface.unknown,
+            },
         });
     }
     return out.sort((a, b) => a.name.localeCompare(b.name));
 }
 /**
  * Resolve a hook script token to a checkable path. `loadPlugin` expands the
- * braced `${CLAUDE_PLUGIN_ROOT}`; the unbraced shell form `$CLAUDE_PLUGIN_ROOT`
- * survives, so resolve it against the plugin root here and strip shell quotes.
- * A token that still carries any `$VAR` after that is genuinely uncheckable.
+ * braced plugin-root token (`${CLAUDE_PLUGIN_ROOT}`, Codex `${PLUGIN_ROOT}`, …);
+ * the unbraced shell form survives, so resolve BOTH forms of the HARNESS's token
+ * (from the layout, not hard-coded) against the plugin root and strip shell
+ * quotes. A token that still carries any `$VAR` after that is genuinely
+ * uncheckable.
  */
-function resolveScript(token, root) {
+function resolveScript(token, root, pluginRootToken) {
+    // "${CLAUDE_PLUGIN_ROOT}" → unbraced "$CLAUDE_PLUGIN_ROOT".
+    const unbraced = pluginRootToken.replace(/^\$\{(.+)\}$/, "$$$1");
     const cleaned = token
         .replace(/["']/g, "")
-        .replaceAll("${CLAUDE_PLUGIN_ROOT}", root)
-        .replaceAll("$CLAUDE_PLUGIN_ROOT", root);
+        .replaceAll(pluginRootToken, root)
+        .replaceAll(unbraced, root);
     if (cleaned.includes("$"))
         return { script: token, status: "unresolved" };
     // A relative hook path (`./hooks/x.sh`, `scripts/x.py`) is the plugin's own —
@@ -238,7 +263,7 @@ function resolveScript(token, root) {
 // 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)/;
 /** Pull script-file hook commands out of the resolved settings; count inline ones. */
-function scanHooks(settings, root) {
+function scanHooks(settings, root, pluginRootToken) {
     const text = JSON.stringify(settings.hooks ?? {});
     const commands = [...text.matchAll(/"command":\s*"((?:[^"\\]|\\.)*)"/g)].map((m) => m[1]);
     const byScript = new Map();
@@ -257,7 +282,7 @@ function scanHooks(settings, root) {
             continue;
         }
         for (const tok of found) {
-            const hook = resolveScript(tok, root);
+            const hook = resolveScript(tok, root, pluginRootToken);
             byScript.set(hook.script, hook);
         }
     }
@@ -276,10 +301,10 @@ function scanHooks(settings, root) {
  * is a separate, behavioral concern). See https://code.claude.com/docs/en/skills
  * and …/sub-agents.
  */
-function frontmatterIssuesFor(files) {
+function frontmatterIssuesFor(files, cls) {
     const out = [];
     for (const [path, md] of Object.entries(files)) {
-        if (!isAgent(path))
+        if (!cls.isAgent(path))
             continue; // skills require no frontmatter (dir/body fallbacks)
         const fm = frontmatter(md);
         const missing = [];
@@ -337,12 +362,12 @@ function closeCandidate(value, candidates) {
  * Agent frontmatter VALUE validity — a `model:` or `color:` that's a close typo
  * of a real one. A bad `model:` silently falls back; a bad `color:` is ignored.
  * High-precision (close-typo only); a full/dated model id is left alone. Folded
- * into the `agent-frontmatter` rule. Agents only (skills have no model/color).
+ * into the `subagent-frontmatter` rule. Agents only (skills have no model/color).
  */
-function frontmatterValueIssuesFor(files) {
+function frontmatterValueIssuesFor(files, cls) {
     const out = [];
     for (const [path, md] of Object.entries(files)) {
-        if (!isAgent(path))
+        if (!cls.isAgent(path))
             continue;
         const fm = frontmatter(md);
         // A model id with a digit/hyphen is an explicit form, not an alias typo.
@@ -382,10 +407,10 @@ function frontmatterValueIssuesFor(files) {
  * as an informational note (NOT a structural defect) and the lint rule is a
  * warn, not an error. The file's other fields are still salvaged.
  */
-function malformedFrontmatterFor(files) {
+function malformedFrontmatterFor(files, cls) {
     const out = [];
     for (const [path, md] of Object.entries(files)) {
-        if (!isSkill(path) && !isAgent(path))
+        if (!cls.isSkill(path) && !cls.isAgent(path))
             continue;
         if (!(0, frontmatter_read_js_1.readFrontmatter)(md).malformed)
             continue;
@@ -405,10 +430,10 @@ function malformedFrontmatterFor(files) {
  * missing either; surfaced as a soft note in scan (NOT a structural defect, NOT
  * scored) and gated by the `skill-frontmatter` lint rule (warn by default).
  */
-function skillMetaIssuesFor(files) {
+function skillMetaIssuesFor(files, cls) {
     const out = [];
     for (const [path, md] of Object.entries(files)) {
-        if (!isSkill(path))
+        if (!cls.isSkill(path))
             continue;
         const fm = frontmatter(md);
         const missing = [];
@@ -457,8 +482,9 @@ function collectMcpServers(root, layout) {
 /** Scan a plugin/repo directory and report its surfaces + structural issues. */
 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));
+    const { hooks, inline } = 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
@@ -480,26 +506,33 @@ function scanPlugin(dir, layout, dialect = dialect_js_1.claudeCodeDialect) {
         : null;
     const mcpServers = collectMcpServers((0, node_path_1.resolve)(dir), lay);
     const declaredServers = Object.keys(mcpServers);
+    const agents = scanAgents(loaded.files, dialect, declaredServers, cls);
+    const puritySummary = agents.reduce((acc, a) => {
+        acc[a.purity]++;
+        return acc;
+    }, { pure: 0, bounded: 0, unrestricted: 0 });
     return {
         dir,
         instructions,
-        skills: scanSkills(loaded.files),
-        agents: scanAgents(loaded.files, dialect, declaredServers),
+        skills: scanSkills(loaded.files, cls),
+        agents,
         hooks,
         inlineHooks: inline,
-        commands: Object.keys(loaded.files).filter(isCommand).length,
+        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),
         hookEventIssues,
-        frontmatterIssues: frontmatterIssuesFor(loaded.files),
-        frontmatterValueIssues: frontmatterValueIssuesFor(loaded.files),
-        skillMetaIssues: skillMetaIssuesFor(loaded.files),
+        frontmatterIssues: frontmatterIssuesFor(loaded.files, cls),
+        frontmatterValueIssues: frontmatterValueIssuesFor(loaded.files, cls),
+        skillMetaIssues: skillMetaIssuesFor(loaded.files, cls),
         mcpIssues: (0, mcp_config_js_1.verifyMcpServers)(mcpServers),
         mcpHookIssues: (0, mcp_hook_js_1.verifyMcpHookTargets)(loaded.settings.hooks, declaredServers, dialect),
-        descriptionOverlaps: descriptionOverlapsFor(loaded.files),
-        malformedFrontmatter: malformedFrontmatterFor(loaded.files),
+        descriptionOverlaps: descriptionOverlapsFor(loaded.files, cls),
+        malformedFrontmatter: malformedFrontmatterFor(loaded.files, cls),
         warnings: loaded.warnings,
-        untested: (0, test_coverage_js_1.findUntestedSurfaces)({ basePath: dir }).untested.length,
+        untested: (0, test_coverage_js_1.findUntestedSurfaces)({ basePath: dir, layout: lay }).untested
+            .length,
+        puritySummary,
     };
 }
 /**
@@ -588,7 +621,7 @@ function skillLine(s) {
     const mark = s.descriptionScript ? "⚠" : "✓";
     return `  ${mark} ${s.name}${notes.length ? ` (${notes.join("; ")})` : ""}`;
 }
-/** One agent's report block: ✗ (broken contract) / ⚠ (inherits all) / ✓ + issues. */
+/** One agent's report block: ✗ (broken contract) / ⚠ (inherits all) / ✓ + issues + purity. */
 function agentLines(a) {
     const tools = a.tools === null
         ? "tools: (inherits all — no contract)"
@@ -601,7 +634,15 @@ function agentLines(a) {
         mark = "✗";
     else if (a.tools === null)
         mark = "⚠";
-    const lines = [`  ${mark} ${a.name} — ${tools}`];
+    // Purity is an informational health signal (not a structural defect); mark it
+    // clearly so a reader knows which rung this agent is on.
+    const PURITY_TAGS = {
+        pure: "pure",
+        bounded: "bounded",
+        unrestricted: "unrestricted",
+    };
+    const purityTag = PURITY_TAGS[a.purity] ?? "unrestricted";
+    const lines = [`  ${mark} ${a.name} — ${tools} [${purityTag}]`];
     for (const issue of a.toolIssues)
         lines.push(`      ✗ ${issue.message}`);
     for (const issue of a.mcpToolIssues)
@@ -650,6 +691,13 @@ function formatScanReport(r) {
         facts.push(`Commands: ${String(r.commands)}`);
     facts.push(`MCP servers: ${r.mcp ? "yes" : "no"}`);
     facts.push(`Untested surfaces: ${String(r.untested)}`);
+    // Effect surface: harness-level purity summary across all scanned agents.
+    // Informational (higher pure% = more constrained, cheaper to test); shown
+    // only when there are agents to summarize (no agents → no summary line).
+    if (r.agents.length > 0) {
+        const { pure, bounded, unrestricted } = r.puritySummary;
+        facts.push(`Effect surface: ${String(pure)} pure · ${String(bounded)} bounded · ${String(unrestricted)} unrestricted`);
+    }
     out.push(...facts, "");
     // The dangling-ref warning is now shown as a first-class ✗ section above, so
     // drop it from the free-text list to avoid saying the same thing twice.

package/dist/score-explainer.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Score-explainer — the deterministic WHY behind a low measured score (C4 of the
+ * measurement-authority pivot; the strongest pairing in it).
+ *
+ * The MEASUREMENT layer finds a behavioral SYMPTOM: "this skill underperforms",
+ * "the wrong skill fires", "this agent fails its task". A behavioral symptom alone
+ * is not actionable — you can drop the skill, but you don't know WHY it lost. The
+ * cross-reference engine (the linting layer) already detects the deterministic
+ * CAUSES: two skills with near-identical descriptions can't be told apart by the
+ * selector; a never-available / typo'd tool is silently dropped from a subagent; a
+ * hook on a misspelled event never fires. This module BRIDGES the two: given the
+ * `ScanReport` the linter already computes, it surfaces — per affected surface —
+ * the deterministic cause of a behavioral symptom and the one-line fix.
+ *
+ *   Measurement says   "caveman underperforms"
+ *   the explainer says "...BECAUSE its description overlaps `compress` (0.86) —
+ *                       differentiate them so the selector can disambiguate."
+ *
+ * It REUSES the scan findings (one-detector-no-drift) — it never re-detects. So
+ * it's pure over a `ScanReport`, free, model-less, and consistent with `vigiles
+ * lint`/`scan`. It's the diagnostic the per-repo optimizer (`vigiles optimize`,
+ * A2) prints next to each "drop / swap" recommendation. See
+ * `research/measurement-authority.md` ("what becomes of the linting", role 2).
+ */
+import type { ScanReport } from "./scan.js";
+/**
+ * The behavioral failure a MEASUREMENT would observe — the symptom an explanation
+ * accounts for. Discriminated so a consumer can group/filter by symptom and so an
+ * explanation can never carry a symptom it has no cause for.
+ */
+export type BehavioralSymptom = "wrong-skill-fires" | "skill-never-fires" | "agent-underperforms" | "hook-never-runs" | "subagent-never-dispatches";
+/**
+ * How firmly the deterministic finding EXPLAINS the symptom:
+ * - `"likely"` — a hard structural dead-end (a missing script can't run, a
+ *   never-available tool can't be called); the cause is near-certain.
+ * - `"possible"` — a high-precision PROXY for a behavioral risk (a description
+ *   overlap / a foreign-script description); deterministic to detect, but whether
+ *   it actually moved behaviour is confirmed by `scan --trigger`.
+ */
+export type ExplanationConfidence = "likely" | "possible";
+export interface ScoreExplanation {
+    /** The affected surface (a skill/agent/hook name or path) the symptom attaches to. */
+    readonly surface: string;
+    /** What a measurement would SEE. */
+    readonly symptom: BehavioralSymptom;
+    /** The deterministic finding (the scan/lint detector's own message — no drift). */
+    readonly cause: string;
+    /** The lint rule that found it, so a reader can open `docs/rules/<detector>.md`. */
+    readonly detector: string;
+    /** A single, actionable fix. */
+    readonly fix: string;
+    readonly confidence: ExplanationConfidence;
+}
+/**
+ * Explain every behavioral symptom the report's deterministic findings account
+ * for. Returns one `ScoreExplanation` per finding, `"likely"` causes first (a hard
+ * dead-end is more certain than a proxy). Pure over the report.
+ */
+export declare function explainScore(report: ScanReport): ScoreExplanation[];
+/**
+ * The explanations that attach to ONE underperforming surface — the call the
+ * benchmark/optimizer makes when a measurement flags a single skill/agent. Matches
+ * a surface name case-insensitively, including the `"a ↔ b"` overlap pairs (so
+ * explaining "caveman" surfaces an overlap with another skill).
+ */
+export declare function explainSurface(report: ScanReport, surface: string): ScoreExplanation[];
+/** Render explanations for a CLI/report — grouped under the symptom, fix called out. */
+export declare function formatExplanations(exps: readonly ScoreExplanation[]): string;
+//# sourceMappingURL=score-explainer.d.ts.map

package/dist/score-explainer.js

@@ -0,0 +1,169 @@
+"use strict";
+/**
+ * Score-explainer — the deterministic WHY behind a low measured score (C4 of the
+ * measurement-authority pivot; the strongest pairing in it).
+ *
+ * The MEASUREMENT layer finds a behavioral SYMPTOM: "this skill underperforms",
+ * "the wrong skill fires", "this agent fails its task". A behavioral symptom alone
+ * is not actionable — you can drop the skill, but you don't know WHY it lost. The
+ * cross-reference engine (the linting layer) already detects the deterministic
+ * CAUSES: two skills with near-identical descriptions can't be told apart by the
+ * selector; a never-available / typo'd tool is silently dropped from a subagent; a
+ * hook on a misspelled event never fires. This module BRIDGES the two: given the
+ * `ScanReport` the linter already computes, it surfaces — per affected surface —
+ * the deterministic cause of a behavioral symptom and the one-line fix.
+ *
+ *   Measurement says   "caveman underperforms"
+ *   the explainer says "...BECAUSE its description overlaps `compress` (0.86) —
+ *                       differentiate them so the selector can disambiguate."
+ *
+ * It REUSES the scan findings (one-detector-no-drift) — it never re-detects. So
+ * it's pure over a `ScanReport`, free, model-less, and consistent with `vigiles
+ * lint`/`scan`. It's the diagnostic the per-repo optimizer (`vigiles optimize`,
+ * A2) prints next to each "drop / swap" recommendation. See
+ * `research/measurement-authority.md` ("what becomes of the linting", role 2).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.explainScore = explainScore;
+exports.explainSurface = explainSurface;
+exports.formatExplanations = formatExplanations;
+const SYMPTOM_LABEL = {
+    "wrong-skill-fires": "the selector fires the wrong skill",
+    "skill-never-fires": "the skill never fires",
+    "agent-underperforms": "the subagent loses a declared tool",
+    "hook-never-runs": "the hook never runs",
+    "subagent-never-dispatches": "the subagent won't register",
+};
+// 1. Description overlap → the selector can't disambiguate (precision collision).
+function overlapExplanations(report) {
+    return report.descriptionOverlaps.map((o) => ({
+        surface: `${o.a} ↔ ${o.b}`,
+        symptom: "wrong-skill-fires",
+        cause: o.message,
+        detector: "description-overlap",
+        fix: `Differentiate the descriptions of "${o.a}" and "${o.b}" (${o.similarity} similar) — the selector picks by description, so near-identical text makes it fire the wrong one.`,
+        confidence: "possible",
+    }));
+}
+// 2. Skill with no usable description → nothing for the selector to match on.
+function skillExplanations(report) {
+    return report.skills
+        .filter((s) => !s.hasDescription)
+        .map((s) => ({
+        surface: s.name,
+        symptom: "skill-never-fires",
+        cause: `"${s.name}" has no usable description`,
+        detector: "skill-frontmatter",
+        fix: `Add a "description:" to "${s.name}" — the selector matches on it; without one the skill has no trigger surface.`,
+        confidence: "likely",
+    }));
+}
+// 3. Subagent tool-contract dead entries → the tool is silently dropped.
+function agentExplanations(report) {
+    const out = [];
+    for (const a of report.agents) {
+        for (const t of a.toolIssues) {
+            out.push({
+                surface: a.name,
+                symptom: "agent-underperforms",
+                cause: t.message,
+                detector: "subagent-tool-contract",
+                fix: t.suggestion
+                    ? `In "${a.name}", change the tool "${t.tool}" to "${t.suggestion}" — as written it isn't a real tool, so it's dropped and the agent can't use it.`
+                    : `In "${a.name}", remove or correct the tool "${t.tool}" — it isn't an available tool, so it's silently dropped from the contract.`,
+                confidence: "likely",
+            });
+        }
+        for (const m of a.mcpToolIssues) {
+            out.push({
+                surface: a.name,
+                symptom: "agent-underperforms",
+                cause: m.message,
+                detector: "mcp-tool-resolves",
+                fix: `"${a.name}" lists the MCP tool "${m.tool}" but its server "${m.server}" isn't declared in the plugin's mcpServers — declare the server or drop the tool, else the call can't resolve.`,
+                confidence: "likely",
+            });
+        }
+    }
+    return out;
+}
+// 4. Hook on an unknown event, or 5. a missing hook script → the hook never runs.
+function hookExplanations(report) {
+    const out = report.hookEventIssues.map((h) => ({
+        surface: h.event,
+        symptom: "hook-never-runs",
+        cause: h.message,
+        detector: "hook-events",
+        fix: h.suggestion
+            ? `Change the hook event "${h.event}" to "${h.suggestion}" — the harness doesn't define "${h.event}", so the hook never fires.`
+            : `Fix the hook event "${h.event}" — the harness doesn't define it, so the hook never fires.`,
+        confidence: "likely",
+    }));
+    for (const h of report.hooks) {
+        if (h.status === "missing") {
+            out.push({
+                surface: h.script,
+                symptom: "hook-never-runs",
+                cause: `hook script "${h.script}" does not exist on disk`,
+                detector: "hook-script-exists",
+                fix: `Create "${h.script}" or fix its path — the hook references a script that isn't on disk, so it silently never runs.`,
+                confidence: "likely",
+            });
+        }
+    }
+    return out;
+}
+// 6. Subagent frontmatter missing a required field → it won't register at all.
+function frontmatterExplanations(report) {
+    return report.frontmatterIssues
+        .filter((f) => f.kind === "agent")
+        .map((f) => ({
+        surface: f.path,
+        symptom: "subagent-never-dispatches",
+        cause: f.message,
+        detector: "subagent-frontmatter",
+        fix: `Add the missing ${f.missing.join(" + ")} to "${f.path}" — a subagent without it won't register, so it can never be dispatched.`,
+        confidence: "likely",
+    }));
+}
+const confidenceRank = (c) => c === "likely" ? 0 : 1;
+/**
+ * Explain every behavioral symptom the report's deterministic findings account
+ * for. Returns one `ScoreExplanation` per finding, `"likely"` causes first (a hard
+ * dead-end is more certain than a proxy). Pure over the report.
+ */
+function explainScore(report) {
+    return [
+        ...overlapExplanations(report),
+        ...skillExplanations(report),
+        ...agentExplanations(report),
+        ...hookExplanations(report),
+        ...frontmatterExplanations(report),
+        // `likely` before `possible` — surface the certain dead-ends first.
+    ].sort((x, y) => confidenceRank(x.confidence) - confidenceRank(y.confidence));
+}
+/**
+ * The explanations that attach to ONE underperforming surface — the call the
+ * benchmark/optimizer makes when a measurement flags a single skill/agent. Matches
+ * a surface name case-insensitively, including the `"a ↔ b"` overlap pairs (so
+ * explaining "caveman" surfaces an overlap with another skill).
+ */
+function explainSurface(report, surface) {
+    const needle = surface.toLowerCase();
+    return explainScore(report).filter((e) => e.surface.toLowerCase().includes(needle));
+}
+/** 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).";
+    }
+    const lines = [];
+    for (const e of exps) {
+        const mark = e.confidence === "likely" ? "✗" : "⚠";
+        lines.push(`${mark} ${e.surface} — ${SYMPTOM_LABEL[e.symptom]}`);
+        lines.push(`    cause: ${e.cause}  [${e.detector}]`);
+        lines.push(`    fix:   ${e.fix}`);
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=score-explainer.js.map

package/dist/test-coverage.d.ts

@@ -21,6 +21,7 @@
  * The only opt-out is explicit: a `vigiles:ignore-test` marker in the surface
  * file, which is reported as `exempt` so the skip is visible, never silent.
  */
+import type { PluginLayout } from "./core/layout.js";
 export type SurfaceKind = "skill" | "agent" | "hook";
 export interface Surface {
     readonly kind: SurfaceKind;
@@ -54,6 +55,12 @@ export interface TestCoverageOptions {
     readonly testGlobs?: readonly string[];
     /** Extra ignore globs (added to node_modules/dist/.git/.vigiles). */
     readonly exclude?: readonly string[];
+    /**
+     * Harness layout — where skills/agents live, the plugin-root token, the
+     * manifest/settings paths. Defaults to Claude Code; a non-CC adapter passes its
+     * own so the surface globs and hook-token expansion aren't hard-coded.
+     */
+    readonly layout?: PluginLayout;
 }
 /**
  * Find harness surfaces (skills / agents / hooks) that no test or eval covers.