vigiles 8.0.0 → 9.1.0

package/dist/optimize.js

@@ -1,13 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.optimize = optimize;
+exports.formatRecommendations = formatRecommendations;
 exports.formatOptimize = formatOptimize;
 /**
- * The per-repo harness optimizer's DETERMINISTIC spine — shipped as the
- * `vigiles scan --fix-plan` lens (NOT its own `optimize` verb: until the measured
- * A/B half lands, an "optimizer" that only re-prints scan's findings doesn't earn
- * a separate command, so it's folded into scan as one more view on the same
- * report; see research/roadmap.md §P2 "reconsider an `optimize` verb").
+ * The per-repo harness optimizer's DETERMINISTIC spine — folded INLINE into the
+ * default `vigiles audit` report (each finding carries its fix; NOT its own
+ * `optimize` verb, and no longer a `--fix-plan` flag: until the measured A/B half
+ * lands, an "optimizer" that only re-prints audit's findings doesn't earn a
+ * separate surface; see research/roadmap.md §P2 "reconsider an `optimize` verb").
  *
  * A2 in the measurement-authority pivot is the ADOPTION product: measure a user's
  * own skills/model/rules on their tasks and recommend add/drop/swap with a MEASURED
@@ -67,6 +68,27 @@ const ACTION_LABEL = {
     differentiate: "DIFFERENTIATE",
 };
 const measureHint = (dir) => `\`vigiles measure ${dir} --prompts=<file>\` — real-model, runs on your subscription`;
+/**
+ * Just the deterministic fix list (no score header) — folded into the default
+ * `vigiles audit` report so every finding carries its fix inline (replaces the
+ * former `--fix-plan`/`--explain` flags). Empty string when there's nothing to
+ * fix (or no loadable surface), so the caller can skip the section entirely.
+ */
+function formatRecommendations(rep) {
+    if (rep.empty || rep.recommendations.length === 0)
+        return "";
+    const lines = [
+        `${String(rep.recommendations.length)} deterministic fix(es) — free, no model:`,
+        "",
+    ];
+    for (const r of rep.recommendations) {
+        const mark = r.confidence === "likely" ? "✗" : "⚠";
+        lines.push(`${mark} [${ACTION_LABEL[r.action]}] ${r.surface}`);
+        lines.push(`    why: ${r.rationale}  [${r.detector}]`);
+        lines.push(`    →    ${r.fix}`);
+    }
+    return lines.join("\n");
+}
 /** Render an optimization plan for the CLI. */
 function formatOptimize(rep) {
     const head = `Harness health: ${String(rep.score)}/100 (${rep.grade}) — ${rep.dir}`;

package/dist/scan-behavioral.d.ts

@@ -1,8 +1,8 @@
 /**
- * `vigiles scan --trigger` — the BEHAVIORAL column of the scan report.
+ * `vigiles audit` model trigger tier — the BEHAVIORAL column of the audit report.
  *
  * Structural `scan`/`scanPlugin` is deterministic, no-model, CI-free — and stays
- * that way. This is the opt-in, model-gated column that stacks on top: for each
+ * that way. This is the model-gated column that stacks on top: for each
  * model-invocable skill in a plugin, it measures how reliably the description
  * actually FIRES (recall, + precision when irrelevant prompts are supplied),
  * reusing `measureTriggerRate`. It degrades honestly when the `claude` CLI / auth
@@ -12,6 +12,8 @@
  * path in prose is undecidable, and the deterministic-input discipline is what
  * makes the column trustworthy. See `research/plugin-behavioral-findings.md`.
  */
+import type { PluginLayout } from "./core/layout.js";
+import type { HarnessDialect } from "./core/dialect.js";
 import { type EvalDriver } from "./eval.js";
 import { type Trace } from "./harness-test.js";
 /** Which harness drives the behavioral column (default Claude Code). */
@@ -46,6 +48,10 @@ export interface ProbeOptions {
     readonly minDistance?: number;
     /** Which harness to drive (default `"claude-code"`). */
     readonly harness?: ProbeHarness;
+    /** Layout + dialect for candidate discovery — so a Codex repo's skills (under
+     *  the Codex layout) are found, not silently missed by the default CC layout. */
+    readonly layout?: PluginLayout;
+    readonly dialect?: HarnessDialect;
 }
 /**
  * Per-harness probe wiring: the eval driver (runner+parse), how to build the

package/dist/scan-behavioral.js

@@ -1,9 +1,9 @@
 "use strict";
 /**
- * `vigiles scan --trigger` — the BEHAVIORAL column of the scan report.
+ * `vigiles audit` model trigger tier — the BEHAVIORAL column of the audit report.
  *
  * Structural `scan`/`scanPlugin` is deterministic, no-model, CI-free — and stays
- * that way. This is the opt-in, model-gated column that stacks on top: for each
+ * that way. This is the model-gated column that stacks on top: for each
  * model-invocable skill in a plugin, it measures how reliably the description
  * actually FIRES (recall, + precision when irrelevant prompts are supplied),
  * reusing `measureTriggerRate`. It degrades honestly when the `claude` CLI / auth
@@ -131,8 +131,10 @@ async function probeSkill(ctx, name, ps) {
 async function probePluginTriggersWith(dir, promptSet, probe, opts = {}) {
     const ctx = { dir, opts, probe };
     // Only model-invocable, describable skills can auto-trigger; user-invoked and
-    // description-less ones can't, so they're not behavioral candidates.
-    const candidates = (0, scan_js_1.scanPlugin)(dir).skills.filter((s) => !s.userInvoked && s.hasDescription);
+    // description-less ones can't, so they're not behavioral candidates. Discover
+    // them with the resolved layout/dialect (default CC) so a Codex repo's skills
+    // aren't missed by the wrong layout.
+    const candidates = (0, scan_js_1.scanPlugin)(dir, opts.layout, opts.dialect).skills.filter((s) => !s.userInvoked && s.hasDescription);
     const results = [];
     for (const s of candidates) {
         const ps = promptSet[s.name];

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

@@ -1,10 +1,15 @@
 /**
- * scan → trigger-tier nudge. When a plugin ships model-invocable skills AND a
- * real model is reachable, surface the (real-model) `scan --trigger` tier that
- * measures whether those skills actually FIRE (recall + precision). Pure
- * decision + helpers; the IO (prompt / scaffold write / running the measure)
- * lives in the CLI. Honors `great-agent-flow`: an agent (non-TTY / `--json` /
- * `--no-interactive`) is HINTED, never prompted — a `scan` must never hang.
+ * 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 {
@@ -13,42 +18,74 @@ export interface ModelEnv {
     readonly CLAUDE_CODE_ENTRYPOINT?: string;
 }
 /**
- * Is a real model reachable for the eval / 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. Keeping
- * this a tiny, env-only predicate (not a live probe) means it never spends a
- * token just to decide whether to suggest spending one.
+ * 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;
-export type TriggerSuggestion = "prompt" | "hint" | "none";
-export interface SuggestOpts {
-    /** A real model is reachable (`hasModelAccess`). */
-    readonly modelAccess: boolean;
-    /** stdout is an interactive terminal (a human is watching). */
+/**
+ * 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;
-    /** Count of model-invocable, described skills worth measuring. */
-    readonly triggerableSkills: number;
-    /** `--json` — machine output; never decorate or prompt. */
+    /** `--json` — machine output; stays a read even at a TTY (never prompt). */
     readonly json: boolean;
-    /** `--no-interactive` — explicit agent/CI mode; hint, never prompt. */
+    /** `--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 how `scan` surfaces the trigger tier after its report:
- * - `"none"`   — no model-invocable skills, no model access, or `--json`.
- * - `"hint"`   — model access + skills but non-interactive (agent / CI / non-TTY
- *                / `--no-interactive`): a one-line, non-blocking hint.
- * - `"prompt"` — model access + skills + a human at a TTY: offer to set it up.
+ * 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 decideTriggerSuggestion(o: SuggestOpts): TriggerSuggestion;
-/** The one-line, non-blocking hint (the agent/CI surface). */
-export declare function formatTriggerHint(dir: string, triggerableSkills: number): string;
+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. Deterministic; written
- * only on an explicit human "yes" so a plain `scan` never spends a token.
+ * 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

@@ -1,24 +1,29 @@
 "use strict";
 /**
- * scan → trigger-tier nudge. When a plugin ships model-invocable skills AND a
- * real model is reachable, surface the (real-model) `scan --trigger` tier that
- * measures whether those skills actually FIRE (recall + precision). Pure
- * decision + helpers; the IO (prompt / scaffold write / running the measure)
- * lives in the CLI. Honors `great-agent-flow`: an agent (non-TTY / `--json` /
- * `--no-interactive`) is HINTED, never prompted — a `scan` must never hang.
+ * 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.decideTriggerSuggestion = decideTriggerSuggestion;
-exports.formatTriggerHint = formatTriggerHint;
+exports.isMeteredAccess = isMeteredAccess;
+exports.decideExecute = decideExecute;
+exports.formatExecuteSkip = formatExecuteSkip;
 exports.scaffoldTriggerPrompts = scaffoldTriggerPrompts;
 /**
- * Is a real model reachable for the eval / 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. Keeping
- * this a tiny, env-only predicate (not a live probe) means it never spends a
- * token just to decide whether to suggest spending one.
+ * 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 ||
@@ -26,31 +31,59 @@ function hasModelAccess(env) {
         env.CLAUDE_CODE_ENTRYPOINT);
 }
 /**
- * Decide how `scan` surfaces the trigger tier after its report:
- * - `"none"`   — no model-invocable skills, no model access, or `--json`.
- * - `"hint"`   — model access + skills but non-interactive (agent / CI / non-TTY
- *                / `--no-interactive`): a one-line, non-blocking hint.
- * - `"prompt"` — model access + skills + a human at a TTY: offer to set it up.
+ * 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 decideTriggerSuggestion(o) {
-    if (o.json || o.triggerableSkills < 1 || !o.modelAccess)
-        return "none";
-    if (o.noInteractive || !o.isTTY)
-        return "hint";
-    return "prompt";
+function isMeteredAccess(env) {
+    return Boolean(env.ANTHROPIC_API_KEY);
 }
-/** The one-line, non-blocking hint (the agent/CI surface). */
-function formatTriggerHint(dir, triggerableSkills) {
-    const n = triggerableSkills;
-    return (`ℹ ${String(n)} model-invocable skill${n === 1 ? "" : "s"} + model access detected — ` +
-        `measure whether they actually FIRE (recall + precision) with:\n` +
-        `    vigiles scan ${dir} --trigger --prompts=trigger-prompts.json`);
+/**
+ * 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. Deterministic; written
- * only on an explicit human "yes" so a plain `scan` never spends a token.
+ * placeholders the user replaces with real requests.
  */
 function scaffoldTriggerPrompts(skillNames) {
     const obj = {};

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,8 +92,25 @@ 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.
@@ -194,14 +217,16 @@ 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). */
@@ -227,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;
 /**
@@ -235,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
@@ -69,9 +69,21 @@ function makeClassifier(layout) {
     const skillRe = skill ? new RegExp(`${skill}[^/]+/SKILL\\.md$`) : null;
     const agentRe = agent ? new RegExp(`${agent}[^/]+\\.md$`) : null;
     const commandRe = command ? new RegExp(`${command}.+\\.md$`) : null;
+    // A subagent lives at the plugin's TOP-LEVEL `agents/` dir, never recursively
+    // under a skill (`skills/<x>/agents/`). Those nested files are skill-internal
+    // worker docs (e.g. Anthropic's own skill-creator), NOT dispatchable Claude
+    // Code subagents — flagging them is a false positive. The agent dir nested
+    // under the skill dir is excluded; a genuine top-level `agents/foo.md` still
+    // matches. See scan.test.ts for the regression.
+    const nestedAgentRe = layout.skillDir && layout.agentDir
+        ? new RegExp(`(?:^|/)${escapeRe(layout.skillDir)}/.+/${escapeRe(layout.agentDir)}/`)
+        : null;
+    const isAgent = (f) => (agentRe?.test(f) ?? false) &&
+        !f.endsWith(".spec.ts") &&
+        !(nestedAgentRe?.test(f) ?? false);
     return {
         isSkill: (f) => skillRe?.test(f) ?? false,
-        isAgent: (f) => (agentRe?.test(f) ?? false) && !f.endsWith(".spec.ts"),
+        isAgent,
         isCommand: (f) => commandRe?.test(f) ?? false,
     };
 }
@@ -168,6 +180,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,
         });
@@ -244,7 +257,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
@@ -252,14 +265,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
@@ -284,9 +306,42 @@ function preferCompiledHooksMessage(count) {
         `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) => {
@@ -309,8 +364,9 @@ 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));
@@ -564,14 +620,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
@@ -596,7 +654,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");
@@ -648,7 +706,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) {

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 {