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

package/dist/commands/skills/build.js

@@ -8,17 +8,19 @@
  */
 import { existsSync } from 'node:fs';
 import { mkdir, mkdtemp, rename, rm } from 'node:fs/promises';
-import { allowUnusedIssues, calculateValidationStatus, countBySeverity, createAllowUsageLedger, } from '@vibe-agent-toolkit/agent-schema';
-import { packageSkills, packagingConfigToPackageOptions, skillNameToFsPath, validateSkillForPackaging, } from '@vibe-agent-toolkit/agent-skills';
+import { conventionalSuiteProbe, indexPluginLocalSkills, packageSkills, packagingConfigToPackageOptions, skillNameToFsPath, validateSkillForPackaging, } from '@vibe-agent-toolkit/agent-skills';
+import { allowUnusedIssues, calculateValidationStatus, countBySeverity, createAllowUsageLedger, } from '@vibe-agent-toolkit/schema';
 import { safePath, toForwardSlash } from '@vibe-agent-toolkit/utils';
 import { Command } from 'commander';
 import * as yaml from 'yaml';
-import { handleCommandError } from '../../utils/command-error.js';
+import { reportCommandError } from '../../utils/command-error.js';
 import { loadConfig } from '../../utils/config-loader.js';
 import { collectPostBuildIssues, countCollapsedFindings, formatCollapsedFindingsHint, formatIssueLines, formatIssueSetHeading, formatPackagedFileCount, formatRunIssueLines, issuesToRenderAtVerbosity, sumSeverityCounts, } from '../../utils/issue-rendering.js';
 import { requireProjectRoot } from '../../utils/project-root-policy.js';
-import { collectDeclaredEvalSuites, mergeSkillPackagingConfig } from '../../utils/skill-packaging-config.js';
+import { withResourcePopulationSource } from '../../utils/resource-loader.js';
+import { collectDeclaredEvalSuites, mergeSkillPackagingConfig, publishScope } from '../../utils/skill-packaging-config.js';
 import { applyConfigVerdicts } from '../../utils/verdict-helpers.js';
+import { finishCommand } from '../phase-utils.js';
 import { filterSkillsByName, setupCommandContext, writeYamlHeader, } from './command-helpers.js';
 import { rejectUnscopablePath } from './scope-guard.js';
 import { discoverSkillsFromConfig } from './skill-discovery.js';
@@ -56,6 +58,16 @@ Description:
   (schema defaults -> config yaml defaults -> per-skill overrides),
   validates, and packages into dist/skills/<name>/.
 
