create-quiver 0.12.0 → 0.13.0

package/docs/COMMANDS.md.template

@@ -11,38 +11,61 @@ This document is the canonical command reference for the orchestration roadmap.
 |---------|---------|----|-------|---------|
 | `npx create-quiver init --name "<project>"` | Creates the default AI-first Quiver contract for a project | macOS, Linux, Windows | current | `npx create-quiver init --name "{{PROJECT_NAME}}"` |
 | `npx create-quiver --name "<project>"` | Compatibility alias for the recommended init flow | macOS, Linux, Windows | current | `npx create-quiver --name "{{PROJECT_NAME}}"` |
-| `npx create-quiver flow` | Shows the read-only guided flow entrypoint and next safe command | macOS, Linux, Windows | v0.11 | `npx create-quiver flow` |
-| `quiver:analyze` | Writes raw analyzer data to `.quiver/scans/PROJECT_SCAN.json` and the visible project map to `docs/PROJECT_MAP.md` | macOS, Linux, Windows | v0.8 | `npm run quiver:analyze` |
+| `npx create-quiver --version` | Prints the installed CLI version | macOS, Linux, Windows | current | `npx create-quiver --version` |
+| `npx create-quiver --help` | Lists all public commands with descriptions, key options, and recommended examples | macOS, Linux, Windows | current | `npx create-quiver --help` |
+| `npx create-quiver help` | Readable alias for the complete CLI help | macOS, Linux, Windows | current | `npx create-quiver help` |
+| `quiver --help` | Shows the same help when Quiver is installed locally as a project dependency | macOS, Linux, Windows | current | `quiver --help` |
+| `npx create-quiver flow` | Shows the read-only guided flow entrypoint, context source/freshness, package-manager-aware script guidance, and next safe command | macOS, Linux, Windows | v0.11 | `npx create-quiver flow` |
+| `npx create-quiver analyze --dry-run` | Previews scan, project-map, and AI context writes without creating files | macOS, Linux, Windows | v0.13 | `npx create-quiver analyze --dry-run` |
+| `quiver:analyze` | Writes raw analyzer data to `.quiver/scans/PROJECT_SCAN.json`, the visible project map to `docs/PROJECT_MAP.md`, and refreshed AI context | macOS, Linux, Windows | v0.8 | `npm run quiver:analyze` |
 | `quiver:flow` | Runs the guided flow entrypoint through the generated npm script | macOS, Linux, Windows | v0.11 | `npm run quiver:flow` |
 | `quiver:prepare` | Runs guided setup diagnostics and context preparation | macOS, Linux, Windows | v0.10 | `npm run quiver:prepare -- --dry-run --provider codex` |
 | `quiver:doctor` | Validates the Quiver contract and reports layout or migration guidance | macOS, Linux, Windows | v0.8 | `npm run quiver:doctor` |
 | `quiver:doctor -- --fix --dry-run` | Previews safe non-destructive repairs without writing files | macOS, Linux, Windows | v0.11 | `npm run quiver:doctor -- --fix --dry-run` |
 | `quiver:doctor -- --fix` | Applies safe idempotent repairs after review | macOS, Linux, Windows | v0.11 | `npm run quiver:doctor -- --fix` |
 | `quiver:evidence -- run -- <command>` | Captures command validation evidence with exit code, duration, redacted/truncated output, and a local Markdown record | macOS, Linux, Windows | v0.11 | `npm run quiver:evidence -- run -- npm test` |
+| `npx create-quiver ai run create --input <requirements.md>` | Creates a persistent AI lifecycle run under `.quiver/runs/` | macOS, Linux, Windows | v0.12 | `npx create-quiver ai run create --input requirements.md` |
+| `npx create-quiver ai status` | Shows the current AI lifecycle phase and next safe command | macOS, Linux, Windows | v0.12 | `npx create-quiver ai status` |
+| `npx create-quiver ai resume` | Resumes guidance from the last valid AI lifecycle phase | macOS, Linux, Windows | v0.12 | `npx create-quiver ai resume` |
+| `npx create-quiver ai inspect` | Shows actionable lifecycle state for specs, slices, runs, agents, layout, and next commands | macOS, Linux, Windows | v0.13 | `npx create-quiver ai inspect` |
+| `npx create-quiver ai export --format json` | Emits machine-readable specs, slices, runs, agents, dependencies, blockers, and migration state | macOS, Linux, Windows | v0.13 | `npx create-quiver ai export --format json` |
+| `npx create-quiver ai export --format markdown` | Emits readable Markdown lifecycle state for PRs or docs | macOS, Linux, Windows | v0.13 | `npx create-quiver ai export --format markdown` |
+| `npx create-quiver ai specs list` | Lists specs with state, progress, slice counts, and paths | macOS, Linux, Windows | v0.13 | `npx create-quiver ai specs list` |
+| `npx create-quiver ai slices list` | Lists slices with state, progress, dependencies, and blockers | macOS, Linux, Windows | v0.13 | `npx create-quiver ai slices list --json` |
+| `npx create-quiver ai trace report` | Reports AI runs, execution waves, and migration guidance | macOS, Linux, Windows | v0.13 | `npx create-quiver ai trace report` |
 | `npx create-quiver demo create spec-viewer --dry-run` | Previews the optional Quiver Spec Viewer demo scaffold without writing files | macOS, Linux, Windows | v0.11 | `npx create-quiver demo create spec-viewer --dry-run` |
-| `npx create-quiver demo create spec-viewer --dir <target>` | Creates a small static demo app with example specs, slices, and validation scripts | macOS, Linux, Windows | v0.11 | `npx create-quiver demo create spec-viewer --dir ./quiver-spec-viewer` |
-| `quiver:plan` | Sequential orchestration planning command | macOS, Linux, Windows | v0.8 | [docs/examples/plan.md](./examples/plan.md) |
-| `quiver:graph` | Parallel-level orchestration tree command | macOS, Linux, Windows | v0.8 | [docs/examples/graph.md](./examples/graph.md) |
-| `quiver:next` | Ready-slice suggestion command | macOS, Linux, Windows | v0.8 | [docs/examples/next.md](./examples/next.md) |
+| `npx create-quiver demo create spec-viewer --dir <target>` | Creates a small static demo app with Quiver metadata, example specs, slices, validation scripts, and port fallback | macOS, Linux, Windows | v0.12.1 | `npx create-quiver demo create spec-viewer --dir ./quiver-spec-viewer` |
+| `quiver:plan` | Sequential orchestration planning command | macOS, Linux, Windows | v0.8 | `npm run quiver:plan -- --spec <spec>` |
+| `quiver:graph` | Parallel-level orchestration tree command | macOS, Linux, Windows | v0.8 | `npm run quiver:graph -- --format mermaid --spec <spec>` |
+| `quiver:next` | Ready-slice suggestion command | macOS, Linux, Windows | v0.8 | `npm run quiver:next -- --all-ready` |
 | `quiver:plan -- --include-completed` | Shows completed slices for audit/demo history | macOS, Linux, Windows | v0.11 | `npm run quiver:plan -- --include-completed --spec <spec>` |
 | `quiver:graph -- --include-completed` | Includes completed slices in the dependency graph history view | macOS, Linux, Windows | v0.11 | `npm run quiver:graph -- --include-completed --spec <spec>` |
 | `quiver:next -- --include-completed` | Keeps actionable next-slice output and appends completed history | macOS, Linux, Windows | v0.11 | `npm run quiver:next -- --include-completed --spec <spec>` |
