create-quiver 0.15.4 → 0.16.0

package/specs/quiver-v51-cli-ergonomics-automation-contracts/EVIDENCE_REPORT.md

@@ -0,0 +1,145 @@
+# Evidence Report - Quiver v51 CLI Ergonomics and Automation Contracts
+
+## Planning Evidence
+
+- Source requirements: `REQUERIMIENTOS_DERIVADOS_DE_AUDITORIA.md`.
+- Approved plan: user-approved technical plan v4.
+- Current branch inspection showed `status`, `slice`, `handoff`, `evidence list/show`, `demo spec-viewer`, and AI module fragmentation are already present.
+
+## Baseline Evidence To Capture During Execution
+
+- `node bin/create-quiver.js --help`
+- `node bin/create-quiver.js flow --json`
+- `node bin/create-quiver.js dashboard --section invalid --lang es`
+- `node bin/create-quiver.js evidence list --json`
+- namespace alias stdout/stderr behavior
+- Windows `pwsh` command execution for portable scripts
+
+## Validation Evidence
+
+## slice-00-cli-contract-baseline
+
+- `bin/create-quiver.js`: delegates to the `src/create-quiver` CLI implementation.
+- `src/create-quiver/lib/cli/command-registry.js`: enumerates the public command surface for `status`, `flow`, `dashboard`, `plan`, `graph`, `evidence`, `demo`, `slice`, `handoff`, and `ai`.
+- `src/create-quiver/commands/status.js` and `tests/commands/status.test.js`: `status` command exists with human and JSON contracts.
+- `src/create-quiver/commands/slice.js` and `tests/commands/slice-namespace.test.js`: canonical `slice` namespace and legacy aliases exist with deprecation warnings on stderr.
+- `src/create-quiver/commands/handoff.js` and `tests/commands/handoff-namespace.test.js`: canonical `handoff` namespace and legacy aliases exist with deprecation warnings on stderr.
+- `src/create-quiver/commands/evidence.js`, `src/create-quiver/lib/evidence.js`, and `tests/commands/evidence.test.js`: evidence `run/list/show`, redaction, truncation, JSON, and path-safety contracts exist.
+- `src/create-quiver/commands/demo.js` and `tests/commands/demo.test.js`: `demo spec-viewer` and `demo create spec-viewer` compatibility exists.
+- `src/create-quiver/commands/ai.js` delegates to `src/create-quiver/commands/ai/{agents,diagnostics,execution,inspection,lifecycle,planner}.js`; AI fragmentation is already implemented.
+- `src/create-quiver/commands/flow.js` and `tests/commands/flow.test.js`: `flow` is read-only and has JSON tests, but additive `next_command` still belongs to `slice-01`.
+- `src/create-quiver/lib/dashboard.js` and `tests/commands/dashboard.test.js`: dashboard sections and JSON constraints are tested; invalid-section localization remains for `slice-02`.
+- `tests/commands/plan.test.js` and `tests/commands/graph.test.js`: missing estimates and empty level filters are covered.
+- `package.json`: legacy Bash scripts coexist with portable `quiver:*` scripts; Windows script policy remains for `slice-06`.
+- Runtime code was not modified for this baseline slice.
+- `git diff --check`: passed.
+- `node bin/create-quiver.js spec validate specs/quiver-v51-cli-ergonomics-automation-contracts`: passed.
+
+## slice-01-flow-json-compatibility
+
+- `src/create-quiver/commands/flow.js`: `baseReport` now emits `next_command` as an additive snake_case alias of the existing `nextCommand` field.
+- `tests/commands/flow.test.js`: machine-readable tests cover both uninitialized and ready-slice states, asserting `next_command` and `nextCommand` remain equal.
+- `docs/reference/commands.md`: documents `flow --json` compatibility for both fields.
+- `specs/quiver-v43-cli-i18n-audit-release-readiness/command-language-mode-matrix.json`: records the newly documented `flow --json` command under a JSON coverage profile.
+- `node --test tests/commands/flow.test.js`: passed, 17 tests.
+- `node --test tests/commands/i18n-audit-matrix.test.js tests/commands/flow.test.js`: passed, 19 tests.
+- `node --test`: passed, 622 tests.
+- `npm run docs:check`: passed.
+- `git diff --check`: passed.
+- `node bin/create-quiver.js spec validate specs/quiver-v51-cli-ergonomics-automation-contracts`: passed.
+
+## slice-02-dashboard-section-validation-i18n
+
+- `src/create-quiver/lib/dashboard.js`: existing invalid-section handling uses localized `dashboard.unsupported_section` for human output and English-only translation for JSON output.
+- `src/create-quiver/lib/i18n/messages/en.js`: English help text now lists the supported dashboard sections.
+- `src/create-quiver/lib/i18n/messages/es.js`: Spanish help text now lists the supported dashboard sections.
+- `tests/commands/dashboard.test.js`: added EN/ES invalid-section assertions, supported-section list coverage, and JSON-safe invalid-section failure coverage.
+- `tests/commands/cli-contract.test.js`: updated help contract to require the supported section list.
+- `docs/reference/commands.md`: documents every supported dashboard section, including `overview`.
+- `docs/COMMANDS.md.template`: keeps generated command docs aligned with the public reference.
+- `npm run test:ci -- tests/commands/dashboard.test.js tests/commands/cli-contract.test.js tests/lib/i18n-catalog.test.js`: passed, 35 tests.
+- `node --test`: passed, 624 tests.
+- `npm run docs:check`: passed.
+- `git diff --check`: passed.
+- `node bin/create-quiver.js spec validate specs/quiver-v51-cli-ergonomics-automation-contracts`: passed.
+- `node bin/create-quiver.js check-slice specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-02-dashboard-section-validation-i18n/slice.json --local --gate validation`: passed.
+- `node bin/create-quiver.js check-scope specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-02-dashboard-section-validation-i18n/slice.json --base main --strict`: passed.
+- `node bin/create-quiver.js check-pr specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-02-dashboard-section-validation-i18n/slice.json --base main`: passed spec, slice, overlap, validation gate, scope, branch, and clean-worktree checks; failed commit ownership because PR readiness still evaluates `origin/develop` even when the slice base is `main`. This is tracked by `slice-03-base-branch-resolution-policy`.
+
+## slice-03-base-branch-resolution-policy
+
+- `src/create-quiver/lib/git.js`: adds shared base branch resolution helpers with explicit override precedence, Remote HEAD discovery, and fallback candidates `main`, `master`, and `develop`.
+- `src/create-quiver/lib/readiness.js`: uses the shared resolver for slice readiness, scope checks, and PR readiness instead of hardcoded `origin/develop`.
+- `src/create-quiver/lib/spec-worktrees.js`: uses the shared resolver for spec worktree base selection while preserving explicit slice/spec base metadata.
+- `src/create-quiver/lib/lifecycle.js`: applies the shared resolver to slice cleanup and base freshness checks without changing slice branch fetch behavior.
+- `src/create-quiver/lib/ai/github.js`: resolves default `ai pr` base from Remote HEAD when `--base` is omitted, while preserving the `gh pr create --base <branch>` argument contract.
+- `src/create-quiver/index.js`: forwards `--base` only as an explicit override for `check-pr`, `ai pr`, `spec start`, and `spec close`.
+- `src/create-quiver/lib/i18n/messages/en.js` and `src/create-quiver/lib/i18n/messages/es.js`: remove stale hardcoded `origin/develop` readiness text and localize generic base/ref messages.
+- `docs/reference/commands.md` and `docs/COMMANDS.md.template`: document explicit `--base` precedence, Remote HEAD resolution, and fallback order.
+- `tests/lib/git.test.js`: covers explicit override precedence, Remote HEAD defaulting, and `main`/`master`/`develop` fallback order.
+- `tests/lib/check-slice.test.js`: covers `check-pr` using the slice base branch instead of hardcoded `origin/develop`.
+- `tests/lib/ai-github.test.js`: covers `ai pr` defaulting to Remote HEAD when `--base` is omitted.
+- `tests/lib/scope.test.js`: existing coverage verifies slice `git.base_branch` and explicit base override behavior for scope checks.
+- `tests/lib/lifecycle.test.js`: confirms lifecycle start/cleanup output remains valid after restoring remote slice branch detection.
+- `node --test tests/lib/git.test.js tests/commands/spec-close.test.js tests/commands/ai-pr.test.js tests/lib/check-slice.test.js tests/lib/scope.test.js tests/lib/ai-github.test.js tests/lib/i18n-catalog.test.js tests/commands/cli-contract.test.js`: passed, 77 tests.
+- `node --test tests/lib/lifecycle.test.js`: passed, 12 tests.
+- `node --test`: passed, 629 tests.
+- `npm run docs:check`: passed.
+- `git diff --check`: passed.
+- `node bin/create-quiver.js spec validate specs/quiver-v51-cli-ergonomics-automation-contracts`: passed.
+- `node bin/create-quiver.js check-slice specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-03-base-branch-resolution-policy/slice.json --local --gate validation`: passed.
+- `node bin/create-quiver.js check-scope specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-03-base-branch-resolution-policy/slice.json --base main --strict`: passed.
+- `node bin/create-quiver.js check-pr specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-03-base-branch-resolution-policy/slice.json --base main`: passed.
+
+## slice-04-next-plan-graph-ux-edge-cases
+
+- `tests/commands/next.test.js`: existing coverage validates `next --auto-start` rejects no-TTY sessions and can start through an injected confirmation prompt.
+- `src/create-quiver/commands/plan.js`: adds a localized human-only note when pending slices have no positive `estimated_hours`; JSON output still contains numeric `hours` and no human prose.
+- `tests/commands/plan.test.js`: covers EN/ES missing-estimates notes, `total_hours`/`hours` as `0`, and JSON output without human notes.
+- `src/create-quiver/commands/graph.js`: adds a localized human empty state for `graph --level <n>` when that level has no slices.
+- `tests/commands/graph.test.js`: covers empty-level EN/ES output, JSON-safe empty `levels`/`conflicts`, and `--json` precedence over `--format mermaid`.
+- `src/create-quiver/lib/i18n/messages/en.js` and `src/create-quiver/lib/i18n/messages/es.js`: add localized plan missing-estimates and graph empty-level messages.
+- `docs/reference/commands.md`, `docs/CLI_UX_GUIDE.md`, and `docs/COMMANDS.md.template`: document plan missing estimates, graph empty-level behavior, `next --auto-start` TTY behavior, and `graph --json` precedence over human render formats.
+- `node --test tests/commands/next.test.js tests/commands/plan.test.js tests/commands/graph.test.js tests/lib/i18n-catalog.test.js`: passed, 37 tests.
+- `node --test`: passed, 632 tests.
+- `npm run docs:check`: passed.
+- `git diff --check`: passed.
+
+## slice-05-evidence-robustness-path-safety
+
+- `src/create-quiver/lib/evidence.js`: now resolves explicit output/read paths through project-root and realpath checks, rejects traversal and symlink escapes, preserves failure evidence, records signal metadata, and exposes safe `list`/`show` helpers.
+- `src/create-quiver/commands/evidence.js`: supports `evidence list` and `evidence show` with human output and parseable `--json` output.
+- `src/create-quiver/index.js`: parses `evidence run|list|show`, validates positional arguments, and documents the expanded help surface.
+- `src/create-quiver/lib/i18n/messages/en.js` and `src/create-quiver/lib/i18n/messages/es.js`: keep evidence list/show human messages and missing-subcommand guidance aligned.
+- `tests/commands/evidence.test.js`: covers parseable JSON list/show and rejects traversal output before command execution.
+- `tests/lib/evidence.test.js`: covers redaction, truncation, failure evidence, signal exit code metadata, symlink escape rejection, safe listing, and safe show behavior.
+- `tests/commands/cli-contract.test.js`: covers the expanded help contract for `evidence list` and `evidence show`.
+- `docs/reference/commands.md` and `docs/COMMANDS.md.template`: document evidence run/list/show, safe path policy, JSON usage, redaction/truncation, and signal exit-code behavior.
+- `specs/quiver-v43-cli-i18n-audit-release-readiness/command-language-mode-matrix.json`: records evidence run/list/show coverage for the documented command reference.
+- `node --test tests/commands/evidence.test.js tests/lib/evidence.test.js tests/lib/i18n-catalog.test.js tests/commands/cli-contract.test.js`: passed, 38 tests.
+- `node --test tests/commands/i18n-audit-matrix.test.js tests/commands/evidence.test.js tests/lib/evidence.test.js tests/lib/i18n-catalog.test.js tests/commands/cli-contract.test.js`: passed, 40 tests.
+- `node --test`: passed, 638 tests.
+- `npm run docs:check`: passed.
+- `git diff --check`: passed.
+
+## slice-06-namespace-compatibility-windows-scripts
+
+- `src/create-quiver/index.js`: adds canonical `slice start|check|pr|scope|cleanup|refresh-active` and `handoff check|new` namespace parsing while mapping to existing handlers.
+- `src/create-quiver/index.js`: preserves legacy top-level aliases and emits deprecation guidance to stderr only; warnings are suppressed for `--json` output.
+- `package.json`: adds PowerShell-safe `quiver:*` scripts that call the Node CLI directly and keeps existing Bash scripts as legacy compatibility paths.
+- `src/create-quiver/lib/init-layout.js`: generated project scripts now use canonical namespaces for slice and handoff commands.
+- `.github/workflows/ci.yml`: extends the Windows PowerShell smoke with canonical namespace commands and the portable `quiver:check-handoff` npm script.
+- `README.md`, `CONTRIBUTING.md`, `docs/reference/commands.md`, and `docs/COMMANDS.md.template`: document canonical namespaces, legacy alias policy, portable script guidance, and Windows-safe command paths.
+- `src/create-quiver/lib/i18n/messages/es.js`: adds Spanish help descriptions for the new canonical namespace entries.
+- `specs/quiver-v43-cli-i18n-audit-release-readiness/command-language-mode-matrix.json`: records canonical namespace command coverage for the i18n audit matrix.
+- `tests/commands/slice-namespace.test.js`: validates canonical/legacy slice parity, stderr-only legacy warnings, JSON warning suppression, and unsupported subcommand rejection.
+- `tests/commands/handoff-namespace.test.js`: validates canonical/legacy handoff parity, `handoff new` compatibility, and unsupported subcommand rejection.
+- `tests/commands/parser-contract.test.js`: validates help coverage and package script portability contracts.
+- `tests/commands/cli-contract.test.js` and `tests/lib/init-layout.test.js`: align public help and generated script contracts with canonical namespaces.
+- `node --test tests/commands/slice-namespace.test.js tests/commands/handoff-namespace.test.js tests/commands/parser-contract.test.js tests/commands/cli-contract.test.js tests/lib/init-layout.test.js tests/commands/i18n-audit-matrix.test.js tests/lib/i18n-catalog.test.js`: passed, 40 tests.
+- `npm ci`: passed; `package-lock.json` did not require changes because root package scripts are not represented in lockfile metadata.
+- `node bin/create-quiver.js slice check --local specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-00-cli-contract-baseline/slice.json && node bin/create-quiver.js handoff check specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-06-namespace-compatibility-windows-scripts/EXECUTION_BRIEF.md && npm run quiver:check-handoff -- specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-06-namespace-compatibility-windows-scripts/EXECUTION_BRIEF.md`: passed after dependency installation.
+- `npm run docs:check`: passed.
+- `git diff --check`: passed.
+- `node --test`: passed, 646 tests.
+- Windows PowerShell validation is configured in CI; local execution was performed on macOS using the same Node CLI entrypoints and package script contracts.

