vigiles 16.1.1 → 16.1.3

package/dist/core/skill-resources.js

@@ -37,6 +37,15 @@ exports.skillResourceIssues = skillResourceIssues;
  * `MD_HEADING`) and carries no illustrative cue (example / e.g. / such as /
  * would be / template / →). See `inlinePathIsUsed`.
  *
+ * CANDIDATES COME FROM THE PARSE, THE GATE READS THE PROSE. Every candidate is
+ * a `MarkdownRef` from `core/markdown.ts` — a link's DESTINATION or a code span
+ * that is not inside a link's text. The line is then consulted only to decide
+ * whether the surrounding prose DIRECTS the agent at the file. Before that
+ * split, a second regex scanned each line for backtick spans without knowing it
+ * was standing inside a link, and reported the link's LABEL as a missing
+ * resource while its destination resolved (measured on
+ * `microsoft/power-platform-skills` and `rohitg00/pro-workflow`, 2026-08-17).
+ *
  * 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
  * `vigiles-disable orphan-docs`) — for a skill whose body is inherently full of
@@ -57,13 +66,6 @@ const markdown_js_1 = require("./markdown.js");
 // these is unambiguously a local bundled resource, even without a `./`.
 const BUNDLE_DIRS = ["scripts", "references", "assets"];
 const BUNDLE_PREFIX = new RegExp(`^(?:${BUNDLE_DIRS.join("|")})/`);
