vigiles 31.0.0 → 32.0.0

package/dist/cli-main.js

@@ -34,6 +34,7 @@ const setup_plan_js_1 = require("./setup-plan.js");
 const types_js_1 = require("./core/types.js");
 const test_coverage_js_1 = require("./test-coverage.js");
 const scan_js_1 = require("./scan.js");
+const frame_js_1 = require("./core/frame.js");
 const surface_discovery_js_1 = require("./core/surface-discovery.js");
 const scan_trigger_suggest_js_1 = require("./scan-trigger-suggest.js");
 const install_reader_js_1 = require("./core/install-reader.js");
@@ -630,6 +631,13 @@ function isGitHubActions() {
 /**
  * Emit a GitHub Actions annotation for the inline PR experience.
  * No-op outside GitHub Actions.
+ *
+ * `file` is a {@link RepoPath}, not a `string`, and that is the #281 fix made
+ * structural: GitHub resolves `file=` against the checked-out repository, so a
+ * path relative to a nested bundle (`skills/x/SKILL.md` for
+ * `plugins/p/skills/x/SKILL.md`) or an absolute machine path lands on a missing
+ * file — or, worse, on the ROOT bundle's file of the same name. Such a path no
+ * longer compiles here; it has to go through `core/frame.ts` first.
  */
 function ghAnnotate(level, message, file, line) {
     if (!isGitHubActions())
@@ -642,7 +650,7 @@ function ghAnnotate(level, message, file, line) {
     const loc = locParts.length > 0 ? " " + locParts.join(",") : "";
     console.log(`::${level}${loc}::${message}`);
 }
-function verifyHashes(filePaths, silent = false) {
+function verifyHashes(frame, filePaths, silent = false) {
     let errorCount = 0;
     const log = (msg) => {
         if (!silent)
@@ -656,7 +664,7 @@ function verifyHashes(filePaths, silent = false) {
         if (!(0, node_fs_1.existsSync)(fullPath)) {
             log(`\n✗ ${filePath} — file not found`);
             if (!silent) {
-                ghAnnotate("error", `File not found: ${filePath}`, filePath);
+                ghAnnotate("error", `File not found: ${filePath}`, frame.repo(fullPath));
             }
             errorCount++;
             continue;
@@ -673,7 +681,7 @@ function verifyHashes(filePaths, silent = false) {
         log(`\n✗ ${filePath} — hash mismatch (manually edited after compilation)`);
         log(`  Re-run \`vigiles compile\` to regenerate from ${result.specFile ?? "spec"}.`);
         if (!silent) {
-            ghAnnotate("error", "Hash mismatch — file was manually edited after compilation", filePath);
+            ghAnnotate("error", "Hash mismatch — file was manually edited after compilation", frame.repo(fullPath));
         }
         errorCount++;
     }
@@ -720,8 +728,8 @@ function validateSpecs(filePaths, rulesConfig, silent = false) {
     }
     return allValid;
 }
-function check(filePaths, silent = false) {
-    const hashes = verifyHashes(filePaths, silent);
+function check(frame, filePaths, silent = false) {
+    const hashes = verifyHashes(frame, filePaths, silent);
     const vConfig = (0, validate_js_1.loadConfig)();
     const specsValid = validateSpecs(filePaths, vConfig.rules, silent);
     return {
@@ -821,7 +829,7 @@ async function findDuplicateRules(excludes, threshold = 0.3, silent = false, sco
  * Each named file is parsed on demand; there is no project-wide index. Returns
  * the count of broken references.
  */
-async function verifyMarkdownSymbols(files, silent) {
+async function verifyMarkdownSymbols(frame, files, silent) {
     if (files.length === 0)
         return 0;
     const cwd = process.cwd();
@@ -845,7 +853,7 @@ async function verifyMarkdownSymbols(files, silent) {
             }
             for (const b of broken) {
                 console.log(`  ✗ ${f}:${String(b.line)} ${b.reason}`);
-                ghAnnotate("error", b.reason, f, b.line);
+                ghAnnotate("error", b.reason, frame.repo((0, node_path_1.resolve)(cwd, f)), b.line);
             }
         }
         errors += broken.length;
@@ -859,7 +867,7 @@ async function verifyMarkdownSymbols(files, silent) {
  * only started if a mark actually references it. Returns the count of broken
  * references. Async because it speaks to real servers.
  */
-async function verifyMarkdownMcpRefs(files, silent) {
+async function verifyMarkdownMcpRefs(frame, files, silent) {
     const cwd = process.cwd();
     const servers = (0, mcp_js_1.loadMcpServers)(cwd);
     if (files.length === 0 || Object.keys(servers).length === 0)
@@ -885,7 +893,7 @@ async function verifyMarkdownMcpRefs(files, silent) {
             for (const b of broken) {
                 const msg = (0, mcp_js_1.mcpRefMessage)(b);
                 console.log(`  ✗ ${f}:${String(b.line)} ${msg}`);
-                ghAnnotate("error", msg, f, b.line);
+                ghAnnotate("error", msg, frame.repo((0, node_path_1.resolve)(cwd, f)), b.line);
             }
         }
         errors += broken.length;
@@ -993,7 +1001,7 @@ function lintExitCode(report) {
  * Verify one parsed enforce rule against the linter catalog/config, logging
  * and annotating on failure. Returns true when the rule is valid+enabled.
  */
-function verifyOneRule(rule, filePath, silent, linterOptions) {
+function verifyOneRule(frame, rule, filePath, silent, linterOptions) {
     const log = (msg) => {
         if (!silent)
             console.log(msg);
@@ -1003,14 +1011,14 @@ function verifyOneRule(rule, filePath, silent, linterOptions) {
         const message = result.error ?? `Rule "${rule.linterRule}" not found`;
         log(`  ✗ line ${String(rule.line)}: ${message}`);
         if (!silent)
-            ghAnnotate("error", message, filePath, rule.line);
+            ghAnnotate("error", message, frame.repo((0, node_path_1.resolve)(process.cwd(), filePath)), rule.line);
         return false;
     }
     if (result.enabled === "disabled") {
         const message = `Rule "${rule.linterRule}" exists but is disabled in ${result.linter} config`;
         log(`  ✗ line ${String(rule.line)}: ${message}`);
         if (!silent)
-            ghAnnotate("error", message, filePath, rule.line);
+            ghAnnotate("error", message, frame.repo((0, node_path_1.resolve)(process.cwd(), filePath)), rule.line);
         return false;
     }
     log(`  ✓ line ${String(rule.line)}: ${rule.linterRule}`);
@@ -1023,13 +1031,13 @@ function verifyOneRule(rule, filePath, silent, linterOptions) {
  * package.json / the filesystem. References resolve relative to the markdown
  * file's own directory. Returns the number of stale references found.
  */
-function verifyMarkdownRefs(files, commands, filePath, silent) {
+function verifyMarkdownRefs(frame, files, commands, filePath, silent) {
     const basePath = (0, node_path_1.dirname)((0, node_path_1.resolve)(process.cwd(), filePath));
     let errorCount = 0;
     const report = (err, line) => {
         if (!silent) {
             console.log(`  ✗ line ${String(line)}: ${err.message}`);
-            ghAnnotate("error", err.message, filePath, line);
+            ghAnnotate("error", err.message, frame.repo((0, node_path_1.resolve)(process.cwd(), filePath)), line);
         }
         errorCount++;
     };
@@ -1045,7 +1053,7 @@ function verifyMarkdownRefs(files, commands, filePath, silent) {
     }
     return errorCount;
 }
-function verifyInlineRules(filePath, silent, linterOptions) {
+function verifyInlineRules(frame, filePath, silent, linterOptions) {
     const log = (msg) => {
         if (!silent)
             console.log(msg);
@@ -1070,14 +1078,14 @@ function verifyInlineRules(filePath, silent, linterOptions) {
         log(`  ✗ line ${String(err.line)}: ${err.message}`);
         errorCount++;
         if (!silent) {
-            ghAnnotate("error", err.message, filePath, err.line);
+            ghAnnotate("error", err.message, frame.repo((0, node_path_1.resolve)(process.cwd(), filePath)), err.line);
         }
     }
     for (const rule of rules) {
-        if (!verifyOneRule(rule, filePath, silent, linterOptions))
+        if (!verifyOneRule(frame, rule, filePath, silent, linterOptions))
             errorCount++;
     }
-    errorCount += verifyMarkdownRefs(files, commands, filePath, silent);
+    errorCount += verifyMarkdownRefs(frame, files, commands, filePath, silent);
     return {
         ok: errorCount === 0,
         errorCount,
@@ -1091,7 +1099,7 @@ function verifyInlineRules(filePath, silent, linterOptions) {
  * in `exclude` (e.g. declared inline in the same file) are skipped so a
  * rule present in both sources is reported once, not twice.
  */
-function verifyFrontmatterRules(filePath, silent, exclude, linterOptions) {
+function verifyFrontmatterRules(frame, filePath, silent, exclude, linterOptions) {
     const log = (msg) => {
         if (!silent)
             console.log(msg);
@@ -1117,14 +1125,14 @@ function verifyFrontmatterRules(filePath, silent, exclude, linterOptions) {
         log(`  ✗ line ${String(err.line)}: ${err.message}`);
         errorCount++;
         if (!silent) {
-            ghAnnotate("error", err.message, filePath, err.line);
+            ghAnnotate("error", err.message, frame.repo((0, node_path_1.resolve)(process.cwd(), filePath)), err.line);
         }
     }
     for (const rule of rules) {
-        if (!verifyOneRule(rule, filePath, silent, linterOptions))
+        if (!verifyOneRule(frame, rule, filePath, silent, linterOptions))
             errorCount++;
     }
-    errorCount += verifyMarkdownRefs(files, commands, filePath, silent);
+    errorCount += verifyMarkdownRefs(frame, files, commands, filePath, silent);
     return {
         ok: errorCount === 0,
         errorCount,
@@ -1162,7 +1170,7 @@ const FRONTMATTER_MODE_ENABLED = false;
  * declared both inline and in frontmatter is verified once (inline wins as
  * the first source). See docs/markdown-mode.md.
  */
-function verifyMarkdownModeRules(files, silent, config) {
+function verifyMarkdownModeRules(frame, files, silent, config) {
     const totals = {
         inlineErrors: 0,
         inlineRules: 0,
@@ -1190,13 +1198,13 @@ function verifyMarkdownModeRules(files, silent, config) {
         }
         if (compiledFromRe.test(content))
             continue; // managed via hash header
-        const inline = verifyInlineRules(filePath, silent, linterOptions);
+        const inline = verifyInlineRules(frame, filePath, silent, linterOptions);
         totals.inlineErrors += inline.errorCount;
         totals.inlineRules += inline.ruleCount;
         // Frontmatter mode is DISABLED (kept in code, inert in lint) — a `vigiles:`
         // block is ignored, never verified. See FRONTMATTER_MODE_ENABLED.
         if (FRONTMATTER_MODE_ENABLED) {
-            const fm = verifyFrontmatterRules(filePath, silent, new Set(inline.ruleNames), linterOptions);
+            const fm = verifyFrontmatterRules(frame, filePath, silent, new Set(inline.ruleNames), linterOptions);
             totals.frontmatterErrors += fm.errorCount;
             totals.frontmatterRules += fm.ruleCount;
         }
@@ -1217,21 +1225,6 @@ 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;
-}
 /**
  * Nested plugin bundles under a lint root — a directory that is itself a harness
  * (its own `.claude-plugin/plugin.json`, or its own skills dir) and is NOT the
@@ -1303,21 +1296,39 @@ function discoverNestedBundles(root, excludes) {
     return out.sort();
 }
 /**
- * Run one per-surface check over EVERY root and sum its counters.
+ * Run one per-surface check over EVERY bundle and sum its counters.
  *
- * The checks all share `(config, silent, adapter, root)` and return a small
- * record of numbers, so one wrapper covers all twenty rather than twenty edits —
- * and a check added later is swept in by using it, not by remembering to.
+ * The checks all take a {@link BundleCheck} and return a small record of
+ * numbers, so one wrapper covers all of them rather than twenty edits — and a
+ * check added later is swept in by using it, not by remembering to. The first
+ * bundle is the lint target; the rest are nested bundles.
  */
-function overBundles(fn, config, silent, adapter, roots) {
-    const [first, ...rest] = roots;
-    const total = { ...fn(config, silent, adapter, first) };
-    for (const root of rest) {
-        const next = fn(config, silent, adapter, root);
+function overBundles(fn, run, bundles) {
+    const many = bundles.length > 1;
+    const ctxFor = (abs, i) => {
+        const bundle = run.frame.bundle(abs);
+        const label = (text) => many && i > 0 ? `[${bundle.at}] ${text}` : text;
+        return {
+            ...run,
+            bundle,
+            label,
+            annotate: (level, message, file) => {
+                ghAnnotate(level, file === undefined ? label(message) : message, file);
+            },
+            scan: (extra = {}) => (0, scan_js_1.scanPlugin)(bundle.abs, run.adapter.layout, run.adapter.dialect, {
+                ...extra,
+                excludes: run.excludes,
+            }),
+        };
+    };
+    const [first, ...rest] = bundles;
+    const total = { ...fn(ctxFor(first, 0)) };
+    rest.forEach((abs, i) => {
+        const next = fn(ctxFor(abs, i + 1));
         for (const key of Object.keys(next))
             total[key] =
                 (total[key] ?? 0) + (next[key] ?? 0);
-    }
+    });
     return total;
 }
 /**
@@ -1485,6 +1496,11 @@ async function runLint(restArgs, flags, excludes, config) {
     const nestedBundles = discoverNestedBundles(scanRoot, excludes);
     const scoreAll = flags.includes("--bundles=all") || config?.bundles === "all";
     const lintRoots = scoreAll ? [scanRoot, ...nestedBundles] : [scanRoot];
+    // ONE frame for the whole run (#281): every path a check prints or annotates is
+    // relative to it, and config globs resolve from it — whichever bundle is being
+    // scored. Built here, once, instead of each option re-deriving its own root.
+    const frame = (0, frame_js_1.frameFor)(process.cwd(), scanRoot);
+    const run = { config, silent, adapter, excludes, frame };
     if (!silent && nestedBundles.length > 0) {
         const rel = nestedBundles.map((b) => (0, node_path_1.relative)(scanRoot, b) || b);
         console.log(scoreAll
@@ -1510,11 +1526,11 @@ async function runLint(restArgs, flags, excludes, config) {
         }
     }
     const hashResult = files.length > 0
-        ? check(files, silent)
+        ? check(frame, files, silent)
         : { valid: true, hashErrors: 0, validationErrors: 0 };
     // 1b. Verify inline + frontmatter rules in instruction files not managed
     // by a spec. See verifyMarkdownModeRules / docs/markdown-mode.md.
-    const md = verifyMarkdownModeRules(files, silent, config);
+    const md = verifyMarkdownModeRules(frame, files, silent, config);
     const { inlineErrors, inlineRules, frontmatterErrors, frontmatterRules } = md;
     // 2. Coverage gaps (discover)
     if (!silent)
@@ -1570,7 +1586,7 @@ async function runLint(restArgs, flags, excludes, config) {
             // The repo-wide `exclude` is the FLOOR under the rule's own `exclude`
             // (union, never override): an excluded corpus is neither an orphan
             // candidate nor a source of references that keep a doc alive (#192).
-            repoExclude: excludes.ignore,
+            repoExclude: excludes.globIgnore,
             // Exempt every registered harness's surface files (instruction file,
             // SKILL.md, subagents, commands) as orphan candidates — layout-driven so
             // core carries no harness literal (see src/core/orphans.ts).
@@ -1591,74 +1607,74 @@ async function runLint(restArgs, flags, excludes, config) {
     // A compiled artifact's refs, re-derived from its spec — the hash says the file
     // is unchanged, not that what it names still exists (#173).
     const specRefs = await checkSpecRefs(excludes, config, silent, adapter.dialect);
-    const untested = overBundles((c, s, a, r) => checkUntestedSurfaces(excludes, c, s, a, r), config, silent, adapter, lintRoots);
+    const untested = overBundles(checkUntestedSurfaces, run, lintRoots);
     // 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 = overBundles(checkSubagentToolContracts, config, silent, adapter, lintRoots);
+    const toolContract = overBundles(checkSubagentToolContracts, run, lintRoots);
     // 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 = overBundles(checkHookEvents, config, silent, adapter, lintRoots);
+    const hookEvents = overBundles(checkHookEvents, run, lintRoots);
     // 7e. Subagent-frontmatter check — a subagent missing required frontmatter
     // (name + description) won't register. n/a on a harness with no subagents.
-    const frontmatter = overBundles(checkFrontmatterSchema, config, silent, adapter, lintRoots);
+    const frontmatter = overBundles(checkFrontmatterSchema, run, lintRoots);
     // 7f. MCP-config check — a declared MCP server with no command/url can't start.
-    const mcpConfig = overBundles(checkMcpConfig, config, silent, adapter, lintRoots);
+    const mcpConfig = overBundles(checkMcpConfig, run, lintRoots);
     // 7g. Skill-frontmatter — RECOMMEND explicit name/description on skills (a
     // reliable trigger surface). Best-practice nudge; skills load without it.
-    const skillFm = overBundles(checkSkillFrontmatter, config, silent, adapter, lintRoots);
+    const skillFm = overBundles(checkSkillFrontmatter, run, lintRoots);
     // 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 = overBundles(checkMcpToolResolves, config, silent, adapter, lintRoots);
+    const mcpToolResolves = overBundles(checkMcpToolResolves, run, lintRoots);
     // 7i. Hook-script existence — a hook command referencing a missing script file
     // never runs. This comment used to add "matches Anthropic's own `claude plugin
     // validate`"; measured false on 2026-09-08 (Claude Code 2.1.263) — see
     // docs/rules/hook-script-exists.md and tools/measure-validate-overlap.mjs.
-    const hookScripts = overBundles(checkHookScriptExists, config, silent, adapter, lintRoots);
+    const hookScripts = overBundles(checkHookScriptExists, run, lintRoots);
     // 7j. Disallowed-tools — a `disallowedTools:` block-list typo blocks nothing
     // (the deny-side mirror of subagent-tool-contract; close-typo only).
-    const disallowedTools = overBundles(checkDisallowedTools, config, silent, adapter, lintRoots);
+    const disallowedTools = overBundles(checkDisallowedTools, run, lintRoots);
     // 7k. Description-overlap — two model-invocable skills with near-identical
     // descriptions collide in the selector (deterministic NCD precision proxy).
-    const descriptionOverlap = overBundles(checkDescriptionOverlap, config, silent, adapter, lintRoots);
+    const descriptionOverlap = overBundles(checkDescriptionOverlap, run, lintRoots);
     // 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 = overBundles(checkDescriptionBudget, config, silent, adapter, lintRoots);
+    const descriptionBudget = overBundles(checkDescriptionBudget, run, lintRoots);
     // 7l. Frontmatter-valid — a `---` block that isn't valid YAML (warn; js-yaml is
     // stricter than some loaders, so verify before enforcing).
-    const frontmatterValid = overBundles(checkFrontmatterValid, config, silent, adapter, lintRoots);
+    const frontmatterValid = overBundles(checkFrontmatterValid, run, lintRoots);
     // 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 = overBundles(checkMcpHookTargets, config, silent, adapter, lintRoots);
+    const mcpHookTargets = overBundles(checkMcpHookTargets, run, lintRoots);
     // 7n. Prefer-compiled-hooks — ONE discovery nudge (not per-hook) toward
     // compiled `vigiles/hook` artifacts when hand-written hooks ship. Recommendation.
-    const preferCompiledHooks = overBundles(checkPreferCompiledHooks, config, silent, adapter, lintRoots);
+    const preferCompiledHooks = overBundles(checkPreferCompiledHooks, run, lintRoots);
     // 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 = overBundles(checkLethalTrifecta, config, silent, adapter, lintRoots);
+    const lethalTrifecta = overBundles(checkLethalTrifecta, run, lintRoots);
     // 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 = overBundles(checkSkillResourceResolves, config, silent, adapter, lintRoots);
+    const skillResources = overBundles(checkSkillResourceResolves, run, lintRoots);
     // 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 = overBundles(checkSkillMissingFence, config, silent, adapter, lintRoots);
+    const skillFence = overBundles(checkSkillMissingFence, run, lintRoots);
     // 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 = overBundles(checkPluginDirLayout, config, silent, adapter, lintRoots);
+    const pluginLayout = overBundles(checkPluginDirLayout, run, lintRoots);
     // 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 = overBundles(checkDelegationTrifecta, config, silent, adapter, lintRoots);
+    const delegationTrifecta = overBundles(checkDelegationTrifecta, run, lintRoots);
     // 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 = overBundles(checkHookBlockIneffective, config, silent, adapter, lintRoots);
+    const hookBlock = overBundles(checkHookBlockIneffective, run, lintRoots);
     // 7u. Hook-matcher — a hook `matcher` that doesn't fire as written (tool-name
     // typo, an uncompilable or unreachable MCP pattern, one too narrow for real
     // server naming, or an undeclared MCP server).
-    const hookMatcher = overBundles(checkHookMatcher, config, silent, adapter, lintRoots);
+    const hookMatcher = overBundles(checkHookMatcher, run, lintRoots);
     // 8. Validate vigiles builder calls inside markdown code blocks — the
     // `doc-refs` rule, DEFAULT OFF. Illustrative blocks opt out via
     // `<!-- vigiles:ignore -->` (single block) or `<!-- vigiles:ignore-file -->`
@@ -1696,7 +1712,7 @@ async function runLint(restArgs, flags, excludes, config) {
     // whose exit code is discarded gates nothing — after which hand-written CI steps
     // grew to do the gating instead. One unpassed argument, that whole chain.
     const docRefReport = docRefSeverity
-        ? (0, doc_refs_js_1.findDocRefs)({ basePath: process.cwd(), ignore: excludes.ignore })
+        ? (0, doc_refs_js_1.findDocRefs)({ basePath: process.cwd(), ignore: excludes.globIgnore })
         : {
             filesScanned: 0,
             filesIgnored: 0,
@@ -1719,14 +1735,14 @@ async function runLint(restArgs, flags, excludes, config) {
     // on the PR. CI-only (isGitHubActions); skipped under --json/--summary.
     if (isGitHubActions() && !silent && docRefSeverity) {
         for (const e of docRefReport.errors) {
-            ghAnnotate(docRefSeverity === "error" ? "error" : "warning", `${e.kind}("${e.value}") — ${e.message}`, e.file, e.line);
+            ghAnnotate(docRefSeverity === "error" ? "error" : "warning", `${e.kind}("${e.value}") — ${e.message}`, frame.repo((0, node_path_1.resolve)(process.cwd(), e.file)), e.line);
         }
     }
     // 9. Verify code-shaped symbol references live (see src/refs.ts).
-    const symbolRefErrors = await verifyMarkdownSymbols(files, silent);
+    const symbolRefErrors = await verifyMarkdownSymbols(frame, files, silent);
     // 10. Verify `vigiles:mcp server#tool` marks against live MCP servers
     // (only when a .mcp.json declares them). See src/mcp.ts.
-    const mcpRefErrors = await verifyMarkdownMcpRefs(files, silent);
+    const mcpRefErrors = await verifyMarkdownMcpRefs(frame, files, silent);
     const report = {
         hashErrors: hashResult.hashErrors,
         validationErrors: hashResult.validationErrors,
@@ -3605,18 +3621,22 @@ function untestedRules(config) {
  * "warn" prints but never fails CI; "error" fails (exit 2). Returns the raw
  * untested count plus the severity-gated error count.
  */
-function checkUntestedSurfaces(excludes, config, silent, adapter, scanRoot) {
+function checkUntestedSurfaces(ctx) {
+    const { config, silent, adapter, frame, bundle } = ctx;
     const { severity: sevFor, anyEnabled, options } = untestedRules(config);
     if (!anyEnabled)
         return { untested: 0, errors: 0 };
     const report = (0, test_coverage_js_1.findUntestedSurfaces)({
         ...options,
-        basePath: scanRoot,
+        basePath: bundle.abs,
+        // #281: `include`/`exclude` and every reported path are relative to the
+        // frame root (where `.vigilesrc.json` lives), not to the bundle being scored.
+        root: frame.root,
         layout: adapter.layout,
         // The rule's own `exclude` NARROWS; the repo-wide one is the floor under
         // it. Union, never override — a rule option must not re-admit a vendored
-        // corpus the repo excluded (#192).
-        exclude: [...(options.exclude ?? []), ...excludes.ignore],
+        // corpus the repo excluded (#192). Passed WHOLE so it carries its own root.
+        excludes: ctx.excludes,
     });
     if (!silent) {
         console.log("\nUntested surfaces:\n");
@@ -3624,7 +3644,7 @@ function checkUntestedSurfaces(excludes, config, silent, adapter, scanRoot) {
             console.log(`  ${line}`);
         }
         for (const s of report.untested) {
-            ghAnnotate(sevFor(s.kind) === "error" ? "error" : "warning", `${s.kind} ${s.path} ships without a test or eval`, s.path);
+            ctx.annotate(sevFor(s.kind) === "error" ? "error" : "warning", `${s.kind} ${s.path} ships without a test or eval`, frame.repo((0, node_path_1.join)(frame.root, s.path)));
         }
     }
     return {
@@ -3653,7 +3673,8 @@ 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, scanRoot) {
+function checkSubagentToolContracts(ctx) {
+    const { config, silent, adapter } = ctx;
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["subagent-tool-contract"]);
     if (!sev)
         return { issues: 0, errors: 0 };
@@ -3666,7 +3687,7 @@ function checkSubagentToolContracts(config, silent, adapter, scanRoot) {
     // `agents/` path, so a harness with a different subagent dir Just Works.
     let agents;
     try {
-        agents = (0, scan_js_1.scanPlugin)(scanRoot, adapter.layout, adapter.dialect).agents;
+        agents = ctx.scan().agents;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -3683,8 +3704,8 @@ function checkSubagentToolContracts(config, silent, adapter, scanRoot) {
                 printedHeader = true;
             }
             for (const issue of agent.toolIssues) {
-                console.log(`  ${sev === "error" ? "✗" : "⚠"} ${agent.path}: ${issue.message}`);
-                ghAnnotate(sev === "error" ? "error" : "warning", issue.message, agent.path);
+                console.log(`  ${sev === "error" ? "✗" : "⚠"} ${ctx.bundle.scanned(agent.path)}: ${issue.message}`);
+                ctx.annotate(sev === "error" ? "error" : "warning", issue.message, ctx.bundle.scanned(agent.path));
             }
         }
     }
@@ -3696,7 +3717,8 @@ function checkSubagentToolContracts(config, silent, adapter, scanRoot) {
  * `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, scanRoot) {
+function checkHookEvents(ctx) {
+    const { config, silent, adapter } = ctx;
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["hook-events"]);
     if (!sev)
         return { issues: 0, errors: 0 };
@@ -3706,7 +3728,7 @@ function checkHookEvents(config, silent, adapter, scanRoot) {
     }
     let found;
     try {
-        found = (0, scan_js_1.scanPlugin)(scanRoot, adapter.layout, adapter.dialect).hookEventIssues;
+        found = ctx.scan().hookEventIssues;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -3714,8 +3736,8 @@ function checkHookEvents(config, silent, adapter, scanRoot) {
     if (found.length > 0 && !silent) {
         console.log("\nHook-event check:\n");
         for (const issue of found) {
-            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${issue.message}`);
-            ghAnnotate(sev === "error" ? "error" : "warning", issue.message);
+            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${ctx.label(issue.message)}`);
+            ctx.annotate(sev === "error" ? "error" : "warning", issue.message);
         }
     }
     return { issues: found.length, errors: sev === "error" ? found.length : 0 };
@@ -3727,7 +3749,8 @@ function checkHookEvents(config, silent, adapter, scanRoot) {
  * 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, scanRoot) {
+function checkFrontmatterSchema(ctx) {
+    const { config, silent, adapter } = ctx;
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["subagent-frontmatter"]);
     if (!sev)
         return { issues: 0, errors: 0 };
@@ -3737,7 +3760,7 @@ function checkFrontmatterSchema(config, silent, adapter, scanRoot) {
     }
     let found;
     try {
-        const r = (0, scan_js_1.scanPlugin)(scanRoot, adapter.layout, adapter.dialect);
+        const r = ctx.scan();
         found = [...r.frontmatterIssues, ...r.frontmatterValueIssues];
     }
     catch {
@@ -3746,8 +3769,8 @@ function checkFrontmatterSchema(config, silent, adapter, scanRoot) {
     if (found.length > 0 && !silent) {
         console.log("\nFrontmatter-schema check:\n");
         for (const issue of found) {
-            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${issue.message}`);
-            ghAnnotate(sev === "error" ? "error" : "warning", issue.message, issue.path);
+            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${ctx.label(issue.message)}`);
+            ctx.annotate(sev === "error" ? "error" : "warning", issue.message, ctx.bundle.scanned(issue.path));
         }
     }
     return { issues: found.length, errors: sev === "error" ? found.length : 0 };
@@ -3760,13 +3783,14 @@ function checkFrontmatterSchema(config, silent, adapter, scanRoot) {
  * default; set "error" to enforce it on your own skills. Reuses `scanPlugin`'s
  * `skillMetaIssues`.
  */
-function checkSkillFrontmatter(config, silent, adapter, scanRoot) {
+function checkSkillFrontmatter(ctx) {
+    const { config, silent } = ctx;
     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)(scanRoot, adapter.layout, adapter.dialect).skillMetaIssues;
+        found = ctx.scan().skillMetaIssues;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -3774,8 +3798,8 @@ function checkSkillFrontmatter(config, silent, adapter, scanRoot) {
     if (found.length > 0 && !silent) {
         console.log("\nSkill-frontmatter check:\n");
         for (const issue of found) {
-            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${issue.message}`);
-            ghAnnotate(sev === "error" ? "error" : "warning", issue.message, issue.path);
+            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${ctx.label(issue.message)}`);
+            ctx.annotate(sev === "error" ? "error" : "warning", issue.message, ctx.bundle.scanned(issue.path));
         }
     }
     return { issues: found.length, errors: sev === "error" ? found.length : 0 };
@@ -3787,13 +3811,14 @@ function checkSkillFrontmatter(config, silent, adapter, scanRoot) {
  * 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, scanRoot) {
+function checkPreferCompiledHooks(ctx) {
+    const { config, silent } = ctx;
     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)(scanRoot, adapter.layout, adapter.dialect).manualHookCount;
+        count = ctx.scan().manualHookCount;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -3803,8 +3828,8 @@ function checkPreferCompiledHooks(config, silent, adapter, scanRoot) {
     const message = (0, scan_js_1.preferCompiledHooksMessage)(count);
     if (!silent) {
         console.log("\nCompiled-hooks check:\n");
-        console.log(`  ${sev === "error" ? "✗" : "ℹ"} ${message}`);
-        ghAnnotate(sev === "error" ? "error" : "warning", message);
+        console.log(`  ${sev === "error" ? "✗" : "ℹ"} ${ctx.label(message)}`);
+        ctx.annotate(sev === "error" ? "error" : "warning", message);
     }
     return { issues: 1, errors: sev === "error" ? 1 : 0 };
 }
@@ -3813,13 +3838,14 @@ function checkPreferCompiledHooks(config, silent, adapter, scanRoot) {
  * (stdio) nor a `url` (http/sse) can't start. Reuses `scanPlugin`'s `mcpIssues`.
  * Warning by default; "error" gates CI.
  */
-function checkMcpConfig(config, silent, adapter, scanRoot) {
+function checkMcpConfig(ctx) {
+    const { config, silent } = ctx;
     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)(scanRoot, adapter.layout, adapter.dialect).mcpIssues;
+        found = ctx.scan().mcpIssues;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -3827,8 +3853,8 @@ function checkMcpConfig(config, silent, adapter, scanRoot) {
     if (found.length > 0 && !silent) {
         console.log("\nMCP-config check:\n");
         for (const issue of found) {
-            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${issue.message}`);
-            ghAnnotate(sev === "error" ? "error" : "warning", issue.message);
+            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${ctx.label(issue.message)}`);
+            ctx.annotate(sev === "error" ? "error" : "warning", issue.message);
         }
     }
     return { issues: found.length, errors: sev === "error" ? found.length : 0 };
@@ -3840,7 +3866,8 @@ function checkMcpConfig(config, silent, adapter, scanRoot) {
  * `disallowedToolIssues` (close-typo only — high-precision). Warning by default;
  * "error" gates CI.
  */
-function checkDisallowedTools(config, silent, adapter, scanRoot) {
+function checkDisallowedTools(ctx) {
+    const { config, silent, adapter } = ctx;
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["disallowed-tools-contract"]);
     if (!sev)
         return { issues: 0, errors: 0 };
@@ -3850,7 +3877,10 @@ function checkDisallowedTools(config, silent, adapter, scanRoot) {
     }
     let found;
     try {
-        found = (0, scan_js_1.scanPlugin)(scanRoot, adapter.layout, adapter.dialect).agents.flatMap((a) => a.disallowedToolIssues.map((i) => ({ message: i.message, path: a.path })));
+        found = ctx.scan().agents.flatMap((a) => a.disallowedToolIssues.map((i) => ({
+            message: i.message,
+            path: a.path,
+        })));
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -3858,8 +3888,8 @@ function checkDisallowedTools(config, silent, adapter, scanRoot) {
     if (found.length > 0 && !silent) {
         console.log("\nDisallowed-tools check:\n");
         for (const issue of found) {
-            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${issue.path}: ${issue.message}`);
-            ghAnnotate(sev === "error" ? "error" : "warning", issue.message, issue.path);
+            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${ctx.bundle.scanned(issue.path)}: ${issue.message}`);
+            ctx.annotate(sev === "error" ? "error" : "warning", issue.message, ctx.bundle.scanned(issue.path));
         }
     }
     return { issues: found.length, errors: sev === "error" ? found.length : 0 };
@@ -3872,13 +3902,14 @@ function checkDisallowedTools(config, silent, adapter, scanRoot) {
  * colon / `<example>` is flagged though it may still load — hence WARN by default
  * (verify before setting "error").
  */
-function checkFrontmatterValid(config, silent, adapter, scanRoot) {
+function checkFrontmatterValid(ctx) {
+    const { config, silent } = ctx;
     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)(scanRoot, adapter.layout, adapter.dialect).malformedFrontmatter;
+        found = ctx.scan().malformedFrontmatter;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -3886,8 +3917,8 @@ function checkFrontmatterValid(config, silent, adapter, scanRoot) {
     if (found.length > 0 && !silent) {
         console.log("\nFrontmatter-validity check:\n");
         for (const issue of found) {
-            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${issue.message}`);
-            ghAnnotate(sev === "error" ? "error" : "warning", issue.message, issue.path);
+            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${ctx.label(issue.message)}`);
+            ctx.annotate(sev === "error" ? "error" : "warning", issue.message, ctx.bundle.scanned(issue.path));
         }
     }
     return { issues: found.length, errors: sev === "error" ? found.length : 0 };
@@ -3899,13 +3930,14 @@ function checkFrontmatterValid(config, silent, adapter, scanRoot) {
  * `scanPlugin`'s `descriptionOverlaps` (calibrated FP-safe: only basically
  * identical text). Warning by default; "error" gates CI.
  */
-function checkDescriptionOverlap(config, silent, adapter, scanRoot) {
+function checkDescriptionOverlap(ctx) {
+    const { config, silent } = ctx;
     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)(scanRoot, adapter.layout, adapter.dialect).descriptionOverlaps;
+        found = ctx.scan().descriptionOverlaps;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -3913,8 +3945,8 @@ function checkDescriptionOverlap(config, silent, adapter, scanRoot) {
     if (found.length > 0 && !silent) {
         console.log("\nDescription-overlap check:\n");
         for (const issue of found) {
-            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${issue.message}`);
-            ghAnnotate(sev === "error" ? "error" : "warning", issue.message);
+            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${ctx.label(issue.message)}`);
+            ctx.annotate(sev === "error" ? "error" : "warning", issue.message);
         }
     }
     return { issues: found.length, errors: sev === "error" ? found.length : 0 };
@@ -3926,13 +3958,14 @@ function checkDescriptionOverlap(config, silent, adapter, scanRoot) {
  * deterministic heuristic proxy (generous 500-char budget). Reuses `scanPlugin`'s
  * `descriptionBudgetIssues`. Warning by default; "error" gates CI.
  */
-function checkDescriptionBudget(config, silent, adapter, scanRoot) {
+function checkDescriptionBudget(ctx) {
+    const { config, silent } = ctx;
     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)(scanRoot, adapter.layout, adapter.dialect).descriptionBudgetIssues;
+        found = ctx.scan().descriptionBudgetIssues;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -3940,8 +3973,8 @@ function checkDescriptionBudget(config, silent, adapter, scanRoot) {
     if (found.length > 0 && !silent) {
         console.log("\nSkill-description-budget check:\n");
         for (const issue of found) {
-            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${issue.message}`);
-            ghAnnotate(sev === "error" ? "error" : "warning", issue.message);
+            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${ctx.label(issue.message)}`);
+            ctx.annotate(sev === "error" ? "error" : "warning", issue.message);
         }
     }
     return { issues: found.length, errors: sev === "error" ? found.length : 0 };
@@ -3962,13 +3995,14 @@ function checkDescriptionBudget(config, silent, adapter, scanRoot) {
  * COUNT is unchanged (units, not lines), so exit codes and the CI gate are
  * unaffected by the collapse.
  */
-function checkLethalTrifecta(config, silent, adapter, scanRoot) {
+function checkLethalTrifecta(ctx) {
+    const { config, silent } = ctx;
     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)(scanRoot, adapter.layout, adapter.dialect).trifectaFindings;
+        found = ctx.scan().trifectaFindings;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -3982,8 +4016,8 @@ function checkLethalTrifecta(config, silent, adapter, scanRoot) {
             if (unfenced.includes(t))
                 continue;
             const msg = `${t.kind} ${t.name}: ${t.finding.message}`;
-            console.log(`  ${mark} ${t.path}: ${msg}`);
-            ghAnnotate(level, msg, t.path);
+            console.log(`  ${mark} ${ctx.bundle.scanned(t.path)}: ${msg}`);
+            ctx.annotate(level, msg, ctx.bundle.scanned(t.path));
         }
         if (unfenced.length > 0) {
             console.log(`  ${mark} ${String(unfenced.length)} skill(s) declare no \`disallowed-tools:\` fence, so each ` +
@@ -4002,17 +4036,18 @@ function checkLethalTrifecta(config, silent, adapter, scanRoot) {
  * nothing. Reuses `scanPlugin`'s `skillResourceIssues` (high-precision / FP-safe,
  * one detector, no drift). Warning by default; "error" gates CI.
  */
-function checkSkillResourceResolves(config, silent, adapter, scanRoot) {
+function checkSkillResourceResolves(ctx) {
+    const { config, silent } = ctx;
     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)(scanRoot, adapter.layout, adapter.dialect, {
+        found = ctx.scan({
             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),
+            // sharedDirs live at the frame root — the repo that OWNS the scan target:
+            // cwd for a scoped subdir or a nested bundle, the target for a foreign lint.
+            sharedDirsRoot: ctx.frame.root,
         }).skillResourceIssues;
     }
     catch {
@@ -4027,8 +4062,8 @@ function checkSkillResourceResolves(config, silent, adapter, scanRoot) {
                 // it was documented only in docs/skills-monorepo.md, so a CI log gave no
                 // hint and the rule read as broken rather than misconfigured.
                 ` If it resolves from the repo root instead, add its directory to \`sharedDirs\` in .vigilesrc.json.`;
-            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${s.path}: ${msg}`);
-            ghAnnotate(sev === "error" ? "error" : "warning", msg, s.path);
+            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${ctx.bundle.scanned(s.path)}: ${msg}`);
+            ctx.annotate(sev === "error" ? "error" : "warning", msg, ctx.bundle.scanned(s.path));
         }
     }
     return { issues: found.length, errors: sev === "error" ? found.length : 0 };
@@ -4040,13 +4075,14 @@ function checkSkillResourceResolves(config, silent, adapter, scanRoot) {
  * Reuses `scanPlugin`'s `skillFenceIssues` (one detector, no drift). Warning by
  * default; "error" gates CI.
  */
-function checkSkillMissingFence(config, silent, adapter, scanRoot) {
+function checkSkillMissingFence(ctx) {
+    const { config, silent } = ctx;
     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)(scanRoot, adapter.layout, adapter.dialect).skillFenceIssues;
+        found = ctx.scan().skillFenceIssues;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -4055,8 +4091,8 @@ function checkSkillMissingFence(config, silent, adapter, scanRoot) {
         console.log("\nSkill-missing-fence check:\n");
         for (const s of found) {
             const msg = `${s.name}: ${s.finding.message}`;
-            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${s.path}: ${msg}`);
-            ghAnnotate(sev === "error" ? "error" : "warning", msg, s.path);
+            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${ctx.bundle.scanned(s.path)}: ${msg}`);
+            ctx.annotate(sev === "error" ? "error" : "warning", msg, ctx.bundle.scanned(s.path));
         }
     }
     return { issues: found.length, errors: sev === "error" ? found.length : 0 };
@@ -4068,13 +4104,14 @@ function checkSkillMissingFence(config, silent, adapter, scanRoot) {
  * `pluginLayoutIssues` (one detector, no drift). Warning by default; "error"
  * gates CI.
  */
-function checkPluginDirLayout(config, silent, adapter, scanRoot) {
+function checkPluginDirLayout(ctx) {
+    const { config, silent } = ctx;
     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)(scanRoot, adapter.layout, adapter.dialect).pluginLayoutIssues;
+        found = ctx.scan().pluginLayoutIssues;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -4082,8 +4119,8 @@ function checkPluginDirLayout(config, silent, adapter, scanRoot) {
     if (found.length > 0 && !silent) {
         console.log("\nPlugin-dir-layout check:\n");
         for (const p of found) {
-            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${p.message}`);
-            ghAnnotate(sev === "error" ? "error" : "warning", p.message);
+            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${ctx.label(p.message)}`);
+            ctx.annotate(sev === "error" ? "error" : "warning", p.message);
         }
     }
     return { issues: found.length, errors: sev === "error" ? found.length : 0 };
@@ -4096,13 +4133,14 @@ function checkPluginDirLayout(config, silent, adapter, scanRoot) {
  * 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, scanRoot) {
+function checkDelegationTrifecta(ctx) {
+    const { config, silent } = ctx;
     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)(scanRoot, adapter.layout, adapter.dialect).delegationTrifecta;
+        found = ctx.scan().delegationTrifecta;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -4111,8 +4149,8 @@ function checkDelegationTrifecta(config, silent, adapter, scanRoot) {
         console.log("\nDelegation-trifecta check:\n");
         for (const d of found) {
             const msg = `${d.finding.name}: ${d.finding.message}`;
-            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${d.path}: ${msg}`);
-            ghAnnotate(sev === "error" ? "error" : "warning", msg, d.path);
+            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${ctx.bundle.scanned(d.path)}: ${msg}`);
+            ctx.annotate(sev === "error" ? "error" : "warning", msg, ctx.bundle.scanned(d.path));
         }
     }
     return { issues: found.length, errors: sev === "error" ? found.length : 0 };
@@ -4124,7 +4162,8 @@ function checkDelegationTrifecta(config, silent, adapter, scanRoot) {
  * 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, scanRoot) {
+function checkHookBlockIneffective(ctx) {
+    const { config, silent, adapter } = ctx;
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["hook-block-ineffective"]);
     if (!sev)
         return { issues: 0, errors: 0 };
@@ -4134,22 +4173,38 @@ function checkHookBlockIneffective(config, silent, adapter, scanRoot) {
     }
     let found;
     try {
-        found = (0, scan_js_1.scanPlugin)(scanRoot, adapter.layout, adapter.dialect).hookBlockFindings;
+        found = ctx.scan().hookBlockFindings;
     }
     catch {
         return { issues: 0, errors: 0 };
     }
     if (found.length > 0 && !silent) {
+        const mark = sev === "error" ? "✗" : "⚠";
+        const level = sev === "error" ? "error" : "warning";
         console.log("\nHook-block check:\n");
         for (const h of found) {
-            const where = h.scriptPath ?? "(inline)";
-            const msg = `[${h.event}] ${where}: ${h.message}`;
-            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${msg}`);
-            ghAnnotate(sev === "error" ? "error" : "warning", msg, h.scriptPath ?? undefined);
+            const { msg, file, shown } = hookBlockLine(ctx, h);
+            console.log(`  ${mark} ${shown}`);
+            ctx.annotate(level, msg, file);
         }
     }
     return { issues: found.length, errors: sev === "error" ? found.length : 0 };
 }
+/**
+ * One hook-block finding in the repo frame. scan-core reports the script
+ * ABSOLUTE (it resolves the command against the bundle), which used to print a
+ * machine path and annotate `file=/home/…` (#281); an inline hook names no file
+ * and so carries the bundle label instead.
+ */
+function hookBlockLine(ctx, h) {
+    if (h.scriptPath === null) {
+        const msg = `[${h.event}] (inline): ${h.message}`;
+        return { msg, shown: ctx.label(msg) };
+    }
+    const file = ctx.bundle.scanned(h.scriptPath);
+    const msg = `[${h.event}] ${file}: ${h.message}`;
+    return { msg, file, shown: msg };
+}
 /**
  * Apply the `hook-matcher` rule: a hook `matcher` string that doesn't fire as
  * written — a tool-name typo (`bash`→`Bash`), a matcher that doesn't compile, an
@@ -4158,7 +4213,8 @@ function checkHookBlockIneffective(config, silent, adapter, scanRoot) {
  * Reuses `scanPlugin`'s `hookMatcherFindings` (one detector, no drift). Warning
  * by default; "error" gates CI.
  */
-function checkHookMatcher(config, silent, adapter, scanRoot) {
+function checkHookMatcher(ctx) {
+    const { config, silent, adapter } = ctx;
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["hook-matcher"]);
     if (!sev)
         return { issues: 0, errors: 0 };
@@ -4168,7 +4224,7 @@ function checkHookMatcher(config, silent, adapter, scanRoot) {
     }
     let found;
     try {
-        found = (0, scan_js_1.scanPlugin)(scanRoot, adapter.layout, adapter.dialect).hookMatcherFindings;
+        found = ctx.scan().hookMatcherFindings;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -4176,8 +4232,8 @@ function checkHookMatcher(config, silent, adapter, scanRoot) {
     if (found.length > 0 && !silent) {
         console.log("\nHook-matcher check:\n");
         for (const m of found) {
-            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${m.message}`);
-            ghAnnotate(sev === "error" ? "error" : "warning", m.message);
+            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${ctx.label(m.message)}`);
+            ctx.annotate(sev === "error" ? "error" : "warning", m.message);
         }
     }
     return { issues: found.length, errors: sev === "error" ? found.length : 0 };
@@ -4189,7 +4245,8 @@ function checkHookMatcher(config, silent, adapter, scanRoot) {
  * `mcpHookIssues` (high-precision: declared-set gated, built-ins allowlisted).
  * Warning by default; "error" gates CI.
  */
-function checkMcpHookTargets(config, silent, adapter, scanRoot) {
+function checkMcpHookTargets(ctx) {
+    const { config, silent, adapter } = ctx;
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["mcp-hook-target-resolves"]);
     if (!sev)
         return { issues: 0, errors: 0 };
@@ -4199,7 +4256,7 @@ function checkMcpHookTargets(config, silent, adapter, scanRoot) {
     }
     let found;
     try {
-        found = (0, scan_js_1.scanPlugin)(scanRoot, adapter.layout, adapter.dialect).mcpHookIssues;
+        found = ctx.scan().mcpHookIssues;
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -4207,8 +4264,8 @@ function checkMcpHookTargets(config, silent, adapter, scanRoot) {
     if (found.length > 0 && !silent) {
         console.log("\nMCP hook-target check:\n");
         for (const issue of found) {
-            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${issue.message}`);
-            ghAnnotate(sev === "error" ? "error" : "warning", issue.message);
+            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${ctx.label(issue.message)}`);
+            ctx.annotate(sev === "error" ? "error" : "warning", issue.message);
         }
     }
     return { issues: found.length, errors: sev === "error" ? found.length : 0 };
@@ -4221,7 +4278,8 @@ function checkMcpHookTargets(config, silent, adapter, scanRoot) {
  * existence-guarded one-liners, inline commands). Matches Anthropic's own
  * `claude plugin validate`. Warning by default; "error" gates CI.
  */
-function checkHookScriptExists(config, silent, adapter, scanRoot) {
+function checkHookScriptExists(ctx) {
+    const { config, silent, adapter } = ctx;
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["hook-script-exists"]);
     if (!sev)
         return { issues: 0, errors: 0 };
@@ -4231,7 +4289,7 @@ function checkHookScriptExists(config, silent, adapter, scanRoot) {
     }
     let missing;
     try {
-        missing = (0, scan_js_1.scanPlugin)(scanRoot, adapter.layout, adapter.dialect).hooks.filter((h) => h.status === "missing");
+        missing = ctx.scan().hooks.filter((h) => h.status === "missing");
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -4239,9 +4297,12 @@ function checkHookScriptExists(config, silent, adapter, scanRoot) {
     if (missing.length > 0 && !silent) {
         console.log("\nHook-script existence check:\n");
         for (const h of missing) {
-            const msg = `hook script "${h.script}" is referenced but missing — the hook never runs.`;
-            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${msg}`);
-            ghAnnotate(sev === "error" ? "error" : "warning", msg);
+            // `script` arrives with the plugin-root token EXPANDED, i.e. absolute —
+            // printed as-is it was a machine path (#281). A relative one is the
+            // bundle's own, which is what `scanned` assumes.
+            const msg = `hook script "${ctx.bundle.scanned(h.script)}" is referenced but missing — the hook never runs.`;
+            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${ctx.label(msg)}`);
+            ctx.annotate(sev === "error" ? "error" : "warning", msg);
         }
     }
     return {
@@ -4256,7 +4317,8 @@ function checkHookScriptExists(config, silent, adapter, scanRoot) {
  * — 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, scanRoot) {
+function checkMcpToolResolves(ctx) {
+    const { config, silent, adapter } = ctx;
     const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["mcp-tool-resolves"]);
     if (!sev)
         return { issues: 0, errors: 0 };
@@ -4266,7 +4328,9 @@ function checkMcpToolResolves(config, silent, adapter, scanRoot) {
     }
     let found;
     try {
-        found = (0, scan_js_1.scanPlugin)(scanRoot, adapter.layout, adapter.dialect).agents.flatMap((a) => a.mcpToolIssues.map((i) => ({ message: i.message, path: a.path })));
+        found = ctx
+            .scan()
+            .agents.flatMap((a) => a.mcpToolIssues.map((i) => ({ message: i.message, path: a.path })));
     }
     catch {
         return { issues: 0, errors: 0 };
@@ -4274,8 +4338,8 @@ function checkMcpToolResolves(config, silent, adapter, scanRoot) {
     if (found.length > 0 && !silent) {
         console.log("\nMCP tool-resolution check:\n");
         for (const issue of found) {
-            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${issue.path}: ${issue.message}`);
-            ghAnnotate(sev === "error" ? "error" : "warning", issue.message, issue.path);
+            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${ctx.bundle.scanned(issue.path)}: ${issue.message}`);
+            ctx.annotate(sev === "error" ? "error" : "warning", issue.message, ctx.bundle.scanned(issue.path));
         }
     }
     return { issues: found.length, errors: sev === "error" ? found.length : 0 };
@@ -4316,7 +4380,7 @@ async function checkCoverageThresholds(excludes, coverage, config, silent) {
         // Load all claude specs so coverage doesn't depend on a built dist/.
         const loaded = await Promise.all(findSpecs(excludes).map(loadSpec));
         const claudeSpecs = loaded.filter((s) => s?._specType === "claude");
-        const metric = (0, coverage_js_1.computeScriptCoverage)(process.cwd(), opts.scripts, claudeSpecs, excludes.ignore);
+        const metric = (0, coverage_js_1.computeScriptCoverage)(process.cwd(), opts.scripts, claudeSpecs, excludes.globIgnore);
         const ok = metric.passing;
         if (!ok)
             failing++;
@@ -4807,7 +4871,7 @@ function resolveRecords(cwd, runs, tier, harnessFlag) {
      *   1. `.claude-plugin/plugin.json#name` — the repo's own declared name, used
      *      when the run installed the repo AS a plugin (`pluginDir`).
      *   2. `vigiles-loose-skills` — the synthetic name OUR OWN packaging gives a
-     *      loose `.claude/skills` dir (`packageSkillsDir`, and `underTestSource`'s
+     *      loose `.claude/skills` dir (`packageSkillsDir`, and `installNamespace`'s
      *      fallback when a plugin manifest has no name). A repo that is not a plugin
      *      still reports namespaced ids under it, so omitting it would drop every
      *      trigger-rate record for the documented one-liner.
@@ -4828,20 +4892,35 @@ function resolveRecords(cwd, runs, tier, harnessFlag) {
         return [...names];
     }
     const recordsConfig = (0, validate_js_1.loadConfig)();
-    const scan = (0, test_coverage_js_1.findUntestedSurfaces)({
-        basePath: cwd,
-        layout: harnessLayoutFor(cwd, recordsConfig, harnessFlag),
-        // The repo-wide `exclude` only — the per-rule severities/include stay out
-        // of record resolution on purpose (a run's probes must map to a surface
-        // whether or not the untested-* rule for its kind is on).
-        exclude: (0, exclude_js_1.excludeSet)(cwd, recordsConfig.exclude).ignore,
+    const layout = harnessLayoutFor(cwd, recordsConfig, harnessFlag);
+    // The repo-wide `exclude` only — the per-rule severities/include stay out
+    // of record resolution on purpose (a run's probes must map to a surface
+    // whether or not the untested-* rule for its kind is on).
+    const excludes = (0, exclude_js_1.excludeSet)(cwd, recordsConfig.exclude);
+    // 🔴 THE SAME BUNDLES `lint` SCORES (#281, D5). This discovered the root
+    // bundle only, so under `bundles: "all"` a run that exercised a nested skill
+    // recorded nothing, and `lint` then called that skill untested. Every bundle's
+    // surfaces are expressed from `cwd`, the one frame the artifact is keyed in; a
+    // name two bundles share identifies neither (`resolveProbe` takes only a
+    // unique match), which is the honest answer to an ambiguous probe.
+    const bundles = recordsConfig.bundles === "all"
+        ? [cwd, ...discoverNestedBundles(cwd, excludes)]
+        : [cwd];
+    const surfaces = bundles.flatMap((basePath) => {
+        const scan = (0, test_coverage_js_1.findUntestedSurfaces)({
+            basePath,
+            root: cwd,
+            layout,
+            excludes,
+        });
+        return [...scan.covered, ...scan.untested];
     });
     return (0, coverage_artifact_js_1.recordsFrom)({
         runs,
-        surfaces: [...scan.covered, ...scan.untested],
+        surfaces,
         tier,
         at: new Date().toISOString(),
-        selfNamespaces: selfNamespaces(cwd),
+        selfNamespaces: [...new Set(bundles.flatMap(selfNamespaces))],
         // The root an ABSOLUTE command ref must lie beneath to be OURS. Without it a
         // harness that executed `/tmp/fixture/hooks/pre.sh` credited this repo's own
         // `hooks/pre.sh`, because the tail matched. See the ladder note on
@@ -4943,7 +5022,7 @@ async function handleRunScripts(kind, args, restArgs, excludes) {
     }
     // A script under an excluded path is not DISCOVERED (a vendored corpus's own
     // harness must not run as ours), but a script you NAME still runs (#192).
-    const files = (0, run_scripts_js_1.discoverScripts)(restArgs.map((p) => noteExplicitOverride(excludes, p, "running")), defaultGlob, cwd, excludes.ignore);
+    const files = (0, run_scripts_js_1.discoverScripts)(restArgs.map((p) => noteExplicitOverride(excludes, p, "running")), defaultGlob, cwd, excludes.globIgnore);
     // `--min=N`: a CI gate asserts at least N scripts actually LOADED — so a bad
     // path, a renamed file, a glob that matched nothing, or a file that matched and
     // never linked fails LOUD instead of passing green with nothing executed.
@@ -5766,17 +5845,31 @@ function evalLockNudgeHookCommand() {
     // heard nothing at all, while a repo that already tests got reminded. That is
     // backwards, and `untested-skill` already stated the missing half correctly;
     // it just lived in `vigiles lint`, which someone has to run by hand.
-    const msg = (0, test_coverage_js_1.skillTestNudge)(target, {
+    // Same union `vigiles lint` applies: the rule's exclude narrows, the
+    // repo-wide exclude is the floor (#192) — the nudge must not report a
+    // vendored skill the linter would never list.
+    const excludes = (0, exclude_js_1.excludeSet)(cwd, config.exclude);
+    // 🔴 THE BUNDLE THAT HOLDS THE EDIT, found the way `lint` finds it (#281, D6).
+    // The nudge scanned the root bundle only and matched by SUFFIX, so an edit to
+    // `plugins/p/skills/x/SKILL.md` was answered with the coverage of the ROOT's
+    // `skills/x`. Now the edited path is a `RepoPath`, the scan runs over the
+    // bundle it lives in, and the two are compared for equality in one frame.
+    // A nested bundle `lint` would not score (no `bundles: "all"`) gets no nudge,
+    // for the same reason it gets no finding.
+    const frame = (0, frame_js_1.frameAt)(cwd);
+    const edited = (0, node_path_1.resolve)(cwd, file);
+    const home = (config.bundles === "all"
+        ? discoverNestedBundles(cwd, excludes).find((b) => {
+            const r = (0, node_path_1.relative)(b, edited);
+            return r !== "" && !r.startsWith("..") && !(0, node_path_1.isAbsolute)(r);
+        })
+        : undefined) ?? cwd;
+    const msg = (0, test_coverage_js_1.skillTestNudge)(frame.repo(edited), {
         ...options,
-        basePath: cwd,
+        basePath: home,
+        root: cwd,
         layout,
-        // Same union `vigiles lint` applies: the rule's exclude narrows, the
-        // repo-wide exclude is the floor (#192) — the nudge must not report a
-        // vendored skill the linter would never list.
-        exclude: [
-            ...(options.exclude ?? []),
-            ...(0, exclude_js_1.excludeSet)(cwd, config.exclude).ignore,
-        ],
+        excludes,
     }) ?? (0, eval_lock_js_1.evalLockNudge)(target, (0, node_path_1.resolve)(cwd, eval_lock_js_1.DEFAULT_LOCK_DIR));
     if (!msg)
         return;
@@ -6733,9 +6826,12 @@ async function main() {
                     process.exitCode = 2;
                     return;
                 }
+                // The same single owner of "relative to which directory" `lint` uses
+                // (#281): cwd, unless the audited dir is somebody else's repository.
+                const frame = (0, frame_js_1.frameFor)(process.cwd(), root);
                 const report = (0, scan_js_1.scanPlugin)(targets[0], adapter.layout, adapter.dialect, {
                     sharedDirs: config.sharedDirs,
-                    sharedDirsRoot: sharedDirsRootFor(targets[0]),
+                    sharedDirsRoot: frame.root,
                     // `.vigilesrc.json#exclude` reaches surface DISCOVERY, not just the
                     // instruction file. Measured 2026-09-21 before this line existed: a repo
                     // with `{"exclude": [".claude"]}` and one skill at `.claude/skills/demo`
@@ -6770,7 +6866,16 @@ async function main() {
                 // `init` adopts (layout-driven instruction file + skill/subagent sweep).
                 // Surfaced in the AuditReport (the report's "Create spec" command-emit
                 // buttons read it) and the terminal nudge below.
-                const adoptableSurfaces = discoverAdoptableForAudit(root, adapter.layout.instructionFile);
+                //
+                // 🔴 IN THE FRAME `init` RUNS IN, AND WITHOUT WHAT THE REPO EXCLUDES (#281,
+                // D7). The sweep reads the audited dir, so its paths are relative to it —
+                // and for `audit plugins/p` the printed `npx vigiles init
+                // --target=skills/x/SKILL.md` named a file that does not exist from where
+                // you run it, and offered to adopt a skill `exclude` had removed.
+                const auditedBundle = frame.bundle(root);
+                const adoptableSurfaces = discoverAdoptableForAudit(root, adapter.layout.instructionFile)
+                    .filter((p) => !(0, exclude_js_1.excludedBy)(excludes)((0, node_path_1.resolve)(root, p)))
+                    .map((p) => auditedBundle.scanned(p));
                 // Read the local flight recorder ONCE — feeds both the JSON report
                 // (structured summary, the product boundary) and the terminal render.
                 const ledgerRecords = (0, observe_js_1.readObservations)(root);