create-quiver 0.15.0 → 0.15.2

package/specs/quiver-v32-npx-installation-guidance/pr.md

@@ -0,0 +1,72 @@
+## Title
+
+Quiver v32: clarify npx vs local installation
+
+## Summary
+
+- Explains why `npx --yes create-quiver@latest` does not install Quiver into project `node_modules`.
+- Adds a dedicated installation guide for `npx` vs local `devDependency` usage.
+- Adds troubleshooting guidance for users who expect Quiver in `node_modules`.
+- Aligns generated docs templates and `README_FOR_AI.md`.
+
+## Scope
+
+- Public README guidance.
+- Installation guide under `docs/getting-started/`.
+- Troubleshooting entry.
+- Command reference and generated docs template notes.
+- Documentation-only WDD/SDD traceability.
+
+## Files
+
+- `README.md`
+- `README_FOR_AI.md`
+- `docs/getting-started/installation.md`
+- `docs/reference/commands.md`
+- `docs/TROUBLESHOOTING.md`
+- `docs/TROUBLESHOOTING.md.template`
+- `docs/COMMANDS.md.template`
+- `specs/quiver-v32-npx-installation-guidance/**`
+
+## How to Test (DETAILED - REQUIRED)
+
+### Required Environment
+
+- Node.js and npm.
+- Local Quiver source checkout.
+
+### Worktree Access
+
+- Use a dedicated docs branch for this PR.
+- No product-code changes are expected.
+
+### Run the Project
+
+This is a documentation-only change. No app runtime is needed.
+
+### Use Cases
+
+- Read the README and confirm it explains why `npx` does not populate `node_modules`.
+- Read `docs/getting-started/installation.md` and confirm it explains when to use `npx` and when to install `create-quiver` as a `devDependency`.
+- Read `docs/TROUBLESHOOTING.md` and confirm it covers the `node_modules` confusion.
+- Inspect templates to confirm generated projects inherit the same explanation.
+
+### Technical Verification
+
+- `git diff --check`
+- `node bin/create-quiver.js spec validate specs/quiver-v32-npx-installation-guidance`
+
+## Evidence
+
+- Documentation updated in public, reference, troubleshooting, template, and AI source-of-truth surfaces.
+- `git diff --check` passed.
+- `node bin/create-quiver.js spec validate specs/quiver-v32-npx-installation-guidance` passed.
+
+## Rollback
+
+Revert this documentation slice commit. No runtime behavior or package installation behavior changed.
+
+## Risks / Notes
+
+- This PR does not change how `init` or `migrate` may install local dev dependencies.
+- The guidance intentionally keeps `npx --yes create-quiver@latest` as the recommended bootstrap path.

package/specs/quiver-v32-npx-installation-guidance/slices/slice-00-installation-docs/CLOSURE_BRIEF.md

@@ -0,0 +1,31 @@
+# Closure Brief - slice-00-installation-docs
+
+## Resumen de lo realizado
+
+Se agregó documentación para explicar que `npx --yes create-quiver@latest` ejecuta Quiver desde la caché de npm y no instala el paquete dentro de `node_modules`. También se documentó cuándo conviene instalar `create-quiver` como `devDependency`.
+
+## Validación contra criterios de aceptación
+
+- README incluye explicación breve y link a la guía.
+- `docs/getting-started/installation.md` explica `npx`, caché de npm, `node_modules` y `devDependency`.
+- `docs/TROUBLESHOOTING.md` cubre la confusión de `node_modules`.
+- Templates generados fueron alineados.
+- `README_FOR_AI.md` fue actualizado como fuente de verdad.
+
+## Cambios relevantes
+
+- Public documentation now covers `npx` vs local install.
+- Generated project templates inherit the key guidance.
+- Spec package and PR body were created for traceability.
+
+## Pendientes
+
+- Abrir el PR.
+
+## Riesgos remanentes
+
+- Ninguno crítico. Esta spec no cambia comportamiento de producto.
+
+## Recomendaciones futuras
+
+- Consider adding `npx` cache behavior to `create-quiver --help` only if more users hit the same confusion.

package/specs/quiver-v32-npx-installation-guidance/slices/slice-00-installation-docs/EXECUTION_BRIEF.md

