@mstar-harness/engine 2.4.1 → 3.1.0

package/dist/engine.js

@@ -81,27 +81,118 @@ function harnessVersionFrom(moduleDir) {
 function readHarnessVersion() {
   return harnessVersionFrom(dirname(fileURLToPath(import.meta.url)));
 }
+// src/mstarc.ts
+import { readFileSync as readFileSync2, statSync } from "node:fs";
+import { dirname as dirname2, isAbsolute, join as join2, relative, resolve as resolve2 } from "node:path";
+var MSTARC_FILE = ".mstarc";
+var MSTARC_SECTION = "config";
+var MSTARC_HARNESS_DIR_KEY = "harness_dir";
+var MSTARC_PLAN_DIR_KEY = "plan_dir";
+var MSTARC_SDD_DIR_KEY = "sdd_dir";
+var MSTARC_ITERATION_DIR_KEY = "iteration_dir";
+var MSTARC_KNOWLEDGE_DIR_KEY = "knowledge_dir";
+var MSTARC_SPECS_DIR_KEY = "specs_dir";
+var MSTARC_WORKFLOW_DIR_KEY = "workflow_dir";
+var MSTARC_PROJECT_DIR_KEY = "project_dir";
+var MSTARC_ENFORCEMENT_KEY = "enforcement";
+var CONFIG_KEYS = {
+  [MSTARC_HARNESS_DIR_KEY]: "harnessDir",
+  [MSTARC_PLAN_DIR_KEY]: "planDir",
+  [MSTARC_SDD_DIR_KEY]: "sddDir",
+  [MSTARC_ITERATION_DIR_KEY]: "iterationDir",
+  [MSTARC_KNOWLEDGE_DIR_KEY]: "knowledgeDir",
+  [MSTARC_SPECS_DIR_KEY]: "specsDir",
+  [MSTARC_WORKFLOW_DIR_KEY]: "workflowDir",
+  [MSTARC_PROJECT_DIR_KEY]: "projectDir",
+  [MSTARC_ENFORCEMENT_KEY]: "enforcement"
+};
+function parseMstarc(text) {
+  let section = null;
+  const out = {};
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (line === "" || line.startsWith("#") || line.startsWith(";"))
+      continue;
+    const header = /^\[([^\]]+)\]$/.exec(line);
+    if (header !== null) {
+      section = header[1].trim();
+      continue;
+    }
+    if (section !== MSTARC_SECTION)
+      continue;
+    const eq = line.indexOf("=");
+    if (eq === -1)
+      continue;
+    const field = CONFIG_KEYS[line.slice(0, eq).trim()];
+    if (field === undefined)
+      continue;
+    const value = line.slice(eq + 1).trim();
+    if (value === "")
+      continue;
+    if (field === "enforcement" && value !== "hard" && value !== "soft")
+      continue;
+    out[field] = value;
+  }
+  return out;
+}
+function isFile(file) {
+  try {
+    return statSync(file).isFile();
+  } catch {
+    return false;
+  }
+}
+function findMstarc(startDir, boundary) {
+  let dir = resolve2(startDir);
+  const bound = resolve2(boundary);
+  for (;; ) {
+    if (!isAtOrBelow(dir, bound))
+      return null;
+    const candidate = join2(dir, MSTARC_FILE);
+    if (isFile(candidate))
+      return candidate;
+    if (dir === bound)
+      return null;
+    const parent = dirname2(dir);
+    if (parent === dir)
+      return null;
+    dir = parent;
+  }
+}
+function loadMstarc(startDir, boundary) {
+  const file = findMstarc(startDir, boundary);
+  if (file === null)
+    return null;
+  return { file, dir: dirname2(file), config: parseMstarc(readFileSync2(file, "utf8")) };
+}
+function isAtOrBelow(dir, root) {
+  const rel = relative(root, dir);
+  return rel === "" || !rel.startsWith("..") && !isAbsolute(rel);
+}
 // src/path.ts
-import { mkdirSync as mkdirSync2, readdirSync, readFileSync as readFileSync2, statSync } from "node:fs";
+import { mkdirSync as mkdirSync2, readdirSync, readFileSync as readFileSync3, statSync as statSync2 } from "node:fs";
 import { execFileSync } from "node:child_process";
-import { basename as basename2, dirname as dirname2, isAbsolute, join as join2, relative, resolve as resolve2 } from "node:path";
+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 = resolve2(startDir);
+  const start = resolve3(startDir);
   const explicit = opts.harnessDir ?? process.env.MSTAR_HARNESS_DIR;
   if (explicit)
-    return resolve2(start, explicit);
-  const boundary = resolve2(start, opts.workspaceRoot ?? defaultWorkspaceRoot(start));
+    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 (!isAtOrBelow(dir, boundary))
+    if (!isAtOrBelow2(dir, boundary))
       return null;
-    for (const candidate of [join2(dir, ".mstar"), join2(dir, ".agents"), join2(dir, ".plans"), join2(dir, "plans")]) {
+    for (const candidate of [join3(dir, ".mstar"), join3(dir, ".agents"), join3(dir, ".plans"), join3(dir, "plans")]) {
       if (isDirectory(candidate))
         return candidate;
     }
     if (dir === boundary)
       return null;
-    const parent = dirname2(dir);
+    const parent = dirname3(dir);
     if (parent === dir)
       return null;
     dir = parent;
@@ -119,41 +210,56 @@ function defaultWorkspaceRoot(startDir) {
     let boundary = startDir;
     for (const segment of cdup.split(/[\\/]/)) {
       if (segment && segment !== ".")
-        boundary = dirname2(boundary);
+        boundary = dirname3(boundary);
     }
-    return resolve2(boundary);
+    return resolve3(boundary);
   } catch {}
   return startDir;
 }
