@mstar-harness/cli 3.1.2 → 3.2.0

package/dist/mstar-harness.js

@@ -2414,7 +2414,7 @@ var require_picocolors2 = __commonJS((exports, module) => {
 });
 
 // src/index.ts
-import { execFileSync as execFileSync9 } from "child_process";
+import { execFileSync as execFileSync8 } from "child_process";
 import fs8 from "fs";
 import path12 from "path";
 
@@ -4069,6 +4069,8 @@ var {
 
 // ../engine/dist/engine.js
 import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { basename, dirname, join, resolve } from "node:path";
 import { readFileSync as readFileSync2, statSync } from "node:fs";
 import { dirname as dirname2, isAbsolute, join as join2, relative, resolve as resolve2 } from "node:path";
 import { existsSync as existsSync2, mkdirSync as mkdirSync2, readdirSync, readFileSync as readFileSync3, realpathSync, statSync as statSync2 } from "node:fs";
@@ -4076,7 +4078,9 @@ import { execFileSync } from "node:child_process";
 import { basename as basename2, dirname as dirname3, isAbsolute as isAbsolute2, join as join3, relative as relative2, resolve as resolve3 } from "node:path";
 import { existsSync as existsSync3, readFileSync as readFileSync4, readdirSync as readdirSync2, realpathSync as realpathSync2 } from "node:fs";
 import { dirname as dirname5, join as join6, resolve as resolve5, sep } from "node:path";
+import { 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 as AsyncLocalStorage2 } from "node:async_hooks";
 import { execFileSync as execFileSync2 } from "node:child_process";
 import { existsSync as existsSync4 } from "node:fs";
@@ -4087,11 +4091,11 @@ import { basename as basename3, dirname as dirname6, isAbsolute as isAbsolute5,
 import { existsSync as existsSync5, readdirSync as readdirSync4, readFileSync as readFileSync6 } from "node:fs";
 import { existsSync as existsSync6, readFileSync as readFileSync7, readdirSync as readdirSync5 } from "node:fs";
 import { join as join9 } from "node:path";
-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";
-import { existsSync as existsSync7, 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";
-import { existsSync as existsSync8 } from "node:fs";
+import { existsSync as existsSync7, mkdirSync as mkdirSync7, readdirSync as readdirSync7, readFileSync as readFileSync9, rmdirSync as rmdirSync2, rmSync, writeFileSync as writeFileSync5 } from "node:fs";
+import { basename as basename4, join as join11, resolve as resolve9, sep as sep3 } from "node:path";
+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 resolve10, sep as sep4 } from "node:path";
+import { existsSync as existsSync9 } from "node:fs";
 import { join as join13 } from "node:path";
 var SEVERITY_ORDER = ["critical", "high", "medium", "low", "nit"];
 function readJson(filePath) {
@@ -4106,6 +4110,21 @@ function readJson(filePath) {
     throw new Error(`Invalid JSON in ${filePath}: ${error.message}`);
   }
 }
+function writeJson(filePath, value) {
+  const parent = dirname(filePath);
+  mkdirSync(parent, { recursive: true });
+  const tmp = join(parent, `.${basename(filePath)}.${process.pid}.${randomUUID()}.tmp`);
+  try {
+    writeFileSync(tmp, `${JSON.stringify(value, null, 2)}
+`, "utf8");
+    renameSync(tmp, filePath);
+  } catch (error) {
+    try {
+      unlinkSync(tmp);
+    } catch {}
+    throw error;
+  }
+}
 var MSTARC_FILE = ".mstarc";
 var MSTARC_SECTION = "config";
 var MSTARC_HARNESS_DIR_KEY = "harness_dir";
@@ -4414,7 +4433,54 @@ function validateIntegrationMergeLease(lease) {
   }
   return { ok: violations.length === 0, violations };
 }
+var STATUS_WRITE_LOCKDIR = ".status-write.lockdir";
+var LOCKDIR_HOLDER_PID = "holder.pid";
 var heldLockDirs = new AsyncLocalStorage2;
+async function withStatusWriteLock(statusPath, fn, opts = {}) {
+  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 \u2014 withStatusWriteLock is not reentrant; a nested acquisition on the same status.json is a bug`);
+  }
+  const timeoutMs = opts.timeoutMs ?? 30000;
+  const pollMs = opts.pollMs ?? 25;
+  const deadline = Date.now() + timeoutMs;
+  let acquired = null;
+  for (;; ) {
+    try {
+      mkdirSync3(lockDir);
+      const st = statSync3(lockDir);
+      acquired = { dev: st.dev, ino: st.ino };
+      break;
+    } catch (error) {
+      if (error.code !== "EEXIST")
+        throw error;
+      if (Date.now() >= deadline) {
+        throw new Error(`${lockDir} already exists \u2014 another writer holds the status write lock; Blocked (same-host exclusive lock; status-and-residuals.md \u00a7 Same-host exclusive write lock). ` + `Recovery: remove ${lockDir} if no writer is alive (holder.pid inside names the acquiring process)`);
+      }
+      await sleep(pollMs);
+    }
+  }
+  try {
+    writeFileSync2(join4(lockDir, LOCKDIR_HOLDER_PID), String(process.pid), "utf8");
+  } catch {}
+  const owns = held ?? new Set;
+  owns.add(lockDir);
+  try {
+    return await heldLockDirs.run(owns, fn);
+  } finally {
+    owns.delete(lockDir);
+    try {
+      const current = statSync3(lockDir);
+      if (acquired !== null && current.dev === acquired.dev && current.ino === acquired.ino) {
+        try {
+          unlinkSync2(join4(lockDir, LOCKDIR_HOLDER_PID));
+        } catch {}
+        rmdirSync(lockDir);
+      }
+    } catch {}
+  }
+}
 var BRANCH_FORMS_HINT = '"Working branch: <existing>" | "Working branch: create <new> from <base>" | "Branch policy: direct on <branch> \u2014 <reason>"';
 var REQUIRED_FIELDS = [
   { key: "executeAs", label: "Execute as", code: "execute-as" },
@@ -4693,6 +4759,12 @@ function isPlainObject3(value) {
 function violation4(severity, code, message, fix) {
   return { ok: false, severity, code, message, fix };
 }
+function todayString() {
+  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 normalizeSeverity(value) {
   if (value === "warning")
     return "low";
@@ -4881,13 +4953,35 @@ function validateStatusV2(docOrPath, opts = {}) {
         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)} \u2014 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)} \u2014 the root entry mirrors the snapshot; align them`));
