vigiles 7.0.0 → 9.0.0

package/dist/scan-trigger-suggest.d.ts

@@ -0,0 +1,91 @@
+/**
+ * audit → the ONE read-vs-run decision. `audit` is a Lighthouse-style LOCAL
+ * report: a deterministic READ by default — safe + identical on every OS, nothing
+ * executes — NOT a CI step (CI uses `vigiles lint`, the deterministic gate). The
+ * executing checks (safety battery, live MCP resolution, skill-firing trigger-rate)
+ * run ONLY when there's a human to consent: at a TTY `audit` ASKS once (and
+ * remembers in `.vigilesrc.json` `audit.measure`); headless (an agent / `--json` /
+ * `--no-interactive` / a pipe) it stays a read + a one-line nudge — never hangs,
+ * never silently executes. There is deliberately NO execution flag: automation
+ * tests the harness through the `vigiles/testing` API + skills (the layered tiers),
+ * not through the report verb. The IO (prompt / run / remember) lives in the CLI;
+ * this is the pure decision + helpers.
+ */
+/** Only the env vars that signal a reachable model (parse, don't validate). */
+export interface ModelEnv {
+    readonly ANTHROPIC_API_KEY?: string;
+    readonly CLAUDECODE?: string;
+    readonly CLAUDE_CODE_ENTRYPOINT?: string;
+}
+/**
+ * Is a real model reachable for the trigger tier? Either a metered API key
+ * (`ANTHROPIC_API_KEY`), OR an authenticated Claude Code session (`CLAUDECODE=1`
+ * / `CLAUDE_CODE_ENTRYPOINT`, web/desktop/CLI) — the latter drives the `claude`
+ * CLI on the user's subscription, no key needed and $0 metered. A tiny env-only
+ * predicate (not a live probe), so it never spends a token just to decide.
+ */
+export declare function hasModelAccess(env: ModelEnv): boolean;
+/**
+ * Is the reachable model METERED (a paid API key) rather than a subscription?
+ * Only affects the consent DISCLOSURE wording (a metered key bills per token; a
+ * subscription is $0 metered) — the run/skip decision itself is consent-driven,
+ * not metered-driven.
+ */
+export declare function isMeteredAccess(env: ModelEnv): boolean;
+/** Why the executing checks were skipped (drives the "not run" nudge). */
+export type ExecuteSkipReason = "nothing" | "headless" | "remembered-no";
+/**
+ * What `audit` should do about the EXECUTING checks (battery + live MCP +
+ * trigger-rate), as ONE bundle:
+ * - `run`  — run them now (a remembered yes).
+ * - `ask`  — interactive human + something to run + no sticky choice: ask once,
+ *            then remember.
+ * - `skip` — stay a deterministic read; the `reason` drives a one-line nudge.
+ */
+export type ExecuteDecision = {
+    readonly kind: "run";
+} | {
+    readonly kind: "ask";
+} | {
+    readonly kind: "skip";
+    readonly reason: ExecuteSkipReason;
+};
+export interface ExecuteEnv {
+    /** Is there ANY executable surface — runnable hooks, an own-repo MCP server, or
+     *  a model-invocable skill? Nothing to run → never ask, never nudge. */
+    readonly hasExecutable: boolean;
+    /** Both stdin AND stdout are a terminal (a human who can answer + wait). */
+    readonly isTTY: boolean;
+    /** `--json` — machine output; stays a read even at a TTY (never prompt). */
+    readonly json: boolean;
+    /** `--no-interactive` / `--yes` — explicit agent/CI mode (never prompt). */
+    readonly noInteractive: boolean;
+    /** Sticky remembered choice from `.vigilesrc.json` (`audit.measure`), or undefined. */
+    readonly remembered?: boolean;
+}
+/**
+ * Decide what `audit` does with the executing checks. Total + pure; the first
+ * matching rule wins. There is NO execution flag — `audit` is a local report, so
+ * the executing checks need a human to consent:
+ *  1. nothing executable → skip "nothing" (a clean read; no nudge)
+ *  2. headless (`--json` / `--no-interactive` / non-TTY — an agent, a pipe, CI) →
+ *     skip "headless" (no one to ask; automation uses the `vigiles/testing` API)
+ *  3. sticky no → skip "remembered-no"
+ *  4. sticky yes → run
+ *  5. interactive human, no sticky choice → ask (then remember)
+ */
+export declare function decideExecute(o: ExecuteEnv): ExecuteDecision;
+/**
+ * The one-line "executing checks not run" nudge for a skipped read (the
+ * no-silent-skips corollary). Returns null for `nothing` (nothing to run — not a
+ * gap). There is no flag to point at — `audit` runs them only interactively, and
+ * automation uses the `vigiles/testing` API.
+ */
+export declare function formatExecuteSkip(reason: ExecuteSkipReason): string | null;
+/**
+ * A starter `--prompts` file (the real `TriggerPromptSet` shape: bare skill name
+ * → `{ prompts, irrelevant }`). One entry per triggerable skill, with TODO
+ * placeholders the user replaces with real requests.
+ */
+export declare function scaffoldTriggerPrompts(skillNames: readonly string[]): string;
+//# sourceMappingURL=scan-trigger-suggest.d.ts.map

