create-quiver 0.10.0 → 0.12.1

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; release-ready pending PR merge and npm publication
+
+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 targets `0.12.1`. Publication happens only after the implementation PR is merged, the local validation suite passes, and the candidate package is smoke-tested outside the repo.

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; release-ready pending PR merge and npm publication
+**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. The goal is to prepare a reliable `0.12.1` before using Quiver for the real `Quiver Spec Viewer` project.
+
+## 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 is intentionally pending until PR merge.
+- The real `Quiver Spec Viewer` project should wait until `create-quiver@0.12.1` is published and smoke-tested from npm.
+
+## Next Step
+
+Open the PR, merge after review, publish `create-quiver@0.12.1`, then verify the published package with `npm view create-quiver version` and a clean npm smoke.

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

@@ -0,0 +1,96 @@
+## Title
+Quiver v26 - 0.12.1 Smoke Hardening
+
+## Summary
+
+- Hardens the `0.12.0` AI-first workflow based on a clean npm smoke test.
+- Fixes CLI discoverability, version output, generated docs, AI review guidance, local validation, brief validation, and demo readiness.
+- Prepares `0.12.1` release evidence before the next real dogfooding project.
+
+## Scope
+
+- Product implementation for v26 slices from `slice-01` through `slice-07`.
+- Documentation, tests, smoke coverage, candidate package validation, and source-of-truth sync.
+- No npm publication is included in the PR itself.
+
+## Files
+
+- `README.md`
+- `README_FOR_AI.md`
+- `ROADMAP.md`
+- `CHANGELOG.md`
+- `package.json`
+- `package-lock.json`
+- `src/create-quiver/**`
+- `docs/**`
+- `scripts/ci/**`
+- `specs/quiver-v25-ai-first-lifecycle-orchestrator/STATUS.md`
+- `specs/quiver-v26-0121-smoke-hardening/**`
+- `tests/**`
+
+## How to Test (DETAILED - REQUIRED)
+
+### Required Environment
+
+- Node.js and npm available.
+- Git checkout with the v26 branch.
+- No AI provider credentials are required for dry-run and prompt-only validation.
+
+### Worktree Access
+
+- Run commands from the repository root.
+- Candidate package smoke should run from `/private/tmp` or another clean directory outside the repo.
+
+### Run the Project
+
+```bash
+node --test tests/**/*.test.js
+npm run smoke:create-quiver
+npm run smoke:guided-workflow
+npm run smoke:doctor-fixtures
+git diff --check
+```
+
+### Use Cases
+
+- Print package version with top-level `--version`.
+- Discover commands with `--help`, `help`, and local `quiver --help`.
+- Initialize a clean project and run `analyze`, `doctor`, and `flow`.
+- Validate local slices and slice briefs without remote/base assumptions.
+- Generate and validate the `spec-viewer` demo.
+- Run scoped `plan` and `graph` without OOM in this repo.
+
+### Technical Verification
+
+```bash
+npm --cache /private/tmp/quiver-npm-cache pack --pack-destination /private/tmp/quiver-v26-tarball-smoke
+cd /private/tmp/quiver-v26-tarball-project-0121
+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
+npx create-quiver --help
+npx create-quiver init --name "Tarball Smoke Project" --skip-install
+npx create-quiver analyze
+npx create-quiver doctor
+npx create-quiver flow
+npx create-quiver ai onboard --dry-run
+npx create-quiver ai plan --phase acceptance --input requirements.md --dry-run
+npx create-quiver demo create spec-viewer --dir ./demo
+cd demo
+node scripts/validate-demo.js
+```
+
+## Evidence
+
+- See `specs/quiver-v26-0121-smoke-hardening/EVIDENCE_REPORT.md`.
+
+## Rollback
+
+- Revert the v26 slice commits in reverse order.
+- No npm publication occurs as part of the PR.
+
+## Risks / Notes
+
+- Top-level `--version` must not break AI draft approvals.
+- Help output should be covered by tests to prevent command drift.
+- Demo port fallback must work cross-platform or provide clear cross-platform instructions.
+- Standard `npm pack` failed locally because `~/.npm` contains root-owned cache files; candidate package validation passed with an isolated temp cache.

