vigiles 16.1.1 → 16.1.3

package/dist/core/vocabulary.js

@@ -0,0 +1,262 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classify = classify;
+exports.suggest = suggest;
+exports.termIssue = termIssue;
+exports.scoredIssues = scoredIssues;
+exports.advisoryIssues = advisoryIssues;
+exports.authoringIssues = authoringIssues;
+exports.vocabularyFromLists = vocabularyFromLists;
+/**
+ * HarnessVocabulary — the platform's own words, with a STATUS per word.
+ *
+ * The three vocabulary checks (`hook-events`, `subagent-tool-contract`, and the
+ * `disallowedTools:` mirror) used to model a harness's vocabulary as two
+ * hand-kept arrays — "these names are fine", "these names are dead" — and then
+ * decide what to SAY about a name in neither by its EDIT DISTANCE to the first
+ * array. That is the defect this module exists to remove, and it failed in both
+ * directions at once (measured against the vendor docs, 2026-08-17):
+ *
+ *  - FALSE ACCUSATION. `Setup` is a documented Claude Code hook event. It was
+ *    reported as "a hook here never fires … Did you mean Stop?" — and the
+ *    suggested repair rewires a one-shot setup hook onto every turn's Stop.
+ *    It was caught for one reason only: `setup` happens to sit at edit distance
+ *    2 from `stop`.
+ *  - SILENCE. Of the 31 events the vendor documents, the old catalog held 9.
+ *    The other 22 were not "accepted" — they were unrecognised and >2 away from
+ *    any known name, so nothing was said. `SubagentStart` and `PostCompact` sat
+ *    at distance 3: one character from becoming the next `Setup`.
+ *
+ * So which of the two a valid name got — an accusation or silence — was decided
+ * by spelling luck. Neither is a verdict, and a tool whose pitch is precision
+ * cannot ship either as its answer to "I don't know this word".
+ *
+ * The fix is not a longer array. It is to stop asking "is this string in my
+ * list?" (a boolean, which has no room for "I don't know") and start asking
+ * "what does my catalog SAY about this string?" — a {@link TermVerdict}, which
+ * has four answers because the vendor's own documentation distinguishes four:
+ *
+ *  - `available`     — the platform provides it.
+ *  - `withheld`      — the platform removes it, unconditionally. A real defect.
+ *  - `conditional`   — the platform removes it only under a STATED condition
+ *                      (`Agent` at the depth limit; `ExitPlanMode` unless
+ *                      `permissionMode: plan`; every non-background built-in when
+ *                      the subagent runs in the background). vigiles cannot see
+ *                      the condition, so it must not assert — it reports the
+ *                      condition and stops.
+ *  - `unrecognised`  — not in the catalog. This is a statement about VIGILES,
+ *                      not about the repo being audited, and the message says so.
+ *
+ * THE THIRD OPTION. `unrecognised` is why this module exists. Silence reads as
+ * approval and hides our own staleness; an error blames the user for our gap.
+ * The honest third answer is an ADVISORY that names vigiles as the possibly-stale
+ * party and prints the capture the catalog came from. It is surfaced and it is
+ * never scored, so a name newer than our capture can never cost anyone a grade.
+ *
+ * WHY THE DISTANCE IS NOT ON THE VERDICT. {@link TermVerdict}'s `unrecognised`
+ * branch carries no near-match. A caller therefore CANNOT write
+ * `if (nearest) report()` — the shape that produced both bugs — because at the
+ * point where the report/skip decision is made, no distance is in scope.
+ * {@link suggest} exists solely to decorate a message that is already being
+ * emitted, and is called from the message builder, not from a branch.
+ *
+ * FAILING LOUDLY. `classify` is total: every name returns one of four cases, so
+ * a `switch` that forgets one is a `tsc` error via the `never` exhaustiveness
+ * check in {@link termIssue}. There is no `null`/`undefined` return to ignore.
+ *
+ * GOING STALE. It will. `capturedFrom` records the exact vendor artifact and
+ * version each catalog was read from, and every name we do not hold prints it.
+ * That is the difference from an ordinary allowlist: this one reports its own
+ * age at the moment it is out of date, rather than silently approving the word
+ * it has never heard of.
+ */
+const edit_distance_js_1 = require("./edit-distance.js");
+/** Look the name up. Total: always one of the four verdicts, never null. */
+function classify(vocab, name) {
+    const term = vocab.terms.find((t) => t.name === name);
+    if (term === undefined)
+        return { kind: "unrecognised", name };
+    switch (term.status) {
+        case "available":
+            return { kind: "available", term };
+        case "withheld":
+            return { kind: "withheld", term };
+        case "conditional":
+            return { kind: "conditional", term };
+    }
+}
+/**
+ * Closest catalog name within edit distance 2, else null — a MESSAGE decoration
+ * only. Never call this to decide whether to report something; the verdict has
+ * already decided that. The ≤2 bound stays tight for the reason it always was:
+ * a loose bound mis-suggests (`TaskGet → Task?` is a different real tool, not a
+ * typo). Only `available` terms are offered — suggesting a name the platform
+ * withholds would trade one dead reference for another.
+ */
+function suggest(vocab, name) {
+    const near = nearest(vocab, name);
+    return near !== null && near.distance <= SUGGEST_MAX ? near.name : null;
+}
+/** How far a hint may reach. Beyond this a "did you mean" mis-suggests. */
+const SUGGEST_MAX = 2;
+/**
+ * How close an unrecognised name must be to a real one before vigiles will call
+ * it a TYPO and put it in the grade, rather than treating it as a name it simply
+ * does not know.
+ *
+ * MEASURED, not assumed — and the measurement is the whole reason the old check
+ * failed. Over every pair of distinct names in the two shipped Claude Code
+ * vocabularies (465 hook-event pairs, 741 subagent-tool pairs):
+ *
+ *   distance 1 : 0 pairs of the 1,206
+ *   distance 2 : exactly 1 pair in each — `Setup`/`Stop` and `Bash`/`Task`
+ *
+ * So the vendor does not ship two real names one edit apart, which makes
+ * distance 1 strong evidence of a mistyped name. Distance 2, on the other hand,
+ * is exactly where two genuinely different real names DO collide — and the one
+ * event-pair that collides there is the bug itself: the old code used ≤2 as its
+ * threshold and therefore accused `Setup`, a real event, of being a typo of
+ * `Stop`. The old bound was not merely too loose, it was set precisely at the
+ * width of the collision.
+ *
+ * Hence: distance 1 is scored, distance 2 still earns a did-you-mean but stays
+ * advisory. RESIDUAL RISK, stated plainly: if the vendor ever ships a name one
+ * edit from an existing one, it will be scored as a typo until the catalog is
+ * updated. Zero of 1,206 current pairs are that close, and `dialect-drift` plus
+ * the conformance invariants are what surface the catalog falling behind.
+ */
+const TYPO_MAX = 1;
+/** Closest catalog name and its distance, or null when the vocabulary is empty. */
+function nearest(vocab, name) {
+    let best = null;
+    let bestDistance = Infinity;
+    for (const t of vocab.terms) {
+        if (t.status === "withheld")
+            continue;
+        const d = (0, edit_distance_js_1.editDistance)(name.toLowerCase(), t.name.toLowerCase());
+        if (d < bestDistance) {
+            bestDistance = d;
+            best = t.name;
+        }
+    }
+    return best === null ? null : { name: best, distance: bestDistance };
+}
+/**
+ * Turn a verdict into the finding to report, or null when there is nothing to
+ * say. The severity is decided HERE, once, from the verdict — callers never
+ * invent their own policy, which is what let `scan` and `lint` drift apart from
+ * `compileAgent` before.
+ *
+ * `noun` names the thing in the message ("hook event" / "tool"); `subject`
+ * describes what listing it does, e.g. "a hook here never fires".
+ */
+function termIssue(vocab, verdict, noun, deadConsequence) {
+    switch (verdict.kind) {
+        case "available":
+            return null;
+        case "conditional": {
+            const alias = verdict.term.aliasOf !== undefined
+                ? ` "${verdict.term.name}" is a still-supported deprecated alias of "${verdict.term.aliasOf}".`
+                : "";
+            return {
+                verdict: "conditional",
+                severity: "advisory",
+                suggestion: null,
+                condition: verdict.term.condition,
+                message: `${noun} "${verdict.term.name}" is available to a subagent, but the platform ` +
+                    `removes it ${verdict.term.condition ?? "under a documented condition"}. ` +
+                    `vigiles cannot see that condition from the file, so this is a note, not a defect.${alias}`,
+            };
+        }
+        case "withheld":
+            return {
+                verdict: "withheld",
+                severity: "scored",
+                suggestion: null,
+                message: `${noun} "${verdict.term.name}" is never available to a subagent — remove it from the tools list.`,
+            };
+        case "unrecognised": {
+            const near = nearest(vocab, verdict.name);
+            const suggestion = near !== null && near.distance <= SUGGEST_MAX ? near.name : null;
+            // One edit from a real name, and no two real names are that close (see
+            // TYPO_MAX): this is a mistyped name, and it is dead in the repo now.
+            if (near !== null && near.distance <= TYPO_MAX)
+                return {
+                    verdict: "unrecognised",
+                    severity: "scored",
+                    suggestion,
+                    message: `${noun} "${verdict.name}" matches no known name — ${deadConsequence}. ` +
+                        `Did you mean "${near.name}"?`,
+                };
+            const hint = suggestion !== null ? ` Did you mean "${suggestion}"?` : "";
+            return {
+                verdict: "unrecognised",
+                severity: "advisory",
+                suggestion,
+                message: `${noun} "${verdict.name}" is not in vigiles's ${vocab.kind} catalog ` +
+                    `(captured from ${vocab.capturedFrom}). If it is newer than that capture, or ` +
+                    `custom to your harness, vigiles is out of date — not your config. ` +
+                    `If it is a typo, ${deadConsequence}.${hint}`,
+            };
+        }
+        default: {
+            // Exhaustiveness: a new verdict kind with no branch is a tsc error here,
+            // so a future status cannot be silently dropped on the floor.
+            const never = verdict;
+            return never;
+        }
+    }
+}
+/**
+ * The issues that count toward a grade. Replaces the per-check
+ * `confidentToolIssues` / `confidentHookEventIssues` helpers, which asked "is
+ * there a near match?" — a question about spelling, answered by a helper each
+ * caller had to remember to apply and which `compileAgent` did not, so `scan`,
+ * `lint` and authoring could disagree about which issues were real. Severity now
+ * travels ON the issue, decided once in {@link termIssue}, so the split is the
+ * same wherever it is taken.
+ */
+function scoredIssues(issues) {
+    return issues.filter((i) => i.severity === "scored");
+}
+/**
+ * The issues that are surfaced but never scored — `conditional` tools and any
+ * name newer than our capture. Kept out of the grade on purpose: vigiles's own
+ * staleness must not cost someone a letter.
+ */
+function advisoryIssues(issues) {
+    return issues.filter((i) => i.severity === "advisory");
+}
+/**
+ * The issues an AUTHORING path treats as errors — everything except
+ * `conditional`. Authoring is a CLOSED world: you are writing this spec now,
+ * against the vigiles you have, so an unrecognised name is a typo worth stopping
+ * for. Auditing is an OPEN world: someone else wrote the file, possibly against
+ * a newer platform, so there the same verdict is only an advisory.
+ *
+ * `conditional` is an error in NEITHER. The tool is real and declaring it is
+ * correct; erroring on it is exactly what told delegating subagents to drop
+ * `Agent`, and what made `tools: Agent, Read, Bash` — a worked example in the
+ * vendor's own docs — fail to compile.
+ */
+function authoringIssues(issues) {
+    return issues.filter((i) => i.verdict !== "conditional");
+}
+/**
+ * Build a vocabulary from a dialect that predates this module — `available` from
+ * its built-in catalog, `withheld` from its never-available list. A dialect on
+ * the legacy shape keeps working and its unknowns become `unrecognised`
+ * ADVISORIES rather than silence, which is the honest reading: a catalog with no
+ * recorded capture cannot claim a name is invalid.
+ */
+function vocabularyFromLists(kind, capturedFrom, available, withheld = []) {
+    return {
+        kind,
+        capturedFrom,
+        terms: [
+            ...available.map((name) => ({ name, status: "available" })),
+            ...withheld.map((name) => ({ name, status: "withheld" })),
+        ],
+    };
+}
+//# sourceMappingURL=vocabulary.js.map

