coding-agent-harness 1.0.2 → 1.0.4

package/scripts/lib/task-lifecycle.mjs

@@ -1,9 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import crypto from "node:crypto";
-import { spawnSync } from "node:child_process";
 import {
-  repoRoot,
   visualMapFile,
   legacyVisualRoadmapFile,
   lessonCandidatesFile,
@@ -25,26 +23,44 @@ import {
   normalizeTaskId,
   renderTaskTemplate,
 } from "./core-shared.mjs";
-import { verifyMigrationSession } from "./migration-planner.mjs";
 import { readCapabilityRegistry } from "./capability-registry.mjs";
+import { readPresetPackage } from "./preset-registry.mjs";
+import {
+  assertPresetWriteScope,
+  buildPresetContext,
+  evaluateTemplateValues,
+  resolvePresetInputs,
+  renderPresetResourceIndex,
+  renderPresetTaskTemplate,
+} from "./preset-engine.mjs";
 import {
   collectTasks,
   collectReviewRisks,
   isBlockingReviewRisk,
   listTaskPlanPaths,
-  parsePhases,
   parseTaskBudget,
-  parseLessonCandidateStatus,
-  isLessonCandidateDecisionComplete,
-  parseReviewConfirmation,
-  readVisualMapContractFile,
   taskIdForDirectory,
+  taskScannerVersion,
 } from "./task-scanner.mjs";
 import {
   getColumn,
   firstColumn,
   updateMarkdownTableRow,
 } from "./markdown-utils.mjs";
+import {
+  validateLifecycleTransition,
+  validateReviewEntryGate,
+} from "./task-lifecycle/review-gates.mjs";
+import { confirmTaskReview as confirmTaskReviewWithContext } from "./task-lifecycle/review-confirm.mjs";
+import { appendProgressLog, markdownCell } from "./task-lifecycle/text-utils.mjs";
+import {
+  beginGovernanceSync,
+  commitGovernanceSync,
+  governanceRelativePaths,
+  releaseGovernanceSync,
+  syncModuleStepGovernance,
+  syncTaskGovernance,
+} from "./governance-sync.mjs";
 
 function taskTemplateFiles({ locale = "en-US" } = {}) {
   return [
@@ -91,7 +107,7 @@ function taskRoot(target, taskId, { moduleKey = "" } = {}) {
   return path.join(target.docsRoot, "09-PLANNING/TASKS", normalizedTaskId);
 }
 
-function resolveTaskDirectory(target, taskRef) {
+export function resolveTaskDirectory(target, taskRef) {
   const raw = String(taskRef || "").replace(/^docs\/09-PLANNING\//, "").replace(/^\/+/, "");
   if (!raw) throw new Error("Missing task id");
   const direct = raw.startsWith("TASKS/") || raw.startsWith("MODULES/") ? path.join(target.docsRoot, "09-PLANNING", raw) : "";
@@ -153,11 +169,10 @@ function normalizeTaskBudgetInput(budget) {
   throw new Error(`Invalid task budget: ${budget}. Expected one of: simple, standard, complex`);
 }
 
-function normalizeTaskPresetInput(preset) {
+function normalizeTaskPresetInput(preset, { targetInput = "" } = {}) {
   const normalized = String(preset || "none").trim().toLowerCase().replaceAll("_", "-");
   if (!normalized || normalized === "none") return "none";
-  if (normalized === "legacy-migration") return normalized;
-  throw new Error(`Invalid task preset: ${preset}. Expected one of: legacy-migration`);
+  return readPresetPackage(normalized, { targetInput }).id;
 }
 
 function taskFilesForBudget({ budget, locale }) {
@@ -171,60 +186,6 @@ function appendLongRunningContractFile(files, { locale, longRunning }) {
   return [...files, [longRunningTaskContractFile, localizedTemplateSource("templates/planning/long-running-task-contract.md", locale)]];
 }
 
-function validateLifecycleTransition({ event, currentState, budget, reviewContent = "" }) {
-  if (event === "task-review" && currentState !== "in_progress") {
-    throw new Error(`task-review requires current state in_progress; current state is ${currentState || "unknown"}`);
-  }
-  if (event === "task-complete" && budget !== "simple" && currentState !== "review") {
-    throw new Error(`task-complete for ${budget} tasks requires current state review. Run task-review first.`);
-  }
-  if (event === "task-complete" && budget !== "simple") {
-    const blockingRisks = collectReviewRisks(reviewContent).filter(isBlockingReviewRisk);
-    if (blockingRisks.length > 0) {
-      const ids = blockingRisks.map((risk) => risk.id || risk.severity).join(", ");
-      throw new Error(`Open blocking review findings must be closed before task-complete: ${ids}`);
-    }
-    if (!parseReviewConfirmation(reviewContent)?.confirmed) {
-      throw new Error("Human review must be confirmed before task-complete. Run review-confirm first.");
-    }
-  }
-}
-
-function validateReviewEntryGate(taskDir, budget) {
-  if (budget === "simple") return;
-  const candidatePath = path.join(taskDir, lessonCandidatesFile);
-  if (!fs.existsSync(candidatePath)) {
-    throw new Error(`task-review requires ${lessonCandidatesFile} before entering human review.`);
-  }
-  const phases = parsePhases(readVisualMapContractFile(taskDir).content);
-  const actionablePhases = phases.filter((phase) => phase.state !== "skipped");
-  const hasRecordedPhaseProgress = actionablePhases.some(
-    (phase) =>
-      phase.completion > 0 ||
-      ["in_progress", "review", "blocked", "done"].includes(phase.state) ||
-      ["partial", "present", "waived"].includes(phase.evidenceStatus),
-  );
-  if (actionablePhases.length > 0 && !hasRecordedPhaseProgress) {
-    throw new Error("task-review requires at least one Visual Map phase progress update. Run task-phase before entering human review.");
-  }
-}
-
-function validateHumanReviewConfirmation({ task, budget }) {
-  if (budget === "simple") return;
-  const state = task?.state || "unknown";
-  const lifecycle = task?.lifecycleState || "";
-  if (state !== "review" && !["in_review", "review-blocked"].includes(lifecycle)) {
-    throw new Error(`Human review confirmation requires current state review; current state is ${state}. Run task-review first.`);
-  }
-  if (!task?.walkthroughPath) {
-    throw new Error("Human review confirmation requires a walkthrough linked from Closeout SSoT before review-confirm.");
-  }
-  if (!task?.lessonCandidateDecisionComplete) {
-    const status = task?.lessonCandidateStatus || "missing";
-    throw new Error(`Human review confirmation requires lesson candidate decision complete; current status is ${status}.`);
-  }
-}
-
 function updateProgressState(content, state, locale) {
   const label = stateLabel(state, locale);
   if (/^##\s*状态[:：][^\n]*/im.test(content)) {
@@ -236,22 +197,6 @@ function updateProgressState(content, state, locale) {
   return `${content.trimEnd()}\n\n## Status\n\n${label}\n`;
 }
 
-function appendProgressLog(content, { event, message, evidence, actor = "coordinator" }) {
-  const timestamp = nowTimestamp();
-  const safeMessage = String(message || event).replace(/\r?\n/g, " ").trim();
-  const safeEvidence = String(evidence || "n/a").replace(/\r?\n/g, " ").trim();
-  if (/^##\s*Log\s*$/im.test(content)) {
-    return content.replace(
-      /(^##\s*Log\s*$[\s\S]*?\| --- \| --- \| --- \| --- \| --- \|\n)/im,
-      `$1| ${timestamp} | ${actor} | ${event}: ${safeMessage} | ${safeEvidence} | ${event === "task-complete" ? "done" : "continue"} |\n`,
-    );
-  }
-  if (/^##\s*进度记录\s*$/im.test(content)) {
-    return `${content.trimEnd()}\n\n### [${timestamp}] - ${event}\n\n- 做了什么：${safeMessage}\n- 验证结果：已记录\n- 下一步：${event === "task-complete" ? "完成" : "继续执行"}\n- 证据：${safeEvidence}\n`;
-  }
-  return `${content.trimEnd()}\n\n## Log\n\n| Time | Actor | Action | Evidence | Next |\n| --- | --- | --- | --- | --- |\n| ${timestamp} | ${actor} | ${event}: ${safeMessage} | ${safeEvidence} | ${event === "task-complete" ? "done" : "continue"} |\n`;
-}
-
 function ensureDatePrefix(slug) {
   if (datePrefix.test(slug)) return slug;
   return `${localDate()}-${slug}`;
@@ -262,42 +207,53 @@ function bareSlug(datedId) {
   return datedId;
 }
 
-export function createTask(targetInput, taskId, { title = "", locale = "en-US", dryRun = false, moduleKey = "", budget = "standard", longRunning = false, preset = "", fromSession = "" } = {}) {
-  const normalizedPreset = normalizeTaskPresetInput(preset);
-  const migrationSession = fromSession ? readMigrationSession(fromSession) : null;
-  const target = migrationSession ? normalizeTarget(migrationSession.target) : normalizeTarget(targetInput);
-  if (migrationSession && targetInput && targetInput !== "." && path.resolve(targetInput) !== path.resolve(migrationSession.target)) {
-    throw new Error(`--from-session target mismatch: session target is ${migrationSession.target}`);
+export function createTask(targetInput, taskId, { title = "", locale = "en-US", dryRun = false, moduleKey = "", budget = "standard", longRunning = false, preset = "", fromSession = "", presetArgs = [] } = {}) {
+  const requestedPreset = preset || (moduleKey ? "module" : "");
+  const normalizedPreset = normalizeTaskPresetInput(requestedPreset, { targetInput });
+  const presetPackage = normalizedPreset === "none" ? null : readPresetPackage(normalizedPreset, { targetInput });
+  const presetInputs = presetPackage ? resolvePresetInputs(presetPackage, { cliArgs: presetArgs, fromSession, targetInput }) : null;
+  const target = normalizeTarget(presetInputs?.targetInput || targetInput);
+  if (presetInputs?.targetInput && targetInput && targetInput !== "." && path.resolve(targetInput) !== path.resolve(presetInputs.targetInput)) {
+    throw new Error(`--from-session target mismatch: session target is ${presetInputs.targetInput}`);
   }
-  if (normalizedPreset !== "none" && normalizedPreset !== "legacy-migration") throw new Error(`Unsupported task preset: ${normalizedPreset}`);
-  if (normalizedPreset === "legacy-migration" && budget !== "complex") throw new Error("legacy-migration preset requires --budget complex");
-  if (normalizedPreset === "legacy-migration" && moduleKey) throw new Error("legacy-migration preset is project-level and cannot be combined with --module");
-  if (normalizedPreset === "legacy-migration" && !migrationSession) throw new Error("legacy-migration preset requires --from-session");
-  const rawNormalized = normalizeTaskId(taskId || (normalizedPreset === "legacy-migration" ? "harness-v1-migration" : ""));
+  const normalizedBudget = normalizeTaskBudgetInput(budget);
+  if (presetPackage && !presetPackage.compatibleBudgets.includes(normalizedBudget)) throw new Error(`${normalizedPreset} preset requires --budget ${presetPackage.compatibleBudgets.join("|")}`);
+  if (presetPackage?.task?.projectLevelOnly === true && moduleKey) throw new Error(`${normalizedPreset} preset is project-level and cannot be combined with --module`);
+  if (presetPackage?.task?.requiresFromSession === true && !fromSession) throw new Error(`${normalizedPreset} preset requires --from-session`);
+  const rawNormalized = normalizeTaskId(taskId || (presetPackage?.task?.defaultTaskId || ""));
   const normalizedTaskId = ensureDatePrefix(rawNormalized);
   if (!normalizedTaskId) throw new Error("Missing task id");
   const semanticSlug = bareSlug(normalizedTaskId);
   const normalizedModuleKey = moduleKey ? normalizeTaskId(moduleKey) : "";
   const normalizedLocale = normalizeLocale(locale || readCapabilityRegistry(target).locale);
-  const normalizedBudget = normalizeTaskBudgetInput(budget);
   const taskTitle = title || (normalizedPreset === "legacy-migration" ? "Harness v1 legacy migration" : semanticSlug);
   const directory = taskRoot(target, normalizedTaskId, { moduleKey: normalizedModuleKey });
   if (fs.existsSync(directory)) throw new Error(`Task already exists: ${normalizedTaskId}`);
-  const presetContext = normalizedPreset === "legacy-migration"
-    ? legacyMigrationPresetContext({ target, taskDir: directory, taskId: normalizedTaskId, session: migrationSession })
+  const evaluatedPresetValues = presetPackage ? evaluateTemplateValues(presetPackage, presetInputs.inputs, { taskId: normalizedTaskId, taskTitle, moduleKey: normalizedModuleKey }) : null;
+  const presetContext = presetPackage
+    ? buildPresetContext({ ...presetPackage, task: { ...(presetPackage.task || {}), kind: presetPackage.task?.kind || "general" } }, {
+        target,
+        taskDir: directory,
+        taskId: normalizedTaskId,
+        taskTitle,
+        resolvedInputs: presetInputs.inputs,
+        evaluatedValues: evaluatedPresetValues,
+      })
     : null;
   const changes = [];
+  const governanceContext = beginGovernanceSync(target, { operation: `new-task ${normalizedTaskId}`, dryRun });
+  try {
   if (normalizedModuleKey) {
     const moduleDirectory = path.dirname(directory);
     for (const [destination, source] of moduleTemplateFiles({ locale: normalizedLocale })) {
       const destinationPath = path.join(moduleDirectory, destination);
       if (fs.existsSync(destinationPath)) continue;
-      const sourcePath = path.join(repoRoot, source);
       changes.push({
         destination: toPosix(path.relative(target.projectRoot, destinationPath)),
         source,
         action: dryRun ? "would-create" : "create",
       });
+      if (presetPackage) assertPresetWriteScope(presetPackage, toPosix(path.relative(target.projectRoot, destinationPath)));
       if (dryRun) continue;
       fs.mkdirSync(path.dirname(destinationPath), { recursive: true });
       fs.writeFileSync(
@@ -317,12 +273,12 @@ export function createTask(targetInput, taskId, { title = "", locale = "en-US",
   });
   for (const [destination, source] of files) {
     const destinationPath = path.join(directory, destination);
-    const sourcePath = path.join(repoRoot, source);
     changes.push({
       destination: toPosix(path.relative(target.projectRoot, destinationPath)),
       source,
       action: dryRun ? "would-create" : "create",
     });
+    if (presetPackage) assertPresetWriteScope(presetPackage, toPosix(path.relative(target.projectRoot, destinationPath)));
     if (dryRun) continue;
     fs.mkdirSync(path.dirname(destinationPath), { recursive: true });
     fs.writeFileSync(
@@ -343,211 +299,93 @@ export function createTask(targetInput, taskId, { title = "", locale = "en-US",
         source: evidence.source,
         action: dryRun ? "would-create" : "create",
       });
+      assertPresetWriteScope(presetPackage, toPosix(evidence.relativePath));
       if (dryRun) continue;
       fs.mkdirSync(path.dirname(destinationPath), { recursive: true });
       fs.writeFileSync(destinationPath, evidence.content);
     }
+    for (const resource of presetContext.resourceFiles || []) {
+      const destinationPath = path.join(target.projectRoot, resource.relativePath);
+      changes.push({
+        destination: toPosix(resource.relativePath),
+        source: resource.source,
+        action: dryRun ? "would-create" : "create",
+      });
+      assertPresetWriteScope(presetPackage, toPosix(resource.relativePath));
+      if (dryRun) continue;
+      fs.mkdirSync(path.dirname(destinationPath), { recursive: true });
+      fs.writeFileSync(destinationPath, resource.content);
+    }
+    for (const [kind, rows] of Object.entries(presetContext.resourceIndexRows || {})) {
+      if (!rows.length) continue;
+      const destination = kind === "references" ? "references/INDEX.md" : "artifacts/INDEX.md";
+      const destinationPath = path.join(directory, destination);
+      const relativePath = toPosix(path.relative(target.projectRoot, destinationPath));
+      changes.push({
+        destination: relativePath,
+        source: `preset-${kind}-index`,
+        action: dryRun ? "would-update" : "update",
+      });
+      assertPresetWriteScope(presetPackage, relativePath);
+      if (dryRun) continue;
+      fs.mkdirSync(path.dirname(destinationPath), { recursive: true });
+      const existing = fs.existsSync(destinationPath) ? fs.readFileSync(destinationPath, "utf8") : "";
+      fs.writeFileSync(destinationPath, renderPresetResourceIndex(existing, kind, rows));
+    }
+  }
+  const task = {
+    id: taskIdForDirectory(target, directory),
+    shortId: normalizedTaskId,
+    title: taskTitle,
+    module: normalizedModuleKey || null,
+    path: `TARGET:${toPosix(path.relative(target.projectRoot, directory))}`,
+    locale: normalizedLocale,
+    budget: normalizedBudget,
+    kind: presetContext?.kind || "general",
+    preset: normalizedPreset,
+    presetVersion: presetContext?.presetVersion || "",
+    presetAudit: presetContext?.audit || null,
+    migrationTargetLevel: presetContext?.migrationTargetLevel || "",
+    migrationAchievedLevel: presetContext?.migrationAchievedLevel || "",
+    evidenceBundle: presetContext?.evidenceBundle || "",
+    longRunning,
+  };
+  const governance = syncTaskGovernance(target, task, { event: "new-task", state: "planned", message: "task registered by CLI", dryRun });
+  changes.push(...governance.changes);
+  const commandWriteScopes = governanceRelativePaths(changes);
+  if (presetContext) {
+    refreshPresetCommandAudit(target, presetContext, { commandWriteScopes, dryRun });
+    task.presetAudit = presetContext.audit;
   }
+  const commit = commitGovernanceSync(governanceContext, commandWriteScopes, {
+    message: `chore(harness): register task ${task.id}`,
+  });
   return {
     dryRun,
-    task: {
-      id: taskIdForDirectory(target, directory),
-      shortId: normalizedTaskId,
-      title: taskTitle,
-      module: normalizedModuleKey || null,
-      path: `TARGET:${toPosix(path.relative(target.projectRoot, directory))}`,
-      locale: normalizedLocale,
-      budget: normalizedBudget,
-      kind: presetContext?.kind || "general",
-      preset: normalizedPreset,
-      presetVersion: presetContext?.presetVersion || "",
-      migrationTargetLevel: presetContext?.migrationTargetLevel || "",
-      migrationAchievedLevel: presetContext?.migrationAchievedLevel || "",
-      evidenceBundle: presetContext?.evidenceBundle || "",
-      longRunning,
-    },
+    task,
     changes,
+    governance: { ...governance, commit },
   };
-}
-
-function readMigrationSession(fromSession) {
-  const sessionPath = path.resolve(fromSession || "");
-  if (!sessionPath || !fs.existsSync(sessionPath)) throw new Error(`Migration session not found: ${fromSession}`);
-  let session;
-  try {
-    session = JSON.parse(fs.readFileSync(sessionPath, "utf8"));
-  } catch (error) {
-    throw new Error(`Invalid migration session JSON: ${error.message}`);
+  } finally {
+    releaseGovernanceSync(governanceContext);
   }
-  if (session.operation !== "migrate-run") throw new Error("legacy-migration preset requires a migrate-run session");
-  if (session.planOnly) throw new Error("legacy-migration preset cannot use plan-only session evidence");
-  if (!session.target || !fs.existsSync(session.target)) throw new Error(`Migration session target missing: ${session.target || "(none)"}`);
-  return { ...session, sourcePath: sessionPath };
 }
 
-function legacyMigrationPresetContext({ target, taskDir, taskId, session }) {
-  const stamp = String(session.generatedAt || new Date().toISOString()).replace(/[^0-9A-Za-z-]+/g, "-").replace(/-+$/g, "");
-  const evidenceBundle = toPosix(path.relative(target.projectRoot, path.join(taskDir, "evidence", stamp || "session")));
-  const targetLevel = "migration-baseline";
-  const achievedLevel = session.strictDeferred ? "migration-deferred" : session.result === "complete" ? "migration-full-cutover" : "migration-baseline";
-  const verifyResult = verifyMigrationSession(session.sourcePath, { fullCutover: false });
-  return {
-    kind: "project-migration",
-    preset: "legacy-migration",
-    presetVersion: "v1",
-    migrationTargetLevel: targetLevel,
-    migrationAchievedLevel: achievedLevel,
-    evidenceBundle,
-    session,
-    evidenceFiles: legacyMigrationEvidenceFiles({ target, session, evidenceBundle, verifyResult }),
+function refreshPresetCommandAudit(target, presetContext, { commandWriteScopes = [], dryRun = false } = {}) {
+  const scopes = [...new Set(commandWriteScopes.filter(Boolean))];
+  presetContext.audit = {
+    ...presetContext.audit,
+    presetWriteScopes: presetContext.audit.writeScopes || [],
+    commandWriteScopes: scopes,
   };
-}
-
-function legacyMigrationEvidenceFiles({ target, session, evidenceBundle, verifyResult }) {
-  const files = [];
-  const addJson = (name, value, source = "session") => files.push({
-    relativePath: path.join(evidenceBundle, name),
-    source,
-    content: `${JSON.stringify(value, null, 2)}\n`,
-  });
-  const addText = (name, value, source = "generated") => files.push({
-    relativePath: path.join(evidenceBundle, name),
-    source,
-    content: `${String(value || "").trim()}\n`,
-  });
-  addJson("session.json", session, "session.json");
-  addJson("migrate-plan.json", session.plan || {}, "migrate-plan.json");
-  addJson("normal-check.json", session.checks?.normal || {}, "session.checks.normal");
-  addJson("strict-check.json", session.checks?.strict || {}, "session.checks.strict");
-  addJson("migrate-verify.json", verifyResult, "migrate-verify");
-  addText("dashboard.hash.txt", dashboardHash(session.dashboard?.indexPath || ""), "dashboard");
-  addText("target-git-status.txt", JSON.stringify(session.git?.after || {}, null, 2), "session.git.after");
-  addText("target-commit.txt", targetCommit(target.projectRoot), "git");
-  addText("harness-version.txt", packageVersion(), "package.json");
-  addText("generated-at.txt", new Date().toISOString(), "generated");
-  return files;
-}
-
-function dashboardHash(indexPath) {
-  if (!indexPath || !fs.existsSync(indexPath)) return "missing";
-  const hash = crypto.createHash("sha256").update(fs.readFileSync(indexPath)).digest("hex");
-  return `sha256:${hash}`;
-}
-
-function targetCommit(projectRoot) {
-  const result = spawnSync("git", ["-C", projectRoot, "rev-parse", "HEAD"], { encoding: "utf8" });
-  return result.status === 0 ? result.stdout.trim() : "n/a";
-}
-
-function packageVersion() {
-  try {
-    return JSON.parse(fs.readFileSync(path.join(repoRoot, "package.json"), "utf8")).version || "unknown";
-  } catch {
-    return "unknown";
+  for (const evidence of presetContext.evidenceFiles || []) {
+    if (evidence.source !== "preset-audit") continue;
+    evidence.content = `${JSON.stringify(presetContext.audit, null, 2)}\n`;
+    if (dryRun) continue;
+    fs.writeFileSync(path.join(target.projectRoot, evidence.relativePath), evidence.content);
   }
 }
 
-function renderPresetTaskTemplate(destination, content, presetContext) {
-  if (!presetContext) return content;
-  if (destination === "task_plan.md") return renderLegacyMigrationTaskPlan(content, presetContext);
-  if (destination === "execution_strategy.md") return `${content.trimEnd()}\n\n${legacyMigrationExecutionStrategy(presetContext)}\n`;
-  if (destination === "findings.md") return `${content.trimEnd()}\n\n${legacyMigrationFindings(presetContext)}\n`;
-  if (destination === "review.md") return `${content.trimEnd()}\n\n${legacyMigrationReview(presetContext)}\n`;
-  if (destination === visualMapFile) return `${content.trimEnd()}\n\n${legacyMigrationVisualMap()}\n`;
-  return content;
-}
-
-function renderLegacyMigrationTaskPlan(content, context) {
-  const metadata = [
-    `Selected budget: complex`,
-    `Task Kind: ${context.kind}`,
-    `Task Preset: ${context.preset}`,
-    `Preset Version: ${context.presetVersion}`,
-    `Migration Target Level: ${context.migrationTargetLevel}`,
-    `Migration Achieved Level: ${context.migrationAchievedLevel}`,
-    `Evidence Bundle: ${context.evidenceBundle}`,
-  ].join("\n");
-  let next = String(content).replace(/^(Task Contract:\s*harness-task\/v1\s*)$/im, `$1\n${metadata}`);
-  next = next.replace("[State the outcome this task must deliver in one sentence.]", "Create a controlled Harness v1 migration task from the recorded migrate-run session without rewriting history automatically.");
-  next = next.replace("[用一句话说明本任务完成后应达到的状态。]", "基于已记录的 migrate-run session 创建受控的 Harness v1 迁移任务，不自动改写历史材料。");
-  return `${next.trimEnd()}\n\n## Legacy Migration Preset\n\nThis Complex Task uses the legacy-migration preset. The preset only scaffolds the task and records evidence. It does not run migration, rewrite historical task bodies, stage files, or commit changes.\n\n- Baseline session: \`${context.evidenceBundle}/session.json\`\n- Migration plan: \`${context.evidenceBundle}/migrate-plan.json\`\n- Strict deferred: ${context.session.strictDeferred ? "yes" : "no"}\n- Full-cutover claim allowed now: ${context.migrationAchievedLevel === "migration-full-cutover" ? "yes" : "no"}\n`;
-}
-
-function legacyMigrationExecutionStrategy(context) {
-  return `## Legacy Migration Preset Strategy
-
-This preset keeps migration inside the Complex Task contract.
-
-| Area | Rule |
-| --- | --- |
-| Write boundary | Do not rewrite historical task bodies unless the user explicitly confirms that phase. |
-| Evidence source | Use \`${context.evidenceBundle}/\` as the handoff bundle. Absolute session paths are origin data only. |
-| Target level | \`${context.migrationTargetLevel}\` |
-| Achieved level | \`${context.migrationAchievedLevel}\` |
-
-## Subagent Lane Table
-
-Declare lanes before dispatching workers.
-
-| Lane ID | Allowed globs | Forbidden globs | Shared file owner | Worktree / branch | Handoff path | Merge order | Verification command |
-| --- | --- | --- | --- | --- | --- | --- | --- |
-| coordinator | docs/09-PLANNING/TASKS/** | AGENTS.md, CLAUDE.md, docs/Harness-Ledger.md until closeout | coordinator | current | progress.md | 1 | harness check --profile target-project . |
-`;
-}
-
-function legacyMigrationFindings(context) {
-  return `## Legacy Migration Action Buckets
-
-| Bucket | Count | Owner | Status | Next Action |
-| --- | ---: | --- | --- | --- |
-| warnings | ${context.session.plan?.summary?.warnings || 0} | coordinator | open | Triage before increasing target level |
-| taskActions | ${context.session.plan?.summary?.taskActions || 0} | coordinator | open | Upgrade only current/reopened/current-evidence tasks |
-| legacyResiduals | ${context.session.plan?.summary?.legacyResiduals || 0} | coordinator | open | Assign real owner before full cutover |
-
-## Residual Policy
-
-Residuals require reason, owner, trigger, next action, and reviewer. Placeholder owner \`migration-owner\` is not a real owner.
-
-## Status Conflict Table
-
-| Item | Competing Evidence | Chosen Classification | Confidence | Human Needed |
-| --- | --- | --- | --- | --- |
-| pending | session / SSoT / progress / git | pending | medium | yes |
-`;
-}
-
-function legacyMigrationReview(context) {
-  return `## Legacy Migration Preset Gate
-
-\`migration-full-cutover\` can only be claimed when the final session proves all gates:
-
-- final session result is \`complete\`
-- strict check passes
-- \`migrate-verify --full-cutover\` passes
-- warnings/actions/residuals/strictDeferred are zero
-- dashboard evidence is readable
-- review has no open P0/P1/P2 blocker
-
-Current achieved level: \`${context.migrationAchievedLevel}\`.
-`;
-}
-
-function legacyMigrationVisualMap() {
-  return `## Legacy Migration Preset Flow
-
-\`\`\`mermaid
-flowchart TD
-  A["Recorded migrate-run session"] --> B["Create Complex Task preset"]
-  B --> C["Baseline usable"]
-  C --> D{"User confirms deeper cutover?"}
-  D -- no --> E["Keep residuals owned"]
-  D -- yes --> F["Current work cutover"]
-  F --> G["Historical consolidation"]
-  G --> H["Strict / full-cutover verify"]
-\`\`\`
-`;
-}
-
 export function updateTaskLifecycle(targetInput, taskId, { event = "task-log", state = "", message = "", evidence = "" } = {}) {
   const target = normalizeTarget(targetInput);
   const taskDir = resolveTaskDirectory(target, taskId);
@@ -556,109 +394,114 @@ export function updateTaskLifecycle(targetInput, taskId, { event = "task-log", s
   const normalizedState = state ? String(state).toLowerCase().replaceAll("-", "_") : "";
   if (normalizedState && !allowedTaskStates.has(normalizedState)) throw new Error(`Invalid task state: ${state}`);
   const currentTask = findTaskByDirectory(target, taskDir);
+  const canonicalTaskId = taskIdForDirectory(target, taskDir);
   const budget = parseTaskBudget(readFileSafe(path.join(taskDir, "task_plan.md")));
   validateLifecycleTransition({
     event,
     currentState: currentTask?.state || "unknown",
     budget,
     reviewContent: readFileSafe(path.join(taskDir, "review.md")),
+    reviewTaskKey: canonicalTaskId,
+    projectRoot: target.projectRoot,
+    taskDir,
   });
   if (event === "task-review") validateReviewEntryGate(taskDir, budget);
-  let content = readFileSafe(progressPath);
-  if (normalizedState) content = updateProgressState(content, normalizedState, registry.locale);
-  content = appendProgressLog(content, { event, message, evidence });
-  fs.writeFileSync(progressPath, content.endsWith("\n") ? content : `${content}\n`);
-  return {
-    event,
-    task: findTaskByDirectory(target, taskDir) || { id: taskIdForDirectory(target, taskDir), state: normalizedState || "unknown" },
-  };
+  const governanceContext = beginGovernanceSync(target, { operation: `${event} ${canonicalTaskId}` });
+  try {
+    let content = readFileSafe(progressPath);
+    if (normalizedState) content = updateProgressState(content, normalizedState, registry.locale);
+    content = appendProgressLog(content, { event, message, evidence });
+    fs.writeFileSync(progressPath, content.endsWith("\n") ? content : `${content}\n`);
+    const allowedPaths = [toPosix(path.relative(target.projectRoot, progressPath))];
+    if (event === "task-review") {
+      const reviewPath = path.join(taskDir, "review.md");
+      const reviewContent = readFileSafe(reviewPath);
+      fs.writeFileSync(
+        reviewPath,
+        replaceAgentReviewSubmission(
+          reviewContent,
+          renderAgentReviewSubmission({
+            target,
+            taskDir,
+            canonicalTaskId,
+            message,
+            evidence,
+          }),
+        ),
+      );
+      allowedPaths.push(toPosix(path.relative(target.projectRoot, reviewPath)));
+    }
+    const task =
+      findTaskByDirectory(target, taskDir) ||
+      {
+        id: canonicalTaskId,
+        shortId: path.basename(taskDir),
+        title: canonicalTaskId,
+        path: `TARGET:${toPosix(path.relative(target.projectRoot, taskDir))}`,
+        state: normalizedState || currentTask?.state || "unknown",
+      };
+    const governanceState = normalizedState || task.state || currentTask?.state || "planned";
+    const governance = syncTaskGovernance(target, task, { event, state: governanceState, message, dryRun: false });
+    const commit = commitGovernanceSync(governanceContext, [...allowedPaths, ...governanceRelativePaths(governance.changes)], {
+      message: `chore(harness): advance task ${canonicalTaskId} to ${governanceState}`,
+    });
+    return {
+      event,
+      task,
+      governance: { ...governance, commit },
+    };
+  } finally {
+    releaseGovernanceSync(governanceContext);
+  }
 }
 
 export function confirmTaskReview(targetInput, taskId, { reviewer = "Human Reviewer", message = "", confirmText = "", evidence = "" } = {}) {
   const target = normalizeTarget(targetInput);
   const taskDir = resolveTaskDirectory(target, taskId);
-  assertTaskDirectoryInsidePlanning(target, taskDir);
-  const canonicalTaskId = taskIdForDirectory(target, taskDir);
-  const shortId = path.basename(taskDir);
-  if (confirmText && ![shortId, canonicalTaskId].includes(confirmText)) {
-    throw new Error(`Review confirmation text must match task id: ${shortId}`);
-  }
-  if (!confirmText) throw new Error(`Missing review confirmation text: ${shortId}`);
-
-  const reviewPath = path.join(taskDir, "review.md");
-  const progressPath = path.join(taskDir, "progress.md");
-  const reviewContent = readFileSafe(reviewPath);
-  const budget = parseTaskBudget(readFileSafe(path.join(taskDir, "task_plan.md")));
-  const candidateStatus = parseLessonCandidateStatus(readFileSafe(path.join(taskDir, lessonCandidatesFile)));
-  const blockingRisks = collectReviewRisks(reviewContent).filter(isBlockingReviewRisk);
-  if (blockingRisks.length > 0) {
-    const ids = blockingRisks.map((risk) => risk.id || risk.severity).join(", ");
-    throw new Error(`Open blocking review findings must be closed before confirmation: ${ids}`);
-  }
-  validateHumanReviewConfirmation({
-    task: findTaskByDirectory(target, taskDir),
-    budget,
-  });
-  if (budget !== "simple" && !isLessonCandidateDecisionComplete(candidateStatus)) {
-    throw new Error(`Human review confirmation requires lesson candidate decision complete; current status is ${candidateStatus.status}.`);
-  }
-
+  return confirmTaskReviewWithContext({ target, taskDir, findTaskByDirectory }, { reviewer, message, confirmText, evidence });
+}
+function renderAgentReviewSubmission({ target, taskDir, canonicalTaskId, message, evidence }) {
   const timestamp = nowTimestamp();
-  const safeReviewer = markdownCell(reviewer || "Human Reviewer");
-  const safeMessage = markdownCell(message || "Human review confirmed");
-  const safeEvidence = markdownCell(evidence || `TARGET:docs/09-PLANNING/${canonicalTaskId}/review.md`);
-  const confirmationBlock = [
-    "## Human Review Confirmation",
-    "",
-    `Reviewer: ${safeReviewer}`,
+  const submissionId = `ARS-${timestamp.replace(/[^0-9]/g, "").slice(0, 14)}`;
+  const materialsHash = hashTaskMaterials(taskDir);
+  const reviewContent = readFileSafe(path.join(taskDir, "review.md"));
+  const openFindings = collectReviewRisks(reviewContent).filter(isBlockingReviewRisk).length;
+  const evidenceSummary = evidence || message || "Agent submitted task for human review.";
+  return [
+    "## Agent Review Submission",
     "",
-    "| Confirmed At | Reviewer | Message | Evidence |",
-    "| --- | --- | --- | --- |",
-    `| ${timestamp} | ${safeReviewer} | ${safeMessage} | ${safeEvidence} |`,
+    "| Field | Value |",
+    "| --- | --- |",
+    `| Submission ID | ${submissionId} |`,
+    `| Submitted At | ${timestamp} |`,
+    "| Submitted By | agent |",
+    `| Task Key | ${canonicalTaskId} |`,
+    `| Materials Checklist Hash | ${materialsHash} |`,
+    `| Evidence Summary | ${markdownCell(evidenceSummary)} |`,
+    `| Open Findings Count | ${openFindings} |`,
+    `| Scanner Version | ${taskScannerVersion} |`,
+    `| Target | TARGET:${toPosix(path.relative(target.projectRoot, taskDir))} |`,
     "",
   ].join("\n");
-  const nextReview = replaceReviewConfirmation(reviewContent, confirmationBlock);
-  fs.writeFileSync(reviewPath, nextReview.endsWith("\n") ? nextReview : `${nextReview}\n`);
-
-  let progressContent = readFileSafe(progressPath);
-  progressContent = appendProgressLog(progressContent, {
-    event: "review-confirm",
-    message: message || `Human review confirmed by ${reviewer}`,
-    evidence: evidence || `TARGET:docs/09-PLANNING/${canonicalTaskId}/review.md`,
-    actor: reviewer || "Human Reviewer",
-  });
-  fs.writeFileSync(progressPath, progressContent.endsWith("\n") ? progressContent : `${progressContent}\n`);
-
-  return {
-    event: "review-confirm",
-    task: findTaskByDirectory(target, taskDir) || { id: canonicalTaskId, reviewStatus: "confirmed" },
-  };
-}
-
-function assertTaskDirectoryInsidePlanning(target, taskDir) {
-  const realTaskDir = fs.realpathSync(taskDir);
-  const allowedRoots = [
-    path.join(target.docsRoot, "09-PLANNING/TASKS"),
-    path.join(target.docsRoot, "09-PLANNING/MODULES"),
-  ].filter(fs.existsSync).map((root) => fs.realpathSync(root));
-  if (!allowedRoots.some((root) => realTaskDir === root || realTaskDir.startsWith(`${root}${path.sep}`))) {
-    throw new Error(`Task directory outside planning root: ${taskIdForDirectory(target, taskDir)}`);
-  }
-}
-
-function markdownCell(value) {
-  return String(value || "")
-    .replace(/\r?\n/g, " ")
-    .replaceAll("|", "\\|")
-    .trim();
 }
-
-function replaceReviewConfirmation(content, block) {
+function replaceAgentReviewSubmission(content, block) {
   const trimmed = String(content || "").trimEnd();
-  if (/^##\s*(?:Human Review Confirmation|人工审查确认)\s*$/im.test(trimmed)) {
-    return trimmed.replace(/^##\s*(?:Human Review Confirmation|人工审查确认)\s*$[\s\S]*?(?=^##\s+|\s*$)/im, block.trimEnd());
+  if (/^##\s*(?:Agent Review Submission|Agent 审查提交|Agent 提交审查)\s*$/im.test(trimmed)) {
+    return `${trimmed.replace(/^##\s*(?:Agent Review Submission|Agent 审查提交|Agent 提交审查)\s*$[\s\S]*?(?=^##\s+|(?![\s\S]))/im, `${block.trimEnd()}\n\n`)}\n`;
+  }
+  return `${trimmed}\n\n${block.trimEnd()}\n`;
+}
+function hashTaskMaterials(taskDir) {
+  const hash = crypto.createHash("sha256");
+  for (const fileName of ["brief.md", "task_plan.md", visualMapFile, lessonCandidatesFile, "progress.md", "review.md", "findings.md", longRunningTaskContractFile]) {
+    const filePath = path.join(taskDir, fileName);
+    if (!fs.existsSync(filePath)) continue;
+    hash.update(fileName);
+    hash.update("\0");
+    hash.update(readFileSafe(filePath));
+    hash.update("\0");
   }
-  return `${trimmed}\n\n${block}`;
+  return hash.digest("hex").slice(0, 16);
 }
 
 export function updateTaskPhase(targetInput, taskId, phaseId, { state = "", completion = "", evidenceStatus = "" } = {}) {
@@ -692,9 +535,17 @@ export function updateTaskPhase(targetInput, taskId, phaseId, { state = "", comp
     return next;
   });
   if (!phaseUpdate.matched) throw new Error(`Phase not found: ${phaseId}`);
-  content = phaseUpdate.content;
-  fs.writeFileSync(visualMapPath, content);
-  return { event: "task-phase", task: findTaskByDirectory(target, taskDir), phaseId };
+  const governanceContext = beginGovernanceSync(target, { operation: `task-phase ${taskId} ${phaseId}` });
+  try {
+    content = phaseUpdate.content;
+    fs.writeFileSync(visualMapPath, content);
+    const commit = commitGovernanceSync(governanceContext, [toPosix(path.relative(target.projectRoot, visualMapPath))], {
+      message: `chore(harness): update task phase ${taskId} ${phaseId}`,
+    });
+    return { event: "task-phase", task: findTaskByDirectory(target, taskDir), phaseId, governance: { commit } };
+  } finally {
+    releaseGovernanceSync(governanceContext);
+  }
 }
 
 export function updateModuleStep(targetInput, moduleKey, stepId, { state = "" } = {}) {
@@ -714,42 +565,85 @@ export function updateModuleStep(targetInput, moduleKey, stepId, { state = "" }
     return next;
   });
   if (!stepUpdate.matched) throw new Error(`Module step not found: ${stepId}`);
-  content = stepUpdate.content;
-  fs.writeFileSync(modulePlanPath, content);
-
-  const registryPath = path.join(target.docsRoot, "09-PLANNING/Module-Registry.md");
-  if (fs.existsSync(registryPath)) {
-    let registry = readFileSafe(registryPath);
-    const registryUpdate = updateMarkdownTableRow(registry, /^(ID|模块 Key)$/i, (header, row) => {
-      const moduleIndex = firstColumn(header, ["Module", "模块", "模块 Key"]);
-      const taskPlanIndex = getColumn(header, "Task Plan");
-      const matchesModule = normalizeTaskId(row[moduleIndex] || "") === normalizedModuleKey;
-      const matchesPlan = taskPlanIndex >= 0 && String(row[taskPlanIndex] || "").includes(`/MODULES/${normalizedModuleKey}/`);
-      if (!matchesModule && !matchesPlan) return null;
-      const next = [...row];
-      const statusIndex = firstColumn(header, ["Status", "状态"]);
-      const updatedIndex = firstColumn(header, ["Updated", "更新时间"]);
-      const currentStepIndex = firstColumn(header, ["Current Step", "当前步骤"]);
-      const chineseRegistry = header.some((cell) => /模块 Key|模块名称|状态|更新时间/.test(cell));
-      if (statusIndex >= 0) {
-        next[statusIndex] = normalizedState === "done"
-          ? chineseRegistry ? "completed" : "merged"
-          : normalizedState === "in-progress" ? chineseRegistry ? "in-progress" : "active" : normalizedState;
-      }
-      if (currentStepIndex >= 0) next[currentStepIndex] = stepId;
-      if (updatedIndex >= 0) next[updatedIndex] = todayDate();
-      return next;
-    });
-    registry = registryUpdate.content;
-    fs.writeFileSync(registryPath, registry);
+  const governanceContext = beginGovernanceSync(target, { operation: `module-step ${normalizedModuleKey} ${stepId}` });
+  try {
+    content = stepUpdate.content;
+    fs.writeFileSync(modulePlanPath, content);
+
+    const registryPath = path.join(target.docsRoot, "09-PLANNING/Module-Registry.md");
+    if (fs.existsSync(registryPath)) {
+      let registry = readFileSafe(registryPath);
+      const registryUpdate = updateMarkdownTableRow(registry, /^(ID|模块 Key)$/i, (header, row) => {
+        const moduleIndex = firstColumn(header, ["Module", "模块", "模块 Key"]);
+        const taskPlanIndex = getColumn(header, "Task Plan");
+        const matchesModule = normalizeTaskId(row[moduleIndex] || "") === normalizedModuleKey;
+        const matchesPlan = taskPlanIndex >= 0 && String(row[taskPlanIndex] || "").includes(`/MODULES/${normalizedModuleKey}/`);
+        if (!matchesModule && !matchesPlan) return null;
+        const next = [...row];
+        const statusIndex = firstColumn(header, ["Status", "状态"]);
+        const updatedIndex = firstColumn(header, ["Updated", "更新时间"]);
+        const currentStepIndex = firstColumn(header, ["Current Step", "当前步骤"]);
+        const chineseRegistry = header.some((cell) => /模块 Key|模块名称|状态|更新时间/.test(cell));
+        if (statusIndex >= 0) {
+          next[statusIndex] = normalizedState === "done"
+            ? chineseRegistry ? "completed" : "merged"
+            : normalizedState === "in-progress" ? chineseRegistry ? "in-progress" : "active" : normalizedState;
+        }
+        if (currentStepIndex >= 0) next[currentStepIndex] = stepId;
+        if (updatedIndex >= 0) next[updatedIndex] = todayDate();
+        return next;
+      });
+      registry = registryUpdate.content;
+      fs.writeFileSync(registryPath, registry);
+    }
+    const governance = syncModuleStepGovernance(target, { moduleKey: normalizedModuleKey, stepId, state: normalizedState });
+    const commit = commitGovernanceSync(
+      governanceContext,
+      [
+        toPosix(path.relative(target.projectRoot, modulePlanPath)),
+        toPosix(path.relative(target.projectRoot, registryPath)),
+        ...governanceRelativePaths(governance.changes),
+      ],
+      { message: `chore(harness): update module ${normalizedModuleKey} step ${stepId}` },
+    );
+    return { event: "module-step", moduleKey: normalizedModuleKey, stepId, state: normalizedState, governance: { ...governance, commit } };
+  } finally {
+    releaseGovernanceSync(governanceContext);
   }
-  return { event: "module-step", moduleKey: normalizedModuleKey, stepId, state: normalizedState };
 }
 
-export function listLifecycleTasks(targetInput, { state = "", moduleKey = "" } = {}) {
+export function listLifecycleTasks(targetInput, { state = "", moduleKey = "", queue = "", preset = "", review = "", lesson = "", search = "", missingMaterials = false } = {}) {
   const target = normalizeTarget(targetInput);
   let tasks = collectTasks(target);
   if (state) tasks = tasks.filter((task) => task.state === String(state).toLowerCase().replaceAll("-", "_"));
   if (moduleKey) tasks = tasks.filter((task) => task.module === normalizeTaskId(moduleKey));
+  if (queue) {
+    const normalizedQueue = queryToken(queue);
+    tasks = tasks.filter((task) => (task.taskQueues || []).map(queryToken).includes(normalizedQueue));
+  }
+  if (preset) tasks = tasks.filter((task) => queryToken(task.taskPreset || "none") === queryToken(preset));
+  if (review) tasks = tasks.filter((task) => queryToken(task.reviewStatus || "") === queryToken(review));
+  if (lesson) {
+    const needle = queryToken(lesson);
+    tasks = tasks.filter((task) => [task.lessonCandidateStatus, task.lessonCandidateReviewDecision, task.lessonCandidatePromotionState].some((value) => queryToken(value) === needle));
+  }
+  if (missingMaterials) tasks = tasks.filter((task) => !task.materialsReady);
+  if (search) {
+    const needle = String(search).toLowerCase();
+    tasks = tasks.filter((task) => [
+      task.id,
+      task.taskKey,
+      task.shortId,
+      task.title,
+      task.currentPath,
+      task.taskPlanPath,
+      task.module,
+      task.inferredModule,
+    ].some((value) => String(value || "").toLowerCase().includes(needle)));
+  }
   return { tasks };
 }
+
+function queryToken(value) {
+  return String(value || "").trim().toLowerCase().replaceAll("_", "-");
+}