create-quiver 0.15.1 → 0.15.2

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

@@ -85,6 +85,10 @@ const {
   savePlannerDraft,
   summarizePlannerApproval,
 } = require('../lib/approvals');
+const {
+  buildApprovalCandidateReport,
+  formatApprovalDecisionLines,
+} = require('../lib/ai/approval-candidates');
 const { assertPlannerPhaseReady, getPlannerPhaseDetails, normalizePlannerPhase, PlannerPhaseError } = require('../lib/ai/phase-gates');
 const { collectActiveSliceState, resolveProjectState } = require('../lib/project-state-resolver');
 
@@ -1224,7 +1228,11 @@ function formatApprovalStatusReport(repoRoot) {
   for (const phase of PLANNER_APPROVAL_PHASES) {
     const summary = summarizePlannerApproval(repoRoot, phase).trimEnd();
     const relation = classifyGlobalApprovalRelation(readPhaseApproval(repoRoot, phase), runApprovalRows);
-    sections.push(`${summary}\nRun relation: ${relation}`);
+    const candidates = buildApprovalCandidateReport(repoRoot, phase);
+    const decisionLines = formatApprovalDecisionLines(candidates)
+      .map((line) => `- ${line}`)
+      .join('\n');
+    sections.push(`${summary}\nRun relation: ${relation}${decisionLines ? `\nApproval candidates:\n${decisionLines}` : ''}`);
   }
   sections.push(summarizePlanReview(repoRoot).trimEnd());
   return `${sections.join('\n\n')}\n`;
@@ -1657,7 +1665,7 @@ async function runPlan(repoRoot, options = {}) {
 
   if (options.revise === true) {
     if (!inputPath) {
-      throw new Error(formatError(`missing feedback input file for ai revise phase '${phase}'`));
+      throw new Error(formatError(`missing feedback input file for ai revise phase '${phase}'. Use: npx create-quiver ai revise --phase ${phase} --input <feedback.md> --dry-run`));
     }
     const feedbackText = readTextFile(inputPath, repoRoot);
     const revisionInput = buildRevisionInput({
@@ -2190,20 +2198,112 @@ async function runRevise(repoRoot, options = {}) {
   });
 }
 
+function formatApprovalCandidateHint(candidate) {
+  const parts = [];
+  if (candidate.current) {
+    parts.push('current');
+  }
+  if (candidate.created_at) {
+    parts.push(candidate.created_at);
+  }
+  if (candidate.review?.recommendation) {
+    parts.push(`review=${candidate.review.recommendation}`);
+  }
+  if (candidate.review?.required_fixes_count) {
+    parts.push(`required fixes=${candidate.review.required_fixes_count}`);
+  }
+  if (candidate.review?.optional_hardening_count) {
+    parts.push(`optional=${candidate.review.optional_hardening_count}`);
+  }
+  if (candidate.review?.risks_count) {
+    parts.push(`risks=${candidate.review.risks_count}`);
+  }
+  parts.push(candidate.reason);
+  return parts.filter(Boolean).join(', ');
+}
+
+function approvalSelectionOptions(report) {
+  return report.candidates.map((candidate) => ({
+    label: `${candidate.label}${candidate.recommended ? ' (recommended)' : candidate.current ? ' (current)' : ' (history)'}`,
+    value: String(candidate.version || ''),
+    hint: formatApprovalCandidateHint(candidate),
+    default: candidate.recommended === true,
+    raw: candidate,
+  }));
+}
+
+async function resolveApprovalVersion(repoRoot, phase, options = {}) {
+  if (options.version) {
+    return options.version;
+  }
+
+  const canPrompt = isInteractiveAgentPromptAvailable(options);
+  const shouldPrompt = options.interactive === true || canPrompt;
+  const report = buildApprovalCandidateReport(repoRoot, phase);
+
+  if (!shouldPrompt || !canPrompt) {
+    const recommended = report.recommended?.version || report.latest_version || '<n>';
+    throw new Error(formatActionableError({
+      failure: `ai approve --phase ${phase} requires --version <n> when prompts are not available.`,
+      impact: 'Quiver cannot safely guess which saved planner draft the human approved.',
+      fix: 'Review drafts with `npx create-quiver ai approvals`, then pass the version explicitly.',
+      nextCommand: `npx create-quiver ai approve --phase ${phase} --version ${recommended}`,
+    }));
+  }
+
+  if (report.candidates.length === 0) {
+    throw new Error(formatActionableError({
+      failure: `ai approve --phase ${phase} has no saved drafts to approve.`,
+      impact: 'There is no planner artifact that can pass the approval gate.',
+      fix: `Generate a ${phase} draft first.`,
+      nextCommand: `npx create-quiver ai plan --phase ${phase}${phase === 'acceptance' ? ' --input <requirements.md>' : ''} --dry-run`,
+    }));
+  }
+
+  const selected = await selectOption(`¿Qué ${phase} draft querés aprobar?`, approvalSelectionOptions(report), {
+    env: options.env,
+    error: options.error,
+    input: options.input,
+    interactive: true,
+    noColor: options.noColor,
+    output: options.output,
+    prompts: options.prompts,
+    promptSelect: options.promptSelect,
+    stdinIsTTY: options.stdinIsTTY,
+    stdoutIsTTY: options.stdoutIsTTY,
+    stderrIsTTY: options.stderrIsTTY,
+    defaultValue: report.recommended?.version ? String(report.recommended.version) : undefined,
+    flag: '--version',
+    name: `${phase} approval version`,
+  });
+
+  const candidate = selected.raw;
+  if (!candidate?.approvable) {
+    throw new Error(formatActionableError({
+      failure: `${phase} draft ${selected.label} is not approvable.`,
+      impact: candidate?.review?.blocking
+        ? 'The current review gate blocks technical-plan approval.'
+        : 'Quiver only approves the current eligible draft version.',
+      fix: candidate?.reason || 'Inspect planner approvals before approving.',
+      nextCommand: candidate?.next_command || `npx create-quiver ai approvals`,
+    }));
+  }
+
+  return selected.value;
+}
+
 async function runApprove(repoRoot, options = {}) {
   const phase = normalizePlannerPhase(options.phase || DEFAULT_PLAN_PHASE);
   if (phase === 'spec') {
     throw new Error(formatError(`ai approve does not support phase '${phase}'`));
   }
 
-  if (!options.version) {
-    throw new Error(formatError(`ai approve --phase ${phase} requires --version <n>. Review drafts with \`npx create-quiver ai approvals\`.`));
-  }
-
   if (options.input) {
     throw new Error(formatError(`ai approve --phase ${phase} approves saved draft versions only. Use \`npx create-quiver ai revise --phase ${phase} --input ${options.input}\` to create a new draft first.`));
   }
 
+  const version = await resolveApprovalVersion(repoRoot, phase, options);
+
   if (phase === 'technical-plan') {
     const review = readPlanReview(repoRoot);
     if (review.status !== 'unapproved' && review.status !== 'reviewed') {
@@ -2214,24 +2314,24 @@ async function runApprove(repoRoot, options = {}) {
       const requiredFixes = Array.isArray(result.required_fixes) ? result.required_fixes.length : 0;
       throw new Error(formatError(`ai approve --phase technical-plan is blocked by plan review; approval recommendation is ${result.approval_recommendation}. Required fixes: ${requiredFixes}. Next command: ${result.next_command}`));
     }
-    assertTechnicalPlanDraftHasSpecContract(repoRoot, options.version);
+    assertTechnicalPlanDraftHasSpecContract(repoRoot, version);
   }
 
   const inputText = '';
 
   if (options.dryRun) {
-    process.stdout.write(formatApprovalDryRunResult({ phase, input: options.input, version: options.version }));
+    process.stdout.write(formatApprovalDryRunResult({ phase, input: options.input, version }));
     return {
       task: 'approve',
       phase,
       input: options.input,
-      version: options.version || null,
+      version: version || null,
       dryRun: true,
     };
   }
 
   const result = approvePlannerPhase(repoRoot, phase, options.input || '', inputText, {
-    version: options.version || undefined,
+    version: version || undefined,
   });
   const lifecycleRun = ensureAiRun(repoRoot, {
     command: `ai approve --phase ${phase}`,
@@ -2241,7 +2341,7 @@ async function runApprove(repoRoot, options = {}) {
   recordAiRunApproval(repoRoot, lifecycleRun.run_id, {
     artifact: path.relative(repoRoot, result.filePath).split(path.sep).join('/'),
     phase,
-    source_file: options.input || `draft version ${options.version}`,
+    source_file: options.input || `draft version ${version}`,
     version: result.version || null,
   });
   updateAiRunPhase(repoRoot, lifecycleRun.run_id, phase === 'acceptance' ? 'acceptance-approved' : 'technical-plan-approved', {
@@ -2250,7 +2350,7 @@ async function runApprove(repoRoot, options = {}) {
   });
   process.stdout.write(formatApprovalResult({
     ...result,
-    sourceFile: options.input || `draft version ${options.version}`,
+    sourceFile: options.input || `draft version ${version}`,
   }, repoRoot));
 
   return {

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

@@ -525,6 +525,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];
 
@@ -875,8 +883,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;

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');