create-quiver 0.15.0 → 0.15.2

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({
@@ -321,10 +353,10 @@ function detectFlowState(projectRoot) {
       stage: 'agent-profiles-needed',
       label: 'agent profiles need setup',
       blockers: [`Missing ${agents.missingCore.join(' and ')} agent profile${agents.missingCore.length > 1 ? 's' : ''}.`],
-      nextCommand: `npx create-quiver ai agent set ${role} --provider codex --model "<model-label>"`,
+      nextCommand: `npx create-quiver ai agent set ${role} --provider codex --model gpt-5.5`,
       suggestedCommands: [
         'npx create-quiver ai agent list',
-        `npx create-quiver ai agent set ${role} --provider codex --model "<model-label>"`,
+        `npx create-quiver ai agent set ${role} --provider codex --model gpt-5.5`,
       ],
       facts,
     });
@@ -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

@@ -22,6 +22,7 @@ const {
   runLifecycleResume: runAiLifecycleResume,
   runLifecycleRun: runAiLifecycleRun,
   runLifecycleStatus: runAiLifecycleStatus,
+  runModelsList: runAiModelsList,
   runOnboard,
   runPlan: runAiPlan,
   runPrepareContext: runAiPrepareContext,
@@ -172,7 +173,8 @@ const COMMAND_HELP_GROUPS = [
       ['ai resume', 'Resume guidance from the last valid lifecycle phase without chat memory.'],
       ['ai onboard', 'Run or print the planner onboarding prompt with a token-aware context pack.'],
       ['ai prepare-context', 'Preview or write docs-only AI context updates with assumptions and risks.'],
-      ['ai agent set|list|show', 'Manage planner, executor, reviewer, and doctor provider profiles without secrets; use set --dry-run to preview.'],
+      ['ai agent set|list|show|doctor|repair', 'Manage, diagnose, and dry-run repair planner, executor, reviewer, and doctor provider profiles without secrets.'],
+      ['ai models list', 'List provider/model ids known by Quiver without claiming account availability.'],
       ['ai plan', 'Generate versioned planner drafts for acceptance criteria, technical plan, or spec phase.'],
       ['ai revise', 'Create a new planner draft from human feedback without approving it.'],
       ['ai repair-plan', 'Repair an approved technical plan into a new structured draft without mutating the approved artifact.'],
@@ -261,7 +263,8 @@ function printUsage() {
   npx create-quiver ai specs list [--json]
   npx create-quiver ai slices list [--json]
   npx create-quiver ai trace report [options]
-  npx create-quiver ai agent <set|list|show> [role] [options]
+  npx create-quiver ai agent <set|list|show|doctor|repair> [role] [options]
+  npx create-quiver ai models list [--provider codex|claude|gemini] [--json]
   npx create-quiver ai prepare-context [options]
   npx create-quiver ai revise [options]
   npx create-quiver ai repair-plan [options]
@@ -321,7 +324,7 @@ Options:
       --allow-dirty           For ai execute-slice, allow pre-existing dirty files and ignore them for scope diff
       --mode <name>           Execution mode for ai execute-plan (auto, manual, delegated)
       --provider <name>       Provider CLI to preflight for prepare or AI commands
-      --model <label>         Free-form model label for AI agent profiles
+      --model <model-id>      Technical model id for AI agent profiles or provider-backed AI commands
       --version <n>           Draft version to approve for AI planner phases
       --run <id>              AI lifecycle run id
       --ssh-host-alias <name> SSH host alias to validate for prepare or AI commands
@@ -359,7 +362,10 @@ Examples:
   cd ./my-project && npx create-quiver ai trace report
   cd ./my-project && npx create-quiver ai agent set planner --provider codex --model gpt-5.5 --dry-run
   cd ./my-project && npx create-quiver ai agent set planner --provider codex --model gpt-5.5
+  cd ./my-project && npx create-quiver ai agent doctor
+  cd ./my-project && npx create-quiver ai agent repair --dry-run
   cd ./my-project && npx create-quiver ai agent list
+  cd ./my-project && npx create-quiver ai models list --provider codex
   cd ./my-project && npx create-quiver ai plan --phase acceptance --input requirements.md --dry-run
   cd ./my-project && npx create-quiver ai revise --phase acceptance --input feedback.md --dry-run
   cd ./my-project && npx create-quiver ai approve --phase acceptance --version 1
@@ -519,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];
 
@@ -869,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;
@@ -1050,10 +1064,10 @@ function parseArgs(argv) {
     if (result.aiCommand === 'run' && !result.aiRunCommand && positional.length > 0) {
       result.aiRunCommand = positional.shift();
     }
-    if ((result.aiCommand === 'specs' || result.aiCommand === 'slices' || result.aiCommand === 'trace' || result.aiCommand === 'active-slice') && !result.aiSecondaryCommand && positional.length > 0) {
+    if ((result.aiCommand === 'specs' || result.aiCommand === 'slices' || result.aiCommand === 'models' || result.aiCommand === 'trace' || result.aiCommand === 'active-slice') && !result.aiSecondaryCommand && positional.length > 0) {
       result.aiSecondaryCommand = positional.shift();
     }
-    if ((result.aiCommand === 'specs' || result.aiCommand === 'slices') && result.aiSecondaryCommand && result.aiSecondaryCommand !== 'list') {
+    if ((result.aiCommand === 'specs' || result.aiCommand === 'slices' || result.aiCommand === 'models') && result.aiSecondaryCommand && result.aiSecondaryCommand !== 'list') {
       throw new Error(formatError(`unsupported ai ${result.aiCommand} subcommand: ${result.aiSecondaryCommand}. Supported tasks: list`));
     }
     if (result.aiCommand === 'trace' && result.aiSecondaryCommand && result.aiSecondaryCommand !== 'report') {
@@ -2704,8 +2718,8 @@ async function resolveInteractiveInitOptions(args, targetDir, projectName, optio
 
   if (agentGuidance.value === 'show') {
     ux.nextSteps([
-      'npx create-quiver ai agent set planner --provider codex --model "<modelo-planner>" --dry-run',
-      'npx create-quiver ai agent set executor --provider claude --model "<modelo-executor>" --dry-run',
+      'npx create-quiver ai agent set planner --provider codex --model gpt-5.5 --dry-run',
+      'npx create-quiver ai agent set executor --provider claude --model claude-sonnet-4-6 --dry-run',
     ], { title: 'Despues de inicializar' });
   }
 
@@ -2836,7 +2850,7 @@ async function run(argv) {
 
   if (args.mode === 'ai') {
     if (!args.aiCommand) {
-      throw new Error(formatError('missing ai subcommand. Use: npx create-quiver ai onboard | prepare-context | run | active-slice | status | resume | inspect | export | specs | slices | trace | plan | revise | repair-plan | review-plan | approve | approvals | agent | prompt-slice | execute-slice | execute-plan | doctor | pr'));
+      throw new Error(formatError('missing ai subcommand. Use: npx create-quiver ai onboard | prepare-context | run | active-slice | status | resume | inspect | export | specs | slices | models | trace | plan | revise | repair-plan | review-plan | approve | approvals | agent | prompt-slice | execute-slice | execute-plan | doctor | pr'));
     }
 
     if (args.aiCommand === 'run') {
@@ -2909,13 +2923,23 @@ async function run(argv) {
       return;
     }
 
+    if (args.aiCommand === 'models') {
+      runAiModelsList({
+        json: args.json,
+        provider: args.aiProviderExplicit ? args.aiProvider : undefined,
+      });
+      return;
+    }
+
     if (args.aiCommand === 'agent') {
-      runAiAgent(process.cwd(), {
+      await runAiAgent(process.cwd(), {
         command: args.aiAgentCommand,
         context: args.aiContext || undefined,
         defaultProfile: args.aiDefaultProfile,
         displayName: args.aiDisplayName || undefined,
         id: args.aiProfileId || undefined,
+        interactive: args.interactive,
+        json: args.json,
         label: args.aiLabel || undefined,
         model: args.aiModel || undefined,
         provider: args.aiProviderExplicit ? args.aiProvider : undefined,
@@ -3120,7 +3144,7 @@ async function run(argv) {
       return;
     }
 
-    throw new Error(formatError(`unsupported ai subcommand: ${args.aiCommand}. Supported tasks: onboard, prepare-context, run, active-slice, status, resume, inspect, export, specs, slices, trace, plan, revise, repair-plan, review-plan, approve, approvals, agent, prompt-slice, execute-slice, execute-plan, doctor, pr`));
+    throw new Error(formatError(`unsupported ai subcommand: ${args.aiCommand}. Supported tasks: onboard, prepare-context, run, active-slice, status, resume, inspect, export, specs, slices, models, trace, plan, revise, repair-plan, review-plan, approve, approvals, agent, prompt-slice, execute-slice, execute-plan, doctor, pr`));
   }
 
   if (args.mode === 'graph') {