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

package/dist/utils/command-error.d.ts

@@ -1,12 +1,15 @@
 /**
  * Shared command error handling utilities.
  *
- * THE single implementation of each failure exit. `commands/skills/` used to
+ * The failure endings a command may take, each publishing a document and
+ * ending on one member of the `ExitCode` contract. `commands/skills/` used to
  * carry its own `handleCommandError` that logged to stderr and exited 2 having
  * written nothing to stdout — same name, same signature, same documented
- * contract, silently different behaviour. Every command family routes here.
+ * contract, silently different behaviour. A command that ends some other way
+ * still names its code from `ExitCode`; the lint rule
+ * `no-literal-process-exit` refuses a bare number.
  */
-import { type SeverityCounts, type ValidationIssue } from '@vibe-agent-toolkit/schema';
+import { type ExitCodeValue, type SeverityCounts, type ValidationIssue } from '@vibe-agent-toolkit/schema';
 import type { Logger } from './logger.js';
 /**
  * Format duration for human readability
@@ -14,25 +17,6 @@ import type { Logger } from './logger.js';
  * @returns Formatted duration string (e.g., "500ms", "1.5s", "1.5m")
  */
 export declare function formatDuration(ms: number): string;
-/**
- * Everything about a thrown value that `error.message` alone discards.
- *
- * Exit 2 is the UNEXPECTED failure — an internal bug, not a usage mistake — and
- * the one thing a reader needs there is the frame that threw. A real `TypeError`
- * arrived here as a single line (`Cannot read properties of undefined (reading
- * 'readdir')`) with no file, no frames, and no flag that would produce them; the
- * only way to find the throw site was to hand-patch the built `dist`. A value
- * thrown that is not an `Error` fared worse still — the envelope flattens it to
- * the literal string `Unknown error`, which names neither its type nor its
- * contents.
- *
- * The result rides the logger's **debug** channel (`--debug`), so default output
- * is unchanged and no golden moves.
- *
- * @param error - The value that was thrown
- * @returns Stack trace for an `Error`, or an inspected rendering of a non-`Error`
- */
-export declare function errorDiagnostics(error: unknown): string;
 /** The document a command publishes when an unexpected failure stops it. */
 export interface CommandErrorDocument {
     status: 'error';
@@ -63,8 +47,8 @@ export declare function reportCommandError(error: unknown, logger: Logger, start
 /**
  * Handle command error with standard formatting and exit.
  *
- * The command-line ending for {@link reportCommandError}. Exit 2 is the
- * UNEXPECTED failure, per the exit-code contract every command's help documents.
+ * The command-line ending for {@link reportCommandError}. `ExitCode.ERROR` is
+ * the UNEXPECTED failure, per the exit-code contract every command's help documents.
  *
  * 🔑 **`format` is not decoration.** Every command offering `--format json`
  * honoured it on the success path and emitted YAML here, so the one document a
@@ -82,6 +66,65 @@ export declare function reportCommandError(error: unknown, logger: Logger, start
  *   omitted) for YAML — matching the success path's own two-branch switch
  */
 export declare function handleCommandError(error: unknown, logger: Logger, startTime: number, commandName: string, format?: string | undefined): never;
+/**
+ * Publish an EXPECTED failure in the format the operator asked for, then exit
+ * with the code the command's own contract assigns it.
+ *
+ * The third ending of one failure, beside {@link handleCommandError} (the
+ * UNEXPECTED failure, always `ERROR`) and {@link handleValidationGateFailure}
+ * (a validation gate, always `FINDINGS`, always YAML). This one covers the
+ * failure that is neither: the command ran, understood the project, and has a
+ * documented non-zero code for what it found — `vat ard emit` ending on
+ * `FINDINGS` for "this project declares no `ard:` block" or `ERROR` for "there
+ * is no config file here".
+ *
+ * 🔑 It exists because those endings were written inline, and an inline ending
+ * publishes nothing: `ard emit` honoured `--format json` on its success path
+ * and through `handleCommandError`, then wrote **zero bytes to stdout** on the
+ * two exits a repository actually reaches — the commonest being the first run
+ * of any repository that never opted into ARD. A CI wrapper reading stdout got
+ * an empty document and a bare non-zero code, which is the exact failure the
+ * `format` note on {@link handleCommandError} exists to forbid.
+ *
+ * The message goes to stderr as it always did — humans read it there — and the
+ * document goes to stdout, matching what both neighbours already do.
+ *
+ * @param message - What went wrong, in the command's own words
+ * @param exitCode - The code this command's `--help` assigns to this outcome
+ * @param startTime - Command start time (from Date.now()), so the document
+ *   reports the run's real duration rather than a fabricated zero
+ * @param format - What the operator asked for: `json`, or anything else (and
+ *   omitted) for YAML — the same two-branch switch the success path uses
+ */
+export declare function handleExpectedFailure(message: string, exitCode: ExitCodeValue, startTime: number, format?: string | undefined): never;
+/**
+ * {@link handleCommandError} for a command whose document is the shared
+ * `Report<T>` envelope: the failure document IS the envelope
+ * (`buildErrorReport`), so the emitted `schemas/<command>.json` describes the
+ * failed run too. Every command registered as `report` in `report-schemas.ts`
+ * ends its unexpected failures here; `handleCommandError`'s
+ * `CommandErrorDocument` is the shape the legacy documents keep.
+ *
+ * @param error - The value that was thrown
+ * @param logger - Logger instance for error output
+ * @param startTime - Command start time (from Date.now())
+ * @param commandName - Name of the command (for the stderr line)
+ * @param format - What the operator asked for: `json`, or anything else (and
+ *   omitted) for YAML
+ */
+export declare function handleReportCommandError(error: unknown, logger: Logger, startTime: number, commandName: string, format?: string | undefined): never;
+/**
+ * {@link handleExpectedFailure} for a command whose document is the shared
+ * `Report<T>` envelope — same document as {@link handleReportCommandError},
+ * with the exit code the command's own contract assigns.
+ *
+ * @param message - What went wrong, in the command's own words
+ * @param exitCode - The code this command's `--help` assigns to this outcome
+ * @param startTime - Command start time (from Date.now())
+ * @param format - What the operator asked for: `json`, or anything else (and
+ *   omitted) for YAML
+ */
+export declare function handleReportExpectedFailure(message: string, exitCode: ExitCodeValue, startTime: number, format?: string | undefined): never;
 /** The payload a command publishes when its own validation gate stops it. */
 export interface ValidationGateFailure {
     status: 'error';
@@ -99,9 +142,9 @@ export interface ValidationGateFailure {
 export declare function buildValidationGateFailure(subject: string, issues: readonly ValidationIssue[]): ValidationGateFailure;
 /**
  * Publish the documented failure payload for a command stopped by its OWN
- * validation gate, then exit 1.
+ * validation gate, then end on `FINDINGS`.
  *
- * {@link handleCommandError} above covers the UNEXPECTED failure (exit 2). This
+ * {@link handleCommandError} above covers the UNEXPECTED failure (`ERROR`). This
  * covers the expected one, and `vat skills build` / `vat skills package` both
  * exited it after writing zero bytes to stdout — while their `--help` texts
  * document a YAML summary on stdout and reserve exit 1 for exactly this case.
@@ -109,40 +152,29 @@ export declare function buildValidationGateFailure(subject: string, issues: read
  * a bare non-zero code.
  */
 export declare function handleValidationGateFailure(subject: string, issues: readonly ValidationIssue[]): never;
-/**
- * The exit code a USAGE mistake ends on: a flag this program does not declare,
- * a verb it does not know, a missing or invalid argument.
- *
- * 🔑 **Two is not a style choice — one was a factual lie.** Every command's
- * `--help` publishes the same three-way contract: `0` no error-severity
- * findings, `1` at least one, `2` a system error. Commander's default for a
- * usage mistake is `process.exit(1)`, so `vat resources check --json` (the
- * option is `--format json`) exited **1** — which, read against the contract
- * the command itself prints, asserts that at least one check was violated.
- * Nothing had run. A CI wrapper spelled `if [ $? -ne 0 ]; then report_findings`
- * therefore reported findings that were never computed, and the operator went
- * looking for a violation that did not exist.
- *
- * The same hole swallowed a mistyped verb (`vat resources chekc`) and every
- * unknown option on all 69 commands. VAT's own refusals were already correct —
- * an unknown `--check` name and an unusable `--budget` both exit 2 — so the
- * inconsistency was Commander's default leaking through the one path VAT had
- * not claimed.
- *
- * ⚠️ **Help and `--version` are NOT usage mistakes.** They terminate through
- * the same `_exit` path with code 0 and must stay 0; only a non-zero commander
- * ending is remapped. See {@link exitCodeForCommanderEnding}.
- */
-export declare const USAGE_ERROR_EXIT_CODE = 2;
 /**
  * Map a commander termination to the exit code VAT's contract promises.
  *
+ * A USAGE mistake — a flag this program does not declare, a verb it does not
+ * know, a missing or invalid argument — ends on `ExitCode.ERROR`, and the
+ * reason is not style. Commander's default for a usage mistake is
+ * `process.exit(1)`, so `vat resources check --json` (the option is
+ * `--format json`) exited **1** — which, read against the contract the command
+ * itself prints, asserts that at least one check was violated. Nothing had
+ * run. A CI wrapper spelled `if [ $? -ne 0 ]; then report_findings` therefore
+ * reported findings that were never computed. The same hole swallowed a
+ * mistyped verb (`vat resources chekc`) and every unknown option on every
+ * command.
+ *
  * Commander reports BOTH successful and failing terminations through the same
  * `CommanderError`: `--help` and `--version` carry `exitCode` 0, while an
  * unknown option, an unknown command and `help({ error: true })` carry non-zero.
  * Anything non-zero is a usage mistake by construction — commander raises these
- * only while parsing, before any action runs — so it maps to
- * {@link USAGE_ERROR_EXIT_CODE}.
+ * only while parsing, before any action runs — so it maps to `ERROR`.
+ *
+ * ⚠️ **Help and `--version` are NOT usage mistakes.** They terminate through
+ * the same `_exit` path with code 0 and must stay `OK`; only a non-zero
+ * commander ending is remapped.
  *
  * 🪤 Do NOT switch on `error.code` (`commander.unknownOption`, `commander.help`,
  * …). The unknown-COMMAND path arrives as `commander.help` with exitCode 1,
@@ -151,7 +183,7 @@ export declare const USAGE_ERROR_EXIT_CODE = 2;
  * code commander already computed is the honest discriminator; the string is not.
  *
  * @param commanderExitCode - The `exitCode` commander put on its CommanderError
- * @returns 0 for a successful ending, {@link USAGE_ERROR_EXIT_CODE} otherwise
+ * @returns `OK` for a successful ending, `ERROR` otherwise
  */
-export declare function exitCodeForCommanderEnding(commanderExitCode: number): number;
+export declare function exitCodeForCommanderEnding(commanderExitCode: number): ExitCodeValue;
 //# sourceMappingURL=command-error.d.ts.map

package/dist/utils/command-error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command-error.d.ts","sourceRoot":"","sources":["../../src/utils/command-error.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,EAAmB,KAAK,cAAc,EAAE,KAAK,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAExG,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAG1C;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAQjD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAMvD;AAED,4EAA4E;AAC5E,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,GAClB,oBAAoB,CAQtB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,GAC1B,KAAK,CAQP;AAED,6EAA6E;AAC7E,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,cAAc,CAAC;IAC5B,iFAAiF;IACjF,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,SAAS,eAAe,EAAE,GACjC,qBAAqB,CAEvB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,SAAS,eAAe,EAAE,GACjC,KAAK,CAGP;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,0BAA0B,CAAC,iBAAiB,EAAE,MAAM,GAAG,MAAM,CAE5E"}
+{"version":3,"file":"command-error.d.ts","sourceRoot":"","sources":["../../src/utils/command-error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAiE,KAAK,aAAa,EAAE,KAAK,cAAc,EAAE,KAAK,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAE1K,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAG1C;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAQjD;AAED,4EAA4E;AAC5E,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,GAClB,oBAAoB,CAQtB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,GAC1B,KAAK,CAGP;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,aAAa,EACvB,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,GAC1B,KAAK,CAQP;AAkBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,GAC1B,KAAK,CAGP;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,aAAa,EACvB,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,GAC1B,KAAK,CAGP;AAED,6EAA6E;AAC7E,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,cAAc,CAAC;IAC5B,iFAAiF;IACjF,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,SAAS,eAAe,EAAE,GACjC,qBAAqB,CAEvB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,SAAS,eAAe,EAAE,GACjC,KAAK,CAGP;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,0BAA0B,CAAC,iBAAiB,EAAE,MAAM,GAAG,aAAa,CAEnF"}

package/dist/utils/command-error.js

@@ -1,13 +1,15 @@
 /**
  * Shared command error handling utilities.
  *
- * THE single implementation of each failure exit. `commands/skills/` used to
+ * The failure endings a command may take, each publishing a document and
+ * ending on one member of the `ExitCode` contract. `commands/skills/` used to
  * carry its own `handleCommandError` that logged to stderr and exited 2 having
  * written nothing to stdout — same name, same signature, same documented
- * contract, silently different behaviour. Every command family routes here.
+ * contract, silently different behaviour. A command that ends some other way
+ * still names its code from `ExitCode`; the lint rule
+ * `no-literal-process-exit` refuses a bare number.
  */
-import { inspect } from 'node:util';
-import { countBySeverity } from '@vibe-agent-toolkit/schema';
+import { ExitCode, buildErrorReport, countBySeverity, errorDiagnostics } from '@vibe-agent-toolkit/schema';
 import { writeJsonOutput, writeYamlOutput } from './output.js';
 /**
  * Format duration for human readability
@@ -23,31 +25,6 @@ export function formatDuration(ms) {
     }
     return `${(ms / 60000).toFixed(1)}m`;
 }
-/**
- * Everything about a thrown value that `error.message` alone discards.
- *
- * Exit 2 is the UNEXPECTED failure — an internal bug, not a usage mistake — and
- * the one thing a reader needs there is the frame that threw. A real `TypeError`
- * arrived here as a single line (`Cannot read properties of undefined (reading
- * 'readdir')`) with no file, no frames, and no flag that would produce them; the
- * only way to find the throw site was to hand-patch the built `dist`. A value
- * thrown that is not an `Error` fared worse still — the envelope flattens it to
- * the literal string `Unknown error`, which names neither its type nor its
- * contents.
- *
- * The result rides the logger's **debug** channel (`--debug`), so default output
- * is unchanged and no golden moves.
- *
- * @param error - The value that was thrown
- * @returns Stack trace for an `Error`, or an inspected rendering of a non-`Error`
- */
-export function errorDiagnostics(error) {
-    if (error instanceof Error) {
-        // `stack` is optional in the type and absent on some cross-realm errors.
-        return error.stack ?? `${error.name}: ${error.message}`;
-    }
-    return `Non-Error value thrown: ${inspect(error, { depth: 3 })}`;
-}
 /**
  * Report an unexpected failure on stderr and return the document that describes
  * it, WITHOUT deciding how the caller ends.
@@ -78,8 +55,8 @@ export function reportCommandError(error, logger, startTime, commandName) {
 /**
  * Handle command error with standard formatting and exit.
  *
- * The command-line ending for {@link reportCommandError}. Exit 2 is the
- * UNEXPECTED failure, per the exit-code contract every command's help documents.
+ * The command-line ending for {@link reportCommandError}. `ExitCode.ERROR` is
+ * the UNEXPECTED failure, per the exit-code contract every command's help documents.
  *
  * 🔑 **`format` is not decoration.** Every command offering `--format json`
  * honoured it on the success path and emitted YAML here, so the one document a
@@ -98,13 +75,96 @@ export function reportCommandError(error, logger, startTime, commandName) {
  */
 export function handleCommandError(error, logger, startTime, commandName, format) {
     const document = reportCommandError(error, logger, startTime, commandName);
+    return publishFailure(document, format, ExitCode.ERROR);
+}
+/**
+ * Publish an EXPECTED failure in the format the operator asked for, then exit
+ * with the code the command's own contract assigns it.
+ *
+ * The third ending of one failure, beside {@link handleCommandError} (the
+ * UNEXPECTED failure, always `ERROR`) and {@link handleValidationGateFailure}
+ * (a validation gate, always `FINDINGS`, always YAML). This one covers the
+ * failure that is neither: the command ran, understood the project, and has a
+ * documented non-zero code for what it found — `vat ard emit` ending on
+ * `FINDINGS` for "this project declares no `ard:` block" or `ERROR` for "there
+ * is no config file here".
+ *
+ * 🔑 It exists because those endings were written inline, and an inline ending
+ * publishes nothing: `ard emit` honoured `--format json` on its success path
+ * and through `handleCommandError`, then wrote **zero bytes to stdout** on the
+ * two exits a repository actually reaches — the commonest being the first run
+ * of any repository that never opted into ARD. A CI wrapper reading stdout got
+ * an empty document and a bare non-zero code, which is the exact failure the
+ * `format` note on {@link handleCommandError} exists to forbid.
+ *
+ * The message goes to stderr as it always did — humans read it there — and the
+ * document goes to stdout, matching what both neighbours already do.
+ *
+ * @param message - What went wrong, in the command's own words
+ * @param exitCode - The code this command's `--help` assigns to this outcome
+ * @param startTime - Command start time (from Date.now()), so the document
+ *   reports the run's real duration rather than a fabricated zero
+ * @param format - What the operator asked for: `json`, or anything else (and
+ *   omitted) for YAML — the same two-branch switch the success path uses
+ */
+export function handleExpectedFailure(message, exitCode, startTime, format) {
+    process.stderr.write(`${message}\n`);
+    const document = {
+        status: 'error',
+        error: message,
+        duration: formatDuration(Date.now() - startTime),
+    };
+    return publishFailure(document, format, exitCode);
+}
+/**
+ * Publish a failure document in the operator's format, then end on `exitCode`.
+ *
+ * @param document - What to write to stdout
+ * @param format - `json`, or anything else (and omitted) for YAML
+ * @param exitCode - The member of the contract this ending is
+ */
+function publishFailure(document, format, exitCode) {
     if (format === 'json') {
         writeJsonOutput(document);
     }
     else {
         writeYamlOutput(document);
     }
-    process.exit(2);
+    process.exit(exitCode);
+}
+/**
+ * {@link handleCommandError} for a command whose document is the shared
+ * `Report<T>` envelope: the failure document IS the envelope
+ * (`buildErrorReport`), so the emitted `schemas/<command>.json` describes the
+ * failed run too. Every command registered as `report` in `report-schemas.ts`
+ * ends its unexpected failures here; `handleCommandError`'s
+ * `CommandErrorDocument` is the shape the legacy documents keep.
+ *
+ * @param error - The value that was thrown
+ * @param logger - Logger instance for error output
+ * @param startTime - Command start time (from Date.now())
+ * @param commandName - Name of the command (for the stderr line)
+ * @param format - What the operator asked for: `json`, or anything else (and
+ *   omitted) for YAML
+ */
+export function handleReportCommandError(error, logger, startTime, commandName, format) {
+    const { error: message } = reportCommandError(error, logger, startTime, commandName);
+    return publishFailure(buildErrorReport(message, Date.now() - startTime), format, ExitCode.ERROR);
+}
+/**
+ * {@link handleExpectedFailure} for a command whose document is the shared
+ * `Report<T>` envelope — same document as {@link handleReportCommandError},
+ * with the exit code the command's own contract assigns.
+ *
+ * @param message - What went wrong, in the command's own words
+ * @param exitCode - The code this command's `--help` assigns to this outcome
+ * @param startTime - Command start time (from Date.now())
+ * @param format - What the operator asked for: `json`, or anything else (and
+ *   omitted) for YAML
+ */
+export function handleReportExpectedFailure(message, exitCode, startTime, format) {
+    process.stderr.write(`${message}\n`);
+    return publishFailure(buildErrorReport(message, Date.now() - startTime), format, exitCode);
 }
 /**
  * Pure: the document {@link handleValidationGateFailure} writes.
@@ -118,9 +178,9 @@ export function buildValidationGateFailure(subject, issues) {
 }
 /**
  * Publish the documented failure payload for a command stopped by its OWN
- * validation gate, then exit 1.
+ * validation gate, then end on `FINDINGS`.
  *
- * {@link handleCommandError} above covers the UNEXPECTED failure (exit 2). This
+ * {@link handleCommandError} above covers the UNEXPECTED failure (`ERROR`). This
  * covers the expected one, and `vat skills build` / `vat skills package` both
  * exited it after writing zero bytes to stdout — while their `--help` texts
  * document a YAML summary on stdout and reserve exit 1 for exactly this case.
@@ -129,42 +189,31 @@ export function buildValidationGateFailure(subject, issues) {
  */
 export function handleValidationGateFailure(subject, issues) {
     writeYamlOutput(buildValidationGateFailure(subject, issues));
-    process.exit(1);
+    process.exit(ExitCode.FINDINGS);
 }
-/**
- * The exit code a USAGE mistake ends on: a flag this program does not declare,
- * a verb it does not know, a missing or invalid argument.
- *
- * 🔑 **Two is not a style choice — one was a factual lie.** Every command's
- * `--help` publishes the same three-way contract: `0` no error-severity
- * findings, `1` at least one, `2` a system error. Commander's default for a
- * usage mistake is `process.exit(1)`, so `vat resources check --json` (the
- * option is `--format json`) exited **1** — which, read against the contract
- * the command itself prints, asserts that at least one check was violated.
- * Nothing had run. A CI wrapper spelled `if [ $? -ne 0 ]; then report_findings`
- * therefore reported findings that were never computed, and the operator went
- * looking for a violation that did not exist.
- *
- * The same hole swallowed a mistyped verb (`vat resources chekc`) and every
- * unknown option on all 69 commands. VAT's own refusals were already correct —
- * an unknown `--check` name and an unusable `--budget` both exit 2 — so the
- * inconsistency was Commander's default leaking through the one path VAT had
- * not claimed.
- *
- * ⚠️ **Help and `--version` are NOT usage mistakes.** They terminate through
- * the same `_exit` path with code 0 and must stay 0; only a non-zero commander
- * ending is remapped. See {@link exitCodeForCommanderEnding}.
- */
-export const USAGE_ERROR_EXIT_CODE = 2;
 /**
  * Map a commander termination to the exit code VAT's contract promises.
  *
+ * A USAGE mistake — a flag this program does not declare, a verb it does not
+ * know, a missing or invalid argument — ends on `ExitCode.ERROR`, and the
+ * reason is not style. Commander's default for a usage mistake is
+ * `process.exit(1)`, so `vat resources check --json` (the option is
+ * `--format json`) exited **1** — which, read against the contract the command
+ * itself prints, asserts that at least one check was violated. Nothing had
+ * run. A CI wrapper spelled `if [ $? -ne 0 ]; then report_findings` therefore
+ * reported findings that were never computed. The same hole swallowed a
+ * mistyped verb (`vat resources chekc`) and every unknown option on every
+ * command.
+ *
  * Commander reports BOTH successful and failing terminations through the same
  * `CommanderError`: `--help` and `--version` carry `exitCode` 0, while an
  * unknown option, an unknown command and `help({ error: true })` carry non-zero.
  * Anything non-zero is a usage mistake by construction — commander raises these
- * only while parsing, before any action runs — so it maps to
- * {@link USAGE_ERROR_EXIT_CODE}.
+ * only while parsing, before any action runs — so it maps to `ERROR`.
+ *
+ * ⚠️ **Help and `--version` are NOT usage mistakes.** They terminate through
+ * the same `_exit` path with code 0 and must stay `OK`; only a non-zero
+ * commander ending is remapped.
  *
  * 🪤 Do NOT switch on `error.code` (`commander.unknownOption`, `commander.help`,
  * …). The unknown-COMMAND path arrives as `commander.help` with exitCode 1,
@@ -173,9 +222,9 @@ export const USAGE_ERROR_EXIT_CODE = 2;
  * code commander already computed is the honest discriminator; the string is not.
  *
  * @param commanderExitCode - The `exitCode` commander put on its CommanderError
- * @returns 0 for a successful ending, {@link USAGE_ERROR_EXIT_CODE} otherwise
+ * @returns `OK` for a successful ending, `ERROR` otherwise
  */
 export function exitCodeForCommanderEnding(commanderExitCode) {
-    return commanderExitCode === 0 ? 0 : USAGE_ERROR_EXIT_CODE;
+    return commanderExitCode === 0 ? ExitCode.OK : ExitCode.ERROR;
 }
 //# sourceMappingURL=command-error.js.map

package/dist/utils/command-error.js.map

@@ -1 +1 @@
-{"version":3,"file":"command-error.js","sourceRoot":"","sources":["../../src/utils/command-error.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,eAAe,EAA6C,MAAM,4BAA4B,CAAC;AAGxG,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE/D;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,EAAU;IACvC,IAAI,EAAE,GAAG,IAAI,EAAE,CAAC;QACd,OAAO,GAAG,EAAE,IAAI,CAAC;IACnB,CAAC;IACD,IAAI,EAAE,GAAG,KAAK,EAAE,CAAC;QACf,OAAO,GAAG,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;IACtC,CAAC;IACD,OAAO,GAAG,CAAC,EAAE,GAAG,KAAK,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;AACvC,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,yEAAyE;QACzE,OAAO,KAAK,CAAC,KAAK,IAAI,GAAG,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC;IAC1D,CAAC;IACD,OAAO,2BAA2B,OAAO,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;AACnE,CAAC;AASD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,kBAAkB,CAChC,KAAc,EACd,MAAc,EACd,SAAiB,EACjB,WAAmB;IAEnB,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;IACxC,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC;IAEzE,MAAM,CAAC,KAAK,CAAC,GAAG,WAAW,YAAY,OAAO,EAAE,CAAC,CAAC;IAClD,MAAM,CAAC,KAAK,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC,CAAC;IAEtC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,cAAc,CAAC,QAAQ,CAAC,EAAE,CAAC;AACjF,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,kBAAkB,CAChC,KAAc,EACd,MAAc,EACd,SAAiB,EACjB,WAAmB,EACnB,MAA2B;IAE3B,MAAM,QAAQ,GAAG,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,WAAW,CAAC,CAAC;IAC3E,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;QACtB,eAAe,CAAC,QAAQ,CAAC,CAAC;IAC5B,CAAC;SAAM,CAAC;QACN,eAAe,CAAC,QAAQ,CAAC,CAAC;IAC5B,CAAC;IACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAUD;;;;;;GAMG;AACH,MAAM,UAAU,0BAA0B,CACxC,OAAe,EACf,MAAkC;IAElC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,eAAe,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;AACnF,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,2BAA2B,CACzC,OAAe,EACf,MAAkC;IAElC,eAAe,CAAC,0BAA0B,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;IAC7D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC;AAEvC;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,0BAA0B,CAAC,iBAAyB;IAClE,OAAO,iBAAiB,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,qBAAqB,CAAC;AAC7D,CAAC"}
+{"version":3,"file":"command-error.js","sourceRoot":"","sources":["../../src/utils/command-error.ts"],"names":[],"mappings":"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"}

package/dist/utils/config-loader.d.ts

@@ -5,6 +5,7 @@
  * - VAT_TEST_CONFIG: Override config file path for testing (absolute path)
  */
 import { type ProjectConfig } from '@vibe-agent-toolkit/resources';
+import { VatError } from '@vibe-agent-toolkit/utils';
 /**
  * A `vibe-agent-toolkit.config.yaml` exists but failed to parse or validate.
  *
@@ -14,7 +15,7 @@ import { type ProjectConfig } from '@vibe-agent-toolkit/resources';
  * `vat skill test`) should surface this; a bulk linter (`vat audit`) may catch
  * it and fall back to config-free validation.
  */
-export declare class ConfigLoadError extends Error {
+export declare class ConfigLoadError extends VatError {
     readonly projectRoot: string;
     constructor(projectRoot: string, cause: unknown);
 }

package/dist/utils/config-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config-loader.d.ts","sourceRoot":"","sources":["../../src/utils/config-loader.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,EAAuD,KAAK,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAaxH;;;;;;;;GAQG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;gBACjB,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO;CAMhD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAkDzE;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAEvD;AAqBD;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAM7C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAgB/E"}
+{"version":3,"file":"config-loader.d.ts","sourceRoot":"","sources":["../../src/utils/config-loader.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,EAAuD,KAAK,aAAa,EAAE,MAAM,+BAA+B,CAAC;AACxH,OAAO,EAAY,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAY/D;;;;;;;;GAQG;AACH,qBAAa,eAAgB,SAAQ,QAAQ;IAC3C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;gBACjB,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO;CAKhD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAgDzE;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAEvD;AAqBD;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAM7C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAgB/E"}

package/dist/utils/config-loader.js

@@ -7,7 +7,7 @@
 import { readFileSync, existsSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { parseConfigAllowingUnknownKeys, ProjectConfigSchema } from '@vibe-agent-toolkit/resources';
-import { safePath } from '@vibe-agent-toolkit/utils';
+import { safePath, VatError } from '@vibe-agent-toolkit/utils';
 import * as yaml from 'yaml';
 const CONFIG_FILENAME = 'vibe-agent-toolkit.config.yaml';
 /**
@@ -25,11 +25,10 @@ const warnedConfigPaths = new Set();
  * `vat skill test`) should surface this; a bulk linter (`vat audit`) may catch
  * it and fall back to config-free validation.
  */
-export class ConfigLoadError extends Error {
+export class ConfigLoadError extends VatError {
     projectRoot;
     constructor(projectRoot, cause) {
-        super(cause instanceof Error ? cause.message : String(cause));
-        this.name = 'ConfigLoadError';
+        super('CONFIG_LOAD', cause instanceof Error ? cause.message : String(cause));
         this.projectRoot = projectRoot;
         if (cause instanceof Error)
             this.cause = cause;
@@ -59,12 +58,10 @@ export class ConfigLoadError extends Error {
 export function loadConfig(projectRoot) {
     // Override for testing: VAT_TEST_CONFIG provides explicit config path
     const configPath = process.env['VAT_TEST_CONFIG'] ?? safePath.join(projectRoot, CONFIG_FILENAME);
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- configPath is derived from projectRoot parameter or env override
     if (!existsSync(configPath)) {
         return undefined;
     }
     try {
-        // eslint-disable-next-line security/detect-non-literal-fs-filename -- configPath is derived from projectRoot parameter
         const content = readFileSync(configPath, 'utf-8');
         const parsed = yaml.parse(content);
         // Validate with canonical schema from resources package.

package/dist/utils/config-loader.js.map

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

package/dist/utils/context-budget-issues.d.ts

@@ -11,7 +11,7 @@
  *
  * A sweep reports every working location, and locations sharing an instruction
  * chain share one budget — that is the whole point of the collapse. Re-measured
- * on VAT's own tree 2026-08-23, after the context population began declining the
+ * on VAT's own tree, after the context population began declining the
  * gitignored half: **366 of 589 directories** pay the single chain
  * `['CLAUDE.md']`, so emitting per location would print 366 byte-identical
  * findings, all blaming one file, the moment the root `CLAUDE.md` crossed the

package/dist/utils/context-budget-issues.js

@@ -11,7 +11,7 @@
  *
  * A sweep reports every working location, and locations sharing an instruction
  * chain share one budget — that is the whole point of the collapse. Re-measured
- * on VAT's own tree 2026-08-23, after the context population began declining the
+ * on VAT's own tree, after the context population began declining the
  * gitignored half: **366 of 589 directories** pay the single chain
  * `['CLAUDE.md']`, so emitting per location would print 366 byte-identical
  * findings, all blaming one file, the moment the root `CLAUDE.md` crossed the

package/dist/utils/corpus-target.d.ts

@@ -5,34 +5,12 @@
  * about positions in it — `vat claude context` and `vat claude budget` today.
  * They ask different questions and default differently when no path is named,
  * but "is this argument inside the tree I enumerated, and what is it called
- * there" is one rule, and a second copy of it would be free to drift on the one
- * clause that only fails where nobody looks (see {@link escapesCorpusRoot}).
+ * there" is one rule. The predicate itself is `relativeEscapesRoot` from
+ * `@vibe-agent-toolkit/utils` — the one lexical classifier every lane shares,
+ * so the clause that only fails on Windows (a cross-drive `relative()` comes
+ * back ABSOLUTE, not `..`-prefixed) is tested once, there, with the string
+ * Windows really produces.
  */
-/**
- * Does a path already stated against the corpus root fall OUTSIDE it?
- *
- * Three spellings of "outside", not two, and the third is the one that could
- * only fail where nobody would see it. `safePath.relative` says "not under this
- * root" with a `..`-prefixed path in the ordinary case, but returns an ABSOLUTE
- * path when no relative route exists at all — which on Windows is exactly what a
- * different drive letter produces. Without the third test, `vat claude context
- * D:\elsewhere\doc.md` run from a `C:` repo passes the guard and answers `kind:
- * unknown`, indistinguishable from a typo inside the tree, which is the one
- * outcome {@link targetPathWithin}'s `@throws` claims to prevent. Its sibling
- * `escapesRoot` (`closure-extent.ts`) applies the same triple for the same
- * reason.
- *
- * ⛔ Exported so it can be TESTED. On POSIX `safePath.relative` between two
- * absolute paths never returns an absolute string, so the third clause is
- * unreachable through {@link targetPathWithin} on every machine a developer
- * runs — the branch has to be exercised directly or not at all, and "not at
- * all" is how it went missing in the first place.
- *
- * @param normalizedRelative - A forward-slashed path already stated against the
- *   corpus root
- * @returns True when the corpus root does not contain it
- */
-export declare function escapesCorpusRoot(normalizedRelative: string): boolean;
 /**
  * The root-relative path to query, refusing anything outside the corpus.
  *

package/dist/utils/corpus-target.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"corpus-target.d.ts","sourceRoot":"","sources":["../../src/utils/corpus-target.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,iBAAiB,CAAC,kBAAkB,EAAE,MAAM,GAAG,OAAO,CAIrE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,WAAW,EAAE,MAAM,GAClB,MAAM,CAUR"}
+{"version":3,"file":"corpus-target.d.ts","sourceRoot":"","sources":["../../src/utils/corpus-target.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,WAAW,EAAE,MAAM,GAClB,MAAM,CAUR"}