create-quiver 0.14.0 → 0.14.1

package/docs/workflows/legacy-quiver-project.md

@@ -0,0 +1,102 @@
+# Flujo para proyecto con Quiver anterior
+
+Usá este flujo cuando el proyecto ya tiene archivos de Quiver creados por una versión anterior.
+
+## 1. Entrar al proyecto
+
+```bash
+cd /ruta/al/proyecto
+git status -sb
+```
+
+Qué hace:
+
+- revisa la rama actual y los cambios pendientes.
+
+## 2. Ejecutar doctor
+
+```bash
+npx --yes create-quiver@latest doctor
+```
+
+Qué hace:
+
+- detecta si el proyecto está inicializado, incompleto, legacy, híbrido o sano.
+
+## 3. Previsualizar migración
+
+```bash
+npx --yes create-quiver@latest migrate --dry-run
+```
+
+Qué hace:
+
+- muestra qué actualizaría Quiver;
+- evita escribir archivos.
+
+## 4. Aplicar migración
+
+```bash
+npx --yes create-quiver@latest migrate
+```
+
+Qué hace:
+
+- actualiza documentación y estado interno de Quiver;
+- preserva archivos existentes del proyecto;
+- mantiene la migración lo más aditiva posible.
+
+Usá esta variante si no querés instalar dependencias:
+
+```bash
+npx --yes create-quiver@latest migrate --skip-install
+```
+
+## 5. Reconstruir contexto del proyecto
+
+```bash
+npx --yes create-quiver@latest analyze
+npx --yes create-quiver@latest doctor
+```
+
+Qué hace:
+
+- refresca `docs/PROJECT_MAP.md`;
+- confirma que la estructura migrada esté sana.
+
+## 6. Preparar contexto para IA
+
+```bash
+npx --yes create-quiver@latest ai prepare-context --dry-run
+npx --yes create-quiver@latest ai prepare-context
+```
+
+Modo asistido por planner, útil cuando el contexto anterior quedó desactualizado:
+
+```bash
+npx --yes create-quiver@latest ai prepare-context --with-planner --dry-run
+npx --yes create-quiver@latest ai prepare-context --with-planner --review --interactive
+```
+
+Qué hace:
+
+- actualiza contexto de onboarding de forma segura;
+- reporta supuestos y contradicciones.
+
+## 7. Commit de migración
+
+```bash
+git status -sb
+git add AGENTS.md docs .quiver .gitignore package.json package-lock.json
+git commit -m "docs: migrate quiver workflow"
+```
+
+Qué hace:
+
+- crea una base estable antes de empezar specs nuevas.
+
+Ajustá los paths según lo que haya informado la migración.
+
+Siguiente paso:
+
+- [Ejecutar el flujo completo de spec a PR con IA](./full-ai-spec-to-pr.md)

package/docs/workflows/new-project.md

@@ -0,0 +1,76 @@
+# Flujo para proyecto nuevo
+
+Usá este flujo cuando el repositorio todavía no existe o la carpeta está vacía.
+
+## 1. Crear la carpeta del proyecto
+
+```bash
+mkdir mi-proyecto
+cd mi-proyecto
+git init
+```
+
+Qué hace:
+
+- crea una carpeta para el proyecto;
+- inicializa Git para que Quiver pueda razonar sobre cambios y worktrees.
+
+## 2. Inicializar Quiver
+
+```bash
+npx --yes create-quiver@latest init --name "Mi Proyecto"
+```
+
+Qué hace:
+
+- crea el contrato visible de Quiver;
+- crea el estado interno en `.quiver/`;
+- agrega scripts `quiver:*` cuando existe o se crea `package.json`.
+
+## 3. Revisar el próximo paso
+
+```bash
+npx --yes create-quiver@latest flow
+```
+
+Qué hace:
+
+- muestra el estado actual del workflow;
+- recomienda el próximo comando seguro.
+
+## 4. Analizar y validar
+
+```bash
+npx --yes create-quiver@latest analyze
+npx --yes create-quiver@latest doctor
+```
+
+Qué hace:
+
+- crea o actualiza `docs/PROJECT_MAP.md`;
+- refresca el contexto para IA;
+- valida que el contrato de Quiver esté sano.
+
+## 5. Preparar contexto para IA
+
+```bash
+npx --yes create-quiver@latest ai prepare-context --dry-run
+npx --yes create-quiver@latest ai prepare-context
+```
+
+Modo asistido por planner, si querés que una IA proponga el contexto:
+
+```bash
+npx --yes create-quiver@latest ai prepare-context --with-planner --dry-run
+npx --yes create-quiver@latest ai prepare-context --with-planner --review --interactive
+```
+
+Qué hace:
+
+- previsualiza cambios documentales de onboarding;
+- escribe la documentación de contexto después de revisar;
+- evita cambios en código de producto.
+
+Siguiente paso:
+
+- [Ejecutar el flujo completo de spec a PR con IA](./full-ai-spec-to-pr.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-quiver",
-  "version": "0.14.0",
+  "version": "0.14.1",
   "private": false,
   "description": "Quiver CLI for scaffolding projects from the packaged template",
   "license": "MIT",
@@ -49,5 +49,9 @@
     "smoke:tiered-pack": "bash scripts/ci/smoke-tiered-pack.sh",
     "smoke:guided-workflow": "bash scripts/ci/smoke-guided-workflow.sh",
     "release:quiver": "bash scripts/release-quiver.sh"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.4.0",
+    "zod": "^4.4.3"
   }
 }

