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

package/dist/commands/verify.d.ts

@@ -6,15 +6,19 @@
  *   2. vat skills validate     (SKILL.md frontmatter validation)
  *   3. vat claude marketplace validate  (strict marketplace validation, when configured)
  *   4. files-config-dests  (in-process; every `files:` dest exists in the built output)
- *   5. consistency check  (in-process; skill distribution integrity — package.json, plugin assignment)
+ *   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–5 run here and
+ * 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.
  */
+import { type ValidationIssue } from '@vibe-agent-toolkit/agent-schema';
 import type { ProjectConfig } from '@vibe-agent-toolkit/resources';
 import { Command } from 'commander';
+import { type ConsistencyIssueSeverity } from './consistency-check.js';
 import { type PhaseSelection } from './phase-utils.js';
+import type { DiscoveredSkill } from './skills/command-helpers.js';
 export interface VerifyCommandOptions {
     /** Retired; declared only so {@link rejectRetiredOnly} can explain the removal. */
     only?: string;
@@ -32,16 +36,55 @@ export interface FilesDestCheckResult {
 /**
  * Check that all dest paths from the merged files config exist in the built output.
  *
- * Checks each skill's dests in the location(s) where `vat build` actually wrote them:
- *   - Pool skills: `dist/skills/<fsName>/`            (only when that dir exists)
- *   - Tree-copy skills: `dist/.claude/plugins/.../skills/<name>/` (only when that dir exists)
- *
  * A dest is "missing" ONLY when absent from a candidate dir that exists. If a skill
  * has no existing candidate dir, it is not reported (build didn't run for that mode).
  *
+ * @param discovered - The skills this run discovered from `skills.include`. See
+ *   {@link collectBuiltSkillOutputs} for why it is required rather than optional.
  * @returns One result per (skill, outputDir) pair where dests are absent.
  */
-export declare function checkFilesConfigDests(cwd: string): FilesDestCheckResult[];
+export declare function checkFilesConfigDests(cwd: string, discovered: readonly DiscoveredSkill[]): FilesDestCheckResult[];
+/**
+ * Crawl every built skill bundle for repo-internal agent-instruction files.
+ *
+ * The built-skill-bundle arm of `PACKAGED_AGENT_INSTRUCTION_FILE`. Its description
+ * has always claimed three surfaces — a built skill bundle, an installed plugin, a
+ * plugin source directory — but only the two plugin arms had a producer: the skill
+ * lanes inspect SKILL.md plus what links reach from it, so a file that arrives in a
+ * bundle with no link at all was invisible to every command. Measured on an adopter
+ * bundle carrying two of them: `vat audit` reported `filesScanned: 1`, zero issues,
+ * and `vat verify` reported `warnings: 0`.
+ *
+ * UNCONDITIONAL here, with no provenance test: `vat verify` reads the built `dist/`
+ * tree by definition, so every tree this enumerates is distributed output. (`vat
+ * audit` takes an arbitrary path and therefore must answer the provenance question
+ * first — see `appendDistributedTreeFindings` in audit.ts.)
+ *
+ * Explicit `files:` dests are exempt (§8.2): here the config is knowable, and
+ * naming a dest is an instruction to ship that file. A glob match never earns the
+ * exemption — a glob is a net, not a declaration — which is why the exempt set
+ * comes from {@link explicitFilesConfigDests} rather than from every `files:` entry.
+ *
+ * Each bundle's findings are then resolved against that skill's effective
+ * `validation.severity` (see {@link resolveIssueSeverity}), so the opt-out the
+ * code's own `fix` text prescribes actually works here. It did not: this phase
+ * published `detectPackagedAgentInstructionFiles`' raw output straight into the
+ * document, so `severity.PACKAGED_AGENT_INSTRUCTION_FILE: ignore` changed nothing
+ * — measured `warnings: 1` with the override at `skills.defaults`, at
+ * `skills.config.<name>`, and with no override at all.
+ *
+ * `validation.allow` is deliberately NOT applied. Allow is a per-PATH suppression
+ * 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`.
+ *
+ * Locations anchor at `cwd`, the run's stated root, so a reader can open them.
+ *
+ * @param discovered - The skills this run discovered from `skills.include`. See
+ *   {@link collectBuiltSkillOutputs} for why it is required rather than optional.
+ */
+export declare function checkPackagedAgentInstructionFiles(cwd: string, discovered: readonly DiscoveredSkill[]): ValidationIssue[];
 /**
  * Decide which verification phases to run.
  *
@@ -70,4 +113,31 @@ export declare function selectVerifyPhases(config: ProjectConfig | undefined, co
  * in order. A phase that would consult nothing is not named.
  */
 export declare function formatVerifyAnnouncement(subprocessPhaseNames: readonly string[], config: ProjectConfig | undefined): string;
+/** An in-process phase's finding as it appears in the archived YAML. */
+interface PublishedIssue {
+    severity: ValidationIssue['severity'] | ConsistencyIssueSeverity;
+    code: string;
+    message: string;
+    fix: string;
+    /** Project-relative path of the file to open. Absent when the finding has none. */
+    location?: string;
+    /** 1-based line within {@link PublishedIssue.location}. */
+    line?: number;
+    /** Doc link the code's registry entry carries. */
+    reference?: string;
+}
+/**
+ * Project ONE finding into the archived YAML.
+ *
+ * The whole anchor rides along. This shape used to be `{severity, code, message,
+ * fix}` and the projection destructured exactly those four, so every
+ * `packaged-content` finding reached the document with no `location` — the same
+ * defect this PR fixed one command over in `vat skills build`, where a published
+ * count carried "no `code`, no location and no fix string at ANY verbosity". It
+ * looked survivable only because `materializeIssue` happens to interpolate the
+ * detail into `message` for this one code; that is a coincidence, not a contract,
+ * and stderr is not the document a CI consumer parses.
+ */
+export declare function toPublishedIssue(issue: ValidationIssue): PublishedIssue;
+export {};
 //# sourceMappingURL=verify.d.ts.map

package/dist/commands/verify.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../src/commands/verify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAYH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAEnE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAapC,OAAO,EAWL,KAAK,cAAc,EAEpB,MAAM,kBAAkB,CAAC;AAG1B,MAAM,WAAW,oBAAoB;IACnC,mFAAmF;IACnF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AASD,wBAAgB,2BAA2B,IAAI,OAAO,CA4ErD;AAED,iFAAiF;AACjF,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,kFAAkF;IAClF,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAwCD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,oBAAoB,EAAE,CAkDzE;AAkFD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,aAAa,GAAG,SAAS,EACjC,WAAW,CAAC,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,OAAO,GAChB,cAAc,CA6BhB;AAyCD;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,oBAAoB,EAAE,SAAS,MAAM,EAAE,EACvC,MAAM,EAAE,aAAa,GAAG,SAAS,GAChC,MAAM,CAGR"}
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../src/commands/verify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,OAAO,EAIL,KAAK,eAAe,EACrB,MAAM,kCAAkC,CAAC;AAO1C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAEnE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAWpC,OAAO,EAGL,KAAK,wBAAwB,EAC9B,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAWL,KAAK,cAAc,EAEpB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAGnE,MAAM,WAAW,oBAAoB;IACnC,mFAAmF;IACnF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAYD,wBAAgB,2BAA2B,IAAI,OAAO,CAqFrD;AAED,iFAAiF;AACjF,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,kFAAkF;IAClF,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAyID;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,SAAS,eAAe,EAAE,GACrC,oBAAoB,EAAE,CAmBxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAgB,kCAAkC,CAChD,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,SAAS,eAAe,EAAE,GACrC,eAAe,EAAE,CAWnB;AAwGD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,aAAa,GAAG,SAAS,EACjC,WAAW,CAAC,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,OAAO,GAChB,cAAc,CA6BhB;AA4CD;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,oBAAoB,EAAE,SAAS,MAAM,EAAE,EACvC,MAAM,EAAE,aAAa,GAAG,SAAS,GAChC,MAAM,CAGR;AAED,wEAAwE;AACxE,UAAU,cAAc;IAGtB,QAAQ,EAAE,eAAe,CAAC,UAAU,CAAC,GAAG,wBAAwB,CAAC;IACjE,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,mFAAmF;IACnF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,eAAe,GAAG,cAAc,CAavE"}

package/dist/commands/verify.js

@@ -6,24 +6,29 @@
  *   2. vat skills validate     (SKILL.md frontmatter validation)
  *   3. vat claude marketplace validate  (strict marketplace validation, when configured)
  *   4. files-config-dests  (in-process; every `files:` dest exists in the built output)
- *   5. consistency check  (in-process; skill distribution integrity — package.json, plugin assignment)
+ *   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–5 run here and
+ * 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.
  */
 import { existsSync } from 'node:fs';
 import { basename } from 'node:path';
 import { calculateValidationStatus, countBySeverity, } from '@vibe-agent-toolkit/agent-schema';
-import { computeTreeCopiedSkillLocations, mergeFilesConfig } from '@vibe-agent-toolkit/agent-skills';
+import { computeTreeCopiedSkillLocations, detectPackagedAgentInstructionFiles, explicitFilesConfigDests, } from '@vibe-agent-toolkit/agent-skills';
 import { safePath } from '@vibe-agent-toolkit/utils';
 import { Command } from 'commander';
 import { handleCommandError } from '../utils/command-error.js';
 import { loadConfig } from '../utils/config-loader.js';
+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 { 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';
 /**
  * Measured full-run duration on the 90-skill / 1,041-document adopter, cited by
@@ -31,6 +36,8 @@ import { discoverSkillsFromConfig } from './skills/skill-discovery.js';
  * 1.0s + consistency under a second.
  */
 const VERIFY_FULL_RUN_SECONDS = 32;
+/** How this command names itself in every user-facing diagnostic. */
+const COMMAND_NAME = 'vat verify';
 export function createVerifyTopLevelCommand() {
     const command = new Command('verify');
     addRetiredOnlyOption(command)
@@ -59,11 +66,14 @@ Description:
   Phases (in-process, 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
+                         file (CLAUDE.md, AGENTS.md, GEMINI.md). A dest an explicit
+                         'files:' entry names is honoured, not reported.
     consistency        → skill distribution integrity (package.json, plugin assignment)
 
-  A run with a 'skills:' block runs all three of skills, files-config-dests and
-  consistency: they read that same config block. Without it neither in-process
-  phase has anything to read, so neither runs.
+  A run with a 'skills:' block runs all four of skills, files-config-dests,
+  packaged-content and consistency: they read that same config block. Without it
+  no in-process phase has anything to read, so none run.
 
   The startup line on stderr names, in order, the phases that will inspect
   something. A phase that would consult nothing is not listed; a phase that does
@@ -76,9 +86,10 @@ Output:
     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'
-    carries its findings into the document too, while 'files-config-dests'
-    publishes counts only and lists the missing dests on stderr.
+    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.
   Progress and validation errors → stderr (streamed live)
 
   By default each subprocess phase reports a per-asset summary plus the assets
@@ -90,7 +101,12 @@ Exit Codes:
   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)
+      output that could not be parsed), 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>'.
 
 Requirements:
   projectRoot: required (errors if no vibe-agent-toolkit.config.yaml or .git/ ancestor)
@@ -110,38 +126,73 @@ Example:
 function skillNameToFsPath(name) {
     return name.replaceAll(':', '__');
 }
+/** The `files:` entries governing a candidate, `[]` when the skill declares none. */
+function filesOf(entry) {
+    return entry.packaging.files ?? [];
+}
 /**
- * Register a check for (skillName, outputDir, mergedFiles) in the dedup map.
+ * Register a check for (skillName, outputDir, packaging) in the dedup map.
  *
  * Skips silently if:
- *   - mergedFiles is empty (no entries to verify)
  *   - outputDir does not exist on disk (not a candidate)
  *   - the key was already added (dedup guard)
+ *
+ * An EMPTY `files:` block is registered, not skipped: {@link checkFilesConfigDests}
+ * has nothing to verify for such a skill and filters it out itself, but
+ * {@link checkPackagedAgentInstructionFiles} must still crawl that bundle — a skill
+ * 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, mergedFiles) {
-    if (mergedFiles.length === 0)
-        return;
+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))
         return;
     const key = `${skillName}\0${outputDir}`;
     if (!checks.has(key)) {
-        checks.set(key, { skillName, outputDir, mergedFiles });
+        checks.set(key, { skillName, outputDir, packaging });
     }
 }
 /**
- * Check that all dest paths from the merged files config exist in the built output.
+ * Every built skill bundle this project's config accounts for that EXISTS on disk,
+ * with the `files:` entries that govern it.
  *
- * Checks each skill's dests in the location(s) where `vat build` actually wrote them:
- *   - Pool skills: `dist/skills/<fsName>/`            (only when that dir exists)
- *   - Tree-copy skills: `dist/.claude/plugins/.../skills/<name>/` (only when that dir exists)
+ * 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>/`
  *
- * A dest is "missing" ONLY when absent from a candidate dir that exists. If a skill
- * has no existing candidate dir, it is not reported (build didn't run for that mode).
+ * 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 One result per (skill, outputDir) pair where dests are absent.
+ * 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
+ * phases blind to the common case: a per-skill `config:` block is optional, so a
+ * skill discovered only by `skills.include` had no key and its bundle was never
+ * looked at. Measured on a two-skill fixture with an identical `CLAUDE.md` planted
+ * in each built bundle, `packaged-content` reported ONE finding and exit 0 — the
+ * phase was structurally blind to the population its own doc comment cites as the
+ * motivating incident. The same line made `files-config-dests` a total no-op for a
+ * project whose `files:` entries live only under `skills.defaults`, while the
+ * startup banner still announced that the phase ran.
+ *
+ * The config keys stay in the union rather than being replaced by discovery: a key
+ * naming a skill discovery does not reach (a renamed glob, a stale entry) still
+ * points at a bundle that may be sitting in `dist/`, and dropping it would trade
+ * one blindness for another.
+ *
+ * `discovered` is a REQUIRED parameter, not an optional convenience: discovery
+ * 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).
+ *
+ * The merge goes through {@link mergeSkillPackagingConfig} — the ONE helper every
+ * lane uses — so `vat verify` and `vat build` cannot disagree about a skill's
+ * effective config. Doing the `files:` half by hand here and leaving `validation:`
+ * unread is what made `severity.PACKAGED_AGENT_INSTRUCTION_FILE: ignore` a no-op in
+ * this command.
  */
-export function checkFilesConfigDests(cwd) {
+function collectBuiltSkillOutputs(cwd, discovered) {
     try {
         const config = loadConfig(cwd);
         if (!config)
@@ -150,12 +201,15 @@ export function checkFilesConfigDests(cwd) {
         const defaults = skillsConfig?.defaults;
         // Dedup map: key = `skillName\0outputDir` → check entry
         const checks = new Map();
-        // --- Pool/config skills: candidate dir is dist/skills/<fsName> ---
-        for (const skillName of Object.keys(skillsConfig?.config ?? {})) {
+        // --- 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 mergedFiles = mergeFilesConfig(defaults?.files, perSkill?.files);
             const outputDir = safePath.resolve(cwd, 'dist', 'skills', skillNameToFsPath(skillName));
-            tryAddCheckEntry(checks, skillName, outputDir, mergedFiles);
+            tryAddCheckEntry(checks, skillName, outputDir, mergeSkillPackagingConfig(defaults, perSkill));
         }
         // --- Tree-copy skills: candidate dirs are plugin output skill dirs ---
         for (const loc of computeTreeCopiedSkillLocations(config, cwd)) {
@@ -163,31 +217,94 @@ export function checkFilesConfigDests(cwd) {
             // 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];
-            const mergedFiles = mergeFilesConfig(defaults?.files, perSkill?.files);
-            tryAddCheckEntry(checks, loc.skillDirPath, loc.skillOutputDir, mergedFiles);
-        }
-        // --- Run each pending check and collect results ---
-        const results = [];
-        for (const { skillName, outputDir, mergedFiles } of checks.values()) {
-            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);
-                }
-            }
-            if (missing.length > 0) {
-                results.push({ skillName, outputDir, missing });
-            }
+            const perSkill = (skillsConfig?.config?.[loc.skillDirPath] ?? skillsConfig?.config?.[dirLeaf]);
+            tryAddCheckEntry(checks, loc.skillDirPath, loc.skillOutputDir, mergeSkillPackagingConfig(defaults, perSkill));
         }
-        return results;
+        return [...checks.values()];
     }
     catch {
         return [];
     }
 }
+/**
+ * Check that all dest paths from the merged files config exist in the built output.
+ *
+ * A dest is "missing" ONLY when absent from a candidate dir that exists. If a skill
+ * has no existing candidate dir, it is not reported (build didn't run for that mode).
+ *
+ * @param discovered - The skills this run discovered from `skills.include`. See
+ *   {@link collectBuiltSkillOutputs} for why it is required rather than optional.
+ * @returns One result per (skill, outputDir) pair where dests are absent.
+ */
+export function checkFilesConfigDests(cwd, discovered) {
+    const results = [];
+    for (const check of collectBuiltSkillOutputs(cwd, discovered)) {
+        const { skillName, outputDir } = check;
+        const mergedFiles = filesOf(check);
+        if (mergedFiles.length === 0)
+            continue;
+        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);
+            }
+        }
+        if (missing.length > 0) {
+            results.push({ skillName, outputDir, missing });
+        }
+    }
+    return results;
+}
+/**
+ * Crawl every built skill bundle for repo-internal agent-instruction files.
+ *
+ * The built-skill-bundle arm of `PACKAGED_AGENT_INSTRUCTION_FILE`. Its description
+ * has always claimed three surfaces — a built skill bundle, an installed plugin, a
+ * plugin source directory — but only the two plugin arms had a producer: the skill
+ * lanes inspect SKILL.md plus what links reach from it, so a file that arrives in a
+ * bundle with no link at all was invisible to every command. Measured on an adopter
+ * bundle carrying two of them: `vat audit` reported `filesScanned: 1`, zero issues,
+ * and `vat verify` reported `warnings: 0`.
+ *
+ * UNCONDITIONAL here, with no provenance test: `vat verify` reads the built `dist/`
+ * tree by definition, so every tree this enumerates is distributed output. (`vat
+ * audit` takes an arbitrary path and therefore must answer the provenance question
+ * first — see `appendDistributedTreeFindings` in audit.ts.)
+ *
+ * Explicit `files:` dests are exempt (§8.2): here the config is knowable, and
+ * naming a dest is an instruction to ship that file. A glob match never earns the
+ * exemption — a glob is a net, not a declaration — which is why the exempt set
+ * comes from {@link explicitFilesConfigDests} rather than from every `files:` entry.
+ *
+ * Each bundle's findings are then resolved against that skill's effective
+ * `validation.severity` (see {@link resolveIssueSeverity}), so the opt-out the
+ * code's own `fix` text prescribes actually works here. It did not: this phase
+ * published `detectPackagedAgentInstructionFiles`' raw output straight into the
+ * document, so `severity.PACKAGED_AGENT_INSTRUCTION_FILE: ignore` changed nothing
+ * — measured `warnings: 1` with the override at `skills.defaults`, at
+ * `skills.config.<name>`, and with no override at all.
+ *
+ * `validation.allow` is deliberately NOT applied. Allow is a per-PATH suppression
+ * 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`.
+ *
+ * Locations anchor at `cwd`, the run's stated root, so a reader can open them.
+ *
+ * @param discovered - The skills this run discovered from `skills.include`. See
+ *   {@link collectBuiltSkillOutputs} for why it is required rather than optional.
+ */
+export function checkPackagedAgentInstructionFiles(cwd, discovered) {
+    const issues = [];
+    for (const check of collectBuiltSkillOutputs(cwd, discovered)) {
+        const raw = detectPackagedAgentInstructionFiles(check.outputDir, cwd, explicitFilesConfigDests(filesOf(check)));
+        issues.push(...resolveIssueSeverity(raw, check.packaging.validation));
+    }
+    return issues;
+}
 /**
  * Load the project config without letting a broken one abort the command.
  *
@@ -217,6 +334,25 @@ function reportFilesDestErrors(results, logger) {
         }
     }
 }
+/**
+ * Log packaged-content findings to stderr.
+ *
+ * A companion to the document entry, never a substitute for it: this phase's
+ * findings are published into the YAML too (see {@link FindingsPhaseResult}).
+ *
+ * Rendered through the SHARED {@link formatIssueLines}, which `vat skills build`
+ * and `vat skills validate` already use. The hand-rolled renderer this replaces
+ * printed severity, code, location and fix — and dropped `message`, the only part
+ * of a finding that says what is wrong. A second renderer for the same shape is
+ * how one command's findings end up spelled differently from every other's.
+ */
+function reportPackagedContentIssues(issues, logger) {
+    logger.error(`\n▶ Phase: ${PACKAGED_CONTENT}`);
+    for (const issue of issues) {
+        for (const line of formatIssueLines(issue, '  '))
+            logger.error(line);
+    }
+}
 /**
  * Log consistency check issues to stderr.
  */
