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

package/dist/commands/skills/build.d.ts

@@ -6,27 +6,37 @@
  * packaging config (schema defaults -> config defaults -> per-skill overrides),
  * validates, and packages into dist/skills/<name>/.
  */
-import { type SeverityCounts } from '@vibe-agent-toolkit/agent-schema';
-import { type PackageSkillResult, type PackagingValidationResult } from '@vibe-agent-toolkit/agent-skills';
+import { type SeverityCounts, type ValidationIssue } from '@vibe-agent-toolkit/agent-schema';
+import { type DeclaredEvalSuite, type PackageSkillResult, type PackagingValidationResult, type SkillPackagingConfig } from '@vibe-agent-toolkit/agent-skills';
 import { Command } from 'commander';
+import { type createLogger } from '../../utils/logger.js';
+import { type DiscoveredSkill } from './command-helpers.js';
 export interface SkillsBuildCommandOptions {
     skill?: string;
     dryRun?: boolean;
     debug?: boolean;
+    verbose?: boolean;
 }
 export declare function createBuildCommand(): Command;
 /**
  * Render every emitted pre-build finding, each labelled with its own severity.
  *
  * `allErrors` is the full emitted set INCLUDING info (its name lies — see the
- * doc comment on `PackagingValidationResult`). Walking `activeErrors` plus only
- * the `ALLOW_EXPIRED` subset of `activeWarnings`, which is what this used to do,
+ * doc comment on `PackagingValidationResult`). Walking only the errors plus the
+ * `ALLOW_EXPIRED` subset of the warnings, which is what this used to do,
  * dropped every other warning and every info finding from a report that had
  * already decided to abort the build.
  *
+ * `verbose` picks how much of that set is spelled out, never how much of it is
+ * COUNTED: the heading is built from `allErrors` either way, so the severity
+ * breakdown stays whole even when the bodies below it do not (see
+ * `issuesToRenderAtVerbosity`). Every error is printed at both verbosities —
+ * these are the findings that just aborted the build, so putting one behind a
+ * flag would mean re-running to learn what broke.
+ *
  * Pure so the whole set is assertable, not a chosen subset of it.
  */
-export declare function formatPreBuildIssueReport(validationResult: PackagingValidationResult): string[];
+export declare function formatPreBuildIssueReport(validationResult: PackagingValidationResult, verbose: boolean): string[];
 /**
  * Render post-build integrity issues, each prefixed by its OWN resolved severity.
  *
@@ -35,10 +45,18 @@ export declare function formatPreBuildIssueReport(validationResult: PackagingVal
  * failed it, and the heading names the set's actual severity mix rather than
  * calling every set by its worst member.
  *
+ * The heading is unconditional and counts the WHOLE set; `verbose` decides only
+ * which findings get a block beneath it (see `issuesToRenderAtVerbosity`). This
+ * loop printing every occurrence is what made a 90-skill build emit 6,552 stderr
+ * lines against the 804 `vat skills validate` emitted for the same corpus — 1,620
+ * of them one high-cardinality warning code. A set whose findings all collapse
+ * still renders its heading: collapsing that too would turn a warning-carrying
+ * build into silence, which is the reassuring direction this module warns about.
+ *
  * Pure: returns the lines instead of writing them, so the whole rendered set is
  * assertable without capturing a stream.
  */
