create-quiver 0.7.0 → 0.8.0

package/specs/quiver-v17-orchestration-foundation/slices/slice-01-ci-matrix-verified/slice.json

@@ -0,0 +1,68 @@
+{
+  "slice_id": "slice-01-ci-matrix-verified",
+  "ticket": "QUIVER-01",
+  "type": "ops",
+  "title": "Cross-Platform CI Matrix Verified",
+  "objective": "Ensure `.github/workflows/ci.yml` runs on macOS, Linux, and Windows and is green on all three, so every subsequent orchestration command can rely on the matrix instead of adding its own.",
+  "description": "Every command in v18 through v22 is Node-first and must behave identically on macOS, Linux, and Windows. Today some tests assume POSIX shells, `/` path separators, or UTF-8 output. This slice either confirms the existing CI matrix already covers the three OS targets or introduces the missing job(s), and adds a negative test that fails on Windows if paths are hardcoded with `/`.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "ci-matrix-verified",
+    "branch_name": "feature/QUIVER-01-ci-matrix-verified"
+  },
+  "must": [
+    "Confirm or add `macos-latest`, `ubuntu-latest`, and `windows-latest` entries in the `.github/workflows/ci.yml` matrix",
+    "Add a guard test that fails on Windows when a path in the codebase is hardcoded with `/` instead of `path.sep`",
+    "Document the cross-platform authoring rules in `docs/SUPPORT_MATRIX.md` (no shell invocations for logic, `path.join`, EOL handling, JSON-first, TTY-aware color, Unicode opt-in)",
+    "Create `docs/COMMANDS.md` with a header table and a reserved row for `quiver:plan`",
+    "Add a `CHANGELOG.md` entry noting the foundation for orchestration commands"
+  ],
+  "not_included": [
+    "Introducing any new user-facing command",
+    "Building `lib/slice-graph.js` (handled in slice-02)",
+    "Validating `depends_on` (handled in slice-03)",
+    "Removing existing Bash wrappers (legacy path remains until runtime slices land)"
+  ],
+  "acceptance": [
+    "`.github/workflows/ci.yml` shows a matrix with `macos-latest`, `ubuntu-latest`, and `windows-latest`",
+    "The matrix is green on all three OS in the PR that lands this slice",
+    "A deliberate regression using `/` hardcoded paths fails on Windows CI and passes after fixing",
+    "`docs/SUPPORT_MATRIX.md` contains a section named `Cross-Platform Authoring Rules` with the six rules",
+    "`docs/COMMANDS.md` exists with a table header `| Command | Purpose | OS | Since |` and at least one reserved row for `quiver:plan`"
+  ],
+  "files": [
+    ".github/workflows/ci.yml",
+    "docs/SUPPORT_MATRIX.md",
+    "docs/COMMANDS.md",
+    "CHANGELOG.md",
+    "specs/quiver-v17-orchestration-foundation/SPEC.md",
+    "specs/quiver-v17-orchestration-foundation/STATUS.md",
+    "specs/quiver-v17-orchestration-foundation/EVIDENCE_REPORT.md",
+    "specs/quiver-v17-orchestration-foundation/slices/slice-01-ci-matrix-verified/slice.json"
+  ],
+  "tests": [
+    "node -e \"const fs=require('fs'); const y=fs.readFileSync('.github/workflows/ci.yml','utf8'); if(!y.includes('macos-latest')||!y.includes('ubuntu-latest')||!y.includes('windows-latest')) process.exit(1)\"",
+    "test -f docs/SUPPORT_MATRIX.md",
+    "test -f docs/COMMANDS.md",
+    "git diff --check"
+  ],
+  "documentation": [
+    "docs/SUPPORT_MATRIX.md",
+    "docs/COMMANDS.md",
+    "CHANGELOG.md"
+  ],
+  "dependencies": [],
+  "assumptions": [
+    "GitHub Actions continues to offer `windows-latest` runners at no extra cost",
+    "Existing tests are shell-agnostic enough to pass on Windows after the matrix flip",
+    "A single smoke on each OS is sufficient; no need for full matrix fan-out per test"
+  ],
+  "estimated_hours": 4,
+  "actual_hours": null,
+  "status": "completed",
+  "blocked_reason": null,
+  "ready_at": null,
+  "started_at": null,
+  "completed_at": "2026-04-23T00:00:00Z"
+}

