vigiles 2.6.0 → 4.0.0

package/dist/cli.js

@@ -6,34 +6,42 @@
  * Commands:
  *   vigiles init            — scaffold a spec from scratch
  *   vigiles compile         — compile .spec.ts → .md with linter verification
- *   vigiles audit           — verify hashes, report coverage, detect duplicates
+ *   vigiles lint            — verify hashes, report coverage, detect duplicates
  *   vigiles generate-types  — emit .d.ts with types from project state
  */
 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 compose_js_1 = require("./core/compose.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
 // ---------------------------------------------------------------------------
@@ -44,7 +52,11 @@ const IGNORE_NODE_MODULES = ["node_modules/**"];
 function findSpecs(pattern) {
     const glob = pattern ?? "**/*.md.spec.ts";
     return (0, glob_1.globSync)(glob, {
-        ignore: [...IGNORE_NODE_MODULES, "dist/**"],
+        // `dot: true` so specs that live in a sync tool's source slot (e.g.
+        // `.ruler/AGENTS.md.spec.ts`, the redirect target) are discovered by
+        // compile/audit/the recompile hook — not just root-level specs.
+        dot: true,
+        ignore: [...IGNORE_NODE_MODULES, "dist/**", ".git/**"],
         cwd: process.cwd(),
     });
 }
@@ -133,6 +145,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 +181,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 +200,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) {
@@ -388,7 +405,7 @@ async function findDuplicateRules(threshold = 0.3, silent = false, scopeFiles) {
     const allSpecs = findSpecs();
     // If audit was invoked with explicit file arguments, only scan the specs
     // for those files — otherwise an unrelated duplicate elsewhere in the
-    // repo would fail a targeted CI check (e.g. `vigiles audit path/foo.md`).
+    // repo would fail a targeted CI check (e.g. `vigiles lint path/foo.md`).
     //
     // Resolve each requested file to its real source spec by reading the
     // compiled-from header. Multi-target projects compile one spec to
@@ -541,6 +558,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 +835,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 +870,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 +900,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)
@@ -968,6 +994,34 @@ function discover(silent = false) {
     }
     return { enabled: totalEnabled, documented: totalDocumented };
 }
+/** This package's own version (from the installed package.json). */
+function getVersion() {
+    try {
+        // dist/cli.js → ../package.json (the package root).
+        const pkg = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.resolve)(__dirname, "..", "package.json"), "utf-8"));
+        return pkg.version ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+/** The dependency range to pin `vigiles` to (the running CLI's major, e.g.
+ * `^3`). Falls back to `latest` for the unreleased dev placeholder version. */
+function vigilesDepSpec() {
+    const major = parseInt(getVersion(), 10);
+    return Number.isFinite(major) && major > 0 ? `^${String(major)}` : "latest";
+}
+/** True when the file's first line carries a vigiles integrity hash (i.e. it
+ * is a compiled artifact we own, safe to overwrite — not hand-written prose). */
+function targetHasHash(absPath) {
+    try {
+        const first = (0, node_fs_1.readFileSync)(absPath, "utf-8").split("\n", 1)[0];
+        return first.includes("vigiles:sha256");
+    }
+    catch {
+        return false;
+    }
+}
 function init(args) {
     const targetFlag = args.find((a) => a.startsWith("--target="));
     const target = targetFlag ? targetFlag.split("=")[1] : "CLAUDE.md";
@@ -976,7 +1030,12 @@ function init(args) {
         console.log(`${specPath} already exists.`);
         return;
     }
-    const targetLine = target !== "CLAUDE.md" ? `\n  target: "${target}",` : "";
+    // The compiled output is derived from the spec FILE path; the spec's `target`
+    // field is the h1 + the name the compiler validates against, so it must be the
+    // bare filename even when the spec lives in a subdir (e.g. a sync tool's
+    // `.ruler/AGENTS.md.spec.ts` source slot → target "AGENTS.md").
+    const targetName = (0, node_path_1.basename)(target);
+    const targetLine = targetName !== "CLAUDE.md" ? `\n  target: "${targetName}",` : "";
     const template = `import { claude, enforce, guidance } from "vigiles/spec";
 
 export default claude({${targetLine}
@@ -1010,40 +1069,172 @@ export default claude({${targetLine}
   },
 });
 `;
-    (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(process.cwd(), specPath), template);
+    const specAbs = (0, node_path_1.resolve)(process.cwd(), specPath);
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(specAbs), { recursive: true });
+    (0, node_fs_1.writeFileSync)(specAbs, template);
     console.log(`Created ${specPath} — edit it and run \`vigiles compile\`.`);
 }
 // ---------------------------------------------------------------------------
 // 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 (lint pillar) and, when the test pillar is set up, a deterministic