-| `quiver:ai:agent` | Stores reusable planner/executor/reviewer/researcher provider profiles without secrets | macOS, Linux, Windows | v0.11 | `npm run quiver:ai:agent -- set planner --provider codex --model "planner-model"` |
+| `quiver:ai:agent -- set <role> ... --dry-run` | Previews planner/executor/reviewer/doctor provider profile writes without creating `.quiver/agents/profiles.json` | macOS, Linux, Windows | v0.13 | `npm run quiver:ai:agent -- set planner --provider codex --model "planner-model" --dry-run` |
+| `quiver:ai:agent` | Stores reusable planner/executor/reviewer/doctor provider profiles without secrets | macOS, Linux, Windows | v0.11 | `npm run quiver:ai:agent -- set planner --provider codex --model "planner-model"` |
+| `quiver:ai:inspect` | Shows actionable lifecycle state through the generated npm script | macOS, Linux, Windows | v0.13 | `npm run quiver:ai:inspect` |
+| `quiver:ai:export` | Exports lifecycle state as JSON or Markdown through the generated npm script | macOS, Linux, Windows | v0.13 | `npm run quiver:ai:export -- --format json` |
+| `quiver:ai:specs` | Lists specs through the generated npm script | macOS, Linux, Windows | v0.13 | `npm run quiver:ai:specs` |
+| `quiver:ai:slices` | Lists slices through the generated npm script | macOS, Linux, Windows | v0.13 | `npm run quiver:ai:slices -- --json` |
+| `quiver:ai:trace` | Prints a trace report through the generated npm script | macOS, Linux, Windows | v0.13 | `npm run quiver:ai:trace` |
 | `quiver:ai:onboard` | Runs AI onboarding prompt through a supported local provider CLI | macOS, Linux, Windows | v0.10 | `npm run quiver:ai:onboard -- --dry-run` |
-| `quiver:ai:prepare-context` | Prepares docs-only AI context drafts and reports assumptions, risks, files considered, and omitted paths | macOS, Linux, Windows | v0.11 | `npm run quiver:ai:prepare-context -- --dry-run` |
+| `quiver:ai:prepare-context` | Prepares docs-only AI context drafts with diff preview, assumptions, risks, contradictions, and snapshots before writes | macOS, Linux, Windows | v0.11 | `npm run quiver:ai:prepare-context -- --dry-run` |
 | `quiver:ai:plan` | Runs phase-gated AI planning for acceptance criteria, technical plan, or spec generation | macOS, Linux, Windows | v0.10 | `npm run quiver:ai:plan -- --phase acceptance --input requirements.md --dry-run` |
+| `quiver:ai:revise` | Creates a new draft version from human feedback without approving or advancing the planner phase | macOS, Linux, Windows | v0.13 | `npm run quiver:ai:revise -- --phase acceptance --input feedback.md --dry-run` |
 | `quiver:ai:review-plan` | Reviews the technical-plan draft for production readiness before approval and spec generation | macOS, Linux, Windows | v0.11 | `npm run quiver:ai:review-plan -- --dry-run` |
-| `quiver:ai:approve` | Persists approved acceptance criteria or technical plans for the next planner phase | macOS, Linux, Windows | v0.10 | `npm run quiver:ai:approve -- --phase acceptance --input acceptance-approved.md` |
+| `quiver:ai:approve` | Approves a concrete saved draft version for the next planner phase | macOS, Linux, Windows | v0.10 | `npm run quiver:ai:approve -- --phase acceptance --version 1` |
 | `quiver:ai:prompt-slice` | Prints a minimal executor prompt for manual slice assignment without calling a provider | macOS, Linux, Windows | v0.11 | `npm run quiver:ai:prompt-slice -- --slice specs/<spec>/slices/<slice>/slice.json --dry-run` |
-| `quiver:ai:execute-slice` | Runs an executor agent against one slice handoff with scope checks and optional commit | macOS, Linux, Windows | v0.10 | `npm run quiver:ai:execute-slice -- --slice specs/<spec>/slices/<slice>/slice.json --dry-run --commit` |
+| `quiver:ai:execute-slice` | Runs one executor against a slice handoff with branch/worktree checks, scope checks, redacted logs, closure/evidence updates, and optional commit | macOS, Linux, Windows | v0.10 | `npm run quiver:ai:execute-slice -- --slice specs/<spec>/slices/<slice>/slice.json --dry-run --commit` |
 | `quiver:ai:execute-plan` | Prints or executes dependency-safe waves of slices, with manual prompts or delegated worktrees | macOS, Linux, Windows | v0.10 | `npm run quiver:ai:execute-plan -- --dry-run --commit --mode delegated` |
 | `quiver:ai:doctor` | Runs GitHub PR preflight checks without opening a PR | macOS, Linux, Windows | v0.10 | `npm run quiver:ai:doctor -- --dry-run --ssh-host-alias github-work --identity-file ~/.ssh/github-work` |
 | `quiver:ai:pr` | Validates `gh`, reads `pr.md`, prints a PR plan, and creates a PR only with `--create` | macOS, Linux, Windows | v0.10 | `npm run quiver:ai:pr -- --dry-run --input specs/<spec>/pr.md --ssh-host-alias github-work --identity-file ~/.ssh/github-work` |
 | `quiver:spec:create` | Creates the real spec tree from the reviewed approved technical plan | macOS, Linux, Windows | v0.11 | `npm run quiver:spec:create -- --dry-run` |
 | `quiver:spec:start` | Creates or reuses the dedicated worktree for one spec | macOS, Linux, Windows | v0.10 | `npm run quiver:spec:start -- specs/<spec>` |
 | `quiver:spec:status` | Shows spec worktree, branch, `slice-00`, and pending slices | macOS, Linux, Windows | v0.10 | `npm run quiver:spec:status -- specs/<spec>` |
