create-quiver 0.12.0 → 0.13.0

package/specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/slice-02-run-state-phase-locks/CLOSURE_BRIEF.md

@@ -0,0 +1,43 @@
+# CLOSURE BRIEF - slice-02: Run state, phase gates, and locks
+
+## Summary of Work
+
+- Added persistent AI lifecycle run state under `.quiver/runs/<run-id>/`.
+- Added `ai run create`, `ai status`, and `ai resume` command behavior.
+- Added approvals metadata for lifecycle runs.
+- Added run/slice lock helpers with stale-lock metadata in `.quiver/locks/`.
+- Connected `ai plan` and `ai approve` to lifecycle phase updates.
+- Added phase guard helpers for blocking future-phase work with next-command guidance.
+
+## Validation Against Acceptance Criteria
+
+- [x] Run creation inspected.
+- [x] Resume verified.
+- [x] Invalid phase blocked.
+- [x] Locks verified.
+- [x] Tests run.
+
+## Relevant Changes
+
+- `src/create-quiver/lib/ai/run-state.js`
+- `src/create-quiver/commands/ai.js`
+- `src/create-quiver/index.js`
+- `src/create-quiver/lib/init-layout.js`
+- `tests/lib/ai-run-state.test.js`
+- `tests/commands/ai-run-state.test.js`
+- `tests/lib/init-layout.test.js`
+- `README.md`
+- `README_FOR_AI.md`
+- `docs/COMMANDS.md.template`
+
+## Pending
+
+- None.
+
+## Remaining Risks
+
+- Locks are implemented as file locks with owner metadata. Process liveness cleanup is intentionally manual for now to avoid unsafe deletion.
+
+## Future Recommendations
+
+- Later slices should wire `assertAiRunPhaseAllows` into spec generation, execution planning, slice execution, and PR creation.

package/specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/slice-02-run-state-phase-locks/EXECUTION_BRIEF.md

@@ -0,0 +1,54 @@
+# EXECUTION BRIEF - slice-02: Run state, phase gates, and locks
+
+## Context
+
+The lifecycle must survive interruptions, multiple agents, and multiple terminal sessions. Chat memory is not a safe state store.
+
+## Objective
+
+Add persistent run state, phase validation, approvals metadata, status/resume, and locks.
+
+## Scope
+
+- `.quiver/runs/<run-id>/state.json`.
+- `.quiver/runs/<run-id>/approvals.json`.
+- Run status and resume commands or command paths.
+- Phase transition validation.
+- Run/slice locks and stale-lock recovery.
+
+## Acceptance Criteria
+
+- Run state persists and can be resumed.
+- Future-phase commands are blocked.
+- Locks prevent concurrent mutation.
+- Stale locks are recoverable with metadata.
+
+## Technical Plan Summary
+
+Create state helpers and phase transition guards before adding higher-level planner or executor flows.
+
+## Suggested Execution Steps
+
+1. Define state schema and phase enum.
+2. Add read/write helpers.
+3. Add phase guard utility.
+4. Add lock helpers.
+5. Wire status/resume commands.
+6. Test phase and lock behavior with temp fixtures.
+
+## Restrictions
+
+- Do not execute provider CLIs.
+- Do not generate specs in this slice.
+
+## Risks
+
+- State schema drift can break future runs. Keep it versioned or migration-ready.
+
+## Completion Checklist
+
+- [ ] State helpers implemented.
+- [ ] Phase guards implemented.
+- [ ] Locks implemented.
+- [ ] Tests passing.
+- [ ] Evidence appended.

package/specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/slice-02-run-state-phase-locks/slice.json

