create-quiver 0.10.0 → 0.12.1

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.

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

@@ -0,0 +1,242 @@
+# Quiver v25 - AI-First Lifecycle Orchestrator
+
+**Date:** 2026-05-22
+**Status:** In progress
+
+Slice numbering resets here. This spec intentionally starts at `slice-00`.
+
+## Problem
+
+Quiver already has guided AI workflow commands, planner drafts, approvals, spec creation, executor prompts, delegated execution modes, worktrees, PR support, evidence capture, and dogfooding hardening. Real use still shows a larger product gap: the ideal workflow is not yet experienced as one durable, phase-gated, AI-first lifecycle that starts from a natural-language requirement and carries the work through onboarding, approvals, specs, slices, execution, commits, PR, merge cleanup, and project context documentation.
+
+The most important gap is not only execution. It is that Quiver must own the state of the workflow so a human and multiple agents do not rely on chat memory, pasted prompts, or manual reconstruction of context.
+
+## Objective
+
+Turn Quiver into a production-ready AI-first lifecycle orchestrator for WDD + SDD:
+
+- prepare project onboarding documentation with AI for new and existing projects;
+- run planner and executor flows through explicit human approval gates;
+- persist state, approvals, prompts, versions, logs, and evidence under `.quiver/`;
+- generate specs, slices, handoffs, execution plans, and PR body from approved plans;
+- execute slices with minimal context and controlled write scope;
+- support worktree-per-spec, one commit per slice, PR creation, post-merge cleanup, validation, and migration;
+- keep command behavior clear across `npx create-quiver`, local `quiver`, and generated `quiver:*` scripts.
+
+## Context
+
+This spec is based on approved acceptance criteria and a production-readiness review performed during Quiver dogfooding. It extends the work already delivered by:
+
+- v20 AI CLI Orchestration;
+- v21 AI-First Layout;
+- v22 Guided AI Workflow;
+- v23 Guided Flow Productization;
+- v24 DX Onboarding Hardening.
+
+The spec does not assume that every AI provider CLI behaves the same. It requires adapter contracts, prompt-only mode, dry-runs, phase locks, and safe persistence before deeper automation.
+
+## Core Decisions
+
+- `npx create-quiver` remains the canonical bootstrap command.
+- `quiver` remains a local installed alias to the same CLI behavior, not a replacement for bootstrap.
+- Generated `quiver:*` npm scripts remain the repeatable project workflow surface.
+- `ai` is the canonical command namespace. `ia` may be added only as an alias if it does not increase ambiguity.
+- `slice-00` is mandatory for every generated spec and must publish the planning package before implementation starts.
+- State that drives execution lives under `.quiver/`; versionable delivery artifacts live under `specs/<spec-slug>/` and project docs under `docs/`.
+- Agent profiles must not store API keys, tokens, or credentials.
+- Documentation generated by AI must never silently overwrite human content.
+- Automatic agent execution must be optional; prompt-only mode must remain available.
+- Human approval gates are part of the product contract and cannot be bypassed silently.
+
+## Scope
+
+### Included
+
+- CLI contract and compatibility across `create-quiver`, local `quiver`, and generated scripts.
+- Strict run state machine with phase validation, resume/status, approvals, and locks.
+- Safe AI-assisted onboarding docs for new, existing, and older Quiver projects.
+- Agent profiles and provider CLI adapters for planner, executor, reviewer, and doctor roles.
+- Approval gates for acceptance criteria, technical plan, production review, spec generation, and execution.
+- Spec, slice, handoff, PR body, evidence, command log, and execution-plan generation.
+- Slice dependency planning, execution waves, parallel-safety checks, and file conflict checks.
+- Controlled slice execution with minimal context, allowed write paths, closure updates, evidence, and one commit per slice.
+- Worktree-per-spec lifecycle, GitHub CLI preflight, SSH alias guidance, PR creation, and post-merge cleanup.
+- Actionable errors, dry-run behavior, redaction, fixture coverage, version checks, migration, export, and visual/dashboard-friendly output.
+
+### Excluded
+
+- Building a large web IDE into the core package.
+- Silent installation of AI provider CLIs, GitHub credentials, SSH keys, or secrets.
+- Storing provider credentials in `.quiver/agents/profiles.json`.
+- Automatically merging PRs.
+- Replacing Git, GitHub CLI, npm, or provider CLIs.
+- Provider API billing, pricing, or account management.
+- Shipping a package release as part of this spec.
+
+## Acceptance Criteria
+
+### Project onboarding
+
+1. Given a new project without Quiver docs, when AI onboarding generation runs, then Quiver creates the base docs and fills what it can infer from stack, scripts, and structure.
+2. Given an existing project with partial or missing docs, when AI onboarding generation runs, then Quiver updates docs such as `docs/CONTEXTO.md`, `docs/WORKFLOW.md`, `docs/ARCHITECTURE.md`, `docs/STATUS.md`, `docs/INDEX.md`, `docs/AI_CONTEXT.md`, and `docs/PROJECT_MAP.md` without deleting useful human content.
+3. Given Quiver cannot infer a project rule, when docs are generated, then the statement is marked as `TODO`, `Assumption`, or `Pending confirmation`.
+4. Given onboarding generation runs with `--dry-run`, then no files are changed and Quiver reports proposed creates, updates, diffs, assumptions, and risks.
+5. Given onboarding generation writes docs, then Quiver stores a snapshot of touched files under `.quiver/runs/<run-id>/snapshots/`.
+6. Given generated docs conflict with existing code, scripts, or docs, then Quiver reports the conflict and does not silently resolve it.
+
+### AI-first planner flow
+
+7. Given a natural-language requirement, when `ai spec create` starts, then Quiver creates a run and stores the original requirement.
+8. Given a planner profile exists, when the planner phase runs, then Quiver invokes or prints the planner prompt with minimum required context.
+9. Given the planner completes acceptance criteria, then Quiver stores a versioned draft for human review.
+10. Given criteria are not approved, when the user requests a revision, then Quiver stores a new version and does not advance phase.
+11. Given criteria are approved, when the human approves a concrete version, then Quiver unlocks technical-plan generation.
+12. Given the technical plan is generated, then Quiver stores a versioned draft for review.
+13. Given the plan is not approved, when the user requests a revision, then Quiver stores a new version and does not create specs or slices.
+14. Given the plan is approved, when spec generation runs, then Quiver generates the versionable planning artifacts.
+
+### State, phases, and locks
+
+15. Given a run exists, when `ai status` runs, then Quiver reports run id, current phase, approved versions, next allowed command, blockers, and artifact locations.
+16. Given a run is interrupted, when `ai resume` runs, then Quiver resumes from the last valid phase without chat memory.
+17. Given a command belongs to a future phase, when it runs early, then Quiver blocks it and prints the valid next command.
+18. Given a run or slice is already locked, when another process tries to mutate it, then Quiver blocks the operation or explains safe lock recovery.
+19. Given a stale lock exists, when lock recovery is requested, then Quiver shows lock metadata before removing it.
+
+### Specs, slices, and handoffs
+
+20. Given an approved plan, when spec generation runs, then Quiver creates `SPEC.md`, `STATUS.md`, `EVIDENCE_REPORT.md`, `EXECUTION_PLAN.md`, `pr.md`, and slice folders.
+21. Given a spec is generated, then `slice-00` is always present and is the only slice allowed to publish the planning package before implementation.
+22. Given each slice is generated, then it has `slice.json`, `EXECUTION_BRIEF.md`, and `CLOSURE_BRIEF.md`.
+23. Given slices have dependencies, when validation runs, then Quiver detects missing references, cycles, invalid formats, and unsafe parallel execution.
+24. Given a slice declares file scope, when it closes, then Quiver validates that modified files are within allowed write paths or reports risk.
+
+### Slice execution
+
+25. Given a ready slice, when execution starts, then Quiver verifies the correct worktree, clean working tree, valid dependency state, and agent profile.
+26. Given an executor prompt is produced, then it contains only slice objective, required excerpts, declared files, constraints, criteria, output contract, and validation commands.
+27. Given a slice completes, then Quiver updates `CLOSURE_BRIEF.md`, evidence, command log, status, and decision history.
+28. Given a slice passed validation, when commit is requested, then Quiver creates one commit associated with that slice and refuses mixed unrelated changes.
+
+### Worktrees, PRs, and GitHub
+
+29. Given a spec starts execution, then Quiver can create or validate a dedicated worktree and branch.
+30. Given a worktree, branch, or PR already exists, then Quiver reports the current state and offers safe recovery instead of duplicating it.
+31. Given PR creation runs, then Quiver validates `gh`, authentication, remote, branch, SSH alias guidance, PR body, and open slices before creating the PR.
+32. Given a PR was merged, when spec close runs, then Quiver guides worktree removal, local pull, and final validation.
+
+### CLI, validation, and release safety
+
+33. Given `npx create-quiver --version` or local `quiver --version` runs, then it prints the installed version without error.
+34. Given inspection commands run, then `status`, `specs list`, `slices list`, `inspect`, and `trace report` provide actionable state.
+35. Given export runs, then Quiver emits specs and slices as JSON and Markdown suitable for dashboards and agents.
+36. Given a command fails, then the error states what failed, why it matters, how to fix it, and the next command.
+37. Given a write-capable command supports `--dry-run`, then it does not modify files and shows planned changes.
+38. Given logs or evidence contain likely secrets, then Quiver redacts common token, key, auth header, npm, GitHub, and environment-value patterns before writing.
+39. Given fixtures run, then they cover new project, existing project, older Quiver project, monorepo, no git, dirty git, no `gh`, path with spaces, docs contradiction, and missing agent profile.
+40. Given release validation runs, then package smoke verifies local version, npm-visible version when network is available, installed version, changelog, tag expectations, and tarball safety.
+
+## Technical Plan
+
+Implement the lifecycle in small, independently reviewable slices:
+
+1. Publish the v25 documentation foundation.
+2. Stabilize command contracts before adding more behavior.
+3. Add run state, phase gates, approvals, and locks.
+4. Add safe onboarding doc generation.
+5. Add agent profiles and adapter contracts.
+6. Add approval gates for criteria and technical plans.
+7. Generate specs, slices, handoffs, and PR body from approved plans.
+8. Generate execution plans and detect parallel safety.
+9. Execute slices with minimal context, scope validation, closure, and evidence.
+10. Add worktree, commit, PR, and close lifecycle.
+11. Harden errors, fixtures, redaction, and cross-platform validation.
+12. Add export, visualization-friendly outputs, and migration support.
+
+## Run State Model
+
+The minimum phase model is:
+
+```text
+created
+→ onboarding-ready
+→ acceptance-draft
+→ acceptance-approved
+→ technical-plan-draft
+→ technical-plan-reviewed
+→ technical-plan-approved
+→ spec-generated
+→ execution-plan-generated
+→ slice-executing
+→ pr-ready
+→ closed
+```
+
+Every mutating command must validate that it is allowed in the current phase.
+
+## Artifact Model
+
+Runtime state:
+
+```text
+.quiver/runs/<run-id>/
+  state.json
+  approvals.json
+  requirement.md
+  drafts/
+  prompts/
+  logs/
+  snapshots/
+  decisions.md
+```
+
+Versionable artifacts:
+
+```text
+specs/<spec-slug>/
+  SPEC.md
+  STATUS.md
+  EVIDENCE_REPORT.md
+  EXECUTION_PLAN.md
+  pr.md
+  slices/<slice-id>/
+    slice.json
+    EXECUTION_BRIEF.md
+    CLOSURE_BRIEF.md
+```
+
+## Slicing Strategy
+
+`slice-00` lands first and only publishes the documentation package. Implementation starts with command/state contracts because every later feature depends on predictable commands, persistent state, and phase safety. Automatic provider execution is deliberately placed after prompt-only adapters and approval gates so Quiver can deliver value without requiring provider credentials.
+
+## Slice Roadmap
+
+| Slice | Title | Status | Dependencies |
+|---|---|---|---|
+| slice-00 | Spec foundation and source-of-truth sync | Completed | none |
+| slice-01 | CLI contract and compatibility | Completed | slice-00 |
+| slice-02 | Run state, phase gates, and locks | Completed | slice-01 |
+| slice-03 | Safe AI onboarding documentation | Completed | slice-02 |
+| slice-04 | Agent profiles and provider adapters | Completed | slice-02 |
+| slice-05 | Approval gates and planner iterations | Completed | slice-02, slice-04 |
+| slice-06 | Spec, slice, handoff, and PR body generation | Completed | slice-05 |
+| slice-07 | Slice execution planning and parallel safety | Completed | slice-06 |
+| slice-08 | Controlled slice execution and evidence | Planned | slice-07 |
+| slice-09 | Git worktree, commit, PR, and close lifecycle | Planned | slice-08 |
+| slice-10 | Validation, actionable errors, redaction, and fixtures | Planned | slice-01, slice-02, slice-08 |
+| slice-11 | Export, dashboard-friendly output, and migration | Planned | slice-07, slice-10 |
+
+## Risks
+
+- Provider CLI behavior can drift across tools and versions.
+- AI-generated documentation can overstate confidence.
+- Concurrent agents can corrupt run state without locks.
+- Worktrees and commits can mix unrelated changes if scope is not enforced.
+- Secret redaction is best-effort and cannot replace careful user handling.
+- A large command surface can hurt first-use clarity unless `flow`, `status`, and error messages stay focused.
+
+## Open Questions
+
+- Whether `ia` should ship as an alias for `ai`, or remain documentation-only for Spanish examples.
+- Whether automatic provider execution should be enabled in the first implementation pass or remain prompt-only until dogfooded.
+- Whether a static HTML export is enough for visualization, or a companion package will be needed later.

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

