create-quiver 0.14.0 → 0.15.0

package/specs/quiver-v29-planner-prepare-context-cli-ux/slices/slice-06-docs-tests-smoke-readiness/CLOSURE_BRIEF.md

@@ -0,0 +1,31 @@
+# CLOSURE_BRIEF - slice-06 Docs, tests, smoke, and release readiness
+
+## Summary
+
+Completed final documentation, template, workflow, test, smoke, package, and tarball readiness for Quiver v29.
+
+## Validation Against Acceptance Criteria
+
+- Documentation now covers deterministic and planner-assisted `ai prepare-context`, guarded UX flags, review/interactive flows, color tokens, JSON/CI/no-TTY behavior, and command applicability.
+- `README_FOR_AI.md` is synchronized with implemented behavior and records v29 as implemented but pending package publication.
+- Generated templates now include planner-assisted context guidance and UX flag rules.
+- Full tests, focused tests, smoke commands, package validation, tarball dry-run, spec validation, handoff validation, JSON validation, and diff check passed.
+
+## Relevant Changes
+
+- Added `docs/CLI_UX_GUIDE.md`.
+- Updated `README.md`, `README_FOR_AI.md`, `docs/reference/commands.md`, generated templates, workflow guides, `CHANGELOG.md`, and `ROADMAP.md`.
+- Updated spec status, evidence, and slice metadata.
+
+## Pending Work
+
+- Npm publication and PR creation are outside this slice unless explicitly requested later.
+
+## Remaining Risks
+
+- Package version remains `0.14.0`; publication/version bump is intentionally outside this slice.
+- The npm CLI printed an update notice for npm `11.12.1 -> 11.15.0`; it did not block validation.
+
+## Future Recommendations
+
+- Use dogfooding findings from the first planner-assisted projects to scope the next UX adoption batch.

package/specs/quiver-v29-planner-prepare-context-cli-ux/slices/slice-06-docs-tests-smoke-readiness/EXECUTION_BRIEF.md

@@ -0,0 +1,50 @@
+# EXECUTION_BRIEF - slice-06 Docs, tests, smoke, and release readiness
+
+## Context
+
+This is the final Quiver v29 slice. It must reconcile implementation, documentation, generated templates, tests, and package safety.
+
+## Objective
+
+Close the spec with complete documentation and validation evidence.
+
+## Scope
+
+- Update public and AI-facing docs.
+- Add or update `docs/CLI_UX_GUIDE.md`.
+- Update command references and templates.
+- Run full tests and smoke commands.
+- Update spec status, evidence, and closure briefs.
+
+## Acceptance Criteria
+
+- Documentation matches implemented behavior.
+- README_FOR_AI.md remains source-of-truth aligned.
+- Tests and package smoke pass.
+- Any blocker is explicitly documented.
+
+## Suggested Steps
+
+1. Compare implementation against `SPEC.md`.
+2. Update docs and templates.
+3. Run focused tests, then full test suite.
+4. Run smoke/package commands.
+5. Update status/evidence/closure docs.
+
+## Restrictions
+
+- Do not add new behavior in this slice unless required to fix a validation failure from prior slices.
+- Do not publish npm.
+- Do not open PR.
+
+## Risks
+
+- Docs can easily drift from real behavior. Verify against `node bin/create-quiver.js --help`.
+
+## Completion Checklist
+
+- [ ] Docs synchronized.
+- [ ] Full tests run.
+- [ ] Smoke/package validation run.
+- [ ] Spec status updated.
+- [ ] Final risks recorded.

package/specs/quiver-v29-planner-prepare-context-cli-ux/slices/slice-06-docs-tests-smoke-readiness/slice.json

