create-quiver 0.13.0 → 0.14.1

package/README_FOR_AI.md

@@ -8,6 +8,7 @@ Important: slice numbering resets inside each spec. `slice-00` is the mandatory
 The canonical installer entrypoint is `npx create-quiver` run from the target project root.
 Do not recommend global installation; use `npx` or a project-local devDependency when the team needs a pinned version.
 The package also exposes `quiver` as a binary alias to the same CLI. Treat it as a local installed shortcut, not as a replacement for the bootstrap command `npx create-quiver`.
+The root `README.md` is the public landing/onboarding page: keep it concise, Spanish-first, AI-first, and focused on what Quiver is, what problem it solves, the WDD + SDD flow, core commands, and links to deeper guides. Long step-by-step instructions live in `docs/getting-started/`, `docs/workflows/`, and `docs/reference/commands.md`; do not duplicate every procedural detail in the root README.
 The post-init contract is validated with `npx create-quiver doctor` from the project root. Use `npx create-quiver doctor --fix --dry-run` to preview safe non-destructive repairs, then `npx create-quiver doctor --fix` only after reviewing the plan.
 If the project already exists from an older Quiver version and was previously initialized by Quiver, run `npx create-quiver migrate` before `analyze` from the project root.
 If the project was never initialized by Quiver, do not use `migrate` as bootstrap; run `npx create-quiver init --name "Project Name"` first.
@@ -18,20 +19,28 @@ The v24 spec is implemented under `specs/quiver-v24-dx-onboarding-hardening/`; i
 The v25 spec is implemented under `specs/quiver-v25-ai-first-lifecycle-orchestrator/` and shipped in `create-quiver@0.12.0`; it covers safe AI onboarding docs, strict run state, phase locks, agent adapters, approval gates, spec/slice generation, execution planning, controlled slice execution, worktree/PR lifecycle, validation hardening, export, and migration.
 The v26 hotfix spec is implemented under `specs/quiver-v26-0121-smoke-hardening/` and shipped in `create-quiver@0.12.1`; it covers smoke hardening for CLI help/version output, generated doc links, AI approval/review guidance, local validation, slice brief validation, demo readiness, scoped plan/graph performance, and release smoke coverage.
 The v27 spec is implemented under `specs/quiver-v27-reliability-ai-workflow-hardening/` and shipped in `create-quiver@0.13.0`; it captures Pixel Quiver dogfooding findings (`QP-001` to `QP-019`, `QIS-001` to `QIS-022`) and includes shared state resolution, canonical statuses, schema v2 exports, structured spec creation, AI artifact cleanup, worktree locks, validation gates, context diagnostics, cross-platform DX, fixtures, smoke suites, and package/tarball release readiness.
+The v28 spec is implemented under `specs/quiver-v28-pixel-quiver-feedback-reconciliation/` and shipped in `create-quiver@0.14.0`; it captures the Pixel Quiver follow-up reconciliation with active-slice reconciliation, stale `ai inspect` recovery, structured review closure, stricter technical-plan approval, spec/worktree validation hardening, agent-safe commands, GitHub auth/alias guidance, and package-readiness evidence.
+The v29 spec is implemented under `specs/quiver-v29-planner-prepare-context-cli-ux/` and is pending package publication; it adds shared CLI UX primitives, Quiver palette usage, guarded UX flags, planner-assisted `ai prepare-context`, and review/interactive adoption for selected planner/spec/PR commands.
 Guided AI workflow behavior is available: prepare, approvals, production-readiness plan review, spec worktrees, executor commits, execution waves, PR creation, spec close, and package safety.
 Generated projects also get `quiver:*` npm scripts that call the Node CLI directly; prefer those for repeatable project workflows, including `quiver:flow` for the read-only guided entrypoint, `quiver:plan` for sequential planning, `quiver:graph` for parallel-level inspection, `quiver:next` for the next ready slice, `quiver:evidence` for local command evidence, `quiver:spec:create` for real spec generation, `quiver:spec:validate` for full spec validation, and the AI family `quiver:ai:agent`, `quiver:ai:inspect`, `quiver:ai:export`, `quiver:ai:specs`, `quiver:ai:slices`, `quiver:ai:trace`, `quiver:ai:onboard`, `quiver:ai:prepare-context`, `quiver:ai:plan`, `quiver:ai:review-plan`, `quiver:ai:approve`, `quiver:ai:prompt-slice`, `quiver:ai:execute-slice`, `quiver:ai:execute-plan`, `quiver:ai:pr`, and `quiver:ai:doctor`. Use `quiver:graph --format mermaid` for PR-ready Markdown or `quiver:graph --format dot` for Graphviz source.
 `quiver:ai:execute-plan` supports `--mode manual` for paste-ready executor prompts and `--mode delegated` for temporary worktrees on parallel-ready waves; unsafe waves fall back to sequential execution.
 Agent profiles live in `.quiver/agents/profiles.json`; they store role, provider, model label, context label, and display label only. Do not store API keys, tokens, or credentials there.
 Planner drafts are versioned under `.quiver/approvals/<phase>/drafts/`; review the technical-plan draft with `npx create-quiver ai review-plan --dry-run` before approving it, then approve a concrete version with `npx create-quiver ai approve --phase <phase> --version <n>` when reviewing iterations.
+`ai review-plan` stores structured closure metadata under `.quiver/approvals/plan-review/meta.json`: `approval_recommendation` is `approve`, `approve-with-risk`, or `revise`; required fixes block technical-plan approval, while optional hardening does not.
 AI lifecycle runs are persisted under `.quiver/runs/<run-id>/`; use `npx create-quiver ai run create --input <requirements.md>` to start one explicitly, `npx create-quiver ai status` to inspect it, `npx create-quiver ai resume` to continue from the last valid phase without relying on chat memory, and `npx create-quiver ai export --format json|markdown` when another agent, PR, or dashboard needs the current specs/slices/runs state.
+Use `npx create-quiver ai active-slice reconcile --dry-run` when `docs/ai/ACTIVE_SLICE.md`, `ACTIVE_SLICES.md`, worktrees, or `ai inspect` appear out of sync. The command is dry-run-first and reports preserve, close, replace, or blocked decisions without writing files.
+When generating commands for another AI agent, prefer non-interactive package-pinned examples such as `npx --yes create-quiver@<version> ai prompt-slice --slice <slice.json> --dry-run`.
 Maintain release notes and package publishing with `scripts/release-quiver.sh`.
 Use `npm run smoke:doctor-fixtures` after changing doctor, preflight, validation, actionable errors, or fixture coverage.
 The primary generated project context for agents is `docs/AI_CONTEXT.md`.
 The project map is the single source of truth for stack, package manager, commands, and file hints: `docs/PROJECT_MAP.md`.
 The raw analyzer output is internal machinery at `.quiver/scans/PROJECT_SCAN.json`; read it only when the visible map is not enough.
 `npx create-quiver analyze --dry-run` must remain read-only and only preview the scan/project-map/context writes. `npx create-quiver flow` reports the context source/freshness and the package-manager-aware generated script command so agents can see whether the project map is current, stale, partial, legacy, invalid, or missing.