package/specs/quiver-v17-orchestration-foundation/slices/slice-02-slice-graph-library/slice.json

@@ -0,0 +1,65 @@
+{
+  "slice_id": "slice-02-slice-graph-library",
+  "ticket": "QUIVER-02",
+  "type": "feat",
+  "title": "Slice Graph Library",
+  "objective": "Introduce `src/create-quiver/lib/slice-graph.js` as the single shared dependency of every orchestration command, exposing a stable API to read slices, infer dependencies, build a graph, topologically sort, compute parallel levels, and detect file conflicts.",
+  "description": "All v18–v22 commands must read `slice.json` files, understand ordering, and identify parallel-safe groups. Without a library each command re-implements this. This slice builds the library, includes heuristic dependency inference (numeric order within a spec, intersected with `files[]` overlap) and honors explicit `depends_on` when present. The library is pure Node and deterministic so it works identically on all three OS.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "slice-graph-library",
+    "branch_name": "feature/QUIVER-02-slice-graph-library"
+  },
+  "must": [
+    "Create `src/create-quiver/lib/slice-graph.js` exporting `readAllSlices`, `inferDependencies`, `buildGraph`, `topoSort`, `computeLevels`, `detectFileConflicts`",
+    "Implement heuristic dependency inference: within a spec, `slice-NN` depends on any lower-numbered sibling that shares at least one entry in `files[]`",
+    "Honor explicit `depends_on` in `slice.json` when present (overrides heuristic)",
+    "Detect cycles in `topoSort` and throw a typed error with the cycle path",
+    "Implement `computeLevels` as a repeated Kahn pass: each level is the set of nodes with no pending predecessors",
+    "Implement `detectFileConflicts` by grouping slices in a level whose `files[]` intersect",
+    "Add unit tests under `tests/lib/slice-graph.test.js` covering: empty repo, single spec, cross-spec deps, explicit `depends_on`, cycle, disjoint vs intersecting files",
+    "Document the API at the top of `src/create-quiver/lib/slice-graph.js` and cross-link from `docs/COMMANDS.md`"
+  ],
+  "not_included": [
+    "Any CLI-facing command (handled from slice-18 onward)",
+    "Validating `depends_on` at `check-slice` time (handled in slice-03)",
+    "Rendering trees, mermaid, or DOT output (handled in v18)",
+    "Enforcing parallelism at runtime (library is advisory)"
+  ],
+  "acceptance": [
+    "`require('./src/create-quiver/lib/slice-graph')` exposes all six documented functions",
+    "`readAllSlices('.')` against the Quiver repo returns a non-zero slice count and does not throw",
+    "Unit tests pass on macOS, Linux, and Windows",
+    "A test fixture with a cycle causes `topoSort` to throw an error whose message includes every node in the cycle",
+    "A test fixture with two slices that touch disjoint files places them at the same level"
+  ],
+  "files": [
+    "src/create-quiver/lib/slice-graph.js",
+    "tests/lib/slice-graph.test.js",
+    "docs/COMMANDS.md",
+    "specs/quiver-v17-orchestration-foundation/slices/slice-02-slice-graph-library/slice.json"
+  ],
+  "tests": [
+    "node --test tests/lib/slice-graph.test.js",
+    "node -e \"const g=require('./src/create-quiver/lib/slice-graph'); if(g.readAllSlices('.').length===0) process.exit(1)\"",
+    "git diff --check"
+  ],
+  "documentation": [
+    "src/create-quiver/lib/slice-graph.js",
+    "docs/COMMANDS.md"
+  ],
+  "dependencies": ["slice-01-ci-matrix-verified"],
+  "assumptions": [
+    "Heuristic inference by numeric order + file overlap is accurate enough for existing specs; edge cases escalate to explicit `depends_on`",
+    "`node --test` is available in the Node version required by the project",
+    "Reading every `slice.json` at startup is cheap enough not to warrant caching yet"
+  ],
+  "estimated_hours": 5,
+  "actual_hours": null,
+  "status": "completed",
+  "blocked_reason": null,
+  "ready_at": "2026-04-23T00:00:00Z",
+  "started_at": "2026-04-23T00:00:00Z",
+  "completed_at": "2026-04-23T00:00:00Z"
+}

package/specs/quiver-v17-orchestration-foundation/slices/slice-03-depends-on-validation/slice.json

