create-quiver 0.14.0 → 0.14.1

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

@@ -0,0 +1,95 @@
+## Title
+
+Quiver v29: planner-assisted prepare-context and CLI UX standard
+
+## Summary
+
+- Adds a shared UX standard for Quiver CLI commands.
+- Keeps `ai prepare-context` deterministic by default.
+- Adds an explicit planner-assisted prepare-context mode.
+- Adds review and interactive patterns with safe non-interactive alternatives.
+- Standardizes color tokens, loaders, prompts, JSON/CI/no-TTY behavior, and command flag applicability.
+
+## Scope
+
+- CLI UX infrastructure and docs.
+- Planner proposal validation for context documentation.
+- `ai prepare-context` planner-assisted mode.
+- Progressive UX adoption for selected commands.
+- Tests, generated docs, and package readiness.
+
+## Files
+
+Expected areas:
+
+- `src/create-quiver/index.js`
+- `src/create-quiver/commands/ai.js`
+- `src/create-quiver/commands/spec.js`
+- `src/create-quiver/lib/cli/**`
+- `src/create-quiver/lib/ai/**`
+- `docs/**`
+- `README.md`
+- `README_FOR_AI.md`
+- `tests/**`
+- `package.json`
+- `package-lock.json`
+- `specs/quiver-v29-planner-prepare-context-cli-ux/**`
+
+## How to Test (DETAILED - REQUIRED)
+
+### Required Environment
+
+- Node.js and npm.
+- Git.
+- Local provider CLI only for provider-backed tests/manual smoke.
+
+### Worktree Access
+
+- One spec worktree dedicated to `quiver-v29-planner-prepare-context-cli-ux`.
+- One commit per slice.
+
+### Run the Project
+
+This is a CLI framework change. Run command-level tests and smoke commands from the Quiver repo root.
+
+### Use Cases
+
+- Run deterministic `ai prepare-context`.
+- Run planner-assisted dry-run.
+- Print planner prompt without provider auth.
+- Review planner proposal with `$EDITOR`.
+- Confirm JSON/no-TTY/CI output stays clean.
+- Confirm unsupported UX flags fail with actionable guidance.
+
+### Technical Verification
+
+- `node --test tests/**/*.test.js`
+- `npm run smoke:create-quiver`
+- `npm run smoke:doctor-fixtures`
+- `npm run smoke:guided-workflow`
+- `npm run package:quiver`
+- `npm pack --dry-run`
+- `git diff --check`
+- `npx create-quiver spec validate specs/quiver-v29-planner-prepare-context-cli-ux`
+
+## Evidence
+
+- Focused command/UX tests passed with 87 tests.
+- Full suite passed with 426 tests.
+- `npm run smoke:create-quiver` passed.
+- `npm run smoke:doctor-fixtures` passed with 13 fixture states.
+- `npm run smoke:guided-workflow` passed.
+- `npm run package:quiver` passed.
+- `npm pack --dry-run` passed for `create-quiver@0.14.0`.
+- `git diff --check` passed.
+- `node bin/create-quiver.js spec validate specs/quiver-v29-planner-prepare-context-cli-ux` passed.
+
+## Rollback
+
+Revert the slice commits in reverse order. The deterministic `ai prepare-context` default must remain available throughout rollback.
+
+## Risks / Notes
+
+- Dependencies must be validated for CJS/ESM compatibility and package size.
+- Human-mode visual output must never leak into JSON or CI output.
+- Planner output must be treated as untrusted until validated.

package/specs/quiver-v29-planner-prepare-context-cli-ux/slices/slice-00-cli-ux-spec-foundation/CLOSURE_BRIEF.md

@@ -0,0 +1,32 @@
+# CLOSURE_BRIEF - slice-00 CLI UX spec foundation
+
+## Summary
+
+Created and validated the Quiver v29 spec package for planner-assisted `ai prepare-context` and the shared CLI UX standard.
+
+## Validation Against Acceptance Criteria
+
+- Spec root includes `SPEC.md`, `EXECUTION_PLAN.md`, `STATUS.md`, `EVIDENCE_REPORT.md`, and `pr.md`.
+- Every slice folder includes `slice.json`, `EXECUTION_BRIEF.md`, and `CLOSURE_BRIEF.md`.
+- Every `slice.json` parsed successfully.
+- Every brief passed `check-handoff`.
+- `spec validate` passed.
+- `git diff --check` passed.
+
+## Relevant Changes
+
+- Added `specs/quiver-v29-planner-prepare-context-cli-ux/**`.
+- Added 7 planned slices with dependencies and execution waves.
+- Captured approved acceptance criteria, technical plan, UX flag matrix, Quiver color tokens, and validation strategy.
+
+## Pending Work
+
+- Execute implementation slices after this documentation foundation commit.
+
+## Remaining Risks
+
+- Implementation still needs to validate dependency impact, terminal compatibility, planner output safety, and docs sync.
+
+## Future Recommendations
+
+- Keep this slice as the scope anchor for Quiver v29 and update later closure briefs with evidence rather than changing approved scope.

