coding-agent-harness 1.0.4 → 1.0.5

package/scripts/lib/governance-sync.mjs

@@ -1,10 +1,11 @@
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
+import crypto from "node:crypto";
 import { spawnSync } from "node:child_process";
-import { readBundledTemplate, readFileSafe, repoRoot, todayDate, toPosix, visualMapFile } from "./core-shared.mjs";
+import { readBundledTemplate, readFileSafe, readJsonSafe, repoRoot, todayDate, toPosix, visualMapFile } from "./core-shared.mjs";
 import { collectTasks } from "./task-scanner.mjs";
-import { firstColumn, splitMarkdownRow, updateMarkdownTableRow } from "./markdown-utils.mjs";
-import { markdownCell } from "./task-lifecycle/text-utils.mjs";
+import { appendMarkdownTableRow, firstColumn, fitMarkdownTableRow, splitMarkdownRow, upsertMarkdownTableRow } from "./markdown-utils.mjs";
 
 export class GovernanceSyncError extends Error {
   constructor(message, { code = "governance-sync-failed", details = {}, recovery = [] } = {}) {
@@ -16,38 +17,14 @@ export class GovernanceSyncError extends Error {
   }
 }
 
-export function beginGovernanceSync(target, { operation = "governance-sync", dryRun = false } = {}) {
+export function beginGovernanceSync(target, { operation = "governance-sync", dryRun = false, allowDirtyWorktree = false, allowedRelativePaths = [] } = {}) {
   if (dryRun) return { target, dryRun, operation, git: inspectGit(target.projectRoot), lockPath: "", active: false };
   const lockPath = path.join(target.projectRoot, ".harness/locks/governance-sync.lock");
   fs.mkdirSync(path.dirname(lockPath), { recursive: true });
-  let fd = null;
-  try {
-    fd = fs.openSync(lockPath, "wx");
-    fs.writeFileSync(
-      fd,
-      `${JSON.stringify({
-        operation,
-        pid: process.pid,
-        host: process.env.HOSTNAME || "",
-        branch: currentBranch(target.projectRoot),
-        targetRoot: target.projectRoot,
-        startedAt: new Date().toISOString(),
-      }, null, 2)}\n`,
-    );
-  } catch (error) {
-    if (fd !== null) fs.closeSync(fd);
-    throw new GovernanceSyncError("Governance sync lock already exists; refusing concurrent registry writes.", {
-      code: "governance-lock-exists",
-      details: { lockPath, error: error.message },
-      recovery: [
-        `Inspect ${lockPath}.`,
-        "If no process owns the lock, remove it manually and retry.",
-      ],
-    });
-  }
-  if (fd !== null) fs.closeSync(fd);
+  acquireGovernanceSyncLock(lockPath, target, { operation });
 
   const gitState = inspectGit(target.projectRoot);
+  const allowed = [...new Set((allowedRelativePaths || []).filter(Boolean).map(toPosix))].sort();
   if (gitState.inGit) {
     if (real(gitState.gitRoot) !== real(target.projectRoot)) {
       releaseGovernanceSync({ lockPath, active: true });
@@ -57,7 +34,7 @@ export function beginGovernanceSync(target, { operation = "governance-sync", dry
         recovery: ["Run the harness command against the target repository root."],
       });
     }
-    if (gitState.entries.length > 0) {
+    if (gitState.entries.length > 0 && !allowDirtyWorktree) {
       releaseGovernanceSync({ lockPath, active: true });
       throw new GovernanceSyncError("Governance sync requires a clean Git working tree before CLI-owned writes.", {
         code: "governance-git-dirty",
@@ -65,9 +42,79 @@ export function beginGovernanceSync(target, { operation = "governance-sync", dry
         recovery: ["Commit or otherwise resolve unrelated changes before running this lifecycle command."],
       });
     }
+    if (gitState.entries.length > 0 && allowDirtyWorktree) {
+      try {
+        assertDirtyCompatibleWithWriteScope(gitState.entries, allowed);
+      } catch (error) {
+        releaseGovernanceSync({ lockPath, active: true });
+        throw error;
+      }
+    }
     assertCommitIdentity(target.projectRoot);
   }
-  return { target, dryRun, operation, git: gitState, lockPath, active: true };
+  const initialDirtyEntries = gitState.inGit ? gitState.entries.map((entry) => ({
+    ...entry,
+    fingerprint: fingerprintEntry(target.projectRoot, entry),
+  })) : [];
+  return { target, dryRun, operation, git: gitState, initialDirtyEntries, lockPath, active: true };
+}
+
+function acquireGovernanceSyncLock(lockPath, target, { operation }) {
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    let fd = null;
+    try {
+      fd = fs.openSync(lockPath, "wx");
+      fs.writeFileSync(
+        fd,
+        `${JSON.stringify({
+          operation,
+          pid: process.pid,
+          host: governanceLockHost(),
+          branch: currentBranch(target.projectRoot),
+          targetRoot: target.projectRoot,
+          startedAt: new Date().toISOString(),
+        }, null, 2)}\n`,
+      );
+      fs.closeSync(fd);
+      return;
+    } catch (error) {
+      if (fd !== null) fs.closeSync(fd);
+      if (error?.code === "EEXIST" && attempt === 0 && removeStaleGovernanceSyncLock(lockPath)) continue;
+      throw governanceLockExistsError(lockPath, error);
+    }
+  }
+}
+
+function removeStaleGovernanceSyncLock(lockPath) {
+  const lockContent = readFileSafe(lockPath);
+  const lock = readJsonSafe(lockPath, null);
+  if (!lock) return false;
+  if (lock.host !== governanceLockHost()) return false;
+  if (!Number.isInteger(lock?.pid) || lock.pid <= 0) return false;
+  try {
+    process.kill(lock.pid, 0);
+    return false;
+  } catch (error) {
+    if (error?.code !== "ESRCH") return false;
+  }
+  if (readFileSafe(lockPath) !== lockContent) return false;
+  fs.rmSync(lockPath);
+  return true;
+}
+
+function governanceLockHost() {
+  return process.env.HOSTNAME || os.hostname() || "";
+}
+
+function governanceLockExistsError(lockPath, error) {
+  return new GovernanceSyncError("Governance sync lock already exists; refusing concurrent registry writes.", {
+    code: "governance-lock-exists",
+    details: { lockPath, error: error?.message || String(error) },
+    recovery: [
+      `Inspect ${lockPath}.`,
+      "If no process owns the lock, remove it manually and retry.",
+    ],
+  });
 }
 
 export function releaseGovernanceSync(context) {
@@ -82,24 +129,32 @@ export function releaseGovernanceSync(context) {
 export function commitGovernanceSync(context, allowedRelativePaths, { message = "chore(harness): sync governance state" } = {}) {
   const allowed = [...new Set((allowedRelativePaths || []).filter(Boolean).map(toPosix))].sort();
   if (context?.dryRun || !context?.git?.inGit) return { committed: false, reason: context?.git?.inGit ? "dry-run" : "not-git", allowedPaths: allowed };
-  assertOnlyAllowedChanged(context.target.projectRoot, allowed);
   if (allowed.length === 0) return { committed: false, reason: "no-allowed-paths", allowedPaths: allowed };
+  assertNoUnexpectedOutsideChanges(context.target.projectRoot, allowed, context.initialDirtyEntries || []);
   git(context.target.projectRoot, ["add", "--", ...allowed]);
   assertOnlyAllowedStaged(context.target.projectRoot, allowed);
   const staged = git(context.target.projectRoot, ["diff", "--cached", "--name-only", "-z"]).stdout.split("\0").filter(Boolean);
   if (staged.length === 0) return { committed: false, reason: "no-changes", allowedPaths: allowed };
-  const commitResult = git(context.target.projectRoot, ["commit", "-m", message], { allowFailure: true });
+  const commitResult = git(context.target.projectRoot, ["-c", "core.hooksPath=/dev/null", "commit", "--no-verify", "-m", message], { allowFailure: true });
   if (commitResult.status !== 0) {
+    let outsideChanges = null;
+    try {
+      assertNoUnexpectedOutsideChanges(context.target.projectRoot, allowed, context.initialDirtyEntries || []);
+    } catch (error) {
+      outsideChanges = error.details || null;
+    }
     throw new GovernanceSyncError("Governance sync wrote files but Git commit failed.", {
       code: "governance-git-commit-failed",
-      details: { stdout: commitResult.stdout.trim(), stderr: commitResult.stderr.trim(), allowedPaths: allowed },
+      details: { stdout: commitResult.stdout.trim(), stderr: commitResult.stderr.trim(), allowedPaths: allowed, outsideChanges },
       recovery: [
         `Inspect files: ${allowed.join(", ")}`,
-        `Then run: git add -- ${allowed.join(" ")} && git commit -m ${JSON.stringify(message)}`,
+        `Then run: git add -- ${allowed.join(" ")} && git -c core.hooksPath=/dev/null commit --no-verify -m ${JSON.stringify(message)}`,
       ],
     });
   }
-  assertClean(context.target.projectRoot);
+  assertLastCommitOnlyAllowed(context.target.projectRoot, allowed);
+  assertNoUnexpectedOutsideChanges(context.target.projectRoot, allowed, context.initialDirtyEntries || []);
+  assertWriteScopeClean(context.target.projectRoot, allowed);
   return { committed: true, commitSha: git(context.target.projectRoot, ["rev-parse", "HEAD"]).stdout.trim(), allowedPaths: allowed };
 }
 
@@ -138,7 +193,7 @@ export function syncModuleStepGovernance(target, { moduleKey, stepId, state, dry
       "module-step",
       todayDate(),
     ];
-    fs.writeFileSync(ledgerPath, appendRow(content, /^ID$/i, row));
+    fs.writeFileSync(ledgerPath, appendMarkdownTableRow(content, /^ID$/i, row));
   }
   changes.push({ destination: ledgerRelative, action: dryRun ? "would-sync-governance" : "sync-governance", surface: "harness-ledger" });
   return { changes };
@@ -168,7 +223,7 @@ function syncLedgerRow(target, task, { event, state, message, planPath, reviewPa
       message || "none",
       todayDate(),
     ];
-    fs.writeFileSync(ledgerPath, upsertRow(content, /^ID$/i, (header, existing) => rowMatchesPlan(header, existing, planPath), row));
+    fs.writeFileSync(ledgerPath, upsertMarkdownTableRow(content, /^ID$/i, (header, existing) => rowMatchesPlan(header, existing, planPath), row));
   }
   return { destination: relative, action: dryRun ? "would-sync-governance" : "sync-governance", surface: "harness-ledger" };
 }
@@ -195,7 +250,7 @@ function syncModuleRegistryRow(target, task, { state, planPath, dryRun }) {
       "none",
       todayDate(),
     ];
-    fs.writeFileSync(registryPath, upsertRow(content, /^ID$/i, (header, existing) => rowMatchesModule(header, existing, moduleKey, modulePlan), row));
+    fs.writeFileSync(registryPath, upsertMarkdownTableRow(content, /^ID$/i, (header, existing) => rowMatchesModule(header, existing, moduleKey, modulePlan), row));
   }
   return { destination: relative, action: dryRun ? "would-sync-governance" : "sync-governance", surface: "module-registry" };
 }
@@ -285,7 +340,7 @@ function renderModuleVisualMap(moduleKey, tasks) {
   });
   const graphLines = tasks.map((task, index) => {
     const stepId = moduleStepId(task);
-    const label = markdownCell(task.title || task.shortId || task.id).replace(/"/g, "'");
+    const label = fitMarkdownTableRow([task.title || task.shortId || task.id], 1)[0].replace(/"/g, "'");
     if (index === 0) return `  ${stepId}["${label}"]`;
     const previous = moduleStepId(tasks[index - 1]);
     return `  ${previous} --> ${stepId}["${label}"]`;
@@ -313,7 +368,7 @@ ${graphLines.length ? graphLines.join("\n") : "  EMPTY[\"No module tasks\"]"}
 
 | Phase ID | Depends On | State | Completion | Output | Required Evidence | Evidence Status | Blocking Risk | Owner / Handoff |
 | --- | --- | --- | ---: | --- | --- | --- | --- | --- |
-${rows.map((row) => `| ${fitRow(row, 9).join(" | ")} |`).join("\n")}
+${rows.map((row) => `| ${fitMarkdownTableRow(row, 9).join(" | ")} |`).join("\n")}
 
 Allowed Evidence Status: missing, partial, present, waived.
 `;
@@ -329,10 +384,10 @@ function replaceTableRows(content, headerPattern, rows) {
     if (!separator.every((cell) => /^:?-{3,}:?$/.test(cell))) continue;
     let end = index + 2;
     while (end < lines.length && lines[end].trim().startsWith("|")) end += 1;
-    lines.splice(index + 2, end - index - 2, ...rows.map((row) => `| ${fitRow(row, header.length).join(" | ")} |`));
+    lines.splice(index + 2, end - index - 2, ...rows.map((row) => `| ${fitMarkdownTableRow(row, header.length).join(" | ")} |`));
     return `${lines.join("\n").trimEnd()}\n`;
   }
-  return `${String(content || "").trimEnd()}\n\n${rows.map((row) => `| ${fitRow(row, row.length).join(" | ")} |`).join("\n")}\n`;
+  return `${String(content || "").trimEnd()}\n\n${rows.map((row) => `| ${fitMarkdownTableRow(row, row.length).join(" | ")} |`).join("\n")}\n`;
 }
 
 function existingOrTemplate(filePath, templateSource) {
@@ -361,32 +416,6 @@ function ensureFileFromTemplate(destinationPath, templateSource, { dryRun = fals
   fs.writeFileSync(destinationPath, readBundledTemplate(templateSource));
 }
 
-function upsertRow(content, headerPattern, matcher, row) {
-  const updated = updateMarkdownTableRow(content, headerPattern, (header, existing) => (matcher(header, existing) ? fitRow(row, header.length) : null));
-  if (updated.matched) return updated.content;
-  return appendRow(content, headerPattern, row);
-}
-
-function appendRow(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, `| ${fitRow(row, header.length).join(" | ")} |`);
-    return lines.join("\n");
-  }
-  return `${String(content || "").trimEnd()}\n\n| ${row.join(" | ")} |\n`;
-}
-
-function fitRow(row, length) {
-  const next = row.map((cell) => markdownCell(cell));
-  while (next.length < length) next.push("");
-  return next.slice(0, length);
-}
-
 function rowMatchesPlan(header, row, planPath) {
   const planIndex = firstColumn(header, ["Task Plan", "Plan", "当前产物"]);
   return planIndex >= 0 && String(row[planIndex] || "").includes(planPath);
@@ -446,19 +475,28 @@ function assertCommitIdentity(root) {
   }
 }
 
-function assertOnlyAllowedChanged(root, allowedPaths) {
-  const outside = statusEntries(root).filter((entry) => !allowedPaths.includes(entry.path));
-  if (outside.length > 0) {
-    throw new GovernanceSyncError("Governance sync produced changes outside the allowlist.", {
-      code: "governance-allowlist-violation",
-      details: { disallowed: outside, allowedPaths },
-      recovery: ["Inspect the extra paths; the CLI will not stage or commit unrelated files."],
+function assertDirtyCompatibleWithWriteScope(entries, allowedPaths) {
+  const allowed = new Set(allowedPaths);
+  const overlapping = entries.filter((entry) => allowed.has(entry.path));
+  if (overlapping.length > 0) {
+    throw new GovernanceSyncError("Governance sync write scope overlaps existing dirty files; refusing to overwrite user-owned changes.", {
+      code: "governance-write-scope-dirty",
+      details: { overlapping, allowedPaths },
+      recovery: ["Commit, move, or remove the overlapping files before retrying this lifecycle command."],
+    });
+  }
+  const outsideStaged = entries.filter((entry) => entry.index !== " " && entry.index !== "?" && !allowed.has(entry.path));
+  if (outsideStaged.length > 0) {
+    throw new GovernanceSyncError("Git index contains staged files outside the governance sync write scope.", {
+      code: "governance-index-outside-write-scope",
+      details: { disallowed: outsideStaged, allowedPaths },
+      recovery: ["Unstage unrelated files before retrying the lifecycle command."],
     });
   }
 }
 
 function assertOnlyAllowedStaged(root, allowedPaths) {
-  const outside = statusEntries(root).filter((entry) => entry.index !== " " && !allowedPaths.includes(entry.path));
+  const outside = statusEntries(root).filter((entry) => entry.index !== " " && entry.index !== "?" && !allowedPaths.includes(entry.path));
   if (outside.length > 0) {
     throw new GovernanceSyncError("Git index contains staged files outside the governance sync allowlist.", {
       code: "governance-index-allowlist-violation",
@@ -468,17 +506,76 @@ function assertOnlyAllowedStaged(root, allowedPaths) {
   }
 }
 
-function assertClean(root) {
+function assertNoUnexpectedOutsideChanges(root, allowedPaths, initialDirtyEntries) {
+  const allowed = new Set(allowedPaths);
+  const initialByPath = new Map(
+    (initialDirtyEntries || [])
+      .filter((entry) => !allowed.has(entry.path))
+      .map((entry) => [entry.path, entry]),
+  );
+  const unexpected = [];
+  const changed = [];
+  for (const entry of statusEntries(root)) {
+    if (allowed.has(entry.path)) continue;
+    const current = { ...entry, fingerprint: fingerprintEntry(root, entry) };
+    const initial = initialByPath.get(entry.path);
+    if (!initial) {
+      unexpected.push(current);
+    } else if (initial.raw !== current.raw || initial.fingerprint !== current.fingerprint) {
+      changed.push({ before: initial, after: current });
+    }
+  }
+  if (unexpected.length > 0 || changed.length > 0) {
+    throw new GovernanceSyncError("Governance sync produced changes outside its write scope.", {
+      code: "governance-allowlist-violation",
+      details: { unexpected, changed, allowedPaths },
+      recovery: ["Inspect the extra paths; the CLI will not stage or commit unrelated files."],
+    });
+  }
+}
+
+function assertLastCommitOnlyAllowed(root, allowedPaths) {
+  const committed = git(root, ["diff-tree", "--no-commit-id", "--name-only", "-r", "-z", "HEAD"]).stdout
+    .split("\0")
+    .filter(Boolean)
+    .map(toPosix);
+  const outside = committed.filter((file) => !allowedPaths.includes(file));
+  if (outside.length > 0) {
+    throw new GovernanceSyncError("Governance sync commit contains files outside its write scope.", {
+      code: "governance-commit-allowlist-violation",
+      details: { disallowed: outside, committed, allowedPaths },
+      recovery: ["Inspect the last commit and remove any files that are not owned by the lifecycle command."],
+    });
+  }
+}
+
+function assertWriteScopeClean(root, allowedPaths) {
   const entries = statusEntries(root);
-  if (entries.length > 0) {
-    throw new GovernanceSyncError("Governance sync commit completed but working tree is not clean.", {
+  const remaining = entries.filter((entry) => allowedPaths.includes(entry.path));
+  if (remaining.length > 0) {
+    throw new GovernanceSyncError("Governance sync commit completed but write scope is not clean.", {
       code: "governance-post-commit-dirty",
-      details: { entries },
-      recovery: ["Inspect remaining files before continuing."],
+      details: { entries: remaining, allowedPaths },
+      recovery: ["Inspect remaining write-scope files before continuing."],
     });
   }
 }
 
+function fingerprintEntry(root, entry) {
+  const absolute = path.join(root, entry.path);
+  try {
+    const stat = fs.lstatSync(absolute);
+    if (stat.isSymbolicLink()) return `symlink:${fs.readlinkSync(absolute)}`;
+    if (stat.isFile()) {
+      return `file:${stat.size}:${crypto.createHash("sha256").update(fs.readFileSync(absolute)).digest("hex")}`;
+    }
+    if (stat.isDirectory()) return "directory";
+    return `${stat.mode}:${stat.size}`;
+  } catch {
+    return "missing";
+  }
+}
+
 function statusEntries(root) {
   return git(root, ["status", "--porcelain=v1", "--untracked-files=all"]).stdout
     .split(/\r?\n/)

package/scripts/lib/harness-core.mjs

@@ -2,6 +2,7 @@ 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";

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/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-engine.mjs

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import crypto from "node:crypto";
 import { spawnSync } from "node:child_process";
-import { repoRoot, taskContractMarker, toPosix, visualMapFile } from "./core-shared.mjs";
+import { readJsonSafe, repoRoot, taskContractMarker, toPosix, visualMapFile } from "./core-shared.mjs";
 import { verifyMigrationSession } from "./migration-planner.mjs";
 import { buildPresetAudit, renderPresetTemplate } from "./preset-registry.mjs";
 
@@ -25,12 +25,9 @@ export function resolvePresetInputs(preset, { cliArgs = [], fromSession = "", ta
       }
       const filePath = path.resolve(String(rawValue));
       if (!fs.existsSync(filePath)) throw new Error(`Preset input file not found for ${declaration.flag || name}: ${rawValue}`);
-      let value;
-      try {
-        value = JSON.parse(fs.readFileSync(filePath, "utf8"));
-      } catch (error) {
-        throw new Error(`Invalid preset JSON input ${declaration.flag || name}: ${error.message}`);
-      }
+      let readError = null;
+      const value = readJsonSafe(filePath, null, { onError: (error) => { readError = error; } });
+      if (value === null) throw new Error(`Invalid preset JSON input ${declaration.flag || name}: ${readError?.message || "unknown parse error"}`);
       if (declaration.validateOperation && value.operation !== declaration.validateOperation) {
         throw new Error(`${preset.id} preset requires ${declaration.flag || name} operation ${declaration.validateOperation}`);
       }
@@ -463,7 +460,7 @@ function targetCommit(projectRoot) {
 
 function packageVersion() {
   try {
-    return JSON.parse(fs.readFileSync(path.join(repoRoot, "package.json"), "utf8")).version || "unknown";
+    return readJsonSafe(path.join(repoRoot, "package.json"), {}).version || "unknown";
   } catch {
     return "unknown";
   }