create-quiver 0.6.0 → 0.8.0

package/specs/quiver-v14-tiered-context-pack/slices/slice-05-doctor-smokes-tiered-pack/slice.json

@@ -0,0 +1,84 @@
+{
+  "slice_id": "slice-05-doctor-smokes-tiered-pack",
+  "ticket": "QUIVER-05",
+  "type": "test",
+  "title": "Doctor and Smokes for Tiered Pack",
+  "objective": "Teach `doctor` to warn when the tiered pack drifts out of contract, and add CI smokes that cover the pack, AGENTS.md, ACTIVE_SLICE lifecycle, and deduplication.",
+  "description": "Slices 01-04 introduce new artifacts. Without validation, those artifacts silently decay: QUICK grows past 50 lines, front-matter fields disappear, ACTIVE_SLICE is left orphaned after cleanup, or stack duplication creeps back in. This slice adds lightweight checks in `doctor` and cross-platform smokes in CI so the contract stays enforced. This slice also absorbs the doctor and smoke assertions originally planned for v13 slice-04, which was removed during reconciliation.",
+  "git": {
+    "branch_type": "test",
+    "base_branch": "main",
+    "branch_slug": "doctor-smokes-tiered-pack",
+    "branch_name": "test/QUIVER-05-doctor-smokes-tiered-pack"
+  },
+  "must": [
+    "Extend `src/create-quiver/lib/doctor.js` (or the doctor logic in `src/create-quiver/index.js`) to print warnings when: QUICK.md exceeds 50 non-empty lines, STANDARD.md exceeds 300 non-empty lines, AGENTS.md is missing any of the six required sections, any file in `docs/ai/` is missing front-matter, `ACTIVE_SLICE.md` exists without any active worktree, or stack information appears in more than one generated file",
+    "Warnings are non-fatal: doctor still exits 0 when only warnings are present, and exits non-zero only for existing hard failures",
+    "Add a smoke script `scripts/ci/smoke-tiered-pack.sh` that: creates a scratch project, verifies tier files exist and meet size bounds, verifies AGENTS.md sections, runs start-slice and checks ACTIVE_SLICE.md, runs cleanup-slice and checks ACTIVE_SLICE.md is gone, and greps for duplicated stack info",
+    "Wire `scripts/ci/smoke-tiered-pack.sh` into the existing `smoke:create-quiver` package script or add a sibling `smoke:tiered-pack` script",
+    "Update `.github/workflows/ci.yml` so the new smoke runs on macOS, Linux, and Windows matrix entries",
+    "Smoke asserts that docs/DECISIONS.md exists in a freshly generated project",
+    "Smoke asserts that docs/PROJECT_MAP.md contains a Suggested Reading Order section",
+    "Smoke asserts that generated guidance names all four AI modes (onboarding, implementation, review, debug)",
+    "Update specs/[project-name]/EVIDENCE_REPORT.md.template guidance to prefer summarized command evidence (command, exit code, first relevant error, stacktrace, log path) over pasted long logs"
+  ],
+  "not_included": [
+    "New diagnostic commands (token-cost, diff-pack are deferred to v15)",
+    "Blocking doctor on warnings (they stay informational)",
+    "Replacing existing smokes"
+  ],
+  "acceptance": [
+    "Running `doctor` on a healthy v14-generated project prints zero warnings and exits 0",
+    "Running `doctor` on a project where QUICK.md has 60 non-empty lines prints a warning mentioning the 50-line budget",
+    "Running `doctor` on a project where AGENTS.md is missing the Reading Budget section prints a warning naming that section",
+    "Running `doctor` on a project where `docs/ai/STANDARD.md` has no front-matter prints a warning for that file",
+    "`smoke-tiered-pack.sh` exits 0 against a freshly generated project and non-zero when any check fails",
+    "CI matrix entries for macOS, Linux, and Windows execute the new smoke",
+    "Smoke fails if DECISIONS.md is missing after init",
+    "Smoke fails if PROJECT_MAP.md is missing the Suggested Reading Order section",
+    "Smoke fails if any of the four mode names is missing from generated guidance",
+    "Generated EVIDENCE_REPORT.md.template prefers summarized command evidence over long logs"
+  ],
+  "files": [
+    "src/create-quiver/lib/doctor.js",
+    "src/create-quiver/index.js",
+    "scripts/ci/smoke-tiered-pack.sh",
+    "package.json",
+    ".github/workflows/ci.yml",
+    "specs/[project-name]/EVIDENCE_REPORT.md.template",
+    "specs/quiver-v14-tiered-context-pack/SPEC.md",
+    "specs/quiver-v14-tiered-context-pack/STATUS.md",
+    "specs/quiver-v14-tiered-context-pack/EVIDENCE_REPORT.md",
+    "specs/quiver-v14-tiered-context-pack/slices/slice-05-doctor-smokes-tiered-pack/slice.json"
+  ],
+  "tests": [
+    "node bin/create-quiver.js --name \"Scratch\" --dir /tmp/quiver-v14-slice-05-smoke",
+    "node bin/create-quiver.js doctor --dir /tmp/quiver-v14-slice-05-smoke",
+    "bash scripts/ci/smoke-tiered-pack.sh",
+    "awk 'NR==1,/^---$/{next} /^---$/{exit} {print}' /tmp/quiver-v14-slice-05-smoke/docs/ai/QUICK.md > /dev/null",
+    "git diff --check"
+  ],
+  "documentation": [
+    "docs/TESTING_GUIDE_FOR_AI.md.template",
+    "README.md"
+  ],
+  "dependencies": [
+    "slice-01-tiered-context-pack",
+    "slice-02-agents-md-router",
+    "slice-03-active-slice-lifecycle",
+    "slice-04-dedup-frontmatter"
+  ],
+  "assumptions": [
+    "Warnings are more useful than hard failures for stylistic contracts; hard failures belong to migration and file presence checks",
+    "A single smoke script is easier to maintain than spreading the checks across the existing smokes",
+    "Cross-platform shell differences are already handled by the v12 CI matrix; the new smoke follows the same conventions"
+  ],
+  "estimated_hours": 4,
+  "actual_hours": null,
+  "status": "completed",
+  "blocked_reason": null,
+  "ready_at": null,
+  "started_at": "2026-04-23",
+  "completed_at": "2026-04-23",
+  "actual_hours": 5
+}

