vigiles 5.0.1 → 5.2.0

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.

package/dist/test-coverage.js

@@ -29,6 +29,20 @@ exports.formatUntestedReport = formatUntestedReport;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const glob_1 = require("glob");
+const layout_js_1 = require("./adapters/claude-code/layout.js");
+/**
+ * The two on-disk locations a surface dir can occupy: the plugin-root form
+ * (`skills/…`) and the materialized form (`.claude/skills/…`) — derived from the
+ * layout so a non-Claude-Code harness (its own `materializeRoot` / surface dir)
+ * is discovered without hard-coding `.claude`. An empty `dir` (a harness lacking
+ * the surface, e.g. Codex subagents) yields no globs.
+ */
+function surfaceGlobs(dir, leaf, materializeRoot) {
+    if (!dir)
+        return [];
+    const matForm = materializeRoot ? `${materializeRoot}/${dir}` : dir;
+    return [...new Set([`${dir}/${leaf}`, `${matForm}/${leaf}`])];
+}
 // ---------------------------------------------------------------------------
 // Internals
 // ---------------------------------------------------------------------------
@@ -58,12 +72,9 @@ function read(path) {
         return "";
     }
 }
-function discoverSkills(basePath, ignore) {
+function discoverSkills(basePath, ignore, layout) {
     const out = [];
-    const found = (0, glob_1.globSync)(["skills/*/SKILL.md", ".claude/skills/*/SKILL.md"], {
-        cwd: basePath,
-        ignore,
-    });
+    const found = (0, glob_1.globSync)(surfaceGlobs(layout.skillDir, "*/SKILL.md", layout.materializeRoot), { cwd: basePath, ignore });
     for (const path of found.sort()) {
         const name = (0, node_path_1.basename)((0, node_path_1.dirname)(path));
         const content = read((0, node_path_1.join)(basePath, path));
@@ -71,18 +82,15 @@ function discoverSkills(basePath, ignore) {
             kind: "skill",
             path,
             name,
-            tokens: [`skills/${name}`, `:${name}`],
+            tokens: [`${layout.skillDir}/${name}`, `:${name}`],
             ignored: content.includes(IGNORE_MARKER),
         });
     }
     return out;
 }