+ * harness job. */
+function vigilesWorkflow(plan) {
+    const harness = plan.test
+        ? `
+  harness:
+    # Test pillar — 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:
+  lint:
+    # Lint pillar — 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}`;
+}
+/**
+ * Detect a workflow that drives vigiles through an OLD API — a bare `npx vigiles`
+ * (a no-op help screen in v2+) rather than the `zernie/vigiles@` Action or a real
+ * subcommand (`audit`/`test`/…). Upgrading users whose workflow predates the
+ * subcommand split silently lose CI validation, so we flag it loudly.
+ */
+function workflowUsesStaleApi(content) {
+    if (content.includes("zernie/vigiles@"))
+        return false; // uses the Action — fine
+    if (!/\bvigiles\b/.test(content))
+        return false; // not a vigiles workflow
+    const hasModernCmd = /vigiles\s+(lint|test|eval|compile|scan|generate-types|generate-schema|init)\b/.test(content);
+    return !hasModernCmd;
+}
+/** Create `.github/workflows/vigiles.yml`. Returns the files it wrote (for the
+ * commit hint). An existing workflow is never clobbered, but a STALE one (old
+ * bare-`npx vigiles` API) is reported loudly instead of silently skipped. */
+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)) {
+        const content = (0, node_fs_1.readFileSync)(path, "utf-8");
+        if (workflowUsesStaleApi(content)) {
+            console.log("⚠ .github/workflows/vigiles.yml is STALE — it runs a bare `npx vigiles`,\n" +
+                "  which is a no-op help screen now. Replace its run step with the Action +\n" +
+                "  the test job (CI is otherwise silently not validating anything):\n" +
+                "    - uses: zernie/vigiles@v1   # lint pillar — verify references\n" +
+                "    - run: npx vigiles test     # pillar 2 — harness tests\n" +
+                "  Or delete the file and re-run `vigiles init` to regenerate it.");
+        }
+        else {
+            console.log("✓ .github/workflows/vigiles.yml already exists (up to date)");
         }
+        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)");
+    return [".github/workflows/vigiles.yml"];
+}
+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.
+ * Returns the files it wrote (for the commit hint). */
+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 (npx vigiles test)");
+    return ["vigiles.harness.mjs"];
+}
+/** 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/lint/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 {
+            lint: pillars !== "test",
+            test: pillars !== "lint" && pillars !== "verify",
+            gha,
+            plugin,
+        };
+    }
+    finally {
+        rl.close();
     }
-    return false;
 }
 const KNOWN_INSTRUCTION_FILES = ["CLAUDE.md", "AGENTS.md"];
 const KNOWN_OTHER_CONFIGS = {
@@ -1120,175 +1311,344 @@ 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(", ")}`);
-    }
+/** The instruction-file targets Pillar 1 will create specs for — the harness's
+ * native instruction file (CLAUDE.md for Claude Code, AGENTS.md for Codex),
+ * plus any existing instruction file that lacks a spec. */
+function determineTargets(detected, targetValue, harnesses) {
+    if (targetValue)
+        return [targetValue];
+    const targets = [];
+    if (harnesses.includes("claude"))
+        targets.push("CLAUDE.md");
+    if (harnesses.includes("codex"))
+        targets.push("AGENTS.md");
+    if (targets.length === 0)
+        targets.push("CLAUDE.md");
+    // Any existing instruction file without a spec also gets one.
     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
-    let targets;
-    if (targetFlag) {
-        targets = [targetFlag.split("=")[1]];
+        if (!f.hasSpec && !targets.includes(f.path))
+            targets.push(f.path);
     }
-    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`);
-            }
-            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;
-            }
-        }
-        // 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) {
-            targets.push("AGENTS.md");
-        }
-    }
-    // Step 3: Create specs
+    return targets;
+}
+/**
+ * When CLAUDE.md and AGENTS.md are ONE artifact — a symlink, or kept
+ * byte-identical by rulesync/Ruler — collapse them to a single canonical spec
+ * target. Two specs would fight over one file and collide on the integrity hash
+ * (see the "Compose With Sync Tools" rule). The mirror is distributed from the
+ * canonical, not compiled separately.
+ */
+function collapseMirroredTargets(targets, mirror) {
+    if (!mirror)
+        return targets;
+    // The compile source slot: the real file for a symlink, else CLAUDE.md (the
+    // one Claude Code reads natively; the sync tool fans out to AGENTS.md).
+    const canonical = mirror.kind === "symlink"
+        ? (mirror.realTarget ?? "CLAUDE.md")
+        : "CLAUDE.md";
+    const mirrored = mirror.files.find((f) => f !== canonical);
+    if (!mirrored)
+        return targets;
+    if (!targets.includes(canonical) && !targets.includes(mirrored)) {
+        return targets; // neither file is a target — nothing to collapse
+    }
+    const collapsed = targets.filter((t) => t !== mirrored);
+    if (!collapsed.includes(canonical))
+        collapsed.push(canonical);
+    console.log(`Note: CLAUDE.md and AGENTS.md are one artifact (${mirror.kind}). ` +
+        `Scaffolding a single spec for ${canonical}; ${mirrored} is its mirror ` +
+        `(don't add a second spec — it would collide on the integrity hash).`);
+    return collapsed;
+}
+/**
+ * When a detected rule-sync tool (rulesync / Ruler) regenerates a file vigiles
+ * would compile to, REDIRECT the compile target to the tool's source slot
+ * (`.ruler/AGENTS.md`, `.rulesync/rules/vigiles.md`). vigiles compiles upstream;
+ * the tool distributes to CLAUDE.md/AGENTS.md/Cursor/… — so the integrity hash
+ * never collides with the tool's output (the "Compose With Sync Tools" rule).
+ */
+function redirectSyncToolTargets(cwd, targets) {
+    const collisions = (0, compose_js_1.composeCollisions)(cwd, targets);
+    if (collisions.length === 0)
+        return targets;
+    const slotFor = new Map(collisions.map((c) => [c.target, c.redirectTo]));
+    const out = [];
+    for (const t of targets) {
+        const redirected = slotFor.get(t) ?? t;
+        if (!out.includes(redirected))
+            out.push(redirected);
+    }
+    const tool = collisions[0].tool;
+    const slots = [...new Set(collisions.map((c) => c.redirectTo))].join(", ");
+    const from = [...slotFor.keys()].join(", ");
+    console.log(`Note: ${tool} detected — scaffolding the spec to compile into its source ` +
+        `slot (${slots}) instead of ${from}, so ${tool} distributes it without ` +
+        `staling the integrity hash.`);
+    return out;
+}
+/** Pillar 1 — specs + types + schema + compile. Scaffolds a spec for every
+ * instruction file (so `--lint` always delivers a spec), but never compiles
+ * OVER a hand-written file — that is left to the migrate-to-spec skill. */
+async function setupPillar1(detected, targetValue, harnesses) {
+    const cwd = process.cwd();
+    const written = [];
+    const needsMigration = [];
+    // An explicit --target is honoured as-is; otherwise collapse a CLAUDE.md⇄
+    // AGENTS.md mirror (symlink or synced) to one canonical spec, then redirect
+    // into a sync tool's source slot when one would own the output.
+    const targets = targetValue
+        ? determineTargets(detected, targetValue, harnesses)
+        : redirectSyncToolTargets(cwd, collapseMirroredTargets(determineTargets(detected, targetValue, harnesses), (0, compose_js_1.detectInstructionMirror)(cwd)));
+    // Create specs (blank). An existing hand-written target keeps its content —
+    // we scaffold the spec but flag it for migration rather than clobbering it.
     for (const target of targets) {
         const specPath = `${target}.spec.ts`;
-        if ((0, node_fs_1.existsSync)((0, node_path_1.resolve)(process.cwd(), specPath))) {
+        const targetExists = (0, node_fs_1.existsSync)((0, node_path_1.resolve)(cwd, target));
+        if ((0, node_fs_1.existsSync)((0, node_path_1.resolve)(cwd, specPath))) {
             console.log(`✓ ${specPath} already exists`);
         }
-        else if ((0, node_fs_1.existsSync)((0, node_path_1.resolve)(process.cwd(), target))) {
-            console.log(`⚠ ${target} exists without spec — migrate with migrate-to-spec skill`);
-        }
         else {
-            init(["--target=" + target]);
+            init(["--target=" + target]); // prints "Created …"
+            written.push(specPath);
+        }
+        if (targetExists && !targetHasHash((0, node_path_1.resolve)(cwd, target))) {
+            needsMigration.push(target);
+            console.log(`  ${target} already has content — port it into the spec with the migrate-to-spec skill, then \`vigiles compile\`.`);
         }
     }
-    // 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)) {
+    const typesResult = (0, generate_types_js_1.generateTypes)({ basePath: cwd });
+    const outDir = (0, node_path_1.resolve)(cwd, ".vigiles");
+    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)(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");
+    written.push(".vigiles/generated.d.ts");
     const schemaResult = (0, generate_schema_js_1.generateSchema)({
-        basePath: process.cwd(),
+        basePath: 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)(cwd, ".vigiles/schema.json"), schemaResult.json);
+    console.log("✓ Generated .vigiles/schema.json (YAML-LSP frontmatter schema)");
+    written.push(".vigiles/schema.json");
+    // Compile — but only specs whose target is greenfield or already ours. A
+    // freshly-scaffolded blank spec over an existing hand-written file is skipped
+    // so we never overwrite the user's instructions with an empty compile.
     console.log("\nCompiling specs...");
-    const specs = findSpecs();
-    if (specs.length > 0) {
+    const specs = findSpecs().filter((s) => {
+        const tf = (0, node_path_1.resolve)(cwd, s.replace(/\.spec\.ts$/, ""));
+        return !(0, node_fs_1.existsSync)(tf) || targetHasHash(tf);
+    });
+    if (specs.length > 0)
         await compile(specs, (0, validate_js_1.loadConfig)());
+    return { specTargets: targets, written, needsMigration };
+}
+/** Whether a harness binary (`claude`, `codex`) is on PATH. */
+function harnessBinaryPresent(bin) {
+    try {
+        const { execSync: exec } = require("node:child_process");
+        exec(`${bin} --version`, { stdio: "ignore", timeout: 10000 });
+        return true;
     }
-    // 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)
-        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");
-        }
-        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
+    catch {
+        return false;
+    }
+}
+/**
+ * Install vigiles's skills/hooks for the chosen harness(es) via the per-harness
+ * `planPluginInstall` decision — Claude Code through the GLOBAL plugin
+ * marketplace (nothing vendored into the repo), Codex via AGENTS.md-direct (no
+ * global store). The decision is pure and unit-tested; this is the thin IO.
+ */
+function installPlugins(harnesses) {
+    const { execSync: exec } = require("node:child_process");
+    const plans = (0, setup_plan_js_1.planPluginInstall)(harnesses, {
+        hasClaude: harnesses.includes("claude") && harnessBinaryPresent("claude"),
+    });
+    for (const plan of plans) {
+        console.log("");
+        let installed = false;
+        if (plan.commands.length > 0) {
+            try {
+                for (const cmd of plan.commands) {
+                    exec(cmd, { stdio: ["ignore", "pipe", "pipe"], timeout: 120000 });
                 }
+                console.log(plan.successMessage);
+                installed = true;
             }
-            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;
+            catch {
+                // Fall through to the manual instructions below.
             }
-            (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)");
         }
+        if (!installed) {
+            console.log(`Install vigiles for ${plan.harness}:`);
+            for (const step of plan.manualSteps)
+                console.log(`    ${step}`);
+        }
+        for (const note of plan.notes)
+            console.log(`  ${note}`);
     }
-    // Step 8: Agent-specific guidance
+}
+/** Add/upgrade `vigiles` in the project's `devDependencies` (and move it out of
+ * `dependencies` if it's there). Returns the files it wrote (for the commit
+ * hint). No-op in the vigiles repo itself and when there is no package.json. */
+function ensureVigilesDevDep() {
+    const pkgPath = (0, node_path_1.resolve)(process.cwd(), "package.json");
+    if (!(0, node_fs_1.existsSync)(pkgPath))
+        return [];
+    let pkg;
+    try {
+        pkg = JSON.parse((0, node_fs_1.readFileSync)(pkgPath, "utf-8"));
+    }
+    catch {
+        return [];
+    }
+    if (pkg.name === "vigiles")
+        return []; // don't self-depend in this repo
+    const spec = vigilesDepSpec();
+    let changed = false;
+    // Move a stale/misplaced runtime dependency (e.g. a `github:zernie/vigiles`
+    // git pin, or vigiles sitting in `dependencies`) into devDependencies.
+    if (pkg.dependencies && "vigiles" in pkg.dependencies) {
+        delete pkg.dependencies.vigiles;
+        changed = true;
+    }
+    const dev = (pkg.devDependencies ??= {});
+    if (dev.vigiles !== spec) {
+        dev.vigiles = spec;
+        changed = true;
+    }
+    if (!changed)
+        return [];
+    (0, node_fs_1.writeFileSync)(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+    console.log(`✓ Set vigiles@${spec} in devDependencies — run \`npm install\` to fetch it`);
+    return ["package.json"];
+}
+/** Which harnesses to set up: an explicit `--harness=` list, else auto-detected
+ * from the repo (Claude Code / Codex), defaulting to Claude Code. */
+function resolveHarnesses(parsed, detected) {
+    if (parsed.harness) {
+        return parsed.harness
+            .split(",")
+            .map((s) => s.trim().toLowerCase())
+            .filter(Boolean);
+    }
+    const set = new Set();
+    if (detected.hasClaude ||
+        detected.agents.includes("Claude Code") ||
+        detected.instructionFiles.some((f) => f.path === "CLAUDE.md")) {
+        set.add("claude");
+    }
+    if (detected.agents.includes("Codex / GitHub Copilot") ||
+        detected.instructionFiles.some((f) => f.path === "AGENTS.md")) {
+        set.add("codex");
+    }
+    if (set.size === 0)
+        set.add("claude");
+    return [...set];
+}
+/** Print the project-detection summary line(s). */
+function printDetection(detected, harnesses) {
+    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`);
+    }
+    console.log(`Harness: ${harnesses.join(", ")}`);
+}
+/** Print the closing next-steps list + an honest commit hint (only files
+ * actually written this run). */
+function printSetupSummary(opts) {
+    const { plan, strict, targets, needsMigration, written } = opts;
     const specPathsList = targets.map((t) => `${t}.spec.ts`);
-    const specPaths = specPathsList.join(", ");
+    console.log("\n---\nSetup complete.\n");
+    const nextSteps = [];
+    if (needsMigration.length > 0) {
+        nextSteps.push(`Port ${needsMigration.join(", ")} into its spec with the migrate-to-spec skill, then \`npx vigiles compile\``);
+    }
+    else 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 (written.includes("package.json")) {
+        nextSteps.push("Run `npm install` to fetch the vigiles dev dependency");
+    }
+    if (!strict) {
+        nextSteps.push("When ready, enforce in CI: npx vigiles init --strict");
+    }
+    nextSteps.forEach((s, i) => {
+        console.log(`  ${String(i + 1)}. ${s}`);
+    });
+    // Only list files actually written this run (deduped, in a stable order).
+    const files = [...new Set(written)];
+    if (files.length > 0) {
+        console.log(`\n  Commit:\n    git add ${files.join(" ")} && git commit -m "Add vigiles"`);
+    }
+}
+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.lint && "lint", plan.test && "test"]
+        .filter(Boolean)
+        .join(" + ");
+    console.log(`vigiles setup${strict ? " (strict)" : ""} — pillars: ${pillars}\n`);
+    // Detect project.
+    const detected = detectProject();
+    const harnesses = resolveHarnesses(parsed, detected);
+    printDetection(detected, harnesses);
+    // Files actually written, accumulated for an honest commit hint.
+    const written = [];
+    // Lint pillar — verify instruction-file references.
+    let targets = [];
+    let needsMigration = [];
+    if (plan.lint) {
+        console.log("");
+        const p1 = await setupPillar1(detected, parsed.target, harnesses);
+        targets = p1.specTargets;
+        needsMigration = p1.needsMigration;
+        written.push(...p1.written);
+    }
+    // Test pillar — test the harness.
+    if (plan.test) {
+        console.log("");
+        written.push(...scaffoldPillar2());
+    }
+    // Add/upgrade the vigiles dev dependency (both pillars import from it).
+    if (plan.lint || plan.test) {
+        written.push(...ensureVigilesDevDep());
+    }
+    // CI — the production Action (+ a harness job when Pillar 2 is on).
+    if (plan.gha) {
+        console.log("");
+        written.push(...wireGha(plan));
+    }
+    // Plugin/skill install — per-harness (Claude marketplace / Codex direct).
+    if (plan.plugin) {
+        installPlugins(harnesses);
+    }
+    // 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 +1657,16 @@ 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");
+            written.push(".vigilesrc.json");
         }
     }
