create-quiver 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -4,6 +4,25 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.14.0] - 2026-05-25
+
+### Added
+
+- v28 Pixel Quiver feedback reconciliation under `specs/quiver-v28-pixel-quiver-feedback-reconciliation/`.
+- `ai active-slice status|reconcile` for dry-run-first active-slice state inspection across `docs/ai/ACTIVE_SLICE.md` and `ACTIVE_SLICES.md`.
+- Structured `ai review-plan` closure metadata with `approve`, `approve-with-risk`, and `revise` recommendations.
+
+### Changed
+
+- `ai inspect` now prefers existing-spec recovery commands (`spec validate`, `next`, `ai prompt-slice`) when a lifecycle run still points to stale `spec create` guidance.
+- Agent-facing docs/help now include non-interactive `npx --yes create-quiver@<version>` examples.
+- GitHub PR preflight guidance now gives clearer macOS, Linux, Windows PowerShell, Git Bash, and WSL recovery copy for `gh` and SSH aliases.
+
+### Fixed
+
+- Technical-plan approval now blocks reviews with required fixes or a `revise` recommendation.
+- `spec validate`, `spec status`, and `spec start --dry-run` were hardened for execution metadata, stale worktree paths, dirty checkout recovery, and scope diagnostics.
+
 ## [0.13.0] - 2026-05-25
 
 ### Added

package/README.md

