@mstar-harness/engine 3.1.1 → 3.1.3

package/dist/core.d.ts

@@ -83,7 +83,7 @@ export declare function readJson(filePath: string): Record<string, unknown>;
  * stored state; revisit if the harness moves to a filesystem without
  * rename-atomicity guarantees.
  */
-export declare function writeJson(filePath: string, value: Record<string, unknown>): void;
+export declare function writeJson<T>(filePath: string, value: T): void;
 /**
  * Resolve the project root by walking up from `startDir` (default: cwd) to
  * the nearest ancestor containing `package.json` or `bun.lock`. Falls back

package/dist/dispatch.d.ts

@@ -173,8 +173,10 @@ export declare function assertTriIdentity(reviewerRoles: readonly string[]): Gat
 export type ComposeDispatchGateOptions = {
     /**
      * Host role-binding field (omp task entry `agent` / opencode `subagent` /
-     * cursor `subagent_type`); the anti-recursion precheck runs only when
-     * non-empty.
+     * cursor `subagent_type` / dsh `dispatchBinding`). The anti-recursion
+     * precheck runs for EVERY Assignment-shaped text: an empty or omitted
+     * binding fails closed (`dispatch.anti-recursion.empty-binding`) — the
+     * host cannot prove the dispatching agent is not recursing.
      */
     agent?: string;
     /**
@@ -204,7 +206,10 @@ export type ComposeDispatchGateResult = GateResult & {
  *    Assignment-shaped passes silently (`shaped: false`).
  * 2. `validateAssignmentFields` with `writable: false` when `opts.writable
  *    === false` (read-only roles), else the writable default.
- * 3. Anti-recursion precheck when `opts.agent` is non-empty.
+ * 3. Anti-recursion precheck — runs for every Assignment-shaped text; an
+ *    empty/omitted host binding fails closed (`dispatch.anti-recursion.
+ *    empty-binding`), a binding equal to `Execute as` is the existing
+ *    `dispatch.anti-recursion.self-type` critical.
  * 4. Default-branch gate for writable text: the branch comes from the
  *    Assignment's own branch forms (create-form name / Working branch /
  *    Branch policy branch), else `$MSTAR_WORKING_BRANCH`; a well-formed
@@ -221,7 +226,11 @@ export declare function composeDispatchGate(text: string, opts?: ComposeDispatch
  * Anti-recursion precheck (NEVER red line, mstar-dispatch-gates § 承接方反递归
  * 红线): a leaf executor MUST NOT invoke a Task/subagent whose role-binding
  * field (`subagent_type` / `agent` / `subagent`) equals its own `Execute as`.
- * Comparison is case-insensitive after trim; an empty binding is not a
- * self-recursion (its presence is the field gate's job, not this precheck).
+ * Comparison is case-insensitive after trim. An EMPTY binding fails closed
+ * (`dispatch.anti-recursion.empty-binding`, critical): the host cannot
+ * report which agent is calling, so anti-recursion cannot be proven — the
+ * dispatch must not proceed as if the NEVER red line held. An empty
+ * `executeAs` with a set binding stays ok (field presence is
+ * `validateAssignmentFields`' job, not this precheck).
  */
 export declare function antiRecursionPrecheck(subagentType: string, executeAs: string): GateResult;

package/dist/engine.js

@@ -170,7 +170,7 @@ function isAtOrBelow(dir, root) {
   return rel === "" || !rel.startsWith("..") && !isAbsolute(rel);
 }
 // src/path.ts
-import { mkdirSync as mkdirSync2, readdirSync, readFileSync as readFileSync3, statSync as statSync2 } from "node:fs";
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, readdirSync, readFileSync as readFileSync3, realpathSync, statSync as statSync2 } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { basename as basename2, dirname as dirname3, isAbsolute as isAbsolute2, join as join3, relative as relative2, resolve as resolve3 } from "node:path";
 function resolveHarnessDir(startDir = process.cwd(), opts = {}) {
@@ -425,6 +425,23 @@ function assertPlanWritingPath(planPath, harnessDir) {
       fix: `write the plan under ${planDir}`
     };
   }
