create-quiver 0.12.0 → 0.13.0

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.
+

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

@@ -0,0 +1,73 @@
+{
+  "slice_id": "slice-00-docs-foundation",
+  "ticket": "QUIVER-26-00",
+  "type": "docs",
+  "title": "Docs foundation and source-of-truth sync",
+  "objective": "Create the v26 hotfix planning package and align source-of-truth docs with the actual v25 and 0.12.0 release state.",
+  "description": "Publish the v26 spec, status, evidence report, execution plan, PR body, slice definitions, execution briefs, closure briefs, and source-of-truth documentation sync before product implementation starts.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v26-0121-smoke-hardening-docs-foundation",
+    "branch_name": "feature/QUIVER-26-00-v26-0121-smoke-hardening-docs-foundation"
+  },
+  "files": [
+    "README_FOR_AI.md",
+    "ROADMAP.md",
+    "CHANGELOG.md",
+    "specs/quiver-v25-ai-first-lifecycle-orchestrator/STATUS.md",
+    "specs/quiver-v26-0121-smoke-hardening/**"
+  ],
+  "expected_read_paths": [
+    "README_FOR_AI.md",
+    "ROADMAP.md",
+    "CHANGELOG.md",
+    "specs/quiver-v25-ai-first-lifecycle-orchestrator/STATUS.md",
+    "specs/quiver-v25-ai-first-lifecycle-orchestrator/**"
+  ],
+  "allowed_write_paths": [
+    "README_FOR_AI.md",
+    "ROADMAP.md",
+    "CHANGELOG.md",
+    "specs/quiver-v25-ai-first-lifecycle-orchestrator/STATUS.md",
+    "specs/quiver-v26-0121-smoke-hardening/**"
+  ],
+  "depends_on": [],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "slice-00 must land before every implementation slice.",
+  "must": [
+    "Create the v26 planning artifacts.",
+    "Create slice.json, EXECUTION_BRIEF.md, and CLOSURE_BRIEF.md for every slice.",
+    "Sync source-of-truth docs with v25 implemented/published and v26 planned.",
+    "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-v26-0121-smoke-hardening.",
+    "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, ROADMAP.md, CHANGELOG.md, and v25 status do not contradict the published 0.12.0 state.",
+    "No product code is modified."
+  ],
+  "tests": [
+    "git diff --check",
+    "find specs/quiver-v26-0121-smoke-hardening -name \"slice.json\" -print -exec node -e \"JSON.parse(require('fs').readFileSync(process.argv[1], 'utf8'))\" {} \\;"
+  ],
+  "validation_hints": [
+    "Use git diff to confirm only docs/spec files changed.",
+    "Check source-of-truth docs for stale v25 planned/pending wording."
+  ],
+  "estimated_hours": 2,
+  "status": "completed",
+  "blocked_reason": null,
+  "actual_hours": 2,
+  "completed_at": "2026-05-23T00:00:00-0300"
+}
+

package/specs/quiver-v26-0121-smoke-hardening/slices/slice-01-cli-help-version-contract/CLOSURE_BRIEF.md

@@ -0,0 +1,38 @@
+# CLOSURE BRIEF - slice-01: CLI help and version contract
+
+## Summary of Work
+
+- Added grouped command descriptions to `--help`.
+- Added `npx create-quiver help` as an alias for complete help.
+- Preserved top-level version output and AI draft-version approval behavior.
+- Added tests for help coverage, local alias metadata, and command discovery.
+- Updated README and generated command reference docs.
+
+## Validation Against Acceptance Criteria
+
+- [x] Version commands verified.
+- [x] AI draft version behavior verified.
+- [x] Help output verified.
+- [x] Help drift coverage added.
+
+## Relevant Changes
+
+- `src/create-quiver/index.js`
+- `tests/commands/cli-contract.test.js`
+- `README.md`
+- `docs/COMMANDS.md.template`
+- `specs/quiver-v26-0121-smoke-hardening/EVIDENCE_REPORT.md`
+- `specs/quiver-v26-0121-smoke-hardening/STATUS.md`
+- `specs/quiver-v26-0121-smoke-hardening/slices/slice-01-cli-help-version-contract/slice.json`
+
+## Pending
+
+- None.
+
+## Remaining Risks
+
+- Help output is still maintained in code, but coverage now checks important public commands.
+
+## Future Recommendations
+
+- Consider moving command help metadata into a shared command registry in a future non-hotfix slice.

package/specs/quiver-v26-0121-smoke-hardening/slices/slice-01-cli-help-version-contract/EXECUTION_BRIEF.md

