coding-agent-harness 1.0.4 → 1.0.6

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

@@ -0,0 +1,82 @@
+// @ts-nocheck
+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/dist/lib/task-lifecycle/review-confirm.mjs

@@ -0,0 +1,93 @@
+// @ts-nocheck
+// Dynamic review confirmation flow stays behavior-first until the metadata domain model PR.
+import fs from "node:fs";
+import path from "node:path";
+import { lessonCandidatesFile, nowTimestamp, readFileSafe, toPosix, } 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:${toPosix(path.relative(target.projectRoot, reviewPath))}`,
+        "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 = (target.harness?.taskRoots || [])
+        .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/dist/lib/task-lifecycle/review-gates.mjs

@@ -0,0 +1,62 @@
+// @ts-nocheck
+// Dynamic review gate modeling stays behavior-first until the metadata domain model PR.
+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 task-local walkthrough.md 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/dist/lib/task-lifecycle/review-submission.mjs

@@ -0,0 +1,52 @@
+// @ts-nocheck
+// Dynamic review submission rendering stays behavior-first until the metadata domain model PR.
+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/dist/lib/task-lifecycle/scaffold-provenance.mjs

@@ -0,0 +1,54 @@
+// @ts-nocheck
+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/dist/lib/task-lifecycle/template-files.mjs

@@ -0,0 +1,52 @@
+// @ts-ignore core-shared remains a JS runtime dependency until its migration PR.
+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 }) {
+    const files = budget === "simple"
+        ? simpleTaskTemplateFiles({ locale })
+        : budget === "complex"
+            ? [...taskTemplateFiles({ locale }), ...optionalTaskTemplateFiles({ locale })]
+            : taskTemplateFiles({ locale });
+    return [...files, ["walkthrough.md", localizedTemplateSource("templates/planning/walkthrough.md", locale)]];
+}
+export function appendLongRunningContractFile(files, { locale, longRunning }) {
+    if (!longRunning)
+        return files;
+    return [...files, [longRunningTaskContractFile, localizedTemplateSource("templates/planning/long-running-task-contract.md", locale)]];
+}

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

@@ -0,0 +1,26 @@
+// @ts-ignore core-shared remains a JS runtime dependency until its migration PR.
+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();
+}
+export function markWalkthroughClosed(content) {
+    if (/^Closeout Status\s*:/im.test(content)) {
+        return content.replace(/^Closeout Status\s*:[^\n]*/im, "Closeout Status: closed").trimEnd() + "\n";
+    }
+    return `${String(content || "").trimEnd()}\n\nCloseout Status: closed\n`;
+}