create-quiver 0.15.1 → 0.15.2

package/.github/workflows/ci.yml

@@ -43,6 +43,9 @@ jobs:
         with:
           node-version: 22
 
+      - name: Install dependencies
+        run: npm ci
+
       - name: Run cross-platform smoke
         run: node scripts/ci/smoke-cross-platform.js
 

package/README.md

@@ -182,8 +182,10 @@ Usá la guía que corresponda al estado de tu proyecto:
 | `npx --yes create-quiver@latest ai agent doctor` | Diagnostica perfiles de agentes existentes. |
 | `npx --yes create-quiver@latest ai agent repair --dry-run` | Previsualiza reparaciones seguras para perfiles heredados o mal configurados. |
 | `npx --yes create-quiver@latest ai plan --phase acceptance` | Genera un borrador de criterios de aceptación. |
+| `npx --yes create-quiver@latest ai approve --phase acceptance` | En TTY lista drafts y recomienda la versión current/latest aprobable. |
 | `npx --yes create-quiver@latest ai plan --phase technical-plan` | Genera un borrador de plan técnico. |
 | `npx --yes create-quiver@latest ai review-plan` | Revisa el plan técnico antes de aprobarlo. |
+| `npx --yes create-quiver@latest ai approve --phase technical-plan` | En TTY muestra drafts con datos de review; en CI usá `--version <n>`. |
 | `npx --yes create-quiver@latest spec create` | Crea spec, slices, briefs, plan de ejecución y cuerpo del PR. |
 | `npx --yes create-quiver@latest spec create --interactive` | Guía la selección de metodología, input aprobado y revisión antes de escribir la spec. |
 | `npx --yes create-quiver@latest spec start specs/<spec>` | Crea o reutiliza el worktree de una spec. |

package/README_FOR_AI.md

@@ -35,9 +35,11 @@ Agent profiles live in `.quiver/agents/profiles.json`; they store role, provider
 `npx create-quiver ai models list` shows models known by Quiver, not models guaranteed available in the user's provider account. Use `npx create-quiver ai agent doctor` to diagnose profile issues and `npx create-quiver ai agent repair --dry-run` to preview safe legacy-profile alias normalization before writing anything.
 Provider/model selection must be honest: dry-runs can preview a selected model without provider auth, but live IA execution must pass the selected model through the provider adapter or fail with actionable guidance instead of silently ignoring it.
 Planner-oriented live IA commands must show visible TTY progress with the selected profile/model name, completed preparation checks, and a provider-running spinner. `--dry-run`, `--print-prompt`, CI, JSON, and non-TTY output must remain clean and automation-safe.
+This progress standard applies to `ai plan`, `ai revise`, `ai review-plan`, and `ai repair-plan`; do not add fake loaders to dry-runs or prompt-only output.
 Executor and PR live commands follow the same standard: show truthful TTY progress for slice execution, validation, commits, GitHub preflight, and PR creation while preserving scope gates, provider errors, `gh` errors, and clean machine output.
-Planner drafts are versioned under `.quiver/approvals/<phase>/drafts/`; review the technical-plan draft with `npx create-quiver ai review-plan --dry-run` before approving it, then approve a concrete version with `npx create-quiver ai approve --phase <phase> --version <n>` when reviewing iterations.
+Planner drafts are versioned under `.quiver/approvals/<phase>/drafts/`; review the technical-plan draft with `npx create-quiver ai review-plan --dry-run` before approving it. In TTY, `npx create-quiver ai approve --phase <phase>` can list saved drafts and recommend the current/latest eligible version; in CI/no-TTY, pass `--version <n>` explicitly.
 `ai review-plan` stores structured closure metadata under `.quiver/approvals/plan-review/meta.json`: `approval_recommendation` is `approve`, `approve-with-risk`, or `revise`; required fixes block technical-plan approval, while optional hardening does not.
+Use `npx create-quiver ai approvals`, `npx create-quiver flow`, `npx create-quiver ai status`, and `npx create-quiver ai resume` to read the same approval-candidate guidance before choosing the next command. `spec create --interactive` must show the reviewed approved technical-plan input, approved version, and review summary before writing.
 AI lifecycle runs are persisted under `.quiver/runs/<run-id>/`; use `npx create-quiver ai run create --input <requirements.md>` to start one explicitly, `npx create-quiver ai status` to inspect it, `npx create-quiver ai resume` to continue from the last valid phase without relying on chat memory, and `npx create-quiver ai export --format json|markdown` when another agent, PR, or dashboard needs the current specs/slices/runs state.
 Use `npx create-quiver ai active-slice reconcile --dry-run` when `docs/ai/ACTIVE_SLICE.md`, `ACTIVE_SLICES.md`, worktrees, or `ai inspect` appear out of sync. The command is dry-run-first and reports preserve, close, replace, or blocked decisions without writing files.
 When generating commands for another AI agent, prefer non-interactive package-pinned examples such as `npx --yes create-quiver@<version> ai prompt-slice --slice <slice.json> --dry-run`.
@@ -168,10 +170,10 @@ After initialization, the user should:
 10. Open and merge the documentation PR that establishes the workflow files
 11. Inspect reusable provider choices with `npx create-quiver ai models list`, diagnose existing profiles with `npx create-quiver ai agent doctor`, preview reusable provider choices with `npx create-quiver ai agent set <role> --provider <provider> --model <model-id> --dry-run`, then save planner/executor/doctor profiles without `--dry-run` after review
 12. Use `npx create-quiver ai plan --phase acceptance --input requirements.md --dry-run`; use `--print-prompt` when you need the exact prompt without provider auth and `--review --interactive` when the human should edit or confirm before saving
