vigiles 15.0.0 → 15.0.2

package/dist/core/hook-matcher.js

@@ -4,178 +4,292 @@ exports.hookMatcherIssues = hookMatcherIssues;
 const tool_contract_js_1 = require("./tool-contract.js");
 const mcp_tool_js_1 = require("./mcp-tool.js");
 // ---------------------------------------------------------------------------
+// The probe corpus
+// ---------------------------------------------------------------------------
+/**
+ * Server segments an MCP tool name really carries. `Google_Calendar` is
+ * Anthropic's own connector naming (an underscore INSIDE the server segment);
+ * the uuid is the SAME server as it appears in another session (hyphens). A
+ * matcher meant to catch "MCP tools" has to reach both.
+ */
+const PROBE_SERVERS = [
+    "srv",
+    "Google_Calendar",
+    "4f54037d-0499-426a-8573-6130f3da1ef8",
+];
+/** Tool segments: plain, underscored, and the second underscored form. */
+const PROBE_TOOLS = ["tool", "list_events", "update_event"];
+/** The simplest possible MCP tool name — "does this pattern match MCP at all". */
+const PROBE_SIMPLE = "mcp__srv__tool";
+/**
+ * The two REAL-SHAPE probes a generic MCP matcher must also reach. Both are
+ * measured: `mcp__[^_]+__[^_]+` does not fire on the first, `mcp__\w+__\w+`
+ * does not fire on the second.
+ */
+const REAL_SHAPE_PROBES = [
+    "mcp__Google_Calendar__list_events",
+    "mcp__4f54037d-0499-426a-8573-6130f3da1ef8__update_event",
+];
+/** The widest correct MCP matcher — what a too-narrow one should become. */
+const WIDE_MCP_MATCHER = "mcp__.*__.*";
+/** Match-all matchers the harness special-cases (and `*` isn't even a regex). */
+const MATCH_ALL = new Set(["", "*", "**", ".*"]);
+/** Cap on segments harvested from a matcher — bounds the probe corpus. */
+const MAX_DERIVED_SEGMENTS = 4;
+// ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------
+/** Regex metacharacters — their presence is what makes a matcher a PATTERN. */
+const REGEX_META = /[\\^$.*+?()[\]{}|]/;
+/** A matcher with no metacharacter is compared by string equality (measured). */
+function isLiteralMatcher(matcher) {
+    return !REGEX_META.test(matcher);
+}
+/** Compile a matcher, or null when the regex engine rejects it. */
+function compileMatcher(matcher) {
+    try {
+        return new RegExp(matcher);
+    }
+    catch {
+        return null;
+    }
+}
 /**
- * Whether a matcher token should be skipped for FP-safety. We ONLY inspect
- * a SINGLE bare token that could plausibly be a literal tool name or MCP
- * reference. Anything with regex / glob meta-characters, alternation, a
- * trailing glob wildcard alone, or an empty string is a pattern — skip it.
- *
- * Conservative by design: an unrecognized form → skip, never flag.
+ * A token starts with `mcp` followed by a separator — it is trying to be an MCP
+ * tool reference, whether or not it succeeds. A leading `^` is tolerated so an
+ * ANCHORED pattern (`^mcp__srv$`, which cannot reach the tool segment) is judged
+ * as MCP rather than skipped as an unknown built-in.
  */
