create-quiver 0.12.0 → 0.13.0

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

@@ -0,0 +1,71 @@
+# Execution Plan - Quiver v27
+
+## Wave 0 - Required Foundation
+
+1. `slice-00-docs-audit-coverage-and-contracts` - completed
+   - Must run first.
+   - Audits docs/code/tests against Pixel Quiver evidence.
+   - Defines the contracts that prevent partial fixes.
+
+## Wave 1 - Shared Model
+
+Run sequentially:
+
+1. `slice-01-core-state-resolver-and-canonical-statuses` - completed
+
+This slice owns the state model used by later command fixes.
+
+## Wave 2 - Export and Spec Generation
+
+Run after Wave 1. Prefer sequential order:
+
+1. `slice-02-json-export-contract-and-machine-output` - completed
+2. `slice-03-approved-plan-to-spec-create` - completed
+
+These touch shared AI/spec data contracts and should not run in parallel unless file scopes are proven independent.
+
+## Wave 3 - AI Artifacts and Worktrees
+
+Can run in parallel after Wave 1 if write scopes do not overlap:
+
+1. `slice-04-ai-artifact-storage-redaction-and-token-compaction` - completed
+2. `slice-05-worktree-lifecycle-locks-and-recovery` - completed
+
+Status: Wave 3 is complete.
+
+## Wave 4 - Validation Gates
+
+Run after Wave 3:
+
+1. `slice-06-validation-gates-and-scope-safety` - completed
+
+Status: Wave 4 is complete.
+
+## Wave 5 - Context and DX
+
+Run after Wave 4:
+
+1. `slice-07-context-analysis-and-doctor-flow` - completed
+2. `slice-08-cross-platform-help-auth-and-dx` - completed
+
+`slice-08` depends on `slice-07` because help/auth guidance should reference the hardened diagnostics contract.
+
+Status: Wave 5 is complete.
+
+## Wave 6 - Final Readiness
+
+Run last:
+
+1. `slice-09-fixtures-smoke-docs-and-release-readiness`
+
+This slice validates the whole package from source and tarball.
+
+Status: Wave 6 is complete.
+
+## Parallel Safety Notes
+
+- Keep one commit per slice.
+- Do not run slices in parallel when `allowed_write_paths` overlap.
+- `slice-00`, `slice-01`, `slice-02`, `slice-03`, `slice-06`, and `slice-09` are sequential checkpoints.
+- `slice-04` and `slice-05` are the main candidates for parallel execution after `slice-01`.
+- Do not publish npm from this spec.

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