+  if (existsSync2(planAbs)) {
+    try {
+      const canonicalPlan = realpathSync(planAbs);
+      const canonicalPlanDir = existsSync2(planDir) ? realpathSync(planDir) : resolve3(planDir);
+      const canonicalRel = relative2(canonicalPlanDir, canonicalPlan);
+      const canonicalInside = canonicalRel === "" || !canonicalRel.startsWith("..") && !isAbsolute2(canonicalRel);
+      if (!canonicalInside) {
+        return {
+          ok: false,
+          severity: "high",
+          code: "plan-path.symlink-escape",
+          message: `plan file ${planAbs} resolves to ${canonicalPlan}, outside {PLAN_DIR} (${canonicalPlanDir})`,
+          fix: `write the plan under ${planDir}`
+        };
+      }
+    } catch {}
+  }
   return {
     ok: true,
     severity: "low",
@@ -455,7 +472,7 @@ function hasFiles(dir) {
   }
 }
 // src/status.ts
-import { existsSync as existsSync2, readFileSync as readFileSync4, readdirSync as readdirSync2, realpathSync } from "node:fs";
+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";
 
 // src/lease.ts
@@ -910,10 +927,8 @@ function composeDispatchGate(text, opts = {}) {
     const violations = [];
     const writable = opts.writable !== false;
     violations.push(...validateAssignmentFields(text, { writable }).violations);
-    const agent = (opts.agent ?? "").trim();
-    if (agent !== "") {
-      violations.push(...antiRecursionPrecheck(agent, parseAssignmentFields(text).executeAs ?? "").violations);
-    }
+    const agent = opts.agent ?? "";
+    violations.push(...antiRecursionPrecheck(agent, parseAssignmentFields(text).executeAs ?? "").violations);
     if (writable) {
       const forms = parseAssignmentBranchForms(text);
       const branch = forms.createForm?.name ?? forms.workingBranch ?? forms.directOn?.branch ?? process.env.MSTAR_WORKING_BRANCH;
@@ -932,7 +947,15 @@ function composeDispatchGate(text, opts = {}) {
 function antiRecursionPrecheck(subagentType, executeAs) {
   const binding = subagentType.trim().toLowerCase();
   const role = executeAs.trim().toLowerCase();
-  if (binding !== "" && binding === role) {
+  if (binding === "") {
+    return {
+      ok: false,
+      violations: [
+        violation2("critical", "dispatch.anti-recursion.empty-binding", `empty host role binding — the host cannot report which agent is calling, so anti-recursion cannot be proven (a dispatch could silently recurse)`, "set the host role-binding field (omp task entry `agent` / opencode `subagent` / cursor `subagent_type` / dsh `dispatchBinding`) before dispatching")
+      ]
+    };
+  }
+  if (binding === role) {
     return {
       ok: false,
       violations: [
@@ -1294,7 +1317,7 @@ function validateStatusV2(docOrPath, opts = {}) {
   if (harnessDir !== undefined && Array.isArray(doc.workflows)) {
     let realHarnessDir = null;
     try {
-      realHarnessDir = realpathSync(harnessDir);
+      realHarnessDir = realpathSync2(harnessDir);
     } catch {}
     for (const entry of doc.workflows) {
       if (!isPlainObject3(entry) || typeof entry.dir !== "string")
@@ -1304,7 +1327,7 @@ function validateStatusV2(docOrPath, opts = {}) {
       const label = typeof entry.id === "string" ? entry.id : relSnapshot;
       let physical;
       try {
-        physical = realpathSync(snapshotPath);
+        physical = realpathSync2(snapshotPath);
       } catch {
         violations.push(violation4("high", "status.workflow.snapshot-missing", `workflows[] lists ${JSON.stringify(label)} but its snapshot does not exist at ${JSON.stringify(relSnapshot)} — the root holds active lifecycles only; unregister the id when its snapshot is removed`));
         continue;
@@ -1327,41 +1350,42 @@ 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)} — the root entry mirrors the snapshot; align them`));
       }
       if (typeof entry.started_at === "string" && typeof snapshot.started_at === "string" && entry.started_at !== snapshot.started_at) {
-        violations.push(violation4("medium", "status.workflow.mismatched-started-at", `workflows[] entry ${JSON.stringify(label)} started_at ${JSON.stringify(entry.started_at)} does not match its snapshot started_at ${JSON.stringify(snapshot.started_at)} — the root entry mirrors the snapshot; align them`));
+        violations.push(violation4("medium", "status.workflow.mismatched-started-at", `workflows[] entry ${JSON.stringify(label)} started_at ${JSON.stringify(entry.started_at)} does not match its snapshot started_at ${JSON.stringify(snapshot.started_at)} — workflow ${JSON.stringify(label)} collided with another writer (e.g. a concurrent/re-run \`audit promote\` with the same workflow id rewrote the snapshot); the root entry mirrors the snapshot — align them or remove the colliding workflow`));
       }
     }
   }
   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 — 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;
+}
 async function registerWorkflow(root, entry) {
   const entryGate = validateWorkflowEntry(entry);
   if (!entryGate.ok) {
     throw new Error(`refusing to register invalid workflow entry: ${entryGate.violations.map((v) => v.message).join("; ")}`);
   }
   const statusPath = resolve5(root);
-  const harnessDir = dirname5(statusPath);
-  return withStatusWriteLock(statusPath, () => {
-    const current = readJson(statusPath);
-    const fresh = Object.keys(current).length === 0;
-    const doc = fresh ? { version: 2, updated_at: todayString(), workflows: [] } : current;
-    if (!fresh && !Array.isArray(doc.workflows)) {
-      throw new Error("refusing to modify status.json: workflows must be an array — a v1 root must be migrated first (run `mstar migrate`)");
-    }
-    const existing = doc.workflows.findIndex((wf) => wf.id === entry.id);
-    if (existing >= 0) {
-      doc.workflows[existing] = entry;
-    } else {
-      doc.workflows.push(entry);
-    }
-    doc.updated_at = todayString();
-    const gate = validateStatusV2(doc, { harnessDir });
-    if (!gate.ok) {
-      throw new Error(`refusing to write invalid status.json: ${gate.violations.map((v) => v.message).join("; ")}`);
-    }
-    writeJson(statusPath, doc);
-    return doc;
-  });
+  return withStatusWriteLock(statusPath, () => registerWorkflowEntryLocked(statusPath, entry));
 }
 async function unregisterWorkflow(root, id) {
   if (typeof id !== "string" || id.trim() === "") {
@@ -1394,7 +1418,7 @@ async function unregisterWorkflow(root, id) {
 }
 function resolveCompassEnforcement(harnessDir) {
   const iterationsDir = resolveIterationDir(harnessDir);
-  if (!existsSync2(iterationsDir))
+  if (!existsSync3(iterationsDir))
     return { hard: false, source: "none" };
   let entries;
   try {
@@ -1406,7 +1430,7 @@ function resolveCompassEnforcement(harnessDir) {
     if (!entry.isDirectory())
       continue;
     const compassPath = join6(iterationsDir, entry.name, "delivery-compass.md");
-    if (!existsSync2(compassPath))
+    if (!existsSync3(compassPath))
       continue;
     let content;
     try {
@@ -1442,7 +1466,7 @@ function resolveRepoEnforcement(harnessDir) {
 }
 // src/worktree.ts
 import { execFileSync as execFileSync2 } from "node:child_process";
-import { existsSync as existsSync3 } from "node:fs";
+import { existsSync as existsSync4 } from "node:fs";
 import { isAbsolute as isAbsolute4, resolve as resolve6 } from "node:path";
 var DEFAULT_PROBE_TIMEOUT_MS = 1e4;
 function probeTimeoutMs() {
@@ -1497,7 +1521,7 @@ function l1PreDispatchCheck(input, opts = {}) {
   if (controlWorktreePath !== "" && leaseWorktreePath !== "" && resolve6(controlWorktreePath) === resolve6(leaseWorktreePath)) {
     violations.push(violation5("critical", "worktree.l1.lease-equals-control", `execution_lease.worktree_path "${leaseWorktreePath}" equals metadata.control_worktree_path — the feature worktree MUST differ from the control worktree (L1 isolation; product edits never land in the control checkout)`, "use a distinct feature worktree for the plan (git worktree add <path> <branch>) and update the lease"));
   }
-  if (leaseWorktreePath !== "" && !existsSync3(leaseWorktreePath)) {
+  if (leaseWorktreePath !== "" && !existsSync4(leaseWorktreePath)) {
     violations.push(violation5("high", "worktree.l1.feature-missing", `feature worktree directory "${leaseWorktreePath}" does not exist for plan "${planId}"`, `create it before dispatch: git worktree add ${leaseWorktreePath} <working-branch>`));
   } else if (leaseWorktreePath !== "" && leaseWorkingBranch !== "") {
     const probe = probeBranch(leaseWorktreePath, opts);
@@ -1531,7 +1555,7 @@ function l2PreDispatchCheck(input, opts = {}) {
       return;
     }
     seenPaths.add(normalized);
-    if (!existsSync3(track.worktreePath)) {
+    if (!existsSync4(track.worktreePath)) {
       violations.push(violation5("high", "worktree.l2.track-missing", `track worktree directory "${track.worktreePath}" does not exist`, `create it before dispatch: git worktree add ${track.worktreePath} ${track.workingBranch}`));
       return;
     }
@@ -1594,7 +1618,7 @@ function singleReviewSnapshot(assignments) {
 }
 // src/sdd.ts
 import { execFileSync as execFileSync3 } from "node:child_process";
-import { mkdirSync as mkdirSync5, readdirSync as readdirSync3, readFileSync as readFileSync5, realpathSync as realpathSync2, statSync as statSync4, writeFileSync as writeFileSync3 } from "node:fs";
+import { mkdirSync as mkdirSync5, readdirSync as readdirSync3, readFileSync as readFileSync5, realpathSync as realpathSync3, statSync as statSync4, writeFileSync as writeFileSync3 } from "node:fs";
 import { basename as basename3, dirname as dirname6, isAbsolute as isAbsolute5, join as join7, resolve as resolve7 } from "node:path";
 class SddScriptError extends Error {
   exitCode;
@@ -1671,8 +1695,8 @@ function isLinkedWorktree(root) {
   if (gitDir.includes("/.git/worktrees/") || gitDir.includes("/worktrees/"))
     return true;
   try {
-    const gdParent = realpathSync2(dirname6(gitDir));
-    const cmAbs = realpathSync2(common);
+    const gdParent = realpathSync3(dirname6(gitDir));
+    const cmAbs = realpathSync3(common);
     return join7(gdParent, basename3(gitDir)) !== cmAbs && gitDir !== cmAbs;
   } catch {
     return false;
@@ -1690,10 +1714,10 @@ function sddWorkspace(planId, opts = {}) {
     if (!isDirectory2(controlRoot)) {
       throw new SddScriptError(`mstar sdd workspace: CONTROL_ROOT / MSTAR_CONTROL_ROOT is not a directory: ${controlRoot}`, 1);
     }
-    root = realpathSync2(controlRoot);
+    root = realpathSync3(controlRoot);
   } else {
     const topLevel = gitOut(cwd, ["rev-parse", "--show-toplevel"]);
-    root = realpathSync2(topLevel ?? cwd);
+    root = realpathSync3(topLevel ?? cwd);
   }
   if (!controlRoot && isLinkedWorktree(root)) {
     throw new SddScriptError(`mstar sdd workspace: linked worktree at ${root} has no {HARNESS_DIR}/status.json (default gitignore).
@@ -1727,7 +1751,7 @@ function sddWorkspace(planId, opts = {}) {
   mkdirSync5(sddDir, { recursive: true });
   writeFileSync3(join7(sddDir, ".gitignore"), `*
 `);
-  return realpathSync2(sddDir);
+  return realpathSync3(sddDir);
 }
 function taskBrief(planFile, taskN, outFile, opts = {}) {
   if (!planFile || !Number.isInteger(taskN) || taskN < 1) {
@@ -1879,7 +1903,7 @@ function implementerSessionStickyRules(input) {
   return { resume: true, reason: `sticky resume OK: host_agent_id ${session.host_agent_id}, next task ${nextTask}` };
 }
 // src/iteration.ts
-import { existsSync as existsSync4, readdirSync as readdirSync4, readFileSync as readFileSync6 } from "node:fs";
+import { existsSync as existsSync5, readdirSync as readdirSync4, readFileSync as readFileSync6 } from "node:fs";
 import { join as join8 } from "node:path";
 var COMPASS_STATUSES = ["active", "locked", "completed"];
 var DATE_RE2 = /^\d{4}-\d{2}-\d{2}$/;
@@ -2108,7 +2132,7 @@ function pushCadenceProbe(ciRunning, reviewWaveActive) {
   return { ok: violations.length === 0, violations };
 }
 function assertIndexRowObligations(iterationsDir) {
-  if (!existsSync4(iterationsDir)) {
+  if (!existsSync5(iterationsDir)) {
     return {
       ok: false,
       violations: [
@@ -2116,9 +2140,9 @@ function assertIndexRowObligations(iterationsDir) {
       ]
     };
   }
-  const iterationIds = readdirSync4(iterationsDir, { withFileTypes: true }).filter((entry) => entry.isDirectory()).filter((entry) => existsSync4(join8(iterationsDir, entry.name, COMPASS_FILE))).map((entry) => entry.name).sort();
+  const iterationIds = readdirSync4(iterationsDir, { withFileTypes: true }).filter((entry) => entry.isDirectory()).filter((entry) => existsSync5(join8(iterationsDir, entry.name, COMPASS_FILE))).map((entry) => entry.name).sort();
   const readmePath = join8(iterationsDir, INDEX_README);
-  if (!existsSync4(readmePath)) {
+  if (!existsSync5(readmePath)) {
     return {
       ok: false,
       violations: [
@@ -2209,7 +2233,7 @@ function parseFlowArray(raw, filePath) {
   return items;
 }
 // src/project.ts
-import { existsSync as existsSync5, readFileSync as readFileSync7, readdirSync as readdirSync5 } from "node:fs";
+import { existsSync as existsSync6, readFileSync as readFileSync7, readdirSync as readdirSync5 } from "node:fs";
 import { join as join9 } from "node:path";
 var PROJECT_ROADMAP_FILE = "roadmap.md";
 var PROJECT_REFERENCES_DIR = "references";
@@ -2393,7 +2417,7 @@ function techDebtRollup(projectDir) {
     if (!project.isDirectory())
       continue;
     const registerPath = join9(projectDir, project.name, PROJECT_REGISTER_FILE);
-    if (!existsSync5(registerPath))
+    if (!existsSync6(registerPath))
       continue;
     let register;
     try {
@@ -2967,9 +2991,11 @@ async function applyMigratePlan(plan) {
     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(dirname7(filePath), { recursive: true });
+      writeJson(filePath, plan.register.data);
+    }
   }
   if (plan.roadmap !== null) {
     const filePath = projectTargetOf(plan.roadmap.file);
@@ -3396,8 +3422,8 @@ function completenessLevel(frontmatterText, checklist) {
   return { level, items, missing, placeholders, upgradeTo, bodyUnverified };
 }
 // src/audit.ts
-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, 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";
 function violation9(severity, code, message, fix) {
   return { ok: false, severity, code, message, fix };
 }
@@ -3469,74 +3495,6 @@ function validateAuditStatusBlocks(planText) {
   });
   return { ok: violations.length === 0, violations };
 }
-var WHOLE_MATCH_PATTERNS = [
-  { type: "private-key", re: /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----/g },
-  { type: "aws-access-key", re: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g },
-  { type: "github-token", re: /\bgh[pousr]_[A-Za-z0-9]{36,}\b/g },
-  { type: "slack-token", re: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g },
-  { type: "jwt", re: /\beyJ[A-Za-z0-9_-]{10,1024}\.[A-Za-z0-9_-]{10,1024}\.[A-Za-z0-9_-]{10,1024}\b/g },
-  { type: "api-secret-key", re: /\bsk-[A-Za-z0-9-]{20,}\b/g }
-];
-var VALUE_PATTERNS = [
-  {
-    typeOf: (key) => key.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase().replace(/[_-]+/g, "-"),
-    re: /(["']?)\b(password|passwd|api[_-]?key|access[_-]?token|auth[_-]?token|secret|token)\b(["']?)(\s*[:=]\s*)("[^"\n]{8,}"|'[^'\n]{8,}'|[A-Za-z0-9_./+\-=]{16,})/gi
-  }
-];
-function buildLineStarts(text) {
-  const starts = [0];
-  for (let i = 0;i < text.length; i++) {
-    if (text[i] === `
-`)
-      starts.push(i + 1);
-  }
-  return starts;
-}
-function lineAt(starts, index) {
-  let lo = 0;
-  let hi = starts.length - 1;
-  while (lo < hi) {
-    const mid = lo + hi + 1 >> 1;
-    if (starts[mid] <= index)
-      lo = mid;
-    else
-      hi = mid - 1;
-  }
-  return lo + 1;
-}
-function redactSecrets(text, filePath) {
-  const starts = buildLineStarts(text);
-  const marker = (type, index) => `[REDACTED ${type}@${lineAt(starts, index)}${filePath === undefined ? "" : ` in ${filePath}`}]`;
-  const replacements = [];
-  const findings = [];
-  for (const pattern of WHOLE_MATCH_PATTERNS) {
-    for (const match of text.matchAll(pattern.re)) {
-      if (match.index === undefined)
-        continue;
-      replacements.push({ index: match.index, length: match[0].length, text: marker(pattern.type, match.index) });
-      findings.push({ line: lineAt(starts, match.index), type: pattern.type });
-    }
-  }
-  for (const pattern of VALUE_PATTERNS) {
-    for (const match of text.matchAll(pattern.re)) {
-      if (match.index === undefined)
-        continue;
-      const type = pattern.typeOf(match[2]);
-      const replacement = `${match[1]}${match[2]}${match[3]}${match[4]}${marker(type, match.index)}`;
-      replacements.push({ index: match.index, length: match[0].length, text: replacement });
-      findings.push({ line: lineAt(starts, match.index), type });
-    }
-  }
-  replacements.sort((a, b) => b.index - a.index);
-  let out = text;
-  for (const r of replacements)
-    out = out.slice(0, r.index) + r.text + out.slice(r.index + r.length);
-  const deduped = new Map;
-  for (const f of findings)
-    deduped.set(`${f.line}:${f.type}`, f);
-  const sorted = [...deduped.values()].sort((a, b) => a.line - b.line || a.type.localeCompare(b.type));
-  return { text: out, findings: sorted };
-}
 function slugify(title) {
   return title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 }
@@ -3673,9 +3631,140 @@ 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,…)");
+  }
+  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}) — 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;
+}
 // src/compound.ts
-import { existsSync as existsSync6, readdirSync as readdirSync8, readFileSync as readFileSync10 } from "node:fs";
-import { basename as basename4, isAbsolute as isAbsolute7, join as join12, relative as relative4, resolve as resolve10, sep as sep3 } from "node:path";
+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";
 function violation10(severity, code, message, fix) {
   return { ok: false, severity, code, message, fix };
 }
@@ -3982,7 +4071,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 (existsSync6(resolve10(repoRoot, candidate))) {
+      if (existsSync8(resolve10(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"));
@@ -4013,7 +4102,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("/"));
       }
     }
   }
@@ -4030,7 +4119,7 @@ function normalizeIndexRef(cell) {
 function assertIndexRows(knowledgeDir) {
   const violations = [];
   const readmePath = join12(knowledgeDir, "README.md");
-  if (!existsSync6(readmePath)) {
+  if (!existsSync8(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 };
   }
@@ -4062,7 +4151,7 @@ function compoundRefreshScope(harnessDir, projectRoot) {
   ];
 }
 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(path, allowedRoots) {
   const resolved = resolve10(path);
@@ -4071,7 +4160,7 @@ function scopeGuard(path, 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: [] };
     }
   }
@@ -4315,7 +4404,7 @@ function lintStrategySections(docText) {
   return { ok: violations.length === 0, violations };
 }
 // src/roles.ts
-import { existsSync as existsSync7 } from "node:fs";
+import { existsSync as existsSync9 } from "node:fs";
 import { join as join13 } from "node:path";
 function violation12(severity, code, message, fix) {
   return { ok: false, severity, code, message, fix };
@@ -4372,7 +4461,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 (!existsSync7(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 § Role Reference Mapping)`, `create ${join13(rolesDir, reference)} or fix the mapping row`));
     }
   }
@@ -4628,11 +4717,11 @@ export {
   releaseLease,
   registerWorkflow,
   referenceExists,
-  redactSecrets,
   readProgressLedger,
   readJson,
   readHarnessVersion,
   pushCadenceProbe,
+  promoteAuditPlans,
   planQualityBar,
   planExecutionLeaseLocations,
   parseMstarc,

package/dist/index.d.ts

@@ -46,8 +46,8 @@ export type { MigrateNotesFile, MigrateOptions, MigratePlan, MigrateRegister, Mi
 export { ARCHIVED_STATUS_V1_FILE, MIGRATE_STATUS_FILE, NOTES_LEDGER_FILE, applyMigratePlan, migrateHarnessTree, } from "./migrate.js";
 export type { CompletenessItem, CompletenessLevel, CompletenessPlaceholder, CompletenessResult, DesignFrontmatter, } from "./design-md.js";
 export { assertLightDarkParity, completenessLevel, parseDesignFrontmatter, validateDesignTokenFrontmatter, } from "./design-md.js";
-export type { AuditCategory, AuditEffort, AuditFinding, AuditPriority, AuditRisk, RedactResult, ScaffoldAuditPlanOptions, ScaffoldAuditPlanResult, SecretFinding, } from "./audit.js";
-export { AUDIT_CATEGORIES, AUDIT_EFFORTS, AUDIT_PRIORITIES, AUDIT_RISKS, redactSecrets, scaffoldAuditPlan, validateAuditStatusBlocks, } from "./audit.js";
+export type { AuditCategory, AuditEffort, AuditFinding, AuditPriority, AuditRisk, PromoteAuditPlansOptions, RedactResult, ScaffoldAuditPlanOptions, ScaffoldAuditPlanResult, SecretFinding, } from "./audit.js";
+export { AUDIT_CATEGORIES, AUDIT_EFFORTS, AUDIT_PRIORITIES, AUDIT_RISKS, promoteAuditPlans, scaffoldAuditPlan, validateAuditStatusBlocks, } from "./audit.js";
 export type { ReferenceCheckResult } from "./compound.js";
 export { KNOWLEDGE_BUG_PROBLEM_TYPES, KNOWLEDGE_CATEGORY_MAP, KNOWLEDGE_KNOWLEDGE_PROBLEM_TYPES, KNOWLEDGE_PROBLEM_TYPES, KNOWLEDGE_REQUIRED_FIELDS, KNOWLEDGE_RESOLUTION_TYPES, KNOWLEDGE_SEVERITIES, assertIndexRows, compoundRefreshScope, referenceExists, scopeGuard, validateSchemaYaml, } from "./compound.js";
 export type { EphemeralCitation, PlanQualityFinding, PlanQualityResult, SimplifyMarker, TemporaryMarker, TemporaryMarkerResult, } from "./lint.js";