create-quiver 0.13.0 → 0.14.0

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.

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

@@ -0,0 +1,128 @@
+# Quiver v28 - Pixel Quiver Feedback Reconciliation
+
+## Title
+
+Quiver v28 - Pixel Quiver Feedback Reconciliation
+
+## Summary
+
+- Reconciles Pixel Quiver dogfooding findings against the current Quiver implementation.
+- Fixes unresolved AI lifecycle, approvals, spec creation, active-slice, validation, worktree, plan-review, and agent-DX gaps.
+- Adds regression coverage, documentation updates, smoke evidence, and package-readiness checks.
+- Keeps v28 changes in `Unreleased`; no npm publication is claimed by this PR.
+
+## Scope
+
+- `slice-00`: evidence freeze and reconciliation matrix.
+- `slice-01`: AI run state, approvals, and clean output.
+- `slice-02`: structured technical-plan contract and repair flow.
+- `slice-03`: active-slice reconciliation and `ai inspect` recovery.
+- `slice-04`: spec validation, scope, and worktree reliability.
+- `slice-05`: review-plan closure and agent DX.
+- `slice-06`: docs, compatibility checks, smoke tests, and release readiness.
+
+## Files
+
+- `src/create-quiver/commands/ai.js`
+- `src/create-quiver/commands/spec.js`
+- `src/create-quiver/index.js`
+- `src/create-quiver/lib/ai/**`
+- `src/create-quiver/lib/project-state-resolver.js`
+- `src/create-quiver/lib/spec-worktrees.js`
+- `tests/commands/**`
+- `tests/lib/**`
+- `README.md`
+- `README_FOR_AI.md`
+- `CHANGELOG.md`
+- `ROADMAP.md`
+- `docs/*.template`
+- `.npmignore`
+- `specs/quiver-v28-pixel-quiver-feedback-reconciliation/**`
+
+## How to Test (DETAILED - REQUIRED)
+
+### Required Environment
+
+- Node.js and npm available locally.
+- Git repository checkout with access to the Quiver remote.
+- `gh` is required only for PR operations, not for source validation.
+
+### Worktree Access
+
+Run from the repository root:
+
+```bash
+cd /Users/fabrijk/Documents/Work/Proyectos\ Personales/nika/frameworks/quiver
+```
+
+### Run the Project
+
+This PR changes the `create-quiver` CLI. Use direct Node execution or npm scripts from the repo root:
+
+```bash
+node bin/create-quiver.js --help
+node bin/create-quiver.js ai --help
+```
+
+### Use Cases
+
+Validate the main updated workflows:
+
+```bash
+node bin/create-quiver.js spec validate specs/quiver-v28-pixel-quiver-feedback-reconciliation --strict
+node bin/create-quiver.js next --all-ready --spec quiver-v28-pixel-quiver-feedback-reconciliation
+```
+
+Expected result:
+
+- Spec validation passes.
+- `next --all-ready` reports no ready slices after v28 closure.
+
+### Technical Verification
+
+Run:
+
+```bash
+node --test tests/**/*.test.js
+npm run smoke:doctor-fixtures
+npm run smoke:guided-workflow
+npm run smoke:create-quiver
+npm run package:quiver
+npm pack --dry-run --json
+git diff --check
+```
+
+Expected result:
+
+- All tests pass.
+- Smoke commands pass.
+- Package smoke passes.
+- `npm pack --dry-run --json` does not include local PDF files.
+- `git diff --check` returns no whitespace errors.
+
+## Evidence
+
+Recorded in `specs/quiver-v28-pixel-quiver-feedback-reconciliation/EVIDENCE_REPORT.md`.
+
+Latest validation evidence:
+
+- `node --test tests/**/*.test.js` passed with `376` tests.
+- `npm run smoke:doctor-fixtures` passed with `13` fixture states.
+- `npm run smoke:guided-workflow` passed.
+- `npm run smoke:create-quiver` passed.
+- `npm run package:quiver` passed.
+- `npm pack --dry-run --json` passed with no `.pdf` files in the package.
+- `git diff --check` passed.
+- `node bin/create-quiver.js spec validate specs/quiver-v28-pixel-quiver-feedback-reconciliation --strict` passed.
+- `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` passed.
+
+## Rollback
+
+Revert this PR. No migration, npm publication, external service change, or credential storage change is included.
+
+## Risks / Notes
+
+- v28 tightens validation and approval gates. Backward compatibility was preserved by keeping stricter behavior behind explicit validation and review paths where possible.
+- Existing local `.quiver/` state may expose more precise stale-run or active-slice diagnostics after this change.
+- `.npmignore` now excludes `*.pdf` because package dry-run showed a local requirements PDF would otherwise be included in the npm tarball.
+- npm publication is intentionally out of scope for this PR.