package/specs/quiver-v29-planner-prepare-context-cli-ux/EVIDENCE_REPORT.md

@@ -0,0 +1,163 @@
+# Evidence Report - Quiver v29 Planner Prepare Context CLI UX
+
+**Status:** Initial documentation package evidence
+**Date:** 2026-05-26
+
+## Scope
+
+This evidence report currently covers creation of the approved spec/slice package only. Implementation evidence must be appended by each execution slice.
+
+## Commands Run During Spec Creation
+
+```bash
+find specs/quiver-v29-planner-prepare-context-cli-ux -name 'slice.json' -print -exec node -e "JSON.parse(require('fs').readFileSync(process.argv[1], 'utf8')); console.log('ok ' + process.argv[1])" {} \;
+git diff --check
+for f in specs/quiver-v29-planner-prepare-context-cli-ux/slices/*/EXECUTION_BRIEF.md specs/quiver-v29-planner-prepare-context-cli-ux/slices/*/CLOSURE_BRIEF.md; do node bin/create-quiver.js check-handoff "$f" >/dev/null || exit 1; done; echo "handoff briefs ok"
+node bin/create-quiver.js spec validate specs/quiver-v29-planner-prepare-context-cli-ux
+```
+
+## Results
+
+- `slice-00-cli-ux-spec-foundation` completed as the documentation foundation slice.
+- Every `slice.json` parsed successfully.
+- `git diff --check` passed.
+- Every `EXECUTION_BRIEF.md` and `CLOSURE_BRIEF.md` passed `check-handoff` after normalizing the required `Acceptance Criteria` heading.
+- Initial `spec validate` reported this file as missing; this report was added to satisfy the spec validation contract.
+- `node bin/create-quiver.js spec validate specs/quiver-v29-planner-prepare-context-cli-ux` passed after adding this report.
+
+## Pending Evidence
+
+Implementation slices must append:
+
+- focused unit tests;
+- command integration tests;
+- CI/no-TTY/JSON validation;
+- package smoke;
+- tarball dry-run;
+- final docs sync validation.
+
+## slice-01-cli-ux-primitives-theme Evidence
+
+**Date:** 2026-05-26
+**Status:** Passed
+
+### Commands
+
+```bash
+node --test tests/lib/cli-theme.test.js tests/lib/cli-ux.test.js tests/lib/cli-editor.test.js
+npm run package:quiver
+git diff --check
+```
+
+### Results
+
+- `node --test tests/lib/cli-theme.test.js tests/lib/cli-ux.test.js tests/lib/cli-editor.test.js` passed with 18 tests.
+- `npm run package:quiver` passed and produced package smoke output for `create-quiver-0.14.0.tgz`.
+- `git diff --check` passed.
+- Dependencies were added through npm so `package-lock.json` records the resolved package metadata.
+
+## slice-02-planner-context-proposal-contract Evidence
+
+**Date:** 2026-05-26
+**Status:** Passed
+
+### Commands
+
+```bash
+node --test tests/lib/ai-context-proposal.test.js
+```
+
+### Results
+
+- `node --test tests/lib/ai-context-proposal.test.js` passed with 8 tests.
+- Fixtures cover valid JSON, fenced JSON, malformed output, product-code path, absolute path, and path traversal.
+- The slice did not invoke providers and did not modify `runPrepareContext` write behavior.
+
+## slice-04-ux-flag-matrix-compatibility Evidence
+
+**Date:** 2026-05-26
+**Status:** Passed
+
+### Commands
+
+```bash
+node --test tests/commands/ux-flags.test.js tests/commands/cli-contract.test.js tests/lib/cli-ux.test.js
+```
+
+### Results
+
+- `node --test tests/commands/ux-flags.test.js tests/commands/cli-contract.test.js tests/lib/cli-ux.test.js` passed with 22 tests.
+- Tests cover matrix support, unsupported flags, incompatible `--json` combinations, read-only commands, `ai pr --with-planner`, and parseable JSON output for existing commands.
+
+## slice-03-prepare-context-planner-review-flow Evidence
+
+**Date:** 2026-05-26
+**Status:** Passed
+
+### Commands
+
+```bash
+node --test tests/commands/ai-onboard.test.js tests/commands/ai-prepare-context-planner.test.js tests/lib/ai-context-proposal.test.js
+node --test tests/commands/ux-flags.test.js tests/commands/cli-contract.test.js tests/lib/cli-ux.test.js
+git diff --check
+```
+
+### Results
+
+- `node --test tests/commands/ai-onboard.test.js tests/commands/ai-prepare-context-planner.test.js tests/lib/ai-context-proposal.test.js` passed with 25 tests.
+- `node --test tests/commands/ux-flags.test.js tests/commands/cli-contract.test.js tests/lib/cli-ux.test.js` passed with 22 tests.
+- Tests cover deterministic compatibility, planner dry-run, prompt printing, provider success, provider failure, invalid planner output, review cancellation, review edit/revalidation, and interactive decline.
+- `git diff --check` passed.
+
+## slice-05-progressive-command-adoption Evidence
+
+**Date:** 2026-05-26
+**Status:** Passed
+
+### Commands
+
+```bash
+node --test tests/commands/ai-plan.test.js tests/commands/spec-create.test.js tests/commands/ai-pr.test.js tests/commands/ux-flags.test.js
+```
+
+### Results
+
+- `node --test tests/commands/ai-plan.test.js tests/commands/spec-create.test.js tests/commands/ai-pr.test.js tests/commands/ux-flags.test.js` passed with 46 tests.
+- Tests cover `ai plan` UX flags, draft review, interactive decline, `spec create --review`, `spec create --interactive`, `ai pr --review`, `ai pr --interactive`, and the central unsupported flag matrix.
+
+## slice-06-docs-tests-smoke-readiness Evidence
+
+**Date:** 2026-05-26
+**Status:** Passed
+
+### Commands
+
+```bash
+node --test tests/commands/ai-prepare-context-planner.test.js tests/commands/ai-plan.test.js tests/commands/spec-create.test.js tests/commands/ai-pr.test.js tests/commands/ux-flags.test.js tests/commands/cli-contract.test.js tests/lib/cli-theme.test.js tests/lib/cli-ux.test.js tests/lib/cli-editor.test.js tests/lib/ai-context-proposal.test.js
+node bin/create-quiver.js --help >/tmp/quiver-help.txt && rg -- '--with-planner|--interactive|--review|--no-color' /tmp/quiver-help.txt
+node --test tests/**/*.test.js
+npm run smoke:create-quiver
+npm run smoke:doctor-fixtures
+npm run smoke:guided-workflow
+npm run package:quiver
+npm pack --dry-run
+git diff --check
+node bin/create-quiver.js spec validate specs/quiver-v29-planner-prepare-context-cli-ux
+```
+
+### Results
+
+- Focused command/UX validation passed with 87 tests and confirmed the public help includes `--with-planner`, `--interactive`, `--review`, and `--no-color`.
+- Full test suite passed with 426 tests.
+- `npm run smoke:create-quiver` passed.
+- `npm run smoke:doctor-fixtures` passed with 13 fixture states.
+- `npm run smoke:guided-workflow` passed.
+- `npm run package:quiver` passed and validated package safety.
+- `npm pack --dry-run` passed and produced a clean dry-run tarball report for `create-quiver@0.14.0`.
+- `git diff --check` passed.
+- `node bin/create-quiver.js spec validate specs/quiver-v29-planner-prepare-context-cli-ux` passed after closure metadata updates.
+
+### Notes
+
+- Npm printed a non-blocking update notice for npm `11.12.1 -> 11.15.0`.
+- Publishing and PR creation remain outside this slice.

