create-quiver 0.7.0 → 0.8.0

package/specs/quiver-v15-init-required-before-migrate/slices/slice-02-doctor-not-initialized-guidance/slice.json

@@ -0,0 +1,61 @@
+{
+  "slice_id": "slice-02-doctor-not-initialized-guidance",
+  "ticket": "QUIVER-02",
+  "type": "feature",
+  "title": "Doctor Not-Initialized Guidance",
+  "objective": "Make `doctor` explain when a project was never initialized by Quiver.",
+  "description": "Once `migrate` is hardened, `doctor` must stop implying that every repo only needs migration. This slice teaches the CLI to distinguish not-initialized from not-migrated projects.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "doctor-not-initialized-guidance",
+    "branch_name": "feature/QUIVER-02-doctor-not-initialized-guidance"
+  },
+  "must": [
+    "Update `doctor` so missing init metadata points to `npx create-quiver --name \"Project Name\"` instead of migration",
+    "Keep migration guidance for projects that do have init metadata but are missing upgrade artifacts",
+    "Do not weaken existing hard failures around missing required files"
+  ],
+  "not_included": [
+    "Changing README or generated docs",
+    "Changing migrate behavior"
+  ],
+  "acceptance": [
+    "A repo without init metadata gets an init-first doctor message",
+    "An initialized but outdated repo still gets migration guidance",
+    "Healthy initialized projects keep the current doctor success flow"
+  ],
+  "files": [
+    "src/create-quiver/index.js",
+    "src/create-quiver/lib/doctor.js",
+    "scripts/ci/smoke-create-quiver.sh",
+    "specs/quiver-v15-init-required-before-migrate/SPEC.md",
+    "specs/quiver-v15-init-required-before-migrate/STATUS.md",
+    "specs/quiver-v15-init-required-before-migrate/EVIDENCE_REPORT.md",
+    "specs/quiver-v15-init-required-before-migrate/slices/slice-02-doctor-not-initialized-guidance/slice.json"
+  ],
+  "tests": [
+    "node -c src/create-quiver/index.js",
+    "node -c src/create-quiver/lib/doctor.js",
+    "bash scripts/ci/smoke-create-quiver.sh",
+    "git diff --check"
+  ],
+  "documentation": [
+    "specs/quiver-v15-init-required-before-migrate/SPEC.md",
+    "specs/quiver-v15-init-required-before-migrate/STATUS.md",
+    "specs/quiver-v15-init-required-before-migrate/EVIDENCE_REPORT.md"
+  ],
+  "dependencies": [
+    "slice-01-migrate-initialization-precondition"
+  ],
+  "assumptions": [
+    "The init state can be inferred purely from Quiver metadata without guessing from generated files"
+  ],
+  "estimated_hours": 2,
+  "actual_hours": 1,
+  "status": "completed",
+  "blocked_reason": null,
+  "ready_at": null,
+  "started_at": "2026-04-23",
+  "completed_at": "2026-04-23"
+}

package/specs/quiver-v15-init-required-before-migrate/slices/slice-03-docs-smokes-init-before-migrate/slice.json

@@ -0,0 +1,64 @@
+{
+  "slice_id": "slice-03-docs-smokes-init-before-migrate",
+  "ticket": "QUIVER-03",
+  "type": "docs",
+  "title": "Docs and Smokes for Init Before Migrate",
+  "objective": "Align the public docs and smoke tests with the new init-before-migrate contract.",
+  "description": "Once the CLI behavior changes, the README, generated docs, and smoke coverage must reflect the new rule so users do not keep treating `migrate` as a bootstrap path.",
+  "git": {
+    "branch_type": "docs",
+    "base_branch": "main",
+    "branch_slug": "docs-smokes-init-before-migrate",
+    "branch_name": "docs/QUIVER-03-init-before-migrate-contract"
+  },
+  "must": [
+    "Document that `migrate` is only for projects previously initialized by Quiver",
+    "Update generated docs to point non-initialized repos back to `npx create-quiver --name \"Project Name\"`",
+    "Add smoke coverage for the fail-before-init path and the success-after-init path"
+  ],
+  "not_included": [
+    "Changing CLI semantics beyond messaging and tests"
+  ],
+  "acceptance": [
+    "README explains the init-before-migrate contract",
+    "Generated docs do not imply that `migrate` bootstraps new repos",
+    "Smokes fail if `migrate` succeeds before init"
+  ],
+  "files": [
+    "README.md",
+    "README_FOR_AI.md",
+    "src/create-quiver/lib/init-docs.js",
+    "scripts/ci/smoke-create-quiver.sh",
+    "scripts/ci/smoke-cross-platform.js",
+    "specs/quiver-v15-init-required-before-migrate/SPEC.md",
+    "specs/quiver-v15-init-required-before-migrate/STATUS.md",
+    "specs/quiver-v15-init-required-before-migrate/EVIDENCE_REPORT.md",
+    "specs/quiver-v15-init-required-before-migrate/slices/slice-03-docs-smokes-init-before-migrate/slice.json"
+  ],
+  "tests": [
+    "bash scripts/ci/smoke-create-quiver.sh",
+    "node scripts/ci/smoke-cross-platform.js",
+    "git diff --check"
+  ],
+  "documentation": [
+    "README.md",
+    "README_FOR_AI.md",
+    "specs/quiver-v15-init-required-before-migrate/SPEC.md",
+    "specs/quiver-v15-init-required-before-migrate/STATUS.md",
+    "specs/quiver-v15-init-required-before-migrate/EVIDENCE_REPORT.md"
+  ],
+  "dependencies": [
+    "slice-01-migrate-initialization-precondition",
+    "slice-02-doctor-not-initialized-guidance"
+  ],
+  "assumptions": [
+    "Public docs should describe state-based behavior, not internal implementation details"
+  ],
+  "estimated_hours": 3,
+  "actual_hours": 1,
+  "status": "completed",
+  "blocked_reason": null,
+  "ready_at": null,
+  "started_at": "2026-04-23",
+  "completed_at": "2026-04-23"
+}