+        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)} \u2014 workflow ${JSON.stringify(label)} collided with another writer (e.g. a concurrent/re-run \`audit promote\` with the same workflow id rewrote the snapshot); the root entry mirrors the snapshot \u2014 align them or remove the colliding workflow`));
       }
     }
   }
   return { ok: violations.length === 0, violations };
 }
 var validateStatus = validateStatusV2;
+function registerWorkflowEntryLocked(statusPath, entry) {
+  const harnessDir = dirname5(statusPath);
+  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 \u2014 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("; ")}`);
+  }
+  writeJson(statusPath, doc);
+  return doc;
+}
 var DEFAULT_PROBE_TIMEOUT_MS = 1e4;
 function probeTimeoutMs() {
   const raw = process.env.MSTAR_GIT_PROBE_TIMEOUT_MS;
@@ -6189,6 +6283,137 @@ function scaffoldAuditPlan(outDir, findings, options = {}) {
   }));
   return { outDir: resolve9(outDir), date, files: written, nextNumber: next };
 }
+async function promoteAuditPlans(outDir, selected, options) {
+  if (selected.length === 0) {
+    throw new Error("promoteAuditPlans: at least one plan id must be selected (--plans 001,002,\u2026)");
+  }
+  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(resolve9(outDir));
+  assertSafePathComponent(workflowId, "workflow id");
+  const harnessDir = resolve9(options.harnessDir);
+  const statusPath = join11(harnessDir, "status.json");
+  const workflowDir = join11(harnessDir, "workflows", workflowId);
+  const snapshotPath = join11(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;
+    return {
+      id: stem,
+      title,
+      file: planFileRel(outDir, planFile),
+      status: "Todo"
+    };
+  });
+  const now = new Date;
+  const snapshot = {
+    schema_version: 1,
+    id: workflowId,
+    type: "plan",
+    status: "running",
+    started_at: now.toISOString(),
+    updated_at: now.toISOString().slice(0, 10),
+    plans
+  };
+  const entry = {
+    id: workflowId,
+    type: "plan",
+    started_at: snapshot.started_at,
+    dir: `workflows/${workflowId}`
+  };
+  const entryGate = validateWorkflowEntry(entry);
+  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)) {
+      throw new Error(`refusing to promote audit plans: workflow ${JSON.stringify(workflowId)} already exists ` + `(snapshot at ${snapshotPath}) \u2014 re-promote would drop its registered plan rows; ` + `remove that workflow before promoting again`);
+    }
+    mkdirSync7(workflowDir, { recursive: true });
+    try {
+      writeJson(snapshotPath, snapshot);
+      registerWorkflowEntryLocked(statusPath, entry);
+    } catch (error) {
+      rmSync(snapshotPath, { force: true });
+      try {
+        if (readdirSync7(workflowDir).length === 0) {
+          rmdirSync2(workflowDir);
+        }
+      } catch {}
+      throw error;
+    }
+    return { workflowId, snapshotPath };
+  });
+  return { workflowId, snapshotPath };
+}
+function resolveSelectedPlanFiles(outDir, selected) {
+  const files = readdirSync7(outDir).filter((f) => /^\d{3}-.*\.md$/.test(f)).sort();
+  const byNum = new Map;
+  const byStem = new Map;
+  for (const file of files) {
+    const stem = file.replace(/\.md$/, "");
+    if (!byNum.has(stem.slice(0, 3))) {
+      byNum.set(stem.slice(0, 3), file);
+    }
+    byStem.set(stem, file);
+  }
+  const resolved = [];
+  const seen = new Set;
+  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 ${resolve9(outDir)}`);
+    }
+    if (!seen.has(file)) {
+      seen.add(file);
+      resolved.push(file);
+    }
+  }
+  return resolved;
+}
+function readExecutionOrderIndex(outDir) {
+  const readmePath = join11(outDir, "README.md");
+  let text;
+  try {
+    text = readFileSync9(readmePath, "utf8");
+  } catch {
+    return new Map;
+  }
+  const rows = new Map;
+  const lines = text.split(`
+`);
+  let inSection = false;
+  for (const line of lines) {
+    if (/^##\s+Execution order & status/.test(line)) {
+      inSection = true;
+      continue;
+    }
+    if (inSection && /^#/.test(line)) {
+      break;
+    }
+    if (!inSection)
+      continue;
+    const cells = line.split(/(?<!\\)\|/).map((c) => c.trim());
+    if (cells.length >= 3 && /^\d{3}$/.test(cells[1])) {
+      rows.set(cells[1], { title: cells[2].replace(/\\\|/g, "|") });
+    }
+  }
+  return rows;
+}
+function planFileRel(outDir, planFile) {
+  const resolved = resolve9(outDir);
+  const parts = resolved.split(sep3);
+  const plansIdx = parts.lastIndexOf("plans");
+  if (plansIdx >= 0) {
+    return `${parts.slice(plansIdx + 1).join(sep3)}${sep3}${planFile}`;
+  }
+  return planFile;
+}
 function violation10(severity, code, message, fix) {
   return { ok: false, severity, code, message, fix };
 }
