create-quiver 0.12.1 → 0.14.0

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

@@ -0,0 +1,125 @@
+# Command Contracts - Quiver v27 Reliability and AI Workflow Hardening
+
+## Purpose
+
+These contracts apply to every command touched by v27. A slice may add stricter behavior, but it must not weaken these defaults without documenting a migration path.
+
+## Output Streams
+
+- Human-readable progress, hints, warnings, and debug text go to `stderr` when `--format json` is used.
+- Machine-readable JSON goes to `stdout` only.
+- A successful JSON command must produce valid JSON parseable without stripping banners, logs, colors, prompts, or extra lines.
+- Non-JSON human commands may use `stdout` for primary content and `stderr` for warnings/errors.
+- Error details must be actionable and include the command area, failing precondition, and next safe step when known.
+
+## Exit Codes
+
+| Code | Meaning |
+|---:|---|
+| 0 | Success. Requested operation completed or dry-run was valid. |
+| 1 | General command failure with no more specific category. |
+| 2 | Invalid user input, unsupported option, missing required argument, or schema validation failure. |
+| 3 | Unsafe repository state, missing dependency, dirty worktree, stale lock, or failed precondition. |
+| 4 | External tool/provider failure, including AI provider, `gh`, git, npm, or package manager failures. |
+| 5 | Partial state was detected and recovery is required. The command must report exact files/state involved. |
+
+## Dry-Run
+
+- `--dry-run` is strictly read-only.
+- A dry-run command must not write, create, delete, rename, stage, commit, or modify files anywhere in the repository.
+- This includes `.quiver/`, `docs/`, `specs/`, generated logs, cache files, lock files, and package artifacts.
+- Dry-run output must clearly state what would change, where it would be written, and which validations would run.
+- If a command cannot guarantee read-only behavior, it must fail before doing work and explain why dry-run is unsupported.
+
+## Write Classes
+
+Every writing command must fit one of these classes:
+
+| Class | Meaning | Requirements |
+|---|---|---|
+| inspect | Read-only command. | Must not write. Supports JSON when useful. |
+| generate | Creates new files from validated input. | Must preflight collisions and fail atomically where possible. |
+| update | Modifies existing files or state. | Must backup or preserve recoverable previous valid state when practical. |
+| execute | Performs implementation or lifecycle action. | Must validate dependencies, scope, git state, and target worktree first. |
+| external | Calls git, GitHub, package manager, or AI provider. | Must report external command failure clearly and preserve local state. |
+
+## Atomicity and Partial State
+
+- Commands that write multiple files must validate all inputs before the first write whenever possible.
+- If partial writes can occur, the command must report exactly which files were written and how to recover.
+- Failed generation must not leave empty directories unless they are explicitly reported as recoverable partial state.
+- Existing valid files must not be replaced with invalid output.
+
+## Idempotency
+
+- Re-running a successful command with the same inputs should either produce the same result or report that no change is needed.
+- Collision handling must be deterministic and documented.
+- Commands that create slugs, spec ids, slice ids, branches, or worktree paths must use stable generation rules.
+
+## Path Safety
+
+- All write paths must resolve inside the project root unless the command explicitly documents an external target.
+- Path traversal (`..`), symlink escape, absolute-path injection, and writing into parent directories must be rejected.
+- Paths printed in help or next-step examples must be copy-safe when project paths include spaces.
+- Shell examples must be safe for the target shell family: macOS/Linux POSIX shells, Windows PowerShell, Git Bash, and WSL.
+
+## Root Detection
+
+- Commands must resolve and report the project root used for reads and writes.
+- Running from a subdirectory, a worktree, or a simple monorepo package must produce deterministic root resolution.
+- If multiple plausible roots exist, the command must stop and ask for an explicit root or print the safe command to run.
+
+## Package Manager Detection
+
+- Quiver must prefer the package manager indicated by lockfiles and package metadata.
+- Detection priority must be deterministic and documented.
+- Suggested commands must match the detected package manager: npm, pnpm, yarn, or bun.
+- If detection is ambiguous, Quiver must report the ambiguity and use the safest explicit command form.
+
+## Deterministic Ordering
+
+- JSON arrays for specs, slices, agents, runs, approvals, blockers, evidence, and next steps must be sorted deterministically.
+- Stable order should prefer declared dependency order, numeric slice order, created timestamp, and then id as a tiebreaker.
+- Human summaries must follow the same order where practical.
+
+## Status Catalogs
+
+Commands must use shared canonical statuses from the resolver once slice-01 introduces them. Until then, commands must not invent one-off lifecycle names.
+
+Minimum canonical families:
+
+- Spec: `draft`, `planned`, `approved`, `in-progress`, `blocked`, `review`, `done`, `archived`
+- Slice: `planned`, `ready`, `in-progress`, `blocked`, `review`, `completed`, `skipped`
+- Run: `draft`, `waiting-approval`, `approved`, `running`, `blocked`, `done`, `failed`
+- Agent: `idle`, `planning`, `reading`, `coding`, `reviewing`, `blocked`, `waiting-approval`, `done`
+- Approval: `pending`, `approved`, `rejected`, `superseded`
+
+## JSON Schema and Versioning
+
+- Machine-readable exports must include `schema_version`.
+- Breaking changes require a new schema version and migration guidance.
+- Payloads must include `generated_at`, `project_root`, `source`, and `warnings`.
+- Optional fields must be present as empty arrays/objects when that makes downstream parsing simpler and stable.
+
+## Legacy and Strict Modes
+
+- Existing commands should preserve legacy behavior by default when changing output would break users.
+- New strict behavior may be introduced behind explicit flags or by adding new command variants.
+- When legacy behavior is used, output should point to the stricter command or flag where appropriate.
+
+## Security and Redaction
+
+- Secrets, tokens, auth headers, provider keys, private URLs, and unnecessary absolute local paths must be redacted from committed fixtures and generated evidence.
+- Raw AI transcripts must be stored separately from clean drafts.
+- Redaction must happen before writing logs that may be committed.
+
+## Validation Expectations
+
+Each implementation slice must add or update tests for the contracts it touches. At minimum:
+
+- Successful `--format json` output parses as JSON.
+- Failing commands write diagnostics to `stderr` and exit non-zero.
+- Dry-run commands leave the git diff unchanged.
+- Path safety rejects writes outside the project root.
+- Fixtures preserve deterministic order.
+

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