package/specs/quiver-v16-handoff-contract/EVIDENCE_REPORT.md

@@ -0,0 +1,26 @@
+# Quiver v0.16 Evidence Report
+
+**Spec:** quiver-v16-handoff-contract
+**Date:** 2026-04-23
+**Status:** Completed
+
+## Summary
+
+This spec will standardize Quiver handoffs as a lightweight artifact for exceptional context transfers. The target outcome is a documented contract with minimal automation, not a new workflow layer.
+
+## Slice Evidence
+
+| Slice | Status | Evidence |
+|-------|--------|----------|
+| slice-01 | Completed | A canonical `specs/[project-name]/HANDOFF.md.template` now exists, `init-docs` and `scripts/init-docs.sh` copy it into `specs/<project-slug>/HANDOFF.md`, and the docs explain when to use a handoff versus updating a spec or slice directly |
+| slice-02 | Completed | `create-quiver check-handoff <path>` validates path and required sections, returns non-zero on malformed handoffs, and smoke coverage proves both valid and invalid examples |
+| slice-03 | Completed | `create-quiver new-handoff <spec-slug>` generates `specs/<spec-slug>/HANDOFF.md` from the template without overwriting an existing handoff and stays aligned with the validator contract |
+
+## Required Final Evidence
+
+- A canonical `HANDOFF.md.template` exists under `specs/[project-name]/`
+- Documentation defines the canonical location, lifecycle, and required sections
+- `check-handoff` fails clearly for missing files, wrong paths, and missing required sections
+- A valid `HANDOFF.md` passes validation
+- If `new-handoff` is implemented, it generates a valid handoff in the correct location and refuses accidental overwrite
+- The contract remains separate from `slice.json` types and from `doctor`

package/specs/quiver-v16-handoff-contract/SPEC.md

@@ -0,0 +1,68 @@
+# Quiver v0.16 - Handoff Contract
+
+**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
+
+Formalize a lightweight `HANDOFF.md` contract for exceptional context transfers between humans and agents without turning handoffs into a new slice type or a heavier orchestration system.
+
+## Scope
+
+### Included
+
+- Define a canonical `HANDOFF.md` template and required sections
+- Define the canonical location and lifecycle for handoff artifacts
+- Add a lightweight `check-handoff` command that validates structure and placement
+- Optionally add a `new-handoff` scaffold command for faster creation
+- Document when a handoff should be used and when a normal spec or slice update is enough
+
+### Excluded
+
+- Adding a new `type` to `slice.json`
+- Integrating handoff checks into `doctor`
+- Persisting handoff state in `.quiver/state.json`
+- Automatic handoff resolution, merging, or workflow orchestration
+- Publishing a release as part of this spec
+
+## Organic Evidence
+
+- One real handoff already exists at [specs/quiver-v14-tiered-context-pack/HANDOFF.md](../quiver-v14-tiered-context-pack/HANDOFF.md)
+- This spec promotes that pattern into a documented contract without assuming broader automation than the evidence supports
+
+## Preconditions
+
+- Before executing `slice-01`, align [ROADMAP.md](../../ROADMAP.md) and [BACKLOG.md](../../BACKLOG.md) so they reflect the already completed `v14` and `v15` work
+
+## Proposed Contract
+
+- Canonical path: `specs/<spec-slug>/HANDOFF.md`
+- Canonical template source: `specs/[project-name]/HANDOFF.md.template`
+- Required sections:
+  - `## Background`
+  - `## What you will change`
+  - `## Validation checklist`
+  - `## Out of scope`
+  - `## Expected deliverable`
+  - `## Constraints`
+- Handoffs are exceptional artifacts for cross-cutting reconciliation, redirection, or bounded transfer of execution context
+- A handoff must not replace `SPEC.md`, `STATUS.md`, `EVIDENCE_REPORT.md`, or `slice.json`
+
+## Slices
+
+| Slice | Title | Status | Spec |
+|-------|-------|--------|------|
+| 01 | Handoff Template and Contract | Completed | [slice-01](./slices/slice-01-handoff-template-and-contract/slice.json) |
+| 02 | Check Handoff Command | Completed | [slice-02](./slices/slice-02-check-handoff-command/slice.json) |
+| 03 | Handoff Scaffold Optional | Completed | [slice-03](./slices/slice-03-handoff-scaffold-optional/slice.json) |
+
+## Definition of Done
+
+- Quiver ships a canonical `HANDOFF.md.template` with the required sections
+- The documentation explains where handoffs live, when to create one, and when not to
+- `create-quiver check-handoff <path>` validates the contract and fails clearly on missing sections or wrong placement
+- `create-quiver new-handoff <spec-slug>` can create a handoff from the template without overwriting an existing file
+- No new `slice.json` type or handoff state machine is introduced
+- Smokes cover the validator and, if implemented, the scaffold flow