package/specs/quiver-v51-cli-ergonomics-automation-contracts/EXECUTION_PLAN.md

@@ -0,0 +1,32 @@
+# Execution Plan - Quiver v51 CLI Ergonomics and Automation Contracts
+
+## Order
+
+1. Execute `slice-00-cli-contract-baseline`.
+2. Execute `slice-01-flow-json-compatibility`.
+3. Execute `slice-02-dashboard-section-validation-i18n`.
+4. Execute `slice-03-base-branch-resolution-policy`.
+5. Execute `slice-04-next-plan-graph-ux-edge-cases`.
+6. Execute `slice-05-evidence-robustness-path-safety`.
+7. Execute `slice-06-namespace-compatibility-windows-scripts`.
+
+## Parallel Execution
+
+- `slice-01`, `slice-02`, `slice-04`, and `slice-05` can run in parallel after `slice-00` if they coordinate i18n catalog changes.
+- `slice-03` should be isolated because it touches shared Git/base behavior.
+- `slice-06` should run after or alongside CI hardening from v50 when Windows `pwsh` evidence is available.
+
+## Risk Controls
+
+- Preserve existing JSON fields.
+- Validate stdout/stderr separation for every warning and JSON change.
+- Add tests before or with behavior changes.
+- Close already-implemented findings with evidence instead of refactor.
+
+## Required Final Validation
+
+- `node --test`
+- `node bin/create-quiver.js --help`
+- Windows `pwsh` CI evidence or documented blocker
+- `git diff --check`
+- `node bin/create-quiver.js spec validate specs/quiver-v51-cli-ergonomics-automation-contracts`