@@ -302,6 +438,8 @@ export function selectVerifyPhases(config, configError, verbose) {
         unreadableConfig: configError,
     });
 }
+/** The in-process phase that crawls built skill bundles for what must not ship. */
+const PACKAGED_CONTENT = 'packaged-content';
 /**
  * Which in-process phases this run performs, given the config.
  *
@@ -335,7 +473,7 @@ export function selectVerifyPhases(config, configError, verbose) {
  * though a clean run reports nothing.
  */
 function selectInProcessVerifyPhases(config) {
-    return config?.skills === undefined ? [] : [FILES_CONFIG_DESTS, 'consistency'];
+    return config?.skills === undefined ? [] : [FILES_CONFIG_DESTS, PACKAGED_CONTENT, 'consistency'];
 }
 /**
  * The startup announcement: every phase this run will inspect something with,
@@ -345,6 +483,32 @@ export function formatVerifyAnnouncement(subprocessPhaseNames, config) {
     const all = [...subprocessPhaseNames, ...selectInProcessVerifyPhases(config)];
     return `🔍 vat verify (phases: ${all.join(' → ')})`;
 }
+/**
+ * Project ONE finding into the archived YAML.
+ *
+ * The whole anchor rides along. This shape used to be `{severity, code, message,
+ * fix}` and the projection destructured exactly those four, so every
+ * `packaged-content` finding reached the document with no `location` — the same
+ * defect this PR fixed one command over in `vat skills build`, where a published
+ * count carried "no `code`, no location and no fix string at ANY verbosity". It
+ * looked survivable only because `materializeIssue` happens to interpolate the
+ * detail into `message` for this one code; that is a coincidence, not a contract,
+ * and stderr is not the document a CI consumer parses.
+ */
+export function toPublishedIssue(issue) {
+    return {
+        severity: issue.severity,
+        code: issue.code,
+        message: issue.message,
+        fix: issue.fix ?? '',
+        // Conditional rather than `location: issue.location`: `exactOptionalPropertyTypes`
+        // distinguishes an absent key from an explicit `undefined`, and a YAML document
+        // carrying `location: null` claims something the finding never said.
+        ...(issue.location === undefined ? {} : { location: issue.location }),
+        ...(issue.line === undefined ? {} : { line: issue.line }),
+        ...(issue.reference === undefined ? {} : { reference: issue.reference }),
+    };
+}
 /**
  * `ConsistencyIssue` speaks the same severity vocabulary as `ValidationIssue`
  * but carries a free-form `code`, so it is counted through this projection —
@@ -366,8 +530,12 @@ function asValidationIssues(issues) {
  * to go to stderr only, so the archived YAML — the artifact of record — said
  * nothing happened. And a warning-only run reported `passed`, which is the
  * reassuring answer to a question it could not represent.
+ *
+ * Discovery is handed in rather than performed here: it crawls the whole project,
+ * 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".
  */