@@ -0,0 +1,176 @@
+# Quiver v27 - Reliability and AI Workflow Hardening
+
+**Date:** 2026-05-24
+**Status:** Active
+**Source:** Pixel Quiver dogfooding evidence, final worktree traceability
+
+Slice numbering resets here. This spec intentionally starts at `slice-00`.
+
+## Problem
+
+Real use of Quiver in Pixel Quiver exposed that several AI-first workflow areas are still fragile even though related capabilities were introduced across v24, v25, and v26.
+
+The current risk is not a missing single feature. The risk is systemic: commands can disagree about specs/slices, machine-readable output is not stable enough for dashboards, `spec create` can generate incomplete scaffolds from an approved plan, dry-run behavior is not consistently read-only, and validation/worktree guidance can leave users or agents in ambiguous states.
+
+## Objective
+
+Make Quiver reliable for production-grade AI-first WDD + SDD workflows by hardening the core state model, command contracts, spec/slice generation, exports, AI artifacts, worktrees, validations, context preparation, cross-platform DX, and release evidence.
+
+## Evidence Sources
+
+Primary requirement inputs are the final Pixel Quiver dogfooding files:
+
+- `/Users/fabrijk/Documents/Work/Proyectos Personales/nika/.worktrees/Pixel Quiver/feature-REAL-QUIVER-AI-LIFECYCLE-01-quiver-ai-config-and-context/QUIVER_PROBLEMS.md`
+- `/Users/fabrijk/Documents/Work/Proyectos Personales/nika/.worktrees/Pixel Quiver/feature-REAL-QUIVER-AI-LIFECYCLE-01-quiver-ai-config-and-context/QUIVER_IMPROVEMENT_SUGGESTIONS.md`
+- `/Users/fabrijk/Documents/Work/Proyectos Personales/nika/.worktrees/Pixel Quiver/feature-REAL-QUIVER-AI-LIFECYCLE-01-quiver-ai-config-and-context/COMMAND_LOG.md`
+
+The final traceability set contains:
+
+- `QP-001` to `QP-019`
+- `QIS-001` to `QIS-022`
+
+## Core Decisions
+
+- Audit existing v24/v25/v26 behavior before changing code.
+- Treat `README_FOR_AI.md` as the repository source of truth.
+- Keep `npx create-quiver` as the canonical bootstrap command.
+- Preserve existing command names and compatibility unless a breaking change is explicitly justified.
+- Define shared contracts before fixing individual commands.
+- Make `slice.json` and `.quiver/` operational state the source of truth; visible docs are derived and validated.
+- Keep `--dry-run` strictly read-only.
+- Keep machine-readable output parseable without cleanup.
+- Keep one persistent worktree per spec and one commit per slice; delegated temporary worktrees remain an internal execution mode.
+- Do not publish npm or open PRs from this spec unless explicitly requested after implementation and validation.
+
+## Scope
+
+### Included
+
+- Audit and coverage matrix for all `QP-*` and `QIS-*`.
+- Command contracts: exit codes, stdout/stderr, dry-run, write classes, idempotency, atomic writes, path safety, root detection, package manager detection, and deterministic ordering.
+- Unified state resolver for specs, slices, runs, approvals, agents, evidence, worktrees, status, and source metadata.
+- Canonical status catalogs for specs, slices, runs, approvals, agents, and datasets.
+- JSON export contract for dashboards and agents.
+- Alignment between `ai export` and the stable export contract.
+- `spec create` generation from a reviewed and approved technical plan.
+- Structured approved-plan slice block validation.
+- Clean AI drafts, separated raw logs, redaction, and token compaction.
+- Worktree lifecycle hardening, locks, recovery, and no nested worktree guidance.
+- Validation gates for `check-slice`, `check-scope`, `check-handoff`, and `spec validate`.
+- Context and diagnostics hardening for `analyze`, `prepare-context`, `flow`, and `doctor`.
+- Cross-platform DX for macOS, Linux, Windows PowerShell, Git Bash, and WSL.
+- GitHub auth diagnostics and help/error messages.
+- Real/sanitized fixtures and smoke tests, including tarball/package validation.
+
+### Excluded
+
+- Building a web dashboard inside Quiver core.
+- Publishing npm.
+- Opening a PR.
+- Replacing the WDD + SDD methodology.
+- Removing existing legacy compatibility without an explicit migration path.
+- Storing provider credentials or API keys.
+
+## Acceptance Criteria
+
+1. Given the v27 spec is created, when `slice-00` completes, then every `QP-*` and `QIS-*` is mapped to a slice, command area, risk, and validation strategy.
+2. Given a command supports `--dry-run`, when it completes, then no repository file changes, including `.quiver/`, `docs/`, and `specs/`.
+3. Given a command emits `--format json`, when it succeeds, then `stdout` is valid JSON parseable without removing logs or human text.
+4. Given a command fails, when it exits, then it writes the error to `stderr`, exits non-zero, and leaves previous valid state intact or reports exact partial state.
+5. Given Quiver resolves project state, when commands inspect specs/slices, then classic and AI commands use the same resolver and agree on status, dependencies, completed slices, runs, approvals, agents, and evidence.
+6. Given a project has completed slices, when export runs with `--include-completed`, then completed specs/slices appear in deterministic order.
+7. Given Quiver exports JSON, when a dashboard consumes it, then the payload includes schema version, dataset source, generated timestamp, source metadata, warnings, specs, slices, agents, runs, approvals, blockers, evidence, next steps, lifecycle, and aggregates.
+8. Given an approved technical plan includes a structured slice block, when `spec create` runs, then it creates the approved spec, slices, handoffs, execution plan, and PR body without generic fallback.
+9. Given an approved technical plan lacks a parseable structured slice block, when `spec create` runs, then it fails before writing files and prints the expected format.
+10. Given an AI provider returns prompt echo, logs, or mixed output, when Quiver persists drafts, then the useful draft is clean and raw logs are stored separately with redaction.
+11. Given feedback is near provider context limits, when `ai revise` runs, then Quiver compacts safely or requests smaller input before exceeding limits.
+12. Given a spec worktree exists, when `spec start`, `spec status`, or slice execution commands run, then Quiver reuses the persistent spec worktree and avoids nested or conflicting worktrees.
+13. Given a worktree or lock is stale, missing, dirty, or manually removed, when Quiver detects it, then it reports recovery steps without corrupting state.
+14. Given a slice is checked locally, when `check-slice --local` runs, then it validates all local preconditions required by later execution or explicitly lists skipped checks.
+15. Given `check-scope` receives `--base` or a slice declares `git.base_branch`, when it runs, then it uses that base before falling back.
+16. Given a handoff/brief is incomplete, when `check-handoff` runs, then it prints the missing heading, a minimal template, and supported aliases where applicable.
+17. Given a path is outside the project root or attempts traversal, when a write path is resolved, then Quiver rejects it.
+18. Given Quiver runs in a simple repo, subdirectory, worktree, or basic monorepo, when it resolves the root, then it uses or reports the project root clearly.
+19. Given a project uses npm, pnpm, yarn, or bun, when Quiver suggests package commands, then it respects the detected package manager.
+20. Given a project path contains spaces, when Quiver prints commands, then examples are copy-safe for macOS, Linux, Windows PowerShell, Git Bash, and WSL.
+21. Given GitHub auth is missing or ambiguous, when `ai doctor` or PR preflight runs, then Quiver reports account/scopes/alias expectations and the next safe command.
+22. Given old `.quiver/` state exists, when `migrate --dry-run` runs, then it reports exactly what would be updated and preserves existing data.
+23. Given fixtures are added from real projects, when committed, then they are sanitized and do not expose unnecessary personal paths or credentials.
+24. Given release readiness is validated, when final smoke runs, then it uses the packaged tarball or installed package path, not only local source files.
+
+## Coverage Matrix
+
+The full coverage matrix lives in `COVERAGE_MATRIX.md`. Summary:
+
+| Evidence | Covered by |
+|---|---|
+| QP-001, QIS-001 | slice-07 |
+| QP-002, QIS-002 | slice-08 |
+| QP-003, QIS-006 | slice-01, slice-02 |
+| QP-004, QIS-009 | slice-08 |
+| QP-005, QIS-007 | slice-07 |
+| QP-006, QIS-008 | slice-07 |
+| QP-007, QIS-010 | slice-07, slice-08 |
+| QP-008, QIS-008 | slice-00, slice-07 |
+| QP-009, QIS-012 | slice-04 |
+| QP-010, QIS-013 | slice-04 |
+| QP-011, QIS-014, QIS-015 | slice-03 |
+| QP-012 | slice-03 |
+| QP-013, QIS-016 | slice-06 |
+| QP-014, QIS-017 | slice-07 |
+| QP-015, QIS-018 | slice-07 |
+| QP-016, QIS-019 | slice-06 |
+| QP-017, QIS-020 | slice-06 |
+| QP-018, QIS-021 | slice-05 |
+| QP-019, QIS-004, QIS-022 | slice-02 |
+| QIS-003 | slice-06 |
+| QIS-005 | slice-06 |
+| QIS-011 | slice-08 |
+
+## Technical Plan
+
+1. Publish a documentation-only foundation that audits current docs, code, tests, and dogfooding evidence.
+2. Define command contracts and the shared internal state model before command-specific fixes.
+3. Build or refactor a core resolver that every relevant command can consume.
+4. Define and test a stable JSON export contract with pure machine output.
+5. Make `spec create` require a reviewed, approved, structured plan and fail safely otherwise.
+6. Clean AI artifact persistence, raw logs, redaction, and token compaction.
+7. Harden worktree, lock, branch, and recovery behavior for the spec/slice lifecycle.
+8. Harden validation gates and scope/path safety.
+9. Harden context commands, diagnostics, first-use guidance, and cross-platform help.
+10. Validate with fixtures, command tests, smokes, tarball/package smoke, docs sync, and release readiness.
+
+## Slice Roadmap
+
+| Slice | Title | Status | Dependencies |
+|---|---|---|---|
+| slice-00 | Docs audit, coverage, and contracts | completed | none |
+| slice-01 | Core state resolver and canonical statuses | completed | slice-00 |
+| slice-02 | JSON export contract and machine output | completed | slice-01 |
+| slice-03 | Approved plan to spec create | completed | slice-01, slice-02 |
+| slice-04 | AI artifact storage, redaction, and token compaction | completed | slice-01 |
+| slice-05 | Worktree lifecycle, locks, and recovery | completed | slice-01 |
+| slice-06 | Validation gates and scope safety | completed | slice-01, slice-05 |
+| slice-07 | Context analysis and doctor flow | completed | slice-01, slice-06 |
+| slice-08 | Cross-platform help, auth, and DX | completed | slice-07 |
+| slice-09 | Fixtures, smoke, docs, and release readiness | completed | slice-02, slice-03, slice-04, slice-05, slice-06, slice-07, slice-08 |
+
+## 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`
+- Tarball smoke from `/private/tmp`
+- `git diff --check`
+- JSON parse validation for every `slice.json`
+- `check-handoff` for every `EXECUTION_BRIEF.md` and `CLOSURE_BRIEF.md`
+
+## Risks
+
+- Some v24/v25/v26 docs may claim behavior that is only partially implemented.
+- A shared resolver can create broad regressions if introduced without command-by-command compatibility tests.
+- Export schema stabilization can break ad-hoc consumers unless old behavior is kept or documented.
+- Worktree lifecycle changes can affect existing users with in-flight branches.
+- Real fixtures can expose local paths unless sanitized.

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

