create-quiver 0.12.1 → 0.14.0

package/specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-09-fixtures-smoke-docs-and-release-readiness/slice.json

@@ -0,0 +1,91 @@
+{
+  "slice_id": "slice-09-fixtures-smoke-docs-and-release-readiness",
+  "ticket": "QUIVER-27-09",
+  "type": "validation",
+  "title": "Fixtures, smoke, docs, and release readiness",
+  "objective": "Validate the full v27 hardening package with sanitized fixtures, local tests, smoke tests, tarball/package validation, and source-of-truth docs.",
+  "description": "Adds final regression fixtures from real dogfooding, runs full local and package smokes, synchronizes docs, records evidence, and confirms release readiness without publishing npm.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v27-fixtures-smoke-docs-release-readiness",
+    "branch_name": "feature/QUIVER-27-09-fixtures-smoke-docs-release-readiness"
+  },
+  "files": [
+    "README.md",
+    "README_FOR_AI.md",
+    "ROADMAP.md",
+    "CHANGELOG.md",
+    "tests/**",
+    "scripts/**",
+    "specs/quiver-v27-reliability-ai-workflow-hardening/**"
+  ],
+  "expected_read_paths": [
+    "README.md",
+    "README_FOR_AI.md",
+    "ROADMAP.md",
+    "CHANGELOG.md",
+    "package.json",
+    "scripts/package-quiver.sh",
+    "scripts/ci/**",
+    "tests/**",
+    "specs/quiver-v27-reliability-ai-workflow-hardening/**"
+  ],
+  "allowed_write_paths": [
+    "README.md",
+    "README_FOR_AI.md",
+    "ROADMAP.md",
+    "CHANGELOG.md",
+    "tests/**",
+    "scripts/**",
+    "specs/quiver-v27-reliability-ai-workflow-hardening/**"
+  ],
+  "depends_on": [
+    "slice-02-json-export-contract-and-machine-output",
+    "slice-03-approved-plan-to-spec-create",
+    "slice-04-ai-artifact-storage-redaction-and-token-compaction",
+    "slice-05-worktree-lifecycle-locks-and-recovery",
+    "slice-06-validation-gates-and-scope-safety",
+    "slice-07-context-analysis-and-doctor-flow",
+    "slice-08-cross-platform-help-auth-and-dx"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Final validation and docs sync must run after all implementation slices.",
+  "must": [
+    "Add sanitized fixtures that represent real dogfooding failures.",
+    "Run full command and lib tests.",
+    "Run smoke suites.",
+    "Run package/tarball smoke from outside the repo.",
+    "Update source-of-truth docs only with implemented behavior.",
+    "Record release readiness evidence without publishing."
+  ],
+  "not_included": [
+    "Publishing npm.",
+    "Opening PR unless requested.",
+    "Adding unsanitized local paths or credentials."
+  ],
+  "acceptance": [
+    "All v27 QP/QIS coverage items are either fixed, validated, or documented as remaining risk.",
+    "Sanitized fixtures cover Pixel Quiver completed specs, path with spaces, no Git, old .quiver state, multiple specs, and stale docs.",
+    "node --test tests/**/*.test.js passes.",
+    "smoke:create-quiver, smoke:guided-workflow, and smoke:doctor-fixtures pass or documented blockers are resolved.",
+    "Package/tarball smoke validates installed CLI behavior rather than only source code.",
+    "README, README_FOR_AI, ROADMAP, and CHANGELOG are synchronized with actual implementation state."
+  ],
+  "tests": [
+    "node --test tests/**/*.test.js",
+    "npm run smoke:create-quiver",
+    "npm run smoke:guided-workflow",
+    "npm run smoke:doctor-fixtures",
+    "npm run package:quiver",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Run package smoke from /private/tmp or another clean directory.",
+    "Confirm fixtures do not contain private tokens or unnecessary personal paths."
+  ],
+  "estimated_hours": 5,
+  "status": "completed",
+  "completed_at": "2026-05-24",
+  "blocked_reason": null
+}

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.
+

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

