create-quiver 0.13.0 → 0.14.1

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.

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

@@ -0,0 +1,82 @@
+{
+  "slice_id": "slice-03-prepare-context-planner-review-flow",
+  "ticket": "QUIVER-29-03",
+  "type": "feature",
+  "title": "Planner-assisted prepare-context review flow",
+  "objective": "Implement `ai prepare-context --with-planner` with dry-run, print-prompt, review, interactive, docs-only writes, snapshots, and safe fallback.",
+  "description": "Extends the current deterministic prepare-context command while preserving its default behavior.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v29-prepare-context-planner-review-flow",
+    "branch_name": "feature/QUIVER-29-03-v29-prepare-context-planner-review-flow"
+  },
+  "files": [
+    "src/create-quiver/index.js",
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/onboarding-template.js",
+    "src/create-quiver/lib/ai/context-proposal.js",
+    "src/create-quiver/lib/ai/artifacts.js",
+    "tests/commands/ai-onboard.test.js",
+    "tests/commands/ai-prepare-context-planner.test.js",
+    "specs/quiver-v29-planner-prepare-context-cli-ux/**"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/index.js",
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/**",
+    "tests/commands/ai-onboard.test.js",
+    "tests/commands/ai-plan.test.js"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/index.js",
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/onboarding-template.js",
+    "src/create-quiver/lib/ai/context-proposal.js",
+    "src/create-quiver/lib/ai/artifacts.js",
+    "tests/commands/ai-onboard.test.js",
+    "tests/commands/ai-prepare-context-planner.test.js",
+    "specs/quiver-v29-planner-prepare-context-cli-ux/**"
+  ],
+  "depends_on": [
+    "slice-02-planner-context-proposal-contract",
+    "slice-04-ux-flag-matrix-compatibility"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Main command integration touches central AI command behavior and should run after contract/flag guardrails are stable.",
+  "must": [
+    "Keep current prepare-context behavior as default.",
+    "Add --with-planner as explicit planner-assisted mode.",
+    "Support --print-prompt without provider auth or writes.",
+    "Support --dry-run without provider execution or writes.",
+    "Support --review with editor review and revalidation.",
+    "Support --interactive only in TTY and with non-interactive flag equivalents.",
+    "Create snapshots before writes.",
+    "Fallback safely to deterministic mode guidance when planner fails."
+  ],
+  "not_included": [
+    "Applying UX flags to unrelated commands.",
+    "Allowing planner writes outside context docs.",
+    "Changing `analyze` behavior."
+  ],
+  "acceptance": [
+    "Default prepare-context tests still pass.",
+    "--with-planner --dry-run reports invocation and candidate docs without writes.",
+    "--with-planner --print-prompt prints exact prompt and exits without provider auth.",
+    "--with-planner --review opens/uses editor flow and revalidates edited proposal.",
+    "Provider failure and invalid planner output produce no partial writes.",
+    "Docs-only snapshots are created before live writes."
+  ],
+  "tests": [
+    "node --test tests/commands/ai-onboard.test.js tests/commands/ai-prepare-context-planner.test.js",
+    "node --test tests/lib/ai-context-proposal.test.js"
+  ],
+  "validation_hints": [
+    "Use injected provider/editor functions in tests.",
+    "Verify no product-code writes through path allowlist tests."
+  ],
+  "estimated_hours": 10,
+  "actual_hours": 5,
+  "status": "completed",
+  "completed_at": "2026-05-26"
+}

package/specs/quiver-v29-planner-prepare-context-cli-ux/slices/slice-04-ux-flag-matrix-compatibility/CLOSURE_BRIEF.md

@@ -0,0 +1,34 @@
+# CLOSURE_BRIEF - slice-04 UX flag matrix and compatibility guardrails
+
+## Summary
+
+Completed centralized UX flag support and early compatibility validation.
+
+## Validation Against Acceptance Criteria
+
+- `--with-planner`, `--interactive`, and `--review` support is centralized in `src/create-quiver/lib/cli/ux-flags.js`.
+- Unsupported UX flags fail before command dispatch and before side effects.
+- Incompatible combinations such as `--json --interactive` and `--json --review` fail before command dispatch.
+- `ai pr` supports `--interactive` and `--review`, while rejecting `--with-planner`.
+- Read-only commands such as `flow`, `ai inspect`, and `ai export` reject unsupported UX flags.
+- Existing `plan --json` output remains parseable when UX flags are not requested.
+
+## Relevant Changes
+
+- Added `src/create-quiver/lib/cli/ux-flags.js`.
+- Updated `src/create-quiver/index.js` to parse UX flags, validate them early, document them in help, and forward supported values to future command handlers.
+- Added `tests/commands/ux-flags.test.js`.
+
+## Pending Work
+
+- Later slices should rely on this matrix instead of ad hoc flag behavior.
+- `slice-03` must implement actual `ai prepare-context --with-planner` behavior now that flags are accepted and forwarded.
+
+## Remaining Risks
+
+- Command help and docs must stay aligned with this matrix.
+- Some supported flags are forwarded before their command behavior exists; final release readiness depends on `slice-03` and `slice-05` completing before merge.
+
+## Future Recommendations
+
+- Consider generating docs/reference command flag tables from the matrix in a future spec.

package/specs/quiver-v29-planner-prepare-context-cli-ux/slices/slice-04-ux-flag-matrix-compatibility/EXECUTION_BRIEF.md

@@ -0,0 +1,46 @@
+# EXECUTION_BRIEF - slice-04 UX flag matrix and compatibility guardrails
+
+## Context
+
+Quiver needs standard UX flags without making every command accept every flag.
+
+## Objective
+
+Centralize and enforce command support for `--with-planner`, `--interactive`, and `--review`.
+
+## Scope
+
+- Add a command/flag matrix.
+- Add parser validation for UX flags.
+- Add incompatible-combination errors.
+- Add tests for CI/no-TTY/JSON behavior.
+
+## Acceptance Criteria
+
+- Unsupported flags fail before side effects.
+- Supported flags are discoverable in help/docs.
+- Machine modes are never decorated.
+
+## Suggested Steps
+
+1. Add central flag support matrix.
+2. Extend arg parsing for new flags.
+3. Validate unsupported and incompatible combinations early.
+4. Add command contract tests.
+5. Confirm existing commands keep passing.
+
+## Restrictions
+
+- Do not implement planner proposal writes here.
+- Do not add prompts to commands in this slice.
+
+## Risks
+
+- Over-strict validation can break existing scripts if flags were previously ignored. Make errors clear and only reject new UX flags.
+
+## Completion Checklist
+
+- [ ] Matrix exists in code.
+- [ ] Matrix is tested.
+- [ ] CI/no-TTY/JSON behavior is protected.
+- [ ] Unsupported flags produce actionable output.

package/specs/quiver-v29-planner-prepare-context-cli-ux/slices/slice-04-ux-flag-matrix-compatibility/slice.json

@@ -0,0 +1,73 @@
+{
+  "slice_id": "slice-04-ux-flag-matrix-compatibility",
+  "ticket": "QUIVER-29-04",
+  "type": "feature",
+  "title": "UX flag matrix and compatibility guardrails",
+  "objective": "Add centralized rules for UX flags, incompatible combinations, machine-output modes, and unsupported command guidance.",
+  "description": "Prevents inconsistent adoption of `--with-planner`, `--interactive`, and `--review` by making command support explicit and testable.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v29-ux-flag-matrix-compatibility",
+    "branch_name": "feature/QUIVER-29-04-v29-ux-flag-matrix-compatibility"
+  },
+  "files": [
+    "src/create-quiver/index.js",
+    "src/create-quiver/lib/cli/ux-flags.js",
+    "src/create-quiver/lib/cli/ux.js",
+    "tests/commands/cli-contract.test.js",
+    "tests/commands/ux-flags.test.js",
+    "tests/lib/cli-ux.test.js",
+    "specs/quiver-v29-planner-prepare-context-cli-ux/**"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/index.js",
+    "src/create-quiver/lib/cli/**",
+    "tests/commands/cli-contract.test.js"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/index.js",
+    "src/create-quiver/lib/cli/ux-flags.js",
+    "src/create-quiver/lib/cli/ux.js",
+    "tests/commands/cli-contract.test.js",
+    "tests/commands/ux-flags.test.js",
+    "tests/lib/cli-ux.test.js",
+    "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-02 if central parser conflicts are avoided.",
+  "must": [
+    "Define which commands support --with-planner, --interactive, and --review.",
+    "Reject unsupported UX flags with actionable messages.",
+    "Reject incompatible combinations such as --json --interactive and --json --review.",
+    "Ensure CI/no-TTY/--json disables spinners, colors, prompts, and decorative output.",
+    "Keep machine-readable stdout parseable."
+  ],
+  "not_included": [
+    "Implementing planner mode itself.",
+    "Migrating all commands to interactive mode.",
+    "Changing existing command semantics beyond flag validation."
+  ],
+  "acceptance": [
+    "Command/flag matrix is enforced in code and documented.",
+    "Unsupported flags fail before side effects.",
+    "Incompatible flag combinations fail before side effects.",
+    "JSON output stays undecorated.",
+    "Human-mode helpers remain opt-in."
+  ],
+  "tests": [
+    "node --test tests/commands/ux-flags.test.js tests/commands/cli-contract.test.js",
+    "node --test tests/lib/cli-ux.test.js"
+  ],
+  "validation_hints": [
+    "Tests should cover both supported and unsupported commands.",
+    "Do not allow partial command execution after flag validation failure."
+  ],
+  "estimated_hours": 7,
+  "actual_hours": 2,
+  "status": "completed",
+  "completed_at": "2026-05-26"
+}