create-quiver 0.12.1 → 0.14.0

package/CHANGELOG.md

@@ -4,6 +4,33 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.14.0] - 2026-05-25
+
+### Added
+
+- v28 Pixel Quiver feedback reconciliation under `specs/quiver-v28-pixel-quiver-feedback-reconciliation/`.
+- `ai active-slice status|reconcile` for dry-run-first active-slice state inspection across `docs/ai/ACTIVE_SLICE.md` and `ACTIVE_SLICES.md`.
+- Structured `ai review-plan` closure metadata with `approve`, `approve-with-risk`, and `revise` recommendations.
+
+### Changed
+
+- `ai inspect` now prefers existing-spec recovery commands (`spec validate`, `next`, `ai prompt-slice`) when a lifecycle run still points to stale `spec create` guidance.
+- Agent-facing docs/help now include non-interactive `npx --yes create-quiver@<version>` examples.
+- GitHub PR preflight guidance now gives clearer macOS, Linux, Windows PowerShell, Git Bash, and WSL recovery copy for `gh` and SSH aliases.
+
+### Fixed
+
+- Technical-plan approval now blocks reviews with required fixes or a `revise` recommendation.
+- `spec validate`, `spec status`, and `spec start --dry-run` were hardened for execution metadata, stale worktree paths, dirty checkout recovery, and scope diagnostics.
+
+## [0.13.0] - 2026-05-25
+
+### Added
+
+- Implemented v27 reliability and AI workflow hardening under `specs/quiver-v27-reliability-ai-workflow-hardening/`, based on Pixel Quiver dogfooding findings.
+- Shared project-state resolver, canonical statuses, schema v2 lifecycle exports, structured approved-plan spec creation, AI artifact cleanup/redaction, token compaction, worktree locks/recovery, validation gates, context freshness diagnostics, cross-platform DX guidance, and release-readiness fixture coverage.
+- Final v27 package/tarball smoke coverage for packaged CLI help, `flow`, `ai agent set --dry-run`, doctor fixtures, guided workflow, and full test suite validation.
+
 ## [0.12.1] - 2026-05-23
 
 ### Added

package/README.md

@@ -16,6 +16,7 @@ npx create-quiver flow
 npx create-quiver prepare --dry-run
 npx create-quiver analyze
 npx create-quiver doctor
+npx create-quiver ai agent set planner --provider codex --model "planner-model" --dry-run
 npx create-quiver ai agent set planner --provider codex --model "planner-model"
 npx create-quiver ai agent set executor --provider codex --model "executor-model"
 npx create-quiver ai prepare-context --dry-run
@@ -61,12 +62,13 @@ Reglas prácticas por sistema:
 - Windows con PowerShell: usá los mismos comandos `npx`, `npm` y `node`, pero adaptá rutas a formato Windows, por ejemplo `C:\Users\<usuario>\ssh\github-work`.
 - Windows con Git Bash o WSL: podés usar rutas tipo Unix, por ejemplo `~/.ssh/github-work`.
 - Los wrappers Bash bajo `tools/scripts/` son compatibilidad legacy u opcional. Para trabajo nuevo, preferí el CLI Node y los scripts `quiver:*`.
+- Si una ruta tiene espacios, mantenela entre comillas. En los preflights de GitHub, Quiver imprime ejemplos seguros para macOS/Linux, Windows PowerShell, Git Bash y WSL.
 
 Cuando uses GitHub o PRs:
 
 - `--ssh-host-alias` recibe el alias del host en tu configuración SSH, por ejemplo `github-work` o `github-personal`.
 - `--identity-file` recibe la ruta al archivo de clave, que cambia según el sistema operativo.
-- `gh` debe estar instalado y autenticado; Quiver lo valida con `ai doctor` o `ai pr --dry-run`.
+- `gh` debe estar instalado y autenticado; Quiver lo valida con `ai doctor` o `ai pr --dry-run`, y cuando falla indica cuenta, permisos/scopes, alias SSH y próximo comando seguro.
 
 ### Desarrollar este repositorio
 