@@ -0,0 +1,132 @@
+# Quiver v28 - Pixel Quiver Feedback Reconciliation
+
+**Date:** 2026-05-25
+**Status:** Completed
+**Source:** Pixel Quiver dogfooding follow-up after `create-quiver@0.13.0`
+
+Slice numbering resets here. This spec intentionally starts at `slice-00`.
+
+## Problem
+
+Pixel Quiver produced a second set of framework feedback after Quiver v27 shipped in `create-quiver@0.13.0`. The repository source of truth says v27 already covered `QP-001` to `QP-019` and `QIS-001` to `QIS-022`, but the Pixel Quiver files still list several of those items as open and add later issues around `spec create`, repair flows, active-slice reconciliation, worktrees, and `ai inspect`.
+
+The risk is implementing duplicate fixes or missing regressions. Quiver needs a reconciliation-first spec that verifies what v27 truly covers, then fixes only the remaining, partial, regressed, or newly observed gaps.
+
+## Objective
+
+Reconcile Pixel Quiver feedback against the current Quiver implementation, then harden the unresolved workflow gaps across AI runs, approvals, structured technical plans, active-slice state, spec validation, worktrees, plan reviews, agent DX, documentation, and release readiness.
+
+## Evidence Sources
+
+Primary input files:
+
+- `/Users/fabrijk/Documents/Work/Proyectos Personales/nika/Pixel Quiver/QUIVER_PROBLEMS.md`
+- `/Users/fabrijk/Documents/Work/Proyectos Personales/nika/Pixel Quiver/QUIVER_IMPROVEMENT_SUGGESTIONS.md`
+- `/Users/fabrijk/Documents/Work/Proyectos Personales/nika/Pixel Quiver/QUIVER_FRAMEWORK_IMPROVEMENTS.md`
+
+Repository source-of-truth files:
+
+- `README_FOR_AI.md`
+- `ROADMAP.md`
+- `BACKLOG.md`
+- `specs/quiver-v27-reliability-ai-workflow-hardening/**`
+
+## Core Decisions
+
+- Do not reimplement v27 behavior blindly.
+- `slice-00` must freeze and reconcile evidence before implementation slices start.
+- Each finding must end as `verified-resolved`, `fixed`, `documented-risk`, `duplicate`, or `out-of-scope-with-reason`.
+- No npm publication or PR creation is included in this spec.
+- Changes must remain backward compatible by default unless a stricter mode is explicitly documented.
+- `--dry-run` behavior must remain read-only.
+- Machine-readable output must be valid without stripping human logs.
+
+## Scope
+
+### Included
+
+- Reconciliation matrix for all supplied Pixel Quiver `QP-*`, `QIS-*`, and framework improvement sections.
+- AI run lifecycle and approval clarity.
+- Clean AI command output and raw provider log persistence.
+- Structured `spec.slices[]` contract for technical plans.
+- Safe repair path for approved technical plans with missing structure.
+- Active-slice multi-source reconciliation.
+- `ai inspect` behavior after manual/fallback spec creation.
+- `spec validate`, `check-slice`, `spec status`, `spec start`, scope, and worktree reliability.
+- Structured `ai review-plan` closure metadata.
+- Agent command DX using `npx --yes create-quiver@<version>`.
+- Cross-platform help, docs, fixtures, tests, smoke coverage, and release readiness.
+
+### Excluded
+
+- Pixel Quiver application changes.
+- Building a web dashboard inside Quiver core.
+- Publishing npm.
+- Opening a PR.
+- Removing legacy compatibility without migration.
+- Storing provider credentials.
+
+## Acceptance Criteria
+
+1. Given v27 claims coverage for earlier findings, when `slice-00` completes, then every supplied finding is classified with evidence as resolved, partial, pending, regression, duplicate, or out of scope.
+2. Given a finding is already resolved by v27, when the final matrix is produced, then it is not reimplemented unless a regression test proves it still fails.
+3. Given a finding is pending or partial, when implementation starts, then it is mapped to exactly one primary slice and at least one validation artifact.
+4. Given an AI run is active, when another run is created or inspected, then Quiver avoids mixing scopes and shows the next safe action.
+5. Given approvals exist across multiple runs, when `ai approvals` runs, then active, historical, stale, orphaned, and run-specific approvals are distinguishable.
+6. Given `ai onboard`, `ai plan`, or provider-backed commands run, when output is shown, then useful human output is separated from raw logs and redacted raw artifacts are persisted separately.
+7. Given a technical plan is generated, when it is approved or used by `spec create`, then it contains a parseable structured `spec.slices[]` contract or fails before writing files.
+8. Given an approved plan lacks required structure, when the user requests repair, then Quiver can create a derived draft without mutating the approved artifact and requires review plus approval.
+9. Given active slice state exists in multiple files, when reconciliation runs, then Quiver reports all sources and supports safe dry-run decisions: preserve, close, replace, or block.
+10. Given a spec was created manually or by fallback, when `ai inspect` runs, then it reconciles existing specs and suggests `spec validate`, `next`, or `ai prompt-slice` instead of stale `spec create`.
+11. Given `spec validate` runs, when slices are structurally invalid for execution, then the command detects the relevant `check-slice --local` failures or reports them as strict warnings.
+12. Given a spec worktree path is missing, stale, dirty, or not listed by Git, when `spec status` runs, then the command reports the real state and recovery guidance.
+13. Given `spec start --dry-run` finds a dirty checkout, when it fails, then it lists blocking files and safe options without modifying state.
+14. Given `ai review-plan` runs, when it finishes, then it emits structured metadata for blocking status, approval recommendation, required fixes, optional hardening, and next command.
+15. Given generated examples target agents, when commands are printed, then non-interactive versioned examples use `npx --yes create-quiver@<version>`.
+16. Given docs are updated, when the spec closes, then `README_FOR_AI.md`, `README.md`, `CHANGELOG.md`, and `ROADMAP.md` do not contradict the implemented state.
+17. Given final validation runs, when release readiness is checked, then source tests and package/tarball smoke evidence are recorded.
+
+## Technical Plan
+
+1. Freeze evidence and create the reconciliation matrix before implementation.
+2. Add focused fixtures for unresolved or regressed cases.
+3. Harden AI run state and approvals before touching spec generation.
+4. Enforce the structured technical-plan contract and repair path.
+5. Add active-slice reconciliation and stale `ai inspect` recovery.
+6. Align validation gates and worktree reporting.
+7. Add plan-review closure metadata and agent-friendly command examples.
+8. Close with compatibility tests, documentation sync, smoke coverage, and release evidence.
+
+## Slice Roadmap
+
+| Slice | Title | Status | Dependencies |
+|---|---|---|---|
+| slice-00 | Reconciliation and evidence freeze | completed | none |
+| slice-01 | AI run state, approvals, and clean output | completed | slice-00 |
+| slice-02 | Structured technical plan contract and repair flow | completed | slice-00, slice-01 |
+| slice-03 | Active slice reconciliation and AI inspect | completed | slice-00, slice-01 |
+| slice-04 | Spec validation, scope, and worktree reliability | completed | slice-00 |
+| slice-05 | Review-plan closure and agent DX | completed | slice-00, slice-01 |
+| slice-06 | Backward compatibility, docs, and release readiness | completed | slice-01, slice-02, slice-03, slice-04, slice-05 |
+
+## Validation Strategy
+
+- `node --test tests/**/*.test.js`
+- `npm run smoke:doctor-fixtures`
+- `npm run smoke:guided-workflow`
+- `npm run smoke:create-quiver`
+- `npm run package:quiver`
+- package/tarball smoke from a temporary directory
+- `git diff --check`
+- JSON parse validation for all `slice.json`
+- `npx create-quiver spec validate specs/quiver-v28-pixel-quiver-feedback-reconciliation`
+- `npx create-quiver check-handoff` for each execution and closure brief
+
+## Risks
+
+- Some findings may already be fixed by v27 and only stale in Pixel Quiver docs.
+- Tightening validation can break older project specs if strict behavior is not gated.
+- AI lifecycle changes can affect existing `.quiver/runs` and `.quiver/approvals` state.
+- Worktree changes can affect users with in-flight branches.
+- Real dogfooding evidence contains absolute local paths and must not be copied into fixtures without sanitization.
+- Local non-package files can accidentally enter npm tarballs unless ignored; v28 added `*.pdf` to `.npmignore` after package dry-run evidence.

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

