create-quiver 0.12.0 → 0.13.0

package/specs/quiver-v26-0121-smoke-hardening/slices/slice-07-smoke-release-readiness/EXECUTION_BRIEF.md

@@ -0,0 +1,55 @@
+# EXECUTION BRIEF - slice-07: Smoke and release readiness
+
+## Context
+
+This final slice proves the hotfix is ready for PR, merge, and later npm publication. It should not publish npm itself.
+
+## Objective
+
+Run full validation, prepare `0.12.1` package metadata, perform candidate tarball smoke, and record evidence.
+
+## Scope
+
+- Version metadata.
+- Changelog/release notes.
+- Test and smoke scripts if needed.
+- Evidence report and PR body.
+
+## Acceptance Criteria
+
+- Full test suite passes.
+- Required smokes pass.
+- Candidate tarball smoke passes from `/private/tmp`.
+- Package metadata targets `0.12.1`.
+- Evidence and PR body are updated.
+
+## Technical Plan Summary
+
+Integrate all previous slices, run package safety and clean install smoke, then update release artifacts for PR review.
+
+## Suggested Execution Steps
+
+1. Confirm all prior slices are complete.
+2. Bump package metadata to `0.12.1`.
+3. Run full test and smoke suite.
+4. Run `npm pack` and smoke the tarball from `/private/tmp`.
+5. Update `EVIDENCE_REPORT.md`, `STATUS.md`, `CHANGELOG.md`, and `pr.md`.
+6. Leave npm publication for post-merge release.
+
+## Restrictions
+
+- Do not publish npm.
+- Do not create the real demo project in `/Prueba`.
+- Do not ignore failed smoke output.
+
+## Risks
+
+- Tarball smoke may reveal packaging-only issues not covered by local tests.
+
+## Completion Checklist
+
+- [ ] Full tests passed.
+- [ ] Smokes passed.
+- [ ] Tarball smoke passed.
+- [ ] Evidence recorded.
+- [ ] Version metadata ready.

package/specs/quiver-v26-0121-smoke-hardening/slices/slice-07-smoke-release-readiness/slice.json

@@ -0,0 +1,92 @@
+{
+  "slice_id": "slice-07-smoke-release-readiness",
+  "ticket": "QUIVER-26-07",
+  "type": "release",
+  "title": "Smoke and release readiness",
+  "objective": "Validate the hotfix end to end, prepare 0.12.1 package metadata, and record evidence before PR and publication.",
+  "description": "Run the full validation suite, candidate tarball smoke, documentation sync, version bump, evidence updates, and release-readiness checks.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "smoke-release-readiness",
+    "branch_name": "feature/QUIVER-26-07-smoke-release-readiness"
+  },
+  "files": [
+    "package.json",
+    "package-lock.json",
+    "CHANGELOG.md",
+    "README_FOR_AI.md",
+    "ROADMAP.md",
+    "scripts/ci/**",
+    "specs/quiver-v26-0121-smoke-hardening/**",
+    "tests/**"
+  ],
+  "expected_read_paths": [
+    "package.json",
+    "package-lock.json",
+    "CHANGELOG.md",
+    "scripts/release-quiver.sh",
+    "scripts/package-quiver.sh",
+    "scripts/ci/**",
+    "specs/quiver-v26-0121-smoke-hardening/EVIDENCE_REPORT.md"
+  ],
+  "allowed_write_paths": [
+    "package.json",
+    "package-lock.json",
+    "CHANGELOG.md",
+    "README_FOR_AI.md",
+    "ROADMAP.md",
+    "scripts/ci/**",
+    "specs/quiver-v26-0121-smoke-hardening/**",
+    "tests/**"
+  ],
+  "depends_on": [
+    "slice-01-cli-help-version-contract",
+    "slice-02-init-doc-links-and-flow-guidance",
+    "slice-03-ai-approval-review-consistency",
+    "slice-04-local-validation-brief-contracts",
+    "slice-05-demo-scaffold-readiness",
+    "slice-06-plan-graph-scope-performance"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Final integration and release readiness must run after every implementation slice.",
+  "must": [
+    "Bump package metadata to 0.12.1 only after implementation slices are complete.",
+    "Run full local tests and smokes.",
+    "Run candidate tarball smoke from a clean temp directory.",
+    "Record evidence and remaining risks.",
+    "Prepare PR body and release notes without publishing npm."
+  ],
+  "not_included": [
+    "Publishing npm before PR merge.",
+    "Creating the real Quiver Spec Viewer project.",
+    "Skipping failed smoke results."
+  ],
+  "acceptance": [
+    "node --test tests/**/*.test.js passes.",
+    "npm run smoke:create-quiver passes.",
+    "npm run smoke:guided-workflow passes.",
+    "npm run smoke:doctor-fixtures passes.",
+    "git diff --check passes.",
+    "Candidate tarball smoke validates init, analyze, doctor, flow, AI dry-runs, demo, and validate.",
+    "CHANGELOG.md and evidence report document 0.12.1 readiness."
+  ],
+  "tests": [
+    "node --test tests/**/*.test.js",
+    "npm run smoke:create-quiver",
+    "npm run smoke:guided-workflow",
+    "npm run smoke:doctor-fixtures",
+    "npm pack",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Use /private/tmp for tarball smoke.",
+    "Do not rely on the local checkout path for candidate validation.",
+    "After merge and publish, verify npm with npm view create-quiver version."
+  ],
+  "estimated_hours": 4,
+  "status": "completed",
+  "blocked_reason": null,
+  "actual_hours": 3,
+  "completed_at": "2026-05-23T00:00:00-0300"
+}

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

