create-quiver 0.15.1 → 0.15.3

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.

package/specs/quiver-v33-approval-ux-and-planner-progress/slices/slice-00-approval-ux-foundation/CLOSURE_BRIEF.md

@@ -0,0 +1,30 @@
+# CLOSURE_BRIEF - slice-00 Approval UX foundation
+
+## Summary
+
+Created the v33 planning package for approval UX, planner progress, shared approval decision guidance, and revise input guardrails.
+
+## Validation Against Acceptance Criteria
+
+- [x] Spec folder created.
+- [x] Every slice has `slice.json`, `EXECUTION_BRIEF.md`, and `CLOSURE_BRIEF.md`.
+- [x] Product code was not modified.
+- [x] JSON validation captured.
+- [x] Spec validation captured.
+- [x] `git diff --check` captured.
+
+## Relevant Changes
+
+- New folder: `specs/quiver-v33-approval-ux-and-planner-progress/`.
+
+## Pending
+
+- None.
+
+## Remaining Risks
+
+- The repository still lacks `docs/INDEX.md`; this spec used the documented Quiver sources available in the repo.
+
+## Future Recommendations
+
+Keep future approval-gate changes covered by focused selector, no-TTY, review-state, and workflow-surface tests.

package/specs/quiver-v33-approval-ux-and-planner-progress/slices/slice-00-approval-ux-foundation/EXECUTION_BRIEF.md

@@ -0,0 +1,56 @@
+# EXECUTION_BRIEF - slice-00 Approval UX foundation
+
+## Context
+
+The user approved a revised production-reviewed plan for approval UX, planner progress, revise input guardrails, and shared approval decision guidance.
+
+## Objective
+
+Create the v33 planning package under `specs/quiver-v33-approval-ux-and-planner-progress/` without implementing product code.
+
+## Scope
+
+- `specs/quiver-v33-approval-ux-and-planner-progress/SPEC.md`
+- `specs/quiver-v33-approval-ux-and-planner-progress/STATUS.md`
+- `specs/quiver-v33-approval-ux-and-planner-progress/EVIDENCE_REPORT.md`
+- `specs/quiver-v33-approval-ux-and-planner-progress/EXECUTION_PLAN.md`
+- `specs/quiver-v33-approval-ux-and-planner-progress/pr.md`
+- all slice folders and handoff briefs
+
+## Acceptance Criteria
+
+- Spec package exists.
+- Every slice has `slice.json`, `EXECUTION_BRIEF.md`, and `CLOSURE_BRIEF.md`.
+- `slice-00` records the approved acceptance criteria and revised technical plan.
+- JSON files parse.
+- Spec validation passes.
+- No product code is modified.
+
+## Technical Plan Summary
+
+Use recent Quiver specs as the local contract and keep slice-00 documentation-only.
+
+## Suggested Steps
+
+1. Create the spec folder.
+2. Create top-level spec artifacts.
+3. Create slice folders and JSON contracts.
+4. Create execution and closure briefs for every slice.
+5. Validate JSON and spec structure.
+
+## Restrictions
+
+- Do not edit `src/`.
+- Do not edit tests.
+- Do not claim implementation is complete.
+
+## Risks
+
+- Missing `docs/INDEX.md` remains a documentation debt outside this slice.
+
+## Completion Checklist
+
+- [x] Spec artifacts created.
+- [x] Slice contracts created.
+- [x] Handoff briefs created.
+- [x] Validation commands run.

package/specs/quiver-v33-approval-ux-and-planner-progress/slices/slice-00-approval-ux-foundation/slice.json

