vigiles 12.6.0 → 12.8.0

package/dist/core/layout.d.ts

@@ -29,6 +29,17 @@ export interface PluginLayout {
     readonly instructionFile: string;
     /** Surface dirs materialized into the sandbox, e.g. skills/agents/commands. */
     readonly surfaceDirs: readonly string[];
+    /**
+     * Project-level dir under which an END-USER (not a plugin author) keeps the
+     * same surfaces, e.g. `.claude` → `.claude/skills`, `.claude/agents`. When set,
+     * the loader reads each surface from BOTH `<root>/<surface>` (the plugin /
+     * skills-library shape) AND `<root>/<userSurfaceRoot>/<surface>` (the shape a
+     * plain Claude Code user has), normalizing to the same materialized key. Most
+     * Claude Code users are NOT publishing a plugin — their skills live here, so
+     * without this the loader would see an empty machine for a normal repo.
+     * Undefined ⇒ only the primary location is read (backwards-compatible).
+     */
+    readonly userSurfaceRoot?: string;
     /** Skills dir, holding the nested `<dir>/<name>/SKILL.md`, e.g. `skills`. */
     readonly skillDir: string;
     /** Subagents dir, holding flat `<dir>/<name>.md`, e.g. `agents` (`""` = none). */

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

@@ -14,6 +14,22 @@ export interface SkillResourceFinding {
 export interface SkillResourceOptions {
     /** Injectable existence check (default: node:fs existsSync). */
     readonly existsSync?: (p: string) => boolean;
+    /**
+     * Repo root, used only together with `sharedDirs` (below). Off by default.
+     */
+    readonly repoRoot?: string;
+    /**
+     * OPT-IN shared-resource dirs — top-level dir names a repo shares across skills
+     * (`.vigilesrc.json` `sharedDirs`, e.g. `["scripts", "references"]`). Many skill
+     * libraries keep ONE top-level `scripts/` tree instead of a copy beside every
+     * SKILL.md, so a ref like `scripts/promptfoo/x.py` lives at the repo root. When
+     * a ref's FIRST path segment is a declared shared dir, it may ALSO resolve
+     * against `repoRoot`. Scoped to declared dirs on PURPOSE: a repo that sets no
+     * `sharedDirs` is byte-identical to before (skill-dir-only), and even with it a
+     * ref OUTSIDE a shared dir still can't be masked by a same-named repo-root file.
+     * The controlled fix for feedback P1-4 (opt-in, never a default behavior change).
+     */
+    readonly sharedDirs?: readonly string[];
 }
 /**
  * The bundled-resource references in a SKILL.md body that don't resolve on disk

package/dist/core/skill-resources.js

@@ -72,11 +72,28 @@ function localResourceTarget(rawTarget) {
     // 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.)
+    // SKIP: `~/`-rooted paths — the user's home / machine-global config, referenced
+    // intentionally from OUTSIDE the repo (JIT routing like `Read ~/.claude/docs/x.md`).
+    // Not a repo-bundled resource; unverifiable from the repo and never a "broken ref".
+    if (target === "~" || target.startsWith("~/"))
+        return null;
+    // Drop a URL fragment / query suffix so `references/api.md#auth` AND
+    // `references/schema.json?raw=1` resolve to the file. Done BEFORE the glob skip
+    // below so a legitimate `?query` suffix on a real bundled ref isn't mistaken for
+    // a glob `?` and wrongly skipped — the file must still be checked. (Only after
+    // the scheme check above, so we never mangle a URL.)
     const path = target.replace(/[?#].*$/, "");
     if (path.length === 0)
         return null;
+    // SKIP: globs and template placeholders — a ref carrying a glob metacharacter
+    // (`*`) or a brace/angle-bracket placeholder (`{trivial,…}`, `<linter>`) is a
+    // directory CONVENTION or an example, not a concrete file (`references/*.md`,
+    // `references/linter-cards/{a,b}/<linter>.md`). Resolving it as a literal path and
+    // reporting "missing" is a false positive (feedback P1-3). `?` is intentionally
+    // NOT in this class — it's the query separator stripped above; a genuine `?`-glob
+    // truncates to an extensionless path and is dropped by HAS_EXT below anyway.
+    if (/[*{}<>]/.test(path))
+        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(/^\.\//, "");
@@ -134,6 +151,18 @@ function candidatesInLine(line, lineNo) {
  */
 function skillResourceIssues(skillBody, skillDir, opts = {}) {
     const exists = opts.existsSync ?? node_fs_1.existsSync;
+    const sharedDirs = new Set(opts.sharedDirs ?? []);
+    // A ref resolves if it exists under the skill's own dir. If (and only if) its
+    // first segment is a DECLARED shared dir, it may also resolve against the repo
+    // root — the opt-in shared-tree case. No shared dirs → skill-dir-only (unchanged).
+    const resolvesAnywhere = (rel) => {
+        if (exists((0, node_path_1.resolve)(skillDir, rel)))
+            return true;
+        const firstSeg = rel.split("/")[0];
+        return (opts.repoRoot !== undefined &&
+            sharedDirs.has(firstSeg) &&
+            exists((0, node_path_1.resolve)(opts.repoRoot, rel)));
+    };
     const findings = [];
     const seen = new Set();
     const lines = skillBody.split("\n");
@@ -146,8 +175,7 @@ function skillResourceIssues(skillBody, skillDir, opts = {}) {
         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))
+            if (resolvesAnywhere(c.resolved))
                 continue;
             // De-dupe the same missing file referenced several times in the body.
             const key = `${c.kind}:${c.resolved}`;

package/dist/core/types.d.ts

@@ -333,6 +333,18 @@ export interface VigilesConfig {
      * excluded.
      */
     exclude?: readonly string[];
+    /**
+     * Top-level dir names shared across skills, e.g. `["scripts", "references"]`.
+     * OPT-IN: many skill libraries keep ONE top-level `scripts/`/`references/` tree
+     * rather than a copy beside every `SKILL.md`, so a bundled ref like
+     * `scripts/promptfoo/x.py` lives at the REPO ROOT. When a `SKILL.md` body ref's
+     * first path segment is a declared shared dir, `skill-resource-resolves` / audit
+     * ALSO resolves it against the repo root, not only the skill's own dir. Scoped
+     * to declared dirs on purpose: a repo that omits this key behaves exactly as
+     * before (skill-dir-only resolution), and a ref outside a shared dir is never
+     * masked by a same-named repo-root file. See feedback P1-4.
+     */
+    sharedDirs?: readonly string[];
     /**
      * The harness(es) this repo targets — selects the compile dialect / skill
      * frontmatter profile / instruction-file shape, instead of sniffing the cwd.

package/dist/eval-cost.d.ts

@@ -9,7 +9,7 @@
  * the `claude` CLI) + a running session tally. We deliberately do NOT show a
  * "% of your subscription" — Anthropic does not expose a subscription's quota or
  * limit programmatically (and the real limits are rolling rate windows, not a
- * dollar bucket), so any percentage would be fiction. See docs/eval-architecture.md.
+ * dollar bucket), so any percentage would be fiction. See research/eval-architecture.md.
  *
  * Pure + injectable (env + an output sink), so the whole thing is unit-tested
  * without a model or a real key.

package/dist/eval.d.ts

@@ -43,7 +43,7 @@ export interface EvalArm {
      * opus: { model: "claude-opus-4-8" } }` — so model-as-an-arm answers "does my
      * harness still hold on the cheaper tier / after a model upgrade?" through the
      * same significance machinery, with no separate model-matrix runner. Omit to
-     * use the eval-level model. See `docs/eval-architecture.md` (model strategy).
+     * use the eval-level model. See `research/eval-architecture.md` (model strategy).
      */
     readonly model?: string;
 }
@@ -491,7 +491,7 @@ export declare function aggregateUsage(usages: readonly EvalUsage[]): ArmUsage;
  * e.g. `claude-haiku-4-5-20251001`. A floating alias (`haiku`, `sonnet`, or even
  * `claude-sonnet-4-6` with no date) can change underneath you — so a cached or
  * baselined result pinned to it can silently hide model drift. See
- * `docs/eval-architecture.md` (honest model pinning).
+ * `research/eval-architecture.md` (honest model pinning).
  */
 export declare function isDatedModel(model: string): boolean;
 /**

package/dist/eval.js

@@ -665,7 +665,7 @@ function isRecord(v) {
  * e.g. `claude-haiku-4-5-20251001`. A floating alias (`haiku`, `sonnet`, or even
  * `claude-sonnet-4-6` with no date) can change underneath you — so a cached or
  * baselined result pinned to it can silently hide model drift. See
- * `docs/eval-architecture.md` (honest model pinning).
+ * `research/eval-architecture.md` (honest model pinning).
  */
 function isDatedModel(model) {
     return /\d{8}$/.test(model);

package/dist/leaderboard.js

@@ -214,6 +214,12 @@ function computeIntegrityScore(deductions) {
     }
     return { score: Math.max(0, 100 - penalty), penalty };
 }
+/** Resolve the terse "thing(s)" plural placeholder against a count:
+ * n===1 drops the "(s)" ("1 tool"); otherwise it becomes "s" ("3 tools").
+ * (Kept local — audit-score.ts has its own copy to avoid a circular import.) */
+function pluralizeLabel(n, label) {
+    return label.replace(/\(s\)/g, n === 1 ? "" : "s");
+}
 /** Deterministic structural-health score for one scanned plugin. */
 function scoreReport(r) {
     // An empty/unloadable machine isn't healthy — it's a non-plugin or a broken
@@ -230,7 +236,7 @@ function scoreReport(r) {
     for (const d of deductions) {
         if (d.n === 0)
             continue;
-        issues.push(`${String(d.n)} ${d.label}`);
+        issues.push(`${String(d.n)} ${pluralizeLabel(d.n, d.label)}`);
     }
     // Sort issues by cost (worst first) so the report leads with what matters.
     issues.sort((a, b) => Number(b.split(" ")[0]) - Number(a.split(" ")[0]));
@@ -241,10 +247,10 @@ function scoreReport(r) {
     //   - untested surfaces: a hardening gap, not breakage.
     const noContract = r.agents.filter((a) => a.tools === null).length;
     if (noContract > 0) {
-        issues.push(`${String(noContract)} agent(s) inherit all tools (no contract) (advisory)`);
+        issues.push(`${String(noContract)} ${pluralizeLabel(noContract, "agent(s) inherit all tools (no contract) (advisory)")}`);
     }
     if (r.untested > 0) {
-        issues.push(`${String(r.untested)} untested surface(s) (advisory)`);
+        issues.push(`${String(r.untested)} ${pluralizeLabel(r.untested, "untested surface(s) (advisory)")}`);
     }
     return { score, issues };
 }

package/dist/plugin-loader.d.ts

@@ -14,6 +14,15 @@ export interface LoadedPlugin {
      * read it in a test, or just to know what the deterministic run won't reach.
      */
     readonly warnings: readonly string[];
+    /**
+     * Map from a materialized `files` key to the ABSOLUTE on-disk path it was read
+     * from. A surface can be materialized under a canonical key (`.claude/skills/
+     * foo/SKILL.md`) while living on disk at a different root (the repo-root
+     * `skills/` OR the project-level `.claude/skills/`), so a consumer that needs
+     * the real dir (e.g. resolving a skill's bundled resources) must reverse-map
+     * through this instead of guessing from the key. Present for every surface file.
+     */
+    readonly sources: Record<string, string>;
 }
 /**
  * Load the real harness at `pluginPath`. Returns the resolved settings (hooks),

package/dist/plugin-loader.js

@@ -36,6 +36,7 @@ exports.resolveHarness = resolveHarness;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const toml_1 = require("@iarna/toml");
+const hash_js_1 = require("./core/hash.js");
 const MAX_SKILL_FILE_BYTES = 256 * 1024;
 /** Parse a JSON file, or null on any error (missing / malformed). */
 function safeReadJson(path) {
@@ -140,32 +141,108 @@ function loadPlugin(pluginPath, layout) {
         ? JSON.parse(JSON.stringify(hooks).replaceAll(layout.pluginRootToken, root))
         : undefined;
     const files = {};
+    const sources = {};
     const instructions = (0, node_path_1.join)(root, layout.instructionFile);
     if ((0, node_fs_1.existsSync)(instructions)) {
         files[layout.instructionFile] = (0, node_fs_1.readFileSync)(instructions, "utf-8");
+        sources[layout.instructionFile] = instructions;
     }
-    // Materialize each project-level surface under the materialize root so the
-    // assembled context is present in the sandbox (best-effort — headless
-    // activation of plugin skills/subagents/commands is not guaranteed; the body
-    // is present for the agent to read either way). Counting what we materialize
-    // also lets us warn about surfaces the deterministic tier can't drive.
-    const counts = {};
-    for (const surface of layout.surfaceDirs) {
-        const dir = (0, node_path_1.join)(root, surface);
-        if (!(0, node_fs_1.existsSync)(dir) || !(0, node_fs_1.statSync)(dir).isDirectory())
-            continue;
-        const tree = readTree(dir, root);
-        for (const [rel, content] of Object.entries(tree)) {
-            files[(0, node_path_1.join)(layout.materializeRoot, rel)] = content;
-        }
-        counts[surface] = Object.keys(tree).length;
-    }
+    const counts = materializeSurfaces(root, layout, files, sources);
     return {
         settings: resolvedHooks ? { hooks: resolvedHooks } : {},
         files,
+        sources,
         warnings: pluginWarnings(root, counts, resolvedHooks, files, layout),
     };
 }
+/**
+ * A surface holds a LOADABLE file — a `<name>/SKILL.md` for skills, a `.md` for
+ * agents/commands. A stray non-surface file (`skills/README.md`, `.gitkeep`) does
+ * NOT count, else it would mark the root populated and shadow a plain user's real
+ * `.claude/skills`.
+ */
+function surfaceHasLoadable(layout, surface, tree) {
+    const keys = Object.keys(tree);
+    return surface === layout.skillDir
+        ? keys.some((k) => (0, node_path_1.basename)(k) === "SKILL.md")
+        : keys.some((k) => k.endsWith(".md"));
+}
+/**
+ * Classify the repo shape from disk, with EXPLICIT precedence:
+ *  1. a `<root>/SKILL.md` → the target IS one skill dir (single-skill).
+ *  2. any root-surface with LOADABLE content, OR a plugin manifest / hooks
+ *     convention → read the ROOT surfaces. A plugin ships from its manifest even
+ *     with no root surface dirs, so its dev `.claude/…` is never a fallback.
+ *  3. else, if the layout declares a user-surface root → a plain user repo.
+ *  4. else → nothing loadable.
+ * Pure over the pre-read `rootTrees` + a few existence checks — one place to test.
+ */
+function classifySurfaceSource(root, layout, rootTrees) {
+    if (layout.skillDir && (0, node_fs_1.existsSync)((0, node_path_1.join)(root, "SKILL.md"))) {
+        return { kind: "single-skill", skillName: (0, node_path_1.basename)(root) };
+    }
+    const rootHasLoadable = layout.surfaceDirs.some((s) => surfaceHasLoadable(layout, s, rootTrees.get(s) ?? {}));
+    const isPluginShaped = (0, node_fs_1.existsSync)((0, node_path_1.join)(root, layout.manifestPath)) ||
+        (0, node_fs_1.existsSync)((0, node_path_1.join)(root, layout.hooksConventionPath));
+    if (rootHasLoadable || isPluginShaped)
+        return { kind: "root" };
+    if (layout.userSurfaceRoot !== undefined) {
+        return { kind: "user", sub: layout.userSurfaceRoot };
+    }
+    return { kind: "none" };
+}
+function materializeSurfaces(root, layout, files, sources) {
+    const counts = {};
+    const isDir = (p) => (0, node_fs_1.existsSync)(p) && (0, node_fs_1.statSync)(p).isDirectory();
+    // Read each ROOT-level surface tree once (keys relative to the surface dir).
+    const rootTrees = new Map();
+    for (const surface of layout.surfaceDirs) {
+        const dir = (0, node_path_1.join)(root, surface);
+        if (isDir(dir))
+            rootTrees.set(surface, readTree(dir, dir));
+    }
+    const add = (key, content, onDisk) => {
+        files[key] = content;
+        sources[key] = onDisk;
+    };
+    const source = classifySurfaceSource(root, layout, rootTrees);
+    switch (source.kind) {
+        case "single-skill": {
+            // Materialize the WHOLE skill dir under the canonical skills key, so its
+            // bundled resources (scripts/references/assets) ship too, not just SKILL.md.
+            const tree = readTree(root, root);
+            for (const [rel, content] of Object.entries(tree)) {
+                add((0, node_path_1.join)(layout.materializeRoot, layout.skillDir, source.skillName, rel), content, (0, node_path_1.join)(root, rel));
+            }
+            counts[layout.skillDir] = Object.keys(tree).length;
+            break;
+        }
+        case "root":
+        case "user": {
+            const base = source.kind === "user" ? (0, node_path_1.join)(root, source.sub) : root;
+            for (const surface of layout.surfaceDirs) {
+                const dir = (0, node_path_1.join)(base, surface);
+                // Root surfaces were pre-read; user surfaces are read fresh here.
+                const tree = source.kind === "root"
+                    ? (rootTrees.get(surface) ?? {})
+                    : isDir(dir)
+                        ? readTree(dir, dir)
+                        : {};
+                for (const [rel, content] of Object.entries(tree)) {
+                    add((0, node_path_1.join)(layout.materializeRoot, surface, rel), content, (0, node_path_1.join)(dir, rel));
+                }
+                counts[surface] = Object.keys(tree).length;
+            }
+            break;
+        }
+        case "none":
+            break;
+        /* v8 ignore next 2 -- exhaustiveness guard, unreachable given SurfaceSource */
+        default:
+            (0, hash_js_1.assertNever)(source);
+    }
+    return counts;
+}
 /**
  * Flag surfaces present-but-not-deterministically-exercisable. Subagents
  * (`agents/`) and slash commands (`commands/`) are materialized into the sandbox

package/dist/rule-inventory.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Rule-inventory — the deterministic, foreign-safe teaser surface of the
+ * `audit` rule-compile tier (design: `research/audit-rule-compile-tier.md`).
+ *
+ * Finds prose rules in a `CLAUDE.md` / `AGENTS.md` that map to an off-the-shelf
+ * lint rule, and whether that rule already appears in the repo's lint config.
+ * The remedy for a documented-but-unconfigured intent is a one-line config
+ * change, not synthesis — so this is a cheap, high-value nudge.
+ *
+ * NO model. NO config execution (textual grep only — never resolves/executes
+ * `eslint.config.js`, which would be the RCE path). HIGH PRECISION by
+ * construction: only rule-name / code-token-shaped keywords are matched, and
+ * only as whole tokens. Bare prose words are excluded on purpose — a raw
+ * keyword match (`token`, `!`, `await`, `secret`, `silently`, …) sprays false
+ * positives on real instruction files (measured: 107 raw hits over 4 real
+ * CLAUDE.md files, ~all garbage). The model-driven analysis (extract → classify
+ * → compile → gate → run) lives in the OPT-IN tier, not here.
+ *
+ * MULTI-LINTER by shape, ESLint-first by data. The matcher is linter-agnostic;
+ * each mapping is keyed by linter, so adding Ruff / Clippy / Pylint / RuboCop /
+ * Stylelint is additive DATA (a curation task), not a refactor. The OPT-IN tier
+ * should resolve "is this rule enabled" via vigiles's existing multi-linter
+ * `checkLinterRule` engine (which execs the config) — kept out of this
+ * exec-free, foreign-safe surface on purpose.
+ */
+/** Linters vigiles's cross-reference engine already understands. */
+export type LinterName = "eslint" | "ruff" | "clippy" | "pylint" | "rubocop" | "stylelint";
+/** One prose→rule mapping for a single linter. `keywords` are rule-name/token-shaped. */
+export interface IntentMapping {
+    readonly intent: string;
+    readonly linter: LinterName;
+    /** Whole-token, code-shaped triggers only (no bare English words). */
+    readonly keywords: readonly string[];
+    /** The off-the-shelf rule that enforces this intent. */
+    readonly rule: string;
+    /** The one-line config change that turns it on. */
+    readonly configFix: string;
+    /** True if a `recommended` preset typically enables this rule (so a bare
+     * recommended-extends is evidence it may already be on). */
+    readonly inRecommended?: boolean;
+}
+/**
+ * Curated from agent-rules-compiler's `rule-map.json`, keeping ONLY the
+ * specific (rule-name / code-token) keywords and dropping every bare-word
+ * trigger the FP measurement flagged (`token`, `secret`, `password`, `await`,
+ * `!`, `aria`, `silently`, `prefix`, `complexity`, `barrel`, `cycle`, …).
+ *
+ * ESLint-only today — Ruff/Clippy/Pylint/RuboCop/Stylelint entries append here
+ * with their own `linter` + rule-name keywords, no code change.
+ */
+export declare const INTENT_MAP: readonly IntentMapping[];
+/**
+ * Whether the mapped rule is visible in the lint config text (textual grep —
+ * imperfect, labelled). `contradiction` is the sharpest state: the harness
+ * documents the rule as a norm, yet the config EXPLICITLY sets it to off/0 —
+ * the docs and the config disagree.
+ */
+export type ConfigState = "in-config" | "not-in-config" | "preset-maybe" | "contradiction";
+/** One documented-intent → off-the-shelf-rule finding. */
+export interface RuleInventoryItem {
+    readonly intent: string;
+    readonly linter: LinterName;
+    /** The rule-name/token that matched in the instruction file. */
+    readonly matched: string;
+    /** The off-the-shelf rule that enforces it. */
+    readonly rule: string;
+    /** Whether `rule` appears anywhere in the provided config text. */
+    readonly configState: ConfigState;
+    /** The one-line config change to enforce it (shown when not in config). */
+    readonly configFix: string;
+}
+/** Options for {@link buildRuleInventory}. */
+export interface RuleInventoryOptions {
+    /**
+     * Restrict to the repo's detected linter(s). When omitted, all linters are
+     * considered — safe because the keywords are rule-name-specific, but a caller
+     * that knows the repo is Python-only can pass `["ruff"]` to avoid a stray
+     * cross-language rule-name collision.
+     */
+    readonly linters?: readonly LinterName[];
+}
+/**
+ * A keyword matches only as a WHOLE token: bounded by start/end or a
+ * non-`[\w/@.-]` character on each side (so `no-console` matches in
+ * `` `no-console` `` and `enforce no-console;` but `no-console-x` does not,
+ * and prose containing the substring elsewhere never trips it).
+ */
+export declare function matchesWholeToken(text: string, keyword: string): boolean;
+export declare function buildRuleInventory(instructionText: string, configText: string, options?: RuleInventoryOptions): RuleInventoryItem[];
+//# sourceMappingURL=rule-inventory.d.ts.map