vigiles 12.6.0 → 12.7.0

package/dist/adapters/claude-code/layout.js

@@ -9,6 +9,10 @@ exports.claudeCodeLayout = {
     settingsFormat: "json",
     instructionFile: "CLAUDE.md",
     surfaceDirs: ["skills", "agents", "commands"],
+    // A plain Claude Code USER keeps skills/agents/commands under `.claude/`, not at
+    // the repo root (that's the published-plugin shape). Read both so a normal repo
+    // isn't seen as an empty machine.
+    userSurfaceRoot: ".claude",
     skillDir: "skills",
     agentDir: "agents",
     commandDir: "commands",

package/dist/cli.js

@@ -924,18 +924,49 @@ function verifyMarkdownModeRules(files, silent, config) {
  *   --summary   Print a single-line summary (for SessionStart hooks)
  *   --json      Print structured JSON report (for CI integration)
  */
+/**
+ * The repo root that `sharedDirs` resolve against. The caller's cwd (where
+ * `.vigilesrc.json` lives) is used ONLY when the scan target is INSIDE it — e.g.
+ * `lint packages/foo` from the repo root, where the shared tree is an ancestor of
+ * the scoped subdir. When the target is NOT under cwd (`lint path/to/other-repo`),
+ * we resolve against the TARGET itself, so a foreign-repo lint never lets the
+ * caller's own files satisfy the target's bundled resources (scoped-lint integrity).
+ */
+function sharedDirsRootFor(scanTarget) {
+    const cwd = process.cwd();
+    const target = (0, node_path_1.resolve)(scanTarget);
+    const rel = (0, node_path_1.relative)(cwd, target);
+    const underCwd = rel === "" || (!rel.startsWith("..") && !(0, node_path_1.isAbsolute)(rel));
+    return underCwd ? cwd : target;
+}
 async function runLint(restArgs, flags, config) {
     const summary = flags.includes("--summary");
     const json = flags.includes("--json");
     const silent = summary || json;
     const files = findInstructionFiles(restArgs, config?.exclude);
+    // P0-2: scope the surface checks (subagent contracts, skill resources, MCP, …)
+    // to an explicit DIRECTORY target when one is given, instead of always scanning
+    // the whole working dir and reporting surfaces the user didn't point at. Only a
+    // SINGLE existing directory narrows; a file / several paths / none → cwd, so
+    // bare `vigiles lint` (the CI-common case) stays byte-identical. scanPlugin
+    // reads only under this root, so a surface outside it can never enter the report.
+    // Computed BEFORE the harness resolves so auto-detection keys on the TARGET, not
+    // cwd — `lint path/to/codex-repo` picks that repo's harness, not the caller's.
+    const positional = restArgs.filter((a) => !a.startsWith("--"));
+    const scanRoot = positional.length === 1 &&
+        (0, node_fs_1.existsSync)(positional[0]) &&
+        (0, node_fs_1.lstatSync)(positional[0]).isDirectory()
+        ? (0, node_path_1.resolve)(positional[0])
+        : process.cwd();
     // Resolve the active harness ONCE so the harness-specific checks below run
     // against the right adapter's dialect (tool/event catalogs) and surfaces —
     // not a hard-coded Claude Code default. A subagent-surface rule reports n/a
-    // on a harness without subagents (Codex) rather than scanning nothing.
+    // on a harness without subagents (Codex) rather than scanning nothing. Detect
+    // against `scanRoot` (the target), so a scoped scan of another-harness repo
+    // uses that repo's layout/dialect.
     const harnessFlag = harnessFlagFrom(flags);
     const lintSelection = (0, adapter_registry_js_1.resolveHarnessSelection)({
-        root: process.cwd(),
+        root: scanRoot,
         flag: harnessFlag,
         configHarness: (0, adapter_registry_js_1.normalizeHarnessList)(config?.harness),
     });
@@ -998,71 +1029,71 @@ async function runLint(restArgs, flags, config) {
     // 7b. Untested-surface check — skills/agents/hooks shipping without a test or
     // eval. Warning by default (a nudge, exit 0); set rules.untested-{skill,agent,
     // hook} to "error" to gate CI. See src/test-coverage.ts and docs/rules/.
-    const untested = checkUntestedSurfaces(config, silent, adapter);
+    const untested = checkUntestedSurfaces(config, silent, adapter, scanRoot);
     // 7c. Subagent tool-contract check — cross-reference each subagent's `tools:`
     // rail against the harness catalog (the moat). n/a on a harness with no
     // subagents. Off by default unless a severity is configured; warning surfaces
     // a typo/never-available tool, error gates CI.
-    const toolContract = checkSubagentToolContracts(config, silent, adapter);
+    const toolContract = checkSubagentToolContracts(config, silent, adapter, scanRoot);
     // 7d. Hook-event check — a hook registered under an event the harness doesn't
     // define never fires. High-precision (close typos only). Off unless configured.
-    const hookEvents = checkHookEvents(config, silent, adapter);
+    const hookEvents = checkHookEvents(config, silent, adapter, scanRoot);
     // 7e. Subagent-frontmatter check — a subagent missing required frontmatter
     // (name + description) won't register. n/a on a harness with no subagents.
-    const frontmatter = checkFrontmatterSchema(config, silent, adapter);
+    const frontmatter = checkFrontmatterSchema(config, silent, adapter, scanRoot);
     // 7f. MCP-config check — a declared MCP server with no command/url can't start.
-    const mcpConfig = checkMcpConfig(config, silent, adapter);
+    const mcpConfig = checkMcpConfig(config, silent, adapter, scanRoot);
     // 7g. Skill-frontmatter — RECOMMEND explicit name/description on skills (a
     // reliable trigger surface). Best-practice nudge; skills load without it.
-    const skillFm = checkSkillFrontmatter(config, silent, adapter);
+    const skillFm = checkSkillFrontmatter(config, silent, adapter, scanRoot);
     // 7h. MCP tool-resolution — an `mcp__server__tool` in a contract whose server
     // the plugin doesn't declare can't resolve (the MCP half of the tool moat).
-    const mcpToolResolves = checkMcpToolResolves(config, silent, adapter);
+    const mcpToolResolves = checkMcpToolResolves(config, silent, adapter, scanRoot);
     // 7i. Hook-script existence — a hook command referencing a missing script file
     // never runs (matches Anthropic's own `claude plugin validate`).
-    const hookScripts = checkHookScriptExists(config, silent, adapter);
+    const hookScripts = checkHookScriptExists(config, silent, adapter, scanRoot);
     // 7j. Disallowed-tools — a `disallowedTools:` block-list typo blocks nothing
     // (the deny-side mirror of subagent-tool-contract; close-typo only).
-    const disallowedTools = checkDisallowedTools(config, silent, adapter);
+    const disallowedTools = checkDisallowedTools(config, silent, adapter, scanRoot);
     // 7k. Description-overlap — two model-invocable skills with near-identical
     // descriptions collide in the selector (deterministic NCD precision proxy).
-    const descriptionOverlap = checkDescriptionOverlap(config, silent, adapter);
+    const descriptionOverlap = checkDescriptionOverlap(config, silent, adapter, scanRoot);
     // 7k². Skill-description-budget — a model-invocable skill whose description is
     // so long the trigger signal is buried (heuristic proxy; degrades recall +
     // precision). Generous 500-char budget; warn-tier, never gates.
-    const descriptionBudget = checkDescriptionBudget(config, silent, adapter);
+    const descriptionBudget = checkDescriptionBudget(config, silent, adapter, scanRoot);
     // 7l. Frontmatter-valid — a `---` block that isn't valid YAML (warn; js-yaml is
     // stricter than some loaders, so verify before enforcing).
-    const frontmatterValid = checkFrontmatterValid(config, silent, adapter);
+    const frontmatterValid = checkFrontmatterValid(config, silent, adapter, scanRoot);
     // 7m. MCP hook-target — a `type: mcp_tool` hook action that's incomplete or
     // targets an undeclared server (the moat applied to the hook surface).
-    const mcpHookTargets = checkMcpHookTargets(config, silent, adapter);
+    const mcpHookTargets = checkMcpHookTargets(config, silent, adapter, scanRoot);
     // 7n. Prefer-compiled-hooks — ONE discovery nudge (not per-hook) toward
     // compiled `vigiles/hook` artifacts when hand-written hooks ship. Recommendation.
-    const preferCompiledHooks = checkPreferCompiledHooks(config, silent, adapter);
+    const preferCompiledHooks = checkPreferCompiledHooks(config, silent, adapter, scanRoot);
     // 7o. Lethal-trifecta — a unit (subagent / model-invocable skill) whose tools
     // hold all three legs (read-private + ingest-untrusted + exfiltrate) is a
     // prompt-injection exfil path (Rule of Two). Capability SET-intersection.
-    const lethalTrifecta = checkLethalTrifecta(config, silent, adapter);
+    const lethalTrifecta = checkLethalTrifecta(config, silent, adapter, scanRoot);
     // 7p. Skill-resource — a SKILL.md body referencing a bundled file that doesn't
     // exist on disk under the skill dir (the agent gets nothing). FP-safe.
-    const skillResources = checkSkillResourceResolves(config, silent, adapter);
+    const skillResources = checkSkillResourceResolves(config, silent, adapter, scanRoot);
     // 7q. Skill-missing-fence — a SKILL.md opening with `name:`/`description:` but no
     // `---` fence loads as plain body (invisible — no name/description/trigger).
-    const skillFence = checkSkillMissingFence(config, silent, adapter);
+    const skillFence = checkSkillMissingFence(config, silent, adapter, scanRoot);
     // 7r. Plugin-dir-layout — functional surface dirs (skills/agents/commands) nested
     // inside the `.claude-plugin/` manifest dir where the harness can't see them.
-    const pluginLayout = checkPluginDirLayout(config, silent, adapter);
+    const pluginLayout = checkPluginDirLayout(config, silent, adapter, scanRoot);
     // 7s. Delegation-trifecta — a lethal trifecta that emerges across a delegation
     // edge (a subagent's own ∪ delegated-to capability) though no single unit trips it.
-    const delegationTrifecta = checkDelegationTrifecta(config, silent, adapter);
+    const delegationTrifecta = checkDelegationTrifecta(config, silent, adapter, scanRoot);
     // 7t. Hook-block-ineffective — a hook that looks like it blocks but silently
     // doesn't (block decision on a non-blocking event, or the legacy `decision`
     // field on a permission-gated event). The #1 verified hook pain (#19009).
-    const hookBlock = checkHookBlockIneffective(config, silent, adapter);
+    const hookBlock = checkHookBlockIneffective(config, silent, adapter, scanRoot);
     // 7u. Hook-matcher — a hook `matcher` that never fires (tool-name typo, or a
     // malformed/undeclared MCP form).
-    const hookMatcher = checkHookMatcher(config, silent, adapter);
+    const hookMatcher = checkHookMatcher(config, silent, adapter, scanRoot);
     // 8. Validate vigiles builder calls inside markdown code blocks. Default
     // is to validate every ref; illustrative blocks opt out via
     // `<!-- vigiles:ignore -->` (single block) or
@@ -2456,7 +2487,7 @@ function checkIntegrityForFiles(files, severity, silent) {
  * "warn" prints but never fails CI; "error" fails (exit 2). Returns the raw
  * untested count plus the severity-gated error count.
  */
-function checkUntestedSurfaces(config, silent, adapter) {
+function checkUntestedSurfaces(config, silent, adapter, scanRoot) {
     const rules = config?.rules;
     const skillSev = (0, types_js_1.ruleSeverity)(rules?.["untested-skill"]);
     const agentSev = (0, types_js_1.ruleSeverity)(rules?.["untested-subagent"]);
@@ -2472,7 +2503,7 @@ function checkUntestedSurfaces(config, silent, adapter) {
         ...(0, types_js_1.ruleOptions)(rules?.["untested-hook"]),
     };
     const report = (0, test_coverage_js_1.findUntestedSurfaces)({
-        basePath: process.cwd(),
+        basePath: scanRoot,
         layout: adapter.layout,
         skills: skillSev !== false,
         agents: agentSev !== false,
@@ -2515,7 +2546,7 @@ function reportNotApplicable(check, surface, adapter, silent) {
  * (plugin/MCP-provided) is never a false alarm. Warning by default; set
  * `subagent-tool-contract: "error"` to gate CI. Returns the issue + error counts.
  */
-function checkSubagentToolContracts(config, silent, adapter) {
+function checkSubagentToolContracts(config, silent, adapter, scanRoot) {
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["subagent-tool-contract"]);
     if (!sev)
         return { issues: 0, errors: 0 };
@@ -2528,7 +2559,7 @@ function checkSubagentToolContracts(config, silent, adapter) {
     // `agents/` path, so a harness with a different subagent dir Just Works.
     let agents;
     try {
-        agents = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).agents;
+        agents = (0, scan_js_1.scanPlugin)(scanRoot, adapter.layout, adapter.dialect).agents;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -2558,7 +2589,7 @@ function checkSubagentToolContracts(config, silent, adapter) {
  * `hookEventIssues` (the shared detector, high-precision: close typos only, never
  * a framework/custom event). Warning by default; "error" gates CI.
  */
-function checkHookEvents(config, silent, adapter) {
+function checkHookEvents(config, silent, adapter, scanRoot) {
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["hook-events"]);
     if (!sev)
         return { issues: 0, errors: 0 };
@@ -2568,7 +2599,7 @@ function checkHookEvents(config, silent, adapter) {
     }
     let found;
     try {
-        found = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).hookEventIssues;
+        found = (0, scan_js_1.scanPlugin)(scanRoot, adapter.layout, adapter.dialect).hookEventIssues;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -2589,7 +2620,7 @@ function checkHookEvents(config, silent, adapter) {
  * of a real one) — it silently falls back / is ignored. Reuses `scanPlugin`'s
  * `frontmatterIssues` + `frontmatterValueIssues`. Warning by default; "error" gates CI.
  */
-function checkFrontmatterSchema(config, silent, adapter) {
+function checkFrontmatterSchema(config, silent, adapter, scanRoot) {
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["subagent-frontmatter"]);
     if (!sev)
         return { issues: 0, errors: 0 };
@@ -2599,7 +2630,7 @@ function checkFrontmatterSchema(config, silent, adapter) {
     }
     let found;
     try {
-        const r = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect);
+        const r = (0, scan_js_1.scanPlugin)(scanRoot, adapter.layout, adapter.dialect);
         found = [...r.frontmatterIssues, ...r.frontmatterValueIssues];
     }
     catch {
@@ -2622,13 +2653,13 @@ function checkFrontmatterSchema(config, silent, adapter) {
  * default; set "error" to enforce it on your own skills. Reuses `scanPlugin`'s
  * `skillMetaIssues`.
  */
-function checkSkillFrontmatter(config, silent, adapter) {
+function checkSkillFrontmatter(config, silent, adapter, scanRoot) {
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["skill-frontmatter"]);
     if (!sev)
         return { issues: 0, errors: 0 };
     let found;
     try {
-        found = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).skillMetaIssues;
+        found = (0, scan_js_1.scanPlugin)(scanRoot, adapter.layout, adapter.dialect).skillMetaIssues;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -2649,13 +2680,13 @@ function checkSkillFrontmatter(config, silent, adapter) {
  * lane stays first-class — so it fires once and the message links the guide.
  * Reuses `scanPlugin`'s `manualHookCount` (one-detector-no-drift).
  */
-function checkPreferCompiledHooks(config, silent, adapter) {
+function checkPreferCompiledHooks(config, silent, adapter, scanRoot) {
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["prefer-compiled-hooks"]);
     if (!sev)
         return { issues: 0, errors: 0 };
     let count;
     try {
-        count = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).manualHookCount;
+        count = (0, scan_js_1.scanPlugin)(scanRoot, adapter.layout, adapter.dialect).manualHookCount;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -2675,13 +2706,13 @@ function checkPreferCompiledHooks(config, silent, adapter) {
  * (stdio) nor a `url` (http/sse) can't start. Reuses `scanPlugin`'s `mcpIssues`.
  * Warning by default; "error" gates CI.
  */
-function checkMcpConfig(config, silent, adapter) {
+function checkMcpConfig(config, silent, adapter, scanRoot) {
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["mcp-config"]);
     if (!sev)
         return { issues: 0, errors: 0 };
     let found;
     try {
-        found = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).mcpIssues;
+        found = (0, scan_js_1.scanPlugin)(scanRoot, adapter.layout, adapter.dialect).mcpIssues;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -2702,7 +2733,7 @@ function checkMcpConfig(config, silent, adapter) {
  * `disallowedToolIssues` (close-typo only — high-precision). Warning by default;
  * "error" gates CI.
  */
-function checkDisallowedTools(config, silent, adapter) {
+function checkDisallowedTools(config, silent, adapter, scanRoot) {
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["disallowed-tools-contract"]);
     if (!sev)
         return { issues: 0, errors: 0 };
@@ -2712,7 +2743,7 @@ function checkDisallowedTools(config, silent, adapter) {
     }
     let found;
     try {
-        found = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).agents.flatMap((a) => a.disallowedToolIssues.map((i) => ({ message: i.message, path: a.path })));
+        found = (0, scan_js_1.scanPlugin)(scanRoot, adapter.layout, adapter.dialect).agents.flatMap((a) => a.disallowedToolIssues.map((i) => ({ message: i.message, path: a.path })));
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -2734,13 +2765,13 @@ function checkDisallowedTools(config, silent, adapter) {
  * colon / `<example>` is flagged though it may still load — hence WARN by default
  * (verify before setting "error").
  */
-function checkFrontmatterValid(config, silent, adapter) {
+function checkFrontmatterValid(config, silent, adapter, scanRoot) {
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["frontmatter-valid"]);
     if (!sev)
         return { issues: 0, errors: 0 };
     let found;
     try {
-        found = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).malformedFrontmatter;
+        found = (0, scan_js_1.scanPlugin)(scanRoot, adapter.layout, adapter.dialect).malformedFrontmatter;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -2761,13 +2792,13 @@ function checkFrontmatterValid(config, silent, adapter) {
  * `scanPlugin`'s `descriptionOverlaps` (calibrated FP-safe: only basically
  * identical text). Warning by default; "error" gates CI.
  */
-function checkDescriptionOverlap(config, silent, adapter) {
+function checkDescriptionOverlap(config, silent, adapter, scanRoot) {
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["description-overlap"]);
     if (!sev)
         return { issues: 0, errors: 0 };
     let found;
     try {
-        found = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).descriptionOverlaps;
+        found = (0, scan_js_1.scanPlugin)(scanRoot, adapter.layout, adapter.dialect).descriptionOverlaps;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -2788,13 +2819,13 @@ function checkDescriptionOverlap(config, silent, adapter) {
  * deterministic heuristic proxy (generous 500-char budget). Reuses `scanPlugin`'s
  * `descriptionBudgetIssues`. Warning by default; "error" gates CI.
  */
-function checkDescriptionBudget(config, silent, adapter) {
+function checkDescriptionBudget(config, silent, adapter, scanRoot) {
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["skill-description-budget"]);
     if (!sev)
         return { issues: 0, errors: 0 };
     let found;
     try {
-        found = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).descriptionBudgetIssues;
+        found = (0, scan_js_1.scanPlugin)(scanRoot, adapter.layout, adapter.dialect).descriptionBudgetIssues;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -2817,13 +2848,13 @@ function checkDescriptionBudget(config, silent, adapter) {
  * and skills, so it is NOT gated on the `subagents` capability — a skill-only
  * harness still has the surface.
  */
-function checkLethalTrifecta(config, silent, adapter) {
+function checkLethalTrifecta(config, silent, adapter, scanRoot) {
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["lethal-trifecta"]);
     if (!sev)
         return { issues: 0, errors: 0 };
     let found;
     try {
-        found = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).trifectaFindings;
+        found = (0, scan_js_1.scanPlugin)(scanRoot, adapter.layout, adapter.dialect).trifectaFindings;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -2845,13 +2876,18 @@ function checkLethalTrifecta(config, silent, adapter) {
  * nothing. Reuses `scanPlugin`'s `skillResourceIssues` (high-precision / FP-safe,
  * one detector, no drift). Warning by default; "error" gates CI.
  */
-function checkSkillResourceResolves(config, silent, adapter) {
+function checkSkillResourceResolves(config, silent, adapter, scanRoot) {
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["skill-resource-resolves"]);
     if (!sev)
         return { issues: 0, errors: 0 };
     let found;
     try {
-        found = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).skillResourceIssues;
+        found = (0, scan_js_1.scanPlugin)(scanRoot, adapter.layout, adapter.dialect, {
+            sharedDirs: config?.sharedDirs,
+            // sharedDirs live at the repo root that OWNS the scan target — cwd for a
+            // scoped subdir of this repo, the target itself for a foreign-repo lint.
+            sharedDirsRoot: sharedDirsRootFor(scanRoot),
+        }).skillResourceIssues;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -2873,13 +2909,13 @@ function checkSkillResourceResolves(config, silent, adapter) {
  * Reuses `scanPlugin`'s `skillFenceIssues` (one detector, no drift). Warning by
  * default; "error" gates CI.
  */
-function checkSkillMissingFence(config, silent, adapter) {
+function checkSkillMissingFence(config, silent, adapter, scanRoot) {
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["skill-missing-fence"]);
     if (!sev)
         return { issues: 0, errors: 0 };
     let found;
     try {
-        found = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).skillFenceIssues;
+        found = (0, scan_js_1.scanPlugin)(scanRoot, adapter.layout, adapter.dialect).skillFenceIssues;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -2901,13 +2937,13 @@ function checkSkillMissingFence(config, silent, adapter) {
  * `pluginLayoutIssues` (one detector, no drift). Warning by default; "error"
  * gates CI.
  */
-function checkPluginDirLayout(config, silent, adapter) {
+function checkPluginDirLayout(config, silent, adapter, scanRoot) {
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["plugin-dir-layout"]);
     if (!sev)
         return { issues: 0, errors: 0 };
     let found;
     try {
-        found = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).pluginLayoutIssues;
+        found = (0, scan_js_1.scanPlugin)(scanRoot, adapter.layout, adapter.dialect).pluginLayoutIssues;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -2929,13 +2965,13 @@ function checkPluginDirLayout(config, silent, adapter) {
  * gates CI. Surfaces across the subagent graph, so it is NOT gated on a
  * capability the way a surface-specific rule is.
  */
-function checkDelegationTrifecta(config, silent, adapter) {
+function checkDelegationTrifecta(config, silent, adapter, scanRoot) {
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["delegation-trifecta"]);
     if (!sev)
         return { issues: 0, errors: 0 };
     let found;
     try {
-        found = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).delegationTrifecta;
+        found = (0, scan_js_1.scanPlugin)(scanRoot, adapter.layout, adapter.dialect).delegationTrifecta;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -2957,7 +2993,7 @@ function checkDelegationTrifecta(config, silent, adapter) {
  * permission-gated event (#19009, the #1 verified hook pain). Reuses `scanPlugin`'s
  * `hookBlockFindings` (one detector, no drift). Warning by default; "error" gates CI.
  */
-function checkHookBlockIneffective(config, silent, adapter) {
+function checkHookBlockIneffective(config, silent, adapter, scanRoot) {
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["hook-block-ineffective"]);
     if (!sev)
         return { issues: 0, errors: 0 };
@@ -2967,7 +3003,7 @@ function checkHookBlockIneffective(config, silent, adapter) {
     }
     let found;
     try {
-        found = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).hookBlockFindings;
+        found = (0, scan_js_1.scanPlugin)(scanRoot, adapter.layout, adapter.dialect).hookBlockFindings;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -2989,7 +3025,7 @@ function checkHookBlockIneffective(config, silent, adapter) {
  * Reuses `scanPlugin`'s `hookMatcherFindings` (one detector, no drift). Warning
  * by default; "error" gates CI.
  */
-function checkHookMatcher(config, silent, adapter) {
+function checkHookMatcher(config, silent, adapter, scanRoot) {
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["hook-matcher"]);
     if (!sev)
         return { issues: 0, errors: 0 };
@@ -2999,7 +3035,7 @@ function checkHookMatcher(config, silent, adapter) {
     }
     let found;
     try {
-        found = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).hookMatcherFindings;
+        found = (0, scan_js_1.scanPlugin)(scanRoot, adapter.layout, adapter.dialect).hookMatcherFindings;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -3020,7 +3056,7 @@ function checkHookMatcher(config, silent, adapter) {
  * `mcpHookIssues` (high-precision: declared-set gated, built-ins allowlisted).
  * Warning by default; "error" gates CI.
  */
-function checkMcpHookTargets(config, silent, adapter) {
+function checkMcpHookTargets(config, silent, adapter, scanRoot) {
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["mcp-hook-target-resolves"]);
     if (!sev)
         return { issues: 0, errors: 0 };
@@ -3030,7 +3066,7 @@ function checkMcpHookTargets(config, silent, adapter) {
     }
     let found;
     try {
-        found = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).mcpHookIssues;
+        found = (0, scan_js_1.scanPlugin)(scanRoot, adapter.layout, adapter.dialect).mcpHookIssues;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -3052,7 +3088,7 @@ function checkMcpHookTargets(config, silent, adapter) {
  * existence-guarded one-liners, inline commands). Matches Anthropic's own
  * `claude plugin validate`. Warning by default; "error" gates CI.
  */
-function checkHookScriptExists(config, silent, adapter) {
+function checkHookScriptExists(config, silent, adapter, scanRoot) {
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["hook-script-exists"]);
     if (!sev)
         return { issues: 0, errors: 0 };
@@ -3062,7 +3098,7 @@ function checkHookScriptExists(config, silent, adapter) {
     }
     let missing;
     try {
-        missing = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).hooks.filter((h) => h.status === "missing");
+        missing = (0, scan_js_1.scanPlugin)(scanRoot, adapter.layout, adapter.dialect).hooks.filter((h) => h.status === "missing");
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -3087,7 +3123,7 @@ function checkHookScriptExists(config, silent, adapter) {
  * — high-precision (gated on a declared set, built-ins allowlisted, the
  * plugin-namespaced form skipped). Warning by default; "error" gates CI.
  */
-function checkMcpToolResolves(config, silent, adapter) {
+function checkMcpToolResolves(config, silent, adapter, scanRoot) {
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["mcp-tool-resolves"]);
     if (!sev)
         return { issues: 0, errors: 0 };
@@ -3097,7 +3133,7 @@ function checkMcpToolResolves(config, silent, adapter) {
     }
     let found;
     try {
-        found = (0, scan_js_1.scanPlugin)(process.cwd(), adapter.layout, adapter.dialect).agents.flatMap((a) => a.mcpToolIssues.map((i) => ({ message: i.message, path: a.path })));
+        found = (0, scan_js_1.scanPlugin)(scanRoot, adapter.layout, adapter.dialect).agents.flatMap((a) => a.mcpToolIssues.map((i) => ({ message: i.message, path: a.path })));
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -5038,7 +5074,10 @@ async function main() {
                 const adapter = harnessFlag
                     ? (0, adapter_registry_js_1.resolveAdapter)(root, harnessFlag)
                     : det.adapter;
-                const report = (0, scan_js_1.scanPlugin)(targets[0], adapter.layout, adapter.dialect);
+                const report = (0, scan_js_1.scanPlugin)(targets[0], adapter.layout, adapter.dialect, {
+                    sharedDirs: config.sharedDirs,
+                    sharedDirsRoot: sharedDirsRootFor(targets[0]),
+                });
                 if (!json) {
                     console.log(`Detected harness: ${adapter.name}`);
                     if (!harnessFlag && det.ambiguousWith.length > 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/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/scan.d.ts

@@ -301,7 +301,10 @@ export declare function isManagedHookCommand(command: string): boolean;
 /** The `prefer-compiled-hooks` recommendation message (shared by `lint` + `scan`). */
 export declare function preferCompiledHooksMessage(count: number): string;
 /** Scan a plugin/repo directory and report its surfaces + structural issues. */
-export declare function scanPlugin(dir: string, layout?: PluginLayout, dialect?: HarnessDialect): ScanReport;
+export declare function scanPlugin(dir: string, layout?: PluginLayout, dialect?: HarnessDialect, opts?: {
+    sharedDirs?: readonly string[];
+    sharedDirsRoot?: string;
+}): ScanReport;
 /**
  * LIVE MCP tool resolution for a scanned plugin — the dynamic check no static
  * linter can do: it STARTS each declared MCP server and checks every

package/dist/scan.js

@@ -151,11 +151,18 @@ function onDiskPath(materializedKey, materializeRoot) {
         : materializedKey;
 }
 function scanSkills(files, cls, ctx) {
-    const { root, materializeRoot, dialect } = ctx;
+    const { root, materializeRoot, dialect, sharedDirs } = ctx;
+    // `sharedDirs` are declared relative to the REPO root (config location), which
+    // is `root` for a whole-repo scan but a PARENT when the scan is scoped to a
+    // subdir. Resolve them against that, not the scoped subdir.
+    const sharedDirsRoot = ctx.sharedDirsRoot ?? root;
     const out = [];
     for (const [path, md] of Object.entries(files)) {
         if (!cls.isSkill(path))
             continue;
+        // Prefer the real on-disk dir (a `.claude/skills/…` skill materializes under
+        // the same canonical key as a repo-root one, but lives elsewhere on disk).
+        const onDiskDir = ctx.sources?.[path];
         const fm = frontmatter(md);
         // A skill's trigger surface is its frontmatter `description` OR — when that's
         // absent — Claude Code's fallback to the first body paragraph. Only when
@@ -166,8 +173,18 @@ function scanSkills(files, cls, ctx) {
         // Bundled-resource refs resolve against the skill's OWN dir (resources ship
         // beside the SKILL.md), built from the plugin root + the file's ON-DISK dir
         // (the materialize-root prefix the loader added is stripped back off).
-        const skillDir = (0, node_path_1.resolve)(root, (0, node_path_1.dirname)(onDiskPath(path, materializeRoot)));
-        const resourceIssues = (0, skill_resources_js_1.skillResourceIssues)(skillBody(md), skillDir);
+        const skillDir = onDiskDir
+            ? (0, node_path_1.dirname)(onDiskDir)
+            : (0, node_path_1.resolve)(root, (0, node_path_1.dirname)(onDiskPath(path, materializeRoot)));
+        // Bundled refs resolve against the skill's OWN dir. A repo that shares a
+        // top-level tree across skills (`sharedDirs` in .vigilesrc.json) ALSO resolves
+        // a ref under one of those declared dirs against the repo root — OPT-IN, so a
+        // repo that doesn't set it is byte-identical to before (no masking of a real
+        // missing bundled resource). See feedback P1-4.
+        const resourceIssues = (0, skill_resources_js_1.skillResourceIssues)(skillBody(md), skillDir, {
+            repoRoot: sharedDirsRoot,
+            sharedDirs,
+        });
         // The lethal trifecta is a property of what a unit CAN do, which for a skill is
         // its declared `allowed-tools` (the CC skill tool contract). Only a model-
         // invocable skill can be hijacked by attacker content, so a user-invoked one is
@@ -702,7 +719,7 @@ function summarizePurity(agents) {
     }, { pure: 0, bounded: 0, unrestricted: 0 });
 }
 /** Scan a plugin/repo directory and report its surfaces + structural issues. */
-function scanPlugin(dir, layout, dialect = dialect_js_1.claudeCodeDialect) {
+function scanPlugin(dir, layout, dialect = dialect_js_1.claudeCodeDialect, opts = {}) {
     const lay = layout ?? layout_js_1.claudeCodeLayout;
     const cls = makeClassifier(lay);
     const loaded = (0, plugin_loader_js_1.loadPlugin)(dir, lay);
@@ -734,6 +751,9 @@ function scanPlugin(dir, layout, dialect = dialect_js_1.claudeCodeDialect) {
         root: (0, node_path_1.resolve)(dir),
         materializeRoot: lay.materializeRoot,
         dialect,
+        sources: loaded.sources,
+        sharedDirs: opts.sharedDirs,
+        sharedDirsRoot: opts.sharedDirsRoot,
     });
     const puritySummary = summarizePurity(agents);
     const { trifectaFindings, skillResourceFindings, skillFenceFindings } = collectSurfaceFindings(agents, skills);
@@ -958,7 +978,18 @@ function formatScanReport(r) {
     out.push(...section("MCP hook targets", r.mcpHookIssues.map((i) => `  ✗ ${i.message}`)));
     out.push(...section("Description overlap (precision risk)", r.descriptionOverlaps.map((o) => `  ⚠ ${o.message}`)));
     out.push(...section("Description budget (trigger-signal risk)", r.descriptionBudgetIssues.map((o) => `  ⚠ ${o.message}`)));
-    out.push(...section("Lethal trifecta (prompt-injection exfil risk)", r.trifectaFindings.map((t) => `  ${t.finding.severity === "hard" ? "✗" : "⚠"} ${t.kind} ${t.name} (${t.path}): ${t.finding.message}`)));
+    out.push(...section("Lethal trifecta (prompt-injection exfil risk)", 
+    // The section header already carries the count. HARD findings name their
+    // specific legs (keep the message). ADVISORY (inherits-all) findings all
+    // carry the SAME boilerplate paragraph — at bulk that's a wall of identical
+    // text, so collapse each to a one-liner (feedback P2-6). Gate on "no NEW
+    // trifecta" with `vigiles lint` (the lethal-trifecta rule), not by eyeballing.
+    r.trifectaFindings.map((t) => {
+        const mark = t.finding.severity === "hard" ? "✗" : "⚠";
+        return t.finding.severity === "hard"
+            ? `  ${mark} ${t.kind} ${t.name} (${t.path}): ${t.finding.message}`
+            : `  ${mark} ${t.kind} ${t.name} (${t.path}) — inherits-all contract holds all three legs (declare a tools list dropping one)`;
+    })));
     out.push(...section("Skill bundled resources", r.skillResourceIssues.map((s) => `  ✗ ${s.name}: ${s.finding.ref} (line ${String(s.finding.line)}) — bundled resource not found`)));
     out.push(...section("Invisible skills (missing frontmatter fence)", r.skillFenceIssues.map((s) => `  ✗ ${s.name} (${s.path}): opens with \`${s.finding.key}:\` but no \`---\` fence — loads as body, never fires`)));
     out.push(...section("Misplaced plugin directories", r.pluginLayoutIssues.map((p) => `  ✗ ${p.message}`)));

package/dist/test-coverage.js

@@ -86,6 +86,22 @@ function discoverSkills(basePath, ignore, layout) {
             ignored: content.includes(IGNORE_MARKER),
         });
     }
+    // Single-skill-directory target: a bare `SKILL.md` AT the base (the dir you
+    // pointed lint/audit at). The globs above only match `<skillDir>/*/SKILL.md`
+    // NESTED under the base, so without this the untested-skill check would silently
+    // vanish for exactly the single-skill target that scoping now supports.
+    const rootSkill = (0, node_path_1.join)(basePath, "SKILL.md");
+    if ((0, node_fs_1.existsSync)(rootSkill)) {
+        const name = (0, node_path_1.basename)(basePath);
+        const content = read(rootSkill);
+        out.push({
+            kind: "skill",
+            path: "SKILL.md",
+            name,
+            tokens: [`${layout.skillDir}/${name}`, `:${name}`],
+            ignored: content.includes(IGNORE_MARKER),
+        });
+    }
     return out;
 }
 function discoverAgents(basePath, ignore, layout) {
@@ -171,7 +187,13 @@ function discoverTests(basePath, globs, ignore) {
 /** Colocated: a test inside a skill dir, or a name-prefixed sibling of an agent/hook. */
 function isColocated(surface, testPath) {
     if (surface.kind === "skill") {
-        return testPath.startsWith(`${(0, node_path_1.dirname)(surface.path)}/`);
+        const dir = (0, node_path_1.dirname)(surface.path);
+        // A root `SKILL.md` (single-skill-dir target) lives at ".", so any TOP-LEVEL
+        // test is colocated — globSync returns those without a "./" prefix, which a
+        // bare `startsWith("./")` would miss (false "untested").
+        return dir === "."
+            ? (0, node_path_1.dirname)(testPath) === "."
+            : testPath.startsWith(`${dir}/`);
     }
     return ((0, node_path_1.dirname)(testPath) === (0, node_path_1.dirname)(surface.path) &&
         (0, node_path_1.basename)(testPath).startsWith(`${surface.name}.`));
@@ -223,10 +245,14 @@ function findUntestedSurfaces(options = {}) {
 }
 /** Suggested colocated test path for an untested surface (shown in the warning). */
 function suggestedTestPath(surface) {
+    // A root skill lives at ".", so drop the "./" prefix — the suggested path then
+    // matches what globSync actually discovers at the top level.
+    const dir = (0, node_path_1.dirname)(surface.path);
+    const prefix = dir === "." ? "" : `${dir}/`;
     if (surface.kind === "skill") {
-        return `${(0, node_path_1.dirname)(surface.path)}/${surface.name}.eval.mjs`;
+        return `${prefix}${surface.name}.eval.mjs`;
     }
-    return `${(0, node_path_1.dirname)(surface.path)}/${surface.name}.harness.mjs`;
+    return `${prefix}${surface.name}.harness.mjs`;
 }
 /** Format an untested-surface report as human-readable text. */
 function formatUntestedReport(report) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigiles",
-  "version": "12.6.0",
+  "version": "12.7.0",
   "description": "Lint & test the harness your AI agent runs on — verify the references in your CLAUDE.md / AGENTS.md and test that your hooks and skills actually work.",
   "keywords": [
     "claude-code",