package/specs/quiver-v29-planner-prepare-context-cli-ux/EXECUTION_PLAN.md

@@ -0,0 +1,72 @@
+# Execution Plan - Quiver v29 Planner Prepare Context CLI UX
+
+## Execution Order
+
+```mermaid
+flowchart TD
+    S00[slice-00: CLI UX spec foundation]
+    S01[slice-01: CLI UX primitives, theme, and dependencies]
+    S02[slice-02: Planner context proposal contract]
+    S03[slice-03: Planner-assisted prepare-context review flow]
+    S04[slice-04: UX flag matrix and compatibility guardrails]
+    S05[slice-05: Progressive command adoption]
+    S06[slice-06: Docs, tests, smoke, and release readiness]
+
+    S00 --> S01
+    S01 --> S02
+    S01 --> S04
+    S02 --> S03
+    S04 --> S03
+    S03 --> S05
+    S04 --> S05
+    S02 --> S06
+    S03 --> S06
+    S04 --> S06
+    S05 --> S06
+```
+
+## Waves
+
+### Wave 0 - Sequential
+
+1. `slice-00-cli-ux-spec-foundation`
+
+This slice must run first. It establishes the approved UX standard, command/flag matrix, and documentation contract.
+
+### Wave 1 - Sequential
+
+1. `slice-01-cli-ux-primitives-theme`
+
+This slice adds shared UX infrastructure and dependencies. Other implementation slices depend on this common layer.
+
+### Wave 2 - Parallel after slice-01
+
+- `slice-02-planner-context-proposal-contract`
+- `slice-04-ux-flag-matrix-compatibility`
+
+These can run in parallel if their write scopes stay separated: proposal validation under AI libs, flag/output guardrails under CLI parsing and UX helpers.
+
+### Wave 3 - Sequential
+
+1. `slice-03-prepare-context-planner-review-flow`
+
+This slice depends on the proposal contract and UX compatibility rules.
+
+### Wave 4 - Sequential
+
+1. `slice-05-progressive-command-adoption`
+
+This slice applies the standard to selected commands after `ai prepare-context` proves the pattern.
+
+### Wave 5 - Sequential close
+
+1. `slice-06-docs-tests-smoke-readiness`
+
+This slice closes docs, generated templates, validation coverage, package smoke, and release readiness.
+
+## Parallel Safety Notes
+
+- Do not run `slice-03` before `slice-02` and `slice-04` are complete.
+- Do not run `slice-05` before `slice-03`; progressive adoption should reuse the proven prepare-context pattern.
+- `slice-06` is never parallel-safe because it validates all previous slices and updates final documentation.
+- If `slice-02` or `slice-04` both need to modify central CLI parsing, run `slice-04` first, then rebase `slice-02`.