+  publish: false (merged from skills.defaults and skills.config.<name>)
+  marks an IN-PLACE skill: validated at source by 'vat validate', never
+  bundled here, never expected by 'vat verify'. Such skills are set aside
+  with one info line and counted as skillsInPlace; --skill naming one is
+  an error (exit 1). A plugin-local skill (a git-tracked skill dir under a
+  plugin's skills/) ships with its plugin regardless of publish, so it is
+  never in place: under publish: false it is set aside on its own info line,
+  counted as skillsPluginOnly, and --skill naming it exits 1 pointing at the
+  claude phase that packages it.
+
 Config Structure (vibe-agent-toolkit.config.yaml):
   version: 1
   skills:
@@ -74,6 +86,8 @@ Config Structure (vibe-agent-toolkit.config.yaml):
             LINK_DROPPED_BY_DEPTH:
               - paths: ["docs/**"]
                 reason: depth drop is intentional for large reference docs
+      used-in-place:
+        publish: false
 
 Validation:
   Both pre-build and post-build checks use the unified validation framework.
@@ -120,6 +134,14 @@ Output:
                   emitted post-build validation errors. They are counted in
                   skillsBuilt, not skillsFailed, so read ALL of these before
                   concluding a run was clean: the exit code follows this one too.
+  skillsInPlace / skillsInPlaceNames:
+                  NOT a failure — skills whose merged config says publish: false,
+                  so this run set them aside unbuilt. Published so a build that
+                  bundles fewer skills than it discovered says so by count.
+  skillsPluginOnly / skillsPluginOnlyNames:
+                  NOT a failure — plugin-local publish: false skills, set aside
+                  here too but shipped with their plugin by the claude phase, so
+                  never counted in skillsInPlace. Both pairs are also in --dry-run.
   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:
@@ -289,7 +311,7 @@ function displayIgnoredErrors(validationResult, logger) {
  * publishes, rather than a flat "one error" stand-in.
  */
 async function validateSkillBeforeBuild(input) {
-    const { skillName, sourcePath, packagingConfig, logger, locationRoot, allowLedger, projectSkills, verbose } = input;
+    const { skillName, sourcePath, packagingConfig, logger, locationRoot, allowLedger, projectSkills, suiteProbe, populationSource, verbose } = input;
     logger.debug(`   Validating skill: ${skillName}`);
     // 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
@@ -298,7 +320,20 @@ async function validateSkillBeforeBuild(input) {
     //
     // 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 });
+    const validationResult = await validateSkillForPackaging(sourcePath, packagingConfig, 'source', {
+        allowLedger,
+        projectSkills,
+        // A build must not ship a shorter bundle: a directory the validator's own
+        // registry crawl cannot list refuses the run by name.
+        unreadable: 'refuse',
+        // Likewise the RUN's, and the same instance the packaging phase gets: this
+        // lane resolves test input for the subject AND every entry in
+        // `projectSkills`, so a per-call probe is S² over the loop.
+        suiteProbe,
+        // The RUN's source, so every skill in the loop shares one memo entry
+        // behind `crawlAndResolveRegistry` and the run pays one crawl, not N.
+        ...(populationSource !== undefined && { populationSource }),
+    });
     applyConfigVerdicts(validationResult, packagingConfig.targets, sourcePath, locationRoot);
     if (validationResult.status !== 'error') {
         if (validationResult.ignoredErrors.length > 0) {
@@ -320,7 +355,7 @@ async function validateSkillBeforeBuild(input) {
 /**
  * Output dry-run results
  */
-function outputDryRunYaml(skills, duration) {
+function outputDryRunYaml(skills, setAside, duration) {
     writeYamlHeader({
         status: 'success',
         dryRun: true,
@@ -330,6 +365,10 @@ function outputDryRunYaml(skills, duration) {
         // misreading. This field makes the absence explicit instead.
         validated: false,
         skillsFound: skills.length,
+        // The same partition the real build publishes: what a preview would NOT
+        // bundle is as much a part of the preview as what it would.
+        skillsInPlace: setAside.inPlace.length,
+        skillsPluginOnly: setAside.pluginOnly.length,
     });
     process.stdout.write(`skills:\n`);
     for (const skill of skills) {
@@ -337,21 +376,24 @@ function outputDryRunYaml(skills, duration) {
         process.stdout.write(`    source: ${skill.sourcePath}\n`);
         process.stdout.write(`    output: dist/skills/${skillNameToFsPath(skill.name)}\n`);
     }
+    process.stdout.write(yaml.stringify({ skillsInPlaceNames: [...setAside.inPlace], skillsPluginOnlyNames: [...setAside.pluginOnly] }, { indent: 2, lineWidth: 0 }));
     process.stdout.write(`duration: ${duration}ms\n`);
 }
 /**
  * Perform dry-run preview
  */
-function performDryRun(skillsToBuild, duration, logger) {
+function performDryRun(skillsToBuild, setAside, duration, logger) {
     logger.info(`Dry-run: Analyzing skill build...`);
     logger.info(`   Skills to build: ${skillsToBuild.length}`);
+    logger.info(`   In-place skills (publish: false, not bundled): ${setAside.inPlace.length}`);
+    logger.info(`   Plugin-only skills (publish: false, ship with their plugin): ${setAside.pluginOnly.length}`);
     logger.info(`\nSkills:`);
     for (const skill of skillsToBuild) {
         logger.info(`   ${skill.name}`);
         logger.info(`      Source: ${skill.sourcePath}`);
         logger.info(`      Output: dist/skills/${skillNameToFsPath(skill.name)}`);
     }
-    outputDryRunYaml(skillsToBuild, duration);
+    outputDryRunYaml(skillsToBuild, setAside, duration);
     logger.info(`\nDry-run complete (no files created)`);
     logger.info(`   Run without --dry-run to build the skills`);
 }
@@ -545,24 +587,38 @@ export function buildYamlSummary(run, duration) {
     };
 }
 /**
- * Output build results
+ * THE document this command publishes — the shape a consumer actually reads.
+ *
+ * NOT the same object as {@link buildYamlSummary}, and the difference is the
+ * whole reason this function exists. The summary carries `skillsWithErrors` as
+ * an ARRAY of names; the published document carries `skillsWithErrors` as a
+ * COUNT (in the header, beside the other tallies) and the names separately under
+ * `skillsWithErrorNames`. That projection used to live inside the renderer, so
+ * the only way to obtain the real document was to serialize it and parse it back
+ * — which is exactly what the parent process did, and exactly what stopped being
+ * true when phases stopped being child processes. Returning the summary instead
+ * would have flipped `skillsWithErrors` from a number to an array in `vat
+ * build`'s output, silently and with nothing to typecheck it against.
+ *
+ * `skillsInPlace` and `skillsPluginOnly` ride in the header beside `skillsBuilt`,
+ * with the names under `skillsInPlaceNames` / `skillsPluginOnlyNames`: a build that
+ * ships fewer skills than it discovered is the drop this command exists to prevent,
+ * so every skill a `publish: false` removed from `skillsBuilt` must be visible where
+ * a consumer reads the count — including a plugin-local one, which is not in place
+ * (it ships with its plugin) but is still not bundled here.
  */
-function outputBuildYaml(run, duration) {
+export function buildBuildDocument(run, setAside, duration) {
     const summary = buildYamlSummary(run, duration);
     const { status, skillsBuilt, skillsFailed, skillsFailedValidation, issueCounts, runIssueCounts, skills, skillsStaged, failedSkills, validationFailedSkills, outputCommitted, duration: durationText, } = summary;
-    // In the header, beside the other counts: these are the numbers the exit code
-    // actually follows, so a reader who stops at the header is not misled by it.
-    // `outputCommitted` rides up here too — a reader who sees exit 1 needs to know
-    // whether their dist/skills still exists before they do anything else.
-    writeYamlHeader({
+    return {
         status,
         skillsBuilt,
+        skillsInPlace: setAside.inPlace.length,
+        skillsPluginOnly: setAside.pluginOnly.length,
         skillsFailed,
         skillsFailedValidation,
         skillsWithErrors: summary.skillsWithErrors.length,
         outputCommitted,
-    });
-    process.stdout.write(yaml.stringify({
         issueCounts,
         runIssueCounts,
         // Published in the BODY, not the header: `writeYamlHeader` writes raw
@@ -580,8 +636,37 @@ function outputBuildYaml(run, duration) {
         failedSkills,
         validationFailedSkills,
         skillsWithErrorNames: summary.skillsWithErrors,
+        skillsInPlaceNames: [...setAside.inPlace],
+        skillsPluginOnlyNames: [...setAside.pluginOnly],
         runIssues: summary.runIssues,
-    }, { indent: 2, lineWidth: 0, aliasDuplicateObjects: false }));
+        duration: durationText,
+    };
+}
+/**
+ * Render {@link buildBuildDocument}'s document to stdout.
+ *
+ * Streamed in two pieces — a raw scalar header, then the body — rather than as
+ * one `yaml.stringify`, so the header lands before a body that can run to
+ * megabytes on a large project. The key ORDER here is the document's order; the
+ * split is presentation only and adds nothing the document does not carry.
+ */
+export function outputBuildYaml(document) {
+    const { status, skillsBuilt, skillsInPlace, skillsPluginOnly, skillsFailed, skillsFailedValidation, skillsWithErrors, outputCommitted, duration: durationText, ...body } = document;
+    // In the header, beside the other counts: these are the numbers the exit code
+    // actually follows, so a reader who stops at the header is not misled by it.
+    // `outputCommitted` rides up here too — a reader who sees exit 1 needs to know
+    // whether their dist/skills still exists before they do anything else.
+    writeYamlHeader({
+        status: status,
+        skillsBuilt: skillsBuilt,
+        skillsInPlace: skillsInPlace,
+        skillsPluginOnly: skillsPluginOnly,
+        skillsFailed: skillsFailed,
+        skillsFailedValidation: skillsFailedValidation,
+        skillsWithErrors: skillsWithErrors,
+        outputCommitted: outputCommitted,
+    });
+    process.stdout.write(yaml.stringify(body, { indent: 2, lineWidth: 0, aliasDuplicateObjects: false }));
     process.stdout.write(`duration: ${durationText}\n`);
 }
 /** How the human stream names the output tree. One spelling, one place. */
@@ -736,7 +821,6 @@ export function reanchorStagedResult(result, mapPath) {
 export async function beginStagedBuild(cwd, onlySkill) {
     const distDir = safePath.resolve(cwd, 'dist');
     const skillsDir = safePath.join(distDir, 'skills');
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- resolved from cwd
     await mkdir(distDir, { recursive: true });
     const root = toForwardSlash(await mkdtemp(safePath.join(distDir, '.vat-skills-')));
     // `--skill <name>` rebuilds ONE bundle, so the all-or-nothing guarantee is
@@ -749,9 +833,7 @@ export async function beginStagedBuild(cwd, onlySkill) {
     // without a dirname call.
     const promoteToParent = subPath === undefined ? distDir : skillsDir;
     const parked = `${root}.previous`;
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- resolved from cwd
     const hadPreviousOutput = existsSync(promoteTo);
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- resolved from cwd
     if (hadPreviousOutput)
         await rename(promoteTo, parked);
     // Flipped the instant this run's bundles reach `promoteTo`, so a later failure
@@ -774,11 +856,8 @@ export async function beginStagedBuild(cwd, onlySkill) {
             // staging root always exists, so a run that built nothing promotes an
             // empty dist/skills — an accurate statement of "this build produced no
             // bundles", where the old delete-up-front flow left the path absent.)
-            // eslint-disable-next-line security/detect-non-literal-fs-filename -- resolved from cwd
             if (existsSync(promoteFrom)) {
-                // eslint-disable-next-line security/detect-non-literal-fs-filename -- resolved from cwd
                 await mkdir(promoteToParent, { recursive: true });
-                // eslint-disable-next-line security/detect-non-literal-fs-filename -- resolved from cwd
                 await rename(promoteFrom, promoteTo);
             }
             promoted = true;
@@ -791,36 +870,30 @@ export async function beginStagedBuild(cwd, onlySkill) {
             await rm(root, { recursive: true, force: true });
             if (!hadPreviousOutput)
                 return;
-            // eslint-disable-next-line security/detect-non-literal-fs-filename -- resolved from cwd
             await mkdir(promoteToParent, { recursive: true });
-            // eslint-disable-next-line security/detect-non-literal-fs-filename -- resolved from cwd
             await rename(parked, promoteTo);
         },
         recover: async () => {
             const residue = [];
             let restoredPrevious = false;
-            // eslint-disable-next-line security/detect-non-literal-fs-filename -- resolved from cwd
             const targetFree = !existsSync(promoteTo);
-            // eslint-disable-next-line security/detect-non-literal-fs-filename -- resolved from cwd
             if (hadPreviousOutput && existsSync(parked)) {
                 if (targetFree) {
                     try {
-                        // eslint-disable-next-line security/detect-non-literal-fs-filename -- resolved from cwd
                         await mkdir(promoteToParent, { recursive: true });
-                        // eslint-disable-next-line security/detect-non-literal-fs-filename -- resolved from cwd
                         await rename(parked, promoteTo);
                         restoredPrevious = true;
                     }
-                    catch {
+                    catch (error) {
                         // The repair is best-effort by construction: it runs because the
                         // filesystem already refused something. A throw here must not replace
-                        // the original diagnosis, so the parked path is reported as residue
-                        // and the caller still names the real cause.
-                        residue.push(parked);
+                        // the original diagnosis, so the parked path is reported as residue —
+                        // with this refusal beside it — and the caller still names the real cause.
+                        residue.push({ path: parked, reason: `restore failed: ${describeThrown(error)}` });
                     }
                 }
                 else {
-                    residue.push(parked);
+                    residue.push({ path: parked, reason: 'the promotion target is already occupied' });
                 }
             }
             // This run's own staging root is always safe to drop: it holds output this
@@ -829,8 +902,8 @@ export async function beginStagedBuild(cwd, onlySkill) {
             try {
                 await rm(root, { recursive: true, force: true });
             }
-            catch {
-                residue.push(root);
+            catch (error) {
+                residue.push({ path: root, reason: `removal failed: ${describeThrown(error)}` });
             }
             return { restoredPrevious, residue };
         },
@@ -883,7 +956,7 @@ export async function settleStaging(staging, runFailed, logger) {
  * whole remedy, and the path is unreconstructable without being told.
  */
 function describePromotionFailure(staging, error, recovery) {
-    const cause = error instanceof Error ? error.message : String(error);
+    const cause = describeThrown(error);
     const lines = [`Build output promotion failed: ${cause}`];
     if (staging.promoted()) {
         lines.push(`   ${staging.promoteLabel} DOES hold this run's output — the failure was in the cleanup that follows.`);
@@ -897,11 +970,94 @@ function describePromotionFailure(staging, error, recovery) {
     else {
         lines.push(`   ${staging.promoteLabel} was never written, and there was no previous output to lose.`);
     }
-    for (const path of recovery.residue) {
-        lines.push(`   Left on disk (this run could not remove it): ${path}`);
+    for (const { path, reason } of recovery.residue) {
+        lines.push(`   Left on disk (this run could not remove it): ${path} — ${reason}`);
     }
     return lines.join('\n');
 }
+/** The message of whatever was thrown, for a report line. */
+function describeThrown(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Merge every skill's config and split the pool skills from the ones this run sets aside.
+ *
+ * `buildSpecs` is what this run bundles. Of the `publish: false` skills (see
+ * `publishScope`), `inPlace` is every one used from the repo — validated at
+ * source by `vat validate`, never bundled, never expected by `vat verify` — and
+ * `pluginOnly` every PLUGIN-LOCAL one (its source dir is a location in `pluginLocal`,
+ * from `indexPluginLocalSkills`): not bundled here either, but shipped with its
+ * plugin, so reporting it as in-place would be false. Every list keeps discovery
+ * order, so the human and machine reports list them as the globs found them.
+ */
+export function partitionInPlaceSkills(skills, skillsConfig, pluginLocal) {
+    const lists = { pool: [], 'in-place': [], 'plugin-only': [] };
+    for (const skill of skills) {
+        const packagingConfig = mergeSkillPackagingConfig(skillsConfig.defaults, skillsConfig.config?.[skill.name]);
+        lists[publishScope(skill, packagingConfig, pluginLocal)].push({ skill, packagingConfig });
+    }
+    return { buildSpecs: lists.pool, inPlace: lists['in-place'], pluginOnly: lists['plugin-only'] };
+}
+/** How many set-aside names one info line spells out before "… and N more". */
+const SET_ASIDE_NAMES_SHOWN = 10;
+/**
+ * ONE info line for one population this run set aside, naming the count and (up
+ * to {@link SET_ASIDE_NAMES_SHOWN} of) the names. Nothing when there are none: a
+ * "0 in-place" line on every build is noise that trains readers to skip the line
+ * that matters.
+ */
+function logSetAsideSkills(setAside, label, logger) {
+    if (setAside.length === 0)
+        return;
+    const names = setAside.map((spec) => spec.skill.name);
+    const shown = names.slice(0, SET_ASIDE_NAMES_SHOWN).join(', ');
+    const more = names.length > SET_ASIDE_NAMES_SHOWN ? ` … and ${names.length - SET_ASIDE_NAMES_SHOWN} more` : '';
+    logger.info(`Skipping ${setAside.length} ${label}: ${shown}${more}`);
+}
+/** The info line for the in-place skills — see {@link logSetAsideSkills}. */
+export function logInPlaceSkills(inPlace, logger) {
+    logSetAsideSkills(inPlace, 'in-place skill(s) (publish: false — validated at source, never bundled)', logger);
+}
+/**
+ * The info line for the plugin-local `publish: false` skills — deliberately NOT the
+ * in-place line: they are left out of `dist/skills` but ship with their plugin.
+ */
+function logPluginOnlySkills(pluginOnly, logger) {
+    logSetAsideSkills(pluginOnly, 'plugin-local skill(s) from dist/skills (publish: false — each ships with its plugin via the claude phase)', logger);
+}
+/**
+ * `--skill x` on an in-place skill is a contradiction, not a silent skip: exit 1
+ * naming the key that makes it one. (The one-skill filter leaves only that skill.)
+ */
+export function inPlaceSkillRefusal(skill, inPlace) {
+    if (skill === undefined || inPlace.length === 0)
+        return undefined;
+    return new Error(`Skill "${skill}" is an in-place skill (skills.config.${skill}.publish is false, `
+        + 'directly or via skills.defaults.publish): vat build never bundles it, so there is no bundle to build. '
+        + 'Set publish: true to distribute it through dist/skills, or drop --skill.');
+}
+/**
+ * `--skill x` on a plugin-local `publish: false` skill: exit 1 like the in-place
+ * refusal, but saying what is true of it — it is not a pool skill, and it ships
+ * with its plugin, packaged by the claude phase.
+ */
+function pluginOnlySkillRefusal(skill, pluginOnly) {
+    if (skill === undefined || pluginOnly.length === 0)
+        return undefined;
+    return new Error(`Skill "${skill}" is a plugin-local skill (under a plugin's skills/ directory) with publish: false `
+        + `(skills.config.${skill}.publish, directly or via skills.defaults.publish): it ships with its plugin, `
+        + 'packaged by the claude phase, and is never bundled into dist/skills, so this command has nothing to build for it. '
+        + "Run 'vat build --only claude' to package its plugin, set publish: true to also distribute it through dist/skills, "
+        + 'or drop --skill.');
+}
+/** The human success line, naming each set-aside population only when it is non-empty. */
+export function formatBuiltSuccessLine(built, setAside) {
+    const tails = [
+        ...(setAside.inPlace === 0 ? [] : [`${setAside.inPlace} in-place skill(s) not bundled`]),
+        ...(setAside.pluginOnly === 0 ? [] : [`${setAside.pluginOnly} plugin-only skill(s) shipped with their plugin`]),
+    ];
+    return `\nBuilt ${built} skill(s) successfully` + (tails.length === 0 ? '' : ` (${tails.join(', ')})`);
+}
 /**
  * Validate, package, and drain — the whole span of ONE `vat build` invocation.
  *
@@ -933,42 +1089,82 @@ export async function runSkillBuild(input) {
     // detail no reader should have to decode.
     const buildable = [];
     const validationFailures = [];
-    for (const spec of specs) {
-        const { skill, packagingConfig } = spec;
-        logger.info(`\nBuilding skill: ${skill.name}`);
-        logger.info(`   Source: ${skill.sourcePath}`);
-        logger.info(`   Output: ${finalOutputPath(cwd, skill.name)}`);
-        const failure = await validateSkillBeforeBuild({
-            skillName: skill.name,
-            sourcePath: skill.sourcePath,
-            packagingConfig,
-            logger,
-            locationRoot: cwd,
-            allowLedger,
-            projectSkills,
-            verbose,
-        });
-        if (failure) {
-            validationFailures.push(failure);
-            continue;
-        }
-        buildable.push(spec);
-    }
-    // Build the skills that qualified, with a shared registry.
+    // ONE bracket over the WHOLE run — both validation lanes and the packaging —
+    // rather than over `packageSkills` alone.
+    //
+    // Two properties depend on it, and neither is cosmetic. First, every
+    // enumeration of the SOURCE tree this run performs is then on the lane the
+    // process selected: the pre-build check builds a private registry through
+    // `crawlAndResolveRegistry`, and outside the bracket it had no source to reach,
+    // so a projection-lane build still did one full walk. (Each skill's POST-build
+    // check is deliberately NOT on the lane — `runPostBuildValidation` passes no
+    // source, because it validates the built output rather than the source tree.
+    // See its docstring in `skill-packager.ts`.) Second, the memo behind that crawl
+    // is keyed on the source's IDENTITY, so one closure for the run means one crawl
+    // for the run; a bracket per phase would hand out two closures and buy a second
+    // crawl to save the first.
     //
-    // `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 = buildable.map(({ skill, packagingConfig }) => ({
-        skillPath: skill.sourcePath,
-        options: packagingConfigToPackageOptions(packagingConfig, {
+    // `populationSource` is `undefined` when the walk stays selected, and every
+    // consumer below treats that as "keep the incumbent" — the default path is
+    // structurally unchanged.
+    // Run-scoped for the same reason `projectSkills` is, and it is the more expensive
+    // half: resolving a skill's test-input dirs probes the filesystem for a conventional
+    // eval suite under the subject AND under every entry of `projectSkills`, so a probe
+    // rebuilt per skill costs O(S) per skill and O(S²) per run. Measured on a 103-skill
+    // adopter, in the sibling `vat resources validate` lane that shares this helper:
+    // 10,815 `existsSync` calls over 103 distinct paths, half of that command's entire
+    // filesystem traffic. This lane has the same shape.
+    //
+    // NOT module-scoped: the answer is a filesystem snapshot, so a cache outliving the
+    // run would keep answering for a tree that has since changed.
+    const suiteProbe = conventionalSuiteProbe();
+    const outcomes = await withResourcePopulationSource({ root: cwd }, async (populationSource) => {
+        for (const spec of specs) {
+            const { skill, packagingConfig } = spec;
+            logger.info(`\nBuilding skill: ${skill.name}`);
+            logger.info(`   Source: ${skill.sourcePath}`);
+            logger.info(`   Output: ${finalOutputPath(cwd, skill.name)}`);
+            const failure = await validateSkillBeforeBuild({
+                skillName: skill.name,
+                sourcePath: skill.sourcePath,
+                packagingConfig,
+                logger,
+                locationRoot: cwd,
+                allowLedger,
+                projectSkills,
+                suiteProbe,
+                populationSource,
+                verbose,
+            });
+            if (failure) {
+                validationFailures.push(failure);
+                continue;
+            }
+            buildable.push(spec);
+        }
+        // Build the skills that qualified, 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 = buildable.map(({ skill, packagingConfig }) => ({
             skillPath: skill.sourcePath,
-            // Into staging, not dist/skills: see `beginStagedBuild`.
-            outputPath: safePath.join(staging.root, skillNameToFsPath(skill.name)),
-        }, projectSkills),
-    }));
-    const outcomes = await packageSkills(buildSpecs, cwd, allowLedger);
+            options: packagingConfigToPackageOptions(packagingConfig, {
+                skillPath: skill.sourcePath,
+                // Into staging, not dist/skills: see `beginStagedBuild`.
+                outputPath: safePath.join(staging.root, skillNameToFsPath(skill.name)),
+            }, projectSkills, suiteProbe),
+        }));
+        // `packageSkills` builds THE registry for the run, so this is the only seam
+        // that can put `vat skills build` — and therefore `vat build`'s packaging
+        // phase — on the lane. The registry's markdown-only `include` is re-applied
+        // to whatever the source offers, so what gets packaged is unchanged; only how
+        // the file list was obtained differs.
+        return packageSkills(buildSpecs, cwd, allowLedger, {
+            ...(populationSource !== undefined && { populationSource }),
+        });
+    });
     const results = [];
     const skillsWithErrors = [];
     const failures = [];
@@ -1077,7 +1273,15 @@ function logRunFailures(run, logger) {
         logger.error(`\nBuild failed: run-level validation errors (project config, not any one skill)`);
     }
 }
-async function buildCommand(pathArg, options) {
+/**
+ * Build every configured skill and hand back the document and exit code,
+ * printing the document nowhere.
+ *
+ * The phase entry point for `vat build`, whose `skills` phase is this command.
+ * The three early returns publish no document — an unconfigured run and a dry
+ * run both print their own thing and stop, exactly as the child process did.
+ */
+export async function runSkillsBuildPhase(pathArg, options) {
     const { logger, cwd, startTime } = setupCommandContext(pathArg, options.debug);
     try {
         // Spec §7: `vat skills build` requires a projectRoot — fails fast at the
@@ -1089,18 +1293,36 @@ async function buildCommand(pathArg, options) {
         const config = loadConfig(cwd);
         if (!config?.skills) {
             logger.info('No skills configuration found — nothing to build');
-            process.exit(0);
+            return { document: undefined, exitCode: 0 };
         }
         const skillsConfig = config.skills;
         // Discover SKILL.md files from config globs (relative to cwd where config lives)
         logger.info(`Discovering skills from config...`);
-        const discoveredSkills = await discoverSkillsFromConfig(skillsConfig, cwd);
+        // `'refuse'`: a build that silently ships fewer skills is the drop this
+        // command exists to prevent. The throw lands in the catch below →
+        // `reportCommandError`, exit 2.
+        const discoveredSkills = await discoverSkillsFromConfig(skillsConfig, cwd, 'refuse');
         if (discoveredSkills.length === 0) {
             throw new Error(`No SKILL.md files found matching include patterns: ${skillsConfig.include.join(', ')}`);
         }
-        // Filter by skill name if specified
-        const skillsToBuild = filterSkillsByName(discoveredSkills, options.skill);
-        logger.info(`Found ${skillsToBuild.length} skill(s) to build`);
+        // Filter by skill name if specified, then set the in-place skills aside.
+        // `publish: false` names a skill the pool never carries (see
+        // `isSkillPublished`), so the partition happens BEFORE the count is announced:
+        // "Found N skill(s) to build" must be the number this run will bundle.
+        // Plugin-local = a skill dir the plugin build packages (the same index the
+        // consistency check and `vat verify` ask): such a skill is never in place.
+        const { buildSpecs, inPlace, pluginOnly } = partitionInPlaceSkills(filterSkillsByName(discoveredSkills, options.skill), skillsConfig, indexPluginLocalSkills(config, cwd));
+        const refusal = inPlaceSkillRefusal(options.skill, inPlace) ?? pluginOnlySkillRefusal(options.skill, pluginOnly);
+        if (refusal !== undefined) {
+            return { document: reportCommandError(refusal, logger, startTime, 'SkillsBuild'), exitCode: 1, failed: true };
+        }
+        logInPlaceSkills(inPlace, logger);
+        logPluginOnlySkills(pluginOnly, logger);
+        logger.info(`Found ${buildSpecs.length} skill(s) to build`);
+        const setAside = {
+            inPlace: inPlace.map((spec) => spec.skill.name),
+            pluginOnly: pluginOnly.map((spec) => spec.skill.name),
+        };
         // Handle dry-run mode. Nothing has touched `dist/` at this point — the
         // staging directory and the swap both live inside `runSkillBuild`, which a
         // dry run never reaches, so "preview without creating files" is now true of
@@ -1109,13 +1331,9 @@ async function buildCommand(pathArg, options) {
         // guard three lines up to stay honest.)
         if (options.dryRun) {
             const duration = Date.now() - startTime;
-            performDryRun(skillsToBuild, duration, logger);
-            process.exit(0);
+            performDryRun(buildSpecs.map((spec) => spec.skill), setAside, duration, logger);
+            return { document: undefined, exitCode: 0 };
         }
-        const buildSpecs = skillsToBuild.map((skill) => ({
-            skill,
-            packagingConfig: mergeSkillPackagingConfig(skillsConfig.defaults, skillsConfig.config?.[skill.name]),
-        }));
         // 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);
@@ -1128,8 +1346,7 @@ async function buildCommand(pathArg, options) {
             verbose: options.verbose === true,
         });
         const duration = Date.now() - startTime;
-        // Output YAML results
-        outputBuildYaml(run, duration);
+        const document = buildBuildDocument(run, setAside, duration);
         for (const line of formatRunIssueLines(run.runIssues)) {
             logger.info(line);
         }
@@ -1137,24 +1354,35 @@ async function buildCommand(pathArg, options) {
         // A promotion failure is a SYSTEM error (2), not a validation one (1): the
         // build's verdict on the skills is not what went wrong, and a CI script has
         // to be able to tell "your skills are broken" from "the filesystem refused
-        // and dist/skills is in a state someone must look at". Reported AFTER the
-        // document is written, which is the whole reason it rides on the run rather
-        // than being thrown from inside it.
+        // and dist/skills is in a state someone must look at". The document is
+        // returned WITH the failing code rather than suppressed, which is the whole
+        // reason the error rides on the run rather than being thrown from inside it.
         if (run.promotionError !== undefined) {
             logger.error(`\n${run.promotionError}`);
-            process.exit(2);
+            return { document, exitCode: 2 };
         }
         // Gated on the SAME fact that decided whether the swap happened, not on a
         // second copy of the predicate: the exit code and `outputCommitted` can then
         // never disagree about whether this run succeeded.
         if (!run.outputCommitted) {
-            process.exit(1);
+            return { document, exitCode: 1 };
         }
-        logger.info(`\nBuilt ${run.results.length} skill(s) successfully`);
-        process.exit(0);
+        logger.info(formatBuiltSuccessLine(run.results.length, { inPlace: inPlace.length, pluginOnly: pluginOnly.length }));
+        return { document, exitCode: 0 };
     }
     catch (error) {
-        handleCommandError(error, logger, startTime, 'SkillsBuild');
+        return {
+            document: reportCommandError(error, logger, startTime, 'SkillsBuild'),
+            exitCode: 2,
+            failed: true,
+        };
     }
 }
+async function buildCommand(pathArg, options) {
+    // `undefined`: this command offers no `--format`, so its failure envelope is
+    // YAML like its report.
+    finishCommand(await runSkillsBuildPhase(pathArg, options), (document) => {
+        outputBuildYaml(document);
+    }, undefined);
+}
 //# sourceMappingURL=build.js.map