create-quiver 0.12.0 → 0.13.0

package/specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/slice-11-export-dashboard-migration/CLOSURE_BRIEF.md

@@ -0,0 +1,36 @@
+# CLOSURE BRIEF - slice-11: Export, dashboard-friendly output, and migration
+
+## Summary of Work
+
+Implemented lifecycle inspection and export surfaces for humans, agents, and optional dashboards. Quiver now exposes specs, slices, runs, agents, dependencies, blockers, progress, and migration findings through read-only AI commands, plus a dry-run migration preview for older projects.
+
+## Validation Against Acceptance Criteria
+
+- [x] Inspection output verified.
+- [x] JSON export verified.
+- [x] Markdown export verified.
+- [x] Migration dry-run verified.
+- [x] No heavy dependencies added.
+
+## Relevant Changes
+
+- Added `ai inspect`, `ai export`, `ai specs list`, `ai slices list`, and `ai trace report`.
+- Added a versioned lifecycle export contract under `src/create-quiver/lib/ai/export-state.js`.
+- Added dashboard-friendly state for agents, specs, slices, dependencies, blockers, migration status, and progress.
+- Added `migrate --dry-run` reporting without writes.
+- Added generated npm scripts and docs for the new inspection/export commands.
+- Fixed JSON comment stripping so glob strings such as `src/**` are not corrupted.
+
+## Pending
+
+- None for this slice.
+
+## Remaining Risks
+
+- The JSON export uses `schema_version: 1`; future dashboard consumers should pin and validate against that version.
+- Quiver core intentionally does not ship a persistent dashboard UI. Visual tools should consume the export externally.
+
+## Future Recommendations
+
+- Dogfood `ai export --format json` in the Quiver Spec Viewer demo before expanding the export contract.
+- Evaluate a static HTML export only after JSON/Markdown export is stable in real projects.

package/specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/slice-11-export-dashboard-migration/EXECUTION_BRIEF.md

@@ -0,0 +1,54 @@
+# EXECUTION BRIEF - slice-11: Export, dashboard-friendly output, and migration
+
+## Context
+
+Quiver should expose its state to humans, agents, and optional visualizers without turning the core package into a full web application.
+
+## Objective
+
+Add inspection, export, dashboard-friendly output, and migration dry-runs.
+
+## Scope
+
+- `status`, `specs list`, `slices list`, `inspect`, and `trace report` style outputs.
+- JSON and Markdown export.
+- Dashboard-friendly state shape.
+- Migration dry-run for older Quiver projects.
+
+## Acceptance Criteria
+
+- Inspection output is actionable.
+- JSON export is machine-readable.
+- Markdown export is readable.
+- Migration dry-run writes nothing.
+- Older project fixtures get clear guidance.
+- No heavy UI dependencies are added.
+
+## Technical Plan Summary
+
+Build on execution planning and validation so export and migration reflect real Quiver state rather than ad-hoc file reads.
+
+## Suggested Execution Steps
+
+1. Define export JSON contract.
+2. Add Markdown export.
+3. Add inspection/list/report commands.
+4. Add migration dry-run checks.
+5. Test against older-project fixtures.
+
+## Restrictions
+
+- Do not add a persistent web server to core.
+- Do not perform destructive migration without preview.
+
+## Risks
+
+- Export contracts can become public APIs. Version the shape or document stability.
+
+## Completion Checklist
+
+- [ ] JSON export tested.
+- [ ] Markdown export tested.
+- [ ] Inspection commands tested.
+- [ ] Migration dry-run tested.
+- [ ] Evidence appended.

package/specs/quiver-v25-ai-first-lifecycle-orchestrator/slices/slice-11-export-dashboard-migration/slice.json

