create-quiver 0.6.0 → 0.8.0

package/specs/quiver-v18-stabilization/slices/slice-01-fix-legacy-dependency-resolution/slice.json

@@ -0,0 +1,56 @@
+{
+  "slice_id": "slice-01-fix-legacy-dependency-resolution",
+  "ticket": "QUIVER-01",
+  "type": "bugfix",
+  "title": "Fix legacy dependency resolution in `slice-graph.js`",
+  "objective": "Make `npx create-quiver plan` exit 0 on the Quiver repo by ignoring bare spec-name values in the legacy `\"dependencies\"` field instead of crashing with `MISSING_DEPENDENCY`.",
+  "description": "Old slice.json files (v01–v16) declare cross-spec dependencies with bare spec names in a `\"dependencies\"` array, e.g. `[\"quiver-v01\"]`. The `normalizeDependencyRef` function in `slice-graph.js` expands bare values by prepending the current spec slug, producing refs like `quiver-v02-bootstrap-hardening/quiver-v01`. These refs do not match any slice key, causing `buildGraph` to throw `SliceGraphError: Missing dependency reference(s)`. The fix is one guard: if a bare value does not start with `slice-`, it is a spec-level legacy ref and must be returned as null (filtered). The new `\"depends_on\"` format with full `spec/slice-id` paths is unaffected.",
+  "git": {
+    "branch_type": "bugfix",
+    "base_branch": "main",
+    "branch_slug": "fix-legacy-dependency-resolution",
+    "branch_name": "bugfix/QUIVER-01-fix-legacy-dependency-resolution"
+  },
+  "must": [
+    "Add a guard in `normalizeDependencyRef` that returns `null` when the bare dependency value does not start with `slice-`",
+    "Leave all other logic in `normalizeDependencyRef` and `buildGraph` unchanged",
+    "Add a unit test that exercises the legacy `\"dependencies\": [\"quiver-vNN\"]` format and confirms no error is thrown and no edge is produced",
+    "Run `node --test tests/` and confirm all tests pass",
+    "Run `npx create-quiver plan` on the Quiver repo and confirm exit 0"
+  ],
+  "not_included": [
+    "Changing the output or behavior of `plan`, `graph`, or `next`",
+    "Migrating old slice.json files to the new `depends_on` format",
+    "Adding warnings or notices for legacy deps — silent drop is intentional",
+    "Any other file besides `src/create-quiver/lib/slice-graph.js` and `tests/`"
+  ],
+  "acceptance": [
+    "`npx create-quiver plan` exits 0 on the Quiver repo",
+    "`npx create-quiver plan --json` returns valid JSON with `plan`, `critical_path`, and `total_hours`",
+    "A test with `\"dependencies\": [\"quiver-v01\"]` does not throw and produces zero edges for that dep",
+    "A test with `\"depends_on\": [\"other-spec/slice-01-foo\"]` still produces the expected edge (regression)",
+    "`node --test tests/` exits 0"
+  ],
+  "files": [
+    "src/create-quiver/lib/slice-graph.js",
+    "tests/lib/slice-graph.test.js"
+  ],
+  "tests": [
+    "node --test tests/",
+    "node bin/create-quiver.js plan > /dev/null",
+    "node bin/create-quiver.js plan --json | node -e \"const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8')); if(!Array.isArray(d.plan)) process.exit(1)\""
+  ],
+  "documentation": [],
+  "depends_on": [],
+  "assumptions": [
+    "All old slices using bare spec names in `\"dependencies\"` are already completed — silently dropping them causes no operational loss",
+    "No slice uses a bare dep that starts with `slice-` and refers to a different spec (would be an ambiguous format)"
+  ],
+  "estimated_hours": 0.5,
+  "actual_hours": 0.5,
+  "status": "completed",
+  "blocked_reason": null,
+  "ready_at": "2026-05-12T00:00:00Z",
+  "started_at": "2026-05-12T00:00:00Z",
+  "completed_at": "2026-05-12T00:00:00Z"
+}

package/specs/quiver-v18-stabilization/slices/slice-02-roadmap-and-branch-cleanup/CLOSURE_BRIEF.md