@@ -0,0 +1,72 @@
+{
+  "slice_id": "slice-03-depends-on-validation",
+  "ticket": "QUIVER-03",
+  "type": "feat",
+  "title": "Optional `depends_on` Validation",
+  "objective": "Extend `check-slice` so when a slice declares `depends_on` or `parallel_safe` the values are validated against the real filesystem, preventing typos, dead references, and missing justifications from reaching execution.",
+  "description": "Heuristic inference covers most cases, but specs that need explicit dependencies (cross-spec, non-sequential, or overriding file-overlap inference) should be validated up front. This slice adds three validation rules to `check-slice`: each `depends_on` target must resolve to an existing `slice.json`; the set of declared deps must be acyclic with the graph built so far; and `parallel_safe: \"never\"` requires a non-empty `parallel_safe_reason`.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "depends-on-validation",
+    "branch_name": "feature/QUIVER-03-depends-on-validation"
+  },
+  "must": [
+    "Extend `check-slice` to validate optional `depends_on` entries point to existing `<spec-slug>/<slice-id>` combinations",
+    "Detect cycles introduced by newly declared `depends_on` using the shared slice graph library",
+    "Require a non-empty `parallel_safe_reason` when `parallel_safe: \"never\"` is declared",
+    "Update `specs/[project-name]/slice-template/slice.json` with the new optional fields, commented out",
+    "Update `docs/COMMANDS.md` with a paragraph describing the new validations",
+    "Add a `CHANGELOG.md` entry"
+  ],
+  "not_included": [
+    "Enforcing `depends_on` at `start-slice` time beyond the existing checks",
+    "Auto-filling `depends_on` from heuristic inference (commands can do this read-only)",
+    "Introducing a full JSON Schema (only these fields are validated)"
+  ],
+  "acceptance": [
+    "A slice with `depends_on: [\"nonexistent/slice-99\"]` causes `check-slice` to exit non-zero with a clear message naming the missing path",
+    "A slice that creates a cycle with an existing declaration causes `check-slice` to exit non-zero and print the cycle",
+    "A slice with `parallel_safe: \"never\"` and no `parallel_safe_reason` fails; adding a reason makes it pass",
+    "A slice with no `depends_on` field continues to pass without changes",
+    "The slice template shows the new fields as commented-out examples"
+  ],
+  "files": [
+    "src/create-quiver/lib/json.js",
+    "src/create-quiver/lib/readiness.js",
+    "src/create-quiver/lib/slice-graph.js",
+    "src/create-quiver/lib/slice.js",
+    "specs/[project-name]/slice-template/slice.json",
+    "docs/COMMANDS.md",
+    "CHANGELOG.md",
+    "tests/lib/check-slice.test.js",
+    "scripts/check-slice-readiness.sh",
+    "scripts/ci/smoke-create-quiver.sh",
+    "scripts/ci/smoke-cross-platform.js",
+    "scripts/ci/smoke-init-docs.sh",
+    ".github/workflows/ci.yml",
+    "specs/quiver-v17-orchestration-foundation/slices/slice-03-depends-on-validation/slice.json"
+  ],
+  "tests": [
+    "node --test tests/lib/check-slice.test.js",
+    "git diff --check"
+  ],
+  "documentation": [
+    "docs/COMMANDS.md",
+    "CHANGELOG.md",
+    "specs/[project-name]/slice-template/slice.json"
+  ],
+  "dependencies": ["slice-02-slice-graph-library"],
+  "assumptions": [
+    "`check-slice` already exists as the validation entry point",
+    "Slice IDs across specs are unique enough to form `<spec-slug>/<slice-id>` keys",
+    "The validation implementation lives in `src/create-quiver/lib/readiness.js` or an equivalent shared gate module"
+  ],
+  "estimated_hours": 2,
+  "actual_hours": 2,
+  "status": "completed",
+  "blocked_reason": null,
+  "ready_at": "2026-04-23T00:00:00Z",
+  "started_at": "2026-04-23T00:00:00Z",
+  "completed_at": "2026-04-23T00:00:00Z"
+}

package/specs/quiver-v18-slice-orchestration/EVIDENCE_REPORT.md