+`npx create-quiver ai prepare-context --dry-run` remains the deterministic default and must not execute provider CLIs. `npx create-quiver ai prepare-context --with-planner --dry-run` previews planner-assisted context preparation. `--with-planner --print-prompt` prints the exact prompt without provider auth; live planner writes should use `--review` and/or `--interactive` when the human wants review before docs-only writes.
 `npx create-quiver ai agent set <role> --provider <provider> --model "<label>" --dry-run` must preview `.quiver/agents/profiles.json` changes without writing. Use it before saving planner/executor/reviewer/doctor profiles.
 GitHub PR diagnostics must stay cross-platform: auth failures should point to likely account, scope, and SSH alias issues; path examples with spaces must be copy-safe for macOS/Linux, Windows PowerShell, Git Bash, and WSL.
+CLI UX standard lives in `docs/CLI_UX_GUIDE.md`. Supported Quiver colors are `#86C8F2`, `#6BADEB`, `#7F9EE8`, `#9B82E6`, and `#D56AB0`; output must respect `--no-color`, `NO_COLOR`, CI, and no-TTY environments.
+UX flags are intentionally limited: `ai prepare-context`, `ai plan`, and `spec create` support `--with-planner`, `--interactive`, and `--review`; `ai pr` supports `--interactive` and `--review` but rejects `--with-planner`; read-only commands such as `flow`, `next`, `graph`, `ai inspect`, `ai export`, `ai specs list`, `ai slices list`, and `ai trace report` reject these UX flags. `--json` must reject `--interactive` and `--review` before writing human output.
 The universal router for generated projects is `AGENTS.md`; read it before `docs/AI_CONTEXT.md` and `docs/AI_ONBOARDING_PROMPT.md`.
 Generated projects also get `docs/DECISIONS.md`; use it for durable choices that should not be re-litigated.
 If a generated project has been analyzed, the exact agent handoff prompt is `docs/AI_ONBOARDING_PROMPT.md`.
@@ -137,32 +146,33 @@ Init preserves existing target files and reports skipped copies instead of overw
 After initialization, the user should:
 
 1. Run `npx create-quiver flow` when unsure about the next safe command
-2. Run `npx create-quiver ai prepare-context --dry-run` to preview onboarding docs, diffs, assumptions, risks, contradictions, and omitted paths
-3. After review, run `npx create-quiver ai prepare-context` to write docs-only context updates; Quiver snapshots touched docs under `.quiver/runs/<run-id>/snapshots/` and preserves human-authored content
-4. Run `npx create-quiver analyze --dry-run` when unsure what analysis would update, then run `npx create-quiver analyze` if `docs/PROJECT_MAP.md` or `.quiver/scans/PROJECT_SCAN.json` is missing or stale
-5. If the project already exists from an older Quiver version and was previously initialized by Quiver, run `npx create-quiver migrate`
-6. If the project was never initialized by Quiver, run `npx create-quiver init --name "Project Name"` instead of `migrate`
-7. Ask the AI agent to execute `docs/AI_ONBOARDING_PROMPT.md`
-8. Review context docs before creating the first implementation slice
-9. Open and merge the documentation PR that establishes the workflow files
-10. Preview reusable provider choices with `npx create-quiver ai agent set <role> --provider <provider> --model "<label>" --dry-run`, then save planner/executor/doctor profiles without `--dry-run` after review
-11. Use `npx create-quiver ai plan --phase acceptance --input requirements.md --dry-run`; use `--print-prompt` when you need the exact prompt without provider auth
-12. If the human asks for changes, create a new draft with `npx create-quiver ai revise --phase acceptance --input feedback.md --dry-run`; after human approval, save the selected current draft with `npx create-quiver ai approve --phase acceptance --version <n>`
-13. Use `npx create-quiver ai plan --phase technical-plan --dry-run`
-14. Review the technical plan with `npx create-quiver ai review-plan --dry-run`, inspect exact prompt with `--print-prompt` if needed, then run it without `--dry-run` when ready
-15. After human approval, save the reviewed plan version with `npx create-quiver ai approve --phase technical-plan --version <n>`
-16. Use `npx create-quiver spec create --dry-run` to preview the real spec, slices, handoffs, execution plan, and PR body, then run it without `--dry-run` when ready
-17. Run `npx create-quiver spec start specs/<spec-slug> --dry-run` to inspect the planned worktree, then run without `--dry-run` to create or reuse it
-18. Run `npx create-quiver plan` or `npm run quiver:plan`
-19. Run `npx create-quiver next` or `npm run quiver:next`
-20. Run `npx create-quiver ai execute-plan --dry-run --commit --mode manual` to inspect prompts, or `npx create-quiver ai execute-plan --dry-run --commit --mode delegated` to inspect delegated execution waves
-21. For manual assignment, print a minimal executor prompt with `npx create-quiver ai prompt-slice --slice <slice.json> --dry-run`
-22. Execute one slice with `npx create-quiver ai execute-slice --slice <slice.json> --commit` or execute delegated waves with `npx create-quiver ai execute-plan --execute --commit --mode delegated`; single-slice execution must run from the declared slice branch, validates `allowed_write_paths`/`files`, redacts captured logs, and updates closure, evidence, command log, status, and `slice.json`
-23. Keep one commit per slice
-24. Open one PR per spec with `npx create-quiver ai pr --dry-run --input specs/<spec-slug>/pr.md --ssh-host-alias <alias> ...`, then `--create` only after review; PR creation is blocked while spec slices remain open
-25. After merge, close the worktree with `npx create-quiver spec close specs/<spec-slug>`
-26. Validate the spec with `npx create-quiver spec validate specs/<spec-slug>` or `npm run quiver:spec:validate -- specs/<spec-slug>`
-27. Validate the slice and the final PR with the workflow gates
+2. Run `npx create-quiver ai prepare-context --dry-run` to preview deterministic onboarding docs, diffs, assumptions, risks, contradictions, and omitted paths without provider execution
+3. If the user wants planner-generated context, run `npx create-quiver ai prepare-context --with-planner --dry-run`; use `--print-prompt` for external planner execution or `--with-planner --review --interactive` before live docs-only writes
+4. After review, run `npx create-quiver ai prepare-context` for deterministic writes or `npx create-quiver ai prepare-context --with-planner --review --interactive` for planner-assisted writes; Quiver snapshots touched docs under `.quiver/runs/<run-id>/snapshots/` and preserves human-authored content
+5. Run `npx create-quiver analyze --dry-run` when unsure what analysis would update, then run `npx create-quiver analyze` if `docs/PROJECT_MAP.md` or `.quiver/scans/PROJECT_SCAN.json` is missing or stale
+6. If the project already exists from an older Quiver version and was previously initialized by Quiver, run `npx create-quiver migrate`
+7. If the project was never initialized by Quiver, run `npx create-quiver init --name "Project Name"` instead of `migrate`
+8. Ask the AI agent to execute `docs/AI_ONBOARDING_PROMPT.md`
+9. Review context docs before creating the first implementation slice
+10. Open and merge the documentation PR that establishes the workflow files
+11. Preview reusable provider choices with `npx create-quiver ai agent set <role> --provider <provider> --model "<label>" --dry-run`, then save planner/executor/doctor profiles without `--dry-run` after review
+12. Use `npx create-quiver ai plan --phase acceptance --input requirements.md --dry-run`; use `--print-prompt` when you need the exact prompt without provider auth and `--review --interactive` when the human should edit or confirm before saving
+13. If the human asks for changes, create a new draft with `npx create-quiver ai revise --phase acceptance --input feedback.md --dry-run`; after human approval, save the selected current draft with `npx create-quiver ai approve --phase acceptance --version <n>`
+14. Use `npx create-quiver ai plan --phase technical-plan --dry-run`
+15. Review the technical plan with `npx create-quiver ai review-plan --dry-run`, inspect exact prompt with `--print-prompt` if needed, then run it without `--dry-run` when ready
+16. After human approval, save the reviewed plan version with `npx create-quiver ai approve --phase technical-plan --version <n>`
+17. Use `npx create-quiver spec create --dry-run` to preview the real spec, slices, handoffs, execution plan, and PR body; use `--review --interactive` when the human should inspect the package before writing
+18. Run `npx create-quiver spec start specs/<spec-slug> --dry-run` to inspect the planned worktree, then run without `--dry-run` to create or reuse it
+19. Run `npx create-quiver plan` or `npm run quiver:plan`
+20. Run `npx create-quiver next` or `npm run quiver:next`
+21. Run `npx create-quiver ai execute-plan --dry-run --commit --mode manual` to inspect prompts, or `npx create-quiver ai execute-plan --dry-run --commit --mode delegated` to inspect delegated execution waves
+22. For manual assignment, print a minimal executor prompt with `npx create-quiver ai prompt-slice --slice <slice.json> --dry-run`
+23. Execute one slice with `npx create-quiver ai execute-slice --slice <slice.json> --commit` or execute delegated waves with `npx create-quiver ai execute-plan --execute --commit --mode delegated`; single-slice execution must run from the declared slice branch, validates `allowed_write_paths`/`files`, redacts captured logs, and updates closure, evidence, command log, status, and `slice.json`
+24. Keep one commit per slice
+25. Open one PR per spec with `npx create-quiver ai pr --dry-run --input specs/<spec-slug>/pr.md --ssh-host-alias <alias> ...`, optionally use `--review`, then `--create --interactive` only after review; PR creation is blocked while spec slices remain open
+26. After merge, close the worktree with `npx create-quiver spec close specs/<spec-slug>`
+27. Validate the spec with `npx create-quiver spec validate specs/<spec-slug>` or `npm run quiver:spec:validate -- specs/<spec-slug>`
+28. Validate the slice and the final PR with the workflow gates
 
 Bootstrap note: `start-slice` should resolve paths canonically, prefer a local `develop` or `main` base branch before reaching for `origin`, and reject `draft` slices unless `--allow-draft` is passed intentionally.
 Release note: `scripts/package-quiver.sh` runs package safety against the npm tarball and must fail if local AI state, env files, npm credentials, or worktree state would be published.