@@ -0,0 +1,65 @@
+{
+  "slice_id": "slice-00-approval-ux-foundation",
+  "ticket": "QUIVER-33-00",
+  "type": "docs",
+  "title": "Approval UX foundation",
+  "objective": "Create the v33 spec package for approval UX, planner progress, and shared decision guidance.",
+  "description": "Publishes the approved spec, execution plan, PR body, status, evidence report, slice definitions, and handoffs without changing product code.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v33-approval-ux-foundation",
+    "branch_name": "feature/QUIVER-33-00-v33-approval-ux-foundation"
+  },
+  "files": [
+    "specs/quiver-v33-approval-ux-and-planner-progress/**"
+  ],
+  "expected_read_paths": [
+    "README_FOR_AI.md",
+    "docs/CLI_UX_GUIDE.md",
+    "docs/reference/commands.md",
+    "docs/workflows/full-ai-spec-to-pr.md",
+    "specs/quiver-v29-planner-prepare-context-cli-ux/**",
+    "specs/quiver-v30-interactive-cli-ux-agent-selection/**",
+    "specs/quiver-v31-ai-model-catalog-agent-selection/**"
+  ],
+  "allowed_write_paths": [
+    "specs/quiver-v33-approval-ux-and-planner-progress/**"
+  ],
+  "depends_on": [],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "slice-00 is the foundation barrier for the spec.",
+  "must": [
+    "Create SPEC.md, STATUS.md, EVIDENCE_REPORT.md, EXECUTION_PLAN.md, and pr.md.",
+    "Create slice.json, EXECUTION_BRIEF.md, and CLOSURE_BRIEF.md for every slice.",
+    "Capture approved acceptance criteria and production review fixes.",
+    "Avoid product code changes."
+  ],
+  "not_included": [
+    "Implementing approval selectors.",
+    "Changing command behavior.",
+    "Updating public docs outside this spec package.",
+    "Publishing a package."
+  ],
+  "acceptance": [
+    "Spec folder exists under specs/quiver-v33-approval-ux-and-planner-progress.",
+    "Every slice has slice.json, EXECUTION_BRIEF.md, and CLOSURE_BRIEF.md.",
+    "Every slice.json parses successfully.",
+    "Spec validation passes.",
+    "No product code is modified."
+  ],
+  "tests": [
+    "git diff --check",
+    "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'))\" {} \\;",
+    "node bin/create-quiver.js spec validate specs/quiver-v33-approval-ux-and-planner-progress"
+  ],
+  "validation_hints": [
+    "Keep this slice documentation-only.",
+    "Do not claim implementation or package publication."
+  ],
+  "estimated_hours": 2,
+  "status": "completed",
+  "blocked_reason": null,
+  "actual_hours": 2,
+  "completed_at": "2026-05-28"
+}

package/specs/quiver-v33-approval-ux-and-planner-progress/slices/slice-01-approval-candidates-model/CLOSURE_BRIEF.md

@@ -0,0 +1,19 @@
+# CLOSURE_BRIEF - slice-01 Shared approval candidates model
+
+## Summary
+
+Completed shared approval-candidate construction for acceptance and technical-plan phases. Candidates include current/latest flags, approvability, next command, redacted/truncated previews, and technical-plan review decision data.
+
+## Validation
+
+- [x] Candidate model tests pass.
+- [x] Existing approval and plan-review tests pass.
+- [x] No provider execution added.
+
+## Pending
+
+- None.
+
+## Remaining Risks
+
+- None critical; downstream surfaces consume the model in slice-06.

package/specs/quiver-v33-approval-ux-and-planner-progress/slices/slice-01-approval-candidates-model/EXECUTION_BRIEF.md

@@ -0,0 +1,51 @@
+# EXECUTION_BRIEF - slice-01 Shared approval candidates model
+
+## Context
+
+Approval guidance is currently split across approval persistence, plan-review metadata, `ai approve`, `ai approvals`, `flow`, and run-state formatting.
+
+## Objective
+
+Create a shared read-only candidate model that every later approval UX surface can consume.
+
+## Scope
+
+- `src/create-quiver/lib/approvals.js`
+- `src/create-quiver/lib/ai/plan-review.js`
+- focused tests
+
+## Acceptance Criteria
+
+- Candidate data includes phase, version, path, source, current/latest state, review recommendation, blocking state, risks, and next command.
+- Only the latest draft is marked recommended/approvable.
+- Technical-plan candidates include plan-review state.
+- Candidate summaries are bounded and safe.
+- Existing approval metadata remains backward compatible.
+
+## Technical Plan Summary
+
+Add pure helper functions around existing metadata readers. Keep formatting and interactivity out of this slice except for minimal candidate summary helpers if needed.
+
+## Suggested Steps
+
+1. Model candidate shape.
+2. Build acceptance candidates from approval metadata.
+3. Build technical-plan candidates with plan-review context.
+4. Add unit tests for missing, draft, stale, approved, approve-with-risk, and revise states.
+5. Export only stable helpers needed by later slices.
+
+## Restrictions
+
+- Do not add prompts.
+- Do not change approval persistence format unless tests prove compatibility.
+- Do not relax review blocking.
+
+## Risks
+
+- A poorly scoped helper can become another duplicated formatter instead of a source of truth.
+
+## Completion Checklist
+
+- [ ] Shared candidate helpers implemented.
+- [ ] Candidate tests added.
+- [ ] Existing approval tests still pass.