package/specs/quiver-v51-cli-ergonomics-automation-contracts/SPEC.md

@@ -0,0 +1,109 @@
+# Quiver v51 - CLI Ergonomics and Automation Contracts
+
+**Date:** 2026-06-01
+**Status:** Planned
+**Source:** User-approved plan v4 derived from `REQUERIMIENTOS_DERIVADOS_DE_AUDITORIA.md`.
+
+Slice numbering resets here. This spec intentionally starts at `slice-00`.
+
+## Problem
+
+The audit identified CLI ergonomics and automation contract gaps around JSON output, dashboard validation, base branch defaults, next/plan/graph UX, evidence robustness, namespace compatibility, and Windows portability. Several related capabilities already exist and must be preserved by tests/evidence instead of reimplemented.
+
+## Objective
+
+Harden Quiver's CLI contracts for humans, scripts, agents, and production CI:
+
+- Add compatibility-safe JSON fields.
+- Localize and document dashboard validation.
+- Define one base branch resolution policy across related commands.
+- Close UX edge cases in `next`, `plan`, and `graph`.
+- Make evidence handling robust and path-safe.
+- Preserve namespace compatibility and make recommended npm scripts portable.
+
+## Scope
+
+### Included
+
+- CLI contract baseline for already-implemented findings.
+- `flow --json` `next_command` additive compatibility.
+- Dashboard `--section` validation/i18n/help.
+- Base branch policy for `spec close`, `ai pr`, `slice check`, `slice scope`, and related readiness flows.
+- `next`, `plan`, and `graph` UX edge cases.
+- Evidence run/list/show robustness, signals, redaction, truncation, and path safety.
+- Namespace parity, legacy stderr-only warnings, and Windows PowerShell script portability.
+
+### Excluded
+
+- Removing legacy aliases.
+- Breaking JSON contracts.
+- Rewriting parser.
+- Shell completion.
+- TypeScript.
+- Commander.js/yargs.
+
+## Approved Acceptance Criteria
+
+1. Already-implemented CLI findings are closed by evidence/tests/docs only.
+2. `flow --json` adds `next_command` while preserving `nextCommand`.
+3. `dashboard --section` errors are localized, actionable, and list real supported sections.
+4. Base branch resolution is consistent across all commands that use `--base`.
+5. `next`, `plan`, and `graph` edge cases are implemented or closed by evidence.
+6. Evidence commands preserve exit codes, redaction, truncation, safe paths, JSON contracts, and signal behavior.
+7. Canonical namespaces and legacy aliases remain compatible with warnings only on stderr.
+8. Recommended npm scripts/commands are portable under Windows PowerShell.
+
+## Execution Baseline - slice-00
+
+| Finding | Current state | Evidence | Action |
+|---|---|---|---|
+| `status` top-level command | implemented | `src/create-quiver/commands/status.js`; `tests/commands/status.test.js`. | Preserve current human/JSON and read-only contracts. |
+| `slice start/check/check-pr/scope/cleanup/refresh` plus legacy aliases | implemented | `src/create-quiver/commands/slice.js`; `src/create-quiver/lib/cli/command-registry.js`; `tests/commands/slice-namespace.test.js`. | Preserve canonical namespace, legacy aliases, and stderr-only deprecation warnings. |
+| `handoff check/create` plus legacy aliases | implemented | `src/create-quiver/commands/handoff.js`; `tests/commands/handoff-namespace.test.js`. | Preserve canonical namespace and stderr-only deprecation warnings. |
+| `evidence run/list/show` | implemented | `src/create-quiver/commands/evidence.js`; `src/create-quiver/lib/evidence.js`; `tests/commands/evidence.test.js`. | Freeze JSON schema version, redaction, truncation, path-safety, and exit-code contracts before `slice-05`. |
+| `demo spec-viewer` and `demo create spec-viewer` compatibility | implemented | `src/create-quiver/commands/demo.js`; `tests/commands/demo.test.js`. | Preserve both entrypoints and non-destructive scaffold behavior. |
+| AI command fragmentation | implemented | `src/create-quiver/commands/ai.js` delegates to `src/create-quiver/commands/ai/{agents,diagnostics,execution,inspection,lifecycle,planner}.js`. | Preserve split modules and compatibility aliases; no dispatcher rewrite in v51 baseline. |
+| `flow` human/stdout/JSON contract | partial | `src/create-quiver/commands/flow.js`; `tests/commands/flow.test.js`; current JSON contains `nextCommand` but not additive `next_command`. | Implement additive `next_command` in `slice-01-flow-json-compatibility`. |
+| `dashboard` invalid-section behavior and JSON constraints | partial | `src/create-quiver/lib/dashboard.js`; `tests/commands/dashboard.test.js`; invalid `--section` error is actionable but still English-only in observed behavior. | Implement localization/help hardening in `slice-02-dashboard-section-validation-i18n`. |
+| `plan` and `graph` UX edge cases | implemented | `tests/commands/plan.test.js`; `tests/commands/graph.test.js` cover missing estimates and empty level filters. | Close as evidence-only unless later validation proves a regression. |
+| Base branch resolution policy | partial | `src/create-quiver/lib/spec-worktrees.js`, `src/create-quiver/commands/ai/github.js`, and readiness helpers use related but not fully centralized fallback logic. | Implement single policy in `slice-03-base-branch-resolution-policy`. |
+| Windows npm script portability | partial | `package.json` still includes legacy Bash scripts (`check:slice`, `check:pr`, `start:slice`, `cleanup:slice`, `migrate`) alongside portable `quiver:*` scripts. | Implement or document portable script strategy in `slice-06-namespace-compatibility-windows-scripts`. |
+
+## Slice Roadmap
+
+| Slice | Title | Status | Dependencies |
+|---|---|---|---|
+| slice-00 | CLI contract baseline | completed | none |
+| slice-01 | Flow JSON compatibility | planned | slice-00 |
+| slice-02 | Dashboard section validation and i18n | planned | slice-00 |
+| slice-03 | Base branch resolution policy | planned | slice-00 |
+| slice-04 | Next/plan/graph UX edge cases | planned | slice-00 |
+| slice-05 | Evidence robustness and path safety | planned | slice-00 |
+| slice-06 | Namespace compatibility and Windows npm scripts | planned | slice-00 |
+
+## Guardrails
+
+- Add JSON fields, do not rename/remove existing fields.
+- Do not let warnings or deprecation messages contaminate JSON stdout.
+- Do not change command semantics for already-implemented findings unless the baseline proves a gap.
+- Keep `--base` explicit override highest priority.
+- Preserve evidence format unless a compatible migration is documented.
+- Keep aliases working.
+
+## Required Production Gates
+
+- targeted command tests
+- parser contract tests when flags change
+- stdout/stderr assertions for JSON, warnings, and errors
+- EN/ES validation for human messages
+- no-TTY/CI checks for prompts
+- Windows `pwsh` validation for portable scripts
+- `node --test`
+- `git diff --check`
+- `node bin/create-quiver.js spec validate specs/quiver-v51-cli-ergonomics-automation-contracts`
+
+## Open Decisions
+
+- Exact base branch fallback when no remote HEAD is available.
+- Exact policy for `evidence run --output` allowed paths.
+- Strategy for scripts Bash legacy: replace, wrap, or document as legacy.