-// A markdown inline link `[text](target)` — we read its target.
-const MD_LINK = /\[[^\]]*\]\(([^)\s]+)\)/g;
-// An inline-code path mention: a backtick span whose whole content is a single
-// path token. We only treat it as a ref when it is a bundle-dir-prefixed path
-// with an extension (the high-confidence shape); a bare `scripts` or a generic
-// `foo.ts` mention is NOT flagged.
-const INLINE_SPAN = /`([^`\n]+)`/g;
 // A path must carry a file extension to be a resource reference. A bare word or
 // a directory name (`scripts/lib`) is undecidable prose — skipped.
 const HAS_EXT = /\.[A-Za-z0-9]+$/;
@@ -224,39 +226,40 @@ function inlinePathIsUsed(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) {
-    const out = [];
-    // A markdown link is EXPLICIT follow-me syntax (`[text](target)`) — the link IS
-    // the reference — so it's real UNLESS the line is an illustrative example.
-    // Suppress it ONLY on an illustrative cue; do NOT also require a use directive,
-    // or a plain `Resources: [API](references/api.md)` (no verb) goes unchecked
-    // (Codex review — that under-detection). A BARE inline backtick path is noisier
-    // (often just a mention), so it still needs BOTH a use directive AND no cue.
-    const illustrative = ILLUSTRATIVE_CUE.test(line);
-    // Markdown links: a relative path target that passes the local-resource gate.
-    if (!illustrative) {
-        for (const m of line.matchAll(MD_LINK)) {
-            const resolved = localResourceTarget(m[1]);
-            if (resolved !== null) {
-                out.push({ ref: m[1].trim(), resolved, kind: "link", line: lineNo });
-            }
-        }
-    }
-    // Inline-code path mentions: only the high-confidence bundle-dir-prefixed form,
-    // and only when the prose directs the agent to use it (the noisier shape).
-    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 });
-            }
-        }
+/**
+ * Turn one structural markdown reference into a candidate, or `null`.
+ *
+ * `line` is the raw source line, used ONLY by the prose gate — the candidate
+ * itself comes from {@link markdownRefs}, never from the characters. That split
+ * is load-bearing: the gate reads prose because prose is what it judges, while
+ * a REFERENCE is a thing the parser found.
+ */
+function candidateFor(ref, line) {
+    if (ref.kind === "link") {
+        // A markdown link is EXPLICIT follow-me syntax — the DESTINATION is the
+        // reference — so it's real UNLESS the line is an illustrative example.
+        // Suppress it ONLY on an illustrative cue; do NOT also require a use
+        // directive, or a plain `Resources: [API](references/api.md)` (no verb)
+        // goes unchecked (Codex review — that under-detection).
+        if (ILLUSTRATIVE_CUE.test(line))
+            return null;
+        const resolved = localResourceTarget(ref.value);
+        if (resolved === null)
+            return null;
+        return { ref: ref.value.trim(), resolved, kind: "link", line: ref.line };
     }
-    return out;
+    // A bare inline backtick path is noisier (often just a mention), so it needs
+    // BOTH a use directive AND no cue, and only in the high-confidence
+    // bundle-dir-prefixed form.
+    if (!inlinePathIsUsed(line))
+        return null;
+    const token = ref.value.trim();
+    if (!isInlineBundlePath(token))
+        return null;
+    const resolved = localResourceTarget(token);
+    if (resolved === null)
+        return null;
+    return { ref: token, resolved, kind: "path", line: ref.line };
 }
 /**
  * A SKILL.md body carrying this marker opts OUT of skill-resource checking
@@ -293,25 +296,23 @@ function skillResourceIssues(skillBody, skillDir, opts) {
     const findings = [];
     const seen = new Set();
     const lines = skillBody.split("\n");
-    const fenced = (0, markdown_js_1.fencedLineFlags)(skillBody);
-    for (let i = 0; i < lines.length; i++) {
-        if (fenced[i])
+    for (const ref of (0, markdown_js_1.markdownRefs)(skillBody)) {
+        const c = candidateFor(ref, lines[ref.line - 1] ?? "");
+        if (c === null)
+            continue;
+        if (resolvesAnywhere(c.resolved))
+            continue;
+        // De-dupe the same missing file referenced several times in the body.
+        const key = `${c.kind}:${c.resolved}`;
+        if (seen.has(key))
             continue;
-        for (const c of candidatesInLine(lines[i], i + 1)) {
-            if (resolvesAnywhere(c.resolved))
-                continue;
-            // De-dupe the same missing file referenced several times in the body.
-            const key = `${c.kind}:${c.resolved}`;
-            if (seen.has(key))
-                continue;
-            seen.add(key);
-            findings.push({
-                ref: c.ref,
-                resolved: c.resolved,
-                kind: c.kind,
-                line: c.line,
-            });
-        }
+        seen.add(key);
+        findings.push({
+            ref: c.ref,
+            resolved: c.resolved,
+            kind: c.kind,
+            line: c.line,
+        });
     }
     return findings;
 }

package/dist/core/source-refs.d.ts

@@ -0,0 +1,118 @@
+/**
+ * vigiles — recovering a FILE REFERENCE from PLAIN SOURCE TEXT.
+ *
+ * The third of three reference grammars, and the only one with no parser behind
+ * it. A markdown body is read by markdown-it (`core/markdown.ts` →
+ * `markdownRefs`), a hook `command` is read by mvdan-sh (`core/bash-effects.ts`
+ * → `commandWords`), and what is left — the body of a hook script, a helper
+ * `.js` / `.py` / `.rb` — is scanned for path-shaped character runs, because a
+ * general-purpose "find every path this program touches" analysis is not a
+ * thing this tool can be.
+ *
+ * Since that scan IS a character run, the only thing standing between it and a
+ * false accusation is where the run may START and STOP. This module owns both
+ * boundaries and the extension vocabularies, so no caller can build a pattern
+ * without them.
+ *
+ * ## The two boundaries, and the two live defects that came from omitting them
+ *
+ * RIGHT — the extension must END the token. `INTRA_REF_EXTS` used to be a bare
+ * alternation with no trailing assertion, and `js` sits ahead of `json` in it,
+ * so `hooks/hooks.json` matched as `hooks/hooks.js`. Measured 2026-08-17 on
+ * `microsoft/power-platform-skills`: a `//` comment naming `hooks/hooks.json`,
+ * with that exact file sitting beside it on disk, was reported as
+ * "hooks/hooks.js (referenced but MISSING)" — a maintainer told a file they
+ * have is missing, under a name they never wrote.
+ *
+ * LEFT — the surface dir must START the token. `(?:agents|hooks|skills)/` with
+ * nothing before it also matches the tail of `claude-agents/`. Measured the
+ * same day on `fcakyon/claude-codex-settings`: a
+ * `new URL("../../../claude-agents/fable-advisor.md", …)` — a correct,
+ * resolving reference — was reported as a broken `agents/fable-advisor.md`.
+ * That boundary is a predicate ({@link startsAtSeparator}) rather than a regex
+ * lookbehind, because the browser twin (`scan-files.ts`) compiles this into the
+ * demo engine, and because the caller already inspects `m.index` for its
+ * plugin-rooted test.
+ *
+ * ## Comments are prose in every language, not only in shell
+ *
+ * `stripShellComments` had the right idea and too narrow a domain: a full-line
+ * `#` in a `.sh` file is prose, and so is a full-line `//` or a JSDoc `*` in a
+ * `.js` file. Both remaining corpus false accusations in this detector came out
+ * of JSDoc — `* It is deliberately not registered in hooks/hooks.json:` and
+ * "`git log --grep=.env -- hooks/x.mjs` is refused …". Neither is a file
+ * operation; both were reported as broken references.
+ *
+ * FULL-LINE ONLY, the same rule the shell version already held. A trailing
+ * comment on a real code line is left alone, so a genuine reference sharing a
+ * line with code is never dropped. The cost is stated rather than hidden: a
+ * path mentioned ONLY in a trailing comment still counts as a reference.
+ */
+/**
+ * Whether a match at `idx` begins at a path boundary rather than inside a
+ * longer name. Position 0 counts as a boundary.
+ *
+ * `/` is a boundary on purpose: `${CLAUDE_PLUGIN_ROOT}/hooks/x.sh` is the
+ * standard spelling, and the caller's plugin-rooted test decides whether the
+ * segment before that slash roots the path inside the plugin or outside it.
+ */
+export declare function startsAtSeparator(content: string, idx: number): boolean;
+/**
+ * Extensions an intra-plugin reference may carry — the file kinds a plugin's
+ * own hook / helper source legitimately points at.
+ */
+export declare const INTRA_REF_EXTENSIONS: readonly ["md", "sh", "cmd", "mjs", "cjs", "js", "ts", "py", "rb", "txt", "json"];
+/**
+ * Extensions a RUNNABLE script carries. Shared by the hook scanner and the
+ * coverage twins, which each declared their own copy before.
+ */
+export declare const SCRIPT_REF_EXTENSIONS: readonly ["sh", "mjs", "cjs", "js", "ts", "py", "rb"];
+/**
+ * A plugin-relative path under one of `dirs`, carrying a known extension — the
+ * pattern for scanning a plugin's own SOURCE TEXT.
+ *
+ * The left boundary is not baked into the returned regex (see
+ * {@link startsAtSeparator}): a caller scanning raw text must apply that
+ * predicate at `m.index`, which both the disk detector and its browser twin do
+ * inside their plugin-rooted test.
+ */
+export declare function intraRefPattern(dirs: readonly string[]): RegExp;
+/**
+ * A script path occupying a WHOLE shell WORD.
+ *
+ * ⚠️ ANCHORING IS NOT WHAT FIXES THE `node -e` DEFECT, and saying so would be
+ * wrong twice over — the payload
+ * `import(require(node:url).pathToFileURL(require(node:path).join(root,hooks,always-on.mjs`
+ * contains no whitespace and ends in `.mjs`, so it satisfies this pattern
+ * perfectly (asserted in source-refs.test.ts, so the claim cannot drift back).
+ * That defect is fixed one level up, by `commandWords` refusing to hand the
+ * argument of `-e` to anyone.
+ *
+ * What anchoring buys is narrower and worth stating exactly: the reported name
+ * is always a word a shell could hand to `execve`, never a fragment cut out of
+ * a longer one. `echo "see hooks/x.sh"` is one word containing a path; before,
+ * `hooks/x.sh` was lifted out of it and checked as though the hook ran it.
+ *
+ * The cost, stated rather than discovered later: a path bundled into a flag
+ * (`--require=hooks/x.js`) is no longer seen. Measured across the 32-repo
+ * dogfood corpus, that costs zero findings.
+ */
+export declare function scriptWordPattern(): RegExp;
+/**
+ * A script path appearing anywhere inside a string — for the one caller with no
+ * shell parse to hand (the coverage twins scan a serialized settings blob).
+ * Carries the right boundary; it cannot carry the left one, and its callers
+ * gate every hit on the file existing, so a stray match is dropped rather than
+ * reported.
+ */
+export declare function scriptRefPattern(): RegExp;
+/**
+ * Drop FULL-LINE comments (including a shebang, which also starts with `#`)
+ * from an executable source before it is scanned for path references.
+ *
+ * A file of unknown kind is returned unchanged: guessing a comment syntax is
+ * how a real reference gets deleted, and this detector's contract is that it
+ * under-reports rather than accuses.
+ */
+export declare function stripFullLineComments(path: string, content: string): string;
+//# sourceMappingURL=source-refs.d.ts.map

