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

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

@@ -4,8 +4,12 @@
  * Discovers skills from config yaml skills.include/exclude, validates each
  * using validateSkillForPackaging with merged packaging config.
  */
-import { type SeverityCounts, type ValidationIssue } from '@vibe-agent-toolkit/agent-schema';
-import { type PackagingValidationResult } from '@vibe-agent-toolkit/agent-skills';
+import { type DeclaredEvalSuite, type PackagingValidationResult, type SkillPackagingConfig, type SkillValidationSharedContext } from '@vibe-agent-toolkit/agent-skills';
+import { ResourceRegistry, type ProjectConfig, type ResourcePopulationSource, type SkillsConfig } from '@vibe-agent-toolkit/resources';
+import { type SeverityCounts, type ValidationIssue } from '@vibe-agent-toolkit/schema';
+import { type createLogger } from '../../utils/logger.js';
+import { type PhaseOutcome } from '../phase-utils.js';
+import { type DiscoveredSkill } from './command-helpers.js';
 /**
  * Skills validate command options
  */
@@ -14,6 +18,12 @@ export interface SkillsValidateCommandOptions {
     debug?: boolean;
     verbose?: boolean;
 }
+/**
+ * Discovered skill with merged packaging config for validation
+ */
+export interface ValidatableSkill extends DiscoveredSkill {
+    packagingConfig: SkillPackagingConfig;
+}
 /** The vocabulary of a validation verdict: worst ACTIONABLE severity. */
 type ValidationStatus = 'success' | 'warning' | 'error';
 /**
@@ -26,6 +36,46 @@ type ValidationStatus = 'success' | 'warning' | 'error';
  * validated at the time is what produced 78 warnings from 3 real entries.
  */
 type RunIssues = readonly ValidationIssue[];
+/**
+ * The discovery declaration a run's document answers for: the globs that
+ * decided which skills it validated. Only these two keys are read, so a caller
+ * with a full `SkillsConfig` and a test with two arrays hand in the same thing.
+ */
+export type SkillDiscoveryPatterns = Pick<SkillsConfig, 'include' | 'exclude'>;
+/**
+ * The run-level findings, with the run-integrity refusal derived in front of
+ * them when the run validated no skill.
+ *
+ * 🚨 **Zero skills validated is an ERROR, not a clean run.** `skills.include`
+ * globs that discover nothing — a typo, a renamed directory, an `exclude` that
+ * swallows every match — used to take an early return that printed one info
+ * line and published NO document at exit 0, and `vat validate` folded that into
+ * `status: success`: the gate the docs name as THE gate, green forever on a
+ * config that checked nothing. `vat verify` refused the identical config in its
+ * `packaged-content` phase and its message sent the operator to this command,
+ * which then said nothing.
+ *
+ * 🔑 The ONE seam both channels read. {@link buildValidateSummary} (the
+ * document) and {@link formatValidationReportLines} (stderr) both derive their
+ * issue set here, so "denominator zero, status clean" is unrepresentable on
+ * either channel rather than merely unwritten, and the exit code — derived from
+ * the document's own counts — agrees with both by construction. Through the
+ * shared mechanism in `run-integrity.ts`: one non-overridable
+ * `RESOURCE_CHECK_BROKEN` at `error`.
+ *
+ * Only the empty GLOB is refused. A config with no `skills:` block at all is a
+ * choice — the project declares no skills — and both orchestrators already skip
+ * this phase on that config; the phase declines it the same way (no document,
+ * exit 0) rather than inventing a refusal for a gate nobody declared.
+ *
+ * @param results - One result per skill the run validated: the denominator
+ * @param runIssues - The run's own findings so far (`ALLOW_UNUSED`), so an
+ *   existing run-integrity report is not duplicated
+ * @param patterns - The discovery globs, named in the refusal so the operator
+ *   sees what matched nothing
+ * @returns The run-level issues the document and the stderr report publish
+ */
+export declare function withRunIntegrity(results: readonly PackagingValidationResult[], runIssues: RunIssues, patterns: SkillDiscoveryPatterns): ValidationIssue[];
 /**
  * Build the YAML summary object.
  *
@@ -52,8 +102,13 @@ type RunIssues = readonly ValidationIssue[];
  * zeros: `issueCounts` and `runIssueCounts` keep their complete
  * `{errors, warnings, info}` shape in both modes, because they are the
  * reconciliation identity rather than something a reader scans.
+ *
+ * A run over ZERO skills is refused here, not passed — see
+ * {@link withRunIntegrity}, which is why the discovery `patterns` are a
+ * parameter of a document builder: the refusal names the globs that matched
+ * nothing, and the builder is where the refusal is derived.
  */