package/specs/quiver-v29-planner-prepare-context-cli-ux/slices/slice-00-cli-ux-spec-foundation/EXECUTION_BRIEF.md

@@ -0,0 +1,45 @@
+# EXECUTION_BRIEF - slice-00 CLI UX spec foundation
+
+## Context
+
+Quiver v29 introduces planner-assisted `ai prepare-context` and a shared CLI UX standard. This slice establishes the documentation foundation only.
+
+## Objective
+
+Commit the approved spec package so later implementation slices have a stable contract.
+
+## Scope
+
+- Review `SPEC.md`, `EXECUTION_PLAN.md`, `STATUS.md`, `pr.md`, and every slice contract.
+- Ensure each slice has `slice.json`, `EXECUTION_BRIEF.md`, and `CLOSURE_BRIEF.md`.
+- Validate JSON and Markdown hygiene.
+
+## Acceptance Criteria
+
+- No product code changes.
+- All slice JSON files parse.
+- `git diff --check` passes.
+- Slice dependencies and allowed write paths are explicit.
+
+## Suggested Steps
+
+1. Inspect the spec package.
+2. Validate every `slice.json`.
+3. Run `git diff --check`.
+4. Commit only the spec package.
+
+## Restrictions
+
+- Do not modify `src/`, tests, package files, or generated templates in this slice.
+- Do not implement CLI behavior.
+
+## Risks
+
+- If this slice is skipped, implementation agents may work from inconsistent scope.
+
+## Completion Checklist
+
+- [ ] Spec package reviewed.
+- [ ] JSON validation passed.
+- [ ] Whitespace validation passed.
+- [ ] Documentation foundation committed.

package/specs/quiver-v29-planner-prepare-context-cli-ux/slices/slice-00-cli-ux-spec-foundation/slice.json

@@ -0,0 +1,58 @@
+{
+  "slice_id": "slice-00-cli-ux-spec-foundation",
+  "ticket": "QUIVER-29-00",
+  "type": "docs",
+  "title": "CLI UX spec foundation",
+  "objective": "Commit the approved spec package, UX standard, execution plan, and slice contracts before implementation begins.",
+  "description": "Creates the documentary foundation for Quiver v29, including the approved acceptance criteria, technical plan, command/flag matrix, execution waves, PR body, and slice handoffs.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v29-cli-ux-spec-foundation",
+    "branch_name": "feature/QUIVER-29-00-v29-cli-ux-spec-foundation"
+  },
+  "files": [
+    "specs/quiver-v29-planner-prepare-context-cli-ux/**"
+  ],
+  "expected_read_paths": [
+    "README_FOR_AI.md",
+    "README.md",
+    "docs/reference/commands.md",
+    "specs/quiver-v28-pixel-quiver-feedback-reconciliation/**"
+  ],
+  "allowed_write_paths": [
+    "specs/quiver-v29-planner-prepare-context-cli-ux/**"
+  ],
+  "depends_on": [],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "This documentation foundation must land before any implementation slice starts.",
+  "must": [
+    "Capture approved acceptance criteria and technical plan.",
+    "Define the UX flag matrix and Quiver color tokens.",
+    "Create EXECUTION_BRIEF.md and CLOSURE_BRIEF.md for every slice.",
+    "Include an execution plan that identifies sequential and parallel-safe waves."
+  ],
+  "not_included": [
+    "Product code changes.",
+    "Dependency installation.",
+    "CLI behavior changes."
+  ],
+  "acceptance": [
+    "The spec root includes SPEC.md, EXECUTION_PLAN.md, STATUS.md, and pr.md.",
+    "Every slice folder includes slice.json, EXECUTION_BRIEF.md, and CLOSURE_BRIEF.md.",
+    "Every slice has explicit dependencies and allowed write paths.",
+    "The documentation package validates as Markdown/JSON and is ready for commit."
+  ],
+  "tests": [
+    "find specs/quiver-v29-planner-prepare-context-cli-ux -name 'slice.json' -print -exec node -e \"JSON.parse(require('fs').readFileSync(process.argv[1], 'utf8'))\" {} \\;",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Run this slice first.",
+    "Do not start code implementation before this slice is committed."
+  ],
+  "estimated_hours": 2,
+  "actual_hours": 2,
+  "completed_at": "2026-05-26",
+  "status": "completed"
+}