-13. If the human asks for changes, create a new draft with `npx create-quiver ai revise --phase acceptance --input feedback.md --dry-run`; after human approval, save the selected current draft with `npx create-quiver ai approve --phase acceptance --version <n>`
+13. If the human asks for changes, create a new draft with `npx create-quiver ai revise --phase acceptance --input feedback.md --dry-run`; after human approval, run `npx create-quiver ai approve --phase acceptance` in TTY or `--version <n>` in CI/no-TTY
 14. Use `npx create-quiver ai plan --phase technical-plan --dry-run`
 15. Review the technical plan with `npx create-quiver ai review-plan --dry-run`, inspect exact prompt with `--print-prompt` if needed, then run it without `--dry-run` when ready
-16. After human approval, save the reviewed plan version with `npx create-quiver ai approve --phase technical-plan --version <n>`
+16. After human approval, save the reviewed plan version with `npx create-quiver ai approve --phase technical-plan` in TTY or `--version <n>` in CI/no-TTY; if review recommends `revise`, run `ai revise --phase technical-plan --input feedback.md --dry-run` first
 17. Use `npx create-quiver spec create --dry-run` to preview the real spec, slices, handoffs, execution plan, and PR body; use `--review --interactive` when the human should inspect the package before writing
 18. Run `npx create-quiver spec start specs/<spec-slug> --dry-run` to inspect the planned worktree, then run without `--dry-run` to create or reuse it
 19. Run `npx create-quiver plan` or `npm run quiver:plan`

package/docs/CLI_UX_GUIDE.md

@@ -54,6 +54,7 @@ Reglas:
 | `ai execute-slice` | no | si | no | Interactive puede seleccionar un slice listo y un executor configurado. |
 | `ai execute-plan` | no | si | no | Interactive queda reservado para estrategia/seleccion; JSON sigue limpio. |
 | `ai agent set` | no | si | no | En TTY puede guiar proveedor/modelo; en CI/no-TTY requiere `--provider` y `--model`. |
+| `ai approve` | no | no | no | Si falta `--version` y hay TTY, abre selector de drafts; en CI/no-TTY exige `--version <n>`. |
 | `ai agent doctor` | no | no | no | Diagnostica perfiles sin escribir; `--json` usa el mismo modelo de hallazgos. |
 | `ai agent repair` | no | no | no | Por ahora solo `--dry-run`; muestra before/after sin escribir. |
 | `ai models list` | no | no | no | Lista el catalogo local conocido por Quiver; no valida acceso de cuenta. |
@@ -116,11 +117,22 @@ Reglas:
 `spec create --interactive` debe:
 
 - seleccionar la metodologia real soportada: `WDD + SDD`;
-- mostrar el input aprobado que se usara para generar la spec;
+- mostrar el input aprobado que se usara para generar la spec, la version aprobada y el resumen de review;
 - permitir elegir confirmacion directa o `--review`;
 - mostrar resumen antes de escribir;
 - bloquearse en no-TTY/CI/JSON con mensaje accionable en lugar de abrir prompts.
 
+## Aprobaciones planner
+
+`ai approve` conserva el modo script con `--version <n>`, pero en una terminal humana puede guiar la eleccion cuando falta `--version`:
+
+- `ai approve --phase acceptance` lista drafts versionados y recomienda el current/latest elegible.
+- `ai approve --phase technical-plan` agrega estado de `plan-review`, recomendacion, fixes requeridos, hardening opcional y riesgos.
+- CI/no-TTY nunca espera input; falla temprano con el comando explicito `--version <n>`.
+- Las versiones historicas pueden mostrarse como contexto, pero solo el draft current/latest es aprobable.
+- Los snippets o previews de candidatos deben estar truncados y redactados.
+- `ai approvals`, `flow`, `ai status`, `ai resume` y `spec create --interactive` deben usar el mismo modelo de candidatos para no contradecir el proximo paso.
+
 ## Loaders y prompts
 
 Usar loaders solo cuando aportan claridad:
@@ -143,6 +155,8 @@ Usar prompts interactivos cuando hay una decision humana real:
 
 No usar prompts para informacion que ya se pueda expresar con flags.
 
+Los comandos provider-backed `ai plan`, `ai revise`, `ai review-plan` y `ai repair-plan` deben seguir el mismo patron de progreso en TTY: checks de preparacion reales y spinner solo durante ejecucion del proveedor. `--dry-run`, `--print-prompt`, CI, no-TTY y JSON no deben mostrar loaders falsos.
+
 ## Salida de Doctor
 
 `doctor` debe mostrar una jerarquia estable para humanos:

package/docs/COMMANDS.md.template

@@ -154,7 +154,8 @@ This document is the canonical command reference for the orchestration roadmap.
 - `quiver:ai:agent -- repair --dry-run` previews safe normalizations such as `model: "GPT 5.5"` to `model: "gpt-5.5"` plus `displayName: "GPT 5.5"`; it does not write files.
 - `quiver:ai:inspect`, `quiver:ai:specs`, `quiver:ai:slices`, and `quiver:ai:trace` are read-only inspection surfaces for humans and agents.
 - `quiver:ai:export -- --format json` is the dashboard/agent-friendly state contract; `--format markdown` is the PR/docs-friendly version.