@@ -0,0 +1,36 @@
+# Status - Quiver v28 Pixel Quiver Feedback Reconciliation
+
+## Overall Status
+
+- Phase: Final validation complete
+- Progress: 100%
+- Current recommended slice: none
+- Source evidence: Pixel Quiver feedback files after `create-quiver@0.13.0`
+
+## Slices
+
+| Slice | Title | Status | Progress | Dependencies |
+|---|---|---|---:|---|
+| slice-00 | Reconciliation and evidence freeze | completed | 100% | none |
+| slice-01 | AI run state, approvals, and clean output | completed | 100% | slice-00 |
+| slice-02 | Structured technical plan contract and repair flow | completed | 100% | slice-00, slice-01 |
+| slice-03 | Active slice reconciliation and AI inspect | completed | 100% | slice-00, slice-01 |
+| slice-04 | Spec validation, scope, and worktree reliability | completed | 100% | slice-00 |
+| slice-05 | Review-plan closure and agent DX | completed | 100% | slice-00, slice-01 |
+| slice-06 | Backward compatibility, docs, and release readiness | completed | 100% | slice-01, slice-02, slice-03, slice-04, slice-05 |
+
+## Blockers
+
+- None.
+
+## Known Production Concerns
+
+- v27 already covers part of the Pixel Quiver feedback; remaining slices must not duplicate verified-resolved work.
+- Pixel Quiver evidence contains absolute local paths and must remain evidence only unless sanitized into fixtures.
+- Backward compatibility for existing `.quiver/runs`, `.quiver/approvals`, active-slice docs, and worktree state is mandatory.
+- Tightening validation must avoid breaking older specs by default; strict behavior should be explicit when needed.
+- A local PDF in the repo root was detected by `npm pack --dry-run`; `.npmignore` now excludes `*.pdf` to avoid accidental package publication.
+
+## Next Step
+
+Prepare the PR/release decision outside this spec. npm publication and PR creation were intentionally not performed here.