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

package/dist/commands/verify.js

@@ -9,15 +9,15 @@
  *   5. packaged-content  (in-process; built bundles carry nothing that must not ship)
  *   6. consistency check  (in-process; skill distribution integrity — package.json, plugin assignment)
  *
- * 1–3 are subprocess phases chosen by {@link selectVerifyPhases}; 4–6 run here and
- * are chosen by `selectInProcessVerifyPhases`. Both sets are config-gated, and both
- * are announced on startup.
+ * 1–3 delegate to a whole `vat` command and nest that command's own report under
+ * `report`; they are chosen by {@link selectVerifyPhases}. 4–6 exist only here and
+ * are chosen by `selectInProcessVerifyPhases`. Every phase runs in this process.
+ * Both sets are config-gated, and both are announced on startup.
  */
-import { existsSync } from 'node:fs';
-import { basename } from 'node:path';
-import { calculateValidationStatus, countBySeverity, } from '@vibe-agent-toolkit/agent-schema';
-import { computeTreeCopiedSkillLocations, detectPackagedAgentInstructionFiles, explicitFilesConfigDests, } from '@vibe-agent-toolkit/agent-skills';
-import { safePath } from '@vibe-agent-toolkit/utils';
+import { existsSync, statSync } from 'node:fs';
+import { detectPackagedAgentInstructionFiles, explicitFilesConfigDests, indexPluginLocalSkills, } from '@vibe-agent-toolkit/agent-skills';
+import { calculateValidationStatus, countBySeverity, } from '@vibe-agent-toolkit/schema';
+import { isPathAbsentError, safePath, toForwardSlash } from '@vibe-agent-toolkit/utils';
 import { Command } from 'commander';
 import { handleCommandError } from '../utils/command-error.js';
 import { loadConfig } from '../utils/config-loader.js';
@@ -25,11 +25,15 @@ import { formatIssueLines } from '../utils/issue-rendering.js';
 import { resolveIssueSeverity } from '../utils/issue-severity.js';
 import { writeYamlOutput } from '../utils/output.js';
 import { requireProjectRoot } from '../utils/project-root-policy.js';
-import { mergeSkillPackagingConfig } from '../utils/skill-packaging-config.js';
+import { nothingCheckedFinding, runIntegrityFinding } from '../utils/run-integrity.js';
+import { isSkillPublished, mergeSkillPackagingConfig, pluginLocalSkillConfigEntry, publishScope } from '../utils/skill-packaging-config.js';
+import { runMarketplaceValidatePhase } from './claude/marketplace/validate.js';
 import { runConsistencyChecks, } from './consistency-check.js';
 import { addRetiredOnlyOption, aggregatePhaseStatus, applyPhaseSelection, createPhaseContext, decidePhaseSelection, exitCodeForPhases, rejectRetiredOnly, runPhase, } from './phase-utils.js';
 import { rejectPositionalArguments } from './positional-args.js';
