coding-agent-harness 1.0.2 → 1.0.5

package/scripts/lib/governance-table-boundary.mjs

@@ -0,0 +1,175 @@
+import fs from "node:fs";
+import path from "node:path";
+import { readFileSafe, toPosix } from "./core-shared.mjs";
+import { getCell, parseAllMarkdownTables } from "./markdown-utils.mjs";
+
+const newRuleCutoff = "2026-05-24";
+
+const globalTableSpecs = [
+  { key: "feature-ssot", relativePath: "09-PLANNING/Feature-SSoT.md", allowed: "index-state-route-summary", evaluate: evaluateFeatureRow },
+  { key: "harness-ledger", relativePath: "Harness-Ledger.md", allowed: "task-audit-summary-route", evaluate: evaluateLedgerRow },
+  { key: "closeout-ssot", relativePath: "10-WALKTHROUGH/Closeout-SSoT.md", allowed: "closeout-index-review-route-summary", evaluate: evaluateCloseoutRow },
+  { key: "regression-ssot", relativePath: "05-TEST-QA/Regression-SSoT.md", allowed: "gate-index-current-state", evaluate: evaluateRegressionRow },
+  { key: "cadence-ledger", relativePath: "05-TEST-QA/Cadence-Ledger.md", allowed: "trigger-rule-and-batch-summary", evaluate: evaluateCadenceRow },
+];
+
+export function validateGovernanceTableBoundaries(target) {
+  const failures = [];
+  const warnings = [];
+  for (const spec of globalTableSpecs) {
+    const file = path.join(target.docsRoot, spec.relativePath);
+    if (!fs.existsSync(file)) continue;
+    const relative = toPosix(path.relative(target.projectRoot, file));
+    for (const table of parseAllMarkdownTables(readFileSafe(file), relative, spec.key)) {
+      for (const row of table.rows) {
+        if (isPlaceholderRow(row)) continue;
+        for (const finding of spec.evaluate(row)) {
+          const rowKey = governanceRowKey(row);
+          const message = [
+            "governance-table-entropy",
+            `${relative}:${table.line}`,
+            `${spec.key} row ${rowKey}`,
+            finding.reason,
+            `allowed=${spec.allowed}`,
+            `route=${finding.route}`,
+          ].join(": ");
+          if (isLegacyRow(rowUpdatedDate(row))) warnings.push(`${message}: legacy-report-only`);
+          else failures.push(message);
+        }
+      }
+    }
+  }
+  return { failures, warnings };
+}
+
+function evaluateFeatureRow(row) {
+  const cells = row.cells || {};
+  const text = rowText(row);
+  const taskPlan = getCell(cells, ["Task Plan", "Task", "任务计划", "路径"], "");
+  const evidence = getCell(cells, ["Acceptance Evidence", "Evidence", "验收证据"], "");
+  const findings = [];
+  if (/09-PLANNING\/MODULES\//i.test(taskPlan) && !isModuleAggregateRow(row) && localDetailPattern().test(text)) {
+    findings.push({
+      reason: "module-local detail belongs in module_plan.md or task files, not Feature SSoT",
+      route: "module-plan-or-task-detail",
+    });
+  }
+  if (longEvidencePattern().test(evidence) || temporaryPromptPattern().test(text)) {
+    findings.push({
+      reason: "long evidence or temporary repair prompt belongs in task evidence, not Feature SSoT",
+      route: "task-artifacts-or-progress",
+    });
+  }
+  return findings;
+}
+
+function isModuleAggregateRow(row) {
+  const cells = row.cells || {};
+  const id = getCell(cells, ["ID"], "");
+  const taskPlan = getCell(cells, ["Task Plan", "Task", "任务计划", "路径"], "");
+  return /^F-MODULE-/i.test(id) && /09-PLANNING\/MODULES\/[^/]+\/module_plan\.md/i.test(taskPlan);
+}
+
+function evaluateLedgerRow(row) {
+  const text = rowText(row);
+  const evidence = ledgerEvidenceText(row);
+  if (executionLogPattern().test(evidence) || temporaryPromptPattern().test(text) || rawTranscriptPattern().test(evidence)) {
+    return [{
+      reason: "execution logs, long evidence, and temporary repair prompts belong in task progress/review/artifacts",
+      route: "task-progress-review-artifacts",
+    }];
+  }
+  return [];
+}
+
+function ledgerEvidenceText(row) {
+  const cells = row.cells || {};
+  return [
+    "Evidence Summary",
+    "Evidence",
+    "Regression Evidence",
+    "Review Evidence",
+    "Regression",
+    "Review",
+    "证据摘要",
+    "证据",
+    "回归",
+    "审查",
+  ].map((column) => getCell(cells, [column], "")).filter(Boolean).join(" ");
+}
+
+function evaluateCloseoutRow(row) {
+  const text = rowText(row);
+  if (executionLogPattern().test(text) || rawTranscriptPattern().test(text)) {
+    return [{
+      reason: "closeout rows should route to walkthrough/evidence instead of carrying execution detail",
+      route: "walkthrough-or-task-evidence",
+    }];
+  }
+  return [];
+}
+
+function evaluateRegressionRow(row) {
+  const text = rowText(row);
+  if (executionLogPattern().test(text) || temporaryPromptPattern().test(text)) {
+    return [{
+      reason: "regression global tables should keep gate state and route detailed failure analysis elsewhere",
+      route: "regression-detail-or-task-review",
+    }];
+  }
+  return [];
+}
+
+function evaluateCadenceRow(row) {
+  const text = rowText(row);
+  if (rawTranscriptPattern().test(text) || temporaryPromptPattern().test(text)) {
+    return [{
+      reason: "cadence rows should summarize batch outcomes and route raw run detail elsewhere",
+      route: "regression-batch-artifacts",
+    }];
+  }
+  return [];
+}
+
+function governanceRowKey(row) {
+  return getCell(row.cells || {}, ["ID", "Lesson", "Lesson ID", "Feature", "Work Item", "Gate ID", "Batch ID"], "") || row.id || "unknown-row";
+}
+
+function rowText(row) {
+  return Object.values(row.cells || {}).join(" ");
+}
+
+function rowUpdatedDate(row) {
+  const value = getCell(row.cells || {}, ["Updated", "Date", "日期", "Last Verified", "最近验证"], "");
+  const match = String(value).match(/\d{4}-\d{2}-\d{2}/);
+  return match ? match[0] : "";
+}
+
+function isLegacyRow(updated) {
+  return updated && updated < newRuleCutoff;
+}
+
+function isPlaceholderRow(row) {
+  const text = rowText(row);
+  return /\b(?:YYYY|MM|DD|NNN)\b|L-YYYY|HL-YYYY|\[[^\]]+\]|\.\.\.md|\bowner\b|\bShort lesson title\b/i.test(text);
+}
+
+function localDetailPattern() {
+  return /\b(module|local|implementation detail|parser branch|button label|copy every|工作项|局部|实现细节)\b/i;
+}
+
+function longEvidencePattern() {
+  return /\b(long evidence|full local evidence|raw evidence|stack trace|reviewer transcript|copied raw)\b/i;
+}
+
+function executionLogPattern() {
+  return /\b(execution log|command failed|stack trace|raw output|step one|step two|执行流水|命令输出)\b/i;
+}
+
+function temporaryPromptPattern() {
+  return /\b(temporary repair prompt|repair prompt|copyable prompt|paste back|临时修复提示)\b/i;
+}
+
+function rawTranscriptPattern() {
+  return /\b(raw transcript|reviewer transcript|full transcript|完整记录|原始记录)\b/i;
+}