package/specs/quiver-v33-approval-ux-and-planner-progress/slices/slice-01-approval-candidates-model/slice.json

@@ -0,0 +1,74 @@
+{
+  "slice_id": "slice-01-approval-candidates-model",
+  "ticket": "QUIVER-33-01",
+  "type": "feature",
+  "title": "Shared approval candidates model",
+  "objective": "Create a single approval-candidate model for acceptance, technical-plan, and plan-review decision data.",
+  "description": "Adds reusable read-only candidate construction so approval commands and workflow surfaces share the same current draft, version, review state, recommendation, and next-command guidance.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v33-approval-candidates-model",
+    "branch_name": "feature/QUIVER-33-01-v33-approval-candidates-model"
+  },
+  "files": [
+    "src/create-quiver/lib/approvals.js",
+    "src/create-quiver/lib/ai/plan-review.js",
+    "tests/lib/approvals.test.js",
+    "tests/commands/ai-review-plan.test.js"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/lib/approvals.js",
+    "src/create-quiver/lib/ai/plan-review.js",
+    "src/create-quiver/commands/ai.js",
+    "tests/lib/approvals.test.js",
+    "tests/commands/ai-review-plan.test.js",
+    "SPEC.md"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/lib/approvals.js",
+    "src/create-quiver/lib/ai/plan-review.js",
+    "tests/lib/approvals.test.js",
+    "tests/commands/ai-review-plan.test.js",
+    "specs/quiver-v33-approval-ux-and-planner-progress/**"
+  ],
+  "depends_on": [
+    "slice-00-approval-ux-foundation"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "This model is a dependency for later command and workflow surfaces.",
+  "must": [
+    "Expose candidate data without changing existing persisted approval metadata unless required.",
+    "Include phase, version, path, created_at, source_file, latest/current flags, status, recommendation, blocking state, recommended action, and next command.",
+    "Represent older drafts as history but mark them non-current and not recommended.",
+    "Expose technical-plan plan-review state using the existing plan-review semantics.",
+    "Use redacted/truncated summary helpers for any preview text.",
+    "Keep JSON/no-TTY consumers clean."
+  ],
+  "not_included": [
+    "Interactive prompts.",
+    "Changing approval execution behavior.",
+    "Changing plan-review blocking rules."
+  ],
+  "acceptance": [
+    "Acceptance candidates include the latest draft and draft history.",
+    "Technical-plan candidates include plan-review state and recommendation.",
+    "Older drafts are visible as history but not marked approvable.",
+    "A revise recommendation is represented as blocking.",
+    "Approve-with-risk is represented as approvable with risks.",
+    "Candidate summaries do not print unbounded draft contents."
+  ],
+  "tests": [
+    "node --test tests/lib/approvals.test.js tests/commands/ai-review-plan.test.js",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Prefer pure functions that can be reused by commands without I/O side effects.",
+    "Do not call providers in this slice."
+  ],
+  "estimated_hours": 6,
+  "status": "completed",
+  "blocked_reason": null,
+  "actual_hours": 6,
+  "completed_at": "2026-05-28"
+}

package/specs/quiver-v33-approval-ux-and-planner-progress/slices/slice-02-approve-interactive-selection/CLOSURE_BRIEF.md

@@ -0,0 +1,20 @@
+# CLOSURE_BRIEF - slice-02 Interactive approval selection
+
+## Summary
+
+Completed TTY approval selection for acceptance and technical-plan when `--version` is omitted, while preserving explicit version approval for scripts and CI.
+
+## Validation
+
+- [x] Acceptance selector test passes.
+- [x] Technical-plan selector test passes.
+- [x] No-TTY/CI failure test passes.
+- [x] Explicit version regression test passes.
+
+## Pending
+
+- None.
+
+## Remaining Risks
+
+- None critical; slice-06 integrates shared guidance into the remaining surfaces.