create-quiver 0.15.2 → 0.15.4

package/specs/quiver-v34-cli-dashboard-status/slices/slice-03-dashboard-edge-cases-and-guardrails/slice.json

@@ -0,0 +1,77 @@
+{
+  "slice_id": "slice-03-dashboard-edge-cases-and-guardrails",
+  "ticket": "QUIVER-34-03",
+  "type": "fix",
+  "title": "Dashboard edge cases and guardrails",
+  "objective": "Harden the dashboard against partial fixes and misleading output in unusual project states.",
+  "description": "Adds guardrails for missing specs, invalid graph state, no-spec projects, legacy/incomplete layouts, blockers, no-color/CI/no-TTY, and sensitive evidence summaries.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v34-dashboard-edge-cases",
+    "branch_name": "feature/QUIVER-34-03-dashboard-edge-cases"
+  },
+  "files": [
+    "src/create-quiver/lib/dashboard.js",
+    "src/create-quiver/commands/dashboard.js",
+    "tests/lib/dashboard.test.js",
+    "tests/commands/dashboard.test.js"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/lib/dashboard.js",
+    "src/create-quiver/commands/dashboard.js",
+    "src/create-quiver/lib/ai/export-state.js",
+    "src/create-quiver/lib/slice-graph.js",
+    "tests/commands/ai-export.test.js",
+    "tests/commands/dashboard.test.js",
+    "specs/quiver-v34-cli-dashboard-status/SPEC.md"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/lib/dashboard.js",
+    "src/create-quiver/commands/dashboard.js",
+    "tests/lib/dashboard.test.js",
+    "tests/commands/dashboard.test.js",
+    "specs/quiver-v34-cli-dashboard-status/**"
+  ],
+  "depends_on": [
+    "slice-01-dashboard-report-contract",
+    "slice-02-dashboard-command-rendering"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "This slice hardens behavior across the report and command layers.",
+  "must": [
+    "Fail actionably for explicit missing --spec values.",
+    "Render useful state for no specs and no slices.",
+    "Render useful state for legacy, incomplete, and not-initialized layouts where the existing state resolver can report them.",
+    "Degrade safely when the slice graph has cycles or missing dependencies.",
+    "Avoid printing raw evidence, logs, command output, secrets, or tokens.",
+    "Keep JSON output parseable for success and failure paths.",
+    "Cover no-color, CI, and no-TTY behavior."
+  ],
+  "not_included": [
+    "Changing slice graph semantics.",
+    "Adding destructive actions.",
+    "Adding web or TUI surfaces."
+  ],
+  "acceptance": [
+    "Missing --spec produces an actionable error.",
+    "Invalid graph state produces a dashboard warning rather than a crash.",
+    "No-spec projects produce next-step guidance.",
+    "Legacy/incomplete layouts show migration guidance.",
+    "Evidence summaries expose counts/refs only.",
+    "No-color output remains readable."
+  ],
+  "tests": [
+    "node --test tests/lib/dashboard.test.js tests/commands/dashboard.test.js",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Create focused fixture repos for edge states.",
+    "Avoid broad refactors of slice graph internals."
+  ],
+  "estimated_hours": 5,
+  "status": "completed",
+  "blocked_reason": null,
+  "actual_hours": 4,
+  "completed_at": "2026-05-28"
+}

package/specs/quiver-v34-cli-dashboard-status/slices/slice-04-docs-templates-and-scripts/CLOSURE_BRIEF.md

@@ -0,0 +1,19 @@
+# CLOSURE_BRIEF - slice-04 Docs, templates, and scripts
+
+## Summary
+
+Documented `dashboard` in README, AI guidance, command reference, CLI UX guide, generated command/workflow templates, init docs, package scripts, and generated project scripts. Added `quiver:dashboard` and updated related tests.
+
+## Validation
+
+- [x] `node --test tests/lib/init-docs.test.js tests/lib/init-layout.test.js`
+- [x] `node --test tests/commands/cli-contract.test.js`
+- [x] `git diff --check`
+
+## Pending
+
+- None for this slice.
+
+## Remaining Risks
+
+- None critical.