@@ -0,0 +1,52 @@
+{
+  "slice_id": "slice-02-run-state-phase-locks",
+  "ticket": "QUIVER-25-02",
+  "type": "feature",
+  "title": "Run state, phase gates, and locks",
+  "objective": "Persist AI lifecycle state and prevent invalid phase transitions or concurrent run corruption.",
+  "description": "Introduce `.quiver/runs/<run-id>/` state, approvals metadata, status/resume behavior, phase validation, and locks for runs and slices.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "run-state-phase-locks",
+    "branch_name": "feature/QUIVER-25-02-run-state-phase-locks"
+  },
+  "files": [
+    "src/create-quiver/**",
+    "docs/**",
+    "tests/**"
+  ],
+  "depends_on": [
+    "slice-01-cli-contract-compatibility"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Creates shared state machinery required by later slices.",
+  "must": [
+    "Create and load `.quiver/runs/<run-id>/state.json`.",
+    "Persist approvals metadata.",
+    "Add status and resume behavior.",
+    "Block commands that do not match the current phase.",
+    "Add run and slice locks with stale-lock metadata."
+  ],
+  "not_included": [
+    "Provider execution.",
+    "Generating specs from planner output.",
+    "Git worktree lifecycle."
+  ],
+  "acceptance": [
+    "A run can be created, inspected, and resumed.",
+    "Invalid future-phase commands are blocked with next-command guidance.",
+    "Run and slice locks prevent concurrent mutation.",
+    "Stale lock recovery shows metadata before removal.",
+    "State can be read without chat memory."
+  ],
+  "tests": [
+    "node --test tests/**/*.test.js",
+    "git diff --check"
+  ],
+  "estimated_hours": 6,
+  "status": "completed",
+  "blocked_reason": null,
+  "actual_hours": 3,
+  "completed_at": "2026-05-22T00:00:00-0300"
+}

package/specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/slice-03-safe-ai-onboarding-docs/CLOSURE_BRIEF.md

@@ -0,0 +1,35 @@
+# CLOSURE BRIEF - slice-03: Safe AI onboarding documentation
+
+## Summary of Work
+
+Implemented safe docs-only AI context preparation for new and existing projects.
+
+## Validation Against Acceptance Criteria
+
+- [x] New project fixture validated.
+- [x] Existing project fixture validated.
+- [x] Dry-run validated.
+- [x] Snapshot validated.
+- [x] Conflict reporting validated.
+
+## Relevant Changes
+
+- `ai prepare-context --dry-run` now reports proposed doc actions, compact diffs, assumptions, risks, contradictions, omitted paths, and uncertainty markers without writing.
+- Write mode snapshots touched docs under `.quiver/runs/<run-id>/snapshots/` before updating docs.
+- Existing human-authored docs are preserved; Quiver appends or refreshes a managed context-prep block instead of replacing the full file.
+- Context prep now targets `INDEX`, `PROJECT_MAP`, `AI_CONTEXT`, `AI_ONBOARDING_PROMPT`, `CONTEXTO`, `WORKFLOW`, `ARCHITECTURE`, `STATUS`, and `DECISIONS`.
+- Context prep advances the lifecycle run to `onboarding-ready` after successful docs writes.
+- README and command docs describe diff preview, snapshots, and contradiction reporting.
+
+## Pending
+
+No pending implementation for this slice.
+
+## Remaining Risks
+
+- Diff snippets are previews; full review should still use `git diff`.
+- Contradiction detection is conservative and should expand with more real project signals in future hardening.
+
+## Future Recommendations
+
+- Dogfood this slice on Quiver itself and on a small generated project.

package/specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/slice-03-safe-ai-onboarding-docs/EXECUTION_BRIEF.md

@@ -0,0 +1,53 @@
+# EXECUTION BRIEF - slice-03: Safe AI onboarding documentation
+
+## Context
+
+Quiver should reduce manual onboarding work by letting AI complete project context docs, but this must be safe in existing projects.
+
+## Objective
+
+Generate and update onboarding documentation with dry-run, snapshots, assumptions, and conflict reporting.
+
+## Scope
+
+- Docs-only onboarding generation.
+- New project and existing project behavior.
+- Dry-run previews and snapshots.
+- Uncertainty markers and contradiction reports.
+
+## Acceptance Criteria
+
+- New projects get generated onboarding docs.
+- Existing docs are preserved unless explicitly updated.
+- `--dry-run` writes nothing.
+- Snapshots are saved before writes.
+- Unknowns and contradictions are visible.
+
+## Technical Plan Summary
+
+Extend analyzer/context preparation into a safe doc writer that separates inferred facts from assumptions and uses the run state created in slice-02.
+
+## Suggested Execution Steps
+
+1. Define allowed docs and write policy.
+2. Add dry-run diff output.
+3. Add snapshot creation.
+4. Add uncertainty/conflict reporting.
+5. Cover project-new, project-existing, and old-Quiver fixtures.
+
+## Restrictions
+
+- Do not modify product code in target projects.
+- Do not read or log secret values from `.env` files.
+
+## Risks
+
+- AI text may sound more certain than evidence supports. Force uncertainty labels.
+
+## Completion Checklist
+
+- [ ] Dry-run implemented.
+- [ ] Snapshot behavior implemented.
+- [ ] Existing docs preservation tested.
+- [ ] Conflict reporting tested.
+- [ ] Evidence appended.