package/specs/quiver-v51-cli-ergonomics-automation-contracts/STATUS.md

@@ -0,0 +1,25 @@
+# Status - Quiver v51 CLI Ergonomics and Automation Contracts
+
+**Overall status:** Completed, pending PR
+**Created:** 2026-06-01
+**Current slice:** slice-06-namespace-compatibility-windows-scripts completed
+
+## Summary
+
+This spec hardens CLI contracts for automation, JSON consumers, human UX, evidence handling, base branch behavior, and Windows portability. All planned slices are complete locally and pending the final slice PR review/merge.
+
+## Slice Status
+
+| Slice | Status | Notes |
+|---|---|---|
+| slice-00-cli-contract-baseline | Completed | Classified current CLI capabilities, froze implemented contracts, and routed partial gaps to later slices. |
+| slice-01-flow-json-compatibility | Completed | Added additive `next_command`, preserved `nextCommand`, documented compatibility, and tested matching values in representative JSON states. |
+| slice-02-dashboard-section-validation-i18n | Completed | Localized and documented invalid dashboard section behavior with EN/ES tests, JSON-safe failure coverage, and supported section help/reference docs. |
+| slice-03-base-branch-resolution-policy | Completed | Centralized base branch resolution across readiness, spec lifecycle, scope, and AI PR flows. |
+| slice-04-next-plan-graph-ux-edge-cases | Completed | Closed next/plan/graph secondary UX gaps with localized human notes, JSON-safe tests, and docs alignment. |
+| slice-05-evidence-robustness-path-safety | Completed | Hardened evidence command contracts, safe paths, signal metadata, JSON list/show, docs, and i18n matrix coverage. |
+| slice-06-namespace-compatibility-windows-scripts | Completed | Added canonical `slice`/`handoff` namespaces, preserved legacy aliases with stderr-only warnings, documented portable scripts, and added Windows CI smoke coverage. |
+
+## Current Blockers
+
+- None. Final slice is ready for PR review after local gates.

