vigiles 6.0.0 → 8.0.0

package/dist/cli.js

@@ -7,7 +7,7 @@
  *   vigiles init            — scaffold a spec from scratch
  *   vigiles compile         — compile .spec.ts → .md with linter verification
  *   vigiles lint            — verify hashes, report coverage, detect duplicates
- *   vigiles generate-types  — emit .d.ts with types from project state
+ *   vigiles generate types  — emit .d.ts with types from project state
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 const node_fs_1 = require("node:fs");
@@ -15,6 +15,7 @@ const node_path_1 = require("node:path");
 const glob_1 = require("glob");
 const generate_types_js_1 = require("./core/generate-types.js");
 const generate_harness_js_1 = require("./core/generate-harness.js");
+const capability_diff_js_1 = require("./core/capability-diff.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");
@@ -23,6 +24,8 @@ const test_coverage_js_1 = require("./test-coverage.js");
 const scaffold_test_js_1 = require("./scaffold-test.js");
 const effects_js_1 = require("./core/effects.js");
 const scan_js_1 = require("./scan.js");
+const scan_trigger_suggest_js_1 = require("./scan-trigger-suggest.js");
+const dialect_drift_js_1 = require("./dialect-drift.js");
 const score_explainer_js_1 = require("./score-explainer.js");
 const scan_behavioral_js_1 = require("./scan-behavioral.js");
 const adapter_registry_js_1 = require("./adapter-registry.js");
@@ -37,6 +40,11 @@ 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 guards_js_1 = require("./core/guards.js");
+const hook_program_js_1 = require("./core/hook-program.js");
+const hook_install_js_1 = require("./hook-install.js");
+const hook_providers_js_1 = require("./core/hook-providers.js");
+const toml_1 = require("@iarna/toml");
 const agent_runtime_js_1 = require("./adapters/claude-code/agent-runtime.js");
 const effect_region_js_1 = require("./adapters/claude-code/effect-region.js");
 const tool_intercept_js_1 = require("./tool-intercept.js");
@@ -47,6 +55,7 @@ const linters_js_1 = require("./core/linters.js");
 const harness_test_js_1 = require("./harness-test.js");
 const run_scripts_js_1 = require("./adapters/claude-code/run-scripts.js");
 const integrity_js_1 = require("./core/integrity.js");
+const adopt_js_1 = require("./core/adopt.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");
@@ -440,7 +449,7 @@ function validateSpecs(filePaths, rulesConfig, silent = false) {
             // Verify the referenced spec still exists
             const specRef = (0, node_path_1.resolve)(process.cwd(), hashMatch[1]);
             if (!(0, node_fs_1.existsSync)(specRef)) {
-                log(`  ✗ [require-spec] ${filePath} references "${hashMatch[1]}" but that spec no longer exists.`);
+                log(`  ✗ [require-instructions-spec] ${filePath} references "${hashMatch[1]}" but that spec no longer exists.`);
                 allValid = false;
             }
             continue;
@@ -469,7 +478,7 @@ function check(filePaths, silent = false) {
         // `validateSpecs` only returns a boolean today, so we collapse
         // failures to 1 until it starts reporting counts. Kept in its own
         // counter so lint's "stale hash — run vigiles compile" remediation
-        // doesn't misreport a require-spec / other validation failure.
+        // doesn't misreport a require-instructions-spec / other validation failure.
         validationErrors: specsValid ? 0 : 1,
     };
 }
@@ -651,6 +660,7 @@ function lintExitCode(report) {
         report.descriptionOverlapErrors > 0 ||
         report.frontmatterValidErrors > 0 ||
         report.mcpHookErrors > 0 ||
+        report.preferCompiledHookErrors > 0 ||
         report.symbolRefErrors > 0 ||
         report.mcpRefErrors > 0)
         return 2;
@@ -871,7 +881,7 @@ async function runLint(restArgs, flags, config) {
     const summary = flags.includes("--summary");
     const json = flags.includes("--json");
     const silent = summary || json;
-    const files = findInstructionFiles(restArgs);
+    const files = findInstructionFiles(restArgs, config?.exclude);
     // Resolve the active harness ONCE so the harness-specific checks below run
     // against the right adapter's dialect (tool/event catalogs) and surfaces —
     // not a hard-coded Claude Code default. A subagent-surface rule reports n/a
@@ -976,6 +986,9 @@ async function runLint(restArgs, flags, config) {
     // 7m. MCP hook-target — a `type: mcp_tool` hook action that's incomplete or
     // targets an undeclared server (the moat applied to the hook surface).
     const mcpHookTargets = checkMcpHookTargets(config, silent, adapter);
+    // 7n. Prefer-compiled-hooks — ONE discovery nudge (not per-hook) toward
+    // compiled `vigiles/hook` artifacts when hand-written hooks ship. Recommendation.
+    const preferCompiledHooks = checkPreferCompiledHooks(config, silent, adapter);
     // 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
@@ -1041,6 +1054,8 @@ async function runLint(restArgs, flags, config) {
         frontmatterValidErrors: frontmatterValid.errors,
         mcpHookIssues: mcpHookTargets.issues,
         mcpHookErrors: mcpHookTargets.errors,
+        preferCompiledHookIssues: preferCompiledHooks.issues,
+        preferCompiledHookErrors: preferCompiledHooks.errors,
         docRefErrors: docRefReport.errors.length,
         symbolRefErrors,
         mcpRefErrors,
@@ -1195,10 +1210,27 @@ function init(args) {
     const targetFlag = args.find((a) => a.startsWith("--target="));
     const target = targetFlag ? targetFlag.split("=")[1] : "CLAUDE.md";
     const specPath = `${target}.spec.ts`;
-    if ((0, node_fs_1.existsSync)((0, node_path_1.resolve)(process.cwd(), specPath))) {
+    const specAbs = (0, node_path_1.resolve)(process.cwd(), specPath);
+    if ((0, node_fs_1.existsSync)(specAbs)) {
         console.log(`${specPath} already exists.`);
         return;
     }
+    // Auto-adopt: when the target file already exists with hand-written content
+    // (no integrity header), faithfully convert it into a spec instead of
+    // scaffolding a blank one — so `init` leaves you with a spec, not homework, and
+    // `require-instructions-spec` is satisfied by construction. The compile that
+    // follows reproduces the file (+ the header); review the diff. `vigiles eject`
+    // reverses it. See research/install-enforcement-dx.md.
+    const targetAbs = (0, node_path_1.resolve)(process.cwd(), target);
+    if ((0, node_fs_1.existsSync)(targetAbs) && !targetHasHash(targetAbs)) {
+        const md = (0, node_fs_1.readFileSync)(targetAbs, "utf-8");
+        const { source, tier, sectionCount } = (0, adopt_js_1.adoptMarkdown)(md, (0, node_path_1.basename)(target));
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(specAbs), { recursive: true });
+        (0, node_fs_1.writeFileSync)(specAbs, source);
+        console.log(`Adopted ${target} → ${specPath} (${tier}, ${String(sectionCount)} section${sectionCount === 1 ? "" : "s"}). ` +
+            `Run \`vigiles compile\` and review the diff; the \`/strengthen\` skill upgrades prose to verified rules.`);
+        return;
+    }
     // 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
@@ -1245,11 +1277,125 @@ export default claude({${targetLine}
   },
 });
 `;
-    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\`.`);
 }
+/**
+ * `vigiles eject [file]` — the inverse of `compile`: hand a compiled instruction
+ * file back to the user as plain, hand-owned markdown. Strips the `vigiles:sha256`
+ * integrity header, adds a `require-instructions-spec` disable marker so `lint` stays quiet,
+ * and removes the spec that managed it (`--keep-spec` to leave it). The
+ * "managed-but-ejectable" escape hatch: adopting a typed spec is never a one-way
+ * door.
+ */
+function eject(args) {
+    const keepSpec = args.includes("--keep-spec");
+    const file = args.find((a) => !a.startsWith("-")) ?? "CLAUDE.md";
+    const abs = (0, node_path_1.resolve)(process.cwd(), file);
+    if (!(0, node_fs_1.existsSync)(abs)) {
+        console.error(`✗ ${file}: no such file.`);
+        process.exitCode = 1;
+        return;
+    }
+    const ejected = (0, integrity_js_1.ejectMarkdown)((0, node_fs_1.readFileSync)(abs, "utf-8"));
+    if (!ejected) {
+        console.log(`${file} is not vigiles-managed (no integrity header) — nothing to eject.`);
+        return;
+    }
+    (0, node_fs_1.writeFileSync)(abs, ejected.markdown);
+    console.log(`✓ Ejected ${file} — it's now plain, hand-owned markdown.`);
+    const specAbs = (0, node_path_1.resolve)(process.cwd(), ejected.specFile);
+    // SAFETY: the `compiled from <path>` header is untrusted text — a hand-edited /
+    // forged header could name `package.json` or `../../secret`, and a blind rmSync
+    // would delete it. Only ever remove a `.spec.ts` that resolves INSIDE the
+    // project (no `..` escape).
+    const relSpec = (0, node_path_1.relative)((0, node_path_1.resolve)(process.cwd()), specAbs);
+    const isSafeSpecTarget = ejected.specFile.endsWith(".spec.ts") &&
+        relSpec !== "" &&
+        !relSpec.startsWith("..");
+    if ((0, node_fs_1.existsSync)(specAbs)) {
+        if (!isSafeSpecTarget) {
+            console.log(`  ⚠ Kept ${ejected.specFile} — the integrity header names a path that isn't a .spec.ts inside this project (it may have been hand-edited); refusing to delete it. Remove it yourself if that's intended.`);
+        }
+        else if (keepSpec) {
+            console.log(`  Kept ${ejected.specFile} (--keep-spec) — but \`vigiles compile\` would re-manage ${file}.`);
+        }
+        else if (specReferencedElsewhere(ejected.specFile, file)) {
+            // A multi-target spec (e.g. `target: ["CLAUDE.md", "docs/AGENTS.md"]`, or a
+            // mirror) compiles to several files — possibly in other directories — that
+            // all name the SAME source in their header. Deleting it while ANY of them is
+            // still managed would orphan that file. So keep the spec until its last
+            // consumer is ejected.
+            console.log(`  Kept ${ejected.specFile} — another compiled file in this project is still managed by it (a multi-target / mirrored spec); deleting it would orphan that file. Eject the others too, or remove the spec by hand once it's unused.`);
+        }
+        else {
+            (0, node_fs_1.rmSync)(specAbs);
+            console.log(`  Removed ${ejected.specFile} (the spec that managed it).`);
+        }
+    }
+    // The disable marker is only added to instruction files (not skills/agents),
+    // so only mention it when it was actually written.
+    if (ejected.markdown.startsWith(integrity_js_1.REQUIRE_INSTRUCTIONS_SPEC_DISABLE)) {
+        console.log(`  Left a \`${integrity_js_1.REQUIRE_INSTRUCTIONS_SPEC_DISABLE}\` marker so \`vigiles lint\` won't ask for a spec; delete it if you remove vigiles entirely.`);
+    }
+}
+/**
+ * Whether another compiled markdown file ANYWHERE under the project still carries
+ * an integrity header naming `specFile` — i.e. the spec has OTHER compiled outputs
+ * (a multi-target `target: [...]` spec or a CLAUDE.md⇄AGENTS.md mirror, possibly
+ * in a different directory like `docs/AGENTS.md`), so removing it would orphan
+ * them. Walks the project tree from cwd, skipping heavy/irrelevant dirs; the
+ * ejected file itself is skipped (its header was already stripped). Matches on the
+ * RESOLVED spec path (not basename), so two unrelated specs that happen to share a
+ * filename — `src/CLAUDE.md.spec.ts` vs `CLAUDE.md.spec.ts`, common in a monorepo —
+ * don't collide; genuine sibling outputs of one compile carry the identical
+ * recorded spec path. Best-effort: an unreadable file is ignored.
+ */
+function specReferencedElsewhere(specFile, ejectedFile) {
+    const root = (0, node_path_1.resolve)(process.cwd());
+    const ejectedAbs = (0, node_path_1.resolve)(root, ejectedFile);
+    const specAbs = (0, node_path_1.resolve)(root, specFile);
+    const SKIP = new Set([
+        "node_modules",
+        ".git",
+        "dist",
+        "build",
+        "coverage",
+        ".next",
+        "out",
+    ]);
+    const stack = [root];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = (0, node_fs_1.readdirSync)(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            const p = (0, node_path_1.resolve)(dir, e.name);
+            if (e.isDirectory()) {
+                if (!SKIP.has(e.name))
+                    stack.push(p);
+                continue;
+            }
+            if (!e.name.endsWith(".md") || p === ejectedAbs)
+                continue;
+            try {
+                const header = (0, integrity_js_1.parseIntegrityHeader)((0, node_fs_1.readFileSync)(p, "utf-8"));
+                if (header && (0, node_path_1.resolve)(root, header.specFile) === specAbs)
+                    return true;
+            }
+            catch {
+                /* unreadable file — skip */
+            }
+        }
+    }
+    return false;
+}
 // ---------------------------------------------------------------------------
 // Setup wizard
 // ---------------------------------------------------------------------------
