vigiles 8.0.0 → 9.1.0

package/dist/core/adopt.d.ts

@@ -18,6 +18,7 @@
  * vs `enforce()` is deliberately NOT guessed here — that cross-referencing is
  * `strengthen`'s separate, later job; adoption is lossless transcription.
  */
+import { type SkillSpec, type AgentSpec } from "./spec.js";
 export type AdoptTier = "structured" | "raw";
 export interface AdoptResult {
     /** Generated `.spec.ts` source (compiles back to ~the original file). */
@@ -62,4 +63,31 @@ export declare function adoptToSpec(markdown: string, target: string): AdoptedSp
  * (the deliverable `init` writes).
  */
 export declare function adoptMarkdown(markdown: string, target: string): AdoptResult;
+export interface AdoptSurfaceResult {
+    /** Generated `.spec.ts` source. */
+    source: string;
+    kind: "skill" | "agent";
+    /**
+     * The parsed spec object the source builds — exposed so a round-trip test can
+     * feed it straight to `compileSkill`/`compileAgent` without evaluating the
+     * generated TS (the same split as `adoptToSpec`/`renderSpecSource`).
+     */
+    spec: SkillSpec | AgentSpec;
+    /**
+     * Frontmatter keys present in the source that the typed spec has no field for
+     * — emitted as a `// NOTE:` comment in the source so nothing is lost silently.
+     */
+    unmappedKeys: string[];
+}
+/**
+ * Adopt an existing SKILL.md into a `skill()` spec. The body is carried verbatim
+ * (skills are freeform markdown — `##` headings stay in the body), so a clean
+ * skill round-trips below the integrity header.
+ *
+ * @param markdown the SKILL.md content
+ * @param dirName  the skill's directory name — the CC fallback for `name` when
+ *   frontmatter omits it
+ */
+export declare function adoptSkill(markdown: string, dirName: string): AdoptSurfaceResult;
+export declare function adoptAgent(markdown: string, fileBase: string): AdoptSurfaceResult;
 //# sourceMappingURL=adopt.d.ts.map

package/dist/core/adopt.js

@@ -22,7 +22,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.adoptToSpec = adoptToSpec;
 exports.adoptMarkdown = adoptMarkdown;
+exports.adoptSkill = adoptSkill;
+exports.adoptAgent = adoptAgent;
 const integrity_js_1 = require("./integrity.js");
+const frontmatter_read_js_1 = require("./frontmatter-read.js");
+const spec_js_1 = require("./spec.js");
 // A top-level heading is `#` or `##` (the levels the compiler reserves for
 // document/section structure). `###`+ stay inside a section body.
 const HEADING_RE = /^ {0,3}(#{1,2})\s+(.*)$/;
@@ -196,4 +200,203 @@ function adoptMarkdown(markdown, target) {
         sectionCount: Object.keys(spec.sections).length,
     };
 }
+// Consumes the WHOLE leading frontmatter block (through its closing `---` and the
+// trailing newline) so the remainder is the verbatim body — mirrors BLOCK_RE in
+// frontmatter-read.ts but matches past the closing fence.
+const FRONTMATTER_CONSUME_RE = /^\uFEFF?(?:<!--[\s\S]*?-->\s*)?---\r?\n[\s\S]*?\r?\n---[ \t]*\r?\n?/;
+function splitFrontmatterBody(markdown) {
+    const fm = (0, frontmatter_read_js_1.readFrontmatter)(markdown);
+    if (fm.block === null)
+        return { fm, body: markdown.replace(/^\uFEFF/, "") };
+    const m = FRONTMATTER_CONSUME_RE.exec(markdown);
+    return { fm, body: m ? markdown.slice(m[0].length) : markdown };
+}
+/** The first non-empty, non-heading paragraph — the CC fallback for a skill's
+ * description when its frontmatter omits one (name←dir, description←first ¶). */
+function firstParagraph(body) {
+    const para = [];
+    let started = false;
+    for (const line of body.split("\n")) {
+        const t = line.trim();
+        if (!started) {
+            if (t === "" || /^#{1,6}\s/.test(t))
+                continue;
+            started = true;
+            para.push(t);
+        }
+        else {
+            if (t === "")
+                break;
+            para.push(t);
+        }
+    }
+    return para.join(" ").trim();
+}
+/** Keys the typed spec models — everything else is reported as unmapped. */
+const SKILL_KNOWN_KEYS = new Set([
+    "name",
+    "description",
+    "allowed-tools",
+    "tools",
+    "disable-model-invocation",
+    "argument-hint",
+    "context",
+]);
+const AGENT_KNOWN_KEYS = new Set([
+    "name",
+    "description",
+    "model",
+    "color",
+    "tools",
+    "disallowedTools",
+    "disallowed-tools",
+]);
+function unmappedFrontmatterKeys(fm, known) {
+    if (!fm.data)
+        return [];
+    return Object.keys(fm.data).filter((k) => !known.has(k));
+}
+/** A `// NOTE:` banner naming any frontmatter keys we couldn't represent. */
+function unmappedNote(kind, keys) {
+    if (keys.length === 0)
+        return "";
+    return (`// NOTE: these frontmatter keys had no ${kind}() field and were left out —\n` +
+        `// re-add them by hand if they matter: ${keys.join(", ")}\n`);
+}
+const SURFACE_HEADER = (from) => `// Adopted from ${from} by \`vigiles init\` — body verbatim, standard\n` +
+    `// frontmatter mapped; no rules inferred. Review the diff, then \`compile\`.\n`;
+/**
+ * Adopt an existing SKILL.md into a `skill()` spec. The body is carried verbatim
+ * (skills are freeform markdown — `##` headings stay in the body), so a clean
+ * skill round-trips below the integrity header.
+ *
+ * @param markdown the SKILL.md content
+ * @param dirName  the skill's directory name — the CC fallback for `name` when
+ *   frontmatter omits it
+ */
+function adoptSkill(markdown, dirName) {
+    const { fm, body } = splitFrontmatterBody(markdown);
+    const name = (0, frontmatter_read_js_1.frontmatterScalar)(fm, "name") ?? dirName;
+    const description = (0, frontmatter_read_js_1.frontmatterScalar)(fm, "description") ?? firstParagraph(body) ?? name;
+    const tools = (0, frontmatter_read_js_1.frontmatterList)(fm, "allowed-tools") ?? (0, frontmatter_read_js_1.frontmatterList)(fm, "tools");
+    const argumentHint = (0, frontmatter_read_js_1.frontmatterScalar)(fm, "argument-hint");
+    const disableModelInvocation = (0, frontmatter_read_js_1.frontmatterScalar)(fm, "disable-model-invocation") === "true";
+    const unmappedKeys = unmappedFrontmatterKeys(fm, SKILL_KNOWN_KEYS);
+    const lines = [
+        `  name: ${JSON.stringify(name)},`,
+        `  description: ${JSON.stringify(description)},`,
+    ];
+    if (argumentHint)
+        lines.push(`  argumentHint: ${JSON.stringify(argumentHint)},`);
+    if (disableModelInvocation)
+        lines.push(`  disableModelInvocation: true,`);
+    if (tools && tools.length > 0)
+        lines.push(`  tools: ${JSON.stringify(tools)},`);
+    const trimmedBody = body.trim();
+    if (trimmedBody)
+        lines.push(`  body: ${tsTemplate(trimmedBody)},`);
+    const spec = (0, spec_js_1.skill)({
+        name,
+        description,
+        ...(argumentHint ? { argumentHint } : {}),
+        ...(disableModelInvocation ? { disableModelInvocation: true } : {}),
+        ...(tools && tools.length > 0 ? { tools } : {}),
+        ...(trimmedBody ? { body: trimmedBody } : {}),
+    });
+    const source = SURFACE_HEADER(`${dirName}/SKILL.md`) +
+        unmappedNote("skill", unmappedKeys) +
+        `import { skill } from "vigiles/spec";\n\n` +
+        `export default skill({\n${lines.join("\n")}\n});\n`;
+    return { source, kind: "skill", spec, unmappedKeys };
+}
+/**
+ * Adopt an existing subagent (`agents/<name>.md`) into an `agent()` spec. Unlike
+ * a skill, an agent's `sections` reject `##` headers, so the body is split: the
+ * lead preamble becomes `body` and each `##`/`#` heading becomes a named section
+ * (reusing the instruction-file splitter). The tool contract is carried as-is —
+ * if the source lists a never-available tool, the generated spec surfaces it on
+ * `compile` (which is the point).
+ *
+ * @param markdown the subagent file content
+ * @param fileBase the file's base name (sans `.md`) — the fallback for `name`
+ */
+/** Split a subagent system prompt: preamble → `body`, each `#`/`##` heading →
+ * a named section (agent `sections` reject `##` in the body, so they're hoisted). */
+function splitAgentBody(body) {
+    const blocks = splitIntoBlocks(body);
+    let lead = "";
+    const used = new Set();
+    const sectionEntries = [];
+    for (const block of blocks) {
+        if (block.level === null) {
+            lead = block.lines.join("\n").trim();
+        }
+        else {
+            sectionEntries.push({
+                key: allocKey(safeKey(block.heading ?? ""), used),
+                content: block.lines.join("\n").trim(),
+            });
+        }
+    }
+    return { lead, sectionEntries };
+}
+/** Render the `agent({…})` source lines from the extracted fields. */
+function buildAgentLines(f) {
+    const lines = [
+        `  name: ${JSON.stringify(f.name)},`,
+        `  description: ${JSON.stringify(f.description)},`,
+    ];
+    if (f.model)
+        lines.push(`  model: ${JSON.stringify(f.model)},`);
+    if (f.color)
+        lines.push(`  color: ${JSON.stringify(f.color)},`);
+    if (f.tools && f.tools.length > 0)
+        lines.push(`  tools: ${JSON.stringify(f.tools)},`);
+    if (f.disallowedTools && f.disallowedTools.length > 0)
+        lines.push(`  disallowedTools: ${JSON.stringify(f.disallowedTools)},`);
+    if (f.lead)
+        lines.push(`  body: ${tsTemplate(f.lead)},`);
+    if (f.sectionEntries.length > 0) {
+        const entries = f.sectionEntries
+            .map(({ key, content }) => `    ${JSON.stringify(key)}: ${tsTemplate(content)},`)
+            .join("\n");
+        lines.push(`  sections: {\n${entries}\n  },`);
+    }
+    return lines;
+}
+function adoptAgent(markdown, fileBase) {
+    const { fm, body } = splitFrontmatterBody(markdown);
+    const name = (0, frontmatter_read_js_1.frontmatterScalar)(fm, "name") ?? fileBase;
+    const f = {
+        name,
+        description: (0, frontmatter_read_js_1.frontmatterScalar)(fm, "description") ?? name,
+        model: (0, frontmatter_read_js_1.frontmatterScalar)(fm, "model"),
+        color: (0, frontmatter_read_js_1.frontmatterScalar)(fm, "color"),
+        tools: (0, frontmatter_read_js_1.frontmatterList)(fm, "tools"),
+        disallowedTools: (0, frontmatter_read_js_1.frontmatterList)(fm, "disallowedTools") ??
+            (0, frontmatter_read_js_1.frontmatterList)(fm, "disallowed-tools"),
+        ...splitAgentBody(body),
+    };
+    const unmappedKeys = unmappedFrontmatterKeys(fm, AGENT_KNOWN_KEYS);
+    const sections = {};
+    for (const { key, content } of f.sectionEntries)
+        sections[key] = content;
+    const spec = (0, spec_js_1.agent)({
+        name: f.name,
+        description: f.description,
+        ...(f.model ? { model: f.model } : {}),
+        ...(f.color ? { color: f.color } : {}),
+        ...(f.tools && f.tools.length > 0 ? { tools: f.tools } : {}),
+        ...(f.disallowedTools && f.disallowedTools.length > 0
+            ? { disallowedTools: f.disallowedTools }
+            : {}),
+        ...(f.lead ? { body: f.lead } : {}),
+        ...(f.sectionEntries.length > 0 ? { sections } : {}),
+    });
+    const source = SURFACE_HEADER(`${fileBase}.md`) +
+        unmappedNote("agent", unmappedKeys) +
+        `import { agent } from "vigiles/spec";\n\n` +
+        `export default agent({\n${buildAgentLines(f).join("\n")}\n});\n`;
+    return { source, kind: "agent", spec, unmappedKeys };
+}
 //# sourceMappingURL=adopt.js.map

package/dist/core/inline.js

@@ -35,6 +35,16 @@ const ENFORCE_RE = /<!--\s*vigiles:enforce\s+([@A-Za-z0-9_/:.-]+)\s+"([^"\n]*)"\
  * ambiguous against the closing `-->`.
  */
 const FILE_RE = /<!--\s*vigiles:file\s+(\S+)\s*-->/;
