create-quiver 0.9.0 → 0.10.0

package/src/create-quiver/lib/ai/context-packs.js

@@ -0,0 +1,158 @@
+const { filterContextPaths, shouldExcludeContextPath } = require('./safety');
+const { buildRolePrompt } = require('./prompts');
+const { readProjectScanArtifact } = require('../project-scan');
+
+const ROLES = Object.freeze({
+  PLANNER: 'planner',
+  EXECUTOR: 'executor',
+});
+
+const CONTEXT_PACKS = Object.freeze({
+  full: Object.freeze({
+    name: 'full',
+    description: 'Broad planner onboarding context.',
+    role: ROLES.PLANNER,
+    tokenBudgetHint: 14000,
+    roleGuidance: 'Use broad onboarding context, project map, workflow docs, and relevant specs.',
+  }),
+  planning: Object.freeze({
+    name: 'planning',
+    description: 'Focused planner context for acceptance criteria and technical planning.',
+    role: ROLES.PLANNER,
+    tokenBudgetHint: 8000,
+    roleGuidance: 'Use project map, workflow docs, and only the specs needed for the current planning step.',
+  }),
+  slice: Object.freeze({
+    name: 'slice',
+    description: 'Executor context for a single slice handoff.',
+    role: ROLES.EXECUTOR,
+    tokenBudgetHint: 3200,
+    roleGuidance: 'Use slice handoff, allowed files, acceptance criteria, and validation commands only.',
+  }),
+  minimal: Object.freeze({
+    name: 'minimal',
+    description: 'Smallest executor context for narrowly-scoped tasks.',
+    role: ROLES.EXECUTOR,
+    tokenBudgetHint: 1200,
+    roleGuidance: 'Use the smallest safe set of slice details and avoid onboarding context.',
+  }),
+});
+
+const DEFAULT_CONTEXT_PACK_BY_ROLE = Object.freeze({
+  [ROLES.PLANNER]: 'planning',
+  [ROLES.EXECUTOR]: 'slice',
+});
+
+const PACK_ORDER = ['full', 'planning', 'slice', 'minimal'];
+
+function normalizeRole(role) {
+  const value = String(role || '').trim().toLowerCase();
+  if (value === ROLES.PLANNER || value === ROLES.EXECUTOR) {
+    return value;
+  }
+  throw new Error(`create-quiver: unsupported role '${role}'. Expected planner or executor.`);
+}
+
+function normalizePackName(packName) {
+  const value = String(packName || '').trim().toLowerCase();
+  if (CONTEXT_PACKS[value]) {
+    return value;
+  }
+  throw new Error(`create-quiver: unsupported context pack '${packName}'. Expected one of: ${PACK_ORDER.join(', ')}`);
+}
+
+function getDefaultContextPack(role) {
+  const normalizedRole = normalizeRole(role);
+  return DEFAULT_CONTEXT_PACK_BY_ROLE[normalizedRole];
+}
+
+function resolveContextPack({ role, packName } = {}) {
+  const normalizedRole = normalizeRole(role);
+  const defaultPack = getDefaultContextPack(normalizedRole);
+  const resolvedPackName = packName ? normalizePackName(packName) : defaultPack;
+
+  if (normalizedRole === ROLES.EXECUTOR && resolvedPackName === 'full') {
+    throw new Error('create-quiver: executor context cannot use the full pack by default.');
+  }
+
+  const pack = CONTEXT_PACKS[resolvedPackName];
+  if (pack.role !== normalizedRole && !(normalizedRole === ROLES.PLANNER && resolvedPackName === 'slice')) {
+    throw new Error(`create-quiver: context pack '${resolvedPackName}' is not valid for role '${normalizedRole}'.`);
+  }
+
+  return {
+    role: normalizedRole,
+    packName: resolvedPackName,
+    defaultPack,
+    isDefault: resolvedPackName === defaultPack,
+    tokenBudgetHint: pack.tokenBudgetHint,
+    pack,
+  };
+}
+
+function buildPackSelection({ role, packName, paths = [] } = {}) {
+  const resolved = resolveContextPack({ role, packName });
+  const { included, excluded } = filterContextPaths(paths);
+
+  return {
+    ...resolved,
+    includedPaths: included,
+    excludedPaths: excluded,
+  };
+}
+
+function resolveScanArtifactMetadata(repoRoot) {
+  if (!repoRoot) {
+    return null;
+  }
+
+  const artifact = readProjectScanArtifact(repoRoot);
+  if (!artifact) {
+    return null;
+  }
+
+  return {
+    path: artifact.relativePath,
+    source: artifact.source,
+  };
+}
+
+function buildContextPackMetadata(options = {}) {
+  const selection = buildPackSelection(options);
+
+  return {
+    role: selection.role,
+    packName: selection.packName,
+    isDefault: selection.isDefault,
+    tokenBudgetHint: selection.tokenBudgetHint,
+    description: selection.pack.description,
+    includedPaths: selection.includedPaths,
+    excludedPaths: selection.excludedPaths,
+    scanArtifact: resolveScanArtifactMetadata(options.repoRoot),
+    prompt: buildRolePrompt(selection.role, selection.pack),
+  };
+}
+
+function selectSafePaths(paths, options = {}) {
+  const selection = buildPackSelection({ ...options, paths });
+  return {
+    included: selection.includedPaths,
+    excluded: selection.excludedPaths,
+  };
+}
+
+module.exports = {
+  CONTEXT_PACKS,
+  DEFAULT_CONTEXT_PACK_BY_ROLE,
+  PACK_ORDER,
+  ROLES,
+  buildContextPackMetadata,
+  buildPackSelection,
+  getDefaultContextPack,
+  normalizePackName,
+  normalizeRole,
+  resolveScanArtifactMetadata,
+  resolveContextPack,
+  selectSafePaths,
+  shouldExcludeContextPath,
+};

