create-quiver 0.10.0 → 0.12.1

package/BACKLOG.md

@@ -40,25 +40,24 @@
 ### Slice Orchestration and Tooling Commands
 
 - **Observed:** 2026-04-23
-- **Status:** planned
-- **Evidence so far:** 0 real cases. Drafted by the maintainer anticipating multi-model coordination (Opus/GPT-5.4 planning, Sonnet/GPT-5.4 Mini/Qwen Code execution) and visibility pain once specs accumulate.
-- **Problem it solves:** Today coordinating multiple agents across pending slices requires ad-hoc grep, ls, and git commands. There is no canonical way to ask "what runs next", "what can run in parallel", "what is this repo's state", or "how expensive is this slice to load".
+- **Status:** promoted
+- **Evidence so far:** The core orchestration line shipped through v18, v20, v21, v22, and v23. Guided workflow is implemented in `specs/quiver-v22-guided-ai-workflow/` and productized in `specs/quiver-v23-guided-flow-productization/`.
+- **Problem it solves:** Coordinating multiple agents across slices needs canonical answers for what runs next, what can run in parallel, what context each agent needs, and when work is ready for PR.
 - **Proposed shape:**
-  - v17 Orchestration Foundation (CI matrix, `lib/slice-graph.js`, `depends_on` validation)
-  - v18 Slice Orchestration (`plan`, `graph`, `next`)
-  - v19 Project Visibility (`status`, `estimate`, `lint-spec`)
-  - v20 Context Diagnostics (`cost`, `diff-pack`, `replay`)
-  - v21 Slice Archaeology (`archive`, `blame-slice`)
-  - v22 Deferred Tooling (`fork-slice`, `squash-spec`, `share`, evidence-gated per slice)
-- **Cost to formalize:** ~55h across 15 slices in 4 specs (v19–v22). Spec/slice files drafted under `drafts/v19-v22-orchestration-followups`.
-- **Reasons to wait:** v17 and v18 shipped. v18 must pass its validation checkpoint (≥1 week real use) before v19 starts. Building orchestration before validating the existing commands risks reinforcing a design that does not earn its place.
-- **Trigger to promote (per spec):**
-  - v19: immediately after v18 checkpoint passes (≥1 week real use of `plan`, `graph`, `next`)
-  - v20–v21: previous spec validation checkpoint passed (≥1 week real use)
-  - v22 per slice: explicit occurrence recorded in this file for each of `fork-slice`, `squash-spec`, `share`
+  - v18 Slice Orchestration (`plan`, `graph`, `next`) shipped.
+  - v20 AI CLI Orchestration shipped.
+  - v21 AI-First Layout shipped.
+  - v22 Guided AI Workflow shipped in this branch.
+  - v23 Guided Flow Productization shipped in this branch.
+- **Cost to formalize:** Completed in `specs/quiver-v22-guided-ai-workflow/` and `specs/quiver-v23-guided-flow-productization/`, both with mandatory `slice-00`.
+- **Reasons to wait:** No wait for the guided workflow; it has been implemented. Deferred tooling such as `fork-slice`, `squash-spec`, and `share` still requires real demand before separate implementation.
+- **Trigger to promote:** Fulfilled for guided workflow on 2026-05-21.
 - **Related:**
-  - `drafts/v19-v22-orchestration-followups` (parked spec drafts)
-  - `ROADMAP.md` Orchestration and Tooling section
+  - `specs/quiver-v18-slice-orchestration/`
+  - `specs/quiver-v20-ai-cli-orchestration/`
+  - `specs/quiver-v21-ai-first-layout/`
+  - `specs/quiver-v22-guided-ai-workflow/`
+  - `specs/quiver-v23-guided-flow-productization/`
 
 ### Handoff Contract
 

package/CHANGELOG.md

