create-quiver 0.12.0 → 0.12.1

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.

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

@@ -0,0 +1,77 @@
+## Title
+Quiver v25 - AI-First Lifecycle Orchestrator
+
+## Summary
+
+- Implements the Quiver v25 AI-first lifecycle orchestrator across CLI, state, planner approval gates, generated artifacts, controlled execution, worktrees/PRs, validation hardening, export, and migration dry-runs.
+- Adds durable `.quiver/` run state, agent profiles, prompt-only/provider adapter flows, phase-gated planning, reviewed technical-plan approval, generated specs/slices/handoffs/PR body, and one-slice execution closure.
+- Adds dashboard/agent-friendly lifecycle inspection and export commands for specs, slices, runs, agents, dependencies, blockers, progress, and migration state.
+
+## Scope
+
+- Product implementation for all v25 slices from `slice-01` through `slice-11`.
+- Documentation, templates, tests, smoke coverage, CLI help, generated npm scripts, and spec evidence.
+- No package release is included.
+
+## Files
+
+- `README.md`
+- `README_FOR_AI.md`
+- `docs/**`
+- `package.json`
+- `scripts/ci/**`
+- `src/create-quiver/**`
+- `specs/quiver-v25-ai-first-lifecycle-orchestrator/**`
+- `tests/**`
+
+## How to Test (DETAILED - REQUIRED)
+
+### Required Environment
+
+- Node.js and npm available.
+- Git checkout with the v25 branch.
+- No provider CLI credentials are required for dry-run/prompt-only validations.
+
+### Worktree Access
+
+- Run commands from the repository root.
+- This PR does not require a running app server.
+
+### Run the Project
+
+```bash
+node --test tests/**/*.test.js
+npm run smoke:create-quiver
+npm run smoke:guided-workflow
+npm run smoke:doctor-fixtures
+```
+
+### Use Cases
+
+- Create and inspect AI lifecycle runs with `ai run create`, `ai status`, and `ai resume`.
+- Prepare docs-only context with `ai prepare-context --dry-run`.
+- Generate planner drafts, revise them, approve concrete versions, and create specs only after reviewed approval.
+- Execute or print slice prompts with `ai prompt-slice`, `ai execute-slice`, and `ai execute-plan`.
+- Inspect/export lifecycle state with `ai inspect`, `ai export`, `ai specs list`, `ai slices list`, and `ai trace report`.
+
+### Technical Verification
+
+```bash
+git diff --check
+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'));"
+```
+
+## Evidence
+
+- See `specs/quiver-v25-ai-first-lifecycle-orchestrator/EVIDENCE_REPORT.md`.
+
+## Rollback
+
+- Revert the v25 slice commits in reverse order.
+- No migration or PR command writes unless invoked explicitly; dry-runs remain available for recovery.
+
+## Risks / Notes
+
+- Source-of-truth docs should not claim npm publication unless publication has been verified.
+- `CHANGELOG.md`/`ROADMAP.md` still need release-version sync before npm publishing.
+- The lifecycle export JSON is `schema_version: 1`; dashboard consumers should pin expectations.

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

@@ -0,0 +1,34 @@
+# CLOSURE BRIEF - slice-00: Spec foundation and source-of-truth sync
+
+## Summary of Work
+
+- Created the v25 planning package.
+- Added spec, status, evidence report, execution plan, PR body, slice definitions, and handoffs.
+- Synced source-of-truth planning docs with v25 as planned work.
+
+## Validation Against Acceptance Criteria
+
+- [x] Spec folder created.
+- [x] `slice-00` created.
+- [x] Every slice has `slice.json`, `EXECUTION_BRIEF.md`, and `CLOSURE_BRIEF.md`.
+- [x] JSON validation captured.
+- [x] `git diff --check` captured.
+- [x] No product code modified.
+
+## Relevant Changes
+
+- New folder: `specs/quiver-v25-ai-first-lifecycle-orchestrator/`.
+- Source-of-truth planning docs updated.
+
+## Pending
+
+- Execute implementation slices from `slice-01` onward.
+- Implement `slice-01` onward.
+
+## Remaining Risks
+
+- Release status wording for v24/v0.11-v0.12 should be verified before claiming npm publication in source docs.
+
+## Future Recommendations
+
+- Execute slices according to `EXECUTION_PLAN.md`.

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