package/ROADMAP.md

@@ -75,6 +75,15 @@
 - Published package `0.13.0`.
 - **v27** — Reliability hardening from Pixel Quiver dogfooding: shared state resolver, canonical statuses, JSON export contract, approved-plan spec generation, AI artifact cleanup, token compaction, worktree lifecycle, validation gates, context diagnostics, cross-platform DX, fixtures, smoke tests, and package/tarball release readiness live in `specs/quiver-v27-reliability-ai-workflow-hardening/`.
 
+## v0.14 — Pixel Quiver Feedback Reconciliation (shipped 2026-05-25)
+
+- Published package `0.14.0`.
+- **v28** — Follow-up hardening from Pixel Quiver dogfooding: active-slice reconciliation, spec-aware `ai inspect` recovery, structured plan-review closure, safer technical-plan approval, stronger spec/worktree validation, agent-safe command examples, GitHub auth/alias guidance, and final release-readiness evidence live in `specs/quiver-v28-pixel-quiver-feedback-reconciliation/`.
+
+## v0.15 — Planner Context and CLI UX Standard (in progress)
+
+- **v29** — Planner-assisted context preparation and CLI UX standard: shared output helpers, Quiver palette, guarded `--with-planner` / `--interactive` / `--review` flags, optional planner-generated `ai prepare-context`, review/interactive adoption for selected commands, docs, tests, and smoke readiness live in `specs/quiver-v29-planner-prepare-context-cli-ux/`.
+
 ## Post-Checkpoint Plan (do not execute before validating v14)
 
 > This section now records the follow-up line from the v14-era plan.
@@ -91,6 +100,8 @@
 - **v25 — AI-First Lifecycle Orchestrator** (shipped in `0.12.0`): safe AI onboarding docs, strict run state, phase locks, agent adapters, approval gates, generated specs/slices/handoffs/PR body, execution waves, controlled slice execution, worktree/PR lifecycle, validation hardening, export, and migration live in `specs/quiver-v25-ai-first-lifecycle-orchestrator/`.
 - **v26 — 0.12.1 Smoke Hardening** (shipped in `0.12.1`): first-use hardening from clean npm smoke testing, covering CLI help/version output, generated doc links, AI approval/review guidance, local validation, slice brief validation, demo readiness, scoped plan/graph performance, and release smoke coverage live in `specs/quiver-v26-0121-smoke-hardening/`.
 - **v27 — Reliability and AI Workflow Hardening** (shipped in `0.13.0`): Pixel Quiver dogfooding follow-up covering resolver/export/spec-create/AI-artifact/worktree/validation/context/DX hardening lives in `specs/quiver-v27-reliability-ai-workflow-hardening/`.
+- **v28 — Pixel Quiver Feedback Reconciliation** (shipped in `0.14.0`): active-slice reconciliation, stale inspect recovery, structured review closure, validation/worktree hardening, agent-safe commands, GitHub auth guidance, and release-readiness evidence live in `specs/quiver-v28-pixel-quiver-feedback-reconciliation/`.
+- **v29 — Planner Context and CLI UX Standard** (in progress): planner-assisted `ai prepare-context`, CLI UX primitives, guarded UX flags, human review/interactive flows, and final docs/smoke readiness live in `specs/quiver-v29-planner-prepare-context-cli-ux/`.
 
 The shipped v20/v21/v22/v23 work is no longer pending. The older context-diagnostics and slice-archaeology ideas remain deferred until real demand justifies them.
 

package/assets/quiver-wordmark.svg