-import { discoverSkillsFromConfig } from './skills/skill-discovery.js';
+import { runResourcesValidatePhase } from './resources/validate.js';
+import { discoverSkillsFromConfig, readPluginLocalSkillNames } from './skills/skill-discovery.js';
+import { runSkillsValidatePhase } from './skills/validate.js';
 /**
  * Measured full-run duration on the 90-skill / 1,041-document adopter, cited by
  * the retired-`--only` message: resources 12.5s + skills 15.6s + marketplace
@@ -58,12 +62,12 @@ Description:
   about as long as its slowest two phases, so a CI gate cannot lose coverage
   by naming a phase whose config key was renamed out from under it.
 
-  Phases (subprocess):
+  Phases (delegated to a whole vat command):
     resources    → link integrity, collection frontmatter schemas (when 'resources:' configured)
     skills       → SKILL.md frontmatter and packaging validation (when 'skills:' configured)
     marketplace  → strict marketplace validation (when 'claude.marketplaces:' configured)
 
-  Phases (in-process, run after the above, when 'skills:' is configured):
+  Phases (verify's own, run after the above, when 'skills:' is configured):
     files-config-dests → every 'files:' dest exists in the built output. Appears
                          in the document only when a dest is missing.
     packaged-content   → built skill bundles carry no repo-internal agent-instruction
@@ -81,32 +85,48 @@ Description:
 
 Output:
   ONE YAML document → stdout
-    per phase: status (success | warning | error | system-error). A subprocess
+    per phase: status (success | warning | error | system-error). A delegated
     phase's own report is captured and nested under 'report', so the whole run
     is a single parseable document (a phase's stdout is never streamed
-    through). A phase's status comes from the child's REPORTED status, not
-    from its exit code — an exit code cannot express 'warning'. In-process
-    phases also publish issueCounts {errors, warnings, info}; 'consistency' and
+    through). A phase's status comes from its own REPORTED status, not from its
+    exit code — an exit code cannot express 'warning'. Verify's own phases also
+    publish issueCounts {errors, warnings, info}; 'consistency' and
     'packaged-content' carry their findings into the document too, while
     'files-config-dests' publishes counts only and lists the missing dests on
-    stderr.
+    stderr. 'packaged-content' also publishes bundlesInspected — the built
+    bundles it crawled — beside bundlesExpected (the bundles 'vat build'
+    produces for the skills this run discovered) and bundlesMissing (expected
+    bundles absent from dist/, by path). Zero inspected, or any missing, is
+    refused as RESOURCE_CHECK_BROKEN at error (exit 1) rather than reported as
+    a pass: a run that found none of the build (dist/ not built, or a
+    skills.include glob that matched nothing) or only part of it (a bundle
+    deleted, a skill added since the last build) is not a verdict on what ships.
+    A skill whose merged config says publish: false is IN-PLACE — never
+    bundled by 'vat build', so no pool bundle is expected for it (a stale one
+    in dist/skills is still inspected); bundlesInPlace counts them, and a run
+    whose every discovered skill is in place passes with nothing to inspect. A
+    plugin-local skill (a git-tracked skill dir under a plugin's skills/) is
+    never in place: it is expected in its plugin tree whatever publish says,
+    and never counted in bundlesInPlace. Declare
+    skills.defaults.publish: false for a project that builds with --only claude
+    and uses its other skills from the repo.
   Progress and validation errors → stderr (streamed live)
 
-  By default each subprocess phase reports a per-asset summary plus the assets
-  that have findings. '--verbose' is forwarded to every subprocess phase, which
+  By default each delegated phase reports a per-asset summary plus the assets
+  that have findings. '--verbose' is forwarded to every delegated phase, which
   then also lists the assets it inspected and found nothing to report.
 
 Exit Codes:
   0 - All phases passed (a warning does not fail the run — read status/issueCounts)
   1 - Validation errors found
   2 - System error (this command's own, or propagated from a phase that could
-      not run: exited 2, was killed by a signal, was never spawned, or wrote
-      output that could not be parsed), or a usage error such as passing a path
+      not run: it exited 2, or reported 'system-error' for itself), or a usage
+      error such as passing a path
 
 Arguments:
   None. Scope comes from vibe-agent-toolkit.config.yaml, never from the command
   line — a path argument is rejected (exit 2) rather than discarded. To inspect
-  ONE skill or bundle by path, use 'vat audit <path>'.
+  ONE skill or bundle by path, use 'vat skill review <path>'.
 
 Requirements:
   projectRoot: required (errors if no vibe-agent-toolkit.config.yaml or .git/ ancestor)
@@ -131,11 +151,34 @@ function filesOf(entry) {
     return entry.packaging.files ?? [];
 }
 /**
- * Register a check for (skillName, outputDir, packaging) in the dedup map.
+ * Whether `dir` is a directory — `false` for a file and for nothing. Both are
+ * "no bundle here": a bundle is a tree, and a regular FILE sitting where one
+ * should be passed `existsSync`, was counted as built, and the packaged-content
+ * crawl then threw `Base path is not a directory: /abs/…` out of the whole
+ * command — exit 2, no document, an absolute path on stderr — where the
+ * missing-bundle lane names it at exit 1.
+ *
+ * A path the process cannot stat is NOT "no bundle here" and throws: reading a
+ * refused `dist/skills/x` as missing would name it under `missing` with a
+ * remedy ("run vat build") that cannot help.
+ */
+function isDirectory(dir) {
+    try {
+        return statSync(dir).isDirectory();
+    }
+    catch (error) {
+        if (isPathAbsentError(error))
+            return false;
+        throw error;
+    }
+}
+/**
+ * Register a (skillName, outputDir, packaging) candidate.
  *
- * Skips silently if:
- *   - outputDir does not exist on disk (not a candidate)
- *   - the key was already added (dedup guard)
+ * A candidate whose output dir IS A DIRECTORY lands in `built` (deduplicated by
+ * key). An `expected` candidate is counted whether or not it exists, and one
+ * that is not a directory is named in `missing` — that absence is the finding,
+ * not a skip (see {@link isDirectory} for why "exists" is not enough).
  *
  * An EMPTY `files:` block is registered, not skipped: {@link checkFilesConfigDests}
  * has nothing to verify for such a skill and filters it out itself, but
@@ -143,27 +186,33 @@ function filesOf(entry) {
  * with no `files:` block is exactly the one whose agent-instruction file arrived by
  * some other route, and dropping it here would make the crawl blind to it.
  */