@@ -0,0 +1,37 @@
+# Status - Quiver v27 Reliability and AI Workflow Hardening
+
+## Overall Status
+
+- Phase: implemented, pending package release
+- Progress: 100%
+- Current recommended slice: none
+- Source evidence: Pixel Quiver final dogfooding traceability (`QP-001` to `QP-019`, `QIS-001` to `QIS-022`)
+
+## Slices
+
+| Slice | Title | Status | Progress | Dependencies |
+|---|---|---|---:|---|
+| slice-00 | Docs audit, coverage, and contracts | completed | 100% | none |
+| slice-01 | Core state resolver and canonical statuses | completed | 100% | slice-00 |
+| slice-02 | JSON export contract and machine output | completed | 100% | slice-01 |
+| slice-03 | Approved plan to spec create | completed | 100% | slice-01, slice-02 |
+| slice-04 | AI artifact storage, redaction, and token compaction | completed | 100% | slice-01 |
+| slice-05 | Worktree lifecycle, locks, and recovery | completed | 100% | slice-01 |
+| slice-06 | Validation gates and scope safety | completed | 100% | slice-01, slice-05 |
+| slice-07 | Context analysis and doctor flow | completed | 100% | slice-01, slice-06 |
+| slice-08 | Cross-platform help, auth, and DX | completed | 100% | slice-07 |
+| slice-09 | Fixtures, smoke, docs, and release readiness | completed | 100% | slice-02, slice-03, slice-04, slice-05, slice-06, slice-07, slice-08 |
+
+## Blockers
+
+- No implementation blockers after `slice-09`.
+
+## Known Production Concerns
+
+- v27 is implemented and validated from source and packaged tarball, but npm publication is not part of this spec.
+- The final Pixel Quiver source files live outside this repo and must remain evidence only; committed fixtures stay sanitized and synthetic.
+- `README_FOR_AI.md`, `ROADMAP.md`, `CHANGELOG.md`, and `README.md` were synchronized with the implemented-but-unpublished state.
+
+## Next Step
+
+Open the PR or release branch for v27. Publish only after human review and the normal release process.

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