@@ -0,0 +1,29 @@
+# CLOSURE BRIEF — slice-02: ROADMAP v0.6 y limpieza de branches
+
+**Spec:** quiver-v18-stabilization
+**Slice:** slice-02-roadmap-and-branch-cleanup
+
+---
+
+## Checklist antes de abrir el PR
+
+- [ ] `grep 'unreleased' ROADMAP.md` → retorna vacío (exit 1 en grep, que es lo correcto).
+- [ ] `grep 'v0.6 (shipped)' ROADMAP.md` → retorna match.
+- [ ] `git branch | grep backup` → retorna vacío.
+- [ ] `git branch --merged main` → lista solo `main` (y `develop` si aplica). No hay branches de feature/docs/ci/test.
+- [ ] `git diff --stat HEAD` → solo `ROADMAP.md`.
+
+## Checklist del PR
+
+- [ ] Branch: `docs/QUIVER-02-close-v06-roadmap` → `main`.
+- [ ] Título: `docs(QUIVER-02): close v0.6 as shipped in ROADMAP`.
+- [ ] Body del PR sigue las secciones del `docs/GITFLOW_PR_GUIDE.md.template`.
+- [ ] En "Summary": mencionar ambas acciones (ROADMAP edit + branch cleanup local).
+- [ ] En "Scope": aclarar que la limpieza de branches es local-only, sin diff.
+- [ ] En "How to Test": `grep 'unreleased' ROADMAP.md` debe retornar sin match.
+- [ ] En "Rollback": `git revert HEAD --no-edit` restaura ROADMAP.md. Las branches borradas no se recuperan automáticamente (pero estaban mergeadas, sin trabajo único).
+
+## Post-merge
+
+- [ ] Actualizar `specs/quiver-v18-stabilization/STATUS.md`: slice-02 → `Completed`, agregar PR y `actual_hours`.
+- [ ] Actualizar `specs/quiver-v18-stabilization/EVIDENCE_REPORT.md`: registrar evidencia.

package/specs/quiver-v18-stabilization/slices/slice-02-roadmap-and-branch-cleanup/EXECUTION_BRIEF.md

@@ -0,0 +1,118 @@
+# EXECUTION BRIEF — slice-02: ROADMAP v0.6 y limpieza de branches
+
+**Spec:** quiver-v18-stabilization
+**Slice:** slice-02-roadmap-and-branch-cleanup
+**Estimated time:** 20 min
+**Branch:** `docs/QUIVER-02-close-v06-roadmap` from `main`
+
+---
+
+## Contexto
+
+Dos fuentes de ruido a eliminar:
+
+1. `ROADMAP.md` tiene `## v0.6 (unreleased)` aunque su scope (Node-native runtime, `quiver:*` scripts) fue absorbido y publicado en v0.7. Es una entrada engañosa.
+2. El repo tiene ~35 branches locales que son backup artifacts o branches de PRs ya mergeados a main. No bloquean nada, pero añaden ruido a `git branch`.
+
+**La limpieza de branches es local y no produce commit.** El único artefacto que va al PR es el cambio en `ROADMAP.md`.
+
+---
+
+## Parte A — Limpieza de branches (local, sin commit)
+
+### Paso 1: Listar branches ya merged a main
+
+```bash
+git branch --merged main
+```
+
+Deberías ver una lista larga. Anotá mentalmente las excepciones que NO debes borrar:
+- `main`
+- `develop`
+- `drafts/v19-v22-orchestration-followups`
+
+Todo lo demás en esa lista es candidato a eliminar.
+
+### Paso 2: Verificar que no hay trabajo no mergeado en esas branches
+
+```bash
+git branch --no-merged main
+```
+
+Si aparece algo inesperado que no sean las tres excepciones de arriba, revisalo antes de borrar. Si hay dudas, no borrés esa branch.
+
+### Paso 3: Borrar branches mergeadas (una por una o en lote)
+
+```bash
+# Borra todas las merged excepto main/develop/drafts de un golpe:
+git branch --merged main \
+  | grep -vE "^\*|^  main$|^  develop$|^  drafts/" \
+  | xargs git branch -d
+```
+
+### Paso 4: Borrar las dos branches de backup explícitamente
+
+```bash
+git branch -d backup/main-before-reconcile-20260512-094512
+git branch -d backup/main-before-reconcile-20260512-094712
+```
+
+### Paso 5: Verificar
+
+```bash
+git branch | wc -l   # debería ser significativamente menor que 35
+git branch | grep backup   # debe retornar vacío
+```
+
+---
+
+## Parte B — ROADMAP.md (sí va al PR)
+
+### El único cambio
+
+En `ROADMAP.md`, localizá la sección:
+
+```markdown
+## v0.6 (unreleased)
+
+- Cross-platform CI matrix (macOS, Linux, Windows) for Node-native runtime
+- Node-native generated project npm scripts (`quiver:*`)
+- Additive migration support for existing projects
+```
+
+Reemplazá el encabezado y agregá la nota:
+
+```markdown
+## v0.6 (shipped)
+
+> Scope absorbed into v0.7. Node-native runtime and `quiver:*` npm scripts
+> landed together with the token-efficient context pack work.
+
+- Cross-platform CI matrix (macOS, Linux, Windows) for Node-native runtime
+- Node-native generated project npm scripts (`quiver:*`)
+- Additive migration support for existing projects
+```
+
+Nada más. No toques ninguna otra sección.
+
+---
+
+## Commit y PR
+
+```bash
+git add ROADMAP.md
+git commit -m "docs(QUIVER-02): close v0.6 as shipped in ROADMAP"
+git push origin docs/QUIVER-02-close-v06-roadmap
+```
+
+Abrí el PR con `gh pr create` apuntando a `main`. El body del PR documenta ambas partes (aunque la limpieza de branches no tiene diff, mencionala en el Summary para trazabilidad).
+
+---
+
+## Restricciones
+
+- **No** toques ninguna otra sección de ROADMAP.md.
+- **No** borres branches en origin — solo local.
+- **No** borres `drafts/v19-v22-orchestration-followups` ni `develop` ni `main`.
+- **No** agregues nada a CHANGELOG.md — este cambio no es una feature.
+- El diff del PR debe mostrar solo `ROADMAP.md`.

