create-quiver 0.12.1 → 0.13.0

package/specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-04-ai-artifact-storage-redaction-and-token-compaction/CLOSURE_BRIEF.md

@@ -0,0 +1,31 @@
+# CLOSURE BRIEF - slice-04: AI artifact storage, redaction, and token compaction
+
+## Summary
+
+Implemented AI artifact hardening for planner and review flows. Draft/review artifacts now persist clean provider output, raw stdout/stderr are stored separately under run-scoped `.quiver/runs/<run-id>/raw/*.json`, secrets and local paths are redacted, oversized revise inputs are compacted before provider execution, and package safety blocks raw AI artifacts from npm tarballs.
+
+## Validation Against Acceptance Criteria
+
+- Draft files contain useful output only: covered by `ai plan stores clean drafts and separates redacted raw provider logs`.
+- Raw logs are run-scoped and redacted: covered by `raw_artifact_path` assertions in `ai-plan` and `ai-review-plan` tests.
+- Oversized revise inputs are compacted or blocked: covered by `ai revise compacts oversized feedback before provider execution` and `ai plan rejects oversized prompts before provider execution`.
+- Approved versions remain explicit: existing versioned approval tests still pass and approved metadata carries the selected draft metadata.
+- Package safety blocks raw AI artifacts: covered by `tests/lib/package-safety.test.js`.
+
+## Changes
+
+- Added `src/create-quiver/lib/ai/artifacts.js`.
+- Updated `src/create-quiver/commands/ai.js` for clean/raw separation, prompt-size guards, and revise compaction.
+- Updated `src/create-quiver/lib/approvals.js` and `src/create-quiver/lib/ai/plan-review.js` to persist raw artifact metadata.
+- Updated `src/create-quiver/lib/package-safety.js` to classify `.quiver/runs/*/raw/` as unsafe package content.
+- Added/updated tests in `tests/commands/ai-plan.test.js`, `tests/commands/ai-review-plan.test.js`, and `tests/lib/package-safety.test.js`.
+
+## Remaining Risks
+
+- Provider-specific log formats can vary. The cleanup intentionally strips prompt echoes and common leading/trailing provider log lines while preserving the provider's main stdout content.
+- Raw artifacts are redacted and ignored under `.quiver/`, but future package changes should keep package-safety checks in the release path.
+
+## Follow-up Recommendations
+
+- Add provider-specific clean-output fixtures if future dogfooding finds additional Claude/Codex/Gemini transcript wrappers.
+- Consider exposing prompt-size limits in user-facing docs if users need to tune `QUIVER_AI_MAX_PROMPT_BYTES`, `QUIVER_AI_MAX_REVISION_INPUT_BYTES`, or `QUIVER_AI_COMPACTED_REVISION_INPUT_BYTES`.

package/specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-04-ai-artifact-storage-redaction-and-token-compaction/EXECUTION_BRIEF.md

@@ -0,0 +1,55 @@
+# EXECUTION BRIEF - slice-04: AI artifact storage, redaction, and token compaction
+
+## Context
+
+Pixel Quiver showed drafts polluted with provider logs and `ai revise` failures caused by very large accumulated context. This slice hardens AI artifact persistence and token control.
+
+## Objective
+
+Persist clean drafts, store raw logs separately, redact sensitive values, and compact oversized feedback safely.
+
+## Scope
+
+- AI provider/output handling
+- Approval draft persistence
+- Raw log storage
+- Redaction and package safety
+- Token compaction for revise/review flows
+
+## Acceptance Criteria
+
+- Drafts contain clean useful AI output.
+- Raw logs are separated and redacted.
+- Oversized inputs are compacted or rejected before provider execution.
+- Approved version metadata remains explicit.
+- Package safety covers raw AI artifacts.
+
+## Technical Plan Summary
+
+Add output extraction, raw transcript storage, redaction, size checks, compaction logic, and regression tests.
+
+## Suggested Execution Steps
+
+1. Inspect AI provider and approval persistence paths.
+2. Add clean/raw separation.
+3. Add redaction and package-safety rules.
+4. Add size checks and compaction.
+5. Test contaminated provider output and long feedback inputs.
+
+## Restrictions
+
+- Do not store credentials.
+- Do not weaken approval gates.
+
+## Risks
+
+- Over-compaction can remove important constraints; preserve decisions, risks, files, and criteria.
+
+## Completion Checklist
+
+- [ ] Clean draft behavior implemented.
+- [ ] Raw logs separated and redacted.
+- [ ] Compaction covered by tests.
+- [ ] Package safety updated.
+- [ ] Validation commands passed.
+