-function isInspectableToken(token) {
-    if (token.length === 0)
-        return false;
-    // Pure wildcard forms used as "match-all" matchers.
-    if (token === "*" || token === ".*" || token === "**")
-        return false;
-    // Contains regex alternation — a combined matcher, not a single tool name.
-    if (token.includes("|"))
-        return false;
-    // Contains a parenthesised group `(…)` — regex, not a tool name.
+function looksMcpIsh(token) {
+    return /^\^?mcp[_-]/i.test(token);
+}
+/**
+ * Whether a NON-MCP token should be inspected as a possible tool-name typo. We
+ * only inspect a single bare token that could plausibly BE a tool name; regex /
+ * glob syntax means it is a pattern over tool names, not one. Conservative by
+ * design: an unrecognized form → skip, never flag.
+ */
+function isBareToolToken(token) {
     if (token.includes("(") || token.includes(")"))
         return false;
-    // Contains a `[` — character class; skip.
     if (token.includes("["))
         return false;
-    // A leading `^` or trailing `$` — anchored regex.
     if (token.startsWith("^") || token.endsWith("$"))
         return false;
-    // Leading `.*` — regex prefix; always a pattern.
     if (token.startsWith(".*"))
         return false;
-    // A trailing `.*`/`*` is a glob/regex suffix on a plain TOOL matcher (`Bash.*`,
-    // `Read*`) → skip. But for an MCP-ish token the trailing wildcard is EXACTLY
-    // what we must inspect: `mcp__server__.*` is the legitimate match-all-tools
-    // form, and `mcp_memory_*` is the classic single-underscore typo we want to
-    // catch — so do NOT skip a wildcard suffix on an `mcp`-ish token.
-    if (!looksMcpIsh(token) && (token.endsWith(".*") || token.endsWith("*")))
+    if (token.endsWith(".*") || token.endsWith("*"))
         return false;
     return true;
 }
 /**
- * A token starts with `mcp` (case-insensitive) and contains at least one
- * `_` (making it look like an MCP tool reference, not a harness built-in).
+ * Strip the regex anchors so an anchored matcher (`^mcp__memory__.*$`) is read
+ * structurally the same as its unanchored twin. The anchors stay in the compiled
+ * regex — this is only for reading the matcher's literal segments.
  */
-function looksMcpIsh(token) {
-    return /^mcp[_-]/i.test(token);
+function withoutAnchors(matcher) {
+    return matcher.replace(/^\^/, "").replace(/\$$/, "");
+}
+/** The literal server segment of `mcp__<server>__…`, or null when it's a pattern. */
+function literalServerSegment(matcher) {
+    return /^mcp__([A-Za-z0-9_-]+)__/.exec(withoutAnchors(matcher))?.[1] ?? null;
+}
+/** Literal name-shaped runs inside one segment of a matcher (`mem.*` → `mem`). */
+function literalRuns(segment) {
+    return (segment.match(/[A-Za-z0-9][A-Za-z0-9_-]*/g) ?? []).slice(0, MAX_DERIVED_SEGMENTS);
 }
 /**
- * Whether `token` matches the canonical `mcp__<server>__<rest>` double-
- * underscore shape (the valid MCP matcher form). We use the dialect's own
- * `mcpToolPattern` extended to allow trailing `.*` for wildcard matchers,
- * since a hook `matcher` may be `mcp__server__.*` (match-all-tools-on-server).
+ * Synthetic MCP tool names to test a matcher against: the generic corpus (the
+ * real-world server/tool shapes) PLUS names built from the matcher's OWN literal
+ * segments, so a legitimately scoped `mcp__memory__search.*` has something to
+ * match. Derivation is POSITIONAL — segments are read from the `mcp__`-split
+ * positions they occupy, never re-used as a different segment — so a malformed
+ * `mcp_memory_search` cannot manufacture a probe that rescues it.
  */
-function isValidMcpForm(token, dialect) {
-    // The canonical pattern from the dialect: `mcp__server__tool`.
-    if (dialect.mcpToolPattern.test(token))
-        return true;
-    // Also allow the wildcard suffix form `mcp__server__.*`.
-    if (/^mcp__[a-z0-9_-]+__\.\*$/i.test(token))
-        return true;
-    return false;
+function mcpProbes(matcher) {
+    const parts = withoutAnchors(matcher).split("__");
+    const derivedServers = parts[0] === "mcp" && parts.length > 1 ? literalRuns(parts[1]) : [];
+    const derivedTools = parts[0] === "mcp" && parts.length > 2
+        ? literalRuns(parts.slice(2).join("__"))
+        : [];
+    const servers = [...derivedServers, ...PROBE_SERVERS];
+    const tools = [...derivedTools, ...PROBE_TOOLS];
+    const probes = [];
+    for (const server of servers)
+        for (const tool of tools)
+            probes.push(`mcp__${server}__${tool}`);
+    return probes;
 }
 /**
- * Attempt to recover the server segment from a malformed MCP token so we can
- * suggest the corrected `mcp__<server>__.*` form. Returns null when no
- * segment can be confidently recovered.
+ * Recover the server segment from a malformed MCP token so the corrected
+ * `mcp__<server>__.*` form can be suggested. Returns null when nothing
+ * name-shaped can be recovered (then the message spells the form out instead).
  *
- * Handles:
- *   - Single-underscore: `mcp_memory_search` → server=`memory`, tool=`search`
- *   - Hyphenated:        `mcp-memory-search` → server=`memory`, tool=`search`
- *   - Glob suffix:       `mcp_memory_*`       → server=`memory`
- *   - Mixed:             `mcp__memory_*`      → only one `__` segment found
+ * Handles the `__`-separated form first — the segment the user actually wrote is
+ * kept whole (`mcp__memory_search` → `memory_search`, since a real server IS
+ * named like `Google_Calendar`) — then the single-underscore / hyphen typos
+ * (`mcp_memory_search`, `mcp-memory-search`, `mcp_memory_*` → `memory`).
  */
 function recoverMcpServer(token) {
-    // Strip a leading `mcp` and then a separator (`__`, `_`, `-`).
-    const rest = token.replace(/^mcp(?:__|_|-)/i, "");
-    if (!rest || rest === token)
+    const parts = withoutAnchors(token).split("__");
+    const candidate = parts.length > 1 && parts[1].length > 0
+        ? parts[1]
+        : firstSeparatedSegment(token);
+    if (candidate === null)
+        return null;
+    // A recovered segment must be name-shaped, or the "suggestion" would be a
+    // regex fragment — the bug that made the old advice grow `__.*` forever.
+    return /^[A-Za-z][A-Za-z0-9_-]*$/.test(candidate) ? candidate : null;
+}
+/** The segment after a single `_`/`-` separator following the `mcp` prefix. */
+function firstSeparatedSegment(token) {
+    const rest = withoutAnchors(token).replace(/^mcp(?:_|-)/i, "");
+    if (rest === token || rest.length === 0)
         return null;
-    // Split on single underscores or hyphens (not `__`) to get the next segment.
-    // We want the first non-empty segment after the `mcp` prefix separator.
-    const segments = rest.split(/(?<!_)_(?!_)|(?<!-)(?:-(?!-))/);
-    const server = segments[0];
-    if (!server || server.length === 0)
+    const segment = rest.split(/(?<!_)_(?!_)|-/)[0];
+    return segment.length > 0 ? segment : null;
+}
+// ---------------------------------------------------------------------------
+// Finding builders
+// ---------------------------------------------------------------------------
+/** The matcher can match NO MCP tool name — the hook is dead. */
+function unreachableFinding(matcher) {
+    const server = recoverMcpServer(matcher);
+    const suggestion = server === null ? undefined : `mcp__${server}__.*`;
+    const hint = suggestion === undefined
+        ? " Use the form `mcp__<server>__<tool>` (double underscores), or a pattern that produces it."
+        : ` Did you mean "${suggestion}"?`;
+    return {
+        matcher,
+        kind: "mcp-form",
+        ...(suggestion === undefined ? {} : { suggestion }),
+        message: `Hook matcher "${matcher}" matches no MCP tool name — MCP tools are named \`mcp__<server>__<tool>\`, so this hook never fires.${hint}`,
+    };
+}
+/**
+ * The matcher fires on some MCP tools but misses real-world server naming. The
+ * message names the probes it actually misses — not the whole corpus — so the
+ * finding is checkable rather than a vague "too narrow".
+ */
+function narrowFinding(matcher, missed) {
+    const names = missed.map((m) => `"${m}"`).join(" or ");
+    return {
+        matcher,
+        kind: "mcp-narrow",
+        suggestion: WIDE_MCP_MATCHER,
+        message: `Hook matcher "${matcher}" fires on some MCP tools but not on ${names} — real server segments contain "_" and "-" (the same server appears as \`mcp__Google_Calendar__…\` in one session and \`mcp__<uuid>__…\` in another), so this matcher silently skips them. Did you mean "${WIDE_MCP_MATCHER}"?`,
+    };
+}
+/** The matcher isn't a regex the engine accepts — it can never match. */
+function invalidRegexFinding(matcher) {
+    return {
+        matcher,
+        kind: "invalid-regex",
+        message: `Hook matcher "${matcher}" is not a valid regular expression — the harness can't compile it, so the hook never fires.`,
+    };
+}
+// ---------------------------------------------------------------------------
+// Per-matcher checks
+// ---------------------------------------------------------------------------
+/**
+ * The shape half of the MCP check: can this matcher produce an MCP tool name at
+ * all, and if so does it reach the ones that occur in the wild? `re` is null for
+ * a literal matcher (compared by string equality, so only the shape can be
+ * checked).
+ */
+function mcpShapeFinding(matcher, re, dialect) {
+    if (re === null)
+        return dialect.mcpToolPattern.test(matcher)
+            ? null
+            : unreachableFinding(matcher);
+    if (!mcpProbes(matcher).some((p) => re.test(p)))
+        return unreachableFinding(matcher);
+    // The narrowness check applies only to a matcher meant to be GENERIC: one that
+    // pins no literal server yet matches the simplest MCP name. A matcher scoped to
+    // one server (or to specific tools) is narrow ON PURPOSE — never flag it.
+    if (literalServerSegment(matcher) !== null || !re.test(PROBE_SIMPLE))
+        return null;
+    const missed = REAL_SHAPE_PROBES.filter((p) => !re.test(p));
+    return missed.length === 0 ? null : narrowFinding(matcher, missed);
+}
+/**
+ * The resolution half: a matcher pinning a literal server the plugin doesn't
+ * declare can't fire. Gated EXACTLY like `mcp-tool-resolves` — no declared set →
+ * silent (the server may be user-global), built-ins allowlisted, the
+ * plugin-namespaced form skipped.
+ */
+function mcpUndeclaredFinding(matcher, declaredServers, dialect) {
+    if (declaredServers.length === 0)
+        return null;
+    const server = (0, mcp_tool_js_1.mcpToolServer)(matcher, dialect) ?? literalServerSegment(matcher);
+    if (server === null)
+        return null;
+    if (/^plugin_/i.test(server))
+        return null;
+    const known = new Set([
+        ...declaredServers,
+        ...(dialect.knownMcpServers ?? []),
+    ]);
+    if (known.has(server))
+        return null;
+    return {
+        matcher,
+        kind: "mcp-undeclared",
+        message: `Hook matcher "${matcher}" references MCP server "${server}", which the plugin doesn't declare (declared: ${declaredServers.join(", ")}) — the hook can't fire.`,
+    };
+}
+/** A literal bare token that is a close typo of a real built-in tool. */
+function toolTypoFinding(matcher, dialect) {
+    if (!isBareToolToken(matcher))
+        return null;
+    if (new Set(dialect.builtinAgentTools).has(matcher))
+        return null;
+    const near = (0, tool_contract_js_1.closestTool)(matcher, dialect);
+    if (near === null)
+        return null; // far/unknown → likely a plugin tool, not a typo
+    return {
+        matcher,
+        kind: "tool-typo",
+        suggestion: near,
+        message: `Hook matcher "${matcher}" doesn't match any built-in tool — the hook silently never fires. Did you mean "${near}"?`,
+    };
+}
+/** The whole per-matcher decision. Null when the matcher is fine (or skipped). */
+function matcherFinding(matcher, declaredServers, dialect) {
+    if (MATCH_ALL.has(matcher))
         return null;
-    // Reject segments that are clearly numeric-only or single chars (too ambiguous).
-    if (/^\d+$/.test(server))
+    // Alternation: each arm would have to be judged on its own, and a mixed set
+    // (`mcp__x__y|Bash`) is legitimate — skip, same don't-cry-wolf discipline.
+    if (matcher.includes("|"))
         return null;
-    return server;
+    const literal = isLiteralMatcher(matcher);
+    const re = literal ? null : compileMatcher(matcher);
+    if (!literal && re === null)
+        return invalidRegexFinding(matcher);
+    if (looksMcpIsh(matcher))
+        return (mcpShapeFinding(matcher, re, dialect) ??
+            mcpUndeclaredFinding(matcher, declaredServers, dialect));
+    return literal ? toolTypoFinding(matcher, dialect) : null;
 }
 // ---------------------------------------------------------------------------
 // Public detector
 // ---------------------------------------------------------------------------
 /**
- * Verify hook-matcher strings for the three forms that silently never fire.
+ * Verify hook-matcher strings for the ways a matcher fails to fire as written.
  * Returns one {@link HookMatcherFinding} per offending entry. De-duplicates
- * repeated matchers. Returns `[]` when all matchers are FP-safe to skip or
- * are correct.
+ * repeated matchers. Returns `[]` when every matcher is FP-safe to skip or is
+ * correct.
  */
 function hookMatcherIssues(entries, declaredServers, dialect) {
     const findings = [];
     const seen = new Set();
     for (const { matcher } of entries) {
-        // De-dupe repeated matchers across entries.
         if (seen.has(matcher))
-            continue;
+            continue; // de-dupe repeated matchers across entries
         seen.add(matcher);
-        // Skip wildcards, alternation, regex patterns — FP-safety.
-        if (!isInspectableToken(matcher))
-            continue;
-        // ── kind: mcp-form ──────────────────────────────────────────────────────
-        // The token looks MCP-ish but is NOT the valid double-underscore form.
-        if (looksMcpIsh(matcher)) {
-            if (!isValidMcpForm(matcher, dialect)) {
-                const server = recoverMcpServer(matcher);
-                const suggestion = server ? `mcp__${server}__.*` : undefined;
-                const hintPart = suggestion !== undefined
-                    ? ` Did you mean "${suggestion}"?`
-                    : " Use the form `mcp__<server>__<tool>` (double underscores).";
-                findings.push({
-                    matcher,
-                    kind: "mcp-form",
-                    ...(suggestion !== undefined ? { suggestion } : {}),
-                    message: `Hook matcher "${matcher}" is not a valid MCP tool reference (requires double underscores: \`mcp__server__tool\`).${hintPart}`,
-                });
-                continue;
-            }
-            // ── kind: mcp-undeclared ──────────────────────────────────────────────
-            // A correctly-formed MCP token whose server isn't in the declared set.
-            // Guard 1: no declared set → skip (reaches global/project servers).
-            if (declaredServers.length === 0)
-                continue;
-            // `mcpToolServer` reads the `mcp__server__tool` form; a server-wide WILDCARD
-            // matcher (`mcp__server__.*`) isn't a concrete tool, so fall back to the
-            // wildcard server segment so an undeclared server is still caught.
-            const server = (0, mcp_tool_js_1.mcpToolServer)(matcher, dialect) ??
-                /^mcp__([a-z0-9_-]+)__\.\*$/i.exec(matcher)?.[1] ??
-                null;
-            if (server === null)
-                continue; // plugin-namespaced form → guard 3, skip
-            // The plugin-namespaced `mcp__plugin_<plugin>_<server>__` form is the
-            // plugin's OWN server — never an undeclared reference (mirrors mcpToolServer).
-            if (/^plugin_/i.test(server))
-                continue;
-            const known = new Set([
-                ...declaredServers,
-                ...(dialect.knownMcpServers ?? []),
-            ]);
-            // Guard 2: built-in server → skip.
-            if (known.has(server))
-                continue;
-            findings.push({
-                matcher,
-                kind: "mcp-undeclared",
-                message: `Hook matcher "${matcher}" references MCP server "${server}", which the plugin doesn't declare (declared: ${declaredServers.join(", ")}) — the hook can't fire.`,
-            });
-            continue;
-        }
-        // ── kind: tool-typo ─────────────────────────────────────────────────────
-        // A bare token that is NOT an exact built-in tool but IS a close typo of one.
-        const knownTools = new Set(dialect.builtinAgentTools);
-        if (knownTools.has(matcher))
-            continue; // exact match → no issue
-        // Reuse the same ≤ 2 edit-distance helper from tool-contract.ts.
-        const near = (0, tool_contract_js_1.closestTool)(matcher, dialect);
-        if (near === null)
-            continue; // far/unknown → likely a plugin tool, not a typo
-        findings.push({
-            matcher,
-            kind: "tool-typo",
-            suggestion: near,
-            message: `Hook matcher "${matcher}" doesn't match any built-in tool — the hook silently never fires. Did you mean "${near}"?`,
-        });
+        const finding = matcherFinding(matcher, declaredServers, dialect);
+        if (finding !== null)
+            findings.push(finding);
     }
     return findings;
 }

package/dist/core/lethal-trifecta.d.ts

@@ -86,16 +86,45 @@ export declare function bashGrantIsUnbounded(raw: string): boolean;
  * by {@link lethalTrifectaIssues}, which knows it grants every leg.
  */
 export declare function classifyTrifectaLegs(tools: readonly string[], dialect: HarnessDialect): TrifectaLegs;
+/** Extra facts about HOW the contract was obtained, which change the verdict. */
+export interface TrifectaContext {
+    /**
+     * The unit's frontmatter block EXISTS but is not valid YAML.
+     *
+     * 🔴 WHY THE DETECTOR NEEDS TO KNOW. vigiles's frontmatter reader is
+     * deliberately lenient: on a block js-yaml rejects it regex-SALVAGES the
+     * fields, so the live PreToolUse rail still has something to enforce. Right
+     * for a rail, wrong for a score. Measured 2026-08-08:
+     * `readFrontmatter(bad).malformed` is `true` — the tool KNOWS the block is
+     * broken — while `frontmatterList(…, "allowed-tools")` on it still returns
+     * `["Read","Bash"]`, the narrow contract its author MEANT. A unit whose
+     * contract a strict loader rejects was therefore graded as though it had
+     * declared exactly that list, and scored CLEAN. Presence of a declaration is
+     * not enforcement of it — the product's own thesis, turned on the product.
+     *
+     * With this set, `tools` is read as a SALVAGE, not a contract: it can only make
+     * the verdict worse, never better. A salvaged list that names all three legs
+     * still fires `"hard"` (both readings of the file agree the unit holds them);
+     * anything less falls back to what a strict loader actually yields — no
+     * contract at all, i.e. inherits-all, which is the `"advisory"` finding.
+     */
+    readonly contractUnreadable?: boolean;
+}
 /**
  * Returns a {@link TrifectaFinding} ONLY when a unit holds all three legs, else
  * `null` (≤ 2 legs = safe by the Rule of Two).
  *
- * Two paths:
+ * Three paths:
  * - INHERITS-ALL (a wildcard `""`/`"*"`, or an EMPTY contract): inherits every
  *   tool → trivially all three legs → an `"advisory"` finding (the inherits-all
  *   stance: a footgun worth surfacing, not a declared exfil path).
  * - EXPLICIT: classify the named tools; emit a `"hard"` finding iff each of the
  *   three legs is non-empty.
+ * - UNREADABLE ({@link TrifectaContext.contractUnreadable}): the names came from
+ *   a salvage of a block a strict loader rejects. They can only make the verdict
+ *   WORSE — a salvaged all-three still fires `"hard"` — and anything short of
+ *   that falls back to what a strict loader really yields: no contract, i.e.
+ *   inherits-all, the `"advisory"` finding. Never the other way round.
  */
-export declare function lethalTrifectaIssues(tools: readonly string[], dialect: HarnessDialect): TrifectaFinding | null;
+export declare function lethalTrifectaIssues(tools: readonly string[], dialect: HarnessDialect, ctx?: TrifectaContext): TrifectaFinding | null;
 //# sourceMappingURL=lethal-trifecta.d.ts.map

package/dist/core/lethal-trifecta.js

@@ -249,14 +249,19 @@ function classifyTrifectaLegs(tools, dialect) {
  * Returns a {@link TrifectaFinding} ONLY when a unit holds all three legs, else
  * `null` (≤ 2 legs = safe by the Rule of Two).
  *
- * Two paths:
+ * Three paths:
  * - INHERITS-ALL (a wildcard `""`/`"*"`, or an EMPTY contract): inherits every
  *   tool → trivially all three legs → an `"advisory"` finding (the inherits-all
  *   stance: a footgun worth surfacing, not a declared exfil path).
  * - EXPLICIT: classify the named tools; emit a `"hard"` finding iff each of the
  *   three legs is non-empty.
+ * - UNREADABLE ({@link TrifectaContext.contractUnreadable}): the names came from
+ *   a salvage of a block a strict loader rejects. They can only make the verdict
+ *   WORSE — a salvaged all-three still fires `"hard"` — and anything short of
+ *   that falls back to what a strict loader really yields: no contract, i.e.
+ *   inherits-all, the `"advisory"` finding. Never the other way round.
  */
-function lethalTrifectaIssues(tools, dialect) {
+function lethalTrifectaIssues(tools, dialect, ctx = {}) {
     const hasWildcard = tools.some((t) => isWildcard(baseTool(t)));
     // Inherits-all is signalled by a WILDCARD (the caller passes `["*"]` for an
     // absent `tools:` line). An EXPLICIT empty `[]` is the opposite — zero tools,
@@ -271,10 +276,17 @@ function lethalTrifectaIssues(tools, dialect) {
         return {
             severity: "advisory",
             legs,
-            message: "Inherits-all contract (no explicit tools / wildcard) grants every capability — " +
-                "it holds all three lethal-trifecta legs (read private data, ingest untrusted content, " +
-                "exfiltrate) and is a maximal prompt-injection blast radius. Declare an explicit tools " +
-                "list dropping at least one leg (Meta's Rule of Two).",
+            message: ctx.contractUnreadable
+                ? "Frontmatter is not valid YAML, so the declared tool list could not be read — a " +
+                    "strict loader rejects the block, and a regex salvage of it is a guess, not a " +
+                    "contract. Scored as INHERITS-ALL (every capability), which is what a strict " +
+                    "loader yields: it therefore holds all three lethal-trifecta legs (read private " +
+                    "data, ingest untrusted content, exfiltrate). Fix the YAML and the declared list " +
+                    "counts again — a declaration that does not parse is not an enforcement."
+                : "Inherits-all contract (no explicit tools / wildcard) grants every capability — " +
+                    "it holds all three lethal-trifecta legs (read private data, ingest untrusted content, " +
+                    "exfiltrate) and is a maximal prompt-injection blast radius. Declare an explicit tools " +
+                    "list dropping at least one leg (Meta's Rule of Two).",
         };
     }
     const legs = classifyTrifectaLegs(tools, dialect);
@@ -288,9 +300,22 @@ function lethalTrifectaIssues(tools, dialect) {
                 `(${legs.private.join(", ")}), ingest untrusted content ` +
                 `(${legs.untrusted.join(", ")}), AND exfiltrate ` +
                 `(${legs.exfil.join(", ")}) — a prompt-injection exfil path with no exploit code. ` +
-                "Drop at least one leg (Meta's Rule of Two: allow at most two).",
+                "Drop at least one leg (Meta's Rule of Two: allow at most two)." +
+                (ctx.contractUnreadable
+                    ? " (Those tool names were SALVAGED: the frontmatter is not valid YAML, so a strict" +
+                        " loader reads no contract here at all and the real grant may be wider still." +
+                        " Fix the YAML — this finding stands either way.)"
+                    : ""),
         };
     }
+    // Fewer than three legs — but the names were salvaged from a block a strict
+    // loader rejects, so "fewer" is a guess. What that loader actually yields is
+    // NOTHING: no contract, which is inherits-all, which holds every leg. This is
+    // the branch the defect lived in — a malformed unit scored clean because the
+    // salvage happened to read narrow.
+    if (ctx.contractUnreadable) {
+        return lethalTrifectaIssues(["*"], dialect, ctx);
+    }
     return null;
 }
 //# sourceMappingURL=lethal-trifecta.js.map

package/dist/core/rule-meta.js

@@ -139,7 +139,7 @@ exports.RULE_META = {
         bucket: "structural-closed",
         surface: ["hook"],
         defaultSeverity: "warn",
-        summary: "A hook matcher fires (no tool-name typo / malformed MCP form).",
+        summary: "A hook matcher fires as written (no tool-name typo, no MCP pattern that reaches nothing or misses real server names).",
         detector: "hookMatcherIssues",
         upstreamPrevention: "compiled hook tool()/tools() matcher is typed",
     },

package/dist/core/skill-resources.js

@@ -33,8 +33,9 @@ exports.skillResourceIssues = skillResourceIssues;
  * `references/finance.md`", or a markdown-link example demonstrating how to
  * write a path — e.g. one with a space in the filename). A reference (link OR
  * inline path) is treated as real ONLY when the line DIRECTS the agent to use
- * the file (read/run/see/…) and carries no illustrative cue (example / e.g. /
- * such as / would be / template / →). See `inlinePathIsUsed`.
+ * the file (read/run/see/…, or the line is a HEADING naming it — see
+ * `MD_HEADING`) and carries no illustrative cue (example / e.g. / such as /
+ * would be / template / →). See `inlinePathIsUsed`.
  *
  * ESCAPE HATCH: a SKILL.md carrying `<!-- vigiles-disable skill-resource-resolves -->`
  * anywhere in its body opts OUT of this check entirely (mirrors `orphans.ts`'s
@@ -179,18 +180,49 @@ const USE_DIRECTIVE = /\b(run|runs|execute|executes|read|reads|load|loads|open|o
 // pointing at a shipped file. Includes the `→`/`->` arrow used in "move detail
 // → `references/x.md`" authoring lists.
 const ILLUSTRATIVE_CUE = /\b(example|examples|e\.g\.?|i\.e\.?|such as|for instance|would be|helpful|useful|template|boilerplate)\b|→|->/i;
+/**
+ * An ATX markdown heading (`## …`, up to three leading spaces per CommonMark).
+ *
+ * 🔴 WHY A HEADING COUNTS AS A USE-DIRECTIVE. The verb gate below reads PROSE,
+ * and a heading is not prose — it is the section's label. So the single most
+ * common way a skill points at its own bundled script, naming it in the heading
+ * of the section about running it, carried no verb and went unchecked:
+ *
+ *     ## 🏗 START WITH THE MECHANICAL LEG — `scripts/structure.mjs`
+ *
+ * Measured 2026-08-08 on a real skill whose `structure.mjs` sits at the skill
+ * ROOT, not under `scripts/`: that line yielded NOTHING. Rewriting the same
+ * heading to "Run the mechanical leg" — same file, same ref, same missing
+ * target — correctly yielded the finding. The tool's answer depended on the
+ * author's choice of verb, and it stayed silent for three days.
+ *
+ * The narrow fix, and deliberately not the wide one. The alternative — treat
+ * ANY bundle-dir path with an extension as a reference, verb or not — reopens
+ * exactly the false positives the gate exists for (a skill TEACHING how to
+ * build skills mentions `scripts/rotate.py` constantly as prose). A heading
+ * naming a bundle path is a structural claim about what this section is about,
+ * not a sentence illustrating what a skill *could* ship, so it earns the same
+ * standing as an explicit "run …". The illustrative-cue veto still applies —
+ * `## Examples: \`references/finance.md\`` stays skipped — and the check is
+ * `warn` severity with a `vigiles-disable` escape hatch, so a slightly wider
+ * net is affordable where a blanket one is not.
+ */
+const MD_HEADING = /^\s{0,3}#{1,6}\s/;
 /**
  * Whether a bundle-path reference on this line reads as a REAL reference (the
  * agent is told to use the file) rather than an illustrative mention. Requires
- * a positive use-directive and the absence of an illustrative cue — both
- * evaluated over the whole line for simplicity (a tight, precise rule over a
- * clever one). BOTH candidate shapes consult this (issue #110) — a markdown
- * link's `[text](target)` syntax is a stronger signal than a bare inline span,
- * but "For example, see [the schema](...)" is still an illustrative mention,
- * not a real dead ref.
+ * a positive directive — a use verb, or the line being a heading (see
+ * {@link MD_HEADING}) — and the absence of an illustrative cue, both evaluated
+ * over the whole line for simplicity (a tight, precise rule over a clever one).
+ * BOTH candidate shapes consult this (issue #110) — a markdown link's
+ * `[text](target)` syntax is a stronger signal than a bare inline span, but
+ * "For example, see [the schema](...)" is still an illustrative mention, not a
+ * real dead ref.
  */
 function inlinePathIsUsed(line) {
-    return USE_DIRECTIVE.test(line) && !ILLUSTRATIVE_CUE.test(line);
+    if (ILLUSTRATIVE_CUE.test(line))
+        return false;
+    return USE_DIRECTIVE.test(line) || MD_HEADING.test(line);
 }
 /** Collect candidate bundled-resource refs from one body line, skipping fences. */
 function candidatesInLine(line, lineNo) {