@vibe-agent-toolkit/cli 0.2.0-rc.5 → 0.2.0-rc.7

package/dist/commands/audit.js

@@ -5,22 +5,25 @@
 import * as fs from 'node:fs';
 import { existsSync as fsExistsSync } from 'node:fs';
 import { basename } from 'node:path';
-import { crawlAndResolveRegistry, detectDeclaredButMissing, detectMarketplacePluginSourceMissing, resetPackagingRegistryCache, detectPresentButUndeclared, detectReferenceTargetMissing, detectResourceFormat, enumerateSurfaces, materializeIssue, 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 { listingRefusalRemedy } from '@vibe-agent-toolkit/resources';
 import { calculateValidationStatus, countBySeverity, } from '@vibe-agent-toolkit/schema';
 import { findProjectRoot, isAbsolutePath, isFilesystemAccessError, issueLocation, resetProjectRootCaches, safePath, } 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 { 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';
@@ -29,7 +32,7 @@ import { withClonedRepo } from './audit/git-url-clone.js';
 import { buildHierarchicalOutput } from './audit/hierarchical-output.js';
 import { renderProvenanceHeader, rewritePathsInResults, } from './audit/provenance.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. */
@@ -51,7 +54,7 @@ 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)) {
@@ -69,7 +72,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);
@@ -79,7 +82,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;
@@ -162,22 +174,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 — issue #180's exact shape, from the
+ * crawl the fix for #180 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);
@@ -189,10 +466,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;
@@ -249,6 +534,20 @@ function collect(value, previous) {
 /**
  * Create audit command
  * Top-level command: vat audit [path]
+ *
+ * 🔑 **Two verdicts, deliberately.** The YAML `status` describes the FINDINGS;
+ * the exit code describes whether the RUN completed. `status: error` beside exit
+ * `0` is the correct pair for a tree with errors, and both facts are worth
+ * publishing — but `status` moves with the exit code in every other command of
+ * this CLI, so this one is the exception and the help text says so out loud (see
+ * the `Output` and `Exit Codes` sections below, and `docs/audit.md`).
+ *
+ * ⚠️ Do NOT "reconcile" the two by making one follow the other. Making the exit
+ * code follow `status` turns an advisory report into a gate — the thing
+ * `vat validate` already is, and the thing this command's published contract
+ * promises it is not. Making `status` follow the exit code deletes the only
+ * machine-readable verdict a CI consumer has, and a stamped `success` over a
+ * report full of errors is a stronger falsehood than the mismatch ever was.
  */
 export function createAuditCommand() {
     const audit = new Command('audit');
@@ -315,11 +614,26 @@ Description:
     done
   (See packages/cli/docs/audit.md for details.)
 
+Output — two verdicts, and they answer different questions:
+  The YAML 'status' describes the FINDINGS. The exit code describes whether the
+  RUN completed. On a tree with errors that is 'status: error' beside exit 0,
+  and both are correct.
+
+  Note that 'status' means something narrower here than elsewhere in this CLI,
+  where it moves with the exit code. Gate CI on the report — 'status' and
+  'issueCounts' — never on this command's exit code.
+
+  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), still beside exit 0 — the run
+  completed; it just is not a verdict.
+
 Validation Behavior:
   Advisory only: 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
@@ -364,14 +678,24 @@ 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 - Always, when the audit completes — including when it reports
+      'status: error'. The findings are in the report; see Output above.
+      A missing or unrecognised path is UNKNOWN_FORMAT; an unreadable one,
+      or a governing config that cannot be loaded or whose skills.include
+      reaches an unreadable directory, is SCAN_PATH_UNREADABLE — readable
+      siblings are still validated, and the config's skills config-free.
+  2 - The audit could not run at all (--user with no Claude config dir,
+      a git URL that would not clone, an internal failure), so there is
+      no report to read.
 
 Examples:
   $ vat audit ./plugins/              # Audit recursively (default)
@@ -439,7 +763,7 @@ async function auditUserDirectories(recursive, options, startTime, logger) {
         logger.error('Claude plugins/skills/marketplaces have not been installed yet.');
         process.exit(2);
     }
-    const results = [];
+    const scanned = [];
     // The roots that exist, minus any one another already covers — see
     // {@link userScanTargets}. `marketplaces/` lives inside `plugins/`.
     const present = [
@@ -449,8 +773,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
@@ -463,7 +791,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']);
@@ -547,13 +875,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
@@ -588,11 +924,13 @@ 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.
@@ -604,9 +942,9 @@ function applySeverityFilter(results, config) {
         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;
         }
@@ -669,7 +1007,18 @@ 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).
     //
     // Guarded, and the ordering is why: the scan above has ALREADY run and collected
@@ -699,10 +1048,6 @@ export async function buildAuditReport(scanPath, options, startTime, logger) {
     // Allow is deliberately NOT applied — audit is advisory only.
     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)
@@ -886,20 +1231,34 @@ 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 — is appended with error
+ * severity, the message spelled scan-root-relative wherever it names the file.
  */
 function appendInventoryParseErrors(result, inv, locationRoot) {
     const pluginJsonSuffix = safePath.join('.claude-plugin', 'plugin.json');
     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,
+            message: withRelativePath(err.message, err.path, locationRoot),
             location: issueLocation(err.path, locationRoot),
         });
     }