-export declare function formatPostBuildIssueReport(result: PackageSkillResult): string[];
+export declare function formatPostBuildIssueReport(result: PackageSkillResult, verbose: boolean): string[];
 /**
  * The archived summary of a build, as YAML fields.
  *
@@ -48,20 +66,91 @@ export declare function formatPostBuildIssueReport(result: PackageSkillResult):
  * from the same issues the human stream renders, and the per-severity counts
  * ride beside it because a status cannot express a three-valued distribution:
  * `success` here means "nothing you must act on", not "there was nothing to see".
+ *
+ * The header total reconciles against the document, by construction:
+ *
+ *     issueCounts === Σ skills[].issueCounts
+ *                   + Σ failedSkills[].issueCounts
+ *                   + runIssueCounts
+ *
+ * Every addend therefore has a ROW a reader can point at. Counting the failures
+ * only in the header — which is how this first shipped — reproduced, one command
+ * over, the exact defect `vat skills validate` was fixed for: a header reporting
+ * more than its rows summed to (there, 1814 warnings against 1800), leaving a
+ * consumer to hand-count a list to find out what the difference was. `--help`
+ * states this identity; changing it means changing that text too.
  */
 export declare function buildYamlSummary(results: Array<{
     name: string;
     result: PackageSkillResult;
-}>, duration: number): {
+}>, failures: readonly SkillBuildFailure[], duration: number, runIssues: readonly ValidationIssue[], skillsWithErrors: readonly string[]): {
     status: 'success' | 'warning' | 'error';
     issueCounts: SeverityCounts;
+    runIssueCounts: SeverityCounts;
     skillsBuilt: number;
+    skillsFailed: number;
+    skillsWithErrors: string[];
     skills: Array<{
         name: string;
         outputPath: string;
         filesPackaged: number;
         issueCounts: SeverityCounts;
     }>;
+    failedSkills: Array<{
+        name: string;
+        error: string;
+        issueCounts: SeverityCounts;
+    }>;
+    runIssues: ValidationIssue[];
     duration: string;
 };
+/** One discovered skill paired with the packaging config merged for it. */
+export interface BuildSkillSpec {
+    skill: DiscoveredSkill;
+    packagingConfig: SkillPackagingConfig;
+}
+/**
+ * A skill whose packaging THREW — it produced no artifact at all.
+ *
+ * Deliberately distinct from `skillsWithErrors`, which names skills that built
+ * successfully and then failed post-build validation. Collapsing the two would
+ * lose the only distinction that matters to the reader: whether `dist/skills/`
+ * contains anything for that name.
+ */
+export interface SkillBuildFailure {
+    name: string;
+    message: string;
+}
+/** Everything one `vat build` invocation produced, ready to report on. */
+export interface SkillBuildRun {
+    results: Array<{
+        name: string;
+        result: PackageSkillResult;
+    }>;
+    /** Findings that belong to the run, not to any one skill (ALLOW_UNUSED). */
+    runIssues: ValidationIssue[];
+    /** Names of skills that BUILT and whose own post-build validation errored. */
+    skillsWithErrors: string[];
+    /** Skills that never built because packaging threw. */
+    failures: SkillBuildFailure[];
+}
+/**
+ * Validate, package, and drain — the whole span of ONE `vat build` invocation.
+ *
+ * The allow-usage ledger created here spans EVERY skill and BOTH validation
+ * lanes (the source-tree pre-build check and the two lanes inside
+ * `packageSkill`), because `validation.allow` is declared once for the package
+ * while being evaluated once per skill per lane. Anything narrower reports
+ * entries that legitimately matched somewhere else as unused: measured on this
+ * repo's own 13-skill package, 3 live entries produced 32 false ALLOW_UNUSED
+ * warnings — 6 from the cross-skill seam, 26 because the two lanes inside
+ * `packageSkill` see a FILTERED issue population against a file packaging has
+ * renamed to `SKILL.md`, so entries scoped to a source filename are structurally
+ * incapable of matching there. A lane that sees a subset cannot answer "matched
+ * nothing"; only the union can. Hence one ledger, drained once, here.
+ *
+ * Extracted from the command body so the span is testable without driving
+ * `process.exit` — the drain seam is the thing worth asserting.
+ */
+export declare function runSkillBuild(specs: readonly BuildSkillSpec[], cwd: string, logger: ReturnType<typeof createLogger>, projectSkills: readonly DeclaredEvalSuite[], verbose?: boolean): Promise<SkillBuildRun>;
 //# sourceMappingURL=build.d.ts.map

package/dist/commands/skills/build.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../../src/commands/skills/build.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAKL,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,EAG/B,MAAM,kCAAkC,CAAC;AAG1C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAwBpC,MAAM,WAAW,yBAAyB;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,wBAAgB,kBAAkB,IAAI,OAAO,CAkE5C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CACvC,gBAAgB,EAAE,yBAAyB,GAC1C,MAAM,EAAE,CASV;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,EAAE,CAQ/E;AAwHD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,kBAAkB,CAAA;CAAE,CAAC,EAC5D,QAAQ,EAAE,MAAM,GACf;IACD,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;IACxC,WAAW,EAAE,cAAc,CAAC;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,KAAK,CAAC;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,UAAU,EAAE,MAAM,CAAC;QACnB,aAAa,EAAE,MAAM,CAAC;QACtB,WAAW,EAAE,cAAc,CAAC;KAC7B,CAAC,CAAC;IACH,QAAQ,EAAE,MAAM,CAAC;CAClB,CAyBA"}
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../../src/commands/skills/build.ts"],"names":[],"mappings":"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"}

