vigiles 8.0.0 → 9.1.0

package/dist/cli.js

@@ -26,12 +26,16 @@ 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");
@@ -1206,7 +1210,110 @@ 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()`.
+ */
+/** Classify an adoption target by its path: a `SKILL.md` is a skill, a file under
+ * an `agents/` dir is a subagent, everything else is an instruction file. Used to
+ * pick the right adopt function so `init --target=skills/x/SKILL.md` (the
+ * per-surface path the audit report points at) makes a `skill()`/`agent()` spec. */
+function surfaceKind(target) {
+    if (/^SKILL\.md$/i.test((0, node_path_1.basename)(target)))
+        return "skill";
+    if (/(^|[/\\])agents[/\\]/.test(target))
+        return "agent";
+    return "instruction";
+}
+function logAdoptedSurface(target, specPath, label, unmappedKeys) {
+    const note = unmappedKeys.length > 0
+        ? ` (review the // NOTE — unmapped frontmatter: ${unmappedKeys.join(", ")})`
+        : "";
+    console.log(`Adopted ${label} ${target} → ${specPath}${note}. ` +
+        `Run \`vigiles compile\` and review the diff.`);
+}
+/** Discover existing skill (`skills/<x>/SKILL.md`) and subagent (`agents/<x>.md`)
+ * surfaces — under the bare or `.claude/` roots — that don't yet have a spec, so
+ * bare `vigiles init` creates a spec for EVERY surface it can, not just the
+ * instruction file. Shallow (top-level only) so it never walks node_modules or a
+ * vendored plugin. CC paths are intentional here — `init` is the one composition
+ * point allowed to know them (see adapter-aware-lint-rules). */
+function discoverAdoptableSurfaces(cwd) {
+    const out = [];
+    const unspecced = (rel) => (0, node_fs_1.existsSync)((0, node_path_1.resolve)(cwd, rel)) &&
+        !(0, node_fs_1.existsSync)((0, node_path_1.resolve)(cwd, `${rel}.spec.ts`));
+    for (const root of ["skills", ".claude/skills"]) {
+        const abs = (0, node_path_1.resolve)(cwd, root);
+        if (!(0, node_fs_1.existsSync)(abs))
+            continue;
+        for (const e of (0, node_fs_1.readdirSync)(abs, { withFileTypes: true })) {
+            const rel = `${root}/${e.name}/SKILL.md`;
+            if (e.isDirectory() && unspecced(rel))
+                out.push(rel);
+        }
+    }
+    for (const root of ["agents", ".claude/agents"]) {
+        const abs = (0, node_path_1.resolve)(cwd, root);
+        if (!(0, node_fs_1.existsSync)(abs))
+            continue;
+        for (const e of (0, node_fs_1.readdirSync)(abs, { withFileTypes: true })) {
+            const rel = `${root}/${e.name}`;
+            if (e.isFile() && e.name.endsWith(".md") && unspecced(rel))
+                out.push(rel);
+        }
+    }
+    return out;
+}
+/** The full adoptable-surface list `audit` reports: the instruction file (when it
+ * exists hand-written, no spec) PLUS every skill/subagent surface without a spec.
+ * Same notion `init` adopts; surfaced in the AuditReport + the terminal nudge so
+ * the report's "Create spec" / "Create all specs" affordances have their paths.
+ * Composition-root only — CC paths are intentional here (like discoverAdoptableSurfaces). */
+function discoverAdoptableForAudit(root, instructionFile) {
+    const out = [];
+    const instrAbs = (0, node_path_1.resolve)(root, instructionFile);
+    if ((0, node_fs_1.existsSync)(instrAbs) &&
+        !targetHasHash(instrAbs) &&
+        !(0, node_fs_1.existsSync)((0, node_path_1.resolve)(root, `${instructionFile}.spec.ts`))) {
+        out.push(instructionFile);
+    }
+    out.push(...discoverAdoptableSurfaces(root));
+    return out;
+}
+/** The terminal "adoptable surfaces" nudge — N un-spec'd surfaces + the create-all
+ * command and up to ~5 per-surface commands (then "+K more"). "" when nothing to
+ * adopt (a fully spec-managed repo says nothing). */
+function formatAdoptableNudge(surfaces) {
+    if (surfaces.length === 0)
+        return "";
+    const n = surfaces.length;
+    const lines = [
+        `ℹ ${String(n)} surface${n === 1 ? "" : "s"} not yet spec-managed — create specs with \`npx vigiles init\``,
+        `  (or one at a time: \`npx vigiles init --target=<path>\`)`,
+    ];
+    const shown = surfaces.slice(0, 5);
+    for (const s of shown)
+        lines.push(`    • npx vigiles init --target=${s}`);
+    const more = n - shown.length;
+    if (more > 0)
+        lines.push(`    • +${String(more)} more`);
+    return lines.join("\n");
+}
+/** A small, terse behavioral nudge — the deterministic read can't tell whether a
+ * skill actually FIRES. "" when there are no model-invocable skills. */
+function formatTriggerNudge(triggerableSkills) {
+    if (triggerableSkills <= 0)
+        return "";
+    const n = triggerableSkills;
+    return (`ℹ Do your ${String(n)} skill${n === 1 ? "" : "s"} actually fire? The deterministic read can't tell — ` +
+        `run \`audit\` interactively to measure, or test with \`measureTriggerRate\` (vigiles/testing).`);
+}
+function scaffoldSpec(args) {
     const targetFlag = args.find((a) => a.startsWith("--target="));
     const target = targetFlag ? targetFlag.split("=")[1] : "CLAUDE.md";
     const specPath = `${target}.spec.ts`;
@@ -1224,11 +1331,24 @@ function init(args) {
     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.`);
+        const kind = surfaceKind(target);
+        if (kind === "skill") {
+            const { source, unmappedKeys } = (0, adopt_js_1.adoptSkill)(md, (0, node_path_1.basename)((0, node_path_1.dirname)(target)));
+            (0, node_fs_1.writeFileSync)(specAbs, source);
+            logAdoptedSurface(target, specPath, "skill", unmappedKeys);
+        }
+        else if (kind === "agent") {
+            const { source, unmappedKeys } = (0, adopt_js_1.adoptAgent)(md, (0, node_path_1.basename)(target, ".md"));
+            (0, node_fs_1.writeFileSync)(specAbs, source);
+            logAdoptedSurface(target, specPath, "subagent", unmappedKeys);
+        }
+        else {
+            const { source, tier, sectionCount } = (0, adopt_js_1.adoptMarkdown)(md, (0, node_path_1.basename)(target));
+            (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`
@@ -1454,7 +1574,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;
 }
 /**
@@ -1465,7 +1585,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) {
@@ -1475,7 +1595,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;
@@ -1755,11 +1875,17 @@ async function setupPillar1(detected, targetValue, harnesses) {
     // 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
+    const instructionTargets = targetValue
         ? determineTargets(detected, targetValue, harnesses)
         : redirectSyncToolTargets(cwd, collapseMirroredTargets(determineTargets(detected, targetValue, harnesses), (0, compose_js_1.detectInstructionMirror)(cwd)));
+    // Bare `init` (no explicit --target) also adopts every existing skill +
+    // subagent surface — "create all the specs it can", not just the instruction
+    // file. An explicit --target stays scoped to that one surface.
+    const targets = targetValue
+        ? instructionTargets
+        : [...instructionTargets, ...discoverAdoptableSurfaces(cwd)];
     // 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
+    // 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) {
@@ -1772,7 +1898,7 @@ async function setupPillar1(detected, targetValue, harnesses) {
             console.log(`✓ ${specPath} already exists`);
         }
         else {
-            init(["--target=" + target]); // adopts existing content, else blank scaffold
+            scaffoldSpec(["--target=" + target]); // adopts existing content, else blank scaffold
             written.push(specPath);
             if (willAdopt)
                 adopted.push(target);
@@ -2709,14 +2835,14 @@ function flagValue(args, name) {
     return args.find((a) => a.startsWith(`${name}=`))?.slice(name.length + 1);
 }
 /**
- * `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
+ * 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 scan ./plugin --trigger --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] ?? ".");
@@ -3051,32 +3177,6 @@ function harnessFlagFrom(argv) {
         .find((a) => a.startsWith("--harness="))
         ?.slice("--harness=".length);
 }
-/**
- * `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
- * 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
@@ -3227,9 +3327,9 @@ function printUsage(command) {
     console.log("  vigiles compile [files...]     Compile .spec.ts → .md");
     console.log("  vigiles eject [file]           Un-manage a compiled file → plain hand-owned markdown (--keep-spec)");
     console.log("  vigiles lint [files...]        Verify references, find gaps in instruction files");
-    console.log("  vigiles scan [dir...]          Report what a plugin ships + what's broken (free; 2+ dirs → leaderboard)");
-    console.log("                                 --trigger: do skills fire/collide? (real model) · --explain: why a surface underperforms · --fix-plan");
-    console.log("                                 with model access + a TTY, scan offers to measure firing; --no-interactive/--yes/--json hint instead (agents)");
+    console.log("  vigiles 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 scaffold-test [dir]    Generate a starter test for each untested skill/agent/hook (--write, --json)");
@@ -4030,32 +4130,175 @@ 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`).
+ * 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 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).
+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,
-        triggerableSkills: triggerable.length,
         json,
         noInteractive: args.includes("--no-interactive") || args.includes("--yes"),
+        remembered: (0, validate_js_1.loadConfig)().audit?.measure,
     });
-    if (decision === "none")
-        return;
-    if (decision === "hint") {
-        console.log("\n" + (0, scan_trigger_suggest_js_1.formatTriggerHint)(dir, triggerable.length));
-        return;
+    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);
     }
-    await promptTriggerSetup(report, dir, triggerable.length, args);
 }
 /** Ask one question on a fresh readline, closing it after (the codebase pattern). */
 async function askOnce(q) {
@@ -4075,29 +4318,33 @@ async function askOnce(q) {
         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;
+/**
+ * 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
+        }
     }
-    if (exists) {
-        await handleMeasure([dir], [...args, "--prompts=trigger-prompts.json"]);
-        return;
+    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 */
     }
-    (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);
@@ -4121,7 +4368,7 @@ async function main() {
             // 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);
@@ -4184,19 +4431,15 @@ async function main() {
         case "eval":
             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;
-            }
+        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
@@ -4249,19 +4492,69 @@ 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.
+                // Surfaces that exist but aren't spec-managed yet — the same notion
+                // `init` adopts (layout-driven instruction file + skill/subagent sweep).
+                // Surfaced in the AuditReport (the report's "Create spec" command-emit
+                // buttons read it) and the terminal nudge below.
+                const adoptableSurfaces = discoverAdoptableForAudit(root, adapter.layout.instructionFile);
+                const auditReport = (0, audit_report_js_1.buildAuditReport)(report, {
+                    harness: adapter.name,
+                    vigilesVersion: getVersion(),
+                    adoptableSurfaces,
+                });
+                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);
+                    // Adoption nudge: surfaces that exist but aren't spec-managed yet, with
+                    // the create-all + per-surface `init` commands (the JSON carries the
+                    // data in `adoptable` instead — the terminal stays human-readable).
+                    const adoptNudge = formatAdoptableNudge(adoptableSurfaces);
+                    if (adoptNudge)
+                        console.log("\n" + adoptNudge);
+                    // A small behavioral nudge — the deterministic read can't tell whether
+                    // skills actually FIRE; point at the interactive measure + the API.
+                    const fireNudge = formatTriggerNudge(report.skills.filter((s) => s.hasDescription && !s.userInvoked)
+                        .length);
+                    if (fireNudge)
+                        console.log("\n" + fireNudge);
                 }
-                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)
@@ -4280,9 +4573,76 @@ 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);
+                // 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;
         }