package/specs/quiver-v18-stabilization/slices/slice-02-roadmap-and-branch-cleanup/slice.json

@@ -0,0 +1,57 @@
+{
+  "slice_id": "slice-02-roadmap-and-branch-cleanup",
+  "ticket": "QUIVER-02",
+  "type": "chore",
+  "title": "Close v0.6 in ROADMAP and clean stale local branches",
+  "objective": "Remove two sources of noise: the `v0.6 (unreleased)` entry in ROADMAP.md (the scope shipped in v0.7) and ~35 stale local branches that are already merged to main or are backup artifacts.",
+  "description": "v0.6 was never formally closed in ROADMAP.md even though its scope (Node-native runtime, `quiver:*` scripts) landed in v0.7. The entry currently reads `v0.6 (unreleased)`, which is misleading. Additionally, 35 local branches accumulate since earlier in development — two are explicit backup branches created today, the rest are feature/docs/ci branches whose PRs were merged to main months ago. The branch cleanup is a local-only operation with no commit. The ROADMAP fix is a one-line edit that goes in a docs PR.",
+  "git": {
+    "branch_type": "docs",
+    "base_branch": "main",
+    "branch_slug": "close-v06-roadmap",
+    "branch_name": "docs/QUIVER-02-close-v06-roadmap"
+  },
+  "must": [
+    "Edit `ROADMAP.md`: replace `## v0.6 (unreleased)` with `## v0.6 (shipped)` and add a one-line note: scope (Node-native runtime, `quiver:*` npm scripts) was absorbed and shipped as part of v0.7",
+    "Delete locally: `backup/main-before-reconcile-20260512-094512` and `backup/main-before-reconcile-20260512-094712`",
+    "Delete locally all branches returned by `git branch --merged main` except `main`, `develop`, and `drafts/v19-v22-orchestration-followups`",
+    "Confirm no branch with unmerged work is deleted — run `git branch --no-merged main` and verify the list before deleting anything",
+    "Commit only `ROADMAP.md` — branch cleanup produces no commit"
+  ],
+  "not_included": [
+    "Editing any other section of ROADMAP.md",
+    "Deleting branches on origin — local cleanup only",
+    "Closing or editing CHANGELOG.md",
+    "Any source code changes"
+  ],
+  "acceptance": [
+    "`grep 'unreleased' ROADMAP.md` returns no match",
+    "`grep 'v0.6 (shipped)' ROADMAP.md` returns a match",
+    "`git branch` shows no `backup/*` branches",
+    "`git branch --merged main` returns only `main` (and `develop` if present) — no stale feature/docs/ci branches",
+    "PR diff contains only `ROADMAP.md` changes"
+  ],
+  "files": [
+    "ROADMAP.md"
+  ],
+  "tests": [
+    "grep -c 'unreleased' ROADMAP.md | grep -q '^0$'",
+    "git branch --merged main",
+    "git branch | grep backup | wc -l | grep -q '^0$'"
+  ],
+  "documentation": [
+    "ROADMAP.md"
+  ],
+  "depends_on": [],
+  "assumptions": [
+    "All branches returned by `git branch --merged main` (except main/develop/drafts) are safe to delete — they were created from merged PRs",
+    "No branch other than `drafts/v19-v22-orchestration-followups` contains uncommitted or unmerged work worth preserving"
+  ],
+  "estimated_hours": 0.3,
+  "actual_hours": 0.1,
+  "status": "completed",
+  "blocked_reason": null,
+  "ready_at": "2026-05-12T00:00:00Z",
+  "started_at": "2026-05-12T00:00:00Z",
+  "completed_at": "2026-05-12T00:00:00Z"
+}