@@ -0,0 +1,51 @@
+# EXECUTION BRIEF - slice-01: CLI help and version contract
+
+## Context
+
+The npm smoke test showed that `npx create-quiver@0.12.0 --version` fails because the top-level parser treats `--version` as an option requiring a draft version. Help output also needs to become a stronger onboarding surface.
+
+## Objective
+
+Fix version/help behavior and add coverage that keeps command descriptions from drifting.
+
+## Scope
+
+- CLI entrypoint and command router.
+- Help output and command descriptions.
+- Command docs and tests.
+
+## Acceptance Criteria
+
+- `npx create-quiver --version` and `-V` print package version and exit `0`.
+- `ai approve --phase technical-plan --version <n>` still uses draft version semantics.
+- `--help`, `help`, and local `quiver --help` show grouped commands with descriptions.
+- Help drift is covered by automated tests.
+
+## Technical Plan Summary
+
+Route top-level version flags before command-specific option parsing. Centralize or test the public command help surface. Preserve subcommand option ownership.
+
+## Suggested Execution Steps
+
+1. Read the CLI router and current help implementation.
+2. Add top-level version handling only for commandless version requests.
+3. Improve help output and command descriptions.
+4. Add focused CLI tests.
+5. Update docs and evidence.
+
+## Restrictions
+
+- Do not change AI phase state in this slice.
+- Do not remove existing command aliases.
+
+## Risks
+
+- Over-broad `--version` handling could break planner draft approvals.
+
+## Completion Checklist
+
+- [ ] Version tests added.
+- [ ] Help output tests added.
+- [ ] AI approve version behavior preserved.
+- [ ] Docs updated.
+

package/specs/quiver-v26-0121-smoke-hardening/slices/slice-01-cli-help-version-contract/slice.json

