cc-devflow 4.1.5 → 4.1.6

package/lib/harness/operations/dispatch.js

@@ -0,0 +1,285 @@
+/**
+ * [INPUT]: 依赖 manifest/checkpoint/events 与 shell 执行能力，接收并行度与重试参数。
+ * [OUTPUT]: 更新 task-manifest 状态，写入每任务 events.jsonl 与 checkpoint.json。
+ * [POS]: harness Stage-4 执行入口，被 CLI `harness:dispatch` 与 `harness:resume` 复用。
+ * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+ */
+
+const {
+  nowIso,
+  ensureDir,
+  appendJsonl,
+  writeJson,
+  readJson,
+  runCommand,
+  getTaskManifestPath,
+  getRuntimeTaskDir,
+  getEventsPath,
+  getCheckpointPath
+} = require('../store');
+const { parseManifest, parseCheckpoint } = require('../schemas');
+
+function toSessionId(taskId) {
+  return `${taskId}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+function dependenciesPassed(task, taskMap) {
+  return task.dependsOn.every((depId) => {
+    const dep = taskMap.get(depId);
+    return dep && dep.status === 'passed';
+  });
+}
+
+function dependenciesFailed(task, taskMap) {
+  return task.dependsOn.some((depId) => {
+    const dep = taskMap.get(depId);
+    return dep && (dep.status === 'failed' || dep.status === 'skipped');
+  });
+}
+
+function hasTouchConflict(task, lockedTouches) {
+  if (!task.touches || task.touches.length === 0) {
+    return false;
+  }
+
+  return task.touches.some((filePath) => lockedTouches.has(filePath));
+}
+
+function selectBatch(readyTasks, parallel) {
+  const selected = [];
+  const lockedTouches = new Set();
+
+  for (const task of readyTasks) {
+    if (selected.length >= parallel) {
+      break;
+    }
+
+    if (hasTouchConflict(task, lockedTouches)) {
+      continue;
+    }
+
+    selected.push(task);
+    for (const touched of task.touches) {
+      lockedTouches.add(touched);
+    }
+  }
+
+  return selected;
+}
+
+async function writeCheckpoint(repoRoot, changeId, taskId, payload) {
+  const checkpointPath = getCheckpointPath(repoRoot, changeId, taskId);
+  const checkpoint = parseCheckpoint(payload);
+  await writeJson(checkpointPath, checkpoint);
+}
+
+async function writeEvent(repoRoot, changeId, taskId, event) {
+  const eventsPath = getEventsPath(repoRoot, changeId, taskId);
+  await appendJsonl(eventsPath, event);
+}
+
+async function executeTask({ repoRoot, changeId, task, retryOverride }) {
+  const taskRuntimeDir = getRuntimeTaskDir(repoRoot, changeId, task.id);
+  await ensureDir(taskRuntimeDir);
+
+  const sessionId = toSessionId(task.id);
+  const commands = [...task.run, ...task.checks];
+  const taskRetry = Number.isInteger(retryOverride) ? retryOverride : task.maxRetries;
+  const maxAttempts = Math.max(1, taskRetry + 1);
+
+  while (task.attempts < maxAttempts) {
+    task.attempts += 1;
+    task.status = 'running';
+
+    await writeCheckpoint(repoRoot, changeId, task.id, {
+      changeId,
+      taskId: task.id,
+      sessionId,
+      status: task.status,
+      summary: `Task started (attempt ${task.attempts}/${maxAttempts})`,
+      timestamp: nowIso(),
+      attempt: task.attempts
+    });
+
+    await writeEvent(repoRoot, changeId, task.id, {
+      type: 'task_started',
+      changeId,
+      taskId: task.id,
+      sessionId,
+      attempt: task.attempts,
+      timestamp: nowIso()
+    });
+
+    let failed = false;
+    let failureMessage = '';
+
+    for (const command of commands) {
+      const result = await runCommand(command, {
+        cwd: repoRoot,
+        timeoutMs: 30 * 60 * 1000
+      });
+
+      await writeEvent(repoRoot, changeId, task.id, {
+        type: 'command_finished',
+        changeId,
+        taskId: task.id,
+        sessionId,
+        attempt: task.attempts,
+        command,
+        code: result.code,
+        durationMs: result.durationMs,
+        timestamp: nowIso()
+      });
+
+      if (result.code !== 0) {
+        failed = true;
+        failureMessage = (result.stderr || result.stdout || 'Command failed').trim();
+        break;
+      }
+    }
+
+    if (!failed) {
+      task.status = 'passed';
+      task.lastError = undefined;
+
+      await writeCheckpoint(repoRoot, changeId, task.id, {
+        changeId,
+        taskId: task.id,
+        sessionId,
+        status: task.status,
+        summary: `Task passed after ${task.attempts} attempt(s)`,
+        timestamp: nowIso(),
+        attempt: task.attempts
+      });
+
+      await writeEvent(repoRoot, changeId, task.id, {
+        type: 'task_passed',
+        changeId,
+        taskId: task.id,
+        sessionId,
+        attempts: task.attempts,
+        timestamp: nowIso()
+      });
+
+      return;
+    }
+
+    task.status = 'failed';
+    task.lastError = failureMessage;
+
+    await writeCheckpoint(repoRoot, changeId, task.id, {
+      changeId,
+      taskId: task.id,
+      sessionId,
+      status: task.status,
+      summary: `Task failed: ${failureMessage.slice(0, 240)}`,
+      timestamp: nowIso(),
+      attempt: task.attempts
+    });
+
+    await writeEvent(repoRoot, changeId, task.id, {
+      type: 'task_failed',
+      changeId,
+      taskId: task.id,
+      sessionId,
+      attempt: task.attempts,
+      error: failureMessage,
+      timestamp: nowIso()
+    });
+  }
+}
+
+function summarizeTasks(tasks) {
+  return tasks.reduce(
+    (acc, task) => {
+      acc[task.status] = (acc[task.status] || 0) + 1;
+      return acc;
+    },
+    { pending: 0, running: 0, passed: 0, failed: 0, skipped: 0 }
+  );
+}
+
+async function runDispatch({ repoRoot, changeId, parallel = 3, maxRetries, resume = false }) {
+  const manifestPath = getTaskManifestPath(repoRoot, changeId);
+  const manifest = parseManifest(await readJson(manifestPath));
+
+  if (resume) {
+    for (const task of manifest.tasks) {
+      if (task.status === 'running') {
+        task.status = 'pending';
+      }
+    }
+  }
+
+  const safeParallel = Math.max(1, Number.parseInt(parallel, 10) || 1);
+
+  while (true) {
+    const taskMap = new Map(manifest.tasks.map((task) => [task.id, task]));
+    const pending = manifest.tasks.filter((task) => task.status === 'pending');
+
+    if (pending.length === 0) {
+      break;
+    }
+
+    for (const task of pending) {
+      if (dependenciesFailed(task, taskMap)) {
+        task.status = 'skipped';
+        task.lastError = 'Blocked by failed dependency';
+      }
+    }
+
+    const ready = manifest.tasks.filter(
+      (task) => task.status === 'pending' && dependenciesPassed(task, taskMap)
+    );
+
+    if (ready.length === 0) {
+      await writeJson(manifestPath, {
+        ...manifest,
+        updatedAt: nowIso()
+      });
+
+      return {
+        changeId,
+        manifestPath,
+        summary: summarizeTasks(manifest.tasks),
+        success: false,
+        reason: 'No ready tasks left. Check dependencies and failed tasks.'
+      };
+    }
+
+    const batch = selectBatch(ready, safeParallel);
+
+    if (batch.length === 0) {
+      const firstReady = ready[0];
+      batch.push(firstReady);
+    }
+
+    await Promise.all(
+      batch.map((task) =>
+        executeTask({
+          repoRoot,
+          changeId,
+          task,
+          retryOverride: Number.isInteger(maxRetries) ? maxRetries : undefined
+        })
+      )
+    );
+
+    manifest.updatedAt = nowIso();
+    await writeJson(manifestPath, manifest);
+  }
+
+  const summary = summarizeTasks(manifest.tasks);
+  const success = summary.failed === 0 && summary.pending === 0;
+
+  return {
+    changeId,
+    manifestPath,
+    summary,
+    success
+  };
+}
+
+module.exports = {
+  runDispatch
+};

package/lib/harness/operations/init.js

@@ -0,0 +1,48 @@
+/**
+ * [INPUT]: 依赖 store 提供 repo/change 路径与读写能力，接收 changeId/goal 初始化参数。
+ * [OUTPUT]: 写入 requirement 目录与 harness-state.json，返回初始化摘要。
+ * [POS]: harness Stage-1 初始化入口，被 CLI `harness:init` 调用。
+ * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+ */
+
+const {
+  nowIso,
+  ensureDir,
+  writeJson,
+  readJson,
+  getRequirementDir,
+  getRuntimeChangeDir,
+  getHarnessStatePath
+} = require('../store');
+
+async function runInit({ repoRoot, changeId, goal }) {
+  const requirementDir = getRequirementDir(repoRoot, changeId);
+  const runtimeDir = getRuntimeChangeDir(repoRoot, changeId);
+  const statePath = getHarnessStatePath(repoRoot, changeId);
+
+  await ensureDir(requirementDir);
+  await ensureDir(runtimeDir);
+
+  const previous = (await readJson(statePath, {})) || {};
+  const nextState = {
+    changeId,
+    goal: goal || previous.goal || `Deliver ${changeId} safely with auditable checkpoints.`,
+    status: 'initialized',
+    initializedAt: previous.initializedAt || nowIso(),
+    updatedAt: nowIso()
+  };
+
+  await writeJson(statePath, nextState);
+
+  return {
+    changeId,
+    requirementDir,
+    runtimeDir,
+    statePath,
+    status: nextState.status
+  };
+}
+
+module.exports = {
+  runInit
+};

package/lib/harness/operations/janitor.js

@@ -0,0 +1,74 @@
+/**
+ * [INPUT]: 依赖 .harness/runtime 目录与 checkpoint 状态，接收保留小时阈值。
+ * [OUTPUT]: 删除过期且非运行中的任务运行态目录，并输出清理统计。
+ * [POS]: harness 熵清理入口，被 CLI `harness:janitor` 调用。
+ * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+ */
+
+const fs = require('fs');
+const path = require('path');
+const {
+  readJson,
+  listDirectories,
+  getRuntimeRoot
+} = require('../store');
+
+async function removeDirectoryRecursive(dirPath) {
+  await fs.promises.rm(dirPath, { recursive: true, force: true });
+}
+
+async function isTaskActive(taskDir) {
+  const checkpointPath = path.join(taskDir, 'checkpoint.json');
+  const checkpoint = await readJson(checkpointPath, null);
+
+  if (!checkpoint) {
+    return false;
+  }
+
+  return checkpoint.status === 'running';
+}
+
+async function runJanitor({ repoRoot, hours = 72 }) {
+  const runtimeRoot = getRuntimeRoot(repoRoot);
+  const cutoffMs = Date.now() - Number(hours) * 60 * 60 * 1000;
+
+  const changeDirs = await listDirectories(runtimeRoot);
+  let removedTaskDirs = 0;
+  let removedChangeDirs = 0;
+
+  for (const changeDir of changeDirs) {
+    const taskDirs = await listDirectories(changeDir);
+
+    for (const taskDir of taskDirs) {
+      const stat = await fs.promises.stat(taskDir);
+      const isStale = stat.mtimeMs < cutoffMs;
+      if (!isStale) {
+        continue;
+      }
+
+      if (await isTaskActive(taskDir)) {
+        continue;
+      }
+
+      await removeDirectoryRecursive(taskDir);
+      removedTaskDirs += 1;
+    }
+
+    const remaining = await listDirectories(changeDir);
+    if (remaining.length === 0) {
+      await removeDirectoryRecursive(changeDir);
+      removedChangeDirs += 1;
+    }
+  }
+
+  return {
+    runtimeRoot,
+    removedTaskDirs,
+    removedChangeDirs,
+    cutoffHours: Number(hours)
+  };
+}
+
+module.exports = {
+  runJanitor
+};

package/lib/harness/operations/pack.js

@@ -0,0 +1,100 @@
+/**
+ * [INPUT]: 依赖 store 读取 harness-state/package scripts，并通过 git 命令收集仓库事实。
+ * [OUTPUT]: 生成 context-package.md，提供可复现的目标/约束/下一步命令。
+ * [POS]: harness Stage-2 上下文打包入口，被 CLI `harness:pack` 调用。
+ * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+ */
+
+const {
+  nowIso,
+  readJson,
+  writeText,
+  getContextPackagePath,
+  getHarnessStatePath,
+  runCommand,
+  getPackageScripts
+} = require('../store');
+
+async function collectGitFacts(repoRoot) {
+  const [branch, commit, status] = await Promise.all([
+    runCommand('git rev-parse --abbrev-ref HEAD', { cwd: repoRoot }),
+    runCommand('git rev-parse HEAD', { cwd: repoRoot }),
+    runCommand('git status --short', { cwd: repoRoot })
+  ]);
+
+  return {
+    branch: branch.code === 0 ? branch.stdout.trim() : 'unknown',
+    commit: commit.code === 0 ? commit.stdout.trim() : 'unknown',
+    status: status.code === 0 ? status.stdout.trim() : '(clean)'
+  };
+}
+
+function buildContextMarkdown({ changeId, goal, gitFacts, scripts }) {
+  const nextCommands = [
+    `npm run harness:plan -- --change-id ${changeId}`,
+    `npm run harness:dispatch -- --change-id ${changeId} --parallel 3`,
+    `npm run harness:verify -- --change-id ${changeId} --strict`,
+    `npm run harness:release -- --change-id ${changeId}`
+  ];
+
+  return [
+    `# Context Package - ${changeId}`,
+    '',
+    `- Generated: ${nowIso()}`,
+    `- Goal: ${goal}`,
+    '',
+    '## Repository Facts',
+    '',
+    `- Branch: ${gitFacts.branch}`,
+    `- Commit: ${gitFacts.commit}`,
+    '',
+    '### Git Status',
+    '',
+    '```text',
+    gitFacts.status || '(clean)',
+    '```',
+    '',
+    '## Constraints',
+    '',
+    '- Keep tasks dependency-aware and checkpointed.',
+    '- Block release when strict verification fails.',
+    '- Preserve auditable runtime logs in .harness/runtime/.',
+    '',
+    '## Available npm scripts',
+    '',
+    '```text',
+    Object.keys(scripts).sort().join('\n') || '(none)',
+    '```',
+    '',
+    '## Next Commands',
+    '',
+    ...nextCommands.map((command) => `- \`${command}\``),
+    ''
+  ].join('\n');
+}
+
+async function runPack({ repoRoot, changeId, goal }) {
+  const state = (await readJson(getHarnessStatePath(repoRoot, changeId), {})) || {};
+  const effectiveGoal = goal || state.goal || `Deliver ${changeId} safely with auditable checkpoints.`;
+  const gitFacts = await collectGitFacts(repoRoot);
+  const scripts = await getPackageScripts(repoRoot);
+  const context = buildContextMarkdown({
+    changeId,
+    goal: effectiveGoal,
+    gitFacts,
+    scripts
+  });
+
+  const outputPath = getContextPackagePath(repoRoot, changeId);
+  await writeText(outputPath, `${context}`);
+
+  return {
+    changeId,
+    outputPath,
+    goal: effectiveGoal
+  };
+}
+
+module.exports = {
+  runPack
+};

