create-quiver 0.17.2 → 0.17.3

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

@@ -36,6 +36,18 @@ 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,
@@ -501,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 [];
@@ -553,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()}`];
@@ -570,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 '';
@@ -2010,6 +2558,17 @@ 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;
@@ -2323,82 +2882,93 @@ async function runAnalyzeProject(repoRoot, options = {}) {
     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) {