package/dist/core/source-refs.js

@@ -0,0 +1,206 @@
+"use strict";
+/**
+ * vigiles — recovering a FILE REFERENCE from PLAIN SOURCE TEXT.
+ *
+ * The third of three reference grammars, and the only one with no parser behind
+ * it. A markdown body is read by markdown-it (`core/markdown.ts` →
+ * `markdownRefs`), a hook `command` is read by mvdan-sh (`core/bash-effects.ts`
+ * → `commandWords`), and what is left — the body of a hook script, a helper
+ * `.js` / `.py` / `.rb` — is scanned for path-shaped character runs, because a
+ * general-purpose "find every path this program touches" analysis is not a
+ * thing this tool can be.
+ *
+ * Since that scan IS a character run, the only thing standing between it and a
+ * false accusation is where the run may START and STOP. This module owns both
+ * boundaries and the extension vocabularies, so no caller can build a pattern
+ * without them.
+ *
+ * ## The two boundaries, and the two live defects that came from omitting them
+ *
+ * RIGHT — the extension must END the token. `INTRA_REF_EXTS` used to be a bare
+ * alternation with no trailing assertion, and `js` sits ahead of `json` in it,
+ * so `hooks/hooks.json` matched as `hooks/hooks.js`. Measured 2026-08-17 on
+ * `microsoft/power-platform-skills`: a `//` comment naming `hooks/hooks.json`,
+ * with that exact file sitting beside it on disk, was reported as
+ * "hooks/hooks.js (referenced but MISSING)" — a maintainer told a file they
+ * have is missing, under a name they never wrote.
+ *
+ * LEFT — the surface dir must START the token. `(?:agents|hooks|skills)/` with
+ * nothing before it also matches the tail of `claude-agents/`. Measured the
+ * same day on `fcakyon/claude-codex-settings`: a
+ * `new URL("../../../claude-agents/fable-advisor.md", …)` — a correct,
+ * resolving reference — was reported as a broken `agents/fable-advisor.md`.
+ * That boundary is a predicate ({@link startsAtSeparator}) rather than a regex
+ * lookbehind, because the browser twin (`scan-files.ts`) compiles this into the
+ * demo engine, and because the caller already inspects `m.index` for its
+ * plugin-rooted test.
+ *
+ * ## Comments are prose in every language, not only in shell
+ *
+ * `stripShellComments` had the right idea and too narrow a domain: a full-line
+ * `#` in a `.sh` file is prose, and so is a full-line `//` or a JSDoc `*` in a
+ * `.js` file. Both remaining corpus false accusations in this detector came out
+ * of JSDoc — `* It is deliberately not registered in hooks/hooks.json:` and
+ * "`git log --grep=.env -- hooks/x.mjs` is refused …". Neither is a file
+ * operation; both were reported as broken references.
+ *
+ * FULL-LINE ONLY, the same rule the shell version already held. A trailing
+ * comment on a real code line is left alone, so a genuine reference sharing a
+ * line with code is never dropped. The cost is stated rather than hidden: a
+ * path mentioned ONLY in a trailing comment still counts as a reference.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SCRIPT_REF_EXTENSIONS = exports.INTRA_REF_EXTENSIONS = void 0;
+exports.startsAtSeparator = startsAtSeparator;
+exports.intraRefPattern = intraRefPattern;
+exports.scriptWordPattern = scriptWordPattern;
+exports.scriptRefPattern = scriptRefPattern;
+exports.stripFullLineComments = stripFullLineComments;
+// ---------------------------------------------------------------------------
+// Boundaries — the two assertions no pattern here may be built without
+// ---------------------------------------------------------------------------
+/**
+ * The right boundary: the matched extension must be the END of the token.
+ * A negative lookahead over the characters an extension is drawn from, so `js`
+ * cannot claim the head of `json` / `jsonl` and `py` cannot claim `pyc`. `.` is
+ * deliberately NOT in the class, which preserves the prior `\b` behaviour on
+ * `bundle.js.map`.
+ */
+const ENDS_TOKEN = "(?![A-Za-z0-9_])";
+/**
+ * Characters a path SEGMENT is made of. A match preceded by one of these landed
+ * in the middle of a longer name (`claude-agents/`), which is not a reference
+ * to the surface dir it happens to end with.
+ */
+const SEGMENT_CHAR = /[A-Za-z0-9._-]/;
+/**
+ * Whether a match at `idx` begins at a path boundary rather than inside a
+ * longer name. Position 0 counts as a boundary.
+ *
+ * `/` is a boundary on purpose: `${CLAUDE_PLUGIN_ROOT}/hooks/x.sh` is the
+ * standard spelling, and the caller's plugin-rooted test decides whether the
+ * segment before that slash roots the path inside the plugin or outside it.
+ */
+function startsAtSeparator(content, idx) {
+    if (idx <= 0)
+        return true;
+    return !SEGMENT_CHAR.test(content[idx - 1] ?? "");
+}
+// ---------------------------------------------------------------------------
+// Extension vocabularies
+// ---------------------------------------------------------------------------
+/**
+ * Extensions an intra-plugin reference may carry — the file kinds a plugin's
+ * own hook / helper source legitimately points at.
+ */
+exports.INTRA_REF_EXTENSIONS = [
+    "md",
+    "sh",
+    "cmd",
+    "mjs",
+    "cjs",
+    "js",
+    "ts",
+    "py",
+    "rb",
+    "txt",
+    "json",
+];
+/**
+ * Extensions a RUNNABLE script carries. Shared by the hook scanner and the
+ * coverage twins, which each declared their own copy before.
+ */
+exports.SCRIPT_REF_EXTENSIONS = [
+    "sh",
+    "mjs",
+    "cjs",
+    "js",
+    "ts",
+    "py",
+    "rb",
+];
+/**
+ * A plugin-relative path under one of `dirs`, carrying a known extension — the
+ * pattern for scanning a plugin's own SOURCE TEXT.
+ *
+ * The left boundary is not baked into the returned regex (see
+ * {@link startsAtSeparator}): a caller scanning raw text must apply that
+ * predicate at `m.index`, which both the disk detector and its browser twin do
+ * inside their plugin-rooted test.
+ */
+function intraRefPattern(dirs) {
+    const exts = exports.INTRA_REF_EXTENSIONS.join("|");
+    return new RegExp(`(?:${dirs.join("|")})/[A-Za-z0-9._/-]+\\.(?:${exts})${ENDS_TOKEN}`, "g");
+}
+/**
+ * A script path occupying a WHOLE shell WORD.
+ *
+ * ⚠️ ANCHORING IS NOT WHAT FIXES THE `node -e` DEFECT, and saying so would be
+ * wrong twice over — the payload
+ * `import(require(node:url).pathToFileURL(require(node:path).join(root,hooks,always-on.mjs`
+ * contains no whitespace and ends in `.mjs`, so it satisfies this pattern
+ * perfectly (asserted in source-refs.test.ts, so the claim cannot drift back).
+ * That defect is fixed one level up, by `commandWords` refusing to hand the
+ * argument of `-e` to anyone.
+ *
+ * What anchoring buys is narrower and worth stating exactly: the reported name
+ * is always a word a shell could hand to `execve`, never a fragment cut out of
+ * a longer one. `echo "see hooks/x.sh"` is one word containing a path; before,
+ * `hooks/x.sh` was lifted out of it and checked as though the hook ran it.
+ *
+ * The cost, stated rather than discovered later: a path bundled into a flag
+ * (`--require=hooks/x.js`) is no longer seen. Measured across the 32-repo
+ * dogfood corpus, that costs zero findings.
+ */
+function scriptWordPattern() {
+    const exts = exports.SCRIPT_REF_EXTENSIONS.join("|");
+    return new RegExp(`^[^\\s*?]+\\.(?:${exts})$`);
+}
+/**
+ * A script path appearing anywhere inside a string — for the one caller with no
+ * shell parse to hand (the coverage twins scan a serialized settings blob).
+ * Carries the right boundary; it cannot carry the left one, and its callers
+ * gate every hit on the file existing, so a stray match is dropped rather than
+ * reported.
+ */
+function scriptRefPattern() {
+    const exts = exports.SCRIPT_REF_EXTENSIONS.join("|");
+    return new RegExp("[\\w./$" + "{}@-]+\\." + `(?:${exts})${ENDS_TOKEN}`, "g");
+}
+// ---------------------------------------------------------------------------
+// Comments (prose inside an executable source)
+// ---------------------------------------------------------------------------
+/** Source kinds whose full-line comments this module knows how to drop. */
+const HASH_COMMENT = /\.(?:sh|bash|zsh|cmd|py|rb|pl)$/i;
+const SLASH_COMMENT = /\.(?:m|c)?[jt]s$/i;
+/**
+ * A line that is ENTIRELY a comment in a `//`-style language: a `//` line, a
+ * block-comment delimiter, or a JSDoc continuation `*` followed by whitespace
+ * or end of line.
+ *
+ * A bare `*name` does NOT count — `*run() {}` is a generator method, and
+ * dropping that line would silently delete a real reference from code.
+ */
+const SLASH_COMMENT_LINE = /^(?:\/\/|\/\*|\*\/|\*(?:\s|$))/;
+/**
+ * Drop FULL-LINE comments (including a shebang, which also starts with `#`)
+ * from an executable source before it is scanned for path references.
+ *
+ * A file of unknown kind is returned unchanged: guessing a comment syntax is
+ * how a real reference gets deleted, and this detector's contract is that it
+ * under-reports rather than accuses.
+ */
+function stripFullLineComments(path, content) {
+    const isHash = HASH_COMMENT.test(path);
+    const isSlash = SLASH_COMMENT.test(path);
+    if (!isHash && !isSlash)
+        return content;
+    return content
+        .split("\n")
+        .filter((line) => {
+        const t = line.trimStart();
+        return isHash ? !t.startsWith("#") : !SLASH_COMMENT_LINE.test(t);
+    })
+        .join("\n");
+}
+//# sourceMappingURL=source-refs.js.map