@@ -0,0 +1,95 @@
+{
+  "slice_id": "slice-06-docs-tests-smoke-readiness",
+  "ticket": "QUIVER-29-06",
+  "type": "docs",
+  "title": "Docs, tests, smoke, and release readiness",
+  "objective": "Close the spec by synchronizing documentation, templates, tests, package safety, and release evidence.",
+  "description": "Ensures the implemented CLI UX standard and planner-assisted prepare-context flow are documented, tested, and package-ready.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v29-docs-tests-smoke-readiness",
+    "branch_name": "feature/QUIVER-29-06-v29-docs-tests-smoke-readiness"
+  },
+  "files": [
+    "README.md",
+    "README_FOR_AI.md",
+    "CHANGELOG.md",
+    "ROADMAP.md",
+    "docs/COMMANDS.md.template",
+    "docs/AI_CONTEXT.md.template",
+    "docs/AI_ONBOARDING_PROMPT.md.template",
+    "docs/CLI_UX_GUIDE.md",
+    "docs/reference/commands.md",
+    "docs/workflows/*.md",
+    "tests/**",
+    "specs/quiver-v29-planner-prepare-context-cli-ux/**"
+  ],
+  "expected_read_paths": [
+    "README.md",
+    "README_FOR_AI.md",
+    "docs/**",
+    "tests/**",
+    "scripts/package-quiver.sh",
+    "scripts/ci/**"
+  ],
+  "allowed_write_paths": [
+    "README.md",
+    "README_FOR_AI.md",
+    "CHANGELOG.md",
+    "ROADMAP.md",
+    "docs/COMMANDS.md.template",
+    "docs/AI_CONTEXT.md.template",
+    "docs/AI_ONBOARDING_PROMPT.md.template",
+    "docs/CLI_UX_GUIDE.md",
+    "docs/reference/commands.md",
+    "docs/workflows/*.md",
+    "tests/**",
+    "specs/quiver-v29-planner-prepare-context-cli-ux/**"
+  ],
+  "depends_on": [
+    "slice-02-planner-context-proposal-contract",
+    "slice-03-prepare-context-planner-review-flow",
+    "slice-04-ux-flag-matrix-compatibility",
+    "slice-05-progressive-command-adoption"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Final validation and docs sync must run after all behavior slices.",
+  "must": [
+    "Document the UX standard, color tokens, and flag matrix.",
+    "Document deterministic and planner-assisted prepare-context flows.",
+    "Update generated templates where needed.",
+    "Run full test and smoke suite.",
+    "Record validation evidence in the spec.",
+    "Keep README_FOR_AI.md synchronized with implemented behavior."
+  ],
+  "not_included": [
+    "Publishing npm.",
+    "Opening the final PR.",
+    "Adding new behavior beyond closing docs/tests."
+  ],
+  "acceptance": [
+    "Docs do not contradict implemented command behavior.",
+    "Generated docs/templates include the new UX and planner guidance.",
+    "Full tests and smoke commands pass or documented blockers are explicit.",
+    "Package/tarball dry-run is clean.",
+    "Spec status and closure briefs reflect final implementation state."
+  ],
+  "tests": [
+    "node --test tests/**/*.test.js",
+    "npm run smoke:create-quiver",
+    "npm run smoke:doctor-fixtures",
+    "npm run smoke:guided-workflow",
+    "npm run package:quiver",
+    "npm pack --dry-run",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Run this slice last.",
+    "Check README_FOR_AI.md against actual CLI behavior before closing."
+  ],
+  "estimated_hours": 6,
+  "actual_hours": 4,
+  "status": "completed",
+  "completed_at": "2026-05-26"
+}

package/specs/quiver-v30-interactive-cli-ux-agent-selection/EVIDENCE_REPORT.md

