create-quiver 0.7.0 → 0.8.0

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,
+};

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

@@ -0,0 +1,205 @@
+const fs = require('fs');
+const path = require('path');
+const { relativePosixPath } = require('../lib/paths');
+const { buildGraph, readAllSlices, topoSort } = require('../lib/slice-graph');
+
+const EXCLUDED_STATUSES = new Set(['completed', 'skipped', 'cancelled']);
+
+function toHourCount(value) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
+}
+
+function compareRefs(left, right) {
+  return String(left || '').localeCompare(String(right || ''));
+}
+
+function sliceToPlanItem(repoRoot, slice, index, readySet) {
+  return {
+    index,
+    ref: slice.ref,
+    spec_family: slice.specFamily || '',
+    spec_slug: slice.specSlug,
+    slice_id: slice.sliceId,
+    slice_path: relativePosixPath(repoRoot, slice.slicePath),
+    ticket: slice.ticket || '',
+    title: slice.title || slice.sliceId,
+    status: slice.status || 'draft',
+    hours: toHourCount(slice.json?.estimated_hours),
+    files: Array.isArray(slice.files) ? slice.files : [],
+    depends_on: Array.isArray(slice.depends_on) ? slice.depends_on : [],
+    ready: readySet.has(slice.ref),
+  };
+}
+
+function buildSubgraph(graph, refs) {
+  const refSet = new Set(refs);
+  return {
+    nodes: graph.nodes.filter((node) => refSet.has(node.ref)),
+    edges: graph.edges.filter((edge) => refSet.has(edge.from) && refSet.has(edge.to)),
+    cycles: graph.cycles.filter((cycle) => cycle.every((ref) => refSet.has(ref))),
+  };
+}
+
+function buildReadySet(graph, pendingRefs) {
+  const pendingSet = new Set(pendingRefs);
+  const incomingCounts = new Map(pendingRefs.map((ref) => [ref, 0]));
+
+  for (const edge of graph.edges) {
+    if (!pendingSet.has(edge.from) || !pendingSet.has(edge.to)) {
+      continue;
+    }
+    incomingCounts.set(edge.to, (incomingCounts.get(edge.to) || 0) + 1);
+  }
+
+  return new Set(Array.from(incomingCounts.entries()).filter(([, count]) => count === 0).map(([ref]) => ref));
+}
+
+function buildCriticalPath(graph, refs) {
+  if (refs.length === 0) {
+    return [];
+  }
+
+  const subgraph = buildSubgraph(graph, refs);
+  const ordered = topoSort(subgraph);
+  const incoming = new Map(ordered.map((node) => [node.ref, []]));
+
+  for (const edge of subgraph.edges) {
+    if (!incoming.has(edge.to)) {
+      continue;
+    }
+    incoming.get(edge.to).push(edge.from);
+  }
+
+  const best = new Map();
+
+  for (const node of ordered) {
+    const hours = toHourCount(node.json?.estimated_hours);
+    const predecessors = incoming.get(node.ref) || [];
+    let candidate = {
+      hours,
+      path: [node.ref],
+    };
+
+    for (const pred of predecessors) {
+      const prev = best.get(pred);
+      if (!prev) {
+        continue;
+      }
+      const nextCandidate = {
+        hours: prev.hours + hours,
+        path: [...prev.path, node.ref],
+      };
+      const pathLabel = nextCandidate.path.join('>');
+      const bestLabel = candidate.path.join('>');
+      if (nextCandidate.hours > candidate.hours || (nextCandidate.hours === candidate.hours && compareRefs(pathLabel, bestLabel) < 0)) {
+        candidate = nextCandidate;
+      }
+    }
+
+    best.set(node.ref, candidate);
+  }
+
+  let winner = null;
+  for (const node of ordered) {
+    const candidate = best.get(node.ref);
+    if (!candidate) {
+      continue;
+    }
+    if (!winner || candidate.hours > winner.hours || (candidate.hours === winner.hours && compareRefs(candidate.path.join('>'), winner.path.join('>')) < 0)) {
+      winner = candidate;
+    }
+  }
+
+  return winner ? winner.path : [];
+}
+
+function collectPlan(repoRoot, options = {}) {
+  const allSlices = readAllSlices(repoRoot);
+  const graph = buildGraph(allSlices);
+  const topo = topoSort(graph);
+  const excluded = EXCLUDED_STATUSES;
+  const specSlug = options.specSlug ? String(options.specSlug).trim() : '';
+
+  const pendingRefs = new Set(
+    graph.nodes
+      .filter((node) => !excluded.has(String(node.status || '').toLowerCase()))
+      .map((node) => node.ref),
+  );
+
+  const readyRefs = buildReadySet(graph, Array.from(pendingRefs));
+
+  const selectedNodes = topo.filter((node) => {
+    if (!pendingRefs.has(node.ref)) {
+      return false;
+    }
+    if (specSlug && node.specSlug !== specSlug) {
+      return false;
+    }
+    return true;
+  });
+
+  const readyNodes = selectedNodes.filter((node) => readyRefs.has(node.ref));
+  const targetNodes = options.onlyReady ? readyNodes : selectedNodes;
+  const criticalPath = buildCriticalPath(graph, targetNodes.map((node) => node.ref));
+  const totalHours = targetNodes.reduce((sum, node) => sum + toHourCount(node.json?.estimated_hours), 0);
+  const plan = targetNodes.map((node, index) => sliceToPlanItem(repoRoot, node, index + 1, readyRefs));
+
+  return {
+    critical_path: criticalPath,
+    plan,
+    total_hours: totalHours,
+  };
+}
+
+function formatHumanPlan(report, options = {}) {
+  const unicode = Boolean(options.unicode) || /UTF-8/i.test(process.env.LANG || '');
+  const title = options.onlyReady ? 'Ready slices' : 'Quiver plan';
+  const pathSeparator = unicode ? ' → ' : ' -> ';
+  const lines = [title, `Total hours: ${report.total_hours}`, `Critical path: ${report.critical_path.length > 0 ? report.critical_path.join(pathSeparator) : '-'}`, ''];
+
+  if (report.plan.length === 0) {
+    lines.push('No pending slices found.');
+    return `${lines.join('\n')}\n`;
+  }
+
+  const rows = report.plan.map((item) => [
+    `[${item.index}]`,
+    item.ticket || '-',
+    item.ref,
+    item.title,
+    `${item.hours}`,
+    item.status,
+  ]);
+
+  const widths = rows[0].map((_, colIndex) => Math.max(
+    rows.reduce((max, row) => Math.max(max, row[colIndex].length), 0),
+    ['[N]', 'TICKET', 'SPEC/SLICE', 'TITLE', 'HOURS', 'STATUS'][colIndex].length,
+  ));
+
+  lines.push(['[N]', 'TICKET', 'SPEC/SLICE', 'TITLE', 'HOURS', 'STATUS'].map((label, index) => label.padEnd(widths[index])).join('  '));
+  lines.push(widths.map((width) => '-'.repeat(width)).join('  '));
+
+  for (const row of rows) {
+    lines.push(row.map((value, index) => value.padEnd(widths[index])).join('  '));
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
+function runPlan(repoRoot, options = {}) {
+  const report = collectPlan(repoRoot, options);
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    return report;
+  }
+
+  process.stdout.write(formatHumanPlan(report, options));
+  return report;
+}
+
+module.exports = {
+  collectPlan,
+  formatHumanPlan,
+  runPlan,
+};