create-quiver 0.7.0 → 0.8.0

package/docs/examples/plan.md.template

@@ -0,0 +1,28 @@
+# Plan Example
+
+Use `plan` to inspect the pending slice order before starting implementation work.
+
+## Input
+
+```bash
+npx create-quiver plan
+```
+
+## Representative Output
+
+```text
+Quiver plan
+Total hours: 10
+Critical path: spec-a/slice-01-alpha -> spec-a/slice-02-beta -> spec-b/slice-01-delta
+
+[N]  TICKET   SPEC/SLICE            TITLE                 HOURS  STATUS
+---  -------  --------------------  --------------------  -----  ------
+[1]  QUIVER-1 spec-a/slice-01-alpha Alpha                 2      draft
+[2]  QUIVER-1 spec-a/slice-02-beta  Beta                  5      draft
+[3]  QUIVER-1 spec-b/slice-01-delta Delta                 3      draft
+```
+
+## Notes
+
+- The exact order depends on the repo's current pending graph.
+- Use `--json` when another tool needs the plan, critical path, or total hours.

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "create-quiver",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "private": false,
   "description": "Quiver CLI for scaffolding projects from the packaged template",
   "license": "MIT",
   "bin": {
-    "create-quiver": "./bin/create-quiver.js"
+    "create-quiver": "bin/create-quiver.js"
   },
   "scripts": {
     "check:slice": "bash tools/scripts/check-slice-readiness.sh",
@@ -13,6 +13,9 @@
     "start:slice": "bash tools/scripts/start-slice.sh",
     "cleanup:slice": "bash tools/scripts/cleanup-slice.sh",
     "migrate": "bash tools/scripts/migrate-project.sh",
+    "quiver:plan": "npx create-quiver plan",
+    "quiver:graph": "npx create-quiver graph",
+    "quiver:next": "npx create-quiver next",
     "package:quiver": "bash scripts/package-quiver.sh",
     "smoke:create-quiver": "bash scripts/ci/smoke-create-quiver.sh",
     "smoke:tiered-pack": "bash scripts/ci/smoke-tiered-pack.sh",

package/package.template.json

@@ -2,17 +2,22 @@
   "name": "quiver-docs-template",
   "private": true,
   "scripts": {
-    "quiver:migrate": "npx create-quiver migrate",
-    "quiver:analyze": "npx create-quiver analyze",
-    "quiver:doctor": "npx create-quiver doctor",
+  "quiver:migrate": "npx create-quiver migrate",
+  "quiver:analyze": "npx create-quiver analyze",
+  "quiver:plan": "npx create-quiver plan",
+  "quiver:graph": "npx create-quiver graph",
+  "quiver:next": "npx create-quiver next",
+  "quiver:doctor": "npx create-quiver doctor",
     "quiver:start-slice": "npx create-quiver start-slice",
     "quiver:check-slice": "npx create-quiver check-slice",
     "quiver:check-pr": "npx create-quiver check-pr",
+    "quiver:check-handoff": "npx create-quiver check-handoff",
     "quiver:cleanup-slice": "npx create-quiver cleanup-slice",
     "quiver:check-scope": "npx create-quiver check-scope",
     "quiver:refresh-active-slices": "npx create-quiver refresh-active-slices",
     "check:slice": "bash tools/scripts/check-slice-readiness.sh",
     "check:pr": "bash tools/scripts/check-pr-readiness.sh",
+    "check-handoff": "npx create-quiver check-handoff",
     "start:slice": "bash tools/scripts/start-slice.sh",
     "cleanup:slice": "bash tools/scripts/cleanup-slice.sh",
     "check:scope": "bash tools/scripts/check-scope.sh",

package/scripts/check-slice-readiness.sh

@@ -82,11 +82,12 @@ slice_rel="${slice_abs#$repo_root/}"
 slice_meta=()
 while IFS= read -r line; do
   slice_meta+=("$line")
-done < <(node - "$slice_abs" "$slice_rel" <<'NODE'
+done < <(node - "$slice_abs" "$slice_rel" "$repo_root" <<'NODE'
 const fs = require('fs');
 const path = require('path');
 
-const [slicePath, sliceRel] = process.argv.slice(2);
+const [slicePath, sliceRel, repoRoot] = process.argv.slice(2);
+const { parseJsonWithComments } = require(path.join(repoRoot, 'src', 'create-quiver', 'lib', 'json'));
 
 function fail(message) {
   console.error(`Error: ${message}`);
@@ -95,7 +96,7 @@ function fail(message) {
 
 let json;
 try {
-  json = JSON.parse(fs.readFileSync(slicePath, 'utf8'));
+  json = parseJsonWithComments(fs.readFileSync(slicePath, 'utf8'));
 } catch (error) {
   fail(`No se pudo parsear '${slicePath}' como JSON: ${error.message}`);
 }
@@ -175,6 +176,7 @@ const cp = require('child_process');
 
 const [repoRoot, currentBranch, currentFilesB64] = process.argv.slice(2);
 const currentFiles = JSON.parse(Buffer.from(currentFilesB64, 'base64').toString('utf8'));
+const { parseJsonWithComments } = require(path.join(repoRoot, 'src', 'create-quiver', 'lib', 'json'));
 
 function run(cmd, cwd = repoRoot) {
   try {
@@ -201,7 +203,7 @@ function walkSlices(rootDir, acc) {
     }
 
     if (entry.isFile() && entry.name === 'slice.json' && fullPath.includes(`${path.sep}slices${path.sep}`)) {
-      const json = JSON.parse(fs.readFileSync(fullPath, 'utf8'));
+      const json = parseJsonWithComments(fs.readFileSync(fullPath, 'utf8'));
       const branchName = json.git?.branch_name;
       if (!branchName) {
         continue;

package/scripts/init-docs.sh

@@ -50,6 +50,9 @@ PRIMARY_INSTALL="npm install"
 PRIMARY_DEV="npm run quiver:analyze"
 PRIMARY_TEST="npm test"
 ANALYZE_COMMAND="npx create-quiver analyze"
+PLAN_COMMAND="npx create-quiver plan"
+GRAPH_COMMAND="npx create-quiver graph"
+NEXT_COMMAND="npx create-quiver next"
 DOCTOR_COMMAND="npx create-quiver doctor"
 START_SLICE_COMMAND="npx create-quiver start-slice <slice.json>"
 CHECK_SLICE_COMMAND="npx create-quiver check-slice <slice.json>"
@@ -192,12 +195,17 @@ copy_file_if_missing() {
 # Copiar templates de docs/
 copy_template_keep_name "docs-template/AGENTS.md.template" "AGENTS.md"
 copy_template "docs-template/docs/INDEX.md.template" "docs/INDEX.md"
+copy_template "docs-template/docs/COMMANDS.md.template" "docs/COMMANDS.md"
 copy_template "docs-template/docs/QUICK.md.template" "docs/ai/QUICK.md"
 copy_template "docs-template/docs/STANDARD.md.template" "docs/ai/STANDARD.md"
 copy_template "docs-template/docs/DEEP.md.template" "docs/ai/DEEP.md"
+copy_template "docs-template/docs/examples/plan.md.template" "docs/examples/plan.md"
+copy_template "docs-template/docs/examples/graph.md.template" "docs/examples/graph.md"
+copy_template "docs-template/docs/examples/next.md.template" "docs/examples/next.md"
 copy_template "docs-template/docs/DECISIONS.md.template" "docs/DECISIONS.md"
 copy_template "docs-template/docs/AI_CONTEXT.md.template" "docs/AI_CONTEXT.md"
 copy_template "docs-template/docs/AI_ONBOARDING_PROMPT.md.template" "docs/AI_ONBOARDING_PROMPT.md"
+copy_template "docs-template/specs/[project-name]/HANDOFF.md.template" "specs/$PROJECT_SLUG/HANDOFF.md"
 copy_template "docs-template/docs/CONTEXTO.md.template" "docs/CONTEXTO.md"
 copy_template "docs-template/docs/STATUS.md.template" "docs/STATUS.md"
 copy_template "docs-template/docs/WORKFLOW.md.template" "docs/WORKFLOW.md"
@@ -488,8 +496,11 @@ Run Quiver from this project root. Do not install it globally.
 
 \`\`\`bash
 npm install
-npx create-quiver analyze
-npx create-quiver doctor
+$ANALYZE_COMMAND
+$PLAN_COMMAND
+$GRAPH_COMMAND
+$DOCTOR_COMMAND
+$NEXT_COMMAND
 \`\`\`
 
 If this project needs a pinned Quiver version, install it as a devDependency:
@@ -506,17 +517,27 @@ The generated project includes \`quiver:*\` npm scripts that call the Node CLI a
 
 \`\`\`bash
 npm run quiver:analyze
+npm run quiver:plan
+npm run quiver:graph
+npm run quiver:next
 npm run quiver:doctor
 npm run quiver:migrate
 npm run quiver:start-slice -- specs/$PROJECT_SLUG/slices/slice-01/slice.json
 npm run quiver:check-slice -- specs/$PROJECT_SLUG/slices/slice-01/slice.json
 npm run quiver:check-pr -- specs/$PROJECT_SLUG/slices/slice-01/slice.json
+npm run quiver:check-handoff -- specs/$PROJECT_SLUG/HANDOFF.md
 npm run quiver:cleanup-slice -- specs/$PROJECT_SLUG/slices/slice-01/slice.json
 npm run quiver:check-scope -- specs/$PROJECT_SLUG/slices/slice-01/slice.json
 npm run quiver:refresh-active-slices
 \`\`\`
 
+The \`quiver:graph\` script prints the tree view by default; use \`npx create-quiver graph --format mermaid\` for PR-ready Markdown and \`--format dot\` when you want Graphviz source.
+The \`quiver:next\` script points to the next ready slice and can auto-start it behind a confirmation prompt.
+Use \`npx create-quiver next --all-ready\` when you want the full ready level instead of a single suggestion.
 The legacy Bash wrappers remain in \`tools/scripts/\` for compatibility, but new project-level automation should prefer the \`quiver:*\` scripts and the direct \`npx create-quiver ...\` commands below.
+\`npm run check-handoff -- specs/$PROJECT_SLUG/HANDOFF.md\` is available as a legacy-friendly alias for the handoff validator.
+If a new bounded transfer is needed, scaffold \`specs/$PROJECT_SLUG/HANDOFF.md\` with \`npx create-quiver new-handoff $PROJECT_SLUG\` and validate it with \`npx create-quiver check-handoff specs/$PROJECT_SLUG/HANDOFF.md\`.
+For exceptional context transfers between agents or phases, a dedicated \`HANDOFF.md\` can live alongside the usual spec and docs files.
 
 ## Cross-Platform Support
 
@@ -529,8 +550,20 @@ If the project already existed before this Quiver version, upgrade it from the p
 \`\`\`bash
 cd /path/to/your-project
 npx create-quiver migrate
-npx create-quiver analyze
-npx create-quiver doctor
+$ANALYZE_COMMAND
+$PLAN_COMMAND
+$GRAPH_COMMAND
+$NEXT_COMMAND
+$DOCTOR_COMMAND
+\`\`\`
+
+Use \`$GRAPH_COMMAND --format mermaid\` for GitHub-friendly graph embeds or \`$GRAPH_COMMAND --format dot\` for Graphviz pipelines.
+
+Exportable graph formats are available when you need a PR-ready Mermaid block or Graphviz source:
+
+\`\`\`bash
+$GRAPH_COMMAND --format mermaid
+$GRAPH_COMMAND --format dot
 \`\`\`
 
 If your team prefers a pinned local dependency, update the package first and then run the same flow:
@@ -539,9 +572,14 @@ If your team prefers a pinned local dependency, update the package first and the
 npm install --save-dev create-quiver@latest
 npx create-quiver migrate
 npx create-quiver analyze
+npx create-quiver plan
+npx create-quiver graph
+npx create-quiver next
 npx create-quiver doctor
 \`\`\`
 
+The tree output remains the default, but Mermaid and DOT are available on demand for exported docs and slide decks.
+
 ## AI Context Onboarding
 
 Lee \`AGENTS.md\` primero y después \`docs/AI_ONBOARDING_PROMPT.md\` tras el análisis.
@@ -555,6 +593,7 @@ Prepare the project context docs and report assumptions, risks, and files change
 \`\`\`
 
 Review the AI changes to docs/AI_CONTEXT.md, docs/CONTEXTO.md, docs/STATUS.md, and specs/$PROJECT_SLUG/SPEC.md before starting implementation work.
+If the work was explicitly transferred through a handoff artifact, read \`specs/$PROJECT_SLUG/HANDOFF.md\` before implementation.
 
 ## Decision Log
 
@@ -564,15 +603,21 @@ Record durable decisions in \`docs/DECISIONS.md\` so future AI agents do not re-
 
 1. Review or refine specs/$PROJECT_SLUG/SPEC.md.
 2. Create the first slice from specs/$PROJECT_SLUG/slices/slice-template/slice.json.
-3. Start work with \`npx create-quiver start-slice <slice.json>\` or \`npm run quiver:start-slice -- <slice.json>\`.
-4. Make one commit per slice.
-5. Open one PR per spec.
+3. Review the plan with \`$PLAN_COMMAND\` or \`npm run quiver:plan\`.
+4. Inspect the graph with \`$GRAPH_COMMAND\` or \`npm run quiver:graph\`.
+5. Check the next ready slice with \`$NEXT_COMMAND\` or \`npm run quiver:next\`.
+6. Start work with \`$START_SLICE_COMMAND\` or \`npm run quiver:start-slice -- <slice.json>\`.
+7. Make one commit per slice.
+8. Open one PR per spec.
 
 ## Verification Checklist
 
 - [ ] npm install completes
-- [ ] npx create-quiver analyze completes
-- [ ] npx create-quiver doctor completes
+- [ ] $ANALYZE_COMMAND completes
+- [ ] $PLAN_COMMAND completes
+- [ ] $GRAPH_COMMAND completes
+- [ ] $NEXT_COMMAND completes
+- [ ] $DOCTOR_COMMAND completes
 - [ ] AI agent executed docs/AI_ONBOARDING_PROMPT.md
 - [ ] Context docs were reviewed before the first slice
 
@@ -581,6 +626,9 @@ Record durable decisions in \`docs/DECISIONS.md\` so future AI agents do not re-
 - [AI Context](./docs/AI_CONTEXT.md) - Contexto resumido para IA
 - [Decision Log](./docs/DECISIONS.md) - Decisiones durables del proyecto
 - [AI Onboarding Prompt](./docs/AI_ONBOARDING_PROMPT.md) - Handoff exacto para agentes después del análisis
+- [Handoff](./specs/$PROJECT_SLUG/HANDOFF.md) - Transferencia excepcional entre agentes o fases
+- [Check Handoff](./docs/WORKFLOW.md) - Valida el handoff con \`npx create-quiver check-handoff\`
+- [Commands](./docs/COMMANDS.md) - Tabla canónica de comandos de orquestación
 - [Contexto](./docs/CONTEXTO.md) - Qué es $PROJECT_NAME
 - [Workflow](./docs/WORKFLOW.md) - Cómo implementar
 - [Support Matrix](./docs/SUPPORT_MATRIX.md) - Qué entornos están soportados

package/specs/[project-name]/HANDOFF.md.template

@@ -0,0 +1,37 @@
+# Handoff - {{PROJECT_NAME}}
+
+**Date:** {{FECHA}}
+**Project:** {{PROJECT_NAME}}
+**Slug:** {{PROJECT_SLUG}}
+
+This handoff is an exceptional transfer artifact. Use it when work needs to move between agents or between planning and execution with bounded context.
+
+## Background
+
+Describe the situation that requires a handoff and the current state of the work.
+
+## What you will change
+
+List the exact files, modules, docs, or workflows that should change.
+
+## Validation checklist
+
+List the commands, checks, or observations that prove the handoff was completed correctly.
+
+## Out of scope
+
+List anything that should not be touched in this handoff.
+
+## Expected deliverable
+
+Describe the concrete output expected from the recipient.
+
+## Constraints
+
+List the rules, assumptions, and boundaries the recipient must follow.
+
+## Notes
+
+- Handoffs are orthogonal to specs and slices.
+- Do not use this file to introduce a new `slice.json` type.
+- If the work is large enough to need a durable plan, prefer a spec instead.

package/specs/[project-name]/slices/slice-template/slice.json

@@ -44,6 +44,11 @@
     "lib/module/file.ts",
     "components/Component.tsx"
   ],
+  // "depends_on": [
+  //   "slice-01-previous"
+  // ],
+  // "parallel_safe": "never",
+  // "parallel_safe_reason": "Explain why this slice cannot run in parallel."
   "tests": [
     "tests/e2e/module/test.spec.ts",
     "tests/unit/module/test.test.ts"

package/specs/quiver-v08-agent-onboarding-analysis/slices/slice-01-project-scan-command/slice.json

@@ -65,7 +65,7 @@
   ],
   "estimated_hours": 4,
   "actual_hours": 0,
-  "status": "draft",
+  "status": "completed",
   "blocked_reason": null,
   "ready_at": null,
   "started_at": null,

package/specs/quiver-v08-agent-onboarding-analysis/slices/slice-02-ai-onboarding-prompt/slice.json

@@ -74,7 +74,7 @@
   ],
   "estimated_hours": 3,
   "actual_hours": 0,
-  "status": "draft",
+  "status": "completed",
   "blocked_reason": null,
   "ready_at": null,
   "started_at": null,

package/specs/quiver-v08-agent-onboarding-analysis/slices/slice-03-doctor-readme-adoption-flow/slice.json

@@ -68,7 +68,7 @@
   ],
   "estimated_hours": 2,
   "actual_hours": 0,
-  "status": "draft",
+  "status": "completed",
   "blocked_reason": null,
   "ready_at": null,
   "started_at": null,

package/specs/quiver-v12-cross-platform-native-runtime/slices/slice-01-cross-platform-support-contract/slice.json

@@ -61,7 +61,7 @@
   ],
   "estimated_hours": 3,
   "actual_hours": null,
-  "status": "draft",
+  "status": "completed",
   "blocked_reason": null,
   "ready_at": null,
   "started_at": null,

package/specs/quiver-v12-cross-platform-native-runtime/slices/slice-02-node-init-docs-runtime/slice.json

@@ -68,7 +68,7 @@
   ],
   "estimated_hours": 8,
   "actual_hours": null,
-  "status": "draft",
+  "status": "completed",
   "blocked_reason": null,
   "ready_at": null,
   "started_at": null,

package/specs/quiver-v12-cross-platform-native-runtime/slices/slice-03-node-migrate-analyze-doctor-flow/slice.json

@@ -66,7 +66,7 @@
   ],
   "estimated_hours": 5,
   "actual_hours": null,
-  "status": "draft",
+  "status": "completed",
   "blocked_reason": null,
   "ready_at": null,
   "started_at": null,

package/specs/quiver-v12-cross-platform-native-runtime/slices/slice-04-node-slice-lifecycle-commands/slice.json

@@ -73,7 +73,7 @@
   ],
   "estimated_hours": 10,
   "actual_hours": null,
-  "status": "draft",
+  "status": "completed",
   "blocked_reason": null,
   "ready_at": null,
   "started_at": null,

package/specs/quiver-v12-cross-platform-native-runtime/slices/slice-05-generated-project-scripts-and-migration/slice.json

@@ -70,7 +70,7 @@
   ],
   "estimated_hours": 5,
   "actual_hours": null,
-  "status": "draft",
+  "status": "completed",
   "blocked_reason": null,
   "ready_at": null,
   "started_at": null,

package/specs/quiver-v13-token-efficient-ai-context/EVIDENCE_REPORT.md

@@ -2,7 +2,7 @@
 
 **Spec:** quiver-v13-token-efficient-ai-context
 **Date:** 2026-04-23
-**Status:** Draft
+**Status:** Completed
 
 ## Summary
 

package/specs/quiver-v13-token-efficient-ai-context/SPEC.md

@@ -1,7 +1,7 @@
 # Quiver v0.13 - Token-Efficient AI Context
 
 **Date:** 2026-04-23
-**Status:** Draft
+**Status:** Completed
 
 Slice numbering resets here: this spec starts at `slice-01` and does not continue any previous spec's numbering.
 

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"
+}