vigiles 10.0.0 → 11.0.0

package/dist/core/rule-meta.js

@@ -0,0 +1,266 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RULE_META = void 0;
+exports.allRuleMeta = allRuleMeta;
+exports.ruleMeta = ruleMeta;
+/**
+ * The registry. `Record<RuleName, RuleMeta>` makes completeness a COMPILE-TIME
+ * guarantee: add a `RulesConfig` key without a meta here and `tsc` fails. The
+ * runtime test additionally binds this to `docs/rules/*.md` (the fs side a type
+ * can't see).
+ */
+exports.RULE_META = {
+    // --- Spec & integrity (adoption / artifact-matches-source) ---------------
+    "require-instructions-spec": {
+        id: "require-instructions-spec",
+        bucket: "external-decidable",
+        surface: ["instruction"],
+        defaultSeverity: "warn",
+        summary: "A .spec.ts exists behind each CLAUDE.md / AGENTS.md.",
+        detector: "spec-presence (cli)",
+    },
+    "require-skill-spec": {
+        id: "require-skill-spec",
+        bucket: "external-decidable",
+        surface: ["skill"],
+        defaultSeverity: "off",
+        summary: "A .spec.ts exists behind each SKILL.md (opt-in).",
+        detector: "spec-presence (cli)",
+    },
+    integrity: {
+        id: "integrity",
+        bucket: "external-decidable",
+        surface: ["instruction"],
+        defaultSeverity: "warn",
+        summary: "A compiled instruction file still matches its spec's SHA-256.",
+        detector: "checkIntegrity",
+        upstreamPrevention: "compile stamps the hash; this catches later hand-edits",
+    },
+    coverage: {
+        id: "coverage",
+        bucket: "external-decidable",
+        surface: ["instruction"],
+        defaultSeverity: "off",
+        summary: "The spec covers ≥ threshold of linter rules / npm scripts.",
+        detector: "analyzeCoverage",
+    },
+    // --- Test coverage --------------------------------------------------------
+    "untested-skill": {
+        id: "untested-skill",
+        bucket: "external-decidable",
+        surface: ["skill"],
+        defaultSeverity: "warn",
+        summary: "A SKILL.md ships with a test or eval.",
+        detector: "findUntestedSurfaces",
+    },
+    "untested-subagent": {
+        id: "untested-subagent",
+        bucket: "external-decidable",
+        surface: ["subagent"],
+        defaultSeverity: "warn",
+        summary: "A subagent (agents/*.md) ships with a test or eval.",
+        detector: "findUntestedSurfaces",
+    },
+    "untested-hook": {
+        id: "untested-hook",
+        bucket: "external-decidable",
+        surface: ["hook"],
+        defaultSeverity: "warn",
+        summary: "A file-backed hook script ships with a test or eval.",
+        detector: "findUntestedSurfaces",
+    },
+    // --- Reference marking ----------------------------------------------------
+    "unmarked-refs": {
+        id: "unmarked-refs",
+        bucket: "heuristic-behavioral",
+        surface: ["instruction"],
+        defaultSeverity: "warn",
+        summary: "Code-shaped refs in an instruction file are marked (verifiable).",
+        detector: "collectRefIssues",
+    },
+    // --- Subagent contracts ---------------------------------------------------
+    "subagent-tool-contract": {
+        id: "subagent-tool-contract",
+        bucket: "structural-closed",
+        surface: ["subagent"],
+        defaultSeverity: "warn",
+        summary: "A subagent's tools: are all real (no never-available / typo).",
+        detector: "confidentToolIssues",
+        upstreamPrevention: "typed agent() vocabulary + compileAgent — an unknown tool is a tsc/compile error",
+    },
+    "disallowed-tools-contract": {
+        id: "disallowed-tools-contract",
+        bucket: "structural-closed",
+        surface: ["subagent"],
+        defaultSeverity: "warn",
+        summary: "A disallowedTools: entry isn't a typo that blocks nothing.",
+        detector: "disallowedToolIssues",
+        upstreamPrevention: "typed agent() vocabulary (a typo is a tsc error)",
+    },
+    "subagent-frontmatter": {
+        id: "subagent-frontmatter",
+        bucket: "structural-closed",
+        surface: ["subagent"],
+        defaultSeverity: "warn",
+        summary: "A subagent has required name/description + valid model/color.",
+        detector: "frontmatterIssuesFor",
+        upstreamPrevention: "compileAgent emits the required frontmatter",
+    },
+    // --- Hooks & MCP ----------------------------------------------------------
+    "hook-events": {
+        id: "hook-events",
+        bucket: "structural-closed",
+        surface: ["hook"],
+        defaultSeverity: "warn",
+        summary: "A hook's event name is one the harness defines (it can fire).",
+        detector: "confidentHookEventIssues",
+        upstreamPrevention: "compiled hook on: is dialect-validated at compile",
+    },
+    "hook-script-exists": {
+        id: "hook-script-exists",
+        bucket: "external-decidable",
+        surface: ["hook"],
+        defaultSeverity: "warn",
+        summary: "A hook command's script file exists on disk (it can run).",
+        detector: "scanHooks (status 'missing')",
+        upstreamPrevention: "a compiled hook is self-contained (no external script)",
+    },
+    "hook-block-ineffective": {
+        id: "hook-block-ineffective",
+        bucket: "structural-closed",
+        surface: ["hook"],
+        defaultSeverity: "warn",
+        summary: "A hook that looks like it blocks actually can (event + field).",
+        detector: "hookBlockIssues",
+        upstreamPrevention: "compiled hooks — deny compiles to exit 2; the field/exit code is never hand-written",
+    },
+    "hook-matcher": {
+        id: "hook-matcher",
+        bucket: "structural-closed",
+        surface: ["hook"],
+        defaultSeverity: "warn",
+        summary: "A hook matcher fires (no tool-name typo / malformed MCP form).",
+        detector: "hookMatcherIssues",
+        upstreamPrevention: "compiled hook tool()/tools() matcher is typed",
+    },
+    "prefer-compiled-hooks": {
+        id: "prefer-compiled-hooks",
+        bucket: "heuristic-behavioral",
+        surface: ["hook"],
+        defaultSeverity: "off",
+        summary: "Recommends compiled hooks over hand-written shell (one nudge).",
+        detector: "scanHooks (manualHookCount)",
+    },
+    "mcp-config": {
+        id: "mcp-config",
+        bucket: "structural-closed",
+        surface: ["mcp"],
+        defaultSeverity: "warn",
+        summary: "A declared MCP server can start (has a command or url).",
+        detector: "verifyMcpServers",
+    },
+    "mcp-tool-resolves": {
+        id: "mcp-tool-resolves",
+        bucket: "external-decidable",
+        surface: ["subagent", "mcp"],
+        defaultSeverity: "warn",
+        summary: "A subagent's mcp__server__tool names a declared server.",
+        detector: "verifyMcpToolServers",
+    },
+    "mcp-hook-target-resolves": {
+        id: "mcp-hook-target-resolves",
+        bucket: "external-decidable",
+        surface: ["hook", "mcp"],
+        defaultSeverity: "warn",
+        summary: "A type:mcp_tool hook action is complete + names a declared server.",
+        detector: "verifyMcpHookTargets",
+    },
+    // --- Skill triggers -------------------------------------------------------
+    "skill-frontmatter": {
+        id: "skill-frontmatter",
+        bucket: "structural-closed",
+        surface: ["skill"],
+        defaultSeverity: "warn",
+        summary: "A SKILL.md declares an explicit name + description (reliable trigger).",
+        detector: "skillMetaIssuesFor",
+        upstreamPrevention: "skill() compiler emits name + description",
+    },
+    "skill-missing-fence": {
+        id: "skill-missing-fence",
+        bucket: "structural-closed",
+        surface: ["skill"],
+        defaultSeverity: "warn",
+        summary: "A SKILL.md opens with a --- fence (else it loads as inert body).",
+        detector: "skillMissingFence",
+        upstreamPrevention: "skill() compiler always emits the fence",
+    },
+    "description-overlap": {
+        id: "description-overlap",
+        bucket: "heuristic-behavioral",
+        surface: ["skill"],
+        defaultSeverity: "warn",
+        summary: "Two model-invocable skills aren't near-identical (wrong one fires).",
+        detector: "findDescriptionOverlaps",
+    },
+    "frontmatter-valid": {
+        id: "frontmatter-valid",
+        bucket: "heuristic-behavioral",
+        surface: ["skill", "subagent"],
+        defaultSeverity: "warn",
+        summary: "A --- block parses as YAML (js-yaml is stricter than some loaders).",
+        detector: "malformedFrontmatterFor",
+        upstreamPrevention: "the spec compiler emits valid frontmatter",
+    },
+    "skill-resource-resolves": {
+        id: "skill-resource-resolves",
+        bucket: "external-decidable",
+        surface: ["skill"],
+        defaultSeverity: "warn",
+        summary: "A SKILL.md's bundled-file reference exists under the skill dir.",
+        detector: "skillResourceIssues",
+    },
+    // --- Plugin layout & safety ----------------------------------------------
+    "plugin-dir-layout": {
+        id: "plugin-dir-layout",
+        bucket: "external-decidable",
+        surface: ["plugin"],
+        defaultSeverity: "warn",
+        summary: "No functional surface dir is nested inside the manifest dir.",
+        detector: "pluginDirLayoutIssues",
+        upstreamPrevention: "init scaffolds surfaces at the plugin root",
+    },
+    "lethal-trifecta": {
+        id: "lethal-trifecta",
+        bucket: "structural-closed",
+        surface: ["skill", "subagent"],
+        defaultSeverity: "warn",
+        summary: "No unit's tools hold all three lethal-trifecta legs at once.",
+        detector: "lethalTrifectaIssues",
+    },
+    "delegation-trifecta": {
+        id: "delegation-trifecta",
+        bucket: "structural-closed",
+        surface: ["subagent"],
+        defaultSeverity: "warn",
+        summary: "No subagent's (own ∪ delegated) capability forms a trifecta.",
+        detector: "delegationTrifectaIssues",
+    },
+    // --- Docs hygiene ---------------------------------------------------------
+    "orphan-docs": {
+        id: "orphan-docs",
+        bucket: "external-decidable",
+        surface: ["docs"],
+        defaultSeverity: "warn",
+        summary: "Every docs/ + research/ .md is referenced by another .md.",
+        detector: "findOrphanDocs",
+    },
+};
+/** All declared rule metas, as a list. */
+function allRuleMeta() {
+    return Object.values(exports.RULE_META);
+}
+/** Look up one rule's meta (undefined for an unknown id). */
+function ruleMeta(id) {
+    return exports.RULE_META[id];
+}
+//# sourceMappingURL=rule-meta.js.map

