@mstar-harness/engine 3.4.1 → 3.5.0

package/dist/engine.js

@@ -170,13 +170,13 @@ function isAtOrBelow(dir, root) {
   return rel === "" || !rel.startsWith("..") && !isAbsolute(rel);
 }
 // src/path.ts
-import { existsSync as existsSync5, mkdirSync as mkdirSync5, readdirSync as readdirSync4, readFileSync as readFileSync6, realpathSync as realpathSync2, statSync as statSync3, writeFileSync as writeFileSync3 } from "node:fs";
+import { existsSync as existsSync6, mkdirSync as mkdirSync5, readdirSync as readdirSync5, readFileSync as readFileSync6, realpathSync as realpathSync2, statSync as statSync3, writeFileSync as writeFileSync3 } from "node:fs";
 import { execFileSync } from "node:child_process";
-import { basename as basename2, dirname as dirname5, isAbsolute as isAbsolute3, join as join8, relative as relative2, resolve as resolve6 } from "node:path";
+import { basename as basename3, dirname as dirname5, isAbsolute as isAbsolute4, join as join9, relative as relative2, resolve as resolve7 } from "node:path";
 
 // src/project.ts
-import { existsSync as existsSync4, mkdirSync as mkdirSync4, readFileSync as readFileSync5, readdirSync as readdirSync3 } from "node:fs";
-import { join as join7, resolve as resolve5 } from "node:path";
+import { existsSync as existsSync5, mkdirSync as mkdirSync4, readFileSync as readFileSync5, readdirSync as readdirSync4 } from "node:fs";
+import { basename as basename2, join as join8, resolve as resolve6 } from "node:path";
 
 // src/iteration.ts
 import { existsSync as existsSync2, readdirSync, readFileSync as readFileSync3 } from "node:fs";
@@ -757,9 +757,167 @@ async function withStatusWriteLock(statusPath, fn, opts = {}) {
   }
 }
 
+// src/store.ts
+import { existsSync as existsSync3, readdirSync as readdirSync2, unlinkSync as unlinkSync3 } from "node:fs";
+import { isAbsolute as isAbsolute3, join as join5, resolve as resolve4 } from "node:path";
+var PLAN_SHAPED_KEY_RE = /^[0-9]{8}-[a-z0-9-]+$/;
+function resolveArtifactPath(harnessRoot, ref) {
+  const { kind, key } = ref;
+  if (kind === "json") {
+    if (!isAbsolute3(key)) {
+      throw new Error(`ArtifactStore json key must be an absolute path — got ${JSON.stringify(key)}`);
+    }
+    if (key.split(/[\\/]+/).includes("..")) {
+      throw new Error(`ArtifactStore json key must not contain ".." segments — got ${JSON.stringify(key)}`);
+    }
+    return key;
+  }
+  assertSafePathComponent(key, "ArtifactStore key");
+  if (kind === "status") {
+    if (key !== "root") {
+      throw new Error(`ArtifactStore status key must be "root" — got ${JSON.stringify(key)}`);
+    }
+    return join5(harnessRoot, "status.json");
+  }
+  if (kind === "snapshot") {
+    return join5(resolveWorkflowDir(harnessRoot, { harnessDir: harnessRoot }), key, "snapshot.json");
+  }
+  if (kind === "residuals") {
+    return join5(resolveProjectDir(harnessRoot, { harnessDir: harnessRoot }), key, "residuals.json");
+  }
+  if (PLAN_SHAPED_KEY_RE.test(key)) {
+    return join5(harnessRoot, "sdd", key, "review", "report.json");
+  }
+  return join5(harnessRoot, "sdd", "_reviews", `${key}.json`);
+}
+function listDirNames(dir) {
+  return readDirEntries(dir).filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+}
+function listJsonKeys(dir) {
+  return readDirEntries(dir).filter((entry) => entry.isFile() && entry.name.endsWith(".json")).map((entry) => entry.name.slice(0, -".json".length));
+}
+function readDirEntries(dir) {
+  try {
+    return readdirSync2(dir, { withFileTypes: true });
+  } catch (error) {
+    const code = error.code;
+    if (code === "ENOENT" || code === "ENOTDIR")
+      return [];
+    throw error;
+  }
+}
+function tryResolveGetPath(root, kind, key) {
+  try {
+    return resolveArtifactPath(root, { kind, key });
+  } catch {
+    return;
+  }
+}
+function createFsStore(harnessRoot) {
+  const root = resolve4(harnessRoot);
+  return {
+    root,
+    async put(doc) {
+      if (doc.schema !== undefined) {
+        throw new Error("FsStore does not persist schema ids — omit --schema or inject a store module that persists it");
+      }
+      writeJson(resolveArtifactPath(root, doc), doc.payload);
+    },
+    async get(ref) {
+      const filePath = resolveArtifactPath(root, ref);
+      if (!existsSync3(filePath))
+        return;
+      return readJson(filePath);
+    },
+    async delete(ref) {
+      const filePath = resolveArtifactPath(root, ref);
+      if (existsSync3(filePath))
+        unlinkSync3(filePath);
+    },
+    async list(kind) {
+      if (kind === "json") {
+        throw new Error("ArtifactStore json keys are absolute paths and cannot be listed");
+      }
+      const keys = [];
+      if (kind === "status") {
+        if (existsSync3(resolveArtifactPath(root, { kind, key: "root" })))
+          keys.push("root");
+      } else if (kind === "snapshot" || kind === "residuals") {
+        const baseDir = kind === "snapshot" ? resolveWorkflowDir(root, { harnessDir: root }) : resolveProjectDir(root, { harnessDir: root });
+        for (const name of listDirNames(baseDir)) {
+          const getPath = tryResolveGetPath(root, kind, name);
+          if (getPath !== undefined && existsSync3(getPath))
+            keys.push(name);
+        }
+      } else {
+        const sddDir = join5(root, "sdd");
+        for (const key of listJsonKeys(join5(sddDir, "_reviews"))) {
+          if (!PLAN_SHAPED_KEY_RE.test(key) && tryResolveGetPath(root, kind, key) !== undefined) {
+            keys.push(key);
+          }
+        }
+        for (const name of listDirNames(sddDir)) {
+          if (PLAN_SHAPED_KEY_RE.test(name)) {
+            const getPath = tryResolveGetPath(root, kind, name);
+            if (getPath !== undefined && existsSync3(getPath))
+              keys.push(name);
+          }
+        }
+      }
+      return keys.sort().map((key) => ({ kind, key }));
+    }
+  };
+}
+var injectedStore;
+function setArtifactStore(store) {
+  injectedStore = store;
+}
+function getArtifactStore() {
+  if (injectedStore !== undefined)
+    return injectedStore;
+  const root = resolveHarnessDir(process.cwd());
+  if (root === null) {
+    throw new Error(`harness dir not found from ${resolve4(process.cwd())} — cannot create the default FsStore (run \`mstar harness scaffold\`, pass opts.harnessDir, or set MSTAR_HARNESS_DIR)`);
+  }
+  return createFsStore(root);
+}
+function assertFsStorePath(store, ref, expectedPath) {
+  const root = store.root;
+  if (typeof root !== "string")
+    return;
+  const storePath = resolveArtifactPath(root, ref);
+  const expected = resolve4(expectedPath);
+  if (storePath !== expected) {
+    throw new Error(`routed writer path mismatch: the active FsStore resolves ${ref.kind}/${JSON.stringify(ref.key)} to ${JSON.stringify(storePath)} but the caller's target is ${JSON.stringify(expected)} — call setArtifactStore(createFsStore(<root>)) first when the write target differs from the active store's root`);
+  }
+}
+var URI_SCHEME_RE = /^[A-Za-z][A-Za-z0-9+.-]*:/;
+function isArtifactStore(value) {
+  return typeof value === "object" && value !== null && typeof value.put === "function" && typeof value.get === "function";
+}
+async function loadStoreModule(modulePath) {
+  if (modulePath === "") {
+    throw new Error("loadStoreModule: module path must not be empty");
+  }
+  if (URI_SCHEME_RE.test(modulePath)) {
+    throw new Error(`loadStoreModule: only filesystem paths are allowed — got ${JSON.stringify(modulePath)} (URI schemes such as http:/https:/file: are rejected)`);
+  }
+  const resolved = resolve4(modulePath);
+  if (!existsSync3(resolved)) {
+    throw new Error(`loadStoreModule: module file not found — ${JSON.stringify(resolved)}`);
+  }
+  const mod = await import(resolved);
+  const candidate = mod.createArtifactStore ?? mod.default ?? mod;
+  const store = typeof candidate === "function" ? await candidate() : candidate;
+  if (!isArtifactStore(store)) {
+    throw new Error(`loadStoreModule: module ${JSON.stringify(resolved)} does not export an ArtifactStore — expected a createArtifactStore named export, a default factory, or a default object with put() and get() functions`);
+  }
+  return store;
+}
+
 // src/status.ts
-import { existsSync as existsSync3, readFileSync as readFileSync4, readdirSync as readdirSync2, realpathSync } from "node:fs";
-import { dirname as dirname4, join as join6, resolve as resolve4, sep } from "node:path";
+import { existsSync as existsSync4, readFileSync as readFileSync4, readdirSync as readdirSync3, realpathSync } from "node:fs";
+import { dirname as dirname4, join as join7, resolve as resolve5, sep } from "node:path";
 
 // src/dispatch.ts
 var BRANCH_FORMS_HINT = '"Working branch: <existing>" | "Working branch: create <new> from <base>" | "Branch policy: direct on <branch> — <reason>"';