@@ -0,0 +1,132 @@
+# Quiver v27 - Reliability and AI Workflow Hardening
+
+## Title
+
+Quiver v27 - Reliability and AI Workflow Hardening
+
+## Summary
+
+This PR hardens Quiver after Pixel Quiver dogfooding surfaced workflow reliability issues across specs, slices, AI lifecycle commands, validation, worktrees, context diagnostics, and release readiness.
+
+Main changes:
+
+- Aligns classic and AI command state discovery through a shared resolver and canonical statuses.
+- Stabilizes lifecycle JSON exports for dashboards and agents.
+- Makes `spec create`, AI artifacts, worktrees, validation gates, context commands, and cross-platform DX safer.
+- Adds final fixture, smoke, full-suite, and packaged CLI validation evidence.
+
+## Scope
+
+- `QP-001` to `QP-019`
+- `QIS-001` to `QIS-022`
+- Specs/slices, AI lifecycle, exports, validators, worktrees, docs, tests, fixtures, and release readiness.
+- npm publication is intentionally out of scope.
+
+## Files
+
+- `src/create-quiver/**`
+- `bin/create-quiver.js`
+- `docs/**`
+- `docs-template/**`
+- `tests/**`
+- `scripts/**`
+- `package.json`
+- `README.md`
+- `README_FOR_AI.md`
+- `ROADMAP.md`
+- `CHANGELOG.md`
+- `specs/quiver-v27-reliability-ai-workflow-hardening/**`
+
+## How to Test (DETAILED - REQUIRED)
+
+### Required Environment
+
+- Node.js compatible with the current repository test setup.
+- npm available.
+- Git available.
+- No npm publishing credentials are required for this PR.
+
+### Worktree Access
+
+From the repository root:
+
+```bash
+git status --short --branch
+```
+
+Expected:
+
+- Branch contains the v27 commits.
+- No unrelated tracked changes are required.
+- Untracked local files should not be included unless intentionally staged.
+
+### Run the Project
+
+This is a CLI framework repository. Validate the CLI directly from source:
+
+```bash
+node bin/create-quiver.js --help
+node bin/create-quiver.js flow
+```
+
+### Use Cases
+
+Validate the completed v27 spec:
+
+```bash
+node bin/create-quiver.js spec validate specs/quiver-v27-reliability-ai-workflow-hardening
+node bin/create-quiver.js plan --spec quiver-v27-reliability-ai-workflow-hardening --include-completed
+node bin/create-quiver.js graph --spec quiver-v27-reliability-ai-workflow-hardening --include-completed
+node bin/create-quiver.js next --spec quiver-v27-reliability-ai-workflow-hardening
+```
+
+Expected:
+
+- Spec validation passes.
+- Plan and graph show all 10 v27 slices as completed.
+- `next` reports no ready slices.
+
+### Technical Verification
+
+Run:
+
+```bash
+node --test tests/**/*.test.js
+npm run smoke:doctor-fixtures
+npm run smoke:create-quiver
+npm run smoke:guided-workflow
+npm run package:quiver
+git diff --check
+```
+
+Expected:
+
+- Full test suite passes.
+- All smoke suites pass.
+- Package smoke validates the generated tarball.
+- No whitespace errors are reported.
+
+## Evidence
+
+- `node --test tests/**/*.test.js` passed with 356 tests.
+- `npm run smoke:doctor-fixtures` passed.
+- `npm run smoke:create-quiver` passed.
+- `npm run smoke:guided-workflow` passed.
+- `npm run package:quiver` passed and validated `create-quiver-0.12.1.tgz`.
+- Tarball/package smoke validated installed CLI behavior for help, `flow`, and `ai agent set --dry-run`.
+- `node bin/create-quiver.js spec validate specs/quiver-v27-reliability-ai-workflow-hardening` passed.
+- `node bin/create-quiver.js next --spec quiver-v27-reliability-ai-workflow-hardening` reported no ready slices.
+- `git diff --check` passed.
+
+## Rollback
+
+Revert the v27 commits from this PR. Since the changes are organized as one spec with one commit per slice, rollback can be done by reverting the affected slice commits in reverse order.
+
+If a release has already been published, publish a follow-up patch release after reverting or fixing the affected behavior.
+
+## Risks / Notes
+
+- Shared resolver changes can affect many commands.
+- Export schema changes require backward-compatible handling or migration notes.
+- Worktree lifecycle changes must preserve existing user workflows.
+- v27 is implemented and release-ready from source/package validation, but npm publication is intentionally outside this spec.

