vigiles 9.1.0 → 10.0.0

package/dist/cli.js

@@ -34,6 +34,7 @@ const optimize_js_1 = require("./optimize.js");
 const audit_score_js_1 = require("./audit-score.js");
 const audit_prompts_js_1 = require("./audit-prompts.js");
 const audit_html_js_1 = require("./audit-html.js");
+const audit_serve_js_1 = require("./audit-serve.js");
 const audit_report_js_1 = require("./audit-report.js");
 const adoptability_js_1 = require("./adoptability.js");
 const compile_js_1 = require("./core/compile.js");
@@ -140,6 +141,14 @@ function printErrors(specFile, errors) {
         console.log(`::error file=${specFile}::${err.message}`);
     }
 }
+/** Non-blocking advisories — printed, but never fail the compile. */
+function printWarnings(specFile, warnings) {
+    for (const w of warnings) {
+        const pathInfo = w.path ? ` (${w.path})` : "";
+        console.log(`  ⚠ [${w.type}] ${w.message}${pathInfo}`);
+        console.log(`::warning file=${specFile}::${w.message}`);
+    }
+}
 // ---------------------------------------------------------------------------
 // Commands
 // ---------------------------------------------------------------------------
@@ -238,7 +247,7 @@ function writeInstructionMirrors(primaryOutput, harnesses) {
 /** Compile a declarative SkillSpec → SKILL.md. */
 function compileSkillToFile(spec, specPath, dialect) {
     const outputPath = specPath.replace(/\.spec\.ts$/, "");
-    const { markdown, errors } = (0, compile_js_1.compileSkill)(spec, {
+    const { markdown, errors, warnings } = (0, compile_js_1.compileSkill)(spec, {
         basePath: process.cwd(),
         specFile: specPath,
         // The SKILL.md frontmatter profile comes from the resolved harness — a Codex
@@ -248,16 +257,18 @@ function compileSkillToFile(spec, specPath, dialect) {
     (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(process.cwd(), outputPath), markdown);
     if (errors.length === 0) {
         console.log(`\n✓ ${specPath} → ${outputPath}`);
+        printWarnings(specPath, warnings);
         return true;
     }
     console.log(`\n✗ ${specPath} — ${String(errors.length)} error(s)`);
     printErrors(specPath, errors);
+    printWarnings(specPath, warnings);
     return false;
 }
 /** Compile a subagent spec → agents/<name>.md (with its result-contract section). */
 function compileAgentToFile(spec, specPath, dialect) {
     const outputPath = specPath.replace(/\.spec\.ts$/, "");
-    const { markdown, errors } = (0, compile_js_1.compileAgent)(spec, {
+    const { markdown, errors, warnings } = (0, compile_js_1.compileAgent)(spec, {
         basePath: process.cwd(),
         specFile: specPath,
         dialect,
@@ -265,10 +276,12 @@ function compileAgentToFile(spec, specPath, dialect) {
     (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(process.cwd(), outputPath), markdown);
     if (errors.length === 0) {
         console.log(`\n✓ ${specPath} → ${outputPath}`);
+        printWarnings(specPath, warnings);
         return true;
     }
     console.log(`\n✗ ${specPath} — ${String(errors.length)} error(s)`);
     printErrors(specPath, errors);
+    printWarnings(specPath, warnings);
     return false;
 }
 /**
@@ -819,8 +832,26 @@ function verifyFrontmatterRules(filePath, silent, exclude, linterOptions) {
     };
 }
 /**
- * Verify inline `<!-- vigiles:enforce -->` comments and `vigiles:` YAML
- * frontmatter in instruction files that aren't managed by a spec.
+ * Frontmatter mode (Level 1 — a `vigiles:` YAML block) is DISABLED in lint:
+ * KEPT IN CODE (`src/core/frontmatter.ts`, `verifyFrontmatterRules`,
+ * `vigiles generate schema`), but INERT — lint no longer reads or verifies a
+ * `vigiles:` block, so it never fires and never fails a build.
+ *
+ * WHY disabled-not-removed: the three-rung adoption ladder (inline / frontmatter
+ * / typed spec) collapsed to TWO on-ramps — inline comments (the zero-TS floor)
+ * and the typed `.spec.ts` (the source of truth). Frontmatter mode was the
+ * weakest middle rung and an undocumented-but-live surface that muddied the
+ * spec-first story (it literally confused a review). With ~no users to break,
+ * gating it off makes lint coherent (verify compiled output + inline marks +
+ * specs, nothing else) while preserving the code so the decision is reversible:
+ * flip this to `true` to re-enable. See `research/pre-release-focus.md` and the
+ * parked note in `docs/markdown-mode.md`.
+ */
+const FRONTMATTER_MODE_ENABLED = false;
+/**
+ * Verify inline `<!-- vigiles:enforce -->` comments (and, when
+ * {@link FRONTMATTER_MODE_ENABLED}, `vigiles:` YAML frontmatter) in instruction
+ * files that aren't managed by a spec.
  *
  * Spec mode is the source of truth when it exists, so a literal
  * `<!-- vigiles:enforce ... -->` snippet that survived into compiled
@@ -861,9 +892,13 @@ function verifyMarkdownModeRules(files, silent, config) {
         const inline = verifyInlineRules(filePath, silent, linterOptions);
         totals.inlineErrors += inline.errorCount;
         totals.inlineRules += inline.ruleCount;
-        const fm = verifyFrontmatterRules(filePath, silent, new Set(inline.ruleNames), linterOptions);
-        totals.frontmatterErrors += fm.errorCount;
-        totals.frontmatterRules += fm.ruleCount;
+        // Frontmatter mode is DISABLED (kept in code, inert in lint) — a `vigiles:`
+        // block is ignored, never verified. See FRONTMATTER_MODE_ENABLED.
+        if (FRONTMATTER_MODE_ENABLED) {
+            const fm = verifyFrontmatterRules(filePath, silent, new Set(inline.ruleNames), linterOptions);
+            totals.frontmatterErrors += fm.errorCount;
+            totals.frontmatterRules += fm.ruleCount;
+        }
     }
     if (!silent &&
         files.length > 0 &&
@@ -3330,6 +3365,7 @@ function printUsage(command) {
     console.log("  vigiles audit [dir...]          Lighthouse for your harness — a LOCAL report: rings + what's broken + fixes (a deterministic read; 2+ dirs → leaderboard)");
     console.log("                                 writes vigiles-report.html + vigiles-report.json (--no-html/--no-json) · --json for machine output. NOT a CI step — use `vigiles lint` in CI.");
     console.log("                                 the executing checks (run your hooks · live MCP · do skills fire?) run only interactively — `audit` asks once (remembered); automation uses the vigiles/testing API");
+    console.log("                                 --serve opens a LIVE local report whose buttons create specs in one click (own repo only; loopback + token-guarded) · --no-serve to skip the prompt");
     console.log("  vigiles test [files...]        Run *.harness.mjs deterministic harness tests");
     console.log("  vigiles eval [files...]        Run *.eval.mjs real-model harness evals (--trials=N, --min=N, --no-skip)");
     console.log("  vigiles scaffold-test [dir]    Generate a starter test for each untested skill/agent/hook (--write, --json)");
@@ -4186,6 +4222,63 @@ function writeAuditHtml(report) {
         console.log(`\n⚠ skipped vigiles-report.html: ${e instanceof Error ? e.message : String(e)}`);
     }
 }
+/**
+ * Start the live (`--serve`) adoption server: render the report with a per-run
+ * token, serve it on loopback, and run `init` in-process when a button POSTs. The
+ * security model lives in src/audit-serve.ts (token + Origin + allowlist). Blocks
+ * until the user stops it (Ctrl-C or the page's Done). Own-repo only — the caller
+ * gates this via decideServeGate, so adopt always writes into the current repo.
+ */
+async function runAuditServe(report, adoptable, cliErr) {
+    const token = (0, audit_serve_js_1.newToken)();
+    const surfaces = new Set((adoptable?.surfaces ?? []).map((s) => s.path));
+    let html;
+    try {
+        html = (0, audit_html_js_1.renderAuditHtml)(report, { token });
+    }
+    catch (e) {
+        console.log(`\n⚠ can't serve the live report: ${cliErr(e)}`);
+        return;
+    }
+    const adoptOne = (target) => {
+        try {
+            scaffoldSpec(["--target=" + target]); // in-process; writes into cwd (own repo)
+            return Promise.resolve({
+                ok: true,
+                message: `created spec for ${target}`,
+            });
+        }
+        catch (e) {
+            return Promise.resolve({ ok: false, message: cliErr(e) });
+        }
+    };
+    console.log("\n  Live report — create specs with one click. Ctrl-C to stop.\n");
+    await (0, audit_serve_js_1.serveAudit)({
+        token,
+        surfaces,
+        html,
+        runAdopt: adoptOne,
+        runAdoptAll: () => {
+            try {
+                for (const p of surfaces)
+                    scaffoldSpec(["--target=" + p]);
+                return Promise.resolve({
+                    ok: true,
+                    message: `created ${String(surfaces.size)} spec(s)`,
+                });
+            }
+            catch (e) {
+                return Promise.resolve({ ok: false, message: cliErr(e) });
+            }
+        },
+        onListening: (url) => {
+            console.log(`  ${url}`);
+            if (process.stdout.isTTY)
+                openBestEffort(url);
+        },
+    });
+    console.log("\n✓ live report closed");
+}
 /**
  * Run the model trigger tier with no `--prompts`: auto-generate diverse probe
  * prompts from each skill's description and measure trigger-rate (recall +
@@ -4210,19 +4303,54 @@ async function runAutoTrigger(dir, report, adapter, args) {
     if (!json) {
         console.log("\nℹ auto-generated probe prompts from skill descriptions (pass --prompts=<file> for a curated set).");
     }
+    const model = flagValue(args, "--model");
     const trigger = await (0, scan_behavioral_js_1.probePluginTriggers)(dir, promptSet, {
         minPrompts: audit_prompts_js_1.AUTO_RECALL_COUNT,
         minDistance: audit_prompts_js_1.AUTO_MIN_DISTANCE,
-        model: flagValue(args, "--model"),
+        model,
         harness,
         // Discover candidates with the resolved adapter's layout/dialect — a Codex
         // repo's skills live under the Codex layout, not the default CC one.
         layout: adapter.layout,
         dialect: adapter.dialect,
     });
-    console.log(json
-        ? JSON.stringify({ trigger }, null, 2)
-        : "\n" + (0, scan_behavioral_js_1.formatBehavioralReport)(trigger));
+    // Second behavioral eval (same consent): the selection-collision matrix — does
+    // one skill HIJACK a sibling's prompt? This is the MEASURED confirmation of the
+    // deterministic description-overlap proxy (the Triggering ring flags look-alikes;
+    // this proves the wrong one actually fires). Only meaningful with ≥2 model-
+    // invocable skills (a lone skill can't collide); reuses the same auto prompts.
+    const collisions = skills.length >= 2
+        ? await (0, scan_behavioral_js_1.measurePluginSelection)(dir, promptSet, { model, harness })
+        : null;
+    // Third behavioral eval (same consent): adversarial-gate — do enforcement-gate
+    // skills HOLD when the agent is told to violate them? Auto-derives its own
+    // attacks; a no-op (no model calls) when the plugin declares no gate skills.
+    const gates = await (0, scan_behavioral_js_1.measureGateAdversarial)(dir, {
+        model,
+        harness,
+        layout: adapter.layout,
+        dialect: adapter.dialect,
+    });
+    // Show the gate section when gate skills were DETECTED — even if the eval
+    // couldn't RUN (a Codex audit, or no `claude` CLI) it returns available:false
+    // with empty results, and `formatGateReport` renders the "unavailable" note.
+    // The consent prompt already advertised these gate skills, so a skipped check
+    // must be reported LOUDLY, never silently omitted as if there were none.
+    const hasGates = gates.results.length > 0 || (0, scan_behavioral_js_1.detectGateSkills)(report.skills).length > 0;
+    if (json) {
+        console.log(JSON.stringify({
+            trigger,
+            ...(collisions ? { collisions } : {}),
+            ...(hasGates ? { gates } : {}),
+        }, null, 2));
+    }
+    else {
+        console.log("\n" + (0, scan_behavioral_js_1.formatBehavioralReport)(trigger));
+        if (collisions)
+            console.log("\n" + (0, scan_behavioral_js_1.formatSelectionReport)(collisions));
+        if (hasGates)
+            console.log("\n" + (0, scan_behavioral_js_1.formatGateReport)(gates));
+    }
 }
 /**
  * The ONE read-vs-run decision for a single-plugin `audit`. A plain `audit` is a
@@ -4272,7 +4400,17 @@ function buildExecuteDisclosure(s, harness) {
     if (s.hasMcp)
         lines.push("  · start your MCP servers — connects to their backends");
     if (s.triggerableSkills > 0) {
-        lines.push(`  · measure whether skills fire (${triggerCostWording(harness)})`);
+        // ≥2 model-invocable skills also get the selection-collision matrix (does one
+        // skill hijack a sibling's prompt) — disclose it so the consent stays honest.
+        const what = s.triggerableSkills >= 2
+            ? "measure whether skills fire and collide"
+            : "measure whether skills fire";
+        lines.push(`  · ${what} (${triggerCostWording(harness)})`);
+    }
+    if (s.gateSkills > 0) {
+        // The adversarial-gate eval runs the FULL (unstubbed) skill — the most
+        // expensive check — so disclose it separately when gate skills are present.
+        lines.push(`  · test whether ${String(s.gateSkills)} enforcement-gate skill${s.gateSkills === 1 ? "" : "s"} hold under pressure — runs the full skill (${triggerCostWording(harness)})`);
     }
     if (s.adoptableRefs) {
         lines.push(`  · draft + verify your instruction file's references (${triggerCostWording(harness)})`);
@@ -4452,7 +4590,10 @@ async function main() {
                 // through to a misleading "empty machine / no structural issues" report
                 // (obra/superpowers-marketplace, anthropics/claude-plugins-community).
                 if (json) {
-                    console.log(JSON.stringify(market, null, 2));
+                    console.log(JSON.stringify((0, audit_report_js_1.buildMarketplaceReport)(market, {
+                        vigilesVersion: getVersion(),
+                        dir: (0, node_path_1.resolve)(dirs[0]),
+                    }), null, 2));
                 }
                 else {
                     console.log(`Marketplace "${market.name}": ${String(market.total)} plugin(s), all external ` +
@@ -4468,7 +4609,12 @@ async function main() {
                 const text = args.includes("--md")
                     ? (0, leaderboard_js_1.formatLeaderboardMarkdown)(scores)
                     : (0, leaderboard_js_1.formatLeaderboard)(scores);
-                console.log(json ? JSON.stringify(scores, null, 2) : text);
+                console.log(json
+                    ? JSON.stringify((0, audit_report_js_1.buildLeaderboardReport)(scores, {
+                        vigilesVersion: getVersion(),
+                        dir: (0, node_path_1.resolve)(dirs[0]),
+                    }), null, 2)
+                    : text);
             }
             else {
                 const root = (0, node_path_1.resolve)(targets[0]);
@@ -4546,6 +4692,7 @@ async function main() {
                 const surfaces = {
                     hasMcp: report.mcp && !isForeign,
                     triggerableSkills: report.skills.filter((s) => s.hasDescription && !s.userInvoked).length,
+                    gateSkills: (0, scan_behavioral_js_1.detectGateSkills)(report.skills).length,
                     adoptableRefs: adapter.name === "claude-code" &&
                         (0, node_fs_1.existsSync)((0, node_path_1.resolve)(root, adapter.layout.instructionFile)),
                 };
@@ -4632,17 +4779,36 @@ async function main() {
                 const finalReport = adoptabilityResult
                     ? { ...auditReport, adoptability: adoptabilityResult }
                     : auditReport;
-                // The shareable HTML report — written by default (--no-html to skip), and
-                // opened best-effort only for a human at a TTY (never spawn a browser for
-                // an agent / CI run).
-                if (!json && !args.includes("--no-html")) {
-                    writeAuditHtml(finalReport);
-                }
                 // The versioned JSON artifact — the upload/CI boundary (a hosted dashboard
                 // ingests this). Written by default in the human path; --no-json to skip.
                 if (!json && !args.includes("--no-json")) {
                     writeAuditJson(finalReport);
                 }
+                // The HTML report has two deliveries. STATIC (default): write the
+                // shareable file whose buttons copy the `init` command. LIVE (`--serve`,
+                // or a TTY "yes"): start a loopback server whose buttons run `init` for
+                // you. The gate keeps the default a terminating, headless-safe read and
+                // restricts the write-server to your own repo (decideServeGate).
+                const serveGate = (0, audit_serve_js_1.decideServeGate)({
+                    serveFlag: args.includes("--serve"),
+                    noServeFlag: args.includes("--no-serve"),
+                    json,
+                    isTTY: process.stdout.isTTY && process.stdin.isTTY,
+                    ownRepo: !isForeign,
+                    adoptableCount: finalReport.adoptable?.surfaces.length ?? 0,
+                });
+                let serveLive = serveGate === "serve";
+                if (serveGate === "ask") {
+                    const ans = (await askOnce("\nOpen the live report to create specs with one click? [y/N] ")).toLowerCase();
+                    serveLive = ans === "y" || ans === "yes";
+                }
+                const errMsg = (e) => e instanceof Error ? e.message : String(e);
+                if (serveLive) {
+                    await runAuditServe(finalReport, finalReport.adoptable, errMsg);
+                }
+                else if (!json && !args.includes("--no-html")) {
+                    writeAuditHtml(finalReport);
+                }
             }
             break;
         }

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.js

@@ -48,8 +48,10 @@ 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)
+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)
@@ -72,7 +74,6 @@ function gradeFor(score) {
 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);
@@ -117,11 +118,14 @@ function reportDeductions(r) {
             weight: exports.W_NO_CONTRACT,
             label: "agent disallowedTools typo(s) that block nothing",
         },
-        {
-            n: noContract,
-            weight: exports.W_NO_CONTRACT,
-            label: "agent(s) inherit all tools (no contract)",
-        },
+        // 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: r.frontmatterIssues.length,
             weight: exports.W_NO_DESCRIPTION,
@@ -192,8 +196,15 @@ function scoreReport(r) {
     }
     // 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]));
-    // Untested surfaces are advisory — surfaced for visibility, but they don't
-    // affect the score, so they come AFTER the real (score-affecting) 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)`);
     }
@@ -228,12 +239,12 @@ 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 surfaces are advisory — shown, but they don't affect the score.");
+    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 surfaces are advisory (shown, not " +
+    "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,

package/dist/scan-behavioral.d.ts

@@ -135,5 +135,90 @@ export declare function measurePluginSelectionWith(dir: string, promptSet: Trigg
 export declare function measurePluginSelection(dir: string, promptSet: TriggerPromptSet, opts?: SelectionOptions): Promise<SelectionReport>;
 /** Format the selection-collision matrix as a scan-report section. */
 export declare function formatSelectionReport(r: SelectionReport): string;
+/** Does a skill description assert a hard constraint (→ an adversarial-gate candidate)? */
+export declare function isGateDescription(description: string): boolean;
+/** A skill considered for gate detection — name + its (model-visible) description. */
+export interface GateCandidate {
+    readonly name: string;
+    readonly description?: string;
+    readonly userInvoked?: boolean;
+    readonly hasDescription?: boolean;
+}
+/**
+ * The model-invocable, described skills whose description reads as an enforcement
+ * gate — the candidates for the adversarial-gate eval. User-invoked and
+ * description-less skills are excluded (they can't auto-fire a constraint on the
+ * model's behaviour), mirroring the trigger-rate candidate filter.
+ */
+export declare function detectGateSkills(skills: readonly GateCandidate[]): readonly string[];
+/** A gate under test: its name + the rule its description states. */
+export interface GateUnderTest {
+    readonly name: string;
+    readonly description: string;
+}
+/** The verdict an injected judge returns (a subset of judge.ts JudgeResult). */
+export interface GateVerdict {
+    readonly pass: boolean;
+    readonly score: number;
+    readonly reason: string;
+}
+/** Injected dependencies, so the orchestration is unit-testable with no model. */
+export interface GateEvalDeps {
+    readonly driver: EvalDriver;
+    /** Grade whether the gate held, given the run output + the rule rubric. */
+    readonly judge: (a: {
+        output: string;
+        rubric: string;
+    }) => GateVerdict;
+    /** Turn a gate's rule into a one-line user request that tries to violate it. */
+    readonly derive: (gate: GateUnderTest) => string;
+}
+export interface GateOptions {
+    /** Selector model for the harness run (default sonnet). */
+    readonly model?: string;
+    /** Attacks per gate (default 1). */
+    readonly trials?: number;
+    /** Concurrent harness runs (default 1). */
+    readonly concurrency?: number;
+    readonly harness?: ProbeHarness;
+    readonly layout?: PluginLayout;
+    readonly dialect?: HarnessDialect;
+    /** Author-supplied attack prompts (bare skill name → prompts); overrides derive. */
+    readonly attacks?: Record<string, readonly string[]>;
+}
+export interface GateResult {
+    readonly skill: string;
+    readonly measured: boolean;
+    /** Fraction of attacks the gate HELD (1 = held every time). */
+    readonly heldRate?: number;
+    /** Convenience: held on EVERY attack (a single cave → false). */
+    readonly held?: boolean;
+    readonly n?: number;
+    /** The attack used (first), for the report. */
+    readonly attack?: string;
+    /** The judge's rationale on a representative cave (else a hold), for the report. */
+    readonly reason?: string;
+    readonly note?: string;
+}
+export interface GateAdversarialReport {
+    readonly available: boolean;
+    readonly results: readonly GateResult[];
+    readonly note?: string;
+}
+/** Build the LLM-judge rubric from the gate's own rule (pure). */
+export declare function gateRubric(gate: GateUnderTest): string;
+/** The injectable core (unit-testable with fake driver/judge/derive — no model). */
+export declare function measureGateAdversarialWith(dir: string, gates: readonly GateUnderTest[], deps: GateEvalDeps, opts?: GateOptions): Promise<GateAdversarialReport>;
+/**
+ * Measure whether a plugin's enforcement-gate skills HOLD when adversarially
+ * challenged. Detects gate skills (keyword heuristic), auto-derives an attack from
+ * each rule (unless author-supplied), runs the UNSTUBBED harness, and LLM-judges
+ * hold vs cave. Claude Code only; degrades to `available: false` without the CLI/auth.
+ */
+export declare function measureGateAdversarial(dir: string, opts?: GateOptions): Promise<GateAdversarialReport>;
+/** Default adversarial attacks per gate (stochastic → need >1; unstubbed → keep low). */
+export declare const DEFAULT_GATE_TRIALS = 3;
+/** Format the adversarial-gate report as a scan-report section. */
+export declare function formatGateReport(r: GateAdversarialReport): string;
 export {};
 //# sourceMappingURL=scan-behavioral.d.ts.map