vigiles 7.0.0 → 9.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,13 +24,18 @@ 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");
 const skill_harness_js_1 = require("./skill-harness.js");
 const leaderboard_js_1 = require("./leaderboard.js");
 const optimize_js_1 = require("./optimize.js");
+const audit_score_js_1 = require("./audit-score.js");
+const audit_prompts_js_1 = require("./audit-prompts.js");
+const audit_html_js_1 = require("./audit-html.js");
+const audit_report_js_1 = require("./audit-report.js");
+const adoptability_js_1 = require("./adoptability.js");
 const compile_js_1 = require("./core/compile.js");
 const proofs_js_1 = require("./core/proofs.js");
 const inline_js_1 = require("./core/inline.js");
@@ -54,6 +59,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 +453,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 +482,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 +664,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 +990,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 +1058,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,
@@ -1198,14 +1210,40 @@ function targetHasHash(absPath) {
         return false;
     }
 }
-function init(args) {
+/**
+ * Single-target spec scaffolder — the small building block behind the `init`
+ * verb, NOT the wizard. Creates exactly one sibling `<target>.spec.ts`: it
+ * faithfully ADOPTS an existing hand-written instruction file (non-destructive —
+ * never overwrites the markdown) or writes a blank starter for a greenfield
+ * target. Called directly for `vigiles init --target=<file>`, and once per
+ * target by `setupPillar1`. The full onboarding (both layers, deps, CI, plugin)
+ * is `setup()`.
+ */
+function scaffoldSpec(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 +1290,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
 // ---------------------------------------------------------------------------
@@ -1315,7 +1467,7 @@ function workflowUsesStaleApi(content) {
         return false; // uses the Action — fine
     if (!/\bvigiles\b/.test(content))
         return false; // not a vigiles workflow
-    const hasModernCmd = /vigiles\s+(lint|test|eval|compile|scan|generate-types|generate-schema|init)\b/.test(content);
+    const hasModernCmd = /vigiles\s+(lint|test|eval|compile|audit|generate-types|generate-schema|init)\b/.test(content);
     return !hasModernCmd;
 }
 /**
@@ -1326,7 +1478,7 @@ function workflowUsesStaleApi(content) {
  * the bare-API heuristic above, which an Action reference short-circuits.
  */
 const REMOVED_SUBCOMMANDS = {
-    audit: "lint", // v3 → v4 rename
+    scan: "audit", // renamed: the Lighthouse report verb is `audit`
 };
 /** The first removed/renamed `vigiles <sub>` a workflow still calls, if any. */
 function workflowRemovedSubcommand(content) {
@@ -1336,7 +1488,7 @@ function workflowRemovedSubcommand(content) {
     }
     return null;
 }
-/** Rewrite removed/renamed `vigiles <sub>` invocations in place (audit → lint).
+/** Rewrite removed/renamed `vigiles <sub>` invocations in place (scan → audit).
  * Surgical — preserves the rest of the user's workflow. */
 function rewriteRemovedSubcommands(content) {
     let out = content;
@@ -1436,7 +1588,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 +1601,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 +1764,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 (scaffoldSpec() 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 …"
+            scaffoldSpec(["--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 +1813,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 +2017,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 +2060,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 +2081,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 +2117,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 +2153,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 +2386,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 +2691,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
- * 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
+ * The MODEL-GATED behavioral half of `vigiles audit` (the model trigger tier; the
+ * deterministic core of `audit` stays free). 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 audit ./plugin --prompts=p.json` (interactive — say yes when asked).
  */
 async function handleMeasure(restArgs, args) {
     const dir = (0, node_path_1.resolve)(restArgs[0] ?? ".");
@@ -2529,6 +2782,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 +2830,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 +2845,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 +2872,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 +2880,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 +2895,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 +2973,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 +2987,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;
@@ -2753,32 +3064,6 @@ function harnessFlagFrom(argv) {
         .find((a) => a.startsWith("--harness="))
         ?.slice("--harness=".length);
 }
-/**
- * `vigiles explain <dir> [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
- * optimizer's call). `--json` for the agent-consumable shape, `--harness=` to
- * override detection.
- */
-function handleExplain(restArgs, args) {
-    const dir = (0, node_path_1.resolve)(restArgs[0] ?? ".");
-    const surface = restArgs[1];
-    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 report = (0, scan_js_1.scanPlugin)(dir, adapter.layout, adapter.dialect);
-    const exps = surface ? (0, score_explainer_js_1.explainSurface)(report, surface) : (0, score_explainer_js_1.explainScore)(report);
-    if (json) {
-        console.log(JSON.stringify(exps, null, 2));
-        return;
-    }
-    if (surface)
-        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
@@ -2925,14 +3210,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("  vigiles audit [dir...]          Lighthouse for your harness — a LOCAL report: rings + what's broken + fixes (a deterministic read; 2+ dirs → leaderboard)");
+    console.log("                                 writes vigiles-report.html + vigiles-report.json (--no-html/--no-json) · --json for machine output. NOT a CI step — use `vigiles lint` in CI.");
+    console.log("                                 the executing checks (run your hooks · live MCP · do skills fire?) run only interactively — `audit` asks once (remembered); automation uses the vigiles/testing API");
     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 +3227,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 +3580,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 +4016,223 @@ async function runHookProgramCommand(file) {
         }
     }
 }
+/**
+ * Write the versioned JSON artifact (`vigiles-report.json`) — the upload/CI
+ * boundary a hosted dashboard ingests. Stamps `meta.generatedAt` here (at write
+ * time, not in the pure builder, so the HTML-embedded form stays deterministic).
+ */
+function writeAuditJson(report) {
+    const jsonPath = (0, node_path_1.resolve)(process.cwd(), "vigiles-report.json");
+    const stamped = {
+        ...report,
+        meta: { ...report.meta, generatedAt: new Date().toISOString() },
+    };
+    try {
+        (0, node_fs_1.writeFileSync)(jsonPath, JSON.stringify(stamped, null, 2) + "\n");
+        console.log("✓ Wrote vigiles-report.json — the upload/CI artifact");
+    }
+    catch (e) {
+        console.log(`\n⚠ could not write vigiles-report.json: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+/** Best-effort open the report in the default browser (TTY-only caller). */
+function openBestEffort(file) {
+    const cmd = process.platform === "darwin"
+        ? "open"
+        : process.platform === "win32"
+            ? "start"
+            : "xdg-open";
+    void import("node:child_process")
+        .then(({ spawn }) => {
+        const child = spawn(cmd, [file], {
+            stdio: "ignore",
+            detached: true,
+            shell: process.platform === "win32",
+        });
+        child.on("error", () => undefined);
+        child.unref();
+    })
+        .catch(() => undefined);
+}
+/**
+ * Write the self-contained HTML audit report to `vigiles-report.html` (cwd) and,
+ * for a human at a TTY, open it best-effort. The shareable Lighthouse artifact;
+ * never spawns a browser for an agent / CI run.
+ */
+function writeAuditHtml(report) {
+    const htmlPath = (0, node_path_1.resolve)(process.cwd(), "vigiles-report.html");
+    try {
+        (0, node_fs_1.writeFileSync)(htmlPath, (0, audit_html_js_1.renderAuditHtml)(report));
+        console.log("\n✓ Wrote vigiles-report.html — open it for the full report");
+        if (process.stdout.isTTY)
+            openBestEffort(htmlPath);
+    }
+    catch (e) {
+        // No template (unbuilt checkout) or a write error — skip the HTML; the JSON
+        // artifact + terminal report don't depend on it.
+        console.log(`\n⚠ skipped vigiles-report.html: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+/**
+ * Run the model trigger tier with no `--prompts`: auto-generate diverse probe
+ * prompts from each skill's description and measure trigger-rate (recall +
+ * precision) — zero-setup. `--prompts=<file>` (handled by handleMeasure)
+ * overrides for a curated benchmark + the collision matrix. Model-gated: the
+ * probes are deterministic, but RUNNING them needs the harness CLI + model auth
+ * (degrades to "unavailable" otherwise).
+ */
+async function runAutoTrigger(dir, report, adapter, args) {
+    const json = args.includes("--json");
+    const harness = adapter.name === "codex" ? "codex" : "claude-code";
+    const skills = report.skills
+        .filter((s) => s.hasDescription && !s.userInvoked && s.description)
+        .map((s) => ({ name: s.name, description: s.description ?? "" }));
+    if (skills.length === 0) {
+        if (!json) {
+            console.log("\nℹ no model-invocable skills with a description to measure.");
+        }
+        return;
+    }
+    const promptSet = (0, audit_prompts_js_1.autoTriggerPrompts)(skills);
+    if (!json) {
+        console.log("\nℹ auto-generated probe prompts from skill descriptions (pass --prompts=<file> for a curated set).");
+    }
+    const trigger = await (0, scan_behavioral_js_1.probePluginTriggers)(dir, promptSet, {
+        minPrompts: audit_prompts_js_1.AUTO_RECALL_COUNT,
+        minDistance: audit_prompts_js_1.AUTO_MIN_DISTANCE,
+        model: flagValue(args, "--model"),
+        harness,
+        // Discover candidates with the resolved adapter's layout/dialect — a Codex
+        // repo's skills live under the Codex layout, not the default CC one.
+        layout: adapter.layout,
+        dialect: adapter.dialect,
+    });
+    console.log(json
+        ? JSON.stringify({ trigger }, null, 2)
+        : "\n" + (0, scan_behavioral_js_1.formatBehavioralReport)(trigger));
+}
+/**
+ * The ONE read-vs-run decision for a single-plugin `audit`. A plain `audit` is a
+ * deterministic READ; the executing checks are opt-in via a single consent —
+ * `decideExecute` resolves it (run / ask / skip). At a TTY we ASK ONCE (bundled,
+ * with a confinement + cost DISCLOSURE) and remember the answer in `.vigilesrc.json`;
+ * headless we stay a read (the `note` is the loud nudge, printed by the caller
+ * AFTER the report). Never hangs an agent / CI run (`great-agent-flow`).
+ *
+ * Returns `execute` (run the executing checks?) + a `note` to print at the end.
+ */
+async function resolveExecution(s, json, args, harness) {
+    const decision = (0, scan_trigger_suggest_js_1.decideExecute)({
+        hasExecutable: s.hasMcp || s.triggerableSkills > 0 || s.adoptableRefs,
+        // A human is "interactive" only when BOTH streams are a terminal — `askOnce`
+        // reads stdin, so a TTY stdout with piped/redirected stdin (agents, shell
+        // pipelines) must NOT block on a read that never gets input.
+        isTTY: process.stdout.isTTY && process.stdin.isTTY,
+        json,
+        noInteractive: args.includes("--no-interactive") || args.includes("--yes"),
+        remembered: (0, validate_js_1.loadConfig)().audit?.measure,
+    });
+    if (decision.kind === "run")
+        return { execute: true, note: null };
+    if (decision.kind === "skip")
+        return {
+            execute: false,
+            note: json ? null : (0, scan_trigger_suggest_js_1.formatExecuteSkip)(decision.reason),
+        };
+    // ask — prompt once, then remember the answer.
+    const answer = await askOnce(buildExecuteDisclosure(s, harness));
+    const yes = /^y(es)?$/i.test(answer); // default NO (executes your hooks / servers)
+    rememberAuditMeasure(yes);
+    return {
+        execute: yes,
+        note: yes
+            ? null
+            : "  Skipped (remembered — edit .vigilesrc.json `audit.measure` to change).",
+    };
+}
+/** The bundled consent prompt — discloses exactly what will execute (and what it
+ *  costs) so the yes is informed. Default NO. Harness-aware: a Codex repo measures
+ *  via the codex CLI (not a Claude env var), so the cost wording must not falsely
+ *  read "no model access" in exactly the case the prompt is meant to disclose. */
+function buildExecuteDisclosure(s, harness) {
+    const lines = ["\nRun the executing checks against your harness?"];
+    if (s.hasMcp)
+        lines.push("  · start your MCP servers — connects to their backends");
+    if (s.triggerableSkills > 0) {
+        lines.push(`  · measure whether skills fire (${triggerCostWording(harness)})`);
+    }
+    if (s.adoptableRefs) {
+        lines.push(`  · draft + verify your instruction file's references (${triggerCostWording(harness)})`);
+    }
+    lines.push("Asked once — remembered in .vigilesrc.json. [y/N] ");
+    return lines.join("\n");
+}
+/** Cost/availability wording for the trigger tier, per harness. Codex runs on the
+ *  codex CLI (its own auth/plan), so it's never gated on a Claude env var. */
+function triggerCostWording(harness) {
+    if (harness === "codex")
+        return "your Codex CLI, $0 metered — skips if `codex` isn't on PATH";
+    return !(0, scan_trigger_suggest_js_1.hasModelAccess)(process.env)
+        ? "needs model access — none detected, will skip"
+        : (0, scan_trigger_suggest_js_1.isMeteredAccess)(process.env)
+            ? "⚠ spends API credits"
+            : "your subscription, $0 metered";
+}
+/** Run the trigger tier: a curated `--prompts` file, else auto-generated probes. */
+async function runTriggerTier(dir, report, adapter, args) {
+    if (flagValue(args, "--prompts")) {
+        await handleMeasure([dir], args);
+    }
+    else {
+        await runAutoTrigger(dir, report, adapter, 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();
+    }
+}
+/**
+ * Persist the audit consent (`audit.measure`) into `.vigilesrc.json` without
+ * clobbering existing keys — the "ask once, remember" sticky choice. Best-effort:
+ * a malformed user config is left untouched, a write error is non-fatal (the
+ * measurement already ran / was skipped; only the memory is lost).
+ */
+function rememberAuditMeasure(value) {
+    const configPath = (0, node_path_1.resolve)(process.cwd(), ".vigilesrc.json");
+    let existing = {};
+    if ((0, node_fs_1.existsSync)(configPath)) {
+        try {
+            existing = JSON.parse((0, node_fs_1.readFileSync)(configPath, "utf-8"));
+        }
+        catch {
+            return; // user-owned malformed config — never clobber it
+        }
+    }
+    const prevAudit = typeof existing.audit === "object" && existing.audit !== null
+        ? existing.audit
+        : {};
+    const merged = { ...existing, audit: { ...prevAudit, measure: value } };
+    try {
+        (0, node_fs_1.writeFileSync)(configPath, JSON.stringify(merged, null, 2) + "\n");
+    }
+    catch {
+        /* non-fatal — the run already happened; only the remembered choice is lost */
+    }
+}
 async function main() {
     const args = process.argv.slice(2);
     const command = args[0];
@@ -3786,11 +4251,11 @@ 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) {
-                init(args.slice(1));
+                scaffoldSpec(args.slice(1));
             }
             else {
                 await setup(args);
@@ -3817,6 +4282,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 +4296,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("--"));
@@ -3844,7 +4318,15 @@ async function main() {
         case "eval":
             handleRunScripts("eval", args, restArgs);
             break;
-        case "scan": {
+        case "audit": {
+            // The Lighthouse run: a plain `audit` is a deterministic READ — rings, each
+            // finding's fix inline, HTML/JSON report — safe + identical on every OS,
+            // nothing executes. Like Lighthouse it's a LOCAL report, NOT a CI step (CI
+            // uses `vigiles lint`). The executing checks (safety battery + live MCP +
+            // skill firing) run only on consent: at a TTY `audit` asks once (remembered
+            // in `.vigilesrc.json`), headless it stays a read + a one-line nudge. There
+            // is NO execution flag — automation tests the harness via the vigiles/testing
+            // API + skills, not the report verb. See the `audit-side-effect-free` rule.
             const dirs = restArgs.length > 0 ? restArgs : ["."];
             const json = args.includes("--json");
             // A single dir that's a marketplace (e.g. wshobson/agents' 80+ plugins
@@ -3897,19 +4379,51 @@ async function main() {
                     }
                     console.log("");
                 }
-                if (args.includes("--fix-plan")) {
-                    // The deterministic optimization lens on the SAME report: health score
-                    // + the ranked free fixes to clear before measuring (the A2 spine).
-                    const plan = (0, optimize_js_1.optimize)(report);
-                    console.log(json ? JSON.stringify(plan, null, 2) : (0, optimize_js_1.formatOptimize)(plan));
+                // The versioned AuditReport is the product boundary — the same JSON the
+                // HTML renders, `--json` emits, and (later) a hosted dashboard ingests.
+                // Built ONCE; the rings + fix list are read off it. Pure deterministic —
+                // nothing executes to produce it.
+                const auditReport = (0, audit_report_js_1.buildAuditReport)(report, {
+                    harness: adapter.name,
+                    vigilesVersion: getVersion(),
+                });
+                const sc = auditReport.score;
+                const plan = (0, optimize_js_1.optimize)(report);
+                if (!json) {
+                    // The Lighthouse rings: per-category 0–100 + the weighted overall,
+                    // shown before the detailed report so the headline signal leads.
+                    console.log((0, audit_score_js_1.formatAuditScore)(sc));
+                    console.log("");
                 }
-                else {
-                    console.log(json ? JSON.stringify(report, null, 2) : (0, scan_js_1.formatScanReport)(report));
+                console.log(json
+                    ? JSON.stringify(auditReport, null, 2)
+                    : (0, scan_js_1.formatScanReport)(report));
+                if (!json) {
+                    // Fold each finding's fix inline (replaces the former --fix-plan/--explain
+                    // flags): the deterministic, free recommendation list under the report.
+                    const fixes = (0, optimize_js_1.formatRecommendations)(plan);
+                    if (fixes)
+                        console.log("\n" + fixes);
                 }
-                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.
+                // ONE read-vs-run decision for the EXECUTING checks (live MCP + skill
+                // firing). A plain `audit` is a deterministic READ; these run only on
+                // consent — ASK once at a TTY (remembered); headless stays a read + a
+                // nudge (no execution flag — automation uses the vigiles/testing API).
+                // (The safety battery is NOT here — it needs cross-platform confinement
+                // that isn't shipped, so it lives in the vigiles/testing API.)
+                const isForeign = root !== process.cwd();
+                const surfaces = {
+                    hasMcp: report.mcp && !isForeign,
+                    triggerableSkills: report.skills.filter((s) => s.hasDescription && !s.userInvoked).length,
+                    adoptableRefs: adapter.name === "claude-code" &&
+                        (0, node_fs_1.existsSync)((0, node_path_1.resolve)(root, adapter.layout.instructionFile)),
+                };
+                const { execute, note: execNote } = await resolveExecution(surfaces, json, args, adapter.name);
+                // LIVE MCP tool resolution STARTS each declared MCP server — a server is
+                // exactly what connects to a real Postgres / authenticates a real API on
+                // boot. So it runs only under consent (`execute`) AND own-repo (never
+                // spawn a stranger's server).
+                if (execute && surfaces.hasMcp) {
                     const mcpErrs = await (0, scan_js_1.verifyLiveMcpTools)(report, adapter.layout, adapter.dialect);
                     console.log(json
                         ? JSON.stringify({ mcpContractTools: mcpErrs }, null, 2)
@@ -3928,30 +4442,85 @@ async function main() {
                     if (args.includes("--fail-on-widen") && diff.widened)
                         process.exitCode = 1;
                 }
+                // The model trigger tier — "do your skills actually FIRE?" — runs as part
+                // of the same consent (`execute`), and only when a model is reachable;
+                // otherwise it's a one-line note (never a hang).
+                if (execute && surfaces.triggerableSkills > 0) {
+                    // Model-access detection is per-harness: `hasModelAccess` reads Claude
+                    // env (claude CLI / ANTHROPIC_API_KEY). A Codex repo authenticates the
+                    // codex CLI instead, so we DON'T gate it on a Claude var — the Codex
+                    // probe checks `codexDriver.available()` internally and self-reports
+                    // unavailable. (harness-parity: never block Codex behind a CC check.)
+                    const modelReachable = adapter.name === "codex" || (0, scan_trigger_suggest_js_1.hasModelAccess)(process.env);
+                    if (modelReachable) {
+                        await runTriggerTier(targets[0], report, adapter, args);
+                    }
+                    else if (!json) {
+                        console.log("\nℹ skill firing not measured — no model access (authenticate the `claude` CLI or set ANTHROPIC_API_KEY).");
+                    }
+                }
+                // The adoption preview — "what would vigiles catch in YOUR repo?" The model
+                // DRAFTS the verifiable refs in the instruction file; the cross-ref engine
+                // VERIFIES each, so "M broken right now" is trustworthy though the extraction
+                // is probabilistic. Same consent as the trigger tier (`surfaces.adoptableRefs`
+                // makes a bare instruction-file repo consent-eligible — the prime adoption
+                // target). v1: instruction-file only; drafting drives the `claude` CLI, so
+                // `adoptableRefs` is Claude Code only (the Codex deferral note is printed
+                // below as a LOUD harness-parity deferral, never a silent CC-only path).
+                let adoptabilityResult;
+                if (execute && surfaces.adoptableRefs) {
+                    if ((0, scan_trigger_suggest_js_1.hasModelAccess)(process.env)) {
+                        const instrPath = (0, node_path_1.resolve)(root, adapter.layout.instructionFile);
+                        adoptabilityResult = await (0, adoptability_js_1.runAdoptabilityTier)({
+                            instructionContent: (0, node_fs_1.readFileSync)(instrPath, "utf-8"),
+                            basePath: root,
+                        });
+                        if (!json)
+                            console.log("\n" +
+                                (0, adoptability_js_1.formatAdoptability)(adoptabilityResult, adapter.layout.instructionFile));
+                    }
+                    else if (!json && surfaces.triggerableSkills === 0) {
+                        // Only when the trigger tier didn't already print the same note.
+                        console.log("\nℹ adoptability not measured — no model access (authenticate the `claude` CLI or set ANTHROPIC_API_KEY).");
+                    }
+                }
+                // LOUD harness-parity deferral: adoptability drafting drives the `claude`
+                // CLI, so a Codex repo with an instruction file is told it's a follow-up,
+                // never silently skipped (research/adoption-gateway-preview.md, increment 4).
+                if (!json &&
+                    adapter.name === "codex" &&
+                    (0, node_fs_1.existsSync)((0, node_path_1.resolve)(root, adapter.layout.instructionFile))) {
+                    console.log("\nℹ adoptability preview (what vigiles would catch in your repo) is Claude Code only for now — Codex support is a follow-up.");
+                }
+                // The loud read-vs-run nudge for a headless / remembered-no skip — printed
+                // AFTER the report so the deterministic read leads.
+                if (execNote)
+                    console.log(execNote);
+                // The final report folds in the adoptability preview (when the model-gated
+                // tier ran) so the written HTML/JSON carry it; a deterministic read omits it.
+                const finalReport = adoptabilityResult
+                    ? { ...auditReport, adoptability: adoptabilityResult }
+                    : auditReport;
+                // The shareable HTML report — written by default (--no-html to skip), and
+                // opened best-effort only for a human at a TTY (never spawn a browser for
+                // an agent / CI run).
+                if (!json && !args.includes("--no-html")) {
+                    writeAuditHtml(finalReport);
+                }
+                // The versioned JSON artifact — the upload/CI boundary (a hosted dashboard
+                // ingests this). Written by default in the human path; --no-json to skip.
+                if (!json && !args.includes("--no-json")) {
+                    writeAuditJson(finalReport);
+                }
             }
             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.