package/specs/quiver-v28-pixel-quiver-feedback-reconciliation/slices/slice-00-reconciliation-and-evidence-freeze/CLOSURE_BRIEF.md

@@ -0,0 +1,44 @@
+# CLOSURE BRIEF - slice-00: Reconciliation and evidence freeze
+
+## Summary
+
+Completed the mandatory reconciliation slice for Quiver v28. The Pixel Quiver feedback files were frozen with hashes/timestamps, all supplied `QP-*`, `QIS-*`, and narrative framework-improvement sections were classified, and the execution mapping for remaining slices was updated.
+
+## Validation
+
+Passed:
+
+- `git diff --check`
+- JSON parse validation for 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`
+
+## Relevant Changes
+
+- Replaced the initial planning matrix in `COVERAGE_MATRIX.md` with evidence-backed classifications.
+- Updated `EVIDENCE_REPORT.md` with frozen source hashes, timestamps, inspected evidence, and remaining validation requirements.
+- Updated `STATUS.md` and `SPEC.md` so `slice-00` is completed and Wave 1 slices are ready.
+- Marked `slice-01` and `slice-04` as ready in their `slice.json` files.
+- Expanded `slice-05` scope to own GitHub auth/alias recovery copy, compact executor handoff guidance, and agent-safe command examples.
+
+## Pending Work
+
+- `slice-01`: AI run state, approvals, and clean output.
+- `slice-04`: spec validation, scope, and worktree reliability.
+- `slice-02`, `slice-03`, and `slice-05` remain blocked until `slice-01` completes.
+- `slice-06` remains the final documentation, compatibility, and release-readiness pass.
+
+## Remaining Risks
+
+- Some v27-covered findings may still need regression tests if implementation slices touch nearby behavior.
+- Pixel Quiver evidence contains absolute local paths and must not be copied into fixtures without sanitization.
+- Framework ideas such as graph conflict summaries and browser-based visual validation are documented as future work, not v28 blockers.
+
+## Future Recommendations
+
+- Keep all implementation slices anchored to `COVERAGE_MATRIX.md`.
+- Do not start `slice-02`, `slice-03`, or `slice-05` until `slice-01` clarifies run and approval state.
+- If a later slice finds that a `verified-resolved` item still fails in code, update the matrix before implementing the fix.

package/specs/quiver-v28-pixel-quiver-feedback-reconciliation/slices/slice-00-reconciliation-and-evidence-freeze/EXECUTION_BRIEF.md

@@ -0,0 +1,56 @@
+# EXECUTION BRIEF - slice-00: Reconciliation and evidence freeze
+
+## Context
+
+Pixel Quiver produced a follow-up set of Quiver framework findings after `create-quiver@0.13.0`. `README_FOR_AI.md` says v27 already covered part of that set, so this slice must verify reality before code changes.
+
+## Objective
+
+Freeze the input evidence and produce the final reconciliation matrix for v28.
+
+## Scope
+
+- `specs/quiver-v28-pixel-quiver-feedback-reconciliation/**`
+- `README_FOR_AI.md`
+- `ROADMAP.md`
+- `CHANGELOG.md`
+
+## Acceptance Criteria
+
+- Every finding from the supplied files is classified with evidence.
+- Pending or partial findings map to one implementation slice.
+- Already-resolved findings are not scheduled for duplicate work.
+- No product code changes are made.
+
+## Technical Plan Summary
+
+Read the supplied Pixel Quiver files, compare them with v27 docs/code/tests, update the coverage matrix, and finalize the slice plan.
+
+## Suggested Execution Steps
+
+1. Record evidence source paths, timestamps, and hashes where practical.
+2. Compare each finding against v27 docs, source, and tests.
+3. Update `COVERAGE_MATRIX.md`.
+4. Update `STATUS.md`, `EVIDENCE_REPORT.md`, and `CLOSURE_BRIEF.md`.
+5. Validate JSON and spec structure.
+
+## Restrictions
+
+- Do not modify product code.
+- Do not publish npm.
+- Do not open a PR.
+- Do not mark a finding resolved without evidence.
+
+## Risks
+
+- Reimplementing v27 behavior would create noise and possible regressions.
+- Pixel Quiver files may be stale relative to the current Quiver source.
+
+## Completion Checklist
+
+- [ ] Evidence freeze complete.
+- [ ] Matrix final statuses assigned.
+- [ ] Implementation slices adjusted if needed.
+- [ ] JSON validation passed.
+- [ ] Spec validation passed.
+

package/specs/quiver-v28-pixel-quiver-feedback-reconciliation/slices/slice-00-reconciliation-and-evidence-freeze/slice.json

@@ -0,0 +1,71 @@
+{
+  "slice_id": "slice-00-reconciliation-and-evidence-freeze",
+  "ticket": "QUIVER-28-00",
+  "type": "docs",
+  "title": "Reconciliation and evidence freeze",
+  "objective": "Freeze Pixel Quiver evidence, reconcile every supplied finding against v27, and produce the final implementation matrix before code changes.",
+  "description": "This mandatory documentary slice prevents duplicate fixes by classifying every QP, QIS, and framework improvement as resolved, partial, pending, regression, duplicate, or out of scope with evidence.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v28-reconciliation-evidence-freeze",
+    "branch_name": "feature/QUIVER-28-00-v28-reconciliation-evidence-freeze"
+  },
+  "files": [
+    "specs/quiver-v28-pixel-quiver-feedback-reconciliation/**",
+    "README_FOR_AI.md",
+    "ROADMAP.md",
+    "CHANGELOG.md"
+  ],
+  "expected_read_paths": [
+    "README_FOR_AI.md",
+    "ROADMAP.md",
+    "BACKLOG.md",
+    "CHANGELOG.md",
+    "specs/quiver-v27-reliability-ai-workflow-hardening/**",
+    "src/create-quiver/**",
+    "tests/**"
+  ],
+  "allowed_write_paths": [
+    "specs/quiver-v28-pixel-quiver-feedback-reconciliation/**",
+    "README_FOR_AI.md",
+    "ROADMAP.md",
+    "CHANGELOG.md"
+  ],
+  "depends_on": [],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "slice-00 is the mandatory foundation and controls what later slices are allowed to fix.",
+  "must": [
+    "Freeze input evidence with paths, timestamps or hashes, and source notes.",
+    "Compare Pixel Quiver findings against v27 implementation, docs, and tests.",
+    "Produce the final coverage matrix with one final status per finding.",
+    "Update docs only if needed to reflect planned state.",
+    "Do not modify product code."
+  ],
+  "not_included": [
+    "CLI behavior changes.",
+    "New tests beyond documentation validation.",
+    "npm publishing.",
+    "PR creation."
+  ],
+  "acceptance": [
+    "Every supplied QP/QIS/framework improvement is classified with evidence.",
+    "Every pending or partial finding is mapped to a primary implementation slice.",
+    "Every already-resolved finding has a test, code, or doc reference.",
+    "No implementation slice starts before this matrix is complete.",
+    "No product code is modified."
+  ],
+  "tests": [
+    "git diff --check",
+    "find specs/quiver-v28-pixel-quiver-feedback-reconciliation -name \"slice.json\" -print -exec node -e \"JSON.parse(require('fs').readFileSync(process.argv[1], 'utf8'))\" {} \\;",
+    "npx create-quiver spec validate specs/quiver-v28-pixel-quiver-feedback-reconciliation"
+  ],
+  "validation_hints": [
+    "Do not copy unsanitized absolute paths into fixtures.",
+    "Treat v27 claims as hypotheses until verified against code and tests."
+  ],
+  "estimated_hours": 4,
+  "actual_hours": 4,
+  "completed_at": "2026-05-25T15:19:49Z",
+  "status": "completed"
+}

package/specs/quiver-v28-pixel-quiver-feedback-reconciliation/slices/slice-01-ai-run-state-approvals-and-clean-output/CLOSURE_BRIEF.md

@@ -0,0 +1,38 @@
+# CLOSURE BRIEF - slice-01: AI run state, approvals, and clean output
+
+## Summary
+
+Completed the AI run-state and approval-visibility hardening slice. Successful provider-backed planner commands now print clean extracted output instead of raw stdout/stderr, run-scoped approvals are shown separately from global planner approval files, and stale runs can be closed without deleting evidence.
+
+## Validation
+
+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`
+
+## Relevant Changes
+
+- Updated `src/create-quiver/commands/ai.js`.
+- Updated `src/create-quiver/lib/ai/run-state.js`.
+- Updated `tests/commands/ai-run-state.test.js`.
+- Updated `tests/commands/ai-plan.test.js`.
+- Updated v28 coverage/status/evidence documents.
+
+## Pending Work
+
+- `slice-02`: enforce and repair structured `spec.slices[]` technical-plan contracts.
+- `slice-03`: reconcile multi-source active-slice state and stale `ai inspect` next commands.
+- `slice-04`: align spec validation, scope, and worktree reliability.
+- `slice-05`: add structured review-plan closure metadata and agent DX improvements.
+
+## Remaining Risks
+
+- `ai run close` archives by setting phase/status to `closed`; it does not delete or migrate any run artifacts.
+- Existing historical `.quiver/approvals/*` files may still be orphaned by design; the CLI now labels them instead of mutating them.
+- More advanced run replacement UX can be added later if dogfooding shows `close` plus visible open-run warnings are not enough.
+
+## Future Recommendations
+
+- Keep future planner commands using clean output on success and raw output only on failure diagnostics.
+- Keep approval reports grouped by run when adding new phases or approval types.

package/specs/quiver-v28-pixel-quiver-feedback-reconciliation/slices/slice-01-ai-run-state-approvals-and-clean-output/EXECUTION_BRIEF.md

@@ -0,0 +1,53 @@
+# EXECUTION BRIEF - slice-01: AI run state, approvals, and clean output
+
+## Context
+
+Pixel Quiver observed stale run state, approval history mixed with active work, and noisy provider output in AI commands.
+
+## Objective
+
+Make AI run and approval state clear, scoped to the active run when requested, and safe for humans and agents to consume.
+
+## Scope
+
+- AI command lifecycle and approvals.
+- Clean draft persistence.
+- Raw provider log storage and redaction.
+- Tests for run/approval states.
+
+## Acceptance Criteria
+
+- Active run and historical approvals are distinguishable.
+- Clean drafts do not include prompt echo or raw provider logs.
+- Raw logs are stored separately and redacted.
+- Existing run/approval data remains readable.
+
+## Technical Plan Summary
+
+Add or refine run-state and approval helpers, update AI command output, and add fixtures/tests around old and active lifecycle data.
+
+## Suggested Execution Steps
+
+1. Read `slice-00` final matrix for exact findings assigned here.
+2. Add failing tests for stale/historical approvals and noisy output.
+3. Update run/approval resolution.
+4. Update raw artifact persistence and output formatting.
+5. Run focused tests and update closure evidence.
+
+## Restrictions
+
+- Do not implement spec generation changes in this slice.
+- Do not change provider credentials handling.
+- Do not store secrets.
+
+## Risks
+
+- Existing `.quiver/approvals` layouts may vary across versions.
+
+## Completion Checklist
+
+- [ ] Run-state tests pass.
+- [ ] Approval grouping tests pass.
+- [ ] Clean draft/raw log tests pass.
+- [ ] Documentation evidence updated.
+

package/specs/quiver-v28-pixel-quiver-feedback-reconciliation/slices/slice-01-ai-run-state-approvals-and-clean-output/slice.json

@@ -0,0 +1,83 @@
+{
+  "slice_id": "slice-01-ai-run-state-approvals-and-clean-output",
+  "ticket": "QUIVER-28-01",
+  "type": "feature",
+  "title": "AI run state, approvals, and clean output",
+  "objective": "Harden AI run lifecycle, approval visibility, and provider output persistence so scopes and drafts do not get mixed.",
+  "description": "Separates active and historical runs, groups approvals by run, persists clean drafts and raw logs separately, and prevents stale approvals from appearing current.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v28-ai-run-state-approvals-clean-output",
+    "branch_name": "feature/QUIVER-28-01-v28-ai-run-state-approvals-clean-output"
+  },
+  "files": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/run-state.js",
+    "src/create-quiver/lib/ai/artifacts.js",
+    "src/create-quiver/lib/ai/export-state.js",
+    "src/create-quiver/lib/approvals.js",
+    "tests/commands/ai-run-state.test.js",
+    "tests/commands/ai-plan.test.js",
+    "tests/commands/ai-export.test.js",
+    "tests/lib/ai-run-state.test.js",
+    "tests/lib/approvals.test.js",
+    "tests/lib/ai-export-state.test.js",
+    "specs/quiver-v28-pixel-quiver-feedback-reconciliation/**"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/**",
+    "src/create-quiver/lib/approvals.js",
+    "tests/commands/ai-*.test.js",
+    "tests/lib/ai-*.test.js"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/run-state.js",
+    "src/create-quiver/lib/ai/artifacts.js",
+    "src/create-quiver/lib/ai/export-state.js",
+    "src/create-quiver/lib/approvals.js",
+    "tests/commands/ai-run-state.test.js",
+    "tests/commands/ai-plan.test.js",
+    "tests/commands/ai-export.test.js",
+    "tests/lib/ai-run-state.test.js",
+    "tests/lib/approvals.test.js",
+    "tests/lib/ai-export-state.test.js",
+    "specs/quiver-v28-pixel-quiver-feedback-reconciliation/**"
+  ],
+  "depends_on": [
+    "slice-00-reconciliation-and-evidence-freeze"
+  ],
+  "parallel_safe": "after_dependencies",
+  "parallel_safe_reason": "Can run after slice-00 if no overlap with slice-04 is introduced.",
+  "must": [
+    "Distinguish active, historical, stale, and orphaned approvals.",
+    "Keep clean drafts separate from raw provider logs.",
+    "Redact raw logs before persistence.",
+    "Avoid breaking existing run directories."
+  ],
+  "not_included": [
+    "Technical-plan schema repair.",
+    "Active-slice reconciliation.",
+    "PR creation."
+  ],
+  "acceptance": [
+    "AI commands do not mix current run output with historical approvals.",
+    "Raw provider logs are persisted separately from useful drafts.",
+    "Tests cover old, current, stale, and incomplete run states.",
+    "JSON export remains parseable without human log cleanup."
+  ],
+  "tests": [
+    "node --test tests/commands/ai-run-state.test.js tests/commands/ai-plan.test.js tests/commands/ai-export.test.js",
+    "node --test tests/lib/ai-run-state.test.js tests/lib/approvals.test.js tests/lib/ai-export-state.test.js"
+  ],
+  "validation_hints": [
+    "Add fixtures for old approvals before changing behavior.",
+    "Keep backward compatibility for existing .quiver/runs."
+  ],
+  "estimated_hours": 8,
+  "actual_hours": 8,
+  "completed_at": "2026-05-25T15:19:49Z",
+  "status": "completed"
+}