create-quiver 0.12.1 → 0.13.0

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

@@ -0,0 +1,179 @@
+# Evidence Report - Quiver v27 Reliability and AI Workflow Hardening
+
+## Initial Evidence
+
+- Pixel Quiver final dogfooding produced `QP-001` to `QP-019` and `QIS-001` to `QIS-022`.
+- The approved plan requires a single spec with slices ordered by shared contracts first, command fixes second, and release readiness last.
+- `README_FOR_AI.md` was read before creating this spec.
+- `ROADMAP.md` and `BACKLOG.md` were reviewed before creating this spec.
+
+## Validation Status
+
+- v27 source, fixture, smoke, guided workflow, and packaged tarball validation passed on 2026-05-24.
+- npm publication was intentionally not performed by this spec.
+
+## Slice 00 Evidence - 2026-05-24
+
+- Created `COVERAGE_MATRIX.md` to map all `QP-001..QP-019` and `QIS-001..QIS-022` to a responsible slice, risk, and validation strategy.
+- Created `COMMAND_CONTRACTS.md` to define shared production contracts for output streams, exit codes, dry-run behavior, write classes, atomicity, idempotency, path safety, root detection, package manager detection, deterministic ordering, status catalogs, JSON versioning, legacy/strict modes, security, and validation.
+- Created `AUDIT_V24_V25_V26.md` to separate existing v24/v25/v26 implementation surfaces from the dogfooding gaps that v27 must still close.
+- Audited existing command and test surfaces with `rg` across `src/create-quiver`, `tests`, and v24/v25/v26 specs for resolver/export/spec-create/check-scope/check-handoff/worktree/analyze/dry-run/doctor/path/redaction surfaces.
+- Confirmed `README_FOR_AI.md`, `ROADMAP.md`, and `CHANGELOG.md` were updated so v26 remains the shipped release and v27 is not described as published.
+
+## Slice 01 Evidence - 2026-05-24
+
+- Added `src/create-quiver/lib/statuses.js` with shared canonical status catalogs and alias normalization for specs, slices, runs, approvals, agents, and datasets.
+- Added `src/create-quiver/lib/project-state-resolver.js` as the shared resolver over slice discovery, graph building, deterministic ordering, scoped reads, completed-slice filtering, progress, spec grouping, and graph summaries.
+- Routed classic `plan` and `graph` commands through the shared resolver while preserving existing human output and adding `canonical_status` to machine payloads.
+- Routed AI lifecycle export/list/inspect state through the shared resolver so classic and AI surfaces agree about completed slices when `includeCompleted` is requested.
+- Added `tests/lib/project-state-resolver.test.js` for canonical statuses, scoped read safety, and plan/export agreement on completed slices.
+- Ran targeted command and library tests for resolver, AI export, plan, graph, next, and doctor.
+- Ran `npm run smoke:doctor-fixtures`.
+- Ran full Node test suite: `node --test tests/**/*.test.js` passed with 320 tests.
+- Ran `git diff --check`.
+
+## Slice 02 Evidence - 2026-05-24
+
+- Bumped lifecycle export schema to `schema_version: 2`.
+- Extended `ai export` JSON with `source_metadata`, `warnings`, `approvals`, top-level `blockers`, `evidence`, `next_steps`, `lifecycle`, and `aggregates` while preserving existing `summary`, `project`, `agents`, `runs`, `specs`, `slices`, `graph`, `migration`, and `dashboard` fields.
+- Kept source metadata sanitized by exposing the project root name rather than an absolute local path.
+- Added canonical statuses to exported slices, runs, agents, specs, and approvals.
+- Added CLI tests that parse stdout JSON directly, assert stderr is empty on success, assert unsupported formats write to stderr with non-zero exit, and assert `--include-completed` includes completed slices.
+- Ran `node --test tests/lib/ai-export-state.test.js tests/commands/ai-export.test.js`.
+- Ran `node --test tests/commands/cli-contract.test.js tests/lib/project-state-resolver.test.js`.
+- Ran full Node test suite: `node --test tests/**/*.test.js` passed with 321 tests.
+- Ran `git diff --check`.
+
+## Slice 03 Evidence - 2026-05-24
+
+- Updated approved-plan parsing to extract structured slice data from full JSON input or fenced JSON blocks inside Markdown.
+- Removed silent generic fallback behavior for plans without structured slices.
+- Added pre-write validation for duplicate slice IDs, missing dependencies, invalid slice IDs, and dependency cycles.
+- Kept `slice-00-spec-foundation` mandatory while preserving every approved implementation slice from the plan.
+- Added atomic failure coverage showing missing structured slices fail before creating a spec directory or temporary build remnant.
+- Added command-level coverage for `spec create --dry-run` failing safely when the reviewed approved plan lacks structured slices.
+- Ran `node --test tests/lib/ai-spec-generator.test.js tests/commands/spec-create.test.js tests/commands/ai-plan-spec-phase.test.js`.
+- Ran full Node test suite: `node --test tests/**/*.test.js` passed with 327 tests.
+
+## Slice 04 Evidence - 2026-05-24
+
+- Added `src/create-quiver/lib/ai/artifacts.js` to centralize clean AI output extraction, raw provider artifact persistence, local path redaction, prompt-size checks, and revise-input compaction.
+- Updated `ai plan`, `ai revise`, and `ai review-plan` persistence so saved drafts/reviews use clean provider output while raw stdout/stderr are stored separately under `.quiver/runs/<run-id>/raw/*.json`.
+- Added prompt echo stripping and provider-log edge cleanup so draft artifacts do not include provider logs or prompt echoes when useful stdout is available.
+- Added raw artifact metadata to planner approval and plan-review metadata, including `raw_artifact_path`, `output_source`, and revise `input_compaction`.
+- Preserved explicit approved draft versions while carrying raw artifact metadata from the selected draft into approved metadata.
+- Added revise-input compaction for oversized feedback, preserving decisions, risks, files, acceptance criteria, validation, blockers, dependencies, assumptions, rollback, and evidence lines.
+- Added prompt-size rejection before provider execution with an actionable `AI_PROMPT_TOO_LARGE` error.
+- Added package-safety coverage for raw AI artifacts under `.quiver/runs/*/raw/`.
+- Ran `node --test tests/commands/ai-plan.test.js tests/commands/ai-review-plan.test.js tests/lib/ai-providers.test.js tests/lib/package-safety.test.js`.
+- Ran `node --test tests/lib/ai-*.test.js tests/commands/ai-plan.test.js tests/commands/ai-review-plan.test.js`.
+- Ran full Node test suite: `node --test tests/**/*.test.js` passed with 330 tests.
+- Ran `node bin/create-quiver.js plan --spec quiver-v27-reliability-ai-workflow-hardening --include-completed`.
+- Ran `node bin/create-quiver.js graph --spec quiver-v27-reliability-ai-workflow-hardening`.
+- Ran `git diff --check`.
+
+## Slice 05 Evidence - 2026-05-24
+
+- Added `src/create-quiver/lib/locks.js` to centralize `.quiver/locks` lock acquisition, release, stale lock diagnostics, and automatic local exclusion of Quiver runtime state.
+- Hardened `spec start` and `spec close` with spec-level locks, persistent worktree reuse, stale/missing worktree detection, and actionable recovery guidance.
+- Hardened slice worktree startup to reject nested worktree creation when commands run from an existing linked worktree.
+- Hardened git helpers to detect missing paths, linked worktrees, absolute git dirs, and shared git common dirs reliably across realpath differences such as `/var` and `/private/var`.
+- Added delegated execution locks for parallel AI execution runs so duplicate concurrent run IDs fail before provider execution.
+- Added tests for stale spec worktrees, concurrent spec locks, nested slice worktrees, and delegated execution lock collisions.
+- Ran `node --test tests/lib/lifecycle.test.js tests/commands/spec-worktree.test.js tests/commands/spec-close.test.js tests/commands/ai-execute-plan.test.js`.
+- Ran full Node test suite: `node --test tests/**/*.test.js` passed with 334 tests.
+
+## Slice 06 Evidence - 2026-05-24
+
+- Hardened `check-slice --local` so it validates execution git metadata, declared write/read paths, dependency contracts, and reports exactly which checks are executed or skipped in local mode.
+- Updated `check-scope` to resolve base branches from `--base`, then `slice.git.base_branch`, then safe fallbacks instead of hardcoding `develop`.
+- Added actionable `check-handoff` failures with accepted heading aliases and a minimal copyable template for legacy handoffs, execution briefs, and closure briefs.
+- Added `spec validate` to validate spec docs, slices, JSON parseability, brief contracts, dependency cycles, safe paths, evidence references, and status references.
+- Added shared path safety helpers and applied them to slice resolution, scope validation, and AI executor prompt/scope construction so absolute, traversal, and external slice paths are rejected.
+- Synced the new `spec validate` command into generated `quiver:spec:validate` scripts, README command references, `README_FOR_AI.md`, and `docs/COMMANDS.md.template`.
+- Ran `node bin/create-quiver.js spec validate specs/quiver-v27-reliability-ai-workflow-hardening`.
+- Ran `node --test tests/lib/check-slice.test.js tests/lib/scope.test.js tests/lib/handoff.test.js tests/lib/paths.test.js tests/commands/spec-validate.test.js tests/commands/cli-contract.test.js`.
+- Ran `node --test tests/commands/spec-create.test.js tests/commands/spec-worktree.test.js tests/commands/spec-close.test.js tests/commands/ai-execute-slice.test.js tests/commands/ai-execute-plan.test.js tests/lib/scope.test.js tests/lib/check-slice.test.js tests/lib/handoff.test.js tests/lib/paths.test.js`.
+- Ran full Node test suite: `node --test tests/**/*.test.js` passed with 343 tests.
+
+## Slice 07 Evidence - 2026-05-24
+
+- Added `analyze --dry-run` as a true no-write mode that reports planned scan, project map, and AI context writes without creating `.quiver/` or `docs/`.
+- Fixed React + Vite detection so `vite.config.*` no longer classifies a project as Vue unless Vue evidence exists.
+- Added project scan source/freshness metadata through `readProjectScanStatus`, including current, legacy, partial, stale, invalid, and missing states.
+- Updated `flow` to print the context source summary and include the same metadata in JSON output.
+- Updated `doctor` examples to prefer an active non-completed slice, use the only spec when unambiguous, or fall back to placeholders when multiple specs have no active slice.
+- Added prepare-context coverage showing evidence-backed stack and command facts are preserved while unknown architecture boundaries remain marked for confirmation.
+- Added tests for analyze dry-run, React/Vite classification, scan source summaries, flow context source output, doctor active/generic examples, and prepare-context evidence behavior.
+- Ran `node --test tests/commands/analyze.test.js tests/commands/ai-onboard.test.js tests/commands/flow.test.js tests/commands/doctor.test.js tests/lib/project-scan.test.js tests/lib/doctor.test.js`.
+- Ran `npm run smoke:doctor-fixtures`.
+- Ran `node bin/create-quiver.js spec validate specs/quiver-v27-reliability-ai-workflow-hardening`.
+- Ran `git diff --check`.
+- Ran full Node test suite: `node --test tests/**/*.test.js` passed with 349 tests.
+- Ran `node bin/create-quiver.js plan --spec quiver-v27-reliability-ai-workflow-hardening --include-completed`.
+- Ran `node bin/create-quiver.js graph --spec quiver-v27-reliability-ai-workflow-hardening`.
+
+## Slice 08 Evidence - 2026-05-24
+
+- Added real `ai agent set --dry-run` preview behavior that validates the requested profile and reports the planned `.quiver/agents/profiles.json` change without writing files.
+- Updated top-level help and examples so `--help` includes the agent dry-run flow.
+- Hardened GitHub auth failures with actionable account, scope, and SSH alias guidance plus a safe `gh auth status` next command.
+- Added shell-specific path guidance for identity files and PR commands with spaces across macOS/Linux, Windows PowerShell, Git Bash, and WSL.
+- Updated `flow` to report the detected package manager and matching generated `quiver:flow` script command.
+- Updated init/migrate auto-install fallback warnings to respect the detected package manager instead of always printing npm.
+- Synced `README.md`, `README_FOR_AI.md`, and `docs/COMMANDS.md.template` with the new help/auth/dry-run behavior.
+- Ran `node --test tests/commands/cli-contract.test.js tests/commands/ai-agent.test.js tests/lib/ai-github.test.js tests/commands/flow.test.js`.
+- Ran `node --test tests/commands/cli-contract.test.js tests/commands/ai-agent.test.js tests/lib/ai-github.test.js tests/commands/flow.test.js tests/lib/init-docs.test.js`.
+- Ran `node --test tests/commands/cli-contract.test.js tests/commands/ai-agent.test.js tests/lib/ai-github.test.js tests/lib/doctor.test.js tests/commands/flow.test.js tests/lib/init-docs.test.js`.
+- Ran `npm run smoke:doctor-fixtures`.
+- Ran `node bin/create-quiver.js spec validate specs/quiver-v27-reliability-ai-workflow-hardening`.
+- Ran `node --test tests/**/*.test.js` passed with 354 tests.
+- Ran `node bin/create-quiver.js plan --spec quiver-v27-reliability-ai-workflow-hardening --include-completed`.
+- Ran `node bin/create-quiver.js graph --spec quiver-v27-reliability-ai-workflow-hardening`.
+- Ran `git diff --check`.
+
+## Slice 09 Evidence - 2026-05-24
+
+- Extended the sanitized doctor fixture matrix to cover Pixel Quiver-style completed specs, multiple-spec fallback behavior, stale generated context, old `.quiver` state, no-Git projects, and paths with spaces.
+- Hardened `scripts/ci/smoke-doctor-fixtures.js` so every declared fixture state must have executable coverage references and those references must exist.
+- Added doctor command coverage for stale generated docs when the scan is newer than `docs/PROJECT_MAP.md`.
+- Added doctor command coverage for old incomplete `.quiver` state so legacy projects recommend `migrate` instead of `init`.
+- Extended `scripts/ci/smoke-create-quiver.sh` to smoke `flow` package-manager guidance, source `ai agent set --dry-run`, packaged CLI `--help`, packaged `flow`, and packaged `ai agent set --dry-run`.
+- Synced `README_FOR_AI.md`, `ROADMAP.md`, `CHANGELOG.md`, `README.md`, v27 `STATUS.md`, `SPEC.md`, `EXECUTION_PLAN.md`, `pr.md`, and this evidence report with the implemented-but-unpublished v27 state.
+- Ran `node --test tests/commands/doctor.test.js`.
+- Ran `npm run smoke:doctor-fixtures`.
+- Ran `npm run smoke:create-quiver`.
+- Ran `npm run smoke:guided-workflow`.
+- Ran `npm run package:quiver`.
+- Ran full Node test suite: `node --test tests/**/*.test.js` passed with 356 tests.
+- Ran `node bin/create-quiver.js spec validate specs/quiver-v27-reliability-ai-workflow-hardening`.
+- Ran `node bin/create-quiver.js plan --spec quiver-v27-reliability-ai-workflow-hardening --include-completed`.
+- Ran `node bin/create-quiver.js graph --spec quiver-v27-reliability-ai-workflow-hardening --include-completed`.
+- Ran `node bin/create-quiver.js next --spec quiver-v27-reliability-ai-workflow-hardening`; no ready slices remain.
+- Ran targeted regression suite: `node --test tests/commands/doctor.test.js tests/lib/project-state-resolver.test.js tests/commands/plan.test.js tests/commands/graph.test.js` passed with 31 tests.
+- Ran `git diff --check`.
+
+## Spec Package Validation - 2026-05-24
+
+- Every `slice.json` under `specs/quiver-v27-reliability-ai-workflow-hardening` parsed successfully with Node.
+- Every `EXECUTION_BRIEF.md` passed `node bin/create-quiver.js check-handoff`.
+- Every `CLOSURE_BRIEF.md` passed `node bin/create-quiver.js check-handoff`.
+- `node bin/create-quiver.js plan --spec quiver-v27-reliability-ai-workflow-hardening --include-completed` passed and reported 10 planned slices.
+- `node bin/create-quiver.js graph --spec quiver-v27-reliability-ai-workflow-hardening` passed and produced the expected dependency levels.
+- `node bin/create-quiver.js check-slice --local <slice.json>` passed for all 10 slices.
+- `git diff --check` passed.
+
+## Slice Evidence
+
+| Slice | Evidence |
+|---|---|
+| slice-00 | Completed: coverage matrix, command contracts, v24/v25/v26 audit, source-of-truth docs sync, and spec package validation. |
+| slice-01 | Completed: shared resolver, canonical status catalogs, classic/AI resolver adapters, scoped-read tests, completed-slice consistency tests, and targeted validation. |
+| slice-02 | Completed: schema v2 export contract, pure stdout/stderr CLI checks, completed-slice export coverage, source metadata, warnings, approvals, evidence, next steps, lifecycle, and aggregates. |
+| slice-03 | Completed: structured approved-plan extraction, no generic fallback, duplicate/dependency/cycle validation, eight-slice preservation, safe failure cleanup, and command coverage. |
+| slice-04 | Completed: clean drafts/reviews, redacted run-scoped raw provider artifacts, revise compaction, prompt-size guardrails, approval metadata, and raw artifact package-safety coverage. |
+| slice-05 | Completed: spec/slice worktree locks, stale and missing worktree recovery, nested worktree prevention, delegated run lock safety, and lifecycle/git helper coverage. |
+| slice-06 | Completed: stronger local slice gates, base-aware scope validation, actionable handoff templates, spec validate, and repo-bound path safety. |
+| slice-07 | Completed: read-only analyze dry-run, React/Vite stack detection, scan source/freshness reporting, flow context source output, active/generic doctor examples, and prepare-context evidence coverage. |
+| slice-08 | Completed: agent profile dry-run, grouped help sync, cross-platform path guidance, GitHub account/scope/alias diagnostics, package-manager-aware flow guidance, install fallback messages, and focused command/library tests. |
+| slice-09 | Completed: sanitized fixture matrix coverage, fixture coverage validator, stale-doc and old-state doctor regressions, source and packaged CLI smokes, full test suite, package smoke, and docs/release readiness sync. |

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.