package/specs/quiver-v34-cli-dashboard-status/slices/slice-04-docs-templates-and-scripts/EXECUTION_BRIEF.md

@@ -0,0 +1,54 @@
+# EXECUTION_BRIEF - slice-04 Docs, templates, and scripts
+
+## Context
+
+The dashboard command and guardrails are stable after slices 02 and 03. Public docs and generated project scripts now need to reflect the command.
+
+## Objective
+
+Document `dashboard` and add generated `quiver:dashboard` script support.
+
+## Scope
+
+- public docs
+- AI guidance
+- generated docs/templates
+- generated package scripts
+- focused docs/script tests
+
+## Acceptance Criteria
+
+- README and command reference mention `dashboard`.
+- `README_FOR_AI.md` mentions dashboard as a read-only inspection command.
+- CLI UX guide records dashboard as read-only and non-interactive.
+- Generated project scripts include `quiver:dashboard`.
+- Docs do not imply dashboard writes, executes providers, or opens a TUI.
+
+## Technical Plan Summary
+
+Update documentation only after the command contract is implemented. Keep root README concise and put procedural detail in command reference or generated docs.
+
+## Suggested Steps
+
+1. Update command reference.
+2. Update README command list.
+3. Update AI guidance.
+4. Update CLI UX guide matrix.
+5. Update generated docs/scripts.
+6. Update docs/template tests.
+
+## Restrictions
+
+- Do not change command behavior in this slice.
+- Do not claim npm publication.
+- Do not document Ink as part of this feature.
+
+## Risks
+
+- Docs can drift if command contract changes after this slice; run command tests before final readiness.
+
+## Completion Checklist
+
+- [ ] Docs updated.
+- [ ] Generated script tests updated.
+- [ ] Docs tests pass.

package/specs/quiver-v34-cli-dashboard-status/slices/slice-04-docs-templates-and-scripts/slice.json

@@ -0,0 +1,88 @@
+{
+  "slice_id": "slice-04-docs-templates-and-scripts",
+  "ticket": "QUIVER-34-04",
+  "type": "docs",
+  "title": "Docs, templates, and scripts",
+  "objective": "Document the dashboard command and add generated project script support.",
+  "description": "Updates public documentation, AI guidance, generated docs/templates, and package scripts after the dashboard command contract is stable.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v34-dashboard-docs-scripts",
+    "branch_name": "feature/QUIVER-34-04-dashboard-docs-scripts"
+  },
+  "files": [
+    "README.md",
+    "README_FOR_AI.md",
+    "docs/CLI_UX_GUIDE.md",
+    "docs/reference/commands.md",
+    "docs/COMMANDS.md.template",
+    "docs/WORKFLOW.md.template",
+    "package.json",
+    "src/create-quiver/lib/init-docs.js",
+    "tests/lib/init-docs.test.js",
+    "tests/lib/init-layout.test.js"
+  ],
+  "expected_read_paths": [
+    "README.md",
+    "README_FOR_AI.md",
+    "docs/CLI_UX_GUIDE.md",
+    "docs/reference/commands.md",
+    "src/create-quiver/lib/init-docs.js",
+    "tests/lib/init-docs.test.js",
+    "tests/lib/init-layout.test.js",
+    "specs/quiver-v34-cli-dashboard-status/SPEC.md"
+  ],
+  "allowed_write_paths": [
+    "README.md",
+    "README_FOR_AI.md",
+    "docs/CLI_UX_GUIDE.md",
+    "docs/reference/commands.md",
+    "docs/COMMANDS.md.template",
+    "docs/WORKFLOW.md.template",
+    "package.json",
+    "src/create-quiver/lib/init-docs.js",
+    "tests/lib/init-docs.test.js",
+    "tests/lib/init-layout.test.js",
+    "specs/quiver-v34-cli-dashboard-status/**"
+  ],
+  "depends_on": [
+    "slice-02-dashboard-command-rendering",
+    "slice-03-dashboard-edge-cases-and-guardrails"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Docs and generated scripts should land after command behavior is stable.",
+  "must": [
+    "Document `npx create-quiver dashboard` and key flags.",
+    "Document that dashboard is read-only and not a TUI/fullscreen surface.",
+    "Document `dashboard --json` compact schema at a high level.",
+    "Add generated `quiver:dashboard` script where generated quiver scripts are listed.",
+    "Keep README concise and avoid duplicating full procedural docs.",
+    "Update tests for generated docs/scripts."
+  ],
+  "not_included": [
+    "Changing command behavior.",
+    "Adding Ink/TUI docs.",
+    "Claiming npm publication."
+  ],
+  "acceptance": [
+    "Public docs mention dashboard usage and flags.",
+    "Generated scripts include quiver:dashboard.",
+    "Generated docs/templates stay aligned.",
+    "Docs do not imply dashboard writes or runs providers."
+  ],
+  "tests": [
+    "node --test tests/lib/init-docs.test.js tests/lib/init-layout.test.js",
+    "node --test tests/commands/cli-contract.test.js",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Keep command examples package-manager-aware where generated scripts are discussed.",
+    "Do not over-document internals in README."
+  ],
+  "estimated_hours": 4,
+  "status": "completed",
+  "blocked_reason": null,
+  "actual_hours": 3,
+  "completed_at": "2026-05-28"
+}

