@ai-content-space/loopx 0.1.0 → 0.1.2

package/src/workflow.mjs

@@ -1,9 +1,12 @@
 import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-import { ensureLoopXRoot, resolveLoopXRoot } from './runtime-maintenance.mjs';
+import { AUTOPILOT_PHASES, createDefaultAutopilotAdapter } from './autopilot-runtime.mjs';
+import { ensureLoopxRoot, resolveLoopxRoot } from './runtime-maintenance.mjs';
+import { DEFAULT_BUILD_MAX_ITERATIONS, createDefaultBuildAdapter } from './build-runtime.mjs';
+import { DEFAULT_MAX_ITERATIONS, createDefaultPlanAdapter } from './plan-runtime.mjs';
 
 const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
 const WORKSPACE_SCHEMA_VERSION = 1;
@@ -36,6 +39,23 @@ export const TRANSITIONS = {
 const PLAN_ARTIFACTS = ['plan.md', 'architecture.md', 'development-plan.md', 'test-plan.md'];
 const V1_ARTIFACTS = ['spec.md', ...PLAN_ARTIFACTS, 'execution-record.md', 'review-report.md'];
 const LEGACY_ARTIFACTS = ['brief.md', 'plan.md', 'detailed-design.md', 'architecture.md', 'test-plan.md', 'build-result.md', 'review-report.md'];
+const PLAN_DOC_FILENAMES = {
+  architecture: '架构文档.md',
+  design: '设计文档.md',
+  testPlan: '测试计划.md',
+};
+const PLAN_REVIEW_DIR = 'plan-reviews';
+const BUILD_SUPPORT_DIR = 'build-support';
+const CLARIFY_PROFILES = {
+  standard: {
+    threshold: 0.2,
+    maxRounds: 15,
+  },
+  deep: {
+    threshold: 0.1,
+    maxRounds: 25,
+  },
+};
 
 function normalizeSlug(raw) {
   const slug = String(raw || '')
@@ -57,6 +77,14 @@ function nowStamp() {
   return nowIso().replace(/[-:]/g, '').replace(/\.\d{3}Z$/, 'Z');
 }
 
+function normalizeClarifyProfile(raw) {
+  const value = String(raw || 'standard').trim().toLowerCase();
+  if (!(value in CLARIFY_PROFILES)) {
+    throw new Error(`invalid_clarify_profile:${value}`);
+  }
+  return value;
+}
+
 function parseFrontmatter(text) {
   if (!text.startsWith('---\n')) {
     return {};
@@ -113,6 +141,22 @@ function frontmatterBlock(values) {
   return lines.join('\n');
 }
 
+function frontmatterBoolean(value) {
+  if (value === true || value === false) {
+    return value;
+  }
+  if (typeof value === 'string') {
+    const normalized = value.trim().toLowerCase();
+    if (normalized === 'true') {
+      return true;
+    }
+    if (normalized === 'false') {
+      return false;
+    }
+  }
+  return Boolean(value);
+}
+
 function statePath(root) {
   return join(root, 'state.json');
 }
@@ -153,7 +197,7 @@ async function writeState(root, state) {
 }
 
 export function resolveWorkspaceRoot(cwd) {
-  return resolveLoopXRoot(cwd);
+  return resolveLoopxRoot(cwd);
 }
 
 export function resolveWorkflowRoot(cwd, slug) {
@@ -168,6 +212,41 @@ function resolvePlansRoot(cwd) {
   return join(resolveWorkspaceRoot(cwd), 'plans');
 }
 
+function resolveDocsRoot(cwd, slug) {
+  return join(resolve(cwd), 'docs', normalizeSlug(slug));
+}
+
+function resolvePlanDocPaths(cwd, slug) {
+  const docsRoot = resolveDocsRoot(cwd, slug);
+  return {
+    docsRoot,
+    architecture: join(docsRoot, PLAN_DOC_FILENAMES.architecture),
+    design: join(docsRoot, PLAN_DOC_FILENAMES.design),
+    testPlan: join(docsRoot, PLAN_DOC_FILENAMES.testPlan),
+  };
+}
+
+function resolvePlanReviewPaths(root, iteration) {
+  const reviewsRoot = join(root, PLAN_REVIEW_DIR);
+  return {
+    reviewsRoot,
+    planner: join(reviewsRoot, `planner-iteration-${iteration}.md`),
+    architect: join(reviewsRoot, `architect-iteration-${iteration}.md`),
+    critic: join(reviewsRoot, `critic-iteration-${iteration}.md`),
+  };
+}
+
+function resolveBuildSupportPaths(root, iteration) {
+  const supportRoot = join(root, BUILD_SUPPORT_DIR);
+  return {
+    supportRoot,
+    laneSummary: join(supportRoot, `lanes-iteration-${iteration}.md`),
+    architect: join(supportRoot, `architect-iteration-${iteration}.md`),
+    deslop: join(supportRoot, `deslop-iteration-${iteration}.md`),
+    regression: join(supportRoot, `regression-iteration-${iteration}.md`),
+  };
+}
+
 function canonicalClarifySpecPath(cwd, slug, stamp) {
   return join(resolveSpecsRoot(cwd), `clarify-${normalizeSlug(slug)}-${stamp}.md`);
 }
@@ -190,9 +269,9 @@ export async function readState(cwd, slug) {
 
 function buildWorkspaceReadme() {
   return [
-    '# LoopX Workspace',
+    '# loopx Workspace',
     '',
-    'This directory is initialized for the LoopX skill-first runtime contract.',
+    'This directory is initialized for the loopx skill-first runtime contract.',
     '',
     '## Default Flow',
     '',
@@ -214,22 +293,66 @@ function buildWorkspaceReadme() {
   ].join('\n');
 }
 
-function createInitialState(slug) {
+function createInitialState(slug, profile) {
+  const clarifyProfile = CLARIFY_PROFILES[profile];
   return {
     schema_version: WORKFLOW_SCHEMA_VERSION,
     slug,
     current_stage: STAGES.CLARIFY,
     stage_status: 'blocked',
+    clarify_profile: profile,
+    clarify_target_ambiguity_threshold: clarifyProfile.threshold,
+    clarify_max_rounds: clarifyProfile.maxRounds,
+    clarify_current_round: 0,
+    clarify_ambiguity_score: 1,
+    clarify_pressure_pass_complete: false,
+    clarify_non_goals_resolved: false,
+    clarify_decision_boundaries_resolved: false,
     ambiguity_items: [
       {
         id: 'A-1',
-        question: 'What specific task should LoopX execute in this workflow?',
+        question: 'What specific task should loopx execute in this workflow?',
         status: 'open',
         resolution: null,
       },
     ],
     unresolved_ambiguity_count: 1,
     plan_package_status: 'missing',
+    plan_current_iteration: 0,
+    plan_max_iterations: DEFAULT_MAX_ITERATIONS,
+    plan_consensus_mode: false,
+    plan_deliberate_mode: false,
+    plan_interactive_mode: false,
+    plan_principles_resolved: false,
+    plan_options_reviewed: false,
+    plan_architect_review_status: 'not-started',
+    plan_critic_verdict: 'none',
+    plan_acceptance_criteria_testable: false,
+    plan_verification_steps_resolved: false,
+    plan_execution_inputs_resolved: false,
+    plan_docs_status: 'missing',
+    plan_docs_artifact_paths: null,
+    plan_review_artifact_paths: [],
+    plan_blockers: [],
+    plan_source_spec_path: null,
+    build_run_id: null,
+    build_current_iteration: 0,
+    build_max_iterations: DEFAULT_BUILD_MAX_ITERATIONS,
+    build_parallel_mode: false,
+    build_lane_statuses: [],
+    build_verification_status: 'pending',
+    build_architect_verification_status: 'not-started',
+    build_deslop_status: 'pending',
+    build_regression_status: 'pending',
+    build_blockers: [],
+    build_progress_artifact_paths: [],
+    build_support_evidence_paths: [],
+    build_no_deslop: false,
+    autopilot_current_phase: 'none',
+    autopilot_phase_history: [],
+    autopilot_blockers: [],
+    autopilot_run_path: null,
+    autopilot_completed: false,
     review_status: 'not-started',
     recommended_next_action: 'Resolve ambiguity items in spec.md before requesting approval to enter plan.',
     rollback_target: 'none',
@@ -293,8 +416,10 @@ async function copyArtifact(fromRoot, toPath, name) {
 }
 
 async function writeCanonicalPlanArtifacts(cwd, root, slug) {
-  const planPath = join(resolvePlansRoot(cwd), `prd-${slug}.md`);
-  const testSpecPath = join(resolvePlansRoot(cwd), `test-spec-${slug}.md`);
+  const plansRoot = resolvePlansRoot(cwd);
+  await ensureDir(plansRoot);
+  const planPath = join(plansRoot, `prd-${slug}.md`);
+  const testSpecPath = join(plansRoot, `test-spec-${slug}.md`);
   const planText = await readFile(artifactPath(root, 'plan.md'), 'utf8');
   const architectureText = await readFile(artifactPath(root, 'architecture.md'), 'utf8');
   const developmentPlanText = await readFile(artifactPath(root, 'development-plan.md'), 'utf8');
@@ -303,7 +428,7 @@ async function writeCanonicalPlanArtifacts(cwd, root, slug) {
   await writeText(
     planPath,
     [
-      `# LoopX PRD: ${slug}`,
+      `# loopx PRD: ${slug}`,
       '',
       '## Plan',
       '',
@@ -322,14 +447,342 @@ async function writeCanonicalPlanArtifacts(cwd, root, slug) {
   return { planPath, testSpecPath };
 }
 
+function deriveSlugFromSpecPath(path, text) {
+  const meta = parseFrontmatter(text);
+  if (meta.workflow_id) {
+    return normalizeSlug(meta.workflow_id);
+  }
+  const name = basename(path).replace(/\.md$/i, '');
+  return normalizeSlug(name.replace(/^deep-interview-/, '').replace(/^clarify-/, ''));
+}
+
+function containsChineseText(text) {
+  return /[\u3400-\u9fff]/.test(text);
+}
+
+async function ensurePlanWorkflowFromDirectSpec(cwd, directSpecPath, explicitSlug, options = {}) {
+  const resolvedSpecPath = resolve(cwd, directSpecPath);
+  const specText = await readFile(resolvedSpecPath, 'utf8');
+  const slug = explicitSlug ? normalizeSlug(explicitSlug) : deriveSlugFromSpecPath(resolvedSpecPath, specText);
+  const root = resolveWorkflowRoot(cwd, slug);
+  await ensureLoopxRoot(cwd);
+  await ensureDir(root);
+  await writeText(artifactPath(root, 'spec.md'), specText);
+
+  const existing = await readState(cwd, slug);
+  if (existing) {
+    const merged = withRecommendedAction({
+      ...existing,
+      spec_artifact_path: resolvedSpecPath,
+      plan_source_spec_path: resolvedSpecPath,
+      plan_consensus_mode: true,
+      plan_deliberate_mode: Boolean(options.deliberate),
+      plan_interactive_mode: Boolean(options.interactive),
+    });
+    await writeState(root, merged);
+    return { slug, root, state: merged };
+  }
+
+  const state = withRecommendedAction({
+    ...createInitialState(slug, 'standard'),
+    clarify_current_round: 1,
+    clarify_ambiguity_score: 0,
+    clarify_pressure_pass_complete: true,
+    clarify_non_goals_resolved: true,
+    clarify_decision_boundaries_resolved: true,
+    unresolved_ambiguity_count: 0,
+    spec_artifact_path: resolvedSpecPath,
+    plan_source_spec_path: resolvedSpecPath,
+    requested_transition: TRANSITIONS.CLARIFY_TO_PLAN,
+    stage_status: 'awaiting-approval',
+    plan_consensus_mode: true,
+    plan_deliberate_mode: Boolean(options.deliberate),
+    plan_interactive_mode: Boolean(options.interactive),
+    approval: {
+      ...createInitialState(slug, 'standard').approval,
+      plan: APPROVAL_STATES.APPROVED,
+    },
+  });
+  await writeState(root, state);
+  return { slug, root, state };
+}
+
+async function writePlanArtifacts(root, cwd, slug, plannerDraft) {
+  await writeText(artifactPath(root, 'plan.md'), plannerDraft.planText);
+  await writeText(artifactPath(root, 'architecture.md'), plannerDraft.architectureText);
+  await writeText(artifactPath(root, 'development-plan.md'), plannerDraft.developmentPlanText);
+  await writeText(artifactPath(root, 'test-plan.md'), plannerDraft.testPlanText);
+
+  const docPaths = resolvePlanDocPaths(cwd, slug);
+  await ensureDir(docPaths.docsRoot);
+  await writeText(docPaths.architecture, plannerDraft.docs.architecture);
+  await writeText(docPaths.design, plannerDraft.docs.design);
+  await writeText(docPaths.testPlan, plannerDraft.docs.testPlan);
+  return docPaths;
+}
+
+async function writePlanReviewArtifacts(root, iteration, plannerDraft, architectReview, criticReview) {
+  const paths = resolvePlanReviewPaths(root, iteration);
+  await ensureDir(paths.reviewsRoot);
+  await writeText(
+    paths.planner,
+    [
+      `# Planner Draft: iteration ${iteration}`,
+      '',
+      '## Principles',
+      '',
+      ...plannerDraft.principles.map((item) => `- ${item}`),
+      '',
+      '## Decision Drivers',
+      '',
+      ...plannerDraft.decisionDrivers.map((item) => `- ${item}`),
+    ].join('\n'),
+  );
+  await writeText(
+    paths.architect,
+    [
+      `# Architect Review: iteration ${iteration}`,
+      '',
+      `- status: ${architectReview.status}`,
+      `- verdict: ${architectReview.verdict}`,
+      '',
+      '## Findings',
+      '',
+      ...architectReview.findings.map((item) => `- ${item}`),
+    ].join('\n'),
+  );
+  await writeText(
+    paths.critic,
+    [
+      `# Critic Review: iteration ${iteration}`,
+      '',
+      `- verdict: ${criticReview.verdict}`,
+      '',
+      '## Findings',
+      '',
+      ...criticReview.findings.map((item) => `- ${item}`),
+    ].join('\n'),
+  );
+  return paths;
+}
+
+async function readPlanCompletion(cwd, root, slug, state) {
+  const blockers = [];
+  const docPaths = resolvePlanDocPaths(cwd, slug);
+  const docsPresent = {
+    architecture: existsSync(docPaths.architecture),
+    design: existsSync(docPaths.design),
+    testPlan: existsSync(docPaths.testPlan),
+  };
+  if (state.plan_architect_review_status !== 'complete') {
+    blockers.push('architect_review_incomplete');
+  }
+  if (state.plan_critic_verdict !== 'approve') {
+    blockers.push(`critic_verdict_${state.plan_critic_verdict}`);
+  }
+  if (state.plan_package_status !== 'complete') {
+    blockers.push(`plan_package_${state.plan_package_status}`);
+  }
+  if (!state.plan_acceptance_criteria_testable) {
+    blockers.push('acceptance_criteria_unresolved');
+  }
+  if (!state.plan_verification_steps_resolved) {
+    blockers.push('verification_steps_unresolved');
+  }
+  if (!state.plan_execution_inputs_resolved) {
+    blockers.push('execution_inputs_unresolved');
+  }
+  if (!state.plan_artifact_path || !existsSync(state.plan_artifact_path)) {
+    blockers.push('missing_prd');
+  }
+  if (!state.test_spec_artifact_path || !existsSync(state.test_spec_artifact_path)) {
+    blockers.push('missing_test_spec');
+  }
+  for (const [key, present] of Object.entries(docsPresent)) {
+    if (!present) {
+      blockers.push(`missing_doc_${key}`);
+      continue;
+    }
+    const text = await readFile(docPaths[key], 'utf8');
+    if (!containsChineseText(text)) {
+      blockers.push(`doc_not_chinese_${key}`);
+    }
+  }
+
+  const docsComplete = Object.values(docsPresent).every(Boolean)
+    && blockers.every((blocker) => !blocker.startsWith('doc_not_chinese_') && !blocker.startsWith('missing_doc_'));
+
+  return {
+    blockers,
+    docsStatus: docsComplete ? 'complete' : Object.values(docsPresent).some(Boolean) ? 'partial' : 'missing',
+    docPaths,
+  };
+}
+
+function buildIterationBlockers(iterationData, { noDeslop = false } = {}) {
+  const blockers = [];
+  for (const lane of iterationData.lanes) {
+    if (lane.status !== 'complete') {
+      blockers.push(`lane_incomplete_${lane.name}`);
+    }
+  }
+  if (iterationData.verificationStatus !== 'complete') {
+    blockers.push(`verification_${iterationData.verificationStatus}`);
+  }
+  if (iterationData.architectVerdict !== 'approve') {
+    blockers.push(`architect_${iterationData.architectVerdict}`);
+  }
+  if (!noDeslop && iterationData.deslopStatus !== 'complete') {
+    blockers.push(`deslop_${iterationData.deslopStatus}`);
+  }
+  if (!noDeslop && iterationData.regressionStatus !== 'complete') {
+    blockers.push(`regression_${iterationData.regressionStatus}`);
+  }
+  return blockers;
+}
+
+function buildExecutionRecordContent({ slug, iterationData, complete }) {
+  const placeholder = complete ? null : 'TODO: build iteration is not review-ready yet.';
+  return [
+    frontmatterBlock({
+      schema_version: WORKFLOW_SCHEMA_VERSION,
+      workflow_id: slug,
+      run_id: iterationData.runId,
+      stage: STAGES.BUILD,
+      actor_id: iterationData.actorId,
+      actor_role: STAGES.BUILD,
+      plan_digest: `plan@${slug}`,
+      started_at: nowIso(),
+      completed_at: nowIso(),
+      checkpoint_count: iterationData.lanes.length,
+      evidence_manifest: iterationData.lanes.flatMap((lane) => lane.evidence || []),
+    }),
+    `# loopx Execution Record: ${slug}`,
+    '',
+    '## Changes',
+    '',
+    '- Completed the current build iteration lanes and aggregated evidence.',
+    '',
+    '## Checkpoint Log',
+    '',
+    ...iterationData.lanes.map((lane) => `- ${lane.name}: ${lane.status}`),
+    '',
+    '## Execution Evidence',
+    '',
+    ...iterationData.executionEvidence.map((item) => `- ${item}`),
+    '',
+    '## Verification Evidence',
+    '',
+    ...iterationData.verificationEvidence.map((item) => `- ${item}`),
+    '',
+    '## Limitations',
+    '',
+    ...(placeholder ? [`- ${placeholder}`] : iterationData.limitations.map((item) => `- ${item}`)),
+  ].join('\n');
+}
+
+async function writeBuildSupportArtifacts(root, iterationData, noDeslop) {
+  const paths = resolveBuildSupportPaths(root, iterationData.iteration);
+  await ensureDir(paths.supportRoot);
+  await writeText(
+    paths.laneSummary,
+    [
+      `# Build Lanes: iteration ${iterationData.iteration}`,
+      '',
+      ...iterationData.lanes.map((lane) => `- ${lane.name}: ${lane.status} | ${lane.summary}`),
+    ].join('\n'),
+  );
+  await writeText(
+    paths.architect,
+    [
+      `# Build Architect Gate: iteration ${iterationData.iteration}`,
+      '',
+      `- verdict: ${iterationData.architectVerdict}`,
+      '',
+      ...iterationData.architectFindings.map((item) => `- ${item}`),
+    ].join('\n'),
+  );
+  await writeText(
+    paths.deslop,
+    [
+      `# Build Deslop: iteration ${iterationData.iteration}`,
+      '',
+      `- status: ${noDeslop ? 'skipped' : iterationData.deslopStatus}`,
+    ].join('\n'),
+  );
+  await writeText(
+    paths.regression,
+    [
+      `# Build Regression: iteration ${iterationData.iteration}`,
+      '',
+      `- status: ${noDeslop ? 'skipped' : iterationData.regressionStatus}`,
+    ].join('\n'),
+  );
+  return paths;
+}
+
 async function readSpecSummary(root) {
   const text = await readTextIfExists(artifactPath(root, 'spec.md'));
   if (!text) {
-    return { unresolvedCount: 1 };
+    return {
+      unresolvedCount: 1,
+      currentRound: 0,
+      ambiguityScore: 1,
+      pressurePassComplete: false,
+      nonGoalsResolved: false,
+      decisionBoundariesResolved: false,
+    };
   }
   const meta = parseFrontmatter(text);
   const unresolvedCount = Number.parseInt(String(meta.unresolved_ambiguity_count ?? 1), 10);
-  return { unresolvedCount: Number.isNaN(unresolvedCount) ? 1 : unresolvedCount };
+  const currentRound = Number.parseInt(String(meta.current_round ?? meta.clarify_current_round ?? 0), 10);
+  const ambiguityScore = Number.parseFloat(String(meta.ambiguity_score ?? meta.clarify_ambiguity_score ?? 1));
+  return {
+    unresolvedCount: Number.isNaN(unresolvedCount) ? 1 : unresolvedCount,
+    currentRound: Number.isNaN(currentRound) ? 0 : currentRound,
+    ambiguityScore: Number.isFinite(ambiguityScore) && ambiguityScore >= 0 && ambiguityScore <= 1 ? ambiguityScore : 1,
+    pressurePassComplete: frontmatterBoolean(meta.pressure_pass_complete ?? meta.clarify_pressure_pass_complete ?? false),
+    nonGoalsResolved: frontmatterBoolean(meta.non_goals_resolved ?? meta.clarify_non_goals_resolved ?? false),
+    decisionBoundariesResolved: frontmatterBoolean(meta.decision_boundaries_resolved ?? meta.clarify_decision_boundaries_resolved ?? false),
+  };
+}
+
+function withClarifySummary(state, spec) {
+  return {
+    ...state,
+    clarify_current_round: spec.currentRound,
+    clarify_ambiguity_score: spec.ambiguityScore,
+    clarify_pressure_pass_complete: spec.pressurePassComplete,
+    clarify_non_goals_resolved: spec.nonGoalsResolved,
+    clarify_decision_boundaries_resolved: spec.decisionBoundariesResolved,
+    unresolved_ambiguity_count: spec.unresolvedCount,
+  };
+}
+
+function clarifyReadinessBlockers(state) {
+  const blockers = [];
+  if (state.unresolved_ambiguity_count > 0) {
+    blockers.push('unresolved_ambiguity');
+  }
+  if (state.clarify_current_round <= 0) {
+    blockers.push('clarify_current_round_required');
+  }
+  if (state.clarify_current_round > state.clarify_max_rounds) {
+    blockers.push('clarify_max_rounds_exceeded');
+  }
+  if (state.clarify_ambiguity_score > state.clarify_target_ambiguity_threshold) {
+    blockers.push('clarify_ambiguity_score_above_threshold');
+  }
+  if (!state.clarify_non_goals_resolved) {
+    blockers.push('clarify_non_goals_unresolved');
+  }
+  if (!state.clarify_decision_boundaries_resolved) {
+    blockers.push('clarify_decision_boundaries_unresolved');
+  }
+  if (!state.clarify_pressure_pass_complete) {
+    blockers.push('clarify_pressure_pass_incomplete');
+  }
+  return blockers;
 }
 
 async function readExecutionRecordSummary(root) {
@@ -363,19 +816,25 @@ async function readExecutionRecordSummary(root) {
 
 function recommendedAction(state, legacy = false) {
   if (legacy) {
-    return 'Legacy codex-helper workflow detected. Run loopx migrate or create a new LoopX workflow.';
+    return 'Legacy codex-helper workflow detected. Run loopx migrate or create a new loopx workflow.';
   }
 
   switch (state.current_stage) {
     case STAGES.CLARIFY:
       return state.approval.plan === APPROVAL_STATES.APPROVED
         ? 'Run loopx plan to consume the approved clarify -> plan transition.'
-        : 'Resolve ambiguity and approve clarify -> plan.';
+        : `Resolve ambiguity in ${state.clarify_profile ?? 'standard'} clarify mode and approve clarify -> plan.`;
     case STAGES.PLAN:
+      if (Array.isArray(state.plan_blockers) && state.plan_blockers.length > 0) {
+        return 'Run loopx plan to continue the planning review loop until architect, critic, and docs blockers are cleared.';
+      }
       return state.approval.build === APPROVAL_STATES.APPROVED
         ? 'Run loopx build to consume the approved plan -> build transition.'
         : 'Approve plan -> build when the plan package is ready.';
     case STAGES.BUILD:
+      if (Array.isArray(state.build_blockers) && state.build_blockers.length > 0) {
+        return 'Run loopx build to continue the execution loop until verification, architect, deslop, and regression blockers are cleared.';
+      }
       return state.approval.review === APPROVAL_STATES.APPROVED
         ? 'Run loopx review to consume the approved build -> review transition.'
         : 'Approve build -> review when execution-record.md is complete.';
@@ -392,6 +851,9 @@ function recommendedAction(state, legacy = false) {
       }
       return 'Run loopx review after build completes.';
     case STAGES.DONE:
+      if (state.autopilot_current_phase && state.autopilot_current_phase !== 'none' && state.autopilot_completed) {
+        return 'Autopilot run is complete.';
+      }
       return 'Workflow is complete.';
     default:
       return 'Run loopx clarify to start a workflow.';
@@ -466,7 +928,7 @@ function executionRecordTemplate(slug, stage, actorId, runId) {
       checkpoint_count: 0,
       evidence_manifest: [],
     }),
-    `# LoopX Execution Record: ${slug}`,
+    `# loopx Execution Record: ${slug}`,
     '',
     '## Changes',
     '',
@@ -504,7 +966,7 @@ function reviewReportContent({ slug, reviewer, runId, verdict, rollbackTarget, r
       rollback_target: rollbackTarget,
       rollback_rationale: rollbackRationale ?? null,
     }),
-    `# LoopX Review Report: ${slug}`,
+    `# loopx Review Report: ${slug}`,
     '',
     '## Verdict',
     '',
@@ -538,7 +1000,7 @@ async function refreshExecutionStatus(root, state) {
 
 export async function initWorkspace(cwd, { slug } = {}) {
   const workspaceRoot = resolveWorkspaceRoot(cwd);
-  await ensureLoopXRoot(cwd);
+  await ensureLoopxRoot(cwd);
   await ensureDir(join(workspaceRoot, 'context'));
   await ensureDir(join(workspaceRoot, 'workflows'));
   await ensureDir(join(workspaceRoot, 'specs'));
@@ -547,7 +1009,7 @@ export async function initWorkspace(cwd, { slug } = {}) {
 
   const config = {
     schema_version: WORKSPACE_SCHEMA_VERSION,
-    tool: 'LoopX',
+    tool: 'loopx',
     product_contract: 'skill-first-v1',
     default_flow: ['clarify', 'plan', 'build', 'review', 'done'],
     preferred_surface: ['clarify', 'plan', 'build', 'review', 'autopilot'],
@@ -567,20 +1029,24 @@ export async function initWorkspace(cwd, { slug } = {}) {
   return { workspaceRoot, config, workflow };
 }
 
-export async function clarifyStage(cwd, slug) {
+export async function clarifyStage(cwd, slug, { profile = 'standard' } = {}) {
   const normalized = normalizeSlug(slug);
+  const clarifyProfile = normalizeClarifyProfile(profile);
   const root = resolveWorkflowRoot(cwd, normalized);
-  await ensureLoopXRoot(cwd);
+  await ensureLoopxRoot(cwd);
   await ensureDir(root);
   const stamp = nowStamp();
   await writeTemplateArtifact(root, 'spec.md', {
     'task name': normalized,
     'workflow id': normalized,
+    profile: clarifyProfile,
+    'target ambiguity threshold': CLARIFY_PROFILES[clarifyProfile].threshold,
+    'max rounds': CLARIFY_PROFILES[clarifyProfile].maxRounds,
   });
   const specArtifactPath = canonicalClarifySpecPath(cwd, normalized, stamp);
   await copyArtifact(root, specArtifactPath, 'spec.md');
   const state = withRecommendedAction({
-    ...createInitialState(normalized),
+    ...createInitialState(normalized, clarifyProfile),
     spec_artifact_path: specArtifactPath,
   });
   await writeState(root, state);
@@ -598,9 +1064,17 @@ export async function approveStage(cwd, slug, { from, to }) {
 
   if (transition === TRANSITIONS.CLARIFY_TO_PLAN) {
     const spec = await readSpecSummary(root);
-    next.unresolved_ambiguity_count = spec.unresolvedCount;
-    if (spec.unresolvedCount > 0) {
-      throw new Error('unresolved_ambiguity');
+    next = withClarifySummary(next, spec);
+    const blockers = clarifyReadinessBlockers(next);
+    if (blockers.length > 0) {
+      const blocked = withRecommendedAction({
+        ...next,
+        stage_status: 'blocked',
+        pending_user_decision: TRANSITIONS.CLARIFY_TO_PLAN,
+        requested_transition: TRANSITIONS.NONE,
+      });
+      await writeState(root, blocked);
+      throw new Error(`clarify_readiness_blocked:${blockers.join(',')}`);
     }
   }
 
@@ -609,6 +1083,23 @@ export async function approveStage(cwd, slug, { from, to }) {
       throw new Error('plan_package_incomplete');
     }
     next.plan_package_status = 'complete';
+    const completion = await readPlanCompletion(cwd, root, state.slug, next);
+    next = {
+      ...next,
+      plan_docs_status: completion.docsStatus,
+      plan_docs_artifact_paths: completion.docPaths,
+      plan_blockers: completion.blockers,
+    };
+    if (completion.blockers.length > 0) {
+      const blocked = withRecommendedAction({
+        ...next,
+        stage_status: 'blocked',
+        pending_user_decision: TRANSITIONS.PLAN_TO_BUILD,
+        requested_transition: TRANSITIONS.NONE,
+      });
+      await writeState(root, blocked);
+      throw new Error(`plan_review_gate_blocked:${completion.blockers.join(',')}`);
+    }
   }
 
   if (transition === TRANSITIONS.BUILD_TO_REVIEW) {
@@ -617,6 +1108,16 @@ export async function approveStage(cwd, slug, { from, to }) {
     if (next.execution_record_status !== 'complete') {
       throw new Error('review_gate_blocked:execution-record.md');
     }
+    if (Array.isArray(next.build_blockers) && next.build_blockers.length > 0) {
+      const blocked = withRecommendedAction({
+        ...next,
+        stage_status: 'blocked',
+        pending_user_decision: TRANSITIONS.BUILD_TO_REVIEW,
+        requested_transition: TRANSITIONS.NONE,
+      });
+      await writeState(root, blocked);
+      throw new Error(`build_review_gate_blocked:${next.build_blockers.join(',')}`);
+    }
   }
 
   if (transition === TRANSITIONS.REVIEW_TO_PLAN) {
@@ -643,57 +1144,190 @@ export async function approveStage(cwd, slug, { from, to }) {
   return { root, state: next };
 }
 
-export async function planStage(cwd, slug) {
-  const { root, state, slug: normalized } = await loadWorkflowState(cwd, slug, { allowLegacy: false });
-  ensureApprovedTransition(state, TRANSITIONS.CLARIFY_TO_PLAN, 'plan');
-  if (state.spec_artifact_path) {
-    await copyArtifact(root, state.spec_artifact_path, 'spec.md');
-  }
-  for (const name of PLAN_ARTIFACTS) {
-    await writeTemplateArtifact(root, name, {
-      'task name': normalized,
-      'workflow id': normalized,
+export async function planStage(cwd, slug, options = {}) {
+  let normalized = slug ? normalizeSlug(slug) : null;
+  if (options.directSpecPath) {
+    const bootstrapped = await ensurePlanWorkflowFromDirectSpec(cwd, options.directSpecPath, normalized, options);
+    normalized = bootstrapped.slug;
+  }
+
+  const loaded = await loadWorkflowState(cwd, normalized, { allowLegacy: false });
+  const { root } = loaded;
+  let { state } = loaded;
+  if (!options.directSpecPath) {
+    ensureApprovedTransition(state, TRANSITIONS.CLARIFY_TO_PLAN, 'plan');
+    if (state.spec_artifact_path) {
+      await copyArtifact(root, state.spec_artifact_path, 'spec.md');
+    }
+  }
+
+  const sourceSpecPath = options.directSpecPath ? resolve(cwd, options.directSpecPath) : (state.plan_source_spec_path || artifactPath(root, 'spec.md'));
+  const sourceText = await readFile(sourceSpecPath, 'utf8');
+  const adapter = options.adapter || createDefaultPlanAdapter();
+  const maxIterations = DEFAULT_MAX_ITERATIONS;
+  let iteration = 1;
+  let architectReview = null;
+  let criticReview = null;
+  const reviewArtifactPaths = [];
+
+  while (iteration <= maxIterations) {
+    const plannerDraft = await adapter.planner({
+      cwd,
+      root,
+      slug: normalized,
+      sourceText,
+      iteration,
+      deliberateMode: Boolean(options.deliberate),
+      interactiveMode: Boolean(options.interactive),
+    });
+    const docPaths = await writePlanArtifacts(root, cwd, normalized, plannerDraft);
+    const artifactPaths = await writeCanonicalPlanArtifacts(cwd, root, normalized);
+
+    architectReview = await adapter.architect({
+      cwd,
+      root,
+      slug: normalized,
+      sourceText,
+      plannerDraft,
+      iteration,
+      deliberateMode: Boolean(options.deliberate),
     });
+    criticReview = await adapter.critic({
+      cwd,
+      root,
+      slug: normalized,
+      sourceText,
+      plannerDraft,
+      architectReview,
+      iteration,
+      deliberateMode: Boolean(options.deliberate),
+    });
+    const reviewPaths = await writePlanReviewArtifacts(root, iteration, plannerDraft, architectReview, criticReview);
+    reviewArtifactPaths.push(reviewPaths);
+
+    state = {
+      ...state,
+      current_stage: STAGES.PLAN,
+      plan_current_iteration: iteration,
+      plan_max_iterations: maxIterations,
+      plan_consensus_mode: true,
+      plan_deliberate_mode: Boolean(options.deliberate),
+      plan_interactive_mode: Boolean(options.interactive),
+      plan_principles_resolved: plannerDraft.principlesResolved,
+      plan_options_reviewed: plannerDraft.optionsReviewed,
+      plan_architect_review_status: architectReview.status,
+      plan_critic_verdict: criticReview.verdict,
+      plan_acceptance_criteria_testable: criticReview.acceptanceCriteriaTestable,
+      plan_verification_steps_resolved: criticReview.verificationStepsResolved,
+      plan_execution_inputs_resolved: criticReview.executionInputsResolved,
+      plan_package_status: 'complete',
+      plan_docs_artifact_paths: docPaths,
+      plan_review_artifact_paths: reviewArtifactPaths,
+      plan_artifact_path: artifactPaths.planPath,
+      test_spec_artifact_path: artifactPaths.testSpecPath,
+      plan_source_spec_path: sourceSpecPath,
+      last_confirmed_transition: TRANSITIONS.CLARIFY_TO_PLAN,
+      approval: {
+        ...state.approval,
+        plan: APPROVAL_STATES.APPROVED,
+        build: APPROVAL_STATES.NOT_REQUESTED,
+        review: APPROVAL_STATES.NOT_REQUESTED,
+        rollback: APPROVAL_STATES.NOT_REQUESTED,
+        complete: APPROVAL_STATES.NOT_REQUESTED,
+      },
+    };
+
+    if (criticReview.verdict === 'approve') {
+      break;
+    }
+    iteration += 1;
   }
-  const { planPath, testSpecPath } = await writeCanonicalPlanArtifacts(cwd, root, normalized);
 
+  const completion = await readPlanCompletion(cwd, root, normalized, state);
   const next = withRecommendedAction({
     ...state,
     current_stage: STAGES.PLAN,
-    stage_status: 'awaiting-approval',
-    plan_package_status: 'complete',
+    stage_status: completion.blockers.length > 0 ? 'blocked' : 'awaiting-approval',
     pending_user_decision: TRANSITIONS.NONE,
     requested_transition: TRANSITIONS.NONE,
-    last_confirmed_transition: TRANSITIONS.CLARIFY_TO_PLAN,
-    approval: {
-      ...state.approval,
-      plan: APPROVAL_STATES.APPROVED,
-      build: APPROVAL_STATES.NOT_REQUESTED,
-      review: APPROVAL_STATES.NOT_REQUESTED,
-      rollback: APPROVAL_STATES.NOT_REQUESTED,
-      complete: APPROVAL_STATES.NOT_REQUESTED,
-    },
-    plan_artifact_path: planPath,
-    test_spec_artifact_path: testSpecPath,
+    plan_docs_status: completion.docsStatus,
+    plan_docs_artifact_paths: completion.docPaths,
+    plan_blockers: completion.blockers,
   });
   await writeState(root, next);
-  return { root, state: next };
+  return { root, state: next, architectReview, criticReview };
 }
 
-export async function buildStage(cwd, slug) {
+export async function buildStage(cwd, slug, options = {}) {
   const { root, state, slug: normalized } = await loadWorkflowState(cwd, slug, { allowLegacy: false });
   ensureApprovedTransition(state, TRANSITIONS.PLAN_TO_BUILD, 'build');
-  const runId = `${normalized}-build-draft`;
-  await writeText(artifactPath(root, 'execution-record.md'), executionRecordTemplate(normalized, STAGES.BUILD, `${normalized}-builder-1`, runId));
+  if (!PLAN_ARTIFACTS.every((name) => existsSync(artifactPath(root, name)))) {
+    throw new Error('build_requires_workflow_plan_artifacts');
+  }
+  if (!state.plan_artifact_path || !existsSync(state.plan_artifact_path) || !state.test_spec_artifact_path || !existsSync(state.test_spec_artifact_path)) {
+    throw new Error('build_requires_approved_plan_artifacts');
+  }
 
+  const adapter = options.adapter || createDefaultBuildAdapter();
+  const maxIterations = adapter.maxIterations || DEFAULT_BUILD_MAX_ITERATIONS;
+  const noDeslop = Boolean(options.noDeslop);
+  const progressArtifacts = [];
+  const supportArtifacts = [];
+  let iteration = 1;
+  let current = null;
+  let blockers = ['build_not_started'];
+
+  while (iteration <= maxIterations) {
+    current = await adapter.executeLanes({
+      cwd,
+      root,
+      slug: normalized,
+      iteration,
+      noDeslop,
+      planArtifactPath: state.plan_artifact_path,
+      testSpecArtifactPath: state.test_spec_artifact_path,
+    });
+    blockers = buildIterationBlockers(current, { noDeslop });
+    const supportPaths = await writeBuildSupportArtifacts(root, current, noDeslop);
+    progressArtifacts.push(supportPaths.laneSummary);
+    supportArtifacts.push(supportPaths.architect, supportPaths.deslop, supportPaths.regression);
+    await writeText(
+      artifactPath(root, 'execution-record.md'),
+      buildExecutionRecordContent({
+        slug: normalized,
+        iterationData: current,
+        complete: blockers.length === 0,
+      }),
+    );
+    if (blockers.length === 0) {
+      break;
+    }
+    iteration += 1;
+  }
+
+  const finalBlocked = blockers.length > 0;
+  const refreshed = await refreshExecutionStatus(root, state);
   const next = withRecommendedAction({
-    ...state,
+    ...refreshed.state,
     current_stage: STAGES.BUILD,
-    stage_status: 'blocked',
-    execution_record_status: 'partial',
-    review_status: 'pending-input',
-    active_run_id: runId,
-    pending_user_decision: TRANSITIONS.NONE,
+    stage_status: finalBlocked ? 'blocked' : 'awaiting-approval',
+    execution_record_status: finalBlocked ? 'partial' : refreshed.state.execution_record_status,
+    review_status: finalBlocked ? 'pending-input' : 'ready-for-review',
+    build_run_id: current?.runId || null,
+    build_current_iteration: current?.iteration || 0,
+    build_max_iterations: maxIterations,
+    build_parallel_mode: true,
+    build_lane_statuses: current?.lanes || [],
+    build_verification_status: current?.verificationStatus || 'pending',
+    build_architect_verification_status: current?.architectVerdict || 'not-started',
+    build_deslop_status: noDeslop ? 'skipped' : (current?.deslopStatus || 'pending'),
+    build_regression_status: noDeslop ? 'skipped' : (current?.regressionStatus || 'pending'),
+    build_blockers: blockers,
+    build_progress_artifact_paths: progressArtifacts,
+    build_support_evidence_paths: supportArtifacts,
+    build_no_deslop: noDeslop,
+    active_run_id: current?.runId || null,
+    pending_user_decision: finalBlocked ? TRANSITIONS.NONE : TRANSITIONS.BUILD_TO_REVIEW,
     requested_transition: TRANSITIONS.NONE,
     last_confirmed_transition: TRANSITIONS.PLAN_TO_BUILD,
     approval: {
@@ -828,98 +1462,171 @@ export async function reviewStage(cwd, slug, { reviewer = 'independent-reviewer'
   return { root, state: next, verdict: reviewInput.verdict, rollbackTarget: reviewInput.rollbackTarget };
 }
 
-export async function autopilotStage(cwd, slug, { reviewer = 'autopilot-reviewer' } = {}) {
+async function writeAutopilotRun(rootPath, payload) {
+  await ensureDir(dirname(rootPath));
+  await writeText(rootPath, JSON.stringify(payload, null, 2));
+}
+
+export async function autopilotStage(cwd, slug, { reviewer = 'autopilot-reviewer', phaseAdapter, planOptions = {}, buildOptions = {} } = {}) {
   const normalized = normalizeSlug(slug);
   const workflowRoot = resolveWorkflowRoot(cwd, normalized);
   if (!existsSync(statePath(workflowRoot))) {
     await clarifyStage(cwd, normalized);
   }
 
-  const { root } = await loadWorkflowState(cwd, normalized, { allowLegacy: false });
-  const spec = await readSpecSummary(root);
-  if (spec.unresolvedCount > 0) {
-    throw new Error('autopilot_requires_resolved_spec');
-  }
+  const { root, state: initialState } = await loadWorkflowState(cwd, normalized, { allowLegacy: false });
 
+  const adapter = phaseAdapter || createDefaultAutopilotAdapter();
+  const autopilotRoot = join(resolveWorkspaceRoot(cwd), 'autopilot', normalized);
+  const runPath = join(autopilotRoot, 'run.json');
   const controlEvents = [];
+  const phases = [];
   const recordEvent = (transition) => controlEvents.push({
     transition,
-    actor: 'loopx-autopilot',
+    actor: 'autopilot',
     recorded_at: nowIso(),
   });
+  const blockerKey = (value) => String(value).trim().toLowerCase().replace(/\s+/g, '-');
+  const artifacts = {
+    specPath: initialState.spec_artifact_path || artifactPath(root, 'spec.md'),
+    planPath: null,
+    testSpecPath: null,
+    executionRecordPath: artifactPath(root, 'execution-record.md'),
+    reviewReportPath: artifactPath(root, 'review-report.md'),
+  };
+
+  const updateWorkflowState = async (state, extras) => {
+    const next = withRecommendedAction({
+      ...state,
+      autopilot_current_phase: extras.currentPhase,
+      autopilot_phase_history: phases,
+      autopilot_blockers: extras.blockers || [],
+      autopilot_run_path: runPath,
+      autopilot_completed: Boolean(extras.completed),
+    });
+    await writeState(root, next);
+    return next;
+  };
+
+  const persistRun = async ({ currentPhase, completed, blockers = [], reviewedRunId = null, workflowState = null }) => {
+    await writeAutopilotRun(runPath, {
+      workflowId: normalized,
+      reviewer,
+      currentPhase,
+      phases,
+      controlEvents,
+      reviewedRunId,
+      artifacts,
+      blockers,
+      completed,
+    });
+    if (workflowState) {
+      await updateWorkflowState(workflowState, { currentPhase, blockers, completed });
+    }
+  };
+
+  const expansion = await adapter.expansion({
+    cwd,
+    slug: normalized,
+    root,
+    state: {
+      ...initialState,
+      cwd,
+      root,
+      slug: normalized,
+      unresolved_ambiguity_count: (await readSpecSummary(root)).unresolvedCount,
+    },
+  });
+  phases.push(expansion);
+  if (expansion.status !== 'complete') {
+    await persistRun({
+      currentPhase: 'expansion',
+      completed: false,
+      blockers: [`expansion_${expansion.status}`],
+      workflowState: initialState,
+    });
+    throw new Error(`autopilot_phase_blocked:expansion:${expansion.status}`);
+  }
+  const refreshedSpec = await readSpecSummary(root);
+  if (refreshedSpec.unresolvedCount > 0) {
+    await persistRun({
+      currentPhase: 'expansion',
+      completed: false,
+      blockers: ['expansion_unresolved_ambiguity'],
+      workflowState: initialState,
+    });
+    throw new Error('autopilot_requires_resolved_spec');
+  }
 
   await approveStage(cwd, normalized, { from: STAGES.CLARIFY, to: STAGES.PLAN });
   recordEvent(TRANSITIONS.CLARIFY_TO_PLAN);
-  await planStage(cwd, normalized);
+  const planned = await planStage(cwd, normalized, planOptions);
+  artifacts.planPath = planned.state.plan_artifact_path;
+  artifacts.testSpecPath = planned.state.test_spec_artifact_path;
+  const planning = await adapter.planning({ cwd, slug: normalized, root, planResult: planned });
+  phases.push(planning);
+  if (planning.status !== 'complete') {
+    await persistRun({
+      currentPhase: 'planning',
+      completed: false,
+      blockers: [`planning_${planning.status}`],
+      workflowState: planned.state,
+    });
+    throw new Error(`autopilot_phase_blocked:planning:${planning.status}`);
+  }
+
   await approveStage(cwd, normalized, { from: STAGES.PLAN, to: STAGES.BUILD });
   recordEvent(TRANSITIONS.PLAN_TO_BUILD);
-  const build = await buildStage(cwd, normalized);
-  await writeText(
-    artifactPath(build.root, 'execution-record.md'),
-    [
-      frontmatterBlock({
-        schema_version: WORKFLOW_SCHEMA_VERSION,
-        workflow_id: normalized,
-        run_id: `${normalized}-autopilot-run-1`,
-        stage: STAGES.BUILD,
-        actor_id: 'loopx-autopilot',
-        actor_role: 'autopilot',
-        plan_digest: `plan@${normalized}`,
-        started_at: nowIso(),
-        completed_at: nowIso(),
-        checkpoint_count: 3,
-        evidence_manifest: [
-          { id: `${normalized}-autopilot`, kind: 'command', summary: 'loopx autopilot executed', ref: `loopx autopilot ${normalized}` },
-          { id: `${normalized}-review`, kind: 'artifact', summary: 'review report generated', ref: 'review-report.md' },
-        ],
-      }),
-      `# LoopX Execution Record: ${normalized}`,
-      '',
-      '## Changes',
-      '',
-      '- LoopX autopilot completed one bounded build path.',
-      '',
-      '## Checkpoint Log',
-      '',
-      '- checkpoint 1: internal approvals recorded',
-      '- checkpoint 2: plan and build completed',
-      '- checkpoint 3: review requested',
-      '',
-      '## Execution Evidence',
-      '',
-      `- \`loopx autopilot ${normalized}\``,
-      '',
-      '## Verification Evidence',
-      '',
-      '- PASS: bounded autopilot composition completed',
-      '- PASS: review-ready evidence generated',
-      '',
-      '## Limitations',
-      '',
-      '- none',
-    ].join('\n'),
-  );
+      const build = await buildStage(cwd, normalized, buildOptions);
+  const execution = await adapter.execution({ cwd, slug: normalized, root, buildResult: build });
+  phases.push(execution);
+  if (execution.status !== 'complete') {
+    await persistRun({
+      currentPhase: 'execution',
+      completed: false,
+      blockers: [`execution_${execution.status}`, ...(build.state.build_blockers || [])],
+      workflowState: build.state,
+    });
+    throw new Error(`autopilot_phase_blocked:execution:${execution.status}`);
+  }
+  const qa = await adapter.qa({ cwd, slug: normalized, root, buildResult: build });
+  phases.push(qa);
+  if (qa.status !== 'complete') {
+    await persistRun({
+      currentPhase: 'qa',
+      completed: false,
+      blockers: [`qa_${qa.status}`, ...(build.state.build_blockers || [])],
+      workflowState: build.state,
+    });
+    throw new Error(`autopilot_phase_blocked:qa:${qa.status}`);
+  }
+
   await approveStage(cwd, normalized, { from: STAGES.BUILD, to: STAGES.REVIEW });
   recordEvent(TRANSITIONS.BUILD_TO_REVIEW);
   const review = await reviewStage(cwd, normalized, { reviewer });
-  if (review.verdict !== 'APPROVE') {
+  const validation = await adapter.validation({ cwd, slug: normalized, root, reviewResult: review });
+  phases.push(validation);
+  if (review.verdict !== 'APPROVE' || validation.status !== 'complete') {
+    await persistRun({
+      currentPhase: 'validation',
+      completed: false,
+      blockers: [`validation_${blockerKey(validation.status)}`, `review_${blockerKey(review.verdict)}`],
+      reviewedRunId: review.state.active_run_id || null,
+      workflowState: review.state,
+    });
     throw new Error('autopilot_review_failed');
   }
   await approveStage(cwd, normalized, { from: STAGES.REVIEW, to: STAGES.DONE });
   recordEvent(TRANSITIONS.REVIEW_TO_DONE);
   const done = await reviewStage(cwd, normalized, { reviewer });
-
-  const autopilotRoot = join(resolveWorkspaceRoot(cwd), 'autopilot', normalized);
-  await ensureDir(autopilotRoot);
-  await writeText(join(autopilotRoot, 'run.json'), JSON.stringify({
-    workflowId: normalized,
-    reviewer,
-    controlEvents,
-    reviewedRunId: `${normalized}-autopilot-run-1`,
+  await persistRun({
+    currentPhase: 'complete',
     completed: true,
-  }, null, 2));
-
-  return { root: done.root, state: done.state, runPath: join(autopilotRoot, 'run.json') };
+    reviewedRunId: done.state.active_run_id || build.state.build_run_id || null,
+    workflowState: done.state,
+  });
+  const finalState = await readState(cwd, normalized);
+  return { root: done.root, state: finalState ?? done.state, runPath };
 }
 
 async function listWorkflowSummaries(workflowsRoot) {