@@ -6444,7 +6669,7 @@ function collectKnowledgeDocs(dir) {
       if (entry.isDirectory()) {
         stack.push(full);
       } else if (entry.name.endsWith(".md") && entry.name !== "README.md" && entry.name !== "index.md") {
-        docs.push(relative4(dir, full).split(sep3).join("/"));
+        docs.push(relative4(dir, full).split(sep4).join("/"));
       }
     }
   }
@@ -6461,7 +6686,7 @@ function normalizeIndexRef(cell) {
 function assertIndexRows(knowledgeDir) {
   const violations = [];
   const readmePath = join12(knowledgeDir, "README.md");
-  if (!existsSync7(readmePath)) {
+  if (!existsSync8(readmePath)) {
     violations.push(violation10("medium", "compound.index.missing-readme", `missing ${readmePath} \u2014 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 };
   }
@@ -6485,7 +6710,7 @@ function assertIndexRows(knowledgeDir) {
   return { ok: violations.length === 0, violations };
 }
 function isFileLikeRoot(root) {
-  return /^[^.]*\.[A-Za-z0-9]{1,10}$/.test(basename4(root));
+  return /^[^.]*\.[A-Za-z0-9]{1,10}$/.test(basename5(root));
 }
 function scopeGuard(path2, allowedRoots) {
   const resolved = resolve10(path2);
@@ -6494,7 +6719,7 @@ function scopeGuard(path2, allowedRoots) {
     if (isFileLikeRoot(r)) {
       if (resolved === r)
         return { ok: true, violations: [] };
-    } else if (resolved === r || resolved.startsWith(r + sep3)) {
+    } else if (resolved === r || resolved.startsWith(r + sep4)) {
       return { ok: true, violations: [] };
     }
   }
@@ -6642,7 +6867,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(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)"));
+      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-artifacts/references/plan-quality-bar.md; templates/plan.main.md placeholder scan)"));
     }
   }
   return { ok: violations.length === 0, violations, findings };
@@ -6791,7 +7016,7 @@ function validateRoleMapping(rolesDir, options = {}) {
   const violations = [];
   const referenceById = new Map(mapping.map((m) => [m.agentId, m.reference]));
   for (const { agentId, reference } of mapping) {
-    if (!existsSync8(join13(rolesDir, reference))) {
+    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 \u00a7 Role Reference Mapping)`, `create ${join13(rolesDir, reference)} or fix the mapping row`));
     }
   }
@@ -6993,28 +7218,28 @@ function lintFiveQuestion(bodyText, mode = "authoring") {
 }
 
 // ../engine/dist/engine.js
-import { existsSync as existsSync9, mkdirSync as mkdirSync3, readFileSync as readFileSync8, renameSync as renameSync2, unlinkSync as unlinkSync2, writeFileSync as writeFileSync2 } from "node:fs";
-import { randomUUID } from "node:crypto";
-import { basename, dirname, join, resolve } from "node:path";
+import { existsSync as existsSync10, mkdirSync as mkdirSync4, readFileSync as readFileSync8, renameSync as renameSync2, unlinkSync as unlinkSync3, writeFileSync as writeFileSync4 } from "node:fs";
+import { randomUUID as randomUUID2 } from "node:crypto";
+import { basename as basename6, dirname as dirname7, join as join5, resolve as resolve8 } from "node:path";
 import { fileURLToPath } from "node:url";
-import { readFileSync as readFileSync22, statSync as statSync3 } from "node:fs";
+import { readFileSync as readFileSync22, statSync as statSync5 } from "node:fs";
 import { dirname as dirname22, isAbsolute as isAbsolute6, join as join22, relative as relative3, resolve as resolve22 } from "node:path";
 import { existsSync as existsSync22, mkdirSync as mkdirSync22, readdirSync as readdirSync6, readFileSync as readFileSync32, realpathSync as realpathSync4, statSync as statSync22 } from "node:fs";
 import { execFileSync as execFileSync4 } from "node:child_process";
 import { basename as basename22, dirname as dirname32, isAbsolute as isAbsolute22, join as join32, relative as relative22, resolve as resolve32 } from "node:path";
 import { existsSync as existsSync32, readFileSync as readFileSync42, readdirSync as readdirSync22, realpathSync as realpathSync22 } from "node:fs";
 import { dirname as dirname52, join as join62, resolve as resolve52, sep as sep2 } from "node:path";
-import { mkdirSync as mkdirSync32, rmdirSync, statSync as statSync32, unlinkSync as unlinkSync22, writeFileSync as writeFileSync22 } from "node:fs";
+import { mkdirSync as mkdirSync32, rmdirSync as rmdirSync3, statSync as statSync32, unlinkSync as unlinkSync22, writeFileSync as writeFileSync22 } from "node:fs";
 import { dirname as dirname42, isAbsolute as isAbsolute32, join as join42, resolve as resolve42 } from "node:path";
-import { setTimeout as sleep } from "node:timers/promises";
+import { setTimeout as sleep2 } from "node:timers/promises";
 import { AsyncLocalStorage as AsyncLocalStorage3 } from "node:async_hooks";
-import { mkdirSync as mkdirSync4 } from "node:fs";
-import { join as join5 } from "node:path";
-import { copyFileSync, mkdirSync as mkdirSync6, readFileSync as readFileSync82, readdirSync as readdirSync62, writeFileSync as writeFileSync4 } from "node:fs";
-import { dirname as dirname7, isAbsolute as isAbsolute62, join as join10, relative as relative32, resolve as resolve8, sep as sep22 } from "node:path";
+import { mkdirSync as mkdirSync42 } from "node:fs";
+import { join as join52 } from "node:path";
+import { copyFileSync, mkdirSync as mkdirSync6, readFileSync as readFileSync82, readdirSync as readdirSync62, writeFileSync as writeFileSync42 } from "node:fs";
+import { dirname as dirname72, isAbsolute as isAbsolute62, join as join10, relative as relative32, resolve as resolve82, sep as sep22 } from "node:path";
 var SEVERITY_ORDER2 = ["critical", "high", "medium", "low", "nit"];
 function readJson2(filePath) {
-  if (!existsSync9(filePath))
+  if (!existsSync10(filePath))
     return {};
   const content = readFileSync8(filePath, "utf8").trim();
   if (!content)
@@ -7025,28 +7250,28 @@ function readJson2(filePath) {
     throw new Error(`Invalid JSON in ${filePath}: ${error.message}`);
   }
 }
-function writeJson(filePath, value) {
-  const parent = dirname(filePath);
-  mkdirSync3(parent, { recursive: true });
-  const tmp = join(parent, `.${basename(filePath)}.${process.pid}.${randomUUID()}.tmp`);
+function writeJson2(filePath, value) {
+  const parent = dirname7(filePath);
+  mkdirSync4(parent, { recursive: true });
+  const tmp = join5(parent, `.${basename6(filePath)}.${process.pid}.${randomUUID2()}.tmp`);
   try {
-    writeFileSync2(tmp, `${JSON.stringify(value, null, 2)}
+    writeFileSync4(tmp, `${JSON.stringify(value, null, 2)}
 `, "utf8");
     renameSync2(tmp, filePath);
   } catch (error) {
     try {
-      unlinkSync2(tmp);
+      unlinkSync3(tmp);
     } catch {}
     throw error;
   }
 }
 function resolveProjectRoot(startDir = process.cwd()) {
-  const start = resolve(startDir);
+  const start = resolve8(startDir);
   let dir = start;
   for (;; ) {
-    if (existsSync9(join(dir, "package.json")) || existsSync9(join(dir, "bun.lock")))
+    if (existsSync10(join5(dir, "package.json")) || existsSync10(join5(dir, "bun.lock")))
       return dir;
-    const parent = dirname(dir);
+    const parent = dirname7(dir);
     if (parent === dir)
       return start;
     dir = parent;
@@ -7055,20 +7280,20 @@ function resolveProjectRoot(startDir = process.cwd()) {
 function findRootPackageJson(startDir) {
   let dir = startDir;
   for (;; ) {
-    const candidate = resolve(dir, "package.json");
+    const candidate = resolve8(dir, "package.json");
     try {
       const pkg = JSON.parse(readFileSync8(candidate, "utf8"));
       if (pkg.name === "morning-star")
         return candidate;
     } catch {}
-    const parent = dirname(dir);
+    const parent = dirname7(dir);
     if (parent === dir)
       return null;
     dir = parent;
   }
 }
 function harnessVersionFrom(moduleDir) {
-  const ownManifest = join(moduleDir, "..", "package.json");
+  const ownManifest = join5(moduleDir, "..", "package.json");
   try {
     const pkg = JSON.parse(readFileSync8(ownManifest, "utf8"));
     if (typeof pkg.version === "string" && pkg.version !== "")
@@ -7085,7 +7310,7 @@ function harnessVersionFrom(moduleDir) {
   }
 }
 function readHarnessVersion() {
-  return harnessVersionFrom(dirname(fileURLToPath(import.meta.url)));
+  return harnessVersionFrom(dirname7(fileURLToPath(import.meta.url)));
 }
 var MSTARC_FILE2 = ".mstarc";
 var MSTARC_SECTION2 = "config";
@@ -7140,7 +7365,7 @@ function parseMstarc2(text) {
 }
 function isFile3(file) {
   try {
-    return statSync3(file).isFile();
+    return statSync5(file).isFile();
   } catch {
     return false;
   }
@@ -7374,11 +7599,11 @@ function verifyPlanExecutionLease(row, planId) {
   violations.push(...validateExecutionLease2(lease).violations);
   return { ok: violations.length === 0, violations, lease };
 }
-var STATUS_WRITE_LOCKDIR = ".status-write.lockdir";
-var LOCKDIR_HOLDER_PID = "holder.pid";
+var STATUS_WRITE_LOCKDIR2 = ".status-write.lockdir";
+var LOCKDIR_HOLDER_PID2 = "holder.pid";
 var heldLockDirs2 = new AsyncLocalStorage3;
-async function withStatusWriteLock(statusPath, fn, opts = {}) {
-  const lockDir = join42(dirname42(resolve42(statusPath)), STATUS_WRITE_LOCKDIR);
+async function withStatusWriteLock2(statusPath, fn, opts = {}) {
+  const lockDir = join42(dirname42(resolve42(statusPath)), STATUS_WRITE_LOCKDIR2);
   const held = heldLockDirs2.getStore();
   if (held !== undefined && held.has(lockDir)) {
     throw new Error(`${lockDir} is already held by this process in this async context \u2014 withStatusWriteLock is not reentrant; a nested acquisition on the same status.json is a bug`);
@@ -7399,11 +7624,11 @@ async function withStatusWriteLock(statusPath, fn, opts = {}) {
       if (Date.now() >= deadline) {
         throw new Error(`${lockDir} already exists \u2014 another writer holds the status write lock; Blocked (same-host exclusive lock; status-and-residuals.md \u00a7 Same-host exclusive write lock). ` + `Recovery: remove ${lockDir} if no writer is alive (holder.pid inside names the acquiring process)`);
       }
-      await sleep(pollMs);
+      await sleep2(pollMs);
     }
   }
   try {
-    writeFileSync22(join42(lockDir, LOCKDIR_HOLDER_PID), String(process.pid), "utf8");
+    writeFileSync22(join42(lockDir, LOCKDIR_HOLDER_PID2), String(process.pid), "utf8");
   } catch {}
   const owns = held ?? new Set;
   owns.add(lockDir);
@@ -7415,9 +7640,9 @@ async function withStatusWriteLock(statusPath, fn, opts = {}) {
       const current = statSync32(lockDir);
       if (acquired !== null && current.dev === acquired.dev && current.ino === acquired.ino) {
         try {
-          unlinkSync22(join42(lockDir, LOCKDIR_HOLDER_PID));
+          unlinkSync22(join42(lockDir, LOCKDIR_HOLDER_PID2));
         } catch {}
-        rmdirSync(lockDir);
+        rmdirSync3(lockDir);
       }
     } catch {}
   }
@@ -7538,10 +7763,10 @@ async function writeWorkflowSnapshot(snapshot, dir) {
     const detail = gate2.violations.map((v) => v.message).join("; ");
     throw new Error(`refusing to write invalid workflow snapshot: ${detail}`);
   }
-  const snapshotPath = join5(dir, WORKFLOW_SNAPSHOT_FILE2);
-  mkdirSync4(dir, { recursive: true });
-  await withStatusWriteLock(snapshotPath, () => {
-    writeJson(snapshotPath, snapshot);
+  const snapshotPath = join52(dir, WORKFLOW_SNAPSHOT_FILE2);
+  mkdirSync42(dir, { recursive: true });
+  await withStatusWriteLock2(snapshotPath, () => {
+    writeJson2(snapshotPath, snapshot);
   });
 }
 var DATE_RE3 = /^\d{4}-\d{2}-\d{2}$/;
@@ -7788,7 +8013,7 @@ function validateStatusV22(docOrPath, opts = {}) {
         violations.push(violation42("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)} \u2014 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(violation42("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)} \u2014 the root entry mirrors the snapshot; align them`));
+        violations.push(violation42("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)} \u2014 workflow ${JSON.stringify(label)} collided with another writer (e.g. a concurrent/re-run \`audit promote\` with the same workflow id rewrote the snapshot); the root entry mirrors the snapshot \u2014 align them or remove the colliding workflow`));
       }
     }
   }
@@ -8220,7 +8445,7 @@ function collectNotesFiles(snapshots) {
     if (lines.length === 0)
       continue;
     out.push({
-      file: join10(dirname7(snapshot.file), NOTES_LEDGER_FILE),
+      file: join10(dirname72(snapshot.file), NOTES_LEDGER_FILE),
       source,
       lines
     });
@@ -8228,7 +8453,7 @@ function collectNotesFiles(snapshots) {
   return out;
 }
 function migrateHarnessTree(root, opts = {}) {
-  const harnessDir = resolve8(root);
+  const harnessDir = resolve82(root);
   const workflowDir = resolveWorkflowDir2(harnessDir, { harnessDir });
   const projectDir = resolveProjectDir2(harnessDir, { harnessDir });
   const projectId = opts.projectId ?? _DEFAULT_PROJECT2;
@@ -8382,9 +8607,9 @@ async function applyMigratePlan(plan) {
   if (current.version === 2) {
     return { applied: false, message: "no-op: status.json already at schema version 2 (migrated) \u2014 nothing to do" };
   }
-  const harnessRoot = resolve8(plan.root);
-  const workflowRoot = resolve8(plan.workflowDir);
-  const projectRoot = resolve8(plan.projectDir);
+  const harnessRoot = resolve82(plan.root);
+  const workflowRoot = resolve82(plan.workflowDir);
+  const projectRoot = resolve82(plan.projectDir);
   if (!isAbsolute62(plan.workflowDir) || !isAbsolute62(plan.projectDir)) {
     throw new Error(`refusing to apply migration: plan workflowDir/projectDir must be absolute (got ${JSON.stringify(plan.workflowDir)} / ${JSON.stringify(plan.projectDir)})`);
   }
@@ -8398,44 +8623,46 @@ async function applyMigratePlan(plan) {
     ...plan.roadmap !== null ? [plan.roadmap.file] : []
   ];
   for (const destination of allDestinations) {
-    const resolvedDest = resolve8(join10(plan.root, destination));
+    const resolvedDest = resolve82(join10(plan.root, destination));
     const inside = (dir) => resolvedDest === dir || resolvedDest.startsWith(`${dir}${sep22}`);
     if (!inside(harnessRoot) && !inside(workflowRoot) && !inside(projectRoot)) {
       throw new Error(`refusing to apply migration: destination escapes the harness dir (${JSON.stringify(destination)}) \u2014 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 });
+  mkdirSync6(join10(plan.root, dirname72(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)));
+    await writeWorkflowSnapshot(snapshot.data, dirname72(workflowTargetOf(snapshot.file)));
   }
   for (const notes of plan.notesFiles) {
     const filePath = workflowTargetOf(notes.file);
-    mkdirSync6(dirname7(filePath), { recursive: true });
+    mkdirSync6(dirname72(filePath), { recursive: true });
     const content = notes.lines.length > 0 ? `${notes.lines.join(`
 `)}
 ` : "";
-    writeFileSync4(filePath, content, "utf8");
+    writeFileSync42(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 (Object.keys(plan.register.data.entries ?? {}).length > 0) {
+      const filePath = projectTargetOf(plan.register.file);
+      mkdirSync6(dirname72(filePath), { recursive: true });
+      writeJson2(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");
+    mkdirSync6(dirname72(filePath), { recursive: true });
+    writeFileSync42(filePath, plan.roadmap.content, "utf8");
   }
   const rootGate = validateStatusV22(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, () => {
+  return withStatusWriteLock2(statusPath, () => {
     const latest = readJson2(statusPath);
     if (latest.version === 2) {
       return {
@@ -8443,7 +8670,7 @@ async function applyMigratePlan(plan) {
         message: "no-op: status.json already at schema version 2 (migrated) \u2014 nothing to do"
       };
     }
-    writeJson(statusPath, plan.rootV2.data);
+    writeJson2(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})`
@@ -9028,7 +9255,22 @@ import path5 from "node:path";
 import fs2 from "node:fs";
 import os from "node:os";
 import path4 from "node:path";
+
+// src/exec.ts
 import { execFileSync as execFileSync6 } from "node:child_process";
+function runCliCommand(command, opts = {}) {
+  if (opts.dryRun)
+    return "";
+  return execFileSync6(command[0], command.slice(1), {
+    cwd: opts.cwd,
+    encoding: "utf8",
+    env: opts.env,
+    stdio: "pipe",
+    timeout: opts.timeoutMs
+  });
+}
+
+// src/adapters/shared-install.ts
 var REPO_URL = "https://github.com/btspoony/mstar-harness.git";
 var PLUGIN_NAME = "morning-star-harness";
 var HARNESS_REPO_PATH = path4.join(os.homedir(), ".mstar", "harness");
@@ -9060,9 +9302,7 @@ function ensureDir(dirPath, dryRun) {
     fs2.mkdirSync(dirPath, { recursive: true });
 }
 function runCommand(command, cwd, dryRun) {
-  if (dryRun)
-    return;
-  execFileSync6(command[0], command.slice(1), { cwd, stdio: "pipe", encoding: "utf8" });
+  runCliCommand(command, { cwd, dryRun });
 }
 function ensureLocalHarnessRepo(dryRun) {
   const notes = [];
@@ -9250,9 +9490,10 @@ var CODEX_PROJECT_COMMAND_NAMES = [
   "iteration-start",
   "iteration-drive",
   "iteration-loop",
-  "codebase-audit"
+  "codebase-audit",
+  "pr-deep-review"
 ];
-var GLOBAL_ITERATION_SKILLS_WARNING = "Codex project-scoped commands (iteration-start / iteration-drive / iteration-loop / codebase-audit) are installed as project-local skills under .agents/skills/ only. Global install skips them to avoid polluting other code agents. Re-run with --scope project to enable.";
+var GLOBAL_ITERATION_SKILLS_WARNING = "Codex project-scoped commands (iteration-start / iteration-drive / iteration-loop / codebase-audit / pr-deep-review) are installed as project-local skills under .agents/skills/ only. Global install skips them to avoid polluting other code agents. Re-run with --scope project to enable.";
 function globalMarketplacePath() {
   return GLOBAL_MARKETPLACE_PATH;
 }
@@ -9375,7 +9616,7 @@ function ensureIterationSkillLinks(dryRun) {
   }
   const gitignoreEntries = CODEX_PROJECT_COMMAND_NAMES.map(iterationSkillGitignoreEntry);
   notes.push(...appendGitignore(projectRoot, gitignoreEntries, dryRun));
-  notes.push("Installed Codex project-scoped command skills under .agents/skills/ (iteration-start, iteration-drive, iteration-loop, codebase-audit) \u2014 symlinked to harness commands/*.md.");
+  notes.push("Installed Codex project-scoped command skills under .agents/skills/ (iteration-start, iteration-drive, iteration-loop, codebase-audit, pr-deep-review) \u2014 symlinked to harness commands/*.md.");
   return notes;
 }
 function validateIterationSkillLinks() {
@@ -9411,7 +9652,7 @@ function runInit(scope, dryRun) {
   }
   notes.push(...ensureAgentLinks(scope, dryRun));
   if (!dryRun)
-    writeJson(pathToMarketplace, next);
+    writeJson2(pathToMarketplace, next);
   notes.push(existingEntry ? `Updated ${PLUGIN_NAME} local marketplace entry.` : `Added ${PLUGIN_NAME} local marketplace entry.`);
   notes.push(`Source path: ${mstarEntry(scope).source.path}`);
   notes.push(`Install after init: codex plugin add ${PLUGIN_NAME} --marketplace ${MARKETPLACE_NAME}`);
@@ -9547,7 +9788,6 @@ var cursorAdapter = {
 };
 
 // src/adapters/dsh.ts
-import { execFileSync as execFileSync7 } from "node:child_process";
 import os4 from "node:os";
 import path7 from "node:path";
 var DSH_BIN = "dsh";
@@ -9571,14 +9811,7 @@ var DSH_PLUGIN_SPECS = ["@mstar-harness/dsh", "dsh-llm-fallbacks"];
 var DSH_FALLBACKS_SPEC = DSH_PLUGIN_SPECS[1];
 var DSH_INSTALL_HINT = "Install the DeepSeek Harness CLI (@deepseek-ai/dsh), e.g. `pnpm add -g @deepseek-ai/dsh` or `npm install -g @deepseek-ai/dsh`, then re-run init.";
 function runDsh(args, dryRun, timeoutMs) {
-  if (dryRun)
-    return "";
-  return execFileSync7(DSH_BIN, args, {
-    stdio: "pipe",
-    encoding: "utf8",
-    env: process.env,
-    timeout: timeoutMs
-  });
+  return runCliCommand([DSH_BIN, ...args], { dryRun, timeoutMs, env: process.env });
 }
 function dshAvailable() {
   try {
@@ -9717,7 +9950,7 @@ var dshAdapter = {
 // src/adapters/omp.ts
 import fs5 from "node:fs";
 import path8 from "node:path";
-import { execFileSync as execFileSync8 } from "node:child_process";
+import { execFileSync as execFileSync7 } from "node:child_process";
 var OMP_PLUGIN_MARKER = ".omp-plugin/plugin.json";
 var CLAUDE_PLUGIN_MARKER = ".claude-plugin/plugin.json";
 var PACKAGE_NAMES = new Set(["morning-star", PLUGIN_NAME, "github:btspoony/mstar-harness"]);
@@ -9725,20 +9958,18 @@ var SKILL_SMOKE = ["mstar-host", "mstar-harness-core", "pm"];
 var COMMAND_SMOKE = ["iteration-start", "iteration-drive", "iteration-loop", "codebase-audit"];
 function ompAvailable() {
   try {
-    execFileSync8("omp", ["--version"], { stdio: "pipe", encoding: "utf8" });
+    execFileSync7("omp", ["--version"], { stdio: "pipe", encoding: "utf8" });
     return true;
   } catch {
     return false;
   }
 }
 function runOmp(args, dryRun) {
-  if (dryRun)
-    return;
-  execFileSync8("omp", args, { stdio: "pipe", encoding: "utf8" });
+  runCliCommand(["omp", ...args], { dryRun });
 }
 function listInstalledPlugins() {
   try {
-    const raw = execFileSync8("omp", ["plugin", "list", "--json"], {
+    const raw = execFileSync7("omp", ["plugin", "list", "--json"], {
       stdio: "pipe",
       encoding: "utf8"
     });
@@ -9814,7 +10045,7 @@ function runInit3(scope, dryRun) {
       notes.push(`Would update local harness repo: git -C ${HARNESS_REPO_PATH} pull --ff-only`);
     } else {
       try {
-        execFileSync8("git", ["-C", HARNESS_REPO_PATH, "pull", "--ff-only"], {
+        execFileSync7("git", ["-C", HARNESS_REPO_PATH, "pull", "--ff-only"], {
           stdio: "pipe",
           encoding: "utf8"
         });
@@ -10175,13 +10406,13 @@ function runInit4(scope, dryRun) {
   if (!dryRun) {
     if (!fs6.existsSync(MARKETPLACE_DIR))
       fs6.mkdirSync(MARKETPLACE_DIR, { recursive: true });
-    writeJson(MARKETPLACE_JSON_PATH, buildMarketplaceJson());
+    writeJson2(MARKETPLACE_JSON_PATH, buildMarketplaceJson());
   }
   notes.push(`Wrote ZCode marketplace: ${MARKETPLACE_JSON_PATH}`);
   const knownRaw = readJson2(KNOWN_MARKETPLACES_PATH);
   const knownNext = upsertKnownMarketplace(knownRaw);
   if (!dryRun)
-    writeJson(KNOWN_MARKETPLACES_PATH, knownNext);
+    writeJson2(KNOWN_MARKETPLACES_PATH, knownNext);
   notes.push(`Registered ${MARKETPLACE_ID} marketplace in ${KNOWN_MARKETPLACES_PATH}`);
   notes.push(`Then in ZCode: Settings \u2192 Plugin Management \u2192 Discover \u2192 install ${PLUGIN_NAME} from the ${MARKETPLACE_ID} marketplace.`);
   return {
@@ -10364,7 +10595,7 @@ async function runInit5(options) {
 - `)}`);
   }
   if (!options.dryRun) {
-    writeJson(configPath, updated);
+    writeJson2(configPath, updated);
     const persistedErrors = adapter.validateConfig?.(readJson2(configPath)) || [];
     if (persistedErrors.length) {
       throw new Error(`Post-write verification failed:
@@ -11219,7 +11450,7 @@ function resolveAuditShortSha(cwd, override) {
   if (override !== undefined && override !== "")
     return override;
   try {
-    const out = execFileSync9("git", ["rev-parse", "--short", "HEAD"], {
+    const out = execFileSync8("git", ["rev-parse", "--short", "HEAD"], {
       cwd,
       encoding: "utf8",
       stdio: ["ignore", "pipe", "ignore"]
@@ -11255,6 +11486,30 @@ auditCommand.command("scaffold").description("Scaffold an audit-<date>/ plan dir
     failScript(error, "audit scaffold");
   }
 });
+auditCommand.command("promote").description("Promote selected audit plans into the v2 workflow lifecycle: write the workflow snapshot " + "(type plan, Todo rows) then register the workflow in {HARNESS_DIR}/status.json " + "(exit 2 on usage, 1 when the harness dir cannot be resolved)").argument("[audit-dir]", "audit-<date>/ directory under {PLAN_DIR}").option("--plans <ids>", "Comma-separated selected plan ids (README Plan column `001`, stem, or basename)").option("--workflow <id>", "Workflow id (default: audit-<date> basename)").option("--harness <dir>", "Harness dir containing status.json (default: resolveHarnessDir() / MSTAR_HARNESS_DIR)").action(async (auditDir, options) => {
+  try {
+    if (!auditDir) {
+      throw new SddScriptError("usage: audit promote <audit-dir> --plans <ids> [--workflow <id>] [--harness <dir>]", 2);
+    }
+    const selected = parseCsv(options.plans);
+    if (!selected || selected.length === 0) {
+      throw new SddScriptError("usage: audit promote <audit-dir> --plans <ids> [--workflow <id>] [--harness <dir>]", 2);
+    }
+    const outDir = resolveCliPath(auditDir);
+    if (!fs8.existsSync(outDir)) {
+      throw new Error(`audit dir not found: ${outDir}`);
+    }
+    const harnessDir = resolveLeaseHarnessDir(options.harness);
+    const result = await promoteAuditPlans(outDir, selected, {
+      harnessDir,
+      ...options.workflow !== undefined ? { workflowId: options.workflow } : {}
+    });
+    console.log(import_picocolors2.default.green(`audit promote: OK \u2014 workflow ${result.workflowId} registered`));
+    console.log(`  snapshot: ${result.snapshotPath}`);
+  } catch (error) {
+    failScript(error, "audit promote");
+  }
+});
 var compoundCommand = program2.command("compound").description("knowledge-doc schema / index / scope checks (engine-backed)");
 compoundCommand.command("validate").description("Validate a knowledge doc frontmatter (schema.yaml contract); with --knowledge-dir, also assert the " + "knowledge README index rows and guard the doc inside the knowledge scope (exit 1 on violations, 2 on usage)").argument("[doc-path]", "Knowledge doc (markdown with YAML frontmatter)").option("--knowledge-dir <dir>", "Knowledge directory (enables index-row asserts + scope guard)").action((docPath, options) => {
   try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mstar-harness/cli",
-  "version": "3.1.2",
+  "version": "3.2.0",
   "description": "Morning Star harness CLI — installer bootstrap + mstar workflow verbs (path/status/lease/sdd/iteration/dispatch/worktree/lint/design-md/audit/compound/host/skill).",
   "license": "MIT",
   "repository": {