create-quiver 0.12.1 → 0.14.0

package/specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-02-json-export-contract-and-machine-output/slice.json

@@ -0,0 +1,75 @@
+{
+  "slice_id": "slice-02-json-export-contract-and-machine-output",
+  "ticket": "QUIVER-27-02",
+  "type": "implementation",
+  "title": "JSON export contract and machine output",
+  "objective": "Define and implement a stable JSON export contract for dashboards, agents, and machine consumers.",
+  "description": "Adds a versioned export schema, pure stdout JSON behavior, deterministic ordering, source metadata, partial/empty/invalid semantics, sanitized paths, and alignment between ai export and export-specs.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v27-json-export-contract-machine-output",
+    "branch_name": "feature/QUIVER-27-02-v27-json-export-contract-machine-output"
+  },
+  "files": [
+    "src/create-quiver/lib/**",
+    "src/create-quiver/commands/**",
+    "src/create-quiver/index.js",
+    "tests/lib/**",
+    "tests/commands/**",
+    "specs/quiver-v27-reliability-ai-workflow-hardening/**"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/lib/ai/export-state.js",
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/index.js",
+    "tests/lib/ai-export-state.test.js",
+    "tests/commands/ai-export.test.js"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/lib/**",
+    "src/create-quiver/commands/**",
+    "src/create-quiver/index.js",
+    "tests/lib/**",
+    "tests/commands/**",
+    "specs/quiver-v27-reliability-ai-workflow-hardening/**"
+  ],
+  "depends_on": [
+    "slice-01-core-state-resolver-and-canonical-statuses"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Export contract depends on the shared state resolver and is consumed by later slices.",
+  "must": [
+    "Define schemaVersion and stable field names.",
+    "Ensure --format json writes JSON only to stdout.",
+    "Route warnings/errors to structured JSON fields or stderr as appropriate.",
+    "Include source metadata and completed slices with --include-completed.",
+    "Sanitize local paths where needed."
+  ],
+  "not_included": [
+    "Dashboard UI implementation.",
+    "Provider execution.",
+    "Spec create parsing changes."
+  ],
+  "acceptance": [
+    "JSON output parses with JSON.parse without cleanup.",
+    "Export includes specs, slices, agents, runs, approvals, blockers, evidence, next steps, lifecycle, aggregates, warnings, and source metadata.",
+    "Completed slices appear when --include-completed is used.",
+    "Human logs are not mixed into JSON stdout.",
+    "Unsupported formats fail with non-zero exit and stderr error."
+  ],
+  "tests": [
+    "node --test tests/lib/ai-export-state.test.js tests/commands/ai-export.test.js",
+    "node --test tests/commands/cli-contract.test.js",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Add tests that run the CLI and parse stdout directly.",
+    "Assert deterministic ordering in exported arrays."
+  ],
+  "estimated_hours": 5,
+  "actual_hours": 5,
+  "status": "completed",
+  "completed_at": "2026-05-24T13:54:36Z",
+  "blocked_reason": null
+}

package/specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-03-approved-plan-to-spec-create/CLOSURE_BRIEF.md

@@ -0,0 +1,36 @@
+# CLOSURE BRIEF - slice-03: Approved plan to spec create
+
+## Summary
+
+Implemented strict approved-plan to spec generation.
+
+`spec create` and the spec-phase generator now require structured slice data from the reviewed and approved technical plan. They preserve every approved implementation slice, generate the mandatory `slice-00-spec-foundation`, and fail before writing when the plan is not structurally safe.
+
+## Validation Against Acceptance Criteria
+
+- A plan with 8 approved implementation slices produces those 8 slices plus the mandatory `slice-00-spec-foundation`.
+- Plans without a structured slices array fail before writing files.
+- Duplicate slice IDs fail before writing files.
+- Missing dependencies fail before writing files.
+- Circular dependencies fail before writing files.
+- Fenced JSON slice blocks inside Markdown plans are supported.
+- Failed `spec create --dry-run` does not create a spec directory.
+
+## Changes
+
+- Updated `src/create-quiver/lib/ai/spec-generator.js`.
+- Updated `src/create-quiver/lib/ai/spec-templates.js`.
+- Updated `tests/lib/ai-spec-generator.test.js`.
+- Updated `tests/commands/spec-create.test.js`.
+- Updated v27 spec status, execution plan, evidence, and this closure brief.
+
+## Remaining Risks
+
+- Free-form technical plans without structured slice data now fail intentionally; users need to revise the planner prompt or add a fenced JSON slice block.
+- The structured contract is currently documented through the error message and tests, not a standalone schema file.
+- Generated spec execution is still not performed in this slice.
+
+## Follow-up Recommendations
+
+- Update planner prompts in later slices so technical plans always include the structured slice block.
+- Execute `slice-04` and `slice-05` next; they can proceed in parallel only if write scopes remain independent.

package/specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-03-approved-plan-to-spec-create/EXECUTION_BRIEF.md

@@ -0,0 +1,55 @@
+# EXECUTION BRIEF - slice-03: Approved plan to spec create
+
+## Context
+
+Pixel Quiver showed that `spec create` can generate a generic two-slice scaffold instead of the approved multi-slice plan. That breaks the central WDD + SDD flow.
+
+## Objective
+
+Make `spec create` faithful to the approved technical plan and safe on parse failure.
+
+## Scope
+
+- Spec generator
+- Approval metadata handling
+- Spec templates
+- Command tests and fixtures
+- v27 evidence/status docs
+
+## Acceptance Criteria
+
+- `spec create` uses an explicitly approved technical plan version.
+- Approved slice count, IDs, dependencies, handoffs, execution plan, and PR body are generated.
+- Missing/invalid structured slice data fails before writing.
+- Generic fallback scaffolds are not created silently.
+- Failed runs do not leave empty remnant directories.
+
+## Technical Plan Summary
+
+Add structured plan extraction/validation, atomic writes, safe failure handling, and regression tests based on the Pixel Quiver failure.
+
+## Suggested Execution Steps
+
+1. Inspect current spec generator and approval selection.
+2. Define the structured slice block contract.
+3. Implement validation and atomic write flow.
+4. Add tests for good plan, missing structure, duplicates, circular dependencies, dry-run, and failure cleanup.
+5. Update docs/evidence.
+
+## Restrictions
+
+- Do not execute generated slices.
+- Do not open PRs.
+
+## Risks
+
+- Existing free-form plans may need compatibility guidance or migration.
+
+## Completion Checklist
+
+- [ ] Structured block contract implemented.
+- [ ] Generic fallback removed or made explicit error.
+- [ ] Atomic write behavior covered.
+- [ ] Regression fixture added.
+- [ ] Validation commands passed.
+

package/specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-03-approved-plan-to-spec-create/slice.json

@@ -0,0 +1,78 @@
+{
+  "slice_id": "slice-03-approved-plan-to-spec-create",
+  "ticket": "QUIVER-27-03",
+  "type": "implementation",
+  "title": "Approved plan to spec create",
+  "objective": "Make spec create generate the approved spec/slices/handoffs from a reviewed and approved technical plan, or fail safely before writing.",
+  "description": "Prevents generic fallback scaffolds by requiring structured slice data from the approved plan, validating slice IDs/dependencies/slice-00/handoffs, using atomic writes, and cleaning up safely.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v27-approved-plan-to-spec-create",
+    "branch_name": "feature/QUIVER-27-03-v27-approved-plan-to-spec-create"
+  },
+  "files": [
+    "src/create-quiver/lib/ai/spec-generator.js",
+    "src/create-quiver/lib/ai/spec-templates.js",
+    "src/create-quiver/lib/approvals.js",
+    "src/create-quiver/commands/spec.js",
+    "tests/lib/ai-spec-generator.test.js",
+    "tests/commands/spec-create.test.js",
+    "specs/quiver-v27-reliability-ai-workflow-hardening/**"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/lib/ai/spec-generator.js",
+    "src/create-quiver/lib/ai/spec-templates.js",
+    "src/create-quiver/lib/approvals.js",
+    "tests/lib/ai-spec-generator.test.js",
+    "tests/commands/spec-create.test.js"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/lib/ai/spec-generator.js",
+    "src/create-quiver/lib/ai/spec-templates.js",
+    "src/create-quiver/lib/approvals.js",
+    "src/create-quiver/commands/spec.js",
+    "tests/lib/ai-spec-generator.test.js",
+    "tests/commands/spec-create.test.js",
+    "specs/quiver-v27-reliability-ai-workflow-hardening/**"
+  ],
+  "depends_on": [
+    "slice-01-core-state-resolver-and-canonical-statuses",
+    "slice-02-json-export-contract-and-machine-output"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Spec generation depends on shared state/export contracts and affects core workflow.",
+  "must": [
+    "Use explicitly approved technical plan metadata.",
+    "Require or extract a structured slice block.",
+    "Generate slice-00 and every approved slice.",
+    "Create SPEC.md, STATUS.md, EVIDENCE_REPORT.md, EXECUTION_PLAN.md, pr.md, slice.json, EXECUTION_BRIEF.md, and CLOSURE_BRIEF.md.",
+    "Fail before writing if the plan cannot be parsed.",
+    "Use atomic writes and avoid empty scaffold remnants."
+  ],
+  "not_included": [
+    "Changing AI provider prompts except where needed for structured output.",
+    "Executing generated slices.",
+    "Opening PRs."
+  ],
+  "acceptance": [
+    "Given a plan with 8 approved slices, spec create creates 8 slices plus required artifacts.",
+    "Given no structured slice block, spec create fails without writing files.",
+    "Given duplicate IDs or circular dependencies, spec create fails before writing.",
+    "Generated names are derived from requirement/spec metadata and not generic approved placeholders.",
+    "No empty generic scaffold directories remain after failure or regeneration."
+  ],
+  "tests": [
+    "node --test tests/lib/ai-spec-generator.test.js tests/commands/spec-create.test.js",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Test dry-run and real-run behavior.",
+    "Compare git status before/after failed spec create."
+  ],
+  "estimated_hours": 6,
+  "actual_hours": 6,
+  "status": "completed",
+  "completed_at": "2026-05-24T14:00:33Z",
+  "blocked_reason": null
+}

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.