package/specs/quiver-v15-init-required-before-migrate/EVIDENCE_REPORT.md

@@ -0,0 +1,26 @@
+# Quiver v0.15 Evidence Report
+
+**Spec:** quiver-v15-init-required-before-migrate
+**Date:** 2026-04-23
+**Status:** Completed
+
+## Summary
+
+This spec hardens `migrate` so it only upgrades projects that were already initialized by Quiver. The key outcome is that migration stops behaving like a hidden bootstrap path.
+
+## Slice Evidence
+
+| Slice | Status | Evidence |
+|-------|--------|----------|
+| slice-01 | Completed | `runMigrate()` now fails before any writes when a repo lacks Quiver initialization evidence; `src/create-quiver/lib/state.js` recognizes both initialized state metadata and strong legacy Quiver markers; `scripts/ci/smoke-create-quiver.sh` now proves that migrate fails for plain or malformed repos and still succeeds for legacy Quiver projects |
+| slice-02 | Completed | `doctor` now fails early with an init-first message when the repo has no Quiver initialization evidence; the smoke suite proves that plain repos and malformed state get `Run init first`, while legacy Quiver projects still receive migration guidance |
+| slice-03 | Completed | `README.md`, `README_FOR_AI.md`, and the generated README contract in `src/create-quiver/lib/init-docs.js` now state that `migrate` is only for already initialized Quiver projects; shell and cross-platform smokes assert the generated docs keep that wording |
+
+## Required Final Evidence
+
+- Running `npx create-quiver migrate` in a repo without Quiver initialization evidence fails before creating docs
+- The failure message points to `npx create-quiver --name "Project Name"`
+- Running `migrate` in an initialized or legacy Quiver project still succeeds
+- `doctor` can explain the difference between "not initialized" and "needs migration"
+- README and generated docs reflect the new contract
+- Smokes cover both the failing and successful flows

package/specs/quiver-v15-init-required-before-migrate/SPEC.md