-- Planner drafts are versioned under `.quiver/approvals/<phase>/drafts/`; use `quiver:ai:review-plan -- --dry-run` before approving a technical-plan draft, then `quiver:ai:approve -- --phase technical-plan --version 1` to approve the reviewed version. Plan reviews store structured recommendations: `approve`, `approve-with-risk`, or `revise`.
+- Planner drafts are versioned under `.quiver/approvals/<phase>/drafts/`; in TTY, `quiver:ai:approve -- --phase <phase>` lists drafts and recommends the current/latest eligible version, while CI/no-TTY must pass `--version <n>`. Use `quiver:ai:review-plan -- --dry-run` before approving a technical-plan draft. Plan reviews store structured recommendations: `approve`, `approve-with-risk`, or `revise`.
+- `quiver:ai:approvals`, `quiver:flow`, `quiver:ai:status`, `quiver:ai:resume`, and `quiver:spec:create -- --interactive` use the same approval-candidate data so next-step guidance stays consistent.
 - `quiver:ai:prompt-slice -- --dry-run` prints a paste-ready manual executor prompt and does not call a provider.
 - For commands pasted into another AI agent, prefer a non-interactive pinned form such as `npx --yes create-quiver@<version> ai prompt-slice --slice specs/<spec>/slices/<slice>/slice.json --dry-run`.
 - `quiver:evidence -- run -- <command>` preserves the wrapped command exit code. Redaction is best effort; avoid commands that intentionally print secrets.

package/docs/WORKFLOW.md.template

@@ -35,10 +35,10 @@ Use maps, metadata, diffs, and summaries first. Open full files only when the sm
 1. Run `npx create-quiver flow` when the next safe command is unclear.
 2. Triage the request.
 3. Save reusable planner/executor provider choices with `ai agent set` when the team has preferred local AI CLIs.
-4. Use `ai plan --phase acceptance` to draft criteria, then save the approved version with `ai approve --phase acceptance`.
+4. Use `ai plan --phase acceptance` to draft criteria, then save the approved version with `ai approve --phase acceptance` in TTY or `--version <n>` in CI/no-TTY.
 5. Use `ai plan --phase technical-plan` to draft the plan.
 6. Use `ai review-plan` to review the technical-plan draft for production readiness without changing product code. Treat `approve` and `approve-with-risk` as approvable states; treat `revise` or required fixes as blockers.
-7. Save the reviewed plan version with `ai approve --phase technical-plan --version <n>` only after the review recommendation is approvable.
+7. Save the reviewed plan version with `ai approve --phase technical-plan` in TTY or `--version <n>` in CI/no-TTY only after the review recommendation is approvable.
 8. Use `spec create` to generate the spec, mandatory `slice-00`, implementation slices, handoffs, execution plan, and `pr.md`.
 9. Open and merge the documentation PR or commit that establishes `slice-00` before running implementation slices.
 10. Read the AI context pack, support matrix, and troubleshooting guide before the first slice if the environment is new or uncertain.

package/docs/reference/commands.md

@@ -58,11 +58,16 @@ Más detalle: [Instalación y uso con npx](../getting-started/installation.md).
 | `npx --yes create-quiver@latest ai status` | Muestra el estado de la ejecución actual. |
 | `npx --yes create-quiver@latest ai plan --phase acceptance --input <file>` | Genera criterios de aceptación. |
 | `npx --yes create-quiver@latest ai plan --phase acceptance --review --interactive --input <file>` | Permite revisar y confirmar el borrador del planner antes de guardarlo. |
-| `npx --yes create-quiver@latest ai revise --phase acceptance --input <file>` | Crea una nueva versión de criterios. |
-| `npx --yes create-quiver@latest ai approve --phase acceptance --version <n>` | Aprueba criterios. |
+| `npx --yes create-quiver@latest ai revise --phase acceptance --input <feedback.md>` | Crea una nueva versión de criterios desde feedback; `--input` sin valor o archivos inexistentes fallan antes del proveedor. |
+| `npx --yes create-quiver@latest ai approve --phase acceptance` | En TTY lista drafts y recomienda el current/latest; en CI/no-TTY exige `--version <n>`. |
+| `npx --yes create-quiver@latest ai approve --phase acceptance --version <n>` | Aprueba criterios en modo explícito/script-safe. |
 | `npx --yes create-quiver@latest ai plan --phase technical-plan` | Genera plan técnico. |
-| `npx --yes create-quiver@latest ai review-plan` | Revisa el plan técnico. |
-| `npx --yes create-quiver@latest ai approve --phase technical-plan --version <n>` | Aprueba el plan técnico revisado. |
+| `npx --yes create-quiver@latest ai revise --phase technical-plan --input <feedback.md>` | Crea una nueva versión del plan técnico desde feedback. |
+| `npx --yes create-quiver@latest ai review-plan` | Revisa el plan técnico y guarda recomendación `approve`, `approve-with-risk` o `revise`. |
+| `npx --yes create-quiver@latest ai repair-plan` | Repara un plan técnico aprobado legacy que no cumple el contrato `spec.slices[]`, creando un nuevo draft. |
+| `npx --yes create-quiver@latest ai approve --phase technical-plan` | En TTY lista drafts con datos de review; `revise` bloquea aprobación y `approve-with-risk` muestra riesgos. |
+| `npx --yes create-quiver@latest ai approve --phase technical-plan --version <n>` | Aprueba el plan técnico revisado en modo explícito/script-safe. |
+| `npx --yes create-quiver@latest ai approvals` | Muestra approvals run-scoped/globales, candidatos actuales, versión recomendada y próximo comando. |
 
 ## Specs y slices
 
