@vibe-agent-toolkit/cli 0.1.41-rc.7 → 0.1.41

package/dist/commands/audit.js

@@ -4,22 +4,26 @@
  */
 import * as fs from 'node:fs';
 import { existsSync as fsExistsSync } from 'node:fs';
+import { basename } from 'node:path';
 import { calculateValidationStatus, countBySeverity, } from '@vibe-agent-toolkit/agent-schema';
 import { crawlAndResolveRegistry, detectDeclaredButMissing, detectMarketplacePluginSourceMissing, resetPackagingRegistryCache, detectPresentButUndeclared, detectReferenceTargetMissing, detectResourceFormat, enumerateSurfaces, validate, validateMarketplace, validateSkill, validateSkillForPackaging, } from '@vibe-agent-toolkit/agent-skills';
 import { analyzeCompatibility, checkSettingsCompatibility, detectSkillClaudePluginNameMismatch, crawlSkillLinkRegistry, extractClaudeMarketplaceInventory, extractClaudePluginInventory, getClaudeUserPaths, readEffectiveSettings, validatePlugin, } from '@vibe-agent-toolkit/claude-marketplace';
 import { detectFormat } from '@vibe-agent-toolkit/discovery';
-import { findProjectRoot, gitFindRoot, GitTracker, isAbsolutePath, isGitUrl, issueLocation, parseGitUrl, resetProjectRootCaches, safePath, } from '@vibe-agent-toolkit/utils';
+import { findProjectRoot, gitFindRoot, isAbsolutePath, isGitUrl, issueLocation, parseGitUrl, resetProjectRootCaches, safePath, } from '@vibe-agent-toolkit/utils';
 import { Command } from 'commander';
 import picomatch from 'picomatch';
-import { resetSkillDiscoveryCache, resolveSkillPackagingConfig, stripValidationAllowForDisplay, } from '../skill-resolution/packaging-config.js';
+import { resetSkillDiscoveryCache, resolveProjectDeclaredEvalSuites, resolveSkillPackagingConfig, stripValidationAllowForDisplay, } from '../skill-resolution/packaging-config.js';
 import { handleCommandError } from '../utils/command-error.js';
 import { ConfigLoadError, loadConfig, resetLoadedConfigCache, } from '../utils/config-loader.js';
-import { formatIssueAnchor } from '../utils/issue-anchor.js';
+import { countCollapsedFindings, formatCollapsedFindingsHint, formatIssueLines, formatSeverityBreakdown, issuesToRenderAtVerbosity, } from '../utils/issue-rendering.js';
+import { resolveIssueSeverity } from '../utils/issue-severity.js';
 import { createLogger } from '../utils/logger.js';
 import { writeYamlOutput } from '../utils/output.js';
+import { relativizePathEntries } from '../utils/relativize-paths.js';
 import { mergeSkillPackagingConfig } from '../utils/skill-packaging-config.js';
 import { renderSkillQualityFooter } from '../utils/skill-quality-footer.js';
 import { computeConfigVerdicts } from '../utils/verdict-helpers.js';
+import { crawlOwnsSubtree, distributedTreeFindings, getOrCreateGitTracker, isWithin, resetGitTrackerCache, } from './audit/distributed-tree.js';
 import { withClonedRepo } from './audit/git-url-clone.js';
 import { buildHierarchicalOutput } from './audit/hierarchical-output.js';
 import { renderProvenanceHeader, rewritePathsInResults, } from './audit/provenance.js';