package/specs/quiver-v18-stabilization/slices/slice-03-publish-drafts-branch/CLOSURE_BRIEF.md

@@ -0,0 +1,23 @@
+# CLOSURE BRIEF — slice-03: Publicar rama de drafts
+
+**Spec:** quiver-v18-stabilization
+**Slice:** slice-03-publish-drafts-branch
+
+---
+
+## Checklist de cierre (sin PR)
+
+- [ ] Gate confirmada: el mantenedor declaró explícitamente que el checkpoint de v18 pasó.
+- [ ] `git ls-remote origin drafts/v19-v22-orchestration-followups` retorna un SHA no vacío.
+- [ ] El SHA remoto coincide con `git rev-parse drafts/v19-v22-orchestration-followups`.
+- [ ] No se abrió ningún PR para esta rama.
+
+## Post-ejecución
+
+- [ ] Actualizar `specs/quiver-v18-stabilization/STATUS.md`: slice-03 → `Completed`, `actual_hours: 0.1`.
+- [ ] Actualizar `specs/quiver-v18-stabilization/EVIDENCE_REPORT.md`: registrar SHA y fecha de push.
+- [ ] Si todos los slices de esta spec están `Completed`, actualizar el campo `Status` del EVIDENCE_REPORT a `Completed`.
+
+## Nota sobre el checkpoint de v18
+
+Una vez que este slice cierra, la spec `quiver-v18-stabilization` está completa. El siguiente paso en el BACKLOG es la promoción de v19 (Project Visibility) desde la rama de drafts a una spec activa. Ese es un proceso editorial del mantenedor, no un slice de esta spec.

package/specs/quiver-v18-stabilization/slices/slice-03-publish-drafts-branch/EXECUTION_BRIEF.md