@@ -4,6 +4,84 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [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.
+- `quiver:prepare`, `quiver:flow`, `quiver:ai:agent`, `quiver:ai:review-plan`, `quiver:ai:prompt-slice`, `quiver:ai:execute-plan`, `quiver:spec:create`, `quiver:spec:start`, `quiver:spec:status`, and `quiver:spec:close` npm scripts for generated projects.
+- Guided workflow smoke coverage for flow status, profiles, onboarding, approvals, review-plan, spec create, executor prompts, delegated execution dry-runs, PR dry-run/create mocks, cleanup, and package safety.
+- DX onboarding hardening for generated projects: `doctor --fix`, `check-slice --local`, `plan|graph|next --include-completed`, `ai prepare-context`, `evidence run`, and `demo create spec-viewer`.
+- Generated scripts for `quiver:evidence` and `quiver:ai:prepare-context`.
+
+### Changed
+
+- Root and generated docs now present Quiver as AI-first guided workflow tooling, not only scaffolding.
+- `ai execute-plan` now documents manual prompt mode and delegated worktree mode.
+- Refreshed AI context docs keep front matter after `analyze`.
+- Package smoke now fails when local AI/tool state, env files, npm credentials, or worktree state would enter the npm tarball.
+- `init`, `doctor`, `prepare`, and `analyze` now produce clearer first-use guidance, safer repairs, better generated metadata, and better command maps.
+
+### Fixed
+
+- Unknown top-level commands now fail clearly instead of being treated as legacy project names.
+- Generated docs and scripts are kept aligned with the selected init profile and supported command surface.
+- Local-only repositories can run structural slice validation without a remote/base branch by using `check-slice --local`.
+
+## [0.10.0] - 2026-05-21
+
+### Added
+
+- AI CLI orchestration commands for provider dry-runs, planner phases, executor slice runs, and GitHub PR preflight.
+- AI-first default project layout with visible onboarding docs and internal `.quiver/` machinery.
+- Generated spec/slice/handoff/PR artifacts with mandatory `slice-00`.
+
+### Changed
+
+- Published `create-quiver` 0.10.0 and aligned the root docs with the current release line.
+
 ## [0.9.0] - 2026-05-14
 
 ### Added

package/README.md

@@ -12,8 +12,13 @@ Ejecutá Quiver desde la raíz del proyecto donde querés instalar el workflow:
 
 ```bash
 npx create-quiver init --name "Mi Proyecto"
+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"
+npx create-quiver ai agent set executor --provider codex --model "executor-model"
+npx create-quiver ai prepare-context --dry-run
 npx create-quiver ai onboard --dry-run
 ```
 
@@ -24,19 +29,44 @@ Después de eso, revisá:
 - `docs/AI_CONTEXT.md`
 - `docs/AI_ONBOARDING_PROMPT.md`
 
-La maquinaria interna queda en `.quiver/`. Las specs reales no se crean durante el init: aparecen cuando el planner genera y aprueba una spec con `ai plan --phase spec`.
+La maquinaria interna queda en `.quiver/`. Las specs reales no se crean durante el init: aparecen cuando el plan técnico ya fue revisado y aprobado, usando `spec create`.
 
 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 plan --phase technical-plan --input acceptance-approved.md --dry-run
-npx create-quiver ai plan --phase spec --input technical-plan-approved.md --dry-run
+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
+npx create-quiver ai approve --phase technical-plan --version <n>
+npx create-quiver spec create --dry-run
+npx create-quiver spec start specs/<project-slug>
 npx create-quiver next
-npx create-quiver ai execute-slice --slice specs/<project-slug>/slices/slice-01/slice.json --dry-run
+npx create-quiver ai execute-plan --dry-run --commit --mode manual
+npx create-quiver ai execute-plan --dry-run --commit --mode delegated
 ```
 
-Usá `--dry-run` para validar provider, rol, contexto y paths sin ejecutar el modelo. Cuando el output esté revisado y aprobado, quitá `--dry-run`.
+Usá `--dry-run` para validar provider, rol, contexto, paths y olas sin ejecutar el modelo. `--mode manual` imprime prompts para asignar slices a mano; `--mode delegated` prepara la ejecución con workspaces seguros cuando hay paralelismo.
+
+### Compatibilidad: macOS, Linux y Windows
+
+El camino principal de Quiver está pensado para ser portable: usa `npx create-quiver ...`, `npm run quiver:*` y `node ...`. Esos comandos funcionan en macOS, Linux y Windows siempre que tengas Node.js, npm y Git instalados.
+
+Reglas prácticas por sistema:
+
+- macOS y Linux: podés copiar los ejemplos tal como están. Las rutas SSH suelen verse como `~/.ssh/github-work`.
+- 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:*`.
+
+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`.
 
 ### Desarrollar este repositorio
 
@@ -58,21 +88,31 @@ Quiver asume que la mayoría de los equipos lo van a usar para coordinar trabajo
 |---|---|---|
 | WDD | Workflow-Driven Development: dejar claro cómo se trabaja antes de implementar. | `AGENTS.md`, `docs/WORKFLOW.md`, `docs/AI_CONTEXT.md`, `docs/PROJECT_MAP.md` |
 | SDD | Spec-Driven Development: definir el trabajo en specs y slices antes de tocar código. | `specs/<project-slug>/SPEC.md`, `slice.json`, `EXECUTION_BRIEF.md`, `pr.md` |
-| IA planner | Agente que lee contexto amplio y propone criterios, plan técnico, spec y slices. | `ai onboard`, `ai plan` |
-| IA executor | Agente que recibe un slice aprobado y trabaja con contexto mínimo. | `ai execute-slice`, `check-scope`, `check-slice` |
+| IA planner | Agente que lee contexto amplio y propone criterios, plan técnico, spec y slices. | `ai prepare-context`, `ai onboard`, `ai plan` |
+| IA executor | Agente que recibe un slice aprobado y trabaja con contexto mínimo. | `ai prompt-slice`, `ai execute-slice`, `check-scope`, `check-slice` |
 
 Flujo recomendado:
 
 ```bash
 npx create-quiver analyze
+npx create-quiver flow
 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 plan --phase technical-plan --input acceptance-approved.md --dry-run
-npx create-quiver ai plan --phase spec --input technical-plan-approved.md --dry-run
+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>
+npx create-quiver spec create --dry-run
+npx create-quiver spec start specs/<project-slug>
 npx create-quiver graph
 npx create-quiver next
-npx create-quiver ai execute-slice --slice specs/<project-slug>/slices/slice-01/slice.json --dry-run
+npx create-quiver ai prompt-slice --slice specs/<project-slug>/slices/slice-01/slice.json --dry-run
+npx create-quiver ai execute-slice --slice specs/<project-slug>/slices/slice-01/slice.json --dry-run --commit
+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
 ```
 
 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`.
@@ -87,25 +127,32 @@ Usá este camino cuando todavía no existe el proyecto o estás arrancando una c
 mkdir mi-proyecto
 cd mi-proyecto
 npx create-quiver init --name "Mi Proyecto"
+npx create-quiver flow
+npx create-quiver prepare --dry-run
 npx create-quiver analyze
 npx create-quiver doctor
+npx create-quiver ai prepare-context --dry-run
 npx create-quiver ai onboard --dry-run
 ```
 
 Qué esperar:
 
-- Quiver crea un contrato visible chico: `AGENTS.md`, `docs/`, scripts `quiver:*` en `package.json` y configuración interna en `.quiver/`.
+- Quiver crea un contrato visible chico: `AGENTS.md`, `docs/`, `.gitignore`, scripts `quiver:*` en `package.json` y configuración interna en `.quiver/`.
 - No crea `docs-template/`, `tools/scripts/` ni una spec placeholder en el flujo default.
 - `analyze` crea el scan crudo en `.quiver/scans/PROJECT_SCAN.json` y el mapa legible en `docs/PROJECT_MAP.md`.
 - `doctor` valida que el contrato inicial esté completo.
-- `ai onboard --dry-run` muestra cómo se incorporaría un agente planner sin ejecutar el provider todavía.
+- `ai prepare-context --dry-run` muestra borradores y supuestos sin escribir; `ai onboard --dry-run` muestra cómo se incorporaría un agente planner sin ejecutar el provider todavía.
 
 Después del bootstrap, revisá:
 
 ```bash
 npx create-quiver ai plan --phase acceptance --input requirements.md --dry-run
-npx create-quiver ai plan --phase technical-plan --input acceptance-approved.md --dry-run
-npx create-quiver ai plan --phase spec --input technical-plan-approved.md --dry-run
+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>
+npx create-quiver spec create --dry-run
 npx create-quiver plan
 npx create-quiver graph
 npx create-quiver next
@@ -127,8 +174,12 @@ Luego inicializá Quiver desde la raíz del proyecto:
 
 ```bash
 npx create-quiver init --name "Nombre del Proyecto"
+npx create-quiver flow
 npx create-quiver analyze
 npx create-quiver doctor
+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
 npx create-quiver ai onboard --dry-run
 git status --short
 ```
@@ -138,7 +189,7 @@ Qué esperar:
 - Quiver agrega documentación, scripts `quiver:*` y archivos internos de soporte en `.quiver/`.
 - No deberías mezclar este paso con cambios de producto.
 - `docs/PROJECT_MAP.md` queda como fuente de verdad para stack, package manager, comandos y rutas importantes.
-- Las specs y slices reales se crean después, con `ai plan --phase spec`, cuando ya existen criterios y plan técnico aprobados.
+- Las specs y slices reales se crean después, con `spec create`, cuando ya existen criterios aprobados y un plan técnico revisado y aprobado.
 - El primer trabajo de IA debería ser preparar contexto y planificación, no implementar.
 
 Importante: no uses `migrate` para un proyecto que nunca tuvo Quiver. `migrate` es solo para proyectos previamente inicializados.
@@ -164,6 +215,7 @@ npx create-quiver doctor
 npx create-quiver migrate
 npx create-quiver analyze
 npx create-quiver doctor
+npx create-quiver ai prepare-context --dry-run
 npx create-quiver ai onboard --dry-run
 git status --short
 ```
@@ -179,7 +231,7 @@ Qué esperar:
 - La migración restaura o agrega archivos faltantes de forma aditiva.
 - No debería sobrescribir archivos existentes de proyecto sin necesidad.
 - Después de migrar, `analyze` actualiza el mapa técnico y `doctor` confirma los próximos pasos.
-- `ai onboard --dry-run` ayuda a validar que el contexto viejo quedó entendible para un agente planner.
+- `ai prepare-context --dry-run` ayuda a revisar supuestos del contexto migrado; `ai onboard --dry-run` valida que el contexto viejo quedó entendible para un agente planner.
 
 Si `doctor` falla indicando que el proyecto no fue inicializado por Quiver, usá el flujo del caso 2.
 
@@ -203,7 +255,7 @@ La idea práctica: primero contexto, después plan, después código.
 | Runtime | Node.js CLI |
 | Lenguaje | JavaScript CommonJS |
 | Package manager | npm (`package-lock.json`) |
-| Binario npm | `create-quiver` -> `bin/create-quiver.js` |
+| Binario npm | `create-quiver` y alias `quiver` -> `bin/create-quiver.js` |
 | Tests | Node built-in test runner (`node:test`) |
 | CI/CD | GitHub Actions |
 | Distribución | Paquete npm público `create-quiver` |
@@ -231,7 +283,7 @@ No se detectaron archivos `.env`; Quiver no requiere variables de entorno para e
 | `src/create-quiver/commands/` | Comandos `ai`, `graph`, `next` y `plan`. |
 | `src/create-quiver/lib/` | Lógica de análisis, doctor, slices, lifecycle, IA, Git y renderers. |
 | `docs/` | Plantillas que Quiver copia a proyectos destino. |
-| `specs/` | Specs internas del desarrollo de Quiver y templates usados cuando `ai plan --phase spec` crea una spec real. |
+| `specs/` | Specs internas del desarrollo de Quiver y templates usados cuando `spec create` crea una spec real. |
 | `scripts/` | Scripts de packaging, release, CI smoke y wrappers legacy. |
 | `tests/` | Tests unitarios y fixtures. |
 | `examples/` | Ejemplo mínimo de spec/slice. |
@@ -255,53 +307,112 @@ Para IA sin `--dry-run`, la autenticación depende del proveedor local que uses
 ## 🧭 Comandos principales
 
 Los comandos reales del CLI se ejecutan con `npx create-quiver ...` o, durante desarrollo local, con `node bin/create-quiver.js ...`.
+El paquete también publica el alias binario `quiver`, que apunta al mismo CLI. Usalo cuando el paquete ya esté instalado localmente; para bootstrap remoto, seguí usando `npx create-quiver`.
 
 | Comando | Para qué sirve |
 |---|---|
 | `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 --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 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 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 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 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. |
+| `npx create-quiver plan --include-completed` | Muestra slices completados para auditoría o demos. |
+| `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. 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; 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. |
 | `npx create-quiver check-pr <slice.json>` | Valida estructura esperada para PR. |
 | `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. |
+| `npx create-quiver demo create spec-viewer --dir <target>` | Crea el demo estático con app, spec, slices, handoffs y validación. |
 
 ### Comandos de IA para WDD + SDD
 
 ```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"
+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 plan --phase technical-plan --input acceptance-approved.md --dry-run
-npx create-quiver ai plan --phase spec --input technical-plan-approved.md --dry-run
-npx create-quiver ai execute-slice --slice specs/<project-slug>/slices/slice-01/slice.json --dry-run
+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
+npx create-quiver ai execute-slice --slice specs/<project-slug>/slices/slice-01/slice.json --dry-run --commit
+npx create-quiver ai execute-plan --dry-run --commit --mode manual
+npx create-quiver ai execute-plan --dry-run --commit --mode delegated
 npx create-quiver ai doctor --dry-run --ssh-host-alias github-work --identity-file ~/.ssh/github-work
-npx create-quiver ai pr --dry-run --ssh-host-alias github-work --identity-file ~/.ssh/github-work
+npx create-quiver ai pr --dry-run --input specs/<project-slug>/pr.md --ssh-host-alias github-work --identity-file ~/.ssh/github-work
 ```
 
 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 onboard`: el planner entiende el repo y el workflow.
-2. `ai plan --phase acceptance`: convierte requerimientos en criterios de aceptación.
-3. `ai plan --phase technical-plan`: propone el plan técnico.
-4. `ai plan --phase spec`: genera spec, slices, handoffs y PR body.
-5. `ai execute-slice`: ejecuta un slice aprobado con rol executor.
-6. `ai doctor` / `ai pr`: valida preflight de GitHub y PR.
+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.
+5. `ai review-plan`: revisa el plan como si fuera a producción, sin tocar código ni cuestionar el alcance aprobado.
+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.
+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. `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
 
@@ -311,35 +422,78 @@ Validación rápida del repo:
 node bin/create-quiver.js --help
 node --test tests/**/*.test.js
 npm run package:quiver
+npm pack --dry-run
 ```
 
 Validaciones adicionales disponibles:
 
 ```bash
 npm run smoke:create-quiver
+npm run smoke:doctor-fixtures
+npm run smoke:guided-workflow
 npm run smoke:tiered-pack
 ```
 
+Para dejar evidencia resumida de una validación sin pegar logs completos:
+
+```bash
+npx create-quiver evidence run -- npm test
+```
+
+Por defecto la evidencia queda en `.quiver/evidence/`. También podés elegir destino con `--output <archivo>` y limitar stdout/stderr con `--max-output <n>`.
+
+Para probar Quiver sin inventar una app desde cero:
+
+```bash
+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, 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:tiered-pack` existe, pero revisar la sección "Información pendiente de confirmar" antes de usarlo como gate obligatorio.
+- `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: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. |
 | `npm run quiver:graph` | Ejecuta `npx create-quiver graph`. |
 | `npm run quiver:next` | Ejecuta `npx create-quiver next`. |
+| `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 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. |
+| `npm run quiver:ai:prompt-slice` | Imprime un prompt mínimo para asignar un slice a un executor. |
 | `npm run quiver:ai:execute-slice` | Ejecuta un slice con rol executor. |
+| `npm run quiver:ai:execute-plan` | Imprime o ejecuta olas de slices; soporta `--mode manual` y `--mode delegated`. |
 | `npm run quiver:ai:doctor` | Ejecuta preflight IA/GitHub. |
-| `npm run quiver:ai:pr` | Ejecuta preflight de PR. |
+| `npm run quiver:ai:pr` | Ejecuta preflight de PR y crea PR con `--create`. |
+| `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: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. |
 
@@ -350,12 +504,15 @@ Notas reales del estado actual:
 1. Inicializá Quiver o migrá si el proyecto ya lo tenía.
 2. Corré `analyze` para generar el mapa técnico.
 3. Corré `doctor` para validar el contrato.
-4. Incorporá al planner con `ai onboard --dry-run`.
-5. Convertí requerimientos en criterios, plan técnico y spec con `ai plan`.
-6. Revisá dependencias con `graph` y elegí el próximo trabajo con `next`.
-7. Ejecutá el slice con `ai execute-slice` o con tu agente usando el handoff generado.
-8. Validá con `check-slice`, `check-scope` y `check-pr`.
-9. Cerrá el trabajo con evidencia en el PR.
+4. Prepará contexto IA con `ai prepare-context --dry-run` y revisá los supuestos antes de escribir.
+5. Incorporá al planner con `ai onboard --dry-run`.
+6. Convertí requerimientos en criterios, plan técnico y spec con `ai plan`; revisá el plan con `ai review-plan` antes de aprobarlo.
+7. Creá la spec real con `spec create` y prepará su worktree con `spec start`.
+8. Revisá dependencias con `graph`, `next` o `ai execute-plan --dry-run --mode manual`.
+9. Para ejecución manual, generá el prompt con `ai prompt-slice --slice <slice.json> --dry-run`.
+10. Ejecutá slices con `ai execute-slice --commit` o `ai execute-plan --execute --commit --mode delegated`.
+11. Abrí el PR con `ai pr --create` después de revisar el dry-run.
+12. Después del merge, cerrá el worktree con `spec close`.
 
 ## 🤝 Contribuir
 
@@ -392,6 +549,16 @@ npm whoami
 npm view create-quiver version
 ```
 
+Checklist de release:
+
+1. `node --test tests/**/*.test.js`
+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.
+
 ## 📚 Documentación útil
 
 - [README para agentes de IA](./README_FOR_AI.md)
@@ -402,11 +569,11 @@ npm view create-quiver version
 - [Contribución](./CONTRIBUTING.md)
 - [Seguridad](./SECURITY.md)
 
-## Información pendiente de confirmar
+## Información confirmada y pendiente
 
+- `package.json` está en `0.10.0` y `CHANGELOG.md` reconoce `0.10.0`.
 - `package.json` no declara `engines`; la versión mínima real de Node queda pendiente. La CI usa Node 22.
-- `package.json` está en `0.9.0`, igual que `CHANGELOG.md`.
-- `docs/COMMANDS.md.template` marca algunos comandos de IA como `v0.10`, aunque `package.json` todavía está en `0.9.0`; la próxima publicación debe alinear versión y changelog.
+- 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`.
 
 ## Licencia