create-quiver 0.12.1 → 0.13.0

package/specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-00-docs-audit-coverage-and-contracts/EXECUTION_BRIEF.md

@@ -0,0 +1,56 @@
+# EXECUTION BRIEF - slice-00: Docs audit, coverage, and contracts
+
+## Context
+
+Pixel Quiver dogfooding produced `QP-001` to `QP-019` and `QIS-001` to `QIS-022`. Some related Quiver capabilities are documented as shipped in v24, v25, and v26, but real usage showed remaining gaps. This slice creates the foundation and contracts before product code changes.
+
+## Objective
+
+Create and verify the v27 documentary foundation, coverage matrix, and production command contracts.
+
+## Scope
+
+- `specs/quiver-v27-reliability-ai-workflow-hardening/**`
+- `README_FOR_AI.md`
+- `ROADMAP.md`
+- `CHANGELOG.md`
+
+## Acceptance Criteria
+
+- The v27 spec package exists and every slice has `slice.json`, `EXECUTION_BRIEF.md`, and `CLOSURE_BRIEF.md`.
+- Every QP/QIS is mapped to a slice and validation strategy.
+- Cross-command contracts are documented.
+- Source-of-truth docs mention v27 as planned without claiming implementation.
+- No product code changes are made.
+
+## Technical Plan Summary
+
+Audit existing docs/code/tests, record coverage, and update docs/spec artifacts only.
+
+## Suggested Execution Steps
+
+1. Inspect v24/v25/v26 docs, implementation, and tests.
+2. Fill the v27 coverage matrix with status per QP/QIS.
+3. Document command contracts and compatibility expectations.
+4. Update source-of-truth docs.
+5. Validate JSON, handoffs, and whitespace.
+
+## Restrictions
+
+- Do not modify product code.
+- Do not publish npm.
+- Do not open a PR unless explicitly requested.
+
+## Risks
+
+- Existing docs may overstate implemented behavior; record gaps instead of assuming.
+
+## Completion Checklist
+
+- [ ] Coverage matrix completed.
+- [ ] Contracts documented.
+- [ ] Source-of-truth docs synced.
+- [ ] JSON validation passed.
+- [ ] Handoff validation passed.
+- [ ] `git diff --check` passed.
+

package/specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-00-docs-audit-coverage-and-contracts/slice.json

@@ -0,0 +1,75 @@
+{
+  "slice_id": "slice-00-docs-audit-coverage-and-contracts",
+  "ticket": "QUIVER-27-00",
+  "type": "docs",
+  "title": "Docs audit, coverage, and contracts",
+  "objective": "Create the v27 documentary foundation, audit existing v24/v25/v26 behavior against Pixel Quiver evidence, and define cross-command contracts before implementation starts.",
+  "description": "Audits source-of-truth docs, existing specs, tests, and implementation surfaces; creates a QP/QIS coverage matrix; defines command contracts for exit codes, stdout/stderr, dry-run, write classes, idempotency, atomic writes, path safety, root detection, package managers, deterministic ordering, schema/versioning, and legacy/strict behavior.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v27-docs-audit-coverage-contracts",
+    "branch_name": "feature/QUIVER-27-00-v27-docs-audit-coverage-contracts"
+  },
+  "files": [
+    "README_FOR_AI.md",
+    "ROADMAP.md",
+    "CHANGELOG.md",
+    "specs/quiver-v27-reliability-ai-workflow-hardening/**"
+  ],
+  "expected_read_paths": [
+    "README_FOR_AI.md",
+    "ROADMAP.md",
+    "BACKLOG.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/**"
+  ],
+  "allowed_write_paths": [
+    "README_FOR_AI.md",
+    "ROADMAP.md",
+    "CHANGELOG.md",
+    "specs/quiver-v27-reliability-ai-workflow-hardening/**"
+  ],
+  "depends_on": [],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "slice-00 is the mandatory documentary foundation and must land before implementation slices.",
+  "must": [
+    "Create or refine the v27 planning package.",
+    "Map QP-001..QP-019 and QIS-001..QIS-022 to slices and validations.",
+    "Audit v24/v25/v26 docs and code for already implemented, partial, broken, or missing behavior.",
+    "Define cross-command production contracts.",
+    "Avoid product code changes."
+  ],
+  "not_included": [
+    "Changing CLI behavior.",
+    "Adding tests beyond documentation validation.",
+    "Publishing npm.",
+    "Opening a PR."
+  ],
+  "acceptance": [
+    "The v27 spec folder exists with SPEC.md, STATUS.md, EXECUTION_PLAN.md, EVIDENCE_REPORT.md, pr.md, and all slice folders.",
+    "Every QP/QIS is assigned to at least one slice or explicitly marked covered by existing implementation with evidence.",
+    "Command contracts for exit codes, stdout/stderr, dry-run, write class, idempotency, atomic writes, path safety, root detection, package managers, deterministic ordering, and legacy/strict behavior are documented.",
+    "README_FOR_AI.md, ROADMAP.md, and CHANGELOG.md do not contradict the current v27 planned state.",
+    "No product code is modified."
+  ],
+  "tests": [
+    "git diff --check",
+    "find specs/quiver-v27-reliability-ai-workflow-hardening -name \"slice.json\" -print -exec node -e \"JSON.parse(require('fs').readFileSync(process.argv[1], 'utf8'))\" {} \\;",
+    "npx create-quiver check-handoff specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-00-docs-audit-coverage-and-contracts/EXECUTION_BRIEF.md",
+    "npx create-quiver check-handoff specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-00-docs-audit-coverage-and-contracts/CLOSURE_BRIEF.md"
+  ],
+  "validation_hints": [
+    "Use git diff to confirm the slice is documentation-only.",
+    "Do not copy unsanitized Pixel Quiver absolute paths into fixtures."
+  ],
+  "estimated_hours": 3,
+  "actual_hours": 3,
+  "status": "completed",
+  "completed_at": "2026-05-24T13:38:42Z",
+  "blocked_reason": null
+}