package/specs/quiver-v29-planner-prepare-context-cli-ux/slices/slice-01-cli-ux-primitives-theme/CLOSURE_BRIEF.md

@@ -0,0 +1,33 @@
+# CLOSURE_BRIEF - slice-01 CLI UX primitives, theme, and dependencies
+
+## Summary
+
+Completed the shared CLI UX foundation required by later v29 slices.
+
+## Validation Against Acceptance Criteria
+
+- Theme tokens are centralized in `src/create-quiver/lib/cli/theme.js` and tested against the approved Quiver palette.
+- UX mode detection disables prompts, spinners, colors, and decorative output for `--json`, CI, and no-TTY modes.
+- `@clack/prompts` is wrapped behind internal helpers and loaded lazily so command code does not couple to it directly.
+- `$VISUAL`/`$EDITOR` resolution, fallback behavior, shell-free execution, and cancellation paths are tested.
+- `npm run package:quiver` passed after adding dependencies.
+
+## Relevant Changes
+
+- Added runtime dependencies: `@clack/prompts` and `zod`.
+- Added `theme.js`, `ux.js`, and `editor.js` under `src/create-quiver/lib/cli/`.
+- Added focused `node:test` coverage for theme, UX mode/spinner/prompt behavior, and editor resolution/execution.
+
+## Pending Work
+
+- Later slices must adopt these helpers instead of duplicating output logic.
+- `zod` is intentionally added now and will be used by `slice-02` for planner proposal validation.
+
+## Remaining Risks
+
+- `@clack/prompts` is ESM-only; it is loaded through dynamic import and covered by tests, but later command adoption must keep this boundary.
+- Windows editor behavior is covered through injected platform/runner tests; real terminal coverage remains part of final smoke/manual validation.
+
+## Future Recommendations
+
+- Keep UX helpers minimal and command-owned: command behavior should stay testable without a real TTY.

package/specs/quiver-v29-planner-prepare-context-cli-ux/slices/slice-01-cli-ux-primitives-theme/EXECUTION_BRIEF.md

@@ -0,0 +1,49 @@
+# EXECUTION_BRIEF - slice-01 CLI UX primitives, theme, and dependencies
+
+## Context
+
+Quiver currently has no runtime dependencies and uses direct string output. This slice adds a shared UX layer carefully so later command changes stay consistent and script-safe.
+
+## Objective
+
+Create internal helpers for Quiver-branded human output, prompts, spinners, mode detection, and editor review.
+
+## Scope
+
+- Add `@clack/prompts` and `zod` only if required by the approved implementation path.
+- Add `src/create-quiver/lib/cli/theme.js`.
+- Add `src/create-quiver/lib/cli/ux.js`.
+- Add `src/create-quiver/lib/cli/editor.js`.
+- Add focused unit tests.
+
+## Acceptance Criteria
+
+- Existing commands keep current behavior unless using new helpers internally without visible behavior changes.
+- No output decoration in CI/no-TTY/JSON/no-color modes.
+- Quiver color tokens match the approved palette.
+- `$VISUAL`/`$EDITOR` fallback is tested.
+
+## Suggested Steps
+
+1. Add dependencies and lockfile updates.
+2. Implement theme tokens and symbol fallbacks.
+3. Implement mode detection and human-output helpers.
+4. Implement editor helper with cancellation handling.
+5. Add unit tests.
+6. Run package smoke.
+
+## Restrictions
+
+- Do not migrate CLI parsing in this slice.
+- Do not modify `ai prepare-context` behavior yet.
+
+## Risks
+
+- Dependency ESM/CJS compatibility can break `npx`.
+- Decoration can leak into tests if mode detection is weak.
+
+## Completion Checklist
+
+- [ ] Dependencies justified and package smoke passes.
+- [ ] Theme/helper/editor tests pass.
+- [ ] No hardcoded Quiver colors outside the theme module.

package/specs/quiver-v29-planner-prepare-context-cli-ux/slices/slice-01-cli-ux-primitives-theme/slice.json

