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

package/dist/commands/audit.js

@@ -3,32 +3,33 @@
  * Top-level command: vat audit [path]
  */
 import * as fs from 'node:fs';
-import { existsSync as fsExistsSync } from 'node:fs';
 import { basename } from 'node:path';
-import { conventionalSuiteProbe, 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, describeIssues, 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, ExitCode, } from '@vibe-agent-toolkit/schema';
-import { findProjectRoot, isFilesystemAccessError, isPathAbsentError, issueLocation, relativeEscapesRoot, resetProjectRootCaches, safePath, toForwardSlash, } from '@vibe-agent-toolkit/utils';
+import { buildReport, countBySeverity, exitCodeForReport, summarizeIssues, toFindings, withAddedFindings, } from '@vibe-agent-toolkit/schema';
+import { everywhere, findProjectRoot, followedKind, followedKindSync, forEachInOrder, fsFaultOf, isPathAbsentError, issueLocation, mapInOrder, pathPresent, 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 { resetSkillDiscoveryCache, resolveProjectDeclaredEvalSuites, resolveSkillPackagingConfig, stripValidationAllowForDisplay, } from '../skill-resolution/packaging-config.js';
-import { handleCommandError, handleExpectedFailure } from '../utils/command-error.js';
+import { CommandRefusalError, errorMessageOf, refusalCodeOf } from '../utils/command-refusal.js';
 import { ConfigLoadError, loadConfig, resetLoadedConfigCache, } from '../utils/config-loader.js';
-import { countCollapsedFindings, formatCollapsedFindingsHint, formatIssueLines, formatSeverityBreakdown, issuesToRenderAtVerbosity, sumSeverityCounts, } from '../utils/issue-rendering.js';
+import { endWithRefusal, leftoverIssueOf, NOTHING_FINISHED, writeDocument } from '../utils/document-writer.js';
+import { countCollapsedFindings, formatCollapsedFindingsHint, formatIssueLines, formatSeverityBreakdown, issuesToRenderAtVerbosity, } from '../utils/issue-rendering.js';
 import { resolveIssueSeverity } from '../utils/issue-severity.js';
 import { createLogger } from '../utils/logger.js';
-import { writeYamlOutput } from '../utils/output.js';
-import { relativizePathEntries } from '../utils/relativize-paths.js';
-import { nothingCheckedFinding } from '../utils/run-integrity.js';
+import { classifyInputFault, readInputFile, unlistableDirectoryRefusal } from '../utils/project-root-policy.js';
+import { relativizePath } from '../utils/relativize-paths.js';
+import { RUN_INTEGRITY_CODE } 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';
+import { compatLaneIssues } from './audit/compat-lane-findings.js';
 import { crawlOwnsSubtree, distributedTreeFindings, getOrCreateGitTracker, gitTrackerForProjectRoot, isWithin, resetGitTrackerCache, } from './audit/distributed-tree.js';
 import { withClonedRepo } from './audit/git-url-clone.js';
-import { buildHierarchicalOutput } from './audit/hierarchical-output.js';
+import { addMisconfigurationIssues, 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';
@@ -55,12 +56,13 @@ const RESOURCE_TYPE_CLAUDE_PLUGIN = 'claude-plugin';
  */
 async function buildVATProjectContext(scanRoot, logger, locationRoot) {
     const configPath = safePath.join(scanRoot, VAT_CONFIG_FILENAME);
-    if (!fs.existsSync(configPath)) {
+    // A probe the OS refuses is the config's source fault, never "no config here".
+    if (!pathPresent(configPath, { follow: scanRoot }, everywhere('source'), 'probe')) {
         return null;
     }
     let config;
     try {
-        config = loadConfig(scanRoot);
+        config = loadConfig(scanRoot, 'source');
     }
     catch (error) {
         logger.debug(`Config-aware audit: skipping invalid config in ${scanRoot}: ${String(error)}`);
@@ -96,23 +98,17 @@ async function buildVATProjectContext(scanRoot, logger, locationRoot) {
     }
     return { skillConfigs };
 }
-/**
- * Convert PackagingValidationResult to ValidationResult for consistent audit output.
- * In audit mode, we merge allErrors (which includes both errors and warnings after
- * severity resolution but WITHOUT allow suppression) into the standard issues array.
- *
- * Compat verdicts (COMPAT_TARGET_*) are computed from the result's observations
- * and the config-level targets, then merged into the issue list.
- */
-/**
- * The one-line human summary of a severity distribution.
- *
- * Every result that carries findings renders its counts the same way, so a reader
- * comparing two entries is comparing the same sentence.
- */
-function formatCountsSummary(counts) {
-    return `${counts.errors} errors, ${counts.warnings} warnings, ${counts.info} info`;
+/** A file carries an error-severity finding — the `filesWithErrors` bucket. */
+function hasErrors(result) {
+    return countBySeverity(result.issues).errors > 0;
+}
+/** A file's worst actionable finding is a warning — the `filesWithWarnings` bucket. */
+function hasOnlyWarnings(result) {
+    const { errors, warnings } = countBySeverity(result.issues);
+    return errors === 0 && warnings > 0;
 }
+/** `vat audit` has no `--strict`: warnings never move its exit code. */
+const AUDIT_GATE = { strict: false };
 /**
  * Append findings to a result and re-derive everything that describes them.
  *
@@ -124,17 +120,25 @@ function formatCountsSummary(counts) {
  *
  * Mutates in place, because the audit pipeline hands these results around by
  * reference and there is no single place a rebuilt copy could be swapped in.
+ * The sentence comes from the same `describeIssues` the producer used, so the
+ * re-derived one is exactly what the producer says for the grown list — never a
+ * second wording, and never a stale "Valid plugin" beside a warning.
  */
 function appendIssues(result, issues) {
     if (issues.length === 0) {
         return;
     }
     result.issues.push(...issues);
-    const counts = countBySeverity(result.issues);
-    result.status = calculateValidationStatus(result.issues);
-    result.issueCounts = counts;
-    result.summary = formatCountsSummary(counts);
+    Object.assign(result, describeIssues(result.issues, result.type));
 }
+/**
+ * Convert PackagingValidationResult to ValidationResult for consistent audit output.
+ * In audit mode, we merge allErrors (which includes both errors and warnings after
+ * severity resolution but WITHOUT allow suppression) into the standard issues array.
+ *
+ * Compat verdicts (COMPAT_TARGET_*) are computed from the result's observations
+ * and the config-level targets, then merged into the issue list.
+ */
 function packagingResultToValidationResult(skillPath, result, configTargets, locationRoot) {
     // allErrors contains all emitted issues (errors + warnings) after severity resolution
     // but without allow suppression — exactly what audit wants. Verdicts are
@@ -143,14 +147,11 @@ function packagingResultToValidationResult(skillPath, result, configTargets, loc
     const issues = verdictIssues.length > 0
         ? [...result.allErrors, ...verdictIssues]
         : result.allErrors;
-    const issueCounts = countBySeverity(issues);
     const out = {
         path: skillPath,
         type: RESOURCE_TYPE_AGENT_SKILL,
-        status: calculateValidationStatus(issues),
-        summary: formatCountsSummary(issueCounts),
+        ...describeIssues(issues, RESOURCE_TYPE_AGENT_SKILL),
         issues,
-        issueCounts,
         metadata: {
             lineCount: result.metadata.skillLines,
             name: result.skillName,
@@ -196,7 +197,7 @@ function packagingResultToValidationResult(skillPath, result, configTargets, loc
  *
  * ⚠️ 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
+ * `fsFaultOf` 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.
@@ -317,7 +318,7 @@ function recordUnloadableConfig(err, logger, locationRoot) {
     // 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';
+    const why = fsFaultOf(err) === undefined ? 'unloadable' : 'unreadable';
     logger.warn(`Ignoring ${why} config at ${configPath}; skills it governs are validated`
         + ` config-free: ${err.message}`);
 }
@@ -340,7 +341,7 @@ function recordUnloadableConfig(err, logger, locationRoot) {
 function degradingDiscovery(configRoot, logger, locationRoot) {
     return {
         degrade: (refusal) => {
-            recordRefusedDiscovery(new DirectoryListingRefusedError(refusal, { root: configRoot, remedy: SKILLS_INCLUDE_REMEDY }), configRoot, logger, locationRoot);
+            recordRefusedDiscovery(new DirectoryListingRefusedError(refusal, { root: configRoot, remedy: SKILLS_INCLUDE_REMEDY, side: 'source' }), configRoot, logger, locationRoot);
         },
     };
 }
@@ -372,7 +373,7 @@ function degradingDiscovery(configRoot, logger, locationRoot) {
 function degradingRegistry(projectRoot, logger, locationRoot) {
     return {
         degrade: (refusal) => {
-            const err = new DirectoryListingRefusedError(refusal, { root: projectRoot, remedy: listingRefusalRemedy(projectRoot) });
+            const err = new DirectoryListingRefusedError(refusal, { root: projectRoot, remedy: listingRefusalRemedy(projectRoot), side: 'source' });
             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}`);
         },
@@ -469,8 +470,10 @@ async function validateSingleSkill(skillPath, options, logger, locationRoot, cra
         // 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, { unreadable }),
+            registry: await crawlAndResolveRegistry(projectRoot, { outputs: [], unreadable }),
             unreadable,
+            // An audit only reads the trees it scans.
+            outputs: [],
             locationRoot,
             projectSkills: await resolveProjectDeclaredEvalSuites(skillPath, degradingDiscovery(projectRoot, logger, locationRoot)),
             // The RUN's probe, not this call's — see {@link runSuiteProbe}. This lane
@@ -486,7 +489,8 @@ async function validateSingleSkill(skillPath, options, logger, locationRoot, cra
         return configAware;
     }
     // Fallback: basic validation. Severity is applied by `applySeverityFilter`.
-    const validateOptions = { skillPath, locationRoot, validation: {} };
+    // The audited skill is the verb's input.
+    const validateOptions = { skillPath, locationRoot, validation: {}, side: 'source' };
     if (options.warnUnreferencedFiles) {
         validateOptions.checkUnreferencedFiles = true;
     }
@@ -533,13 +537,13 @@ 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.
+ * Publishes the report envelope through the one writer, and ends on the code
+ * the written document derives — the rule every report verb shares: `OK` when
+ * no finding is at error severity, `FINDINGS` when one is (a run that audited
+ * zero files carries the writer's `RESOURCE_CHECK_BROKEN`), `ERROR` only when
+ * the audit did not finish (`status: error`, with the refusal in `error.code`).
+ * Warnings never move the exit code — audit has no `--strict`;
+ * `validation.severity` is the dial that decides what counts.
  */
 export function createAuditCommand() {
     const audit = new Command('audit');
@@ -607,12 +611,19 @@ Description:
   (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.
+  The report envelope every report verb publishes (YAML on stdout):
+  - status: ok (no findings) | findings (at least one) | error (did not finish)
+  - examined: files read; summary: findings by severity; gate: { strict: false }
+  - findings: every finding, each with the file to open as 'location'
+  - data.root: the scan root every path is relative to (null for a git URL,
+      whose data.provenance names the source instead)
+  - data.counts: filesPassed / filesWithWarnings / filesWithErrors /
+      pathsUnreadable; data.files: one row per file (status, summary,
+      compatibility, settings); data.hierarchical: the --user grouping
+  - error: { code, message } when status is error
 
-  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.
+  A run that audited ZERO files is not a pass: the report carries one
+  non-overridable RESOURCE_CHECK_BROKEN finding and ends on exit 1.
 
 Validation Behavior:
   Audit surfaces all validation issues for inspection.
@@ -620,9 +631,8 @@ Validation Behavior:
   - NEVER applies validation.allow (allowed codes are always shown)
   - 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
+  For gated validation that honours validation.allow, use: vat skills validate
   For the full list of codes and severity defaults, see: docs/validation-codes.md
 
   Default: Validates SKILL.md and all transitively linked markdown files
@@ -640,7 +650,10 @@ Validation Checks:
   Warnings (should fix):
   - Skill exceeds recommended length (>5000 lines)
   - With --compat: a declared target cannot or may not run the skill
-    (COMPAT_TARGET_INCOMPATIBLE, COMPAT_TARGET_NEEDS_REVIEW)
+    (COMPAT_TARGET_INCOMPATIBLE, COMPAT_TARGET_NEEDS_REVIEW); a plugin or a
+    path the analysis could not look at (COMPAT_NOT_CHECKED)
+  - With --compat --settings: something the plugin declares that the settings
+    block (SETTINGS_POLICY_CONFLICT)
   - Unreferenced files detected (with --warn-unreferenced-files)
 
   Info (observations):
@@ -679,20 +692,23 @@ Config-Aware Validation:
     skills.config.<name>.validation...     that one skill
 
 Exit Codes:
-  0 - The audit completed with nothing at error severity (warnings and
+  0 - The audit finished and no finding is 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.
+  1 - The audit finished with at least one error-severity finding
+      ('status: findings'), including zero files audited. A path inside the
+      tree the scan could not read, or a governing config that cannot be
+      loaded, is SCAN_PATH_UNREADABLE (warning): the run is degraded, not
+      failed, and the refused path is counted in data.counts.pathsUnreadable,
+      never in 'examined'.
+  2 - The audit did not finish ('status: error', the reason in error.code):
+      USAGE_INVALID for a path that does not exist, a file no audit lane
+      recognises, a git URL that does not parse, --user with no Claude
+      config dir, --settings without --compat or together with --user, or a
+      --settings file that does not exist; INPUT_UNREADABLE for a root
+      directory the OS will not list, a git URL that would not clone, or a
+      settings file (named or auto-discovered) the OS refuses, that does not
+      parse, or that fails the settings schema; INTERNAL_ERROR for a defect
+      in VAT.
 
 Examples:
   $ vat audit ./plugins/              # Audit recursively (default)
@@ -739,23 +755,22 @@ export function userScanTargets(candidates, recursive) {
 }
 /**
  * Handle --user audit: scans ~/.claude/plugins, ~/.claude/skills, ~/.claude/marketplaces
- * and outputs hierarchical YAML. Calls process.exit() when done.
+ * and publishes the report with its `data.hierarchical` view. Calls process.exit() when done.
  */
 async function auditUserDirectories(recursive, options, startTime, logger) {
     const { claudeDir, pluginsDir, skillsDir, marketplacesDir } = getClaudeUserPaths();
     // --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);
-    const pluginsDirExists = fs.existsSync(pluginsDir);
-    const skillsDirExists = fs.existsSync(skillsDir);
-    const marketplacesDirExists = fs.existsSync(marketplacesDir);
+    // Each install root is the operator's own configuration (`CLAUDE_CONFIG_DIR`/`HOME`), so it is
+    // its own `within`; a probe the OS refuses is that root's source fault, never "not installed".
+    const userRootPresent = (dir) => pathPresent(dir, { follow: dir }, everywhere('source'), 'probe');
+    const pluginsDirExists = userRootPresent(pluginsDir);
+    const skillsDirExists = userRootPresent(skillsDir);
+    const marketplacesDirExists = userRootPresent(marketplacesDir);
     if (!pluginsDirExists && !skillsDirExists && !marketplacesDirExists) {
-        logger.error(`No user-level Claude directories found:`);
-        logger.error(`  Plugins: ${pluginsDir}`);
-        logger.error(`  Skills: ${skillsDir}`);
-        logger.error(`  Marketplaces: ${marketplacesDir}`);
-        logger.error('Claude plugins/skills/marketplaces have not been installed yet.');
-        process.exit(ExitCode.ERROR);
+        throw new CommandRefusalError('USAGE_INVALID', `No user-level Claude directories found (plugins: ${pluginsDir}, skills: ${skillsDir}, marketplaces: ${marketplacesDir}). `
+            + 'Claude plugins, skills and marketplaces have not been installed yet — set CLAUDE_CONFIG_DIR to the config dir to audit.');
     }
     const scanned = [];
     // The roots that exist, minus any one another already covers — see
@@ -765,27 +780,36 @@ async function auditUserDirectories(recursive, options, startTime, logger) {
         ...(skillsDirExists ? [skillsDir] : []),
         ...(marketplacesDirExists ? [marketplacesDir] : []),
     ];
-    for (const target of userScanTargets(present, recursive)) {
+    // In order: the targets share the population cache and the logger.
+    await forEachInOrder(userScanTargets(present, recursive), async (target) => {
         logger.debug(`Auditing user-level resources at: ${target}`);
         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);
+    // document — see the same call in `buildAuditReport`. The misconfiguration
+    // findings join the RESULTS, not only the hierarchy, so the envelope counts them.
+    const results = addMisconfigurationIssues(withDegradedConfigFindings(scanned), scanRoot);
     // Run compatibility analysis if --compat flag is set
     const compatMap = options.compat
-        ? await runCompatAnalysis(results, logger, scanRoot) // --settings not supported in --user mode
+        ? await runCompatAnalysis(results, logger, scanRoot) // --settings is refused under --user
         : undefined;
     const verbose = options.verbose ?? false;
     const skillResults = results.filter((r) => SKILL_RESULT_TYPES.has(r.type));
     const hierarchical = buildHierarchicalOutput(skillResults, verbose, scanRoot);
-    const summary = calculateHierarchicalSummary(results, hierarchical, startTime, compatMap, verbose, scanRoot);
-    writeYamlOutput(summary);
+    const report = buildAuditDocument(results, {
+        root: scanRoot,
+        compatMap,
+        verbose,
+        hierarchical,
+        durationMs: Date.now() - startTime,
+    });
+    const written = writeDocument('audit', report, 'yaml');
     if (verbose) {
         renderVerboseEvidence(results, scanRoot, logger);
     }
-    logHierarchicalSummary(results, summary.issues, logger);
+    logHierarchicalSummary({ results, written, data: report.data, root: scanRoot, verbose }, logger);
+    process.exit(exitCodeForReport(written));
 }
 /** Skill resource types that can have per-skill validation config. */
 const SKILL_RESULT_TYPES = new Set([RESOURCE_TYPE_AGENT_SKILL, 'vat-agent']);
@@ -809,7 +833,8 @@ const SKILL_RESULT_TYPES = new Set([RESOURCE_TYPE_AGENT_SKILL, 'vat-agent']);
  */
 export function deriveScanRoot(targetPath) {
     const resolved = safePath.resolve(targetPath);
-    const isDirectory = fs.existsSync(resolved) && fs.statSync(resolved).isDirectory();
+    // The operator's own target: its own `within`.
+    const isDirectory = followedKindSync(resolved, resolved) === 'directory';
     return isDirectory ? resolved : safePath.resolve(resolved, '..');
 }
 /**
@@ -841,15 +866,12 @@ function deriveConfigRoot(targetPath) {
  * Build the recalculated status and summary after issues have been filtered.
  */
 function buildFilteredResult(result, filteredIssues) {
-    const counts = countBySeverity(filteredIssues);
     return {
         ...result,
-        status: calculateValidationStatus(filteredIssues),
-        // Spreading `result` carried the PRE-filter `issueCounts` forward, so a
+        // Spreading `result` carried the PRE-filter counts forward, so a
         // `severity: ignore` config left the counts describing findings the report
         // no longer contained. The counts are re-derived, never inherited.
-        issueCounts: counts,
-        summary: formatCountsSummary(counts),
+        ...describeIssues(filteredIssues, result.type),
         issues: filteredIssues,
     };
 }
@@ -970,29 +992,57 @@ function isEmptiedUnreadablePathResult(result) {
         && result.metadata === undefined;
 }
 /**
- * Resolve `--settings`-driven EffectiveSettings if both --settings and
- * --compat flags are present. Logs warnings for misconfiguration paths.
+ * Refuse a `--settings` the run would otherwise ignore, before any scan or clone.
+ *
+ * Every arm used to be a stderr line and exit 0: without `--compat` a warning
+ * and no settings check; under `--user` nothing at all; and a named file that
+ * is absent read as "no settings", so `--compat --settings /typo.json` printed
+ * `findings: []` for a check that never compared anything. The sibling verb
+ * `audit settings --file <missing>` refuses the same path.
+ *
+ * @throws {CommandRefusalError} `USAGE_INVALID` for a flag the run cannot honour
+ *   or a named file that is absent; `INPUT_UNREADABLE` for one the OS refuses
  */
-async function resolveEffectiveSettings(options, scanPath, logger) {
-    if (!options.settings)
-        return undefined;
+function refuseUnusableSettingsFlag(options) {
+    if (options.settings === undefined || options.settings === false)
+        return;
     if (!options.compat) {
-        logger.error('Warning: --settings requires --compat to be effective');
-        return undefined;
+        throw new CommandRefusalError('USAGE_INVALID', '--settings requires --compat: the settings check runs inside the compatibility analysis. Add --compat, or drop --settings.');
+    }
+    if (options.user) {
+        throw new CommandRefusalError('USAGE_INVALID', '--settings is not supported with --user. Audit the plugin directory with --compat --settings instead, or drop --settings.');
     }
+    if (typeof options.settings !== 'string')
+        return;
+    readInputFile(safePath.resolve(options.settings), { origin: 'argument', message: `Path does not exist: ${safePath.resolve(options.settings)}` });
+}
+/**
+ * The EffectiveSettings `--settings` asks the compat analysis to check against.
+ * Called only under `--compat`; {@link refuseUnusableSettingsFlag} has already
+ * refused every combination the run cannot honour.
+ *
+ * @throws {CommandRefusalError} `INPUT_UNREADABLE` when a settings file (named
+ *   or auto-discovered) the OS refuses, does not parse, or fails its schema — the check cannot run, and a warning beside
+ *   an unchecked report was how it used to pass silently
+ */
+async function resolveEffectiveSettings(options, scanPath) {
+    if (!options.settings)
+        return undefined;
     const settingsFile = typeof options.settings === 'string' ? options.settings : undefined;
     try {
         return await readEffectiveSettings({ settingsFile, projectDir: scanPath });
     }
-    catch (err) {
-        logger.error(`Warning: could not load settings: ${String(err)}`);
-        return undefined;
+    catch (error) {
+        throw new CommandRefusalError('INPUT_UNREADABLE', `Claude settings could not be loaded for --settings: ${errorMessageOf(error)}`, { cause: error });
     }
 }
 /**
- * Run the audit pipeline at `scanPath` and assemble the report document,
- * without writing anything. The document states its coordinate system once
- * (`root`) and every `path`/`location` beneath it is relative to that root.
+ * Run the audit pipeline at `scanPath` and assemble the report, without
+ * writing anything. The report states its coordinate system once
+ * (`data.root`) and every `path`/`location` beneath it is relative to that root.
+ *
+ * The zero-files refusal is NOT here: the writer adds it from the registry's
+ * denominator on the way out, as it does for every report verb.
  *
  * @internal Exported for integration testing only — not part of the public CLI API.
  */
@@ -1026,7 +1076,7 @@ export async function buildAuditReport(scanPath, options, startTime, logger) {
     // only show more than the adopter asked for, never less.
     let config;
     try {
-        config = loadConfig(deriveConfigRoot(scanPath));
+        config = loadConfig(deriveConfigRoot(scanPath), 'source');
     }
     catch (err) {
         // `warn`, not `debug`. Falling back to no config is the safe direction — it
@@ -1040,60 +1090,95 @@ export async function buildAuditReport(scanPath, options, startTime, logger) {
     // Apply severity filtering: hide codes whose effective severity is 'ignore'.
     // Allow is deliberately NOT applied — audit shows every finding.
     const results = applySeverityFilter(rawResults, config);
-    const effectiveSettings = await resolveEffectiveSettings(options, scanPath, logger);
     // Run compatibility analysis if --compat flag is set
     const compatMap = options.compat
-        ? await runCompatAnalysis(results, logger, scanRoot, effectiveSettings, vatContextForCompat)
+        ? await runCompatAnalysis(results, logger, scanRoot, await resolveEffectiveSettings(options, scanPath), vatContextForCompat)
         : undefined;
     const verbose = options.verbose ?? false;
     return {
         results,
-        document: calculateSummary(results, startTime, compatMap, verbose, scanRoot),
+        report: buildAuditDocument(results, {
+            root: scanRoot,
+            compatMap,
+            verbose,
+            hierarchical: null,
+            durationMs: Date.now() - startTime,
+        }),
     };
 }
-/** Strip the run root from a report whose base cannot be named as a path. */
-function withoutRoot(document) {
-    const copy = { ...document };
-    delete copy['root'];
-    return copy;
+/**
+ * A URL audit's report: its run root is a random tempdir — not reproducible and
+ * useless to a reader — so `data.root` is `null`, `data.provenance` states the
+ * base instead (url @ ref @ commit), and any string still spelling the tempdir
+ * is rewritten relative to the clone.
+ */
+export function urlAuditReport(report, provenance, tempRoot) {
+    const rewritten = rewritePathsInResults(report, tempRoot);
+    return { ...rewritten, data: { ...rewritten.data, root: null, provenance } };
 }
-async function runAuditAtPath(scanPath, options, overrides = {}) {
+/**
+ * Audit `scanPath` and build the report, without publishing it: a URL audit publishes it only
+ * once its clone is disposed of, so a clone left behind is a warning IN the document.
+ */
+async function buildAuditAtPath(scanPath, options, overrides = {}) {
     const logger = createLogger(options.debug ? { debug: true } : {});
     const startTime = Date.now();
     const verbose = options.verbose ?? false;
-    const { results, document } = await buildAuditReport(scanPath, options, startTime, logger);
-    // A URL audit's run root is a random tempdir: not reproducible and useless to
-    // a reader. The provenance header states the base instead (url @ ref @ commit)
-    // and every path below is already relative to the clone, so drop `root`
-    // rather than print a path nobody can resolve.
-    const finalDocument = overrides.tempRoot === undefined ? document : rewritePathsInResults(withoutRoot(document), overrides.tempRoot);
-    if (overrides.provenance) {
-        process.stdout.write(renderProvenanceHeader(overrides.provenance));
-    }
-    writeYamlOutput(finalDocument);
+    const { results, report } = await buildAuditReport(scanPath, options, startTime, logger);
+    const scanRoot = deriveScanRoot(scanPath);
+    if (overrides.provenance !== undefined) {
+        // The human half of the provenance: the machine half is `data.provenance`.
+        logger.info(renderProvenanceHeader(overrides.provenance).trimEnd());
+    }
+    const published = overrides.provenance === undefined || overrides.tempRoot === undefined
+        ? report
+        : urlAuditReport(report, overrides.provenance, overrides.tempRoot);
+    return { results, report: published, scanRoot, logger, verbose, startTime };
+}
+/**
+ * Publish a built audit, with `added` findings the run learned of after building it.
+ *
+ * @returns What was published. The caller exits with the code it calls for.
+ */
+function publishAudit(built, added) {
+    const { results, scanRoot, logger, verbose } = built;
+    const report = withAddedFindings(built.report, added);
+    const written = writeDocument('audit', report, 'yaml');
     if (verbose) {
-        renderVerboseEvidence(results, document.root, logger);
+        renderVerboseEvidence(results, scanRoot, logger);
     }
-    handleAuditResults(results, document, logger, verbose);
-    logger.debug(`Audit complete in ${Date.now() - startTime}ms`);
+    handleAuditResults({ results, written, data: report.data, root: scanRoot, verbose }, logger);
+    logger.debug(`Audit complete in ${Date.now() - built.startTime}ms`);
+    return written;
 }
 async function runUrlAudit(rawInput, options) {
-    const parsed = parseGitUrl(rawInput);
-    await withClonedRepo(parsed, { keepTempForDebug: options.debug === true }, async ({ targetDir, tempdir, provenance }) => {
+    let parsed;
+    try {
+        parsed = parseGitUrl(rawInput);
+    }
+    catch (error) {
+        // The argument is the operator's, and it does not name a source.
+        throw new CommandRefusalError('USAGE_INVALID', errorMessageOf(error), { cause: error });
+    }
+    const { value: built, leftover } = await withClonedRepo(parsed, { keepTempForDebug: options.debug === true }, ({ targetDir, tempdir, provenance }) => {
         // Re-enter the audit pipeline against the cloned target. Strip --user
         // (it doesn't apply to URL audits).
         const innerOptions = { ...options, user: false };
-        await runAuditAtPath(targetDir, innerOptions, {
+        return buildAuditAtPath(targetDir, innerOptions, {
             provenance,
             tempRoot: tempdir,
         });
     });
+    // Only now, the clone disposed of: one it left behind is a warning in the document.
+    const written = publishAudit(built, leftover === undefined ? [] : toFindings([leftoverIssueOf(leftover)]));
+    process.exit(exitCodeForReport(written));
 }
 export async function auditCommand(targetPath, options) {
     const logger = createLogger(options.debug ? { debug: true } : {});
     const startTime = Date.now();
     resetAuditCaches();
     try {
+        refuseUnusableSettingsFlag(options);
         // A local path always wins. `isGitUrl` accepts bare `owner/repo` GitHub
         // shorthand, which is indistinguishable from an ordinary two-segment
         // relative path (`plugins/arc`, `docs/guides`, `packages/cli`). Asking
@@ -1101,7 +1186,9 @@ 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.
-        if (targetPath !== undefined && !fsExistsSync(targetPath) && isGitUrl(targetPath)) {
+        // The operator's own argument: its own `within`. A probe the OS refuses is its source fault,
+        // never "names nothing on disk" — that would send a local path to the network.
+        if (targetPath !== undefined && !pathPresent(targetPath, { follow: targetPath }, everywhere('source'), 'probe') && isGitUrl(targetPath)) {
             await runUrlAudit(targetPath, options);
             return;
         }
@@ -1112,19 +1199,14 @@ 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);
+        const unusable = await unusableRootRefusal(scanPath);
+        if (unusable !== undefined)
+            throw unusable;
+        process.exit(exitCodeForReport(publishAudit(await buildAuditAtPath(scanPath, options), [])));
     }
     catch (error) {
-        // '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');
+        logger.debug(`Audit did not finish after ${Date.now() - startTime}ms`);
+        endWithRefusal('audit', refusalCodeOf(error), error, 'yaml', AUDIT_GATE, NOTHING_FINISHED);
     }
 }
 /**
@@ -1132,42 +1214,49 @@ export async function auditCommand(targetPath, options) {
  * 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
+ * file no audit lane recognises, is the INVOCATION's mistake — a `USAGE_INVALID`
+ * refusal (exit 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`.
+ * 🚨 **And a root DIRECTORY the OS refuses to list.** It used to be left to
+ * the scan, which degraded it to `SCAN_PATH_UNREADABLE` and ended on the
+ * zero-files refusal at exit 1 — while `vat resources validate`, `check`,
+ * `query` and `scan` all end the same argument at exit 2. One outcome, two
+ * codes. Nothing under an unlistable root can be examined, so the audit could
+ * not do its job: an `INPUT_UNREADABLE` refusal, exit 2 like a missing path.
+ *
+ * ONLY the root. 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` and the `audit` row of
+ * `exit-code-matrix-path-unlistable.system.test.ts`.
  */
-async function unusableRootReason(scanPath) {
+async function unusableRootRefusal(scanPath) {
     let isDirectory;
     try {
         isDirectory = fs.lstatSync(scanPath).isDirectory();
     }
     catch (error) {
-        if (isPathAbsentError(error))
-            return `Path does not exist: ${scanPath}`;
-        return undefined;
+        // Absent is the invocation's mistake; any other error (an `EACCES` parent) is
+        // the input's refusal — never a scan that starts anyway.
+        return classifyInputFault(scanPath, error, { origin: 'argument', message: `Path does not exist: ${scanPath}` });
     }
-    if (isDirectory || detectFormat(scanPath) === RESOURCE_TYPE_AGENT_SKILL)
+    if (isDirectory)
+        return unlistableDirectoryRefusal(scanPath);
+    if (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}`;
+    return new CommandRefusalError('USAGE_INVALID', `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
  * branch of {@link getValidationResults} focused so cognitive complexity stays
  * within the ESLint budget.
  */
-async function validateSurface(surface, options, logger, locationRoot) {
+function validateSurface(surface, options, logger, locationRoot) {
     if (surface.type === RESOURCE_TYPE_AGENT_SKILL) {
         // No crawl: this arm only runs for a MULTI-surface root, which in practice is
         // skill-claude-plugin (SKILL.md beside .claude-plugin/plugin.json). The plugin
@@ -1184,13 +1273,10 @@ async function validateSurface(surface, options, logger, locationRoot) {
  * Validate every surface enumerated at a directory root (used when
  * `enumerateSurfaces` returns more than one — e.g., skill-claude-plugin).
  */
-async function validateMultipleSurfaces(surfaces, scanPath, options, logger, locationRoot) {
+function validateMultipleSurfaces(surfaces, scanPath, options, logger, locationRoot) {
     logger.debug(`Detected ${surfaces.length.toString()} surfaces at ${scanPath}: ${surfaces.map((s) => s.type).join(', ')}`);
-    const results = [];
-    for (const surface of surfaces) {
-        results.push(await validateSurface(surface, options, logger, locationRoot));
-    }
-    return results;
+    // In order: the surfaces share the population cache and the logger.
+    return mapInOrder(surfaces, (surface) => validateSurface(surface, options, logger, locationRoot));
 }
 /**
  * Additive inventory-detector pass — runs the pure-function detectors
@@ -1234,18 +1320,19 @@ async function recurseIntoMarketplacePlugins(marketplaceInv, recursive, options,
     const marketplaceRoot = safePath.resolve(marketplaceInv.path);
     const seen = new Set([marketplaceRoot]);
     const results = [];
-    for (const plugin of marketplaceInv.discovered.plugins) {
+    // In order: the `seen` dedupe must see each plugin before the next one starts.
+    await forEachInOrder(marketplaceInv.discovered.plugins, async (plugin) => {
         const pluginPath = safePath.resolve(plugin.path);
         if (seen.has(pluginPath)) {
             logger.debug(`  Skipping marketplace-recurse into already-visited path: ${pluginPath}`);
-            continue;
+            return;
         }
         seen.add(pluginPath);
         logger.debug(`  Recursing into marketplace path-source plugin: ${pluginPath}`);
         // Same run root — recursing into a co-located plugin must NOT re-anchor.
         const pluginResults = await getValidationResults(pluginPath, recursive, options, logger, locationRoot);
         results.push(...pluginResults);
-    }
+    });
     return results;
 }
 /**
@@ -1309,7 +1396,7 @@ function appendInventoryParseErrors(result, inv, locationRoot) {
         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
+    // Status was hand-set to 'error' here while the counts and description kept
     // describing the pre-append list. One appender derives all three.
     appendIssues(result, parseIssues);
 }
@@ -1352,7 +1439,7 @@ export async function getValidationResults(scanPath, recursive, options, logger,
     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))
+        if (fsFaultOf(error) === undefined)
             throw error;
         logger.debug(`Unreadable audit subject: ${scanPath}`);
         return [unreadablePathResult(scanPath, error, locationRoot)];
@@ -1426,13 +1513,10 @@ function withoutHostedRefusals(result, hosted) {
         return [];
     if (issues.length === result.issues.length)
         return [result];
-    const issueCounts = countBySeverity(issues);
     return [{
             ...result,
-            status: calculateValidationStatus(issues),
-            summary: formatCountsSummary(issueCounts),
+            ...describeIssues(issues, result.type),
             issues,
-            issueCounts,
         }];
 }
 async function validateAuditSubject(scanPath, recursive, options, logger, locationRoot) {
@@ -1499,7 +1583,7 @@ async function validateAuditSubject(scanPath, recursive, options, logger, locati
         return [result];
     }
     // If unknown format, check if it's a directory we can scan
-    if (await isScannableDirectory(scanPath)) {
+    if (await isScannableDirectory(scanPath, locationRoot)) {
         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
@@ -1527,10 +1611,10 @@ async function validateAuditSubject(scanPath, recursive, options, logger, locati
  * `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');
+async function isScannableDirectory(scanPath, locationRoot) {
     try {
-        return (await fsp.stat(scanPath)).isDirectory();
+        // `scanPath` is crawled beneath the run's scan root: its links are read before the kernel follows them.
+        return (await followedKind(scanPath, locationRoot)) === 'directory';
     }
     catch (error) {
         if (isPathAbsentError(error))
@@ -1550,11 +1634,12 @@ async function isScannableDirectory(scanPath) {
 async function validatePluginSkillsViaInventory(scanPath, options, logger, locationRoot, excludeSkillPaths = new Set()) {
     const inv = await pluginInventoryAt(scanPath);
     const results = [];
-    for (const skill of inv.discovered.skills) {
+    // In order: the skills share the population cache and the logger.
+    await forEachInOrder(inv.discovered.skills, async (skill) => {
         const resolvedPath = safePath.resolve(skill.files.skillMd);
         if (excludeSkillPaths.has(resolvedPath)) {
             logger.debug(`  Skipping already-validated skill (inventory): ${skill.files.skillMd}`);
-            continue;
+            return;
         }
         logger.debug(`  Validating plugin-bundled skill (inventory): ${skill.files.skillMd}`);
         // Guarded PER SKILL, not left to the boundary. The boundary guard answers at
@@ -1572,12 +1657,12 @@ async function validatePluginSkillsViaInventory(scanPath, options, logger, locat
             results.push(await validateSingleSkill(skill.files.skillMd, options, logger, locationRoot, false));
         }
         catch (error) {
-            if (!isFilesystemAccessError(error))
+            if (fsFaultOf(error) === undefined)
                 throw error;
             logger.debug(`  Unreadable plugin-bundled skill: ${skill.files.skillMd}`);
             results.push(unreadablePathResult(skill.files.skillMd, error, locationRoot));
         }
-    }
+    });
     return results;
 }
 /**
@@ -1643,9 +1728,10 @@ function withRelativePath(message, absolutePath, locationRoot) {
  */
 export async function runCompatAnalysis(results, logger, locationRoot, effectiveSettings, vatContext = null) {
     const compatMap = new Map();
-    for (const result of results) {
+    // In order: each plugin's explanations go to the logger as it is analyzed.
+    await forEachInOrder(results, async (result) => {
         if (result.type !== RESOURCE_TYPE_CLAUDE_PLUGIN)
-            continue;
+            return;
         const entry = {
             compat: await analyzeOrExplain(result.path, locationRoot, vatContext, logger),
         };
@@ -1653,9 +1739,31 @@ export async function runCompatAnalysis(results, logger, locationRoot, effective
             entry.settings = await settingsVerdict(result.path, effectiveSettings, locationRoot, logger);
         }
         compatMap.set(result.path, entry);
-    }
+    });
+    fileLaneFindings(results, compatMap, locationRoot);
     return compatMap;
 }
+/**
+ * File what the lanes found, and what they could not look at, as findings on each plugin's own
+ * result — so the envelope's status, the row's status and the file counts say what the
+ * `compatibility:` and `settings:` blocks say. A path whose refusal the document already carries
+ * (by its code: `compatLaneIssues` decides which) is not filed a second time.
+ */
+function fileLaneFindings(results, compatMap, locationRoot) {
+    const locationOf = (absolutePath) => issueLocation(absolutePath, locationRoot) || '.';
+    const filed = results.flatMap((result) => result.issues.map((issue) => ({ code: issue.code, location: issue.location ?? locationOf(result.path) })));
+    for (const result of results) {
+        const entry = compatMap.get(result.path);
+        if (entry === undefined)
+            continue;
+        const issues = compatLaneIssues(locationOf(result.path), {
+            compatibility: entry.compat,
+            ...(entry.settings !== undefined && { settings: renderSettingsBlock(entry.settings, locationRoot) }),
+        }, filed);
+        appendIssues(result, issues);
+        filed.push(...issues.map((issue) => ({ code: issue.code, location: issue.location ?? locationOf(result.path) })));
+    }
+}
 /**
  * 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:
@@ -1743,45 +1851,65 @@ function applyCompatMap(results, compatMap, locationRoot) {
     return results;
 }
 /**
- * Strip `evidence` from per-file results and `compatibility.evidence` when
- * the audit is not running in --verbose mode. Producing the field at all
- * (even as `[]`) would clutter terse YAML; we omit the key entirely.
+ * `compatibility.evidence` is published only under `--verbose`. Producing the
+ * field at all (even as `[]`) would clutter terse YAML; the key is omitted.
  */
 function stripCompatEvidence(compat) {
     const out = { ...compat };
     delete out['evidence'];
     return out;
 }
-function applyVerboseFilter(results, verbose) {
-    if (verbose)
-        return results;
-    return results.map(r => {
-        const stripped = { ...r };
-        delete stripped['evidence'];
-        if (r.compatibility !== undefined) {
-            stripped['compatibility'] = stripCompatEvidence(r.compatibility);
-        }
-        return stripped;
-    });
-}
 /**
- * Nested carriers inside a file entry that publish their own `path`.
- *
- * `linkedFiles[].path` sat absolute in every document while every sibling
- * `path` and `location` beside it was root-relative — 532 of them in a single
- * `vat audit --user` run. Naming the carrier here is what re-bases it; a new
- * carrier that is not named keeps shipping absolute paths.
- */
-const NESTED_PATH_CARRIERS = ['linkedFiles'];
-function calculateSummary(results, startTime, compatMap, verbose, root) {
-    const { entries, ...base } = buildBaseSummary(results, startTime);
-    const withCompat = applyCompatMap(entries, compatMap, root);
-    return {
-        // Stated once, first, and the only absolute path in the document.
-        root,
-        ...base,
-        files: relativizePathEntries(applyVerboseFilter(withCompat, verbose), root, NESTED_PATH_CARRIERS),
-    };
+ * A result's row. `status` and `summary` are re-derived from its FINAL issue
+ * list here — a producer that appended findings after publishing its counts
+ * cannot leave the row describing the list as it was.
+ */
+function fileRow(result, root, verbose) {
+    const row = { path: relativizePath(result.path, root), type: result.type, ...summarizeIssues(result.issues) };
+    if (result.compatibility !== undefined)
+        row.compatibility = verbose ? result.compatibility : stripCompatEvidence(result.compatibility);
+    if (result.settings !== undefined)
+        row.settings = result.settings;
+    return row;
+}
+/**
+ * Every file's findings, flattened, each naming the file to open. A finding a
+ * validator published without a `location` inherits its file's row path, so a
+ * consumer never has to join a finding back to the row it came from.
+ */
+function auditFindings(results, root) {
+    return toFindings(results.flatMap((result) => result.issues.map((issue) => issue.location === undefined ? { ...issue, location: relativizePath(result.path, root) } : issue)));
+}
+/**
+ * Assemble the report envelope from the per-file results.
+ *
+ * ONE builder for the directory lane, the `--user` lane and the corpus scan's
+ * per-plugin document, so none of them can publish a status or a count the
+ * others would not. `examined` is the files READ — a refused path is counted
+ * in `data.counts.pathsUnreadable` and nowhere else — and the writer turns a
+ * zero into the run's `RESOURCE_CHECK_BROKEN` finding.
+ *
+ * @param results - One result per audited file or refused path
+ * @param context - The root, the compat lanes' output and the `--user` view
+ * @returns The report, before the writer's run-integrity pass
+ */
+export function buildAuditDocument(results, context) {
+    const { root, compatMap, verbose, hierarchical, durationMs } = context;
+    const { examined, counts } = countFilesByStatus(results);
+    return buildReport({
+        examined,
+        findings: auditFindings(results, root),
+        data: {
+            // Stated once, and the only absolute path in the document.
+            root,
+            provenance: null,
+            counts,
+            files: applyCompatMap([...results], compatMap, root).map((result) => fileRow(result, root, verbose)),
+            hierarchical,
+        },
+        gate: AUDIT_GATE,
+        durationMs,
+    });
 }
 /**
  * Maps a CAPABILITY_* observation code to the family of pattern IDs whose
@@ -1879,21 +2007,22 @@ 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.
+ * The stderr half of the run-level refusal, so the human channel says what the
+ * document says. The writer derives it (the registry's denominator for `audit`
+ * is files); this only RENDERS the finding the WRITTEN report carries. Both
+ * stderr lanes call it first, because "Audit successful: 0 file(s) passed"
+ * over a refused run is the exact disagreement the refusal exists to end
+ * (invariant 6 of `run-integrity.ts`).
  *
  * @returns Whether a refusal was rendered, so the caller skips its verdict line
  */
-function logRunIntegrity(runIssues, logger) {
-    if (runIssues === undefined || runIssues.length === 0)
+function logRunIntegrity(written, logger) {
+    const refusals = written.findings.filter((finding) => finding.code === RUN_INTEGRITY_CODE);
+    if (refusals.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(`Audit is not a verdict: it audited ${written.examined} files`);
+    for (const refusal of refusals) {
+        for (const line of formatIssueLines(refusal, '  '))
             logger.error(line);
     }
     return true;
@@ -1933,36 +2062,34 @@ function logSettingsTotals(files, logger) {
         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;
-    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) {
+/**
+ * The human channel for the directory lane, read off the WRITTEN report — the
+ * file counts, and the findings of the files that carry an actionable one. The
+ * exit code is not decided here: the caller ends on `exitCodeForReport`.
+ */
+function handleAuditResults({ results, written, data, root, verbose }, logger) {
+    const { filesWithErrors: errorCount, filesWithWarnings: warningCount, filesPassed: successCount, } = data.counts;
+    logSettingsTotals(data.files, logger);
+    if (logRunIntegrity(written, 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`);
-        logFindingsForStatus(results, 'error', summary.root, logger.error.bind(logger), verbose);
+        logFindingsForStatus(results, hasErrors, root, logger.error.bind(logger), verbose);
     }
     else if (warningCount > 0) {
         logger.info(`Audit passed with warnings: ${warningCount} file(s)`);
-        logFindingsForStatus(results, 'warning', summary.root, logger.info.bind(logger), verbose);
+        logFindingsForStatus(results, hasOnlyWarnings, root, logger.info.bind(logger), verbose);
     }
     else {
-        // `success` means "nothing actionable", NOT "nothing to see" — name the
-        // informational findings or the YAML and the stderr line disagree.
+        // `ok` over info findings still means "nothing actionable", NOT "nothing
+        // to see" — name them or the YAML and the stderr line disagree.
         const withFindings = countResultsWithFindings(results);
         logger.info(withFindings > 0
             ? `Audit successful: ${successCount} file(s) passed (${withFindings} with informational findings)`
             : `Audit successful: ${successCount} file(s) passed`);
     }
     renderAuditFooter(results, logger);
-    process.exit(refused || errorCount > 0 ? ExitCode.FINDINGS : ExitCode.OK);
 }
 /**
  * Render the skill-quality checklist footer when audit results contain
@@ -2015,7 +2142,7 @@ function renderAuditFooter(results, logger) {
  * cannot answer the question.
  *
  * Pure: takes results, returns lines. It reads `issues` and never rewrites it,
- * because `runAuditAtPath` builds the YAML document from the very same array.
+ * because `buildAuditAtPath` builds the YAML document from the very same array.
  *
  * @internal Exported for unit testing only — not part of the public CLI API.
  */
@@ -2051,8 +2178,8 @@ export function formatAuditFindingsLines(results, root, verbose) {
  * The banner counts FILES and the blocks below count FINDINGS; both are needed,
  * and `logFn` picks the channel the calling branch already established.
  */
-function logFindingsForStatus(results, status, root, logFn, verbose) {
-    const selected = results.filter((r) => r.status === status);
+function logFindingsForStatus(results, inBucket, root, logFn, verbose) {
+    const selected = results.filter(inBucket);
     for (const line of formatAuditFindingsLines(selected, root, verbose)) {
         logFn(line);
     }
@@ -2134,15 +2261,16 @@ async function handleFileEntry(entry, fullPath, options, logger, scanCtx) {
             const skillDir = safePath.resolve(fullPath, '..');
             const unreadable = degradingRegistry(findProjectRoot(skillDir) ?? skillDir, logger, locationRoot);
             const sharedCtx = scanCtx.gitTracker === null
-                ? { locationRoot, projectSkills, suiteProbe, unreadable }
-                : { gitTracker: scanCtx.gitTracker, locationRoot, projectSkills, suiteProbe, unreadable };
+                ? { locationRoot, projectSkills, suiteProbe, unreadable, outputs: [] }
+                : { gitTracker: scanCtx.gitTracker, locationRoot, projectSkills, suiteProbe, unreadable, outputs: [] };
             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. Severity is applied by `applySeverityFilter`.
-        const validateOptions = { skillPath: fullPath, locationRoot, validation: {} };
+        // The audited skill is the verb's input.
+        const validateOptions = { skillPath: fullPath, locationRoot, validation: {}, side: 'source' };
         if (options.warnUnreferencedFiles) {
             validateOptions.checkUnreferencedFiles = true;
         }
@@ -2179,7 +2307,7 @@ async function validatePluginDirectory(dir, logger, locationRoot) {
  */
 const inventoryRegistryCache = new Map();
 /** Build (once per run, per root) the registry the plugin inventory link walk needs. */
-async function getOrCreateInventoryRegistry(projectRoot) {
+function getOrCreateInventoryRegistry(projectRoot) {
     const cached = inventoryRegistryCache.get(projectRoot);
     if (cached !== undefined) {
         return cached;
@@ -2215,7 +2343,7 @@ async function getOrCreateInventoryRegistry(projectRoot) {
  * case to encode here. This is the call site that carried all 786 measured
  * `git check-ignore` spawns.
  */
-async function pluginInventoryAt(dir) {
+function pluginInventoryAt(dir) {
     const projectRoot = findProjectRoot(dir);
     return extractClaudePluginInventory(dir, {
         ...(projectRoot === null
@@ -2280,11 +2408,11 @@ async function resolveScanContext(dirPath, locationRoot, logger) {
  * 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`
+ * This result is a `data.files[]` row but NOT a file read: `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.
+ * `data.counts.pathsUnreadable`, outside `examined` and the status counts. A
+ * root the OS refused therefore examines zero files and ends on the zero-files
+ * refusal, instead of `examined: 1` over a path nothing read.
  */
 function unreadablePathResult(dirPath, error, locationRoot) {
     // `issueLocation` is `path.relative`, so it answers `''` when the subject IS the
@@ -2305,14 +2433,11 @@ function unreadablePathResult(dirPath, error, locationRoot) {
             detail: `${location}: ${reason}`,
         }),
     ];
-    const issueCounts = countBySeverity(issues);
     return {
         path: dirPath,
         type: 'unknown',
-        status: calculateValidationStatus(issues),
-        summary: formatCountsSummary(issueCounts),
+        ...describeIssues(issues, 'unknown'),
         issues,
-        issueCounts,
     };
 }
 /**
@@ -2342,7 +2467,7 @@ async function validateScanSubject(subject, options, logger, scanCtx, claims) {
         }
         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)) {
+        if (subject.kind === 'skill' && ownsOwnCrawl(subjectCtx, subject.path) && await crawlOwnsSubtree(subject.path, locationRoot)) {
             claims.claim(subject.dir);
         }
         return result === null ? [] : [result];
@@ -2352,7 +2477,7 @@ async function validateScanSubject(subject, options, logger, scanCtx, claims) {
         // 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))
+        if (fsFaultOf(error) === undefined)
             throw error;
         const path = subject.kind === 'plugin' ? subject.dir : subject.path;
         logger.debug(`Unreadable entry: ${path}`);
@@ -2403,29 +2528,16 @@ async function scanDirectory(dirPath, recursive, options, logger, scanCtx) {
     }
     const results = population.refusals.map((refusal) => {
         logger.debug(`Unreadable directory: ${refusal.directory}`);
-        const err = new DirectoryListingRefusedError(refusal, { root: dirPath, remedy: scanRefusalRemedy() });
+        const err = new DirectoryListingRefusedError(refusal, { root: dirPath, remedy: scanRefusalRemedy(), side: 'source' });
         return unreadablePathResult(refusal.directory, err, scanCtx.locationRoot);
     });
     const claims = new SubtreeClaims();
-    for (const subject of population.subjects) {
+    // In order: `claims` resolves each subtree against the subjects before it.
+    await forEachInOrder(population.subjects, async (subject) => {
         results.push(...await validateScanSubject(subject, options, logger, scanCtx, claims));
-    }
+    });
     return results;
 }
-/**
- * Calculate overall status from validation results
- */
-function calculateOverallStatus(results) {
-    const errorCount = results.filter((r) => r.status === 'error').length;
-    const warningCount = results.filter((r) => r.status === 'warning').length;
-    if (errorCount > 0) {
-        return 'error';
-    }
-    if (warningCount > 0) {
-        return 'warning';
-    }
-    return 'success';
-}
 /**
  * How many results carry at least one finding.
  *
@@ -2449,147 +2561,53 @@ function isUnreadablePathResult(result) {
         && result.issues.every((issue) => issue.code === 'SCAN_PATH_UNREADABLE');
 }
 /**
- * Count files by their own status.
+ * Count files by their worst actionable severity, and the files read.
  *
  * 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`.
+ * `chmod 000` on the whole root gave one file scanned, none passed, a warning
+ * status and exit 0 — nothing read, gate green. Kept out of every status count
+ * too, or `filesWithWarnings` would exceed the files read.
  */
 function countFilesByStatus(results) {
     const scanned = results.filter((r) => !isUnreadablePathResult(r));
+    const withErrors = scanned.filter(hasErrors).length;
+    const withWarnings = scanned.filter(hasOnlyWarnings).length;
     return {
-        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,
-    };
-}
-/**
- * Build base summary structure (used by both flat and hierarchical), together
- * with the entries the document will publish.
- *
- * `issueCounts` is named exactly as it is on every individual file entry, and
- * means the same thing at both levels: findings, by severity. `summary` only ever
- * counts files.
- *
- * The header total and every per-file total come from ONE traversal of the
- * final issue set, and the entries carrying those per-file totals are returned
- * from the same pass. Before that, the header was derived from the issue
- * records while each file's `issueCounts` was whatever its producer had
- * published — and a producer that appends findings after publishing (or never
- * sets the counts at all: `validatePlugin` writes `status` and `summary` but
- * not `issueCounts`) left the two disagreeing inside one document. A real
- * `vat audit --user` run said 55/422/504 in the header over per-file counts
- * summing to 55/360/405, with 91 of 614 entries declaring `{0,0,0}` above the
- * findings they listed. Re-deriving here means the header and the sum are the
- * same arithmetic on the same array, so they cannot drift again no matter what
- * a producer forgets.
- *
- * `linkedFiles[].issues` are deliberately NOT added: every linked finding is
- * also present in its owner's `issues`, so the nested list is a VIEW of records
- * already counted, not extra records. `audit-report-coherence.integration.test.ts`
- * pins that subset relation, because counting once is only correct while it holds.
- *
- * 🚨 **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 };
-    const entries = results.map((result) => {
-        const counts = countBySeverity(result.issues);
-        issueCounts.errors += counts.errors;
-        issueCounts.warnings += counts.warnings;
-        issueCounts.info += counts.info;
-        return { ...result, issueCounts: counts };
-    });
-    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,
-        // 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`,
-    };
-}
-/**
- * Calculate summary for hierarchical output
- */
-function calculateHierarchicalSummary(results, hierarchical, startTime, compatMap, verbose, root) {
-    const { entries, ...base } = buildBaseSummary(results, startTime);
-    const withCompat = applyCompatMap(entries, compatMap, root);
-    return {
-        root,
-        ...base,
-        summary: {
-            ...base.summary,
-            marketplaces: hierarchical.marketplaces.length,
-            cachedPlugins: hierarchical.cachedPlugins.length,
-            standalonePlugins: hierarchical.standalonePlugins.length,
-            standaloneSkills: hierarchical.standaloneSkills.length,
+        examined: scanned.length,
+        counts: {
+            filesPassed: scanned.length - withErrors - withWarnings,
+            filesWithWarnings: withWarnings,
+            filesWithErrors: withErrors,
+            pathsUnreadable: results.length - scanned.length,
         },
-        files: relativizePathEntries(applyVerboseFilter(withCompat, verbose), root, NESTED_PATH_CARRIERS),
-        hierarchical,
     };
 }
 /**
- * Log hierarchical summary to stderr
+ * The human channel for the `--user` lane, read off the WRITTEN report. The
+ * exit code is not decided here: the caller ends on `exitCodeForReport`.
  */
-function logHierarchicalSummary(results, runIssues, logger) {
-    const status = calculateOverallStatus(results);
+function logHierarchicalSummary({ results, written, data }, logger) {
+    const { filesWithErrors, filesWithWarnings } = data.counts;
     const skillsWithIssues = countResultsWithFindings(results);
     const totalSkills = results.length;
-    // Same rule as the per-file lane: the exit code follows `status`.
-    const refused = logRunIntegrity(runIssues, logger);
-    if (refused) {
+    if (logRunIntegrity(written, 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)`);
+    else if (filesWithErrors > 0) {
+        logger.error(`Audit found ${filesWithErrors} skill(s) with errors (${totalSkills} scanned, ${skillsWithIssues} with issues)`);
     }
-    else if (status === 'warning') {
-        const warningCount = results.filter((r) => r.status === 'warning').length;
-        logger.info(`Audit passed with warnings: ${warningCount} skill(s) (${totalSkills} scanned, ${skillsWithIssues} with issues)`);
+    else if (filesWithWarnings > 0) {
+        logger.info(`Audit passed with warnings: ${filesWithWarnings} skill(s) (${totalSkills} scanned, ${skillsWithIssues} with issues)`);
     }
     else if (skillsWithIssues > 0) {
-        // `success` means "nothing actionable", NOT "nothing to see". Saying only
-        // "N passed" over a pile of info findings is how they stayed invisible.
+        // Nothing actionable is NOT "nothing to see". Saying only "N passed" over
+        // a pile of info findings is how they stayed invisible.
         logger.info(`Audit successful: ${totalSkills} skill(s) passed (${skillsWithIssues} with informational findings)`);
     }
     else {
         logger.info(`Audit successful: ${totalSkills} skill(s) passed`);
     }
     renderAuditFooter(results, logger);
-    process.exit(refused || status === 'error' ? ExitCode.FINDINGS : ExitCode.OK);
 }
 //# sourceMappingURL=audit.js.map