package/specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-01-core-state-resolver-and-canonical-statuses/CLOSURE_BRIEF.md

@@ -0,0 +1,37 @@
+# CLOSURE BRIEF - slice-01: Core state resolver and canonical statuses
+
+## Summary
+
+Implemented the shared resolver foundation for Quiver lifecycle state.
+
+Classic commands and AI lifecycle surfaces now share a resolver layer for slice discovery, scoped reads, canonical status normalization, deterministic ordering, completed-slice filtering, graph summaries, and progress calculations.
+
+## Validation Against Acceptance Criteria
+
+- Classic `plan` and `graph` commands now resolve slices through `project-state-resolver`.
+- AI lifecycle export/list/inspect state now resolves slices through the same resolver.
+- Completed slices are visible when `includeCompleted` or `--include-completed` is requested.
+- Scoped reads continue to avoid parsing unrelated historical specs.
+- Status aliases are normalized through a shared canonical catalog while preserving legacy `status` fields for compatibility.
+- Existing behavior for plan, graph, next, doctor, and AI export/list/inspect remains covered by tests.
+
+## Changes
+
+- Added `src/create-quiver/lib/statuses.js`.
+- Added `src/create-quiver/lib/project-state-resolver.js`.
+- Updated `src/create-quiver/commands/plan.js`.
+- Updated `src/create-quiver/commands/graph.js`.
+- Updated `src/create-quiver/lib/ai/export-state.js`.
+- Added `tests/lib/project-state-resolver.test.js`.
+- Updated v27 evidence, status, and spec docs.
+
+## Remaining Risks
+
+- `flow` and deeper doctor next-step logic still have command-specific state logic; their full hardening remains assigned to `slice-07`.
+- The public JSON export schema is not finalized in this slice; `slice-02` owns that contract.
+- Worktree state is not yet unified through the resolver; `slice-05` owns persistent worktree lifecycle behavior.
+
+## Follow-up Recommendations
+
+- Execute `slice-02-json-export-contract-and-machine-output` next to stabilize the machine-readable export contract over the resolver.
+- Keep `status` fields backward compatible and expose canonical state through additive fields until a migration is explicitly approved.

package/specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-01-core-state-resolver-and-canonical-statuses/EXECUTION_BRIEF.md

