create-quiver 0.14.0 → 0.15.0

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

@@ -1,4 +1,5 @@
 const fs = require('node:fs');
+const os = require('node:os');
 const path = require('node:path');
 
 const { redactSecrets } = require('../lib/evidence');
@@ -10,6 +11,9 @@ const {
   writeRawProviderArtifact,
 } = require('../lib/ai/artifacts');
 const { buildContextPackMetadata, normalizeRole } = require('../lib/ai/context-packs');
+const { parseContextProposalOutput } = require('../lib/ai/context-proposal');
+const { openEditor } = require('../lib/cli/editor');
+const { createUx } = require('../lib/cli/ux');
 const { runExecuteSlice, runPromptSlice } = require('../lib/ai/executor');
 const { runExecutePlan } = require('../lib/ai/execution-plan');
 const { buildPrCreatePlan, formatPreflightReport, formatPrCreateReport, preflightGitHubPr, runGhPrCreate } = require('../lib/ai/github');
@@ -53,7 +57,10 @@ const {
   agentProfilesPath,
   buildAgentProfileState,
   getAgentProfile,
+  getAgentProfileById,
   listAgentProfiles,
+  normalizeAgentProfileRole,
+  resolveAgentProfileDisplayName,
   resolveProfileProvider,
   setAgentProfile,
 } = require('../lib/agent-profiles');
@@ -118,11 +125,119 @@ function normalizeTimeout(timeoutMs) {
   return parsed;
 }
 