package/specs/quiver-v34-cli-dashboard-status/slices/slice-05-tests-smokes-release-readiness/CLOSURE_BRIEF.md

@@ -0,0 +1,26 @@
+# CLOSURE_BRIEF - slice-05 Tests, smokes, and release readiness
+
+## Summary
+
+Completed focused validation, full test suite, required smokes, package smoke, dashboard smoke against this repository, final spec validation, and evidence/status updates. No npm publication was performed.
+
+## Validation
+
+- [x] `node --test tests/lib/dashboard.test.js`
+- [x] `node --test tests/commands/dashboard.test.js`
+- [x] `node --test`
+- [x] `npm run smoke:create-quiver`
+- [x] `npm run smoke:doctor-fixtures`
+- [x] `npm run smoke:guided-workflow`
+- [x] `npm run package:quiver`
+- [x] `node bin/create-quiver.js dashboard --json --spec quiver-v34-cli-dashboard-status`
+- [x] `git diff --check`
+- [x] `node bin/create-quiver.js spec validate specs/quiver-v34-cli-dashboard-status`
+
+## Pending
+
+- None.
+
+## Remaining Risks
+
+- No critical risks. Package publication is intentionally out of scope.

package/specs/quiver-v34-cli-dashboard-status/slices/slice-05-tests-smokes-release-readiness/EXECUTION_BRIEF.md

@@ -0,0 +1,57 @@
+# EXECUTION_BRIEF - slice-05 Tests, smokes, and release readiness
+
+## Context
+
+All dashboard behavior and docs should be complete before this slice starts. This slice validates the whole spec and prepares PR readiness evidence.
+
+## Objective
+
+Close v34 with full validation and evidence.
+
+## Scope
+
+- tests as needed for final regressions
+- `specs/quiver-v34-cli-dashboard-status/**`
+
+## Acceptance Criteria
+
+- Focused dashboard tests pass.
+- CLI contract and UX flag tests pass.
+- Generated docs/script tests pass.
+- Full test suite passes or blockers are recorded.
+- Smokes and package smoke pass or blockers are recorded.
+- Spec validation passes.
+- Evidence and closure briefs are updated.
+
+## Technical Plan Summary
+
+Run focused validation first, then broad tests and smokes. Update evidence only with actual command outcomes.
+
+## Suggested Steps
+
+1. Run focused dashboard tests.
+2. Run CLI contract and UX flag tests.
+3. Run generated docs/script tests.
+4. Run full test suite.
+5. Run smokes and package check.
+6. Run spec validation.
+7. Update evidence, status, closure briefs, and PR body.
+
+## Restrictions
+
+- Do not publish npm.
+- Do not add new feature scope during readiness.
+- Do not hide unrelated failures; document them as blockers if they matter.
+
+## Risks
+
+- Package smokes can reveal generated-template drift late; leave enough time for a small docs/script correction if needed.
+
+## Completion Checklist
+
+- [ ] Focused tests pass.
+- [ ] Full tests pass.
+- [ ] Smokes pass.
+- [ ] Package smoke passes.
+- [ ] Evidence updated.
+- [ ] Spec validation passes.