+| `quiver:spec:validate` | Validates spec docs, slices, briefs, evidence, status, dependencies, and safe paths | macOS, Linux, Windows | v0.13 | `npm run quiver:spec:validate -- specs/<spec>` |
 | `quiver:spec:close` | Closes a merged clean spec worktree and pulls the main checkout | macOS, Linux, Windows | v0.10 | `npm run quiver:spec:close -- specs/<spec> --dry-run` |
 | `quiver:check-slice -- --local <slice.json>` | Runs local structural slice validation without remote/base checks | macOS, Linux, Windows | v0.11 | `npm run quiver:check-slice -- --local specs/<spec>/slices/<slice>/slice.json` |
+| `quiver:check-handoff -- <handoff-or-brief.md>` | Validates legacy `HANDOFF.md` files and per-slice `EXECUTION_BRIEF.md` / `CLOSURE_BRIEF.md` files | macOS, Linux, Windows | v0.12.1 | `npm run quiver:check-handoff -- specs/<spec>/slices/<slice>/EXECUTION_BRIEF.md` |
 
 ## CLI Flags
 
@@ -58,19 +81,21 @@ This document is the canonical command reference for the orchestration roadmap.
 | `--max-output <n>` | `evidence run` | Limit captured stdout and stderr characters per section |
 | `--dir <target>` | `demo create spec-viewer` | Select the demo target directory; default is `./quiver-spec-viewer` |
 | `--json` | `plan`, `graph`, `next` | Emit machine-readable JSON |
-| `--format <tree\|mermaid\|dot>` | `graph` | Output format |
 | `--all-ready` | `next` | List all ready slices instead of just the next one |
 | `--only-ready` | `plan` | Show only slices with no pending dependencies |
 | `--include-completed` | `plan`, `graph`, `next` | Include completed slices for audit/demo history without changing default pending-only behavior |
 | `--local` | `check-slice` | Run structural validation without remote/base checks; use normal mode before PR readiness |
 | `--spec <slug>` | `plan`, `graph`, `spec create` | Restrict output to one spec or override the generated spec slug |
-| `--provider <codex\|claude\|gemini>` | `ai onboard`, `ai plan`, `ai review-plan`, `ai execute-slice`, `ai execute-plan` | Select the local AI CLI adapter |
+| `--format <tree\|mermaid\|dot\|json\|markdown>` | `graph`, `ai export` | Select graph or lifecycle export output format |
+| `--provider <codex\|claude\|gemini>` | `ai onboard`, `ai plan`, `ai revise`, `ai review-plan`, `ai execute-slice`, `ai execute-plan` | Select the local AI CLI adapter |
 | `--model <label>` | `ai agent set` | Store a free-form model label in an agent profile; Quiver does not verify model availability |
 | `--label <label>` | `ai agent set` | Store a display label for the profile |
-| `--role <planner\|executor>` | `ai onboard`, `ai plan`, `ai execute-slice`, `ai execute-plan` | Select planner or executor role; execution requires executor |
-| `--context <full\|planning\|slice\|minimal>` | `ai onboard`, `ai plan`, `ai review-plan`, `ai execute-slice`, `ai execute-plan` | Select a token-budgeted context pack |
-| `--phase <acceptance\|technical-plan\|spec>` | `ai plan` | Select the gated planner phase |
-| `--input <file>` | `ai plan`, `ai review-plan`, `ai approve`, `ai pr`, `spec create` | Read approved requirements/plans or select the generated PR body |
+| `--dry-run` | `ai agent set` | Preview profile writes without creating or updating `.quiver/agents/profiles.json` |
+| `--print-prompt` | `ai onboard`, `ai plan`, `ai revise`, `ai review-plan` | Print the exact provider prompt and exit without executing provider CLIs or requiring provider auth |
+| `--role <planner\|executor\|reviewer\|doctor>` | `ai onboard`, `ai plan`, `ai revise`, `ai execute-slice`, `ai execute-plan` | Select an AI role; execution requires executor |
+| `--context <full\|planning\|slice\|minimal>` | `ai onboard`, `ai plan`, `ai revise`, `ai review-plan`, `ai execute-slice`, `ai execute-plan` | Select a token-budgeted context pack |
+| `--phase <acceptance\|technical-plan\|spec>` | `ai plan`, `ai revise`, `ai approve` | Select the gated planner phase; `ai revise` and `ai approve` do not support `spec` |
+| `--input <file>` | `ai plan`, `ai revise`, `ai review-plan`, `ai pr`, `spec create` | Read requirements, human feedback, plans, review targets, or select the generated PR body |
 | `--version <n>` | `ai approve` | Approve a specific saved draft version |
 | `--slice <slice.json>` | `ai prompt-slice`, `ai execute-slice` | Select the slice handoff to print or execute |
 | `--commit` | `ai execute-slice`, `ai execute-plan` | Commit validated slice changes after provider, scope, and tests pass |
@@ -91,18 +116,26 @@ This document is the canonical command reference for the orchestration roadmap.
 - `quiver:graph --format mermaid` is the PR-friendly Mermaid export; `--format dot` is for Graphviz/DOT consumers.
 - `quiver:next` prints the next ready slice and can auto-start it behind a confirmation prompt.
 - `check-slice` validates `depends_on` targets and requires `parallel_safe_reason` when `parallel_safe` is `never`.
-- `quiver:ai:onboard`, `quiver:ai:plan`, `quiver:ai:review-plan`, and `quiver:ai:execute-slice` support `codex`, `claude`, and `gemini` through local CLIs. Use `--dry-run` first to inspect the invocation without requiring provider auth.
-- `quiver:ai:prepare-context -- --dry-run` previews docs-only context drafts. Run it before write mode and review assumptions, risks, and omitted paths.
+- `check-handoff` validates both exceptional `HANDOFF.md` transfers and current slice-local `EXECUTION_BRIEF.md` / `CLOSURE_BRIEF.md` contracts.
+- `quiver:ai:onboard`, `quiver:ai:plan`, `quiver:ai:revise`, `quiver:ai:review-plan`, and `quiver:ai:execute-slice` support `codex`, `claude`, and `gemini` through local CLIs. Use `--dry-run` first to inspect the invocation without requiring provider auth, or `--print-prompt` to print the exact planner/reviewer prompt without executing a provider.
+- `quiver:ai:prepare-context -- --dry-run` previews docs-only context drafts, diff snippets, assumptions, risks, contradictions, and omitted paths. Write mode stores snapshots under `.quiver/runs/<run-id>/snapshots/` and preserves human-authored content by appending or refreshing a Quiver-managed block.
+- `quiver:flow` reports the detected package manager and the matching generated project script, for example `npm run quiver:flow`, `pnpm run quiver:flow`, `yarn run quiver:flow`, or `bun run quiver:flow`.
+- `quiver:ai:agent -- set ... --dry-run` previews provider/model profile changes without writing `.quiver/agents/profiles.json`.
 - `quiver:ai:agent` stores provider/model labels under `.quiver/agents/profiles.json`; credentials stay in the provider CLI or OS credential store.
