create-quiver 0.12.0 → 0.12.1

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.12.1",
   "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",
@@ -39,6 +44,7 @@
     "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.