package/src/create-quiver/lib/ai/execution-plan.js

@@ -0,0 +1,254 @@
+const { buildGraph, computeLevels, detectFileConflicts, isFoundationSliceId, readAllSlices, topoSort, SliceGraphError } = require('../slice-graph');
+
+const EXCLUDED_STATUSES = new Set(['completed', 'skipped', 'cancelled']);
+
+function formatError(message) {
+  return `create-quiver: ${message}`;
+}
+
+function summarizeSlice(node) {
+  return {
+    ref: node.ref,
+    spec_slug: node.specSlug,
+    slice_id: node.sliceId,
+    title: node.title || node.sliceId,
+    status: node.status || 'draft',
+    files: Array.isArray(node.files) ? node.files : [],
+    depends_on: Array.isArray(node.depends_on) ? node.depends_on : [],
+    parallel_safe: node.parallel_safe || null,
+    parallel_safe_reason: node.parallel_safe_reason || null,
+    branch_name: node.json?.git?.branch_name || '',
+  };
+}
+
+function buildPendingGraph(graph, options = {}) {
+  const specSlug = options.specSlug ? String(options.specSlug).trim() : '';
+  const pendingNodes = graph.nodes.filter((node) => {
+    if (specSlug && node.specSlug !== specSlug) {
+      return false;
+    }
+    return !EXCLUDED_STATUSES.has(String(node.status || '').toLowerCase());
+  });
+  const pendingRefs = new Set(pendingNodes.map((node) => node.ref));
+  const nodesBySpec = new Map();
+  const foundationRefsBySpec = new Map();
+
+  for (const node of pendingNodes) {
+    if (!nodesBySpec.has(node.specSlug)) {
+      nodesBySpec.set(node.specSlug, []);
+    }
+    nodesBySpec.get(node.specSlug).push(node);
+
+    if (isFoundationSliceId(node.sliceId)) {
+      if (!foundationRefsBySpec.has(node.specSlug)) {
+        foundationRefsBySpec.set(node.specSlug, []);
+      }
+      foundationRefsBySpec.get(node.specSlug).push(node.ref);
+    }
+  }
+
+  const edgeKey = (from, to) => `${from}::${to}`;
+  const edges = [];
+  const seenEdges = new Set();
+
+  for (const edge of graph.edges) {
+    if (!pendingRefs.has(edge.from) || !pendingRefs.has(edge.to)) {
+      continue;
+    }
+    const key = edgeKey(edge.from, edge.to);
+    if (seenEdges.has(key)) {
+      continue;
+    }
+    seenEdges.add(key);
+    edges.push({ from: edge.from, to: edge.to });
+  }
+
+  for (const [specSlug, specNodes] of nodesBySpec.entries()) {
+    const foundationRefs = foundationRefsBySpec.get(specSlug) || [];
+    if (foundationRefs.length === 0) {
+      continue;
+    }
+
+    for (const node of specNodes) {
+      if (isFoundationSliceId(node.sliceId)) {
+        continue;
+      }
+
+      for (const foundationRef of foundationRefs) {
+        const key = edgeKey(foundationRef, node.ref);
+        if (seenEdges.has(key)) {
+          continue;
+        }
+        seenEdges.add(key);
+        edges.push({ from: foundationRef, to: node.ref, implicit: true, reason: 'slice-00 foundation barrier' });
+      }
+    }
+  }
+
+  return {
+    nodes: pendingNodes,
+    edges,
+    foundationRefs: Array.from(foundationRefsBySpec.values()).flat().sort((left, right) => String(left).localeCompare(String(right))),
+  };
+}
+
+function buildLevelStrategy(levelNodes) {
+  if (levelNodes.length > 1) {
+    return {
+      mode: 'temporary-per-slice',
+      temporary_worktrees: true,
+      reason: 'Run each ready slice in its own temporary worktree, then integrate the commits in stable level order.',
+    };
+  }
+
+  return {
+    mode: 'shared-worktree',
+    temporary_worktrees: false,
+    reason: 'A single ready slice can reuse the active worktree.',
+  };
+}
+
+function summarizeLevel(levelNodes, index) {
+  const slices = levelNodes.map(summarizeSlice);
+  const sliceRefs = slices.map((slice) => slice.ref);
+  const conflicts = detectFileConflicts(levelNodes).map((group) => ({
+    files: group.files,
+    slices: group.slices,
+  }));
+
+  return {
+    index,
+    slice_refs: sliceRefs,
+    parallel_ready: levelNodes.length > 1,
+    requires_temporary_worktrees: levelNodes.length > 1,
+    worktree_strategy: buildLevelStrategy(levelNodes),
+    conflicts,
+    slices,
+  };
+}
+
+function collectExecutionPlan(repoRoot, options = {}) {
+  try {
+    const allSlices = readAllSlices(repoRoot);
+    const graph = buildGraph(allSlices);
+    topoSort(graph);
+
+    const specSlug = options.specSlug ? String(options.specSlug).trim() : '';
+    const pendingGraph = buildPendingGraph(graph, { specSlug });
+    if (pendingGraph.nodes.length === 0) {
+      return {
+        root: repoRoot,
+        summary: {
+          total_slices: 0,
+          ready_levels: 0,
+          parallel_levels: 0,
+          foundation_refs: [],
+        },
+        ready_levels: [],
+        levels: [],
+        execution_order: [],
+        integration_order: [],
+        sequential_order: [],
+      };
+    }
+
+    const readyLevels = computeLevels(pendingGraph);
+    const readyLevelReports = readyLevels.map((levelNodes, index) => summarizeLevel(levelNodes, index));
+    const executionOrder = topoSort(pendingGraph).map((node) => node.ref);
+    const integrationOrder = readyLevelReports.flatMap((level) => level.slice_refs);
+    const foundationRefs = pendingGraph.foundationRefs;
+
+    return {
+      root: repoRoot,
+      summary: {
+        total_slices: pendingGraph.nodes.length,
+        ready_levels: readyLevelReports.length,
+        parallel_levels: readyLevelReports.filter((level) => level.parallel_ready).length,
+        foundation_refs: foundationRefs,
+      },
+      ready_levels: readyLevelReports,
+      levels: readyLevelReports,
+      execution_order: executionOrder,
+      integration_order: integrationOrder,
+      sequential_order: executionOrder,
+      options: {
+        specSlug,
+      },
+    };
+  } catch (error) {
+    if (error instanceof SliceGraphError) {
+      throw error;
+    }
+    throw new Error(formatError(`unable to build execution plan: ${error.message || error}`));
+  }
+}
+
+function formatHumanExecutionPlan(report) {
+  const lines = [
+    'Execution plan',
+    `Total slices: ${report.summary.total_slices}`,
+    `Ready levels: ${report.summary.ready_levels}`,
+    `Parallel levels: ${report.summary.parallel_levels}`,
+    `Foundation refs: ${report.summary.foundation_refs.length > 0 ? report.summary.foundation_refs.join(', ') : '-'}`,
+    '',
+    'Sequential order',
+  ];
+
+  if (report.sequential_order.length === 0) {
+    lines.push('- none');
+  } else {
+    for (const [index, ref] of report.sequential_order.entries()) {
+      lines.push(`${index + 1}. ${ref}`);
+    }
+  }
+
+  lines.push('', 'Ready levels');
+
+  if (report.ready_levels.length === 0) {
+    lines.push('- none');
+    return `${lines.join('\n')}\n`;
+  }
+
+  for (const level of report.ready_levels) {
+    const modeLabel = level.parallel_ready ? 'parallel' : 'sequential';
+    lines.push(`Level ${level.index} (${modeLabel})`);
+    lines.push(`Worktree strategy: ${level.worktree_strategy.mode}`);
+
+    for (const slice of level.slices) {
+      lines.push(`- ${slice.ref} [${slice.status}]`);
+    }
+
+    if (level.conflicts.length > 0) {
+      lines.push('Conflicts:');
+      for (const conflict of level.conflicts) {
+        lines.push(`- ${conflict.slices.join(', ')} :: ${conflict.files.join(', ')}`);
+      }
+    }
+
+    lines.push('');
+  }
+
+  lines.push('Integration order');
+  for (const [index, ref] of report.integration_order.entries()) {
+    lines.push(`${index + 1}. ${ref}`);
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
+function runExecutionPlan(repoRoot, options = {}) {
+  const report = collectExecutionPlan(repoRoot, options);
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    return report;
+  }
+
+  process.stdout.write(formatHumanExecutionPlan(report, options));
+  return report;
+}
+
+module.exports = {
+  collectExecutionPlan,
+  formatHumanExecutionPlan,
+  runExecutionPlan,
+};