package/dist/core/skill-missing-fence.d.ts

@@ -0,0 +1,47 @@
+/**
+ * vigiles — SKILL.md missing-fence detector (the cross-reference moat applied
+ * to SKILL.md frontmatter structure).
+ *
+ * A SKILL.md that begins with frontmatter-looking keys (`name:`, `description:`,
+ * `allowed-tools:`, etc.) but is MISSING the opening `---` fence is a very
+ * common real-world pain: the harness loads the whole file as plain body text —
+ * no name, no description, no tool list — so the skill is INVISIBLE and never
+ * fires. The model-selector has nothing to match against and the agent can never
+ * find the skill at all.
+ *
+ * HIGH-PRECISION / FP-SAFE, by the same don't-cry-wolf discipline as the rest of
+ * vigiles (see `danglingRefs`, `confidentToolIssues`): we flag ONLY when the
+ * first non-blank, non-comment line matches a KNOWN frontmatter key at column 0
+ * from an explicit whitelist (`name`, `description`, `allowed-tools`, `tools`,
+ * `model`, `color`, `disable-model-invocation`, `argument-hint`, `version`,
+ * `license`, `metadata`). A random prose line like `Note: something` is never
+ * flagged — the whitelist is what keeps the check FP-safe. Prefer MISSING a
+ * real finding over emitting a false positive.
+ *
+ * Pure: no IO. Input is the raw SKILL.md content string.
+ */
+/**
+ * A finding returned when a SKILL.md is missing its opening `---` fence but
+ * begins with what looks like a frontmatter key.
+ */
+export interface SkillFenceFinding {
+    /** The frontmatter-looking key that appears unfenced (e.g. `"name"`). */
+    readonly key: string;
+    /** 1-based line number of the first unfenced key in the content string. */
+    readonly line: number;
+    /** Human-readable explanation and fix. */
+    readonly message: string;
+}
+/**
+ * Detect a SKILL.md body that begins with a known frontmatter key at column 0
+ * but is missing the required opening `---` fence.
+ *
+ * Returns a {@link SkillFenceFinding} describing the unfenced key, or `null`
+ * when no problem is detected (the file is correctly fenced, starts with prose,
+ * or is empty).
+ *
+ * Pure — no IO. The shared detector behind both `vigiles lint`
+ * (`skill-missing-fence` rule) and `vigiles audit` — one detector, no drift.
+ */
+export declare function skillMissingFence(skillBody: string): SkillFenceFinding | null;
+//# sourceMappingURL=skill-missing-fence.d.ts.map