-    // 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");
-    if (!strict) {
-        console.log("  3. When ready, enforce specs in CI: npx vigiles setup --strict");
-    }
-    console.log("\n  Commit:");
-    const files = [
-        ...targets,
-        ...specPathsList,
-        ".vigiles/generated.d.ts",
-        ".vigiles/schema.json",
-        ...(shouldInstallPlugin ? [".claude/settings.json"] : []),
-        ...(strict ? [".vigilesrc.json"] : []),
-    ];
-    console.log(`    git add ${files.join(" ")} && git commit -m "Add vigiles spec"`);
+    printSetupSummary({ plan, strict, targets, needsMigration, written });
 }
 // ---------------------------------------------------------------------------
 // Strengthen: guidance() → enforce() suggestions
@@ -1358,6 +1697,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 +1899,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,16 +1919,24 @@ 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");
     console.log("");
     console.log("Commands:");
-    console.log("  vigiles init [flags]           Setup project (--target=X.md, --strict, --no-gha)");
+    console.log("  vigiles init [flags]           Setup project (--lint, --test, --harness=, --strict, --no-gha)");
     console.log("  vigiles compile [files...]     Compile .spec.ts → .md");
-    console.log("  vigiles audit [files...]       Verify, find gaps, suggest improvements");
+    console.log("  vigiles lint [files...]        Verify references, find gaps in instruction files");
     console.log("  vigiles test [files...]        Run *.harness.mjs deterministic harness tests");
     console.log("  vigiles eval [files...]        Run *.eval.mjs real-model harness evals (--trials=N)");
     console.log("");
@@ -1574,6 +1950,7 @@ function printUsage(command) {
     console.log("  vigiles generate-types --check  Verify .d.ts is up to date");
     console.log("  vigiles generate-schema [out] Emit JSON Schema for vigiles: frontmatter");
     console.log("  vigiles generate-schema --check Verify schema.json is up to date");
+    console.log("  vigiles --version             Print the version number");
     if (command && command !== "--help") {
         console.log(`\nUnknown command: "${command}"`);
         process.exit(1);
@@ -1785,17 +2162,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 +2215,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 +2227,45 @@ 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];
+    // `--version` / `-v` / `version` prints the version number, not the help
+    // banner — so `npx vigiles --version` reports e.g. `3.0.0`.
+    if (command === "--version" || command === "-v" || command === "version") {
+        console.log(getVersion());
+        return;
+    }
     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": {
@@ -1904,8 +2300,8 @@ async function main() {
             }
             break;
         }
-        case "audit": {
-            // audit = verify + discover + guidance count
+        case "lint": {
+            // lint = verify references + discover + guidance count
             const flags = args.slice(1).filter((a) => a.startsWith("--"));
             const report = await audit(restArgs, flags, config);
             annotateAuditForGitHub(report, flags);
@@ -1921,6 +2317,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);