create-quiver 0.17.1 → 0.17.3

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

@@ -22,18 +22,43 @@ const {
   formatAnalyzeProjectDiffPreview,
   writeAnalyzeProjectDocs,
 } = require('../lib/ai/analyze-project-docs');
-const { parseAnalyzeProjectOutput } = require('../lib/ai/analyze-project-parser');
-const { buildAnalyzeProjectPrompt } = require('../lib/ai/analyze-project-prompts');
+const {
+  buildAnalyzeProjectPrompt,
+  buildAnalyzeProjectRetryPrompt,
+  buildSelectedContextManifest,
+  writeSelectedContextManifest,
+} = require('../lib/ai/analyze-project-prompts');
+const {
+  parseAnalyzeProjectOutputWithRepair,
+  writeAnalyzeProjectRepairManifest,
+} = require('../lib/ai/analyze-project-repair');
 const {
   confirmAnalyzeProjectWrites,
   reviewAnalyzeProjectDocProposal,
 } = require('../lib/ai/analyze-project-review');
+const {
+  findLatestAnalyzeProjectSavedProposalRun,
+  readAnalyzeProjectSavedProposal,
+  writeAnalyzeProjectProposalArtifacts,
+} = require('../lib/ai/analyze-project-proposal');
+const {
+  applyAnalyzeProjectDocProposal,
+} = require('../lib/ai/analyze-project-apply');
+const {
+  canUseAnalyzeProjectInteractiveSelector,
+  runAnalyzeProjectInteractiveApplySelector,
+} = require('../lib/ai/analyze-project-interactive');
 const {
   DEFAULT_MAX_BYTES: DEFAULT_ANALYZE_MAX_BYTES,
   DEFAULT_MAX_FILES: DEFAULT_ANALYZE_MAX_FILES,
   sampleProjectFiles,
 } = require('../lib/ai/analyze-project-sampling');
-const { validateAnalyzeProjectPostWrite } = require('../lib/ai/analyze-project-validation');
+const {
+  groupAnalyzeProjectIssues,
+  validateAnalyzeProjectPostWrite,
+  writeAnalyzeProjectRetryManifest,
+  writeAnalyzeProjectValidationManifest,
+} = require('../lib/ai/analyze-project-validation');
 const { openEditor } = require('../lib/cli/editor');
 const { selectOption, promptText } = require('../lib/cli/selectors');
 const { createUx } = require('../lib/cli/ux');
@@ -166,22 +191,23 @@ function limitList(items, maxItems = 30) {
 }
 
 function formatAnalyzeProjectIssues(issues = [], maxIssues = 8) {
-  const list = Array.isArray(issues) ? issues : [];
-  const visible = list.slice(0, maxIssues);
-  const lines = visible.map((issue) => {
-    const location = issue.path || 'analysis';
-    const code = issue.issue || 'invalid';
-    const message = issue.message || 'Invalid provider analysis output.';
-    return `- ${location}: ${code} - ${message}`;
+  const groups = groupAnalyzeProjectIssues(issues, { maxExamplesPerGroup: 1 });
+  const visible = groups.slice(0, maxIssues);
+  const lines = visible.map((group) => {
+    const example = group.examples[0];
+    const exampleText = example
+      ? ` Example: ${example.path || 'analysis'} - ${example.message}`
+      : '';
+    return `- ${group.path_family}: ${group.type} (${group.count} issue${group.count === 1 ? '' : 's'}). Cause: ${group.cause_hint}${exampleText}`;
   });
-  const hidden = list.length - visible.length;
+  const hidden = groups.length - visible.length;
   if (hidden > 0) {
-    lines.push(`- ... ${hidden} more issue${hidden === 1 ? '' : 's'}`);
+    lines.push(`- ... ${hidden} more issue group${hidden === 1 ? '' : 's'}`);
   }
   return lines;
 }
 
-function enhanceAnalyzeProjectAnalysisError(error) {
+function enhanceAnalyzeProjectAnalysisError(error, options = {}) {
   if (!error || error.code !== 'AI_ANALYZE_PROJECT_INVALID') {
     return error;
   }
@@ -195,13 +221,19 @@ function enhanceAnalyzeProjectAnalysisError(error) {
     error.message,
     'Issues:',
     ...issueLines,
+    options.repairManifest?.path ? `Repair manifest: ${options.repairManifest.path}` : '',
+    options.retryManifest?.path ? `Retry manifest: ${options.retryManifest.path}` : '',
+    options.validationManifest?.path ? `Validation manifest: ${options.validationManifest.path}` : '',
     'Next safe step: inspect the selected evidence with `npx create-quiver ai analyze-project --deep --dry-run --json`, then rerun live. If provider drift repeats, reduce --max-files or --max-bytes.',
-  ].join('\n'));
+  ].filter(Boolean).join('\n'));
   wrapped.name = error.name;
   wrapped.code = error.code;
   wrapped.cause = error;
   wrapped.issues = error.issues;
   wrapped.details = error.issues;
+  wrapped.repair_manifest = options.repairManifest || null;
+  wrapped.retry_manifest = options.retryManifest || null;
+  wrapped.validation_manifest = options.validationManifest || null;
   return wrapped;
 }
 