@@ -0,0 +1,38 @@
+# Quiver v0.18 Evidence Report
+
+**Spec:** quiver-v18-slice-orchestration
+**Date:** 2026-04-24
+**Status:** Completed
+
+## Summary
+
+This spec delivers the three user-facing orchestration commands: `plan`, `graph`, and `next`. All are read-only by default; `next --auto-start` is the only path that mutates state, and only under TTY confirmation. The measurable outcome is that a maintainer coordinating multiple agents can identify the correct next slice and the current parallel-safe lots without running custom scripts.
+
+## Slice Evidence
+
+| Slice | Status | Evidence |
+|-------|--------|----------|
+| slice-01 | Completed | `quiver:plan` prints the topological order of pending slices; `--json` is a valid parseable payload; critical path is calculated; docs/examples/plan.md exists |
+| slice-02 | Completed | `quiver:graph --format tree` prints an ASCII tree; `--show-conflicts` flags intersecting files; ASCII fallback works without UTF-8 locale |
+| slice-03 | Completed | `quiver:graph --format mermaid` prints a fenced Mermaid flowchart; `--format dot` prints valid DOT source and the docs show both formats |
+| slice-04 | Completed | `quiver:next` prints one slice; `--all-ready` prints the whole first level; `--auto-start` requires confirmation on TTY and refuses on non-TTY |
+
+## Required Final Evidence
+
+- `npx create-quiver plan` returns exit 0 on the Quiver repo and prints the expected number of pending slices
+- `npx create-quiver plan --json` returns valid JSON with `plan`, `critical_path`, and `total_hours` keys
+- `npx create-quiver graph --format tree` renders an ASCII tree on macOS, Linux, and Windows CI
+- `npx create-quiver graph --format mermaid` output pastes directly into a GitHub issue comment and renders
+- `npx create-quiver next` prints a slice without side effects; running it twice returns the same slice
+- `npx create-quiver next --all-ready` prints every slice in the first unblocked level
+- `npx create-quiver next --auto-start` on a TTY prompts before running `start-slice`; on non-TTY returns a non-zero exit
+- `npx create-quiver next --json` returns valid JSON with `next` and `all_ready`
+- `docs/examples/plan.md`, `docs/examples/graph.md`, and `docs/examples/next.md` contain real input and output
+- `docs/COMMANDS.md` has rows for all three commands with OS columns showing macOS/Linux/Windows
+- `README.md` "Project NPM Scripts" lists `quiver:plan`, `quiver:graph`, `quiver:next`
+
+## Validation Checkpoint (Post-Merge)
+
+- `quiver:plan` is used at least once per day for one week of real work on Quiver
+- At least one external user reports whether `quiver:graph --format mermaid` matches their expectations
+- Decision to scope v19 (`status`, `estimate`, `lint-spec`) is made only after this evidence is collected

package/specs/quiver-v18-slice-orchestration/SPEC.md

