create-quiver 0.13.0 → 0.14.1

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

@@ -1,4 +1,5 @@
 const fs = require('node:fs');
+const os = require('node:os');
 const path = require('node:path');
 
 const { redactSecrets } = require('../lib/evidence');
@@ -10,6 +11,9 @@ const {
   writeRawProviderArtifact,
 } = require('../lib/ai/artifacts');
 const { buildContextPackMetadata, normalizeRole } = require('../lib/ai/context-packs');
+const { parseContextProposalOutput } = require('../lib/ai/context-proposal');
+const { openEditor } = require('../lib/cli/editor');
+const { createUx } = require('../lib/cli/ux');
 const { runExecuteSlice, runPromptSlice } = require('../lib/ai/executor');
 const { runExecutePlan } = require('../lib/ai/execution-plan');
 const { buildPrCreatePlan, formatPreflightReport, formatPrCreateReport, preflightGitHubPr, runGhPrCreate } = require('../lib/ai/github');
@@ -26,18 +30,25 @@ const {
   PLAN_REVIEW_PROMPT_SOURCE,
   buildPlanReviewPrompt,
   readPlanReview,
+  reviewBlocksApproval,
   resolveReviewedTechnicalPlanInput,
   resolveTechnicalPlanReviewInput,
   savePlanReview,
   summarizePlanReview,
 } = require('../lib/ai/plan-review');