@@ -0,0 +1,52 @@
+# EXECUTION BRIEF - slice-00: Spec foundation and source-of-truth sync
+
+## Context
+
+This slice publishes the v25 planning package generated from approved acceptance criteria and a production-readiness review.
+
+## Objective
+
+Create the durable spec foundation for Quiver v25 without changing product behavior.
+
+## Scope
+
+- Create `SPEC.md`, `STATUS.md`, `EVIDENCE_REPORT.md`, `EXECUTION_PLAN.md`, and `pr.md`.
+- Create every slice folder with `slice.json`, `EXECUTION_BRIEF.md`, and `CLOSURE_BRIEF.md`.
+- Update `README_FOR_AI.md` and `ROADMAP.md` so source-of-truth docs mention v25 as planned work.
+
+## Acceptance Criteria
+
+- Spec folder exists.
+- Mandatory `slice-00` exists.
+- Every slice has required handoff files.
+- Every `slice.json` parses.
+- No product code is modified.
+
+## Technical Plan Summary
+
+Write documentation only, following the existing `specs/quiver-v24-dx-onboarding-hardening/` structure.
+
+## Suggested Execution Steps
+
+1. Create the spec folder and top-level spec files.
+2. Create all slice folders and handoffs.
+3. Sync source-of-truth planning docs.
+4. Validate JSON and whitespace.
+
+## Restrictions
+
+- Do not edit CLI source.
+- Do not modify tests.
+- Do not publish or open a PR from this slice.
+
+## Risks
+
+- Source-of-truth docs could accidentally imply v25 is implemented. Keep wording as planned only.
+
+## Completion Checklist
+
+- [x] Spec files created.
+- [x] Slice handoffs created.
+- [x] Source-of-truth docs synced.
+- [x] JSON parse validation captured.
+- [x] `git diff --check` captured.

package/specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/slice-00-spec-foundation/slice.json

@@ -0,0 +1,52 @@
+{
+  "slice_id": "slice-00-spec-foundation",
+  "ticket": "QUIVER-25-00",
+  "type": "docs",
+  "title": "Spec foundation and source-of-truth sync",
+  "objective": "Create the documentation foundation for the AI-first lifecycle orchestrator spec before product implementation starts.",
+  "description": "Publish the v25 spec, status, evidence report, execution plan, PR body, slice definitions, handoffs, and source-of-truth planning references.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "ai-first-lifecycle-orchestrator-spec-foundation",
+    "branch_name": "feature/QUIVER-25-00-ai-first-lifecycle-orchestrator-spec-foundation"
+  },
+  "files": [
+    "README_FOR_AI.md",
+    "ROADMAP.md",
+    "specs/quiver-v25-ai-first-lifecycle-orchestrator/**"
+  ],
+  "depends_on": [],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "slice-00 must land before every implementation slice.",
+  "must": [
+    "Create SPEC.md, STATUS.md, EVIDENCE_REPORT.md, EXECUTION_PLAN.md, and pr.md.",
+    "Create slice.json, EXECUTION_BRIEF.md, and CLOSURE_BRIEF.md for every slice.",
+    "Sync README_FOR_AI.md and ROADMAP.md with v25 as planned work only.",
+    "Avoid product code changes."
+  ],
+  "not_included": [
+    "Implementing CLI behavior.",
+    "Changing package behavior.",
+    "Running AI providers.",
+    "Publishing a package.",
+    "Opening a PR."
+  ],
+  "acceptance": [
+    "Spec folder exists under specs/quiver-v25-ai-first-lifecycle-orchestrator.",
+    "Mandatory slice-00 exists.",
+    "Every slice has slice.json, EXECUTION_BRIEF.md, and CLOSURE_BRIEF.md.",
+    "Every slice.json parses successfully.",
+    "README_FOR_AI.md and ROADMAP.md mention v25 as planned, not implemented.",
+    "No product code is modified."
+  ],
+  "tests": [
+    "git diff --check",
+    "find specs/quiver-v25-ai-first-lifecycle-orchestrator -name \"slice.json\" -print -exec node -e \"JSON.parse(require('fs').readFileSync(process.argv[1], 'utf8'))\" {} \\;"
+  ],
+  "estimated_hours": 2,
+  "status": "completed",
+  "blocked_reason": null,
+  "actual_hours": 2,
+  "completed_at": "2026-05-22T00:00:00-0300"
+}

package/specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/slice-01-cli-contract-compatibility/CLOSURE_BRIEF.md