@@ -0,0 +1,91 @@
+# Quiver v0.18 - Slice Orchestration
+
+**Date:** 2026-04-23
+**Status:** Draft
+
+Slice numbering resets here: this spec starts at `slice-01` and does not continue any previous spec's numbering.
+
+## Objective
+
+Ship the three commands that answer the core multi-agent question "what should I work on now, and what can run in parallel?": `quiver:plan` (sequential order), `quiver:graph` (dependency and parallelism tree), and `quiver:next` (single ready slice). Together they let a maintainer coordinate planning-tier and execution-tier models without guessing.
+
+## Context
+
+With the v17 foundation in place (CI matrix, shared graph library, optional `depends_on` validation), the user-facing commands are thin wrappers around the library. The main deliverables here are the output formats, flag ergonomics, and documentation. `quiver:next` never takes destructive action by default: it prints a suggestion and only optionally runs `start-slice` behind a confirmation prompt.
+
+## Scope
+
+### Included
+
+- `quiver:plan` — topological order of pending slices across all specs, with critical path and total hours
+- `quiver:graph` — dependency tree with parallel lots, conflict detection, and multiple output formats
+- `quiver:next` — next ready slice (or all ready slices), with optional `--auto-start` behind a TTY confirmation
+- Entries in `docs/COMMANDS.md`, examples in `docs/examples/`, `package.json` `quiver:*` scripts, `README.md` and `README_FOR_AI.md` updates for each command
+- `CHANGELOG.md` entries
+
+### Excluded
+
+- A status dashboard (deferred to v19)
+- Token cost estimation (deferred to v20)
+- Archiving completed specs (deferred to v21)
+- Automatic locking of parallel slices (commands are advisory)
+
+## Commands
+
+### `quiver:plan`
+
+Topological order across all specs with pending slices. Output modes:
+
+- Default: human-readable table with `[N]  TICKET  spec/slice  title  hours  status`
+- `--json`: `{ plan: Slice[], critical_path: SliceId[], total_hours: number }`
+- `--only-ready`: filter to slices with no pending dependencies
+- `--spec <slug>`: restrict to a single spec
+
+Exit codes: 0 ok, 1 cycle detected, 2 invalid repo state.
+
+### `quiver:graph`
+
+Dependency and parallelism view. Output modes:
+
+- `--format tree` (default): ASCII tree grouped by level, with `⚠` markers on file conflicts (`+--` fallback without Unicode)
+- `--format mermaid`: Mermaid `flowchart TD` block pastable into GitHub
+- `--format dot`: Graphviz DOT source
+- `--show-conflicts`: highlight intersections of `files[]`
+- `--level <n>`: focus on one topological level
+- `--json`: structured output
+
+### `quiver:next`
+
+Single-slice suggestion. Output modes:
+
+- Default: top-1 ready slice plus the exact `start-slice` command to copy
+- `--all-ready`: list every slice at the first unblocked level
+- `--auto-start`: prompt for confirmation (requires TTY) and run `start-slice` on accept
+- `--json`: `{ next: Slice | null, all_ready: Slice[] }`
+
+## Slices
+
+| Slice | Title | Status | Spec |
+|-------|-------|--------|------|
+| 01 | `quiver:plan` Command | Completed | [slice-01](./slices/slice-01-plan-command/slice.json) |
+| 02 | `quiver:graph` MVP Tree | Completed | [slice-02](./slices/slice-02-graph-mvp-tree/slice.json) |
+| 03 | `quiver:graph` Extended Formats | Completed | [slice-03](./slices/slice-03-graph-extended-formats/slice.json) |
+| 04 | `quiver:next` Command | Completed | [slice-04](./slices/slice-04-next-command/slice.json) |
+
+## Definition of Done
+
+- `npx create-quiver plan` prints the sequential plan and `--json` produces a valid parseable object
+- `npx create-quiver graph --format tree` prints a correct tree; `--show-conflicts` marks shared files
+- `npx create-quiver graph --format mermaid` output pastes directly into a GitHub markdown block
+- `npx create-quiver next` prints the next ready slice without side effects
+- `npx create-quiver next --all-ready` prints every ready slice in the first unblocked level
+- `npx create-quiver next --auto-start` requires confirmation on TTY and refuses on non-TTY
+- `npx create-quiver next --json` produces a valid parseable object with `next` and `all_ready`
+- Each command has a `docs/examples/<command>.md` page with input and representative output
+- `docs/COMMANDS.md` has rows for all three commands with OS support and example link
+- `README.md` "Project NPM Scripts" lists `quiver:plan`, `quiver:graph`, `quiver:next`
+- All three commands run green on macOS, Linux, and Windows in CI
+
+## Validation Checkpoint
+
+Before v19 is started, `quiver:plan` must be used at least once per day for one week during real work on Quiver itself. If the maintainer does not reach for it, v19 is rescoped before it is written.

package/specs/quiver-v18-slice-orchestration/STATUS.md

@@ -0,0 +1,33 @@
+# Quiver v0.18 Spec Status
+
+**Spec:** quiver-v18-slice-orchestration
+**Last updated:** 2026-04-24
+
+Slice numbering is local to this spec. The first slice is `slice-01`.
+
+## Status
+
+| Slice | Title | Status | PR | Estimated hours | Actual hours |
+|-------|-------|--------|----|-----------------|--------------|
+| slice-01 | `quiver:plan` Command | Completed | https://github.com/FabriJuncal/quiver/pull/49 | 5 | 5 |
+| slice-02 | `quiver:graph` MVP Tree | Completed | https://github.com/FabriJuncal/quiver/pull/50 | 4 | 4 |
+| slice-03 | `quiver:graph` Extended Formats | Completed | https://github.com/FabriJuncal/quiver/pull/51 | 2 | 2 |
+| slice-04 | `quiver:next` Command | Completed | https://github.com/FabriJuncal/quiver/pull/52 | 3 | 4 |
+
+## Progress
+
+- Completed slices: 4 / 4
+- Estimated hours: 14
+- Actual hours: 15
+
+## Blockers
+
+| Slice | Blocker | Since | Action needed |
+|-------|---------|-------|---------------|
+| - | - | - | - |
+
+## Dependencies
+
+- All slices depend on `quiver-v17-orchestration-foundation/slice-02-slice-graph-library`
+- slice-03 depends on slice-02 (extends graph output with new formats)
+- slice-04 depends on slice-01 (reuses plan ordering for "next")