package/dist/core/tool-contract.d.ts

@@ -2,8 +2,8 @@
  * Tool-contract verification — the cross-referencing moat ("valid is not true")
  * applied to a subagent's declared `tools:` rail. A subagent may only run
  * built-in tools from the harness dialect's catalog or an MCP tool; anything else
- * is a typo or a nonexistent / never-available tool — a guaranteed-dead reference
- * a compiler catches, not a runtime surprise.
+ * is a typo or a nonexistent tool — a guaranteed-dead reference a compiler
+ * catches, not a runtime surprise.
  *
  * ONE pure detector (`one-detector-no-drift`), reused by THREE callers so they
  * can't disagree: `compileAgent` (spec authoring), `scan` (read-only audit of a
@@ -11,51 +11,89 @@
  * commit gate). The dialect is injected (core ⊄ adapter) — the composition root
  * passes `claudeCodeDialect` / `codexDialect`.
  *
- * Scope note: this validates a SUBAGENT contract against the SUBAGENT catalog
- * (`builtinAgentTools` / `neverAvailableTools`). A skill's `allowed-tools` is a
- * DIFFERENT namespace (skills legitimately use `AskUserQuestion`, `TaskCreate`,
- * … which are never-available to a subagent), so it is deliberately NOT validated
- * here — doing so against the agent catalog would be a false-positive factory.
+ * WHAT CHANGED, 2026-08-17. This used to split names two ways — in
+ * `builtinAgentTools` (fine) or in `neverAvailableTools` (dead) — and decide
+ * what to say about a name in neither by its edit distance to the first list.
+ * Two failures came out of that shape:
+ *
+ *  - `Agent` was in the DENYLIST while its own deprecated alias `Task` was in the
+ *    catalog, so vigiles rejected the platform's current name, accepted the old
+ *    one, and told orchestrator subagents to remove the tool they exist to use.
+ *    Nothing could notice, because the two lists were never compared.
+ *  - Real tools vigiles didn't know (`EndConversation`, `TaskOutput`,
+ *    `Workflow`) and outright invented ones passed in silence, while typos of
+ *    known names were caught — so the more wrong a name was, the likelier it
+ *    went unreported.
+ *
+ * Names are now CLASSIFIED against the dialect's vocabulary
+ * (`core/vocabulary.ts`), which has a third status for what the two-way split
+ * could not express: the vendor removes `Agent` only at the spawn depth limit,
+ * `ExitPlanMode` only outside plan mode, and most built-ins only from a
+ * background subagent. Those are `conditional` — reported as a note with the
+ * condition quoted, never as "remove it". Severity travels on the issue, so
+ * `scan`, `lint` and `compileAgent` cannot drift apart on which issues count.
+ *
+ * Scope note: this validates a SUBAGENT contract against the SUBAGENT catalog. A
+ * skill's `allowed-tools` is a DIFFERENT namespace (skills legitimately use
+ * `AskUserQuestion`, `TaskCreate`, … which a subagent doesn't get), so it is
+ * deliberately NOT validated here — doing so against the agent catalog would be
+ * a false-positive factory.
  */
 import type { HarnessDialect } from "./dialect.js";