@@ -1429,7 +1575,8 @@ function scaffoldPillar2() {
     console.log("✓ Scaffolded vigiles.harness.mjs — Pillar 2 starter (npx vigiles test)");
     return ["vigiles.harness.mjs"];
 }
-/** Interactive prompts (TTY only): which pillars, CI, plugin. */
+/** Interactive prompts (TTY only): the readline IO shell over the pure
+ *  `collectSetupAnswers` (the Q&A logic is unit-tested in setup-plan.test.ts). */
 async function promptSetup() {
     const readline = await import("node:readline");
     const rl = readline.createInterface({
@@ -1441,17 +1588,8 @@ async function promptSetup() {
             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,
-        };
+        return await (0, setup_plan_js_1.collectSetupAnswers)(ask);
     }
     finally {
         rl.close();
@@ -1613,28 +1751,31 @@ function redirectSyncToolTargets(cwd, targets) {
 async function setupPillar1(detected, targetValue, harnesses) {
     const cwd = process.cwd();
     const written = [];
-    const needsMigration = [];
+    const adopted = [];
     // 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.
+    // Create specs. An existing hand-written target is faithfully ADOPTED into a
+    // spec (init() does the convert), not clobbered with a blank one — so the
+    // compile below reproduces it (the user reviews the diff). A greenfield target
+    // gets a blank starter spec.
     for (const target of targets) {
         const specPath = `${target}.spec.ts`;
-        const targetExists = (0, node_fs_1.existsSync)((0, node_path_1.resolve)(cwd, target));
+        const targetAbs = (0, node_path_1.resolve)(cwd, target);
+        const willAdopt = (0, node_fs_1.existsSync)(targetAbs) &&
+            !targetHasHash(targetAbs) &&
+            !(0, node_fs_1.existsSync)((0, node_path_1.resolve)(cwd, specPath));
         if ((0, node_fs_1.existsSync)((0, node_path_1.resolve)(cwd, specPath))) {
             console.log(`✓ ${specPath} already exists`);
         }
         else {
-            init(["--target=" + target]); // prints "Created …"
+            init(["--target=" + target]); // adopts existing content, else blank scaffold
             written.push(specPath);
-        }
-        if (targetExists && !targetHasHash((0, node_path_1.resolve)(cwd, target))) {
-            needsMigration.push(target);
-            console.log(`  ${target} already has content — adopt it into a spec with the adopt-spec skill, then \`vigiles compile\`.`);
+            if (willAdopt)
+                adopted.push(target);
         }
     }
     // Generate types + schema.
@@ -1659,17 +1800,59 @@ async function setupPillar1(detected, targetValue, harnesses) {
     (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().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)
+    // Compile — but NEVER overwrite an existing hand-written file during `init`:
+    // we compile only GREENFIELD targets (the file doesn't exist yet) and targets
+    // we already manage (carry our hash). An ADOPTED file is left untouched — the
+    // user reviews the generated spec and runs `vigiles compile` themselves to
+    // switch it to spec-managed (non-destructive by default; the compile is
+    // byte-faithful, but it's the user's call to make, with a diff to review).
+    // And we only compile when `vigiles` actually resolves — a fresh repo hasn't
+    // run `npm install` yet, so compiling would just error; defer it with a clear
+    // next step instead of a scary stack-traceless "failed to load".
+    const canCompile = canResolveVigiles(cwd);
+    const specs = canCompile
+        ? 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) {
+        console.log("\nCompiling specs...");
         await compile(specs, (0, validate_js_1.loadConfig)());
-    return { specTargets: targets, written, needsMigration };
+    }
+    else if (!canCompile) {
+        // Honest, project-type-aware guidance. A JS repo just needs `npm install`
+        // (init already added the devDep). A repo with NO package.json (Python, Rust,
+        // …) can't resolve the npm package at all, so point at the no-install paths
+        // instead of a misleading `npm install`.
+        if ((0, node_fs_1.existsSync)((0, node_path_1.resolve)(cwd, "package.json"))) {
+            console.log("\n  Skipping compile — run `npm install` (to fetch the vigiles dep just added), then `npx vigiles compile`.");
+        }
+        else {
+            console.log("\n  No package.json here, so the typed-spec compile isn't available yet.\n" +
+                "  • `npx vigiles lint` verifies your instruction files right now — no install needed.\n" +
+                "  • To spec-manage them, add a package.json first: `npm init -y && npm i -D vigiles`, then `npx vigiles compile`.");
+        }
+    }
+    return { specTargets: targets, written, adopted };
+}
+/**
+ * Whether `vigiles/spec` will resolve for a spec compiled from `cwd` — true when
+ * vigiles is installed locally (`node_modules/vigiles`) or `cwd` IS the vigiles
+ * package itself (the in-repo dogfood / a monorepo workspace). A fresh user repo
+ * that hasn't run `npm install` yet returns false, so `init` defers the compile
+ * instead of emitting a resolution error.
+ */
+function canResolveVigiles(cwd) {
+    if ((0, node_fs_1.existsSync)((0, node_path_1.resolve)(cwd, "node_modules", "vigiles")))
+        return true;
+    try {
+        const pkg = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.resolve)(cwd, "package.json"), "utf-8"));
+        return pkg.name === "vigiles";
+    }
+    catch {
+        return false;
+    }
 }
 /** Whether a harness binary (`claude`, `codex`) is on PATH. */
 function harnessBinaryPresent(bin) {
@@ -1821,24 +2004,37 @@ function printDetection(detected, harnesses) {
 /** 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 { plan, strict, targets, adopted, written } = opts;
     const specPathsList = targets.map((t) => `${t}.spec.ts`);
+    // A repo with no package.json (Python/Rust/…) can't resolve the npm package,
+    // so the typed-spec compile path needs an install first — give honest steps.
+    const hasPkg = (0, node_fs_1.existsSync)((0, node_path_1.resolve)(process.cwd(), "package.json"));
     console.log("\n---\nSetup complete.\n");
+    // Next steps in DEPENDENCY order: install the dep first, then compile (which
+    // needs it), then the optional hardening / test / CI steps.
     const nextSteps = [];
-    if (needsMigration.length > 0) {
-        nextSteps.push(`Adopt ${needsMigration.join(", ")} into a spec with the adopt-spec skill, then \`npx vigiles compile\``);
+    if (written.includes("package.json")) {
+        nextSteps.push("Run `npm install` to fetch the vigiles dev dependency");
+    }
+    if (adopted.length > 0 && !hasPkg) {
+        // Non-JS repo: compile needs a local install. Point at the no-install verify
+        // path + how to enable specs, instead of a compile that would fail.
+        nextSteps.push(`Verify now with \`npx vigiles lint\` (no install). To spec-manage ${adopted.join(", ")}, add a package.json first (\`npm init -y && npm i -D vigiles\`), then \`npx vigiles compile\` and review the diff`);
+    }
+    else if (adopted.length > 0) {
+        // Adoption is NON-DESTRUCTIVE: the file is untouched until you compile, so
+        // the diff to review is what compile WOULD produce (byte-faithful).
+        nextSteps.push(`Run \`npx vigiles compile\` to put ${adopted.join(", ")} under spec management — it reproduces the file + adds an integrity header, so review the diff (\`vigiles eject\` reverses it)`);
+        nextSteps.push("Run the `/strengthen` skill to upgrade prose rules to verified enforce()/guard()");
     }
     else if (specPathsList.length > 0) {
-        nextSteps.push(`Edit ${specPathsList.join(", ")} — add your conventions, then \`/strengthen\``);
+        nextSteps.push(`Edit ${specPathsList.join(", ")} — add your conventions, then \`npx vigiles compile\` (and \`/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.push("When ready, enforce specs + tests in CI: `npx vigiles init --strict`");
     }
     nextSteps.forEach((s, i) => {
         console.log(`  ${String(i + 1)}. ${s}`);
@@ -1851,12 +2047,15 @@ function printSetupSummary(opts) {
 }
 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());
     }
+    // Read strict from the RESOLVED plan, not the raw flag — an interactive "yes"
+    // to the workflow tier (no `--strict` flag) sets plan.strict, and the config
+    // write + summary must honor it.
+    const strict = plan.strict;
     const pillars = [plan.lint && "lint", plan.test && "test"]
         .filter(Boolean)
         .join(" + ");
@@ -1869,12 +2068,12 @@ async function setup(args) {
     const written = [];
     // Lint pillar — verify instruction-file references.
     let targets = [];
-    let needsMigration = [];
+    let adopted = [];
     if (plan.lint) {
         console.log("");
         const p1 = await setupPillar1(detected, parsed.target, harnesses);
         targets = p1.specTargets;
-        needsMigration = p1.needsMigration;
+        adopted = p1.adopted;
         written.push(...p1.written);
     }
     // Test pillar — test the harness.
@@ -1905,9 +2104,16 @@ async function setup(args) {
         console.log("    npm install -D rule-porter");
     }
     // Project config — record the harness(es) so compile/lint select the dialect
-    // deterministically (no cwd sniffing), plus strict rule severities on --strict.
-    writeProjectConfig({ harnesses, strict, written });
-    printSetupSummary({ plan, strict, targets, needsMigration, written });
+    // deterministically (no cwd sniffing), plus strict rule severities on --strict
+    // (or all-warn under --report-only).
+    writeProjectConfig({
+        harnesses,
+        strict,
+        reportOnly: parsed.reportOnly,
+        lint: plan.lint,
+        written,
+    });
+    printSetupSummary({ plan, strict, targets, adopted, written });
 }
 /** Canonical, de-duplicated harness list → a config value (string when one). */
 function harnessConfigValue(harnesses) {
@@ -1934,6 +2140,8 @@ function writeProjectConfig(opts) {
     const merged = (0, setup_plan_js_1.mergeProjectConfig)(existing, {
         harness: harnessConfigValue(opts.harnesses),
         strict: opts.strict,
+        reportOnly: opts.reportOnly,
+        lint: opts.lint,
     });
     if (!merged)
         return;
@@ -2165,6 +2373,34 @@ function checkSkillFrontmatter(config, silent, adapter) {
     }
     return { issues: found.length, errors: sev === "error" ? found.length : 0 };
 }
+/**
+ * Apply the `prefer-compiled-hooks` rule: a SINGLE repo-level recommendation
+ * (one finding regardless of hook count) nudging hand-written hooks toward
+ * compiled `vigiles/hook` artifacts. A discovery nudge, not a defect — the shell
+ * lane stays first-class — so it fires once and the message links the guide.
+ * Reuses `scanPlugin`'s `manualHookCount` (one-detector-no-drift).
+ */
+function checkPreferCompiledHooks(config, silent, adapter) {
+    const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["prefer-compiled-hooks"]);
+    if (!sev)
+        return { issues: 0, errors: 0 };
+    let count;
+    try {
+        count = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).manualHookCount;
+    }
+    catch {
+        return { issues: 0, errors: 0 };
+    }
+    if (count === 0)
+        return { issues: 0, errors: 0 };
+    const message = (0, scan_js_1.preferCompiledHooksMessage)(count);
+    if (!silent) {
+        console.log("\nCompiled-hooks check:\n");
+        console.log(`  ${sev === "error" ? "✗" : "ℹ"} ${message}`);
+        ghAnnotate(sev === "error" ? "error" : "warning", message);
+    }
+    return { issues: 1, errors: sev === "error" ? 1 : 0 };
+}
 /**
  * Apply the `mcp-config` rule: a declared MCP server with neither a `command`
  * (stdio) nor a `url` (http/sse) can't start. Reuses `scanPlugin`'s `mcpIssues`.
@@ -2441,29 +2677,58 @@ async function countGuidanceRules(silent = false) {
 // ---------------------------------------------------------------------------
 // Command handlers for main()
 // ---------------------------------------------------------------------------
-function findInstructionFiles(restArgs) {
-    if (restArgs.length > 0)
-        return restArgs;
+function findInstructionFiles(restArgs, exclude = []) {
     const patterns = ["**/CLAUDE.md", "**/AGENTS.md", "**/SKILL.md"];
-    const files = [];
-    for (const pattern of patterns) {
-        files.push(...(0, glob_1.globSync)(pattern, { ignore: IGNORE_NODE_MODULES, cwd: process.cwd() }));
+    // `exclude` (from .vigilesrc.json) drops vendored/benchmark fixtures the repo's
+    // own lint shouldn't police — a third-party CLAUDE.md isn't held to require-instructions-spec.
+    // node_modules/dist/.git stay always-excluded.
+    const ignore = [...IGNORE_NODE_MODULES, "dist/**", ".git/**", ...exclude];
+    // Discover instruction files under one directory, as paths relative to cwd.
+    const discoverIn = (dirAbs) => patterns
+        .flatMap((p) => (0, glob_1.globSync)(p, { ignore, cwd: dirAbs, absolute: true }))
+        .map((abs) => (0, node_path_1.relative)(process.cwd(), abs));
+    if (restArgs.length === 0)
+        return discoverIn(process.cwd());
+    // Explicit args: expand a DIRECTORY to the instruction files inside it (so
+    // `vigiles lint .` works), keep a file arg as-is, and pass a non-existent arg
+    // through unchanged (lint reports it as not-found rather than crashing).
+    const out = [];
+    for (const arg of restArgs) {
+        const abs = (0, node_path_1.resolve)(process.cwd(), arg);
+        if ((0, node_fs_1.existsSync)(abs) && (0, node_fs_1.lstatSync)(abs).isDirectory()) {
+            out.push(...discoverIn(abs));
+        }
+        else {
+            out.push(arg);
+        }
     }
-    return files;
+    return out;
 }
 /** Value of a `--flag=value` arg (the `=` form, so it never collides with a positional). */
 function flagValue(args, name) {
     return args.find((a) => a.startsWith(`${name}=`))?.slice(name.length + 1);
 }
 /**
- * The `scan --trigger` behavioral column: load the author-supplied per-skill
- * prompt sets, probe the plugin's model-invocable skills, print the column.
- * Model-gated and opt-in — the structural scan above stays deterministic.
+ * `vigiles scan <dir> --trigger` — the MODEL-GATED behavioral report on a plugin (the paid
+ * tier; `scan` stays free/deterministic). Loads the author-supplied per-skill prompt
+ * sets (`--prompts`) and reports BOTH behavioral columns: trigger-rate (does each
+ * skill actually FIRE — recall + precision) and the selection-collision matrix (does
+ * one skill HIJACK a sibling's prompt — the behavioral confirmation of the
+ * deterministic `description-overlap` rule). Needs the harness CLI + model auth;
+ * degrades honestly ("unavailable") when absent. The OSS-testing front door:
+ * `vigiles scan ./plugin --trigger --prompts=p.json`.
  */
-async function handleScanTrigger(root, args, json, harness) {
+async function handleMeasure(restArgs, args) {
+    const dir = (0, node_path_1.resolve)(restArgs[0] ?? ".");
+    const json = args.includes("--json");
+    const harnessFlag = harnessFlagFrom(args);
+    const adapter = harnessFlag
+        ? (0, adapter_registry_js_1.resolveAdapter)(dir, harnessFlag)
+        : (0, adapter_registry_js_1.detectAdapterResult)(dir).adapter;
+    const harness = adapter.name === "codex" ? "codex" : "claude-code";
     const promptsPath = flagValue(args, "--prompts");
     if (!promptsPath) {
-        console.error("scan --trigger needs --prompts=<file.json> (a map of skill name → { prompts, irrelevant }).");
+        console.error("measure needs --prompts=<file.json> (a map of skill name → { prompts, irrelevant }).");
         process.exitCode = 2;
         return;
     }
@@ -2472,21 +2737,62 @@ async function handleScanTrigger(root, args, json, harness) {
         promptSet = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.resolve)(promptsPath), "utf-8"));
     }
     catch (e) {
-        console.error(`scan --trigger: could not read --prompts file "${promptsPath}": ${e instanceof Error ? e.message : String(e)}`);
+        console.error(`measure: could not read --prompts file "${promptsPath}": ${e instanceof Error ? e.message : String(e)}`);
         process.exitCode = 2;
         return;
     }
-    const concurrencyRaw = flagValue(args, "--concurrency");
-    const minPromptsRaw = flagValue(args, "--min-prompts");
-    const report = await (0, scan_behavioral_js_1.probePluginTriggers)(root, promptSet, {
-        concurrency: concurrencyRaw ? Number(concurrencyRaw) : undefined,
-        minPrompts: minPromptsRaw ? Number(minPromptsRaw) : undefined,
-        model: flagValue(args, "--model"),
+    const num = (f) => {
+        const v = flagValue(args, f);
+        return v ? Number(v) : undefined;
+    };
+    const model = flagValue(args, "--model");
+    const concurrency = num("--concurrency");
+    // Trigger-rate (recall + precision) AND the selection-collision matrix — the two
+    // behavioral columns, one report. Collisions report n/a where they don't apply
+    // (a single skill, or Codex — no skill-selection event), never a false pass.
+    const trigger = await (0, scan_behavioral_js_1.probePluginTriggers)(dir, promptSet, {
+        concurrency,
+        minPrompts: num("--min-prompts"),
+        model,
         harness,
     });
-    console.log(json
-        ? JSON.stringify(report, null, 2)
-        : `\n${(0, scan_behavioral_js_1.formatBehavioralReport)(report)}`);
+    const collisions = await (0, scan_behavioral_js_1.measurePluginSelection)(dir, promptSet, {
+        concurrency,
+        trials: num("--trials"),
+        model,
+        harness,
+    });
+    if (json) {
+        console.log(JSON.stringify({ trigger, collisions }, null, 2));
+        return;
+    }
+    console.log(`\n${(0, scan_behavioral_js_1.formatBehavioralReport)(trigger)}`);
+    console.log(`\n${(0, scan_behavioral_js_1.formatSelectionReport)(collisions)}`);
+}
+/**
+ * `vigiles generate <kind>` — one verb over the three dev-toolchain generators
+ * (types/schema/harness). Each emits a file YOUR editor/tsc reads, not the agent
+ * — grouped under one verb instead of N hyphenated siblings (cohesive-cli-surface,
+ * high-bar-for-new-commands). The kind is the first positional; the rest passes
+ * through to the per-kind handler (out path / dir).
+ */
+async function handleGenerate(restArgs, args) {
+    const kind = restArgs[0];
+    const rest = restArgs.slice(1);
+    switch (kind) {
+        case "types":
+            handleGenerateTypes(args, rest);
+            break;
+        case "schema":
+            handleGenerateSchema(args, rest);
+            break;
+        case "harness":
+            await handleGenerateHarness(args, rest);
+            break;
+        default:
+            console.error("Usage: vigiles generate <types|schema|harness> [out] [--check]");
+            process.exit(2);
+    }
 }
 function handleGenerateTypes(args, restArgs) {
     const checkOnly = args.includes("--check");
@@ -2511,7 +2817,7 @@ function handleGenerateTypes(args, restArgs) {
     if (checkOnly) {
         // --check: compare against existing file, exit 1 if stale
         if (!(0, node_fs_1.existsSync)(fullOut)) {
-            console.log(`\n✗ ${outPath} does not exist. Run \`vigiles generate-types\` to create it.`);
+            console.log(`\n✗ ${outPath} does not exist. Run \`vigiles generate types\` to create it.`);
             process.exit(1);
         }
         const existing = (0, node_fs_1.readFileSync)(fullOut, "utf-8");
@@ -2526,7 +2832,7 @@ function handleGenerateTypes(args, restArgs) {
             console.log(`\n✓ ${outPath} is up to date`);
         }
         else {
-            console.log(`\n✗ ${outPath} is stale. Run \`vigiles generate-types\` to update.`);
+            console.log(`\n✗ ${outPath} is stale. Run \`vigiles generate types\` to update.`);
             process.exit(1);
         }
         return;
@@ -2553,7 +2859,7 @@ function handleGenerateSchema(args, restArgs) {
     const fullOut = (0, node_path_1.resolve)(process.cwd(), outPath);
     if (checkOnly) {
         if (!(0, node_fs_1.existsSync)(fullOut)) {
-            console.log(`\n✗ ${outPath} does not exist. Run \`vigiles generate-schema\` to create it.`);
+            console.log(`\n✗ ${outPath} does not exist. Run \`vigiles generate schema\` to create it.`);
             process.exit(1);
         }
         const existing = (0, node_fs_1.readFileSync)(fullOut, "utf-8");
@@ -2561,7 +2867,7 @@ function handleGenerateSchema(args, restArgs) {
             console.log(`\n✓ ${outPath} is up to date`);
         }
         else {
-            console.log(`\n✗ ${outPath} is stale. Run \`vigiles generate-schema\` to update.`);
+            console.log(`\n✗ ${outPath} is stale. Run \`vigiles generate schema\` to update.`);
             process.exit(1);
         }
         return;
@@ -2576,13 +2882,46 @@ function handleGenerateSchema(args, restArgs) {
         `    # yaml-language-server: $schema=./${outPath}`);
 }
 /**
- * `vigiles generate-harness [dir] [out]` — emit one typed registry over every
+ * `vigiles generate harness [dir] [out]` — emit one typed registry over every
  * `*.spec.ts` under `dir`, so a single `tsc --noEmit` cross-checks the whole
  * harness (dangling delegates → a tsc error; duplicate names → this command
  * exits non-zero; the capability lattice → a computed export). The third
  * generated artifact beside `generate-types` / `generate-schema`. See
  * docs/cli.md and research/whole-harness-codegen.md.
  */
+/**
+ * Keep an EXISTING `harness.gen.ts` fresh as a side effect of `compile`, so the
+ * whole-harness registry tracks the specs without a separate manual
+ * `generate-harness` run (the user almost never calls that verb by hand). Gated
+ * on the file already existing: compile keeps a registry the user opted into
+ * (committed like a lockfile) up to date — it never imposes one on a repo that
+ * didn't ask for it. Cheap by construction: `generate-harness` only PARSES specs
+ * (no linter spawning), unlike `generate-types`/`generate-schema` (which spawn
+ * every linter and so stay on the config-change guard, off the hot compile path).
+ * Returns false on a duplicate-name collision so it fails the compile.
+ */
+async function refreshHarnessGenIfPresent(harnessFlag) {
+    const dir = process.cwd();
+    const fullOut = (0, node_path_1.resolve)(dir, generate_harness_js_1.HARNESS_GEN_FILENAME);
+    if (!(0, node_fs_1.existsSync)(fullOut))
+        return true; // opt-in: nothing to refresh
+    const adapter = harnessFlag
+        ? (0, adapter_registry_js_1.resolveAdapter)(dir, harnessFlag)
+        : (0, adapter_registry_js_1.detectAdapterResult)(dir).adapter;
+    const model = await (0, generate_harness_js_1.loadHarnessModel)(dir, (abs) => loadSpec(abs));
+    const result = (0, generate_harness_js_1.generateHarness)(model, {
+        dialect: adapter.dialect,
+        outDir: (0, node_path_1.dirname)(fullOut),
+    });
+    if (result.duplicate) {
+        console.log(`\n✗ ${result.duplicate.message}`);
+        console.log(`::error::${result.duplicate.message}`);
+        return false;
+    }
+    (0, node_fs_1.writeFileSync)(fullOut, result.gen);
+    console.log(`  ↻ refreshed ${generate_harness_js_1.HARNESS_GEN_FILENAME} (${String(result.agentCount)} agent(s))`);
+    return true;
+}
 async function handleGenerateHarness(args, restArgs) {
     const checkOnly = args.includes("--check");
     const dir = (0, node_path_1.resolve)(restArgs[0] ?? ".");
@@ -2621,7 +2960,7 @@ async function handleGenerateHarness(args, restArgs) {
     }
     if (checkOnly) {
         if (!(0, node_fs_1.existsSync)(fullOut)) {
-            console.log(`\n✗ ${outPath} does not exist. Run \`vigiles generate-harness\` to create it.`);
+            console.log(`\n✗ ${outPath} does not exist. Run \`vigiles generate harness\` to create it.`);
             process.exit(1);
         }
         const existing = (0, node_fs_1.readFileSync)(fullOut, "utf-8");
@@ -2635,7 +2974,7 @@ async function handleGenerateHarness(args, restArgs) {
             console.log(`\n✓ ${outPath} is up to date`);
         }
         else {
-            console.log(`\n✗ ${outPath} is stale. Run \`vigiles generate-harness\` to update.`);
+            console.log(`\n✗ ${outPath} is stale. Run \`vigiles generate harness\` to update.`);
             process.exit(1);
         }
         return;
@@ -2713,7 +3052,7 @@ function harnessFlagFrom(argv) {
         ?.slice("--harness=".length);
 }
 /**
- * `vigiles explain <dir> [name]` — the deterministic WHY behind a low score (C4):
+ * `vigiles scan <dir> --explain [name]` — the deterministic WHY behind a low score (C4):
  * scan a plugin and surface the structural CAUSE of a behavioral symptom + the
  * one-line fix. No model — it reads the same `ScanReport` `scan` computes. An
  * optional surface name narrows to one underperforming skill/agent (the
@@ -2738,6 +3077,19 @@ function handleExplain(restArgs, args) {
         console.log(`Explaining "${surface}":\n`);
     console.log((0, score_explainer_js_1.formatExplanations)(exps));
 }
+/**
+ * Whole-harness capability lattice from a scanned plugin's agents (no `tools:` line →
+ * inherits-all). The substrate `scan --capability-diff` diffs. Reused for both the
+ * already-scanned "after" report and the freshly-scanned "before" dir.
+ */
+function capabilitiesOfReport(report, dialect) {
+    const agents = report.agents.map((a) => ({
+        name: a.name,
+        tools: a.tools ?? undefined,
+        file: a.path,
+    }));
+    return (0, generate_harness_js_1.computeHarnessCapabilities)(agents, dialect);
+}
 /**
  * The plugin's declared name for the namespaced skill id, read from the layout's
  * manifest (adapter-aware path, not a hardcoded `.claude-plugin/`), falling back to
@@ -2871,12 +3223,15 @@ function printUsage(command) {
     console.log("vigiles — compile typed specs to instruction files");
     console.log("");
     console.log("Commands:");
-    console.log("  vigiles init [flags]           Setup project (--lint, --test, --harness=, --strict, --no-gha, --force)");
+    console.log("  vigiles init [flags]           Setup project (--lint, --test, --harness=, --strict, --report-only, --no-gha, --force)");
     console.log("  vigiles compile [files...]     Compile .spec.ts → .md");
+    console.log("  vigiles eject [file]           Un-manage a compiled file → plain hand-owned markdown (--keep-spec)");
     console.log("  vigiles lint [files...]        Verify references, find gaps in instruction files");
+    console.log("  vigiles scan [dir...]          Report what a plugin ships + what's broken (free; 2+ dirs → leaderboard)");
+    console.log("                                 --trigger: do skills fire/collide? (real model) · --explain: why a surface underperforms · --fix-plan");
+    console.log("                                 with model access + a TTY, scan offers to measure firing; --no-interactive/--yes/--json hint instead (agents)");
     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, --min=N, --no-skip)");
-    console.log("  vigiles explain <dir> [name]   Deterministic WHY a skill/agent underperforms + the fix (--json, --harness=)");
     console.log("  vigiles scaffold-test [dir]    Generate a starter test for each untested skill/agent/hook (--write, --json)");
     console.log("");
     console.log("Examples:");
@@ -2885,12 +3240,8 @@ function printUsage(command) {
     console.log("  vigiles lint                 Verify references, hashes, coverage + suggestions");
     console.log("");
     console.log("Plumbing:");
-    console.log("  vigiles generate-types [out]  Emit .d.ts from project state");
-    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 generate-harness [dir] Emit harness.gen.ts — one typed registry");
-    console.log("  vigiles generate-harness --check Verify harness.gen.ts is up to date");
+    console.log("  vigiles generate <kind>       Emit a dev-toolchain artifact: types (.d.ts) · schema (JSON Schema) · harness (harness.gen.ts)");
+    console.log("  vigiles generate <kind> --check  Verify the generated file is up to date");
     console.log("  vigiles --version             Print the version number");
     if (command && command !== "--help") {
         console.log(`\nUnknown command: "${command}"`);
@@ -2928,7 +3279,7 @@ function annotateLintForGitHub(report, flags) {
  */
 function runSkillCommand(target) {
     if (!target) {
-        console.error("Usage: vigiles run-skill <SKILL.md>");
+        console.error("Usage: vigiles hook-runtime run-skill <SKILL.md>");
         process.exit(2);
     }
     const path = (0, node_path_1.resolve)(process.cwd(), target);
@@ -2983,7 +3334,7 @@ function skillHookCommand() {
 /** Mark a skill active so the Stop hook enforces its result gate. */
 function skillStartCommand(target) {
     if (!target) {
-        console.error("Usage: vigiles skill-start <SKILL.md>");
+        console.error("Usage: vigiles hook-runtime skill-start <SKILL.md>");
         process.exit(2);
     }
     (0, skill_runtime_js_1.setActiveSkill)(process.cwd(), target);
@@ -3056,26 +3407,29 @@ function agentHookCommand() {
         /* malformed input → no tool, allow */
     }
     const cwd = process.cwd();
-    // EXPERIMENTAL (parked P3, flat-only — do NOT auto-wire): the Task/SubagentStop
-    // bracketing below assumes one active subagent at a time and is NOT nesting-safe
-    // (CC v2.1.172 depth-5 nesting needs a stack + spawn-tool-name check). See
-    // research/effect-boundary-design.md.
-    // SubagentStop → CLOSE the window deterministically (no model `agent-done`):
-    // the subagent returned, so its contract/purity no longer apply.
+    // EXPERIMENTAL (parked P3 — do NOT auto-wire). The spawn/SubagentStop bracketing
+    // is now nesting-safe: a depth-aware STACK (push on dispatch, POP on SubagentStop)
+    // closes the contract-escape the flat single-slot model allowed under CC v2.1.172
+    // depth-5 nesting. See research/effect-boundary-design.md + AgentWindowStack.tla.
+    //
+    // SubagentStop → CLOSE the window deterministically (no model `agent-done`): the
+    // subagent returned, so POP its frame — control returns to its PARENT, whose
+    // contract the gate enforces again (NOT a full clear, which would drop the parent).
     if (event === "SubagentStop") {
-        (0, agent_runtime_js_1.clearActiveAgent)(cwd);
+        (0, agent_runtime_js_1.popActiveAgent)(cwd);
         (0, effect_region_js_1.clearEffectActive)(cwd);
         return;
     }
-    // PreToolUse(Task) → OPEN the window deterministically (no model `agent-start`
-    // / `effect-enter`): the parent is dispatching a subagent, so activate that
-    // subagent's compiled contract for the tool calls it is about to make. The
-    // Task dispatch itself is the PARENT's action — don't gate it against the
-    // subagent's contract; just open the window and allow.
-    if (tool === "Task") {
+    // PreToolUse(spawn) → OPEN the window deterministically (no model `agent-start` /
+    // `effect-enter`): the parent is dispatching a subagent, so PUSH that subagent's
+    // compiled contract for the tool calls it is about to make. Recognize both spawn
+    // tool names — `Task` (top-level dispatch) and `Agent` (nested-spawn, CC v2.1.172)
+    // — gated on a resolvable `subagent_type` so a non-spawn call never opens a frame.
+    // The dispatch itself is the PARENT's action — don't gate it; just open + allow.
+    if (tool === "Task" || tool === "Agent") {
         const agentPath = (0, agent_runtime_js_1.decideTaskDispatch)(toolInput, cwd, process.env.CLAUDE_PLUGIN_ROOT);
         if (agentPath) {
-            (0, agent_runtime_js_1.setActiveAgent)(cwd, agentPath);
+            (0, agent_runtime_js_1.pushActiveAgent)(cwd, agentPath);
             (0, effect_region_js_1.setEffectActive)(cwd);
         }
         return;
@@ -3089,7 +3443,7 @@ function agentHookCommand() {
     }
 }
 /**
- * `vigiles intercept-tool-hook` — the PreToolUse interception hook for the
+ * `vigiles hook-runtime intercept-tool` — the PreToolUse interception hook for the
  * tool-call spy. Reads the intercept list from `VIGILES_INTERCEPT_TOOLS`, decides
  * whether the called tool should be intercepted, and if so denies the real
  * execution (exit 2) with a block message — the call is intercepted (prevented),
@@ -3112,63 +3466,99 @@ function interceptToolHookCommand() {
         process.exit(2);
     }
 }
+/**
+ * `vigiles hook-runtime guard` — the PreToolUse gate for typed safe-by-construction guards
+ * (EXPERIMENTAL). Reads the live event on stdin, runs the declared guard set
+ * (`.vigiles/guards.json`) against the session ledger (`.vigiles/guard-ledger.json`),
+ * and blocks (exit 2 + reason) or records the allowed call. The command in the
+ * generated hooks block IS this gate — not user shell — so the enforcement is
+ * safe-by-construction. See src/core/guards.ts.
+ */
+function guardHookCommand() {
+    let raw = "";
+    try {
+        raw = (0, node_fs_1.readFileSync)(0, "utf-8");
+    }
+    catch {
+        /* no stdin */
+    }
+    const { decision } = (0, guards_js_1.runGuardHook)(process.cwd(), raw);
+    if (!decision.allow) {
+        console.error(decision.reason ?? "Blocked by a vigiles guard.");
+        process.exit(2);
+    }
+}
 /** Mark a subagent active so the PreToolUse hook enforces its tool contract. */
 function agentStartCommand(target) {
     if (!target) {
-        console.error("Usage: vigiles agent-start <agents/<name>.md>");
+        console.error("Usage: vigiles hook-runtime agent-start <agents/<name>.md>");
         process.exit(2);
     }
-    (0, agent_runtime_js_1.setActiveAgent)(process.cwd(), target);
+    (0, agent_runtime_js_1.pushActiveAgent)(process.cwd(), target);
     console.log(`Active agent: ${target}`);
 }
 /** Dispatch the skill-runtime subcommands. Returns false if unrecognized. */
-function handleSkillCommand(command, restArgs) {
-    switch (command) {
-        case "run-skill":
-            runSkillCommand(restArgs[0]);
-            return true;
+/**
+ * `vigiles hook-runtime <kind> [args]` — the hidden umbrella for RUNTIME
+ * entrypoints: the executables the harness invokes via a block `vigiles compile`
+ * emits into your hooks config, NEVER typed by a human. They stay off the help
+ * surface by design — verbs are typed, runtime entrypoints are emitted (the
+ * cohesive-cli-surface rule). Renaming a `<kind>` breaks every already-emitted
+ * block, so it is a breaking change.
+ */
+async function handleHookRuntime(kind, restArgs) {
+    switch (kind) {
+        case "run-program":
+            await runHookProgramCommand(restArgs[0]);
+            return;
+        case "agent":
+            agentHookCommand();
+            return;
+        case "agent-start":
+            agentStartCommand(restArgs[0]);
+            return;
+        case "agent-done":
+            (0, agent_runtime_js_1.popActiveAgent)(process.cwd());
+            return;
+        case "skill":
+            skillHookCommand();
+            return;
+        case "skill-tool":
+            skillToolHookCommand();
+            return;
         case "skill-start":
             skillStartCommand(restArgs[0]);
-            return true;
+            return;
         case "skill-done":
             (0, skill_runtime_js_1.clearActiveSkill)(process.cwd());
-            return true;
-        case "skill-hook":
-            skillHookCommand();
-            return true;
-        case "skill-tool-hook":
-            skillToolHookCommand();
-            return true;
-        case "agent-start":
-            agentStartCommand(restArgs[0]);
-            return true;
-        case "agent-done":
-            (0, agent_runtime_js_1.clearActiveAgent)(process.cwd());
-            return true;
-        case "agent-hook":
-            agentHookCommand();
-            return true;
-        case "intercept-tool-hook":
+            return;
+        case "run-skill":
+            runSkillCommand(restArgs[0]);
+            return;
+        case "intercept-tool":
             interceptToolHookCommand();
-            return true;
-        case "action-hook":
+            return;
+        case "guard":
+            guardHookCommand();
+            return;
+        case "action":
             actionHookCommand();
-            return true;
+            return;
         case "refs":
-            refsCommand(restArgs[0]);
-            return true;
-        case "refs-hook":
             refsHookCommand();
-            return true;
+            return;
         case "effect-enter":
             (0, effect_region_js_1.setEffectActive)(process.cwd());
             console.log("Effect boundary entered.");
-            return true;
+            return;
         case "effect-exit":
             (0, effect_region_js_1.clearEffectActive)(process.cwd());
-            return true;
+            return;
         default:
-            return false;
+            console.error(`vigiles hook-runtime: unknown runtime entrypoint "${kind ?? ""}". ` +
+                `These are emitted into your hooks config by \`vigiles compile\` — ` +
+                `you don't run them by hand.`);
+            process.exit(2);
     }
 }
 /**
@@ -3203,40 +3593,6 @@ const INSTRUCTION_FILE = /^(SKILL|CLAUDE|AGENTS)\.md$/;
 function isInstructionFile(file) {
     return INSTRUCTION_FILE.test((0, node_path_1.basename)(file));
 }
-/**
- * Inspect an instruction file's symbol references: broken file-qualified refs
- * (`path.ext#symbol` whose file/symbol is wrong) and code-shaped references not
- * yet marked. Emits one line per finding via `log`; returns whether any issue
- * was found. `basePath` is the file's own directory (where paths resolve).
- */
-function reportRefIssues(markdown, basePath, log) {
-    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) {
-    if (!target) {
-        console.error("Usage: vigiles refs <instruction-file.md>");
-        process.exit(2);
-    }
-    const cwd = process.cwd();
-    let markdown;
-    try {
-        markdown = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(cwd, target), "utf-8");
-    }
-    catch {
-        console.error(`Cannot read ${target}`);
-        process.exit(2);
-    }
-    const bad = reportRefIssues(markdown, (0, node_path_1.dirname)((0, node_path_1.resolve)(cwd, target)), (m) => {
-        console.log(m);
-    });
-    if (bad)
-        process.exit(2);
-    console.log(`✓ ${target}: all code references are marked and resolve.`);
-}
 /**
  * PostToolUse-hook entrypoint: when the agent edits an instruction file, force
  * every code reference to carry a file-qualified mark (`path.ext#symbol`) and
@@ -3301,6 +3657,448 @@ function refsHookCommand() {
         },
     }) + "\n");
 }
+// ---------------------------------------------------------------------------
+// Compiled hooks (`vigiles/hook`) — author a hook as a pure typed program,
+// compile it to a harness block, run it as the hooks-block command.
+// ---------------------------------------------------------------------------
+/**
+ * Load a compiled-hook program's default export. JS module formats
+ * (`.mjs`/`.cjs`/`.js`) load via dynamic import directly; a TypeScript hook
+ * loads only under a TS-capable runtime (tsx / Node >= 23.6) — otherwise an
+ * actionable error points at authoring it as `.mjs`.
+ */
+async function loadHookProgram(file) {
+    const abs = (0, node_path_1.resolve)(process.cwd(), file);
+    const { pathToFileURL } = require("node:url");
+    let mod;
+    try {
+        mod = (await import(pathToFileURL(abs).href));
+    }
+    catch (e) {
+        if (/\.(?:m|c)?ts$/.test(file)) {
+            throw new hook_program_js_1.HookCompileError(`Cannot load TypeScript hook "${file}" in this Node runtime. Run under ` +
+                `tsx (npx tsx …) / Node >= 23.6, or author the hook as a .mjs file.`);
+        }
+        throw new hook_program_js_1.HookCompileError(`Cannot load hook "${file}": ${e.message}`);
+    }
+    // Unwrap the ESM/CJS double-default that `export default` can produce.
+    const program = mod.default?.default ?? mod.default;
+    if (!program || typeof program !== "object") {
+        throw new hook_program_js_1.HookCompileError(`${file} has no default-exported hook program ` +
+            `(use \`export default defineHook({…})\`).`);
+    }
+    return program;
+}
+/** Load a registered provider (`.vigiles/providers/<name>`) → its definition. */
+async function loadProvider(file) {
+    const abs = (0, node_path_1.resolve)(process.cwd(), file);
+    const { pathToFileURL } = require("node:url");
+    let mod;
+    try {
+        mod = (await import(pathToFileURL(abs).href));
+    }
+    catch (e) {
+        throw new hook_program_js_1.HookCompileError(`Cannot load provider "${file}": ${e.message}`);
+    }
+    const def = mod.default?.default ?? mod.default;
+    if (!def ||
+        typeof def !== "object" ||
+        def.kind !== "provider-def") {
+        throw new hook_program_js_1.HookCompileError(`${file} has no default-exported provider ` +
+            `(use \`export default defineProvider({…})\`).`);
+    }
+    return def;
+}
+/**
+ * Compile (validate) the registered providers under `.vigiles/providers/`: each
+ * must load and be read-only unless it opted into `dangerous`. Returns the set of
+ * valid provider NAMES (so a hook's `provider()` ref can resolve at compile).
+ * Throws HookCompileError on an unsafe provider — the same fail-the-build contract
+ * as a hook.
+ */
+async function compileProviders() {
+    const names = [];
+    for (const file of (0, hook_install_js_1.discoverProviderFiles)(process.cwd())) {
+        const def = await loadProvider(file);
+        if ((0, hook_providers_js_1.unsafeProvider)(def)) {
+            throw new hook_program_js_1.HookCompileError(`provider ${file} ("${def.run}") is not provably read-only — ` +
+                `pass dangerous:true to defineProvider to acknowledge it.`);
+        }
+        names.push(def.name);
+    }
+    return names;
+}
+/** Path of the tamper-evident stamp sidecar for a hook file. */
+function hookStampPath(file) {
+    return (0, node_path_1.resolve)(process.cwd(), ".vigiles/hooks", (0, node_path_1.basename)(file) + ".json");
+}
+/**
+ * Compile ONE typed hook program (authored against `vigiles/hook`) and MERGE it
+ * into the active harness's native config — the hook half of `vigiles compile`
+ * (there is no `compile-hook` verb; the cohesive-cli-surface rule). An import
+ * outside the sanctioned API does NOT compile (capability = API surface). The
+ * emitted block routes the live event to `hook-runtime run-program`; a
+ * tamper-evident stamp sidecar lets the runtime refuse a hand-edited artifact.
+ * The merge is idempotent (keyed by the hook PATH), so recompiling updates in
+ * place and never clobbers the user's own hooks.
+ */
+async function installHookFile(file, adapter, registeredProviders = []) {
+    const source = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(process.cwd(), file), "utf-8");
+    const program = await loadHookProgram(file);
+    const compiled = (0, hook_program_js_1.compileHookProgram)(source, program, {
+        gateCommand: `npx vigiles hook-runtime run-program ${file}`,
+        dialect: adapter.dialect,
+        hookProtocol: adapter.hookProtocol,
+        settingsFormat: adapter.layout.settingsFormat,
+        registeredProviders,
+    });
+    // Tamper-evident stamp beside the source (one dir → basename is unique).
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(hookStampPath(file)), { recursive: true });
+    (0, node_fs_1.writeFileSync)(hookStampPath(file), JSON.stringify({ file, stamp: compiled.stamp }, null, 2) + "\n");
+    // Merge into the harness's native config, idempotently.
+    const format = adapter.layout.settingsFormat;
+    const settingsAbs = (0, node_path_1.resolve)(process.cwd(), adapter.layout.settingsPath);
+    const existing = (0, node_fs_1.existsSync)(settingsAbs)
+        ? format === "toml"
+            ? (0, toml_1.parse)((0, node_fs_1.readFileSync)(settingsAbs, "utf-8"))
+            : JSON.parse((0, node_fs_1.readFileSync)(settingsAbs, "utf-8"))
+        : {};
+    const merged = format === "toml"
+        ? (0, hook_install_js_1.mergeHooksToml)(existing, compiled.hooks, file)
+        : (0, hook_install_js_1.mergeHooksJson)(existing, compiled.hooks, file);
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(settingsAbs), { recursive: true });
+    (0, node_fs_1.writeFileSync)(settingsAbs, (0, hook_install_js_1.serializeConfig)(merged, format));
+    // Honest gap (no silent skips): the gate/deny path is exit-2 and cross-harness,
+    // but an inject/react hook's OUTPUT shape is confirmed only for Claude Code. On
+    // another harness it would emit CC-shaped output that may not be read — exactly
+    // the silent failure this feature exists to prevent. Flag it, loudly.
+    const role = (0, hook_program_js_1.dispatchKind)(program);
+    const warning = adapter.name !== "claude-code" && (role === "inject" || role === "react")
+        ? `${role} output is only confirmed for Claude Code. On ${adapter.name}, ` +
+            `the gate (deny→exit 2) path works, but this hook's ${role} output is ` +
+            `CC-shaped and unverified — it may silently not apply. Use a gate hook on ` +
+            `${adapter.name} for now, or confirm against the real binary first ` +
+            `(research/compiled-hooks-codex.md §Deferred).`
+        : undefined;
+    return { role, settingsPath: adapter.layout.settingsPath, warning };
+}
+/**
+ * Compile + install every hook (explicit paths, else discovered under
+ * `.vigiles/hooks/`) into the active harness's config. Returns false if any
+ * hook failed to compile.
+ */
+async function installHooks(hookFiles, harnessFlag) {
+    if (hookFiles.length === 0)
+        return true;
+    const adapter = harnessFlag
+        ? (0, adapter_registry_js_1.resolveAdapter)(process.cwd(), harnessFlag)
+        : (0, adapter_registry_js_1.detectAdapterResult)(process.cwd()).adapter;
+    // Validate registered providers first → the names a hook's provider() ref may
+    // resolve to (an unsafe provider fails the whole compile, like a bad hook).
+    let registeredProviders;
+    try {
+        registeredProviders = await compileProviders();
+    }
+    catch (e) {
+        if (e instanceof hook_program_js_1.HookCompileError) {
+            console.error(`✗ ${e.message}`);
+            return false;
+        }
+        throw e;
+    }
+    let ok = true;
+    for (const file of hookFiles) {
+        try {
+            const r = await installHookFile(file, adapter, registeredProviders);
+            console.log(`✓ ${file} → ${r.settingsPath} (role: ${r.role}, harness: ${adapter.name})`);
+            if (r.warning)
+                console.warn(`⚠ ${r.warning}`);
+        }
+        catch (e) {
+            if (e instanceof hook_program_js_1.HookCompileError) {
+                console.error(`✗ ${file} — ${e.message}`);
+                const src = (() => {
+                    try {
+                        return (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(process.cwd(), file), "utf-8");
+                    }
+                    catch {
+                        return "";
+                    }
+                })();
+                if ((0, hook_program_js_1.checkHookImports)(src).length > 0) {
+                    console.error("  A compiled hook may import ONLY `vigiles/hook` — that is its " +
+                        "entire capability surface.");
+                }
+                ok = false;
+            }
+            else {
+                throw e;
+            }
+        }
+    }
+    return ok;
+}
+/**
+ * Gather a gate's DECLARED context providers (the trusted-host I/O step). Runs
+ * each declared read-only command via execSync in the hook's cwd; a provider
+ * that can't resolve yields its default (never throws). The pure registry +
+ * decision logic live in core/hook-providers.ts — this only injects the real IO.
+ */
+async function gatherHookContext(program) {
+    const needs = (0, hook_program_js_1.hookNeeds)(program);
+    if (needs.length === 0)
+        return {};
+    // Only load the registered-provider registry if a provider() ref is declared.
+    const hasRef = needs.some((n) => typeof n !== "string" && n.kind === "provider-ref");
+    const registry = hasRef ? await loadProviderRegistry() : {};
+    const { execSync } = require("node:child_process");
+    const { isCI } = require("ci-info");
+    return (0, hook_providers_js_1.gatherContext)(needs, {
+        exec: (command) => execSync(command, {
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }),
+        cwd: process.cwd(),
+        platform: process.platform,
+        isCI,
+    }, registry);
+}
+/**
+ * Load the registered providers (`.vigiles/providers/`) into a name→def registry
+ * for `provider()` ref resolution. A bad/unloadable provider file is skipped (the
+ * ref then yields its default ""), never crashes a live session.
+ */
+async function loadProviderRegistry() {
+    const registry = {};
+    for (const file of (0, hook_install_js_1.discoverProviderFiles)(process.cwd())) {
+        try {
+            const def = await loadProvider(file);
+            registry[def.name] = def;
+        }
+        catch {
+            /* skip an unloadable provider file */
+        }
+    }
+    return registry;
+}
+/** Append an observe-mode record to `.vigiles/hook-observations.jsonl` (best-effort). */
+function recordObservation(file, on, would, reason) {
+    try {
+        const dir = (0, node_path_1.resolve)(process.cwd(), ".vigiles");
+        (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+        const line = JSON.stringify({
+            ts: new Date().toISOString(),
+            hook: file,
+            event: on,
+            would,
+            reason,
+        }) + "\n";
+        (0, node_fs_1.appendFileSync)((0, node_path_1.resolve)(dir, "hook-observations.jsonl"), line);
+    }
+    catch {
+        /* recording is best-effort — never let it break a live session */
+    }
+}
+/**
+ * Emit a gate Decision in the harness protocol — the author never writes it.
+ * `observe` mode turns a would-be block/ask into a recorded no-op (exit 0): the
+ * shadow/rollout path. Harness-neutral — exit 2 / exit 0 are identical on Claude
+ * Code and Codex; the record is vigiles-local.
+ */
+function emitGate(decision, on, mode, file) {
+    const action = (0, hook_program_js_1.gateAction)(decision, mode);
+    switch (action.kind) {
+        case "block":
+            console.error(action.reason);
+            process.exit(2);
+            return;
+        case "ask":
+            process.stdout.write(JSON.stringify({
+                hookSpecificOutput: {
+                    hookEventName: on,
+                    permissionDecision: "ask",
+                    permissionDecisionReason: action.reason,
+                },
+            }) + "\n");
+            return;
+        case "observe":
+            recordObservation(file, on, action.would, action.reason);
+            console.error(`⚠ [vigiles observe] ${on}: would ${action.would} — ${action.reason}`);
+            return; // exit 0 — observe never blocks
+        case "allow":
+            return; // emit nothing, exit 0
+    }
+}
+/**
+ * Fail closed if a stamp sidecar exists and the on-disk source no longer
+ * matches it — a hand-edit that smuggles in a capability breaks the stamp.
+ * No sidecar → run uncompiled (e.g. a test fixture or a not-yet-compiled hook).
+ */
+function verifyStampOrRefuse(file) {
+    const stampPath = hookStampPath(file);
+    if (!(0, node_fs_1.existsSync)(stampPath))
+        return;
+    try {
+        const { stamp } = JSON.parse((0, node_fs_1.readFileSync)(stampPath, "utf-8"));
+        const source = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(process.cwd(), file), "utf-8");
+        if (stamp && !(0, hook_program_js_1.verifyHookStamp)(source, stamp)) {
+            console.error(`vigiles: hook ${file} does not match its compiled stamp (tampered).`);
+            process.exit(2);
+        }
+    }
+    catch {
+        /* unreadable sidecar → don't block a live session on it */
+    }
+}
+/**
+ * `vigiles hook-runtime run-program <file>` — the runtime the compiled hooks block
+ * points at. Reads the live event on stdin, loads the typed program, verifies
+ * its stamp, and dispatches by role: a gate exits 2 + reason on `deny`; an
+ * inject prints `additionalContext`; a react runs its effect-classified
+ * command. A hook that won't load fails CLOSED (exit 2), never silent-allow.
+ */
+async function runHookProgramCommand(file) {
+    if (!file) {
+        console.error("Usage: vigiles hook-runtime run-program <hook-file>");
+        process.exit(2);
+        return;
+    }
+    let raw = "";
+    try {
+        raw = (0, node_fs_1.readFileSync)(0, "utf-8");
+    }
+    catch {
+        /* no stdin */
+    }
+    let event = {};
+    try {
+        event = JSON.parse(raw);
+    }
+    catch {
+        /* malformed → empty event */
+    }
+    let program;
+    try {
+        program = await loadHookProgram(file);
+    }
+    catch {
+        console.error(`vigiles: cannot load hook program ${file}`);
+        process.exit(2);
+        return;
+    }
+    verifyStampOrRefuse(file);
+    switch ((0, hook_program_js_1.dispatchKind)(program)) {
+        case "inject": {
+            const out = (0, hook_program_js_1.runInject)(program, { source: event.source });
+            process.stdout.write(JSON.stringify(out) + "\n");
+            return;
+        }
+        case "react": {
+            const reaction = (0, hook_program_js_1.runReact)(program, event);
+            if (reaction.kind === "run") {
+                const { spawnSync } = require("node:child_process");
+                const res = spawnSync(reaction.command, {
+                    shell: true,
+                    stdio: "inherit",
+                });
+                process.exit(res.status ?? 0);
+            }
+            if (reaction.kind === "notice")
+                console.error(reaction.message);
+            return;
+        }
+        case "file-gate": {
+            const ctx = await gatherHookContext(program);
+            emitGate((0, hook_program_js_1.decideFileGate)(program, event, ctx), program.on, (0, hook_program_js_1.hookMode)(program), file);
+            return;
+        }
+        case "bash-gate": {
+            const ctx = await gatherHookContext(program);
+            emitGate((0, hook_program_js_1.decideProgram)(program, event, ctx), program.on, (0, hook_program_js_1.hookMode)(program), file);
+            return;
+        }
+        case "prompt-gate": {
+            const ctx = await gatherHookContext(program);
+            emitGate((0, hook_program_js_1.decidePromptGate)(program, event, ctx), program.on, (0, hook_program_js_1.hookMode)(program), file);
+            return;
+        }
+        case "stop-gate": {
+            const ctx = await gatherHookContext(program);
+            emitGate((0, hook_program_js_1.decideStopGate)(program, event, ctx), program.on, (0, hook_program_js_1.hookMode)(program), file);
+            return;
+        }
+    }
+}
+/**
+ * After a single-plugin `scan` report: if the plugin ships model-invocable
+ * skills AND a real model is reachable, surface the real-model `--trigger` tier
+ * that measures whether those skills actually FIRE. A human at a TTY is offered
+ * setup; an agent / CI (non-TTY / `--json` / `--no-interactive` / `--yes`) gets a
+ * one-line, non-blocking hint — a `scan` must never hang (`great-agent-flow`).
+ */
+async function maybeSuggestTrigger(report, dir, json, args) {
+    const triggerable = report.skills.filter((s) => s.hasDescription && !s.userInvoked);
+    const decision = (0, scan_trigger_suggest_js_1.decideTriggerSuggestion)({
+        modelAccess: (0, scan_trigger_suggest_js_1.hasModelAccess)(process.env),
+        // Prompt only when BOTH streams are a terminal — `askOnce` reads stdin, so a
+        // TTY stdout with piped/redirected stdin (agents, shell pipelines) must take
+        // the non-blocking hint path, not block on a read that never gets input.
+        // `isTTY` is `undefined` at runtime when not a terminal (falsy → hint path).
+        isTTY: process.stdout.isTTY && process.stdin.isTTY,
+        triggerableSkills: triggerable.length,
+        json,
+        noInteractive: args.includes("--no-interactive") || args.includes("--yes"),
+    });
+    if (decision === "none")
+        return;
+    if (decision === "hint") {
+        console.log("\n" + (0, scan_trigger_suggest_js_1.formatTriggerHint)(dir, triggerable.length));
+        return;
+    }
+    await promptTriggerSetup(report, dir, triggerable.length, args);
+}
+/** Ask one question on a fresh readline, closing it after (the codebase pattern). */
+async function askOnce(q) {
+    const readline = await import("node:readline");
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    try {
+        return await new Promise((res) => {
+            rl.question(q, (a) => {
+                res(a.trim());
+            });
+        });
+    }
+    finally {
+        rl.close();
+    }
+}
+/** Interactive (TTY) trigger-tier setup: run an existing prompts file now, or
+ *  scaffold one to fill in. The real-model run stays an explicit confirmation so
+ *  a plain `scan` never spends a token without a yes. */
+async function promptTriggerSetup(report, dir, n, args) {
+    const promptsPath = (0, node_path_1.resolve)(process.cwd(), "trigger-prompts.json");
+    const exists = (0, node_fs_1.existsSync)(promptsPath);
+    const q = exists
+        ? `\nℹ Model access detected. Measure whether your ${String(n)} skill(s) FIRE now using trigger-prompts.json (real model)? [y/N] `
+        : `\nℹ ${String(n)} model-invocable skill(s) + model access detected. Scaffold trigger-prompts.json to measure firing? [y/N] `;
+    const answer = await askOnce(q);
+    if (!/^y(es)?$/i.test(answer)) {
+        console.log("  Skipped. " + (0, scan_trigger_suggest_js_1.formatTriggerHint)(dir, n));
+        return;
+    }
+    if (exists) {
+        await handleMeasure([dir], [...args, "--prompts=trigger-prompts.json"]);
+        return;
+    }
+    (0, node_fs_1.writeFileSync)(promptsPath, (0, scan_trigger_suggest_js_1.scaffoldTriggerPrompts)(report.skills
+        .filter((s) => s.hasDescription && !s.userInvoked)
+        .map((s) => s.name)));
+    console.log("  ✓ Wrote trigger-prompts.json — fill in the placeholders, then run:");
+    console.log(`    vigiles scan ${dir} --trigger --prompts=trigger-prompts.json`);
+}
 async function main() {
     const args = process.argv.slice(2);
     const command = args[0];
@@ -3319,7 +4117,7 @@ async function main() {
         case "init": {
             // Explicit --target bypasses the setup wizard and always creates a
             // bare spec, so `npx vigiles init --target=<file>` is a reliable
-            // remediation for the require-spec validator. Bare `vigiles init`
+            // remediation for the require-instructions-spec validator. Bare `vigiles init`
             // still runs the full wizard (project detection + auto-targets).
             const hasTarget = args.some((a) => a.startsWith("--target="));
             if (hasTarget) {
@@ -3331,14 +4129,29 @@ async function main() {
             break;
         }
         case "compile": {
-            const specs = restArgs.length > 0 ? restArgs : findSpecs();
-            if (specs.length === 0) {
-                console.log("No .spec.ts files found.");
+            const harnessFlag = harnessFlagFrom(args);
+            // One verb compiles every typed authoring artifact: a .spec.ts → markdown,
+            // a hook program → its harness config + stamp (cohesive-cli-surface). With
+            // explicit args, partition by extension; bare, discover both.
+            const specs = restArgs.length > 0
+                ? restArgs.filter((f) => f.endsWith(".spec.ts"))
+                : findSpecs();
+            const hooks = restArgs.length > 0
+                ? restArgs.filter((f) => !f.endsWith(".spec.ts"))
+                : (0, hook_install_js_1.discoverHookFiles)(process.cwd());
+            if (specs.length === 0 && hooks.length === 0) {
+                console.log("No .spec.ts or .vigiles/hooks/ hook files found.");
                 console.log("Run `vigiles init` to create one.");
                 process.exit(0);
             }
-            const harnessFlag = harnessFlagFrom(args);
-            const valid = await compile(specs, config, { harnessFlag });
+            let valid = true;
+            if (specs.length > 0)
+                valid = (await compile(specs, config, { harnessFlag })) && valid;
+            valid = (await installHooks(hooks, harnessFlag)) && valid;
+            // Keep an existing whole-harness registry in sync (cheap, opt-in) so the
+            // user never hand-runs `generate-harness`. Skipped when no harness.gen.ts.
+            if (specs.length > 0)
+                valid = (await refreshHarnessGenIfPresent(harnessFlag)) && valid;
             console.log("");
             if (valid) {
                 console.log("Compilation complete.");
@@ -3349,6 +4162,11 @@ async function main() {
             }
             break;
         }
+        case "eject":
+            // Inverse of compile: un-manage a compiled file → plain hand-owned
+            // markdown (the "always ejectable" escape hatch).
+            eject(args.slice(1));
+            break;
         case "lint": {
             // lint = verify references + discover + guidance count
             const flags = args.slice(1).filter((a) => a.startsWith("--"));
@@ -3367,13 +4185,24 @@ async function main() {
             handleRunScripts("eval", args, restArgs);
             break;
         case "scan": {
+            // Model-gated behavioral column + the deterministic diagnostic, folded into
+            // scan (formerly the `measure` / `explain` verbs): `--trigger` measures
+            // whether each skill FIRES / COLLIDES (real model), `--explain` is the
+            // free WHY-a-surface-underperforms + the fix.
+            if (args.includes("--trigger")) {
+                await handleMeasure(restArgs, args);
+                break;
+            }
+            if (args.includes("--explain")) {
+                handleExplain(restArgs, args);
+                break;
+            }
             const dirs = restArgs.length > 0 ? restArgs : ["."];
             const json = args.includes("--json");
             // A single dir that's a marketplace (e.g. wshobson/agents' 80+ plugins
             // under one marketplace.json) expands into its members and ranks them.
             const market = dirs.length === 1 ? (0, scan_js_1.inspectMarketplace)((0, node_path_1.resolve)(dirs[0])) : null;
             const targets = market && market.onDisk.length > 0 ? [...market.onDisk] : dirs;
-            const wantTrigger = args.includes("--trigger");
             if (market && market.onDisk.length === 0 && market.total > 0) {
                 // A CURATED marketplace — every member is an external git/url plugin, so
                 // there's nothing on disk to scan. Say so honestly instead of falling
@@ -3390,12 +4219,13 @@ async function main() {
                 }
             }
             else if (targets.length > 1) {
-                // Multiple targets → rank them (the leaderboard engine).
+                // Multiple targets → rank them (the leaderboard engine). `--md` emits the
+                // publishable Markdown table (a README / gist / the leaderboard site).
                 const scores = (0, leaderboard_js_1.rankPlugins)(targets);
-                console.log(json ? JSON.stringify(scores, null, 2) : (0, leaderboard_js_1.formatLeaderboard)(scores));
-                if (wantTrigger) {
-                    console.log("\n⚠ --trigger (behavioral column) runs per single plugin; not yet wired into the leaderboard. Scan one plugin dir to probe it.");
-                }
+                const text = args.includes("--md")
+                    ? (0, leaderboard_js_1.formatLeaderboardMarkdown)(scores)
+                    : (0, leaderboard_js_1.formatLeaderboard)(scores);
+                console.log(json ? JSON.stringify(scores, null, 2) : text);
             }
             else {
                 const root = (0, node_path_1.resolve)(targets[0]);
@@ -3410,6 +4240,13 @@ async function main() {
                     if (!harnessFlag && det.ambiguousWith.length > 0) {
                         console.log(`⚠ repo also matches: ${det.ambiguousWith.join(", ")} — override with --harness=<name>`);
                     }
+                    // Freshness: warn if our hand-maintained CC catalog drifted from the
+                    // user's INSTALLED claude-code (read-local, best-effort, never throws).
+                    if (adapter.name === "claude-code") {
+                        const drift = (0, dialect_drift_js_1.formatDialectDrift)((0, dialect_drift_js_1.checkDialectDrift)());
+                        if (drift)
+                            console.log(drift);
+                    }
                     console.log("");
                 }
                 if (args.includes("--fix-plan")) {
@@ -3421,32 +4258,48 @@ async function main() {
                 else {
                     console.log(json ? JSON.stringify(report, null, 2) : (0, scan_js_1.formatScanReport)(report));
                 }
-                if (wantTrigger) {
-                    const harness = adapter.name === "codex" ? "codex" : "claude-code";
-                    await handleScanTrigger(root, args, json, harness);
+                if (args.includes("--verify-mcp")) {
+                    // Opt-in LIVE MCP tool resolution: starts each declared server and checks
+                    // the agent's mcp__server__tool refs actually exist (the dynamic check no
+                    // static linter can do). Side-effecting (spawns servers) → opt-in only.
+                    const mcpErrs = await (0, scan_js_1.verifyLiveMcpTools)(report, adapter.layout, adapter.dialect);
+                    console.log(json
+                        ? JSON.stringify({ mcpContractTools: mcpErrs }, null, 2)
+                        : "\n" + (0, scan_js_1.formatMcpContractReport)(mcpErrs));
+                }
+                const capBase = flagValue(args, "--capability-diff");
+                if (capBase) {
+                    // Did this version WIDEN the agent's blast radius vs <before>? Diffs the
+                    // two whole-harness capability lattices (moat #2). Informational by
+                    // default; `--fail-on-widen` exits non-zero (the opt-in CI gate).
+                    const beforeReport = (0, scan_js_1.scanPlugin)((0, node_path_1.resolve)(capBase), adapter.layout, adapter.dialect);
+                    const diff = (0, capability_diff_js_1.diffCapabilities)(capabilitiesOfReport(beforeReport, adapter.dialect), capabilitiesOfReport(report, adapter.dialect));
+                    console.log(json
+                        ? JSON.stringify({ capabilityDiff: diff }, null, 2)
+                        : "\n" + (0, capability_diff_js_1.formatCapabilityDiff)(diff));
+                    if (args.includes("--fail-on-widen") && diff.widened)
+                        process.exitCode = 1;
                 }
+                // Nudge toward the real-model trigger tier when a model is reachable and
+                // the plugin ships model-invocable skills (hint for agents, offer for humans).
+                await maybeSuggestTrigger(report, targets[0], json, args);
             }
             break;
         }
-        case "explain":
-            handleExplain(restArgs, args);
-            break;
         case "scaffold-test":
             handleScaffoldTest(restArgs, args);
             break;
         // --- Plumbing ---
-        case "generate-types":
-            handleGenerateTypes(args, restArgs);
-            break;
-        case "generate-schema":
-            handleGenerateSchema(args, restArgs);
+        case "generate":
+            await handleGenerate(restArgs, args);
             break;
-        case "generate-harness":
-            await handleGenerateHarness(args, restArgs);
+        // Hidden umbrella for runtime entrypoints emitted into hooks configs — never
+        // typed by a human. See handleHookRuntime / the cohesive-cli-surface rule.
+        case "hook-runtime":
+            await handleHookRuntime(restArgs[0], restArgs.slice(1));
             break;
         default:
-            if (!handleSkillCommand(command, restArgs))
-                printUsage(command);
+            printUsage(command);
             break;
     }
 }