cc-devflow 4.2.0 → 4.4.1

package/lib/skill-runtime/intent.js

@@ -0,0 +1,333 @@
+/**
+ * [INPUT]: 依赖 store 的路径与文件读写能力，依赖 change-state/task-manifest/report-card/checkpoint 作为 durable truth。
+ * [OUTPUT]: 对外提供 handoff 级工件生成与 legacy artifact 清理能力。
+ * [POS]: skill runtime 的薄 handoff 层，只保留终态交付文件，不再投影中间态 Markdown。
+ * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+ */
+
+const {
+  nowIso,
+  exists,
+  readJson,
+  writeText,
+  removePath,
+  getRuntimeStatePath,
+  getTaskManifestPath,
+  getReportCardPath,
+  getCheckpointPath,
+  getReleaseNotePath
+} = require('./store');
+const {
+  deriveLifecycleStage,
+  summarizeTaskStates,
+  getApprovalState,
+  deriveLifecycleNextAction,
+  isTaskSettledStatus
+} = require('./lifecycle');
+const {
+  getChangePaths
+} = require('./paths');
+const {
+  getIntentResumeIndexPath,
+  getIntentPrBriefPath,
+  getIntentHandoffArtifactPaths,
+  getLegacyIntentProjectionPaths,
+  ensureIntentScaffold
+} = require('./artifacts');
+
+function formatList(items, empty = '- None') {
+  if (!items || items.length === 0) {
+    return empty;
+  }
+
+  return items.map((item) => `- ${item}`).join('\n');
+}
+
+function truncateLine(value, max = 120) {
+  const normalized = String(value || '').replace(/\s+/g, ' ').trim();
+  if (normalized.length <= max) {
+    return normalized;
+  }
+
+  return `${normalized.slice(0, max - 3).trimEnd()}...`;
+}
+
+function suggestPrTitle(changeId, goal) {
+  const prefix = changeId.startsWith('FIX-') ? 'fix' : 'feat';
+  return `${prefix}(${changeId.toLowerCase()}): ${truncateLine(goal || changeId, 72)}`;
+}
+
+function summarizeGateSection(gates = []) {
+  if (!gates.length) {
+    return ['- None'];
+  }
+
+  return gates.map((gate) => {
+    const duration = typeof gate.durationMs === 'number' ? `${gate.durationMs}ms` : 'n/a';
+    return `- ${gate.name}: ${gate.status} (${duration}) via \`${gate.command}\``;
+  });
+}
+
+async function readLatestCheckpoints(repoRoot, changeId, tasks = []) {
+  const checkpoints = [];
+
+  for (const task of tasks) {
+    const checkpoint = await readJson(getCheckpointPath(repoRoot, changeId, task.id), null);
+    if (!checkpoint) {
+      continue;
+    }
+
+    checkpoints.push({
+      taskId: task.id,
+      title: task.title,
+      status: checkpoint.status,
+      timestamp: checkpoint.timestamp,
+      summary: checkpoint.summary
+    });
+  }
+
+  checkpoints.sort((left, right) => right.timestamp.localeCompare(left.timestamp));
+  return checkpoints;
+}
+
+async function cleanupLegacyArtifacts(repoRoot, changeId, manifest) {
+  const taskIds = (manifest?.tasks || []).map((task) => task.id);
+  const change = getChangePaths(repoRoot, changeId);
+
+  await Promise.all(
+    getLegacyIntentProjectionPaths(repoRoot, changeId, taskIds).map((target) => removePath(target))
+  );
+  await removePath(change.workersDir);
+}
+
+async function clearHandoffArtifacts(repoRoot, changeId, keep = null) {
+  await Promise.all(
+    getIntentHandoffArtifactPaths(repoRoot, changeId)
+      .filter((target) => target !== keep)
+      .map((target) => removePath(target))
+  );
+}
+
+async function writeResumeIndex(repoRoot, changeId, state, manifest, report) {
+  await ensureIntentScaffold(repoRoot, changeId);
+
+  const checkpoints = await readLatestCheckpoints(repoRoot, changeId, manifest?.tasks || []);
+  const lastGoodCheckpoint = checkpoints.find((checkpoint) => checkpoint.status === 'passed') || checkpoints[0] || null;
+  const blockers = [
+    ...(manifest?.tasks || [])
+      .filter((task) => task.status === 'failed')
+      .map((task) => `${task.id}: ${task.lastError || 'Task failed'}`),
+    ...(report?.blockingFindings || [])
+  ];
+  const hasPrBrief = await exists(getIntentPrBriefPath(repoRoot, changeId));
+  const hasReleaseNote = await exists(getReleaseNotePath(repoRoot, changeId));
+  const stage = deriveLifecycleStage({ state, manifest, report, hasPrBrief });
+  const approval = getApprovalState(state, manifest);
+  const goal = manifest?.goal || state?.goal || changeId;
+  const nextAction = deriveLifecycleNextAction({
+    state,
+    manifest,
+    report,
+    hasPrBrief,
+    hasReleaseNote
+  });
+  const resumePath = getIntentResumeIndexPath(repoRoot, changeId);
+
+  const content = [
+    `# Resume Index: ${changeId}`,
+    '',
+    `- Goal: ${goal}`,
+    `- Stage: \`${stage}\``,
+    `- Lifecycle: \`${state?.status || 'unknown'}\``,
+    `- Approval: \`${approval.status}\``,
+    `- Execution Mode: \`${approval.executionMode}\``,
+    `- Plan Version: ${manifest?.metadata?.planVersion || 1}`,
+    `- Updated At: ${nowIso()}`,
+    '',
+    '## Last Good Checkpoint',
+    '',
+    lastGoodCheckpoint
+      ? `- \`${lastGoodCheckpoint.taskId}\` ${lastGoodCheckpoint.status} @ ${lastGoodCheckpoint.timestamp} - ${lastGoodCheckpoint.summary}`
+      : '- No checkpoint yet',
+    '',
+    '## Blockers',
+    '',
+    formatList(blockers, '- None'),
+    '',
+    '## Next Action',
+    '',
+    nextAction,
+    '',
+    '## Durable Truth',
+    '',
+    formatList([
+      `\`devflow/changes/<change>/meta/change-state.json\``,
+      `\`devflow/changes/<change>/planning/task-manifest.json\``,
+      `\`devflow/changes/<change>/review/report-card.json\``
+    ])
+  ].join('\n');
+
+  await clearHandoffArtifacts(repoRoot, changeId, resumePath);
+  await writeText(resumePath, `${content}\n`);
+
+  return {
+    goalId: changeId,
+    resumePath
+  };
+}
+
+async function syncIntentPrBrief(repoRoot, changeId) {
+  await ensureIntentScaffold(repoRoot, changeId);
+
+  const [state, manifest, report] = await Promise.all([
+    readJson(getRuntimeStatePath(repoRoot, changeId), null),
+    readJson(getTaskManifestPath(repoRoot, changeId), null),
+    readJson(getReportCardPath(repoRoot, changeId), null)
+  ]);
+
+  if (!manifest) {
+    throw new Error(`Cannot prepare PR brief for ${changeId}: task-manifest.json is missing`);
+  }
+
+  if (!report) {
+    throw new Error(`Cannot prepare PR brief for ${changeId}: report-card.json is missing`);
+  }
+
+  if (report.overall !== 'pass') {
+    throw new Error(`Cannot prepare PR brief for ${changeId}: verification has not passed`);
+  }
+
+  await cleanupLegacyArtifacts(repoRoot, changeId, manifest);
+
+  const goal = manifest.goal || state?.goal || changeId;
+  const summary = summarizeTaskStates(manifest.tasks || []);
+  const touchedFiles = [...new Set((manifest.tasks || []).flatMap((task) => task.touches || []))];
+  const skippedTasks = (manifest.tasks || []).filter((task) => task.status === 'skipped');
+  const checkpointRefs = (manifest.tasks || [])
+    .filter((task) => isTaskSettledStatus(task.status))
+    .map((task) => `\`${task.id}\` ${task.title} -> \`devflow/changes/<change>/execution/tasks/${task.id}/checkpoint.json\``);
+
+  const risks = [
+    ...((report.review?.status === 'skipped' || report.review?.status === 'blocked')
+      ? ['评审门未完全闭环，合并前需要补齐 review 证据。']
+      : []),
+    ...(skippedTasks.length > 0
+      ? [`存在 ${skippedTasks.length} 个 skipped 任务，需要确认是否可接受：${skippedTasks.map((task) => task.id).join(', ')}`]
+      : []),
+    ...(summary.failed > 0
+      ? [`manifest 中仍有 ${summary.failed} 个 failed 任务，PR 前需要重新确认状态一致性。`]
+      : []),
+    ...(report.blockingFindings || [])
+  ];
+
+  const content = [
+    `# PR Brief: ${changeId}`,
+    '',
+    `- Suggested Title: ${suggestPrTitle(changeId, goal)}`,
+    `- Goal: ${goal}`,
+    `- Lifecycle: \`${state?.status || 'verified'}\``,
+    `- Prepared At: ${nowIso()}`,
+    '',
+    '## Summary',
+    '',
+    formatList(
+      (manifest.tasks || [])
+        .filter((task) => task.status === 'passed')
+        .map((task) => `\`${task.id}\` ${task.title}`),
+      '- No passed tasks'
+    ),
+    '',
+    '## Verification',
+    '',
+    `- Verdict: \`${report.verdict || (report.overall === 'pass' ? 'pass' : 'fail')}\``,
+    `- Overall: \`${report.overall}\``,
+    `- Review: \`${report.review?.status || 'skipped'}\``,
+    `- Blocking Findings: ${(report.blockingFindings || []).length}`,
+    '',
+    '### Quick Gates',
+    '',
+    ...summarizeGateSection(report.quickGates),
+    '',
+    '### Strict Gates',
+    '',
+    ...summarizeGateSection(report.strictGates),
+    '',
+    '### Review Summary',
+    '',
+    report.review?.summary || '- None',
+    '',
+    '## Risks',
+    '',
+    formatList(risks, '- None captured by verify; remaining risk is merge timing and manual product acceptance.'),
+    '',
+    '## Rollback',
+    '',
+    formatList([
+      '回滚该变更分支或最终提交栈，然后重新执行 cc-check 的验证命令。',
+      touchedFiles.length > 0
+        ? `优先检查这些触达文件：${touchedFiles.slice(0, 8).map((file) => `\`${file}\``).join(', ')}${touchedFiles.length > 8 ? ' ...' : ''}`
+        : '当前 manifest 未记录触达文件，回滚时以最终 diff 为准。'
+    ]),
+    '',
+    '## Key Artifacts',
+    '',
+    formatList([
+      `\`devflow/changes/<change>/meta/change-state.json\``,
+      `\`devflow/changes/<change>/planning/task-manifest.json\``,
+      `\`devflow/changes/<change>/review/report-card.json\``,
+      ...checkpointRefs
+    ]),
+    ''
+  ].join('\n');
+
+  const prBriefPath = getIntentPrBriefPath(repoRoot, changeId);
+  await clearHandoffArtifacts(repoRoot, changeId, prBriefPath);
+  await writeText(prBriefPath, `${content}\n`);
+
+  return {
+    goalId: changeId,
+    prBriefPath,
+    suggestedTitle: suggestPrTitle(changeId, goal)
+  };
+}
+
+async function syncIntentMemory(repoRoot, changeId, options = {}) {
+  await ensureIntentScaffold(repoRoot, changeId);
+
+  const [state, manifest, report] = await Promise.all([
+    readJson(getRuntimeStatePath(repoRoot, changeId), null),
+    readJson(getTaskManifestPath(repoRoot, changeId), null),
+    readJson(getReportCardPath(repoRoot, changeId), null)
+  ]);
+
+  await cleanupLegacyArtifacts(repoRoot, changeId, manifest);
+
+  if (options.handoff === 'resume') {
+    return writeResumeIndex(repoRoot, changeId, state, manifest, report);
+  }
+
+  const prBriefPath = getIntentPrBriefPath(repoRoot, changeId);
+  const releaseNotePath = getReleaseNotePath(repoRoot, changeId);
+  const hasPrBrief = await exists(prBriefPath);
+  const hasReleaseNote = await exists(releaseNotePath);
+  const stage = deriveLifecycleStage({ state, manifest, report, hasPrBrief });
+
+  if (hasReleaseNote) {
+    await clearHandoffArtifacts(repoRoot, changeId, releaseNotePath);
+  } else if (hasPrBrief) {
+    await clearHandoffArtifacts(repoRoot, changeId, prBriefPath);
+  } else {
+    await clearHandoffArtifacts(repoRoot, changeId, null);
+  }
+
+  return {
+    goalId: changeId,
+    stage,
+    resumePath: hasPrBrief || hasReleaseNote ? null : getIntentResumeIndexPath(repoRoot, changeId)
+  };
+}
+
+module.exports = {
+  syncIntentPrBrief,
+  syncIntentMemory
+};

