vigiles 9.0.0 → 10.0.0

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/compile.d.ts

@@ -25,7 +25,7 @@ export declare function verifyHash(content: string): {
  */
 /** @internal */ export declare function estimateTokens(text: string): number;
 export interface CompileError {
-    type: "stale-file" | "stale-command" | "stale-ref" | "invalid-rule" | "budget-exceeded" | "section-too-long" | "section-has-header" | "reserved-section-key" | "spec-name-mismatch" | "unknown-tool" | "invalid-railway" | "purity-violation" | "output-without-fork" | "effect-in-skill";
+    type: "stale-file" | "stale-command" | "stale-ref" | "invalid-rule" | "budget-exceeded" | "section-too-long" | "section-has-header" | "reserved-section-key" | "spec-name-mismatch" | "unknown-tool" | "invalid-railway" | "purity-violation" | "output-without-fork" | "effect-in-skill" | "inline-code-too-long";
     message: string;
     path?: string;
 }
@@ -76,6 +76,8 @@ export declare function compileClaude(spec: ClaudeSpec, options?: CompileClaudeO
 export interface CompileSkillResult {
     markdown: string;
     errors: CompileError[];
+    /** Non-blocking advisories (e.g. an over-long inline code block). */
+    warnings: CompileError[];
 }
 /**
  * Compile a SkillSpec into SKILL.md markdown with YAML frontmatter.
@@ -90,6 +92,8 @@ export declare function compileSkill(spec: SkillSpec, options?: {
 export interface CompileAgentResult {
     markdown: string;
     errors: CompileError[];
+    /** Non-blocking advisories (e.g. an over-long inline code block). */
+    warnings: CompileError[];
 }
 /**
  * Compile an AgentSpec into a subagent markdown file with YAML frontmatter.

package/dist/core/compile.js

@@ -664,11 +664,17 @@ function renderSkillSections(spec) {
     return sections.join("\n\n");
 }
 const DEFAULT_MAX_INLINE_CODE_LINES = 20;
-/** Flag inline fenced code blocks longer than `max` lines (0 = disabled). */
+/**
+ * Flag inline fenced code blocks longer than `max` lines (0 = disabled). These
+ * are WARNINGS, not errors: a big inline code block is an authoring smell worth
+ * surfacing ("extract it to a file"), but it never breaks the harness — and a
+ * faithful adoption of an existing skill/subagent (`init`) must still compile.
+ * Callers route the result into a result's `warnings` channel, never `errors`.
+ */
 function checkInlineCode(markdown, max) {
     if (max <= 0)
         return [];
-    const errs = [];
+    const warns = [];
     const lines = markdown.split("\n");
     let start = -1;
     let lang = "";
@@ -683,16 +689,16 @@ function checkInlineCode(markdown, max) {
         else {
             const len = i - start - 1;
             if (len > max) {
-                errs.push({
-                    type: "section-too-long",
-                    message: `Inline ${lang || "code"} block is ${String(len)} lines (max ${String(max)}); extract it to a file and reference it with file().`,
+                warns.push({
+                    type: "inline-code-too-long",
+                    message: `Inline ${lang || "code"} block is ${String(len)} lines (max ${String(max)}); consider extracting it to a file and referencing it with file().`,
                 });
             }
             start = -1;
             lang = "";
         }
     }
-    return errs;
+    return warns;
 }
 /**
  * Compile a SkillSpec into SKILL.md markdown with YAML frontmatter.
@@ -756,14 +762,16 @@ function compileSkill(spec, options = {}) {
         }
     }
     const sections = renderSkillSections(spec);
-    errors.push(...checkInlineCode(sections, spec.maxInlineCodeLines ?? DEFAULT_MAX_INLINE_CODE_LINES));
+    // Over-long inline code blocks are WARNINGS, not errors — they don't block
+    // compilation (so adoption always compiles), just nudge toward file().
+    const warnings = checkInlineCode(sections, spec.maxInlineCodeLines ?? DEFAULT_MAX_INLINE_CODE_LINES);
     const marker = purityMarker(spec.purity);
     const content = renderSkillFrontmatter(spec, profile) +
         "\n\n" +
         (marker ? marker + "\n\n" : "") +
         sections.trim() +
         "\n";
-    return { markdown: addHash(content, specFile), errors };
+    return { markdown: addHash(content, specFile), errors, warnings };
 }
 // ---------------------------------------------------------------------------
 // Compile a subagent spec → agents/<name>.md
@@ -944,14 +952,15 @@ function compileAgent(spec, options) {
     if (spec.output)
         sections.push(renderOutputContract(spec.output));
     const body = sections.join("\n\n");
-    errors.push(...checkInlineCode(body, DEFAULT_MAX_INLINE_CODE_LINES));
+    // Over-long inline code blocks are WARNINGS, not errors (see checkInlineCode).
+    const warnings = checkInlineCode(body, DEFAULT_MAX_INLINE_CODE_LINES);
     const marker = purityMarker(spec.purity);
     const content = renderAgentFrontmatter(spec) +
         "\n\n" +
         (marker ? marker + "\n\n" : "") +
         body.trim() +
         "\n";
-    return { markdown: addHash(content, specFile), errors };
+    return { markdown: addHash(content, specFile), errors, warnings };
 }
 /** Verify a railway: non-empty, bounded recovery, every delegate target real. */
 function validateRailway(rw, knownAgents) {

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,16 @@ 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; // generic small-footgun weight (disallowedTools typo, invalid model/color)
+// Two things are advisory, NOT graded penalties (shown, never scored — see scoreReport):
+//   - untested surfaces — a hardening gap, not breakage.
+//   - an agent that inherits all tools (no `tools:` line) — see reportDeductions for why.
 /** Map a 0–100 structural-health score to its letter grade (A ≥90 … F <60). */
 function gradeFor(score) {
     if (score >= 90)
@@ -55,101 +64,151 @@ 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",
         },
+        // NB: an agent that inherits all tools (no `tools:` line) is ADVISORY, not a
+        // graded penalty — it's surfaced by scoreReport / the Structure ring but never
+        // drags the score. WHY: omitting the `tools:` line is a near-universal,
+        // legitimate authoring style (a measured OSS sweep of 122 real plugins found
+        // 109 whose ONLY finding was this), so penalizing it makes the grade cry wolf
+        // on idiomatic subagents. A health score should mean "something is BROKEN", and
+        // a broad-by-default tool surface is a hardening/least-privilege NUDGE, not
+        // breakage. The count is re-derived where the advisory note is built.
         {
-            n: noContract,
-            weight: 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 };
+    // Advisory notes are surfaced for visibility but DON'T affect the score, so they
+    // come AFTER the real (score-affecting) issues:
+    //   - inherit-all (no tool contract): a least-privilege NUDGE, not breakage —
+    //     see reportDeductions for the full rationale.
+    //   - untested surfaces: a hardening gap, not breakage.
+    const noContract = r.agents.filter((a) => a.tools === null).length;
+    if (noContract > 0) {
+        issues.push(`${String(noContract)} agent(s) inherit all tools (no contract) (advisory)`);
+    }
+    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 +239,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, dead tool/MCP ref -8.", "Inherit-all subagents and untested surfaces are advisory — shown, not scored.");
     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._";
+    "no-description skill −10, broken intra-plugin / dead-tool ref −8. " +
+    "Inherit-all subagents and 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