@@ -940,7 +1299,7 @@ function appendInventoryParseErrors(result, inv, locationRoot) {
  */
 export async function getValidationResults(scanPath, recursive, options, logger, locationRoot) {
     try {
-        return await validateAuditSubject(scanPath, recursive, options, logger, locationRoot);
+        return dedupeUnreadablePathResults(await validateAuditSubject(scanPath, recursive, options, logger, locationRoot));
     }
     catch (error) {
         // Only the filesystem refusing the subject degrades; a defect in a validator
@@ -951,6 +1310,83 @@ export async function getValidationResults(scanPath, recursive, options, logger,
         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
@@ -1114,7 +1550,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.
  *
@@ -1135,67 +1579,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;
 }
@@ -1232,7 +1708,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,
@@ -1345,23 +1821,83 @@ 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`). Exit stays 0 — the run
+ * completed — and the note says which command gates.
+ *
+ * @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 ${ADVISORY_EXIT_NOTE}`);
+    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`);
-    }
+    logSettingsTotals(summary.files ?? [], logger);
     // 🔑 Audit is advisory only — always exit 0 for validation results, and the
-    // WORDING has to agree with that or the three signals contradict each other.
-    // This line used to read "Audit failed", beside `status: error` in the
-    // document, on exit 0: an adopter wiring `vat audit` into CI read a failure,
-    // saw a failure status, and got a green step. "Found" is what actually
-    // happened; the gate is `vat validate`, which is named here rather than
-    // implied.
-    if (errorCount > 0) {
+    // WORDING has to say so. This line used to read "Audit failed" on exit 0: an
+    // adopter wiring `vat audit` into CI read a failure and got a green step.
+    // "Found" is what actually happened, and the gate is `vat validate`, named
+    // here rather than implied.
+    //
+    // ⚠️ That fixed the WORDING and nothing else. The document still says
+    // `status: error` over exit 0 — measured on
+    // `packages/agent-skills/test/fixtures/skill-files` — and that is the
+    // published contract, not a leftover: `status` describes the FINDINGS, the
+    // exit code describes whether the RUN completed. An earlier version of this
+    // comment claimed all three signals had been reconciled; two of the three
+    // had, and the third is not a signal to reconcile. Where a reader is told
+    // which is which is {@link createAuditCommand}'s help — see its `Output`
+    // section, and `docs/audit.md`.
+    if (logRunIntegrity(summary.issues, logger)) {
+        // 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 ${ADVISORY_EXIT_NOTE}`);
         logFindingsForStatus(results, 'error', summary.root, logger.error.bind(logger), verbose);
     }
@@ -1547,18 +2083,34 @@ 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));
@@ -1637,7 +2189,17 @@ function resolveProjectExcludes(scanDir, logger) {
     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)}`);
+        //
+        // 🚨 `warn`, not `debug`. This comment already said "say so" while logging at
+        // a level nobody sees without `--debug`, so what actually happened was the
+        // silent drop it forbids — and the consequence is the one this function's own
+        // docstring spells out: EVERY `resources.exclude` the project declared is
+        // void, so a package that excludes its deliberately-broken eval fixtures has
+        // them audited as production skills. That is findings APPEARING, not findings
+        // disappearing, which is exactly the direction an operator will read as VAT
+        // being wrong rather than as their config being broken.
+        logger.warn(`Config at ${projectRoot} could not be read; every resources.exclude it declares is`
+            + ` dropped for this run, so excluded trees are audited as ordinary source: ${String(err)}`);
         return null;
     }
     if (patterns.length === 0)
@@ -1721,6 +2283,8 @@ export function resetAuditCaches() {
     resetGitTrackerCache();
     resetPackagingRegistryCache();
     inventoryRegistryCache.clear();
+    unloadableConfigResults.clear();
+    runSuiteProbe = undefined;
     resetProjectRootCaches();
     resetLoadedConfigCache();
     resetSkillDiscoveryCache();
@@ -1820,10 +2384,14 @@ function unreadablePathResult(dirPath, error, locationRoot) {
     // 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}: ${error instanceof Error ? error.message : String(error)}`,
+            detail: `${location}: ${reason}`,
         }),
     ];
     const issueCounts = countBySeverity(issues);
@@ -2012,6 +2580,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 };
@@ -2022,11 +2608,21 @@ function buildBaseSummary(results, startTime) {
         issueCounts.info += counts.info;
         return { ...result, issueCounts: counts };
     });
+    const runIssues = nothingCheckedFinding(entries.length, 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),
+        // 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: countFilesByStatus(entries),
-        issueCounts,
+        issueCounts: sumSeverityCounts([issueCounts, countBySeverity(runIssues)]),
+        ...(runIssues.length === 0 ? {} : { issues: [...runIssues] }),
         duration: `${Date.now() - startTime}ms`,
     };
 }
@@ -2035,7 +2631,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,
@@ -2053,13 +2649,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') {
+    if (logRunIntegrity(runIssues, logger)) {
+        // 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) ${ADVISORY_EXIT_NOTE}`);
     }