package/specs/quiver-v51-cli-ergonomics-automation-contracts/pr.md

@@ -0,0 +1,69 @@
+## Title
+
+QUIVER-51: CLI Ergonomics and Automation Contracts planning baseline
+
+## Summary
+
+Adds the Quiver v51 CLI Ergonomics and Automation Contracts spec package and closes its `slice-00` baseline.
+
+The baseline freezes current CLI contracts for implemented commands and routes partial gaps to later slices: `flow --json` additive compatibility, dashboard section i18n, base branch policy, evidence robustness, and Windows script portability.
+
+## Scope
+
+- Adds the v51 spec documentation, status, evidence report, slices, and per-slice handoff briefs.
+- Marks `slice-00-cli-contract-baseline` as completed.
+- Records current CLI command contracts and compatibility constraints.
+- Does not modify runtime code.
+
+## Files
+
+- `specs/quiver-v51-cli-ergonomics-automation-contracts/SPEC.md`
+- `specs/quiver-v51-cli-ergonomics-automation-contracts/STATUS.md`
+- `specs/quiver-v51-cli-ergonomics-automation-contracts/EVIDENCE_REPORT.md`
+- `specs/quiver-v51-cli-ergonomics-automation-contracts/pr.md`
+- `specs/quiver-v51-cli-ergonomics-automation-contracts/slices/**`
+
+## How to Test (DETAILED - REQUIRED)
+
+### Required Environment
+
+- Node.js available locally.
+- Repository checkout with Quiver CLI scripts available.
+- GitHub CLI is not required to validate the spec contents.
+
+### Worktree Access
+
+- Checkout this PR branch.
+- Confirm no runtime source files are changed by this PR.
+
+### Run the Project
+
+No application runtime needs to be started; this PR is documentation/spec planning only.
+
+### Use Cases
+
+- Review the v51 CLI baseline table in `SPEC.md`.
+- Confirm implemented findings are evidence-only.
+- Confirm partial gaps are routed to `slice-01` through `slice-06`.
+
+### Technical Verification
+
+```bash
+git diff --check
+node bin/create-quiver.js spec validate specs/quiver-v51-cli-ergonomics-automation-contracts
+```
+
+## Evidence
+
+- `git diff --check`: passed.
+- `node bin/create-quiver.js spec validate specs/quiver-v51-cli-ergonomics-automation-contracts`: passed.
+- Runtime code was not modified.
+
+## Rollback
+
+Remove `specs/quiver-v51-cli-ergonomics-automation-contracts/` and revert the commit.
+
+## Risks / Notes
+
+- This PR intentionally excludes local audit inputs, PDFs, copy docs, and other root-level untracked files.
+- Follow-up implementation must start from `slice-01-flow-json-compatibility`.