package/specs/quiver-v29-planner-prepare-context-cli-ux/SPEC.md

@@ -0,0 +1,173 @@
+# Quiver v29 - Planner-Assisted Prepare Context and CLI UX Standard
+
+**Date:** 2026-05-26
+**Status:** Planned
+**Source:** User-approved requirement to improve `ai prepare-context` with optional planner IA and standardize CLI UX across Quiver.
+
+Slice numbering resets here. This spec intentionally starts at `slice-00`.
+
+## Problem
+
+`npx create-quiver ai prepare-context` is currently safe and deterministic: it prepares docs-only context using templates and project signals. That behavior must remain, but Quiver also needs an explicit planner-assisted mode where a configured planner IA can analyze project context and propose richer onboarding documentation.
+
+At the same time, Quiver's CLI UX has grown command by command. It needs a shared standard for loaders, prompts, visual hierarchy, review flows, flags, color usage, non-interactive execution, CI, `--json`, agents, and errors. Without a standard, each new AI command risks solving UX differently.
+
+## Objective
+
+Create a CLI UX standard for Quiver and implement the first high-value application of it:
+
+- keep `ai prepare-context` deterministic by default;
+- add explicit planner-assisted preparation;
+- add safe interactive/review flows;
+- validate planner output before writes;
+- standardize output modes, colors, prompts, loaders, and flags;
+- apply the standard progressively to selected commands.
+
+## Scope
+
+### Included
+
+- UX standard documentation for Quiver CLI commands.
+- Shared CLI UX/theme/editor helpers.
+- Quiver color tokens for human-mode output.
+- Optional `--with-planner` mode for `ai prepare-context`.
+- Optional `--interactive` and `--review` flows where they add value.
+- `--print-prompt`, `--dry-run`, `--json`, CI, no-TTY, no-color compatibility.
+- Planner proposal contract validated with a structured schema.
+- Docs-only allowlist for context writes.
+- `$EDITOR` review before applying AI-generated documentation.
+- Progressive adoption plan for `ai plan`, `spec create`, and `ai pr`.
+- Tests, fixtures, documentation, and package smoke readiness.
+
+### Excluded
+
+- Replacing the whole CLI parser with `commander`, `yargs`, or `oclif`.
+- Adding terminal dashboards with `ink`, `blessed`, or `neo-blessed`.
+- Adding image output protocols.
+- Migrating tests from `node:test` to `vitest`.
+- Storing provider credentials.
+- Allowing planner IA to modify product code.
+- Making interactive prompts mandatory.
+
+## Approved Acceptance Criteria
+
+### Prepare-context modes
+
+1. Given a project with Quiver initialized, when `npx create-quiver ai prepare-context --dry-run` runs, then Quiver keeps the current deterministic behavior, invokes no provider, writes no files, and shows the proposed docs plan.
+2. Given a user runs `npx create-quiver ai prepare-context` without new flags, when the command finishes, then it writes only allowed context docs and does not modify product code.
+3. Given a planner profile or explicit provider is available, when `npx create-quiver ai prepare-context --with-planner --dry-run` runs, then Quiver shows provider invocation, context inputs, candidate docs, and no writes.
+4. Given the user has reviewed dry-run output, when `npx create-quiver ai prepare-context --with-planner` runs, then Quiver invokes the planner, validates the output, and applies only allowed docs-only changes.
+5. Given the user wants to use another AI environment, when `--with-planner --print-prompt` is used, then Quiver prints the exact prompt and exits without provider auth or writes.
+6. Given planner output suggests docs updates, when Quiver evaluates it, then only allowed context docs can be written.
+7. Given planner output attempts product-code, dependency, build, test, lockfile, runtime, absolute, traversal, or outside-repo writes, when Quiver validates it, then the command blocks those writes and reports why.
+8. Given the command writes docs, when it completes, then it snapshots touched docs under `.quiver/runs/<run-id>/snapshots/` and reports files, assumptions, risks, and generation source.
+9. Given provider CLI fails, is missing, or is unauthenticated, when planner mode runs, then Quiver shows an actionable error and writes no partial changes.
+10. Given planner output is incomplete, ambiguous, or invalid, when Quiver processes it, then Quiver does not write files automatically and reports the next safe step.
+
+### CLI UX standard
+
+11. Given the new behavior, when docs are reviewed, then README, command reference, templates, and `README_FOR_AI.md` explain deterministic mode, planner-assisted mode, and safe usage.
+12. Given the new command surface, when tests run, then there is coverage for deterministic mode, planner dry-run, prompt printing, provider failure, invalid output, path blocking, docs-only writes, TTY/no-TTY, CI, and `--json`.
+13. Given any command uses UX output, when it runs, then it clearly indicates whether it is deterministic, planner-assisted, interactive, review, dry-run, or machine mode.
+14. Given multiple docs or checks are proposed, when human output is shown, then Quiver groups files, actions, risks, and next steps with clear visual hierarchy.
+15. Given `--json`, CI, or stdout/stderr redirection, when output is produced, then no spinners, prompts, colors, or decorative symbols appear in machine-readable output.
+16. Given a command supports `--review`, when a proposal exists, then Quiver opens `$VISUAL` or `$EDITOR`; if neither is available, it leaves an artifact path and gives a manual next step.
+17. Given a command supports prompts, when `--interactive` is not used, then it must not block for interactive choices except already documented confirmations.
+18. Given a prompt is added, when automation is needed, then equivalent non-interactive flags must exist.
+19. Given a command uses loaders, when it runs in human TTY mode, then loaders appear only for slow stages and never hide errors.
+20. Given an output uses colors, when colors are disabled or unsupported, then the output remains readable.
+
+### Standard flags and visual identity
+
+21. Given the UX standard, when docs are reviewed, then `--with-planner`, `--interactive`, and `--review` are defined with purpose, rules, and applicable commands.
+22. Given a command is evaluated for those flags, when there is no generation, human decision, review, or planner value, then the command must not expose decorative flags.
+23. Given `--with-planner --review` runs on a command that writes persistent AI-generated docs, then Quiver generates, validates, opens for human review, revalidates, and applies only allowed changes after approval.
+24. Given unsupported UX flags are used on a command, then Quiver fails early with a clear explanation and an alternative command.
+25. Given the Quiver CLI uses loaders, states, badges, or highlighted sections, when colors are enabled, then it uses the Quiver palette consistently:
+    - `quiver.sky` `#86C8F2`
+    - `quiver.blue` `#6BADEB`
+    - `quiver.periwinkle` `#7F9EE8`
+    - `quiver.violet` `#9B82E6`
+    - `quiver.magenta` `#D56AB0`
+26. Given semantic status output is needed, then success/error/warning semantics remain clear and are not replaced blindly by brand colors.
+27. Given a migrated command shows output, then colors and symbols come from centralized helpers, not command-local hardcoding.
+
+## Approved Technical Plan
+
+1. Keep the current no-IA `ai prepare-context` behavior as the default.
+2. Add shared CLI UX helpers behind a small internal abstraction before command adoption.
+3. Add Quiver theme tokens and no-color/CI/no-TTY detection.
+4. Add `$EDITOR` review support with safe fallback.
+5. Add a planner context proposal contract and schema validation.
+6. Add planner-assisted `ai prepare-context` flow with `--with-planner`, `--print-prompt`, `--dry-run`, `--review`, and `--interactive`.
+7. Add strict docs-only allowlist and path safety for planner-generated writes.
+8. Improve human output with loaders and hierarchy only where safe.
+9. Preserve clean JSON output and automation behavior.
+10. Apply the UX flag standard first to `ai prepare-context`, then selected parts of `ai plan`, `spec create`, and `ai pr`.
+11. Document the standard and update generated templates.
+12. Add tests and package/tarball smoke coverage.
+
+## Command/Flag Matrix
+
+| Command | `--with-planner` | `--interactive` | `--review` | Scope in this spec |
+|---|---:|---:|---:|---|
+| `ai prepare-context` | yes | yes | yes | Full implementation |
+| `ai plan` | yes | yes | yes | Progressive adoption and contract alignment |
+| `spec create` | yes | yes | yes | Progressive adoption and guardrails |
+| `ai pr` | no | yes | yes | Review/edit PR body and interactive inputs |
+| `ai onboard` | implicit planner | future | future | Documented follow-up |
+| `ai revise` | future | future | future | Documented follow-up |
+| `ai review-plan` | no planner flag | future | future | Documented follow-up |
+| `doctor` | no | future for fixes | no | Documented follow-up |
+| `flow`, `next`, `graph`, `ai inspect`, `ai export`, list commands | no | no | no | Must remain read-only/scriptable |
+
+## Tools and Dependency Decisions
+
+- Adopt `zod` for validating planner proposal contracts.
+- Adopt `@clack/prompts` behind internal helpers for interactive prompts and human-mode spinners.
+- Use Node native process spawning for `$EDITOR`.
+- Do not adopt `commander`, `yargs`, or `oclif` in this spec.
+- Do not adopt `ink`, `blessed`, `neo-blessed`, terminal image protocols, or `vitest` in this spec.
+
+## Slice Roadmap
+
+| Slice | Title | Status | Dependencies |
+|---|---|---|---|
+| slice-00 | CLI UX spec foundation | completed | none |
+| slice-01 | CLI UX primitives, theme, and dependencies | completed | slice-00 |
+| slice-02 | Planner context proposal contract | completed | slice-01 |
+| slice-03 | Planner-assisted prepare-context review flow | completed | slice-01, slice-02 |
+| slice-04 | UX flag matrix and compatibility guardrails | completed | slice-01 |
+| slice-05 | Progressive command adoption | completed | slice-03, slice-04 |
+| slice-06 | Docs, tests, smoke, and release readiness | completed | slice-02, slice-03, slice-04, slice-05 |
+
+## Validation Strategy
+
+- `node --test tests/**/*.test.js`
+- focused command tests for `ai prepare-context`
+- focused tests for UX mode detection and theme fallback
+- focused tests for planner proposal schema/path validation
+- focused tests for editor review cancellation and invalid edit fallback
+- `npm run smoke:create-quiver`
+- `npm run smoke:doctor-fixtures`
+- `npm run smoke:guided-workflow`
+- `npm run package:quiver`
+- `npm pack --dry-run`
+- `git diff --check`
+- `npx create-quiver check-handoff` for all slice briefs
+- JSON parse validation for all `slice.json` files
+
+## Risks
+
+- New dependencies may affect startup time, CJS/ESM compatibility, and package size.
+- Visual output can break automation unless strictly disabled for `--json`, CI, no-TTY, and pipes.
+- Planner output can be useful but invalid; the validation path must be strict.
+- `$EDITOR` behavior differs across macOS, Linux, Windows PowerShell, Git Bash, and WSL.
+- `--review` can become ambiguous unless consistently defined as "review before persistent writes".
+- Progressive adoption can create inconsistent UX if the matrix is not documented and enforced.
+
+## Resolved Decisions
+
+- No-color behavior uses both `--no-color` and environment detection (`NO_COLOR`, CI, and no-TTY).
+- `ai plan --with-planner` is accepted for UX consistency because planner behavior is already implicit.
+- `spec create --with-planner` is accepted because the command consumes an already reviewed and approved planner output; it does not execute a provider again.