@@ -0,0 +1,22 @@
+<svg width="1120" height="360" viewBox="0 0 1120 360" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="title desc">
+  <title id="title">Quiver</title>
+  <desc id="desc">Pixel style Quiver wordmark for the AI-first WDD and SDD workflow framework.</desc>
+  <rect width="1120" height="360" fill="#11151d"/>
+  <rect x="34" y="34" width="1052" height="292" fill="#151b25" stroke="#334155" stroke-width="6"/>
+  <g transform="translate(448 34)">
+    <rect x="0" y="36" width="34" height="34" fill="#7dd3fc"/>
+    <rect x="34" y="36" width="34" height="34" fill="#38bdf8"/>
+    <rect x="68" y="36" width="34" height="34" fill="#60a5fa"/>
+    <rect x="102" y="36" width="34" height="34" fill="#a78bfa"/>
+    <rect x="136" y="36" width="34" height="34" fill="#f472b6"/>
+    <rect x="34" y="70" width="34" height="34" fill="#0f172a"/>
+    <rect x="68" y="70" width="34" height="34" fill="#0f172a"/>
+    <rect x="102" y="70" width="34" height="34" fill="#0f172a"/>
+  </g>
+  <text x="560" y="206" text-anchor="middle" font-family="'Courier New', monospace" font-size="118" font-weight="900" fill="#ffffff" stroke="#020617" stroke-width="16" paint-order="stroke">
+    QUIVER
+  </text>
+  <text x="560" y="276" text-anchor="middle" font-family="'Courier New', monospace" font-size="28" font-weight="700" fill="#93c5fd">
+    AI-FIRST WDD + SDD WORKFLOW FRAMEWORK
+  </text>
+</svg>

package/docs/AI_CONTEXT.md.template

@@ -26,6 +26,7 @@ This file is the main context pack after `AGENTS.md` and `docs/PROJECT_MAP.md`.
 - `docs/DECISIONS.md` tracks durable choices so agents do not re-litigate them.
 - `docs/STATUS.md` tracks progress, blockers, and the current slice.
 - `npx create-quiver ai prepare-context --dry-run` previews docs-only context drafts before writing.
+- `npx create-quiver ai prepare-context --with-planner --dry-run` previews an optional planner-generated context proposal. Use `--print-prompt` to run the prompt elsewhere, `--review` to inspect the proposal, and `--interactive` to confirm before writing.
 
 ## Critical Rules
 
@@ -37,6 +38,7 @@ This file is the main context pack after `AGENTS.md` and `docs/PROJECT_MAP.md`.
 - Never overwrite user-authored content without checking whether the file is meant to be preserved.
 - If a command or path is ambiguous, prefer the local project root and the generated docs.
 - Context preparation must stay in docs/context files and should use TODO, Assumption, or Pending confirmation markers for uncertain statements.
+- Planner-assisted context proposals must remain docs-only. Do not accept product-code, dependency, build, runtime, lockfile, generated-output, absolute-path, or traversal writes.
 
 ## What To Update After A Slice
 

package/docs/AI_ONBOARDING_PROMPT.md.template

@@ -15,7 +15,8 @@ Actúa como asistente de onboarding de IA para este proyecto. Tu objetivo es com
    - Lee `docs/INDEX.md`, si existe, y úsalo como mapa para decidir qué abrir después.
    - Lee `docs/PROJECT_MAP.md` para stack, comandos y estructura. Usa `.quiver/scans/PROJECT_SCAN.json` solo si el mapa visible no alcanza.
    - Lee `docs/AI_CONTEXT.md`, `docs/AI_ONBOARDING_PROMPT.md`, `docs/WORKFLOW.md`, `docs/STATUS.md` y `docs/DECISIONS.md` solo cuando existan y sean relevantes para la tarea.
-   - Si usás `npx create-quiver ai prepare-context`, revisá los borradores propuestos antes de escribir y mantené las escrituras limitadas a docs/context.
+   - Si usás `npx create-quiver ai prepare-context`, empezá con `--dry-run`, revisá los borradores propuestos antes de escribir y mantené las escrituras limitadas a docs/context.
+   - Usá `--with-planner` solo cuando el humano quiera una propuesta generada por un planner IA; combiná `--review` y `--interactive` antes de aplicar escrituras.
    - Lee specs, slices o handoffs solo si la tarea actual lo requiere.
    - No leas todo `docs/` por defecto.
    - Si un documento referenciado no existe, repórtalo como deuda documental.
@@ -73,6 +74,9 @@ Si usás los comandos de IA de Quiver, empezá con `--dry-run` para revisar prov
 ```bash
 npm run quiver:prepare -- --dry-run
 npm run quiver:ai:prepare-context -- --dry-run
+npm run quiver:ai:prepare-context -- --with-planner --dry-run
+npm run quiver:ai:prepare-context -- --with-planner --print-prompt
+npm run quiver:ai:prepare-context -- --with-planner --review --interactive
 npm run quiver:ai:onboard -- --dry-run
 npm run quiver:ai:inspect
 npm run quiver:ai:export -- --format json
@@ -80,18 +84,21 @@ npm run quiver:ai:specs
 npm run quiver:ai:slices
 npm run quiver:ai:trace
 npm run quiver:ai:plan -- --phase acceptance --input requirements.md --dry-run
+npm run quiver:ai:plan -- --phase acceptance --input requirements.md --review --interactive
 npm run quiver:ai:revise -- --phase acceptance --input feedback.md --dry-run
 npm run quiver:ai:approve -- --phase acceptance --version <n>
 npm run quiver:ai:plan -- --phase technical-plan --dry-run
 npm run quiver:ai:review-plan -- --dry-run
 npm run quiver:ai:approve -- --phase technical-plan --version <n>
 npm run quiver:spec:create -- --dry-run
+npm run quiver:spec:create -- --review --interactive
 npm run quiver:spec:start -- specs/{{PROJECT_SLUG}}
 npm run quiver:ai:prompt-slice -- --slice specs/{{PROJECT_SLUG}}/slices/<slice-id>/slice.json --dry-run
 npm run quiver:ai:execute-slice -- --slice specs/{{PROJECT_SLUG}}/slices/<slice-id>/slice.json --dry-run --commit
 npm run quiver:ai:execute-plan -- --dry-run --commit --mode manual
 npm run quiver:ai:execute-plan -- --dry-run --commit --mode delegated
 npm run quiver:ai:pr -- --dry-run --input specs/{{PROJECT_SLUG}}/pr.md --ssh-host-alias github-work --identity-file ~/.ssh/github-work
+npm run quiver:ai:pr -- --review --dry-run --input specs/{{PROJECT_SLUG}}/pr.md --ssh-host-alias github-work --identity-file ~/.ssh/github-work
 npm run quiver:spec:close -- specs/{{PROJECT_SLUG}} --dry-run
 ```
 
@@ -113,6 +120,7 @@ npm run quiver:spec:close -- specs/{{PROJECT_SLUG}} --dry-run
 - Indica rutas omitidas o señales faltantes.
 - Mantén la respuesta enfocada en documentación y contexto de onboarding salvo que el usuario haya autorizado cambios de código de producto.
 - No cambies reglas del workflow de Quiver salvo que el usuario lo pida explícitamente.
+- No combines `--json` con `--interactive` ni `--review`. Si necesitás salida machine-readable, evitá prompts, editores y loaders humanos.
 
 ## Reporte final
 

package/docs/CLI_UX_GUIDE.md