@@ -118,6 +123,7 @@ Más detalle: [Instalación y uso con npx](../getting-started/installation.md).
 | `ai plan` | sí | sí | sí |
 | `spec create` | sí | sí | sí |
 | `ai pr` | no | sí | sí |
+| `ai approve` | no | no | no |
 | `flow`, `next`, `graph` | no | no | no |
 | `ai inspect`, `ai export`, `ai specs list`, `ai slices list`, `ai trace report` | no | no | no |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-quiver",
-  "version": "0.15.1",
+  "version": "0.15.2",
   "private": false,
   "description": "Quiver CLI for scaffolding projects from the packaged template",
   "license": "MIT",

package/specs/quiver-v33-approval-ux-and-planner-progress/EVIDENCE_REPORT.md

@@ -0,0 +1,93 @@
+# Evidence Report - Quiver v33 Approval UX and Planner Progress
+
+## Summary
+
+This report records implementation and validation evidence for all v33 slices.
+
+## slice-00 - Approval UX foundation
+
+### Completed
+
+- Created v33 spec package with `SPEC.md`, `STATUS.md`, `EXECUTION_PLAN.md`, `EVIDENCE_REPORT.md`, and `pr.md`.
+- Created 8 slice folders with `slice.json`, `EXECUTION_BRIEF.md`, and `CLOSURE_BRIEF.md`.
+- Captured the approved acceptance criteria, production review fixes, revised technical plan, and execution order.
+
+### Validation
+
+- `find specs/quiver-v33-approval-ux-and-planner-progress -name 'slice.json' -print -exec node -e "JSON.parse(require('fs').readFileSync(process.argv[1], 'utf8')); console.log('ok', process.argv[1])" {} \;` passed for 8 slice files.
+- `node bin/create-quiver.js spec validate specs/quiver-v33-approval-ux-and-planner-progress` passed and reported 8 slices.
+- `git diff --check` passed.
+
+### Risks Observed During Planning
+
+- `docs/INDEX.md` is still missing in this repository; onboarding used `docs/INDEX.md.template` plus repo-specific Quiver docs as the documented fallback.
+- The repo branch was already ahead of `origin/main` before this spec package was created.
+
+## slice-01 to slice-03 - Approval candidates and approval selection
+
+### Completed
+
+- Slice ids covered: `slice-01-approval-candidates-model`, `slice-02-approve-interactive-selection`, `slice-03-technical-plan-review-decision-data`.
+- Added redacted/truncated approval-candidate data for planner phases.
+- Added technical-plan candidate enrichment with plan-review recommendation, blocking, fixes, hardening, risks, and next command.
+- Added TTY selector flow for `ai approve --phase acceptance|technical-plan` when `--version` is omitted.
+- Preserved explicit `--version <n>` behavior for no-TTY/CI/scripted usage.
+
+### Validation
+
+- `node --test tests/lib/approvals.test.js tests/commands/ai-review-plan.test.js` passed during slice execution.
+- `node --test tests/commands/ai-plan.test.js tests/commands/ai-review-plan.test.js tests/lib/approvals.test.js` passed after interactive approval integration.
+
+## slice-04 and slice-05 - Revise guardrails and provider progress
+
+### Completed
+
+- Slice ids covered: `slice-04-revise-input-guardrails`, `slice-05-provider-progress-alignment`.
+- Hardened parser/command errors for `ai revise --phase acceptance --input` and `ai revise --phase technical-plan --input`.
+- Added coverage for nonexistent feedback files and accidental trailing positional arguments.
+- Added TTY progress checks and spinner coverage for `ai plan`, `ai review-plan`, and `ai repair-plan`; `ai revise` inherits the shared plan path.
+- Confirmed dry-run and print-prompt remain loader-free.
+
+### Validation
+
+- `node --test tests/commands/ai-plan.test.js tests/commands/ai-review-plan.test.js tests/lib/approvals.test.js` passed with 51 tests.
+- Focused progress regressions for `ai prepare-context`, executor, PR, selectors, and UX helpers passed.
+
+## slice-06 - Workflow surface integration
+
+### Completed
+
+- Slice id covered: `slice-06-workflow-surface-integration`.
+- Added `src/create-quiver/lib/ai/approval-candidates.js` as the shared formatter/command helper for decision surfaces.
+- Updated `ai approvals`, `flow`, `ai status`, `ai resume`, and `spec create --interactive` to consume shared candidate data.
+- Added drift-prevention tests for current recommended versions and plan-review `revise` blockers.
+
+### Validation
+
+- `node --test tests/commands/flow.test.js tests/commands/ai-run-state.test.js tests/commands/spec-create.test.js tests/commands/ai-review-plan.test.js tests/commands/ai-plan.test.js tests/lib/approvals.test.js` passed with 80 tests.
+
+## slice-07 - Docs, tests, and release readiness
+
+### Completed
+
+- Slice id covered: `slice-07-docs-tests-release-readiness`.
+- Updated `README.md`, `README_FOR_AI.md`, `docs/CLI_UX_GUIDE.md`, `docs/reference/commands.md`, `docs/COMMANDS.md.template`, and `docs/WORKFLOW.md.template`.
+- Updated all slice `CLOSURE_BRIEF.md` files, slice status metadata, spec `STATUS.md`, and `pr.md`.
+
+### Validation
+
+- `git diff --check` passed.
+- `node bin/create-quiver.js spec validate specs/quiver-v33-approval-ux-and-planner-progress` passed.
+- `node --test tests/lib/git.test.js tests/lib/paths.test.js` passed: 12 tests.
+- `node --test tests/lib/paths.test.js` passed: 10 tests.
+- `node --test tests/**/*.test.js` passed: 496 tests, 496 pass.
+- `npm run smoke:create-quiver` passed: `create-quiver smoke test passed`.
+- `npm run smoke:doctor-fixtures` passed: 13 states.
+- `npm run smoke:guided-workflow` passed.
+- `npm run package:quiver` passed: `Package smoke passed: create-quiver-0.15.1.tgz`.
+- `node scripts/ci/smoke-cross-platform.js` passed after adding `npm ci` to the GitHub Actions cross-platform smoke job.
+
+### Remaining Risks
+
+- No critical risks remain.
+- This evidence does not claim npm publication.

