create-quiver 0.6.0 → 0.8.0

package/specs/quiver-v16-handoff-contract/slices/slice-02-check-handoff-command/slice.json

@@ -0,0 +1,70 @@
+{
+  "slice_id": "slice-02-check-handoff-command",
+  "ticket": "QUIVER-02",
+  "type": "feature",
+  "title": "Check Handoff Command",
+  "objective": "Add a lightweight validator for HANDOFF artifacts so the contract is machine-checkable.",
+  "description": "Once the handoff contract exists, Quiver should be able to validate that a concrete handoff lives in the canonical location and contains the required sections. This slice adds `create-quiver check-handoff <path>` with clear failures for missing files, wrong placement, and missing headings.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "check-handoff-command",
+    "branch_name": "feature/QUIVER-02-check-handoff-command"
+  },
+  "must": [
+    "Add `create-quiver check-handoff <path>` to the CLI",
+    "Fail non-zero when the target file does not exist",
+    "Fail non-zero when the target file is not located at the canonical `specs/<spec-slug>/HANDOFF.md` path",
+    "Fail non-zero when any required section heading is missing",
+    "Allow extra sections as long as the required headings are present",
+    "Add smoke coverage for both passing and failing examples"
+  ],
+  "not_included": [
+    "Automatic handoff creation",
+    "Doctor warnings",
+    "Semantic validation of handoff quality"
+  ],
+  "acceptance": [
+    "A valid `specs/<spec-slug>/HANDOFF.md` passes `create-quiver check-handoff <path>`",
+    "A missing handoff path exits non-zero with a clear message",
+    "A handoff missing one required section exits non-zero and names the missing heading",
+    "A handoff outside the canonical `specs/<spec-slug>/HANDOFF.md` path exits non-zero with a placement error",
+    "Smoke coverage proves both valid and invalid cases"
+  ],
+  "files": [
+    "src/create-quiver/index.js",
+    "src/create-quiver/lib/handoff.js",
+    "scripts/ci/smoke-cross-platform.js",
+    "README.md",
+    "README_FOR_AI.md",
+    "specs/quiver-v16-handoff-contract/SPEC.md",
+    "specs/quiver-v16-handoff-contract/STATUS.md",
+    "specs/quiver-v16-handoff-contract/EVIDENCE_REPORT.md",
+    "specs/quiver-v16-handoff-contract/slices/slice-02-check-handoff-command/slice.json"
+  ],
+  "tests": [
+    "node -c src/create-quiver/index.js",
+    "node -c src/create-quiver/lib/handoff.js",
+    "node bin/create-quiver.js check-handoff /tmp/quiver-valid-handoff/specs/sample-spec/HANDOFF.md",
+    "node bin/create-quiver.js check-handoff /tmp/quiver-invalid-handoff/specs/sample-spec/HANDOFF.md",
+    "git diff --check"
+  ],
+  "documentation": [
+    "README.md",
+    "README_FOR_AI.md"
+  ],
+  "dependencies": [
+    "slice-01-handoff-template-and-contract"
+  ],
+  "assumptions": [
+    "Structure validation is enough for the first version; semantic quality can stay a human review concern",
+    "The validator should enforce canonical placement so the contract stays discoverable"
+  ],
+  "estimated_hours": 3,
+  "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-v16-handoff-contract/slices/slice-03-handoff-scaffold-optional/slice.json

@@ -0,0 +1,67 @@
+{
+  "slice_id": "slice-03-handoff-scaffold-optional",
+  "ticket": "QUIVER-03",
+  "type": "feature",
+  "title": "Handoff Scaffold Optional",
+  "objective": "Optionally add a scaffold command for handoffs after the contract and validator already exist.",
+  "description": "If the handoff contract proves useful, Quiver can add a convenience command to create `specs/<spec-slug>/HANDOFF.md` from the canonical template. This slice stays intentionally small and must not become a larger orchestration feature.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "handoff-scaffold-optional",
+    "branch_name": "feature/QUIVER-03-handoff-scaffold-optional"
+  },
+  "must": [
+    "Add `create-quiver new-handoff <spec-slug>`",
+    "Generate `specs/<spec-slug>/HANDOFF.md` from `specs/[project-name]/HANDOFF.md.template`",
+    "Refuse to overwrite an existing handoff unless a future explicit force flag is added in another spec",
+    "Keep the scaffold aligned with the validator contract and required headings",
+    "Document the command as optional convenience rather than a mandatory workflow step"
+  ],
+  "not_included": [
+    "Force overwrite flags",
+    "Automatic creation of handoffs during init, migrate, or doctor",
+    "Any new state machine for handoff lifecycle"
+  ],
+  "acceptance": [
+    "Running `create-quiver new-handoff sample-spec` creates `specs/sample-spec/HANDOFF.md` in the canonical location",
+    "The generated handoff passes `create-quiver check-handoff specs/sample-spec/HANDOFF.md`",
+    "Running the command again without deleting the file exits non-zero and preserves the existing handoff",
+    "README and AI docs describe the scaffold as optional convenience"
+  ],
+  "files": [
+    "src/create-quiver/index.js",
+    "src/create-quiver/lib/handoff.js",
+    "README.md",
+    "README_FOR_AI.md",
+    "specs/quiver-v16-handoff-contract/SPEC.md",
+    "specs/quiver-v16-handoff-contract/STATUS.md",
+    "specs/quiver-v16-handoff-contract/EVIDENCE_REPORT.md",
+    "specs/quiver-v16-handoff-contract/slices/slice-03-handoff-scaffold-optional/slice.json"
+  ],
+  "tests": [
+    "node -c src/create-quiver/index.js",
+    "node -c src/create-quiver/lib/handoff.js",
+    "node bin/create-quiver.js new-handoff sample-spec",
+    "node bin/create-quiver.js check-handoff specs/sample-spec/HANDOFF.md",
+    "git diff --check"
+  ],
+  "documentation": [
+    "README.md",
+    "README_FOR_AI.md"
+  ],
+  "dependencies": [
+    "slice-01-handoff-template-and-contract"
+  ],
+  "assumptions": [
+    "The scaffold remains optional and should not be built before the contract is clear",
+    "Convenience is valuable only if the generated file stays perfectly aligned with the validator"
+  ],
+  "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-v17-orchestration-foundation/EVIDENCE_REPORT.md