@@ -0,0 +1,125 @@
+# Guia de UX del CLI de Quiver
+
+Este documento define el estandar de experiencia para los comandos de Quiver. La meta es que el CLI sea claro para humanos, seguro para automatizacion y consistente para agentes de IA.
+
+## Principios
+
+- Los comandos deben explicar que modo estan usando: deterministico, planner-assisted, dry-run, review, interactive, JSON o CI.
+- `--dry-run` debe ser el primer paso recomendado antes de escrituras, proveedores externos, worktrees, PRs o reparaciones.
+- La salida humana puede usar jerarquia visual, loaders y color; la salida JSON debe permanecer limpia y parseable.
+- Los prompts interactivos son opt-in. Ningun comando debe bloquear automatizaciones si `--interactive` no fue pedido.
+- Las revisiones humanas ocurren antes de escrituras persistentes siempre que el comando soporte `--review`.
+- Las credenciales viven en los CLIs de proveedor, `gh`, Git o el sistema operativo. Quiver no debe guardarlas.
+
+## Colores de Quiver
+
+Usar esta paleta en loaders, estados, etiquetas y enfasis visual:
+
+| Token | Hex | Uso sugerido |
+|---|---:|---|
+| `sky` | `#86C8F2` | informacion, rutas, contexto |
+| `blue` | `#6BADEB` | acciones primarias, progreso |
+| `periwinkle` | `#7F9EE8` | modo planner, prompts |
+| `violet` | `#9B82E6` | revision, decisiones humanas |
+| `magenta` | `#D56AB0` | advertencias suaves, approval gates |
+
+Reglas:
+
+- Respetar `--no-color`, `NO_COLOR`, CI y terminales sin TTY.
+- No depender solo del color para comunicar estado.
+- Mantener fallback ASCII cuando Unicode no sea seguro.
+
+## Banderas UX
+
+| Flag | Definicion | Regla |
+|---|---|---|
+| `--with-planner` | Activa comportamiento asistido por planner cuando el comando lo soporta. | No debe ser decorativo. Si no cambia el comportamiento o contrato del comando, debe rechazarse. |
+| `--interactive` | Habilita prompts humanos de confirmacion o eleccion. | Nunca se activa por defecto. Debe tener alternativa no interactiva. |
+| `--review` | Abre o prepara revision humana antes de escrituras persistentes. | Debe usar `$VISUAL`, `$EDITOR` o dejar un artefacto revisable cuando no haya TTY. |
+| `--dry-run` | Previsualiza sin escribir ni ejecutar acciones irreversibles. | Debe ser seguro y no requerir credenciales salvo que el comando lo documente. |
+| `--print-prompt` | Imprime el prompt exacto sin ejecutar proveedor. | Debe evitar auth/provider execution. |
+| `--json` | Emite salida machine-readable. | Incompatible con `--interactive` y `--review`. |
+| `--no-color` | Desactiva color ANSI. | Debe respetarse en toda salida humana. |
+
+## Matriz de soporte
+
+| Comando | `--with-planner` | `--interactive` | `--review` | Notas |
+|---|---:|---:|---:|---|
+| `ai prepare-context` | si | si | si | Modo deterministico por defecto; planner opcional con contrato docs-only. |
+| `ai plan` | si | si | si | El planner ya es implicito; `--with-planner` se acepta por consistencia. |
+| `spec create` | si | si | si | Consume un plan tecnico aprobado del planner; no vuelve a ejecutar proveedor. Review previsualiza el paquete antes de escribir. |
+| `ai pr` | no | si | si | Review edita `pr.md`; interactive confirma `gh pr create`. |
+| `flow`, `next`, `graph` | no | no | no | Lectura/inspeccion; no deben exponer flags decorativas. |
+| `ai inspect`, `ai export`, `ai specs list`, `ai slices list`, `ai trace report` | no | no | no | Superficies read-only o machine-readable. |
+
+## Flujo recomendado para contexto de IA
+
+Modo deterministico:
+
+```bash
+npx create-quiver ai prepare-context --dry-run
+npx create-quiver ai prepare-context
+```
+
+Modo asistido por planner:
+
+```bash
+npx create-quiver ai prepare-context --with-planner --dry-run
+npx create-quiver ai prepare-context --with-planner --print-prompt
+npx create-quiver ai prepare-context --with-planner --review --interactive
+```
+
+El planner debe devolver una propuesta validable. Quiver solo acepta cambios en documentación/contexto permitida y rechaza rutas de producto, dependencias, build, runtime, lockfiles, salidas generadas, rutas absolutas y traversal.
+
+## Loaders y prompts
+
+Usar loaders solo cuando aportan claridad:
+
+```text
+Analizando estructura del proyecto...
+Leyendo contexto base...
+Preparando prompt para planner...
+Ejecutando agente...
+```
+
+Usar prompts interactivos cuando hay una decision humana real:
+
+```text
+? Aplicar 3 actualizaciones docs-only de contexto?
+? Crear spec "quiver-demo"?
+? Crear PR "Implementar dashboard"?
+```
+
+No usar prompts para informacion que ya se pueda expresar con flags.
+
+## Revision con editor
+
+Los comandos con `--review` deben:
+
+1. Crear o abrir un artefacto revisable.
+2. Respetar `$VISUAL` antes que `$EDITOR`.
+3. No usar shell interpolation para abrir editores.
+4. Bloquear escrituras si la revision se cancela.
+5. Revalidar la propuesta editada cuando el contenido tiene contrato estructurado.
+6. Reportar la ruta del artefacto si no se puede abrir un editor.
+
+## Testing minimo
+
+Cada comando que adopte estas reglas debe cubrir:
+
+- modo `--dry-run`;
+- salida sin TTY/CI;
+- `--json` limpio o rechazo temprano si corresponde;
+- `--interactive` aceptado y cancelado;
+- `--review` aceptado, cancelado y editado;
+- `--no-color`;
+- rechazo de flags no soportadas con mensaje accionable.
+
+## Checklist para nuevos comandos
+
+- [ ] El comando define si es lectura, escritura, proveedor, worktree, PR o validacion.
+- [ ] `--dry-run` existe si hay escrituras o efectos externos.
+- [ ] `--with-planner`, `--interactive` y `--review` solo se aceptan si agregan valor real.
+- [ ] La salida JSON no se mezcla con prompts, colores, loaders ni texto humano.
+- [ ] Los mensajes de error incluyen proximo paso seguro.
+- [ ] La documentacion publica y `README_FOR_AI.md` quedan sincronizados.

package/docs/COMMANDS.md.template

@@ -30,6 +30,7 @@ This document is the canonical command reference for the orchestration roadmap.
 | `npx create-quiver ai inspect` | Shows actionable lifecycle state for specs, slices, runs, agents, layout, and next commands | macOS, Linux, Windows | v0.13 | `npx create-quiver ai inspect` |
 | `npx create-quiver ai export --format json` | Emits machine-readable specs, slices, runs, agents, dependencies, blockers, and migration state | macOS, Linux, Windows | v0.13 | `npx create-quiver ai export --format json` |
 | `npx create-quiver ai export --format markdown` | Emits readable Markdown lifecycle state for PRs or docs | macOS, Linux, Windows | v0.13 | `npx create-quiver ai export --format markdown` |
+| `npx create-quiver ai active-slice reconcile --dry-run` | Reports active-slice state from supported local sources and previews preserve, close, replace, or blocked reconciliation decisions without writing files | macOS, Linux, Windows | next | `npx create-quiver ai active-slice reconcile --dry-run` |
 | `npx create-quiver ai specs list` | Lists specs with state, progress, slice counts, and paths | macOS, Linux, Windows | v0.13 | `npx create-quiver ai specs list` |
 | `npx create-quiver ai slices list` | Lists slices with state, progress, dependencies, and blockers | macOS, Linux, Windows | v0.13 | `npx create-quiver ai slices list --json` |
 | `npx create-quiver ai trace report` | Reports AI runs, execution waves, and migration guidance | macOS, Linux, Windows | v0.13 | `npx create-quiver ai trace report` |