-export declare function buildValidateSummary(results: PackagingValidationResult[], duration: number, verbose: boolean, runIssues: RunIssues): {
+export declare function buildValidateSummary(results: PackagingValidationResult[], duration: number, verbose: boolean, runIssues: RunIssues, patterns: SkillDiscoveryPatterns): {
     status: ValidationStatus;
     issueCounts: SeverityCounts;
     runIssueCounts: SeverityCounts;
@@ -79,8 +134,12 @@ export declare function buildValidateSummary(results: PackagingValidationResult[
  * Run-level findings and the banner are printed in full either way — there are
  * ~14 of the former, and they belong to the project config rather than to any
  * asset, so there is no row for them to collapse into.
+ *
+ * Reads the same seam as the document builder ({@link withRunIntegrity}), so a
+ * run over zero skills prints the refusal here too rather than a green banner
+ * over a document that says `error`.
  */
-export declare function formatValidationReportLines(results: PackagingValidationResult[], runIssues: RunIssues, verbose: boolean): string[];
+export declare function formatValidationReportLines(results: PackagingValidationResult[], runIssues: RunIssues, verbose: boolean, patterns: SkillDiscoveryPatterns): string[];
 /**
  * Log validation progress for a single skill.
  *
@@ -90,6 +149,83 @@ export declare function formatValidationReportLines(results: PackagingValidation
  * collapse as the batch banner, one line earlier.
  */
 export declare function formatSkillProgressLine(skillName: string, result: PackagingValidationResult): string[];
+/**
+ * Build a single shared validation context for an entire `vat skills validate`
+ * invocation.
+ *
+ * When every skill in the batch resolves to the same projectRoot (the normal
+ * monorepo case), we crawl the resource registry once and hand the same
+ * instance to each skill's validation — the per-skill markdown reparse
+ * disappears. Similarly, gitignore checks are backed by a single
+ * {@link GitTracker} when every skill sits inside the same git repository.
+ *
+ * When the batch is heterogeneous (e.g. multiple projectRoots), the helper
+ * returns an empty context and validators transparently fall back to their
+ * legacy per-skill setup — correctness first, perf second.
+ */
+/**
+ * Options for {@link buildSkillsValidateRegistry}.
+ */
+export interface SkillsValidateRegistryOptions {
+    /**
+     * The project's configuration, or `undefined` for a project that has none.
+     *
+     * **Not optional in the sense of "nice to have".** A collection may declare a
+     * `mimeType` that overrides the extension tables and decides which parser runs
+     * over a file. `ResourceRegistry` routes through `resources.collections` when —
+     * and only when — it was handed a config; the projection lane behind
+     * `populationSource` reads those same declarations off the root. A registry
+     * built without the config therefore reaches a DIFFERENT verdict about whether
+     * a file is prose than the population that enumerated it, inside one command.
+     *
+     * Passed rather than re-read here so this lane cannot answer from a second,
+     * later parse of the same file.
+     */
+    config?: ProjectConfig | undefined;
+    /**
+     * Where the file list comes from — omit for the incumbent walk, supply one to
+     * source it from a projection instead. Enumeration only: `include` below is
+     * re-applied to whatever the source offers.
+     */
+    populationSource?: ResourcePopulationSource | undefined;
+}
+/**
+ * The markdown-only, link-resolved registry `vat skills validate` shares across
+ * every skill in one invocation.
+ *
+ * Exported and named because it had two implementations: this one, and a
+ * restatement inside `pipeline-oracles/lanes.ts` whose own comment recorded that
+ * it was "the one lane with no reusable builder to point at". A copy of a
+ * registry builder is a copy of its ARGUMENTS, and the argument that matters
+ * here is `config` — see {@link SkillsValidateRegistryOptions.config}.
+ *
+ * @param projectRoot - Root every skill in the batch resolves to
+ * @param options - The governing config, and optionally the projection-backed
+ *   enumeration to build from
+ * @returns A crawled registry whose links are already resolved
+ */
+export declare function buildSkillsValidateRegistry(projectRoot: string, options?: SkillsValidateRegistryOptions): Promise<ResourceRegistry>;
+export declare function buildSharedValidationContext(skills: ValidatableSkill[], projectSkills: readonly DeclaredEvalSuite[], config: ProjectConfig | undefined, logger: ReturnType<typeof createLogger>): Promise<SkillValidationSharedContext>;
+/**
+ * Validate every configured skill and hand back the document and exit code,
+ * printing the document nowhere.
+ *
+ * The phase entry point for `vat validate` and `vat verify`. The one early
+ * return publishes NO document: a config with no `skills:` block prints one
+ * info line, exits 0, and `phaseResultFromOutcome` records that as `success`
+ * with no `report` — both orchestrators skip the phase on that config anyway,
+ * because declaring no skills is a choice.
+ *
+ * A `skills:` block whose globs discover nothing is NOT a second early return.
+ * It used to be — one info line, no document, exit 0 — and that made `vat
+ * validate` green forever on a typo'd glob. It now runs through the same
+ * builder as a populated batch, which refuses a zero denominator (see
+ * {@link withRunIntegrity}): a document with one `RESOURCE_CHECK_BROKEN` at
+ * `error`, `status: error`, exit 1. Exit 1 and not 2, deliberately: the run
+ * completed and the gate FAILED, which is the class an operator's CI already
+ * handles; 2 is for a run that could not answer at all.
+ */
+export declare function runSkillsValidatePhase(pathArg: string | undefined, options: SkillsValidateCommandOptions): Promise<PhaseOutcome>;
 /**
  * Skills validate command implementation
  */

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

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../src/commands/skills/validate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAKL,KAAK,cAAc,EACnB,KAAK,eAAe,EACrB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAGL,KAAK,yBAAyB,EAG/B,MAAM,kCAAkC,CAAC;AA8B1C;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AASD,yEAAyE;AACzE,KAAK,gBAAgB,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;AAaxD;;;;;;;;GAQG;AACH,KAAK,SAAS,GAAG,SAAS,eAAe,EAAE,CAAC;AA6D5C;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,yBAAyB,EAAE,EACpC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,SAAS,GACnB;IACD,MAAM,EAAE,gBAAgB,CAAC;IACzB,WAAW,EAAE,cAAc,CAAC;IAC5B,cAAc,EAAE,cAAc,CAAC;IAC/B,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,OAAO,EAAE,CAAC;IACnB,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,YAAY,EAAE,MAAM,CAAC;CACtB,CA2BA;AAqHD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,yBAAyB,EAAE,EACpC,SAAS,EAAE,SAAS,EACpB,OAAO,EAAE,OAAO,GACf,MAAM,EAAE,CAeV;AAkCD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,yBAAyB,GAChC,MAAM,EAAE,CAeV;AAkGD;;GAEG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,OAAO,EAAE,4BAA4B,GACpC,OAAO,CAAC,IAAI,CAAC,CA4Ff"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../src/commands/skills/validate.ts"],"names":[],"mappings":"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"}

package/dist/commands/skills/validate.js

@@ -4,19 +4,23 @@
  * Discovers skills from config yaml skills.include/exclude, validates each
  * using validateSkillForPackaging with merged packaging config.
  */
-import { allowUnusedIssues, calculateValidationStatus, countBySeverity, createAllowUsageLedger, } from '@vibe-agent-toolkit/agent-schema';
-import { validateSkillForPackaging, } from '@vibe-agent-toolkit/agent-skills';
-import { ResourceRegistry } from '@vibe-agent-toolkit/resources';
-import { findProjectRoot, gitFindRoot, GitTracker, safePath } from '@vibe-agent-toolkit/utils';
+import { conventionalSuiteProbe, validateSkillForPackaging, } from '@vibe-agent-toolkit/agent-skills';
+import { ResourceRegistry, } from '@vibe-agent-toolkit/resources';
+import { allowUnusedIssues, calculateValidationStatus, countBySeverity, createAllowUsageLedger, } from '@vibe-agent-toolkit/schema';
+import { findProjectRoot, safePath } from '@vibe-agent-toolkit/utils';
+import { gitFindRoot, GitTracker } from '@vibe-agent-toolkit/utils/git';
 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 { formatDurationSecs } from '../../utils/duration.js';
 import { formatIssueLines, formatRunIssueLines, formatSeverityBreakdown, issuesToRenderAtVerbosity, summarizeFindings, sumSeverityCounts, } from '../../utils/issue-rendering.js';
 import { requireProjectRoot } from '../../utils/project-root-policy.js';
+import { RESOURCES_CRAWL_ENV, RESOURCES_CRAWL_PROJECTION, withResourcePopulationSource, } from '../../utils/resource-loader.js';
+import { nothingCheckedFinding } from '../../utils/run-integrity.js';
 import { collectDeclaredEvalSuites, mergeSkillPackagingConfig } from '../../utils/skill-packaging-config.js';
 import { renderSkillQualityFooter } from '../../utils/skill-quality-footer.js';
 import { applyConfigVerdicts } from '../../utils/verdict-helpers.js';
+import { finishCommand } from '../phase-utils.js';
 import { filterSkillsByName, setupCommandContext, } from './command-helpers.js';
 import { discoverSkillsFromConfig } from './skill-discovery.js';
 /**
@@ -29,6 +33,62 @@ import { discoverSkillsFromConfig } from './skill-discovery.js';
 function batchIssues(results) {
     return results.flatMap((r) => r.allErrors);
 }
+/**
+ * The run-level findings, with the run-integrity refusal derived in front of
+ * them when the run validated no skill.
+ *
+ * 🚨 **Zero skills validated is an ERROR, not a clean run.** `skills.include`
+ * globs that discover nothing — a typo, a renamed directory, an `exclude` that
+ * swallows every match — used to take an early return that printed one info
+ * line and published NO document at exit 0, and `vat validate` folded that into
+ * `status: success`: the gate the docs name as THE gate, green forever on a
+ * config that checked nothing. `vat verify` refused the identical config in its
+ * `packaged-content` phase and its message sent the operator to this command,
+ * which then said nothing.
+ *
+ * 🔑 The ONE seam both channels read. {@link buildValidateSummary} (the
+ * document) and {@link formatValidationReportLines} (stderr) both derive their
+ * issue set here, so "denominator zero, status clean" is unrepresentable on
+ * either channel rather than merely unwritten, and the exit code — derived from
+ * the document's own counts — agrees with both by construction. Through the
+ * shared mechanism in `run-integrity.ts`: one non-overridable
+ * `RESOURCE_CHECK_BROKEN` at `error`.
+ *
+ * Only the empty GLOB is refused. A config with no `skills:` block at all is a
+ * choice — the project declares no skills — and both orchestrators already skip
+ * this phase on that config; the phase declines it the same way (no document,
+ * exit 0) rather than inventing a refusal for a gate nobody declared.
+ *
+ * @param results - One result per skill the run validated: the denominator
+ * @param runIssues - The run's own findings so far (`ALLOW_UNUSED`), so an
+ *   existing run-integrity report is not duplicated
+ * @param patterns - The discovery globs, named in the refusal so the operator
+ *   sees what matched nothing
+ * @returns The run-level issues the document and the stderr report publish
+ */
+export function withRunIntegrity(results, runIssues, patterns) {
+    return [
+        ...nothingCheckedFinding(results.length, runIssues, () => nothingDiscoveredMessage(patterns)),
+        ...runIssues,
+    ];
+}
+/** The globs as an operator wrote them, back-quoted and comma-separated. */
+function quoteGlobs(globs) {
+    return globs.map((glob) => `\`${glob}\``).join(', ');
+}
+/** What did not run, and what the operator can do — invariant 5 of `run-integrity.ts`. */
+function nothingDiscoveredMessage(patterns) {
+    const include = quoteGlobs(patterns.include);
+    const exclude = patterns.exclude === undefined || patterns.exclude.length === 0
+        ? ''
+        : ` after \`skills.exclude\` (${quoteGlobs(patterns.exclude)})`;
+    return 'vat skills validate validated 0 skills, so this run is not a verdict: nothing was checked,'
+        + ' and the document reads the same as a run over clean skills. The `skills.include` globs in'
+        + ` vibe-agent-toolkit.config.yaml (${include}) matched no SKILL.md${exclude} — usually a typo`
+        + ' in the glob, a renamed directory, or an exclude that swallows every match. Fix the patterns'
+        + ' so they discover the skills this project ships, or remove the `skills:` block if it ships'
+        + ' none.';
+}
 /**
  * One skill's VERBOSE YAML entry: the whole result plus the per-severity counts
  * its two-valued `status` cannot express.
@@ -111,12 +171,18 @@ function toSummaryYamlResult(result) {
  * zeros: `issueCounts` and `runIssueCounts` keep their complete
  * `{errors, warnings, info}` shape in both modes, because they are the
  * reconciliation identity rather than something a reader scans.
+ *
+ * A run over ZERO skills is refused here, not passed — see
+ * {@link withRunIntegrity}, which is why the discovery `patterns` are a
+ * parameter of a document builder: the refusal names the globs that matched
+ * nothing, and the builder is where the refusal is derived.
  */
-export function buildValidateSummary(results, duration, verbose, runIssues) {
+export function buildValidateSummary(results, duration, verbose, runIssues, patterns) {
     const skillIssues = batchIssues(results);
-    const runIssueCounts = countBySeverity(runIssues);
+    const published = withRunIntegrity(results, runIssues, patterns);
+    const runIssueCounts = countBySeverity(published);
     return {
-        status: calculateValidationStatus([...skillIssues, ...runIssues]),
+        status: calculateValidationStatus([...skillIssues, ...published]),
         issueCounts: sumSeverityCounts([countBySeverity(skillIssues), runIssueCounts]),
         runIssueCounts,
         // `skillsValidated` stays the true denominator even though the default
@@ -136,16 +202,15 @@ export function buildValidateSummary(results, duration, verbose, runIssues) {
         results: verbose
             ? results.map((r) => toVerboseYamlResult(r))
             : results.filter((r) => hasFindings(r)).map((r) => toSummaryYamlResult(r)),
-        runIssues: [...runIssues],
+        runIssues: published,
         durationSecs: formatDurationSecs(duration),
     };
 }
 /**
  * Output YAML summary to stdout
  */
-function outputYamlSummary(results, duration, verbose, runIssues) {
-    const output = buildValidateSummary(results, duration, verbose, runIssues);
-    console.log(yaml.stringify(output, { indent: 2, lineWidth: 0, aliasDuplicateObjects: false }));
+function writeYamlSummary(summary) {
+    console.log(yaml.stringify(summary, { indent: 2, lineWidth: 0, aliasDuplicateObjects: false }));
 }
 /**
  * ONE line for one skill: its severity breakdown, its allowed count, and the
@@ -226,7 +291,7 @@ const STATUS_GLYPHS = {
  * expected pre-build state and must not fail CI); only the claim was wrong. It
  * is dropped rather than made conditional because the code registry carries no
  * build-blocking fact to condition it on — `CodeRegistryEntry` in
- * agent-schema/src/validation-codes.ts is exactly `defaultSeverity` /
+ * schema/src/validation-codes.ts is exactly `defaultSeverity` /
  * `description` / `fix` / `reference` — and keying the claim
  * on a hardcoded list of code names would assert a cause this renderer cannot
  * observe, and would go stale the next time a code is added.
@@ -259,9 +324,14 @@ function reportBanner(status, counts) {
  * Run-level findings and the banner are printed in full either way — there are
  * ~14 of the former, and they belong to the project config rather than to any
  * asset, so there is no row for them to collapse into.
+ *
+ * Reads the same seam as the document builder ({@link withRunIntegrity}), so a
+ * run over zero skills prints the refusal here too rather than a green banner
+ * over a document that says `error`.
  */
-export function formatValidationReportLines(results, runIssues, verbose) {
-    const issues = [...batchIssues(results), ...runIssues];
+export function formatValidationReportLines(results, runIssues, verbose, patterns) {
+    const published = withRunIntegrity(results, runIssues, patterns);
+    const issues = [...batchIssues(results), ...published];
     const counts = countBySeverity(issues);
     const status = calculateValidationStatus(issues);
     const lines = [reportBanner(status, counts)];
@@ -270,7 +340,7 @@ export function formatValidationReportLines(results, runIssues, verbose) {
             continue;
         lines.push(...skillReportLines(result, verbose));
     }
-    const runLines = formatRunIssueLines(runIssues);
+    const runLines = formatRunIssueLines(published);
     if (runLines.length > 0) {
         lines.push(...runLines, '');
     }
@@ -279,8 +349,7 @@ export function formatValidationReportLines(results, runIssues, verbose) {
 /**
  * Output validation report to stdout (YAML) and stderr (human-readable)
  */
-function outputValidationReport(results, duration, logger, verbose, runIssues) {
-    outputYamlSummary(results, duration, verbose, runIssues);
+function reportValidationToStderr(results, logger, verbose, runIssues, patterns) {
     // Collect all emitted codes across skills (both errors and warnings) to drive the footer
     const emittedCodes = new Set();
     for (const r of results) {
@@ -288,11 +357,11 @@ function outputValidationReport(results, duration, logger, verbose, runIssues) {
             emittedCodes.add(issue.code);
         }
     }
-    for (const issue of runIssues) {
+    for (const issue of withRunIntegrity(results, runIssues, patterns)) {
         emittedCodes.add(issue.code);
     }
     const hasSkillFindings = results.some((r) => calculateValidationStatus(r.allErrors) !== 'success');
-    for (const line of formatValidationReportLines(results, runIssues, verbose)) {
+    for (const line of formatValidationReportLines(results, runIssues, verbose, patterns)) {
         logger.info(line);
     }
     renderSkillQualityFooter(logger, hasSkillFindings, emittedCodes);
@@ -326,30 +395,61 @@ function logSkillProgress(skillName, result, logger) {
     }
 }
 /**
- * Build a single shared validation context for an entire `vat skills validate`
- * invocation.
+ * The markdown-only, link-resolved registry `vat skills validate` shares across
+ * every skill in one invocation.
  *
- * When every skill in the batch resolves to the same projectRoot (the normal
- * monorepo case), we crawl the resource registry once and hand the same
- * instance to each skill's validation — the per-skill markdown reparse
- * disappears. Similarly, gitignore checks are backed by a single
- * {@link GitTracker} when every skill sits inside the same git repository.
+ * Exported and named because it had two implementations: this one, and a
+ * restatement inside `pipeline-oracles/lanes.ts` whose own comment recorded that
+ * it was "the one lane with no reusable builder to point at". A copy of a
+ * registry builder is a copy of its ARGUMENTS, and the argument that matters
+ * here is `config` — see {@link SkillsValidateRegistryOptions.config}.
  *
- * When the batch is heterogeneous (e.g. multiple projectRoots), the helper
- * returns an empty context and validators transparently fall back to their
- * legacy per-skill setup — correctness first, perf second.
+ * @param projectRoot - Root every skill in the batch resolves to
+ * @param options - The governing config, and optionally the projection-backed
+ *   enumeration to build from
+ * @returns A crawled registry whose links are already resolved
  */
-async function buildSharedValidationContext(skills, projectSkills, logger) {
+export async function buildSkillsValidateRegistry(projectRoot, options = {}) {
+    const { config, populationSource } = options;
+    const registry = await ResourceRegistry.fromCrawl({
+        baseDir: projectRoot,
+        include: ['**/*.md'],
+        // `vat skills validate` acts on this registry as the whole population: a
+        // directory it cannot list refuses the run by name, exit 2.
+        unreadable: 'refuse',
+        ...(populationSource !== undefined && { populationSource }),
+    }, config === undefined ? undefined : { config });
+    registry.resolveLinks();
+    return registry;
+}
+export async function buildSharedValidationContext(skills, projectSkills, config, logger) {
     // The allow-entry ledger is not an optimization like the two below — it is
     // what makes ALLOW_UNUSED true. `validation.allow` is declared once for the
     // package and matched per skill, so only the batch can say an entry matched
     // nothing. Always present, so no early return can drop it.
     const allowLedger = createAllowUsageLedger();
+    // The RUN's conventional-suite probe, and it belongs beside the ledger rather
+    // than with the two optimizations below: resolving a skill's test input probes
+    // `<skill-root>/evals/evals.json` for the subject AND for every entry in
+    // `projectSkills`, so a probe minted per skill asks S questions per skill and
+    // S² per run about the same S paths. Measured with the lab on a 103-skill
+    // adopter: 10,815 probes over 103 distinct paths, half the command's entire
+    // filesystem traffic; with the run's probe threaded, ~103.
+    //
+    // Created here, once, and handed to every skill in the batch — that is the
+    // whole contract of `SkillValidationSharedContext.suiteProbe`, whose fallback
+    // (`?? conventionalSuiteProbe()`) treats an omitting caller as claiming ITS
+    // call is the whole run. This lane loops, so omitting it made that claim
+    // falsely and silently.
+    //
+    // NOT module-scoped: the answer is a filesystem snapshot, and a cache
+    // outliving the run keeps answering for a tree that has since changed.
+    const suiteProbe = conventionalSuiteProbe();
     // Likewise not an optimization: the test-input rule is project-wide, so this
     // lane must model a bundle that excludes EVERY declared suite, not just the
     // subject's. Present even for an empty batch, so no early return can drop it.
     if (skills.length === 0) {
-        return { allowLedger, projectSkills };
+        return { allowLedger, projectSkills, suiteProbe, unreadable: 'refuse' };
     }
     const projectRoots = new Set();
     const gitRoots = new Set();
@@ -367,27 +467,15 @@ async function buildSharedValidationContext(skills, projectSkills, logger) {
             gitRoots.add(safePath.resolve(gitRoot));
         }
     }
-    const context = { allowLedger, projectSkills };
-    // Only reuse a single registry when every skill shares the same project
-    // root. Otherwise the per-skill fallback path is correct and the cost is
-    // unchanged from the pre-refactor baseline.
-    if (projectRoots.size === 1) {
-        const [sharedRoot] = [...projectRoots];
-        if (sharedRoot !== undefined) {
-            logger.debug(`Building shared resource registry rooted at: ${sharedRoot}`);
-            const registry = await ResourceRegistry.fromCrawl({
-                baseDir: sharedRoot,
-                include: ['**/*.md'],
-            });
-            registry.resolveLinks();
-            context.registry = registry;
-        }
-    }
-    else {
-        logger.debug(`Skipping shared registry — batch spans ${projectRoots.size} project roots`);
-    }
+    const context = { allowLedger, projectSkills, suiteProbe, unreadable: 'refuse' };
     // One tracker per repo; when the batch spans repos, skip rather than spawn
     // multiple `git ls-files`.
+    //
+    // Built BEFORE the registry, which is the one ordering constraint in this
+    // function: the projection lane below needs an ignore oracle, and without one
+    // every realization row reads `gitignored: false` — so the population would
+    // admit the ignored half of the tree and this command would start validating
+    // generated markdown. Nothing else here depends on the order.
     if (gitRoots.size === 1) {
         const [sharedGitRoot] = [...gitRoots];
         if (sharedGitRoot !== undefined) {
@@ -400,12 +488,63 @@ async function buildSharedValidationContext(skills, projectSkills, logger) {
     else if (gitRoots.size > 1) {
         logger.debug(`Skipping shared tracker — batch spans ${gitRoots.size} git roots`);
     }
+    // Only reuse a single registry when every skill shares the same project
+    // root. Otherwise the per-skill fallback path is correct and the cost is
+    // unchanged from the pre-refactor baseline.
+    if (projectRoots.size === 1) {
+        const [sharedRoot] = [...projectRoots];
+        if (sharedRoot !== undefined) {
+            logger.debug(`Building shared resource registry rooted at: ${sharedRoot}`);
+            // The lane, and the store that answers it, bracket the crawl and nothing
+            // else: the source is called from inside `fromCrawl` and nowhere after it.
+            // `include` is unchanged either way — `ResourceRegistry.crawl` re-applies
+            // it to whatever the source offers, so this stays a markdown-only registry
+            // on both lanes.
+            const registry = await withResourcePopulationSource({ root: sharedRoot, gitTracker: context.gitTracker }, async (populationSource) => {
+                logger.debug(populationSource
+                    ? `Enumerating via the projection lane (${RESOURCES_CRAWL_ENV}=${RESOURCES_CRAWL_PROJECTION})`
+                    : `Enumerating via the incumbent walk (${RESOURCES_CRAWL_ENV} unset)`);
+                return buildSkillsValidateRegistry(sharedRoot, {
+                    // The command's OWN config, not a second read of the same file. It
+                    // governs `sharedRoot` by construction: this command exits early
+                    // without a config at `cwd`, every skill is discovered relative to
+                    // `cwd`, and `findProjectRoot` stops at the nearest config — so the
+                    // root every skill agrees on IS the root this config was loaded
+                    // from. Withholding it routes parsing by the extension tables while
+                    // the projection behind `populationSource` routes by the declared
+                    // `mimeType`, and the two then disagree about which files are prose.
+                    config,
+                    ...(populationSource !== undefined && { populationSource }),
+                });
+            });
+            context.registry = registry;
+        }
+    }
+    else {
+        logger.debug(`Skipping shared registry — batch spans ${projectRoots.size} project roots`);
+    }
     return context;
 }
 /**
- * Skills validate command implementation
+ * Validate every configured skill and hand back the document and exit code,
+ * printing the document nowhere.
+ *
+ * The phase entry point for `vat validate` and `vat verify`. The one early
+ * return publishes NO document: a config with no `skills:` block prints one
+ * info line, exits 0, and `phaseResultFromOutcome` records that as `success`
+ * with no `report` — both orchestrators skip the phase on that config anyway,
+ * because declaring no skills is a choice.
+ *
+ * A `skills:` block whose globs discover nothing is NOT a second early return.
+ * It used to be — one info line, no document, exit 0 — and that made `vat
+ * validate` green forever on a typo'd glob. It now runs through the same
+ * builder as a populated batch, which refuses a zero denominator (see
+ * {@link withRunIntegrity}): a document with one `RESOURCE_CHECK_BROKEN` at
+ * `error`, `status: error`, exit 1. Exit 1 and not 2, deliberately: the run
+ * completed and the gate FAILED, which is the class an operator's CI already
+ * handles; 2 is for a run that could not answer at all.
  */
-export async function validateCommand(pathArg, options) {
+export async function runSkillsValidatePhase(pathArg, options) {
     const { logger, cwd, startTime } = setupCommandContext(pathArg, options.debug);
     try {
         // Spec §7: `vat skills validate` requires a projectRoot — fails fast at
@@ -417,14 +556,16 @@ export async function validateCommand(pathArg, options) {
         const config = loadConfig(cwd);
         if (!config?.skills) {
             logger.info('No skills section in config yaml — nothing to validate');
-            process.exit(0);
-        }
-        // Discover skills from config yaml (relative to cwd where config lives)
-        const discovered = await discoverSkillsFromConfig(config.skills, cwd);
-        if (discovered.length === 0) {
-            logger.info('ℹ️  No skills found matching config yaml skills.include patterns');
-            process.exit(0);
+            return { document: undefined, exitCode: 0 };
         }
+        // Discover skills from config yaml (relative to cwd where config lives).
+        // `'refuse'`: one fewer skill at exit 0 is the drop this command must not
+        // make. The throw lands in the catch below → `reportCommandError`, exit 2.
+        const discovered = await discoverSkillsFromConfig(config.skills, cwd, 'refuse');
+        // No early return on `discovered.length === 0` — see the function comment.
+        // The empty batch flows through every step below unchanged: the shared
+        // context is built for zero skills (its ledger and probe exist regardless),
+        // the loop runs zero times, and the builder refuses the zero denominator.
         // Merge packaging config for each skill.
         const { defaults, config: perSkillConfig } = config.skills;
         const validatableSkills = discovered.map(skill => ({
@@ -441,7 +582,7 @@ export async function validateCommand(pathArg, options) {
         // Every declared skill, not just `skillsToValidate`: `--skill x` narrows what is
         // REPORTED on, never what counts as some skill's declared test input.
         const projectSkills = collectDeclaredEvalSuites(config.skills, discovered);
-        const sharedContext = await buildSharedValidationContext(skillsToValidate, projectSkills, logger);
+        const sharedContext = await buildSharedValidationContext(skillsToValidate, projectSkills, config, logger);
         // Validate each skill
         const results = [];
         for (const skill of skillsToValidate) {
@@ -461,16 +602,32 @@ export async function validateCommand(pathArg, options) {
         const runIssues = sharedContext.allowLedger === undefined
             ? []
             : allowUnusedIssues(sharedContext.allowLedger);
-        // Output report and exit
         const duration = Date.now() - startTime;
         const verbose = options.verbose === true;
-        outputValidationReport(results, duration, logger, verbose, runIssues);
-        const hasErrors = results.some(r => r.status === 'error')
-            || runIssues.some(i => i.severity === 'error');
-        process.exit(hasErrors ? 1 : 0);
+        const document = buildValidateSummary(results, duration, verbose, runIssues, config.skills);
+        reportValidationToStderr(results, logger, verbose, runIssues, config.skills);
+        // The exit code is read off the DOCUMENT, not recomputed beside it, so the
+        // two cannot disagree: whatever the builder refused, the process refuses.
+        // `issueCounts.errors` counts an active error on any skill and every
+        // run-level error alike — including the zero-denominator refusal.
+        return { document, exitCode: document.issueCounts.errors > 0 ? 1 : 0 };
     }
     catch (error) {
-        handleCommandError(error, logger, startTime, 'SkillsValidate');
+        return {
+            document: reportCommandError(error, logger, startTime, 'SkillsValidate'),
+            exitCode: 2,
+            failed: true,
+        };
     }
 }
+/**
+ * Skills validate command implementation
+ */
+export async function validateCommand(pathArg, options) {
+    // `undefined`: this command offers no `--format`, so its failure envelope is
+    // YAML like its report.
+    finishCommand(await runSkillsValidatePhase(pathArg, options), (document) => {
+        writeYamlSummary(document);
+    }, undefined);
+}
 //# sourceMappingURL=validate.js.map