package/specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/slice-03-safe-ai-onboarding-docs/slice.json

@@ -0,0 +1,54 @@
+{
+  "slice_id": "slice-03-safe-ai-onboarding-docs",
+  "ticket": "QUIVER-25-03",
+  "type": "feature",
+  "title": "Safe AI onboarding documentation",
+  "objective": "Let Quiver use AI to generate and update project onboarding docs safely for new, existing, and older Quiver projects.",
+  "description": "Implement docs-only onboarding generation with dry-run, diffs, snapshots, assumptions, risks, and conflict reporting.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "safe-ai-onboarding-docs",
+    "branch_name": "feature/QUIVER-25-03-safe-ai-onboarding-docs"
+  },
+  "files": [
+    "src/create-quiver/**",
+    "docs/**",
+    "templates/**",
+    "tests/**"
+  ],
+  "depends_on": [
+    "slice-02-run-state-phase-locks"
+  ],
+  "parallel_safe": "yes",
+  "parallel_safe_reason": "Can run beside agent adapter work if command/state files do not overlap.",
+  "must": [
+    "Support onboarding generation with `--dry-run`.",
+    "Generate or update docs such as CONTEXTO, WORKFLOW, ARCHITECTURE, STATUS, INDEX, AI_CONTEXT, and PROJECT_MAP where applicable.",
+    "Mark uncertain content as TODO, Assumption, or Pending confirmation.",
+    "Preserve human-authored content and show diffs before writing.",
+    "Snapshot touched docs before writing.",
+    "Report contradictions instead of silently resolving them."
+  ],
+  "not_included": [
+    "Provider adapter implementation unless needed for prompt-only output.",
+    "Spec generation from approved plans.",
+    "Product code modification in target projects."
+  ],
+  "acceptance": [
+    "New projects receive useful onboarding docs from inferred stack/scripts/structure.",
+    "Existing projects update only approved docs without deleting useful content.",
+    "`--dry-run` writes nothing and reports proposed changes.",
+    "Snapshots are stored before writes.",
+    "Contradictions and unknowns are reported clearly.",
+    "No product code files are modified by onboarding generation."
+  ],
+  "tests": [
+    "node --test tests/**/*.test.js",
+    "git diff --check"
+  ],
+  "estimated_hours": 8,
+  "status": "completed",
+  "completed_at": "2026-05-22T16:31:18-0300",
+  "blocked_reason": null
+}

package/specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/slice-04-agent-profiles-adapters/CLOSURE_BRIEF.md

@@ -0,0 +1,34 @@
+# CLOSURE BRIEF - slice-04: Agent profiles and provider adapters
+
+## Summary of Work
+
+Implemented the provider-agnostic agent profile contract for planner, executor, reviewer, and doctor roles, plus prompt-only rendering and redacted provider output.
+
+## Validation Against Acceptance Criteria
+
+- [x] Profiles inspected.
+- [x] Prompt-only mode verified.
+- [x] Missing CLI guidance verified.
+- [x] Structured output captured.
+- [x] Tests run.
+
+## Relevant Changes
+
+- Added `doctor` as a supported agent profile and removed `researcher` from the public profile contract.
+- Added `--print-prompt` support for planner/reviewer AI commands without invoking provider CLIs.
+- Redacted likely secrets from provider stdout, stderr, and error messages.
+- Added focused tests for doctor profiles, prompt-only output, missing CLI guidance, structured provider metadata, and log redaction.
+- Updated README and command reference docs.
+
+## Pending
+
+No pending implementation for this slice.
+
+## Remaining Risks
+
+- Redaction remains best-effort and should not be treated as a reason to intentionally print secrets.
+- `ai doctor` does not yet use the doctor provider profile; it remains a local readiness/GitHub preflight command.
+
+## Future Recommendations
+
+- Consider a later explicit `ai doctor --provider` diagnostic flow if the doctor profile should run model-assisted diagnosis.