package/specs/quiver-v34-cli-dashboard-status/slices/slice-05-tests-smokes-release-readiness/slice.json

@@ -0,0 +1,85 @@
+{
+  "slice_id": "slice-05-tests-smokes-release-readiness",
+  "ticket": "QUIVER-34-05",
+  "type": "validation",
+  "title": "Tests, smokes, and release readiness",
+  "objective": "Close v34 with full validation, evidence, status updates, and PR readiness.",
+  "description": "Runs focused and full validation, updates evidence, closes slice metadata, validates the spec package, and prepares the PR body without claiming npm publication.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v34-dashboard-release-readiness",
+    "branch_name": "feature/QUIVER-34-05-dashboard-release-readiness"
+  },
+  "files": [
+    "tests/**",
+    "specs/quiver-v34-cli-dashboard-status/**"
+  ],
+  "expected_read_paths": [
+    "SPEC.md",
+    "STATUS.md",
+    "EVIDENCE_REPORT.md",
+    "pr.md",
+    "tests/**",
+    "package.json",
+    "scripts/ci/**"
+  ],
+  "allowed_write_paths": [
+    "tests/**",
+    "specs/quiver-v34-cli-dashboard-status/**"
+  ],
+  "depends_on": [
+    "slice-03-dashboard-edge-cases-and-guardrails",
+    "slice-04-docs-templates-and-scripts"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Final validation and evidence must run after all implementation and docs slices.",
+  "must": [
+    "Run focused dashboard tests.",
+    "Run CLI contract and UX flag tests.",
+    "Run generated docs/script tests.",
+    "Run full test suite.",
+    "Run smoke commands.",
+    "Run package smoke.",
+    "Run spec validation.",
+    "Update EVIDENCE_REPORT.md with real results.",
+    "Update STATUS.md and slice CLOSURE_BRIEF.md files.",
+    "Prepare final pr.md evidence."
+  ],
+  "not_included": [
+    "Publishing npm.",
+    "Adding new dashboard scope after validation begins.",
+    "Changing accepted command semantics without revisiting prior slices."
+  ],
+  "acceptance": [
+    "Focused tests pass.",
+    "Full tests pass or any failure is documented with blocker status.",
+    "Smokes pass or blockers are recorded.",
+    "Spec validation passes.",
+    "Evidence report records commands and outcomes.",
+    "Final status reflects readiness accurately."
+  ],
+  "tests": [
+    "node --test tests/lib/dashboard.test.js",
+    "node --test tests/commands/dashboard.test.js",
+    "node --test tests/commands/cli-contract.test.js tests/commands/ux-flags.test.js",
+    "node --test tests/lib/ai-export-state.test.js tests/commands/ai-export.test.js",
+    "node --test tests/lib/init-docs.test.js tests/lib/init-layout.test.js",
+    "node --test tests/**/*.test.js",
+    "npm run smoke:create-quiver",
+    "npm run smoke:doctor-fixtures",
+    "npm run smoke:guided-workflow",
+    "npm run package:quiver",
+    "git diff --check",
+    "node bin/create-quiver.js spec validate specs/quiver-v34-cli-dashboard-status"
+  ],
+  "validation_hints": [
+    "Record evidence without claiming package publication.",
+    "If a full-suite failure is unrelated, document it explicitly instead of hiding it."
+  ],
+  "estimated_hours": 5,
+  "status": "completed",
+  "blocked_reason": null,
+  "actual_hours": 4,
+  "completed_at": "2026-05-28"
+}