@@ -0,0 +1,75 @@
+{
+  "slice_id": "slice-01-cli-ux-primitives-theme",
+  "ticket": "QUIVER-29-01",
+  "type": "feature",
+  "title": "CLI UX primitives, theme, and dependencies",
+  "objective": "Add shared CLI UX primitives for human output, TTY/CI detection, Quiver colors, prompts, spinners, and editor support without changing command behavior yet.",
+  "description": "Introduces the reusable internal UX layer that later command slices can adopt safely.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v29-cli-ux-primitives-theme",
+    "branch_name": "feature/QUIVER-29-01-v29-cli-ux-primitives-theme"
+  },
+  "files": [
+    "package.json",
+    "package-lock.json",
+    "src/create-quiver/lib/cli/theme.js",
+    "src/create-quiver/lib/cli/ux.js",
+    "src/create-quiver/lib/cli/editor.js",
+    "tests/lib/cli-theme.test.js",
+    "tests/lib/cli-ux.test.js",
+    "tests/lib/cli-editor.test.js",
+    "specs/quiver-v29-planner-prepare-context-cli-ux/**"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/index.js",
+    "src/create-quiver/commands/next.js",
+    "package.json",
+    "tests/**"
+  ],
+  "allowed_write_paths": [
+    "package.json",
+    "package-lock.json",
+    "src/create-quiver/lib/cli/**",
+    "tests/lib/cli-theme.test.js",
+    "tests/lib/cli-ux.test.js",
+    "tests/lib/cli-editor.test.js",
+    "specs/quiver-v29-planner-prepare-context-cli-ux/**"
+  ],
+  "depends_on": [
+    "slice-00-cli-ux-spec-foundation"
+  ],
+  "parallel_safe": "after_dependencies",
+  "parallel_safe_reason": "Must run before other implementation slices because it owns shared helpers and dependencies.",
+  "must": [
+    "Add Quiver color tokens in one shared module.",
+    "Detect TTY, CI, JSON, no-color, and machine-output modes.",
+    "Wrap @clack/prompts behind internal helpers so command code is not coupled directly.",
+    "Add editor helper using VISUAL, EDITOR, and safe fallback.",
+    "Keep existing command behavior unchanged."
+  ],
+  "not_included": [
+    "Planner proposal parsing.",
+    "prepare-context behavior changes.",
+    "Full parser migration to commander/yargs/oclif."
+  ],
+  "acceptance": [
+    "Theme tokens are centralized and tested.",
+    "UX helpers disable decoration for CI, no-TTY, --json, and no-color mode.",
+    "Editor helper handles missing editor and cancellation without writes.",
+    "Package smoke still passes after dependencies are added."
+  ],
+  "tests": [
+    "node --test tests/lib/cli-theme.test.js tests/lib/cli-ux.test.js tests/lib/cli-editor.test.js",
+    "npm run package:quiver"
+  ],
+  "validation_hints": [
+    "Prefer small wrappers over direct @clack usage in commands.",
+    "Do not hardcode color values outside theme.js."
+  ],
+  "estimated_hours": 6,
+  "actual_hours": 3,
+  "status": "completed",
+  "completed_at": "2026-05-26"
+}

package/specs/quiver-v29-planner-prepare-context-cli-ux/slices/slice-02-planner-context-proposal-contract/CLOSURE_BRIEF.md

@@ -0,0 +1,32 @@
+# CLOSURE_BRIEF - slice-02 Planner context proposal contract
+
+## Summary
+
+Completed a strict planner context proposal contract for future `ai prepare-context --with-planner` usage.
+
+## Validation Against Acceptance Criteria
+
+- Valid structured JSON and fenced JSON planner outputs parse into a normalized docs-only write plan.
+- Unsafe paths are rejected before writes, including product code, dependency/lockfiles, absolute paths, traversal paths, generated outputs, runtime/build config, `.quiver/`, and unapproved docs.
+- Schema validation uses `zod` and reports actionable issues with safe next steps.
+- Invalid raw output can be persisted as a redacted run artifact under `.quiver/runs/<run-id>/raw/`.
+
+## Relevant Changes
+
+- Added `src/create-quiver/lib/ai/context-proposal.schema.js`.
+- Added `src/create-quiver/lib/ai/context-proposal.js`.
+- Added valid, fenced, malformed, product-code, absolute-path, and traversal fixtures under `tests/fixtures/ai-context-proposals/`.
+- Added focused unit tests in `tests/lib/ai-context-proposal.test.js`.
+
+## Pending Work
+
+- `ai prepare-context` must consume this contract in a later slice.
+
+## Remaining Risks
+
+- Planner output compatibility must be tested with real provider transcripts later.
+- The allowlist intentionally matches current `prepare-context` docs; future docs must be added explicitly to avoid unsafe broadening.
+
+## Future Recommendations
+
+- Keep the schema versioned if external agents or dashboards start consuming it.

