vigiles 14.2.0 → 14.3.0

package/README.md

@@ -278,7 +278,7 @@ Targets Claude Code and Codex out of the box, or [your own harness](docs/authori
 The **[docs index](docs/README.md)** is the full map, grouped by what you're doing:
 
 - **Guides** — [verify instruction files](docs/verifying-instruction-files.md) · [test your harness](docs/harness-testing.md) · [measure a skill](docs/measuring-skills.md) · [ship a plugin](docs/for-plugin-authors.md) · [Codex & other harnesses](docs/harnesses.md)
-- **Reference** — [CLI](docs/cli.md) · [rules matrix](docs/verifying-instruction-files.md#the-validation-rules--the-full-matrix) · [testing API](docs/testing-api.md) · [full API](https://zernie.github.io/vigiles/)
+- **Reference** — [CLI](docs/cli.md) · [rules matrix](docs/verifying-instruction-files.md#the-validation-rules--the-full-matrix) · [testing API](docs/testing-api.md) · [full API](https://zernie.github.io/vigiles/api/)
 - **Explanation** — [what it catches](docs/what-vigiles-catches.md) · [how it compares](docs/comparison.md) · [FAQ](docs/faq.md)
 
 **Project** — [Stability](STABILITY.md) · [Related tools](docs/comparison.md#what-vigiles-composes-with)

package/dist/audit-score.d.ts

@@ -14,8 +14,10 @@
  * (`lethalTrifectaIssues` → `report.trifectaFindings`): a unit holding all three
  * capability legs is a prompt-injection exfil path detectable from the tool-SET
  * alone — nothing executes, so it sidesteps the confinement blocker. A `"hard"`
- * (explicit all-three) finding is GRADED into the overall; a `"advisory"`
- * (inherits-all) finding is SHOWN in the ring but not graded. NB the EXECUTING
+ * (explicit all-three) finding is GRADED into the overall at a REDUCED weight
+ * (`W_TRIFECTA=10`, HALF the old 20 — a DING, not a fail: it dents the grade
+ * without a catastrophic F for a pattern official plugins ship by design); a
+ * `"advisory"` (inherits-all) finding is SHOWN in the ring but not graded. NB the EXECUTING
  * "do your hooks actually block?" disaster-battery is STILL not an `audit` ring:
  * running arbitrary hooks safely needs cross-platform confinement that isn't
  * shipped yet, so the battery lives in the `vigiles/testing` API via

package/dist/audit-score.js

@@ -18,8 +18,10 @@ exports.formatAuditScore = formatAuditScore;
  * (`lethalTrifectaIssues` → `report.trifectaFindings`): a unit holding all three
  * capability legs is a prompt-injection exfil path detectable from the tool-SET
  * alone — nothing executes, so it sidesteps the confinement blocker. A `"hard"`
- * (explicit all-three) finding is GRADED into the overall; a `"advisory"`
- * (inherits-all) finding is SHOWN in the ring but not graded. NB the EXECUTING
+ * (explicit all-three) finding is GRADED into the overall at a REDUCED weight
+ * (`W_TRIFECTA=10`, HALF the old 20 — a DING, not a fail: it dents the grade
+ * without a catastrophic F for a pattern official plugins ship by design); a
+ * `"advisory"` (inherits-all) finding is SHOWN in the ring but not graded. NB the EXECUTING
  * "do your hooks actually block?" disaster-battery is STILL not an `audit` ring:
  * running arbitrary hooks safely needs cross-platform confinement that isn't
  * shipped yet, so the battery lives in the `vigiles/testing` API via
@@ -154,9 +156,10 @@ function structure(r) {
     };
 }
 /**
- * SAFETY — fed by the STATIC lethal-trifecta check (`report.trifectaFindings`).
- * A `"hard"` finding (an explicit contract naming all three capability legs) is a
- * declared prompt-injection exfil path and is GRADED (`W_TRIFECTA` each, the same
+ * SAFETY — fed by the STATIC lethal-trifecta check (`report.trifectaFindings`), a
+ * GRADED ring. A `"hard"` finding (an explicit contract naming all three
+ * capability legs) is a prompt-injection exfil path and is GRADED at a REDUCED
+ * weight (`W_TRIFECTA=10` each — HALF the old 20, a DING not a fail; the same
  * weight `reportDeductions` sums into the overall, so the ring and the headline
  * agree). A `"advisory"` finding (inherits-all) is SHOWN in the ring's findings
  * but NOT graded — aligned with the inherits-all-is-advisory stance.

package/dist/core/skill-resources.js

@@ -25,6 +25,15 @@ exports.skillResourceIssues = skillResourceIssues;
  * MISSING a real ref over emitting a false positive — a noisy resource check
  * would teach users to ignore it.
  *
+ * The INLINE-CODE path form is weaker than a link, so it carries an extra prose
+ * gate: a skill that TEACHES how to build skills mentions bundle paths
+ * constantly as EXAMPLES of what a skill *could* ship ("a `scripts/rotate.py`
+ * would be helpful to store", "**Examples**: `references/finance.md`"). An
+ * inline path is treated as a real reference 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 / →). Markdown links are
+ * unchanged — a link is already an act-on-it reference. See `inlinePathIsUsed`.
+ *
  * Pure: the only IO is an injectable `existsSync` (default node:fs), mirroring
  * core/refs.ts and the loader so the detector is testable with a fake.
  */
@@ -119,6 +128,46 @@ function isInlineBundlePath(token) {
     const normalized = t.replace(/^\.\//, "");
     return BUNDLE_PREFIX.test(normalized) && HAS_EXT.test(normalized);
 }
+// ---------------------------------------------------------------------------
+// Inline-path prose gate (don't-cry-wolf on TEACHING / illustrative skills)
+// ---------------------------------------------------------------------------
+//
+// An inline-code bundle path (`` `scripts/foo.py` ``) is a much WEAKER signal
+// than a markdown link — skills that TEACH how to build skills (e.g. the
+// official `skill-development` skill) are full of bundle paths used as
+// EXAMPLES of what a skill *could* contain, not as references to a file the
+// skill actually ships: "a `scripts/rotate_pdf.py` would be helpful to store",
+// "**Examples**: `references/finance.md` …", "- **`references/patterns.md`** —
+// Common patterns". Flagging those as "bundled resource not found" cries wolf
+// and graded a clean, correct skill an F.
+//
+// So an inline path is only treated as a real reference when the surrounding
+// prose DIRECTS the agent to ACT on the file (read/run/see/…) AND carries no
+// illustrative/hypothetical cue. Markdown links (`[text](path)`) are unchanged
+// — a link is already a high-confidence, follow-me reference. We bias HARD
+// toward precision here: missing a real dead-ref is far better than a false
+// positive on a teaching skill (the same don't-cry-wolf discipline as the
+// loader's `danglingRefs`).
+// Verbs that direct the agent to CONSUME an existing file. Deliberately EXCLUDES
+// authoring verbs (store/create/add/move/write) — "a `scripts/x.py` would be
+// helpful to STORE in the skill" is describing a resource to CREATE, exactly
+// what a teaching skill illustrates, not a file the skill already ships.
+const USE_DIRECTIVE = /\b(run|runs|execute|executes|read|reads|load|loads|open|opens|source|sources|import|imports|see|view|refer|follow|call|invoke|apply|consult|check)\b/i;
+// Illustrative / hypothetical prose cues — a line carrying one is describing
+// what a skill MIGHT contain (an example, a suggestion, a template), not
+// 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;
+/**
+ * Whether an inline bundle-path 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). Only the inline-path branch consults this; markdown links do not.
+ */
+function inlinePathIsUsed(line) {
+    return USE_DIRECTIVE.test(line) && !ILLUSTRATIVE_CUE.test(line);
+}
 /** Collect candidate bundled-resource refs from one body line, skipping fences. */
 function candidatesInLine(line, lineNo) {
     const out = [];
@@ -129,14 +178,18 @@ function candidatesInLine(line, lineNo) {
             out.push({ ref: m[1].trim(), resolved, kind: "link", line: lineNo });
         }
     }
-    // Inline-code path mentions: only the high-confidence bundle-dir-prefixed form.
-    for (const m of line.matchAll(INLINE_SPAN)) {
-        const token = m[1].trim();
-        if (!isInlineBundlePath(token))
-            continue;
-        const resolved = localResourceTarget(token);
-        if (resolved !== null) {
-            out.push({ ref: token, resolved, kind: "path", line: lineNo });
+    // Inline-code path mentions: only the high-confidence bundle-dir-prefixed
+    // form, AND only when the surrounding prose USES the file (not an illustrative
+    // mention on a teaching skill — see `inlinePathIsUsed`).
+    if (inlinePathIsUsed(line)) {
+        for (const m of line.matchAll(INLINE_SPAN)) {
+            const token = m[1].trim();
+            if (!isInlineBundlePath(token))
+                continue;
+            const resolved = localResourceTarget(token);
+            if (resolved !== null) {
+                out.push({ ref: token, resolved, kind: "path", line: lineNo });
+            }
         }
     }
     return out;

package/dist/dialect-drift.d.ts

@@ -43,9 +43,27 @@ export declare function eventsMissingFromBundle(bundle: string, events: readonly
  * we only read files the user already installed under their own CC license.
  */
 export declare function findClaudeCodePackage(): string | null;
+/**
+ * Extract the semver core from a `claude --version` line
+ * (e.g. `"2.1.211 (Claude Code)"` → `"2.1.211"`). Pure; null when absent.
+ */
+export declare function parseClaudeVersion(raw: string): string | null;
+/**
+ * The version of the `claude` binary actually on PATH — which can DIFFER from the
+ * package {@link findClaudeCodePackage} locates. In the native-binary era CC ships
+ * as a platform binary with no readable `sdk-tools.d.ts`, so a box can carry a
+ * stale leftover `@anthropic-ai/claude-code` in a global `node_modules` (readable,
+ * but months old and NOT what's running) beside the real, newer CC. Reconciling
+ * against this stops the drift alarm crying wolf on that leftover. Real IO; null
+ * when `claude` isn't runnable.
+ */
+export declare function onPathClaudeVersion(): string | null;
 /** A runtime drift report: how the INSTALLED CC's tool surface compares to ours. */
 export interface DialectDriftReport {
+    /** Version of the located `@anthropic-ai/claude-code` package (its types we read). */
     readonly installedVersion: string;
+    /** Version of the `claude` binary on PATH, or null — the actually-running CC. */
+    readonly runningVersion: string | null;
     readonly validatedVersion: string;
     /** Tool-input types present in the install but not in ACKNOWLEDGED (CC added). */
     readonly newToolTypes: string[];

package/dist/dialect-drift.js

@@ -5,6 +5,8 @@ exports.parseToolInputTypes = parseToolInputTypes;
 exports.findClaudeCodeBundle = findClaudeCodeBundle;
 exports.eventsMissingFromBundle = eventsMissingFromBundle;
 exports.findClaudeCodePackage = findClaudeCodePackage;
+exports.parseClaudeVersion = parseClaudeVersion;
+exports.onPathClaudeVersion = onPathClaudeVersion;
 exports.checkDialectDrift = checkDialectDrift;
 exports.formatDialectDrift = formatDialectDrift;
 /**
@@ -36,7 +38,13 @@ exports.formatDialectDrift = formatDialectDrift;
  * NOT a readable `cli.js` JS bundle. So the old "grep hook-event string literals out
  * of cli.js" check has no bundle to read and degrades to a LOUD SKIP (see
  * `findClaudeCodeBundle`); `sdk-tools.d.ts` is still shipped, so the tool-type drift
- * alarm keeps working.
+ * alarm keeps working. But the native binary means a box can carry a STALE leftover
+ * `@anthropic-ai/claude-code` JS package (readable `sdk-tools.d.ts`, months old) in a
+ * global `node_modules` while the real, newer CC runs from the native binary — so
+ * `findClaudeCodePackage` can locate a package that ISN'T what's running. The runtime
+ * alarm (`checkDialectDrift`/`formatDialectDrift`) reconciles the located package
+ * version against the on-PATH `claude --version` and SUPPRESSES the warning on a
+ * mismatch (the located types don't describe the running CC — crying wolf otherwise).
  *
  * Pure parsers (testable with fixtures) + a local-install locator. TWO consumers:
  * the gated CI test in `dialect-drift.test.ts` (fails loud on tool/event drift), and
@@ -167,6 +175,31 @@ function findClaudeCodePackage() {
     }
     return null;
 }
+/**
+ * Extract the semver core from a `claude --version` line
+ * (e.g. `"2.1.211 (Claude Code)"` → `"2.1.211"`). Pure; null when absent.
+ */
+function parseClaudeVersion(raw) {
+    const m = raw.match(/\b(\d+\.\d+\.\d+)\b/);
+    return m ? m[1] : null;
+}
+/**
+ * The version of the `claude` binary actually on PATH — which can DIFFER from the
+ * package {@link findClaudeCodePackage} locates. In the native-binary era CC ships
+ * as a platform binary with no readable `sdk-tools.d.ts`, so a box can carry a
+ * stale leftover `@anthropic-ai/claude-code` in a global `node_modules` (readable,
+ * but months old and NOT what's running) beside the real, newer CC. Reconciling
+ * against this stops the drift alarm crying wolf on that leftover. Real IO; null
+ * when `claude` isn't runnable.
+ */
+function onPathClaudeVersion() {
+    try {
+        return parseClaudeVersion((0, node_child_process_1.execSync)("claude --version", { encoding: "utf-8" }));
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Best-effort, read-local drift check for `scan` (and other runtime callers). Reads
  * only the small `sdk-tools.d.ts` (fast — no `cli.js` bundle scan; events are the
@@ -191,6 +224,7 @@ function checkDialectDrift() {
         }
         return {
             installedVersion,
+            runningVersion: onPathClaudeVersion(),
             validatedVersion: exports.VALIDATED_CC_VERSION,
             newToolTypes: [...installed].filter((t) => !ack.has(t)).sort(),
             removedToolTypes: [...ack].filter((t) => !installed.has(t)).sort(),
@@ -202,7 +236,15 @@ function checkDialectDrift() {
 }
 /** A one-line freshness warning if the dialect drifted from the install, else null. */
 function formatDialectDrift(r) {
-    if (!r || (r.newToolTypes.length === 0 && r.removedToolTypes.length === 0))
+    if (!r)
+        return null;
+    // The located `sdk-tools.d.ts` belongs to a DIFFERENT install than the CC
+    // actually running (a stale leftover npm package beside a newer native binary),
+    // so its tool set says nothing about the CC you're on — don't cry wolf. The
+    // pinned CI drift TEST is where real drift is gated.
+    if (r.runningVersion && r.runningVersion !== r.installedVersion)
+        return null;
+    if (r.newToolTypes.length === 0 && r.removedToolTypes.length === 0)
         return null;
     const parts = [];
     if (r.newToolTypes.length > 0)

package/dist/leaderboard.d.ts

@@ -26,7 +26,7 @@ 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;
-export declare const W_TRIFECTA = 20;
+export declare const W_TRIFECTA = 10;
 /** 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. */

package/dist/leaderboard.js

@@ -49,10 +49,12 @@ exports.W_NO_DESCRIPTION = 10; // a skill with no usable description → can't t
 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)
-exports.W_TRIFECTA = 20; // a HARD lethal-trifecta contract (all three legs, explicit) → a declared prompt-injection exfil path
+exports.W_TRIFECTA = 10; // a HARD lethal-trifecta contract (all three legs, explicit) → a prompt-injection exfil path. HALF the old 20: a DING, not a fail — a trifecta is a real risk worth surfacing in the grade, but official plugins ship the pattern by design, so it dents the score (e.g. feature-dev's 3 hard units → −30 → C) without a catastrophic F.
 // 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.
+//   - an inherits-all (severity "advisory") trifecta finding — shown by the Safety
+//     ring but never scored; only the HARD, explicit all-three-legs finding grades.
 /** Map a 0–100 structural-health score to its letter grade (A ≥90 … F <60). */
 function gradeFor(score) {
     if (score >= 90)
@@ -79,9 +81,11 @@ function reportDeductions(r) {
     const deadMcpTools = r.agents.reduce((n, a) => n + a.mcpToolIssues.length, 0);
     const deadDisallowed = r.agents.reduce((n, a) => n + a.disallowedToolIssues.length, 0);
     // HARD lethal-trifecta findings only — an EXPLICIT contract naming all three
-    // legs (a declared exfil path). Advisory (inherits-all) trifecta findings are
-    // surfaced but NEVER graded (aligned with the inherits-all stance), so they're
-    // excluded here.
+    // legs (a prompt-injection exfil path). Graded at W_TRIFECTA=10 (HALF the old
+    // 20): a DING that surfaces a real risk in the grade without a catastrophic F
+    // for an accepted design pattern official plugins ship. Advisory (inherits-all)
+    // trifecta findings are surfaced but NEVER graded (aligned with the inherits-all
+    // stance), so they're excluded here.
     const hardTrifecta = r.trifectaFindings.filter((f) => f.finding.severity === "hard").length;
     return [
         {
@@ -283,13 +287,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: lethal-trifecta unit -20, 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.");
+    out.push("", "Structural health only (no model). Weights: missing hook -15, hard lethal-", "trifecta unit -10, no-description skill -10, broken intra-plugin ref -8, dead", "tool/MCP ref -8. Inherit-all subagents, inherits-all trifecta and untested", "surfaces are advisory — shown, not scored.");
     return out.join("\n");
 }
-const LEADERBOARD_METHOD = "_Structural health only (deterministic, no model): lethal-trifecta unit −20, " +
-    "missing hook −15, 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._";
+const LEADERBOARD_METHOD = "_Structural health only (deterministic, no model): missing hook −15, hard " +
+    "lethal-trifecta unit −10, no-description skill −10, broken intra-plugin / dead-tool ref −8. " +
+    "Inherit-all subagents, inherits-all trifecta 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigiles",
-  "version": "14.2.0",
+  "version": "14.3.0",
   "description": "Lint & test the harness your AI agent runs on — verify the references in your CLAUDE.md / AGENTS.md and test that your hooks and skills actually work.",
   "keywords": [
     "claude-code",