-function tryAddCheckEntry(checks, skillName, outputDir, packaging) {
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- outputDir is resolved from config, not user input
-    if (!existsSync(outputDir))
+function addCheckCandidate(outputs, seen, cwd, candidate, expected) {
+    const key = `${candidate.skillName}\0${candidate.outputDir}`;
+    if (seen.has(key))
         return;
-    const key = `${skillName}\0${outputDir}`;
-    if (!checks.has(key)) {
-        checks.set(key, { skillName, outputDir, packaging });
-    }
+    seen.add(key);
+    const exists = isDirectory(candidate.outputDir);
+    if (exists)
+        outputs.built.push(candidate);
+    if (!expected)
+        return;
+    outputs.expected += 1;
+    if (!exists)
+        outputs.missing.push(toForwardSlash(safePath.relative(cwd, candidate.outputDir)));
 }
 /**
- * Every built skill bundle this project's config accounts for that EXISTS on disk,
- * with the `files:` entries that govern it.
+ * Every built skill bundle this project's config accounts for, with the `files:`
+ * entries that govern it — those that EXIST on disk, and the coverage of those
+ * the build should have produced (see {@link BuiltSkillOutputs}).
  *
  * ONE enumeration of "where did `vat build` write this skill", shared by every
  * in-process verify phase, in the two locations the build actually uses:
  *   - Pool skills: `dist/skills/<fsName>/`
  *   - Tree-copy skills: `dist/.claude/plugins/.../skills/<name>/`
  *
- * Returns `[]` (never throws) for an unreadable config: `vat verify`'s subprocess
- * phases report the real config error, and an in-process phase must not race them
- * with a second, worse diagnosis.
+ * Returns an empty enumeration (never throws) for an unreadable config: `vat
+ * verify`'s delegated phases report the real config error, and one of verify's
+ * own phases must not race them with a second, worse diagnosis.
  *
  * The pool arm enumerates the skills the run DISCOVERED, unioned with the keys of
  * `skills.config`. It used to be the config keys alone, which made both in-process
@@ -185,6 +234,11 @@ function tryAddCheckEntry(checks, skillName, outputDir, packaging) {
  * crawls the whole project, `vat verify` already needs the same list for its
  * consistency phase, and an optional parameter here would let a call site quietly
  * re-crawl (or, worse, skip discovery and reinstate the blindness above).
+ * `pluginLocal` is required for the same reason: listing plugin-local skills crawls
+ * every plugin, and `vat verify` builds that index ONCE for all three in-process phases.
+ * `pluginLocalNames` — every location's declared name, read once per run by
+ * `readPluginLocalSkillNames` — is required too: without it a plugin-local skill's config
+ * would be looked up by something other than the name the plugin build packaged it under.
  *
  * The merge goes through {@link mergeSkillPackagingConfig} — the ONE helper every
  * lane uses — so `vat verify` and `vat build` cannot disagree about a skill's
@@ -192,39 +246,55 @@ function tryAddCheckEntry(checks, skillName, outputDir, packaging) {
  * unread is what made `severity.PACKAGED_AGENT_INSTRUCTION_FILE: ignore` a no-op in
  * this command.
  */
-function collectBuiltSkillOutputs(cwd, discovered) {
-    try {
-        const config = loadConfig(cwd);
-        if (!config)
-            return [];
-        const skillsConfig = config.skills;
-        const defaults = skillsConfig?.defaults;
-        // Dedup map: key = `skillName\0outputDir` → check entry
-        const checks = new Map();
-        // --- Pool skills: candidate dir is dist/skills/<fsName> ---
-        const poolNames = new Set([
-            ...discovered.map((skill) => skill.name),
-            ...Object.keys(skillsConfig?.config ?? {}),
-        ]);
-        for (const skillName of poolNames) {
-            const perSkill = skillsConfig?.config?.[skillName];
-            const outputDir = safePath.resolve(cwd, 'dist', 'skills', skillNameToFsPath(skillName));
-            tryAddCheckEntry(checks, skillName, outputDir, mergeSkillPackagingConfig(defaults, perSkill));
-        }
-        // --- Tree-copy skills: candidate dirs are plugin output skill dirs ---
-        for (const loc of computeTreeCopiedSkillLocations(config, cwd)) {
-            // Per-skill config is keyed by the skill's declared NAME. `skillDirPath` is a
-            // path (`group/nested-skill` for a nested skill), so try its trailing segment
-            // too — the spelling that matches for every skill whose dir is named after it.
-            const dirLeaf = basename(loc.skillDirPath);
-            const perSkill = (skillsConfig?.config?.[loc.skillDirPath] ?? skillsConfig?.config?.[dirLeaf]);
-            tryAddCheckEntry(checks, loc.skillDirPath, loc.skillOutputDir, mergeSkillPackagingConfig(defaults, perSkill));
-        }
-        return [...checks.values()];
+function collectBuiltSkillOutputs(cwd, discovered, pluginLocal, pluginLocalNames) {
+    const outputs = { built: [], expected: 0, inPlace: 0, missing: [] };
+    // No `try`, deliberately. The config was already loaded by the command (see
+    // `loadConfigTolerant`) and the in-process phases run only when it loaded, so
+    // `loadConfig` here answers from cache. The `catch { return outputs }` that
+    // used to wrap this whole body could only ever absorb a DEFECT — and it
+    // absorbed it into an empty candidate list, which every phase below then
+    // verified against: zero bundles, zero findings, exit 0.
+    const config = loadConfig(cwd);
+    if (!config)
+        return outputs;
+    const skillsConfig = config.skills;
+    const defaults = skillsConfig?.defaults;
+    // Dedup guard: key = `skillName\0outputDir`
+    const seen = new Set();
+    const packagingOf = (skillName) => mergeSkillPackagingConfig(defaults, skillsConfig?.config?.[skillName]);
+    // A plugin-local skill is never in place, whatever `publish` says: its plugin copy
+    // is expected below. Counted per discovered SKILL, not per name — a repo-only skill
+    // may share its declared name with a plugin-local one.
+    outputs.inPlace = discovered.filter((skill) => publishScope(skill, packagingOf(skill.name), pluginLocal) === 'in-place').length;
+    // --- Pool skills: candidate dir is dist/skills/<fsName> ---
+    // Expected only when discovered AND published (see BuiltSkillOutputs.expected).
+    // An in-place skill's stale bundle in dist/ is still inspected, just not demanded.
+    const discoveredNames = new Set(discovered.map((skill) => skill.name));
+    const poolNames = new Set([...discoveredNames, ...Object.keys(skillsConfig?.config ?? {})]);
+    for (const skillName of poolNames) {
+        const outputDir = safePath.resolve(cwd, 'dist', 'skills', skillNameToFsPath(skillName));
+        const packaging = packagingOf(skillName);
+        addCheckCandidate(outputs, seen, cwd, { skillName, outputDir, packaging }, discoveredNames.has(skillName) && isSkillPublished(packaging));
     }
-    catch {
-        return [];
+    // --- Tree-copy skills: candidate dirs are plugin output skill dirs ---
+    // Always expected, whatever `publish` says: every location here is a
+    // plugin-local skill the claude build phase packages into the plugin tree —
+    // `publish` scopes the pool only (see `isSkillPublished`).
+    // Per-skill config goes through `pluginLocalSkillConfigEntry` — the plugin build's own
+    // lookup — under the declared name the build reads (`pluginLocalNames`).
+    for (const loc of pluginLocal.locations) {
+        const declaredName = pluginLocalNames.get(safePath.resolve(loc.skillSourceDir));
+        if (declaredName === undefined) {
+            throw new Error(`vat verify defect: no declared name was read for the plugin-local skill at ${loc.skillSourceDir}`);
+        }
+        const perSkill = pluginLocalSkillConfigEntry(skillsConfig?.config, { skillName: declaredName, skillDirPath: loc.skillDirPath });
+        addCheckCandidate(outputs, seen, cwd, {
+            skillName: loc.skillDirPath,
+            outputDir: loc.skillOutputDir,
+            packaging: mergeSkillPackagingConfig(defaults, perSkill),
+        }, true);
     }
+    return outputs;
 }
 /**
  * Check that all dest paths from the merged files config exist in the built output.
@@ -234,11 +304,13 @@ function collectBuiltSkillOutputs(cwd, discovered) {
  *
  * @param discovered - The skills this run discovered from `skills.include`. See
  *   {@link collectBuiltSkillOutputs} for why it is required rather than optional.
+ * @param pluginLocal - The run's plugin-local index — required for the same reason.
+ * @param pluginLocalNames - The declared name of every location in `pluginLocal` — required for the same reason.
  * @returns One result per (skill, outputDir) pair where dests are absent.
  */
-export function checkFilesConfigDests(cwd, discovered) {
+export function checkFilesConfigDests(cwd, discovered, pluginLocal, pluginLocalNames) {
     const results = [];
-    for (const check of collectBuiltSkillOutputs(cwd, discovered)) {
+    for (const check of collectBuiltSkillOutputs(cwd, discovered, pluginLocal, pluginLocalNames).built) {
         const { skillName, outputDir } = check;
         const mergedFiles = filesOf(check);
         if (mergedFiles.length === 0)
@@ -246,7 +318,6 @@ export function checkFilesConfigDests(cwd, discovered) {
         const missing = [];
         for (const entry of mergedFiles) {
             const destPath = safePath.resolve(outputDir, entry.dest);
-            // eslint-disable-next-line security/detect-non-literal-fs-filename -- destPath resolved from config
             if (!existsSync(destPath)) {
                 missing.push(entry.dest);
             }
@@ -290,20 +361,33 @@ export function checkFilesConfigDests(cwd, discovered) {
  * whose usage is only answerable across a whole run, and this phase would have to
  * drain a ledger it is not the run of — reporting ALLOW_UNUSED for every entry the
  * project declares for other lanes. Severity is answerable per unit of work; allow
- * is not. See `AllowUsageLedger` in `@vibe-agent-toolkit/agent-schema`.
+ * is not. See `AllowUsageLedger` in `@vibe-agent-toolkit/schema`.
  *
  * Locations anchor at `cwd`, the run's stated root, so a reader can open them.
  *
+ * Returns the count of bundles crawled beside the findings, because the phase
+ * that publishes them needs the denominator: zero findings over zero bundles is
+ * not a pass — see {@link buildPackagedContentPhase}.
+ *
  * @param discovered - The skills this run discovered from `skills.include`. See
  *   {@link collectBuiltSkillOutputs} for why it is required rather than optional.
+ * @param pluginLocal - The run's plugin-local index — required for the same reason.
+ * @param pluginLocalNames - The declared name of every location in `pluginLocal` — required for the same reason.
  */
-export function checkPackagedAgentInstructionFiles(cwd, discovered) {
+export function checkPackagedAgentInstructionFiles(cwd, discovered, pluginLocal, pluginLocalNames) {
     const issues = [];
-    for (const check of collectBuiltSkillOutputs(cwd, discovered)) {
+    const outputs = collectBuiltSkillOutputs(cwd, discovered, pluginLocal, pluginLocalNames);
+    for (const check of outputs.built) {
         const raw = detectPackagedAgentInstructionFiles(check.outputDir, cwd, explicitFilesConfigDests(filesOf(check)));
         issues.push(...resolveIssueSeverity(raw, check.packaging.validation));
     }
-    return issues;
+    return {
+        bundlesInspected: outputs.built.length,
+        bundlesExpected: outputs.expected,
+        bundlesInPlace: outputs.inPlace,
+        bundlesMissing: outputs.missing,
+        issues,
+    };
 }
 /**
  * Load the project config without letting a broken one abort the command.
@@ -407,31 +491,35 @@ const VERIFY_VOCABULARY = {
  * `vat build`).
  *
  * @param configError - The config-load failure, when the config could not be
- *   read. Every subprocess phase still runs so the CHILD reports the real
- *   config error (exit 2) instead of this command guessing.
- * @param verbose - Forwarded to each subprocess phase as `--verbose`. The
- *   children own their own summarization; this command only relays the request.
+ *   read. Every delegated phase still runs so THE PHASE reports the real config
+ *   error (exit 2) instead of this command guessing.
+ * @param verbose - Forwarded to each delegated phase. Each phase owns its own
+ *   summarization; this command only relays the request.
  */
 export function selectVerifyPhases(config, configError, verbose) {
     const phases = [];
     const unreadable = configError !== undefined;
-    const detail = verbose === true ? ['--verbose'] : [];
+    const detail = verbose === true;
     if (unreadable || config?.resources) {
-        phases.push({ name: 'resources', args: ['resources', 'validate', ...detail] });
+        phases.push({
+            name: 'resources',
+            run: () => runResourcesValidatePhase(undefined, { verbose: detail }),
+        });
     }
     if (unreadable || config?.skills) {
-        phases.push({ name: 'skills', args: ['skills', 'validate', ...detail] });
+        phases.push({
+            name: 'skills',
+            run: () => runSkillsValidatePhase(undefined, { verbose: detail }),
+        });
     }
     for (const name of Object.keys(config?.claude?.marketplaces ?? {})) {
+        // Bound per marketplace, so each phase closes over its OWN name. This is a
+        // loop over the adopter's config, which is why verify's phase count is
+        // `2 + n` and never the constant four its help text once implied.
+        const marketplacePath = `dist/.claude/plugins/marketplaces/${name}`;
         phases.push({
             name: `marketplace:${name}`,
-            args: [
-                'claude',
-                'marketplace',
-                'validate',
-                `dist/.claude/plugins/marketplaces/${name}`,
-                ...detail,
-            ],
+            run: () => runMarketplaceValidatePhase(marketplacePath, { verbose: detail }),
         });
     }
     return decidePhaseSelection(undefined, phases, VERIFY_VOCABULARY, {
@@ -446,7 +534,7 @@ const PACKAGED_CONTENT = 'packaged-content';
  * The SINGLE source for that question: {@link verifyTopLevelCommand} gates
  * execution on this list and {@link formatVerifyAnnouncement} announces the same
  * list, so the printed phase list cannot drift from the phases that run. It used
- * to be announced from the subprocess phases alone while these two were gated by
+ * to be announced from the delegated phases alone while these two were gated by
  * hand-written conditions further down, so a run printed '(phases: skills)' and
  * then also ran `consistency`, which put a second entry in the emitted document.
  * A status that under-reports what it did is the same defect class as
@@ -479,8 +567,8 @@ function selectInProcessVerifyPhases(config) {
  * The startup announcement: every phase this run will inspect something with,
  * in order. A phase that would consult nothing is not named.
  */
-export function formatVerifyAnnouncement(subprocessPhaseNames, config) {
-    const all = [...subprocessPhaseNames, ...selectInProcessVerifyPhases(config)];
+export function formatVerifyAnnouncement(delegatedPhaseNames, config) {
+    const all = [...delegatedPhaseNames, ...selectInProcessVerifyPhases(config)];
     return `🔍 vat verify (phases: ${all.join(' → ')})`;
 }
 /**
@@ -509,11 +597,89 @@ export function toPublishedIssue(issue) {
         ...(issue.reference === undefined ? {} : { reference: issue.reference }),
     };
 }
+/**
+ * The refusal for a crawl that found only PART of the build.
+ *
+ * Mirrors `unresolvedLocalPluginsFinding` in `claude/marketplace/validate.ts`:
+ * the count declared, the count checked, and the missing ones BY NAME — the
+ * operator's next move is to look at those paths, so the message carries them.
+ * ONE finding however many are missing (run-integrity invariant 4).
+ *
+ * @param crawl - What the crawl found, over what
+ * @returns The one finding, or nothing when every expected bundle was inspected
+ */
+function missingBundlesFinding(crawl) {
+    if (crawl.bundlesMissing.length === 0)
+        return [];
+    const named = crawl.bundlesMissing.map((dir) => `\`${dir}\``).join(', ');
+    return [runIntegrityFinding(`This run discovered skills that \`vat build\` produces ${crawl.bundlesExpected} bundle(s) for and`
+            + ` the packaged-content phase inspected ${crawl.bundlesInspected}, so this phase is not a verdict`
+            + ' on the build: a bundle that was never crawled reads the same as a clean one. Expected'
+            + ` bundle(s) not found on disk: ${named}. Usually \`vat build\` has not run since a skill was`
+            + ' added, failed part-way, or wrote somewhere other than dist/ — or the bundle was deleted.'
+            + ' Run `vat build` first, then re-run `vat verify`.')];
+}
+/**
+ * Build the `packaged-content` phase result from what the crawl found.
+ *
+ * 🚨 **Zero bundles is an ERROR, not a clean phase — and so is a MISSING one.**
+ * The phase is pushed unconditionally whenever `skills:` exists and it feeds the
+ * real exit code; `discoverSkillsFromConfig` returning `[]` on a typo'd glob —
+ * or `dist/` not having been built at all, or built somewhere else — gave the
+ * crawl nothing to walk, and nothing walked was zero findings was `success`,
+ * with no count in the document to say the phase had looked at nothing. `vat
+ * verify` exists to check the BUILT tree; a run that found none of it is not a
+ * verdict on it. Nor is a run that found half of it: with `bundlesInspected` as
+ * the only denominator, two discovered skills and one deleted bundle published
+ * `success` beside `bundlesInspected: 1`. The crawl now also carries what it
+ * should have found, and the document publishes both counts.
+ *
+ * One zero IS a verdict: nothing expected because every discovered skill is in
+ * place (`bundlesInPlace > 0`). Zero discovered skills stays refused.
+ *
+ * Derived here, in the one function that produces this phase's document, and
+ * not in the command body, so no path through the orchestrator can publish
+ * `status: success` beside `bundlesInspected: 0` or beside a non-empty
+ * `bundlesMissing`. Through the shared mechanism in `run-integrity.ts`: one
+ * non-overridable `RESOURCE_CHECK_BROKEN` at `error`, which
+ * {@link exitCodeForPhases} then turns into exit 1. ONE, not two, when both
+ * apply: the missing-bundle refusal is derived first because it names paths,
+ * and {@link nothingCheckedFinding} stands down behind an existing
+ * run-integrity finding.
+ *
+ * Pure, and exported so the refusal is pinned without a project on disk.
+ */
+export function buildPackagedContentPhase(crawl) {
+    const { bundlesInspected, bundlesExpected, bundlesInPlace, bundlesMissing, issues: found } = crawl;
+    const missing = missingBundlesFinding(crawl);
+    const accountedFor = bundlesExpected === 0 ? bundlesInspected + bundlesInPlace : bundlesInspected;
+    const issues = [
+        ...missing,
+        ...nothingCheckedFinding(accountedFor, [...missing, ...found], () => 'The packaged-content phase inspected 0 built skill bundles, so this phase is not a'
+            + ' verdict: nothing was crawled for files that must not ship, and the document reads'
+            + ' the same as a run over clean bundles. Either `vat build` has not run (or wrote'
+            + ' somewhere other than dist/), or `skills.include` in vibe-agent-toolkit.config.yaml'
+            + ' matched no SKILL.md — usually a typo in the glob. Run `vat build` first; `vat skills'
+            + ' validate` lists what the globs discover.'),
+        ...found,
+    ];
+    return {
+        name: PACKAGED_CONTENT,
+        status: calculateValidationStatus(issues),
+        // The denominator, beside the counts it qualifies — and what it should have been.
+        bundlesInspected,
+        bundlesExpected,
+        bundlesInPlace,
+        bundlesMissing,
+        issueCounts: countBySeverity(issues),
+        issues: issues.map(toPublishedIssue),
+    };
+}
 /**
  * `ConsistencyIssue` speaks the same severity vocabulary as `ValidationIssue`
  * but carries a free-form `code`, so it is counted through this projection —
  * there must be exactly ONE issues→status/counts collapse in the codebase, and
- * it lives in `@vibe-agent-toolkit/agent-schema`.
+ * it lives in `@vibe-agent-toolkit/schema`.
  */
 function asValidationIssues(issues) {
     return issues.map((issue) => ({
@@ -521,8 +687,42 @@ function asValidationIssues(issues) {
         severity: issue.severity,
         message: issue.message,
         fix: issue.fix,
+        ...(issue.location === undefined ? {} : { location: issue.location }),
+        ...(issue.line === undefined ? {} : { line: issue.line }),
     }));
 }
+/**
+ * Run the `packaged-content` phase: crawl, derive the phase document, and
+ * report THAT document's issues on stderr.
+ *
+ * 🚨 **The stderr report used to be gated on the crawl, one line before the
+ * refusal was derived.** `if (crawl.issues.length > 0) report(crawl.issues)`
+ * ran ahead of {@link buildPackagedContentPhase}, which is where the
+ * zero-bundle refusal is added — so on an unbuilt project the crawl found
+ * nothing, nothing was logged, the skills phase's `✅ All validations passed`
+ * stayed the last line on stderr, and the process exited 1 on a refusal that
+ * existed only in the YAML. Reporting from the phase result makes what stderr
+ * says and what the exit code is computed from one list, which is
+ * `run-integrity.ts` invariant 6.
+ *
+ * The round trip through `asValidationIssues` is deliberate rather than
+ * reporting the crawl's list plus a second derivation of the refusal: the
+ * document is the artifact of record, and stderr should render exactly what it
+ * carries, not a parallel computation that can drift from it.
+ */
+export function runPackagedContentPhase(projectRoot, discoveredSkills, pluginLocal, pluginLocalNames, logger) {
+    const phase = buildPackagedContentPhase(checkPackagedAgentInstructionFiles(projectRoot, discoveredSkills, pluginLocal, pluginLocalNames));
+    reportPackagedContentPhase(phase, logger);
+    return phase;
+}
+export function reportPackagedContentPhase(phase, logger) {
+    if (phase.issues.length > 0) {
+        reportPackagedContentIssues(asValidationIssues(phase.issues), logger);
+    }
+    else if (phase.bundlesExpected === 0 && phase.bundlesInspected === 0) {
+        logger.info(`\n▶ Phase: ${PACKAGED_CONTENT} — nothing to inspect: all ${phase.bundlesInPlace} discovered skill(s) are in place (publish: false)`);
+    }
+}
 /**
  * Run the in-process consistency check phase and record its outcome.
  *
@@ -535,7 +735,7 @@ function asValidationIssues(issues) {
  * and the packaged-content and files-config-dests phases need the same list. One
  * crawl per run, one answer to "which skills does this project have".
  */
-function runConsistencyPhase(logger, phaseResults, config, projectRoot, discoveredSkills) {
+function runConsistencyPhase(logger, phaseResults, config, projectRoot, discoveredSkills, pluginLocal) {
     if (!config?.skills) {
         // Nothing to cross-reference, so nothing to report: a run without a
         // `skills:` block is a genuine no-op, and {@link selectInProcessVerifyPhases}
@@ -549,7 +749,7 @@ function runConsistencyPhase(logger, phaseResults, config, projectRoot, discover
         // defensively (and narrows `config.skills` for the call below).
         return;
     }
-    const consistencyResult = runConsistencyChecks([...discoveredSkills], config, projectRoot);
+    const consistencyResult = runConsistencyChecks([...discoveredSkills], config, projectRoot, pluginLocal);
     const issues = consistencyResult.issues;
     if (issues.length > 0) {
         reportConsistencyIssues(issues, logger);
@@ -563,6 +763,55 @@ function runConsistencyPhase(logger, phaseResults, config, projectRoot, discover
     };
     phaseResults.push(result);
 }
+/**
+ * The in-process half of `vat verify`: `files-config-dests`, `packaged-content` and
+ * `consistency`, each where `inProcess` names it.
+ */
+async function runInProcessPhases(run) {
+    const { inProcess, config, projectRoot, logger, phaseResults } = run;
+    // ONE discovery for the whole in-process half of the run. Every phase below
+    // asks the same question — "which skills does this project have" — and each
+    // answer used to be a different one: `consistency` crawled, while
+    // `files-config-dests` and `packaged-content` read `skills.config` keys and
+    // were therefore blind to every skill discovered by a glob.
+    // `'refuse'`: a verify over a population it could not see is the
+    // green-without-checking shape this command exists to refuse. The throw
+    // lands in the command's catch → `handleCommandError`, exit 2, with the
+    // crawl's own root-relative sentence.
+    const discoveredSkills = await discoverSkillsFromConfig(run.skills, projectRoot, 'refuse');
+    // ONE plugin-local index likewise: listing it crawls every plugin, and every phase
+    // below asks it (in-place vs plugin-only, plugin-tree bundles, plugin assignment).
+    const pluginLocal = indexPluginLocalSkills(config, projectRoot);
+    // …and the declared name of each plugin-local skill, which keys its config exactly as
+    // the plugin build keyed it.
+    const pluginLocalNames = await readPluginLocalSkillNames(pluginLocal);
+    // Post-build files config check: verify all dest paths exist in built output
+    if (inProcess.includes(FILES_CONFIG_DESTS)) {
+        const filesDestResults = checkFilesConfigDests(projectRoot, discoveredSkills, pluginLocal, pluginLocalNames);
+        if (filesDestResults.length > 0) {
+            reportFilesDestErrors(filesDestResults, logger);
+            phaseResults.push({
+                name: FILES_CONFIG_DESTS,
+                status: 'error',
+                issueCounts: { errors: filesDestResults.length, warnings: 0, info: 0 },
+            });
+        }
+    }
+    // Packaged-content check: crawl each built skill bundle for repo-internal
+    // agent-instruction files. Publishes its findings INTO the document rather
+    // than only logging them — a file that must not ship has to be visible in
+    // `issueCounts`, or a CI consumer reads a clean report for a bundle carrying
+    // one. Warnings do not fail the run; the exit code still comes from errors.
+    // The zero-bundle refusal is derived inside the builder and logged from the
+    // built phase, so stderr, the document and the exit code carry one list.
+    if (inProcess.includes(PACKAGED_CONTENT)) {
+        phaseResults.push(runPackagedContentPhase(projectRoot, discoveredSkills, pluginLocal, pluginLocalNames, logger));
+    }
+    // Consistency check: cross-reference discovered skills vs package.json and plugin assignments
+    if (inProcess.includes('consistency')) {
+        runConsistencyPhase(logger, phaseResults, config, projectRoot, discoveredSkills, pluginLocal);
+    }
+}
 async function verifyTopLevelCommand(options, command) {
     // First, and before requireProjectRoot: `vat verify dist/skills/demo` used to
     // be accepted, have its path discarded, run wide over the whole project and
@@ -572,13 +821,15 @@ async function verifyTopLevelCommand(options, command) {
     // with "no vibe-agent-toolkit.config.yaml found" would diagnose the wrong
     // problem for anyone running the old invocation outside a project.
     rejectRetiredOnly(options.only, COMMAND_NAME, VERIFY_FULL_RUN_SECONDS);
-    // Spec §7: `vat verify` requires a projectRoot.
-    const projectRoot = requireProjectRoot(process.cwd(), COMMAND_NAME);
-    const { logger, startTime, binPath } = createPhaseContext(options.debug);
+    const { logger, startTime } = createPhaseContext(options.debug);
     try {
         // Inside the try, deliberately: phase selection used to throw from out here
         // (on an unroutable `--only`), so the user got a raw Node stack trace and
-        // zero bytes of the structured document a scripted caller parses.
+        // zero bytes of the structured document a scripted caller parses — and so
+        // did "no project here", at Node's default exit 1, which the contract reads
+        // as FINDINGS.
+        // Spec §7: `vat verify` requires a projectRoot.
+        const projectRoot = requireProjectRoot(process.cwd(), COMMAND_NAME);
         const { config, error: configError } = loadConfigTolerant(projectRoot);
         const phases = applyPhaseSelection(selectVerifyPhases(config, configError, options.verbose), logger, startTime);
         // Announced from the same list the in-process gates below read, so the
@@ -588,49 +839,13 @@ async function verifyTopLevelCommand(options, command) {
         const phaseResults = [];
         for (const phase of phases) {
             logger.info(`\n▶ Phase: ${phase.name}`);
-            phaseResults.push(runPhase(binPath, phase));
-        }
-        // ONE discovery for the whole in-process half of the run. Every phase below
-        // asks the same question — "which skills does this project have" — and each
-        // answer used to be a different one: `consistency` crawled, while
-        // `files-config-dests` and `packaged-content` read `skills.config` keys and
-        // were therefore blind to every skill discovered by a glob.
-        const discoveredSkills = inProcess.length > 0 && config?.skills
-            ? await discoverSkillsFromConfig(config.skills, projectRoot)
-            : [];
-        // Post-build files config check: verify all dest paths exist in built output
-        if (inProcess.includes(FILES_CONFIG_DESTS)) {
-            const filesDestResults = checkFilesConfigDests(projectRoot, discoveredSkills);
-            if (filesDestResults.length > 0) {
-                reportFilesDestErrors(filesDestResults, logger);
-                phaseResults.push({
-                    name: FILES_CONFIG_DESTS,
-                    status: 'error',
-                    issueCounts: { errors: filesDestResults.length, warnings: 0, info: 0 },
-                });
-            }
-        }
-        // Packaged-content check: crawl each built skill bundle for repo-internal
-        // agent-instruction files. Publishes its findings INTO the document rather
-        // than only logging them — a file that must not ship has to be visible in
-        // `issueCounts`, or a CI consumer reads a clean report for a bundle carrying
-        // one. Warnings do not fail the run; the exit code still comes from errors.
-        if (inProcess.includes(PACKAGED_CONTENT)) {
-            const packagedIssues = checkPackagedAgentInstructionFiles(projectRoot, discoveredSkills);
-            if (packagedIssues.length > 0) {
-                reportPackagedContentIssues(packagedIssues, logger);
-            }
-            const packagedResult = {
-                name: PACKAGED_CONTENT,
-                status: calculateValidationStatus(packagedIssues),
-                issueCounts: countBySeverity(packagedIssues),
-                issues: packagedIssues.map(toPublishedIssue),
-            };
-            phaseResults.push(packagedResult);
+            // Awaited in the loop, deliberately: phases are announced in a fixed order
+            // and their stderr streams live, so overlapping them would interleave two
+            // running reports into one unreadable channel.
+            phaseResults.push(await runPhase(phase));
         }
-        // Consistency check: cross-reference discovered skills vs package.json and plugin assignments
-        if (inProcess.includes('consistency')) {
-            runConsistencyPhase(logger, phaseResults, config, projectRoot, discoveredSkills);
+        if (inProcess.length > 0 && config?.skills) {
+            await runInProcessPhases({ inProcess, config, skills: config.skills, projectRoot, logger, phaseResults });
         }
         const duration = Date.now() - startTime;
         // Worst-wins across phases, with `system-error` outranking `error`: a phase