package/lib/skill-runtime/lifecycle.js

@@ -0,0 +1,294 @@
+/**
+ * [INPUT]: 依赖 harness-state/task-manifest/report-card 的内存对象，接收 stage 名与任务元数据。
+ * [OUTPUT]: 对外提供 lifecycle 阶段判定、approval 解析、下一步动作建议、执行模式归一化与 direct/delegate/team 路由决策。
+ * [POS]: skill runtime 的共享生命周期语义层，让 query/intent/autopilot/dispatch 使用同一套运行时词汇与阶段建议。
+ * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+ */
+
+const STAGE_ORDER = [
+  'discover',
+  'converge',
+  'approve',
+  'delegate',
+  'execute',
+  'verify',
+  'document',
+  'prepare-pr',
+  'released'
+];
+
+function normalizeStage(stage) {
+  if (!stage) {
+    return null;
+  }
+
+  const aliases = {
+    init: 'discover',
+    snapshot: 'discover',
+    plan: 'converge',
+    approval: 'approve',
+    approved: 'approve',
+    'awaiting-approval': 'approve',
+    awaiting_approval: 'approve',
+    spec: 'converge',
+    dispatch: 'execute',
+    resume: 'execute',
+    release: 'prepare-pr'
+  };
+
+  return aliases[stage] || stage;
+}
+
+function stageIndex(stage) {
+  const normalized = normalizeStage(stage);
+  if (!normalized) {
+    return 0;
+  }
+
+  const index = STAGE_ORDER.indexOf(normalized);
+  if (index === -1) {
+    throw new Error(`Unknown autopilot stage: ${stage}`);
+  }
+
+  return index;
+}
+
+function normalizeExecutionMode(mode) {
+  if (['direct', 'delegate', 'team'].includes(mode)) {
+    return mode;
+  }
+
+  return 'delegate';
+}
+
+function normalizeTaskStatus(status) {
+  const aliases = {
+    completed: 'passed',
+    done: 'passed',
+    verified: 'passed'
+  };
+
+  return aliases[status] || status || 'pending';
+}
+
+function isTaskCompletedStatus(status) {
+  return normalizeTaskStatus(status) === 'passed';
+}
+
+function isTaskSettledStatus(status) {
+  return isTaskCompletedStatus(status) || status === 'skipped';
+}
+
+function summarizeTaskStates(tasks = []) {
+  return tasks.reduce(
+    (acc, task) => {
+      const normalizedStatus = normalizeTaskStatus(task.status);
+      acc[normalizedStatus] = (acc[normalizedStatus] || 0) + 1;
+      return acc;
+    },
+    { pending: 0, running: 0, passed: 0, failed: 0, skipped: 0 }
+  );
+}
+
+function deriveTaskProgress(tasks = []) {
+  const summary = summarizeTaskStates(tasks);
+
+  return {
+    totalTasks: tasks.length,
+    completedTasks: summary.passed,
+    failedTasks: summary.failed,
+    pendingTasks: summary.pending,
+    runningTasks: summary.running,
+    skippedTasks: summary.skipped
+  };
+}
+
+function listTaskIdsByStatus(tasks = [], status) {
+  return tasks
+    .filter((task) => task.status === status)
+    .map((task) => task.id);
+}
+
+function getApprovalState(state, manifest = null) {
+  const currentPlanVersion = manifest?.metadata?.planVersion || state?.approval?.planVersion || null;
+  const executionMode = normalizeExecutionMode(state?.approval?.executionMode);
+  const approvedPlanVersion = state?.approval?.planVersion || null;
+  const approved = Boolean(
+    currentPlanVersion &&
+    state?.approval?.status === 'approved' &&
+    approvedPlanVersion === currentPlanVersion
+  );
+
+  return {
+    status: approved ? 'approved' : 'pending',
+    executionMode,
+    planVersion: currentPlanVersion,
+    approvedPlanVersion,
+    approvedAt: approved ? state?.approval?.approvedAt || null : null
+  };
+}
+
+function isExecutionApproved(state, manifest) {
+  return getApprovalState(state, manifest).status === 'approved';
+}
+
+function classifyDelegationMode(task, options = {}) {
+  const commandCount = (task.run || []).length + (task.checks || []).length;
+  const executionMode = normalizeExecutionMode(
+    options.executionMode || options.approval?.executionMode || options.state?.approval?.executionMode
+  );
+  const teamCandidate = (task.touches || []).length >= 4 || (task.dependsOn || []).length >= 3;
+
+  if (executionMode === 'direct') {
+    return 'direct';
+  }
+
+  if (executionMode === 'team' && teamCandidate) {
+    return 'team';
+  }
+
+  if (
+    commandCount > 1 ||
+    (task.touches || []).length > 1 ||
+    (task.dependsOn || []).length > 0 ||
+    teamCandidate
+  ) {
+    return 'delegate';
+  }
+
+  return 'direct';
+}
+
+function deriveLifecycleStage({ state, manifest, report, hasPrBrief = false }) {
+  const approval = getApprovalState(state, manifest);
+
+  if (state?.status === 'released') {
+    return 'released';
+  }
+
+  if (report?.overall === 'pass' && hasPrBrief) {
+    return 'prepare-pr';
+  }
+
+  if (report?.overall === 'pass') {
+    return 'document';
+  }
+
+  if (report?.overall === 'fail') {
+    return 'verify';
+  }
+
+  if (manifest && approval.status !== 'approved') {
+    return 'approve';
+  }
+
+  if (manifest) {
+    const summary = summarizeTaskStates(manifest.tasks);
+    if (summary.running > 0 || summary.failed > 0 || summary.pending > 0) {
+      return state?.status === 'planned' ? 'delegate' : 'execute';
+    }
+    if (summary.passed > 0 || summary.skipped > 0) {
+      return 'verify';
+    }
+  }
+
+  if (state?.status === 'planned') {
+    return 'delegate';
+  }
+
+  if (state?.status === 'initialized') {
+    return 'discover';
+  }
+
+  return 'converge';
+}
+
+function describeExecutionNextAction({ failedTaskIds, runningTaskIds, pendingTaskIds, report }) {
+  if (failedTaskIds.length > 0) {
+    return `优先修复失败任务 ${failedTaskIds.join(', ')}，然后从最近稳定 checkpoint 恢复。`;
+  }
+
+  if (runningTaskIds.length > 0) {
+    return `检查运行中任务 ${runningTaskIds.join(', ')}。`;
+  }
+
+  if (pendingTaskIds.length > 0) {
+    return `继续执行待处理任务 ${pendingTaskIds.join(', ')}。`;
+  }
+
+  if (!report) {
+    return '所有任务已完成，进入 cc-check 并同步验证证据。';
+  }
+
+  if (report.overall === 'fail') {
+    return '修复 blocking findings 后重新进入 cc-check。';
+  }
+
+  return '验证已通过，按实际路由生成唯一 handoff 文件。';
+}
+
+const DEFAULT_NEXT_ACTION = '生成或刷新 task-manifest，然后回到批准闸。';
+
+const NEXT_ACTION_RESOLVERS = {
+  discover: () => DEFAULT_NEXT_ACTION,
+  converge: () => DEFAULT_NEXT_ACTION,
+  approve: ({ approval }) => `先批准当前计划版本 ${approval.planVersion || 1}，再进入执行。`,
+  delegate: describeExecutionNextAction,
+  execute: describeExecutionNextAction,
+  verify: describeExecutionNextAction,
+  document: ({ hasReleaseNote }) => (
+    hasReleaseNote
+      ? '发布材料已经生成，可归档或启动下一轮增量。'
+      : '验证已通过，按实际路由生成唯一 handoff 文件。'
+  ),
+  'prepare-pr': ({ hasPrBrief, hasReleaseNote }) => {
+    if (hasReleaseNote) {
+      return '发布材料已经生成，可归档或启动下一轮增量。';
+    }
+
+    if (hasPrBrief) {
+      return 'PR brief 已生成，可直接整理提交并创建 PR。';
+    }
+
+    return '验证已通过，按实际路由生成唯一 handoff 文件。';
+  },
+  released: () => '发布材料已经生成，可归档或启动下一轮增量。'
+};
+
+function deriveLifecycleNextAction({
+  state,
+  manifest,
+  report,
+  hasPrBrief = false,
+  hasReleaseNote = false
+}) {
+  const stage = deriveLifecycleStage({ state, manifest, report, hasPrBrief });
+  const resolver = NEXT_ACTION_RESOLVERS[stage] || NEXT_ACTION_RESOLVERS.converge;
+
+  return resolver({
+    approval: getApprovalState(state, manifest),
+    report,
+    hasPrBrief,
+    hasReleaseNote,
+    failedTaskIds: listTaskIdsByStatus(manifest?.tasks, 'failed'),
+    runningTaskIds: listTaskIdsByStatus(manifest?.tasks, 'running'),
+    pendingTaskIds: listTaskIdsByStatus(manifest?.tasks, 'pending')
+  });
+}
+
+module.exports = {
+  STAGE_ORDER,
+  normalizeStage,
+  stageIndex,
+  normalizeExecutionMode,
+  normalizeTaskStatus,
+  isTaskCompletedStatus,
+  isTaskSettledStatus,
+  summarizeTaskStates,
+  deriveTaskProgress,
+  getApprovalState,
+  isExecutionApproved,
+  classifyDelegationMode,
+  deriveLifecycleStage,
+  deriveLifecycleNextAction
+};

