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

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

@@ -8,67 +8,177 @@
  * `okf.bundles.<name>.severity`; the finding is still reported either way.
  */
 import { type OkfBundleReport } from '@vibe-agent-toolkit/resources';
-import type { SeverityCounts } from '@vibe-agent-toolkit/schema';
+import { type Report } from '@vibe-agent-toolkit/schema';
+import { z } from 'zod';
 export interface OkfValidateOptions {
     format?: 'yaml' | 'json';
     specVersion?: string;
     debug?: boolean;
 }
+/** One checked bundle's `data` row: what was read, never the findings (those are the envelope's). */
+export declare const OkfBundleSummarySchema: z.ZodObject<{
+    /** The `okf.bundles.<name>` key. */
+    bundle: z.ZodString;
+    /** The root as the config file wrote it — never the resolved absolute path. */
+    root: z.ZodString;
+    /** Every non-reserved `.md` beneath the root, bundle-relative and sorted. */
+    conceptDocuments: z.ZodArray<z.ZodString, "many">;
+    /** Every `index.md` / `log.md` beneath the root, bundle-relative and sorted. */
+    reservedDocuments: z.ZodArray<z.ZodString, "many">;
+    /** What the root `index.md` declares, when it declares a well-formed one. Reported, never obeyed. */
+    declaredOkfVersion: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    root: string;
+    bundle: string;
+    conceptDocuments: string[];
+    reservedDocuments: string[];
+    declaredOkfVersion?: string | undefined;
+}, {
+    root: string;
+    bundle: string;
+    conceptDocuments: string[];
+    reservedDocuments: string[];
+    declaredOkfVersion?: string | undefined;
+}>;
+export declare const OkfValidateDataSchema: z.ZodObject<{
+    bundles: z.ZodArray<z.ZodObject<{
+        /** The `okf.bundles.<name>` key. */
+        bundle: z.ZodString;
+        /** The root as the config file wrote it — never the resolved absolute path. */
+        root: z.ZodString;
+        /** Every non-reserved `.md` beneath the root, bundle-relative and sorted. */
+        conceptDocuments: z.ZodArray<z.ZodString, "many">;
+        /** Every `index.md` / `log.md` beneath the root, bundle-relative and sorted. */
+        reservedDocuments: z.ZodArray<z.ZodString, "many">;
+        /** What the root `index.md` declares, when it declares a well-formed one. Reported, never obeyed. */
+        declaredOkfVersion: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        root: string;
+        bundle: string;
+        conceptDocuments: string[];
+        reservedDocuments: string[];
+        declaredOkfVersion?: string | undefined;
+    }, {
+        root: string;
+        bundle: string;
+        conceptDocuments: string[];
+        reservedDocuments: string[];
+        declaredOkfVersion?: string | undefined;
+    }>, "many">;
+    /**
+     * Present only when there was nothing to check, and says what to declare or
+     * which root to look at.
+     *
+     * 🪤 The command used to print `status: passed`, `bundles: []`, exit 0 when a
+     * project declared no `okf.bundles` at all — a report indistinguishable from
+     * a bundle read in full and found conformant, so a mistyped key
+     * (`okf.bundle:`, `okf.Bundles:`) read as a clean bill of health. The
+     * envelope's REQUIRED `examined` now says `0` in that case, and this sentence
+     * says why. The exit code stays 0: nothing failed, and failing a build for a
+     * feature the project never opted into would be worse.
+     */
+    notice: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    bundles: {
+        root: string;
+        bundle: string;
+        conceptDocuments: string[];
+        reservedDocuments: string[];
+        declaredOkfVersion?: string | undefined;
+    }[];
+    notice?: string | undefined;
+}, {
+    bundles: {
+        root: string;
+        bundle: string;
+        conceptDocuments: string[];
+        reservedDocuments: string[];
+        declaredOkfVersion?: string | undefined;
+    }[];
+    notice?: string | undefined;
+}>;
+export type OkfBundleSummary = z.infer<typeof OkfBundleSummarySchema>;
+export type OkfValidateData = z.infer<typeof OkfValidateDataSchema>;
 /** The document this command publishes. */
