vigiles 2.6.0 → 3.0.0

package/dist/plugin-loader.js

@@ -3,28 +3,38 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadPlugin = loadPlugin;
 exports.resolveHarness = resolveHarness;
 /**
- * vigiles — load a real plugin/repo harness for testing.
+ * vigiles — harness-agnostic plugin/repo harness loader (composition root).
  *
- * The unit that matters is not a single hook but the *assembled machine*: the
- * hooks, settings, CLAUDE.md, skills, subagents, and commands a plugin/repo
- * actually ships, working together. `loadPlugin` reads that real harness so a
- * `runHarnessTest` / `runEval` runs against what ships — not a hand-retyped
- * subset that can drift. Hooks, CLAUDE.md and skills are exercisable at the
- * deterministic tier; subagents/commands/MCP are materialized but only run under
- * a real model, so `LoadedPlugin.warnings` flags them (no silent empty machine).
+ * Lives at the app/composition root, NOT in any harness adapter, so every
+ * adapter (Claude Code, Codex, OpenCode, …) loads its plugin through the SAME
+ * loader by injecting its own `PluginLayout` — no adapter imports a sibling
+ * adapter. The unit that matters is not a single hook but the *assembled
+ * machine*: the hooks, settings, instruction file, skills, subagents, and
+ * commands a plugin/repo actually ships, working together. `loadPlugin` reads
+ * that real harness so a `runHarnessTest` / `runEval` runs against what ships —
+ * not a hand-retyped subset that can drift. Hooks, instruction file and skills
+ * are exercisable at the deterministic tier; subagents/commands/MCP are
+ * materialized but only run under a real model, so `LoadedPlugin.warnings` flags
+ * them (no silent empty machine).
  *
  *   runHarnessTest({ plugin: "./", model: scriptModel([...]) });
  *
- * Resolution order for hooks: inline `hooks` in `.claude-plugin/plugin.json`, a
- * `hooks` string path in plugin.json, the `hooks/hooks.json` convention (e.g.
- * obra/superpowers), then a plain repo's `.claude/settings.json`. `${CLAUDE_
- * PLUGIN_ROOT}` in any hook command is expanded to the plugin's absolute path,
- * so the real hook scripts run from where they live (no copying needed). The
- * plugin's CLAUDE.md and skills/ are materialized into the sandbox so the
- * assembled context is present too.
+ * Resolution order for hooks: inline `hooks` in the layout's manifest, a `hooks`
+ * string path in the manifest, the layout's `hooks` convention path (e.g.
+ * obra/superpowers' `hooks/hooks.json`), then a plain repo's settings file.
+ * The layout's plugin-root token in any hook command is expanded to the plugin's
+ * absolute path, so the real hook scripts run from where they live (no copying
+ * needed). The plugin's instruction file and skills/ are materialized into the
+ * sandbox so the assembled context is present too.
+ *
+ * `layout` is REQUIRED here — there is no harness default at the composition
+ * root. Each adapter supplies its own (the Claude Code wrapper at
+ * `src/adapters/claude-code/plugin-loader.ts` defaults it to `claudeCodeLayout`
+ * to preserve `loadPlugin(dir)` ergonomics and the public `vigiles/*` exports).
  */
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
+const toml_1 = require("@iarna/toml");
 const MAX_SKILL_FILE_BYTES = 256 * 1024;
 /** Parse a JSON file, or null on any error (missing / malformed). */
 function safeReadJson(path) {
@@ -39,6 +49,40 @@ function safeReadJson(path) {
 function readHooksFile(path) {
     return safeReadJson(path)?.hooks;
 }
+/**
+ * Parse the layout's manifest in its declared `settingsFormat` — JSON (Claude
+ * Code's plugin.json) or TOML (Codex's `config.toml`). A TOML harness's manifest
+ * (hooks, `[mcp_servers]`) would otherwise read as empty through the JSON path.
+ * Behaviour-identical to `safeReadJson` when the format is JSON.
+ */
+function safeReadManifest(root, layout) {
+    const path = (0, node_path_1.join)(root, layout.manifestPath);
+    if (layout.settingsFormat === "toml") {
+        try {
+            return (0, toml_1.parse)((0, node_fs_1.readFileSync)(path, "utf-8"));
+        }
+        catch {
+            return null;
+        }
+    }
+    return safeReadJson(path);
+}
+/**
+ * Read the `.hooks` field of a settings file in the layout's format — JSON
+ * (Claude Code's settings.json) or TOML (Codex's `config.toml` `[hooks]`). A
+ * TOML harness's hooks would otherwise be read as zero by the JSON path.
+ */
+function readSettingsHooks(path, format) {
+    if (format === "json")
+        return readHooksFile(path);
+    try {
+        return (0, toml_1.parse)((0, node_fs_1.readFileSync)(path, "utf-8"))
+            .hooks;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Read the hooks block, handling the real-world plugin layouts:
  *   1. inline `hooks` object in .claude-plugin/plugin.json,
@@ -46,22 +90,23 @@ function readHooksFile(path) {
  *   3. the `hooks/hooks.json` convention (e.g. obra/superpowers) — auto-discovered,
  *   4. a plain repo's `.claude/settings.json`.
  */
-function readHooks(root) {
-    // A malformed plugin.json must not crash the loader — fall through to the
-    // other layouts (safeReadJson returns null on a parse error).
-    const m = safeReadJson((0, node_path_1.join)(root, ".claude-plugin", "plugin.json"));
+function readHooks(root, layout) {
+    // A malformed manifest must not crash the loader — fall through to the
+    // other layouts (safeReadManifest returns null on a parse error). Format-aware
+    // so a Codex `config.toml` manifest's `[hooks]` is read, not skipped.
+    const m = safeReadManifest(root, layout);
     if (m) {
         if (typeof m.hooks === "string")
             return readHooksFile((0, node_path_1.join)(root, m.hooks));
         if (m.hooks !== undefined)
             return m.hooks;
     }
-    const conventionPath = (0, node_path_1.join)(root, "hooks", "hooks.json");
+    const conventionPath = (0, node_path_1.join)(root, layout.hooksConventionPath);
     if ((0, node_fs_1.existsSync)(conventionPath))
         return readHooksFile(conventionPath);
-    const settingsPath = (0, node_path_1.join)(root, ".claude", "settings.json");
+    const settingsPath = (0, node_path_1.join)(root, layout.settingsPath);
     if ((0, node_fs_1.existsSync)(settingsPath))
-        return readHooksFile(settingsPath);
+        return readSettingsHooks(settingsPath, layout.settingsFormat);
     return undefined;
 }
 /** Recursively collect text files under `dir` as `relativePath → contents`. */
@@ -85,39 +130,39 @@ function readTree(dir, base) {
  * sandbox, and `warnings` for surfaces the deterministic tier can't drive. Merge
  * `settings` with any inline settings and spread `files` into the fixture.
  */
-function loadPlugin(pluginPath) {
+function loadPlugin(pluginPath, layout) {
     const root = (0, node_path_1.resolve)(pluginPath);
-    const hooks = readHooks(root);
-    // Expand ${CLAUDE_PLUGIN_ROOT} to the real absolute path so the actual hook
+    const hooks = readHooks(root, layout);
+    // Expand the plugin-root token to the real absolute path so the actual hook
     // scripts execute — we test the shipped wiring, not a reimplementation.
     const resolvedHooks = hooks
-        ? JSON.parse(JSON.stringify(hooks).replaceAll("${CLAUDE_PLUGIN_ROOT}", root))
+        ? JSON.parse(JSON.stringify(hooks).replaceAll(layout.pluginRootToken, root))
         : undefined;
     const files = {};
-    const claudeMd = (0, node_path_1.join)(root, "CLAUDE.md");
-    if ((0, node_fs_1.existsSync)(claudeMd)) {
-        files["CLAUDE.md"] = (0, node_fs_1.readFileSync)(claudeMd, "utf-8");
+    const instructions = (0, node_path_1.join)(root, layout.instructionFile);
+    if ((0, node_fs_1.existsSync)(instructions)) {
+        files[layout.instructionFile] = (0, node_fs_1.readFileSync)(instructions, "utf-8");
     }
-    // Materialize each project-level surface under .claude/<surface>/ so the
+    // Materialize each project-level surface under the materialize root so the
     // assembled context is present in the sandbox (best-effort — headless
     // activation of plugin skills/subagents/commands is not guaranteed; the body
     // is present for the agent to read either way). Counting what we materialize
     // also lets us warn about surfaces the deterministic tier can't drive.
     const counts = {};
-    for (const surface of ["skills", "agents", "commands"]) {
+    for (const surface of layout.surfaceDirs) {
         const dir = (0, node_path_1.join)(root, surface);
         if (!(0, node_fs_1.existsSync)(dir) || !(0, node_fs_1.statSync)(dir).isDirectory())
             continue;
         const tree = readTree(dir, root);
         for (const [rel, content] of Object.entries(tree)) {
-            files[(0, node_path_1.join)(".claude", rel)] = content;
+            files[(0, node_path_1.join)(layout.materializeRoot, rel)] = content;
         }
         counts[surface] = Object.keys(tree).length;
     }
     return {
         settings: resolvedHooks ? { hooks: resolvedHooks } : {},
         files,
-        warnings: pluginWarnings(root, counts, resolvedHooks, files),
+        warnings: pluginWarnings(root, counts, resolvedHooks, files, layout),
     };
 }
 /**
@@ -127,7 +172,7 @@ function loadPlugin(pluginPath) {
  * the eval tier. MCP servers aren't wired by the loader at all. And a plugin
  * that yields neither hooks nor files would otherwise be a silent empty machine.
  */
-function pluginWarnings(root, counts, hooks, files) {
+function pluginWarnings(root, counts, hooks, files, layout) {
     const warnings = [];
     if (counts.agents) {
         warnings.push(`plugin defines ${String(counts.agents)} subagent file(s) under agents/ — these run only under a real model; test them at the eval tier (runEval), not the deterministic mock.`);
@@ -135,10 +180,10 @@ function pluginWarnings(root, counts, hooks, files) {
     if (counts.commands) {
         warnings.push(`plugin defines ${String(counts.commands)} slash-command file(s) under commands/ — slash-command invocation needs a real model; test at the eval tier.`);
     }
-    if (hasMcp(root)) {
-        warnings.push(`plugin declares MCP server(s) (mcpServers / .mcp.json) — the loader does not wire MCP; bring the server up yourself if your test needs it.`);
+    if (hasMcp(root, layout)) {
+        warnings.push(`plugin declares MCP server(s) (${layout.mcpManifestKey} / ${layout.mcpConfigFile}) — the loader does not wire MCP; bring the server up yourself if your test needs it.`);
     }
-    const dangling = danglingRefs(root);
+    const dangling = danglingRefs(root, layout);
     if (dangling.length) {
         const shown = dangling.slice(0, 5).join(", ");
         const more = dangling.length > 5 ? `, … (+${String(dangling.length - 5)})` : "";
@@ -149,16 +194,20 @@ function pluginWarnings(root, counts, hooks, files) {
     }
     return warnings;
 }
-/** Whether the plugin declares any MCP servers (manifest field or .mcp.json). */
-function hasMcp(root) {
-    if ((0, node_fs_1.existsSync)((0, node_path_1.join)(root, ".mcp.json")))
+/** Whether the plugin declares any MCP servers (manifest key or standalone file).
+ *  Format-aware: reads the layout's `mcpManifestKey` from a JSON OR TOML manifest,
+ *  so Codex's `[mcp_servers]` TOML table is detected, not silently missed. */
+function hasMcp(root, layout) {
+    if ((0, node_fs_1.existsSync)((0, node_path_1.join)(root, layout.mcpConfigFile)))
         return true;
-    return (safeReadJson((0, node_path_1.join)(root, ".claude-plugin", "plugin.json"))?.mcpServers !==
-        undefined);
+    return safeReadManifest(root, layout)?.[layout.mcpManifestKey] !== undefined;
 }
 // A plugin-relative path reference to a file under a standard surface dir, with a
 // known extension — e.g. a hook script that `cat`s `skills/using-superpowers/SKILL.md`.
-const INTRA_REF_RE = /(?:skills|hooks|commands|agents)\/[A-Za-z0-9._/-]+\.(?:md|sh|cmd|mjs|cjs|js|ts|py|rb|txt|json)/g;
+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");
+}
 /**
  * Intra-plugin file references that don't resolve — the partial-vendor / broken-
  * path class (e.g. obra/superpowers' `SessionStart` reads
@@ -168,15 +217,16 @@ const INTRA_REF_RE = /(?:skills|hooks|commands|agents)\/[A-Za-z0-9._/-]+\.(?:md|
  * 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.
  */
-function danglingRefs(root) {
+function danglingRefs(root, layout) {
     const missing = new Set();
     const seen = new Set();
-    for (const surface of ["hooks", "skills", "agents", "commands"]) {
+    const re = intraRefRe(layout);
+    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(INTRA_REF_RE)) {
+            for (const m of content.matchAll(re)) {
                 const ref = m[0];
                 if (seen.has(ref))
                     continue;
@@ -215,11 +265,13 @@ function mergeSettings(base, override) {
 /**
  * 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
- * `runEval` so both test the assembled machine the same way.
+ * `runEval` so both test the assembled machine the same way. `layout` is
+ * REQUIRED (no harness default at the composition root) — the Claude Code
+ * wrapper supplies `claudeCodeLayout` to preserve `resolveHarness(opts)`.
  */
-function resolveHarness(opts) {
+function resolveHarness(opts, layout) {
     const loaded = opts.plugin
-        ? loadPlugin(opts.plugin)
+        ? loadPlugin(opts.plugin, layout)
         : { settings: {}, files: {} };
     return {
         files: { ...loaded.files, ...opts.files },

package/dist/scan.d.ts

@@ -0,0 +1,49 @@
+/**
+ * `vigiles scan <dir>` — point vigiles at any plugin/repo and see what it ships
+ * and what's broken, with **no model and no API key**.
+ *
+ * This is the deterministic substrate under the plugin/skill leaderboard
+ * (research/divergent-bets.md #9) and the harness-aware audit
+ * (research/agent-supply-chain-security.md #1): it re-aims the machinery that
+ * already exists — `loadPlugin` (surfaces + dangling-ref/MCP/empty-machine
+ * warnings), `parseAgentTools` (the declared tool contract), and
+ * `findUntestedSurfaces` — into one read-only report. Behavioral checks that
+ * need to RUN the plugin (observed egress under the sandbox, real trigger-rate)
+ * stack on top later; this core stays pure so it runs anywhere in CI for free.
+ */
+import type { PluginLayout } from "./core/layout.js";
+export interface ScanSkill {
+    readonly name: string;
+    readonly path: string;
+    readonly hasDescription: boolean;
+    readonly userInvoked: boolean;
+}
+export interface ScanAgent {
+    readonly name: string;
+    readonly path: string;
+    /** Declared tool contract, or null when the agent ships no `tools:` (inherits all). */
+    readonly tools: readonly string[] | null;
+}
+/** ok = file present; missing = referenced but absent; unresolved = path still has an unexpanded var, can't check. */
+export type HookStatus = "ok" | "missing" | "unresolved";
+export interface ScanHook {
+    readonly script: string;
+    readonly status: HookStatus;
+}
+export interface ScanReport {
+    readonly dir: string;
+    readonly skills: readonly ScanSkill[];
+    readonly agents: readonly ScanAgent[];
+    readonly hooks: readonly ScanHook[];
+    /** Hook entries with no script file (inline shell one-liners) — can't be path-checked. */
+    readonly inlineHooks: number;
+    readonly commands: number;
+    readonly mcp: boolean;
+    readonly warnings: readonly string[];
+    readonly untested: number;
+}
+/** Scan a plugin/repo directory and report its surfaces + structural issues. */
+export declare function scanPlugin(dir: string, layout?: PluginLayout): ScanReport;
+/** Format a scan report as human-readable text. */
+export declare function formatScanReport(r: ScanReport): string;
+//# sourceMappingURL=scan.d.ts.map

package/dist/scan.js

@@ -0,0 +1,177 @@
+"use strict";
+/**
+ * `vigiles scan <dir>` — point vigiles at any plugin/repo and see what it ships
+ * and what's broken, with **no model and no API key**.
+ *
+ * This is the deterministic substrate under the plugin/skill leaderboard
+ * (research/divergent-bets.md #9) and the harness-aware audit
+ * (research/agent-supply-chain-security.md #1): it re-aims the machinery that
+ * already exists — `loadPlugin` (surfaces + dangling-ref/MCP/empty-machine
+ * warnings), `parseAgentTools` (the declared tool contract), and
+ * `findUntestedSurfaces` — into one read-only report. Behavioral checks that
+ * need to RUN the plugin (observed egress under the sandbox, real trigger-rate)
+ * stack on top later; this core stays pure so it runs anywhere in CI for free.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scanPlugin = scanPlugin;
+exports.formatScanReport = formatScanReport;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const plugin_loader_js_1 = require("./adapters/claude-code/plugin-loader.js");
+const agent_runtime_js_1 = require("./adapters/claude-code/agent-runtime.js");
+const test_coverage_js_1 = require("./test-coverage.js");
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+const SCRIPT_RE = /\S+\.(?:sh|mjs|cjs|js|ts|py|rb)\b/g;
+function frontmatter(md) {
+    const m = /(?:^|\n)---\r?\n([\s\S]*?)\r?\n---/.exec(md);
+    if (!m)
+        return {};
+    const name = /^name:\s*(.+)$/m.exec(m[1])?.[1]?.trim();
+    const description = /^description:\s*(.+)$/m.exec(m[1])?.[1]?.trim();
+    return { name, description };
+}
+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 skillName(path) {
+    return (path
+        .replace(/\/SKILL\.md$/, "")
+        .split("/")
+        .pop() ?? path);
+}
+function scanSkills(files) {
+    const out = [];
+    for (const [path, md] of Object.entries(files)) {
+        if (!isSkill(path))
+            continue;
+        const fm = frontmatter(md);
+        out.push({
+            name: fm.name ?? skillName(path),
+            path,
+            hasDescription: Boolean(fm.description && fm.description.length >= 20),
+            userInvoked: /^\s*disable-model-invocation:\s*true\s*$/m.test(md),
+        });
+    }
+    return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+function scanAgents(files) {
+    const out = [];
+    for (const [path, md] of Object.entries(files)) {
+        if (!isAgent(path))
+            continue;
+        out.push({ name: (0, node_path_1.basename)(path, ".md"), path, tools: (0, agent_runtime_js_1.parseAgentTools)(md) });
+    }
+    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.
+ */
+function resolveScript(token, root) {
+    const path = token
+        .replace(/["']/g, "")
+        .replaceAll("${CLAUDE_PLUGIN_ROOT}", root)
+        .replaceAll("$CLAUDE_PLUGIN_ROOT", root);
+    if (path.includes("$"))
+        return { script: token, status: "unresolved" };
+    return { script: path, status: (0, node_fs_1.existsSync)(path) ? "ok" : "missing" };
+}
+/** Pull script-file hook commands out of the resolved settings; count inline ones. */
+function scanHooks(settings, root) {
+    const text = JSON.stringify(settings.hooks ?? {});
+    const commands = [...text.matchAll(/"command":\s*"((?:[^"\\]|\\.)*)"/g)].map((m) => m[1]);
+    const byScript = new Map();
+    let inline = 0;
+    for (const cmd of commands) {
+        const unescaped = cmd.replace(/\\(.)/g, "$1");
+        const found = unescaped.match(SCRIPT_RE);
+        if (!found || found.length === 0) {
+            inline++;
+            continue;
+        }
+        for (const tok of found) {
+            const hook = resolveScript(tok, root);
+            byScript.set(hook.script, hook);
+        }
+    }
+    const hooks = [...byScript.values()].sort((a, b) => a.script.localeCompare(b.script));
+    return { hooks, inline };
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/** Scan a plugin/repo directory and report its surfaces + structural issues. */
+function scanPlugin(dir, layout) {
+    const loaded = (0, plugin_loader_js_1.loadPlugin)(dir, layout);
+    const { hooks, inline } = scanHooks(loaded.settings, (0, node_path_1.resolve)(dir));
+    return {
+        dir,
+        skills: scanSkills(loaded.files),
+        agents: scanAgents(loaded.files),
+        hooks,
+        inlineHooks: inline,
+        commands: Object.keys(loaded.files).filter(isCommand).length,
+        mcp: loaded.warnings.some((w) => w.includes("MCP server")),
+        warnings: loaded.warnings,
+        untested: (0, test_coverage_js_1.findUntestedSurfaces)({ basePath: dir }).untested.length,
+    };
+}
+function section(title, lines) {
+    if (lines.length === 0)
+        return [];
+    return [`${title} (${String(lines.length)}):`, ...lines, ""];
+}
+/** Format a scan report as human-readable text. */
+function formatScanReport(r) {
+    const out = [`Scan: ${r.dir}`, ""];
+    out.push(...section("Skills", r.skills.map((s) => {
+        const mark = s.hasDescription ? "✓" : "⚠";
+        const note = s.hasDescription
+            ? s.userInvoked
+                ? "(user-invoked)"
+                : ""
+            : "(missing/short description — can't trigger)";
+        return `  ${mark} ${s.name} ${note}`.trimEnd();
+    })));
+    out.push(...section("Agents", r.agents.map((a) => {
+        const tools = a.tools === null
+            ? "tools: (inherits all — no contract)"
+            : `tools: ${a.tools.join(", ") || "(none)"}`;
+        return `  ${a.tools === null ? "⚠" : "✓"} ${a.name} — ${tools}`;
+    })));
+    const hookMark = {
+        ok: "✓",
+        missing: "✗",
+        unresolved: "?",
+    };
+    const hookNote = {
+        ok: "",
+        missing: " (referenced but MISSING)",
+        unresolved: " (unresolved var — can't check)",
+    };
+    const hookLines = r.hooks.map((h) => `  ${hookMark[h.status]} ${h.script}${hookNote[h.status]}`);
+    if (r.inlineHooks > 0) {
+        hookLines.push(`  · ${String(r.inlineHooks)} inline hook(s) (no script file)`);
+    }
+    out.push(...section("Hooks", hookLines));
+    const facts = [];
+    if (r.commands > 0)
+        facts.push(`Commands: ${String(r.commands)}`);
+    facts.push(`MCP servers: ${r.mcp ? "yes" : "no"}`);
+    facts.push(`Untested surfaces: ${String(r.untested)}`);
+    out.push(...facts, "");
+    if (r.warnings.length > 0) {
+        out.push("Warnings:", ...r.warnings.map((w) => `  - ${w}`), "");
+    }
+    const broken = r.hooks.filter((h) => h.status === "missing").length +
+        r.skills.filter((s) => !s.hasDescription).length;
+    out.push(broken === 0
+        ? "✓ no structural issues found"
+        : `⚠ ${String(broken)} structural issue(s) — see ✗/⚠ above`);
+    return out.join("\n");
+}
+//# sourceMappingURL=scan.js.map

package/dist/setup-plan.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Pure decision logic for `vigiles init`.
+ *
+ * Turns CLI args + whether a human's at a TTY into a concrete setup PLAN, so the
+ * IO-heavy `setup()` in cli.ts stays a thin shell and every choice is unit-tested.
+ * Best-practice onboarding: **interactive** when a human runs it in a terminal,
+ * **non-interactive** (sensible defaults) for agents / CI / piped input — so
+ * "set up vigiles" from a Claude Code or Codex prompt Just Works without hanging
+ * on a prompt. See docs/agent-setup.md.
+ */
+/** What `vigiles init` will set up. */
+export interface SetupPlan {
+    /** Pillar 1 — verify instruction files (specs, types, compile, audit, hooks). */
+    verify: boolean;
+    /** Pillar 2 — test the harness (scaffold a starter harness test + CI job). */
+    test: boolean;
+    /** Wire CI (the `zernie/vigiles@v1` Action; creates a workflow if none). */
+    gha: boolean;
+    /** Install the Claude Code plugin (hooks + skills). */
+    plugin: boolean;
+    /** Strict rule severities in `.vigilesrc.json`. */
+    strict: boolean;
+}
+/** The explicit choices a user pinned via flags (undefined = "not specified"). */
+export interface ParsedSetupArgs {
+    target?: string;
+    strict: boolean;
+    yes: boolean;
+    pillars?: "verify" | "test" | "both";
+    gha?: boolean;
+    plugin?: boolean;
+}
+/** Parse `init` args into the choices the user pinned. */
+export declare function parseSetupArgs(args: readonly string[]): ParsedSetupArgs;
+/** The non-interactive defaults: both pillars, CI, and the plugin. */
+export declare function defaultPlan(strict?: boolean): SetupPlan;
+/**
+ * Whether to drop into interactive prompts: a human at a TTY who passed neither
+ * `--yes` nor an explicit `--target`, and who hasn't already pinned every choice
+ * via flags. Agents / CI / piped input (no TTY) never prompt.
+ */
+export declare function shouldPrompt(parsed: ParsedSetupArgs, isTTY: boolean): boolean;
+/** Interactive answers (only the fields the prompts cover). */
+export type SetupAnswers = Partial<Pick<SetupPlan, "verify" | "test" | "gha" | "plugin">>;
+/**
+ * Resolve the final plan: defaults, then flags, then interactive answers (each
+ * layer overrides the previous only where it has an opinion). `--target` pins a
+ * bare Pillar-1 spec (no harness scaffold).
+ */
+export declare function resolvePlan(parsed: ParsedSetupArgs, answers?: SetupAnswers): SetupPlan;
+//# sourceMappingURL=setup-plan.d.ts.map

package/dist/setup-plan.js

@@ -0,0 +1,85 @@
+"use strict";
+/**
+ * Pure decision logic for `vigiles init`.
+ *
+ * Turns CLI args + whether a human's at a TTY into a concrete setup PLAN, so the
+ * IO-heavy `setup()` in cli.ts stays a thin shell and every choice is unit-tested.
+ * Best-practice onboarding: **interactive** when a human runs it in a terminal,
+ * **non-interactive** (sensible defaults) for agents / CI / piped input — so
+ * "set up vigiles" from a Claude Code or Codex prompt Just Works without hanging
+ * on a prompt. See docs/agent-setup.md.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseSetupArgs = parseSetupArgs;
+exports.defaultPlan = defaultPlan;
+exports.shouldPrompt = shouldPrompt;
+exports.resolvePlan = resolvePlan;
+function flagValue(args, prefix) {
+    return args.find((a) => a.startsWith(prefix))?.slice(prefix.length);
+}
+/** Parse `init` args into the choices the user pinned. */
+function parseSetupArgs(args) {
+    const pillarsRaw = flagValue(args, "--pillars=");
+    const pillars = pillarsRaw === "verify" || pillarsRaw === "test" || pillarsRaw === "both"
+        ? pillarsRaw
+        : undefined;
+    return {
+        target: flagValue(args, "--target="),
+        strict: args.includes("--strict"),
+        yes: args.includes("--yes") || args.includes("-y"),
+        pillars,
+        gha: args.includes("--no-gha") ? false : undefined,
+        plugin: args.includes("--no-plugin") ? false : undefined,
+    };
+}
+/** The non-interactive defaults: both pillars, CI, and the plugin. */
+function defaultPlan(strict = false) {
+    return { verify: true, test: true, gha: true, plugin: true, strict };
+}
+/**
+ * Whether to drop into interactive prompts: a human at a TTY who passed neither
+ * `--yes` nor an explicit `--target`, and who hasn't already pinned every choice
+ * via flags. Agents / CI / piped input (no TTY) never prompt.
+ */
+function shouldPrompt(parsed, isTTY) {
+    if (!isTTY || parsed.yes || parsed.target)
+        return false;
+    const allPinned = parsed.pillars !== undefined &&
+        parsed.gha !== undefined &&
+        parsed.plugin !== undefined;
+    return !allPinned;
+}
+/**
+ * Resolve the final plan: defaults, then flags, then interactive answers (each
+ * layer overrides the previous only where it has an opinion). `--target` pins a
+ * bare Pillar-1 spec (no harness scaffold).
+ */
+function resolvePlan(parsed, answers) {
+    const plan = defaultPlan(parsed.strict);
+    if (parsed.pillars === "verify") {
+        plan.verify = true;
+        plan.test = false;
+    }
+    else if (parsed.pillars === "test") {
+        plan.verify = false;
+        plan.test = true;
+    }
+    if (parsed.gha === false)
+        plan.gha = false;
+    if (parsed.plugin === false)
+        plan.plugin = false;
+    if (parsed.target)
+        plan.test = false;
+    if (answers) {
+        if (answers.verify !== undefined)
+            plan.verify = answers.verify;
+        if (answers.test !== undefined)
+            plan.test = answers.test;
+        if (answers.gha !== undefined)
+            plan.gha = answers.gha;
+        if (answers.plugin !== undefined)
+            plan.plugin = answers.plugin;
+    }
+    return plan;
+}
+//# sourceMappingURL=setup-plan.js.map

package/dist/skill-test.d.ts

@@ -8,7 +8,7 @@
  * gate blocked. The model's prose quality is never asserted — that's the
  * probabilistic boundary; everything else is deterministic and checkable.
  */
-import { type SkillProgram, type GeneratorSkill } from "./skill-driver.js";
+import { type SkillProgram, type GeneratorSkill } from "./adapters/claude-code/skill-driver.js";
 export type ModelFn = (prose: string) => string;
 /**
  * Script the mocked model. Pass:

package/dist/skill-test.js

@@ -12,7 +12,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.scriptModel = scriptModel;
 exports.runSkill = runSkill;
-const skill_driver_js_1 = require("./skill-driver.js");
+const skill_driver_js_1 = require("./adapters/claude-code/skill-driver.js");
 function gateLabel(g) {
     if (g._ref === "cmd")
         return g.command;