package/specs/quiver-v33-approval-ux-and-planner-progress/EXECUTION_PLAN.md

@@ -0,0 +1,83 @@
+# Execution Plan - Quiver v33 Approval UX and Planner Progress
+
+## Execution Order
+
+```mermaid
+flowchart TD
+    S00[slice-00: Approval UX foundation]
+    S01[slice-01: Approval candidates model]
+    S02[slice-02: Interactive approval selection]
+    S03[slice-03: Technical-plan review decision data]
+    S04[slice-04: Revise input guardrails]
+    S05[slice-05: Provider progress alignment]
+    S06[slice-06: Workflow surface integration]
+    S07[slice-07: Docs, tests, and release readiness]
+
+    S00 --> S01
+    S01 --> S02
+    S01 --> S04
+    S01 --> S05
+    S02 --> S03
+    S01 --> S06
+    S02 --> S06
+    S03 --> S06
+    S02 --> S07
+    S03 --> S07
+    S04 --> S07
+    S05 --> S07
+    S06 --> S07
+```
+
+## Waves
+
+### Wave 0 - Completed Foundation
+
+1. `slice-00-approval-ux-foundation`
+
+The foundation slice creates the approved spec package and does not change product code.
+
+### Wave 1 - Core Model
+
+1. `slice-01-approval-candidates-model`
+
+Build the shared approval-candidate model before changing command UX.
+
+### Wave 2 - Command UX and Guardrails
+
+1. `slice-02-approve-interactive-selection`
+2. `slice-04-revise-input-guardrails`
+3. `slice-05-provider-progress-alignment`
+
+These slices can proceed after slice-01. Coordinate conflicts in `src/create-quiver/commands/ai.js`.
+
+### Wave 3 - Technical Review and Workflow Surfaces
+
+1. `slice-03-technical-plan-review-decision-data`
+2. `slice-06-workflow-surface-integration`
+
+Run slice-03 before or alongside slice-06 only if the plan-review decision contract is stable enough to consume.
+
+### Wave 4 - Close
+
+1. `slice-07-docs-tests-release-readiness`
+
+This slice is never parallel-safe because it closes docs, tests, smokes, and release evidence.
+
+## Parallel Safety Notes
+
+- Do not run any implementation slice before slice-01.
+- Do not add `ai approve` prompts before the shared candidate model exists.
+- Do not weaken `plan-review` blocking behavior while adding selectors.
+- `slice-02`, `slice-04`, and `slice-05` may all touch `src/create-quiver/commands/ai.js`; if conflicts are likely, land them sequentially.
+- Keep all JSON/no-TTY behavior clean at every slice, not only at the final slice.
+
+## Recommended Commit Order
+
+1. `docs: add v33 approval ux spec`
+2. `feat: add approval candidate model`
+3. `feat: add interactive approval selection`
+4. `feat: expose technical plan review decision data`
+5. `fix: harden ai revise input handling`
+6. `feat: align planner progress flows`
+7. `feat: share approval guidance across workflow surfaces`
+8. `docs: close v33 approval ux readiness`

package/specs/quiver-v33-approval-ux-and-planner-progress/SPEC.md