package/specs/quiver-v29-planner-prepare-context-cli-ux/slices/slice-02-planner-context-proposal-contract/EXECUTION_BRIEF.md

@@ -0,0 +1,47 @@
+# EXECUTION_BRIEF - slice-02 Planner context proposal contract
+
+## Context
+
+Planner-assisted `ai prepare-context` needs a strict contract before any provider output can affect project docs.
+
+## Objective
+
+Create a safe parser and schema for planner-generated documentation proposals.
+
+## Scope
+
+- Add proposal schema.
+- Add proposal parser/normalizer.
+- Add docs-only allowlist.
+- Add path safety checks.
+- Add valid and invalid fixtures.
+
+## Acceptance Criteria
+
+- Unsafe planner output is rejected before writes.
+- Valid planner output becomes a normalized docs-only plan.
+- Errors explain what failed and how to continue safely.
+
+## Suggested Steps
+
+1. Define proposal JSON shape.
+2. Add `zod` schema validation.
+3. Add path normalization and allowlist checks.
+4. Add fixtures for valid, invalid, product-code, absolute-path, traversal, and malformed outputs.
+5. Add unit tests.
+
+## Restrictions
+
+- Do not call providers in this slice.
+- Do not modify `runPrepareContext` write behavior yet.
+
+## Risks
+
+- Too-strict parsing can reject useful planner output; prefer clear repair guidance over unsafe fallback.
+
+## Completion Checklist
+
+- [ ] Valid fixtures parse.
+- [ ] Unsafe fixtures fail.
+- [ ] Proposal errors are actionable.
+- [ ] No docs are written by this slice.

package/specs/quiver-v29-planner-prepare-context-cli-ux/slices/slice-02-planner-context-proposal-contract/slice.json

@@ -0,0 +1,71 @@
+{
+  "slice_id": "slice-02-planner-context-proposal-contract",
+  "ticket": "QUIVER-29-02",
+  "type": "feature",
+  "title": "Planner context proposal contract",
+  "objective": "Define and validate the structured proposal format used when a planner IA suggests context documentation updates.",
+  "description": "Adds the parser, schema, path safety, allowlist checks, and diff-ready internal model for planner-generated context proposals.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v29-planner-context-proposal-contract",
+    "branch_name": "feature/QUIVER-29-02-v29-planner-context-proposal-contract"
+  },
+  "files": [
+    "src/create-quiver/lib/ai/context-proposal.js",
+    "src/create-quiver/lib/ai/context-proposal.schema.js",
+    "src/create-quiver/lib/ai/onboarding-template.js",
+    "tests/lib/ai-context-proposal.test.js",
+    "tests/fixtures/ai-context-proposals/**",
+    "specs/quiver-v29-planner-prepare-context-cli-ux/**"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/lib/ai/onboarding-template.js",
+    "src/create-quiver/lib/ai/safety.js",
+    "src/create-quiver/commands/ai.js",
+    "tests/commands/ai-onboard.test.js",
+    "tests/lib/ai-context-packs.test.js"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/lib/ai/context-proposal.js",
+    "src/create-quiver/lib/ai/context-proposal.schema.js",
+    "src/create-quiver/lib/ai/onboarding-template.js",
+    "tests/lib/ai-context-proposal.test.js",
+    "tests/fixtures/ai-context-proposals/**",
+    "specs/quiver-v29-planner-prepare-context-cli-ux/**"
+  ],
+  "depends_on": [
+    "slice-01-cli-ux-primitives-theme"
+  ],
+  "parallel_safe": "after_dependencies",
+  "parallel_safe_reason": "Can run in parallel with slice-04 if both avoid central CLI parser conflicts.",
+  "must": [
+    "Validate planner proposals with zod.",
+    "Accept structured JSON or fenced JSON output when safe.",
+    "Reject paths outside the repo, path traversal, absolute writes, product code, dependencies, lockfiles, build files, generated files, and runtime config.",
+    "Produce a normalized docs-only write plan that existing prepare-context logic can consume.",
+    "Persist invalid raw output as an artifact only when safe and redacted."
+  ],
+  "not_included": [
+    "Invoking provider CLIs.",
+    "Writing docs from planner proposals.",
+    "Interactive editor review."
+  ],
+  "acceptance": [
+    "Valid planner proposal fixtures parse into a normalized internal model.",
+    "Invalid or unsafe proposals fail before writes.",
+    "Allowed docs-only paths are explicit and tested.",
+    "The parser reports actionable errors with next safe commands."
+  ],
+  "tests": [
+    "node --test tests/lib/ai-context-proposal.test.js"
+  ],
+  "validation_hints": [
+    "Treat planner output as untrusted input.",
+    "Keep schema and allowlist close to the proposal parser."
+  ],
+  "estimated_hours": 8,
+  "actual_hours": 3,
+  "status": "completed",
+  "completed_at": "2026-05-26"
+}

