coding-agent-harness 1.0.2 → 1.0.4

package/scripts/lib/task-scanner.mjs

@@ -18,31 +18,48 @@ import {
   firstColumn,
   splitList,
   splitDependencies,
-  getColumn,
 } from "./markdown-utils.mjs";
-
-export const allowedLessonCandidateTaskStatuses = new Set([
-  "missing",
-  "pending-review",
-  "no-candidate-accepted",
-  "needs-promotion",
-  "promoted",
-  "rejected",
-]);
-
-export const allowedLessonCandidateRowStatuses = new Set([
-  "ready-for-review",
-  "needs-promotion",
-  "promoted",
-  "rejected",
-]);
-
-export const reviewCompleteLessonCandidateStatuses = new Set([
-  "no-candidate-accepted",
-  "needs-promotion",
-  "promoted",
-  "rejected",
-]);
+import {
+  isLessonCandidateDecisionComplete,
+  parseLessonCandidateStatus,
+  validateLessonCandidateDetailArtifacts,
+} from "./task-lesson-candidates.mjs";
+import {
+  assessMaterialsReadiness,
+  collectReviewRisks,
+  collectStateConflicts,
+  deriveLifecycleState,
+  deriveReviewQueueState,
+  deriveTaskQueues,
+  isBlockingReviewRisk,
+  parseAgentReviewSubmission,
+  parseReviewConfirmation,
+  parseTaskIdentity,
+  parseTaskTombstone,
+  requiresReviewMaterials,
+  taskReviewStatus,
+  taskScannerVersion,
+} from "./task-review-model.mjs";
+export {
+  collectReviewRisks,
+  deriveLifecycleState,
+  deriveReviewQueueState,
+  isBlockingReviewRisk,
+  parseAgentReviewSubmission,
+  parseReviewConfirmation,
+  parseTaskIdentity,
+  parseTaskTombstone,
+  requiresReviewMaterials,
+  taskReviewStatus,
+  taskScannerVersion,
+} from "./task-review-model.mjs";
+export {
+  allowedLessonCandidateRowStatuses,
+  allowedLessonCandidateTaskStatuses,
+  isLessonCandidateDecisionComplete,
+  parseLessonCandidateStatus,
+  reviewCompleteLessonCandidateStatuses,
+} from "./task-lesson-candidates.mjs";
 
 export function parseTaskState(progressContent) {
   return parseTaskStateInfo(progressContent).state;
@@ -307,7 +324,11 @@ export function collectTasks(target) {
     const visualMap = readVisualMapContractFile(taskDir, taskPlan);
     const progress = readFileSafe(progressPath);
     const review = readFileSafe(reviewPath);
-    const lessonCandidates = parseLessonCandidateStatus(readFileSafe(lessonCandidatesPath));
+    const parsedLessonCandidates = parseLessonCandidateStatus(readFileSafe(lessonCandidatesPath));
+    const lessonDetailIssues = validateLessonCandidateDetailArtifacts(target, taskDir, parsedLessonCandidates);
+    const lessonCandidates = lessonDetailIssues.length
+      ? { ...parsedLessonCandidates, issues: [...parsedLessonCandidates.issues, ...lessonDetailIssues] }
+      : parsedLessonCandidates;
     const phases = parsePhases(visualMap.content);
     const completion =
       phases.length > 0
@@ -318,6 +339,8 @@ export function collectTasks(target) {
         : 0;
     const relative = toPosix(path.relative(target.projectRoot, taskDir));
     const id = taskIdForDirectory(target, taskDir);
+    const identity = parseTaskIdentity(taskPlan, id);
+    const tombstone = parseTaskTombstone(taskPlan);
     const title = titleFromMarkdown(brief.content || taskPlan, path.basename(taskDir));
     const stateInfo = parseTaskStateInfo(progress);
     const budget = parseTaskBudget(taskPlan);
@@ -329,13 +352,70 @@ export function collectTasks(target) {
     const briefVisualStatus = explicitVisualMapStatus(brief.content);
     const visualMapStatus = briefVisualStatus === "not-needed" && visualMap.status === "missing" ? "not-needed" : visualMap.status;
     const risks = collectReviewRisks(review);
-    const reviewConfirmation = parseReviewConfirmation(review);
-    const reviewStatus = taskReviewStatus({ reviewContent: review, risks, confirmation: reviewConfirmation });
+    const reviewSubmission = parseAgentReviewSubmission(review, { taskKey: identity.taskKey });
+    const reviewConfirmation = parseReviewConfirmation(review, {
+      taskKey: identity.taskKey,
+      projectRoot: target.projectRoot,
+      taskDir,
+      reviewPath,
+      progressPath,
+    });
+    const reviewStatus = taskReviewStatus({ reviewContent: review, risks, confirmation: reviewConfirmation, submission: reviewSubmission });
     const closeoutInfo = taskCloseoutInfo(target, taskPlanPath);
     const lifecycleState = deriveLifecycleState({ state: stateInfo.state, reviewStatus, closeoutStatus: closeoutInfo.status });
+    const materialReadiness = assessMaterialsReadiness({
+      budget,
+      taskDir,
+      taskPlan,
+      brief,
+      visualMap,
+      reviewSubmission,
+      lessonCandidates,
+      phases,
+      longRunningContractPath,
+      reviewSurfaceRequired: requiresReviewMaterials({
+        state: stateInfo.state,
+        lifecycleState,
+        closeoutStatus: closeoutInfo.status,
+      }),
+    });
     const stateConflicts = collectStateConflicts({ state: stateInfo.state, reviewStatus, closeoutStatus: closeoutInfo.status, lifecycleState });
+    const reviewQueueState = deriveReviewQueueState({
+      state: stateInfo.state,
+      lifecycleState,
+      reviewStatus,
+      closeoutStatus: closeoutInfo.status,
+      budget,
+      walkthroughPath: closeoutInfo.walkthroughPath,
+      lessonCandidateDecisionComplete: isLessonCandidateDecisionComplete(lessonCandidates),
+      materialsReady: materialReadiness.ready,
+      deletionState: tombstone.deletionState,
+    });
+    const queueModel = deriveTaskQueues({
+      id,
+      title,
+      state: stateInfo.state,
+      budget,
+      reviewStatus,
+      reviewSubmission,
+      reviewConfirmation,
+      reviewQueueState,
+      materialIssues: materialReadiness.issues,
+      risks,
+      stateConflicts,
+      lessonCandidates,
+      closeoutStatus: closeoutInfo.status,
+      tombstone,
+      taskDir,
+      target,
+    });
     return {
       id,
+      taskKey: identity.taskKey,
+      currentPath: `TARGET:${relative}`,
+      originalPath: `TARGET:${relative}`,
+      aliases: [],
+      identitySource: identity.identitySource,
       shortId: path.basename(taskDir),
       title,
       path: `TARGET:${relative}`,
@@ -368,11 +448,19 @@ export function collectTasks(target) {
       presetVersion: metadata.presetVersion,
       migrationTargetLevel: metadata.migrationTargetLevel,
       migrationAchievedLevel: metadata.migrationAchievedLevel,
-      evidenceBundle: metadata.evidenceBundle,
+      evidenceBundle: formatEvidenceBundle(metadata.evidenceBundle),
       migrationSnapshot: collectMigrationSnapshot(target, metadata),
       lifecycleState,
       reviewStatus,
+      reviewSubmitted: Boolean(reviewSubmission?.submitted),
+      reviewSubmission,
+      reviewQueueState,
       reviewConfirmation,
+      materialsReady: materialReadiness.ready,
+      materialIssues: materialReadiness.issues,
+      taskQueues: queueModel.taskQueues,
+      queueReasons: queueModel.queueReasons,
+      repairPrompt: queueModel.repairPrompt,
       closeoutStatus: closeoutInfo.status,
       walkthroughPath: closeoutInfo.walkthroughPath ? `TARGET:${closeoutInfo.walkthroughPath}` : "",
       lessonCandidatePath: fs.existsSync(lessonCandidatesPath)
@@ -383,6 +471,7 @@ export function collectTasks(target) {
       lessonCandidatePromotionState: lessonCandidates.promotionState,
       lessonCandidateCloseoutToken: lessonCandidates.closeoutToken,
       lessonCandidateRowCount: lessonCandidates.rows.length,
+      lessonCandidateRows: lessonCandidates.rows,
       lessonCandidateOpenCount: lessonCandidates.openCount,
       lessonCandidateIssues: lessonCandidates.issues,
       lessonCandidateDecisionComplete: isLessonCandidateDecisionComplete(lessonCandidates),
@@ -390,6 +479,16 @@ export function collectTasks(target) {
         ? `TARGET:${toPosix(path.relative(target.projectRoot, longRunningContractPath))}`
         : "",
       longRunningContractStatus: fs.existsSync(longRunningContractPath) ? "present" : "missing",
+      deletionState: tombstone.deletionState,
+      supersededBy: tombstone.supersededBy,
+      supersedes: tombstone.supersedes,
+      deleteReason: tombstone.deleteReason,
+      hiddenByDefault: tombstone.hiddenByDefault,
+      reopenEligible: tombstone.reopenEligible,
+      archiveEligible: tombstone.archiveEligible,
+      tombstoneSourcePath: tombstone.tombstoneSourcePath
+        ? `TARGET:${toPosix(path.relative(target.projectRoot, path.join(taskDir, "task_plan.md")))}#Task Tombstone`
+        : "",
       stateConflicts,
       completion,
       phases,
@@ -432,136 +531,11 @@ function collectMigrationSnapshot(target, metadata) {
   };
 }
 
-export function parseLessonCandidateStatus(content) {
-  const text = String(content || "");
-  if (!text.trim()) {
-    return emptyLessonCandidateStatus("missing", ["missing-candidate-file"]);
-  }
-
-  const fields = lessonCandidateFields(text);
-  const declaredStatus = normalizeLessonCandidateStatus(fields.get("task-level status") || "pending-review");
-  const reviewDecision = normalizeCandidateField(fields.get("review decision") || "pending-human-review");
-  const promotionState = normalizeCandidateField(fields.get("promotion state") || "not-promoted");
-  const closeoutToken = String(fields.get("closeout token") || "pending").trim();
-  const rows = lessonCandidateRows(text);
-  const issues = [];
-
-  if (!allowedLessonCandidateTaskStatuses.has(declaredStatus)) {
-    issues.push(`invalid-task-status:${declaredStatus}`);
-  }
-  for (const row of rows) {
-    if (!allowedLessonCandidateRowStatuses.has(row.status)) issues.push(`invalid-row-status:${row.id || "missing-id"}:${row.status}`);
-  }
-
-  const aggregateStatus = aggregateLessonCandidateStatus(rows, declaredStatus);
-  if (declaredStatus !== aggregateStatus && declaredStatus !== "missing") {
-    issues.push(`status-aggregate-mismatch:${declaredStatus}->${aggregateStatus}`);
-  }
-  if (aggregateStatus === "no-candidate-accepted" && !noCandidateReason(text)) {
-    issues.push("missing-no-candidate-reason");
-  }
-
-  return {
-    status: aggregateStatus,
-    declaredStatus,
-    schemaVersion: fields.get("schema version") || "",
-    reviewDecision,
-    promotionState,
-    closeoutToken,
-    rows,
-    openCount: rows.filter((row) => ["ready-for-review", "needs-promotion"].includes(row.status)).length,
-    issues,
-  };
-}
-
-export function isLessonCandidateDecisionComplete(candidateStatus) {
-  if (!candidateStatus || candidateStatus.issues?.length) return false;
-  return reviewCompleteLessonCandidateStatuses.has(candidateStatus.status);
+function formatEvidenceBundle(value) {
+  const normalized = String(value || "").replace(/^TARGET:/, "").replace(/^\/+/, "");
+  return normalized ? `TARGET:${normalized}` : "";
 }
 
-function emptyLessonCandidateStatus(status, issues = []) {
-  return {
-    status,
-    declaredStatus: status,
-    schemaVersion: "",
-    reviewDecision: "",
-    promotionState: "",
-    closeoutToken: "",
-    rows: [],
-    openCount: 0,
-    issues,
-  };
-}
-
-function lessonCandidateFields(content) {
-  const { header, rows } = tableAfterHeading(content, /^Field$/i);
-  const fieldIndex = firstColumn(header, ["Field", "字段"]);
-  const valueIndex = firstColumn(header, ["Value", "值"]);
-  const fields = new Map();
-  if (fieldIndex < 0 || valueIndex < 0) return fields;
-  for (const row of rows) {
-    const key = String(row[fieldIndex] || "").trim().toLowerCase();
-    if (key) fields.set(key, String(row[valueIndex] || "").trim());
-  }
-  return fields;
-}
-
-function lessonCandidateRows(content) {
-  const { header, rows } = tableAfterHeading(content, /^ID$/i);
-  const idIndex = firstColumn(header, ["ID", "候选 ID"]);
-  const statusIndex = firstColumn(header, ["Row Status", "行状态", "Status", "状态"]);
-  const titleIndex = firstColumn(header, ["Title", "标题"]);
-  const decisionIndex = firstColumn(header, ["Review Decision", "审查决定"]);
-  const targetIndex = firstColumn(header, ["Promotion Target", "沉淀目标"]);
-  if (idIndex < 0 || statusIndex < 0) return [];
-  return rows
-    .filter((row) => /^LC-[A-Za-z0-9-]+$/i.test(row[idIndex] || ""))
-    .map((row) => ({
-      id: row[idIndex] || "",
-      status: normalizeLessonCandidateStatus(row[statusIndex] || ""),
-      title: row[titleIndex] || "",
-      reviewDecision: row[decisionIndex] || "",
-      promotionTarget: row[targetIndex] || "",
-    }));
-}
-
-function normalizeLessonCandidateStatus(value) {
-  return String(value || "")
-    .replace(/`/g, "")
-    .trim()
-    .toLowerCase()
-    .replaceAll("_", "-")
-    .replace(/\s+/g, "-");
-}
-
-function normalizeCandidateField(value) {
-  return String(value || "").replace(/`/g, "").trim().toLowerCase().replaceAll("_", "-").replace(/\s+/g, "-");
-}
-
-function aggregateLessonCandidateStatus(rows, declaredStatus) {
-  if (rows.length === 0) return declaredStatus === "no-candidate-accepted" ? "no-candidate-accepted" : declaredStatus;
-  const statuses = rows.map((row) => row.status);
-  if (statuses.includes("ready-for-review")) return "pending-review";
-  if (statuses.includes("needs-promotion")) return "needs-promotion";
-  if (statuses.every((status) => status === "promoted")) return "promoted";
-  if (statuses.every((status) => status === "rejected")) return "rejected";
-  if (statuses.every((status) => ["promoted", "rejected"].includes(status))) return "promoted";
-  return declaredStatus;
-}
-
-function noCandidateReason(content) {
-  const lines = String(content || "").split(/\r?\n/);
-  const start = lines.findIndex((line) => /^##\s*No-Candidate Reason\s*$/i.test(line.trim()));
-  if (start < 0) return "";
-  const body = [];
-  for (const line of lines.slice(start + 1)) {
-    if (/^##\s+/.test(line)) break;
-    body.push(line);
-  }
-  return body.join("\n").replace(/`/g, "").trim();
-}
-
-
 function taskCloseoutInfo(target, taskPlanPath) {
   const closeout = readFileSafe(path.join(target.docsRoot, "10-WALKTHROUGH/Closeout-SSoT.md"));
   if (!closeout.trim()) return { status: "missing", walkthroughPath: "" };
@@ -585,91 +559,11 @@ function extractWalkthroughPath(target, closeoutLine) {
   return projectRelative;
 }
 
-export function parseReviewConfirmation(reviewContent) {
-  const match = String(reviewContent || "").match(/^##\s*(?:Human Review Confirmation|人工审查确认)\s*$([\s\S]*?)(?=^##\s+|\s*$)/im);
-  if (!match) return null;
-  const block = match[1] || "";
-  const timeMatch = block.match(/\|\s*(\d{4}-\d{2}-\d{2}[^|]*)\|/);
-  const reviewerMatch = block.match(/Reviewer\s*[:：]\s*([^\n]+)/i) || block.match(/审查人\s*[:：]\s*([^\n]+)/);
-  return {
-    confirmed: true,
-    confirmedAt: timeMatch ? timeMatch[1].trim() : "",
-    reviewer: reviewerMatch ? reviewerMatch[1].trim() : "",
-  };
-}
-
-export function taskReviewStatus({ reviewContent = "", risks = [], confirmation = null } = {}) {
-  if (risks.some(isBlockingReviewRisk)) return "blocked-open-findings";
-  if (confirmation?.confirmed) return "confirmed";
-  if (!String(reviewContent || "").trim()) return "missing";
-  if (/Verdict\s*[:：]\s*yes/i.test(reviewContent) || /本轮已检查|未发现阻塞目标的重要发现/.test(reviewContent)) return "reviewed-unconfirmed";
-  return "required";
-}
-
-export function isBlockingReviewRisk(risk) {
-  return /^P[0-2]$/i.test(risk?.severity || "") && (risk.open || risk.blocksRelease);
-}
-
-export function deriveLifecycleState({ state = "unknown", reviewStatus = "missing", closeoutStatus = "missing" } = {}) {
-  if (closeoutStatus === "closed") return "closed";
-  if (state === "blocked") return "blocked";
-  if (reviewStatus === "blocked-open-findings") return "review-blocked";
-  if (state === "done") return "closing";
-  if (state === "review") return "in_review";
-  if (state === "in_progress") return "active";
-  if (["planned", "not_started"].includes(state)) return "ready";
-  return "unknown";
-}
-
-function collectStateConflicts({ state, reviewStatus, closeoutStatus, lifecycleState }) {
-  const conflicts = [];
-  if (state === "done" && closeoutStatus !== "closed") {
-    conflicts.push({
-      code: "done-without-closeout",
-      severity: "warn",
-      message: "Task state is done, but closeout is still missing or pending.",
-    });
-  }
-  if (reviewStatus === "blocked-open-findings") {
-    conflicts.push({
-      code: "review-blocked-open-findings",
-      severity: "block",
-      message: "Open P0-P2 review findings block human review confirmation.",
-    });
-  }
-  if (lifecycleState === "closed" && reviewStatus === "blocked-open-findings") {
-    conflicts.push({
-      code: "closed-with-blocking-review",
-      severity: "block",
-      message: "Closeout is closed while review findings still block release.",
-    });
-  }
-  return conflicts;
-}
-
 function collectHandoffs(progressContent, taskId) {
   if (!/Coordinator Handoff/i.test(progressContent) || !/pending-coordinator-pass/i.test(progressContent)) return [];
   return [{ id: `H-${taskId}`, from: "worker", to: "coordinator", state: "pending", summary: "Coordinator handoff pending" }];
 }
 
-export function collectReviewRisks(reviewContent) {
-  const { header, rows } = tableAfterHeading(reviewContent, /^ID$/i);
-  const severityIndex = getColumn(header, "Severity");
-  const findingIndex = getColumn(header, "Finding");
-  const openIndex = getColumn(header, "Open");
-  const blocksIndex = getColumn(header, "Blocks Release");
-  if (severityIndex < 0 || findingIndex < 0) return [];
-  return rows
-    .filter((row) => /^P[0-3]$/i.test(row[severityIndex] || ""))
-    .map((row) => ({
-      id: row[0],
-      severity: row[severityIndex],
-      open: /^yes$/i.test(row[openIndex] || "no"),
-      blocksRelease: /^yes$/i.test(row[blocksIndex] || "no"),
-      summary: row[findingIndex],
-    }));
-}
-
 function collectEvidence(progressContent) {
   const matches = [...progressContent.matchAll(/\b(command|diff|fixture|screenshot|review|report):((?:PUBLIC|PRIVATE|TARGET|EXTERNAL|URL):[^:\s|]+):([^\n|]+)/g)];
   return matches.map((match, index) => ({

package/scripts/lib/task-tombstone-commands.mjs

@@ -0,0 +1,140 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  normalizeTarget,
+  nowTimestamp,
+  readFileSafe,
+  toPosix,
+  datePrefix,
+} from "./core-shared.mjs";
+import { collectTasks } from "./task-scanner.mjs";
+import {
+  beginGovernanceSync,
+  commitGovernanceSync,
+  releaseGovernanceSync,
+} from "./governance-sync.mjs";
+
+export function supersedeTask(targetInput, oldRef, { by = "", reason = "" } = {}) {
+  if (!by) throw new Error("task-supersede requires --by <new-task-id>");
+  const target = normalizeTarget(targetInput);
+  const oldTask = resolveTask(target, oldRef);
+  const newTask = resolveTask(target, by);
+  const governanceContext = beginGovernanceSync(target, { operation: `task-supersede ${oldTask.id}` });
+  try {
+    writeTombstone(target, oldTask, {
+      State: "superseded",
+      "Superseded By": newTask.id,
+      Reason: reason || "superseded",
+      Operator: "coordinator",
+      Timestamp: nowTimestamp(),
+      "Reopen Eligible": "yes",
+      "Archive Eligible": "no",
+    });
+    appendProgress(target, oldTask, `task-supersede: superseded by ${newTask.id}`, reason || "superseded");
+    appendSupersedes(target, newTask, oldTask.id);
+    const commit = commitGovernanceSync(contextFor(target, governanceContext), taskPaths(target, oldTask, newTask), {
+      message: `chore(harness): supersede task ${oldTask.id}`,
+    });
+    return { taskId: oldTask.id, supersededBy: newTask.id, reason: reason || "superseded", governance: { commit } };
+  } finally {
+    releaseGovernanceSync(governanceContext);
+  }
+}
+
+export function softDeleteTask(targetInput, taskRef, { reason = "" } = {}) {
+  const target = normalizeTarget(targetInput);
+  const task = resolveTask(target, taskRef);
+  return writeDeletionState(target, task, "soft-deleted", reason || "soft-delete", "task-delete --soft");
+}
+
+export function archiveTask(targetInput, taskRef, { reason = "" } = {}) {
+  const target = normalizeTarget(targetInput);
+  const task = resolveTask(target, taskRef);
+  return writeDeletionState(target, task, "archived", reason || "archive", "task-archive");
+}
+
+export function reopenTask(targetInput, taskRef, { reason = "" } = {}) {
+  const target = normalizeTarget(targetInput);
+  const task = resolveTask(target, taskRef);
+  const governanceContext = beginGovernanceSync(target, { operation: `task-reopen ${task.id}` });
+  try {
+    const taskPlanPath = path.join(target.projectRoot, task.taskPlanPath.replace(/^TARGET:/, ""));
+    const content = readFileSafe(taskPlanPath);
+    const next = content.replace(/\n##\s*(?:Task Tombstone|任务墓碑)\s*$[\s\S]*?(?=^##\s+|(?![\s\S]))/im, "");
+    fs.writeFileSync(taskPlanPath, next.endsWith("\n") ? next : `${next}\n`);
+    appendProgress(target, task, "task-reopen", reason || "reopened");
+    const commit = commitGovernanceSync(governanceContext, taskPaths(target, task), {
+      message: `chore(harness): reopen task ${task.id}`,
+    });
+    return { taskId: task.id, deletionState: "active", reason: reason || "reopened", governance: { commit } };
+  } finally {
+    releaseGovernanceSync(governanceContext);
+  }
+}
+
+function writeDeletionState(target, task, deletionState, reason, action) {
+  const governanceContext = beginGovernanceSync(target, { operation: `${action} ${task.id}` });
+  try {
+    writeTombstone(target, task, {
+      State: deletionState,
+      Reason: reason,
+      Operator: "coordinator",
+      Timestamp: nowTimestamp(),
+      "Reopen Eligible": "yes",
+      "Archive Eligible": deletionState === "archived" ? "yes" : "no",
+    });
+    appendProgress(target, task, action, reason);
+    const commit = commitGovernanceSync(governanceContext, taskPaths(target, task), {
+      message: `chore(harness): ${action.replace(/\s+/g, " ")} ${task.id}`,
+    });
+    return { taskId: task.id, deletionState, reason, governance: { commit } };
+  } finally {
+    releaseGovernanceSync(governanceContext);
+  }
+}
+
+function taskPaths(target, ...tasks) {
+  return [...new Set(tasks.flatMap((task) => [task.taskPlanPath, task.progressPath]).filter(Boolean).map((item) => toPosix(item.replace(/^TARGET:/, ""))))];
+}
+
+function contextFor(_target, context) {
+  return context;
+}
+
+function resolveTask(target, ref) {
+  const normalized = String(ref || "").trim();
+  const matches = collectTasks(target).filter((task) => {
+    const bare = datePrefix.test(task.shortId) ? task.shortId.replace(datePrefix, "") : task.shortId;
+    return task.id === normalized || task.shortId === normalized || task.id.endsWith(`/${normalized}`) || bare === normalized;
+  });
+  if (matches.length === 1) return matches[0];
+  if (matches.length > 1) throw new Error(`Ambiguous task reference: ${ref}`);
+  throw new Error(`Task not found: ${ref}`);
+}
+
+function writeTombstone(target, task, fields) {
+  const taskPlanPath = path.join(target.projectRoot, task.taskPlanPath.replace(/^TARGET:/, ""));
+  const content = readFileSafe(taskPlanPath).replace(/\n##\s*(?:Task Tombstone|任务墓碑)\s*$[\s\S]*?(?=^##\s+|(?![\s\S]))/im, "");
+  const block = ["", "## Task Tombstone", "", "| Field | Value |", "| --- | --- |", ...Object.entries(fields).map(([key, value]) => `| ${key} | ${escapeCell(value)} |`), ""].join("\n");
+  fs.writeFileSync(taskPlanPath, `${content.trimEnd()}\n${block}`);
+}
+
+function appendSupersedes(target, task, oldId) {
+  const taskPlanPath = path.join(target.projectRoot, task.taskPlanPath.replace(/^TARGET:/, ""));
+  const content = readFileSafe(taskPlanPath);
+  if (/^Supersedes\s*[:：]/im.test(content)) {
+    fs.writeFileSync(taskPlanPath, content.replace(/^Supersedes\s*[:：]\s*(.*)$/im, (_m, current) => `Supersedes: ${[current, oldId].filter(Boolean).join(", ")}`));
+    return;
+  }
+  fs.writeFileSync(taskPlanPath, `${content.trimEnd()}\nSupersedes: ${oldId}\n`);
+}
+
+function appendProgress(target, task, action, reason) {
+  const progressPath = path.join(target.projectRoot, task.progressPath.replace(/^TARGET:/, ""));
+  const relative = toPosix(path.relative(target.projectRoot, progressPath));
+  fs.appendFileSync(progressPath, `\n\n## Tombstone Log\n\n- ${nowTimestamp()} ${action}: ${escapeCell(reason)} (${relative})\n`);
+}
+
+function escapeCell(value) {
+  return String(value || "").replace(/\r?\n/g, " ").replaceAll("|", "\\|").trim();
+}

package/scripts/postinstall.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+
+import { seedBundledPresets } from "./lib/harness-core.mjs";
+
+if (process.env.CODING_AGENT_HARNESS_SKIP_POSTINSTALL === "1") process.exit(0);
+
+try {
+  const result = seedBundledPresets({ scope: "user" });
+  const changed = result.created + result.overwritten;
+  const summary = changed > 0 ? `${changed} bundled presets installed` : `${result.skipped} bundled presets already present`;
+  console.log(`coding-agent-harness postinstall: ${summary} at ${result.target}`);
+} catch (error) {
+  console.warn(`coding-agent-harness postinstall: preset seed skipped (${error.message})`);
+}