@@ -0,0 +1,67 @@
+# Audit - v24/v25/v26 Against Pixel Quiver Evidence
+
+## Purpose
+
+This audit records the starting point for v27. It separates already existing implementation surfaces from behavior that remains partial, fragile, or unproven by the Pixel Quiver dogfooding evidence.
+
+## Audited Inputs
+
+- `README_FOR_AI.md`
+- `ROADMAP.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/**`
+- Pixel Quiver evidence files containing `QP-001..QP-019` and `QIS-001..QIS-022`
+
+## Existing Coverage Observed
+
+The current repository already contains implementation and tests in several areas that v27 must reuse instead of rebuilding from scratch:
+
+| Area | Existing evidence in repo |
+|---|---|
+| `flow`, onboarding, and first-use guidance | `src/create-quiver/commands/flow.js`, `tests/commands/flow.test.js`, v24/v25/v26 docs. |
+| Context analysis and context preparation | `src/create-quiver/commands/analyze.js`, `src/create-quiver/commands/prepare-context.js`, `tests/commands/analyze.test.js`, `tests/commands/prepare-context.test.js`. |
+| Doctor diagnostics | `src/create-quiver/commands/doctor.js`, `tests/commands/doctor.test.js`, doctor fixture scripts. |
+| AI lifecycle commands | `src/create-quiver/commands/ai-onboard.js`, `ai-plan.js`, `ai-revise.js`, `ai-approve.js`, `ai-execute-plan.js`, `ai-export.js`, and related tests. |
+| AI export/state helpers | `src/create-quiver/lib/ai/export-state.js`, `tests/lib/ai-export-state.test.js`, `tests/commands/ai-export.test.js`. |
+| Spec and worktree lifecycle | `src/create-quiver/commands/spec-create.js`, `spec-start.js`, `spec-status.js`, `spec-close.js`, `src/create-quiver/lib/spec-worktrees.js`, related command tests. |
+| Scope, slice, handoff, and path validation | `src/create-quiver/commands/check-scope.js`, `check-slice.js`, `check-handoff.js`, `src/create-quiver/lib/scope.js`, `handoff.js`, `paths.js`, related tests. |
+| Evidence redaction and package safety | `src/create-quiver/lib/evidence.js`, `tests/lib/evidence.test.js`, `tests/lib/package-safety.test.js`. |
+| Cross-platform path handling | `tests/lib/paths.test.js` includes Windows-style path normalization and project-root safety coverage. |
+
+## Dogfooding Gaps Still Requiring v27 Work
+
+| Gap | Evidence | Why existing coverage is not enough |
+|---|---|---|
+| Classic and AI commands still disagree on completed slices. | QP-003, QIS-006 | Tests cover command names and helper output, but Pixel Quiver showed inconsistent lifecycle state across `plan --include-completed`, `ai inspect`, and `ai export`. |
+| JSON export is not stable enough for dashboards. | QP-019, QIS-004, QIS-022 | Existing `ai export` support exists, but the dashboard contract needs schema versioning, source metadata, lifecycle data, agents, runs, approvals, blockers, evidence, aggregates, and pure stdout JSON. |
+| `spec create` can ignore approved plan structure. | QP-011, QP-012, QIS-014, QIS-015 | Existing spec creation exists, but approved technical-plan parsing, structured slice validation, deterministic naming, and safe failure cleanup need direct regression fixtures. |
+| AI artifacts can contain prompt echo or raw provider noise. | QP-010, QIS-013 | Existing AI commands do not fully prove clean draft/raw transcript separation for real provider-style output. |
+| Revision feedback can exceed context limits. | QP-009, QIS-012 | Token compaction and safe refusal need explicit behavior before provider overflow. |
+| Worktree lifecycle needs persistent one-spec behavior and recovery. | QP-018, QIS-021 | Worktree helpers exist, but dogfooding showed nested/conflicting worktree confusion and missing recovery guidance. |
+| Validation gates miss execution preconditions. | QP-013, QP-016, QP-017, QIS-003, QIS-016, QIS-019, QIS-020 | Existing validation commands exist, but they must align with actual execution needs, base branch resolution, handoff templates, and strict spec validation. |
+| `analyze --dry-run` must be strictly read-only and stack detection must improve. | QP-005, QP-014, QIS-007, QIS-017 | Analyzer tests exist, but v27 needs mutation guards and React/Vite fixtures based on dogfooding failures. |
+| `flow`, `doctor`, and `prepare-context` must use current resolver state. | QP-001, QP-006, QP-015, QIS-001, QIS-008, QIS-018 | Existing diagnostics exist, but stale examples and missing evidence-backed next steps remain a real-world problem. |
+| Cross-platform help and GitHub auth guidance are incomplete. | QP-002, QP-004, QP-007, QIS-002, QIS-009, QIS-010, QIS-011 | Existing docs/help exist, but they must be more explicit for Windows/macOS/Linux, `gh`, aliases, and AI agent setup dry-runs. |
+
+## Source-of-Truth Sync
+
+`README_FOR_AI.md`, `ROADMAP.md`, and `CHANGELOG.md` were updated before implementation started so they do not describe v27 as already released.
+
+The current sync decision is:
+
+- v26 / `0.12.1` is shipped.
+- v27 is active/planned implementation work.
+- v27 must not be described as published until release smoke and npm publication happen.
+
+## Implementation Guidance
+
+- Treat v24/v25/v26 as prior art, not proof of closure.
+- Prefer extending existing commands and tests over creating duplicate lifecycle paths.
+- Add dogfooding fixtures that reproduce the Pixel Quiver failures in sanitized form.
+- Keep compatibility where users may depend on existing command names.
+- Introduce shared contracts first, then command-specific behavior.
+

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