@@ -0,0 +1,74 @@
+# Coverage Matrix - Quiver v27 Reliability and AI Workflow Hardening
+
+## Purpose
+
+This matrix maps every Pixel Quiver dogfooding problem (`QP-*`) and improvement suggestion (`QIS-*`) to the v27 implementation slice that must close it.
+
+The source files are evidence inputs, not fixtures. Do not copy unsanitized local paths, user names, command output, or project-specific data into committed fixtures without explicit sanitization.
+
+## Problem Coverage
+
+| Evidence | Area | Primary Slice | Risk if missed | Validation strategy |
+|---|---|---|---|---|
+| QP-001 | `flow` source discovery and stale examples | slice-07 | Users and agents follow incorrect next steps. | Fixture with current and stale spec state; `flow` output checked against resolver state. |
+| QP-002 | Paths with spaces and copy-safe examples | slice-08 | Commands fail in common macOS/Linux/Windows project paths. | Cross-platform path formatting snapshots for macOS, Linux, PowerShell, Git Bash, and WSL examples. |
+| QP-003 | Classic and AI commands disagree about completed slices | slice-01, slice-02 | Agents act on incomplete or stale lifecycle state. | Shared resolver tests plus export tests with completed, planned, blocked, and active slices. |
+| QP-004 | GitHub authentication and alias guidance | slice-08 | PR creation or preflight fails late with unclear recovery. | `ai doctor` and PR preflight fixtures for missing `gh`, wrong account, missing scopes, and alias expectations. |
+| QP-005 | Analyzer misdetects React/Vite context | slice-07 | Context docs are wrong, causing bad onboarding and bad prompts. | React/Vite fixture with expected stack detection and no false Vue classification. |
+| QP-006 | `prepare-context` lacks evidence and next-step clarity | slice-07 | Agents cannot trust generated context or understand what to do next. | Snapshot output includes evidence, stale/missing docs, and next safe command. |
+| QP-007 | Agent docs gaps and missing prompts | slice-07, slice-08 | Users manually invent onboarding and execution prompts. | Docs/help tests confirm planner, executor, and handoff guidance exists and links to generated files. |
+| QP-008 | Source-of-truth docs drift | slice-00, slice-07 | README, roadmap, and AI docs contradict product state. | Documentation audit plus docs sync checks in final release slice. |
+| QP-009 | `ai revise` grows context without compaction | slice-04 | Planner calls exceed provider limits or waste tokens. | Token-limit fixture validates compacted feedback or safe refusal before provider overflow. |
+| QP-010 | Prompt echo and raw logs mix into final drafts | slice-04 | Specs and plans contain unusable provider noise. | AI artifact fixture separates clean draft from raw transcript and redacts secrets. |
+| QP-011 | `spec create` ignores approved plan structure | slice-03 | Quiver creates generic or incomplete scaffolds after approval. | Approved-plan fixture creates expected spec, slices, handoffs, execution plan, and PR body. |
+| QP-012 | Failed `spec create` leaves empty dirs | slice-03 | Repo state becomes dirty and confusing after failure. | Failure fixture asserts no partial writes or exact recovery report. |
+| QP-013 | `check-slice --local` misses execution preconditions | slice-06 | Later execution fails after a passing local check. | Local check fixture validates required git, worktree, brief, dependency, and scope preconditions or lists skipped checks. |
+| QP-014 | `analyze --dry-run` writes files | slice-07 | Users cannot safely inspect impact before generating docs. | Dry-run test asserts no file changes, including `.quiver/`, `docs/`, and `specs/`. |
+| QP-015 | `doctor` points to wrong spec/slice examples | slice-07 | First-use guidance sends users to stale work. | Doctor fixture derives active spec/slice from resolver state. |
+| QP-016 | `check-scope` assumes wrong base branch | slice-06 | Valid branches fail scope checks or bad diffs are compared. | Scope fixtures cover `--base`, `git.base_branch`, remote default, and fallback order. |
+| QP-017 | `check-handoff` missing actionable template/aliases | slice-06 | Users cannot quickly fix invalid briefs. | Handoff fixture prints missing headings, minimal template, and supported aliases. |
+| QP-018 | Worktree lifecycle causes nested/conflicting worktrees | slice-05 | Spec work becomes scattered, dirty, or unsafe to merge. | Worktree fixtures cover persistent spec worktree, locks, stale state, dirty state, and recovery. |
+| QP-019 | JSON export not dashboard-ready | slice-02 | UIs and agents need custom parsing or cannot consume Quiver state. | JSON schema and fixture parse tests with deterministic output. |
+
+## Suggestion Coverage
+
+| Evidence | Area | Primary Slice | Risk if missed | Validation strategy |
+|---|---|---|---|---|
+| QIS-001 | Improve `flow` source references | slice-07 | Flow output remains untrustworthy. | Flow snapshot includes source file, status, and active target. |
+| QIS-002 | Quote/copy-safe command examples | slice-08 | Users with spaces in paths hit preventable failures. | Help snapshot validates quoted examples per shell family. |
+| QIS-003 | Add/strengthen `spec validate` | slice-06 | Broken specs/slices pass until later commands fail. | Spec validation fixture covers schema, dependencies, briefs, worktree hints, and source metadata. |
+| QIS-004 | Export canonical dashboard data | slice-02 | Dashboard and agents keep using unstable ad-hoc output. | Export schema fixture validates required top-level datasets and aggregates. |
+| QIS-005 | Generate executor handoff packages | slice-06 | Executors need too much context and burn tokens. | Handoff package fixture includes only selected slice, briefs, constraints, evidence, and validation commands. |
+| QIS-006 | One resolver for classic and AI commands | slice-01 | Commands keep disagreeing about lifecycle state. | Unit tests require classic and AI command adapters to consume the same resolver output. |
+| QIS-007 | Improve framework detection | slice-07 | Context docs misrepresent stack and workflow. | Analyzer fixtures for React/Vite, package-manager variants, and unknown stack. |
+| QIS-008 | Evidence-backed context generation | slice-07 | Generated docs cannot be trusted or maintained. | `prepare-context` output references source files and marks assumptions. |
+| QIS-009 | GitHub/PR readiness diagnostics | slice-08 | PR creation fails late. | Doctor/preflight output includes `gh`, auth, account, scopes, alias, remote, and next action. |
+| QIS-010 | Agent onboarding guide | slice-07, slice-08 | Users manually paste long prompts repeatedly. | README/help docs expose planner/executor/doctor/reviewer flows with minimal-context guidance. |
+| QIS-011 | `ai agent set --dry-run` or equivalent preflight | slice-08 | Users configure agents without seeing effect or missing dependencies. | Dry-run setup output lists provider command, availability, and files that would change without writing. |
+| QIS-012 | Token compaction for revisions | slice-04 | Iteration becomes expensive and brittle. | Revision fixture compacts accepted history and preserves required decisions. |
+| QIS-013 | Separate clean draft and raw transcript | slice-04 | Prompt echo corrupts committed docs. | Artifact tests assert separate files and redacted raw output. |
+| QIS-014 | Approved-plan parser | slice-03 | Structured human approvals cannot become accurate slices. | Parser fixtures cover valid, invalid, partial, and ambiguous slice blocks. |
+| QIS-015 | Deterministic slug/path generation | slice-03 | Repeated `spec create` creates inconsistent names or collisions. | Slug fixtures cover accents, spaces, punctuation, long titles, and collisions. |
+| QIS-016 | Stronger slice execution gate | slice-06 | Execution starts with missing dependencies or invalid scope. | `start-slice`/`check-slice` fixture blocks unsafe execution and prints recovery. |
+| QIS-017 | Strict dry-run contract | slice-07 | Trust in Quiver inspection commands is lost. | Dry-run mutation guard across analysis/context commands. |
+| QIS-018 | Doctor active-state awareness | slice-07 | Doctor suggests stale examples. | Doctor fixture uses resolver current state and reports stale docs. |
+| QIS-019 | Base branch configuration | slice-06 | Scope checks fail in repos using `main`, `develop`, or custom branches. | Base resolution fixture covers CLI option, slice config, git config, remote HEAD, fallback. |
+| QIS-020 | Handoff template guidance | slice-06 | Invalid briefs are hard to fix. | `check-handoff` output includes minimal copyable template. |
+| QIS-021 | Persistent spec worktree lifecycle | slice-05 | One-spec-per-worktree model remains manual and error-prone. | Worktree commands create/reuse/report one persistent worktree per spec. |
+| QIS-022 | Machine-readable output contract | slice-02 | Agents cannot parse command output safely. | `--format json` tests validate stdout-only JSON, stderr diagnostics, schema versioning, and deterministic ordering. |
+
+## Slice Responsibility Summary
+
+| Slice | Responsibility |
+|---|---|
+| slice-00 | Documentary foundation, evidence mapping, command contracts, v24/v25/v26 audit. |
+| slice-01 | Shared state resolver and canonical statuses for specs, slices, runs, approvals, agents, evidence, and worktrees. |
+| slice-02 | Stable JSON export and pure machine-readable command output. |
+| slice-03 | Approved technical plan parsing and reliable spec/slice generation. |
+| slice-04 | AI draft storage, raw logs, redaction, and token compaction. |
+| slice-05 | Persistent spec worktree lifecycle, locks, recovery, and no nested worktrees. |
+| slice-06 | Validation gates, scope safety, handoff packages, and local execution preconditions. |
+| slice-07 | Context analysis, prepare-context, flow, doctor, dry-run safety, and source-backed docs. |
+| slice-08 | Cross-platform help, GitHub auth, agent setup guidance, and first-use DX. |
+| slice-09 | Fixtures, smoke tests, docs sync, package smoke, and release readiness. |
+

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.