@@ -1008,7 +1166,7 @@ function antiRecursionPrecheck(subagentType, executeAs) {
 
 // src/workflow.ts
 import { mkdirSync as mkdirSync3 } from "node:fs";
-import { join as join5 } from "node:path";
+import { join as join6 } 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"];
@@ -1125,10 +1283,12 @@ async function writeWorkflowSnapshot(snapshot, dir) {
     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);
+  const snapshotPath = join6(dir, WORKFLOW_SNAPSHOT_FILE);
+  const store = getArtifactStore();
+  assertFsStorePath(store, { kind: "snapshot", key: snapshot.id }, snapshotPath);
   mkdirSync3(dir, { recursive: true });
-  await withStatusWriteLock(snapshotPath, () => {
-    writeJson(snapshotPath, snapshot);
+  await withStatusWriteLock(snapshotPath, async () => {
+    await store.put({ kind: "snapshot", key: snapshot.id, payload: snapshot });
   });
 }
 
@@ -1295,7 +1455,7 @@ function validateStatusV2(docOrPath, opts = {}) {
   if (typeof docOrPath === "string") {
     try {
       doc = readJson(docOrPath);
-      harnessDir = dirname4(resolve4(docOrPath));
+      harnessDir = dirname4(resolve5(docOrPath));
     } catch (error) {
       return {
         ok: false,
@@ -1362,8 +1522,8 @@ function validateStatusV2(docOrPath, opts = {}) {
     for (const entry of doc.workflows) {
       if (!isPlainObject4(entry) || typeof entry.dir !== "string")
         continue;
-      const relSnapshot = join6(entry.dir, WORKFLOW_SNAPSHOT_FILE);
-      const snapshotPath = join6(harnessDir, relSnapshot);
+      const relSnapshot = join7(entry.dir, WORKFLOW_SNAPSHOT_FILE);
+      const snapshotPath = join7(harnessDir, relSnapshot);
       const label = typeof entry.id === "string" ? entry.id : relSnapshot;
       let physical;
       try {
@@ -1397,8 +1557,10 @@ function validateStatusV2(docOrPath, opts = {}) {
   return { ok: violations.length === 0, violations };
 }
 var validateStatus = validateStatusV2;
-function registerWorkflowEntryLocked(statusPath, entry) {
+async function registerWorkflowEntryLocked(statusPath, entry) {
   const harnessDir = dirname4(statusPath);
+  const store = getArtifactStore();
+  assertFsStorePath(store, { kind: "status", key: "root" }, statusPath);
   const current = readJson(statusPath);
   const fresh = Object.keys(current).length === 0;
   const doc = fresh ? { version: 2, updated_at: todayString(), workflows: [] } : current;
@@ -1416,7 +1578,7 @@ function registerWorkflowEntryLocked(statusPath, entry) {
   if (!gate.ok) {
     throw new Error(`refusing to write invalid status.json: ${gate.violations.map((v) => v.message).join("; ")}`);
   }
-  writeJson(statusPath, doc);
+  await store.put({ kind: "status", key: "root", payload: doc });
   return doc;
 }
 async function registerWorkflow(root, entry) {
@@ -1424,16 +1586,18 @@ async function registerWorkflow(root, entry) {
   if (!entryGate.ok) {
     throw new Error(`refusing to register invalid workflow entry: ${entryGate.violations.map((v) => v.message).join("; ")}`);
   }
-  const statusPath = resolve4(root);
+  const statusPath = resolve5(root);
   return withStatusWriteLock(statusPath, () => registerWorkflowEntryLocked(statusPath, entry));
 }
 async function unregisterWorkflow(root, id) {
   if (typeof id !== "string" || id.trim() === "") {
     throw new Error("refusing to unregister workflow: id must be a non-empty string");
   }
-  const statusPath = resolve4(root);
+  const statusPath = resolve5(root);
+  const store = getArtifactStore();
+  assertFsStorePath(store, { kind: "status", key: "root" }, statusPath);
   const harnessDir = dirname4(statusPath);
-  return withStatusWriteLock(statusPath, () => {
+  return withStatusWriteLock(statusPath, async () => {
     const current = readJson(statusPath);
     if (Object.keys(current).length === 0) {
       return { version: 2, updated_at: todayString(), workflows: [] };
@@ -1452,25 +1616,25 @@ async function unregisterWorkflow(root, id) {
     if (!gate.ok) {
       throw new Error(`refusing to write invalid status.json: ${gate.violations.map((v) => v.message).join("; ")}`);
     }
-    writeJson(statusPath, doc);
+    await store.put({ kind: "status", key: "root", payload: doc });
     return doc;
   });
 }
 function resolveCompassEnforcement(harnessDir) {
   const iterationsDir = resolveIterationDir(harnessDir);
-  if (!existsSync3(iterationsDir))
+  if (!existsSync4(iterationsDir))
     return { hard: false, source: "none" };
   let entries;
   try {
-    entries = readdirSync2(iterationsDir, { withFileTypes: true });
+    entries = readdirSync3(iterationsDir, { withFileTypes: true });
   } catch {
     return { hard: false, source: "none" };
   }
   for (const entry of entries) {
     if (!entry.isDirectory())
       continue;
-    const compassPath = join6(iterationsDir, entry.name, "delivery-compass.md");
-    if (!existsSync3(compassPath))
+    const compassPath = join7(iterationsDir, entry.name, "delivery-compass.md");
+    if (!existsSync4(compassPath))
       continue;
     let content;
     try {
@@ -1489,7 +1653,7 @@ function resolveCompassEnforcement(harnessDir) {
   return { hard: false, source: "none" };
 }
 function resolveMstarcEnforcement(harnessDir) {
-  const dir = resolve4(harnessDir);
+  const dir = resolve5(harnessDir);
   const rc = loadMstarc(dir, dirname4(dir));
   const value = rc?.config.enforcement;
   if (value === "hard")
@@ -1641,9 +1805,12 @@ async function appendProjectRegisterEntries(opts) {
   if (opts.entries.length === 0) {
     throw new Error("refusing to append residual entries: entries must not be empty");
   }
-  const registerPath = resolve5(join7(opts.projectDir, PROJECT_REGISTER_FILE));
+  const registerPath = resolve6(join8(opts.projectDir, PROJECT_REGISTER_FILE));
+  const projectKey = basename2(resolve6(opts.projectDir));
+  const store = getArtifactStore();
+  assertFsStorePath(store, { kind: "residuals", key: projectKey }, registerPath);
   mkdirSync4(opts.projectDir, { recursive: true });
-  return withStatusWriteLock(registerPath, () => {
+  return withStatusWriteLock(registerPath, async () => {
     const doc = readJson(registerPath);
     const entriesMap = doc.entries ?? {};
     let key = opts.basePlanKey;
@@ -1678,14 +1845,17 @@ async function appendProjectRegisterEntries(opts) {
     if (!gate.ok) {
       throw new Error(`refusing to write invalid project register: ${gate.violations.map((v) => v.message).join("; ")}`);
     }
-    writeJson(registerPath, register);
+    await store.put({ kind: "residuals", key: projectKey, payload: register });
     return { ok: true, key };
   });
 }
 async function closeProjectRegisterEntry(opts) {
-  const registerPath = resolve5(join7(opts.projectDir, PROJECT_REGISTER_FILE));
+  const registerPath = resolve6(join8(opts.projectDir, PROJECT_REGISTER_FILE));
+  const projectKey = basename2(resolve6(opts.projectDir));
+  const store = getArtifactStore();
+  assertFsStorePath(store, { kind: "residuals", key: projectKey }, registerPath);
   mkdirSync4(opts.projectDir, { recursive: true });
-  return withStatusWriteLock(registerPath, () => {
+  return withStatusWriteLock(registerPath, async () => {
     const doc = readJson(registerPath);
     const planEntries = doc.entries?.[opts.planKey];
     if (!Array.isArray(planEntries)) {
@@ -1705,7 +1875,7 @@ async function closeProjectRegisterEntry(opts) {
     if (!gate.ok) {
       throw new Error(`refusing to write invalid project register: ${gate.violations.map((v) => v.message).join("; ")}`);
     }
-    writeJson(registerPath, register);
+    await store.put({ kind: "residuals", key: projectKey, payload: register });
     return { ok: true };
   });
 }
@@ -1758,15 +1928,15 @@ function techDebtRollup(projectDir) {
   const items = [];
   let entries;
   try {
-    entries = readdirSync3(projectDir, { withFileTypes: true });
+    entries = readdirSync4(projectDir, { withFileTypes: true });
   } catch {
     entries = [];
   }
   for (const project of entries) {
     if (!project.isDirectory())
       continue;
-    const registerPath = join7(projectDir, project.name, PROJECT_REGISTER_FILE);
-    if (!existsSync4(registerPath))
+    const registerPath = join8(projectDir, project.name, PROJECT_REGISTER_FILE);
+    if (!existsSync5(registerPath))
       continue;
     let register;
     try {
@@ -1802,10 +1972,10 @@ function techDebtRollup(projectDir) {
   return { computed, stored, checks, overall };
 }
 function listProjectReferenceFiles(projectDir) {
-  const root = join7(projectDir, PROJECT_REFERENCES_DIR);
+  const root = join8(projectDir, PROJECT_REFERENCES_DIR);
   let entries;
   try {
-    entries = readdirSync3(root, { withFileTypes: true });
+    entries = readdirSync4(root, { withFileTypes: true });
   } catch {
     return [];
   }
@@ -1818,7 +1988,7 @@ function listProjectReferenceFiles(projectDir) {
     } else if (entry.isDirectory()) {
       let nested;
       try {
-        nested = readdirSync3(join7(root, entry.name), { withFileTypes: true });
+        nested = readdirSync4(join8(root, entry.name), { withFileTypes: true });
       } catch {
         continue;
       }
@@ -1833,19 +2003,19 @@ function listProjectReferenceFiles(projectDir) {
 
 // src/path.ts
 function resolveHarnessDir(startDir = process.cwd(), opts = {}) {
-  const start = resolve6(startDir);
+  const start = resolve7(startDir);
   const explicit = opts.harnessDir ?? process.env.MSTAR_HARNESS_DIR;
   if (explicit)
-    return resolve6(start, explicit);
-  const boundary = resolve6(start, opts.workspaceRoot ?? defaultWorkspaceRoot(start));
+    return resolve7(start, explicit);
+  const boundary = resolve7(start, opts.workspaceRoot ?? defaultWorkspaceRoot(start));
   const rc = loadMstarc(start, boundary);
   if (rc !== null && rc.config.harnessDir)
-    return resolve6(rc.dir, rc.config.harnessDir);
+    return resolve7(rc.dir, rc.config.harnessDir);
   let dir = start;
   for (;; ) {
     if (!isAtOrBelow2(dir, boundary))
       return null;
-    for (const candidate of [join8(dir, ".mstar"), join8(dir, ".agents"), join8(dir, ".plans"), join8(dir, "plans")]) {
+    for (const candidate of [join9(dir, ".mstar"), join9(dir, ".agents"), join9(dir, ".plans"), join9(dir, "plans")]) {
       if (isDirectory(candidate))
         return candidate;
     }
@@ -1871,19 +2041,19 @@ function defaultWorkspaceRoot(startDir) {
       if (segment && segment !== ".")
         boundary = dirname5(boundary);
     }
-    return resolve6(boundary);
+    return resolve7(boundary);
   } catch {}
   return startDir;
 }
 function isAtOrBelow2(dir, root) {
   const rel = relative2(root, dir);
-  return rel === "" || !rel.startsWith("..") && !isAbsolute3(rel);
+  return rel === "" || !rel.startsWith("..") && !isAbsolute4(rel);
 }
 function mstarcDirOverride(harnessDir, key) {
-  const dir = resolve6(harnessDir);
+  const dir = resolve7(harnessDir);
   const rc = loadMstarc(dir, dirname5(dir));
   const declared = rc?.config[key];
-  return declared ? resolve6(rc.dir, declared) : null;
+  return declared ? resolve7(rc.dir, declared) : null;
 }
 function resolveSpecsDir(harnessDir, opts = {}) {
   const declared = mstarcDirOverride(harnessDir, "specsDir");
@@ -1892,20 +2062,20 @@ function resolveSpecsDir(harnessDir, opts = {}) {
       mkdirSync5(declared, { recursive: true });
     return declared;
   }
-  const harness = resolve6(harnessDir);
+  const harness = resolve7(harnessDir);
   const repoRoot = dirname5(harness);
   const candidates = [
-    join8(harness, "specs"),
-    join8(repoRoot, "docs", "specs"),
-    join8(repoRoot, "specs"),
-    join8(harness, "designs"),
-    join8(repoRoot, "designs")
+    join9(harness, "specs"),
+    join9(repoRoot, "docs", "specs"),
+    join9(repoRoot, "specs"),
+    join9(harness, "designs"),
+    join9(repoRoot, "designs")
   ];
   for (const candidate of candidates) {
     if (isDirectory(candidate) && hasFiles(candidate))
       return candidate;
   }
-  const fallback = join8(harness, "specs");
+  const fallback = join9(harness, "specs");
   if (opts.create !== false)
     mkdirSync5(fallback, { recursive: true });
   return fallback;
@@ -1914,11 +2084,11 @@ function resolvePlanDir(harnessDir) {
   const declared = mstarcDirOverride(harnessDir, "planDir");
   if (declared !== null)
     return declared;
-  const dir = resolve6(harnessDir);
-  const name = basename2(dir);
+  const dir = resolve7(harnessDir);
+  const name = basename3(dir);
   if (name === ".plans" || name === "plans")
     return dir;
-  return join8(dir, "plans");
+  return join9(dir, "plans");
 }
 function assertSafePathComponent(value, what) {
   if (value === "" || value === "." || value === ".." || !/^[A-Za-z0-9._-]+$/.test(value)) {
@@ -1927,30 +2097,30 @@ function assertSafePathComponent(value, what) {
 }
 function resolveSddDir(harnessDir, planId) {
   assertSafePathComponent(planId, "planId");
-  const base = resolve6(harnessDir);
+  const base = resolve7(harnessDir);
   const declared = mstarcDirOverride(base, "sddDir");
-  const sddBase = declared !== null ? declared : join8(base, "sdd");
-  return join8(sddBase, planId);
+  const sddBase = declared !== null ? declared : join9(base, "sdd");
+  return join9(sddBase, planId);
 }
 function resolveIterationDir(harnessDir) {
   const declared = mstarcDirOverride(harnessDir, "iterationDir");
   if (declared !== null)
     return declared;
-  return join8(resolve6(harnessDir), "iterations");
+  return join9(resolve7(harnessDir), "iterations");
 }
 function resolveKnowledgeDir(harnessDir) {
   const declared = mstarcDirOverride(harnessDir, "knowledgeDir");
   if (declared !== null)
     return declared;
-  return join8(resolve6(harnessDir), "knowledge");
+  return join9(resolve7(harnessDir), "knowledge");
 }
 function resolveHarnessSubdir(startDir, opts, key, fallback) {
   const harness = resolveHarnessDir(startDir, opts);
   if (harness === null) {
-    throw new Error(`harness dir not found from ${resolve6(startDir)} — cannot resolve the ${fallback} dir (run \`mstar harness scaffold\`, pass opts.harnessDir, or set MSTAR_HARNESS_DIR)`);
+    throw new Error(`harness dir not found from ${resolve7(startDir)} — cannot resolve the ${fallback} dir (run \`mstar harness scaffold\`, pass opts.harnessDir, or set MSTAR_HARNESS_DIR)`);
   }
   const declared = mstarcDirOverride(harness, key);
-  return declared !== null ? declared : join8(resolve6(harness), fallback);
+  return declared !== null ? declared : join9(resolve7(harness), fallback);
 }
 function resolveWorkflowDir(startDir = process.cwd(), opts = {}) {
   return resolveHarnessSubdir(startDir, opts, "workflowDir", "workflows");
@@ -1965,13 +2135,13 @@ var EMPTY_STATUS_TEMPLATE = {
 };
 var SCAFFOLD_DIRS = ["plans", "iterations", "knowledge", "specs", "sdd"];
 function resolveScaffoldDirs(root) {
-  const start = resolve6(root);
-  const boundary = resolve6(start, defaultWorkspaceRoot(start));
+  const start = resolve7(root);
+  const boundary = resolve7(start, defaultWorkspaceRoot(start));
   const rc = loadMstarc(start, boundary);
   const explicit = process.env.MSTAR_HARNESS_DIR;
-  const harnessDir = explicit ? resolve6(start, explicit) : rc !== null && rc.config.harnessDir ? resolve6(rc.dir, rc.config.harnessDir) : join8(start, ".mstar");
+  const harnessDir = explicit ? resolve7(start, explicit) : rc !== null && rc.config.harnessDir ? resolve7(rc.dir, rc.config.harnessDir) : join9(start, ".mstar");
   const declaredProjectDir = mstarcDirOverride(harnessDir, "projectDir");
-  const projectDir = declaredProjectDir !== null ? declaredProjectDir : join8(harnessDir, "projects");
+  const projectDir = declaredProjectDir !== null ? declaredProjectDir : join9(harnessDir, "projects");
   return { harnessDir, projectDir };
 }
 var ROADMAP_TEMPLATE = `---
@@ -1993,18 +2163,18 @@ var EMPTY_REGISTER_TEMPLATE = {
 function scaffoldHarness(root) {
   const { harnessDir, projectDir } = resolveScaffoldDirs(root);
   for (const dir of SCAFFOLD_DIRS)
-    mkdirSync5(join8(harnessDir, dir), { recursive: true });
-  const statusPath = join8(harnessDir, "status.json");
+    mkdirSync5(join9(harnessDir, dir), { recursive: true });
+  const statusPath = join9(harnessDir, "status.json");
   if (Object.keys(readJson(statusPath)).length === 0)
     writeJson(statusPath, EMPTY_STATUS_TEMPLATE);
-  const defaultProjectDir = join8(projectDir, _DEFAULT_PROJECT);
+  const defaultProjectDir = join9(projectDir, _DEFAULT_PROJECT);
   mkdirSync5(defaultProjectDir, { recursive: true });
-  const roadmapPath = join8(defaultProjectDir, PROJECT_ROADMAP_FILE);
-  if (!existsSync5(roadmapPath)) {
+  const roadmapPath = join9(defaultProjectDir, PROJECT_ROADMAP_FILE);
+  if (!existsSync6(roadmapPath)) {
     const created = new Date().toISOString().slice(0, 10);
     writeFileSync3(roadmapPath, ROADMAP_TEMPLATE.replace("{created_at}", created), "utf8");
   }
-  const registerPath = join8(defaultProjectDir, PROJECT_REGISTER_FILE);
+  const registerPath = join9(defaultProjectDir, PROJECT_REGISTER_FILE);
   if (Object.keys(readJson(registerPath)).length === 0)
     writeJson(registerPath, EMPTY_REGISTER_TEMPLATE);
   return harnessDir;
@@ -2042,7 +2212,7 @@ function emitGitignoreSnippet(kind) {
   return `${GITIGNORE_SNIPPET}${GITIGNORE_SNIPPET_AGENTS}`;
 }
 function validateGitignore(root) {
-  const gitignorePath = join8(resolve6(root), ".gitignore");
+  const gitignorePath = join9(resolve7(root), ".gitignore");
   const kind = detectHarnessKind(resolveHarnessDir(root));
   let content;
   try {
@@ -2090,7 +2260,7 @@ function validateGitignore(root) {
 function detectHarnessKind(harnessDir) {
   if (!harnessDir)
     return null;
-  const name = basename2(resolve6(harnessDir));
+  const name = basename3(resolve7(harnessDir));
   if (name === ".mstar")
     return "mstar";
   if (name === ".agents")
@@ -2098,7 +2268,7 @@ function detectHarnessKind(harnessDir) {
   return null;
 }
 function assertPlanWritingPath(planPath, harnessDir) {
-  const planAbs = resolve6(planPath);
+  const planAbs = resolve7(planPath);
   if (!harnessDir) {
     return {
       ok: false,
@@ -2110,7 +2280,7 @@ function assertPlanWritingPath(planPath, harnessDir) {
   }
   const planDir = resolvePlanDir(harnessDir);
   const rel = relative2(planDir, planAbs);
-  const inside = rel === "" || !rel.startsWith("..") && !isAbsolute3(rel);
+  const inside = rel === "" || !rel.startsWith("..") && !isAbsolute4(rel);
   if (!inside) {
     return {
       ok: false,
@@ -2120,12 +2290,12 @@ function assertPlanWritingPath(planPath, harnessDir) {
       fix: `write the plan under ${planDir}`
     };
   }
-  if (existsSync5(planAbs)) {
+  if (existsSync6(planAbs)) {
     try {
       const canonicalPlan = realpathSync2(planAbs);
-      const canonicalPlanDir = existsSync5(planDir) ? realpathSync2(planDir) : resolve6(planDir);
+      const canonicalPlanDir = existsSync6(planDir) ? realpathSync2(planDir) : resolve7(planDir);
       const canonicalRel = relative2(canonicalPlanDir, canonicalPlan);
-      const canonicalInside = canonicalRel === "" || !canonicalRel.startsWith("..") && !isAbsolute3(canonicalRel);
+      const canonicalInside = canonicalRel === "" || !canonicalRel.startsWith("..") && !isAbsolute4(canonicalRel);
       if (!canonicalInside) {
         return {
           ok: false,
@@ -2153,9 +2323,9 @@ function isDirectory(dir) {
 }
 function hasFiles(dir) {
   try {
-    for (const entry of readdirSync4(dir, { withFileTypes: true })) {
+    for (const entry of readdirSync5(dir, { withFileTypes: true })) {
       if (entry.isDirectory()) {
-        if (hasFiles(join8(dir, entry.name)))
+        if (hasFiles(join9(dir, entry.name)))
           return true;
       } else if (entry.isFile()) {
         return true;
@@ -2168,8 +2338,8 @@ function hasFiles(dir) {
 }
 // src/worktree.ts
 import { execFileSync as execFileSync2 } from "node:child_process";
-import { existsSync as existsSync6 } from "node:fs";
-import { isAbsolute as isAbsolute4, resolve as resolve7 } from "node:path";
+import { existsSync as existsSync7 } from "node:fs";
+import { isAbsolute as isAbsolute5, resolve as resolve8 } from "node:path";
 var DEFAULT_PROBE_TIMEOUT_MS = 1e4;
 function probeTimeoutMs() {
   const raw = process.env.MSTAR_GIT_PROBE_TIMEOUT_MS;
@@ -2220,10 +2390,10 @@ function l1PreDispatchCheck(input, opts = {}) {
   if (leaseWorkingBranch.trim() === "") {
     violations.push(violation7("high", "worktree.l1.lease-branch-missing", `execution_lease.working_branch is empty for plan "${planId}"`, "record the lease working_branch before dispatch"));
   }
-  if (controlWorktreePath !== "" && leaseWorktreePath !== "" && resolve7(controlWorktreePath) === resolve7(leaseWorktreePath)) {
+  if (controlWorktreePath !== "" && leaseWorktreePath !== "" && resolve8(controlWorktreePath) === resolve8(leaseWorktreePath)) {
     violations.push(violation7("critical", "worktree.l1.lease-equals-control", `execution_lease.worktree_path "${leaseWorktreePath}" equals metadata.control_worktree_path — the feature worktree MUST differ from the control worktree (L1 isolation; product edits never land in the control checkout)`, "use a distinct feature worktree for the plan (git worktree add <path> <branch>) and update the lease"));
   }
-  if (leaseWorktreePath !== "" && !existsSync6(leaseWorktreePath)) {
+  if (leaseWorktreePath !== "" && !existsSync7(leaseWorktreePath)) {
     violations.push(violation7("high", "worktree.l1.feature-missing", `feature worktree directory "${leaseWorktreePath}" does not exist for plan "${planId}"`, `create it before dispatch: git worktree add ${leaseWorktreePath} <working-branch>`));
   } else if (leaseWorktreePath !== "" && leaseWorkingBranch !== "") {
     const probe = probeBranch(leaseWorktreePath, opts);
@@ -2247,17 +2417,17 @@ function l2PreDispatchCheck(input, opts = {}) {
       violations.push(violation7("high", "worktree.l2.track-invalid", `track ${index + 1} is missing worktreePath and/or workingBranch`, "fill both fields for every track"));
       return;
     }
-    if (!isAbsolute4(track.worktreePath)) {
+    if (!isAbsolute5(track.worktreePath)) {
       violations.push(violation7("high", "worktree.l2.track-path-relative", `track ${index + 1} worktreePath "${track.worktreePath}" is not an absolute path — L2 tracks MUST use absolute worktree checkout paths (consistent with the lease validator's absolute worktree_path enforcement)`, `use an absolute path for track ${index + 1} (e.g. /Users/<you>/worktrees/<branch>)`));
       return;
     }
-    const normalized = resolve7(track.worktreePath);
+    const normalized = resolve8(track.worktreePath);
     if (seenPaths.has(normalized)) {
       violations.push(violation7("high", "worktree.l2.track-path-collision", `duplicate worktreePath "${track.worktreePath}" across parallel tracks — L2 parallel-writable isolation requires a distinct absolute Worktree path per track (N parallel invokes ≠ isolation)`, "give every parallel track its own git worktree checkout"));
       return;
     }
     seenPaths.add(normalized);
-    if (!existsSync6(track.worktreePath)) {
+    if (!existsSync7(track.worktreePath)) {
       violations.push(violation7("high", "worktree.l2.track-missing", `track worktree directory "${track.worktreePath}" does not exist`, `create it before dispatch: git worktree add ${track.worktreePath} ${track.workingBranch}`));
       return;
     }
@@ -2272,7 +2442,7 @@ function l2PreDispatchCheck(input, opts = {}) {
 }
 function assertControlVsFeaturePath(controlWorktreePath, featureWorktreePath) {
   const violations = [];
-  const samePath = controlWorktreePath === "" && featureWorktreePath === "" || controlWorktreePath !== "" && featureWorktreePath !== "" && resolve7(controlWorktreePath) === resolve7(featureWorktreePath);
+  const samePath = controlWorktreePath === "" && featureWorktreePath === "" || controlWorktreePath !== "" && featureWorktreePath !== "" && resolve8(controlWorktreePath) === resolve8(featureWorktreePath);
   if (samePath) {
     violations.push(violation7("critical", "worktree.control-feature.same", `control worktree path equals feature/lease worktree path "${controlWorktreePath}" — execution_lease.worktree_path MUST differ from metadata.control_worktree_path`, "use a distinct feature worktree for the plan's product edits"));
   }
@@ -2320,8 +2490,8 @@ function singleReviewSnapshot(assignments) {
 }
 // src/sdd.ts
 import { execFileSync as execFileSync3 } from "node:child_process";
-import { mkdirSync as mkdirSync6, readdirSync as readdirSync5, readFileSync as readFileSync7, realpathSync as realpathSync3, statSync as statSync4, writeFileSync as writeFileSync4 } from "node:fs";
-import { basename as basename3, dirname as dirname6, isAbsolute as isAbsolute5, join as join9, resolve as resolve8 } from "node:path";
+import { mkdirSync as mkdirSync6, readdirSync as readdirSync6, readFileSync as readFileSync7, realpathSync as realpathSync3, statSync as statSync4, writeFileSync as writeFileSync4 } from "node:fs";
+import { basename as basename4, dirname as dirname6, isAbsolute as isAbsolute6, join as join10, resolve as resolve9 } from "node:path";
 class SddScriptError extends Error {
   exitCode;
   constructor(message, exitCode) {
@@ -2358,14 +2528,14 @@ function gitOut(cwd, args) {
   }
 }
 function probeHarnessWithStatus(root) {
-  if (isFile2(join9(root, ".mstar", "status.json")))
-    return join9(root, ".mstar");
-  if (isFile2(join9(root, ".agents", "status.json")))
-    return join9(root, ".agents");
-  if (hasWorkflowSnapshot(join9(root, ".mstar")))
-    return join9(root, ".mstar");
-  if (hasWorkflowSnapshot(join9(root, ".agents")))
-    return join9(root, ".agents");
+  if (isFile2(join10(root, ".mstar", "status.json")))
+    return join10(root, ".mstar");
+  if (isFile2(join10(root, ".agents", "status.json")))
+    return join10(root, ".agents");
+  if (hasWorkflowSnapshot(join10(root, ".mstar")))
+    return join10(root, ".mstar");
+  if (hasWorkflowSnapshot(join10(root, ".agents")))
+    return join10(root, ".agents");
   return null;
 }
 function hasWorkflowSnapshot(harnessDir) {
@@ -2373,13 +2543,13 @@ function hasWorkflowSnapshot(harnessDir) {
   try {
     workflowsDir = resolveWorkflowDir(harnessDir, { harnessDir });
   } catch {
-    workflowsDir = join9(harnessDir, "workflows");
+    workflowsDir = join10(harnessDir, "workflows");
   }
   if (!isDirectory2(workflowsDir))
     return false;
   try {
-    for (const entry of readdirSync5(workflowsDir, { withFileTypes: true })) {
-      if (entry.isDirectory() && isFile2(join9(workflowsDir, entry.name, "snapshot.json")))
+    for (const entry of readdirSync6(workflowsDir, { withFileTypes: true })) {
+      if (entry.isDirectory() && isFile2(join10(workflowsDir, entry.name, "snapshot.json")))
         return true;
     }
   } catch {
@@ -2392,14 +2562,14 @@ function isLinkedWorktree(root) {
   const commonRaw = gitOut(root, ["rev-parse", "--git-common-dir"]);
   if (gitDirRaw === null || commonRaw === null)
     return false;
-  const gitDir = isAbsolute5(gitDirRaw) ? gitDirRaw : join9(root, gitDirRaw);
-  const common = isAbsolute5(commonRaw) ? commonRaw : join9(root, commonRaw);
+  const gitDir = isAbsolute6(gitDirRaw) ? gitDirRaw : join10(root, gitDirRaw);
+  const common = isAbsolute6(commonRaw) ? commonRaw : join10(root, commonRaw);
   if (gitDir.includes("/.git/worktrees/") || gitDir.includes("/worktrees/"))
     return true;
   try {
     const gdParent = realpathSync3(dirname6(gitDir));
     const cmAbs = realpathSync3(common);
-    return join9(gdParent, basename3(gitDir)) !== cmAbs && gitDir !== cmAbs;
+    return join10(gdParent, basename4(gitDir)) !== cmAbs && gitDir !== cmAbs;
   } catch {
     return false;
   }
@@ -2430,28 +2600,28 @@ function sddWorkspace(planId, opts = {}) {
   const harnessOverride = opts.harnessDir ?? (process.env.MSTAR_HARNESS_DIR || undefined);
   let harnessDir;
   if (harnessOverride) {
-    harnessDir = resolve8(root, harnessOverride);
+    harnessDir = resolve9(root, harnessOverride);
   } else {
     const rc = findMstarc(root, root);
     const rcHarnessDir = rc !== null ? parseMstarc(readFileSync7(rc, "utf8")).harnessDir : undefined;
     if (rcHarnessDir) {
-      harnessDir = resolve8(rc !== null ? dirname6(rc) : root, rcHarnessDir);
+      harnessDir = resolve9(rc !== null ? dirname6(rc) : root, rcHarnessDir);
     } else {
       const probed = probeHarnessWithStatus(root);
       if (probed) {
         harnessDir = probed;
-      } else if (isDirectory2(join9(root, ".mstar"))) {
-        harnessDir = join9(root, ".mstar");
-      } else if (isDirectory2(join9(root, ".agents"))) {
-        harnessDir = join9(root, ".agents");
+      } else if (isDirectory2(join10(root, ".mstar"))) {
+        harnessDir = join10(root, ".mstar");
+      } else if (isDirectory2(join10(root, ".agents"))) {
+        harnessDir = join10(root, ".agents");
       } else {
-        harnessDir = join9(root, ".mstar");
+        harnessDir = join10(root, ".mstar");
       }
     }
   }
   const sddDir = resolveSddDir(harnessDir, planId);
   mkdirSync6(sddDir, { recursive: true });
-  writeFileSync4(join9(sddDir, ".gitignore"), `*
+  writeFileSync4(join10(sddDir, ".gitignore"), `*
 `);
   return realpathSync3(sddDir);
 }
@@ -2474,7 +2644,7 @@ function taskBrief(planFile, taskN, outFile, opts = {}) {
       throw new SddScriptError("mstar sdd task-brief: set SDD_DIR or pass OUTFILE (run mstar sdd workspace PLAN_ID first)", 2);
     }
     mkdirSync6(sddDir, { recursive: true });
-    out = join9(sddDir, `task-${taskN}-brief.md`);
+    out = join10(sddDir, `task-${taskN}-brief.md`);
   }
   const records = content.endsWith(`
 `) ? content.split(`
@@ -2527,7 +2697,7 @@ function reviewPackage(base, head, outFile, opts = {}) {
     mkdirSync6(sddDir, { recursive: true });
     const shortBase = gitOut(cwd, ["rev-parse", "--short", base]) ?? base;
     const shortHead = gitOut(cwd, ["rev-parse", "--short", head]) ?? head;
-    out = join9(sddDir, `review-${shortBase}..${shortHead}.diff`);
+    out = join10(sddDir, `review-${shortBase}..${shortHead}.diff`);
   }
   const run = (args) => execFileSync3("git", args, { cwd, maxBuffer: GIT_CAPTURE_MAX_BYTES });
   const parts = [
@@ -2563,7 +2733,7 @@ function assertBaseSha(ref, opts = {}) {
 }
 function taskReportExists(sddDir, taskN) {
   try {
-    const st = statSync4(join9(sddDir, `task-${taskN}-report.md`));
+    const st = statSync4(join10(sddDir, `task-${taskN}-report.md`));
     return st.isFile() && st.size > 0;
   } catch {
     return false;
@@ -2572,7 +2742,7 @@ function taskReportExists(sddDir, taskN) {
 function readProgressLedger(sddDir) {
   let content;
   try {
-    content = readFileSync7(join9(sddDir, "progress.md"), "utf8");
+    content = readFileSync7(join10(sddDir, "progress.md"), "utf8");
   } catch {
     return [];
   }
@@ -2605,8 +2775,8 @@ function implementerSessionStickyRules(input) {
   return { resume: true, reason: `sticky resume OK: host_agent_id ${session.host_agent_id}, next task ${nextTask}` };
 }
 // src/migrate.ts
-import { copyFileSync, mkdirSync as mkdirSync7, readFileSync as readFileSync8, readdirSync as readdirSync6, writeFileSync as writeFileSync5 } from "node:fs";
-import { dirname as dirname7, isAbsolute as isAbsolute6, join as join10, relative as relative3, resolve as resolve9, sep as sep2 } from "node:path";
+import { copyFileSync, mkdirSync as mkdirSync7, readFileSync as readFileSync8, readdirSync as readdirSync7, writeFileSync as writeFileSync5 } from "node:fs";
+import { dirname as dirname7, isAbsolute as isAbsolute7, join as join11, relative as relative3, resolve as resolve10, 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";
@@ -2646,18 +2816,18 @@ function todayString3() {
   return `${now.getFullYear()}-${month}-${day}`;
 }
 function scanCompasses(harnessDir) {
-  const iterationsDir = join10(harnessDir, "iterations");
+  const iterationsDir = join11(harnessDir, "iterations");
   const out = [];
   let entries;
   try {
-    entries = readdirSync6(iterationsDir, { withFileTypes: true });
+    entries = readdirSync7(iterationsDir, { withFileTypes: true });
   } catch {
     return out;
   }
   for (const entry of entries) {
     if (!entry.isDirectory())
       continue;
-    const compassPath = join10(iterationsDir, entry.name, "delivery-compass.md");
+    const compassPath = join11(iterationsDir, entry.name, "delivery-compass.md");
     let content;
     try {
       content = readFileSync8(compassPath, "utf8");
@@ -2737,8 +2907,8 @@ function buildIterationSnapshot(compass, rowById, rootUpdatedAt) {
     id: compass.id,
     type: "iteration",
     status,
-    file: join10("workflows", compass.id, WORKFLOW_SNAPSHOT_FILE),
-    source: join10("iterations", compass.id, "delivery-compass.md"),
+    file: join11("workflows", compass.id, WORKFLOW_SNAPSHOT_FILE),
+    source: join11("iterations", compass.id, "delivery-compass.md"),
     data: snapshot
   };
 }
@@ -2773,7 +2943,7 @@ function buildStandaloneSnapshot(row, rootUpdatedAt, migrationNotes) {
     id,
     type: "plan",
     status,
-    file: join10("workflows", id, WORKFLOW_SNAPSHOT_FILE),
+    file: join11("workflows", id, WORKFLOW_SNAPSHOT_FILE),
     source: "status.json plans[] row",
     data: snapshot
   };
@@ -2881,7 +3051,7 @@ function buildRegister(residualFindings, byPlan, projectId, migratedAt) {
     return null;
   const doc = { entries };
   return {
-    file: join10("projects", projectId, PROJECT_REGISTER_FILE),
+    file: join11("projects", projectId, PROJECT_REGISTER_FILE),
     source: "status.json residual_findings",
     data: doc
   };
@@ -2912,7 +3082,7 @@ function collectNotesFiles(snapshots) {
     if (lines.length === 0)
       continue;
     out.push({
-      file: join10(dirname7(snapshot.file), NOTES_LEDGER_FILE),
+      file: join11(dirname7(snapshot.file), NOTES_LEDGER_FILE),
       source,
       lines
     });
@@ -2920,11 +3090,11 @@ function collectNotesFiles(snapshots) {
   return out;
 }
 function migrateHarnessTree(root, opts = {}) {
-  const harnessDir = resolve9(root);
+  const harnessDir = resolve10(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 statusPath = join11(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";
@@ -3020,7 +3190,7 @@ function migrateHarnessTree(root, opts = {}) {
       migrationNotes.push(`roadmap title sanitized for frontmatter (line breaks replaced with spaces): ${JSON.stringify(rawTitle)}`);
     }
     roadmap = {
-      file: join10("projects", projectId, PROJECT_ROADMAP_FILE),
+      file: join11("projects", projectId, PROJECT_ROADMAP_FILE),
       source: "status.json metadata.program_roadmap",
       content: buildRoadmap({ ...programRoadmap, title: sanitizedTitle }, projectId, migratedAt)
     };
@@ -3069,19 +3239,19 @@ async function applyMigratePlan(plan) {
   if (plan.dryRun) {
     return { applied: false, message: `dry-run: ${plan.steps.length} steps planned (source → destination), zero writes` };
   }
-  const statusPath = join10(plan.root, MIGRATE_STATUS_FILE);
+  const statusPath = join11(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 = resolve9(plan.root);
-  const workflowRoot = resolve9(plan.workflowDir);
-  const projectRoot = resolve9(plan.projectDir);
-  if (!isAbsolute6(plan.workflowDir) || !isAbsolute6(plan.projectDir)) {
+  const harnessRoot = resolve10(plan.root);
+  const workflowRoot = resolve10(plan.workflowDir);
+  const projectRoot = resolve10(plan.projectDir);
+  if (!isAbsolute7(plan.workflowDir) || !isAbsolute7(plan.projectDir)) {
     throw new Error(`refusing to apply migration: plan workflowDir/projectDir must be absolute (got ${JSON.stringify(plan.workflowDir)} / ${JSON.stringify(plan.projectDir)})`);
   }
-  const workflowTargetOf = (canonicalFile) => join10(workflowRoot, relative3("workflows", canonicalFile));
-  const projectTargetOf = (canonicalFile) => join10(projectRoot, relative3("projects", canonicalFile));
+  const workflowTargetOf = (canonicalFile) => join11(workflowRoot, relative3("workflows", canonicalFile));
+  const projectTargetOf = (canonicalFile) => join11(projectRoot, relative3("projects", canonicalFile));
   const allDestinations = [
     plan.archive.file,
     ...plan.snapshots.map((snapshot) => snapshot.file),
@@ -3090,14 +3260,14 @@ async function applyMigratePlan(plan) {
     ...plan.roadmap !== null ? [plan.roadmap.file] : []
   ];
   for (const destination of allDestinations) {
-    const resolvedDest = resolve9(join10(plan.root, destination));
+    const resolvedDest = resolve10(join11(plan.root, destination));
     const inside = (dir) => resolvedDest === dir || resolvedDest.startsWith(`${dir}${sep2}`);
     if (!inside(harnessRoot) && !inside(workflowRoot) && !inside(projectRoot)) {
       throw new Error(`refusing to apply migration: destination escapes the harness dir (${JSON.stringify(destination)}) — every write must stay under ${JSON.stringify(plan.root)}, the workflow dir (${JSON.stringify(plan.workflowDir)}) or the project dir (${JSON.stringify(plan.projectDir)})`);
     }
   }
-  mkdirSync7(join10(plan.root, dirname7(plan.archive.file)), { recursive: true });
-  copyFileSync(statusPath, join10(plan.root, plan.archive.file));
+  mkdirSync7(join11(plan.root, dirname7(plan.archive.file)), { recursive: true });
+  copyFileSync(statusPath, join11(plan.root, plan.archive.file));
   for (const snapshot of plan.snapshots) {
     await writeWorkflowSnapshot(snapshot.data, dirname7(workflowTargetOf(snapshot.file)));
   }
@@ -3546,8 +3716,8 @@ function completenessLevel(frontmatterText, checklist) {
 }
 // src/audit.ts
 import { execFileSync as execFileSync4 } from "node:child_process";
-import { existsSync as existsSync7, mkdirSync as mkdirSync8, readdirSync as readdirSync7, readFileSync as readFileSync9, rmdirSync as rmdirSync2, rmSync, writeFileSync as writeFileSync6 } from "node:fs";
-import { basename as basename4, join as join11, resolve as resolve10, sep as sep3 } from "node:path";
+import { existsSync as existsSync8, mkdirSync as mkdirSync8, readdirSync as readdirSync8, readFileSync as readFileSync9, rmdirSync as rmdirSync2, rmSync, writeFileSync as writeFileSync6 } from "node:fs";
+import { basename as basename5, join as join12, resolve as resolve11, sep as sep3 } from "node:path";
 function violation9(severity, code, message, fix) {
   return { ok: false, severity, code, message, fix };
 }
@@ -3848,7 +4018,7 @@ function scanSecrets(files) {
       unreadableFiles++;
       continue;
     }
-    const base = basename4(file);
+    const base = basename5(file);
     for (const entry of NEVER_COMMIT_FILENAMES) {
       if (entry.re.test(base))
         findings.push({ file, line: 1, type: entry.type });
@@ -3900,12 +4070,12 @@ var LOCKFILE_NAMES = [
 function rootLockfiles(root) {
   let entries;
   try {
-    entries = readdirSync7(root, { withFileTypes: true });
+    entries = readdirSync8(root, { withFileTypes: true });
   } catch {
     return [];
   }
   const names = new Set(LOCKFILE_NAMES);
-  const present = entries.filter((entry) => entry.isFile() && names.has(entry.name)).map((entry) => join11(root, entry.name));
+  const present = entries.filter((entry) => entry.isFile() && names.has(entry.name)).map((entry) => join12(root, entry.name));
   if (present.length === 0)
     return [];
   try {
@@ -3914,7 +4084,7 @@ function rootLockfiles(root) {
       encoding: "utf8",
       stdio: ["ignore", "pipe", "ignore"]
     }).split("\x00").filter((f) => f !== ""));
-    return present.filter((p) => tracked.has(basename4(p)));
+    return present.filter((p) => tracked.has(basename5(p)));
   } catch {
     return present;
   }
@@ -3930,17 +4100,17 @@ function supplyChainChecks(repoRoot) {
     findings.push({ kind: "lockfile-duplicate", file: lockfiles.map((f) => f.replace(`${repoRoot}/`, "")).join(", ") });
     violations.push(violation9("medium", "audit.supply.lockfile-duplicate", `multiple lockfiles at ${repoRoot}: ${lockfiles.join(", ")}`, "keep exactly one lockfile per package manager"));
   }
-  const workflowsDir = join11(repoRoot, ".github", "workflows");
+  const workflowsDir = join12(repoRoot, ".github", "workflows");
   let wfEntries = [];
   try {
-    wfEntries = readdirSync7(workflowsDir, { withFileTypes: true });
+    wfEntries = readdirSync8(workflowsDir, { withFileTypes: true });
   } catch {
     wfEntries = [];
   }
   for (const entry of wfEntries) {
     if (!entry.isFile() || !/\.(?:ya?ml)$/.test(entry.name))
       continue;
-    const wfPath = join11(workflowsDir, entry.name);
+    const wfPath = join12(workflowsDir, entry.name);
     const relPath = `.github/workflows/${entry.name}`;
     let text;
     try {
@@ -4097,9 +4267,9 @@ function scaffoldAuditPlan(outDir, findings, options = {}) {
   const date = options.date ?? new Date().toISOString().slice(0, 10);
   const plannedAt = options.plannedAt ?? { commit: options.repoShortSha ?? "unknown", date };
   mkdirSync8(outDir, { recursive: true });
-  const existingReadme = join11(outDir, "README.md");
-  const carried = existsSync7(existingReadme) ? extractSecurityDispositionSections(readFileSync9(existingReadme, "utf8")) : { needsVerification: [], hardeningChecked: [] };
-  const existing = readdirSync7(outDir).filter((f) => /^\d{3}-.*\.md$/.test(f));
+  const existingReadme = join12(outDir, "README.md");
+  const carried = existsSync8(existingReadme) ? extractSecurityDispositionSections(readFileSync9(existingReadme, "utf8")) : { needsVerification: [], hardeningChecked: [] };
+  const existing = readdirSync8(outDir).filter((f) => /^\d{3}-.*\.md$/.test(f));
   let next = existing.reduce((max, f) => Math.max(max, Number(f.slice(0, 3))), 0) + 1;
   const redactedFindings = findings.map(redactFinding);
   const written = [];
@@ -4115,13 +4285,13 @@ function scaffoldAuditPlan(outDir, findings, options = {}) {
     }
     usedSlugs.add(slug);
     const file = `${num}-${slug}.md`;
-    writeFileSync6(join11(outDir, file), renderPlanFile(finding, plannedAt));
+    writeFileSync6(join12(outDir, file), renderPlanFile(finding, plannedAt));
     written.push(file);
     next++;
   }
   const all = [...existing, ...written].sort();
   const rows = all.map((file) => {
-    const summary = readPlanFileSummary(join11(outDir, file));
+    const summary = readPlanFileSummary(join12(outDir, file));
     const fields = summary.fields;
     return {
       num: file.slice(0, 3),
@@ -4155,7 +4325,7 @@ function scaffoldAuditPlan(outDir, findings, options = {}) {
   });
   const needsVerificationLines = options.needsVerification !== undefined ? options.needsVerification.map((nv) => `- ${escapeCell(redactText(nv.lead))}: ${escapeCell(redactText(nv.how))}${nv.evidence ? ` (${escapeCell(redactText(nv.evidence))})` : ""}`) : carried.needsVerification;
   const hardeningCheckedLines = options.hardeningChecked !== undefined ? options.hardeningChecked.map((hc) => `- ${hc.kind}: ${escapeCell(redactText(hc.text))}`) : carried.hardeningChecked;
-  writeFileSync6(join11(outDir, "README.md"), renderIndex({
+  writeFileSync6(join12(outDir, "README.md"), renderIndex({
     date,
     repoName: options.repoName ?? "repo",
     repoShortSha: options.repoShortSha ?? "unknown",
@@ -4164,7 +4334,7 @@ function scaffoldAuditPlan(outDir, findings, options = {}) {
     needsVerification: needsVerificationLines,
     hardeningChecked: hardeningCheckedLines
   }));
-  return { outDir: resolve10(outDir), date, files: written, nextNumber: next };
+  return { outDir: resolve11(outDir), date, files: written, nextNumber: next };
 }
 async function promoteAuditPlans(outDir, selected, options) {
   if (selected.length === 0) {
@@ -4173,19 +4343,19 @@ async function promoteAuditPlans(outDir, selected, options) {
   if (typeof options.harnessDir !== "string" || options.harnessDir.trim() === "") {
     throw new Error("promoteAuditPlans: options.harnessDir is required (must contain status.json + workflows/)");
   }
-  const workflowId = options.workflowId ?? basename4(resolve10(outDir));
+  const workflowId = options.workflowId ?? basename5(resolve11(outDir));
   assertSafePathComponent(workflowId, "workflow id");
-  const harnessDir = resolve10(options.harnessDir);
-  const statusPath = join11(harnessDir, "status.json");
-  const workflowDir = join11(harnessDir, "workflows", workflowId);
-  const snapshotPath = join11(workflowDir, WORKFLOW_SNAPSHOT_FILE);
+  const harnessDir = resolve11(options.harnessDir);
+  const statusPath = join12(harnessDir, "status.json");
+  const workflowDir = join12(harnessDir, "workflows", workflowId);
+  const snapshotPath = join12(workflowDir, WORKFLOW_SNAPSHOT_FILE);
   const planFiles = resolveSelectedPlanFiles(outDir, selected);
   const indexRows = readExecutionOrderIndex(outDir);
   const plans = planFiles.map((planFile) => {
     const stem = planFile.replace(/\.md$/, "");
     const num = stem.slice(0, 3);
     const indexRow = indexRows.get(num);
-    const title = indexRow?.title ?? readPlanFileSummary(join11(outDir, planFile)).title;
+    const title = indexRow?.title ?? readPlanFileSummary(join12(outDir, planFile)).title;
     return {
       id: stem,
       title,
@@ -4213,18 +4383,18 @@ async function promoteAuditPlans(outDir, selected, options) {
   if (!entryGate.ok) {
     throw new Error(`refusing to register invalid workflow entry: ${entryGate.violations.map((v) => v.message).join("; ")}`);
   }
-  await withStatusWriteLock(statusPath, () => {
-    if (existsSync7(snapshotPath)) {
+  await withStatusWriteLock(statusPath, async () => {
+    if (existsSync8(snapshotPath)) {
       throw new Error(`refusing to promote audit plans: workflow ${JSON.stringify(workflowId)} already exists ` + `(snapshot at ${snapshotPath}) — re-promote would drop its registered plan rows; ` + `remove that workflow before promoting again`);
     }
     mkdirSync8(workflowDir, { recursive: true });
     try {
       writeJson(snapshotPath, snapshot);
-      registerWorkflowEntryLocked(statusPath, entry);
+      await registerWorkflowEntryLocked(statusPath, entry);
     } catch (error) {
       rmSync(snapshotPath, { force: true });
       try {
-        if (readdirSync7(workflowDir).length === 0) {
+        if (readdirSync8(workflowDir).length === 0) {
           rmdirSync2(workflowDir);
         }
       } catch {}
@@ -4235,7 +4405,7 @@ async function promoteAuditPlans(outDir, selected, options) {
   return { workflowId, snapshotPath };
 }
 function resolveSelectedPlanFiles(outDir, selected) {
-  const files = readdirSync7(outDir).filter((f) => /^\d{3}-.*\.md$/.test(f)).sort();
+  const files = readdirSync8(outDir).filter((f) => /^\d{3}-.*\.md$/.test(f)).sort();
   const byNum = new Map;
   const byStem = new Map;
   for (const file of files) {
@@ -4250,7 +4420,7 @@ function resolveSelectedPlanFiles(outDir, selected) {
   for (const id of selected) {
     const file = byNum.get(id) ?? byStem.get(id) ?? byStem.get(id.replace(/\.md$/, ""));
     if (file === undefined) {
-      throw new Error(`promoteAuditPlans: selected plan ${JSON.stringify(id)} does not match any NNN-*.md file in ${resolve10(outDir)}`);
+      throw new Error(`promoteAuditPlans: selected plan ${JSON.stringify(id)} does not match any NNN-*.md file in ${resolve11(outDir)}`);
     }
     if (!seen.has(file)) {
       seen.add(file);
@@ -4260,7 +4430,7 @@ function resolveSelectedPlanFiles(outDir, selected) {
   return resolved;
 }
 function readExecutionOrderIndex(outDir) {
-  const readmePath = join11(outDir, "README.md");
+  const readmePath = join12(outDir, "README.md");
   let text;
   try {
     text = readFileSync9(readmePath, "utf8");
@@ -4289,7 +4459,7 @@ function readExecutionOrderIndex(outDir) {
   return rows;
 }
 function planFileRel(outDir, planFile) {
-  const resolved = resolve10(outDir);
+  const resolved = resolve11(outDir);
   const parts = resolved.split(sep3);
   const plansIdx = parts.lastIndexOf("plans");
   if (plansIdx >= 0) {
@@ -4298,8 +4468,8 @@ function planFileRel(outDir, planFile) {
   return planFile;
 }
 // src/compound.ts
-import { existsSync as existsSync8, readdirSync as readdirSync8, readFileSync as readFileSync10 } from "node:fs";
-import { basename as basename5, isAbsolute as isAbsolute7, join as join12, relative as relative4, resolve as resolve11, sep as sep4 } from "node:path";
+import { existsSync as existsSync9, readdirSync as readdirSync9, readFileSync as readFileSync10 } from "node:fs";
+import { basename as basename6, isAbsolute as isAbsolute8, join as join13, relative as relative4, resolve as resolve12, sep as sep4 } from "node:path";
 function violation10(severity, code, message, fix) {
   return { ok: false, severity, code, message, fix };
 }
@@ -4566,7 +4736,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("~") || isAbsolute7(ref)) {
+    if (SCHEME_RE.test(ref) || ref.startsWith("{") || ref.startsWith("#") || ref.includes("*") || ref.includes("?") || ref.startsWith("~") || isAbsolute8(ref)) {
       continue;
     }
     if (ref.includes("/") || REF_EXT_RE.test(ref)) {
@@ -4585,7 +4755,7 @@ function referenceExists(repoRoot, docText) {
       const dir = stack.pop();
       let entries;
       try {
-        entries = readdirSync8(dir, { withFileTypes: true });
+        entries = readdirSync9(dir, { withFileTypes: true });
       } catch {
         continue;
       }
@@ -4594,7 +4764,7 @@ function referenceExists(repoRoot, docText) {
           break;
         if (entry.isDirectory()) {
           if (!WALK_SKIP_DIRS.has(entry.name))
-            stack.push(join12(dir, entry.name));
+            stack.push(join13(dir, entry.name));
         } else if (!entry.isSymbolicLink()) {
           const base = entry.name.replace(/\.(?:ts|tsx|js|jsx|mjs|cjs)$/, "");
           if (moduleNames.has(base))
@@ -4606,7 +4776,7 @@ function referenceExists(repoRoot, docText) {
   for (const { ref, isSymbol, module } of refs) {
     if (!isSymbol || module === undefined) {
       const candidate = ref.replace(LINE_SUFFIX_RE, "").replace(ANCHOR_RE, "");
-      if (existsSync8(resolve11(repoRoot, candidate))) {
+      if (existsSync9(resolve12(repoRoot, candidate))) {
         checked++;
       } else {
         violations.push(violation10("medium", "compound.reference.missing-file", `referenced path \`${ref}\` does not exist under ${repoRoot} (compound-refresh Phase 2: referenced code still exists?)`, "update the doc to reference an existing path, or delete the stale reference"));
@@ -4626,14 +4796,14 @@ function collectKnowledgeDocs(dir) {
     const current = stack.pop();
     let entries;
     try {
-      entries = readdirSync8(current, { withFileTypes: true });
+      entries = readdirSync9(current, { withFileTypes: true });
     } catch {
       continue;
     }
     for (const entry of entries) {
       if (entry.isSymbolicLink())
         continue;
-      const full = join12(current, entry.name);
+      const full = join13(current, entry.name);
       if (entry.isDirectory()) {
         stack.push(full);
       } else if (entry.name.endsWith(".md") && entry.name !== "README.md" && entry.name !== "index.md") {
@@ -4653,8 +4823,8 @@ function normalizeIndexRef(cell) {
 }
 function assertIndexRows(knowledgeDir) {
   const violations = [];
-  const readmePath = join12(knowledgeDir, "README.md");
-  if (!existsSync8(readmePath)) {
+  const readmePath = join13(knowledgeDir, "README.md");
+  if (!existsSync9(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 };
   }
@@ -4679,19 +4849,19 @@ function assertIndexRows(knowledgeDir) {
 }
 function compoundRefreshScope(harnessDir, projectRoot) {
   return [
-    join12(harnessDir, "knowledge"),
-    join12(harnessDir, "knowledge", "README.md"),
-    join12(projectRoot, "CONCEPTS.md"),
-    join12(harnessDir, "status.json")
+    join13(harnessDir, "knowledge"),
+    join13(harnessDir, "knowledge", "README.md"),
+    join13(projectRoot, "CONCEPTS.md"),
+    join13(harnessDir, "status.json")
   ];
 }
 function isFileLikeRoot(root) {
-  return /^[^.]*\.[A-Za-z0-9]{1,10}$/.test(basename5(root));
+  return /^[^.]*\.[A-Za-z0-9]{1,10}$/.test(basename6(root));
 }
 function scopeGuard(path, allowedRoots) {
-  const resolved = resolve11(path);
+  const resolved = resolve12(path);
   for (const root of allowedRoots) {
-    const r = resolve11(root);
+    const r = resolve12(root);
     if (isFileLikeRoot(r)) {
       if (resolved === r)
         return { ok: true, violations: [] };
@@ -4939,8 +5109,8 @@ function lintStrategySections(docText) {
   return { ok: violations.length === 0, violations };
 }
 // src/roles.ts
-import { existsSync as existsSync9 } from "node:fs";
-import { join as join13 } from "node:path";
+import { existsSync as existsSync10 } from "node:fs";
+import { join as join14 } from "node:path";
 function violation12(severity, code, message, fix) {
   return { ok: false, severity, code, message, fix };
 }
@@ -4996,8 +5166,8 @@ function validateRoleMapping(rolesDir, options = {}) {
   const violations = [];
   const referenceById = new Map(mapping.map((m) => [m.agentId, m.reference]));
   for (const { agentId, reference } of mapping) {
-    if (!existsSync9(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`));
+    if (!existsSync10(join14(rolesDir, reference))) {
+      violations.push(violation12("medium", "roles.mapping.reference.missing", `role "${agentId}" maps to ${reference} which does not exist under ${rolesDir} (mstar-roles § Role Reference Mapping)`, `create ${join14(rolesDir, reference)} or fix the mapping row`));
     }
   }
   for (const { family, memberIds } of families) {
@@ -5202,8 +5372,8 @@ function resolveAssetPath(skillName, relPath, host) {
   return `skill \`${skillName}\` → ${relPath} (${resolveSkillRoot(host, { skill: skillName, rel: relPath })})`;
 }
 // src/prreview.ts
-import { readdirSync as readdirSync9 } from "node:fs";
-import { isAbsolute as isAbsolute8, join as join14 } from "node:path";
+import { readdirSync as readdirSync10 } from "node:fs";
+import { isAbsolute as isAbsolute9, join as join15 } from "node:path";
 var MERGE_CLASSES = ["must-fix", "should-fix", "nit"];
 var PR_VERDICTS = ["ship it", "needs fixes", "blocked"];
 var REVIEW_EMOJI = {
@@ -5240,6 +5410,162 @@ function computePrTally(input) {
 ` + `must-fix=${mustFix} should-fix=${shouldFix} nit=${nit} unverified=${unverified}`;
   return { verdict, scorePct, tally: { mustFix, shouldFix, nit, unverified }, chatHeader };
 }
+var REVIEW_SCHEMA_ID = "mstar.review/v1";
+var INSPECTOR_VERDICTS = ["comment", "request_changes", "approve"];
+var INSPECTOR_SEVERITIES = ["critical", "warning", "suggestion", "info"];
+function isPlainObject7(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+var TALLY_COUNT_KEYS = ["mustFix", "shouldFix", "nit", "unverified"];
+function checkProvidedTallyShape(tally, violations) {
+  if (typeof tally.verdict !== "string" || !PR_VERDICTS.includes(tally.verdict)) {
+    violations.push(violation14("high", "review.tally-malformed", `tally.verdict "${String(tally.verdict)}" is not one of ${JSON.stringify(PR_VERDICTS)}`, `use one of: ${PR_VERDICTS.join(" | ")}`));
+  }
+  if (typeof tally.scorePct !== "number" || !Number.isInteger(tally.scorePct) || tally.scorePct < 0 || tally.scorePct > 100) {
+    violations.push(violation14("high", "review.tally-malformed", `tally.scorePct must be an integer in [0, 100] - got ${String(tally.scorePct)}`));
+  }
+  if (!isPlainObject7(tally.tally)) {
+    violations.push(violation14("high", "review.tally-malformed", "tally.tally must be an object carrying the four class counts"));
+  } else {
+    for (const key of TALLY_COUNT_KEYS) {
+      const count = tally.tally[key];
+      if (typeof count !== "number" || !Number.isInteger(count) || count < 0) {
+        violations.push(violation14("high", "review.tally-malformed", `tally.tally.${key} must be a non-negative integer - got ${String(count)}`));
+      }
+    }
+  }
+  if (typeof tally.chatHeader !== "string") {
+    violations.push(violation14("high", "review.tally-malformed", `tally.chatHeader must be a string - got ${typeof tally.chatHeader}`));
+  }
+}
+function validateMstarReviewV1(doc) {
+  const violations = [];
+  if (!isPlainObject7(doc)) {
+    return {
+      ok: false,
+      violations: [violation14("high", "review.not-object", "review document must be a JSON object")]
+    };
+  }
+  if (doc.schema === undefined) {
+    violations.push(violation14("high", "review.missing-schema", "missing required field: schema"));
+  } else if (doc.schema !== REVIEW_SCHEMA_ID) {
+    violations.push(violation14("high", "review.invalid-schema", `schema "${String(doc.schema)}" is not "${REVIEW_SCHEMA_ID}"`));
+  }
+  if (doc.verdict === undefined) {
+    violations.push(violation14("high", "review.missing-verdict", "missing required field: verdict"));
+  } else if (typeof doc.verdict !== "string") {
+    violations.push(violation14("high", "review.invalid-verdict", `verdict must be a string - got ${typeof doc.verdict}`));
+  } else if (INSPECTOR_VERDICTS.includes(doc.verdict)) {
+    violations.push(violation14("high", "review.inspector-vocab", `verdict "${doc.verdict}" is inspector M1 vocab - harness verdicts are ${JSON.stringify(PR_VERDICTS)}`, `use one of: ${PR_VERDICTS.join(" | ")}`));
+  } else if (!PR_VERDICTS.includes(doc.verdict)) {
+    violations.push(violation14("high", "review.invalid-verdict", `verdict "${doc.verdict}" is not one of ${JSON.stringify(PR_VERDICTS)}`, `use one of: ${PR_VERDICTS.join(" | ")}`));
+  }
+  if (doc.summary_md === undefined || typeof doc.summary_md !== "string" || doc.summary_md.trim() === "") {
+    violations.push(violation14("high", "review.missing-summary", "summary_md must be a non-empty string"));
+  }
+  if (doc.findings === undefined || !Array.isArray(doc.findings)) {
+    violations.push(violation14("high", "review.findings-not-array", "findings must be an array"));
+  } else {
+    doc.findings.forEach((finding, index) => {
+      if (!isPlainObject7(finding)) {
+        violations.push(violation14("high", "review.invalid-finding", `findings[${index}] must be an object`));
+        return;
+      }
+      if (finding.severity !== undefined) {
+        violations.push(violation14("high", "review.inspector-vocab", `findings[${index}] carries inspector M1 field "severity" - harness merge classes are ${JSON.stringify(MERGE_CLASSES)}`, "use mergeClass: must-fix | should-fix | nit"));
+      }
+      if (finding.mergeClass === undefined) {
+        violations.push(violation14("high", "review.missing-merge-class", `findings[${index}] missing required field: mergeClass`));
+      } else if (typeof finding.mergeClass !== "string") {
+        violations.push(violation14("high", "review.invalid-merge-class", `findings[${index}].mergeClass must be a string - got ${typeof finding.mergeClass}`));
+      } else if (INSPECTOR_SEVERITIES.includes(finding.mergeClass)) {
+        violations.push(violation14("high", "review.inspector-vocab", `findings[${index}].mergeClass "${finding.mergeClass}" is inspector M1 severity vocab - harness merge classes are ${JSON.stringify(MERGE_CLASSES)}`, `use one of: ${MERGE_CLASSES.join(" | ")}`));
+      } else if (!MERGE_CLASSES.includes(finding.mergeClass)) {
+        violations.push(violation14("high", "review.invalid-merge-class", `findings[${index}].mergeClass "${finding.mergeClass}" is not one of ${JSON.stringify(MERGE_CLASSES)}`, `use one of: ${MERGE_CLASSES.join(" | ")}`));
+      }
+      if (finding.title === undefined || typeof finding.title !== "string" || finding.title.trim() === "") {
+        violations.push(violation14("high", "review.empty-title", `findings[${index}].title must be a non-empty string`));
+      }
+      if (finding.body === undefined || typeof finding.body !== "string" || finding.body.trim() === "") {
+        violations.push(violation14("high", "review.empty-body", `findings[${index}].body must be a non-empty string`));
+      }
+      if (finding.category !== undefined && typeof finding.category !== "string") {
+        violations.push(violation14("high", "review.invalid-category", `findings[${index}].category must be a string`));
+      }
+      if (finding.file_path !== undefined && finding.file_path !== null && typeof finding.file_path !== "string") {
+        violations.push(violation14("high", "review.invalid-file-path", `findings[${index}].file_path must be a string or null`));
+      }
+      if (finding.line_start !== undefined && finding.line_start !== null && typeof finding.line_start !== "number") {
+        violations.push(violation14("high", "review.invalid-line-start", `findings[${index}].line_start must be a number or null`));
+      }
+      if (finding.line_end !== undefined && finding.line_end !== null && typeof finding.line_end !== "number") {
+        violations.push(violation14("high", "review.invalid-line-end", `findings[${index}].line_end must be a number or null`));
+      }
+      if (finding.fingerprint_hint !== undefined && typeof finding.fingerprint_hint !== "string") {
+        violations.push(violation14("high", "review.invalid-fingerprint-hint", `findings[${index}].fingerprint_hint must be a string`));
+      }
+    });
+  }
+  if (doc.tally !== undefined) {
+    if (!isPlainObject7(doc.tally)) {
+      violations.push(violation14("high", "review.invalid-tally", "tally must be a PrTallyResult object"));
+    } else {
+      checkProvidedTallyShape(doc.tally, violations);
+      if (doc.tally.verdict !== doc.verdict) {
+        violations.push(violation14("high", "review.verdict-tally-mismatch", `tally.verdict "${String(doc.tally.verdict)}" does not equal the top-level verdict "${String(doc.verdict)}" - the envelope verdict and tally must agree (consistency rule)`));
+      }
+    }
+  }
+  if (doc.target !== undefined) {
+    if (!isPlainObject7(doc.target)) {
+      violations.push(violation14("high", "review.invalid-target", "target must be an object"));
+    } else {
+      if (doc.target.owner !== undefined && typeof doc.target.owner !== "string") {
+        violations.push(violation14("high", "review.invalid-target", "target.owner must be a string"));
+      }
+      if (doc.target.repo !== undefined && typeof doc.target.repo !== "string") {
+        violations.push(violation14("high", "review.invalid-target", "target.repo must be a string"));
+      }
+      if (doc.target.pr !== undefined && typeof doc.target.pr !== "number") {
+        violations.push(violation14("high", "review.invalid-target", "target.pr must be a number"));
+      }
+      if (doc.target.head_sha !== undefined && typeof doc.target.head_sha !== "string") {
+        violations.push(violation14("high", "review.invalid-target", "target.head_sha must be a string"));
+      }
+    }
+  }
+  return { ok: violations.length === 0, violations };
+}
+function defaultReviewSummary(tally, findings) {
+  const lines = [
+    `## Verdict: ${tally.verdict} · ${tally.scorePct}%`,
+    "",
+    `must-fix=${tally.tally.mustFix} should-fix=${tally.tally.shouldFix} nit=${tally.tally.nit} unverified=${tally.tally.unverified}`
+  ];
+  if (findings.length > 0) {
+    lines.push("");
+    for (const finding of findings) {
+      lines.push(`- ${finding.mergeClass}: ${finding.title}`);
+    }
+  }
+  return lines.join(`
+`);
+}
+function synthesizeReview(input) {
+  const tally = computePrTally({
+    findings: input.findings,
+    unverifiedCount: input.unverifiedCount,
+    unmetAc: input.unmetAc
+  });
+  return {
+    schema: "mstar.review/v1",
+    verdict: tally.verdict,
+    summary_md: input.summary_md ?? defaultReviewSummary(tally, input.findings),
+    tally,
+    findings: input.findings,
+    ...input.target !== undefined ? { target: input.target } : {}
+  };
+}
 var SHORT_SHA_WIDTH = 7;
 var DATE_RE6 = /^\d{4}-\d{2}-\d{2}$/;
 function todayString4() {
@@ -5287,7 +5613,7 @@ function prReviewReportPath(opts) {
   const sameStem = new RegExp(`^${escaped}(?:-r([0-9]+))?\\.md$`);
   let dirents;
   try {
-    dirents = readdirSync9(opts.reportsDir, { withFileTypes: true });
+    dirents = readdirSync10(opts.reportsDir, { withFileTypes: true });
   } catch (error) {
     if (error.code === "ENOENT")
       dirents = [];
@@ -5303,7 +5629,7 @@ function prReviewReportPath(opts) {
   }
   const revision = maxRevision + 1;
   const name = revision === 1 ? `${finalStem}.md` : `${finalStem}-r${revision}.md`;
-  return join14(opts.reportsDir, name);
+  return join15(opts.reportsDir, name);
 }
 var PR_TIERS = ["quick", "default", "deep"];
 function violation14(severity, code, message, fix) {
@@ -5573,10 +5899,10 @@ function prReviewSeatPrompt(opts) {
   }
   const skillRoot = opts.skillRoot.trim();
   const worktreePath = opts.worktreePath.trim();
-  if (!isAbsolute8(skillRoot)) {
+  if (!isAbsolute9(skillRoot)) {
     throw new TypeError(`prReviewSeatPrompt: skillRoot must be an absolute path - got ${JSON.stringify(opts.skillRoot)}`);
   }
-  if (!isAbsolute8(worktreePath)) {
+  if (!isAbsolute9(worktreePath)) {
     throw new TypeError(`prReviewSeatPrompt: worktreePath must be an absolute path - got ${JSON.stringify(opts.worktreePath)}`);
   }
   const slug = `${domain}-${seat}`;
@@ -5600,14 +5926,14 @@ function prReviewSeatPrompt(opts) {
   lines.push("");
   lines.push("## Read first");
   lines.push("");
-  const prReviewRef = join14(skillRoot, "references", "pr-review.md");
+  const prReviewRef = join15(skillRoot, "references", "pr-review.md");
   const sections = opts.stage === 1 ? tier === "quick" ? "Scoping, Evidence rules" : "Review pipeline, Worktree isolation, Scoping, Evidence rules" : "Merge class, Attack and vet, Evidence rules, Sizing & change shape";
   lines.push(`1. \`${prReviewRef}\` — read at least these sections: ${sections}.`);
   lines.push(`2. The review worktree: \`${worktreePath}\` — your ONLY working directory this session; read-only (no edits, no fixes, no stash, no commits, no posts).`);
   if (opts.stage === 2) {
-    lines.push(`3. \`${join14(skillRoot, "references", "finding-format.md")}\` — the template every finding follows.`);
+    lines.push(`3. \`${join15(skillRoot, "references", "finding-format.md")}\` — the template every finding follows.`);
     if (opts.securitySeat === true) {
-      lines.push(`4. \`${join14(skillRoot, "references", "security-review.md")}\` — the security lens.`);
+      lines.push(`4. \`${join15(skillRoot, "references", "security-review.md")}\` — the security lens.`);
     }
   }
   lines.push("");
@@ -5791,6 +6117,7 @@ export {
   validateProjectRegister,
   validatePrReviewReport,
   validatePlanRow,
+  validateMstarReviewV1,
   validateIntegrationMergeLease,
   validateGitignore,
   validateFindingDoc,
@@ -5803,9 +6130,11 @@ export {
   techDebtRollup,
   taskReportExists,
   taskBrief,
+  synthesizeReview,
   supplyChainChecks,
   stripFrontmatter,
   singleReviewSnapshot,
+  setArtifactStore,
   sddWorkspace,
   scopeGuard,
   scanSecrets,
@@ -5829,6 +6158,7 @@ export {
   resolveHarnessDir,
   resolveCompassEnforcement,
   resolveAssetPath,
+  resolveArtifactPath,
   releaseLease,
   registerWorkflow,
   referenceExists,
@@ -5855,6 +6185,7 @@ export {
   parseAssignmentBranchForms,
   normalizeSeverity,
   migrateHarnessTree,
+  loadStoreModule,
   listProjectReferenceFiles,
   lintStrategySections,
   lintSkillFrontmatter,
@@ -5865,6 +6196,7 @@ export {
   l1PreDispatchCheck,
   isReadOnlyAssignmentRole,
   implementerSessionStickyRules,
+  getArtifactStore,
   findingsCleanupGate,
   findTemporaryMarkers,
   findSimplifyMarkers,
@@ -5875,6 +6207,7 @@ export {
   emitGitignoreSnippet,
   detectHost,
   detectHarnessKind,
+  createFsStore,
   computePrTally,
   compoundRefreshScope,
   composeDispatchGate,
@@ -5890,6 +6223,7 @@ export {
   assertLightDarkParity,
   assertIndexRows,
   assertIndexRowObligations,
+  assertFsStorePath,
   assertDefaultBranchProtected,
   assertControlVsFeaturePath,
   assertBranchAlignment,