package/specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-00-docs-audit-coverage-and-contracts/CLOSURE_BRIEF.md

@@ -0,0 +1,36 @@
+# CLOSURE BRIEF - slice-00: Docs audit, coverage, and contracts
+
+## Summary
+
+Completed the documentation foundation for v27 before any product-code implementation.
+
+This slice added the full QP/QIS coverage matrix, shared command contracts, and a v24/v25/v26 audit so later slices have a concrete production contract instead of fixing command behavior in isolation.
+
+## Validation Against Acceptance Criteria
+
+- The v27 spec package exists with `SPEC.md`, `STATUS.md`, `EXECUTION_PLAN.md`, `EVIDENCE_REPORT.md`, `pr.md`, and all slice folders.
+- `COVERAGE_MATRIX.md` maps every `QP-001..QP-019` and `QIS-001..QIS-022` to at least one slice with risk and validation strategy.
+- `COMMAND_CONTRACTS.md` documents exit codes, stdout/stderr behavior, dry-run, write class, idempotency, atomic writes, path safety, root detection, package managers, deterministic ordering, and legacy/strict behavior.
+- `AUDIT_V24_V25_V26.md` documents existing implementation surfaces and remaining dogfooding gaps.
+- `README_FOR_AI.md`, `ROADMAP.md`, and `CHANGELOG.md` were kept aligned with the current state: v26 shipped, v27 active but not published.
+- No product code was modified.
+
+## Changes
+
+- Added `specs/quiver-v27-reliability-ai-workflow-hardening/COVERAGE_MATRIX.md`.
+- Added `specs/quiver-v27-reliability-ai-workflow-hardening/COMMAND_CONTRACTS.md`.
+- Added `specs/quiver-v27-reliability-ai-workflow-hardening/AUDIT_V24_V25_V26.md`.
+- Updated v27 `SPEC.md`, `STATUS.md`, and `EVIDENCE_REPORT.md` to mark `slice-00` complete and set `slice-01` as the next recommended slice.
+- Updated this closure brief and `slice.json` with completion state.
+
+## Remaining Risks
+
+- The audit is documentary evidence only. Implementation slices must still add regression tests for each dogfooding failure.
+- Some existing v24/v25/v26 tests may pass while behavior remains insufficient for the exact Pixel Quiver scenarios.
+- Pixel Quiver source files contain local paths and must be sanitized before becoming fixtures.
+
+## Follow-up Recommendations
+
+- Start `slice-01-core-state-resolver-and-canonical-statuses` next because every later command depends on a shared state resolver.
+- Treat `COMMAND_CONTRACTS.md` as the implementation contract for all later slices.
+- Add fixtures from Pixel Quiver only after replacing personal paths and project-specific values.