@@ -117,6 +117,12 @@ npx create-quiver ai execute-plan --dry-run --commit --mode delegated
 npx create-quiver ai pr --dry-run --input specs/<project-slug>/pr.md --ssh-host-alias github-work --identity-file ~/.ssh/github-work
 ```
 
+Cuando pegues comandos en un agente externo y quieras evitar prompts interactivos de `npx`, usá la forma versionada y no interactiva:
+
+```bash
+npx --yes create-quiver@<version> ai prompt-slice --slice specs/<project-slug>/slices/slice-01/slice.json --dry-run
+```
+
 Regla práctica: el planner no modifica código de producto; el executor solo trabaja sobre un slice aprobado y dentro de los archivos declarados en `slice.json`.
 
 ## 🛠️ Empezar a usar Quiver según tu caso
@@ -330,6 +336,7 @@ El paquete también publica el alias binario `quiver`, que apunta al mismo CLI.
 | `npx create-quiver ai inspect` | Resume specs, slices, runs, agentes, layout y próximos comandos accionables. |
 | `npx create-quiver ai export --format json` | Exporta estado de specs, slices, runs, agentes, dependencias y migración para dashboards o agentes. |
 | `npx create-quiver ai export --format markdown` | Exporta el mismo estado en Markdown legible para PRs o docs. |
+| `npx create-quiver ai active-slice reconcile --dry-run` | Inspecciona y reconcilia en modo lectura el estado local del slice activo entre `docs/ai/ACTIVE_SLICE.md` y `ACTIVE_SLICES.md`. |
 | `npx create-quiver ai specs list` | Lista specs con estado, progreso y cantidad de slices. |
 | `npx create-quiver ai slices list` | Lista slices con estado, progreso, dependencias y bloqueos. |
 | `npx create-quiver ai trace report` | Muestra runs, olas de ejecución y estado de migración en formato humano. |
@@ -410,7 +417,7 @@ Orden recomendado:
 2. `ai onboard`: el planner entiende el repo y el workflow.
 3. `ai plan --phase acceptance`: convierte requerimientos en criterios de aceptación.
 4. `ai plan --phase technical-plan`: propone el plan técnico.
-5. `ai review-plan`: revisa el plan como si fuera a producción, sin tocar código ni cuestionar el alcance aprobado.
+5. `ai review-plan`: revisa el plan como si fuera a producción, sin tocar código ni cuestionar el alcance aprobado. La salida guarda metadata con recomendación `approve`, `approve-with-risk` o `revise`.
 6. `ai approve`: guarda criterios o la versión revisada del plan técnico.
 7. `spec create`: genera spec, slices, handoffs y PR body desde el plan revisado y aprobado.
 8. `spec start`: prepara un worktree por spec.
@@ -579,7 +586,7 @@ Checklist de release:
 
 ## Información confirmada y pendiente
 
-- `package.json` está en `0.13.0` y `CHANGELOG.md` reconoce `0.13.0`.
+- `package.json` está en `0.14.0` y `CHANGELOG.md` reconoce `0.14.0`.
 - `package.json` no declara `engines`; la versión mínima real de Node queda pendiente. La CI usa Node 22.
 - Si aparece alguna referencia vieja a `0.9.0`, hay que actualizarla al contrato actual antes de seguir.
 - Los scripts legacy de `package.json` que apuntan a `tools/scripts/*` deben confirmarse para este repo fuente o separarse de los scripts pensados para proyectos generados con `--legacy-scripts` o `--full`.

package/README_FOR_AI.md

@@ -18,12 +18,16 @@ The v24 spec is implemented under `specs/quiver-v24-dx-onboarding-hardening/`; i
 The v25 spec is implemented under `specs/quiver-v25-ai-first-lifecycle-orchestrator/` and shipped in `create-quiver@0.12.0`; it covers safe AI onboarding docs, strict run state, phase locks, agent adapters, approval gates, spec/slice generation, execution planning, controlled slice execution, worktree/PR lifecycle, validation hardening, export, and migration.
 The v26 hotfix spec is implemented under `specs/quiver-v26-0121-smoke-hardening/` and shipped in `create-quiver@0.12.1`; it covers smoke hardening for CLI help/version output, generated doc links, AI approval/review guidance, local validation, slice brief validation, demo readiness, scoped plan/graph performance, and release smoke coverage.
 The v27 spec is implemented under `specs/quiver-v27-reliability-ai-workflow-hardening/` and shipped in `create-quiver@0.13.0`; it captures Pixel Quiver dogfooding findings (`QP-001` to `QP-019`, `QIS-001` to `QIS-022`) and includes shared state resolution, canonical statuses, schema v2 exports, structured spec creation, AI artifact cleanup, worktree locks, validation gates, context diagnostics, cross-platform DX, fixtures, smoke suites, and package/tarball release readiness.
+The v28 spec is implemented under `specs/quiver-v28-pixel-quiver-feedback-reconciliation/` and shipped in `create-quiver@0.14.0`; it captures the Pixel Quiver follow-up reconciliation with active-slice reconciliation, stale `ai inspect` recovery, structured review closure, stricter technical-plan approval, spec/worktree validation hardening, agent-safe commands, GitHub auth/alias guidance, and package-readiness evidence.
 Guided AI workflow behavior is available: prepare, approvals, production-readiness plan review, spec worktrees, executor commits, execution waves, PR creation, spec close, and package safety.
 Generated projects also get `quiver:*` npm scripts that call the Node CLI directly; prefer those for repeatable project workflows, including `quiver:flow` for the read-only guided entrypoint, `quiver:plan` for sequential planning, `quiver:graph` for parallel-level inspection, `quiver:next` for the next ready slice, `quiver:evidence` for local command evidence, `quiver:spec:create` for real spec generation, `quiver:spec:validate` for full spec validation, and the AI family `quiver:ai:agent`, `quiver:ai:inspect`, `quiver:ai:export`, `quiver:ai:specs`, `quiver:ai:slices`, `quiver:ai:trace`, `quiver:ai:onboard`, `quiver:ai:prepare-context`, `quiver:ai:plan`, `quiver:ai:review-plan`, `quiver:ai:approve`, `quiver:ai:prompt-slice`, `quiver:ai:execute-slice`, `quiver:ai:execute-plan`, `quiver:ai:pr`, and `quiver:ai:doctor`. Use `quiver:graph --format mermaid` for PR-ready Markdown or `quiver:graph --format dot` for Graphviz source.
 `quiver:ai:execute-plan` supports `--mode manual` for paste-ready executor prompts and `--mode delegated` for temporary worktrees on parallel-ready waves; unsafe waves fall back to sequential execution.
 Agent profiles live in `.quiver/agents/profiles.json`; they store role, provider, model label, context label, and display label only. Do not store API keys, tokens, or credentials there.
 Planner drafts are versioned under `.quiver/approvals/<phase>/drafts/`; review the technical-plan draft with `npx create-quiver ai review-plan --dry-run` before approving it, then approve a concrete version with `npx create-quiver ai approve --phase <phase> --version <n>` when reviewing iterations.
+`ai review-plan` stores structured closure metadata under `.quiver/approvals/plan-review/meta.json`: `approval_recommendation` is `approve`, `approve-with-risk`, or `revise`; required fixes block technical-plan approval, while optional hardening does not.
 AI lifecycle runs are persisted under `.quiver/runs/<run-id>/`; use `npx create-quiver ai run create --input <requirements.md>` to start one explicitly, `npx create-quiver ai status` to inspect it, `npx create-quiver ai resume` to continue from the last valid phase without relying on chat memory, and `npx create-quiver ai export --format json|markdown` when another agent, PR, or dashboard needs the current specs/slices/runs state.
+Use `npx create-quiver ai active-slice reconcile --dry-run` when `docs/ai/ACTIVE_SLICE.md`, `ACTIVE_SLICES.md`, worktrees, or `ai inspect` appear out of sync. The command is dry-run-first and reports preserve, close, replace, or blocked decisions without writing files.
+When generating commands for another AI agent, prefer non-interactive package-pinned examples such as `npx --yes create-quiver@<version> ai prompt-slice --slice <slice.json> --dry-run`.
 Maintain release notes and package publishing with `scripts/release-quiver.sh`.
 Use `npm run smoke:doctor-fixtures` after changing doctor, preflight, validation, actionable errors, or fixture coverage.
 The primary generated project context for agents is `docs/AI_CONTEXT.md`.

package/ROADMAP.md

@@ -75,6 +75,11 @@
 - Published package `0.13.0`.
 - **v27** — Reliability hardening from Pixel Quiver dogfooding: shared state resolver, canonical statuses, JSON export contract, approved-plan spec generation, AI artifact cleanup, token compaction, worktree lifecycle, validation gates, context diagnostics, cross-platform DX, fixtures, smoke tests, and package/tarball release readiness live in `specs/quiver-v27-reliability-ai-workflow-hardening/`.
 
+## v0.14 — Pixel Quiver Feedback Reconciliation (shipped 2026-05-25)
+
+- Published package `0.14.0`.
+- **v28** — Follow-up hardening from Pixel Quiver dogfooding: active-slice reconciliation, spec-aware `ai inspect` recovery, structured plan-review closure, safer technical-plan approval, stronger spec/worktree validation, agent-safe command examples, GitHub auth/alias guidance, and final release-readiness evidence live in `specs/quiver-v28-pixel-quiver-feedback-reconciliation/`.
+
 ## Post-Checkpoint Plan (do not execute before validating v14)
 
 > This section now records the follow-up line from the v14-era plan.
@@ -91,6 +96,7 @@
 - **v25 — AI-First Lifecycle Orchestrator** (shipped in `0.12.0`): safe AI onboarding docs, strict run state, phase locks, agent adapters, approval gates, generated specs/slices/handoffs/PR body, execution waves, controlled slice execution, worktree/PR lifecycle, validation hardening, export, and migration live in `specs/quiver-v25-ai-first-lifecycle-orchestrator/`.
 - **v26 — 0.12.1 Smoke Hardening** (shipped in `0.12.1`): first-use hardening from clean npm smoke testing, covering CLI help/version output, generated doc links, AI approval/review guidance, local validation, slice brief validation, demo readiness, scoped plan/graph performance, and release smoke coverage live in `specs/quiver-v26-0121-smoke-hardening/`.
 - **v27 — Reliability and AI Workflow Hardening** (shipped in `0.13.0`): Pixel Quiver dogfooding follow-up covering resolver/export/spec-create/AI-artifact/worktree/validation/context/DX hardening lives in `specs/quiver-v27-reliability-ai-workflow-hardening/`.
+- **v28 — Pixel Quiver Feedback Reconciliation** (shipped in `0.14.0`): active-slice reconciliation, stale inspect recovery, structured review closure, validation/worktree hardening, agent-safe commands, GitHub auth guidance, and release-readiness evidence live in `specs/quiver-v28-pixel-quiver-feedback-reconciliation/`.
 
 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

@@ -30,6 +30,7 @@ This document is the canonical command reference for the orchestration roadmap.
 | `npx create-quiver ai inspect` | Shows actionable lifecycle state for specs, slices, runs, agents, layout, and next commands | macOS, Linux, Windows | v0.13 | `npx create-quiver ai inspect` |
 | `npx create-quiver ai export --format json` | Emits machine-readable specs, slices, runs, agents, dependencies, blockers, and migration state | macOS, Linux, Windows | v0.13 | `npx create-quiver ai export --format json` |
 | `npx create-quiver ai export --format markdown` | Emits readable Markdown lifecycle state for PRs or docs | macOS, Linux, Windows | v0.13 | `npx create-quiver ai export --format markdown` |
+| `npx create-quiver ai active-slice reconcile --dry-run` | Reports active-slice state from supported local sources and previews preserve, close, replace, or blocked reconciliation decisions without writing files | macOS, Linux, Windows | next | `npx create-quiver ai active-slice reconcile --dry-run` |
 | `npx create-quiver ai specs list` | Lists specs with state, progress, slice counts, and paths | macOS, Linux, Windows | v0.13 | `npx create-quiver ai specs list` |
 | `npx create-quiver ai slices list` | Lists slices with state, progress, dependencies, and blockers | macOS, Linux, Windows | v0.13 | `npx create-quiver ai slices list --json` |
 | `npx create-quiver ai trace report` | Reports AI runs, execution waves, and migration guidance | macOS, Linux, Windows | v0.13 | `npx create-quiver ai trace report` |
@@ -124,8 +125,9 @@ This document is the canonical command reference for the orchestration roadmap.
 - `quiver:ai:agent` stores provider/model labels under `.quiver/agents/profiles.json`; credentials stay in the provider CLI or OS credential store.
 - `quiver:ai:inspect`, `quiver:ai:specs`, `quiver:ai:slices`, and `quiver:ai:trace` are read-only inspection surfaces for humans and agents.
 - `quiver:ai:export -- --format json` is the dashboard/agent-friendly state contract; `--format markdown` is the PR/docs-friendly version.
-- Planner drafts are versioned under `.quiver/approvals/<phase>/drafts/`; use `quiver:ai:review-plan -- --dry-run` before approving a technical-plan draft, then `quiver:ai:approve -- --phase technical-plan --version 1` to approve the reviewed version.
+- Planner drafts are versioned under `.quiver/approvals/<phase>/drafts/`; use `quiver:ai:review-plan -- --dry-run` before approving a technical-plan draft, then `quiver:ai:approve -- --phase technical-plan --version 1` to approve the reviewed version. Plan reviews store structured recommendations: `approve`, `approve-with-risk`, or `revise`.
 - `quiver:ai:prompt-slice -- --dry-run` prints a paste-ready manual executor prompt and does not call a provider.
+- For commands pasted into another AI agent, prefer a non-interactive pinned form such as `npx --yes create-quiver@<version> ai prompt-slice --slice specs/<spec>/slices/<slice>/slice.json --dry-run`.
 - `quiver:evidence -- run -- <command>` preserves the wrapped command exit code. Redaction is best effort; avoid commands that intentionally print secrets.
 - `demo create spec-viewer` is optional and static; it must stay outside default `init`.
 - `quiver:spec:start -- --dry-run specs/<spec>` previews the spec worktree path and branch without creating a worktree.

package/docs/TROUBLESHOOTING.md.template

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

package/docs/WORKFLOW.md.template

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-quiver",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "private": false,
   "description": "Quiver CLI for scaffolding projects from the packaged template",
   "license": "MIT",

package/specs/quiver-v28-pixel-quiver-feedback-reconciliation/COVERAGE_MATRIX.md

@@ -0,0 +1,117 @@
+# Coverage Matrix - Quiver v28 Pixel Quiver Feedback Reconciliation
+
+`slice-00` completed the evidence freeze on 2026-05-25. This matrix replaces the initial planning hypothesis and is the execution contract for the remaining slices.
+
+Status meanings used during this spec:
+
+- `verified-resolved`: current repo evidence shows enough code, test, or doc coverage; no v28 implementation should repeat it.
+- `partial`: current repo covers part of the issue, but Pixel Quiver evidence still exposes a gap or missing regression guard.
+- `pending`: no sufficient current coverage was found; implement in the mapped v28 slice.
+- `duplicate`: tracked through another finding.
+- `documented-risk`: not fixed in this slice; must remain visible until closure.
+- `out-of-scope-with-reason`: intentionally excluded from v28 with a reason.
+
+## Frozen Inputs
+
+| Source | Unique IDs | SHA-256 | Modified |
+|---|---:|---|---|
+| Pixel Quiver `QUIVER_PROBLEMS.md` | `QP-001` to `QP-028` | `516d8928af437fc3d20cacfe50fb78752954eb59b6dace6860cdda820aa6701d` | 2026-05-25 03:29:24 -03 |
+| Pixel Quiver `QUIVER_IMPROVEMENT_SUGGESTIONS.md` | `QIS-001` to `QIS-031` | `43c4bfbef68fc8343b7f905f299c53716b55abcace415c9ce1088aa53ac12949` | 2026-05-25 03:29:39 -03 |
+| Pixel Quiver `QUIVER_FRAMEWORK_IMPROVEMENTS.md` | narrative sections only | `7a4eb66a996fc44cce80df4907a948fbef3e780a5f8fc856a6bdc2b0bd1f1ea3` | 2026-05-25 03:29:53 -03 |
+
+## Problem Coverage
+
+| Finding | Status | Primary slice | Evidence | Required action |
+|---|---|---|---|---|
+| QP-001 | verified-resolved | slice-00 | v27 matrix maps flow freshness to slice-07; `tests/commands/flow.test.js`; `src/create-quiver/commands/flow.js`. | Do not reimplement. |
+| QP-002 | fixed | slice-05 | v27 path handling remains, and help/docs now include non-interactive `npx --yes create-quiver@<version>` examples for agents. | Completed in slice-05. |
+| QP-003 | fixed | slice-03 | `collectLifecycleExport` now includes active-slice state, uses shared resolver data, and `ai inspect` next steps reconcile existing specs before suggesting stale creation. Covered by `tests/lib/ai-export-state.test.js` and `tests/commands/ai-export.test.js`. | Completed in slice-03. |
+| QP-004 | fixed | slice-05 | GitHub install/auth/alias guidance now includes account/scope/alias diagnosis plus macOS, Linux, Windows PowerShell, Git Bash, and WSL recovery copy. Covered by `tests/lib/ai-github.test.js`. | Completed in slice-05. |
+| QP-005 | verified-resolved | slice-00 | v27 matrix maps React/Vite analyzer detection to slice-07; `tests/commands/analyze.test.js`; `tests/fixtures/validation-errors/matrix.json`. | Do not reimplement unless a new failing fixture appears. |
+| QP-006 | verified-resolved | slice-00 | v27 matrix maps evidence-backed `prepare-context` to slice-07; `README_FOR_AI.md`; `docs/PROJECT_MAP.md` contract in templates. | Do not reimplement. |
+| QP-007 | verified-resolved | slice-00 | v27 matrix maps agent docs gaps to slice-07/slice-08; generated templates include current docs instead of missing `docs/ai/QUICK.md` style paths. | Do not reimplement. |
+| QP-008 | verified-resolved | slice-00 | v27 status is 100%; v27 evidence says source-of-truth docs were synchronized; `README_FOR_AI.md` documents v27 coverage. | Do not reimplement. |
+| QP-009 | verified-resolved | slice-00 | `src/create-quiver/lib/ai/artifacts.js`; `tests/commands/ai-plan.test.js`; v27 slice-04 closure covers revise compaction. | Do not reimplement. |
+| QP-010 | fixed | slice-01 | `src/create-quiver/commands/ai.js`; `tests/commands/ai-plan.test.js` covers clean console output without prompt echo/stderr logs while raw artifacts remain persisted. | Completed in slice-01. |
+| QP-011 | fixed | slice-02 | `ai plan --phase technical-plan` prompts for the required `spec.slices[]` contract; `ai approve --phase technical-plan` blocks invalid drafts before writing approved artifacts; `spec create` still fails before writes for legacy invalid approvals. | Completed in slice-02. |
+| QP-012 | verified-resolved | slice-00 | `tests/lib/ai-spec-generator.test.js` covers fail-before-writing and no build remnants. | Do not reimplement. |
+| QP-013 | fixed | slice-01 | `ai status` reports multiple open runs; `ai run close --run <id>` archives stale runs without deleting evidence; covered by `tests/commands/ai-run-state.test.js`. | Completed in slice-01. |
+| QP-014 | fixed | slice-01 | Provider-backed `ai onboard`, `ai plan`, and `ai review-plan` print clean output on success; raw output is only printed on provider failure. Covered by focused `ai plan` test. | Completed in slice-01. |
+| QP-015 | fixed | slice-01 | `ai approvals` now separates run-scoped approvals, active run, global planner approvals, and run relation (`active`, `historical`, `orphaned`, `none`). | Completed in slice-01. |
+| QP-016 | fixed | slice-03 | Added active-source detection for `docs/ai/ACTIVE_SLICE.md` and `ACTIVE_SLICES.md`, conflict detection, and `ai active-slice reconcile --dry-run`. Covered by resolver and CLI tests. | Completed in slice-03. |
+| QP-017 | fixed | slice-05 | `ai review-plan` now stores structured `review_result` metadata with approval recommendation, blocking status, required fixes, optional hardening, risks, and next command. | Completed in slice-05. |
+| QP-018 | fixed | slice-05 | Stale technical-plan review approval errors now recommend dry-run review followed by live review, and blocking review results surface the exact next command. | Completed in slice-05. |
+| QP-019 | fixed | slice-05 | Review closure now distinguishes `approve`, `approve-with-risk`, and `revise`, with required fixes blocking approval and optional hardening remaining non-blocking. | Completed in slice-05. |
+| QP-020 | fixed | slice-03 | `collectActiveSliceState` defines supported sources and canonical dry-run decisions: `preserve`, `close`, `replace`, and `blocked`. | Completed in slice-03. |
+| QP-021 | fixed | slice-05 | Review metadata separates `required_fixes` from `optional_hardening`, and approval checks block only revise/blocking results. | Completed in slice-05. |
+| QP-022 | fixed | slice-03 | Added `npx create-quiver ai active-slice status|reconcile`; `reconcile` is dry-run-first and refuses live writes. | Completed in slice-03. |
+| QP-023 | fixed | slice-02 | Technical-plan approval now validates that the selected draft can generate a spec package before approving it. | Completed in slice-02. |
+| QP-024 | fixed | slice-02 | Added `ai repair-plan` to create a provider-backed derived structured draft from a legacy approved invalid technical plan while preserving the original approved artifact. | Completed in slice-02. |
+| QP-025 | fixed | slice-04 | `spec validate` now rejects slices missing execution git metadata required by `check-slice --local`; covered by `tests/commands/spec-validate.test.js`. | Completed in slice-04. |
+| QP-026 | fixed | slice-04 | `spec status` now reports expected worktree paths that exist but are not registered in `git worktree list` as missing/stale; covered by `tests/commands/spec-worktree.test.js`. | Completed in slice-04. |
+| QP-027 | fixed | slice-04 | `spec start --dry-run` dirty checkout failures now list dirty files and safe recovery options; covered by `tests/commands/spec-worktree.test.js`. | Completed in slice-04. |
+| QP-028 | fixed | slice-03 | `ai inspect` detects existing specs when an active run still points at `spec create --dry-run` and now suggests `spec validate`, `next --all-ready`, and `ai prompt-slice`. | Completed in slice-03. |
+
+## Suggestion Coverage
+
+| Finding | Status | Primary slice | Evidence | Required action |
+|---|---|---|---|---|
+| QIS-001 | verified-resolved | slice-00 | v27 flow source/freshness coverage; `tests/commands/flow.test.js`. | Do not reimplement. |
+| QIS-002 | fixed | slice-05 | Agent examples now include `npx --yes create-quiver@<version>` and existing shell-safe copy remains covered. | Completed in slice-05. |
+| QIS-003 | fixed | slice-04 | `spec validate` now catches missing execution git metadata before users reach local slice execution. | Completed in slice-04. |
+| QIS-004 | verified-resolved | slice-00 | `src/create-quiver/lib/ai/export-state.js` exposes schema v2 dashboard data. | Do not reimplement unless schema gaps appear. |
+| QIS-005 | fixed | slice-05 | Executor context pack guidance now explicitly limits agents to `slice.json`, `EXECUTION_BRIEF`, `CLOSURE_BRIEF`, allowed files, acceptance criteria, and validation commands; docs include non-interactive prompt-slice examples. | Completed in slice-05. |
+| QIS-006 | fixed | slice-03 | `ai inspect`, `ai export`, active-slice status, spec listing, and slice listing share resolver-backed lifecycle export data. | Completed in slice-03. |
+| QIS-007 | verified-resolved | slice-00 | v27 analyzer coverage and fixtures. | Do not reimplement. |
+| QIS-008 | verified-resolved | slice-00 | v27 context evidence coverage and source-backed docs contract. | Do not reimplement. |
+| QIS-009 | fixed | slice-05 | GitHub preflight guidance now includes shell-specific `gh` installation and SSH alias setup/verification copy. | Completed in slice-05. |
+| QIS-010 | verified-resolved | slice-00 | v27 agent docs/template cleanup. | Do not reimplement. |
+| QIS-011 | verified-resolved | slice-00 | `tests/commands/ai-agent.test.js` covers `ai agent set --dry-run`. | Do not reimplement. |
+| QIS-012 | verified-resolved | slice-00 | v27 artifact compaction tests and `src/create-quiver/lib/ai/artifacts.js`. | Do not reimplement. |
+| QIS-013 | fixed | slice-01 | Clean/raw persistence remains, and console output no longer emits provider transcript/logs on successful planner commands. | Completed in slice-01. |
+| QIS-014 | fixed | slice-02 | Structured technical-plan output is now required in planner prompts and enforced before technical-plan approval/spec creation. | Completed in slice-02. |
+| QIS-015 | fixed | slice-02 | Existing generator regressions continue to cover slug/title normalization, collision refusal, multi-slice preservation, and structured markdown extraction while the shared contract validator was added. | Completed in slice-02. |
+| QIS-016 | fixed | slice-01 | `ai status` exposes other open runs and `ai run close --run <id>` provides a safe archive path. | Completed in slice-01. |
+| QIS-017 | fixed | slice-01 | Successful provider-backed planner commands print clean output only; raw logs remain stored/redacted. | Completed in slice-01. |
+| QIS-018 | fixed | slice-01 | `ai approvals` groups active/historical run-scoped approvals separately from global approval files. | Completed in slice-01. |
+| QIS-019 | fixed | slice-03 | Added `ai active-slice status|reconcile` with multi-source reporting and dry-run output. | Completed in slice-03. |
+| QIS-020 | fixed | slice-05 | `summarizePlanReview` now reports approval recommendation, blocking status, required fixes, optional hardening, and next command. | Completed in slice-05. |
+| QIS-021 | fixed | slice-05 | `meta.json` stores machine-readable `review_result` data for downstream agents and gates. | Completed in slice-05. |
+| QIS-022 | fixed | slice-03 | Added canonical multi-source active-slice reconciliation from active doc plus root board. | Completed in slice-03. |
+| QIS-023 | fixed | slice-05 | CLI help, README, README_FOR_AI, and generated command docs now include `npx --yes create-quiver@<version>` guidance for agent-pasted commands. | Completed in slice-05. |
+| QIS-024 | fixed | slice-05 | Review close threshold is now `approve`, `approve-with-risk`, or `revise`; `revise` and blocking required fixes prevent technical-plan approval. | Completed in slice-05. |
+| QIS-025 | fixed | slice-03 | `ai active-slice reconcile --dry-run` reports supported sources, detected sources, planned changes, risks, and no-write guarantee. | Completed in slice-03. |
+| QIS-026 | fixed | slice-02 | Missing `spec.slices[]` is now caught before approval and before spec creation. | Completed in slice-02. |
+| QIS-027 | fixed | slice-02 | `ai repair-plan` provides a traceable repair path for approved legacy plans missing structure. | Completed in slice-02. |
+| QIS-028 | fixed | slice-04 | `spec validate` enforces local execution metadata parity with focused regression coverage. | Completed in slice-04. |
+| QIS-029 | fixed | slice-04 | `spec status` detects unregistered expected worktree directories and reports them as stale. | Completed in slice-04. |
+| QIS-030 | fixed | slice-04 | Dirty checkout recovery now includes blocking files and safe options. | Completed in slice-04. |
+| QIS-031 | fixed | slice-03 | `collectNextSteps` now prefers existing-spec recovery commands over stale lifecycle `spec create` guidance. | Completed in slice-03. |
+
+## Framework Improvement Sections
+
+| Area from Pixel Quiver improvement file | Status | Primary slice | Evidence | Required action |
+|---|---|---|---|---|
+| Intent/spec selection before a spec exists | fixed | slice-03 | `ai inspect` now reconciles existing specs and ready slices before suggesting another spec creation path. | Completed in slice-03 without adding a separate intent system. |
+| Local vs latest Quiver version visibility | documented-risk | slice-06 | README now states the package remains `0.13.0` and v28 changes are unreleased until future publication; package smoke ran against the local package artifact without claiming npm publish. | Future work: consider `status --versions`. |
+| Standard names for improvement files | documented-risk | slice-06 | v28 preserved the three Pixel Quiver evidence files as explicit source inputs and frozen hashes in this matrix/evidence report. | Future work: document accepted feedback filenames and aliases. |
+| Graph conflicts summary | out-of-scope-with-reason | slice-06 | Useful but not required for the AI lifecycle failures in v28. | Record as future graph UX work. |
+| Visual validation command | out-of-scope-with-reason | slice-06 | Valuable for frontend projects, but would require browser tooling and a larger product decision. | Record as future visual evidence feature. |
+| Active run management | fixed | slice-01 | `ai status` surfaces multiple open runs; `ai run close --run <id>` closes stale runs while preserving `.quiver/runs/<id>`. | Completed in slice-01. |
+| Clean AI output | fixed | slice-01 | Successful provider-backed planner commands now print clean extracted output instead of raw stdout/stderr. | Completed in slice-01. |
+| Active slice reconciliation | fixed | slice-03 | Matches QP-016/QP-020/QIS-019/QIS-022/QIS-025; implemented through resolver state and `ai active-slice` CLI. | Completed in slice-03. |
+| Structured plan/spec create | fixed | slice-02 | Matches QP-011, QP-023, QP-024, QIS-014, QIS-015, QIS-026, and QIS-027; validated by approval, repair, spec-create, and generator tests. | Completed in slice-02. |
+| Worktree and validation hardening | fixed | slice-04 | Matches QP-025 to QP-027 and QIS-028 to QIS-030; validated by spec validation, worktree, check-slice, scope, and path tests. | Completed in slice-04. |
+| Review-plan closure | fixed | slice-05 | Matches QP-017/QP-019/QP-021 and QIS-020/QIS-021/QIS-024; implemented with structured review metadata and approval gating. | Completed in slice-05. |
+| Agent-safe `npx --yes create-quiver@<version>` examples | fixed | slice-05 | Matches QIS-023 and Pixel command log; help/docs now include non-interactive pinned examples for agents. | Completed in slice-05. |
+| GitHub auth/alias guidance | fixed | slice-05 | Matches QP-004/QIS-009; guidance and tests cover gh install/auth plus SSH alias setup across supported shells. | Completed in slice-05. |
+| Package contents safety | fixed | slice-06 | `npm pack --dry-run` first showed `Quiver_Spec_Viewer_requisitos.pdf` would be included. `.npmignore` now excludes `*.pdf`, and the follow-up JSON dry-run confirmed no PDF files in the package. | Completed in slice-06. |
+
+## Execution Decisions
+
+- `slice-01` and `slice-04` are completed after `slice-00`.
+- `slice-02`, `slice-03`, and `slice-04` are completed after `slice-01`.
+- `slice-05` is completed after `slice-01`; `slice-06` owns final compatibility, docs sync, smoke, and release readiness.
+- Graph conflict summaries and visual validation commands are kept as documented future work, not v28 blocking implementation.
+- No product code was modified by `slice-00`.
+- `slice-06` did not publish npm or open a PR; it only established source and package-readiness evidence.

package/specs/quiver-v28-pixel-quiver-feedback-reconciliation/EVIDENCE_REPORT.md

@@ -0,0 +1,200 @@
+# Evidence Report - Quiver v28 Pixel Quiver Feedback Reconciliation
+
+## slice-00-reconciliation-and-evidence-freeze
+
+Completed on 2026-05-25.
+
+### Source Evidence Frozen
+
+The following Pixel Quiver files were treated as evidence inputs only. They were not copied into fixtures.
+
+| Source | SHA-256 | Modified |
+|---|---|---|
+| `/Users/fabrijk/Documents/Work/Proyectos Personales/nika/Pixel Quiver/QUIVER_PROBLEMS.md` | `516d8928af437fc3d20cacfe50fb78752954eb59b6dace6860cdda820aa6701d` | 2026-05-25 03:29:24 -03 |
+| `/Users/fabrijk/Documents/Work/Proyectos Personales/nika/Pixel Quiver/QUIVER_IMPROVEMENT_SUGGESTIONS.md` | `43c4bfbef68fc8343b7f905f299c53716b55abcace415c9ce1088aa53ac12949` | 2026-05-25 03:29:39 -03 |
+| `/Users/fabrijk/Documents/Work/Proyectos Personales/nika/Pixel Quiver/QUIVER_FRAMEWORK_IMPROVEMENTS.md` | `7a4eb66a996fc44cce80df4907a948fbef3e780a5f8fc856a6bdc2b0bd1f1ea3` | 2026-05-25 03:29:53 -03 |
+
+Detected IDs:
+
+- `QP-001` to `QP-028`
+- `QIS-001` to `QIS-031`
+- Narrative framework-improvement sections without stable IDs
+
+### Repository Evidence Inspected
+
+- `README_FOR_AI.md`
+- `ROADMAP.md`
+- `BACKLOG.md`
+- `CHANGELOG.md`
+- `specs/quiver-v27-reliability-ai-workflow-hardening/COVERAGE_MATRIX.md`
+- `specs/quiver-v27-reliability-ai-workflow-hardening/STATUS.md`
+- `specs/quiver-v27-reliability-ai-workflow-hardening/EVIDENCE_REPORT.md`
+- `src/create-quiver/commands/spec.js`
+- `src/create-quiver/commands/ai.js`
+- `src/create-quiver/lib/ai/run-state.js`
+- `src/create-quiver/lib/ai/export-state.js`
+- `src/create-quiver/lib/ai/plan-review.js`
+- `src/create-quiver/lib/approvals.js`
+- `src/create-quiver/lib/spec-worktrees.js`
+- `src/create-quiver/lib/lifecycle.js`
+- Focused tests under `tests/commands/*` and `tests/lib/*`
+
+### Reconciliation Outcome
+
+- v27 is documented as complete and covers many earlier findings (`QP-001` to `QP-019`, `QIS-001` to `QIS-022`), but several later Pixel Quiver findings expose gaps that v27 either did not intend to solve or only partially solved.
+- Confirmed no product-code change is required for `slice-00`.
+- The final execution mapping is now captured in `COVERAGE_MATRIX.md`.
+- `slice-01` and `slice-04` are the only implementation slices ready immediately after `slice-00`.
+
+## Final Release-Readiness Evidence
+
+`slice-06` completed the pending final checks for source compatibility, generated docs, smoke coverage, and package contents.
+
+## Validation Evidence for slice-00
+
+Passed:
+
+- `git diff --check`
+- JSON parse validation for all v28 `slice.json` files
+- `node bin/create-quiver.js spec validate specs/quiver-v28-pixel-quiver-feedback-reconciliation`
+- `node bin/create-quiver.js spec validate specs/quiver-v28-pixel-quiver-feedback-reconciliation --strict`
+- `node bin/create-quiver.js check-slice --local specs/quiver-v28-pixel-quiver-feedback-reconciliation/slices/slice-00-reconciliation-and-evidence-freeze/slice.json`
+- `node bin/create-quiver.js next --all-ready --spec quiver-v28-pixel-quiver-feedback-reconciliation`
+- `node bin/create-quiver.js plan --spec quiver-v28-pixel-quiver-feedback-reconciliation --json`
+
+Ready slices reported after `slice-00`:
+
+- `slice-01-ai-run-state-approvals-and-clean-output`
+- `slice-04-spec-validation-scope-and-worktree-reliability`
+
+## slice-01-ai-run-state-approvals-and-clean-output
+
+Completed on 2026-05-25.
+
+### Implementation Evidence
+
+- Updated `src/create-quiver/commands/ai.js` so successful provider-backed planner commands print clean extracted output instead of raw stdout/stderr.
+- Preserved raw provider artifact persistence and redaction for `ai plan` and `ai review-plan`.
+- Updated `ai approvals` output to separate run-scoped approvals, active run, global planner approvals, and run relation.
+- Added `ai run close --run <id>` to close/archive stale runs without deleting `.quiver/runs/<id>` evidence.
+- Updated `src/create-quiver/lib/ai/run-state.js` so `ai status` reports the number of open runs and lists other open runs with next safe commands.
+
+### Validation Evidence
+
+Passed:
+
+- `node --test tests/commands/ai-run-state.test.js tests/commands/ai-plan.test.js tests/commands/ai-export.test.js tests/commands/cli-contract.test.js`
+- `node --test tests/lib/ai-run-state.test.js tests/lib/approvals.test.js tests/lib/ai-export-state.test.js`
+
+## slice-04-spec-validation-scope-and-worktree-reliability
+
+Completed on 2026-05-25.
+
+### Implementation Evidence
+
+- Updated `src/create-quiver/commands/spec.js` so `spec validate` rejects slices missing execution git metadata required by local slice execution: `git.branch_type`, `git.base_branch`, `git.branch_slug`, and `git.branch_name`.
+- Updated `src/create-quiver/lib/spec-worktrees.js` so `spec status` reports expected worktree paths that exist on disk but are not registered in `git worktree list` as missing/stale.
+- Updated dirty checkout failures in `spec start --dry-run` to list blocking dirty files and safe recovery options without modifying state.
+- Added regression coverage for exact path plus supported glob scope matching.
+
+### Validation Evidence
+
+Passed:
+
+- `node --test tests/commands/spec-validate.test.js tests/commands/spec-worktree.test.js`
+- `node --test tests/lib/check-slice.test.js tests/lib/scope.test.js tests/lib/paths.test.js`
+
+## slice-02-structured-technical-plan-contract-and-repair-flow
+
+Completed on 2026-05-25.
+
+### Implementation Evidence
+
+- Updated `src/create-quiver/commands/ai.js` so technical-plan prompts require a fenced structured JSON contract with `spec.slices[]`.
+- Added approval-time validation for `ai approve --phase technical-plan` so invalid drafts fail before `approved.md` is written.
+- Added `ai repair-plan` to repair legacy approved technical plans missing `spec.slices[]` into a new provider-backed draft without mutating the approved artifact.
+- Added shared `validateTechnicalPlanSpecContract` in `src/create-quiver/lib/ai/spec-generator.js`.
+- Updated CLI help and dispatch so `ai repair-plan --dry-run` and `--print-prompt` are first-class commands.
+
+### Validation Evidence
+
+Passed:
+
+- `node --test tests/commands/ai-plan.test.js tests/commands/ai-plan-spec-phase.test.js tests/commands/spec-create.test.js`
+- `node --test tests/commands/ai-review-plan.test.js tests/commands/flow.test.js tests/commands/cli-contract.test.js`
+- `node --test tests/lib/ai-spec-generator.test.js tests/lib/approvals.test.js`
+
+## slice-03-active-slice-reconciliation-and-ai-inspect
+
+Completed on 2026-05-25.
+
+### Implementation Evidence
+
+- Added resolver-backed active-slice source collection for `docs/ai/ACTIVE_SLICE.md` and `ACTIVE_SLICES.md`.
+- Added canonical reconciliation decisions: `preserve`, `close`, `replace`, and `blocked`.
+- Added `ai active-slice status|reconcile` with dry-run-first behavior; live reconcile currently refuses writes.
+- Updated `ai inspect`/lifecycle export so existing specs take precedence over stale `spec create --dry-run` lifecycle guidance.
+- Added active-slice state to lifecycle export summary, dashboard data, blockers, and human inspect output.
+- Hardened `ACTIVE_SLICES.md` table parsing so Markdown separator rows are ignored.
+
+### Validation Evidence
+
+Passed:
+
+- `node --test tests/commands/ai-export.test.js tests/commands/cli-contract.test.js`
+- `node --test tests/lib/project-state-resolver.test.js tests/lib/ai-export-state.test.js`
+
+## slice-05-review-plan-closure-and-agent-dx
+
+Completed on 2026-05-25.
+
+### Implementation Evidence
+
+- Added structured `review_result` metadata to saved plan reviews with `approve`, `approve-with-risk`, and `revise` recommendations.
+- Updated the review prompt to require a fenced JSON review contract.
+- Updated `ai approve --phase technical-plan` to block reviews with required fixes or `revise` recommendation.
+- Updated `ai approvals`/plan-review summary to include approval recommendation, blocking status, required fixes, optional hardening, and next command.
+- Updated executor context-pack guidance to avoid full-spec context unless explicitly required.
+- Added shell-specific GitHub CLI install and SSH alias setup guidance for macOS, Linux, Windows PowerShell, Git Bash, and WSL.
+- Added agent-facing non-interactive `npx --yes create-quiver@<version>` examples to help and docs.
+
+### Validation Evidence
+
+Passed:
+
+- `node --test tests/commands/ai-review-plan.test.js tests/commands/cli-contract.test.js`
+- `node --test tests/lib/ai-context-packs.test.js tests/lib/ai-github.test.js`
+
+## slice-06-backward-compatibility-docs-and-release-readiness
+
+Completed on 2026-05-25.
+
+### Implementation Evidence
+
+- Updated `CHANGELOG.md` with unreleased v28 additions, changes, and fixes without claiming npm publication.
+- Updated `ROADMAP.md` so v28 is visible as an unreleased reconciliation/release-readiness milestone.
+- Updated `README.md`, `docs/WORKFLOW.md.template`, and `docs/TROUBLESHOOTING.md.template` to match implemented review-plan, active-slice, and pinned agent-command behavior.
+- Expanded `slice-06` scope to include `.npmignore` after package dry-run evidence showed a local requirements PDF would otherwise be included in the npm tarball.
+- Updated `.npmignore` to exclude local `*.pdf` files from published packages.
+
+### Validation Evidence
+
+Passed:
+
+- `node --test tests/**/*.test.js` (`376` tests passed)
+- `npm run smoke:doctor-fixtures` (`13` doctor fixture states passed)
+- `npm run smoke:guided-workflow`
+- `npm run smoke:create-quiver`
+- `npm run package:quiver`
+- `npm pack --dry-run --json` with a follow-up assertion that no `.pdf` files are included (`543` files)
+- `git diff --check`
+- `node bin/create-quiver.js spec validate specs/quiver-v28-pixel-quiver-feedback-reconciliation --strict`
+- `node bin/create-quiver.js check-slice --local specs/quiver-v28-pixel-quiver-feedback-reconciliation/slices/slice-06-backward-compatibility-docs-and-release-readiness/slice.json`
+- `node bin/create-quiver.js next --all-ready --spec quiver-v28-pixel-quiver-feedback-reconciliation`
+
+### Release Notes
+
+- npm publication was not performed.
+- PR creation was not performed.
+- `package.json` version remains `0.13.0`.
+- Pre-fix package evidence showed `Quiver_Spec_Viewer_requisitos.pdf` would be packed. The file was left in the working tree and excluded through `.npmignore`.

package/specs/quiver-v28-pixel-quiver-feedback-reconciliation/EXECUTION_PLAN.md

@@ -0,0 +1,60 @@
+# Execution Plan - Quiver v28 Pixel Quiver Feedback Reconciliation
+
+## Execution Order
+
+```mermaid
+flowchart TD
+    S00[slice-00: Reconciliation and evidence freeze]
+    S01[slice-01: AI run state, approvals, and clean output]
+    S02[slice-02: Structured technical plan contract and repair flow]
+    S03[slice-03: Active slice reconciliation and AI inspect]
+    S04[slice-04: Spec validation, scope, and worktree reliability]
+    S05[slice-05: Review-plan closure and agent DX]
+    S06[slice-06: Backward compatibility, docs, and release readiness]
+
+    S00 --> S01
+    S00 --> S04
+    S01 --> S02
+    S01 --> S03
+    S01 --> S05
+    S02 --> S06
+    S03 --> S06
+    S04 --> S06
+    S05 --> S06
+```
+
+## Waves
+
+### Wave 0 - Sequential
+
+1. `slice-00-reconciliation-and-evidence-freeze`
+
+This slice must run first. It decides what is already resolved, what is pending, and what must not be reimplemented.
+
+### Wave 1 - Parallel after slice-00
+
+- `slice-01-ai-run-state-approvals-and-clean-output`
+- `slice-04-spec-validation-scope-and-worktree-reliability`
+
+These can run in parallel because their primary write scopes are different.
+
+### Wave 2 - Parallel after slice-01
+
+- `slice-02-structured-technical-plan-contract-and-repair-flow`
+- `slice-03-active-slice-reconciliation-and-ai-inspect`
+- `slice-05-review-plan-closure-and-agent-dx`
+
+These depend on the run/approval model being clarified.
+
+### Wave 3 - Sequential close
+
+1. `slice-06-backward-compatibility-docs-and-release-readiness`
+
+This slice must run last because it validates compatibility, docs, package smoke, and final coverage.
+
+## Parallel Safety Notes
+
+- Do not run slices in parallel if `slice-00` finds that their write scopes overlap more than currently expected.
+- `slice-02` and `slice-05` may both touch planning prompts; if `slice-00` identifies overlap, run `slice-02` before `slice-05`.
+- `slice-06` is never parallel-safe.
+