package/specs/quiver-v29-planner-prepare-context-cli-ux/slices/slice-03-prepare-context-planner-review-flow/CLOSURE_BRIEF.md

@@ -0,0 +1,33 @@
+# CLOSURE_BRIEF - slice-03 Planner-assisted prepare-context review flow
+
+## Summary
+
+Completed explicit planner-assisted context preparation for `ai prepare-context`.
+
+## Validation Against Acceptance Criteria
+
+- Default deterministic `ai prepare-context` behavior remains unchanged and existing tests still pass.
+- `--with-planner --dry-run` reports provider invocation, candidate docs, allowed paths, and writes nothing.
+- `--with-planner --print-prompt` prints the exact planner prompt without provider auth or writes.
+- Live `--with-planner` invokes the provider, validates the proposal contract, creates snapshots, and writes only allowed docs.
+- Provider failures, invalid planner output, review cancellation, and declined interactive approval leave docs untouched.
+- `--review` writes a proposal artifact, opens or uses the editor flow, and revalidates edited JSON before writing.
+
+## Relevant Changes
+
+- Extended `src/create-quiver/commands/ai.js` with planner prompt building, dry-run/prompt-only reports, provider execution, proposal review, interactive confirmation, and planner write integration.
+- Updated `src/create-quiver/index.js` to forward planner UX flags/options into `runPrepareContext`.
+- Added `tests/commands/ai-prepare-context-planner.test.js`.
+
+## Pending Work
+
+- Progressive command adoption should reuse this pattern.
+
+## Remaining Risks
+
+- Real provider outputs may need fixture updates after dogfooding.
+- Review mode uses a temporary JSON artifact; future UX can make this artifact easier to discover or persist under run state when useful.
+
+## Future Recommendations
+
+- Consider a future `ai describe-project` alias only if users still find `prepare-context --with-planner` unclear.

package/specs/quiver-v29-planner-prepare-context-cli-ux/slices/slice-03-prepare-context-planner-review-flow/EXECUTION_BRIEF.md

@@ -0,0 +1,52 @@
+# EXECUTION_BRIEF - slice-03 Planner-assisted prepare-context review flow
+
+## Context
+
+The deterministic `ai prepare-context` path must remain default. Planner-assisted mode is opt-in and must never bypass docs-only safety.
+
+## Objective
+
+Implement `ai prepare-context --with-planner` with dry-run, prompt printing, review, and interactive support.
+
+## Scope
+
+- Parse new flags for `ai prepare-context`.
+- Build planner prompt from context pack and current draft plan.
+- Invoke provider only when not dry-run/print-prompt.
+- Validate planner proposal.
+- Snapshot and write docs-only changes.
+- Add editor review flow.
+
+## Acceptance Criteria
+
+- Existing deterministic behavior stays compatible.
+- Planner mode is explicit.
+- No partial writes on provider, validation, editor, or snapshot failure.
+- Human output has clear next safe commands.
+
+## Suggested Steps
+
+1. Extend CLI args for `ai prepare-context`.
+2. Add planner prompt builder or reuse onboarding prompt pieces.
+3. Add dry-run and print-prompt paths.
+4. Add provider execution path.
+5. Add proposal validation and write integration.
+6. Add review flow and tests.
+
+## Restrictions
+
+- Do not allow product code writes.
+- Do not make planner mode default.
+- Do not require interactive prompts for automation.
+
+## Risks
+
+- Combining provider execution, review, and writes can create partial-state bugs unless staged carefully.
+
+## Completion Checklist
+
+- [ ] Default mode unchanged.
+- [ ] Planner dry-run and print-prompt tested.
+- [ ] Provider failure tested.
+- [ ] Review cancellation tested.
+- [ ] Snapshot and docs-only write tested.