@@ -0,0 +1,158 @@
+# Quiver v33 - Approval UX and Planner Progress
+
+**Date:** 2026-05-28
+**Status:** Completed
+**Source:** User-approved acceptance criteria and production review for approval selectors, planner progress, and consistent decision guidance.
+
+Slice numbering resets here. This spec intentionally starts at `slice-00`.
+
+## Problem
+
+Quiver already has visible progress and guided selectors in several AI workflow commands, but the experience is incomplete around planner approvals and technical-plan iteration.
+
+Three gaps create partial-fix risk:
+
+- planner/reviewer commands can still feel inconsistent with `ai prepare-context --with-planner`;
+- `ai approve --phase acceptance|technical-plan` requires users to know the exact draft version instead of guiding them with the same kind of selector used by `ai agent set`;
+- approval recommendations are spread across `ai approve`, `ai approvals`, `flow`, `ai status`, `ai resume`, `spec create --interactive`, and `plan-review` logic, which can produce conflicting or incomplete next-step guidance.
+
+## Objective
+
+Make planner approval and revision flows production-safe and consistent:
+
+- show real human progress for provider-backed planner/reviewer commands;
+- offer TTY selectors for approval versions when `--version` is omitted;
+- keep CI/no-TTY/JSON/scripted usage clean and explicit;
+- centralize approval candidates and recommendations so every workflow surface presents the same decision state;
+- harden incomplete `ai revise --input` usage for both acceptance and technical-plan phases;
+- keep `plan-review` blocking semantics strict and visible.
+
+## Scope
+
+### Included
+
+- Shared approval-candidate model for acceptance, technical-plan, and plan-review decision context.
+- `ai approve --phase acceptance` selector when `--version` is omitted in TTY.
+- `ai approve --phase technical-plan` selector that includes plan-review recommendation, blocking status, required fixes, optional hardening, risks, and next command.
+- No-TTY/CI guardrails for `ai approve` without `--version`.
+- Missing/incomplete `--input` handling for `ai revise --phase acceptance` and `ai revise --phase technical-plan`.
+- Progress/loaders alignment for provider-backed planner commands: `ai plan`, `ai revise`, `ai review-plan`, and `ai repair-plan`.
+- Audit and regression coverage for existing long-running flows: `ai onboard`, `ai prepare-context --with-planner`, `ai execute-slice`, `ai execute-plan --execute`, and `ai pr --create`.
+- Integration of the shared approval-candidate model into `ai approvals`, `flow`, `ai status`, `ai resume`, and `spec create --interactive`.
+- Documentation and tests for human, TTY, no-TTY, CI, JSON, dry-run, print-prompt, no-color, and review-state cases.
+
+### Excluded
+
+- Product feature implementation beyond CLI workflow UX and approval state.
+- Replacing the CLI parser.
+- Adding a TUI framework.
+- Making prompts mandatory.
+- Relaxing `plan-review` approval gates.
+- Storing provider credentials or secrets.
+- Changing WDD + SDD semantics.
+
+## Approved Acceptance Criteria
+
+### Provider Progress
+
+1. `ai plan --phase acceptance --input <file>` shows human progress and a spinner when executing the planner in a human TTY, following the pattern of `ai prepare-context --with-planner`.
+2. `ai plan --phase technical-plan` shows the same progress pattern when executing the planner.
+3. `ai revise --phase acceptance --input <file>` and `ai revise --phase technical-plan --input <file>` inherit the same progress behavior through the shared planner path.
+4. `ai review-plan` shows progress for reading the technical plan, preparing context, preparing the prompt, executing the reviewer, and writing review metadata.
+5. `ai repair-plan` is in scope and shows the same provider-progress standard.
+6. Existing long-running flows are audited for consistency: `ai onboard`, `ai prepare-context --with-planner`, `ai execute-slice`, `ai execute-plan --execute`, and `ai pr --create`.
+7. `--dry-run` and `--print-prompt` never execute providers or show fake loaders.
+8. `--json`, CI/no-TTY, `NO_COLOR`, `TERM=dumb`, and `--no-color` remain clean and script-safe.
+
+### Approval Selection
+
+9. `ai approve --phase acceptance` without `--version` opens a TTY selector when prompts are available.
+10. `ai approve --phase technical-plan` without `--version` opens a TTY selector when prompts are available and includes plan-review decision data.
+11. In no-TTY/CI, `ai approve --phase <phase>` without `--version` fails early with an actionable command using `--version <n>`.
+12. Explicit `--version <n>` preserves existing script-safe behavior.
+13. Only the latest draft version is approvable. Older versions may be displayed as history but must not be silently approved.
+14. The selector recommends the current/latest eligible draft and explains why.
+15. Technical-plan approval distinguishes `plan-review` states: `missing`, `stale`, `unapproved`, `reviewed + approve`, `reviewed + approve-with-risk`, and `reviewed + revise`.
+16. `reviewed + revise` blocks approval and points to `ai revise --phase technical-plan --input <feedback.md> --dry-run`.
+17. `reviewed + approve-with-risk` allows explicit approval while showing risks and optional hardening.
+18. Candidate summaries must be concise, truncated, and redacted through existing utilities before printing draft or review snippets.
+
+### Revise Input Guardrails
+
+19. `ai revise --phase acceptance --input` and `ai revise --phase technical-plan --input` handle a missing input value explicitly.
+20. Missing input in no-TTY/CI fails with an actionable example.
+21. Missing input in TTY may show a selector or focused guidance if useful artifacts are available.
+22. Nonexistent input files fail before provider execution.
+23. Accidental extra arguments, such as a trailing `s`, are detected or reported clearly instead of being ignored.
+
+### Shared Decision Surfaces
+
+24. A shared approval-candidate model feeds `ai approve`, `ai approvals`, `flow`, `ai status`, `ai resume`, and `spec create --interactive`.
+25. These surfaces do not duplicate or contradict next-step recommendations.
+26. `spec create --interactive` shows the reviewed and approved technical-plan source using the same decision data.
+27. Approval candidates include phase, version, path, created_at, source_file, current/latest flag, review recommendation, blocking state, recommended action, and next command.
+
+### Documentation and Tests
+
+28. `docs/CLI_UX_GUIDE.md`, `docs/reference/commands.md`, and `README_FOR_AI.md` are updated when the visible contract changes.
+29. Tests cover TTY selector paths, no-TTY/CI failures, explicit `--version`, latest-draft recommendation, stale/blocked plan-review states, `approve-with-risk`, missing `--input`, accidental extra args, dry-run, print-prompt, no-color, and JSON cleanliness.
+30. Implementation does not log secrets or credentials.
+31. Every slice in this spec has `slice.json`, `EXECUTION_BRIEF.md`, and `CLOSURE_BRIEF.md`.
+
+## Approved Technical Plan
+
+1. Inventory the real command surface and existing tests before implementation.
+2. Create a shared approval-candidates module that reads existing approval and plan-review metadata without changing persisted formats unless required.
+3. Integrate approval candidates into `ai approvals`, `flow`, `ai status`, `ai resume`, and `spec create --interactive`.
+4. Add TTY approval selection in `ai approve` for acceptance and technical-plan when `--version` is omitted.
+5. Preserve no-TTY/CI/script behavior by requiring explicit `--version <n>` outside prompts.
+6. Harden missing/incomplete `--input` handling in `ai revise` for both planner phases.
+7. Align provider progress in `ai plan`, `ai revise`, `ai review-plan`, and `ai repair-plan`.
+8. Audit existing progress flows and add regression tests instead of rewriting working behavior unnecessarily.
+9. Update public docs and AI guidance only after the command contract is implemented.
+10. Add focused tests and final full-suite/smoke validation.
+
+## Slice Roadmap
+
+| Slice | Title | Status | Dependencies |
+|---|---|---|---|
+| slice-00 | Approval UX foundation | completed | none |
+| slice-01 | Approval candidates model | completed | slice-00 |
+| slice-02 | Interactive approval selection | completed | slice-01 |
+| slice-03 | Technical-plan review decision data | completed | slice-01, slice-02 |
+| slice-04 | Revise input guardrails | completed | slice-01 |
+| slice-05 | Provider progress alignment | completed | slice-01 |
+| slice-06 | Workflow surface integration | completed | slice-01, slice-02, slice-03 |
+| slice-07 | Docs, tests, and release readiness | completed | slice-02, slice-03, slice-04, slice-05, slice-06 |
+
+## Validation Strategy
+
+- `node --test tests/lib/approvals.test.js tests/commands/ai-run-state.test.js tests/commands/ai-review-plan.test.js`
+- `node --test tests/commands/ai-plan.test.js tests/commands/ai-prepare-context-planner.test.js`
+- `node --test tests/commands/ai-agent.test.js tests/lib/cli-selectors.test.js tests/lib/cli-ux.test.js`
+- `node --test tests/commands/flow.test.js tests/commands/spec-create.test.js`
+- `node --test tests/**/*.test.js`
+- `npm run smoke:create-quiver`
+- `npm run smoke:doctor-fixtures`
+- `npm run smoke:guided-workflow`
+- `npm run package:quiver`
+- `git diff --check`
+- `node bin/create-quiver.js spec validate specs/quiver-v33-approval-ux-and-planner-progress`
+
+## Risks
+
+- Approval UX touches critical workflow gates; selector convenience must not weaken plan-review blocking behavior.
+- Prompt behavior can break automation if it is not strictly TTY-gated.
+- Multiple surfaces can drift if candidate data is not shared.
+- Progress output can contaminate JSON or no-TTY output if not centralized.
+- Draft snippets can leak sensitive content unless they are truncated and redacted.
+
+## Resolved Decisions
+
+- `ai repair-plan` is in scope.
+- `ai revise --phase acceptance --input` is in scope, not only technical-plan.
+- TTY selection for `ai approve` may happen when `--version` is omitted, but CI/no-TTY must require explicit flags.
+- Only the latest draft is approvable.
+- `plan-review` recommendation `revise` remains blocking.
+- `approve-with-risk` remains approvable with visible risk context.
+- Do not add `--review` to commands that do not need editor review.