@@ -0,0 +1,76 @@
+{
+  "slice_id": "slice-01-cli-help-version-contract",
+  "ticket": "QUIVER-26-01",
+  "type": "fix",
+  "title": "CLI help and version contract",
+  "objective": "Make top-level version and help output reliable, complete, and test-covered without breaking AI draft version approvals.",
+  "description": "Fix top-level --version handling, improve grouped help output, add help drift coverage, and preserve subcommand-specific --version semantics for AI approvals.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "cli-help-version-contract",
+    "branch_name": "feature/QUIVER-26-01-cli-help-version-contract"
+  },
+  "files": [
+    "bin/create-quiver.js",
+    "src/create-quiver/index.js",
+    "src/create-quiver/**",
+    "README.md",
+    "docs/COMMANDS.md.template",
+    "tests/**",
+    "specs/quiver-v26-0121-smoke-hardening/**"
+  ],
+  "expected_read_paths": [
+    "bin/create-quiver.js",
+    "src/create-quiver/index.js",
+    "package.json",
+    "tests/commands/**",
+    "README.md",
+    "docs/COMMANDS.md.template"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/**",
+    "README.md",
+    "docs/COMMANDS.md.template",
+    "tests/**",
+    "specs/quiver-v26-0121-smoke-hardening/**"
+  ],
+  "depends_on": [
+    "slice-00-docs-foundation"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "This slice owns shared CLI routing and help output used by later slices.",
+  "must": [
+    "Support top-level --version and -V as package version output.",
+    "Preserve ai approve --version <n> draft-version behavior.",
+    "Support npx create-quiver --help, npx create-quiver help, and local quiver --help.",
+    "Group public commands with descriptions and examples.",
+    "Add tests that prevent important commands from missing help descriptions."
+  ],
+  "not_included": [
+    "Changing AI lifecycle state behavior.",
+    "Changing generated docs beyond command references.",
+    "Publishing npm."
+  ],
+  "acceptance": [
+    "Top-level version commands exit 0 and print the package version.",
+    "AI approval version commands still work with draft versions.",
+    "Help output lists public commands with descriptions grouped by purpose.",
+    "Tests fail if important public commands are missing from help.",
+    "Unknown command behavior remains clear and actionable."
+  ],
+  "tests": [
+    "node --test tests/commands/cli-contract.test.js",
+    "node --test tests/commands/ai-plan.test.js tests/lib/approvals.test.js",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Exercise both top-level --version and ai approve --version <n>.",
+    "Validate local alias through package bin metadata or installed fixture when practical."
+  ],
+  "estimated_hours": 4,
+  "status": "completed",
+  "blocked_reason": null,
+  "actual_hours": 2,
+  "completed_at": "2026-05-23T00:00:00-0300"
+}

package/specs/quiver-v26-0121-smoke-hardening/slices/slice-02-init-doc-links-and-flow-guidance/CLOSURE_BRIEF.md

@@ -0,0 +1,37 @@
+# CLOSURE BRIEF - slice-02: Init doc links and flow guidance
+
+## Summary of Work
+
+- Replaced default command doc links to optional examples with inline commands.
+- Removed the generated status link to a placeholder slice that does not exist in default init.
+- Added doctor regression coverage for missing generated local docs links.
+- Added flow regression coverage for `init -> analyze -> flow`.
+
+## Validation Against Acceptance Criteria
+
+- [x] Default init docs verified.
+- [x] Doctor warnings resolved.
+- [x] Flow guidance verified.
+- [x] Tests run.
+
+## Relevant Changes
+
+- `docs/COMMANDS.md.template`
+- `docs/STATUS.md.template`
+- `tests/commands/doctor.test.js`
+- `tests/commands/flow.test.js`
+- `specs/quiver-v26-0121-smoke-hardening/EVIDENCE_REPORT.md`
+- `specs/quiver-v26-0121-smoke-hardening/STATUS.md`
+- `specs/quiver-v26-0121-smoke-hardening/slices/slice-02-init-doc-links-and-flow-guidance/slice.json`
+
+## Pending
+
+- None.
+
+## Remaining Risks
+
+- Optional docs must not be referenced by default docs unless generated.
+
+## Future Recommendations
+
+- Keep generated doc link checks in smoke coverage.

package/specs/quiver-v26-0121-smoke-hardening/slices/slice-02-init-doc-links-and-flow-guidance/EXECUTION_BRIEF.md

@@ -0,0 +1,52 @@
+# EXECUTION BRIEF - slice-02: Init doc links and flow guidance
+
+## Context
+
+The clean npm smoke test showed `doctor` warnings for links generated by default init and a temporary stale `flow` state when analyze had not completed yet.
+
+## Objective
+
+Make generated docs internally consistent and make `flow` guidance match the actual project state.
+
+## Scope
+
+- Default init templates and template selection.
+- Doctor link checks.
+- Flow next-step guidance.
+- Tests and evidence.
+
+## Acceptance Criteria
+
+- Default init docs do not contain broken links created by Quiver.
+- `doctor` does not warn about Quiver-generated default links.
+- `flow` shows correct next steps after analyze.
+- Tests cover default init and flow state.
+
+## Technical Plan Summary
+
+Audit links in default init templates, remove or generate referenced optional files consistently, and update flow state checks to avoid stale blockers.
+
+## Suggested Execution Steps
+
+1. Reproduce default init + doctor warnings in a fixture.
+2. Fix template references or generated file set.
+3. Verify `flow` before and after analyze.
+4. Add focused tests.
+5. Update evidence.
+
+## Restrictions
+
+- Do not widen default init to legacy/full assets unless necessary.
+- Do not touch AI approval state in this slice.
+
+## Risks
+
+- Removing useful links could reduce onboarding quality; prefer valid links over deletion when the target should exist.
+
+## Completion Checklist
+
+- [ ] Template links audited.
+- [ ] Doctor warnings resolved.
+- [ ] Flow state tests added.
+- [ ] Smoke coverage updated if needed.
+

package/specs/quiver-v26-0121-smoke-hardening/slices/slice-02-init-doc-links-and-flow-guidance/slice.json

@@ -0,0 +1,75 @@
+{
+  "slice_id": "slice-02-init-doc-links-and-flow-guidance",
+  "ticket": "QUIVER-26-02",
+  "type": "fix",
+  "title": "Init doc links and flow guidance",
+  "objective": "Remove broken links from default generated docs and make flow guidance reflect the current project state after analyze and doctor.",
+  "description": "Fix default init template references, doctor link warnings, and guided flow next-step messaging for clean projects.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "init-doc-links-flow-guidance",
+    "branch_name": "feature/QUIVER-26-02-init-doc-links-flow-guidance"
+  },
+  "files": [
+    "src/create-quiver/lib/init-docs.js",
+    "src/create-quiver/lib/init-layout.js",
+    "src/create-quiver/lib/doctor.js",
+    "src/create-quiver/commands/flow.js",
+    "docs/**/*.template",
+    "tests/**",
+    "specs/quiver-v26-0121-smoke-hardening/**"
+  ],
+  "expected_read_paths": [
+    "docs/COMMANDS.md.template",
+    "docs/STATUS.md.template",
+    "src/create-quiver/lib/doctor.js",
+    "src/create-quiver/commands/flow.js",
+    "tests/commands/flow.test.js",
+    "tests/commands/doctor.test.js"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/lib/init-docs.js",
+    "src/create-quiver/lib/init-layout.js",
+    "src/create-quiver/lib/doctor.js",
+    "src/create-quiver/commands/flow.js",
+    "docs/**/*.template",
+    "tests/**",
+    "specs/quiver-v26-0121-smoke-hardening/**"
+  ],
+  "depends_on": [
+    "slice-01-cli-help-version-contract"
+  ],
+  "parallel_safe": "maybe",
+  "parallel_safe_reason": "Can run beside slice-03 only if shared flow/help files do not overlap.",
+  "must": [
+    "Default init docs must not reference files absent from the default profile.",
+    "doctor must not warn about links Quiver itself generated incorrectly.",
+    "flow must show the correct next step after analyze creates PROJECT_MAP.md.",
+    "Errors and warnings must remain actionable."
+  ],
+  "not_included": [
+    "Changing AI approval persistence.",
+    "Changing demo scaffold behavior."
+  ],
+  "acceptance": [
+    "Default init followed by doctor has no generated-doc broken-link warnings.",
+    "After analyze, flow no longer reports PROJECT_MAP.md as missing.",
+    "Generated docs still point users to valid examples or omit optional references.",
+    "Focused tests cover default init docs and flow state."
+  ],
+  "tests": [
+    "node --test tests/commands/flow.test.js tests/commands/doctor.test.js tests/lib/init-layout.test.js",
+    "npm run smoke:create-quiver",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Use a clean temp directory for init/analyze/doctor/flow.",
+    "Check both before and after analyze state."
+  ],
+  "estimated_hours": 4,
+  "status": "completed",
+  "blocked_reason": null,
+  "actual_hours": 2,
+  "completed_at": "2026-05-23T00:00:00-0300"
+}