-export type ToolIssueKind = "never-available" | "unknown";
+import { type HarnessVocabulary, type IssueSeverity, type TermVerdict } from "./vocabulary.js";
+export type ToolIssueKind = 
+/** The platform removes it unconditionally — a real, scored defect. */
+"never-available"
+/** Not in vigiles's catalog — advisory; may be newer than our capture. */
+ | "unknown"
+/** Real, but removed under a condition vigiles can't see — advisory. */
+ | "conditional";
 export interface ToolIssue {
     readonly tool: string;
     readonly kind: ToolIssueKind;
-    /** Closest known built-in tool (did-you-mean), or null. */
+    /** Which vocabulary verdict produced this — the input to every policy. */
+    readonly verdict: TermVerdict["kind"];
+    /** Closest known built-in tool (did-you-mean), or null. Message only. */
     readonly suggestion: string | null;
+    /**
+     * The vendor condition — present ONLY for a `conditional` verdict. Carried so
+     * a report can group the tools sharing one condition rather than repeat the
+     * same sentence per tool.
+     */
+    readonly condition?: string;
+    /** `"scored"` counts toward the grade; `"advisory"` never does. */
+    readonly severity: IssueSeverity;
     /** A ready-to-show, actionable message. */
     readonly message: string;
 }
 /**
- * Closest known built-in tool by edit distance (≤ 2), for a "did you mean" hint.
- * The ≤ 2 bound is deliberately tight: a suggestion is a CONFIDENCE signal (this
- * `unknown` is really a typo of a real tool), and a loose bound mis-suggests —
- * `TaskGet → Task?` (distance 3) is a real tool set, not a typo of `Task`.
+ * The tool vocabulary this dialect verifies against — its declared one, else a
+ * synthesised one from the flat lists so a legacy adapter keeps working.
  */
