@vibe-agent-toolkit/cli 0.2.0-rc.1 → 0.2.0-rc.10

package/dist/commands/audit.js

@@ -5,21 +5,24 @@
 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 { conventionalSuiteProbe, crawlAndResolveRegistry, detectDeclaredButMissing, detectMarketplacePluginSourceMissing, resetPackagingRegistryCache, detectPresentButUndeclared, detectReferenceTargetMissing, detectResourceFormat, enumerateSurfaces, materializeIssue, 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, isAbsolutePath, isGitUrl, issueLocation, parseGitUrl, resetProjectRootCaches, safePath, } from '@vibe-agent-toolkit/utils';
+import { listingRefusalRemedy } from '@vibe-agent-toolkit/resources';
+import { calculateValidationStatus, countBySeverity, ExitCode, } from '@vibe-agent-toolkit/schema';
+import { findProjectRoot, isFilesystemAccessError, isPathAbsentError, issueLocation, relativeEscapesRoot, resetProjectRootCaches, safePath, toForwardSlash, } from '@vibe-agent-toolkit/utils';
+import { DirectoryListingRefusedError } from '@vibe-agent-toolkit/utils/crawl';
+import { gitFindRoot, isGitUrl, parseGitUrl, } from '@vibe-agent-toolkit/utils/git';
 import { Command } from 'commander';
-import picomatch from 'picomatch';
 import { resetSkillDiscoveryCache, resolveProjectDeclaredEvalSuites, resolveSkillPackagingConfig, stripValidationAllowForDisplay, } from '../skill-resolution/packaging-config.js';
-import { handleCommandError } from '../utils/command-error.js';
+import { handleCommandError, handleExpectedFailure } from '../utils/command-error.js';
 import { ConfigLoadError, loadConfig, resetLoadedConfigCache, } from '../utils/config-loader.js';
-import { countCollapsedFindings, formatCollapsedFindingsHint, formatIssueLines, formatSeverityBreakdown, issuesToRenderAtVerbosity, } from '../utils/issue-rendering.js';
+import { countCollapsedFindings, formatCollapsedFindingsHint, formatIssueLines, formatSeverityBreakdown, issuesToRenderAtVerbosity, sumSeverityCounts, } 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 { nothingCheckedFinding } from '../utils/run-integrity.js';
 import { mergeSkillPackagingConfig } from '../utils/skill-packaging-config.js';
 import { renderSkillQualityFooter } from '../utils/skill-quality-footer.js';
 import { computeConfigVerdicts } from '../utils/verdict-helpers.js';