@@ -115,6 +117,12 @@ npx create-quiver ai execute-plan --dry-run --commit --mode delegated
 npx create-quiver ai pr --dry-run --input specs/<project-slug>/pr.md --ssh-host-alias github-work --identity-file ~/.ssh/github-work
 ```
 
+Cuando pegues comandos en un agente externo y quieras evitar prompts interactivos de `npx`, usá la forma versionada y no interactiva:
+
+```bash
+npx --yes create-quiver@<version> ai prompt-slice --slice specs/<project-slug>/slices/slice-01/slice.json --dry-run
+```
+
 Regla práctica: el planner no modifica código de producto; el executor solo trabaja sobre un slice aprobado y dentro de los archivos declarados en `slice.json`.
 
 ## 🛠️ Empezar a usar Quiver según tu caso
@@ -317,7 +325,8 @@ El paquete también publica el alias binario `quiver`, que apunta al mismo CLI.
 | `npx create-quiver --help` | Lista todos los comandos públicos con descripción, opciones principales y ejemplos recomendados. |
 | `npx create-quiver help` | Alias legible de la ayuda completa. |
 | `quiver --help` | Muestra la misma ayuda cuando Quiver ya está instalado localmente. |
-| `npx create-quiver flow` | Muestra el estado inicial del flujo guiado y el próximo comando seguro sin escribir estado ni llamar providers. |
+| `npx create-quiver flow` | Muestra el estado inicial del flujo guiado, la fuente/frescura del contexto, el package manager detectado, el script `quiver:flow` correcto y el próximo comando seguro sin escribir estado ni llamar providers. |
+| `npx create-quiver ai agent set <role> --provider <provider> --model <label> --dry-run` | Previsualiza el perfil que se guardaría sin escribir `.quiver/agents/profiles.json`. |
 | `npx create-quiver ai agent set <role> --provider <provider> --model <label>` | Guarda perfiles reutilizables para planner, executor, reviewer o doctor sin guardar secretos. |
 | `npx create-quiver ai agent list` | Lista los perfiles configurados. |
 | `npx create-quiver ai agent show <role>` | Muestra un perfil específico. |
@@ -327,6 +336,7 @@ El paquete también publica el alias binario `quiver`, que apunta al mismo CLI.
 | `npx create-quiver ai inspect` | Resume specs, slices, runs, agentes, layout y próximos comandos accionables. |
 | `npx create-quiver ai export --format json` | Exporta estado de specs, slices, runs, agentes, dependencias y migración para dashboards o agentes. |
 | `npx create-quiver ai export --format markdown` | Exporta el mismo estado en Markdown legible para PRs o docs. |
+| `npx create-quiver ai active-slice reconcile --dry-run` | Inspecciona y reconcilia en modo lectura el estado local del slice activo entre `docs/ai/ACTIVE_SLICE.md` y `ACTIVE_SLICES.md`. |
 | `npx create-quiver ai specs list` | Lista specs con estado, progreso y cantidad de slices. |
 | `npx create-quiver ai slices list` | Lista slices con estado, progreso, dependencias y bloqueos. |
 | `npx create-quiver ai trace report` | Muestra runs, olas de ejecución y estado de migración en formato humano. |
@@ -336,7 +346,8 @@ El paquete también publica el alias binario `quiver`, que apunta al mismo CLI.
 | `npx create-quiver init --full` | Crea el layout amplio de compatibilidad. |
 | `npx create-quiver init --legacy-scripts` | Agrega wrappers Bash legacy bajo `tools/scripts/`. |
 | `npx create-quiver init --include-templates` | Exporta templates empaquetados bajo `.quiver/templates/`. |
-| `npx create-quiver analyze` | Genera `.quiver/scans/PROJECT_SCAN.json` y `docs/PROJECT_MAP.md`. |
+| `npx create-quiver analyze --dry-run` | Previsualiza el scan, el mapa de proyecto y el refresh de contexto sin escribir archivos. |
+| `npx create-quiver analyze` | Genera `.quiver/scans/PROJECT_SCAN.json`, `docs/PROJECT_MAP.md` y refresca `docs/AI_CONTEXT.md`. |
 | `npx create-quiver doctor` | Valida que el contrato de Quiver esté completo. |
 | `npx create-quiver doctor --fix --dry-run` | Muestra reparaciones seguras sin escribir archivos. |
 | `npx create-quiver doctor --fix` | Aplica reparaciones no destructivas e idempotentes. |
@@ -354,6 +365,7 @@ El paquete también publica el alias binario `quiver`, que apunta al mismo CLI.
 | `npx create-quiver spec create` | Crea la spec real desde el plan técnico revisado y aprobado. |
 | `npx create-quiver spec start <spec-dir>` | Crea o reutiliza el worktree dedicado de una spec. Usá `--dry-run` para ver qué worktree se crearía sin tocar Git. |
 | `npx create-quiver spec status <spec-dir>` | Muestra branch, path, `slice-00` y slices pendientes. |
+| `npx create-quiver spec validate <spec-dir>` | Valida documentos de spec, slices, briefs, evidencia, estado, dependencias y rutas seguras. |
 | `npx create-quiver spec close <spec-dir>` | Cierra un worktree de spec ya mergeado y limpio; en modo normal también intenta traer los cambios del merge al checkout principal. |
 | `npx create-quiver start-slice <slice.json>` | Prepara worktree y contexto para ejecutar un slice. |
 | `npx create-quiver check-slice <slice.json>` | Valida readiness del slice. |
@@ -374,6 +386,7 @@ El paquete también publica el alias binario `quiver`, que apunta al mismo CLI.
 npx create-quiver ai prepare-context --dry-run
 npx create-quiver ai onboard --dry-run
 npx create-quiver ai onboard --print-prompt
+npx create-quiver ai agent set planner --provider codex --model "planner-model" --dry-run
 npx create-quiver ai agent set planner --provider codex --model "planner-model"
 npx create-quiver ai agent set executor --provider codex --model "executor-model"
 npx create-quiver ai agent set doctor --provider codex --model "diagnostic-model"
@@ -404,7 +417,7 @@ Orden recomendado:
 2. `ai onboard`: el planner entiende el repo y el workflow.
 3. `ai plan --phase acceptance`: convierte requerimientos en criterios de aceptación.
 4. `ai plan --phase technical-plan`: propone el plan técnico.
-5. `ai review-plan`: revisa el plan como si fuera a producción, sin tocar código ni cuestionar el alcance aprobado.
+5. `ai review-plan`: revisa el plan como si fuera a producción, sin tocar código ni cuestionar el alcance aprobado. La salida guarda metadata con recomendación `approve`, `approve-with-risk` o `revise`.
 6. `ai approve`: guarda criterios o la versión revisada del plan técnico.
 7. `spec create`: genera spec, slices, handoffs y PR body desde el plan revisado y aprobado.
 8. `spec start`: prepara un worktree por spec.
@@ -462,7 +475,7 @@ Notas reales del estado actual:
 
 | Script | Uso |
 |---|---|
-| `npm run quiver:analyze` | Ejecuta `npx create-quiver analyze`. |
+| `npm run quiver:analyze` | Ejecuta `npx create-quiver analyze`; usalo con `-- --dry-run` para previsualizar sin escribir. |
 | `npm run quiver:flow` | Ejecuta `npx create-quiver flow`. |
 | `npm run quiver:plan` | Ejecuta `npx create-quiver plan`. |
 | `npm run quiver:prepare` | Ejecuta preparación guiada y diagnósticos. |
@@ -489,6 +502,7 @@ Notas reales del estado actual:
 | `npm run quiver:spec:create` | Ejecuta `npx create-quiver spec create`. |
 | `npm run quiver:spec:start` | Ejecuta `npx create-quiver spec start`. |
 | `npm run quiver:spec:status` | Ejecuta `npx create-quiver spec status`. |
+| `npm run quiver:spec:validate` | Ejecuta `npx create-quiver spec validate`. |
 | `npm run quiver:spec:close` | Ejecuta `npx create-quiver spec close`. |
 | `npm run package:quiver` | Empaqueta y valida el tarball npm. |
 | `npm run smoke:create-quiver` | Smoke del instalador `create-quiver`. |
@@ -555,9 +569,10 @@ Checklist de release:
 2. `npm run smoke:create-quiver`
 3. `npm run smoke:doctor-fixtures`
 4. `npm run smoke:guided-workflow`
-4. `npm run smoke:tiered-pack`
-5. `npm pack --dry-run`
-6. Confirmar que el PR esta aprobado antes de publicar.
+5. `npm run smoke:tiered-pack`
+6. `npm run package:quiver`
+7. `npm pack --dry-run`
+8. Confirmar que el PR esta aprobado antes de publicar.
 
 ## 📚 Documentación útil
 
@@ -571,7 +586,7 @@ Checklist de release:
 
 ## Información confirmada y pendiente
 
-- `package.json` está en `0.10.0` y `CHANGELOG.md` reconoce `0.10.0`.
+- `package.json` está en `0.14.0` y `CHANGELOG.md` reconoce `0.14.0`.
 - `package.json` no declara `engines`; la versión mínima real de Node queda pendiente. La CI usa Node 22.
 - Si aparece alguna referencia vieja a `0.9.0`, hay que actualizarla al contrato actual antes de seguir.
 - Los scripts legacy de `package.json` que apuntan a `tools/scripts/*` deben confirmarse para este repo fuente o separarse de los scripts pensados para proyectos generados con `--legacy-scripts` o `--full`.

package/README_FOR_AI.md

@@ -16,18 +16,26 @@ Use `npx create-quiver demo create spec-viewer --dry-run` to inspect the optiona
 The v20, v21, v22, and v23 specs are completed. `specs/quiver-v23-guided-flow-productization/` productized the manual planner/executor prompt workflow into guided Quiver commands, profiles, compact prompts, safe approvals, executor prompts, delegated execution modes, and release readiness evidence.
 The v24 spec is implemented under `specs/quiver-v24-dx-onboarding-hardening/`; it captures DX hardening found while dogfooding Quiver with Quiver Spec Viewer, including init hygiene, CLI ambiguity, local slice validation, analyzer quality, AI context preparation, evidence capture, and demo scaffolding. Do not claim a package release until npm publication actually happens.
 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/`; it prepares `create-quiver@0.12.1` 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. Do not claim `0.12.1` is published until npm publication actually happens after PR merge.
+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.
 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, 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.
+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 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.
 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`.
@@ -64,7 +72,7 @@ Prefer maps, metadata, diffs, and summaries over full file reads when they are e
 - The normal workflow runs from the project root without `--dir`; use `--dir` only when targeting another directory explicitly.
 - The cross-platform contract targets native macOS, Linux, and Windows users through the Node CLI (`npx create-quiver ...`) and generated `quiver:*` npm scripts. Bash wrappers are legacy or optional compatibility, not the primary path. Keep root README examples clear about adapting SSH identity paths on Windows PowerShell, Git Bash, WSL, macOS, and Linux.
 - The support contract lives in `docs/SUPPORT_MATRIX.md` and `docs/TROUBLESHOOTING.md`.
-- Generated project npm scripts should prefer `quiver:*` names such as `quiver:analyze`, `quiver:flow`, `quiver:plan`, `quiver:graph`, `quiver:next`, `quiver:doctor`, `quiver:evidence`, `quiver:ai:agent`, `quiver:ai:inspect`, `quiver:ai:export`, `quiver:ai:specs`, `quiver:ai:slices`, `quiver:ai:trace`, `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:spec:create`, `quiver:spec:start`, `quiver:spec:status`, `quiver:spec:close`, `quiver:start-slice`, `quiver:check-slice`, and `quiver:check-pr`.
+- Generated project npm scripts should prefer `quiver:*` names such as `quiver:analyze`, `quiver:flow`, `quiver:plan`, `quiver:graph`, `quiver:next`, `quiver:doctor`, `quiver:evidence`, `quiver:ai:agent`, `quiver:ai:inspect`, `quiver:ai:export`, `quiver:ai:specs`, `quiver:ai:slices`, `quiver:ai:trace`, `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:spec:create`, `quiver:spec:start`, `quiver:spec:status`, `quiver:spec:validate`, `quiver:spec:close`, `quiver:start-slice`, `quiver:check-slice`, and `quiver:check-pr`.
 - Optional demos are created with `npx create-quiver demo create spec-viewer`; do not add demo output to the package or default init flow.
 - `quiver:graph` defaults to the tree view; choose `--format mermaid` or `--format dot` when you need exportable graph artifacts.
 - `quiver:next` prints the next ready slice and can auto-start it behind a confirmation prompt.
@@ -135,13 +143,13 @@ 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` if `docs/PROJECT_MAP.md` or `.quiver/scans/PROJECT_SCAN.json` is missing or stale
+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. Save reusable provider choices with `npx create-quiver ai agent set planner --provider <provider> --model "<label>"`, `npx create-quiver ai agent set executor --provider <provider> --model "<label>"`, and `npx create-quiver ai agent set doctor --provider <provider> --model "<label>"`
+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`
@@ -157,7 +165,8 @@ After initialization, the user should:
 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 slice and the final PR with the workflow gates
+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
 
 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

@@ -65,10 +65,21 @@
 - Published package `0.12.0`.
 - **v25** — AI-first lifecycle orchestrator: 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.
 
-## v0.12.1 — Smoke Hardening Hotfix (release-ready, pending publication)
+## v0.12.1 — Smoke Hardening Hotfix (shipped 2026-05-24)
 
+- Published package `0.12.1`.
 - **v26** — `0.12.1` smoke hardening from clean npm package validation: CLI help/version output, generated doc links, AI approval/review guidance, local validation, slice brief validation, demo scaffold readiness, scoped plan/graph performance, and release smoke coverage.
 
+## v0.13 — Reliability and AI Workflow Hardening (shipped 2026-05-25)
+
+- 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/`.
+
 ## Post-Checkpoint Plan (do not execute before validating v14)
 
 > This section now records the follow-up line from the v14-era plan.
@@ -83,7 +94,9 @@
 - **v23 — Guided Flow Productization** (completed): AI-first flow command, agent profiles, compact onboarding/planning prompts, production plan review, explicit `spec create`, manual executor prompts, delegated worktree execution, and release readiness live in `specs/quiver-v23-guided-flow-productization/`.
 - **v24 — DX Onboarding Hardening** (shipped in `0.11.0`): real-world dogfooding fixes for init/templates, CLI routing, doctor/prepare, local validation, analyzer, AI context preparation, evidence, and demos live in `specs/quiver-v24-dx-onboarding-hardening/`.
 - **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** (release-ready, pending publication): 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/`.
+- **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/`.
 
 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/docs/COMMANDS.md.template

@@ -15,8 +15,9 @@ This document is the canonical command reference for the orchestration roadmap.
 | `npx create-quiver --help` | Lists all public commands with descriptions, key options, and recommended examples | macOS, Linux, Windows | current | `npx create-quiver --help` |
 | `npx create-quiver help` | Readable alias for the complete CLI help | macOS, Linux, Windows | current | `npx create-quiver help` |
 | `quiver --help` | Shows the same help when Quiver is installed locally as a project dependency | macOS, Linux, Windows | current | `quiver --help` |
-| `npx create-quiver flow` | Shows the read-only guided flow entrypoint and next safe command | macOS, Linux, Windows | v0.11 | `npx create-quiver flow` |
-| `quiver:analyze` | Writes raw analyzer data to `.quiver/scans/PROJECT_SCAN.json` and the visible project map to `docs/PROJECT_MAP.md` | macOS, Linux, Windows | v0.8 | `npm run quiver:analyze` |
+| `npx create-quiver flow` | Shows the read-only guided flow entrypoint, context source/freshness, package-manager-aware script guidance, and next safe command | macOS, Linux, Windows | v0.11 | `npx create-quiver flow` |
+| `npx create-quiver analyze --dry-run` | Previews scan, project-map, and AI context writes without creating files | macOS, Linux, Windows | v0.13 | `npx create-quiver analyze --dry-run` |
+| `quiver:analyze` | Writes raw analyzer data to `.quiver/scans/PROJECT_SCAN.json`, the visible project map to `docs/PROJECT_MAP.md`, and refreshed AI context | macOS, Linux, Windows | v0.8 | `npm run quiver:analyze` |
 | `quiver:flow` | Runs the guided flow entrypoint through the generated npm script | macOS, Linux, Windows | v0.11 | `npm run quiver:flow` |
 | `quiver:prepare` | Runs guided setup diagnostics and context preparation | macOS, Linux, Windows | v0.10 | `npm run quiver:prepare -- --dry-run --provider codex` |
 | `quiver:doctor` | Validates the Quiver contract and reports layout or migration guidance | macOS, Linux, Windows | v0.8 | `npm run quiver:doctor` |
@@ -29,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` |
@@ -40,6 +42,7 @@ This document is the canonical command reference for the orchestration roadmap.
 | `quiver:plan -- --include-completed` | Shows completed slices for audit/demo history | macOS, Linux, Windows | v0.11 | `npm run quiver:plan -- --include-completed --spec <spec>` |
 | `quiver:graph -- --include-completed` | Includes completed slices in the dependency graph history view | macOS, Linux, Windows | v0.11 | `npm run quiver:graph -- --include-completed --spec <spec>` |
 | `quiver:next -- --include-completed` | Keeps actionable next-slice output and appends completed history | macOS, Linux, Windows | v0.11 | `npm run quiver:next -- --include-completed --spec <spec>` |
+| `quiver:ai:agent -- set <role> ... --dry-run` | Previews planner/executor/reviewer/doctor provider profile writes without creating `.quiver/agents/profiles.json` | macOS, Linux, Windows | v0.13 | `npm run quiver:ai:agent -- set planner --provider codex --model "planner-model" --dry-run` |
 | `quiver:ai:agent` | Stores reusable planner/executor/reviewer/doctor provider profiles without secrets | macOS, Linux, Windows | v0.11 | `npm run quiver:ai:agent -- set planner --provider codex --model "planner-model"` |
 | `quiver:ai:inspect` | Shows actionable lifecycle state through the generated npm script | macOS, Linux, Windows | v0.13 | `npm run quiver:ai:inspect` |
 | `quiver:ai:export` | Exports lifecycle state as JSON or Markdown through the generated npm script | macOS, Linux, Windows | v0.13 | `npm run quiver:ai:export -- --format json` |
@@ -60,6 +63,7 @@ This document is the canonical command reference for the orchestration roadmap.
 | `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: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>` |
 | `quiver:spec:close` | Closes a merged clean spec worktree and pulls the main checkout | macOS, Linux, Windows | v0.10 | `npm run quiver:spec:close -- specs/<spec> --dry-run` |
 | `quiver:check-slice -- --local <slice.json>` | Runs local structural slice validation without remote/base checks | macOS, Linux, Windows | v0.11 | `npm run quiver:check-slice -- --local specs/<spec>/slices/<slice>/slice.json` |
 | `quiver:check-handoff -- <handoff-or-brief.md>` | Validates legacy `HANDOFF.md` files and per-slice `EXECUTION_BRIEF.md` / `CLOSURE_BRIEF.md` files | macOS, Linux, Windows | v0.12.1 | `npm run quiver:check-handoff -- specs/<spec>/slices/<slice>/EXECUTION_BRIEF.md` |
@@ -87,6 +91,7 @@ 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 |
 | `--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 |
@@ -115,11 +120,14 @@ This document is the canonical command reference for the orchestration roadmap.
 - `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: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.
@@ -128,6 +136,7 @@ This document is the canonical command reference for the orchestration roadmap.
 - `quiver:ai:execute-plan -- --dry-run --commit --mode delegated` prints safe delegated waves and falls back to sequential mode when file scope is missing or overlapping.
 - `quiver:ai:execute-plan -- --execute --commit --mode delegated` uses temporary worktrees for parallel-ready waves and integrates one validated commit per slice.
 - `quiver:ai:pr -- --dry-run` validates GitHub CLI, auth, Git remote, current branch/worktree, `docs/GITFLOW_PR_GUIDE.md`, SSH host alias, optional identity file, `pr.md`, and open slice status without creating a PR. Add `--create` only after reviewing the plan.
+- GitHub auth and SSH diagnostics should identify likely account, scopes, and alias issues. When paths contain spaces, Quiver prints copy-safe examples for macOS/Linux, Windows PowerShell, Git Bash, and WSL.
 - `quiver:spec:close` refuses dirty or unmerged spec worktrees unless discard behavior is explicitly requested.
 - `npm run smoke:doctor-fixtures` validates the required fixture matrix for doctor, validation, and actionable error coverage in the Quiver source repo.
 - After `init` or `migrate`, Quiver auto-installs itself as a dev dependency. Use `--skip-install` to suppress.

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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-quiver",
-  "version": "0.12.1",
+  "version": "0.14.0",
   "private": false,
   "description": "Quiver CLI for scaffolding projects from the packaged template",
   "license": "MIT",
@@ -41,6 +41,7 @@
     "quiver:spec:create": "npx create-quiver spec create",
     "quiver:spec:start": "npx create-quiver spec start",
     "quiver:spec:status": "npx create-quiver spec status",
+    "quiver:spec:validate": "npx create-quiver spec validate",
     "quiver:spec:close": "npx create-quiver spec close",
     "package:quiver": "bash scripts/package-quiver.sh",
     "smoke:create-quiver": "bash scripts/ci/smoke-create-quiver.sh",

package/specs/quiver-v26-0121-smoke-hardening/SPEC.md

@@ -1,7 +1,7 @@
 # Quiver v26 - 0.12.1 Smoke Hardening
 
 **Date:** 2026-05-23
-**Status:** Implemented; release-ready pending PR merge and npm publication
+**Status:** Implemented; shipped in `create-quiver@0.12.1`
 
 Slice numbering resets here. This spec intentionally starts at `slice-00`.
 
@@ -134,4 +134,4 @@ The production-readiness review added these constraints:
 
 ## Release Plan
 
-This spec targets `0.12.1`. Publication happens only after the implementation PR is merged, the local validation suite passes, and the candidate package is smoke-tested outside the repo.
+This spec targeted `0.12.1`, which has been published. Follow-up reliability findings from Pixel Quiver dogfooding are tracked in `specs/quiver-v27-reliability-ai-workflow-hardening/`.

package/specs/quiver-v26-0121-smoke-hardening/STATUS.md

@@ -1,12 +1,12 @@
 # Status - Quiver v26 0.12.1 Smoke Hardening
 
-**Overall status:** Slices 00-07 complete; release-ready pending PR merge and npm publication
+**Overall status:** Slices 00-07 complete; shipped in `create-quiver@0.12.1`
 **Created:** 2026-05-23
 **Current slice:** slice-07 completed
 
 ## Summary
 
-This hotfix spec tracks the first-use issues found while smoke testing `create-quiver@0.12.0` from npm. The goal is to prepare a reliable `0.12.1` before using Quiver for the real `Quiver Spec Viewer` project.
+This hotfix spec tracks the first-use issues found while smoke testing `create-quiver@0.12.0` from npm. It prepared the `0.12.1` package that was later published.
 
 ## Slice Status
 
@@ -24,9 +24,9 @@ This hotfix spec tracks the first-use issues found while smoke testing `create-q
 ## Current Blockers
 
 - No local implementation blockers remain.
-- npm publication is intentionally pending until PR merge.
-- The real `Quiver Spec Viewer` project should wait until `create-quiver@0.12.1` is published and smoke-tested from npm.
+- npm publication for `0.12.1` is complete.
+- Follow-up dogfooding findings are tracked in `specs/quiver-v27-reliability-ai-workflow-hardening/`.
 
 ## Next Step
 
-Open the PR, merge after review, publish `create-quiver@0.12.1`, then verify the published package with `npm view create-quiver version` and a clean npm smoke.
+Use v27 for the next reliability hardening cycle.

package/specs/quiver-v27-reliability-ai-workflow-hardening/AUDIT_V24_V25_V26.md

@@ -0,0 +1,67 @@
+# Audit - v24/v25/v26 Against Pixel Quiver Evidence
+
+## Purpose
+
+This audit records the starting point for v27. It separates already existing implementation surfaces from behavior that remains partial, fragile, or unproven by the Pixel Quiver dogfooding evidence.
+
+## Audited Inputs
+
+- `README_FOR_AI.md`
+- `ROADMAP.md`
+- `CHANGELOG.md`
+- `specs/quiver-v24-dx-onboarding-hardening/**`
+- `specs/quiver-v25-ai-first-lifecycle-orchestrator/**`
+- `specs/quiver-v26-0121-smoke-hardening/**`
+- `src/create-quiver/**`
+- `tests/**`
+- Pixel Quiver evidence files containing `QP-001..QP-019` and `QIS-001..QIS-022`
+
+## Existing Coverage Observed
+
+The current repository already contains implementation and tests in several areas that v27 must reuse instead of rebuilding from scratch:
+
+| Area | Existing evidence in repo |
+|---|---|
+| `flow`, onboarding, and first-use guidance | `src/create-quiver/commands/flow.js`, `tests/commands/flow.test.js`, v24/v25/v26 docs. |
+| Context analysis and context preparation | `src/create-quiver/commands/analyze.js`, `src/create-quiver/commands/prepare-context.js`, `tests/commands/analyze.test.js`, `tests/commands/prepare-context.test.js`. |
+| Doctor diagnostics | `src/create-quiver/commands/doctor.js`, `tests/commands/doctor.test.js`, doctor fixture scripts. |
+| AI lifecycle commands | `src/create-quiver/commands/ai-onboard.js`, `ai-plan.js`, `ai-revise.js`, `ai-approve.js`, `ai-execute-plan.js`, `ai-export.js`, and related tests. |
+| AI export/state helpers | `src/create-quiver/lib/ai/export-state.js`, `tests/lib/ai-export-state.test.js`, `tests/commands/ai-export.test.js`. |
+| Spec and worktree lifecycle | `src/create-quiver/commands/spec-create.js`, `spec-start.js`, `spec-status.js`, `spec-close.js`, `src/create-quiver/lib/spec-worktrees.js`, related command tests. |
+| Scope, slice, handoff, and path validation | `src/create-quiver/commands/check-scope.js`, `check-slice.js`, `check-handoff.js`, `src/create-quiver/lib/scope.js`, `handoff.js`, `paths.js`, related tests. |
+| Evidence redaction and package safety | `src/create-quiver/lib/evidence.js`, `tests/lib/evidence.test.js`, `tests/lib/package-safety.test.js`. |
+| Cross-platform path handling | `tests/lib/paths.test.js` includes Windows-style path normalization and project-root safety coverage. |
+
+## Dogfooding Gaps Still Requiring v27 Work
+
+| Gap | Evidence | Why existing coverage is not enough |
+|---|---|---|
+| Classic and AI commands still disagree on completed slices. | QP-003, QIS-006 | Tests cover command names and helper output, but Pixel Quiver showed inconsistent lifecycle state across `plan --include-completed`, `ai inspect`, and `ai export`. |
+| JSON export is not stable enough for dashboards. | QP-019, QIS-004, QIS-022 | Existing `ai export` support exists, but the dashboard contract needs schema versioning, source metadata, lifecycle data, agents, runs, approvals, blockers, evidence, aggregates, and pure stdout JSON. |
+| `spec create` can ignore approved plan structure. | QP-011, QP-012, QIS-014, QIS-015 | Existing spec creation exists, but approved technical-plan parsing, structured slice validation, deterministic naming, and safe failure cleanup need direct regression fixtures. |
+| AI artifacts can contain prompt echo or raw provider noise. | QP-010, QIS-013 | Existing AI commands do not fully prove clean draft/raw transcript separation for real provider-style output. |
+| Revision feedback can exceed context limits. | QP-009, QIS-012 | Token compaction and safe refusal need explicit behavior before provider overflow. |
+| Worktree lifecycle needs persistent one-spec behavior and recovery. | QP-018, QIS-021 | Worktree helpers exist, but dogfooding showed nested/conflicting worktree confusion and missing recovery guidance. |
+| Validation gates miss execution preconditions. | QP-013, QP-016, QP-017, QIS-003, QIS-016, QIS-019, QIS-020 | Existing validation commands exist, but they must align with actual execution needs, base branch resolution, handoff templates, and strict spec validation. |
+| `analyze --dry-run` must be strictly read-only and stack detection must improve. | QP-005, QP-014, QIS-007, QIS-017 | Analyzer tests exist, but v27 needs mutation guards and React/Vite fixtures based on dogfooding failures. |
+| `flow`, `doctor`, and `prepare-context` must use current resolver state. | QP-001, QP-006, QP-015, QIS-001, QIS-008, QIS-018 | Existing diagnostics exist, but stale examples and missing evidence-backed next steps remain a real-world problem. |
+| Cross-platform help and GitHub auth guidance are incomplete. | QP-002, QP-004, QP-007, QIS-002, QIS-009, QIS-010, QIS-011 | Existing docs/help exist, but they must be more explicit for Windows/macOS/Linux, `gh`, aliases, and AI agent setup dry-runs. |
+
+## Source-of-Truth Sync
+
+`README_FOR_AI.md`, `ROADMAP.md`, and `CHANGELOG.md` were updated before implementation started so they do not describe v27 as already released.
+
+The current sync decision is:
+
+- v26 / `0.12.1` is shipped.
+- v27 is active/planned implementation work.
+- v27 must not be described as published until release smoke and npm publication happen.
+
+## Implementation Guidance
+
+- Treat v24/v25/v26 as prior art, not proof of closure.
+- Prefer extending existing commands and tests over creating duplicate lifecycle paths.
+- Add dogfooding fixtures that reproduce the Pixel Quiver failures in sanitized form.
+- Keep compatibility where users may depend on existing command names.
+- Introduce shared contracts first, then command-specific behavior.
+