package/specs/quiver-v33-approval-ux-and-planner-progress/STATUS.md

@@ -0,0 +1,31 @@
+# Status - Quiver v33 Approval UX and Planner Progress
+
+**Overall status:** Completed
+**Created:** 2026-05-28
+**Completed:** 2026-05-28
+**Current slice:** none
+
+## Summary
+
+This spec improves planner approval UX, approval decision guidance, incomplete revise input handling, and provider progress consistency across the AI workflow. All planned slices are complete and validated.
+
+## Slice Status
+
+| Slice | Status | Notes |
+|---|---|---|
+| slice-00-approval-ux-foundation | Completed | Spec package, execution plan, PR body, evidence skeleton, and slice briefs created. |
+| slice-01-approval-candidates-model | Completed | Added shared approval-candidate data for acceptance and technical-plan review context. |
+| slice-02-approve-interactive-selection | Completed | Added TTY draft selection for `ai approve` when `--version` is omitted and no-TTY guardrails. |
+| slice-03-technical-plan-review-decision-data | Completed | Technical-plan candidates expose review recommendation, blocking, fixes, hardening, risks, and next command. |
+| slice-04-revise-input-guardrails | Completed | Missing `--input`, nonexistent files, and accidental extra args fail before provider execution. |
+| slice-05-provider-progress-alignment | Completed | `ai plan`, `ai revise`, `ai review-plan`, and `ai repair-plan` use real TTY progress and spinner behavior. |
+| slice-06-workflow-surface-integration | Completed | Shared candidates feed `ai approvals`, `flow`, `ai status`, `ai resume`, and `spec create --interactive`. |
+| slice-07-docs-tests-release-readiness | Completed | Docs, templates, tests, smokes, package readiness, evidence, and PR body are updated. |
+
+## Current Blockers
+
+- None.
+
+## Next Step
+
+Open review/PR with the recorded validation evidence. Do not claim npm publication from this spec.