package/scripts/lib/harness-core.mjs

@@ -2,9 +2,15 @@ export * from "./core-shared.mjs";
 export * from "./markdown-utils.mjs";
 export * from "./capability-registry.mjs";
 export * from "./task-scanner.mjs";
+export * from "./status-builder.mjs";
 export * from "./check-profiles.mjs";
 export * from "./dashboard-data.mjs";
 export * from "./dashboard-workbench.mjs";
 export * from "./migration-planner.mjs";
+export * from "./preset-registry.mjs";
+export * from "./governance-index-generator.mjs";
 export * from "./task-lifecycle.mjs";
+export * from "./task-lesson-sedimentation.mjs";
 export * from "./lesson-maintenance.mjs";
+export * from "./task-index.mjs";
+export * from "./task-tombstone-commands.mjs";

package/scripts/lib/lesson-maintenance.mjs

@@ -12,8 +12,13 @@ import {
   collectTasks,
   parseLessonCandidateStatus,
 } from "./task-scanner.mjs";
+import {
+  beginGovernanceSync,
+  commitGovernanceSync,
+  releaseGovernanceSync,
+} from "./governance-sync.mjs";
 
-export function promoteLessonCandidate(targetInput, taskId, candidateId, { dryRun = false } = {}) {
+export function promoteLessonCandidate(targetInput, taskId, candidateId, { dryRun = false, apply = false } = {}) {
   const target = normalizeTarget(targetInput);
   const normalizedRef = slug(taskId);
   const matchesBareSlug = (item) => {
@@ -45,23 +50,43 @@ export function promoteLessonCandidate(targetInput, taskId, candidateId, { dryRu
   const title = row.title || lessonId;
   const detailRelative = `docs/01-GOVERNANCE/lessons/${lessonId}-${slug(title)}.md`;
   const detailPath = path.join(target.projectRoot, detailRelative);
-  const ssotPath = path.join(target.docsRoot, "01-GOVERNANCE/Lessons-SSoT.md");
-  const ssotContent = readFileSafe(ssotPath);
-  if (!ssotContent.trim()) throw new Error("Lessons SSoT not found");
 
   const changes = [];
   if (!fs.existsSync(detailPath)) changes.push({ action: dryRun ? "would-create" : "create", path: `TARGET:${detailRelative}` });
-  if (!ssotContent.includes(lessonId)) changes.push({ action: dryRun ? "would-append" : "append", path: "TARGET:docs/01-GOVERNANCE/Lessons-SSoT.md" });
   if (row.status !== "promoted" || parsed.status !== "promoted") changes.push({ action: dryRun ? "would-update" : "update", path: task.lessonCandidatePath || `TARGET:${toPosix(path.relative(target.projectRoot, candidatePath))}` });
 
-  if (dryRun) return { dryRun: true, taskId: task.id, candidateId: row.id, lessonId, detailDoc: `TARGET:${detailRelative}`, changes };
+  const effectiveDryRun = dryRun || !apply;
+  if (effectiveDryRun) {
+    return {
+      dryRun: true,
+      applyRequired: true,
+      taskId: task.id,
+      candidateId: row.id,
+      lessonId,
+      detailDoc: `TARGET:${detailRelative}`,
+      changes: changes.map((change) => ({ ...change, action: change.action.replace(/^(create|append|update)$/, "would-$1") })),
+      nextCommand: `harness lesson-promote ${task.shortId} ${row.id} --apply`,
+    };
+  }
 
-  fs.mkdirSync(path.dirname(detailPath), { recursive: true });
-  if (!fs.existsSync(detailPath)) fs.writeFileSync(detailPath, renderLessonDetail({ lessonId, candidate: row, task, detailRelative }));
-  if (!ssotContent.includes(lessonId)) fs.writeFileSync(ssotPath, appendLessonSsotRow(ssotContent, { lessonId, candidate: row, task, detailRelative }));
-  fs.writeFileSync(candidatePath, markCandidatePromoted(candidateContent, row.id, lessonId));
+  const governanceContext = beginGovernanceSync(target, { operation: `lesson-promote ${task.id} ${row.id}` });
+  try {
+    fs.mkdirSync(path.dirname(detailPath), { recursive: true });
+    if (!fs.existsSync(detailPath)) fs.writeFileSync(detailPath, renderLessonDetail({ lessonId, candidate: row, task, detailRelative }));
+    fs.writeFileSync(candidatePath, markCandidatePromoted(candidateContent, row.id, lessonId));
+    const commit = commitGovernanceSync(
+      governanceContext,
+      [
+        detailRelative,
+        toPosix(path.relative(target.projectRoot, candidatePath)),
+      ],
+      { message: `chore(harness): promote lesson ${row.id}` },
+    );
 
-  return { dryRun: false, taskId: task.id, candidateId: row.id, lessonId, detailDoc: `TARGET:${detailRelative}`, changes };
+    return { dryRun: false, taskId: task.id, candidateId: row.id, lessonId, detailDoc: `TARGET:${detailRelative}`, changes, governance: { commit } };
+  } finally {
+    releaseGovernanceSync(governanceContext);
+  }
 }
 
 function lessonIdFromCandidate(candidateId) {
@@ -95,24 +120,6 @@ function renderLessonDetail({ lessonId, candidate, task }) {
   ].join("\n");
 }
 
-function appendLessonSsotRow(content, { lessonId, candidate, task, detailRelative }) {
-  const lines = String(content || "").split(/\r?\n/);
-  const headerIndex = lines.findIndex((line) => /^\|\s*(ID|Lesson ID)\s*\|/.test(line));
-  if (headerIndex < 0) throw new Error("Lessons SSoT active table not found");
-  const columnCount = splitSimpleRow(lines[headerIndex]).length;
-  const date = lessonId.match(/^L-(\d{4}-\d{2}-\d{2})-/)?.[1] || new Date().toISOString().slice(0, 10);
-  const detail = `\`${detailRelative}\``;
-  const source = `\`${task.path.replace(/^TARGET:/, "docs/").replace(/^docs\/docs\//, "docs/")}/task_plan.md\``;
-  const row =
-    columnCount === 10
-      ? `| ${lessonId} | ${escapeCell(candidate.title || lessonId)} | ${source} | process-change | coordinator | candidate | ${escapeCell(candidate.promotionTarget || "governance review")} | ${detail} | ${escapeCell(candidate.id)} | ${date} |`
-      : `| ${lessonId} | ${date} | ${source} | process-change | ${escapeCell(candidate.promotionTarget || "governance review")} | ${escapeCell(candidate.title || lessonId)} | ${detail} | pending | ${escapeCell(candidate.id)} |`;
-  let insertAt = headerIndex + 1;
-  while (insertAt < lines.length && lines[insertAt].trim().startsWith("|")) insertAt += 1;
-  lines.splice(insertAt, 0, row);
-  return `${lines.join("\n").trimEnd()}\n`;
-}
-
 function markCandidatePromoted(content, candidateId, lessonId) {
   const lines = String(content || "").split(/\r?\n/);
   const headerIndex = lines.findIndex((line) => /^\|\s*ID\s*\|/.test(line));

package/scripts/lib/markdown-utils.mjs

@@ -156,3 +156,36 @@ export function updateMarkdownTableRow(content, headerPattern, updater) {
   }
   return { content, matched: false };
 }
+
+export function upsertMarkdownTableRow(content, headerPattern, matcher, row) {
+  const updated = updateMarkdownTableRow(content, headerPattern, (header, existing) => (matcher(header, existing) ? fitMarkdownTableRow(row, header.length) : null));
+  if (updated.matched) return updated.content;
+  return appendMarkdownTableRow(content, headerPattern, row);
+}
+
+export function appendMarkdownTableRow(content, headerPattern, row) {
+  const lines = String(content || "").split(/\r?\n/);
+  for (let index = 0; index < lines.length; index += 1) {
+    if (!lines[index].trim().startsWith("|")) continue;
+    const header = splitMarkdownRow(lines[index]);
+    if (!header.some((cell) => headerPattern.test(cell))) continue;
+    let insertAt = index + 2;
+    while (insertAt < lines.length && lines[insertAt].trim().startsWith("|")) insertAt += 1;
+    lines.splice(insertAt, 0, `| ${fitMarkdownTableRow(row, header.length).join(" | ")} |`);
+    return lines.join("\n");
+  }
+  return `${String(content || "").trimEnd()}\n\n| ${row.map(markdownTableCell).join(" | ")} |\n`;
+}
+
+export function fitMarkdownTableRow(row, length) {
+  const next = row.map(markdownTableCell);
+  while (next.length < length) next.push("");
+  return next.slice(0, length);
+}
+
+function markdownTableCell(value) {
+  return String(value || "")
+    .replace(/\r?\n/g, " ")
+    .replaceAll("|", "\\|")
+    .trim();
+}

package/scripts/lib/migration-planner.mjs

@@ -6,6 +6,7 @@ import {
   normalizeTarget,
   normalizeLocale,
   readFileSafe,
+  readJsonSafe,
   existsInDocs,
   walkFiles,
   toPosix,
@@ -363,12 +364,9 @@ export function verifyMigrationSession(sessionPathInput, { fullCutover = false }
   }
   const failures = [];
   const warnings = [];
-  let session;
-  try {
-    session = JSON.parse(fs.readFileSync(sessionPath, "utf8"));
-  } catch (error) {
-    return { operation: "migrate-verify", status: "fail", failures: [`invalid session json: ${error.message}`], warnings };
-  }
+  let readError = null;
+  const session = readJsonSafe(sessionPath, null, { onError: (error) => { readError = error; } });
+  if (!session) return { operation: "migrate-verify", status: "fail", failures: [`invalid session json: ${readError?.message || "unknown parse error"}`], warnings };
   if (session.operation !== "migrate-run") failures.push("session operation is not migrate-run");
   if (session.schemaVersion !== 1 && session.version !== 1) failures.push("session missing schema version");
   if (session.planOnly) failures.push("plan-only session is not completed migration evidence; rerun migrate-run without --plan-only");

package/scripts/lib/migration-support.mjs

@@ -22,8 +22,8 @@ export function migrationSampleFiles(target) {
     path.join(target.projectRoot, "AGENTS.md"),
     path.join(target.projectRoot, "CLAUDE.md"),
     path.join(target.docsRoot, "Harness-Ledger.md"),
-    path.join(target.docsRoot, "09-PLANNING/Feature-SSoT.md"),
     path.join(target.docsRoot, "05-TEST-QA/Regression-SSoT.md"),
+    path.join(target.docsRoot, "09-PLANNING/Delivery-SSoT.md"),
   ];
   const taskPlans = listTaskPlanPaths(target).slice(0, 20);
   return [...candidates, ...taskPlans].filter((file) => fs.existsSync(file));

package/scripts/lib/phase-kind.mjs

@@ -0,0 +1,50 @@
+export const allowedPhaseKinds = new Set(["init", "execution", "gate"]);
+export const allowedPhaseActors = new Set(["agent", "human", "coordinator"]);
+
+export function normalizePhaseKind(value) {
+  const normalized = String(value || "")
+    .replace(/`/g, "")
+    .trim()
+    .toLowerCase()
+    .replaceAll("_", "-");
+  if (!normalized) return "execution";
+  if (normalized === "exec" || normalized === "implementation") return "execution";
+  if (normalized === "prep" || normalized === "discussion") return "init";
+  if (normalized === "review" || normalized === "closeout") return "gate";
+  return normalized;
+}
+
+export function normalizePhaseActor(value) {
+  const normalized = String(value || "")
+    .replace(/`/g, "")
+    .trim()
+    .toLowerCase()
+    .replaceAll("_", "-");
+  return normalized || "agent";
+}
+
+export function isExecutionPhase(phase) {
+  return normalizePhaseKind(phase?.kind) === "execution";
+}
+
+export function nonSkippedPhases(phases = []) {
+  return phases.filter((phase) => phase.state !== "skipped");
+}
+
+export function implementationPhases(phases = []) {
+  return nonSkippedPhases(phases).filter(isExecutionPhase);
+}
+
+export function phaseCompletionAverage(phases = []) {
+  const scored = implementationPhases(phases);
+  if (scored.length === 0) return 0;
+  return Math.round(scored.reduce((sum, phase) => sum + phase.completion, 0) / scored.length);
+}
+
+export function phaseHasRecordedProgress(phase) {
+  return (
+    phase.completion > 0 ||
+    ["in_progress", "review", "blocked", "done"].includes(String(phase.state || "").toLowerCase()) ||
+    ["partial", "present", "waived"].includes(String(phase.evidenceStatus || "").toLowerCase())
+  );
+}

package/scripts/lib/preset-audit-contracts.mjs

@@ -0,0 +1,37 @@
+import fs from "node:fs";
+import path from "node:path";
+import { readFileSafe, toPosix } from "./core-shared.mjs";
+
+export function validateTaskPresetAuditSnapshot(target, task, presetPackage) {
+  const failures = [];
+  if (!presetPackage?.audit?.manifestRequired) return failures;
+  const bundle = String(task.evidenceBundle || "").replace(/^TARGET:/, "").replace(/^\/+/, "");
+  if (!bundle) {
+    failures.push(`${task.path} ${task.taskPreset} preset missing Evidence Bundle for manifest audit`);
+    return failures;
+  }
+  const auditPath = path.join(target.projectRoot, bundle, "preset-audit.json");
+  if (!fs.existsSync(auditPath)) {
+    failures.push(`${task.path} ${task.taskPreset} preset audit missing: TARGET:${toPosix(path.relative(target.projectRoot, auditPath))}`);
+    return failures;
+  }
+  let audit = null;
+  try {
+    audit = JSON.parse(readFileSafe(auditPath));
+  } catch (error) {
+    failures.push(`${task.path} ${task.taskPreset} preset audit invalid JSON: ${error.message}`);
+    return failures;
+  }
+  if (audit.preset !== task.taskPreset) {
+    failures.push(`${task.path} ${task.taskPreset} preset audit id mismatch: ${audit.preset || "(missing)"}`);
+  }
+  if (String(audit.version || "") !== String(task.presetVersion || "")) {
+    failures.push(`${task.path} ${task.taskPreset} preset audit version mismatch: ${audit.version || "(missing)"}`);
+  }
+  if (!audit.manifestSha256) {
+    failures.push(`${task.path} ${task.taskPreset} preset audit missing manifestSha256`);
+  } else if (audit.manifestSha256 !== presetPackage.manifestSha256) {
+    failures.push(`${task.path} ${task.taskPreset} preset manifest hash mismatch: task audit ${audit.manifestSha256}, current ${presetPackage.manifestSha256}`);
+  }
+  return failures;
+}