create-quiver 0.12.0 → 0.13.0

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

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

@@ -0,0 +1,88 @@
+{
+  "slice_id": "slice-07-context-analysis-and-doctor-flow",
+  "ticket": "QUIVER-27-07",
+  "type": "implementation",
+  "title": "Context analysis and doctor flow",
+  "objective": "Harden analyze, prepare-context, flow, and doctor so onboarding docs are evidence-based, dry-runs are read-only, and next steps are accurate.",
+  "description": "Fixes stack detection, read-only dry-run behavior, docs/status consistency checks, stale-state guidance, active spec/slice examples, root/package manager detection, and first-use diagnostics.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v27-context-analysis-doctor-flow",
+    "branch_name": "feature/QUIVER-27-07-v27-context-analysis-doctor-flow"
+  },
+  "files": [
+    "src/create-quiver/lib/analyze.js",
+    "src/create-quiver/lib/project-scan.js",
+    "src/create-quiver/lib/doctor.js",
+    "src/create-quiver/lib/ai/onboarding-template.js",
+    "src/create-quiver/commands/flow.js",
+    "src/create-quiver/commands/prepare.js",
+    "tests/lib/**",
+    "tests/commands/**",
+    "tests/fixtures/**",
+    "specs/quiver-v27-reliability-ai-workflow-hardening/**"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/lib/analyze.js",
+    "src/create-quiver/lib/project-scan.js",
+    "src/create-quiver/lib/doctor.js",
+    "src/create-quiver/lib/ai/onboarding-template.js",
+    "src/create-quiver/commands/flow.js",
+    "tests/commands/analyze.test.js",
+    "tests/commands/ai-onboard.test.js",
+    "tests/commands/flow.test.js",
+    "tests/commands/doctor.test.js"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/lib/analyze.js",
+    "src/create-quiver/lib/project-scan.js",
+    "src/create-quiver/lib/doctor.js",
+    "src/create-quiver/lib/ai/onboarding-template.js",
+    "src/create-quiver/commands/flow.js",
+    "src/create-quiver/commands/prepare.js",
+    "tests/lib/**",
+    "tests/commands/**",
+    "tests/fixtures/**",
+    "specs/quiver-v27-reliability-ai-workflow-hardening/**"
+  ],
+  "depends_on": [
+    "slice-01-core-state-resolver-and-canonical-statuses",
+    "slice-06-validation-gates-and-scope-safety"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Context and doctor guidance depends on resolver and validation contract behavior.",
+  "must": [
+    "Make analyze --dry-run read-only.",
+    "Improve React/Vite and stack detection using package.json and config evidence.",
+    "Make prepare-context conservative and evidence-based.",
+    "Detect docs/status contradictions without overwriting human content.",
+    "Make flow show source/timestamp or stale-state information.",
+    "Make doctor prioritize active spec/slice examples where available."
+  ],
+  "not_included": [
+    "Changing spec create behavior.",
+    "Changing worktree lifecycle beyond guidance messages.",
+    "Executing AI providers."
+  ],
+  "acceptance": [
+    "analyze --dry-run leaves git status unchanged.",
+    "React + Vite projects are detected as React/Vite, not Vue.",
+    "prepare-context --dry-run does not propose placeholders as truth when evidence exists.",
+    "flow reports the state source or a stale/missing context explanation.",
+    "doctor examples prefer active spec/slice context or generic examples over the wrong spec."
+  ],
+  "tests": [
+    "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",
+    "npm run smoke:doctor-fixtures",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Snapshot git status before/after dry-run tests.",
+    "Use fixtures with stale docs and real completed slices."
+  ],
+  "estimated_hours": 6,
+  "status": "completed",
+  "completed_at": "2026-05-24",
+  "blocked_reason": null
+}

package/specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-08-cross-platform-help-auth-and-dx/CLOSURE_BRIEF.md