package/specs/quiver-v35-compact-dashboard-version-ux/EVIDENCE_REPORT.md

@@ -0,0 +1,43 @@
+# Evidence Report - Quiver v35 Compact Dashboard and Version UX
+
+## Status
+
+Implementation, documentation, tests, package smoke, and cross-platform smoke completed. No npm publication is part of this spec.
+
+## Evidence Log
+
+| Date | Slice | Evidence | Result |
+|---|---|---|---|
+| 2026-05-28 | slice-00-foundation-and-doc-router | Created spec package, slices, execution briefs, closure brief templates, status, execution plan, and PR body. | Completed |
+| 2026-05-28 | slice-00-foundation-and-doc-router | `node -e "const fs=require('fs'); for (const f of process.argv.slice(1)) JSON.parse(fs.readFileSync(f,'utf8')); console.log('slice json ok')" specs/quiver-v35-compact-dashboard-version-ux/slices/*/slice.json` | Passed |
+| 2026-05-28 | slice-00-foundation-and-doc-router | `node bin/create-quiver.js spec validate specs/quiver-v35-compact-dashboard-version-ux` | Passed |
+| 2026-05-28 | slice-00-foundation-and-doc-router | `git diff --check` | Passed |
+| 2026-05-28 | slice-01-dashboard-cli-contract | Added dashboard-scoped `--details`, `--section <name>`, and `--limit <n>` parsing/validation plus JSON-safe errors. | Completed |
+| 2026-05-28 | slice-02-dashboard-compact-renderer | Implemented compact default dashboard renderer with summary, next command, counts, truncation, and detail inspection hints. | Completed |
+| 2026-05-28 | slice-03-dashboard-details-sections | Implemented `dashboard --details` and focused sections for overview, specs, slices, blockers, warnings, agents, approvals, runs, active-slice, and next-steps. | Completed |
+| 2026-05-28 | slice-04-version-command | Added `version` and `version --json`, Quiver ASCII banner, palette coloring, no-color handling, package-manager detection, and semver-only `--version` preservation. | Completed |
+| 2026-05-28 | slice-05-docs-help-generated-guidance | Updated CLI help, `docs/reference/commands.md`, `docs/CLI_UX_GUIDE.md`, `README_FOR_AI.md`, generated docs guidance, and `quiver:version` generated script. | Completed |
+| 2026-05-28 | slice-05-docs-help-generated-guidance | Root `docs/INDEX.md` decision: not added in this repo because only `docs/INDEX.md.template` exists and generated projects already receive `docs/INDEX.md`; package validation confirms no unintended package-content change. | Passed |
+| 2026-05-28 | slice-06-tests-smokes-release-readiness | `node --check src/create-quiver/lib/version.js && node --check src/create-quiver/lib/dashboard.js && node --check src/create-quiver/index.js && node --check scripts/ci/smoke-cross-platform.js` | Passed |
+| 2026-05-28 | slice-06-tests-smokes-release-readiness | `node --test tests/lib/dashboard.test.js tests/commands/dashboard.test.js tests/commands/cli-contract.test.js tests/lib/version.test.js tests/lib/cli-theme.test.js tests/lib/init-layout.test.js tests/lib/init-docs.test.js` | Passed |
+| 2026-05-28 | slice-06-tests-smokes-release-readiness | `node --test tests/**/*.test.js` | Passed: 523 tests |
+| 2026-05-28 | slice-06-tests-smokes-release-readiness | `npm run package:quiver` | Passed: `create-quiver-0.15.2.tgz` |
+| 2026-05-28 | slice-06-tests-smokes-release-readiness | `npm run smoke:create-quiver` | Passed |
+| 2026-05-28 | slice-07-package-and-cross-platform-smoke | Installed tarball smoke validates `create-quiver --version`, `create-quiver version`, `create-quiver version --json`, `quiver version`, `dashboard`, and `dashboard --json`. | Passed |
+| 2026-05-28 | slice-07-package-and-cross-platform-smoke | `node scripts/ci/smoke-cross-platform.js` | Passed |
+| 2026-05-28 | slice-07-package-and-cross-platform-smoke | `npx create-quiver spec validate specs/quiver-v35-compact-dashboard-version-ux --strict` | Passed |
+| 2026-05-28 | slice-07-package-and-cross-platform-smoke | `git diff --check` | Passed |
+
+## Required Final Validation
+
+- [x] `node --test tests/**/*.test.js`
+- [x] `git diff --check`
+- [x] `npx create-quiver spec validate specs/quiver-v35-compact-dashboard-version-ux --strict`
+- [x] `npm run package:quiver`
+- [x] `npm run smoke:create-quiver`
+- [x] Package-installed smoke for `create-quiver` and `quiver` binaries
+- [x] `node scripts/ci/smoke-cross-platform.js`
+
+## Notes
+
+No npm publication is part of this spec. Cross-platform smoke was executed on the local macOS environment; the script contains Windows path and npm command guards but was not run on a native Windows host in this turn.