-function discoverAgents(basePath, ignore) {
+function discoverAgents(basePath, ignore, layout) {
     const out = [];
-    const found = (0, glob_1.globSync)(["agents/*.md", ".claude/agents/*.md"], {
-        cwd: basePath,
-        ignore,
-    });
+    const found = (0, glob_1.globSync)(surfaceGlobs(layout.agentDir, "*.md", layout.materializeRoot), { cwd: basePath, ignore });
     for (const path of found.sort()) {
         if (path.endsWith(".spec.ts"))
             continue;
@@ -100,7 +108,7 @@ function discoverAgents(basePath, ignore) {
     return out;
 }
 /** Hook-script paths referenced from a manifest's `hooks` block (file hooks only). */
-function hookScripts(basePath, manifest) {
+function hookScripts(basePath, manifest, pluginRootToken) {
     if (!(0, node_fs_1.existsSync)((0, node_path_1.join)(basePath, manifest)))
         return [];
     let hooks;
@@ -114,25 +122,31 @@ function hookScripts(basePath, manifest) {
     if (hooks === undefined)
         return [];
     const text = JSON.stringify(hooks);
+    // "${CLAUDE_PLUGIN_ROOT}" → unbraced "$CLAUDE_PLUGIN_ROOT" — strip the harness's
+    // own token (both forms) so the path is checkable relative to the plugin root.
+    const unbraced = pluginRootToken.replace(/^\$\{(.+)\}$/, "$$$1");
     const scripts = new Set();
     for (const m of text.matchAll(SCRIPT_RE)) {
         const rel = m[0]
-            .replace("${CLAUDE_PLUGIN_ROOT}/", "")
-            .replace(/^\$\{CLAUDE_PLUGIN_ROOT\}/, "")
+            .replaceAll(pluginRootToken, "")
+            .replaceAll(unbraced, "")
+            .replace(/^\/+/, "")
             .replace(/^\.\//, "");
         if ((0, node_fs_1.existsSync)((0, node_path_1.join)(basePath, rel)))
             scripts.add(rel);
     }
     return [...scripts];
 }
-function discoverHooks(basePath) {
+function discoverHooks(basePath, layout) {
     const scripts = new Set();
-    for (const m of [
-        ".claude-plugin/plugin.json",
-        ".claude/settings.json",
-        ".claude/settings.local.json",
-    ]) {
-        for (const s of hookScripts(basePath, m))
+    // The harness's manifest + settings (and a `.local` settings sibling, a CC
+    // convention that's harmless to probe elsewhere).
+    const localSettings = layout.settingsPath.replace(/(\.[^./]+)$/, ".local$1");
+    const manifests = [
+        ...new Set([layout.manifestPath, layout.settingsPath, localSettings]),
+    ];
+    for (const m of manifests) {
+        for (const s of hookScripts(basePath, m, layout.pluginRootToken))
             scripts.add(s);
     }
     return [...scripts].sort().map((path) => ({
@@ -185,15 +199,16 @@ function isCovered(surface, tests) {
  */
 function findUntestedSurfaces(options = {}) {
     const basePath = options.basePath ?? process.cwd();
+    const layout = options.layout ?? layout_js_1.claudeCodeLayout;
     const ignore = [...DEFAULT_IGNORE, ...(options.exclude ?? [])];
     const globs = options.testGlobs ?? DEFAULT_TEST_GLOBS;
     const surfaces = [];
     if (options.skills !== false)
-        surfaces.push(...discoverSkills(basePath, ignore));
+        surfaces.push(...discoverSkills(basePath, ignore, layout));
     if (options.agents !== false)
-        surfaces.push(...discoverAgents(basePath, ignore));
+        surfaces.push(...discoverAgents(basePath, ignore, layout));
     if (options.hooks !== false)
-        surfaces.push(...discoverHooks(basePath));
+        surfaces.push(...discoverHooks(basePath, layout));
     // Every skill/agent/hook is held to the requirement — only an explicit
     // `vigiles:ignore-test` marker exempts a surface (a visible, deliberate skip).
     const considered = surfaces.filter((s) => !s.ignored);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigiles",
-  "version": "5.0.1",
+  "version": "5.2.0",
   "description": "Lint & test the harness your AI agent runs on — verify the references in your CLAUDE.md / AGENTS.md and test that your hooks and skills actually work.",
   "keywords": [
     "claude-code",
@@ -128,6 +128,7 @@
     "glob": "^13.0.6",
     "js-yaml": "^4.1.0",
     "minimatch": "^10.0.1",
+    "mvdan-sh": "^0.10.1",
     "ts-essentials": "^10.2.1",
     "typescript": "^5.9.3"
   }

package/skills/{migrate-to-spec → adopt-spec}/SKILL.md

@@ -1,13 +1,13 @@
 ---
-name: migrate-to-spec
-description: Convert an existing hand-written CLAUDE.md into a typed .spec.ts file for incremental adoption
+name: adopt-spec
+description: Adopt a typed .spec.ts for an existing hand-written CLAUDE.md — start from the file you already have, non-destructively
 disable-model-invocation: true
 argument-hint: <path to CLAUDE.md, defaults to CLAUDE.md>
 ---
 
-Convert an existing hand-written CLAUDE.md (or AGENTS.md) into a typed `CLAUDE.md.spec.ts` file. This is the incremental adoption path — you keep your existing instruction file as the starting point and get type safety going forward.
+Start a typed `CLAUDE.md.spec.ts` from an existing hand-written CLAUDE.md (or AGENTS.md). This is the non-destructive adoption path — you keep your existing instruction file as the starting point and get type safety going forward.
 
-> **Don't need full TypeScript?** A typed spec is the deepest commitment level. If the user only wants verified rules without a build step, point them at markdown mode first: inline `<!-- vigiles:enforce ... -->` comments (Level 0) or a `vigiles:` YAML frontmatter block with `vigiles generate-schema` for editor autocomplete (Level 1). Both are verified by `vigiles lint` with the same engine as a spec. See `docs/markdown-mode.md`. Migrate to a spec only when they want compiler-grade guarantees.
+> **Don't need full TypeScript?** A typed spec is the deepest commitment level. If the user only wants verified rules without a build step, point them at markdown mode first: inline `<!-- vigiles:enforce ... -->` comments (Level 0) or a `vigiles:` YAML frontmatter block with `vigiles generate-schema` for editor autocomplete (Level 1). Both are verified by `vigiles lint` with the same engine as a spec. See `docs/markdown-mode.md`. Adopt a spec only when they want compiler-grade guarantees.
 
 ## Instructions
 
@@ -46,8 +46,6 @@ import {
   claude,
   enforce,
   guidance,
-  check,
-  every,
   file,
   cmd,
   ref,

package/skills/edit-spec/SKILL.md

@@ -27,7 +27,7 @@ Look for spec files in the repo root:
 - Any `*.spec.ts` matching instruction files
 
 If no spec exists: if there's a hand-written `CLAUDE.md`, suggest the
-`migrate-to-spec` skill; otherwise suggest `npx vigiles init` to scaffold one.
+`adopt-spec` skill; otherwise suggest `npx vigiles init` to scaffold one.
 
 ### Step 2: Read and Understand the Spec