@@ -0,0 +1,35 @@
+# Status - Quiver v25 AI-First Lifecycle Orchestrator
+
+**Overall status:** Completed and published in `create-quiver@0.12.0`
+**Created:** 2026-05-22
+**Current slice:** slice-11 completed
+
+## Summary
+
+The v25 implementation slices are complete. The CLI contract, run state, safe onboarding docs, provider profile adapter contract, planner approval gates, generated spec/slice artifact contract, execution planning safety, controlled slice execution closure, Git/worktree/PR lifecycle hardening, validation fixture hardening, lifecycle export, dashboard-friendly state, and migration dry-run support are implemented.
+
+## Slice Status
+
+| Slice | Status | Notes |
+|---|---|---|
+| slice-00-spec-foundation | Completed | Planning artifacts created. |
+| slice-01-cli-contract-compatibility | Completed | Top-level version handling, CLI contract tests, and docs added. |
+| slice-02-run-state-phase-locks | Completed | Persistent runs, status/resume, phase helpers, approval metadata, and locks added. |
+| slice-03-safe-ai-onboarding-docs | Completed | Docs-only context prep now supports broader onboarding docs, dry-run diffs, snapshots, human-content preservation, and contradiction reporting. |
+| slice-04-agent-profiles-adapters | Completed | Doctor profile, prompt-only output, redacted provider output, focused tests, and docs added. |
+| slice-05-approval-gates | Completed | Versioned drafts, `ai revise`, explicit `--version` approval, technical-plan review gate, flow guidance, docs, and tests added. |
+| slice-06-spec-slice-generator | Completed | Generated slice JSON and execution briefs now include read paths, allowed write paths, validation hints, dependency data, and parallel safety. |
+| slice-07-slice-execution-planner | Completed | Execution waves now use generated allowed write paths for conflicts and expose scope metadata in JSON. |
+| slice-08-controlled-slice-execution | Completed | Direct slice execution now validates branch/worktree, scope, writes closure/evidence/status artifacts, and redacts logs. |
+| slice-09-git-worktree-pr-lifecycle | Completed | Spec worktree dry-run, commit cleanliness, PR alias/body/open-slice preflight, and close guidance hardened. |
+| slice-10-validation-errors-fixtures | Completed | Actionable errors, doctor environment warnings, fixture matrix, and smoke coverage added. |
+| slice-11-export-dashboard-migration | Completed | AI inspection/export/list/trace surfaces, dashboard-friendly state, migration dry-run, docs, parser hardening, and tests added. |
+
+## Current Blockers
+
+- None for v25.
+- Post-release smoke findings were promoted to `specs/quiver-v26-0121-smoke-hardening/`.
+
+## Next Step
+
+Use v26 for the `0.12.1` smoke hardening hotfix before using the published package for the next real dogfooding project.