@@ -0,0 +1,53 @@
+{
+  "slice_id": "slice-11-export-dashboard-migration",
+  "ticket": "QUIVER-25-11",
+  "type": "feature",
+  "title": "Export, dashboard-friendly output, and migration",
+  "objective": "Expose lifecycle state, specs, slices, and migration findings in formats useful for humans, agents, and optional dashboards.",
+  "description": "Add export commands, inspect/list/report surfaces, visualization-friendly JSON/Markdown, and migration dry-runs for older Quiver projects.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "export-dashboard-migration",
+    "branch_name": "feature/QUIVER-25-11-export-dashboard-migration"
+  },
+  "files": [
+    "src/create-quiver/**",
+    "docs/**",
+    "tests/**"
+  ],
+  "depends_on": [
+    "slice-07-slice-execution-planner",
+    "slice-10-validation-errors-fixtures"
+  ],
+  "parallel_safe": "yes",
+  "parallel_safe_reason": "Late-stage output/migration work can run beside hardening if shared CLI files are coordinated.",
+  "must": [
+    "Add or improve status, specs list, slices list, inspect, and trace report surfaces.",
+    "Export specs/slices/runs as JSON and Markdown.",
+    "Provide dashboard-friendly state for agents, specs, slices, dependencies, blockers, and progress.",
+    "Support migration dry-run for older Quiver projects.",
+    "Keep core package lightweight and avoid a full web IDE."
+  ],
+  "not_included": [
+    "Building a persistent web server UI into core.",
+    "Automatic package publishing.",
+    "Automatic PR merge."
+  ],
+  "acceptance": [
+    "Inspection commands show actionable lifecycle state.",
+    "Export JSON is machine-readable and stable enough for demos/dashboards.",
+    "Markdown export is readable in PRs or docs.",
+    "Migration dry-run reports planned changes without writing.",
+    "Older Quiver project fixtures receive clear migration guidance.",
+    "No heavy UI dependencies are added to core."
+  ],
+  "tests": [
+    "node --test tests/**/*.test.js",
+    "git diff --check"
+  ],
+  "estimated_hours": 7,
+  "status": "completed",
+  "blocked_reason": null,
+  "completed_at": "2026-05-22T17:31:01-03:00"
+}

package/specs/quiver-v26-0121-smoke-hardening/EVIDENCE_REPORT.md