package/specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-00-cli-contract-baseline/CLOSURE_BRIEF.md

@@ -0,0 +1,20 @@
+# CLOSURE_BRIEF - slice-00 CLI contract baseline
+
+## Summary
+
+Classified current v51 CLI contracts and routed implemented, partial, and missing work to the correct later slices. Runtime code was not changed.
+
+## Validation
+
+- [x] `git diff --check`
+- [x] `node bin/create-quiver.js spec validate specs/quiver-v51-cli-ergonomics-automation-contracts`
+
+## Closure Conditions
+
+- [x] Current CLI contracts classified.
+- [x] Implemented findings marked evidence/test/docs only.
+- [x] Runtime code unchanged.
+
+## Open Items
+
+- None.

package/specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-00-cli-contract-baseline/EXECUTION_BRIEF.md

@@ -0,0 +1,58 @@
+# EXECUTION_BRIEF - slice-00 CLI contract baseline
+
+## Context
+
+Several CLI findings from the audit are already implemented in the current branch. This slice prevents duplicate work.
+
+## Objective
+
+Validate current CLI capabilities and classify v51 findings before implementation.
+
+## Scope
+
+- Current command/help/JSON behavior.
+- Finding classification.
+- Planning artifacts only.
+
+## Acceptance Criteria
+
+- A `Finding | Current state | Action` table exists.
+- Implemented findings are mapped to evidence/test/docs only.
+- Missing/partial findings are mapped to later slices.
+- Runtime code is unchanged.
+
+## Expected Files To Modify
+
+- `specs/quiver-v51-cli-ergonomics-automation-contracts/SPEC.md`
+- `specs/quiver-v51-cli-ergonomics-automation-contracts/STATUS.md`
+- `specs/quiver-v51-cli-ergonomics-automation-contracts/EVIDENCE_REPORT.md`
+
+## Validations Required
+
+- `git diff --check`
+- `node bin/create-quiver.js spec validate specs/quiver-v51-cli-ergonomics-automation-contracts`
+
+## Risks
+
+- Reimplementing stable CLI behavior.
+- Missing a current contract that later slices break.
+
+## Dependencies
+
+- None.
+
+## Instructions For Executor
+
+1. Run representative commands and capture behavior.
+2. Classify each v51 finding.
+3. Do not modify runtime code.
+
+## Completion Checklist
+
+- [ ] Acceptance criteria satisfied.
+- [ ] Required validations run or blockers documented.
+- [ ] Closure brief updated.
+
+## Conditions Of Closure
+
+- v51 implementation slices have a precise CLI baseline.

