vigiles 7.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");
@@ -24,6 +24,7 @@ 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");
@@ -54,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");
@@ -447,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;
@@ -476,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,
     };
 }
@@ -658,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;
@@ -983,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
@@ -1048,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,
@@ -1202,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
@@ -1252,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
 // ---------------------------------------------------------------------------
@@ -1436,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({
@@ -1448,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();
@@ -1620,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.
@@ -1666,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) {
@@ -1828,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}`);
@@ -1858,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(" + ");
@@ -1876,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.
@@ -1912,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) {
@@ -1941,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;
@@ -2172,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`.
@@ -2449,34 +2678,45 @@ async function countGuidanceRules(silent = false) {
 // Command handlers for main()
 // ---------------------------------------------------------------------------
 function findInstructionFiles(restArgs, exclude = []) {
-    if (restArgs.length > 0)
-        return restArgs;
     const patterns = ["**/CLAUDE.md", "**/AGENTS.md", "**/SKILL.md"];
-    const files = [];
-    for (const pattern of patterns) {
-        files.push(...(0, glob_1.globSync)(pattern, {
-            // `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-spec. node_modules/dist/.git stay always-excluded.
-            ignore: [...IGNORE_NODE_MODULES, "dist/**", ".git/**", ...exclude],
-            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);
 }
 /**
- * `vigiles measure <dir>` — the MODEL-GATED behavioral report on a plugin (the paid
+ * `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 measure ./plugin --prompts=p.json`.
+ * `vigiles scan ./plugin --trigger --prompts=p.json`.
  */
 async function handleMeasure(restArgs, args) {
     const dir = (0, node_path_1.resolve)(restArgs[0] ?? ".");
@@ -2529,6 +2769,31 @@ async function handleMeasure(restArgs, args) {
     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");
     const outPath = restArgs[0] ?? ".vigiles/generated.d.ts";
@@ -2552,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");
@@ -2567,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;
@@ -2594,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");
@@ -2602,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;
@@ -2617,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] ?? ".");
@@ -2662,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");
@@ -2676,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;
@@ -2754,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
@@ -2925,14 +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("  vigiles measure <dir>          Model-gated: does each skill FIRE / COLLIDE? (--prompts=, real model)");
+    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:");
@@ -2941,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}"`);
@@ -3298,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
@@ -3768,6 +4029,76 @@ async function runHookProgramCommand(file) {
         }
     }
 }
+/**
+ * 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];
@@ -3786,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) {
@@ -3817,6 +4148,10 @@ async function main() {
             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.");
@@ -3827,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("--"));
@@ -3845,6 +4185,18 @@ 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
@@ -3928,30 +4280,18 @@ async function main() {
                     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;
-        case "measure":
-            await handleMeasure(restArgs, args);
-            break;
         // --- Plumbing ---
-        case "generate-types":
-            handleGenerateTypes(args, restArgs);
-            break;
-        case "generate-schema":
-            handleGenerateSchema(args, restArgs);
-            break;
-        case "generate-harness":
-            await handleGenerateHarness(args, restArgs);
-            break;
-        case "refs":
-            refsCommand(restArgs[0]);
+        case "generate":
+            await handleGenerate(restArgs, args);
             break;
         // Hidden umbrella for runtime entrypoints emitted into hooks configs — never
         // typed by a human. See handleHookRuntime / the cohesive-cli-surface rule.