package/lib/skill-runtime/operations/CLAUDE.md

@@ -0,0 +1,19 @@
+# operations/
+> L2 | 父级: ../CLAUDE.md
+
+阶段分组
+初始化与快照: `init.js` 创建 runtime 骨架，`snapshot.js` 采集 discover 阶段需要的只读事实。
+计划与批准: `plan.js` 生成 `task-manifest.json`，`approve.js` 锁定批准版本与执行模式。
+执行主链: `dispatch.js` 推进当前任务前沿，`resume.js` 从稳定 checkpoint 恢复，`verify.js` 和 `release.js` 负责质量门与发布收口。
+交接与工人: `prepare-pr.js` 生成唯一 PR brief，`worker.js`/`worker-run.js` 负责本地或 provider worker handoff 与回写。
+自动驾驶: `autopilot-shared.js`、`autopilot-core.js`、`autopilot-execution.js`、`autopilot.js` 拆开共享语义、阶段判定和执行循环，避免单文件失控。
+维护类: `janitor.js` 清理过期 runtime 工件，但不改变正在运行任务的真相源。
+
+更新规则
+这里只记录阶段入口和职责边界，不维护逐文件穷举说明。
+新增 operation 如果只是归入已有阶段，不改此文档；只有出现新阶段或边界迁移时才更新。
+阶段入口只保留当前真相源，不为历史别名单独占坑。
+
+法则: 阶段先于文件名·边界先于清单·父级链接稳定
+
+[PROTOCOL]: 变更阶段边界或入口约定时更新此头部，然后检查 CLAUDE.md