@@ -0,0 +1,213 @@
+# Evidence Report - Quiver v30 Interactive CLI UX and Agent Selection
+
+## Summary
+
+This report records the evidence for every v30 slice, from the documentation foundation through final release readiness.
+
+## slice-00 - Spec foundation
+
+### Completed
+
+- Create v30 spec folder.
+- 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`.
+- Sync source-of-truth planning docs with v29 release status and v30 planned scope.
+
+### Validation
+
+- `find specs/quiver-v30-interactive-cli-ux-agent-selection -name 'slice.json' -print -exec node -e "JSON.parse(require('fs').readFileSync(process.argv[1], 'utf8')); console.log('ok', process.argv[1])" {} \;` passed for 9 slice files.
+- `git diff --check` passed.
+- `node bin/create-quiver.js spec validate specs/quiver-v30-interactive-cli-ux-agent-selection` passed and reported 9 slices.
+
+### Risks Observed During Validation
+
+- None for the documentation package.
+
+## Later Slices
+
+Each implementation slice appended:
+
+- commands executed;
+- tests or smokes run;
+- files changed;
+- validation result;
+- UX/machine-output evidence;
+- remaining risks;
+- evidence location.
+
+## slice-01 - CLI UX runtime and progress engine
+
+### Completed
+
+- Extended `src/create-quiver/lib/cli/theme.js` with section, success, warning, and error semantics while keeping the approved Quiver palette centralized.
+- Extended `src/create-quiver/lib/cli/ux.js` with helpers for sections, checks, warnings, errors, summaries, next steps, and task groups.
+- Hardened spinner stop behavior so a spinner is stopped once on success or failure.
+- Added tests for branded human hierarchy, plain no-TTY fallback, JSON suppression, and real stage execution through `taskGroup`.
+
+### Validation
+
+- `node --test tests/lib/cli-theme.test.js tests/lib/cli-ux.test.js` passed: 15 tests.
+- `git diff --check` passed.
+
+### Risks
+
+- Command adoption is intentionally deferred to later slices; this slice only adds the runtime.
+
+## slice-02 - Agent profile selection and selectors
+
+### Completed
+
+- Added backward-compatible multiple named agent profiles per role.
+- Kept legacy single-profile behavior by preserving the default profile under `profiles.<role>`.
+- Added profile sets under `profile_sets.<role>s`.
+- Added display-name resolution order for profile output.
+- Added CLI flags for profile identity and future selectors: `--id`, `--display-name`, `--default`, `--planner`, `--executor`, `--reviewer`, `--doctor`, and `--methodology`.
+- Added `src/create-quiver/lib/cli/selectors.js` for reusable interactive/non-interactive selection.
+- Extended `ai agent set/list/show` for named profiles.
+
+### Validation
+
+- `node --test tests/lib/agent-profiles.test.js tests/lib/cli-selectors.test.js tests/commands/ai-agent.test.js` passed: 16 tests.
+- `git diff --check` passed.
+- `node bin/create-quiver.js spec validate specs/quiver-v30-interactive-cli-ux-agent-selection` passed.
+
+### Risks
+
+- Command flows do not yet consume the new profile selector flags; that adoption belongs to later slices.
+- Provider model correctness is not enforced until slice-03.
+
+## slice-03 - Provider model selection contract
+
+### Completed
+
+- Added provider adapter metadata for model selection support and model argument construction.
+- Added model-selection metadata to provider invocations and dry-run results.
+- Added live execution enforcement so selected models are passed to provider adapters or block with actionable guidance when unsupported.
+- Wired planner/reviewer profile model selection into `ai onboard`, `ai prepare-context --with-planner`, `ai plan`, `ai review-plan`, `ai repair-plan`, and `ai revise`.
+- Added command flag propagation for `--model`, `--planner`, and `--reviewer` in planner/reviewer flows.
+- Documented the model-selection contract in `docs/CLI_UX_GUIDE.md` and synchronized `README_FOR_AI.md`.
+
+### Validation
+
+- `node --test tests/lib/ai-providers.test.js tests/commands/ai-agent.test.js tests/commands/ai-onboard.test.js tests/commands/ai-plan.test.js tests/commands/ai-review-plan.test.js tests/commands/ai-prepare-context-planner.test.js` passed: 72 tests.
+- `git diff --check` passed.
+- `node bin/create-quiver.js spec validate specs/quiver-v30-interactive-cli-ux-agent-selection` passed.
+
+### Risks
+
+- Provider model flags are implemented through the current adapter contract. Installed provider CLIs can still vary by version, so later release validation should dogfood dry-run and live commands with available local CLIs.
+- Executor provider/model propagation remains for slice-05.
+
+## slice-04 - Planner IA progress flows
+
+### Completed
+
+- Added a shared command UX bridge for planner-oriented IA commands.
+- Added visible TTY progress for `ai onboard`, `ai prepare-context --with-planner`, `ai plan`, `ai review-plan`, `ai repair-plan`, and `ai revise`.
+- Progress headings use the selected profile/model display name when available.
+- Provider execution now runs inside a spinner in human TTY mode and stops on both success and provider failure.
+- `--dry-run`, `--print-prompt`, CI, and non-TTY output remain free of progress noise.
+- Updated `docs/CLI_UX_GUIDE.md` and `README_FOR_AI.md` with the progress-output standard.
+
+### Validation
+
+- `node --test tests/commands/ai-prepare-context-planner.test.js tests/commands/ai-onboard.test.js tests/commands/ai-plan.test.js tests/commands/ai-review-plan.test.js tests/lib/cli-ux.test.js` passed: 65 tests.
+- `git diff --check` passed.
+
+### Risks
+
+- Some direct unit tests run with a TTY can display clack spinner artifacts in the test log, although captured no-TTY output remains clean. Slice-08 should include a final full-suite check and adjust test harness mode if needed.
+- Executor and PR command progress remains for slice-05.
+
+## slice-05 - Executor, execution-plan, and PR progress flows
+
+### Completed
+
+- Added executor runtime profile/model resolution and provider model enforcement to `ai execute-slice`.
+- Added interactive ready-slice selection for `ai execute-slice --interactive` when `--slice` is omitted.
+- Added interactive executor profile selection when multiple executor profiles are configured.
+- Added TTY progress for executor provider execution, validation commands, slice commits, execution-plan waves, GitHub preflight, and PR creation.
+- Added model visibility to execute-slice and execute-plan dry-runs.
+- Extended UX flag support to `ai execute-slice` and `ai execute-plan` for `--interactive`.
+- Preserved clean JSON/no-TTY behavior and existing PR/gh error propagation.
+
+### Validation
+
+- `node --test tests/lib/ai-executor.test.js tests/commands/ai-execute-slice.test.js tests/lib/ai-execution-plan.test.js tests/commands/ai-execute-plan.test.js tests/commands/ai-pr.test.js tests/commands/ux-flags.test.js` passed: 54 tests.
+- `git diff --check` passed.
+
+### Risks
+
+- `ai execute-plan --interactive` is now accepted for strategy UX consistency, but this slice does not yet add a full strategy selector. Future UX work can add it without changing the safety contract.
+- Direct TTY unit runs can still show spinner artifacts in logs; final suite validation should decide whether to force test I/O to no-TTY.
+
+## slice-06 - Doctor visual and JSON contract
+
+### Completed
+
+- Added a shared Doctor command report with stable fields for `schema_version`, `status`, `exit_code`, `checks`, `suggested_fixes`, `warnings`, and `errors`.
+- Rendered human Doctor output with the required `Quiver Doctor`, `Checks`, and `Suggested fixes` hierarchy.
+- Added `doctor --json` output that is parseable, machine-clean, and backed by the same checks as human output.
+- Preserved deterministic exit-code behavior: warnings remain exit code 0 and blocking layout errors set exit code 1.
+- Kept `doctor --fix --dry-run` behavior and added clean JSON behavior for `doctor --fix --dry-run --json`.
+- Updated Doctor documentation in `docs/CLI_UX_GUIDE.md`, `docs/reference/commands.md`, and `README_FOR_AI.md`.
+
+### Validation
+
+- `node --test tests/commands/doctor.test.js tests/lib/doctor.test.js tests/lib/cli-ux.test.js` passed: 29 tests.
+- `npm run smoke:doctor-fixtures` passed: 13 fixture states.
+- `git diff --check` passed.
+
+### Risks
+
+- Local environment checks can still add host-dependent warnings, for example `gh auth` status. That behavior existed before this slice and remains visible through the shared check model.
+- Downstream JSON consumers should pin to `schema_version: 1` and avoid parsing human text.
+
+## slice-07 - Interactive init and spec create flows
+
+### Completed
+
+- Added guarded `init --interactive` flow for project mode, methodology, init profile, and optional agent-profile guidance.
+- Added `--methodology wdd-sdd` validation and documented that no other methodology is currently supported.
+- Added `spec create --interactive` selectors for methodology, approved plan input, and direct-vs-review mode.
+- Added summaries before persistent writes for interactive init/spec-create flows.
+- Added explicit no-TTY failure for interactive init/spec-create so CI and scripts do not hang.
+- Extended UX flag support to `init --interactive`.
+- Updated help text, CLI UX guide, command reference, and `README_FOR_AI.md`.
+
+### Validation
+
+- `node --test tests/commands/init-profiles.test.js tests/commands/spec-create.test.js tests/commands/ux-flags.test.js tests/commands/cli-contract.test.js` passed: 39 tests.
+- `node bin/create-quiver.js --help` showed the updated interactive init example and methodology flag.
+- `git diff --check` passed.
+
+### Risks
+
+- The `init --interactive` validation-only path delegates to `doctor`, which still requires Quiver initialization evidence in the target project.
+- The spec-create approved-input selector currently exposes the resolved approved technical-plan input. Wider selection across historical approved inputs is intentionally deferred until the approval store defines that as a stable contract.
+
+## slice-08 - Tests, docs, cross-platform smokes, and release readiness
+
+### Completed
+
+- Synchronized release-facing documentation for the v30 CLI UX behavior.
+- Updated command templates with `init --interactive`, `doctor --json`, `spec create --interactive`, `--methodology wdd-sdd`, and interactive human-output guidance.
+- Updated `README.md`, `README_FOR_AI.md`, `ROADMAP.md`, and `CHANGELOG.md` with the implemented v30 behavior.
+- Closed the v30 spec metadata and PR body with final validation evidence.
+- Confirmed release readiness without publishing to npm.
+
+### Validation
+
+- `node --test tests/**/*.test.js` passed: 449 tests.
+- `npm run smoke:create-quiver` passed.
+- `npm run smoke:guided-workflow` passed.
+- `npm run smoke:doctor-fixtures` passed: 13 fixture states.
+- `npm run package:quiver` passed and produced package-smoke evidence for `create-quiver-0.14.1.tgz`.
+- `npm pack --dry-run` passed.
+- `git diff --check` passed.
+- `node bin/create-quiver.js spec validate specs/quiver-v30-interactive-cli-ux-agent-selection` passed.
+
+### Risks
+
+- Live provider smoke tests were not executed against every external IA CLI because those checks depend on local provider installation and authentication.
+- Cross-platform behavior is covered by documented script-safe modes and automated command contracts, but final human terminal rendering should still be dogfooded on Windows PowerShell, Git Bash, WSL, macOS, and Linux before broad announcement.

package/specs/quiver-v30-interactive-cli-ux-agent-selection/EXECUTION_PLAN.md

@@ -0,0 +1,85 @@
+# Execution Plan - Quiver v30 Interactive CLI UX and Agent Selection
+
+## Execution Order
+
+```mermaid
+flowchart TD
+    S00[slice-00: Spec foundation and source-of-truth sync]
+    S01[slice-01: CLI UX runtime and progress engine]
+    S02[slice-02: Agent profile selection and selectors]
+    S03[slice-03: Provider model selection contract]
+    S04[slice-04: Planner IA progress flows]
+    S05[slice-05: Executor, execution-plan, and PR progress flows]
+    S06[slice-06: Doctor visual and JSON contract]
+    S07[slice-07: Interactive init and spec create flows]
+    S08[slice-08: Tests, docs, cross-platform smokes, and release readiness]
+
+    S00 --> S01
+    S01 --> S02
+    S02 --> S03
+    S01 --> S06
+    S01 --> S07
+    S02 --> S07
+    S03 --> S04
+    S03 --> S05
+    S04 --> S08
+    S05 --> S08
+    S06 --> S08
+    S07 --> S08
+```
+
+## Waves
+
+### Wave 0 - Sequential
+
+1. `slice-00-spec-foundation`
+
+This slice must run first. It commits the approved spec, all slices, handoffs, execution plan, PR body, and source-of-truth documentation sync.
+
+### Wave 1 - Sequential
+
+1. `slice-01-cli-ux-runtime-progress-engine`
+
+Shared UX runtime and progress lifecycle must exist before command adoption.
+
+### Wave 2 - Sequential Core Selection
+
+1. `slice-02-agent-profile-selection-selectors`
+2. `slice-03-provider-model-selection-contract`
+
+Profile selectors must land before provider model execution semantics so selected models and display names map to real provider invocations.
+
+### Wave 3 - Parallel after slice-03
+
+- `slice-04-planner-ia-progress-flows`
+- `slice-05-executor-pr-progress-flows`
+- `slice-06-doctor-visual-json-contract`
+- `slice-07-interactive-init-spec-create`
+
+These can run in parallel if their write scopes stay separated. Resolve conflicts in `src/create-quiver/commands/ai.js` by landing planner flows before executor/PR flows if needed.
+
+### Wave 4 - Sequential Close
+
+1. `slice-08-tests-docs-cross-platform-release`
+
+This slice validates all previous work, updates final docs/templates, and prepares package release evidence.
+
+## Parallel Safety Notes
+
+- Do not run any implementation slice before `slice-00`.
+- Do not adopt command progress before `slice-01`.
+- Do not show profile/model display names in live IA flows before `slice-03` proves selected models map to real provider invocations.
+- `slice-04` and `slice-05` may both touch `commands/ai.js`; if conflicts are likely, run `slice-04` first.
+- `slice-08` is never parallel-safe because it closes docs, tests, smokes, and release readiness.
+
+## Recommended Commit Order
+
+1. `docs: add v30 interactive cli ux spec`
+2. `feat: add cli ux progress runtime`
+3. `feat: add agent profile selectors`
+4. `feat: add provider model selection contract`
+5. `feat: add planner progress flows`
+6. `feat: add executor and pr progress flows`
+7. `feat: add doctor visual json contract`
+8. `feat: add interactive init and spec create`
+9. `docs: close v30 cli ux release readiness`