package/specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-04-ai-artifact-storage-redaction-and-token-compaction/slice.json

@@ -0,0 +1,77 @@
+{
+  "slice_id": "slice-04-ai-artifact-storage-redaction-and-token-compaction",
+  "ticket": "QUIVER-27-04",
+  "type": "implementation",
+  "title": "AI artifact storage, redaction, and token compaction",
+  "objective": "Keep AI drafts clean, persist raw provider logs separately with redaction, and prevent revise flows from exceeding provider context limits.",
+  "description": "Separates useful provider output from raw transcripts, redacts sensitive values before persistence, snapshots raw logs under run-scoped paths, and compacts long review/feedback inputs before calling providers.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v27-ai-artifacts-redaction-token-compaction",
+    "branch_name": "feature/QUIVER-27-04-v27-ai-artifacts-redaction-token-compaction"
+  },
+  "files": [
+    "src/create-quiver/lib/ai/**",
+    "src/create-quiver/lib/approvals.js",
+    "src/create-quiver/lib/package-safety.js",
+    "tests/lib/ai-*.test.js",
+    "tests/lib/package-safety.test.js",
+    "tests/commands/ai-*.test.js",
+    "specs/quiver-v27-reliability-ai-workflow-hardening/**"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/lib/ai/providers.js",
+    "src/create-quiver/lib/ai/prompt-transport.js",
+    "src/create-quiver/lib/ai/plan-review.js",
+    "src/create-quiver/lib/approvals.js",
+    "tests/commands/ai-plan.test.js",
+    "tests/commands/ai-review-plan.test.js"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/lib/ai/**",
+    "src/create-quiver/lib/approvals.js",
+    "src/create-quiver/lib/package-safety.js",
+    "tests/lib/ai-*.test.js",
+    "tests/lib/package-safety.test.js",
+    "tests/commands/ai-*.test.js",
+    "specs/quiver-v27-reliability-ai-workflow-hardening/**"
+  ],
+  "depends_on": [
+    "slice-01-core-state-resolver-and-canonical-statuses"
+  ],
+  "parallel_safe": "yes",
+  "parallel_safe_reason": "Can run after shared resolver if it avoids files touched by worktree lifecycle work.",
+  "must": [
+    "Store clean drafts separately from raw provider output.",
+    "Redact secrets and sensitive local values before persisting raw logs.",
+    "Detect oversized inputs before provider calls.",
+    "Compact feedback while preserving decisions, risks, changed files, and acceptance criteria.",
+    "Preserve approved version metadata."
+  ],
+  "not_included": [
+    "Changing provider CLI installation.",
+    "Changing spec create parsing.",
+    "Adding telemetry."
+  ],
+  "acceptance": [
+    "Draft files contain only useful AI output, not provider logs or prompt echo.",
+    "Raw logs are stored in run-scoped raw paths and redacted.",
+    "Oversized revise inputs are compacted or blocked with an actionable message before provider execution.",
+    "Approved versions remain explicit and are not inferred from latest draft filenames.",
+    "Package safety blocks unsafe raw AI artifacts from npm publication."
+  ],
+  "tests": [
+    "node --test tests/lib/ai-*.test.js tests/commands/ai-plan.test.js tests/commands/ai-review-plan.test.js",
+    "node --test tests/lib/package-safety.test.js",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Use fixtures with prompt echo and long review text.",
+    "Assert raw logs do not leak obvious token/env patterns."
+  ],
+  "estimated_hours": 5,
+  "status": "completed",
+  "completed_at": "2026-05-24",
+  "blocked_reason": null
+}

package/specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-05-worktree-lifecycle-locks-and-recovery/CLOSURE_BRIEF.md

@@ -0,0 +1,31 @@
+# CLOSURE BRIEF - slice-05: Worktree lifecycle, locks, and recovery
+
+## Summary
+
+Implemented worktree lifecycle hardening for persistent spec worktrees, slice worktree startup, and delegated parallel AI execution runs. The slice adds shared lock handling, stale/missing worktree recovery messages, nested worktree prevention, and focused tests for the production risks found in Pixel Quiver dogfooding.
+
+## Validation Against Acceptance Criteria
+
+- `spec start` dry-run and real reuse behavior remains covered by existing spec worktree tests.
+- Existing spec worktrees are reused when valid; stale or manually deleted registered worktrees now fail with recovery steps instead of being silently recreated.
+- Running slice startup from a linked worktree now rejects nested worktree creation unless it is reusing the exact registered worktree.
+- Delegated parallel execution uses a run-level lock and fails safely before provider execution when the same run is already active.
+- Dirty, missing, stale, and conflicting worktree states produce actionable recovery guidance.
+
+## Changes
+
+- Added `src/create-quiver/lib/locks.js` for `.quiver/locks` helpers and local runtime-state ignore handling.
+- Updated `src/create-quiver/lib/git.js` with linked-worktree and realpath-aware git directory helpers.
+- Updated `src/create-quiver/lib/spec-worktrees.js` with persistent worktree reuse checks, lock handling, stale path recovery, and nested worktree safeguards.
+- Updated `src/create-quiver/lib/lifecycle.js` with slice worktree locks and nested worktree prevention.
+- Updated `src/create-quiver/lib/ai/execution-plan.js` with delegated run locking.
+- Added regression coverage in `tests/lib/lifecycle.test.js` and `tests/commands/ai-execute-plan.test.js`.
+
+## Remaining Risks
+
+- Existing user-created stale locks may require manual removal after the user confirms no Quiver process is active.
+- This slice hardens lifecycle behavior but does not yet expand `check-scope`, `check-handoff`, or `spec validate`; those remain in `slice-06`.
+
+## Follow-up Recommendations
+
+- Execute `slice-06-validation-gates-and-scope-safety` next so the new lifecycle guarantees are enforced by validation gates before later context and DX work.

package/specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-05-worktree-lifecycle-locks-and-recovery/EXECUTION_BRIEF.md

@@ -0,0 +1,55 @@
+# EXECUTION BRIEF - slice-05: Worktree lifecycle, locks, and recovery
+
+## Context
+
+Pixel Quiver showed confusing worktree guidance and potential nested worktree paths. The desired workflow is one persistent worktree per spec and one commit per slice, while delegated execution may still use temporary worktrees internally.
+
+## Objective
+
+Harden worktree lifecycle, locking, and recovery.
+
+## Scope
+
+- Spec worktree lifecycle
+- Delegated execution worktree strategy
+- Git/worktree recovery messages
+- Locking for concurrent operations
+- Tests and docs evidence
+
+## Acceptance Criteria
+
+- Spec worktrees are persistent and reused.
+- Existing spec worktrees do not create nested paths.
+- Temporary worktrees remain limited to delegated parallel execution.
+- Dirty/missing/stale worktrees report recovery steps.
+- Concurrent operations are locked or rejected safely.
+
+## Technical Plan Summary
+
+Clarify worktree identity, add detection for current worktree context, add locks and recovery tests.
+
+## Suggested Execution Steps
+
+1. Inspect spec worktree and executor code.
+2. Define worktree modes and lock locations.
+3. Implement context detection and recovery messaging.
+4. Add tests for root, worktree, dirty, missing, stale, and delegated paths.
+5. Update docs/evidence.
+
+## Restrictions
+
+- Do not remove delegated parallel capability.
+- Do not force destructive cleanup without explicit option.
+
+## Risks
+
+- Existing users may rely on current branch names; preserve compatibility where possible.
+
+## Completion Checklist
+
+- [ ] Persistent spec worktree behavior covered.
+- [ ] Nested worktree prevention covered.
+- [ ] Delegated worktrees still pass tests.
+- [ ] Lock/recovery behavior covered.
+- [ ] Validation commands passed.
+

package/specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-05-worktree-lifecycle-locks-and-recovery/slice.json

@@ -0,0 +1,84 @@
+{
+  "slice_id": "slice-05-worktree-lifecycle-locks-and-recovery",
+  "ticket": "QUIVER-27-05",
+  "type": "implementation",
+  "title": "Worktree lifecycle, locks, and recovery",
+  "objective": "Harden the spec worktree lifecycle so Quiver supports one persistent worktree per spec, one commit per slice, temporary delegated worktrees, locks, and recovery.",
+  "description": "Clarifies spec vs temporary slice worktrees, prevents nested/conflicting paths, handles dirty root and missing worktrees, adds locks for concurrent execution, and reports recovery paths.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v27-worktree-lifecycle-locks-recovery",
+    "branch_name": "feature/QUIVER-27-05-v27-worktree-lifecycle-locks-recovery"
+  },
+  "files": [
+    "src/create-quiver/lib/spec-worktrees.js",
+    "src/create-quiver/lib/lifecycle.js",
+    "src/create-quiver/lib/locks.js",
+    "src/create-quiver/lib/ai/execution-plan.js",
+    "src/create-quiver/lib/ai/executor.js",
+    "src/create-quiver/lib/git.js",
+    "tests/lib/*worktree*.test.js",
+    "tests/commands/spec-worktree.test.js",
+    "tests/commands/ai-execute-plan.test.js",
+    "specs/quiver-v27-reliability-ai-workflow-hardening/**"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/lib/spec-worktrees.js",
+    "src/create-quiver/lib/lifecycle.js",
+    "src/create-quiver/lib/git.js",
+    "src/create-quiver/lib/ai/execution-plan.js",
+    "src/create-quiver/lib/ai/executor.js",
+    "tests/commands/spec-worktree.test.js",
+    "tests/commands/ai-execute-plan.test.js",
+    "tests/lib/lifecycle.test.js"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/lib/spec-worktrees.js",
+    "src/create-quiver/lib/lifecycle.js",
+    "src/create-quiver/lib/locks.js",
+    "src/create-quiver/lib/ai/execution-plan.js",
+    "src/create-quiver/lib/ai/executor.js",
+    "src/create-quiver/lib/git.js",
+    "tests/lib/**",
+    "tests/commands/**",
+    "specs/quiver-v27-reliability-ai-workflow-hardening/**"
+  ],
+  "depends_on": [
+    "slice-01-core-state-resolver-and-canonical-statuses"
+  ],
+  "parallel_safe": "yes",
+  "parallel_safe_reason": "Can run after shared resolver if it avoids AI artifact files touched by slice-04.",
+  "must": [
+    "Preserve one persistent worktree per spec.",
+    "Keep temporary per-slice worktrees only for delegated parallel execution.",
+    "Avoid nested worktree paths.",
+    "Handle dirty root/worktree states with clear recovery.",
+    "Add locks for concurrent spec/run operations.",
+    "Detect stale or manually deleted worktrees."
+  ],
+  "not_included": [
+    "Changing PR creation behavior unless required by worktree recovery.",
+    "Publishing npm.",
+    "Changing provider execution."
+  ],
+  "acceptance": [
+    "spec start dry-run and real run report/reuse the same persistent spec worktree.",
+    "Running from an existing spec worktree does not propose a nested worktree.",
+    "Delegated execution can still use temporary worktrees safely.",
+    "Dirty, missing, stale, or deleted worktrees produce actionable recovery messages.",
+    "Concurrent operations use locks or fail safely."
+  ],
+  "tests": [
+    "node --test tests/commands/spec-worktree.test.js tests/commands/spec-close.test.js tests/commands/ai-execute-plan.test.js tests/lib/lifecycle.test.js",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Test from repo root and from inside a spec worktree.",
+    "Simulate manually deleted worktree paths."
+  ],
+  "estimated_hours": 6,
+  "status": "completed",
+  "completed_at": "2026-05-24",
+  "blocked_reason": null
+}

package/specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-06-validation-gates-and-scope-safety/CLOSURE_BRIEF.md

@@ -0,0 +1,32 @@
+# CLOSURE BRIEF - slice-06: Validation gates and scope safety
+
+## Summary
+
+Implemented validation gate hardening across local slice checks, scope validation, handoff validation, full spec validation, and path safety. The slice closes the Pixel Quiver gaps where validation could pass while later execution failed or where commands assumed the wrong base branch.
+
+## Validation Against Acceptance Criteria
+
+- `check-slice --local` now validates local execution metadata, declared scope paths, dependency contracts, and reports executed and skipped checks.
+- `check-scope` now respects an explicit `--base`, then `slice.git.base_branch`, before falling back to common base branches.
+- `check-handoff` now reports missing headings with accepted aliases and a minimal template.
+- `spec validate` now checks spec docs, slice JSON, briefs, dependency cycles, safe paths, evidence references, and status references.
+- Slice paths and declared scope paths outside the repo root or using traversal are rejected before execution guidance or scope validation.
+
+## Changes
+
+- Added `spec validate` command support in `src/create-quiver/commands/spec.js` and `src/create-quiver/index.js`.
+- Hardened `src/create-quiver/lib/readiness.js` for local slice checks and base-aware `check-scope`.
+- Hardened `src/create-quiver/lib/handoff.js` with alias/template guidance.
+- Added repo-bound path validation helpers in `src/create-quiver/lib/paths.js`.
+- Applied path boundary checks in `src/create-quiver/lib/slice.js`, `src/create-quiver/lib/scope.js`, and `src/create-quiver/lib/ai/executor.js`.
+- Added `quiver:spec:validate` to generated package scripts and synchronized `README.md`, `README_FOR_AI.md`, and `docs/COMMANDS.md.template`.
+- Added tests in `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`, and `tests/commands/cli-contract.test.js`.
+
+## Remaining Risks
+
+- `spec validate` intentionally treats status/evidence mismatches as warnings by default for legacy compatibility; `--strict` promotes those warnings to failures.
+- `check-pr` still contains older `origin/develop` assumptions and should be revisited when PR/readiness flows are hardened further.
+
+## Follow-up Recommendations
+
+- Execute `slice-07-context-analysis-and-doctor-flow` next so analyzer, prepare-context, flow, and doctor can consume the stronger validation contracts.

package/specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-06-validation-gates-and-scope-safety/EXECUTION_BRIEF.md

@@ -0,0 +1,57 @@
+# EXECUTION BRIEF - slice-06: Validation gates and scope safety
+
+## Context
+
+Pixel Quiver showed that some validation gates passed while later execution failed, or skipped checks because of wrong branch assumptions. This slice turns validation into a reliable preflight.
+
+## Objective
+
+Harden validation gates and path/scope safety.
+
+## Scope
+
+- `check-slice`
+- `check-scope`
+- `check-handoff`
+- `spec validate`
+- path safety helpers
+- tests and docs evidence
+
+## Acceptance Criteria
+
+- Local slice validation catches local execution preconditions or clearly lists skipped checks.
+- Scope validation respects `--base` and `slice.git.base_branch`.
+- Handoff errors include templates or aliases.
+- `spec validate` validates full spec structure and evidence consistency.
+- Path traversal/out-of-root writes are rejected.
+
+## Technical Plan Summary
+
+Align validators with execution behavior, add strict/legacy modes where needed, and cover real dogfooding failures with tests.
+
+## Suggested Execution Steps
+
+1. Inspect validation and scope code.
+2. Add missing base/path/brief checks.
+3. Implement `spec validate` if not present.
+4. Add compatibility handling for legacy specs.
+5. Add regression tests.
+
+## Restrictions
+
+- Do not break legacy specs without documented strict mode.
+- Do not silently skip validation when base information is available.
+
+## Risks
+
+- End users may have older specs; use warnings or migration guidance when appropriate.
+
+## Completion Checklist
+
+- [ ] check-slice covered.
+- [ ] check-scope covered.
+- [ ] check-handoff covered.
+- [ ] spec validate covered.
+- [ ] path safety covered.
+- [ ] Validation commands passed.
+

package/specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-06-validation-gates-and-scope-safety/slice.json

@@ -0,0 +1,99 @@
+{
+  "slice_id": "slice-06-validation-gates-and-scope-safety",
+  "ticket": "QUIVER-27-06",
+  "type": "implementation",
+  "title": "Validation gates and scope safety",
+  "objective": "Harden check-slice, check-scope, check-handoff, spec validate, and path safety so validation gates catch real execution failures.",
+  "description": "Aligns local slice validation with execution preconditions, fixes base branch resolution, improves handoff template errors and aliases, adds spec validate, and prevents path traversal/out-of-scope writes.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v27-validation-gates-scope-safety",
+    "branch_name": "feature/QUIVER-27-06-v27-validation-gates-scope-safety"
+  },
+  "files": [
+    "src/create-quiver/lib/readiness.js",
+    "src/create-quiver/lib/scope.js",
+    "src/create-quiver/lib/handoff.js",
+    "src/create-quiver/lib/paths.js",
+    "src/create-quiver/lib/slice.js",
+    "src/create-quiver/lib/ai/executor.js",
+    "src/create-quiver/lib/init-layout.js",
+    "src/create-quiver/commands/spec.js",
+    "src/create-quiver/index.js",
+    "package.json",
+    "README.md",
+    "README_FOR_AI.md",
+    "docs/COMMANDS.md.template",
+    "tests/lib/**",
+    "tests/commands/**",
+    "specs/quiver-v27-reliability-ai-workflow-hardening/**"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/lib/readiness.js",
+    "src/create-quiver/lib/scope.js",
+    "src/create-quiver/lib/handoff.js",
+    "src/create-quiver/lib/paths.js",
+    "src/create-quiver/lib/slice.js",
+    "src/create-quiver/lib/init-layout.js",
+    "tests/lib/check-slice.test.js",
+    "tests/lib/scope.test.js",
+    "tests/lib/handoff.test.js"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/lib/readiness.js",
+    "src/create-quiver/lib/scope.js",
+    "src/create-quiver/lib/handoff.js",
+    "src/create-quiver/lib/paths.js",
+    "src/create-quiver/lib/slice.js",
+    "src/create-quiver/lib/ai/executor.js",
+    "src/create-quiver/lib/init-layout.js",
+    "src/create-quiver/commands/spec.js",
+    "src/create-quiver/index.js",
+    "package.json",
+    "README.md",
+    "README_FOR_AI.md",
+    "docs/COMMANDS.md.template",
+    "tests/lib/**",
+    "tests/commands/**",
+    "specs/quiver-v27-reliability-ai-workflow-hardening/**"
+  ],
+  "depends_on": [
+    "slice-01-core-state-resolver-and-canonical-statuses",
+    "slice-05-worktree-lifecycle-locks-and-recovery"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Validation gates depend on resolver and worktree lifecycle behavior.",
+  "must": [
+    "Align check-slice --local with start/execute preconditions or list skipped checks.",
+    "Make check-scope respect --base and slice git.base_branch before fallbacks.",
+    "Add or harden spec validate.",
+    "Improve check-handoff error templates and Spanish/English aliases.",
+    "Reject path traversal and writes outside project root.",
+    "Support legacy/strict validation modes where needed."
+  ],
+  "not_included": [
+    "Changing export schema.",
+    "Changing AI provider behavior.",
+    "Publishing npm."
+  ],
+  "acceptance": [
+    "check-slice --local catches required local metadata for execution or documents skipped checks.",
+    "check-scope does not hardcode develop when --base or slice base_branch is provided.",
+    "check-handoff prints minimal templates or accepted aliases when headings are missing.",
+    "spec validate checks spec docs, slices, JSON, briefs, evidence, and status consistency.",
+    "Paths outside the repo root are rejected."
+  ],
+  "tests": [
+    "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/cli-contract.test.js",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Add tests for main, master, develop, --base, and missing remote.",
+    "Add path traversal and symlink cases."
+  ],
+  "estimated_hours": 6,
+  "status": "completed",
+  "completed_at": "2026-05-24",
+  "blocked_reason": null
+}

package/specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-07-context-analysis-and-doctor-flow/CLOSURE_BRIEF.md

@@ -0,0 +1,31 @@
+# CLOSURE BRIEF - slice-07: Context analysis and doctor flow
+
+## Summary
+
+Hardened context analysis and diagnostics so `analyze`, `prepare-context`, `flow`, and `doctor` provide evidence-based guidance without unsafe dry-run writes or misleading examples.
+
+## Validation Against Acceptance Criteria
+
+- `analyze --dry-run` now builds the scan in memory, reports planned writes, and does not create `.quiver/`, `docs/PROJECT_MAP.md`, or `docs/AI_CONTEXT.md`.
+- React + Vite projects are detected as `react` with `vite` as an additional framework; `vite.config.*` no longer implies Vue.
+- `prepare-context` keeps detected package manager, stack, and scripts as facts while leaving unknown architecture boundaries as TODO/pending confirmation.
+- `flow` reports context source/freshness in human output and JSON facts.
+- `doctor` examples target an active slice when available, the single spec when unambiguous, or generic placeholders when multiple specs have no active slice.
+
+## Changes
+
+- Added scan status metadata in `src/create-quiver/lib/project-scan.js`.
+- Added true `analyze --dry-run` handling and React/Vite detection fixes in `src/create-quiver/index.js`.
+- Added `flow` context-source output.
+- Added doctor example target selection.
+- Added focused command and library tests for analyze, flow, doctor, project scan status, and prepare-context evidence behavior.
+- Updated v27 spec/status/evidence docs.
+
+## Remaining Risks
+
+- Analyzer heuristics remain intentionally conservative. More real-world fixtures should be added in slice-09 before release readiness.
+
+## Follow-up Recommendations
+
+- Continue with `slice-08-cross-platform-help-auth-and-dx`.
+- In slice-09, include tarball/package smoke coverage for `analyze --dry-run`, `flow`, and `doctor` examples.

package/specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-07-context-analysis-and-doctor-flow/EXECUTION_BRIEF.md

@@ -0,0 +1,57 @@
+# EXECUTION BRIEF - slice-07: Context analysis and doctor flow
+
+## Context
+
+Pixel Quiver showed analyzer stack mistakes, `analyze --dry-run` writes, placeholder-heavy `prepare-context`, stale docs, and doctor examples pointing to the wrong spec. This slice hardens context commands and first-use guidance.
+
+## Objective
+
+Make context analysis and doctor/flow guidance evidence-based, read-only where promised, and accurate.
+
+## Scope
+
+- `analyze`
+- project scan
+- `ai prepare-context`
+- `flow`
+- `doctor`
+- fixtures and tests
+
+## Acceptance Criteria
+
+- `analyze --dry-run` writes nothing.
+- React + Vite detection is correct.
+- `prepare-context` is conservative and evidence-based.
+- `flow` reports source/staleness.
+- `doctor` does not suggest commands for the wrong spec.
+
+## Technical Plan Summary
+
+Improve scan heuristics, dry-run behavior, docs contradiction detection, active context selection, and test fixtures.
+
+## Suggested Execution Steps
+
+1. Inspect analyze/project-scan behavior.
+2. Add no-write dry-run guard and tests.
+3. Improve stack detection.
+4. Improve prepare-context contradiction output.
+5. Improve flow/doctor state source and example selection.
+6. Add fixtures and evidence.
+
+## Restrictions
+
+- Do not overwrite human-authored docs without snapshots/review.
+- Do not execute providers.
+
+## Risks
+
+- Analyzer heuristics can regress other stacks; add representative fixtures.
+
+## Completion Checklist
+
+- [ ] Dry-run no-write test added.
+- [ ] React/Vite fixture added.
+- [ ] prepare-context evidence behavior covered.
+- [ ] flow/doctor guidance covered.
+- [ ] Validation commands passed.
+