@@ -0,0 +1,66 @@
+# Quiver v0.15 - Init Required Before Migrate
+
+**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
+
+Make `create-quiver migrate` refuse to run unless the target project was previously initialized by Quiver, so migration stops being an implicit bootstrap path.
+
+## Scope
+
+### Included
+
+- Require Quiver initialization metadata before `migrate` touches the filesystem
+- Keep the failure non-destructive: if the precondition fails, no docs or templates are created
+- Teach `doctor` to distinguish a project that was never initialized from one that only needs migration
+- Document the new contract in README and generated docs
+- Add smokes that prove `migrate` fails before init and succeeds after init
+
+### Excluded
+
+- A fallback bootstrap mode inside `migrate`
+- New CLI commands for repair or force-migration
+- Reworking `init`, `analyze`, or slice lifecycle semantics beyond the migration precondition
+- Publishing a release as part of this spec
+
+## Contract Change
+
+The supported flows become:
+
+For a new project:
+
+```bash
+npx create-quiver --name "Project Name"
+npx create-quiver analyze
+npx create-quiver doctor
+```
+
+For an existing Quiver project:
+
+```bash
+npx create-quiver migrate
+npx create-quiver analyze
+npx create-quiver doctor
+```
+
+If the project was never initialized by Quiver, `migrate` must fail with a clear message that points back to `npx create-quiver --name "Project Name"`. Legacy Quiver projects that predate `.quiver/state.json` must still be recognized from their generated workflow markers.
+
+## Slices
+
+| Slice | Title | Status | Spec |
+|-------|-------|--------|------|
+| 01 | Migrate Initialization Precondition | Completed | [slice-01](./slices/slice-01-migrate-initialization-precondition/slice.json) |
+| 02 | Doctor Not-Initialized Guidance | Completed | [slice-02](./slices/slice-02-doctor-not-initialized-guidance/slice.json) |
+| 03 | Docs and Smokes for Init Before Migrate | Completed | [slice-03](./slices/slice-03-docs-smokes-init-before-migrate/slice.json) |
+
+## Definition of Done
+
+- `migrate` fails before any file writes when Quiver initialization evidence is missing
+- The failure message tells the developer to run `npx create-quiver --name "Project Name"`
+- Initialized projects and legacy Quiver projects still migrate successfully
+- `doctor` distinguishes not-initialized from not-migrated states
+- README and generated docs explain that `migrate` is only for previously initialized projects
+- Smokes cover both the failing and successful paths

package/specs/quiver-v15-init-required-before-migrate/STATUS.md

@@ -0,0 +1,26 @@
+# Quiver v0.15 Spec Status
+
+**Spec:** quiver-v15-init-required-before-migrate
+**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 | Migrate Initialization Precondition | Completed | - | 3 | 2 |
+| slice-02 | Doctor Not-Initialized Guidance | Completed | - | 2 | 1 |
+| slice-03 | Docs and Smokes for Init Before Migrate | Completed | - | 3 | 1 |
+
+## Progress
+
+- Completed slices: 3 / 3
+- Estimated hours: 8
+- Actual hours: 4
+
+## Blockers
+
+| Slice | Blocker | Since | Action needed |
+|-------|---------|-------|---------------|
+| - | - | - | - |

package/specs/quiver-v15-init-required-before-migrate/slices/slice-01-migrate-initialization-precondition/slice.json

@@ -0,0 +1,65 @@
+{
+  "slice_id": "slice-01-migrate-initialization-precondition",
+  "ticket": "QUIVER-01",
+  "type": "feature",
+  "title": "Migrate Initialization Precondition",
+  "objective": "Block `migrate` unless the target project was previously initialized by Quiver.",
+  "description": "Today `migrate` can create Quiver docs in a repo that never ran `create-quiver --name ...`, which makes migration act like an undocumented bootstrap path. This slice adds a hard precondition based on Quiver initialization evidence and makes the failure non-destructive while preserving migration for legacy Quiver projects.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "init-before-migrate-precondition",
+    "branch_name": "feature/QUIVER-01-init-before-migrate-precondition"
+  },
+  "must": [
+    "Teach `runMigrate()` to fail before any filesystem writes when the project has no durable evidence of a prior Quiver initialization",
+    "The precondition must accept either initialized state metadata or strong legacy Quiver markers from previously generated projects",
+    "The error must tell the developer to run `npx create-quiver --name \"Project Name\"`",
+    "The failure path must not create `docs/`, `docs-template/`, or `.quiver/`"
+  ],
+  "not_included": [
+    "Changing `doctor` guidance",
+    "Updating README or generated docs",
+    "Adding repair or force flags"
+  ],
+  "acceptance": [
+    "Running `npx create-quiver migrate` in a repo without Quiver initialization evidence exits non-zero",
+    "Running `npx create-quiver migrate` in a repo with malformed or incomplete Quiver state and no legacy Quiver markers exits non-zero",
+    "The failure message includes `npx create-quiver --name \"Project Name\"`",
+    "A previously initialized project can still migrate successfully",
+    "A legacy Quiver project missing `.quiver/state.json` can still migrate successfully",
+    "The failing path does not create Quiver docs or template directories"
+  ],
+  "files": [
+    "src/create-quiver/index.js",
+    "src/create-quiver/lib/state.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-01-migrate-initialization-precondition/slice.json"
+  ],
+  "tests": [
+    "node -c src/create-quiver/index.js",
+    "node -c src/create-quiver/lib/state.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": [],
+  "assumptions": [
+    "A combination of state metadata and generated Quiver markers is enough to distinguish legacy Quiver repos from unrelated repos",
+    "Blocking before writes is more important than preserving the current bootstrap-like behavior"
+  ],
+  "estimated_hours": 3,
+  "actual_hours": 2,
+  "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-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
+}