package/dist/scan-trigger-suggest.js

@@ -0,0 +1,103 @@
+"use strict";
+/**
+ * audit → the ONE read-vs-run decision. `audit` is a Lighthouse-style LOCAL
+ * report: a deterministic READ by default — safe + identical on every OS, nothing
+ * executes — NOT a CI step (CI uses `vigiles lint`, the deterministic gate). The
+ * executing checks (safety battery, live MCP resolution, skill-firing trigger-rate)
+ * run ONLY when there's a human to consent: at a TTY `audit` ASKS once (and
+ * remembers in `.vigilesrc.json` `audit.measure`); headless (an agent / `--json` /
+ * `--no-interactive` / a pipe) it stays a read + a one-line nudge — never hangs,
+ * never silently executes. There is deliberately NO execution flag: automation
+ * tests the harness through the `vigiles/testing` API + skills (the layered tiers),
+ * not through the report verb. The IO (prompt / run / remember) lives in the CLI;
+ * this is the pure decision + helpers.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasModelAccess = hasModelAccess;
+exports.isMeteredAccess = isMeteredAccess;
+exports.decideExecute = decideExecute;
+exports.formatExecuteSkip = formatExecuteSkip;
+exports.scaffoldTriggerPrompts = scaffoldTriggerPrompts;
+/**
+ * Is a real model reachable for the trigger tier? Either a metered API key
+ * (`ANTHROPIC_API_KEY`), OR an authenticated Claude Code session (`CLAUDECODE=1`
+ * / `CLAUDE_CODE_ENTRYPOINT`, web/desktop/CLI) — the latter drives the `claude`
+ * CLI on the user's subscription, no key needed and $0 metered. A tiny env-only
+ * predicate (not a live probe), so it never spends a token just to decide.
+ */
+function hasModelAccess(env) {
+    return Boolean(env.ANTHROPIC_API_KEY ||
+        env.CLAUDECODE === "1" ||
+        env.CLAUDE_CODE_ENTRYPOINT);
+}
+/**
+ * Is the reachable model METERED (a paid API key) rather than a subscription?
+ * Only affects the consent DISCLOSURE wording (a metered key bills per token; a
+ * subscription is $0 metered) — the run/skip decision itself is consent-driven,
+ * not metered-driven.
+ */
+function isMeteredAccess(env) {
+    return Boolean(env.ANTHROPIC_API_KEY);
+}
+/**
+ * Decide what `audit` does with the executing checks. Total + pure; the first
+ * matching rule wins. There is NO execution flag — `audit` is a local report, so
+ * the executing checks need a human to consent:
+ *  1. nothing executable → skip "nothing" (a clean read; no nudge)
+ *  2. headless (`--json` / `--no-interactive` / non-TTY — an agent, a pipe, CI) →
+ *     skip "headless" (no one to ask; automation uses the `vigiles/testing` API)
+ *  3. sticky no → skip "remembered-no"
+ *  4. sticky yes → run
+ *  5. interactive human, no sticky choice → ask (then remember)
+ */
+function decideExecute(o) {
+    if (!o.hasExecutable)
+        return { kind: "skip", reason: "nothing" };
+    if (o.json || o.noInteractive || !o.isTTY)
+        return { kind: "skip", reason: "headless" };
+    if (o.remembered === false)
+        return { kind: "skip", reason: "remembered-no" };
+    if (o.remembered === true)
+        return { kind: "run" };
+    return { kind: "ask" };
+}
+/**
+ * The one-line "executing checks not run" nudge for a skipped read (the
+ * no-silent-skips corollary). Returns null for `nothing` (nothing to run — not a
+ * gap). There is no flag to point at — `audit` runs them only interactively, and
+ * automation uses the `vigiles/testing` API.
+ */
+function formatExecuteSkip(reason) {
+    switch (reason) {
+        case "nothing":
+            return null;
+        case "headless":
+            return ("\nℹ Executing checks (safety battery · live MCP · skill firing) skipped — " +
+                "`audit` runs them only interactively (a terminal). For automation, test the " +
+                "harness with the `vigiles/testing` API.");
+        case "remembered-no":
+            return ("\nℹ Executing checks not run (you disabled them — edit .vigilesrc.json " +
+                "`audit.measure` to re-enable).");
+    }
+}
+/**
+ * A starter `--prompts` file (the real `TriggerPromptSet` shape: bare skill name
+ * → `{ prompts, irrelevant }`). One entry per triggerable skill, with TODO
+ * placeholders the user replaces with real requests.
+ */
+function scaffoldTriggerPrompts(skillNames) {
+    const obj = {};
+    for (const name of skillNames) {
+        obj[name] = {
+            prompts: [
+                `TODO: a request that SHOULD trigger "${name}"`,
+                `TODO: a differently-phrased request that should also trigger it`,
+            ],
+            irrelevant: [
+                `TODO: an unrelated request that should NOT trigger "${name}"`,
+            ],
+        };
+    }
+    return JSON.stringify(obj, null, 2) + "\n";
+}
+//# sourceMappingURL=scan-trigger-suggest.js.map