@@ -0,0 +1,36 @@
+# CLOSURE BRIEF - slice-01: CLI contract and compatibility
+
+## Summary of Work
+
+- Added top-level CLI version support for `--version` and `-V`.
+- Preserved `ai approve --version <n>` as the planner draft-version option.
+- Added CLI contract tests for version output and unsupported command guidance.
+- Documented `npx create-quiver --version` in the README command table and generated commands template.
+
+## Validation Against Acceptance Criteria
+
+- [x] Version commands verified.
+- [x] Alias behavior verified through shared binary entrypoint and package bin contract.
+- [x] Unknown command behavior verified.
+- [x] Docs updated.
+- [x] Tests run.
+
+## Relevant Changes
+
+- `src/create-quiver/index.js`
+- `tests/commands/cli-contract.test.js`
+- `README.md`
+- `docs/COMMANDS.md.template`
+- `specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/slice-01-cli-contract-compatibility/slice.json`
+
+## Pending
+
+- None.
+
+## Remaining Risks
+
+- The `quiver` alias itself is covered through package bin metadata and shared entrypoint behavior, not by installing a real local package binary during the test.
+
+## Future Recommendations
+
+- Keep top-level `--version` limited to the commandless case so `ai approve --version <n>` remains unambiguous.

package/specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/slice-01-cli-contract-compatibility/EXECUTION_BRIEF.md

@@ -0,0 +1,52 @@
+# EXECUTION BRIEF - slice-01: CLI contract and compatibility
+
+## Context
+
+Every later AI lifecycle feature depends on a clear command surface. This slice stabilizes command naming before state, approvals, agents, and execution are added.
+
+## Objective
+
+Make `create-quiver`, local `quiver`, generated `quiver:*` scripts, version reporting, and unknown-command errors consistent.
+
+## Scope
+
+- CLI routing and binary alias behavior.
+- `--version` support.
+- Documentation for canonical bootstrap vs local shortcut.
+- Tests for command compatibility and ambiguity.
+
+## Acceptance Criteria
+
+- `npx create-quiver --version` works.
+- Local `quiver --version` works when installed.
+- Unknown commands fail clearly.
+- Docs do not contradict `README_FOR_AI.md`.
+- Generated scripts target supported commands.
+
+## Technical Plan Summary
+
+Audit CLI entrypoints, normalize version handling, harden unknown command routing, and update docs/tests.
+
+## Suggested Execution Steps
+
+1. Read current CLI entrypoint and command router.
+2. Add/adjust version handling.
+3. Verify alias behavior.
+4. Update docs.
+5. Add focused tests.
+
+## Restrictions
+
+- Do not add new AI workflow behavior in this slice.
+- Do not change spec/slice generation behavior.
+
+## Risks
+
+- Changing routing may break legacy `npx create-quiver --name` usage.
+
+## Completion Checklist
+
+- [ ] Tests added or updated.
+- [ ] Docs updated.
+- [ ] Existing init behavior preserved.
+- [ ] Evidence appended.

package/specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/slice-01-cli-contract-compatibility/slice.json

@@ -0,0 +1,56 @@
+{
+  "slice_id": "slice-01-cli-contract-compatibility",
+  "ticket": "QUIVER-25-01",
+  "type": "feature",
+  "title": "CLI contract and compatibility",
+  "objective": "Make command naming, aliases, version reporting, and generated script behavior explicit and consistent.",
+  "description": "Define and implement the contract between canonical `npx create-quiver`, local `quiver`, and generated `quiver:*` scripts before adding more AI lifecycle commands.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "cli-contract-compatibility",
+    "branch_name": "feature/QUIVER-25-01-cli-contract-compatibility"
+  },
+  "files": [
+    "bin/**",
+    "package.json",
+    "src/create-quiver/**",
+    "docs/**",
+    "README.md",
+    "README_FOR_AI.md",
+    "tests/**"
+  ],
+  "depends_on": [
+    "slice-00-spec-foundation"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Establishes shared CLI routing and naming contracts used by all later slices.",
+  "must": [
+    "Preserve `npx create-quiver` as the canonical bootstrap path.",
+    "Keep `quiver` as local alias behavior where installed.",
+    "Make `--version` work for both command surfaces.",
+    "Document whether `ia` is supported or intentionally not supported.",
+    "Ensure unknown commands fail with actionable guidance."
+  ],
+  "not_included": [
+    "Run state persistence.",
+    "Agent execution.",
+    "Spec generation."
+  ],
+  "acceptance": [
+    "`npx create-quiver --version` prints the installed version without error.",
+    "Local `quiver --version` prints the installed version when the binary alias is available.",
+    "Docs explain bootstrap vs local alias without contradiction.",
+    "Unknown commands are not treated as project names.",
+    "Generated scripts target supported command names."
+  ],
+  "tests": [
+    "node --test tests/**/*.test.js",
+    "git diff --check"
+  ],
+  "estimated_hours": 4,
+  "status": "completed",
+  "blocked_reason": null,
+  "actual_hours": 1,
+  "completed_at": "2026-05-22T00:00:00-0300"
+}