create-quiver 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -4,6 +4,58 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [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
+
+- `help` command alias and grouped top-level CLI help so `npx create-quiver --help`, `npx create-quiver help`, and local `quiver --help` expose the supported command surface.
+- Current per-slice brief validation for `EXECUTION_BRIEF.md` and `CLOSURE_BRIEF.md`, while keeping legacy `HANDOFF.md` validation compatible.
+- Regression coverage for scoped `plan` and `graph` loading so unrelated historical specs are not parsed when `--spec <slug>` is used.
+
+### Changed
+
+- Default generated docs now avoid links to optional `docs/examples/*` files unless those files are actually exported.
+- `flow` and AI review/spec-create blockers now guide approved-but-unreviewed technical plans toward `ai review-plan` instead of confusing re-approval steps.
+- The optional `spec-viewer` demo now includes minimal Quiver metadata, doctor-friendly docs, broader Quiver scripts, and server port fallback.
+- Root development scripts for `quiver:plan` and `quiver:graph` now use the local CLI entrypoint so local validation tests the branch code.
+
+### Fixed
+
+- `check-slice --local` no longer fatally requires Git metadata in no-Git folders.
+- Bare same-spec dependencies such as `slice-00-docs-foundation` resolve correctly during local dependency validation.
+- Scoped `plan` and `graph` complete in this repository without increasing Node heap size.
+
+## [0.12.0] - 2026-05-22
+
+### Added
+
+- AI-first lifecycle run state with status, resume, phase locks, approvals, prompt/draft artifacts, and dashboard-friendly exports.
+- Safe AI onboarding docs with dry-run diffs, snapshots, assumptions, risks, contradictions, and human-content preservation.
+- Agent profiles and prompt-only/provider adapter flows for planner, executor, reviewer, and doctor roles.
+- Strict approval gates for acceptance criteria, technical plans, production-readiness reviews, and spec generation.
+- Generated spec/slice artifacts with `EXECUTION_BRIEF.md`, `CLOSURE_BRIEF.md`, read paths, allowed write paths, validation hints, dependency data, execution plans, and PR body.
+- Controlled slice execution with scope validation, closure/evidence/status updates, and one-commit-per-slice support.
+- Worktree, PR, inspection, export, trace, migration dry-run, and lifecycle list surfaces for AI-first workflows.
+
+### Changed
+
+- Quiver now treats the guided AI lifecycle as durable state under `.quiver/`, not as chat-only memory.
+- Generated docs and root docs describe planner/executor flows, review gates, worktree-per-spec, and release safety more explicitly.
+
+### Fixed
+
+- Hardened validation errors, fixture coverage, redaction, parser behavior, and migration/readiness checks around the AI lifecycle.
+
+## [0.11.0] - 2026-05-22
+
 ### Added
 
 - Guided AI workflow commands: `prepare`, agent profiles, planner onboarding, approval persistence, `review-plan`, `spec create`, executor prompt generation, delegated execution waves, PR creation with `gh`, spec worktree start/status/close, and package safety.

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
@@ -36,7 +37,8 @@ El flujo normal con IA continúa así:
 ```bash
 npx create-quiver flow
 npx create-quiver ai plan --phase acceptance --input requirements.md --dry-run
-npx create-quiver ai approve --phase acceptance --input acceptance-approved.md
+npx create-quiver ai revise --phase acceptance --input feedback.md --dry-run
+npx create-quiver ai approve --phase acceptance --version <n>
 npx create-quiver ai approvals
 npx create-quiver ai plan --phase technical-plan --dry-run
 npx create-quiver ai review-plan --dry-run
@@ -60,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
 
@@ -99,7 +102,8 @@ npx create-quiver doctor
 npx create-quiver ai prepare-context --dry-run
 npx create-quiver ai onboard --dry-run
 npx create-quiver ai plan --phase acceptance --input requirements.md --dry-run
-npx create-quiver ai approve --phase acceptance --input acceptance-approved.md
+npx create-quiver ai revise --phase acceptance --input feedback.md --dry-run
+npx create-quiver ai approve --phase acceptance --version <n>
 npx create-quiver ai plan --phase technical-plan --dry-run
 npx create-quiver ai review-plan --dry-run
 npx create-quiver ai approve --phase technical-plan --version <n>
@@ -145,7 +149,8 @@ Después del bootstrap, revisá:
 
 ```bash
 npx create-quiver ai plan --phase acceptance --input requirements.md --dry-run
-npx create-quiver ai approve --phase acceptance --input acceptance-approved.md
+npx create-quiver ai revise --phase acceptance --input feedback.md --dry-run
+npx create-quiver ai approve --phase acceptance --version <n>
 npx create-quiver ai plan --phase technical-plan --dry-run
 npx create-quiver ai review-plan --dry-run
 npx create-quiver ai approve --phase technical-plan --version <n>
@@ -310,24 +315,40 @@ El paquete también publica el alias binario `quiver`, que apunta al mismo CLI.
 |---|---|
 | `npx create-quiver init --name "Proyecto"` | Inicializa Quiver en un proyecto nuevo o nunca inicializado. |
 | `npx create-quiver --name "Proyecto"` | Alias compatible del flujo de init recomendado. |
-| `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 ai agent set <role> --provider <provider> --model <label>` | Guarda perfiles reutilizables para planner, executor, reviewer o researcher sin guardar secretos. |
+| `npx create-quiver --version` | Muestra la versión instalada del 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, 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. |
+| `npx create-quiver ai run create --input requirements.md` | Crea un run persistente en `.quiver/runs/` para un requerimiento. |
+| `npx create-quiver ai status` | Muestra la fase actual del run AI y el próximo comando seguro. |
+| `npx create-quiver ai resume` | Reanuda el run AI desde la última fase válida sin depender del historial del chat. |
+| `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 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. |
 | `npx create-quiver ai approvals` | Muestra drafts versionados y aprobados por fase. |
 | `npx create-quiver ai approve --phase acceptance --version <n>` | Aprueba una versión concreta de un draft guardado. |
 | `npx create-quiver init --minimal` | Crea solo el contrato esencial de onboarding. |
 | `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. |
 | `npx create-quiver prepare --dry-run` | Ejecuta diagnóstico guiado de preparación sin escribir archivos. |
 | `npx create-quiver prepare` | Refresca contexto y muestra riesgos, supuestos y próximos comandos. |
-| `npx create-quiver ai prepare-context --dry-run` | Previsualiza borradores de contexto IA, supuestos, riesgos, archivos considerados y rutas omitidas sin escribir. |
+| `npx create-quiver ai prepare-context --dry-run` | Previsualiza docs de onboarding, diffs, supuestos, riesgos, contradicciones y rutas omitidas sin escribir. |
 | `npx create-quiver migrate` | Actualiza proyectos que ya fueron inicializados con Quiver. |
+| `npx create-quiver migrate --dry-run` | Muestra qué actualizaría la migración sin escribir archivos. |
 | `npx create-quiver plan` | Lista slices pendientes en orden y calcula camino crítico. |
 | `npx create-quiver graph` | Muestra el grafo de dependencias (`tree`, `mermaid` o `dot`). |
 | `npx create-quiver next` | Sugiere el próximo slice listo para trabajar. |
@@ -335,9 +356,10 @@ El paquete también publica el alias binario `quiver`, que apunta al mismo CLI.
 | `npx create-quiver graph --include-completed` | Incluye slices completados en el grafo histórico. |
 | `npx create-quiver next --include-completed` | Mantiene la recomendación accionable y agrega historial completado. |
 | `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. |
+| `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 close <spec-dir>` | Cierra un worktree de spec ya mergeado y limpio. |
+| `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. |
 | `npx create-quiver check-slice --local <slice.json>` | Valida estructura local sin exigir remoto/base. |
@@ -345,7 +367,7 @@ El paquete también publica el alias binario `quiver`, que apunta al mismo CLI.
 | `npx create-quiver check-scope <slice.json>` | Verifica que los archivos modificados estén dentro del alcance declarado. |
 | `npx create-quiver cleanup-slice <slice.json>` | Limpia worktree/branch local asociado a un slice. |
 | `npx create-quiver refresh-active-slices` | Regenera el tablero local `ACTIVE_SLICES.md`. |
-| `npx create-quiver check-handoff <handoff.md>` | Valida un handoff. |
+| `npx create-quiver check-handoff <handoff-or-brief.md>` | Valida un `HANDOFF.md` o un brief de slice (`EXECUTION_BRIEF.md` / `CLOSURE_BRIEF.md`). |
 | `npx create-quiver new-handoff <spec-slug>` | Crea un handoff para una transferencia excepcional. |
 | `npx create-quiver evidence run -- <comando>` | Ejecuta un comando y guarda evidencia local con exit code, duración y salida redactada/truncada. |
 | `npx create-quiver demo create spec-viewer --dry-run` | Previsualiza el demo opcional Quiver Spec Viewer sin escribir archivos. |
@@ -356,13 +378,19 @@ El paquete también publica el alias binario `quiver`, que apunta al mismo CLI.
 ```bash
 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"
 npx create-quiver ai agent list
 npx create-quiver ai plan --phase acceptance --input requirements.md --dry-run
-npx create-quiver ai approve --phase acceptance --input acceptance-approved.md
+npx create-quiver ai plan --phase acceptance --input requirements.md --print-prompt
+npx create-quiver ai revise --phase acceptance --input feedback.md --dry-run
+npx create-quiver ai approve --phase acceptance --version <n>
 npx create-quiver ai plan --phase technical-plan --dry-run
 npx create-quiver ai review-plan --dry-run
+npx create-quiver ai review-plan --print-prompt
 npx create-quiver ai approve --phase technical-plan --version <n>
 npx create-quiver spec create --dry-run
 npx create-quiver ai prompt-slice --slice specs/<project-slug>/slices/slice-01/slice.json --dry-run
@@ -374,11 +402,11 @@ npx create-quiver ai pr --dry-run --input specs/<project-slug>/pr.md --ssh-host-
 ```
 
 Providers soportados: `codex`, `claude` y `gemini`, siempre vía CLI local.
-Usá `--dry-run` primero para revisar provider, rol, context pack, prompt y paths sin ejecutar el modelo.
+Usá `--dry-run` primero para revisar provider, rol, context pack y paths sin ejecutar el modelo. Usá `--print-prompt` cuando quieras ver el prompt exacto que se enviaría, sin depender de autenticación del provider.
 
 Orden recomendado:
 
-1. `ai prepare-context --dry-run`: revisa borradores de contexto, supuestos y riesgos antes de escribir docs.
+1. `ai prepare-context --dry-run`: revisa borradores de contexto, diffs, supuestos, riesgos y contradicciones antes de escribir docs. En modo escritura, Quiver guarda snapshots bajo `.quiver/runs/<run-id>/snapshots/`.
 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.
@@ -387,9 +415,10 @@ Orden recomendado:
 7. `spec create`: genera spec, slices, handoffs y PR body desde el plan revisado y aprobado.
 8. `spec start`: prepara un worktree por spec.
 9. `ai prompt-slice`: imprime el prompt mínimo para asignar un slice manualmente.
-10. `ai execute-slice` / `ai execute-plan`: ejecuta slices aprobados, con commit opt-in. Usá `--mode manual` para prompts y `--mode delegated` para worktrees temporales en olas paralelas.
-11. `ai doctor` / `ai pr`: valida GitHub y crea el PR solo con `--create`.
-12. `spec close`: cierra el worktree después del merge.
+10. `ai execute-slice` / `ai execute-plan`: ejecuta slices aprobados, con commit opt-in. `ai execute-slice` exige worktree/rama correctos, bloquea cambios fuera del alcance declarado, redacta logs sensibles y actualiza `CLOSURE_BRIEF.md`, `EVIDENCE_REPORT.md`, `COMMAND_LOG.md`, `STATUS.md` y `slice.json` cuando la ejecución pasa. Usá `--mode manual` para prompts y `--mode delegated` para worktrees temporales en olas paralelas.
+11. `ai inspect` / `ai export`: exponen estado accionable y formatos JSON/Markdown para humanos, agentes o dashboards.
+12. `ai doctor` / `ai pr`: valida GitHub y crea el PR solo con `--create`.
+13. `spec close`: cierra el worktree después del merge.
 
 ## 🧪 Cómo probar que funciona
 
@@ -406,6 +435,7 @@ Validaciones adicionales disponibles:
 
 ```bash
 npm run smoke:create-quiver
+npm run smoke:doctor-fixtures
 npm run smoke:guided-workflow
 npm run smoke:tiered-pack
 ```
@@ -425,19 +455,20 @@ npx create-quiver demo create spec-viewer --dry-run
 npx create-quiver demo create spec-viewer --dir ./quiver-spec-viewer
 ```
 
-El demo genera una app estática pequeña, specs/slices de ejemplo y scripts de validación. No forma parte de `init`; se crea solo cuando lo pedís.
+El demo genera una app estática pequeña, metadata mínima de Quiver, specs/slices de ejemplo y scripts de validación. `doctor`, `plan`, `graph` y `next` funcionan dentro del demo, y el server intenta el siguiente puerto si el inicial está ocupado. No forma parte de `init`; se crea solo cuando lo pedís.
 
 Notas reales del estado actual:
 
 - No hay script `npm test`; el comando verificado para tests es `node --test tests/**/*.test.js`.
 - `npm run package:quiver` valida el contenido del paquete npm generado.
 - `npm run smoke:guided-workflow` cubre el flujo guiado con IA sin llamadas reales pagas a providers.
+- `npm run smoke:doctor-fixtures` valida la matriz de estados de proyecto que deben seguir cubiertos por doctor/preflight.
 
 ## 📜 Scripts npm
 
 | 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. |
@@ -446,8 +477,13 @@ Notas reales del estado actual:
 | `npm run quiver:doctor` | Ejecuta `npx create-quiver doctor`. |
 | `npm run quiver:evidence` | Ejecuta `npx create-quiver evidence`; usalo como `npm run quiver:evidence -- run -- <comando>`. |
 | `npm run quiver:ai:agent` | Ejecuta `npx create-quiver ai agent`. |
+| `npm run quiver:ai:inspect` | Ejecuta `npx create-quiver ai inspect`. |
+| `npm run quiver:ai:export` | Ejecuta `npx create-quiver ai export`. |
+| `npm run quiver:ai:specs` | Ejecuta `npx create-quiver ai specs list`. |
+| `npm run quiver:ai:slices` | Ejecuta `npx create-quiver ai slices list`. |
+| `npm run quiver:ai:trace` | Ejecuta `npx create-quiver ai trace report`. |
 | `npm run quiver:ai:onboard` | Ejecuta onboarding de IA. |
-| `npm run quiver:ai:prepare-context` | Prepara borradores de contexto IA solo en documentación; usalo primero con `-- --dry-run`. |
+| `npm run quiver:ai:prepare-context` | Prepara docs de contexto IA solo en documentación; usalo primero con `-- --dry-run` para revisar diffs y contradicciones. |
 | `npm run quiver:ai:plan` | Ejecuta planificación IA por fases. |
 | `npm run quiver:ai:review-plan` | Revisa el plan técnico antes de aprobarlo y crear la spec. |
 | `npm run quiver:ai:approve` | Guarda criterios o planes aprobados. |
@@ -459,9 +495,11 @@ 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`. |
+| `npm run smoke:doctor-fixtures` | Smoke de la matriz de fixtures para validación, doctor y errores accionables. |
 | `npm run smoke:guided-workflow` | Smoke del flujo guiado con IA, PR, cleanup y package safety. |
 | `npm run smoke:tiered-pack` | Smoke de context packs y lifecycle. |
 | `npm run release:quiver` | Release dry-run o publish, según flags. |
@@ -522,10 +560,12 @@ Checklist de release:
 
 1. `node --test tests/**/*.test.js`
 2. `npm run smoke:create-quiver`
-3. `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.
+3. `npm run smoke:doctor-fixtures`
+4. `npm run smoke:guided-workflow`
+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
 
@@ -539,7 +579,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.13.0` y `CHANGELOG.md` reconoce `0.13.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

@@ -15,15 +15,23 @@ Use `npx create-quiver evidence run -- <command>` to capture validation evidence
 Use `npx create-quiver demo create spec-viewer --dry-run` to inspect the optional Quiver Spec Viewer demo scaffold, then add `--dir <target>` for a real run. The demo is not part of default init and must remain small, static, dependency-light, and non-destructive.
 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/` 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.
 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: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 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.
 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`.
@@ -60,7 +68,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: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.
@@ -129,33 +137,32 @@ 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. Fill in `docs/AI_CONTEXT.md`
-3. Fill in `docs/AI_ONBOARDING_PROMPT.md`
-4. Fill in `docs/CONTEXTO.md`
-5. Fill in `docs/STATUS.md`
-6. Run `npx create-quiver analyze` if `docs/PROJECT_MAP.md` or `.quiver/scans/PROJECT_SCAN.json` is missing
-7. If the project already exists from an older Quiver version and was previously initialized by Quiver, run `npx create-quiver migrate`
-8. If the project was never initialized by Quiver, run `npx create-quiver init --name "Project Name"` instead of `migrate`
-9. Ask the AI agent to execute `docs/AI_ONBOARDING_PROMPT.md`
-10. Review context docs before creating the first implementation slice
-11. Open and merge the documentation PR that establishes the workflow files
-12. Save reusable provider choices with `npx create-quiver ai agent set planner --provider <provider> --model "<label>"` and `npx create-quiver ai agent set executor --provider <provider> --model "<label>"`
-13. Use `npx create-quiver ai plan --phase acceptance --input requirements.md --dry-run`
-14. After human approval, save approved criteria with `npx create-quiver ai approve --phase acceptance --input acceptance-approved.md`
-15. Use `npx create-quiver ai plan --phase technical-plan --dry-run`
-16. Review the technical plan with `npx create-quiver ai review-plan --dry-run`, then run it without `--dry-run` when ready
-17. After human approval, save the reviewed plan version with `npx create-quiver ai approve --phase technical-plan --version <n>`
-18. 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
-19. Run `npx create-quiver spec start specs/<spec-slug>` to create or reuse the spec worktree
-20. Run `npx create-quiver plan` or `npm run quiver:plan`
-21. Run `npx create-quiver next` or `npm run quiver:next`
-22. 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
-23. For manual assignment, print a minimal executor prompt with `npx create-quiver ai prompt-slice --slice <slice.json> --dry-run`
-24. 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`
-25. Keep one commit per slice
-26. Open one PR per spec with `npx create-quiver ai pr --dry-run --input specs/<spec-slug>/pr.md ...`, then `--create` only after review
-27. After merge, close the worktree with `npx create-quiver spec close specs/<spec-slug>`
-28. Validate the slice and the final PR with the workflow gates
+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
 
 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

@@ -55,9 +55,25 @@
 - Shipped v22 Guided AI Workflow after `0.10.0`: preparation diagnostics, approval state, spec worktrees, executor commits, execution waves, PR creation, post-merge cleanup, and release/package safety are implemented on the release branch.
 - Shipped v23 Guided Flow Productization after `0.10.0`: short `quiver` entrypoint, flow status, agent profiles, token-efficient onboarding, versioned planner drafts, production plan review, spec create, executor prompts, delegated worktrees, and final smoke/readiness coverage are implemented on the release branch and ready for the next package release.
 
-## v0.11 — DX Onboarding Hardening (implemented, pending package release)
+## v0.11 — DX Onboarding Hardening (shipped 2026-05-22)
 
-- **v24** — DX and onboarding hardening from real Quiver Spec Viewer dogfooding: init hygiene, CLI ambiguity, version mismatch checks, local slice validation, analyzer quality, AI context preparation, evidence capture, optional demo scaffolding, documentation, and smoke coverage are implemented on the release branch. No npm release is implied until publication happens.
+- Published package `0.11.0`.
+- **v24** — DX and onboarding hardening from real Quiver Spec Viewer dogfooding: init hygiene, CLI ambiguity, version mismatch checks, local slice validation, analyzer quality, AI context preparation, evidence capture, optional demo scaffolding, documentation, and smoke coverage.
+
+## v0.12 — AI-First Lifecycle Orchestrator (shipped 2026-05-22)
+
+- 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 (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/`.
 
 ## Post-Checkpoint Plan (do not execute before validating v14)
 
@@ -71,7 +87,10 @@
 - **v21 — AI-First Layout** (completed): clean default init, `.quiver/` internals, analyze scan relocation, optional legacy assets, and no-spec-safe commands.
 - **v22 — Guided AI Workflow** (completed): guided preparation, approvals, spec worktrees, executor commits, execution waves, PR creation, cleanup, and release/package safety live in `specs/quiver-v22-guided-ai-workflow/`.
 - **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** (implemented, pending package release): 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/`.
+- **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** (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/`.
 
 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/AI_ONBOARDING_PROMPT.md.template

@@ -74,8 +74,14 @@ Si usás los comandos de IA de Quiver, empezá con `--dry-run` para revisar prov
 npm run quiver:prepare -- --dry-run
 npm run quiver:ai:prepare-context -- --dry-run
 npm run quiver:ai:onboard -- --dry-run
+npm run quiver:ai:inspect
+npm run quiver:ai:export -- --format json
+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:approve -- --phase acceptance --input acceptance-approved.md
+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>