create-quiver 0.15.0 → 0.15.2

package/src/create-quiver/lib/ai/model-catalog.js

@@ -0,0 +1,333 @@
+const { assertSupportedProvider } = require('./providers');
+
+const MODEL_CATALOG_VERSION = 1;
+const MODEL_CATALOG_LAST_UPDATED = '2026-05-27';
+
+const MODEL_CATALOG = Object.freeze({
+  catalogVersion: MODEL_CATALOG_VERSION,
+  lastUpdated: MODEL_CATALOG_LAST_UPDATED,
+  providers: Object.freeze({
+    codex: Object.freeze({
+      id: 'codex',
+      displayName: 'Codex',
+      models: Object.freeze([
+        knownModel('gpt-5.5', 'GPT 5.5', {
+          aliases: ['GPT 5.5', 'gpt 5.5', 'Gpt-5.5'],
+          recommendedFor: ['planner', 'reviewer'],
+          costTier: 'high',
+          qualityTier: 'premium',
+          stability: 'stable',
+          notes: 'Recommended for planning, specs, architecture, and high-risk reviews.',
+        }),
+        knownModel('gpt-5.4', 'GPT 5.4', {
+          aliases: ['GPT 5.4', 'gpt 5.4'],
+          recommendedFor: ['planner', 'reviewer'],
+          costTier: 'medium',
+          qualityTier: 'high',
+          stability: 'stable',
+          notes: 'Balanced planner or reviewer model.',
+        }),
+        knownModel('gpt-5.4-mini', 'GPT 5.4 mini', {
+          aliases: ['GPT 5.4 mini', 'gpt 5.4 mini', 'gpt-5.4 mini'],
+          recommendedFor: ['executor', 'doctor'],
+          costTier: 'low',
+          qualityTier: 'standard',
+          stability: 'stable',
+          notes: 'Recommended for lower-cost execution, diagnostics, and sub-agent work.',
+        }),
+        knownModel('gpt-5.3-codex', 'GPT 5.3 Codex', {
+          aliases: ['GPT 5.3 Codex', 'gpt 5.3 codex'],
+          recommendedFor: ['executor'],
+          costTier: 'medium',
+          qualityTier: 'high',
+          stability: 'stable',
+          notes: 'Recommended for more complex coding slices.',
+        }),
+        knownModel('gpt-5.3-codex-spark', 'GPT 5.3 Codex Spark', {
+          aliases: ['GPT 5.3 Codex Spark', 'gpt 5.3 codex spark'],
+          recommendedFor: ['executor'],
+          costTier: 'medium',
+          qualityTier: 'high',
+          stability: 'preview',
+          notes: 'Preview or limited model for quick code iteration.',
+        }),
+      ]),
+    }),
+    claude: Object.freeze({
+      id: 'claude',
+      displayName: 'Claude',
+      models: Object.freeze([
+        knownModel('opus', 'Claude Opus', {
+          aliases: ['Claude Opus', 'opus'],
+          recommendedFor: ['planner', 'reviewer'],
+          costTier: 'high',
+          qualityTier: 'premium',
+          stability: 'stable',
+          notes: 'Recommended for complex planning and architectural decisions.',
+        }),
+        knownModel('sonnet', 'Claude Sonnet', {
+          aliases: ['Claude Sonnet', 'sonnet'],
+          recommendedFor: ['executor', 'reviewer'],
+          costTier: 'medium',
+          qualityTier: 'high',
+          stability: 'stable',
+          notes: 'Balanced execution and review model.',
+        }),
+        knownModel('haiku', 'Claude Haiku', {
+          aliases: ['Claude Haiku', 'haiku'],
+          recommendedFor: ['doctor'],
+          costTier: 'low',
+          qualityTier: 'standard',
+          stability: 'stable',
+          notes: 'Recommended for diagnostics and simple tasks.',
+        }),
+        knownModel('claude-opus-4-7', 'Claude Opus 4.7', {
+          aliases: ['OPUS 4.7', 'Claude Opus 4.7', 'opus 4.7'],
+          recommendedFor: ['planner', 'reviewer'],
+          costTier: 'high',
+          qualityTier: 'premium',
+          stability: 'known',
+          notes: 'Version-pinned known catalog choice for planning.',
+        }),
+        knownModel('claude-sonnet-4-6', 'Claude Sonnet 4.6', {
+          aliases: ['Claude Sonnet 4.6', 'sonnet 4.6'],
+          recommendedFor: ['executor', 'reviewer'],
+          costTier: 'medium',
+          qualityTier: 'high',
+          stability: 'known',
+          notes: 'Version-pinned known catalog choice for execution and review.',
+        }),
+        knownModel('claude-haiku-4-5', 'Claude Haiku 4.5', {
+          aliases: ['Claude Haiku 4.5', 'haiku 4.5'],
+          recommendedFor: ['doctor'],
+          costTier: 'low',
+          qualityTier: 'standard',
+          stability: 'known',
+          notes: 'Version-pinned known catalog choice for low-cost diagnostics.',
+        }),
+      ]),
+    }),
+    gemini: Object.freeze({
+      id: 'gemini',
+      displayName: 'Gemini',
+      models: Object.freeze([
+        knownModel('gemini-3.1-pro-preview', 'Gemini 3.1 Pro Preview', {
+          aliases: ['Gemini 3.1 Pro Preview', 'gemini 3.1 pro preview'],
+          recommendedFor: ['planner', 'reviewer'],
+          costTier: 'high',
+          qualityTier: 'premium',
+          stability: 'preview',
+          notes: 'Known catalog choice for complex planning and review.',
+        }),
+        knownModel('gemini-3.5-flash', 'Gemini 3.5 Flash', {
+          aliases: ['Gemini 3.5 Flash', 'gemini 3.5 flash'],
+          recommendedFor: ['executor'],
+          costTier: 'medium',
+          qualityTier: 'high',
+          stability: 'stable',
+          notes: 'Known catalog choice for balanced execution.',
+        }),
+        knownModel('gemini-3.1-flash-lite', 'Gemini 3.1 Flash-Lite', {
+          aliases: ['Gemini 3.1 Flash Lite', 'Gemini 3.1 Flash-Lite', 'gemini 3.1 flash lite'],
+          recommendedFor: ['doctor'],
+          costTier: 'low',
+          qualityTier: 'standard',
+          stability: 'stable',
+          notes: 'Known catalog choice for low-cost diagnostics and mechanical tasks.',
+        }),
+        knownModel('gemini-3.1-pro-preview-customtools', 'Gemini 3.1 Pro Custom Tools', {
+          aliases: ['Gemini 3.1 Pro Custom Tools', 'gemini 3.1 pro preview custom tools'],
+          recommendedFor: ['planner', 'reviewer'],
+          costTier: 'high',
+          qualityTier: 'premium',
+          stability: 'preview',
+          notes: 'Known catalog choice for advanced tool-oriented workflows.',
+        }),
+      ]),
+    }),
+  }),
+});
+
+function knownModel(id, displayName, options = {}) {
+  return Object.freeze({
+    id,
+    displayName,
+    aliases: Object.freeze(Array.from(new Set([id, displayName].concat(options.aliases || [])))),
+    recommendedFor: Object.freeze((options.recommendedFor || []).slice()),
+    costTier: options.costTier || 'unknown',
+    qualityTier: options.qualityTier || 'unknown',
+    stability: options.stability || 'known',
+    notes: options.notes || '',
+    modelSource: 'catalog',
+  });
+}
+
+function customModel(providerId, modelId = '') {
+  const id = String(modelId || '').trim();
+  return {
+    id: id || 'custom',
+    displayName: id || 'Custom',
+    aliases: id ? [id] : ['custom'],
+    recommendedFor: [],
+    costTier: 'unknown',
+    qualityTier: 'unknown',
+    stability: 'custom',
+    notes: 'Custom model id. Quiver cannot guarantee account availability without a live validation.',
+    modelSource: 'custom',
+    custom: true,
+    provider: providerId ? assertSupportedProvider(providerId) : '',
+  };
+}
+
+function getModelCatalog() {
+  return MODEL_CATALOG;
+}
+
+function listCatalogProviders() {
+  return Object.values(MODEL_CATALOG.providers).map((provider) => ({
+    id: provider.id,
+    displayName: provider.displayName,
+    modelCount: provider.models.length,
+  }));
+}
+
+function getProviderModelCatalog(providerId) {
+  const provider = assertSupportedProvider(providerId);
+  return MODEL_CATALOG.providers[provider];
+}
+
+function getKnownModelsForProvider(providerId, options = {}) {
+  const provider = getProviderModelCatalog(providerId);
+  const role = String(options.role || '').trim().toLowerCase();
+  const includeCustom = options.includeCustom !== false;
+  const models = provider.models.slice();
+  const sorted = role
+    ? models.sort((left, right) => roleScore(right, role) - roleScore(left, role))
+    : models;
+
+  if (!includeCustom) {
+    return sorted;
+  }
+
+  return sorted.concat(customModel(provider.id));
+}
+
+function roleScore(model, role) {
+  const roles = Array.isArray(model.recommendedFor) ? model.recommendedFor : [];
+  const index = roles.indexOf(role);
+  if (index === -1) return 0;
+  return 100 - index;
+}
+
+function normalizeModelAliasKey(value) {
+  return String(value || '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '');
+}
+
+function resolveModelFromEntries(providerId, modelValue, entries) {
+  const provider = assertSupportedProvider(providerId);
+  const input = String(modelValue || '').trim();
+  const inputKey = normalizeModelAliasKey(input);
+  if (!inputKey) {
+    return {
+      provider,
+      input,
+      matched: false,
+      ambiguous: false,
+      model: null,
+      matches: [],
+      reason: 'empty model',
+    };
+  }
+
+  const matches = [];
+  for (const model of entries || []) {
+    const aliases = Array.isArray(model.aliases) ? model.aliases : [model.id, model.displayName];
+    if (aliases.some((alias) => normalizeModelAliasKey(alias) === inputKey)) {
+      matches.push(model);
+    }
+  }
+
+  if (matches.length === 1) {
+    const model = matches[0];
+    return {
+      provider,
+      input,
+      matched: true,
+      ambiguous: false,
+      model,
+      matches,
+      technicalModel: model.id,
+      displayName: model.displayName,
+      modelSource: model.modelSource || 'catalog',
+      reason: 'known model alias matched',
+    };
+  }
+
+  if (matches.length > 1) {
+    return {
+      provider,
+      input,
+      matched: false,
+      ambiguous: true,
+      model: null,
+      matches,
+      reason: 'ambiguous model alias',
+    };
+  }
+
+  return {
+    provider,
+    input,
+    matched: false,
+    ambiguous: false,
+    model: customModel(provider, input),
+    matches: [],
+    technicalModel: input,
+    displayName: input,
+    modelSource: 'custom',
+    reason: 'custom model',
+  };
+}
+
+function resolveKnownModel(providerId, modelValue) {
+  const provider = getProviderModelCatalog(providerId);
+  return resolveModelFromEntries(provider.id, modelValue, provider.models);
+}
+
+function normalizeModelSelection(providerId, modelValue, options = {}) {
+  const resolution = resolveKnownModel(providerId, modelValue);
+  const fallbackDisplayName = String(options.displayName || '').trim();
+
+  if (resolution.ambiguous) {
+    return {
+      ...resolution,
+      model: String(modelValue || '').trim(),
+      displayName: fallbackDisplayName || String(modelValue || '').trim(),
+      validationStatus: options.validationStatus || 'not-tested',
+    };
+  }
+
+  return {
+    ...resolution,
+    model: resolution.technicalModel || String(modelValue || '').trim(),
+    displayName: fallbackDisplayName || resolution.displayName || String(modelValue || '').trim(),
+    validationStatus: options.validationStatus || 'not-tested',
+  };
+}
+
+module.exports = {
+  MODEL_CATALOG_LAST_UPDATED,
+  MODEL_CATALOG_VERSION,
+  customModel,
+  getKnownModelsForProvider,
+  getModelCatalog,
+  getProviderModelCatalog,
+  listCatalogProviders,
+  normalizeModelAliasKey,
+  normalizeModelSelection,
+  resolveKnownModel,
+  resolveModelFromEntries,
+};

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/providers.js

@@ -72,9 +72,54 @@ function normalizeProviderModel(model) {
   return value || '';
 }
 
+function resolveProviderModelSelection(providerId, model, options = {}) {
+  const rawModel = normalizeProviderModel(model);
+  if (!rawModel) {
+    return {
+      input: '',
+      model: '',
+      displayName: '',
+      modelSource: '',
+      aliasNormalized: false,
+    };
+  }
+
+  const { normalizeModelSelection } = require('./model-catalog');
+  const selection = normalizeModelSelection(providerId, rawModel, {
+    displayName: options.displayName,
+  });
+  const aliasNormalized = selection.modelSource === 'catalog' && selection.model !== rawModel;
+  if (aliasNormalized && options.blockModelAlias === true) {
+    throw new ProviderRunnerError(
+      'DISPLAY_MODEL_ALIAS',
+      `Model '${rawModel}' is a display alias for provider '${providerId}', not the technical id. Use '${selection.model}' or run 'npx create-quiver ai agent repair --dry-run'.`,
+      {
+        provider: providerId,
+        inputModel: rawModel,
+        suggestedModel: selection.model,
+        displayName: selection.displayName,
+        nextSteps: [
+          `Use --model ${selection.model}.`,
+          'Run npx create-quiver ai agent repair --dry-run to preview profile normalization.',
+          'Run npx create-quiver ai agent doctor to inspect profile issues.',
+        ],
+      },
+    );
+  }
+
+  return {
+    input: rawModel,
+    model: selection.model,
+    displayName: selection.displayName,
+    modelSource: selection.modelSource,
+    aliasNormalized,
+  };
+}
+
 function buildProviderModelArgs(providerId, model, options = {}) {
   const provider = getProviderDefinition(providerId);
-  const normalizedModel = normalizeProviderModel(model);
+  const modelResolution = resolveProviderModelSelection(provider.id, model, options);
+  const normalizedModel = modelResolution.model;
   const enforce = options.enforce === true;
 
   if (!normalizedModel) {
@@ -114,13 +159,19 @@ function buildProviderModelArgs(providerId, model, options = {}) {
   }
 
   const args = provider.modelArgBuilder(normalizedModel);
-  return {
+  const result = {
     model: normalizedModel,
     supported: true,
     enforced: enforce,
     args: Array.isArray(args) ? args.map((arg) => String(arg)) : [],
-    reason: 'model argument supported',
+    reason: modelResolution.aliasNormalized ? `model alias normalized from ${modelResolution.input}` : 'model argument supported',
   };
+  if (modelResolution.aliasNormalized) {
+    result.input = modelResolution.input;
+    result.displayName = modelResolution.displayName;
+    result.modelSource = modelResolution.modelSource;
+  }
+  return result;
 }
 
 function buildProviderInvocation(providerId, options = {}) {
@@ -128,6 +179,8 @@ function buildProviderInvocation(providerId, options = {}) {
   const extraArgs = Array.isArray(options.args) ? options.args.map((arg) => String(arg)) : [];
   const modelSelection = buildProviderModelArgs(provider.id, options.model, {
     enforce: options.enforceModelSelection === true,
+    blockModelAlias: options.blockModelAlias === true,
+    displayName: options.displayName,
   });
   const prompt = String(options.prompt ?? '');
   const timeoutMs = Number.isFinite(options.timeoutMs) ? Number(options.timeoutMs) : provider.timeoutMs;
@@ -184,6 +237,85 @@ function serializeError(error, provider, invocation) {
   };
 }
 
+function compactProviderText(value) {
+  return redactSecrets(String(value || ''))
+    .replace(/\bsk-[A-Za-z0-9_-]{16,}\b/g, '[REDACTED]')
+    .replace(/\bghp_[A-Za-z0-9_]{16,}\b/g, '[REDACTED]')
+    .replace(/\bgithub_pat_[A-Za-z0-9_]{16,}\b/g, '[REDACTED]')
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .slice(0, 6)
+    .join(' ');
+}
+
+function extractProviderErrorCause(result = {}) {
+  const error = result.error || {};
+  const text = compactProviderText([
+    error.message,
+    result.stderr,
+    result.stdout,
+  ].filter(Boolean).join('\n'));
+  const lower = text.toLowerCase();
+
+  if (error.code === 'MISSING_PROVIDER_CLI') {
+    return {
+      code: 'MISSING_PROVIDER_CLI',
+      message: error.message || `Provider CLI '${result.command || result.provider}' is not available.`,
+    };
+  }
+
+  if (error.code === 'PROVIDER_TIMEOUT') {
+    return {
+      code: 'PROVIDER_TIMEOUT',
+      message: error.message || `Provider '${result.provider}' timed out.`,
+    };
+  }
+
+  const quotedUnsupportedModel = text.match(/the ['"`]([^'"`]+)['"`] model is not supported/i);
+  const genericInvalidModel = /invalid model|unknown model|model .*not supported|model .*not available|model .*does not exist|unsupported model/i.test(text);
+  if (quotedUnsupportedModel || genericInvalidModel) {
+    const model = quotedUnsupportedModel ? quotedUnsupportedModel[1] : result.modelSelection?.model;
+    return {
+      code: 'INVALID_PROVIDER_MODEL',
+      message: model
+        ? `Provider '${result.provider}' rejected model '${model}'. ${text}`
+        : `Provider '${result.provider}' rejected the selected model. ${text}`,
+    };
+  }
+
+  if (/unauthorized|forbidden|permission denied|not authenticated|authentication|api key|login required|log in/i.test(text)) {
+    return {
+      code: 'PROVIDER_AUTH_ERROR',
+      message: `Provider '${result.provider}' authentication failed. ${text}`,
+    };
+  }
+
+  if (text) {
+    return {
+      code: 'PROVIDER_RUN_FAILED',
+      message: text,
+    };
+  }
+
+  return {
+    code: 'PROVIDER_RUN_FAILED',
+    message: 'provider run failed',
+  };
+}
+
+function createProviderFailureError(result = {}) {
+  const cause = extractProviderErrorCause(result);
+  return new ProviderRunnerError(cause.code, cause.message, {
+    provider: result.provider,
+    command: result.command,
+    args: Array.isArray(result.args) ? result.args.slice() : [],
+    exitCode: result.exitCode,
+    signal: result.signal,
+    modelSelection: result.modelSelection,
+  });
+}
+
 function runSpawn(command, args, options = {}) {
   const spawnImpl = options.spawn || spawn;
 
@@ -352,7 +484,7 @@ async function runProvider(providerId, options = {}) {
       timeoutMs: invocation.timeoutMs,
     });
 
-    return {
+    const providerResult = {
       ok: execution.ok,
       dryRun: false,
       provider: invocation.provider,
@@ -369,6 +501,10 @@ async function runProvider(providerId, options = {}) {
       error: execution.error,
       preflight: preflightResult,
     };
+    if (!providerResult.ok && !providerResult.error) {
+      providerResult.error = serializeError(createProviderFailureError(providerResult), invocation.provider, invocation);
+    }
+    return providerResult;
   } finally {
     finalizePromptTransport(transport);
   }
@@ -380,7 +516,10 @@ module.exports = {
   assertSupportedProvider,
   buildProviderModelArgs,
   buildProviderInvocation,
+  createProviderFailureError,
+  extractProviderErrorCause,
   formatProviderList,
   getProviderDefinition,
+  resolveProviderModelSelection,
   runProvider,
 };

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