create-quiver 0.15.1 → 0.15.3

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

@@ -2,6 +2,7 @@ const fs = require('fs');
 const path = require('path');
 
 const { readPhaseApproval } = require('../lib/approvals');
+const { approvalCandidateCommand, buildApprovalCandidateReport, formatCandidateSummary } = require('../lib/ai/approval-candidates');
 const { readPlanReview } = require('../lib/ai/plan-review');
 const { listAgentProfiles } = require('../lib/agent-profiles');
 const { readProjectScanStatus } = require('../lib/project-scan');
@@ -89,6 +90,25 @@ function safeReadPlanReview(projectRoot) {
   }
 }
 
+function safeBuildApprovalCandidateReport(projectRoot, phase) {
+  try {
+    return buildApprovalCandidateReport(projectRoot, phase);
+  } catch (error) {
+    return {
+      phase,
+      approval_status: 'invalid',
+      latest_version: null,
+      current: null,
+      recommended: null,
+      candidates: [],
+      history: [],
+      approved: null,
+      next_command: 'npx create-quiver ai approvals',
+      error: error.message,
+    };
+  }
+}
+
 function summarizeDocs(projectRoot) {
   const docs = {
     hasProjectMap: exists(projectRoot, 'docs/PROJECT_MAP.md'),
@@ -250,11 +270,23 @@ function detectFlowState(projectRoot) {
     acceptance: safeReadApproval(projectRoot, 'acceptance'),
     technicalPlan: safeReadApproval(projectRoot, 'technical-plan'),
   };
+  const approvalCandidates = {
+    acceptance: safeBuildApprovalCandidateReport(projectRoot, 'acceptance'),
+    technicalPlan: safeBuildApprovalCandidateReport(projectRoot, 'technical-plan'),
+  };
   const planReview = safeReadPlanReview(projectRoot);
   const agents = summarizeAgentProfiles(projectRoot);
   const packageManager = detectPackageManager(projectRoot);
   const specSlugs = listSpecSlugs(projectRoot);
   const facts = buildFacts({ initialized, docs, approvals, planReview, agents, packageManager, specSlugs, state });
+  const acceptanceApprovalCommand = approvalCandidateCommand(
+    approvalCandidates.acceptance,
+    'npx create-quiver ai approve --phase acceptance --version <n>',
+  );
+  const technicalPlanApprovalCommand = approvalCandidateCommand(
+    approvalCandidates.technicalPlan,
+    'npx create-quiver ai approve --phase technical-plan --version <n>',
+  );
 
   if (!initialized) {
     return baseReport({
@@ -334,12 +366,12 @@ function detectFlowState(projectRoot) {
     return baseReport({
       stage: 'criteria-draft',
       label: 'acceptance criteria need approval',
-      blockers: ['Acceptance criteria draft exists but is not approved.'],
-      nextCommand: 'npx create-quiver ai approve --phase acceptance --version <n>',
+      blockers: ['Acceptance criteria draft exists but is not approved.', formatCandidateSummary(approvalCandidates.acceptance.current)].filter(Boolean),
+      nextCommand: acceptanceApprovalCommand,
       suggestedCommands: [
         'npx create-quiver ai approvals',
         'npx create-quiver ai revise --phase acceptance --input feedback.md --dry-run',
-        'npx create-quiver ai approve --phase acceptance --version <n>',
+        acceptanceApprovalCommand,
       ],
       facts,
     });
@@ -349,12 +381,12 @@ function detectFlowState(projectRoot) {
     return baseReport({
       stage: 'criteria-stale',
       label: 'acceptance criteria approval is stale',
-      blockers: ['Acceptance criteria changed after approval.'],
-      nextCommand: 'npx create-quiver ai approve --phase acceptance --version <n>',
+      blockers: ['Acceptance criteria changed after approval.', formatCandidateSummary(approvalCandidates.acceptance.current)].filter(Boolean),
+      nextCommand: acceptanceApprovalCommand,
       suggestedCommands: [
         'npx create-quiver ai approvals',
         'npx create-quiver ai revise --phase acceptance --input feedback.md --dry-run',
-        'npx create-quiver ai approve --phase acceptance --version <n>',
+        acceptanceApprovalCommand,
       ],
       facts,
     });
@@ -390,14 +422,29 @@ function detectFlowState(projectRoot) {
       });
     }
 
+    if (!approvalCandidates.technicalPlan.current?.approvable) {
+      return baseReport({
+        stage: 'technical-plan-review-blocked',
+        label: 'technical plan review requires revision',
+        blockers: ['Technical plan review blocks approval.', formatCandidateSummary(approvalCandidates.technicalPlan.current)].filter(Boolean),
+        nextCommand: approvalCandidates.technicalPlan.current?.next_command || 'npx create-quiver ai revise --phase technical-plan --input <feedback.md> --dry-run',
+        suggestedCommands: [
+          'npx create-quiver ai approvals',
+          approvalCandidates.technicalPlan.current?.next_command || 'npx create-quiver ai revise --phase technical-plan --input <feedback.md> --dry-run',
+          'npx create-quiver ai review-plan --dry-run',
+        ],
+        facts,
+      });
+    }
+
     return baseReport({
       stage: 'technical-plan-draft',
       label: 'technical plan needs approval',
-      blockers: ['Technical plan draft was reviewed but is not approved.'],
-      nextCommand: 'npx create-quiver ai approve --phase technical-plan --version <n>',
+      blockers: ['Technical plan draft was reviewed but is not approved.', formatCandidateSummary(approvalCandidates.technicalPlan.current)].filter(Boolean),
+      nextCommand: technicalPlanApprovalCommand,
       suggestedCommands: [
         'npx create-quiver ai approvals',
-        'npx create-quiver ai approve --phase technical-plan --version <n>',
+        technicalPlanApprovalCommand,
       ],
       facts,
     });
@@ -419,14 +466,29 @@ function detectFlowState(projectRoot) {
       });
     }
 
+    if (!approvalCandidates.technicalPlan.current?.approvable) {
+      return baseReport({
+        stage: 'technical-plan-review-blocked',
+        label: 'technical plan review requires revision',
+        blockers: ['Technical plan changed after approval and latest review blocks approval.', formatCandidateSummary(approvalCandidates.technicalPlan.current)].filter(Boolean),
+        nextCommand: approvalCandidates.technicalPlan.current?.next_command || 'npx create-quiver ai revise --phase technical-plan --input <feedback.md> --dry-run',
+        suggestedCommands: [
+          'npx create-quiver ai approvals',
+          approvalCandidates.technicalPlan.current?.next_command || 'npx create-quiver ai revise --phase technical-plan --input <feedback.md> --dry-run',
+          'npx create-quiver ai review-plan --dry-run',
+        ],
+        facts,
+      });
+    }
+
     return baseReport({
       stage: 'technical-plan-stale',
       label: 'technical plan approval is stale',
-      blockers: ['Technical plan changed after approval and the latest draft was reviewed.'],
-      nextCommand: 'npx create-quiver ai approve --phase technical-plan --version <n>',
+      blockers: ['Technical plan changed after approval and the latest draft was reviewed.', formatCandidateSummary(approvalCandidates.technicalPlan.current)].filter(Boolean),
+      nextCommand: technicalPlanApprovalCommand,
       suggestedCommands: [
         'npx create-quiver ai approvals',
-        'npx create-quiver ai approve --phase technical-plan --version <n>',
+        technicalPlanApprovalCommand,
       ],
       facts,
     });

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

@@ -7,6 +7,7 @@ const { selectOption } = require('../lib/cli/selectors');
 const { createUx } = require('../lib/cli/ux');
 const { parseJsonWithComments } = require('../lib/json');
 const { assertPathInsideRoot, validateProjectRelativePaths } = require('../lib/paths');
+const { buildApprovalCandidateReport, formatReviewSummary } = require('../lib/ai/approval-candidates');
 const { resolveReviewedTechnicalPlanInput } = require('../lib/ai/plan-review');
 const {
   buildSpecGenerationManifest,
@@ -439,6 +440,11 @@ async function resolveInteractiveSpecCreateOptions(repoRoot, preview, options =
     stdinIsTTY: options.stdinIsTTY,
     stdoutIsTTY: options.stdoutIsTTY,
   };
+  const technicalPlanCandidates = buildApprovalCandidateReport(repoRoot, 'technical-plan');
+  const approvedVersion = technicalPlanCandidates.approved?.version
+    ? `v${technicalPlanCandidates.approved.version}`
+    : 'approved';
+  const reviewSummary = formatReviewSummary(technicalPlanCandidates.review);
   const selectedMethodology = await selectOption('¿Qué metodología aplica esta spec?', SPEC_METHODOLOGY_OPTIONS, {
     ...selectorOptions,
     defaultValue: 'wdd-sdd',
@@ -450,7 +456,7 @@ async function resolveInteractiveSpecCreateOptions(repoRoot, preview, options =
     {
       label: preview.inputPath,
       value: preview.inputPath,
-      hint: 'Plan técnico revisado y aprobado',
+      hint: ['Plan técnico revisado y aprobado', approvedVersion, reviewSummary].filter(Boolean).join(', '),
       default: true,
     },
   ], {
@@ -484,6 +490,7 @@ async function resolveInteractiveSpecCreateOptions(repoRoot, preview, options =
     { label: 'Spec', value: preview.manifest.slug },
     { label: 'Metodologia', value: selectedMethodology.label },
     { label: 'Input', value: selectedInput.value },
+    { label: 'Plan tecnico', value: ['aprobado', approvedVersion, reviewSummary].filter(Boolean).join(', ') },
     { label: 'Target', value: preview.relativeSpecDir },
     { label: 'Archivos planificados', value: preview.preview.files.length },
     { label: 'Revision', value: selectedReview.value === 'review' ? 'abrir preview' : 'confirmacion directa' },

package/src/create-quiver/index.js

@@ -35,6 +35,7 @@ const {
   runSpecsList: runAiSpecsList,
   runTraceReport: runAiTraceReport,
 } = require('./commands/ai');
+const { runDashboard } = require('./commands/dashboard');
 const { runDemo } = require('./commands/demo');
 const { runPrepare } = require('./commands/prepare');
 const { runEvidence } = require('./commands/evidence');
@@ -43,6 +44,7 @@ const { runGraph } = require('./commands/graph');
 const { runNext } = require('./commands/next');
 const { runPlan } = require('./commands/plan');
 const { runCreateSpec, runValidateSpec } = require('./commands/spec');
+const { collectVersionReport, formatHumanVersionReport } = require('./lib/version');
 const { buildInitLayout, formatInitLayoutPlan } = require('./lib/init-layout');
 const {
   formatInstallSelfCommand,
@@ -82,7 +84,9 @@ function formatError(message) {
 
 const SUPPORTED_COMMAND_MODES = new Set([
   'init',
+  'version',
   'flow',
+  'dashboard',
   'plan',
   'graph',
   'next',
@@ -152,6 +156,8 @@ const COMMAND_HELP_GROUPS = [
       ['analyze', 'Scan the project and write docs/PROJECT_MAP.md plus .quiver scan data.'],
       ['doctor', 'Validate the Quiver layout, generated docs, environment, and next safe steps.'],
       ['flow', 'Show the read-only guided workflow stage, blockers, and next safe command.'],
+      ['dashboard', 'Show compact read-only project, spec, slice, run, approval, and agent status.'],
+      ['version', 'Show a Quiver-branded version report; use --json for metadata.'],
       ['prepare', 'Run setup diagnostics for providers, GitHub, SSH, and project readiness.'],
       ['migrate', 'Upgrade an already initialized Quiver project to the current contract.'],
     ],
@@ -251,6 +257,8 @@ function printUsage() {
   npx create-quiver init [options]
   npx create-quiver analyze [options]
   npx create-quiver flow [options]
+  npx create-quiver dashboard [options]
+  npx create-quiver version [--json]
   npx create-quiver plan [options]
   npx create-quiver ai <task> [options]
   npx create-quiver ai run create --input <requirements.md>
@@ -294,12 +302,15 @@ ${formatCommandHelpGroups()}
 Options:
   -n, --name <project-name>   Project name to generate
   -d, --dir <target-dir>      Target directory to scaffold into or inspect
-      --spec <slug>           Restrict plan output to one spec
+      --spec <slug>           Restrict plan, graph, next, or dashboard output to one spec
       --format <name>         Graph or AI export output format (tree, mermaid, dot, json, markdown)
       --show-conflicts        Show shared file paths in graph output
       --level <n>             Restrict graph output to one level
       --json                  Emit machine-readable JSON
-      --include-completed     Include completed slices in plan, graph, or next history output
+      --include-completed     Include completed slices in dashboard, plan, graph, or next history output
+      --details               Show the full human dashboard report
+      --section <name>        Show one human dashboard section
+      --limit <n>             Limit dashboard human lists (1-100)
       --only-ready            Show only slices with no pending dependencies
       --all-ready             List every ready slice returned by next
       --auto-start            Prompt for confirmation and run start-slice on next
@@ -345,6 +356,11 @@ Examples:
   npx create-quiver --name "My Project"
   npx create-quiver --name "My Project" --dir ./my-project
   cd ./my-project && npx create-quiver flow
+  cd ./my-project && npx create-quiver dashboard
+  cd ./my-project && npx create-quiver dashboard --section slices --limit 10
+  cd ./my-project && npx create-quiver dashboard --json
+  cd ./my-project && npx create-quiver version
+  cd ./my-project && npx create-quiver version --json
   cd ./my-project && npx create-quiver analyze
   cd ./my-project && npx create-quiver plan --json
   cd ./my-project && npx create-quiver ai onboard --dry-run
@@ -437,6 +453,10 @@ function parseArgs(argv) {
     interactive: false,
     review: false,
     includeCompleted: false,
+    dashboardDetails: false,
+    dashboardSection: '',
+    dashboardLimit: null,
+    dashboardOptionErrors: [],
     onlyReady: false,
     allReady: false,
     autoStart: false,
@@ -525,6 +545,14 @@ function parseArgs(argv) {
 
   const positional = [];
 
+  function missingInputValueMessage() {
+    const aiCommandHint = result.mode === 'ai' ? positional[0] : '';
+    if (aiCommandHint === 'revise') {
+      return `missing feedback input file for ai revise --phase ${result.aiPhase}. Use: npx create-quiver ai revise --phase ${result.aiPhase} --input <feedback.md> --dry-run`;
+    }
+    return 'missing value for --input';
+  }
+
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index];
 
@@ -692,6 +720,33 @@ function parseArgs(argv) {
       continue;
     }
 
+    if (arg === '--details') {
+      result.dashboardDetails = true;
+      continue;
+    }
+
+    if (arg === '--section') {
+      const value = args[index + 1];
+      if (!value || String(value).startsWith('--')) {
+        result.dashboardOptionErrors.push('missing value for --section');
+        continue;
+      }
+      result.dashboardSection = value;
+      index += 1;
+      continue;
+    }
+
+    if (arg === '--limit') {
+      const value = args[index + 1];
+      if (!value || String(value).startsWith('--')) {
+        result.dashboardOptionErrors.push('missing value for --limit');
+        continue;
+      }
+      result.dashboardLimit = value;
+      index += 1;
+      continue;
+    }
+
     if (arg === '--show-conflicts') {
       result.showConflicts = true;
       continue;
@@ -875,8 +930,8 @@ function parseArgs(argv) {
 
     if (arg === '--input') {
       const value = args[++index];
-      if (!value) {
-        throw new Error(formatError('missing value for --input'));
+      if (!value || String(value).startsWith('--')) {
+        throw new Error(formatError(missingInputValueMessage()));
       }
       result.aiInput = value;
       continue;
@@ -1041,6 +1096,14 @@ function parseArgs(argv) {
     if (positional.length > 0) {
       throw new Error(formatError('flow does not accept positional arguments'));
     }
+  } else if (result.mode === 'version') {
+    if (positional.length > 0) {
+      throw new Error(formatError('version does not accept positional arguments'));
+    }
+  } else if (result.mode === 'dashboard') {
+    if (positional.length > 0) {
+      throw new Error(formatError('dashboard does not accept positional arguments; use --spec <slug>'));
+    }
   } else if (result.mode === 'ai') {
     if (!result.aiCommand && positional.length > 0) {
       result.aiCommand = positional.shift();
@@ -1134,6 +1197,14 @@ function parseArgs(argv) {
     throw new Error(formatError('too many positional arguments'));
   }
 
+  const requestedDashboardFlags = [];
+  if (result.dashboardDetails) requestedDashboardFlags.push('--details');
+  if (result.dashboardSection || result.dashboardOptionErrors.some((error) => error.includes('--section'))) requestedDashboardFlags.push('--section');
+  if (result.dashboardLimit !== null || result.dashboardOptionErrors.some((error) => error.includes('--limit'))) requestedDashboardFlags.push('--limit');
+  if (result.mode !== 'dashboard' && requestedDashboardFlags.length > 0) {
+    throw new Error(formatError(`${requestedDashboardFlags.join(', ')} ${requestedDashboardFlags.length === 1 ? 'is' : 'are'} only supported by dashboard. Use: npx create-quiver dashboard ${requestedDashboardFlags[0]}${requestedDashboardFlags[0] === '--section' ? ' <name>' : requestedDashboardFlags[0] === '--limit' ? ' <n>' : ''}`));
+  }
+
   return result;
 }
 
@@ -2819,6 +2890,37 @@ async function run(argv) {
     return;
   }
 
+  if (args.mode === 'dashboard') {
+    runDashboard(process.cwd(), {
+      details: args.dashboardDetails,
+      includeCompleted: args.includeCompleted,
+      json: args.json,
+      limit: args.dashboardLimit,
+      noColor: args.noColor,
+      optionErrors: args.dashboardOptionErrors,
+      section: args.dashboardSection,
+      specSlug: args.specSlug,
+    });
+    return;
+  }
+
+  if (args.mode === 'version') {
+    const report = collectVersionReport(process.cwd(), {
+      cliVersion: CLI_VERSION,
+      env: process.env,
+    });
+    if (args.json) {
+      process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    } else {
+      process.stdout.write(formatHumanVersionReport(report, {
+        env: process.env,
+        noColor: args.noColor,
+        stdoutIsTTY: Boolean(process.stdout.isTTY),
+      }));
+    }
+    return;
+  }
+
   if (args.mode === 'plan') {
     runPlan(process.cwd(), {
       includeCompleted: args.includeCompleted,
@@ -3388,6 +3490,7 @@ async function run(argv) {
 module.exports = {
   resolveInteractiveInitOptions,
   runAnalyze,
+  runDashboard,
   runDoctor,
   runFlow,
   runMigrate,

package/src/create-quiver/lib/ai/approval-candidates.js

@@ -0,0 +1,86 @@
+const { buildPlannerApprovalCandidates } = require('../approvals');
+const { buildTechnicalPlanApprovalCandidates } = require('./plan-review');
+
+function buildApprovalCandidateReport(projectRoot, phase) {
+  return phase === 'technical-plan'
+    ? buildTechnicalPlanApprovalCandidates(projectRoot)
+    : buildPlannerApprovalCandidates(projectRoot, phase);
+}
+
+function formatReviewSummary(review) {
+  if (!review || !review.recommendation) {
+    return '';
+  }
+
+  const parts = [`review=${review.recommendation}`];
+  if (review.blocking) {
+    parts.push('blocking');
+  }
+  if (review.required_fixes_count) {
+    parts.push(`required fixes=${review.required_fixes_count}`);
+  }
+  if (review.optional_hardening_count) {
+    parts.push(`optional=${review.optional_hardening_count}`);
+  }
+  if (review.risks_count) {
+    parts.push(`risks=${review.risks_count}`);
+  }
+  return parts.join(', ');
+}
+
+function formatCandidateSummary(candidate) {
+  if (!candidate) {
+    return '';
+  }
+
+  const parts = [
+    candidate.label,
+    candidate.current ? 'current' : 'history',
+    candidate.approvable ? 'approvable' : 'blocked',
+    candidate.reason,
+    formatReviewSummary(candidate.review),
+  ].filter(Boolean);
+  return parts.join(', ');
+}
+
+function approvalCandidateCommand(report, fallback = 'npx create-quiver ai approvals') {
+  if (report?.recommended?.next_command) {
+    return report.recommended.next_command;
+  }
+  if (report?.current?.next_command) {
+    return report.current.next_command;
+  }
+  return report?.next_command || fallback;
+}
+
+function formatApprovalDecisionLines(report) {
+  const lines = [];
+  if (!report || !Array.isArray(report.candidates)) {
+    return lines;
+  }
+
+  lines.push(`Candidates: ${report.candidates.length}`);
+  if (report.latest_version) {
+    lines.push(`Latest draft: v${report.latest_version}`);
+  }
+  if (report.current) {
+    lines.push(`Current candidate: ${formatCandidateSummary(report.current)}`);
+  }
+  if (report.recommended) {
+    lines.push(`Recommended approval: ${report.recommended.next_command}`);
+  } else if (report.next_command) {
+    lines.push(`Recommended next command: ${report.next_command}`);
+  }
+  if (report.review?.status) {
+    lines.push(`Review status: ${report.review.status}`);
+  }
+  return lines;
+}
+
+module.exports = {
+  approvalCandidateCommand,
+  buildApprovalCandidateReport,
+  formatApprovalDecisionLines,
+  formatCandidateSummary,
+  formatReviewSummary,
+};

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

@@ -1,7 +1,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 
-const { readPhaseApproval, resolveApprovedPlannerInput } = require('../approvals');
+const { buildPlannerApprovalCandidates, readPhaseApproval, resolveApprovedPlannerInput } = require('../approvals');
 const { quiverInternalPaths } = require('../init-layout');
 
 const PLAN_REVIEW_PROMPT_SOURCE = 'packaged production-readiness plan review template';
@@ -186,6 +186,81 @@ function reviewBlocksApproval(review) {
   return result.blocking === true || result.approval_recommendation === 'revise';
 }
 
+function normalizeReviewDecision(review) {
+  const result = review?.meta?.review_result || null;
+  const requiredFixes = normalizeList(result?.required_fixes);
+  const optionalHardening = normalizeList(result?.optional_hardening);
+  const risks = normalizeList(result?.risks);
+  const blocking = reviewBlocksApproval(review);
+  const recommendation = result?.approval_recommendation || (review.status === 'missing' || review.status === 'stale' ? 'review-required' : 'approve-with-risk');
+  const nextCommand = result?.next_command || (review.status === 'unapproved' || review.status === 'reviewed'
+    ? 'npx create-quiver ai approve --phase technical-plan --version <n>'
+    : 'npx create-quiver ai review-plan --dry-run');
+
+  return {
+    status: review.status,
+    recommendation,
+    blocking: blocking || review.status === 'missing' || review.status === 'stale',
+    required_fixes: requiredFixes,
+    optional_hardening: optionalHardening,
+    risks,
+    required_fixes_count: requiredFixes.length,
+    optional_hardening_count: optionalHardening.length,
+    risks_count: risks.length,
+    source_file: review.meta?.source_file || '',
+    source_kind: review.meta?.source_kind || null,
+    source_version: review.meta?.source_version || null,
+    reviewed_at: review.meta?.reviewed_at || '',
+    next_command: nextCommand,
+  };
+}
+
+function buildTechnicalPlanApprovalCandidates(projectRoot) {
+  const base = buildPlannerApprovalCandidates(projectRoot, 'technical-plan');
+  const review = readPlanReview(projectRoot);
+  const reviewDecision = normalizeReviewDecision(review);
+  const reviewReady = (review.status === 'unapproved' || review.status === 'reviewed') && reviewDecision.blocking !== true;
+  const candidates = base.candidates.map((candidate) => {
+    const matchesReviewVersion = !reviewDecision.source_version
+      || !candidate.version
+      || Number(reviewDecision.source_version) === Number(candidate.version);
+    const approvable = candidate.approvable === true && reviewReady && matchesReviewVersion;
+    const reason = approvable
+      ? `latest draft has plan-review recommendation ${reviewDecision.recommendation}`
+      : review.status === 'missing'
+        ? 'technical-plan requires production review before approval'
+        : review.status === 'stale'
+          ? 'technical-plan review is stale'
+          : reviewDecision.blocking
+            ? `plan-review blocks approval with recommendation ${reviewDecision.recommendation}`
+            : matchesReviewVersion
+              ? candidate.reason
+              : `plan-review targets v${reviewDecision.source_version}; candidate is v${candidate.version}`;
+
+    return {
+      ...candidate,
+      approvable,
+      recommended: candidate.current === true && approvable,
+      blocked: !approvable,
+      status: approvable ? 'approvable' : candidate.current ? 'blocked' : 'history',
+      reason,
+      recommended_action: approvable ? 'approve' : reviewDecision.blocking || review.status === 'missing' || review.status === 'stale' ? 'review-or-revise' : 'inspect',
+      next_command: approvable ? candidate.next_command : reviewDecision.next_command,
+      review: reviewDecision,
+    };
+  });
+
+  return {
+    ...base,
+    candidates,
+    current: candidates.find((candidate) => candidate.current) || null,
+    recommended: candidates.find((candidate) => candidate.recommended) || null,
+    history: candidates.filter((candidate) => !candidate.current),
+    review: reviewDecision,
+    next_command: candidates.find((candidate) => candidate.recommended)?.next_command || reviewDecision.next_command,
+  };
+}
+
 function latestTechnicalPlanDraft(approval) {
   const version = Number(approval.meta?.draft?.version || 0);
   if (!version) {
@@ -435,6 +510,7 @@ module.exports = {
   PLAN_REVIEW_RECOMMENDATIONS,
   assertPlanReviewed,
   buildPlanReviewPrompt,
+  buildTechnicalPlanApprovalCandidates,
   derivePlanReviewResult,
   planReviewMetaPath,
   planReviewPath,

package/src/create-quiver/lib/ai/run-state.js

@@ -2,6 +2,7 @@ const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 
+const { buildApprovalCandidateReport } = require('./approval-candidates');
 const { quiverInternalPaths } = require('../init-layout');
 
 const AI_RUN_PHASES = Object.freeze([
@@ -104,8 +105,24 @@ function phaseRank(phase) {
   return AI_RUN_PHASES.indexOf(phase);
 }
 
-function nextCommandForPhase(phase) {
+function nextCommandForPhase(phase, projectRoot = '') {
   assertKnownPhase(phase);
+  if (projectRoot && phase === 'acceptance-draft') {
+    try {
+      const report = buildApprovalCandidateReport(projectRoot, 'acceptance');
+      return report.recommended?.next_command || report.current?.next_command || PHASE_NEXT_COMMAND[phase];
+    } catch {
+      return PHASE_NEXT_COMMAND[phase];
+    }
+  }
+  if (projectRoot && phase === 'technical-plan-reviewed') {
+    try {
+      const report = buildApprovalCandidateReport(projectRoot, 'technical-plan');
+      return report.recommended?.next_command || report.current?.next_command || PHASE_NEXT_COMMAND[phase];
+    } catch {
+      return PHASE_NEXT_COMMAND[phase];
+    }
+  }
   return PHASE_NEXT_COMMAND[phase];
 }
 
@@ -374,12 +391,12 @@ function formatAiRunStatus(projectRoot, run) {
   if (otherOpenRuns.length > 0) {
     lines.push('Other open runs:');
     for (const item of otherOpenRuns) {
-      lines.push(`- ${item.run_id}: ${item.phase} (${item.status}) -> ${nextCommandForPhase(item.phase)}`);
+      lines.push(`- ${item.run_id}: ${item.phase} (${item.status}) -> ${nextCommandForPhase(item.phase, projectRoot)}`);
     }
   }
 
   lines.push(
-    `Next safe command: ${nextCommandForPhase(run.phase)}`,
+    `Next safe command: ${nextCommandForPhase(run.phase, projectRoot)}`,
     '',
   );
 
@@ -400,7 +417,7 @@ function formatAiRunResume(projectRoot, run) {
     'AI run resume',
     `Run: ${run.run_id}`,
     `Current phase: ${run.phase}`,
-    `Next safe command: ${nextCommandForPhase(run.phase)}`,
+    `Next safe command: ${nextCommandForPhase(run.phase, projectRoot)}`,
     `State: ${toRelativePosix(projectRoot, runStatePath(projectRoot, run.run_id))}`,
     '',
   ].join('\n');