-export declare function closestTool(tool: string, dialect: HarnessDialect): string | null;
+export declare function subagentToolVocabulary(dialect: HarnessDialect): HarnessVocabulary;
 /**
- * The HIGH-CONFIDENCE subset of a contract's issues — the ones safe to flag when
- * AUDITING a third-party plugin (scan / lint), where the catalog can't know
- * every tool (plugin-/MCP-provided, newer platform tools). Only two are confident:
- * a `never-available` tool (a curated denylist) and an `unknown` with a close
- * typo suggestion (`Edt → Edit`). A bare `unknown` with no near match is NOT
- * flagged here — it is more likely a tool vigiles doesn't know than a defect
- * (sweeping real plugins surfaced a 280★ plugin using `TaskCreate/TaskGet/…`
- * consistently; flagging those would be crying wolf). `compileAgent` stays strict
- * — when you author your OWN spec, every unrecognized tool is worth an error.
+ * Closest known built-in tool by edit distance (≤ 2), for a "did you mean" hint.
+ * A MESSAGE DECORATION, never a gate: whether to report is already settled by
+ * the verdict before this is called. The ≤ 2 bound stays tight because a loose
+ * bound mis-suggests — `TaskGet → Task?` is a different real tool, not a typo.
  */
-export declare function confidentToolIssues(issues: readonly ToolIssue[]): ToolIssue[];
+export declare function closestTool(tool: string, dialect: HarnessDialect): string | null;
 /**
  * Verify a subagent's `disallowedTools:` BLOCK-list — the mirror of the allow
  * contract. A typo here is dangerous: you meant to block `Bash` but wrote `Bsh`,
  * so nothing is blocked and the dangerous tool stays available, silently. Returns
- * one {@link ToolIssue} per entry that's a CLOSE TYPO of a real built-in (the
- * high-confidence signal). Deliberately NOT flagged: a real built-in (it IS being
- * blocked — correct), a never-available tool (harmless to block), an MCP tool (a
- * legitimate plugin tool to block), or a bare unknown with no near match (likely
- * a plugin/MCP tool, not a typo — the cry-wolf trap). The block-list inverts the
- * allow check: never-available is fine to list, a typo is the actual defect.
+ * one {@link ToolIssue} per entry that's a CLOSE TYPO of a real tool.
+ * Deliberately NOT flagged: any name the vocabulary knows (blocking it is the
+ * point — including a withheld one, which is merely redundant), an MCP tool (a
+ * legitimate plugin tool to block), or a bare unknown with no near match.
+ *
+ * This is the ONE place a near match still gates a finding, and it is not the
+ * confidence proxy the allow-side check was rightly stripped of. On a block-list
+ * the risk inverts: an entry naming nothing is harmless UNLESS you meant a real
+ * tool and mistyped it, and "meant a real tool" is precisely what a one-character
+ * distance evidences. `disallowedTools: [Zzzz]` blocks nothing and nobody
+ * intended otherwise; `disallowedTools: [Bsh]` leaves `Bash` wide open. So the
+ * distance here is the actual semantic signal, not a stand-in for one.
  */
 export declare function disallowedToolIssues(tools: readonly string[], dialect: HarnessDialect): ToolIssue[];
 /**
@@ -65,4 +103,5 @@ export declare function disallowedToolIssues(tools: readonly string[], dialect:
  * is stripped to its base tool before checking.
  */
 export declare function verifyToolContract(tools: readonly string[], dialect: HarnessDialect): ToolIssue[];
+export { scoredIssues, advisoryIssues, authoringIssues } from "./vocabulary.js";
 //# sourceMappingURL=tool-contract.d.ts.map