vigiles 5.0.1 → 5.2.0

package/dist/leaderboard.js

@@ -12,6 +12,7 @@
  * model and stack on top later; this part runs anywhere in CI for free.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.gradeFor = gradeFor;
 exports.scoreReport = scoreReport;
 exports.rankPlugins = rankPlugins;
 exports.formatLeaderboard = formatLeaderboard;
@@ -20,8 +21,10 @@ const scan_js_1 = require("./scan.js");
 // Penalty weights — broken-at-runtime costs most, footguns less, nudges least.
 const W_MISSING_HOOK = 15; // a hook script that doesn't exist → never runs
 const W_NO_DESCRIPTION = 10; // a skill with no usable description → can't trigger
+const W_DANGLING_REF = 8; // a referenced intra-plugin file that's missing → broken path
 const W_NO_CONTRACT = 5; // an agent with no `tools:` line → inherits everything
 const W_UNTESTED = 3; // a surface with no test/eval → warning-tier
+/** Map a 0–100 structural-health score to its letter grade (A ≥90 … F <60). */
 function gradeFor(score) {
     if (score >= 90)
         return "A";
@@ -35,29 +38,86 @@ function gradeFor(score) {
 }
 /** Deterministic structural-health score for one scanned plugin. */
 function scoreReport(r) {
-    // An empty/unloadable machine isn't healthy — it's a non-plugin or a broken load.
-    if (r.skills.length + r.agents.length + r.hooks.length === 0) {
+    // An empty/unloadable machine isn't healthy — it's a non-plugin or a broken
+    // load. A command-only or MCP-only plugin (commands/*.md or .mcp.json with no
+    // skills/agents/hooks) IS a legitimate plugin, though — Anthropic ships
+    // command-only plugins in its own marketplace — so it must NOT score 0.
+    const surfaces = r.skills.length + r.agents.length + r.hooks.length + r.commands;
+    if (surfaces === 0 && !r.mcp) {
         return { score: 0, issues: ["no loadable plugin surface"] };
     }
     const missingHooks = r.hooks.filter((h) => h.status === "missing").length;
     const noDesc = r.skills.filter((s) => !s.hasDescription).length;
     const noContract = r.agents.filter((a) => a.tools === null).length;
+    const deadTools = r.agents.reduce((n, a) => n + a.toolIssues.length, 0);
+    const deadMcpTools = r.agents.reduce((n, a) => n + a.mcpToolIssues.length, 0);
+    const deadDisallowed = r.agents.reduce((n, a) => n + a.disallowedToolIssues.length, 0);
+    const deadHookEvents = r.hookEventIssues.length;
+    const badFrontmatter = r.frontmatterIssues.length;
+    const badFrontmatterValues = r.frontmatterValueIssues.length;
+    const badMcp = r.mcpIssues.length;
+    const badMcpHooks = r.mcpHookIssues.length;
     const deductions = [
         {
             n: missingHooks,
             weight: W_MISSING_HOOK,
             label: "hook script(s) MISSING",
         },
+        {
+            n: deadHookEvents,
+            weight: W_MISSING_HOOK,
+            label: "hook(s) on an unknown event (never fire)",
+        },
         {
             n: noDesc,
             weight: W_NO_DESCRIPTION,
             label: "skill(s) with no usable description",
         },
+        {
+            n: r.danglingRefs.length,
+            weight: W_DANGLING_REF,
+            label: "broken intra-plugin reference(s)",
+        },
+        {
+            n: deadTools,
+            weight: W_DANGLING_REF,
+            label: "agent tool(s) that don't exist (typo / never-available)",
+        },
+        {
+            n: deadMcpTools,
+            weight: W_DANGLING_REF,
+            label: "agent MCP tool(s) whose server isn't declared (can't resolve)",
+        },
+        {
+            n: deadDisallowed,
+            weight: W_NO_CONTRACT,
+            label: "agent disallowedTools typo(s) that block nothing",
+        },
         {
             n: noContract,
             weight: W_NO_CONTRACT,
             label: "agent(s) inherit all tools (no contract)",
         },
+        {
+            n: badFrontmatter,
+            weight: W_NO_DESCRIPTION,
+            label: "surface(s) missing required frontmatter (name/description)",
+        },
+        {
+            n: badFrontmatterValues,
+            weight: W_NO_CONTRACT,
+            label: "agent(s) with an invalid model/color (typo → silent fallback)",
+        },
+        {
+            n: badMcp,
+            weight: W_DANGLING_REF,
+            label: "MCP server(s) that can't start (no command/url)",
+        },
+        {
+            n: badMcpHooks,
+            weight: W_DANGLING_REF,
+            label: "mcp_tool hook(s) incomplete / targeting an undeclared server",
+        },
         { n: r.untested, weight: W_UNTESTED, label: "untested surface(s)" },
     ];
     let penalty = 0;
@@ -101,7 +161,7 @@ function formatLeaderboard(scores) {
         const issue = s.issues.length > 0 ? ` — ${s.issues.join("; ")}` : "";
         out.push(`  ${rank}  ${score}    ${s.grade}      ${s.name}${issue}`);
     });
-    out.push("", "Structural health only (no model). Weights: missing hook -15, no-description", "skill -10, agent-without-tool-contract -5, untested surface -3.");
+    out.push("", "Structural health only (no model). Weights: missing hook -15, no-description", "skill -10, broken intra-plugin ref -8, agent-without-tool-contract -5,", "untested surface -3.");
     return out.join("\n");
 }
 //# sourceMappingURL=leaderboard.js.map

package/dist/optimize.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The per-repo harness optimizer's DETERMINISTIC spine — shipped as the
+ * `vigiles scan --fix-plan` lens (NOT its own `optimize` verb: until the measured
+ * A/B half lands, an "optimizer" that only re-prints scan's findings doesn't earn
+ * a separate command, so it's folded into scan as one more view on the same
+ * report; see research/roadmap.md §P2 "reconsider an `optimize` verb").
+ *
+ * A2 in the measurement-authority pivot is the ADOPTION product: measure a user's
+ * own skills/model/rules on their tasks and recommend add/drop/swap with a MEASURED
+ * delta. The measured delta is the real-model layer (gated on the Pro/Max
+ * subscription, costs tokens); this v0 ships the deterministic HALF — the free
+ * pre-filter that runs on every commit with no model.
+ *
+ * It answers "what should I fix in my harness, and why" using only the cross-ref
+ * findings the linter already computes: it reuses `scoreReport` for the headline
+ * structural-health score and `explainScore` for the per-surface cause + one-line
+ * fix (one-detector-no-drift — it never re-detects). The result is a prioritized,
+ * typed action list — the spine the measured A/B (the behavioral delta) stacks on.
+ *
+ * This is the "linting as a free pre-filter to measurement" thesis made a command:
+ * clear the structural dead-ends a model can't help with FIRST (free, certain),
+ * THEN spend tokens measuring whether the structurally-clean skills earn their keep.
+ *
+ * Distinct from `vigiles explain` (which diagnoses ONE underperforming surface a
+ * measurement flagged): `optimize` is the whole-repo adoption view — health score +
+ * the ranked fix list + the hand-off to the measured layer. Same findings, the
+ * optimization framing. See research/measurement-authority.md (A2) + roadmap §P1.
+ */
+import { type PluginScore } from "./leaderboard.js";
+import { type ExplanationConfidence } from "./score-explainer.js";
+import type { ScanReport } from "./scan.js";
+/**
+ * The action a recommendation asks for. The deterministic detectors yield two:
+ * `"differentiate"` (a description-overlap PAIR — make the two distinct so the
+ * selector can disambiguate) and `"fix"` (every other structural dead-end —
+ * correct/add/remove the offending bit). The richer add/drop/swap vocabulary
+ * belongs to the MEASURED layer, once a behavioral delta ranks the alternatives.
+ */
+export type OptimizeAction = "fix" | "differentiate";
+export interface Recommendation {
+    /** The affected surface (a skill/agent/hook name or path, or an `a ↔ b` pair). */
+    readonly surface: string;
+    readonly action: OptimizeAction;
+    /** The deterministic cause (the detector's own message — no drift). */
+    readonly rationale: string;
+    /** A single, actionable fix. */
+    readonly fix: string;
+    /** The lint rule that found it (open `docs/rules/<detector>.md`). */
+    readonly detector: string;
+    readonly confidence: ExplanationConfidence;
+}
+export interface OptimizeReport {
+    readonly dir: string;
+    /** Structural-health score 0–100 (the same `scoreReport` the leaderboard uses). */
+    readonly score: number;
+    readonly grade: PluginScore["grade"];
+    /** The free deterministic fixes, `likely` dead-ends first (explainScore's order). */
+    readonly recommendations: readonly Recommendation[];
+    /**
+     * No loadable surface at all (not a plugin, or a broken load) — distinct from a
+     * clean-and-loaded harness with zero findings, so the formatter doesn't call an
+     * EMPTY machine "clean". Mirrors `scoreReport`'s empty-machine case.
+     */
+    readonly empty: boolean;
+}
+/**
+ * Turn a scan report into a prioritized optimization plan: the structural-health
+ * score + a typed recommendation per deterministic finding (`likely` dead-ends
+ * before `possible` proxies, via explainScore's own ordering). Pure over the report.
+ */
+export declare function optimize(report: ScanReport): OptimizeReport;
+/** Render an optimization plan for the CLI. */
+export declare function formatOptimize(rep: OptimizeReport): string;
+//# sourceMappingURL=optimize.d.ts.map

package/dist/optimize.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.optimize = optimize;
+exports.formatOptimize = formatOptimize;
+/**
+ * The per-repo harness optimizer's DETERMINISTIC spine — shipped as the
+ * `vigiles scan --fix-plan` lens (NOT its own `optimize` verb: until the measured
+ * A/B half lands, an "optimizer" that only re-prints scan's findings doesn't earn
+ * a separate command, so it's folded into scan as one more view on the same
+ * report; see research/roadmap.md §P2 "reconsider an `optimize` verb").
+ *
+ * A2 in the measurement-authority pivot is the ADOPTION product: measure a user's
+ * own skills/model/rules on their tasks and recommend add/drop/swap with a MEASURED
+ * delta. The measured delta is the real-model layer (gated on the Pro/Max
+ * subscription, costs tokens); this v0 ships the deterministic HALF — the free
+ * pre-filter that runs on every commit with no model.
+ *
+ * It answers "what should I fix in my harness, and why" using only the cross-ref
+ * findings the linter already computes: it reuses `scoreReport` for the headline
+ * structural-health score and `explainScore` for the per-surface cause + one-line
+ * fix (one-detector-no-drift — it never re-detects). The result is a prioritized,
+ * typed action list — the spine the measured A/B (the behavioral delta) stacks on.
+ *
+ * This is the "linting as a free pre-filter to measurement" thesis made a command:
+ * clear the structural dead-ends a model can't help with FIRST (free, certain),
+ * THEN spend tokens measuring whether the structurally-clean skills earn their keep.
+ *
+ * Distinct from `vigiles explain` (which diagnoses ONE underperforming surface a
+ * measurement flagged): `optimize` is the whole-repo adoption view — health score +
+ * the ranked fix list + the hand-off to the measured layer. Same findings, the
+ * optimization framing. See research/measurement-authority.md (A2) + roadmap §P1.
+ */
+const leaderboard_js_1 = require("./leaderboard.js");
+const score_explainer_js_1 = require("./score-explainer.js");
+function actionFor(e) {
+    return e.symptom === "wrong-skill-fires" ? "differentiate" : "fix";
+}
+function isEmptyMachine(r) {
+    const surfaces = r.skills.length + r.agents.length + r.hooks.length + r.commands;
+    return surfaces === 0 && !r.mcp;
+}
+/**
+ * Turn a scan report into a prioritized optimization plan: the structural-health
+ * score + a typed recommendation per deterministic finding (`likely` dead-ends
+ * before `possible` proxies, via explainScore's own ordering). Pure over the report.
+ */
+function optimize(report) {
+    const { score } = (0, leaderboard_js_1.scoreReport)(report);
+    const recommendations = (0, score_explainer_js_1.explainScore)(report).map((e) => ({
+        surface: e.surface,
+        action: actionFor(e),
+        rationale: e.cause,
+        fix: e.fix,
+        detector: e.detector,
+        confidence: e.confidence,
+    }));
+    return {
+        dir: report.dir,
+        score,
+        grade: (0, leaderboard_js_1.gradeFor)(score),
+        recommendations,
+        empty: isEmptyMachine(report),
+    };
+}
+const ACTION_LABEL = {
+    fix: "FIX",
+    differentiate: "DIFFERENTIATE",
+};
+const measureHint = (dir) => `\`vigiles scan ${dir} --trigger\` — real-model, runs on your subscription`;
+/** Render an optimization plan for the CLI. */
+function formatOptimize(rep) {
+    const head = `Harness health: ${String(rep.score)}/100 (${rep.grade}) — ${rep.dir}`;
+    if (rep.empty) {
+        return `${head}\n\nNothing loaded — this isn't a plugin/harness, or the load failed. Point optimize at a dir with a CLAUDE.md/AGENTS.md, skills, agents, or hooks.`;
+    }
+    if (rep.recommendations.length === 0) {
+        return `${head}\n\nNo deterministic fixes found — the structure is clean. Whether your skills actually help is a BEHAVIORAL question; measure it with ${measureHint(rep.dir)}.`;
+    }
+    const lines = [
+        head,
+        "",
+        `${String(rep.recommendations.length)} deterministic fix(es) — free, no model. Apply these before measuring:`,
+        "",
+    ];
+    for (const r of rep.recommendations) {
+        const mark = r.confidence === "likely" ? "✗" : "⚠";
+        lines.push(`${mark} [${ACTION_LABEL[r.action]}] ${r.surface}`);
+        lines.push(`    why: ${r.rationale}  [${r.detector}]`);
+        lines.push(`    →    ${r.fix}`);
+    }
+    lines.push("", `Then measure the behavioral delta of what's left (does each skill earn its keep?) with ${measureHint(rep.dir)}.`);
+    return lines.join("\n");
+}
+//# sourceMappingURL=optimize.js.map

package/dist/plugin-loader.d.ts

@@ -22,6 +22,7 @@ export interface LoadedPlugin {
  * `settings` with any inline settings and spread `files` into the fixture.
  */
 export declare function loadPlugin(pluginPath: string, layout: PluginLayout): LoadedPlugin;
+export declare function danglingRefs(root: string, layout: PluginLayout): string[];
 /**
  * Resolve the effective harness for a test/eval (arm): load the plugin if given,
  * then layer inline settings + files on top. Shared by `runHarnessTest` and

package/dist/plugin-loader.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadPlugin = loadPlugin;
+exports.danglingRefs = danglingRefs;
 exports.resolveHarness = resolveHarness;
 /**
  * vigiles — harness-agnostic plugin/repo harness loader (composition root).
@@ -208,34 +209,86 @@ const INTRA_REF_EXTS = "md|sh|cmd|mjs|cjs|js|ts|py|rb|txt|json";
 function intraRefRe(layout) {
     return new RegExp(`(?:${layout.intraRefDirs.join("|")})/[A-Za-z0-9._/-]+\\.(?:${INTRA_REF_EXTS})`, "g");
 }
+// Shell vars that root a path OUTSIDE the plugin (the user's project / home), so
+// a `surface/…` after one is NOT a plugin-root ref. Anything else ($ROOT,
+// $PLUGIN_ROOT, ${CLAUDE_PLUGIN_ROOT}, …) is taken as the plugin root.
+const NON_PLUGIN_VARS = new Set([
+    "CLAUDE_PROJECT_DIR",
+    "CLAUDE_PROJECT",
+    "HOME",
+    "PWD",
+    "OLDPWD",
+]);
+/**
+ * Is a surface-dir match at `idx` actually rooted at the PLUGIN (so checkable
+ * under `root`), vs nested under a literal dir or a project/home var? A match
+ * preceded by a literal segment (`.claude/hooks/…` — a PROJECT path, the
+ * gmickel/flow-next false positive) or a project var (`$CLAUDE_PROJECT_DIR/…`)
+ * is NOT a plugin ref. A bare ref (`cat skills/…`) or one after a plugin-root
+ * var (`${PLUGIN_ROOT}/skills/…`, obra/superpowers) IS.
+ */
+function isPluginRooted(content, idx) {
+    if (idx === 0 || content[idx - 1] !== "/")
+        return true; // bare / after quote-space
+    // The path component immediately before the separating slash.
+    const seg = /([^\s"'`(=:/]*)$/.exec(content.slice(0, idx - 1))?.[1] ?? "";
+    const varName = /^\$\{?(\w+)\}?$/.exec(seg)?.[1];
+    if (varName !== undefined)
+        return !NON_PLUGIN_VARS.has(varName); // a var root
+    return false; // a literal dir segment → nested, not a plugin-root ref
+}
+// Documentation files (skill bodies, command docs, reference notes) are PROSE —
+// a `skills/foo/SKILL.md` path inside them is almost always an example, a
+// template placeholder (`wc -w skills/path/SKILL.md`), or a "❌ Bad" sample, not
+// a real file operation. Scanning them produced near-100% false positives across
+// real plugins (wshobson/agents, obra/superpowers), so we skip them as SOURCES.
+// A path in an executable hook/helper script (incl. extensionless ones like
+// obra/superpowers' `hooks/session-start`) IS a real file op — those we scan.
+const DOC_SOURCE_RE = /\.(?:md|markdown|mdx|txt|rst)$/i;
 /**
  * Intra-plugin file references that don't resolve — the partial-vendor / broken-
- * path class (e.g. obra/superpowers' `SessionStart` reads
+ * path class (e.g. obra/superpowers' `hooks/session-start` reads
  * `skills/using-superpowers/SKILL.md`, which a sliced vendor snapshot omits). We
- * scan the plugin's own text files under the surface dirs (hooks scripts
- * included — those aren't materialized into `files`) for root-relative path refs
- * and report the ones missing on disk. A static check that would have caught a
- * bug the dogfood hit twice. Best-effort: a warning, not an error.
+ * scan the plugin's own EXECUTABLE files under the surface dirs (hook/helper
+ * scripts — those aren't materialized into `files`) for root-relative path refs
+ * and report the ones missing on disk. Documentation sources are deliberately
+ * excluded (see `DOC_SOURCE_RE`) — a path in prose is undecidably ref-or-example,
+ * the same heuristic-scanning anti-pattern reference verification rejects. A
+ * static check that would have caught a bug the dogfood hit twice. Best-effort:
+ * a warning, not an error.
  */
-function danglingRefs(root, layout) {
-    const missing = new Set();
-    const seen = new Set();
-    const re = intraRefRe(layout);
+/** Path refs in `content` (matched by `re`) that don't resolve under `root`. */
+function missingRefsIn(content, re, root) {
+    const out = [];
+    for (const m of content.matchAll(re)) {
+        if (m.index !== undefined && !isPluginRooted(content, m.index))
+            continue;
+        if (!(0, node_fs_1.existsSync)((0, node_path_1.join)(root, m[0])))
+            out.push(m[0]);
+    }
+    return out;
+}
+/** The plugin's executable (non-prose) source files under the surface dirs. */
+function executableSources(root, layout) {
+    const sources = {};
     for (const surface of layout.intraRefDirs) {
         const dir = (0, node_path_1.join)(root, surface);
         if (!(0, node_fs_1.existsSync)(dir) || !(0, node_fs_1.statSync)(dir).isDirectory())
             continue;
-        for (const content of Object.values(readTree(dir, root))) {
-            for (const m of content.matchAll(re)) {
-                const ref = m[0];
-                if (seen.has(ref))
-                    continue;
-                seen.add(ref);
-                if (!(0, node_fs_1.existsSync)((0, node_path_1.join)(root, ref)))
-                    missing.add(ref);
-            }
+        for (const [path, content] of Object.entries(readTree(dir, root))) {
+            if (!DOC_SOURCE_RE.test(path))
+                sources[path] = content; // skip prose
         }
     }
+    return sources;
+}
+function danglingRefs(root, layout) {
+    const re = intraRefRe(layout);
+    const missing = new Set();
+    for (const content of Object.values(executableSources(root, layout))) {
+        for (const ref of missingRefsIn(content, re, root))
+            missing.add(ref);
+    }
     return [...missing];
 }
 /**

package/dist/scaffold-test.d.ts

@@ -0,0 +1,30 @@
+export type SurfaceKind = "skill" | "agent" | "hook";
+/** The cheapest meaningful tier for a surface kind (mirrors the test-harness skill). */
+export type TestTier = "unit" | "harness" | "eval";
+/** What the generator needs to know about a surface to scaffold its test. */
+export interface ScaffoldInput {
+    readonly kind: SurfaceKind;
+    /** Skill dir name / agent name / hook-script basename. */
+    readonly name: string;
+    /** Repo-relative path to the surface (SKILL.md / agent .md / hook script). */
+    readonly path: string;
+    /** Plugin name for the namespaced skill id; a placeholder TODO when unknown. */
+    readonly pluginName?: string;
+    /** A user-invoked skill — trigger-rate is for model-invocable skills, so note it. */
+    readonly userInvoked?: boolean;
+    /** A subagent's declared tool contract (drives the assertion hint); null = inherits all. */
+    readonly tools?: readonly string[] | null;
+    /** How the CLI invokes the hook (e.g. `bash hooks/pre-edit.sh`); a TODO when unknown. */
+    readonly hookCommand?: string;
+}
+export interface Scaffold {
+    readonly path: string;
+    readonly content: string;
+    readonly kind: SurfaceKind;
+    readonly tier: TestTier;
+}
+/** Scaffold a starter test for one surface. Pure: path + content, no I/O. */
+export declare function scaffoldTest(input: ScaffoldInput): Scaffold;
+/** Render a set of scaffolds for the CLI (what was generated, where, which tier). */
+export declare function formatScaffolds(scaffolds: readonly Scaffold[]): string;
+//# sourceMappingURL=scaffold-test.d.ts.map

package/dist/scaffold-test.js

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scaffoldTest = scaffoldTest;
+exports.formatScaffolds = formatScaffolds;
+/**
+ * `vigiles scaffold-test` — the deterministic test-gen engine (B1 v0).
+ *
+ * Free-form in, a RUNNABLE starter test out. Given an existing hand-written
+ * skill / subagent / hook, emit a scaffolded `*.harness.mjs` / `*.eval.mjs` at the
+ * surface's suggested test path — the deterministic counterpart to the
+ * `test-harness` SKILL (which picks the tier with a model). The scaffold picks the
+ * cheapest meaningful tier for the kind, wires the real public API + the surface's
+ * own metadata (name, namespaced id, declared tools), and leaves TODOs only where a
+ * human/model must supply judgement (the prompts, the event input, the assertion).
+ *
+ * Pure + model-free: hand it a `ScaffoldInput`, get back a `{ path, content }`. The
+ * CLI resolves a surface path / plugin dir into inputs (reusing the scan + untested
+ * detectors) and writes the files; this module owns only the templating.
+ */
+const node_path_1 = require("node:path");
+const PLUGIN_TODO = "<plugin>";
+/**
+ * The suggested test path for a surface — mirrors `suggestedTestPath` in
+ * `test-coverage.ts` (a skill gets an `.eval.mjs`, agent/hook a `.harness.mjs`),
+ * so a generated file is colocated where the untested-surface detector looks for it
+ * and the surface stops being reported untested.
+ */
+function suggestedPath(input) {
+    const dir = (0, node_path_1.dirname)(input.path);
+    const ext = input.kind === "skill" ? "eval.mjs" : "harness.mjs";
+    return `${dir}/${input.name}.${ext}`;
+}
+function header(title, run) {
+    return [
+        "/**",
+        ` * ${title}`,
+        " *",
+        " * Generated by `vigiles scaffold-test` — a STARTER, not a finished test. Fill in",
+        " * the TODOs (they're where a human/model must supply judgement), then run:",
+        ` *   ${run}`,
+        " */",
+    ].join("\n");
+}
+/** A hook → the unit tier (`runHook`): free, no model, reaches every event. */
+function hookScaffold(input) {
+    const cmd = input.hookCommand ?? `bash ${input.path}`;
+    return `${header(`Starter unit test for the \`${input.name}\` hook.`, `npx vigiles test ${suggestedPath(input)}`)}
+import { runHook, assertHookAllowed } from "vigiles/unit";
+
+// TODO: set the event + input your hook actually inspects (PreToolUse/Bash shown).
+const event = {
+  hook_event_name: "PreToolUse",
+  tool_name: "Bash",
+  tool_input: { command: "echo hello" },
+};
+
+const r = runHook(${JSON.stringify(cmd)}, event);
+
+// TODO: assert the decision you expect. Use assertHookBlocked(r) for the deny case
+// (and a second runHook with the input that SHOULD be blocked).
+assertHookAllowed(r);
+console.log("✓ ${input.name}: hook allowed the benign event");
+`;
+}
+/** A skill → the eval tier (`measureTriggerRate`): does its description FIRE? */
+function skillScaffold(input) {
+    const id = `${input.pluginName ?? PLUGIN_TODO}:${input.name}`;
+    const note = input.userInvoked
+        ? "\n// NOTE: this skill is user-invoked (disableModelInvocation). Trigger-rate\n// measures MODEL-invocable skills; either make it model-invocable or test its\n// slash-command invocation with runHarnessTest instead.\n"
+        : "";
+    return `${header(`Starter trigger-rate eval for the \`${id}\` skill (recall + precision).`, `npx vigiles eval ${suggestedPath(input)}   # real model, on your subscription`)}
+import {
+  measureTriggerRate,
+  formatTriggerRateReport,
+  assertTriggerRate,
+  skillResolved,
+} from "vigiles/testing";
+import { fileURLToPath } from "node:url";
+${note}
+// TODO: point at the plugin root (the dir holding .claude-plugin/ or skills/).
+const pluginDir = fileURLToPath(new URL("../../", import.meta.url));
+const skill = ${JSON.stringify(id)};
+
+const report = await measureTriggerRate({
+  pluginDir,
+  stubSkillBodies: true, // firing is a frontmatter property — stub bodies, pay less
+  prompts: [
+    // TODO: >=5 varied prompts that SHOULD fire ${input.name} (recall).
+    "TODO: a realistic task that should trigger ${input.name}",
+  ],
+  irrelevantPrompts: [
+    // TODO: >=5 unrelated prompts that should NOT fire it (precision).
+    "TODO: an unrelated coding task",
+  ],
+  fired: (t) => skillResolved(t, skill),
+  trials: Number(process.env.VIGILES_TRIALS || 1),
+});
+
+console.log(formatTriggerRateReport(report));
+assertTriggerRate(report, { min: 0.8, maxFalsePositive: 0.3 });
+`;
+}
+/** A subagent → the deterministic harness tier; point at the railway/Result path. */
+function agentScaffold(input) {
+    const toolHint = input.tools && input.tools.length > 0
+        ? `assertToolUsed(r, ${JSON.stringify(input.tools[0])}); // its declared contract: ${input.tools.join(", ")}`
+        : `assertToolUsed(r, "Task"); // TODO: assert what the subagent should do`;
+    return `${header(`Starter harness test for the \`${input.name}\` subagent.`, `npx vigiles test ${suggestedPath(input)}`)}
+import { runHarnessTest, assertToolUsed } from "vigiles/testing";
+
+// A subagent's OUTCOME is best asserted via a result() contract — deterministic,
+// no LLM judge. If ${input.name} has one, use assertAgentOk(r.output, contract)
+// instead; see the railway-result example in the vigiles docs.
+
+const r = await runHarnessTest({
+  plugin: ".", // TODO: the plugin dir holding this subagent
+  // TODO: a prompt that dispatches ${input.name} (via the Task tool).
+  prompt: "TODO: a task that should dispatch ${input.name}",
+  transcript: true,
+  model: [{ text: "on it" }],
+});
+
+${toolHint}
+console.log("✓ ${input.name}: subagent test ran");
+`;
+}
+const TIER = {
+    hook: "unit",
+    skill: "eval",
+    agent: "harness",
+};
+const BUILDER = {
+    hook: hookScaffold,
+    skill: skillScaffold,
+    agent: agentScaffold,
+};
+/** Scaffold a starter test for one surface. Pure: path + content, no I/O. */
+function scaffoldTest(input) {
+    return {
+        path: suggestedPath(input),
+        content: BUILDER[input.kind](input),
+        kind: input.kind,
+        tier: TIER[input.kind],
+    };
+}
+/** Render a set of scaffolds for the CLI (what was generated, where, which tier). */
+function formatScaffolds(scaffolds) {
+    if (scaffolds.length === 0) {
+        return "Nothing to scaffold — every surface already has a test, or none was found.";
+    }
+    const lines = [`Scaffolded ${String(scaffolds.length)} starter test(s):`, ""];
+    for (const s of scaffolds) {
+        lines.push(`  ${s.path}  [${s.kind} → ${s.tier} tier]`);
+    }
+    lines.push("", "These are STARTERS — fill in the TODOs (prompts / event / assertions), then run", "them with `npx vigiles test` (deterministic) or `npx vigiles eval` (real model).");
+    return lines.join("\n");
+}
+//# sourceMappingURL=scaffold-test.js.map