vigiles 5.1.0 → 5.2.0

package/dist/core/validate.js

@@ -43,15 +43,15 @@ const DEFAULT_RULES = {
     coverage: false,
     // Per-kind surface-coverage: a skill/agent/hook must ship with a test or eval.
     "untested-skill": "warn",
-    "untested-agent": "warn",
+    "untested-subagent": "warn",
     "untested-hook": "warn",
     "unmarked-refs": "warn",
     // High-precision (never-available + close typos only), so on by default at warn.
-    "agent-tool-contract": "warn",
+    "subagent-tool-contract": "warn",
     // High-precision (close typos only), on by default at warn.
     "hook-events": "warn",
     // Missing required frontmatter (name/description) — on by default at warn.
-    "agent-frontmatter": "warn",
+    "subagent-frontmatter": "warn",
     // A declared MCP server with no command/url can't start — on by default at warn.
     "mcp-config": "warn",
     // Best-practice nudge (skills load without frontmatter) — warn, not error.
@@ -60,7 +60,7 @@ const DEFAULT_RULES = {
     "mcp-tool-resolves": "warn",
     // A hook script referenced but missing never runs — on by default at warn.
     "hook-script-exists": "warn",
-    // High-precision (close-typo only) deny-list mirror of agent-tool-contract.
+    // High-precision (close-typo only) deny-list mirror of subagent-tool-contract.
     "disallowed-tools-contract": "warn",
     // Deterministic NCD precision proxy (near-identical skill descriptions) — warn.
     "description-overlap": "warn",

package/dist/harness-test.d.ts

@@ -110,6 +110,13 @@ export interface SubagentTrace {
     readonly name: string;
     /** The tools the subagent invoked (events tagged with the Task's id). */
     readonly toolCalls: readonly ToolCall[];
+    /**
+     * The subagent's RETURNED text — the dispatch tool_result the orchestrator
+     * receives back. This is where a `result()` contract's `vigiles:ok`/`vigiles:err`
+     * block lands, so `subagent(name, [output(/vigiles:ok/)])` can assert the typed
+     * outcome. "" if not captured.
+     */
+    readonly output: string;
 }
 export interface HarnessTestResult extends Trace {
     readonly exitCode: number;

package/dist/harness-test.js

@@ -130,6 +130,7 @@ function parseToolCalls(streamJson) {
  */
 function parseSubagents(streamJson) {
     const tasks = new Map(); // dispatch id → subagent name
+    const dispatchOutput = new Map(); // dispatch id → returned text
     const byParent = new Map();
     const groupFor = (parent) => {
         let g = byParent.get(parent);
@@ -162,7 +163,10 @@ function parseSubagents(streamJson) {
                     // A subagent dispatch is any top-level tool_use whose input carries a
                     // `subagent_type` — the dispatch tool is named "Agent" on the live CLI
                     // (older docs say "Task"), so match the input field, NOT the tool name,
-                    // to survive the rename. Confirmed against real claude output.
+                    // to survive the rename. Confirmed against real claude output. CC NOTE:
+                    // under `--plugin-dir` the value is NAMESPACED `plugin:agent` (captured
+                    // "reviewer-spec:code-reviewer"); the bare agent name is matched in the
+                    // `subagent()` check (src/check.ts), so the full id is preserved here.
                     const sub = b.input?.subagent_type;
                     if (typeof sub === "string")
                         tasks.set(id, sub);
@@ -170,12 +174,20 @@ function parseSubagents(streamJson) {
                 if (parent)
                     groupFor(parent).uses.push({ id, name: b.name, input: b.input });
             }
-            else if (b.type === "tool_result" && parent) {
+            else if (b.type === "tool_result") {
                 const id = typeof b.tool_use_id === "string" ? b.tool_use_id : "";
-                groupFor(parent).results.set(id, {
-                    text: contentText(b.content),
-                    isError: b.is_error === true,
-                });
+                if (parent) {
+                    groupFor(parent).results.set(id, {
+                        text: contentText(b.content),
+                        isError: b.is_error === true,
+                    });
+                }
+                else if (id) {
+                    // A top-level tool_result whose id is a subagent dispatch is the SUB's
+                    // RETURN to the orchestrator (where a result() vigiles:ok/err block
+                    // lands). Record it; matched to its dispatch by id below.
+                    dispatchOutput.set(id, contentText(b.content));
+                }
             }
         }
     }
@@ -188,7 +200,7 @@ function parseSubagents(streamJson) {
             resultText: g?.results.get(u.id)?.text ?? "",
             isError: g?.results.get(u.id)?.isError ?? false,
         }));
-        out.push({ name, toolCalls });
+        out.push({ name, toolCalls, output: dispatchOutput.get(taskId) ?? "" });
     }
     return out;
 }

package/dist/leaderboard.d.ts

@@ -21,6 +21,8 @@ export interface PluginScore {
     readonly issues: readonly string[];
     readonly report: ScanReport;
 }
+/** Map a 0–100 structural-health score to its letter grade (A ≥90 … F <60). */
+export declare function gradeFor(score: number): PluginScore["grade"];
 /** Deterministic structural-health score for one scanned plugin. */
 export declare function scoreReport(r: ScanReport): {
     score: number;

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;
@@ -23,6 +24,7 @@ const W_NO_DESCRIPTION = 10; // a skill with no usable description → can't tri
 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";

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/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

package/dist/scan.d.ts

@@ -19,6 +19,7 @@ import { type McpIssue } from "./core/mcp-config.js";
 import { type DescriptionOverlap } from "./core/description-overlap.js";
 import { type McpToolIssue } from "./core/mcp-tool.js";
 import { type McpHookIssue } from "./core/mcp-hook.js";
+import { type PurityLevel, type EffectSurface } from "./core/effects.js";
 /** A named writing system. The label `unexpectedScript` reports + the config's expectation parse into this. */
 export type Script = "Latin" | "Cyrillic" | "Han" | "Japanese" | "Korean" | "Arabic" | "Hebrew" | "Greek" | "Devanagari" | "Thai";
 export interface ScanSkill {
@@ -47,6 +48,19 @@ export interface ScanAgent {
     readonly mcpToolIssues: readonly McpToolIssue[];
     /** `disallowedTools:` block-list entries that are typos of a real tool (block nothing). */
     readonly disallowedToolIssues: readonly ToolIssue[];
+    /**
+     * Static effect-surface purity of the agent's declared tool contract.
+     * - `"pure"` — no side-effecting tools (read-only, deterministically testable).
+     * - `"bounded"` — has side-effecting tools (Edit/Write/…) but no Bash or unknown.
+     * - `"unrestricted"` — has Bash, any MCP/unknown tool, or inherits-all (no contract).
+     * Computed by `effectSurface()` from `src/core/effects.ts` — one detector, no drift.
+     */
+    readonly purity: PurityLevel;
+    /**
+     * The three tool buckets from `effectSurface()`: read-only, side-effecting, and
+     * unknown-effect (MCP or unrecognized) tool names in the declared contract.
+     */
+    readonly effectBuckets: Pick<EffectSurface, "readOnly" | "sideEffecting" | "unknown">;
 }
 /** A skill/agent whose frontmatter is missing a required field (name / description). */
 export interface FrontmatterIssue {
@@ -121,6 +135,32 @@ export interface ScanReport {
     readonly malformedFrontmatter: readonly FrontmatterParseIssue[];
     readonly warnings: readonly string[];
     readonly untested: number;
+    /**
+     * Harness-level purity summary: how many scanned agents fall into each purity
+     * rung. A high `pure` count means more of the harness is statically testable
+     * (deterministic, no mocks); `unrestricted` is the blind-spot count.
+     * Computed by `effectSurface()` (one detector, no drift).
+     */
+    readonly puritySummary: {
+        pure: number;
+        bounded: number;
+        unrestricted: number;
+    };
+}
+/**
+ * Per-kind surface classifiers, built from the harness `PluginLayout`'s
+ * `skillDir`/`agentDir`/`commandDir` — so adding a harness whose subagents live
+ * somewhere other than `agents/` (OpenCode's `.opencode/agent`) needs no change
+ * here. Each anchors 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.
+ */
+export interface SurfaceClassifier {
+    readonly isSkill: (f: string) => boolean;
+    readonly isAgent: (f: string) => boolean;
+    readonly isCommand: (f: string) => boolean;
 }
 /**
  * The description's dominant alphabetic script when it DIFFERS from `expected`