@@ -0,0 +1,208 @@
+# Evidence Report - Quiver v26 0.12.1 Smoke Hardening
+
+## Summary
+
+This report starts with documentation-only evidence for `slice-00`. Product implementation evidence must be appended by each later slice.
+
+## slice-00 - Docs foundation
+
+### Completed
+
+- Created v26 hotfix 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`.
+- Synchronized source-of-truth docs with v25 as implemented/published and v26 as the next hotfix.
+
+### Validation
+
+- `find specs/quiver-v26-0121-smoke-hardening -name "slice.json" -print -exec node -e "JSON.parse(require('fs').readFileSync(process.argv[1], 'utf8'))" {} \;` passed for 8 slice files.
+- `git diff --check` passed.
+- `find specs/quiver-v26-0121-smoke-hardening/slices -maxdepth 2 -type f | sort | wc -l` returned 24 slice files.
+- `rg -n "v25.*planned|v25.*pending|pending package release|Do not treat v25" README_FOR_AI.md ROADMAP.md CHANGELOG.md specs/quiver-v25-ai-first-lifecycle-orchestrator/STATUS.md` returned no stale source-of-truth matches.
+- `npm run quiver:plan -- --spec quiver-v26-0121-smoke-hardening --include-completed` failed with Node out-of-memory. This repeats the planning-output scaling issue observed in v25.
+- `npm run quiver:graph -- --spec quiver-v26-0121-smoke-hardening --include-completed` failed with Node out-of-memory. This should be covered by implementation hardening before `0.12.1` release.
+
+### Risks
+
+- Implementation has not started.
+- Release publication must wait until `slice-06` evidence passes.
+- `plan` and `graph` can still OOM in this repo even when scoped to a small spec; implementation slices must address this before release readiness.
+
+## Later Slices
+
+Each implementation slice must append:
+
+- commands executed;
+- tests or smokes run;
+- files changed;
+- validation result;
+- risks remaining;
+- evidence location.
+
+## slice-01 - CLI help and version contract
+
+### Completed
+
+- Added grouped command descriptions to the CLI help output.
+- Added `npx create-quiver help` as a readable alias for full help.
+- Preserved top-level `--version` / `-V` behavior and `ai approve --version <n>` semantics.
+- Added CLI contract tests for grouped help, important public command coverage, and local `quiver` alias metadata.
+- Updated README and generated command reference template with `--help`, `help`, and local `quiver --help`.
+
+### Validation
+
+- `node --test tests/commands/cli-contract.test.js` passed: 6 tests.
+- `node --test tests/commands/cli-contract.test.js tests/commands/ai-plan.test.js tests/lib/approvals.test.js` passed: 25 tests.
+- `node bin/create-quiver.js help` printed grouped command descriptions.
+- `node bin/create-quiver.js --version` printed `0.12.0`.
+- `git diff --check` passed.
+
+### Risks
+
+- Help output is still maintained in code, but the new contract test checks important public commands are present with descriptions.
+
+## slice-02 - Init doc links and flow guidance
+
+### Completed
+
+- Replaced default `docs/COMMANDS.md` example links to optional `docs/examples/*.md` files with inline commands.
+- Removed the default `docs/STATUS.md` link to a non-existent placeholder slice.
+- Added doctor coverage that default init does not produce missing local docs link warnings.
+- Added flow coverage that `init -> analyze -> flow` uses the generated `docs/PROJECT_MAP.md` and advances to agent profile guidance.
+
+### Validation
+
+- `node --test tests/commands/doctor.test.js tests/commands/flow.test.js tests/lib/init-layout.test.js` passed: 28 tests.
+- `git diff --check` passed.
+
+### Risks
+
+- Full-profile optional examples remain available; default docs now use inline command examples instead of linking to files not generated by default.
+
+## slice-03 - AI approval and review consistency
+
+### Completed
+
+- Updated spec-generation review blocker messaging to point first to `ai review-plan --dry-run`, then to persisted `ai review-plan`.
+- Removed confusing `ai approve --phase technical-plan --version <n>` guidance from the flow state where the technical plan is approved but still lacks a valid review.
+- Added regression coverage for the approved-but-unreviewed technical plan flow state.
+- Updated review-plan tests to assert the actionable next-command sequence.
+
+### Validation
+
+- `node --test 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` passed: 27 tests.
+- `git diff --check` passed.
+
+### Risks
+
+- The review gate remains strict; users must persist a review before spec generation can proceed.
+
+## slice-04 - Local validation and brief contracts
+
+### Completed
+
+- Allowed `check-slice --local` to run structural validation in folders without a Git repository.
+- Normalized declared `depends_on` references before comparing them to the slice graph, so bare same-spec dependencies like `slice-00-docs-foundation` resolve correctly.
+- Extended `check-handoff` to validate legacy `HANDOFF.md` files plus current per-slice `EXECUTION_BRIEF.md` and `CLOSURE_BRIEF.md` files.
+- Updated CLI help, generated command docs, README, and generated workflow docs to show brief validation.
+- Added regression fixtures for no-Git local projects, completed `slice-00` dependencies, legacy handoffs, execution briefs, and closure briefs.
+
+### Validation
+
+- `node --test tests/lib/check-slice.test.js tests/lib/handoff.test.js tests/lib/slice-graph.test.js` passed: 25 tests.
+- `node bin/create-quiver.js check-slice --local specs/quiver-v26-0121-smoke-hardening/slices/slice-01-cli-help-version-contract/slice.json` passed.
+- `node bin/create-quiver.js check-handoff specs/quiver-v26-0121-smoke-hardening/slices/slice-04-local-validation-brief-contracts/EXECUTION_BRIEF.md` passed.
+- `node bin/create-quiver.js check-handoff specs/quiver-v26-0121-smoke-hardening/slices/slice-04-local-validation-brief-contracts/CLOSURE_BRIEF.md` passed.
+- `node --test tests/lib/check-slice.test.js tests/lib/handoff.test.js tests/lib/slice-graph.test.js tests/commands/cli-contract.test.js tests/lib/init-docs.test.js tests/lib/init-layout.test.js` passed: 50 tests.
+- `npm run smoke:guided-workflow` passed: 130 tests plus package smoke.
+
+### Risks
+
+- Normal remote/base validation remains unchanged; final release smoke still needs to cover `check-slice` in normal mode and `check-pr`.
+
+## slice-05 - Demo scaffold readiness
+
+### Completed
+
+- Generated demo scaffold now includes minimal Quiver initialization metadata and required docs so `doctor` can inspect it without a misleading not-initialized error.
+- Demo package scripts include the broader Quiver command set while keeping the app itself dependency-free.
+- Demo server now tries subsequent ports when the starting port is occupied and documents POSIX/PowerShell port overrides.
+- Demo execution briefs now match the current per-slice brief validation contract.
+- Updated stale smoke fixtures that expected removed `COMMANDS.md` links to optional `docs/examples/*` files.
+
+### Validation
+
+- `node --test tests/commands/demo.test.js tests/commands/doctor.test.js` passed: 14 tests.
+- `npm run smoke:create-quiver` passed.
+- `node scripts/ci/smoke-cross-platform.js` passed.
+- `bash scripts/ci/smoke-init-docs.sh` passed.
+
+### Risks
+
+- Port fallback was validated through generated server contract assertions because this sandbox blocks opening local sockets.
+
+## slice-06 - Plan and graph scope performance
+
+### Completed
+
+- Added `readSlicesForSpec()` to load only the requested spec and explicit dependency refs for scoped plan/graph runs.
+- Updated `plan` and `graph` commands to use scoped loading before graph construction when `--spec` is provided.
+- Preserved unscoped behavior and cycle checks.
+- Added regression tests proving scoped plan/graph do not parse unrelated invalid historical slice artifacts.
+- Added readiness coverage for explicit external dependencies during scoped planning.
+- Updated root `quiver:plan` and `quiver:graph` scripts to use the local CLI entrypoint during repository validation.
+
+### Validation
+
+- `node --test tests/commands/plan.test.js tests/commands/graph.test.js tests/lib/slice-graph.test.js` passed: 28 tests.
+- `npm run quiver:plan -- --spec quiver-v26-0121-smoke-hardening --include-completed` completed without OOM.
+- `npm run quiver:graph -- --spec quiver-v26-0121-smoke-hardening --include-completed` completed without OOM.
+
+### Risks
+
+- Scoped output still displays only the requested spec; external dependencies are retained internally for readiness checks.
+
+## slice-07 - Smoke and release readiness
+
+### Completed
+
+- Bumped package metadata to `0.12.1` in `package.json` and `package-lock.json`.
+- Added `0.12.1` release notes to `CHANGELOG.md`.
+- Updated source-of-truth project docs to mark v26 as implemented and release-ready, while keeping npm publication as a post-merge step.
+- Ran full unit, command, smoke, cross-platform, init-docs, package, and candidate tarball validation.
+- Validated the candidate tarball from `/private/tmp` in a clean project installed from `create-quiver-0.12.1.tgz`.
+
+### Validation
+
+- `node --test tests/**/*.test.js` passed: 317 tests.
+- `npm run smoke:create-quiver` passed.
+- `npm run smoke:guided-workflow` passed: 130 tests plus package smoke.
+- `npm run smoke:doctor-fixtures` passed: 10 doctor fixture states.
+- `node scripts/ci/smoke-cross-platform.js` passed.
+- `bash scripts/ci/smoke-init-docs.sh` passed.
+- `npm run quiver:plan -- --spec quiver-v26-0121-smoke-hardening --include-completed` passed and reported all 8 slices as completed.
+- `npm run quiver:graph -- --spec quiver-v26-0121-smoke-hardening --include-completed` passed and rendered the scoped graph without OOM.
+- `node bin/create-quiver.js check-slice --local specs/quiver-v26-0121-smoke-hardening/slices/slice-07-smoke-release-readiness/slice.json` passed structural validation.
+- `npm pack --pack-destination /private/tmp/quiver-v26-tarball-smoke` initially failed because the local `~/.npm` cache has root-owned files.
+- `npm --cache /private/tmp/quiver-npm-cache pack --pack-destination /private/tmp/quiver-v26-tarball-smoke` passed and produced `create-quiver-0.12.1.tgz`.
+- Clean tarball smoke from `/private/tmp/quiver-v26-tarball-project-0121` passed:
+  - `npm --cache /private/tmp/quiver-npm-cache install -D /private/tmp/quiver-v26-tarball-smoke/create-quiver-0.12.1.tgz`
+  - `npx create-quiver --version` printed `0.12.1`.
+  - `npx create-quiver --help` printed the grouped command reference.
+  - `npx create-quiver init --name "Tarball Smoke Project" --skip-install` completed.
+  - `npx create-quiver analyze` completed.
+  - `npx create-quiver doctor` passed.
+  - `npx create-quiver flow` completed and suggested the next safe command.
+  - `npx create-quiver ai onboard --dry-run` completed without provider execution.
+  - `npx create-quiver ai plan --phase acceptance --input requirements.md --dry-run` completed without provider execution.
+  - `npx create-quiver demo create spec-viewer --dir ./demo` completed.
+  - `node scripts/validate-demo.js` passed inside the generated demo.
+  - `npx create-quiver check-handoff specs/quiver-spec-viewer/slices/slice-00-docs-foundation/EXECUTION_BRIEF.md` passed inside the generated demo.
+  - `npx create-quiver check-handoff specs/quiver-spec-viewer/slices/slice-01-static-spec-viewer/CLOSURE_BRIEF.md` passed inside the generated demo.
+  - `npx create-quiver doctor` passed inside the generated demo.
+- `git diff --check` passed.
+
+### Risks
+
+- npm publication was intentionally not performed in this slice; it must happen only after PR merge.
+- The standard `npm pack` command can fail on this workstation until `~/.npm` cache ownership is repaired. The package itself was validated by rerunning pack with an isolated temp cache.

package/specs/quiver-v26-0121-smoke-hardening/EXECUTION_PLAN.md

@@ -0,0 +1,57 @@
+# Execution Plan - Quiver v26
+
+## Wave 0 - Required Foundation
+
+1. `slice-00-docs-foundation`
+   - Must land first.
+   - Publishes the spec, slices, briefs, PR body, execution plan, and source-of-truth sync.
+
+## Wave 1 - CLI Discovery Contract
+
+Run sequentially:
+
+1. `slice-01-cli-help-version-contract`
+
+This slice owns the command surface that later guidance and smoke tests depend on.
+
+## Wave 2 - Guidance and AI State
+
+Can run in parallel after Wave 1 only if write scopes do not overlap:
+
+1. `slice-02-init-doc-links-and-flow-guidance`
+2. `slice-03-ai-approval-review-consistency`
+
+If both need to modify shared help/flow code, run them sequentially in the listed order.
+
+## Wave 3 - Validation and Demo
+
+Run after Wave 2:
+
+1. `slice-04-local-validation-brief-contracts`
+2. `slice-05-demo-scaffold-readiness`
+
+These can run in parallel only if `slice-05` does not need changes in shared validation helpers touched by `slice-04`.
+
+## Wave 4 - Plan/Graph Scope Performance
+
+Run after Wave 3:
+
+1. `slice-06-plan-graph-scope-performance`
+
+This slice must prove that scoped `plan` and `graph` commands do not scan or retain unrelated historical specs in a way that can OOM.
+
+## Wave 5 - Release Readiness
+
+Run last:
+
+1. `slice-07-smoke-release-readiness`
+
+This slice validates the full package, prepares version metadata, records evidence, and confirms the candidate flow before publication.
+
+## Parallel Safety Notes
+
+- `slice-00` must be committed before implementation slices.
+- Keep one commit per slice.
+- Do not run slices in parallel if `allowed_write_paths` overlap.
+- Prefer focused tests during each slice and full smokes in `slice-06`.
+- Do not publish npm from any slice except the post-merge release step.

package/specs/quiver-v26-0121-smoke-hardening/SPEC.md

@@ -0,0 +1,137 @@
+# Quiver v26 - 0.12.1 Smoke Hardening
+
+**Date:** 2026-05-23
+**Status:** Implemented; shipped in `create-quiver@0.12.1`
+
+Slice numbering resets here. This spec intentionally starts at `slice-00`.
+
+## Problem
+
+`create-quiver@0.12.0` was published and passed the broad product implementation path, but a clean smoke test from npm exposed several first-use frictions before Quiver can be used confidently for the real `Quiver Spec Viewer` project.
+
+The issues are not large feature gaps. They are product-quality gaps in command discoverability, version output, generated docs, AI phase guidance, local validation, demo readiness, and release smoke confidence.
+
+## Objective
+
+Ship a focused `0.12.1` hotfix that makes the published AI-first workflow more reliable for new users and agents:
+
+- top-level version and help commands work clearly;
+- generated docs do not contain broken internal links;
+- `flow`, `review-plan`, `approve`, and `spec create` guide the user through valid AI lifecycle states;
+- local slice and brief validation works for new/local projects;
+- the optional `spec-viewer` demo can be generated, validated, diagnosed, and run without confusing errors;
+- source-of-truth docs match the actual v25 and npm `0.12.0` state;
+- release readiness is validated through normal tests, smoke tests, and a clean install smoke before publishing `0.12.1`.
+
+## Context
+
+This spec comes from a real smoke test of `create-quiver@0.12.0` in `/private/tmp`. The test validated the package from npm, not the local repo. It found:
+
+- `npx create-quiver@0.12.0 --version` fails because top-level `--version` is interpreted as a draft version option.
+- `doctor` reports broken links generated by default init docs.
+- `flow` and AI approval guidance can refer to review state in a way that is not directly actionable.
+- `spec create --dry-run` correctly blocks without reviewed plan state, but the recovery path is not clear enough.
+- `check-slice --local` still fails before structural validation if no Git repo exists.
+- `check-slice --local` does not resolve a dependency on a completed `slice-00-docs-foundation` in the generated demo.
+- `check-handoff` only accepts the older global `HANDOFF.md` contract, while current slices use `EXECUTION_BRIEF.md` and `CLOSURE_BRIEF.md`.
+- `demo create spec-viewer` generates a runnable demo, but `doctor` inside it reports that it is not initialized by Quiver.
+- The demo server fails with `EADDRINUSE` when port `4173` is occupied.
+- `plan` and `graph` can still fail with Node out-of-memory even when scoped to one small spec.
+- `README_FOR_AI.md`, `ROADMAP.md`, `CHANGELOG.md`, and v25 status docs are stale relative to the merged and published `0.12.0` state.
+
+## Core Decisions
+
+- This is a hotfix, not a lifecycle redesign.
+- Keep `npx create-quiver` as the canonical bootstrap command.
+- Keep `quiver` as a local installed shortcut, not a global install recommendation.
+- Keep `--version <n>` for AI draft approvals inside AI commands.
+- Treat top-level `--version` as package version only when no subcommand owns the option.
+- Keep the old global `HANDOFF.md` validator compatible, but support slice-local execution and closure briefs.
+- Prefer actionable errors over silent fallback when workflow state is incomplete.
+- No provider credentials or AI API calls are required to validate this hotfix.
+
+## Scope
+
+### Included
+
+- Top-level CLI version handling and complete grouped help output.
+- Automated coverage to prevent major public commands from missing help descriptions.
+- Default init template link hygiene.
+- `flow`, `ai review-plan`, `ai approve`, and `spec create` guidance consistency.
+- Local slice validation without remote/base requirements and better Git precondition handling.
+- Dependency resolution for completed slices such as `slice-00-docs-foundation`.
+- Brief validation for `EXECUTION_BRIEF.md` and `CLOSURE_BRIEF.md`.
+- Demo scaffold readiness, `doctor` behavior, and port handling/documentation.
+- Scoped `plan` and `graph` performance/read behavior for large repos with many historical specs.
+- Version/docs sync for the `0.12.0` release state and `0.12.1` hotfix target.
+- Final smoke, tarball smoke, and release readiness evidence.
+
+### Excluded
+
+- Creating the real `Quiver Spec Viewer` project in `/Prueba`.
+- Adding a web dashboard to Quiver core.
+- Changing the spec/slice directory model.
+- Installing provider CLIs, GitHub CLI, SSH keys, or credentials.
+- Automatically publishing npm before PR merge and validation.
+- Replacing existing `HANDOFF.md` support.
+
+## Acceptance Criteria
+
+1. Given a user in any folder, when they run `npx create-quiver@0.12.1 --version`, then the CLI prints the installed package version and exits with code `0`.
+2. Given the AI approval flow, when `npx create-quiver ai approve --phase technical-plan --version <n>` runs, then `--version <n>` still means draft version and remains compatible with existing approval behavior.
+3. Given a user runs `npx create-quiver --help`, `npx create-quiver help`, or local `quiver --help`, then the CLI lists public commands with short descriptions, grouped by purpose, with key options and recommended examples.
+4. Given public commands are added or renamed, when tests run, then coverage fails if important public commands are missing from the help output or have no description.
+5. Given a project is initialized with default init, when `npx create-quiver doctor` runs, then Quiver does not warn about broken links generated by its own default templates.
+6. Given a project is initialized and `analyze`, `doctor`, and `flow` are run in order, then `flow` shows the current valid next step and does not rely on stale missing-map state.
+7. Given a technical plan is approved but not reviewed, when `spec create --dry-run` runs, then Quiver blocks with a message that explains the missing review state and prints the exact next command.
+8. Given `flow` recommends plan review, when the user follows the suggested commands, then the commands exist and can be completed in the documented order.
+9. Given a new local project without a Git repo, when `check-slice --local <slice.json>` runs, then structural validation can run without failing on `git rev-parse`; Git-dependent checks are skipped or downgraded to actionable warnings.
+10. Given `slice-01` depends on a completed `slice-00-docs-foundation`, when `check-slice --local` runs, then the dependency resolves correctly.
+11. Given a slice has `EXECUTION_BRIEF.md` and `CLOSURE_BRIEF.md`, when brief validation runs, then Quiver validates the current per-slice contract or prints the correct command for validating it.
+12. Given `demo create spec-viewer` generates a demo, when the user runs `doctor` inside the demo, then Quiver either recognizes the demo's Quiver metadata or explains clearly that it is a partial demo scaffold and what command to run next.
+13. Given the default demo port is occupied, when the demo starts, then the user gets a clear cross-platform recovery path or the server selects a safe fallback port and prints it.
+14. Given a repo with many historical specs, when `plan` or `graph` runs with `--spec <slug>`, then Quiver only loads the necessary spec/slice data and does not fail with Node out-of-memory.
+15. Given the hotfix is implemented, when local validation runs, then `node --test tests/**/*.test.js`, `npm run smoke:create-quiver`, `npm run smoke:guided-workflow`, `npm run smoke:doctor-fixtures`, and `git diff --check` pass.
+16. Given the hotfix is ready to release, when tarball smoke runs from `/private/tmp`, then the candidate package supports `init -> analyze -> doctor -> flow -> ai dry-runs -> demo -> validate` without critical first-use friction.
+17. Given `README_FOR_AI.md` is the source of truth, when `slice-00` completes, then `README_FOR_AI.md`, `ROADMAP.md`, `CHANGELOG.md`, and v25 status docs no longer contradict that v25 was merged and `0.12.0` was published.
+
+## Technical Plan
+
+1. Publish the v26 documentation foundation and source-of-truth sync.
+2. Fix top-level CLI version/help behavior while preserving AI draft-version semantics.
+3. Clean generated init docs and align guided flow output with valid next commands.
+4. Tighten AI approval/review/spec-create state messaging and tests.
+5. Harden local validation and current brief contracts.
+6. Make the optional demo scaffold self-consistent and easier to run cross-platform.
+7. Fix scoped `plan` and `graph` behavior so large historical repos do not OOM.
+8. Run full validation, tarball smoke, docs/version prep, and release evidence for `0.12.1`.
+
+## Production Review Additions
+
+The production-readiness review added these constraints:
+
+- Do not overload `--version`; route it by command context.
+- Do not introduce a `plan-review` approval phase unless the CLI fully supports it.
+- In `--local` validation, avoid fatal Git or remote assumptions.
+- Resolve dependencies against all known slices, including completed documentary slices.
+- Keep help output generated from a stable registry or covered by tests to prevent drift.
+- Validate the local `quiver` alias through an installed package path where possible.
+- Keep `HANDOFF.md` compatible while supporting slice briefs.
+- Prefer automatic demo port fallback; if not feasible, document macOS/Linux/Git Bash and Windows PowerShell commands.
+
+## Slice Roadmap
+
+| Slice | Title | Status | Dependencies |
+|---|---|---|---|
+| slice-00 | Docs foundation and source-of-truth sync | Completed | none |
+| slice-01 | CLI help and version contract | Completed | slice-00 |
+| slice-02 | Init doc links and flow guidance | Completed | slice-01 |
+| slice-03 | AI approval and review consistency | Completed | slice-01 |
+| slice-04 | Local validation and brief contracts | Completed | slice-02, slice-03 |
+| slice-05 | Demo scaffold readiness | Completed | slice-02, slice-04 |
+| slice-06 | Plan and graph scope performance | Completed | slice-04 |
+| slice-07 | Smoke and release readiness | Completed | slice-01, slice-02, slice-03, slice-04, slice-05, slice-06 |
+
+## Release Plan
+
+This spec targeted `0.12.1`, which has been published. Follow-up reliability findings from Pixel Quiver dogfooding are tracked in `specs/quiver-v27-reliability-ai-workflow-hardening/`.

package/specs/quiver-v26-0121-smoke-hardening/STATUS.md

@@ -0,0 +1,32 @@
+# Status - Quiver v26 0.12.1 Smoke Hardening
+
+**Overall status:** Slices 00-07 complete; shipped in `create-quiver@0.12.1`
+**Created:** 2026-05-23
+**Current slice:** slice-07 completed
+
+## Summary
+
+This hotfix spec tracks the first-use issues found while smoke testing `create-quiver@0.12.0` from npm. It prepared the `0.12.1` package that was later published.
+
+## Slice Status
+
+| Slice | Status | Notes |
+|---|---|---|
+| slice-00-docs-foundation | Completed | Planning artifacts and source-of-truth sync created. |
+| slice-01-cli-help-version-contract | Completed | Added grouped command help, `help` command alias, help drift tests, and alias/version coverage. |
+| slice-02-init-doc-links-and-flow-guidance | Completed | Removed default generated doc links to absent files and added flow-after-analyze coverage. |
+| slice-03-ai-approval-review-consistency | Completed | Clarified review/spec-create blockers and removed confusing re-approval guidance before review. |
+| slice-04-local-validation-brief-contracts | Completed | Local validation no longer fatally requires Git, bare slice dependencies normalize, and brief validation supports execution/closure briefs. |
+| slice-05-demo-scaffold-readiness | Completed | Demo scaffold now includes Quiver metadata, doctor/plan/graph/next coverage, brief validation, and server port fallback. |
+| slice-06-plan-graph-scope-performance | Completed | Scoped plan/graph now read only the target spec plus explicit dependency refs and root scripts validate local code. |
+| slice-07-smoke-release-readiness | Completed | Full tests, required smokes, tarball candidate smoke, version bump, changelog, and release evidence completed. |
+
+## Current Blockers
+
+- No local implementation blockers remain.
+- npm publication for `0.12.1` is complete.
+- Follow-up dogfooding findings are tracked in `specs/quiver-v27-reliability-ai-workflow-hardening/`.
+
+## Next Step
+
+Use v27 for the next reliability hardening cycle.