package/specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-00-docs-audit-coverage-and-contracts/EXECUTION_BRIEF.md

@@ -0,0 +1,56 @@
+# EXECUTION BRIEF - slice-00: Docs audit, coverage, and contracts
+
+## Context
+
+Pixel Quiver dogfooding produced `QP-001` to `QP-019` and `QIS-001` to `QIS-022`. Some related Quiver capabilities are documented as shipped in v24, v25, and v26, but real usage showed remaining gaps. This slice creates the foundation and contracts before product code changes.
+
+## Objective
+
+Create and verify the v27 documentary foundation, coverage matrix, and production command contracts.
+
+## Scope
+
+- `specs/quiver-v27-reliability-ai-workflow-hardening/**`
+- `README_FOR_AI.md`
+- `ROADMAP.md`
+- `CHANGELOG.md`
+
+## Acceptance Criteria
+
+- The v27 spec package exists and every slice has `slice.json`, `EXECUTION_BRIEF.md`, and `CLOSURE_BRIEF.md`.
+- Every QP/QIS is mapped to a slice and validation strategy.
+- Cross-command contracts are documented.
+- Source-of-truth docs mention v27 as planned without claiming implementation.
+- No product code changes are made.
+
+## Technical Plan Summary
+
+Audit existing docs/code/tests, record coverage, and update docs/spec artifacts only.
+
+## Suggested Execution Steps
+
+1. Inspect v24/v25/v26 docs, implementation, and tests.
+2. Fill the v27 coverage matrix with status per QP/QIS.
+3. Document command contracts and compatibility expectations.
+4. Update source-of-truth docs.
+5. Validate JSON, handoffs, and whitespace.
+
+## Restrictions
+
+- Do not modify product code.
+- Do not publish npm.
+- Do not open a PR unless explicitly requested.
+
+## Risks
+
+- Existing docs may overstate implemented behavior; record gaps instead of assuming.
+
+## Completion Checklist
+
+- [ ] Coverage matrix completed.
+- [ ] Contracts documented.
+- [ ] Source-of-truth docs synced.
+- [ ] JSON validation passed.
+- [ ] Handoff validation passed.
+- [ ] `git diff --check` passed.
+