@@ -50,7 +51,11 @@ This document is the canonical command reference for the orchestration roadmap.
 | `quiver:ai:trace` | Prints a trace report through the generated npm script | macOS, Linux, Windows | v0.13 | `npm run quiver:ai:trace` |
 | `quiver:ai:onboard` | Runs AI onboarding prompt through a supported local provider CLI | macOS, Linux, Windows | v0.10 | `npm run quiver:ai:onboard -- --dry-run` |
 | `quiver:ai:prepare-context` | Prepares docs-only AI context drafts with diff preview, assumptions, risks, contradictions, and snapshots before writes | macOS, Linux, Windows | v0.11 | `npm run quiver:ai:prepare-context -- --dry-run` |
+| `quiver:ai:prepare-context -- --with-planner --dry-run` | Previews a planner-generated docs-only context proposal without writing files | macOS, Linux, Windows | next | `npm run quiver:ai:prepare-context -- --with-planner --dry-run` |
+| `quiver:ai:prepare-context -- --with-planner --print-prompt` | Prints the exact planner context prompt without running provider CLIs | macOS, Linux, Windows | next | `npm run quiver:ai:prepare-context -- --with-planner --print-prompt` |
+| `quiver:ai:prepare-context -- --with-planner --review --interactive` | Runs planner-assisted context preparation, opens review, and asks before docs-only writes | macOS, Linux, Windows | next | `npm run quiver:ai:prepare-context -- --with-planner --review --interactive` |
 | `quiver:ai:plan` | Runs phase-gated AI planning for acceptance criteria, technical plan, or spec generation | macOS, Linux, Windows | v0.10 | `npm run quiver:ai:plan -- --phase acceptance --input requirements.md --dry-run` |
+| `quiver:ai:plan -- --review --interactive` | Lets a human edit and confirm planner drafts before saving them | macOS, Linux, Windows | next | `npm run quiver:ai:plan -- --phase acceptance --input requirements.md --review --interactive` |
 | `quiver:ai:revise` | Creates a new draft version from human feedback without approving or advancing the planner phase | macOS, Linux, Windows | v0.13 | `npm run quiver:ai:revise -- --phase acceptance --input feedback.md --dry-run` |
 | `quiver:ai:review-plan` | Reviews the technical-plan draft for production readiness before approval and spec generation | macOS, Linux, Windows | v0.11 | `npm run quiver:ai:review-plan -- --dry-run` |
 | `quiver:ai:approve` | Approves a concrete saved draft version for the next planner phase | macOS, Linux, Windows | v0.10 | `npm run quiver:ai:approve -- --phase acceptance --version 1` |
@@ -59,7 +64,9 @@ This document is the canonical command reference for the orchestration roadmap.
 | `quiver:ai:execute-plan` | Prints or executes dependency-safe waves of slices, with manual prompts or delegated worktrees | macOS, Linux, Windows | v0.10 | `npm run quiver:ai:execute-plan -- --dry-run --commit --mode delegated` |
 | `quiver:ai:doctor` | Runs GitHub PR preflight checks without opening a PR | macOS, Linux, Windows | v0.10 | `npm run quiver:ai:doctor -- --dry-run --ssh-host-alias github-work --identity-file ~/.ssh/github-work` |
 | `quiver:ai:pr` | Validates `gh`, reads `pr.md`, prints a PR plan, and creates a PR only with `--create` | macOS, Linux, Windows | v0.10 | `npm run quiver:ai:pr -- --dry-run --input specs/<spec>/pr.md --ssh-host-alias github-work --identity-file ~/.ssh/github-work` |
+| `quiver:ai:pr -- --review` | Opens `pr.md` for human review and rebuilds the PR plan from the edited body | macOS, Linux, Windows | next | `npm run quiver:ai:pr -- --review --dry-run --input specs/<spec>/pr.md` |
 | `quiver:spec:create` | Creates the real spec tree from the reviewed approved technical plan | macOS, Linux, Windows | v0.11 | `npm run quiver:spec:create -- --dry-run` |
+| `quiver:spec:create -- --review --interactive` | Reviews the generated spec package preview and asks before writing files | macOS, Linux, Windows | next | `npm run quiver:spec:create -- --review --interactive` |
 | `quiver:spec:start` | Creates or reuses the dedicated worktree for one spec | macOS, Linux, Windows | v0.10 | `npm run quiver:spec:start -- specs/<spec>` |
 | `quiver:spec:status` | Shows spec worktree, branch, `slice-00`, and pending slices | macOS, Linux, Windows | v0.10 | `npm run quiver:spec:status -- specs/<spec>` |
 | `quiver:spec:validate` | Validates spec docs, slices, briefs, evidence, status, dependencies, and safe paths | macOS, Linux, Windows | v0.13 | `npm run quiver:spec:validate -- specs/<spec>` |
@@ -90,8 +97,12 @@ This document is the canonical command reference for the orchestration roadmap.
 | `--provider <codex\|claude\|gemini>` | `ai onboard`, `ai plan`, `ai revise`, `ai review-plan`, `ai execute-slice`, `ai execute-plan` | Select the local AI CLI adapter |
 | `--model <label>` | `ai agent set` | Store a free-form model label in an agent profile; Quiver does not verify model availability |
 | `--label <label>` | `ai agent set` | Store a display label for the profile |
-| `--dry-run` | `ai agent set` | Preview profile writes without creating or updating `.quiver/agents/profiles.json` |
-| `--print-prompt` | `ai onboard`, `ai plan`, `ai revise`, `ai review-plan` | Print the exact provider prompt and exit without executing provider CLIs or requiring provider auth |
+| `--dry-run` | init, analyze, migrate, prepare, spec, demo, AI, PR, worktree, and repair commands that support preview | Preview planned actions without writes, provider execution, PR creation, or irreversible changes |
+| `--with-planner` | `ai prepare-context`, `ai plan`, `spec create` | Enable planner-assisted behavior only on commands that explicitly support it |
+| `--interactive` | `ai prepare-context`, `ai plan`, `spec create`, `ai pr` | Enable human prompts for confirmation or choices |
+| `--review` | `ai prepare-context`, `ai plan`, `spec create`, `ai pr` | Open or prepare human review before persistent writes |
+| `--no-color` | all human-output commands | Disable ANSI color in human output |
+| `--print-prompt` | `ai onboard`, `ai prepare-context`, `ai plan`, `ai revise`, `ai review-plan` | Print the exact provider prompt and exit without executing provider CLIs or requiring provider auth |
 | `--role <planner\|executor\|reviewer\|doctor>` | `ai onboard`, `ai plan`, `ai revise`, `ai execute-slice`, `ai execute-plan` | Select an AI role; execution requires executor |
 | `--context <full\|planning\|slice\|minimal>` | `ai onboard`, `ai plan`, `ai revise`, `ai review-plan`, `ai execute-slice`, `ai execute-plan` | Select a token-budgeted context pack |
 | `--phase <acceptance\|technical-plan\|spec>` | `ai plan`, `ai revise`, `ai approve` | Select the gated planner phase; `ai revise` and `ai approve` do not support `spec` |