package/specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-00-cli-contract-baseline/slice.json

@@ -0,0 +1,56 @@
+{
+  "slice_id": "slice-00-cli-contract-baseline",
+  "ticket": "QUIVER-51-00",
+  "type": "documentation",
+  "title": "CLI contract baseline",
+  "objective": "Validate current CLI capabilities and classify v51 findings before implementation.",
+  "description": "Records which CLI findings are already implemented, partial, missing, or not applicable so later slices avoid duplicate refactors.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v51-cli-contract-baseline",
+    "branch_name": "feature/QUIVER-51-00-v51-cli-contract-baseline"
+  },
+  "files": [
+    "specs/quiver-v51-cli-ergonomics-automation-contracts/**"
+  ],
+  "expected_read_paths": [
+    "REQUERIMIENTOS_DERIVADOS_DE_AUDITORIA.md",
+    "src/create-quiver/index.js",
+    "src/create-quiver/commands/**",
+    "tests/commands/**",
+    "package.json"
+  ],
+  "allowed_write_paths": [
+    "specs/quiver-v51-cli-ergonomics-automation-contracts/**"
+  ],
+  "depends_on": [],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Baseline defines implementation vs validation-only actions for all v51 slices.",
+  "must": [
+    "Create a Finding | Current state | Action table.",
+    "Validate current status, namespaces, evidence list/show, demo spec-viewer, and AI fragmentation.",
+    "Freeze relevant JSON and stdout/stderr contracts.",
+    "Do not modify runtime code."
+  ],
+  "not_included": [
+    "Implementing CLI changes."
+  ],
+  "acceptance": [
+    "Already-implemented findings are marked evidence/test/docs only.",
+    "Missing and partial findings are routed to later slices.",
+    "Runtime code remains unchanged."
+  ],
+  "tests": [
+    "git diff --check",
+    "node bin/create-quiver.js spec validate specs/quiver-v51-cli-ergonomics-automation-contracts"
+  ],
+  "validation_hints": [
+    "Use command outputs as evidence, not assumptions from the audit."
+  ],
+  "estimated_hours": 2,
+  "status": "completed",
+  "blocked_reason": null,
+  "actual_hours": 2,
+  "completed_at": "2026-06-01T21:37:54-0300"
+}