package/specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/slice-04-agent-profiles-adapters/EXECUTION_BRIEF.md

@@ -0,0 +1,54 @@
+# EXECUTION BRIEF - slice-04: Agent profiles and provider adapters
+
+## Context
+
+Quiver must support different model CLIs without hard-coding one provider or storing credentials.
+
+## Objective
+
+Add provider-agnostic agent profiles and adapter contracts, starting with prompt-only behavior.
+
+## Scope
+
+- Planner, executor, reviewer, and doctor profiles.
+- Provider command validation.
+- Prompt rendering.
+- Structured command result capture.
+- Secret redaction for adapter logs.
+
+## Acceptance Criteria
+
+- Profiles store labels and command preferences, not secrets.
+- Prompt-only mode works.
+- Missing CLI errors are actionable.
+- Execution metadata is captured when execution is enabled.
+
+## Technical Plan Summary
+
+Build a small adapter layer around external CLIs with explicit input/output contracts and dry-run-safe behavior.
+
+## Suggested Execution Steps
+
+1. Inspect current agent profile code.
+2. Define adapter interface.
+3. Implement prompt-only path.
+4. Add CLI availability checks.
+5. Add structured result capture and redaction.
+6. Test with mocked provider commands.
+
+## Restrictions
+
+- Do not require real provider credentials in tests.
+- Do not store API keys or tokens.
+
+## Risks
+
+- Provider CLIs differ substantially. Keep the first contract conservative.
+
+## Completion Checklist
+
+- [ ] Profile schema updated.
+- [ ] Prompt-only path validated.
+- [ ] Missing CLI errors tested.
+- [ ] Redaction tested.
+- [ ] Evidence appended.

package/specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/slice-04-agent-profiles-adapters/slice.json

@@ -0,0 +1,52 @@
+{
+  "slice_id": "slice-04-agent-profiles-adapters",
+  "ticket": "QUIVER-25-04",
+  "type": "feature",
+  "title": "Agent profiles and provider adapters",
+  "objective": "Create a safe provider-agnostic contract for planner, executor, reviewer, and doctor agents.",
+  "description": "Add profile and adapter behavior for Codex, Claude, Gemini, or custom commands, starting with prompt-only and dry-run-safe execution.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "agent-profiles-adapters",
+    "branch_name": "feature/QUIVER-25-04-agent-profiles-adapters"
+  },
+  "files": [
+    "src/create-quiver/**",
+    "docs/**",
+    "tests/**"
+  ],
+  "depends_on": [
+    "slice-02-run-state-phase-locks"
+  ],
+  "parallel_safe": "yes",
+  "parallel_safe_reason": "Can run beside onboarding docs if adapter files are isolated.",
+  "must": [
+    "Support planner, executor, reviewer, and doctor profiles.",
+    "Store provider/model labels but never credentials.",
+    "Support prompt-only output with `--print-prompt` or equivalent.",
+    "Validate provider CLI availability before execution.",
+    "Capture stdout, stderr, exit code, timeout, and sanitized logs.",
+    "Define fallback behavior when a CLI is missing."
+  ],
+  "not_included": [
+    "Approval gate implementation.",
+    "Spec generation.",
+    "Automatic multi-agent scheduling."
+  ],
+  "acceptance": [
+    "Profiles can be configured and inspected without secrets.",
+    "Prompt-only mode works without provider authentication.",
+    "Missing provider CLI produces actionable guidance.",
+    "Adapter output is captured in a structured way.",
+    "Logs redact likely secrets before writing."
+  ],
+  "tests": [
+    "node --test tests/**/*.test.js",
+    "git diff --check"
+  ],
+  "estimated_hours": 7,
+  "status": "completed",
+  "completed_at": "2026-05-22T16:21:54-0300",
+  "blocked_reason": null
+}