package/specs/quiver-v33-approval-ux-and-planner-progress/pr.md

@@ -0,0 +1,109 @@
+## Title
+
+Quiver v33: Approval UX and planner progress
+
+## Summary
+
+- Adds shared approval-candidate guidance for planner phases.
+- Adds guided approval selection for `ai approve` in TTY when `--version` is omitted.
+- Preserves explicit `--version` behavior for CI/no-TTY/scripted use.
+- Hardens incomplete `ai revise --input` usage.
+- Aligns progress/loaders for provider-backed planner/reviewer commands.
+- Synchronizes approval guidance across `ai approvals`, `flow`, `ai status`, `ai resume`, and `spec create --interactive`.
+
+## Scope
+
+- Approval candidate model and formatting.
+- Interactive approval selector.
+- Technical-plan plan-review state visibility and blocking.
+- Revise input validation.
+- Planner/reviewer/repair-plan progress UX.
+- Workflow-surface integration.
+- Docs, tests, smokes, and release readiness.
+
+## Files
+
+- `.github/workflows/ci.yml`
+- `README.md`
+- `README_FOR_AI.md`
+- `docs/CLI_UX_GUIDE.md`
+- `docs/reference/commands.md`
+- `docs/COMMANDS.md.template`
+- `docs/WORKFLOW.md.template`
+- `src/create-quiver/commands/ai.js`
+- `src/create-quiver/commands/flow.js`
+- `src/create-quiver/commands/spec.js`
+- `src/create-quiver/index.js`
+- `src/create-quiver/lib/git.js`
+- `src/create-quiver/lib/approvals.js`
+- `src/create-quiver/lib/ai/approval-candidates.js`
+- `src/create-quiver/lib/ai/plan-review.js`
+- `src/create-quiver/lib/paths.js`
+- `src/create-quiver/lib/ai/run-state.js`
+- `tests/lib/git.test.js`
+- `tests/lib/paths.test.js`
+- `tests/**`
+- `specs/quiver-v33-approval-ux-and-planner-progress/**`
+
+## How to Test (DETAILED - REQUIRED)
+
+### Required Environment
+
+- Node.js and npm.
+- No provider credentials are required for dry-run/print-prompt tests.
+- TTY-like behavior should be tested through injected prompt helpers.
+
+### Worktree Access
+
+- One dedicated branch/worktree for `quiver-v33-approval-ux-and-planner-progress`.
+- One commit per slice.
+
+### Use Cases
+
+- Run `ai approve --phase acceptance` in a prompt-capable test harness without `--version`.
+- Run `ai approve --phase technical-plan` for plan-review states: missing, stale, unapproved, approve, approve-with-risk, revise.
+- Run `ai approve --phase acceptance` in no-TTY/CI without `--version` and verify it fails actionably.
+- Run `ai approve --phase acceptance --version 1` and verify existing scripted behavior remains.
+- Run `ai revise --phase acceptance --input` and `ai revise --phase technical-plan --input` with missing, invalid, and accidental extra input.
+- Run provider-backed planner commands in human mode and verify progress does not leak into JSON/dry-run/print-prompt.
+
+### Technical Verification
+
+- `node --test tests/lib/approvals.test.js tests/commands/ai-run-state.test.js tests/commands/ai-review-plan.test.js`
+- `node --test tests/commands/ai-plan.test.js tests/commands/ai-prepare-context-planner.test.js`
+- `node --test tests/commands/flow.test.js tests/commands/spec-create.test.js`
+- `node --test tests/commands/ai-agent.test.js tests/lib/cli-selectors.test.js tests/lib/cli-ux.test.js`
+- `node --test tests/lib/git.test.js tests/lib/paths.test.js`
+- `node --test tests/**/*.test.js`
+- `npm run smoke:create-quiver`
+- `npm run smoke:doctor-fixtures`
+- `npm run smoke:guided-workflow`
+- `npm run package:quiver`
+- `node scripts/ci/smoke-cross-platform.js`
+- `git diff --check`
+- `node bin/create-quiver.js spec validate specs/quiver-v33-approval-ux-and-planner-progress`
+
+## Evidence
+
+- `git diff --check` passed.
+- `node bin/create-quiver.js spec validate specs/quiver-v33-approval-ux-and-planner-progress` passed.
+- `node --test tests/lib/git.test.js tests/lib/paths.test.js` passed.
+- `node --test tests/**/*.test.js` passed: 496/496.
+- `npm run smoke:create-quiver` passed.
+- `npm run smoke:doctor-fixtures` passed.
+- `npm run smoke:guided-workflow` passed.
+- `npm run package:quiver` passed.
+- `node scripts/ci/smoke-cross-platform.js` passed after adding `npm ci` to the GitHub Actions smoke matrix.
+- Detailed slice evidence is in `specs/quiver-v33-approval-ux-and-planner-progress/EVIDENCE_REPORT.md`.
+
+## Rollback
+
+Revert slice commits in reverse order. Preserve explicit `--version` approval behavior and existing non-interactive planner workflows during rollback.
+
+## Risks / Notes
+
+- Approval gates are critical workflow safety controls; selector UX must not approve stale or blocked drafts.
+- Candidate summaries must remain redacted and truncated.
+- Provider progress must not contaminate machine-readable output.
+- GitHub Actions cross-platform smoke requires dependencies installed before invoking the source CLI.
+- This PR does not publish npm.