@mstar-harness/engine 3.1.2 → 3.1.3

package/dist/audit.d.ts

@@ -97,3 +97,45 @@ export type ScaffoldAuditPlanResult = {
  * findings render in the "considered and rejected" section.
  */
 export declare function scaffoldAuditPlan(outDir: string, findings: readonly AuditFinding[], options?: ScaffoldAuditPlanOptions): ScaffoldAuditPlanResult;
+/** Options for `promoteAuditPlans`. `harnessDir` is required — the snapshot
+ * and `status.json` live under the harness, never beside the audit dir. */
+export type PromoteAuditPlansOptions = {
+    /** Absolute harness dir that contains `status.json` + `workflows/`. Required. */
+    harnessDir: string;
+    /** Default: basename of `outDir` (e.g. `audit-2026-08-22`). */
+    workflowId?: string;
+};
+/**
+ * Promote selected audit plans into the v2 workflow lifecycle as a
+ * `type: "plan"` workflow (mstar-audit Handoff): write the workflow
+ * snapshot FIRST (with one Todo PlanRow per selected file), then register
+ * the workflow entry — `validateStatusV2` validates the full status doc
+ * including the per-snapshot existence check, so the snapshot must exist
+ * before the registration. Plan rows are built from the README index
+ * `## Execution order & status` columns (Plan/Title), falling back to the
+ * private `readPlanFileSummary` only when the index lacks the row.
+ *
+ * Run-once semantics: a workflow id whose snapshot already exists refuses
+ * the promote (re-promote would drop its registered plan rows); remove
+ * that workflow first.
+ *
+ * The re-promote guard, the snapshot write, and the root upsert run in ONE
+ * atomic section under the root `withStatusWriteLock(statusPath)` — the
+ * same root lock `registerWorkflow` uses — so the guard is check-then-act
+ * safe: two concurrent same-id promotes cannot both pass it (one writes
+ * and registers; the other re-checks under the lock and refuses). The
+ * snapshot is written directly with `writeJson` under the root lock (never
+ * a nested `writeWorkflowSnapshot` — its own snapshot-dir lock would be a
+ * second serialization point; the root lock must be THE serialization
+ * point). The root upsert replicates `registerWorkflow` semantics inline
+ * via the shared `registerWorkflowEntryLocked` helper (calling
+ * `registerWorkflow` itself would re-enter the non-reentrant root lock).
+ *
+ * On any failure inside the lock, the partial snapshot + now-empty
+ * workflow dir are rolled back so a retry converges after the root
+ * conflict is resolved.
+ */
+export declare function promoteAuditPlans(outDir: string, selected: readonly string[], options: PromoteAuditPlansOptions): Promise<{
+    workflowId: string;
+    snapshotPath: string;
+}>;

package/dist/audit.js

@@ -0,0 +1,755 @@
+// src/audit.ts
+import { existsSync as existsSync3, mkdirSync as mkdirSync3, readdirSync as readdirSync2, readFileSync as readFileSync3, rmdirSync as rmdirSync2, rmSync, writeFileSync as writeFileSync3 } from "node:fs";
+import { basename as basename2, join as join4, resolve as resolve4, sep as sep2 } from "node:path";
+
+// src/core.ts
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { basename, dirname, join, resolve } from "node:path";
+function readJson(filePath) {
+  if (!existsSync(filePath))
+    return {};
+  const content = readFileSync(filePath, "utf8").trim();
+  if (!content)
+    return {};
+  try {
+    return JSON.parse(content);
+  } catch (error) {
+    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;
+  }
+}
+
+// src/lease.ts
+import { mkdirSync as mkdirSync2, rmdirSync, statSync, unlinkSync as unlinkSync2, writeFileSync as writeFileSync2 } from "node:fs";
+import { dirname as dirname2, isAbsolute, join as join2, resolve as resolve2 } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+import { AsyncLocalStorage } from "node:async_hooks";
+var DATE_PART = String.raw`\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])`;
+var RFC3339_Z_RE = new RegExp(String.raw`^${DATE_PART}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$`);
+var DATE_ONLY_RE = new RegExp(String.raw`^${DATE_PART}$`);
+var STATUS_WRITE_LOCKDIR = ".status-write.lockdir";
+var LOCKDIR_HOLDER_PID = "holder.pid";
+var heldLockDirs = new AsyncLocalStorage;
+async function withStatusWriteLock(statusPath, fn, opts = {}) {
+  const lockDir = join2(dirname2(resolve2(statusPath)), STATUS_WRITE_LOCKDIR);
+  const held = heldLockDirs.getStore();
+  if (held !== undefined && held.has(lockDir)) {
+    throw new Error(`${lockDir} is already held by this process in this async context — withStatusWriteLock is not reentrant; a nested acquisition on the same status.json is a bug`);
+  }
+  const timeoutMs = opts.timeoutMs ?? 30000;
+  const pollMs = opts.pollMs ?? 25;
+  const deadline = Date.now() + timeoutMs;
+  let acquired = null;
+  for (;; ) {
+    try {
+      mkdirSync2(lockDir);
+      const st = statSync(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 — another writer holds the status write lock; Blocked (same-host exclusive lock; status-and-residuals.md § 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(join2(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 = statSync(lockDir);
+      if (acquired !== null && current.dev === acquired.dev && current.ino === acquired.ino) {
+        try {
+          unlinkSync2(join2(lockDir, LOCKDIR_HOLDER_PID));
+        } catch {}
+        rmdirSync(lockDir);
+      }
+    } catch {}
+  }
+}
+
+// src/mstarc.ts
+var MSTARC_HARNESS_DIR_KEY = "harness_dir";
+var MSTARC_PLAN_DIR_KEY = "plan_dir";
+var MSTARC_SDD_DIR_KEY = "sdd_dir";
+var MSTARC_ITERATION_DIR_KEY = "iteration_dir";
+var MSTARC_KNOWLEDGE_DIR_KEY = "knowledge_dir";
+var MSTARC_SPECS_DIR_KEY = "specs_dir";
+var MSTARC_WORKFLOW_DIR_KEY = "workflow_dir";
+var MSTARC_PROJECT_DIR_KEY = "project_dir";
+var MSTARC_ENFORCEMENT_KEY = "enforcement";
+var CONFIG_KEYS = {
+  [MSTARC_HARNESS_DIR_KEY]: "harnessDir",
+  [MSTARC_PLAN_DIR_KEY]: "planDir",
+  [MSTARC_SDD_DIR_KEY]: "sddDir",
+  [MSTARC_ITERATION_DIR_KEY]: "iterationDir",
+  [MSTARC_KNOWLEDGE_DIR_KEY]: "knowledgeDir",
+  [MSTARC_SPECS_DIR_KEY]: "specsDir",
+  [MSTARC_WORKFLOW_DIR_KEY]: "workflowDir",
+  [MSTARC_PROJECT_DIR_KEY]: "projectDir",
+  [MSTARC_ENFORCEMENT_KEY]: "enforcement"
+};
+
+// src/path.ts
+function assertSafePathComponent(value, what) {
+  if (value === "" || value === "." || value === ".." || !/^[A-Za-z0-9._-]+$/.test(value)) {
+    throw new Error(`${what} must be a single safe path component ([A-Za-z0-9._-]+; not "", ".", "..", or containing "/" or "\\") — got ${JSON.stringify(value)}`);
+  }
+}
+var GITIGNORE_SNIPPET = `# Morning Star harness (.mstar/)
+# Principle: process stays local; results are shared with the team.
+# Default-ignore everything under .mstar/, then re-include the tracked results.
+.mstar/**
+!.mstar/AGENTS.md
+!.mstar/knowledge/
+!.mstar/knowledge/**
+!.mstar/specs/
+!.mstar/specs/**
+# .mstarc — repo-local harness config (may declare [config] harness_dir=<name>)
+.mstarc
+`;
+var GITIGNORE_SNIPPET_AGENTS = `# Morning Star harness (.agents/) — legacy
+# Default-ignore everything under .agents/, then re-include the tracked results.
+.agents/**
+!.agents/AGENTS.md
+!.agents/knowledge/
+!.agents/knowledge/**
+!.agents/specs/
+!.agents/specs/**
+`;
+var GITIGNORE_PROCESS_ENTRIES = GITIGNORE_SNIPPET.split(`
+`).filter((line) => line.startsWith(".mstar/") || line.startsWith("!.mstar/")).map((line) => line.trim());
+var GITIGNORE_PROCESS_ENTRIES_AGENTS = GITIGNORE_SNIPPET_AGENTS.split(`
+`).filter((line) => line.startsWith(".agents/") || line.startsWith("!.agents/")).map((line) => line.trim());
+
+// src/status.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2, readdirSync, realpathSync } from "node:fs";
+import { dirname as dirname3, join as join3, resolve as resolve3, sep } from "node:path";
+
+// src/workflow.ts
+var WORKFLOW_SNAPSHOT_FILE = "snapshot.json";
+var WORKFLOW_TERMINAL_STATUSES = ["completed", "failed", "stopped"];
+var WORKFLOW_LIFECYCLE_TYPES = ["plan", "iteration"];
+
+// src/status.ts
+var DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function violation(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 validateNonEmptyString(violations, value, field, missingCode, invalidCode) {
+  if (value === undefined) {
+    violations.push(violation("high", missingCode, `missing required field: ${field}`));
+  } else if (typeof value !== "string" || value.trim() === "") {
+    violations.push(violation("medium", invalidCode, `${field} must be a non-empty string`));
+  }
+}
+function isHarnessRelativePath(dir) {
+  if (dir.startsWith("/") || dir.startsWith("\\"))
+    return false;
+  if (/^[A-Za-z]:[\\/]/.test(dir))
+    return false;
+  return !dir.split(/[\\/]+/).includes("..");
+}
+function validateWorkflowEntry(entry) {
+  const violations = [];
+  if (!isPlainObject(entry)) {
+    return {
+      ok: false,
+      violations: [violation("high", "status.workflow.invalid", "workflow entry must be an object")]
+    };
+  }
+  validateNonEmptyString(violations, entry.id, "id", "status.workflow.missing-id", "status.workflow.invalid-id");
+  if (entry.type === undefined) {
+    violations.push(violation("high", "status.workflow.missing-type", "missing required field: type"));
+  } else if (typeof entry.type !== "string" || !WORKFLOW_LIFECYCLE_TYPES.includes(entry.type)) {
+    violations.push(violation("medium", "status.workflow.invalid-type", `type must be one of ${WORKFLOW_LIFECYCLE_TYPES.join(" | ")} — got ${JSON.stringify(entry.type)}`));
+  }
+  validateNonEmptyString(violations, entry.started_at, "started_at", "status.workflow.missing-started-at", "status.workflow.invalid-started-at");
+  if (entry.dir === undefined) {
+    violations.push(violation("high", "status.workflow.missing-dir", "missing required field: dir"));
+  } else if (typeof entry.dir !== "string" || entry.dir.trim() === "") {
+    violations.push(violation("medium", "status.workflow.invalid-dir", "dir must be a non-empty string"));
+  } else if (!isHarnessRelativePath(entry.dir)) {
+    violations.push(violation("medium", "status.workflow.invalid-dir", `dir must be a harness-relative path (no absolute paths, no ".." segments) — got ${JSON.stringify(entry.dir)}`));
+  }
+  return { ok: violations.length === 0, violations };
+}
+function validateStatusV2(docOrPath, opts = {}) {
+  let doc;
+  let harnessDir = opts.harnessDir;
+  if (typeof docOrPath === "string") {
+    try {
+      doc = readJson(docOrPath);
+      harnessDir = dirname3(resolve3(docOrPath));
+    } catch (error) {
+      return {
+        ok: false,
+        violations: [violation("high", "status.invalid-json", error.message)]
+      };
+    }
+  } else {
+    doc = docOrPath;
+  }
+  if (!isPlainObject(doc)) {
+    return { ok: false, violations: [violation("high", "status.invalid-doc", "status document must be an object")] };
+  }
+  if (doc.version !== 2) {
+    return {
+      ok: false,
+      violations: [
+        violation("high", "status.migration-required", `status.json schema version 2 required — got ${JSON.stringify(doc.version)} (v1 or unknown version); run \`mstar migrate\` to convert the tree`, "run `mstar migrate`")
+      ]
+    };
+  }
+  if (Array.isArray(doc.plans)) {
+    return {
+      ok: false,
+      violations: [
+        violation("high", "status.migration-required", "v1-shaped status.json (root plans[]) is not a v2 document — run `mstar migrate` to convert the tree", "run `mstar migrate`")
+      ]
+    };
+  }
+  if (doc.residual_findings !== undefined) {
+    return {
+      ok: false,
+      violations: [
+        violation("high", "status.migration-required", "v1-shaped status.json (root residual_findings) is not a v2 document — run `mstar migrate` to convert the tree", "run `mstar migrate`")
+      ]
+    };
+  }
+  const violations = [];
+  if (doc.updated_at === undefined) {
+    violations.push(violation("high", "status.missing-updated-at", "missing required field: updated_at"));
+  } else if (typeof doc.updated_at !== "string" || !DATE_RE.test(doc.updated_at)) {
+    violations.push(violation("medium", "status.invalid-updated-at", "updated_at must be YYYY-MM-DD"));
+  }
+  if (doc.workflows === undefined) {
+    violations.push(violation("high", "status.missing-workflows", "missing required field: workflows"));
+  } else if (!Array.isArray(doc.workflows)) {
+    violations.push(violation("high", "status.invalid-workflows", "workflows must be an array"));
+  } else {
+    const seen = new Set;
+    for (const entry of doc.workflows) {
+      violations.push(...validateWorkflowEntry(entry).violations);
+      if (isPlainObject(entry) && typeof entry.id === "string") {
+        if (seen.has(entry.id)) {
+          violations.push(violation("medium", "status.workflow.duplicate-id", `duplicate workflow id in workflows[]: ${JSON.stringify(entry.id)}`));
+        }
+        seen.add(entry.id);
+      }
+    }
+  }
+  if (harnessDir !== undefined && Array.isArray(doc.workflows)) {
+    let realHarnessDir = null;
+    try {
+      realHarnessDir = realpathSync(harnessDir);
+    } catch {}
+    for (const entry of doc.workflows) {
+      if (!isPlainObject(entry) || typeof entry.dir !== "string")
+        continue;
+      const relSnapshot = join3(entry.dir, WORKFLOW_SNAPSHOT_FILE);
+      const snapshotPath = join3(harnessDir, relSnapshot);
+      const label = typeof entry.id === "string" ? entry.id : relSnapshot;
+      let physical;
+      try {
+        physical = realpathSync(snapshotPath);
+      } catch {
+        violations.push(violation("high", "status.workflow.snapshot-missing", `workflows[] lists ${JSON.stringify(label)} but its snapshot does not exist at ${JSON.stringify(relSnapshot)} — the root holds active lifecycles only; unregister the id when its snapshot is removed`));
+        continue;
+      }
+      if (realHarnessDir !== null && physical !== realHarnessDir && !physical.startsWith(`${realHarnessDir}${sep}`)) {
+        violations.push(violation("high", "status.workflow.snapshot-outside-harness", `workflows[] lists ${JSON.stringify(label)} but its snapshot resolves outside the harness dir (${JSON.stringify(physical)}) — symlinked snapshot paths are rejected; the snapshot must physically live under ${JSON.stringify(harnessDir)}`));
+        continue;
+      }
+      let snapshot;
+      try {
+        snapshot = readJson(snapshotPath);
+      } catch (error) {
+        violations.push(violation("high", "status.workflow.snapshot-invalid", `snapshot at ${JSON.stringify(relSnapshot)} is not valid JSON: ${error.message}`));
+        continue;
+      }
+      if (typeof snapshot.status === "string" && WORKFLOW_TERMINAL_STATUSES.includes(snapshot.status)) {
+        violations.push(violation("high", "status.workflow.terminal-listed", `workflows[] lists ${JSON.stringify(label)} whose snapshot status is terminal (${snapshot.status}) — removal-at-terminal: terminal writers unregister AFTER the snapshot write`));
+      }
+      if (typeof entry.type === "string" && typeof snapshot.type === "string" && entry.type !== snapshot.type) {
+        violations.push(violation("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(violation("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 };
+}
+function registerWorkflowEntryLocked(statusPath, entry) {
+  const harnessDir = dirname3(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;
+}
+
+// src/audit.ts
+function violation2(severity, code, message, fix) {
+  return { ok: false, severity, code, message, fix };
+}
+var AUDIT_PRIORITIES = ["P1", "P2", "P3"];
+var AUDIT_EFFORTS = ["XS", "S", "M", "L", "XL"];
+var AUDIT_RISKS = ["LOW", "MED", "HIGH"];
+var AUDIT_CATEGORIES = [
+  "bug",
+  "security",
+  "perf",
+  "tests",
+  "tech-debt",
+  "migration",
+  "dx",
+  "docs",
+  "direction"
+];
+var AUDIT_STATUS_FIELDS = ["Priority", "Effort", "Risk", "Depends on", "Category", "Planned at"];
+function parseStatusBlocks(planText) {
+  const blocks = [];
+  let current = null;
+  for (const line of planText.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (trimmed === "## Status") {
+      current = new Map;
+      blocks.push({ fields: current });
+      continue;
+    }
+    if (current === null)
+      continue;
+    if (trimmed.startsWith("#")) {
+      current = null;
+      continue;
+    }
+    const match = /^-\s*\*\*([^*]+)\*\*:\s*(.*)$/.exec(trimmed);
+    if (match !== null)
+      current.set(match[1].trim(), match[2].trim());
+  }
+  return blocks;
+}
+function validateAuditStatusBlocks(planText) {
+  const violations = [];
+  const blocks = parseStatusBlocks(planText);
+  if (blocks.length === 0) {
+    violations.push(violation2("medium", "audit.status.missing-block", "no `## Status` block found — audit plan files carry the Status block fields (mstar-audit SKILL § Plan files)", "add a `## Status` block with Priority, Effort, Risk, Depends on, Category, Planned at"));
+    return { ok: false, violations };
+  }
+  blocks.forEach((block, index) => {
+    const label = blocks.length > 1 ? ` #${index + 1}` : "";
+    for (const field of AUDIT_STATUS_FIELDS) {
+      if (!block.fields.has(field)) {
+        violations.push(violation2("medium", "audit.status.missing-field", `Status block${label} missing required field "${field}" (mstar-audit SKILL § Plan files)`, `add \`- **${field}**: <value>\` to the Status block`));
+      }
+    }
+    const check = (field, pattern, code, expected) => {
+      const value = block.fields.get(field);
+      if (value === undefined)
+        return;
+      if (!pattern.test(value)) {
+        violations.push(violation2("medium", code, `Status block${label} "${field}" = "${value}" — expected ${expected} (mstar-audit SKILL § Plan files)`, `fix \`- **${field}**:\` to one of: ${expected}`));
+      }
+    };
+    check("Priority", /^P[123]$/, "audit.status.invalid-priority", "P1 | P2 | P3");
+    check("Effort", /^(?:XS|S|M|L|XL)$/, "audit.status.invalid-effort", "XS | S | M | L | XL");
+    check("Risk", /^(?:LOW|MED|HIGH)$/, "audit.status.invalid-risk", "LOW | MED | HIGH");
+    check("Category", /^(?:bug|security|perf|tests|tech-debt|migration|dx|docs|direction)$/, "audit.status.invalid-category", "bug | security | perf | tests | tech-debt | migration | dx | docs | direction");
+    check("Depends on", /^(?:none|plans\/\d{3}-[\w.*-]+\.md)$/i, "audit.status.invalid-depends-on", "none or plans/NNN-*.md");
+    check("Planned at", /^commit \`?(?:[0-9a-f]{7,40}|unknown)\`?, \d{4}-\d{2}-\d{2}$/, "audit.status.invalid-planned-at", "commit <short SHA>, <YYYY-MM-DD> (or `commit unknown` outside a git repo)");
+  });
+  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, "");
+}
+var escapeCell = (value) => value.replace(/\|/g, "\\|");
+var truncate = (value, max) => value.length > max ? `${value.slice(0, max)}…` : value;
+function renderPlanFile(finding, plannedAt) {
+  const sections = [
+    `# ${finding.title}`,
+    "",
+    "## Status",
+    `- **Priority**: ${finding.priority}`,
+    `- **Effort**: ${finding.effort}`,
+    `- **Risk**: ${finding.risk}`,
+    `- **Depends on**: ${finding.dependsOn ?? "none"}`,
+    `- **Category**: ${finding.category}`,
+    `- **Planned at**: commit \`${plannedAt.commit}\`, ${plannedAt.date}`,
+    "",
+    "## Impact",
+    finding.impact
+  ];
+  if (finding.evidence.length > 0) {
+    sections.push("", "## Evidence", ...finding.evidence.map((e) => `- ${e}`));
+  }
+  if (finding.fixSketch !== undefined) {
+    sections.push("", "## Fix sketch", finding.fixSketch);
+  }
+  if (finding.verification !== undefined) {
+    sections.push("", "## Verification", finding.verification);
+  }
+  return `${sections.join(`
+`)}
+`;
+}
+function readPlanFileSummary(filePath) {
+  const text = readFileSync3(filePath, "utf8");
+  const title = (text.match(/^# (.+)$/m) ?? [])[1] ?? filePath;
+  const blocks = parseStatusBlocks(text);
+  return { title: title.trim(), fields: blocks.length > 0 ? blocks[0].fields : new Map };
+}
+function renderIndex(params) {
+  const { date, repoName, repoShortSha, rows, rejected } = params;
+  const findingsRows = rows.map((r) => `| ${r.num} | ${escapeCell(r.title)} | ${r.category} | ${escapeCell(truncate(r.impact, 80))} | ${r.effort} | ${r.risk} | ${r.confidence} | ${escapeCell(truncate(r.evidence, 80))} |`).join(`
+`);
+  const directionRows = rows.filter((r) => r.category === "direction").map((r) => `- ${escapeCell(r.title)} — ${escapeCell(truncate(r.impact, 120))}`).join(`
+`);
+  const executionRows = rows.map((r) => `| ${r.num} | ${escapeCell(r.title)} | ${r.priority} | ${r.effort} | ${r.dependsOn} | TODO |`).join(`
+`);
+  const rejectedRows = rejected.map((r) => `- ${escapeCell(r.title)}: ${escapeCell(r.reason)}`).join(`
+`);
+  const sections = [
+    `# Audit Report — ${repoName} @ ${repoShortSha} (${date})`,
+    "",
+    "## Findings",
+    "",
+    "| # | Finding | Category | Impact | Effort | Risk | Confidence | Evidence |",
+    "|---|---------|----------|--------|--------|------|------------|----------|",
+    findingsRows
+  ];
+  if (directionRows !== "") {
+    sections.push("", "## Direction", "", directionRows);
+  }
+  sections.push("", "## Execution order & status", "", "| Plan | Title | Priority | Effort | Depends on | Status |", "|------|-------|----------|--------|------------|--------|", executionRows);
+  if (rejectedRows !== "") {
+    sections.push("", "## Findings considered and rejected", "", rejectedRows);
+  }
+  sections.push("", "## Red-team dispositions", "", "- <finding>: <survived / refuted / hallucination-dropped / uncovered-kept>, <one-line reason>");
+  return `${sections.join(`
+`)}
+`;
+}
+function scaffoldAuditPlan(outDir, findings, options = {}) {
+  const date = options.date ?? new Date().toISOString().slice(0, 10);
+  const plannedAt = options.plannedAt ?? { commit: options.repoShortSha ?? "unknown", date };
+  mkdirSync3(outDir, { recursive: true });
+  const existing = readdirSync2(outDir).filter((f) => /^\d{3}-.*\.md$/.test(f));
+  let next = existing.reduce((max, f) => Math.max(max, Number(f.slice(0, 3))), 0) + 1;
+  const written = [];
+  const usedSlugs = new Set;
+  for (const finding of findings) {
+    const num = String(next).padStart(3, "0");
+    let slug = slugify(finding.title);
+    if (usedSlugs.has(slug)) {
+      let n = 2;
+      while (usedSlugs.has(`${slug}-${n}`))
+        n++;
+      slug = `${slug}-${n}`;
+    }
+    usedSlugs.add(slug);
+    const file = `${num}-${slug}.md`;
+    writeFileSync3(join4(outDir, file), renderPlanFile(finding, plannedAt));
+    written.push(file);
+    next++;
+  }
+  const all = [...existing, ...written].sort();
+  const rows = all.map((file) => {
+    const summary = readPlanFileSummary(join4(outDir, file));
+    const fields = summary.fields;
+    return {
+      num: file.slice(0, 3),
+      title: summary.title,
+      category: fields.get("Category") ?? "—",
+      impact: "see plan file",
+      effort: fields.get("Effort") ?? "—",
+      risk: fields.get("Risk") ?? "—",
+      confidence: "—",
+      evidence: fields.get("Evidence") ?? "—",
+      priority: fields.get("Priority") ?? "—",
+      dependsOn: fields.get("Depends on") ?? "—"
+    };
+  });
+  const byNum = new Map(rows.map((r) => [r.num, r]));
+  written.forEach((file, i) => {
+    const finding = findings[i];
+    if (finding === undefined)
+      return;
+    const row = byNum.get(file.slice(0, 3));
+    if (row !== undefined) {
+      row.category = finding.category;
+      row.impact = finding.impact;
+      row.effort = finding.effort;
+      row.risk = finding.risk;
+      row.confidence = finding.confidence;
+      row.evidence = finding.evidence[0] ?? "";
+      row.priority = finding.priority;
+      row.dependsOn = finding.dependsOn ?? "none";
+    }
+  });
+  writeFileSync3(join4(outDir, "README.md"), renderIndex({
+    date,
+    repoName: options.repoName ?? "repo",
+    repoShortSha: options.repoShortSha ?? "unknown",
+    rows,
+    rejected: options.rejected ?? []
+  }));
+  return { outDir: resolve4(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 ?? basename2(resolve4(outDir));
+  assertSafePathComponent(workflowId, "workflow id");
+  const harnessDir = resolve4(options.harnessDir);
+  const statusPath = join4(harnessDir, "status.json");
+  const workflowDir = join4(harnessDir, "workflows", workflowId);
+  const snapshotPath = join4(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(join4(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 (existsSync3(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`);
+    }
+    mkdirSync3(workflowDir, { recursive: true });
+    try {
+      writeJson(snapshotPath, snapshot);
+      registerWorkflowEntryLocked(statusPath, entry);
+    } catch (error) {
+      rmSync(snapshotPath, { force: true });
+      try {
+        if (readdirSync2(workflowDir).length === 0) {
+          rmdirSync2(workflowDir);
+        }
+      } catch {}
+      throw error;
+    }
+    return { workflowId, snapshotPath };
+  });
+  return { workflowId, snapshotPath };
+}
+function resolveSelectedPlanFiles(outDir, selected) {
+  const files = readdirSync2(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 ${resolve4(outDir)}`);
+    }
+    if (!seen.has(file)) {
+      seen.add(file);
+      resolved.push(file);
+    }
+  }
+  return resolved;
+}
+function readExecutionOrderIndex(outDir) {
+  const readmePath = join4(outDir, "README.md");
+  let text;
+  try {
+    text = readFileSync3(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 = resolve4(outDir);
+  const parts = resolved.split(sep2);
+  const plansIdx = parts.lastIndexOf("plans");
+  if (plansIdx >= 0) {
+    return `${parts.slice(plansIdx + 1).join(sep2)}${sep2}${planFile}`;
+  }
+  return planFile;
+}
+export {
+  validateAuditStatusBlocks,
+  scaffoldAuditPlan,
+  redactSecrets,
+  promoteAuditPlans,
+  AUDIT_RISKS,
+  AUDIT_PRIORITIES,
+  AUDIT_EFFORTS,
+  AUDIT_CATEGORIES
+};

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/engine.js

@@ -1350,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() === "") {
@@ -2990,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);
@@ -3419,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 };
 }
@@ -3492,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, "");
 }
@@ -3696,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 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, 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 };
 }
@@ -4005,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 (existsSync7(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"));
@@ -4036,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("/"));
       }
     }
   }
@@ -4053,7 +4119,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} — 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 };
   }
@@ -4085,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);
@@ -4094,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: [] };
     }
   }
@@ -4338,7 +4404,7 @@ function lintStrategySections(docText) {
   return { ok: violations.length === 0, violations };
 }
 // src/roles.ts
-import { existsSync as existsSync8 } 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 };
@@ -4395,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 (!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 § Role Reference Mapping)`, `create ${join13(rolesDir, reference)} or fix the mapping row`));
     }
   }
@@ -4651,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";

package/dist/status.d.ts

@@ -136,6 +136,26 @@ export declare function validateStatusV2(docOrPath: StatusV2Doc | string, opts?:
  * closed on v1 input with the `mstar migrate` hint.
  */
 export declare const validateStatus: typeof validateStatusV2;
+/**
+ * Root-file workflow upsert, to be called ONLY while the caller holds the
+ * root `withStatusWriteLock(statusPath)` (see `registerWorkflow` and the
+ * audit promote path, which call this from inside their lock — the root
+ * lock is the serialization point for read-check-replace-verify).
+ *
+ * Idempotent upsert by entry `id`, bumping root `updated_at`. A
+ * missing/empty root file is initialized from the v2 template (never a v1
+ * tree); a v1 root is refused with the `mstar migrate` hint (no silent
+ * mutation of an un-migrated tree). The final document is validated with
+ * `validateStatusV2` (including the removal-at-terminal snapshot invariant
+ * against `dirname(statusPath)`) before the write — an entry whose
+ * snapshot is missing or terminal is refused and nothing is written.
+ *
+ * The caller must validate the entry (`validateWorkflowEntry`) before
+ * acquiring the lock; this helper asserts it as a safety net (cheap —
+ * an invalid entry would fail `validateStatusV2` anyway, but the explicit
+ * gate keeps the pre-lock fail-fast contract of `registerWorkflow`).
+ */
+export declare function registerWorkflowEntryLocked(statusPath: string, entry: WorkflowEntry): StatusV2Doc;
 /**
  * Register one active workflow entry in the v2 root file (plan Task 3).
  * Idempotent upsert by entry `id` under the root-file `withStatusWriteLock`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mstar-harness/engine",
-  "version": "3.1.2",
+  "version": "3.1.3",
   "description": "Morning Star Harness Workflow Engine — deterministic workflow enforcement library (path, status, lease, dispatch, sdd, iteration, lint gates).",
   "license": "MIT",
   "repository": {
@@ -16,13 +16,17 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/engine.js"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./src/audit": {
+      "types": "./dist/audit.d.ts",
+      "default": "./dist/audit.js"
+    }
   },
   "files": [
     "dist"
   ],
   "scripts": {
-    "build": "rm -rf dist && bun build src/index.ts --target node --outfile dist/engine.js && bunx tsc",
+    "build": "rm -rf dist && bun build src/index.ts --target node --outfile dist/engine.js && bun build src/audit.ts --target node --outfile dist/audit.js && bunx tsc",
     "test": "bun test",
     "prepublishOnly": "bun run build"
   },