-async function runConsistencyPhase(logger, phaseResults, config, projectRoot) {
+function runConsistencyPhase(logger, phaseResults, config, projectRoot, discoveredSkills) {
     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}
@@ -381,8 +549,7 @@ async function runConsistencyPhase(logger, phaseResults, config, projectRoot) {
         // defensively (and narrows `config.skills` for the call below).
         return;
     }
-    const discoveredSkills = await discoverSkillsFromConfig(config.skills, projectRoot);
-    const consistencyResult = runConsistencyChecks(discoveredSkills, config, projectRoot);
+    const consistencyResult = runConsistencyChecks([...discoveredSkills], config, projectRoot);
     const issues = consistencyResult.issues;
     if (issues.length > 0) {
         reportConsistencyIssues(issues, logger);
@@ -392,17 +559,21 @@ async function runConsistencyPhase(logger, phaseResults, config, projectRoot) {
         name: 'consistency',
         status: calculateValidationStatus(asValidation),
         issueCounts: countBySeverity(asValidation),
-        issues: issues.map(({ severity, code, message, fix }) => ({ severity, code, message, fix })),
+        issues: asValidation.map(toPublishedIssue),
     };
     phaseResults.push(result);
 }
-async function verifyTopLevelCommand(options) {
+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
+    // report success. Nothing below can un-tell that lie, so the run ends here.
+    rejectPositionalArguments(command.args, COMMAND_NAME, 'verifies every phase vibe-agent-toolkit.config.yaml declares, against the built dist/ tree');
     // Before requireProjectRoot: a retired flag is a usage error, and answering it
     // 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, 'vat verify', VERIFY_FULL_RUN_SECONDS);
+    rejectRetiredOnly(options.only, COMMAND_NAME, VERIFY_FULL_RUN_SECONDS);
     // Spec §7: `vat verify` requires a projectRoot.
-    const projectRoot = requireProjectRoot(process.cwd(), 'vat verify');
+    const projectRoot = requireProjectRoot(process.cwd(), COMMAND_NAME);
     const { logger, startTime, binPath } = createPhaseContext(options.debug);
     try {
         // Inside the try, deliberately: phase selection used to throw from out here
@@ -419,9 +590,17 @@ async function verifyTopLevelCommand(options) {
             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);
+            const filesDestResults = checkFilesConfigDests(projectRoot, discoveredSkills);
             if (filesDestResults.length > 0) {
                 reportFilesDestErrors(filesDestResults, logger);
                 phaseResults.push({
@@ -431,9 +610,27 @@ async function verifyTopLevelCommand(options) {
                 });
             }
         }
+        // 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);
+        }
         // Consistency check: cross-reference discovered skills vs package.json and plugin assignments
         if (inProcess.includes('consistency')) {
-            await runConsistencyPhase(logger, phaseResults, config, projectRoot);
+            runConsistencyPhase(logger, phaseResults, config, projectRoot, discoveredSkills);
         }
         const duration = Date.now() - startTime;
         // Worst-wins across phases, with `system-error` outranking `error`: a phase