@@ -0,0 +1,32 @@
+# Quiver v0.17 Evidence Report
+
+**Spec:** quiver-v17-orchestration-foundation
+**Date:** 2026-04-23
+**Status:** Completed
+
+## Summary
+
+This spec installs the cross-platform foundation and shared graph library used by every orchestration command in v18–v22. It does not ship a user-facing command. The primary measurable outcome is that the graph library returns the correct topological order and parallel levels for the existing Quiver repo, and that the CI matrix is green on macOS, Linux, and Windows.
+
+## Slice Evidence
+
+| Slice | Status | Evidence |
+|-------|--------|----------|
+| slice-01 | Completed | CI matrix runs macOS + Linux + Windows; a Windows path guard validates `path.win32` handling and the authoring rules docs are generated |
+| slice-02 | Completed | `src/create-quiver/lib/slice-graph.js` exports the six documented functions; unit tests cover empty repos, heuristic inference, explicit overrides, cross-spec deps, cycle detection, and conflict grouping |
+| slice-03 | Completed | `check-slice` rejects `depends_on: ["nonexistent/slice-99"]`, rejects cycles, and requires `parallel_safe_reason` when `parallel_safe: "never"` |
+
+## Required Final Evidence
+
+- `.github/workflows/ci.yml` shows `macos-latest`, `ubuntu-latest`, `windows-latest` in the matrix and all three are green
+- `node -e "const g=require('./src/create-quiver/lib/slice-graph'); console.log(g.readAllSlices('.').length)"` returns a non-zero count on all three OS
+- Unit tests for `buildGraph`, `topoSort`, `computeLevels`, and `detectFileConflicts` pass on all three OS
+- `check-slice` output demonstrates the new `depends_on` validation rules
+- `docs/COMMANDS.md` exists with a header table and at least one reserved command row
+- `docs/SUPPORT_MATRIX.md` contains the cross-platform authoring rules section
+
+## Validation Checkpoint (Post-Merge)
+
+- A dry-run of `readAllSlices` against the Quiver repo returns every existing slice without throwing
+- The maintainer confirms the library is usable before starting v18
+- At least one reviewer on a second machine confirms the CI matrix works locally

package/specs/quiver-v17-orchestration-foundation/SPEC.md