+- `quiver:ai:inspect`, `quiver:ai:specs`, `quiver:ai:slices`, and `quiver:ai:trace` are read-only inspection surfaces for humans and agents.
+- `quiver:ai:export -- --format json` is the dashboard/agent-friendly state contract; `--format markdown` is the PR/docs-friendly version.
 - Planner drafts are versioned under `.quiver/approvals/<phase>/drafts/`; use `quiver:ai:review-plan -- --dry-run` before approving a technical-plan draft, then `quiver:ai:approve -- --phase technical-plan --version 1` to approve the reviewed version.
 - `quiver:ai:prompt-slice -- --dry-run` prints a paste-ready manual executor prompt and does not call a provider.
 - `quiver:evidence -- run -- <command>` preserves the wrapped command exit code. Redaction is best effort; avoid commands that intentionally print secrets.
 - `demo create spec-viewer` is optional and static; it must stay outside default `init`.
-- `quiver:ai:execute-slice -- --commit` creates exactly one commit only after provider, scope, and validation commands pass.
+- `quiver:spec:start -- --dry-run specs/<spec>` previews the spec worktree path and branch without creating a worktree.
+- `quiver:ai:execute-slice -- --commit` creates exactly one commit only after provider, branch/worktree, scope, and validation commands pass. Commit mode refuses pre-existing dirty files even if `--allow-dirty` is set. Successful execution updates `CLOSURE_BRIEF.md`, `EVIDENCE_REPORT.md`, `COMMAND_LOG.md`, `STATUS.md`, and `slice.json`; likely secrets in captured stdout/stderr are redacted.
 - `quiver:ai:execute-plan -- --dry-run --commit --mode manual` prints paste-ready executor prompt commands without provider execution.
 - `quiver:ai:execute-plan -- --dry-run --commit --mode delegated` prints safe delegated waves and falls back to sequential mode when file scope is missing or overlapping.
 - `quiver:ai:execute-plan -- --execute --commit --mode delegated` uses temporary worktrees for parallel-ready waves and integrates one validated commit per slice.
-- `quiver:ai:pr -- --dry-run` validates GitHub CLI, auth, Git remote, current branch/worktree, `docs/GITFLOW_PR_GUIDE.md`, SSH host alias, identity file, and `pr.md` without creating a PR. Add `--create` only after reviewing the plan.
+- `quiver:ai:pr -- --dry-run` validates GitHub CLI, auth, Git remote, current branch/worktree, `docs/GITFLOW_PR_GUIDE.md`, SSH host alias, optional identity file, `pr.md`, and open slice status without creating a PR. Add `--create` only after reviewing the plan.
+- GitHub auth and SSH diagnostics should identify likely account, scopes, and alias issues. When paths contain spaces, Quiver prints copy-safe examples for macOS/Linux, Windows PowerShell, Git Bash, and WSL.
 - `quiver:spec:close` refuses dirty or unmerged spec worktrees unless discard behavior is explicitly requested.
+- `npm run smoke:doctor-fixtures` validates the required fixture matrix for doctor, validation, and actionable error coverage in the Quiver source repo.
 - After `init` or `migrate`, Quiver auto-installs itself as a dev dependency. Use `--skip-install` to suppress.
 - Cross-platform authoring rules live in `docs/SUPPORT_MATRIX.md`.

package/docs/STATUS.md.template

@@ -10,9 +10,13 @@ This page tracks progress, blockers, and the current slice. Stack and command de
 
 ## Slice Summary
 
+No implementation slices exist yet. Create specs and slices only after acceptance criteria are approved and the technical plan is reviewed and approved.
+
+When slices exist, track them here with:
+
 | Slice | Title | Status | Progress | Spec |
 |-------|-------|--------|----------|------|
-| 01 | [Name] | Done | 100% | [link](../specs/{{PROJECT_SLUG}}/slices/slice-01/slice.json) |
+| slice-00 | Documentary foundation | Pending | 0% | `specs/<spec>/slices/slice-00-.../slice.json` |
 
 ## Blockers
 

package/docs/WORKFLOW.md.template

@@ -48,21 +48,23 @@ Use maps, metadata, diffs, and summaries first. Open full files only when the sm
 
 ## Execution
 
-1. Create or reuse the spec worktree with `npx create-quiver spec start specs/<spec-slug>` or `npm run quiver:spec:start -- specs/<spec-slug>`.
-2. Inspect manual prompts with `npx create-quiver ai execute-plan --dry-run --commit --mode manual` or delegated waves with `npm run quiver:ai:execute-plan -- --dry-run --commit --mode delegated`.
-3. Print a minimal manual executor prompt with `npx create-quiver ai prompt-slice --slice <slice.json> --dry-run` when assigning the slice to another agent.
-4. Bootstrap a single slice with `npx create-quiver start-slice <slice.json>` or `npm run quiver:start-slice -- <slice.json>` when manual execution is preferred.
+1. Create or reuse the spec worktree with `npx create-quiver spec start specs/<spec-slug>` or `npm run quiver:spec:start -- specs/<spec-slug>`. Use `--dry-run` first when you want to inspect the planned branch/path without changing Git state.
+2. Inspect lifecycle state with `npx create-quiver ai inspect`, or export it with `npx create-quiver ai export --format json` for dashboards/agents and `--format markdown` for PRs/docs.
+3. Inspect manual prompts with `npx create-quiver ai execute-plan --dry-run --commit --mode manual` or delegated waves with `npm run quiver:ai:execute-plan -- --dry-run --commit --mode delegated`.
+4. Print a minimal manual executor prompt with `npx create-quiver ai prompt-slice --slice <slice.json> --dry-run` when assigning the slice to another agent.
+5. Bootstrap a single slice with `npx create-quiver start-slice <slice.json>` or `npm run quiver:start-slice -- <slice.json>` when manual execution is preferred.
    - The bootstrap step should work with canonical paths and a local base branch when `origin` is absent.
    - Draft slices require `--allow-draft`; otherwise `npx create-quiver start-slice` exits before execution.
    - Legacy Bash wrappers remain available for compatibility, but generated projects should prefer the Node CLI and `quiver:*` npm scripts.
    - `start-slice` generates `docs/ai/ACTIVE_SLICE.md` and `WORKTREE_CONTEXT.md`; use the active slice brief as the source of truth for execution.
