create-quiver 0.12.1 → 0.14.0

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

@@ -4,6 +4,7 @@ const path = require('path');
 const { readPhaseApproval } = require('../lib/approvals');
 const { readPlanReview } = require('../lib/ai/plan-review');
 const { listAgentProfiles } = require('../lib/agent-profiles');
+const { readProjectScanStatus } = require('../lib/project-scan');
 const { buildGraph, naturalNumberFromSliceId, readAllSlices } = require('../lib/slice-graph');
 const { hasQuiverInitializationEvidence, readState } = require('../lib/state');
 
@@ -11,6 +12,46 @@ function exists(projectRoot, relativePath) {
   return fs.existsSync(path.join(projectRoot, relativePath));
 }
 
+function readJsonIfExists(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function detectPackageManager(projectRoot) {
+  const packageManagerField = readJsonIfExists(path.join(projectRoot, 'package.json'))?.packageManager;
+  if (typeof packageManagerField === 'string' && packageManagerField.trim()) {
+    return packageManagerField.split('@')[0];
+  }
+
+  const signals = [
+    ['bun', 'bun.lockb'],
+    ['bun', 'bun.lock'],
+    ['pnpm', 'pnpm-lock.yaml'],
+    ['yarn', 'yarn.lock'],
+    ['npm', 'package-lock.json'],
+  ];
+
+  for (const [manager, filename] of signals) {
+    if (exists(projectRoot, filename)) {
+      return manager;
+    }
+  }
+
+  return 'npm';
+}
+
+function formatRunScriptCommand(packageManager, scriptName) {
+  const manager = ['npm', 'pnpm', 'yarn', 'bun'].includes(packageManager) ? packageManager : 'npm';
+  return `${manager} run ${scriptName}`;
+}
+
 function listSpecSlugs(projectRoot) {
   const specsDir = path.join(projectRoot, 'specs');
   if (!fs.existsSync(specsDir)) {
@@ -53,6 +94,7 @@ function summarizeDocs(projectRoot) {
     hasProjectMap: exists(projectRoot, 'docs/PROJECT_MAP.md'),
     hasAiContext: exists(projectRoot, 'docs/AI_CONTEXT.md'),
     hasOnboardingPrompt: exists(projectRoot, 'docs/AI_ONBOARDING_PROMPT.md'),
+    scanStatus: readProjectScanStatus(projectRoot),
   };
   const missing = [
     ['docs/PROJECT_MAP.md', docs.hasProjectMap],
@@ -77,7 +119,7 @@ function summarizeAgentProfiles(projectRoot) {
   };
 }
 
-function buildFacts({ initialized, docs, approvals, planReview, agents, specSlugs, state, slices = null }) {
+function buildFacts({ initialized, docs, approvals, planReview, agents, packageManager, specSlugs, state, slices = null }) {
   return {
     initialized,
     hasProjectMap: docs.hasProjectMap,
@@ -91,6 +133,9 @@ function buildFacts({ initialized, docs, approvals, planReview, agents, specSlug
     agents,
     specSlugs,
     slices,
+    contextSource: docs.scanStatus,
+    packageManager,
+    flowScriptCommand: formatRunScriptCommand(packageManager, 'quiver:flow'),
     quiverVersion: state?.quiver_version || null,
   };
 }
@@ -207,8 +252,9 @@ function detectFlowState(projectRoot) {
   };
   const planReview = safeReadPlanReview(projectRoot);
   const agents = summarizeAgentProfiles(projectRoot);
+  const packageManager = detectPackageManager(projectRoot);
   const specSlugs = listSpecSlugs(projectRoot);
-  const facts = buildFacts({ initialized, docs, approvals, planReview, agents, specSlugs, state });
+  const facts = buildFacts({ initialized, docs, approvals, planReview, agents, packageManager, specSlugs, state });
 
   if (!initialized) {
     return baseReport({
@@ -430,7 +476,7 @@ function detectFlowState(projectRoot) {
   }
 
   const slices = summarizeSlices(projectRoot, specSlugs);
-  const sliceFacts = buildFacts({ initialized, docs, approvals, planReview, agents, specSlugs, state, slices: {
+  const sliceFacts = buildFacts({ initialized, docs, approvals, planReview, agents, packageManager, specSlugs, state, slices: {
     completed: slices.completedCount,
     pending: slices.pendingCount,
     ready: slices.ready.map((slice) => slice.ref),
@@ -516,10 +562,12 @@ function formatFlowReport(report) {
     'Command path:',
     '- Bootstrap and remote use: npx create-quiver <command>',
     '- Short alias after local install: quiver <command>',
-    '- Generated npm script: npm run quiver:flow',
+    `- Generated project script: ${report.facts.flowScriptCommand}`,
     '',
+    `Package manager: ${report.facts.packageManager}`,
     `Stage: ${report.label}`,
     `Next safe command: ${report.nextCommand}`,
+    `Context source: ${report.facts.contextSource.summary}`,
   ];
 
   if (report.blockers.length > 0) {

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

@@ -1,11 +1,9 @@
-const { buildGraph, computeLevels, detectFileConflicts, readAllSlices, readSlicesForSpec } = require('../lib/slice-graph');
+const { filterSlicesForExecution, resolveProjectState } = require('../lib/project-state-resolver');
+const { computeLevels, detectFileConflicts } = 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']);
-const HISTORY_EXCLUDED_STATUSES = new Set(['skipped', 'cancelled']);
-
 function toGraphNode(node) {
   return {
     ref: node.ref,
@@ -14,6 +12,7 @@ function toGraphNode(node) {
     title: node.title || node.sliceId,
     hours: Number.isFinite(Number(node.json?.estimated_hours)) ? Number(node.json.estimated_hours) : 0,
     status: node.status || 'draft',
+    canonical_status: node.canonical_status || 'planned',
     files: Array.isArray(node.files) ? node.files : [],
     depends_on: Array.isArray(node.depends_on) ? node.depends_on : [],
   };
@@ -29,14 +28,15 @@ function buildConflictPayload(levelIndex, groups) {
 
 function collectGraph(repoRoot, options = {}) {
   const specSlug = options.specSlug ? String(options.specSlug).trim() : '';
-  const graph = buildGraph(specSlug ? readSlicesForSpec(repoRoot, specSlug) : readAllSlices(repoRoot));
+  const state = resolveProjectState(repoRoot, { specSlug });
+  const graph = state.graph;
   if (!specSlug) {
     computeLevels(graph);
   }
   const includeCompleted = options.includeCompleted === true;
-  const excluded = includeCompleted ? HISTORY_EXCLUDED_STATUSES : EXCLUDED_STATUSES;
+  const executionRefs = new Set(filterSlicesForExecution(graph.nodes, { includeCompleted }).map((node) => node.ref));
   const pendingNodes = graph.nodes.filter((node) => {
-    if (excluded.has(String(node.status || '').toLowerCase())) {
+    if (!executionRefs.has(node.ref)) {
       return false;
     }
     if (specSlug && node.specSlug !== specSlug) {

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

@@ -1,10 +1,6 @@
-const fs = require('fs');
-const path = require('path');
 const { relativePosixPath } = require('../lib/paths');
-const { buildGraph, readAllSlices, readSlicesForSpec, topoSort } = require('../lib/slice-graph');
-
-const EXCLUDED_STATUSES = new Set(['completed', 'skipped', 'cancelled']);
-const HISTORY_EXCLUDED_STATUSES = new Set(['skipped', 'cancelled']);
+const { filterSlicesForExecution, resolveProjectState } = require('../lib/project-state-resolver');
+const { topoSort } = require('../lib/slice-graph');
 
 function toHourCount(value) {
   const parsed = Number(value);
@@ -26,6 +22,7 @@ function sliceToPlanItem(repoRoot, slice, index, readySet) {
     ticket: slice.ticket || '',
     title: slice.title || slice.sliceId,
     status: slice.status || 'draft',
+    canonical_status: slice.canonical_status || 'planned',
     hours: toHourCount(slice.json?.estimated_hours),
     files: Array.isArray(slice.files) ? slice.files : [],
     depends_on: Array.isArray(slice.depends_on) ? slice.depends_on : [],
@@ -117,17 +114,11 @@ function buildCriticalPath(graph, refs) {
 
 function collectPlan(repoRoot, options = {}) {
   const specSlug = options.specSlug ? String(options.specSlug).trim() : '';
-  const allSlices = specSlug ? readSlicesForSpec(repoRoot, specSlug) : readAllSlices(repoRoot);
-  const graph = buildGraph(allSlices);
+  const state = resolveProjectState(repoRoot, { specSlug });
+  const graph = state.graph;
   const topo = topoSort(graph);
   const includeCompleted = options.includeCompleted === true;
-  const excluded = includeCompleted ? HISTORY_EXCLUDED_STATUSES : EXCLUDED_STATUSES;
-
-  const pendingRefs = new Set(
-    graph.nodes
-      .filter((node) => !excluded.has(String(node.status || '').toLowerCase()))
-      .map((node) => node.ref),
-  );
+  const pendingRefs = new Set(filterSlicesForExecution(graph.nodes, { includeCompleted }).map((node) => node.ref));
 
   const readyRefs = buildReadySet(graph, Array.from(pendingRefs));
 

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

@@ -1,6 +1,9 @@
 const fs = require('node:fs');
 const path = require('node:path');
 
+const { checkHandoff } = require('../lib/handoff');
+const { parseJsonWithComments } = require('../lib/json');
+const { assertPathInsideRoot, validateProjectRelativePaths } = require('../lib/paths');
 const { resolveReviewedTechnicalPlanInput } = require('../lib/ai/plan-review');
 const {
   buildSpecGenerationManifest,
@@ -24,6 +27,292 @@ function readInputText(repoRoot, inputPath) {
   return fs.readFileSync(resolved, 'utf8');
 }
 
+function resolveSpecDir(repoRoot, specInput) {
+  const value = String(specInput || '').trim();
+  if (!value) {
+    throw new Error(formatError('missing spec directory. Use: npx create-quiver spec validate specs/<spec-slug>'));
+  }
+
+  const candidates = [
+    path.resolve(repoRoot, value),
+    path.resolve(repoRoot, 'specs', value),
+    path.resolve(repoRoot, 'specs-fix', value),
+  ];
+
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate) && fs.statSync(candidate).isDirectory()) {
+      assertPathInsideRoot(repoRoot, candidate, 'spec path');
+      return candidate;
+    }
+  }
+
+  throw new Error(formatError(`spec directory not found: ${value}`));
+}
+
+function findSliceJsonFiles(specDir) {
+  const slicesRoot = path.join(specDir, 'slices');
+  const files = [];
+  if (!fs.existsSync(slicesRoot)) {
+    return files;
+  }
+
+  const stack = [slicesRoot];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const fullPath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(fullPath);
+      } else if (entry.isFile() && entry.name === 'slice.json') {
+        files.push(fullPath);
+      }
+    }
+  }
+
+  return files.sort();
+}
+
+function shortSliceId(sliceId) {
+  const match = String(sliceId || '').match(/^(slice-\d+)/);
+  return match ? match[1] : String(sliceId || '');
+}
+
+function normalizeDependency(specSlug, sliceId, dep) {
+  const value = String(dep || '').trim();
+  if (!value) {
+    return '';
+  }
+  if (value.includes('/')) {
+    return value;
+  }
+  return `${specSlug}/${value}`;
+}
+
+function detectCycle(nodes) {
+  const visiting = new Set();
+  const visited = new Set();
+  const stack = [];
+
+  function visit(ref) {
+    if (visiting.has(ref)) {
+      const start = stack.indexOf(ref);
+      return [...stack.slice(start), ref];
+    }
+    if (visited.has(ref)) {
+      return null;
+    }
+
+    visiting.add(ref);
+    stack.push(ref);
+    const node = nodes.get(ref);
+    for (const dep of node?.deps || []) {
+      if (!nodes.has(dep)) {
+        continue;
+      }
+      const cycle = visit(dep);
+      if (cycle) {
+        return cycle;
+      }
+    }
+    stack.pop();
+    visiting.delete(ref);
+    visited.add(ref);
+    return null;
+  }
+
+  for (const ref of nodes.keys()) {
+    const cycle = visit(ref);
+    if (cycle) {
+      return cycle;
+    }
+  }
+  return null;
+}
+
+function missingGitFields(git) {
+  const data = git && typeof git === 'object' ? git : {};
+  return ['branch_type', 'base_branch', 'branch_slug', 'branch_name']
+    .filter((field) => !String(data[field] || '').trim());
+}
+
+function buildSpecValidationReport(repoRoot, specInput, options = {}) {
+  const strict = options.strict === true;
+  const specDir = resolveSpecDir(repoRoot, specInput);
+  const relativeSpecDir = toRelativePosix(repoRoot, specDir);
+  const specSlug = path.basename(specDir);
+  const errors = [];
+  const warnings = [];
+  const checked = [];
+  const docs = ['SPEC.md', 'STATUS.md', 'EVIDENCE_REPORT.md'];
+  const docText = {};
+
+  for (const doc of docs) {
+    const filePath = path.join(specDir, doc);
+    if (!fs.existsSync(filePath)) {
+      errors.push(`missing required spec document: ${relativeSpecDir}/${doc}`);
+      continue;
+    }
+    docText[doc] = fs.readFileSync(filePath, 'utf8');
+    checked.push(`${relativeSpecDir}/${doc}`);
+  }
+
+  const sliceFiles = findSliceJsonFiles(specDir);
+  if (sliceFiles.length === 0) {
+    errors.push(`spec has no slices: ${relativeSpecDir}/slices`);
+  }
+
+  const nodes = new Map();
+  const seenSliceIds = new Set();
+
+  for (const sliceFile of sliceFiles) {
+    const relativeSliceFile = toRelativePosix(repoRoot, sliceFile);
+    checked.push(relativeSliceFile);
+
+    let json;
+    try {
+      json = parseJsonWithComments(fs.readFileSync(sliceFile, 'utf8'));
+    } catch (error) {
+      errors.push(`invalid JSON in ${relativeSliceFile}: ${error.message}`);
+      continue;
+    }
+
+    const sliceId = String(json.slice_id || '').trim();
+    const expectedSliceId = path.basename(path.dirname(sliceFile));
+    if (!sliceId) {
+      errors.push(`${relativeSliceFile} is missing slice_id`);
+      continue;
+    }
+    if (sliceId !== expectedSliceId) {
+      errors.push(`${relativeSliceFile} slice_id must match directory name (${expectedSliceId})`);
+    }
+    if (seenSliceIds.has(sliceId)) {
+      errors.push(`duplicate slice_id in spec: ${sliceId}`);
+    }
+    seenSliceIds.add(sliceId);
+
+    const writeScope = Array.isArray(json.allowed_write_paths) && json.allowed_write_paths.length > 0
+      ? json.allowed_write_paths
+      : json.files;
+    if (!Array.isArray(writeScope) || writeScope.length === 0) {
+      errors.push(`${relativeSliceFile} must declare files or allowed_write_paths`);
+    }
+    const missingGit = missingGitFields(json.git);
+    if (missingGit.length > 0) {
+      errors.push(`${relativeSliceFile} must declare git.branch_type, git.base_branch, git.branch_slug, and git.branch_name for local execution (missing: ${missingGit.join(', ')}).`);
+    }
+    try {
+      validateProjectRelativePaths(writeScope, `${relativeSliceFile} write scope`);
+      validateProjectRelativePaths(json.expected_read_paths, `${relativeSliceFile} expected_read_paths`);
+    } catch (error) {
+      errors.push(error.message);
+    }
+
+    for (const briefName of ['EXECUTION_BRIEF.md', 'CLOSURE_BRIEF.md']) {
+      const briefRel = toRelativePosix(repoRoot, path.join(path.dirname(sliceFile), briefName));
+      try {
+        checkHandoff(briefRel, repoRoot);
+        checked.push(briefRel);
+      } catch (error) {
+        errors.push(error.message);
+      }
+    }
+
+    const ref = `${specSlug}/${sliceId}`;
+    const deps = (Array.isArray(json.depends_on) ? json.depends_on : [])
+      .map((dep) => normalizeDependency(specSlug, sliceId, dep))
+      .filter(Boolean);
+    nodes.set(ref, { deps, json, ref, sliceId });
+
+    const statusNeedle = shortSliceId(sliceId);
+    if (docText['STATUS.md'] && !docText['STATUS.md'].includes(sliceId) && !docText['STATUS.md'].includes(statusNeedle)) {
+      warnings.push(`STATUS.md does not reference ${sliceId}`);
+    }
+
+    if (String(json.status || '').trim() === 'completed') {
+      if (!json.completed_at) {
+        warnings.push(`${relativeSliceFile} is completed but missing completed_at`);
+      }
+      if (docText['EVIDENCE_REPORT.md'] && !docText['EVIDENCE_REPORT.md'].includes(sliceId) && !docText['EVIDENCE_REPORT.md'].includes(statusNeedle)) {
+        warnings.push(`EVIDENCE_REPORT.md does not reference completed slice ${sliceId}`);
+      }
+    }
+  }
+
+  for (const [ref, node] of nodes.entries()) {
+    for (const dep of node.deps) {
+      if (dep.startsWith(`${specSlug}/`) && !nodes.has(dep)) {
+        errors.push(`${ref} depends on missing slice ${dep}`);
+      }
+    }
+  }
+
+  const cycle = detectCycle(nodes);
+  if (cycle) {
+    errors.push(`dependency cycle detected: ${cycle.join(' -> ')}`);
+  }
+
+  if (strict && warnings.length > 0) {
+    errors.push(...warnings.map((warning) => `strict warning: ${warning}`));
+  }
+
+  return {
+    ok: errors.length === 0,
+    specDir: relativeSpecDir,
+    checked,
+    errors,
+    warnings,
+    slices: sliceFiles.length,
+    strict,
+  };
+}
+
+function formatSpecValidationReport(report) {
+  const lines = [
+    'Quiver spec validation',
+    `Spec: ${report.specDir}`,
+    `Slices: ${report.slices}`,
+    `Strict: ${report.strict ? 'yes' : 'no'}`,
+  ];
+
+  if (report.checked.length > 0) {
+    lines.push('Checked files:');
+    for (const file of report.checked) {
+      lines.push(`- ${file}`);
+    }
+  }
+
+  if (report.warnings.length > 0) {
+    lines.push('Warnings:');
+    for (const warning of report.warnings) {
+      lines.push(`- ${warning}`);
+    }
+  }
+
+  if (report.errors.length > 0) {
+    lines.push('Errors:');
+    for (const error of report.errors) {
+      lines.push(`- ${error}`);
+    }
+  }
+
+  lines.push(report.ok ? 'PASS: spec validation passed.' : 'FAIL: spec validation failed.');
+  return `${lines.join('\n')}\n`;
+}
+
+function runValidateSpec(repoRoot, specInput, options = {}) {
+  const report = buildSpecValidationReport(repoRoot, specInput, options);
+  process.stdout.write(formatSpecValidationReport(report));
+
+  if (!report.ok) {
+    const error = new Error(formatError(`spec validate failed for ${report.specDir}`));
+    error.code = 'SPEC_VALIDATE_FAILED';
+    error.details = report;
+    throw error;
+  }
+
+  return report;
+}
+
 function buildSpecCreatePreview(repoRoot, options = {}) {
   const resolved = resolveReviewedTechnicalPlanInput(repoRoot, options.input || undefined);
   const inputPath = resolved.inputPath;
@@ -126,8 +415,11 @@ function runCreateSpec(repoRoot, options = {}) {
 }
 
 module.exports = {
+  buildSpecValidationReport,
   buildSpecCreatePreview,
   formatSpecCreateDryRun,
   formatSpecCreateResult,
+  formatSpecValidationReport,
   runCreateSpec,
+  runValidateSpec,
 };