@mstar-harness/engine 3.2.6 → 3.3.0

package/dist/engine.js

@@ -170,327 +170,365 @@ function isAtOrBelow(dir, root) {
   return rel === "" || !rel.startsWith("..") && !isAbsolute(rel);
 }
 // src/path.ts
-import { existsSync as existsSync2, mkdirSync as mkdirSync2, readdirSync, readFileSync as readFileSync3, realpathSync, statSync as statSync2 } from "node:fs";
+import { existsSync as existsSync5, mkdirSync as mkdirSync4, readdirSync as readdirSync4, readFileSync as readFileSync6, realpathSync as realpathSync2, statSync as statSync3, writeFileSync as writeFileSync3 } from "node:fs";
 import { execFileSync } from "node:child_process";
-import { basename as basename2, dirname as dirname3, isAbsolute as isAbsolute2, join as join3, relative as relative2, resolve as resolve3 } from "node:path";
-function resolveHarnessDir(startDir = process.cwd(), opts = {}) {
-  const start = resolve3(startDir);
-  const explicit = opts.harnessDir ?? process.env.MSTAR_HARNESS_DIR;
-  if (explicit)
-    return resolve3(start, explicit);
-  const boundary = resolve3(start, opts.workspaceRoot ?? defaultWorkspaceRoot(start));
-  const rc = loadMstarc(start, boundary);
-  if (rc !== null && rc.config.harnessDir)
-    return resolve3(rc.dir, rc.config.harnessDir);
-  let dir = start;
-  for (;; ) {
-    if (!isAtOrBelow2(dir, boundary))
-      return null;
-    for (const candidate of [join3(dir, ".mstar"), join3(dir, ".agents"), join3(dir, ".plans"), join3(dir, "plans")]) {
-      if (isDirectory(candidate))
-        return candidate;
+import { basename as basename2, dirname as dirname5, isAbsolute as isAbsolute3, join as join8, relative as relative2, resolve as resolve5 } from "node:path";
+
+// src/project.ts
+import { existsSync as existsSync4, readFileSync as readFileSync5, readdirSync as readdirSync3 } from "node:fs";
+import { join as join7 } from "node:path";
+
+// src/iteration.ts
+import { existsSync as existsSync2, readdirSync, readFileSync as readFileSync3 } from "node:fs";
+import { join as join3 } from "node:path";
+var COMPASS_STATUSES = ["active", "locked", "completed"];
+var DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+var PLAN_STATUS_DONE = "Done";
+var COMPASS_FILE = "delivery-compass.md";
+var INDEX_README = "README.md";
+var INDEX_HEADER = "| Iteration | Path | Description | Status |";
+function typeName(value) {
+  if (value === null)
+    return "null";
+  if (Array.isArray(value))
+    return "array";
+  return typeof value;
+}
+function validateCompassShape(doc) {
+  const issues = [];
+  const expectString = (key, opts = {}) => {
+    const value = doc[key];
+    if (typeof value !== "string") {
+      issues.push({ path: [key], message: `expected string, received ${typeName(value)}` });
+      return;
     }
-    if (dir === boundary)
-      return null;
-    const parent = dirname3(dir);
-    if (parent === dir)
-      return null;
-    dir = parent;
+    if (opts.min !== undefined && value.length < opts.min) {
+      issues.push({ path: [key], message: `string must contain at least ${opts.min} character(s)` });
+      return;
+    }
+    if (opts.regex !== undefined && !opts.regex.test(value)) {
+      issues.push({ path: [key], message: `string must match ${opts.regex}` });
+    }
+  };
+  expectString("iteration_id", { min: 1 });
+  expectString("start_date", { regex: DATE_RE });
+  const status = doc.status;
+  if (typeof status !== "string" || !COMPASS_STATUSES.includes(status)) {
+    issues.push({
+      path: ["status"],
+      message: `expected one of ${COMPASS_STATUSES.map((s) => `'${s}'`).join(" | ")}, received ${typeName(status)}`
+    });
   }
-}
-function defaultWorkspaceRoot(startDir) {
-  try {
-    const cdup = execFileSync("git", ["rev-parse", "--show-cdup"], {
-      cwd: startDir,
-      encoding: "utf8",
-      stdio: ["ignore", "pipe", "ignore"]
-    }).trim();
-    if (!cdup)
-      return startDir;
-    let boundary = startDir;
-    for (const segment of cdup.split(/[\\/]/)) {
-      if (segment && segment !== ".")
-        boundary = dirname3(boundary);
+  expectString("iteration_base_branch", { min: 1 });
+  expectString("target_branch", { min: 1 });
+  const plans = doc.plans;
+  if (plans !== undefined) {
+    if (!Array.isArray(plans)) {
+      issues.push({ path: ["plans"], message: `expected array, received ${typeName(plans)}` });
+    } else {
+      plans.forEach((entry, index) => {
+        if (typeof entry !== "string") {
+          issues.push({ path: ["plans", index], message: `expected string, received ${typeName(entry)}` });
+        } else if (entry.length < 1) {
+          issues.push({ path: ["plans", index], message: "string must contain at least 1 character(s)" });
+        }
+      });
     }
-    return resolve3(boundary);
-  } catch {}
-  return startDir;
+  }
+  const end_date = doc.end_date;
+  if (end_date !== undefined) {
+    if (typeof end_date !== "string") {
+      issues.push({ path: ["end_date"], message: `expected string, received ${typeName(end_date)}` });
+    } else if (!DATE_RE.test(end_date)) {
+      issues.push({ path: ["end_date"], message: `string must match ${DATE_RE}` });
+    }
+  }
+  if (issues.length > 0)
+    return { ok: false, issues };
+  return {
+    ok: true,
+    data: {
+      iteration_id: doc.iteration_id,
+      start_date: doc.start_date,
+      status,
+      iteration_base_branch: doc.iteration_base_branch,
+      target_branch: doc.target_branch,
+      ...plans !== undefined ? { plans } : {},
+      ...end_date !== undefined ? { end_date } : {}
+    }
+  };
 }
-function isAtOrBelow2(dir, root) {
-  const rel = relative2(root, dir);
-  return rel === "" || !rel.startsWith("..") && !isAbsolute2(rel);
+function violation(severity, code, message, fix) {
+  return { ok: false, severity, code, message, fix };
 }
-function mstarcDirOverride(harnessDir, key) {
-  const dir = resolve3(harnessDir);
-  const rc = loadMstarc(dir, dirname3(dir));
-  const declared = rc?.config[key];
-  return declared ? resolve3(rc.dir, declared) : null;
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function resolveSpecsDir(harnessDir, opts = {}) {
-  const declared = mstarcDirOverride(harnessDir, "specsDir");
-  if (declared !== null) {
-    if (opts.create !== false)
-      mkdirSync2(declared, { recursive: true });
-    return declared;
+function validateCompassFrontmatter(doc) {
+  if (!isPlainObject(doc)) {
+    return {
+      ok: false,
+      violations: [
+        violation("medium", "COMPASS_INVALID_FIELD", "Compass frontmatter must be a YAML object with iteration_id / start_date / status / iteration_base_branch / target_branch (template: mstar-iteration §1.3)", "Fix the frontmatter of {ITERATION_DIR}/<iteration-id>/delivery-compass.md")
+      ]
+    };
   }
-  const harness = resolve3(harnessDir);
-  const repoRoot = dirname3(harness);
-  const candidates = [
-    join3(harness, "specs"),
-    join3(repoRoot, "docs", "specs"),
-    join3(repoRoot, "specs"),
-    join3(harness, "designs"),
-    join3(repoRoot, "designs")
-  ];
-  for (const candidate of candidates) {
-    if (isDirectory(candidate) && hasFiles(candidate))
-      return candidate;
+  const parsed = validateCompassShape(doc);
+  if (!parsed.ok) {
+    return {
+      ok: false,
+      violations: parsed.issues.map((issue) => {
+        const field = issue.path.join(".") || "(root)";
+        return violation("medium", "COMPASS_INVALID_FIELD", `Compass frontmatter field '${field}' is invalid: ${issue.message}`, `Fix '${field}' in {ITERATION_DIR}/<iteration-id>/delivery-compass.md frontmatter (template: mstar-iteration §1.3)`);
+      })
+    };
   }
-  const fallback = join3(harness, "specs");
-  if (opts.create !== false)
-    mkdirSync2(fallback, { recursive: true });
-  return fallback;
+  const violations = [];
+  const { status, end_date } = parsed.data;
+  if (status === "completed" && end_date === undefined) {
+    violations.push(violation("high", "COMPASS_END_DATE_REQUIRED", "Compass frontmatter status is 'completed' but end_date is missing — end_date is required at iteration-close (mstar-iteration §3.4, template Fields guide)", "Add `end_date: YYYY-MM-DD` to the frontmatter"));
+  }
+  if (status !== "completed" && end_date !== undefined) {
+    violations.push(violation("medium", "COMPASS_END_DATE_NOT_ALLOWED", `Compass frontmatter sets end_date while status is '${status}' — end_date is only written at iteration-close (mstar-iteration §3.4)`, "Remove end_date until iteration-close"));
+  }
+  return { ok: violations.length === 0, violations };
 }
-function resolvePlanDir(harnessDir) {
-  const declared = mstarcDirOverride(harnessDir, "planDir");
-  if (declared !== null)
-    return declared;
-  const dir = resolve3(harnessDir);
-  const name = basename2(dir);
-  if (name === ".plans" || name === "plans")
-    return dir;
-  return join3(dir, "plans");
+function registeredPlanIds(compassDoc) {
+  if (!Array.isArray(compassDoc.plans))
+    return [];
+  return compassDoc.plans.filter((plan) => typeof plan === "string" && plan.length > 0);
 }
-function assertSafePathComponent(value, what) {
-  if (value === "" || value === "." || value === ".." || !/^[A-Za-z0-9._-]+$/.test(value)) {
-    throw new Error(`${what} must be a single safe path component ([A-Za-z0-9._-]+; not "", ".", "..", or containing "/" or "\\") — got ${JSON.stringify(value)}`);
+function findPlanRow(snapshotDoc, planId) {
+  if (!Array.isArray(snapshotDoc.plans))
+    return null;
+  for (const row of snapshotDoc.plans) {
+    if (!isPlainObject(row))
+      continue;
+    const rowId = typeof row.id === "string" ? row.id : typeof row.plan_id === "string" ? row.plan_id : null;
+    if (rowId === planId)
+      return row;
   }
+  return null;
 }
-function resolveSddDir(harnessDir, planId) {
-  assertSafePathComponent(planId, "planId");
-  const base = resolve3(harnessDir);
-  const declared = mstarcDirOverride(base, "sddDir");
-  const sddBase = declared !== null ? declared : join3(base, "sdd");
-  return join3(sddBase, planId);
-}
-function resolveIterationDir(harnessDir) {
-  const declared = mstarcDirOverride(harnessDir, "iterationDir");
-  if (declared !== null)
-    return declared;
-  return join3(resolve3(harnessDir), "iterations");
+function entryPlansAllDone(snapshotDoc, registered) {
+  const violations = [];
+  if (registered.length === 0) {
+    violations.push(violation("medium", "COMPASS_NO_PLANS", "Compass frontmatter registers no plans — the all-plans-Done transition cannot be verified (mstar-iteration §1.3 / Phase transition gates)", "List the iteration's plan ids in the compass frontmatter `plans`"));
+    return violations;
+  }
+  for (const planId of registered) {
+    const row = findPlanRow(snapshotDoc, planId);
+    if (row === null) {
+      violations.push(violation("high", "PLAN_NOT_IN_STATUS", `Plan '${planId}' is registered in the compass frontmatter but has no row in the workflow snapshot plans[] (mstar-iteration §3.1 entry item 1)`, "Add the plan row to {HARNESS_DIR}/workflows/<id>/snapshot.json"));
+      continue;
+    }
+    if (row.status !== PLAN_STATUS_DONE) {
+      violations.push(violation("high", "PLAN_NOT_DONE", `Plan '${planId}' status is ${JSON.stringify(row.status)} in the workflow snapshot — all compass-registered plans must be 'Done' before iteration-close (mstar-iteration §3.1 entry item 1)`));
+    }
+  }
+  return violations;
 }
-function resolveKnowledgeDir(harnessDir) {
-  const declared = mstarcDirOverride(harnessDir, "knowledgeDir");
-  if (declared !== null)
-    return declared;
-  return join3(resolve3(harnessDir), "knowledge");
+function entryFrontmatterComplete(compassDoc) {
+  return validateCompassFrontmatter(compassDoc).violations;
 }
-function resolveHarnessSubdir(startDir, opts, key, fallback) {
-  const harness = resolveHarnessDir(startDir, opts);
-  if (harness === null) {
-    throw new Error(`harness dir not found from ${resolve3(startDir)} — cannot resolve the ${fallback} dir (run \`mstar init\`, pass opts.harnessDir, or set MSTAR_HARNESS_DIR)`);
+function exitFrontmatterClosed(compassDoc) {
+  const violations = [];
+  if (compassDoc.status !== "completed") {
+    violations.push(violation("high", "EXIT_STATUS_NOT_COMPLETED", `Compass frontmatter status must be 'completed' at close exit — current: ${JSON.stringify(compassDoc.status)} (mstar-iteration §3.4 / §3.5 exit item 4)`));
   }
-  const declared = mstarcDirOverride(harness, key);
-  return declared !== null ? declared : join3(resolve3(harness), fallback);
-}
-function resolveWorkflowDir(startDir = process.cwd(), opts = {}) {
-  return resolveHarnessSubdir(startDir, opts, "workflowDir", "workflows");
+  const endDate = compassDoc.end_date;
+  if (typeof endDate !== "string" || !DATE_RE.test(endDate)) {
+    violations.push(violation("high", "EXIT_END_DATE_REQUIRED", "Compass frontmatter end_date (YYYY-MM-DD) is required when closing (mstar-iteration §3.4 / §3.5 exit item 4)"));
+  }
+  return violations;
 }
-function resolveProjectDir(startDir = process.cwd(), opts = {}) {
-  return resolveHarnessSubdir(startDir, opts, "projectDir", "projects");
+function exitBranchCheck(opts) {
+  const violations = [];
+  const { currentBranch, specIntegrationBranch } = opts;
+  if (currentBranch === undefined || specIntegrationBranch === undefined) {
+    violations.push(violation("medium", "EXIT_BRANCH_UNVERIFIABLE", "Cannot verify the current branch is spec_integration_branch — missing currentBranch / specIntegrationBranch probe inputs (mstar-iteration §3.5 exit item 5)"));
+  } else if (currentBranch !== specIntegrationBranch) {
+    violations.push(violation("high", "EXIT_BRANCH_MISMATCH", `Current branch '${currentBranch}' is not the spec_integration_branch '${specIntegrationBranch}' (mstar-iteration §3.5 exit item 5)`));
+  }
+  return violations;
 }
-var EMPTY_STATUS_TEMPLATE = {
-  version: 2,
-  updated_at: "1970-01-01",
-  workflows: []
-};
-var SCAFFOLD_DIRS = ["plans", "iterations", "knowledge", "specs", "sdd"];
-function scaffoldHarness(root) {
-  const harnessDir = join3(resolve3(root), ".mstar");
-  for (const dir of SCAFFOLD_DIRS)
-    mkdirSync2(join3(harnessDir, dir), { recursive: true });
-  const statusPath = join3(harnessDir, "status.json");
-  if (Object.keys(readJson(statusPath)).length === 0)
-    writeJson(statusPath, EMPTY_STATUS_TEMPLATE);
-  return harnessDir;
+function exitPrBaseCheck(compassDoc, opts) {
+  const violations = [];
+  const target = compassDoc.target_branch;
+  const { prBaseBranch } = opts;
+  if (prBaseBranch === undefined) {
+    violations.push(violation("medium", "EXIT_PR_BASE_UNVERIFIABLE", "Cannot verify the PR base — missing prBaseBranch probe input (mstar-iteration §3.5 exit item 6)"));
+  } else if (typeof target !== "string" || prBaseBranch !== target) {
+    violations.push(violation("high", "EXIT_PR_BASE_MISMATCH", `PR base '${prBaseBranch}' must equal the compass target_branch '${String(target)}' — not an undocumented branch (mstar-iteration §3.5 exit item 6)`));
+  }
+  return violations;
 }
-var GITIGNORE_SNIPPET = `# Morning Star harness (.mstar/)
-# Principle: process stays local; results are shared with the team.
-# Default-ignore everything under .mstar/, then re-include the tracked results.
-.mstar/**
-!.mstar/AGENTS.md
-!.mstar/knowledge/
-!.mstar/knowledge/**
-!.mstar/specs/
-!.mstar/specs/**
-# .mstarc — repo-local harness config (may declare [config] harness_dir=<name>)
-.mstarc
-`;
-var GITIGNORE_SNIPPET_AGENTS = `# Morning Star harness (.agents/) — legacy
-# Default-ignore everything under .agents/, then re-include the tracked results.
-.agents/**
-!.agents/AGENTS.md
-!.agents/knowledge/
-!.agents/knowledge/**
-!.agents/specs/
-!.agents/specs/**
-`;
-var GITIGNORE_PROCESS_ENTRIES = GITIGNORE_SNIPPET.split(`
-`).filter((line) => line.startsWith(".mstar/") || line.startsWith("!.mstar/")).map((line) => line.trim());
-var GITIGNORE_PROCESS_ENTRIES_AGENTS = GITIGNORE_SNIPPET_AGENTS.split(`
-`).filter((line) => line.startsWith(".agents/") || line.startsWith("!.agents/")).map((line) => line.trim());
-function emitGitignoreSnippet(kind) {
-  if (kind === "agents")
-    return GITIGNORE_SNIPPET_AGENTS;
-  if (kind === "mstar")
-    return GITIGNORE_SNIPPET;
-  return `${GITIGNORE_SNIPPET}${GITIGNORE_SNIPPET_AGENTS}`;
-}
-function validateGitignore(root) {
-  const gitignorePath = join3(resolve3(root), ".gitignore");
-  const kind = detectHarnessKind(resolveHarnessDir(root));
-  let content;
-  try {
-    content = readFileSync3(gitignorePath, "utf8");
-  } catch {
-    return {
-      ok: false,
-      severity: "medium",
-      code: "gitignore.missing",
-      message: `no .gitignore found at ${gitignorePath}`,
-      fix: `append the canonical snippet (emitGitignoreSnippet(${kind ? `"${kind}"` : ""})) to ${gitignorePath}`
-    };
-  }
-  const lines = new Set(content.split(/\r?\n/).map((line) => line.trim()).filter((line) => line.length > 0));
-  const mstarMissing = GITIGNORE_PROCESS_ENTRIES.filter((entry) => !lines.has(entry));
-  const agentsMissing = GITIGNORE_PROCESS_ENTRIES_AGENTS.filter((entry) => !lines.has(entry));
-  let missing;
-  let label;
-  if (kind === "agents") {
-    missing = agentsMissing;
-    label = ".agents/ set";
-  } else if (kind === "mstar") {
-    missing = mstarMissing;
-    label = ".mstar/ set";
-  } else {
-    label = "either .mstar/ or .agents/ set";
-    missing = mstarMissing.length === 0 || agentsMissing.length === 0 ? [] : mstarMissing.length <= agentsMissing.length ? mstarMissing : agentsMissing;
-  }
-  if (missing.length > 0) {
-    return {
-      ok: false,
-      severity: "medium",
-      code: "gitignore.missing-entries",
-      message: `.gitignore at ${gitignorePath} is missing canonical harness ignore entries (${label}): ${missing.join(", ")}`,
-      fix: `append the canonical snippet (emitGitignoreSnippet(${kind ? `"${kind}"` : ""})) to ${gitignorePath}`
-    };
-  }
+function evaluatePhaseGate(snapshotDoc, compassDoc, opts = {}) {
+  const registered = registeredPlanIds(compassDoc);
+  const entryViolations = [
+    ...entryPlansAllDone(snapshotDoc, registered),
+    ...entryFrontmatterComplete(compassDoc)
+  ];
+  const exitViolations = [
+    ...exitFrontmatterClosed(compassDoc),
+    ...exitBranchCheck(opts),
+    ...exitPrBaseCheck(compassDoc, opts)
+  ];
+  const allPlansDone = registered.length > 0 && registered.every((planId) => {
+    const row = findPlanRow(snapshotDoc, planId);
+    return row !== null && row.status === PLAN_STATUS_DONE;
+  });
+  const entry = { ok: entryViolations.length === 0, violations: entryViolations };
+  const exit = { ok: exitViolations.length === 0, violations: exitViolations };
+  let transition;
+  if (!allPlansDone)
+    transition = "phase-2-execute";
+  else if (entry.ok && exit.ok)
+    transition = "phase-4-pr-delivery";
+  else
+    transition = "phase-3-close";
+  const gateBlocking = allPlansDone ? [...entryViolations, ...exitViolations] : [];
   return {
-    ok: true,
-    severity: "low",
-    code: "gitignore.ok",
-    message: `.gitignore at ${gitignorePath} contains a complete canonical harness ignore set — default-ignore + tracked re-includes (${label})`
+    transition,
+    allPlansDone,
+    entry,
+    exit,
+    ok: gateBlocking.length === 0,
+    violations: gateBlocking
   };
 }
-function detectHarnessKind(harnessDir) {
-  if (!harnessDir)
-    return null;
-  const name = basename2(resolve3(harnessDir));
-  if (name === ".mstar")
-    return "mstar";
-  if (name === ".agents")
-    return "agents";
-  return null;
+function pushCadenceProbe(ciRunning, reviewWaveActive) {
+  const violations = [];
+  if (ciRunning) {
+    violations.push(violation("high", "PUSH_BLOCKED_CI", "CI checks are still queued/in_progress on the current head — do not push until the wave completes (mstar-iteration §5.1a push gate 1)", "Wait for CI to settle, then push once with the whole local batch"));
+  }
+  if (reviewWaveActive) {
+    violations.push(violation("high", "PUSH_BLOCKED_REVIEW_WAVE", "An AI/bot review wave is still running on the current head — do not push until it settles (mstar-iteration §5.1a push gate 2)", "Wait for the review wave, then push once"));
+  }
+  return { ok: violations.length === 0, violations };
 }
-function assertPlanWritingPath(planPath, harnessDir) {
-  const planAbs = resolve3(planPath);
-  if (!harnessDir) {
+function assertIndexRowObligations(iterationsDir) {
+  if (!existsSync2(iterationsDir)) {
     return {
       ok: false,
-      severity: "high",
-      code: "plan-path.no-harness",
-      message: `persistent plan tracking is not enabled — cannot place plan ${planAbs} under {PLAN_DIR}`,
-      fix: "initialize the harness (scaffoldHarness) so plans land in {PLAN_DIR}"
+      violations: [
+        violation("high", "INDEX_ITERATIONS_DIR_MISSING", `{ITERATION_DIR} '${iterationsDir}' does not exist (mstar-iteration §1.4)`, "Create the iterations directory (path.resolveIterationDir)")
+      ]
     };
   }
-  const planDir = resolvePlanDir(harnessDir);
-  const rel = relative2(planDir, planAbs);
-  const inside = rel === "" || !rel.startsWith("..") && !isAbsolute2(rel);
-  if (!inside) {
+  const iterationIds = readdirSync(iterationsDir, { withFileTypes: true }).filter((entry) => entry.isDirectory()).filter((entry) => existsSync2(join3(iterationsDir, entry.name, COMPASS_FILE))).map((entry) => entry.name).sort();
+  const readmePath = join3(iterationsDir, INDEX_README);
+  if (!existsSync2(readmePath)) {
     return {
       ok: false,
-      severity: "high",
-      code: "plan-path.outside-plan-dir",
-      message: `plan file ${planAbs} is outside {PLAN_DIR} (${planDir})`,
-      fix: `write the plan under ${planDir}`
+      violations: [
+        violation("high", "INDEX_README_MISSING", `{ITERATION_DIR}/README.md does not exist — one row per iteration is required (mstar-iteration §1.4)`, `Create {ITERATION_DIR}/README.md with the header '${INDEX_HEADER}' and one row per iteration`)
+      ]
     };
   }
-  if (existsSync2(planAbs)) {
-    try {
-      const canonicalPlan = realpathSync(planAbs);
-      const canonicalPlanDir = existsSync2(planDir) ? realpathSync(planDir) : resolve3(planDir);
-      const canonicalRel = relative2(canonicalPlanDir, canonicalPlan);
-      const canonicalInside = canonicalRel === "" || !canonicalRel.startsWith("..") && !isAbsolute2(canonicalRel);
-      if (!canonicalInside) {
-        return {
-          ok: false,
-          severity: "high",
-          code: "plan-path.symlink-escape",
-          message: `plan file ${planAbs} resolves to ${canonicalPlan}, outside {PLAN_DIR} (${canonicalPlanDir})`,
-          fix: `write the plan under ${planDir}`
-        };
-      }
-    } catch {}
+  const violations = [];
+  const lines = readFileSync3(readmePath, "utf8").split(/\r?\n/);
+  if (!lines.some((line) => line.includes(INDEX_HEADER))) {
+    violations.push(violation("medium", "INDEX_HEADER_MISSING", `{ITERATION_DIR}/README.md lacks the table header '${INDEX_HEADER}' (mstar-iteration §1.4)`, "Add the header row on first creation"));
   }
-  return {
-    ok: true,
-    severity: "low",
-    code: "plan-path.ok",
-    message: `plan file ${planAbs} lives under {PLAN_DIR} (${planDir})`
-  };
+  const indexed = new Set;
+  for (const line of lines) {
+    const match = line.match(/^\s*\|\s*`([^`]+)`\s*\|/);
+    if (match)
+      indexed.add(match[1].trim());
+  }
+  for (const id of iterationIds) {
+    if (!indexed.has(id)) {
+      violations.push(violation("medium", "INDEX_ROW_MISSING", `Iteration '${id}' has a delivery-compass.md but no index row in {ITERATION_DIR}/README.md — one row per iteration (mstar-iteration §1.4)`, `Add | \`${id}\` | [\`${id}/\`](${id}/) | <description> | <status> |`));
+    }
+  }
+  return { ok: violations.length === 0, violations };
 }
-function isDirectory(dir) {
-  try {
-    return statSync2(dir).isDirectory();
-  } catch {
-    return false;
+function parseCompassFrontmatter(filePath) {
+  return parseCompassFrontmatterText(readFileSync3(filePath, "utf8"), filePath);
+}
+function parseCompassFrontmatterText(content, filePath) {
+  const lines = content.split(/\r?\n/);
+  if (lines[0]?.trim() !== "---") {
+    throw new Error(`no YAML frontmatter fence in ${filePath} (expected first line "---")`);
   }
+  const end = lines.indexOf("---", 1);
+  if (end === -1) {
+    throw new Error(`unterminated YAML frontmatter in ${filePath} (no closing "---")`);
+  }
+  const doc = {};
+  let listKey = null;
+  for (let i = 1;i < end; i += 1) {
+    const line = lines[i] ?? "";
+    if (!line.trim() || line.trim().startsWith("#"))
+      continue;
+    if (listKey !== null && /^\s*-\s+/.test(line)) {
+      const item = line.replace(/^\s*-\s+/, "").trim().replace(/^["']|["']$/g, "");
+      if (!Array.isArray(doc[listKey]))
+        doc[listKey] = [];
+      doc[listKey].push(item);
+      continue;
+    }
+    listKey = null;
+    const kv = line.match(/^([A-Za-z_][A-Za-z0-9_-]*):\s*(.*)$/);
+    if (!kv) {
+      throw new Error(`unsupported frontmatter line in ${filePath}: ${JSON.stringify(line)}`);
+    }
+    const value = kv[2].trim();
+    doc[kv[1]] = value === "" ? null : /^\[.*\]$/.test(value) ? parseFlowArray(value, filePath) : value.replace(/^["']|["']$/g, "");
+    listKey = value === "" ? kv[1] : null;
+  }
+  return doc;
 }
-function hasFiles(dir) {
-  try {
-    for (const entry of readdirSync(dir, { withFileTypes: true })) {
-      if (entry.isDirectory()) {
-        if (hasFiles(join3(dir, entry.name)))
-          return true;
-      } else if (entry.isFile()) {
-        return true;
-      }
+function parseFlowArray(raw, filePath) {
+  const inner = raw.slice(1, -1);
+  if (/[[\]]/.test(inner)) {
+    throw new Error(`nested flow-style array in ${filePath}: ${JSON.stringify(raw)} — only flat scalar items are supported (e.g. [a, b])`);
+  }
+  let quote = null;
+  for (const ch of inner) {
+    if (ch === '"' || ch === "'") {
+      if (quote === null)
+        quote = ch;
+      else if (quote === ch)
+        quote = null;
+    } else if (ch === "," && quote !== null) {
+      throw new Error(`ambiguous flow-style array in ${filePath}: ${JSON.stringify(raw)} — quoted item containing comma cannot be split unambiguously (flat scalar items only)`);
     }
-    return false;
-  } catch {
-    return false;
   }
+  if (quote !== null) {
+    throw new Error(`unterminated ${quote} quote in flow-style array in ${filePath}: ${JSON.stringify(raw)}`);
+  }
+  const items = [];
+  for (const part of inner.split(",")) {
+    const item = part.trim().replace(/^["']|["']$/g, "");
+    if (item === "")
+      continue;
+    items.push(item);
+  }
+  return items;
 }
+
 // src/status.ts
-import { existsSync as existsSync3, readFileSync as readFileSync4, readdirSync as readdirSync2, realpathSync as realpathSync2 } from "node:fs";
-import { dirname as dirname5, join as join6, resolve as resolve5, sep } from "node:path";
+import { existsSync as existsSync3, readFileSync as readFileSync4, readdirSync as readdirSync2, realpathSync } from "node:fs";
+import { dirname as dirname4, join as join6, resolve as resolve4, sep } from "node:path";
 
 // src/lease.ts
-import { mkdirSync as mkdirSync3, rmdirSync, statSync as statSync3, unlinkSync as unlinkSync2, writeFileSync as writeFileSync2 } from "node:fs";
-import { dirname as dirname4, isAbsolute as isAbsolute3, join as join4, resolve as resolve4 } from "node:path";
+import { mkdirSync as mkdirSync2, rmdirSync, statSync as statSync2, unlinkSync as unlinkSync2, writeFileSync as writeFileSync2 } from "node:fs";
+import { dirname as dirname3, isAbsolute as isAbsolute2, join as join4, resolve as resolve3 } from "node:path";
 import { setTimeout as sleep } from "node:timers/promises";
 import { AsyncLocalStorage } from "node:async_hooks";
-function isPlainObject(value) {
+function isPlainObject2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function violation(severity, code, message, fix) {
+function violation2(severity, code, message, fix) {
   return { ok: false, severity, code, message, fix };
 }
 function validateNonEmptyString(violations, value, field, missingCode, invalidCode) {
   if (value === undefined) {
-    violations.push(violation("high", missingCode, `missing required field: ${field}`));
+    violations.push(violation2("high", missingCode, `missing required field: ${field}`));
   } else if (typeof value !== "string" || value.trim() === "") {
-    violations.push(violation("medium", invalidCode, `${field} must be a non-empty string`));
+    violations.push(violation2("medium", invalidCode, `${field} must be a non-empty string`));
   }
 }
 var DATE_PART = String.raw`\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])`;
@@ -501,66 +539,66 @@ function isValidClaimedAt(value) {
 }
 function validateExecutionLease(lease) {
   const violations = [];
-  if (!isPlainObject(lease)) {
+  if (!isPlainObject2(lease)) {
     return {
       ok: false,
       violations: [
-        violation("high", "lease.execution-lease.invalid", "execution_lease must be an object — null and tombstone objects are invalid; writers delete the key on release")
+        violation2("high", "lease.execution-lease.invalid", "execution_lease must be an object — null and tombstone objects are invalid; writers delete the key on release")
       ]
     };
   }
   validateNonEmptyString(violations, lease.holder, "holder", "lease.execution-lease.missing-holder", "lease.execution-lease.invalid-holder");
   if (lease.claimed_at === undefined) {
-    violations.push(violation("high", "lease.execution-lease.missing-claimed-at", "missing required field: claimed_at"));
+    violations.push(violation2("high", "lease.execution-lease.missing-claimed-at", "missing required field: claimed_at"));
   } else if (!isValidClaimedAt(lease.claimed_at)) {
-    violations.push(violation("medium", "lease.execution-lease.invalid-claimed-at", "claimed_at must be an RFC 3339 UTC timestamp with explicit Z (e.g. 2026-07-22T02:30:00Z) or a YYYY-MM-DD date"));
+    violations.push(violation2("medium", "lease.execution-lease.invalid-claimed-at", "claimed_at must be an RFC 3339 UTC timestamp with explicit Z (e.g. 2026-07-22T02:30:00Z) or a YYYY-MM-DD date"));
   }
   if (lease.worktree_path === undefined) {
-    violations.push(violation("high", "lease.execution-lease.missing-worktree-path", "missing required field: worktree_path"));
+    violations.push(violation2("high", "lease.execution-lease.missing-worktree-path", "missing required field: worktree_path"));
   } else if (typeof lease.worktree_path !== "string" || lease.worktree_path.trim() === "") {
-    violations.push(violation("medium", "lease.execution-lease.invalid-worktree-path", "worktree_path must be a non-empty string"));
-  } else if (!isAbsolute3(lease.worktree_path)) {
-    violations.push(violation("medium", "lease.execution-lease.invalid-worktree-path", "worktree_path must be an absolute path — it identifies the dedicated feature-worktree root (and MUST differ from metadata.control_worktree_path)"));
+    violations.push(violation2("medium", "lease.execution-lease.invalid-worktree-path", "worktree_path must be a non-empty string"));
+  } else if (!isAbsolute2(lease.worktree_path)) {
+    violations.push(violation2("medium", "lease.execution-lease.invalid-worktree-path", "worktree_path must be an absolute path — it identifies the dedicated feature-worktree root (and MUST differ from metadata.control_worktree_path)"));
   }
   validateNonEmptyString(violations, lease.working_branch, "working_branch", "lease.execution-lease.missing-working-branch", "lease.execution-lease.invalid-working-branch");
   if (lease.session_label !== undefined && typeof lease.session_label !== "string") {
-    violations.push(violation("medium", "lease.execution-lease.invalid-session-label", "session_label must be a string (display only — never used for ownership comparison)"));
+    violations.push(violation2("medium", "lease.execution-lease.invalid-session-label", "session_label must be a string (display only — never used for ownership comparison)"));
   }
   return { ok: violations.length === 0, violations };
 }
 function validateIntegrationMergeLease(lease) {
   const violations = [];
-  if (!isPlainObject(lease)) {
+  if (!isPlainObject2(lease)) {
     return {
       ok: false,
       violations: [
-        violation("high", "lease.merge-lease.invalid", "integration_merge_lease must be an object — absent means unclaimed; null and tombstone objects are invalid; writers delete the key on release")
+        violation2("high", "lease.merge-lease.invalid", "integration_merge_lease must be an object — absent means unclaimed; null and tombstone objects are invalid; writers delete the key on release")
       ]
     };
   }
   validateNonEmptyString(violations, lease.holder, "holder", "lease.merge-lease.missing-holder", "lease.merge-lease.invalid-holder");
   if (lease.claimed_at === undefined) {
-    violations.push(violation("high", "lease.merge-lease.missing-claimed-at", "missing required field: claimed_at"));
+    violations.push(violation2("high", "lease.merge-lease.missing-claimed-at", "missing required field: claimed_at"));
   } else if (!isValidClaimedAt(lease.claimed_at)) {
-    violations.push(violation("medium", "lease.merge-lease.invalid-claimed-at", "claimed_at must be an RFC 3339 UTC timestamp with explicit Z (e.g. 2026-07-22T04:00:00Z) or a YYYY-MM-DD date"));
+    violations.push(violation2("medium", "lease.merge-lease.invalid-claimed-at", "claimed_at must be an RFC 3339 UTC timestamp with explicit Z (e.g. 2026-07-22T04:00:00Z) or a YYYY-MM-DD date"));
   }
   validateNonEmptyString(violations, lease.plan_id, "plan_id", "lease.merge-lease.missing-plan-id", "lease.merge-lease.invalid-plan-id");
   validateNonEmptyString(violations, lease.source_branch, "source_branch", "lease.merge-lease.missing-source-branch", "lease.merge-lease.invalid-source-branch");
   validateNonEmptyString(violations, lease.target_branch, "target_branch", "lease.merge-lease.missing-target-branch", "lease.merge-lease.invalid-target-branch");
   if (lease.session_label !== undefined && typeof lease.session_label !== "string") {
-    violations.push(violation("medium", "lease.merge-lease.invalid-session-label", "session_label must be a string (display only — never used for ownership comparison)"));
+    violations.push(violation2("medium", "lease.merge-lease.invalid-session-label", "session_label must be a string (display only — never used for ownership comparison)"));
   }
   return { ok: violations.length === 0, violations };
 }
 function claimLease(row, holder, fields) {
   const lease = row.execution_lease;
   if (lease !== undefined) {
-    if (!isPlainObject(lease)) {
+    if (!isPlainObject2(lease)) {
       return {
         ok: false,
         row,
         violations: [
-          violation("high", "lease.claim.tombstone", "execution_lease must be an object — null and tombstone objects are invalid; resolve the corrupt state before claiming")
+          violation2("high", "lease.claim.tombstone", "execution_lease must be an object — null and tombstone objects are invalid; resolve the corrupt state before claiming")
         ]
       };
     }
@@ -569,7 +607,7 @@ function claimLease(row, holder, fields) {
         ok: false,
         row,
         violations: [
-          violation("high", "lease.claim.other-holder", `execution_lease held by ${JSON.stringify(lease.holder)} — no timestamp makes it stealable; Blocked unless the current-turn user explicitly overrides (then audit plans[].notes)`)
+          violation2("high", "lease.claim.other-holder", `execution_lease held by ${JSON.stringify(lease.holder)} — no timestamp makes it stealable; Blocked unless the current-turn user explicitly overrides (then audit plans[].notes)`)
         ]
       };
     }
@@ -578,7 +616,7 @@ function claimLease(row, holder, fields) {
         ok: false,
         row,
         violations: [
-          violation("high", "lease.claim.verify-held-lease", `same holder but lease ${lease.worktree_path} @ ${lease.working_branch} does not match the Assignment ${fields.worktree_path} @ ${fields.working_branch} — verify-held-lease failed`)
+          violation2("high", "lease.claim.verify-held-lease", `same holder but lease ${lease.worktree_path} @ ${lease.working_branch} does not match the Assignment ${fields.worktree_path} @ ${fields.working_branch} — verify-held-lease failed`)
         ]
       };
     }
@@ -589,7 +627,7 @@ function claimLease(row, holder, fields) {
       ok: false,
       row,
       violations: [
-        violation("high", "lease.claim.orphan", "plan is InProgress without an execution_lease — orphan: STOP, no writable dispatch until recovery (status-and-residuals.md § Orphan recovery); do not invent a lease")
+        violation2("high", "lease.claim.orphan", "plan is InProgress without an execution_lease — orphan: STOP, no writable dispatch until recovery (status-and-residuals.md § Orphan recovery); do not invent a lease")
       ]
     };
   }
@@ -598,7 +636,7 @@ function claimLease(row, holder, fields) {
       ok: false,
       row,
       violations: [
-        violation("high", "lease.claim.status", `claim requires status Todo or Blocked (got ${JSON.stringify(row.status)}) — claim-before-InProgress contract`)
+        violation2("high", "lease.claim.status", `claim requires status Todo or Blocked (got ${JSON.stringify(row.status)}) — claim-before-InProgress contract`)
       ]
     };
   }
@@ -619,12 +657,12 @@ function releaseLease(row, holder) {
   if (row.execution_lease === undefined) {
     return { ok: true, row, outcome: "released", violations: [] };
   }
-  if (!isPlainObject(row.execution_lease)) {
+  if (!isPlainObject2(row.execution_lease)) {
     return {
       ok: false,
       row,
       violations: [
-        violation("high", "lease.release.tombstone", "execution_lease must be an object — null and tombstone objects are invalid; resolve the corrupt state before releasing")
+        violation2("high", "lease.release.tombstone", "execution_lease must be an object — null and tombstone objects are invalid; resolve the corrupt state before releasing")
       ]
     };
   }
@@ -633,7 +671,7 @@ function releaseLease(row, holder) {
       ok: false,
       row,
       violations: [
-        violation("high", "lease.release.other-holder", `execution_lease held by ${JSON.stringify(row.execution_lease.holder)} — release requires the same-session holder; a different holder must Blocked (no timestamp makes it stealable)`)
+        violation2("high", "lease.release.other-holder", `execution_lease held by ${JSON.stringify(row.execution_lease.holder)} — release requires the same-session holder; a different holder must Blocked (no timestamp makes it stealable)`)
       ]
     };
   }
@@ -641,10 +679,10 @@ function releaseLease(row, holder) {
   return { ok: true, row: rest, outcome: "released", violations: [] };
 }
 function sameHolderResume(lease, holder) {
-  return isPlainObject(lease) && lease.holder === holder;
+  return isPlainObject2(lease) && lease.holder === holder;
 }
 function canSteal(lease, holder, opts = {}) {
-  if (!isPlainObject(lease) || lease.holder === holder)
+  if (!isPlainObject2(lease) || lease.holder === holder)
     return false;
   return opts.userOverride === true;
 }
@@ -659,14 +697,14 @@ function verifyPlanExecutionLease(row, planId) {
       return {
         ok: false,
         violations: [
-          violation("high", "lease.verify.orphan", "plan is InProgress without an execution_lease — orphan: STOP, no writable dispatch until recovery (status-and-residuals.md § Orphan recovery)")
+          violation2("high", "lease.verify.orphan", "plan is InProgress without an execution_lease — orphan: STOP, no writable dispatch until recovery (status-and-residuals.md § Orphan recovery)")
         ]
       };
     }
     return {
       ok: false,
       violations: [
-        violation("high", "lease.verify.missing", `plan ${planId} has no execution_lease at the SSOT location plans[].execution_lease`)
+        violation2("high", "lease.verify.missing", `plan ${planId} has no execution_lease at the SSOT location plans[].execution_lease`)
       ]
     };
   }
@@ -678,7 +716,7 @@ var STATUS_WRITE_LOCKDIR = ".status-write.lockdir";
 var LOCKDIR_HOLDER_PID = "holder.pid";
 var heldLockDirs = new AsyncLocalStorage;
 async function withStatusWriteLock(statusPath, fn, opts = {}) {
-  const lockDir = join4(dirname4(resolve4(statusPath)), STATUS_WRITE_LOCKDIR);
+  const lockDir = join4(dirname3(resolve3(statusPath)), STATUS_WRITE_LOCKDIR);
   const held = heldLockDirs.getStore();
   if (held !== undefined && held.has(lockDir)) {
     throw new Error(`${lockDir} is already held by this process in this async context — withStatusWriteLock is not reentrant; a nested acquisition on the same status.json is a bug`);
@@ -689,8 +727,8 @@ async function withStatusWriteLock(statusPath, fn, opts = {}) {
   let acquired = null;
   for (;; ) {
     try {
-      mkdirSync3(lockDir);
-      const st = statSync3(lockDir);
+      mkdirSync2(lockDir);
+      const st = statSync2(lockDir);
       acquired = { dev: st.dev, ino: st.ino };
       break;
     } catch (error) {
@@ -712,7 +750,7 @@ async function withStatusWriteLock(statusPath, fn, opts = {}) {
   } finally {
     owns.delete(lockDir);
     try {
-      const current = statSync3(lockDir);
+      const current = statSync2(lockDir);
       if (acquired !== null && current.dev === acquired.dev && current.ino === acquired.ino) {
         try {
           unlinkSync2(join4(lockDir, LOCKDIR_HOLDER_PID));
@@ -730,7 +768,7 @@ var REQUIRED_FIELDS = [
   { key: "delegation", label: "Delegation", code: "delegation" },
   { key: "taskCategory", label: "Task category", code: "task-category" }
 ];
-function violation2(severity, code, message, fix) {
+function violation3(severity, code, message, fix) {
   return { ok: false, severity, code, message, fix };
 }
 function parseAssignmentFields(assignmentText) {
@@ -780,11 +818,11 @@ function parseEnforcementFlag(text) {
 }
 function requireField(violations, value, label, code) {
   if (value === undefined) {
-    const v = violation2("high", `assignment.field.missing-${code}`, `missing required Assignment field: ${label}`, `add "**${label}**: <value>" to the Assignment`);
+    const v = violation3("high", `assignment.field.missing-${code}`, `missing required Assignment field: ${label}`, `add "**${label}**: <value>" to the Assignment`);
     v.aliases = [`assignment.presence.missing-${code}`];
     violations.push(v);
   } else if (value === "") {
-    const v = violation2("high", `assignment.field.invalid-${code}`, `${label} must be non-empty`, `fill in "**${label}**: <value>"`);
+    const v = violation3("high", `assignment.field.invalid-${code}`, `${label} must be non-empty`, `fill in "**${label}**: <value>"`);
     v.aliases = [`assignment.presence.missing-${code}`];
     violations.push(v);
   }
@@ -843,20 +881,20 @@ function validateAssignmentFields(assignmentText, opts = {}) {
     const formCount = Number(workingPresent) + Number(policyPresent);
     const forms = parseAssignmentBranchForms(assignmentText);
     if (formCount === 0) {
-      violations.push(violation2("high", "assignment.field.branch-missing", "writable assignment must contain exactly one branch form", `add exactly one of: ${BRANCH_FORMS_HINT}`));
+      violations.push(violation3("high", "assignment.field.branch-missing", "writable assignment must contain exactly one branch form", `add exactly one of: ${BRANCH_FORMS_HINT}`));
     } else if (formCount > 1) {
-      violations.push(violation2("high", "assignment.field.branch-multiple", `writable assignment contains ${formCount} branch forms (Working branch + Branch policy) — exactly one required`, `keep exactly one of: ${BRANCH_FORMS_HINT}`));
+      violations.push(violation3("high", "assignment.field.branch-multiple", `writable assignment contains ${formCount} branch forms (Working branch + Branch policy) — exactly one required`, `keep exactly one of: ${BRANCH_FORMS_HINT}`));
     } else if (workingPresent) {
       const create = forms.createForm;
       if (create !== undefined && (create.base === undefined || create.base.trim() === "" || create.name.trim() === "")) {
-        violations.push(violation2("high", "assignment.field.branch-missing-base", `create-form Working branch is incomplete: "${fields.workingBranch}" (expected "create <new-branch> from <base>")`, "write both the new branch name and the ancestor branch after `from` (main / existing feature branch / remote-tracking branch / `current`)"));
+        violations.push(violation3("high", "assignment.field.branch-missing-base", `create-form Working branch is incomplete: "${fields.workingBranch}" (expected "create <new-branch> from <base>")`, "write both the new branch name and the ancestor branch after `from` (main / existing feature branch / remote-tracking branch / `current`)"));
       }
     } else if (policyPresent) {
       const direct = forms.directOn;
       if (direct === undefined) {
-        violations.push(violation2("high", "assignment.field.branch-policy-missing-branch", `unparseable Branch policy: "${fields.branchPolicy}" (expected "direct on <branch> — <reason>")`, "start the field with `direct on <branch>`"));
+        violations.push(violation3("high", "assignment.field.branch-policy-missing-branch", `unparseable Branch policy: "${fields.branchPolicy}" (expected "direct on <branch> — <reason>")`, "start the field with `direct on <branch>`"));
       } else if (direct.reason === "") {
-        violations.push(violation2("high", "assignment.field.branch-policy-missing-reason", `Branch policy "direct on ${direct.branch}" is missing the reason`, 'append "— <reason>" after the branch name'));
+        violations.push(violation3("high", "assignment.field.branch-policy-missing-reason", `Branch policy "direct on ${direct.branch}" is missing the reason`, 'append "— <reason>" after the branch name'));
       }
     }
   }
@@ -867,7 +905,7 @@ function assertDefaultBranchProtected(branch, opts = {}) {
   const violations = [];
   const normalized = branch.trim();
   if (normalized !== "" && defaultBranches.includes(normalized) && opts.directOnException !== true) {
-    violations.push(violation2("high", "dispatch.default-branch.protected", `writable work on default protected branch "${normalized}" requires an explicit direct-on exception`, `add "Branch policy: direct on ${normalized} — <reason>" to the Assignment, or use a feature branch`));
+    violations.push(violation3("high", "dispatch.default-branch.protected", `writable work on default protected branch "${normalized}" requires an explicit direct-on exception`, `add "Branch policy: direct on ${normalized} — <reason>" to the Assignment, or use a feature branch`));
   }
   return { ok: violations.length === 0, violations };
 }
@@ -876,7 +914,7 @@ function executionModeToN(executionMode, opts = {}) {
   const mode = executionMode.trim().toLowerCase().split(/\s+/)[0] ?? "";
   let n;
   if (mode === "") {
-    violations.push(violation2("high", "dispatch.execution-mode.missing", "missing required Assignment field: Execution mode", 'add "**Execution mode**: sdd | inline | targeted"'));
+    violations.push(violation3("high", "dispatch.execution-mode.missing", "missing required Assignment field: Execution mode", 'add "**Execution mode**: sdd | inline | targeted"'));
   } else if (mode === "sdd") {
     n = 3;
   } else if (mode === "inline") {
@@ -884,14 +922,14 @@ function executionModeToN(executionMode, opts = {}) {
   } else if (mode === "targeted") {
     const seats = [...new Set((opts.seats ?? []).map((s) => s.trim()).filter((s) => s !== ""))];
     if (seats.length === 0) {
-      violations.push(violation2("high", "dispatch.execution-mode.missing-seats", 'execution mode "targeted" requires listed reviewer seats', 'add "QC re-review: targeted — reviewers: <role-id>, …" to the Assignment and pass the seats'));
+      violations.push(violation3("high", "dispatch.execution-mode.missing-seats", 'execution mode "targeted" requires listed reviewer seats', 'add "QC re-review: targeted — reviewers: <role-id>, …" to the Assignment and pass the seats'));
     } else if (seats.length > 3) {
-      violations.push(violation2("high", "dispatch.execution-mode.too-many-seats", `execution mode "targeted" lists ${seats.length} reviewer seats — at most 3 (targeted re-review seats are the tri seats, N = 1–3)`, "list at most three reviewer seats for the targeted re-review"));
+      violations.push(violation3("high", "dispatch.execution-mode.too-many-seats", `execution mode "targeted" lists ${seats.length} reviewer seats — at most 3 (targeted re-review seats are the tri seats, N = 1–3)`, "list at most three reviewer seats for the targeted re-review"));
     } else {
       n = seats.length;
     }
   } else {
-    violations.push(violation2("high", "dispatch.execution-mode.unknown", `unknown execution mode "${executionMode.trim()}" (expected sdd | inline | targeted)`, "fix the Execution mode field"));
+    violations.push(violation3("high", "dispatch.execution-mode.unknown", `unknown execution mode "${executionMode.trim()}" (expected sdd | inline | targeted)`, "fix the Execution mode field"));
   }
   return n === undefined ? { ok: false, violations } : { ok: true, violations, n };
 }
@@ -905,7 +943,7 @@ function assertTriIdentity(reviewerRoles) {
   return {
     ok: false,
     violations: [
-      violation2("high", "dispatch.tri-identity.invalid", `tri-review initial wave must be exactly qc-specialist / qc-specialist-2 / qc-specialist-3, got: ${got}`, "dispatch qc-specialist, qc-specialist-2 and qc-specialist-3 for the initial wave")
+      violation3("high", "dispatch.tri-identity.invalid", `tri-review initial wave must be exactly qc-specialist / qc-specialist-2 / qc-specialist-3, got: ${got}`, "dispatch qc-specialist, qc-specialist-2 and qc-specialist-3 for the initial wave")
     ]
   };
 }
@@ -951,7 +989,7 @@ function antiRecursionPrecheck(subagentType, executeAs) {
     return {
       ok: false,
       violations: [
-        violation2("critical", "dispatch.anti-recursion.empty-binding", `empty host role binding — the host cannot report which agent is calling, so anti-recursion cannot be proven (a dispatch could silently recurse)`, "set the host role-binding field (omp task entry `agent` / opencode `subagent` / cursor `subagent_type` / dsh `dispatchBinding`) before dispatching")
+        violation3("critical", "dispatch.anti-recursion.empty-binding", `empty host role binding — the host cannot report which agent is calling, so anti-recursion cannot be proven (a dispatch could silently recurse)`, "set the host role-binding field (omp task entry `agent` / opencode `subagent` / cursor `subagent_type` / dsh `dispatchBinding`) before dispatching")
       ]
     };
   }
@@ -959,7 +997,7 @@ function antiRecursionPrecheck(subagentType, executeAs) {
     return {
       ok: false,
       violations: [
-        violation2("critical", "dispatch.anti-recursion.self-type", `recursive dispatch refused: role binding "${subagentType}" equals Execute as "${executeAs}" (leaf executors must not re-invoke their own role)`, "complete the work in this session, or return Blocked to project-manager")
+        violation3("critical", "dispatch.anti-recursion.self-type", `recursive dispatch refused: role binding "${subagentType}" equals Execute as "${executeAs}" (leaf executors must not re-invoke their own role)`, "complete the work in this session, or return Blocked to project-manager")
       ]
     };
   }
@@ -967,51 +1005,51 @@ function antiRecursionPrecheck(subagentType, executeAs) {
 }
 
 // src/workflow.ts
-import { mkdirSync as mkdirSync4 } from "node:fs";
+import { mkdirSync as mkdirSync3 } from "node:fs";
 import { join as join5 } from "node:path";
 var WORKFLOW_SNAPSHOT_FILE = "snapshot.json";
 var WORKFLOW_LIFECYCLE_STATUSES = ["running", "paused", "completed", "failed", "stopped"];
 var WORKFLOW_TERMINAL_STATUSES = ["completed", "failed", "stopped"];
 var WORKFLOW_LIFECYCLE_TYPES = ["plan", "iteration"];
-function isPlainObject2(value) {
+function isPlainObject3(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function violation3(severity, code, message, fix) {
+function violation4(severity, code, message, fix) {
   return { ok: false, severity, code, message, fix };
 }
 function validateNonEmptyString2(violations, value, field, missingCode, invalidCode) {
   if (value === undefined) {
-    violations.push(violation3("high", missingCode, `missing required field: ${field}`));
+    violations.push(violation4("high", missingCode, `missing required field: ${field}`));
   } else if (typeof value !== "string" || value.trim() === "") {
-    violations.push(violation3("medium", invalidCode, `${field} must be a non-empty string`));
+    violations.push(violation4("medium", invalidCode, `${field} must be a non-empty string`));
   }
 }
 function validateWorkflowSnapshot(doc) {
   const violations = [];
-  if (!isPlainObject2(doc)) {
+  if (!isPlainObject3(doc)) {
     return {
       ok: false,
-      violations: [violation3("high", "workflow.snapshot.invalid", "workflow snapshot must be an object")]
+      violations: [violation4("high", "workflow.snapshot.invalid", "workflow snapshot must be an object")]
     };
   }
   if (doc.schema_version === undefined) {
-    violations.push(violation3("high", "workflow.snapshot.missing-schema-version", "missing required field: schema_version"));
+    violations.push(violation4("high", "workflow.snapshot.missing-schema-version", "missing required field: schema_version"));
   } else if (doc.schema_version !== 1) {
-    violations.push(violation3("high", "workflow.snapshot.invalid-schema-version", `schema_version must be 1 — got ${JSON.stringify(doc.schema_version)} (version is reserved for the root file discriminator)`));
+    violations.push(violation4("high", "workflow.snapshot.invalid-schema-version", `schema_version must be 1 — got ${JSON.stringify(doc.schema_version)} (version is reserved for the root file discriminator)`));
   }
   if (doc.version !== undefined) {
-    violations.push(violation3("medium", "workflow.snapshot.reserved-version", `top-level version is reserved for the root status.json discriminator — snapshots use schema_version; remove the version key (got ${JSON.stringify(doc.version)})`, "remove the version key from the snapshot"));
+    violations.push(violation4("medium", "workflow.snapshot.reserved-version", `top-level version is reserved for the root status.json discriminator — snapshots use schema_version; remove the version key (got ${JSON.stringify(doc.version)})`, "remove the version key from the snapshot"));
   }
   validateNonEmptyString2(violations, doc.id, "id", "workflow.snapshot.missing-id", "workflow.snapshot.invalid-id");
   if (doc.type === undefined) {
-    violations.push(violation3("high", "workflow.snapshot.missing-type", "missing required field: type"));
+    violations.push(violation4("high", "workflow.snapshot.missing-type", "missing required field: type"));
   } else if (typeof doc.type !== "string" || !WORKFLOW_LIFECYCLE_TYPES.includes(doc.type)) {
-    violations.push(violation3("medium", "workflow.snapshot.invalid-type", `type must be one of ${WORKFLOW_LIFECYCLE_TYPES.join(" | ")} — got ${JSON.stringify(doc.type)}`));
+    violations.push(violation4("medium", "workflow.snapshot.invalid-type", `type must be one of ${WORKFLOW_LIFECYCLE_TYPES.join(" | ")} — got ${JSON.stringify(doc.type)}`));
   }
   if (doc.status === undefined) {
-    violations.push(violation3("high", "workflow.snapshot.missing-status", "missing required field: status"));
+    violations.push(violation4("high", "workflow.snapshot.missing-status", "missing required field: status"));
   } else if (typeof doc.status !== "string" || !WORKFLOW_LIFECYCLE_STATUSES.includes(doc.status)) {
-    violations.push(violation3("medium", "workflow.snapshot.invalid-status", `status must be one of ${WORKFLOW_LIFECYCLE_STATUSES.join(" | ")} — got ${JSON.stringify(doc.status)}`));
+    violations.push(violation4("medium", "workflow.snapshot.invalid-status", `status must be one of ${WORKFLOW_LIFECYCLE_STATUSES.join(" | ")} — got ${JSON.stringify(doc.status)}`));
   }
   validateNonEmptyString2(violations, doc.started_at, "started_at", "workflow.snapshot.missing-started-at", "workflow.snapshot.invalid-started-at");
   validateNonEmptyString2(violations, doc.updated_at, "updated_at", "workflow.snapshot.missing-updated-at", "workflow.snapshot.invalid-updated-at");
@@ -1019,35 +1057,35 @@ function validateWorkflowSnapshot(doc) {
     validateNonEmptyString2(violations, doc.ended_at, "ended_at", "workflow.snapshot.missing-ended-at", "workflow.snapshot.invalid-ended-at");
   }
   if (doc.phase !== undefined && typeof doc.phase !== "string") {
-    violations.push(violation3("medium", "workflow.snapshot.invalid-phase", "phase must be a string (free-form phase machine label)"));
+    violations.push(violation4("medium", "workflow.snapshot.invalid-phase", "phase must be a string (free-form phase machine label)"));
   }
   if (doc.plans === undefined) {
-    violations.push(violation3("high", "workflow.snapshot.missing-plans", "missing required field: plans"));
+    violations.push(violation4("high", "workflow.snapshot.missing-plans", "missing required field: plans"));
   } else if (!Array.isArray(doc.plans)) {
-    violations.push(violation3("high", "workflow.snapshot.invalid-plans", "plans must be an array of legacy plan rows"));
+    violations.push(violation4("high", "workflow.snapshot.invalid-plans", "plans must be an array of legacy plan rows"));
   } else {
     for (const row of doc.plans) {
       violations.push(...validatePlanRow(row).violations);
-      if (isPlainObject2(row) && row.execution_lease !== undefined) {
+      if (isPlainObject3(row) && row.execution_lease !== undefined) {
         violations.push(...validateExecutionLease(row.execution_lease).violations);
       }
     }
   }
   if (doc.execution_policy !== undefined) {
-    if (!isPlainObject2(doc.execution_policy)) {
-      violations.push(violation3("medium", "workflow.snapshot.invalid-execution-policy", "execution_policy must be an object"));
+    if (!isPlainObject3(doc.execution_policy)) {
+      violations.push(violation4("medium", "workflow.snapshot.invalid-execution-policy", "execution_policy must be an object"));
     }
   }
   if (doc.integration_merge_lease !== undefined) {
     violations.push(...validateIntegrationMergeLease(doc.integration_merge_lease).violations);
   }
   if (doc.branch !== undefined) {
-    if (!isPlainObject2(doc.branch)) {
-      violations.push(violation3("medium", "workflow.snapshot.invalid-branch", "branch must be an object"));
+    if (!isPlainObject3(doc.branch)) {
+      violations.push(violation4("medium", "workflow.snapshot.invalid-branch", "branch must be an object"));
     } else {
       for (const key of ["base", "integration", "target"]) {
         if (doc.branch[key] !== undefined && (typeof doc.branch[key] !== "string" || doc.branch[key].trim() === "")) {
-          violations.push(violation3("medium", "workflow.snapshot.invalid-branch", `branch.${key} must be a non-empty string`));
+          violations.push(violation4("medium", "workflow.snapshot.invalid-branch", `branch.${key} must be a non-empty string`));
         }
       }
     }
@@ -1055,8 +1093,8 @@ function validateWorkflowSnapshot(doc) {
   if (doc.control_worktree_path !== undefined) {
     validateNonEmptyString2(violations, doc.control_worktree_path, "control_worktree_path", "workflow.snapshot.missing-control-worktree-path", "workflow.snapshot.invalid-control-worktree-path");
   }
-  if (doc.legacy_metadata !== undefined && !isPlainObject2(doc.legacy_metadata)) {
-    violations.push(violation3("medium", "workflow.snapshot.invalid-legacy-metadata", "legacy_metadata must be an object"));
+  if (doc.legacy_metadata !== undefined && !isPlainObject3(doc.legacy_metadata)) {
+    violations.push(violation4("medium", "workflow.snapshot.invalid-legacy-metadata", "legacy_metadata must be an object"));
   }
   if (doc.compass_ref !== undefined) {
     validateNonEmptyString2(violations, doc.compass_ref, "compass_ref", "workflow.snapshot.missing-compass-ref", "workflow.snapshot.invalid-compass-ref");
@@ -1064,17 +1102,17 @@ function validateWorkflowSnapshot(doc) {
   const terminal = typeof doc.status === "string" && WORKFLOW_TERMINAL_STATUSES.includes(doc.status);
   if (terminal) {
     if (doc.ended_at === undefined) {
-      violations.push(violation3("high", "workflow.snapshot.missing-ended-at", `terminal status ${JSON.stringify(doc.status)} requires ended_at — a terminal snapshot must record when the lifecycle ended`));
+      violations.push(violation4("high", "workflow.snapshot.missing-ended-at", `terminal status ${JSON.stringify(doc.status)} requires ended_at — a terminal snapshot must record when the lifecycle ended`));
     }
     if (Array.isArray(doc.plans)) {
       for (const row of doc.plans) {
-        if (isPlainObject2(row) && row.execution_lease !== undefined) {
-          violations.push(violation3("high", "workflow.snapshot.terminal-dangling-execution-lease", `terminal snapshot must not carry a row execution_lease (dangling lease) — release every lease before the lifecycle ends`));
+        if (isPlainObject3(row) && row.execution_lease !== undefined) {
+          violations.push(violation4("high", "workflow.snapshot.terminal-dangling-execution-lease", `terminal snapshot must not carry a row execution_lease (dangling lease) — release every lease before the lifecycle ends`));
         }
       }
     }
     if (doc.integration_merge_lease !== undefined) {
-      violations.push(violation3("high", "workflow.snapshot.terminal-dangling-merge-lease", "terminal snapshot must not carry integration_merge_lease (dangling lease) — release the merge lease before the lifecycle ends"));
+      violations.push(violation4("high", "workflow.snapshot.terminal-dangling-merge-lease", "terminal snapshot must not carry integration_merge_lease (dangling lease) — release the merge lease before the lifecycle ends"));
     }
   }
   return { ok: violations.length === 0, violations };
@@ -1086,21 +1124,21 @@ async function writeWorkflowSnapshot(snapshot, dir) {
     throw new Error(`refusing to write invalid workflow snapshot: ${detail}`);
   }
   const snapshotPath = join5(dir, WORKFLOW_SNAPSHOT_FILE);
-  mkdirSync4(dir, { recursive: true });
+  mkdirSync3(dir, { recursive: true });
   await withStatusWriteLock(snapshotPath, () => {
     writeJson(snapshotPath, snapshot);
   });
 }
 
 // src/status.ts
-var DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+var DATE_RE2 = /^\d{4}-\d{2}-\d{2}$/;
 var PLAN_STATUSES = ["Todo", "InProgress", "InReview", "Blocked", "Done"];
 var RESIDUAL_DECISIONS = ["defer", "accept", "risk-accepted"];
 var RESIDUAL_LIFECYCLES = ["open", "resolved", "waived", "superseded", "duplicate"];
-function isPlainObject3(value) {
+function isPlainObject4(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function violation4(severity, code, message, fix) {
+function violation5(severity, code, message, fix) {
   return { ok: false, severity, code, message, fix };
 }
 function todayString() {
@@ -1123,19 +1161,19 @@ function isOpenResidual(entry) {
 }
 function validateNonEmptyString3(violations, value, field, missingCode, invalidCode) {
   if (value === undefined) {
-    violations.push(violation4("high", missingCode, `missing required field: ${field}`));
+    violations.push(violation5("high", missingCode, `missing required field: ${field}`));
   } else if (typeof value !== "string" || value.trim() === "") {
-    violations.push(violation4("medium", invalidCode, `${field} must be a non-empty string`));
+    violations.push(violation5("medium", invalidCode, `${field} must be a non-empty string`));
   }
 }
 function validatePlanRow(row) {
   const violations = [];
-  if (!isPlainObject3(row)) {
-    return { ok: false, violations: [violation4("high", "status.plan-row.invalid", "plan row must be an object")] };
+  if (!isPlainObject4(row)) {
+    return { ok: false, violations: [violation5("high", "status.plan-row.invalid", "plan row must be an object")] };
   }
   const { id, plan_id: planId, title, file, status, metadata, execution_lease } = row;
   if (id === undefined && planId === undefined) {
-    violations.push(violation4("high", "status.plan-row.missing-id", "missing required field: id (or legacy plan_id)"));
+    violations.push(violation5("high", "status.plan-row.missing-id", "missing required field: id (or legacy plan_id)"));
   } else {
     if (id !== undefined) {
       validateNonEmptyString3(violations, id, "id", "status.plan-row.missing-id", "status.plan-row.invalid-id");
@@ -1144,31 +1182,31 @@ function validatePlanRow(row) {
       validateNonEmptyString3(violations, planId, "plan_id", "status.plan-row.missing-plan-id", "status.plan-row.invalid-plan-id");
     }
     if (id !== undefined && planId !== undefined && id !== planId) {
-      violations.push(violation4("medium", "status.plan-row.dual-id", "row has both id and plan_id with different values — write one canonical key (prefer id)"));
+      violations.push(violation5("medium", "status.plan-row.dual-id", "row has both id and plan_id with different values — write one canonical key (prefer id)"));
     }
   }
   validateNonEmptyString3(violations, title, "title", "status.plan-row.missing-title", "status.plan-row.invalid-title");
   validateNonEmptyString3(violations, file, "file", "status.plan-row.missing-file", "status.plan-row.invalid-file");
   if (status === undefined) {
-    violations.push(violation4("high", "status.plan-row.missing-status", "missing required field: status"));
+    violations.push(violation5("high", "status.plan-row.missing-status", "missing required field: status"));
   } else if (typeof status !== "string" || !PLAN_STATUSES.includes(status)) {
-    violations.push(violation4("medium", "status.plan-row.invalid-status", `status must be one of ${PLAN_STATUSES.join(" | ")} — got ${JSON.stringify(status)}`));
+    violations.push(violation5("medium", "status.plan-row.invalid-status", `status must be one of ${PLAN_STATUSES.join(" | ")} — got ${JSON.stringify(status)}`));
   }
-  if (metadata !== undefined && !isPlainObject3(metadata)) {
-    violations.push(violation4("medium", "status.plan-row.invalid-metadata", "metadata must be an object"));
+  if (metadata !== undefined && !isPlainObject4(metadata)) {
+    violations.push(violation5("medium", "status.plan-row.invalid-metadata", "metadata must be an object"));
   }
-  if (execution_lease !== undefined && !isPlainObject3(execution_lease)) {
-    violations.push(violation4("medium", "status.plan-row.invalid-execution-lease", "execution_lease must be an object"));
+  if (execution_lease !== undefined && !isPlainObject4(execution_lease)) {
+    violations.push(violation5("medium", "status.plan-row.invalid-execution-lease", "execution_lease must be an object"));
   }
   if (status === "Done" && execution_lease !== undefined) {
-    violations.push(violation4("medium", "status.plan-row.done-with-lease", 'plan status Done must not carry an execution_lease — the Done authority deletes the lease in the same complete-file update as status: "Done" (status-and-residuals.md § Hold, release, and override)', 'delete plans[].execution_lease in the same update that sets status: "Done"'));
+    violations.push(violation5("medium", "status.plan-row.done-with-lease", 'plan status Done must not carry an execution_lease — the Done authority deletes the lease in the same complete-file update as status: "Done" (status-and-residuals.md § Hold, release, and override)', 'delete plans[].execution_lease in the same update that sets status: "Done"'));
   }
   return { ok: violations.length === 0, violations };
 }
 function validateResidual(entry) {
   const violations = [];
-  if (!isPlainObject3(entry)) {
-    return { ok: false, violations: [violation4("high", "status.residual.invalid", "residual entry must be an object")] };
+  if (!isPlainObject4(entry)) {
+    return { ok: false, violations: [violation5("high", "status.residual.invalid", "residual entry must be an object")] };
   }
   const { id, title, severity, source, scope, decision, owner, target, tracking, detail_doc, lifecycle, closed_at } = entry;
   validateNonEmptyString3(violations, id, "id", "status.residual.missing-id", "status.residual.invalid-id");
@@ -1177,42 +1215,42 @@ function validateResidual(entry) {
   validateNonEmptyString3(violations, scope, "scope", "status.residual.missing-scope", "status.residual.invalid-scope");
   validateNonEmptyString3(violations, owner, "owner", "status.residual.missing-owner", "status.residual.invalid-owner");
   if (severity === undefined) {
-    violations.push(violation4("high", "status.residual.missing-severity", "missing required field: severity"));
+    violations.push(violation5("high", "status.residual.missing-severity", "missing required field: severity"));
   } else if (typeof severity !== "string" || !SEVERITY_ORDER.includes(severity) && severity !== "warning") {
-    violations.push(violation4("medium", "status.residual.invalid-severity", `severity must be one of ${SEVERITY_ORDER.join(" | ")} — got ${JSON.stringify(severity)}`));
+    violations.push(violation5("medium", "status.residual.invalid-severity", `severity must be one of ${SEVERITY_ORDER.join(" | ")} — got ${JSON.stringify(severity)}`));
   } else if (severity === "warning") {
-    violations.push(violation4("low", "status.residual.legacy-warning", `severity "warning" is legacy — forbidden on new entries; read paths normalize it to "low"`, `use "low" (normalizeSeverity maps 'warning' → 'low')`));
+    violations.push(violation5("low", "status.residual.legacy-warning", `severity "warning" is legacy — forbidden on new entries; read paths normalize it to "low"`, `use "low" (normalizeSeverity maps 'warning' → 'low')`));
   }
   if (decision === undefined) {
-    violations.push(violation4("high", "status.residual.missing-decision", "missing required field: decision"));
+    violations.push(violation5("high", "status.residual.missing-decision", "missing required field: decision"));
   } else if (typeof decision !== "string" || !RESIDUAL_DECISIONS.includes(decision)) {
-    violations.push(violation4("medium", "status.residual.invalid-decision", `decision must be one of ${RESIDUAL_DECISIONS.join(" | ")} — got ${JSON.stringify(decision)}`));
+    violations.push(violation5("medium", "status.residual.invalid-decision", `decision must be one of ${RESIDUAL_DECISIONS.join(" | ")} — got ${JSON.stringify(decision)}`));
   }
   if (target === undefined) {
-    violations.push(violation4("high", "status.residual.missing-target", "missing required field: target"));
+    violations.push(violation5("high", "status.residual.missing-target", "missing required field: target"));
   } else if (typeof target !== "string" && target !== null) {
-    violations.push(violation4("medium", "status.residual.invalid-target", "target must be a string or null"));
+    violations.push(violation5("medium", "status.residual.invalid-target", "target must be a string or null"));
   }
   if (tracking === undefined) {
-    violations.push(violation4("high", "status.residual.missing-tracking", "missing required field: tracking"));
+    violations.push(violation5("high", "status.residual.missing-tracking", "missing required field: tracking"));
   } else if (typeof tracking !== "string" && tracking !== null) {
-    violations.push(violation4("medium", "status.residual.invalid-tracking", "tracking must be a string or null"));
+    violations.push(violation5("medium", "status.residual.invalid-tracking", "tracking must be a string or null"));
   }
   if (detail_doc !== undefined && typeof detail_doc !== "string" && detail_doc !== null) {
-    violations.push(violation4("medium", "status.residual.invalid-detail-doc", "detail_doc must be a string or null"));
+    violations.push(violation5("medium", "status.residual.invalid-detail-doc", "detail_doc must be a string or null"));
   }
-  if (closed_at !== undefined && (typeof closed_at !== "string" || !DATE_RE.test(closed_at))) {
-    violations.push(violation4("medium", "status.residual.invalid-closed-at", "closed_at must be YYYY-MM-DD"));
+  if (closed_at !== undefined && (typeof closed_at !== "string" || !DATE_RE2.test(closed_at))) {
+    violations.push(violation5("medium", "status.residual.invalid-closed-at", "closed_at must be YYYY-MM-DD"));
   }
   if (lifecycle !== undefined) {
     if (typeof lifecycle !== "string" || !RESIDUAL_LIFECYCLES.includes(lifecycle)) {
-      violations.push(violation4("medium", "status.residual.invalid-lifecycle", `lifecycle must be one of ${RESIDUAL_LIFECYCLES.join(" | ")} — got ${JSON.stringify(lifecycle)}`));
+      violations.push(violation5("medium", "status.residual.invalid-lifecycle", `lifecycle must be one of ${RESIDUAL_LIFECYCLES.join(" | ")} — got ${JSON.stringify(lifecycle)}`));
     } else if (lifecycle !== "open") {
       if (closed_at === undefined) {
-        violations.push(violation4("high", "status.residual.closed-missing-closed-at", `lifecycle "${lifecycle}" requires closed_at (YYYY-MM-DD)`, 'set closed_at (e.g. "2026-08-08")'));
+        violations.push(violation5("high", "status.residual.closed-missing-closed-at", `lifecycle "${lifecycle}" requires closed_at (YYYY-MM-DD)`, 'set closed_at (e.g. "2026-08-08")'));
       }
       if (entry.closure_note === undefined) {
-        violations.push(violation4("medium", "status.residual.closed-missing-closure-note", `lifecycle "${lifecycle}" requires closure_note (what changed; how verified)`, "add closure_note explaining the close"));
+        violations.push(violation5("medium", "status.residual.closed-missing-closure-note", `lifecycle "${lifecycle}" requires closure_note (what changed; how verified)`, "add closure_note explaining the close"));
       }
     }
   }
@@ -1227,25 +1265,25 @@ function isHarnessRelativePath(dir) {
 }
 function validateWorkflowEntry(entry) {
   const violations = [];
-  if (!isPlainObject3(entry)) {
+  if (!isPlainObject4(entry)) {
     return {
       ok: false,
-      violations: [violation4("high", "status.workflow.invalid", "workflow entry must be an object")]
+      violations: [violation5("high", "status.workflow.invalid", "workflow entry must be an object")]
     };
   }
   validateNonEmptyString3(violations, entry.id, "id", "status.workflow.missing-id", "status.workflow.invalid-id");
   if (entry.type === undefined) {
-    violations.push(violation4("high", "status.workflow.missing-type", "missing required field: type"));
+    violations.push(violation5("high", "status.workflow.missing-type", "missing required field: type"));
   } else if (typeof entry.type !== "string" || !WORKFLOW_LIFECYCLE_TYPES.includes(entry.type)) {
-    violations.push(violation4("medium", "status.workflow.invalid-type", `type must be one of ${WORKFLOW_LIFECYCLE_TYPES.join(" | ")} — got ${JSON.stringify(entry.type)}`));
+    violations.push(violation5("medium", "status.workflow.invalid-type", `type must be one of ${WORKFLOW_LIFECYCLE_TYPES.join(" | ")} — got ${JSON.stringify(entry.type)}`));
   }
   validateNonEmptyString3(violations, entry.started_at, "started_at", "status.workflow.missing-started-at", "status.workflow.invalid-started-at");
   if (entry.dir === undefined) {
-    violations.push(violation4("high", "status.workflow.missing-dir", "missing required field: dir"));
+    violations.push(violation5("high", "status.workflow.missing-dir", "missing required field: dir"));
   } else if (typeof entry.dir !== "string" || entry.dir.trim() === "") {
-    violations.push(violation4("medium", "status.workflow.invalid-dir", "dir must be a non-empty string"));
+    violations.push(violation5("medium", "status.workflow.invalid-dir", "dir must be a non-empty string"));
   } else if (!isHarnessRelativePath(entry.dir)) {
-    violations.push(violation4("medium", "status.workflow.invalid-dir", `dir must be a harness-relative path (no absolute paths, no ".." segments) — got ${JSON.stringify(entry.dir)}`));
+    violations.push(violation5("medium", "status.workflow.invalid-dir", `dir must be a harness-relative path (no absolute paths, no ".." segments) — got ${JSON.stringify(entry.dir)}`));
   }
   return { ok: violations.length === 0, violations };
 }
@@ -1255,24 +1293,24 @@ function validateStatusV2(docOrPath, opts = {}) {
   if (typeof docOrPath === "string") {
     try {
       doc = readJson(docOrPath);
-      harnessDir = dirname5(resolve5(docOrPath));
+      harnessDir = dirname4(resolve4(docOrPath));
     } catch (error) {
       return {
         ok: false,
-        violations: [violation4("high", "status.invalid-json", error.message)]
+        violations: [violation5("high", "status.invalid-json", error.message)]
       };
     }
   } else {
     doc = docOrPath;
   }
-  if (!isPlainObject3(doc)) {
-    return { ok: false, violations: [violation4("high", "status.invalid-doc", "status document must be an object")] };
+  if (!isPlainObject4(doc)) {
+    return { ok: false, violations: [violation5("high", "status.invalid-doc", "status document must be an object")] };
   }
   if (doc.version !== 2) {
     return {
       ok: false,
       violations: [
-        violation4("high", "status.migration-required", `status.json schema version 2 required — got ${JSON.stringify(doc.version)} (v1 or unknown version); run \`mstar migrate\` to convert the tree`, "run `mstar migrate`")
+        violation5("high", "status.migration-required", `status.json schema version 2 required — got ${JSON.stringify(doc.version)} (v1 or unknown version); run \`mstar migrate\` to convert the tree`, "run `mstar migrate`")
       ]
     };
   }
@@ -1280,7 +1318,7 @@ function validateStatusV2(docOrPath, opts = {}) {
     return {
       ok: false,
       violations: [
-        violation4("high", "status.migration-required", "v1-shaped status.json (root plans[]) is not a v2 document — run `mstar migrate` to convert the tree", "run `mstar migrate`")
+        violation5("high", "status.migration-required", "v1-shaped status.json (root plans[]) is not a v2 document — run `mstar migrate` to convert the tree", "run `mstar migrate`")
       ]
     };
   }
@@ -1288,27 +1326,27 @@ function validateStatusV2(docOrPath, opts = {}) {
     return {
       ok: false,
       violations: [
-        violation4("high", "status.migration-required", "v1-shaped status.json (root residual_findings) is not a v2 document — run `mstar migrate` to convert the tree", "run `mstar migrate`")
+        violation5("high", "status.migration-required", "v1-shaped status.json (root residual_findings) is not a v2 document — run `mstar migrate` to convert the tree", "run `mstar migrate`")
       ]
     };
   }
   const violations = [];
   if (doc.updated_at === undefined) {
-    violations.push(violation4("high", "status.missing-updated-at", "missing required field: updated_at"));
-  } else if (typeof doc.updated_at !== "string" || !DATE_RE.test(doc.updated_at)) {
-    violations.push(violation4("medium", "status.invalid-updated-at", "updated_at must be YYYY-MM-DD"));
+    violations.push(violation5("high", "status.missing-updated-at", "missing required field: updated_at"));
+  } else if (typeof doc.updated_at !== "string" || !DATE_RE2.test(doc.updated_at)) {
+    violations.push(violation5("medium", "status.invalid-updated-at", "updated_at must be YYYY-MM-DD"));
   }
   if (doc.workflows === undefined) {
-    violations.push(violation4("high", "status.missing-workflows", "missing required field: workflows"));
+    violations.push(violation5("high", "status.missing-workflows", "missing required field: workflows"));
   } else if (!Array.isArray(doc.workflows)) {
-    violations.push(violation4("high", "status.invalid-workflows", "workflows must be an array"));
+    violations.push(violation5("high", "status.invalid-workflows", "workflows must be an array"));
   } else {
     const seen = new Set;
     for (const entry of doc.workflows) {
       violations.push(...validateWorkflowEntry(entry).violations);
-      if (isPlainObject3(entry) && typeof entry.id === "string") {
+      if (isPlainObject4(entry) && typeof entry.id === "string") {
         if (seen.has(entry.id)) {
-          violations.push(violation4("medium", "status.workflow.duplicate-id", `duplicate workflow id in workflows[]: ${JSON.stringify(entry.id)}`));
+          violations.push(violation5("medium", "status.workflow.duplicate-id", `duplicate workflow id in workflows[]: ${JSON.stringify(entry.id)}`));
         }
         seen.add(entry.id);
       }
@@ -1317,40 +1355,40 @@ function validateStatusV2(docOrPath, opts = {}) {
   if (harnessDir !== undefined && Array.isArray(doc.workflows)) {
     let realHarnessDir = null;
     try {
-      realHarnessDir = realpathSync2(harnessDir);
+      realHarnessDir = realpathSync(harnessDir);
     } catch {}
     for (const entry of doc.workflows) {
-      if (!isPlainObject3(entry) || typeof entry.dir !== "string")
+      if (!isPlainObject4(entry) || typeof entry.dir !== "string")
         continue;
       const relSnapshot = join6(entry.dir, WORKFLOW_SNAPSHOT_FILE);
       const snapshotPath = join6(harnessDir, relSnapshot);
       const label = typeof entry.id === "string" ? entry.id : relSnapshot;
       let physical;
       try {
-        physical = realpathSync2(snapshotPath);
+        physical = realpathSync(snapshotPath);
       } catch {
-        violations.push(violation4("high", "status.workflow.snapshot-missing", `workflows[] lists ${JSON.stringify(label)} but its snapshot does not exist at ${JSON.stringify(relSnapshot)} — the root holds active lifecycles only; unregister the id when its snapshot is removed`));
+        violations.push(violation5("high", "status.workflow.snapshot-missing", `workflows[] lists ${JSON.stringify(label)} but its snapshot does not exist at ${JSON.stringify(relSnapshot)} — the root holds active lifecycles only; unregister the id when its snapshot is removed`));
         continue;
       }
       if (realHarnessDir !== null && physical !== realHarnessDir && !physical.startsWith(`${realHarnessDir}${sep}`)) {
-        violations.push(violation4("high", "status.workflow.snapshot-outside-harness", `workflows[] lists ${JSON.stringify(label)} but its snapshot resolves outside the harness dir (${JSON.stringify(physical)}) — symlinked snapshot paths are rejected; the snapshot must physically live under ${JSON.stringify(harnessDir)}`));
+        violations.push(violation5("high", "status.workflow.snapshot-outside-harness", `workflows[] lists ${JSON.stringify(label)} but its snapshot resolves outside the harness dir (${JSON.stringify(physical)}) — symlinked snapshot paths are rejected; the snapshot must physically live under ${JSON.stringify(harnessDir)}`));
         continue;
       }
       let snapshot;
       try {
         snapshot = readJson(snapshotPath);
       } catch (error) {
-        violations.push(violation4("high", "status.workflow.snapshot-invalid", `snapshot at ${JSON.stringify(relSnapshot)} is not valid JSON: ${error.message}`));
+        violations.push(violation5("high", "status.workflow.snapshot-invalid", `snapshot at ${JSON.stringify(relSnapshot)} is not valid JSON: ${error.message}`));
         continue;
       }
       if (typeof snapshot.status === "string" && WORKFLOW_TERMINAL_STATUSES.includes(snapshot.status)) {
-        violations.push(violation4("high", "status.workflow.terminal-listed", `workflows[] lists ${JSON.stringify(label)} whose snapshot status is terminal (${snapshot.status}) — removal-at-terminal: terminal writers unregister AFTER the snapshot write`));
+        violations.push(violation5("high", "status.workflow.terminal-listed", `workflows[] lists ${JSON.stringify(label)} whose snapshot status is terminal (${snapshot.status}) — removal-at-terminal: terminal writers unregister AFTER the snapshot write`));
       }
       if (typeof entry.type === "string" && typeof snapshot.type === "string" && entry.type !== snapshot.type) {
-        violations.push(violation4("medium", "status.workflow.mismatched-type", `workflows[] entry ${JSON.stringify(label)} type ${JSON.stringify(entry.type)} does not match its snapshot type ${JSON.stringify(snapshot.type)} — the root entry mirrors the snapshot; align them`));
+        violations.push(violation5("medium", "status.workflow.mismatched-type", `workflows[] entry ${JSON.stringify(label)} type ${JSON.stringify(entry.type)} does not match its snapshot type ${JSON.stringify(snapshot.type)} — the root entry mirrors the snapshot; align them`));
       }
       if (typeof entry.started_at === "string" && typeof snapshot.started_at === "string" && entry.started_at !== snapshot.started_at) {
-        violations.push(violation4("medium", "status.workflow.mismatched-started-at", `workflows[] entry ${JSON.stringify(label)} started_at ${JSON.stringify(entry.started_at)} does not match its snapshot started_at ${JSON.stringify(snapshot.started_at)} — workflow ${JSON.stringify(label)} collided with another writer (e.g. a concurrent/re-run \`audit promote\` with the same workflow id rewrote the snapshot); the root entry mirrors the snapshot — align them or remove the colliding workflow`));
+        violations.push(violation5("medium", "status.workflow.mismatched-started-at", `workflows[] entry ${JSON.stringify(label)} started_at ${JSON.stringify(entry.started_at)} does not match its snapshot started_at ${JSON.stringify(snapshot.started_at)} — workflow ${JSON.stringify(label)} collided with another writer (e.g. a concurrent/re-run \`audit promote\` with the same workflow id rewrote the snapshot); the root entry mirrors the snapshot — align them or remove the colliding workflow`));
       }
     }
   }
@@ -1358,7 +1396,7 @@ function validateStatusV2(docOrPath, opts = {}) {
 }
 var validateStatus = validateStatusV2;
 function registerWorkflowEntryLocked(statusPath, entry) {
-  const harnessDir = dirname5(statusPath);
+  const harnessDir = dirname4(statusPath);
   const current = readJson(statusPath);
   const fresh = Object.keys(current).length === 0;
   const doc = fresh ? { version: 2, updated_at: todayString(), workflows: [] } : current;
@@ -1384,15 +1422,15 @@ async function registerWorkflow(root, entry) {
   if (!entryGate.ok) {
     throw new Error(`refusing to register invalid workflow entry: ${entryGate.violations.map((v) => v.message).join("; ")}`);
   }
-  const statusPath = resolve5(root);
+  const statusPath = resolve4(root);
   return withStatusWriteLock(statusPath, () => registerWorkflowEntryLocked(statusPath, entry));
 }
 async function unregisterWorkflow(root, id) {
   if (typeof id !== "string" || id.trim() === "") {
     throw new Error("refusing to unregister workflow: id must be a non-empty string");
   }
-  const statusPath = resolve5(root);
-  const harnessDir = dirname5(statusPath);
+  const statusPath = resolve4(root);
+  const harnessDir = dirname4(statusPath);
   return withStatusWriteLock(statusPath, () => {
     const current = readJson(statusPath);
     if (Object.keys(current).length === 0) {
@@ -1449,8 +1487,8 @@ function resolveCompassEnforcement(harnessDir) {
   return { hard: false, source: "none" };
 }
 function resolveMstarcEnforcement(harnessDir) {
-  const dir = resolve5(harnessDir);
-  const rc = loadMstarc(dir, dirname5(dir));
+  const dir = resolve4(harnessDir);
+  const rc = loadMstarc(dir, dirname4(dir));
   const value = rc?.config.enforcement;
   if (value === "hard")
     return { hard: true, source: "mstarc" };
@@ -1464,1025 +1502,1030 @@ function resolveRepoEnforcement(harnessDir) {
     return rc;
   return resolveCompassEnforcement(harnessDir);
 }
-// src/worktree.ts
-import { execFileSync as execFileSync2 } from "node:child_process";
-import { existsSync as existsSync4 } from "node:fs";
-import { isAbsolute as isAbsolute4, resolve as resolve6 } from "node:path";
-var DEFAULT_PROBE_TIMEOUT_MS = 1e4;
-function probeTimeoutMs() {
-  const raw = process.env.MSTAR_GIT_PROBE_TIMEOUT_MS;
-  if (raw === undefined || raw.trim() === "")
-    return DEFAULT_PROBE_TIMEOUT_MS;
-  const parsed = Number(raw);
-  return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_PROBE_TIMEOUT_MS;
+
+// src/project.ts
+var PROJECT_ROADMAP_FILE = "roadmap.md";
+var PROJECT_REFERENCES_DIR = "references";
+var PROJECT_REGISTER_FILE = "residuals.json";
+var _DEFAULT_PROJECT = "_default";
+var ROADMAP_STATUSES = ["active", "paused", "completed"];
+var DATE_RE3 = /^\d{4}-\d{2}-\d{2}$/;
+var ROLLUP_FIELDS = ["total_open", "by_severity", "by_target", "by_plan"];
+function isPlainObject5(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function violation5(severity, code, message, fix) {
+function violation6(severity, code, message, fix) {
   return { ok: false, severity, code, message, fix };
 }
-function gate(violations) {
-  return { ok: violations.length === 0, violations };
-}
-function probeBranch(worktreePath, opts) {
-  const precomputed = opts.branchOf?.(worktreePath);
-  if (precomputed !== undefined)
-    return { branch: precomputed };
-  const timeout = opts.timeoutMs ?? probeTimeoutMs();
-  try {
-    const stdout = execFileSync2(opts.gitPath ?? "git", ["-C", worktreePath, "branch", "--show-current"], {
-      encoding: "utf8",
-      stdio: ["ignore", "pipe", "pipe"],
-      timeout
-    });
-    const branch = stdout.trim();
-    if (branch === "")
-      return { error: `no branch checked out (detached HEAD?) at "${worktreePath}"` };
-    return { branch };
-  } 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 validateNonEmptyString4(violations, value, field, missingCode, invalidCode) {
+  if (value === undefined) {
+    violations.push(violation6("high", missingCode, `missing required field: ${field}`));
+  } else if (typeof value !== "string" || value.trim() === "") {
+    violations.push(violation6("medium", invalidCode, `${field} must be a non-empty string`));
   }
 }
-function l1PreDispatchCheck(input, opts = {}) {
+function validateRoadmap(filePath) {
   const violations = [];
-  const { controlWorktreePath, leaseWorktreePath, leaseWorkingBranch, planId } = input;
-  if (controlWorktreePath.trim() === "") {
-    violations.push(violation5("high", "worktree.l1.control-missing", "metadata.control_worktree_path is not recorded — the L1 control worktree (integration-branch checkout) must be recorded in status.json before writable dispatch", "record the control worktree path in status.json metadata.control_worktree_path"));
+  let content;
+  try {
+    content = readFileSync5(filePath, "utf8");
+  } catch {
+    return {
+      ok: false,
+      violations: [violation6("high", "project.roadmap.unreadable", `cannot read roadmap file: ${filePath}`)],
+      warnings: []
+    };
   }
-  if (leaseWorktreePath.trim() === "") {
-    violations.push(violation5("high", "worktree.l1.lease-missing", `execution_lease.worktree_path is empty for plan "${planId}" — no verified execution_lease to dispatch against`, "claim the execution_lease with an absolute feature worktree path before dispatch"));
+  let doc;
+  try {
+    doc = parseCompassFrontmatterText(content, filePath);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : `invalid roadmap frontmatter in ${filePath}`;
+    return { ok: false, violations: [violation6("high", "project.roadmap.invalid-frontmatter", message)], warnings: [] };
   }
-  if (leaseWorkingBranch.trim() === "") {
-    violations.push(violation5("high", "worktree.l1.lease-branch-missing", `execution_lease.working_branch is empty for plan "${planId}"`, "record the lease working_branch before dispatch"));
+  validateNonEmptyString4(violations, doc.project_id, "project_id", "project.roadmap.missing-project-id", "project.roadmap.invalid-project-id");
+  validateNonEmptyString4(violations, doc.title, "title", "project.roadmap.missing-title", "project.roadmap.invalid-title");
+  if (doc.status === undefined) {
+    violations.push(violation6("high", "project.roadmap.missing-status", "missing required field: status"));
+  } else if (typeof doc.status !== "string" || !ROADMAP_STATUSES.includes(doc.status)) {
+    violations.push(violation6("medium", "project.roadmap.invalid-status", `status must be one of ${ROADMAP_STATUSES.join(" | ")} — got ${JSON.stringify(doc.status)}`));
   }
-  if (controlWorktreePath !== "" && leaseWorktreePath !== "" && resolve6(controlWorktreePath) === resolve6(leaseWorktreePath)) {
-    violations.push(violation5("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 (doc.created_at === undefined) {
+    violations.push(violation6("high", "project.roadmap.missing-created-at", "missing required field: created_at"));
+  } else if (typeof doc.created_at !== "string" || !DATE_RE3.test(doc.created_at)) {
+    violations.push(violation6("medium", "project.roadmap.invalid-created-at", "created_at must be YYYY-MM-DD"));
   }
-  if (leaseWorktreePath !== "" && !existsSync4(leaseWorktreePath)) {
-    violations.push(violation5("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>`));
-  } else if (leaseWorktreePath !== "" && leaseWorkingBranch !== "") {
-    const probe = probeBranch(leaseWorktreePath, opts);
-    if ("error" in probe) {
-      violations.push(violation5("high", "worktree.l1.branch-probe-failed", `cannot probe branch at "${leaseWorktreePath}" for plan "${planId}": ${probe.error}`, "verify the path is a git worktree checkout on the lease working branch (not detached)"));
-    } else if (probe.branch !== leaseWorkingBranch) {
-      violations.push(violation5("high", "worktree.l1.branch-mismatch", `feature worktree "${leaseWorktreePath}" is on branch "${probe.branch}", expected execution_lease.working_branch "${leaseWorkingBranch}" (plan "${planId}")`, `checkout ${leaseWorkingBranch} in the feature worktree`));
+  if (doc.milestones !== undefined && doc.milestones !== null) {
+    if (!Array.isArray(doc.milestones)) {
+      violations.push(violation6("medium", "project.roadmap.invalid-milestones", "milestones must be a list of milestone names"));
+    } else {
+      for (const item of doc.milestones) {
+        if (typeof item !== "string" || item.trim() === "") {
+          violations.push(violation6("medium", "project.roadmap.invalid-milestones", "milestones items must be non-empty strings"));
+          break;
+        }
+      }
     }
   }
-  return gate(violations);
-}
-function l2PreDispatchCheck(input, opts = {}) {
-  const violations = [];
-  const tracks = input.tracks ?? [];
-  const seenPaths = new Set;
-  if (tracks.length < 1) {
-    violations.push(violation5("high", "worktree.l2.no-tracks", "no parallel writable tracks — the L2 pre-dispatch checklist requires at least one track with an absolute worktreePath and Working branch", "pass each track's absolute Worktree path and PM-approved Working branch"));
-  }
-  tracks.forEach((track, index) => {
-    if (track.worktreePath.trim() === "" || track.workingBranch.trim() === "") {
-      violations.push(violation5("high", "worktree.l2.track-invalid", `track ${index + 1} is missing worktreePath and/or workingBranch`, "fill both fields for every track"));
-      return;
-    }
-    if (!isAbsolute4(track.worktreePath)) {
-      violations.push(violation5("high", "worktree.l2.track-path-relative", `track ${index + 1} worktreePath "${track.worktreePath}" is not an absolute path — L2 tracks MUST use absolute worktree checkout paths (consistent with the lease validator's absolute worktree_path enforcement)`, `use an absolute path for track ${index + 1} (e.g. /Users/<you>/worktrees/<branch>)`));
-      return;
-    }
-    const normalized = resolve6(track.worktreePath);
-    if (seenPaths.has(normalized)) {
-      violations.push(violation5("high", "worktree.l2.track-path-collision", `duplicate worktreePath "${track.worktreePath}" across parallel tracks — L2 parallel-writable isolation requires a distinct absolute Worktree path per track (N parallel invokes ≠ isolation)`, "give every parallel track its own git worktree checkout"));
-      return;
-    }
-    seenPaths.add(normalized);
-    if (!existsSync4(track.worktreePath)) {
-      violations.push(violation5("high", "worktree.l2.track-missing", `track worktree directory "${track.worktreePath}" does not exist`, `create it before dispatch: git worktree add ${track.worktreePath} ${track.workingBranch}`));
-      return;
-    }
-    const probe = probeBranch(track.worktreePath, opts);
-    if ("error" in probe) {
-      violations.push(violation5("high", "worktree.l2.branch-probe-failed", `cannot probe branch at "${track.worktreePath}": ${probe.error}`, "verify the path is a git worktree checkout on its Working branch (not detached)"));
-    } else if (probe.branch !== track.workingBranch) {
-      violations.push(violation5("high", "worktree.l2.branch-mismatch", `track worktree "${track.worktreePath}" is on branch "${probe.branch}", expected Working branch "${track.workingBranch}"`, `checkout ${track.workingBranch} in that worktree`));
+  if (doc.residuals_ref !== undefined && doc.residuals_ref !== null) {
+    if (typeof doc.residuals_ref !== "string" || doc.residuals_ref.trim() === "") {
+      violations.push(violation6("medium", "project.roadmap.invalid-residuals-ref", "residuals_ref must be a non-empty string"));
     }
-  });
-  return gate(violations);
-}
-function assertControlVsFeaturePath(controlWorktreePath, featureWorktreePath) {
-  const violations = [];
-  const samePath = controlWorktreePath === "" && featureWorktreePath === "" || controlWorktreePath !== "" && featureWorktreePath !== "" && resolve6(controlWorktreePath) === resolve6(featureWorktreePath);
-  if (samePath) {
-    violations.push(violation5("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"));
   }
-  return gate(violations);
-}
-function assertBranchAlignment(worktreePath, expectedBranch, opts = {}) {
-  const violations = [];
-  const probe = probeBranch(worktreePath, opts);
-  if ("error" in probe) {
-    violations.push(violation5("high", "worktree.branch-probe-failed", `cannot probe branch at "${worktreePath}": ${probe.error}`, "verify the path is a git worktree checkout on the expected branch (not detached)"));
-  } else if (probe.branch !== expectedBranch) {
-    violations.push(violation5("high", "worktree.branch-mismatch", `worktree "${worktreePath}" is on branch "${probe.branch}", expected "${expectedBranch}" (Assignment Working branch)`, `checkout ${expectedBranch} in that worktree`));
+  const warnings = [];
+  const fenceEnd = linesIndexOfClosingFence(content);
+  const body = content.split(/\r?\n/).slice(fenceEnd + 1).join(`
+`);
+  if (!/^##\s+Direction\s*$/m.test(body)) {
+    warnings.push(violation6("low", "project.roadmap.body.missing-direction", "roadmap body has no `## Direction` section (documented body convention) — state the project direction there"));
   }
-  return gate(violations);
+  if (!/^\s*[-*]\s+\[[xX ]\]/m.test(body)) {
+    warnings.push(violation6("low", "project.roadmap.body.no-goal-items", "roadmap body has no goal-item task list (documented body convention) — list goals as `- [ ]` / `- [x]` markdown task items"));
+  }
+  return { ok: violations.length === 0, violations, warnings };
 }
-var QC_ALIGNMENT_FIELDS = [
-  { key: "planId", label: "plan_id" },
-  { key: "reviewRange", label: "Review range" },
-  { key: "diffBasis", label: "Diff basis" }
-];
-function assertQcAlignment(assignments) {
+function linesIndexOfClosingFence(content) {
+  return content.split(/\r?\n/).indexOf("---", 1);
+}
+function validateProjectRegister(doc) {
   const violations = [];
-  const list = assignments ?? [];
-  for (const { key, label } of QC_ALIGNMENT_FIELDS) {
-    const distinct = [...new Set(list.map((a) => a[key]))];
-    if (distinct.length > 1) {
-      violations.push(violation5("high", "qc.alignment.mismatch", `QC/QA alignment field "${label}" is not byte-identical across ${list.length} assignments: ${distinct.map((v) => `"${v}"`).join(" vs ")}`, `copy the same ${label} value verbatim into every QC tri and QA Assignment`));
+  if (!isPlainObject5(doc)) {
+    return {
+      ok: false,
+      violations: [violation6("high", "project.register.invalid", "project register must be an object")]
+    };
+  }
+  if (doc.entries === undefined) {
+    violations.push(violation6("high", "project.register.missing-entries", "missing required field: entries"));
+  } else if (!isPlainObject5(doc.entries)) {
+    violations.push(violation6("high", "project.register.invalid-entries", "entries must be an object keyed by plan id"));
+  } else {
+    for (const [key, entries] of Object.entries(doc.entries)) {
+      if (key.trim() === "") {
+        violations.push(violation6("medium", "project.register.invalid-key", "entries keys must be non-empty plan ids"));
+      }
+      if (!Array.isArray(entries)) {
+        violations.push(violation6("high", "project.register.invalid-entry-list", `entries[${JSON.stringify(key)}] must be an array of residual entries (one entry per residual; v1 multi-finding semantics)`));
+        continue;
+      }
+      for (const entry of entries) {
+        violations.push(...validateResidual(entry).violations);
+        if (!isPlainObject5(entry))
+          continue;
+        validateNonEmptyString4(violations, entry.source_plan, "source_plan", "project.register.missing-source-plan", "project.register.invalid-source-plan");
+        if (entry.registered_at === undefined) {
+          violations.push(violation6("high", "project.register.missing-registered-at", "missing required field: registered_at"));
+        } else if (typeof entry.registered_at !== "string" || !DATE_RE3.test(entry.registered_at)) {
+          violations.push(violation6("medium", "project.register.invalid-registered-at", "registered_at must be YYYY-MM-DD"));
+        }
+        if (entry.lifecycle_id !== undefined && (typeof entry.lifecycle_id !== "string" || entry.lifecycle_id.trim() === "")) {
+          violations.push(violation6("medium", "project.register.invalid-lifecycle-id", "lifecycle_id must be a non-empty string"));
+        }
+        if (typeof entry.source_plan === "string" && entry.source_plan.trim() !== "" && entry.source_plan !== key) {
+          violations.push(violation6("medium", "project.register.mismatched-source-plan", `source_plan ${JSON.stringify(entry.source_plan)} does not match the entries key ${JSON.stringify(key)} — entries are keyed by plan id`));
+        }
+      }
     }
   }
-  return gate(violations);
+  return { ok: violations.length === 0, violations };
 }
-function singleReviewSnapshot(assignments) {
+function findingsCleanupGate(register, planId, opts) {
+  const mode = opts?.mode ?? "allow-residual";
   const violations = [];
-  const list = assignments ?? [];
-  list.forEach((a, index) => {
-    if ((a.head ?? "").trim() === "") {
-      violations.push(violation5("high", "qc.alignment.snapshot-missing", `review head not provided for assignment ${index + 1} (plan_id "${a.planId}") — cannot confirm the single review snapshot precondition`, "precompute and pass the review HEAD (full SHA) for every assignment"));
-    }
-  });
-  const distinct = [...new Set(list.map((a) => a.head ?? "").filter((h) => h.trim() !== ""))];
-  if (distinct.length > 1) {
-    violations.push(violation5("high", "qc.alignment.single-snapshot", `assignments cover ${distinct.length} different review heads (${distinct.join(", ")}) — all reviewable commits must sit on ONE Working branch HEAD before QC tri + QA`, "merge the parallel tracks to a single Working branch HEAD, then re-derive the heads"));
+  const entries = isPlainObject5(register.entries) ? register.entries[planId] : undefined;
+  if (entries === undefined) {
+    return { ok: true, violations };
   }
-  return gate(violations);
-}
-// src/sdd.ts
-import { execFileSync as execFileSync3 } from "node:child_process";
-import { mkdirSync as mkdirSync5, readdirSync as readdirSync3, readFileSync as readFileSync5, realpathSync as realpathSync3, statSync as statSync4, writeFileSync as writeFileSync3 } from "node:fs";
-import { basename as basename3, dirname as dirname6, isAbsolute as isAbsolute5, join as join7, resolve as resolve7 } from "node:path";
-class SddScriptError extends Error {
-  exitCode;
-  constructor(message, exitCode) {
-    super(message);
-    this.name = "SddScriptError";
-    this.exitCode = exitCode;
+  if (!Array.isArray(entries)) {
+    violations.push(violation6("high", "project.register.invalid-entry-list", `entries[${JSON.stringify(planId)}] must be an array of residual entries (one entry per residual; v1 multi-finding semantics)`));
+    return { ok: false, violations };
   }
-}
-function isDirectory2(dir) {
-  try {
-    return statSync4(dir).isDirectory();
-  } catch {
-    return false;
+  if (entries.length === 0) {
+    return { ok: true, violations };
   }
-}
-function isFile2(file) {
-  try {
-    return statSync4(file).isFile();
-  } catch {
-    return false;
+  for (const entry of entries) {
+    if (!isOpenResidual(entry))
+      continue;
+    const id = typeof entry.id === "string" ? entry.id : "<unnamed>";
+    const label = `R#${id}`;
+    if (mode === "zero-residual") {
+      if (entry.severity === "nit") {
+        violations.push(violation6("medium", "findings.zero-residual-nit", `${label}: style-only nits must be fixed in-session or dropped — never left open under zero-residual`));
+      } else if (entry.decision === "risk-accepted" || entry.lifecycle === "waived") {
+        violations.push(violation6("medium", "findings.zero-residual-risk-accepted", `${label}: waived/risk-accepted findings must be closed/archived, not left open under zero-residual`));
+      } else if (entry.decision === "defer") {
+        if (typeof entry.target !== "string" || entry.target.trim() === "") {
+          violations.push(violation6("medium", "findings.zero-residual-defer-no-target", `${label}: blocker-defer requires a target (next iteration/milestone) under zero-residual`));
+        }
+      } else {
+        violations.push(violation6("medium", "findings.zero-residual-open-fixable", `${label}: fixable finding must not remain open under zero-residual — fix now or convert to a blocker-defer`));
+      }
+    } else if (normalizeSeverity(entry.severity) === "critical") {
+      violations.push(violation6("high", "findings.allow-residual-critical", `${label}: unresolved critical blocks Approve with residuals`));
+    }
   }
+  return { ok: violations.length === 0, violations };
 }
-var GIT_CAPTURE_MAX_BYTES = 64 * 1024 * 1024;
-function gitOut(cwd, args) {
-  try {
-    return execFileSync3("git", args, {
-      cwd,
-      encoding: "utf8",
-      stdio: ["ignore", "pipe", "pipe"],
-      maxBuffer: GIT_CAPTURE_MAX_BYTES
-    }).trim();
-  } catch {
-    return null;
+function groupCount(values) {
+  const counts = new Map;
+  for (const value of values) {
+    const key = typeof value === "string" ? value : String(value);
+    counts.set(key, (counts.get(key) ?? 0) + 1);
   }
+  return Object.fromEntries([...counts.entries()].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0));
 }
-function probeHarnessWithStatus(root) {
-  if (isFile2(join7(root, ".mstar", "status.json")))
-    return join7(root, ".mstar");
-  if (isFile2(join7(root, ".agents", "status.json")))
-    return join7(root, ".agents");
-  if (hasWorkflowSnapshot(join7(root, ".mstar")))
-    return join7(root, ".mstar");
-  if (hasWorkflowSnapshot(join7(root, ".agents")))
-    return join7(root, ".agents");
-  return null;
-}
-function hasWorkflowSnapshot(harnessDir) {
-  let workflowsDir;
+function techDebtRollup(projectDir) {
+  const items = [];
+  let entries;
   try {
-    workflowsDir = resolveWorkflowDir(harnessDir, { harnessDir });
+    entries = readdirSync3(projectDir, { withFileTypes: true });
   } catch {
-    workflowsDir = join7(harnessDir, "workflows");
+    entries = [];
   }
-  if (!isDirectory2(workflowsDir))
-    return false;
-  try {
-    for (const entry of readdirSync3(workflowsDir, { withFileTypes: true })) {
-      if (entry.isDirectory() && isFile2(join7(workflowsDir, entry.name, "snapshot.json")))
-        return true;
+  for (const project of entries) {
+    if (!project.isDirectory())
+      continue;
+    const registerPath = join7(projectDir, project.name, PROJECT_REGISTER_FILE);
+    if (!existsSync4(registerPath))
+      continue;
+    let register;
+    try {
+      register = readJson(registerPath);
+    } catch {
+      continue;
+    }
+    if (!isPlainObject5(register) || !isPlainObject5(register.entries))
+      continue;
+    for (const [plan, planEntries] of Object.entries(register.entries)) {
+      if (!Array.isArray(planEntries))
+        continue;
+      for (const entry of planEntries) {
+        if (!isPlainObject5(entry) || !isOpenResidual(entry))
+          continue;
+        items.push({ plan, entry });
+      }
     }
-  } catch {
-    return false;
   }
-  return false;
+  const bySeverity = {};
+  for (const severity of SEVERITY_ORDER) {
+    bySeverity[severity] = items.filter(({ entry }) => normalizeSeverity(entry.severity) === severity).length;
+  }
+  const computed = {
+    total_open: items.length,
+    by_severity: bySeverity,
+    by_target: groupCount(items.map(({ entry }) => entry.target ?? "unspecified")),
+    by_plan: groupCount(items.map(({ plan }) => plan))
+  };
+  const stored = null;
+  const checks = ROLLUP_FIELDS.map((field) => ({ field, status: "DRIFT" }));
+  const overall = "DRIFT";
+  return { computed, stored, checks, overall };
 }
-function isLinkedWorktree(root) {
-  const gitDirRaw = gitOut(root, ["rev-parse", "--git-dir"]);
-  const commonRaw = gitOut(root, ["rev-parse", "--git-common-dir"]);
-  if (gitDirRaw === null || commonRaw === null)
-    return false;
-  const gitDir = isAbsolute5(gitDirRaw) ? gitDirRaw : join7(root, gitDirRaw);
-  const common = isAbsolute5(commonRaw) ? commonRaw : join7(root, commonRaw);
-  if (gitDir.includes("/.git/worktrees/") || gitDir.includes("/worktrees/"))
-    return true;
+function listProjectReferenceFiles(projectDir) {
+  const root = join7(projectDir, PROJECT_REFERENCES_DIR);
+  let entries;
   try {
-    const gdParent = realpathSync3(dirname6(gitDir));
-    const cmAbs = realpathSync3(common);
-    return join7(gdParent, basename3(gitDir)) !== cmAbs && gitDir !== cmAbs;
+    entries = readdirSync3(root, { withFileTypes: true });
   } catch {
-    return false;
-  }
-}
-function sddWorkspace(planId, opts = {}) {
-  if (!planId) {
-    throw new SddScriptError(`usage: mstar sdd workspace PLAN_ID [CONTROL_ROOT]
-` + "  Set MSTAR_CONTROL_ROOT=<control_worktree_path> when running from a feature worktree.", 2);
-  }
-  const cwd = opts.cwd ?? process.cwd();
-  const controlRoot = opts.controlRoot ?? (process.env.MSTAR_CONTROL_ROOT || undefined);
-  let root;
-  if (controlRoot) {
-    if (!isDirectory2(controlRoot)) {
-      throw new SddScriptError(`mstar sdd workspace: CONTROL_ROOT / MSTAR_CONTROL_ROOT is not a directory: ${controlRoot}`, 1);
-    }
-    root = realpathSync3(controlRoot);
-  } else {
-    const topLevel = gitOut(cwd, ["rev-parse", "--show-toplevel"]);
-    root = realpathSync3(topLevel ?? cwd);
-  }
-  if (!controlRoot && isLinkedWorktree(root)) {
-    throw new SddScriptError(`mstar sdd workspace: linked worktree at ${root} has no {HARNESS_DIR}/status.json (default gitignore).
-` + `  Refusing to create a second SDD tree under the feature checkout.
-` + `  Re-run with MSTAR_CONTROL_ROOT=<control_worktree_path> or: mstar sdd workspace ${planId} <control_worktree_path>
-` + `  See mstar-branch-worktree «Harness path SSOT under default gitignore».`, 1);
+    return [];
   }
-  const harnessOverride = opts.harnessDir ?? (process.env.MSTAR_HARNESS_DIR || undefined);
-  let harnessDir;
-  if (harnessOverride) {
-    harnessDir = resolve7(root, harnessOverride);
-  } else {
-    const rc = findMstarc(root, root);
-    const rcHarnessDir = rc !== null ? parseMstarc(readFileSync5(rc, "utf8")).harnessDir : undefined;
-    if (rcHarnessDir) {
-      harnessDir = resolve7(rc !== null ? dirname6(rc) : root, rcHarnessDir);
-    } else {
-      const probed = probeHarnessWithStatus(root);
-      if (probed) {
-        harnessDir = probed;
-      } else if (isDirectory2(join7(root, ".mstar"))) {
-        harnessDir = join7(root, ".mstar");
-      } else if (isDirectory2(join7(root, ".agents"))) {
-        harnessDir = join7(root, ".agents");
-      } else {
-        harnessDir = join7(root, ".mstar");
+  const files = [];
+  for (const entry of entries) {
+    if (entry.name === PROJECT_ROADMAP_FILE || entry.name === PROJECT_REGISTER_FILE)
+      continue;
+    if (entry.isFile()) {
+      files.push(entry.name);
+    } else if (entry.isDirectory()) {
+      let nested;
+      try {
+        nested = readdirSync3(join7(root, entry.name), { withFileTypes: true });
+      } catch {
+        continue;
+      }
+      for (const child of nested) {
+        if (child.isFile())
+          files.push(`${entry.name}/${child.name}`);
       }
     }
   }
-  const sddDir = resolveSddDir(harnessDir, planId);
-  mkdirSync5(sddDir, { recursive: true });
-  writeFileSync3(join7(sddDir, ".gitignore"), `*
-`);
-  return realpathSync3(sddDir);
+  return files.sort();
 }
-function taskBrief(planFile, taskN, outFile, opts = {}) {
-  if (!planFile || !Number.isInteger(taskN) || taskN < 1) {
-    throw new SddScriptError("usage: mstar sdd task-brief PLAN_FILE TASK_NUMBER [OUTFILE]", 2);
-  }
-  let content;
-  try {
-    content = readFileSync5(planFile, "utf8");
-  } catch {
-    throw new SddScriptError(`no such plan file: ${planFile}`, 2);
-  }
-  let out;
-  if (outFile) {
-    out = outFile;
-  } else {
-    const sddDir = opts.sddDir ?? process.env.SDD_DIR;
-    if (!sddDir) {
-      throw new SddScriptError("mstar sdd task-brief: set SDD_DIR or pass OUTFILE (run mstar sdd workspace PLAN_ID first)", 2);
+
+// src/path.ts
+function resolveHarnessDir(startDir = process.cwd(), opts = {}) {
+  const start = resolve5(startDir);
+  const explicit = opts.harnessDir ?? process.env.MSTAR_HARNESS_DIR;
+  if (explicit)
+    return resolve5(start, explicit);
+  const boundary = resolve5(start, opts.workspaceRoot ?? defaultWorkspaceRoot(start));
+  const rc = loadMstarc(start, boundary);
+  if (rc !== null && rc.config.harnessDir)
+    return resolve5(rc.dir, rc.config.harnessDir);
+  let dir = start;
+  for (;; ) {
+    if (!isAtOrBelow2(dir, boundary))
+      return null;
+    for (const candidate of [join8(dir, ".mstar"), join8(dir, ".agents"), join8(dir, ".plans"), join8(dir, "plans")]) {
+      if (isDirectory(candidate))
+        return candidate;
     }
-    mkdirSync5(sddDir, { recursive: true });
-    out = join7(sddDir, `task-${taskN}-brief.md`);
-  }
-  const records = content.endsWith(`
-`) ? content.split(`
-`).slice(0, -1) : content.split(`
-`);
-  const headingRe = /^#+[ \t]+Task[ \t]+[0-9]+/;
-  const targetRe = new RegExp(`^#+[ 	]+Task[ 	]+${taskN}([^0-9]|$)`);
-  let infence = false;
-  let intask = false;
-  const printed = [];
-  for (const line of records) {
-    if (/^```/.test(line))
-      infence = !infence;
-    if (!infence && headingRe.test(line))
-      intask = targetRe.test(line);
-    if (intask)
-      printed.push(line);
-  }
-  const output = printed.length > 0 ? `${printed.join(`
-`)}
-` : "";
-  writeFileSync3(out, output);
-  if (printed.length === 0) {
-    throw new SddScriptError(`task ${taskN} not found in ${planFile} (no heading matching Task ${taskN})`, 3);
+    if (dir === boundary)
+      return null;
+    const parent = dirname5(dir);
+    if (parent === dir)
+      return null;
+    dir = parent;
   }
-  return out;
 }
-function reviewPackage(base, head, outFile, opts = {}) {
-  if (!base || !head) {
-    throw new SddScriptError("usage: mstar sdd review-package BASE HEAD [OUTFILE]", 2);
-  }
-  const cwd = opts.cwd ?? process.cwd();
-  const verifyRef = (ref, what) => {
-    try {
-      execFileSync3("git", ["rev-parse", "--verify", "--quiet", ref], { cwd, stdio: ["ignore", "pipe", "pipe"] });
-    } catch {
-      throw new SddScriptError(`bad ${what}: ${ref}`, 2);
-    }
-  };
-  verifyRef(base, "BASE");
-  verifyRef(head, "HEAD");
-  let out;
-  if (outFile) {
-    out = outFile;
-  } else {
-    const sddDir = opts.sddDir ?? process.env.SDD_DIR;
-    if (!sddDir) {
-      throw new SddScriptError("mstar sdd review-package: set SDD_DIR or pass OUTFILE", 2);
+function defaultWorkspaceRoot(startDir) {
+  try {
+    const cdup = execFileSync("git", ["rev-parse", "--show-cdup"], {
+      cwd: startDir,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+    if (!cdup)
+      return startDir;
+    let boundary = startDir;
+    for (const segment of cdup.split(/[\\/]/)) {
+      if (segment && segment !== ".")
+        boundary = dirname5(boundary);
     }
-    mkdirSync5(sddDir, { recursive: true });
-    const shortBase = gitOut(cwd, ["rev-parse", "--short", base]) ?? base;
-    const shortHead = gitOut(cwd, ["rev-parse", "--short", head]) ?? head;
-    out = join7(sddDir, `review-${shortBase}..${shortHead}.diff`);
+    return resolve5(boundary);
+  } catch {}
+  return startDir;
+}
+function isAtOrBelow2(dir, root) {
+  const rel = relative2(root, dir);
+  return rel === "" || !rel.startsWith("..") && !isAbsolute3(rel);
+}
+function mstarcDirOverride(harnessDir, key) {
+  const dir = resolve5(harnessDir);
+  const rc = loadMstarc(dir, dirname5(dir));
+  const declared = rc?.config[key];
+  return declared ? resolve5(rc.dir, declared) : null;
+}
+function resolveSpecsDir(harnessDir, opts = {}) {
+  const declared = mstarcDirOverride(harnessDir, "specsDir");
+  if (declared !== null) {
+    if (opts.create !== false)
+      mkdirSync4(declared, { recursive: true });
+    return declared;
   }
-  const run = (args) => execFileSync3("git", args, { cwd, maxBuffer: GIT_CAPTURE_MAX_BYTES });
-  const parts = [
-    Buffer.from(`# Review package: ${base}..${head}
-
-## Commits
-`),
-    run(["log", "--oneline", `${base}..${head}`]),
-    Buffer.from(`
-## Files changed
-`),
-    run(["diff", "--stat", `${base}..${head}`]),
-    Buffer.from(`
-## Diff
-`),
-    run(["diff", "-U10", `${base}..${head}`])
+  const harness = resolve5(harnessDir);
+  const repoRoot = dirname5(harness);
+  const candidates = [
+    join8(harness, "specs"),
+    join8(repoRoot, "docs", "specs"),
+    join8(repoRoot, "specs"),
+    join8(harness, "designs"),
+    join8(repoRoot, "designs")
   ];
-  writeFileSync3(out, Buffer.concat(parts));
-  return out;
-}
-function assertBaseSha(ref, opts = {}) {
-  if (typeof ref !== "string" || !/^[0-9a-f]{4,40}$/i.test(ref)) {
-    throw new SddScriptError(`assertBaseSha: BASE must be a commit SHA (full or prefix); got ${JSON.stringify(ref)}. ` + "Never use HEAD~1 as review BASE (multi-commit tasks truncate).", 2);
+  for (const candidate of candidates) {
+    if (isDirectory(candidate) && hasFiles(candidate))
+      return candidate;
   }
-  try {
-    execFileSync3("git", ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`], {
-      cwd: opts.cwd,
-      stdio: ["ignore", "pipe", "pipe"]
-    });
-  } catch {
-    throw new SddScriptError(`assertBaseSha: commit not found: ${ref}`, 2);
+  const fallback = join8(harness, "specs");
+  if (opts.create !== false)
+    mkdirSync4(fallback, { recursive: true });
+  return fallback;
+}
+function resolvePlanDir(harnessDir) {
+  const declared = mstarcDirOverride(harnessDir, "planDir");
+  if (declared !== null)
+    return declared;
+  const dir = resolve5(harnessDir);
+  const name = basename2(dir);
+  if (name === ".plans" || name === "plans")
+    return dir;
+  return join8(dir, "plans");
+}
+function assertSafePathComponent(value, what) {
+  if (value === "" || value === "." || value === ".." || !/^[A-Za-z0-9._-]+$/.test(value)) {
+    throw new Error(`${what} must be a single safe path component ([A-Za-z0-9._-]+; not "", ".", "..", or containing "/" or "\\") — got ${JSON.stringify(value)}`);
   }
 }
-function taskReportExists(sddDir, taskN) {
-  try {
-    const st = statSync4(join7(sddDir, `task-${taskN}-report.md`));
-    return st.isFile() && st.size > 0;
-  } catch {
-    return false;
+function resolveSddDir(harnessDir, planId) {
+  assertSafePathComponent(planId, "planId");
+  const base = resolve5(harnessDir);
+  const declared = mstarcDirOverride(base, "sddDir");
+  const sddBase = declared !== null ? declared : join8(base, "sdd");
+  return join8(sddBase, planId);
+}
+function resolveIterationDir(harnessDir) {
+  const declared = mstarcDirOverride(harnessDir, "iterationDir");
+  if (declared !== null)
+    return declared;
+  return join8(resolve5(harnessDir), "iterations");
+}
+function resolveKnowledgeDir(harnessDir) {
+  const declared = mstarcDirOverride(harnessDir, "knowledgeDir");
+  if (declared !== null)
+    return declared;
+  return join8(resolve5(harnessDir), "knowledge");
+}
+function resolveHarnessSubdir(startDir, opts, key, fallback) {
+  const harness = resolveHarnessDir(startDir, opts);
+  if (harness === null) {
+    throw new Error(`harness dir not found from ${resolve5(startDir)} — cannot resolve the ${fallback} dir (run \`mstar harness scaffold\`, pass opts.harnessDir, or set MSTAR_HARNESS_DIR)`);
   }
+  const declared = mstarcDirOverride(harness, key);
+  return declared !== null ? declared : join8(resolve5(harness), fallback);
 }
-function readProgressLedger(sddDir) {
+function resolveWorkflowDir(startDir = process.cwd(), opts = {}) {
+  return resolveHarnessSubdir(startDir, opts, "workflowDir", "workflows");
+}
+function resolveProjectDir(startDir = process.cwd(), opts = {}) {
+  return resolveHarnessSubdir(startDir, opts, "projectDir", "projects");
+}
+var EMPTY_STATUS_TEMPLATE = {
+  version: 2,
+  updated_at: "1970-01-01",
+  workflows: []
+};
+var SCAFFOLD_DIRS = ["plans", "iterations", "knowledge", "specs", "sdd"];
+function resolveScaffoldDirs(root) {
+  const start = resolve5(root);
+  const boundary = resolve5(start, defaultWorkspaceRoot(start));
+  const rc = loadMstarc(start, boundary);
+  const explicit = process.env.MSTAR_HARNESS_DIR;
+  const harnessDir = explicit ? resolve5(start, explicit) : rc !== null && rc.config.harnessDir ? resolve5(rc.dir, rc.config.harnessDir) : join8(start, ".mstar");
+  const declaredProjectDir = mstarcDirOverride(harnessDir, "projectDir");
+  const projectDir = declaredProjectDir !== null ? declaredProjectDir : join8(harnessDir, "projects");
+  return { harnessDir, projectDir };
+}
+var ROADMAP_TEMPLATE = `---
+project_id: _default
+title: Default Project
+status: active
+created_at: {created_at}
+---
+
+# Roadmap
+
+## Direction
+
+State the project direction here.
+`;
+var EMPTY_REGISTER_TEMPLATE = {
+  entries: {}
+};
+function scaffoldHarness(root) {
+  const { harnessDir, projectDir } = resolveScaffoldDirs(root);
+  for (const dir of SCAFFOLD_DIRS)
+    mkdirSync4(join8(harnessDir, dir), { recursive: true });
+  const statusPath = join8(harnessDir, "status.json");
+  if (Object.keys(readJson(statusPath)).length === 0)
+    writeJson(statusPath, EMPTY_STATUS_TEMPLATE);
+  const defaultProjectDir = join8(projectDir, _DEFAULT_PROJECT);
+  mkdirSync4(defaultProjectDir, { recursive: true });
+  const roadmapPath = join8(defaultProjectDir, PROJECT_ROADMAP_FILE);
+  if (!existsSync5(roadmapPath)) {
+    const created = new Date().toISOString().slice(0, 10);
+    writeFileSync3(roadmapPath, ROADMAP_TEMPLATE.replace("{created_at}", created), "utf8");
+  }
+  const registerPath = join8(defaultProjectDir, PROJECT_REGISTER_FILE);
+  if (Object.keys(readJson(registerPath)).length === 0)
+    writeJson(registerPath, EMPTY_REGISTER_TEMPLATE);
+  return harnessDir;
+}
+var GITIGNORE_SNIPPET = `# Morning Star harness (.mstar/)
+# Principle: process stays local; results are shared with the team.
+# Default-ignore everything under .mstar/, then re-include the tracked results.
+.mstar/**
+!.mstar/AGENTS.md
+!.mstar/knowledge/
+!.mstar/knowledge/**
+!.mstar/specs/
+!.mstar/specs/**
+# .mstarc — repo-local harness config (may declare [config] harness_dir=<name>)
+.mstarc
+`;
+var GITIGNORE_SNIPPET_AGENTS = `# Morning Star harness (.agents/) — legacy
+# Default-ignore everything under .agents/, then re-include the tracked results.
+.agents/**
+!.agents/AGENTS.md
+!.agents/knowledge/
+!.agents/knowledge/**
+!.agents/specs/
+!.agents/specs/**
+`;
+var GITIGNORE_PROCESS_ENTRIES = GITIGNORE_SNIPPET.split(`
+`).filter((line) => line.startsWith(".mstar/") || line.startsWith("!.mstar/")).map((line) => line.trim());
+var GITIGNORE_PROCESS_ENTRIES_AGENTS = GITIGNORE_SNIPPET_AGENTS.split(`
+`).filter((line) => line.startsWith(".agents/") || line.startsWith("!.agents/")).map((line) => line.trim());
+function emitGitignoreSnippet(kind) {
+  if (kind === "agents")
+    return GITIGNORE_SNIPPET_AGENTS;
+  if (kind === "mstar")
+    return GITIGNORE_SNIPPET;
+  return `${GITIGNORE_SNIPPET}${GITIGNORE_SNIPPET_AGENTS}`;
+}
+function validateGitignore(root) {
+  const gitignorePath = join8(resolve5(root), ".gitignore");
+  const kind = detectHarnessKind(resolveHarnessDir(root));
   let content;
   try {
-    content = readFileSync5(join7(sddDir, "progress.md"), "utf8");
+    content = readFileSync6(gitignorePath, "utf8");
   } catch {
-    return [];
-  }
-  return content.split(`
-`).map((line) => line.trim()).filter((line) => line.length > 0);
-}
-function implementerSessionStickyRules(input) {
-  const { session, nextTask, microBatchTasks = 1 } = input;
-  if (session.session_mode !== "sticky") {
-    return { resume: false, reason: `session_mode is '${session.session_mode}'; sticky resume requires 'sticky'` };
-  }
-  if (typeof session.host_agent_id !== "string" || session.host_agent_id.length === 0) {
-    return {
-      resume: false,
-      reason: "host_agent_id is missing from implementer-session.json; fall back to fresh for this task " + "(mstar-sdd SKILL.md red flag: resume implementer without host_agent_id)"
-    };
-  }
-  if (nextTask <= session.last_task) {
-    return {
-      resume: false,
-      reason: `nextTask ${nextTask} <= last_task ${session.last_task}; task already completed in this session`
-    };
-  }
-  if (microBatchTasks < 1 || microBatchTasks > 3) {
     return {
-      resume: false,
-      reason: `micro-batch of ${microBatchTasks} tasks is outside 1..3 (max 3 without user override, ` + "sticky-implementer-session.md § Micro-batch fallback)"
+      ok: false,
+      severity: "medium",
+      code: "gitignore.missing",
+      message: `no .gitignore found at ${gitignorePath}`,
+      fix: `append the canonical snippet (emitGitignoreSnippet(${kind ? `"${kind}"` : ""})) to ${gitignorePath}`
     };
   }
-  return { resume: true, reason: `sticky resume OK: host_agent_id ${session.host_agent_id}, next task ${nextTask}` };
-}
-// src/iteration.ts
-import { existsSync as existsSync5, readdirSync as readdirSync4, readFileSync as readFileSync6 } from "node:fs";
-import { join as join8 } from "node:path";
-var COMPASS_STATUSES = ["active", "locked", "completed"];
-var DATE_RE2 = /^\d{4}-\d{2}-\d{2}$/;
-var PLAN_STATUS_DONE = "Done";
-var COMPASS_FILE = "delivery-compass.md";
-var INDEX_README = "README.md";
-var INDEX_HEADER = "| Iteration | Path | Description | Status |";
-function typeName(value) {
-  if (value === null)
-    return "null";
-  if (Array.isArray(value))
-    return "array";
-  return typeof value;
-}
-function validateCompassShape(doc) {
-  const issues = [];
-  const expectString = (key, opts = {}) => {
-    const value = doc[key];
-    if (typeof value !== "string") {
-      issues.push({ path: [key], message: `expected string, received ${typeName(value)}` });
-      return;
-    }
-    if (opts.min !== undefined && value.length < opts.min) {
-      issues.push({ path: [key], message: `string must contain at least ${opts.min} character(s)` });
-      return;
-    }
-    if (opts.regex !== undefined && !opts.regex.test(value)) {
-      issues.push({ path: [key], message: `string must match ${opts.regex}` });
-    }
-  };
-  expectString("iteration_id", { min: 1 });
-  expectString("start_date", { regex: DATE_RE2 });
-  const status = doc.status;
-  if (typeof status !== "string" || !COMPASS_STATUSES.includes(status)) {
-    issues.push({
-      path: ["status"],
-      message: `expected one of ${COMPASS_STATUSES.map((s) => `'${s}'`).join(" | ")}, received ${typeName(status)}`
-    });
-  }
-  expectString("iteration_base_branch", { min: 1 });
-  expectString("target_branch", { min: 1 });
-  const plans = doc.plans;
-  if (plans !== undefined) {
-    if (!Array.isArray(plans)) {
-      issues.push({ path: ["plans"], message: `expected array, received ${typeName(plans)}` });
-    } else {
-      plans.forEach((entry, index) => {
-        if (typeof entry !== "string") {
-          issues.push({ path: ["plans", index], message: `expected string, received ${typeName(entry)}` });
-        } else if (entry.length < 1) {
-          issues.push({ path: ["plans", index], message: "string must contain at least 1 character(s)" });
-        }
-      });
-    }
+  const lines = new Set(content.split(/\r?\n/).map((line) => line.trim()).filter((line) => line.length > 0));
+  const mstarMissing = GITIGNORE_PROCESS_ENTRIES.filter((entry) => !lines.has(entry));
+  const agentsMissing = GITIGNORE_PROCESS_ENTRIES_AGENTS.filter((entry) => !lines.has(entry));
+  let missing;
+  let label;
+  if (kind === "agents") {
+    missing = agentsMissing;
+    label = ".agents/ set";
+  } else if (kind === "mstar") {
+    missing = mstarMissing;
+    label = ".mstar/ set";
+  } else {
+    label = "either .mstar/ or .agents/ set";
+    missing = mstarMissing.length === 0 || agentsMissing.length === 0 ? [] : mstarMissing.length <= agentsMissing.length ? mstarMissing : agentsMissing;
   }
-  const end_date = doc.end_date;
-  if (end_date !== undefined) {
-    if (typeof end_date !== "string") {
-      issues.push({ path: ["end_date"], message: `expected string, received ${typeName(end_date)}` });
-    } else if (!DATE_RE2.test(end_date)) {
-      issues.push({ path: ["end_date"], message: `string must match ${DATE_RE2}` });
-    }
+  if (missing.length > 0) {
+    return {
+      ok: false,
+      severity: "medium",
+      code: "gitignore.missing-entries",
+      message: `.gitignore at ${gitignorePath} is missing canonical harness ignore entries (${label}): ${missing.join(", ")}`,
+      fix: `append the canonical snippet (emitGitignoreSnippet(${kind ? `"${kind}"` : ""})) to ${gitignorePath}`
+    };
   }
-  if (issues.length > 0)
-    return { ok: false, issues };
   return {
     ok: true,
-    data: {
-      iteration_id: doc.iteration_id,
-      start_date: doc.start_date,
-      status,
-      iteration_base_branch: doc.iteration_base_branch,
-      target_branch: doc.target_branch,
-      ...plans !== undefined ? { plans } : {},
-      ...end_date !== undefined ? { end_date } : {}
-    }
+    severity: "low",
+    code: "gitignore.ok",
+    message: `.gitignore at ${gitignorePath} contains a complete canonical harness ignore set — default-ignore + tracked re-includes (${label})`
   };
 }
-function violation6(severity, code, message, fix) {
-  return { ok: false, severity, code, message, fix };
-}
-function isPlainObject4(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
+function detectHarnessKind(harnessDir) {
+  if (!harnessDir)
+    return null;
+  const name = basename2(resolve5(harnessDir));
+  if (name === ".mstar")
+    return "mstar";
+  if (name === ".agents")
+    return "agents";
+  return null;
 }
-function validateCompassFrontmatter(doc) {
-  if (!isPlainObject4(doc)) {
+function assertPlanWritingPath(planPath, harnessDir) {
+  const planAbs = resolve5(planPath);
+  if (!harnessDir) {
     return {
       ok: false,
-      violations: [
-        violation6("medium", "COMPASS_INVALID_FIELD", "Compass frontmatter must be a YAML object with iteration_id / start_date / status / iteration_base_branch / target_branch (template: mstar-iteration §1.3)", "Fix the frontmatter of {ITERATION_DIR}/<iteration-id>/delivery-compass.md")
-      ]
+      severity: "high",
+      code: "plan-path.no-harness",
+      message: `persistent plan tracking is not enabled — cannot place plan ${planAbs} under {PLAN_DIR}`,
+      fix: "initialize the harness (scaffoldHarness) so plans land in {PLAN_DIR}"
     };
   }
-  const parsed = validateCompassShape(doc);
-  if (!parsed.ok) {
+  const planDir = resolvePlanDir(harnessDir);
+  const rel = relative2(planDir, planAbs);
+  const inside = rel === "" || !rel.startsWith("..") && !isAbsolute3(rel);
+  if (!inside) {
     return {
       ok: false,
-      violations: parsed.issues.map((issue) => {
-        const field = issue.path.join(".") || "(root)";
-        return violation6("medium", "COMPASS_INVALID_FIELD", `Compass frontmatter field '${field}' is invalid: ${issue.message}`, `Fix '${field}' in {ITERATION_DIR}/<iteration-id>/delivery-compass.md frontmatter (template: mstar-iteration §1.3)`);
-      })
+      severity: "high",
+      code: "plan-path.outside-plan-dir",
+      message: `plan file ${planAbs} is outside {PLAN_DIR} (${planDir})`,
+      fix: `write the plan under ${planDir}`
     };
   }
-  const violations = [];
-  const { status, end_date } = parsed.data;
-  if (status === "completed" && end_date === undefined) {
-    violations.push(violation6("high", "COMPASS_END_DATE_REQUIRED", "Compass frontmatter status is 'completed' but end_date is missing — end_date is required at iteration-close (mstar-iteration §3.4, template Fields guide)", "Add `end_date: YYYY-MM-DD` to the frontmatter"));
-  }
-  if (status !== "completed" && end_date !== undefined) {
-    violations.push(violation6("medium", "COMPASS_END_DATE_NOT_ALLOWED", `Compass frontmatter sets end_date while status is '${status}' — end_date is only written at iteration-close (mstar-iteration §3.4)`, "Remove end_date until iteration-close"));
+  if (existsSync5(planAbs)) {
+    try {
+      const canonicalPlan = realpathSync2(planAbs);
+      const canonicalPlanDir = existsSync5(planDir) ? realpathSync2(planDir) : resolve5(planDir);
+      const canonicalRel = relative2(canonicalPlanDir, canonicalPlan);
+      const canonicalInside = canonicalRel === "" || !canonicalRel.startsWith("..") && !isAbsolute3(canonicalRel);
+      if (!canonicalInside) {
+        return {
+          ok: false,
+          severity: "high",
+          code: "plan-path.symlink-escape",
+          message: `plan file ${planAbs} resolves to ${canonicalPlan}, outside {PLAN_DIR} (${canonicalPlanDir})`,
+          fix: `write the plan under ${planDir}`
+        };
+      }
+    } catch {}
   }
-  return { ok: violations.length === 0, violations };
-}
-function registeredPlanIds(compassDoc) {
-  if (!Array.isArray(compassDoc.plans))
-    return [];
-  return compassDoc.plans.filter((plan) => typeof plan === "string" && plan.length > 0);
+  return {
+    ok: true,
+    severity: "low",
+    code: "plan-path.ok",
+    message: `plan file ${planAbs} lives under {PLAN_DIR} (${planDir})`
+  };
 }
-function findPlanRow(snapshotDoc, planId) {
-  if (!Array.isArray(snapshotDoc.plans))
-    return null;
-  for (const row of snapshotDoc.plans) {
-    if (!isPlainObject4(row))
-      continue;
-    const rowId = typeof row.id === "string" ? row.id : typeof row.plan_id === "string" ? row.plan_id : null;
-    if (rowId === planId)
-      return row;
+function isDirectory(dir) {
+  try {
+    return statSync3(dir).isDirectory();
+  } catch {
+    return false;
   }
-  return null;
 }
-function entryPlansAllDone(snapshotDoc, registered) {
-  const violations = [];
-  if (registered.length === 0) {
-    violations.push(violation6("medium", "COMPASS_NO_PLANS", "Compass frontmatter registers no plans — the all-plans-Done transition cannot be verified (mstar-iteration §1.3 / Phase transition gates)", "List the iteration's plan ids in the compass frontmatter `plans`"));
-    return violations;
-  }
-  for (const planId of registered) {
-    const row = findPlanRow(snapshotDoc, planId);
-    if (row === null) {
-      violations.push(violation6("high", "PLAN_NOT_IN_STATUS", `Plan '${planId}' is registered in the compass frontmatter but has no row in the workflow snapshot plans[] (mstar-iteration §3.1 entry item 1)`, "Add the plan row to {HARNESS_DIR}/workflows/<id>/snapshot.json"));
-      continue;
-    }
-    if (row.status !== PLAN_STATUS_DONE) {
-      violations.push(violation6("high", "PLAN_NOT_DONE", `Plan '${planId}' status is ${JSON.stringify(row.status)} in the workflow snapshot — all compass-registered plans must be 'Done' before iteration-close (mstar-iteration §3.1 entry item 1)`));
+function hasFiles(dir) {
+  try {
+    for (const entry of readdirSync4(dir, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        if (hasFiles(join8(dir, entry.name)))
+          return true;
+      } else if (entry.isFile()) {
+        return true;
+      }
     }
+    return false;
+  } catch {
+    return false;
   }
-  return violations;
 }
-function entryFrontmatterComplete(compassDoc) {
-  return validateCompassFrontmatter(compassDoc).violations;
+// src/worktree.ts
+import { execFileSync as execFileSync2 } from "node:child_process";
+import { existsSync as existsSync6 } from "node:fs";
+import { isAbsolute as isAbsolute4, resolve as resolve6 } from "node:path";
+var DEFAULT_PROBE_TIMEOUT_MS = 1e4;
+function probeTimeoutMs() {
+  const raw = process.env.MSTAR_GIT_PROBE_TIMEOUT_MS;
+  if (raw === undefined || raw.trim() === "")
+    return DEFAULT_PROBE_TIMEOUT_MS;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_PROBE_TIMEOUT_MS;
 }
-function exitFrontmatterClosed(compassDoc) {
-  const violations = [];
-  if (compassDoc.status !== "completed") {
-    violations.push(violation6("high", "EXIT_STATUS_NOT_COMPLETED", `Compass frontmatter status must be 'completed' at close exit — current: ${JSON.stringify(compassDoc.status)} (mstar-iteration §3.4 / §3.5 exit item 4)`));
-  }
-  const endDate = compassDoc.end_date;
-  if (typeof endDate !== "string" || !DATE_RE2.test(endDate)) {
-    violations.push(violation6("high", "EXIT_END_DATE_REQUIRED", "Compass frontmatter end_date (YYYY-MM-DD) is required when closing (mstar-iteration §3.4 / §3.5 exit item 4)"));
-  }
-  return violations;
+function violation7(severity, code, message, fix) {
+  return { ok: false, severity, code, message, fix };
 }
-function exitBranchCheck(opts) {
-  const violations = [];
-  const { currentBranch, specIntegrationBranch } = opts;
-  if (currentBranch === undefined || specIntegrationBranch === undefined) {
-    violations.push(violation6("medium", "EXIT_BRANCH_UNVERIFIABLE", "Cannot verify the current branch is spec_integration_branch — missing currentBranch / specIntegrationBranch probe inputs (mstar-iteration §3.5 exit item 5)"));
-  } else if (currentBranch !== specIntegrationBranch) {
-    violations.push(violation6("high", "EXIT_BRANCH_MISMATCH", `Current branch '${currentBranch}' is not the spec_integration_branch '${specIntegrationBranch}' (mstar-iteration §3.5 exit item 5)`));
-  }
-  return violations;
+function gate(violations) {
+  return { ok: violations.length === 0, violations };
 }
-function exitPrBaseCheck(compassDoc, opts) {
-  const violations = [];
-  const target = compassDoc.target_branch;
-  const { prBaseBranch } = opts;
-  if (prBaseBranch === undefined) {
-    violations.push(violation6("medium", "EXIT_PR_BASE_UNVERIFIABLE", "Cannot verify the PR base — missing prBaseBranch probe input (mstar-iteration §3.5 exit item 6)"));
-  } else if (typeof target !== "string" || prBaseBranch !== target) {
-    violations.push(violation6("high", "EXIT_PR_BASE_MISMATCH", `PR base '${prBaseBranch}' must equal the compass target_branch '${String(target)}' — not an undocumented branch (mstar-iteration §3.5 exit item 6)`));
+function probeBranch(worktreePath, opts) {
+  const precomputed = opts.branchOf?.(worktreePath);
+  if (precomputed !== undefined)
+    return { branch: precomputed };
+  const timeout = opts.timeoutMs ?? probeTimeoutMs();
+  try {
+    const stdout = execFileSync2(opts.gitPath ?? "git", ["-C", worktreePath, "branch", "--show-current"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout
+    });
+    const branch = stdout.trim();
+    if (branch === "")
+      return { error: `no branch checked out (detached HEAD?) at "${worktreePath}"` };
+    return { branch };
+  } 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 };
   }
-  return violations;
-}
-function evaluatePhaseGate(snapshotDoc, compassDoc, opts = {}) {
-  const registered = registeredPlanIds(compassDoc);
-  const entryViolations = [
-    ...entryPlansAllDone(snapshotDoc, registered),
-    ...entryFrontmatterComplete(compassDoc)
-  ];
-  const exitViolations = [
-    ...exitFrontmatterClosed(compassDoc),
-    ...exitBranchCheck(opts),
-    ...exitPrBaseCheck(compassDoc, opts)
-  ];
-  const allPlansDone = registered.length > 0 && registered.every((planId) => {
-    const row = findPlanRow(snapshotDoc, planId);
-    return row !== null && row.status === PLAN_STATUS_DONE;
-  });
-  const entry = { ok: entryViolations.length === 0, violations: entryViolations };
-  const exit = { ok: exitViolations.length === 0, violations: exitViolations };
-  let transition;
-  if (!allPlansDone)
-    transition = "phase-2-execute";
-  else if (entry.ok && exit.ok)
-    transition = "phase-4-pr-delivery";
-  else
-    transition = "phase-3-close";
-  const gateBlocking = allPlansDone ? [...entryViolations, ...exitViolations] : [];
-  return {
-    transition,
-    allPlansDone,
-    entry,
-    exit,
-    ok: gateBlocking.length === 0,
-    violations: gateBlocking
-  };
 }
-function pushCadenceProbe(ciRunning, reviewWaveActive) {
+function l1PreDispatchCheck(input, opts = {}) {
   const violations = [];
-  if (ciRunning) {
-    violations.push(violation6("high", "PUSH_BLOCKED_CI", "CI checks are still queued/in_progress on the current head — do not push until the wave completes (mstar-iteration §5.1a push gate 1)", "Wait for CI to settle, then push once with the whole local batch"));
-  }
-  if (reviewWaveActive) {
-    violations.push(violation6("high", "PUSH_BLOCKED_REVIEW_WAVE", "An AI/bot review wave is still running on the current head — do not push until it settles (mstar-iteration §5.1a push gate 2)", "Wait for the review wave, then push once"));
-  }
-  return { ok: violations.length === 0, violations };
-}
-function assertIndexRowObligations(iterationsDir) {
-  if (!existsSync5(iterationsDir)) {
-    return {
-      ok: false,
-      violations: [
-        violation6("high", "INDEX_ITERATIONS_DIR_MISSING", `{ITERATION_DIR} '${iterationsDir}' does not exist (mstar-iteration §1.4)`, "Create the iterations directory (path.resolveIterationDir)")
-      ]
-    };
+  const { controlWorktreePath, leaseWorktreePath, leaseWorkingBranch, planId } = input;
+  if (controlWorktreePath.trim() === "") {
+    violations.push(violation7("high", "worktree.l1.control-missing", "metadata.control_worktree_path is not recorded — the L1 control worktree (integration-branch checkout) must be recorded in status.json before writable dispatch", "record the control worktree path in status.json metadata.control_worktree_path"));
   }
-  const iterationIds = readdirSync4(iterationsDir, { withFileTypes: true }).filter((entry) => entry.isDirectory()).filter((entry) => existsSync5(join8(iterationsDir, entry.name, COMPASS_FILE))).map((entry) => entry.name).sort();
-  const readmePath = join8(iterationsDir, INDEX_README);
-  if (!existsSync5(readmePath)) {
-    return {
-      ok: false,
-      violations: [
-        violation6("high", "INDEX_README_MISSING", `{ITERATION_DIR}/README.md does not exist — one row per iteration is required (mstar-iteration §1.4)`, `Create {ITERATION_DIR}/README.md with the header '${INDEX_HEADER}' and one row per iteration`)
-      ]
-    };
+  if (leaseWorktreePath.trim() === "") {
+    violations.push(violation7("high", "worktree.l1.lease-missing", `execution_lease.worktree_path is empty for plan "${planId}" — no verified execution_lease to dispatch against`, "claim the execution_lease with an absolute feature worktree path before dispatch"));
   }
-  const violations = [];
-  const lines = readFileSync6(readmePath, "utf8").split(/\r?\n/);
-  if (!lines.some((line) => line.includes(INDEX_HEADER))) {
-    violations.push(violation6("medium", "INDEX_HEADER_MISSING", `{ITERATION_DIR}/README.md lacks the table header '${INDEX_HEADER}' (mstar-iteration §1.4)`, "Add the header row on first creation"));
+  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"));
   }
-  const indexed = new Set;
-  for (const line of lines) {
-    const match = line.match(/^\s*\|\s*`([^`]+)`\s*\|/);
-    if (match)
-      indexed.add(match[1].trim());
+  if (controlWorktreePath !== "" && leaseWorktreePath !== "" && resolve6(controlWorktreePath) === resolve6(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"));
   }
-  for (const id of iterationIds) {
-    if (!indexed.has(id)) {
-      violations.push(violation6("medium", "INDEX_ROW_MISSING", `Iteration '${id}' has a delivery-compass.md but no index row in {ITERATION_DIR}/README.md — one row per iteration (mstar-iteration §1.4)`, `Add | \`${id}\` | [\`${id}/\`](${id}/) | <description> | <status> |`));
+  if (leaseWorktreePath !== "" && !existsSync6(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>`));
+  } else if (leaseWorktreePath !== "" && leaseWorkingBranch !== "") {
+    const probe = probeBranch(leaseWorktreePath, opts);
+    if ("error" in probe) {
+      violations.push(violation7("high", "worktree.l1.branch-probe-failed", `cannot probe branch at "${leaseWorktreePath}" for plan "${planId}": ${probe.error}`, "verify the path is a git worktree checkout on the lease working branch (not detached)"));
+    } else if (probe.branch !== leaseWorkingBranch) {
+      violations.push(violation7("high", "worktree.l1.branch-mismatch", `feature worktree "${leaseWorktreePath}" is on branch "${probe.branch}", expected execution_lease.working_branch "${leaseWorkingBranch}" (plan "${planId}")`, `checkout ${leaseWorkingBranch} in the feature worktree`));
     }
   }
-  return { ok: violations.length === 0, violations };
-}
-function parseCompassFrontmatter(filePath) {
-  return parseCompassFrontmatterText(readFileSync6(filePath, "utf8"), filePath);
+  return gate(violations);
 }
-function parseCompassFrontmatterText(content, filePath) {
-  const lines = content.split(/\r?\n/);
-  if (lines[0]?.trim() !== "---") {
-    throw new Error(`no YAML frontmatter fence in ${filePath} (expected first line "---")`);
-  }
-  const end = lines.indexOf("---", 1);
-  if (end === -1) {
-    throw new Error(`unterminated YAML frontmatter in ${filePath} (no closing "---")`);
+function l2PreDispatchCheck(input, opts = {}) {
+  const violations = [];
+  const tracks = input.tracks ?? [];
+  const seenPaths = new Set;
+  if (tracks.length < 1) {
+    violations.push(violation7("high", "worktree.l2.no-tracks", "no parallel writable tracks — the L2 pre-dispatch checklist requires at least one track with an absolute worktreePath and Working branch", "pass each track's absolute Worktree path and PM-approved Working branch"));
   }
-  const doc = {};
-  let listKey = null;
-  for (let i = 1;i < end; i += 1) {
-    const line = lines[i] ?? "";
-    if (!line.trim() || line.trim().startsWith("#"))
-      continue;
-    if (listKey !== null && /^\s*-\s+/.test(line)) {
-      const item = line.replace(/^\s*-\s+/, "").trim().replace(/^["']|["']$/g, "");
-      if (!Array.isArray(doc[listKey]))
-        doc[listKey] = [];
-      doc[listKey].push(item);
-      continue;
+  tracks.forEach((track, index) => {
+    if (track.worktreePath.trim() === "" || track.workingBranch.trim() === "") {
+      violations.push(violation7("high", "worktree.l2.track-invalid", `track ${index + 1} is missing worktreePath and/or workingBranch`, "fill both fields for every track"));
+      return;
     }
-    listKey = null;
-    const kv = line.match(/^([A-Za-z_][A-Za-z0-9_-]*):\s*(.*)$/);
-    if (!kv) {
-      throw new Error(`unsupported frontmatter line in ${filePath}: ${JSON.stringify(line)}`);
+    if (!isAbsolute4(track.worktreePath)) {
+      violations.push(violation7("high", "worktree.l2.track-path-relative", `track ${index + 1} worktreePath "${track.worktreePath}" is not an absolute path — L2 tracks MUST use absolute worktree checkout paths (consistent with the lease validator's absolute worktree_path enforcement)`, `use an absolute path for track ${index + 1} (e.g. /Users/<you>/worktrees/<branch>)`));
+      return;
     }
-    const value = kv[2].trim();
-    doc[kv[1]] = value === "" ? null : /^\[.*\]$/.test(value) ? parseFlowArray(value, filePath) : value.replace(/^["']|["']$/g, "");
-    listKey = value === "" ? kv[1] : null;
+    const normalized = resolve6(track.worktreePath);
+    if (seenPaths.has(normalized)) {
+      violations.push(violation7("high", "worktree.l2.track-path-collision", `duplicate worktreePath "${track.worktreePath}" across parallel tracks — L2 parallel-writable isolation requires a distinct absolute Worktree path per track (N parallel invokes ≠ isolation)`, "give every parallel track its own git worktree checkout"));
+      return;
+    }
+    seenPaths.add(normalized);
+    if (!existsSync6(track.worktreePath)) {
+      violations.push(violation7("high", "worktree.l2.track-missing", `track worktree directory "${track.worktreePath}" does not exist`, `create it before dispatch: git worktree add ${track.worktreePath} ${track.workingBranch}`));
+      return;
+    }
+    const probe = probeBranch(track.worktreePath, opts);
+    if ("error" in probe) {
+      violations.push(violation7("high", "worktree.l2.branch-probe-failed", `cannot probe branch at "${track.worktreePath}": ${probe.error}`, "verify the path is a git worktree checkout on its Working branch (not detached)"));
+    } else if (probe.branch !== track.workingBranch) {
+      violations.push(violation7("high", "worktree.l2.branch-mismatch", `track worktree "${track.worktreePath}" is on branch "${probe.branch}", expected Working branch "${track.workingBranch}"`, `checkout ${track.workingBranch} in that worktree`));
+    }
+  });
+  return gate(violations);
+}
+function assertControlVsFeaturePath(controlWorktreePath, featureWorktreePath) {
+  const violations = [];
+  const samePath = controlWorktreePath === "" && featureWorktreePath === "" || controlWorktreePath !== "" && featureWorktreePath !== "" && resolve6(controlWorktreePath) === resolve6(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"));
   }
-  return doc;
+  return gate(violations);
 }
-function parseFlowArray(raw, filePath) {
-  const inner = raw.slice(1, -1);
-  if (/[[\]]/.test(inner)) {
-    throw new Error(`nested flow-style array in ${filePath}: ${JSON.stringify(raw)} — only flat scalar items are supported (e.g. [a, b])`);
+function assertBranchAlignment(worktreePath, expectedBranch, opts = {}) {
+  const violations = [];
+  const probe = probeBranch(worktreePath, opts);
+  if ("error" in probe) {
+    violations.push(violation7("high", "worktree.branch-probe-failed", `cannot probe branch at "${worktreePath}": ${probe.error}`, "verify the path is a git worktree checkout on the expected branch (not detached)"));
+  } else if (probe.branch !== expectedBranch) {
+    violations.push(violation7("high", "worktree.branch-mismatch", `worktree "${worktreePath}" is on branch "${probe.branch}", expected "${expectedBranch}" (Assignment Working branch)`, `checkout ${expectedBranch} in that worktree`));
   }
-  let quote = null;
-  for (const ch of inner) {
-    if (ch === '"' || ch === "'") {
-      if (quote === null)
-        quote = ch;
-      else if (quote === ch)
-        quote = null;
-    } else if (ch === "," && quote !== null) {
-      throw new Error(`ambiguous flow-style array in ${filePath}: ${JSON.stringify(raw)} — quoted item containing comma cannot be split unambiguously (flat scalar items only)`);
+  return gate(violations);
+}
+var QC_ALIGNMENT_FIELDS = [
+  { key: "planId", label: "plan_id" },
+  { key: "reviewRange", label: "Review range" },
+  { key: "diffBasis", label: "Diff basis" }
+];
+function assertQcAlignment(assignments) {
+  const violations = [];
+  const list = assignments ?? [];
+  for (const { key, label } of QC_ALIGNMENT_FIELDS) {
+    const distinct = [...new Set(list.map((a) => a[key]))];
+    if (distinct.length > 1) {
+      violations.push(violation7("high", "qc.alignment.mismatch", `QC/QA alignment field "${label}" is not byte-identical across ${list.length} assignments: ${distinct.map((v) => `"${v}"`).join(" vs ")}`, `copy the same ${label} value verbatim into every QC tri and QA Assignment`));
     }
   }
-  if (quote !== null) {
-    throw new Error(`unterminated ${quote} quote in flow-style array in ${filePath}: ${JSON.stringify(raw)}`);
-  }
-  const items = [];
-  for (const part of inner.split(",")) {
-    const item = part.trim().replace(/^["']|["']$/g, "");
-    if (item === "")
-      continue;
-    items.push(item);
-  }
-  return items;
-}
-// src/project.ts
-import { existsSync as existsSync6, readFileSync as readFileSync7, readdirSync as readdirSync5 } from "node:fs";
-import { join as join9 } from "node:path";
-var PROJECT_ROADMAP_FILE = "roadmap.md";
-var PROJECT_REFERENCES_DIR = "references";
-var PROJECT_REGISTER_FILE = "residuals.json";
-var _DEFAULT_PROJECT = "_default";
-var ROADMAP_STATUSES = ["active", "paused", "completed"];
-var DATE_RE3 = /^\d{4}-\d{2}-\d{2}$/;
-var ROLLUP_FIELDS = ["total_open", "by_severity", "by_target", "by_plan"];
-function isPlainObject5(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
+  return gate(violations);
 }
-function violation7(severity, code, message, fix) {
-  return { ok: false, severity, code, message, fix };
+function singleReviewSnapshot(assignments) {
+  const violations = [];
+  const list = assignments ?? [];
+  list.forEach((a, index) => {
+    if ((a.head ?? "").trim() === "") {
+      violations.push(violation7("high", "qc.alignment.snapshot-missing", `review head not provided for assignment ${index + 1} (plan_id "${a.planId}") — cannot confirm the single review snapshot precondition`, "precompute and pass the review HEAD (full SHA) for every assignment"));
+    }
+  });
+  const distinct = [...new Set(list.map((a) => a.head ?? "").filter((h) => h.trim() !== ""))];
+  if (distinct.length > 1) {
+    violations.push(violation7("high", "qc.alignment.single-snapshot", `assignments cover ${distinct.length} different review heads (${distinct.join(", ")}) — all reviewable commits must sit on ONE Working branch HEAD before QC tri + QA`, "merge the parallel tracks to a single Working branch HEAD, then re-derive the heads"));
+  }
+  return gate(violations);
 }
-function validateNonEmptyString4(violations, value, field, missingCode, invalidCode) {
-  if (value === undefined) {
-    violations.push(violation7("high", missingCode, `missing required field: ${field}`));
-  } else if (typeof value !== "string" || value.trim() === "") {
-    violations.push(violation7("medium", invalidCode, `${field} must be a non-empty string`));
+// src/sdd.ts
+import { execFileSync as execFileSync3 } from "node:child_process";
+import { mkdirSync as mkdirSync5, readdirSync as readdirSync5, readFileSync as readFileSync7, realpathSync as realpathSync3, statSync as statSync4, writeFileSync as writeFileSync4 } from "node:fs";
+import { basename as basename3, dirname as dirname6, isAbsolute as isAbsolute5, join as join9, resolve as resolve7 } from "node:path";
+class SddScriptError extends Error {
+  exitCode;
+  constructor(message, exitCode) {
+    super(message);
+    this.name = "SddScriptError";
+    this.exitCode = exitCode;
   }
 }
-function validateRoadmap(filePath) {
-  const violations = [];
-  let content;
+function isDirectory2(dir) {
   try {
-    content = readFileSync7(filePath, "utf8");
+    return statSync4(dir).isDirectory();
   } catch {
-    return {
-      ok: false,
-      violations: [violation7("high", "project.roadmap.unreadable", `cannot read roadmap file: ${filePath}`)],
-      warnings: []
-    };
+    return false;
   }
-  let doc;
+}
+function isFile2(file) {
   try {
-    doc = parseCompassFrontmatterText(content, filePath);
-  } catch (err) {
-    const message = err instanceof Error ? err.message : `invalid roadmap frontmatter in ${filePath}`;
-    return { ok: false, violations: [violation7("high", "project.roadmap.invalid-frontmatter", message)], warnings: [] };
-  }
-  validateNonEmptyString4(violations, doc.project_id, "project_id", "project.roadmap.missing-project-id", "project.roadmap.invalid-project-id");
-  validateNonEmptyString4(violations, doc.title, "title", "project.roadmap.missing-title", "project.roadmap.invalid-title");
-  if (doc.status === undefined) {
-    violations.push(violation7("high", "project.roadmap.missing-status", "missing required field: status"));
-  } else if (typeof doc.status !== "string" || !ROADMAP_STATUSES.includes(doc.status)) {
-    violations.push(violation7("medium", "project.roadmap.invalid-status", `status must be one of ${ROADMAP_STATUSES.join(" | ")} — got ${JSON.stringify(doc.status)}`));
-  }
-  if (doc.created_at === undefined) {
-    violations.push(violation7("high", "project.roadmap.missing-created-at", "missing required field: created_at"));
-  } else if (typeof doc.created_at !== "string" || !DATE_RE3.test(doc.created_at)) {
-    violations.push(violation7("medium", "project.roadmap.invalid-created-at", "created_at must be YYYY-MM-DD"));
-  }
-  if (doc.milestones !== undefined && doc.milestones !== null) {
-    if (!Array.isArray(doc.milestones)) {
-      violations.push(violation7("medium", "project.roadmap.invalid-milestones", "milestones must be a list of milestone names"));
-    } else {
-      for (const item of doc.milestones) {
-        if (typeof item !== "string" || item.trim() === "") {
-          violations.push(violation7("medium", "project.roadmap.invalid-milestones", "milestones items must be non-empty strings"));
-          break;
-        }
-      }
-    }
-  }
-  if (doc.residuals_ref !== undefined && doc.residuals_ref !== null) {
-    if (typeof doc.residuals_ref !== "string" || doc.residuals_ref.trim() === "") {
-      violations.push(violation7("medium", "project.roadmap.invalid-residuals-ref", "residuals_ref must be a non-empty string"));
-    }
-  }
-  const warnings = [];
-  const fenceEnd = linesIndexOfClosingFence(content);
-  const body = content.split(/\r?\n/).slice(fenceEnd + 1).join(`
-`);
-  if (!/^##\s+Direction\s*$/m.test(body)) {
-    warnings.push(violation7("low", "project.roadmap.body.missing-direction", "roadmap body has no `## Direction` section (documented body convention) — state the project direction there"));
+    return statSync4(file).isFile();
+  } catch {
+    return false;
   }
-  if (!/^\s*[-*]\s+\[[xX ]\]/m.test(body)) {
-    warnings.push(violation7("low", "project.roadmap.body.no-goal-items", "roadmap body has no goal-item task list (documented body convention) — list goals as `- [ ]` / `- [x]` markdown task items"));
+}
+var GIT_CAPTURE_MAX_BYTES = 64 * 1024 * 1024;
+function gitOut(cwd, args) {
+  try {
+    return execFileSync3("git", args, {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+      maxBuffer: GIT_CAPTURE_MAX_BYTES
+    }).trim();
+  } catch {
+    return null;
   }
-  return { ok: violations.length === 0, violations, warnings };
 }
-function linesIndexOfClosingFence(content) {
-  return content.split(/\r?\n/).indexOf("---", 1);
+function probeHarnessWithStatus(root) {
+  if (isFile2(join9(root, ".mstar", "status.json")))
+    return join9(root, ".mstar");
+  if (isFile2(join9(root, ".agents", "status.json")))
+    return join9(root, ".agents");
+  if (hasWorkflowSnapshot(join9(root, ".mstar")))
+    return join9(root, ".mstar");
+  if (hasWorkflowSnapshot(join9(root, ".agents")))
+    return join9(root, ".agents");
+  return null;
 }
-function validateProjectRegister(doc) {
-  const violations = [];
-  if (!isPlainObject5(doc)) {
-    return {
-      ok: false,
-      violations: [violation7("high", "project.register.invalid", "project register must be an object")]
-    };
+function hasWorkflowSnapshot(harnessDir) {
+  let workflowsDir;
+  try {
+    workflowsDir = resolveWorkflowDir(harnessDir, { harnessDir });
+  } catch {
+    workflowsDir = join9(harnessDir, "workflows");
   }
-  if (doc.entries === undefined) {
-    violations.push(violation7("high", "project.register.missing-entries", "missing required field: entries"));
-  } else if (!isPlainObject5(doc.entries)) {
-    violations.push(violation7("high", "project.register.invalid-entries", "entries must be an object keyed by plan id"));
-  } else {
-    for (const [key, entries] of Object.entries(doc.entries)) {
-      if (key.trim() === "") {
-        violations.push(violation7("medium", "project.register.invalid-key", "entries keys must be non-empty plan ids"));
-      }
-      if (!Array.isArray(entries)) {
-        violations.push(violation7("high", "project.register.invalid-entry-list", `entries[${JSON.stringify(key)}] must be an array of residual entries (one entry per residual; v1 multi-finding semantics)`));
-        continue;
-      }
-      for (const entry of entries) {
-        violations.push(...validateResidual(entry).violations);
-        if (!isPlainObject5(entry))
-          continue;
-        validateNonEmptyString4(violations, entry.source_plan, "source_plan", "project.register.missing-source-plan", "project.register.invalid-source-plan");
-        if (entry.registered_at === undefined) {
-          violations.push(violation7("high", "project.register.missing-registered-at", "missing required field: registered_at"));
-        } else if (typeof entry.registered_at !== "string" || !DATE_RE3.test(entry.registered_at)) {
-          violations.push(violation7("medium", "project.register.invalid-registered-at", "registered_at must be YYYY-MM-DD"));
-        }
-        if (entry.lifecycle_id !== undefined && (typeof entry.lifecycle_id !== "string" || entry.lifecycle_id.trim() === "")) {
-          violations.push(violation7("medium", "project.register.invalid-lifecycle-id", "lifecycle_id must be a non-empty string"));
-        }
-        if (typeof entry.source_plan === "string" && entry.source_plan.trim() !== "" && entry.source_plan !== key) {
-          violations.push(violation7("medium", "project.register.mismatched-source-plan", `source_plan ${JSON.stringify(entry.source_plan)} does not match the entries key ${JSON.stringify(key)} — entries are keyed by plan id`));
-        }
-      }
+  if (!isDirectory2(workflowsDir))
+    return false;
+  try {
+    for (const entry of readdirSync5(workflowsDir, { withFileTypes: true })) {
+      if (entry.isDirectory() && isFile2(join9(workflowsDir, entry.name, "snapshot.json")))
+        return true;
     }
+  } catch {
+    return false;
+  }
+  return false;
+}
+function isLinkedWorktree(root) {
+  const gitDirRaw = gitOut(root, ["rev-parse", "--git-dir"]);
+  const commonRaw = gitOut(root, ["rev-parse", "--git-common-dir"]);
+  if (gitDirRaw === null || commonRaw === null)
+    return false;
+  const gitDir = isAbsolute5(gitDirRaw) ? gitDirRaw : join9(root, gitDirRaw);
+  const common = isAbsolute5(commonRaw) ? commonRaw : join9(root, commonRaw);
+  if (gitDir.includes("/.git/worktrees/") || gitDir.includes("/worktrees/"))
+    return true;
+  try {
+    const gdParent = realpathSync3(dirname6(gitDir));
+    const cmAbs = realpathSync3(common);
+    return join9(gdParent, basename3(gitDir)) !== cmAbs && gitDir !== cmAbs;
+  } catch {
+    return false;
   }
-  return { ok: violations.length === 0, violations };
 }
-function findingsCleanupGate(register, planId, opts) {
-  const mode = opts?.mode ?? "allow-residual";
-  const violations = [];
-  const entries = isPlainObject5(register.entries) ? register.entries[planId] : undefined;
-  if (entries === undefined) {
-    return { ok: true, violations };
+function sddWorkspace(planId, opts = {}) {
+  if (!planId) {
+    throw new SddScriptError(`usage: mstar sdd workspace PLAN_ID [CONTROL_ROOT]
+` + "  Set MSTAR_CONTROL_ROOT=<control_worktree_path> when running from a feature worktree.", 2);
   }
-  if (!Array.isArray(entries)) {
-    violations.push(violation7("high", "project.register.invalid-entry-list", `entries[${JSON.stringify(planId)}] must be an array of residual entries (one entry per residual; v1 multi-finding semantics)`));
-    return { ok: false, violations };
+  const cwd = opts.cwd ?? process.cwd();
+  const controlRoot = opts.controlRoot ?? (process.env.MSTAR_CONTROL_ROOT || undefined);
+  let root;
+  if (controlRoot) {
+    if (!isDirectory2(controlRoot)) {
+      throw new SddScriptError(`mstar sdd workspace: CONTROL_ROOT / MSTAR_CONTROL_ROOT is not a directory: ${controlRoot}`, 1);
+    }
+    root = realpathSync3(controlRoot);
+  } else {
+    const topLevel = gitOut(cwd, ["rev-parse", "--show-toplevel"]);
+    root = realpathSync3(topLevel ?? cwd);
   }
-  if (entries.length === 0) {
-    return { ok: true, violations };
+  if (!controlRoot && isLinkedWorktree(root)) {
+    throw new SddScriptError(`mstar sdd workspace: linked worktree at ${root} has no {HARNESS_DIR}/status.json (default gitignore).
+` + `  Refusing to create a second SDD tree under the feature checkout.
+` + `  Re-run with MSTAR_CONTROL_ROOT=<control_worktree_path> or: mstar sdd workspace ${planId} <control_worktree_path>
+` + `  See mstar-branch-worktree «Harness path SSOT under default gitignore».`, 1);
   }
-  for (const entry of entries) {
-    if (!isOpenResidual(entry))
-      continue;
-    const id = typeof entry.id === "string" ? entry.id : "<unnamed>";
-    const label = `R#${id}`;
-    if (mode === "zero-residual") {
-      if (entry.severity === "nit") {
-        violations.push(violation7("medium", "findings.zero-residual-nit", `${label}: style-only nits must be fixed in-session or dropped — never left open under zero-residual`));
-      } else if (entry.decision === "risk-accepted" || entry.lifecycle === "waived") {
-        violations.push(violation7("medium", "findings.zero-residual-risk-accepted", `${label}: waived/risk-accepted findings must be closed/archived, not left open under zero-residual`));
-      } else if (entry.decision === "defer") {
-        if (typeof entry.target !== "string" || entry.target.trim() === "") {
-          violations.push(violation7("medium", "findings.zero-residual-defer-no-target", `${label}: blocker-defer requires a target (next iteration/milestone) under zero-residual`));
-        }
+  const harnessOverride = opts.harnessDir ?? (process.env.MSTAR_HARNESS_DIR || undefined);
+  let harnessDir;
+  if (harnessOverride) {
+    harnessDir = resolve7(root, harnessOverride);
+  } else {
+    const rc = findMstarc(root, root);
+    const rcHarnessDir = rc !== null ? parseMstarc(readFileSync7(rc, "utf8")).harnessDir : undefined;
+    if (rcHarnessDir) {
+      harnessDir = resolve7(rc !== null ? dirname6(rc) : root, rcHarnessDir);
+    } else {
+      const probed = probeHarnessWithStatus(root);
+      if (probed) {
+        harnessDir = probed;
+      } else if (isDirectory2(join9(root, ".mstar"))) {
+        harnessDir = join9(root, ".mstar");
+      } else if (isDirectory2(join9(root, ".agents"))) {
+        harnessDir = join9(root, ".agents");
       } else {
-        violations.push(violation7("medium", "findings.zero-residual-open-fixable", `${label}: fixable finding must not remain open under zero-residual — fix now or convert to a blocker-defer`));
+        harnessDir = join9(root, ".mstar");
       }
-    } else if (normalizeSeverity(entry.severity) === "critical") {
-      violations.push(violation7("high", "findings.allow-residual-critical", `${label}: unresolved critical blocks Approve with residuals`));
     }
   }
-  return { ok: violations.length === 0, violations };
+  const sddDir = resolveSddDir(harnessDir, planId);
+  mkdirSync5(sddDir, { recursive: true });
+  writeFileSync4(join9(sddDir, ".gitignore"), `*
+`);
+  return realpathSync3(sddDir);
 }
-function groupCount(values) {
-  const counts = new Map;
-  for (const value of values) {
-    const key = typeof value === "string" ? value : String(value);
-    counts.set(key, (counts.get(key) ?? 0) + 1);
+function taskBrief(planFile, taskN, outFile, opts = {}) {
+  if (!planFile || !Number.isInteger(taskN) || taskN < 1) {
+    throw new SddScriptError("usage: mstar sdd task-brief PLAN_FILE TASK_NUMBER [OUTFILE]", 2);
   }
-  return Object.fromEntries([...counts.entries()].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0));
-}
-function techDebtRollup(projectDir) {
-  const items = [];
-  let entries;
+  let content;
   try {
-    entries = readdirSync5(projectDir, { withFileTypes: true });
+    content = readFileSync7(planFile, "utf8");
   } catch {
-    entries = [];
+    throw new SddScriptError(`no such plan file: ${planFile}`, 2);
   }
-  for (const project of entries) {
-    if (!project.isDirectory())
-      continue;
-    const registerPath = join9(projectDir, project.name, PROJECT_REGISTER_FILE);
-    if (!existsSync6(registerPath))
-      continue;
-    let register;
+  let out;
+  if (outFile) {
+    out = outFile;
+  } else {
+    const sddDir = opts.sddDir ?? process.env.SDD_DIR;
+    if (!sddDir) {
+      throw new SddScriptError("mstar sdd task-brief: set SDD_DIR or pass OUTFILE (run mstar sdd workspace PLAN_ID first)", 2);
+    }
+    mkdirSync5(sddDir, { recursive: true });
+    out = join9(sddDir, `task-${taskN}-brief.md`);
+  }
+  const records = content.endsWith(`
+`) ? content.split(`
+`).slice(0, -1) : content.split(`
+`);
+  const headingRe = /^#+[ \t]+Task[ \t]+[0-9]+/;
+  const targetRe = new RegExp(`^#+[ 	]+Task[ 	]+${taskN}([^0-9]|$)`);
+  let infence = false;
+  let intask = false;
+  const printed = [];
+  for (const line of records) {
+    if (/^```/.test(line))
+      infence = !infence;
+    if (!infence && headingRe.test(line))
+      intask = targetRe.test(line);
+    if (intask)
+      printed.push(line);
+  }
+  const output = printed.length > 0 ? `${printed.join(`
+`)}
+` : "";
+  writeFileSync4(out, output);
+  if (printed.length === 0) {
+    throw new SddScriptError(`task ${taskN} not found in ${planFile} (no heading matching Task ${taskN})`, 3);
+  }
+  return out;
+}
+function reviewPackage(base, head, outFile, opts = {}) {
+  if (!base || !head) {
+    throw new SddScriptError("usage: mstar sdd review-package BASE HEAD [OUTFILE]", 2);
+  }
+  const cwd = opts.cwd ?? process.cwd();
+  const verifyRef = (ref, what) => {
     try {
-      register = readJson(registerPath);
+      execFileSync3("git", ["rev-parse", "--verify", "--quiet", ref], { cwd, stdio: ["ignore", "pipe", "pipe"] });
     } catch {
-      continue;
+      throw new SddScriptError(`bad ${what}: ${ref}`, 2);
     }
-    if (!isPlainObject5(register) || !isPlainObject5(register.entries))
-      continue;
-    for (const [plan, planEntries] of Object.entries(register.entries)) {
-      if (!Array.isArray(planEntries))
-        continue;
-      for (const entry of planEntries) {
-        if (!isPlainObject5(entry) || !isOpenResidual(entry))
-          continue;
-        items.push({ plan, entry });
-      }
+  };
+  verifyRef(base, "BASE");
+  verifyRef(head, "HEAD");
+  let out;
+  if (outFile) {
+    out = outFile;
+  } else {
+    const sddDir = opts.sddDir ?? process.env.SDD_DIR;
+    if (!sddDir) {
+      throw new SddScriptError("mstar sdd review-package: set SDD_DIR or pass OUTFILE", 2);
     }
+    mkdirSync5(sddDir, { recursive: true });
+    const shortBase = gitOut(cwd, ["rev-parse", "--short", base]) ?? base;
+    const shortHead = gitOut(cwd, ["rev-parse", "--short", head]) ?? head;
+    out = join9(sddDir, `review-${shortBase}..${shortHead}.diff`);
   }
-  const bySeverity = {};
-  for (const severity of SEVERITY_ORDER) {
-    bySeverity[severity] = items.filter(({ entry }) => normalizeSeverity(entry.severity) === severity).length;
+  const run = (args) => execFileSync3("git", args, { cwd, maxBuffer: GIT_CAPTURE_MAX_BYTES });
+  const parts = [
+    Buffer.from(`# Review package: ${base}..${head}
+
+## Commits
+`),
+    run(["log", "--oneline", `${base}..${head}`]),
+    Buffer.from(`
+## Files changed
+`),
+    run(["diff", "--stat", `${base}..${head}`]),
+    Buffer.from(`
+## Diff
+`),
+    run(["diff", "-U10", `${base}..${head}`])
+  ];
+  writeFileSync4(out, Buffer.concat(parts));
+  return out;
+}
+function assertBaseSha(ref, opts = {}) {
+  if (typeof ref !== "string" || !/^[0-9a-f]{4,40}$/i.test(ref)) {
+    throw new SddScriptError(`assertBaseSha: BASE must be a commit SHA (full or prefix); got ${JSON.stringify(ref)}. ` + "Never use HEAD~1 as review BASE (multi-commit tasks truncate).", 2);
+  }
+  try {
+    execFileSync3("git", ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`], {
+      cwd: opts.cwd,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+  } catch {
+    throw new SddScriptError(`assertBaseSha: commit not found: ${ref}`, 2);
   }
-  const computed = {
-    total_open: items.length,
-    by_severity: bySeverity,
-    by_target: groupCount(items.map(({ entry }) => entry.target ?? "unspecified")),
-    by_plan: groupCount(items.map(({ plan }) => plan))
-  };
-  const stored = null;
-  const checks = ROLLUP_FIELDS.map((field) => ({ field, status: "DRIFT" }));
-  const overall = "DRIFT";
-  return { computed, stored, checks, overall };
 }
-function listProjectReferenceFiles(projectDir) {
-  const root = join9(projectDir, PROJECT_REFERENCES_DIR);
-  let entries;
+function taskReportExists(sddDir, taskN) {
+  try {
+    const st = statSync4(join9(sddDir, `task-${taskN}-report.md`));
+    return st.isFile() && st.size > 0;
+  } catch {
+    return false;
+  }
+}
+function readProgressLedger(sddDir) {
+  let content;
   try {
-    entries = readdirSync5(root, { withFileTypes: true });
+    content = readFileSync7(join9(sddDir, "progress.md"), "utf8");
   } catch {
     return [];
   }
-  const files = [];
-  for (const entry of entries) {
-    if (entry.name === PROJECT_ROADMAP_FILE || entry.name === PROJECT_REGISTER_FILE)
-      continue;
-    if (entry.isFile()) {
-      files.push(entry.name);
-    } else if (entry.isDirectory()) {
-      let nested;
-      try {
-        nested = readdirSync5(join9(root, entry.name), { withFileTypes: true });
-      } catch {
-        continue;
-      }
-      for (const child of nested) {
-        if (child.isFile())
-          files.push(`${entry.name}/${child.name}`);
-      }
-    }
+  return content.split(`
+`).map((line) => line.trim()).filter((line) => line.length > 0);
+}
+function implementerSessionStickyRules(input) {
+  const { session, nextTask, microBatchTasks = 1 } = input;
+  if (session.session_mode !== "sticky") {
+    return { resume: false, reason: `session_mode is '${session.session_mode}'; sticky resume requires 'sticky'` };
   }
-  return files.sort();
+  if (typeof session.host_agent_id !== "string" || session.host_agent_id.length === 0) {
+    return {
+      resume: false,
+      reason: "host_agent_id is missing from implementer-session.json; fall back to fresh for this task " + "(mstar-sdd SKILL.md red flag: resume implementer without host_agent_id)"
+    };
+  }
+  if (nextTask <= session.last_task) {
+    return {
+      resume: false,
+      reason: `nextTask ${nextTask} <= last_task ${session.last_task}; task already completed in this session`
+    };
+  }
+  if (microBatchTasks < 1 || microBatchTasks > 3) {
+    return {
+      resume: false,
+      reason: `micro-batch of ${microBatchTasks} tasks is outside 1..3 (max 3 without user override, ` + "sticky-implementer-session.md § Micro-batch fallback)"
+    };
+  }
+  return { resume: true, reason: `sticky resume OK: host_agent_id ${session.host_agent_id}, next task ${nextTask}` };
 }
 // src/migrate.ts
-import { copyFileSync, mkdirSync as mkdirSync6, readFileSync as readFileSync8, readdirSync as readdirSync6, writeFileSync as writeFileSync4 } from "node:fs";
+import { copyFileSync, mkdirSync as mkdirSync6, readFileSync as readFileSync8, readdirSync as readdirSync6, writeFileSync as writeFileSync5 } from "node:fs";
 import { dirname as dirname7, isAbsolute as isAbsolute6, join as join10, relative as relative3, resolve as resolve8, sep as sep2 } from "node:path";
 var MIGRATE_STATUS_FILE = "status.json";
 var ARCHIVED_STATUS_V1_FILE = "archived/status.v1.json";
@@ -2984,7 +3027,7 @@ async function applyMigratePlan(plan) {
     const content = notes.lines.length > 0 ? `${notes.lines.join(`
 `)}
 ` : "";
-    writeFileSync4(filePath, content, "utf8");
+    writeFileSync5(filePath, content, "utf8");
   }
   if (plan.register !== null) {
     const gate2 = validateProjectRegister(plan.register.data);
@@ -3000,7 +3043,7 @@ async function applyMigratePlan(plan) {
   if (plan.roadmap !== null) {
     const filePath = projectTargetOf(plan.roadmap.file);
     mkdirSync6(dirname7(filePath), { recursive: true });
-    writeFileSync4(filePath, plan.roadmap.content, "utf8");
+    writeFileSync5(filePath, plan.roadmap.content, "utf8");
   }
   const rootGate = validateStatusV2(plan.rootV2.data, { harnessDir: plan.root });
   if (!rootGate.ok) {
@@ -3422,7 +3465,7 @@ function completenessLevel(frontmatterText, checklist) {
   return { level, items, missing, placeholders, upgradeTo, bodyUnverified };
 }
 // src/audit.ts
-import { existsSync as existsSync7, mkdirSync as mkdirSync7, readdirSync as readdirSync7, readFileSync as readFileSync9, rmdirSync as rmdirSync2, rmSync, writeFileSync as writeFileSync5 } from "node:fs";
+import { existsSync as existsSync7, mkdirSync as mkdirSync7, readdirSync as readdirSync7, readFileSync as readFileSync9, rmdirSync as rmdirSync2, rmSync, writeFileSync as writeFileSync6 } from "node:fs";
 import { basename as basename4, join as join11, resolve as resolve9, sep as sep3 } from "node:path";
 function violation9(severity, code, message, fix) {
   return { ok: false, severity, code, message, fix };
@@ -3534,8 +3577,17 @@ function readPlanFileSummary(filePath) {
   const blocks = parseStatusBlocks(text);
   return { title: title.trim(), fields: blocks.length > 0 ? blocks[0].fields : new Map };
 }
+function extractSecurityDispositionSections(text) {
+  const grab = (heading) => {
+    const match = text.match(new RegExp(`(?:^|\\r?\\n)##[ \\t]+${heading}[ \\t]*\\r?\\n(?:[ \\t]*\\r?\\n)?([\\s\\S]*?)(?=\\r?\\n## |$)`, "i"));
+    if (!match)
+      return [];
+    return match[1].split(/\r?\n/).map((line) => line.replace(/\r$/, "")).filter((line) => line.startsWith("- "));
+  };
+  return { needsVerification: grab("Needs verification"), hardeningChecked: grab("Hardening & checked notes") };
+}
 function renderIndex(params) {
-  const { date, repoName, repoShortSha, rows, rejected } = params;
+  const { date, repoName, repoShortSha, rows, rejected, needsVerification, hardeningChecked } = params;
   const findingsRows = rows.map((r) => `| ${r.num} | ${escapeCell(r.title)} | ${r.category} | ${escapeCell(truncate(r.impact, 80))} | ${r.effort} | ${r.risk} | ${r.confidence} | ${escapeCell(truncate(r.evidence, 80))} |`).join(`
 `);
   const directionRows = rows.filter((r) => r.category === "direction").map((r) => `- ${escapeCell(r.title)} — ${escapeCell(truncate(r.impact, 120))}`).join(`
@@ -3556,6 +3608,12 @@ function renderIndex(params) {
   if (directionRows !== "") {
     sections.push("", "## Direction", "", directionRows);
   }
+  if (needsVerification.length > 0) {
+    sections.push("", "## Needs verification", "", ...needsVerification);
+  }
+  if (hardeningChecked.length > 0) {
+    sections.push("", "## Hardening & checked notes", "", ...hardeningChecked);
+  }
   sections.push("", "## Execution order & status", "", "| Plan | Title | Priority | Effort | Depends on | Status |", "|------|-------|----------|--------|------------|--------|", executionRows);
   if (rejectedRows !== "") {
     sections.push("", "## Findings considered and rejected", "", rejectedRows);
@@ -3569,6 +3627,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 };
   mkdirSync7(outDir, { recursive: true });
+  const existingReadme = join11(outDir, "README.md");
+  const carried = existsSync7(existingReadme) ? extractSecurityDispositionSections(readFileSync9(existingReadme, "utf8")) : { needsVerification: [], hardeningChecked: [] };
   const existing = readdirSync7(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 written = [];
@@ -3584,7 +3644,7 @@ function scaffoldAuditPlan(outDir, findings, options = {}) {
     }
     usedSlugs.add(slug);
     const file = `${num}-${slug}.md`;
-    writeFileSync5(join11(outDir, file), renderPlanFile(finding, plannedAt));
+    writeFileSync6(join11(outDir, file), renderPlanFile(finding, plannedAt));
     written.push(file);
     next++;
   }
@@ -3622,12 +3682,16 @@ function scaffoldAuditPlan(outDir, findings, options = {}) {
       row.dependsOn = finding.dependsOn ?? "none";
     }
   });
-  writeFileSync5(join11(outDir, "README.md"), renderIndex({
+  const needsVerificationLines = options.needsVerification !== undefined ? options.needsVerification.map((nv) => `- ${escapeCell(nv.lead)}: ${escapeCell(nv.how)}${nv.evidence ? ` (${escapeCell(nv.evidence)})` : ""}`) : carried.needsVerification;
+  const hardeningCheckedLines = options.hardeningChecked !== undefined ? options.hardeningChecked.map((hc) => `- ${hc.kind}: ${escapeCell(hc.text)}`) : carried.hardeningChecked;
+  writeFileSync6(join11(outDir, "README.md"), renderIndex({
     date,
     repoName: options.repoName ?? "repo",
     repoShortSha: options.repoShortSha ?? "unknown",
     rows,
-    rejected: options.rejected ?? []
+    rejected: options.rejected ?? [],
+    needsVerification: needsVerificationLines,
+    hardeningChecked: hardeningCheckedLines
   }));
   return { outDir: resolve9(outDir), date, files: written, nextNumber: next };
 }
@@ -4704,6 +4768,7 @@ export {
   resolveSpecsDir,
   resolveSkillRoot,
   resolveSddDir,
+  resolveScaffoldDirs,
   resolveRepoEnforcement,
   resolveProjectRoot,
   resolveProjectDir,
@@ -4753,6 +4818,7 @@ export {
   evaluatePhaseGate,
   emitGitignoreSnippet,
   detectHost,
+  detectHarnessKind,
   compoundRefreshScope,
   composeDispatchGate,
   completenessLevel,