@@ -0,0 +1,31 @@
+# CLOSURE BRIEF - slice-08: Cross-platform help, auth, and DX
+
+## Summary
+
+Hardened cross-platform DX around help output, agent profile previews, GitHub auth diagnostics, SSH/path guidance, and package-manager-aware next-step messaging.
+
+## Validation Against Acceptance Criteria
+
+- Help output now documents the `ai agent set --dry-run` flow and the general `--dry-run` option includes `ai agent set`.
+- Paths with spaces now trigger shell-specific guidance for macOS/Linux, Windows PowerShell, Git Bash, and WSL in GitHub PR/preflight output.
+- GitHub auth failures now identify likely account, scope, and SSH alias issues and point to `gh auth status` as the next safe command.
+- `ai agent set --dry-run` validates and previews the profile without writing `.quiver/agents/profiles.json`.
+- `flow` now reports the detected package manager and generated `quiver:flow` script command; init/migrate install fallback warnings respect npm, pnpm, yarn, or bun.
+
+## Changes
+
+- Added `buildAgentProfileState` and wired `ai agent set --dry-run` through `src/create-quiver/commands/ai.js`.
+- Updated CLI help, examples, and agent dispatch in `src/create-quiver/index.js`.
+- Added GitHub auth classification and shell-safe command/path formatting in `src/create-quiver/lib/ai/github.js`.
+- Added package-manager-aware flow output in `src/create-quiver/commands/flow.js`.
+- Updated command docs and v27 evidence/status docs.
+- Added focused tests for agent dry-run, help contract, GitHub diagnostics/path guidance, and flow package-manager output.
+
+## Remaining Risks
+
+- `gh auth status` output varies by GitHub CLI version; diagnostics intentionally combine parsed hints with general account/scope/alias guidance.
+- Shell-safe examples are generated for common shells, but unusual shell configurations may still require manual path adaptation.
+
+## Follow-up Recommendations
+
+- In `slice-09`, include smoke coverage for packaged CLI help, `flow`, `ai agent set --dry-run`, and GitHub diagnostic fixtures.

package/specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-08-cross-platform-help-auth-and-dx/EXECUTION_BRIEF.md

@@ -0,0 +1,56 @@
+# EXECUTION BRIEF - slice-08: Cross-platform help, auth, and DX
+
+## Context
+
+Pixel Quiver exposed DX gaps around paths with spaces, GitHub auth, command copying, help coverage, and safe profile configuration. This slice focuses on user-facing clarity after core context behavior is hardened.
+
+## Objective
+
+Improve cross-platform help, auth diagnostics, and actionable command guidance.
+
+## Scope
+
+- CLI help
+- doctor/preflight messages
+- GitHub auth diagnostics
+- agent profile dry-run
+- package manager-aware suggestions
+- docs and tests
+
+## Acceptance Criteria
+
+- Help output covers public commands and key options.
+- Path guidance is copy-safe across OS variants.
+- GitHub auth diagnostics are actionable.
+- Agent profile dry-run does not write files.
+- Suggested commands respect detected package manager.
+
+## Technical Plan Summary
+
+Update help registry/messages, add auth diagnostics and dry-run preview, and cover OS/package-manager examples with tests.
+
+## Suggested Execution Steps
+
+1. Inspect help and diagnostics surfaces.
+2. Add/adjust `ai agent set --dry-run`.
+3. Improve GitHub auth and SSH alias messages.
+4. Add path/package-manager guidance.
+5. Update docs and tests.
+
+## Restrictions
+
+- Do not install credentials or mutate user auth.
+- Do not require network in tests.
+
+## Risks
+
+- Help output can drift; keep tests tied to command registry.
+
+## Completion Checklist
+
+- [ ] Help tests updated.
+- [ ] Auth diagnostics tested.
+- [ ] Agent dry-run tested.
+- [ ] Cross-platform path guidance tested.
+- [ ] Validation commands passed.
+