package/specs/quiver-v26-0121-smoke-hardening/slices/slice-03-ai-approval-review-consistency/CLOSURE_BRIEF.md

@@ -0,0 +1,37 @@
+# CLOSURE BRIEF - slice-03: AI approval and review consistency
+
+## Summary of Work
+
+- Clarified spec generation blockers when review state is missing or stale.
+- Ensured flow does not suggest re-approving an already approved technical plan before review.
+- Added regression coverage for approved-but-unreviewed technical plan guidance.
+- Updated tests for actionable review-plan next commands.
+
+## Validation Against Acceptance Criteria
+
+- [x] Unsupported phase suggestions removed.
+- [x] Spec-create blockers verified.
+- [x] Reviewed approval path verified.
+- [x] Tests run.
+
+## Relevant Changes
+
+- `src/create-quiver/lib/ai/plan-review.js`
+- `src/create-quiver/commands/flow.js`
+- `tests/commands/flow.test.js`
+- `tests/commands/ai-review-plan.test.js`
+- `specs/quiver-v26-0121-smoke-hardening/EVIDENCE_REPORT.md`
+- `specs/quiver-v26-0121-smoke-hardening/STATUS.md`
+- `specs/quiver-v26-0121-smoke-hardening/slices/slice-03-ai-approval-review-consistency/slice.json`
+
+## Pending
+
+- None.
+
+## Remaining Risks
+
+- Existing approval artifacts remain compatible; only user-facing guidance changed.
+
+## Future Recommendations
+
+- Keep every printed next command covered by a CLI acceptance test.

package/specs/quiver-v26-0121-smoke-hardening/slices/slice-03-ai-approval-review-consistency/EXECUTION_BRIEF.md

@@ -0,0 +1,53 @@
+# EXECUTION BRIEF - slice-03: AI approval and review consistency
+
+## Context
+
+The smoke test showed that Quiver correctly blocks spec generation without reviewed plan state, but the recovery path can be confusing. A suggested `plan-review` approval phase is not supported by `ai approve`.
+
+## Objective
+
+Make review/approval/spec-create gates coherent, testable, and actionable.
+
+## Scope
+
+- `ai review-plan` guidance.
+- `ai approve` phase guidance.
+- `spec create` blockers.
+- `flow` next-step messages for plan review.
+- Tests and docs.
+
+## Acceptance Criteria
+
+- No unsupported approval phase is suggested.
+- Missing review state blocks spec creation with the exact next command.
+- Reviewed technical-plan drafts can be approved through a supported path.
+- Tests cover review/approval/spec-create edge cases.
+
+## Technical Plan Summary
+
+Audit approval state transitions and user-facing messages. Clarify status labels and block conditions without weakening review gates.
+
+## Suggested Execution Steps
+
+1. Reproduce the approved-but-unreviewed state.
+2. Audit `flow`, `review-plan`, `approve`, and `spec create` messages.
+3. Fix unsupported phase suggestions.
+4. Add focused tests for state transitions.
+5. Update docs and evidence.
+
+## Restrictions
+
+- Do not allow spec generation from unreviewed technical plans.
+- Do not introduce a new phase unless it is fully wired and tested.
+
+## Risks
+
+- Changing approval labels can break existing tests or stored state expectations.
+
+## Completion Checklist
+
+- [ ] Blocker messages are actionable.
+- [ ] Supported command path verified.
+- [ ] Tests added.
+- [ ] Docs updated.
+