@@ -118,14 +129,18 @@ This document is the canonical command reference for the orchestration roadmap.
 - `check-slice` validates `depends_on` targets and requires `parallel_safe_reason` when `parallel_safe` is `never`.
 - `check-handoff` validates both exceptional `HANDOFF.md` transfers and current slice-local `EXECUTION_BRIEF.md` / `CLOSURE_BRIEF.md` contracts.
 - `quiver:ai:onboard`, `quiver:ai:plan`, `quiver:ai:revise`, `quiver:ai:review-plan`, and `quiver:ai:execute-slice` support `codex`, `claude`, and `gemini` through local CLIs. Use `--dry-run` first to inspect the invocation without requiring provider auth, or `--print-prompt` to print the exact planner/reviewer prompt without executing a provider.
-- `quiver:ai:prepare-context -- --dry-run` previews docs-only context drafts, diff snippets, assumptions, risks, contradictions, and omitted paths. Write mode stores snapshots under `.quiver/runs/<run-id>/snapshots/` and preserves human-authored content by appending or refreshing a Quiver-managed block.
+- `quiver:ai:prepare-context -- --dry-run` previews deterministic docs-only context drafts, diff snippets, assumptions, risks, contradictions, and omitted paths. Write mode stores snapshots under `.quiver/runs/<run-id>/snapshots/` and preserves human-authored content by appending or refreshing a Quiver-managed block.
+- `quiver:ai:prepare-context -- --with-planner` invokes a planner provider and only accepts a validated docs-only proposal. Use `--print-prompt` for external planners, `--review` to inspect the proposal before writing, and `--interactive` to require confirmation.
+- UX flags are centralized: `--with-planner`, `--interactive`, and `--review` are accepted only by commands where they add real behavior. Read-only inspection commands reject them with an actionable next step. `spec create --with-planner` consumes an already approved planner output and does not call a provider again. `--json` is incompatible with `--interactive` and `--review`.
+- Quiver human output uses the palette `#86C8F2`, `#6BADEB`, `#7F9EE8`, `#9B82E6`, and `#D56AB0`; respect `--no-color`, `NO_COLOR`, CI, and no-TTY environments.
 - `quiver:flow` reports the detected package manager and the matching generated project script, for example `npm run quiver:flow`, `pnpm run quiver:flow`, `yarn run quiver:flow`, or `bun run quiver:flow`.
 - `quiver:ai:agent -- set ... --dry-run` previews provider/model profile changes without writing `.quiver/agents/profiles.json`.
 - `quiver:ai:agent` stores provider/model labels under `.quiver/agents/profiles.json`; credentials stay in the provider CLI or OS credential store.
 - `quiver:ai:inspect`, `quiver:ai:specs`, `quiver:ai:slices`, and `quiver:ai:trace` are read-only inspection surfaces for humans and agents.
 - `quiver:ai:export -- --format json` is the dashboard/agent-friendly state contract; `--format markdown` is the PR/docs-friendly version.
-- Planner drafts are versioned under `.quiver/approvals/<phase>/drafts/`; use `quiver:ai:review-plan -- --dry-run` before approving a technical-plan draft, then `quiver:ai:approve -- --phase technical-plan --version 1` to approve the reviewed version.
+- Planner drafts are versioned under `.quiver/approvals/<phase>/drafts/`; use `quiver:ai:review-plan -- --dry-run` before approving a technical-plan draft, then `quiver:ai:approve -- --phase technical-plan --version 1` to approve the reviewed version. Plan reviews store structured recommendations: `approve`, `approve-with-risk`, or `revise`.
 - `quiver:ai:prompt-slice -- --dry-run` prints a paste-ready manual executor prompt and does not call a provider.
+- For commands pasted into another AI agent, prefer a non-interactive pinned form such as `npx --yes create-quiver@<version> ai prompt-slice --slice specs/<spec>/slices/<slice>/slice.json --dry-run`.
 - `quiver:evidence -- run -- <command>` preserves the wrapped command exit code. Redaction is best effort; avoid commands that intentionally print secrets.
 - `demo create spec-viewer` is optional and static; it must stay outside default `init`.
 - `quiver:spec:start -- --dry-run specs/<spec>` previews the spec worktree path and branch without creating a worktree.

package/docs/GITFLOW_PR_GUIDE.md

@@ -0,0 +1,70 @@
+# Git and PR Guide
+
+**Version:** 2.0
+**Last updated:** 2026-05-26
+
+## Purpose
+
+This guide explains how to open and review spec PRs without breaking the canonical workflow.
+
+## Core Rule
+
+- One slice = one commit
+- One spec = one PR
+- One spec should be worked from one dedicated worktree/branch.
+- Slice numbers reset per spec. `slice-01` is the first slice in each spec.
+- Do not commit directly to `develop`
+- Open and merge the documentation PR before the first slice starts execution
+- Do not open the spec PR before the documentation PR is merged
+
+## AI PR Preflight
+
+Before asking an AI agent to prepare PR work, validate the local setup:
+
+```bash
+npm run quiver:ai:pr -- --dry-run --ssh-host-alias github-work --identity-file ~/.ssh/github-work
+```
+
+Use the SSH host alias from your Git remote separately from the key path. Quiver validates `gh`, `gh auth status`, the remote, branch/worktree state, this guide, and the identity file. It does not install `gh`, edit SSH config, or create a PR in dry-run mode.
+
+## Review Guidance
+
+- Start with `git diff` and the slice scope before opening full files.
+- Use the diff to confirm what changed, then open full files only for gaps, regressions, or unclear context.
+- For debugging reviews, inspect the first relevant error, stacktrace, or failing command before reading large logs.
+- Keep review notes anchored to the changed lines and the slice acceptance criteria.
+
+## Required PR Headings
+
+All spec PR notes must use:
+
+- `## Title`
+- `## Summary`
+- `## Scope`
+- `## Files`
+- `## How to Test (DETAILED - REQUIRED)`
+- `## Evidence`
+- `## Rollback`
+- `## Risks / Notes`
+
+Inside `How to Test`, use:
+
+- `### Required Environment`
+- `### Worktree Access`
+- `### Run the Project`
+- `### Use Cases`
+- `### Technical Verification`
+
+## Branch Strategy
+
+| Type | Prefix | Source | Target |
+|------|--------|--------|--------|
+| feature | `feature/` | `develop` | `develop` |
+| bugfix | `bugfix/` | `develop` | `develop` |
+| hotfix | `hotfix/` | `main` | `main` |
+
+## Anti-Patterns
+
+- Pushing directly to `develop`
+- Reusing the same branch for multiple specs
+- Writing PR bodies outside `pr.md`

package/docs/TROUBLESHOOTING.md.template

@@ -147,6 +147,35 @@ Use this guide when a first-run bootstrap or gate check fails. The recovery path
 3. Use `--provider codex`, `--provider claude`, or `--provider gemini` explicitly if your default is unclear.
 4. Re-run the command from a clean worktree when using `ai execute-slice`.
 
