vigiles 2.5.0 → 3.0.0

package/dist/cli.js

@@ -13,27 +13,34 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const glob_1 = require("glob");
-const generate_types_js_1 = require("./generate-types.js");
-const validate_js_1 = require("./validate.js");
-const types_js_1 = require("./types.js");
-const compile_js_1 = require("./compile.js");
-const proofs_js_1 = require("./proofs.js");
-const inline_js_1 = require("./inline.js");
-const frontmatter_js_1 = require("./frontmatter.js");
-const generate_schema_js_1 = require("./generate-schema.js");
-const compile_generator_js_1 = require("./compile-generator.js");
+const generate_types_js_1 = require("./core/generate-types.js");
+const validate_js_1 = require("./core/validate.js");
+const cli_flags_js_1 = require("./cli-flags.js");
+const setup_plan_js_1 = require("./setup-plan.js");
+const types_js_1 = require("./core/types.js");
+const test_coverage_js_1 = require("./test-coverage.js");
+const scan_js_1 = require("./scan.js");
+const adapter_registry_js_1 = require("./adapter-registry.js");
+const leaderboard_js_1 = require("./leaderboard.js");
+const compile_js_1 = require("./core/compile.js");
+const dialect_js_1 = require("./adapters/claude-code/dialect.js");
+const proofs_js_1 = require("./core/proofs.js");
+const inline_js_1 = require("./core/inline.js");
+const frontmatter_js_1 = require("./core/frontmatter.js");
+const generate_schema_js_1 = require("./core/generate-schema.js");
+const compile_generator_js_1 = require("./core/compile-generator.js");
 const action_gate_js_1 = require("./action-gate.js");