@@ -0,0 +1,73 @@
+# EXECUTION BRIEF — slice-03: Publicar rama de drafts
+
+**Spec:** quiver-v18-stabilization
+**Slice:** slice-03-publish-drafts-branch
+**Estimated time:** 5 min
+**Sin PR** — es un `git push` directo de una rama de referencia.
+
+---
+
+## ⛔ Gate obligatoria — leer antes de ejecutar cualquier cosa
+
+Este slice está **bloqueado** hasta que el mantenedor confirme explícitamente:
+
+1. Usé `quiver:plan`, `quiver:graph`, y `quiver:next` en al menos un ciclo real de trabajo.
+2. Registré una observación en `specs/quiver-v18-slice-orchestration/EVIDENCE_REPORT.md`.
+3. Confirmo que el checkpoint de v18 pasó.
+
+**Si esa confirmación no está en el prompt que te delega este slice, abortá y pedila.**
+
+---
+
+## Contexto
+
+La rama `drafts/v19-v22-orchestration-followups` existe solo localmente. Contiene 23 archivos (4 specs: v19–v22) en un único commit. ROADMAP.md y BACKLOG.md ya hacen referencia a esta rama por nombre. Publicarla en origin completa la cadena de trazabilidad y protege el trabajo ante pérdida local.
+
+No es una rama candidata a merge. Es una rama de referencia que vive indefinidamente hasta que alguna de las specs se promueva formalmente.
+
+---
+
+## Verificación previa
+
+```bash
+# 1. Confirmar que la rama existe y tiene el commit correcto
+git log drafts/v19-v22-orchestration-followups --oneline -1
+# Esperás: 13eab96 docs(drafts): park v19-v22 spec drafts pending v18 checkpoint
+
+# 2. Confirmar que NO existe ya en origin
+git ls-remote origin drafts/v19-v22-orchestration-followups
+# Esperás: salida vacía (si retorna algo, la rama ya fue publicada — slice completado)
+```
+
+---
+
+## Ejecución
+
+```bash
+GIT_SSH_COMMAND="ssh -i ~/ssh/github-personal" \
+  git push origin drafts/v19-v22-orchestration-followups
+```
+
+---
+
+## Verificación post-push
+
+```bash
+# Confirmar que el SHA remoto coincide con el local
+LOCAL_SHA=$(git rev-parse drafts/v19-v22-orchestration-followups)
+REMOTE_SHA=$(git ls-remote origin drafts/v19-v22-orchestration-followups | awk '{print $1}')
+
+echo "Local:  $LOCAL_SHA"
+echo "Remote: $REMOTE_SHA"
+
+[ "$LOCAL_SHA" = "$REMOTE_SHA" ] && echo "OK" || echo "MISMATCH — investigar"
+```
+
+---
+
+## Restricciones
+
+- **No** abras un PR para esta rama.
+- **No** hagas `--force` en ninguna circunstancia.
+- **No** edites ningún archivo en la rama antes de publicarla.
+- **No** ejecutes este slice si el gate no fue confirmado explícitamente.

package/specs/quiver-v18-stabilization/slices/slice-03-publish-drafts-branch/slice.json

@@ -0,0 +1,49 @@
+{
+  "slice_id": "slice-03-publish-drafts-branch",
+  "ticket": "QUIVER-03",
+  "type": "chore",
+  "title": "Publish `drafts/v19-v22-orchestration-followups` to origin",
+  "objective": "Push the locally-parked v19–v22 draft specs to origin so they are preserved in the remote in case of local machine loss and are accessible for future promotion.",
+  "description": "The branch `drafts/v19-v22-orchestration-followups` exists only locally. It contains 23 files across 4 spec directories (v19 Project Visibility, v20 Context Diagnostics, v21 Slice Archaeology, v22 Deferred Tooling) committed in a single commit. ROADMAP.md and BACKLOG.md already reference this branch by name. Pushing it to origin completes the traceability chain. This slice has no PR — it is a single `git push` operation. It is gated by the human checkpoint for v18: the maintainer must confirm that `plan`, `graph`, and `next` were used in real work before this slice is executed.",
+  "git": {
+    "branch_type": "chore",
+    "base_branch": null,
+    "branch_slug": "publish-drafts-v19-v22",
+    "branch_name": "drafts/v19-v22-orchestration-followups"
+  },
+  "must": [
+    "Confirm the human checkpoint for v18 was explicitly declared by the maintainer before executing",
+    "Run `git log drafts/v19-v22-orchestration-followups --oneline -1` and confirm the expected SHA is present",
+    "Push with: `GIT_SSH_COMMAND=\"ssh -i ~/ssh/github-personal\" git push origin drafts/v19-v22-orchestration-followups`",
+    "Verify with: `git ls-remote origin drafts/v19-v22-orchestration-followups` and confirm the SHA matches local"
+  ],
+  "not_included": [
+    "Opening a PR for the drafts branch — it is a reference branch, not a merge candidate",
+    "Promoting any of v19–v22 to active spec — that is a separate decision after the checkpoint",
+    "Modifying any file in the drafts branch",
+    "Any other git push"
+  ],
+  "acceptance": [
+    "Maintainer has explicitly confirmed the v18 human checkpoint",
+    "`git ls-remote origin drafts/v19-v22-orchestration-followups` returns a non-empty SHA",
+    "The returned SHA matches `git rev-parse drafts/v19-v22-orchestration-followups`"
+  ],
+  "files": [],
+  "tests": [
+    "git ls-remote origin drafts/v19-v22-orchestration-followups",
+    "git rev-parse drafts/v19-v22-orchestration-followups"
+  ],
+  "documentation": [],
+  "depends_on": [],
+  "assumptions": [
+    "The SSH key at `~/ssh/github-personal` has push access to `FabriJuncal/quiver`",
+    "The local branch `drafts/v19-v22-orchestration-followups` has not been rebased or force-reset since creation"
+  ],
+  "estimated_hours": 0.1,
+  "actual_hours": 0.1,
+  "status": "completed",
+  "blocked_reason": null,
+  "ready_at": "2026-05-12T00:00:00Z",
+  "started_at": "2026-05-12T00:00:00Z",
+  "completed_at": "2026-05-12T00:00:00Z"
+}

