cc-devflow 4.2.0 → 4.4.1

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

@@ -0,0 +1,59 @@
+/**
+ * [INPUT]: 依赖 planner.createTaskManifest，接收 changeId/goal/overwrite 参数。
+ * [OUTPUT]: 生成并返回已校验的 task-manifest.json 摘要。
+ * [POS]: skill runtime Stage-3 计划生成入口，供内部规划链路复用。
+ * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+ */
+
+const { createTaskManifest } = require('../planner');
+const { getIntentHandoffArtifactPaths } = require('../artifacts');
+const {
+  getTaskManifestPath,
+  getRuntimeStatePath,
+  getReportCardPath,
+  exists,
+  readJson,
+  writeJson,
+  removePath
+} = require('../store');
+
+async function runPlan({ repoRoot, changeId, goal, overwrite }) {
+  const manifest = await createTaskManifest({
+    repoRoot,
+    changeId,
+    goal,
+    overwrite
+  });
+
+  // Update change-state.json with plannedAt timestamp
+  const statePath = getRuntimeStatePath(repoRoot, changeId);
+  if (await exists(statePath)) {
+    const state = await readJson(statePath);
+    state.status = 'planned';
+    state.plannedAt = new Date().toISOString();
+    state.approval = {
+      status: 'pending',
+      executionMode: state.approval?.executionMode || 'delegate'
+    };
+    delete state.verifiedAt;
+    delete state.releasedAt;
+    state.updatedAt = new Date().toISOString();
+    await writeJson(statePath, state);
+  }
+
+  await Promise.all([
+    removePath(getReportCardPath(repoRoot, changeId)),
+    ...getIntentHandoffArtifactPaths(repoRoot, changeId).map((target) => removePath(target))
+  ]);
+
+  return {
+    changeId,
+    manifestPath: getTaskManifestPath(repoRoot, changeId),
+    taskCount: manifest.tasks.length,
+    source: manifest.metadata.source
+  };
+}
+
+module.exports = {
+  runPlan
+};

package/lib/skill-runtime/operations/prepare-pr.js

@@ -0,0 +1,25 @@
+/**
+ * [INPUT]: 依赖 intent 的 PR brief 生成能力，接收 repoRoot 与 changeId。
+ * [OUTPUT]: 生成 `devflow/changes/<goal>/handoff/pr-brief.md`，并清理冲突 handoff 文件。
+ * [POS]: skill runtime 的 PR-ready 收尾入口，被 autopilot 与内部收尾链路复用。
+ * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+ */
+
+const { getIntentPrBriefPath } = require('../artifacts');
+const { syncIntentMemory, syncIntentPrBrief } = require('../intent');
+
+async function runPreparePr({ repoRoot, changeId }) {
+  const prepared = await syncIntentPrBrief(repoRoot, changeId);
+  await syncIntentMemory(repoRoot, changeId);
+
+  return {
+    changeId,
+    prBriefPath: prepared.prBriefPath || getIntentPrBriefPath(repoRoot, changeId),
+    suggestedTitle: prepared.suggestedTitle,
+    status: 'prepared'
+  };
+}
+
+module.exports = {
+  runPreparePr
+};

package/lib/{harness → skill-runtime}/operations/release.js

@@ -1,7 +1,7 @@
 /**
  * [INPUT]: 依赖 report-card 与 task-manifest 的最终状态。
- * [OUTPUT]: 在 requirement 目录生成 RELEASE_NOTE.md，并更新 harness-state 为 released。
- * [POS]: harness 发布收尾入口，被 CLI `harness:release` 调用。
+ * [OUTPUT]: 在 handoff 目录生成 release-note.md，并更新 change-state 为 released。
+ * [POS]: skill runtime 发布收尾入口，供内部收尾链路复用。
  * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
  */
 
@@ -13,9 +13,10 @@ const {
   getReportCardPath,
   getTaskManifestPath,
   getReleaseNotePath,
-  getHarnessStatePath
+  getRuntimeStatePath
 } = require('../store');
 const { parseReportCard, parseManifest } = require('../schemas');