package/specs/quiver-v18-slice-orchestration/slices/slice-01-plan-command/slice.json

@@ -0,0 +1,79 @@
+{
+  "slice_id": "slice-01-plan-command",
+  "ticket": "QUIVER-01",
+  "type": "feat",
+  "title": "`quiver:plan` Command",
+  "objective": "Ship `npx create-quiver plan` and `quiver:plan` that print the sequential execution order of all pending slices, the critical path, and the total hours, with `--json` for tooling integration.",
+  "description": "The plan command answers \"what do I work on next, and in what order?\" across every spec in the repo. It reads all `slice.json` files, drops completed and skipped slices, builds the dependency graph using the v17 library, topologically sorts the remaining nodes, and prints the result. The command is read-only, deterministic, and cross-platform.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "plan-command",
+    "branch_name": "feature/QUIVER-01-plan-command"
+  },
+  "must": [
+    "Create `src/create-quiver/commands/plan.js` that wires up `readAllSlices`, `inferDependencies`, `buildGraph`, and `topoSort` from the v17 library",
+    "Implement critical path detection by walking the longest-hours chain in the DAG",
+    "Implement `--spec <slug>`, `--only-ready`, and `--json` flags",
+    "Register `plan` in `bin/create-quiver.js` and add `quiver:plan` to `package.json`",
+    "Print human output with ASCII by default, Unicode only when `process.env.LANG` includes `UTF-8` or `--unicode` is passed",
+    "Respect `NO_COLOR` and `!isTTY` when deciding whether to emit colors",
+    "Create `docs/examples/plan.md` with input and representative output",
+    "Add a `COMMANDS.md` row for plan",
+    "Update `README.md` npm scripts list and `README_FOR_AI.md` reading order if relevant",
+    "Add a `CHANGELOG.md` entry"
+  ],
+  "not_included": [
+    "Auto-starting slices (handled by `next --auto-start`)",
+    "Rendering a graph tree (handled in slice-02)",
+    "Status dashboards (handled in v19)"
+  ],
+  "acceptance": [
+    "`npx create-quiver plan` returns exit 0 and prints a non-empty plan in the Quiver repo",
+    "`npx create-quiver plan --json` produces valid JSON with `plan`, `critical_path`, and `total_hours` fields",
+    "`npx create-quiver plan --only-ready` returns only slices with no pending predecessors",
+    "`npx create-quiver plan --spec quiver-v14-tiered-context-pack` returns only that spec's slices",
+    "Introducing a cycle in a test fixture causes exit code 1 with a message naming the cycle",
+    "Running under `CI=true TERM=dumb NO_COLOR=1` produces ASCII output without color codes",
+    "`docs/examples/plan.md` exists with a real example block",
+    "`docs/COMMANDS.md` has a row naming `plan` with OS support listed"
+  ],
+  "files": [
+    "src/create-quiver/commands/plan.js",
+    "bin/create-quiver.js",
+    "package.json",
+    "docs/examples/plan.md",
+    "docs/COMMANDS.md",
+    "README.md",
+    "README_FOR_AI.md",
+    "CHANGELOG.md",
+    "tests/commands/plan.test.js",
+    "specs/quiver-v18-slice-orchestration/slices/slice-01-plan-command/slice.json"
+  ],
+  "tests": [
+    "node --test tests/commands/plan.test.js",
+    "node bin/create-quiver.js plan --json > /tmp/quiver-plan.json",
+    "node -e \"const p=require('/tmp/quiver-plan.json'); if(!Array.isArray(p.plan)||typeof p.total_hours!=='number') process.exit(1)\"",
+    "git diff --check"
+  ],
+  "documentation": [
+    "docs/examples/plan.md",
+    "docs/COMMANDS.md",
+    "README.md",
+    "README_FOR_AI.md",
+    "CHANGELOG.md"
+  ],
+  "dependencies": ["quiver-v17-orchestration-foundation/slice-02-slice-graph-library"],
+  "assumptions": [
+    "`readAllSlices` is fast enough to run on every invocation without caching",
+    "A single critical-path metric (longest hours chain) is sufficient for now",
+    "Humans reading the default output prefer ASCII over Unicode box-drawing by default"
+  ],
+  "estimated_hours": 5,
+  "actual_hours": 5,
+  "status": "completed",
+  "blocked_reason": null,
+  "ready_at": null,
+  "started_at": null,
+  "completed_at": null
+}