-5. Implement only what the slice declares.
-6. Make one commit for that slice, or let `ai execute-slice --commit` / `ai execute-plan --execute --commit --mode delegated` create it after provider, scope, and validation pass.
-7. Validate with `npx create-quiver check-slice <slice.json>` or `npm run quiver:check-slice -- <slice.json>`.
-8. Write evidence. Prefer `npx create-quiver evidence run -- <command>` when you need a compact local Markdown record of validation output.
-9. Repeat for the next slice until the spec is complete.
-10. Open one PR for the spec. Use `npx create-quiver ai pr --dry-run --input specs/<spec-slug>/pr.md ...` first, then add `--create` only after review.
-11. After the PR is merged and the spec worktree is clean, close it with `npx create-quiver spec close specs/<spec-slug>`.
+6. Implement only what the slice declares.
+7. Make one commit for that slice, or let `ai execute-slice --commit` / `ai execute-plan --execute --commit --mode delegated` create it after provider, branch/worktree, scope, and validation pass.
+   - `ai execute-slice` updates `CLOSURE_BRIEF.md`, `EVIDENCE_REPORT.md`, `COMMAND_LOG.md`, `STATUS.md`, and `slice.json` only after the provider changes in-scope files and validation passes.
+8. Validate with `npx create-quiver check-slice <slice.json>` or `npm run quiver:check-slice -- <slice.json>`.
+9. Write evidence. Prefer `npx create-quiver evidence run -- <command>` when you need a compact local Markdown record of validation output.
+10. Repeat for the next slice until the spec is complete.
+11. Open one PR for the spec. Use `npx create-quiver ai pr --dry-run --input specs/<spec-slug>/pr.md --ssh-host-alias <alias> ...` first, then add `--create` only after review. Quiver blocks PR creation while slices in that spec remain open.
+12. After the PR is merged and the spec worktree is clean, close it with `npx create-quiver spec close specs/<spec-slug>`.
 
 ## Support Contract
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-quiver",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "private": false,
   "description": "Quiver CLI for scaffolding projects from the packaged template",
   "license": "MIT",
@@ -17,12 +17,17 @@
     "quiver:analyze": "npx create-quiver analyze",
     "quiver:flow": "npx create-quiver flow",
     "quiver:prepare": "npx create-quiver prepare",
-    "quiver:plan": "npx create-quiver plan",
-    "quiver:graph": "npx create-quiver graph",
+    "quiver:plan": "node bin/create-quiver.js plan",
+    "quiver:graph": "node bin/create-quiver.js graph",
     "quiver:next": "npx create-quiver next",
     "quiver:doctor": "npx create-quiver doctor",
     "quiver:evidence": "npx create-quiver evidence",
     "quiver:ai:agent": "npx create-quiver ai agent",
+    "quiver:ai:inspect": "npx create-quiver ai inspect",
+    "quiver:ai:export": "npx create-quiver ai export",
+    "quiver:ai:specs": "npx create-quiver ai specs list",
+    "quiver:ai:slices": "npx create-quiver ai slices list",
+    "quiver:ai:trace": "npx create-quiver ai trace report",
     "quiver:ai:onboard": "npx create-quiver ai onboard",
     "quiver:ai:prepare-context": "npx create-quiver ai prepare-context",
     "quiver:ai:plan": "npx create-quiver ai plan",
@@ -36,9 +41,11 @@
     "quiver:spec:create": "npx create-quiver spec create",
     "quiver:spec:start": "npx create-quiver spec start",
     "quiver:spec:status": "npx create-quiver spec status",
+    "quiver:spec:validate": "npx create-quiver spec validate",
     "quiver:spec:close": "npx create-quiver spec close",
     "package:quiver": "bash scripts/package-quiver.sh",
     "smoke:create-quiver": "bash scripts/ci/smoke-create-quiver.sh",
+    "smoke:doctor-fixtures": "node scripts/ci/smoke-doctor-fixtures.js",
     "smoke:tiered-pack": "bash scripts/ci/smoke-tiered-pack.sh",
     "smoke:guided-workflow": "bash scripts/ci/smoke-guided-workflow.sh",
     "release:quiver": "bash scripts/release-quiver.sh"

package/specs/quiver-v25-ai-first-lifecycle-orchestrator/EVIDENCE_REPORT.md