package/specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-00-docs-audit-coverage-and-contracts/slice.json

@@ -0,0 +1,75 @@
+{
+  "slice_id": "slice-00-docs-audit-coverage-and-contracts",
+  "ticket": "QUIVER-27-00",
+  "type": "docs",
+  "title": "Docs audit, coverage, and contracts",
+  "objective": "Create the v27 documentary foundation, audit existing v24/v25/v26 behavior against Pixel Quiver evidence, and define cross-command contracts before implementation starts.",
+  "description": "Audits source-of-truth docs, existing specs, tests, and implementation surfaces; creates a QP/QIS coverage matrix; defines command contracts for exit codes, stdout/stderr, dry-run, write classes, idempotency, atomic writes, path safety, root detection, package managers, deterministic ordering, schema/versioning, and legacy/strict behavior.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v27-docs-audit-coverage-contracts",
+    "branch_name": "feature/QUIVER-27-00-v27-docs-audit-coverage-contracts"
+  },
+  "files": [
+    "README_FOR_AI.md",
+    "ROADMAP.md",
+    "CHANGELOG.md",
+    "specs/quiver-v27-reliability-ai-workflow-hardening/**"
+  ],
+  "expected_read_paths": [
+    "README_FOR_AI.md",
+    "ROADMAP.md",
+    "BACKLOG.md",
+    "CHANGELOG.md",
+    "specs/quiver-v24-dx-onboarding-hardening/**",
+    "specs/quiver-v25-ai-first-lifecycle-orchestrator/**",
+    "specs/quiver-v26-0121-smoke-hardening/**",
+    "src/create-quiver/**",
+    "tests/**"
+  ],
+  "allowed_write_paths": [
+    "README_FOR_AI.md",
+    "ROADMAP.md",
+    "CHANGELOG.md",
+    "specs/quiver-v27-reliability-ai-workflow-hardening/**"
+  ],
+  "depends_on": [],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "slice-00 is the mandatory documentary foundation and must land before implementation slices.",
+  "must": [
+    "Create or refine the v27 planning package.",
+    "Map QP-001..QP-019 and QIS-001..QIS-022 to slices and validations.",
+    "Audit v24/v25/v26 docs and code for already implemented, partial, broken, or missing behavior.",
+    "Define cross-command production contracts.",
+    "Avoid product code changes."
+  ],
+  "not_included": [
+    "Changing CLI behavior.",
+    "Adding tests beyond documentation validation.",
+    "Publishing npm.",
+    "Opening a PR."
+  ],
+  "acceptance": [
+    "The v27 spec folder exists with SPEC.md, STATUS.md, EXECUTION_PLAN.md, EVIDENCE_REPORT.md, pr.md, and all slice folders.",
+    "Every QP/QIS is assigned to at least one slice or explicitly marked covered by existing implementation with evidence.",
+    "Command contracts for exit codes, stdout/stderr, dry-run, write class, idempotency, atomic writes, path safety, root detection, package managers, deterministic ordering, and legacy/strict behavior are documented.",
+    "README_FOR_AI.md, ROADMAP.md, and CHANGELOG.md do not contradict the current v27 planned state.",
+    "No product code is modified."
+  ],
+  "tests": [
+    "git diff --check",
+    "find specs/quiver-v27-reliability-ai-workflow-hardening -name \"slice.json\" -print -exec node -e \"JSON.parse(require('fs').readFileSync(process.argv[1], 'utf8'))\" {} \\;",
+    "npx create-quiver check-handoff specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-00-docs-audit-coverage-and-contracts/EXECUTION_BRIEF.md",
+    "npx create-quiver check-handoff specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-00-docs-audit-coverage-and-contracts/CLOSURE_BRIEF.md"
+  ],
+  "validation_hints": [
+    "Use git diff to confirm the slice is documentation-only.",
+    "Do not copy unsanitized Pixel Quiver absolute paths into fixtures."
+  ],
+  "estimated_hours": 3,
+  "actual_hours": 3,
+  "status": "completed",
+  "completed_at": "2026-05-24T13:38:42Z",
+  "blocked_reason": null
+}