-function isAtOrBelow(dir, root) {
-  const rel = relative(root, dir);
-  return rel === "" || !rel.startsWith("..") && !isAbsolute(rel);
+function isAtOrBelow2(dir, root) {
+  const rel = relative2(root, dir);
+  return rel === "" || !rel.startsWith("..") && !isAbsolute2(rel);
+}
+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 resolveSpecsDir(harnessDir, opts = {}) {
-  const harness = resolve2(harnessDir);
-  const repoRoot = dirname2(harness);
+  const declared = mstarcDirOverride(harnessDir, "specsDir");
+  if (declared !== null) {
+    if (opts.create !== false)
+      mkdirSync2(declared, { recursive: true });
+    return declared;
+  }
+  const harness = resolve3(harnessDir);
+  const repoRoot = dirname3(harness);
   const candidates = [
-    join2(harness, "specs"),
-    join2(repoRoot, "docs", "specs"),
-    join2(repoRoot, "specs"),
-    join2(harness, "designs"),
-    join2(repoRoot, "designs")
+    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 fallback = join2(harness, "specs");
+  const fallback = join3(harness, "specs");
   if (opts.create !== false)
     mkdirSync2(fallback, { recursive: true });
   return fallback;
 }
 function resolvePlanDir(harnessDir) {
-  const dir = resolve2(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 join2(dir, "plans");
+  return join3(dir, "plans");
 }
 function assertSafePathComponent(value, what) {
   if (value === "" || value === "." || value === ".." || !/^[A-Za-z0-9._-]+$/.test(value)) {
@@ -162,24 +268,48 @@ function assertSafePathComponent(value, what) {
 }
 function resolveSddDir(harnessDir, planId) {
   assertSafePathComponent(planId, "planId");
-  return join2(resolve2(harnessDir), "sdd", 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) {
-  return join2(resolve2(harnessDir), "iterations");
+  const declared = mstarcDirOverride(harnessDir, "iterationDir");
+  if (declared !== null)
+    return declared;
+  return join3(resolve3(harnessDir), "iterations");
+}
+function resolveKnowledgeDir(harnessDir) {
+  const declared = mstarcDirOverride(harnessDir, "knowledgeDir");
+  if (declared !== null)
+    return declared;
+  return join3(resolve3(harnessDir), "knowledge");
+}
+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)`);
+  }
+  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");
+}
+function resolveProjectDir(startDir = process.cwd(), opts = {}) {
+  return resolveHarnessSubdir(startDir, opts, "projectDir", "projects");
 }
 var EMPTY_STATUS_TEMPLATE = {
-  version: 1,
+  version: 2,
   updated_at: "1970-01-01",
-  plans: [],
-  residual_findings: {},
-  metadata: {}
+  workflows: []
 };
 var SCAFFOLD_DIRS = ["plans", "iterations", "knowledge", "specs", "sdd"];
 function scaffoldHarness(root) {
-  const harnessDir = join2(resolve2(root), ".mstar");
+  const harnessDir = join3(resolve3(root), ".mstar");
   for (const dir of SCAFFOLD_DIRS)
-    mkdirSync2(join2(harnessDir, dir), { recursive: true });
-  const statusPath = join2(harnessDir, "status.json");
+    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;
@@ -193,6 +323,8 @@ var GITIGNORE_SNIPPET = `# Morning Star harness (.mstar/)
 !.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.
@@ -215,11 +347,11 @@ function emitGitignoreSnippet(kind) {
   return `${GITIGNORE_SNIPPET}${GITIGNORE_SNIPPET_AGENTS}`;
 }
 function validateGitignore(root) {
-  const gitignorePath = join2(resolve2(root), ".gitignore");
+  const gitignorePath = join3(resolve3(root), ".gitignore");
   const kind = detectHarnessKind(resolveHarnessDir(root));
   let content;
   try {
-    content = readFileSync2(gitignorePath, "utf8");
+    content = readFileSync3(gitignorePath, "utf8");
   } catch {
     return {
       ok: false,
@@ -263,7 +395,7 @@ function validateGitignore(root) {
 function detectHarnessKind(harnessDir) {
   if (!harnessDir)
     return null;
-  const name = basename2(resolve2(harnessDir));
+  const name = basename2(resolve3(harnessDir));
   if (name === ".mstar")
     return "mstar";
   if (name === ".agents")
@@ -271,7 +403,7 @@ function detectHarnessKind(harnessDir) {
   return null;
 }
 function assertPlanWritingPath(planPath, harnessDir) {
-  const planAbs = resolve2(planPath);
+  const planAbs = resolve3(planPath);
   if (!harnessDir) {
     return {
       ok: false,
@@ -282,8 +414,8 @@ function assertPlanWritingPath(planPath, harnessDir) {
     };
   }
   const planDir = resolvePlanDir(harnessDir);
-  const rel = relative(planDir, planAbs);
-  const inside = rel === "" || !rel.startsWith("..") && !isAbsolute(rel);
+  const rel = relative2(planDir, planAbs);
+  const inside = rel === "" || !rel.startsWith("..") && !isAbsolute2(rel);
   if (!inside) {
     return {
       ok: false,
@@ -302,7 +434,7 @@ function assertPlanWritingPath(planPath, harnessDir) {
 }
 function isDirectory(dir) {
   try {
-    return statSync(dir).isDirectory();
+    return statSync2(dir).isDirectory();
   } catch {
     return false;
   }
@@ -311,7 +443,7 @@ function hasFiles(dir) {
   try {
     for (const entry of readdirSync(dir, { withFileTypes: true })) {
       if (entry.isDirectory()) {
-        if (hasFiles(join2(dir, entry.name)))
+        if (hasFiles(join3(dir, entry.name)))
           return true;
       } else if (entry.isFile()) {
         return true;
@@ -323,12 +455,12 @@ function hasFiles(dir) {
   }
 }
 // src/status.ts
-import { existsSync as existsSync2, readFileSync as readFileSync3, readdirSync as readdirSync2 } from "node:fs";
-import { join as join4, resolve as resolve4 } from "node:path";
+import { existsSync as existsSync2, readFileSync as readFileSync4, readdirSync as readdirSync2, realpathSync } from "node:fs";
+import { dirname as dirname5, join as join6, resolve as resolve5, sep } from "node:path";
 
 // src/lease.ts
-import { mkdirSync as mkdirSync3, rmdirSync, statSync as statSync2, unlinkSync as unlinkSync2, writeFileSync as writeFileSync2 } from "node:fs";
-import { dirname as dirname3, isAbsolute as isAbsolute2, join as join3, resolve as resolve3 } from "node:path";
+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 { setTimeout as sleep } from "node:timers/promises";
 import { AsyncLocalStorage } from "node:async_hooks";
 function isPlainObject(value) {
@@ -370,7 +502,7 @@ function validateExecutionLease(lease) {
     violations.push(violation("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 (!isAbsolute2(lease.worktree_path)) {
+  } 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)"));
   }
   validateNonEmptyString(violations, lease.working_branch, "working_branch", "lease.execution-lease.missing-working-branch", "lease.execution-lease.invalid-working-branch");
@@ -500,13 +632,11 @@ function canSteal(lease, holder, opts = {}) {
   return opts.userOverride === true;
 }
 function planExecutionLeaseLocations(row) {
-  const meta = row.metadata;
-  const metadataLease = meta && typeof meta === "object" && !Array.isArray(meta) ? meta.execution_lease : undefined;
-  return { row: row.execution_lease, metadata: metadataLease };
+  return { row: row.execution_lease };
 }
 function verifyPlanExecutionLease(row, planId) {
-  const { row: rowLease, metadata: metadataLease } = planExecutionLeaseLocations(row);
-  const lease = rowLease !== undefined ? rowLease : metadataLease;
+  const { row: rowLease } = planExecutionLeaseLocations(row);
+  const lease = rowLease;
   if (lease === undefined) {
     if (row.status === "InProgress") {
       return {
@@ -519,16 +649,11 @@ function verifyPlanExecutionLease(row, planId) {
     return {
       ok: false,
       violations: [
-        violation("high", "lease.verify.missing", `plan ${planId} has no execution_lease (neither plans[].execution_lease nor legacy plans[].metadata.execution_lease)`)
+        violation("high", "lease.verify.missing", `plan ${planId} has no execution_lease at the SSOT location plans[].execution_lease`)
       ]
     };
   }
   const violations = [];
-  if (rowLease !== undefined && metadataLease !== undefined) {
-    violations.push(violation("high", "lease.verify.dual-write", "execution_lease present in BOTH plans[].execution_lease (SSOT) and plans[].metadata.execution_lease — the row-level lease wins; delete the metadata copy to remove the dual write"));
-  } else if (rowLease === undefined) {
-    violations.push(violation("high", "lease.verify.non-ssot-location", "execution_lease found only under plans[].metadata.execution_lease — the SSOT location is plans[].execution_lease; the metadata location is a legacy/hand-written read-compat fallback, not equivalent to SSOT success (migrate the lease to the plan row)"));
-  }
   violations.push(...validateExecutionLease(lease).violations);
   return { ok: violations.length === 0, violations, lease };
 }
@@ -536,7 +661,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 = join3(dirname3(resolve3(statusPath)), STATUS_WRITE_LOCKDIR);
+  const lockDir = join4(dirname4(resolve4(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`);
@@ -548,7 +673,7 @@ async function withStatusWriteLock(statusPath, fn, opts = {}) {
   for (;; ) {
     try {
       mkdirSync3(lockDir);
-      const st = statSync2(lockDir);
+      const st = statSync3(lockDir);
       acquired = { dev: st.dev, ino: st.ino };
       break;
     } catch (error) {
@@ -561,7 +686,7 @@ async function withStatusWriteLock(statusPath, fn, opts = {}) {
     }
   }
   try {
-    writeFileSync2(join3(lockDir, LOCKDIR_HOLDER_PID), String(process.pid), "utf8");
+    writeFileSync2(join4(lockDir, LOCKDIR_HOLDER_PID), String(process.pid), "utf8");
   } catch {}
   const owns = held ?? new Set;
   owns.add(lockDir);
@@ -570,10 +695,10 @@ async function withStatusWriteLock(statusPath, fn, opts = {}) {
   } finally {
     owns.delete(lockDir);
     try {
-      const current = statSync2(lockDir);
+      const current = statSync3(lockDir);
       if (acquired !== null && current.dev === acquired.dev && current.ino === acquired.ino) {
         try {
-          unlinkSync2(join3(lockDir, LOCKDIR_HOLDER_PID));
+          unlinkSync2(join4(lockDir, LOCKDIR_HOLDER_PID));
         } catch {}
         rmdirSync(lockDir);
       }
@@ -818,16 +943,141 @@ function antiRecursionPrecheck(subagentType, executeAs) {
   return { ok: true, violations: [] };
 }
 
+// src/workflow.ts
+import { mkdirSync as mkdirSync4 } 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) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function violation3(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}`));
+  } else if (typeof value !== "string" || value.trim() === "") {
+    violations.push(violation3("medium", invalidCode, `${field} must be a non-empty string`));
+  }
+}
+function validateWorkflowSnapshot(doc) {
+  const violations = [];
+  if (!isPlainObject2(doc)) {
+    return {
+      ok: false,
+      violations: [violation3("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"));
+  } 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)`));
+  }
+  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"));
+  }
+  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"));
+  } 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)}`));
+  }
+  if (doc.status === undefined) {
+    violations.push(violation3("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)}`));
+  }
+  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");
+  if (doc.ended_at !== undefined) {
+    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)"));
+  }
+  if (doc.plans === undefined) {
+    violations.push(violation3("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"));
+  } else {
+    for (const row of doc.plans) {
+      violations.push(...validatePlanRow(row).violations);
+      if (isPlainObject2(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 (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"));
+    } 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`));
+        }
+      }
+    }
+  }
+  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.compass_ref !== undefined) {
+    validateNonEmptyString2(violations, doc.compass_ref, "compass_ref", "workflow.snapshot.missing-compass-ref", "workflow.snapshot.invalid-compass-ref");
+  }
+  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`));
+    }
+    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 (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"));
+    }
+  }
+  return { ok: violations.length === 0, violations };
+}
+async function writeWorkflowSnapshot(snapshot, dir) {
+  const gate = validateWorkflowSnapshot(snapshot);
+  if (!gate.ok) {
+    const detail = gate.violations.map((v) => v.message).join("; ");
+    throw new Error(`refusing to write invalid workflow snapshot: ${detail}`);
+  }
+  const snapshotPath = join5(dir, WORKFLOW_SNAPSHOT_FILE);
+  mkdirSync4(dir, { recursive: true });
+  await withStatusWriteLock(snapshotPath, () => {
+    writeJson(snapshotPath, snapshot);
+  });
+}
+
 // src/status.ts
 var DATE_RE = /^\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"];
-var ROLLUP_FIELDS = ["total_open", "by_severity", "by_target", "by_plan"];
-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 todayString() {
@@ -848,254 +1098,299 @@ function isOpenResidual(entry) {
   const effective = lifecycle === false || lifecycle === null || lifecycle === undefined ? "open" : lifecycle;
   return effective === "open";
 }
-function validateNonEmptyString2(violations, value, field, missingCode, invalidCode) {
+function validateNonEmptyString3(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 validatePlanRow(row) {
   const violations = [];
-  if (!isPlainObject2(row)) {
-    return { ok: false, violations: [violation3("high", "status.plan-row.invalid", "plan row must be an object")] };
+  if (!isPlainObject3(row)) {
+    return { ok: false, violations: [violation4("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(violation3("high", "status.plan-row.missing-id", "missing required field: id (or legacy plan_id)"));
+    violations.push(violation4("high", "status.plan-row.missing-id", "missing required field: id (or legacy plan_id)"));
   } else {
     if (id !== undefined) {
-      validateNonEmptyString2(violations, id, "id", "status.plan-row.missing-id", "status.plan-row.invalid-id");
+      validateNonEmptyString3(violations, id, "id", "status.plan-row.missing-id", "status.plan-row.invalid-id");
     }
     if (planId !== undefined) {
-      validateNonEmptyString2(violations, planId, "plan_id", "status.plan-row.missing-plan-id", "status.plan-row.invalid-plan-id");
+      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(violation3("medium", "status.plan-row.dual-id", "row has both id and plan_id with different values — write one canonical key (prefer id)"));
+      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)"));
     }
   }
-  validateNonEmptyString2(violations, title, "title", "status.plan-row.missing-title", "status.plan-row.invalid-title");
-  validateNonEmptyString2(violations, file, "file", "status.plan-row.missing-file", "status.plan-row.invalid-file");
+  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(violation3("high", "status.plan-row.missing-status", "missing required field: status"));
+    violations.push(violation4("high", "status.plan-row.missing-status", "missing required field: status"));
   } else if (typeof status !== "string" || !PLAN_STATUSES.includes(status)) {
-    violations.push(violation3("medium", "status.plan-row.invalid-status", `status must be one of ${PLAN_STATUSES.join(" | ")} — got ${JSON.stringify(status)}`));
+    violations.push(violation4("medium", "status.plan-row.invalid-status", `status must be one of ${PLAN_STATUSES.join(" | ")} — got ${JSON.stringify(status)}`));
   }
-  if (metadata !== undefined && !isPlainObject2(metadata)) {
-    violations.push(violation3("medium", "status.plan-row.invalid-metadata", "metadata must be an object"));
+  if (metadata !== undefined && !isPlainObject3(metadata)) {
+    violations.push(violation4("medium", "status.plan-row.invalid-metadata", "metadata must be an object"));
   }
-  if (execution_lease !== undefined && !isPlainObject2(execution_lease)) {
-    violations.push(violation3("medium", "status.plan-row.invalid-execution-lease", "execution_lease 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 (status === "Done" && execution_lease !== undefined) {
-    violations.push(violation3("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(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"'));
   }
   return { ok: violations.length === 0, violations };
 }
 function validateResidual(entry) {
   const violations = [];
-  if (!isPlainObject2(entry)) {
-    return { ok: false, violations: [violation3("high", "status.residual.invalid", "residual entry must be an object")] };
+  if (!isPlainObject3(entry)) {
+    return { ok: false, violations: [violation4("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;
-  validateNonEmptyString2(violations, id, "id", "status.residual.missing-id", "status.residual.invalid-id");
-  validateNonEmptyString2(violations, title, "title", "status.residual.missing-title", "status.residual.invalid-title");
-  validateNonEmptyString2(violations, source, "source", "status.residual.missing-source", "status.residual.invalid-source");
-  validateNonEmptyString2(violations, scope, "scope", "status.residual.missing-scope", "status.residual.invalid-scope");
-  validateNonEmptyString2(violations, owner, "owner", "status.residual.missing-owner", "status.residual.invalid-owner");
+  validateNonEmptyString3(violations, id, "id", "status.residual.missing-id", "status.residual.invalid-id");
+  validateNonEmptyString3(violations, title, "title", "status.residual.missing-title", "status.residual.invalid-title");
+  validateNonEmptyString3(violations, source, "source", "status.residual.missing-source", "status.residual.invalid-source");
+  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(violation3("high", "status.residual.missing-severity", "missing required field: severity"));
+    violations.push(violation4("high", "status.residual.missing-severity", "missing required field: severity"));
   } else if (typeof severity !== "string" || !SEVERITY_ORDER.includes(severity) && severity !== "warning") {
-    violations.push(violation3("medium", "status.residual.invalid-severity", `severity must be one of ${SEVERITY_ORDER.join(" | ")} — got ${JSON.stringify(severity)}`));
+    violations.push(violation4("medium", "status.residual.invalid-severity", `severity must be one of ${SEVERITY_ORDER.join(" | ")} — got ${JSON.stringify(severity)}`));
   } else if (severity === "warning") {
-    violations.push(violation3("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(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')`));
   }
   if (decision === undefined) {
-    violations.push(violation3("high", "status.residual.missing-decision", "missing required field: decision"));
+    violations.push(violation4("high", "status.residual.missing-decision", "missing required field: decision"));
   } else if (typeof decision !== "string" || !RESIDUAL_DECISIONS.includes(decision)) {
-    violations.push(violation3("medium", "status.residual.invalid-decision", `decision must be one of ${RESIDUAL_DECISIONS.join(" | ")} — got ${JSON.stringify(decision)}`));
+    violations.push(violation4("medium", "status.residual.invalid-decision", `decision must be one of ${RESIDUAL_DECISIONS.join(" | ")} — got ${JSON.stringify(decision)}`));
   }
   if (target === undefined) {
-    violations.push(violation3("high", "status.residual.missing-target", "missing required field: target"));
+    violations.push(violation4("high", "status.residual.missing-target", "missing required field: target"));
   } else if (typeof target !== "string" && target !== null) {
-    violations.push(violation3("medium", "status.residual.invalid-target", "target must be a string or null"));
+    violations.push(violation4("medium", "status.residual.invalid-target", "target must be a string or null"));
   }
   if (tracking === undefined) {
-    violations.push(violation3("high", "status.residual.missing-tracking", "missing required field: tracking"));
+    violations.push(violation4("high", "status.residual.missing-tracking", "missing required field: tracking"));
   } else if (typeof tracking !== "string" && tracking !== null) {
-    violations.push(violation3("medium", "status.residual.invalid-tracking", "tracking must be a string or null"));
+    violations.push(violation4("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(violation3("medium", "status.residual.invalid-detail-doc", "detail_doc must be a string or null"));
+    violations.push(violation4("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(violation3("medium", "status.residual.invalid-closed-at", "closed_at must be YYYY-MM-DD"));
+    violations.push(violation4("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(violation3("medium", "status.residual.invalid-lifecycle", `lifecycle must be one of ${RESIDUAL_LIFECYCLES.join(" | ")} — got ${JSON.stringify(lifecycle)}`));
+      violations.push(violation4("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(violation3("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(violation4("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(violation3("medium", "status.residual.closed-missing-closure-note", `lifecycle "${lifecycle}" requires closure_note (what changed; how verified)`, "add closure_note explaining the close"));
+        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"));
       }
     }
   }
   return { ok: violations.length === 0, violations };
 }
-function validateStatus(docOrPath) {
+function isHarnessRelativePath(dir) {
+  if (dir.startsWith("/") || dir.startsWith("\\"))
+    return false;
+  if (/^[A-Za-z]:[\\/]/.test(dir))
+    return false;
+  return !dir.split(/[\\/]+/).includes("..");
+}
+function validateWorkflowEntry(entry) {
+  const violations = [];
+  if (!isPlainObject3(entry)) {
+    return {
+      ok: false,
+      violations: [violation4("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"));
+  } 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)}`));
+  }
+  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"));
+  } else if (typeof entry.dir !== "string" || entry.dir.trim() === "") {
+    violations.push(violation4("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)}`));
+  }
+  return { ok: violations.length === 0, violations };
+}
+function validateStatusV2(docOrPath, opts = {}) {
   let doc;
+  let harnessDir = opts.harnessDir;
   if (typeof docOrPath === "string") {
     try {
       doc = readJson(docOrPath);
+      harnessDir = dirname5(resolve5(docOrPath));
     } catch (error) {
       return {
         ok: false,
-        violations: [violation3("high", "status.invalid-json", error.message)]
+        violations: [violation4("high", "status.invalid-json", error.message)]
       };
     }
   } else {
     doc = docOrPath;
   }
-  const violations = [];
-  const { version, updated_at, plans, residual_findings, metadata } = doc;
-  if (version === undefined) {
-    violations.push(violation3("high", "status.missing-version", "missing required field: version"));
-  } else if (typeof version !== "number" || !Number.isInteger(version)) {
-    violations.push(violation3("high", "status.invalid-version", "version must be an integer"));
-  } else if (version !== 1) {
-    violations.push(violation3("medium", "status.unsupported-version", `unsupported status.json schema version ${version} — expected 1`));
-  }
-  if (updated_at === undefined) {
-    violations.push(violation3("high", "status.missing-updated-at", "missing required field: updated_at"));
-  } else if (typeof updated_at !== "string" || !DATE_RE.test(updated_at)) {
-    violations.push(violation3("medium", "status.invalid-updated-at", "updated_at must be YYYY-MM-DD"));
-  }
-  if (plans === undefined) {
-    violations.push(violation3("high", "status.missing-plans", "missing required field: plans"));
-  } else if (!Array.isArray(plans)) {
-    violations.push(violation3("high", "status.invalid-plans", "plans must be an array"));
-  } else {
-    for (const row of plans) {
-      violations.push(...validatePlanRow(row).violations);
-    }
+  if (!isPlainObject3(doc)) {
+    return { ok: false, violations: [violation4("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`")
+      ]
+    };
   }
-  if (residual_findings === undefined) {
-    violations.push(violation3("high", "status.missing-residual-findings", "missing required field: residual_findings (root-only canonical)"));
-  } else if (!isPlainObject2(residual_findings)) {
-    violations.push(violation3("high", "status.invalid-residual-findings", "residual_findings must be an object at root"));
+  if (Array.isArray(doc.plans)) {
+    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`")
+      ]
+    };
+  }
+  if (doc.residual_findings !== undefined) {
+    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`")
+      ]
+    };
+  }
+  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"));
+  }
+  if (doc.workflows === undefined) {
+    violations.push(violation4("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"));
   } else {
-    for (const [planId, list] of Object.entries(residual_findings)) {
-      if (!Array.isArray(list)) {
-        violations.push(violation3("high", "status.residual.invalid-list", `residual_findings["${planId}"] must be an array`));
-      } else if (list.length === 0) {
-        violations.push(violation3("low", "status.residual.empty-key", `residual_findings["${planId}"] is empty — delete the key (no "plan-id": [])`));
-      } else {
-        for (const entry of list) {
-          violations.push(...validateResidual(entry).violations);
+    const seen = new Set;
+    for (const entry of doc.workflows) {
+      violations.push(...validateWorkflowEntry(entry).violations);
+      if (isPlainObject3(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)}`));
         }
+        seen.add(entry.id);
       }
     }
   }
-  if (metadata === undefined) {
-    violations.push(violation3("high", "status.missing-metadata", "missing required field: metadata"));
-  } else if (!isPlainObject2(metadata)) {
-    violations.push(violation3("high", "status.invalid-metadata", "metadata must be an object"));
-  } else if (Object.prototype.hasOwnProperty.call(metadata, "residual_findings")) {
-    violations.push(violation3("medium", "status.dual-write-residuals", "residual_findings must be root-only — metadata.residual_findings is legacy read-only; remove it (no dual-write)", "move entries to root residual_findings and delete metadata.residual_findings"));
+  if (harnessDir !== undefined && Array.isArray(doc.workflows)) {
+    let realHarnessDir = null;
+    try {
+      realHarnessDir = realpathSync(harnessDir);
+    } catch {}
+    for (const entry of doc.workflows) {
+      if (!isPlainObject3(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 = 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`));
+        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)}`));
+        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}`));
+        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`));
+      }
+      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`));
+      }
+      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)} — the root entry mirrors the snapshot; align them`));
+      }
+    }
   }
   return { ok: violations.length === 0, violations };
 }
-async function archiveResiduals(planId, harnessDir) {
-  const dir = harnessDir !== undefined ? resolve4(harnessDir) : resolveHarnessDir();
-  if (dir === null) {
-    throw new Error(`harness dir not found from ${process.cwd()} — pass harnessDir or set MSTAR_HARNESS_DIR`);
-  }
-  assertSafePathComponent(planId, "planId");
-  const statusPath = join4(dir, "status.json");
-  if (!existsSync2(statusPath)) {
-    throw new Error(`status file not found: ${statusPath}`);
+var validateStatus = validateStatusV2;
+async function registerWorkflow(root, entry) {
+  const entryGate = validateWorkflowEntry(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 harnessDir = dirname5(statusPath);
   return withStatusWriteLock(statusPath, () => {
-    const doc = readJson(statusPath);
-    if (!isPlainObject2(doc.residual_findings)) {
-      throw new Error(`status.json residual_findings must be an object: ${statusPath}`);
-    }
-    const open = doc.residual_findings[planId];
-    const archivePath = join4(dir, "archived", "residuals", `${planId}.json`);
-    if (!Array.isArray(open) || open.length === 0) {
-      return { planId, archived: 0, archivePath };
-    }
-    const archive = readJson(archivePath);
-    const existing = Array.isArray(archive.entries) ? archive.entries : [];
-    const existingIds = new Set(existing.map((e) => isPlainObject2(e) && typeof e.id === "string" ? e.id : undefined).filter((id) => id !== undefined));
-    const today = todayString();
-    const moved = open.filter((entry) => {
-      if (!isPlainObject2(entry) || typeof entry.id !== "string")
-        return true;
-      return !existingIds.has(entry.id);
-    }).map((entry) => ({ ...entry, archived_at: today }));
-    if (moved.length > 0) {
-      writeJson(archivePath, { plan_id: planId, schema_version: 1, entries: [...existing, ...moved] });
+    const current = readJson(statusPath);
+    const fresh = Object.keys(current).length === 0;
+    const doc = fresh ? { version: 2, updated_at: todayString(), workflows: [] } : current;
+    if (!fresh && !Array.isArray(doc.workflows)) {
+      throw new Error("refusing to modify status.json: workflows must be an array — a v1 root must be migrated first (run `mstar migrate`)");
+    }
+    const existing = doc.workflows.findIndex((wf) => wf.id === entry.id);
+    if (existing >= 0) {
+      doc.workflows[existing] = entry;
+    } else {
+      doc.workflows.push(entry);
+    }
+    doc.updated_at = todayString();
+    const gate = validateStatusV2(doc, { harnessDir });
+    if (!gate.ok) {
+      throw new Error(`refusing to write invalid status.json: ${gate.violations.map((v) => v.message).join("; ")}`);
     }
-    delete doc.residual_findings[planId];
-    doc.updated_at = today;
     writeJson(statusPath, doc);
-    return { planId, archived: moved.length, archivePath };
+    return doc;
   });
 }
-function planFindingsCleanup(doc, planId) {
-  if (!Array.isArray(doc.plans))
-    return;
-  for (const row of doc.plans) {
-    if (!isPlainObject2(row))
-      continue;
-    const rowId = row.id ?? row.plan_id;
-    if (rowId !== planId)
-      continue;
-    if (!isPlainObject2(row.metadata))
-      return;
-    const mode = row.metadata.findings_cleanup;
-    if (mode === "zero-residual" || mode === "allow-residual")
-      return mode;
-    return;
+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");
   }
-  return;
-}
-function openResidualsOf(doc, planId) {
-  if (!isPlainObject2(doc.residual_findings))
-    return [];
-  const list = doc.residual_findings[planId];
-  if (!Array.isArray(list))
-    return [];
-  return list.filter((entry) => isPlainObject2(entry) && isOpenResidual(entry));
-}
-function findingsCleanupGate(doc, planId, opts) {
-  const mode = opts?.mode ?? planFindingsCleanup(doc, planId) ?? "allow-residual";
-  const violations = [];
-  const residuals = openResidualsOf(doc, planId);
-  for (const entry of residuals) {
-    const id = typeof entry.id === "string" ? entry.id : "<unnamed>";
-    const label = `R#${id}`;
-    if (mode === "zero-residual") {
-      if (entry.severity === "nit") {
-        violations.push(violation3("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(violation3("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(violation3("medium", "findings.zero-residual-defer-no-target", `${label}: blocker-defer requires a target (next iteration/milestone) under zero-residual`));
-        }
-      } else {
-        violations.push(violation3("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(violation3("high", "findings.allow-residual-critical", `${label}: unresolved critical blocks Approve with residuals`));
+  const statusPath = resolve5(root);
+  const harnessDir = dirname5(statusPath);
+  return withStatusWriteLock(statusPath, () => {
+    const current = readJson(statusPath);
+    if (Object.keys(current).length === 0) {
+      return { version: 2, updated_at: todayString(), workflows: [] };
     }
-  }
-  return { ok: violations.length === 0, violations };
+    const doc = current;
+    if (!Array.isArray(doc.workflows)) {
+      throw new Error("refusing to modify status.json: workflows must be an array — a v1 root must be migrated first (run `mstar migrate`)");
+    }
+    const remaining = doc.workflows.filter((wf) => wf.id !== id);
+    if (remaining.length === doc.workflows.length) {
+      return doc;
+    }
+    doc.workflows = remaining;
+    doc.updated_at = todayString();
+    const gate = validateStatusV2(doc, { harnessDir });
+    if (!gate.ok) {
+      throw new Error(`refusing to write invalid status.json: ${gate.violations.map((v) => v.message).join("; ")}`);
+    }
+    writeJson(statusPath, doc);
+    return doc;
+  });
 }
 function resolveCompassEnforcement(harnessDir) {
   const iterationsDir = resolveIterationDir(harnessDir);
@@ -1110,12 +1405,12 @@ function resolveCompassEnforcement(harnessDir) {
   for (const entry of entries) {
     if (!entry.isDirectory())
       continue;
-    const compassPath = join4(iterationsDir, entry.name, "delivery-compass.md");
+    const compassPath = join6(iterationsDir, entry.name, "delivery-compass.md");
     if (!existsSync2(compassPath))
       continue;
     let content;
     try {
-      content = readFileSync3(compassPath, "utf8");
+      content = readFileSync4(compassPath, "utf8");
     } catch {
       continue;
     }
@@ -1129,58 +1424,26 @@ function resolveCompassEnforcement(harnessDir) {
   }
   return { hard: false, source: "none" };
 }
-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 resolveMstarcEnforcement(harnessDir) {
+  const dir = resolve5(harnessDir);
+  const rc = loadMstarc(dir, dirname5(dir));
+  const value = rc?.config.enforcement;
+  if (value === "hard")
+    return { hard: true, source: "mstarc" };
+  if (value === "soft")
+    return { hard: false, source: "mstarc" };
+  return { hard: false, source: "none" };
 }
-function techDebtRollup(docOrPath) {
-  const doc = typeof docOrPath === "string" ? readJson(docOrPath) : docOrPath;
-  const canonical = isPlainObject2(doc.residual_findings) ? doc.residual_findings : {};
-  const metadata = isPlainObject2(doc.metadata) ? doc.metadata : {};
-  const legacy = isPlainObject2(metadata.residual_findings) ? metadata.residual_findings : {};
-  const merged = { ...canonical, ...legacy };
-  const items = [];
-  for (const [plan, list] of Object.entries(merged)) {
-    if (!Array.isArray(list))
-      continue;
-    for (const value of list) {
-      if (!isPlainObject2(value) || !isOpenResidual(value))
-        continue;
-      items.push({ plan, entry: value });
-    }
-  }
-  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 storedRaw = metadata.tech_debt_summary ?? null;
-  const stored = storedRaw === null ? null : storedRaw;
-  const checks = ROLLUP_FIELDS.map((field) => {
-    const computedField = computed[field];
-    if (stored === null)
-      return { field, status: "DRIFT" };
-    const storedField = stored[field];
-    const storedCompared = storedField === false ? null : storedField ?? null;
-    const status = JSON.stringify(computedField) === JSON.stringify(storedCompared) ? "PASS" : "DRIFT";
-    return { field, status };
-  });
-  const overall = checks.every((check) => check.status === "PASS") ? "PASS" : "DRIFT";
-  return { computed, stored, checks, overall };
+function resolveRepoEnforcement(harnessDir) {
+  const rc = resolveMstarcEnforcement(harnessDir);
+  if (rc.source !== "none")
+    return rc;
+  return resolveCompassEnforcement(harnessDir);
 }
 // src/worktree.ts
 import { execFileSync as execFileSync2 } from "node:child_process";
 import { existsSync as existsSync3 } from "node:fs";
-import { isAbsolute as isAbsolute3, resolve as resolve5 } from "node:path";
+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;
@@ -1189,7 +1452,7 @@ function probeTimeoutMs() {
   const parsed = Number(raw);
   return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_PROBE_TIMEOUT_MS;
 }
-function violation4(severity, code, message, fix) {
+function violation5(severity, code, message, fix) {
   return { ok: false, severity, code, message, fix };
 }
 function gate(violations) {
@@ -1223,25 +1486,25 @@ function l1PreDispatchCheck(input, opts = {}) {
   const violations = [];
   const { controlWorktreePath, leaseWorktreePath, leaseWorkingBranch, planId } = input;
   if (controlWorktreePath.trim() === "") {
-    violations.push(violation4("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"));
+    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"));
   }
   if (leaseWorktreePath.trim() === "") {
-    violations.push(violation4("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"));
+    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"));
   }
   if (leaseWorkingBranch.trim() === "") {
-    violations.push(violation4("high", "worktree.l1.lease-branch-missing", `execution_lease.working_branch is empty for plan "${planId}"`, "record the lease working_branch before dispatch"));
+    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"));
   }
-  if (controlWorktreePath !== "" && leaseWorktreePath !== "" && resolve5(controlWorktreePath) === resolve5(leaseWorktreePath)) {
-    violations.push(violation4("critical", "worktree.l1.lease-equals-control", `execution_lease.worktree_path "${leaseWorktreePath}" equals metadata.control_worktree_path — the feature worktree MUST differ from the control worktree (L1 isolation; product edits never land in the control checkout)`, "use a distinct feature worktree for the plan (git worktree add <path> <branch>) and update the lease"));
+  if (controlWorktreePath !== "" && leaseWorktreePath !== "" && 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 (leaseWorktreePath !== "" && !existsSync3(leaseWorktreePath)) {
-    violations.push(violation4("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>`));
+    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(violation4("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)"));
+      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(violation4("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`));
+      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`));
     }
   }
   return gate(violations);
@@ -1251,41 +1514,41 @@ function l2PreDispatchCheck(input, opts = {}) {
   const tracks = input.tracks ?? [];
   const seenPaths = new Set;
   if (tracks.length < 1) {
-    violations.push(violation4("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"));
+    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(violation4("high", "worktree.l2.track-invalid", `track ${index + 1} is missing worktreePath and/or workingBranch`, "fill both fields for every track"));
+      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 (!isAbsolute3(track.worktreePath)) {
-      violations.push(violation4("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>)`));
+    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 = resolve5(track.worktreePath);
+    const normalized = resolve6(track.worktreePath);
     if (seenPaths.has(normalized)) {
-      violations.push(violation4("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"));
+      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 (!existsSync3(track.worktreePath)) {
-      violations.push(violation4("high", "worktree.l2.track-missing", `track worktree directory "${track.worktreePath}" does not exist`, `create it before dispatch: git worktree add ${track.worktreePath} ${track.workingBranch}`));
+      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(violation4("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)"));
+      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(violation4("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`));
+      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`));
     }
   });
   return gate(violations);
 }
 function assertControlVsFeaturePath(controlWorktreePath, featureWorktreePath) {
   const violations = [];
-  const samePath = controlWorktreePath === "" && featureWorktreePath === "" || controlWorktreePath !== "" && featureWorktreePath !== "" && resolve5(controlWorktreePath) === resolve5(featureWorktreePath);
+  const samePath = controlWorktreePath === "" && featureWorktreePath === "" || controlWorktreePath !== "" && featureWorktreePath !== "" && resolve6(controlWorktreePath) === resolve6(featureWorktreePath);
   if (samePath) {
-    violations.push(violation4("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"));
+    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);
 }
@@ -1293,9 +1556,9 @@ function assertBranchAlignment(worktreePath, expectedBranch, opts = {}) {
   const violations = [];
   const probe = probeBranch(worktreePath, opts);
   if ("error" in probe) {
-    violations.push(violation4("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)"));
+    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(violation4("high", "worktree.branch-mismatch", `worktree "${worktreePath}" is on branch "${probe.branch}", expected "${expectedBranch}" (Assignment Working branch)`, `checkout ${expectedBranch} in that worktree`));
+    violations.push(violation5("high", "worktree.branch-mismatch", `worktree "${worktreePath}" is on branch "${probe.branch}", expected "${expectedBranch}" (Assignment Working branch)`, `checkout ${expectedBranch} in that worktree`));
   }
   return gate(violations);
 }
@@ -1310,7 +1573,7 @@ function assertQcAlignment(assignments) {
   for (const { key, label } of QC_ALIGNMENT_FIELDS) {
     const distinct = [...new Set(list.map((a) => a[key]))];
     if (distinct.length > 1) {
-      violations.push(violation4("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`));
+      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`));
     }
   }
   return gate(violations);
@@ -1320,19 +1583,19 @@ function singleReviewSnapshot(assignments) {
   const list = assignments ?? [];
   list.forEach((a, index) => {
     if ((a.head ?? "").trim() === "") {
-      violations.push(violation4("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"));
+      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(violation4("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"));
+    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"));
   }
   return gate(violations);
 }
 // src/sdd.ts
 import { execFileSync as execFileSync3 } from "node:child_process";
-import { mkdirSync as mkdirSync4, readFileSync as readFileSync4, realpathSync, statSync as statSync3, writeFileSync as writeFileSync3 } from "node:fs";
-import { basename as basename3, dirname as dirname4, isAbsolute as isAbsolute4, join as join5, resolve as resolve6 } from "node:path";
+import { mkdirSync as mkdirSync5, readdirSync as readdirSync3, readFileSync as readFileSync5, realpathSync as realpathSync2, 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) {
@@ -1343,14 +1606,14 @@ class SddScriptError extends Error {
 }
 function isDirectory2(dir) {
   try {
-    return statSync3(dir).isDirectory();
+    return statSync4(dir).isDirectory();
   } catch {
     return false;
   }
 }
-function isFile(file) {
+function isFile2(file) {
   try {
-    return statSync3(file).isFile();
+    return statSync4(file).isFile();
   } catch {
     return false;
   }
@@ -1369,25 +1632,48 @@ function gitOut(cwd, args) {
   }
 }
 function probeHarnessWithStatus(root) {
-  if (isFile(join5(root, ".mstar", "status.json")))
-    return join5(root, ".mstar");
-  if (isFile(join5(root, ".agents", "status.json")))
-    return join5(root, ".agents");
+  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;
+  try {
+    workflowsDir = resolveWorkflowDir(harnessDir, { harnessDir });
+  } catch {
+    workflowsDir = join7(harnessDir, "workflows");
+  }
+  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;
+    }
+  } 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 = isAbsolute4(gitDirRaw) ? gitDirRaw : join5(root, gitDirRaw);
-  const common = isAbsolute4(commonRaw) ? commonRaw : join5(root, commonRaw);
+  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;
   try {
-    const gdParent = realpathSync(dirname4(gitDir));
-    const cmAbs = realpathSync(common);
-    return join5(gdParent, basename3(gitDir)) !== cmAbs && gitDir !== cmAbs;
+    const gdParent = realpathSync2(dirname6(gitDir));
+    const cmAbs = realpathSync2(common);
+    return join7(gdParent, basename3(gitDir)) !== cmAbs && gitDir !== cmAbs;
   } catch {
     return false;
   }
@@ -1404,10 +1690,10 @@ function sddWorkspace(planId, opts = {}) {
     if (!isDirectory2(controlRoot)) {
       throw new SddScriptError(`mstar sdd workspace: CONTROL_ROOT / MSTAR_CONTROL_ROOT is not a directory: ${controlRoot}`, 1);
     }
-    root = realpathSync(controlRoot);
+    root = realpathSync2(controlRoot);
   } else {
     const topLevel = gitOut(cwd, ["rev-parse", "--show-toplevel"]);
-    root = realpathSync(topLevel ?? cwd);
+    root = realpathSync2(topLevel ?? cwd);
   }
   if (!controlRoot && isLinkedWorktree(root)) {
     throw new SddScriptError(`mstar sdd workspace: linked worktree at ${root} has no {HARNESS_DIR}/status.json (default gitignore).
@@ -1418,24 +1704,30 @@ function sddWorkspace(planId, opts = {}) {
   const harnessOverride = opts.harnessDir ?? (process.env.MSTAR_HARNESS_DIR || undefined);
   let harnessDir;
   if (harnessOverride) {
-    harnessDir = resolve6(root, harnessOverride);
+    harnessDir = resolve7(root, harnessOverride);
   } else {
-    const probed = probeHarnessWithStatus(root);
-    if (probed) {
-      harnessDir = probed;
-    } else if (isDirectory2(join5(root, ".mstar"))) {
-      harnessDir = join5(root, ".mstar");
-    } else if (isDirectory2(join5(root, ".agents"))) {
-      harnessDir = join5(root, ".agents");
+    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 {
-      harnessDir = join5(root, ".mstar");
+      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 sddDir = resolveSddDir(harnessDir, planId);
-  mkdirSync4(sddDir, { recursive: true });
-  writeFileSync3(join5(sddDir, ".gitignore"), `*
+  mkdirSync5(sddDir, { recursive: true });
+  writeFileSync3(join7(sddDir, ".gitignore"), `*
 `);
-  return realpathSync(sddDir);
+  return realpathSync2(sddDir);
 }
 function taskBrief(planFile, taskN, outFile, opts = {}) {
   if (!planFile || !Number.isInteger(taskN) || taskN < 1) {
@@ -1443,7 +1735,7 @@ function taskBrief(planFile, taskN, outFile, opts = {}) {
   }
   let content;
   try {
-    content = readFileSync4(planFile, "utf8");
+    content = readFileSync5(planFile, "utf8");
   } catch {
     throw new SddScriptError(`no such plan file: ${planFile}`, 2);
   }
@@ -1455,8 +1747,8 @@ function taskBrief(planFile, taskN, outFile, opts = {}) {
     if (!sddDir) {
       throw new SddScriptError("mstar sdd task-brief: set SDD_DIR or pass OUTFILE (run mstar sdd workspace PLAN_ID first)", 2);
     }
-    mkdirSync4(sddDir, { recursive: true });
-    out = join5(sddDir, `task-${taskN}-brief.md`);
+    mkdirSync5(sddDir, { recursive: true });
+    out = join7(sddDir, `task-${taskN}-brief.md`);
   }
   const records = content.endsWith(`
 `) ? content.split(`
@@ -1506,10 +1798,10 @@ function reviewPackage(base, head, outFile, opts = {}) {
     if (!sddDir) {
       throw new SddScriptError("mstar sdd review-package: set SDD_DIR or pass OUTFILE", 2);
     }
-    mkdirSync4(sddDir, { recursive: true });
+    mkdirSync5(sddDir, { recursive: true });
     const shortBase = gitOut(cwd, ["rev-parse", "--short", base]) ?? base;
     const shortHead = gitOut(cwd, ["rev-parse", "--short", head]) ?? head;
-    out = join5(sddDir, `review-${shortBase}..${shortHead}.diff`);
+    out = join7(sddDir, `review-${shortBase}..${shortHead}.diff`);
   }
   const run = (args) => execFileSync3("git", args, { cwd, maxBuffer: GIT_CAPTURE_MAX_BYTES });
   const parts = [
@@ -1545,7 +1837,7 @@ function assertBaseSha(ref, opts = {}) {
 }
 function taskReportExists(sddDir, taskN) {
   try {
-    const st = statSync3(join5(sddDir, `task-${taskN}-report.md`));
+    const st = statSync4(join7(sddDir, `task-${taskN}-report.md`));
     return st.isFile() && st.size > 0;
   } catch {
     return false;
@@ -1554,7 +1846,7 @@ function taskReportExists(sddDir, taskN) {
 function readProgressLedger(sddDir) {
   let content;
   try {
-    content = readFileSync4(join5(sddDir, "progress.md"), "utf8");
+    content = readFileSync5(join7(sddDir, "progress.md"), "utf8");
   } catch {
     return [];
   }
@@ -1587,8 +1879,8 @@ function implementerSessionStickyRules(input) {
   return { resume: true, reason: `sticky resume OK: host_agent_id ${session.host_agent_id}, next task ${nextTask}` };
 }
 // src/iteration.ts
-import { existsSync as existsSync4, readdirSync as readdirSync3, readFileSync as readFileSync5 } from "node:fs";
-import { join as join6 } from "node:path";
+import { existsSync as existsSync4, 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";
@@ -1666,18 +1958,18 @@ function validateCompassShape(doc) {
     }
   };
 }
-function violation5(severity, code, message, fix) {
+function violation6(severity, code, message, fix) {
   return { ok: false, severity, code, message, fix };
 }
-function isPlainObject3(value) {
+function isPlainObject4(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function validateCompassFrontmatter(doc) {
-  if (!isPlainObject3(doc)) {
+  if (!isPlainObject4(doc)) {
     return {
       ok: false,
       violations: [
-        violation5("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")
+        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")
       ]
     };
   }
@@ -1687,17 +1979,17 @@ function validateCompassFrontmatter(doc) {
       ok: false,
       violations: parsed.issues.map((issue) => {
         const field = issue.path.join(".") || "(root)";
-        return violation5("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)`);
+        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)`);
       })
     };
   }
   const violations = [];
   const { status, end_date } = parsed.data;
   if (status === "completed" && end_date === undefined) {
-    violations.push(violation5("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"));
+    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(violation5("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"));
+    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"));
   }
   return { ok: violations.length === 0, violations };
 }
@@ -1706,11 +1998,11 @@ function registeredPlanIds(compassDoc) {
     return [];
   return compassDoc.plans.filter((plan) => typeof plan === "string" && plan.length > 0);
 }
-function findPlanRow(statusDoc, planId) {
-  if (!Array.isArray(statusDoc.plans))
+function findPlanRow(snapshotDoc, planId) {
+  if (!Array.isArray(snapshotDoc.plans))
     return null;
-  for (const row of statusDoc.plans) {
-    if (!isPlainObject3(row))
+  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)
@@ -1718,65 +2010,35 @@ function findPlanRow(statusDoc, planId) {
   }
   return null;
 }
-function entryPlansAllDone(statusDoc, registered) {
+function entryPlansAllDone(snapshotDoc, registered) {
   const violations = [];
   if (registered.length === 0) {
-    violations.push(violation5("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`"));
+    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(statusDoc, planId);
+    const row = findPlanRow(snapshotDoc, planId);
     if (row === null) {
-      violations.push(violation5("high", "PLAN_NOT_IN_STATUS", `Plan '${planId}' is registered in the compass frontmatter but has no row in status.json plans[] (mstar-iteration §3.1 entry item 1)`, "Add the plan row to {HARNESS_DIR}/status.json"));
+      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(violation5("high", "PLAN_NOT_DONE", `Plan '${planId}' status is ${JSON.stringify(row.status)} in status.json — all compass-registered plans must be 'Done' before iteration-close (mstar-iteration §3.1 entry item 1)`));
+      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)`));
     }
   }
   return violations;
 }
-function entryResidualsOpen(statusDoc, planId) {
-  const violations = [];
-  const residualRoot = statusDoc.residual_findings;
-  if (residualRoot === undefined || residualRoot === null)
-    return violations;
-  if (!isPlainObject3(residualRoot)) {
-    violations.push(violation5("medium", "RESIDUAL_MALFORMED", "status.json residual_findings must be a plan-id → entries object (mstar-iteration §3.1 entry item 2)"));
-    return violations;
-  }
-  const entries = residualRoot[planId];
-  if (entries === undefined)
-    return violations;
-  if (!Array.isArray(entries)) {
-    violations.push(violation5("medium", "RESIDUAL_MALFORMED", `status.json residual_findings['${planId}'] must be an array of residual entries (mstar-iteration §3.1 entry item 2)`));
-    return violations;
-  }
-  const openIds = [];
-  for (const entry of entries) {
-    if (!isPlainObject3(entry) || !isOpenResidual(entry))
-      continue;
-    const isBlockerDefer = entry.decision === "defer" && typeof entry.target === "string" && entry.target.trim() !== "";
-    if (isBlockerDefer)
-      continue;
-    openIds.push(typeof entry.id === "string" ? entry.id : "<unnamed>");
-  }
-  if (openIds.length > 0) {
-    violations.push(violation5("high", "OPEN_RESIDUALS", `Plan '${planId}' has ${openIds.length} open residual finding(s) not exempted as blocker-defers (${openIds.join(", ")}) — residuals must be closed/archived before iteration-close; only zero-residual blocker-defers (decision: defer + target) may stay open (mstar-iteration §3.1 entry item 2)`, "Close or archive the open residuals, or convert them into blocker-defers (decision: defer + non-empty target) per mstar-plan-artifacts Findings cleanup modes"));
-  }
-  return violations;
-}
 function entryFrontmatterComplete(compassDoc) {
   return validateCompassFrontmatter(compassDoc).violations;
 }
 function exitFrontmatterClosed(compassDoc) {
   const violations = [];
   if (compassDoc.status !== "completed") {
-    violations.push(violation5("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)`));
+    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(violation5("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)"));
+    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;
 }
@@ -1784,9 +2046,9 @@ function exitBranchCheck(opts) {
   const violations = [];
   const { currentBranch, specIntegrationBranch } = opts;
   if (currentBranch === undefined || specIntegrationBranch === undefined) {
-    violations.push(violation5("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)"));
+    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(violation5("high", "EXIT_BRANCH_MISMATCH", `Current branch '${currentBranch}' is not the spec_integration_branch '${specIntegrationBranch}' (mstar-iteration §3.5 exit item 5)`));
+    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;
 }
@@ -1795,17 +2057,16 @@ function exitPrBaseCheck(compassDoc, opts) {
   const target = compassDoc.target_branch;
   const { prBaseBranch } = opts;
   if (prBaseBranch === undefined) {
-    violations.push(violation5("medium", "EXIT_PR_BASE_UNVERIFIABLE", "Cannot verify the PR base — missing prBaseBranch probe input (mstar-iteration §3.5 exit item 6)"));
+    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(violation5("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)`));
+    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)`));
   }
   return violations;
 }
-function evaluatePhaseGate(statusDoc, compassDoc, opts = {}) {
+function evaluatePhaseGate(snapshotDoc, compassDoc, opts = {}) {
   const registered = registeredPlanIds(compassDoc);
   const entryViolations = [
-    ...entryPlansAllDone(statusDoc, registered),
-    ...registered.flatMap((planId) => entryResidualsOpen(statusDoc, planId)),
+    ...entryPlansAllDone(snapshotDoc, registered),
     ...entryFrontmatterComplete(compassDoc)
   ];
   const exitViolations = [
@@ -1814,7 +2075,7 @@ function evaluatePhaseGate(statusDoc, compassDoc, opts = {}) {
     ...exitPrBaseCheck(compassDoc, opts)
   ];
   const allPlansDone = registered.length > 0 && registered.every((planId) => {
-    const row = findPlanRow(statusDoc, planId);
+    const row = findPlanRow(snapshotDoc, planId);
     return row !== null && row.status === PLAN_STATUS_DONE;
   });
   const entry = { ok: entryViolations.length === 0, violations: entryViolations };
@@ -1839,10 +2100,10 @@ function evaluatePhaseGate(statusDoc, compassDoc, opts = {}) {
 function pushCadenceProbe(ciRunning, reviewWaveActive) {
   const violations = [];
   if (ciRunning) {
-    violations.push(violation5("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"));
+    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(violation5("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"));
+    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 };
 }
@@ -1851,24 +2112,24 @@ function assertIndexRowObligations(iterationsDir) {
     return {
       ok: false,
       violations: [
-        violation5("high", "INDEX_ITERATIONS_DIR_MISSING", `{ITERATION_DIR} '${iterationsDir}' does not exist (mstar-iteration §1.4)`, "Create the iterations directory (path.resolveIterationDir)")
+        violation6("high", "INDEX_ITERATIONS_DIR_MISSING", `{ITERATION_DIR} '${iterationsDir}' does not exist (mstar-iteration §1.4)`, "Create the iterations directory (path.resolveIterationDir)")
       ]
     };
   }
-  const iterationIds = readdirSync3(iterationsDir, { withFileTypes: true }).filter((entry) => entry.isDirectory()).filter((entry) => existsSync4(join6(iterationsDir, entry.name, COMPASS_FILE))).map((entry) => entry.name).sort();
-  const readmePath = join6(iterationsDir, INDEX_README);
+  const iterationIds = readdirSync4(iterationsDir, { withFileTypes: true }).filter((entry) => entry.isDirectory()).filter((entry) => existsSync4(join8(iterationsDir, entry.name, COMPASS_FILE))).map((entry) => entry.name).sort();
+  const readmePath = join8(iterationsDir, INDEX_README);
   if (!existsSync4(readmePath)) {
     return {
       ok: false,
       violations: [
-        violation5("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`)
+        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`)
       ]
     };
   }
   const violations = [];
-  const lines = readFileSync5(readmePath, "utf8").split(/\r?\n/);
+  const lines = readFileSync6(readmePath, "utf8").split(/\r?\n/);
   if (!lines.some((line) => line.includes(INDEX_HEADER))) {
-    violations.push(violation5("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"));
+    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"));
   }
   const indexed = new Set;
   for (const line of lines) {
@@ -1878,13 +2139,15 @@ function assertIndexRowObligations(iterationsDir) {
   }
   for (const id of iterationIds) {
     if (!indexed.has(id)) {
-      violations.push(violation5("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> |`));
+      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> |`));
     }
   }
   return { ok: violations.length === 0, violations };
 }
 function parseCompassFrontmatter(filePath) {
-  const content = readFileSync5(filePath, "utf8");
+  return parseCompassFrontmatterText(readFileSync6(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 "---")`);
@@ -1945,8 +2208,795 @@ function parseFlowArray(raw, filePath) {
   }
   return items;
 }
+// src/project.ts
+import { existsSync as existsSync5, 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);
+}
+function violation7(severity, code, message, fix) {
+  return { ok: false, severity, code, message, fix };
+}
+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`));
+  }
+}
+function validateRoadmap(filePath) {
+  const violations = [];
+  let content;
+  try {
+    content = readFileSync7(filePath, "utf8");
+  } catch {
+    return {
+      ok: false,
+      violations: [violation7("high", "project.roadmap.unreadable", `cannot read roadmap file: ${filePath}`)],
+      warnings: []
+    };
+  }
+  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: [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"));
+  }
+  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"));
+  }
+  return { ok: violations.length === 0, violations, warnings };
+}
+function linesIndexOfClosingFence(content) {
+  return content.split(/\r?\n/).indexOf("---", 1);
+}
+function validateProjectRegister(doc) {
+  const violations = [];
+  if (!isPlainObject5(doc)) {
+    return {
+      ok: false,
+      violations: [violation7("high", "project.register.invalid", "project register must be an object")]
+    };
+  }
+  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`));
+        }
+      }
+    }
+  }
+  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 };
+  }
+  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 };
+  }
+  if (entries.length === 0) {
+    return { ok: true, violations };
+  }
+  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`));
+        }
+      } 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`));
+      }
+    } 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 };
+}
+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 techDebtRollup(projectDir) {
+  const items = [];
+  let entries;
+  try {
+    entries = readdirSync5(projectDir, { withFileTypes: true });
+  } catch {
+    entries = [];
+  }
+  for (const project of entries) {
+    if (!project.isDirectory())
+      continue;
+    const registerPath = join9(projectDir, project.name, PROJECT_REGISTER_FILE);
+    if (!existsSync5(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 });
+      }
+    }
+  }
+  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 listProjectReferenceFiles(projectDir) {
+  const root = join9(projectDir, PROJECT_REFERENCES_DIR);
+  let entries;
+  try {
+    entries = readdirSync5(root, { withFileTypes: true });
+  } 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 files.sort();
+}
+// src/migrate.ts
+import { copyFileSync, mkdirSync as mkdirSync6, readFileSync as readFileSync8, readdirSync as readdirSync6, writeFileSync as writeFileSync4 } 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";
+var NOTES_LEDGER_FILE = "notes.jsonl";
+var DATE_RE4 = /^\d{4}-\d{2}-\d{2}$/;
+var ROOT_METADATA_LIFT_KEYS = {
+  plan_parallelism: true,
+  worktree_mode: true,
+  push_policy: true,
+  iteration_base_branch: true,
+  target_branch: true,
+  spec_integration_branch: true,
+  control_worktree_path: true,
+  integration_merge_lease: true,
+  program_roadmap: true,
+  updated_at: true
+};
+function isPlainObject6(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function dateString(value) {
+  return typeof value === "string" && DATE_RE4.test(value) ? value : undefined;
+}
+function rowIdOf(row) {
+  if (typeof row.id === "string" && row.id.trim() !== "")
+    return row.id;
+  if (typeof row.plan_id === "string" && row.plan_id.trim() !== "")
+    return row.plan_id;
+  return null;
+}
+function compareIds(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+function todayString2() {
+  const now = new Date;
+  const month = String(now.getMonth() + 1).padStart(2, "0");
+  const day = String(now.getDate()).padStart(2, "0");
+  return `${now.getFullYear()}-${month}-${day}`;
+}
+function scanCompasses(harnessDir) {
+  const iterationsDir = join10(harnessDir, "iterations");
+  const out = [];
+  let entries;
+  try {
+    entries = readdirSync6(iterationsDir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory())
+      continue;
+    const compassPath = join10(iterationsDir, entry.name, "delivery-compass.md");
+    let content;
+    try {
+      content = readFileSync8(compassPath, "utf8");
+    } catch {
+      continue;
+    }
+    const doc = parseCompassFrontmatterText(content, compassPath);
+    const status = doc.status;
+    if (status !== "active" && status !== "locked" && status !== "completed") {
+      throw new Error(`refusing to migrate: compass ${JSON.stringify(compassPath)} has unsupported status ${JSON.stringify(status)} (expected active | locked | completed)`);
+    }
+    const plans = Array.isArray(doc.plans) ? doc.plans.filter((p) => typeof p === "string" && p !== "") : [];
+    out.push({
+      id: typeof doc.iteration_id === "string" && doc.iteration_id !== "" ? doc.iteration_id : entry.name,
+      file: compassPath,
+      status,
+      plans,
+      startDate: dateString(doc.start_date),
+      endDate: dateString(doc.end_date)
+    });
+  }
+  out.sort((a, b) => compareIds(a.id, b.id));
+  return out;
+}
+function pickDate(preferred, fallback) {
+  for (const candidate of preferred) {
+    if (candidate !== undefined)
+      return candidate;
+  }
+  return fallback;
+}
+function groupRows(rows, compasses) {
+  const rowById = new Map;
+  for (const row of rows) {
+    const id = rowIdOf(row);
+    if (id !== null && !rowById.has(id))
+      rowById.set(id, row);
+  }
+  const byPlan = new Map;
+  for (const compass of compasses) {
+    for (const planId of compass.plans) {
+      if (!byPlan.has(planId))
+        byPlan.set(planId, compass);
+    }
+  }
+  return { byPlan, rowById };
+}
+function buildIterationSnapshot(compass, rowById, rootUpdatedAt) {
+  const rows = compass.plans.map((planId) => rowById.get(planId)).filter((row) => row !== undefined);
+  rows.sort((a, b) => compareIds(rowIdOf(a) ?? "", rowIdOf(b) ?? ""));
+  const rowDates = rows.flatMap((row) => [
+    dateString(row.created_at),
+    dateString(row.updated_at),
+    dateString(row.done_at)
+  ]);
+  const startedAt = pickDate([compass.startDate, ...rowDates], rootUpdatedAt);
+  const endedAt = pickDate([compass.endDate, ...rowDates], rootUpdatedAt);
+  const status = compass.status === "completed" ? "completed" : "running";
+  const compactMissing = compass.plans.filter((planId) => !rowById.has(planId)).sort();
+  const snapshot = {
+    schema_version: 1,
+    id: compass.id,
+    type: "iteration",
+    status,
+    started_at: startedAt,
+    ...status === "completed" ? { ended_at: endedAt } : {},
+    updated_at: status === "completed" ? endedAt : startedAt,
+    plans: rows,
+    compass_ref: `iterations/${compass.id}/delivery-compass.md`
+  };
+  const legacyMetadata = {};
+  if (compactMissing.length > 0)
+    legacyMetadata.compact_missing = compactMissing;
+  if (Object.keys(legacyMetadata).length > 0)
+    snapshot.legacy_metadata = legacyMetadata;
+  return {
+    id: compass.id,
+    type: "iteration",
+    status,
+    file: join10("workflows", compass.id, WORKFLOW_SNAPSHOT_FILE),
+    source: join10("iterations", compass.id, "delivery-compass.md"),
+    data: snapshot
+  };
+}
+function buildStandaloneSnapshot(row, rootUpdatedAt, migrationNotes) {
+  const id = rowIdOf(row) ?? "<unnamed>";
+  const statusValue = row.status;
+  let status;
+  if (statusValue === "Done")
+    status = "completed";
+  else if (statusValue === "InProgress" || statusValue === "InReview")
+    status = "running";
+  else if (statusValue === "Todo" || statusValue === "Blocked")
+    status = "paused";
+  else {
+    status = "paused";
+    migrationNotes.push(`row ${JSON.stringify(id)} has unrecognized v1 status ${JSON.stringify(statusValue)} — snapshot status defaults to paused (row status stays verbatim)`);
+  }
+  const startedAt = pickDate([dateString(row.created_at), dateString(row.updated_at)], rootUpdatedAt);
+  const updatedAt = pickDate([dateString(row.updated_at), dateString(row.done_at), dateString(row.created_at)], rootUpdatedAt);
+  const endedAt = pickDate([dateString(row.done_at), dateString(row.updated_at)], rootUpdatedAt);
+  const snapshot = {
+    schema_version: 1,
+    id,
+    type: "plan",
+    status,
+    started_at: startedAt,
+    ...status === "completed" ? { ended_at: endedAt } : {},
+    updated_at: status === "completed" ? endedAt : updatedAt,
+    plans: [row]
+  };
+  return {
+    id,
+    type: "plan",
+    status,
+    file: join10("workflows", id, WORKFLOW_SNAPSHOT_FILE),
+    source: "status.json plans[] row",
+    data: snapshot
+  };
+}
+function applyRootMetadataLift(snapshot, metadata, migrationNotes, activeIterations) {
+  const data = snapshot.data;
+  const policy = {};
+  for (const key of ["plan_parallelism", "worktree_mode", "push_policy"]) {
+    if (metadata[key] !== undefined)
+      policy[key] = metadata[key];
+  }
+  if (Object.keys(policy).length > 0)
+    data.execution_policy = policy;
+  const branch = {};
+  const branchKeys = [
+    ["base", "iteration_base_branch"],
+    ["integration", "spec_integration_branch"],
+    ["target", "target_branch"]
+  ];
+  for (const [target, source] of branchKeys) {
+    const value = metadata[source];
+    if (typeof value === "string" && value !== "")
+      branch[target] = value;
+  }
+  if (Object.keys(branch).length > 0)
+    data.branch = branch;
+  if (typeof metadata.control_worktree_path === "string" && metadata.control_worktree_path !== "") {
+    data.control_worktree_path = metadata.control_worktree_path;
+  }
+  if (isPlainObject6(metadata.integration_merge_lease)) {
+    data.integration_merge_lease = metadata.integration_merge_lease;
+  }
+  const legacyMetadata = isPlainObject6(data.legacy_metadata) ? { ...data.legacy_metadata } : {};
+  for (const [key, value] of Object.entries(metadata)) {
+    if (key === "harness_root")
+      continue;
+    if (ROOT_METADATA_LIFT_KEYS[key] === true)
+      continue;
+    legacyMetadata[key] = value;
+  }
+  if (metadata.harness_root !== undefined) {
+    legacyMetadata.harness_root_note = `dropped as redundant (v2 harness dir derives from status.json location): ${String(metadata.harness_root)}`;
+  }
+  if (Object.keys(legacyMetadata).length > 0)
+    data.legacy_metadata = legacyMetadata;
+  if (activeIterations > 1) {
+    migrationNotes.push(`${activeIterations} active iterations present — root-metadata lifts applied to ${JSON.stringify(snapshot.id)} only`);
+  }
+}
+function buildRoadmap(programRoadmap, projectId, migratedAt) {
+  const title = typeof programRoadmap.title === "string" && programRoadmap.title !== "" ? programRoadmap.title : "Program roadmap";
+  const doc = typeof programRoadmap.doc === "string" ? programRoadmap.doc : "";
+  const completionVersion = typeof programRoadmap.completion_version === "string" ? programRoadmap.completion_version : "";
+  const branch = typeof programRoadmap.branch === "string" ? programRoadmap.branch : "";
+  const milestones = Array.isArray(programRoadmap.slices) ? programRoadmap.slices.map((slice) => String(slice)).filter((slice) => slice !== "") : [];
+  const deferred = Array.isArray(programRoadmap.deferred_beyond) ? programRoadmap.deferred_beyond.map((item) => String(item)).filter((item) => item !== "") : [];
+  const lines = [
+    "---",
+    `project_id: ${projectId}`,
+    `title: ${title}`,
+    "status: active",
+    `created_at: ${migratedAt}`
+  ];
+  if (milestones.length > 0) {
+    lines.push("milestones:");
+    for (const milestone of milestones)
+      lines.push(`  - ${milestone}`);
+  }
+  lines.push("residuals_ref: residuals.json", "---", "", "# Roadmap", "", "## Direction");
+  const provenance = [doc !== "" ? `doc: ${doc}` : "", completionVersion !== "" ? `completion_version: ${completionVersion}` : "", branch !== "" ? `branch: ${branch}` : ""].filter((part) => part !== "").join(", ");
+  lines.push(`Migrated from legacy status.json \`metadata.program_roadmap\`${provenance !== "" ? ` (${provenance})` : ""}.`);
+  if (programRoadmap.no_intermediate_releases !== undefined) {
+    lines.push(`no_intermediate_releases: ${String(programRoadmap.no_intermediate_releases)}`);
+  }
+  if (deferred.length > 0) {
+    lines.push("", "### Deferred beyond", ...deferred.map((item) => `- ${item}`));
+  }
+  lines.push("");
+  return lines.join(`
+`);
+}
+function buildRegister(residualFindings, byPlan, projectId, migratedAt) {
+  const entries = {};
+  const planKeys = Object.keys(residualFindings).sort();
+  for (const planId of planKeys) {
+    const raw = residualFindings[planId];
+    if (!Array.isArray(raw))
+      continue;
+    const open = raw.filter((entry) => isPlainObject6(entry) && isOpenResidual(entry)).sort((a, b) => {
+      const aId = typeof a.id === "string" ? a.id : "";
+      const bId = typeof b.id === "string" ? b.id : "";
+      return compareIds(aId, bId);
+    });
+    if (open.length === 0)
+      continue;
+    const owner = byPlan.get(planId);
+    entries[planId] = open.map((entry) => ({
+      ...entry,
+      source_plan: planId,
+      registered_at: migratedAt,
+      ...owner !== undefined ? { lifecycle_id: owner.id } : {}
+    }));
+  }
+  if (Object.keys(entries).length === 0)
+    return null;
+  const doc = { entries };
+  return {
+    file: join10("projects", projectId, PROJECT_REGISTER_FILE),
+    source: "status.json residual_findings",
+    data: doc
+  };
+}
+function collectNotesFiles(snapshots) {
+  const out = [];
+  for (const snapshot of snapshots) {
+    const lines = [];
+    let source = "";
+    for (const row of snapshot.data.plans) {
+      if (Array.isArray(row.notes)) {
+        source = "status.json plans[].notes arrays";
+        for (const note of row.notes) {
+          if (typeof note !== "string")
+            continue;
+          lines.push(JSON.stringify({ kind: "note", ts: snapshot.data.updated_at, text: note }));
+        }
+      }
+    }
+    if (snapshot.type === "plan" && snapshot.status === "paused") {
+      const row = snapshot.data.plans[0];
+      if (row !== undefined && row.status === "Todo") {
+        source = source === "" ? "status.json plans[] Todo rows (not-started note)" : source;
+        const noteText = typeof row.id === "string" ? `${row.id} not started (v1 row status Todo mapped to snapshot status paused)` : "not started (v1 row status Todo mapped to snapshot status paused)";
+        lines.push(JSON.stringify({ kind: "note", ts: snapshot.data.updated_at, text: noteText }));
+      }
+    }
+    if (lines.length === 0)
+      continue;
+    out.push({
+      file: join10(dirname7(snapshot.file), NOTES_LEDGER_FILE),
+      source,
+      lines
+    });
+  }
+  return out;
+}
+function migrateHarnessTree(root, opts = {}) {
+  const harnessDir = resolve8(root);
+  const workflowDir = resolveWorkflowDir(harnessDir, { harnessDir });
+  const projectDir = resolveProjectDir(harnessDir, { harnessDir });
+  const projectId = opts.projectId ?? _DEFAULT_PROJECT;
+  const statusPath = join10(harnessDir, MIGRATE_STATUS_FILE);
+  const legacy = readJson(statusPath);
+  if (legacy.version === 2) {
+    const updatedAt = typeof legacy.updated_at === "string" && legacy.updated_at !== "" ? legacy.updated_at : "1970-01-01";
+    return {
+      root: harnessDir,
+      workflowDir,
+      projectDir,
+      dryRun: opts.dryRun === true,
+      alreadyMigrated: true,
+      message: `no-op: ${statusPath} is already at schema version 2 (migrated) — nothing to do`,
+      snapshots: [],
+      notesFiles: [],
+      register: null,
+      roadmap: null,
+      rootV2: { file: MIGRATE_STATUS_FILE, data: { version: 2, updated_at: updatedAt, workflows: [] } },
+      archive: { file: ARCHIVED_STATUS_V1_FILE, source: MIGRATE_STATUS_FILE },
+      migrationNotes: [],
+      steps: []
+    };
+  }
+  if (legacy.version !== undefined && legacy.version !== 1) {
+    throw new Error(`refusing to migrate: ${statusPath} has unrecognized schema version ${JSON.stringify(legacy.version)} (expected 1)`);
+  }
+  if (legacy.version === undefined) {
+    throw new Error(`refusing to migrate: no v1 status.json found at ${statusPath} (nothing to migrate)`);
+  }
+  const rows = Array.isArray(legacy.plans) ? legacy.plans.filter(isPlainObject6) : [];
+  if (Array.isArray(legacy.plans)) {
+    const unLiftable = [];
+    const idCounts = new Map;
+    for (const row of legacy.plans) {
+      if (!isPlainObject6(row) || rowIdOf(row) === null) {
+        unLiftable.push(row);
+        continue;
+      }
+      const id = rowIdOf(row);
+      assertSafePathComponent(id, "plan id");
+      idCounts.set(id, (idCounts.get(id) ?? 0) + 1);
+    }
+    if (unLiftable.length > 0) {
+      throw new Error(`refusing to migrate: ${unLiftable.length} plans[] row(s) cannot be lifted (missing id/plan_id or not an object) — every v1 row must land in exactly one snapshot`);
+    }
+    const duplicates = [...idCounts.entries()].filter(([, count]) => count > 1).map(([id]) => id);
+    if (duplicates.length > 0) {
+      throw new Error(`refusing to migrate: ${duplicates.length} duplicate plan id(s) (${duplicates.join(", ")}) — every v1 row must land in exactly one snapshot`);
+    }
+  }
+  const metadata = isPlainObject6(legacy.metadata) ? legacy.metadata : {};
+  const rootUpdatedAt = dateString(legacy.updated_at) ?? dateString(metadata.updated_at) ?? todayString2();
+  const migratedAt = dateString(metadata.updated_at) ?? rootUpdatedAt;
+  const migrationNotes = [];
+  const compasses = scanCompasses(harnessDir);
+  for (const compass of compasses) {
+    assertSafePathComponent(compass.id, "iteration id");
+  }
+  assertSafePathComponent(projectId, "projectId");
+  const { byPlan, rowById } = groupRows(rows, compasses);
+  const snapshots = compasses.map((compass) => buildIterationSnapshot(compass, rowById, rootUpdatedAt));
+  for (const row of rows) {
+    const id = rowIdOf(row);
+    if (id !== null && !byPlan.has(id))
+      snapshots.push(buildStandaloneSnapshot(row, rootUpdatedAt, migrationNotes));
+  }
+  const lifecycleSources = new Map;
+  for (const snapshot of snapshots) {
+    const sources = lifecycleSources.get(snapshot.id) ?? [];
+    sources.push(snapshot.type === "iteration" ? "iteration" : "standalone plan");
+    lifecycleSources.set(snapshot.id, sources);
+  }
+  const projectSources = lifecycleSources.get(projectId) ?? [];
+  projectSources.push("project");
+  lifecycleSources.set(projectId, projectSources);
+  const collisions = [...lifecycleSources.entries()].filter(([, sources]) => sources.length > 1);
+  if (collisions.length > 0) {
+    throw new Error(`refusing to migrate: ${collisions.length} lifecycle id collision(s) (${collisions.map(([id, sources]) => `${JSON.stringify(id)} shared by ${sources.join(" + ")}`).join("; ")}) — every id must be unique across iterations, standalone plans and the project id (each id becomes a workflow/project dir segment)`);
+  }
+  snapshots.sort((a, b) => compareIds(a.id, b.id));
+  const activeIterations = snapshots.filter((snapshot) => snapshot.status === "running" && snapshot.type === "iteration");
+  if (activeIterations.length > 0) {
+    applyRootMetadataLift(activeIterations[0], metadata, migrationNotes, activeIterations.length);
+  } else if (Object.keys(metadata).length > 0) {
+    migrationNotes.push("no active iteration snapshot found — root metadata execution-policy/branch keys have no lift home and stay unmapped (visible here, not silently dropped)");
+  }
+  const notesFiles = collectNotesFiles(snapshots);
+  const residualFindings = isPlainObject6(legacy.residual_findings) ? legacy.residual_findings : {};
+  const register = buildRegister(residualFindings, byPlan, projectId, migratedAt);
+  const programRoadmap = isPlainObject6(metadata.program_roadmap) ? metadata.program_roadmap : null;
+  let roadmap = null;
+  if (programRoadmap) {
+    const rawTitle = typeof programRoadmap.title === "string" && programRoadmap.title !== "" ? programRoadmap.title : "Program roadmap";
+    const sanitizedTitle = rawTitle.replace(/[\r\n]+/g, " ").trim();
+    if (sanitizedTitle !== rawTitle) {
+      migrationNotes.push(`roadmap title sanitized for frontmatter (line breaks replaced with spaces): ${JSON.stringify(rawTitle)}`);
+    }
+    roadmap = {
+      file: join10("projects", projectId, PROJECT_ROADMAP_FILE),
+      source: "status.json metadata.program_roadmap",
+      content: buildRoadmap({ ...programRoadmap, title: sanitizedTitle }, projectId, migratedAt)
+    };
+  }
+  const rootV2 = {
+    file: MIGRATE_STATUS_FILE,
+    data: { version: 2, updated_at: migratedAt, workflows: [] }
+  };
+  const archive = { file: ARCHIVED_STATUS_V1_FILE, source: MIGRATE_STATUS_FILE };
+  const steps = [
+    { kind: "archive-status-v1", source: archive.source, destination: archive.file },
+    ...snapshots.map((snapshot) => ({
+      kind: "write-snapshot",
+      source: snapshot.source,
+      destination: snapshot.file
+    })),
+    ...notesFiles.map((notes) => ({
+      kind: "write-notes",
+      source: notes.source,
+      destination: notes.file
+    }))
+  ];
+  if (register !== null)
+    steps.push({ kind: "write-register", source: register.source, destination: register.file });
+  if (roadmap !== null)
+    steps.push({ kind: "write-roadmap", source: roadmap.source, destination: roadmap.file });
+  steps.push({ kind: "replace-root-v2", source: `${MIGRATE_STATUS_FILE} (v1)`, destination: `${MIGRATE_STATUS_FILE} (v2)` });
+  return {
+    root: harnessDir,
+    workflowDir,
+    projectDir,
+    dryRun: opts.dryRun === true,
+    alreadyMigrated: false,
+    message: `planned migration of ${snapshots.length} lifecycles (${steps.length} steps)`,
+    snapshots,
+    notesFiles,
+    register,
+    roadmap,
+    rootV2,
+    archive,
+    migrationNotes,
+    steps
+  };
+}
+async function applyMigratePlan(plan) {
+  if (plan.dryRun) {
+    return { applied: false, message: `dry-run: ${plan.steps.length} steps planned (source → destination), zero writes` };
+  }
+  const statusPath = join10(plan.root, MIGRATE_STATUS_FILE);
+  const current = readJson(statusPath);
+  if (current.version === 2) {
+    return { applied: false, message: "no-op: status.json already at schema version 2 (migrated) — nothing to do" };
+  }
+  const harnessRoot = resolve8(plan.root);
+  const workflowRoot = resolve8(plan.workflowDir);
+  const projectRoot = resolve8(plan.projectDir);
+  if (!isAbsolute6(plan.workflowDir) || !isAbsolute6(plan.projectDir)) {
+    throw new Error(`refusing to apply migration: plan workflowDir/projectDir must be absolute (got ${JSON.stringify(plan.workflowDir)} / ${JSON.stringify(plan.projectDir)})`);
+  }
+  const workflowTargetOf = (canonicalFile) => join10(workflowRoot, relative3("workflows", canonicalFile));
+  const projectTargetOf = (canonicalFile) => join10(projectRoot, relative3("projects", canonicalFile));
+  const allDestinations = [
+    plan.archive.file,
+    ...plan.snapshots.map((snapshot) => snapshot.file),
+    ...plan.notesFiles.map((notes) => notes.file),
+    ...plan.register !== null ? [plan.register.file] : [],
+    ...plan.roadmap !== null ? [plan.roadmap.file] : []
+  ];
+  for (const destination of allDestinations) {
+    const resolvedDest = resolve8(join10(plan.root, destination));
+    const inside = (dir) => resolvedDest === dir || resolvedDest.startsWith(`${dir}${sep2}`);
+    if (!inside(harnessRoot) && !inside(workflowRoot) && !inside(projectRoot)) {
+      throw new Error(`refusing to apply migration: destination escapes the harness dir (${JSON.stringify(destination)}) — every write must stay under ${JSON.stringify(plan.root)}, the workflow dir (${JSON.stringify(plan.workflowDir)}) or the project dir (${JSON.stringify(plan.projectDir)})`);
+    }
+  }
+  mkdirSync6(join10(plan.root, dirname7(plan.archive.file)), { recursive: true });
+  copyFileSync(statusPath, join10(plan.root, plan.archive.file));
+  for (const snapshot of plan.snapshots) {
+    await writeWorkflowSnapshot(snapshot.data, dirname7(workflowTargetOf(snapshot.file)));
+  }
+  for (const notes of plan.notesFiles) {
+    const filePath = workflowTargetOf(notes.file);
+    mkdirSync6(dirname7(filePath), { recursive: true });
+    const content = notes.lines.length > 0 ? `${notes.lines.join(`
+`)}
+` : "";
+    writeFileSync4(filePath, content, "utf8");
+  }
+  if (plan.register !== null) {
+    const gate2 = validateProjectRegister(plan.register.data);
+    if (!gate2.ok) {
+      throw new Error(`refusing to apply migration: invalid project register: ${gate2.violations.map((v) => v.message).join("; ")}`);
+    }
+    const filePath = projectTargetOf(plan.register.file);
+    mkdirSync6(dirname7(filePath), { recursive: true });
+    writeJson(filePath, plan.register.data);
+  }
+  if (plan.roadmap !== null) {
+    const filePath = projectTargetOf(plan.roadmap.file);
+    mkdirSync6(dirname7(filePath), { recursive: true });
+    writeFileSync4(filePath, plan.roadmap.content, "utf8");
+  }
+  const rootGate = validateStatusV2(plan.rootV2.data, { harnessDir: plan.root });
+  if (!rootGate.ok) {
+    throw new Error(`refusing to apply migration: invalid v2 root: ${rootGate.violations.map((v) => v.message).join("; ")}`);
+  }
+  return withStatusWriteLock(statusPath, () => {
+    const latest = readJson(statusPath);
+    if (latest.version === 2) {
+      return {
+        applied: false,
+        message: "no-op: status.json already at schema version 2 (migrated) — nothing to do"
+      };
+    }
+    writeJson(statusPath, plan.rootV2.data);
+    return {
+      applied: true,
+      message: `migrated ${plan.snapshots.length} lifecycles into workflows/, project layer seeded, root status.json replaced (v1 archived to ${plan.archive.file})`
+    };
+  });
+}
 // src/design-md.ts
-function violation6(severity, code, message, fix) {
+function violation8(severity, code, message, fix) {
   return { ok: false, severity, code, message, fix };
 }
 var RAW_GROUP = "__raw";
@@ -2059,7 +3109,7 @@ function validateDesignTokenFrontmatter(frontmatterText) {
   const violations = [];
   const fm = parseDesignFrontmatter(frontmatterText);
   if (fm === null) {
-    violations.push(violation6("medium", "design-md.tokens.missing-frontmatter", "no `---` YAML frontmatter block found — DESIGN.md must open with a fenced frontmatter holding the token SSOT (design-md-spec §1.5)", "add a `---` fenced frontmatter with version, name, description, and the colors/typography/spacing/rounded groups"));
+    violations.push(violation8("medium", "design-md.tokens.missing-frontmatter", "no `---` YAML frontmatter block found — DESIGN.md must open with a fenced frontmatter holding the token SSOT (design-md-spec §1.5)", "add a `---` fenced frontmatter with version, name, description, and the colors/typography/spacing/rounded groups"));
     return { ok: false, violations };
   }
   const groupEntries = (group) => {
@@ -2074,61 +3124,61 @@ function validateDesignTokenFrontmatter(frontmatterText) {
   };
   for (const group of ["colors", "typography", "spacing", "rounded"]) {
     if (!isMap(fm[group])) {
-      violations.push(violation6("medium", "design-md.tokens.group-not-map", `token group "${group}" must be a YAML map, not a scalar (design-md-spec §1.5)`, `rewrite \`${group}\` as a nested map`));
+      violations.push(violation8("medium", "design-md.tokens.group-not-map", `token group "${group}" must be a YAML map, not a scalar (design-md-spec §1.5)`, `rewrite \`${group}\` as a nested map`));
     } else if (!groupIsMap(group)) {
-      violations.push(violation6("medium", "design-md.tokens.group-not-map", `token group "${group}" must be a YAML map, not a scalar (design-md-spec §1.5)`, `rewrite \`${group}\` as a nested map`));
+      violations.push(violation8("medium", "design-md.tokens.group-not-map", `token group "${group}" must be a YAML map, not a scalar (design-md-spec §1.5)`, `rewrite \`${group}\` as a nested map`));
     } else if (groupEntries(group).length === 0) {
-      violations.push(violation6("medium", "design-md.tokens.missing-group", `missing required token group "${group}" — colors/typography/spacing/rounded are required by the frontmatter SSOT (design-md-spec §1.5)`, `add an active \`${group}:\` block with concrete token values`));
+      violations.push(violation8("medium", "design-md.tokens.missing-group", `missing required token group "${group}" — colors/typography/spacing/rounded are required by the frontmatter SSOT (design-md-spec §1.5)`, `add an active \`${group}:\` block with concrete token values`));
     }
   }
   if (!isMap(fm.components) || !groupIsMap("components")) {
-    violations.push(violation6("medium", "design-md.tokens.group-not-map", `token group "components" must be a YAML map, not a scalar (design-md-spec §1.5)`, `rewrite \`components\` as a nested map`));
+    violations.push(violation8("medium", "design-md.tokens.group-not-map", `token group "components" must be a YAML map, not a scalar (design-md-spec §1.5)`, `rewrite \`components\` as a nested map`));
   }
-  const placeholder = (group, name, value) => violations.push(violation6("low", "design-md.tokens.placeholder", `token "${group}.${name}" uses a "[...]" template value — placeholders never count as concrete tokens (completeness-checklist § How to use item 5)`, `replace \`${value}\` with a concrete value`));
+  const placeholder = (group, name, value) => violations.push(violation8("low", "design-md.tokens.placeholder", `token "${group}.${name}" uses a "[...]" template value — placeholders never count as concrete tokens (completeness-checklist § How to use item 5)`, `replace \`${value}\` with a concrete value`));
   for (const [name, value] of groupEntries("colors")) {
     if (typeof value !== "string") {
-      violations.push(violation6("medium", "design-md.tokens.color-format", `color "${name}" must be a string value (design-md-spec §2.2)`, "quote the color value"));
+      violations.push(violation8("medium", "design-md.tokens.color-format", `color "${name}" must be a string value (design-md-spec §2.2)`, "quote the color value"));
       continue;
     }
     if (isPlaceholder(value)) {
       placeholder("colors", name, value);
     } else if (!HEX_RE.test(value) && !OKLCH_RE.test(value)) {
-      violations.push(violation6("medium", "design-md.tokens.color-format", `color "${name}" = "${value}" is not a hex (\`#rrggbb\`/\`#rrggbbaa\`) or oklch() value (design-md-spec §2.2)`, "use an sRGB hex value, optionally with a `-p3` oklch() twin"));
+      violations.push(violation8("medium", "design-md.tokens.color-format", `color "${name}" = "${value}" is not a hex (\`#rrggbb\`/\`#rrggbbaa\`) or oklch() value (design-md-spec §2.2)`, "use an sRGB hex value, optionally with a `-p3` oklch() twin"));
     }
   }
   for (const [name, value] of groupEntries("typography")) {
     if (!isMap(value)) {
-      violations.push(violation6("medium", "design-md.tokens.typography-shape", `typography token "${name}" must be a map of the five properties (design-md-spec §1.5)`, "give it fontFamily/fontSize/fontWeight/lineHeight/letterSpacing"));
+      violations.push(violation8("medium", "design-md.tokens.typography-shape", `typography token "${name}" must be a map of the five properties (design-md-spec §1.5)`, "give it fontFamily/fontSize/fontWeight/lineHeight/letterSpacing"));
       continue;
     }
     const keys = Object.keys(value);
     const missing = TYPOGRAPHY_PROPS.filter((p) => !keys.includes(p));
     const extra = keys.filter((k) => !TYPOGRAPHY_PROPS.includes(k));
     if (missing.length > 0 || extra.length > 0) {
-      violations.push(violation6("medium", "design-md.tokens.typography-shape", `typography token "${name}" must have exactly the five properties fontFamily/fontSize/fontWeight/lineHeight/letterSpacing (design-md-spec §1.5)${missing.length > 0 ? ` — missing: ${missing.join(", ")}` : ""}${extra.length > 0 ? ` — extra: ${extra.join(", ")}` : ""}`, "align the token with the five-property shape"));
+      violations.push(violation8("medium", "design-md.tokens.typography-shape", `typography token "${name}" must have exactly the five properties fontFamily/fontSize/fontWeight/lineHeight/letterSpacing (design-md-spec §1.5)${missing.length > 0 ? ` — missing: ${missing.join(", ")}` : ""}${extra.length > 0 ? ` — extra: ${extra.join(", ")}` : ""}`, "align the token with the five-property shape"));
     }
     for (const prop of ["fontFamily", "fontSize"]) {
       const v = value[prop];
       if (typeof v === "string" && isPlaceholder(v))
         placeholder("typography", name, v);
       else if (typeof v !== "string" || v.trim() === "") {
-        violations.push(violation6("medium", "design-md.tokens.typography-shape", `typography token "${name}" has an empty \`${prop}\` (design-md-spec §1.5)`, `fill \`${prop}\` with a concrete value`));
+        violations.push(violation8("medium", "design-md.tokens.typography-shape", `typography token "${name}" has an empty \`${prop}\` (design-md-spec §1.5)`, `fill \`${prop}\` with a concrete value`));
       }
     }
   }
   if (groupIsMap("spacing")) {
     const spacing = fm.spacing;
     if (!Object.prototype.hasOwnProperty.call(spacing, "base")) {
-      violations.push(violation6("medium", "design-md.tokens.spacing-base", "spacing must declare the base unit as `base` (design-md-spec §2.4)", "add `base: 4px` (or 8px) to the spacing group"));
+      violations.push(violation8("medium", "design-md.tokens.spacing-base", "spacing must declare the base unit as `base` (design-md-spec §2.4)", "add `base: 4px` (or 8px) to the spacing group"));
     }
     for (const [name, value] of Object.entries(spacing)) {
       if (name !== "base" && name !== RAW_GROUP && !/^\d+$/.test(name)) {
-        violations.push(violation6("medium", "design-md.tokens.spacing-key", `spacing key "${name}" must be \`base\` or a numeric multiplier (design-md-spec §1.5)`, "use numeric scale-step keys or `base`"));
+        violations.push(violation8("medium", "design-md.tokens.spacing-key", `spacing key "${name}" must be \`base\` or a numeric multiplier (design-md-spec §1.5)`, "use numeric scale-step keys or `base`"));
       }
       if (typeof value === "string" && isPlaceholder(value)) {
         placeholder("spacing", name, value);
       } else if (typeof value !== "string" || !PX_RE.test(value)) {
-        violations.push(violation6("medium", "design-md.tokens.spacing-format", `spacing value "${name}" = "${String(value)}" is not a px length (design-md-spec §1.5)`, "use a pixel value like `4px`"));
+        violations.push(violation8("medium", "design-md.tokens.spacing-format", `spacing value "${name}" = "${String(value)}" is not a px length (design-md-spec §1.5)`, "use a pixel value like `4px`"));
       }
     }
   }
@@ -2136,12 +3186,12 @@ function validateDesignTokenFrontmatter(frontmatterText) {
     if (typeof value === "string" && isPlaceholder(value)) {
       placeholder("rounded", name, value);
     } else if (typeof value !== "string" || !PX_RE.test(value)) {
-      violations.push(violation6("medium", "design-md.tokens.rounded-format", `rounded value "${name}" = "${String(value)}" is not a px length (design-md-spec §1.5)`, "use a pixel value like `6px`"));
+      violations.push(violation8("medium", "design-md.tokens.rounded-format", `rounded value "${name}" = "${String(value)}" is not a px length (design-md-spec §1.5)`, "use a pixel value like `6px`"));
     }
   }
   for (const [name, value] of groupEntries("components")) {
     if (!isMap(value)) {
-      violations.push(violation6("medium", "design-md.tokens.components-shape", `component token "${name}" must be a map of properties (design-md-spec §2.8)`, "give it backgroundColor/textColor/typography/rounded/padding/height"));
+      violations.push(violation8("medium", "design-md.tokens.components-shape", `component token "${name}" must be a map of properties (design-md-spec §2.8)`, "give it backgroundColor/textColor/typography/rounded/padding/height"));
       continue;
     }
     for (const [prop, v] of Object.entries(value)) {
@@ -2157,7 +3207,7 @@ function validateDesignTokenFrontmatter(frontmatterText) {
       const [, refGroup, refKey] = ref;
       const resolves = REF_GROUPS.includes(refGroup) && groupIsMap(refGroup) && Object.prototype.hasOwnProperty.call(fm[refGroup], refKey);
       if (!resolves) {
-        violations.push(violation6("medium", "design-md.tokens.ref-unresolved", `component "${name}" references "${v}" which does not resolve to an active token in this frontmatter (design-md-spec §6 — {path} refs MUST trace back to a key)`, `add the referenced token or use a literal value`));
+        violations.push(violation8("medium", "design-md.tokens.ref-unresolved", `component "${name}" references "${v}" which does not resolve to an active token in this frontmatter (design-md-spec §6 — {path} refs MUST trace back to a key)`, `add the referenced token or use a literal value`));
       }
     }
   }
@@ -2169,7 +3219,7 @@ function assertLightDarkParity(lightFm, darkFm) {
   const light = parseDesignFrontmatter(lightFm);
   const dark = parseDesignFrontmatter(darkFm);
   if (light === null || dark === null) {
-    violations.push(violation6("medium", "design-md.parity.missing-frontmatter", `light/dark parity needs a YAML frontmatter in both files — ${light === null ? "DESIGN.md" : "DESIGN.dark.md"} has none (design-md-spec §4 rules 1–2)`, "add the fenced frontmatter to both theme files"));
+    violations.push(violation8("medium", "design-md.parity.missing-frontmatter", `light/dark parity needs a YAML frontmatter in both files — ${light === null ? "DESIGN.md" : "DESIGN.dark.md"} has none (design-md-spec §4 rules 1–2)`, "add the fenced frontmatter to both theme files"));
     return { ok: false, violations };
   }
   const activeKeys = (fm) => {
@@ -2187,12 +3237,12 @@ function assertLightDarkParity(lightFm, darkFm) {
   const darkKeys = activeKeys(dark);
   for (const key of lightKeys) {
     if (!darkKeys.has(key)) {
-      violations.push(violation6("medium", "design-md.parity.missing-dark", `token "${key}" is active in DESIGN.md but missing from DESIGN.dark.md — both files must define the same token set (design-md-spec §4 rule 3)`, "add the token to DESIGN.dark.md with a dark-appropriate value"));
+      violations.push(violation8("medium", "design-md.parity.missing-dark", `token "${key}" is active in DESIGN.md but missing from DESIGN.dark.md — both files must define the same token set (design-md-spec §4 rule 3)`, "add the token to DESIGN.dark.md with a dark-appropriate value"));
     }
   }
   for (const key of darkKeys) {
     if (!lightKeys.has(key)) {
-      violations.push(violation6("medium", "design-md.parity.missing-light", `token "${key}" is active in DESIGN.dark.md but missing from DESIGN.md — DESIGN.md is the SSOT for token names (design-md-spec §4 rules 3–4)`, "add the token to DESIGN.md, or remove it from the dark file"));
+      violations.push(violation8("medium", "design-md.parity.missing-light", `token "${key}" is active in DESIGN.dark.md but missing from DESIGN.md — DESIGN.md is the SSOT for token names (design-md-spec §4 rules 3–4)`, "add the token to DESIGN.md, or remove it from the dark file"));
     }
   }
   return { ok: violations.length === 0, violations };
@@ -2346,9 +3396,9 @@ function completenessLevel(frontmatterText, checklist) {
   return { level, items, missing, placeholders, upgradeTo, bodyUnverified };
 }
 // src/audit.ts
-import { mkdirSync as mkdirSync5, readdirSync as readdirSync4, readFileSync as readFileSync6, writeFileSync as writeFileSync4 } from "node:fs";
-import { join as join7, resolve as resolve7 } from "node:path";
-function violation7(severity, code, message, fix) {
+import { mkdirSync as mkdirSync7, readdirSync as readdirSync7, readFileSync as readFileSync9, writeFileSync as writeFileSync5 } from "node:fs";
+import { join as join11, resolve as resolve9 } from "node:path";
+function violation9(severity, code, message, fix) {
   return { ok: false, severity, code, message, fix };
 }
 var AUDIT_PRIORITIES = ["P1", "P2", "P3"];
@@ -2392,14 +3442,14 @@ function validateAuditStatusBlocks(planText) {
   const violations = [];
   const blocks = parseStatusBlocks(planText);
   if (blocks.length === 0) {
-    violations.push(violation7("medium", "audit.status.missing-block", "no `## Status` block found — audit plan files carry the Status block fields (mstar-audit SKILL § Plan files)", "add a `## Status` block with Priority, Effort, Risk, Depends on, Category, Planned at"));
+    violations.push(violation9("medium", "audit.status.missing-block", "no `## Status` block found — audit plan files carry the Status block fields (mstar-audit SKILL § Plan files)", "add a `## Status` block with Priority, Effort, Risk, Depends on, Category, Planned at"));
     return { ok: false, violations };
   }
   blocks.forEach((block, index) => {
     const label = blocks.length > 1 ? ` #${index + 1}` : "";
     for (const field of AUDIT_STATUS_FIELDS) {
       if (!block.fields.has(field)) {
-        violations.push(violation7("medium", "audit.status.missing-field", `Status block${label} missing required field "${field}" (mstar-audit SKILL § Plan files)`, `add \`- **${field}**: <value>\` to the Status block`));
+        violations.push(violation9("medium", "audit.status.missing-field", `Status block${label} missing required field "${field}" (mstar-audit SKILL § Plan files)`, `add \`- **${field}**: <value>\` to the Status block`));
       }
     }
     const check = (field, pattern, code, expected) => {
@@ -2407,7 +3457,7 @@ function validateAuditStatusBlocks(planText) {
       if (value === undefined)
         return;
       if (!pattern.test(value)) {
-        violations.push(violation7("medium", code, `Status block${label} "${field}" = "${value}" — expected ${expected} (mstar-audit SKILL § Plan files)`, `fix \`- **${field}**:\` to one of: ${expected}`));
+        violations.push(violation9("medium", code, `Status block${label} "${field}" = "${value}" — expected ${expected} (mstar-audit SKILL § Plan files)`, `fix \`- **${field}**:\` to one of: ${expected}`));
       }
     };
     check("Priority", /^P[123]$/, "audit.status.invalid-priority", "P1 | P2 | P3");
@@ -2521,7 +3571,7 @@ function renderPlanFile(finding, plannedAt) {
 `;
 }
 function readPlanFileSummary(filePath) {
-  const text = readFileSync6(filePath, "utf8");
+  const text = readFileSync9(filePath, "utf8");
   const title = (text.match(/^# (.+)$/m) ?? [])[1] ?? filePath;
   const blocks = parseStatusBlocks(text);
   return { title: title.trim(), fields: blocks.length > 0 ? blocks[0].fields : new Map };
@@ -2560,8 +3610,8 @@ function renderIndex(params) {
 function scaffoldAuditPlan(outDir, findings, options = {}) {
   const date = options.date ?? new Date().toISOString().slice(0, 10);
   const plannedAt = options.plannedAt ?? { commit: options.repoShortSha ?? "unknown", date };
-  mkdirSync5(outDir, { recursive: true });
-  const existing = readdirSync4(outDir).filter((f) => /^\d{3}-.*\.md$/.test(f));
+  mkdirSync7(outDir, { recursive: true });
+  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 = [];
   const usedSlugs = new Set;
@@ -2576,13 +3626,13 @@ function scaffoldAuditPlan(outDir, findings, options = {}) {
     }
     usedSlugs.add(slug);
     const file = `${num}-${slug}.md`;
-    writeFileSync4(join7(outDir, file), renderPlanFile(finding, plannedAt));
+    writeFileSync5(join11(outDir, file), renderPlanFile(finding, plannedAt));
     written.push(file);
     next++;
   }
   const all = [...existing, ...written].sort();
   const rows = all.map((file) => {
-    const summary = readPlanFileSummary(join7(outDir, file));
+    const summary = readPlanFileSummary(join11(outDir, file));
     const fields = summary.fields;
     return {
       num: file.slice(0, 3),
@@ -2614,19 +3664,19 @@ function scaffoldAuditPlan(outDir, findings, options = {}) {
       row.dependsOn = finding.dependsOn ?? "none";
     }
   });
-  writeFileSync4(join7(outDir, "README.md"), renderIndex({
+  writeFileSync5(join11(outDir, "README.md"), renderIndex({
     date,
     repoName: options.repoName ?? "repo",
     repoShortSha: options.repoShortSha ?? "unknown",
     rows,
     rejected: options.rejected ?? []
   }));
-  return { outDir: resolve7(outDir), date, files: written, nextNumber: next };
+  return { outDir: resolve9(outDir), date, files: written, nextNumber: next };
 }
 // src/compound.ts
-import { existsSync as existsSync5, readdirSync as readdirSync5, readFileSync as readFileSync7 } from "node:fs";
-import { basename as basename4, isAbsolute as isAbsolute5, join as join8, relative as relative2, resolve as resolve8, sep } from "node:path";
-function violation8(severity, code, message, fix) {
+import { existsSync as existsSync6, readdirSync as readdirSync8, readFileSync as readFileSync10 } from "node:fs";
+import { basename as basename4, isAbsolute as isAbsolute7, join as join12, relative as relative4, resolve as resolve10, sep as sep3 } from "node:path";
+function violation10(severity, code, message, fix) {
   return { ok: false, severity, code, message, fix };
 }
 var KNOWLEDGE_REQUIRED_FIELDS = ["module", "date", "problem_type", "category", "severity"];
@@ -2710,7 +3760,7 @@ var KNOWLEDGE_CATEGORY_MAP = {
   developer_experience: "developer-experience",
   documentation_gap: "documentation"
 };
-var DATE_RE3 = /^\d{4}-\d{2}-\d{2}$/;
+var DATE_RE5 = /^\d{4}-\d{2}-\d{2}$/;
 var isMap2 = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 function parseScalar2(raw) {
   const trimmed = raw.trim();
@@ -2803,36 +3853,36 @@ function validateSchemaYaml(frontmatterText) {
   const violations = [];
   const doc = parseYamlLite(frontmatterText);
   if (doc === null) {
-    violations.push(violation8("medium", "compound.schema.missing-frontmatter", "no `---` YAML frontmatter block found — knowledge docs must open with the schema.yaml contract (mstar-compound/references/schema.yaml)", "add the fenced frontmatter with module, date, problem_type, category, severity"));
+    violations.push(violation10("medium", "compound.schema.missing-frontmatter", "no `---` YAML frontmatter block found — knowledge docs must open with the schema.yaml contract (mstar-compound/references/schema.yaml)", "add the fenced frontmatter with module, date, problem_type, category, severity"));
     return { ok: false, violations };
   }
   const isStr = (v) => typeof v === "string";
-  const missing = (field) => violations.push(violation8("medium", "compound.schema.missing-field", `missing required frontmatter field "${field}" (schema.yaml required_fields)`, `add \`${field}: <value>\` to the frontmatter`));
+  const missing = (field) => violations.push(violation10("medium", "compound.schema.missing-field", `missing required frontmatter field "${field}" (schema.yaml required_fields)`, `add \`${field}: <value>\` to the frontmatter`));
   for (const field of KNOWLEDGE_REQUIRED_FIELDS) {
     if (!(field in doc) || doc[field] === "")
       missing(field);
   }
-  if (doc.date !== undefined && (!isStr(doc.date) || !DATE_RE3.test(doc.date))) {
-    violations.push(violation8("medium", "compound.schema.invalid-date", `date "${String(doc.date)}" must be a YYYY-MM-DD string (schema.yaml required_fields.date)`, "use `YYYY-MM-DD`"));
+  if (doc.date !== undefined && (!isStr(doc.date) || !DATE_RE5.test(doc.date))) {
+    violations.push(violation10("medium", "compound.schema.invalid-date", `date "${String(doc.date)}" must be a YYYY-MM-DD string (schema.yaml required_fields.date)`, "use `YYYY-MM-DD`"));
   }
   const problemType = doc.problem_type;
   if (problemType !== undefined && !isStr(problemType)) {
-    violations.push(violation8("medium", "compound.schema.invalid-problem-type", `problem_type "${String(problemType)}" must be a string — one of the schema.yaml enum values (bug: build_error…config_error; knowledge: developer_experience…testing_pattern)`, "pick the narrowest applicable problem_type from schema.yaml"));
+    violations.push(violation10("medium", "compound.schema.invalid-problem-type", `problem_type "${String(problemType)}" must be a string — one of the schema.yaml enum values (bug: build_error…config_error; knowledge: developer_experience…testing_pattern)`, "pick the narrowest applicable problem_type from schema.yaml"));
   }
   const problemTypeValid = isStr(problemType) && KNOWLEDGE_PROBLEM_TYPES.includes(problemType);
   if (isStr(problemType) && !problemTypeValid) {
-    violations.push(violation8("medium", "compound.schema.invalid-problem-type", `problem_type "${problemType}" is not one of the schema.yaml enum values (bug: build_error…config_error; knowledge: developer_experience…testing_pattern)`, "pick the narrowest applicable problem_type from schema.yaml"));
+    violations.push(violation10("medium", "compound.schema.invalid-problem-type", `problem_type "${problemType}" is not one of the schema.yaml enum values (bug: build_error…config_error; knowledge: developer_experience…testing_pattern)`, "pick the narrowest applicable problem_type from schema.yaml"));
   }
   if (doc.severity !== undefined && !isStr(doc.severity)) {
-    violations.push(violation8("medium", "compound.schema.invalid-severity", `severity "${String(doc.severity)}" must be a string — critical | high | medium | low (schema.yaml required_fields.severity)`, "use one of the four severity values"));
+    violations.push(violation10("medium", "compound.schema.invalid-severity", `severity "${String(doc.severity)}" must be a string — critical | high | medium | low (schema.yaml required_fields.severity)`, "use one of the four severity values"));
   }
   if (isStr(doc.severity) && !KNOWLEDGE_SEVERITIES.includes(doc.severity)) {
-    violations.push(violation8("medium", "compound.schema.invalid-severity", `severity "${doc.severity}" must be critical | high | medium | low (schema.yaml required_fields.severity)`, "use one of the four severity values"));
+    violations.push(violation10("medium", "compound.schema.invalid-severity", `severity "${doc.severity}" must be critical | high | medium | low (schema.yaml required_fields.severity)`, "use one of the four severity values"));
   }
   if (problemTypeValid && isStr(doc.category)) {
     const expected = KNOWLEDGE_CATEGORY_MAP[problemType];
     if (doc.category !== expected) {
-      violations.push(violation8("medium", "compound.schema.category-mismatch", `category "${doc.category}" does not match problem_type "${problemType}" — category-mapping.md rule 1 maps it to "${expected}"`, `set \`category: ${expected}\` (the directory name under {KNOWLEDGE_DIR})`));
+      violations.push(violation10("medium", "compound.schema.category-mismatch", `category "${doc.category}" does not match problem_type "${problemType}" — category-mapping.md rule 1 maps it to "${expected}"`, `set \`category: ${expected}\` (the directory name under {KNOWLEDGE_DIR})`));
     }
   }
   if (problemTypeValid) {
@@ -2840,37 +3890,37 @@ function validateSchemaYaml(frontmatterText) {
     if (isBug) {
       for (const field of ["symptoms", "root_cause", "resolution_type"]) {
         if (!(field in doc)) {
-          violations.push(violation8("medium", "compound.schema.missing-track-field", `bug-track doc missing required field "${field}" (schema.yaml track_rules.bug)`, `add \`${field}:\` to the frontmatter`));
+          violations.push(violation10("medium", "compound.schema.missing-track-field", `bug-track doc missing required field "${field}" (schema.yaml track_rules.bug)`, `add \`${field}:\` to the frontmatter`));
         }
       }
       if (doc.symptoms !== undefined && !Array.isArray(doc.symptoms)) {
-        violations.push(violation8("medium", "compound.schema.invalid-symptoms", "bug-track `symptoms` must be a YAML list (schema.yaml track_rules.bug)", "list the observable symptoms under `symptoms:`"));
+        violations.push(violation10("medium", "compound.schema.invalid-symptoms", "bug-track `symptoms` must be a YAML list (schema.yaml track_rules.bug)", "list the observable symptoms under `symptoms:`"));
       }
       if (doc.root_cause !== undefined && !isStr(doc.root_cause)) {
-        violations.push(violation8("medium", "compound.schema.invalid-root-cause", "bug-track `root_cause` must be a string (schema.yaml track_rules.bug)", "write the fundamental technical cause as a string"));
+        violations.push(violation10("medium", "compound.schema.invalid-root-cause", "bug-track `root_cause` must be a string (schema.yaml track_rules.bug)", "write the fundamental technical cause as a string"));
       }
       if (isStr(doc.resolution_type) && !KNOWLEDGE_RESOLUTION_TYPES.includes(doc.resolution_type)) {
-        violations.push(violation8("medium", "compound.schema.invalid-resolution-type", `resolution_type "${doc.resolution_type}" is not one of the schema.yaml track_rules.bug enum values`, "use code_fix | migration | config_change | test_fix | dependency_update | environment_setup | workflow_improvement | documentation_update | tooling_addition"));
+        violations.push(violation10("medium", "compound.schema.invalid-resolution-type", `resolution_type "${doc.resolution_type}" is not one of the schema.yaml track_rules.bug enum values`, "use code_fix | migration | config_change | test_fix | dependency_update | environment_setup | workflow_improvement | documentation_update | tooling_addition"));
       }
     } else if (doc.applies_when !== undefined && !Array.isArray(doc.applies_when)) {
-      violations.push(violation8("low", "compound.schema.invalid-applies-when", "knowledge-track `applies_when` must be a YAML list when present (schema.yaml track_rules.knowledge)", "list the conditions under `applies_when:`"));
+      violations.push(violation10("low", "compound.schema.invalid-applies-when", "knowledge-track `applies_when` must be a YAML list when present (schema.yaml track_rules.knowledge)", "list the conditions under `applies_when:`"));
     }
   }
   if (doc.plan_id !== undefined && !isStr(doc.plan_id)) {
-    violations.push(violation8("low", "compound.schema.invalid-plan-id", "optional `plan_id` must be a string (schema.yaml optional_fields.plan_id)", "reference the status.json plan id as a string"));
+    violations.push(violation10("low", "compound.schema.invalid-plan-id", "optional `plan_id` must be a string (schema.yaml optional_fields.plan_id)", "reference the status.json plan id as a string"));
   }
   if (doc.tags !== undefined) {
     if (!Array.isArray(doc.tags)) {
-      violations.push(violation8("low", "compound.schema.invalid-tags", "optional `tags` must be a YAML list (schema.yaml optional_fields.tags)", "list lowercase, hyphen-separated keywords"));
+      violations.push(violation10("low", "compound.schema.invalid-tags", "optional `tags` must be a YAML list (schema.yaml optional_fields.tags)", "list lowercase, hyphen-separated keywords"));
     } else if (doc.tags.length > 8) {
-      violations.push(violation8("low", "compound.schema.tags-too-many", `tags has ${doc.tags.length} entries — max 8 (schema.yaml optional_fields.tags.max_items)`, "trim the tag list to at most 8 keywords"));
+      violations.push(violation10("low", "compound.schema.tags-too-many", `tags has ${doc.tags.length} entries — max 8 (schema.yaml optional_fields.tags.max_items)`, "trim the tag list to at most 8 keywords"));
     }
   }
-  if (doc.last_updated !== undefined && (!isStr(doc.last_updated) || !DATE_RE3.test(doc.last_updated))) {
-    violations.push(violation8("low", "compound.schema.invalid-last-updated", `last_updated "${String(doc.last_updated)}" must be YYYY-MM-DD (schema.yaml optional_fields.last_updated)`, "use `YYYY-MM-DD`"));
+  if (doc.last_updated !== undefined && (!isStr(doc.last_updated) || !DATE_RE5.test(doc.last_updated))) {
+    violations.push(violation10("low", "compound.schema.invalid-last-updated", `last_updated "${String(doc.last_updated)}" must be YYYY-MM-DD (schema.yaml optional_fields.last_updated)`, "use `YYYY-MM-DD`"));
   }
   if (doc.related_components !== undefined && !Array.isArray(doc.related_components)) {
-    violations.push(violation8("low", "compound.schema.invalid-related-components", "optional `related_components` must be a YAML list (schema.yaml optional_fields.related_components)", "list the other components involved"));
+    violations.push(violation10("low", "compound.schema.invalid-related-components", "optional `related_components` must be a YAML list (schema.yaml optional_fields.related_components)", "list the other components involved"));
   }
   return { ok: violations.length === 0, violations };
 }
@@ -2892,7 +3942,7 @@ function referenceExists(repoRoot, docText) {
     if (ref === "" || seen.has(ref))
       continue;
     seen.add(ref);
-    if (SCHEME_RE.test(ref) || ref.startsWith("{") || ref.startsWith("#") || ref.includes("*") || ref.includes("?") || ref.startsWith("~") || isAbsolute5(ref)) {
+    if (SCHEME_RE.test(ref) || ref.startsWith("{") || ref.startsWith("#") || ref.includes("*") || ref.includes("?") || ref.startsWith("~") || isAbsolute7(ref)) {
       continue;
     }
     if (ref.includes("/") || REF_EXT_RE.test(ref)) {
@@ -2911,7 +3961,7 @@ function referenceExists(repoRoot, docText) {
       const dir = stack.pop();
       let entries;
       try {
-        entries = readdirSync5(dir, { withFileTypes: true });
+        entries = readdirSync8(dir, { withFileTypes: true });
       } catch {
         continue;
       }
@@ -2920,7 +3970,7 @@ function referenceExists(repoRoot, docText) {
           break;
         if (entry.isDirectory()) {
           if (!WALK_SKIP_DIRS.has(entry.name))
-            stack.push(join8(dir, entry.name));
+            stack.push(join12(dir, entry.name));
         } else if (!entry.isSymbolicLink()) {
           const base = entry.name.replace(/\.(?:ts|tsx|js|jsx|mjs|cjs)$/, "");
           if (moduleNames.has(base))
@@ -2932,15 +3982,15 @@ function referenceExists(repoRoot, docText) {
   for (const { ref, isSymbol, module } of refs) {
     if (!isSymbol || module === undefined) {
       const candidate = ref.replace(LINE_SUFFIX_RE, "").replace(ANCHOR_RE, "");
-      if (existsSync5(resolve8(repoRoot, candidate))) {
+      if (existsSync6(resolve10(repoRoot, candidate))) {
         checked++;
       } else {
-        violations.push(violation8("medium", "compound.reference.missing-file", `referenced path \`${ref}\` does not exist under ${repoRoot} (compound-refresh Phase 2: referenced code still exists?)`, "update the doc to reference an existing path, or delete the stale reference"));
+        violations.push(violation10("medium", "compound.reference.missing-file", `referenced path \`${ref}\` does not exist under ${repoRoot} (compound-refresh Phase 2: referenced code still exists?)`, "update the doc to reference an existing path, or delete the stale reference"));
       }
     } else if (foundModules.has(module)) {
       checked++;
     } else {
-      violations.push(violation8("low", "compound.reference.module-missing", `symbol ref \`${ref}\` — heuristic: no ${module}.ts|tsx|js|jsx|mjs|cjs module file found under ${repoRoot} (compound-refresh Phase 2)`, "verify the module file exists, or update the reference"));
+      violations.push(violation10("low", "compound.reference.module-missing", `symbol ref \`${ref}\` — heuristic: no ${module}.ts|tsx|js|jsx|mjs|cjs module file found under ${repoRoot} (compound-refresh Phase 2)`, "verify the module file exists, or update the reference"));
     }
   }
   return { ok: violations.length === 0, violations, checked };
@@ -2952,18 +4002,18 @@ function collectKnowledgeDocs(dir) {
     const current = stack.pop();
     let entries;
     try {
-      entries = readdirSync5(current, { withFileTypes: true });
+      entries = readdirSync8(current, { withFileTypes: true });
     } catch {
       continue;
     }
     for (const entry of entries) {
       if (entry.isSymbolicLink())
         continue;
-      const full = join8(current, entry.name);
+      const full = join12(current, entry.name);
       if (entry.isDirectory()) {
         stack.push(full);
       } else if (entry.name.endsWith(".md") && entry.name !== "README.md" && entry.name !== "index.md") {
-        docs.push(relative2(dir, full).split(sep).join("/"));
+        docs.push(relative4(dir, full).split(sep3).join("/"));
       }
     }
   }
@@ -2979,14 +4029,14 @@ function normalizeIndexRef(cell) {
 }
 function assertIndexRows(knowledgeDir) {
   const violations = [];
-  const readmePath = join8(knowledgeDir, "README.md");
-  if (!existsSync5(readmePath)) {
-    violations.push(violation8("medium", "compound.index.missing-readme", `missing ${readmePath} — the knowledge index is required (mstar-compound Phase 6: every doc gets a README.md row)`, "create knowledge/README.md with a Document / Source Plan / Description / Status table"));
+  const readmePath = join12(knowledgeDir, "README.md");
+  if (!existsSync6(readmePath)) {
+    violations.push(violation10("medium", "compound.index.missing-readme", `missing ${readmePath} — the knowledge index is required (mstar-compound Phase 6: every doc gets a README.md row)`, "create knowledge/README.md with a Document / Source Plan / Description / Status table"));
     return { ok: false, violations };
   }
   const docs = collectKnowledgeDocs(knowledgeDir);
   const rows = new Set;
-  for (const line of readFileSync7(readmePath, "utf8").split(/\r?\n/)) {
+  for (const line of readFileSync10(readmePath, "utf8").split(/\r?\n/)) {
     if (!line.trim().startsWith("|"))
       continue;
     const cells = line.split("|").map((c) => c.trim());
@@ -2998,42 +4048,42 @@ function assertIndexRows(knowledgeDir) {
   }
   for (const doc of docs) {
     if (!rows.has(doc)) {
-      violations.push(violation8("medium", "compound.index.missing-row", `knowledge doc "${doc}" has no row in knowledge/README.md index (mstar-compound Phase 6 index obligations)`, `add a row \`| [<title>](${doc}) | <source plan> | <description> | <status> |\` to knowledge/README.md`));
+      violations.push(violation10("medium", "compound.index.missing-row", `knowledge doc "${doc}" has no row in knowledge/README.md index (mstar-compound Phase 6 index obligations)`, `add a row \`| [<title>](${doc}) | <source plan> | <description> | <status> |\` to knowledge/README.md`));
     }
   }
   return { ok: violations.length === 0, violations };
 }
 function compoundRefreshScope(harnessDir, projectRoot) {
   return [
-    join8(harnessDir, "knowledge"),
-    join8(harnessDir, "knowledge", "README.md"),
-    join8(projectRoot, "CONCEPTS.md"),
-    join8(harnessDir, "status.json")
+    join12(harnessDir, "knowledge"),
+    join12(harnessDir, "knowledge", "README.md"),
+    join12(projectRoot, "CONCEPTS.md"),
+    join12(harnessDir, "status.json")
   ];
 }
 function isFileLikeRoot(root) {
   return /^[^.]*\.[A-Za-z0-9]{1,10}$/.test(basename4(root));
 }
 function scopeGuard(path, allowedRoots) {
-  const resolved = resolve8(path);
+  const resolved = resolve10(path);
   for (const root of allowedRoots) {
-    const r = resolve8(root);
+    const r = resolve10(root);
     if (isFileLikeRoot(r)) {
       if (resolved === r)
         return { ok: true, violations: [] };
-    } else if (resolved === r || resolved.startsWith(r + sep)) {
+    } else if (resolved === r || resolved.startsWith(r + sep3)) {
       return { ok: true, violations: [] };
     }
   }
   return {
     ok: false,
     violations: [
-      violation8("medium", "compound.scope.outside", `path "${path}" is outside the compound-refresh scope (allowed: ${allowedRoots.join(", ")}) — compound-refresh operates only on {HARNESS_DIR}/knowledge/**, {HARNESS_DIR}/knowledge/README.md, <repo-root>/CONCEPTS.md, {HARNESS_DIR}/status.json (mstar-compound-refresh SKILL.md § 产物与操作路径)`, "point the operation at one of the allowed paths")
+      violation10("medium", "compound.scope.outside", `path "${path}" is outside the compound-refresh scope (allowed: ${allowedRoots.join(", ")}) — compound-refresh operates only on {HARNESS_DIR}/knowledge/**, {HARNESS_DIR}/knowledge/README.md, <repo-root>/CONCEPTS.md, {HARNESS_DIR}/status.json (mstar-compound-refresh SKILL.md § 产物与操作路径)`, "point the operation at one of the allowed paths")
     ]
   };
 }
 // src/lint.ts
-function violation9(severity, code, message, fix) {
+function violation11(severity, code, message, fix) {
   return { ok: false, severity, code, message, fix };
 }
 var COMMENT_INTRODUCER = "(?:\\/\\/|\\/\\*|#|;|--|\\s\\*)";
@@ -3076,7 +4126,7 @@ function findTemporaryMarkers(fileText) {
     }
     markers.push({ line: i + 1, text, removalPath });
     if (removalPath === null) {
-      violations.push(violation9("medium", "lint.temporary.no-removal-path", `temporary marker at line ${i + 1} records no removal path (plan/status artifact reference) — record one before claiming the task complete (mstar-coding-behavior § Simplification markers)`, 'add a plan/status reference to the marker, e.g. "removal tracked in status.json" or "plan 20260808-slice2 removes this"'));
+      violations.push(violation11("medium", "lint.temporary.no-removal-path", `temporary marker at line ${i + 1} records no removal path (plan/status artifact reference) — record one before claiming the task complete (mstar-coding-behavior § Simplification markers)`, 'add a plan/status reference to the marker, e.g. "removal tracked in status.json" or "plan 20260808-slice2 removes this"'));
     }
   }
   return { ok: violations.length === 0, violations, markers };
@@ -3123,13 +4173,13 @@ function assertSddTddTriple(reportText) {
       break;
   }
   if (!hasTests) {
-    violations.push(violation9("medium", "lint.sdd-tdd.missing-tests", "task report carries no test file reference — the TDD triple needs covering test file(s) (mstar-coding-behavior § Integration Notes; mstar-sdd/references/file-handoffs.md)", 'add a "Covering test file(s): <path>.test.ts" line or a `.test.<ext>` path to the report'));
+    violations.push(violation11("medium", "lint.sdd-tdd.missing-tests", "task report carries no test file reference — the TDD triple needs covering test file(s) (mstar-coding-behavior § Integration Notes; mstar-sdd/references/file-handoffs.md)", 'add a "Covering test file(s): <path>.test.ts" line or a `.test.<ext>` path to the report'));
   }
   if (!hasCommand) {
-    violations.push(violation9("medium", "lint.sdd-tdd.missing-command", "task report carries no command — the TDD triple needs the exact command run (mstar-coding-behavior § Integration Notes; mstar-sdd/references/file-handoffs.md)", 'add a "Command run: `bun test <file>`" line to the report'));
+    violations.push(violation11("medium", "lint.sdd-tdd.missing-command", "task report carries no command — the TDD triple needs the exact command run (mstar-coding-behavior § Integration Notes; mstar-sdd/references/file-handoffs.md)", 'add a "Command run: `bun test <file>`" line to the report'));
   }
   if (!hasOutput) {
-    violations.push(violation9("medium", "lint.sdd-tdd.missing-output", "task report carries no output evidence — the TDD triple needs the run output (pass/fail counts or exit code) (mstar-coding-behavior § Integration Notes; mstar-sdd/references/file-handoffs.md)", 'paste the test-run output (e.g. "12 pass / 0 fail") into the report'));
+    violations.push(violation11("medium", "lint.sdd-tdd.missing-output", "task report carries no output evidence — the TDD triple needs the run output (pass/fail counts or exit code) (mstar-coding-behavior § Integration Notes; mstar-sdd/references/file-handoffs.md)", 'paste the test-run output (e.g. "12 pass / 0 fail") into the report'));
   }
   return { ok: violations.length === 0, violations };
 }
@@ -3170,7 +4220,7 @@ function planQualityBar(planText) {
     if (token !== null) {
       const text = trimmed.length > 80 ? `${trimmed.slice(0, 77)}...` : trimmed;
       findings.push({ token, line: i + 1, text });
-      violations.push(violation9("medium", "lint.plan-quality.placeholder", `placeholder token "${token}" at line ${i + 1}: "${text}"`, "replace the placeholder with concrete content before locking the plan (mstar-plan-artifacts/references/plan-quality-bar.md; templates/plan.main.md placeholder scan)"));
+      violations.push(violation11("medium", "lint.plan-quality.placeholder", `placeholder token "${token}" at line ${i + 1}: "${text}"`, "replace the placeholder with concrete content before locking the plan (mstar-plan-artifacts/references/plan-quality-bar.md; templates/plan.main.md placeholder scan)"));
     }
   }
   return { ok: violations.length === 0, violations, findings };
@@ -3182,18 +4232,18 @@ function lintSkillFrontmatter(frontmatterText) {
   const violations = [];
   const fm = parseFrontmatter(frontmatterText);
   if (fm === null) {
-    violations.push(violation9("medium", "lint.frontmatter.missing", "no YAML frontmatter block found — a skill file must open with a `---` fenced frontmatter (mstar-skill-authoring § Frontmatter Contract)", "add a frontmatter block with `name` and `description` at the top of the file"));
+    violations.push(violation11("medium", "lint.frontmatter.missing", "no YAML frontmatter block found — a skill file must open with a `---` fenced frontmatter (mstar-skill-authoring § Frontmatter Contract)", "add a frontmatter block with `name` and `description` at the top of the file"));
     return { ok: false, violations };
   }
   const name = fm.name ?? "";
   if (name === "") {
-    violations.push(violation9("medium", "lint.frontmatter.name.missing", "frontmatter `name` is missing — required (mstar-skill-authoring § Frontmatter Contract)", "add `name: <lowercase-hyphen-id>` to the frontmatter"));
+    violations.push(violation11("medium", "lint.frontmatter.name.missing", "frontmatter `name` is missing — required (mstar-skill-authoring § Frontmatter Contract)", "add `name: <lowercase-hyphen-id>` to the frontmatter"));
   } else if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) {
-    violations.push(violation9("medium", "lint.frontmatter.name.format", `frontmatter \`name\` must be lowercase-hyphen ("${name}") — e.g. example-skill (mstar-skill-authoring § Frontmatter Contract)`, "rename to a stable lowercase-hyphen id, e.g. `name: example-skill`"));
+    violations.push(violation11("medium", "lint.frontmatter.name.format", `frontmatter \`name\` must be lowercase-hyphen ("${name}") — e.g. example-skill (mstar-skill-authoring § Frontmatter Contract)`, "rename to a stable lowercase-hyphen id, e.g. `name: example-skill`"));
   }
   const description = fm.description ?? "";
   if (description === "") {
-    violations.push(violation9("medium", "lint.frontmatter.description.missing", "frontmatter `description` is missing — the trigger contract is required (mstar-skill-authoring § Frontmatter Contract)", "add a `description:` that states when the skill loads (symptoms, context, roles, exclusions)"));
+    violations.push(violation11("medium", "lint.frontmatter.description.missing", "frontmatter `description` is missing — the trigger contract is required (mstar-skill-authoring § Frontmatter Contract)", "add a `description:` that states when the skill loads (symptoms, context, roles, exclusions)"));
   } else {
     const stripped = description.replace(/`[^`]*`/g, " ").replace(/'[^']*'/g, " ").replace(/"[^"]*"/g, " ");
     let pronoun = null;
@@ -3204,15 +4254,15 @@ function lintSkillFrontmatter(frontmatterText) {
       break;
     }
     if (pronoun !== null) {
-      violations.push(violation9("low", "lint.frontmatter.description.person", `description uses first/second-person pronoun "${pronoun[0]}" — keep the trigger contract third person (mstar-skill-authoring § Frontmatter Contract)`, 'rewrite without I/we/you/my/our/your/us, e.g. "Use when the user asks …"'));
+      violations.push(violation11("low", "lint.frontmatter.description.person", `description uses first/second-person pronoun "${pronoun[0]}" — keep the trigger contract third person (mstar-skill-authoring § Frontmatter Contract)`, 'rewrite without I/we/you/my/our/your/us, e.g. "Use when the user asks …"'));
     }
     const start = description.trim().replace(/^[*_#>]+/, "").replace(/^["'`]+/, "").trim();
     if (WORKFLOW_VERB_START_RE.test(start)) {
-      violations.push(violation9("low", "lint.frontmatter.description.workflow", 'description reads as a workflow summary ("Explains/Describes/Covers …") — the description is the trigger contract, not a summary of steps (mstar-skill-authoring § Frontmatter Contract)', "describe when to load the skill (symptoms, context, roles, exclusions) instead of summarizing its steps"));
+      violations.push(violation11("low", "lint.frontmatter.description.workflow", 'description reads as a workflow summary ("Explains/Describes/Covers …") — the description is the trigger contract, not a summary of steps (mstar-skill-authoring § Frontmatter Contract)', "describe when to load the skill (symptoms, context, roles, exclusions) instead of summarizing its steps"));
     } else {
       const words = description.trim().split(/\s+/).filter(Boolean).length;
       if (words > DESCRIPTION_MAX_WORDS) {
-        violations.push(violation9("low", "lint.frontmatter.description.workflow", `description is ${words} words — paragraph-length summaries bury the trigger contract (threshold ${DESCRIPTION_MAX_WORDS}, above the longest corpus description at 114 words, mstar-design-md; mstar-skill-authoring § Frontmatter Contract)`, "trim the description to a scannable trigger contract and move detail into the body"));
+        violations.push(violation11("low", "lint.frontmatter.description.workflow", `description is ${words} words — paragraph-length summaries bury the trigger contract (threshold ${DESCRIPTION_MAX_WORDS}, above the longest corpus description at 114 words, mstar-design-md; mstar-skill-authoring § Frontmatter Contract)`, "trim the description to a scannable trigger contract and move detail into the body"));
       }
     }
   }
@@ -3259,15 +4309,15 @@ function lintStrategySections(docText) {
   }
   for (const required of REQUIRED_STRATEGY_SECTIONS) {
     if (!headings.has(required.toLowerCase())) {
-      violations.push(violation9("medium", "lint.strategy.missing-section", `missing required section "${required}" (mstar-strategy § STRATEGY.md structure)`, "add a `## <Section>` heading; required: Vision, What we build, What we don't build, Guiding Principles, Technology Direction, Decision Log"));
+      violations.push(violation11("medium", "lint.strategy.missing-section", `missing required section "${required}" (mstar-strategy § STRATEGY.md structure)`, "add a `## <Section>` heading; required: Vision, What we build, What we don't build, Guiding Principles, Technology Direction, Decision Log"));
     }
   }
   return { ok: violations.length === 0, violations };
 }
 // src/roles.ts
-import { existsSync as existsSync6 } from "node:fs";
-import { join as join9 } from "node:path";
-function violation10(severity, code, message, fix) {
+import { existsSync as existsSync7 } from "node:fs";
+import { join as join13 } from "node:path";
+function violation12(severity, code, message, fix) {
   return { ok: false, severity, code, message, fix };
 }
 var ROLE_MAPPING = [
@@ -3322,19 +4372,19 @@ function validateRoleMapping(rolesDir, options = {}) {
   const violations = [];
   const referenceById = new Map(mapping.map((m) => [m.agentId, m.reference]));
   for (const { agentId, reference } of mapping) {
-    if (!existsSync6(join9(rolesDir, reference))) {
-      violations.push(violation10("medium", "roles.mapping.reference.missing", `role "${agentId}" maps to ${reference} which does not exist under ${rolesDir} (mstar-roles § Role Reference Mapping)`, `create ${join9(rolesDir, reference)} or fix the mapping row`));
+    if (!existsSync7(join13(rolesDir, reference))) {
+      violations.push(violation12("medium", "roles.mapping.reference.missing", `role "${agentId}" maps to ${reference} which does not exist under ${rolesDir} (mstar-roles § Role Reference Mapping)`, `create ${join13(rolesDir, reference)} or fix the mapping row`));
     }
   }
   for (const { family, memberIds } of families) {
     const absent = memberIds.filter((id) => !referenceById.has(id));
     for (const id of absent) {
-      violations.push(violation10("medium", "roles.mapping.family.member.missing", `shared family "${family}" member "${id}" is absent from the role mapping (mstar-roles § Role Reference Mapping)`, `add "${id}" to the mapping`));
+      violations.push(violation12("medium", "roles.mapping.family.member.missing", `shared family "${family}" member "${id}" is absent from the role mapping (mstar-roles § Role Reference Mapping)`, `add "${id}" to the mapping`));
     }
     if (absent.length === 0) {
       const refs = new Set(memberIds.map((id) => referenceById.get(id)));
       if (refs.size !== 1) {
-        violations.push(violation10("medium", "roles.mapping.family.shared", `shared family "${family}" (${memberIds.join(", ")}) must resolve to ONE shared reference file — got ${[...refs].join(", ")} (mstar-roles § Maintenance Rules: "Keep shared-family roles on one shared reference file")`, `point every "${family}" member at the same references/<role>-shared.md`));
+        violations.push(violation12("medium", "roles.mapping.family.shared", `shared family "${family}" (${memberIds.join(", ")}) must resolve to ONE shared reference file — got ${[...refs].join(", ")} (mstar-roles § Maintenance Rules: "Keep shared-family roles on one shared reference file")`, `point every "${family}" member at the same references/<role>-shared.md`));
       }
     }
   }
@@ -3343,12 +4393,12 @@ function validateRoleMapping(rolesDir, options = {}) {
     for (const row of rows) {
       const existing = tableByRole.get(row.roleId);
       if (existing !== undefined) {
-        violations.push(violation10("medium", "roles.param.role.duplicate", `role "${row.roleId}" appears in both the ${existing} and ${table} parameter rows (mstar-roles § Parameter Table (SSOT))`, "remove the duplicate row"));
+        violations.push(violation12("medium", "roles.param.role.duplicate", `role "${row.roleId}" appears in both the ${existing} and ${table} parameter rows (mstar-roles § Parameter Table (SSOT))`, "remove the duplicate row"));
       } else {
         tableByRole.set(row.roleId, table);
       }
       if (!referenceById.has(row.roleId)) {
-        violations.push(violation10("medium", "roles.param.role.missing", `${table} parameter row references unknown role "${row.roleId}" (mstar-roles § Parameter Table (SSOT))`, `add "${row.roleId}" to the role mapping or drop the row`));
+        violations.push(violation12("medium", "roles.param.role.missing", `${table} parameter row references unknown role "${row.roleId}" (mstar-roles § Parameter Table (SSOT))`, `add "${row.roleId}" to the role mapping or drop the row`));
       }
     }
   };
@@ -3356,20 +4406,20 @@ function validateRoleMapping(rolesDir, options = {}) {
   checkParamRoles(qcReviewers, "QC reviewer");
   for (const row of devTrack) {
     if (row.track !== "primary" && row.track !== "parallel_secondary") {
-      violations.push(violation10("medium", "roles.param.track", `dev track for "${row.roleId}" is "${String(row.track)}" — must be primary or parallel_secondary (mstar-roles § Parameter Table (SSOT))`, 'set track to "primary" or "parallel_secondary"'));
+      violations.push(violation12("medium", "roles.param.track", `dev track for "${row.roleId}" is "${String(row.track)}" — must be primary or parallel_secondary (mstar-roles § Parameter Table (SSOT))`, 'set track to "primary" or "parallel_secondary"'));
     }
   }
   const indices = qcReviewers.map((r) => r.reviewerIndex).sort((a, b) => a - b);
   const unique = new Set(indices);
   if (indices.length !== 3 || unique.size !== 3 || indices[0] !== 1 || indices[1] !== 2 || indices[2] !== 3) {
-    violations.push(violation10("high", "roles.param.qc.index.set", `QC reviewer_index must be exactly {1, 2, 3} across the three qc-specialist* seats — got [${indices.join(", ")}] (mstar-roles § Parameter Table (SSOT))`, "assign reviewer_index 1/2/3 to qc-specialist / qc-specialist-2 / qc-specialist-3"));
+    violations.push(violation12("high", "roles.param.qc.index.set", `QC reviewer_index must be exactly {1, 2, 3} across the three qc-specialist* seats — got [${indices.join(", ")}] (mstar-roles § Parameter Table (SSOT))`, "assign reviewer_index 1/2/3 to qc-specialist / qc-specialist-2 / qc-specialist-3"));
   }
   for (const row of qcReviewers) {
     if (row.focus.trim() === "") {
-      violations.push(violation10("medium", "roles.param.qc.focus.missing", `QC seat "${row.roleId}" (reviewer_index ${row.reviewerIndex}) has an empty focus (mstar-roles § Parameter Table (SSOT))`, "add the review focus"));
+      violations.push(violation12("medium", "roles.param.qc.focus.missing", `QC seat "${row.roleId}" (reviewer_index ${row.reviewerIndex}) has an empty focus (mstar-roles § Parameter Table (SSOT))`, "add the review focus"));
     }
     if (row.reportSuffix !== `qc${row.reviewerIndex}`) {
-      violations.push(violation10("medium", "roles.param.qc.suffix", `QC seat "${row.roleId}" report_suffix "${row.reportSuffix}" must equal qc${row.reviewerIndex} — tri reports land at {SDD_DIR}/review/qc1.md…qc3.md (mstar-roles § Parameter Table (SSOT))`, `set report_suffix to qc${row.reviewerIndex}`));
+      violations.push(violation12("medium", "roles.param.qc.suffix", `QC seat "${row.roleId}" report_suffix "${row.reportSuffix}" must equal qc${row.reviewerIndex} — tri reports land at {SDD_DIR}/review/qc1.md…qc3.md (mstar-roles § Parameter Table (SSOT))`, `set report_suffix to qc${row.reviewerIndex}`));
     }
   }
   return { ok: violations.length === 0, violations };
@@ -3408,11 +4458,11 @@ function lintLoadOrder(skillTexts) {
       continue;
     const section = extractLoadOrderSection(text);
     if (section === null) {
-      violations.push(violation10("medium", "roles.loadorder.section.missing", `skill "${name}" has no Load Order / First action section — every mstar-* topic skill must declare its first read (mstar-harness-core § 加载约定; mstar-roles § Load Order (Required))`, `add a "## Load Order" section naming mstar-harness-core as the first read`));
+      violations.push(violation12("medium", "roles.loadorder.section.missing", `skill "${name}" has no Load Order / First action section — every mstar-* topic skill must declare its first read (mstar-harness-core § 加载约定; mstar-roles § Load Order (Required))`, `add a "## Load Order" section naming mstar-harness-core as the first read`));
       continue;
     }
     if (!section.includes("mstar-harness-core")) {
-      violations.push(violation10("medium", "roles.loadorder.core.missing", `skill "${name}" Load Order section does not declare mstar-harness-core as its first dependency (mstar-harness-core § 加载约定: 凡 mstar-*（name ≠ mstar-harness-core）假定读者已 Read 本 skill)`, "name mstar-harness-core first in the Load Order section"));
+      violations.push(violation12("medium", "roles.loadorder.core.missing", `skill "${name}" Load Order section does not declare mstar-harness-core as its first dependency (mstar-harness-core § 加载约定: 凡 mstar-*（name ≠ mstar-harness-core）假定读者已 Read 本 skill)`, "name mstar-harness-core first in the Load Order section"));
     }
   }
   return { ok: violations.length === 0, violations };
@@ -3458,7 +4508,7 @@ function resolveSkillRoot(host, paths) {
   }
 }
 // src/skill-authoring.ts
-function violation11(severity, code, message, fix) {
+function violation13(severity, code, message, fix) {
   return { ok: false, severity, code, message, fix };
 }
 var FIVE_QUESTION_SECTIONS = [
@@ -3519,7 +4569,7 @@ function lintFiveQuestion(bodyText, mode = "authoring") {
     const aliases = mode === "runtime" ? RUNTIME_HEADING_ALIASES[section.key] ?? [] : [];
     const covered = headings.some((heading) => heading.includes(label) || aliases.some((alias) => heading.includes(alias)));
     if (!covered) {
-      violations.push(violation11("low", `skill-authoring.five-question.${section.key}`, `body does not answer "${section.question}" — no "${section.label}" section (mstar-skill-authoring § Body 必须回答的 5 问 / § 默认 Body 结构)`, `add a "## ${section.label}" section covering ${section.question}`));
+      violations.push(violation13("low", `skill-authoring.five-question.${section.key}`, `body does not answer "${section.question}" — no "${section.label}" section (mstar-skill-authoring § Body 必须回答的 5 问 / § 默认 Body 结构)`, `add a "## ${section.label}" section covering ${section.question}`));
     }
   }
   return { ok: violations.length === 0, violations };
@@ -3528,13 +4578,19 @@ function resolveAssetPath(skillName, relPath, host) {
   return `skill \`${skillName}\` → ${relPath} (${resolveSkillRoot(host, { skill: skillName, rel: relPath })})`;
 }
 export {
+  writeWorkflowSnapshot,
   writeJson,
   withStatusWriteLock,
   verifyPlanExecutionLease,
+  validateWorkflowSnapshot,
+  validateWorkflowEntry,
+  validateStatusV2,
   validateStatus,
   validateSchemaYaml,
   validateRoleMapping,
+  validateRoadmap,
   validateResidual,
+  validateProjectRegister,
   validatePlanRow,
   validateIntegrationMergeLease,
   validateGitignore,
@@ -3543,6 +4599,7 @@ export {
   validateCompassFrontmatter,
   validateAuditStatusBlocks,
   validateAssignmentFields,
+  unregisterWorkflow,
   techDebtRollup,
   taskReportExists,
   taskBrief,
@@ -3554,16 +4611,22 @@ export {
   scaffoldAuditPlan,
   sameHolderResume,
   reviewPackage,
+  resolveWorkflowDir,
   resolveSpecsDir,
   resolveSkillRoot,
   resolveSddDir,
+  resolveRepoEnforcement,
   resolveProjectRoot,
+  resolveProjectDir,
   resolvePlanDir,
+  resolveMstarcEnforcement,
+  resolveKnowledgeDir,
   resolveIterationDir,
   resolveHarnessDir,
   resolveCompassEnforcement,
   resolveAssetPath,
   releaseLease,
+  registerWorkflow,
   referenceExists,
   redactSecrets,
   readProgressLedger,
@@ -3572,13 +4635,17 @@ export {
   pushCadenceProbe,
   planQualityBar,
   planExecutionLeaseLocations,
+  parseMstarc,
   parseEnforcementFlag,
   parseDesignFrontmatter,
+  parseCompassFrontmatterText,
   parseCompassFrontmatter,
   parseBranchPolicyDirectOnBranch,
   parseAssignmentFields,
   parseAssignmentBranchForms,
   normalizeSeverity,
+  migrateHarnessTree,
+  listProjectReferenceFiles,
   lintStrategySections,
   lintSkillFrontmatter,
   lintLoadOrder,
@@ -3591,6 +4658,7 @@ export {
   findingsCleanupGate,
   findTemporaryMarkers,
   findSimplifyMarkers,
+  findMstarc,
   findEphemeralCitations,
   executionModeToN,
   evaluatePhaseGate,
@@ -3613,15 +4681,31 @@ export {
   assertControlVsFeaturePath,
   assertBranchAlignment,
   assertBaseSha,
-  archiveResiduals,
+  applyMigratePlan,
   applyEnforcement,
   antiRecursionPrecheck,
+  _DEFAULT_PROJECT,
+  WORKFLOW_TERMINAL_STATUSES,
+  WORKFLOW_SNAPSHOT_FILE,
+  WORKFLOW_LIFECYCLE_TYPES,
+  WORKFLOW_LIFECYCLE_STATUSES,
   SddScriptError,
   SHARED_FAMILIES,
   SEVERITY_ORDER,
   RUNTIME_HEADING_ALIASES,
   ROLE_MAPPING,
+  ROADMAP_STATUSES,
   QC_REVIEWER_PARAMS,
+  PROJECT_ROADMAP_FILE,
+  PROJECT_REGISTER_FILE,
+  PROJECT_REFERENCES_DIR,
+  NOTES_LEDGER_FILE,
+  MSTARC_WORKFLOW_DIR_KEY,
+  MSTARC_SECTION,
+  MSTARC_PROJECT_DIR_KEY,
+  MSTARC_HARNESS_DIR_KEY,
+  MSTARC_FILE,
+  MIGRATE_STATUS_FILE,
   KNOWLEDGE_SEVERITIES,
   KNOWLEDGE_RESOLUTION_TYPES,
   KNOWLEDGE_REQUIRED_FIELDS,
@@ -3634,5 +4718,6 @@ export {
   AUDIT_RISKS,
   AUDIT_PRIORITIES,
   AUDIT_EFFORTS,
-  AUDIT_CATEGORIES
+  AUDIT_CATEGORIES,
+  ARCHIVED_STATUS_V1_FILE
 };