-const { buildSpecGenerationManifest, describeSpecGeneration, generateSpecArtifacts } = require('../lib/ai/spec-generator');
+const {
+  buildSpecGenerationManifest,
+  describeSpecGeneration,
+  generateSpecArtifacts,
+  validateTechnicalPlanSpecContract,
+} = require('../lib/ai/spec-generator');
 const { buildProviderInvocation, runProvider } = require('../lib/ai/providers');
 const {
   createAiRun,
   ensureAiRun,
   formatAiRunResume,
   formatAiRunStatus,
+  listAiRuns,
   recordAiRunApproval,
   resolveAiRun,
   updateAiRunPhase,
@@ -53,12 +64,15 @@ const {
 const {
   PLANNER_APPROVAL_PHASES,
   approvePlannerPhase,
+  findDraftVersion,
+  latestDraftVersion,
   readPhaseApproval,
   resolveApprovedPlannerInput,
   savePlannerDraft,
   summarizePlannerApproval,
 } = require('../lib/approvals');
 const { assertPlannerPhaseReady, getPlannerPhaseDetails, normalizePlannerPhase, PlannerPhaseError } = require('../lib/ai/phase-gates');
+const { collectActiveSliceState, resolveProjectState } = require('../lib/project-state-resolver');
 
 const DEFAULT_ONBOARD_PROVIDER = 'codex';
 const DEFAULT_ONBOARD_ROLE = 'planner';
@@ -133,6 +147,13 @@ function buildPlanContext({ role, context, phase, inputText, inputPath, repoRoot
       : 'Task: produce a technical plan only. Do not create files or modify product code.',
   ];
 
+  if (phaseDetails.phase === 'technical-plan') {
+    sections.push(
+      'Required output contract: include a fenced json block with `{ "spec": { "slices": [...] } }` so Quiver can create specs after review and approval.',
+      'Each `spec.slices[]` item must include at least `slice_id`, `title`, `objective`, and `files`.',
+    );
+  }
+
   if (relativeInputPath) {
     sections.push(`Input file: ${relativeInputPath}`);
   }
@@ -296,6 +317,255 @@ function formatContextPreparationReport({ dryRun, plan, writePlan, writtenDocs,
   return `${lines.join('\n')}\n`;
 }
 
+function truncatePromptSection(text, maxChars = 1200) {
+  const value = String(text || '').trimEnd();
+  if (value.length <= maxChars) {
+    return value;
+  }
+  return `${value.slice(0, maxChars).trimEnd()}\n[... truncated ${value.length - maxChars} chars ...]`;
+}
+
+function buildPrepareContextPlannerPrompt({ pack, draftPack }) {
+  const plan = draftPack.plan;
+  const allowedPaths = draftPack.docs.map((doc) => doc.path);
+  const sections = [
+    pack.prompt,
+    'Task: planner-assisted Quiver context preparation.',
+    'Goal: improve the docs-only onboarding context for future AI work while preserving WDD + SDD safety.',
+    'Rules:',
+    '- Return only valid JSON. Do not include Markdown outside the JSON object.',
+    '- Do not modify product code, UI code, tests, migrations, dependencies, lockfiles, build files, runtime config, generated files, or paths outside the repo.',
+    '- Only propose writes to the allowed docs paths listed below.',
+    '- If information is ambiguous, document assumptions and risks instead of inventing facts.',
+    '- Keep human-authored content safe; Quiver will merge proposals through managed context blocks.',
+    '',
+    'Allowed docs-only output paths:',
+    ...allowedPaths.map((item) => `- ${item}`),
+    '',
+    'Project context:',
+    `- Project: ${plan.projectName}`,
+    `- Project slug: ${plan.projectSlug}`,
+    `- Package manager: ${plan.facts.packageManager}`,
+    `- Stack summary: ${plan.facts.stackSummary}`,
+    '',
+    'Files considered by deterministic prepare-context:',
+    ...plan.filesConsidered.map((item) => `- ${item.path}: ${item.present ? 'present' : 'absent'}${item.reason ? ` (${item.reason})` : ''}`),
+    '',
+    'Known assumptions:',
+    ...formatPathList(plan.assumptions),
+    '',
+    'Known risks:',
+    ...formatPathList(plan.risks),
+    '',
+    'Known contradictions:',
+    ...formatPathList(plan.contradictions),
+    '',
+    'Deterministic candidate docs:',
+    ...draftPack.docs.flatMap((doc) => [
+      `### ${doc.path}`,
+      truncatePromptSection(doc.content),
+    ]),
+    '',
+    'Required JSON output shape:',
+    JSON.stringify({
+      schema_version: 1,
+      kind: 'quiver-context-proposal',
+      summary: 'short summary',
+      assumptions: ['assumption to confirm'],
+      risks: ['risk to track'],
+      docs: [
+        {
+          path: 'docs/AI_CONTEXT.md',
+          action: 'update',
+          reason: 'why this doc should change',
+          content: '# AI Context\\n\\nFull proposed content or managed section content.\\n',
+          assumptions: [],
+          risks: [],
+        },
+      ],
+      omitted_paths: ['paths intentionally omitted'],
+      next_steps: ['safe next step'],
+    }, null, 2),
+  ];
+
+  return {
+    allowedPaths,
+    plan,
+    prompt: sections.join('\n'),
+    promptSource: 'quiver prepare-context planner proposal contract',
+  };
+}
+
+function formatPrepareContextPlannerDryRunReport({ provider, role, context, invocation, promptInfo, review, interactive }) {
+  const plan = promptInfo.plan;
+  const lines = [
+    'AI prepare-context planner dry-run',
+    'Mode: dry-run',
+    'Planner: enabled',
+    `Provider: ${provider}`,
+    `Role: ${role}`,
+    `Context pack: ${context}`,
+    `Command: ${invocation.command} ${invocation.args.join(' ')}`.trim(),
+    `Prompt bytes: ${invocation.promptLength}`,
+    `Prompt source: ${promptInfo.promptSource}`,
+    `Review requested: ${review ? 'yes' : 'no'}`,
+    `Interactive requested: ${interactive ? 'yes' : 'no'}`,
+    'Provider execution: skipped',
+    'Writes: none',
+    'Product code: untouched',
+    `Candidate docs: ${promptInfo.allowedPaths.join(', ')}`,
+    'Files considered:',
+    ...plan.filesConsidered.map((item) => `- ${item.path}: ${item.present ? 'present' : 'absent'}`),
+    'Allowed docs-only paths:',
+    ...promptInfo.allowedPaths.map((item) => `- ${item}`),
+    'Next safe commands:',
+    '- npx create-quiver ai prepare-context --with-planner --print-prompt',
+    '- npx create-quiver ai prepare-context --with-planner --dry-run --review',
+    '- npx create-quiver ai prepare-context --with-planner',
+  ];
+
+  return `${lines.join('\n')}\n`;
+}
+
+function serializeProposalForReview(proposal) {
+  return {
+    schema_version: proposal.schemaVersion,
+    kind: proposal.kind,
+    summary: proposal.summary,
+    assumptions: proposal.assumptions,
+    risks: proposal.risks,
+    docs: proposal.docs.map((doc) => ({
+      path: doc.path,
+      action: doc.action,
+      reason: doc.reason,
+      content: doc.content,
+      assumptions: doc.assumptions,
+      risks: doc.risks,
+    })),
+    omitted_paths: proposal.omittedPaths,
+    next_steps: proposal.nextSteps,
+  };
+}
+
+function createProposalReviewFile(proposal, options = {}) {
+  const reviewDir = options.reviewDir || fs.mkdtempSync(path.join(os.tmpdir(), 'quiver-context-review-'));
+  const reviewPath = path.join(reviewDir, 'context-proposal.json');
+  fs.mkdirSync(reviewDir, { recursive: true });
+  fs.writeFileSync(reviewPath, `${JSON.stringify(serializeProposalForReview(proposal), null, 2)}\n`);
+  return reviewPath;
+}
+
+function makeReviewError(message, reviewPath, cause) {
+  const error = new Error(formatError(`${message}\nReview artifact: ${reviewPath}\nNext safe step: edit the artifact into valid proposal JSON or rerun with --with-planner --dry-run.`));
+  error.code = cause?.code || 'AI_CONTEXT_REVIEW_FAILED';
+  error.cause = cause;
+  error.reviewPath = reviewPath;
+  return error;
+}
+
+function createReviewTextFile(contents, options = {}) {
+  const reviewDir = options.reviewDir || fs.mkdtempSync(path.join(os.tmpdir(), 'quiver-review-'));
+  const filename = options.reviewFileName || 'review.md';
+  const reviewPath = path.join(reviewDir, filename);
+  fs.mkdirSync(reviewDir, { recursive: true });
+  fs.writeFileSync(reviewPath, String(contents || ''));
+  return reviewPath;
+}
+
+async function reviewTextWithEditor(repoRoot, contents, options = {}) {
+  const reviewPath = createReviewTextFile(contents, options);
+  const hasEditorRunner = typeof options.openEditorFn === 'function';
+  const canOpenEditor = hasEditorRunner || options.stdinIsTTY === true || (options.stdinIsTTY !== false && Boolean(process.stdin.isTTY));
+
+  if (!canOpenEditor) {
+    throw makeReviewError(`${options.reviewLabel || 'review'} requires an interactive terminal or an injected editor runner.`, reviewPath);
+  }
+
+  const editorResult = hasEditorRunner
+    ? options.openEditorFn(reviewPath, { cwd: repoRoot, env: options.env || process.env })
+    : openEditor(reviewPath, { cwd: repoRoot, env: options.env || process.env });
+
+  if (!editorResult || editorResult.ok !== true) {
+    throw makeReviewError(editorResult?.reason || `${options.reviewLabel || 'review'} was canceled.`, reviewPath);
+  }
+
+  return {
+    reviewPath,
+    text: fs.readFileSync(reviewPath, 'utf8'),
+  };
+}
+
+async function confirmInteractiveAction(message, options = {}) {
+  if (options.interactive !== true) {
+    return;
+  }
+
+  const ux = options.ux || createUx({
+    interactive: true,
+    promptConfirm: options.promptConfirm,
+    stdinIsTTY: options.stdinIsTTY,
+    stdoutIsTTY: options.stdoutIsTTY,
+    stderrIsTTY: options.stderrIsTTY,
+    write: options.write,
+  });
+  const confirmed = await ux.promptConfirm(message, {
+    initialValue: false,
+  });
+
+  if (!confirmed) {
+    const error = new Error(formatError('interactive approval declined. No files were written.'));
+    error.code = 'AI_INTERACTIVE_APPROVAL_DECLINED';
+    throw error;
+  }
+}
+
+async function reviewPlannerContextProposal(repoRoot, proposal, options = {}) {
+  const reviewPath = createProposalReviewFile(proposal, options);
+  const hasEditorRunner = typeof options.openEditorFn === 'function';
+  const canOpenEditor = hasEditorRunner || options.stdinIsTTY === true || (options.stdinIsTTY !== false && Boolean(process.stdin.isTTY));
+
+  if (!canOpenEditor) {
+    throw makeReviewError('ai prepare-context review requires an interactive terminal or an injected editor runner.', reviewPath);
+  }
+
+  const editorResult = hasEditorRunner
+    ? options.openEditorFn(reviewPath, { cwd: repoRoot, env: options.env || process.env })
+    : openEditor(reviewPath, { cwd: repoRoot, env: options.env || process.env });
+
+  if (!editorResult || editorResult.ok !== true) {
+    throw makeReviewError(editorResult?.reason || 'ai prepare-context review was canceled before applying docs.', reviewPath);
+  }
+
+  try {
+    return {
+      proposal: parseContextProposalOutput(fs.readFileSync(reviewPath, 'utf8')),
+      reviewPath,
+    };
+  } catch (error) {
+    throw makeReviewError('edited planner proposal is invalid after review.', reviewPath, error);
+  }
+}
+
+async function confirmPlannerContextWrites(writePlan, options = {}) {
+  const changed = writePlan.filter((item) => item.action !== 'skip').length;
+  await confirmInteractiveAction(`Apply ${changed} docs-only context update${changed === 1 ? '' : 's'}?`, options);
+}
+
+function buildPlannerContextWritePlan(repoRoot, proposal) {
+  const reasonByPath = new Map(proposal.docs.map((doc) => [doc.path, doc.reason]));
+  const draftDocs = proposal.docs
+    .filter((doc) => doc.action !== 'skip')
+    .map((doc) => ({
+      path: doc.path,
+      content: doc.content,
+    }));
+
+  return buildContextWritePlan(repoRoot, draftDocs).map((item) => ({
+    ...item,
+    reason: item.action === 'skip' ? item.reason : reasonByPath.get(item.path) || item.reason,
+  }));
+}
+
 function writeProviderOutput(result) {
   if (result.stdout) {
     process.stdout.write(redactSecrets(result.stdout));
@@ -305,6 +575,14 @@ function writeProviderOutput(result) {
   }
 }
 
+function writeCleanProviderOutput(clean) {
+  const output = String(clean?.cleanOutput || '');
+  if (!output) {
+    return;
+  }
+  process.stdout.write(output.endsWith('\n') ? output : `${output}\n`);
+}
+
 function normalizeText(value) {
   return String(value || '').replace(/\r\n/g, '\n');
 }
@@ -548,10 +826,262 @@ function formatApprovalDryRunResult({ phase, input, version }) {
   return `${lines.join('\n')}\n`;
 }
 
+function stripCreateQuiverPrefix(message) {
+  return String(message || '').replace(/^create-quiver:\s*/, '');
+}
+
+function readCurrentDraftForApproval(repoRoot, phase, version) {
+  const approval = readPhaseApproval(repoRoot, phase);
+  const selectedDraft = findDraftVersion(approval.meta, version);
+  if (!selectedDraft) {
+    throw new Error(formatError(`missing ${phase} draft version ${version}`));
+  }
+  const latestVersion = latestDraftVersion(approval.meta);
+  if (latestVersion && Number(selectedDraft.version) !== latestVersion) {
+    throw new Error(formatError(`${phase} draft version ${version} is not current; latest draft version is ${latestVersion}. Approve the latest version or revise again.`));
+  }
+  const draftPath = path.resolve(repoRoot, selectedDraft.path);
+  if (!fs.existsSync(draftPath)) {
+    throw new Error(formatError(`missing ${phase} draft artifact: ${selectedDraft.path}`));
+  }
+  return {
+    approval,
+    contents: fs.readFileSync(draftPath, 'utf8'),
+    draft: selectedDraft,
+    path: selectedDraft.path,
+  };
+}
+
+function assertTechnicalPlanDraftHasSpecContract(repoRoot, version) {
+  const draft = readCurrentDraftForApproval(repoRoot, 'technical-plan', version);
+  try {
+    validateTechnicalPlanSpecContract(repoRoot, {
+      inputPath: draft.path,
+      inputText: draft.contents,
+    });
+  } catch (error) {
+    throw new Error(formatError([
+      `technical-plan draft v${version} cannot be approved because it cannot create specs.`,
+      stripCreateQuiverPrefix(error.message || error),
+      'Required contract: include a structured JSON block with `spec.slices[]` before approval.',
+      'Next safe command: npx create-quiver ai revise --phase technical-plan --input <feedback.md> --dry-run',
+    ].join('\n')));
+  }
+  return draft;
+}
+
+function resolveApprovedTechnicalPlanForRepair(repoRoot, explicitInput = '') {
+  const approval = readPhaseApproval(repoRoot, 'technical-plan');
+  if (!approval.approved?.path) {
+    throw new Error(formatError('ai repair-plan requires an approved technical-plan artifact. Run `npx create-quiver ai approvals` to inspect planner state.'));
+  }
+
+  const approvedPath = approval.approved.path;
+  if (explicitInput) {
+    const explicit = path.resolve(repoRoot, explicitInput);
+    const approved = path.resolve(repoRoot, approvedPath);
+    if (explicit !== approved) {
+      throw new Error(formatError(`ai repair-plan input must match the approved technical-plan artifact: ${approvedPath}`));
+    }
+  }
+
+  const contents = readTextFile(approvedPath, repoRoot);
+  try {
+    validateTechnicalPlanSpecContract(repoRoot, {
+      inputPath: approvedPath,
+      inputText: contents,
+    });
+  } catch (error) {
+    return {
+      approval,
+      contents,
+      path: approvedPath,
+      validationError: stripCreateQuiverPrefix(error.message || error),
+    };
+  }
+
+  throw new Error(formatError('approved technical-plan already includes a valid structured `spec.slices[]` contract. No repair draft is needed.'));
+}
+
+function buildRepairPlanContext({ context, inputText, inputPath, repoRoot, role, validationError }) {
+  const pack = buildContextPackMetadata({
+    role,
+    packName: context,
+    repoRoot,
+  });
+  const prompt = [
+    pack.prompt,
+    'Phase: technical-plan',
+    'Task: repair the approved technical plan into a new draft only. Do not approve it, create specs, modify product code, or expand scope.',
+    'Preserve the approved intent, scope, risks, and decisions.',
+    'Add the required Quiver structured JSON contract in a fenced json block.',
+    'The JSON must include `{ "spec": { "slug": "...", "title": "...", "objective": "...", "slices": [...] } }`.',
+    'Each item in `spec.slices[]` must include at least `slice_id`, `title`, `objective`, and `files`.',
+    `Validation failure to repair: ${validationError}`,
+    `Approved technical-plan artifact: ${inputPath}`,
+    'Approved technical-plan contents:',
+    inputText.trimEnd(),
+  ].join('\n\n');
+
+  return {
+    pack,
+    prompt,
+  };
+}
+
+function formatRepairPlanResult(result, repoRoot) {
+  const relativePath = path.relative(repoRoot, result.filePath).split(path.sep).join('/');
+  return [
+    'AI technical-plan repair draft saved',
+    `Draft: ${relativePath}`,
+    `Version: v${result.version}`,
+    `Source approved artifact: ${result.sourcePath}`,
+    'Original approved artifact: preserved',
+    'Next safe commands:',
+    '- npx create-quiver ai review-plan --dry-run',
+    '- npx create-quiver ai review-plan',
+    `- npx create-quiver ai approve --phase technical-plan --version ${result.version}`,
+  ].join('\n').concat('\n');
+}
+
+function formatActiveSliceReconciliationReport(report, options = {}) {
+  const lines = [
+    'AI active-slice reconciliation',
+    `Mode: ${options.dryRun ? 'dry-run' : 'read-only'}`,
+    `Decision: ${report.reconciliation.decision}`,
+    `Reason: ${report.reconciliation.reason}`,
+    '',
+    'Supported sources:',
+  ];
+
+  for (const source of report.supported_sources) {
+    lines.push(`- ${source.path}: ${source.exists ? 'exists' : 'missing'}`);
+  }
+
+  lines.push('', 'Detected sources:');
+  if (report.sources.length === 0) {
+    lines.push('- none');
+  } else {
+    for (const source of report.sources) {
+      const ref = source.ref || '(unresolved)';
+      const status = source.status ? ` status=${source.status}` : '';
+      const issue = source.issue ? ` issue=${source.issue}` : '';
+      lines.push(`- ${source.source_id}: ${ref}${status}${issue}`);
+    }
+  }
+
+  lines.push('', 'Planned changes:');
+  if (report.reconciliation.planned_changes.length === 0) {
+    lines.push('- none');
+  } else {
+    for (const change of report.reconciliation.planned_changes) {
+      lines.push(`- ${change}`);
+    }
+  }
+
+  lines.push('', 'Risks:');
+  if (report.reconciliation.risks.length === 0) {
+    lines.push('- none');
+  } else {
+    for (const risk of report.reconciliation.risks) {
+      lines.push(`- ${risk}`);
+    }
+  }
+
+  lines.push('', options.dryRun ? 'No files were changed.' : 'This command is read-only; use start-slice or cleanup-slice for intentional writes.');
+  return `${lines.join('\n')}\n`;
+}
+
+function readRunApprovals(repoRoot, run) {
+  if (!run?.approvals_path) {
+    return [];
+  }
+  const filePath = path.resolve(repoRoot, run.approvals_path);
+  if (!fs.existsSync(filePath)) {
+    return [];
+  }
+  try {
+    const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    return Array.isArray(parsed.approvals) ? parsed.approvals : [];
+  } catch {
+    return [];
+  }
+}
+
+function collectRunApprovalRows(repoRoot) {
+  const activeRun = resolveAiRun(repoRoot, '');
+  return listAiRuns(repoRoot)
+    .flatMap((run) => readRunApprovals(repoRoot, run).map((approval) => ({
+      run,
+      approval,
+      relation: activeRun && run.run_id === activeRun.run_id
+        ? 'active'
+        : run.status === 'closed'
+          ? 'historical'
+          : 'other-open',
+    })));
+}
+
+function approvalArtifactForRelation(report) {
+  return report?.approved?.path || report?.draft?.path || '';
+}
+
+function classifyGlobalApprovalRelation(report, runApprovalRows) {
+  const artifact = approvalArtifactForRelation(report);
+  if (!artifact || report.status === 'missing') {
+    return 'none';
+  }
+  const matches = runApprovalRows.filter((row) => row.approval?.artifact === artifact);
+  if (matches.some((row) => row.relation === 'active')) {
+    return 'active';
+  }
+  if (matches.length > 0) {
+    return 'historical';
+  }
+  return 'orphaned';
+}
+
+function formatRunScopedApprovals(repoRoot, runApprovalRows) {
+  const runs = listAiRuns(repoRoot);
+  const activeRun = resolveAiRun(repoRoot, '');
+  const lines = [
+    'Run-scoped approvals',
+    `Active run: ${activeRun ? activeRun.run_id : '(none)'}`,
+  ];
+
+  if (runs.length === 0) {
+    lines.push('- no AI runs found');
+    return `${lines.join('\n')}\n`;
+  }
+
+  for (const run of runs.slice().reverse()) {
+    const relation = activeRun && run.run_id === activeRun.run_id
+      ? 'active'
+      : run.status === 'closed'
+        ? 'historical'
+        : 'other-open';
+    const approvals = runApprovalRows.filter((row) => row.run.run_id === run.run_id);
+    lines.push(`Run: ${run.run_id} (${relation}, phase: ${run.phase}, status: ${run.status})`);
+    if (approvals.length === 0) {
+      lines.push('- no run-scoped approvals');
+      continue;
+    }
+    for (const row of approvals) {
+      const version = row.approval.version ? ` v${row.approval.version}` : '';
+      lines.push(`- ${row.approval.phase || 'unknown'}${version}: ${row.approval.artifact || '(missing artifact)'}`);
+    }
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
 function formatApprovalStatusReport(repoRoot) {
-  const sections = ['AI approvals status'];
+  const runApprovalRows = collectRunApprovalRows(repoRoot);
+  const sections = ['AI approvals status', formatRunScopedApprovals(repoRoot, runApprovalRows).trimEnd(), 'Global planner approvals'];
   for (const phase of PLANNER_APPROVAL_PHASES) {
-    sections.push(summarizePlannerApproval(repoRoot, phase).trimEnd());
+    const summary = summarizePlannerApproval(repoRoot, phase).trimEnd();
+    const relation = classifyGlobalApprovalRelation(readPhaseApproval(repoRoot, phase), runApprovalRows);
+    sections.push(`${summary}\nRun relation: ${relation}`);
   }
   sections.push(summarizePlanReview(repoRoot).trimEnd());
   return `${sections.join('\n\n')}\n`;
@@ -640,12 +1170,14 @@ async function runOnboard(repoRoot, options = {}) {
     throw annotateProviderError(error, 'onboard');
   }
 
-  writeProviderOutput(result);
-
   if (!result.ok) {
+    writeProviderOutput(result);
     throw annotateProviderError(result.error || new Error('provider run failed'), 'onboard');
   }
 
+  const clean = extractCleanProviderOutput(result, { prompt, projectRoot: repoRoot });
+  writeCleanProviderOutput(clean);
+
   return {
     task: 'onboard',
     provider,
@@ -658,6 +1190,10 @@ async function runOnboard(repoRoot, options = {}) {
 }
 
 async function runPrepareContext(repoRoot, options = {}) {
+  if (options.withPlanner === true) {
+    return runPrepareContextWithPlanner(repoRoot, options);
+  }
+
   const draftPack = buildContextPreparationDrafts(repoRoot);
   const writePlan = buildContextWritePlan(repoRoot, draftPack.docs);
   const report = {
@@ -719,6 +1255,152 @@ async function runPrepareContext(repoRoot, options = {}) {
   };
 }
 
+async function runPrepareContextWithPlanner(repoRoot, options = {}) {
+  const role = normalizeRole(options.role || DEFAULT_PLAN_ROLE);
+  const provider = resolveProviderForProfile(repoRoot, role, options.provider, options.providerExplicit, DEFAULT_PLAN_PROVIDER);
+  const context = options.context || DEFAULT_PLAN_CONTEXT;
+  const timeoutMs = normalizeTimeout(options.timeout);
+  const draftPack = buildContextPreparationDrafts(repoRoot);
+  const pack = buildContextPackMetadata({
+    role,
+    packName: context,
+    repoRoot,
+  });
+  const promptInfo = buildPrepareContextPlannerPrompt({ pack, draftPack });
+  const prompt = promptInfo.prompt;
+  assertProviderPromptWithinLimit(prompt, options.promptLimitOptions || {});
+  let invocation;
+
+  try {
+    invocation = buildProviderInvocation(provider, {
+      prompt,
+      cwd: repoRoot,
+      timeoutMs,
+    });
+  } catch (error) {
+    throw annotateProviderError(error, 'prepare-context');
+  }
+
+  if (options.dryRun) {
+    const report = {
+      task: 'prepare-context',
+      mode: 'planner',
+      dryRun: true,
+      provider,
+      role,
+      contextPack: context,
+      invocation,
+      candidateDocs: promptInfo.allowedPaths,
+      plan: draftPack.plan,
+    };
+    process.stdout.write(formatPrepareContextPlannerDryRunReport({
+      provider,
+      role,
+      context,
+      invocation,
+      promptInfo,
+      review: options.review === true,
+      interactive: options.interactive === true,
+    }));
+    return report;
+  }
+
+  if (options.printPrompt) {
+    const report = {
+      task: 'prepare-context',
+      provider,
+      role,
+      contextPack: context,
+      invocation,
+      prompt,
+      promptSource: promptInfo.promptSource,
+    };
+    process.stdout.write(formatPromptOnlyReport(report));
+    return report;
+  }
+
+  let result;
+  try {
+    result = await (options.runProviderFn || runProvider)(provider, {
+      prompt,
+      cwd: repoRoot,
+      timeoutMs,
+      dryRun: false,
+      probe: options.probe,
+      spawn: options.spawn,
+      tempRoot: options.tempRoot,
+      tempFileName: options.tempFileName,
+      tempFilePrefix: options.tempFilePrefix,
+    });
+  } catch (error) {
+    throw annotateProviderError(error, 'prepare-context');
+  }
+
+  if (!result.ok) {
+    writeProviderOutput(result);
+    throw annotateProviderError(result.error || new Error('provider run failed'), 'prepare-context');
+  }
+
+  const clean = extractCleanProviderOutput(result, { prompt, projectRoot: repoRoot });
+  let proposal = parseContextProposalOutput(clean.cleanOutput);
+  let reviewPath = '';
+
+  if (options.review === true) {
+    const reviewed = await reviewPlannerContextProposal(repoRoot, proposal, options);
+    proposal = reviewed.proposal;
+    reviewPath = reviewed.reviewPath;
+  }
+
+  const writePlan = buildPlannerContextWritePlan(repoRoot, proposal);
+  await confirmPlannerContextWrites(writePlan, options);
+
+  const lifecycleRun = ensureAiRun(repoRoot, {
+    command: 'ai prepare-context --with-planner',
+    input: options.input || '',
+    runId: options.runId,
+    phase: 'created',
+  });
+  const snapshot = createContextSnapshots(repoRoot, lifecycleRun, writePlan, options.now || new Date());
+  const plannedDocs = writePlan.filter((item) => item.action !== 'skip').map((item) => item.path);
+
+  process.stdout.write(formatContextPreparationReport({
+    dryRun: false,
+    plan: draftPack.plan,
+    writePlan,
+    writtenDocs: plannedDocs,
+    snapshot,
+  }));
+
+  const writtenDocs = writeDraftDocs(writePlan);
+  updateAiRunPhase(repoRoot, lifecycleRun.run_id, 'onboarding-ready', {
+    artifact: snapshot.manifestPath,
+    command: 'ai prepare-context --with-planner',
+  });
+  process.stdout.write(formatContextPreparationReport({
+    dryRun: false,
+    plan: draftPack.plan,
+    writePlan,
+    writtenDocs,
+    snapshot,
+    completed: true,
+  }));
+
+  return {
+    task: 'prepare-context',
+    mode: 'planner',
+    dryRun: false,
+    provider,
+    role,
+    contextPack: context,
+    invocation,
+    proposal,
+    reviewPath,
+    runId: lifecycleRun.run_id,
+    snapshot,
+    writtenDocs,
+  };
+}
+
 async function runPlan(repoRoot, options = {}) {
   const phase = normalizePlannerPhase(options.phase || DEFAULT_PLAN_PHASE);
   const role = normalizeRole(options.role || DEFAULT_PLAN_ROLE);
@@ -839,6 +1521,15 @@ async function runPlan(repoRoot, options = {}) {
       invocation,
     };
     process.stdout.write(formatDryRunReport(report));
+    if (options.withPlanner === true) {
+      process.stdout.write('Planner mode: already active for ai plan; --with-planner is accepted for UX consistency.\n');
+    }
+    if (options.review === true) {
+      process.stdout.write('Review requested: provider output will be opened for review before saving the draft in live mode.\n');
+    }
+    if (options.interactive === true) {
+      process.stdout.write('Interactive requested: live mode will ask before saving the draft.\n');
+    }
     return report;
   }
 
@@ -873,18 +1564,32 @@ async function runPlan(repoRoot, options = {}) {
     throw annotateProviderError(error, 'plan', phase);
   }
 
-  writeProviderOutput(result);
-
   if (!result.ok) {
+    writeProviderOutput(result);
     throw annotateProviderError(result.error || new Error('provider run failed'), 'plan', phase);
   }
 
+  const clean = extractCleanProviderOutput(result, { prompt, projectRoot: repoRoot });
+  let cleanOutput = clean.cleanOutput;
+  let reviewPath = '';
+
+  if (options.review === true) {
+    const reviewed = await reviewTextWithEditor(repoRoot, cleanOutput, {
+      ...options,
+      reviewFileName: `ai-plan-${phase}-draft.md`,
+      reviewLabel: `ai plan --phase ${phase} review`,
+    });
+    cleanOutput = reviewed.text;
+    reviewPath = reviewed.reviewPath;
+  }
+
+  await confirmInteractiveAction(`Save ${phase} planner draft?`, options);
   const lifecycleRun = ensureAiRun(repoRoot, {
     command: `ai plan --phase ${phase}`,
     input: inputPath,
     runId: options.runId,
   });
-  const clean = extractCleanProviderOutput(result, { prompt, projectRoot: repoRoot });
+  writeCleanProviderOutput({ cleanOutput });
   const rawArtifact = writeRawProviderArtifact(repoRoot, lifecycleRun.run_id, `ai-plan-${phase}`, result, {
     metadata: {
       phase,
@@ -895,10 +1600,11 @@ async function runPlan(repoRoot, options = {}) {
       input_compaction: inputCompaction,
     },
   });
-  const draft = savePlannerDraft(repoRoot, phase, inputPath, clean.cleanOutput, {
+  const draft = savePlannerDraft(repoRoot, phase, inputPath, cleanOutput, {
     rawArtifactPath: rawArtifact.path,
     outputSource: clean.source,
     inputCompaction,
+    reviewPath,
   });
   updateAiRunPhase(repoRoot, lifecycleRun.run_id, phase === 'acceptance' ? 'acceptance-draft' : 'technical-plan-draft', {
     artifact: path.relative(repoRoot, draft.filePath).split(path.sep).join('/'),
@@ -913,6 +1619,7 @@ async function runPlan(repoRoot, options = {}) {
     phase,
     invocation,
     result,
+    reviewPath,
   };
 }
 
@@ -1011,9 +1718,8 @@ async function runReviewPlan(repoRoot, options = {}) {
     throw annotateProviderError(error, 'review-plan');
   }
 
-  writeProviderOutput(result);
-
   if (!result.ok) {
+    writeProviderOutput(result);
     throw annotateProviderError(result.error || new Error('provider run failed'), 'review-plan');
   }
 
@@ -1035,6 +1741,7 @@ async function runReviewPlan(repoRoot, options = {}) {
       stripped_prompt_echo: clean.strippedPromptEcho,
     },
   });
+  writeCleanProviderOutput(clean);
   const saved = savePlanReview(repoRoot, {
     contents: clean.cleanOutput,
     inputPath,
@@ -1044,7 +1751,8 @@ async function runReviewPlan(repoRoot, options = {}) {
     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`);
+  const summary = summarizePlanReview(repoRoot).trimEnd();
+  process.stdout.write(`AI plan review saved\nArtifact: ${relativePath}\nPrompt source: ${PLAN_REVIEW_PROMPT_SOURCE}\n${summary}\n`);
 
   return {
     task: 'review-plan',
@@ -1060,6 +1768,146 @@ async function runReviewPlan(repoRoot, options = {}) {
   };
 }
 
+async function runRepairPlan(repoRoot, options = {}) {
+  const role = normalizeRole(options.role || DEFAULT_PLAN_ROLE);
+  const provider = resolveProviderForProfile(repoRoot, role, options.provider, options.providerExplicit, DEFAULT_PLAN_PROVIDER);
+  const context = options.context || DEFAULT_PLAN_CONTEXT;
+  const timeoutMs = normalizeTimeout(options.timeout);
+  const source = resolveApprovedTechnicalPlanForRepair(repoRoot, options.input || '');
+  const built = buildRepairPlanContext({
+    context,
+    inputText: source.contents,
+    inputPath: source.path,
+    repoRoot,
+    role,
+    validationError: source.validationError,
+  });
+  assertProviderPromptWithinLimit(built.prompt, options);
+  let invocation;
+
+  try {
+    invocation = buildProviderInvocation(provider, {
+      prompt: built.prompt,
+      cwd: repoRoot,
+      timeoutMs,
+    });
+  } catch (error) {
+    throw annotateProviderError(error, 'repair-plan');
+  }
+
+  if (options.dryRun) {
+    const report = {
+      task: 'repair-plan',
+      provider,
+      role,
+      contextPack: built.pack.packName,
+      phase: 'technical-plan',
+      invocation,
+    };
+    process.stdout.write(formatDryRunReport(report));
+    process.stdout.write(`Source approved artifact: ${source.path}\n`);
+    process.stdout.write(`Validation failure: ${source.validationError}\n`);
+    return report;
+  }
+
+  if (options.printPrompt) {
+    const report = {
+      task: 'repair-plan',
+      provider,
+      role,
+      contextPack: built.pack.packName,
+      phase: 'technical-plan',
+      invocation,
+      prompt: built.prompt,
+      inputPath: source.path,
+      inputKind: 'approved',
+      inputVersion: source.approval.meta?.approved?.version || null,
+    };
+    process.stdout.write(formatPromptOnlyReport(report));
+    return report;
+  }
+
+  let providerResult;
+  try {
+    providerResult = await (options.runProviderFn || runProvider)(provider, {
+      prompt: built.prompt,
+      cwd: repoRoot,
+      timeoutMs,
+      dryRun: false,
+      probe: options.probe,
+      spawn: options.spawn,
+      tempRoot: options.tempRoot,
+      tempFileName: options.tempFileName,
+      tempFilePrefix: options.tempFilePrefix,
+    });
+  } catch (error) {
+    throw annotateProviderError(error, 'repair-plan');
+  }
+
+  if (!providerResult.ok) {
+    writeProviderOutput(providerResult);
+    throw annotateProviderError(providerResult.error || new Error('provider run failed'), 'repair-plan');
+  }
+
+  const lifecycleRun = ensureAiRun(repoRoot, {
+    command: 'ai repair-plan',
+    input: source.path,
+    runId: options.runId,
+  });
+  const clean = extractCleanProviderOutput(providerResult, { prompt: built.prompt, projectRoot: repoRoot });
+  const rawArtifact = writeRawProviderArtifact(repoRoot, lifecycleRun.run_id, 'ai-repair-plan', providerResult, {
+    metadata: {
+      phase: 'technical-plan-repair',
+      input_path: source.path,
+      prompt_bytes: invocation.promptLength,
+      clean_output_source: clean.source,
+      stripped_prompt_echo: clean.strippedPromptEcho,
+      validation_failure: source.validationError,
+    },
+  });
+
+  try {
+    validateTechnicalPlanSpecContract(repoRoot, {
+      inputPath: source.path,
+      inputText: clean.cleanOutput,
+    });
+  } catch (error) {
+    throw new Error(formatError([
+      'ai repair-plan provider output is still missing the required structured `spec.slices[]` contract.',
+      stripCreateQuiverPrefix(error.message || error),
+      `Raw provider artifact: ${rawArtifact.path}`,
+      'No technical-plan draft was written.',
+    ].join('\n')));
+  }
+
+  writeCleanProviderOutput(clean);
+  const draft = savePlannerDraft(repoRoot, 'technical-plan', source.path, clean.cleanOutput, {
+    rawArtifactPath: rawArtifact.path,
+    outputSource: clean.source,
+  });
+  updateAiRunPhase(repoRoot, lifecycleRun.run_id, 'technical-plan-draft', {
+    artifact: path.relative(repoRoot, draft.filePath).split(path.sep).join('/'),
+    command: 'ai repair-plan',
+  });
+  process.stdout.write(formatRepairPlanResult({
+    ...draft,
+    sourcePath: source.path,
+  }, repoRoot));
+
+  return {
+    task: 'repair-plan',
+    provider,
+    role,
+    contextPack: built.pack.packName,
+    phase: 'technical-plan',
+    inputPath: source.path,
+    filePath: path.relative(repoRoot, draft.filePath).split(path.sep).join('/'),
+    version: draft.version || null,
+    invocation,
+    result: providerResult,
+  };
+}
+
 async function runRevise(repoRoot, options = {}) {
   const phase = normalizePlannerPhase(options.phase || DEFAULT_PLAN_PHASE);
   if (phase === 'spec') {
@@ -1095,8 +1943,14 @@ async function runApprove(repoRoot, options = {}) {
   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\`.`));
+      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 --dry-run\`, then \`npx create-quiver ai review-plan\`.`));
+    }
+    if (reviewBlocksApproval(review)) {
+      const result = review.meta.review_result;
+      const requiredFixes = Array.isArray(result.required_fixes) ? result.required_fixes.length : 0;
+      throw new Error(formatError(`ai approve --phase technical-plan is blocked by plan review; approval recommendation is ${result.approval_recommendation}. Required fixes: ${requiredFixes}. Next command: ${result.next_command}`));
     }
+    assertTechnicalPlanDraftHasSpecContract(repoRoot, options.version);
   }
 
   const inputText = '';
@@ -1255,14 +2109,53 @@ function runTraceReport(repoRoot, options = {}) {
   };
 }
 
+function runActiveSlice(repoRoot, options = {}) {
+  const command = String(options.command || 'status').trim().toLowerCase();
+  if (command !== 'status' && command !== 'reconcile') {
+    throw new Error(formatError(`unsupported ai active-slice subcommand: ${command}. Supported tasks: status, reconcile`));
+  }
+  if (command === 'reconcile' && options.dryRun !== true) {
+    throw new Error(formatError('ai active-slice reconcile is dry-run first. Run `npx create-quiver ai active-slice reconcile --dry-run`.'));
+  }
+
+  const state = resolveProjectState(repoRoot, { allowGraphErrors: true });
+  const report = collectActiveSliceState(repoRoot, { slices: state.graph.nodes });
+  process.stdout.write(formatActiveSliceReconciliationReport(report, {
+    dryRun: options.dryRun === true,
+  }));
+  return {
+    task: 'active-slice',
+    command,
+    dryRun: options.dryRun === true,
+    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 (command !== 'create' && command !== 'close') {
+    throw new Error(formatError(`unsupported ai run subcommand: ${command}. Supported tasks: create, close`));
   }
-  if (!options.input) {
+  if (command === 'create' && !options.input) {
     throw new Error(formatError('ai run create requires --input <requirements.md>'));
   }
+  if (command === 'close') {
+    const current = resolveAiRun(repoRoot, options.runId || '');
+    if (!current) {
+      throw new Error(formatError('ai run close requires an active run or --run <id>'));
+    }
+    const run = updateAiRunPhase(repoRoot, current.run_id, 'closed', {
+      command: 'ai run close',
+    });
+    const report = `AI run closed\n${formatAiRunStatus(repoRoot, run)}`;
+    process.stdout.write(report);
+    return {
+      task: 'run',
+      command,
+      run,
+      report,
+    };
+  }
   const run = createAiRun(repoRoot, {
     command: 'ai run create',
     input: options.input,
@@ -1463,6 +2356,31 @@ async function runPr(repoRoot, options = {}) {
     throw annotateGitHubError(error, 'pr');
   }
 
+  if (options.review === true) {
+    const hasEditorRunner = typeof options.openEditorFn === 'function';
+    const canOpenEditor = hasEditorRunner || options.stdinIsTTY === true || (options.stdinIsTTY !== false && Boolean(process.stdin.isTTY));
+    if (!canOpenEditor) {
+      throw annotateGitHubError(makeReviewError('ai pr --review requires an interactive terminal or an injected editor runner.', plan.prBodyPath), 'pr');
+    }
+    const editorResult = hasEditorRunner
+      ? options.openEditorFn(plan.prBodyPath, { cwd: repoRoot, env: options.env || process.env })
+      : openEditor(plan.prBodyPath, { cwd: repoRoot, env: options.env || process.env });
+    if (!editorResult || editorResult.ok !== true) {
+      throw annotateGitHubError(makeReviewError(editorResult?.reason || 'ai pr review was canceled.', plan.prBodyPath), 'pr');
+    }
+    try {
+      plan = buildPrCreatePlan(repoRoot, preflight, {
+        baseBranch: options.baseBranch,
+        ghCommand: options.ghCommand,
+        input: options.input,
+        prBodyPath: options.prBodyPath,
+        title: options.title,
+      });
+    } catch (error) {
+      throw annotateGitHubError(error, 'pr');
+    }
+  }
+
   if (dryRun || !create) {
     process.stdout.write(formatPrCreateReport({ preflight, plan }, { dryRun, create }));
     return {
@@ -1474,6 +2392,8 @@ async function runPr(repoRoot, options = {}) {
     };
   }
 
+  await confirmInteractiveAction(`Create GitHub PR '${plan.title}'?`, options);
+
   let result;
   try {
     result = runGhPrCreate(plan, {
@@ -1516,6 +2436,7 @@ module.exports = {
   normalizeTimeout,
   readTextFile,
   runAgent,
+  runActiveSlice,
   runDoctor,
   runExecutePlan,
   runExecuteSlice,
@@ -1528,6 +2449,7 @@ module.exports = {
   runApprove,
   runApprovalStatus,
   runPrepareContext,
+  runRepairPlan,
   runReviewPlan,
   runRevise,
   runPr,