package/dist/commands/skills/build.js

@@ -8,16 +8,16 @@
  */
 import { existsSync } from 'node:fs';
 import { rm } from 'node:fs/promises';
-import { calculateValidationStatus, countBySeverity, } from '@vibe-agent-toolkit/agent-schema';
+import { allowUnusedIssues, calculateValidationStatus, countBySeverity, createAllowUsageLedger, } from '@vibe-agent-toolkit/agent-schema';
 import { packageSkills, packagingConfigToPackageOptions, skillNameToFsPath, validateSkillForPackaging, } from '@vibe-agent-toolkit/agent-skills';
 import { safePath } from '@vibe-agent-toolkit/utils';
 import { Command } from 'commander';
 import * as yaml from 'yaml';
-import { handleCommandError } from '../../utils/command-error.js';
+import { handleCommandError, handleValidationGateFailure } from '../../utils/command-error.js';
 import { loadConfig } from '../../utils/config-loader.js';
-import { collectPostBuildIssues, formatIssueLines, formatIssueSetHeading, sumSeverityCounts, } from '../../utils/issue-rendering.js';
+import { collectPostBuildIssues, formatIssueLines, formatIssueSetHeading, formatRunIssueLines, issuesToRenderAtVerbosity, sumSeverityCounts, } from '../../utils/issue-rendering.js';
 import { requireProjectRoot } from '../../utils/project-root-policy.js';
-import { mergeSkillPackagingConfig } from '../../utils/skill-packaging-config.js';
+import { collectDeclaredEvalSuites, mergeSkillPackagingConfig } from '../../utils/skill-packaging-config.js';
 import { applyConfigVerdicts } from '../../utils/verdict-helpers.js';
 import { filterSkillsByName, setupCommandContext, writeYamlHeader, } from './command-helpers.js';
 import { discoverSkillsFromConfig } from './skill-discovery.js';