package/specs/quiver-v35-compact-dashboard-version-ux/EXECUTION_PLAN.md

@@ -0,0 +1,85 @@
+# Execution Plan - Quiver v35 Compact Dashboard and Version UX
+
+## Execution Order
+
+```mermaid
+flowchart TD
+    S00[slice-00: Foundation and doc router]
+    S01[slice-01: Dashboard CLI contract]
+    S02[slice-02: Compact renderer]
+    S03[slice-03: Details and sections]
+    S04[slice-04: Version command]
+    S05[slice-05: Docs and guidance]
+    S06[slice-06: Tests and readiness]
+    S07[slice-07: Package and cross-platform smoke]
+
+    S00 --> S01
+    S01 --> S02
+    S01 --> S03
+    S01 --> S04
+    S02 --> S03
+    S02 --> S05
+    S03 --> S05
+    S04 --> S05
+    S05 --> S06
+    S06 --> S07
+```
+
+## Waves
+
+### Wave 0 - Foundation
+
+1. `slice-00-foundation-and-doc-router`
+
+Creates the approved spec package only. No product code changes.
+
+### Wave 1 - Public Contract
+
+1. `slice-01-dashboard-cli-contract`
+
+Defines dashboard flags, invalid combinations, JSON-safe errors, and parser/routing behavior before render changes.
+
+### Wave 2 - Human UX
+
+1. `slice-02-dashboard-compact-renderer`
+2. `slice-04-version-command`
+
+These can run after `slice-01` if the implementers coordinate shared CLI theme/router changes.
+
+### Wave 3 - Deep Inspection
+
+1. `slice-03-dashboard-details-sections`
+
+Depends on the compact renderer and CLI contract so section output does not fork semantics.
+
+### Wave 4 - Docs
+
+1. `slice-05-docs-help-generated-guidance`
+
+Runs after command behavior stabilizes.
+
+### Wave 5 - Validation
+
+1. `slice-06-tests-smokes-release-readiness`
+2. `slice-07-package-and-cross-platform-smoke`
+
+`slice-07` closes package-installed and cross-platform validation after focused tests and docs are stable.
+
+## Parallel Safety Notes
+
+- `slice-01` is not parallel-safe because it defines parser and command contracts.
+- `slice-02` and `slice-04` may run in parallel only after `slice-01`, because one touches dashboard rendering and the other touches version output.
+- `slice-03` waits for `slice-02` so detail/section renderers share formatting primitives.
+- `slice-05` waits for behavior to stabilize.
+- `slice-06` and `slice-07` are closeout-oriented and should not be over-parallelized.
+
+## Recommended Commit Order
+
+1. `docs: add v35 compact dashboard and version ux spec`
+2. `feat: add dashboard view flags contract`
+3. `feat: compact dashboard human output`
+4. `feat: add dashboard detail and section views`
+5. `feat: add quiver version command`
+6. `docs: document dashboard and version ux`
+7. `test: validate compact dashboard and version ux`
+8. `test: validate package-installed cli ux`