vigiles 5.1.0 → 6.0.0

package/dist/scaffold-test.js

@@ -0,0 +1,263 @@
+"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 JSON value placeholder for an `OutputFieldType`, for the `vigiles:ok` block. */
+function placeholderFor(type) {
+    switch (type) {
+        case "number":
+            return 1;
+        case "boolean":
+            return true;
+        case "string[]":
+            return ["example"];
+        default:
+            return "example";
+    }
+}
+/** Render a `result(ok, err)` builder call reconstructed from the parsed contract. */
+function renderContractBuilder(contract) {
+    const shape = (fields) => `{ ${fields.map((f) => `${f.name}: ${JSON.stringify(f.type)}`).join(", ")} }`;
+    return `result(\n  ${shape(contract.ok)},\n  ${shape(contract.err)},\n)`;
+}
+/**
+ * The OUTCOME test, GENERATED FROM the subagent's `result()` contract: reconstruct
+ * the contract, build a matching `vigiles:ok` block, and `assertAgentOk` it —
+ * deterministic, no LLM judge. This is the typed-spec payoff a markdown
+ * `description:` cannot give you: a parseable, typed outcome a test reads directly.
+ */
+function outcomeSection(input, contract) {
+    const okValue = Object.fromEntries(contract.ok.map((f) => [f.name, placeholderFor(f.type)]));
+    const firstField = contract.ok[0]?.name;
+    const fieldAssertion = firstField
+        ? `// TODO: assert the VALUES you expect (the shape is already validated above), e.g.:\n//   assert.ok(value.${firstField}, "expected a ${firstField}");`
+        : "";
+    return `import assert from "node:assert/strict";
+import { result } from "vigiles/spec";
+import { assertAgentOk } from "vigiles/testing";
+
+// Reconstructed from ${input.name}'s ## Output contract (its compiled .md) — the
+// typed result() the spec wrote. assertAgentOk parses + validates the outcome
+// with NO model judge; swap \`okOutput\` for a real \`runHarness\` turn (Part B in
+// examples/harness/railway-result.harness.mjs) to assert REAL behaviour.
+const contract = ${renderContractBuilder(contract)};
+
+const okOutput = [
+  "${input.name} finished its task.",
+  "\`\`\`vigiles:ok",
+  ${JSON.stringify(JSON.stringify(okValue))},
+  "\`\`\`",
+].join("\\n");
+
+const value = assertAgentOk(okOutput, contract); // deterministic — no LLM judge
+${fieldAssertion}
+console.log("✓ ${input.name}: result() outcome parses + validates against its typed contract");
+`;
+}
+/** The fallback when the subagent has no `result()` contract — assert a tool use. */
+function fallbackSection(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 `import { runHarnessTest, assertToolUsed } from "vigiles/testing";
+
+// ${input.name} has no result() contract, so its outcome can't be asserted
+// deterministically — add one (result() on its agent() spec) for a no-judge
+// outcome test. For now, assert it reaches for the right tool.
+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");
+`;
+}
+/**
+ * The SAFETY check, GENERATED FROM the subagent's side-effecting `tools`: assert it
+ * stays inside its declared write surface and never reaches for a destructive op.
+ * The `tools` allowlist + effectSurface identify the "hole"; the check asserts it —
+ * a test the typed contract writes for you (markdown can declare the tools, not test them).
+ */
+function safetySection(input, sideEffecting) {
+    const checks = [];
+    if (sideEffecting.includes("Bash")) {
+        checks.push(`  notTool("Bash", { command: /git push|rm -rf/ }), // never a destructive op`);
+    }
+    if (sideEffecting.some((t) => t === "Write" || t === "Edit")) {
+        checks.push(`  didNotWrite("secrets.env"), // TODO: the path(s) it must NOT write outside its surface`);
+    }
+    if (checks.length === 0) {
+        checks.push(`  // TODO: a notTool()/didNotWrite() per side-effecting tool: ${sideEffecting.join(", ")}`);
+    }
+    return `
+// --- Safety (deterministic) — generated from ${input.name}'s side-effecting tools: ${sideEffecting.join(", ")} ---
+// In a real run, replace this constructed Trace with a real \`runHarness\` /
+// \`measure\` turn (use interceptTools so a real model's attempt is DENIED, never
+// executed — see docs/eval-architecture.md). The checks below are derived from the
+// declared tools contract — the agent's "hole" asserted to stay in its lane.
+{
+  const trace = {
+    output: "done",
+    turns: 1,
+    hooks: [],
+    toolCalls: [
+      // TODO: the tool calls a benign run of ${input.name} makes.
+      { name: "Bash", input: { command: "git status" } },
+    ],
+    file: () => null,
+  };
+  assertChecks(trace, [
+${checks.join("\n")}
+  ]);
+  console.log("✓ ${input.name}: stayed inside its declared side-effect surface");
+}
+`;
+}
+/** A subagent → deterministic outcome + safety tests, generated from its typed contract. */
+function agentScaffold(input) {
+    const head = header(`Starter harness test for the \`${input.name}\` subagent.`, `npx vigiles test ${suggestedPath(input)}`);
+    const safetyImport = input.sideEffectingTools && input.sideEffectingTools.length > 0
+        ? `import { notTool, didNotWrite, assertChecks } from "vigiles/testing";\n`
+        : "";
+    const body = input.resultContract
+        ? outcomeSection(input, input.resultContract)
+        : fallbackSection(input);
+    const safety = input.sideEffectingTools && input.sideEffectingTools.length > 0
+        ? safetySection(input, input.sideEffectingTools)
+        : "";
+    return `${head}\n${safetyImport}${body}${safety}`;
+}
+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`

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.