@@ -0,0 +1,56 @@
+# Execution Brief - slice-00-installation-docs
+
+## Context
+
+Users can run Quiver with `npx --yes create-quiver@latest` and expect the package to appear in project `node_modules`. The expected npm behavior is that `npx` runs the CLI from npm's execution cache unless the package is explicitly installed locally.
+
+## Objective
+
+Document the `npx` vs local installation behavior clearly across public docs, troubleshooting, templates, and AI source-of-truth guidance.
+
+## Scope
+
+- Root README summary.
+- Dedicated installation guide.
+- Troubleshooting entry.
+- Command reference note.
+- Generated docs template note.
+- `README_FOR_AI.md` synchronization.
+
+## Criterios de aceptación
+
+- README includes a concise explanation of why Quiver may not appear in `node_modules`.
+- Installation guide explains `npx`, npm cache execution, and `devDependency` installation.
+- Troubleshooting covers the user confusion as a recoverable expected behavior.
+- Templates include the same guidance for generated projects.
+- No product code is modified.
+
+## Plan técnico resumido
+
+1. Add the public README section and link.
+2. Add `docs/getting-started/installation.md`.
+3. Add `docs/TROUBLESHOOTING.md`.
+4. Update generated troubleshooting and command templates.
+5. Update `README_FOR_AI.md`.
+6. Validate docs and spec package.
+
+## Restricciones
+
+- Do not recommend global installation.
+- Do not change runtime behavior.
+- Do not change npm package metadata.
+
+## Riesgos
+
+- Duplicating too much setup guidance in the root README.
+- Confusing `npx create-quiver` local resolution with `npx --yes create-quiver@latest` latest resolution.
+
+## Checklist de finalización
+
+- [x] README updated.
+- [x] Installation guide added.
+- [x] Troubleshooting added.
+- [x] Templates updated.
+- [x] `README_FOR_AI.md` updated.
+- [x] Validation commands run.
+- [ ] PR opened.

package/specs/quiver-v32-npx-installation-guidance/slices/slice-00-installation-docs/slice.json

@@ -0,0 +1,75 @@
+{
+  "slice_id": "slice-00-installation-docs",
+  "ticket": "QUIVER-32-00",
+  "type": "documentation",
+  "title": "npx and node_modules installation guidance",
+  "objective": "Document why Quiver does not appear in project node_modules when executed with npx, and when local devDependency installation is appropriate.",
+  "description": "Adds public README guidance, a dedicated installation guide, troubleshooting coverage, generated docs template notes, and AI source-of-truth synchronization.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v32-npx-installation-guidance",
+    "branch_name": "docs/npx-node-modules-guidance"
+  },
+  "files": [
+    "README.md",
+    "README_FOR_AI.md",
+    "docs/getting-started/installation.md",
+    "docs/reference/commands.md",
+    "docs/TROUBLESHOOTING.md",
+    "docs/TROUBLESHOOTING.md.template",
+    "docs/COMMANDS.md.template"
+  ],
+  "expected_read_paths": [
+    "README_FOR_AI.md",
+    "README.md",
+    "docs/reference/commands.md",
+    "docs/TROUBLESHOOTING.md.template",
+    "docs/COMMANDS.md.template"
+  ],
+  "allowed_write_paths": [
+    "README.md",
+    "README_FOR_AI.md",
+    "docs/getting-started/installation.md",
+    "docs/reference/commands.md",
+    "docs/TROUBLESHOOTING.md",
+    "docs/TROUBLESHOOTING.md.template",
+    "docs/COMMANDS.md.template",
+    "specs/quiver-v32-npx-installation-guidance/**"
+  ],
+  "depends_on": [],
+  "parallel_safe": "yes",
+  "parallel_safe_reason": "This is the only documentation slice in the spec.",
+  "must": [
+    "Explain that npx executes Quiver from npm's execution cache.",
+    "Explain why node_modules is not populated by npx usage.",
+    "Explain when to install create-quiver as a devDependency.",
+    "Keep README_FOR_AI synchronized.",
+    "Avoid claiming runtime behavior changes."
+  ],
+  "not_included": [
+    "Product code changes.",
+    "Package publishing.",
+    "Global install guidance."
+  ],
+  "acceptance": [
+    "README includes concise npx vs local install guidance.",
+    "A dedicated installation guide explains node_modules expectations.",
+    "Troubleshooting covers the missing node_modules symptom.",
+    "Generated docs templates include the same contract.",
+    "README_FOR_AI contains the source-of-truth explanation."
+  ],
+  "tests": [
+    "git diff --check",
+    "node bin/create-quiver.js spec validate specs/quiver-v32-npx-installation-guidance"
+  ],
+  "validation_hints": [
+    "Keep the docs concise and avoid duplicating long workflows in the root README.",
+    "Do not recommend global installation."
+  ],
+  "estimated_hours": 1,
+  "status": "completed",
+  "blocked_reason": null,
+  "actual_hours": 1,
+  "completed_at": "2026-05-27"
+}

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.