-function resolveProviderForProfile(repoRoot, role, provider, providerExplicit, fallbackProvider) {
-  if (providerExplicit === true || (provider && providerExplicit !== false)) {
-    return String(provider || fallbackProvider).trim().toLowerCase();
+function profileOptionForRole(options, role) {
+  const normalized = normalizeAgentProfileRole(role);
+  if (normalized === 'planner') {
+    return options.plannerProfile || options.profileId || '';
   }
-  return resolveProfileProvider(repoRoot, role, fallbackProvider);
+  if (normalized === 'executor') {
+    return options.executorProfile || options.profileId || '';
+  }
+  if (normalized === 'reviewer') {
+    return options.reviewerProfile || options.profileId || '';
+  }
+  if (normalized === 'doctor') {
+    return options.doctorProfile || options.profileId || '';
+  }
+  return options.profileId || '';
+}
+
+function resolveRuntimeAgentProfile(repoRoot, role, options = {}, fallbackProvider = DEFAULT_PLAN_PROVIDER) {
+  const normalizedRole = normalizeAgentProfileRole(role);
+  const explicitProvider = options.providerExplicit === true || (options.provider && options.providerExplicit !== false);
+  const explicitModel = String(options.model || '').trim();
+
+  if (explicitProvider) {
+    const provider = String(options.provider || fallbackProvider).trim().toLowerCase();
+    return {
+      role: normalizedRole,
+      profile: null,
+      profileId: '',
+      displayName: provider,
+      provider,
+      model: explicitModel,
+    };
+  }
+
+  const profileId = profileOptionForRole(options, normalizedRole);
+  const profile = profileId
+    ? getAgentProfileById(repoRoot, normalizedRole, profileId)
+    : getAgentProfile(repoRoot, normalizedRole);
+  const provider = profile?.provider || resolveProfileProvider(repoRoot, normalizedRole, fallbackProvider);
+
+  return {
+    role: normalizedRole,
+    profile,
+    profileId: profile?.id || profileId || '',
+    displayName: profile ? resolveAgentProfileDisplayName(profile) : provider,
+    provider,
+    model: explicitModel || profile?.model || '',
+  };
+}
+
+function createCommandUx(options = {}) {
+  if (options.ux) {
+    return options.ux;
+  }
+
+  return createUx({
+    env: options.env || process.env,
+    input: options.inputStream,
+    output: options.outputStream,
+    error: options.errorStream,
+    interactive: options.interactive,
+    json: options.json,
+    noColor: options.noColor,
+    prompts: options.prompts,
+    spinner: options.spinner,
+    stdinIsTTY: options.stdinIsTTY,
+    stdoutIsTTY: options.stdoutIsTTY,
+    stderrIsTTY: options.stderrIsTTY,
+    write: options.write,
+  });
+}
+
+function shouldShowHumanProgress(ux, options = {}) {
+  return options.progress !== false
+    && options.dryRun !== true
+    && options.printPrompt !== true
+    && ux?.mode?.decoration === true;
+}
+
+function plannerProgressTitle(action, runtimeProfile) {
+  return `${action} con ${runtimeProfile.displayName || runtimeProfile.model || runtimeProfile.provider}`;
+}
+
+function writeProgressChecks(ux, enabled, title, checks = []) {
+  if (!enabled) {
+    return;
+  }
+  ux.heading(title);
+  for (const check of checks) {
+    ux.check(check);
+  }
+}
+
+async function runProviderWithProgress({ ux, enabled, message = 'Ejecutando agente...', successMessage = 'Agente finalizado', failureMessage = 'Fallo ejecutando agente', run }) {
+  async function runAndFailOnProviderResult() {
+    const result = await run();
+    if (result && result.ok === false) {
+      const error = new Error(result.error?.message || 'provider run failed');
+      error.code = result.error?.code || 'AI_PROVIDER_RUN_FAILED';
+      error.providerResult = result;
+      throw error;
+    }
+    return result;
+  }
+
+  if (!enabled) {
+    return run();
+  }
+
+  return ux.withSpinner(message, runAndFailOnProviderResult, {
+    successMessage,
+    failureMessage,
+  });
 }
 
 function buildPlanContext({ role, context, phase, inputText, inputPath, repoRoot, revise = false }) {
@@ -206,6 +321,10 @@ function formatDryRunReport({ task, provider, role, contextPack, phase, invocati
   lines.push(`Timeout: ${invocation.timeoutMs}ms`);
   lines.push(`Prompt transport: ${invocation.promptTransport.mode}`);
   lines.push(`Prompt length: ${invocation.promptLength} bytes`);
+  if (invocation.modelSelection && invocation.modelSelection.model) {
+    lines.push(`Model: ${invocation.modelSelection.model}`);
+    lines.push(`Model support: ${invocation.modelSelection.supported ? 'supported' : 'unsupported'} (${invocation.modelSelection.reason})`);
+  }
 
   if (onboardingPlan) {
     lines.push(`Prompt source: ${onboardingPlan.promptSource}`);
@@ -232,6 +351,10 @@ function formatPromptOnlyReport({ task, provider, role, contextPack, phase, invo
   lines.push(`Timeout: ${invocation.timeoutMs}ms`);
   lines.push(`Prompt transport: ${invocation.promptTransport.mode}`);
   lines.push(`Prompt length: ${invocation.promptLength} bytes`);
+  if (invocation.modelSelection && invocation.modelSelection.model) {
+    lines.push(`Model: ${invocation.modelSelection.model}`);
+    lines.push(`Model support: ${invocation.modelSelection.supported ? 'supported' : 'unsupported'} (${invocation.modelSelection.reason})`);
+  }
 
   if (onboardingPlan) {
     lines.push(`Prompt source: ${onboardingPlan.promptSource}`);
@@ -313,6 +436,261 @@ function formatContextPreparationReport({ dryRun, plan, writePlan, writtenDocs,
   return `${lines.join('\n')}\n`;
 }
 
+function truncatePromptSection(text, maxChars = 1200) {
+  const value = String(text || '').trimEnd();
+  if (value.length <= maxChars) {
+    return value;
+  }
+  return `${value.slice(0, maxChars).trimEnd()}\n[... truncated ${value.length - maxChars} chars ...]`;
+}
+
+function buildPrepareContextPlannerPrompt({ pack, draftPack }) {
+  const plan = draftPack.plan;
+  const allowedPaths = draftPack.docs.map((doc) => doc.path);
+  const sections = [
+    pack.prompt,
+    'Task: planner-assisted Quiver context preparation.',
+    'Goal: improve the docs-only onboarding context for future AI work while preserving WDD + SDD safety.',
+    'Rules:',
+    '- Return only valid JSON. Do not include Markdown outside the JSON object.',
+    '- Do not modify product code, UI code, tests, migrations, dependencies, lockfiles, build files, runtime config, generated files, or paths outside the repo.',
+    '- Only propose writes to the allowed docs paths listed below.',
+    '- If information is ambiguous, document assumptions and risks instead of inventing facts.',
+    '- Keep human-authored content safe; Quiver will merge proposals through managed context blocks.',
+    '',
+    'Allowed docs-only output paths:',
+    ...allowedPaths.map((item) => `- ${item}`),
+    '',
+    'Project context:',
+    `- Project: ${plan.projectName}`,
+    `- Project slug: ${plan.projectSlug}`,
+    `- Package manager: ${plan.facts.packageManager}`,
+    `- Stack summary: ${plan.facts.stackSummary}`,
+    '',
+    'Files considered by deterministic prepare-context:',
+    ...plan.filesConsidered.map((item) => `- ${item.path}: ${item.present ? 'present' : 'absent'}${item.reason ? ` (${item.reason})` : ''}`),
+    '',
+    'Known assumptions:',
+    ...formatPathList(plan.assumptions),
+    '',
+    'Known risks:',
+    ...formatPathList(plan.risks),
+    '',
+    'Known contradictions:',
+    ...formatPathList(plan.contradictions),
+    '',
+    'Deterministic candidate docs:',
+    ...draftPack.docs.flatMap((doc) => [
+      `### ${doc.path}`,
+      truncatePromptSection(doc.content),
+    ]),
+    '',
+    'Required JSON output shape:',
+    JSON.stringify({
+      schema_version: 1,
+      kind: 'quiver-context-proposal',
+      summary: 'short summary',
+      assumptions: ['assumption to confirm'],
+      risks: ['risk to track'],
+      docs: [
+        {
+          path: 'docs/AI_CONTEXT.md',
+          action: 'update',
+          reason: 'why this doc should change',
+          content: '# AI Context\\n\\nFull proposed content or managed section content.\\n',
+          assumptions: [],
+          risks: [],
+        },
+      ],
+      omitted_paths: ['paths intentionally omitted'],
+      next_steps: ['safe next step'],
+    }, null, 2),
+  ];
+
+  return {
+    allowedPaths,
+    plan,
+    prompt: sections.join('\n'),
+    promptSource: 'quiver prepare-context planner proposal contract',
+  };
+}
+
+function formatPrepareContextPlannerDryRunReport({ provider, role, context, invocation, promptInfo, review, interactive }) {
+  const plan = promptInfo.plan;
+  const lines = [
+    'AI prepare-context planner dry-run',
+    'Mode: dry-run',
+    'Planner: enabled',
+    `Provider: ${provider}`,
+    `Role: ${role}`,
+    `Context pack: ${context}`,
+    `Command: ${invocation.command} ${invocation.args.join(' ')}`.trim(),
+    `Prompt bytes: ${invocation.promptLength}`,
+    invocation.modelSelection && invocation.modelSelection.model
+      ? `Model: ${invocation.modelSelection.model}`
+      : '',
+    invocation.modelSelection && invocation.modelSelection.model
+      ? `Model support: ${invocation.modelSelection.supported ? 'supported' : 'unsupported'} (${invocation.modelSelection.reason})`
+      : '',
+    `Prompt source: ${promptInfo.promptSource}`,
+    `Review requested: ${review ? 'yes' : 'no'}`,
+    `Interactive requested: ${interactive ? 'yes' : 'no'}`,
+    'Provider execution: skipped',
+    'Writes: none',
+    'Product code: untouched',
+    `Candidate docs: ${promptInfo.allowedPaths.join(', ')}`,
+    'Files considered:',
+    ...plan.filesConsidered.map((item) => `- ${item.path}: ${item.present ? 'present' : 'absent'}`),
+    'Allowed docs-only paths:',
+    ...promptInfo.allowedPaths.map((item) => `- ${item}`),
+    'Next safe commands:',
+    '- npx create-quiver ai prepare-context --with-planner --print-prompt',
+    '- npx create-quiver ai prepare-context --with-planner --dry-run --review',
+    '- npx create-quiver ai prepare-context --with-planner',
+  ];
+
+  return `${lines.filter(Boolean).join('\n')}\n`;
+}
+
+function serializeProposalForReview(proposal) {
+  return {
+    schema_version: proposal.schemaVersion,
+    kind: proposal.kind,
+    summary: proposal.summary,
+    assumptions: proposal.assumptions,
+    risks: proposal.risks,
+    docs: proposal.docs.map((doc) => ({
+      path: doc.path,
+      action: doc.action,
+      reason: doc.reason,
+      content: doc.content,
+      assumptions: doc.assumptions,
+      risks: doc.risks,
+    })),
+    omitted_paths: proposal.omittedPaths,
+    next_steps: proposal.nextSteps,
+  };
+}
+
+function createProposalReviewFile(proposal, options = {}) {
+  const reviewDir = options.reviewDir || fs.mkdtempSync(path.join(os.tmpdir(), 'quiver-context-review-'));
+  const reviewPath = path.join(reviewDir, 'context-proposal.json');
+  fs.mkdirSync(reviewDir, { recursive: true });
+  fs.writeFileSync(reviewPath, `${JSON.stringify(serializeProposalForReview(proposal), null, 2)}\n`);
+  return reviewPath;
+}
+
+function makeReviewError(message, reviewPath, cause) {
+  const error = new Error(formatError(`${message}\nReview artifact: ${reviewPath}\nNext safe step: edit the artifact into valid proposal JSON or rerun with --with-planner --dry-run.`));
+  error.code = cause?.code || 'AI_CONTEXT_REVIEW_FAILED';
+  error.cause = cause;
+  error.reviewPath = reviewPath;
+  return error;
+}
+
+function createReviewTextFile(contents, options = {}) {
+  const reviewDir = options.reviewDir || fs.mkdtempSync(path.join(os.tmpdir(), 'quiver-review-'));
+  const filename = options.reviewFileName || 'review.md';
+  const reviewPath = path.join(reviewDir, filename);
+  fs.mkdirSync(reviewDir, { recursive: true });
+  fs.writeFileSync(reviewPath, String(contents || ''));
+  return reviewPath;
+}
+
+async function reviewTextWithEditor(repoRoot, contents, options = {}) {
+  const reviewPath = createReviewTextFile(contents, options);
+  const hasEditorRunner = typeof options.openEditorFn === 'function';
+  const canOpenEditor = hasEditorRunner || options.stdinIsTTY === true || (options.stdinIsTTY !== false && Boolean(process.stdin.isTTY));
+
+  if (!canOpenEditor) {
+    throw makeReviewError(`${options.reviewLabel || 'review'} requires an interactive terminal or an injected editor runner.`, reviewPath);
+  }
+
+  const editorResult = hasEditorRunner
+    ? options.openEditorFn(reviewPath, { cwd: repoRoot, env: options.env || process.env })
+    : openEditor(reviewPath, { cwd: repoRoot, env: options.env || process.env });
+
+  if (!editorResult || editorResult.ok !== true) {
+    throw makeReviewError(editorResult?.reason || `${options.reviewLabel || 'review'} was canceled.`, reviewPath);
+  }
+
+  return {
+    reviewPath,
+    text: fs.readFileSync(reviewPath, 'utf8'),
+  };
+}
+
+async function confirmInteractiveAction(message, options = {}) {
+  if (options.interactive !== true) {
+    return;
+  }
+
+  const ux = options.ux || createUx({
+    interactive: true,
+    promptConfirm: options.promptConfirm,
+    stdinIsTTY: options.stdinIsTTY,
+    stdoutIsTTY: options.stdoutIsTTY,
+    stderrIsTTY: options.stderrIsTTY,
+    write: options.write,
+  });
+  const confirmed = await ux.promptConfirm(message, {
+    initialValue: false,
+  });
+
+  if (!confirmed) {
+    const error = new Error(formatError('interactive approval declined. No files were written.'));
+    error.code = 'AI_INTERACTIVE_APPROVAL_DECLINED';
+    throw error;
+  }
+}
+
+async function reviewPlannerContextProposal(repoRoot, proposal, options = {}) {
+  const reviewPath = createProposalReviewFile(proposal, options);
+  const hasEditorRunner = typeof options.openEditorFn === 'function';
+  const canOpenEditor = hasEditorRunner || options.stdinIsTTY === true || (options.stdinIsTTY !== false && Boolean(process.stdin.isTTY));
+
+  if (!canOpenEditor) {
+    throw makeReviewError('ai prepare-context review requires an interactive terminal or an injected editor runner.', reviewPath);
+  }
+
+  const editorResult = hasEditorRunner
+    ? options.openEditorFn(reviewPath, { cwd: repoRoot, env: options.env || process.env })
+    : openEditor(reviewPath, { cwd: repoRoot, env: options.env || process.env });
+
+  if (!editorResult || editorResult.ok !== true) {
+    throw makeReviewError(editorResult?.reason || 'ai prepare-context review was canceled before applying docs.', reviewPath);
+  }
+
+  try {
+    return {
+      proposal: parseContextProposalOutput(fs.readFileSync(reviewPath, 'utf8')),
+      reviewPath,
+    };
+  } catch (error) {
+    throw makeReviewError('edited planner proposal is invalid after review.', reviewPath, error);
+  }
+}
+
+async function confirmPlannerContextWrites(writePlan, options = {}) {
+  const changed = writePlan.filter((item) => item.action !== 'skip').length;
+  await confirmInteractiveAction(`Apply ${changed} docs-only context update${changed === 1 ? '' : 's'}?`, options);
+}
+
+function buildPlannerContextWritePlan(repoRoot, proposal) {
+  const reasonByPath = new Map(proposal.docs.map((doc) => [doc.path, doc.reason]));
+  const draftDocs = proposal.docs
+    .filter((doc) => doc.action !== 'skip')
+    .map((doc) => ({
+      path: doc.path,
+      content: doc.content,
+    }));
+
+  return buildContextWritePlan(repoRoot, draftDocs).map((item) => ({
+    ...item,
+    reason: item.action === 'skip' ? item.reason : reasonByPath.get(item.path) || item.reason,
+  }));
+}
+
 function writeProviderOutput(result) {
   if (result.stdout) {
     process.stdout.write(redactSecrets(result.stdout));
@@ -855,7 +1233,8 @@ function annotateGitHubError(error, scope) {
 
 async function runOnboard(repoRoot, options = {}) {
   const role = normalizeRole(options.role || DEFAULT_ONBOARD_ROLE);
-  const provider = resolveProviderForProfile(repoRoot, role, options.provider, options.providerExplicit, DEFAULT_ONBOARD_PROVIDER);
+  const runtimeProfile = resolveRuntimeAgentProfile(repoRoot, role, options, DEFAULT_ONBOARD_PROVIDER);
+  const provider = runtimeProfile.provider;
   const context = options.context || DEFAULT_ONBOARD_CONTEXT;
   const timeoutMs = normalizeTimeout(options.timeout);
   const inputText = readTextFile(options.input, repoRoot);
@@ -868,9 +1247,15 @@ async function runOnboard(repoRoot, options = {}) {
       prompt,
       cwd: repoRoot,
       timeoutMs,
+      model: runtimeProfile.model,
+      enforceModelSelection: false,
     });
   } catch (error) {
-    throw annotateProviderError(error, 'onboard');
+    if (error.providerResult) {
+      result = error.providerResult;
+    } else {
+      throw annotateProviderError(error, 'onboard');
+    }
   }
 
   if (options.dryRun) {
@@ -881,6 +1266,7 @@ async function runOnboard(repoRoot, options = {}) {
       contextPack: context,
       invocation,
       onboardingPlan: contextInfo.plan,
+      profile: runtimeProfile,
     };
     process.stdout.write(formatDryRunReport(report));
     return report;
@@ -895,23 +1281,39 @@ async function runOnboard(repoRoot, options = {}) {
       invocation,
       onboardingPlan: contextInfo.plan,
       prompt,
+      profile: runtimeProfile,
     };
     process.stdout.write(formatPromptOnlyReport(report));
     return report;
   }
 
+  const ux = createCommandUx(options);
+  const showProgress = shouldShowHumanProgress(ux, options);
+  writeProgressChecks(
+    ux,
+    showProgress,
+    plannerProgressTitle('Ejecutando onboarding', runtimeProfile),
+    ['Leyendo docs base', 'Detectando estructura', 'Preparando prompt'],
+  );
+
   let result;
   try {
-    result = await (options.runProviderFn || runProvider)(provider, {
-      prompt,
-      cwd: repoRoot,
-      timeoutMs,
-      dryRun: false,
-      probe: options.probe,
-      spawn: options.spawn,
-      tempRoot: options.tempRoot,
-      tempFileName: options.tempFileName,
-      tempFilePrefix: options.tempFilePrefix,
+    result = await runProviderWithProgress({
+      ux,
+      enabled: showProgress,
+      run: () => (options.runProviderFn || runProvider)(provider, {
+        prompt,
+        cwd: repoRoot,
+        timeoutMs,
+        dryRun: false,
+        probe: options.probe,
+        spawn: options.spawn,
+        tempRoot: options.tempRoot,
+        tempFileName: options.tempFileName,
+        tempFilePrefix: options.tempFilePrefix,
+        model: runtimeProfile.model,
+        enforceModelSelection: Boolean(runtimeProfile.model),
+      }),
     });
   } catch (error) {
     throw annotateProviderError(error, 'onboard');
@@ -932,11 +1334,16 @@ async function runOnboard(repoRoot, options = {}) {
     contextPack: context,
     invocation,
     onboardingPlan: contextInfo.plan,
+    profile: runtimeProfile,
     result,
   };
 }
 
 async function runPrepareContext(repoRoot, options = {}) {
+  if (options.withPlanner === true) {
+    return runPrepareContextWithPlanner(repoRoot, options);
+  }
+
   const draftPack = buildContextPreparationDrafts(repoRoot);
   const writePlan = buildContextWritePlan(repoRoot, draftPack.docs);
   const report = {
@@ -998,10 +1405,181 @@ async function runPrepareContext(repoRoot, options = {}) {
   };
 }
 
+async function runPrepareContextWithPlanner(repoRoot, options = {}) {
+  const role = normalizeRole(options.role || DEFAULT_PLAN_ROLE);
+  const runtimeProfile = resolveRuntimeAgentProfile(repoRoot, role, options, DEFAULT_PLAN_PROVIDER);
+  const provider = runtimeProfile.provider;
+  const context = options.context || DEFAULT_PLAN_CONTEXT;
+  const timeoutMs = normalizeTimeout(options.timeout);
+  const draftPack = buildContextPreparationDrafts(repoRoot);
+  const pack = buildContextPackMetadata({
+    role,
+    packName: context,
+    repoRoot,
+  });
+  const promptInfo = buildPrepareContextPlannerPrompt({ pack, draftPack });
+  const prompt = promptInfo.prompt;
+  assertProviderPromptWithinLimit(prompt, options.promptLimitOptions || {});
+  let invocation;
+
+  try {
+    invocation = buildProviderInvocation(provider, {
+      prompt,
+      cwd: repoRoot,
+      timeoutMs,
+      model: runtimeProfile.model,
+      enforceModelSelection: false,
+    });
+  } catch (error) {
+    if (error.providerResult) {
+      result = error.providerResult;
+    } else {
+      throw annotateProviderError(error, 'prepare-context');
+    }
+  }
+
+  if (options.dryRun) {
+    const report = {
+      task: 'prepare-context',
+      mode: 'planner',
+      dryRun: true,
+      provider,
+      role,
+      contextPack: context,
+      invocation,
+      candidateDocs: promptInfo.allowedPaths,
+      plan: draftPack.plan,
+      profile: runtimeProfile,
+    };
+    process.stdout.write(formatPrepareContextPlannerDryRunReport({
+      provider,
+      role,
+      context,
+      invocation,
+      promptInfo,
+      review: options.review === true,
+      interactive: options.interactive === true,
+    }));
+    return report;
+  }
+
+  if (options.printPrompt) {
+    const report = {
+      task: 'prepare-context',
+      provider,
+      role,
+      contextPack: context,
+      invocation,
+      prompt,
+      promptSource: promptInfo.promptSource,
+      profile: runtimeProfile,
+    };
+    process.stdout.write(formatPromptOnlyReport(report));
+    return report;
+  }
+
+  const ux = createCommandUx(options);
+  const showProgress = shouldShowHumanProgress(ux, options);
+  writeProgressChecks(
+    ux,
+    showProgress,
+    plannerProgressTitle('Ejecutando onboarding', runtimeProfile),
+    ['Leyendo docs base', 'Detectando estructura', 'Preparando prompt'],
+  );
+
+  let result;
+  try {
+    result = await runProviderWithProgress({
+      ux,
+      enabled: showProgress,
+      run: () => (options.runProviderFn || runProvider)(provider, {
+        prompt,
+        cwd: repoRoot,
+        timeoutMs,
+        dryRun: false,
+        probe: options.probe,
+        spawn: options.spawn,
+        tempRoot: options.tempRoot,
+        tempFileName: options.tempFileName,
+        tempFilePrefix: options.tempFilePrefix,
+        model: runtimeProfile.model,
+        enforceModelSelection: Boolean(runtimeProfile.model),
+      }),
+    });
+  } catch (error) {
+    throw annotateProviderError(error, 'prepare-context');
+  }
+
+  if (!result.ok) {
+    writeProviderOutput(result);
+    throw annotateProviderError(result.error || new Error('provider run failed'), 'prepare-context');
+  }
+
+  const clean = extractCleanProviderOutput(result, { prompt, projectRoot: repoRoot });
+  let proposal = parseContextProposalOutput(clean.cleanOutput);
+  let reviewPath = '';
+
+  if (options.review === true) {
+    const reviewed = await reviewPlannerContextProposal(repoRoot, proposal, options);
+    proposal = reviewed.proposal;
+    reviewPath = reviewed.reviewPath;
+  }
+
+  const writePlan = buildPlannerContextWritePlan(repoRoot, proposal);
+  await confirmPlannerContextWrites(writePlan, options);
+
+  const lifecycleRun = ensureAiRun(repoRoot, {
+    command: 'ai prepare-context --with-planner',
+    input: options.input || '',
+    runId: options.runId,
+    phase: 'created',
+  });
+  const snapshot = createContextSnapshots(repoRoot, lifecycleRun, writePlan, options.now || new Date());
+  const plannedDocs = writePlan.filter((item) => item.action !== 'skip').map((item) => item.path);
+
+  process.stdout.write(formatContextPreparationReport({
+    dryRun: false,
+    plan: draftPack.plan,
+    writePlan,
+    writtenDocs: plannedDocs,
+    snapshot,
+  }));
+
+  const writtenDocs = writeDraftDocs(writePlan);
+  updateAiRunPhase(repoRoot, lifecycleRun.run_id, 'onboarding-ready', {
+    artifact: snapshot.manifestPath,
+    command: 'ai prepare-context --with-planner',
+  });
+  process.stdout.write(formatContextPreparationReport({
+    dryRun: false,
+    plan: draftPack.plan,
+    writePlan,
+    writtenDocs,
+    snapshot,
+    completed: true,
+  }));
+
+  return {
+    task: 'prepare-context',
+    mode: 'planner',
+    dryRun: false,
+    provider,
+    role,
+    contextPack: context,
+    invocation,
+    proposal,
+    reviewPath,
+    runId: lifecycleRun.run_id,
+    snapshot,
+    writtenDocs,
+  };
+}
+
 async function runPlan(repoRoot, options = {}) {
   const phase = normalizePlannerPhase(options.phase || DEFAULT_PLAN_PHASE);
   const role = normalizeRole(options.role || DEFAULT_PLAN_ROLE);
-  const provider = resolveProviderForProfile(repoRoot, role, options.provider, options.providerExplicit, DEFAULT_PLAN_PROVIDER);
+  const runtimeProfile = resolveRuntimeAgentProfile(repoRoot, role, options, DEFAULT_PLAN_PROVIDER);
+  const provider = runtimeProfile.provider;
   const context = options.context || DEFAULT_PLAN_CONTEXT;
   const timeoutMs = normalizeTimeout(options.timeout);
   let inputPath = options.input || '';
@@ -1103,9 +1681,15 @@ async function runPlan(repoRoot, options = {}) {
       prompt,
       cwd: repoRoot,
       timeoutMs,
+      model: runtimeProfile.model,
+      enforceModelSelection: false,
     });
   } catch (error) {
-    throw annotateProviderError(error, 'plan', phase);
+    if (error.providerResult) {
+      result = error.providerResult;
+    } else {
+      throw annotateProviderError(error, 'plan', phase);
+    }
   }
 
   if (options.dryRun) {
@@ -1116,8 +1700,18 @@ async function runPlan(repoRoot, options = {}) {
       contextPack: contextInfo.pack.packName,
       phase,
       invocation,
+      profile: runtimeProfile,
     };
     process.stdout.write(formatDryRunReport(report));
+    if (options.withPlanner === true) {
+      process.stdout.write('Planner mode: already active for ai plan; --with-planner is accepted for UX consistency.\n');
+    }
+    if (options.review === true) {
+      process.stdout.write('Review requested: provider output will be opened for review before saving the draft in live mode.\n');
+    }
+    if (options.interactive === true) {
+      process.stdout.write('Interactive requested: live mode will ask before saving the draft.\n');
+    }
     return report;
   }
 
@@ -1130,23 +1724,39 @@ async function runPlan(repoRoot, options = {}) {
       phase,
       invocation,
       prompt,
+      profile: runtimeProfile,
     };
     process.stdout.write(formatPromptOnlyReport(report));
     return report;
   }
 
+  const ux = createCommandUx(options);
+  const showProgress = shouldShowHumanProgress(ux, options);
+  writeProgressChecks(
+    ux,
+    showProgress,
+    plannerProgressTitle(`Ejecutando plan ${phase}`, runtimeProfile),
+    ['Leyendo entrada', 'Preparando contexto', 'Preparando prompt'],
+  );
+
   let result;
   try {
-    result = await (options.runProviderFn || runProvider)(provider, {
-      prompt,
-      cwd: repoRoot,
-      timeoutMs,
-      dryRun: false,
-      probe: options.probe,
-      spawn: options.spawn,
-      tempRoot: options.tempRoot,
-      tempFileName: options.tempFileName,
-      tempFilePrefix: options.tempFilePrefix,
+    result = await runProviderWithProgress({
+      ux,
+      enabled: showProgress,
+      run: () => (options.runProviderFn || runProvider)(provider, {
+        prompt,
+        cwd: repoRoot,
+        timeoutMs,
+        dryRun: false,
+        probe: options.probe,
+        spawn: options.spawn,
+        tempRoot: options.tempRoot,
+        tempFileName: options.tempFileName,
+        tempFilePrefix: options.tempFilePrefix,
+        model: runtimeProfile.model,
+        enforceModelSelection: Boolean(runtimeProfile.model),
+      }),
     });
   } catch (error) {
     throw annotateProviderError(error, 'plan', phase);
@@ -1157,13 +1767,27 @@ async function runPlan(repoRoot, options = {}) {
     throw annotateProviderError(result.error || new Error('provider run failed'), 'plan', phase);
   }
 
+  const clean = extractCleanProviderOutput(result, { prompt, projectRoot: repoRoot });
+  let cleanOutput = clean.cleanOutput;
+  let reviewPath = '';
+
+  if (options.review === true) {
+    const reviewed = await reviewTextWithEditor(repoRoot, cleanOutput, {
+      ...options,
+      reviewFileName: `ai-plan-${phase}-draft.md`,
+      reviewLabel: `ai plan --phase ${phase} review`,
+    });
+    cleanOutput = reviewed.text;
+    reviewPath = reviewed.reviewPath;
+  }
+
+  await confirmInteractiveAction(`Save ${phase} planner draft?`, options);
   const lifecycleRun = ensureAiRun(repoRoot, {
     command: `ai plan --phase ${phase}`,
     input: inputPath,
     runId: options.runId,
   });
-  const clean = extractCleanProviderOutput(result, { prompt, projectRoot: repoRoot });
-  writeCleanProviderOutput(clean);
+  writeCleanProviderOutput({ cleanOutput });
   const rawArtifact = writeRawProviderArtifact(repoRoot, lifecycleRun.run_id, `ai-plan-${phase}`, result, {
     metadata: {
       phase,
@@ -1174,10 +1798,11 @@ async function runPlan(repoRoot, options = {}) {
       input_compaction: inputCompaction,
     },
   });
-  const draft = savePlannerDraft(repoRoot, phase, inputPath, clean.cleanOutput, {
+  const draft = savePlannerDraft(repoRoot, phase, inputPath, cleanOutput, {
     rawArtifactPath: rawArtifact.path,
     outputSource: clean.source,
     inputCompaction,
+    reviewPath,
   });
   updateAiRunPhase(repoRoot, lifecycleRun.run_id, phase === 'acceptance' ? 'acceptance-draft' : 'technical-plan-draft', {
     artifact: path.relative(repoRoot, draft.filePath).split(path.sep).join('/'),
@@ -1192,12 +1817,14 @@ async function runPlan(repoRoot, options = {}) {
     phase,
     invocation,
     result,
+    reviewPath,
   };
 }
 
 async function runReviewPlan(repoRoot, options = {}) {
   const role = 'planner';
-  const provider = resolveProviderForProfile(repoRoot, 'reviewer', options.provider, options.providerExplicit, DEFAULT_PLAN_PROVIDER);
+  const runtimeProfile = resolveRuntimeAgentProfile(repoRoot, 'reviewer', options, DEFAULT_PLAN_PROVIDER);
+  const provider = runtimeProfile.provider;
   const context = options.context || DEFAULT_PLAN_CONTEXT;
   const timeoutMs = normalizeTimeout(options.timeout);
   const resolved = resolveTechnicalPlanReviewInput(repoRoot, options.input || undefined);
@@ -1221,9 +1848,15 @@ async function runReviewPlan(repoRoot, options = {}) {
       prompt: built.prompt,
       cwd: repoRoot,
       timeoutMs,
+      model: runtimeProfile.model,
+      enforceModelSelection: false,
     });
   } catch (error) {
-    throw annotateProviderError(error, 'review-plan');
+    if (error.providerResult) {
+      result = error.providerResult;
+    } else {
+      throw annotateProviderError(error, 'review-plan');
+    }
   }
 
   if (options.dryRun) {
@@ -1237,6 +1870,7 @@ async function runReviewPlan(repoRoot, options = {}) {
       inputPath,
       inputKind: resolved.kind,
       inputVersion: resolved.version,
+      profile: runtimeProfile,
     };
     process.stdout.write(formatDryRunReport({
       task: 'review-plan',
@@ -1268,23 +1902,39 @@ async function runReviewPlan(repoRoot, options = {}) {
       inputPath,
       inputKind: resolved.kind,
       inputVersion: resolved.version,
+      profile: runtimeProfile,
     };
     process.stdout.write(formatPromptOnlyReport(report));
     return report;
   }
 
+  const ux = createCommandUx(options);
+  const showProgress = shouldShowHumanProgress(ux, options);
+  writeProgressChecks(
+    ux,
+    showProgress,
+    plannerProgressTitle('Ejecutando revisión del plan', runtimeProfile),
+    ['Leyendo plan técnico', 'Preparando contexto', 'Preparando prompt'],
+  );
+
   let result;
   try {
-    result = await (options.runProviderFn || runProvider)(provider, {
-      prompt: built.prompt,
-      cwd: repoRoot,
-      timeoutMs,
-      dryRun: false,
-      probe: options.probe,
-      spawn: options.spawn,
-      tempRoot: options.tempRoot,
-      tempFileName: options.tempFileName,
-      tempFilePrefix: options.tempFilePrefix,
+    result = await runProviderWithProgress({
+      ux,
+      enabled: showProgress,
+      run: () => (options.runProviderFn || runProvider)(provider, {
+        prompt: built.prompt,
+        cwd: repoRoot,
+        timeoutMs,
+        dryRun: false,
+        probe: options.probe,
+        spawn: options.spawn,
+        tempRoot: options.tempRoot,
+        tempFileName: options.tempFileName,
+        tempFilePrefix: options.tempFilePrefix,
+        model: runtimeProfile.model,
+        enforceModelSelection: Boolean(runtimeProfile.model),
+      }),
     });
   } catch (error) {
     throw annotateProviderError(error, 'review-plan');
@@ -1342,7 +1992,8 @@ async function runReviewPlan(repoRoot, options = {}) {
 
 async function runRepairPlan(repoRoot, options = {}) {
   const role = normalizeRole(options.role || DEFAULT_PLAN_ROLE);
-  const provider = resolveProviderForProfile(repoRoot, role, options.provider, options.providerExplicit, DEFAULT_PLAN_PROVIDER);
+  const runtimeProfile = resolveRuntimeAgentProfile(repoRoot, role, options, DEFAULT_PLAN_PROVIDER);
+  const provider = runtimeProfile.provider;
   const context = options.context || DEFAULT_PLAN_CONTEXT;
   const timeoutMs = normalizeTimeout(options.timeout);
   const source = resolveApprovedTechnicalPlanForRepair(repoRoot, options.input || '');
@@ -1362,9 +2013,15 @@ async function runRepairPlan(repoRoot, options = {}) {
       prompt: built.prompt,
       cwd: repoRoot,
       timeoutMs,
+      model: runtimeProfile.model,
+      enforceModelSelection: false,
     });
   } catch (error) {
-    throw annotateProviderError(error, 'repair-plan');
+    if (error.providerResult) {
+      providerResult = error.providerResult;
+    } else {
+      throw annotateProviderError(error, 'repair-plan');
+    }
   }
 
   if (options.dryRun) {
@@ -1375,6 +2032,7 @@ async function runRepairPlan(repoRoot, options = {}) {
       contextPack: built.pack.packName,
       phase: 'technical-plan',
       invocation,
+      profile: runtimeProfile,
     };
     process.stdout.write(formatDryRunReport(report));
     process.stdout.write(`Source approved artifact: ${source.path}\n`);
@@ -1394,23 +2052,39 @@ async function runRepairPlan(repoRoot, options = {}) {
       inputPath: source.path,
       inputKind: 'approved',
       inputVersion: source.approval.meta?.approved?.version || null,
+      profile: runtimeProfile,
     };
     process.stdout.write(formatPromptOnlyReport(report));
     return report;
   }
 
+  const ux = createCommandUx(options);
+  const showProgress = shouldShowHumanProgress(ux, options);
+  writeProgressChecks(
+    ux,
+    showProgress,
+    plannerProgressTitle('Ejecutando reparación del plan', runtimeProfile),
+    ['Leyendo plan aprobado', 'Preparando contexto', 'Preparando prompt'],
+  );
+
   let providerResult;
   try {
-    providerResult = await (options.runProviderFn || runProvider)(provider, {
-      prompt: built.prompt,
-      cwd: repoRoot,
-      timeoutMs,
-      dryRun: false,
-      probe: options.probe,
-      spawn: options.spawn,
-      tempRoot: options.tempRoot,
-      tempFileName: options.tempFileName,
-      tempFilePrefix: options.tempFilePrefix,
+    providerResult = await runProviderWithProgress({
+      ux,
+      enabled: showProgress,
+      run: () => (options.runProviderFn || runProvider)(provider, {
+        prompt: built.prompt,
+        cwd: repoRoot,
+        timeoutMs,
+        dryRun: false,
+        probe: options.probe,
+        spawn: options.spawn,
+        tempRoot: options.tempRoot,
+        tempFileName: options.tempFileName,
+        tempFilePrefix: options.tempFilePrefix,
+        model: runtimeProfile.model,
+        enforceModelSelection: Boolean(runtimeProfile.model),
+      }),
     });
   } catch (error) {
     throw annotateProviderError(error, 'repair-plan');
@@ -1746,10 +2420,13 @@ function runLifecycleRun(repoRoot, options = {}) {
 
 function formatAgentProfile(profile) {
   const lines = [
+    `ID: ${profile.id || 'default'}`,
     `Role: ${profile.role}`,
     `Provider: ${profile.provider}`,
     `Model: ${profile.model || '(not set)'}`,
     `Label: ${profile.label || '(not set)'}`,
+    `Display name: ${resolveAgentProfileDisplayName(profile) || '(not set)'}`,
+    `Default: ${profile.default === true ? 'yes' : 'no'}`,
     `Context: ${profile.context || '(not set)'}`,
     `Updated: ${profile.updated_at}`,
   ];
@@ -1765,7 +2442,9 @@ function formatAgentProfileList(profiles) {
     }
     const model = item.profile.model ? ` model=${item.profile.model}` : '';
     const label = item.profile.label ? ` label=${item.profile.label}` : '';
-    lines.push(`- ${item.role}: provider=${item.profile.provider}${model}${label}`);
+    const displayName = resolveAgentProfileDisplayName(item.profile);
+    const alternatives = item.profiles.length > 1 ? ` options=${item.profiles.length}` : '';
+    lines.push(`- ${item.role}: provider=${item.profile.provider}${model}${label} displayName=${displayName}${alternatives}`);
   }
   return `${lines.join('\n')}\n`;
 }
@@ -1798,6 +2477,9 @@ function runAgent(repoRoot, options = {}) {
     if (options.dryRun) {
       const preview = buildAgentProfileState(repoRoot, options.role, {
         context: options.context,
+        default: options.defaultProfile,
+        displayName: options.displayName,
+        id: options.id,
         label: options.label,
         model: options.model,
         provider: options.provider,
@@ -1813,6 +2495,9 @@ function runAgent(repoRoot, options = {}) {
     }
     const result = setAgentProfile(repoRoot, options.role, {
       context: options.context,
+      default: options.defaultProfile,
+      displayName: options.displayName,
+      id: options.id,
       label: options.label,
       model: options.model,
       provider: options.provider,
@@ -1832,10 +2517,14 @@ function runAgent(repoRoot, options = {}) {
     if (!options.role) {
       throw new Error(formatError('missing agent role. Use: npx create-quiver ai agent show <planner|executor|reviewer|doctor>'));
     }
-    const profile = getAgentProfile(repoRoot, options.role);
+    const profile = options.id
+      ? getAgentProfileById(repoRoot, options.role, options.id)
+      : getAgentProfile(repoRoot, options.role);
     if (!profile) {
       throw new Error(formatActionableError({
-        failure: `agent profile '${options.role}' is not configured.`,
+        failure: options.id
+          ? `agent profile '${options.role}/${options.id}' is not configured.`
+          : `agent profile '${options.role}' is not configured.`,
         impact: 'Quiver will fall back to default provider behavior and may use the wrong model/cost profile.',
         fix: `Configure the ${options.role} profile with a supported provider and optional model label.`,
         nextCommand: `npx create-quiver ai agent set ${options.role} --provider <provider> --model <label>`,
@@ -1896,20 +2585,32 @@ async function runGitHubTask(repoRoot, options = {}, mode = 'pr') {
 async function runPr(repoRoot, options = {}) {
   const dryRun = options.dryRun === true;
   const create = options.create === true;
+  const ux = createCommandUx(options);
+  const showProgress = create && !dryRun && shouldShowHumanProgress(ux, options);
+  if (showProgress) {
+    ux.heading('Creando PR con gh');
+  }
   let preflight;
 
   try {
-    preflight = await (options.preflightFn || preflightGitHubPr)(repoRoot, {
-      remote: options.remote,
-      sshHostAlias: options.sshHostAlias,
-      identityFile: options.identityFile,
-      gitFlowGuidePath: options.gitFlowGuidePath,
-      ghCommand: options.ghCommand,
-      ghProbe: options.ghProbe,
-      ghAuthProbe: options.ghAuthProbe,
-      ghProbeArgs: options.ghProbeArgs,
-      ghAuthArgs: options.ghAuthArgs,
-      blockedBranches: options.blockedBranches,
+    preflight = await runProviderWithProgress({
+      ux,
+      enabled: showProgress,
+      message: 'Ejecutando preflight de GitHub...',
+      successMessage: 'Preflight de GitHub listo',
+      failureMessage: 'Falló preflight de GitHub',
+      run: () => (options.preflightFn || preflightGitHubPr)(repoRoot, {
+        remote: options.remote,
+        sshHostAlias: options.sshHostAlias,
+        identityFile: options.identityFile,
+        gitFlowGuidePath: options.gitFlowGuidePath,
+        ghCommand: options.ghCommand,
+        ghProbe: options.ghProbe,
+        ghAuthProbe: options.ghAuthProbe,
+        ghProbeArgs: options.ghProbeArgs,
+        ghAuthArgs: options.ghAuthArgs,
+        blockedBranches: options.blockedBranches,
+      }),
     });
   } catch (error) {
     throw annotateGitHubError(error, 'pr');
@@ -1924,10 +2625,38 @@ async function runPr(repoRoot, options = {}) {
       prBodyPath: options.prBodyPath,
       title: options.title,
     });
+    if (showProgress) {
+      ux.check('Cuerpo del PR preparado');
+    }
   } catch (error) {
     throw annotateGitHubError(error, 'pr');
   }
 
+  if (options.review === true) {
+    const hasEditorRunner = typeof options.openEditorFn === 'function';
+    const canOpenEditor = hasEditorRunner || options.stdinIsTTY === true || (options.stdinIsTTY !== false && Boolean(process.stdin.isTTY));
+    if (!canOpenEditor) {
+      throw annotateGitHubError(makeReviewError('ai pr --review requires an interactive terminal or an injected editor runner.', plan.prBodyPath), 'pr');
+    }
+    const editorResult = hasEditorRunner
+      ? options.openEditorFn(plan.prBodyPath, { cwd: repoRoot, env: options.env || process.env })
+      : openEditor(plan.prBodyPath, { cwd: repoRoot, env: options.env || process.env });
+    if (!editorResult || editorResult.ok !== true) {
+      throw annotateGitHubError(makeReviewError(editorResult?.reason || 'ai pr review was canceled.', plan.prBodyPath), 'pr');
+    }
+    try {
+      plan = buildPrCreatePlan(repoRoot, preflight, {
+        baseBranch: options.baseBranch,
+        ghCommand: options.ghCommand,
+        input: options.input,
+        prBodyPath: options.prBodyPath,
+        title: options.title,
+      });
+    } catch (error) {
+      throw annotateGitHubError(error, 'pr');
+    }
+  }
+
   if (dryRun || !create) {
     process.stdout.write(formatPrCreateReport({ preflight, plan }, { dryRun, create }));
     return {
@@ -1939,10 +2668,19 @@ async function runPr(repoRoot, options = {}) {
     };
   }
 
+  await confirmInteractiveAction(`Create GitHub PR '${plan.title}'?`, options);
+
   let result;
   try {
-    result = runGhPrCreate(plan, {
-      ghCreateRunner: options.ghCreateRunner,
+    result = await runProviderWithProgress({
+      ux,
+      enabled: showProgress,
+      message: 'Creando PR en GitHub...',
+      successMessage: 'PR creado',
+      failureMessage: 'Falló creación del PR',
+      run: () => runGhPrCreate(plan, {
+        ghCreateRunner: options.ghCreateRunner,
+      }),
     });
   } catch (error) {
     throw annotateGitHubError(error, 'pr');