+## Plan Review Blocks Approval
+
+### Symptom
+
+- `ai approve --phase technical-plan` says the plan review blocks approval
+- `ai approvals` shows `Approval recommendation: revise`
+
+### Recovery
+
+1. Read `.quiver/approvals/plan-review/review.md` and the `required_fixes` in `.quiver/approvals/plan-review/meta.json`.
+2. Create a revised technical-plan draft with `npx create-quiver ai revise --phase technical-plan --input <feedback.md> --dry-run`.
+3. Run `npx create-quiver ai review-plan --dry-run`, then `npx create-quiver ai review-plan` after inspecting the prompt.
+4. Approve only when the review recommendation is `approve` or `approve-with-risk`.
+
+## Active Slice State Conflict
+
+### Symptom
+
+- `ai inspect` reports an active-slice blocker
+- `docs/ai/ACTIVE_SLICE.md` and `ACTIVE_SLICES.md` point to different slices
+- The current active slice was already completed but local active-state files still exist
+
+### Recovery
+
+1. Run `npx create-quiver ai active-slice reconcile --dry-run`.
+2. If the decision is `preserve`, continue with the suggested next command.
+3. If the decision is `close` or `replace`, review the planned file changes before changing local active-state files.
+4. If the decision is `blocked`, fix the missing, ambiguous, or conflicting slice reference before assigning more executor work.
+
 ## GitHub PR Preflight Failure
 
 ### Symptom

package/docs/WORKFLOW.md.template

@@ -37,8 +37,8 @@ Use maps, metadata, diffs, and summaries first. Open full files only when the sm
 3. Save reusable planner/executor provider choices with `ai agent set` when the team has preferred local AI CLIs.
 4. Use `ai plan --phase acceptance` to draft criteria, then save the approved version with `ai approve --phase acceptance`.
 5. Use `ai plan --phase technical-plan` to draft the plan.
-6. Use `ai review-plan` to review the technical-plan draft for production readiness without changing product code.
-7. Save the reviewed plan version with `ai approve --phase technical-plan --version <n>`.
+6. Use `ai review-plan` to review the technical-plan draft for production readiness without changing product code. Treat `approve` and `approve-with-risk` as approvable states; treat `revise` or required fixes as blockers.
+7. Save the reviewed plan version with `ai approve --phase technical-plan --version <n>` only after the review recommendation is approvable.
 8. Use `spec create` to generate the spec, mandatory `slice-00`, implementation slices, handoffs, execution plan, and `pr.md`.
 9. Open and merge the documentation PR or commit that establishes `slice-00` before running implementation slices.
 10. Read the AI context pack, support matrix, and troubleshooting guide before the first slice if the environment is new or uncertain.
@@ -50,21 +50,22 @@ Use maps, metadata, diffs, and summaries first. Open full files only when the sm
 
 1. Create or reuse the spec worktree with `npx create-quiver spec start specs/<spec-slug>` or `npm run quiver:spec:start -- specs/<spec-slug>`. Use `--dry-run` first when you want to inspect the planned branch/path without changing Git state.
 2. Inspect lifecycle state with `npx create-quiver ai inspect`, or export it with `npx create-quiver ai export --format json` for dashboards/agents and `--format markdown` for PRs/docs.
-3. Inspect manual prompts with `npx create-quiver ai execute-plan --dry-run --commit --mode manual` or delegated waves with `npm run quiver:ai:execute-plan -- --dry-run --commit --mode delegated`.
-4. Print a minimal manual executor prompt with `npx create-quiver ai prompt-slice --slice <slice.json> --dry-run` when assigning the slice to another agent.
-5. Bootstrap a single slice with `npx create-quiver start-slice <slice.json>` or `npm run quiver:start-slice -- <slice.json>` when manual execution is preferred.
+3. If active-slice state looks stale or conflicting, run `npx create-quiver ai active-slice reconcile --dry-run` before assigning more execution work.
+4. Inspect manual prompts with `npx create-quiver ai execute-plan --dry-run --commit --mode manual` or delegated waves with `npm run quiver:ai:execute-plan -- --dry-run --commit --mode delegated`.
+5. Print a minimal manual executor prompt with `npx create-quiver ai prompt-slice --slice <slice.json> --dry-run` when assigning the slice to another agent. For commands pasted into another AI agent, prefer `npx --yes create-quiver@<version> ai prompt-slice --slice <slice.json> --dry-run`.
+6. Bootstrap a single slice with `npx create-quiver start-slice <slice.json>` or `npm run quiver:start-slice -- <slice.json>` when manual execution is preferred.
    - The bootstrap step should work with canonical paths and a local base branch when `origin` is absent.
    - Draft slices require `--allow-draft`; otherwise `npx create-quiver start-slice` exits before execution.
    - Legacy Bash wrappers remain available for compatibility, but generated projects should prefer the Node CLI and `quiver:*` npm scripts.
    - `start-slice` generates `docs/ai/ACTIVE_SLICE.md` and `WORKTREE_CONTEXT.md`; use the active slice brief as the source of truth for execution.
-6. Implement only what the slice declares.
-7. Make one commit for that slice, or let `ai execute-slice --commit` / `ai execute-plan --execute --commit --mode delegated` create it after provider, branch/worktree, scope, and validation pass.
+7. Implement only what the slice declares.
+8. Make one commit for that slice, or let `ai execute-slice --commit` / `ai execute-plan --execute --commit --mode delegated` create it after provider, branch/worktree, scope, and validation pass.
    - `ai execute-slice` updates `CLOSURE_BRIEF.md`, `EVIDENCE_REPORT.md`, `COMMAND_LOG.md`, `STATUS.md`, and `slice.json` only after the provider changes in-scope files and validation passes.
-8. Validate with `npx create-quiver check-slice <slice.json>` or `npm run quiver:check-slice -- <slice.json>`.
-9. Write evidence. Prefer `npx create-quiver evidence run -- <command>` when you need a compact local Markdown record of validation output.
-10. Repeat for the next slice until the spec is complete.
-11. Open one PR for the spec. Use `npx create-quiver ai pr --dry-run --input specs/<spec-slug>/pr.md --ssh-host-alias <alias> ...` first, then add `--create` only after review. Quiver blocks PR creation while slices in that spec remain open.
-12. After the PR is merged and the spec worktree is clean, close it with `npx create-quiver spec close specs/<spec-slug>`.
+9. Validate with `npx create-quiver check-slice <slice.json>` or `npm run quiver:check-slice -- <slice.json>`.
+10. Write evidence. Prefer `npx create-quiver evidence run -- <command>` when you need a compact local Markdown record of validation output.
+11. Repeat for the next slice until the spec is complete.
+12. Open one PR for the spec. Use `npx create-quiver ai pr --dry-run --input specs/<spec-slug>/pr.md --ssh-host-alias <alias> ...` first, then add `--create` only after review. Quiver blocks PR creation while slices in that spec remain open.
+13. After the PR is merged and the spec worktree is clean, close it with `npx create-quiver spec close specs/<spec-slug>`.
 
 ## Support Contract