@@ -0,0 +1,293 @@
+# Evidence Report - Quiver v25 AI-First Lifecycle Orchestrator
+
+## Summary
+
+This report starts with documentation-only evidence for `slice-00`. Product implementation evidence must be appended by each later slice.
+
+## slice-00 - Spec foundation
+
+### Completed
+
+- Created v25 spec folder.
+- Created `SPEC.md`, `STATUS.md`, `EXECUTION_PLAN.md`, `EVIDENCE_REPORT.md`, and `pr.md`.
+- Created every slice folder with `slice.json`, `EXECUTION_BRIEF.md`, and `CLOSURE_BRIEF.md`.
+- Updated source-of-truth planning docs to mention v25 as planned without claiming package publication.
+
+### Validation
+
+- `git diff --check` passed.
+- `find specs/quiver-v25-ai-first-lifecycle-orchestrator -name "slice.json" -print -exec node -e "JSON.parse(require('fs').readFileSync(process.argv[1], 'utf8'))" {} \;` passed for 12 slice files.
+- `find specs/quiver-v25-ai-first-lifecycle-orchestrator/slices -maxdepth 2 -type f | wc -l` returned 36 slice files.
+- `npm run quiver:plan -- --spec quiver-v25-ai-first-lifecycle-orchestrator --include-completed` failed with Node out-of-memory after starting `npx create-quiver plan`. This does not invalidate the documentation package, but it is evidence that scoped planning can still have a scaling or command execution issue in the current CLI and should be considered by `slice-10-validation-errors-fixtures`.
+- `npm view create-quiver version` returned `0.12.0`; release documentation should be synchronized before future docs claim the latest package status.
+
+### Risks Observed During Validation
+
+- The scoped plan command can consume too much memory on the current repo. Future implementation should include a fixture or regression test that proves `--spec <slug>` does not scan or retain unnecessary data from unrelated specs.
+
+## Later Slices
+
+Each implementation slice must append:
+
+- commands executed;
+- tests or smokes run;
+- files changed;
+- validation result;
+- risks remaining;
+- evidence location.
+
+## slice-01 - CLI contract and compatibility
+
+### Completed
+
+- Added top-level `--version` and `-V` handling before normal argument parsing.
+- Kept `--version <n>` available for `ai approve`.
+- Added focused CLI contract tests.
+- Added command reference docs for version output.
+
+### Validation
+
+- `node bin/create-quiver.js --version` passed and printed `0.12.0`.
+- `node bin/create-quiver.js -V` passed and printed `0.12.0`.
+- `node --test tests/commands/cli-contract.test.js tests/commands/init-profiles.test.js tests/commands/flow.test.js tests/lib/init-layout.test.js` passed: 36 tests.
+- `git diff --check` passed.
+
+### Risks
+
+- The local `quiver` binary alias is validated through `package.json` and the shared entrypoint, not by installing the package into a fixture.
+
+## slice-02 - Run state, phase gates, and locks
+
+### Completed
+
+- Added `.quiver/runs/<run-id>/state.json`, `approvals.json`, copied requirement input, and decision log scaffolding.
+- Added `.quiver/locks/` as runtime-only internal state.
+- Added `ai run create`, `ai status`, and `ai resume`.
+- Added lifecycle phase helpers, next-command guidance, approval metadata recording, and run/slice lock helpers.
+- Connected `ai plan` and `ai approve` to lifecycle run phase updates.
+
+### Validation
+
+- `node --test tests/lib/ai-run-state.test.js tests/commands/ai-run-state.test.js tests/commands/ai-plan.test.js tests/lib/approvals.test.js tests/lib/init-layout.test.js` passed: 25 tests.
+- `node /Users/fabrijk/Documents/Work/Proyectos\ Personales/nika/frameworks/quiver/bin/create-quiver.js ai status` from `/private/tmp` passed and reported no active run without creating files.
+- `node --test tests/**/*.test.js` passed: 264 tests.
+- `git diff --check` passed.
+
+### Risks
+
+- File locks intentionally require manual inspection/removal when stale; automatic process liveness cleanup is deferred to avoid unsafe cross-platform behavior.
+- Phase guards are available and used by lifecycle status tests, but later slices still need to wire them into spec generation, execution planning, slice execution, and PR creation.
+
+## slice-03 - Safe AI onboarding documentation
+
+### Completed
+
+- Expanded `ai prepare-context` to prepare `INDEX`, `PROJECT_MAP`, `AI_CONTEXT`, `AI_ONBOARDING_PROMPT`, `CONTEXTO`, `WORKFLOW`, `ARCHITECTURE`, `STATUS`, and `DECISIONS` where applicable.
+- Added dry-run write plans with proposed actions, diff snippets, assumptions, risks, contradictions, omitted paths, and uncertainty markers.
+- Added write-mode snapshots under `.quiver/runs/<run-id>/snapshots/` before modifying docs.
+- Preserved human-authored content by appending or refreshing a Quiver-managed context block in existing docs.
+- Added contradiction detection for stale `docs/PROJECT_MAP.md` project name/package manager signals.
+- Wired `ai prepare-context` writes into the AI run lifecycle by advancing to `onboarding-ready`.
+- Updated README, README_FOR_AI, and command docs with the new safe docs behavior.
+
+### Validation
+
+- `node --test tests/commands/ai-onboard.test.js tests/lib/ai-context-packs.test.js tests/lib/init-docs.test.js tests/commands/analyze.test.js` passed: 25 tests.
+- `node --test tests/**/*.test.js` passed: 272 tests.
+- `node -e "JSON.parse(require('fs').readFileSync('specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/slice-03-safe-ai-onboarding-docs/slice.json','utf8')); console.log('slice-03 json ok')"` passed.
+- `git diff --check` passed.
+
+### Risks
+
+- Diff snippets are compact previews, not full patch files; users should still inspect `git diff` before committing generated docs.
+- Contradiction detection is intentionally conservative and currently focuses on high-signal project identity and package-manager mismatches.
+
+## slice-04 - Agent profiles and provider adapters
+
+### Completed
+
+- Replaced the old `researcher` profile slot with `doctor` to match the v25 agent contract.
+- Added prompt-only output through `--print-prompt` for `ai onboard`, `ai plan`, and `ai review-plan`.
+- Kept prompt-only paths provider-auth-free by rendering prompts without running provider preflight or spawn.
+- Added best-effort redaction of likely secrets in provider stdout, stderr, and serialized error messages.
+- Updated README and command reference docs for doctor profiles and prompt-only mode.
+
+### Validation
+
+- `node --test tests/lib/agent-profiles.test.js tests/commands/ai-agent.test.js tests/lib/ai-providers.test.js tests/commands/ai-onboard.test.js tests/commands/ai-plan.test.js tests/commands/ai-review-plan.test.js` passed: 40 tests.
+- `node --test tests/**/*.test.js` passed: 270 tests.
+- `git diff --check` passed.
+
+### Risks
+
+- Redaction is intentionally best-effort and may hide some diagnostic text if provider output contains key-like labels such as `token=` or `password=`.
+- The `doctor` profile is configurable now, but `ai doctor` itself remains a GitHub/readiness preflight and does not invoke a provider in this slice.
+
+## slice-05 - Approval gates and planner iterations
+
+### Completed
+
+- Added `ai revise` as a phase-safe planner revision command for acceptance and technical-plan drafts.
+- Changed `ai approve` so it requires `--version <n>` and approves only the current saved draft version.
+- Blocked direct approval from arbitrary input files; human feedback must create a new draft through `ai revise`.
+- Required a current production-readiness review before approving a technical-plan draft.
+- Kept spec generation blocked until the reviewed technical-plan draft is approved.
+- Updated README, README_FOR_AI, command docs, onboarding templates, generated init docs, flow guidance, package scripts, and CLI help examples.
+- Added tests for versioned approvals, missing/non-current approval failures, acceptance revise, technical-plan revise, stale review blocking, and spec generation gates.
+
+### Validation
+
+- `node --test tests/commands/ai-plan.test.js tests/commands/ai-review-plan.test.js tests/commands/ai-plan-spec-phase.test.js tests/lib/approvals.test.js tests/commands/flow.test.js tests/lib/init-layout.test.js` passed: 48 tests.
+- `node --test tests/**/*.test.js` passed: 276 tests.
+- `git diff --check` passed.
+- `node -e "const fs=require('fs'); for (const f of process.argv.slice(1)) JSON.parse(fs.readFileSync(f,'utf8')); console.log('slice json ok:', process.argv.length-1);" specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/*/slice.json` passed for 12 slice files.
+
+### Risks
+
+- `ai revise` now gives the planner the current draft plus feedback; output quality still depends on the selected provider/model.
+- Approval state remains file-based under `.quiver/approvals`; concurrent writes are still governed by later execution/locking hardening.
+
+## slice-06 - Spec, slice, handoff, and PR body generation
+
+### Completed
+
+- Completed the generated slice artifact contract with `expected_read_paths`, `allowed_write_paths`, and `validation_hints`.
+- Added generated execution brief sections for read paths, write paths, and validation hints.
+- Preserved compatibility with existing `files` and `tests` fields while exposing clearer agent-facing fields.
+- Added validation that generated `slice.json` files contain required scope arrays.
+- Added fixture coverage for explicit generated scope fields and default derivation from existing `files`/`tests`.
+
+### Validation
+
+- `node --test tests/lib/ai-spec-generator.test.js tests/commands/spec-create.test.js tests/commands/ai-plan-spec-phase.test.js` passed: 9 tests.
+- `node --test tests/**/*.test.js` passed: 276 tests.
+- `git diff --check` passed.
+- `node -e "const fs=require('fs'); for (const f of process.argv.slice(1)) JSON.parse(fs.readFileSync(f,'utf8')); console.log('slice json ok:', process.argv.length-1);" specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/*/slice.json` passed for 12 slice files.
+
+### Risks
+
+- Generated read/write scopes depend on the approved plan quality; later validation slices should keep hardening error messages when planner output is incomplete.
+- Existing executor code still primarily reads `files` for scope checks; generated `allowed_write_paths` is now aligned with `files` but deeper executor support belongs to later slices.
+
+## slice-07 - Slice execution planning and parallel safety
+
+### Completed
+
+- Updated slice graph reads to treat `allowed_write_paths` as the authoritative write scope when present.
+- Preserved compatibility by falling back to existing `files` when `allowed_write_paths` is absent.
+- Added execution plan JSON metadata for `expected_read_paths`, `allowed_write_paths`, and `validation_hints`.
+- Updated human execution plan output to show `Wave <n>` and each slice's `parallel_safe` rationale.
+- Added regression coverage for conflicts detected from `allowed_write_paths` even when `files` is empty.
+- Added CLI JSON coverage for downstream agent/dashboard consumption.
+
+### Validation
+
+- `node --test tests/lib/slice-graph.test.js tests/lib/ai-execution-plan.test.js tests/commands/ai-execute-plan.test.js tests/commands/plan.test.js tests/commands/graph.test.js tests/commands/next.test.js` passed: 46 tests.
+- `node --test tests/**/*.test.js` passed: 279 tests.
+- `git diff --check` passed.
+- `node -e "const fs=require('fs'); for (const f of process.argv.slice(1)) JSON.parse(fs.readFileSync(f,'utf8')); console.log('slice json ok:', process.argv.length-1);" specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/*/slice.json` passed for 12 slice files.
+
+### Risks
+
+- If planner output omits both `allowed_write_paths` and `files`, Quiver correctly falls back to sequential execution, but the user still needs to fix the slice contract.
+- Parallel execution still requires later execution slices to enforce scope and commit behavior during actual provider runs.
+
+## slice-08 - Controlled slice execution and evidence
+
+### Completed
+
+- Updated slice metadata resolution so `allowed_write_paths` becomes the authoritative executor write scope while preserving `files` fallback.
+- Added simple glob-aware scope validation for declared write paths such as `src/**` and `tests/**/*.test.js`.
+- Added branch/worktree validation for direct `ai execute-slice` runs and kept `ai execute-plan` delegated worktrees explicitly exempt through internal orchestration.
+- Expanded executor context with expected read paths and validation hints while keeping prompt-only/manual execution minimal.
+- Added automatic closure artifacts after successful execution: `CLOSURE_BRIEF.md`, `EVIDENCE_REPORT.md`, `COMMAND_LOG.md`, `STATUS.md`, and `slice.json`.
+- Added no-op protection so a provider that changes no in-scope files cannot close a slice.
+- Redacted likely secrets from provider output, validation output, command logs, and saved execution evidence.
+- Updated README and generated command/workflow docs for the controlled execution behavior.
+
+### Validation
+
+- `node --test tests/lib/scope.test.js tests/lib/ai-executor.test.js tests/commands/ai-execute-slice.test.js tests/lib/ai-execution-plan.test.js tests/commands/ai-execute-plan.test.js` passed: 39 tests.
+- `node --test tests/**/*.test.js` passed: 285 tests.
+
+### Risks
+
+- Scope glob support is intentionally simple and covers the common `*` and `**` cases used by Quiver-generated slices; more advanced glob syntax remains out of scope.
+- Direct `ai execute-slice` now requires the declared slice branch. Orchestrated `ai execute-plan` execution bypasses that specific branch check because it manages temporary worktrees itself.
+
+## slice-09 - Git worktree, commit, PR, and close lifecycle
+
+### Completed
+
+- Added `spec start --dry-run` so users can inspect the spec branch and worktree path before mutating Git state.
+- Hardened `ai execute-slice --commit` so commit mode refuses pre-existing dirty files even when `--allow-dirty` is set.
+- Required `--ssh-host-alias` for GitHub PR preflight and added macOS/Linux/Windows SSH alias guidance.
+- Blocked PR creation from `specs/<slug>/pr.md` while slices in that spec are still open.
+- Preserved PR creation through generated `pr.md` and existing `gh pr create` argument-array execution.
+- Kept `spec close` behavior that refuses dirty/unmerged worktrees, supports dry-run, removes the worktree after merge, and pulls the main checkout when a remote base is available.
+- Updated README, README_FOR_AI, command docs, workflow docs, and CLI help examples for the hardened lifecycle.
+
+### Validation
+
+- `node --test tests/lib/ai-executor.test.js tests/lib/ai-github.test.js tests/commands/ai-pr.test.js tests/lib/lifecycle.test.js tests/commands/spec-close.test.js tests/commands/ai-execute-plan.test.js` passed: 52 tests.
+- `node --test tests/**/*.test.js` passed: 290 tests.
+- `git diff --check` passed.
+
+### Risks
+
+- SSH alias validation checks that the alias was provided, not that the remote host accepts the key; users should still run `ssh -T <alias>` when configuring credentials.
+- Open-slice PR blocking applies to `specs/<slug>/pr.md` paths. Non-standard PR body locations are still allowed for advanced/manual flows.
+
+## slice-10 - Validation, actionable errors, redaction, and fixtures
+
+### Completed
+
+- Added a shared actionable error formatter with explicit `Impact`, `Fix`, and `Next command` fields.
+- Applied actionable error formatting to missing agent-profile guidance, missing SSH alias PR preflight, and open-slice PR blocking.
+- Added doctor environment warnings for Node, npm, git, gh, gh auth, shell, write permissions, and paths with spaces.
+- Added `tests/fixtures/validation-errors/matrix.json` as the official fixture matrix for new, existing, old Quiver, monorepo, no git, dirty git, no gh, paths with spaces, docs contradiction, and missing agent profile states.
+- Added `npm run smoke:doctor-fixtures` to enforce the fixture matrix in CI.
+- Updated README, README_FOR_AI, and command docs to mention the new smoke and validation contract.
+- Delegated a bounded fixture-gap scan to a sub-agent and incorporated its high-signal recommendations into the implementation.
+
+### Validation
+
+- `node --test tests/lib/doctor.test.js tests/lib/ai-github.test.js tests/commands/ai-agent.test.js tests/commands/doctor.test.js` passed: 30 tests.
+- `npm run smoke:doctor-fixtures` passed: 10 fixture states.
+- `node --test tests/**/*.test.js` passed: 294 tests.
+- `npm run smoke:create-quiver` passed.
+- `npm run smoke:guided-workflow` passed.
+- `git diff --check` passed.
+
+### Risks
+
+- Doctor environment checks are warnings, not hard failures, to avoid blocking offline or partially configured projects.
+- The validation fixture matrix is a contract manifest; individual deep fixtures should continue to grow as new bugs are found.
+
+## slice-11 - Export, dashboard-friendly output, and migration
+
+### Completed
+
+- Added `ai inspect`, `ai export`, `ai specs list`, `ai slices list`, and `ai trace report` surfaces.
+- Added `src/create-quiver/lib/ai/export-state.js` with a versioned lifecycle export shape for specs, slices, runs, agents, dependencies, blockers, progress, migration findings, and dashboard consumers.
+- Added JSON export as the default `ai export` output and Markdown export for PR/docs usage.
+- Added generated npm scripts for `quiver:ai:inspect`, `quiver:ai:export`, `quiver:ai:specs`, `quiver:ai:slices`, and `quiver:ai:trace`.
+- Added `migrate --dry-run` so older Quiver projects can preview planned migration changes without writing files.
+- Hardened `parseJsonWithComments` so JSON strings containing `//`, `/* ... */`, or glob patterns such as `src/**` are preserved.
+- Updated README, README_FOR_AI, command templates, workflow template, onboarding prompt template, and generated README text.
+
+### Validation
+
+- `node --test tests/lib/json.test.js tests/lib/ai-export-state.test.js tests/commands/ai-export.test.js tests/commands/init-profiles.test.js` passed: 20 tests.
+- `node --test tests/lib/init-layout.test.js tests/lib/json.test.js tests/lib/ai-export-state.test.js tests/commands/ai-export.test.js tests/commands/init-profiles.test.js` passed: 28 tests.
+- `node --test tests/**/*.test.js` passed: 301 tests.
+- `npm run smoke:create-quiver` passed.
+- `npm run smoke:guided-workflow` passed: 128 tests plus guided workflow smoke.
+- `npm run smoke:doctor-fixtures` passed: 10 fixture states.
+- `git diff --check` passed.
+- `node -e "JSON.parse(require('fs').readFileSync('package.json','utf8')); JSON.parse(require('fs').readFileSync('specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/slice-11-export-dashboard-migration/slice.json','utf8'));"` passed.
+
+### Risks
+
+- The JSON export is intentionally versioned with `schema_version: 1`; dashboards should treat it as a stable-but-young contract and pin expectations.
+- The core package remains UI-free. Any visual dashboard should consume `ai export --format json` externally rather than adding heavy dependencies to core.