package/src/create-quiver/commands/graph.js

@@ -0,0 +1,97 @@
+const { buildGraph, computeLevels, detectFileConflicts, readAllSlices } = require('../lib/slice-graph');
+const { renderDotGraph } = require('../lib/renderers/dot');
+const { renderMermaidGraph } = require('../lib/renderers/mermaid');
+const { renderTreeGraph, isUnicodeEnabled } = require('../lib/renderers/tree');
+
+const EXCLUDED_STATUSES = new Set(['completed', 'skipped', 'cancelled']);
+
+function toGraphNode(node) {
+  return {
+    ref: node.ref,
+    spec_slug: node.specSlug,
+    slice_id: node.sliceId,
+    title: node.title || node.sliceId,
+    hours: Number.isFinite(Number(node.json?.estimated_hours)) ? Number(node.json.estimated_hours) : 0,
+    status: node.status || 'draft',
+    files: Array.isArray(node.files) ? node.files : [],
+    depends_on: Array.isArray(node.depends_on) ? node.depends_on : [],
+  };
+}
+
+function buildConflictPayload(levelIndex, groups) {
+  return groups.map((group) => ({
+    level: levelIndex,
+    files: group.files,
+    slices: group.slices,
+  }));
+}
+
+function collectGraph(repoRoot, options = {}) {
+  const graph = buildGraph(readAllSlices(repoRoot));
+  computeLevels(graph);
+  const pendingNodes = graph.nodes.filter((node) => !EXCLUDED_STATUSES.has(String(node.status || '').toLowerCase()));
+  const pendingNodeRefs = new Set(pendingNodes.map((node) => node.ref));
+  const pendingEdges = graph.edges.filter((edge) => pendingNodeRefs.has(edge.from) && pendingNodeRefs.has(edge.to));
+  const levels = pendingNodes.length > 0 ? computeLevels({ nodes: pendingNodes, edges: pendingEdges, cycles: [] }) : [];
+  const levelEntries = levels.map((level, levelIndex) => {
+    const conflictGroups = detectFileConflicts(level);
+
+    return {
+      index: levelIndex,
+      slices: level.map(toGraphNode),
+      conflicts: buildConflictPayload(levelIndex, conflictGroups),
+    };
+  });
+
+  const filteredLevels = typeof options.level === 'number'
+    ? levelEntries.filter((entry) => entry.index === options.level)
+    : levelEntries;
+
+  return {
+    levels: filteredLevels.map((entry) => entry.slices),
+    conflicts: filteredLevels.flatMap((entry) => entry.conflicts),
+  };
+}
+
+function formatHumanGraph(report, options = {}) {
+  const format = options.format || 'tree';
+  const sharedOptions = {
+    showConflicts: options.showConflicts === true,
+    unicode: options.unicode === true || isUnicodeEnabled(options),
+  };
+
+  if (format === 'tree') {
+    return renderTreeGraph(report, sharedOptions);
+  }
+
+  if (format === 'mermaid') {
+    return renderMermaidGraph(report, sharedOptions);
+  }
+
+  if (format === 'dot') {
+    return renderDotGraph(report, sharedOptions);
+  }
+
+  throw new Error(`create-quiver: unsupported graph format: ${format}`);
+}
+
+function runGraph(repoRoot, options = {}) {
+  if (options.format && !['tree', 'mermaid', 'dot'].includes(options.format)) {
+    throw new Error(`create-quiver: unsupported graph format: ${options.format}`);
+  }
+
+  const report = collectGraph(repoRoot, options);
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    return report;
+  }
+
+  process.stdout.write(formatHumanGraph(report, options));
+  return report;
+}
+
+module.exports = {
+  collectGraph,
+  formatHumanGraph,
+  runGraph,
+};