package/specs/quiver-v29-planner-prepare-context-cli-ux/STATUS.md

@@ -0,0 +1,34 @@
+# Quiver v29 Status
+
+**Spec:** `quiver-v29-planner-prepare-context-cli-ux`
+**Status:** Completed
+**Created:** 2026-05-26
+
+## Current State
+
+- Acceptance criteria approved.
+- Technical plan approved.
+- Spec package prepared for execution.
+- `slice-00` completed as the documentary foundation.
+- `slice-01` completed with shared CLI UX primitives, Quiver theme tokens, editor helper, and focused tests.
+- `slice-02` completed with planner proposal schema, parser, docs-only allowlist, unsafe path rejection, and redacted invalid-output artifacts.
+- `slice-04` completed with centralized UX flag support, unsupported/incompatible flag guardrails, and CLI contract tests.
+- `slice-03` completed with explicit planner-assisted `ai prepare-context`, dry-run, prompt printing, provider execution, review, interactive approval, docs-only snapshots, and tests.
+- `slice-05` completed with progressive UX adoption for `ai plan`, `spec create`, and `ai pr`.
+- `slice-06` completed with documentation sync, CLI UX guide, generated template updates, full tests, smoke, package, tarball dry-run, and release readiness evidence.
+
+## Slice Status
+
+| Slice | Status | Notes |
+|---|---|---|
+| slice-00-cli-ux-spec-foundation | completed | Spec package validated and ready as foundation commit. |
+| slice-01-cli-ux-primitives-theme | completed | Added shared CLI theme/UX/editor helpers and focused unit tests; package smoke passed. |
+| slice-02-planner-context-proposal-contract | completed | Added zod proposal contract, parser, path safety, fixtures, and tests. |
+| slice-03-prepare-context-planner-review-flow | completed | Implemented planner-assisted prepare-context while preserving deterministic default behavior. |
+| slice-04-ux-flag-matrix-compatibility | completed | Added flag matrix, early validation, help entries, and tests for unsupported/incompatible UX flags. |
+| slice-05-progressive-command-adoption | completed | Added review/interactive paths for selected planner/spec/PR commands and tests. |
+| slice-06-docs-tests-smoke-readiness | completed | Final docs, templates, full tests, smoke, package, and tarball readiness passed. |
+
+## Next Step
+
+Open the PR for `quiver-v29-planner-prepare-context-cli-ux`, merge after review, and publish only after the package release process is explicitly requested.