coding-agent-harness 1.0.5 → 1.0.7

package/scripts/lib/task-lifecycle/phase-sync.mjs

@@ -1,88 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-import {
-  lessonCandidatesFile,
-  readFileSafe,
-  todayDate,
-  toPosix,
-  visualMapFile,
-} from "../core-shared.mjs";
-import {
-  firstColumn,
-  updateMarkdownTableRow,
-} from "../markdown-utils.mjs";
-import {
-  normalizePhaseActor,
-  normalizePhaseKind,
-} from "../phase-kind.mjs";
-import { parseLessonCandidateStatus } from "../task-lesson-candidates.mjs";
-
-export function advanceLifecyclePhase(target, taskDir, event) {
-  const visualMapPath = path.join(taskDir, visualMapFile);
-  if (!fs.existsSync(visualMapPath)) return "";
-  const content = readFileSafe(visualMapPath);
-  let updated = false;
-  const phaseUpdate = updateMarkdownTableRow(content, /^Phase ID$/i, (header, row) => {
-    if (updated || !phaseMatchesLifecycleEvent(header, row, event)) return null;
-    updated = true;
-    const next = [...row];
-    const stateIndex = firstColumn(header, ["State", "状态"]);
-    const completionIndex = firstColumn(header, ["Completion", "完成度"]);
-    const evidenceIndex = firstColumn(header, ["Evidence Status", "证据状态"]);
-    if (stateIndex >= 0) next[stateIndex] = "done";
-    if (completionIndex >= 0) next[completionIndex] = "100";
-    if (evidenceIndex >= 0) next[evidenceIndex] = "present";
-    return next;
-  });
-  if (!updated || phaseUpdate.content === content) return "";
-  fs.writeFileSync(visualMapPath, phaseUpdate.content);
-  return toPosix(path.relative(target.projectRoot, visualMapPath));
-}
-
-export function autoRecordNoLessonCandidateDecision(target, taskDir) {
-  const candidatePath = path.join(taskDir, lessonCandidatesFile);
-  if (!fs.existsSync(candidatePath)) return "";
-  const content = readFileSafe(candidatePath);
-  const status = parseLessonCandidateStatus(content);
-  if (status.rows.length > 0 || status.declaredStatus !== "pending-review") return "";
-  const next = replaceNoLessonCandidateFields(content);
-  if (next === content) return "";
-  fs.writeFileSync(candidatePath, next);
-  return toPosix(path.relative(target.projectRoot, candidatePath));
-}
-
-function phaseMatchesLifecycleEvent(header, row, event) {
-  const kindIndex = firstColumn(header, ["Kind", "阶段类型", "类型"]);
-  if (kindIndex < 0) return false;
-  const actorIndex = firstColumn(header, ["Actor", "执行者", "角色"]);
-  const exitCommandIndex = firstColumn(header, ["Exit Command", "出口命令", "退出命令"]);
-  const outputIndex = firstColumn(header, ["Output", "产出"]);
-  const kind = normalizePhaseKind(row[kindIndex]);
-  const actor = actorIndex >= 0 ? normalizePhaseActor(row[actorIndex]) : "agent";
-  const exitCommand = String(row[exitCommandIndex] || "");
-  const output = String(row[outputIndex] || "");
-  if (event === "task-start") return kind === "init" && actor === "agent";
-  if (event === "task-review") {
-    return kind === "gate" && actor === "agent" && (/\btask-review\b/.test(exitCommand) || /Agent Review Submission/i.test(output));
-  }
-  if (event === "task-complete") {
-    return kind === "gate" && actor === "agent" && /\btask-complete\b/.test(exitCommand);
-  }
-  return false;
-}
-
-function replaceNoLessonCandidateFields(content) {
-  let next = String(content || "");
-  const replacements = [
-    [/(\|\s*Task-level status\s*\|\s*)[^|]+(\|)/i, "$1no-candidate-accepted $2"],
-    [/(\|\s*Review decision\s*\|\s*)[^|]+(\|)/i, "$1accepted-no-candidate $2"],
-    [/(\|\s*Closeout token\s*\|\s*)[^|]+(\|)/i, "$1checked-none:auto-no-candidate $2"],
-    [/(\|\s*Last updated\s*\|\s*)[^|]+(\|)/i, `$1${todayDate()} $2`],
-  ];
-  for (const [pattern, replacement] of replacements) next = next.replace(pattern, replacement);
-  const reason = "Agent review found no reusable lesson candidates in this task; the empty candidate table is recorded as checked for closeout.";
-  return next.replace(
-    /(## No-Candidate Reason\s*\n)([\s\S]*?)(?=\n## |\s*$)/,
-    `$1\n${reason}\n`,
-  );
-}

package/scripts/lib/task-lifecycle/review-confirm.mjs

@@ -1,112 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-import {
-  lessonCandidatesFile,
-  nowTimestamp,
-  readFileSafe,
-} from "../core-shared.mjs";
-import {
-  parseTaskAuditMetadata,
-  readGitIdentity,
-  replaceTaskAuditMetadata,
-  taskAuditFieldOrder,
-} from "../task-audit-metadata.mjs";
-import {
-  collectReviewRisks,
-  isBlockingReviewRisk,
-  isLessonCandidateDecisionComplete,
-  parseLessonCandidateStatus,
-  parseTaskBudget,
-  taskIdForDirectory,
-} from "../task-scanner.mjs";
-import { commitReviewConfirmationGate, prepareReviewConfirmGitGate } from "../review-confirm-git-gate.mjs";
-import { validateHumanReviewConfirmation } from "./review-gates.mjs";
-import { markdownCell } from "./text-utils.mjs";
-
-export function confirmTaskReview({ target, taskDir, findTaskByDirectory }, { reviewer = "Human Reviewer", message = "", confirmText = "", evidence = "" } = {}) {
-  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 indexPath = path.join(taskDir, "INDEX.md");
-  const reviewContent = readFileSafe(reviewPath);
-  const indexContent = readFileSafe(indexPath);
-  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}.`);
-  }
-  const gitGate = prepareReviewConfirmGitGate(target.projectRoot, [indexPath]);
-
-  const timestamp = nowTimestamp();
-  const confirmationId = `HRC-${timestamp.replace(/[^0-9]/g, "").slice(0, 14)}`;
-  const identity = readGitIdentity(target.projectRoot);
-  const baseAuditFields = taskAuditFieldsFromIndex(indexContent);
-  const buildAuditFields = ({ commitSha = "pending", auditStatus = "commit-pending" } = {}) => ({
-    ...baseAuditFields,
-    "Human Review Status": "confirmed",
-    "Confirmation ID": confirmationId,
-    "Confirmed At": timestamp,
-    "Reviewer": reviewer || identity.name || "Human Reviewer",
-    "Reviewer Email": identity.email || "n/a",
-    "Confirm Text": markdownCell(confirmText),
-    "Evidence Checked": evidence || `TARGET:docs/09-PLANNING/${canonicalTaskId}/review.md`,
-    "Review Commit SHA": commitSha,
-    "Audit Source": "native-index",
-    "Audit Status": auditStatus,
-    "Message": message || "Human review confirmed",
-    "Migration Status": baseAuditFields["Migration Status"] || "native",
-  });
-  fs.writeFileSync(indexPath, ensureTrailingNewline(replaceTaskAuditMetadata(indexContent, buildAuditFields(), { locale: target.locale })));
-  const audit = commitReviewConfirmationGate(gitGate, {
-    taskId: canonicalTaskId,
-    reviewPath: indexPath,
-    message: message || `Human review confirmed by ${reviewer}`,
-    writeFinalAudit(commitSha) {
-      const currentIndex = readFileSafe(indexPath);
-      const finalIndex = replaceTaskAuditMetadata(currentIndex, buildAuditFields({ commitSha, auditStatus: "committed" }), { locale: target.locale });
-      fs.writeFileSync(indexPath, ensureTrailingNewline(finalIndex));
-    },
-  });
-  return {
-    event: "review-confirm",
-    task: findTaskByDirectory(target, taskDir) || { id: canonicalTaskId, reviewStatus: "confirmed" },
-    audit,
-  };
-}
-
-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 taskAuditFieldsFromIndex(content) {
-  const audit = parseTaskAuditMetadata(content, { required: true });
-  const fields = {};
-  for (const field of taskAuditFieldOrder) fields[field] = audit.fields.get(field.toLowerCase()) || "n/a";
-  return fields;
-}
-
-function ensureTrailingNewline(content) {
-  return content.endsWith("\n") ? content : `${content}\n`;
-}

package/scripts/lib/task-lifecycle/review-gates.mjs

@@ -1,73 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-import {
-  lessonCandidatesFile,
-} from "../core-shared.mjs";
-import {
-  collectReviewRisks,
-  isBlockingReviewRisk,
-  parseTaskAuditMetadata,
-  parsePhases,
-  parseReviewConfirmation,
-  readVisualMapContractFile,
-} from "../task-scanner.mjs";
-import {
-  implementationPhases,
-  phaseHasRecordedProgress,
-} from "../phase-kind.mjs";
-
-export function validateLifecycleTransition({ event, currentState, budget, reviewContent = "", indexContent = "", reviewTaskKey = "", projectRoot = "", taskDir = "" }) {
-  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, { taskKey: reviewTaskKey, taskAudit: parseTaskAuditMetadata(indexContent), projectRoot, taskDir, indexPath: path.join(taskDir, "INDEX.md") })?.confirmed) {
-      throw new Error("Human review must be confirmed before task-complete. Run review-confirm first.");
-    }
-  }
-}
-
-export 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 = implementationPhases(phases);
-  if (phases.length > 0 && actionablePhases.length === 0) {
-    throw new Error("task-review requires at least one non-skipped Visual Map execution phase.");
-  }
-  const hasRecordedPhaseProgress = actionablePhases.some(phaseHasRecordedProgress);
-  if (actionablePhases.length > 0 && !hasRecordedPhaseProgress) {
-    throw new Error("task-review requires at least one Visual Map execution phase progress update. Run task-phase before entering human review.");
-  }
-}
-
-export function validateHumanReviewConfirmation({ task, budget }) {
-  if (budget === "simple") return;
-  if (!task?.walkthroughPath) {
-    throw new Error("Human review confirmation requires a walkthrough linked from Closeout SSoT before review-confirm.");
-  }
-  const queueState = task?.reviewQueueState || "not-in-queue";
-  if (queueState !== "ready-to-confirm") {
-    const state = task?.state || "unknown";
-    throw new Error(`Human review confirmation requires canonical ready-to-confirm review queue; current state is ${state}, review queue is ${queueState}.`);
-  }
-  if (!Array.isArray(task?.taskQueues) || !task.taskQueues.includes("review")) {
-    const queues = Array.isArray(task?.taskQueues) ? task.taskQueues.join(", ") : "none";
-    throw new Error(`Human review confirmation requires the task to be in the Review queue; current queues: ${queues || "none"}.`);
-  }
-  if (!task?.lessonCandidateDecisionComplete) {
-    const status = task?.lessonCandidateStatus || "missing";
-    throw new Error(`Human review confirmation requires lesson candidate decision complete; current status is ${status}.`);
-  }
-}

package/scripts/lib/task-lifecycle/review-submission.mjs

@@ -1,63 +0,0 @@
-import crypto from "node:crypto";
-import fs from "node:fs";
-import path from "node:path";
-import {
-  lessonCandidatesFile,
-  longRunningTaskContractFile,
-  nowTimestamp,
-  readFileSafe,
-  toPosix,
-  visualMapFile,
-} from "../core-shared.mjs";
-import {
-  collectReviewRisks,
-  isBlockingReviewRisk,
-  taskScannerVersion,
-} from "../task-review-model.mjs";
-import { markdownCell } from "./text-utils.mjs";
-
-export function renderAgentReviewSubmission({ target, taskDir, canonicalTaskId, message, evidence }) {
-  const timestamp = nowTimestamp();
-  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",
-    "",
-    "| 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");
-}
-
-export function replaceAgentReviewSubmission(content, block) {
-  const trimmed = String(content || "").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 hash.digest("hex").slice(0, 16);
-}

package/scripts/lib/task-lifecycle/scaffold-provenance.mjs

@@ -1,49 +0,0 @@
-import path from "node:path";
-import { localizedTemplateSource, todayDate } from "../core-shared.mjs";
-import { markdownCell } from "./text-utils.mjs";
-
-function shellArg(value) {
-  const text = String(value || "");
-  if (/^[A-Za-z0-9._/:=@+-]+$/.test(text)) return text;
-  return `'${text.replaceAll("'", "'\\''")}'`;
-}
-
-function commandPathArg(value, fallback) {
-  const text = String(value || fallback || ".").trim() || ".";
-  if (text === ".") return ".";
-  return path.isAbsolute(text) ? fallback : text;
-}
-
-function renderNewTaskCommand({ taskId, title, locale, budget, longRunning, moduleKey, preset, fromSession, targetInput }) {
-  const parts = ["harness", "new-task"];
-  if (taskId) parts.push(taskId);
-  parts.push("--budget", budget, "--locale", locale);
-  if (title) parts.push("--title", title);
-  if (moduleKey) parts.push("--module", moduleKey);
-  if (preset && preset !== "none") parts.push("--preset", preset);
-  if (fromSession) parts.push("--from-session", commandPathArg(fromSession, "<session.json>"));
-  if (longRunning) parts.push("--long-running");
-  parts.push(commandPathArg(targetInput, "<target>"));
-  return parts.map(shellArg).join(" ");
-}
-
-export function buildScaffoldProvenance({ taskId, normalizedTaskId, title, locale, budget, longRunning, moduleKey, preset, fromSession, targetInput, automaticTaskId = false }) {
-  return {
-    createdBy: "harness new-task",
-    command: markdownCell(renderNewTaskCommand({
-      taskId: automaticTaskId ? "" : taskId || normalizedTaskId,
-      title,
-      locale,
-      budget,
-      longRunning,
-      moduleKey,
-      preset,
-      fromSession,
-      targetInput,
-    })),
-    createdAt: todayDate(),
-    budget,
-    templateSource: localizedTemplateSource("templates/planning/brief.md", locale),
-    exceptionReason: "n/a",
-  };
-}

package/scripts/lib/task-lifecycle/template-files.mjs

@@ -1,53 +0,0 @@
-import { localizedTemplateSource, longRunningTaskContractFile, visualMapFile, lessonCandidatesFile } from "../core-shared.mjs";
-
-export function taskTemplateFiles({ locale = "en-US" } = {}) {
-  return [
-    ["INDEX.md", "templates/planning/INDEX.md"],
-    ["brief.md", "templates/planning/brief.md"],
-    ["task_plan.md", "templates/planning/task_plan.md"],
-    ["execution_strategy.md", "templates/planning/execution_strategy.md"],
-    [visualMapFile, "templates/planning/visual_map.md"],
-    ["findings.md", "templates/planning/findings.md"],
-    [lessonCandidatesFile, "templates/planning/lesson_candidates.md"],
-    ["progress.md", "templates/planning/progress.md"],
-    ["review.md", "templates/planning/review.md"],
-  ].map(([destination, source]) => [destination, localizedTemplateSource(source, locale)]);
-}
-
-export function simpleTaskTemplateFiles({ locale = "en-US" } = {}) {
-  return [
-    ["INDEX.md", "templates/planning/INDEX.md"],
-    ["brief.md", "templates/planning/brief.md"],
-    ["task_plan.md", "templates/planning/task_plan.md"],
-    [visualMapFile, "templates/planning/visual_map.simple.md"],
-    ["progress.md", "templates/planning/progress.md"],
-  ].map(([destination, source]) => [destination, localizedTemplateSource(source, locale)]);
-}
-
-export function optionalTaskTemplateFiles({ locale = "en-US" } = {}) {
-  return [
-    ["references/INDEX.md", "templates/planning/optional/references/INDEX.md"],
-    ["artifacts/INDEX.md", "templates/planning/optional/artifacts/INDEX.md"],
-  ].map(([destination, source]) => [destination, localizedTemplateSource(source, locale)]);
-}
-
-export function moduleTemplateFiles({ locale = "en-US" } = {}) {
-  return [
-    ["brief.md", "templates/planning/module_brief.md"],
-    ["module_plan.md", "templates/planning/module_plan.md"],
-    ["execution_strategy.md", "templates/planning/execution_strategy.md"],
-    [visualMapFile, "templates/planning/visual_map.md"],
-    ["session_prompt.md", "templates/planning/module_session_prompt.md"],
-  ].map(([destination, source]) => [destination, localizedTemplateSource(source, locale)]);
-}
-
-export function taskFilesForBudget({ budget, locale }) {
-  if (budget === "simple") return simpleTaskTemplateFiles({ locale });
-  if (budget === "complex") return [...taskTemplateFiles({ locale }), ...optionalTaskTemplateFiles({ locale })];
-  return taskTemplateFiles({ locale });
-}
-
-export function appendLongRunningContractFile(files, { locale, longRunning }) {
-  if (!longRunning) return files;
-  return [...files, [longRunningTaskContractFile, localizedTemplateSource("templates/planning/long-running-task-contract.md", locale)]];
-}

package/scripts/lib/task-lifecycle/text-utils.mjs

@@ -1,24 +0,0 @@
-import { nowTimestamp } from "../core-shared.mjs";
-
-export 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`;
-}
-
-export function markdownCell(value) {
-  return String(value || "")
-    .replace(/\r?\n/g, " ")
-    .replaceAll("|", "\\|")
-    .trim();
-}