package/src/create-quiver/commands/next.js

@@ -0,0 +1,134 @@
+const path = require('path');
+const readline = require('readline');
+const { collectPlan } = require('./plan');
+const { startSlice } = require('../lib/lifecycle');
+
+function toStartSliceCommand(slicePath) {
+  return `npx create-quiver start-slice "${slicePath}"`;
+}
+
+function collectNext(repoRoot, options = {}) {
+  const report = collectPlan(repoRoot, {
+    onlyReady: true,
+    specSlug: options.specSlug,
+  });
+
+  const allReady = report.plan.filter((item) => String(item.status || '').toLowerCase() !== 'blocked');
+  const next = allReady.length > 0 ? allReady[0] : null;
+
+  return {
+    all_ready: allReady,
+    next,
+  };
+}
+
+function formatHumanNext(report, options = {}) {
+  const lines = [options.allReady ? 'Ready slices' : 'Next ready slice'];
+
+  if (!report.next) {
+    lines.push('No ready slices found.');
+    return `${lines.join('\n')}\n`;
+  }
+
+  const items = options.allReady ? report.all_ready : [report.next];
+
+  for (const [index, item] of items.entries()) {
+    const command = toStartSliceCommand(item.slice_path);
+    if (options.allReady) {
+      lines.push('');
+      lines.push(`[${index + 1}] ${item.ref}`);
+      lines.push(`Title: ${item.title}`);
+      lines.push(`Status: ${item.status}`);
+      lines.push(`Start: ${command}`);
+    } else {
+      lines.push(`Slice: ${item.ref}`);
+      lines.push(`Title: ${item.title}`);
+      lines.push(`Status: ${item.status}`);
+      lines.push(`Start: ${command}`);
+      if (report.all_ready.length > 1) {
+        lines.push(`Also ready: ${report.all_ready.slice(1).map((candidate) => candidate.ref).join(', ')}`);
+      }
+    }
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
+function promptConfirm(message, io = {}) {
+  const input = io.input || process.stdin;
+  const output = io.output || process.stdout;
+
+  return new Promise((resolve, reject) => {
+    const rl = readline.createInterface({
+      input,
+      output,
+    });
+
+    rl.question(`${message} [y/N] `, (answer) => {
+      rl.close();
+      resolve(/^y(es)?$/i.test(String(answer || '').trim()));
+    });
+
+    rl.on('SIGINT', () => {
+      rl.close();
+      reject(new Error('create-quiver: confirmation aborted.'));
+    });
+  });
+}
+
+async function runNext(repoRoot, options = {}) {
+  const report = collectNext(repoRoot, options);
+  const isTTY = options.isTTY || {
+    stdin: Boolean(process.stdin.isTTY),
+    stdout: Boolean(process.stdout.isTTY),
+  };
+
+  if (options.autoStart) {
+    if (!isTTY.stdin || !isTTY.stdout) {
+      throw new Error('create-quiver: --auto-start requires an interactive TTY.');
+    }
+
+    if (!report.next) {
+      process.stdout.write('No ready slices found.\n');
+      return report;
+    }
+
+    const confirmed = await (options.promptConfirm || promptConfirm)(`Start slice ${report.next.ref}?`);
+    if (confirmed) {
+      const slicePath = path.resolve(repoRoot, report.next.slice_path);
+      await Promise.resolve((options.startSliceFn || startSlice)(slicePath, { allowDraft: true }));
+      process.stdout.write(`Started: ${report.next.ref}\n`);
+    } else {
+      process.stdout.write('Aborted.\n');
+    }
+    return report;
+  }
+
+  if (options.json) {
+    const payload = {
+      all_ready: report.all_ready.map((item) => ({
+        ...item,
+        start_slice_command: toStartSliceCommand(item.slice_path),
+      })),
+      next: report.next
+        ? {
+            ...report.next,
+            start_slice_command: toStartSliceCommand(report.next.slice_path),
+          }
+        : null,
+    };
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    return payload;
+  }
+
+  process.stdout.write(formatHumanNext(report, options));
+  return report;
+}
+
+module.exports = {
+  collectNext,
+  formatHumanNext,
+  promptConfirm,
+  runNext,
+  toStartSliceCommand,
+};