@ai-content-space/loopx 0.1.0

package/src/workflow.mjs

@@ -0,0 +1,1008 @@
+import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { ensureLoopXRoot, resolveLoopXRoot } from './runtime-maintenance.mjs';
+
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+const WORKSPACE_SCHEMA_VERSION = 1;
+const WORKFLOW_SCHEMA_VERSION = 1;
+
+export const STAGES = {
+  CLARIFY: 'clarify',
+  PLAN: 'plan',
+  BUILD: 'build',
+  REVIEW: 'review',
+  DONE: 'done',
+};
+
+export const APPROVAL_STATES = {
+  NOT_REQUESTED: 'not-requested',
+  REQUESTED: 'requested',
+  APPROVED: 'approved',
+  REJECTED: 'rejected',
+};
+
+export const TRANSITIONS = {
+  NONE: 'none',
+  CLARIFY_TO_PLAN: 'clarify->plan',
+  PLAN_TO_BUILD: 'plan->build',
+  BUILD_TO_REVIEW: 'build->review',
+  REVIEW_TO_PLAN: 'review->plan',
+  REVIEW_TO_DONE: 'review->done',
+};
+
+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'];
+
+function normalizeSlug(raw) {
+  const slug = String(raw || '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  if (!slug) {
+    throw new Error('workflow_slug_required');
+  }
+  return slug;
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function nowStamp() {
+  return nowIso().replace(/[-:]/g, '').replace(/\.\d{3}Z$/, 'Z');
+}
+
+function parseFrontmatter(text) {
+  if (!text.startsWith('---\n')) {
+    return {};
+  }
+  const end = text.indexOf('\n---\n', 4);
+  if (end === -1) {
+    return {};
+  }
+
+  const result = {};
+  for (const line of text.slice(4, end).split('\n')) {
+    if (!line || /^\s/.test(line)) {
+      continue;
+    }
+    const separator = line.indexOf(':');
+    if (separator === -1) {
+      continue;
+    }
+    const key = line.slice(0, separator).trim();
+    const rawValue = line.slice(separator + 1).trim();
+    if (rawValue === 'null') {
+      result[key] = null;
+      continue;
+    }
+    if (rawValue === 'true' || rawValue === 'false') {
+      result[key] = rawValue === 'true';
+      continue;
+    }
+    if (/^-?\d+$/.test(rawValue)) {
+      result[key] = Number.parseInt(rawValue, 10);
+      continue;
+    }
+    if (rawValue.startsWith('[') || rawValue.startsWith('{')) {
+      result[key] = JSON.parse(rawValue);
+      continue;
+    }
+    result[key] = rawValue;
+  }
+  return result;
+}
+
+function frontmatterBlock(values) {
+  const lines = ['---'];
+  for (const [key, value] of Object.entries(values)) {
+    if (Array.isArray(value) || (typeof value === 'object' && value !== null)) {
+      lines.push(`${key}: ${JSON.stringify(value)}`);
+    } else if (value === null) {
+      lines.push(`${key}: null`);
+    } else {
+      lines.push(`${key}: ${value}`);
+    }
+  }
+  lines.push('---', '');
+  return lines.join('\n');
+}
+
+function statePath(root) {
+  return join(root, 'state.json');
+}
+
+function workspaceConfigPath(root) {
+  return join(root, 'config.json');
+}
+
+function workspaceReadmePath(root) {
+  return join(root, 'README.md');
+}
+
+function artifactPath(root, name) {
+  return join(root, name);
+}
+
+async function ensureDir(path) {
+  await mkdir(path, { recursive: true });
+}
+
+async function readTemplate(name) {
+  return readFile(join(resolve(MODULE_DIR, '../templates'), name), 'utf8');
+}
+
+async function readTextIfExists(path) {
+  if (!existsSync(path)) {
+    return null;
+  }
+  return readFile(path, 'utf8');
+}
+
+async function writeText(path, text) {
+  await writeFile(path, `${text.replace(/\s+$/, '')}\n`);
+}
+
+async function writeState(root, state) {
+  await writeText(statePath(root), JSON.stringify(state, null, 2));
+}
+
+export function resolveWorkspaceRoot(cwd) {
+  return resolveLoopXRoot(cwd);
+}
+
+export function resolveWorkflowRoot(cwd, slug) {
+  return join(resolveWorkspaceRoot(cwd), 'workflows', normalizeSlug(slug));
+}
+
+function resolveSpecsRoot(cwd) {
+  return join(resolveWorkspaceRoot(cwd), 'specs');
+}
+
+function resolvePlansRoot(cwd) {
+  return join(resolveWorkspaceRoot(cwd), 'plans');
+}
+
+function canonicalClarifySpecPath(cwd, slug, stamp) {
+  return join(resolveSpecsRoot(cwd), `clarify-${normalizeSlug(slug)}-${stamp}.md`);
+}
+
+export async function readWorkspaceConfig(cwd) {
+  const path = workspaceConfigPath(resolveWorkspaceRoot(cwd));
+  if (!existsSync(path)) {
+    return null;
+  }
+  return JSON.parse(await readFile(path, 'utf8'));
+}
+
+export async function readState(cwd, slug) {
+  const path = statePath(resolveWorkflowRoot(cwd, slug));
+  if (!existsSync(path)) {
+    return null;
+  }
+  return JSON.parse(await readFile(path, 'utf8'));
+}
+
+function buildWorkspaceReadme() {
+  return [
+    '# LoopX Workspace',
+    '',
+    'This directory is initialized for the LoopX skill-first runtime contract.',
+    '',
+    '## Default Flow',
+    '',
+    '`clarify -> plan -> build -> review -> done`',
+    '',
+    '## Runtime Commands',
+    '',
+    '- `loopx init [--slug <slug>]`',
+    '- `loopx clarify <slug>`',
+    '- `loopx approve <slug> --from <stage> --to <stage>`',
+    '- `loopx plan <slug>`',
+    '- `loopx build <slug>`',
+    '- `loopx review <slug> [--reviewer <name>]`',
+    '- `loopx autopilot <slug> [--reviewer <name>]`',
+    '- `loopx status [slug] [--json]`',
+    '- `loopx doctor`',
+    '- `loopx migrate`',
+    '- `loopx repair-install`',
+  ].join('\n');
+}
+
+function createInitialState(slug) {
+  return {
+    schema_version: WORKFLOW_SCHEMA_VERSION,
+    slug,
+    current_stage: STAGES.CLARIFY,
+    stage_status: 'blocked',
+    ambiguity_items: [
+      {
+        id: 'A-1',
+        question: 'What specific task should LoopX execute in this workflow?',
+        status: 'open',
+        resolution: null,
+      },
+    ],
+    unresolved_ambiguity_count: 1,
+    plan_package_status: 'missing',
+    review_status: 'not-started',
+    recommended_next_action: 'Resolve ambiguity items in spec.md before requesting approval to enter plan.',
+    rollback_target: 'none',
+    rollback_rationale: null,
+    pending_user_decision: TRANSITIONS.NONE,
+    requested_transition: TRANSITIONS.NONE,
+    last_confirmed_transition: TRANSITIONS.NONE,
+    approval: {
+      plan: APPROVAL_STATES.NOT_REQUESTED,
+      build: APPROVAL_STATES.NOT_REQUESTED,
+      review: APPROVAL_STATES.NOT_REQUESTED,
+      rollback: APPROVAL_STATES.NOT_REQUESTED,
+      complete: APPROVAL_STATES.NOT_REQUESTED,
+    },
+    execution_record_status: 'missing',
+    review_verdict: 'none',
+    completion_confirmed: false,
+    active_run_id: null,
+    spec_artifact_path: null,
+    plan_artifact_path: null,
+    test_spec_artifact_path: null,
+  };
+}
+
+function detectLegacyContract(root, state) {
+  if (!state) {
+    return false;
+  }
+  if (!('schema_version' in state)) {
+    return true;
+  }
+  if (existsSync(artifactPath(root, 'brief.md')) && !existsSync(artifactPath(root, 'spec.md'))) {
+    return true;
+  }
+  if (existsSync(artifactPath(root, 'build-result.md')) && !existsSync(artifactPath(root, 'execution-record.md'))) {
+    return true;
+  }
+  return false;
+}
+
+function collectArtifactPresence(root, names) {
+  return Object.fromEntries(names.map((name) => [name, existsSync(artifactPath(root, name))]));
+}
+
+function withTemplateVariables(template, replacements) {
+  return Object.entries(replacements).reduce(
+    (content, [key, value]) => content.replaceAll(`<${key}>`, String(value)),
+    template,
+  );
+}
+
+async function writeTemplateArtifact(root, name, replacements) {
+  const template = await readTemplate(name);
+  await writeText(artifactPath(root, name), withTemplateVariables(template, replacements));
+}
+
+async function copyArtifact(fromRoot, toPath, name) {
+  await ensureDir(dirname(toPath));
+  const content = await readFile(artifactPath(fromRoot, name), 'utf8');
+  await writeText(toPath, content);
+}
+
+async function writeCanonicalPlanArtifacts(cwd, root, slug) {
+  const planPath = join(resolvePlansRoot(cwd), `prd-${slug}.md`);
+  const testSpecPath = join(resolvePlansRoot(cwd), `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');
+  const testPlanText = await readFile(artifactPath(root, 'test-plan.md'), 'utf8');
+
+  await writeText(
+    planPath,
+    [
+      `# LoopX PRD: ${slug}`,
+      '',
+      '## Plan',
+      '',
+      planText,
+      '',
+      '## Architecture',
+      '',
+      architectureText,
+      '',
+      '## Development Plan',
+      '',
+      developmentPlanText,
+    ].join('\n'),
+  );
+  await writeText(testSpecPath, testPlanText);
+  return { planPath, testSpecPath };
+}
+
+async function readSpecSummary(root) {
+  const text = await readTextIfExists(artifactPath(root, 'spec.md'));
+  if (!text) {
+    return { unresolvedCount: 1 };
+  }
+  const meta = parseFrontmatter(text);
+  const unresolvedCount = Number.parseInt(String(meta.unresolved_ambiguity_count ?? 1), 10);
+  return { unresolvedCount: Number.isNaN(unresolvedCount) ? 1 : unresolvedCount };
+}
+
+async function readExecutionRecordSummary(root) {
+  const text = await readTextIfExists(artifactPath(root, 'execution-record.md'));
+  if (!text) {
+    return { status: 'missing', meta: {} };
+  }
+  const meta = parseFrontmatter(text);
+  const hasRequiredMeta = [
+    'schema_version',
+    'workflow_id',
+    'run_id',
+    'stage',
+    'actor_id',
+    'actor_role',
+    'plan_digest',
+    'started_at',
+    'completed_at',
+    'checkpoint_count',
+    'evidence_manifest',
+  ].every((field) => meta[field] !== undefined && meta[field] !== null && meta[field] !== '');
+  const hasEvidenceManifest = Array.isArray(meta.evidence_manifest) && meta.evidence_manifest.length > 0;
+  const hasExecutionEvidence = /## Execution Evidence/i.test(text);
+  const hasVerificationEvidence = /## Verification Evidence/i.test(text);
+  const hasPlaceholder = /\bTODO\b|<[^>\n]+>/.test(text);
+  return {
+    status: hasRequiredMeta && hasEvidenceManifest && hasExecutionEvidence && hasVerificationEvidence && !hasPlaceholder ? 'complete' : 'partial',
+    meta,
+  };
+}
+
+function recommendedAction(state, legacy = false) {
+  if (legacy) {
+    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.';
+    case STAGES.PLAN:
+      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:
+      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.';
+    case STAGES.REVIEW:
+      if (state.review_verdict === 'approve') {
+        return state.approval.complete === APPROVAL_STATES.APPROVED
+          ? 'Run loopx review again to consume the approved review -> done transition.'
+          : 'Approve review -> done to complete the workflow.';
+      }
+      if (state.review_verdict === 'request-changes') {
+        return state.approval.rollback === APPROVAL_STATES.APPROVED
+          ? 'Run loopx review again to consume the approved review -> plan transition.'
+          : 'Approve review -> plan to roll back for another planning pass.';
+      }
+      return 'Run loopx review after build completes.';
+    case STAGES.DONE:
+      return 'Workflow is complete.';
+    default:
+      return 'Run loopx clarify to start a workflow.';
+  }
+}
+
+function withRecommendedAction(state, legacy = false) {
+  return {
+    ...state,
+    recommended_next_action: recommendedAction(state, legacy),
+  };
+}
+
+async function loadWorkflowState(cwd, slug, { allowLegacy = true } = {}) {
+  const normalized = normalizeSlug(slug);
+  const root = resolveWorkflowRoot(cwd, normalized);
+  const state = await readState(cwd, normalized);
+  if (!state) {
+    throw new Error('workflow_not_initialized');
+  }
+  const legacy = detectLegacyContract(root, state);
+  if (legacy && !allowLegacy) {
+    throw new Error('legacy_workflow_not_supported');
+  }
+  return { slug: normalized, root, legacy, state: withRecommendedAction(state, legacy) };
+}
+
+function transitionKey(from, to) {
+  const value = `${from}->${to}`;
+  if (!Object.values(TRANSITIONS).includes(value)) {
+    throw new Error(`invalid_transition:${value}`);
+  }
+  return value;
+}
+
+function approvalKeyForTransition(transition) {
+  switch (transition) {
+    case TRANSITIONS.CLARIFY_TO_PLAN:
+      return 'plan';
+    case TRANSITIONS.PLAN_TO_BUILD:
+      return 'build';
+    case TRANSITIONS.BUILD_TO_REVIEW:
+      return 'review';
+    case TRANSITIONS.REVIEW_TO_PLAN:
+      return 'rollback';
+    case TRANSITIONS.REVIEW_TO_DONE:
+      return 'complete';
+    default:
+      throw new Error(`approval_key_not_found:${transition}`);
+  }
+}
+
+function ensureApprovedTransition(state, expectedTransition, key) {
+  if (state.requested_transition !== expectedTransition || state.approval[key] !== APPROVAL_STATES.APPROVED) {
+    throw new Error(`approved_transition_required:${expectedTransition}`);
+  }
+}
+
+function executionRecordTemplate(slug, stage, actorId, runId) {
+  const timestamp = nowIso();
+  return [
+    frontmatterBlock({
+      schema_version: WORKFLOW_SCHEMA_VERSION,
+      workflow_id: slug,
+      run_id: runId,
+      stage,
+      actor_id: actorId,
+      actor_role: stage,
+      plan_digest: `plan@${slug}`,
+      started_at: timestamp,
+      completed_at: timestamp,
+      checkpoint_count: 0,
+      evidence_manifest: [],
+    }),
+    `# LoopX Execution Record: ${slug}`,
+    '',
+    '## Changes',
+    '',
+    '- TODO: summarize the implementation result.',
+    '',
+    '## Checkpoint Log',
+    '',
+    '- TODO: record execution checkpoints.',
+    '',
+    '## Execution Evidence',
+    '',
+    '- TODO: add concrete execution evidence.',
+    '',
+    '## Verification Evidence',
+    '',
+    '- TODO: add concrete verification evidence.',
+    '',
+    '## Limitations',
+    '',
+    '- TODO: record remaining limitations.',
+  ].join('\n');
+}
+
+function reviewReportContent({ slug, reviewer, runId, verdict, rollbackTarget, rollbackRationale, inputManifest, evidenceManifest, findings }) {
+  return [
+    frontmatterBlock({
+      schema_version: WORKFLOW_SCHEMA_VERSION,
+      workflow_id: slug,
+      review_id: `${slug}-review-${Date.now()}`,
+      reviewer_id: reviewer,
+      reviewed_run_id: runId,
+      input_manifest: inputManifest,
+      evidence_manifest: evidenceManifest,
+      verdict: verdict.toLowerCase().replace('request changes', 'request-changes'),
+      rollback_target: rollbackTarget,
+      rollback_rationale: rollbackRationale ?? null,
+    }),
+    `# LoopX Review Report: ${slug}`,
+    '',
+    '## Verdict',
+    '',
+    `- ${verdict}`,
+    '',
+    '## Evidence Reviewed',
+    '',
+    ...inputManifest.map((item) => `- ${item}`),
+    '',
+    '## Findings',
+    '',
+    ...findings.map((item) => `- ${item}`),
+    '',
+    '## Rollback Recommendation',
+    '',
+    `- ${rollbackTarget}`,
+    rollbackRationale ? `- ${rollbackRationale}` : '- none',
+  ].join('\n');
+}
+
+async function refreshExecutionStatus(root, state) {
+  const summary = await readExecutionRecordSummary(root);
+  return {
+    state: {
+      ...state,
+      execution_record_status: summary.status,
+    },
+    executionSummary: summary,
+  };
+}
+
+export async function initWorkspace(cwd, { slug } = {}) {
+  const workspaceRoot = resolveWorkspaceRoot(cwd);
+  await ensureLoopXRoot(cwd);
+  await ensureDir(join(workspaceRoot, 'context'));
+  await ensureDir(join(workspaceRoot, 'workflows'));
+  await ensureDir(join(workspaceRoot, 'specs'));
+  await ensureDir(join(workspaceRoot, 'plans'));
+  await ensureDir(join(workspaceRoot, 'autopilot'));
+
+  const config = {
+    schema_version: WORKSPACE_SCHEMA_VERSION,
+    tool: 'LoopX',
+    product_contract: 'skill-first-v1',
+    default_flow: ['clarify', 'plan', 'build', 'review', 'done'],
+    preferred_surface: ['clarify', 'plan', 'build', 'review', 'autopilot'],
+  };
+
+  if (!existsSync(workspaceConfigPath(workspaceRoot))) {
+    await writeText(workspaceConfigPath(workspaceRoot), JSON.stringify(config, null, 2));
+  }
+  if (!existsSync(workspaceReadmePath(workspaceRoot))) {
+    await writeText(workspaceReadmePath(workspaceRoot), buildWorkspaceReadme());
+  }
+
+  let workflow = null;
+  if (slug) {
+    workflow = await clarifyStage(cwd, slug);
+  }
+  return { workspaceRoot, config, workflow };
+}
+
+export async function clarifyStage(cwd, slug) {
+  const normalized = normalizeSlug(slug);
+  const root = resolveWorkflowRoot(cwd, normalized);
+  await ensureLoopXRoot(cwd);
+  await ensureDir(root);
+  const stamp = nowStamp();
+  await writeTemplateArtifact(root, 'spec.md', {
+    'task name': normalized,
+    'workflow id': normalized,
+  });
+  const specArtifactPath = canonicalClarifySpecPath(cwd, normalized, stamp);
+  await copyArtifact(root, specArtifactPath, 'spec.md');
+  const state = withRecommendedAction({
+    ...createInitialState(normalized),
+    spec_artifact_path: specArtifactPath,
+  });
+  await writeState(root, state);
+  return { root, state };
+}
+
+export async function approveStage(cwd, slug, { from, to }) {
+  const { root, state } = await loadWorkflowState(cwd, slug, { allowLegacy: false });
+  if (state.current_stage !== from) {
+    throw new Error(`approval_from_stage_mismatch:${from}`);
+  }
+  const transition = transitionKey(from, to);
+  const approvalKey = approvalKeyForTransition(transition);
+  let next = { ...state };
+
+  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');
+    }
+  }
+
+  if (transition === TRANSITIONS.PLAN_TO_BUILD) {
+    if (!PLAN_ARTIFACTS.every((name) => existsSync(artifactPath(root, name)))) {
+      throw new Error('plan_package_incomplete');
+    }
+    next.plan_package_status = 'complete';
+  }
+
+  if (transition === TRANSITIONS.BUILD_TO_REVIEW) {
+    const refreshed = await refreshExecutionStatus(root, state);
+    next = refreshed.state;
+    if (next.execution_record_status !== 'complete') {
+      throw new Error('review_gate_blocked:execution-record.md');
+    }
+  }
+
+  if (transition === TRANSITIONS.REVIEW_TO_PLAN) {
+    if (!next.rollback_rationale) {
+      throw new Error('rollback_rationale_required');
+    }
+  }
+
+  if (transition === TRANSITIONS.REVIEW_TO_DONE && next.review_verdict !== 'approve') {
+    throw new Error('review_not_approved');
+  }
+
+  next = withRecommendedAction({
+    ...next,
+    stage_status: 'awaiting-approval',
+    pending_user_decision: TRANSITIONS.NONE,
+    requested_transition: transition,
+    approval: {
+      ...next.approval,
+      [approvalKey]: APPROVAL_STATES.APPROVED,
+    },
+  });
+  await writeState(root, next);
+  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,
+    });
+  }
+  const { planPath, testSpecPath } = await writeCanonicalPlanArtifacts(cwd, root, normalized);
+
+  const next = withRecommendedAction({
+    ...state,
+    current_stage: STAGES.PLAN,
+    stage_status: 'awaiting-approval',
+    plan_package_status: 'complete',
+    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,
+  });
+  await writeState(root, next);
+  return { root, state: next };
+}
+
+export async function buildStage(cwd, slug) {
+  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));
+
+  const next = withRecommendedAction({
+    ...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,
+    requested_transition: TRANSITIONS.NONE,
+    last_confirmed_transition: TRANSITIONS.PLAN_TO_BUILD,
+    approval: {
+      ...state.approval,
+      build: APPROVAL_STATES.APPROVED,
+      review: APPROVAL_STATES.NOT_REQUESTED,
+      rollback: APPROVAL_STATES.NOT_REQUESTED,
+      complete: APPROVAL_STATES.NOT_REQUESTED,
+    },
+  });
+  await writeState(root, next);
+  return { root, state: next };
+}
+
+function reviewFindings({ executionMeta, executionStatus, reviewer }) {
+  const inputManifest = ['spec.md', ...PLAN_ARTIFACTS, 'execution-record.md'];
+  const evidenceManifest = Array.isArray(executionMeta.evidence_manifest) ? [...executionMeta.evidence_manifest] : [];
+  const findings = [];
+  let verdict = 'APPROVE';
+  let rollbackTarget = 'none';
+  let rollbackRationale = null;
+
+  if (executionStatus !== 'complete') {
+    findings.push('execution-record.md is missing required execution or verification evidence.');
+    verdict = 'REQUEST CHANGES';
+    rollbackTarget = 'plan';
+    rollbackRationale = 'Execution evidence is incomplete, so the workflow must return to planning before another run.';
+  }
+  if (!Array.isArray(executionMeta.evidence_manifest) || executionMeta.evidence_manifest.length === 0) {
+    findings.push('execution-record.md is missing the required evidence_manifest schema.');
+    verdict = 'REQUEST CHANGES';
+    rollbackTarget = 'plan';
+    rollbackRationale = 'Execution evidence schema is incomplete, so review cannot accept the run.';
+  }
+  if (executionMeta.actor_id === reviewer) {
+    findings.push('Reviewer provenance matches the execution actor and is not independent.');
+    verdict = 'REQUEST CHANGES';
+    rollbackTarget = 'plan';
+    rollbackRationale = 'Review independence failed because reviewer provenance matches the execution actor.';
+  }
+
+  return {
+    verdict,
+    findings: findings.length > 0 ? findings : ['Structured evidence and provenance checks passed.'],
+    inputManifest,
+    evidenceManifest,
+    rollbackTarget,
+    rollbackRationale,
+  };
+}
+
+export async function reviewStage(cwd, slug, { reviewer = 'independent-reviewer' } = {}) {
+  const { root, state, slug: normalized } = await loadWorkflowState(cwd, slug, { allowLegacy: false });
+
+  if (state.current_stage === STAGES.REVIEW && state.approval.complete === APPROVAL_STATES.APPROVED && state.review_verdict === 'approve') {
+    const next = withRecommendedAction({
+      ...state,
+      current_stage: STAGES.DONE,
+      stage_status: 'completed',
+      pending_user_decision: TRANSITIONS.NONE,
+      requested_transition: TRANSITIONS.NONE,
+      last_confirmed_transition: TRANSITIONS.REVIEW_TO_DONE,
+      completion_confirmed: true,
+    });
+    await writeState(root, next);
+    return { root, state: next, verdict: 'APPROVE', rollbackTarget: 'none' };
+  }
+
+  if (state.current_stage === STAGES.REVIEW && state.approval.rollback === APPROVAL_STATES.APPROVED && state.review_verdict === 'request-changes') {
+    const next = withRecommendedAction({
+      ...state,
+      current_stage: STAGES.PLAN,
+      stage_status: 'awaiting-approval',
+      pending_user_decision: TRANSITIONS.NONE,
+      requested_transition: TRANSITIONS.NONE,
+      last_confirmed_transition: TRANSITIONS.REVIEW_TO_PLAN,
+      plan_package_status: 'complete',
+      approval: {
+        ...state.approval,
+        build: APPROVAL_STATES.NOT_REQUESTED,
+        review: APPROVAL_STATES.NOT_REQUESTED,
+        rollback: APPROVAL_STATES.APPROVED,
+      },
+    });
+    await writeState(root, next);
+    return { root, state: next, verdict: 'REQUEST CHANGES', rollbackTarget: 'plan' };
+  }
+
+  ensureApprovedTransition(state, TRANSITIONS.BUILD_TO_REVIEW, 'review');
+  const { state: refreshed, executionSummary } = await refreshExecutionStatus(root, state);
+  const reviewInput = reviewFindings({
+    executionMeta: executionSummary.meta,
+    executionStatus: refreshed.execution_record_status,
+    reviewer,
+  });
+  const runId = executionSummary.meta.run_id || refreshed.active_run_id || `${normalized}-unknown-run`;
+
+  await writeText(
+    artifactPath(root, 'review-report.md'),
+    reviewReportContent({
+      slug: normalized,
+      reviewer,
+      runId,
+      verdict: reviewInput.verdict,
+      rollbackTarget: reviewInput.rollbackTarget,
+      rollbackRationale: reviewInput.rollbackRationale,
+      inputManifest: reviewInput.inputManifest,
+      evidenceManifest: reviewInput.evidenceManifest,
+      findings: reviewInput.findings,
+    }),
+  );
+
+  const next = withRecommendedAction({
+    ...refreshed,
+    current_stage: STAGES.REVIEW,
+    stage_status: 'awaiting-approval',
+    review_status: 'in-review',
+    pending_user_decision: reviewInput.verdict === 'APPROVE' ? TRANSITIONS.REVIEW_TO_DONE : TRANSITIONS.REVIEW_TO_PLAN,
+    requested_transition: TRANSITIONS.NONE,
+    last_confirmed_transition: TRANSITIONS.BUILD_TO_REVIEW,
+    review_verdict: reviewInput.verdict === 'APPROVE' ? 'approve' : 'request-changes',
+    rollback_target: reviewInput.rollbackTarget,
+    rollback_rationale: reviewInput.rollbackRationale,
+    approval: {
+      ...refreshed.approval,
+      review: APPROVAL_STATES.APPROVED,
+      rollback: reviewInput.verdict === 'APPROVE' ? APPROVAL_STATES.NOT_REQUESTED : APPROVAL_STATES.REQUESTED,
+      complete: reviewInput.verdict === 'APPROVE' ? APPROVAL_STATES.REQUESTED : APPROVAL_STATES.NOT_REQUESTED,
+    },
+  });
+  await writeState(root, next);
+  return { root, state: next, verdict: reviewInput.verdict, rollbackTarget: reviewInput.rollbackTarget };
+}
+
+export async function autopilotStage(cwd, slug, { reviewer = 'autopilot-reviewer' } = {}) {
+  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 controlEvents = [];
+  const recordEvent = (transition) => controlEvents.push({
+    transition,
+    actor: 'loopx-autopilot',
+    recorded_at: nowIso(),
+  });
+
+  await approveStage(cwd, normalized, { from: STAGES.CLARIFY, to: STAGES.PLAN });
+  recordEvent(TRANSITIONS.CLARIFY_TO_PLAN);
+  await planStage(cwd, normalized);
+  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'),
+  );
+  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') {
+    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`,
+    completed: true,
+  }, null, 2));
+
+  return { root: done.root, state: done.state, runPath: join(autopilotRoot, 'run.json') };
+}
+
+async function listWorkflowSummaries(workflowsRoot) {
+  if (!existsSync(workflowsRoot)) {
+    return [];
+  }
+  const entries = await readdir(workflowsRoot, { withFileTypes: true });
+  const workflows = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+    const slug = entry.name;
+    const root = join(workflowsRoot, slug);
+    const state = existsSync(statePath(root)) ? JSON.parse(await readFile(statePath(root), 'utf8')) : null;
+    const legacy = detectLegacyContract(root, state);
+    const artifacts = collectArtifactPresence(root, legacy ? LEGACY_ARTIFACTS : V1_ARTIFACTS);
+    workflows.push({
+      slug,
+      current_stage: state?.current_stage ?? null,
+      contract: legacy ? 'legacy-codex-helper' : 'loopx-v1',
+      legacy,
+      schema_version: state?.schema_version ?? 0,
+      requested_transition: state?.requested_transition ?? TRANSITIONS.NONE,
+      last_confirmed_transition: state?.last_confirmed_transition ?? TRANSITIONS.NONE,
+      missing_artifact_count: Object.values(artifacts).filter((present) => !present).length,
+    });
+  }
+  return workflows.sort((left, right) => left.slug.localeCompare(right.slug));
+}
+
+function summarizeWorkspace(workflows) {
+  return workflows.reduce((summary, workflow) => {
+    summary.total += 1;
+    summary.by_stage[workflow.current_stage ?? 'unknown'] = (summary.by_stage[workflow.current_stage ?? 'unknown'] || 0) + 1;
+    if (workflow.legacy) {
+      summary.legacy += 1;
+    }
+    return summary;
+  }, {
+    total: 0,
+    legacy: 0,
+    by_stage: {},
+  });
+}
+
+export async function statusSummary(cwd, slug) {
+  const workspaceRoot = resolveWorkspaceRoot(cwd);
+  const initialized = existsSync(workspaceRoot);
+  const config = await readWorkspaceConfig(cwd);
+  const workflowsRoot = join(workspaceRoot, 'workflows');
+
+  if (!slug) {
+    const workflows = await listWorkflowSummaries(workflowsRoot);
+    return {
+      initialized,
+      workspaceRoot,
+      config,
+      workflows,
+      workflow_count: workflows.length,
+      summary: summarizeWorkspace(workflows),
+      next_action: initialized ? 'Run loopx clarify <slug> to start a workflow, or inspect one with loopx status <slug>.' : 'Run loopx init to prepare the workspace.',
+    };
+  }
+
+  const normalized = normalizeSlug(slug);
+  const root = resolveWorkflowRoot(cwd, normalized);
+  const state = await readState(cwd, normalized);
+  const legacy = detectLegacyContract(root, state);
+  const artifacts = collectArtifactPresence(root, legacy ? LEGACY_ARTIFACTS : V1_ARTIFACTS);
+  const missing = Object.entries(artifacts).filter(([, present]) => !present).map(([name]) => name);
+  return {
+    initialized,
+    workspaceRoot,
+    config,
+    slug: normalized,
+    root,
+    state: state ? withRecommendedAction(state, legacy) : null,
+    legacy,
+    contract: legacy ? 'legacy-codex-helper' : 'loopx-v1',
+    schema_version: state?.schema_version ?? 0,
+    artifacts,
+    missing_artifacts: missing,
+    next_action: state ? recommendedAction(state, legacy) : 'Run loopx clarify to start a workflow.',
+  };
+}