create-quiver 0.12.0 → 0.13.0

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

@@ -1,14 +1,31 @@
 const fs = require('node:fs');
 const path = require('node:path');
 
+const { redactSecrets } = require('../lib/evidence');
+const { formatActionableError } = require('../lib/actionable-error');
+const {
+  assertProviderPromptWithinLimit,
+  compactRevisionInput,
+  extractCleanProviderOutput,
+  writeRawProviderArtifact,
+} = require('../lib/ai/artifacts');
 const { buildContextPackMetadata, normalizeRole } = require('../lib/ai/context-packs');
 const { runExecuteSlice, runPromptSlice } = require('../lib/ai/executor');
 const { runExecutePlan } = require('../lib/ai/execution-plan');
 const { buildPrCreatePlan, formatPreflightReport, formatPrCreateReport, preflightGitHubPr, runGhPrCreate } = require('../lib/ai/github');
 const { buildContextPreparationDrafts, buildPlannerOnboardingPrompt } = require('../lib/ai/onboarding-template');
+const {
+  collectLifecycleExport,
+  formatLifecycleExportMarkdown,
+  formatLifecycleInspect,
+  formatSlicesList,
+  formatSpecsList,
+  formatTraceReport,
+} = require('../lib/ai/export-state');
 const {
   PLAN_REVIEW_PROMPT_SOURCE,
   buildPlanReviewPrompt,
+  readPlanReview,
   resolveReviewedTechnicalPlanInput,
   resolveTechnicalPlanReviewInput,
   savePlanReview,
@@ -16,8 +33,18 @@ const {
 } = require('../lib/ai/plan-review');
 const { buildSpecGenerationManifest, describeSpecGeneration, generateSpecArtifacts } = require('../lib/ai/spec-generator');
 const { buildProviderInvocation, runProvider } = require('../lib/ai/providers');
+const {
+  createAiRun,
+  ensureAiRun,
+  formatAiRunResume,
+  formatAiRunStatus,
+  recordAiRunApproval,
+  resolveAiRun,
+  updateAiRunPhase,
+} = require('../lib/ai/run-state');
 const {
   agentProfilesPath,
+  buildAgentProfileState,
   getAgentProfile,
   listAgentProfiles,
   resolveProfileProvider,
@@ -26,6 +53,7 @@ const {
 const {
   PLANNER_APPROVAL_PHASES,
   approvePlannerPhase,
+  readPhaseApproval,
   resolveApprovedPlannerInput,
   savePlannerDraft,
   summarizePlannerApproval,
@@ -39,6 +67,8 @@ const DEFAULT_PLAN_PROVIDER = 'codex';
 const DEFAULT_PLAN_ROLE = 'planner';
 const DEFAULT_PLAN_CONTEXT = 'planning';
 const DEFAULT_PLAN_PHASE = 'acceptance';
+const CONTEXT_PREP_START = '<!-- quiver:context-prep:start -->';
+const CONTEXT_PREP_END = '<!-- quiver:context-prep:end -->';
 
 function formatError(message) {
   return `create-quiver: ${message}`;
@@ -85,7 +115,7 @@ function resolveProviderForProfile(repoRoot, role, provider, providerExplicit, f
   return resolveProfileProvider(repoRoot, role, fallbackProvider);
 }
 
-function buildPlanContext({ role, context, phase, inputText, inputPath, repoRoot }) {
+function buildPlanContext({ role, context, phase, inputText, inputPath, repoRoot, revise = false }) {
   const phaseDetails = getPlannerPhaseDetails(phase);
   const pack = buildContextPackMetadata({
     role,
@@ -96,7 +126,9 @@ function buildPlanContext({ role, context, phase, inputText, inputPath, repoRoot
   const sections = [
     pack.prompt,
     `Phase: ${phaseDetails.phase}`,
-    phaseDetails.phase === 'acceptance'
+    revise
+      ? 'Task: revise the current draft and produce a new version only. Do not advance phase, approve, create specs, or modify product code.'
+      : phaseDetails.phase === 'acceptance'
       ? 'Task: produce acceptance criteria only. Do not create files or modify product code.'
       : 'Task: produce a technical plan only. Do not create files or modify product code.',
   ];
@@ -167,6 +199,52 @@ function formatDryRunReport({ task, provider, role, contextPack, phase, invocati
   return `${lines.join('\n')}\n`;
 }
 
+function formatPromptOnlyReport({ task, provider, role, contextPack, phase, invocation, prompt, onboardingPlan, promptSource, inputPath, inputKind, inputVersion }) {
+  const lines = [
+    `AI ${task} prompt-only`,
+    `Provider: ${provider}`,
+    `Role: ${role}`,
+    `Context pack: ${contextPack}`,
+  ];
+
+  if (phase) {
+    lines.push(`Phase: ${phase}`);
+  }
+
+  lines.push(`Command: ${invocation.command} ${invocation.args.join(' ')}`);
+  lines.push(`Timeout: ${invocation.timeoutMs}ms`);
+  lines.push(`Prompt transport: ${invocation.promptTransport.mode}`);
+  lines.push(`Prompt length: ${invocation.promptLength} bytes`);
+
+  if (onboardingPlan) {
+    lines.push(`Prompt source: ${onboardingPlan.promptSource}`);
+    lines.push(`Selected docs: ${onboardingPlan.selectedDocs.length}`);
+    lines.push(`Documentation debt: ${onboardingPlan.missingDocs.length}`);
+  }
+
+  if (promptSource) {
+    lines.push(`Prompt source: ${promptSource}`);
+  }
+
+  if (inputPath) {
+    lines.push(`Input file: ${inputPath}`);
+  }
+
+  if (inputKind) {
+    lines.push(`Input kind: ${inputKind}`);
+  }
+
+  if (inputVersion) {
+    lines.push(`Input version: v${inputVersion}`);
+  }
+
+  lines.push('--- PROMPT START ---');
+  lines.push(String(prompt || '').trimEnd());
+  lines.push('--- PROMPT END ---');
+
+  return `${lines.join('\n')}\n`;
+}
+
 function formatPathList(items, emptyLabel = 'none') {
   if (!Array.isArray(items) || items.length === 0) {
     return [`- ${emptyLabel}`];
@@ -175,28 +253,41 @@ function formatPathList(items, emptyLabel = 'none') {
   return items.map((item) => `- ${item}`);
 }
 
-function formatContextPreparationReport({ dryRun, plan, docs, writtenDocs }) {
+function formatContextPreparationReport({ dryRun, plan, writePlan, writtenDocs, snapshot, completed = false }) {
   const lines = [
-    dryRun ? 'AI prepare-context dry-run' : 'AI prepare-context completed',
+    dryRun ? 'AI prepare-context dry-run' : completed ? 'AI prepare-context completed' : 'AI prepare-context write plan',
     `Mode: ${dryRun ? 'dry-run' : 'live'}`,
     `Project: ${plan.projectName}`,
     `Project slug: ${plan.projectSlug}`,
     'Writes: docs-only',
     'Product code: untouched',
-    `Proposed docs: ${docs.length > 0 ? docs.map((doc) => doc.path).join(', ') : 'none'}`,
+    `Proposed docs: ${writePlan.length > 0 ? writePlan.map((item) => item.path).join(', ') : 'none'}`,
   ];
 
   if (!dryRun) {
-    lines.push(`Written docs: ${writtenDocs.length > 0 ? writtenDocs.join(', ') : 'none'}`);
+    lines.push(`${completed ? 'Written docs' : 'Planned writes'}: ${writtenDocs.length > 0 ? writtenDocs.join(', ') : 'none'}`);
+    if (snapshot) {
+      lines.push(`Snapshot: ${snapshot.root}`);
+    }
+  }
+
+  if (completed) {
+    return `${lines.join('\n')}\n`;
   }
 
   lines.push(
+    'Proposed changes:',
+    ...writePlan.map((item) => `- ${item.path}: ${item.action}${item.reason ? ` (${item.reason})` : ''}`),
+    'Diff preview:',
+    ...formatDiffPreview(writePlan),
     'Files considered:',
     ...plan.filesConsidered.map((item) => `- ${item.path}: ${item.present ? 'present' : 'absent'}${item.reason ? ` (${item.reason})` : ''}`),
     'Assumptions:',
     ...formatPathList(plan.assumptions),
     'Risks:',
     ...formatPathList(plan.risks),
+    'Contradictions:',
+    ...formatPathList(plan.contradictions),
     'Omitted paths:',
     ...formatPathList(plan.omittedPaths),
     'Uncertainty markers: TODO | Assumption | Pending confirmation',
@@ -207,20 +298,188 @@ function formatContextPreparationReport({ dryRun, plan, docs, writtenDocs }) {
 
 function writeProviderOutput(result) {
   if (result.stdout) {
-    process.stdout.write(result.stdout);
+    process.stdout.write(redactSecrets(result.stdout));
   }
   if (result.stderr) {
-    process.stderr.write(result.stderr);
+    process.stderr.write(redactSecrets(result.stderr));
   }
 }
 
-function writeDraftDocs(repoRoot, drafts) {
-  const writtenDocs = [];
-  for (const draft of drafts) {
+function normalizeText(value) {
+  return String(value || '').replace(/\r\n/g, '\n');
+}
+
+function buildRevisionInput({ phase, feedbackPath, feedbackText, repoRoot, compactionOptions = {} }) {
+  const current = readPhaseApproval(repoRoot, phase);
+  if (!current.draft) {
+    throw new Error(formatError(`ai revise --phase ${phase} requires an existing draft; current status is ${current.status}. Run \`npx create-quiver ai plan --phase ${phase} --input <file>\` first.`));
+  }
+
+  const sections = [];
+
+  if (phase === 'technical-plan') {
+    const acceptance = resolveApprovedPlannerInput(repoRoot, phase, undefined);
+    const acceptanceText = readTextFile(acceptance.inputPath, repoRoot);
+    sections.push(`Approved acceptance input (${acceptance.inputPath}):`, acceptanceText.trimEnd());
+  }
+
+  sections.push(
+    `Current ${phase} draft (${current.draft.path}):`,
+    current.draft.contents.trimEnd(),
+    `Human feedback (${feedbackPath}):`,
+    feedbackText.trimEnd(),
+  );
+
+  return compactRevisionInput(sections.join('\n\n'), compactionOptions);
+}
+
+function buildManagedContextBlock(content) {
+  return `${CONTEXT_PREP_START}\n${String(content || '').trimEnd()}\n${CONTEXT_PREP_END}\n`;
+}
+
+function mergeContextDraft(existingContent, draftContent) {
+  const existing = normalizeText(existingContent);
+  const block = buildManagedContextBlock(draftContent);
+  const startIndex = existing.indexOf(CONTEXT_PREP_START);
+  const endIndex = existing.indexOf(CONTEXT_PREP_END);
+
+  if (startIndex >= 0 && endIndex > startIndex) {
+    const before = existing.slice(0, startIndex).trimEnd();
+    const after = existing.slice(endIndex + CONTEXT_PREP_END.length).trimStart();
+    return `${before}\n\n${block}${after ? `\n${after}` : ''}`;
+  }
+
+  return `${existing.trimEnd()}\n\n${block}`;
+}
+
+function firstChangedLineIndex(beforeLines, afterLines) {
+  const max = Math.max(beforeLines.length, afterLines.length);
+  for (let index = 0; index < max; index += 1) {
+    if (beforeLines[index] !== afterLines[index]) {
+      return index;
+    }
+  }
+  return -1;
+}
+
+function buildDiffSnippet(pathLabel, beforeContent, afterContent, maxLines = 10) {
+  const beforeLines = normalizeText(beforeContent).split('\n');
+  const afterLines = normalizeText(afterContent).split('\n');
+  const changedAt = firstChangedLineIndex(beforeLines, afterLines);
+
+  if (changedAt === -1) {
+    return [`diff -- ${pathLabel}`, '  no changes'];
+  }
+
+  const start = Math.max(0, changedAt - 2);
+  const beforeSnippet = beforeLines.slice(start, start + maxLines);
+  const afterSnippet = afterLines.slice(start, start + maxLines);
+  const lines = [
+    `--- ${pathLabel} (current)`,
+    `+++ ${pathLabel} (proposed)`,
+  ];
+
+  for (const line of beforeSnippet) {
+    if (line) {
+      lines.push(`- ${line}`);
+    }
+  }
+
+  for (const line of afterSnippet) {
+    if (line) {
+      lines.push(`+ ${line}`);
+    }
+  }
+
+  return lines;
+}
+
+function buildContextWritePlan(repoRoot, drafts) {
+  return drafts.map((draft) => {
     const destinationPath = path.join(repoRoot, draft.path);
-    fs.mkdirSync(path.dirname(destinationPath), { recursive: true });
-    fs.writeFileSync(destinationPath, `${draft.content.replace(/\s+$/g, '')}\n`);
-    writtenDocs.push(draft.path);
+    const exists = fs.existsSync(destinationPath);
+    const currentContent = exists ? fs.readFileSync(destinationPath, 'utf8') : '';
+    const proposedContent = exists
+      ? mergeContextDraft(currentContent, draft.content)
+      : `${String(draft.content || '').replace(/\s+$/g, '')}\n`;
+    const changed = normalizeText(currentContent) !== normalizeText(proposedContent);
+
+    return {
+      path: draft.path,
+      destinationPath,
+      action: changed ? (exists ? 'update' : 'create') : 'skip',
+      reason: changed ? (exists ? 'human content preserved; Quiver block appended or refreshed' : 'missing approved context doc') : 'already up to date',
+      exists,
+      currentContent,
+      proposedContent,
+      diff: buildDiffSnippet(draft.path, currentContent, proposedContent),
+    };
+  });
+}
+
+function formatDiffPreview(writePlan) {
+  const lines = [];
+  for (const item of writePlan) {
+    if (item.action === 'skip') {
+      continue;
+    }
+    lines.push(...item.diff);
+  }
+  return lines.length > 0 ? lines : ['- no changes'];
+}
+
+function createContextSnapshots(repoRoot, run, writePlan, now = new Date()) {
+  const stamp = now.toISOString().replace(/[-:]/g, '').replace(/\.\d{3}Z$/, 'Z');
+  const snapshotRoot = path.join(repoRoot, '.quiver', 'runs', run.run_id, 'snapshots', stamp);
+  const manifest = {
+    schema_version: 1,
+    run_id: run.run_id,
+    created_at: now.toISOString(),
+    entries: [],
+  };
+
+  fs.mkdirSync(snapshotRoot, { recursive: true });
+
+  for (const item of writePlan) {
+    if (item.action === 'skip') {
+      continue;
+    }
+    const entry = {
+      path: item.path,
+      action: item.action,
+      existed: item.exists,
+      snapshot_path: null,
+    };
+
+    if (item.exists) {
+      const snapshotPath = path.join(snapshotRoot, item.path);
+      fs.mkdirSync(path.dirname(snapshotPath), { recursive: true });
+      fs.copyFileSync(item.destinationPath, snapshotPath);
+      entry.snapshot_path = path.relative(repoRoot, snapshotPath).split(path.sep).join('/');
+    }
+
+    manifest.entries.push(entry);
+  }
+
+  const manifestPath = path.join(snapshotRoot, 'manifest.json');
+  fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+
+  return {
+    root: path.relative(repoRoot, snapshotRoot).split(path.sep).join('/'),
+    manifestPath: path.relative(repoRoot, manifestPath).split(path.sep).join('/'),
+    entries: manifest.entries,
+  };
+}
+
+function writeDraftDocs(writePlan) {
+  const writtenDocs = [];
+  for (const item of writePlan) {
+    if (item.action === 'skip') {
+      continue;
+    }
+    fs.mkdirSync(path.dirname(item.destinationPath), { recursive: true });
+    fs.writeFileSync(item.destinationPath, item.proposedContent);
+    writtenDocs.push(item.path);
   }
   return writtenDocs;
 }
@@ -350,6 +609,20 @@ async function runOnboard(repoRoot, options = {}) {
     return report;
   }
 
+  if (options.printPrompt) {
+    const report = {
+      task: 'onboard',
+      provider,
+      role,
+      contextPack: context,
+      invocation,
+      onboardingPlan: contextInfo.plan,
+      prompt,
+    };
+    process.stdout.write(formatPromptOnlyReport(report));
+    return report;
+  }
+
   let result;
   try {
     result = await (options.runProviderFn || runProvider)(provider, {
@@ -386,33 +659,62 @@ async function runOnboard(repoRoot, options = {}) {
 
 async function runPrepareContext(repoRoot, options = {}) {
   const draftPack = buildContextPreparationDrafts(repoRoot);
+  const writePlan = buildContextWritePlan(repoRoot, draftPack.docs);
   const report = {
     task: 'prepare-context',
     dryRun: options.dryRun === true,
     docs: draftPack.docs.map((doc) => doc.path),
     plan: draftPack.plan,
+    writePlan: writePlan.map((item) => ({
+      path: item.path,
+      action: item.action,
+      reason: item.reason,
+    })),
   };
 
   if (options.dryRun) {
     process.stdout.write(formatContextPreparationReport({
       dryRun: true,
-      docs: draftPack.docs,
       plan: draftPack.plan,
+      writePlan,
       writtenDocs: [],
     }));
     return report;
   }
 
-  const writtenDocs = writeDraftDocs(repoRoot, draftPack.docs);
+  const lifecycleRun = ensureAiRun(repoRoot, {
+    command: 'ai prepare-context',
+    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',
+  });
   process.stdout.write(formatContextPreparationReport({
     dryRun: false,
-    docs: draftPack.docs,
     plan: draftPack.plan,
+    writePlan,
     writtenDocs,
+    snapshot,
+    completed: true,
   }));
 
   return {
     ...report,
+    runId: lifecycleRun.run_id,
+    snapshot,
     writtenDocs,
   };
 }
@@ -424,6 +726,7 @@ async function runPlan(repoRoot, options = {}) {
   const context = options.context || DEFAULT_PLAN_CONTEXT;
   const timeoutMs = normalizeTimeout(options.timeout);
   let inputPath = options.input || '';
+  let inputCompaction = null;
 
   if (phase === 'spec') {
     const resolved = resolveReviewedTechnicalPlanInput(repoRoot, inputPath || undefined);
@@ -436,6 +739,17 @@ async function runPlan(repoRoot, options = {}) {
       specSlug: options.specSlug,
     });
 
+    if (options.printPrompt) {
+      const report = {
+        task: 'plan',
+        phase,
+        manifest,
+      };
+      process.stdout.write('AI plan prompt-only\nPhase: spec\nNo provider prompt is used for spec generation; showing the local generation plan instead.\n');
+      process.stdout.write(formatSpecDryRunReport({ manifest, repoRoot }));
+      return report;
+    }
+
     if (options.dryRun) {
       const report = {
         task: 'plan',
@@ -464,7 +778,23 @@ async function runPlan(repoRoot, options = {}) {
 
   assertPlannerPhaseReady(phase);
 
-  if (phase === 'technical-plan') {
+  let inputText = '';
+
+  if (options.revise === true) {
+    if (!inputPath) {
+      throw new Error(formatError(`missing feedback input file for ai revise phase '${phase}'`));
+    }
+    const feedbackText = readTextFile(inputPath, repoRoot);
+    const revisionInput = buildRevisionInput({
+      phase,
+      feedbackPath: inputPath,
+      feedbackText,
+      repoRoot,
+      compactionOptions: options,
+    });
+    inputText = revisionInput.text;
+    inputCompaction = revisionInput.compaction;
+  } else if (phase === 'technical-plan') {
     const resolved = resolveApprovedPlannerInput(repoRoot, phase, inputPath || undefined);
     inputPath = resolved.inputPath;
   }
@@ -473,7 +803,9 @@ async function runPlan(repoRoot, options = {}) {
     throw new Error(formatError(`missing input file for ai plan phase '${phase}'`));
   }
 
-  const inputText = readTextFile(inputPath, repoRoot);
+  if (!inputText) {
+    inputText = readTextFile(inputPath, repoRoot);
+  }
   const contextInfo = buildPlanContext({
     role,
     context,
@@ -481,8 +813,10 @@ async function runPlan(repoRoot, options = {}) {
     inputText,
     inputPath,
     repoRoot,
+    revise: options.revise === true,
   });
   const prompt = contextInfo.prompt;
+  assertProviderPromptWithinLimit(prompt, options);
   let invocation;
 
   try {
@@ -508,6 +842,20 @@ async function runPlan(repoRoot, options = {}) {
     return report;
   }
 
+  if (options.printPrompt) {
+    const report = {
+      task: 'plan',
+      provider,
+      role,
+      contextPack: contextInfo.pack.packName,
+      phase,
+      invocation,
+      prompt,
+    };
+    process.stdout.write(formatPromptOnlyReport(report));
+    return report;
+  }
+
   let result;
   try {
     result = await (options.runProviderFn || runProvider)(provider, {
@@ -531,7 +879,31 @@ async function runPlan(repoRoot, options = {}) {
     throw annotateProviderError(result.error || new Error('provider run failed'), 'plan', phase);
   }
 
-  savePlannerDraft(repoRoot, phase, inputPath, [result.stdout, result.stderr].filter(Boolean).join(''));
+  const lifecycleRun = ensureAiRun(repoRoot, {
+    command: `ai plan --phase ${phase}`,
+    input: inputPath,
+    runId: options.runId,
+  });
+  const clean = extractCleanProviderOutput(result, { prompt, projectRoot: repoRoot });
+  const rawArtifact = writeRawProviderArtifact(repoRoot, lifecycleRun.run_id, `ai-plan-${phase}`, result, {
+    metadata: {
+      phase,
+      input_path: inputPath,
+      prompt_bytes: invocation.promptLength,
+      clean_output_source: clean.source,
+      stripped_prompt_echo: clean.strippedPromptEcho,
+      input_compaction: inputCompaction,
+    },
+  });
+  const draft = savePlannerDraft(repoRoot, phase, inputPath, clean.cleanOutput, {
+    rawArtifactPath: rawArtifact.path,
+    outputSource: clean.source,
+    inputCompaction,
+  });
+  updateAiRunPhase(repoRoot, lifecycleRun.run_id, phase === 'acceptance' ? 'acceptance-draft' : 'technical-plan-draft', {
+    artifact: path.relative(repoRoot, draft.filePath).split(path.sep).join('/'),
+    command: `ai plan --phase ${phase}`,
+  });
 
   return {
     task: 'plan',
@@ -562,6 +934,7 @@ async function runReviewPlan(repoRoot, options = {}) {
     inputText,
     inputPath,
   });
+  assertProviderPromptWithinLimit(built.prompt, options);
   let invocation;
 
   try {
@@ -603,6 +976,24 @@ async function runReviewPlan(repoRoot, options = {}) {
     return report;
   }
 
+  if (options.printPrompt) {
+    const report = {
+      task: 'review-plan',
+      provider,
+      role: 'reviewer',
+      contextPack: pack.packName,
+      phase: 'plan-review',
+      invocation,
+      prompt: built.prompt,
+      promptSource: built.promptSource,
+      inputPath,
+      inputKind: resolved.kind,
+      inputVersion: resolved.version,
+    };
+    process.stdout.write(formatPromptOnlyReport(report));
+    return report;
+  }
+
   let result;
   try {
     result = await (options.runProviderFn || runProvider)(provider, {
@@ -626,11 +1017,31 @@ async function runReviewPlan(repoRoot, options = {}) {
     throw annotateProviderError(result.error || new Error('provider run failed'), 'review-plan');
   }
 
+  const lifecycleRun = ensureAiRun(repoRoot, {
+    command: 'ai review-plan',
+    input: inputPath,
+    runId: options.runId,
+    phase: 'technical-plan-reviewed',
+  });
+  const clean = extractCleanProviderOutput(result, { prompt: built.prompt, projectRoot: repoRoot });
+  const rawArtifact = writeRawProviderArtifact(repoRoot, lifecycleRun.run_id, 'ai-review-plan', result, {
+    metadata: {
+      phase: 'plan-review',
+      input_path: inputPath,
+      input_kind: resolved.kind,
+      input_version: resolved.version || null,
+      prompt_bytes: invocation.promptLength,
+      clean_output_source: clean.source,
+      stripped_prompt_echo: clean.strippedPromptEcho,
+    },
+  });
   const saved = savePlanReview(repoRoot, {
-    contents: [result.stdout, result.stderr].filter(Boolean).join(''),
+    contents: clean.cleanOutput,
     inputPath,
     inputKind: resolved.kind,
     inputVersion: resolved.version,
+    outputSource: clean.source,
+    rawArtifactPath: rawArtifact.path,
   });
   const relativePath = path.relative(repoRoot, saved.filePath).split(path.sep).join('/');
   process.stdout.write(`AI plan review saved\nArtifact: ${relativePath}\nPrompt source: ${PLAN_REVIEW_PROMPT_SOURCE}\n`);
@@ -649,17 +1060,46 @@ async function runReviewPlan(repoRoot, options = {}) {
   };
 }
 
+async function runRevise(repoRoot, options = {}) {
+  const phase = normalizePlannerPhase(options.phase || DEFAULT_PLAN_PHASE);
+  if (phase === 'spec') {
+    throw new Error(formatError(`ai revise does not support phase '${phase}'`));
+  }
+
+  const approval = readPhaseApproval(repoRoot, phase);
+  if (approval.status !== 'draft' && approval.status !== 'stale') {
+    throw new Error(formatError(`ai revise --phase ${phase} requires an existing draft; current status is ${approval.status}. Run \`npx create-quiver ai plan --phase ${phase} --input <file>\` first.`));
+  }
+
+  return runPlan(repoRoot, {
+    ...options,
+    phase,
+    revise: true,
+  });
+}
+
 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.input && !options.version) {
-    throw new Error(formatError(`missing input file for ai approve 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 inputText = options.version ? '' : readTextFile(options.input, repoRoot);
+  if (phase === 'technical-plan') {
+    const review = readPlanReview(repoRoot);
+    if (review.status !== 'unapproved' && review.status !== 'reviewed') {
+      throw new Error(formatError(`ai approve --phase technical-plan requires a production review for the current draft; current review status is ${review.status}. Run \`npx create-quiver ai review-plan\`.`));
+    }
+  }
+
+  const inputText = '';
 
   if (options.dryRun) {
     process.stdout.write(formatApprovalDryRunResult({ phase, input: options.input, version: options.version }));
@@ -675,6 +1115,21 @@ async function runApprove(repoRoot, options = {}) {
   const result = approvePlannerPhase(repoRoot, phase, options.input || '', inputText, {
     version: options.version || undefined,
   });
+  const lifecycleRun = ensureAiRun(repoRoot, {
+    command: `ai approve --phase ${phase}`,
+    input: options.input || result.filePath,
+    runId: options.runId,
+  });
+  recordAiRunApproval(repoRoot, lifecycleRun.run_id, {
+    artifact: path.relative(repoRoot, result.filePath).split(path.sep).join('/'),
+    phase,
+    source_file: options.input || `draft version ${options.version}`,
+    version: result.version || null,
+  });
+  updateAiRunPhase(repoRoot, lifecycleRun.run_id, phase === 'acceptance' ? 'acceptance-approved' : 'technical-plan-approved', {
+    artifact: path.relative(repoRoot, result.filePath).split(path.sep).join('/'),
+    command: `ai approve --phase ${phase}`,
+  });
   process.stdout.write(formatApprovalResult({
     ...result,
     sourceFile: options.input || `draft version ${options.version}`,
@@ -699,6 +1154,131 @@ async function runApprovalStatus(repoRoot) {
   };
 }
 
+function runLifecycleStatus(repoRoot, options = {}) {
+  const run = resolveAiRun(repoRoot, options.runId || '');
+  const report = formatAiRunStatus(repoRoot, run);
+  process.stdout.write(report);
+  return {
+    task: 'status',
+    run,
+    report,
+  };
+}
+
+function runLifecycleResume(repoRoot, options = {}) {
+  const run = resolveAiRun(repoRoot, options.runId || '');
+  const report = formatAiRunResume(repoRoot, run);
+  process.stdout.write(report);
+  return {
+    task: 'resume',
+    run,
+    report,
+  };
+}
+
+function runInspect(repoRoot, options = {}) {
+  const report = collectLifecycleExport(repoRoot, {
+    includeCompleted: options.includeCompleted === true,
+  });
+  process.stdout.write(formatLifecycleInspect(report));
+  return {
+    task: 'inspect',
+    report,
+  };
+}
+
+function runExport(repoRoot, options = {}) {
+  const report = collectLifecycleExport(repoRoot, {
+    includeCompleted: options.includeCompleted === true,
+  });
+  const format = String(options.format || 'json').trim().toLowerCase();
+
+  if (format === 'json') {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    return {
+      task: 'export',
+      format,
+      report,
+    };
+  }
+
+  if (format === 'markdown' || format === 'md') {
+    process.stdout.write(formatLifecycleExportMarkdown(report));
+    return {
+      task: 'export',
+      format: 'markdown',
+      report,
+    };
+  }
+
+  throw new Error(formatError(`unsupported ai export format: ${format}. Supported formats: json, markdown`));
+}
+
+function runSpecsList(repoRoot, options = {}) {
+  const report = collectLifecycleExport(repoRoot, {
+    includeCompleted: options.includeCompleted === true,
+  });
+  if (options.json === true) {
+    process.stdout.write(`${JSON.stringify({ specs: report.specs }, null, 2)}\n`);
+  } else {
+    process.stdout.write(formatSpecsList(report));
+  }
+  return {
+    task: 'specs',
+    specs: report.specs,
+  };
+}
+
+function runSlicesList(repoRoot, options = {}) {
+  const report = collectLifecycleExport(repoRoot, {
+    includeCompleted: options.includeCompleted === true,
+  });
+  if (options.json === true) {
+    process.stdout.write(`${JSON.stringify({ slices: report.slices }, null, 2)}\n`);
+  } else {
+    process.stdout.write(formatSlicesList(report));
+  }
+  return {
+    task: 'slices',
+    slices: report.slices,
+  };
+}
+
+function runTraceReport(repoRoot, options = {}) {
+  const report = collectLifecycleExport(repoRoot, {
+    includeCompleted: options.includeCompleted === true,
+  });
+  process.stdout.write(formatTraceReport(report));
+  return {
+    task: 'trace',
+    report,
+  };
+}
+
+function runLifecycleRun(repoRoot, options = {}) {
+  const command = String(options.command || '').trim().toLowerCase();
+  if (command !== 'create') {
+    throw new Error(formatError(`unsupported ai run subcommand: ${command}. Supported tasks: create`));
+  }
+  if (!options.input) {
+    throw new Error(formatError('ai run create requires --input <requirements.md>'));
+  }
+  const run = createAiRun(repoRoot, {
+    command: 'ai run create',
+    input: options.input,
+    runId: options.runId,
+    specSlug: options.specSlug,
+  });
+  const report = formatAiRunStatus(repoRoot, run);
+  process.stdout.write(report);
+  return {
+    task: 'run',
+    command,
+    run,
+    report,
+  };
+}
+
 function formatAgentProfile(profile) {
   const lines = [
     `Role: ${profile.role}`,
@@ -725,16 +1305,47 @@ function formatAgentProfileList(profiles) {
   return `${lines.join('\n')}\n`;
 }
 
+function formatAgentProfileDryRun(repoRoot, result) {
+  const relativePath = path.relative(repoRoot, result.filePath).split(path.sep).join('/');
+  const verb = result.action === 'update' ? 'update' : 'create';
+  return [
+    'AI agent profile dry-run',
+    '- Writes: none',
+    `- Would ${verb}: ${relativePath}`,
+    '',
+    formatAgentProfile(result.profile).trimEnd(),
+    '',
+    'No secrets or provider credentials are stored in agent profiles.',
+    '',
+  ].join('\n');
+}
+
 function runAgent(repoRoot, options = {}) {
   const command = String(options.command || '').trim().toLowerCase();
 
   if (command === 'set') {
     if (!options.role) {
-      throw new Error(formatError('missing agent role. Use: npx create-quiver ai agent set <planner|executor|reviewer|researcher> --provider <provider>'));
+      throw new Error(formatError('missing agent role. Use: npx create-quiver ai agent set <planner|executor|reviewer|doctor> --provider <provider>'));
     }
     if (!options.provider) {
       throw new Error(formatError('ai agent set requires --provider. Supported providers: codex, claude, gemini.'));
     }
+    if (options.dryRun) {
+      const preview = buildAgentProfileState(repoRoot, options.role, {
+        context: options.context,
+        label: options.label,
+        model: options.model,
+        provider: options.provider,
+      });
+      process.stdout.write(formatAgentProfileDryRun(repoRoot, preview));
+      return {
+        task: 'agent',
+        command,
+        dryRun: true,
+        profile: preview.profile,
+        filePath: path.relative(repoRoot, preview.filePath).split(path.sep).join('/'),
+      };
+    }
     const result = setAgentProfile(repoRoot, options.role, {
       context: options.context,
       label: options.label,
@@ -754,11 +1365,16 @@ function runAgent(repoRoot, options = {}) {
 
   if (command === 'show') {
     if (!options.role) {
-      throw new Error(formatError('missing agent role. Use: npx create-quiver ai agent show <planner|executor|reviewer|researcher>'));
+      throw new Error(formatError('missing agent role. Use: npx create-quiver ai agent show <planner|executor|reviewer|doctor>'));
     }
     const profile = getAgentProfile(repoRoot, options.role);
     if (!profile) {
-      throw new Error(formatError(`agent profile '${options.role}' is not configured. Run: npx create-quiver ai agent set ${options.role} --provider <provider> --model <label>`));
+      throw new Error(formatActionableError({
+        failure: `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>`,
+      }));
     }
     process.stdout.write(formatAgentProfile(profile));
     return {
@@ -903,12 +1519,21 @@ module.exports = {
   runDoctor,
   runExecutePlan,
   runExecuteSlice,
+  runLifecycleResume,
+  runLifecycleRun,
+  runLifecycleStatus,
+  runExport,
+  runInspect,
   runPromptSlice,
   runApprove,
   runApprovalStatus,
   runPrepareContext,
   runReviewPlan,
+  runRevise,
   runPr,
+  runSlicesList,
+  runSpecsList,
+  runTraceReport,
   runOnboard,
   runPlan,
   writeProviderOutput,