@@ -0,0 +1,79 @@
+# Quiver v0.17 - Orchestration Foundation
+
+**Date:** 2026-04-23
+**Status:** Completed
+
+Slice numbering resets here: this spec starts at `slice-01` and does not continue any previous spec's numbering.
+
+## Objective
+
+Lay the cross-platform foundation and shared graph library required by every subsequent orchestration command (`plan`, `graph`, `next`, `status`, `estimate`, `lint-spec`, `cost`, `diff-pack`, `replay`, `archive`, `blame-slice`). No user-facing command is shipped here; this spec exists to make the following specs cheap to build and safe on macOS, Linux, and Windows.
+
+## Context
+
+The orchestration roadmap (v18–v22) introduces ~13 new commands that all need to read slices, infer dependencies, compute execution levels, and detect file conflicts. Without a shared library those commands re-implement the same logic three or four times. Without a verified cross-platform CI matrix, any new command is fragile on Windows. This spec consolidates both concerns into one foundation.
+
+## Scope
+
+### Included
+
+- Verify or introduce a CI matrix that runs macOS, Linux, and Windows for all Quiver tests
+- Create `src/create-quiver/lib/slice-graph.js` with a stable API: `readAllSlices`, `inferDependencies`, `buildGraph`, `topoSort`, `computeLevels`, `detectFileConflicts`
+- Support optional `depends_on` and `parallel_safe` fields in `slice.json`, with heuristic inference as the fallback
+- Extend `check-slice` to validate `depends_on` when declared (existence, no cycles, reason when `parallel_safe: "never"`)
+- Create `docs/COMMANDS.md` as the canonical command reference table, initially empty beyond the plan row
+- Publish cross-platform authoring rules in `docs/SUPPORT_MATRIX.md` for all subsequent commands
+
+### Excluded
+
+- Any user-facing orchestration command (deferred to v18)
+- A full slice JSON Schema file (only the new optional fields are validated)
+- Parallelism enforcement or locking (library returns groups; commands decide)
+- Any change to existing slice contents beyond optional new fields
+
+## Cross-Platform Authoring Rules
+
+Every subsequent orchestration command must follow these rules, enforced by code review and CI:
+
+- No shell invocations for logic — Node.js `fs`, `path`, and `child_process` with `shell: false`
+- Paths use `path.join` and `path.sep`; output may normalize to `/` for human readability
+- Write files with `\n`; read tolerating `\r\n`
+- `--json` is the primary contract; human output is cortesy and may vary
+- Colors only when `process.stdout.isTTY && !process.env.NO_COLOR`
+- Unicode glyphs only when `process.env.LANG` includes `UTF-8` or the user passes `--unicode`; ASCII fallback otherwise
+- Optional external tools (`gh`, `graphviz`) detected with a cross-platform probe; degrade with a clear message if absent
+
+## Graph Library Contract
+
+`src/create-quiver/lib/slice-graph.js` exports:
+
+```js
+readAllSlices(rootDir)            // → Slice[] (from specs/*/slices/*/slice.json)
+inferDependencies(slices)         // → Slice[] with implicit depends_on[]
+buildGraph(slices)                // → { nodes, edges, cycles: [] }
+topoSort(graph)                   // → Slice[] (throws on cycle)
+computeLevels(graph)              // → Slice[][] (each level is a parallel lot)
+detectFileConflicts(slicesInLevel)// → ConflictGroup[]
+```
+
+Dependency inference rule: within a single spec, `slice-NN` implicitly depends on all lower-numbered slices in the same spec that share at least one entry in `files[]`. An explicit `depends_on` array in `slice.json` overrides the heuristic.
+
+## Slices
+
+| Slice | Title | Status | Spec |
+|-------|-------|--------|------|
+| 01 | Cross-Platform CI Matrix Verified | Completed | [slice-01](./slices/slice-01-ci-matrix-verified/slice.json) |
+| 02 | Slice Graph Library | Completed | [slice-02](./slices/slice-02-slice-graph-library/slice.json) |
+| 03 | Optional `depends_on` Validation | Completed | [slice-03](./slices/slice-03-depends-on-validation/slice.json) |
+
+## Definition of Done
+
+- `.github/workflows/ci.yml` runs tests on `macos-latest`, `ubuntu-latest`, and `windows-latest` and is green on all three
+- `src/create-quiver/lib/slice-graph.js` exists with the six documented exports and tests for each
+- `check-slice` rejects `depends_on` entries pointing at nonexistent slices and cycles, and requires `parallel_safe_reason` when `parallel_safe: "never"` is declared
+- `docs/COMMANDS.md` exists with a header table and a row reserved for the plan command
+- `docs/SUPPORT_MATRIX.md` documents the cross-platform authoring rules above
+
+## Validation Checkpoint
+
+Before v18 is started, the graph library must pass its own unit tests on all three OS targets, and a dry-run of `readAllSlices(repoRoot)` against the current Quiver repo must return every existing slice without throwing.

package/specs/quiver-v17-orchestration-foundation/STATUS.md

@@ -0,0 +1,31 @@
+# Quiver v0.17 Spec Status
+
+**Spec:** quiver-v17-orchestration-foundation
+**Last updated:** 2026-04-23
+
+Slice numbering is local to this spec. The first slice is `slice-01`.
+
+## Status
+
+| Slice | Title | Status | PR | Estimated hours | Actual hours |
+|-------|-------|--------|----|-----------------|--------------|
+| slice-01 | Cross-Platform CI Matrix Verified | Completed | https://github.com/FabriJuncal/quiver/pull/46 | 4 | 4 |
+| slice-02 | Slice Graph Library | Completed | https://github.com/FabriJuncal/quiver/pull/46 | 5 | 5 |
+| slice-03 | Optional `depends_on` Validation | Completed | https://github.com/FabriJuncal/quiver/pull/48 | 2 | 2 |
+
+## Progress
+
+- Completed slices: 3 / 3
+- Estimated hours: 11
+- Actual hours: 11
+
+## Blockers
+
+| Slice | Blocker | Since | Action needed |
+|-------|---------|-------|---------------|
+| - | - | - | - |
+
+## Dependencies
+
+- slice-02 depends on slice-01 (library assumes CI will validate it cross-platform)
+- slice-03 depends on slice-02 (validation uses the library's graph functions)

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.