package/specs/quiver-v26-0121-smoke-hardening/slices/slice-00-docs-foundation/CLOSURE_BRIEF.md

@@ -0,0 +1,35 @@
+# CLOSURE BRIEF - slice-00: Docs foundation and source-of-truth sync
+
+## Summary of Work
+
+- Created the v26 hotfix planning package.
+- Added all slice definitions and handoff briefs.
+- Synchronized source-of-truth docs with the v25/0.12.0 state.
+
+## Validation Against Acceptance Criteria
+
+- [x] V26 spec folder exists.
+- [x] Every slice has required artifacts.
+- [x] Every `slice.json` parses.
+- [x] Source-of-truth docs are synced.
+- [x] No product code changed.
+
+## Relevant Changes
+
+- `README_FOR_AI.md`
+- `ROADMAP.md`
+- `CHANGELOG.md`
+- `specs/quiver-v25-ai-first-lifecycle-orchestrator/STATUS.md`
+- `specs/quiver-v26-0121-smoke-hardening/**`
+
+## Pending
+
+- Product implementation slices remain pending.
+
+## Remaining Risks
+
+- `0.12.1` is not published until implementation and release validation are complete.
+
+## Future Recommendations
+
+- Keep the final release slice responsible for package version, tarball smoke, and post-publish npm verification.

package/specs/quiver-v26-0121-smoke-hardening/slices/slice-00-docs-foundation/EXECUTION_BRIEF.md

@@ -0,0 +1,55 @@
+# EXECUTION BRIEF - slice-00: Docs foundation and source-of-truth sync
+
+## Context
+
+`create-quiver@0.12.0` was published, but a clean npm smoke test found first-use frictions and stale source-of-truth docs. This slice creates the hotfix planning package before implementation starts.
+
+## Objective
+
+Publish the v26 spec, slices, briefs, execution plan, PR body, evidence report, and source-of-truth sync.
+
+## Scope
+
+- `specs/quiver-v26-0121-smoke-hardening/**`
+- `README_FOR_AI.md`
+- `ROADMAP.md`
+- `CHANGELOG.md`
+- `specs/quiver-v25-ai-first-lifecycle-orchestrator/STATUS.md`
+
+## Acceptance Criteria
+
+- The v26 spec folder exists.
+- Every slice has `slice.json`, `EXECUTION_BRIEF.md`, and `CLOSURE_BRIEF.md`.
+- Every `slice.json` parses successfully.
+- Source-of-truth docs no longer describe v25 as planned or pending release.
+- No product code is modified.
+
+## Technical Plan Summary
+
+Create documentation-only artifacts and update release/source-of-truth references. Leave implementation for later slices.
+
+## Suggested Execution Steps
+
+1. Create the v26 spec folder and slice folders.
+2. Write `SPEC.md`, `STATUS.md`, `EXECUTION_PLAN.md`, `EVIDENCE_REPORT.md`, and `pr.md`.
+3. Write each slice's `slice.json`, `EXECUTION_BRIEF.md`, and `CLOSURE_BRIEF.md`.
+4. Sync source-of-truth docs.
+5. Validate JSON and whitespace.
+
+## Restrictions
+
+- Do not change product code.
+- Do not bump package version in this slice unless required by release docs.
+- Do not publish npm.
+
+## Risks
+
+- Source docs can become stale again if release state is not updated in final slice.
+
+## Completion Checklist
+
+- [ ] Spec artifacts created.
+- [ ] Source-of-truth docs synced.
+- [ ] JSON validation passed.
+- [ ] `git diff --check` passed.
+