package/specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-01-flow-json-compatibility/CLOSURE_BRIEF.md

@@ -0,0 +1,21 @@
+# CLOSURE_BRIEF - slice-01 flow JSON compatibility
+
+## Summary
+
+Implemented additive `flow --json` compatibility by emitting `next_command` with the same value as the existing `nextCommand` field. Human output semantics are unchanged.
+
+## Validation
+
+- [x] `node --test tests/commands/flow.test.js`
+- [x] `node --test`
+- [x] `git diff --check`
+
+## Closure Conditions
+
+- [x] `next_command` added.
+- [x] `nextCommand` preserved.
+- [x] Compatibility documented and tested.
+
+## Open Items
+
+- None.

package/specs/quiver-v51-cli-ergonomics-automation-contracts/slices/slice-01-flow-json-compatibility/EXECUTION_BRIEF.md

@@ -0,0 +1,61 @@
+# EXECUTION_BRIEF - slice-01 flow JSON compatibility
+
+## Context
+
+`flow --json` currently exposes `nextCommand`. The audit requires `next_command` for stable agent consumption, but existing consumers must not break.
+
+## Objective
+
+Add snake_case `next_command` to flow JSON without breaking existing `nextCommand` consumers.
+
+## Scope
+
+- `flow --json`.
+- Compatibility docs.
+- Flow tests.
+
+## Acceptance Criteria
+
+- `next_command` exists in JSON output.
+- `nextCommand` remains.
+- Values match when present.
+- Both are null or documented consistently when no next command exists.
+- Human output remains compatible.
+
+## Expected Files To Modify
+
+- `src/create-quiver/commands/flow.js`
+- `docs/reference/commands.md`
+- `tests/commands/flow.test.js`
+- `specs/quiver-v51-cli-ergonomics-automation-contracts/EVIDENCE_REPORT.md`
+
+## Validations Required
+
+- `node --test tests/commands/flow.test.js`
+- `node --test`
+- `git diff --check`
+
+## Risks
+
+- Breaking existing `nextCommand` users.
+- Adding inconsistent values across states.
+
+## Dependencies
+
+- Depends on `slice-00-cli-contract-baseline`.
+
+## Instructions For Executor
+
+1. Make the JSON change additive only.
+2. Add tests for representative states.
+3. Document compatibility and do not remove legacy field.
+
+## Completion Checklist
+
+- [ ] Acceptance criteria satisfied.
+- [ ] Required validations run or blockers documented.
+- [ ] Closure brief updated.
+
+## Conditions Of Closure
+
+- Flow JSON supports both snake_case and legacy camelCase consumers.