package/specs/quiver-v18-slice-orchestration/slices/slice-02-graph-mvp-tree/slice.json

@@ -0,0 +1,75 @@
+{
+  "slice_id": "slice-02-graph-mvp-tree",
+  "ticket": "QUIVER-02",
+  "type": "feat",
+  "title": "`quiver:graph` MVP Tree",
+  "objective": "Ship `npx create-quiver graph --format tree` and `quiver:graph` that print the dependency tree of pending slices, grouped by parallel level, with optional `--show-conflicts` and `--level <n>` flags.",
+  "description": "Given the library returns levels and conflict groups, this slice focuses on rendering a readable ASCII tree that makes parallel-safe lots obvious. Mermaid and DOT formats are deferred to slice-03; the MVP keeps the surface small. Conflict markers use `⚠` with UTF-8 locale and a plain `!` as fallback.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "graph-mvp-tree",
+    "branch_name": "feature/QUIVER-02-graph-mvp-tree"
+  },
+  "must": [
+    "Create `src/create-quiver/commands/graph.js` with a `--format tree` default",
+    "Render one section per topological level, with slices that can run in parallel listed together",
+    "Mark file conflicts between same-level slices with a conflict symbol and a brief list of shared paths when `--show-conflicts` is set",
+    "Implement `--level <n>` to focus on a single level",
+    "Implement `--json` to emit `{ levels: Slice[][], conflicts: ConflictGroup[] }`",
+    "Register `graph` in `bin/create-quiver.js` and add `quiver:graph` to `package.json`",
+    "Create `docs/examples/graph.md` with input and representative ASCII output",
+    "Add a `docs/COMMANDS.md` row and update `README.md` npm scripts list",
+    "Add a `CHANGELOG.md` entry"
+  ],
+  "not_included": [
+    "Mermaid and DOT formats (handled in slice-03)",
+    "Editing or starting any slice (read-only)",
+    "Rendering file contents; only slice IDs, titles, hours, and shared paths"
+  ],
+  "acceptance": [
+    "`npx create-quiver graph` prints a tree grouped by level with counts of parallel lots",
+    "`npx create-quiver graph --show-conflicts` marks slices that intersect on `files[]`",
+    "`npx create-quiver graph --level 0` prints only the first level",
+    "`npx create-quiver graph --json` produces valid JSON with `levels` and `conflicts` arrays",
+    "Output is ASCII by default; with `LANG=en_US.UTF-8` or `--unicode`, Unicode box-drawing is used",
+    "`docs/examples/graph.md` exists with a real example"
+  ],
+  "files": [
+    "src/create-quiver/commands/graph.js",
+    "src/create-quiver/lib/renderers/tree.js",
+    "bin/create-quiver.js",
+    "package.json",
+    "docs/examples/graph.md",
+    "docs/COMMANDS.md",
+    "README.md",
+    "CHANGELOG.md",
+    "tests/commands/graph.test.js",
+    "specs/quiver-v18-slice-orchestration/slices/slice-02-graph-mvp-tree/slice.json"
+  ],
+  "tests": [
+    "node --test tests/commands/graph.test.js",
+    "node bin/create-quiver.js graph --json > /tmp/quiver-graph.json",
+    "node -e \"const g=require('/tmp/quiver-graph.json'); if(!Array.isArray(g.levels)) process.exit(1)\"",
+    "git diff --check"
+  ],
+  "documentation": [
+    "docs/examples/graph.md",
+    "docs/COMMANDS.md",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "dependencies": ["quiver-v17-orchestration-foundation/slice-02-slice-graph-library", "slice-01-plan-command"],
+  "assumptions": [
+    "Two slices on the same level that intersect on `files[]` are effectively serialized in practice; warning is enough, no hard block",
+    "ASCII tree is readable for repos with fewer than 50 pending slices; larger repos may justify paging later",
+    "Graphviz is not assumed to be installed"
+  ],
+  "estimated_hours": 4,
+  "actual_hours": 4,
+  "status": "completed",
+  "blocked_reason": null,
+  "ready_at": null,
+  "started_at": null,
+  "completed_at": null
+}