package/specs/quiver-v16-handoff-contract/STATUS.md

@@ -0,0 +1,26 @@
+# Quiver v0.16 Spec Status
+
+**Spec:** quiver-v16-handoff-contract
+**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 | Handoff Template and Contract | Completed | - | 3 | 2 |
+| slice-02 | Check Handoff Command | Completed | - | 3 | 2 |
+| slice-03 | Handoff Scaffold Optional | Completed | - | 2 | 2 |
+
+## Progress
+
+- Completed slices: 3 / 3
+- Estimated hours: 8
+- Actual hours: 6
+
+## Blockers
+
+| Slice | Blocker | Since | Action needed |
+|-------|---------|-------|---------------|
+| - | - | - | - |

package/specs/quiver-v16-handoff-contract/slices/slice-01-handoff-template-and-contract/slice.json

@@ -0,0 +1,66 @@
+{
+  "slice_id": "slice-01-handoff-template-and-contract",
+  "ticket": "QUIVER-01",
+  "type": "docs",
+  "title": "Handoff Template and Contract",
+  "objective": "Define the canonical HANDOFF artifact, its required sections, and its lifecycle without changing the slice model.",
+  "description": "Quiver already has one real handoff artifact, but there is no formal contract yet. This slice standardizes the artifact as `specs/<spec-slug>/HANDOFF.md`, adds a reusable template at `specs/[project-name]/HANDOFF.md.template`, and documents when a handoff is appropriate versus when a normal spec or slice update is enough.",
+  "git": {
+    "branch_type": "docs",
+    "base_branch": "main",
+    "branch_slug": "handoff-template-and-contract",
+    "branch_name": "docs/QUIVER-01-handoff-template-and-contract"
+  },
+  "must": [
+    "Add `specs/[project-name]/HANDOFF.md.template` with the required sections `Background`, `What you will change`, `Validation checklist`, `Out of scope`, `Expected deliverable`, and `Constraints`",
+    "Document the canonical path for concrete handoffs as `specs/<spec-slug>/HANDOFF.md`",
+    "Document when a handoff should be used and when a spec, status update, or slice update is the correct tool instead",
+    "State explicitly that handoffs do not introduce a new `slice.json` type and do not replace spec artifacts"
+  ],
+  "not_included": [
+    "CLI commands",
+    "Doctor integration",
+    "Handoff state metadata",
+    "Automatic handoff generation"
+  ],
+  "acceptance": [
+    "The repository contains a canonical `specs/[project-name]/HANDOFF.md.template`",
+    "The template contains all six required sections with stable headings",
+    "README and AI workflow documentation explain the canonical path and lifecycle for handoffs",
+    "The documentation explains that handoffs are exceptional artifacts and not a replacement for `SPEC.md`, `STATUS.md`, `EVIDENCE_REPORT.md`, or `slice.json`"
+  ],
+  "files": [
+    "specs/[project-name]/HANDOFF.md.template",
+    "README.md",
+    "README_FOR_AI.md",
+    "docs/WORKFLOW.md.template",
+    "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-01-handoff-template-and-contract/slice.json"
+  ],
+  "tests": [
+    "rg -n \"^## Background$|^## What you will change$|^## Validation checklist$|^## Out of scope$|^## Expected deliverable$|^## Constraints$\" specs/[project-name]/HANDOFF.md.template",
+    "rg -n \"HANDOFF.md|handoff\" README.md README_FOR_AI.md docs/WORKFLOW.md.template",
+    "git diff --check"
+  ],
+  "documentation": [
+    "README.md",
+    "README_FOR_AI.md",
+    "docs/WORKFLOW.md.template",
+    "specs/[project-name]/HANDOFF.md.template"
+  ],
+  "dependencies": [],
+  "assumptions": [
+    "One organic handoff example is enough to justify a documented contract layer",
+    "The first step should define the artifact and its boundaries before adding automation"
+  ],
+  "estimated_hours": 3,
+  "actual_hours": null,
+  "status": "completed",
+  "blocked_reason": null,
+  "ready_at": null,
+  "started_at": "2026-04-23",
+  "completed_at": "2026-04-23",
+  "actual_hours": 2
+}

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)