package/lib/harness/operations/plan.js

@@ -0,0 +1,29 @@
+/**
+ * [INPUT]: 依赖 planner.createTaskManifest，接收 changeId/goal/overwrite 参数。
+ * [OUTPUT]: 生成并返回已校验的 task-manifest.json 摘要。
+ * [POS]: harness Stage-3 计划生成入口，被 CLI `harness:plan` 调用。
+ * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+ */
+
+const { createTaskManifest } = require('../planner');
+const { getTaskManifestPath } = require('../store');
+
+async function runPlan({ repoRoot, changeId, goal, overwrite }) {
+  const manifest = await createTaskManifest({
+    repoRoot,
+    changeId,
+    goal,
+    overwrite
+  });
+
+  return {
+    changeId,
+    manifestPath: getTaskManifestPath(repoRoot, changeId),
+    taskCount: manifest.tasks.length,
+    source: manifest.metadata.source
+  };
+}
+
+module.exports = {
+  runPlan
+};

package/lib/harness/operations/release.js

@@ -0,0 +1,83 @@
+/**
+ * [INPUT]: 依赖 report-card 与 task-manifest 的最终状态。
+ * [OUTPUT]: 在 requirement 目录生成 RELEASE_NOTE.md，并更新 harness-state 为 released。
+ * [POS]: harness 发布收尾入口，被 CLI `harness:release` 调用。
+ * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+ */
+
+const {
+  nowIso,
+  readJson,
+  writeText,
+  writeJson,
+  getReportCardPath,
+  getTaskManifestPath,
+  getReleaseNotePath,
+  getHarnessStatePath
+} = require('../store');
+const { parseReportCard, parseManifest } = require('../schemas');
+
+function formatReleaseNote({ changeId, manifest, report }) {
+  const passedTasks = manifest.tasks.filter((task) => task.status === 'passed');
+  const failedTasks = manifest.tasks.filter((task) => task.status === 'failed');
+
+  return [
+    `# Release Note - ${changeId}`,
+    '',
+    `- Released At: ${nowIso()}`,
+    `- Verification: ${report.overall.toUpperCase()}`,
+    '',
+    '## Task Summary',
+    '',
+    `- Passed: ${passedTasks.length}`,
+    `- Failed: ${failedTasks.length}`,
+    '',
+    '## Completed Tasks',
+    '',
+    ...(passedTasks.length > 0
+      ? passedTasks.map((task) => `- ${task.id}: ${task.title}`)
+      : ['- (none)']),
+    '',
+    '## Blocking Findings',
+    '',
+    ...(report.blockingFindings.length > 0
+      ? report.blockingFindings.map((item) => `- ${item}`)
+      : ['- None']),
+    ''
+  ].join('\n');
+}
+
+async function runRelease({ repoRoot, changeId }) {
+  const reportPath = getReportCardPath(repoRoot, changeId);
+  const manifestPath = getTaskManifestPath(repoRoot, changeId);
+  const statePath = getHarnessStatePath(repoRoot, changeId);
+
+  const report = parseReportCard(await readJson(reportPath));
+  const manifest = parseManifest(await readJson(manifestPath));
+
+  if (report.overall !== 'pass') {
+    throw new Error('Release blocked: report-card overall is not pass');
+  }
+
+  const note = formatReleaseNote({ changeId, manifest, report });
+  const releaseNotePath = getReleaseNotePath(repoRoot, changeId);
+
+  await writeText(releaseNotePath, note);
+  await writeJson(statePath, {
+    changeId,
+    goal: manifest.goal,
+    status: 'released',
+    releasedAt: nowIso(),
+    updatedAt: nowIso()
+  });
+
+  return {
+    changeId,
+    releaseNotePath,
+    status: 'released'
+  };
+}
+
+module.exports = {
+  runRelease
+};

