vigiles 9.1.0 → 11.0.0

package/dist/core/plugin-dir-layout.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pluginDirLayoutIssues = pluginDirLayoutIssues;
+/**
+ * vigiles — plugin manifest directory layout verification.
+ *
+ * The #1 plugin-author mistake (OSS pain #E1): placing functional surface
+ * directories (skills/, agents/, commands/, hooks/) INSIDE the `.claude-plugin/`
+ * manifest directory instead of at the plugin root. The harness resolves surface
+ * dirs relative to the PLUGIN ROOT (where the agent is launched), not relative to
+ * the manifest directory — so a `skills/` nested inside `.claude-plugin/` is
+ * completely invisible to the harness. Only `plugin.json` belongs inside the
+ * manifest directory; everything else must live at the root.
+ *
+ * Pure + FP-safe: the only IO is an injectable `existsSync` and `isDirectory`
+ * (defaults: node:fs), mirroring the pattern in core/skill-resources.ts and the
+ * loader, so the detector is fully testable with fakes and never touches the
+ * filesystem in tests.
+ *
+ * Harness-agnostic: the surface directory names are INJECTED from the layout
+ * (PluginLayout.skillDir / agentDir / commandDir / hookDir, or equivalent), never
+ * hard-coded here. ONE detector reused by both `vigiles lint` (the
+ * `plugin-dir-layout` rule) and `vigiles audit` (the read-only report) — one
+ * detector, no drift.
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+// ---------------------------------------------------------------------------
+// Detector
+// ---------------------------------------------------------------------------
+/**
+ * Default `isDirectory` implementation — wraps statSync so that a missing or
+ * unreadable path returns `false` instead of throwing.
+ */
+function defaultIsDirectory(p) {
+    try {
+        return (0, node_fs_1.statSync)(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Surface directories found nested INSIDE the manifest directory, where they are
+ * invisible to the harness.
+ *
+ * `manifestDir` is the absolute path to the manifest directory (e.g. the repo's
+ * `.claude-plugin/`). `surfaceDirNames` are the harness's functional surface
+ * directory names, injected from the layout (e.g. `["skills","agents","commands",
+ * "hooks"]`) so the detector stays harness-agnostic — NEVER hard-code them.
+ *
+ * Returns `[]` when the manifest dir doesn't exist or holds no misplaced surface
+ * dirs.
+ */
+function pluginDirLayoutIssues(manifestDir, surfaceDirNames, opts) {
+    const exists = opts?.existsSync ?? node_fs_1.existsSync;
+    const isDir = opts?.isDirectory ?? defaultIsDirectory;
+    const manifestBase = (0, node_path_1.basename)(manifestDir);
+    const findings = [];
+    for (const name of surfaceDirNames) {
+        const candidate = (0, node_path_1.join)(manifestDir, name);
+        if (exists(candidate) && isDir(candidate)) {
+            findings.push({
+                dir: name,
+                message: `\`${name}/\` lives inside the \`${manifestBase}/\` manifest directory ` +
+                    `where the harness can't see it — only \`plugin.json\` belongs there; ` +
+                    `move \`${name}/\` to the plugin root.`,
+            });
+        }
+    }
+    return findings;
+}
+//# sourceMappingURL=plugin-dir-layout.js.map

package/dist/core/rule-meta.d.ts

@@ -0,0 +1,82 @@
+/**
+ * vigiles — the RULE METADATA registry (the ESLint-`meta` pattern, adapted).
+ *
+ * Every deterministic check vigiles ships is DECLARED here with the one fact that
+ * dissolves the "why is this a warning / can't this be a type?" confusion: its
+ * DECIDABILITY BUCKET, which sets the strongest enforcement the defect can ever
+ * reach. See `research/enforcement-model.md` for the full model and
+ * `lint-rule-calibration` (root CLAUDE.md) for the governance rule.
+ *
+ * WHY A CENTRAL REGISTRY, NOT CO-LOCATED `export const meta`. ESLint co-locates
+ * meta with each rule because there 1 rule = 1 module. vigiles deliberately
+ * SHARES detectors (one-detector-no-drift: a single pure function feeds both
+ * `lint` and `audit`, and `scan.ts` computes many rules at once), so co-locating
+ * would scatter metas across files that each own several rules — the very
+ * fragmentation we're removing. ONE registry keyed by rule name is the honest
+ * single source (mirrors `cli-commands.ts` for verbs); the `detector` field names
+ * the pure function so traceability survives.
+ *
+ * The bucket is the CEILING; `defaultSeverity` is where the rule sits TODAY. A
+ * gap between them is meaningful: a bucket-A/B rule at `warn` is a CANDIDATE for
+ * promotion to `error` (deterministic, just rolling out), whereas a bucket-C rule
+ * at `warn` is permanent (forcing it to `error` would cry wolf).
+ */
+import type { RulesConfig } from "./types.js";
+/**
+ * The decidability class of a defect — the single fact that sets its ceiling.
+ *
+ * - `structural-closed` — decidable from the artifact's own content over a CLOSED
+ *   vocabulary; a TYPE could make it impossible for authors who route through the
+ *   typed constructor. Ceiling: unrepresentable / won't-typecheck.
+ * - `external-decidable` — decidable, but needs the EXTERNAL world (the
+ *   filesystem, a linter catalog, another file/server). No type can read those,
+ *   so the ceiling is a hard ERROR at compile-cross-ref or lint — never a type.
+ * - `heuristic-behavioral` — undecidable or a fuzzy proxy ("are these too
+ *   similar?", "does this fire?"). Ceiling: a WARNING or a model-MEASUREMENT. By
+ *   the math, not by laziness; an `error` here would cry wolf.
+ */
+export type RuleBucket = "structural-closed" | "external-decidable" | "heuristic-behavioral";
+/** The artifact surface a rule reads (coarse; a rule may span several). */
+export type RuleSurface = "instruction" | "skill" | "subagent" | "hook" | "mcp" | "plugin" | "docs";
+/** Where a rule sits by default — `"off"` is the normalized form of `false`. */
+export type RuleDefaultSeverity = "error" | "warn" | "off";
+/** Every named rule: the `RulesConfig` keys plus the built-in `orphan-docs`. */
+export type RuleName = keyof RulesConfig | "orphan-docs";
+/**
+ * The declared shape of one rule — co-located metadata in the ESLint `meta`
+ * sense, gathered into one registry because vigiles shares detectors.
+ */
+export interface RuleMeta {
+    /** Canonical rule id (a `RulesConfig` key or `orphan-docs`). */
+    readonly id: RuleName;
+    /** The decidability class → the rule's strongest possible ceiling. */
+    readonly bucket: RuleBucket;
+    /** The artifact surface(s) the rule reads (non-empty). */
+    readonly surface: readonly RuleSurface[];
+    /** Where the rule sits by default today (≤ the bucket's ceiling). */
+    readonly defaultSeverity: RuleDefaultSeverity;
+    /** One-line "what it checks" (tracks the docs matrix row). */
+    readonly summary: string;
+    /** The shared pure detector function (one-detector-no-drift traceability). */
+    readonly detector: string;
+    /**
+     * The upstream construct that makes this SAME defect impossible for authors who
+     * route through it — a TYPE (structural-closed) or a COMPILE cross-ref. Absent
+     * when no construct path exists for the surface, the prevention isn't shipped
+     * yet, or the defect is undecidable (heuristic-behavioral). The lint rule is
+     * always the artifact-time floor regardless.
+     */
+    readonly upstreamPrevention?: string;
+}
+/**
+ * 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).
+ */
+export declare const RULE_META: Record<RuleName, RuleMeta>;
+/** All declared rule metas, as a list. */
+export declare function allRuleMeta(): RuleMeta[];
+/** Look up one rule's meta (undefined for an unknown id). */
+export declare function ruleMeta(id: string): RuleMeta | undefined;
+//# sourceMappingURL=rule-meta.d.ts.map

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