@@ -28,6 +28,7 @@ export function createBuildCommand() {
         .argument('[path]', 'Path to project directory (default: current directory)')
         .option('--skill <name>', 'Build specific skill only')
         .option('--dry-run', 'Preview build without creating files')
+        .option('-v, --verbose', 'Show every individual finding, not just the errors')
         .option('--debug', 'Enable debug logging')
         .action(buildCommand)
         .addHelpText('after', `
@@ -67,9 +68,38 @@ Output:
   YAML summary -> stdout (for programmatic parsing)
   Build progress -> stderr (for human reading)
 
+  On stderr, every findings heading names the whole set and its severity
+  breakdown, and errors are always printed in full beneath it. Warnings and
+  info findings stay collapsed into that heading unless --verbose, because
+  they are the high-cardinality ones (one adopter skill carries 348
+  LINK_DROPPED_BY_DEPTH warnings alone). The stdout YAML is NOT affected by
+  --verbose: it carries every finding at every verbosity.
+
+  skills:         one row per skill that produced a bundle
+  failedSkills:   one row per skill that could not be packaged AT ALL (no
+                  bundle exists for it); each carries name, error and an
+                  issueCounts of one error
+  skillsWithErrors / skillsWithErrorNames:
+                  the OTHER failure mode — skills that packaged fine and then
+                  emitted post-build validation errors. They are counted in
+                  skillsBuilt, not skillsFailed, so read BOTH before concluding
+                  a run was clean: the exit code follows this one too.
+  runIssueCounts: findings that belong to the run rather than to any one
+                  skill (ALLOW_UNUSED)
+  issueCounts:    the run total, which reconciles against the rows above:
+
+                    issueCounts = sum(skills[].issueCounts)
+                                + sum(failedSkills[].issueCounts)
+                                + runIssueCounts
+
+                  Every error, warning and info in the header total is
+                  therefore attributable to a row you can point at.
+
 Exit Codes:
   0 - All skills built successfully (or dry-run preview)
-  1 - One or more skills emitted validation errors
+  1 - One or more skills emitted validation errors, or could not be packaged
+      at all (a skill that fails to package does NOT abort the others; the
+      rest still build and the failures are listed under failedSkills)
   2 - System error (config invalid, directory not found)
 
 Requirements:
@@ -87,18 +117,25 @@ Example:
  * Render every emitted pre-build finding, each labelled with its own severity.
  *
  * `allErrors` is the full emitted set INCLUDING info (its name lies — see the
- * doc comment on `PackagingValidationResult`). Walking `activeErrors` plus only
- * the `ALLOW_EXPIRED` subset of `activeWarnings`, which is what this used to do,
+ * doc comment on `PackagingValidationResult`). Walking only the errors plus the
+ * `ALLOW_EXPIRED` subset of the warnings, which is what this used to do,
  * dropped every other warning and every info finding from a report that had
  * already decided to abort the build.
  *
+ * `verbose` picks how much of that set is spelled out, never how much of it is
+ * COUNTED: the heading is built from `allErrors` either way, so the severity
+ * breakdown stays whole even when the bodies below it do not (see
+ * `issuesToRenderAtVerbosity`). Every error is printed at both verbosities —
+ * these are the findings that just aborted the build, so putting one behind a
+ * flag would mean re-running to learn what broke.
+ *
  * Pure so the whole set is assertable, not a chosen subset of it.
  */
-export function formatPreBuildIssueReport(validationResult) {
+export function formatPreBuildIssueReport(validationResult, verbose) {
     const lines = [];
     if (validationResult.allErrors.length > 0) {
         lines.push(`\n   ${formatIssueSetHeading(validationResult.allErrors)}:`);
-        for (const issue of validationResult.allErrors) {
+        for (const issue of issuesToRenderAtVerbosity(validationResult.allErrors, verbose)) {
             lines.push(...formatIssueLines(issue, '     '));
         }
     }
@@ -112,15 +149,23 @@ export function formatPreBuildIssueReport(validationResult) {
  * failed it, and the heading names the set's actual severity mix rather than
  * calling every set by its worst member.
  *
+ * The heading is unconditional and counts the WHOLE set; `verbose` decides only
+ * which findings get a block beneath it (see `issuesToRenderAtVerbosity`). This
+ * loop printing every occurrence is what made a 90-skill build emit 6,552 stderr
+ * lines against the 804 `vat skills validate` emitted for the same corpus — 1,620
+ * of them one high-cardinality warning code. A set whose findings all collapse
+ * still renders its heading: collapsing that too would turn a warning-carrying
+ * build into silence, which is the reassuring direction this module warns about.
+ *
  * Pure: returns the lines instead of writing them, so the whole rendered set is
  * assertable without capturing a stream.
  */
-export function formatPostBuildIssueReport(result) {
+export function formatPostBuildIssueReport(result, verbose) {
     const issues = collectPostBuildIssues(result);
     if (issues.length === 0)
         return [];
     const lines = [`   ${formatIssueSetHeading(issues, 'post-build')}:`];
-    for (const issue of issues) {
+    for (const issue of issuesToRenderAtVerbosity(issues, verbose)) {
         lines.push(...formatIssueLines(issue, '     '));
     }
     return lines;
@@ -129,8 +174,8 @@ export function formatPostBuildIssueReport(result) {
  * Log post-build integrity issues to stderr (the human stream; stdout is
  * reserved for the YAML summary).
  */
-function logPostBuildIssues(result, logger) {
-    for (const line of formatPostBuildIssueReport(result)) {
+function logPostBuildIssues(result, logger, verbose) {
+    for (const line of formatPostBuildIssueReport(result, verbose)) {
         logger.info(line);
     }
 }
@@ -145,12 +190,17 @@ function displayIgnoredErrors(validationResult, logger) {
         }
     }
 }
-/**
- * Validate skill before building
- */
-async function validateSkillOrExit(skillName, sourcePath, packagingConfig, logger, locationRoot) {
+async function validateSkillOrExit(input) {
+    const { skillName, sourcePath, packagingConfig, logger, locationRoot, allowLedger, projectSkills, verbose } = input;
     logger.debug(`   Validating skill: ${skillName}`);
-    const validationResult = await validateSkillForPackaging(sourcePath, packagingConfig);
+    // The run's ledger, not this call's: an allow entry scoped to a SOURCE
+    // filename can only ever match here — packaging renames the file to
+    // `SKILL.md` and the built lane drops the source-only codes — so a build that
+    // withholds this lane's matches from the run reports live entries as dead.
+    //
+    // The run's declared eval suites likewise: this lane must model the same bundle
+    // the packager below produces, and that bundle excludes EVERY skill's test input.
+    const validationResult = await validateSkillForPackaging(sourcePath, packagingConfig, 'source', { allowLedger, projectSkills });
     applyConfigVerdicts(validationResult, packagingConfig.targets, sourcePath, locationRoot);
     if (validationResult.status !== 'error') {
         if (validationResult.ignoredErrors.length > 0) {
@@ -161,12 +211,15 @@ async function validateSkillOrExit(skillName, sourcePath, packagingConfig, logge
     // Validation failed - display every emitted finding and exit
     logger.error(`\nSkill validation failed: ${skillName}`);
     logger.error(`   Source: ${sourcePath}`);
-    for (const line of formatPreBuildIssueReport(validationResult)) {
+    for (const line of formatPreBuildIssueReport(validationResult, verbose)) {
         logger.error(line);
     }
     displayIgnoredErrors(validationResult, logger);
     logger.error(`\n   Build aborted due to validation errors`);
-    process.exit(1);
+    // Every finding above went to STDERR. Exiting here without the stdout summary
+    // is what made `vat skills build | jq .status` return an empty document
+    // alongside exit 1 — the one case the help text documents exit 1 for.
+    handleValidationGateFailure(skillName, validationResult.allErrors);
 }
 /**
  * Output dry-run results
@@ -206,6 +259,14 @@ function performDryRun(skillsToBuild, duration, logger) {
     logger.info(`\nDry-run complete (no files created)`);
     logger.info(`   Run without --dry-run to build the skills`);
 }
+/**
+ * What ONE unpackageable skill contributes to the run's counts.
+ *
+ * A fresh object per row: these are published as separate YAML nodes, and a
+ * shared reference is how a document grows anchors (or a later mutation edits
+ * every row at once).
+ */
+const failureIssueCounts = () => ({ errors: 1, warnings: 0, info: 0 });
 /**
  * The archived summary of a build, as YAML fields.
  *
@@ -215,12 +276,37 @@ function performDryRun(skillsToBuild, duration, logger) {
  * from the same issues the human stream renders, and the per-severity counts
  * ride beside it because a status cannot express a three-valued distribution:
  * `success` here means "nothing you must act on", not "there was nothing to see".
+ *
+ * The header total reconciles against the document, by construction:
+ *
+ *     issueCounts === Σ skills[].issueCounts
+ *                   + Σ failedSkills[].issueCounts
+ *                   + runIssueCounts
+ *
+ * Every addend therefore has a ROW a reader can point at. Counting the failures
+ * only in the header — which is how this first shipped — reproduced, one command
+ * over, the exact defect `vat skills validate` was fixed for: a header reporting
+ * more than its rows summed to (there, 1814 warnings against 1800), leaving a
+ * consumer to hand-count a list to find out what the difference was. `--help`
+ * states this identity; changing it means changing that text too.
  */
-export function buildYamlSummary(results, duration) {
+export function buildYamlSummary(results, failures, duration, runIssues, skillsWithErrors) {
     const perSkill = results.map(({ name, result }) => {
         const issues = collectPostBuildIssues(result);
         return {
             name,
+            // KNOWN, DELIBERATELY NOT FIXED — this is an ABSOLUTE path, so stdout carries
+            // `$HOME`. Confirmed on a real 90-skill adopter run:
+            // `outputPath: /Users/<user>/Workspaces/.../dist/skills/<name>`. It is absolute
+            // because `runSkillBuild` builds it with `safePath.resolve(cwd, 'dist', ...)`.
+            //
+            // Do NOT "helpfully" relativize it. It is blocked on an approved-but-unbuilt
+            // design decision that is the project owner's call: the document must state one
+            // `root:` and re-base every path onto it, the same coordinate-system rule
+            // `vat audit` already follows (see `deriveScanRoot` in ../audit.ts — "the ONE base
+            // every `path` and `location` in a report is expressed relative to"). Making this
+            // one field relative ahead of that decision picks the anchor by accident and
+            // leaves the document in two coordinate systems.
             outputPath: result.outputPath,
             filesPackaged: result.files.dependencies.length + 1,
             issueCounts: countBySeverity(issues),
@@ -228,26 +314,76 @@ export function buildYamlSummary(results, duration) {
         };
     });
     const allIssues = perSkill.flatMap((s) => s.issues);
+    const runIssueCounts = countBySeverity(runIssues);
+    // A skill that THREW emits no issues at all — it never reached the lanes that
+    // produce them. Deriving the header purely from issue channels therefore said
+    // `success` for a run the command then exited 1 on, which is exactly the
+    // reassuring contradiction this summary exists to prevent. Each failure is
+    // counted as one error so `status`, `issueCounts` and the exit code agree —
+    // and that error is published ON the failure's own row (see
+    // `failureIssueCounts`), never as a header-only addend, so the identity
+    // documented in `--help` holds.
+    const failedSkills = failures.map(({ name, message }) => ({
+        name,
+        error: message,
+        issueCounts: failureIssueCounts(),
+    }));
     return {
-        status: calculateValidationStatus(allIssues),
-        issueCounts: sumSeverityCounts(perSkill.map((s) => s.issueCounts)),
+        status: failures.length > 0
+            ? 'error'
+            : calculateValidationStatus([...allIssues, ...runIssues]),
+        issueCounts: sumSeverityCounts([
+            ...perSkill.map((s) => s.issueCounts),
+            ...failedSkills.map((s) => s.issueCounts),
+            runIssueCounts,
+        ]),
+        runIssueCounts,
         skillsBuilt: results.length,
+        skillsFailed: failures.length,
+        // The OTHER meaning of "failed", published because the exit code follows
+        // THIS one and nothing in the document did. `skillsFailed` counts skills
+        // that could not be packaged at all; a skill that packaged fine and then
+        // emitted post-build validation errors is a `skillsBuilt`, so a real run
+        // printed "Build failed: 3 skill(s) emitted post-build validation errors"
+        // over `skillsFailed: 0` and `failedSkills: []`, and exited 1. A CI job
+        // reading either field saw a clean build. Both categories are now named.
+        skillsWithErrors: [...skillsWithErrors],
+        // `skills` lists what exists on disk. A failed skill is published in its own
+        // list rather than here, because every field of this shape (outputPath,
+        // filesPackaged) would have to be invented for a bundle that was not written.
         skills: perSkill.map(({ name, outputPath, filesPackaged, issueCounts }) => ({
             name,
             outputPath,
             filesPackaged,
             issueCounts,
         })),
+        failedSkills,
+        runIssues: [...runIssues],
         duration: `${duration}ms`,
     };
 }
 /**
  * Output build results
  */
-function outputBuildYaml(results, duration) {
-    const { status, skillsBuilt, issueCounts, skills, duration: durationText } = buildYamlSummary(results, duration);
-    writeYamlHeader({ status, skillsBuilt });
-    process.stdout.write(yaml.stringify({ issueCounts, skills }, { indent: 2, lineWidth: 0, aliasDuplicateObjects: false }));
+function outputBuildYaml(results, failures, duration, runIssues, skillsWithErrors) {
+    const summary = buildYamlSummary(results, failures, duration, runIssues, skillsWithErrors);
+    const { status, skillsBuilt, skillsFailed, issueCounts, runIssueCounts, skills, failedSkills, duration: durationText, } = summary;
+    // In the header, beside the other two counts: this is the number the exit code
+    // actually follows, so a reader who stops at the header is not misled by it.
+    writeYamlHeader({
+        status,
+        skillsBuilt,
+        skillsFailed,
+        skillsWithErrors: summary.skillsWithErrors.length,
+    });
+    process.stdout.write(yaml.stringify({
+        issueCounts,
+        runIssueCounts,
+        skills,
+        failedSkills,
+        skillsWithErrorNames: summary.skillsWithErrors,
+        runIssues: summary.runIssues,
+    }, { indent: 2, lineWidth: 0, aliasDuplicateObjects: false }));
     process.stdout.write(`duration: ${durationText}\n`);
 }
 /**
@@ -270,6 +406,94 @@ async function cleanStaleSkillOutputs(cwd, skillName) {
         }
     }
 }
+/**
+ * Validate, package, and drain — the whole span of ONE `vat build` invocation.
+ *
+ * The allow-usage ledger created here spans EVERY skill and BOTH validation
+ * lanes (the source-tree pre-build check and the two lanes inside
+ * `packageSkill`), because `validation.allow` is declared once for the package
+ * while being evaluated once per skill per lane. Anything narrower reports
+ * entries that legitimately matched somewhere else as unused: measured on this
+ * repo's own 13-skill package, 3 live entries produced 32 false ALLOW_UNUSED
+ * warnings — 6 from the cross-skill seam, 26 because the two lanes inside
+ * `packageSkill` see a FILTERED issue population against a file packaging has
+ * renamed to `SKILL.md`, so entries scoped to a source filename are structurally
+ * incapable of matching there. A lane that sees a subset cannot answer "matched
+ * nothing"; only the union can. Hence one ledger, drained once, here.
+ *
+ * Extracted from the command body so the span is testable without driving
+ * `process.exit` — the drain seam is the thing worth asserting.
+ */
+export async function runSkillBuild(specs, cwd, logger, projectSkills, verbose = false) {
+    const allowLedger = createAllowUsageLedger();
+    // Validate all skills before building
+    for (const { skill, packagingConfig } of specs) {
+        const outputDir = safePath.resolve(cwd, 'dist', 'skills', skillNameToFsPath(skill.name));
+        logger.info(`\nBuilding skill: ${skill.name}`);
+        logger.info(`   Source: ${skill.sourcePath}`);
+        logger.info(`   Output: ${outputDir}`);
+        await validateSkillOrExit({
+            skillName: skill.name,
+            sourcePath: skill.sourcePath,
+            packagingConfig,
+            logger,
+            locationRoot: cwd,
+            allowLedger,
+            projectSkills,
+            verbose,
+        });
+    }
+    // Build all skills with a shared registry.
+    //
+    // `projectSkills` is the run's declared eval suites — the whole project's, not
+    // `specs`'. `--skill x` narrows what gets BUILT; it never narrows what counts as
+    // test input, because an excluded skill's suite is still an answer key that must
+    // not ship inside x's bundle.
+    const buildSpecs = specs.map(({ skill, packagingConfig }) => ({
+        skillPath: skill.sourcePath,
+        options: packagingConfigToPackageOptions(packagingConfig, {
+            skillPath: skill.sourcePath,
+            outputPath: safePath.resolve(cwd, 'dist', 'skills', skillNameToFsPath(skill.name)),
+        }, projectSkills),
+    }));
+    const outcomes = await packageSkills(buildSpecs, cwd, allowLedger);
+    const results = [];
+    const skillsWithErrors = [];
+    const failures = [];
+    for (const [i, spec] of specs.entries()) {
+        const outcome = outcomes[i];
+        if (!outcome)
+            continue;
+        if (outcome.status === 'failed') {
+            // No `Built N files` line here: nothing was built, and claiming a count
+            // for an absent bundle is the misreport this branch exists to avoid.
+            logger.error(`\nBuild failed for skill: ${spec.skill.name}`);
+            logger.error(`   ${outcome.error.message}`);
+            failures.push({ name: spec.skill.name, message: outcome.error.message });
+            continue;
+        }
+        const { result } = outcome;
+        logger.info(`   Built ${result.files.dependencies.length + 1} files`);
+        logPostBuildIssues(result, logger, verbose);
+        if (result.hasErrors) {
+            skillsWithErrors.push(spec.skill.name);
+        }
+        results.push({ name: spec.skill.name, result });
+    }
+    // Drain point: every skill and every lane has now contributed, so this is the
+    // first place the run can honestly say an entry matched nothing. A skill that
+    // threw still contributed the matches it made before throwing — which is why
+    // the drain must stay here, after a partially-failed batch, and not move into
+    // a success-only path. (Before per-skill containment the drain never ran at
+    // all on a throw, because the exception propagated straight past it.)
+    //
+    // Known residual: a skill that threw never reached its later lanes, so an
+    // allow entry only THAT skill could have matched may now be reported
+    // ALLOW_UNUSED. That is a warning, and `runHasErrors` gates on `error` only,
+    // so it cannot fail a build on its own — and the run is already exiting 1 on
+    // the failure the operator actually needs to fix.
+    return { results, runIssues: allowUnusedIssues(allowLedger), skillsWithErrors, failures };
+}
 async function buildCommand(pathArg, options) {
     const { logger, cwd, startTime } = setupCommandContext(pathArg, options.debug);
     try {
@@ -303,47 +527,40 @@ async function buildCommand(pathArg, options) {
             performDryRun(skillsToBuild, duration, logger);
             process.exit(0);
         }
-        // Validate all skills before building
-        const validatedSpecs = [];
-        for (const skill of skillsToBuild) {
-            const packagingConfig = mergeSkillPackagingConfig(skillsConfig.defaults, skillsConfig.config?.[skill.name]);
-            const outputDir = safePath.resolve(cwd, 'dist', 'skills', skillNameToFsPath(skill.name));
-            logger.info(`\nBuilding skill: ${skill.name}`);
-            logger.info(`   Source: ${skill.sourcePath}`);
-            logger.info(`   Output: ${outputDir}`);
-            await validateSkillOrExit(skill.name, skill.sourcePath, packagingConfig, logger, cwd);
-            validatedSpecs.push({ skill, packagingConfig });
-        }
-        // Build all skills with a shared registry
-        const specs = validatedSpecs.map(({ skill, packagingConfig }) => ({
-            skillPath: skill.sourcePath,
-            options: packagingConfigToPackageOptions(packagingConfig, {
-                skillPath: skill.sourcePath,
-                outputPath: safePath.resolve(cwd, 'dist', 'skills', skillNameToFsPath(skill.name)),
-            }),
+        const buildSpecs = skillsToBuild.map((skill) => ({
+            skill,
+            packagingConfig: mergeSkillPackagingConfig(skillsConfig.defaults, skillsConfig.config?.[skill.name]),
         }));
-        const packageResults = await packageSkills(specs, cwd);
-        const results = [];
-        const skillsWithErrors = [];
-        for (const [i, spec] of validatedSpecs.entries()) {
-            const result = packageResults[i];
-            if (result) {
-                logger.info(`   Built ${result.files.dependencies.length + 1} files`);
-                logPostBuildIssues(result, logger);
-                if (result.hasErrors) {
-                    skillsWithErrors.push(spec.skill.name);
-                }
-                results.push({ name: spec.skill.name, result });
-            }
-        }
+        // Assembled ONCE, from the UNFILTERED discovery: `--skill x` narrows the build,
+        // not the set of files that count as some skill's declared test input.
+        const projectSkills = collectDeclaredEvalSuites(skillsConfig, discoveredSkills);
+        const { results, runIssues, skillsWithErrors, failures } = await runSkillBuild(buildSpecs, cwd, logger, projectSkills, options.verbose === true);
         const duration = Date.now() - startTime;
         // Output YAML results
-        outputBuildYaml(results, duration);
+        outputBuildYaml(results, failures, duration, runIssues, skillsWithErrors);
+        for (const line of formatRunIssueLines(runIssues)) {
+            logger.info(line);
+        }
+        if (failures.length > 0) {
+            logger.error(`\nBuild failed: ${failures.length} skill(s) could not be packaged at all`);
+            for (const { name, message } of failures) {
+                logger.error(`   - ${name}: ${message.split('\n')[0] ?? message}`);
+            }
+        }
         if (skillsWithErrors.length > 0) {
             logger.error(`\nBuild failed: ${skillsWithErrors.length} skill(s) emitted post-build validation errors`);
             for (const name of skillsWithErrors) {
                 logger.error(`   - ${name}`);
             }
+        }
+        // A run-level finding belongs to no skill, so the loop above cannot carry
+        // it. Only `error` severity gates: ALLOW_UNUSED ships as a `warning`, and a
+        // warning must never abort a build that produced its artifacts.
+        const runHasErrors = runIssues.some((i) => i.severity === 'error');
+        if (runHasErrors) {
+            logger.error(`\nBuild failed: run-level validation errors (project config, not any one skill)`);
+        }
+        if (skillsWithErrors.length > 0 || runHasErrors || failures.length > 0) {
             process.exit(1);
         }
         logger.info(`\nBuilt ${results.length} skill(s) successfully`);