# T23 Canonical CLI Validation

> - Task: T23 — Implement canonical CLI, JSON output, and alias equivalence - Requirements: VES-CLI-001…005, VES-WSP-001/006, and VES-BST-002/004 at the command-surface boundary - Commit target: feat(cli): add vestra command surface - Focused evidence: 47 cases — 41 contract and 6 e2e - Spec deviations: none

Source: https://github.com/accd/verchestra/blob/main/docs/qualification/t23-validation.md
Content digest: `sha256:bbbd8dcdf6a14156a4c0d12b41e5323a9e293a83a3f3748de758a3c974922528`

## Scope

- Task: T23 — Implement canonical CLI, JSON output, and alias equivalence
- Requirements: VES-CLI-001…005, VES-WSP-001/006, and VES-BST-002/004 at the command-surface boundary
- Commit target: `feat(cli): add vestra command surface`
- Focused evidence: 47 cases — 41 contract and 6 e2e
- Spec deviations: none

T23 creates the canonical `apps/vestra-cli/` composition root, two package launchers, a pure installed-manifest-driven parser, human/JSON renderers, stable public errors and exit codes, and an application `CommandBus` port. The invocation spelling is deliberately absent from dispatched commands and contexts, making alias equivalence structural rather than handler convention.

Signed bundle installation, atomic active-release switching, and concrete command composition remain owned by later release and command tasks. This slice preserves the active release on manifest/compatibility failure because all validation is read-only and occurs before `CommandBus.execute`.

## Deterministic gates

| Command | Result |
| --- | --- |
| `node --test tests/contract/cli-surface.test.mjs tests/e2e/cli-launchers-e2e.test.mjs` | PASS — 47 passed, 0 failed/skipped |
| `node scripts/gate.mjs full` | PASS — format, lint, typecheck, 1,208 unit, 82 contract, 135 integration, 16 e2e, and 32 fault cases |
| `node --test tests/architecture/*.test.mjs` | PASS — 10 passed, 0 failed/skipped |
| `corepack pnpm@10.34.5 install --offline --frozen-lockfile --ignore-scripts` | PASS — all 17 workspace projects restored from the frozen lock |

## Check A — sufficient, spec-anchored coverage

| Criterion / requirement | Exact assertion evidence | Spec-defined outcome | Covered |
| --- | --- | --- | --- |
| VES-CLI-001: canonical version identity | `tests/contract/cli-surface.test.mjs:28`, `:35`, `:43` | Both names exit 0 and emit the same semantic version/release digest; JSON validates | Yes |
| VES-CLI-002: alias equivalence is structural | `tests/contract/cli-surface.test.mjs:91`, `:97`; `tests/e2e/cli-launchers-e2e.test.mjs:16` | Alias spelling cannot enter dispatch; commands, context, stdout, stderr, and exit code match for version/help/sync/unknown | Yes |
| VES-CLI-003: help is installed-manifest-driven | `tests/contract/cli-surface.test.mjs:51`, `:58`, `:64` | Product and canonical name appear; only installed commands are listed | Yes |
| VES-CLI-004/005: stable pre-dispatch failure | `tests/contract/cli-surface.test.mjs:161`, `:170`, `:191` | Unsupported output, incompatible release, and invalid installed manifest return stable non-zero outcomes with zero dispatch | Yes |
| VES-CLI-005: clean versioned JSON stdout | `tests/contract/cli-surface.test.mjs:43`, `:122`, `:129`, `:198`; `tests/e2e/cli-launchers-e2e.test.mjs:25` | One `cli-output@1` document on stdout; diagnostics use stderr; private text is absent | Yes |
| Canonical command dispatch | `tests/contract/cli-surface.test.mjs:83` | Every installed command becomes one typed canonical command | Yes |
| Schema-driven option parsing | `tests/contract/cli-surface.test.mjs:106`, `:112`, `:118` | Boolean/string/enum options preserve exact manifest names and values | Yes |
| Unknown/ambiguous input fails before mutation | `tests/contract/cli-surface.test.mjs:152` | Eight unknown, missing, duplicated, positional, and mixed-global cases cause zero bus calls | Yes |
| Stable safe public errors | `tests/contract/cli-surface.test.mjs:198`, `:212`, `:221`, `:232` | Known errors preserve schema/exit; unknown exceptions sanitize; human failures use stderr; exact catalog validates | Yes |
| Hermetic launchers | `tests/e2e/cli-launchers-e2e.test.mjs:16`, `:25` | Real child processes prove byte-identical alias behavior and parseable clean stdout | Yes |
| Minimum test floor | Focused runner: 47 passed | At least 35 contract/e2e cases | Yes |

No T23-owned precision gap remains. Existing T20/T22 services own init/reconcile semantics; T23 defines the typed dispatch boundary and does not duplicate them.

## Check B — non-shallow litmus

- Alias tests compare real child-process status/stdout/stderr across success, JSON, mutable-command failure, and unknown-command paths.
- The contract test verifies invocation spelling is not present anywhere in the bus call, preventing implementation branches by alias.
- Help removes a command from the installed manifest and asserts the output removes it; a hard-coded help surface fails.
- Eight invalid-input cases assert zero bus calls, so post-dispatch validation fails.
- JSON tests parse and validate the exact stdout document against `cli-output@1` and independently assert diagnostics on stderr.
- A private sentinel exception is injected and asserted absent from serialized output.
- Offline frozen installation proves package-bin and workspace dependency metadata are reproducible.

## Check C — necessary reverse mapping

| Test evidence | Requirement / criterion | Keep |
| --- | --- | --- |
| `cli-surface.test.mjs:28,35,43` | VES-CLI-001 version/digest and alias identity | Yes |
| `cli-surface.test.mjs:51,58,64` | VES-CLI-003 manifest-derived help | Yes |
| `cli-surface.test.mjs:83,91,97` | VES-CLI-002 typed dispatch and structural alias equivalence | Yes |
| `cli-surface.test.mjs:106,112,118,152` | Pure schema-driven parsing and fail-before-dispatch | Yes |
| `cli-surface.test.mjs:122,129,198,212,221,232` | VES-CLI-005 stream separation, schema, stable safe failures | Yes |
| `cli-surface.test.mjs:170,191` | VES-BST-005-style installed release compatibility preflight | Yes |
| `cli-launchers-e2e.test.mjs:16,25` | Real launcher equivalence and clean JSON process output | Yes |

All 47 cases map to a named requirement or T23 done-when criterion. No speculative test remains.

## Check D — guideline conformance

- Followed `.specs/features/verchestra-1.0/tasks.md`: contract and e2e layers exceed the mandated floor and `gate:full` passes.
- Followed Design §4.1: parser/renderers are in `apps/vestra-cli`, dispatch is through an application port, and JSON never shares stdout with diagnostics.
- Followed AD-013/026: the CLI is the composition root; application owns only backend-neutral command contracts; all architecture tests remain green.
- Followed AD-027/029: JSON uses the generated `CliOutput` contract and public errors come from an immutable safe-detail registry.
- Followed AD-037/038: incompatible installed configuration is rejected before bootstrap/sync/reconcile dispatch.

## Adequacy verdict

PASS. Every T23-owned surface criterion has discriminating evidence, all 47 focused cases are traceable, the complete full gate and architecture suite are green, and frozen offline installation succeeds.