@mstar-harness/engine 3.7.0 → 3.7.1

package/dist/engine.js

@@ -2357,8 +2357,8 @@ function hasFiles(dir) {
 }
 // src/worktree.ts
 import { execFileSync as execFileSync2 } from "node:child_process";
-import { existsSync as existsSync7 } from "node:fs";
-import { isAbsolute as isAbsolute5, resolve as resolve8 } from "node:path";
+import { existsSync as existsSync7, realpathSync as realpathSync3 } from "node:fs";
+import { isAbsolute as isAbsolute5, join as join10, resolve as resolve8 } from "node:path";
 var DEFAULT_PROBE_TIMEOUT_MS = 1e4;
 function probeTimeoutMs() {
   const raw = process.env.MSTAR_GIT_PROBE_TIMEOUT_MS;
@@ -2397,6 +2397,51 @@ function probeBranch(worktreePath, opts) {
     return { error: detail };
   }
 }
+function probeCheckout(worktreePath, opts) {
+  const timeout = opts.timeoutMs ?? probeTimeoutMs();
+  try {
+    const stdout = execFileSync2(opts.gitPath ?? "git", ["-C", worktreePath, "rev-parse", "--git-dir"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout
+    });
+    const raw = stdout.trim();
+    if (raw === "")
+      return { error: `no git dir reported at "${worktreePath}"` };
+    const abs = isAbsolute5(raw) ? raw : join10(worktreePath, raw);
+    return { gitDir: realpathSync3(abs) };
+  } catch (err) {
+    const e = err;
+    if (e.killed === true || e.signal !== undefined) {
+      return { error: `git probe timed out after ${timeout}ms (killed by ${e.signal ?? "SIGTERM"})` };
+    }
+    const detail = (e.stderr !== undefined ? e.stderr.toString().trim() : "") || e.message || "git probe failed";
+    return { error: detail };
+  }
+}
+function isDistinctCheckout(controlPath, candidatePath, opts = {}) {
+  const control = probeCheckout(controlPath, opts);
+  const candidate = probeCheckout(candidatePath, opts);
+  if ("error" in control || "error" in candidate)
+    return false;
+  return control.gitDir !== candidate.gitDir;
+}
+function probeCheckoutRoot(path, opts = {}) {
+  const timeout = opts.timeoutMs ?? probeTimeoutMs();
+  try {
+    const stdout = execFileSync2(opts.gitPath ?? "git", ["-C", path, "rev-parse", "--show-toplevel"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout
+    });
+    const raw = stdout.trim();
+    if (raw === "")
+      return null;
+    return realpathSync3(raw);
+  } catch {
+    return null;
+  }
+}
 function l1PreDispatchCheck(input, opts = {}) {
   const violations = [];
   const { controlWorktreePath, leaseWorktreePath, leaseWorkingBranch, planId } = input;
@@ -2409,8 +2454,20 @@ function l1PreDispatchCheck(input, opts = {}) {
   if (leaseWorkingBranch.trim() === "") {
     violations.push(violation7("high", "worktree.l1.lease-branch-missing", `execution_lease.working_branch is empty for plan "${planId}"`, "record the lease working_branch before dispatch"));
   }
-  if (controlWorktreePath !== "" && leaseWorktreePath !== "" && resolve8(controlWorktreePath) === resolve8(leaseWorktreePath)) {
-    violations.push(violation7("critical", "worktree.l1.lease-equals-control", `execution_lease.worktree_path "${leaseWorktreePath}" equals metadata.control_worktree_path — the feature worktree MUST differ from the control worktree (L1 isolation; product edits never land in the control checkout)`, "use a distinct feature worktree for the plan (git worktree add <path> <branch>) and update the lease"));
+  if (controlWorktreePath !== "" && leaseWorktreePath !== "") {
+    if (resolve8(controlWorktreePath) === resolve8(leaseWorktreePath)) {
+      violations.push(violation7("critical", "worktree.l1.lease-equals-control", `execution_lease.worktree_path "${leaseWorktreePath}" equals metadata.control_worktree_path — the feature worktree MUST differ from the control worktree (L1 isolation; product edits never land in the control checkout)`, "use a distinct feature worktree for the plan (git worktree add <path> <branch>) and update the lease"));
+    } else if (existsSync7(leaseWorktreePath)) {
+      const controlProbe = probeCheckout(controlWorktreePath, opts);
+      const leaseProbe = probeCheckout(leaseWorktreePath, opts);
+      if ("error" in controlProbe) {
+        violations.push(violation7("high", "worktree.l1.checkout-probe-failed", `cannot establish the lease worktree "${leaseWorktreePath}" is a distinct Git checkout from the control worktree "${controlWorktreePath}" for plan "${planId}": ${controlProbe.error}`, "verify the control worktree path is a git checkout (integration-branch checkout)"));
+      } else if ("error" in leaseProbe) {
+        violations.push(violation7("high", "worktree.l1.checkout-probe-failed", `cannot establish the lease worktree "${leaseWorktreePath}" is a distinct Git checkout from the control worktree "${controlWorktreePath}" for plan "${planId}": ${leaseProbe.error}`, "verify the lease worktree path is a git checkout (git worktree add <path> <branch>)"));
+      } else if (controlProbe.gitDir === leaseProbe.gitDir) {
+        violations.push(violation7("critical", "worktree.l1.lease-equals-control", `execution_lease.worktree_path "${leaseWorktreePath}" is the same Git checkout as metadata.control_worktree_path "${controlWorktreePath}" — a plain subdirectory or symlink alias of the control checkout is not isolation; the feature worktree MUST be a distinct checkout`, "use a distinct feature worktree for the plan (git worktree add <path> <branch>) and update the lease"));
+      }
+    }
   }
   if (leaseWorktreePath !== "" && !existsSync7(leaseWorktreePath)) {
     violations.push(violation7("high", "worktree.l1.feature-missing", `feature worktree directory "${leaseWorktreePath}" does not exist for plan "${planId}"`, `create it before dispatch: git worktree add ${leaseWorktreePath} <working-branch>`));
@@ -2459,11 +2516,17 @@ function l2PreDispatchCheck(input, opts = {}) {
   });
   return gate(violations);
 }
-function assertControlVsFeaturePath(controlWorktreePath, featureWorktreePath) {
+function assertControlVsFeaturePath(controlWorktreePath, featureWorktreePath, opts = {}) {
   const violations = [];
-  const samePath = controlWorktreePath === "" && featureWorktreePath === "" || controlWorktreePath !== "" && featureWorktreePath !== "" && resolve8(controlWorktreePath) === resolve8(featureWorktreePath);
-  if (samePath) {
-    violations.push(violation7("critical", "worktree.control-feature.same", `control worktree path equals feature/lease worktree path "${controlWorktreePath}" — execution_lease.worktree_path MUST differ from metadata.control_worktree_path`, "use a distinct feature worktree for the plan's product edits"));
+  if (controlWorktreePath === "" && featureWorktreePath === "") {
+    violations.push(violation7("critical", "worktree.control-feature.same", `control worktree path and feature/lease worktree path are both empty — execution_lease.worktree_path MUST differ from metadata.control_worktree_path`, "record a distinct feature worktree path"));
+    return gate(violations);
+  }
+  if (controlWorktreePath === "" || featureWorktreePath === "") {
+    return gate(violations);
+  }
+  if (!isDistinctCheckout(controlWorktreePath, featureWorktreePath, opts)) {
+    violations.push(violation7("critical", "worktree.control-feature.same", `control worktree path "${controlWorktreePath}" and feature/lease worktree path "${featureWorktreePath}" are not distinct Git checkouts — a plain subdirectory or symlink alias of the control checkout is not isolation; execution_lease.worktree_path MUST be a distinct checkout`, "use a distinct feature worktree for the plan's product edits (git worktree add <path> <branch>)"));
   }
   return gate(violations);
 }
@@ -2509,9 +2572,9 @@ function singleReviewSnapshot(assignments) {
 }
 // src/sdd.ts
 import { execFileSync as execFileSync3, spawn } from "node:child_process";
-import { mkdirSync as mkdirSync6, readdirSync as readdirSync6, readFileSync as readFileSync7, realpathSync as realpathSync3, statSync as statSync4, writeFileSync as writeFileSync4 } from "node:fs";
+import { mkdirSync as mkdirSync6, readdirSync as readdirSync6, readFileSync as readFileSync7, realpathSync as realpathSync4, statSync as statSync4, writeFileSync as writeFileSync4 } from "node:fs";
 import { constants as osConstants } from "node:os";
-import { basename as basename4, dirname as dirname6, isAbsolute as isAbsolute6, join as join10, relative as relative3, resolve as resolve9 } from "node:path";
+import { basename as basename4, dirname as dirname6, isAbsolute as isAbsolute6, join as join11, relative as relative3, resolve as resolve9 } from "node:path";
 class SddScriptError extends Error {
   exitCode;
   constructor(message, exitCode) {
@@ -2548,14 +2611,14 @@ function gitOut(cwd, args) {
   }
 }
 function probeHarnessWithStatus(root) {
-  if (isFile2(join10(root, ".mstar", "status.json")))
-    return join10(root, ".mstar");
-  if (isFile2(join10(root, ".agents", "status.json")))
-    return join10(root, ".agents");
-  if (hasWorkflowSnapshot(join10(root, ".mstar")))
-    return join10(root, ".mstar");
-  if (hasWorkflowSnapshot(join10(root, ".agents")))
-    return join10(root, ".agents");
+  if (isFile2(join11(root, ".mstar", "status.json")))
+    return join11(root, ".mstar");
+  if (isFile2(join11(root, ".agents", "status.json")))
+    return join11(root, ".agents");
+  if (hasWorkflowSnapshot(join11(root, ".mstar")))
+    return join11(root, ".mstar");
+  if (hasWorkflowSnapshot(join11(root, ".agents")))
+    return join11(root, ".agents");
   return null;
 }
 function hasWorkflowSnapshot(harnessDir) {
@@ -2563,13 +2626,13 @@ function hasWorkflowSnapshot(harnessDir) {
   try {
     workflowsDir = resolveWorkflowDir(harnessDir, { harnessDir });
   } catch {
-    workflowsDir = join10(harnessDir, "workflows");
+    workflowsDir = join11(harnessDir, "workflows");
   }
   if (!isDirectory2(workflowsDir))
     return false;
   try {
     for (const entry of readdirSync6(workflowsDir, { withFileTypes: true })) {
-      if (entry.isDirectory() && isFile2(join10(workflowsDir, entry.name, "snapshot.json")))
+      if (entry.isDirectory() && isFile2(join11(workflowsDir, entry.name, "snapshot.json")))
         return true;
     }
   } catch {
@@ -2582,14 +2645,14 @@ function isLinkedWorktree(root) {
   const commonRaw = gitOut(root, ["rev-parse", "--git-common-dir"]);
   if (gitDirRaw === null || commonRaw === null)
     return false;
-  const gitDir = isAbsolute6(gitDirRaw) ? gitDirRaw : join10(root, gitDirRaw);
-  const common = isAbsolute6(commonRaw) ? commonRaw : join10(root, commonRaw);
+  const gitDir = isAbsolute6(gitDirRaw) ? gitDirRaw : join11(root, gitDirRaw);
+  const common = isAbsolute6(commonRaw) ? commonRaw : join11(root, commonRaw);
   if (gitDir.includes("/.git/worktrees/") || gitDir.includes("/worktrees/"))
     return true;
   try {
-    const gdParent = realpathSync3(dirname6(gitDir));
-    const cmAbs = realpathSync3(common);
-    return join10(gdParent, basename4(gitDir)) !== cmAbs && gitDir !== cmAbs;
+    const gdParent = realpathSync4(dirname6(gitDir));
+    const cmAbs = realpathSync4(common);
+    return join11(gdParent, basename4(gitDir)) !== cmAbs && gitDir !== cmAbs;
   } catch {
     return false;
   }
@@ -2606,10 +2669,10 @@ function sddWorkspace(planId, opts = {}) {
     if (!isDirectory2(controlRoot)) {
       throw new SddScriptError(`mstar sdd workspace: CONTROL_ROOT / MSTAR_CONTROL_ROOT is not a directory: ${controlRoot}`, 1);
     }
-    root = realpathSync3(controlRoot);
+    root = realpathSync4(controlRoot);
   } else {
     const topLevel = gitOut(cwd, ["rev-parse", "--show-toplevel"]);
-    root = realpathSync3(topLevel ?? cwd);
+    root = realpathSync4(topLevel ?? cwd);
   }
   if (!controlRoot && isLinkedWorktree(root)) {
     throw new SddScriptError(`mstar sdd workspace: linked worktree at ${root} has no {HARNESS_DIR}/status.json (default gitignore).
@@ -2630,20 +2693,20 @@ function sddWorkspace(planId, opts = {}) {
       const probed = probeHarnessWithStatus(root);
       if (probed) {
         harnessDir = probed;
-      } else if (isDirectory2(join10(root, ".mstar"))) {
-        harnessDir = join10(root, ".mstar");
-      } else if (isDirectory2(join10(root, ".agents"))) {
-        harnessDir = join10(root, ".agents");
+      } else if (isDirectory2(join11(root, ".mstar"))) {
+        harnessDir = join11(root, ".mstar");
+      } else if (isDirectory2(join11(root, ".agents"))) {
+        harnessDir = join11(root, ".agents");
       } else {
-        harnessDir = join10(root, ".mstar");
+        harnessDir = join11(root, ".mstar");
       }
     }
   }
   const sddDir = resolveSddDir(harnessDir, planId);
   mkdirSync6(sddDir, { recursive: true });
-  writeFileSync4(join10(sddDir, ".gitignore"), `*
+  writeFileSync4(join11(sddDir, ".gitignore"), `*
 `);
-  return realpathSync3(sddDir);
+  return realpathSync4(sddDir);
 }
 function taskBrief(planFile, taskN, outFile, opts = {}) {
   if (!planFile || !Number.isInteger(taskN) || taskN < 1) {
@@ -2670,7 +2733,7 @@ function taskBrief(planFile, taskN, outFile, opts = {}) {
   if (outFile) {
     out = bound ? resolve9(observedCwd, outFile) : outFile;
   } else if (bound) {
-    out = join10(bound.sddDir, `task-${taskN}-brief.md`);
+    out = join11(bound.sddDir, `task-${taskN}-brief.md`);
     mkdirAfterGate = bound.sddDir;
   } else {
     const sddDir = opts.sddDir ?? process.env.SDD_DIR;
@@ -2678,7 +2741,7 @@ function taskBrief(planFile, taskN, outFile, opts = {}) {
       throw new SddScriptError("mstar sdd task-brief: set SDD_DIR or pass OUTFILE (run mstar sdd workspace PLAN_ID first)", 2);
     }
     mkdirSync6(sddDir, { recursive: true });
-    out = join10(sddDir, `task-${taskN}-brief.md`);
+    out = join11(sddDir, `task-${taskN}-brief.md`);
   }
   if (bound) {
     const gate2 = checkSddAction(bound, { kind: "artifact", cwd: observedCwd, target: out });
@@ -2736,7 +2799,7 @@ function reviewPackage(base, head, outFile, opts = {}) {
   } else if (bound) {
     const shortBase = gitOut(cwd, ["rev-parse", "--short", base]) ?? base;
     const shortHead = gitOut(cwd, ["rev-parse", "--short", head]) ?? head;
-    out = join10(bound.sddDir, `review-${shortBase}..${shortHead}.diff`);
+    out = join11(bound.sddDir, `review-${shortBase}..${shortHead}.diff`);
     mkdirAfterGate = bound.sddDir;
   } else {
     const sddDir = opts.sddDir ?? process.env.SDD_DIR;
@@ -2746,7 +2809,7 @@ function reviewPackage(base, head, outFile, opts = {}) {
     mkdirSync6(sddDir, { recursive: true });
     const shortBase = gitOut(cwd, ["rev-parse", "--short", base]) ?? base;
     const shortHead = gitOut(cwd, ["rev-parse", "--short", head]) ?? head;
-    out = join10(sddDir, `review-${shortBase}..${shortHead}.diff`);
+    out = join11(sddDir, `review-${shortBase}..${shortHead}.diff`);
   }
   if (bound) {
     const gate2 = checkSddAction(bound, { kind: "artifact", cwd: observedCwd, target: out });
@@ -2789,7 +2852,7 @@ function assertBaseSha(ref, opts = {}) {
 }
 function taskReportExists(sddDir, taskN) {
   try {
-    const st = statSync4(join10(sddDir, `task-${taskN}-report.md`));
+    const st = statSync4(join11(sddDir, `task-${taskN}-report.md`));
     return st.isFile() && st.size > 0;
   } catch {
     return false;
@@ -2798,7 +2861,7 @@ function taskReportExists(sddDir, taskN) {
 function readProgressLedger(sddDir) {
   let content;
   try {
-    content = readFileSync7(join10(sddDir, "progress.md"), "utf8");
+    content = readFileSync7(join11(sddDir, "progress.md"), "utf8");
   } catch {
     return [];
   }
@@ -2839,7 +2902,7 @@ function isInside(child, ancestor) {
 }
 function canonicalDir(path) {
   try {
-    return statSync4(path).isDirectory() ? realpathSync3(path) : null;
+    return statSync4(path).isDirectory() ? realpathSync4(path) : null;
   } catch {
     return null;
   }
@@ -2857,7 +2920,7 @@ function throwUsage(message) {
   throw new SddScriptError(message, 2);
 }
 function readActiveWorkflowIds(controlHarnessRoot) {
-  const statusPath = join10(controlHarnessRoot, "status.json");
+  const statusPath = join11(controlHarnessRoot, "status.json");
   if (!isFile2(statusPath))
     return null;
   let doc;
@@ -2892,7 +2955,7 @@ function findWorkflowPlanRow(controlHarnessRoot, planId) {
   }
   const matches = [];
   for (const id of workflowIds) {
-    const snapshotPath = join10(workflowsDir, id, WORKFLOW_SNAPSHOT_FILE);
+    const snapshotPath = join11(workflowsDir, id, WORKFLOW_SNAPSHOT_FILE);
     if (!isFile2(snapshotPath))
       continue;
     let doc;
@@ -2984,15 +3047,20 @@ function resolveSddExecutionContext(input) {
       contextViolation("high", "sdd.context.feature-cwd-missing", `featureCwd "${input.featureCwd}" does not exist or is not a directory — the feature worktree is the required cwd for product edits`, `create the feature worktree first (git worktree add ${input.featureCwd} ${workingBranch})`)
     ]);
   }
-  const controlCheckout = dirname6(canonicalControlHarnessRoot);
-  if (isInside(canonicalFeatureCwd, controlCheckout)) {
+  if (isInside(canonicalControlHarnessRoot, canonicalFeatureCwd)) {
     throwGateFail([
-      contextViolation("critical", "sdd.context.feature-in-control", `featureCwd "${canonicalFeatureCwd}" is inside the control checkout "${controlCheckout}" — product edits never land in the control checkout (execution_lease.worktree_path MUST differ from metadata.control_worktree_path)`, "use a distinct feature worktree for the plan")
+      contextViolation("critical", "sdd.context.control-inside-feature", `controlHarnessRoot "${canonicalControlHarnessRoot}" is inside featureCwd "${canonicalFeatureCwd}" — a feature worktree's same-looking {HARNESS_DIR} is not the SSOT; the control harness must live outside the feature checkout`)
     ]);
   }
-  if (isInside(canonicalControlHarnessRoot, canonicalFeatureCwd)) {
+  const controlCheckout = probeCheckoutRoot(canonicalControlHarnessRoot);
+  if (controlCheckout === null) {
     throwGateFail([
-      contextViolation("critical", "sdd.context.control-inside-feature", `controlHarnessRoot "${canonicalControlHarnessRoot}" is inside featureCwd "${canonicalFeatureCwd}" — a feature worktree's same-looking {HARNESS_DIR} is not the SSOT; the control harness must live outside the feature checkout`)
+      contextViolation("high", "sdd.context.control-root-unresolvable", `cannot resolve the control checkout root for controlHarnessRoot "${canonicalControlHarnessRoot}" (git rev-parse --show-toplevel failed) — the control harness must live inside a git checkout`, "verify the control harness root is inside the control worktree checkout")
+    ]);
+  }
+  if (isInside(canonicalFeatureCwd, controlCheckout) && !isDistinctCheckout(canonicalControlHarnessRoot, canonicalFeatureCwd)) {
+    throwGateFail([
+      contextViolation("critical", "sdd.context.feature-in-control", `featureCwd "${canonicalFeatureCwd}" is inside the control checkout "${controlCheckout}" and is not a distinct Git checkout — a plain subdirectory or symlink alias of the control checkout is not isolation; product edits never land in the control checkout (execution_lease.worktree_path MUST be a distinct checkout)`, "use a distinct feature worktree for the plan (git worktree add <path> <branch>)")
     ]);
   }
   const match = findWorkflowPlanRow(canonicalControlHarnessRoot, planId);
@@ -3037,7 +3105,7 @@ function resolveSddExecutionContext(input) {
     controlHarnessRoot: canonicalControlHarnessRoot,
     featureCwd: canonicalFeatureCwd,
     workingBranch,
-    planFile: realpathSync3(input.planFile),
+    planFile: realpathSync4(input.planFile),
     sddDir: canonicalSddDir
   };
 }
@@ -3177,9 +3245,183 @@ async function runInSddContext(context, argv) {
     });
   });
 }
+// src/gates.ts
+import { existsSync as existsSync8, statSync as statSync5 } from "node:fs";
+import { basename as basename5, dirname as dirname7, join as join12, relative as relative4, resolve as resolve10 } from "node:path";
+var STATUS_FILE = "status.json";
+var SNAPSHOT_FILE = "snapshot.json";
+var REGISTER_FILE = "residuals.json";
+function eventTargetPaths(input) {
+  if (typeof input !== "object" || input === null)
+    return [];
+  const record = input;
+  const paths = [];
+  const push = (value) => {
+    if (typeof value === "string" && value.trim() !== "")
+      paths.push(value);
+  };
+  push(record.path);
+  if (Array.isArray(record.paths)) {
+    for (const value of record.paths)
+      push(value);
+  }
+  return paths;
+}
+function hasEntry(dir, name) {
+  try {
+    statSync5(join12(dir, name));
+    return true;
+  } catch {
+    return false;
+  }
+}
+function hasHarnessRootMarkers(dir) {
+  if (!hasEntry(dir, STATUS_FILE))
+    return false;
+  if (hasEntry(dir, "workflows") && hasEntry(dir, "projects"))
+    return true;
+  try {
+    return hasEntry(resolveWorkflowDir(dir, { harnessDir: dir }), "") && hasEntry(resolveProjectDir(dir, { harnessDir: dir }), "");
+  } catch {
+    return false;
+  }
+}
+function resolveHarnessRootOf(target) {
+  let dir = resolve10(target);
+  for (;; ) {
+    if (hasHarnessRootMarkers(dir))
+      return dir;
+    const parent = dirname7(dir);
+    if (parent === dir)
+      return null;
+    dir = parent;
+  }
+}
+function harnessDocKindOfTarget(targetPath) {
+  if (typeof targetPath !== "string" || targetPath.trim() === "")
+    return null;
+  const resolved = resolve10(targetPath);
+  const name = basename5(resolved);
+  if (name !== STATUS_FILE && name !== SNAPSHOT_FILE && name !== REGISTER_FILE)
+    return null;
+  const classify = (harnessDir2) => {
+    const rel = relative4(harnessDir2, resolved);
+    if (name === STATUS_FILE && rel === STATUS_FILE)
+      return { harnessDir: harnessDir2, kind: "status" };
+    let workflowDir;
+    let projectDir;
+    try {
+      workflowDir = resolveWorkflowDir(harnessDir2, { harnessDir: harnessDir2 });
+      projectDir = resolveProjectDir(harnessDir2, { harnessDir: harnessDir2 });
+    } catch {
+      workflowDir = join12(harnessDir2, "workflows");
+      projectDir = join12(harnessDir2, "projects");
+    }
+    if (name === SNAPSHOT_FILE && /^[^/]+\/snapshot\.json$/.test(relative4(workflowDir, resolved))) {
+      return { harnessDir: harnessDir2, kind: "snapshot" };
+    }
+    if (name === REGISTER_FILE && /^[^/]+\/residuals\.json$/.test(relative4(projectDir, resolved))) {
+      return { harnessDir: harnessDir2, kind: "register" };
+    }
+    return null;
+  };
+  const probeRoot = resolveHarnessRootOf(dirname7(resolved));
+  const harnessDir = probeRoot ?? resolveHarnessDir(dirname7(resolved));
+  if (harnessDir === null)
+    return null;
+  const classified = classify(harnessDir);
+  if (classified !== null)
+    return classified;
+  if (probeRoot === null)
+    return null;
+  const fallbackDir = resolveHarnessDir(dirname7(resolved));
+  if (fallbackDir === null || fallbackDir === probeRoot)
+    return null;
+  return classify(fallbackDir);
+}
+function violationLine(violation8) {
+  return `[${violation8.severity}] ${violation8.code}: ${violation8.message}${violation8.fix ? ` (fix: ${violation8.fix})` : ""}`;
+}
+var MAX_STATUS_CONTENT_LENGTH = 2 * 1024 * 1024;
+function oversizedViolation(filePath) {
+  return {
+    ok: false,
+    severity: "high",
+    code: "status.oversized",
+    message: `${basename5(filePath)} exceeds the ${MAX_STATUS_CONTENT_LENGTH}-byte (2 MiB) coordination-document validation budget — repair out of band or disable for this session with MSTAR_WRITE_GATE=off`
+  };
+}
+function validateStatusWriteDoc(content, filePath, kind, options = {}) {
+  const oversized = options.oversized ?? "pass";
+  if (typeof content === "string") {
+    if (content.length > MAX_STATUS_CONTENT_LENGTH) {
+      return oversized === "violate" ? [oversizedViolation(filePath)] : [];
+    }
+    let doc2;
+    try {
+      doc2 = JSON.parse(content);
+    } catch (error) {
+      return [
+        {
+          ok: false,
+          severity: "high",
+          code: "status.invalid-json",
+          message: error.message
+        }
+      ];
+    }
+    if (doc2 === null || typeof doc2 !== "object" || Array.isArray(doc2)) {
+      return [
+        {
+          ok: false,
+          severity: "high",
+          code: "status.invalid-json",
+          message: `${basename5(filePath)} content must be a JSON object`
+        }
+      ];
+    }
+    return validateDocByKind(doc2, kind);
+  }
+  if (!existsSync8(filePath))
+    return [];
+  try {
+    if (statSync5(filePath).size > MAX_STATUS_CONTENT_LENGTH) {
+      return oversized === "violate" ? [oversizedViolation(filePath)] : [];
+    }
+  } catch {
+    return [];
+  }
+  if (kind === "status")
+    return validateStatus(filePath).violations;
+  let doc;
+  try {
+    doc = readJson(filePath);
+  } catch (error) {
+    return [
+      {
+        ok: false,
+        severity: "high",
+        code: "status.invalid-json",
+        message: error.message
+      }
+    ];
+  }
+  return validateDocByKind(doc, kind);
+}
+function validateDocByKind(doc, kind) {
+  if (kind === "snapshot")
+    return validateWorkflowSnapshot(doc).violations;
+  if (kind === "register")
+    return validateProjectRegister(doc).violations;
+  return validateStatus(doc).violations;
+}
+function formatStatusWriteBlockReason(violations, skillPointer) {
+  return violations.map((v) => `${violationLine(v)} (${skillPointer})`).join(`
+`);
+}
 // src/migrate.ts
 import { copyFileSync, mkdirSync as mkdirSync7, readFileSync as readFileSync8, readdirSync as readdirSync7, writeFileSync as writeFileSync5 } from "node:fs";
-import { dirname as dirname7, isAbsolute as isAbsolute7, join as join11, relative as relative4, resolve as resolve10, sep as sep2 } from "node:path";
+import { dirname as dirname8, isAbsolute as isAbsolute7, join as join13, relative as relative5, resolve as resolve11, sep as sep2 } from "node:path";
 var MIGRATE_STATUS_FILE = "status.json";
 var ARCHIVED_STATUS_V1_FILE = "archived/status.v1.json";
 var NOTES_LEDGER_FILE = "notes.jsonl";
@@ -3219,7 +3461,7 @@ function todayString3() {
   return `${now.getFullYear()}-${month}-${day}`;
 }
 function scanCompasses(harnessDir) {
-  const iterationsDir = join11(harnessDir, "iterations");
+  const iterationsDir = join13(harnessDir, "iterations");
   const out = [];
   let entries;
   try {
@@ -3230,7 +3472,7 @@ function scanCompasses(harnessDir) {
   for (const entry of entries) {
     if (!entry.isDirectory())
       continue;
-    const compassPath = join11(iterationsDir, entry.name, "delivery-compass.md");
+    const compassPath = join13(iterationsDir, entry.name, "delivery-compass.md");
     let content;
     try {
       content = readFileSync8(compassPath, "utf8");
@@ -3310,8 +3552,8 @@ function buildIterationSnapshot(compass, rowById, rootUpdatedAt) {
     id: compass.id,
     type: "iteration",
     status,
-    file: join11("workflows", compass.id, WORKFLOW_SNAPSHOT_FILE),
-    source: join11("iterations", compass.id, "delivery-compass.md"),
+    file: join13("workflows", compass.id, WORKFLOW_SNAPSHOT_FILE),
+    source: join13("iterations", compass.id, "delivery-compass.md"),
     data: snapshot
   };
 }
@@ -3346,7 +3588,7 @@ function buildStandaloneSnapshot(row, rootUpdatedAt, migrationNotes) {
     id,
     type: "plan",
     status,
-    file: join11("workflows", id, WORKFLOW_SNAPSHOT_FILE),
+    file: join13("workflows", id, WORKFLOW_SNAPSHOT_FILE),
     source: "status.json plans[] row",
     data: snapshot
   };
@@ -3454,7 +3696,7 @@ function buildRegister(residualFindings, byPlan, projectId, migratedAt) {
     return null;
   const doc = { entries };
   return {
-    file: join11("projects", projectId, PROJECT_REGISTER_FILE),
+    file: join13("projects", projectId, PROJECT_REGISTER_FILE),
     source: "status.json residual_findings",
     data: doc
   };
@@ -3485,7 +3727,7 @@ function collectNotesFiles(snapshots) {
     if (lines.length === 0)
       continue;
     out.push({
-      file: join11(dirname7(snapshot.file), NOTES_LEDGER_FILE),
+      file: join13(dirname8(snapshot.file), NOTES_LEDGER_FILE),
       source,
       lines
     });
@@ -3493,11 +3735,11 @@ function collectNotesFiles(snapshots) {
   return out;
 }
 function migrateHarnessTree(root, opts = {}) {
-  const harnessDir = resolve10(root);
+  const harnessDir = resolve11(root);
   const workflowDir = resolveWorkflowDir(harnessDir, { harnessDir });
   const projectDir = resolveProjectDir(harnessDir, { harnessDir });
   const projectId = opts.projectId ?? _DEFAULT_PROJECT;
-  const statusPath = join11(harnessDir, MIGRATE_STATUS_FILE);
+  const statusPath = join13(harnessDir, MIGRATE_STATUS_FILE);
   const legacy = readJson(statusPath);
   if (legacy.version === 2) {
     const updatedAt = typeof legacy.updated_at === "string" && legacy.updated_at !== "" ? legacy.updated_at : "1970-01-01";
@@ -3593,7 +3835,7 @@ function migrateHarnessTree(root, opts = {}) {
       migrationNotes.push(`roadmap title sanitized for frontmatter (line breaks replaced with spaces): ${JSON.stringify(rawTitle)}`);
     }
     roadmap = {
-      file: join11("projects", projectId, PROJECT_ROADMAP_FILE),
+      file: join13("projects", projectId, PROJECT_ROADMAP_FILE),
       source: "status.json metadata.program_roadmap",
       content: buildRoadmap({ ...programRoadmap, title: sanitizedTitle }, projectId, migratedAt)
     };
@@ -3642,19 +3884,19 @@ async function applyMigratePlan(plan) {
   if (plan.dryRun) {
     return { applied: false, message: `dry-run: ${plan.steps.length} steps planned (source → destination), zero writes` };
   }
-  const statusPath = join11(plan.root, MIGRATE_STATUS_FILE);
+  const statusPath = join13(plan.root, MIGRATE_STATUS_FILE);
   const current = readJson(statusPath);
   if (current.version === 2) {
     return { applied: false, message: "no-op: status.json already at schema version 2 (migrated) — nothing to do" };
   }
-  const harnessRoot = resolve10(plan.root);
-  const workflowRoot = resolve10(plan.workflowDir);
-  const projectRoot = resolve10(plan.projectDir);
+  const harnessRoot = resolve11(plan.root);
+  const workflowRoot = resolve11(plan.workflowDir);
+  const projectRoot = resolve11(plan.projectDir);
   if (!isAbsolute7(plan.workflowDir) || !isAbsolute7(plan.projectDir)) {
     throw new Error(`refusing to apply migration: plan workflowDir/projectDir must be absolute (got ${JSON.stringify(plan.workflowDir)} / ${JSON.stringify(plan.projectDir)})`);
   }
-  const workflowTargetOf = (canonicalFile) => join11(workflowRoot, relative4("workflows", canonicalFile));
-  const projectTargetOf = (canonicalFile) => join11(projectRoot, relative4("projects", canonicalFile));
+  const workflowTargetOf = (canonicalFile) => join13(workflowRoot, relative5("workflows", canonicalFile));
+  const projectTargetOf = (canonicalFile) => join13(projectRoot, relative5("projects", canonicalFile));
   const allDestinations = [
     plan.archive.file,
     ...plan.snapshots.map((snapshot) => snapshot.file),
@@ -3663,20 +3905,20 @@ async function applyMigratePlan(plan) {
     ...plan.roadmap !== null ? [plan.roadmap.file] : []
   ];
   for (const destination of allDestinations) {
-    const resolvedDest = resolve10(join11(plan.root, destination));
+    const resolvedDest = resolve11(join13(plan.root, destination));
     const inside = (dir) => resolvedDest === dir || resolvedDest.startsWith(`${dir}${sep2}`);
     if (!inside(harnessRoot) && !inside(workflowRoot) && !inside(projectRoot)) {
       throw new Error(`refusing to apply migration: destination escapes the harness dir (${JSON.stringify(destination)}) — every write must stay under ${JSON.stringify(plan.root)}, the workflow dir (${JSON.stringify(plan.workflowDir)}) or the project dir (${JSON.stringify(plan.projectDir)})`);
     }
   }
-  mkdirSync7(join11(plan.root, dirname7(plan.archive.file)), { recursive: true });
-  copyFileSync(statusPath, join11(plan.root, plan.archive.file));
+  mkdirSync7(join13(plan.root, dirname8(plan.archive.file)), { recursive: true });
+  copyFileSync(statusPath, join13(plan.root, plan.archive.file));
   for (const snapshot of plan.snapshots) {
-    await writeWorkflowSnapshot(snapshot.data, dirname7(workflowTargetOf(snapshot.file)));
+    await writeWorkflowSnapshot(snapshot.data, dirname8(workflowTargetOf(snapshot.file)));
   }
   for (const notes of plan.notesFiles) {
     const filePath = workflowTargetOf(notes.file);
-    mkdirSync7(dirname7(filePath), { recursive: true });
+    mkdirSync7(dirname8(filePath), { recursive: true });
     const content = notes.lines.length > 0 ? `${notes.lines.join(`
 `)}
 ` : "";
@@ -3689,13 +3931,13 @@ async function applyMigratePlan(plan) {
     }
     if (Object.keys(plan.register.data.entries ?? {}).length > 0) {
       const filePath = projectTargetOf(plan.register.file);
-      mkdirSync7(dirname7(filePath), { recursive: true });
+      mkdirSync7(dirname8(filePath), { recursive: true });
       writeJson(filePath, plan.register.data);
     }
   }
   if (plan.roadmap !== null) {
     const filePath = projectTargetOf(plan.roadmap.file);
-    mkdirSync7(dirname7(filePath), { recursive: true });
+    mkdirSync7(dirname8(filePath), { recursive: true });
     writeFileSync5(filePath, plan.roadmap.content, "utf8");
   }
   const rootGate = validateStatusV2(plan.rootV2.data, { harnessDir: plan.root });
@@ -4119,8 +4361,8 @@ function completenessLevel(frontmatterText, checklist) {
 }
 // src/audit.ts
 import { execFileSync as execFileSync4 } from "node:child_process";
-import { existsSync as existsSync8, mkdirSync as mkdirSync8, readdirSync as readdirSync8, readFileSync as readFileSync9, rmdirSync as rmdirSync2, rmSync, writeFileSync as writeFileSync6 } from "node:fs";
-import { basename as basename5, join as join12, resolve as resolve11, sep as sep3 } from "node:path";
+import { existsSync as existsSync9, mkdirSync as mkdirSync8, readdirSync as readdirSync8, readFileSync as readFileSync9, rmdirSync as rmdirSync2, rmSync, writeFileSync as writeFileSync6 } from "node:fs";
+import { basename as basename6, join as join14, resolve as resolve12, sep as sep3 } from "node:path";
 function violation9(severity, code, message, fix) {
   return { ok: false, severity, code, message, fix };
 }
@@ -4421,7 +4663,7 @@ function scanSecrets(files) {
       unreadableFiles++;
       continue;
     }
-    const base = basename5(file);
+    const base = basename6(file);
     for (const entry of NEVER_COMMIT_FILENAMES) {
       if (entry.re.test(base))
         findings.push({ file, line: 1, type: entry.type });
@@ -4478,7 +4720,7 @@ function rootLockfiles(root) {
     return [];
   }
   const names = new Set(LOCKFILE_NAMES);
-  const present = entries.filter((entry) => entry.isFile() && names.has(entry.name)).map((entry) => join12(root, entry.name));
+  const present = entries.filter((entry) => entry.isFile() && names.has(entry.name)).map((entry) => join14(root, entry.name));
   if (present.length === 0)
     return [];
   try {
@@ -4487,7 +4729,7 @@ function rootLockfiles(root) {
       encoding: "utf8",
       stdio: ["ignore", "pipe", "ignore"]
     }).split("\x00").filter((f) => f !== ""));
-    return present.filter((p) => tracked.has(basename5(p)));
+    return present.filter((p) => tracked.has(basename6(p)));
   } catch {
     return present;
   }
@@ -4503,7 +4745,7 @@ function supplyChainChecks(repoRoot) {
     findings.push({ kind: "lockfile-duplicate", file: lockfiles.map((f) => f.replace(`${repoRoot}/`, "")).join(", ") });
     violations.push(violation9("medium", "audit.supply.lockfile-duplicate", `multiple lockfiles at ${repoRoot}: ${lockfiles.join(", ")}`, "keep exactly one lockfile per package manager"));
   }
-  const workflowsDir = join12(repoRoot, ".github", "workflows");
+  const workflowsDir = join14(repoRoot, ".github", "workflows");
   let wfEntries = [];
   try {
     wfEntries = readdirSync8(workflowsDir, { withFileTypes: true });
@@ -4513,7 +4755,7 @@ function supplyChainChecks(repoRoot) {
   for (const entry of wfEntries) {
     if (!entry.isFile() || !/\.(?:ya?ml)$/.test(entry.name))
       continue;
-    const wfPath = join12(workflowsDir, entry.name);
+    const wfPath = join14(workflowsDir, entry.name);
     const relPath = `.github/workflows/${entry.name}`;
     let text;
     try {
@@ -4670,8 +4912,8 @@ function scaffoldAuditPlan(outDir, findings, options = {}) {
   const date = options.date ?? new Date().toISOString().slice(0, 10);
   const plannedAt = options.plannedAt ?? { commit: options.repoShortSha ?? "unknown", date };
   mkdirSync8(outDir, { recursive: true });
-  const existingReadme = join12(outDir, "README.md");
-  const carried = existsSync8(existingReadme) ? extractSecurityDispositionSections(readFileSync9(existingReadme, "utf8")) : { needsVerification: [], hardeningChecked: [] };
+  const existingReadme = join14(outDir, "README.md");
+  const carried = existsSync9(existingReadme) ? extractSecurityDispositionSections(readFileSync9(existingReadme, "utf8")) : { needsVerification: [], hardeningChecked: [] };
   const existing = readdirSync8(outDir).filter((f) => /^\d{3}-.*\.md$/.test(f));
   let next = existing.reduce((max, f) => Math.max(max, Number(f.slice(0, 3))), 0) + 1;
   const redactedFindings = findings.map(redactFinding);
@@ -4688,13 +4930,13 @@ function scaffoldAuditPlan(outDir, findings, options = {}) {
     }
     usedSlugs.add(slug);
     const file = `${num}-${slug}.md`;
-    writeFileSync6(join12(outDir, file), renderPlanFile(finding, plannedAt));
+    writeFileSync6(join14(outDir, file), renderPlanFile(finding, plannedAt));
     written.push(file);
     next++;
   }
   const all = [...existing, ...written].sort();
   const rows = all.map((file) => {
-    const summary = readPlanFileSummary(join12(outDir, file));
+    const summary = readPlanFileSummary(join14(outDir, file));
     const fields = summary.fields;
     return {
       num: file.slice(0, 3),
@@ -4728,7 +4970,7 @@ function scaffoldAuditPlan(outDir, findings, options = {}) {
   });
   const needsVerificationLines = options.needsVerification !== undefined ? options.needsVerification.map((nv) => `- ${escapeCell(redactText(nv.lead))}: ${escapeCell(redactText(nv.how))}${nv.evidence ? ` (${escapeCell(redactText(nv.evidence))})` : ""}`) : carried.needsVerification;
   const hardeningCheckedLines = options.hardeningChecked !== undefined ? options.hardeningChecked.map((hc) => `- ${hc.kind}: ${escapeCell(redactText(hc.text))}`) : carried.hardeningChecked;
-  writeFileSync6(join12(outDir, "README.md"), renderIndex({
+  writeFileSync6(join14(outDir, "README.md"), renderIndex({
     date,
     repoName: options.repoName ?? "repo",
     repoShortSha: options.repoShortSha ?? "unknown",
@@ -4737,7 +4979,7 @@ function scaffoldAuditPlan(outDir, findings, options = {}) {
     needsVerification: needsVerificationLines,
     hardeningChecked: hardeningCheckedLines
   }));
-  return { outDir: resolve11(outDir), date, files: written, nextNumber: next };
+  return { outDir: resolve12(outDir), date, files: written, nextNumber: next };
 }
 async function promoteAuditPlans(outDir, selected, options) {
   if (selected.length === 0) {
@@ -4746,19 +4988,19 @@ async function promoteAuditPlans(outDir, selected, options) {
   if (typeof options.harnessDir !== "string" || options.harnessDir.trim() === "") {
     throw new Error("promoteAuditPlans: options.harnessDir is required (must contain status.json + workflows/)");
   }
-  const workflowId = options.workflowId ?? basename5(resolve11(outDir));
+  const workflowId = options.workflowId ?? basename6(resolve12(outDir));
   assertSafePathComponent(workflowId, "workflow id");
-  const harnessDir = resolve11(options.harnessDir);
-  const statusPath = join12(harnessDir, "status.json");
-  const workflowDir = join12(harnessDir, "workflows", workflowId);
-  const snapshotPath = join12(workflowDir, WORKFLOW_SNAPSHOT_FILE);
+  const harnessDir = resolve12(options.harnessDir);
+  const statusPath = join14(harnessDir, "status.json");
+  const workflowDir = join14(harnessDir, "workflows", workflowId);
+  const snapshotPath = join14(workflowDir, WORKFLOW_SNAPSHOT_FILE);
   const planFiles = resolveSelectedPlanFiles(outDir, selected);
   const indexRows = readExecutionOrderIndex(outDir);
   const plans = planFiles.map((planFile) => {
     const stem = planFile.replace(/\.md$/, "");
     const num = stem.slice(0, 3);
     const indexRow = indexRows.get(num);
-    const title = indexRow?.title ?? readPlanFileSummary(join12(outDir, planFile)).title;
+    const title = indexRow?.title ?? readPlanFileSummary(join14(outDir, planFile)).title;
     return {
       id: stem,
       title,
@@ -4787,7 +5029,7 @@ async function promoteAuditPlans(outDir, selected, options) {
     throw new Error(`refusing to register invalid workflow entry: ${entryGate.violations.map((v) => v.message).join("; ")}`);
   }
   await withStatusWriteLock(statusPath, async () => {
-    if (existsSync8(snapshotPath)) {
+    if (existsSync9(snapshotPath)) {
       throw new Error(`refusing to promote audit plans: workflow ${JSON.stringify(workflowId)} already exists ` + `(snapshot at ${snapshotPath}) — re-promote would drop its registered plan rows; ` + `remove that workflow before promoting again`);
     }
     mkdirSync8(workflowDir, { recursive: true });
@@ -4823,7 +5065,7 @@ function resolveSelectedPlanFiles(outDir, selected) {
   for (const id of selected) {
     const file = byNum.get(id) ?? byStem.get(id) ?? byStem.get(id.replace(/\.md$/, ""));
     if (file === undefined) {
-      throw new Error(`promoteAuditPlans: selected plan ${JSON.stringify(id)} does not match any NNN-*.md file in ${resolve11(outDir)}`);
+      throw new Error(`promoteAuditPlans: selected plan ${JSON.stringify(id)} does not match any NNN-*.md file in ${resolve12(outDir)}`);
     }
     if (!seen.has(file)) {
       seen.add(file);
@@ -4833,7 +5075,7 @@ function resolveSelectedPlanFiles(outDir, selected) {
   return resolved;
 }
 function readExecutionOrderIndex(outDir) {
-  const readmePath = join12(outDir, "README.md");
+  const readmePath = join14(outDir, "README.md");
   let text;
   try {
     text = readFileSync9(readmePath, "utf8");
@@ -4862,7 +5104,7 @@ function readExecutionOrderIndex(outDir) {
   return rows;
 }
 function planFileRel(outDir, planFile) {
-  const resolved = resolve11(outDir);
+  const resolved = resolve12(outDir);
   const parts = resolved.split(sep3);
   const plansIdx = parts.lastIndexOf("plans");
   if (plansIdx >= 0) {
@@ -4871,8 +5113,8 @@ function planFileRel(outDir, planFile) {
   return planFile;
 }
 // src/compound.ts
-import { existsSync as existsSync9, readdirSync as readdirSync9, readFileSync as readFileSync10 } from "node:fs";
-import { basename as basename6, isAbsolute as isAbsolute8, join as join13, relative as relative5, resolve as resolve12, sep as sep4 } from "node:path";
+import { existsSync as existsSync10, readdirSync as readdirSync9, readFileSync as readFileSync10 } from "node:fs";
+import { basename as basename7, isAbsolute as isAbsolute8, join as join15, relative as relative6, resolve as resolve13, sep as sep4 } from "node:path";
 function violation10(severity, code, message, fix) {
   return { ok: false, severity, code, message, fix };
 }
@@ -5167,7 +5409,7 @@ function referenceExists(repoRoot, docText) {
           break;
         if (entry.isDirectory()) {
           if (!WALK_SKIP_DIRS.has(entry.name))
-            stack.push(join13(dir, entry.name));
+            stack.push(join15(dir, entry.name));
         } else if (!entry.isSymbolicLink()) {
           const base = entry.name.replace(/\.(?:ts|tsx|js|jsx|mjs|cjs)$/, "");
           if (moduleNames.has(base))
@@ -5179,7 +5421,7 @@ function referenceExists(repoRoot, docText) {
   for (const { ref, isSymbol, module } of refs) {
     if (!isSymbol || module === undefined) {
       const candidate = ref.replace(LINE_SUFFIX_RE, "").replace(ANCHOR_RE, "");
-      if (existsSync9(resolve12(repoRoot, candidate))) {
+      if (existsSync10(resolve13(repoRoot, candidate))) {
         checked++;
       } else {
         violations.push(violation10("medium", "compound.reference.missing-file", `referenced path \`${ref}\` does not exist under ${repoRoot} (compound-refresh Phase 2: referenced code still exists?)`, "update the doc to reference an existing path, or delete the stale reference"));
@@ -5206,11 +5448,11 @@ function collectKnowledgeDocs(dir) {
     for (const entry of entries) {
       if (entry.isSymbolicLink())
         continue;
-      const full = join13(current, entry.name);
+      const full = join15(current, entry.name);
       if (entry.isDirectory()) {
         stack.push(full);
       } else if (entry.name.endsWith(".md") && entry.name !== "README.md" && entry.name !== "index.md") {
-        docs.push(relative5(dir, full).split(sep4).join("/"));
+        docs.push(relative6(dir, full).split(sep4).join("/"));
       }
     }
   }
@@ -5226,8 +5468,8 @@ function normalizeIndexRef(cell) {
 }
 function assertIndexRows(knowledgeDir) {
   const violations = [];
-  const readmePath = join13(knowledgeDir, "README.md");
-  if (!existsSync9(readmePath)) {
+  const readmePath = join15(knowledgeDir, "README.md");
+  if (!existsSync10(readmePath)) {
     violations.push(violation10("medium", "compound.index.missing-readme", `missing ${readmePath} — the knowledge index is required (mstar-compound Phase 6: every doc gets a README.md row)`, "create knowledge/README.md with a Document / Source Plan / Description / Status table"));
     return { ok: false, violations };
   }
@@ -5252,19 +5494,19 @@ function assertIndexRows(knowledgeDir) {
 }
 function compoundRefreshScope(harnessDir, projectRoot) {
   return [
-    join13(harnessDir, "knowledge"),
-    join13(harnessDir, "knowledge", "README.md"),
-    join13(projectRoot, "CONCEPTS.md"),
-    join13(harnessDir, "status.json")
+    join15(harnessDir, "knowledge"),
+    join15(harnessDir, "knowledge", "README.md"),
+    join15(projectRoot, "CONCEPTS.md"),
+    join15(harnessDir, "status.json")
   ];
 }
 function isFileLikeRoot(root) {
-  return /^[^.]*\.[A-Za-z0-9]{1,10}$/.test(basename6(root));
+  return /^[^.]*\.[A-Za-z0-9]{1,10}$/.test(basename7(root));
 }
 function scopeGuard(path, allowedRoots) {
-  const resolved = resolve12(path);
+  const resolved = resolve13(path);
   for (const root of allowedRoots) {
-    const r = resolve12(root);
+    const r = resolve13(root);
     if (isFileLikeRoot(r)) {
       if (resolved === r)
         return { ok: true, violations: [] };
@@ -5512,8 +5754,8 @@ function lintStrategySections(docText) {
   return { ok: violations.length === 0, violations };
 }
 // src/roles.ts
-import { existsSync as existsSync10 } from "node:fs";
-import { join as join14 } from "node:path";
+import { existsSync as existsSync11 } from "node:fs";
+import { join as join16 } from "node:path";
 function violation12(severity, code, message, fix) {
   return { ok: false, severity, code, message, fix };
 }
@@ -5569,8 +5811,8 @@ function validateRoleMapping(rolesDir, options = {}) {
   const violations = [];
   const referenceById = new Map(mapping.map((m) => [m.agentId, m.reference]));
   for (const { agentId, reference } of mapping) {
-    if (!existsSync10(join14(rolesDir, reference))) {
-      violations.push(violation12("medium", "roles.mapping.reference.missing", `role "${agentId}" maps to ${reference} which does not exist under ${rolesDir} (mstar-roles § Role Reference Mapping)`, `create ${join14(rolesDir, reference)} or fix the mapping row`));
+    if (!existsSync11(join16(rolesDir, reference))) {
+      violations.push(violation12("medium", "roles.mapping.reference.missing", `role "${agentId}" maps to ${reference} which does not exist under ${rolesDir} (mstar-roles § Role Reference Mapping)`, `create ${join16(rolesDir, reference)} or fix the mapping row`));
     }
   }
   for (const { family, memberIds } of families) {
@@ -5805,7 +6047,7 @@ function resolveAssetPath(skillName, relPath, host) {
 }
 // src/prreview.ts
 import { readdirSync as readdirSync10 } from "node:fs";
-import { isAbsolute as isAbsolute9, join as join15 } from "node:path";
+import { isAbsolute as isAbsolute9, join as join17 } from "node:path";
 var MERGE_CLASSES = ["must-fix", "should-fix", "nit"];
 var PR_VERDICTS = ["ship it", "needs fixes", "blocked"];
 var REVIEW_EMOJI = {
@@ -6061,7 +6303,7 @@ function prReviewReportPath(opts) {
   }
   const revision = maxRevision + 1;
   const name = revision === 1 ? `${finalStem}.md` : `${finalStem}-r${revision}.md`;
-  return join15(opts.reportsDir, name);
+  return join17(opts.reportsDir, name);
 }
 var PR_TIERS = ["quick", "default", "deep"];
 function violation14(severity, code, message, fix) {
@@ -6378,7 +6620,7 @@ function prReviewSeatPrompt(opts) {
   lines.push("");
   lines.push("## Read first");
   lines.push("");
-  const prReviewRef = join15(skillRoot, "references", "pr-review.md");
+  const prReviewRef = join17(skillRoot, "references", "pr-review.md");
   const sections = opts.stage === 1 ? tier === "quick" ? "Scoping, Evidence rules" : "Review pipeline, Worktree isolation, Scoping, Evidence rules" : "Merge class, Attack and vet, Evidence rules, Sizing & change shape";
   lines.push(`1. \`${prReviewRef}\` — read at least these sections: ${sections}.`);
   lines.push(`2. The review worktree: \`${worktreePath}\` — your ONLY working directory this session; read-only (no edits, no fixes, no stash, no commits, no posts).`);
@@ -6386,9 +6628,9 @@ function prReviewSeatPrompt(opts) {
     lines.push(`- Read the pinned diff snapshot FIRST: \`${opts.diffFile}\` — it is the review's diff basis (already computed at setup); read it before opening files.`);
   }
   if (opts.stage === 2) {
-    lines.push(`3. \`${join15(skillRoot, "references", "finding-format.md")}\` — the template every finding follows.`);
+    lines.push(`3. \`${join17(skillRoot, "references", "finding-format.md")}\` — the template every finding follows.`);
     if (opts.securitySeat === true) {
-      lines.push(`4. \`${join15(skillRoot, "references", "security-review.md")}\` — the security lens.`);
+      lines.push(`4. \`${join17(skillRoot, "references", "security-review.md")}\` — the security lens.`);
     }
   }
   const budget = PR_REVIEW_TIER_BUDGETS[tier];
@@ -6586,6 +6828,7 @@ export {
   KNOWLEDGE_REQUIRED_FIELDS,
   KNOWLEDGE_RESOLUTION_TYPES,
   KNOWLEDGE_SEVERITIES,
+  MAX_STATUS_CONTENT_LENGTH,
   MERGE_CLASSES,
   MIGRATE_STATUS_FILE,
   MSTARC_FILE,
@@ -6644,14 +6887,18 @@ export {
   detectHost,
   emitGitignoreSnippet,
   evaluatePhaseGate,
+  eventTargetPaths,
   executionModeToN,
   findEphemeralCitations,
   findMstarc,
   findSimplifyMarkers,
   findTemporaryMarkers,
   findingsCleanupGate,
+  formatStatusWriteBlockReason,
   getArtifactStore,
+  harnessDocKindOfTarget,
   implementerSessionStickyRules,
+  isDistinctCheckout,
   isReadOnlyAssignmentRole,
   l1PreDispatchCheck,
   l2PreDispatchCheck,
@@ -6680,6 +6927,7 @@ export {
   prReviewSeatPrompt,
   prReviewSizing,
   preflightChangeset,
+  probeCheckoutRoot,
   promoteAuditPlans,
   pushCadenceProbe,
   readHarnessVersion,
@@ -6741,9 +6989,11 @@ export {
   validateSchemaYaml,
   validateStatus,
   validateStatusV2,
+  validateStatusWriteDoc,
   validateWorkflowEntry,
   validateWorkflowSnapshot,
   verifyPlanExecutionLease,
+  violationLine,
   withStatusWriteLock,
   writeJson,
   writeWorkflowSnapshot

package/dist/gates.d.ts

@@ -0,0 +1,69 @@
+import { type ValidationResult } from "./core.js";
+/** Target paths from a write/edit event: `input.path` (string) plus `input.paths` (array). */
+export declare function eventTargetPaths(input: unknown): string[];
+/** Gated harness coordination documents in v3 (compass ruling 7 — hard
+ * cutover): the root `status.json` (v2), workflow snapshots
+ * (`workflows/<id>/snapshot.json`) and project registers
+ * (`projects/<id>/residuals.json`). Each kind maps to its engine
+ * validator; everything else is not a gated coordination write. */
+export type HarnessDocKind = "status" | "snapshot" | "register";
+/**
+ * Classify `targetPath` as a canonical `{HARNESS_DIR}` coordination
+ * document: basename is `status.json` at the harness root, `snapshot.json`
+ * under `{WORKFLOW_DIR}/<id>/`, or `residuals.json` under
+ * `{PROJECT_DIR}/<id>/` (harness-relative, one path component each), AND
+ * the harness root resolves — marker probe first (custom-layout-aware
+ * Phase-5 F1), `resolveHarnessDir` as the declared-root fallback. The
+ * snapshot/register rel is computed against the RESOLVED layout dirs
+ * (`.mstarc` `workflow_dir`/`project_dir` honored, defaults
+ * `workflows`/`projects`), so a custom layout classifies at the same
+ * location the runtime writes. Everything else is not a gated write.
+ * Returns the harness dir + doc kind when gated.
+ */
+export declare function harnessDocKindOfTarget(targetPath: string): {
+    harnessDir: string;
+    kind: HarnessDocKind;
+} | null;
+export declare function violationLine(violation: ValidationResult): string;
+/**
+ * Size guard: content strings beyond ~2MB are skipped without
+ * parsing — a pathologically large write must not approach a host's
+ * handler timeout (which fails CLOSED even in soft mode). The oversized
+ * write passes silently; documented in the host gate contract.
+ */
+export declare const MAX_STATUS_CONTENT_LENGTH: number;
+/**
+ * Options for {@link validateStatusWriteDoc}.
+ */
+export interface ValidateStatusWriteDocOptions {
+    /**
+     * Behavior when the content (string form) or the on-disk gated document
+     * (edit form) exceeds `MAX_STATUS_CONTENT_LENGTH`. `"pass"` (default)
+     * keeps the documented silent-pass degradation; `"violate"` reports a
+     * `status.oversized` violation instead — for hosts whose block dialect
+     * makes the oversized write an enforceable refusal rather than a
+     * permission (the size check stays O(1), before any parse).
+     */
+    oversized?: "pass" | "violate";
+}
+/**
+ * Validate the document being written to a gated harness coordination
+ * document. `content` as a string is the new document: JSON.parse it
+ * and run the matching engine validator on the parsed doc — a parse failure
+ * is a violation (`status.invalid-json`, the same code/message shape the
+ * engine emits for an unparseable file). Parsed `null` / non-object / array
+ * content is a `status.invalid-json` violation too (the JSON
+ * literal `null` would otherwise slip through `validateStatus`'s
+ * destructuring into the outer catch's silent pass). Without a content
+ * string (edit-style events) the on-disk file is validated — unless it does
+ * not exist yet (fresh scaffold/init write): nothing to validate, silent
+ * pass. Never throws (the validators catch their own read errors).
+ */
+export declare function validateStatusWriteDoc(content: unknown, filePath: string, kind: HarnessDocKind, options?: ValidateStatusWriteDocOptions): ValidationResult[];
+/**
+ * Format the gate block reason: one `violationLine` per violation, each
+ * suffixed with the host's skill pointer (omp/ZCode parity: both hosts
+ * pass `skill: mstar-artifacts/references/status-and-residuals.md`),
+ * joined with newlines.
+ */
+export declare function formatStatusWriteBlockReason(violations: ValidationResult[], skillPointer: string): string;

package/dist/gates.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -20,7 +20,10 @@
  * constants (mstar-audit pr-review.md § Tally and derived score), `host`
  * detects the active
  * host from tool shapes, resolves skill roots and defines the type-only
- * `HostAdapter` contract, and `skill-authoring` lints frontmatter +
+ * `HostAdapter` contract, `gates` is the host-neutral coordination-write
+ * gate core (target classification + content/edit validation + reason
+ * formatting, shared by the omp and ZCode host gates), and `skill-authoring`
+ * lints frontmatter +
  * 5-question bodies and resolves skill-relative asset paths.
  */
 export type { GateResult, Severity, ValidationResult } from "./core.js";
@@ -38,13 +41,15 @@ export { WORKFLOW_LIFECYCLE_STATUSES, WORKFLOW_LIFECYCLE_TYPES, WORKFLOW_SNAPSHO
 export type { AssignmentBranchForms, AssignmentFields, ComposeDispatchGateOptions, ComposeDispatchGateResult, DefaultBranchOptions, EnforcementFlag, EnforcementSource, ExecutionModeToNOptions, ExecutionModeToNResult, ValidateAssignmentFieldsOptions, } from "./dispatch.js";
 export { antiRecursionPrecheck, assertDefaultBranchProtected, assertTriIdentity, assignmentHeaderRegion, composeDispatchGate, executionModeToN, isReadOnlyAssignmentRole, parseAssignmentBranchForms, parseAssignmentFields, parseBranchPolicyDirectOnBranch, parseEnforcementFlag, validateAssignmentFields, } from "./dispatch.js";
 export type { BranchProbeOptions, L1PreDispatchInput, L2PreDispatchInput, QcAlignmentAssignment, QcSnapshotAssignment, WorktreeTrack, } from "./worktree.js";
-export { assertBranchAlignment, assertControlVsFeaturePath, assertQcAlignment, l1PreDispatchCheck, l2PreDispatchCheck, singleReviewSnapshot, } from "./worktree.js";
+export { assertBranchAlignment, assertControlVsFeaturePath, assertQcAlignment, isDistinctCheckout, l1PreDispatchCheck, l2PreDispatchCheck, probeCheckoutRoot, singleReviewSnapshot, } from "./worktree.js";
 export type { ImplementerSessionLedger, ReviewPackageOptions, SddAction, SddActionKind, SddExecutionContext, SddWorkspaceOptions, StickyRulesInput, StickyRulesResult, TaskBriefOptions, } from "./sdd.js";
 export { GIT_CAPTURE_MAX_BYTES, SddScriptError, assertBaseSha, checkSddAction, implementerSessionStickyRules, readProgressLedger, resolveSddExecutionContext, reviewPackage, runInSddContext, sddWorkspace, taskBrief, taskReportExists, } from "./sdd.js";
 export type { CompassDoc, PhaseGateOptions, PhaseGateResult, PhaseTransition, } from "./iteration.js";
 export { assertIndexRowObligations, evaluatePhaseGate, parseCompassFrontmatter, parseCompassFrontmatterText, pushCadenceProbe, validateCompassFrontmatter, } from "./iteration.js";
 export type { AppendProjectRegisterEntriesOpts, CloseProjectRegisterEntryOpts, FindingsCleanupMode, ProjectRegisterDoc, ProjectRegisterEntry, RoadmapFrontmatter, RoadmapStatus, RoadmapValidation, TechDebtCheck, TechDebtRollup, TechDebtSummary, } from "./project.js";
 export { PROJECT_REFERENCES_DIR, PROJECT_REGISTER_FILE, PROJECT_ROADMAP_FILE, ROADMAP_STATUSES, _DEFAULT_PROJECT, appendProjectRegisterEntries, closeProjectRegisterEntry, findingsCleanupGate, listProjectReferenceFiles, techDebtRollup, validateProjectRegister, validateRoadmap, } from "./project.js";
+export type { HarnessDocKind, ValidateStatusWriteDocOptions } from "./gates.js";
+export { MAX_STATUS_CONTENT_LENGTH, eventTargetPaths, formatStatusWriteBlockReason, harnessDocKindOfTarget, validateStatusWriteDoc, violationLine, } from "./gates.js";
 export type { MigrateNotesFile, MigrateOptions, MigratePlan, MigrateRegister, MigrateResult, MigrateRoadmap, MigrateRootV2, MigrateSnapshot, MigrateStep, } from "./migrate.js";
 export { ARCHIVED_STATUS_V1_FILE, MIGRATE_STATUS_FILE, NOTES_LEDGER_FILE, applyMigratePlan, migrateHarnessTree, } from "./migrate.js";
 export type { CompletenessItem, CompletenessLevel, CompletenessPlaceholder, CompletenessResult, DesignFrontmatter, } from "./design-md.js";

package/dist/worktree.d.ts

@@ -55,6 +55,27 @@ export type QcSnapshotAssignment = QcAlignmentAssignment & {
     /** Precomputed review HEAD (full SHA preferred) for that assignment. */
     head?: string;
 };
+/**
+ * True when `candidatePath` is a Git checkout DISTINCT from `controlPath` —
+ * the canonical per-worktree git dirs differ. A linked worktree from
+ * `git worktree add` (nested inside the control checkout or a sibling) has
+ * its own git dir and is distinct; the same checkout, a plain subdirectory
+ * of it, or a symlink alias of it resolves to the same git dir and is NOT
+ * distinct. Everything unprovable — a non-repo path or a probe failure —
+ * is NOT distinct: fail closed, never guess an identity.
+ */
+export declare function isDistinctCheckout(controlPath: string, candidatePath: string, opts?: BranchProbeOptions): boolean;
+/**
+ * Probe the repository top-level (worktree root) of a checkout via
+ * `git -C <path> rev-parse --show-toplevel` — bounded exactly like
+ * `probeBranch` / `probeCheckout`, fail-closed (null on any failure). The
+ * canonical top-level is the checkout root regardless of where inside it
+ * the probed path sits — a `.mstarc`-declared nested harness dir like
+ * `<control>/state/.mstar` included — so callers never infer the checkout
+ * root from `dirname(harness)` (a layout assumption that only holds when
+ * the harness sits directly under the checkout).
+ */
+export declare function probeCheckoutRoot(path: string, opts?: BranchProbeOptions): string | null;
 /**
  * L1 cross-plan pre-dispatch checklist (mstar-branch-worktree L1 table +
  * Harness path SSOT hard rules): control path recorded, feature worktree
@@ -74,11 +95,15 @@ export declare function l1PreDispatchCheck(input: L1PreDispatchInput, opts?: Bra
 export declare function l2PreDispatchCheck(input: L2PreDispatchInput, opts?: BranchProbeOptions): GateResult;
 /**
  * L1 hard rule (Harness path SSOT): `execution_lease.worktree_path` MUST
- * differ from `metadata.control_worktree_path`. String equality on the two
- * paths — canonical absolute paths are the caller's contract (the lease
- * validator already requires `worktree_path` to be absolute).
+ * be a Git checkout DISTINCT from `metadata.control_worktree_path` — the
+ * same checkout, a plain subdirectory, or a symlink alias of the control
+ * checkout is refused (checkout identity via the canonical per-worktree
+ * git dir; probe failure fails closed). Both-empty stays a match (nothing
+ * recorded, per the lease validator contract); one empty has nothing to
+ * compare and passes (the lease validator's absolute-path requirement owns
+ * empty lease paths).
  */
-export declare function assertControlVsFeaturePath(controlWorktreePath: string, featureWorktreePath: string): GateResult;
+export declare function assertControlVsFeaturePath(controlWorktreePath: string, featureWorktreePath: string, opts?: BranchProbeOptions): GateResult;
 /**
  * Assert the branch checked out at `worktreePath` matches `expectedBranch`
  * (the Assignment Working branch). Probe = `git -C <path> branch

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mstar-harness/engine",
-  "version": "3.7.0",
+  "version": "3.7.1",
   "description": "Morning Star Harness Workflow Engine — deterministic workflow enforcement library (path, status, lease, dispatch, sdd, iteration, lint gates).",
   "license": "MIT",
   "repository": {