@@ -251,6 +283,9 @@ function formatAnalyzeProjectReport(report) {
   lines.push(`Source roots: ${report.detected.source_roots.length > 0 ? report.detected.source_roots.join(', ') : 'none'}`);
   lines.push(`Entrypoints: ${report.detected.entrypoints.length > 0 ? report.detected.entrypoints.join(', ') : 'none'}`);
   lines.push(`Configs: ${report.detected.configs.length > 0 ? report.detected.configs.join(', ') : 'none'}`);
+  lines.push(`Lockfiles: ${(report.detected.lockfiles || []).length > 0
+    ? report.detected.lockfiles.map((file) => `${file.path} (${file.package_manager}; metadata only)`).join(', ')
+    : 'none'}`);
 
   lines.push('', 'Selected files:');
   for (const file of selected.items) {
@@ -397,6 +432,60 @@ function buildAnalyzeProjectProviderArtifact(result, clean, repoRoot, options =
   };
 }
 
+function createAnalyzeProjectAuditRunId(now = new Date()) {
+  const date = now instanceof Date ? now : new Date(now || Date.now());
+  return `run-${date.toISOString()
+    .replace(/\.\d{3}Z$/, 'z')
+    .replace(/[^0-9a-z]+/gi, '-')
+    .toLowerCase()
+    .replace(/^-+|-+$/g, '')}`;
+}
+
+function writeAnalyzeProjectRunStatus(repoRoot, runId, status, details = {}) {
+  const statusPath = path.join(repoRoot, '.quiver', 'runs', runId, 'status.json');
+  fs.mkdirSync(path.dirname(statusPath), { recursive: true });
+  fs.writeFileSync(statusPath, `${JSON.stringify({
+    schema_version: 1,
+    kind: 'quiver-analyze-project-run-status',
+    run_id: runId,
+    status,
+    updated_at: (details.now instanceof Date ? details.now : new Date(details.now || Date.now())).toISOString(),
+    provider: details.provider || null,
+    attempts: details.attempts || [],
+    artifacts: details.artifacts || {},
+  }, null, 2)}\n`);
+  return path.relative(repoRoot, statusPath).split(path.sep).join('/');
+}
+
+function normalizeAnalyzeProjectMaxRetries(value) {
+  if (value === undefined || value === null || value === '') {
+    return 1;
+  }
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    return 1;
+  }
+  return Math.min(2, Math.floor(parsed));
+}
+
+function isAnalyzeProjectRetryableError(error) {
+  if (!error || error.code !== 'AI_ANALYZE_PROJECT_INVALID') {
+    return false;
+  }
+  const retryableIssues = new Set([
+    'empty-output',
+    'malformed-json',
+    'invalid_type',
+    'invalid_value',
+    'unrecognized_keys',
+    'missing-evidence',
+    'evidence-not-selected',
+    'unapproved-doc-update-path',
+  ]);
+  const issues = Array.isArray(error.issues) ? error.issues : [];
+  return issues.length > 0 && issues.every((issue) => retryableIssues.has(issue.issue || ''));
+}
+
 function formatAnalyzeProjectLiveReport(report) {
   const warningCount = report.analysis_validation?.warnings?.length || 0;
   const docUpdatePaths = report.analysis_validation?.doc_update_paths || [];
@@ -405,6 +494,7 @@ function formatAnalyzeProjectLiveReport(report) {
     `Mode: ${report.mode}`,
     `Provider: ${report.provider}`,
     `Provider execution: ${report.provider_execution}`,
+    `Provider attempts: ${report.provider_attempts?.length || 1}`,
     `Writes: ${report.writes.length === 0 ? 'none' : report.writes.join(', ')}`,
     `Privacy preflight: ${report.privacy_preflight.ok ? 'passed' : 'failed'}`,
     `Prompt bytes: ${report.prompt.bytes}/${report.prompt.max_provider_prompt_bytes}`,
@@ -423,12 +513,46 @@ function formatAnalyzeProjectLiveReport(report) {
   }
 
   lines.push('', 'Next commands:');
+  lines.push('- npx create-quiver ai analyze-project --deep --save-proposal --provider <provider> --model <model>');
   lines.push('- npx create-quiver ai analyze-project --deep --review');
   lines.push('- npx create-quiver ai analyze-project --deep --json');
 
   return `${lines.join('\n')}\n`;
 }
 
+function summarizeAnalyzeProjectWritePlan(writePlan = []) {
+  return writePlan.map((item) => ({
+    path: item.path,
+    action: item.action,
+    dirty: item.dirty,
+    before_sha256: item.before_sha256,
+    after_sha256: item.after_sha256,
+    reason: item.reason,
+  }));
+}
+
+function formatAnalyzeProjectSavedProposalReport(report = {}) {
+  const artifacts = report.proposal_artifacts || {};
+  const changed = report.write_plan?.filter((item) => item.action !== 'skip') || [];
+  const lines = [
+    'AI analyze-project proposal saved',
+    `Run: ${report.run_id || 'unknown'}`,
+    `Provider: ${report.provider || 'unknown'}`,
+    `Writes: none (final docs were not modified)`,
+    `Proposed docs: ${report.doc_paths?.length || 0}`,
+    `Docs with changes: ${changed.length}`,
+    `Proposal JSON: ${artifacts.proposal_json || 'none'}`,
+    `Proposal summary: ${artifacts.proposal_markdown || 'none'}`,
+    `Proposal diff: ${artifacts.proposal_diff || 'none'}`,
+    `Manifest: ${artifacts.manifest || 'none'}`,
+    '',
+    'Next commands:',
+    `- npx create-quiver ai analyze-project apply --run ${report.run_id || '<run-id>'}`,
+    '- npx create-quiver ai analyze-project --deep --apply-docs --provider <provider> --model <model>',
+  ];
+  return `${lines.join('\n')}\n`;
+}
+
 function formatAnalyzeProjectPostWriteValidation(validation) {
   if (!validation) {
     return [];
@@ -475,6 +599,430 @@ function formatAnalyzeProjectReviewPlan({ writePlan, reviewPath, snapshot, writt
   return `${lines.join('\n')}\n`;
 }
 
+function formatAnalyzeProjectApplyReport(report = {}) {
+  const artifacts = report.proposal_artifacts || {};
+  const writeManifest = report.write_manifest || {};
+  const changed = report.write_plan?.filter((item) => item.action !== 'skip') || [];
+  const dirty = changed.filter((item) => item.dirty);
+  const lines = [
+    'AI analyze-project docs applied',
+    `Run: ${report.run_id || 'unknown'}`,
+    `Provider: ${report.provider || 'unknown'}`,
+    report.provider_execution ? `Provider execution: ${report.provider_execution}` : '',
+    report.apply_run ? `Saved proposal edited: ${report.saved_proposal?.proposal_edited ? 'yes' : 'no'}` : '',
+    `Writes: ${changed.length > 0 ? changed.map((item) => item.path).join(', ') : 'none'}`,
+    `Dirty target docs: ${dirty.length > 0 ? dirty.map((item) => item.path).join(', ') : 'none'}`,
+    `Written docs: ${report.written_docs?.length > 0 ? report.written_docs.join(', ') : 'none'}`,
+    `Snapshot: ${report.snapshot?.root || 'none'}`,
+    `Proposal manifest: ${artifacts.manifest || 'none'}`,
+    `Write manifest: ${writeManifest.path || 'none'}`,
+  ].filter(Boolean);
+  lines.push(...formatAnalyzeProjectPostWriteValidation(report.post_write_validation));
+  return `${lines.join('\n')}\n`;
+}
+
+function formatAnalyzeProjectApplyPreflightError(error) {
+  if (!error || error.code !== 'AI_ANALYZE_PROJECT_APPLY_BLOCKED') {
+    return error;
+  }
+
+  const issueLines = (error.issues || []).slice(0, 12).map((issue) => {
+    const hashes = issue.expected_sha256 || issue.current_sha256
+      ? ` expected=${issue.expected_sha256 || 'none'} current=${issue.current_sha256 || 'none'}`
+      : '';
+    return `- ${issue.path || 'docs'}: ${issue.issue}${hashes} - ${issue.message}`;
+  });
+  const wrapped = new Error([
+    error.message,
+    'Issues:',
+    ...issueLines,
+    error.apply_run
+      ? 'Next safe step: inspect `.quiver/runs/<run-id>/proposal/analyze-project-doc-proposal.diff`, then rerun with an explicit run id. Add `--allow-dirty-docs` only if overwriting existing managed docs is intended.'
+      : 'Next safe step: rerun with `--review`, or inspect with `--save-proposal`, or add `--allow-dirty-docs` if overwriting existing managed docs is intended.',
+  ].join('\n'));
+  wrapped.name = error.name;
+  wrapped.code = error.code;
+  wrapped.cause = error;
+  wrapped.issues = error.issues;
+  return wrapped;
+}
+
+function resolveAnalyzeProjectSavedProposalRunId(repoRoot, options = {}) {
+  const requestedRunId = String(options.runId || '').trim();
+  if (requestedRunId !== 'latest') {
+    return { runId: requestedRunId, requestedRunId };
+  }
+
+  if (!canUseInteractiveTerminal(options)) {
+    throw analyzeProjectContractError(
+      'ai analyze-project apply --run latest requires an interactive terminal.',
+      'Use an explicit run id for automation: `npx create-quiver ai analyze-project apply --run <run-id>`.',
+    );
+  }
+
+  const latestRunId = findLatestAnalyzeProjectSavedProposalRun(repoRoot);
+  if (!latestRunId) {
+    throw analyzeProjectContractError(
+      'ai analyze-project apply --run latest could not find a saved proposal.',
+      'Create one first: `npx create-quiver ai analyze-project --deep --save-proposal --provider <provider> --model <model>`.',
+    );
+  }
+
+  if (options.json !== true) {
+    process.stdout.write(`Resolved latest analyze-project proposal: ${latestRunId}\n`);
+  }
+  return { runId: latestRunId, requestedRunId };
+}
+
+function analyzeProjectRawProviderArtifactPaths(rawProviderArtifacts = []) {
+  return (Array.isArray(rawProviderArtifacts) ? rawProviderArtifacts : [])
+    .map((artifact) => (typeof artifact === 'string' ? artifact : artifact?.path))
+    .filter(Boolean);
+}
+
+function summarizeAnalyzeProjectProposalArtifacts(proposalArtifacts = {}) {
+  return {
+    root: proposalArtifacts.root,
+    proposal_json: proposalArtifacts.proposal_json,
+    proposal_markdown: proposalArtifacts.proposal_markdown,
+    proposal_diff: proposalArtifacts.proposal_diff,
+    manifest: proposalArtifacts.manifest,
+    proposal_sha256: proposalArtifacts.proposal_sha256,
+  };
+}
+
+function listAnalyzeProjectProposalArtifactFiles(proposalArtifacts = {}) {
+  if (Array.isArray(proposalArtifacts.files)) {
+    return proposalArtifacts.files.filter(Boolean);
+  }
+  return [
+    proposalArtifacts.proposal_json,
+    proposalArtifacts.proposal_markdown,
+    proposalArtifacts.proposal_diff,
+    proposalArtifacts.manifest,
+  ].filter(Boolean);
+}
+
+function saveAnalyzeProjectDocProposalReport(repoRoot, options = {}) {
+  const proposalArtifacts = writeAnalyzeProjectProposalArtifacts(repoRoot, {
+    runId: options.auditRunId,
+    now: options.commandOptions?.now || new Date(),
+    provider: options.provider,
+    language: options.commandOptions?.language,
+    proposal: options.proposal,
+    writePlan: options.writePlan,
+    selectedContextManifest: options.selectedContextManifest,
+    repairManifest: options.repairManifest,
+    events: options.interactiveAction ? [{
+      type: 'interactive-action',
+      action: options.interactiveAction,
+      at: (options.commandOptions?.now instanceof Date
+        ? options.commandOptions.now
+        : new Date(options.commandOptions?.now || Date.now())).toISOString(),
+    }] : [],
+  });
+  const saveReport = {
+    ...options.completedReport,
+    save_proposal: true,
+    interactive_action: options.interactiveAction || undefined,
+    doc_proposal: options.proposal,
+    doc_paths: proposalArtifacts.doc_paths,
+    proposal_artifacts: summarizeAnalyzeProjectProposalArtifacts(proposalArtifacts),
+    write_plan: summarizeAnalyzeProjectWritePlan(options.writePlan),
+  };
+  writeAnalyzeProjectRunStatus(repoRoot, options.auditRunId, 'proposal-saved', {
+    now: options.commandOptions?.now,
+    provider: options.provider,
+    attempts: options.providerAttempts,
+    artifacts: {
+      selected_context: options.selectedContextManifest,
+      raw_provider: analyzeProjectRawProviderArtifactPaths(options.rawProviderArtifacts),
+      repair: options.repairManifest,
+      retry: options.retryManifest,
+      proposal_manifest: proposalArtifacts.manifest,
+      proposal_files: proposalArtifacts.files,
+    },
+  });
+  return saveReport;
+}
+
+function applyAnalyzeProjectDocProposalReport(repoRoot, options = {}) {
+  let applyReport;
+  try {
+    applyReport = applyAnalyzeProjectDocProposal(repoRoot, {
+      report: options.completedReport,
+      runId: options.auditRunId,
+      now: options.commandOptions?.now || new Date(),
+      provider: options.provider,
+      language: options.commandOptions?.language,
+      proposal: options.proposal,
+      providerArtifact: options.completedReport.provider_artifact,
+      selectedContextManifest: options.selectedContextManifest,
+      repairManifest: options.repairManifest,
+      strict: options.commandOptions?.strict === true,
+      allowDirtyDocs: options.allowDirtyDocs === true,
+      summarizeWritePlan: summarizeAnalyzeProjectWritePlan,
+    });
+  } catch (error) {
+    const proposalArtifacts = error.proposal_artifacts || {};
+    writeAnalyzeProjectRunStatus(repoRoot, options.auditRunId, error.code === 'AI_ANALYZE_PROJECT_APPLY_BLOCKED' ? 'apply-blocked' : 'apply-failed', {
+      now: options.commandOptions?.now,
+      provider: options.provider,
+      attempts: options.providerAttempts,
+      artifacts: {
+        selected_context: options.selectedContextManifest,
+        raw_provider: analyzeProjectRawProviderArtifactPaths(options.rawProviderArtifacts),
+        repair: options.repairManifest,
+        retry: options.retryManifest,
+        proposal_manifest: proposalArtifacts.manifest || null,
+        proposal_files: listAnalyzeProjectProposalArtifactFiles(proposalArtifacts),
+        write_manifest: error.write_manifest?.path || null,
+        snapshot_manifest: error.snapshot?.manifestPath || null,
+      },
+    });
+    throw formatAnalyzeProjectApplyPreflightError(error);
+  }
+
+  applyReport = {
+    ...applyReport,
+    interactive_action: options.interactiveAction || applyReport.interactive_action,
+  };
+  writeAnalyzeProjectRunStatus(repoRoot, options.auditRunId, applyReport.post_write_validation?.ok ? 'docs-applied' : 'apply-validation-failed', {
+    now: options.commandOptions?.now,
+    provider: options.provider,
+    attempts: options.providerAttempts,
+    artifacts: {
+      selected_context: options.selectedContextManifest,
+      raw_provider: analyzeProjectRawProviderArtifactPaths(options.rawProviderArtifacts),
+      repair: options.repairManifest,
+      retry: options.retryManifest,
+      proposal_manifest: applyReport.proposal_artifacts?.manifest,
+      proposal_files: listAnalyzeProjectProposalArtifactFiles(applyReport.proposal_artifacts),
+      write_manifest: applyReport.write_manifest?.path,
+      snapshot_manifest: applyReport.snapshot?.manifestPath,
+    },
+  });
+  return applyReport;
+}
+
+function applyAnalyzeProjectSavedProposalRun(repoRoot, options = {}) {
+  const { runId, requestedRunId } = resolveAnalyzeProjectSavedProposalRunId(repoRoot, options);
+  const now = options.now instanceof Date ? options.now : new Date(options.now || Date.now());
+  const saved = readAnalyzeProjectSavedProposal(repoRoot, runId);
+  const provider = saved.manifest.provider || null;
+  const runStatusPath = path.join('.quiver', 'runs', runId, 'status.json').split(path.sep).join('/');
+  const baseReport = {
+    schema_version: 1,
+    kind: 'quiver-project-analysis-apply-saved-proposal',
+    command: 'ai analyze-project apply',
+    mode: 'apply-saved-proposal',
+    apply_run: true,
+    requested_run_id: requestedRunId,
+    run_id: runId,
+    provider,
+    provider_execution: 'skipped',
+    writes: [],
+    doc_proposal: saved.proposal,
+    saved_proposal: {
+      requested_run_id: requestedRunId,
+      run_id: runId,
+      manifest: saved.artifacts.manifest,
+      proposal_json: saved.artifacts.proposal_json,
+      proposal_sha256: saved.proposal_sha256,
+      proposal_edited: saved.proposal_edited,
+    },
+    run_status_path: runStatusPath,
+  };
+  const events = [
+    {
+      type: 'saved-proposal-apply',
+      at: now.toISOString(),
+      requested_run_id: requestedRunId,
+      run_id: runId,
+    },
+  ];
+  if (saved.proposal_edited) {
+    events.push({
+      type: 'saved-proposal-edited',
+      at: now.toISOString(),
+      original_sha256: saved.manifest.proposal_sha256,
+      current_sha256: saved.proposal_sha256,
+    });
+  }
+
+  let applyReport;
+  try {
+    applyReport = applyAnalyzeProjectDocProposal(repoRoot, {
+      report: baseReport,
+      runId,
+      now,
+      provider,
+      language: saved.manifest.language,
+      proposal: saved.proposal,
+      proposalArtifacts: saved.artifacts,
+      proposalManifest: saved.manifest,
+      proposalEdited: saved.proposal_edited,
+      strict: options.strict === true,
+      allowDirtyDocs: options.allowDirtyDocs === true,
+      summarizeWritePlan: summarizeAnalyzeProjectWritePlan,
+      events,
+    });
+  } catch (error) {
+    error.apply_run = true;
+    const proposalArtifacts = error.proposal_artifacts || saved.artifacts || {};
+    writeAnalyzeProjectRunStatus(repoRoot, runId, error.code === 'AI_ANALYZE_PROJECT_APPLY_BLOCKED' ? 'apply-blocked' : 'apply-failed', {
+      now,
+      provider,
+      attempts: [],
+      artifacts: {
+        proposal_manifest: proposalArtifacts.manifest || saved.artifacts.manifest,
+        proposal_files: listAnalyzeProjectProposalArtifactFiles(proposalArtifacts),
+        write_manifest: error.write_manifest?.path || null,
+        snapshot_manifest: error.snapshot?.manifestPath || null,
+      },
+    });
+    throw formatAnalyzeProjectApplyPreflightError(error);
+  }
+
+  applyReport = {
+    ...applyReport,
+    apply_run: true,
+    requested_run_id: requestedRunId,
+    saved_proposal: baseReport.saved_proposal,
+    run_status_path: runStatusPath,
+  };
+  writeAnalyzeProjectRunStatus(repoRoot, runId, applyReport.post_write_validation?.ok ? 'docs-applied' : 'apply-validation-failed', {
+    now,
+    provider,
+    attempts: [],
+    artifacts: {
+      proposal_manifest: applyReport.proposal_artifacts?.manifest,
+      proposal_files: listAnalyzeProjectProposalArtifactFiles(applyReport.proposal_artifacts),
+      write_manifest: applyReport.write_manifest?.path,
+      snapshot_manifest: applyReport.snapshot?.manifestPath,
+    },
+  });
+  return emitAnalyzeProjectApplyReport(applyReport, options);
+}
+
+function emitAnalyzeProjectApplyReport(applyReport, options = {}) {
+  if (options.json === true) {
+    process.stdout.write(`${JSON.stringify(applyReport, null, 2)}\n`);
+  } else {
+    process.stdout.write(formatAnalyzeProjectApplyReport(applyReport));
+  }
+  if (!applyReport.post_write_validation?.ok) {
+    const error = new Error(formatError('ai analyze-project post-write validation failed.'));
+    error.code = 'AI_ANALYZE_PROJECT_POST_WRITE_VALIDATION_FAILED';
+    error.validation = applyReport.post_write_validation;
+    throw error;
+  }
+  return applyReport;
+}
+
+async function reviewAndWriteAnalyzeProjectDocs(repoRoot, options = {}) {
+  const commandOptions = options.commandOptions || {};
+  const reviewed = await reviewAnalyzeProjectDocProposal(repoRoot, options.initialProposal, commandOptions);
+  const writePlan = buildAnalyzeProjectWritePlan(repoRoot, reviewed.proposal);
+  process.stdout.write(formatAnalyzeProjectReviewPlan({
+    writePlan,
+    reviewPath: reviewed.reviewPath,
+  }));
+  await confirmAnalyzeProjectWrites(writePlan, commandOptions);
+  const lifecycleRun = ensureAiRun(repoRoot, {
+    command: 'ai analyze-project',
+    input: reviewed.reviewPath,
+    runId: commandOptions.runId,
+    phase: 'created',
+  });
+  const snapshot = createAnalyzeProjectSnapshot(repoRoot, lifecycleRun, writePlan, {
+    providerArtifact: options.completedReport.provider_artifact,
+    proposal: reviewed.proposal,
+    now: commandOptions.now || new Date(),
+  });
+  const writtenDocs = writeAnalyzeProjectDocs(writePlan);
+  let writeReport = {
+    ...options.completedReport,
+    review: true,
+    interactive_action: options.interactiveAction || undefined,
+    review_path: reviewed.reviewPath,
+    doc_proposal: reviewed.proposal,
+    write_plan: summarizeAnalyzeProjectWritePlan(writePlan),
+    snapshot,
+    written_docs: writtenDocs,
+    run_id: lifecycleRun.run_id,
+  };
+  const postWriteValidation = validateAnalyzeProjectPostWrite(repoRoot, writeReport, {
+    strict: commandOptions.strict === true,
+  });
+  writeReport = {
+    ...writeReport,
+    post_write_validation: postWriteValidation,
+  };
+
+  if (commandOptions.json === true) {
+    process.stdout.write(`${JSON.stringify(writeReport, null, 2)}\n`);
+    if (!postWriteValidation.ok) {
+      const error = new Error(formatError('ai analyze-project post-write validation failed.'));
+      error.code = 'AI_ANALYZE_PROJECT_POST_WRITE_VALIDATION_FAILED';
+      error.validation = postWriteValidation;
+      throw error;
+    }
+    return writeReport;
+  }
+
+  process.stdout.write(formatAnalyzeProjectReviewPlan({
+    writePlan,
+    reviewPath: reviewed.reviewPath,
+    snapshot,
+    writtenDocs,
+    validation: postWriteValidation,
+    completed: true,
+  }));
+  if (!postWriteValidation.ok) {
+    const error = new Error(formatError('ai analyze-project post-write validation failed.'));
+    error.code = 'AI_ANALYZE_PROJECT_POST_WRITE_VALIDATION_FAILED';
+    error.validation = postWriteValidation;
+    throw error;
+  }
+  return writeReport;
+}
+
+function cancelAnalyzeProjectInteractiveApplyReport(repoRoot, options = {}) {
+  const translator = createTranslator(options.commandOptions?.language);
+  const savedArtifacts = options.savedReport?.proposal_artifacts || null;
+  const cancelReport = {
+    ...options.completedReport,
+    apply_docs: true,
+    interactive_action: options.interactiveAction || 'cancel',
+    cancelled: true,
+    writes: [],
+    written_docs: [],
+    doc_proposal: options.proposal,
+    proposal_artifacts: savedArtifacts || undefined,
+    write_plan: summarizeAnalyzeProjectWritePlan(options.writePlan),
+  };
+  writeAnalyzeProjectRunStatus(repoRoot, options.auditRunId, 'apply-canceled', {
+    now: options.commandOptions?.now,
+    provider: options.provider,
+    attempts: options.providerAttempts,
+    artifacts: {
+      selected_context: options.selectedContextManifest,
+      raw_provider: analyzeProjectRawProviderArtifactPaths(options.rawProviderArtifacts),
+      repair: options.repairManifest,
+      retry: options.retryManifest,
+      proposal_manifest: savedArtifacts?.manifest || null,
+      proposal_files: savedArtifacts ? listAnalyzeProjectProposalArtifactFiles(savedArtifacts) : [],
+    },
+  });
+  process.stdout.write([
+    translator.t('ai.analyze_project.apply.cancelled'),
+    translator.t('ai.analyze_project.apply.cancelled_writes'),
+    '',
+  ].join('\n'));
+  return cancelReport;
+}
+
 function formatLocalizedActionableError({ failure, impact, fix, nextCommand } = {}, options = {}) {
   const translator = createTranslator(options.language);
   const lines = [`create-quiver: ${String(failure || 'operation failed').trim()}`];
@@ -492,6 +1040,84 @@ function formatLocalizedActionableError({ failure, impact, fix, nextCommand } =
   return lines.join('\n');
 }
 
+function analyzeProjectContractError(message, nextCommand) {
+  const error = new Error(formatError([
+    message,
+    nextCommand ? `Next safe step: ${nextCommand}` : '',
+  ].filter(Boolean).join('\n')));
+  error.code = 'AI_ANALYZE_PROJECT_CONTRACT_UNAVAILABLE';
+  return error;
+}
+
+function canUseInteractiveTerminal(options = {}) {
+  return options.stdinIsTTY === true || (options.stdinIsTTY !== false && Boolean(process.stdin.isTTY));
+}
+
+function assertAnalyzeProjectCommandContract(options = {}) {
+  if (options.review === true && options.applyDocs === true) {
+    throw analyzeProjectContractError(
+      'ai analyze-project --apply-docs cannot be combined with --review.',
+      'Use either `npx create-quiver ai analyze-project --deep --review` or `npx create-quiver ai analyze-project --deep --apply-docs`.',
+    );
+  }
+
+  if (options.dryRun === true && options.applyDocs === true) {
+    throw analyzeProjectContractError(
+      'ai analyze-project --dry-run cannot be combined with --apply-docs.',
+      'Preview with `npx create-quiver ai analyze-project --deep --dry-run`, then rerun without --dry-run.',
+    );
+  }
+
+  if (options.dryRun === true && options.saveProposal === true) {
+    throw analyzeProjectContractError(
+      'ai analyze-project --dry-run cannot be combined with --save-proposal.',
+      'Preview with `npx create-quiver ai analyze-project --deep --dry-run`, then rerun with --save-proposal.',
+    );
+  }
+
+  if (options.applyRun === true && options.dryRun === true) {
+    throw analyzeProjectContractError(
+      'ai analyze-project apply --run cannot be combined with --dry-run.',
+      'Inspect the saved proposal under `.quiver/runs/<run-id>/proposal/`, then rerun without --dry-run.',
+    );
+  }
+
+  if (options.applyRun === true && (options.applyDocs === true || options.saveProposal === true || options.review === true)) {
+    throw analyzeProjectContractError(
+      'ai analyze-project apply --run cannot be combined with --apply-docs, --save-proposal, or --review.',
+      'Use `npx create-quiver ai analyze-project apply --run <run-id>` to apply a saved proposal, or rerun `ai analyze-project --deep` for a fresh proposal.',
+    );
+  }
+
+  if (options.json === true && options.applyDocs === true && options.force !== true) {
+    throw analyzeProjectContractError(
+      'ai analyze-project --json with --apply-docs requires --yes because JSON output cannot include an interactive selector.',
+      'Use `npx create-quiver ai analyze-project --deep --apply-docs --yes --json` for automation.',
+    );
+  }
+
+  if (options.applyRun === true && !String(options.runId || '').trim()) {
+    throw analyzeProjectContractError(
+      'ai analyze-project apply requires --run <run-id>.',
+      'Use `npx create-quiver ai analyze-project apply --run <run-id>`.',
+    );
+  }
+
+  if (options.applyRun === true && String(options.runId || '').trim() === 'latest' && options.force === true) {
+    throw analyzeProjectContractError(
+      'ai analyze-project apply --run latest cannot be combined with --yes.',
+      'Use an explicit run id for automation: `npx create-quiver ai analyze-project apply --run <run-id> --yes`.',
+    );
+  }
+
+  if (options.applyRun === true && String(options.runId || '').trim() === 'latest' && options.json === true) {
+    throw analyzeProjectContractError(
+      'ai analyze-project apply --run latest cannot be combined with --json.',
+      'Use an explicit run id for JSON automation: `npx create-quiver ai analyze-project apply --run <run-id> --json`.',
+    );
+  }
+}
+
 function readTextFile(filePath, repoRoot) {
   if (!filePath) {
     return '';
@@ -609,7 +1235,8 @@ function shouldShowHumanProgress(ux, options = {}) {
   return options.progress !== false
     && options.dryRun !== true
     && options.printPrompt !== true
-    && ux?.mode?.decoration === true;
+    && ux?.mode?.json !== true
+    && (ux?.mode?.decoration === true || options.linearProgress === true);
 }
 
 function plannerProgressTitle(action, runtimeProfile, options = {}) {
@@ -630,10 +1257,32 @@ function writeProgressChecks(ux, enabled, title, checks = []) {
   }
 }
 
-async function runProviderWithProgress({ ux, enabled, message = 'Running agent...', successMessage = 'Agent finished', failureMessage = 'Agent failed', run }) {
+function writeProgressCheck(ux, enabled, check) {
+  if (!enabled || !check) {
+    return;
+  }
+  ux.check(check);
+}
+
+function writeProgressInfo(ux, enabled, message) {
+  if (!enabled || !message) {
+    return;
+  }
+  ux.info(message);
+}
+
+async function runProviderWithProgress({
+  ux,
+  enabled,
+  message = 'Running agent...',
+  successMessage = 'Agent finished',
+  failureMessage = 'Agent failed',
+  failOnProviderResult = true,
+  run,
+}) {
   async function runAndFailOnProviderResult() {
     const result = await run();
-    if (result && result.ok === false) {
+    if (failOnProviderResult && 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;
@@ -1909,6 +2558,33 @@ async function runPrepareContext(repoRoot, options = {}) {
 }
 
 async function runAnalyzeProject(repoRoot, options = {}) {
+  assertAnalyzeProjectCommandContract(options);
+  if (options.applyRun === true) {
+    return applyAnalyzeProjectSavedProposalRun(repoRoot, options);
+  }
+  if (options.applyDocs === true && options.force !== true && !canUseAnalyzeProjectInteractiveSelector(options)) {
+    throw analyzeProjectContractError(
+      'ai analyze-project --apply-docs requires an interactive TTY unless --yes is passed. No provider was run and no files were written.',
+      'Use `npx create-quiver ai analyze-project --deep --apply-docs --yes --provider <provider> --model <model>` for automation, or rerun from an interactive terminal.',
+    );
+  }
+
+  const role = normalizeRole(options.role || DEFAULT_PLAN_ROLE);
+  const runtimeProfile = resolveRuntimeAgentProfile(repoRoot, role, options, DEFAULT_PLAN_PROVIDER);
+  const provider = runtimeProfile.provider;
+  const ux = createCommandUx(options);
+  const showProgress = shouldShowHumanProgress(ux, { ...options, linearProgress: true });
+  const progressTranslator = createTranslator(options.language);
+  const progressTitle = plannerProgressTitle(
+    progressTranslator.t('ai.planner.progress.analyze_project'),
+    runtimeProfile,
+    options,
+  );
+
+  if (showProgress) {
+    ux.heading(progressTitle);
+  }
+
   const report = buildAnalyzeProjectReport(repoRoot, options);
   if (options.dryRun === true) {
     if (options.json === true) {
@@ -1919,13 +2595,10 @@ async function runAnalyzeProject(repoRoot, options = {}) {
     return report;
   }
 
-  const role = normalizeRole(options.role || DEFAULT_PLAN_ROLE);
-  const runtimeProfile = resolveRuntimeAgentProfile(repoRoot, role, options, DEFAULT_PLAN_PROVIDER);
-  const provider = runtimeProfile.provider;
   const timeoutMs = normalizeTimeout(options.timeout);
-  const ux = createCommandUx(options);
-  const showProgress = shouldShowHumanProgress(ux, options);
-  const progressTranslator = createTranslator(options.language);
+  writeProgressCheck(ux, showProgress, progressTranslator.t('ai.planner.progress.reading_base_docs'));
+  writeProgressCheck(ux, showProgress, progressTranslator.t('ai.planner.progress.detecting_structure'));
+  writeProgressCheck(ux, showProgress, progressTranslator.t('ai.planner.progress.selecting_sample'));
   const promptPackage = buildAnalyzeProjectPrompt({
     analysisPlan: report,
     repoRoot,
@@ -1935,17 +2608,8 @@ async function runAnalyzeProject(repoRoot, options = {}) {
   const prompt = promptPackage.prompt;
   const promptLimit = assertProviderPromptWithinLimit(prompt, options.promptLimitOptions || {});
   const privacyPreflight = promptPackage.privacyPreflight;
-
-  writeProgressChecks(
-    ux,
-    showProgress,
-    plannerProgressTitle(progressTranslator.t('ai.planner.progress.analyze_project'), runtimeProfile, options),
-    [
-      progressTranslator.t('ai.planner.progress.reading_base_docs'),
-      progressTranslator.t('ai.planner.progress.detecting_structure'),
-      progressTranslator.t('ai.planner.progress.preparing_prompt'),
-    ],
-  );
+  const auditRunId = options.runId || createAnalyzeProjectAuditRunId(options.now || new Date());
+  writeProgressCheck(ux, showProgress, progressTranslator.t('ai.planner.progress.preparing_prompt'));
 
   if (!privacyPreflight.ok) {
     const error = new Error(formatError('ai analyze-project privacy preflight failed; provider execution was blocked before sending repository content.'));
@@ -1983,45 +2647,215 @@ async function runAnalyzeProject(repoRoot, options = {}) {
     };
   }
 
+  const selectedContextManifest = writeSelectedContextManifest(
+    repoRoot,
+    buildSelectedContextManifest({
+      analysisPlan: report,
+      promptPackage,
+      promptLimit,
+      provider,
+      runId: auditRunId,
+      now: options.now,
+    }),
+    {
+      runId: auditRunId,
+      now: options.now,
+    },
+  );
+
+  const maxRetries = normalizeAnalyzeProjectMaxRetries(options.maxAnalyzeProjectRetries);
+  const providerAttempts = [];
   let result;
-  try {
-    result = await runProviderWithProgress({
-      ux,
-      enabled: showProgress,
-      message: progressTranslator.t('ai.planner.progress.running_agent'),
-      successMessage: progressTranslator.t('ai.planner.progress.agent_finished'),
-      failureMessage: progressTranslator.t('ai.planner.progress.agent_failed'),
-      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,
-        ...runtimeModelExecutionOptions(runtimeProfile, options),
-        enforceModelSelection: false,
-      }),
-    });
-  } catch (error) {
-    throw annotateProviderError(error, 'analyze-project');
-  }
+  let clean;
+  let parsed;
+  let repairManifest = null;
+  let retryManifest = null;
+  let currentPrompt = prompt;
+  const rawProviderArtifacts = [];
 
-  if (!result.ok) {
-    throw annotateProviderError(result.error || new Error('provider run failed'), 'analyze-project');
-  }
+  for (let attemptIndex = 0; attemptIndex <= maxRetries; attemptIndex += 1) {
+    try {
+      result = await runProviderWithProgress({
+        ux,
+        enabled: showProgress,
+        message: attemptIndex === 0
+          ? progressTranslator.t('ai.planner.progress.running_agent')
+          : `Retrying agent (${attemptIndex}/${maxRetries})...`,
+        successMessage: progressTranslator.t('ai.planner.progress.agent_finished'),
+        failureMessage: progressTranslator.t('ai.planner.progress.agent_failed'),
+        failOnProviderResult: false,
+        run: () => (options.runProviderFn || runProvider)(provider, {
+          prompt: currentPrompt,
+          cwd: repoRoot,
+          timeoutMs,
+          dryRun: false,
+          probe: options.probe,
+          spawn: options.spawn,
+          tempRoot: options.tempRoot,
+          tempFileName: options.tempFileName,
+          tempFilePrefix: options.tempFilePrefix,
+          ...runtimeModelExecutionOptions(runtimeProfile, options),
+          enforceModelSelection: false,
+        }),
+      });
+    } catch (error) {
+      throw annotateProviderError(error, 'analyze-project');
+    }
 
-  const clean = extractCleanProviderOutput(result, { prompt, projectRoot: repoRoot });
-  let parsed;
-  try {
-    parsed = parseAnalyzeProjectOutput(clean.cleanOutput, {
-      selectedFiles: report.selected_files,
-      promptFiles: promptPackage.files,
-    });
-  } catch (error) {
-    throw enhanceAnalyzeProjectAnalysisError(error);
+    rawProviderArtifacts.push(writeRawProviderArtifact(repoRoot, auditRunId, `analyze-project-provider-attempt-${attemptIndex + 1}`, result, {
+      now: options.now,
+      metadata: {
+        attempt: attemptIndex + 1,
+        retry: attemptIndex > 0,
+      },
+    }));
+    writeProgressCheck(ux, showProgress, progressTranslator.t('ai.planner.progress.writing_artifacts'));
+    if (!result.ok) {
+      writeProgressInfo(ux, showProgress, progressTranslator.t('ai.planner.progress.agent_failed'));
+      writeAnalyzeProjectRunStatus(repoRoot, auditRunId, 'failed', {
+        now: options.now,
+        provider,
+        attempts: [{
+          attempt: attemptIndex + 1,
+          status: 'provider-failed',
+          retry: attemptIndex > 0,
+        }],
+        artifacts: {
+          selected_context: selectedContextManifest,
+          raw_provider: rawProviderArtifacts.map((artifact) => artifact.path),
+        },
+      });
+      throw annotateProviderError(result.error || new Error('provider run failed'), 'analyze-project');
+    }
+
+    clean = extractCleanProviderOutput(result, { prompt: currentPrompt, projectRoot: repoRoot });
+    try {
+      parsed = parseAnalyzeProjectOutputWithRepair(clean.cleanOutput, {
+        selectedFiles: report.selected_files,
+        promptFiles: promptPackage.files,
+      });
+      writeProgressCheck(ux, showProgress, progressTranslator.t('ai.planner.progress.validating_schema'));
+      if (parsed.repairManifest) {
+        repairManifest = writeAnalyzeProjectRepairManifest(repoRoot, parsed.repairManifest, {
+          runId: auditRunId,
+          now: options.now,
+        });
+        writeProgressCheck(ux, showProgress, progressTranslator.t('ai.planner.progress.repairing_schema'));
+      }
+      providerAttempts.push({
+        attempt: attemptIndex + 1,
+        status: 'valid',
+        retry: attemptIndex > 0,
+        parse_source: parsed.parseSource,
+        repaired: parsed.repaired === true,
+        repair_manifest: repairManifest,
+      });
+      if (providerAttempts.length > 1) {
+        retryManifest = writeAnalyzeProjectRetryManifest(repoRoot, {
+          provider,
+          command: 'ai analyze-project',
+          runId: auditRunId,
+          now: options.now,
+          maxRetries,
+          finalStatus: 'valid',
+          attempts: providerAttempts,
+        });
+      }
+      writeAnalyzeProjectRunStatus(repoRoot, auditRunId, 'completed', {
+        now: options.now,
+        provider,
+        attempts: providerAttempts,
+        artifacts: {
+          selected_context: selectedContextManifest,
+          raw_provider: rawProviderArtifacts.map((artifact) => artifact.path),
+          repair: repairManifest,
+          retry: retryManifest,
+        },
+      });
+      break;
+    } catch (error) {
+      let attemptRepairManifest = null;
+      if (error.repair_manifest) {
+        try {
+          attemptRepairManifest = writeAnalyzeProjectRepairManifest(repoRoot, error.repair_manifest, {
+            runId: auditRunId,
+            now: options.now,
+          });
+        } catch {
+          attemptRepairManifest = null;
+        }
+      }
+      const retryable = isAnalyzeProjectRetryableError(error);
+      providerAttempts.push({
+        attempt: attemptIndex + 1,
+        status: 'invalid',
+        retry: attemptIndex > 0,
+        retryable,
+        issue_count: Array.isArray(error.issues) ? error.issues.length : 0,
+        groups: groupAnalyzeProjectIssues(error.issues, { maxExamplesPerGroup: 2 }),
+        repair_manifest: attemptRepairManifest,
+      });
+
+      if (retryable && attemptIndex < maxRetries) {
+        writeProgressInfo(ux, showProgress, progressTranslator.t('ai.planner.progress.retrying_agent'));
+        currentPrompt = buildAnalyzeProjectRetryPrompt({
+          previousOutput: clean.cleanOutput,
+          issueLines: formatAnalyzeProjectIssues(error.issues, 6),
+          attempt: attemptIndex + 1,
+          maxRetries,
+        });
+        continue;
+      }
+
+      if (providerAttempts.length > 1) {
+        retryManifest = writeAnalyzeProjectRetryManifest(repoRoot, {
+          provider,
+          command: 'ai analyze-project',
+          runId: auditRunId,
+          now: options.now,
+          maxRetries,
+          finalStatus: 'invalid',
+          attempts: providerAttempts,
+        });
+      }
+
+      let validationManifest = null;
+      try {
+        validationManifest = writeAnalyzeProjectValidationManifest(repoRoot, {
+          error,
+          provider,
+          command: 'ai analyze-project',
+          runId: auditRunId,
+          now: options.now,
+          retry: {
+            attempts: providerAttempts.length,
+            max_retries: maxRetries,
+            retryable,
+            exhausted: retryable && attemptIndex >= maxRetries,
+            manifest: retryManifest,
+          },
+        });
+      } catch {
+        validationManifest = null;
+      }
+      writeAnalyzeProjectRunStatus(repoRoot, auditRunId, 'failed', {
+        now: options.now,
+        provider,
+        attempts: providerAttempts,
+        artifacts: {
+          selected_context: selectedContextManifest,
+          raw_provider: rawProviderArtifacts.map((artifact) => artifact.path),
+          repair: attemptRepairManifest,
+          retry: retryManifest,
+          validation: validationManifest,
+        },
+      });
+      throw enhanceAnalyzeProjectAnalysisError(error, {
+        validationManifest,
+        repairManifest: attemptRepairManifest,
+        retryManifest,
+      });
+    }
   }
   const completedReport = {
     ...report,
@@ -2040,82 +2874,101 @@ async function runAnalyzeProject(repoRoot, options = {}) {
       parse_source: parsed.parseSource,
       warnings: parsed.warnings,
       doc_update_paths: parsed.docUpdatePaths,
+      repaired: parsed.repaired === true,
+      repair_manifest: repairManifest,
+      retry_count: Math.max(0, providerAttempts.length - 1),
+      retry_manifest: retryManifest,
     },
     provider_artifact: buildAnalyzeProjectProviderArtifact(result, clean, repoRoot),
+    raw_provider_artifacts: rawProviderArtifacts.map((artifact) => artifact.path),
+    provider_attempts: providerAttempts,
+    run_id: auditRunId,
+    run_status_path: path.join('.quiver', 'runs', auditRunId, 'status.json').split(path.sep).join('/'),
+    selected_context_manifest: selectedContextManifest,
+  };
+  const needsDocProposal = options.applyDocs === true || options.saveProposal === true || options.review === true;
+  const docProposal = needsDocProposal ? buildAnalyzeProjectDocProposal(parsed.analysis) : null;
+  const docWritePlan = docProposal ? buildAnalyzeProjectWritePlan(repoRoot, docProposal) : [];
+  const docActionContext = {
+    auditRunId,
+    commandOptions: options,
+    completedReport,
+    proposal: docProposal,
+    writePlan: docWritePlan,
+    provider,
+    providerAttempts,
+    rawProviderArtifacts,
+    selectedContextManifest,
+    repairManifest,
+    retryManifest,
   };
 
-  if (options.review === true) {
-    const initialProposal = buildAnalyzeProjectDocProposal(parsed.analysis);
-    const reviewed = await reviewAnalyzeProjectDocProposal(repoRoot, initialProposal, options);
-    const writePlan = buildAnalyzeProjectWritePlan(repoRoot, reviewed.proposal);
-    process.stdout.write(formatAnalyzeProjectReviewPlan({
-      writePlan,
-      reviewPath: reviewed.reviewPath,
-    }));
-    await confirmAnalyzeProjectWrites(writePlan, options);
-    const lifecycleRun = ensureAiRun(repoRoot, {
-      command: 'ai analyze-project',
-      input: reviewed.reviewPath,
-      runId: options.runId,
-      phase: 'created',
-    });
-    const snapshot = createAnalyzeProjectSnapshot(repoRoot, lifecycleRun, writePlan, {
-      providerArtifact: completedReport.provider_artifact,
-      proposal: reviewed.proposal,
-      now: options.now || new Date(),
+  if (options.applyDocs === true && options.force === true) {
+    const applyReport = applyAnalyzeProjectDocProposalReport(repoRoot, {
+      ...docActionContext,
+      allowDirtyDocs: options.allowDirtyDocs === true,
     });
-    const writtenDocs = writeAnalyzeProjectDocs(writePlan);
-    let writeReport = {
-      ...completedReport,
-      review: true,
-      review_path: reviewed.reviewPath,
-      doc_proposal: reviewed.proposal,
-      write_plan: writePlan.map((item) => ({
-        path: item.path,
-        action: item.action,
-        dirty: item.dirty,
-        before_sha256: item.before_sha256,
-        after_sha256: item.after_sha256,
-        reason: item.reason,
-      })),
-      snapshot,
-      written_docs: writtenDocs,
-      run_id: lifecycleRun.run_id,
-    };
-    const postWriteValidation = validateAnalyzeProjectPostWrite(repoRoot, writeReport, {
-      strict: options.strict === true,
+    return emitAnalyzeProjectApplyReport(applyReport, options);
+  }
+
+  if (options.applyDocs === true) {
+    return runAnalyzeProjectInteractiveApplySelector({
+      report: completedReport,
+      proposal: docProposal,
+      writePlan: docWritePlan,
+      options,
+      actions: {
+        apply: ({ allowDirtyDocs, interactiveAction }) => {
+          const applyReport = applyAnalyzeProjectDocProposalReport(repoRoot, {
+            ...docActionContext,
+            allowDirtyDocs,
+            interactiveAction,
+          });
+          return emitAnalyzeProjectApplyReport(applyReport, options);
+        },
+        save: ({ interactiveAction, silent, savedReport } = {}) => {
+          const saveReport = savedReport || saveAnalyzeProjectDocProposalReport(repoRoot, {
+            ...docActionContext,
+            interactiveAction,
+          });
+          if (silent !== true) {
+            process.stdout.write(formatAnalyzeProjectSavedProposalReport(saveReport));
+          }
+          return saveReport;
+        },
+        edit: ({ interactiveAction } = {}) => reviewAndWriteAnalyzeProjectDocs(repoRoot, {
+          commandOptions: options,
+          completedReport,
+          initialProposal: docProposal,
+          interactiveAction,
+        }),
+        cancel: ({ interactiveAction, savedReport } = {}) => cancelAnalyzeProjectInteractiveApplyReport(repoRoot, {
+          ...docActionContext,
+          interactiveAction,
+          savedReport,
+        }),
+      },
     });
-    writeReport = {
-      ...writeReport,
-      post_write_validation: postWriteValidation,
-    };
+  }
+
+  if (options.saveProposal === true) {
+    const saveReport = saveAnalyzeProjectDocProposalReport(repoRoot, docActionContext);
 
     if (options.json === true) {
-      process.stdout.write(`${JSON.stringify(writeReport, null, 2)}\n`);
-      if (!postWriteValidation.ok) {
-        const error = new Error(formatError('ai analyze-project post-write validation failed.'));
-        error.code = 'AI_ANALYZE_PROJECT_POST_WRITE_VALIDATION_FAILED';
-        error.validation = postWriteValidation;
-        throw error;
-      }
-      return writeReport;
+      process.stdout.write(`${JSON.stringify(saveReport, null, 2)}\n`);
+      return saveReport;
     }
 
-    process.stdout.write(formatAnalyzeProjectReviewPlan({
-      writePlan,
-      reviewPath: reviewed.reviewPath,
-      snapshot,
-      writtenDocs,
-      validation: postWriteValidation,
-      completed: true,
-    }));
-    if (!postWriteValidation.ok) {
-      const error = new Error(formatError('ai analyze-project post-write validation failed.'));
-      error.code = 'AI_ANALYZE_PROJECT_POST_WRITE_VALIDATION_FAILED';
-      error.validation = postWriteValidation;
-      throw error;
-    }
-    return writeReport;
+    process.stdout.write(formatAnalyzeProjectSavedProposalReport(saveReport));
+    return saveReport;
+  }
+
+  if (options.review === true) {
+    return reviewAndWriteAnalyzeProjectDocs(repoRoot, {
+      commandOptions: options,
+      completedReport,
+      initialProposal: docProposal,
+    });
   }
 
   if (options.json === true) {