package/lib/harness/operations/resume.js

@@ -0,0 +1,44 @@
+/**
+ * [INPUT]: 依赖 manifest 当前任务状态与 dispatch 执行器，接收 changeId/并行度/重试参数。
+ * [OUTPUT]: 将 running 与可重试 failed 任务回置为 pending，并继续调度执行。
+ * [POS]: harness 恢复执行入口，被 CLI `harness:resume` 调用。
+ * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+ */
+
+const { readJson, writeJson, getTaskManifestPath } = require('../store');
+const { parseManifest } = require('../schemas');
+const { runDispatch } = require('./dispatch');
+
+async function runResume({ repoRoot, changeId, parallel, maxRetries }) {
+  const manifestPath = getTaskManifestPath(repoRoot, changeId);
+  const manifest = parseManifest(await readJson(manifestPath));
+
+  for (const task of manifest.tasks) {
+    if (task.status === 'running') {
+      task.status = 'pending';
+      task.lastError = 'Resumed from interrupted running state';
+      continue;
+    }
+
+    if (task.status === 'failed') {
+      const retryLimit = Number.isInteger(maxRetries) ? maxRetries : task.maxRetries;
+      if (task.attempts <= retryLimit) {
+        task.status = 'pending';
+      }
+    }
+  }
+
+  await writeJson(manifestPath, manifest);
+
+  return runDispatch({
+    repoRoot,
+    changeId,
+    parallel,
+    maxRetries,
+    resume: true
+  });
+}
+
+module.exports = {
+  runResume
+};