package/specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/slice-05-approval-gates/CLOSURE_BRIEF.md

@@ -0,0 +1,34 @@
+# CLOSURE BRIEF - slice-05: Approval gates and planner iterations
+
+## Summary of Work
+
+Implemented versioned planner approval gates for acceptance and technical-plan phases. `ai revise` now creates a new draft version from human feedback without approving or advancing the phase, while `ai approve` requires an explicit current draft version. Technical-plan approval now requires a production-readiness review for the current draft before spec generation can proceed.
+
+## Validation Against Acceptance Criteria
+
+- [x] Criteria revision flow verified.
+- [x] Criteria approval verified.
+- [x] Plan revision flow verified.
+- [x] Plan approval verified.
+- [x] Premature spec generation blocked.
+
+## Relevant Changes
+
+- Added `npx create-quiver ai revise`.
+- Changed `ai approve` to approve saved draft versions only with `--version <n>`.
+- Blocked approval of missing or non-current draft versions.
+- Required current production-readiness review before technical-plan approval.
+- Updated flow guidance, README, generated docs, init templates, and command reference.
+- Added regression tests for revise, approval versioning, stale review blocking, and spec generation gates.
+
+## Pending
+
+None for this slice.
+
+## Remaining Risks
+
+- Technical-plan review checks are local state based; external provider quality still depends on the configured reviewer prompt and model.
+
+## Future Recommendations
+
+- Keep approval messages concise and cite the approved draft version.

package/specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/slice-05-approval-gates/EXECUTION_BRIEF.md

@@ -0,0 +1,54 @@
+# EXECUTION BRIEF - slice-05: Approval gates and planner iterations
+
+## Context
+
+Human approval is central to Quiver. Planner output must be iterated and approved before later phases can run.
+
+## Objective
+
+Persist criteria and technical-plan drafts, revisions, and approvals with strict phase gates.
+
+## Scope
+
+- Acceptance criteria drafts.
+- Technical-plan drafts.
+- Revise commands.
+- Approval commands.
+- Approval state and phase blocking.
+
+## Acceptance Criteria
+
+- Drafts are versioned.
+- Revisions do not advance phase.
+- Approvals require concrete versions.
+- Spec generation is blocked before approval.
+- Approval history survives session changes.
+
+## Technical Plan Summary
+
+Use the run state from slice-02 and adapter prompts from slice-04 to manage planner drafts and approvals.
+
+## Suggested Execution Steps
+
+1. Define draft storage layout.
+2. Add criteria draft/revise/approve behavior.
+3. Add technical-plan draft/revise/review/approve behavior.
+4. Wire phase guards.
+5. Test invalid transitions.
+
+## Restrictions
+
+- Do not create spec/slice files in this slice.
+- Do not execute implementation agents.
+
+## Risks
+
+- Loose approval semantics can let users approve the wrong version. Require explicit version IDs.
+
+## Completion Checklist
+
+- [ ] Criteria gate tested.
+- [ ] Technical-plan gate tested.
+- [ ] Invalid transitions tested.
+- [ ] Approval state documented.
+- [ ] Evidence appended.

package/specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/slice-05-approval-gates/slice.json

@@ -0,0 +1,53 @@
+{
+  "slice_id": "slice-05-approval-gates",
+  "ticket": "QUIVER-25-05",
+  "type": "feature",
+  "title": "Approval gates and planner iterations",
+  "objective": "Implement human approval gates for criteria, technical plans, and production-readiness review.",
+  "description": "Persist versioned planner drafts, allow revisions, require explicit approval, and block later phases until approvals exist.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "approval-gates-planner-iterations",
+    "branch_name": "feature/QUIVER-25-05-approval-gates-planner-iterations"
+  },
+  "files": [
+    "src/create-quiver/**",
+    "docs/**",
+    "tests/**"
+  ],
+  "depends_on": [
+    "slice-02-run-state-phase-locks",
+    "slice-04-agent-profiles-adapters"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Depends on shared state and agent profile contracts.",
+  "must": [
+    "Store versioned acceptance criteria drafts.",
+    "Store versioned technical-plan drafts.",
+    "Support revise commands that do not advance phase.",
+    "Approve only concrete versions.",
+    "Block spec generation until the plan is approved.",
+    "Record approval decisions and timestamps."
+  ],
+  "not_included": [
+    "Spec file generation.",
+    "Slice execution.",
+    "PR creation."
+  ],
+  "acceptance": [
+    "Criteria drafts can be generated, revised, and approved.",
+    "Technical-plan drafts can be generated, revised, reviewed, and approved.",
+    "Approving a missing or non-current version fails clearly.",
+    "Spec generation is blocked before plan approval.",
+    "Approvals are readable from state without chat memory."
+  ],
+  "tests": [
+    "node --test tests/**/*.test.js",
+    "git diff --check"
+  ],
+  "estimated_hours": 7,
+  "status": "completed",
+  "blocked_reason": null,
+  "completed_at": "2026-05-22T16:45:36-0300"
+}