package/specs/quiver-v25-ai-first-lifecycle-orchestrator/EXECUTION_PLAN.md

@@ -0,0 +1,58 @@
+# Execution Plan - Quiver v25
+
+## Wave 0 - Required Foundation
+
+1. `slice-00-spec-foundation`
+   - Must land first.
+   - Publishes the spec, slices, handoffs, execution plan, PR body, and source-of-truth planning references.
+
+## Wave 1 - Command and State Foundations
+
+Run sequentially:
+
+1. `slice-01-cli-contract-compatibility`
+2. `slice-02-run-state-phase-locks`
+
+These are foundational and should not run in parallel because later work depends on command names, aliases, phase validation, and persistent state.
+
+## Wave 2 - Onboarding and Agent Contracts
+
+Can run in parallel after Wave 1 if file scopes do not overlap:
+
+1. `slice-03-safe-ai-onboarding-docs`
+2. `slice-04-agent-profiles-adapters`
+
+## Wave 3 - Planner Gates and Generation
+
+Run sequentially:
+
+1. `slice-05-approval-gates`
+2. `slice-06-spec-slice-generator`
+3. `slice-07-slice-execution-planner`
+
+These depend on approved phase state and generated artifact contracts.
+
+## Wave 4 - Execution Lifecycle
+
+Run sequentially:
+
+1. `slice-08-controlled-slice-execution`
+2. `slice-09-git-worktree-pr-lifecycle`
+
+The Git/PR lifecycle depends on reliable slice closure and evidence.
+
+## Wave 5 - Hardening and Outputs
+
+Can run in parallel after Wave 4 if write scopes stay separate:
+
+1. `slice-10-validation-errors-fixtures`
+2. `slice-11-export-dashboard-migration`
+
+## Parallel Safety Notes
+
+- Do not run two slices in parallel if both modify CLI routing or shared command utilities.
+- Do not execute slices in parallel if `allowed_write_paths` overlap.
+- `slice-00` must be committed before implementation slices.
+- Prefer one commit per slice.
+- Run focused tests for touched commands during each slice.
+- Run full smoke/package safety only in final hardening unless package behavior changes earlier.