package/dist/core/skill-missing-fence.js

@@ -0,0 +1,119 @@
+"use strict";
+/**
+ * vigiles — SKILL.md missing-fence detector (the cross-reference moat applied
+ * to SKILL.md frontmatter structure).
+ *
+ * A SKILL.md that begins with frontmatter-looking keys (`name:`, `description:`,
+ * `allowed-tools:`, etc.) but is MISSING the opening `---` fence is a very
+ * common real-world pain: the harness loads the whole file as plain body text —
+ * no name, no description, no tool list — so the skill is INVISIBLE and never
+ * fires. The model-selector has nothing to match against and the agent can never
+ * find the skill at all.
+ *
+ * HIGH-PRECISION / FP-SAFE, by the same don't-cry-wolf discipline as the rest of
+ * vigiles (see `danglingRefs`, `confidentToolIssues`): we flag ONLY when the
+ * first non-blank, non-comment line matches a KNOWN frontmatter key at column 0
+ * from an explicit whitelist (`name`, `description`, `allowed-tools`, `tools`,
+ * `model`, `color`, `disable-model-invocation`, `argument-hint`, `version`,
+ * `license`, `metadata`). A random prose line like `Note: something` is never
+ * flagged — the whitelist is what keeps the check FP-safe. Prefer MISSING a
+ * real finding over emitting a false positive.
+ *
+ * Pure: no IO. Input is the raw SKILL.md content string.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.skillMissingFence = skillMissingFence;
+// ---------------------------------------------------------------------------
+// Constants (FP-safety whitelist)
+// ---------------------------------------------------------------------------
+/**
+ * The known SKILL.md / agent-harness frontmatter keys. A line that matches one
+ * of these at column 0 is flagged when there is no opening `---` fence. Any
+ * key NOT in this list is treated as prose and silently skipped.
+ */
+const KNOWN_KEYS = [
+    "name",
+    "description",
+    "allowed-tools",
+    "tools",
+    "model",
+    "color",
+    "disable-model-invocation",
+    "argument-hint",
+    "version",
+    "license",
+    "metadata",
+];
+/**
+ * Pre-built regex: matches `<known-key>:` at column 0, optionally followed by
+ * whitespace or end-of-line. Capturing group 1 holds the matched key name.
+ */
+const KNOWN_KEY_RE = new RegExp(`^(${KNOWN_KEYS.join("|")})\\s*:`);
+/**
+ * Lines that are unambiguously prose or markdown structure — NOT frontmatter.
+ * When the first meaningful line starts with any of these, return null
+ * immediately without even testing the key whitelist.
+ */
+const PROSE_START_RE = /^(?:#|>|-|\*|`|<|\d+\.|[A-Za-z]{4,}(?:\s|$))/;
+/**
+ * A vigiles integrity / meta comment that may legitimately precede frontmatter.
+ * We skip it so `name:` on line 2 (after the comment on line 1) is still found.
+ */
+const VIGILES_COMMENT_RE = /^<!--\s*vigiles:/;
+// ---------------------------------------------------------------------------
+// Detector
+// ---------------------------------------------------------------------------
+/**
+ * Detect a SKILL.md body that begins with a known frontmatter key at column 0
+ * but is missing the required opening `---` fence.
+ *
+ * Returns a {@link SkillFenceFinding} describing the unfenced key, or `null`
+ * when no problem is detected (the file is correctly fenced, starts with prose,
+ * or is empty).
+ *
+ * Pure — no IO. The shared detector behind both `vigiles lint`
+ * (`skill-missing-fence` rule) and `vigiles audit` — one detector, no drift.
+ */
+function skillMissingFence(skillBody) {
+    // Strip a leading UTF-8 BOM (U+FEFF) if present.
+    const content = skillBody.startsWith("") ? skillBody.slice(1) : skillBody;
+    const lines = content.split("\n");
+    let firstMeaningfulLine = null;
+    let firstMeaningfulLineNo = 0; // 1-based
+    for (let i = 0; i < lines.length; i++) {
+        const raw = lines[i];
+        const trimmed = raw.trimEnd();
+        // Skip blank lines.
+        if (trimmed.trim() === "")
+            continue;
+        // Skip a leading vigiles integrity/meta comment (`<!-- vigiles:... -->`).
+        if (VIGILES_COMMENT_RE.test(trimmed.trim()))
+            continue;
+        firstMeaningfulLine = trimmed;
+        firstMeaningfulLineNo = i + 1; // convert to 1-based
+        break;
+    }
+    // Empty or all-blank file — nothing to flag.
+    if (firstMeaningfulLine === null)
+        return null;
+    // A proper opening fence — correctly structured, nothing to flag.
+    if (firstMeaningfulLine.startsWith("---"))
+        return null;
+    // Unambiguous prose / markdown constructs — not a frontmatter key.
+    if (PROSE_START_RE.test(firstMeaningfulLine))
+        return null;
+    // Check against the known-key whitelist (the FP-safety gate).
+    const match = KNOWN_KEY_RE.exec(firstMeaningfulLine);
+    if (!match)
+        return null;
+    const key = match[1];
+    return {
+        key,
+        line: firstMeaningfulLineNo,
+        message: `SKILL.md is missing its opening \`---\` frontmatter fence: ` +
+            `\`${key}:\` on line ${firstMeaningfulLineNo} is loaded as body text, ` +
+            `so the skill has no name, description, or trigger and will never fire. ` +
+            `Wrap the metadata block in \`---\` … \`---\`.`,
+    };
+}
+//# sourceMappingURL=skill-missing-fence.js.map

package/dist/core/skill-resources.d.ts

@@ -0,0 +1,27 @@
+/** How a missing bundled-resource reference was found in the body. */
+export type SkillResourceKind = "link" | "path";
+/** A SKILL.md body reference to a local bundled file that doesn't exist on disk. */
+export interface SkillResourceFinding {
+    /** The reference text exactly as written in the body (e.g. `scripts/run.sh`). */
+    readonly ref: string;
+    /** The path normalized relative to the skill dir, used for resolution. */
+    readonly resolved: string;
+    /** Whether the ref came from a markdown link `[..](..)` or an inline/path mention. */
+    readonly kind: SkillResourceKind;
+    /** 1-based source line of the reference in the body. */
+    readonly line: number;
+}
+export interface SkillResourceOptions {
+    /** Injectable existence check (default: node:fs existsSync). */
+    readonly existsSync?: (p: string) => boolean;
+}
+/**
+ * The bundled-resource references in a SKILL.md body that don't resolve on disk
+ * under `skillDir`. Pure + FP-safe (see the module header). `skillDir` is the
+ * directory the SKILL.md itself lives in (resources are bundled beside it).
+ *
+ * The shared detector behind both `vigiles lint` (the `skill-resource-resolves`
+ * rule) and `vigiles audit` (the read-only report) — one detector, no drift.
+ */
+export declare function skillResourceIssues(skillBody: string, skillDir: string, opts?: SkillResourceOptions): SkillResourceFinding[];
+//# sourceMappingURL=skill-resources.d.ts.map

package/dist/core/skill-resources.js

@@ -0,0 +1,167 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.skillResourceIssues = skillResourceIssues;
+/**
+ * vigiles — SKILL bundled-resource resolution (the cross-reference moat applied
+ * to a SKILL.md body).
+ *
+ * A SKILL.md body is freeform markdown that routinely points the agent at LOCAL
+ * BUNDLED files shipped beside it — `scripts/foo.sh`, `references/api.md`,
+ * `[setup](./scripts/run.py)`, an inline `run \`scripts/setup.sh\``. When a
+ * referenced file doesn't exist on disk under the skill directory, the agent
+ * reads the instruction, gets nothing, and silently continues (a documented top
+ * skill pain — one practitioner found 59 broken refs across 192 files). vigiles
+ * already verifies file/script refs inside typed specs (core/refs.ts,
+ * core/doc-refs.ts) and intra-plugin script refs in the loader
+ * (plugin-loader.ts `danglingRefs`); this extends that to the SKILL.md body.
+ *
+ * HIGH-PRECISION / FP-SAFE, by the same don't-cry-wolf discipline the rest of
+ * vigiles holds (see `danglingRefs`/`isPluginRooted`): we flag ONLY references
+ * that are UNAMBIGUOUSLY a local bundled resource — a markdown link to a
+ * relative path with a file extension, or an explicit `scripts/`/`references/`/
+ * `assets/`-prefixed path (the Agent-Skills standard bundle dirs) with an
+ * extension. Everything else is skipped: URLs, absolute paths, `${VAR}`/`$VAR`
+ * tokens, `../` escapes, bare words with no extension or known prefix. Prefer
+ * MISSING a real ref over emitting a false positive — a noisy resource check
+ * would teach users to ignore it.
+ *
+ * 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.
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+// ---------------------------------------------------------------------------
+// Shapes we match vs deliberately skip (FP-safety)
+// ---------------------------------------------------------------------------
+const FENCE = /^\s*(?:`{3,}|~{3,})/;
+// The Agent-Skills standard bundle subdirectories. A path PREFIXED by one of
+// 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]+$/;
+/**
+ * A reference target is a LOCAL BUNDLED RESOURCE worth resolving iff it is a
+ * relative path with a file extension AND is not one of the skip shapes. This is
+ * the single gate; both the link path and the inline-path path run through it.
+ */
+function localResourceTarget(rawTarget) {
+    // Strip a markdown link title / fragment / query if present, and trim.
+    const target = rawTarget.trim();
+    if (target.length === 0)
+        return null;
+    // SKIP: URLs (http://, https://, mailto:, any scheme://) — external.
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(target) || /^mailto:/i.test(target)) {
+        return null;
+    }
+    // SKIP: a pure anchor / fragment-only link (`#section`).
+    if (target.startsWith("#"))
+        return null;
+    // SKIP: absolute paths (`/etc/x`, Windows `C:\`) — not bundled-relative.
+    if (target.startsWith("/") || /^[A-Za-z]:[\\/]/.test(target))
+        return null;
+    // SKIP: variable tokens (`${CLAUDE_PLUGIN_ROOT}/x`, `$VAR/x`) — uncheckable,
+    // and almost always a plugin-root or runtime path, not a bundled file.
+    if (target.includes("$"))
+        return null;
+    // Drop a URL fragment / query suffix so `references/api.md#auth` resolves to
+    // the file. (Only after the scheme check above, so we never mangle a URL.)
+    const path = target.replace(/[?#].*$/, "");
+    if (path.length === 0)
+        return null;
+    // SKIP: a `../` escape OUT of the skill dir — undecidable / not a bundled
+    // resource (it points at a sibling skill or the repo). A leading `./` is fine.
+    const normalized = path.replace(/^\.\//, "");
+    if (normalized.startsWith("../") || normalized.includes("/../"))
+        return null;
+    // Must look like a file (have an extension), else it's a dir/prose mention.
+    if (!HAS_EXT.test(normalized))
+        return null;
+    return normalized;
+}
+/**
+ * Whether an inline-code path token is high-confidence enough to flag on its
+ * own (no surrounding `[..](..)` link syntax). We require a BUNDLE-DIR PREFIX
+ * (`scripts/`, `references/`, `assets/`) so a generic `` `config.json` `` or a
+ * `` `src/foo.ts` `` API mention in prose is never flagged — only the standard
+ * bundle layout, which is unambiguously a shipped resource.
+ */
+function isInlineBundlePath(token) {
+    const t = token.trim();
+    // A single token only — a span with spaces is a command/prose, not a path.
+    if (/\s/.test(t))
+        return false;
+    const normalized = t.replace(/^\.\//, "");
+    return BUNDLE_PREFIX.test(normalized) && HAS_EXT.test(normalized);
+}
+/** Collect candidate bundled-resource refs from one body line, skipping fences. */
+function candidatesInLine(line, lineNo) {
+    const out = [];
+    // Markdown links: any relative path target that passes the local-resource gate.
+    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.
+    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;
+}
+/**
+ * The bundled-resource references in a SKILL.md body that don't resolve on disk
+ * under `skillDir`. Pure + FP-safe (see the module header). `skillDir` is the
+ * directory the SKILL.md itself lives in (resources are bundled beside it).
+ *
+ * The shared detector behind both `vigiles lint` (the `skill-resource-resolves`
+ * rule) and `vigiles audit` (the read-only report) — one detector, no drift.
+ */
+function skillResourceIssues(skillBody, skillDir, opts = {}) {
+    const exists = opts.existsSync ?? node_fs_1.existsSync;
+    const findings = [];
+    const seen = new Set();
+    const lines = skillBody.split("\n");
+    let inFence = false;
+    for (let i = 0; i < lines.length; i++) {
+        if (FENCE.test(lines[i])) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence)
+            continue;
+        for (const c of candidatesInLine(lines[i], i + 1)) {
+            const full = (0, node_path_1.resolve)(skillDir, c.resolved);
+            if (exists(full))
+                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,
+            });
+        }
+    }
+    return findings;
+}
+//# sourceMappingURL=skill-resources.js.map