package/dist/scan.d.ts

@@ -1,5 +1,5 @@
 /**
- * `vigiles scan <dir>` — point vigiles at any plugin/repo and see what it ships
+ * `vigiles audit <dir>` — point vigiles at any plugin/repo and see what it ships
  * and what's broken, with **no model and no API key**.
  *
  * This is the deterministic substrate under the plugin/skill leaderboard
@@ -27,14 +27,20 @@ export interface ScanSkill {
     readonly name: string;
     readonly path: string;
     readonly hasDescription: boolean;
+    /**
+     * The skill's effective description (frontmatter `description`, else the first
+     * body paragraph — the same text the selector keys on), trimmed; `undefined`
+     * when neither exists. Feeds the model trigger tier's auto-generated probes.
+     */
+    readonly description?: string;
     readonly userInvoked: boolean;
     /**
      * The description's dominant script when it DIFFERS from the expected one
      * (default `"Latin"`), else null. The model's skill-selection context is
      * English-centric, so a description in another script carries a cross-language
      * trigger risk — it may under-fire on English prompts. A RISK flag, not a
-     * defect (a language-matched audience is fine); measure the real gap with
-     * `scan --trigger`.
+     * defect (a language-matched audience is fine); measure the real gap with the
+     * `audit` trigger tier / `measureTriggerRate`.
      */
     readonly descriptionScript: Script | null;
 }