package/specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/slice-06-spec-slice-generator/CLOSURE_BRIEF.md

@@ -0,0 +1,33 @@
+# CLOSURE BRIEF - slice-06: Spec, slice, handoff, and PR body generation
+
+## Summary of Work
+
+Completed the generated artifact contract for specs and slices. Generated `slice.json` files now include dependency data, parallel safety, expected read paths, allowed write paths, and validation hints, and generated `EXECUTION_BRIEF.md` files expose the same execution contract for agents.
+
+## Validation Against Acceptance Criteria
+
+- [x] Blocked before plan approval.
+- [x] Dry-run verified.
+- [x] Spec artifacts generated.
+- [x] Slice handoffs generated.
+- [x] JSON validation passed.
+
+## Relevant Changes
+
+- Added generated `expected_read_paths`, `allowed_write_paths`, and `validation_hints` to `slice.json`.
+- Added validation that generated slice JSON contains those arrays.
+- Added the same read/write/validation sections to generated execution briefs.
+- Preserved backward compatibility by deriving `allowed_write_paths` from existing `files` and deriving `files` from explicit allowed write paths when needed.
+- Added fixture coverage for explicit and default scope declarations.
+
+## Pending
+
+None for this slice.
+
+## Remaining Risks
+
+- Generated scopes are only as accurate as the approved planner output and safe defaults.
+
+## Future Recommendations
+
+- Use generated artifacts to dogfood the next Quiver spec.

package/specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/slice-06-spec-slice-generator/EXECUTION_BRIEF.md

@@ -0,0 +1,56 @@
+# EXECUTION BRIEF - slice-06: Spec, slice, handoff, and PR body generation
+
+## Context
+
+Once the technical plan is approved, Quiver must turn it into durable artifacts that agents and humans can execute.
+
+## Objective
+
+Generate complete spec/slice/handoff/PR artifacts from approved planner output.
+
+## Scope
+
+- Spec folder creation.
+- Mandatory `slice-00`.
+- Slice JSON and handoff generation.
+- `EXECUTION_PLAN.md`, `EVIDENCE_REPORT.md`, `STATUS.md`, and `pr.md`.
+- File scope declarations.
+- Dry-run previews.
+
+## Acceptance Criteria
+
+- Generation is blocked before plan approval.
+- Dry-run lists all proposed files.
+- Artifacts follow Quiver layout.
+- Every slice has handoffs and parseable JSON.
+- `slice-00` exists.
+
+## Technical Plan Summary
+
+Transform approved planner output into the canonical `specs/<spec-slug>/` structure and validate before writing.
+
+## Suggested Execution Steps
+
+1. Define artifact generator contracts.
+2. Add dry-run preview.
+3. Generate top-level files.
+4. Generate slices and handoffs.
+5. Validate JSON and required files.
+6. Test with fixture planner outputs.
+
+## Restrictions
+
+- Do not run execution agents.
+- Do not commit or open PRs.
+
+## Risks
+
+- Poor planner output may create unusable slices. Validate and fail with actionable messages.
+
+## Completion Checklist
+
+- [ ] Dry-run tested.
+- [ ] Generated files validated.
+- [ ] Mandatory slice-00 tested.
+- [ ] PR body tested.
+- [ ] Evidence appended.