-interface OkfValidateReport {
-    status: OkfValidateStatus;
-    bundles: OkfBundleReport[];
-    findingCount: number;
-    issueCounts: SeverityCounts;
-    /** Present only when there was nothing to check; says what to declare. */
-    notice?: string;
-}
-/**
- * `no-bundles` is a third word on purpose, and it is not cosmetic.
- *
- * 🪤 This command used to print `status: passed`, `bundles: []`, exit 0 when a
- * project declared no `okf.bundles` at all — a report indistinguishable from a
- * bundle that was read in full and found conformant. A mistyped key
- * (`okf.bundle:`, `okf.Bundles:`) therefore reads as a clean bill of health,
- * which is the *green-without-running* shape this repo keeps rediscovering.
- *
- * `vat resources check` already answers the identical situation properly — "No
- * checks are declared. Add them under `resources.checks` …" — so this follows a
- * convention the repo holds rather than inventing one.
- *
- * The exit code stays 0: nothing failed, and failing a build for a feature the
- * project never opted into would be worse. It is the status *word* that must not
- * claim a pass, because that word is what a human and a CI log actually read.
- */
-export type OkfValidateStatus = 'passed' | 'failed' | 'no-bundles';
-/** The summary half of the report: pure, so the status rule is testable. */
-export interface OkfValidateSummary {
-    status: OkfValidateStatus;
-    findingCount: number;
+export declare const OKF_VALIDATE_REPORT_SCHEMA: import("@vibe-agent-toolkit/schema").ReportZodSchema<z.ZodObject<{
+    bundles: z.ZodArray<z.ZodObject<{
+        /** The `okf.bundles.<name>` key. */
+        bundle: z.ZodString;
+        /** The root as the config file wrote it — never the resolved absolute path. */
+        root: z.ZodString;
+        /** Every non-reserved `.md` beneath the root, bundle-relative and sorted. */
+        conceptDocuments: z.ZodArray<z.ZodString, "many">;
+        /** Every `index.md` / `log.md` beneath the root, bundle-relative and sorted. */
+        reservedDocuments: z.ZodArray<z.ZodString, "many">;
+        /** What the root `index.md` declares, when it declares a well-formed one. Reported, never obeyed. */
+        declaredOkfVersion: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        root: string;
+        bundle: string;
+        conceptDocuments: string[];
+        reservedDocuments: string[];
+        declaredOkfVersion?: string | undefined;
+    }, {
+        root: string;
+        bundle: string;
+        conceptDocuments: string[];
+        reservedDocuments: string[];
+        declaredOkfVersion?: string | undefined;
+    }>, "many">;
     /**
-     * The severity distribution, published BESIDE the status rather than folded
-     * into it.
+     * Present only when there was nothing to check, and says what to declare or
+     * which root to look at.
      *
-     * Load-bearing here specifically because OKF severity is adopter-configurable
-     * per bundle (`okf.bundles.<name>.severity`). A project that lowers a bundle
-     * to `warning` gets `status: passed` and exit 0 for a bundle carrying real
-     * conformance findings — correct, and completely opaque from the status word
-     * alone. The distribution is the only thing in the report that distinguishes
-     * "nothing was found" from "everything found was downgraded".
+     * 🪤 The command used to print `status: passed`, `bundles: []`, exit 0 when a
+     * project declared no `okf.bundles` at all — a report indistinguishable from
+     * a bundle read in full and found conformant, so a mistyped key
+     * (`okf.bundle:`, `okf.Bundles:`) read as a clean bill of health. The
+     * envelope's REQUIRED `examined` now says `0` in that case, and this sentence
+     * says why. The exit code stays 0: nothing failed, and failing a build for a
+     * feature the project never opted into would be worse.
      */
-    issueCounts: SeverityCounts;
-    notice?: string;
+    notice: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    bundles: {
+        root: string;
+        bundle: string;
+        conceptDocuments: string[];
+        reservedDocuments: string[];
+        declaredOkfVersion?: string | undefined;
+    }[];
+    notice?: string | undefined;
+}, {
+    bundles: {
+        root: string;
+        bundle: string;
+        conceptDocuments: string[];
+        reservedDocuments: string[];
+        declaredOkfVersion?: string | undefined;
+    }[];
+    notice?: string | undefined;
+}>>;
+export type OkfValidateReport = Report<OkfValidateData>;
+/** One bundle's report beside the absolute root it was read from. */
+export interface CheckedOkfBundle {
+    readonly report: OkfBundleReport;
+    /** The resolved absolute root, so a finding can name a project-relative file. */
+    readonly root: string;
 }
 /**
- * Decide the status word and the counts for a set of bundle reports.
+ * Assemble the report for a set of checked bundles. Pure, so the status rule
+ * and the denominator are unit-testable.
+ *
+ * `examined` counts every document that was opened and judged — concept and
+ * reserved alike — across every bundle. A declared-but-empty bundle and an
+ * empty declaration both examine zero, and the notice tells them apart.
  *
- * @param bundles - One report per bundle that was actually checked
- * @returns The status, the finding count and severity distribution, and a
- *   notice when nothing was declared or a declared bundle held nothing
+ * @param checked - One report per bundle that was actually checked, with its root
+ * @param projectRoot - What every finding's `location` is relative to
+ * @returns The report
  */
-export declare function summarizeOkfBundles(bundles: readonly OkfBundleReport[]): OkfValidateSummary;
+export declare function summarizeOkfBundles(checked: readonly CheckedOkfBundle[], projectRoot: string): OkfValidateReport;
 /**
- * Assemble the report for every selected bundle.
+ * Check every selected bundle and assemble the report.
  *
  * Separate from the action so the shape is testable without a process exit.
  *
@@ -78,5 +188,4 @@ export declare function summarizeOkfBundles(bundles: readonly OkfBundleReport[])
 export declare function okfValidateReport(bundleArg: string | undefined, options: OkfValidateOptions): Promise<OkfValidateReport>;
 /** Action handler for `vat okf validate [bundle]`. */
 export declare function okfValidateCommand(bundleArg: string | undefined, options: OkfValidateOptions): Promise<void>;
-export {};
 //# sourceMappingURL=validate.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../src/commands/okf/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAOjE,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,2CAA2C;AAC3C,UAAU,iBAAiB;IACzB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,cAAc,CAAC;IAC5B,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,QAAQ,GAAG,YAAY,CAAC;AAEnE,4EAA4E;AAC5E,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,iBAAiB,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;;;;;;OAUG;IACH,WAAW,EAAE,cAAc,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAuED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,GAAG,kBAAkB,CA2B3F;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,iBAAiB,CAAC,CAkB5B;AAED,sDAAsD;AACtD,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAkBf"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../src/commands/okf/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAsE,KAAK,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAE7H,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,qGAAqG;AACrG,eAAO,MAAM,sBAAsB;IACjC,oCAAoC;;IAEpC,+EAA+E;;IAE/E,6EAA6E;;IAE7E,gFAAgF;;IAEhF,qGAAqG;;;;;;;;;;;;;;EAE5F,CAAC;AAEZ,eAAO,MAAM,qBAAqB;;QAZhC,oCAAoC;;QAEpC,+EAA+E;;QAE/E,6EAA6E;;QAE7E,gFAAgF;;QAEhF,qGAAqG;;;;;;;;;;;;;;;IAMrG;;;;;;;;;;;OAWG;;;;;;;;;;;;;;;;;;;;EAEM,CAAC;AAEZ,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AACtE,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,2CAA2C;AAC3C,eAAO,MAAM,0BAA0B;;QAjCrC,oCAAoC;;QAEpC,+EAA+E;;QAE/E,6EAA6E;;QAE7E,gFAAgF;;QAEhF,qGAAqG;;;;;;;;;;;;;;;IAMrG;;;;;;;;;;;OAWG;;;;;;;;;;;;;;;;;;;;GAQwE,CAAC;AAE9E,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,eAAe,CAAC,CAAC;AAExD,qEAAqE;AACrE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,iFAAiF;IACjF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AA8ED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,SAAS,gBAAgB,EAAE,EACpC,WAAW,EAAE,MAAM,GAClB,iBAAiB,CAyBnB;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,iBAAiB,CAAC,CAmB5B;AAED,sDAAsD;AACtD,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAcf"}

package/dist/commands/okf/validate.js

@@ -9,48 +9,50 @@
  */
 import { dirname } from 'node:path';
 import { okfBundleRuns, parseConfigFile, validateOkfBundle, } from '@vibe-agent-toolkit/resources';
-import { findConfigFile } from '@vibe-agent-toolkit/utils';
-import { handleCommandError } from '../../utils/command-error.js';
+import { buildReport, exitCodeForSeverityCounts, reportSchema } from '@vibe-agent-toolkit/schema';
+import { findConfigFile, issueLocation, safePath } from '@vibe-agent-toolkit/utils';
+import { z } from 'zod';
+import { handleReportCommandError } from '../../utils/command-error.js';
 import { createLogger } from '../../utils/logger.js';
-import { writeJsonOutput, writeYamlOutput } from '../../utils/output.js';
-/**
- * Count one bundle set's findings by severity.
- *
- * Not `countBySeverity` from `@vibe-agent-toolkit/schema`: that takes
- * `ValidationIssue[]`, whose `code` is the shared `IssueCode` registry union,
- * and an OKF finding's code is drawn from the specification's own vocabulary
- * rather than that registry. The counts field is still typed as the shared
- * `SeverityCounts`, so the SHAPE stays checked against the canonical one and a
- * bucket cannot be added, renamed or dropped here alone.
- *
- * @param findings - Every finding across every bundle that was checked
- * @returns The per-severity distribution
- */
-function countOkfFindings(findings) {
-    let errors = 0;
-    let warnings = 0;
-    let info = 0;
-    for (const finding of findings) {
-        if (finding.severity === 'error') {
-            errors += 1;
-        }
-        else if (finding.severity === 'warning') {
-            warnings += 1;
-        }
-        else {
-            info += 1;
-        }
-    }
-    return { errors, warnings, info };
-}
+import { writeStructuredOutput } from '../../utils/output.js';
+/** One checked bundle's `data` row: what was read, never the findings (those are the envelope's). */
+export const OkfBundleSummarySchema = z.object({
+    /** The `okf.bundles.<name>` key. */
+    bundle: z.string(),
+    /** The root as the config file wrote it — never the resolved absolute path. */
+    root: z.string(),
+    /** Every non-reserved `.md` beneath the root, bundle-relative and sorted. */
+    conceptDocuments: z.array(z.string()),
+    /** Every `index.md` / `log.md` beneath the root, bundle-relative and sorted. */
+    reservedDocuments: z.array(z.string()),
+    /** What the root `index.md` declares, when it declares a well-formed one. Reported, never obeyed. */
+    declaredOkfVersion: z.string().optional(),
+}).strict();
+export const OkfValidateDataSchema = z.object({
+    bundles: z.array(OkfBundleSummarySchema),
+    /**
+     * Present only when there was nothing to check, and says what to declare or
+     * which root to look at.
+     *
+     * 🪤 The command used to print `status: passed`, `bundles: []`, exit 0 when a
+     * project declared no `okf.bundles` at all — a report indistinguishable from
+     * a bundle read in full and found conformant, so a mistyped key
+     * (`okf.bundle:`, `okf.Bundles:`) read as a clean bill of health. The
+     * envelope's REQUIRED `examined` now says `0` in that case, and this sentence
+     * says why. The exit code stays 0: nothing failed, and failing a build for a
+     * feature the project never opted into would be worse.
+     */
+    notice: z.string().optional(),
+}).strict();
+/** The document this command publishes. */
+export const OKF_VALIDATE_REPORT_SCHEMA = reportSchema(OkfValidateDataSchema);
 /**
  * The bundles whose root was read successfully and held not one markdown file.
  *
- * 🪤 The same green-without-running shape the `no-bundles` notice exists for,
- * one level down. A `root:` typo that lands on a real-but-wrong directory, or a
- * root written one level too deep, produces `status: passed`, exit 0 and an
- * empty findings list — a report indistinguishable from a bundle that was read
- * in full and found conformant.
+ * 🪤 The same green-without-running shape the `notice` exists for, one level
+ * down. A `root:` typo that lands on a real-but-wrong directory, or a root
+ * written one level too deep, produces zero findings and an `examined` that
+ * only THIS bundle's rows explain — so the run says so in words too.
  *
  * A bundle carrying findings is excluded even when its document lists are empty:
  * that is the unreadable-root case, which already says the truthful thing in its
@@ -79,38 +81,73 @@ function vacuousNotice(vacuous) {
     return `${named} contains no .md files, so nothing was checked in ${subject}. A root pointing one level too deep, or at a real-but-wrong directory, reads exactly like this — check \`okf.bundles.<name>.root\`.`;
 }
 /**
- * Decide the status word and the counts for a set of bundle reports.
+ * The sentence a run carries when it examined less than a reader would assume.
  *
- * @param bundles - One report per bundle that was actually checked
- * @returns The status, the finding count and severity distribution, and a
- *   notice when nothing was declared or a declared bundle held nothing
+ * @param bundles - Every bundle report in the run
+ * @returns The notice, or nothing when every declared bundle held documents
  */
-export function summarizeOkfBundles(bundles) {
-    const findings = bundles.flatMap((report) => report.findings);
-    const findingCount = findings.length;
-    const issueCounts = countOkfFindings(findings);
-    if (bundles.length === 0) {
-        return {
-            status: 'no-bundles',
-            findingCount,
-            issueCounts,
-            notice: 'No OKF bundles are declared, so nothing was checked. Declare one under `okf.bundles.<name>.root` in vibe-agent-toolkit.config.yaml; every non-reserved .md beneath that root is then checked for frontmatter carrying a non-empty `type`.',
-        };
-    }
-    // Status and exit code deliberately do NOT move: nothing failed, and failing a
-    // build over an empty directory would be worse than the silence. It is the
-    // report that must stop implying a bundle was read when it was not.
+function noticeFor(bundles) {
+    if (bundles.length === 0)
+        return NO_BUNDLES_NOTICE;
     const vacuous = vacuousBundles(bundles);
-    const status = issueCounts.errors > 0 ? 'failed' : 'passed';
+    return vacuous.length > 0 ? vacuousNotice(vacuous) : undefined;
+}
+const NO_BUNDLES_NOTICE = 'No OKF bundles are declared, so nothing was checked. Declare one under `okf.bundles.<name>.root` in vibe-agent-toolkit.config.yaml; every non-reserved .md beneath that root is then checked for frontmatter carrying a non-empty `type`.';
+/**
+ * A bundle's finding as the envelope publishes it: the same code, severity and
+ * message, with `location` the project-relative path of the document — the
+ * file you would open — rather than a bundle-relative `document` a reader had
+ * to join with the bundle's root by hand.
+ *
+ * @param finding - The lane's finding
+ * @param root - The bundle's absolute root
+ * @param projectRoot - What `location` is relative to
+ * @returns The published finding
+ */
+function toFinding(finding, root, projectRoot) {
     return {
-        status,
-        findingCount,
-        issueCounts,
-        ...(vacuous.length > 0 && { notice: vacuousNotice(vacuous) }),
+        code: finding.code,
+        severity: finding.severity,
+        message: finding.message,
+        location: issueLocation(safePath.join(root, finding.document), projectRoot),
+        ...(finding.link === undefined ? {} : { link: finding.link }),
+        ...(finding.line === undefined ? {} : { line: finding.line }),
     };
 }
 /**
- * Assemble the report for every selected bundle.
+ * Assemble the report for a set of checked bundles. Pure, so the status rule
+ * and the denominator are unit-testable.
+ *
+ * `examined` counts every document that was opened and judged — concept and
+ * reserved alike — across every bundle. A declared-but-empty bundle and an
+ * empty declaration both examine zero, and the notice tells them apart.
+ *
+ * @param checked - One report per bundle that was actually checked, with its root
+ * @param projectRoot - What every finding's `location` is relative to
+ * @returns The report
+ */
+export function summarizeOkfBundles(checked, projectRoot) {
+    const bundles = checked.map((entry) => entry.report);
+    const findings = checked.flatMap((entry) => entry.report.findings.map((finding) => toFinding(finding, entry.root, projectRoot)));
+    const examined = bundles.reduce((sum, report) => sum + report.conceptDocuments.length + report.reservedDocuments.length, 0);
+    const notice = noticeFor(bundles);
+    return buildReport({
+        examined,
+        findings,
+        data: {
+            bundles: bundles.map((report) => ({
+                bundle: report.bundle,
+                root: report.root,
+                conceptDocuments: report.conceptDocuments,
+                reservedDocuments: report.reservedDocuments,
+                ...(report.declaredOkfVersion === undefined ? {} : { declaredOkfVersion: report.declaredOkfVersion }),
+            })),
+            ...(notice === undefined ? {} : { notice }),
+        },
+    });
+}
+/**
+ * Check every selected bundle and assemble the report.
  *
  * Separate from the action so the shape is testable without a process exit.
  *
@@ -123,35 +160,31 @@ export async function okfValidateReport(bundleArg, options) {
         throw new Error('No vibe-agent-toolkit.config.yaml found. Run from a project directory.');
     }
     const config = await parseConfigFile(configPath);
-    const runs = okfBundleRuns(config.okf, dirname(configPath), {
+    const projectRoot = dirname(configPath);
+    const runs = okfBundleRuns(config.okf, projectRoot, {
         ...(bundleArg !== undefined && { bundle: bundleArg }),
         ...(options.specVersion !== undefined && { specVersion: options.specVersion }),
     });
-    const bundles = [];
+    const checked = [];
     for (const run of runs) {
-        bundles.push(await validateOkfBundle(run));
+        checked.push({ report: await validateOkfBundle(run), root: run.root });
     }
-    return { ...summarizeOkfBundles(bundles), bundles };
+    return summarizeOkfBundles(checked, projectRoot);
 }
 /** Action handler for `vat okf validate [bundle]`. */
 export async function okfValidateCommand(bundleArg, options) {
     const logger = createLogger(options.debug === true ? { debug: true } : {});
     const startTime = Date.now();
     try {
-        const report = await okfValidateReport(bundleArg, options);
-        if (options.format === 'json') {
-            writeJsonOutput(report);
-        }
-        else {
-            writeYamlOutput(report);
-        }
+        const report = { ...(await okfValidateReport(bundleArg, options)), durationMs: Date.now() - startTime };
+        writeStructuredOutput(report, options.format);
         // Read from the counts the report PUBLISHES, not from the status word: an
         // adopter who promotes or lowers a bundle's severity then gates on exactly
         // the number a reader can see.
-        process.exit(report.issueCounts.errors > 0 ? 1 : 0);
+        process.exit(exitCodeForSeverityCounts(report.summary));
     }
     catch (error) {
-        handleCommandError(error, logger, startTime, 'OKF validate', options.format);
+        handleReportCommandError(error, logger, startTime, 'OKF validate', options.format);
     }
 }
 //# sourceMappingURL=validate.js.map

package/dist/commands/okf/validate.js.map

@@ -1 +1 @@
-{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../../src/commands/okf/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EACL,aAAa,EACb,eAAe,EACf,iBAAiB,GAGlB,MAAM,+BAA+B,CAAC;AAEvC,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAE3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAwDzE;;;;;;;;;;;;GAYG;AACH,SAAS,gBAAgB,CAAC,QAA+B;IACvD,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;YACjC,MAAM,IAAI,CAAC,CAAC;QACd,CAAC;aAAM,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC1C,QAAQ,IAAI,CAAC,CAAC;QAChB,CAAC;aAAM,CAAC;YACN,IAAI,IAAI,CAAC,CAAC;QACZ,CAAC;IACH,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;AACpC,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,SAAS,cAAc,CAAC,OAAmC;IACzD,OAAO,OAAO;SACX,MAAM,CACL,CAAC,MAAM,EAAE,EAAE,CACT,MAAM,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC;QAC5B,MAAM,CAAC,gBAAgB,CAAC,MAAM,KAAK,CAAC;QACpC,MAAM,CAAC,iBAAiB,CAAC,MAAM,KAAK,CAAC,CACxC;SACA,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AACpC,CAAC;AAED;;;;;GAKG;AACH,SAAS,aAAa,CAAC,OAA0B;IAC/C,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,MAAM,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAChE,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC;IACrD,OAAO,GAAG,KAAK,qDAAqD,OAAO,sIAAsI,CAAC;AACpN,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAmC;IACrE,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC9D,MAAM,YAAY,GAAG,QAAQ,CAAC,MAAM,CAAC;IACrC,MAAM,WAAW,GAAG,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IAE/C,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO;YACL,MAAM,EAAE,YAAY;YACpB,YAAY;YACZ,WAAW;YACX,MAAM,EACJ,2OAA2O;SAC9O,CAAC;IACJ,CAAC;IAED,+EAA+E;IAC/E,2EAA2E;IAC3E,oEAAoE;IACpE,MAAM,OAAO,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;IACxC,MAAM,MAAM,GAAsB,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC;IAE/E,OAAO;QACL,MAAM;QACN,YAAY;QACZ,WAAW;QACX,GAAG,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,aAAa,CAAC,OAAO,CAAC,EAAE,CAAC;KAC9D,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,SAA6B,EAC7B,OAA2B;IAE3B,MAAM,UAAU,GAAG,cAAc,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IACjD,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CAAC,wEAAwE,CAAC,CAAC;IAC5F,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC,UAAU,CAAC,CAAC;IACjD,MAAM,IAAI,GAAG,aAAa,CAAC,MAAM,CAAC,GAAG,EAAE,OAAO,CAAC,UAAU,CAAC,EAAE;QAC1D,GAAG,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;QACrD,GAAG,CAAC,OAAO,CAAC,WAAW,KAAK,SAAS,IAAI,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,CAAC;KAC/E,CAAC,CAAC;IAEH,MAAM,OAAO,GAAsB,EAAE,CAAC;IACtC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,OAAO,CAAC,IAAI,CAAC,MAAM,iBAAiB,CAAC,GAAG,CAAC,CAAC,CAAC;IAC7C,CAAC;IAED,OAAO,EAAE,GAAG,mBAAmB,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,CAAC;AACtD,CAAC;AAED,sDAAsD;AACtD,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,SAA6B,EAC7B,OAA2B;IAE3B,MAAM,MAAM,GAAG,YAAY,CAAC,OAAO,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAC3E,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAE7B,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,iBAAiB,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QAC3D,IAAI,OAAO,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;YAC9B,eAAe,CAAC,MAAM,CAAC,CAAC;QAC1B,CAAC;aAAM,CAAC;YACN,eAAe,CAAC,MAAM,CAAC,CAAC;QAC1B,CAAC;QACD,0EAA0E;QAC1E,2EAA2E;QAC3E,+BAA+B;QAC/B,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACtD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,cAAc,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/E,CAAC;AACH,CAAC"}
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../../src/commands/okf/validate.ts"],"names":[],"mappings":"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"}

package/dist/commands/phase-utils.d.ts

@@ -1,7 +1,7 @@
 /**
  * Shared utilities for top-level phase orchestration commands (vat build, vat verify, vat validate).
  */
-import { type SeverityCounts } from '@vibe-agent-toolkit/schema';
+import { type ExitCodeValue, type SeverityCounts } from '@vibe-agent-toolkit/schema';
 import { type Command } from 'commander';
 import { createLogger } from '../utils/logger.js';
 /**
@@ -23,7 +23,7 @@ import { createLogger } from '../utils/logger.js';
  */
 export interface PhaseOutcome {
     document: unknown;
-    exitCode: number;
+    exitCode: ExitCodeValue;
     /**
      * The phase failed UNEXPECTEDLY, so `document` is the shared error envelope
      * (`{status, error, duration}`) rather than the command's own report.
@@ -106,7 +106,7 @@ export interface PhaseResult {
     name: string;
     status: PhaseStatus;
     /** The exit code the phase claimed for itself. */
-    exitCode?: number;
+    exitCode?: ExitCodeValue;
     /** Why the phase could not run at all (it threw past its own error handling). */
     error?: string;
     /**
@@ -226,9 +226,10 @@ export declare function worseOf(a: PhaseStatus, b: PhaseStatus): PhaseStatus;
  *
  * | exit code             | phase status   | why                                     |
  * |-----------------------|----------------|-----------------------------------------|
- * | 0                     | `success`      | ran, found nothing actionable           |
- * | 1                     | `error`        | ran, found validation errors            |
- * | 2 (or any other)      | `system-error` | the phase itself reported a system error |
+ * | `OK` (0)              | `success`      | ran, found nothing actionable           |
+ * | `FINDINGS` (1)        | `error`        | ran, found validation errors            |
+ * | `ERROR` (2)           | `system-error` | the phase itself reported a system error |
+ * | anything else         | throws         | a defect in the phase, filed by `runPhase` as `system-error` |
  *
  * The exit code is then reconciled with the phase's OWN reported `status`,
  * worst-wins. An exit code has three values and cannot express `warning`:
@@ -327,9 +328,9 @@ export declare function phaseIssueCounts(result: PhaseResult): SeverityCounts;
 export declare function aggregatePhaseIssueCounts(results: readonly PhaseResult[]): SeverityCounts;
 /**
  * The process exit code for a set of phase outcomes, per the exit-code contract
- * every orchestrator's help text documents: 0 pass, 1 validation failure,
- * 2 system error. Warnings do not fail a run — they are published in the status
- * and counts instead.
+ * every orchestrator's help text documents: `OK` pass, `FINDINGS` validation
+ * failure, `ERROR` system error. Warnings do not fail a run — they are
+ * published in the status and counts instead.
  */
-export declare function exitCodeForPhases(results: readonly PhaseResult[]): 0 | 1 | 2;
+export declare function exitCodeForPhases(results: readonly PhaseResult[]): ExitCodeValue;
 //# sourceMappingURL=phase-utils.d.ts.map

package/dist/commands/phase-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"phase-utils.d.ts","sourceRoot":"","sources":["../../src/commands/phase-utils.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"phase-utils.d.ts","sourceRoot":"","sources":["../../src/commands/phase-utils.ts"],"names":[],"mappings":"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"}