+/**
+ * Strip a single surrounding pair of matching quotes from a captured token.
+ * The documented `vigiles:file` syntax is an unquoted path, but users
+ * reasonably quote it for symmetry with `vigiles:cmd "..."` — without this,
+ * the quotes become part of the path, so it never resolves and the error
+ * reads `File not found: ""path""`. Normalize at the parse boundary.
+ */
+function unquote(token) {
+    return /^"[^]*"$|^'[^]*'$/.test(token) ? token.slice(1, -1) : token;
+}
 /**
  * Match `<!-- vigiles:cmd "<command>" -->`. The command is quoted because
  * commands contain spaces (e.g. `npm run build`).
@@ -122,7 +132,7 @@ function parseInlineRules(content) {
         }
         const fileMatch = FILE_RE.exec(scannable);
         if (fileMatch) {
-            files.push({ path: fileMatch[1], line: i + 1 });
+            files.push({ path: unquote(fileMatch[1]), line: i + 1 });
             continue;
         }
         const cmdMatch = CMD_RE.exec(scannable);

package/dist/core/types.d.ts

@@ -263,6 +263,18 @@ export interface VigilesConfig {
      * `"claude-code"`. See research/multi-harness-compile.md.
      */
     harness?: string | string[];
+    /**
+     * `vigiles audit` preferences. `measure` is the sticky remembered answer to the
+     * "run the executing checks against your harness?" prompt — at a TTY `audit`
+     * asks once, then records the choice here so it never asks again. `true` runs
+     * the executing checks (safety battery · live MCP · skill firing) on every
+     * interactive run, `false` keeps them off (edit this key to change). Written by
+     * the audit consent prompt, not `init`. Headless runs never execute regardless
+     * (audit is a local report, not a CI step — there is no execution flag).
+     */
+    audit?: {
+        measure?: boolean;
+    };
 }
 /** Valid marker types for rule detection. */
 export type MarkerType = "headings" | "checkboxes";