package/specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-01-core-state-resolver-and-canonical-statuses/CLOSURE_BRIEF.md

@@ -0,0 +1,37 @@
+# CLOSURE BRIEF - slice-01: Core state resolver and canonical statuses
+
+## Summary
+
+Implemented the shared resolver foundation for Quiver lifecycle state.
+
+Classic commands and AI lifecycle surfaces now share a resolver layer for slice discovery, scoped reads, canonical status normalization, deterministic ordering, completed-slice filtering, graph summaries, and progress calculations.
+
+## Validation Against Acceptance Criteria
+
+- Classic `plan` and `graph` commands now resolve slices through `project-state-resolver`.
+- AI lifecycle export/list/inspect state now resolves slices through the same resolver.
+- Completed slices are visible when `includeCompleted` or `--include-completed` is requested.
+- Scoped reads continue to avoid parsing unrelated historical specs.
+- Status aliases are normalized through a shared canonical catalog while preserving legacy `status` fields for compatibility.
+- Existing behavior for plan, graph, next, doctor, and AI export/list/inspect remains covered by tests.
+
+## Changes
+
+- Added `src/create-quiver/lib/statuses.js`.
+- Added `src/create-quiver/lib/project-state-resolver.js`.
+- Updated `src/create-quiver/commands/plan.js`.
+- Updated `src/create-quiver/commands/graph.js`.
+- Updated `src/create-quiver/lib/ai/export-state.js`.
+- Added `tests/lib/project-state-resolver.test.js`.
+- Updated v27 evidence, status, and spec docs.
+
+## Remaining Risks
+
+- `flow` and deeper doctor next-step logic still have command-specific state logic; their full hardening remains assigned to `slice-07`.
+- The public JSON export schema is not finalized in this slice; `slice-02` owns that contract.
+- Worktree state is not yet unified through the resolver; `slice-05` owns persistent worktree lifecycle behavior.
+
+## Follow-up Recommendations
+
+- Execute `slice-02-json-export-contract-and-machine-output` next to stabilize the machine-readable export contract over the resolver.
+- Keep `status` fields backward compatible and expose canonical state through additive fields until a migration is explicitly approved.