create-quiver 0.12.1 → 0.13.0

package/CHANGELOG.md

@@ -4,6 +4,14 @@ 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

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
 
@@ -317,7 +319,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. |
@@ -336,7 +339,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 +358,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 +379,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"
@@ -462,7 +468,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 +495,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 +562,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 +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

@@ -16,9 +16,10 @@ 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.
 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.
@@ -28,6 +29,9 @@ Use `npm run smoke:doctor-fixtures` after changing doctor, preflight, validation
 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 +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: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 +139,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 +161,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,16 @@
 - 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/`.
+
 ## Post-Checkpoint Plan (do not execute before validating v14)
 
 > This section now records the follow-up line from the v14-era plan.
@@ -83,7 +89,8 @@
 - **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/`.
 
 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` |
@@ -40,6 +41,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 +62,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 +90,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,6 +119,8 @@ 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.
@@ -128,6 +134,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-quiver",
-  "version": "0.12.1",
+  "version": "0.13.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.
+

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

@@ -0,0 +1,125 @@
+# Command Contracts - Quiver v27 Reliability and AI Workflow Hardening
+
+## Purpose
+
+These contracts apply to every command touched by v27. A slice may add stricter behavior, but it must not weaken these defaults without documenting a migration path.
+
+## Output Streams
+
+- Human-readable progress, hints, warnings, and debug text go to `stderr` when `--format json` is used.
+- Machine-readable JSON goes to `stdout` only.
+- A successful JSON command must produce valid JSON parseable without stripping banners, logs, colors, prompts, or extra lines.
+- Non-JSON human commands may use `stdout` for primary content and `stderr` for warnings/errors.
+- Error details must be actionable and include the command area, failing precondition, and next safe step when known.
+
+## Exit Codes
+
+| Code | Meaning |
+|---:|---|
+| 0 | Success. Requested operation completed or dry-run was valid. |
+| 1 | General command failure with no more specific category. |
+| 2 | Invalid user input, unsupported option, missing required argument, or schema validation failure. |
+| 3 | Unsafe repository state, missing dependency, dirty worktree, stale lock, or failed precondition. |
+| 4 | External tool/provider failure, including AI provider, `gh`, git, npm, or package manager failures. |
+| 5 | Partial state was detected and recovery is required. The command must report exact files/state involved. |
+
+## Dry-Run
+
+- `--dry-run` is strictly read-only.
+- A dry-run command must not write, create, delete, rename, stage, commit, or modify files anywhere in the repository.
+- This includes `.quiver/`, `docs/`, `specs/`, generated logs, cache files, lock files, and package artifacts.
+- Dry-run output must clearly state what would change, where it would be written, and which validations would run.
+- If a command cannot guarantee read-only behavior, it must fail before doing work and explain why dry-run is unsupported.
+
+## Write Classes
+
+Every writing command must fit one of these classes:
+
+| Class | Meaning | Requirements |
+|---|---|---|
+| inspect | Read-only command. | Must not write. Supports JSON when useful. |
+| generate | Creates new files from validated input. | Must preflight collisions and fail atomically where possible. |
+| update | Modifies existing files or state. | Must backup or preserve recoverable previous valid state when practical. |
+| execute | Performs implementation or lifecycle action. | Must validate dependencies, scope, git state, and target worktree first. |
+| external | Calls git, GitHub, package manager, or AI provider. | Must report external command failure clearly and preserve local state. |
+
+## Atomicity and Partial State
+
+- Commands that write multiple files must validate all inputs before the first write whenever possible.
+- If partial writes can occur, the command must report exactly which files were written and how to recover.
+- Failed generation must not leave empty directories unless they are explicitly reported as recoverable partial state.
+- Existing valid files must not be replaced with invalid output.
+
+## Idempotency
+
+- Re-running a successful command with the same inputs should either produce the same result or report that no change is needed.
+- Collision handling must be deterministic and documented.
+- Commands that create slugs, spec ids, slice ids, branches, or worktree paths must use stable generation rules.
+
+## Path Safety
+
+- All write paths must resolve inside the project root unless the command explicitly documents an external target.
+- Path traversal (`..`), symlink escape, absolute-path injection, and writing into parent directories must be rejected.
+- Paths printed in help or next-step examples must be copy-safe when project paths include spaces.
+- Shell examples must be safe for the target shell family: macOS/Linux POSIX shells, Windows PowerShell, Git Bash, and WSL.
+
+## Root Detection
+
+- Commands must resolve and report the project root used for reads and writes.
+- Running from a subdirectory, a worktree, or a simple monorepo package must produce deterministic root resolution.
+- If multiple plausible roots exist, the command must stop and ask for an explicit root or print the safe command to run.
+
+## Package Manager Detection
+
+- Quiver must prefer the package manager indicated by lockfiles and package metadata.
+- Detection priority must be deterministic and documented.
+- Suggested commands must match the detected package manager: npm, pnpm, yarn, or bun.
+- If detection is ambiguous, Quiver must report the ambiguity and use the safest explicit command form.
+
+## Deterministic Ordering
+
+- JSON arrays for specs, slices, agents, runs, approvals, blockers, evidence, and next steps must be sorted deterministically.
+- Stable order should prefer declared dependency order, numeric slice order, created timestamp, and then id as a tiebreaker.
+- Human summaries must follow the same order where practical.
+
+## Status Catalogs
+
+Commands must use shared canonical statuses from the resolver once slice-01 introduces them. Until then, commands must not invent one-off lifecycle names.
+
+Minimum canonical families:
+
+- Spec: `draft`, `planned`, `approved`, `in-progress`, `blocked`, `review`, `done`, `archived`
+- Slice: `planned`, `ready`, `in-progress`, `blocked`, `review`, `completed`, `skipped`
+- Run: `draft`, `waiting-approval`, `approved`, `running`, `blocked`, `done`, `failed`
+- Agent: `idle`, `planning`, `reading`, `coding`, `reviewing`, `blocked`, `waiting-approval`, `done`
+- Approval: `pending`, `approved`, `rejected`, `superseded`
+
+## JSON Schema and Versioning
+
+- Machine-readable exports must include `schema_version`.
+- Breaking changes require a new schema version and migration guidance.
+- Payloads must include `generated_at`, `project_root`, `source`, and `warnings`.
+- Optional fields must be present as empty arrays/objects when that makes downstream parsing simpler and stable.
+
+## Legacy and Strict Modes
+
+- Existing commands should preserve legacy behavior by default when changing output would break users.
+- New strict behavior may be introduced behind explicit flags or by adding new command variants.
+- When legacy behavior is used, output should point to the stricter command or flag where appropriate.
+
+## Security and Redaction
+
+- Secrets, tokens, auth headers, provider keys, private URLs, and unnecessary absolute local paths must be redacted from committed fixtures and generated evidence.
+- Raw AI transcripts must be stored separately from clean drafts.
+- Redaction must happen before writing logs that may be committed.
+
+## Validation Expectations
+
+Each implementation slice must add or update tests for the contracts it touches. At minimum:
+
+- Successful `--format json` output parses as JSON.
+- Failing commands write diagnostics to `stderr` and exit non-zero.
+- Dry-run commands leave the git diff unchanged.
+- Path safety rejects writes outside the project root.
+- Fixtures preserve deterministic order.
+

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

@@ -0,0 +1,74 @@
+# Coverage Matrix - Quiver v27 Reliability and AI Workflow Hardening
+
+## Purpose
+
+This matrix maps every Pixel Quiver dogfooding problem (`QP-*`) and improvement suggestion (`QIS-*`) to the v27 implementation slice that must close it.
+
+The source files are evidence inputs, not fixtures. Do not copy unsanitized local paths, user names, command output, or project-specific data into committed fixtures without explicit sanitization.
+
+## Problem Coverage
+
+| Evidence | Area | Primary Slice | Risk if missed | Validation strategy |
+|---|---|---|---|---|
+| QP-001 | `flow` source discovery and stale examples | slice-07 | Users and agents follow incorrect next steps. | Fixture with current and stale spec state; `flow` output checked against resolver state. |
+| QP-002 | Paths with spaces and copy-safe examples | slice-08 | Commands fail in common macOS/Linux/Windows project paths. | Cross-platform path formatting snapshots for macOS, Linux, PowerShell, Git Bash, and WSL examples. |
+| QP-003 | Classic and AI commands disagree about completed slices | slice-01, slice-02 | Agents act on incomplete or stale lifecycle state. | Shared resolver tests plus export tests with completed, planned, blocked, and active slices. |
+| QP-004 | GitHub authentication and alias guidance | slice-08 | PR creation or preflight fails late with unclear recovery. | `ai doctor` and PR preflight fixtures for missing `gh`, wrong account, missing scopes, and alias expectations. |
+| QP-005 | Analyzer misdetects React/Vite context | slice-07 | Context docs are wrong, causing bad onboarding and bad prompts. | React/Vite fixture with expected stack detection and no false Vue classification. |
+| QP-006 | `prepare-context` lacks evidence and next-step clarity | slice-07 | Agents cannot trust generated context or understand what to do next. | Snapshot output includes evidence, stale/missing docs, and next safe command. |
+| QP-007 | Agent docs gaps and missing prompts | slice-07, slice-08 | Users manually invent onboarding and execution prompts. | Docs/help tests confirm planner, executor, and handoff guidance exists and links to generated files. |
+| QP-008 | Source-of-truth docs drift | slice-00, slice-07 | README, roadmap, and AI docs contradict product state. | Documentation audit plus docs sync checks in final release slice. |
+| QP-009 | `ai revise` grows context without compaction | slice-04 | Planner calls exceed provider limits or waste tokens. | Token-limit fixture validates compacted feedback or safe refusal before provider overflow. |
+| QP-010 | Prompt echo and raw logs mix into final drafts | slice-04 | Specs and plans contain unusable provider noise. | AI artifact fixture separates clean draft from raw transcript and redacts secrets. |
+| QP-011 | `spec create` ignores approved plan structure | slice-03 | Quiver creates generic or incomplete scaffolds after approval. | Approved-plan fixture creates expected spec, slices, handoffs, execution plan, and PR body. |
+| QP-012 | Failed `spec create` leaves empty dirs | slice-03 | Repo state becomes dirty and confusing after failure. | Failure fixture asserts no partial writes or exact recovery report. |
+| QP-013 | `check-slice --local` misses execution preconditions | slice-06 | Later execution fails after a passing local check. | Local check fixture validates required git, worktree, brief, dependency, and scope preconditions or lists skipped checks. |
+| QP-014 | `analyze --dry-run` writes files | slice-07 | Users cannot safely inspect impact before generating docs. | Dry-run test asserts no file changes, including `.quiver/`, `docs/`, and `specs/`. |
+| QP-015 | `doctor` points to wrong spec/slice examples | slice-07 | First-use guidance sends users to stale work. | Doctor fixture derives active spec/slice from resolver state. |
+| QP-016 | `check-scope` assumes wrong base branch | slice-06 | Valid branches fail scope checks or bad diffs are compared. | Scope fixtures cover `--base`, `git.base_branch`, remote default, and fallback order. |
+| QP-017 | `check-handoff` missing actionable template/aliases | slice-06 | Users cannot quickly fix invalid briefs. | Handoff fixture prints missing headings, minimal template, and supported aliases. |
+| QP-018 | Worktree lifecycle causes nested/conflicting worktrees | slice-05 | Spec work becomes scattered, dirty, or unsafe to merge. | Worktree fixtures cover persistent spec worktree, locks, stale state, dirty state, and recovery. |
+| QP-019 | JSON export not dashboard-ready | slice-02 | UIs and agents need custom parsing or cannot consume Quiver state. | JSON schema and fixture parse tests with deterministic output. |
+
+## Suggestion Coverage
+
+| Evidence | Area | Primary Slice | Risk if missed | Validation strategy |
+|---|---|---|---|---|
+| QIS-001 | Improve `flow` source references | slice-07 | Flow output remains untrustworthy. | Flow snapshot includes source file, status, and active target. |
+| QIS-002 | Quote/copy-safe command examples | slice-08 | Users with spaces in paths hit preventable failures. | Help snapshot validates quoted examples per shell family. |
+| QIS-003 | Add/strengthen `spec validate` | slice-06 | Broken specs/slices pass until later commands fail. | Spec validation fixture covers schema, dependencies, briefs, worktree hints, and source metadata. |
+| QIS-004 | Export canonical dashboard data | slice-02 | Dashboard and agents keep using unstable ad-hoc output. | Export schema fixture validates required top-level datasets and aggregates. |
+| QIS-005 | Generate executor handoff packages | slice-06 | Executors need too much context and burn tokens. | Handoff package fixture includes only selected slice, briefs, constraints, evidence, and validation commands. |
+| QIS-006 | One resolver for classic and AI commands | slice-01 | Commands keep disagreeing about lifecycle state. | Unit tests require classic and AI command adapters to consume the same resolver output. |
+| QIS-007 | Improve framework detection | slice-07 | Context docs misrepresent stack and workflow. | Analyzer fixtures for React/Vite, package-manager variants, and unknown stack. |
+| QIS-008 | Evidence-backed context generation | slice-07 | Generated docs cannot be trusted or maintained. | `prepare-context` output references source files and marks assumptions. |
+| QIS-009 | GitHub/PR readiness diagnostics | slice-08 | PR creation fails late. | Doctor/preflight output includes `gh`, auth, account, scopes, alias, remote, and next action. |
+| QIS-010 | Agent onboarding guide | slice-07, slice-08 | Users manually paste long prompts repeatedly. | README/help docs expose planner/executor/doctor/reviewer flows with minimal-context guidance. |
+| QIS-011 | `ai agent set --dry-run` or equivalent preflight | slice-08 | Users configure agents without seeing effect or missing dependencies. | Dry-run setup output lists provider command, availability, and files that would change without writing. |
+| QIS-012 | Token compaction for revisions | slice-04 | Iteration becomes expensive and brittle. | Revision fixture compacts accepted history and preserves required decisions. |
+| QIS-013 | Separate clean draft and raw transcript | slice-04 | Prompt echo corrupts committed docs. | Artifact tests assert separate files and redacted raw output. |
+| QIS-014 | Approved-plan parser | slice-03 | Structured human approvals cannot become accurate slices. | Parser fixtures cover valid, invalid, partial, and ambiguous slice blocks. |
+| QIS-015 | Deterministic slug/path generation | slice-03 | Repeated `spec create` creates inconsistent names or collisions. | Slug fixtures cover accents, spaces, punctuation, long titles, and collisions. |
+| QIS-016 | Stronger slice execution gate | slice-06 | Execution starts with missing dependencies or invalid scope. | `start-slice`/`check-slice` fixture blocks unsafe execution and prints recovery. |
+| QIS-017 | Strict dry-run contract | slice-07 | Trust in Quiver inspection commands is lost. | Dry-run mutation guard across analysis/context commands. |
+| QIS-018 | Doctor active-state awareness | slice-07 | Doctor suggests stale examples. | Doctor fixture uses resolver current state and reports stale docs. |
+| QIS-019 | Base branch configuration | slice-06 | Scope checks fail in repos using `main`, `develop`, or custom branches. | Base resolution fixture covers CLI option, slice config, git config, remote HEAD, fallback. |
+| QIS-020 | Handoff template guidance | slice-06 | Invalid briefs are hard to fix. | `check-handoff` output includes minimal copyable template. |
+| QIS-021 | Persistent spec worktree lifecycle | slice-05 | One-spec-per-worktree model remains manual and error-prone. | Worktree commands create/reuse/report one persistent worktree per spec. |
+| QIS-022 | Machine-readable output contract | slice-02 | Agents cannot parse command output safely. | `--format json` tests validate stdout-only JSON, stderr diagnostics, schema versioning, and deterministic ordering. |
+
+## Slice Responsibility Summary
+
+| Slice | Responsibility |
+|---|---|
+| slice-00 | Documentary foundation, evidence mapping, command contracts, v24/v25/v26 audit. |
+| slice-01 | Shared state resolver and canonical statuses for specs, slices, runs, approvals, agents, evidence, and worktrees. |
+| slice-02 | Stable JSON export and pure machine-readable command output. |
+| slice-03 | Approved technical plan parsing and reliable spec/slice generation. |
+| slice-04 | AI draft storage, raw logs, redaction, and token compaction. |
+| slice-05 | Persistent spec worktree lifecycle, locks, recovery, and no nested worktrees. |
+| slice-06 | Validation gates, scope safety, handoff packages, and local execution preconditions. |
+| slice-07 | Context analysis, prepare-context, flow, doctor, dry-run safety, and source-backed docs. |
+| slice-08 | Cross-platform help, GitHub auth, agent setup guidance, and first-use DX. |
+| slice-09 | Fixtures, smoke tests, docs sync, package smoke, and release readiness. |
+