package/specs/quiver-v18-slice-orchestration/slices/slice-03-graph-extended-formats/slice.json

@@ -0,0 +1,70 @@
+{
+  "slice_id": "slice-03-graph-extended-formats",
+  "ticket": "QUIVER-03",
+  "type": "feat",
+  "title": "`quiver:graph` Extended Formats (Mermaid, DOT)",
+  "objective": "Extend `quiver:graph` with `--format mermaid` and `--format dot` so dependency graphs can be pasted into GitHub markdown (Mermaid) or rendered with Graphviz (DOT) for documentation and slide decks.",
+  "description": "Once the ASCII tree is working, adding machine-renderable formats is cheap: both are templated serializations of the same levels and conflicts data. Mermaid is the primary target for PR descriptions; DOT unlocks Graphviz pipelines and high-resolution exports. Neither format requires external binaries to be present; Graphviz is only needed by the end user if they want to render DOT.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "graph-extended-formats",
+    "branch_name": "feature/QUIVER-03-graph-extended-formats"
+  },
+  "must": [
+    "Add a Mermaid renderer at `src/create-quiver/lib/renderers/mermaid.js` producing a `flowchart TD` block",
+    "Add a DOT renderer at `src/create-quiver/lib/renderers/dot.js` producing valid `digraph` source",
+    "Wire both renderers to `quiver:graph --format mermaid` and `quiver:graph --format dot`",
+    "Update `docs/examples/graph.md` with sample Mermaid and DOT outputs and a note about GitHub's Mermaid support",
+    "Add a `docs/COMMANDS.md` note covering the new formats",
+    "Add a `CHANGELOG.md` entry"
+  ],
+  "not_included": [
+    "Auto-rendering DOT to PNG (Graphviz binary not assumed)",
+    "Interactive web visualizer",
+    "Per-spec subgraphs in Mermaid (flat layout is enough for now)"
+  ],
+  "acceptance": [
+    "`npx create-quiver graph --format mermaid` prints a valid `flowchart TD` block starting with ```` ```mermaid ```` fence",
+    "Pasting the output into a GitHub markdown preview renders the graph",
+    "`npx create-quiver graph --format dot` prints valid DOT source starting with `digraph`",
+    "`echo $(node bin/create-quiver.js graph --format dot) | dot -Tsvg` produces SVG when Graphviz is installed (test runs conditionally)",
+    "`docs/examples/graph.md` shows both formats"
+  ],
+  "files": [
+    "src/create-quiver/commands/graph.js",
+    "src/create-quiver/lib/renderers/mermaid.js",
+    "src/create-quiver/lib/renderers/dot.js",
+    "docs/examples/graph.md",
+    "docs/COMMANDS.md",
+    "CHANGELOG.md",
+    "tests/lib/renderers/mermaid.test.js",
+    "tests/lib/renderers/dot.test.js",
+    "specs/quiver-v18-slice-orchestration/slices/slice-03-graph-extended-formats/slice.json"
+  ],
+  "tests": [
+    "node --test tests/lib/renderers/mermaid.test.js",
+    "node --test tests/lib/renderers/dot.test.js",
+    "node bin/create-quiver.js graph --format mermaid | head -n 1 | grep -q mermaid",
+    "node bin/create-quiver.js graph --format dot | head -n 1 | grep -q digraph",
+    "git diff --check"
+  ],
+  "documentation": [
+    "docs/examples/graph.md",
+    "docs/COMMANDS.md",
+    "CHANGELOG.md"
+  ],
+  "dependencies": ["slice-02-graph-mvp-tree"],
+  "assumptions": [
+    "GitHub continues to render Mermaid in markdown",
+    "DOT identifiers sanitized from slice IDs are stable enough not to collide",
+    "Users who want PNG/SVG have Graphviz installed locally; Quiver does not bundle it"
+  ],
+  "estimated_hours": 2,
+  "actual_hours": 2,
+  "status": "completed",
+  "blocked_reason": null,
+  "ready_at": null,
+  "started_at": null,
+  "completed_at": "2026-04-24T00:00:00Z"
+}