@@ -86,15 +92,32 @@ export interface FrontmatterValueIssue {
 /** ok = file present; missing = referenced but absent; unresolved = path still has an unexpanded var, can't check. */
 export type HookStatus = "ok" | "missing" | "unresolved";
 export interface ScanHook {
+    /**
+     * The full hook command as it would be run (plugin-root token expanded, shell
+     * quotes stripped). Present on script-based hooks; empty string on hooks whose
+     * command is entirely inline (no script file) — but inline hooks never appear
+     * in `hooks[]`, they are counted by `inlineHooks`, so in practice `command` is
+     * always non-empty when a `ScanHook` is in the list.
+     */
+    readonly command: string;
     readonly script: string;
     readonly status: HookStatus;
+    /**
+     * The hook EVENT this script is registered under (`PreToolUse`, `PostToolUse`,
+     * `SessionStart`, …), when it can be determined from the canonical
+     * object-keyed-by-event settings shape; `undefined` for a non-object/array
+     * config. The safety battery uses it to test only the blocking-capable
+     * `PreToolUse` guards — so a `SessionStart`/`PostToolUse` hook isn't unfairly
+     * scored against "does it block rm -rf".
+     */
+    readonly event?: string;
 }
 /**
  * The repo's top-level instruction file (`CLAUDE.md` / `AGENTS.md`), if present.
  * Every cc/codex repo has one even when it ships no plugin surface, so `scan`
  * reports it — otherwise a plain instruction-only repo looks empty. `hasSpec` is
  * the deterministic fact that a `<file>.spec.ts` sits beside it (spec-managed vs
- * hand-written); it is informational, NOT the `require-spec` gate (that's lint).
+ * hand-written); it is informational, NOT the `require-instructions-spec` gate (that's lint).
  */
 export interface ScanInstructions {
     readonly file: string;
@@ -109,6 +132,13 @@ export interface ScanReport {
     readonly hooks: readonly ScanHook[];
     /** Hook entries with no script file (inline shell one-liners) — can't be path-checked. */
     readonly inlineHooks: number;
+    /**
+     * Hand-written hook commands that are NOT compiled `vigiles/hook` artifacts (a
+     * compiled hook's command invokes `vigiles hook-runtime run-program`). The basis
+     * for the `prefer-compiled-hooks` recommendation — a single nudge regardless of
+     * count. Zero when there are no hooks or every hook is vigiles-managed.
+     */
+    readonly manualHookCount: number;
     readonly commands: number;
     readonly mcp: boolean;
     /**
@@ -175,17 +205,28 @@ export interface SurfaceClassifier {
  * no drift). The ≥20% guard avoids a near-empty string tripping on one letter.
  */
 export declare function unexpectedScript(text: string, expected?: Script): Script | null;
+/**
+ * A compiled `vigiles/hook` artifact runs through the `hook-runtime run-program`
+ * runtime entrypoint; any other hook command is hand-written (a shell script or
+ * an inline one-liner) the author maintains directly. The basis for the
+ * `prefer-compiled-hooks` nudge.
+ */
+export declare function isManagedHookCommand(command: string): boolean;
+/** The `prefer-compiled-hooks` recommendation message (shared by `lint` + `scan`). */
+export declare function preferCompiledHooksMessage(count: number): string;
 /** Scan a plugin/repo directory and report its surfaces + structural issues. */
 export declare function scanPlugin(dir: string, layout?: PluginLayout, dialect?: HarnessDialect): ScanReport;
 /**
- * LIVE MCP tool resolution for a scanned plugin — the opt-in (`scan --verify-mcp`)
- * dynamic check no static linter can do: it STARTS each declared MCP server and
- * checks every `mcp__server__tool` the plugin's agents reference actually exists on
- * it (catching rename/removal rot, e.g. `create_issue`→`issue_write`). Reuses the
+ * LIVE MCP tool resolution for a scanned plugin — the dynamic check no static
+ * linter can do: it STARTS each declared MCP server and checks every
+ * `mcp__server__tool` the plugin's agents reference actually exists on it
+ * (catching rename/removal rot, e.g. `create_issue`→`issue_write`). Reuses the
  * already-computed `report` (its agents' tool lists) + the declared server configs;
  * returns `[]` when the plugin declares no MCP servers (nothing to start). Async +
- * side-effecting (spawns servers) — which is exactly why it's opt-in, not a default
- * lint rule. See `verifyMcpContractTools` (core/mcp.ts).
+ * side-effecting (spawns servers) — so `audit` runs it by default only for the
+ * user's OWN repo (own-repo, like running your own tools); a FOREIGN plugin's
+ * servers are never spawned, and `--fast` opts out. See `verifyMcpContractTools`
+ * (core/mcp.ts).
  */
 export declare function verifyLiveMcpTools(report: ScanReport, layout: PluginLayout, dialect: HarnessDialect, timeoutMs?: number): Promise<McpContractToolError[]>;
 /** Render the live MCP tool-check result (human-readable). */
@@ -211,7 +252,7 @@ export interface MarketplaceInfo {
  * Read a `marketplace.json` beside the layout's plugin manifest and classify its
  * members into on-disk vs external. Returns `null` when `dir` is not a
  * marketplace. The source of truth behind {@link expandMarketplace} and the
- * curated-marketplace report in `vigiles scan`.
+ * curated-marketplace report in `vigiles audit`.
  */
 export declare function inspectMarketplace(dir: string, layout?: PluginLayout): MarketplaceInfo | null;
 /**
@@ -219,7 +260,7 @@ export declare function inspectMarketplace(dir: string, layout?: PluginLayout):
  * plugin manifest, e.g. `.claude-plugin/marketplace.json`), expand it into the
  * absolute dirs of its member plugins. Returns `null` when there's no
  * marketplace, `[]` when it's a marketplace whose members are all external (not
- * on disk). Used by `vigiles scan` to rank a whole marketplace — wshobson/agents
+ * on disk). Used by `vigiles audit` to rank a whole marketplace — wshobson/agents
  * alone ships 80+ plugins under one `marketplace.json`. See {@link inspectMarketplace}.
  */
 export declare function expandMarketplace(dir: string, layout?: PluginLayout): string[] | null;

package/dist/scan.js

@@ -1,6 +1,6 @@
 "use strict";
 /**
- * `vigiles scan <dir>` — point vigiles at any plugin/repo and see what it ships
+ * `vigiles audit <dir>` — point vigiles at any plugin/repo and see what it ships
  * and what's broken, with **no model and no API key**.
  *
  * This is the deterministic substrate under the plugin/skill leaderboard
@@ -14,6 +14,8 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.unexpectedScript = unexpectedScript;
+exports.isManagedHookCommand = isManagedHookCommand;
+exports.preferCompiledHooksMessage = preferCompiledHooksMessage;
 exports.scanPlugin = scanPlugin;
 exports.verifyLiveMcpTools = verifyLiveMcpTools;
 exports.formatMcpContractReport = formatMcpContractReport;
@@ -166,6 +168,7 @@ function scanSkills(files, cls) {
             name: fm.name ?? skillName(path),
             path,
             hasDescription: Boolean(effectiveDesc && effectiveDesc.length >= 20),
+            description: effectiveDesc?.trim(),
             userInvoked: /^\s*disable-model-invocation:\s*true\s*$/m.test(md),
             descriptionScript: effectiveDesc ? unexpectedScript(effectiveDesc) : null,
         });
@@ -242,7 +245,7 @@ function scanAgents(files, dialect, declaredServers, cls) {
  * quotes. A token that still carries any `$VAR` after that is genuinely
  * uncheckable.
  */
-function resolveScript(token, root, pluginRootToken) {
+function resolveScript(token, root, pluginRootToken, fullCommand) {
     // "${CLAUDE_PLUGIN_ROOT}" → unbraced "$CLAUDE_PLUGIN_ROOT".
     const unbraced = pluginRootToken.replace(/^\$\{(.+)\}$/, "$$$1");
     const cleaned = token
@@ -250,14 +253,23 @@ function resolveScript(token, root, pluginRootToken) {
         .replaceAll(pluginRootToken, root)
         .replaceAll(unbraced, root);
     if (cleaned.includes("$"))
-        return { script: token, status: "unresolved" };
+        return { command: fullCommand, script: token, status: "unresolved" };
     // A relative hook path (`./hooks/x.sh`, `scripts/x.py`) is the plugin's own —
     // resolve it against the PLUGIN ROOT, not the scanner's cwd. Without this, a
     // plugin that references `./hooks/x.sh` (the file IS present) was reported
     // MISSING because existsSync() checked cwd-relative (a false positive caught on
     // ananddtyagi/cc-marketplace). The displayed `script` stays as the author wrote it.
     const abs = (0, node_path_1.isAbsolute)(cleaned) ? cleaned : (0, node_path_1.resolve)(root, cleaned);
-    return { script: cleaned, status: (0, node_fs_1.existsSync)(abs) ? "ok" : "missing" };
+    // Resolve the full command the same way we resolve the script token (expand
+    // plugin-root, strip outer quotes) so the CLI can pass it to verifyGuardrail.
+    const resolvedCommand = fullCommand
+        .replaceAll(pluginRootToken, root)
+        .replaceAll(unbraced, root);
+    return {
+        command: resolvedCommand,
+        script: cleaned,
+        status: (0, node_fs_1.existsSync)(abs) ? "ok" : "missing",
+    };
 }
 // A shell existence guard around a command — `[ ! -f x ] || x`, `[ -f x ] && x`,
 // `test -f x && …`. Authors use it to make a hook OPTIONAL (run the script only
@@ -265,10 +277,65 @@ function resolveScript(token, root, pluginRootToken) {
 // target is INTENTIONAL, not a broken reference. Don't flag scripts in such a
 // command as MISSING (a false positive caught on gmickel/flow-next's ralph-guard).
 const EXISTENCE_GUARD = /(?:\[\[?\s*!?\s*-[efsx]\s)|(?:\btest\s+!?\s*-[efsx]\s)/;
+/**
+ * A compiled `vigiles/hook` artifact runs through the `hook-runtime run-program`
+ * runtime entrypoint; any other hook command is hand-written (a shell script or
+ * an inline one-liner) the author maintains directly. The basis for the
+ * `prefer-compiled-hooks` nudge.
+ */
+function isManagedHookCommand(command) {
+    return /\bhook-runtime\b/.test(command);
+}
+/** The `prefer-compiled-hooks` recommendation message (shared by `lint` + `scan`). */
+function preferCompiledHooksMessage(count) {
+    return (`${String(count)} hand-written hook command(s) — if any gate the agent ` +
+        `(a block/deny decision), compiled hooks (\`vigiles/hook\`) make whole hook ` +
+        `bug classes unrepresentable at authoring time, and \`guardrail-check\` proves ` +
+        `an existing one blocks. See docs/compiled-hooks.md.`);
+}
 /** Pull script-file hook commands out of the resolved settings; count inline ones. */
+/**
+ * Best-effort map of each script token → the hook EVENT it's registered under,
+ * by walking the canonical object-keyed-by-event settings shape
+ * (`{ PreToolUse: [{ hooks: [{ command }] }], … }`). Lets the safety battery
+ * scope itself to `PreToolUse` (the only event that can block a tool call), so a
+ * `SessionStart`/`PostToolUse`/`Stop` hook isn't tested against the disaster
+ * catalog. Returns an empty map for a non-object/array config (event → unknown).
+ */
+function eventsByScript(hooks) {
+    const map = new Map();
+    if (!hooks || typeof hooks !== "object" || Array.isArray(hooks))
+        return map;
+    for (const [event, arr] of Object.entries(hooks)) {
+        if (!Array.isArray(arr))
+            continue;
+        for (const entry of arr) {
+            const hookList = entry.hooks;
+            if (!Array.isArray(hookList))
+                continue;
+            for (const h of hookList) {
+                const cmd = h.command;
+                if (typeof cmd !== "string")
+                    continue;
+                for (const tok of cmd.match(SCRIPT_RE) ?? []) {
+                    if (!map.has(tok))
+                        map.set(tok, event);
+                }
+            }
+        }
+    }
+    return map;
+}
 function scanHooks(settings, root, pluginRootToken) {
     const text = JSON.stringify(settings.hooks ?? {});
     const commands = [...text.matchAll(/"command":\s*"((?:[^"\\]|\\.)*)"/g)].map((m) => m[1]);
+    const evMap = eventsByScript(settings.hooks);
+    // A hand-written hook is any non-empty command that isn't a vigiles-managed
+    // (compiled) hook-runtime invocation — the basis for the prefer-compiled-hooks nudge.
+    const manual = commands.filter((c) => {
+        const u = c.replace(/\\(.)/g, "$1").trim();
+        return u !== "" && !isManagedHookCommand(u);
+    }).length;
     const byScript = new Map();
     let inline = 0;
     for (const cmd of commands) {
@@ -285,12 +352,13 @@ function scanHooks(settings, root, pluginRootToken) {
             continue;
         }
         for (const tok of found) {
-            const hook = resolveScript(tok, root, pluginRootToken);
-            byScript.set(hook.script, hook);
+            const hook = resolveScript(tok, root, pluginRootToken, unescaped);
+            const event = evMap.get(tok);
+            byScript.set(hook.script, event ? { ...hook, event } : hook);
         }
     }
     const hooks = [...byScript.values()].sort((a, b) => a.script.localeCompare(b.script));
-    return { hooks, inline };
+    return { hooks, inline, manual };
 }
 // ---------------------------------------------------------------------------
 // Public API
@@ -487,7 +555,7 @@ function scanPlugin(dir, layout, dialect = dialect_js_1.claudeCodeDialect) {
     const lay = layout ?? layout_js_1.claudeCodeLayout;
     const cls = makeClassifier(lay);
     const loaded = (0, plugin_loader_js_1.loadPlugin)(dir, lay);
-    const { hooks, inline } = scanHooks(loaded.settings, (0, node_path_1.resolve)(dir), lay.pluginRootToken);
+    const { hooks, inline, manual } = scanHooks(loaded.settings, (0, node_path_1.resolve)(dir), lay.pluginRootToken);
     // Hook-event keys are a CLOSED platform set — an unrecognized one is a dead
     // registration (the hook never fires), so flag every unknown (not just typos).
     // ONLY for the canonical object-keyed-by-event shape: a plugin shipping a
@@ -521,6 +589,7 @@ function scanPlugin(dir, layout, dialect = dialect_js_1.claudeCodeDialect) {
         agents,
         hooks,
         inlineHooks: inline,
+        manualHookCount: manual,
         commands: Object.keys(loaded.files).filter(cls.isCommand).length,
         mcp: loaded.warnings.some((w) => w.includes("MCP server")),
         danglingRefs: (0, plugin_loader_js_2.danglingRefs)((0, node_path_1.resolve)(dir), lay),
@@ -539,14 +608,16 @@ function scanPlugin(dir, layout, dialect = dialect_js_1.claudeCodeDialect) {
     };
 }
 /**
- * LIVE MCP tool resolution for a scanned plugin — the opt-in (`scan --verify-mcp`)
- * dynamic check no static linter can do: it STARTS each declared MCP server and
- * checks every `mcp__server__tool` the plugin's agents reference actually exists on
- * it (catching rename/removal rot, e.g. `create_issue`→`issue_write`). Reuses the
+ * LIVE MCP tool resolution for a scanned plugin — the dynamic check no static
+ * linter can do: it STARTS each declared MCP server and checks every
+ * `mcp__server__tool` the plugin's agents reference actually exists on it
+ * (catching rename/removal rot, e.g. `create_issue`→`issue_write`). Reuses the
  * already-computed `report` (its agents' tool lists) + the declared server configs;
  * returns `[]` when the plugin declares no MCP servers (nothing to start). Async +
- * side-effecting (spawns servers) — which is exactly why it's opt-in, not a default
- * lint rule. See `verifyMcpContractTools` (core/mcp.ts).
+ * side-effecting (spawns servers) — so `audit` runs it by default only for the
+ * user's OWN repo (own-repo, like running your own tools); a FOREIGN plugin's
+ * servers are never spawned, and `--fast` opts out. See `verifyMcpContractTools`
+ * (core/mcp.ts).
  */
 async function verifyLiveMcpTools(report, layout, dialect, timeoutMs = 10000) {
     // collectMcpServers yields the raw JSON server entries; a malformed one (no
@@ -571,7 +642,7 @@ function formatMcpContractReport(errors) {
  * Read a `marketplace.json` beside the layout's plugin manifest and classify its
  * members into on-disk vs external. Returns `null` when `dir` is not a
  * marketplace. The source of truth behind {@link expandMarketplace} and the
- * curated-marketplace report in `vigiles scan`.
+ * curated-marketplace report in `vigiles audit`.
  */
 function inspectMarketplace(dir, layout = layout_js_1.claudeCodeLayout) {
     const mpPath = (0, node_path_1.join)(dir, (0, node_path_1.dirname)(layout.manifestPath), "marketplace.json");
@@ -623,7 +694,7 @@ function inspectMarketplace(dir, layout = layout_js_1.claudeCodeLayout) {
  * plugin manifest, e.g. `.claude-plugin/marketplace.json`), expand it into the
  * absolute dirs of its member plugins. Returns `null` when there's no
  * marketplace, `[]` when it's a marketplace whose members are all external (not
- * on disk). Used by `vigiles scan` to rank a whole marketplace — wshobson/agents
+ * on disk). Used by `vigiles audit` to rank a whole marketplace — wshobson/agents
  * alone ships 80+ plugins under one `marketplace.json`. See {@link inspectMarketplace}.
  */
 function expandMarketplace(dir, layout = layout_js_1.claudeCodeLayout) {
@@ -749,6 +820,11 @@ function formatScanReport(r) {
     if (r.skillMetaIssues.length > 0) {
         out.push(`ℹ ${String(r.skillMetaIssues.length)} skill(s) lack an explicit frontmatter name/description (recommended for a reliable trigger surface) — they still load via fallback`, "");
     }
+    // One discovery nudge toward compiled hooks (never per-hook); the hand-written
+    // shell lane stays first-class, so this is a recommendation, not a defect.
+    if (r.manualHookCount > 0) {
+        out.push(`ℹ ${preferCompiledHooksMessage(r.manualHookCount)}`, "");
+    }
     // Malformed-YAML frontmatter is INFORMATIONAL, not a structural defect: js-yaml
     // is stricter than some loaders (a colon/quote/<example> in a one-line
     // description trips it though the file may still load), and the other fields are

package/dist/score-explainer.d.ts

@@ -35,7 +35,7 @@ export type BehavioralSymptom = "wrong-skill-fires" | "skill-never-fires" | "age
  *   never-available tool can't be called); the cause is near-certain.
  * - `"possible"` — a high-precision PROXY for a behavioral risk (a description
  *   overlap / a foreign-script description); deterministic to detect, but whether
- *   it actually moved behaviour is confirmed by `scan --trigger`.
+ *   it actually moved behaviour is confirmed by the `audit` trigger tier.
  */
 export type ExplanationConfidence = "likely" | "possible";
 export interface ScoreExplanation {

package/dist/setup-plan.d.ts

@@ -27,6 +27,10 @@ export interface SetupPlan {
 export interface ParsedSetupArgs {
     target?: string;
     strict: boolean;
+    /** `--report-only` — write the gating rules at "warn" (nothing fails CI). The
+     * orthogonal severity dial; composes with `--strict` (which rules) by setting
+     * their severity. */
+    reportOnly: boolean;
     yes: boolean;
     /** `--force` — rewrite a stale CI workflow in place. */
     force: boolean;
@@ -51,9 +55,52 @@ export declare function defaultPlan(strict?: boolean): SetupPlan;
  * changed (so the IO layer skips the write). The IO (read/parse/write + the
  * malformed-file guard) stays in cli.ts.
  */
+/**
+ * The structural rules `init` gates BY DEFAULT (severity `error`, so a broken
+ * surface fails `vigiles lint`). Every one is HIGH-PRECISION / FP-safe — it fires
+ * only on a genuine defect (a never-available/typo'd tool, a subagent missing
+ * `name`/`description`, a typo'd hook event, a dead hook script, a broken MCP
+ * ref, two skills that collide in the selector) — so a well-formed plugin stays
+ * green and catching real breakage out of the box never cries wolf.
+ *
+ * Deliberately EXCLUDES `require-instructions-spec` and the workflow-forcing rules:
+ * those make a CLEAN repo fail (you simply haven't written the spec/test yet), so
+ * they stay opt-in under `--strict` (progressive adoption — see
+ * `STRICT_EXTRA_RULES`).
+ *
+ * This is the **`structural`** rule group (see research/install-enforcement-dx.md).
+ */
+export declare const STRUCTURAL_RULES: readonly ["subagent-tool-contract", "subagent-frontmatter", "hook-events", "hook-script-exists", "mcp-config", "mcp-tool-resolves", "mcp-hook-target-resolves", "disallowed-tools-contract", "description-overlap"];
+/**
+ * The **`workflow`** group — the WORKFLOW-FORCING / opinionated tier `--strict`
+ * gates, which a clean repo can still fail because you haven't done the work yet:
+ * a spec per instruction file (`require-instructions-spec`), a test/eval per
+ * surface (`untested-*`). Opt-in by design (the smooth-adoption on-ramp). The
+ * Clippy-`pedantic` / TS-`strict` analog — ONE opinionated opt-in.
+ *
+ * NB `frontmatter-valid` / `skill-frontmatter` live in the `nudge` group, not
+ * here: they're acknowledged-noisy recommendations we never gate on (see
+ * research/install-enforcement-dx.md).
+ */
+export declare const WORKFLOW_RULES: readonly ["require-instructions-spec", "untested-skill", "untested-subagent", "untested-hook"];
+/**
+ * The **`nudge`** group — recommendations / acknowledged-noisy checks that NEVER
+ * gate (not even under `--strict`): `frontmatter-valid` (js-yaml is stricter than
+ * CC's loader), `skill-frontmatter` (skills load without it) and `unmarked-refs`
+ * (the undecidable-plaintext nudge) sit at `warn`; `prefer-compiled-hooks` defaults
+ * OFF (a recommendation that shouldn't fire unasked — the shell lane stays
+ * first-class). `init` does not write these — they keep their own default
+ * severities. Named for the group taxonomy (research/install-enforcement-dx.md).
+ */
+export declare const NUDGE_RULES: readonly ["frontmatter-valid", "skill-frontmatter", "prefer-compiled-hooks", "unmarked-refs"];
 export declare function mergeProjectConfig(existing: Record<string, unknown>, opts: {
     harness: string | string[];
     strict: boolean;
+    reportOnly?: boolean;
+    /** Whether the LINT pillar is on (default true). The rule gate is a lint-layer
+     * concern, so a test-only setup (`init --test` / `--no-lint`) records the
+     * harness but writes NO lint rules. */
+    lint?: boolean;
 }): Record<string, unknown> | null;
 /**
  * Whether to drop into interactive prompts: a human at a TTY who passed neither
@@ -62,7 +109,18 @@ export declare function mergeProjectConfig(existing: Record<string, unknown>, op
  */
 export declare function shouldPrompt(parsed: ParsedSetupArgs, isTTY: boolean): boolean;
 /** Interactive answers (only the fields the prompts cover). */
-export type SetupAnswers = Partial<Pick<SetupPlan, "lint" | "test" | "gha" | "plugin">>;
+export type SetupAnswers = Partial<Pick<SetupPlan, "lint" | "test" | "gha" | "plugin" | "strict">>;
+/** Ask one question with a default — injected so the interactive Q&A is pure +
+ *  unit-testable (a fake `ask` scripts answers; no TTY, no readline). */
+export type AskFn = (question: string, def: string) => Promise<string>;
+/**
+ * The interactive setup Q&A as PURE logic over an injected `ask` — the prompts,
+ * their defaults, and the answer→`SetupAnswers` mapping. The IO shell (readline)
+ * lives in `cli.ts`'s `promptSetup`, which just supplies a real `ask`. Keeping
+ * this here means the fragile interactive path is unit-tested deterministically
+ * (the questions can't silently break) without a terminal.
+ */
+export declare function collectSetupAnswers(ask: AskFn): Promise<SetupAnswers>;
 /**
  * How to install vigiles's skills/hooks for ONE harness — the deterministic
  * decision behind the IO in cli.ts, so a CI test asserts WHICH commands an