package/dist/dialect-drift.js

@@ -40,7 +40,7 @@ exports.formatDialectDrift = formatDialectDrift;
  *
  * Pure parsers (testable with fixtures) + a local-install locator. TWO consumers:
  * the gated CI test in `dialect-drift.test.ts` (fails loud on tool/event drift), and
- * `vigiles scan` at runtime via `checkDialectDrift`/`formatDialectDrift` (a best-effort,
+ * `vigiles audit` at runtime via `checkDialectDrift`/`formatDialectDrift` (a best-effort,
  * read-local freshness WARN when the installed CC's tool surface drifts from ours).
  */
 const node_fs_1 = require("node:fs");

package/dist/eval.d.ts

@@ -251,7 +251,7 @@ export type AgentRunner = (args: AgentRunArgs) => Promise<RunOut>;
  */
 export declare function resolveSpawnEnv(a: Pick<AgentRunArgs, "env" | "replaceEnv">, base?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 /** The real `claude`-spawning runner (composition root). Exported so other
- *  real-model entries (e.g. `scan --trigger`) bind the same runner. */
+ *  real-model entries (e.g. the `audit` trigger tier) bind the same runner. */
 export declare function spawnAgent(a: AgentRunArgs): Promise<RunOut>;
 /**
  * Run the eval: every arm × every trial against the real `claude` CLI, with the

package/dist/eval.js

@@ -96,7 +96,7 @@ function resolveSpawnEnv(a, base = process.env) {
 }
 /* v8 ignore start -- real claude subprocess; exercised by bench/, not the unit gate */
 /** The real `claude`-spawning runner (composition root). Exported so other
- *  real-model entries (e.g. `scan --trigger`) bind the same runner. */
+ *  real-model entries (e.g. the `audit` trigger tier) bind the same runner. */
 function spawnAgent(a) {
     return new Promise((resolvePromise) => {
         const args = [

package/dist/leaderboard.d.ts

@@ -21,8 +21,40 @@ export interface PluginScore {
     readonly issues: readonly string[];
     readonly report: ScanReport;
 }
+export declare const W_MISSING_HOOK = 15;
+export declare const W_NO_DESCRIPTION = 10;
+export declare const W_DANGLING_REF = 8;
+export declare const W_OVERLAP = 8;
+export declare const W_NO_CONTRACT = 5;
 /** Map a 0–100 structural-health score to its letter grade (A ≥90 … F <60). */
 export declare function gradeFor(score: number): PluginScore["grade"];
+/** One deduction: a count, its per-item weight, and the label if non-zero. */
+export interface Deduction {
+    readonly n: number;
+    readonly weight: number;
+    readonly label: string;
+}
+/**
+ * The COMPLETE graded-penalty list a report incurs — the single source of truth
+ * BOTH the leaderboard's single health number and the audit's category rings
+ * read, so the overall can never drift between the two surfaces. Each entry is a
+ * graded penalty; untested surfaces are deliberately ABSENT (they're advisory,
+ * surfaced separately, never scored).
+ */
+export declare function reportDeductions(r: ScanReport): Deduction[];
+/** True when a report has no loadable plugin surface at all (the empty machine). */
+export declare function isEmptyMachine(r: ScanReport): boolean;
+/**
+ * THE shared integrity score — `100 − Σ(all graded penalties)`, clamped to
+ * [0,100]. Both the leaderboard's single health number AND the audit's headline
+ * overall read this, so the two can never disagree (the summed model is the
+ * honest one — averaging rings would dilute a real problem). Returns the score
+ * plus the per-item deductions so callers render their own issue/finding lists.
+ */
+export declare function computeIntegrityScore(deductions: readonly Deduction[]): {
+    score: number;
+    penalty: number;
+};
 /** Deterministic structural-health score for one scanned plugin. */
 export declare function scoreReport(r: ScanReport): {
     score: number;

package/dist/leaderboard.js

@@ -12,7 +12,11 @@
  * model and stack on top later; this part runs anywhere in CI for free.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.W_NO_CONTRACT = exports.W_OVERLAP = exports.W_DANGLING_REF = exports.W_NO_DESCRIPTION = exports.W_MISSING_HOOK = void 0;
 exports.gradeFor = gradeFor;
+exports.reportDeductions = reportDeductions;
+exports.isEmptyMachine = isEmptyMachine;
+exports.computeIntegrityScore = computeIntegrityScore;
 exports.scoreReport = scoreReport;
 exports.rankPlugins = rankPlugins;
 exports.formatLeaderboard = formatLeaderboard;
@@ -38,11 +42,14 @@ function pluginLabel(dir) {
     return (0, node_path_1.basename)(dir) || dir;
 }
 // Penalty weights — broken-at-runtime costs most, footguns less, nudges least.
-const W_MISSING_HOOK = 15; // a hook script that doesn't exist → never runs
-const W_NO_DESCRIPTION = 10; // a skill with no usable description → can't trigger
-const W_DANGLING_REF = 8; // a referenced intra-plugin file that's missing → broken path
-const W_NO_CONTRACT = 5; // an agent with no `tools:` line → inherits everything
-const W_UNTESTED = 3; // a surface with no test/eval → warning-tier
+// Exported so the category view (audit-score.ts) reuses the SAME weights and the
+// two surfaces can never drift on a per-item cost.
+exports.W_MISSING_HOOK = 15; // a hook script that doesn't exist → never runs
+exports.W_NO_DESCRIPTION = 10; // a skill with no usable description → can't trigger
+exports.W_DANGLING_REF = 8; // a referenced intra-plugin file that's missing → broken path
+exports.W_OVERLAP = 8; // a description collision → the wrong skill fires
+exports.W_NO_CONTRACT = 5; // an agent with no `tools:` line → inherits everything
+// (untested surfaces are advisory, not a penalty — see scoreReport)
 /** Map a 0–100 structural-health score to its letter grade (A ≥90 … F <60). */
 function gradeFor(score) {
     if (score >= 90)
@@ -55,101 +62,142 @@ function gradeFor(score) {
         return "D";
     return "F";
 }
-/** Deterministic structural-health score for one scanned plugin. */
-function scoreReport(r) {
-    // An empty/unloadable machine isn't healthy — it's a non-plugin or a broken
-    // load. A command-only or MCP-only plugin (commands/*.md or .mcp.json with no
-    // skills/agents/hooks) IS a legitimate plugin, though — Anthropic ships
-    // command-only plugins in its own marketplace — so it must NOT score 0.
-    const surfaces = r.skills.length + r.agents.length + r.hooks.length + r.commands;
-    if (surfaces === 0 && !r.mcp) {
-        return { score: 0, issues: ["no loadable plugin surface"] };
-    }
+/**
+ * The COMPLETE graded-penalty list a report incurs — the single source of truth
+ * BOTH the leaderboard's single health number and the audit's category rings
+ * read, so the overall can never drift between the two surfaces. Each entry is a
+ * graded penalty; untested surfaces are deliberately ABSENT (they're advisory,
+ * surfaced separately, never scored).
+ */
+function reportDeductions(r) {
     const missingHooks = r.hooks.filter((h) => h.status === "missing").length;
     const noDesc = r.skills.filter((s) => !s.hasDescription).length;
     const noContract = r.agents.filter((a) => a.tools === null).length;
     const deadTools = r.agents.reduce((n, a) => n + a.toolIssues.length, 0);
     const deadMcpTools = r.agents.reduce((n, a) => n + a.mcpToolIssues.length, 0);
     const deadDisallowed = r.agents.reduce((n, a) => n + a.disallowedToolIssues.length, 0);
-    const deadHookEvents = r.hookEventIssues.length;
-    const badFrontmatter = r.frontmatterIssues.length;
-    const badFrontmatterValues = r.frontmatterValueIssues.length;
-    const badMcp = r.mcpIssues.length;
-    const badMcpHooks = r.mcpHookIssues.length;
-    const deductions = [
+    return [
         {
             n: missingHooks,
-            weight: W_MISSING_HOOK,
+            weight: exports.W_MISSING_HOOK,
             label: "hook script(s) MISSING",
         },
         {
-            n: deadHookEvents,
-            weight: W_MISSING_HOOK,
+            n: r.hookEventIssues.length,
+            weight: exports.W_MISSING_HOOK,
             label: "hook(s) on an unknown event (never fire)",
         },
         {
             n: noDesc,
-            weight: W_NO_DESCRIPTION,
+            weight: exports.W_NO_DESCRIPTION,
             label: "skill(s) with no usable description",
         },
+        {
+            n: r.descriptionOverlaps.length,
+            weight: exports.W_OVERLAP,
+            label: "near-identical skill description(s) (wrong one fires)",
+        },
         {
             n: r.danglingRefs.length,
-            weight: W_DANGLING_REF,
+            weight: exports.W_DANGLING_REF,
             label: "broken intra-plugin reference(s)",
         },
         {
             n: deadTools,
-            weight: W_DANGLING_REF,
+            weight: exports.W_DANGLING_REF,
             label: "agent tool(s) that don't exist (typo / never-available)",
         },
         {
             n: deadMcpTools,
-            weight: W_DANGLING_REF,
+            weight: exports.W_DANGLING_REF,
             label: "agent MCP tool(s) whose server isn't declared (can't resolve)",
         },
         {
             n: deadDisallowed,
-            weight: W_NO_CONTRACT,
+            weight: exports.W_NO_CONTRACT,
             label: "agent disallowedTools typo(s) that block nothing",
         },
         {
             n: noContract,
-            weight: W_NO_CONTRACT,
+            weight: exports.W_NO_CONTRACT,
             label: "agent(s) inherit all tools (no contract)",
         },
         {
-            n: badFrontmatter,
-            weight: W_NO_DESCRIPTION,
+            n: r.frontmatterIssues.length,
+            weight: exports.W_NO_DESCRIPTION,
             label: "surface(s) missing required frontmatter (name/description)",
         },
         {
-            n: badFrontmatterValues,
-            weight: W_NO_CONTRACT,
+            n: r.frontmatterValueIssues.length,
+            weight: exports.W_NO_CONTRACT,
             label: "agent(s) with an invalid model/color (typo → silent fallback)",
         },
         {
-            n: badMcp,
-            weight: W_DANGLING_REF,
+            n: r.mcpIssues.length,
+            weight: exports.W_DANGLING_REF,
             label: "MCP server(s) that can't start (no command/url)",
         },
         {
-            n: badMcpHooks,
-            weight: W_DANGLING_REF,
+            n: r.mcpHookIssues.length,
+            weight: exports.W_DANGLING_REF,
             label: "mcp_tool hook(s) incomplete / targeting an undeclared server",
         },
-        { n: r.untested, weight: W_UNTESTED, label: "untested surface(s)" },
+        // NB: untested surfaces are NOT a penalty — an untested surface is a hardening
+        // gap, not breakage, so it never drags the health score (it's appended as an
+        // advisory note below). The score ranks what's BROKEN.
     ];
+}
+/** True when a report has no loadable plugin surface at all (the empty machine). */
+function isEmptyMachine(r) {
+    const surfaces = r.skills.length +
+        r.agents.length +
+        r.hooks.length +
+        r.inlineHooks +
+        r.commands;
+    return surfaces === 0 && !r.mcp;
+}
+/**
+ * THE shared integrity score — `100 − Σ(all graded penalties)`, clamped to
+ * [0,100]. Both the leaderboard's single health number AND the audit's headline
+ * overall read this, so the two can never disagree (the summed model is the
+ * honest one — averaging rings would dilute a real problem). Returns the score
+ * plus the per-item deductions so callers render their own issue/finding lists.
+ */
+function computeIntegrityScore(deductions) {
     let penalty = 0;
+    for (const d of deductions) {
+        if (d.n <= 0)
+            continue;
+        penalty += d.n * d.weight;
+    }
+    return { score: Math.max(0, 100 - penalty), penalty };
+}
+/** Deterministic structural-health score for one scanned plugin. */
+function scoreReport(r) {
+    // An empty/unloadable machine isn't healthy — it's a non-plugin or a broken
+    // load. A command-only or MCP-only plugin (commands/*.md or .mcp.json with no
+    // skills/agents/hooks) IS a legitimate plugin, though — Anthropic ships
+    // command-only plugins in its own marketplace — so it must NOT score 0.
+    const surfaces = r.skills.length + r.agents.length + r.hooks.length + r.commands;
+    if (surfaces === 0 && !r.mcp) {
+        return { score: 0, issues: ["no loadable plugin surface"] };
+    }
+    const deductions = reportDeductions(r);
+    const { score } = computeIntegrityScore(deductions);
     const issues = [];
     for (const d of deductions) {
         if (d.n === 0)
             continue;
-        penalty += d.n * d.weight;
         issues.push(`${String(d.n)} ${d.label}`);
     }
     // Sort issues by cost (worst first) so the report leads with what matters.
     issues.sort((a, b) => Number(b.split(" ")[0]) - Number(a.split(" ")[0]));
-    return { score: Math.max(0, 100 - penalty), issues };
+    // Untested surfaces are advisory — surfaced for visibility, but they don't
+    // affect the score, so they come AFTER the real (score-affecting) issues.
+    if (r.untested > 0) {
+        issues.push(`${String(r.untested)} untested surface(s) (advisory)`);
+    }
+    return { score, issues };
 }
 /** Scan + score each directory, ranked best-first (ties broken by name). */
 function rankPlugins(dirs) {
@@ -180,13 +228,13 @@ function formatLeaderboard(scores) {
         const issue = s.issues.length > 0 ? ` — ${s.issues.join("; ")}` : "";
         out.push(`  ${rank}  ${score}    ${s.grade}      ${s.name}${issue}`);
     });
-    out.push("", "Structural health only (no model). Weights: missing hook -15, no-description", "skill -10, broken intra-plugin ref -8, agent-without-tool-contract -5,", "untested surface -3.");
+    out.push("", "Structural health only (no model). Weights: missing hook -15, no-description", "skill -10, broken intra-plugin ref -8, agent-without-tool-contract -5.", "Untested surfaces are advisory — shown, but they don't affect the score.");
     return out.join("\n");
 }
 const LEADERBOARD_METHOD = "_Structural health only (deterministic, no model): missing hook −15, " +
     "no-description skill −10, broken intra-plugin ref −8, " +
-    "agent-without-tool-contract −5, untested surface −3. " +
-    "Behavioural columns (trigger-rate, collisions, egress) stack on top._";
+    "agent-without-tool-contract −5. Untested surfaces are advisory (shown, not " +
+    "scored). Behavioural columns (trigger-rate, collisions, egress) stack on top._";
 /**
  * Format a ranked leaderboard as a Markdown table — the PUBLISHABLE form (a README,
  * a gist, the leaderboard site). Shows the top 2 deductions per plugin; the full

package/dist/optimize.d.ts

@@ -1,9 +1,9 @@
 /**
- * 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
@@ -69,6 +69,13 @@ export interface OptimizeReport {
  * before `possible` proxies, via explainScore's own ordering). Pure over the report.
  */
 export declare function optimize(report: ScanReport): OptimizeReport;
+/**
+ * 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.
+ */
+export declare function formatRecommendations(rep: OptimizeReport): string;
 /** Render an optimization plan for the CLI. */
 export declare function formatOptimize(rep: OptimizeReport): string;
 //# sourceMappingURL=optimize.d.ts.map