+const { syncIntentMemory } = require('../intent');
 
 function formatReleaseNote({ changeId, manifest, report }) {
   const passedTasks = manifest.tasks.filter((task) => task.status === 'passed');
@@ -25,7 +26,9 @@ function formatReleaseNote({ changeId, manifest, report }) {
     `# Release Note - ${changeId}`,
     '',
     `- Released At: ${nowIso()}`,
+    `- Verdict: ${(report.verdict || report.overall).toUpperCase()}`,
     `- Verification: ${report.overall.toUpperCase()}`,
+    `- Review: ${(report.review?.status || 'skipped').toUpperCase()}`,
     '',
     '## Task Summary',
     '',
@@ -50,10 +53,11 @@ function formatReleaseNote({ changeId, manifest, report }) {
 async function runRelease({ repoRoot, changeId }) {
   const reportPath = getReportCardPath(repoRoot, changeId);
   const manifestPath = getTaskManifestPath(repoRoot, changeId);
-  const statePath = getHarnessStatePath(repoRoot, changeId);
+  const statePath = getRuntimeStatePath(repoRoot, changeId);
 
   const report = parseReportCard(await readJson(reportPath));
   const manifest = parseManifest(await readJson(manifestPath));
+  const previousState = await readJson(statePath, null);
 
   if (report.overall !== 'pass') {
     throw new Error('Release blocked: report-card overall is not pass');
@@ -64,12 +68,21 @@ async function runRelease({ repoRoot, changeId }) {
 
   await writeText(releaseNotePath, note);
   await writeJson(statePath, {
+    ...(previousState || {}),
     changeId,
-    goal: manifest.goal,
+    changeKey: previousState?.changeKey,
+    slug: previousState?.slug,
+    createdAt: previousState?.createdAt,
+    goal: manifest.goal || previousState?.goal,
     status: 'released',
+    initializedAt: previousState?.initializedAt || nowIso(),
+    plannedAt: previousState?.plannedAt,
+    verifiedAt: previousState?.verifiedAt,
+    approval: previousState?.approval,
     releasedAt: nowIso(),
     updatedAt: nowIso()
   });
+  await syncIntentMemory(repoRoot, changeId);
 
   return {
     changeId,

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

@@ -0,0 +1,143 @@
+/**
+ * [INPUT]: 依赖 manifest/checkpoint 当前状态与 dispatch 执行器，接收 changeId/并行度/重试参数。
+ * [OUTPUT]: 将失败执行明确恢复到最近稳定 checkpoint，把未稳定任务重新排队后继续执行。
+ * [POS]: skill runtime 恢复执行入口，供内部恢复链路复用。
+ * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+ */
+
+const {
+  readJson,
+  writeJson,
+  getTaskManifestPath,
+  getRuntimeStatePath,
+  getCheckpointPath
+} = require('../store');
+const { parseManifest } = require('../schemas');
+const { applyManifestExecutionState } = require('../planner');
+const { runDispatch } = require('./dispatch');
+const { syncIntentMemory } = require('../intent');
+const { getApprovalState, isExecutionApproved } = require('../lifecycle');
+
+async function resolveStableCheckpoint(repoRoot, changeId, manifest) {
+  const checkpoints = await Promise.all(
+    manifest.tasks.map(async (task) => {
+      const checkpoint = await readJson(getCheckpointPath(repoRoot, changeId, task.id), null);
+      if (!checkpoint) {
+        return null;
+      }
+
+      return {
+        taskId: task.id,
+        status: checkpoint.status,
+        timestamp: checkpoint.timestamp,
+        summary: checkpoint.summary,
+        planVersion: checkpoint.planVersion || null
+      };
+    })
+  );
+
+  const latestPassed = checkpoints
+    .filter((checkpoint) =>
+      checkpoint &&
+      checkpoint.status === 'passed' &&
+      checkpoint.planVersion === (manifest.metadata?.planVersion || 1)
+    )
+    .sort((left, right) => right.timestamp.localeCompare(left.timestamp))[0];
+
+  return latestPassed || null;
+}
+
+function restoreTaskToPending(task, restoreLabel) {
+  const previousError = task.lastError ? ` Previous error: ${task.lastError}` : '';
+  task.status = 'pending';
+  task.attempts = 0;
+  task.lastError = `Restored from ${restoreLabel}.${previousError}`.trim();
+}
+
+function requeueFromStableCheckpoint(manifest, restoreTarget) {
+  const restoreLabel = restoreTarget ? `stable checkpoint ${restoreTarget.taskId}` : 'execution start';
+  const restoredTaskIds = [];
+
+  for (const task of manifest.tasks) {
+    if (task.status === 'running' || task.status === 'failed') {
+      restoreTaskToPending(task, restoreLabel);
+      restoredTaskIds.push(task.id);
+      continue;
+    }
+
+    if (task.status === 'skipped' && task.lastError === 'Blocked by failed dependency') {
+      restoreTaskToPending(task, restoreLabel);
+      restoredTaskIds.push(task.id);
+    }
+  }
+
+  return {
+    restoreLabel,
+    restoredTaskIds
+  };
+}
+
+async function runResume({
+  repoRoot,
+  changeId,
+  parallel,
+  maxRetries,
+  executionScope = 'all',
+  fromCheckpoint = 'stable'
+}) {
+  const manifestPath = getTaskManifestPath(repoRoot, changeId);
+  const manifest = parseManifest(await readJson(manifestPath));
+  const state = await readJson(getRuntimeStatePath(repoRoot, changeId), null);
+  const approval = getApprovalState(state, manifest);
+
+  if (!isExecutionApproved(state, manifest)) {
+    await syncIntentMemory(repoRoot, changeId, {
+      event: 'resume_blocked_unapproved',
+      reason: `Plan version ${approval.planVersion || manifest.metadata?.planVersion || 1} must be approved before resume`
+    });
+
+    return {
+      changeId,
+      manifestPath,
+      summary: null,
+      success: false,
+      reason: `Execution blocked until plan_version ${approval.planVersion || manifest.metadata?.planVersion || 1} is approved. Return to the cc-plan approval gate and keep execution mode ${approval.executionMode}.`
+    };
+  }
+
+  if (fromCheckpoint && fromCheckpoint !== 'stable') {
+    throw new Error(`Unsupported --from-checkpoint value: ${fromCheckpoint}`);
+  }
+
+  const restoreTarget = await resolveStableCheckpoint(repoRoot, changeId, manifest);
+  const restoreSummary = requeueFromStableCheckpoint(manifest, restoreTarget);
+
+  applyManifestExecutionState(manifest);
+  await writeJson(manifestPath, manifest);
+  await syncIntentMemory(repoRoot, changeId, {
+    event: 'resume_restored_checkpoint',
+    reason: restoreSummary.restoredTaskIds.length > 0
+      ? `Restored ${restoreSummary.restoredTaskIds.join(', ')} from ${restoreSummary.restoreLabel}`
+      : `Resume confirmed ${restoreSummary.restoreLabel}; no unresolved tasks required requeue`
+  });
+
+  const dispatchResult = await runDispatch({
+    repoRoot,
+    changeId,
+    parallel,
+    maxRetries,
+    resume: true,
+    executionScope
+  });
+
+  return {
+    ...dispatchResult,
+    restoredCheckpoint: restoreTarget,
+    restoredTasks: restoreSummary.restoredTaskIds,
+    reason: dispatchResult.reason || `Resumed from ${restoreSummary.restoreLabel}`
+  };
+}
+
+module.exports = {
+  runResume
+};

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

@@ -0,0 +1,45 @@
+/**
+ * [INPUT]: 依赖 store 读取 change-state/package scripts，并通过 git 命令收集仓库事实。
+ * [OUTPUT]: 返回 discover 阶段需要的仓库事实，不再落盘 planning-snapshot.md。
+ * [POS]: skill runtime Stage-2 内部快照入口，被 autopilot discover 阶段调用。
+ * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+ */
+
+const {
+  readJson,
+  getRuntimeStatePath,
+  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)'
+  };
+}
+
+async function runPlanningSnapshot({ repoRoot, changeId, goal }) {
+  const state = (await readJson(getRuntimeStatePath(repoRoot, changeId), {})) || {};
+  const effectiveGoal = goal || state.goal || `Deliver ${changeId} safely with auditable checkpoints.`;
+  const gitFacts = await collectGitFacts(repoRoot);
+  const scripts = await getPackageScripts(repoRoot);
+
+  return {
+    changeId,
+    goal: effectiveGoal,
+    gitFacts,
+    scripts
+  };
+}
+
+module.exports = {
+  runPlanningSnapshot
+};

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

@@ -0,0 +1,170 @@
+/**
+ * [INPUT]: 依赖 manifest 与 package scripts，依赖 shell gates（lint/typecheck/test/audit/review）。
+ * [OUTPUT]: 生成 report-card.json，给出 quick/strict/review 门禁结论。
+ * [POS]: skill runtime 质量门禁入口，供内部验证链路复用。
+ * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+ */
+
+const {
+  nowIso,
+  getPackageScripts,
+  readJson,
+  writeJson,
+  runCommand,
+  getTaskManifestPath,
+  getRuntimeStatePath,
+  getReportCardPath
+} = require('../store');
+const { parseManifest, parseReportCard } = require('../schemas');
+const { runReviewSuite } = require('../review');
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+const REQ_CHECK_DIR = path.join(__dirname, '..', '..', '..', '.claude', 'skills', 'cc-check');
+const RUN_GATES_SCRIPT = path.join(REQ_CHECK_DIR, 'scripts', 'run-quality-gates.sh');
+const RENDER_REPORT_SCRIPT = path.join(REQ_CHECK_DIR, 'scripts', 'render-report-card.js');
+
+function shellEscape(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+
+async function runGateCollection({ repoRoot, definitions }) {
+  if (!definitions || definitions.length === 0) {
+    return [];
+  }
+
+  const args = definitions
+    .map((item) => `--gate ${shellEscape(`${item.name}::${item.command}`)}`)
+    .join(' ');
+  const result = await runCommand(`bash ${shellEscape(RUN_GATES_SCRIPT)} ${args}`, {
+    cwd: repoRoot,
+    timeoutMs: 20 * 60 * 1000
+  });
+
+  if (result.code !== 0) {
+    throw new Error(result.stderr || result.stdout || 'run-quality-gates.sh failed');
+  }
+
+  return JSON.parse(result.stdout || '[]');
+}
+
+async function renderReportCard({ repoRoot, changeId, manifestPath, quickGates, strictGates, review }) {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cc-devflow-cc-check-'));
+  const quickPath = path.join(tempDir, 'quick-gates.json');
+  const strictPath = path.join(tempDir, 'strict-gates.json');
+  const reviewPath = path.join(tempDir, 'review.json');
+
+  try {
+    fs.writeFileSync(quickPath, `${JSON.stringify(quickGates, null, 2)}\n`);
+    fs.writeFileSync(strictPath, `${JSON.stringify(strictGates, null, 2)}\n`);
+    fs.writeFileSync(reviewPath, `${JSON.stringify(review, null, 2)}\n`);
+
+    const command = [
+      'node',
+      shellEscape(RENDER_REPORT_SCRIPT),
+      '--change-id',
+      shellEscape(changeId),
+      '--manifest',
+      shellEscape(manifestPath),
+      '--quick',
+      shellEscape(quickPath),
+      '--strict',
+      shellEscape(strictPath),
+      '--review',
+      shellEscape(reviewPath),
+      '--timestamp',
+      shellEscape(nowIso())
+    ].join(' ');
+
+    const result = await runCommand(command, { cwd: repoRoot, timeoutMs: 20 * 60 * 1000 });
+    if (result.code !== 0) {
+      throw new Error(result.stderr || result.stdout || 'render-report-card.js failed');
+    }
+
+    return JSON.parse(result.stdout);
+  } finally {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  }
+}
+
+async function runVerify({ repoRoot, changeId, strict = false, skipReview = false }) {
+  const manifestPath = getTaskManifestPath(repoRoot, changeId);
+  const manifest = parseManifest(await readJson(manifestPath));
+  const scripts = await getPackageScripts(repoRoot);
+
+  const quickGates = await runGateCollection({
+      repoRoot,
+      definitions: ['lint', 'typecheck', 'test'].map((name) => ({
+        name,
+        command: scripts[name]
+          ? `npm run ${name}`
+          : `printf '__CC_DEVFLOW_SKIP__ Script ${name} is not defined\n'`
+      }))
+  });
+
+  const strictGates = strict
+    ? await runGateCollection({
+      repoRoot,
+      definitions: [
+        {
+          name: 'test:integration',
+          command: scripts['test:integration']
+            ? 'npm run test:integration'
+            : "printf '__CC_DEVFLOW_SKIP__ Script test:integration is not defined\n'"
+        },
+        {
+          name: 'audit',
+          command: 'npm audit --audit-level=high'
+        }
+      ]
+    })
+    : [];
+
+  const review = await runReviewSuite({
+    repoRoot,
+    changeId,
+    manifest,
+    strict,
+    skipReview
+  });
+  const report = parseReportCard(
+    await renderReportCard({
+      repoRoot,
+      changeId,
+      manifestPath,
+      quickGates,
+      strictGates,
+      review
+    })
+  );
+
+  const outputPath = getReportCardPath(repoRoot, changeId);
+  await writeJson(outputPath, report);
+
+  // Update change-state.json with verifiedAt timestamp if passed
+  if (report.verdict === 'pass') {
+    const statePath = getRuntimeStatePath(repoRoot, changeId);
+    const stateExists = require('fs').existsSync(statePath);
+    if (stateExists) {
+      const state = await readJson(statePath);
+      state.status = 'verified';
+      state.verifiedAt = nowIso();
+      state.updatedAt = nowIso();
+      await writeJson(statePath, state);
+    }
+  }
+
+  return {
+    changeId,
+    outputPath,
+    overall: report.overall,
+    verdict: report.verdict || (report.overall === 'pass' ? 'pass' : 'fail'),
+    blockingFindings: report.blockingFindings
+  };
+}
+
+module.exports = {
+  runVerify
+};