package/dist/coverage-evidence.js

@@ -93,6 +93,7 @@ exports.declaredSurfaceName = declaredSurfaceName;
  */
 const frontmatter_read_js_1 = require("./core/frontmatter-read.js");
 const posix_path_js_1 = require("./posix-path.js");
+const source_refs_js_1 = require("./core/source-refs.js");
 /**
  * Is `testPath` the colocated test OF this surface — NAMED after it, SITTING
  * BESIDE it?
@@ -142,9 +143,20 @@ function posixly(p) {
 function prepareTest(path) {
     return { path };
 }
-/** A path that looks like a script, inside a `command` string. Both twins used
- * to declare this separately; it lives here now so they cannot drift on it. */
-const SCRIPT_RE = /[\w./${}@-]+\.(?:sh|mjs|cjs|js|ts|py|rb)/g;
+/**
+ * A path that looks like a script, inside a `command` string. Both twins used to
+ * declare this separately; the extension vocabulary and the trailing boundary
+ * now live in `core/source-refs.ts`, shared with the hook scanner, so the three
+ * cannot drift and none can omit the boundary (without it, `hooks.json` matched
+ * as `hooks.js`).
+ *
+ * ⚠️ This one scans a SERIALIZED settings blob rather than a shell parse, so it
+ * cannot tell an operand from inline program text the way `commandWords` can.
+ * It stays a regex because every hit is gated on the file EXISTING before it
+ * becomes a surface — a stray match is dropped, never reported — so the failure
+ * mode here is under-counting, not accusation.
+ */
+const SCRIPT_RE = (0, source_refs_js_1.scriptRefPattern)();
 /**
  * Is this filename one the PAID real-model runner would actually run?
  *

package/dist/plugin-loader.js

@@ -38,6 +38,7 @@ const node_path_1 = require("node:path");
 const toml_1 = require("@iarna/toml");
 const hash_js_1 = require("./core/hash.js");
 const fs_walk_js_1 = require("./fs-walk.js");
+const source_refs_js_1 = require("./core/source-refs.js");
 const MAX_SKILL_FILE_BYTES = 256 * 1024;
 /** Parse a JSON file, or null on any error (missing / malformed). */
 function safeReadJson(path) {
@@ -319,9 +320,11 @@ function hasMcp(root, layout) {
 }
 // A plugin-relative path reference to a file under a standard surface dir, with a
 // known extension — e.g. a hook script that `cat`s `skills/using-superpowers/SKILL.md`.
-const INTRA_REF_EXTS = "md|sh|cmd|mjs|cjs|js|ts|py|rb|txt|json";
+// The extension vocabulary and BOTH token boundaries live in core/source-refs.ts,
+// so this and its browser twin (scan-files.ts) cannot disagree on them and
+// neither can omit one. See that module for the two boundary defects.
 function intraRefRe(layout) {
-    return new RegExp(`(?:${layout.intraRefDirs.join("|")})/[A-Za-z0-9._/-]+\\.(?:${INTRA_REF_EXTS})`, "g");
+    return (0, source_refs_js_1.intraRefPattern)(layout.intraRefDirs);
 }
 // Shell vars that root a path OUTSIDE the plugin (the user's project / home), so
 // a `surface/…` after one is NOT a plugin-root ref. Anything else ($ROOT,
@@ -340,10 +343,21 @@ const NON_PLUGIN_VARS = new Set([
  * gmickel/flow-next false positive) or a project var (`$CLAUDE_PROJECT_DIR/…`)
  * is NOT a plugin ref. A bare ref (`cat skills/…`) or one after a plugin-root
  * var (`${PLUGIN_ROOT}/skills/…`, obra/superpowers) IS.
+ *
+ * 🔴 THE FIRST QUESTION IS WHETHER THE MATCH STARTS AT A PATH BOUNDARY AT ALL.
+ * "Not preceded by a slash" used to be read as "bare reference", which made
+ * `claude-agents/fable-advisor.md` a bare reference to `agents/fable-advisor.md`
+ * — a resolving path reported broken (`fcakyon/claude-codex-settings`,
+ * 2026-08-17). A preceding path-segment character means the match landed inside
+ * a longer name, which is not a reference to anything.
  */
 function isPluginRooted(content, idx) {
-    if (idx === 0 || content[idx - 1] !== "/")
-        return true; // bare / after quote-space
+    // No `idx === 0` case: start-of-content IS a boundary, and that rule belongs
+    // to `startsAtSeparator` (`idx <= 0 → true`), which the next line reaches with
+    // `content[-1] === undefined`. Restating it here would be a second copy of a
+    // boundary this module deliberately does not own.
+    if (content[idx - 1] !== "/")
+        return (0, source_refs_js_1.startsAtSeparator)(content, idx);
     // The path component immediately before the separating slash.
     const seg = /([^\s"'`(=:/]*)$/.exec(content.slice(0, idx - 1))?.[1] ?? "";
     const varName = /^\$\{?(\w+)\}?$/.exec(seg)?.[1];
@@ -359,27 +373,6 @@ function isPluginRooted(content, idx) {
 // A path in an executable hook/helper script (incl. extensionless ones like
 // obra/superpowers' `hooks/session-start`) IS a real file op — those we scan.
 const DOC_SOURCE_RE = /\.(?:md|markdown|mdx|txt|rst)$/i;
-// A `.sh`/`.bash`/`.cmd` SCRIPT's own `#`-led comments are prose, not code — a
-// usage comment (`# bash skills/<plugin>/hooks/setup.sh`, written as it would be
-// invoked from the REPO CHECKOUT root) is not a real file operation any more than
-// a path mentioned in a doc file is (issue #110). Narrowly scoped to the shell/cmd
-// shapes that conventionally use `#` for a comment (unlike e.g. `.mjs`/`.js`).
-const SCRIPT_COMMENT_RE = /\.(?:sh|bash|cmd)$/i;
-/**
- * Drop FULL-LINE `#` comments (including the shebang, which also starts with
- * `#`) from a `.sh`/`.bash`/`.cmd` script's content before it's scanned for
- * intra-plugin refs — a line whose first non-whitespace character is `#` is
- * prose, never a real command. Full-line only: a `#` inside a quoted string
- * mid-line is left alone, so a genuine ref on a real code line is never
- * dropped. Mirrors `hookBlockIssues`' `stripFullLineComments` discipline
- * (core/hook-block-ineffective.ts).
- */
-function stripShellComments(content) {
-    return content
-        .split("\n")
-        .filter((line) => !line.trimStart().startsWith("#"))
-        .join("\n");
-}
 /**
  * Intra-plugin file references that don't resolve — the partial-vendor / broken-
  * path class (e.g. obra/superpowers' `hooks/session-start` reads
@@ -438,9 +431,10 @@ function executableSources(root, layout) {
         for (const [path, content] of Object.entries(readTree(dir, root))) {
             if (DOC_SOURCE_RE.test(path))
                 continue; // skip prose
-            sources[path] = SCRIPT_COMMENT_RE.test(path)
-                ? stripShellComments(content)
-                : content;
+            // A full-line comment is prose in EVERY language, not only in shell —
+            // both remaining corpus false positives here came out of JSDoc. See
+            // core/source-refs.ts.
+            sources[path] = (0, source_refs_js_1.stripFullLineComments)(path, content);
         }
     }
     return sources;

package/dist/scan-core.d.ts

@@ -1,3 +1,4 @@
+import type { HookEventIssue } from "./core/hook-events.js";
 import { type DescriptionOverlap } from "./core/description-overlap.js";
 import { type DescriptionBudgetIssue } from "./core/skill-description-budget.js";
 import type { SkillRefSource } from "./skill-refs.js";
@@ -6,7 +7,7 @@ import type { HarnessDialect } from "./core/dialect.js";
 import type { HookRegistration } from "./core/hook-normalize.js";
 import type { HookScriptEntry } from "./core/hook-block-ineffective.js";
 import type { HookMatcherEntry } from "./core/hook-matcher.js";
-import type { ScanSkill, ScanAgent, ScanHook, FrontmatterIssue, FrontmatterValueIssue, FrontmatterParseIssue, ScanTrifectaFinding, ScanSkillResourceFinding, ScanSkillFenceFinding, ScanDelegationFinding } from "./scan.js";
+import type { ScanSkill, ScanAgent, ScanHook, FrontmatterIssue, FrontmatterValueIssue, FrontmatterParseIssue, ScanTrifectaFinding, ScanSkillResourceFinding, ScanSkillFenceFinding, ScanDelegationFinding, VocabularyNote } from "./scan.js";
 /**
  * Per-kind surface classifiers, built from the harness `PluginLayout`'s
  * `skillDir`/`agentDir`/`commandDir` — so adding a harness whose subagents live
@@ -201,4 +202,10 @@ export declare function summarizePurity(agents: readonly ScanAgent[]): {
     bounded: number;
     unrestricted: number;
 };
+/**
+ * Gather the advisory half of the vocabulary findings for the report. Kept in
+ * one place so hook events and subagent tools present identically — the two used
+ * to answer the same question with different policies.
+ */
+export declare function collectVocabularyNotes(hookEventIssues: readonly HookEventIssue[], agents: readonly ScanAgent[]): VocabularyNote[];
 //# sourceMappingURL=scan-core.d.ts.map

package/dist/scan-core.js

@@ -20,6 +20,7 @@ exports.collectDelegationTrifecta = collectDelegationTrifecta;
 exports.collectHookBlockEntries = collectHookBlockEntries;
 exports.collectHookMatchers = collectHookMatchers;
 exports.summarizePurity = summarizePurity;
+exports.collectVocabularyNotes = collectVocabularyNotes;
 /**
  * scan-core — the PURE, NODE-FREE detector runtime behind `vigiles audit`.
  *
@@ -45,18 +46,45 @@ const skill_description_budget_js_1 = require("./core/skill-description-budget.j
 const mcp_tool_js_1 = require("./core/mcp-tool.js");
 const lethal_trifecta_js_1 = require("./core/lethal-trifecta.js");
 const skill_resources_js_1 = require("./core/skill-resources.js");
+const bash_effects_js_1 = require("./core/bash-effects.js");
+const source_refs_js_1 = require("./core/source-refs.js");
 const skill_missing_fence_js_1 = require("./core/skill-missing-fence.js");
 const delegation_trifecta_js_1 = require("./core/delegation-trifecta.js");
 const effects_js_1 = require("./core/effects.js");
 const agent_tools_js_1 = require("./adapters/claude-code/agent-tools.js");
-// A script-path token inside a hook command. The token class is `\S` MINUS the
-// glob metacharacters `*` and `?` (dogfood D1): a real, resolvable hook path
-// never contains them, but a command that merely MENTIONS a glob — e.g.
+// A script-path token, matched against a WHOLE shell WORD. The token class is
+// `\S` MINUS the glob metacharacters `*` and `?` (dogfood D1): a real, resolvable
+// hook path never contains them, but a command that merely MENTIONS a glob — e.g.
 // `find . -name "*.js"` in a hook body — would otherwise have `"*.js"` grabbed as
 // a "script" and reported MISSING (a false positive). Shell vars / braces /
-// quotes / slashes ARE kept (`${CLAUDE_PLUGIN_ROOT}/hooks/x.sh`, `"$HOME"/y.sh`),
-// since resolveScript expands + strips those; only glob patterns are dropped.
-const SCRIPT_RE = /[^\s*?]+\.(?:sh|mjs|cjs|js|ts|py|rb)\b/g;
+// slashes ARE kept (`${CLAUDE_PLUGIN_ROOT}/hooks/x.sh`), since resolveScript
+// expands those. See core/source-refs.ts for the boundary rules.
+const SCRIPT_WORD_RE = (0, source_refs_js_1.scriptWordPattern)();
+/**
+ * The script-path operands a hook `command` names.
+ *
+ * 🔴 THE COMMAND IS SHELL, SO IT IS PARSED AS SHELL. This used to run
+ * `SCRIPT_RE` over the raw command string, which cannot tell an operand from
+ * the text of an inline program. Against the standard portable-plugin idiom
+ * `node -e "…await import(…join(root,'hooks','always-on.mjs'))…"` it produced
+ * the script name
+ * `import(require(node:url).pathToFileURL(require(node:path).join(root,hooks,always-on.mjs`
+ * and reported it MISSING, while `hooks/always-on.mjs` sat on disk. Nine such
+ * findings across the 32-repo dogfood corpus (2026-08-17), contributing to two
+ * `F/0` grades.
+ *
+ * `commandWords` returns the words a shell would resolve, with inline program
+ * text subtracted, so the report cannot name a fragment of a JavaScript
+ * expression. A command that does not parse as shell yields `null`, and the
+ * caller treats it as an inline one-liner rather than guessing — abstaining is
+ * the direction that cannot accuse.
+ */
+function scriptTokens(command) {
+    const words = (0, bash_effects_js_1.commandWords)(command);
+    if (words === null)
+        return null;
+    return words.filter((w) => SCRIPT_WORD_RE.test(w));
+}
 // The scalar fields scan reads from a skill/agent `---` block, via the shared
 // lenient reader (core/frontmatter-read.ts) — a real YAML parse with a regex
 // salvage on malformed input, so block scalars / multi-line quoted values parse
@@ -411,6 +439,9 @@ ctx) {
         // including every side-effecting one — pass the wildcard sentinel so
         // effectSurface correctly classifies it as `"unrestricted"`.
         const surface = (0, effects_js_1.effectSurface)(tools ?? ["*"], dialect);
+        // Classify ONCE; the scored and advisory halves are two views of one result,
+        // so they cannot disagree about what the vocabulary said.
+        const vocabIssues = tools ? (0, tool_contract_js_1.verifyToolContract)(tools, dialect) : [];
         out.push({
             name: (0, posix_path_js_1.basename)(path, ".md"),
             path: ctx
@@ -418,12 +449,16 @@ ctx) {
                 : path,
             tools,
             // Cross-reference the declared rail against the dialect catalog — the moat.
-            // Auditing third-party plugins → only the HIGH-CONFIDENCE issues (never-
-            // available + close typos); a bare unrecognized tool is likely plugin/MCP-
-            // provided, not a defect (the TaskCreate/TaskGet lesson). See tool-contract.ts.
-            toolIssues: tools
-                ? (0, tool_contract_js_1.confidentToolIssues)((0, tool_contract_js_1.verifyToolContract)(tools, dialect))
-                : [],
+            // The SCORED half only: a tool the platform withholds unconditionally, or a
+            // name one edit from a real one (no two real names are that close, so that
+            // is a typo). Everything else the vocabulary has an opinion about goes to
+            // `toolNotes` — surfaced, never graded. See core/vocabulary.ts.
+            toolIssues: tools ? (0, tool_contract_js_1.scoredIssues)(vocabIssues) : [],
+            // Advisory: a real tool the platform withholds only under a condition
+            // vigiles cannot see (`Agent` at the depth limit), and a name that is
+            // simply not in our capture — which may mean the catalog is stale, not
+            // that the contract is wrong.
+            toolNotes: tools ? (0, tool_contract_js_1.advisoryIssues)(vocabIssues) : [],
             // The MCP half of the moat: an `mcp__server__tool` whose server isn't in the
             // plugin's declared set can't resolve. High-precision (gated on a declared
             // set, built-ins allowlisted, plugin-namespaced form skipped). See mcp-tool.ts.
@@ -518,7 +553,7 @@ function preferCompiledHooksMessage(count) {
 function eventsByScript(regs) {
     const map = new Map();
     for (const reg of regs) {
-        for (const tok of reg.command.match(SCRIPT_RE) ?? []) {
+        for (const tok of scriptTokens(reg.command) ?? []) {
             if (!map.has(tok))
                 map.set(tok, reg.event);
         }
@@ -537,7 +572,7 @@ function scanHooks(regs, root, pluginRootToken, exists) {
     const byScript = new Map();
     let inline = 0;
     for (const cmd of commands) {
-        const found = cmd.match(SCRIPT_RE);
+        const found = scriptTokens(cmd);
         if (!found || found.length === 0) {
             inline++;
             continue;
@@ -798,13 +833,13 @@ function collectHookBlockEntries(regs, root, pluginRootToken, exists) {
         // A wrapper command runs MORE than one script (`node run.cjs guard.mjs`),
         // so resolve EVERY candidate and inspect each — reading only the first
         // (the wrapper) would miss the guard's block logic. Candidates: extensioned
-        // script tokens (SCRIPT_RE) PLUS path-like words with NO extension
+        // script-shaped words PLUS path-like words with NO extension
         // (`bash hooks/guard`, `${ROOT}/hooks/session-start`) that resolve to a file.
-        const candidates = new Set(cmd.match(SCRIPT_RE) ?? []);
-        for (const word of cmd.split(/\s+/)) {
-            const w = word.replace(/^["']+|["']+$/g, "");
-            if (w.startsWith("-"))
-                continue; // a flag, not a path
+        // Words the SHELL would resolve — not a split on whitespace, which cannot
+        // see quoting and cannot tell `node -e '<program>'` from an operand.
+        const words = (0, bash_effects_js_1.commandWords)(cmd) ?? [];
+        const candidates = new Set(words.filter((w) => SCRIPT_WORD_RE.test(w)));
+        for (const w of words) {
             if (w.includes("/") || w.includes(pluginRootToken))
                 candidates.add(w);
         }
@@ -852,4 +887,54 @@ function summarizePurity(agents) {
         return acc;
     }, { pure: 0, bounded: 0, unrestricted: 0 });
 }
+// ---------------------------------------------------------------------------
+// Vocabulary notes — the advisory half of the findings
+// ---------------------------------------------------------------------------
+// These live HERE, not in scan.ts, because both engines produce them and only
+// this module is node-free. Importing them from scan.ts pulled the node-only
+// graph (down to `@ast-grep/napi`'s native .node binding) into the browser
+// bundle and broke the site build — the gate that owns this invariant.
+/**
+ * Gather the advisory half of the vocabulary findings for the report. Kept in
+ * one place so hook events and subagent tools present identically — the two used
+ * to answer the same question with different policies.
+ */
+function collectVocabularyNotes(hookEventIssues, agents) {
+    return [
+        ...(0, tool_contract_js_1.advisoryIssues)(hookEventIssues).map((i) => ({
+            where: `hook event "${i.event}"`,
+            message: i.message,
+        })),
+        ...agents.flatMap((a) => groupAgentToolNotes(a)),
+    ];
+}
+/**
+ * One agent's advisory tool notes, with the `conditional` ones GROUPED by the
+ * condition they share. A delegating subagent legitimately declares eight
+ * foreground-only tools; printing the same sentence eight times is noise, and
+ * noise is what this whole change exists to stop producing. Unrecognised names
+ * stay one-per-tool — each carries its own did-you-mean.
+ */
+function groupAgentToolNotes(agent) {
+    const notes = (0, tool_contract_js_1.advisoryIssues)(agent.toolNotes ?? []);
+    const byCondition = new Map();
+    const out = [];
+    for (const i of notes) {
+        if (i.verdict === "conditional" && i.condition !== undefined) {
+            const at = byCondition.get(i.condition) ?? [];
+            at.push(i.tool);
+            byCondition.set(i.condition, at);
+            continue;
+        }
+        out.push({ where: agent.path, message: i.message });
+    }
+    for (const [condition, tools] of byCondition)
+        out.push({
+            where: agent.path,
+            message: `${tools.join(", ")} ${tools.length === 1 ? "is a real tool" : "are real tools"}, ` +
+                `but the platform removes ${tools.length === 1 ? "it" : "them"} ${condition}. ` +
+                `vigiles cannot see that condition from the file, so this is a note, not a defect.`,
+        });
+    return out;
+}
 //# sourceMappingURL=scan-core.js.map