@@ -149,8 +153,15 @@ function packagingResultToValidationResult(skillPath, result, configTargets, loc
 /**
  * Validate a single SKILL.md file, using config-aware validation if available.
  * Used for direct SKILL.md and vat-agent paths passed to `vat audit`.
+ *
+ * @param crawlTree Whether this call owns the presence-side crawl of the skill's
+ *   directory (see {@link appendDistributedTreeFindings} below). REQUIRED
+ *   and never defaulted, because the wrong answer is silent in both directions: a
+ *   skill nested inside a plugin is already crawled by `validatePlugin` at any
+ *   depth, so crawling again reports one file twice, while omitting it for a
+ *   standalone bundle is the blindness this parameter exists to end.
  */
-async function validateSingleSkill(skillPath, options, logger, locationRoot, isVATGenerated) {
+async function validateSingleSkill(skillPath, options, logger, locationRoot, crawlTree, isVATGenerated) {
     // Try config-aware validation: walk UP to the skill's nearest-ancestor
     // vibe-agent-toolkit.config.yaml and apply the skill's packaging block. A
     // broken governing config is tolerated here (audit is a bulk linter): log it
@@ -168,21 +179,27 @@ async function validateSingleSkill(skillPath, options, logger, locationRoot, isV
     const skillConfig = fullConfig === null ? null : stripValidationAllowForDisplay(fullConfig);
     if (skillConfig !== null) {
         logger.debug(`  Using config-aware validation for: ${skillPath}`);
-        const { gitTracker } = await resolveScanContext(safePath.resolve(skillPath), locationRoot);
+        const { gitTracker } = await resolveScanContext(safePath.resolve(skillPath), locationRoot, logger);
         // Key the shared registry on the same project root the validator derives,
         // so every skill under one root parses the corpus once for the whole run
         // instead of once each.
         const skillDir = safePath.resolve(skillPath, '..');
         const projectRoot = findProjectRoot(skillDir) ?? skillDir;
+        // The project's declared eval suites, memoized per config root, so this lane
+        // predicts the same bundle the packager produces: no skill's report counts a
+        // SIBLING skill's eval suite as an ordinary bundled file.
         const sharedCtx = {
             registry: await crawlAndResolveRegistry(projectRoot),
             locationRoot,
+            projectSkills: await resolveProjectDeclaredEvalSuites(skillPath),
         };
         if (gitTracker !== null) {
             sharedCtx.gitTracker = gitTracker;
         }
         const packagingResult = await validateSkillForPackaging(skillPath, skillConfig, 'source', sharedCtx);
-        return packagingResultToValidationResult(skillPath, packagingResult, skillConfig.targets, locationRoot);
+        const configAware = packagingResultToValidationResult(skillPath, packagingResult, skillConfig.targets, locationRoot);
+        await appendDistributedTreeFindings(configAware, skillPath, locationRoot, crawlTree);
+        return configAware;
     }
     // Fallback: basic validation
     const validateOptions = { skillPath, locationRoot };
@@ -192,7 +209,35 @@ async function validateSingleSkill(skillPath, options, logger, locationRoot, isV
     if (isVATGenerated === true) {
         validateOptions.isVATGenerated = true;
     }
-    return validateSkill(validateOptions);
+    const result = await validateSkill(validateOptions);
+    await appendDistributedTreeFindings(result, skillPath, locationRoot, crawlTree);
+    return result;
+}
+/**
+ * Crawl a DISTRIBUTED skill's own directory for agent-instruction files and
+ * append what it finds. Mutates `result`, like every other additive detector
+ * pass in this command.
+ *
+ * Which trees count as distributed — and why the config's declaration is NOT the
+ * discriminator any more — lives with the classifier in
+ * `./audit/distributed-tree.ts` (`classifyScannedSkillTree`). In short: a repository that never adopted
+ * VAT declares nothing, and an adopting repo's `include` globs never enumerate
+ * its drafts and fixtures, so "not declared" swept up two populations of
+ * ordinary repo source.
+ *
+ * Called from BOTH lanes — config-aware and wild — deliberately. It used to be
+ * reachable only from the wild one, which left the abandoned discriminator alive
+ * at the caller in its purest suppressing form: adding a `vibe-agent-toolkit.config.yaml`
+ * to a dotfiles repo removed findings from skills installed under `~/.claude`,
+ * because a config-aware match returned before the classifier was ever asked.
+ * Whether the project also declares a skill says nothing about where that skill
+ * lives, so it must not decide whether the question gets asked.
+ *
+ * @param crawlTree `false` when a plugin lane already crawled this subtree — see
+ *   {@link validateSingleSkill}.
+ */
+async function appendDistributedTreeFindings(result, skillPath, locationRoot, crawlTree) {
+    appendIssues(result, await distributedTreeFindings(skillPath, locationRoot, crawlTree));
 }
 /**
  * Collect repeated option values into an array (used for --exclude)
@@ -213,7 +258,12 @@ export function createAuditCommand() {
         .option('--exclude <glob>', 'Exclude paths matching glob pattern (repeatable)', collect, [])
         .option('--include-artifacts', 'Include gitignored paths (build artifacts, dependencies) that are excluded by default')
         .option('--user', 'Audit user-level Claude resources (default: $CLAUDE_CONFIG_DIR or ~/.claude — scans plugins/, skills/, marketplaces/)')
-        .option('--verbose', 'Show all scanned resources, including those without issues')
+        // `-v` short form: `vat audit -v` used to print the version (the root
+        // `-v, --version` shadowed every subcommand), and after that alias was
+        // removed it exited 1 as an unknown option — while five sibling verbs
+        // accepted it. Advertising only the long form is what made the CHANGELOG's
+        // "`-v` means `--verbose` on every verb" claim untrue.
+        .option('-v, --verbose', 'Show all scanned resources, including those without issues')
         .option('--warn-unreferenced-files', 'Warn about files not referenced in skill markdown')
         .option('--compat', 'Run compatibility analysis for each plugin (shows claude-code, claude-cowork, claude-chat support)')
         .option('--settings [file]', 'Check plugins against Claude settings (auto-discover or specify file; requires --compat)')
@@ -306,13 +356,17 @@ Gitignore-Aware Scanning:
   Outside a git repository, no automatic exclusions apply.
 
 Config-Aware Validation:
-  When a vibe-agent-toolkit.config.yaml is found at the git root, audit
-  uses the project's build settings (linkFollowDepth, files,
-  excludeReferencesFromBundle) to validate skills. This prevents false
-  warnings for links that the build pipeline resolves.
+  The governing vibe-agent-toolkit.config.yaml is found by walking UP from
+  the audited path, so a built bundle deep under dist/ is still governed by
+  its project's config. Audit uses that project's build settings
+  (linkFollowDepth, files, excludeReferencesFromBundle) to validate skills,
+  which prevents false warnings for links the build pipeline resolves.
 
   Config-aware mode never applies validation.allow — audit always shows
-  all issues. validation.severity is respected for display grouping.
+  all issues. validation.severity IS applied: a code set to 'ignore' is
+  hidden. skills.defaults.validation.severity applies project-wide (skills,
+  plugins and marketplaces alike); skills.config.<name>.validation.severity
+  layers on top for that skill.
 
 Exit Codes:
   0 - Always (even when validation errors are surfaced)
@@ -330,6 +384,37 @@ Examples:
 `);
     return audit;
 }
+/**
+ * Which of the Claude install roots a `--user` run actually walks.
+ *
+ * The three roots read as siblings and are NOT: `marketplacesDir` is
+ * `<claudeDir>/plugins/marketplaces`, i.e. INSIDE `pluginsDir`. A recursive walk
+ * of `plugins/` already reaches every installed marketplace, so scanning
+ * `marketplaces/` afterwards audited each marketplace-installed plugin and skill
+ * a SECOND time, in a second result, under the identical `path:`. On one real
+ * machine that turned 7 distinct agent-instruction files into 12 reported rows —
+ * and it inflates every finding class, not one code, because the whole subject
+ * is re-audited rather than one detector re-firing.
+ *
+ * The containment test is `isWithin`, the same one the provenance classifier
+ * uses, so "inside" means the same thing on both sides and on Windows.
+ *
+ * Gated on `recursive`, and that is not defensive dressing: under
+ * `--no-recursive` a walk of `plugins/` stops at its top level and never reaches
+ * `marketplaces/`, so dropping the nested root there would replace a double
+ * count with no coverage at all.
+ *
+ * Pure, and exported for that reason: the shape of the defect is "the list of
+ * roots was wrong", which is assertable as a list.
+ *
+ * @internal Exported for unit testing only — not part of the public CLI API.
+ */
+export function userScanTargets(candidates, recursive) {
+    const resolved = candidates.map((dir) => safePath.resolve(dir));
+    if (!recursive)
+        return resolved;
+    return resolved.filter((dir) => !resolved.some((other) => other !== dir && isWithin(other, dir)));
+}
 /**
  * Handle --user audit: scans ~/.claude/plugins, ~/.claude/skills, ~/.claude/marketplaces
  * and outputs hierarchical YAML. Calls process.exit() when done.
@@ -354,21 +439,20 @@ async function auditUserDirectories(recursive, options, startTime, logger) {
         process.exit(2);
     }
     const results = [];
-    if (pluginsDirExists) {
-        logger.debug(`Auditing user-level plugins at: ${pluginsDir}`);
-        results.push(...await getValidationResults(pluginsDir, recursive, options, logger, scanRoot));
-    }
-    if (skillsDirExists) {
-        logger.debug(`Auditing user-level skills at: ${skillsDir}`);
-        results.push(...await getValidationResults(skillsDir, recursive, options, logger, scanRoot));
-    }
-    if (marketplacesDirExists) {
-        logger.debug(`Auditing user-level marketplaces at: ${marketplacesDir}`);
-        results.push(...await getValidationResults(marketplacesDir, recursive, options, logger, scanRoot));
+    // The roots that exist, minus any one another already covers — see
+    // {@link userScanTargets}. `marketplaces/` lives inside `plugins/`.
+    const present = [
+        ...(pluginsDirExists ? [pluginsDir] : []),
+        ...(skillsDirExists ? [skillsDir] : []),
+        ...(marketplacesDirExists ? [marketplacesDir] : []),
+    ];
+    for (const target of userScanTargets(present, recursive)) {
+        logger.debug(`Auditing user-level resources at: ${target}`);
+        results.push(...await getValidationResults(target, recursive, options, logger, scanRoot));
     }
     // Run compatibility analysis if --compat flag is set
     const compatMap = options.compat
-        ? await runCompatAnalysis(results, logger) // --settings not supported in --user mode
+        ? await runCompatAnalysis(results, logger, scanRoot) // --settings not supported in --user mode
         : undefined;
     const verbose = options.verbose ?? false;
     const skillResults = results.filter((r) => SKILL_RESULT_TYPES.has(r.type));
@@ -380,22 +464,6 @@ async function auditUserDirectories(recursive, options, startTime, logger) {
     }
     logHierarchicalSummary(results, logger);
 }
-/**
- * Apply severity filtering to validation results.
- *
- * Audit is advisory only: it applies `validation.severity` to decide what to
- * show, but deliberately ignores `validation.allow`. Codes configured as
- * `severity: 'ignore'` are stripped from the result issues before rendering.
- *
- * The severity config is per-skill, keyed by skill name in
- * `config.skills.config[skillName].validation.severity`.
- * Defaults config (`config.skills.defaults.validation.severity`) is also
- * checked as a fallback.
- *
- * @param results - Raw validation results from skill/plugin validators
- * @param config - Parsed VATConfig (may be undefined if no config file)
- * @returns New results array with ignored codes removed from issues
- */
 /** Skill resource types that can have per-skill validation config. */
 const SKILL_RESULT_TYPES = new Set([RESOURCE_TYPE_AGENT_SKILL, 'vat-agent']);
 /**
@@ -425,17 +493,27 @@ export function deriveScanRoot(targetPath) {
 /**
  * Derive the project root directory for config loading.
  *
- * For a direct SKILL.md path, the project root is two levels up (skill dir → skills/ → project/).
- * For a directory or undefined path, use the directory itself (or cwd).
+ * Walks UP from the audit target through {@link findProjectRoot} — the same
+ * discovery ladder (`vibe-agent-toolkit.config.yaml`, then `.git/`) that
+ * `resolveSkillPackagingConfig` uses per skill, so the two cannot disagree about
+ * which project governs a path.
+ *
+ * It used to guess by SHAPE instead: a directory argument resolved to ITSELF and
+ * a `SKILL.md` argument to exactly two levels up. Neither reaches a project root
+ * from a built bundle — `vat audit dist/skills/demo` looked for the config inside
+ * the bundle, found none, and `applySeverityFilter` early-returned. The effect was
+ * that `severity.PACKAGED_AGENT_INSTRUCTION_FILE: ignore` — the opt-out this very
+ * command's `fix` text tells the reader to write — did nothing whenever audit was
+ * pointed at the bundle rather than at the project. Measured: `warnings: 1` with
+ * the override and without it, from the same tree, while `vat audit .` on that
+ * same project honoured it.
+ *
+ * `null` (no config and no git anywhere above) falls back to the target itself,
+ * which is what the shape-based version returned for every path.
  */
 function deriveConfigRoot(targetPath) {
-    if (targetPath === undefined) {
-        return process.cwd();
-    }
-    if (targetPath.endsWith('SKILL.md')) {
-        return safePath.resolve(safePath.join(targetPath, '..', '..'));
-    }
-    return safePath.resolve(targetPath);
+    const start = targetPath === undefined ? process.cwd() : deriveScanRoot(targetPath);
+    return findProjectRoot(start) ?? start;
 }
 /**
  * Build the recalculated status and summary after issues have been filtered.
@@ -454,16 +532,55 @@ function buildFilteredResult(result, filteredIssues) {
     };
 }
 /**
- * Apply severity filtering to validation results.
+ * Apply severity resolution to validation results.
  *
  * Audit is advisory only: it applies `validation.severity` to decide what to
- * show, but deliberately ignores `validation.allow`. Codes configured as
- * `severity: 'ignore'` are stripped from the result issues before rendering.
+ * show and at what severity, but deliberately ignores `validation.allow`.
+ *
+ * **Both directions, via the one shared resolver.** This used to compute the
+ * merged override map correctly and then consult it for a single value —
+ * `issues.filter(i => effective[i.code] !== 'ignore')` — so `ignore` worked
+ * while `error`, `warning` and `info` fell through untouched. Measured end to
+ * end on a real adopter tree: `severity: error` at BOTH scopes left
+ * `severity: warning`, `errors: 0`, `status: warning`, while `vat verify` on the
+ * same config promoted correctly. Two lanes, one config key, opposite answers.
+ *
+ * Status and counts are re-derived from the resolved severities by
+ * {@link buildFilteredResult}, so a promotion moves the reported status. It does
+ * NOT move this command's exit code — `vat audit` is advisory and its exit-code
+ * behaviour is a separate, pre-existing question tracked in its own issue. That
+ * asymmetry with `vat verify` (whose exit code IS severity-derived) is
+ * deliberate here rather than overlooked.
+ *
+ * Two scopes, both live:
+ *  - `skills.defaults.validation.severity` — the PROJECT-WIDE map, applied to
+ *    every result this run produced, including `claude-plugin` and `marketplace`
+ *    ones. It used to be applied only to skill-typed results, which left the
+ *    opt-out inert for the population that motivated it: the false positive
+ *    `PACKAGED_AGENT_INSTRUCTION_FILE` was kept at `warning` for — an official
+ *    plugin's intentional scaffold template — is a finding on a PLUGIN tree, and
+ *    no per-skill key can name it. Measured before the fix: a plugin result kept
+ *    its warning with `severity: ignore` set at `skills.defaults`.
+ *  - `skills.config.<name>.validation.severity` — layered on top, and only for a
+ *    result that names a skill, since that key is keyed by skill name.
  *
- * The severity config is per-skill, keyed by skill name in
- * `config.skills.config[skillName].validation.severity`.
- * Defaults config (`config.skills.defaults.validation.severity`) is also
- * checked as a fallback.
+ * KNOWN, DELIBERATELY NOT FIXED — per-skill scope cannot reach a finding nested
+ * inside a plugin tree, even when that finding IS attributable to a skill.
+ * `vat audit <plugin dir>` reports two findings: the plugin root's `CLAUDE.md`
+ * (attributable to no skill, which is the case the project-wide scope above was
+ * added for) and an `AGENTS.md` nested inside one of the plugin's OWN skills,
+ * which is attributable. Measured: neither moves under
+ * `skills.config.<that skill>` nor under `skills.config.<the plugin's name>`;
+ * only the project-wide `skills.defaults` moves them. The mechanism is the line
+ * below — a `claude-plugin` result is not in `SKILL_RESULT_TYPES`, so `skillName`
+ * is `undefined` and the per-skill map is never consulted, no matter which name
+ * the adopter writes.
+ *
+ * The consequence worth stating plainly: an adopter with ONE intentional
+ * agent-instruction file in ONE plugin has to silence the code project-wide in
+ * this lane, losing the detector everywhere else. The marketplace lane has the
+ * same project-wide-only limitation for a different reason, recorded there: both
+ * marketplace config schemas are `.strict()` with no `validation` key at all.
  *
  * @param results - Raw validation results from skill/plugin validators
  * @param config - Parsed VATConfig (may be undefined if no config file)
@@ -476,10 +593,7 @@ function applySeverityFilter(results, config) {
     const skillsConfig = config.skills;
     const defaultSeverity = skillsConfig.defaults?.validation?.severity ?? {};
     return results.map(result => {
-        if (!SKILL_RESULT_TYPES.has(result.type)) {
-            return result;
-        }
-        const skillName = result.metadata?.name;
+        const skillName = SKILL_RESULT_TYPES.has(result.type) ? result.metadata?.name : undefined;
         const perSkillSeverity = skillName === undefined
             ? {}
             : (skillsConfig.config?.[skillName]?.validation?.severity ?? {});
@@ -488,11 +602,18 @@ function applySeverityFilter(results, config) {
         if (Object.keys(effectiveSeverity).length === 0) {
             return result;
         }
-        const filteredIssues = result.issues.filter(issue => effectiveSeverity[issue.code] !== 'ignore');
-        if (filteredIssues.length === result.issues.length) {
+        const resolvedIssues = resolveIssueSeverity(result.issues, { severity: effectiveSeverity });
+        // Short-circuit only when NOTHING moved. Comparing lengths alone was the old
+        // test, and it is blind to the promote direction by construction: a resolved
+        // `error` keeps the array exactly as long as it was, so an early return on
+        // equal lengths discarded every re-severitied issue and reported the raw
+        // ones. The severities have to be compared too.
+        const unchanged = resolvedIssues.length === result.issues.length &&
+            resolvedIssues.every((issue, index) => issue.severity === result.issues[index]?.severity);
+        if (unchanged) {
             return result;
         }
-        return buildFilteredResult(result, filteredIssues);
+        return buildFilteredResult(result, resolvedIssues);
     });
 }
 /**
@@ -539,7 +660,7 @@ export async function buildAuditReport(scanPath, options, startTime, logger) {
     const vatContextForCompat = await buildVATProjectContext(deriveConfigRoot(scanPath), logger);
     // Run compatibility analysis if --compat flag is set
     const compatMap = options.compat
-        ? await runCompatAnalysis(results, logger, effectiveSettings, vatContextForCompat)
+        ? await runCompatAnalysis(results, logger, scanRoot, effectiveSettings, vatContextForCompat)
         : undefined;
     const verbose = options.verbose ?? false;
     return {
@@ -570,7 +691,7 @@ async function runAuditAtPath(scanPath, options, overrides = {}) {
     if (verbose) {
         renderVerboseEvidence(results, document.root, logger);
     }
-    handleAuditResults(results, document, logger);
+    handleAuditResults(results, document, logger, verbose);
     logger.debug(`Audit complete in ${Date.now() - startTime}ms`);
 }
 async function runUrlAudit(rawInput, options) {
@@ -622,7 +743,11 @@ export async function auditCommand(targetPath, options) {
  */
 async function validateSurface(surface, options, logger, locationRoot) {
     if (surface.type === RESOURCE_TYPE_AGENT_SKILL) {
-        return validateSingleSkill(surface.path, options, logger, locationRoot);
+        // No crawl: this arm only runs for a MULTI-surface root, which in practice is
+        // skill-claude-plugin (SKILL.md beside .claude-plugin/plugin.json). The plugin
+        // surface below crawls that same directory at any depth, so crawling here
+        // would report every agent-instruction file in it a second time.
+        return validateSingleSkill(surface.path, options, logger, locationRoot, false);
     }
     if (surface.type === RESOURCE_TYPE_CLAUDE_PLUGIN) {
         return validatePlugin(surface.path, { locationRoot });
@@ -749,13 +874,13 @@ export async function getValidationResults(scanPath, recursive, options, logger,
     // Special handling for direct SKILL.md file
     if (format === RESOURCE_TYPE_AGENT_SKILL) {
         logger.debug('Detected single Agent Skill');
-        return [await validateSingleSkill(scanPath, options, logger, locationRoot)];
+        return [await validateSingleSkill(scanPath, options, logger, locationRoot, true)];
     }
     // Special handling for VAT agent: validate its SKILL.md
     if (format === 'vat-agent') {
         const skillPath = safePath.join(scanPath, 'SKILL.md');
         logger.debug('Detected VAT agent, validating SKILL.md');
-        return [await validateSingleSkill(skillPath, options, logger, locationRoot, true)];
+        return [await validateSingleSkill(skillPath, options, logger, locationRoot, true, true)];
     }
     // Enumerate all manifest surfaces at the directory root. If multiple are
     // present (e.g., skill-claude-plugin: SKILL.md + .claude-plugin/plugin.json),
@@ -813,14 +938,11 @@ export async function getValidationResults(scanPath, recursive, options, logger,
         const stat = await fsp.stat(scanPath);
         if (stat.isDirectory()) {
             logger.debug('Scanning directory for resources');
-            // Merge resources.exclude from config with --exclude CLI flag patterns.
-            // Both use the same picomatch semantics. Do NOT mutate options.
-            const config = loadConfig(deriveConfigRoot(scanPath));
-            const configExcludes = config?.resources?.exclude ?? [];
-            const mergedOptions = configExcludes.length > 0
-                ? { ...options, exclude: [...(options.exclude ?? []), ...configExcludes] }
-                : options;
-            return scanDirectory(scanPath, recursive, mergedOptions, logger, await resolveScanContext(scanPath, locationRoot));
+            // The project's `resources.exclude` is applied by the scan context,
+            // on the project-root basis its globs were written against — NOT
+            // merged into `options.exclude`, whose patterns are relative to the
+            // directory the operator named. See resolveProjectExcludes.
+            return scanDirectory(scanPath, recursive, options, logger, await resolveScanContext(scanPath, locationRoot, logger));
         }
     }
     catch {
@@ -850,7 +972,9 @@ async function validatePluginSkillsViaInventory(scanPath, options, logger, locat
             continue;
         }
         logger.debug(`  Validating plugin-bundled skill (inventory): ${skill.files.skillMd}`);
-        results.push(await validateSingleSkill(skill.files.skillMd, options, logger, locationRoot));
+        // No crawl: `validatePlugin` already scanned the whole plugin tree, nested
+        // skill directories included, so this lane would duplicate its findings.
+        results.push(await validateSingleSkill(skill.files.skillMd, options, logger, locationRoot, false));
     }
     return results;
 }
@@ -895,6 +1019,11 @@ function resolveConfigTargetsForPlugin(pluginDir, vatContext) {
  * Non-plugin results are skipped silently.
  * When effectiveSettings is provided, also runs settings conflict detection.
  *
+ * `locationRoot` is the invocation scan root: the ONE base every emitted
+ * evidence `location.file` is relative to. One audit run spans many plugin
+ * directories, so anchoring evidence at each plugin would mix coordinate
+ * systems in a single document.
+ *
  * When vatContext is provided, config-layer `targets` declarations are
  * threaded through to the analyzer so `vat audit .` inside a VAT project
  * matches `vat skills validate` verdicts. See
@@ -902,7 +1031,7 @@ function resolveConfigTargetsForPlugin(pluginDir, vatContext) {
  *
  * @internal Exported for integration testing only — not part of the public CLI API.
  */
-export async function runCompatAnalysis(results, logger, effectiveSettings, vatContext = null) {
+export async function runCompatAnalysis(results, logger, locationRoot, effectiveSettings, vatContext = null) {
     const compatMap = new Map();
     for (const result of results) {
         if (result.type !== RESOURCE_TYPE_CLAUDE_PLUGIN)
@@ -913,7 +1042,7 @@ export async function runCompatAnalysis(results, logger, effectiveSettings, vatC
             const analyzeOptions = configTargets === undefined
                 ? undefined
                 : { configTargets };
-            const compat = await analyzeCompatibility(result.path, analyzeOptions);
+            const compat = await analyzeCompatibility(result.path, locationRoot, analyzeOptions);
             // Settings conflict detection (when --settings flag is used)
             if (effectiveSettings === undefined) {
                 compatMap.set(result.path, compat);
@@ -994,34 +1123,22 @@ function applyVerboseFilter(results, verbose) {
     });
 }
 /**
- * Re-base each emitted file entry's `path` onto the run root.
- *
- * `ValidationResult.path` stays ABSOLUTE inside the pipeline on purpose: it is
- * the identity every internal map keys on (compat results, visited-path
- * de-duplication, registry caches), and unlike `location` it is trivially
- * recoverable — an absolute path plus the known root yields the relative form.
- * `location` is the opposite: it cannot be re-based here because a relative
- * string whose base was never stated is not recoverable, which is exactly why
- * the base is threaded down to the producers instead.
+ * Nested carriers inside a file entry that publish their own `path`.
+ *
+ * `linkedFiles[].path` sat absolute in every document while every sibling
+ * `path` and `location` beside it was root-relative — 532 of them in a single
+ * `vat audit --user` run. Naming the carrier here is what re-bases it; a new
+ * carrier that is not named keeps shipping absolute paths.
  */
-function relativizeFileEntries(entries, root) {
-    return entries.map((entry) => {
-        const relative = issueLocation(entry.path, root);
-        // Pointing audit AT a single resource makes that resource the root, which
-        // relativizes to the empty string. Spell it `.` — the POSIX name for "the
-        // root itself" — so no consumer has to special-case an empty path, and
-        // `join(root, path)` still resolves.
-        return { ...entry, path: relative === '' ? '.' : relative };
-    });
-}
+const NESTED_PATH_CARRIERS = ['linkedFiles'];
 function calculateSummary(results, startTime, compatMap, verbose, root) {
-    const base = buildBaseSummary(results, startTime);
-    const withCompat = applyCompatMap(results, compatMap);
+    const { entries, ...base } = buildBaseSummary(results, startTime);
+    const withCompat = applyCompatMap(entries, compatMap);
     return {
         // Stated once, first, and the only absolute path in the document.
         root,
         ...base,
-        files: relativizeFileEntries(applyVerboseFilter(withCompat, verbose), root),
+        files: relativizePathEntries(applyVerboseFilter(withCompat, verbose), root, NESTED_PATH_CARRIERS),
     };
 }
 /**
@@ -1065,6 +1182,37 @@ function renderIssueEvidence(issue, evidenceSources, logger) {
         logger.info(formatEvidenceLine(ev));
     }
 }
+/**
+ * The name a findings block is headed with — never the empty string.
+ *
+ * `issueLocation` answers "where is this, relative to the scan root", and for a
+ * result that IS the scan root (auditing a plugin directory produces exactly
+ * that) the honest relative path is `''`. Rendered straight into a heading, that
+ * produced ` — 2 warnings:` — the operator was told a nameless something had two
+ * warnings and then, because warnings collapse at default verbosity, shown
+ * neither. Fall back in decreasing order of usefulness to the reader:
+ *
+ *  1. the relative path, whenever there is one (the common case, unchanged);
+ *  2. the resource's own name from metadata already on the result — for a plugin
+ *     or skill this is the most recognisable subject there is;
+ *  3. the last path segment, i.e. the scanned directory's own name;
+ *  4. `'.'`, the minimum honest way to say "the root you pointed me at".
+ *
+ * Every step reads data already in hand — no new I/O, and no re-deriving a path
+ * the caller already resolved.
+ */
+function findingSubject(result, root) {
+    const location = issueLocation(result.path, root);
+    if (location !== '')
+        return location;
+    const name = result.metadata?.name;
+    if (name !== undefined && name !== '')
+        return name;
+    // `basename` is empty for a filesystem root ('/' or 'C:\'), which is the only
+    // case left that '.' has to cover.
+    const directoryName = basename(result.path);
+    return directoryName === '' ? '.' : directoryName;
+}
 /**
  * Render supporting evidence beneath each CAPABILITY_* issue when the
  * audit was invoked with --verbose. Evidence comes from the validation
@@ -1082,13 +1230,13 @@ function renderVerboseEvidence(results, root, logger) {
         ];
         if (evidenceSources.length === 0)
             continue;
-        logger.info(`\n${issueLocation(result.path, root)} — supporting evidence:`);
+        logger.info(`\n${findingSubject(result, root)} — supporting evidence:`);
         for (const issue of capabilityIssues) {
             renderIssueEvidence(issue, evidenceSources, logger);
         }
     }
 }
-function handleAuditResults(results, summary, logger) {
+function handleAuditResults(results, summary, logger, verbose) {
     const { filesWithErrors: errorCount, filesWithWarnings: warningCount, filesPassed: successCount, } = summary.summary;
     // Report settings conflicts (advisory, non-blocking)
     const totalSettingsConflicts = (summary.files ?? []).reduce((sum, f) => {
@@ -1100,10 +1248,12 @@ function handleAuditResults(results, summary, logger) {
     // Audit is advisory only — always exit 0 for validation results.
     // Use vat skills validate for gated validation (exit 1 on errors).
     if (errorCount > 0) {
-        logErrors(results, errorCount, summary.root, logger);
+        logger.error(`Audit failed: ${errorCount} file(s) with errors`);
+        logFindingsForStatus(results, 'error', summary.root, logger.error.bind(logger), verbose);
     }
     else if (warningCount > 0) {
-        logWarnings(results, warningCount, summary.root, logger);
+        logger.info(`Audit passed with warnings: ${warningCount} file(s)`);
+        logFindingsForStatus(results, 'warning', summary.root, logger.info.bind(logger), verbose);
     }
     else {
         // `success` means "nothing actionable", NOT "nothing to see" — name the
@@ -1135,35 +1285,79 @@ function renderAuditFooter(results, logger) {
     }
     renderSkillQualityFooter(logger, hasSkillFindings, emittedCodes);
 }
-function logErrors(results, errorCount, root, logger) {
-    logger.error(`Audit failed: ${errorCount} file(s) with errors`);
-    const errorResults = results.filter((r) => r.status === 'error');
-    for (const result of errorResults) {
-        logger.error(`\n${issueLocation(result.path, root)}:`);
-        const errorIssues = result.issues.filter((i) => i.severity === 'error');
-        logIssues(errorIssues, logger.error.bind(logger));
-    }
-}
-function logWarnings(results, warningCount, root, logger) {
-    logger.info(`Audit passed with warnings: ${warningCount} file(s)`);
-    const warningResults = results.filter((r) => r.status === 'warning');
-    for (const result of warningResults) {
-        logger.info(`\n${issueLocation(result.path, root)}:`);
-        const warningIssues = result.issues.filter((i) => i.severity === 'warning');
-        logIssues(warningIssues, logger.info.bind(logger));
-    }
-}
-function logIssues(issues, logFn) {
-    for (const issue of issues) {
-        logFn(`  [${issue.code}] ${issue.message}`);
-        const anchor = formatIssueAnchor(issue);
-        if (anchor !== undefined) {
-            logFn(`    at: ${anchor}`);
-        }
-        if (issue.fix) {
-            logFn(`    fix: ${issue.fix}`);
+/**
+ * The stderr findings report for a set of audit results — the HUMAN channel.
+ *
+ * Deliberately NOT the YAML document. `vat audit` publishes a machine-readable
+ * report on stdout that CI and tooling parse, and that document carries every
+ * finding at every verbosity; this stream is read by a person, and on a 90-skill
+ * corpus it printed 26,480 lines, 3,480 of them occurrences of a single
+ * high-cardinality warning code. The two channels answer different questions, so
+ * only this one collapses.
+ *
+ * Which findings render in full is not decided here — it is
+ * {@link issuesToRenderAtVerbosity}, shared with the other findings-reporting
+ * verbs so `vat audit`, `vat skills validate` and `vat skills build` cannot drift
+ * onto three answers again. Errors always render; warnings and info collapse
+ * unless `verbose`; allow-listed findings never render.
+ *
+ * The severity breakdown on each file's heading is load-bearing, not decoration.
+ * For a warning-only file at default verbosity that heading is the ENTIRE report
+ * for that file, so dropping the counts would turn the collapse into silence —
+ * the failure direction `issue-rendering.ts` exists to prevent. The trailing
+ * line names the collapsed total and both ways to see it, for the same reason.
+ *
+ * That trailing line points at THIS audit's YAML report, deliberately — do not
+ * broaden it back into a claim about "the YAML report" in general. It is only
+ * true of the verbs that emit full `issues:` arrays, and which verbs those are
+ * has changed: `vat skills build` now publishes them too, so the sentence is
+ * shared rather than re-spelled (see `formatCollapsedFindingsHint`, which takes
+ * the report name for exactly this reason). Any verb that publishes counts alone
+ * must still not use it — there, it would send a CI consumer to a document that
+ * cannot answer the question.
+ *
+ * Pure: takes results, returns lines. It reads `issues` and never rewrites it,
+ * because `runAuditAtPath` builds the YAML document from the very same array.
+ *
+ * @internal Exported for unit testing only — not part of the public CLI API.
+ */
+export function formatAuditFindingsLines(results, root, verbose) {
+    const lines = [];
+    let collapsed = 0;
+    for (const result of results) {
+        const rendered = issuesToRenderAtVerbosity(result.issues, verbose);
+        // What --verbose WOULD show, minus what this verbosity shows. Derived from
+        // the policy rather than re-stating it, so the count cannot contradict it.
+        collapsed += countCollapsedFindings(result.issues, verbose);
+        // The heading is unconditional and counts the WHOLE set — for a
+        // warning-only file at default verbosity it IS the report. The trailing
+        // colon is what varies: it introduces the blocks below, so a heading with
+        // nothing beneath it does not print one. Same rule, same reason, as
+        // `formatPostBuildIssueReport` in `skills/build.ts` — a colon promising a
+        // list the current verbosity will not print is a promise the renderer
+        // already knows it will break.
+        const heading = `\n${findingSubject(result, root)} — ${formatSeverityBreakdown(countBySeverity(result.issues))}`;
+        lines.push(rendered.length === 0 ? heading : `${heading}:`);
+        for (const issue of rendered) {
+            lines.push(...formatIssueLines(issue, '  '));
         }
     }
+    const hint = formatCollapsedFindingsHint(collapsed, 'audit');
+    if (hint !== undefined)
+        lines.push(hint);
+    return lines;
+}
+/**
+ * Write one status class's findings to stderr beneath the run banner.
+ *
+ * The banner counts FILES and the blocks below count FINDINGS; both are needed,
+ * and `logFn` picks the channel the calling branch already established.
+ */
+function logFindingsForStatus(results, status, root, logFn, verbose) {
+    const selected = results.filter((r) => r.status === status);
+    for (const line of formatAuditFindingsLines(selected, root, verbose)) {
+        logFn(line);
+    }
 }
 /**
  * Check whether a path should be excluded during directory scanning.
@@ -1176,6 +1370,53 @@ function isExcludedPath(isMatch, relativePath, isDirectory) {
     }
     return isMatch(relativePath);
 }
+/**
+ * Does the SKILL.md at `skillMdPath` own its own presence-side crawl, or has an
+ * ancestor crawl already covered it?
+ *
+ * The single place the walk answers that question, for both owner kinds — see
+ * {@link ScanContext.crawledRoot}. `isWithin` rather than a bare
+ * `crawledRoot === null`: the claim is a containment claim and it is spelled
+ * once, in the module that already got the separator right.
+ */
+function ownsOwnCrawl(scanCtx, skillMdPath) {
+    return scanCtx.crawledRoot === null || !isWithin(scanCtx.crawledRoot, safePath.resolve(skillMdPath));
+}
+/**
+ * Hand the descending context an owner for everything below `owner`, unless one
+ * is already claimed. First owner wins, and `null` claims nothing.
+ */
+function claimSubtree(scanCtx, owner) {
+    if (owner === null || scanCtx.crawledRoot !== null)
+        return scanCtx;
+    return { ...scanCtx, crawledRoot: safePath.resolve(owner) };
+}
+/**
+ * The context this directory's SUBDIRECTORIES are walked with.
+ *
+ * A `SKILL.md` here means this directory's own crawl reaches every descendant at
+ * any depth, so it — not each nested skill in turn — owns the subtree below.
+ *
+ * Resolved before the entry loop rather than inside it: `SKILL.md` and the
+ * subdirectories it governs are siblings in one `readdir`, and their order is
+ * the filesystem's to choose, so deciding this mid-loop would make the verdict
+ * depend on it.
+ *
+ * Conditional on the crawl actually RUNNING ({@link crawlOwnsSubtree}), not on
+ * the SKILL.md merely existing: a repo-source skill's crawl is skipped
+ * entirely, so claiming its subtree would trade a double count for a missed
+ * finding — and provenance is not monotone down a tree.
+ */
+async function contextForDescendants(dirPath, entries, scanCtx) {
+    if (!entries.some((entry) => entry.isFile() && entry.name === 'SKILL.md'))
+        return scanCtx;
+    const skillMd = safePath.join(dirPath, 'SKILL.md');
+    if (!ownsOwnCrawl(scanCtx, skillMd))
+        return scanCtx;
+    if (!await crawlOwnsSubtree(skillMd))
+        return scanCtx;
+    return claimSubtree(scanCtx, dirPath);
+}
 /**
  * Handle file entry during directory scan
  */
@@ -1198,18 +1439,28 @@ async function handleFileEntry(entry, fullPath, options, logger, scanCtx) {
             logger.debug(`  Using config-aware validation for: ${fullPath}`);
             // Thread the per-scan tracker into packaging validation so gitignore
             // checks in the link-graph walk stay O(1).
+            // `projectSkills`: same project-wide test-input rule as the lane above,
+            // resolved through the same per-config-root memo.
+            const projectSkills = await resolveProjectDeclaredEvalSuites(fullPath);
             const sharedCtx = scanCtx.gitTracker === null
-                ? { locationRoot }
-                : { gitTracker: scanCtx.gitTracker, locationRoot };
+                ? { locationRoot, projectSkills }
+                : { gitTracker: scanCtx.gitTracker, locationRoot, projectSkills };
             const packagingResult = await validateSkillForPackaging(fullPath, skillConfig, 'source', sharedCtx);
-            return packagingResultToValidationResult(fullPath, packagingResult, skillConfig.targets, locationRoot);
+            const configAware = packagingResultToValidationResult(fullPath, packagingResult, skillConfig.targets, locationRoot);
+            await appendDistributedTreeFindings(configAware, fullPath, locationRoot, ownsOwnCrawl(scanCtx, fullPath));
+            return configAware;
         }
         // Wild mode: basic validation
         const validateOptions = { skillPath: fullPath, locationRoot };
         if (options.warnUnreferencedFiles) {
             validateOptions.checkUnreferencedFiles = true;
         }
-        return validateSkill(validateOptions);
+        const result = await validateSkill(validateOptions);
+        // Wild mode is where the distributed-tree question is even ASKED; the
+        // classifier answers it. Suppressed under a plugin ancestor, which already
+        // crawled this whole subtree at any depth.
+        await appendDistributedTreeFindings(result, fullPath, locationRoot, ownsOwnCrawl(scanCtx, fullPath));
+        return result;
     }
     return null;
 }
@@ -1230,15 +1481,64 @@ async function handleDirectoryEntry(fullPath, recursive, options, logger, baseDi
         appendInventoryParseErrors(result, inv, locationRoot);
         results.push(result);
     }
-    // Recurse into subdirectories (both plugin/marketplace dirs and regular dirs)
+    // Recurse into subdirectories (both plugin/marketplace dirs and regular dirs).
+    // Below a plugin, `validatePlugin` has already crawled the whole subtree for
+    // agent-instruction files, so every crawl below must stand down or one file
+    // is reported twice. See {@link ScanContext.crawledRoot} — first owner wins,
+    // and it never clears on the way down.
+    const childCtx = claimSubtree(scanCtx, hasClaudePlugin ? fullPath : null);
     if (recursive) {
-        const subResults = await scanDirectory(fullPath, recursive, options, logger, scanCtx, baseDir, nestedConfigLog);
+        const subResults = await scanDirectory(fullPath, recursive, options, logger, childCtx, baseDir, nestedConfigLog);
         results.push(...subResults);
     }
     return results;
 }
-/** Cache of (gitRoot → initialized GitTracker) to avoid re-spawning ls-files. */
-const gitTrackerCache = new Map();
+/**
+ * Compile the governing project's `resources.exclude` for a scan.
+ *
+ * The config is found by walking UP from the scan directory ({@link findProjectRoot}),
+ * not by looking in it. Looking only in the scan directory is how a path argument
+ * silently voided every exclude the project had declared: `vat audit
+ * packages/x/resources/skills/` found no config there, so a package that excludes
+ * its deliberately-broken eval fixtures had them audited as production skills the
+ * moment anyone named a subdirectory. Commit 8a466b0c fixed the same defect for
+ * `vat resources validate|scan` and `vat rag index`; this is the lane it missed.
+ * The rule is the same one that commit established: a path argument says WHICH
+ * tree to audit, and `exclude` applies either way.
+ *
+ * With one deliberate exception, mirroring the gitignore rule in
+ * {@link resolveScanContext}: when the operator points the scan AT an excluded
+ * tree, their explicit intent wins and the excludes are dropped for that run.
+ * Otherwise naming an excluded directory would report `filesScanned: 0,
+ * status: success` — a green run that scanned nothing.
+ */
+function resolveProjectExcludes(scanDir, logger) {
+    const projectRoot = findProjectRoot(scanDir);
+    if (projectRoot === null)
+        return null;
+    let patterns;
+    try {
+        patterns = loadConfig(projectRoot)?.resources?.exclude ?? [];
+    }
+    catch (err) {
+        // Audit is a bulk linter over trees it does not own; a broken governing
+        // config must not abort the scan. Say so rather than dropping it silently.
+        logger.debug(`Ignoring unreadable config at ${projectRoot}: ${String(err)}`);
+        return null;
+    }
+    if (patterns.length === 0)
+        return null;
+    // dot:true so excludes like `**/.cache/*` match through dotfile dirs;
+    // without it the exclude silently never fires.
+    const isMatch = picomatch([...patterns], { dot: true });
+    const scanRelToProject = safePath.relative(projectRoot, safePath.resolve(scanDir)).replaceAll('\\', '/');
+    if (scanRelToProject !== '' && isExcludedPath(isMatch, scanRelToProject, true)) {
+        logger.debug(`Scan root ${scanRelToProject} is excluded by the config at ${projectRoot}; ` +
+            'auditing it anyway because it was named explicitly');
+        return null;
+    }
+    return { isMatch, base: projectRoot, label: 'excluded by config' };
+}
 /**
  * Cache of (projectRoot → registry for the *inventory* link walk).
  *
@@ -1264,10 +1564,27 @@ async function getOrCreateInventoryRegistry(projectRoot) {
 /**
  * `extractClaudePluginInventory` for a plugin directory, handing it the shared
  * inventory registry so each skill it walks does not re-parse the corpus.
+ *
+ * A PROVIDER, not an awaited registry, and only when there is a project root — the same
+ * two rules `vat inventory`'s `linkRegistryProviderFor` follows, for the same two reasons:
+ *
+ * 1. **Unresolved.** `extractClaudePluginInventory` promises "never throws — all failures
+ *    surface via parseErrors[]", and that promise holds only while the crawl runs inside
+ *    `walkLinkedFiles`'s try/catch. Awaiting it here moved the crawl outside that catch,
+ *    so one unreadable markdown file anywhere under the root aborted the WHOLE audit with
+ *    `status: error` and exit code 2 instead of degrading three link walks. The extractor
+ *    memoizes the provider and caches even a rejection, so the failed crawl is still
+ *    attempted once, not once per skill.
+ * 2. **Only a project root.** Reuse is gated on exact `registry.baseDir === projectRoot`
+ *    equality against the root `walkLinkedFiles` derives per skill
+ *    (`findProjectRoot(dirname(skillMd)) ?? dirname(skillMd)`). With no project root that
+ *    per-skill fallback is each skill's OWN directory, so a registry rooted at the plugin
+ *    matches nothing: it would be crawled, compared, discarded, and re-crawled per skill.
+ *    No root, no provider.
  */
 async function pluginInventoryAt(dir) {
-    const root = findProjectRoot(dir) ?? dir;
-    return extractClaudePluginInventory(dir, await getOrCreateInventoryRegistry(root));
+    const projectRoot = findProjectRoot(dir);
+    return extractClaudePluginInventory(dir, projectRoot === null ? undefined : () => getOrCreateInventoryRegistry(projectRoot));
 }
 /**
  * Reset all module-level audit caches. Must be called at the start of every
@@ -1276,23 +1593,13 @@ async function pluginInventoryAt(dir) {
  * governing configs, or skill-discovery maps from a prior run.
  */
 export function resetAuditCaches() {
-    gitTrackerCache.clear();
+    resetGitTrackerCache();
     resetPackagingRegistryCache();
     inventoryRegistryCache.clear();
     resetProjectRootCaches();
     resetLoadedConfigCache();
     resetSkillDiscoveryCache();
 }
-async function getOrCreateGitTracker(gitRoot) {
-    const cached = gitTrackerCache.get(gitRoot);
-    if (cached !== undefined) {
-        return cached;
-    }
-    const tracker = new GitTracker(gitRoot);
-    await tracker.initialize();
-    gitTrackerCache.set(gitRoot, tracker);
-    return tracker;
-}
 /**
  * Resolve the effective git root and build a per-repo {@link GitTracker} for a
  * scan. On the first call for a scan (no tracker yet), detects the git root
@@ -1303,18 +1610,19 @@ async function getOrCreateGitTracker(gitRoot) {
  * `dist/`), returns `{ gitRoot: null, gitTracker: null }` to disable gitignore
  * filtering — the user's explicit intent takes precedence over .gitignore.
  */
-async function resolveScanContext(dirPath, locationRoot) {
+async function resolveScanContext(dirPath, locationRoot, logger) {
+    const projectExcludes = resolveProjectExcludes(dirPath, logger);
     const detectedRoot = gitFindRoot(dirPath);
     if (detectedRoot === null) {
-        return { gitRoot: null, gitTracker: null, locationRoot };
+        return { gitRoot: null, gitTracker: null, locationRoot, projectExcludes, crawledRoot: null };
     }
     const tracker = await getOrCreateGitTracker(detectedRoot);
     // If the scan root itself is gitignored (e.g. user targeted `dist/`), disable
     // gitignore filtering so the user's explicit intent wins.
     if (tracker.isIgnoredByActiveSet(dirPath)) {
-        return { gitRoot: null, gitTracker: null, locationRoot };
+        return { gitRoot: null, gitTracker: null, locationRoot, projectExcludes, crawledRoot: null };
     }
-    return { gitRoot: detectedRoot, gitTracker: tracker, locationRoot };
+    return { gitRoot: detectedRoot, gitTracker: tracker, locationRoot, projectExcludes, crawledRoot: null };
 }
 /**
  * Build the gitignore exclusion map for a set of entry paths.
@@ -1335,7 +1643,7 @@ function buildGitIgnoreMap(entryPaths, gitTracker, includeArtifacts) {
  * Check whether a directory entry should be skipped during scanning.
  * Returns a reason string for debug logging, or null if the entry should be kept.
  */
-function getSkipReason(entry, fullPath, resolvedBaseDir, gitIgnoredMap, isMatch) {
+function getSkipReason(entry, fullPath, gitIgnoredMap, excludeMatchers) {
     // Always skip .git directory (not reported by git check-ignore)
     if (entry.isDirectory() && entry.name === '.git') {
         return '.git';
@@ -1344,11 +1652,11 @@ function getSkipReason(entry, fullPath, resolvedBaseDir, gitIgnoredMap, isMatch)
     if (gitIgnoredMap !== null && gitIgnoredMap.get(fullPath) === true) {
         return `gitignored: ${entry.name}`;
     }
-    // Check user-supplied --exclude patterns
-    if (isMatch !== null) {
-        const relativePath = safePath.relative(resolvedBaseDir, fullPath).replaceAll('\\', '/');
-        if (isExcludedPath(isMatch, relativePath, entry.isDirectory())) {
-            return `excluded: ${relativePath}`;
+    // Each matcher answers against ITS OWN base — see {@link ExcludeMatcher}.
+    for (const matcher of excludeMatchers) {
+        const relativePath = safePath.relative(matcher.base, fullPath).replaceAll('\\', '/');
+        if (isExcludedPath(matcher.isMatch, relativePath, entry.isDirectory())) {
+            return `${matcher.label}: ${relativePath}`;
         }
     }
     return null;
@@ -1381,14 +1689,27 @@ async function scanDirectory(dirPath, recursive, options, logger, scanCtx, baseD
     // Compile picomatch for user-supplied --exclude patterns.
     // dot:true so excludes like `**/private/*` match through dotfile dirs
     // (`.claude/.../private/x`); without it the exclude silently never fires.
-    const isMatch = userExcludes.length > 0 ? picomatch(userExcludes, { dot: true }) : null;
+    // These are relative to the scan base; the config's excludes carry their own
+    // (project-root) base on the matcher — see {@link ExcludeMatcher}.
+    const excludeMatchers = [];
+    if (userExcludes.length > 0) {
+        excludeMatchers.push({
+            isMatch: picomatch(userExcludes, { dot: true }),
+            base: resolvedBaseDir,
+            label: 'excluded',
+        });
+    }
+    if (resolvedScanCtx.projectExcludes !== null) {
+        excludeMatchers.push(resolvedScanCtx.projectExcludes);
+    }
     const entries = await fs.readdir(dirPath, { withFileTypes: true });
+    const descendCtx = await contextForDescendants(dirPath, entries, resolvedScanCtx);
     // Build full paths and batch-check gitignore status
     const entryPaths = entries.map(e => safePath.join(dirPath, e.name));
     const gitIgnoredMap = buildGitIgnoreMap(entryPaths, resolvedScanCtx.gitTracker, options.includeArtifacts ?? false);
     for (const entry of entries) {
         const fullPath = safePath.join(dirPath, entry.name);
-        const skipReason = getSkipReason(entry, fullPath, resolvedBaseDir, gitIgnoredMap, isMatch);
+        const skipReason = getSkipReason(entry, fullPath, gitIgnoredMap, excludeMatchers);
         if (skipReason !== null) {
             logger.debug(`Excluding path: ${skipReason}`);
             continue;
@@ -1400,7 +1721,9 @@ async function scanDirectory(dirPath, recursive, options, logger, scanCtx, baseD
             }
         }
         else if (entry.isDirectory()) {
-            const dirResults = await handleDirectoryEntry(fullPath, recursive, options, logger, resolvedBaseDir, resolvedScanCtx, resolvedNestedLog);
+            // `descendCtx`, not `resolvedScanCtx`: this level's own skill (if any)
+            // owns everything below, including this subdirectory.
+            const dirResults = await handleDirectoryEntry(fullPath, recursive, options, logger, resolvedBaseDir, descendCtx, resolvedNestedLog);
             results.push(...dirResults);
         }
     }
@@ -1441,17 +1764,45 @@ function countFilesByStatus(results) {
     };
 }
 /**
- * Build base summary structure (used by both flat and hierarchical)
+ * Build base summary structure (used by both flat and hierarchical), together
+ * with the entries the document will publish.
  *
  * `issueCounts` is named exactly as it is on every individual file entry, and
  * means the same thing at both levels: findings, by severity. `summary` only ever
  * counts files.
+ *
+ * The header total and every per-file total come from ONE traversal of the
+ * final issue set, and the entries carrying those per-file totals are returned
+ * from the same pass. Before that, the header was derived from the issue
+ * records while each file's `issueCounts` was whatever its producer had
+ * published — and a producer that appends findings after publishing (or never
+ * sets the counts at all: `validatePlugin` writes `status` and `summary` but
+ * not `issueCounts`) left the two disagreeing inside one document. A real
+ * `vat audit --user` run said 55/422/504 in the header over per-file counts
+ * summing to 55/360/405, with 91 of 614 entries declaring `{0,0,0}` above the
+ * findings they listed. Re-deriving here means the header and the sum are the
+ * same arithmetic on the same array, so they cannot drift again no matter what
+ * a producer forgets.
+ *
+ * `linkedFiles[].issues` are deliberately NOT added: every linked finding is
+ * also present in its owner's `issues`, so the nested list is a VIEW of records
+ * already counted, not extra records. `audit-report-coherence.integration.test.ts`
+ * pins that subset relation, because counting once is only correct while it holds.
  */
 function buildBaseSummary(results, startTime) {
+    const issueCounts = { errors: 0, warnings: 0, info: 0 };
+    const entries = results.map((result) => {
+        const counts = countBySeverity(result.issues);
+        issueCounts.errors += counts.errors;
+        issueCounts.warnings += counts.warnings;
+        issueCounts.info += counts.info;
+        return { ...result, issueCounts: counts };
+    });
     return {
-        status: calculateOverallStatus(results),
-        summary: countFilesByStatus(results),
-        issueCounts: countBySeverity(results.flatMap((r) => r.issues)),
+        entries,
+        status: calculateOverallStatus(entries),
+        summary: countFilesByStatus(entries),
+        issueCounts,
         duration: `${Date.now() - startTime}ms`,
     };
 }
@@ -1459,8 +1810,8 @@ function buildBaseSummary(results, startTime) {
  * Calculate summary for hierarchical output
  */
 function calculateHierarchicalSummary(results, hierarchical, startTime, compatMap, verbose, root) {
-    const base = buildBaseSummary(results, startTime);
-    const withCompat = applyCompatMap(results, compatMap);
+    const { entries, ...base } = buildBaseSummary(results, startTime);
+    const withCompat = applyCompatMap(entries, compatMap);
     return {
         root,
         ...base,
@@ -1471,7 +1822,7 @@ function calculateHierarchicalSummary(results, hierarchical, startTime, compatMa
             standalonePlugins: hierarchical.standalonePlugins.length,
             standaloneSkills: hierarchical.standaloneSkills.length,
         },
-        files: relativizeFileEntries(applyVerboseFilter(withCompat, verbose), root),
+        files: relativizePathEntries(applyVerboseFilter(withCompat, verbose), root, NESTED_PATH_CARRIERS),
         hierarchical,
     };
 }