@@ -0,0 +1,54 @@
+# EXECUTION BRIEF - slice-01: Core state resolver and canonical statuses
+
+## Context
+
+Pixel Quiver showed that classic commands and AI commands can disagree about specs/slices, especially completed slices. This slice creates the shared model that later export, spec create, validation, and DX work depends on.
+
+## Objective
+
+Implement a shared internal resolver and canonical status model.
+
+## Scope
+
+- Resolver/state code under `src/create-quiver/lib/**`
+- Command adapters that currently discover specs/slices independently
+- Tests and fixtures for state discovery
+- v27 evidence/status docs
+
+## Acceptance Criteria
+
+- Classic and AI commands can resolve the same specs/slices from the same underlying model.
+- Completed slices are included when explicitly requested.
+- Scoped reads do not parse unrelated specs unnecessarily.
+- Status values are normalized and deterministic.
+- Existing command contracts are preserved or explicitly documented.
+
+## Technical Plan Summary
+
+Extract or introduce a resolver module, route affected commands through it, add fixtures for mixed states, and test deterministic output.
+
+## Suggested Execution Steps
+
+1. Identify all spec/slice discovery implementations.
+2. Design the internal model and canonical statuses.
+3. Refactor command adapters incrementally.
+4. Add tests for completed/draft/multiple-spec/scoped cases.
+5. Update evidence and status.
+
+## Restrictions
+
+- Do not change public JSON schema in this slice unless required for compatibility.
+- Do not implement spec create parsing here.
+
+## Risks
+
+- Broad resolver changes can regress many commands; keep adapters small and tested.
+
+## Completion Checklist
+
+- [ ] Shared resolver implemented.
+- [ ] Canonical statuses documented in code/tests.
+- [ ] Classic and AI commands covered by tests.
+- [ ] Scoped behavior covered.
+- [ ] Validation commands passed.
+

package/specs/quiver-v27-reliability-ai-workflow-hardening/slices/slice-01-core-state-resolver-and-canonical-statuses/slice.json