-const agent_runtime_js_1 = require("./agent-runtime.js");
-const refs_js_1 = require("./refs.js");
-const mcp_js_1 = require("./mcp.js");
-const skill_runtime_js_1 = require("./skill-runtime.js");
-const linters_js_1 = require("./linters.js");
-const harness_test_js_1 = require("./harness-test.js");
-const run_scripts_js_1 = require("./run-scripts.js");
-const integrity_js_1 = require("./integrity.js");
-const coverage_js_1 = require("./coverage.js");
-const orphans_js_1 = require("./orphans.js");
-const doc_refs_js_1 = require("./doc-refs.js");
+const agent_runtime_js_1 = require("./adapters/claude-code/agent-runtime.js");
+const refs_js_1 = require("./core/refs.js");
+const mcp_js_1 = require("./core/mcp.js");
+const skill_runtime_js_1 = require("./adapters/claude-code/skill-runtime.js");
+const linters_js_1 = require("./core/linters.js");
+const harness_test_js_1 = require("./adapters/claude-code/harness-test.js");
+const run_scripts_js_1 = require("./adapters/claude-code/run-scripts.js");
+const integrity_js_1 = require("./core/integrity.js");
+const coverage_js_1 = require("./core/coverage.js");
+const orphans_js_1 = require("./core/orphans.js");
+const doc_refs_js_1 = require("./core/doc-refs.js");
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -133,6 +140,7 @@ function compileClaudeToFile(spec, specPath, config) {
     const { markdown, errors, linterResults, targets } = (0, compile_js_1.compileClaude)(spec, {
         basePath,
         specFile: specPath,
+        dialect: dialect_js_1.claudeCodeDialect,
         maxRules: config.maxRules,
         maxTokens: config.maxTokens,
         maxSectionLines: config.maxSectionLines,
@@ -168,6 +176,9 @@ function compileSkillToFile(spec, specPath) {
     const { markdown, errors } = (0, compile_js_1.compileSkill)(spec, {
         basePath: process.cwd(),
         specFile: specPath,
+        // Pick the SKILL.md frontmatter profile from the detected harness — a Codex
+        // repo gets a minimal (name + description) SKILL.md; CC gets the full set.
+        dialect: (0, adapter_registry_js_1.detectAdapter)(process.cwd()).dialect,
     });
     (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(process.cwd(), outputPath), markdown);
     if (errors.length === 0) {
@@ -184,6 +195,7 @@ function compileAgentToFile(spec, specPath) {
     const { markdown, errors } = (0, compile_js_1.compileAgent)(spec, {
         basePath: process.cwd(),
         specFile: specPath,
+        dialect: (0, adapter_registry_js_1.detectAdapter)(process.cwd()).dialect,
     });
     (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(process.cwd(), outputPath), markdown);
     if (errors.length === 0) {
@@ -541,6 +553,7 @@ function auditExitCode(report) {
         report.frontmatterErrors > 0 ||
         report.integrityErrors > 0 ||
         report.coverageErrors > 0 ||
+        report.untestedErrors > 0 ||
         report.symbolRefErrors > 0 ||
         report.mcpRefErrors > 0)
         return 2;
@@ -817,6 +830,10 @@ async function audit(restArgs, flags, config) {
             console.log(`  ${line}`);
         }
     }
+    // 7b. Untested-surface check — skills/agents/hooks shipping without a test or
+    // eval. Warning by default (a nudge, exit 0); set rules.untested-surface to
+    // "error" to gate CI. See src/test-coverage.ts and docs/rules/untested-surface.md.
+    const untested = checkUntestedSurfaces(config, silent);
     // 8. Validate vigiles builder calls inside markdown code blocks. Default
     // is to validate every ref; illustrative blocks opt out via
     // `<!-- vigiles:ignore -->` (single block) or
@@ -848,6 +865,8 @@ async function audit(restArgs, flags, config) {
         integrityErrors,
         coverageErrors,
         orphanCount: orphanReport.orphans.length,
+        untestedSurfaces: untested.untested,
+        untestedErrors: untested.errors,
         docRefErrors: docRefReport.errors.length,
         symbolRefErrors,
         mcpRefErrors,
@@ -876,6 +895,8 @@ function printAuditSummary(report) {
         parts.push(`${String(report.duplicatePairs)} duplicates`);
     if (report.orphanCount > 0)
         parts.push(`${String(report.orphanCount)} orphan docs`);
+    if (report.untestedSurfaces > 0)
+        parts.push(`${String(report.untestedSurfaces)} untested surfaces`);
     if (report.docRefErrors > 0)
         parts.push(`${String(report.docRefErrors)} broken doc refs`);
     if (report.symbolRefErrors > 0)
@@ -1016,34 +1037,133 @@ export default claude({${targetLine}
 // ---------------------------------------------------------------------------
 // Setup wizard
 // ---------------------------------------------------------------------------
-const VIGILES_CI_STEP = `      - name: Verify specs
-        run: npx vigiles audit && npx vigiles generate-types --check`;
-function addGhaStep() {
-    // Find existing GHA workflow
-    const ciPaths = [
-        ".github/workflows/ci.yml",
-        ".github/workflows/ci.yaml",
-        ".github/workflows/main.yml",
-        ".github/workflows/main.yaml",
-        ".github/workflows/test.yml",
-        ".github/workflows/test.yaml",
-    ];
-    for (const ciPath of ciPaths) {
-        const fullPath = (0, node_path_1.resolve)(process.cwd(), ciPath);
-        if ((0, node_fs_1.existsSync)(fullPath)) {
-            const content = (0, node_fs_1.readFileSync)(fullPath, "utf-8");
-            if (content.includes("vigiles")) {
-                console.log(`✓ ${ciPath} already has vigiles steps`);
-                return true;
-            }
-            // Append step at end of file (safe for all YAML formats)
-            const trimmed = content.trimEnd();
-            (0, node_fs_1.writeFileSync)(fullPath, trimmed + "\n\n" + VIGILES_CI_STEP + "\n");
-            console.log(`✓ Added vigiles check step to ${ciPath}`);
-            return true;
-        }
+/** Full GitHub Actions workflow that wires the production `zernie/vigiles@v1`
+ * Action (Pillar 1) and, when Pillar 2 is set up, a deterministic harness job. */
+function vigilesWorkflow(plan) {
+    const harness = plan.test
+        ? `
+  harness:
+    # Pillar 2 — run your *.harness.{mjs,ts} tests against the real agent CLI and
+    # a scripted mock model (deterministic, no API key). Drop this job if you only
+    # author runHook unit tests, or keep it for the deterministic tier.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+      - run: npm install
+      - run: npm i -g @anthropic-ai/claude-code # mock tier needs the binary, no API key
+      - run: npx vigiles test
+`
+        : "";
+    return `name: vigiles
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+  pull-requests: write # for the sticky PR comment
+
+jobs:
+  verify:
+    # Pillar 1 — verify the references in your instruction files (composite Action
+    # over the published CLI). Posts a sticky PR comment + a \`valid\` output.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+      - uses: zernie/vigiles@v1
+${harness}`;
+}
+/** Create `.github/workflows/vigiles.yml` (or note it already exists). */
+function wireGha(plan) {
+    const dir = (0, node_path_1.resolve)(process.cwd(), ".github", "workflows");
+    const path = (0, node_path_1.resolve)(dir, "vigiles.yml");
+    if ((0, node_fs_1.existsSync)(path)) {
+        console.log("✓ .github/workflows/vigiles.yml already exists");
+        return;
+    }
+    if (!(0, node_fs_1.existsSync)(dir))
+        (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+    (0, node_fs_1.writeFileSync)(path, vigilesWorkflow(plan));
+    console.log("✓ Created .github/workflows/vigiles.yml (uses zernie/vigiles@v1)");
+}
+const STARTER_HARNESS = `/**
+ * Starter harness test (Pillar 2) — scaffolded by \`vigiles init\`.
+ * Proves a hook actually FIRES, deterministically and with no API key.
+ *
+ *   npm i -D vigiles          # the testing API this imports
+ *   npx vigiles test          # or: node vigiles.harness.mjs
+ *
+ * Guide: https://github.com/zernie/vigiles/blob/main/docs/harness-testing.md
+ */
+import { runHook } from "vigiles/testing";
+import assert from "node:assert/strict";
+
+// EXAMPLE — replace with one of YOUR hooks. This PreToolUse Bash guard blocks a
+// destructive command; runHook pipes it a fake event and checks the decision.
+const guard =
+  \`CMD=$(cat | jq -r '.tool_input.command // empty'); \` +
+  \`case "$CMD" in *"rm -rf /"*) echo blocked >&2; exit 2 ;; esac; exit 0\`;
+
+const blocked = runHook(guard, {
+  hook_event_name: "PreToolUse",
+  tool_name: "Bash",
+  tool_input: { command: "rm -rf / --no-preserve-root" },
+});
+assert.ok(blocked.blocked, "guard should block \\\`rm -rf /\\\`");
+
+const allowed = runHook(guard, {
+  hook_event_name: "PreToolUse",
+  tool_name: "Bash",
+  tool_input: { command: "ls -la" },
+});
+assert.ok(!allowed.blocked, "guard should allow a safe command");
+
+console.log("\\u2713 hook blocks rm -rf / and allows safe commands");
+`;
+/** Pillar 2 — scaffold a starter harness test the user adapts to their hooks. */
+function scaffoldPillar2() {
+    const path = (0, node_path_1.resolve)(process.cwd(), "vigiles.harness.mjs");
+    if ((0, node_fs_1.existsSync)(path)) {
+        console.log("✓ vigiles.harness.mjs already exists");
+        return;
+    }
+    (0, node_fs_1.writeFileSync)(path, STARTER_HARNESS);
+    console.log("✓ Scaffolded vigiles.harness.mjs — Pillar 2 starter (npm i -D vigiles && npx vigiles test)");
+}
+/** Interactive prompts (TTY only): which pillars, CI, plugin. */
+async function promptSetup() {
+    const readline = await import("node:readline");
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    const ask = (q, def) => new Promise((res) => {
+        rl.question(q, (a) => {
+            res(a.trim() || def);
+        });
+    });
+    const isYes = (s) => /^y(es)?$/i.test(s);
+    try {
+        const pillars = (await ask("Set up which pillars? [both/verify/test] (both): ", "both")).toLowerCase();
+        const gha = isYes(await ask("Wire CI (GitHub Action)? [Y/n]: ", "y"));
+        const plugin = isYes(await ask("Install the Claude Code plugin (hooks + skills)? [Y/n]: ", "y"));
+        return {
+            verify: pillars !== "test",
+            test: pillars !== "verify",
+            gha,
+            plugin,
+        };
+    }
+    finally {
+        rl.close();
     }
-    return false;
 }
 const KNOWN_INSTRUCTION_FILES = ["CLAUDE.md", "AGENTS.md"];
 const KNOWN_OTHER_CONFIGS = {
@@ -1120,42 +1240,17 @@ function detectProject() {
         hasClaude: (0, node_fs_1.existsSync)((0, node_path_1.resolve)(cwd, ".claude")),
     };
 }
-async function setup(args) {
-    const targetFlag = args.find((a) => a.startsWith("--target="));
-    const strict = args.includes("--strict");
-    const noGha = args.includes("--no-gha");
-    console.log(`vigiles setup${strict ? " (strict mode)" : ""}\n`);
-    // Step 1: Detect project
-    const detected = detectProject();
-    if (detected.agents.length > 0) {
-        console.log(`Detected: ${detected.agents.join(", ")}`);
-    }
-    if (detected.otherConfigs.length > 0) {
-        console.log(`Other agent configs: ${detected.otherConfigs.join(", ")}`);
-    }
-    if (detected.syncTools.length > 0) {
-        console.log(`Sync tools: ${detected.syncTools.join(", ")}`);
-    }
-    for (const f of detected.instructionFiles) {
-        if (f.isSymlink) {
-            console.log(`Note: ${f.path} is a symlink`);
-        }
-    }
-    if (detected.agents.length > 0 ||
-        detected.otherConfigs.length > 0 ||
-        detected.syncTools.length > 0) {
-        console.log("");
-    }
-    // Step 2: Determine targets
+/** Pillar 1 — specs + types + schema + compile. Returns the spec targets
+ * created/found (empty when every existing file needs migration instead). */
+async function setupPillar1(detected, targetValue) {
+    // Determine targets
     let targets;
-    if (targetFlag) {
-        targets = [targetFlag.split("=")[1]];
+    if (targetValue) {
+        targets = [targetValue];
     }
     else {
-        // Auto-detect: create specs for instruction files that need them
         const needsSpec = detected.instructionFiles.filter((f) => !f.hasSpec);
         if (needsSpec.length > 0) {
-            // Existing files without specs — suggest migration
             for (const f of needsSpec) {
                 console.log(`Found ${f.path} without a spec. Migrate with the migrate-to-spec skill`);
                 console.log(`  or create a blank spec: npx vigiles init --target=${f.path}\n`);
@@ -1163,21 +1258,18 @@ async function setup(args) {
             const hasAnySpec = detected.instructionFiles.some((f) => f.hasSpec);
             if (!hasAnySpec &&
                 needsSpec.length === detected.instructionFiles.length) {
-                // ALL existing files need migration — don't create new ones
-                console.log("Install the plugin to use the migration skill:");
-                console.log("  npx skills add zernie/vigiles");
-                return;
+                // ALL existing files need migration — don't create new specs.
+                console.log("Use the migration skill: npx skills add zernie/vigiles\n");
+                return [];
             }
         }
-        // Default: CLAUDE.md, plus AGENTS.md if Codex detected
         targets = ["CLAUDE.md"];
         const hasAgentsMd = detected.instructionFiles.some((f) => f.path === "AGENTS.md");
         const hasCodex = detected.agents.includes("Codex / GitHub Copilot") || hasAgentsMd;
-        if (hasCodex && !hasAgentsMd) {
+        if (hasCodex && !hasAgentsMd)
             targets.push("AGENTS.md");
-        }
     }
-    // Step 3: Create specs
+    // Create specs
     for (const target of targets) {
         const specPath = `${target}.spec.ts`;
         if ((0, node_fs_1.existsSync)((0, node_path_1.resolve)(process.cwd(), specPath))) {
@@ -1190,105 +1282,129 @@ async function setup(args) {
             init(["--target=" + target]);
         }
     }
-    // Step 4: Generate types
+    // Generate types + schema
     console.log("\nScanning linters and project files...");
     const typesResult = (0, generate_types_js_1.generateTypes)({ basePath: process.cwd() });
-    const outPath = ".vigiles/generated.d.ts";
     const outDir = (0, node_path_1.resolve)(process.cwd(), ".vigiles");
-    if (!(0, node_fs_1.existsSync)(outDir)) {
+    if (!(0, node_fs_1.existsSync)(outDir))
         (0, node_fs_1.mkdirSync)(outDir, { recursive: true });
-    }
-    (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(process.cwd(), outPath), typesResult.dts);
+    (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(process.cwd(), ".vigiles/generated.d.ts"), typesResult.dts);
     for (const l of typesResult.linters) {
         console.log(`  ${l.linter}: ${String(l.rules.length)} rules`);
     }
     if (typesResult.scripts.length > 0) {
         console.log(`  npm scripts: ${String(typesResult.scripts.length)}`);
     }
-    console.log(`✓ Generated ${outPath}`);
-    // Also emit a JSON Schema so `vigiles:` markdown frontmatter (Level 1)
-    // gets rule-name autocomplete + typo squiggles from the editor's YAML LSP.
+    console.log("✓ Generated .vigiles/generated.d.ts");
     const schemaResult = (0, generate_schema_js_1.generateSchema)({
         basePath: process.cwd(),
         linters: (0, validate_js_1.loadConfig)().linters,
     });
-    const schemaPath = ".vigiles/schema.json";
-    (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(process.cwd(), schemaPath), schemaResult.json);
-    console.log(`✓ Generated ${schemaPath} (point frontmatter at it with \`# yaml-language-server: $schema=./${schemaPath}\`)`);
-    // Step 5: Compile specs
+    (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(process.cwd(), ".vigiles/schema.json"), schemaResult.json);
+    console.log("✓ Generated .vigiles/schema.json (YAML-LSP frontmatter schema)");
+    // Compile specs
     console.log("\nCompiling specs...");
     const specs = findSpecs();
-    if (specs.length > 0) {
+    if (specs.length > 0)
         await compile(specs, (0, validate_js_1.loadConfig)());
+    return targets;
+}
+/** Install the Claude Code plugin (hooks + skills). Returns whether the
+ * fallback wrote `.claude/settings.json` (for the commit hint). */
+function installPlugin() {
+    try {
+        const { execSync: exec } = require("node:child_process");
+        exec("npx skills add zernie/vigiles", {
+            cwd: process.cwd(),
+            stdio: ["pipe", "pipe", "pipe"],
+            timeout: 30000,
+        });
+        console.log("✓ Installed vigiles plugin (hooks + skills) via skills CLI");
+        return false;
     }
-    // Step 6: Add CI step
-    console.log("");
-    const addedGha = noGha ? false : addGhaStep();
-    if (!addedGha) {
-        console.log("  No CI workflow found. Add this step to your CI:\n");
-        console.log("    npx vigiles audit && npx vigiles generate-types --check");
-    }
-    // Step 7: Install Claude Code plugin (hooks + skills)
-    const shouldInstallPlugin = detected.hasClaude || targets.includes("CLAUDE.md");
-    if (shouldInstallPlugin) {
-        let pluginInstalled = false;
-        // Try installing the full plugin via skills CLI (gives hooks + skills)
+    catch {
+        // skills CLI not available — fall back to direct hook installation.
+    }
+    const settingsDir = (0, node_path_1.resolve)(process.cwd(), ".claude");
+    const settingsPath = (0, node_path_1.resolve)(settingsDir, "settings.json");
+    if (!(0, node_fs_1.existsSync)(settingsDir))
+        (0, node_fs_1.mkdirSync)(settingsDir, { recursive: true });
+    let settings = {};
+    if ((0, node_fs_1.existsSync)(settingsPath)) {
         try {
-            const { execSync: exec } = require("node:child_process");
-            exec("npx skills add zernie/vigiles", {
-                cwd: process.cwd(),
-                stdio: ["pipe", "pipe", "pipe"],
-                timeout: 30000,
-            });
-            pluginInstalled = true;
-            console.log("✓ Installed vigiles plugin (hooks + skills) via skills CLI");
+            settings = JSON.parse((0, node_fs_1.readFileSync)(settingsPath, "utf-8"));
         }
         catch {
-            // skills CLI not available — fall back to direct hook installation
-        }
-        if (!pluginInstalled) {
-            // Fall back: write hooks directly to .claude/settings.json
-            // (gives auto-compile + block edits, but no skills)
-            const settingsDir = (0, node_path_1.resolve)(process.cwd(), ".claude");
-            const settingsPath = (0, node_path_1.resolve)(settingsDir, "settings.json");
-            if (!(0, node_fs_1.existsSync)(settingsDir)) {
-                (0, node_fs_1.mkdirSync)(settingsDir, { recursive: true });
-            }
-            let settings = {};
-            if ((0, node_fs_1.existsSync)(settingsPath)) {
-                try {
-                    settings = JSON.parse((0, node_fs_1.readFileSync)(settingsPath, "utf-8"));
-                }
-                catch {
-                    // Ignore malformed settings
-                }
-            }
-            if (!settings["hooks"]) {
-                settings["hooks"] = {};
-            }
-            const hooks = settings["hooks"];
-            const preCmd = `FILE=$(cat | jq -r '.tool_input.file_path // empty') && case "$FILE" in *.md) [ -f "$FILE" ] && head -1 "$FILE" | grep -q 'vigiles:sha256:' && { SPEC=$(head -1 "$FILE" | sed -n 's/.*compiled from \\(.*\\) -->/\\1/p'); echo "BLOCKED: Edit $SPEC instead." >&2; exit 2; } ;; esac; exit 0`;
-            const postCmd = `FILE=$(cat | jq -r '.tool_input.file_path // empty') && case "$(basename "$FILE")" in eslint.config.*|.eslintrc*|package.json|pyproject.toml|Cargo.toml) npx vigiles generate-types 2>&1 || true ;; esac && case "$FILE" in *.spec.ts) npx vigiles compile 2>&1 || true ;; esac`;
-            // Append to existing arrays (don't duplicate if already present)
-            const existingStr = JSON.stringify(settings);
-            if (!existingStr.includes("vigiles:sha256")) {
-                const pre = (hooks["PreToolUse"] ?? []);
-                pre.push({ matcher: "Edit|Write", command: preCmd });
-                hooks["PreToolUse"] = pre;
-            }
-            if (!existingStr.includes("vigiles compile")) {
-                const post = (hooks["PostToolUse"] ?? []);
-                post.push({ matcher: "Edit|Write", command: postCmd });
-                hooks["PostToolUse"] = post;
-            }
-            (0, node_fs_1.writeFileSync)(settingsPath, JSON.stringify(settings, null, 2) + "\n");
-            console.log("✓ Installed hooks in .claude/settings.json");
-            console.log("  (For skills like edit-spec and migrate-to-spec, also run: npx skills add zernie/vigiles)");
-        }
+            // Ignore malformed settings.
+        }
+    }
+    if (!settings["hooks"])
+        settings["hooks"] = {};
+    const hooks = settings["hooks"];
+    const preCmd = `FILE=$(cat | jq -r '.tool_input.file_path // empty') && case "$FILE" in *.md) [ -f "$FILE" ] && head -1 "$FILE" | grep -q 'vigiles:sha256:' && { SPEC=$(head -1 "$FILE" | sed -n 's/.*compiled from \\(.*\\) -->/\\1/p'); echo "BLOCKED: Edit $SPEC instead." >&2; exit 2; } ;; esac; exit 0`;
+    const postCmd = `FILE=$(cat | jq -r '.tool_input.file_path // empty') && case "$(basename "$FILE")" in eslint.config.*|.eslintrc*|package.json|pyproject.toml|Cargo.toml) npx vigiles generate-types 2>&1 || true ;; esac && case "$FILE" in *.spec.ts) npx vigiles compile 2>&1 || true ;; esac`;
+    const existingStr = JSON.stringify(settings);
+    if (!existingStr.includes("vigiles:sha256")) {
+        const pre = (hooks["PreToolUse"] ?? []);
+        pre.push({ matcher: "Edit|Write", command: preCmd });
+        hooks["PreToolUse"] = pre;
+    }
+    if (!existingStr.includes("vigiles compile")) {
+        const post = (hooks["PostToolUse"] ?? []);
+        post.push({ matcher: "Edit|Write", command: postCmd });
+        hooks["PostToolUse"] = post;
+    }
+    (0, node_fs_1.writeFileSync)(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+    console.log("✓ Installed hooks in .claude/settings.json");
+    console.log("  (For skills like edit-spec and migrate-to-spec, also run: npx skills add zernie/vigiles)");
+    return true;
+}
+async function setup(args) {
+    const parsed = (0, setup_plan_js_1.parseSetupArgs)(args);
+    const strict = parsed.strict;
+    // Plan: defaults → flags → interactive prompts (only a human at a TTY).
+    let plan = (0, setup_plan_js_1.resolvePlan)(parsed);
+    if ((0, setup_plan_js_1.shouldPrompt)(parsed, process.stdin.isTTY ?? false)) {
+        plan = (0, setup_plan_js_1.resolvePlan)(parsed, await promptSetup());
+    }
+    const pillars = [plan.verify && "verify", plan.test && "test"]
+        .filter(Boolean)
+        .join(" + ");
+    console.log(`vigiles setup${strict ? " (strict)" : ""} — pillars: ${pillars}\n`);
+    // Detect project.
+    const detected = detectProject();
+    if (detected.agents.length > 0) {
+        console.log(`Detected: ${detected.agents.join(", ")}`);
     }
-    // Step 8: Agent-specific guidance
-    const specPathsList = targets.map((t) => `${t}.spec.ts`);
-    const specPaths = specPathsList.join(", ");
+    if (detected.otherConfigs.length > 0) {
+        console.log(`Other agent configs: ${detected.otherConfigs.join(", ")}`);
+    }
+    if (detected.syncTools.length > 0) {
+        console.log(`Sync tools: ${detected.syncTools.join(", ")}`);
+    }
+    for (const f of detected.instructionFiles) {
+        if (f.isSymlink)
+            console.log(`Note: ${f.path} is a symlink`);
+    }
+    // Pillar 1 — verify instruction files.
+    let targets = [];
+    if (plan.verify) {
+        console.log("");
+        targets = await setupPillar1(detected, parsed.target);
+    }
+    // Pillar 2 — test the harness.
+    if (plan.test) {
+        console.log("");
+        scaffoldPillar2();
+    }
+    // CI — the production Action (+ a harness job when Pillar 2 is on).
+    if (plan.gha) {
+        console.log("");
+        wireGha(plan);
+    }
+    // Claude Code plugin (hooks + skills).
+    const wroteSettings = plan.plugin ? installPlugin() : false;
+    // Agent-specific guidance.
     if (targets.includes("AGENTS.md")) {
         console.log("\n  Codex / Copilot reads AGENTS.md directly — no hooks needed.");
         console.log("  Run `npx vigiles compile` after spec edits. CI enforces freshness.");
@@ -1297,37 +1413,42 @@ async function setup(args) {
         console.log("\n  Non-markdown agent configs detected. Use a sync tool to convert:");
         console.log("    npm install -D rule-porter");
     }
-    // Step 8b: Write config if strict mode
+    // Strict config.
     if (strict) {
         const configPath = (0, node_path_1.resolve)(process.cwd(), ".vigilesrc.json");
         if (!(0, node_fs_1.existsSync)(configPath)) {
-            (0, node_fs_1.writeFileSync)(configPath, JSON.stringify({
-                rules: {
-                    "require-spec": "error",
-                    "require-skill-spec": "error",
-                },
-            }, null, 2) + "\n");
+            (0, node_fs_1.writeFileSync)(configPath, JSON.stringify({ rules: { "require-spec": "error", "require-skill-spec": "error" } }, null, 2) + "\n");
             console.log("✓ Created .vigilesrc.json with strict rules");
         }
     }
-    // Step 9: Summary
-    console.log("\n---");
-    console.log("Setup complete.\n");
-    console.log(`  1. Edit ${specPaths} — add your project's conventions`);
-    console.log("  2. Run `/strengthen` in Claude Code to upgrade guidance → enforce");
+    // Summary.
+    const specPathsList = targets.map((t) => `${t}.spec.ts`);
+    console.log("\n---\nSetup complete.\n");
+    const nextSteps = [];
+    if (specPathsList.length > 0) {
+        nextSteps.push(`Edit ${specPathsList.join(", ")} — add your conventions, then \`/strengthen\``);
+    }
+    if (plan.test) {
+        nextSteps.push("Edit vigiles.harness.mjs to test a real hook, then `npx vigiles test`");
+    }
     if (!strict) {
-        console.log("  3. When ready, enforce specs in CI: npx vigiles setup --strict");
+        nextSteps.push("When ready, enforce in CI: npx vigiles init --strict");
     }
-    console.log("\n  Commit:");
+    nextSteps.forEach((s, i) => {
+        console.log(`  ${String(i + 1)}. ${s}`);
+    });
     const files = [
         ...targets,
         ...specPathsList,
-        ".vigiles/generated.d.ts",
-        ".vigiles/schema.json",
-        ...(shouldInstallPlugin ? [".claude/settings.json"] : []),
+        ...(plan.verify ? [".vigiles/generated.d.ts", ".vigiles/schema.json"] : []),
+        ...(plan.test ? ["vigiles.harness.mjs"] : []),
+        ...(plan.gha ? [".github/workflows/vigiles.yml"] : []),
+        ...(wroteSettings ? [".claude/settings.json"] : []),
         ...(strict ? [".vigilesrc.json"] : []),
     ];
-    console.log(`    git add ${files.join(" ")} && git commit -m "Add vigiles spec"`);
+    if (files.length > 0) {
+        console.log(`\n  Commit:\n    git add ${files.join(" ")} && git commit -m "Add vigiles"`);
+    }
 }
 // ---------------------------------------------------------------------------
 // Strengthen: guidance() → enforce() suggestions
@@ -1358,6 +1479,32 @@ function checkIntegrityForFiles(files, severity, silent) {
     }
     return severity === "error" ? errorCount : 0;
 }
+/**
+ * Apply the `untested-surface` rule: find skills/agents/hooks with no test or
+ * eval (see src/test-coverage.ts). Returns the raw untested count plus the
+ * severity-gated error count — "warn" prints but never fails CI (errors=0),
+ * "error" fails (exit 2), mirroring the integrity check.
+ */
+function checkUntestedSurfaces(config, silent) {
+    const severity = (0, types_js_1.ruleSeverity)(config?.rules["untested-surface"]);
+    if (!severity)
+        return { untested: 0, errors: 0 };
+    const opts = (0, types_js_1.ruleOptions)(config?.rules["untested-surface"]);
+    const report = (0, test_coverage_js_1.findUntestedSurfaces)({ basePath: process.cwd(), ...opts });
+    if (!silent) {
+        console.log("\nUntested surfaces:\n");
+        for (const line of (0, test_coverage_js_1.formatUntestedReport)(report).split("\n")) {
+            console.log(`  ${line}`);
+        }
+        for (const s of report.untested) {
+            ghAnnotate(severity === "error" ? "error" : "warning", `${s.kind} ${s.path} ships without a test or eval`, s.path);
+        }
+    }
+    return {
+        untested: report.untested.length,
+        errors: severity === "error" ? report.untested.length : 0,
+    };
+}
 /**
  * Apply the configured coverage thresholds. Returns the number of failing
  * thresholds (so the audit can fail CI when severity is "error").
@@ -1534,16 +1681,19 @@ function handleGenerateSchema(args, restArgs) {
  */
 function handleRunScripts(kind, args, restArgs) {
     const cwd = process.cwd();
-    const defaultGlob = kind === "test" ? "**/*.harness.mjs" : "**/*.eval.mjs";
-    if (kind === "test" && !(0, harness_test_js_1.claudeAvailable)()) {
-        console.log("vigiles test: `claude` CLI not found — skipping harness tests.");
-        return;
-    }
+    // Harness/eval scripts may be authored in JS or TS (see run-scripts.ts).
+    const defaultGlob = (0, run_scripts_js_1.scriptGlob)(kind === "test" ? "harness" : "eval");
     const files = (0, run_scripts_js_1.discoverScripts)(restArgs, defaultGlob, cwd);
     if (files.length === 0) {
         console.log(`No ${defaultGlob} files found.`);
         return;
     }
+    // No blanket skip: unit-tier (runHook) tests need no `claude`, so always run.
+    // A script whose tier DOES need `claude` self-reports `⊘ SKIPPED` (exit 77) —
+    // loud, never a silent green. Just flag up front that some may skip.
+    if (kind === "test" && !(0, harness_test_js_1.claudeAvailable)()) {
+        console.log("ℹ `claude` CLI not found — unit-tier tests run; tests that need it report SKIPPED.\n");
+    }
     const trialsFlag = args.find((a) => a.startsWith("--trials="));
     const env = {};
     if (trialsFlag)
@@ -1551,8 +1701,16 @@ function handleRunScripts(kind, args, restArgs) {
     console.log(`Running ${String(files.length)} ${kind} file(s):\n`);
     const results = (0, run_scripts_js_1.runScripts)(files, cwd, env);
     console.log("\n" + (0, run_scripts_js_1.formatScriptSummary)(results));
-    if (results.some((r) => r.code !== 0))
+    if ((0, run_scripts_js_1.anyFailed)(results))
+        process.exit(1);
+    // `--no-skip`: in a context that ASSERTS the capability is present (a CI job),
+    // a skipped tier is untested surface — fail loudly instead of passing green.
+    if (args.includes("--no-skip") && results.some((r) => r.status === "skip")) {
+        const n = results.filter((r) => r.status === "skip").length;
+        console.log(`\n✗ --no-skip: ${String(n)} tier(s) SKIPPED — untested surface here. ` +
+            "Install the missing capability (e.g. the `claude` CLI) or scope the run.");
         process.exit(1);
+    }
 }
 function printUsage(command) {
     console.log("vigiles — compile typed specs to instruction files");
@@ -1785,17 +1943,10 @@ function isInstructionFile(file) {
  * was found. `basePath` is the file's own directory (where paths resolve).
  */
 function reportRefIssues(markdown, basePath, log) {
-    const broken = (0, refs_js_1.verifySymbolRefs)(markdown, basePath);
-    const unmarked = (0, refs_js_1.unmarkedCodeRefs)(markdown);
-    for (const b of broken) {
-        log(`  ✗ line ${String(b.line)}: ${b.reason}`);
-    }
-    for (const u of unmarked) {
-        const callee = u.text.replace(/\s*\([^)]*\)\s*$/, "");
-        log(`  ✗ line ${String(u.line)}: \`${u.text}\` is an unmarked code reference — ` +
-            `mark it as \`vigiles:symbol path/to/file.ext#${callee}\` or add <!-- vigiles:ignore --> if it is prose`);
-    }
-    return broken.length > 0 || unmarked.length > 0;
+    const issues = (0, refs_js_1.collectRefIssues)(markdown, basePath);
+    for (const m of issues)
+        log(`  ✗ ${m}`);
+    return issues.length > 0;
 }
 /** `vigiles refs <file>` — check a file's symbol references (exit 2 on issues). */
 function refsCommand(target) {
@@ -1845,6 +1996,9 @@ function refsHookCommand() {
     }
     if (!file || !isInstructionFile(file))
         return;
+    const severity = (0, types_js_1.ruleSeverity)((0, validate_js_1.loadConfig)().rules["unmarked-refs"]);
+    if (severity === false)
+        return;
     const cwd = process.cwd();
     const target = (0, node_path_1.relative)(cwd, (0, node_path_1.resolve)(cwd, file)) || file;
     let markdown;
@@ -1854,22 +2008,39 @@ function refsHookCommand() {
     catch {
         return;
     }
-    const lines = [];
-    const bad = reportRefIssues(markdown, (0, node_path_1.dirname)((0, node_path_1.resolve)(cwd, file)), (m) => {
-        lines.push(m);
-    });
-    if (bad) {
+    const issues = (0, refs_js_1.collectRefIssues)(markdown, (0, node_path_1.dirname)((0, node_path_1.resolve)(cwd, file)));
+    const action = (0, refs_js_1.refsHookAction)(issues.length, severity);
+    if (action === "ok")
+        return;
+    if (action === "block") {
+        // Opt-in (`unmarked-refs: "error"`): exit 2 feeds stderr to the model.
         console.error(`vigiles: fix the code references in ${target}:`);
-        for (const l of lines)
-            console.error(l);
+        for (const m of issues)
+            console.error(`  ✗ ${m}`);
         process.exit(2);
     }
+    // Default ("warn"): a non-blocking nudge injected into the agent's context.
+    const context = `vigiles: ${target} has reference(s) that won't be verified unless they ` +
+        `are vigiles marks:\n` +
+        issues.map((m) => `  - ${m}`).join("\n") +
+        `\nExpress references as marks (\`enforce()\` / \`file()\` / \`cmd()\` / a ` +
+        `\`vigiles:symbol\` span / an inline \`<!-- vigiles:enforce -->\` comment) so ` +
+        `\`vigiles audit\` can check them — or add \`<!-- vigiles:ignore -->\` if it ` +
+        `is prose, not a reference.`;
+    process.stdout.write(JSON.stringify({
+        hookSpecificOutput: {
+            hookEventName: "PostToolUse",
+            additionalContext: context,
+        },
+    }) + "\n");
 }
 async function main() {
     const args = process.argv.slice(2);
     const command = args[0];
     const restArgs = args.slice(1).filter((a) => !a.startsWith("--"));
-    const config = (0, validate_js_1.loadConfig)();
+    // Shared flags (--max-rules, --catalog-only) override the loaded config so
+    // every GitHub Action input maps to a real CLI flag. See src/cli-flags.ts.
+    const config = (0, cli_flags_js_1.applyConfigFlags)((0, validate_js_1.loadConfig)(), args);
     switch (command) {
         // --- Primary commands ---
         case "init": {
@@ -1921,6 +2092,35 @@ async function main() {
         case "eval":
             handleRunScripts("eval", args, restArgs);
             break;
+        case "scan": {
+            const dirs = restArgs.length > 0 ? restArgs : ["."];
+            const json = args.includes("--json");
+            if (dirs.length > 1) {
+                // Multiple targets → rank them (the leaderboard engine).
+                const scores = (0, leaderboard_js_1.rankPlugins)(dirs);
+                console.log(json ? JSON.stringify(scores, null, 2) : (0, leaderboard_js_1.formatLeaderboard)(scores));
+            }
+            else {
+                const root = (0, node_path_1.resolve)(dirs[0]);
+                const harnessFlag = args
+                    .find((a) => a.startsWith("--harness="))
+                    ?.slice("--harness=".length);
+                const det = (0, adapter_registry_js_1.detectAdapterResult)(root);
+                const adapter = harnessFlag
+                    ? (0, adapter_registry_js_1.resolveAdapter)(root, harnessFlag)
+                    : det.adapter;
+                const report = (0, scan_js_1.scanPlugin)(dirs[0], adapter.layout);
+                if (!json) {
+                    console.log(`Detected harness: ${adapter.name}`);
+                    if (!harnessFlag && det.ambiguousWith.length > 0) {
+                        console.log(`⚠ repo also matches: ${det.ambiguousWith.join(", ")} — override with --harness=<name>`);
+                    }
+                    console.log("");
+                }
+                console.log(json ? JSON.stringify(report, null, 2) : (0, scan_js_1.formatScanReport)(report));
+            }
+            break;
+        }
         // --- Plumbing ---
         case "generate-types":
             handleGenerateTypes(args, restArgs);