package/lib/skill-runtime/operations/approve.js

@@ -0,0 +1,66 @@
+/**
+ * [INPUT]: 依赖 change-state/task-manifest 与 handoff memory，同步接收 changeId 与 executionMode。
+ * [OUTPUT]: 为当前 plan_version 写入唯一 approval 真相，并返回批准摘要。
+ * [POS]: skill runtime 的显式批准入口，专门负责把计划从 converge 推进到可执行态。
+ * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+ */
+
+const {
+  nowIso,
+  readJson,
+  writeJson,
+  getRuntimeStatePath,
+  getTaskManifestPath
+} = require('../store');
+const { parseRuntimeState, parseManifest } = require('../schemas');
+const { syncIntentMemory } = require('../intent');
+const { normalizeExecutionMode } = require('../lifecycle');
+
+async function runApprove({ repoRoot, changeId, executionMode }) {
+  const statePath = getRuntimeStatePath(repoRoot, changeId);
+  const manifestPath = getTaskManifestPath(repoRoot, changeId);
+  const rawState = await readJson(statePath, null);
+  const rawManifest = await readJson(manifestPath, null);
+
+  if (!rawState) {
+    throw new Error(`Cannot approve ${changeId}: change-state.json is missing`);
+  }
+
+  if (!rawManifest) {
+    throw new Error(`Cannot approve ${changeId}: task-manifest.json is missing`);
+  }
+
+  const state = parseRuntimeState(rawState);
+  const manifest = parseManifest(rawManifest);
+  const approvedAt = nowIso();
+  const nextExecutionMode = normalizeExecutionMode(executionMode || state.approval?.executionMode);
+
+  await writeJson(statePath, {
+    ...state,
+    approval: {
+      status: 'approved',
+      executionMode: nextExecutionMode,
+      planVersion: manifest.metadata?.planVersion || 1,
+      approvedAt
+    },
+    updatedAt: approvedAt
+  });
+
+  await syncIntentMemory(repoRoot, changeId, {
+    event: 'approval_granted',
+    reason: `Plan version ${manifest.metadata?.planVersion || 1} approved for ${nextExecutionMode} execution`
+  });
+
+  return {
+    changeId,
+    statePath,
+    status: 'approved',
+    executionMode: nextExecutionMode,
+    planVersion: manifest.metadata?.planVersion || 1,
+    approvedAt
+  };
+}
+
+module.exports = {
+  runApprove
+};