@@ -0,0 +1,79 @@
+{
+  "slice_id": "slice-01-core-state-resolver-and-canonical-statuses",
+  "ticket": "QUIVER-27-01",
+  "type": "implementation",
+  "title": "Core state resolver and canonical statuses",
+  "objective": "Create a shared internal resolver and canonical status model used by classic and AI commands.",
+  "description": "Unifies spec, slice, run, approval, agent, evidence, worktree, status, source metadata, root detection, and ordering behavior so commands stop disagreeing about project state.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v27-core-state-resolver-canonical-statuses",
+    "branch_name": "feature/QUIVER-27-01-v27-core-state-resolver-canonical-statuses"
+  },
+  "files": [
+    "src/create-quiver/lib/**",
+    "src/create-quiver/commands/**",
+    "tests/lib/**",
+    "tests/commands/**",
+    "specs/quiver-v27-reliability-ai-workflow-hardening/**"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/lib/slice-graph.js",
+    "src/create-quiver/lib/ai/export-state.js",
+    "src/create-quiver/lib/doctor.js",
+    "src/create-quiver/commands/plan.js",
+    "src/create-quiver/commands/graph.js",
+    "src/create-quiver/commands/next.js",
+    "src/create-quiver/commands/ai.js",
+    "tests/lib/ai-export-state.test.js",
+    "tests/commands/ai-export.test.js",
+    "tests/commands/plan.test.js",
+    "tests/commands/doctor.test.js"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/lib/**",
+    "src/create-quiver/commands/**",
+    "tests/lib/**",
+    "tests/commands/**",
+    "specs/quiver-v27-reliability-ai-workflow-hardening/**"
+  ],
+  "depends_on": [
+    "slice-00-docs-audit-coverage-and-contracts"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "This slice defines shared contracts consumed by later slices.",
+  "must": [
+    "Define canonical statuses for specs, slices, runs, approvals, agents, and datasets.",
+    "Expose a shared resolver for classic and AI commands.",
+    "Support scoped reads with --spec without parsing unrelated historical specs unnecessarily.",
+    "Return deterministic ordering.",
+    "Preserve compatibility for existing commands."
+  ],
+  "not_included": [
+    "Public JSON export schema changes beyond resolver plumbing.",
+    "Spec create parsing changes.",
+    "Worktree lifecycle changes."
+  ],
+  "acceptance": [
+    "Classic and AI command tests share the same state resolver or a documented adapter over it.",
+    "Completed slices are visible when includeCompleted/include-completed is requested.",
+    "Scoped reads avoid unrelated specs where possible.",
+    "Status values are normalized through one canonical catalog.",
+    "Existing plan, graph, next, doctor, ai inspect, and ai list behavior remains compatible."
+  ],
+  "tests": [
+    "node --test tests/lib/*resolver*.test.js tests/lib/ai-export-state.test.js tests/commands/ai-export.test.js tests/commands/plan.test.js tests/commands/graph.test.js tests/commands/doctor.test.js",
+    "npm run smoke:doctor-fixtures",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Add fixtures for multiple specs with completed and draft slices.",
+    "Assert ordering is stable across runs."
+  ],
+  "estimated_hours": 6,
+  "actual_hours": 6,
+  "status": "completed",
+  "completed_at": "2026-05-24T13:48:34Z",
+  "blocked_reason": null
+}

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

@@ -0,0 +1,34 @@
+# CLOSURE BRIEF - slice-02: JSON export contract and machine output
+
+## Summary
+
+Implemented the v27 machine-readable lifecycle export contract.
+
+`ai export --format json` now emits schema v2 lifecycle data with source metadata, warnings, approvals, blockers, evidence, next steps, lifecycle details, aggregates, and canonical statuses while preserving existing fields for compatibility.
+
+## Validation Against Acceptance Criteria
+
+- `ai export --format json` emits parseable JSON only on stdout.
+- Successful JSON export keeps stderr empty.
+- Unsupported formats fail non-zero and write the actionable error to stderr.
+- Completed slices are exported when `--include-completed` is used.
+- Export includes source metadata, warnings, aggregates, approvals, blockers, evidence, next steps, lifecycle, specs, slices, agents, and runs.
+- Arrays used by specs, slices, evidence, and resolver-backed state remain deterministically ordered by existing resolver ordering.
+
+## Changes
+
+- Updated `src/create-quiver/lib/ai/export-state.js`.
+- Updated `tests/lib/ai-export-state.test.js`.
+- Updated `tests/commands/ai-export.test.js`.
+- Updated v27 spec status, execution plan, evidence, and this closure brief.
+
+## Remaining Risks
+
+- The export contract is additive, but downstream users that hard-code `schema_version: 1` will need to accept schema v2.
+- The schema is asserted by tests, but there is not yet a separate JSON Schema artifact; that can be added in a later hardening slice if needed.
+- Some approval and evidence fields may remain empty in projects that have not used the AI lifecycle yet.
+
+## Follow-up Recommendations
+
+- Execute `slice-03-approved-plan-to-spec-create` next because it depends on stable resolver/export behavior.
+- Keep any future export changes additive unless a new schema version and migration note are explicitly added.

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

@@ -0,0 +1,54 @@
+# EXECUTION BRIEF - slice-02: JSON export contract and machine output
+
+## Context
+
+Pixel Quiver could not consume `ai export --format json` directly because the output schema did not match dashboard needs and completed slices were missing in some states. This slice stabilizes machine output.
+
+## Objective
+
+Implement a stable, versioned JSON export contract and align AI export behavior with it.
+
+## Scope
+
+- Export resolver/adapters
+- CLI format handling
+- JSON schema fixtures/tests
+- v27 evidence/status docs
+
+## Acceptance Criteria
+
+- `--format json` emits parseable JSON only on stdout.
+- Export includes the required state, source metadata, warnings, and aggregates.
+- Completed slices appear with `--include-completed`.
+- Errors go to stderr and exit non-zero.
+- Arrays are deterministically ordered.
+
+## Technical Plan Summary
+
+Define schema, serialize from the shared resolver, align `ai export`, and add CLI parse tests.
+
+## Suggested Execution Steps
+
+1. Define export payload shape and schema version.
+2. Implement serializer over the shared resolver.
+3. Align `ai export` and/or add `export-specs`.
+4. Add valid/invalid fixtures and CLI tests.
+5. Update docs/evidence.
+
+## Restrictions
+
+- Do not add dashboard UI.
+- Do not mix human logs into JSON stdout.
+
+## Risks
+
+- Existing consumers may rely on older `ai export`; preserve or document compatibility.
+
+## Completion Checklist
+
+- [ ] Schema implemented.
+- [ ] CLI JSON parse tests added.
+- [ ] Completed slice export covered.
+- [ ] Error path covered.
+- [ ] Validation commands passed.
+

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