@@ -27,13 +30,13 @@ import { crawlOwnsSubtree, distributedTreeFindings, getOrCreateGitTracker, gitTr
 import { withClonedRepo } from './audit/git-url-clone.js';
 import { buildHierarchicalOutput } from './audit/hierarchical-output.js';
 import { renderProvenanceHeader, rewritePathsInResults, } from './audit/provenance.js';
+import { enumerateAuditPopulation, resolveProjectExcludes, VAT_CONFIG_FILENAME, } from './audit/scan-population.js';
 import { createAuditSettingsCommand } from './audit-settings.js';
-import { discoverSkillsFromConfig } from './skills/skill-discovery.js';
+import { discoverSkillsFromConfig, SKILLS_INCLUDE_REMEDY, } from './skills/skill-discovery.js';
 /** Resource type constant for agent skills, avoiding duplicate string literals. */
 const RESOURCE_TYPE_AGENT_SKILL = 'agent-skill';
 /** Resource type constant for Claude plugins, avoiding duplicate string literals. */
 const RESOURCE_TYPE_CLAUDE_PLUGIN = 'claude-plugin';
-const VAT_CONFIG_FILENAME = 'vibe-agent-toolkit.config.yaml';
 /**
  * Build config-aware context for a single VAT project at `scanRoot`.
  *
@@ -50,9 +53,8 @@ const VAT_CONFIG_FILENAME = 'vibe-agent-toolkit.config.yaml';
  *
  * Returns `null` if `scanRoot` has no config or the config has no skills.
  */
-async function buildVATProjectContext(scanRoot, logger) {
+async function buildVATProjectContext(scanRoot, logger, locationRoot) {
     const configPath = safePath.join(scanRoot, VAT_CONFIG_FILENAME);
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- scanRoot is a controlled parameter
     if (!fs.existsSync(configPath)) {
         return null;
     }
@@ -68,7 +70,7 @@ async function buildVATProjectContext(scanRoot, logger) {
         return null;
     const skillConfigs = new Map();
     try {
-        const discovered = await discoverSkillsFromConfig(config.skills, scanRoot);
+        const discovered = await discoverSkillsFromConfig(config.skills, scanRoot, degradingDiscovery(scanRoot, logger, locationRoot));
         const { defaults, config: perSkillConfig } = config.skills;
         for (const skill of discovered) {
             const absPath = safePath.resolve(skill.sourcePath);
@@ -78,7 +80,16 @@ async function buildVATProjectContext(scanRoot, logger) {
         logger.debug(`Config-aware audit: found ${discovered.length} skill(s) in ${scanRoot}`);
     }
     catch (error) {
-        logger.debug(`Config-aware audit: failed to discover skills in ${scanRoot}: ${String(error)}`);
+        // Discovery was handed the degrade policy above, so a refused listing never
+        // reaches here; one that does (a caller that switched it to `'refuse'`) is
+        // still degraded past through the same ledger rather than swallowed. It used
+        // to be `logger.debug` for ANY error, which is how a `chmod 000` directory
+        // under `skills.include` downgraded every skill to config-free validation with
+        // the directory named nowhere an operator without `--debug` could see it. A
+        // defect in discovery is not environmental and still fails loudly.
+        if (!(error instanceof DirectoryListingRefusedError))
+            throw error;
+        recordRefusedDiscovery(error, scanRoot, logger, locationRoot);
     }
     if (skillConfigs.size === 0) {
         return null;
@@ -161,22 +172,287 @@ function packagingResultToValidationResult(skillPath, result, configTargets, loc
  *   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, 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
-    // and fall back to config-free validation rather than aborting the scan.
+/**
+ * Resolve a skill's nearest-ancestor `vibe-agent-toolkit.config.yaml`, treating
+ * one that cannot be LOADED as absent rather than as fatal.
+ *
+ * 🔑 Both audit lanes call this, and that is the point. They used to carry
+ * separate copies of the fork, and the copies disagreed: the single-target lane
+ * caught `ConfigLoadError` and fell back, the directory-scan lane let it throw.
+ * One unrecognized key in one nested config therefore aborted a whole-tree scan
+ * with exit 2 and zero skills audited, while auditing a single SKILL.md under
+ * that same config exited 0 — a verdict that depended on whether the argument
+ * was a file or its parent directory. Keeping the tolerance in ONE function is
+ * what stops the two answers drifting apart again.
+ *
+ * Degrading beats destroying, and silence is not the alternative — the policy
+ * `SCAN_PATH_UNREADABLE` states in its own registry docstring. So this warns
+ * rather than logging at debug, AND files a finding on the config path, because
+ * the warning goes to stderr while the report goes to stdout: a run that
+ * downgraded N skills to the much weaker config-free `validateSkill` and exited 0
+ * said nothing about it in the machine-readable artifact anyone actually diffs.
+ * That is the "detector silently disables itself" shape this code cites and was
+ * still doing.
+ *
+ * ⚠️ The filesystem question IS asked, and the answer changes what the operator
+ * is told. `config-loader.ts` preserves `cause` specifically so callers can ask
+ * `isFilesystemAccessError` and "decide whether to degrade or abort"; catching
+ * `ConfigLoadError` unconditionally never asked at all, so a `chmod 000` config
+ * and a typo produced the same sentence — and a permissions problem is not a
+ * broken config.
+ *
+ * 🔑 Asking it and still DEGRADING is deliberate, and was measured. Re-throwing
+ * so the per-entry guard anchors the finding is the obvious alternative and is
+ * worse: on a fixture with one unreadable config and one perfectly readable
+ * skill, the re-throw produced `filesScanned: 1, filesPassed: 0` with the finding
+ * anchored on `skills/demo/SKILL.md` and the skill never validated at all. On a
+ * real `--user` run that is hundreds of readable skills losing every check
+ * because one config is `chmod 000` — the exact "destroying" this lane exists to
+ * prevent, and a violation of the neighbouring promise that "a skill beside the
+ * unreadable path is validated exactly as if it were not there". The finding is
+ * filed on the CONFIG, which is the path that was actually refused, and the skill
+ * goes on to config-free validation.
+ *
+ * @returns the skill's display-safe packaging config, or `null` when there is
+ *   no governing config OR when the one found could not be loaded.
+ */
+async function resolveGoverningConfig(skillPath, logger, locationRoot) {
+    // The walk-up the resolver is about to do (cached), so the degrade handler can
+    // name the config whose include reached the directory. `null` means no config
+    // governs this skill; the resolver answers the same and nothing can be refused.
+    const configRoot = findProjectRoot(safePath.resolve(skillPath, '..'));
+    if (configRoot === null)
+        return null;
     let fullConfig;
     try {
-        fullConfig = await resolveSkillPackagingConfig(skillPath);
+        fullConfig = await resolveSkillPackagingConfig(skillPath, degradingDiscovery(configRoot, logger, locationRoot));
     }
     catch (err) {
-        if (!(err instanceof ConfigLoadError))
-            throw err;
-        logger.debug(`  Ignoring broken governing config for ${skillPath}: ${err.message}`);
-        fullConfig = null;
+        if (err instanceof ConfigLoadError) {
+            recordUnloadableConfig(err, logger, locationRoot);
+            return null;
+        }
+        // Unreachable while the resolver is handed `degradingDiscovery` above — the
+        // crawl then enumerates around a refused directory instead of throwing — but
+        // kept as the fallback for the default policy: same two channels, the skill
+        // goes on config-free rather than the run aborting.
+        if (err instanceof DirectoryListingRefusedError) {
+            recordRefusedDiscovery(err, configRoot, logger, locationRoot);
+            return null;
+        }
+        throw err;
     }
-    const skillConfig = fullConfig === null ? null : stripValidationAllowForDisplay(fullConfig);
+    return fullConfig === null ? null : stripValidationAllowForDisplay(fullConfig);
+}
+/**
+ * Configs this run has already degraded past — unloadable, or loaded but with a
+ * `skills.include` the crawl could not fully expand — keyed by the PATH that was
+ * refused (the config file, or the directory the crawl could not list), each
+ * holding the synthetic result that carries its finding into the report.
+ *
+ * 🚨 MODULE-scoped, and cleared by {@link resetAuditCaches}, exactly like
+ * `config-loader.ts`'s `warnedConfigPaths`. It used to be a `Set` threaded as a
+ * parameter, and the threading had a hole: `handleFileEntry` passed the scan's
+ * real log, but `validateSingleSkill` constructed a fresh `new Set()` on EVERY
+ * call — and `validatePluginSkillsViaInventory` calls it in a loop over every
+ * skill in a plugin. A 40-skill plugin under one unloadable config printed 40
+ * identical warnings. The integration fixture was a bare directory, which routes
+ * through `handleFileEntry`, so the "warns once, not once per skill" test passed
+ * while the lane that actually repeated was never exercised. A run-scoped ledger
+ * cannot be re-created per call by mistake; a parameter can.
+ *
+ * ⚠️ Keyed on the refused PATH (derived from `ConfigLoadError.projectRoot` or
+ * `DirectoryListingRefusedError.refusal.directory`), NOT on `err.message`. The
+ * old key was the message with a comment claiming it "names the offending config
+ * path" — true only for a Zod failure, which is what the fixture happened to be.
+ * A YAML SYNTAX error is thrown out of `yaml.parse` and wrapped as `Failed to
+ * load config: ${message}`, and `YAMLParseError.message` carries no filename at
+ * all, so two nested projects with the same copy-pasted broken config collapsed
+ * to ONE warning naming NEITHER.
+ */
+const unloadableConfigResults = new Map();
+/**
+ * The RUN's conventional-suite probe — the memo behind "does
+ * `<skill-root>/evals/evals.json` exist?".
+ *
+ * Resolving one skill's test input asks that question of the SUBJECT and of
+ * every entry in `projectSkills`, so a probe minted per skill costs S questions
+ * per skill and S² per run over the same S paths. Measured with the lab on a
+ * 103-skill adopter: 10,815 probes over 103 distinct paths, half of the
+ * command's entire filesystem traffic.
+ *
+ * 🚨 MODULE-scoped and cleared by {@link resetAuditCaches}, for the same reason
+ * `unloadableConfigResults` above is: this command has TWO lanes that build a
+ * shared context — {@link validateSingleSkill} and {@link handleFileEntry} — and
+ * both build it PER SKILL, inside their own loops. A probe threaded as a
+ * parameter would be re-minted by whichever lane forgot to thread it, silently,
+ * and that is exactly how this stayed quadratic: the field existed and no caller
+ * set it.
+ *
+ * ⚠️ Its lifetime is the RUN, never longer. The answer is a filesystem snapshot,
+ * and a memo outliving the invocation would keep answering for a tree that has
+ * since changed — in the CLI entrypoint AND in an in-process test sharing a
+ * vitest worker.
+ */
+let runSuiteProbe;
+/** The run's probe, minted on first use and dropped by {@link resetAuditCaches}. */
+function suiteProbeForRun() {
+    runSuiteProbe ??= conventionalSuiteProbe();
+    return runSuiteProbe;
+}
+/**
+ * Warn about — and file a finding for — a governing config this run could not
+ * load, once per config however many skills it governs.
+ *
+ * @param err - The load failure, carrying the project root that owns the config
+ * @param logger - Warnings go to stderr; the finding goes to the report
+ * @param locationRoot - The run's anchor base for the emitted location
+ */
+function recordUnloadableConfig(err, logger, locationRoot) {
+    const configPath = safePath.join(err.projectRoot, VAT_CONFIG_FILENAME);
+    if (unloadableConfigResults.has(configPath))
+        return;
+    unloadableConfigResults.set(configPath, unreadablePathResult(configPath, err, locationRoot));
+    // The filesystem answer changes the NOUN, because the two conditions need
+    // different actions from the operator: `chmod`/ownership on one side, an edit
+    // to the file on the other. Collapsing them into one sentence was the whole
+    // cost of never asking.
+    const why = isFilesystemAccessError(err) ? 'unreadable' : 'unloadable';
+    logger.warn(`Ignoring ${why} config at ${configPath}; skills it governs are validated`
+        + ` config-free: ${err.message}`);
+}
+/**
+ * Audit's discovery policy: enumerate AROUND a directory the crawl cannot list,
+ * report the gap, and keep every skill the crawl could see under its config.
+ *
+ * 🔑 This is what keeps ONE `chmod 000` sibling from costing a readable,
+ * declared skill every config-aware check. Discovery's default is to refuse —
+ * right for a build that must not ship a shorter bundle — but audit already
+ * validates "a skill beside the unreadable path exactly as if it were not
+ * there", and that promise is only kept if discovery degrades the same way the
+ * walk does. The refusal is recorded through the same ledger as an unloadable
+ * config, so it is warned about once and filed once however many skills ask.
+ *
+ * @param configRoot - The project root whose `skills.include` is being expanded
+ * @param logger - Warnings go to stderr; the finding goes to the report
+ * @param locationRoot - The run's anchor base for the emitted location
+ */
+function degradingDiscovery(configRoot, logger, locationRoot) {
+    return {
+        degrade: (refusal) => {
+            recordRefusedDiscovery(new DirectoryListingRefusedError(refusal, { root: configRoot, remedy: SKILLS_INCLUDE_REMEDY }), configRoot, logger, locationRoot);
+        },
+    };
+}
+/**
+ * Audit's ruling for the registry crawl — the link graph `crawlAndResolveRegistry`
+ * builds over the whole project root for the config-aware lane: enumerate
+ * AROUND a directory it cannot list, file the gap, keep every readable document.
+ *
+ * The other half of {@link degradingDiscovery}, on the other crawl the
+ * config-aware lane makes. Every other verb hands this crawl `'refuse'` (a build
+ * must not ship a shorter bundle), and while the registry carried that ruling
+ * INSIDE itself `vat audit` on a tree with one `chmod 000` sibling exited 2
+ * with `status: error` and ZERO findings — the unreadable-directory defect's
+ * exact shape, from the crawl its first fix never looked at. Audit's contract is the opposite:
+ * status describes what was found, exit describes whether the run completed.
+ *
+ * Recorded through the same per-directory ledger as a refused discovery, so a
+ * directory both crawls meet is warned about once and filed once; a directory
+ * only THIS crawl meets (the link graph covers the whole root, discovery only
+ * `skills.include`'s bases) gets its own sentence, naming the crawl that
+ * skipped it. The finding carries the projection's remedy — the same sentence
+ * the refuse ruling throws — because `--exclude` governs audit's own walk, not
+ * this crawl, and an ignore rule is the one knob that does.
+ *
+ * @param projectRoot - The root the link graph is crawled from
+ * @param logger - Warnings go to stderr; the finding goes to the report
+ * @param locationRoot - The run's anchor base for the emitted location
+ */
+function degradingRegistry(projectRoot, logger, locationRoot) {
+    return {
+        degrade: (refusal) => {
+            const err = new DirectoryListingRefusedError(refusal, { root: projectRoot, remedy: listingRefusalRemedy(projectRoot) });
+            recordRefusedListing(err, logger, locationRoot, () => `The link graph under ${projectRoot} skipped an unreadable directory; every document beneath it`
+                + ` is missing from this audit's link and reference checks: ${err.message}`);
+        },
+    };
+}
+/**
+ * Warn about — and file a finding for — a directory that skill discovery under
+ * `configRoot` could not list, once per directory however many skills ask.
+ *
+ * The finding is anchored on the DIRECTORY, not the config: the config loaded
+ * fine, and the directory is the path the filesystem refused. In the directory
+ * lane the walk's own per-entry guard files the same code on the same location;
+ * {@link dedupeUnreadablePathResults} keeps one. The warning carries the crawl's
+ * own sentence, which already names the directory against the project root and
+ * the `skills.include` remedy.
+ *
+ * @param err - The refusal, naming the directory the crawl could not list
+ * @param configRoot - The project root whose `skills.include` reached it
+ * @param logger - Warnings go to stderr; the finding goes to the report
+ * @param locationRoot - The run's anchor base for the emitted location
+ */
+function recordRefusedDiscovery(err, configRoot, logger, locationRoot) {
+    const configPath = safePath.join(configRoot, VAT_CONFIG_FILENAME);
+    recordRefusedListing(err, logger, locationRoot, () => `Skill discovery under ${configPath} skipped an unreadable directory; any skill beneath it`
+        + ` is missing from this audit: ${err.message}`);
+}
+/**
+ * The one ledger write for a refused listing, whichever crawl met it: file
+ * `SCAN_PATH_UNREADABLE` on the directory and warn once on stderr. Keyed on the
+ * refused directory, so the second crawl to meet it — discovery and the link
+ * graph both walk `skills/locked` in the directory lane — says nothing more.
+ *
+ * @param err - The refusal, naming the directory the crawl could not list
+ * @param logger - Warnings go to stderr; the finding goes to the report
+ * @param locationRoot - The run's anchor base for the emitted location
+ * @param warning - The stderr sentence, built only when this is the first record
+ */
+function recordRefusedListing(err, logger, locationRoot, warning) {
+    const directory = err.refusal.directory;
+    if (unloadableConfigResults.has(directory))
+        return;
+    unloadableConfigResults.set(directory, unreadablePathResult(directory, err, locationRoot));
+    logger.warn(warning());
+}
+/**
+ * The synthetic results for every config this run degraded past, so the report
+ * carries what the stderr warning says.
+ *
+ * Read, never drained: `resetAuditCaches()` owns the lifetime, and a drain would
+ * make the answer depend on which aggregation site ran first.
+ */
+function unloadableConfigFindings() {
+    return [...unloadableConfigResults.values()];
+}
+/**
+ * A run's results plus the findings for every config it degraded past, with each
+ * refused path reported once.
+ *
+ * Appended, not merged into a neighbour: a config the scan could not load, or a
+ * directory its discovery could not list, has no host result to hang off, and
+ * attributing it to a skill would name a file that was read fine. Without the
+ * append the ONLY record was a stderr warning, so a run that downgraded every
+ * skill under that config to the weaker config-free validator exited 0 with a
+ * report that said nothing about it. Deduped AFTER the append, because the
+ * directory lane's walk files its own `SCAN_PATH_UNREADABLE` on the very
+ * directory a refused discovery names — one fact, one finding, whichever lane
+ * met it first.
+ */
+function withDegradedConfigFindings(results) {
+    return dedupeUnreadablePathResults([...results, ...unloadableConfigFindings()]);
+}
+async function validateSingleSkill(skillPath, options, logger, locationRoot, crawlTree, isVATGenerated) {
+    // Config-aware validation: walk UP to the skill's nearest-ancestor
+    // vibe-agent-toolkit.config.yaml and apply the skill's packaging block. A
+    // config that cannot be loaded is treated as absent — see
+    // {@link resolveGoverningConfig}, which both audit lanes share so they cannot
+    // disagree about that again. The warn-once ledger is run-scoped module state,
+    // NOT a set minted here — a fresh `new Set()` on this line is what made a
+    // 40-skill plugin print 40 identical warnings.
+    const skillConfig = await resolveGoverningConfig(skillPath, logger, locationRoot);
     if (skillConfig !== null) {
         logger.debug(`  Using config-aware validation for: ${skillPath}`);
         const { gitTracker } = await resolveScanContext(safePath.resolve(skillPath), locationRoot, logger);
@@ -188,10 +464,18 @@ async function validateSingleSkill(skillPath, options, logger, locationRoot, cra
         // 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.
+        // Audit's ruling for the link-graph crawl — see {@link degradingRegistry}.
+        // Stated on the context too, for the fallback crawl `validateSkillForPackaging`
+        // makes when this registry does not cover the skill: one ruling, both crawls.
+        const unreadable = degradingRegistry(projectRoot, logger, locationRoot);
         const sharedCtx = {
-            registry: await crawlAndResolveRegistry(projectRoot),
+            registry: await crawlAndResolveRegistry(projectRoot, { unreadable }),
+            unreadable,
             locationRoot,
-            projectSkills: await resolveProjectDeclaredEvalSuites(skillPath),
+            projectSkills: await resolveProjectDeclaredEvalSuites(skillPath, degradingDiscovery(projectRoot, logger, locationRoot)),
+            // The RUN's probe, not this call's — see {@link runSuiteProbe}. This lane
+            // is called in a loop over every skill in a plugin.
+            suiteProbe: suiteProbeForRun(),
         };
         if (gitTracker !== null) {
             sharedCtx.gitTracker = gitTracker;
@@ -201,8 +485,8 @@ async function validateSingleSkill(skillPath, options, logger, locationRoot, cra
         await appendDistributedTreeFindings(configAware, skillPath, locationRoot, crawlTree);
         return configAware;
     }
-    // Fallback: basic validation
-    const validateOptions = { skillPath, locationRoot };
+    // Fallback: basic validation. Severity is applied by `applySeverityFilter`.
+    const validateOptions = { skillPath, locationRoot, validation: {} };
     if (options.warnUnreferencedFiles) {
         validateOptions.checkUnreferencedFiles = true;
     }
@@ -248,6 +532,14 @@ function collect(value, previous) {
 /**
  * Create audit command
  * Top-level command: vat audit [path]
+ *
+ * The exit code follows the document's `status`, under the one exit-code
+ * contract every verb shares: `OK` when nothing is at error severity,
+ * `FINDINGS` when something is (or the run audited zero files), `ERROR` when
+ * the audit could not run at all. This command used to be the one exception —
+ * "advisory", exit 0 over `status: error` — which a CI author reading the
+ * shared contract got wrong on exactly this verb. Warnings never move the
+ * exit code; `validation.severity` is the dial that decides what counts.
  */
 export function createAuditCommand() {
     const audit = new Command('audit');
@@ -314,11 +606,20 @@ Description:
     done
   (See packages/cli/docs/audit.md for details.)
 
+Output:
+  The YAML 'status' describes the findings, and the exit code follows it, as
+  in every other command of this CLI.
+
+  A run that audited ZERO files is refused, not passed: 'status: error' with one
+  non-overridable RESOURCE_CHECK_BROKEN under a top-level 'issues:' (the claim is
+  about the run, so it is not a files[] row), and exit 1.
+
 Validation Behavior:
-  Advisory only: audit surfaces all validation issues for inspection.
+  Audit surfaces all validation issues for inspection.
   Unlike 'vat skills validate', audit:
   - NEVER applies validation.allow (allowed codes are always shown)
-  - Respects validation.severity: codes set to 'ignore' are hidden
+  - Respects validation.severity: a code set to 'ignore' is hidden; warnings
+    and errors are both reported, each at its configured severity
   - ALWAYS exits 0 for validation results (never gates on errors)
 
   For gated validation (CI/CD), use: vat skills validate
@@ -338,11 +639,16 @@ Validation Checks:
 
   Warnings (should fix):
   - Skill exceeds recommended length (>5000 lines)
-  - Compat smells — requires browser auth, local shell, or external CLI
-    (COMPAT_REQUIRES_BROWSER_AUTH, COMPAT_REQUIRES_LOCAL_SHELL,
-    COMPAT_REQUIRES_EXTERNAL_CLI). See docs/validation-codes.md.
+  - With --compat: a declared target cannot or may not run the skill
+    (COMPAT_TARGET_INCOMPATIBLE, COMPAT_TARGET_NEEDS_REVIEW)
   - Unreferenced files detected (with --warn-unreferenced-files)
 
+  Info (observations):
+  - Capability observations — browser auth, local shell, or external CLI
+    (CAPABILITY_BROWSER_AUTH, CAPABILITY_LOCAL_SHELL, CAPABILITY_EXTERNAL_CLI);
+    with --compat, a skill declaring no targets (COMPAT_TARGET_UNDECLARED).
+    See docs/validation-codes.md.
+
 Gitignore-Aware Scanning:
   When scanning inside a git repository, paths matched by .gitignore are
   skipped by default. This excludes build artifacts (dist/), dependencies
@@ -352,8 +658,9 @@ Gitignore-Aware Scanning:
   Use --include-artifacts to scan gitignored paths (e.g., to audit a
   bundled marketplace plugin in dist/).
 
-  User-supplied --exclude patterns are always applied on top.
-  Outside a git repository, no automatic exclusions apply.
+  User-supplied --exclude patterns are always applied on top. The
+  directories no VAT crawl enters (node_modules/, .git/, coverage/,
+  .turbo/, git worktrees) stay out under every flag, in or out of git.
 
 Config-Aware Validation:
   The governing vibe-agent-toolkit.config.yaml is found by walking UP from
@@ -363,14 +670,29 @@ Config-Aware Validation:
   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 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.
+  all issues. validation.severity IS applied, from three scopes, least
+  specific first:
+    resources.validation.severity          project-wide (the same dial
+                                           'vat resources validate' reads)
+    skills.defaults.validation.severity    project-wide (skills, plugins and
+                                           marketplaces alike)
+    skills.config.<name>.validation...     that one skill
 
 Exit Codes:
-  0 - Always (even when validation errors are surfaced)
-  2 - System error (config invalid, directory not found)
+  0 - The audit completed with nothing at error severity (warnings and
+      informational findings are in the report, not the exit code).
+  1 - The audit completed and reports 'status: error': at least one
+      error-severity finding, or zero files audited. A path inside the tree
+      the scan could not read, or a governing config that cannot be loaded
+      or whose skills.include reaches an unreadable directory, is
+      SCAN_PATH_UNREADABLE (warning): the run is degraded, not failed —
+      readable siblings are still validated, the config's skills
+      config-free, and the refused path is not counted in filesScanned (so
+      a root with nothing readable is a zero-files refusal).
+  2 - The audit could not run at all: the path does not exist or is a file
+      no audit lane recognises, --user with no Claude config dir, a git URL
+      that would not clone, an unknown flag, an internal failure. There is
+      no report to read.
 
 Examples:
   $ vat audit ./plugins/              # Audit recursively (default)
@@ -424,11 +746,8 @@ async function auditUserDirectories(recursive, options, startTime, logger) {
     // --user scans three sibling directories; they share ONE enclosing Claude
     // config dir, so that is the run's single stated root.
     const scanRoot = safePath.resolve(claudeDir);
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- safe: path constructed from os.homedir()
     const pluginsDirExists = fs.existsSync(pluginsDir);
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- safe: path constructed from os.homedir()
     const skillsDirExists = fs.existsSync(skillsDir);
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- safe: path constructed from os.homedir()
     const marketplacesDirExists = fs.existsSync(marketplacesDir);
     if (!pluginsDirExists && !skillsDirExists && !marketplacesDirExists) {
         logger.error(`No user-level Claude directories found:`);
@@ -436,9 +755,9 @@ async function auditUserDirectories(recursive, options, startTime, logger) {
         logger.error(`  Skills: ${skillsDir}`);
         logger.error(`  Marketplaces: ${marketplacesDir}`);
         logger.error('Claude plugins/skills/marketplaces have not been installed yet.');
-        process.exit(2);
+        process.exit(ExitCode.ERROR);
     }
-    const results = [];
+    const scanned = [];
     // The roots that exist, minus any one another already covers — see
     // {@link userScanTargets}. `marketplaces/` lives inside `plugins/`.
     const present = [
@@ -448,8 +767,12 @@ async function auditUserDirectories(recursive, options, startTime, logger) {
     ];
     for (const target of userScanTargets(present, recursive)) {
         logger.debug(`Auditing user-level resources at: ${target}`);
-        results.push(...await getValidationResults(target, recursive, options, logger, scanRoot));
+        scanned.push(...await getValidationResults(target, recursive, options, logger, scanRoot));
     }
+    // The `--user` report is assembled here rather than by `buildAuditReport`, so
+    // it needs its own append or the config findings would reach stderr and not the
+    // document — see the same call in `buildAuditReport`.
+    const results = withDegradedConfigFindings(scanned);
     // Run compatibility analysis if --compat flag is set
     const compatMap = options.compat
         ? await runCompatAnalysis(results, logger, scanRoot) // --settings not supported in --user mode
@@ -462,7 +785,7 @@ async function auditUserDirectories(recursive, options, startTime, logger) {
     if (verbose) {
         renderVerboseEvidence(results, scanRoot, logger);
     }
-    logHierarchicalSummary(results, logger);
+    logHierarchicalSummary(results, summary.issues, logger);
 }
 /** Skill resource types that can have per-skill validation config. */
 const SKILL_RESULT_TYPES = new Set([RESOURCE_TYPE_AGENT_SKILL, 'vat-agent']);
@@ -486,7 +809,6 @@ const SKILL_RESULT_TYPES = new Set([RESOURCE_TYPE_AGENT_SKILL, 'vat-agent']);
  */
 export function deriveScanRoot(targetPath) {
     const resolved = safePath.resolve(targetPath);
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- resolved is the operator's own audit target
     const isDirectory = fs.existsSync(resolved) && fs.statSync(resolved).isDirectory();
     return isDirectory ? resolved : safePath.resolve(resolved, '..');
 }
@@ -534,7 +856,7 @@ function buildFilteredResult(result, filteredIssues) {
 /**
  * Apply severity resolution to validation results.
  *
- * Audit is advisory only: it applies `validation.severity` to decide what to
+ * Audit shows everything: it applies `validation.severity` to decide what to
  * show and at what severity, but deliberately ignores `validation.allow`.
  *
  * **Both directions, via the one shared resolver.** This used to compute the
@@ -546,13 +868,21 @@ function buildFilteredResult(result, filteredIssues) {
  * 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:
+ * {@link buildFilteredResult}, so a promotion moves the reported STATUS — which
+ * describes the findings — and never the exit code, which describes whether the
+ * run completed. The two are different questions and audit publishes both; see
+ * {@link handleAuditResults} and the `Output` section of this command's help.
+ * `vat verify` derives its exit code from severity because it is a gate; this
+ * command is a report.
+ *
+ * THREE scopes, least specific first:
+ *  - `resources.validation.severity` — the PROJECT-WIDE map `vat resources
+ *    validate` already honours. Audit read only the two `skills.*` scopes below,
+ *    so one dial in one config file produced opposite answers from the two
+ *    commands: measured on a two-code fixture, `LINK_MISSING_TARGET: ignore` and
+ *    `LINK_TO_NAVIGATION_FILE: error` written here moved neither finding in
+ *    audit. It is applied FIRST — a `skills` scope naming the same code is the
+ *    more specific statement and wins.
  *  - `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
@@ -587,18 +917,27 @@ function buildFilteredResult(result, filteredIssues) {
  * @returns New results array with ignored codes removed from issues
  */
 function applySeverityFilter(results, config) {
-    if (config?.skills === undefined) {
-        return results;
-    }
-    const skillsConfig = config.skills;
-    const defaultSeverity = skillsConfig.defaults?.validation?.severity ?? {};
+    const skillsConfig = config?.skills;
+    // NOT gated on `config.skills` existing. It was, and that made the resources
+    // dial below inert for exactly the projects that have only one — a repo of
+    // plugins declares no skills at all.
+    const resourceSeverity = config?.resources?.validation?.severity ?? {};
+    const defaultSeverity = skillsConfig?.defaults?.validation?.severity ?? {};
+    const projectSeverity = { ...resourceSeverity, ...defaultSeverity };
+    // `.filter` after `.map`, not `.map` alone: a synthetic unreadable-path result
+    // exists ONLY to carry its finding, so once the adopter has set
+    // `severity.SCAN_PATH_UNREADABLE: ignore` the result has nothing left to say.
+    // Keeping it published `status: success` for a path the scan never read — the
+    // report positively asserting that an unread path PASSED, which is a stronger
+    // falsehood than the count inflation noted on `unreadablePathResult`. Dropping
+    // it is what "ignore" already means everywhere else.
     return results.map(result => {
         const skillName = SKILL_RESULT_TYPES.has(result.type) ? result.metadata?.name : undefined;
         const perSkillSeverity = skillName === undefined
             ? {}
-            : (skillsConfig.config?.[skillName]?.validation?.severity ?? {});
-        // Merge: per-skill overrides default
-        const effectiveSeverity = { ...defaultSeverity, ...perSkillSeverity };
+            : (skillsConfig?.config?.[skillName]?.validation?.severity ?? {});
+        // Merge, least specific first: resources → skills.defaults → skills.config.<name>
+        const effectiveSeverity = { ...projectSeverity, ...perSkillSeverity };
         if (Object.keys(effectiveSeverity).length === 0) {
             return result;
         }
@@ -614,7 +953,21 @@ function applySeverityFilter(results, config) {
             return result;
         }
         return buildFilteredResult(result, resolvedIssues);
-    });
+    }).filter(result => !isEmptiedUnreadablePathResult(result));
+}
+/**
+ * A synthetic unreadable-path result whose only finding was ignored away.
+ *
+ * Keyed on the shape this module itself produces — `type: 'unknown'`, no
+ * metadata, and now no issues — rather than on a marker field, because
+ * `ValidationResult` is a shared contract and this is the one producer that needs
+ * to be recognised. A genuinely-unknown resource from `unified-validator` carries
+ * metadata or issues and is unaffected.
+ */
+function isEmptiedUnreadablePathResult(result) {
+    return result.type === 'unknown'
+        && result.issues.length === 0
+        && result.metadata === undefined;
 }
 /**
  * Resolve `--settings`-driven EffectiveSettings if both --settings and
@@ -647,17 +1000,47 @@ export async function buildAuditReport(scanPath, options, startTime, logger) {
     const recursive = options.recursive !== false;
     logger.debug(`Auditing resources at: ${scanPath}`);
     const scanRoot = deriveScanRoot(scanPath);
-    const rawResults = await getValidationResults(scanPath, recursive, options, logger, scanRoot);
+    const scanned = await getValidationResults(scanPath, recursive, options, logger, scanRoot);
+    // Build config-aware context scoped to the single derived config root —
+    // used by compat analysis to resolve the plugin-level `targets` union.
+    // VAT's design: one config per project, no composition.
+    //
+    // BEFORE the report is assembled, not after: this is the lane that expands
+    // `skills.include` even when the scan reached no SKILL.md under the config,
+    // and a refusal it meets is recorded in the same ledger the append below
+    // reads. Built afterwards, that finding reached stderr and not the document.
+    const vatContextForCompat = await buildVATProjectContext(deriveConfigRoot(scanPath), logger, scanRoot);
+    // See {@link withDegradedConfigFindings} for why these are appended, not merged.
+    const rawResults = withDegradedConfigFindings(scanned);
     // Load config for severity filtering (audit ignores allow; only severity matters).
-    const config = loadConfig(deriveConfigRoot(scanPath));
+    //
+    // Guarded, and the ordering is why: the scan above has ALREADY run and collected
+    // every finding by this point. An unreadable or malformed config here threw past
+    // all of it and ended the command with `status: error` and zero findings —
+    // discarding completed work to report a problem with a file that only decides
+    // which findings to *hide*. Every other `loadConfig` in this file is already
+    // wrapped for the same reason; this one was missed.
+    //
+    // Falling back to no config means no severity overrides are applied, so findings
+    // are reported at their default severity. That is the safe direction: it can
+    // only show more than the adopter asked for, never less.
+    let config;
+    try {
+        config = loadConfig(deriveConfigRoot(scanPath));
+    }
+    catch (err) {
+        // `warn`, not `debug`. Falling back to no config is the safe direction — it
+        // can only show more than the adopter asked for, never less — but it means
+        // every `validation.severity` override they wrote is silently inert. Before
+        // this guard the command failed loudly and told them; degrading without a word
+        // would trade a crash for a config that quietly stopped working, which is the
+        // harder problem to notice.
+        logger.warn(`Config could not be read; severity overrides are not applied: ${String(err)}`);
+    }
     // Apply severity filtering: hide codes whose effective severity is 'ignore'.
-    // Allow is deliberately NOT applied — audit is advisory only.
+    // Allow is deliberately NOT applied — audit shows every finding.
     const results = applySeverityFilter(rawResults, config);
     const effectiveSettings = await resolveEffectiveSettings(options, scanPath, logger);
-    // Build config-aware context scoped to the single derived config root —
-    // used by compat analysis to resolve the plugin-level `targets` union.
-    // VAT's design: one config per project, no composition.
-    const vatContextForCompat = await buildVATProjectContext(deriveConfigRoot(scanPath), logger);
     // Run compatibility analysis if --compat flag is set
     const compatMap = options.compat
         ? await runCompatAnalysis(results, logger, scanRoot, effectiveSettings, vatContextForCompat)
@@ -718,7 +1101,6 @@ export async function auditCommand(targetPath, options) {
         // cloned https://github.com/<that>.git instead, reaching out to the
         // network with a name derived from the caller's own directory layout.
         // Shorthand is a fallback for arguments that name nothing on disk.
-        // eslint-disable-next-line security/detect-non-literal-fs-filename -- targetPath is the user's own audit target; existence is the question being asked
         if (targetPath !== undefined && !fsExistsSync(targetPath) && isGitUrl(targetPath)) {
             await runUrlAudit(targetPath, options);
             return;
@@ -730,11 +1112,55 @@ export async function auditCommand(targetPath, options) {
             return;
         }
         const scanPath = targetPath ? safePath.resolve(targetPath) : process.cwd();
+        const unusable = await unusableRootReason(scanPath);
+        if (unusable !== undefined) {
+            // `return` the call though its type is `never`: under test `process.exit`
+            // is a spy that returns, and a bare call would fall through into the scan.
+            return handleExpectedFailure(unusable, ExitCode.ERROR, startTime);
+        }
         await runAuditAtPath(scanPath, options);
     }
     catch (error) {
-        handleCommandError(error, logger, startTime, 'AgentAudit');
+        // 'Audit', not 'AgentAudit'. The old name was copy-pasted from the agent
+        // command family and named a command that does not exist, so the one line an
+        // operator has to search for did not match what they typed.
+        handleCommandError(error, logger, startTime, 'Audit');
+    }
+}
+/**
+ * Why the ROOT argument cannot be audited at all, or `undefined` when the scan
+ * may start.
+ *
+ * The exit-code contract every verb shares: a path that does not exist, or a
+ * file no audit lane recognises, is the INVOCATION's mistake — `ExitCode.ERROR`
+ * (2) before any scan, the same ending `vat resources validate` and `vat skill
+ * review` give the same argument. Until this check the audit ran anyway and
+ * published `UNKNOWN_FORMAT` as a finding at exit 1 with `filesScanned: 1`: a
+ * typo in a CI step read as "the tree failed its gate", and the denominator
+ * counted a file that was never there.
+ *
+ * ONLY the root, and only these two conditions. A root the OS refuses to stat
+ * is not answered here — the scan degrades it to `SCAN_PATH_UNREADABLE`, which
+ * is not counted as a scanned file, so a tree with nothing readable ends on the
+ * zero-files refusal (exit 1) like any other tree that yielded nothing. A
+ * sub-path inside a readable tree is never the invocation's fault and stays a
+ * finding. Pinned by the `audit → error` rows of `exit-codes.system.test.ts`.
+ */
+async function unusableRootReason(scanPath) {
+    let isDirectory;
+    try {
+        isDirectory = fs.lstatSync(scanPath).isDirectory();
+    }
+    catch (error) {
+        if (isPathAbsentError(error))
+            return `Path does not exist: ${scanPath}`;
+        return undefined;
     }
+    if (isDirectory || detectFormat(scanPath) === RESOURCE_TYPE_AGENT_SKILL)
+        return undefined;
+    if ((await detectResourceFormat(scanPath)).type !== 'unknown')
+        return undefined;
+    return `Path is not a resource this command can audit (a SKILL.md, a plugin or marketplace directory, or a Claude registry file): ${scanPath}`;
 }
 /**
  * Dispatch a single surface to the matching validator. Keeps the multi-surface
@@ -788,7 +1214,7 @@ async function runInventoryDetectors(scanPath, type, locationRoot, prebuiltInv)
         ];
     }
     if (type === 'marketplace') {
-        const inv = prebuiltInv?.kind === 'marketplace' ? prebuiltInv : await extractClaudeMarketplaceInventory(scanPath);
+        const inv = prebuiltInv?.kind === 'marketplace' ? prebuiltInv : await extractClaudeMarketplaceInventory(scanPath, { gitTrackerSource: gitTrackerForProjectRoot });
         return detectMarketplacePluginSourceMissing(inv, locationRoot);
     }
     return [];
@@ -838,22 +1264,50 @@ async function appendPluginInventoryToSurfaceResults(surfaceResults, scanPath, l
 }
 /**
  * Surface `inventory.parseErrors[]` as `PLUGIN_INVALID_JSON` findings on
- * `result`, skipping the plugin.json manifest entry (which is already covered
- * by `validatePlugin`). Only hooks/hooks.json and .mcp.json parse errors reach
- * this helper; they are appended with error severity.
+ * `result`, skipping the entries another lane already files under their own
+ * code:
+ *
+ * - the plugin.json manifest entry, covered by `validatePlugin`;
+ * - every `SKILL.md` entry. The skill extractor records a SKILL.md it could
+ *   not open, could not parse, or could not link-walk on the plugin's
+ *   `parseErrors[]` — and each of those is the SKILL's finding, filed on the
+ *   skill by its own validation (`SCAN_PATH_UNREADABLE`,
+ *   `SKILL_MISSING_FRONTMATTER`) in both the plugin-target lane
+ *   (`validatePluginSkillsViaInventory`, over the same inventory) and the
+ *   directory lane (the walk reaches every SKILL.md beneath the plugin).
+ *   Re-filing it here was a second copy under a code that names a file it is
+ *   not (plugin.json) and a format it is not (JSON), at error severity beside
+ *   the skill lane's warning, and carrying the build host's absolute path.
+ *
+ * What remains — hooks/hooks.json, .mcp.json, a directory the crawl could not
+ * list — is appended with error severity when the SUBJECT is defective, and
+ * as `SCAN_PATH_UNREADABLE` (warning) when the row is marked `unreadable`
+ * (the OS refused the path); the message is spelled scan-root-relative
+ * wherever it names the file.
  */
 function appendInventoryParseErrors(result, inv, locationRoot) {
     const pluginJsonSuffix = safePath.join('.claude-plugin', 'plugin.json');
+    // One refused path, one refusal: the distributed-tree detector crawls the
+    // same directories and files the ones it cannot list on this same result.
+    const refusalsFiled = new Set(result.issues.filter((issue) => issue.code === 'SCAN_PATH_UNREADABLE').map((issue) => issue.location));
     const parseIssues = [];
     for (const err of inv.parseErrors) {
-        if (err.path.endsWith(pluginJsonSuffix))
+        if (err.path.endsWith(pluginJsonSuffix) || basename(err.path) === 'SKILL.md')
             continue;
-        parseIssues.push({
-            severity: 'error',
-            code: 'PLUGIN_INVALID_JSON',
-            message: err.message,
-            location: issueLocation(err.path, locationRoot),
-        });
+        const message = withRelativePath(err.message, err.path, locationRoot);
+        const location = issueLocation(err.path, locationRoot);
+        if (err.unreadable !== true) {
+            parseIssues.push({ severity: 'error', code: 'PLUGIN_INVALID_JSON', message, location });
+            continue;
+        }
+        // A path the OS refused was not examined; that is the run degrading, not
+        // a defect of the plugin, and it is filed at the severity every other lane
+        // gives a refusal. Under `PLUGIN_INVALID_JSON` (error) an `EACCES` on one
+        // skill directory failed the whole audit over a mode bit.
+        if (refusalsFiled.has(location))
+            continue;
+        refusalsFiled.add(location);
+        parseIssues.push(materializeIssue('SCAN_PATH_UNREADABLE', { location, detail: `${location}: ${message}` }));
     }
     // Status was hand-set to 'error' here while `issueCounts` and `summary` kept
     // describing the pre-append list. One appender derives all three.
@@ -869,7 +1323,119 @@ function appendInventoryParseErrors(result, inv, locationRoot) {
  *   location reads, or a run spanning several configs emits one document in
  *   several coordinate systems. Recursion passes it through unchanged.
  */
+/**
+ * Validate ONE audit subject, degrading if the filesystem refuses it.
+ *
+ * THE boundary guard, and deliberately the only one of its kind. The first
+ * version of this fix guarded the directory walk alone, which left every other
+ * way into a validator unprotected: a `SKILL.md` named directly on the command
+ * line, a plugin directory, a marketplace, each surface of a multi-surface tree.
+ * All of them still ended the whole run with `status: error`, exit 2 and zero
+ * findings — the exact symptom of the unreadable-directory defect, in the lanes
+ * nobody had checked.
+ *
+ * Guarding the seven dispatch sites individually would have been the same mistake
+ * a seventh time. This function is what every one of them is reached through, so
+ * it is where "the environment refused this subject" becomes a finding instead of
+ * an abort. It is also the recursion point — `recurseIntoMarketplacePlugins` and
+ * the `--user` target loop both re-enter here — so an unreadable plugin costs its
+ * own subject and nothing else.
+ *
+ * The walk keeps its own per-entry guard: this one would answer at whole-subject
+ * granularity, discarding findings already collected from readable siblings, and
+ * degrading as narrowly as possible is the entire point.
+ */
 export async function getValidationResults(scanPath, recursive, options, logger, locationRoot) {
+    try {
+        return dedupeUnreadablePathResults(await validateAuditSubject(scanPath, recursive, options, logger, locationRoot));
+    }
+    catch (error) {
+        // Only the filesystem refusing the subject degrades; a defect in a validator
+        // must still fail loudly rather than be reported as a permissions problem.
+        if (!isFilesystemAccessError(error))
+            throw error;
+        logger.debug(`Unreadable audit subject: ${scanPath}`);
+        return [unreadablePathResult(scanPath, error, locationRoot)];
+    }
+}
+/**
+ * One refused path, one `SCAN_PATH_UNREADABLE` — however many lanes met it.
+ *
+ * Two lanes can reach the same unreadable directory in one run: the directory
+ * walk (`scanDirectory`, which files the synthetic {@link unreadablePathResult})
+ * and the distributed-tree detector, which crawls a skill's own directory at any
+ * depth and reports what it could not list as an issue ON the skill's result.
+ * Their populations overlap, but neither contains the other: the walk skips
+ * what `--exclude`, the project's `resources.exclude` and gitignore skip, and
+ * does not descend at all under `--no-recursive` or when the SKILL.md is named
+ * directly — the detector enters all of those. So "the walk already reports
+ * everything under the scan root" is false in both directions, and a rule that
+ * silenced one lane by geography would drop the refusal in exactly the cases
+ * where it is the only report. The rule is instead keyed on the FACT: the
+ * code and the location, which both lanes derive from the same directory and
+ * the same anchor root.
+ *
+ * The hosted issue wins and the synthetic result is dropped, not the reverse:
+ * the detector's copy says which SKILL's crawl was cut short, which the
+ * synthetic result cannot, and it is the only copy the direct-target lane ever
+ * produces — so keeping it makes the two lanes' reports the same shape. A
+ * synthetic result that carried nothing but the duplicate is removed whole; one
+ * that somehow carried more keeps its other issues (it cannot today, but the
+ * filter says what it means rather than assuming).
+ *
+ * A THIRD lane files synthetic results too: skill discovery under a governing
+ * config, which refuses a directory its `skills.include` cannot list and is
+ * recorded through {@link recordRefusedDiscovery}. In the directory lane the
+ * walk has already filed its own synthetic result on that same directory, so
+ * two synthetic results can carry one fact. Among synthetics the FIRST wins and
+ * later copies of the same location are dropped — the walk's copy carries the
+ * raw errno, the discovery's copy the crawl's remedy sentence, and the stderr
+ * warning carries the latter either way.
+ */
+function dedupeUnreadablePathResults(results) {
+    const reported = new Set();
+    for (const result of results) {
+        if (result.type === 'unknown')
+            continue;
+        for (const issue of result.issues) {
+            if (issue.code === 'SCAN_PATH_UNREADABLE')
+                reported.add(issue.location ?? '');
+        }
+    }
+    return results.flatMap((result) => {
+        if (result.type !== 'unknown')
+            return [result];
+        const kept = withoutHostedRefusals(result, reported);
+        for (const survivor of kept) {
+            for (const issue of survivor.issues) {
+                if (issue.code === 'SCAN_PATH_UNREADABLE')
+                    reported.add(issue.location ?? '');
+            }
+        }
+        return kept;
+    });
+}
+/**
+ * A synthetic result minus the refusals some hosted result already carries —
+ * as an empty array when nothing is left, so {@link dedupeUnreadablePathResults}
+ * can `flatMap` it away.
+ */
+function withoutHostedRefusals(result, hosted) {
+    const issues = result.issues.filter((issue) => !(issue.code === 'SCAN_PATH_UNREADABLE' && hosted.has(issue.location ?? '')));
+    if (issues.length === 0)
+        return [];
+    if (issues.length === result.issues.length)
+        return [result];
+    const issueCounts = countBySeverity(issues);
+    return [{
+            ...result,
+            status: calculateValidationStatus(issues),
+            summary: formatCountsSummary(issueCounts),
+            issues,
+            issueCounts,
+        }];
+}
+async function validateAuditSubject(scanPath, recursive, options, logger, locationRoot) {
     const format = detectFormat(scanPath);
     // Special handling for direct SKILL.md file
     if (format === RESOURCE_TYPE_AGENT_SKILL) {
@@ -923,7 +1489,7 @@ export async function getValidationResults(scanPath, recursive, options, logger,
             // recursion into co-located, path-source plugins. discovered.plugins[]
             // is populated only for path sources that exist on disk (git/npm/unknown
             // sources are declarations only and stay out of scope).
-            const marketplaceInv = await extractClaudeMarketplaceInventory(scanPath);
+            const marketplaceInv = await extractClaudeMarketplaceInventory(scanPath, { gitTrackerSource: gitTrackerForProjectRoot });
             const marketplaceInventoryIssues = await runInventoryDetectors(scanPath, 'marketplace', locationRoot, marketplaceInv);
             appendIssues(result, marketplaceInventoryIssues);
             logger.debug(`Inventory detectors emitted ${marketplaceInventoryIssues.length.toString()} issues for marketplace at ${scanPath}`);
@@ -933,26 +1499,45 @@ export async function getValidationResults(scanPath, recursive, options, logger,
         return [result];
     }
     // If unknown format, check if it's a directory we can scan
-    const fsp = await import('node:fs/promises');
-    try {
-        const stat = await fsp.stat(scanPath);
-        if (stat.isDirectory()) {
-            logger.debug('Scanning directory for resources');
-            // 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 {
-        // Path doesn't exist or not accessible, let validate() handle it
+    if (await isScannableDirectory(scanPath)) {
+        logger.debug('Scanning directory for resources');
+        // 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));
     }
     // Unknown resource type - use unified validator which will return appropriate error
     logger.debug(`Unknown resource type at: ${scanPath}`);
     const result = await validate(scanPath, { locationRoot });
     return [result];
 }
+/**
+ * Whether `scanPath` is a directory the walk can enter.
+ *
+ * `false` for a file and for NOTHING — `validate()` then names the path as
+ * unknown or absent, which is the answer the operator can act on. A refusal on
+ * the stat is neither: it propagates to `getValidationResults`, whose own catch
+ * files it as `SCAN_PATH_UNREADABLE`, so the audit still degrades (the run
+ * completes, the refusal a finding) rather than refusing the run.
+ *
+ * 🪤 The stat used to share ONE `try` with `scanDirectory` itself, and the
+ * catch was bare. Every throw from the scan — a crawl refusal, a `TypeError`
+ * two frames down — was absorbed into "let validate() handle it", and
+ * `validate()` then reported the directory as an unknown resource format. A
+ * scan that examined nothing was reported as a directory that was nothing.
+ */
+async function isScannableDirectory(scanPath) {
+    const fsp = await import('node:fs/promises');
+    try {
+        return (await fsp.stat(scanPath)).isDirectory();
+    }
+    catch (error) {
+        if (isPathAbsentError(error))
+            return false;
+        throw error;
+    }
+}
 /**
  * Inventory-driven plugin skill walker. Builds the plugin inventory via
  * `extractClaudePluginInventory` and dispatches `validateSingleSkill` for each
@@ -972,9 +1557,26 @@ async function validatePluginSkillsViaInventory(scanPath, options, logger, locat
             continue;
         }
         logger.debug(`  Validating plugin-bundled skill (inventory): ${skill.files.skillMd}`);
-        // 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));
+        // Guarded PER SKILL, not left to the boundary. The boundary guard answers at
+        // whole-subject granularity, so one unreadable bundled `SKILL.md` discarded
+        // the plugin's own manifest findings and every readable sibling skill with
+        // it — 4 results down to 1 — and anchored the finding at the plugin root,
+        // which is perfectly readable. That contradicted this code's own promise
+        // that an unreadable path "costs its own subject and nothing else", and the
+        // documented promise that "a skill beside the unreadable path is validated
+        // exactly as if it were not there". Degrading as narrowly as the structure
+        // allows is the whole point; here the skill is the unit.
+        try {
+            // 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));
+        }
+        catch (error) {
+            if (!isFilesystemAccessError(error))
+                throw error;
+            logger.debug(`  Unreadable plugin-bundled skill: ${skill.files.skillMd}`);
+            results.push(unreadablePathResult(skill.files.skillMd, error, locationRoot));
+        }
     }
     return results;
 }
@@ -1001,9 +1603,9 @@ function resolveConfigTargetsForPlugin(pluginDir, vatContext) {
     const union = new Set();
     for (const [skillPathAbs, packagingConfig] of vatContext.skillConfigs) {
         const rel = safePath.relative(pluginDirAbs, skillPathAbs);
-        // Skill lives inside the plugin directory iff relative path does not
-        // start with '..' and is not absolute.
-        if (rel === '' || rel.startsWith('..') || isAbsolutePath(rel))
+        // Skill lives inside the plugin directory iff the relative path neither
+        // climbs out nor (on Windows, cross-drive) comes back absolute.
+        if (rel === '' || relativeEscapesRoot(rel))
             continue;
         const skillTargets = packagingConfig.targets;
         if (skillTargets === undefined)
@@ -1015,7 +1617,15 @@ function resolveConfigTargetsForPlugin(pluginDir, vatContext) {
     return union.size === 0 ? undefined : [...union];
 }
 /**
- * Run compatibility analysis on plugin results and return a map of path -> CompatibilityResult.
+ * `message`, with `absolutePath` spelled root-relative wherever it appears.
+ * An OS refusal names the path it refused, absolutely; every other path in
+ * the document is relative to `root`, and this one leaks the build host.
+ */
+function withRelativePath(message, absolutePath, locationRoot) {
+    return message.replaceAll(absolutePath, issueLocation(absolutePath, locationRoot) || '.');
+}
+/**
+ * Run compatibility analysis on plugin results and return a map of path -> PluginCompatEntry.
  * Non-plugin results are skipped silently.
  * When effectiveSettings is provided, also runs settings conflict detection.
  *
@@ -1036,67 +1646,99 @@ export async function runCompatAnalysis(results, logger, locationRoot, effective
     for (const result of results) {
         if (result.type !== RESOURCE_TYPE_CLAUDE_PLUGIN)
             continue;
-        try {
-            logger.debug(`Running compatibility analysis for: ${result.path}`);
-            const configTargets = resolveConfigTargetsForPlugin(result.path, vatContext);
-            const analyzeOptions = configTargets === undefined
-                ? undefined
-                : { configTargets };
-            const compat = await analyzeCompatibility(result.path, locationRoot, analyzeOptions);
-            // Settings conflict detection (when --settings flag is used)
-            if (effectiveSettings === undefined) {
-                compatMap.set(result.path, compat);
-            }
-            else {
-                try {
-                    const settingsConflicts = await checkSettingsCompatibility(result.path, effectiveSettings);
-                    compatMap.set(result.path, { ...compat, settingsConflicts });
-                }
-                catch (settingsErr) {
-                    logger.debug(`Settings compat check skipped for ${result.path}: ${String(settingsErr)}`);
-                    compatMap.set(result.path, compat);
-                }
-            }
-        }
-        catch (err) {
-            // Log but do not fail the audit — compat analysis is best-effort
-            logger.debug(`Compatibility analysis skipped for ${result.path}: ${String(err)}`);
+        const entry = {
+            compat: await analyzeOrExplain(result.path, locationRoot, vatContext, logger),
+        };
+        if (effectiveSettings !== undefined) {
+            entry.settings = await settingsVerdict(result.path, effectiveSettings, locationRoot, logger);
         }
+        compatMap.set(result.path, entry);
     }
     return compatMap;
 }
+/**
+ * The analyzer's result for one plugin, or — when it threw — the reason, said
+ * on stderr and carried into the document. Compat analysis is best-effort:
+ * it never fails the audit, but a plugin it could not analyze is reported as
+ * exactly that, never as a plugin with no `compatibility:` block.
+ */
+async function analyzeOrExplain(pluginDir, locationRoot, vatContext, logger) {
+    try {
+        logger.debug(`Running compatibility analysis for: ${pluginDir}`);
+        const configTargets = resolveConfigTargetsForPlugin(pluginDir, vatContext);
+        const analyzeOptions = configTargets === undefined ? undefined : { configTargets };
+        return await analyzeCompatibility(pluginDir, locationRoot, analyzeOptions);
+    }
+    catch (err) {
+        const refused = typeof err.path === 'string' ? err.path : undefined;
+        const raw = err instanceof Error ? err.message : String(err);
+        const reason = refused === undefined ? raw : withRelativePath(raw, refused, locationRoot);
+        logger.warn(`Compatibility analysis could not run for ${issueLocation(pluginDir, locationRoot) || '.'}: ${reason}`);
+        return { analyzed: false, reason };
+    }
+}
+/**
+ * One plugin's settings verdict: the checker's conflicts and the paths it
+ * never saw — and, when the checker itself fails, the plugin as the one thing
+ * unchecked, rather than no `settings:` block at all.
+ *
+ * The checker failing used to be `logger.debug` and a result with no settings
+ * block, so a plugin the check could not run on was indistinguishable from one
+ * the operator never asked about. A run that asked for `--settings` and got no
+ * answer for a plugin is told so on stderr and in the document.
+ */
+async function settingsVerdict(pluginDir, effectiveSettings, locationRoot, logger) {
+    try {
+        return await checkSettingsCompatibility(pluginDir, effectiveSettings);
+    }
+    catch (settingsErr) {
+        const reason = settingsErr instanceof Error ? settingsErr.message : String(settingsErr);
+        logger.warn(`Settings compatibility could not be checked for ${issueLocation(pluginDir, locationRoot) || '.'}: ${reason}`);
+        return { conflicts: [], unchecked: [{ path: pluginDir, reason }] };
+    }
+}
+/**
+ * The `settings:` block for one plugin, every path anchored at `locationRoot`.
+ * `compatible` is derived from BOTH halves: zero conflicts over a skill the
+ * check never read is not compatibility, it is silence.
+ */
+function renderSettingsBlock(check, locationRoot) {
+    const settings = {
+        compatible: check.conflicts.length === 0 && check.unchecked.length === 0,
+        conflicts: check.conflicts,
+    };
+    if (check.unchecked.length > 0) {
+        settings.unchecked = check.unchecked.map(({ path, reason }) => ({
+            path: issueLocation(path, locationRoot) || '.',
+            reason: withRelativePath(reason, path, locationRoot),
+        }));
+    }
+    return settings;
+}
 /**
  * Merge compatibility analysis results into validation result output objects.
  * Returns an array of plain objects ready for YAML serialization.
- * When settingsConflicts are present, adds a `settings:` block for cleaner output.
+ * A plugin the run asked `--settings` about gets a `settings:` block, whatever
+ * the analyzer did.
  */
-function mergeCompatIntoResults(results, compatMap) {
+function mergeCompatIntoResults(results, compatMap, locationRoot) {
     return results.map(r => {
-        const compat = compatMap.get(r.path);
-        if (compat === undefined)
+        const entry = compatMap.get(r.path);
+        if (entry === undefined)
             return r;
-        // Extract settingsConflicts from compat to render as a separate `settings:` block
-        const { settingsConflicts, ...compatWithoutSettings } = compat;
-        if (settingsConflicts !== undefined) {
-            return {
-                ...r,
-                compatibility: compatWithoutSettings,
-                settings: {
-                    compatible: settingsConflicts.length === 0,
-                    conflicts: settingsConflicts,
-                },
-            };
-        }
-        return { ...r, compatibility: compat };
+        const merged = { ...r, compatibility: entry.compat };
+        if (entry.settings !== undefined)
+            merged.settings = renderSettingsBlock(entry.settings, locationRoot);
+        return merged;
     });
 }
 /**
  * Apply compatibility data to results if a compatMap is provided and non-empty.
  * Returns the original results array when no compat data is available.
  */
-function applyCompatMap(results, compatMap) {
+function applyCompatMap(results, compatMap, locationRoot) {
     if (compatMap !== undefined && compatMap.size > 0) {
-        return mergeCompatIntoResults(results, compatMap);
+        return mergeCompatIntoResults(results, compatMap, locationRoot);
     }
     return results;
 }
@@ -1133,7 +1775,7 @@ function applyVerboseFilter(results, verbose) {
 const NESTED_PATH_CARRIERS = ['linkedFiles'];
 function calculateSummary(results, startTime, compatMap, verbose, root) {
     const { entries, ...base } = buildBaseSummary(results, startTime);
-    const withCompat = applyCompatMap(entries, compatMap);
+    const withCompat = applyCompatMap(entries, compatMap, root);
     return {
         // Stated once, first, and the only absolute path in the document.
         root,
@@ -1236,19 +1878,75 @@ function renderVerboseEvidence(results, root, logger) {
         }
     }
 }
+/**
+ * The stderr half of a run-level refusal, so the human channel says what the
+ * document says. The document is derived in `buildBaseSummary`; this only
+ * RENDERS it. Both stderr lanes call it first, because "Audit successful: 0
+ * file(s) passed" over `status: error` is the exact disagreement the refusal
+ * exists to end (invariant 6 of `run-integrity.ts`). The run ends on
+ * `FINDINGS`, like every other `status: error` this command publishes.
+ *
+ * @returns Whether a refusal was rendered, so the caller skips its verdict line
+ */
+function logRunIntegrity(runIssues, logger) {
+    if (runIssues === undefined || runIssues.length === 0)
+        return false;
+    logger.error('Audit is not a verdict: it audited 0 files');
+    for (const issue of runIssues) {
+        for (const line of formatIssueLines(issue, '  '))
+            logger.error(line);
+    }
+    return true;
+}
+/**
+ * The stderr line for the settings lane: how many conflicts it found and how
+ * many paths it never compared, across every plugin in the document.
+ *
+ * 🚩 This read `f.compatibility?.settingsConflicts` — a field the renderer had
+ * already moved out into the `settings:` block — so the count was 0 on every
+ * run and the line never printed. It reads the rendered block now, the same
+ * one the YAML carries, and it counts the unchecked half too: a run that
+ * skipped a skill says so without `--debug`.
+ */
+function logSettingsTotals(files, logger) {
+    let conflicts = 0;
+    let unchecked = 0;
+    // The compat lane's own unchecked paths — a plugin the analyzer could only
+    // partly read is in the document under `compatibility.unchecked`, and this is
+    // the one line that keeps it from being silent on the human channel while the
+    // settings lane says its half. `analyzed: false` has no list: it is the
+    // plugin-wide failure, and the `reason` line already says so.
+    let compatUnchecked = 0;
+    for (const { compatibility, settings } of files) {
+        conflicts += settings?.conflicts.length ?? 0;
+        unchecked += settings?.unchecked?.length ?? 0;
+        if (compatibility !== undefined && 'unchecked' in compatibility)
+            compatUnchecked += compatibility.unchecked.length;
+    }
+    if (conflicts > 0) {
+        logger.error(`⚠ ${conflicts} settings conflict(s) found — see 'settings' section in YAML output`);
+    }
+    if (unchecked > 0) {
+        logger.error(`⚠ ${unchecked} path(s) the settings check could not compare — see 'settings.unchecked' in YAML output`);
+    }
+    if (compatUnchecked > 0) {
+        logger.error(`⚠ ${compatUnchecked} path(s) the compatibility analysis could not read — see 'compatibility.unchecked' in YAML output`);
+    }
+}
 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) => {
-        return sum + (f.compatibility?.settingsConflicts?.length ?? 0);
-    }, 0);
-    if (totalSettingsConflicts > 0) {
-        logger.error(`\u26a0 ${totalSettingsConflicts} settings conflict(s) found — see 'settings' section in YAML output`);
-    }
-    // Audit is advisory only — always exit 0 for validation results.
-    // Use vat skills validate for gated validation (exit 1 on errors).
-    if (errorCount > 0) {
-        logger.error(`Audit failed: ${errorCount} file(s) with errors`);
+    logSettingsTotals(summary.files ?? [], logger);
+    // The exit code follows the document's `status`, as it does in every other
+    // command of this CLI: `status: error` — an error-severity finding, or a run
+    // that audited zero files — ends on `FINDINGS`. This used to be the one
+    // command that exited 0 over `status: error` ("advisory"), and an adopter
+    // wiring it into CI read "Audit failed" on stderr beside a green step.
+    const refused = logRunIntegrity(summary.issues, logger);
+    if (refused) {
+        // Rendered above; there is no file verdict to print over zero files.
+    }
+    else if (errorCount > 0) {
+        logger.error(`Audit found ${errorCount} file(s) with errors`);
         logFindingsForStatus(results, 'error', summary.root, logger.error.bind(logger), verbose);
     }
     else if (warningCount > 0) {
@@ -1264,7 +1962,7 @@ function handleAuditResults(results, summary, logger, verbose) {
             : `Audit successful: ${successCount} file(s) passed`);
     }
     renderAuditFooter(results, logger);
-    process.exit(0);
+    process.exit(refused || errorCount > 0 ? ExitCode.FINDINGS : ExitCode.OK);
 }
 /**
  * Render the skill-quality checklist footer when audit results contain
@@ -1359,17 +2057,6 @@ function logFindingsForStatus(results, status, root, logFn, verbose) {
         logFn(line);
     }
 }
-/**
- * Check whether a path should be excluded during directory scanning.
- * For directories, checks both bare path and path with trailing slash
- * so patterns like "dist/**" prune the directory itself.
- */
-function isExcludedPath(isMatch, relativePath, isDirectory) {
-    if (isDirectory) {
-        return isMatch(relativePath) || isMatch(relativePath + '/');
-    }
-    return isMatch(relativePath);
-}
 /**
  * Does the SKILL.md at `skillMdPath` own its own presence-side crawl, or has an
  * ancestor crawl already covered it?
@@ -1383,39 +2070,27 @@ 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.
+ * The directories whose presence-side crawl already owns everything beneath
+ * them — see {@link ScanContext.crawledRoot} for why there are two owner kinds
+ * and why the first owner wins.
+ *
+ * Kept as a list of roots rather than threaded down a recursion: the
+ * population arrives flat and top-down (an ancestor's subjects before a
+ * descendant's), so "who owns this path" is the first claimed root that
+ * contains it, and a claim is only ever made where no ancestor holds one.
  */
-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);
+class SubtreeClaims {
+    roots = [];
+    /** The claimed root containing `absolutePath`, or `null` while nothing does. */
+    owner(absolutePath) {
+        const resolved = safePath.resolve(absolutePath);
+        return this.roots.find((root) => isWithin(root, resolved)) ?? null;
+    }
+    /** Claim everything below `dir`, unless an ancestor already did. First owner wins. */
+    claim(dir) {
+        if (this.owner(dir) === null)
+            this.roots.push(safePath.resolve(dir));
+    }
 }
 /**
  * Handle file entry during directory scan
@@ -1433,25 +2108,41 @@ async function handleFileEntry(entry, fullPath, options, logger, scanCtx) {
         // Config-aware: walk UP to the skill's nearest-ancestor config and apply
         // ONLY that skill's declared packaging rules. Configs do not compose
         // across VAT projects — audit does not merge rules across sibling configs.
-        const fullConfig = await resolveSkillPackagingConfig(fullPath);
-        const skillConfig = fullConfig === null ? null : stripValidationAllowForDisplay(fullConfig);
+        // Shared with the single-target lane, so one unloadable nested config
+        // cannot abort this whole scan while that lane shrugs it off. The warn-once
+        // ledger lives in `unloadableConfigResults` (module scope, cleared by
+        // `resetAuditCaches`) rather than being threaded here, so BOTH lanes dedupe
+        // against the same state — this one used to, the other minted a fresh set
+        // per skill.
+        const skillConfig = await resolveGoverningConfig(fullPath, logger, locationRoot);
         if (skillConfig !== null) {
             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 projectSkills = await resolveProjectDeclaredEvalSuites(fullPath, degradingDiscovery(findProjectRoot(safePath.resolve(fullPath, '..')) ?? locationRoot, logger, locationRoot));
+            // `suiteProbe`: the RUN's, not this entry's — the directory walk reaches
+            // this function once per SKILL.md it finds. See {@link runSuiteProbe}.
+            const suiteProbe = suiteProbeForRun();
+            // No registry is supplied on this lane, so `validateSkillForPackaging`
+            // crawls one per project root through `crawlAndResolveRegistry` — under
+            // audit's ruling, which is the ONLY reason one `chmod 000` sibling no
+            // longer exits this whole run at 2 with zero findings. The root is the
+            // one the validator itself derives (`findProjectRoot(dirname) ?? dirname`),
+            // so the refuse sentence and the finding name the same crawl.
+            const skillDir = safePath.resolve(fullPath, '..');
+            const unreadable = degradingRegistry(findProjectRoot(skillDir) ?? skillDir, logger, locationRoot);
             const sharedCtx = scanCtx.gitTracker === null
-                ? { locationRoot, projectSkills }
-                : { gitTracker: scanCtx.gitTracker, locationRoot, projectSkills };
+                ? { locationRoot, projectSkills, suiteProbe, unreadable }
+                : { gitTracker: scanCtx.gitTracker, locationRoot, projectSkills, suiteProbe, unreadable };
             const packagingResult = await validateSkillForPackaging(fullPath, skillConfig, 'source', sharedCtx);
             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 };
+        // Wild mode: basic validation. Severity is applied by `applySeverityFilter`.
+        const validateOptions = { skillPath: fullPath, locationRoot, validation: {} };
         if (options.warnUnreferencedFiles) {
             validateOptions.checkUnreferencedFiles = true;
         }
@@ -1465,79 +2156,15 @@ async function handleFileEntry(entry, fullPath, options, logger, scanCtx) {
     return null;
 }
 /**
- * Handle directory entry during directory scan
- */
-async function handleDirectoryEntry(fullPath, recursive, options, logger, baseDir, scanCtx, nestedConfigLog) {
-    const fs = await import('node:fs/promises');
-    const { locationRoot } = scanCtx;
-    const results = [];
-    // Check if directory contains a plugin or marketplace
-    const claudePluginDir = safePath.join(fullPath, '.claude-plugin');
-    const hasClaudePlugin = await fs.access(claudePluginDir).then(() => true).catch(() => false);
-    if (hasClaudePlugin) {
-        logger.debug(`Validating resource directory: ${fullPath}`);
-        const result = await validate(fullPath, { validatePlugin, locationRoot });
-        const inv = await pluginInventoryAt(fullPath);
-        appendInventoryParseErrors(result, inv, locationRoot);
-        results.push(result);
-    }
-    // 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, childCtx, baseDir, nestedConfigLog);
-        results.push(...subResults);
-    }
-    return results;
-}
-/**
- * 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.
+ * Validate a directory the population found holding `.claude-plugin/` — a
+ * plugin or a marketplace, whichever the unified validator decides.
  */
-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' };
+async function validatePluginDirectory(dir, logger, locationRoot) {
+    logger.debug(`Validating resource directory: ${dir}`);
+    const result = await validate(dir, { validatePlugin, locationRoot });
+    const inv = await pluginInventoryAt(dir);
+    appendInventoryParseErrors(result, inv, locationRoot);
+    return result;
 }
 /**
  * Cache of (projectRoot → registry for the *inventory* link walk).
@@ -1590,7 +2217,12 @@ async function getOrCreateInventoryRegistry(projectRoot) {
  */
 async function pluginInventoryAt(dir) {
     const projectRoot = findProjectRoot(dir);
-    return extractClaudePluginInventory(dir, projectRoot === null ? undefined : () => getOrCreateInventoryRegistry(projectRoot), gitTrackerForProjectRoot);
+    return extractClaudePluginInventory(dir, {
+        ...(projectRoot === null
+            ? {}
+            : { sharedRegistry: () => getOrCreateInventoryRegistry(projectRoot) }),
+        gitTrackerSource: gitTrackerForProjectRoot,
+    });
 }
 /**
  * Reset all module-level audit caches. Must be called at the start of every
@@ -1602,6 +2234,8 @@ export function resetAuditCaches() {
     resetGitTrackerCache();
     resetPackagingRegistryCache();
     inventoryRegistryCache.clear();
+    unloadableConfigResults.clear();
+    runSuiteProbe = undefined;
     resetProjectRootCaches();
     resetLoadedConfigCache();
     resetSkillDiscoveryCache();
@@ -1631,107 +2265,150 @@ async function resolveScanContext(dirPath, locationRoot, logger) {
     return { gitRoot: detectedRoot, gitTracker: tracker, locationRoot, projectExcludes, crawledRoot: null };
 }
 /**
- * Build the gitignore exclusion map for a set of entry paths.
- * Returns null when gitignore filtering is not applicable (no git root,
- * --include-artifacts, or outside a git repo).
+ * The one finding a path the walk could not read produces — a directory it could
+ * not enter, or a file it could not open.
+ *
+ * A synthetic result rather than an issue appended to some neighbour: nothing
+ * about the unreadable path was validated, so it has no host result to hang
+ * off, and attaching it to a sibling would attribute the condition to a tree that
+ * scanned fine. Typed `unknown` for the same reason — the whole point is that its
+ * contents were never seen, so any more specific type would be a claim the scan
+ * cannot support.
+ *
+ * The OS message is carried through verbatim (it names the errno and the syscall,
+ * which is what distinguishes a permissions problem from a vanished mount), but it
+ * is no longer the ONLY thing the run says — the code, the location and the fix
+ * come from the registry.
+ *
+ * This result is a `files[]` row but NOT a scanned file: `countFilesByStatus`
+ * recognises it ({@link isUnreadablePathResult}) and reports it under
+ * `summary.pathsUnreadable`, outside `filesScanned` and the status counts. A
+ * root the OS refused therefore audits zero files and ends on the zero-files
+ * refusal, instead of `filesScanned: 1` over a path nothing read.
  */
-function buildGitIgnoreMap(entryPaths, gitTracker, includeArtifacts) {
-    if (gitTracker === null || includeArtifacts) {
-        return null;
-    }
-    const map = new Map();
-    for (const entryPath of entryPaths) {
-        map.set(entryPath, gitTracker.isIgnoredByActiveSet(entryPath));
-    }
-    return map;
+function unreadablePathResult(dirPath, error, locationRoot) {
+    // `issueLocation` is `path.relative`, so it answers `''` when the subject IS the
+    // anchor — and for this finding that is not exotic, it is `vat audit <path>`
+    // where the named path is the unreadable one. `''` reached the report as
+    // `location: ""` and rendered the detail as a bare `": EACCES …"`. `.` is that
+    // same path spelled as something a reader can act on. The identical fix, for the
+    // identical reason, already exists on the distributed-tree finding — see
+    // `anchoredTreeLocation` in ./audit/distributed-tree.ts.
+    const location = issueLocation(dirPath, locationRoot) || '.';
+    // The OS names the path it refused absolutely; the report speaks scan-root
+    // coordinates everywhere else, and an absolute path here is the build host's
+    // `$HOME` in every CI log.
+    const reason = withRelativePath(error instanceof Error ? error.message : String(error), dirPath, locationRoot);
+    const issues = [
+        materializeIssue('SCAN_PATH_UNREADABLE', {
+            location,
+            detail: `${location}: ${reason}`,
+        }),
+    ];
+    const issueCounts = countBySeverity(issues);
+    return {
+        path: dirPath,
+        type: 'unknown',
+        status: calculateValidationStatus(issues),
+        summary: formatCountsSummary(issueCounts),
+        issues,
+        issueCounts,
+    };
 }
 /**
- * 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.
+ * Validate ONE subject the population found, degrading to a finding if the
+ * filesystem refuses it.
+ *
+ * Guarded per SUBJECT, not just per listing: an unreadable FILE (a root-owned
+ * `SKILL.md`, a quarantined bundle) used to throw out of `validateSkill` and
+ * abort the whole run with `status: error` and zero findings. Under
+ * `~/.claude/plugins` — the flagship `vat audit --user` target, populated by sudo
+ * installs and macOS quarantine — a root-owned FILE is at least as likely as a
+ * root-owned directory.
+ *
+ * Ownership is decided here and only here, in population order: a plugin
+ * directory claims its subtree unconditionally; a skill claims its own only
+ * when nothing above it already has AND its crawl actually runs
+ * ({@link crawlOwnsSubtree}) — a repo-source skill's crawl is skipped, so
+ * claiming its subtree would trade a double count for a missed finding.
  */
-function getSkipReason(entry, fullPath, gitIgnoredMap, excludeMatchers) {
-    // Always skip .git directory (not reported by git check-ignore)
-    if (entry.isDirectory() && entry.name === '.git') {
-        return '.git';
-    }
-    // Skip gitignored paths
-    if (gitIgnoredMap !== null && gitIgnoredMap.get(fullPath) === true) {
-        return `gitignored: ${entry.name}`;
-    }
-    // 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}`;
+async function validateScanSubject(subject, options, logger, scanCtx, claims) {
+    const { locationRoot } = scanCtx;
+    try {
+        if (subject.kind === 'plugin') {
+            const result = await validatePluginDirectory(subject.dir, logger, locationRoot);
+            claims.claim(subject.dir);
+            return [result];
+        }
+        const subjectCtx = { ...scanCtx, crawledRoot: claims.owner(subject.path) };
+        const result = await handleFileEntry({ name: basename(subject.path) }, subject.path, options, logger, subjectCtx);
+        if (subject.kind === 'skill' && ownsOwnCrawl(subjectCtx, subject.path) && await crawlOwnsSubtree(subject.path)) {
+            claims.claim(subject.dir);
         }
+        return result === null ? [] : [result];
+    }
+    catch (error) {
+        // ONLY filesystem-access errors degrade. Anything else is rethrown, because
+        // turning a genuine VAT bug into a `warning` about the file it happened on is
+        // the same "detector silently disables itself" shape this guard exists to
+        // prevent — it would make the tool quietest exactly when it is most wrong.
+        if (!isFilesystemAccessError(error))
+            throw error;
+        const path = subject.kind === 'plugin' ? subject.dir : subject.path;
+        logger.debug(`Unreadable entry: ${path}`);
+        return [unreadablePathResult(path, error, locationRoot)];
     }
-    return null;
 }
-async function scanDirectory(dirPath, recursive, options, logger, scanCtx, baseDir, nestedConfigLog) {
-    const fs = await import('node:fs/promises');
-    const results = [];
-    const userExcludes = options.exclude ?? [];
-    const resolvedBaseDir = baseDir ?? dirPath;
-    // The git context (root + tracker) and the run's anchor base are built once by
-    // the caller; every recursion reuses them unchanged.
-    const resolvedScanCtx = scanCtx;
-    const resolvedNestedLog = nestedConfigLog ?? new Set();
-    // Top-down pre-warm of findProjectRoot's walk-up cache (spec §8). The first
-    // call here drives a single ancestor walk; every subsequent recursion is a
-    // Layer-1 hit chain. By the time we reach leaf SKILL.md files,
-    // resolveSkillPackagingConfig's per-skill walk-up is all cache hits.
+/**
+ * The remedy a refused listing names: the operator's own knob for dropping a
+ * directory from the audit on purpose.
+ */
+function scanRefusalRemedy() {
+    return 'To leave it out deliberately, exclude it with --exclude <pattern>.';
+}
+/**
+ * Audit a directory: every plugin, skill and registry file the `crawl` lane
+ * finds beneath it, plus one finding per directory the lane could not list.
+ *
+ * The enumeration is `enumerateAuditPopulation`'s — this function owns no
+ * walk of its own. What it decides is what the audit MAKES of the population:
+ * validation per subject, subtree ownership across subjects (see
+ * {@link validateScanSubject}), the nested-config breadcrumb, and the refusal
+ * findings. A refused directory is a finding, not a thrown error: `vat audit`
+ * is a bulk linter over trees it does not own, and one root-owned directory
+ * under `~/.claude/plugins` used to abort the flagship `vat audit --user` run
+ * outright, losing every finding already collected. The scope of the loss is
+ * the subtree that refused; every readable sibling is still validated.
+ */
+async function scanDirectory(dirPath, recursive, options, logger, scanCtx) {
+    // Warm findProjectRoot's walk-up cache from the scan root: every per-skill
+    // walk-up below lands on a cached ancestor instead of re-walking to `/`.
     findProjectRoot(dirPath);
-    // Emit a one-time info breadcrumb when we encounter a nested
-    // vibe-agent-toolkit.config.yaml that is NOT at the scan root. Configs do
-    // not compose across VAT projects; the message reminds operators that
-    // only per-skill packaging rules from this config still apply.
-    const nestedConfigPath = safePath.join(dirPath, VAT_CONFIG_FILENAME);
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- dirPath is a controlled scan path
-    if (dirPath !== resolvedBaseDir && fsExistsSync(nestedConfigPath) && !resolvedNestedLog.has(nestedConfigPath)) {
-        resolvedNestedLog.add(nestedConfigPath);
-        const rel = safePath.relative(resolvedBaseDir, nestedConfigPath).replaceAll('\\', '/');
-        logger.info(`Nested vibe-agent-toolkit.config.yaml detected at ${rel} — configs do not compose across VAT projects. Per-skill packaging rules from this config still apply to skills declared in it.`);
-    }
-    // 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.
-    // 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, gitIgnoredMap, excludeMatchers);
-        if (skipReason !== null) {
-            logger.debug(`Excluding path: ${skipReason}`);
-            continue;
-        }
-        if (entry.isFile()) {
-            const result = await handleFileEntry(entry, fullPath, options, logger, resolvedScanCtx);
-            if (result !== null) {
-                results.push(result);
-            }
-        }
-        else if (entry.isDirectory()) {
-            // `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);
-        }
+    const population = await enumerateAuditPopulation({
+        scanDir: dirPath,
+        recursive,
+        // No tracker means no git root, or a scan root that is itself gitignored
+        // (the operator's explicit intent wins); either way ignored files are in.
+        respectGitignore: scanCtx.gitTracker !== null && !(options.includeArtifacts ?? false),
+        userExcludes: options.exclude ?? [],
+        projectExcludes: scanCtx.projectExcludes,
+    });
+    // A one-time breadcrumb per nested `vibe-agent-toolkit.config.yaml` that is
+    // NOT at the scan root. Configs do not compose across VAT projects; the
+    // message reminds operators that only per-skill packaging rules from this
+    // config still apply.
+    for (const nestedConfigPath of population.nestedConfigs) {
+        const rel = toForwardSlash(safePath.relative(dirPath, nestedConfigPath));
+        logger.info(`Nested ${VAT_CONFIG_FILENAME} detected at ${rel} — configs do not compose across VAT projects. Per-skill packaging rules from this config still apply to skills declared in it.`);
+    }
+    const results = population.refusals.map((refusal) => {
+        logger.debug(`Unreadable directory: ${refusal.directory}`);
+        const err = new DirectoryListingRefusedError(refusal, { root: dirPath, remedy: scanRefusalRemedy() });
+        return unreadablePathResult(refusal.directory, err, scanCtx.locationRoot);
+    });
+    const claims = new SubtreeClaims();
+    for (const subject of population.subjects) {
+        results.push(...await validateScanSubject(subject, options, logger, scanCtx, claims));
     }
     return results;
 }
@@ -1760,13 +2437,34 @@ function calculateOverallStatus(results) {
 function countResultsWithFindings(results) {
     return results.filter((r) => r.issues.length > 0).length;
 }
-/** Count files by their own status. */
+/**
+ * Whether a `files[]` row is a refused path rather than a scanned file: the
+ * synthetic result {@link unreadablePathResult} builds, carrying nothing but
+ * `SCAN_PATH_UNREADABLE`. Keyed on the code, not on `type: 'unknown'` alone —
+ * an unrecognised file is also `unknown`, and it WAS examined.
+ */
+function isUnreadablePathResult(result) {
+    return result.type === 'unknown'
+        && result.issues.length > 0
+        && result.issues.every((issue) => issue.code === 'SCAN_PATH_UNREADABLE');
+}
+/**
+ * Count files by their own status.
+ *
+ * A refused path is NOT a scanned file. It used to be counted as one, which
+ * made the zero-files refusal unreachable for exactly the tree it exists for:
+ * `chmod 000` on the whole root gave `filesScanned: 1, filesPassed: 0`,
+ * `status: warning`, exit 0 — nothing read, gate green. Kept out of every
+ * status count too, or `filesWithWarnings` would exceed `filesScanned`.
+ */
 function countFilesByStatus(results) {
+    const scanned = results.filter((r) => !isUnreadablePathResult(r));
     return {
-        filesScanned: results.length,
-        filesPassed: results.filter((r) => r.status === 'success').length,
-        filesWithWarnings: results.filter((r) => r.status === 'warning').length,
-        filesWithErrors: results.filter((r) => r.status === 'error').length,
+        filesScanned: scanned.length,
+        filesPassed: scanned.filter((r) => r.status === 'success').length,
+        filesWithWarnings: scanned.filter((r) => r.status === 'warning').length,
+        filesWithErrors: scanned.filter((r) => r.status === 'error').length,
+        pathsUnreadable: results.length - scanned.length,
     };
 }
 /**
@@ -1794,6 +2492,24 @@ function countFilesByStatus(results) {
  * 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.
+ *
+ * 🚨 **Zero files audited is an ERROR, not "an empty tree audits cleanly".**
+ * `calculateOverallStatus([])` is `success`, so an existing directory holding
+ * nothing auditable — moved plugins, a wrong subdirectory, an excluded tree, a
+ * tree of files no lane recognises — published `status: success` beside
+ * `filesScanned: 0`, and this command's own documentation tells CI to gate on
+ * that `status`. Derived HERE, in the one builder both the directory lane
+ * (`calculateSummary`) and the `--user` lane (`calculateHierarchicalSummary`)
+ * pass through, so neither can publish a clean status over a zero denominator.
+ * Through the shared mechanism in `run-integrity.ts`: one non-overridable
+ * `RESOURCE_CHECK_BROKEN` at `error`, published under a top-level `issues` —
+ * the claim is about the RUN, so it is not a `files[]` row and does not count
+ * toward `filesScanned` — and counted in the header `issueCounts`, so the
+ * identity becomes `issueCounts === Σ files[].issueCounts + Σ issues`.
+ *
+ * The exit code is NOT touched by this: `status` describes the findings and the
+ * exit code describes whether the run completed, and this run completed. See
+ * {@link createAuditCommand}.
  */
 function buildBaseSummary(results, startTime) {
     const issueCounts = { errors: 0, warnings: 0, info: 0 };
@@ -1804,11 +2520,24 @@ function buildBaseSummary(results, startTime) {
         issueCounts.info += counts.info;
         return { ...result, issueCounts: counts };
     });
+    const summary = countFilesByStatus(entries);
+    // The denominator is files READ: a tree whose every path was refused audited
+    // nothing, and says so through the same refusal as an empty tree.
+    const runIssues = nothingCheckedFinding(summary.filesScanned, entries.flatMap((entry) => entry.issues), () => 'The audit ran over 0 files, so this report is not a verdict: a tree with nothing'
+        + ' to audit produces the same counts as a clean one. The path resolved to a tree'
+        + ' holding no auditable file — usually a wrong subdirectory, plugins or skills that'
+        + ' have moved, an excluded tree, files no audit lane recognises, or `--no-recursive`'
+        + ' over a tree whose resources sit deeper. Point the command at the plugin,'
+        + ' marketplace, registry or SKILL.md tree it should read.');
     return {
         entries,
-        status: calculateOverallStatus(entries),
-        summary: countFilesByStatus(entries),
-        issueCounts,
+        // Every run-integrity finding is `error` by construction (invariant 2 of
+        // `run-integrity.ts`), so a non-empty refusal IS the status; otherwise the
+        // files decide it, as before.
+        status: runIssues.length > 0 ? 'error' : calculateOverallStatus(entries),
+        summary,
+        issueCounts: sumSeverityCounts([issueCounts, countBySeverity(runIssues)]),
+        ...(runIssues.length === 0 ? {} : { issues: [...runIssues] }),
         duration: `${Date.now() - startTime}ms`,
     };
 }
@@ -1817,7 +2546,7 @@ function buildBaseSummary(results, startTime) {
  */
 function calculateHierarchicalSummary(results, hierarchical, startTime, compatMap, verbose, root) {
     const { entries, ...base } = buildBaseSummary(results, startTime);
-    const withCompat = applyCompatMap(entries, compatMap);
+    const withCompat = applyCompatMap(entries, compatMap, root);
     return {
         root,
         ...base,
@@ -1835,13 +2564,16 @@ function calculateHierarchicalSummary(results, hierarchical, startTime, compatMa
 /**
  * Log hierarchical summary to stderr
  */
-function logHierarchicalSummary(results, logger) {
+function logHierarchicalSummary(results, runIssues, logger) {
     const status = calculateOverallStatus(results);
     const skillsWithIssues = countResultsWithFindings(results);
     const totalSkills = results.length;
-    // Audit is advisory only — always exit 0 for validation results.
-    // Use vat skills validate for gated validation (exit 1 on errors).
-    if (status === 'error') {
+    // Same rule as the per-file lane: the exit code follows `status`.
+    const refused = logRunIntegrity(runIssues, logger);
+    if (refused) {
+        // Rendered above; there is no skill verdict to print over zero skills.
+    }
+    else if (status === 'error') {
         const errorCount = results.filter((r) => r.status === 'error').length;
         logger.error(`Audit found ${errorCount} skill(s) with errors (${totalSkills} scanned, ${skillsWithIssues} with issues)`);
     }
@@ -1858,6 +2590,6 @@ function logHierarchicalSummary(results, logger) {
         logger.info(`Audit successful: ${totalSkills} skill(s) passed`);
     }
     renderAuditFooter(results, logger);
-    process.exit(0);
+    process.exit(refused || status === 'error' ? ExitCode.FINDINGS : ExitCode.OK);
 }
 //# sourceMappingURL=audit.js.map