@mstar-harness/cli 1.8.9 → 2.0.0

package/dist/mstar-harness.js

@@ -2344,7 +2344,8 @@ var require_commander = __commonJS((exports) => {
 });
 
 // src/index.ts
-import fs9 from "fs";
+import { execFileSync as execFileSync6 } from "child_process";
+import fs7 from "fs";
 import path11 from "path";
 
 // ../../node_modules/@inquirer/core/dist/lib/key.js
@@ -3973,52 +3974,2535 @@ var {
   Help
 } = import__.default;
 
+// ../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 { mkdirSync as mkdirSync2, readdirSync, readFileSync as readFileSync2, statSync } from "node:fs";
+import { basename as basename2, dirname as dirname2, isAbsolute, join as join2, relative, resolve as resolve2 } from "node:path";
+import { existsSync as existsSync2, readFileSync as readFileSync3, readdirSync as readdirSync2 } from "node:fs";
+import { join as join4, resolve as resolve4 } from "node:path";
+import { mkdirSync as mkdirSync3, rmdirSync, statSync as statSync2, unlinkSync as unlinkSync2, writeFileSync as writeFileSync2 } from "node:fs";
+import { dirname as dirname3, isAbsolute as isAbsolute2, join as join3, resolve as resolve3 } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+import { AsyncLocalStorage as AsyncLocalStorage2 } from "node:async_hooks";
+import { execFileSync } from "node:child_process";
+import { existsSync as existsSync3 } from "node:fs";
+import { isAbsolute as isAbsolute3, resolve as resolve5 } from "node:path";
+import { execFileSync as execFileSync2 } from "node:child_process";
+import { mkdirSync as mkdirSync4, readFileSync as readFileSync4, realpathSync, statSync as statSync3, writeFileSync as writeFileSync3 } from "node:fs";
+import { basename as basename3, dirname as dirname4, isAbsolute as isAbsolute4, join as join5, resolve as resolve6 } from "node:path";
+import { mkdirSync as mkdirSync5, readdirSync as readdirSync4, readFileSync as readFileSync6, writeFileSync as writeFileSync4 } from "node:fs";
+import { join as join7, resolve as resolve7 } from "node:path";
+import { existsSync as existsSync5, readdirSync as readdirSync5, readFileSync as readFileSync7 } from "node:fs";
+import { basename as basename4, isAbsolute as isAbsolute5, join as join8, relative as relative2, resolve as resolve8, sep } from "node:path";
+var SEVERITY_ORDER = ["critical", "high", "medium", "low", "nit"];
+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;
+  }
+}
+function resolveHarnessDir(startDir = process.cwd(), opts = {}) {
+  const start = resolve2(startDir);
+  const explicit = opts.harnessDir ?? process.env.MSTAR_HARNESS_DIR;
+  if (explicit)
+    return resolve2(start, explicit);
+  let dir = start;
+  for (;; ) {
+    for (const candidate of [join2(dir, ".mstar"), join2(dir, ".agents"), join2(dir, ".plans"), join2(dir, "plans")]) {
+      if (isDirectory(candidate))
+        return candidate;
+    }
+    const parent = dirname2(dir);
+    if (parent === dir)
+      return null;
+    dir = parent;
+  }
+}
+function resolveSpecsDir(harnessDir, opts = {}) {
+  const harness = resolve2(harnessDir);
+  const repoRoot = dirname2(harness);
+  const candidates = [
+    join2(harness, "specs"),
+    join2(repoRoot, "docs", "specs"),
+    join2(repoRoot, "specs"),
+    join2(harness, "designs"),
+    join2(repoRoot, "designs")
+  ];
+  for (const candidate of candidates) {
+    if (isDirectory(candidate) && hasFiles(candidate))
+      return candidate;
+  }
+  const fallback = join2(harness, "specs");
+  if (opts.create !== false)
+    mkdirSync2(fallback, { recursive: true });
+  return fallback;
+}
+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)}`);
+  }
+}
+function resolveSddDir(harnessDir, planId) {
+  assertSafePathComponent(planId, "planId");
+  return join2(resolve2(harnessDir), "sdd", planId);
+}
+var GITIGNORE_SNIPPET = `# Morning Star harness (.mstar/)
+# Principle: process stays local; results are shared with the team.
+# Ignored (process / coordination):
+.mstar/archived/
+.mstar/iterations/
+.mstar/plans/
+.mstar/sdd/
+.mstar/notes.json
+.mstar/status.json
+# Tracked (results): .mstar/AGENTS.md, .mstar/knowledge/, .mstar/specs/
+`;
+var GITIGNORE_SNIPPET_AGENTS = `# Morning Star harness (.agents/) — legacy
+.agents/archived/
+.agents/iterations/
+.agents/plans/
+.agents/sdd/
+.agents/notes.json
+.agents/status.json
+# Tracked (results): .agents/AGENTS.md, .agents/knowledge/, .agents/specs/
+`;
+var GITIGNORE_PROCESS_ENTRIES = GITIGNORE_SNIPPET.split(`
+`).filter((line) => line.startsWith(".mstar/")).map((line) => line.trim());
+var GITIGNORE_PROCESS_ENTRIES_AGENTS = GITIGNORE_SNIPPET_AGENTS.split(`
+`).filter((line) => line.startsWith(".agents/")).map((line) => line.trim());
+function isDirectory(dir) {
+  try {
+    return statSync(dir).isDirectory();
+  } catch {
+    return false;
+  }
+}
+function hasFiles(dir) {
+  try {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        if (hasFiles(join2(dir, entry.name)))
+          return true;
+      } else if (entry.isFile()) {
+        return true;
+      }
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+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 AsyncLocalStorage2;
+async function withStatusWriteLock(statusPath, fn, opts = {}) {
+  const lockDir = join3(dirname3(resolve3(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 {
+      mkdirSync3(lockDir);
+      const st = statSync2(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(join3(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 = statSync2(lockDir);
+      if (acquired !== null && current.dev === acquired.dev && current.ino === acquired.ino) {
+        try {
+          unlinkSync2(join3(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> — <reason>"';
+var REQUIRED_FIELDS = [
+  { key: "executeAs", label: "Execute as", code: "execute-as" },
+  { key: "delegation", label: "Delegation", code: "delegation" },
+  { key: "taskCategory", label: "Task category", code: "task-category" }
+];
+function violation2(severity, code, message, fix) {
+  return { ok: false, severity, code, message, fix };
+}
+function parseAssignmentFields(assignmentText) {
+  const fields = {};
+  for (const line of assignmentText.split(/\r?\n/)) {
+    const match = line.match(/^[ \t]*(?:[-*][ \t]+)?\*\*\s*([^*:]+?)\s*\*\*\s*:\s*(.*)$/) ?? line.match(/^[ \t]*(?:[-*][ \t]+)?([A-Za-z][A-Za-z -]*?)\s*:\s*(.*)$/);
+    if (!match)
+      continue;
+    const label = match[1].trim();
+    const value = match[2].trim();
+    const known = REQUIRED_FIELDS.find((f) => f.label === label);
+    if (known) {
+      fields[known.key] = value;
+      continue;
+    }
+    if (label === "Working branch")
+      fields.workingBranch = value;
+    else if (label === "Branch policy")
+      fields.branchPolicy = value;
+  }
+  return fields;
+}
+function requireField(violations, value, label, code) {
+  if (value === undefined) {
+    const v = violation2("high", `assignment.field.missing-${code}`, `missing required Assignment field: ${label}`, `add "**${label}**: <value>" to the Assignment`);
+    v.aliases = [`assignment.presence.missing-${code}`];
+    violations.push(v);
+  } else if (value === "") {
+    const v = violation2("high", `assignment.field.invalid-${code}`, `${label} must be non-empty`, `fill in "**${label}**: <value>"`);
+    v.aliases = [`assignment.presence.missing-${code}`];
+    violations.push(v);
+  }
+}
+function parseWorkingBranchValue(value) {
+  if (value === "")
+    return {};
+  const create = value.match(/^create\s+(\S+)(?:\s+from\s+(\S+))?$/i);
+  if (create)
+    return { createForm: { name: create[1], base: create[2] } };
+  const danglingFrom = value.match(/^create\s+(\S+)\s+from$/i);
+  if (danglingFrom)
+    return { createForm: { name: danglingFrom[1], base: "" } };
+  const missingName = value.match(/^create\s+from\s+(\S+)$/i);
+  if (missingName)
+    return { createForm: { name: "", base: missingName[1] } };
+  return { workingBranch: value.split(/\s+/)[0] };
+}
+function parseAssignmentBranchForms(assignmentText) {
+  const fields = parseAssignmentFields(assignmentText);
+  const forms = {};
+  if (fields.workingBranch !== undefined && fields.workingBranch !== "") {
+    const parsed = parseWorkingBranchValue(fields.workingBranch);
+    if (parsed.createForm !== undefined)
+      forms.createForm = parsed.createForm;
+    else
+      forms.workingBranch = parsed.workingBranch;
+  }
+  if (fields.branchPolicy !== undefined && fields.branchPolicy !== "") {
+    const direct = fields.branchPolicy.match(/^direct\s+on\s+(\S+)/i);
+    if (direct) {
+      const strict = fields.branchPolicy.match(/^direct\s+on\s+(\S+)(?:\s*(?:[—–]|--|-)\s*(.+))?$/);
+      forms.directOn = { branch: direct[1].trim(), reason: strict ? (strict[2] ?? "").trim() : "" };
+    }
+  }
+  return forms;
+}
+function parseBranchPolicyDirectOnBranch(assignmentText) {
+  const directOn = parseAssignmentBranchForms(assignmentText).directOn;
+  return directOn !== undefined && directOn.reason !== "" ? directOn.branch : undefined;
+}
+function isReadOnlyAssignmentRole(roleId) {
+  const role = roleId.trim().toLowerCase();
+  return role === "scout" || role === "explore";
+}
+function validateAssignmentFields(assignmentText, opts = {}) {
+  const violations = [];
+  const fields = parseAssignmentFields(assignmentText);
+  const writable = opts.writable !== false;
+  for (const { key, label, code } of REQUIRED_FIELDS) {
+    requireField(violations, fields[key], label, code);
+  }
+  if (writable) {
+    const workingPresent = fields.workingBranch !== undefined && fields.workingBranch !== "";
+    const policyPresent = fields.branchPolicy !== undefined && fields.branchPolicy !== "";
+    const formCount = Number(workingPresent) + Number(policyPresent);
+    const forms = parseAssignmentBranchForms(assignmentText);
+    if (formCount === 0) {
+      violations.push(violation2("high", "assignment.field.branch-missing", "writable assignment must contain exactly one branch form", `add exactly one of: ${BRANCH_FORMS_HINT}`));
+    } else if (formCount > 1) {
+      violations.push(violation2("high", "assignment.field.branch-multiple", `writable assignment contains ${formCount} branch forms (Working branch + Branch policy) — exactly one required`, `keep exactly one of: ${BRANCH_FORMS_HINT}`));
+    } else if (workingPresent) {
+      const create = forms.createForm;
+      if (create !== undefined && (create.base === undefined || create.base.trim() === "" || create.name.trim() === "")) {
+        violations.push(violation2("high", "assignment.field.branch-missing-base", `create-form Working branch is incomplete: "${fields.workingBranch}" (expected "create <new-branch> from <base>")`, "write both the new branch name and the ancestor branch after `from` (main / existing feature branch / remote-tracking branch / `current`)"));
+      }
+    } else if (policyPresent) {
+      const direct = forms.directOn;
+      if (direct === undefined) {
+        violations.push(violation2("high", "assignment.field.branch-policy-missing-branch", `unparseable Branch policy: "${fields.branchPolicy}" (expected "direct on <branch> — <reason>")`, "start the field with `direct on <branch>`"));
+      } else if (direct.reason === "") {
+        violations.push(violation2("high", "assignment.field.branch-policy-missing-reason", `Branch policy "direct on ${direct.branch}" is missing the reason`, 'append "— <reason>" after the branch name'));
+      }
+    }
+  }
+  return { ok: violations.length === 0, violations };
+}
+function assertDefaultBranchProtected(branch, opts = {}) {
+  const defaultBranches = opts.defaultBranches ?? ["main", "master"];
+  const violations = [];
+  const normalized = branch.trim();
+  if (normalized !== "" && defaultBranches.includes(normalized) && opts.directOnException !== true) {
+    violations.push(violation2("high", "dispatch.default-branch.protected", `writable work on default protected branch "${normalized}" requires an explicit direct-on exception`, `add "Branch policy: direct on ${normalized} — <reason>" to the Assignment, or use a feature branch`));
+  }
+  return { ok: violations.length === 0, violations };
+}
+function executionModeToN(executionMode, opts = {}) {
+  const violations = [];
+  const mode = executionMode.trim().toLowerCase().split(/\s+/)[0] ?? "";
+  let n;
+  if (mode === "") {
+    violations.push(violation2("high", "dispatch.execution-mode.missing", "missing required Assignment field: Execution mode", 'add "**Execution mode**: sdd | inline | targeted"'));
+  } else if (mode === "sdd") {
+    n = 3;
+  } else if (mode === "inline") {
+    n = 1;
+  } else if (mode === "targeted") {
+    const seats = [...new Set((opts.seats ?? []).map((s) => s.trim()).filter((s) => s !== ""))];
+    if (seats.length === 0) {
+      violations.push(violation2("high", "dispatch.execution-mode.missing-seats", 'execution mode "targeted" requires listed reviewer seats', 'add "QC re-review: targeted — reviewers: <role-id>, …" to the Assignment and pass the seats'));
+    } else if (seats.length > 3) {
+      violations.push(violation2("high", "dispatch.execution-mode.too-many-seats", `execution mode "targeted" lists ${seats.length} reviewer seats — at most 3 (targeted re-review seats are the tri seats, N = 1–3)`, "list at most three reviewer seats for the targeted re-review"));
+    } else {
+      n = seats.length;
+    }
+  } else {
+    violations.push(violation2("high", "dispatch.execution-mode.unknown", `unknown execution mode "${executionMode.trim()}" (expected sdd | inline | targeted)`, "fix the Execution mode field"));
+  }
+  return n === undefined ? { ok: false, violations } : { ok: true, violations, n };
+}
+function assertTriIdentity(reviewerRoles) {
+  const tri = ["qc-specialist", "qc-specialist-2", "qc-specialist-3"];
+  const roles = reviewerRoles.map((r) => r.trim().toLowerCase()).filter((r) => r !== "");
+  const valid = roles.length === tri.length && new Set(roles).size === tri.length && roles.every((r) => tri.includes(r));
+  if (valid)
+    return { ok: true, violations: [] };
+  const got = roles.length > 0 ? roles.join(", ") : "(none)";
+  return {
+    ok: false,
+    violations: [
+      violation2("high", "dispatch.tri-identity.invalid", `tri-review initial wave must be exactly qc-specialist / qc-specialist-2 / qc-specialist-3, got: ${got}`, "dispatch qc-specialist, qc-specialist-2 and qc-specialist-3 for the initial wave")
+    ]
+  };
+}
+var DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+var PLAN_STATUSES = ["Todo", "InProgress", "InReview", "Blocked", "Done"];
+var RESIDUAL_DECISIONS = ["defer", "accept", "risk-accepted"];
+var RESIDUAL_LIFECYCLES = ["open", "resolved", "waived", "superseded", "duplicate"];
+function isPlainObject2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function violation3(severity, code, message, fix) {
+  return { ok: false, severity, code, message, fix };
+}
+function 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 isOpenResidual(entry) {
+  const lifecycle = entry.lifecycle;
+  const effective = lifecycle === false || lifecycle === null || lifecycle === undefined ? "open" : lifecycle;
+  return effective === "open";
+}
+function validateNonEmptyString2(violations, value, field, missingCode, invalidCode) {
+  if (value === undefined) {
+    violations.push(violation3("high", missingCode, `missing required field: ${field}`));
+  } else if (typeof value !== "string" || value.trim() === "") {
+    violations.push(violation3("medium", invalidCode, `${field} must be a non-empty string`));
+  }
+}
+function validatePlanRow(row) {
+  const violations = [];
+  if (!isPlainObject2(row)) {
+    return { ok: false, violations: [violation3("high", "status.plan-row.invalid", "plan row must be an object")] };
+  }
+  const { id, plan_id: planId, title, file, status, metadata, execution_lease } = row;
+  if (id === undefined && planId === undefined) {
+    violations.push(violation3("high", "status.plan-row.missing-id", "missing required field: id (or legacy plan_id)"));
+  } else {
+    if (id !== undefined) {
+      validateNonEmptyString2(violations, id, "id", "status.plan-row.missing-id", "status.plan-row.invalid-id");
+    }
+    if (planId !== undefined) {
+      validateNonEmptyString2(violations, planId, "plan_id", "status.plan-row.missing-plan-id", "status.plan-row.invalid-plan-id");
+    }
+    if (id !== undefined && planId !== undefined && id !== planId) {
+      violations.push(violation3("medium", "status.plan-row.dual-id", "row has both id and plan_id with different values — write one canonical key (prefer id)"));
+    }
+  }
+  validateNonEmptyString2(violations, title, "title", "status.plan-row.missing-title", "status.plan-row.invalid-title");
+  validateNonEmptyString2(violations, file, "file", "status.plan-row.missing-file", "status.plan-row.invalid-file");
+  if (status === undefined) {
+    violations.push(violation3("high", "status.plan-row.missing-status", "missing required field: status"));
+  } else if (typeof status !== "string" || !PLAN_STATUSES.includes(status)) {
+    violations.push(violation3("medium", "status.plan-row.invalid-status", `status must be one of ${PLAN_STATUSES.join(" | ")} — got ${JSON.stringify(status)}`));
+  }
+  if (metadata !== undefined && !isPlainObject2(metadata)) {
+    violations.push(violation3("medium", "status.plan-row.invalid-metadata", "metadata must be an object"));
+  }
+  if (execution_lease !== undefined && !isPlainObject2(execution_lease)) {
+    violations.push(violation3("medium", "status.plan-row.invalid-execution-lease", "execution_lease must be an object"));
+  }
+  if (status === "Done" && execution_lease !== undefined) {
+    violations.push(violation3("medium", "status.plan-row.done-with-lease", 'plan status Done must not carry an execution_lease — the Done authority deletes the lease in the same complete-file update as status: "Done" (status-and-residuals.md § Hold, release, and override)', 'delete plans[].execution_lease in the same update that sets status: "Done"'));
+  }
+  return { ok: violations.length === 0, violations };
+}
+function validateResidual(entry) {
+  const violations = [];
+  if (!isPlainObject2(entry)) {
+    return { ok: false, violations: [violation3("high", "status.residual.invalid", "residual entry must be an object")] };
+  }
+  const { id, title, severity, source, scope, decision, owner, target, tracking, detail_doc, lifecycle, closed_at } = entry;
+  validateNonEmptyString2(violations, id, "id", "status.residual.missing-id", "status.residual.invalid-id");
+  validateNonEmptyString2(violations, title, "title", "status.residual.missing-title", "status.residual.invalid-title");
+  validateNonEmptyString2(violations, source, "source", "status.residual.missing-source", "status.residual.invalid-source");
+  validateNonEmptyString2(violations, scope, "scope", "status.residual.missing-scope", "status.residual.invalid-scope");
+  validateNonEmptyString2(violations, owner, "owner", "status.residual.missing-owner", "status.residual.invalid-owner");
+  if (severity === undefined) {
+    violations.push(violation3("high", "status.residual.missing-severity", "missing required field: severity"));
+  } else if (typeof severity !== "string" || !SEVERITY_ORDER.includes(severity) && severity !== "warning") {
+    violations.push(violation3("medium", "status.residual.invalid-severity", `severity must be one of ${SEVERITY_ORDER.join(" | ")} — got ${JSON.stringify(severity)}`));
+  } else if (severity === "warning") {
+    violations.push(violation3("low", "status.residual.legacy-warning", `severity "warning" is legacy — forbidden on new entries; read paths normalize it to "low"`, `use "low" (normalizeSeverity maps 'warning' → 'low')`));
+  }
+  if (decision === undefined) {
+    violations.push(violation3("high", "status.residual.missing-decision", "missing required field: decision"));
+  } else if (typeof decision !== "string" || !RESIDUAL_DECISIONS.includes(decision)) {
+    violations.push(violation3("medium", "status.residual.invalid-decision", `decision must be one of ${RESIDUAL_DECISIONS.join(" | ")} — got ${JSON.stringify(decision)}`));
+  }
+  if (target === undefined) {
+    violations.push(violation3("high", "status.residual.missing-target", "missing required field: target"));
+  } else if (typeof target !== "string" && target !== null) {
+    violations.push(violation3("medium", "status.residual.invalid-target", "target must be a string or null"));
+  }
+  if (tracking === undefined) {
+    violations.push(violation3("high", "status.residual.missing-tracking", "missing required field: tracking"));
+  } else if (typeof tracking !== "string" && tracking !== null) {
+    violations.push(violation3("medium", "status.residual.invalid-tracking", "tracking must be a string or null"));
+  }
+  if (detail_doc !== undefined && typeof detail_doc !== "string" && detail_doc !== null) {
+    violations.push(violation3("medium", "status.residual.invalid-detail-doc", "detail_doc must be a string or null"));
+  }
+  if (closed_at !== undefined && (typeof closed_at !== "string" || !DATE_RE.test(closed_at))) {
+    violations.push(violation3("medium", "status.residual.invalid-closed-at", "closed_at must be YYYY-MM-DD"));
+  }
+  if (lifecycle !== undefined) {
+    if (typeof lifecycle !== "string" || !RESIDUAL_LIFECYCLES.includes(lifecycle)) {
+      violations.push(violation3("medium", "status.residual.invalid-lifecycle", `lifecycle must be one of ${RESIDUAL_LIFECYCLES.join(" | ")} — got ${JSON.stringify(lifecycle)}`));
+    } else if (lifecycle !== "open") {
+      if (closed_at === undefined) {
+        violations.push(violation3("high", "status.residual.closed-missing-closed-at", `lifecycle "${lifecycle}" requires closed_at (YYYY-MM-DD)`, 'set closed_at (e.g. "2026-08-08")'));
+      }
+      if (entry.closure_note === undefined) {
+        violations.push(violation3("medium", "status.residual.closed-missing-closure-note", `lifecycle "${lifecycle}" requires closure_note (what changed; how verified)`, "add closure_note explaining the close"));
+      }
+    }
+  }
+  return { ok: violations.length === 0, violations };
+}
+function validateStatus(docOrPath) {
+  let doc;
+  if (typeof docOrPath === "string") {
+    try {
+      doc = readJson(docOrPath);
+    } catch (error) {
+      return {
+        ok: false,
+        violations: [violation3("high", "status.invalid-json", error.message)]
+      };
+    }
+  } else {
+    doc = docOrPath;
+  }
+  const violations = [];
+  const { version, updated_at, plans, residual_findings, metadata } = doc;
+  if (version === undefined) {
+    violations.push(violation3("high", "status.missing-version", "missing required field: version"));
+  } else if (typeof version !== "number" || !Number.isInteger(version)) {
+    violations.push(violation3("high", "status.invalid-version", "version must be an integer"));
+  } else if (version !== 1) {
+    violations.push(violation3("medium", "status.unsupported-version", `unsupported status.json schema version ${version} — expected 1`));
+  }
+  if (updated_at === undefined) {
+    violations.push(violation3("high", "status.missing-updated-at", "missing required field: updated_at"));
+  } else if (typeof updated_at !== "string" || !DATE_RE.test(updated_at)) {
+    violations.push(violation3("medium", "status.invalid-updated-at", "updated_at must be YYYY-MM-DD"));
+  }
+  if (plans === undefined) {
+    violations.push(violation3("high", "status.missing-plans", "missing required field: plans"));
+  } else if (!Array.isArray(plans)) {
+    violations.push(violation3("high", "status.invalid-plans", "plans must be an array"));
+  } else {
+    for (const row of plans) {
+      violations.push(...validatePlanRow(row).violations);
+    }
+  }
+  if (residual_findings === undefined) {
+    violations.push(violation3("high", "status.missing-residual-findings", "missing required field: residual_findings (root-only canonical)"));
+  } else if (!isPlainObject2(residual_findings)) {
+    violations.push(violation3("high", "status.invalid-residual-findings", "residual_findings must be an object at root"));
+  } else {
+    for (const [planId, list] of Object.entries(residual_findings)) {
+      if (!Array.isArray(list)) {
+        violations.push(violation3("high", "status.residual.invalid-list", `residual_findings["${planId}"] must be an array`));
+      } else if (list.length === 0) {
+        violations.push(violation3("low", "status.residual.empty-key", `residual_findings["${planId}"] is empty — delete the key (no "plan-id": [])`));
+      } else {
+        for (const entry of list) {
+          violations.push(...validateResidual(entry).violations);
+        }
+      }
+    }
+  }
+  if (metadata === undefined) {
+    violations.push(violation3("high", "status.missing-metadata", "missing required field: metadata"));
+  } else if (!isPlainObject2(metadata)) {
+    violations.push(violation3("high", "status.invalid-metadata", "metadata must be an object"));
+  } else if (Object.prototype.hasOwnProperty.call(metadata, "residual_findings")) {
+    violations.push(violation3("medium", "status.dual-write-residuals", "residual_findings must be root-only — metadata.residual_findings is legacy read-only; remove it (no dual-write)", "move entries to root residual_findings and delete metadata.residual_findings"));
+  }
+  return { ok: violations.length === 0, violations };
+}
+async function archiveResiduals(planId, harnessDir) {
+  const dir = harnessDir !== undefined ? resolve4(harnessDir) : resolveHarnessDir();
+  if (dir === null) {
+    throw new Error(`harness dir not found from ${process.cwd()} — pass harnessDir or set MSTAR_HARNESS_DIR`);
+  }
+  assertSafePathComponent(planId, "planId");
+  const statusPath = join4(dir, "status.json");
+  if (!existsSync2(statusPath)) {
+    throw new Error(`status file not found: ${statusPath}`);
+  }
+  return withStatusWriteLock(statusPath, () => {
+    const doc = readJson(statusPath);
+    if (!isPlainObject2(doc.residual_findings)) {
+      throw new Error(`status.json residual_findings must be an object: ${statusPath}`);
+    }
+    const open = doc.residual_findings[planId];
+    const archivePath = join4(dir, "archived", "residuals", `${planId}.json`);
+    if (!Array.isArray(open) || open.length === 0) {
+      return { planId, archived: 0, archivePath };
+    }
+    const archive = readJson(archivePath);
+    const existing = Array.isArray(archive.entries) ? archive.entries : [];
+    const existingIds = new Set(existing.map((e) => isPlainObject2(e) && typeof e.id === "string" ? e.id : undefined).filter((id) => id !== undefined));
+    const today = todayString();
+    const moved = open.filter((entry) => {
+      if (!isPlainObject2(entry) || typeof entry.id !== "string")
+        return true;
+      return !existingIds.has(entry.id);
+    }).map((entry) => ({ ...entry, archived_at: today }));
+    if (moved.length > 0) {
+      writeJson(archivePath, { plan_id: planId, schema_version: 1, entries: [...existing, ...moved] });
+    }
+    delete doc.residual_findings[planId];
+    doc.updated_at = today;
+    writeJson(statusPath, doc);
+    return { planId, archived: moved.length, archivePath };
+  });
+}
+var DEFAULT_PROBE_TIMEOUT_MS = 1e4;
+function probeTimeoutMs() {
+  const raw = process.env.MSTAR_GIT_PROBE_TIMEOUT_MS;
+  if (raw === undefined || raw.trim() === "")
+    return DEFAULT_PROBE_TIMEOUT_MS;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_PROBE_TIMEOUT_MS;
+}
+function violation4(severity, code, message, fix) {
+  return { ok: false, severity, code, message, fix };
+}
+function gate(violations) {
+  return { ok: violations.length === 0, violations };
+}
+function probeBranch(worktreePath, opts) {
+  const precomputed = opts.branchOf?.(worktreePath);
+  if (precomputed !== undefined)
+    return { branch: precomputed };
+  const timeout = opts.timeoutMs ?? probeTimeoutMs();
+  try {
+    const stdout = execFileSync(opts.gitPath ?? "git", ["-C", worktreePath, "branch", "--show-current"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout
+    });
+    const branch = stdout.trim();
+    if (branch === "")
+      return { error: `no branch checked out (detached HEAD?) at "${worktreePath}"` };
+    return { branch };
+  } catch (err) {
+    const e = err;
+    if (e.killed === true || e.signal !== undefined) {
+      return { error: `git probe timed out after ${timeout}ms (killed by ${e.signal ?? "SIGTERM"})` };
+    }
+    const detail = (e.stderr !== undefined ? e.stderr.toString().trim() : "") || e.message || "git probe failed";
+    return { error: detail };
+  }
+}
+function l1PreDispatchCheck(input, opts = {}) {
+  const violations = [];
+  const { controlWorktreePath, leaseWorktreePath, leaseWorkingBranch, planId } = input;
+  if (controlWorktreePath.trim() === "") {
+    violations.push(violation4("high", "worktree.l1.control-missing", "metadata.control_worktree_path is not recorded — the L1 control worktree (integration-branch checkout) must be recorded in status.json before writable dispatch", "record the control worktree path in status.json metadata.control_worktree_path"));
+  }
+  if (leaseWorktreePath.trim() === "") {
+    violations.push(violation4("high", "worktree.l1.lease-missing", `execution_lease.worktree_path is empty for plan "${planId}" — no verified execution_lease to dispatch against`, "claim the execution_lease with an absolute feature worktree path before dispatch"));
+  }
+  if (leaseWorkingBranch.trim() === "") {
+    violations.push(violation4("high", "worktree.l1.lease-branch-missing", `execution_lease.working_branch is empty for plan "${planId}"`, "record the lease working_branch before dispatch"));
+  }
+  if (controlWorktreePath !== "" && leaseWorktreePath !== "" && resolve5(controlWorktreePath) === resolve5(leaseWorktreePath)) {
+    violations.push(violation4("critical", "worktree.l1.lease-equals-control", `execution_lease.worktree_path "${leaseWorktreePath}" equals metadata.control_worktree_path — the feature worktree MUST differ from the control worktree (L1 isolation; product edits never land in the control checkout)`, "use a distinct feature worktree for the plan (git worktree add <path> <branch>) and update the lease"));
+  }
+  if (leaseWorktreePath !== "" && !existsSync3(leaseWorktreePath)) {
+    violations.push(violation4("high", "worktree.l1.feature-missing", `feature worktree directory "${leaseWorktreePath}" does not exist for plan "${planId}"`, `create it before dispatch: git worktree add ${leaseWorktreePath} <working-branch>`));
+  } else if (leaseWorktreePath !== "" && leaseWorkingBranch !== "") {
+    const probe = probeBranch(leaseWorktreePath, opts);
+    if ("error" in probe) {
+      violations.push(violation4("high", "worktree.l1.branch-probe-failed", `cannot probe branch at "${leaseWorktreePath}" for plan "${planId}": ${probe.error}`, "verify the path is a git worktree checkout on the lease working branch (not detached)"));
+    } else if (probe.branch !== leaseWorkingBranch) {
+      violations.push(violation4("high", "worktree.l1.branch-mismatch", `feature worktree "${leaseWorktreePath}" is on branch "${probe.branch}", expected execution_lease.working_branch "${leaseWorkingBranch}" (plan "${planId}")`, `checkout ${leaseWorkingBranch} in the feature worktree`));
+    }
+  }
+  return gate(violations);
+}
+function l2PreDispatchCheck(input, opts = {}) {
+  const violations = [];
+  const tracks = input.tracks ?? [];
+  const seenPaths = new Set;
+  if (tracks.length < 1) {
+    violations.push(violation4("high", "worktree.l2.no-tracks", "no parallel writable tracks — the L2 pre-dispatch checklist requires at least one track with an absolute worktreePath and Working branch", "pass each track's absolute Worktree path and PM-approved Working branch"));
+  }
+  tracks.forEach((track, index) => {
+    if (track.worktreePath.trim() === "" || track.workingBranch.trim() === "") {
+      violations.push(violation4("high", "worktree.l2.track-invalid", `track ${index + 1} is missing worktreePath and/or workingBranch`, "fill both fields for every track"));
+      return;
+    }
+    if (!isAbsolute3(track.worktreePath)) {
+      violations.push(violation4("high", "worktree.l2.track-path-relative", `track ${index + 1} worktreePath "${track.worktreePath}" is not an absolute path — L2 tracks MUST use absolute worktree checkout paths (consistent with the lease validator's absolute worktree_path enforcement)`, `use an absolute path for track ${index + 1} (e.g. /Users/<you>/worktrees/<branch>)`));
+      return;
+    }
+    const normalized = resolve5(track.worktreePath);
+    if (seenPaths.has(normalized)) {
+      violations.push(violation4("high", "worktree.l2.track-path-collision", `duplicate worktreePath "${track.worktreePath}" across parallel tracks — L2 parallel-writable isolation requires a distinct absolute Worktree path per track (N parallel invokes ≠ isolation)`, "give every parallel track its own git worktree checkout"));
+      return;
+    }
+    seenPaths.add(normalized);
+    if (!existsSync3(track.worktreePath)) {
+      violations.push(violation4("high", "worktree.l2.track-missing", `track worktree directory "${track.worktreePath}" does not exist`, `create it before dispatch: git worktree add ${track.worktreePath} ${track.workingBranch}`));
+      return;
+    }
+    const probe = probeBranch(track.worktreePath, opts);
+    if ("error" in probe) {
+      violations.push(violation4("high", "worktree.l2.branch-probe-failed", `cannot probe branch at "${track.worktreePath}": ${probe.error}`, "verify the path is a git worktree checkout on its Working branch (not detached)"));
+    } else if (probe.branch !== track.workingBranch) {
+      violations.push(violation4("high", "worktree.l2.branch-mismatch", `track worktree "${track.worktreePath}" is on branch "${probe.branch}", expected Working branch "${track.workingBranch}"`, `checkout ${track.workingBranch} in that worktree`));
+    }
+  });
+  return gate(violations);
+}
+class SddScriptError extends Error {
+  exitCode;
+  constructor(message, exitCode) {
+    super(message);
+    this.name = "SddScriptError";
+    this.exitCode = exitCode;
+  }
+}
+function isDirectory2(dir) {
+  try {
+    return statSync3(dir).isDirectory();
+  } catch {
+    return false;
+  }
+}
+function isFile(file) {
+  try {
+    return statSync3(file).isFile();
+  } catch {
+    return false;
+  }
+}
+var GIT_CAPTURE_MAX_BYTES = 64 * 1024 * 1024;
+function gitOut(cwd, args) {
+  try {
+    return execFileSync2("git", args, {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+      maxBuffer: GIT_CAPTURE_MAX_BYTES
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+function probeHarnessWithStatus(root) {
+  if (isFile(join5(root, ".mstar", "status.json")))
+    return join5(root, ".mstar");
+  if (isFile(join5(root, ".agents", "status.json")))
+    return join5(root, ".agents");
+  return null;
+}
+function isLinkedWorktree(root) {
+  const gitDirRaw = gitOut(root, ["rev-parse", "--git-dir"]);
+  const commonRaw = gitOut(root, ["rev-parse", "--git-common-dir"]);
+  if (gitDirRaw === null || commonRaw === null)
+    return false;
+  const gitDir = isAbsolute4(gitDirRaw) ? gitDirRaw : join5(root, gitDirRaw);
+  const common2 = isAbsolute4(commonRaw) ? commonRaw : join5(root, commonRaw);
+  if (gitDir.includes("/.git/worktrees/") || gitDir.includes("/worktrees/"))
+    return true;
+  try {
+    const gdParent = realpathSync(dirname4(gitDir));
+    const cmAbs = realpathSync(common2);
+    return join5(gdParent, basename3(gitDir)) !== cmAbs && gitDir !== cmAbs;
+  } catch {
+    return false;
+  }
+}
+function sddWorkspace(planId, opts = {}) {
+  if (!planId) {
+    throw new SddScriptError(`usage: mstar sdd workspace PLAN_ID [CONTROL_ROOT]
+` + "  Set MSTAR_CONTROL_ROOT=<control_worktree_path> when running from a feature worktree.", 2);
+  }
+  const cwd = opts.cwd ?? process.cwd();
+  const controlRoot = opts.controlRoot ?? (process.env.MSTAR_CONTROL_ROOT || undefined);
+  let root;
+  if (controlRoot) {
+    if (!isDirectory2(controlRoot)) {
+      throw new SddScriptError(`mstar sdd workspace: CONTROL_ROOT / MSTAR_CONTROL_ROOT is not a directory: ${controlRoot}`, 1);
+    }
+    root = realpathSync(controlRoot);
+  } else {
+    const topLevel = gitOut(cwd, ["rev-parse", "--show-toplevel"]);
+    root = realpathSync(topLevel ?? cwd);
+  }
+  if (!controlRoot && isLinkedWorktree(root)) {
+    throw new SddScriptError(`mstar sdd workspace: linked worktree at ${root} has no {HARNESS_DIR}/status.json (default gitignore).
+` + `  Refusing to create a second SDD tree under the feature checkout.
+` + `  Re-run with MSTAR_CONTROL_ROOT=<control_worktree_path> or: mstar sdd workspace ${planId} <control_worktree_path>
+` + `  See mstar-branch-worktree «Harness path SSOT under default gitignore».`, 1);
+  }
+  const harnessOverride = opts.harnessDir ?? (process.env.MSTAR_HARNESS_DIR || undefined);
+  let harnessDir;
+  if (harnessOverride) {
+    harnessDir = resolve6(root, harnessOverride);
+  } else {
+    const probed = probeHarnessWithStatus(root);
+    if (probed) {
+      harnessDir = probed;
+    } else if (isDirectory2(join5(root, ".mstar"))) {
+      harnessDir = join5(root, ".mstar");
+    } else if (isDirectory2(join5(root, ".agents"))) {
+      harnessDir = join5(root, ".agents");
+    } else {
+      harnessDir = join5(root, ".mstar");
+    }
+  }
+  const sddDir = resolveSddDir(harnessDir, planId);
+  mkdirSync4(sddDir, { recursive: true });
+  writeFileSync3(join5(sddDir, ".gitignore"), `*
+`);
+  return realpathSync(sddDir);
+}
+function taskBrief(planFile, taskN, outFile, opts = {}) {
+  if (!planFile || !Number.isInteger(taskN) || taskN < 1) {
+    throw new SddScriptError("usage: mstar sdd task-brief PLAN_FILE TASK_NUMBER [OUTFILE]", 2);
+  }
+  let content;
+  try {
+    content = readFileSync4(planFile, "utf8");
+  } catch {
+    throw new SddScriptError(`no such plan file: ${planFile}`, 2);
+  }
+  let out;
+  if (outFile) {
+    out = outFile;
+  } else {
+    const sddDir = opts.sddDir ?? process.env.SDD_DIR;
+    if (!sddDir) {
+      throw new SddScriptError("mstar sdd task-brief: set SDD_DIR or pass OUTFILE (run mstar sdd workspace PLAN_ID first)", 2);
+    }
+    mkdirSync4(sddDir, { recursive: true });
+    out = join5(sddDir, `task-${taskN}-brief.md`);
+  }
+  const records = content.endsWith(`
+`) ? content.split(`
+`).slice(0, -1) : content.split(`
+`);
+  const headingRe = /^#+[ \t]+Task[ \t]+[0-9]+/;
+  const targetRe = new RegExp(`^#+[ 	]+Task[ 	]+${taskN}([^0-9]|$)`);
+  let infence = false;
+  let intask = false;
+  const printed = [];
+  for (const line of records) {
+    if (/^```/.test(line))
+      infence = !infence;
+    if (!infence && headingRe.test(line))
+      intask = targetRe.test(line);
+    if (intask)
+      printed.push(line);
+  }
+  const output = printed.length > 0 ? `${printed.join(`
+`)}
+` : "";
+  writeFileSync3(out, output);
+  if (printed.length === 0) {
+    throw new SddScriptError(`task ${taskN} not found in ${planFile} (no heading matching Task ${taskN})`, 3);
+  }
+  return out;
+}
+function reviewPackage(base, head, outFile, opts = {}) {
+  if (!base || !head) {
+    throw new SddScriptError("usage: mstar sdd review-package BASE HEAD [OUTFILE]", 2);
+  }
+  const cwd = opts.cwd ?? process.cwd();
+  const verifyRef = (ref, what) => {
+    try {
+      execFileSync2("git", ["rev-parse", "--verify", "--quiet", ref], { cwd, stdio: ["ignore", "pipe", "pipe"] });
+    } catch {
+      throw new SddScriptError(`bad ${what}: ${ref}`, 2);
+    }
+  };
+  verifyRef(base, "BASE");
+  verifyRef(head, "HEAD");
+  let out;
+  if (outFile) {
+    out = outFile;
+  } else {
+    const sddDir = opts.sddDir ?? process.env.SDD_DIR;
+    if (!sddDir) {
+      throw new SddScriptError("mstar sdd review-package: set SDD_DIR or pass OUTFILE", 2);
+    }
+    mkdirSync4(sddDir, { recursive: true });
+    const shortBase = gitOut(cwd, ["rev-parse", "--short", base]) ?? base;
+    const shortHead = gitOut(cwd, ["rev-parse", "--short", head]) ?? head;
+    out = join5(sddDir, `review-${shortBase}..${shortHead}.diff`);
+  }
+  const run = (args) => execFileSync2("git", args, { cwd, maxBuffer: GIT_CAPTURE_MAX_BYTES });
+  const parts = [
+    Buffer.from(`# Review package: ${base}..${head}
+
+## Commits
+`),
+    run(["log", "--oneline", `${base}..${head}`]),
+    Buffer.from(`
+## Files changed
+`),
+    run(["diff", "--stat", `${base}..${head}`]),
+    Buffer.from(`
+## Diff
+`),
+    run(["diff", "-U10", `${base}..${head}`])
+  ];
+  writeFileSync3(out, Buffer.concat(parts));
+  return out;
+}
+var COMPASS_STATUSES = ["active", "locked", "completed"];
+var DATE_RE2 = /^\d{4}-\d{2}-\d{2}$/;
+var PLAN_STATUS_DONE = "Done";
+function typeName(value) {
+  if (value === null)
+    return "null";
+  if (Array.isArray(value))
+    return "array";
+  return typeof value;
+}
+function validateCompassShape(doc) {
+  const issues = [];
+  const expectString = (key, opts = {}) => {
+    const value = doc[key];
+    if (typeof value !== "string") {
+      issues.push({ path: [key], message: `expected string, received ${typeName(value)}` });
+      return;
+    }
+    if (opts.min !== undefined && value.length < opts.min) {
+      issues.push({ path: [key], message: `string must contain at least ${opts.min} character(s)` });
+      return;
+    }
+    if (opts.regex !== undefined && !opts.regex.test(value)) {
+      issues.push({ path: [key], message: `string must match ${opts.regex}` });
+    }
+  };
+  expectString("iteration_id", { min: 1 });
+  expectString("start_date", { regex: DATE_RE2 });
+  const status = doc.status;
+  if (typeof status !== "string" || !COMPASS_STATUSES.includes(status)) {
+    issues.push({
+      path: ["status"],
+      message: `expected one of ${COMPASS_STATUSES.map((s) => `'${s}'`).join(" | ")}, received ${typeName(status)}`
+    });
+  }
+  expectString("iteration_base_branch", { min: 1 });
+  expectString("target_branch", { min: 1 });
+  const plans = doc.plans;
+  if (plans !== undefined) {
+    if (!Array.isArray(plans)) {
+      issues.push({ path: ["plans"], message: `expected array, received ${typeName(plans)}` });
+    } else {
+      plans.forEach((entry, index) => {
+        if (typeof entry !== "string") {
+          issues.push({ path: ["plans", index], message: `expected string, received ${typeName(entry)}` });
+        } else if (entry.length < 1) {
+          issues.push({ path: ["plans", index], message: "string must contain at least 1 character(s)" });
+        }
+      });
+    }
+  }
+  const end_date = doc.end_date;
+  if (end_date !== undefined) {
+    if (typeof end_date !== "string") {
+      issues.push({ path: ["end_date"], message: `expected string, received ${typeName(end_date)}` });
+    } else if (!DATE_RE2.test(end_date)) {
+      issues.push({ path: ["end_date"], message: `string must match ${DATE_RE2}` });
+    }
+  }
+  if (issues.length > 0)
+    return { ok: false, issues };
+  return {
+    ok: true,
+    data: {
+      iteration_id: doc.iteration_id,
+      start_date: doc.start_date,
+      status,
+      iteration_base_branch: doc.iteration_base_branch,
+      target_branch: doc.target_branch,
+      ...plans !== undefined ? { plans } : {},
+      ...end_date !== undefined ? { end_date } : {}
+    }
+  };
+}
+function violation5(severity, code, message, fix) {
+  return { ok: false, severity, code, message, fix };
+}
+function isPlainObject3(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function validateCompassFrontmatter(doc) {
+  if (!isPlainObject3(doc)) {
+    return {
+      ok: false,
+      violations: [
+        violation5("medium", "COMPASS_INVALID_FIELD", "Compass frontmatter must be a YAML object with iteration_id / start_date / status / iteration_base_branch / target_branch (template: mstar-iteration §1.3)", "Fix the frontmatter of {ITERATION_DIR}/<iteration-id>/delivery-compass.md")
+      ]
+    };
+  }
+  const parsed = validateCompassShape(doc);
+  if (!parsed.ok) {
+    return {
+      ok: false,
+      violations: parsed.issues.map((issue) => {
+        const field = issue.path.join(".") || "(root)";
+        return violation5("medium", "COMPASS_INVALID_FIELD", `Compass frontmatter field '${field}' is invalid: ${issue.message}`, `Fix '${field}' in {ITERATION_DIR}/<iteration-id>/delivery-compass.md frontmatter (template: mstar-iteration §1.3)`);
+      })
+    };
+  }
+  const violations = [];
+  const { status, end_date } = parsed.data;
+  if (status === "completed" && end_date === undefined) {
+    violations.push(violation5("high", "COMPASS_END_DATE_REQUIRED", "Compass frontmatter status is 'completed' but end_date is missing — end_date is required at iteration-close (mstar-iteration §3.4, template Fields guide)", "Add `end_date: YYYY-MM-DD` to the frontmatter"));
+  }
+  if (status !== "completed" && end_date !== undefined) {
+    violations.push(violation5("medium", "COMPASS_END_DATE_NOT_ALLOWED", `Compass frontmatter sets end_date while status is '${status}' — end_date is only written at iteration-close (mstar-iteration §3.4)`, "Remove end_date until iteration-close"));
+  }
+  return { ok: violations.length === 0, violations };
+}
+function registeredPlanIds(compassDoc) {
+  if (!Array.isArray(compassDoc.plans))
+    return [];
+  return compassDoc.plans.filter((plan) => typeof plan === "string" && plan.length > 0);
+}
+function findPlanRow(statusDoc, planId) {
+  if (!Array.isArray(statusDoc.plans))
+    return null;
+  for (const row of statusDoc.plans) {
+    if (!isPlainObject3(row))
+      continue;
+    const rowId = typeof row.id === "string" ? row.id : typeof row.plan_id === "string" ? row.plan_id : null;
+    if (rowId === planId)
+      return row;
+  }
+  return null;
+}
+function entryPlansAllDone(statusDoc, registered) {
+  const violations = [];
+  if (registered.length === 0) {
+    violations.push(violation5("medium", "COMPASS_NO_PLANS", "Compass frontmatter registers no plans — the all-plans-Done transition cannot be verified (mstar-iteration §1.3 / Phase transition gates)", "List the iteration's plan ids in the compass frontmatter `plans`"));
+    return violations;
+  }
+  for (const planId of registered) {
+    const row = findPlanRow(statusDoc, planId);
+    if (row === null) {
+      violations.push(violation5("high", "PLAN_NOT_IN_STATUS", `Plan '${planId}' is registered in the compass frontmatter but has no row in status.json plans[] (mstar-iteration §3.1 entry item 1)`, "Add the plan row to {HARNESS_DIR}/status.json"));
+      continue;
+    }
+    if (row.status !== PLAN_STATUS_DONE) {
+      violations.push(violation5("high", "PLAN_NOT_DONE", `Plan '${planId}' status is ${JSON.stringify(row.status)} in status.json — all compass-registered plans must be 'Done' before iteration-close (mstar-iteration §3.1 entry item 1)`));
+    }
+  }
+  return violations;
+}
+function entryResidualsOpen(statusDoc, planId) {
+  const violations = [];
+  const residualRoot = statusDoc.residual_findings;
+  if (residualRoot === undefined || residualRoot === null)
+    return violations;
+  if (!isPlainObject3(residualRoot)) {
+    violations.push(violation5("medium", "RESIDUAL_MALFORMED", "status.json residual_findings must be a plan-id → entries object (mstar-iteration §3.1 entry item 2)"));
+    return violations;
+  }
+  const entries = residualRoot[planId];
+  if (entries === undefined)
+    return violations;
+  if (!Array.isArray(entries)) {
+    violations.push(violation5("medium", "RESIDUAL_MALFORMED", `status.json residual_findings['${planId}'] must be an array of residual entries (mstar-iteration §3.1 entry item 2)`));
+    return violations;
+  }
+  const openIds = [];
+  for (const entry of entries) {
+    if (!isPlainObject3(entry) || !isOpenResidual(entry))
+      continue;
+    const isBlockerDefer = entry.decision === "defer" && typeof entry.target === "string" && entry.target.trim() !== "";
+    if (isBlockerDefer)
+      continue;
+    openIds.push(typeof entry.id === "string" ? entry.id : "<unnamed>");
+  }
+  if (openIds.length > 0) {
+    violations.push(violation5("high", "OPEN_RESIDUALS", `Plan '${planId}' has ${openIds.length} open residual finding(s) not exempted as blocker-defers (${openIds.join(", ")}) — residuals must be closed/archived before iteration-close; only zero-residual blocker-defers (decision: defer + target) may stay open (mstar-iteration §3.1 entry item 2)`, "Close or archive the open residuals, or convert them into blocker-defers (decision: defer + non-empty target) per mstar-plan-artifacts Findings cleanup modes"));
+  }
+  return violations;
+}
+function entryFrontmatterComplete(compassDoc) {
+  return validateCompassFrontmatter(compassDoc).violations;
+}
+function exitFrontmatterClosed(compassDoc) {
+  const violations = [];
+  if (compassDoc.status !== "completed") {
+    violations.push(violation5("high", "EXIT_STATUS_NOT_COMPLETED", `Compass frontmatter status must be 'completed' at close exit — current: ${JSON.stringify(compassDoc.status)} (mstar-iteration §3.4 / §3.5 exit item 4)`));
+  }
+  const endDate = compassDoc.end_date;
+  if (typeof endDate !== "string" || !DATE_RE2.test(endDate)) {
+    violations.push(violation5("high", "EXIT_END_DATE_REQUIRED", "Compass frontmatter end_date (YYYY-MM-DD) is required when closing (mstar-iteration §3.4 / §3.5 exit item 4)"));
+  }
+  return violations;
+}
+function exitBranchCheck(opts) {
+  const violations = [];
+  const { currentBranch, specIntegrationBranch } = opts;
+  if (currentBranch === undefined || specIntegrationBranch === undefined) {
+    violations.push(violation5("medium", "EXIT_BRANCH_UNVERIFIABLE", "Cannot verify the current branch is spec_integration_branch — missing currentBranch / specIntegrationBranch probe inputs (mstar-iteration §3.5 exit item 5)"));
+  } else if (currentBranch !== specIntegrationBranch) {
+    violations.push(violation5("high", "EXIT_BRANCH_MISMATCH", `Current branch '${currentBranch}' is not the spec_integration_branch '${specIntegrationBranch}' (mstar-iteration §3.5 exit item 5)`));
+  }
+  return violations;
+}
+function exitPrBaseCheck(compassDoc, opts) {
+  const violations = [];
+  const target = compassDoc.target_branch;
+  const { prBaseBranch } = opts;
+  if (prBaseBranch === undefined) {
+    violations.push(violation5("medium", "EXIT_PR_BASE_UNVERIFIABLE", "Cannot verify the PR base — missing prBaseBranch probe input (mstar-iteration §3.5 exit item 6)"));
+  } else if (typeof target !== "string" || prBaseBranch !== target) {
+    violations.push(violation5("high", "EXIT_PR_BASE_MISMATCH", `PR base '${prBaseBranch}' must equal the compass target_branch '${String(target)}' — not an undocumented branch (mstar-iteration §3.5 exit item 6)`));
+  }
+  return violations;
+}
+function evaluatePhaseGate(statusDoc, compassDoc, opts = {}) {
+  const registered = registeredPlanIds(compassDoc);
+  const entryViolations = [
+    ...entryPlansAllDone(statusDoc, registered),
+    ...registered.flatMap((planId) => entryResidualsOpen(statusDoc, planId)),
+    ...entryFrontmatterComplete(compassDoc)
+  ];
+  const exitViolations = [
+    ...exitFrontmatterClosed(compassDoc),
+    ...exitBranchCheck(opts),
+    ...exitPrBaseCheck(compassDoc, opts)
+  ];
+  const allPlansDone = registered.length > 0 && registered.every((planId) => {
+    const row = findPlanRow(statusDoc, planId);
+    return row !== null && row.status === PLAN_STATUS_DONE;
+  });
+  const entry = { ok: entryViolations.length === 0, violations: entryViolations };
+  const exit = { ok: exitViolations.length === 0, violations: exitViolations };
+  let transition;
+  if (!allPlansDone)
+    transition = "phase-2-execute";
+  else if (entry.ok && exit.ok)
+    transition = "phase-4-pr-delivery";
+  else
+    transition = "phase-3-close";
+  const gateBlocking = allPlansDone ? [...entryViolations, ...exitViolations] : [];
+  return {
+    transition,
+    allPlansDone,
+    entry,
+    exit,
+    ok: gateBlocking.length === 0,
+    violations: gateBlocking
+  };
+}
+function pushCadenceProbe(ciRunning, reviewWaveActive) {
+  const violations = [];
+  if (ciRunning) {
+    violations.push(violation5("high", "PUSH_BLOCKED_CI", "CI checks are still queued/in_progress on the current head — do not push until the wave completes (mstar-iteration §5.1a push gate 1)", "Wait for CI to settle, then push once with the whole local batch"));
+  }
+  if (reviewWaveActive) {
+    violations.push(violation5("high", "PUSH_BLOCKED_REVIEW_WAVE", "An AI/bot review wave is still running on the current head — do not push until it settles (mstar-iteration §5.1a push gate 2)", "Wait for the review wave, then push once"));
+  }
+  return { ok: violations.length === 0, violations };
+}
+function violation6(severity, code, message, fix) {
+  return { ok: false, severity, code, message, fix };
+}
+var RAW_GROUP = "__raw";
+var isMap = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+function parseScalar(raw) {
+  const trimmed = raw.trim();
+  const quoted = /^"([^"]*)"$/.exec(trimmed) ?? /^'([^']*)'$/.exec(trimmed);
+  if (quoted)
+    return quoted[1];
+  const cut = trimmed.split(/\s+#/)[0].trim();
+  if (/^-?\d+(?:\.\d+)?$/.test(cut))
+    return Number(cut);
+  if (/^(?:true|false)$/.test(cut))
+    return cut === "true";
+  return cut;
+}
+function parseMapBlock(lines, start, indent) {
+  const map = {};
+  let i = start;
+  while (i < lines.length && lines[i].indent === indent) {
+    const match = /^([^:]+):(.*)$/.exec(lines[i].text);
+    if (match === null) {
+      i++;
+      continue;
+    }
+    const key = parseScalar(match[1].trim()).toString();
+    const rest = match[2].trim();
+    if (rest === "") {
+      const nested = i + 1 < lines.length && lines[i + 1].indent > indent;
+      if (nested) {
+        const child = parseBlock(lines, i + 1, lines[i + 1].indent);
+        map[key] = child.value;
+        i = child.next;
+      } else {
+        map[key] = "";
+        i++;
+      }
+    } else {
+      map[key] = parseScalar(rest);
+      i++;
+    }
+  }
+  return { value: map, next: i };
+}
+function parseListBlock(lines, start, indent) {
+  const list = [];
+  let i = start;
+  while (i < lines.length && lines[i].indent === indent && lines[i].text.startsWith("-")) {
+    const rest = lines[i].text.slice(1).trim();
+    const match = /^([^:]+):(.*)$/.exec(rest);
+    if (match !== null && match[2].trim() === "" && i + 1 < lines.length && lines[i + 1].indent > indent) {
+      const child = parseBlock(lines, i + 1, lines[i + 1].indent);
+      list.push({ [parseScalar(match[1].trim()).toString()]: child.value });
+      i = child.next;
+    } else if (match !== null) {
+      list.push({ [parseScalar(match[1].trim()).toString()]: parseScalar(match[2].trim()) });
+      i++;
+    } else {
+      list.push(parseScalar(rest));
+      i++;
+    }
+  }
+  return { value: list, next: i };
+}
+function parseBlock(lines, start, indent) {
+  if (lines[start] !== undefined && lines[start].text.startsWith("-"))
+    return parseListBlock(lines, start, indent);
+  return parseMapBlock(lines, start, indent);
+}
+function parseDesignFrontmatter(frontmatterText) {
+  const body = frontmatterText.replace(/^\uFEFF/, "");
+  const lines = body.split(/\r?\n/);
+  if (lines.length === 0 || !lines[0].trim().startsWith("---"))
+    return null;
+  const inner = [];
+  for (let i = 1;i < lines.length; i++) {
+    const trimmed = lines[i].trim();
+    if (trimmed === "---")
+      break;
+    if (trimmed === "" || trimmed.startsWith("#"))
+      continue;
+    const indent = lines[i].match(/^ */)[0].length;
+    inner.push({ indent, text: lines[i].slice(indent) });
+  }
+  if (inner.length === 0)
+    return null;
+  const top = parseBlock(inner, 0, inner[0].indent);
+  if (!isMap(top.value))
+    return null;
+  const fm = { colors: {}, typography: {}, spacing: {}, rounded: {}, components: {} };
+  for (const [key, value] of Object.entries(top.value)) {
+    if (key === "version" || key === "name" || key === "description") {
+      if (typeof value === "string")
+        fm[key] = value;
+    } else if (key === "colors" || key === "typography" || key === "spacing" || key === "rounded" || key === "components") {
+      fm[key] = isMap(value) ? value : { [RAW_GROUP]: value };
+    }
+  }
+  return fm;
+}
+var HEX_RE = /^#(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+var OKLCH_RE = /^oklch\([^)]*\)$/i;
+var PX_RE = /^-?\d+(?:\.\d+)?px$/;
+var PLACEHOLDER_RE = /^\[.*\]$/;
+var TYPOGRAPHY_PROPS = ["fontFamily", "fontSize", "fontWeight", "lineHeight", "letterSpacing"];
+var REF_RE = /^\{([a-z]+)\.([^}]+)\}$/;
+var REF_GROUPS = ["colors", "typography", "rounded"];
+var isPlaceholder = (value) => PLACEHOLDER_RE.test(value);
+function validateDesignTokenFrontmatter(frontmatterText) {
+  const violations = [];
+  const fm = parseDesignFrontmatter(frontmatterText);
+  if (fm === null) {
+    violations.push(violation6("medium", "design-md.tokens.missing-frontmatter", "no `---` YAML frontmatter block found — DESIGN.md must open with a fenced frontmatter holding the token SSOT (design-md-spec §1.5)", "add a `---` fenced frontmatter with version, name, description, and the colors/typography/spacing/rounded groups"));
+    return { ok: false, violations };
+  }
+  const groupEntries = (group) => {
+    const value = fm[group];
+    if (!isMap(value) || RAW_GROUP in value)
+      return [];
+    return Object.entries(value);
+  };
+  const groupIsMap = (group) => {
+    const value = fm[group];
+    return isMap(value) && !(RAW_GROUP in value);
+  };
+  for (const group of ["colors", "typography", "spacing", "rounded"]) {
+    if (!isMap(fm[group])) {
+      violations.push(violation6("medium", "design-md.tokens.group-not-map", `token group "${group}" must be a YAML map, not a scalar (design-md-spec §1.5)`, `rewrite \`${group}\` as a nested map`));
+    } else if (!groupIsMap(group)) {
+      violations.push(violation6("medium", "design-md.tokens.group-not-map", `token group "${group}" must be a YAML map, not a scalar (design-md-spec §1.5)`, `rewrite \`${group}\` as a nested map`));
+    } else if (groupEntries(group).length === 0) {
+      violations.push(violation6("medium", "design-md.tokens.missing-group", `missing required token group "${group}" — colors/typography/spacing/rounded are required by the frontmatter SSOT (design-md-spec §1.5)`, `add an active \`${group}:\` block with concrete token values`));
+    }
+  }
+  if (!isMap(fm.components) || !groupIsMap("components")) {
+    violations.push(violation6("medium", "design-md.tokens.group-not-map", `token group "components" must be a YAML map, not a scalar (design-md-spec §1.5)`, `rewrite \`components\` as a nested map`));
+  }
+  const placeholder = (group, name, value) => violations.push(violation6("low", "design-md.tokens.placeholder", `token "${group}.${name}" uses a "[...]" template value — placeholders never count as concrete tokens (completeness-checklist § How to use item 5)`, `replace \`${value}\` with a concrete value`));
+  for (const [name, value] of groupEntries("colors")) {
+    if (typeof value !== "string") {
+      violations.push(violation6("medium", "design-md.tokens.color-format", `color "${name}" must be a string value (design-md-spec §2.2)`, "quote the color value"));
+      continue;
+    }
+    if (isPlaceholder(value)) {
+      placeholder("colors", name, value);
+    } else if (!HEX_RE.test(value) && !OKLCH_RE.test(value)) {
+      violations.push(violation6("medium", "design-md.tokens.color-format", `color "${name}" = "${value}" is not a hex (\`#rrggbb\`/\`#rrggbbaa\`) or oklch() value (design-md-spec §2.2)`, "use an sRGB hex value, optionally with a `-p3` oklch() twin"));
+    }
+  }
+  for (const [name, value] of groupEntries("typography")) {
+    if (!isMap(value)) {
+      violations.push(violation6("medium", "design-md.tokens.typography-shape", `typography token "${name}" must be a map of the five properties (design-md-spec §1.5)`, "give it fontFamily/fontSize/fontWeight/lineHeight/letterSpacing"));
+      continue;
+    }
+    const keys = Object.keys(value);
+    const missing = TYPOGRAPHY_PROPS.filter((p) => !keys.includes(p));
+    const extra = keys.filter((k) => !TYPOGRAPHY_PROPS.includes(k));
+    if (missing.length > 0 || extra.length > 0) {
+      violations.push(violation6("medium", "design-md.tokens.typography-shape", `typography token "${name}" must have exactly the five properties fontFamily/fontSize/fontWeight/lineHeight/letterSpacing (design-md-spec §1.5)${missing.length > 0 ? ` — missing: ${missing.join(", ")}` : ""}${extra.length > 0 ? ` — extra: ${extra.join(", ")}` : ""}`, "align the token with the five-property shape"));
+    }
+    for (const prop of ["fontFamily", "fontSize"]) {
+      const v = value[prop];
+      if (typeof v === "string" && isPlaceholder(v))
+        placeholder("typography", name, v);
+      else if (typeof v !== "string" || v.trim() === "") {
+        violations.push(violation6("medium", "design-md.tokens.typography-shape", `typography token "${name}" has an empty \`${prop}\` (design-md-spec §1.5)`, `fill \`${prop}\` with a concrete value`));
+      }
+    }
+  }
+  if (groupIsMap("spacing")) {
+    const spacing = fm.spacing;
+    if (!Object.prototype.hasOwnProperty.call(spacing, "base")) {
+      violations.push(violation6("medium", "design-md.tokens.spacing-base", "spacing must declare the base unit as `base` (design-md-spec §2.4)", "add `base: 4px` (or 8px) to the spacing group"));
+    }
+    for (const [name, value] of Object.entries(spacing)) {
+      if (name !== "base" && name !== RAW_GROUP && !/^\d+$/.test(name)) {
+        violations.push(violation6("medium", "design-md.tokens.spacing-key", `spacing key "${name}" must be \`base\` or a numeric multiplier (design-md-spec §1.5)`, "use numeric scale-step keys or `base`"));
+      }
+      if (typeof value === "string" && isPlaceholder(value)) {
+        placeholder("spacing", name, value);
+      } else if (typeof value !== "string" || !PX_RE.test(value)) {
+        violations.push(violation6("medium", "design-md.tokens.spacing-format", `spacing value "${name}" = "${String(value)}" is not a px length (design-md-spec §1.5)`, "use a pixel value like `4px`"));
+      }
+    }
+  }
+  for (const [name, value] of groupEntries("rounded")) {
+    if (typeof value === "string" && isPlaceholder(value)) {
+      placeholder("rounded", name, value);
+    } else if (typeof value !== "string" || !PX_RE.test(value)) {
+      violations.push(violation6("medium", "design-md.tokens.rounded-format", `rounded value "${name}" = "${String(value)}" is not a px length (design-md-spec §1.5)`, "use a pixel value like `6px`"));
+    }
+  }
+  for (const [name, value] of groupEntries("components")) {
+    if (!isMap(value)) {
+      violations.push(violation6("medium", "design-md.tokens.components-shape", `component token "${name}" must be a map of properties (design-md-spec §2.8)`, "give it backgroundColor/textColor/typography/rounded/padding/height"));
+      continue;
+    }
+    for (const [prop, v] of Object.entries(value)) {
+      if (typeof v !== "string")
+        continue;
+      if (isPlaceholder(v)) {
+        placeholder("components", `${name}.${prop}`, v);
+        continue;
+      }
+      const ref = REF_RE.exec(v);
+      if (ref === null)
+        continue;
+      const [, refGroup, refKey] = ref;
+      const resolves = REF_GROUPS.includes(refGroup) && groupIsMap(refGroup) && Object.prototype.hasOwnProperty.call(fm[refGroup], refKey);
+      if (!resolves) {
+        violations.push(violation6("medium", "design-md.tokens.ref-unresolved", `component "${name}" references "${v}" which does not resolve to an active token in this frontmatter (design-md-spec §6 — {path} refs MUST trace back to a key)`, `add the referenced token or use a literal value`));
+      }
+    }
+  }
+  return { ok: violations.length === 0, violations };
+}
+var PARITY_GROUPS = ["colors", "typography", "spacing", "rounded", "components"];
+function assertLightDarkParity(lightFm, darkFm) {
+  const violations = [];
+  const light = parseDesignFrontmatter(lightFm);
+  const dark = parseDesignFrontmatter(darkFm);
+  if (light === null || dark === null) {
+    violations.push(violation6("medium", "design-md.parity.missing-frontmatter", `light/dark parity needs a YAML frontmatter in both files — ${light === null ? "DESIGN.md" : "DESIGN.dark.md"} has none (design-md-spec §4 rules 1–2)`, "add the fenced frontmatter to both theme files"));
+    return { ok: false, violations };
+  }
+  const activeKeys = (fm) => {
+    const keys = new Set;
+    for (const group of PARITY_GROUPS) {
+      const value = fm[group];
+      if (!isMap(value) || RAW_GROUP in value)
+        continue;
+      for (const key of Object.keys(value))
+        keys.add(`${group}.${key}`);
+    }
+    return keys;
+  };
+  const lightKeys = activeKeys(light);
+  const darkKeys = activeKeys(dark);
+  for (const key of lightKeys) {
+    if (!darkKeys.has(key)) {
+      violations.push(violation6("medium", "design-md.parity.missing-dark", `token "${key}" is active in DESIGN.md but missing from DESIGN.dark.md — both files must define the same token set (design-md-spec §4 rule 3)`, "add the token to DESIGN.dark.md with a dark-appropriate value"));
+    }
+  }
+  for (const key of darkKeys) {
+    if (!lightKeys.has(key)) {
+      violations.push(violation6("medium", "design-md.parity.missing-light", `token "${key}" is active in DESIGN.dark.md but missing from DESIGN.md — DESIGN.md is the SSOT for token names (design-md-spec §4 rules 3–4)`, "add the token to DESIGN.md, or remove it from the dark file"));
+    }
+  }
+  return { ok: violations.length === 0, violations };
+}
+var GRAY_STEPS = ["100", "200", "300", "400", "500", "600", "700", "800", "900", "1000"];
+var ALPHA_STEPS = ["100", "200", "300", "400", "500", "600"];
+var ACCENT_SCALES = ["blue", "red", "amber", "green", "teal", "purple", "pink"];
+var L3_BODY_ITEM_IDS = [
+  "dark-exists",
+  "dark-parity",
+  "elevation-shadows",
+  "motion-easing",
+  "motion-durations",
+  "motion-reduced",
+  "voice-content"
+];
+function isConcrete(value) {
+  if (typeof value === "number")
+    return true;
+  return typeof value === "string" && value !== "" && !isPlaceholder(value);
+}
+function groupHasConcrete(fm, group, key) {
+  if (fm === null)
+    return false;
+  const value = fm[group];
+  if (!isMap(value) || RAW_GROUP in value)
+    return false;
+  const entry = value[key];
+  return entry !== undefined && isConcrete(entry);
+}
+function typographyTokenComplete(fm, key) {
+  if (fm === null)
+    return false;
+  const group = fm.typography;
+  if (!isMap(group) || RAW_GROUP in group)
+    return false;
+  const entry = group[key];
+  if (!isMap(entry))
+    return false;
+  return TYPOGRAPHY_PROPS.every((p) => Object.prototype.hasOwnProperty.call(entry, p) && isConcrete(entry[p]));
+}
+function countRoleTokens(fm, role) {
+  if (fm === null)
+    return 0;
+  const group = fm.typography;
+  if (!isMap(group) || RAW_GROUP in group)
+    return 0;
+  return Object.keys(group).filter((k) => k.startsWith(`${role}-`) && typographyTokenComplete(fm, k)).length;
+}
+function countNumericSpacingSteps(fm) {
+  if (fm === null)
+    return 0;
+  const group = fm.spacing;
+  if (!isMap(group) || RAW_GROUP in group)
+    return 0;
+  return Object.keys(group).filter((k) => k !== "base" && k !== RAW_GROUP && /^\d+$/.test(k)).length;
+}
+function hasComponent(fm, name) {
+  if (fm === null)
+    return false;
+  const group = fm.components;
+  if (!isMap(group) || RAW_GROUP in group)
+    return false;
+  return isMap(group[name]);
+}
+var LEVEL_RANK = { BELOW_MVP: 0, MVP: 1, Standard: 2, Production: 3 };
+function completenessLevel(frontmatterText, checklist) {
+  const fm = parseDesignFrontmatter(frontmatterText);
+  const bodyUnverified = checklist === undefined;
+  const bodyOk = (id) => (checklist ?? []).includes(id);
+  const items = [];
+  const add = (id, level2, source, ok) => {
+    items.push({ id, level: level2, ok, source });
+  };
+  add("fm-exists", 1, "frontmatter", fm !== null);
+  add("version", 1, "frontmatter", fm !== null && typeof fm.version === "string" && isConcrete(fm.version));
+  add("name-description", 1, "frontmatter", fm !== null && typeof fm.name === "string" && isConcrete(fm.name) && typeof fm.description === "string" && isConcrete(fm.description));
+  add("colors-background", 1, "frontmatter", groupHasConcrete(fm, "colors", "background-100"));
+  add("colors-text", 1, "frontmatter", groupHasConcrete(fm, "colors", "gray-1000") && groupHasConcrete(fm, "colors", "gray-900"));
+  add("colors-accent", 1, "frontmatter", ACCENT_SCALES.some((a) => groupHasConcrete(fm, "colors", `${a}-700`)));
+  add("colors-semantic", 1, "frontmatter", groupHasConcrete(fm, "colors", "red-700") && groupHasConcrete(fm, "colors", "amber-700"));
+  add("type-copy", 1, "frontmatter", countRoleTokens(fm, "copy") >= 1);
+  add("type-heading", 1, "frontmatter", countRoleTokens(fm, "heading") >= 1);
+  add("spacing-scale", 1, "frontmatter", groupHasConcrete(fm, "spacing", "base") && countNumericSpacingSteps(fm) >= 5);
+  add("rounded-sm", 1, "frontmatter", groupHasConcrete(fm, "rounded", "sm"));
+  add("breakpoints-2", 1, "body", bodyOk("breakpoints-2"));
+  add("colors-background-scale", 2, "frontmatter", ["background-100", "background-200", "background-300"].every((k) => groupHasConcrete(fm, "colors", k)));
+  add("colors-gray-scale", 2, "frontmatter", GRAY_STEPS.every((s) => groupHasConcrete(fm, "colors", `gray-${s}`)));
+  add("colors-alpha-scale", 2, "frontmatter", ALPHA_STEPS.every((s) => groupHasConcrete(fm, "colors", `gray-alpha-${s}`)));
+  add("colors-accent-scales", 2, "frontmatter", ACCENT_SCALES.every((a) => ["700", "800", "900", "1000"].every((s) => groupHasConcrete(fm, "colors", `${a}-${s}`))));
+  add("type-headings-3", 2, "frontmatter", countRoleTokens(fm, "heading") >= 3);
+  add("type-label", 2, "frontmatter", countRoleTokens(fm, "label") >= 1);
+  add("type-button", 2, "frontmatter", countRoleTokens(fm, "button") >= 1);
+  add("spacing-full", 2, "frontmatter", countNumericSpacingSteps(fm) >= 9);
+  add("rounded-full", 2, "frontmatter", ["sm", "md", "lg", "full"].every((k) => groupHasConcrete(fm, "rounded", k)));
+  add("components-button", 2, "frontmatter", hasComponent(fm, "button-primary") && hasComponent(fm, "button-secondary") && hasComponent(fm, "button-small"));
+  add("components-input", 2, "frontmatter", hasComponent(fm, "input"));
+  add("breakpoints-4", 2, "body", bodyOk("breakpoints-4"));
+  add("components-button-states", 2, "body", bodyOk("components-button-states"));
+  add("components-input-states", 2, "body", bodyOk("components-input-states"));
+  add("spacing-rhythm", 2, "body", bodyOk("spacing-rhythm"));
+  const componentNames = [];
+  if (fm !== null && isMap(fm.components)) {
+    for (const key of Object.keys(fm.components)) {
+      if (key !== RAW_GROUP && isMap(fm.components[key]))
+        componentNames.push(key);
+    }
+  }
+  const namesJoined = componentNames.join(" ");
+  add("components-library", 3, "frontmatter", componentNames.length >= 4 && /card/i.test(namesJoined) && /modal/i.test(namesJoined) && /tooltip/i.test(namesJoined) && /menu|dropdown/i.test(namesJoined));
+  add("dark-exists", 3, "body", bodyOk("dark-exists"));
+  add("dark-parity", 3, "body", bodyOk("dark-parity"));
+  add("elevation-shadows", 3, "body", bodyOk("elevation-shadows"));
+  add("motion-easing", 3, "body", bodyOk("motion-easing"));
+  add("motion-durations", 3, "body", bodyOk("motion-durations"));
+  add("motion-reduced", 3, "body", bodyOk("motion-reduced"));
+  add("voice-content", 3, "body", bodyOk("voice-content"));
+  const participating = items.filter((it) => it.source === "frontmatter" || !bodyUnverified);
+  const failing = (level2) => participating.filter((it) => it.level === level2 && !it.ok).map((it) => it.id);
+  const fail1 = failing(1);
+  const fail2 = failing(2);
+  const fail3 = failing(3);
+  let level;
+  let missing;
+  if (fail1.length > 0) {
+    level = "BELOW_MVP";
+    missing = fail1;
+  } else if (fail2.length > 0) {
+    level = "MVP";
+    missing = fail2;
+  } else if (fail3.length > 0) {
+    level = "Standard";
+    missing = fail3;
+  } else {
+    level = "Production";
+    missing = [];
+  }
+  if (level === "Production" && bodyUnverified) {
+    level = "Standard";
+    missing = [...L3_BODY_ITEM_IDS];
+  }
+  const placeholders = [];
+  frontmatterText.split(/\r?\n/).forEach((line, index) => {
+    const m = /\b(LEVEL([23])_PLACEHOLDER)\b/.exec(line);
+    if (m !== null)
+      placeholders.push({ level: Number(m[2]), marker: m[1], line: index + 1 });
+  });
+  const rank = LEVEL_RANK[level];
+  const candidate = placeholders.map((p) => p.level).filter((l) => l > rank).sort((a, b) => b - a)[0];
+  const upgradeTo = candidate === undefined ? null : candidate;
+  return { level, items, missing, placeholders, upgradeTo, bodyUnverified };
+}
+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"
+];
+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 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 = readFileSync6(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);
+  }
+  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 };
+  mkdirSync5(outDir, { recursive: true });
+  const existing = readdirSync4(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`;
+    writeFileSync4(join7(outDir, file), renderPlanFile(finding, plannedAt));
+    written.push(file);
+    next++;
+  }
+  const all = [...existing, ...written].sort();
+  const rows = all.map((file) => {
+    const summary = readPlanFileSummary(join7(outDir, file));
+    const 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";
+    }
+  });
+  writeFileSync4(join7(outDir, "README.md"), renderIndex({
+    date,
+    repoName: options.repoName ?? "repo",
+    repoShortSha: options.repoShortSha ?? "unknown",
+    rows,
+    rejected: options.rejected ?? []
+  }));
+  return { outDir: resolve7(outDir), date, files: written, nextNumber: next };
+}
+function violation8(severity, code, message, fix) {
+  return { ok: false, severity, code, message, fix };
+}
+var KNOWLEDGE_REQUIRED_FIELDS = ["module", "date", "problem_type", "category", "severity"];
+var KNOWLEDGE_PROBLEM_TYPES = [
+  "build_error",
+  "test_failure",
+  "runtime_error",
+  "performance_issue",
+  "database_issue",
+  "security_issue",
+  "ui_bug",
+  "integration_issue",
+  "logic_error",
+  "config_error",
+  "developer_experience",
+  "workflow_issue",
+  "best_practice",
+  "documentation_gap",
+  "architecture_pattern",
+  "design_pattern",
+  "tooling_decision",
+  "convention",
+  "api_design",
+  "testing_pattern"
+];
+var KNOWLEDGE_BUG_PROBLEM_TYPES = [
+  "build_error",
+  "test_failure",
+  "runtime_error",
+  "performance_issue",
+  "database_issue",
+  "security_issue",
+  "ui_bug",
+  "integration_issue",
+  "logic_error",
+  "config_error"
+];
+var KNOWLEDGE_SEVERITIES = ["critical", "high", "medium", "low"];
+var KNOWLEDGE_RESOLUTION_TYPES = [
+  "code_fix",
+  "migration",
+  "config_change",
+  "test_fix",
+  "dependency_update",
+  "environment_setup",
+  "workflow_improvement",
+  "documentation_update",
+  "tooling_addition"
+];
+var KNOWLEDGE_CATEGORY_MAP = {
+  build_error: "build-errors",
+  test_failure: "test-failures",
+  runtime_error: "runtime-errors",
+  performance_issue: "performance-issues",
+  database_issue: "database-issues",
+  security_issue: "security-issues",
+  ui_bug: "ui-bugs",
+  integration_issue: "integration-issues",
+  logic_error: "logic-errors",
+  config_error: "config-errors",
+  best_practice: "best-practices",
+  convention: "conventions",
+  architecture_pattern: "architecture-patterns",
+  design_pattern: "design-patterns",
+  tooling_decision: "tooling-decisions",
+  testing_pattern: "testing-patterns",
+  api_design: "api-design",
+  workflow_issue: "workflow-patterns",
+  developer_experience: "developer-experience",
+  documentation_gap: "documentation"
+};
+var DATE_RE3 = /^\d{4}-\d{2}-\d{2}$/;
+var isMap2 = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+function parseScalar2(raw) {
+  const trimmed = raw.trim();
+  const quoted = /^"([^"]*)"$/.exec(trimmed) ?? /^'([^']*)'$/.exec(trimmed);
+  if (quoted)
+    return quoted[1];
+  const cut = trimmed.split(/\s+#/)[0].trim();
+  if (/^-?\d+(?:\.\d+)?$/.test(cut))
+    return Number(cut);
+  if (/^(?:true|false)$/.test(cut))
+    return cut === "true";
+  return cut;
+}
+function parseMapBlock2(lines, start, indent) {
+  const map = {};
+  let i = start;
+  while (i < lines.length && lines[i].indent === indent) {
+    const match = /^([^:]+):(.*)$/.exec(lines[i].text);
+    if (match === null) {
+      i++;
+      continue;
+    }
+    const key = parseScalar2(match[1].trim()).toString();
+    const rest = match[2].trim();
+    if (rest === "") {
+      const nested = i + 1 < lines.length && lines[i + 1].indent > indent;
+      if (nested) {
+        const child = parseBlock2(lines, i + 1, lines[i + 1].indent);
+        map[key] = child.value;
+        i = child.next;
+      } else {
+        map[key] = "";
+        i++;
+      }
+    } else {
+      map[key] = parseScalar2(rest);
+      i++;
+    }
+  }
+  return { value: map, next: i };
+}
+function parseListBlock2(lines, start, indent) {
+  const list = [];
+  let i = start;
+  while (i < lines.length && lines[i].indent === indent && lines[i].text.startsWith("-")) {
+    const rest = lines[i].text.slice(1).trim();
+    const match = /^([^:]+):(.*)$/.exec(rest);
+    if (match !== null && match[2].trim() === "" && i + 1 < lines.length && lines[i + 1].indent > indent) {
+      const child = parseBlock2(lines, i + 1, lines[i + 1].indent);
+      list.push({ [parseScalar2(match[1].trim()).toString()]: child.value });
+      i = child.next;
+    } else if (match !== null) {
+      list.push({ [parseScalar2(match[1].trim()).toString()]: parseScalar2(match[2].trim()) });
+      i++;
+    } else {
+      list.push(parseScalar2(rest));
+      i++;
+    }
+  }
+  return { value: list, next: i };
+}
+function parseBlock2(lines, start, indent) {
+  if (lines[start] !== undefined && lines[start].text.startsWith("-"))
+    return parseListBlock2(lines, start, indent);
+  return parseMapBlock2(lines, start, indent);
+}
+function parseYamlLite(text) {
+  const body = text.replace(/^\uFEFF/, "");
+  const lines = body.split(/\r?\n/);
+  if (lines.length === 0 || !lines[0].trim().startsWith("---"))
+    return null;
+  const inner = [];
+  for (let i = 1;i < lines.length; i++) {
+    const trimmed = lines[i].trim();
+    if (trimmed === "---")
+      break;
+    if (trimmed === "" || trimmed.startsWith("#"))
+      continue;
+    const indent = lines[i].match(/^ */)[0].length;
+    inner.push({ indent, text: lines[i].slice(indent) });
+  }
+  if (inner.length === 0)
+    return null;
+  const top = parseBlock2(inner, 0, inner[0].indent);
+  if (!isMap2(top.value))
+    return null;
+  return top.value;
+}
+function validateSchemaYaml(frontmatterText) {
+  const violations = [];
+  const doc = parseYamlLite(frontmatterText);
+  if (doc === null) {
+    violations.push(violation8("medium", "compound.schema.missing-frontmatter", "no `---` YAML frontmatter block found — knowledge docs must open with the schema.yaml contract (mstar-compound/references/schema.yaml)", "add the fenced frontmatter with module, date, problem_type, category, severity"));
+    return { ok: false, violations };
+  }
+  const isStr = (v) => typeof v === "string";
+  const missing = (field) => violations.push(violation8("medium", "compound.schema.missing-field", `missing required frontmatter field "${field}" (schema.yaml required_fields)`, `add \`${field}: <value>\` to the frontmatter`));
+  for (const field of KNOWLEDGE_REQUIRED_FIELDS) {
+    if (!(field in doc) || doc[field] === "")
+      missing(field);
+  }
+  if (doc.date !== undefined && (!isStr(doc.date) || !DATE_RE3.test(doc.date))) {
+    violations.push(violation8("medium", "compound.schema.invalid-date", `date "${String(doc.date)}" must be a YYYY-MM-DD string (schema.yaml required_fields.date)`, "use `YYYY-MM-DD`"));
+  }
+  const problemType = doc.problem_type;
+  if (problemType !== undefined && !isStr(problemType)) {
+    violations.push(violation8("medium", "compound.schema.invalid-problem-type", `problem_type "${String(problemType)}" must be a string — one of the schema.yaml enum values (bug: build_error…config_error; knowledge: developer_experience…testing_pattern)`, "pick the narrowest applicable problem_type from schema.yaml"));
+  }
+  const problemTypeValid = isStr(problemType) && KNOWLEDGE_PROBLEM_TYPES.includes(problemType);
+  if (isStr(problemType) && !problemTypeValid) {
+    violations.push(violation8("medium", "compound.schema.invalid-problem-type", `problem_type "${problemType}" is not one of the schema.yaml enum values (bug: build_error…config_error; knowledge: developer_experience…testing_pattern)`, "pick the narrowest applicable problem_type from schema.yaml"));
+  }
+  if (doc.severity !== undefined && !isStr(doc.severity)) {
+    violations.push(violation8("medium", "compound.schema.invalid-severity", `severity "${String(doc.severity)}" must be a string — critical | high | medium | low (schema.yaml required_fields.severity)`, "use one of the four severity values"));
+  }
+  if (isStr(doc.severity) && !KNOWLEDGE_SEVERITIES.includes(doc.severity)) {
+    violations.push(violation8("medium", "compound.schema.invalid-severity", `severity "${doc.severity}" must be critical | high | medium | low (schema.yaml required_fields.severity)`, "use one of the four severity values"));
+  }
+  if (problemTypeValid && isStr(doc.category)) {
+    const expected = KNOWLEDGE_CATEGORY_MAP[problemType];
+    if (doc.category !== expected) {
+      violations.push(violation8("medium", "compound.schema.category-mismatch", `category "${doc.category}" does not match problem_type "${problemType}" — category-mapping.md rule 1 maps it to "${expected}"`, `set \`category: ${expected}\` (the directory name under {KNOWLEDGE_DIR})`));
+    }
+  }
+  if (problemTypeValid) {
+    const isBug = KNOWLEDGE_BUG_PROBLEM_TYPES.includes(problemType);
+    if (isBug) {
+      for (const field of ["symptoms", "root_cause", "resolution_type"]) {
+        if (!(field in doc)) {
+          violations.push(violation8("medium", "compound.schema.missing-track-field", `bug-track doc missing required field "${field}" (schema.yaml track_rules.bug)`, `add \`${field}:\` to the frontmatter`));
+        }
+      }
+      if (doc.symptoms !== undefined && !Array.isArray(doc.symptoms)) {
+        violations.push(violation8("medium", "compound.schema.invalid-symptoms", "bug-track `symptoms` must be a YAML list (schema.yaml track_rules.bug)", "list the observable symptoms under `symptoms:`"));
+      }
+      if (doc.root_cause !== undefined && !isStr(doc.root_cause)) {
+        violations.push(violation8("medium", "compound.schema.invalid-root-cause", "bug-track `root_cause` must be a string (schema.yaml track_rules.bug)", "write the fundamental technical cause as a string"));
+      }
+      if (isStr(doc.resolution_type) && !KNOWLEDGE_RESOLUTION_TYPES.includes(doc.resolution_type)) {
+        violations.push(violation8("medium", "compound.schema.invalid-resolution-type", `resolution_type "${doc.resolution_type}" is not one of the schema.yaml track_rules.bug enum values`, "use code_fix | migration | config_change | test_fix | dependency_update | environment_setup | workflow_improvement | documentation_update | tooling_addition"));
+      }
+    } else if (doc.applies_when !== undefined && !Array.isArray(doc.applies_when)) {
+      violations.push(violation8("low", "compound.schema.invalid-applies-when", "knowledge-track `applies_when` must be a YAML list when present (schema.yaml track_rules.knowledge)", "list the conditions under `applies_when:`"));
+    }
+  }
+  if (doc.plan_id !== undefined && !isStr(doc.plan_id)) {
+    violations.push(violation8("low", "compound.schema.invalid-plan-id", "optional `plan_id` must be a string (schema.yaml optional_fields.plan_id)", "reference the status.json plan id as a string"));
+  }
+  if (doc.tags !== undefined) {
+    if (!Array.isArray(doc.tags)) {
+      violations.push(violation8("low", "compound.schema.invalid-tags", "optional `tags` must be a YAML list (schema.yaml optional_fields.tags)", "list lowercase, hyphen-separated keywords"));
+    } else if (doc.tags.length > 8) {
+      violations.push(violation8("low", "compound.schema.tags-too-many", `tags has ${doc.tags.length} entries — max 8 (schema.yaml optional_fields.tags.max_items)`, "trim the tag list to at most 8 keywords"));
+    }
+  }
+  if (doc.last_updated !== undefined && (!isStr(doc.last_updated) || !DATE_RE3.test(doc.last_updated))) {
+    violations.push(violation8("low", "compound.schema.invalid-last-updated", `last_updated "${String(doc.last_updated)}" must be YYYY-MM-DD (schema.yaml optional_fields.last_updated)`, "use `YYYY-MM-DD`"));
+  }
+  if (doc.related_components !== undefined && !Array.isArray(doc.related_components)) {
+    violations.push(violation8("low", "compound.schema.invalid-related-components", "optional `related_components` must be a YAML list (schema.yaml optional_fields.related_components)", "list the other components involved"));
+  }
+  return { ok: violations.length === 0, violations };
+}
+var WALK_SKIP_DIRS = new Set(["node_modules", ".git", "dist"]);
+function collectKnowledgeDocs(dir) {
+  const docs = [];
+  const stack = [dir];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    let entries;
+    try {
+      entries = readdirSync5(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (entry.isSymbolicLink())
+        continue;
+      const full = join8(current, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(full);
+      } else if (entry.name.endsWith(".md") && entry.name !== "README.md" && entry.name !== "index.md") {
+        docs.push(relative2(dir, full).split(sep).join("/"));
+      }
+    }
+  }
+  return docs.sort();
+}
+function normalizeIndexRef(cell) {
+  const link = /\[[^\]]*\]\(([^)]+)\)/.exec(cell);
+  let value = link !== null ? link[1] : cell;
+  value = value.replace(/`/g, "").replace(/^\.\//, "");
+  if (value.startsWith("knowledge/"))
+    value = value.slice("knowledge/".length);
+  return value.trim();
+}
+function assertIndexRows(knowledgeDir) {
+  const violations = [];
+  const readmePath = join8(knowledgeDir, "README.md");
+  if (!existsSync5(readmePath)) {
+    violations.push(violation8("medium", "compound.index.missing-readme", `missing ${readmePath} — the knowledge index is required (mstar-compound Phase 6: every doc gets a README.md row)`, "create knowledge/README.md with a Document / Source Plan / Description / Status table"));
+    return { ok: false, violations };
+  }
+  const docs = collectKnowledgeDocs(knowledgeDir);
+  const rows = new Set;
+  for (const line of readFileSync7(readmePath, "utf8").split(/\r?\n/)) {
+    if (!line.trim().startsWith("|"))
+      continue;
+    const cells = line.split("|").map((c) => c.trim());
+    if (cells.length < 2)
+      continue;
+    const normalized = normalizeIndexRef(cells[1]);
+    if (normalized !== "")
+      rows.add(normalized);
+  }
+  for (const doc of docs) {
+    if (!rows.has(doc)) {
+      violations.push(violation8("medium", "compound.index.missing-row", `knowledge doc "${doc}" has no row in knowledge/README.md index (mstar-compound Phase 6 index obligations)`, `add a row \`| [<title>](${doc}) | <source plan> | <description> | <status> |\` to knowledge/README.md`));
+    }
+  }
+  return { ok: violations.length === 0, violations };
+}
+function isFileLikeRoot(root) {
+  return /^[^.]*\.[A-Za-z0-9]{1,10}$/.test(basename4(root));
+}
+function scopeGuard(path2, allowedRoots) {
+  const resolved = resolve8(path2);
+  for (const root of allowedRoots) {
+    const r = resolve8(root);
+    if (isFileLikeRoot(r)) {
+      if (resolved === r)
+        return { ok: true, violations: [] };
+    } else if (resolved === r || resolved.startsWith(r + sep)) {
+      return { ok: true, violations: [] };
+    }
+  }
+  return {
+    ok: false,
+    violations: [
+      violation8("medium", "compound.scope.outside", `path "${path2}" is outside the compound-refresh scope (allowed: ${allowedRoots.join(", ")}) — compound-refresh operates only on {HARNESS_DIR}/knowledge/**, {HARNESS_DIR}/knowledge/README.md, <repo-root>/CONCEPTS.md, {HARNESS_DIR}/status.json (mstar-compound-refresh SKILL.md § 产物与操作路径)`, "point the operation at one of the allowed paths")
+    ]
+  };
+}
+function violation9(severity, code, message, fix) {
+  return { ok: false, severity, code, message, fix };
+}
+var COMMENT_INTRODUCER = "(?:\\/\\/|\\/\\*|#|;|--|\\s\\*)";
+function findSimplifyMarkers(fileText) {
+  const markers = [];
+  const re = new RegExp(`${COMMENT_INTRODUCER}\\s*simplify\\s*:`, "i");
+  const lines = fileText.split(/\r?\n/);
+  for (let i = 0;i < lines.length; i++) {
+    if (re.test(lines[i]))
+      markers.push({ line: i + 1, text: lines[i].trim() });
+  }
+  return markers;
+}
+var REMOVAL_PATH_PATTERNS = [
+  /status\.json/i,
+  /R#\d+/i,
+  /\bresiduals?\b/i,
+  /plans?\/[\w./-]+/i,
+  /\bplans?\s+20\d{6}[-.\w]*/i,
+  /\b(?:tracked|recorded|logged|scheduled|listed|noted)\s+in\s+[\w./-]+/i,
+  /removal\s+path\s*[:=]\s*["'`]?[\w./-]+/i
+];
+function findTemporaryMarkers(fileText) {
+  const markers = [];
+  const violations = [];
+  const re = new RegExp(`${COMMENT_INTRODUCER}\\s*temporary\\b`, "i");
+  const lines = fileText.split(/\r?\n/);
+  for (let i = 0;i < lines.length; i++) {
+    const line = lines[i];
+    if (!re.test(line))
+      continue;
+    const text = line.trim();
+    let removalPath = null;
+    for (const pattern of REMOVAL_PATH_PATTERNS) {
+      const match = pattern.exec(text);
+      if (match) {
+        removalPath = match[0];
+        break;
+      }
+    }
+    markers.push({ line: i + 1, text, removalPath });
+    if (removalPath === null) {
+      violations.push(violation9("medium", "lint.temporary.no-removal-path", `temporary marker at line ${i + 1} records no removal path (plan/status artifact reference) — record one before claiming the task complete (mstar-coding-behavior § Simplification markers)`, 'add a plan/status reference to the marker, e.g. "removal tracked in status.json" or "plan 20260808-slice2 removes this"'));
+    }
+  }
+  return { ok: violations.length === 0, violations, markers };
+}
+var TEST_FILE_PATH_RE = /[\w./-]+\.(?:test|spec)\.[a-z0-9]+/i;
+var TEST_FILE_PHRASE_RE = /\btest files?\b/i;
+var COMMAND_PROMPT_RE = /^\s*[$>]\s*\S/;
+var RUNNER_RE = /\b(?:bun|pnpm|npm|yarn|npx|bunx)\s+(?:test|run|exec)\b|\b(?:npx|bunx)\s+[\w./-]+\b|\b(?:tsc|vitest|jest|mocha|pytest)\b|\bgo\s+test\b|\bcargo\s+test\b/i;
+var OUTPUT_TOKEN_RE = /[✓✔✗✘]|\b(?:PASS|FAIL)\b|\b\d+\s+(?:pass(?:es|ed)?|fail(?:s|ed|ing)?|skipped|tests?|ok)\b|\bok\s+\d+\b|\ball\s+ok\b|exit(?:ed)?\s+(?:with\s+)?(?:code\s+)?\d+/i;
+function assertSddTddTriple(reportText) {
+  const violations = [];
+  const lines = reportText.split(/\r?\n/);
+  let hasTests = false;
+  let hasCommand = false;
+  let hasOutput = false;
+  for (const line of lines) {
+    if (!hasTests && (TEST_FILE_PATH_RE.test(line) || TEST_FILE_PHRASE_RE.test(line)))
+      hasTests = true;
+    if (!hasCommand && (COMMAND_PROMPT_RE.test(line) || RUNNER_RE.test(line)))
+      hasCommand = true;
+    if (!hasOutput && OUTPUT_TOKEN_RE.test(line))
+      hasOutput = true;
+    if (hasTests && hasCommand && hasOutput)
+      break;
+  }
+  if (!hasTests) {
+    violations.push(violation9("medium", "lint.sdd-tdd.missing-tests", "task report carries no test file reference — the TDD triple needs covering test file(s) (mstar-coding-behavior § Integration Notes; mstar-sdd/references/file-handoffs.md)", 'add a "Covering test file(s): <path>.test.ts" line or a `.test.<ext>` path to the report'));
+  }
+  if (!hasCommand) {
+    violations.push(violation9("medium", "lint.sdd-tdd.missing-command", "task report carries no command — the TDD triple needs the exact command run (mstar-coding-behavior § Integration Notes; mstar-sdd/references/file-handoffs.md)", 'add a "Command run: `bun test <file>`" line to the report'));
+  }
+  if (!hasOutput) {
+    violations.push(violation9("medium", "lint.sdd-tdd.missing-output", "task report carries no output evidence — the TDD triple needs the run output (pass/fail counts or exit code) (mstar-coding-behavior § Integration Notes; mstar-sdd/references/file-handoffs.md)", 'paste the test-run output (e.g. "12 pass / 0 fail") into the report'));
+  }
+  return { ok: violations.length === 0, violations };
+}
+var PLACEHOLDER_TOKEN_RE = /\b(TBDs?|TODOs?|TBAs?)\b/gi;
+var ELLIPSIS_RE = /\.\.\./;
+var NEGATION_RE = /\b(?:no|not|without|none)\b/i;
+function stripInlineCode(line) {
+  return line.replace(/`[^`]*`/g, " ");
+}
+function planQualityBar(planText) {
+  const findings = [];
+  const violations = [];
+  const lines = planText.split(/\r?\n/);
+  let inFence = false;
+  for (let i = 0;i < lines.length; i++) {
+    const trimmed = lines[i].trim();
+    if (/^```/.test(trimmed) || /^~~~/.test(trimmed)) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence)
+      continue;
+    const stripped = stripInlineCode(lines[i]);
+    const segmentStartBefore = (index) => Math.max(stripped.lastIndexOf("(", index - 1), stripped.lastIndexOf("[", index - 1), stripped.lastIndexOf("{", index - 1), stripped.lastIndexOf(".", index - 1), stripped.lastIndexOf(";", index - 1), stripped.lastIndexOf(",", index - 1));
+    let token = null;
+    for (const wordMatch of stripped.matchAll(PLACEHOLDER_TOKEN_RE)) {
+      if (wordMatch.index === undefined)
+        continue;
+      const negated = NEGATION_RE.test(stripped.slice(segmentStartBefore(wordMatch.index) + 1, wordMatch.index));
+      if (!negated) {
+        token = wordMatch[0].replace(/s$/i, "").toUpperCase();
+        break;
+      }
+    }
+    if (token === null && ELLIPSIS_RE.test(stripped)) {
+      token = "...";
+    }
+    if (token !== null) {
+      const text = trimmed.length > 80 ? `${trimmed.slice(0, 77)}...` : trimmed;
+      findings.push({ token, line: i + 1, text });
+      violations.push(violation9("medium", "lint.plan-quality.placeholder", `placeholder token "${token}" at line ${i + 1}: "${text}"`, "replace the placeholder with concrete content before locking the plan (mstar-plan-artifacts/references/plan-quality-bar.md; templates/plan.main.md placeholder scan)"));
+    }
+  }
+  return { ok: violations.length === 0, violations, findings };
+}
+var WORKFLOW_VERB_START_RE = /^(?:explains?|describes?|covers?|provides?|walks?|guides?|shows?|lists?|details?|demonstrates?|outlines?|teaches?|summarizes?)\b/i;
+var PRONOUN_RE = /\bI\b(?!\/)|\b(?:we|you|my|our|your|us)\b/gi;
+var DESCRIPTION_MAX_WORDS = 120;
+function lintSkillFrontmatter(frontmatterText) {
+  const violations = [];
+  const fm = parseFrontmatter(frontmatterText);
+  if (fm === null) {
+    violations.push(violation9("medium", "lint.frontmatter.missing", "no YAML frontmatter block found — a skill file must open with a `---` fenced frontmatter (mstar-skill-authoring § Frontmatter Contract)", "add a frontmatter block with `name` and `description` at the top of the file"));
+    return { ok: false, violations };
+  }
+  const name = fm.name ?? "";
+  if (name === "") {
+    violations.push(violation9("medium", "lint.frontmatter.name.missing", "frontmatter `name` is missing — required (mstar-skill-authoring § Frontmatter Contract)", "add `name: <lowercase-hyphen-id>` to the frontmatter"));
+  } else if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) {
+    violations.push(violation9("medium", "lint.frontmatter.name.format", `frontmatter \`name\` must be lowercase-hyphen ("${name}") — e.g. example-skill (mstar-skill-authoring § Frontmatter Contract)`, "rename to a stable lowercase-hyphen id, e.g. `name: example-skill`"));
+  }
+  const description = fm.description ?? "";
+  if (description === "") {
+    violations.push(violation9("medium", "lint.frontmatter.description.missing", "frontmatter `description` is missing — the trigger contract is required (mstar-skill-authoring § Frontmatter Contract)", "add a `description:` that states when the skill loads (symptoms, context, roles, exclusions)"));
+  } else {
+    const stripped = description.replace(/`[^`]*`/g, " ").replace(/'[^']*'/g, " ").replace(/"[^"]*"/g, " ");
+    let pronoun = null;
+    for (const m of stripped.matchAll(PRONOUN_RE)) {
+      if (m[0] === "US")
+        continue;
+      pronoun = m;
+      break;
+    }
+    if (pronoun !== null) {
+      violations.push(violation9("low", "lint.frontmatter.description.person", `description uses first/second-person pronoun "${pronoun[0]}" — keep the trigger contract third person (mstar-skill-authoring § Frontmatter Contract)`, 'rewrite without I/we/you/my/our/your/us, e.g. "Use when the user asks …"'));
+    }
+    const start = description.trim().replace(/^[*_#>]+/, "").replace(/^["'`]+/, "").trim();
+    if (WORKFLOW_VERB_START_RE.test(start)) {
+      violations.push(violation9("low", "lint.frontmatter.description.workflow", 'description reads as a workflow summary ("Explains/Describes/Covers …") — the description is the trigger contract, not a summary of steps (mstar-skill-authoring § Frontmatter Contract)', "describe when to load the skill (symptoms, context, roles, exclusions) instead of summarizing its steps"));
+    } else {
+      const words = description.trim().split(/\s+/).filter(Boolean).length;
+      if (words > DESCRIPTION_MAX_WORDS) {
+        violations.push(violation9("low", "lint.frontmatter.description.workflow", `description is ${words} words — paragraph-length summaries bury the trigger contract (threshold ${DESCRIPTION_MAX_WORDS}, above the longest corpus description at 114 words, mstar-design-md; mstar-skill-authoring § Frontmatter Contract)`, "trim the description to a scannable trigger contract and move detail into the body"));
+      }
+    }
+  }
+  return { ok: violations.length === 0, violations };
+}
+function parseFrontmatter(text) {
+  const body = text.replace(/^\uFEFF/, "").replace(/^\s*/, "");
+  const lines = body.split(/\r?\n/);
+  const fields = {};
+  let inBlock = body.startsWith("---");
+  for (let i = inBlock ? 1 : 0;i < lines.length; i++) {
+    const line = lines[i];
+    if (inBlock && line.trim() === "---")
+      break;
+    const keyMatch = /^([A-Za-z_][\w-]*):\s*(.*)$/.exec(line);
+    if (keyMatch) {
+      fields[keyMatch[1].toLowerCase()] = keyMatch[2].trim().replace(/^["']|["']$/g, "");
+    } else if (inBlock && fields.description !== undefined) {
+      fields.description = `${fields.description} ${line.trim()}`.trim();
+    } else if (!inBlock && i >= 10) {
+      break;
+    }
+  }
+  if (Object.keys(fields).length === 0)
+    return null;
+  return fields;
+}
+var REQUIRED_STRATEGY_SECTIONS = [
+  "Vision",
+  "What we build",
+  "What we don't build",
+  "Guiding Principles",
+  "Technology Direction",
+  "Decision Log"
+];
+function lintStrategySections(docText) {
+  const violations = [];
+  const headings = new Set;
+  for (const line of docText.split(/\r?\n/)) {
+    const match = /^#{1,6}\s+(.+)$/.exec(line.trim());
+    if (!match)
+      continue;
+    headings.add(match[1].replace(/[*_`]/g, "").trim().toLowerCase());
+  }
+  for (const required of REQUIRED_STRATEGY_SECTIONS) {
+    if (!headings.has(required.toLowerCase())) {
+      violations.push(violation9("medium", "lint.strategy.missing-section", `missing required section "${required}" (mstar-strategy § STRATEGY.md structure)`, "add a `## <Section>` heading; required: Vision, What we build, What we don't build, Guiding Principles, Technology Direction, Decision Log"));
+    }
+  }
+  return { ok: violations.length === 0, violations };
+}
+function detectHost(signals2) {
+  const s = new Set(signals2);
+  if (s.has("subagent_type"))
+    return "cursor";
+  if (s.has("question") || s.has("task_subagent"))
+    return "opencode";
+  if (s.has("task_agent_batch") || s.has("ask") || s.has("hub"))
+    return "omp";
+  if (s.has("AgentSwarm"))
+    return "kimi";
+  if (s.has("Agent") || s.has("AskUserQuestion") || s.has("EnterPlanMode") || s.has("TodoWrite"))
+    return "zcode";
+  if (s.has("plan_slash") || s.has("goal") || s.has("functions.*") || s.has("tool_search"))
+    return "codex";
+  return "ambiguous";
+}
+function violation11(severity, code, message, fix) {
+  return { ok: false, severity, code, message, fix };
+}
+var FIVE_QUESTION_SECTIONS = [
+  { key: "load-order", label: "Load Order", question: "when to load the skill (triggers / exclusions)" },
+  { key: "workflow", label: "Workflow", question: "the order of execution and key decision points" },
+  { key: "decision-rules", label: "Decision Rules", question: "constraints / invariants that must never be violated" },
+  { key: "evidence", label: "Evidence", question: "what a correct result looks like (success criteria / evidence)" },
+  { key: "references", label: "References", question: "additional resources to open when the main path is not enough" }
+];
+var HEADING_RE = /^#{1,6}\s+[^\r\n]+$/;
+function lintFiveQuestion(bodyText) {
+  const headings = bodyText.split(/\r?\n/).filter((line) => HEADING_RE.test(line)).map((line) => line.replace(/^#{1,6}\s+/, "").trim().toLowerCase());
+  const violations = [];
+  for (const section of FIVE_QUESTION_SECTIONS) {
+    const label = section.label.toLowerCase();
+    const covered = headings.some((heading) => heading.includes(label));
+    if (!covered) {
+      violations.push(violation11("low", `skill-authoring.five-question.${section.key}`, `body does not answer "${section.question}" — no "${section.label}" section (mstar-skill-authoring § Body 必须回答的 5 问 / § 默认 Body 结构)`, `add a "## ${section.label}" section covering ${section.question}`));
+    }
+  }
+  return { ok: violations.length === 0, violations };
+}
+
+// src/compass.ts
+import { readFileSync as readFileSync5 } from "node:fs";
+function parseCompassFrontmatter(filePath) {
+  const content = readFileSync5(filePath, "utf8");
+  const lines = content.split(/\r?\n/);
+  if (lines[0]?.trim() !== "---") {
+    throw new Error(`no YAML frontmatter fence in ${filePath} (expected first line "---")`);
+  }
+  const end = lines.indexOf("---", 1);
+  if (end === -1) {
+    throw new Error(`unterminated YAML frontmatter in ${filePath} (no closing "---")`);
+  }
+  const doc = {};
+  let listKey = null;
+  for (let i = 1;i < end; i += 1) {
+    const line = lines[i] ?? "";
+    if (!line.trim() || line.trim().startsWith("#"))
+      continue;
+    if (listKey !== null && /^\s*-\s+/.test(line)) {
+      const item = line.replace(/^\s*-\s+/, "").trim().replace(/^["']|["']$/g, "");
+      if (!Array.isArray(doc[listKey]))
+        doc[listKey] = [];
+      doc[listKey].push(item);
+      continue;
+    }
+    listKey = null;
+    const kv = line.match(/^([A-Za-z_][A-Za-z0-9_-]*):\s*(.*)$/);
+    if (!kv) {
+      throw new Error(`unsupported frontmatter line in ${filePath}: ${JSON.stringify(line)}`);
+    }
+    const value = kv[2].trim();
+    doc[kv[1]] = value === "" ? null : /^\[.*\]$/.test(value) ? parseFlowArray(value, filePath) : value.replace(/^["']|["']$/g, "");
+    listKey = value === "" ? kv[1] : null;
+  }
+  return doc;
+}
+function parseFlowArray(raw, filePath) {
+  const inner = raw.slice(1, -1);
+  if (/[[\]]/.test(inner)) {
+    throw new Error(`nested flow-style array in ${filePath}: ${JSON.stringify(raw)} — only flat scalar items are supported (e.g. [a, b])`);
+  }
+  let quote = null;
+  for (const ch of inner) {
+    if (ch === '"' || ch === "'") {
+      if (quote === null)
+        quote = ch;
+      else if (quote === ch)
+        quote = null;
+    } else if (ch === "," && quote !== null) {
+      throw new Error(`ambiguous flow-style array in ${filePath}: ${JSON.stringify(raw)} — quoted item containing comma cannot be split unambiguously (flat scalar items only)`);
+    }
+  }
+  if (quote !== null) {
+    throw new Error(`unterminated ${quote} quote in flow-style array in ${filePath}: ${JSON.stringify(raw)}`);
+  }
+  const items = [];
+  for (const part of inner.split(",")) {
+    const item = part.trim().replace(/^["']|["']$/g, "");
+    if (item === "")
+      continue;
+    items.push(item);
+  }
+  return items;
+}
+
+// ../engine/dist/engine.js
+import { existsSync as existsSync4, mkdirSync as mkdirSync6, readFileSync as readFileSync8, renameSync as renameSync2, unlinkSync as unlinkSync3, writeFileSync as writeFileSync5 } from "node:fs";
+import { randomUUID as randomUUID2 } from "node:crypto";
+import { basename as basename5, dirname as dirname5, join as join6, resolve as resolve9 } from "node:path";
+import { fileURLToPath } from "node:url";
+import { dirname as dirname32, isAbsolute as isAbsolute22, join as join32, resolve as resolve32 } from "node:path";
+import { AsyncLocalStorage as AsyncLocalStorage3 } from "node:async_hooks";
+function readJson2(filePath) {
+  if (!existsSync4(filePath))
+    return {};
+  const content = readFileSync8(filePath, "utf8").trim();
+  if (!content)
+    return {};
+  try {
+    return JSON.parse(content);
+  } catch (error) {
+    throw new Error(`Invalid JSON in ${filePath}: ${error.message}`);
+  }
+}
+function writeJson2(filePath, value) {
+  const parent = dirname5(filePath);
+  mkdirSync6(parent, { recursive: true });
+  const tmp = join6(parent, `.${basename5(filePath)}.${process.pid}.${randomUUID2()}.tmp`);
+  try {
+    writeFileSync5(tmp, `${JSON.stringify(value, null, 2)}
+`, "utf8");
+    renameSync2(tmp, filePath);
+  } catch (error) {
+    try {
+      unlinkSync3(tmp);
+    } catch {}
+    throw error;
+  }
+}
+function resolveProjectRoot(startDir = process.cwd()) {
+  const start = resolve9(startDir);
+  let dir = start;
+  for (;; ) {
+    if (existsSync4(join6(dir, "package.json")) || existsSync4(join6(dir, "bun.lock")))
+      return dir;
+    const parent = dirname5(dir);
+    if (parent === dir)
+      return start;
+    dir = parent;
+  }
+}
+function findRootPackageJson(startDir) {
+  let dir = startDir;
+  for (;; ) {
+    const candidate = resolve9(dir, "package.json");
+    try {
+      const pkg = JSON.parse(readFileSync8(candidate, "utf8"));
+      if (pkg.name === "morning-star")
+        return candidate;
+    } catch {}
+    const parent = dirname5(dir);
+    if (parent === dir)
+      return null;
+    dir = parent;
+  }
+}
+function harnessVersionFrom(moduleDir) {
+  const ownManifest = join6(moduleDir, "..", "package.json");
+  try {
+    const pkg = JSON.parse(readFileSync8(ownManifest, "utf8"));
+    if (typeof pkg.version === "string" && pkg.version !== "")
+      return pkg.version;
+  } catch {}
+  const root = findRootPackageJson(moduleDir);
+  if (!root)
+    return "0.0.0";
+  try {
+    const pkg = JSON.parse(readFileSync8(root, "utf8"));
+    return pkg.version || "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+function readHarnessVersion() {
+  return harnessVersionFrom(dirname5(fileURLToPath(import.meta.url)));
+}
+var GITIGNORE_SNIPPET2 = `# Morning Star harness (.mstar/)
+# Principle: process stays local; results are shared with the team.
+# Ignored (process / coordination):
+.mstar/archived/
+.mstar/iterations/
+.mstar/plans/
+.mstar/sdd/
+.mstar/notes.json
+.mstar/status.json
+# Tracked (results): .mstar/AGENTS.md, .mstar/knowledge/, .mstar/specs/
+`;
+var GITIGNORE_SNIPPET_AGENTS2 = `# Morning Star harness (.agents/) — legacy
+.agents/archived/
+.agents/iterations/
+.agents/plans/
+.agents/sdd/
+.agents/notes.json
+.agents/status.json
+# Tracked (results): .agents/AGENTS.md, .agents/knowledge/, .agents/specs/
+`;
+var GITIGNORE_PROCESS_ENTRIES2 = GITIGNORE_SNIPPET2.split(`
+`).filter((line) => line.startsWith(".mstar/")).map((line) => line.trim());
+var GITIGNORE_PROCESS_ENTRIES_AGENTS2 = GITIGNORE_SNIPPET_AGENTS2.split(`
+`).filter((line) => line.startsWith(".agents/")).map((line) => line.trim());
+function isPlainObject4(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function violation(severity, code, message, fix) {
+  return { ok: false, severity, code, message, fix };
+}
+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`));
+  }
+}
+var DATE_PART2 = String.raw`\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])`;
+var RFC3339_Z_RE2 = new RegExp(String.raw`^${DATE_PART2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$`);
+var DATE_ONLY_RE2 = new RegExp(String.raw`^${DATE_PART2}$`);
+function isValidClaimedAt(value) {
+  return typeof value === "string" && (RFC3339_Z_RE2.test(value) || DATE_ONLY_RE2.test(value));
+}
+function validateExecutionLease(lease) {
+  const violations = [];
+  if (!isPlainObject4(lease)) {
+    return {
+      ok: false,
+      violations: [
+        violation("high", "lease.execution-lease.invalid", "execution_lease must be an object — null and tombstone objects are invalid; writers delete the key on release")
+      ]
+    };
+  }
+  validateNonEmptyString(violations, lease.holder, "holder", "lease.execution-lease.missing-holder", "lease.execution-lease.invalid-holder");
+  if (lease.claimed_at === undefined) {
+    violations.push(violation("high", "lease.execution-lease.missing-claimed-at", "missing required field: claimed_at"));
+  } else if (!isValidClaimedAt(lease.claimed_at)) {
+    violations.push(violation("medium", "lease.execution-lease.invalid-claimed-at", "claimed_at must be an RFC 3339 UTC timestamp with explicit Z (e.g. 2026-07-22T02:30:00Z) or a YYYY-MM-DD date"));
+  }
+  if (lease.worktree_path === undefined) {
+    violations.push(violation("high", "lease.execution-lease.missing-worktree-path", "missing required field: worktree_path"));
+  } else if (typeof lease.worktree_path !== "string" || lease.worktree_path.trim() === "") {
+    violations.push(violation("medium", "lease.execution-lease.invalid-worktree-path", "worktree_path must be a non-empty string"));
+  } else if (!isAbsolute22(lease.worktree_path)) {
+    violations.push(violation("medium", "lease.execution-lease.invalid-worktree-path", "worktree_path must be an absolute path — it identifies the dedicated feature-worktree root (and MUST differ from metadata.control_worktree_path)"));
+  }
+  validateNonEmptyString(violations, lease.working_branch, "working_branch", "lease.execution-lease.missing-working-branch", "lease.execution-lease.invalid-working-branch");
+  if (lease.session_label !== undefined && typeof lease.session_label !== "string") {
+    violations.push(violation("medium", "lease.execution-lease.invalid-session-label", "session_label must be a string (display only — never used for ownership comparison)"));
+  }
+  return { ok: violations.length === 0, violations };
+}
+function planExecutionLeaseLocations(row) {
+  const meta = row.metadata;
+  const metadataLease = meta && typeof meta === "object" && !Array.isArray(meta) ? meta.execution_lease : undefined;
+  return { row: row.execution_lease, metadata: metadataLease };
+}
+function verifyPlanExecutionLease(row, planId) {
+  const { row: rowLease, metadata: metadataLease } = planExecutionLeaseLocations(row);
+  const lease = rowLease !== undefined ? rowLease : metadataLease;
+  if (lease === undefined) {
+    if (row.status === "InProgress") {
+      return {
+        ok: false,
+        violations: [
+          violation("high", "lease.verify.orphan", "plan is InProgress without an execution_lease — orphan: STOP, no writable dispatch until recovery (status-and-residuals.md § Orphan recovery)")
+        ]
+      };
+    }
+    return {
+      ok: false,
+      violations: [
+        violation("high", "lease.verify.missing", `plan ${planId} has no execution_lease (neither plans[].execution_lease nor legacy plans[].metadata.execution_lease)`)
+      ]
+    };
+  }
+  const violations = [];
+  if (rowLease !== undefined && metadataLease !== undefined) {
+    violations.push(violation("high", "lease.verify.dual-write", "execution_lease present in BOTH plans[].execution_lease (SSOT) and plans[].metadata.execution_lease — the row-level lease wins; delete the metadata copy to remove the dual write"));
+  } else if (rowLease === undefined) {
+    violations.push(violation("high", "lease.verify.non-ssot-location", "execution_lease found only under plans[].metadata.execution_lease — the SSOT location is plans[].execution_lease; the metadata location is a legacy/hand-written read-compat fallback, not equivalent to SSOT success (migrate the lease to the plan row)"));
+  }
+  violations.push(...validateExecutionLease(lease).violations);
+  return { ok: violations.length === 0, violations, lease };
+}
+var heldLockDirs2 = new AsyncLocalStorage3;
+var GIT_CAPTURE_MAX_BYTES2 = 64 * 1024 * 1024;
+var WALK_SKIP_DIRS2 = new Set(["node_modules", ".git", "dist"]);
 // src/agent-plugins.ts
-import fs2 from "node:fs";
+import fs from "node:fs";
 import path3 from "node:path";
 
 // src/utils.ts
-import fs from "node:fs";
 import path2 from "node:path";
-import { fileURLToPath } from "node:url";
 function ensureObject(value) {
   if (value && typeof value === "object" && !Array.isArray(value))
     return value;
   return {};
 }
-function readJson(filePath) {
-  if (!fs.existsSync(filePath))
-    return {};
-  const content = fs.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 = path2.dirname(filePath);
-  if (!fs.existsSync(parent))
-    fs.mkdirSync(parent, { recursive: true });
-  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}
-`, "utf8");
-}
-function resolveProjectRoot() {
+function resolveProjectRoot2() {
   const candidate = process.env.MSTAR_CLI_PROJECT_ROOT || process.env.INIT_CWD || process.env.PWD;
   if (candidate && candidate.trim())
     return path2.resolve(candidate);
-  return process.cwd();
-}
-function readHarnessVersion() {
-  const packageJsonPath = path2.resolve(path2.dirname(fileURLToPath(import.meta.url)), "../package.json");
-  try {
-    const parsed = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
-    return parsed.version || "0.0.0";
-  } catch {
-    return "0.0.0";
-  }
+  return resolveProjectRoot();
 }
 
 // src/agent-plugins.ts
@@ -4069,18 +6553,18 @@ function describeType(value) {
     return "array";
   return typeof value;
 }
-function isPlainObject2(value) {
+function isPlainObject6(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function parseScalar(raw) {
+function parseScalar3(raw) {
   const trimmed = raw.trim();
   if (trimmed.length >= 2 && (trimmed.startsWith('"') && trimmed.endsWith('"') || trimmed.startsWith("'") && trimmed.endsWith("'"))) {
     return trimmed.slice(1, -1);
   }
   return trimmed;
 }
-function parseFrontmatter(filePath) {
-  const content = fs2.readFileSync(filePath, "utf8");
+function parseFrontmatter2(filePath) {
+  const content = fs.readFileSync(filePath, "utf8");
   const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n/);
   if (!match)
     return null;
@@ -4089,7 +6573,7 @@ function parseFrontmatter(filePath) {
     const field = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
     if (!field)
       continue;
-    result[field[1]] = parseScalar(field[2]);
+    result[field[1]] = parseScalar3(field[2]);
   }
   return result;
 }
@@ -4113,7 +6597,7 @@ function isValidMcpUrl(raw) {
   return true;
 }
 function validateManifest(manifest, errors2, warnings) {
-  if (!isPlainObject2(manifest)) {
+  if (!isPlainObject6(manifest)) {
     errors2.push("plugin.json: manifest must be a JSON object");
     return;
   }
@@ -4149,7 +6633,7 @@ function validateManifest(manifest, errors2, warnings) {
     }
   }
   if (doc.author !== undefined) {
-    if (!isPlainObject2(doc.author)) {
+    if (!isPlainObject6(doc.author)) {
       errors2.push('plugin.json: "author" must be an object with optional string fields name/email/url');
     } else {
       const author = doc.author;
@@ -4172,11 +6656,11 @@ function validateManifest(manifest, errors2, warnings) {
     }
   }
   if (doc.extensions !== undefined) {
-    if (!isPlainObject2(doc.extensions)) {
+    if (!isPlainObject6(doc.extensions)) {
       warnings.push('plugin.json: "extensions" is not an object — ignored');
     } else {
       for (const [namespace, value] of Object.entries(doc.extensions)) {
-        if (!isPlainObject2(value)) {
+        if (!isPlainObject6(value)) {
           warnings.push(`plugin.json: "extensions.${namespace}" is not an object — ignored`);
         }
       }
@@ -4185,7 +6669,7 @@ function validateManifest(manifest, errors2, warnings) {
 }
 function validateMcpServer(name, entry, errors2) {
   const prefix = `mcp.json: mcpServers.${name}`;
-  if (!isPlainObject2(entry)) {
+  if (!isPlainObject6(entry)) {
     errors2.push(`${prefix} must be an object`);
     return;
   }
@@ -4219,7 +6703,7 @@ function validateMcpServer(name, entry, errors2) {
       }
     }
     if (server.env !== undefined) {
-      if (!isPlainObject2(server.env)) {
+      if (!isPlainObject6(server.env)) {
         errors2.push(`${prefix}: "env" must be an object of strings`);
       } else {
         for (const [key, value] of Object.entries(server.env)) {
@@ -4258,7 +6742,7 @@ function validateMcpServer(name, entry, errors2) {
     errors2.push(`${prefix}: "url" must be an absolute http(s) URL without user info or fragment; non-loopback endpoints must use https`);
   }
   if (server.headers !== undefined) {
-    if (!isPlainObject2(server.headers)) {
+    if (!isPlainObject6(server.headers)) {
       errors2.push(`${prefix}: "headers" must be an object of strings`);
     } else {
       const seen = new Set;
@@ -4286,16 +6770,16 @@ function validateMcpServer(name, entry, errors2) {
 }
 function validateMcp(root, manifestSchema, errors2) {
   const mcpPath = path3.join(root, "mcp.json");
-  if (!fs2.existsSync(mcpPath))
+  if (!fs.existsSync(mcpPath))
     return;
   let parsed;
   try {
-    parsed = readJson(mcpPath);
+    parsed = readJson2(mcpPath);
   } catch (error) {
     errors2.push(`mcp.json: ${error.message}`);
     return;
   }
-  if (!isPlainObject2(parsed)) {
+  if (!isPlainObject6(parsed)) {
     errors2.push("mcp.json: configuration must be a JSON object");
     return;
   }
@@ -4318,7 +6802,7 @@ function validateMcp(root, manifestSchema, errors2) {
     }
   }
   const servers = doc.mcpServers;
-  if (!isPlainObject2(servers)) {
+  if (!isPlainObject6(servers)) {
     errors2.push('mcp.json: "mcpServers" is required and must be an object');
     return;
   }
@@ -4329,36 +6813,36 @@ function validateMcp(root, manifestSchema, errors2) {
 function validateSkills(root, errors2, warnings) {
   const skillsPath = path3.join(root, "skills");
   try {
-    if (!fs2.existsSync(skillsPath))
+    if (!fs.existsSync(skillsPath))
       return;
-    if (!fs2.statSync(skillsPath).isDirectory()) {
+    if (!fs.statSync(skillsPath).isDirectory()) {
       errors2.push("skills: skills/ is not a directory (component type invalid)");
       return;
     }
-    const entries = fs2.readdirSync(skillsPath, { withFileTypes: true });
-    const realRoot = fs2.realpathSync(root);
+    const entries = fs.readdirSync(skillsPath, { withFileTypes: true });
+    const realRoot = fs.realpathSync(root);
     for (const entry of entries) {
       if (!entry.isDirectory() && !entry.isSymbolicLink())
         continue;
       const skillDir = entry.name;
       let realSkillPath;
       try {
-        realSkillPath = fs2.realpathSync(path3.join(skillsPath, skillDir));
+        realSkillPath = fs.realpathSync(path3.join(skillsPath, skillDir));
       } catch (error) {
         warnings.push(`skills: ${skillDir}/ cannot be resolved (${error.message}; skill skipped)`);
         continue;
       }
-      const relative = path3.relative(realRoot, realSkillPath);
-      if (relative === ".." || relative.startsWith(`..${path3.sep}`) || path3.isAbsolute(relative)) {
+      const relative3 = path3.relative(realRoot, realSkillPath);
+      if (relative3 === ".." || relative3.startsWith(`..${path3.sep}`) || path3.isAbsolute(relative3)) {
         warnings.push(`skills: ${skillDir}/ resolves outside the plugin root (${realSkillPath}; skill skipped)`);
         continue;
       }
       const skillMdPath = path3.join(skillsPath, skillDir, "SKILL.md");
-      if (!fs2.existsSync(skillMdPath) || !fs2.statSync(skillMdPath).isFile()) {
+      if (!fs.existsSync(skillMdPath) || !fs.statSync(skillMdPath).isFile()) {
         warnings.push(`skills: ${skillDir}/ has no SKILL.md (directory is not a skill; ignored)`);
         continue;
       }
-      const frontmatter = parseFrontmatter(skillMdPath);
+      const frontmatter = parseFrontmatter2(skillMdPath);
       if (!frontmatter) {
         warnings.push(`skills: ${skillDir}/SKILL.md is missing YAML frontmatter (name and description are required; skill skipped)`);
         continue;
@@ -4391,19 +6875,19 @@ function validateAgentPlugin(root) {
   const errors2 = [];
   const warnings = [];
   const manifestPath = path3.join(root, "plugin.json");
-  if (!fs2.existsSync(manifestPath)) {
+  if (!fs.existsSync(manifestPath)) {
     errors2.push(`plugin.json: manifest not found at ${manifestPath} (plugin root must contain plugin.json)`);
     return { ok: false, errors: errors2, warnings };
   }
   let manifest;
   try {
-    manifest = readJson(manifestPath);
+    manifest = readJson2(manifestPath);
   } catch (error) {
     errors2.push(`plugin.json: ${error.message}`);
     return { ok: false, errors: errors2, warnings };
   }
   validateManifest(manifest, errors2, warnings);
-  const manifestSchema = isPlainObject2(manifest) ? manifest["$schema"] : undefined;
+  const manifestSchema = isPlainObject6(manifest) ? manifest["$schema"] : undefined;
   validateMcp(root, manifestSchema, errors2);
   validateSkills(root, errors2, warnings);
   return { ok: errors2.length === 0, errors: errors2, warnings };
@@ -4459,15 +6943,15 @@ function buildModelAssignments(selections) {
 }
 
 // src/adapters/codex.ts
-import fs4 from "node:fs";
+import fs3 from "node:fs";
 import os2 from "node:os";
 import path5 from "node:path";
 
 // src/adapters/shared-install.ts
-import fs3 from "node:fs";
+import fs2 from "node:fs";
 import os from "node:os";
 import path4 from "node:path";
-import { execFileSync } from "node:child_process";
+import { execFileSync as execFileSync3 } from "node:child_process";
 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");
@@ -4479,14 +6963,14 @@ var HARNESS_MARKERS = [
 function harnessMarkerPath() {
   for (const marker of HARNESS_MARKERS) {
     const candidate = path4.join(HARNESS_REPO_PATH, marker);
-    if (fs3.existsSync(candidate))
+    if (fs2.existsSync(candidate))
       return candidate;
   }
   return path4.join(HARNESS_REPO_PATH, HARNESS_MARKERS[0]);
 }
 function pathOrSymlinkExists(filePath) {
   try {
-    fs3.lstatSync(filePath);
+    fs2.lstatSync(filePath);
     return true;
   } catch {
     return false;
@@ -4495,17 +6979,17 @@ function pathOrSymlinkExists(filePath) {
 function ensureDir(dirPath, dryRun) {
   if (dryRun)
     return;
-  if (!fs3.existsSync(dirPath))
-    fs3.mkdirSync(dirPath, { recursive: true });
+  if (!fs2.existsSync(dirPath))
+    fs2.mkdirSync(dirPath, { recursive: true });
 }
 function runCommand(command, cwd, dryRun) {
   if (dryRun)
     return;
-  execFileSync(command[0], command.slice(1), { cwd, stdio: "pipe", encoding: "utf8" });
+  execFileSync3(command[0], command.slice(1), { cwd, stdio: "pipe", encoding: "utf8" });
 }
 function ensureLocalHarnessRepo(dryRun) {
   const notes = [];
-  if (fs3.existsSync(HARNESS_REPO_PATH)) {
+  if (fs2.existsSync(HARNESS_REPO_PATH)) {
     const errors2 = validateLocalHarnessRepo();
     if (errors2.length) {
       throw new Error(errors2.join(`
@@ -4521,12 +7005,12 @@ function ensureLocalHarnessRepo(dryRun) {
 }
 function validateLocalHarnessRepo() {
   const errors2 = [];
-  if (!fs3.existsSync(HARNESS_REPO_PATH)) {
+  if (!fs2.existsSync(HARNESS_REPO_PATH)) {
     errors2.push(`Missing local harness repo: ${HARNESS_REPO_PATH}`);
     return errors2;
   }
   const marker = harnessMarkerPath();
-  if (!fs3.existsSync(marker)) {
+  if (!fs2.existsSync(marker)) {
     errors2.push(`Local harness repo is missing a plugin marker (expected one of: ${HARNESS_MARKERS.join(", ")}).`);
   }
   return errors2;
@@ -4535,13 +7019,13 @@ function ensureGitCheckout(repoUrl, checkoutPath, dryRun) {
   const notes = [];
   const parentDir = path4.dirname(checkoutPath);
   if (pathOrSymlinkExists(checkoutPath)) {
-    const stat = fs3.lstatSync(checkoutPath);
+    const stat = fs2.lstatSync(checkoutPath);
     if (stat.isSymbolicLink()) {
       notes.push(dryRun ? `Would remove symlink at ${checkoutPath} and clone ${repoUrl}` : `Removed symlink at ${checkoutPath} (Cursor requires a real directory)`);
       if (dryRun)
         return notes;
-      fs3.unlinkSync(checkoutPath);
-    } else if (fs3.existsSync(path4.join(checkoutPath, ".git"))) {
+      fs2.unlinkSync(checkoutPath);
+    } else if (fs2.existsSync(path4.join(checkoutPath, ".git"))) {
       if (!dryRun) {
         runCommand(["git", "-C", checkoutPath, "pull", "--ff-only"], checkoutPath, dryRun);
       }
@@ -4564,31 +7048,31 @@ function validateGitCheckout(checkoutPath, markerRelativePath) {
     errors2.push(`Missing checkout directory: ${checkoutPath}`);
     return errors2;
   }
-  const stat = fs3.lstatSync(checkoutPath);
+  const stat = fs2.lstatSync(checkoutPath);
   if (stat.isSymbolicLink()) {
     errors2.push(`Path must be a real directory, not a symlink: ${checkoutPath}. Run: mstar-harness init --target cursor`);
     return errors2;
   }
-  if (!fs3.existsSync(path4.join(checkoutPath, ".git"))) {
+  if (!fs2.existsSync(path4.join(checkoutPath, ".git"))) {
     errors2.push(`Path is not a git checkout: ${checkoutPath}`);
   }
   const marker = path4.join(checkoutPath, markerRelativePath);
-  if (!fs3.existsSync(marker)) {
+  if (!fs2.existsSync(marker)) {
     errors2.push(`Missing marker file: ${marker}`);
   }
   return errors2;
 }
 function ensureSymlink(target, linkPath, dryRun) {
   if (pathOrSymlinkExists(linkPath)) {
-    const stat = fs3.lstatSync(linkPath);
+    const stat = fs2.lstatSync(linkPath);
     if (!stat.isSymbolicLink()) {
       throw new Error(`Path exists and is not a symlink: ${linkPath}`);
     }
-    if (!fs3.existsSync(target)) {
+    if (!fs2.existsSync(target)) {
       throw new Error(`Symlink target is missing: ${target}`);
     }
-    const actual = fs3.realpathSync(linkPath);
-    const expected = fs3.realpathSync(target);
+    const actual = fs2.realpathSync(linkPath);
+    const expected = fs2.realpathSync(target);
     if (actual !== expected) {
       throw new Error(`Symlink ${linkPath} points to ${actual}, expected ${expected}`);
     }
@@ -4596,7 +7080,7 @@ function ensureSymlink(target, linkPath, dryRun) {
   }
   ensureDir(path4.dirname(linkPath), dryRun);
   if (!dryRun)
-    fs3.symlinkSync(target, linkPath);
+    fs2.symlinkSync(target, linkPath);
   return `Linked ${linkPath} -> ${target}`;
 }
 function validateSymlink(target, linkPath) {
@@ -4605,17 +7089,17 @@ function validateSymlink(target, linkPath) {
     errors2.push(`Missing symlink: ${linkPath}`);
     return errors2;
   }
-  const stat = fs3.lstatSync(linkPath);
+  const stat = fs2.lstatSync(linkPath);
   if (!stat.isSymbolicLink()) {
     errors2.push(`Path exists but is not a symlink: ${linkPath}`);
     return errors2;
   }
-  if (!fs3.existsSync(target)) {
+  if (!fs2.existsSync(target)) {
     errors2.push(`Symlink target is missing: ${target}`);
     return errors2;
   }
-  const actual = fs3.realpathSync(linkPath);
-  const expected = fs3.realpathSync(target);
+  const actual = fs2.realpathSync(linkPath);
+  const expected = fs2.realpathSync(target);
   if (actual !== expected) {
     errors2.push(`Symlink ${linkPath} points to ${actual}, expected ${expected}`);
   }
@@ -4641,7 +7125,7 @@ function missingHarnessProcessGitignoreEntries(gitignoreContent) {
 }
 function appendGitignore(projectRoot, entries, dryRun) {
   const gitignorePath = path4.join(projectRoot, ".gitignore");
-  const current = fs3.existsSync(gitignorePath) ? fs3.readFileSync(gitignorePath, "utf8") : "";
+  const current = fs2.existsSync(gitignorePath) ? fs2.readFileSync(gitignorePath, "utf8") : "";
   const lines = new Set(current.split(/\r?\n/).map((line) => line.trim()));
   const missing = entries.filter((entry) => !lines.has(entry));
   if (!missing.length)
@@ -4650,7 +7134,7 @@ function appendGitignore(projectRoot, entries, dryRun) {
     const prefix = current && !current.endsWith(`
 `) ? `
 ` : "";
-    fs3.appendFileSync(gitignorePath, `${prefix}${missing.join(`
+    fs2.appendFileSync(gitignorePath, `${prefix}${missing.join(`
 `)}
 `, "utf8");
   }
@@ -4695,7 +7179,7 @@ function globalMarketplacePath() {
   return GLOBAL_MARKETPLACE_PATH;
 }
 function projectMarketplacePath() {
-  return path5.join(resolveProjectRoot(), ".agents", "plugins", "marketplace.json");
+  return path5.join(resolveProjectRoot2(), ".agents", "plugins", "marketplace.json");
 }
 function agentSourcePath(agentName) {
   return path5.join(HARNESS_REPO_PATH, "codex", "agents", `${agentName}.toml`);
@@ -4704,7 +7188,7 @@ function globalAgentLinkPath(agentName) {
   return path5.join(os2.homedir(), ".codex", "agents", `${agentName}.toml`);
 }
 function projectAgentLinkPath(agentName) {
-  return path5.join(resolveProjectRoot(), ".codex", "agents", `${agentName}.toml`);
+  return path5.join(resolveProjectRoot2(), ".codex", "agents", `${agentName}.toml`);
 }
 function mstarEntry(scope) {
   const sourcePath = scope === "global" ? homeRelativeSourcePath(HARNESS_REPO_PATH) : `./${CODEX_PLUGIN_LINK}`;
@@ -4798,14 +7282,14 @@ function iterationCommandSourcePath(skillName) {
   return path5.join(HARNESS_REPO_PATH, "commands", `${skillName}.md`);
 }
 function projectIterationSkillLinkPath(skillName) {
-  return path5.join(resolveProjectRoot(), ".agents", "skills", skillName, "SKILL.md");
+  return path5.join(resolveProjectRoot2(), ".agents", "skills", skillName, "SKILL.md");
 }
 function iterationSkillGitignoreEntry(skillName) {
   return `.agents/skills/${skillName}`;
 }
 function ensureIterationSkillLinks(dryRun) {
   const notes = [];
-  const projectRoot = resolveProjectRoot();
+  const projectRoot = resolveProjectRoot2();
   for (const skillName of CODEX_PROJECT_COMMAND_NAMES) {
     const source = iterationCommandSourcePath(skillName);
     const linkPath = projectIterationSkillLinkPath(skillName);
@@ -4818,9 +7302,9 @@ function ensureIterationSkillLinks(dryRun) {
 }
 function validateIterationSkillLinks() {
   const errors2 = [];
-  const projectRoot = resolveProjectRoot();
+  const projectRoot = resolveProjectRoot2();
   const gitignorePath = path5.join(projectRoot, ".gitignore");
-  const gitignore = fs4.existsSync(gitignorePath) ? fs4.readFileSync(gitignorePath, "utf8") : "";
+  const gitignore = fs3.existsSync(gitignorePath) ? fs3.readFileSync(gitignorePath, "utf8") : "";
   const lines = gitignore.split(/\r?\n/);
   for (const skillName of CODEX_PROJECT_COMMAND_NAMES) {
     const source = iterationCommandSourcePath(skillName);
@@ -4834,12 +7318,12 @@ function validateIterationSkillLinks() {
 }
 function runInit(scope, dryRun) {
   const pathToMarketplace = marketplacePath(scope);
-  const current = readJson(pathToMarketplace);
+  const current = readJson2(pathToMarketplace);
   const next = upsertEntry(current, scope);
   const existingEntry = findEntry(current);
   const notes = ensureLocalHarnessRepo(dryRun);
   if (scope === "project") {
-    const projectRoot = resolveProjectRoot();
+    const projectRoot = resolveProjectRoot2();
     notes.push(ensureSymlink(HARNESS_REPO_PATH, path5.join(projectRoot, CODEX_PLUGIN_LINK), dryRun));
     notes.push(...appendGitignore(projectRoot, [CODEX_PLUGIN_LINK, ".codex/agents/*.toml"], dryRun));
     notes.push(...appendHarnessProjectGitignore(projectRoot, dryRun));
@@ -4849,7 +7333,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}`);
@@ -4861,19 +7345,19 @@ function runInit(scope, dryRun) {
 function runDoctor(scope) {
   const pathToMarketplace = marketplacePath(scope);
   const errors2 = validateLocalHarnessRepo();
-  if (!fs4.existsSync(pathToMarketplace)) {
+  if (!fs3.existsSync(pathToMarketplace)) {
     return { location: pathToMarketplace, errors: [...errors2, `Missing Codex marketplace: ${pathToMarketplace}`] };
   }
-  const marketplace = readJson(pathToMarketplace);
+  const marketplace = readJson2(pathToMarketplace);
   if (marketplace.name !== MARKETPLACE_NAME) {
     errors2.push(`Codex personal marketplace name must be ${MARKETPLACE_NAME}.`);
   }
   errors2.push(...validateEntryShape(findEntry(marketplace), scope, pathToMarketplace));
   if (scope === "project") {
-    const projectRoot = resolveProjectRoot();
+    const projectRoot = resolveProjectRoot2();
     errors2.push(...validateSymlink(HARNESS_REPO_PATH, path5.join(projectRoot, CODEX_PLUGIN_LINK)));
     const gitignorePath = path5.join(projectRoot, ".gitignore");
-    const gitignore = fs4.existsSync(gitignorePath) ? fs4.readFileSync(gitignorePath, "utf8") : "";
+    const gitignore = fs3.existsSync(gitignorePath) ? fs3.readFileSync(gitignorePath, "utf8") : "";
     const lines = gitignore.split(/\r?\n/);
     if (!lines.includes(CODEX_PLUGIN_LINK))
       errors2.push(`Missing .gitignore entry: ${CODEX_PLUGIN_LINK}`);
@@ -4895,7 +7379,7 @@ var codexAdapter = {
 };
 
 // src/adapters/cursor.ts
-import fs5 from "node:fs";
+import fs4 from "node:fs";
 import os3 from "node:os";
 import path6 from "node:path";
 var CURSOR_PLUGIN_NAME = "morning-star-harness";
@@ -4906,22 +7390,22 @@ function globalInstallPath() {
   return path6.join(os3.homedir(), ".cursor", "plugins", "local", CURSOR_PLUGIN_NAME);
 }
 function projectInstallPath() {
-  return path6.join(resolveProjectRoot(), CURSOR_PLUGIN_LINK);
+  return path6.join(resolveProjectRoot2(), CURSOR_PLUGIN_LINK);
 }
 function validatePluginAgents(pluginRoot) {
   const errors2 = [];
   const agentsDir = path6.join(pluginRoot, "agents");
-  if (!fs5.existsSync(agentsDir)) {
+  if (!fs4.existsSync(agentsDir)) {
     errors2.push(`Missing plugin agents directory: ${agentsDir}`);
     return errors2;
   }
   for (const agentName of CURSOR_AGENT_SMOKE_NAMES) {
     const agentPath = path6.join(agentsDir, `${agentName}.md`);
-    if (!fs5.existsSync(agentPath)) {
+    if (!fs4.existsSync(agentPath)) {
       errors2.push(`Missing plugin agent file: ${agentPath}`);
       continue;
     }
-    const content = fs5.readFileSync(agentPath, "utf8");
+    const content = fs4.readFileSync(agentPath, "utf8");
     if (!/^---\nname:\s/m.test(content)) {
       errors2.push(`Plugin agent ${agentName}.md must use Cursor-first frontmatter (name, description, model before OpenCode fields).`);
     }
@@ -4938,7 +7422,7 @@ function globalInit(dryRun) {
   return { location, notes };
 }
 function projectInit(dryRun) {
-  const projectRoot = resolveProjectRoot();
+  const projectRoot = resolveProjectRoot2();
   const location = projectInstallPath();
   const notes = ensureLocalHarnessRepo(dryRun);
   notes.push(...ensureCursorPluginCheckout(location, dryRun));
@@ -4954,12 +7438,12 @@ function globalDoctor() {
   return { location, errors: errors2 };
 }
 function projectDoctor() {
-  const projectRoot = resolveProjectRoot();
+  const projectRoot = resolveProjectRoot2();
   const location = projectInstallPath();
   const errors2 = validateLocalHarnessRepo();
   errors2.push(...validateGitCheckout(location, CURSOR_PLUGIN_MARKER));
   const gitignorePath = path6.join(projectRoot, ".gitignore");
-  const gitignore = fs5.existsSync(gitignorePath) ? fs5.readFileSync(gitignorePath, "utf8") : "";
+  const gitignore = fs4.existsSync(gitignorePath) ? fs4.readFileSync(gitignorePath, "utf8") : "";
   if (!gitignore.split(/\r?\n/).includes(CURSOR_PLUGIN_LINK)) {
     errors2.push(`Missing .gitignore entry: ${CURSOR_PLUGIN_LINK}`);
   }
@@ -4985,9 +7469,9 @@ var cursorAdapter = {
 };
 
 // src/adapters/omp.ts
-import fs6 from "node:fs";
+import fs5 from "node:fs";
 import path7 from "node:path";
-import { execFileSync as execFileSync2 } from "node:child_process";
+import { execFileSync as execFileSync5 } 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"]);
@@ -4995,7 +7479,7 @@ var SKILL_SMOKE = ["mstar-host", "mstar-harness-core", "pm"];
 var COMMAND_SMOKE = ["iteration-start", "iteration-drive", "iteration-loop", "codebase-audit"];
 function ompAvailable() {
   try {
-    execFileSync2("omp", ["--version"], { stdio: "pipe", encoding: "utf8" });
+    execFileSync5("omp", ["--version"], { stdio: "pipe", encoding: "utf8" });
     return true;
   } catch {
     return false;
@@ -5004,11 +7488,11 @@ function ompAvailable() {
 function runOmp(args, dryRun) {
   if (dryRun)
     return;
-  execFileSync2("omp", args, { stdio: "pipe", encoding: "utf8" });
+  execFileSync5("omp", args, { stdio: "pipe", encoding: "utf8" });
 }
 function listInstalledPlugins() {
   try {
-    const raw = execFileSync2("omp", ["plugin", "list", "--json"], {
+    const raw = execFileSync5("omp", ["plugin", "list", "--json"], {
       stdio: "pipe",
       encoding: "utf8"
     });
@@ -5057,34 +7541,34 @@ function validatePluginTree(pluginRoot) {
   const errors2 = [];
   for (const marker of [OMP_PLUGIN_MARKER, CLAUDE_PLUGIN_MARKER]) {
     const markerPath = path7.join(pluginRoot, marker);
-    if (!fs6.existsSync(markerPath)) {
+    if (!fs5.existsSync(markerPath)) {
       errors2.push(`Missing omp plugin marker: ${markerPath}`);
     }
   }
   for (const skill of SKILL_SMOKE) {
     const skillPath = path7.join(pluginRoot, "skills", skill, "SKILL.md");
-    if (!fs6.existsSync(skillPath))
+    if (!fs5.existsSync(skillPath))
       errors2.push(`Missing skill: ${skillPath}`);
   }
   for (const command of COMMAND_SMOKE) {
     const commandPath = path7.join(pluginRoot, "commands", `${command}.md`);
-    if (!fs6.existsSync(commandPath))
+    if (!fs5.existsSync(commandPath))
       errors2.push(`Missing command: ${commandPath}`);
   }
   const hostRef = path7.join(pluginRoot, "skills", "mstar-host", "references", "omp.md");
-  if (!fs6.existsSync(hostRef))
+  if (!fs5.existsSync(hostRef))
     errors2.push(`Missing omp host reference: ${hostRef}`);
   return errors2;
 }
 function runInit2(scope, dryRun) {
   const notes = ensureLocalHarnessRepo(dryRun);
-  const projectRoot = resolveProjectRoot();
-  if (fs6.existsSync(path7.join(HARNESS_REPO_PATH, ".git"))) {
+  const projectRoot = resolveProjectRoot2();
+  if (fs5.existsSync(path7.join(HARNESS_REPO_PATH, ".git"))) {
     if (dryRun) {
       notes.push(`Would update local harness repo: git -C ${HARNESS_REPO_PATH} pull --ff-only`);
     } else {
       try {
-        execFileSync2("git", ["-C", HARNESS_REPO_PATH, "pull", "--ff-only"], {
+        execFileSync5("git", ["-C", HARNESS_REPO_PATH, "pull", "--ff-only"], {
           stdio: "pipe",
           encoding: "utf8"
         });
@@ -5152,9 +7636,9 @@ function runDoctor2(scope) {
     }
   }
   if (scope === "project") {
-    const projectRoot = resolveProjectRoot();
+    const projectRoot = resolveProjectRoot2();
     const gitignorePath = path7.join(projectRoot, ".gitignore");
-    const gitignore = fs6.existsSync(gitignorePath) ? fs6.readFileSync(gitignorePath, "utf8") : "";
+    const gitignore = fs5.existsSync(gitignorePath) ? fs5.readFileSync(gitignorePath, "utf8") : "";
     for (const entry of missingHarnessProcessGitignoreEntries(gitignore)) {
       errors2.push(`Missing .gitignore entry: ${entry}`);
     }
@@ -5191,11 +7675,11 @@ function isAnyMstarHarnessOpencodeSlot(plugin) {
 function resolveOpencodeConfigPath(scope, outputPath) {
   if (outputPath && outputPath.trim()) {
     const raw = outputPath.trim();
-    return path8.isAbsolute(raw) ? raw : path8.join(resolveProjectRoot(), raw);
+    return path8.isAbsolute(raw) ? raw : path8.join(resolveProjectRoot2(), raw);
   }
   if (scope === "global")
     return path8.join(os4.homedir(), ".config", "opencode", "opencode.json");
-  return path8.join(resolveProjectRoot(), "opencode.json");
+  return path8.join(resolveProjectRoot2(), "opencode.json");
 }
 function ensureConfigSchema(config) {
   const next = ensureObject(config);
@@ -5288,7 +7772,7 @@ var opencodeAdapter = {
 };
 
 // src/adapters/zcode.ts
-import fs7 from "node:fs";
+import fs6 from "node:fs";
 import os5 from "node:os";
 import path9 from "node:path";
 var MARKETPLACE_ID = "mstar-local";
@@ -5360,11 +7844,11 @@ function findMarketplacePlugin(raw) {
 }
 function validateMarketplaceJson() {
   const errors2 = [];
-  if (!fs7.existsSync(MARKETPLACE_JSON_PATH)) {
+  if (!fs6.existsSync(MARKETPLACE_JSON_PATH)) {
     errors2.push(`Missing ZCode marketplace: ${MARKETPLACE_JSON_PATH}`);
     return errors2;
   }
-  const raw = readJson(MARKETPLACE_JSON_PATH);
+  const raw = readJson2(MARKETPLACE_JSON_PATH);
   if (raw.name !== MARKETPLACE_NAME2) {
     errors2.push(`ZCode marketplace name must be ${MARKETPLACE_NAME2} (in ${MARKETPLACE_JSON_PATH}).`);
   }
@@ -5389,11 +7873,11 @@ function validateMarketplaceJson() {
 }
 function validateKnownMarketplaces() {
   const errors2 = [];
-  if (!fs7.existsSync(KNOWN_MARKETPLACES_PATH)) {
+  if (!fs6.existsSync(KNOWN_MARKETPLACES_PATH)) {
     errors2.push(`Missing ZCode known_marketplaces.json: ${KNOWN_MARKETPLACES_PATH}`);
     return errors2;
   }
-  const raw = readJson(KNOWN_MARKETPLACES_PATH);
+  const raw = readJson2(KNOWN_MARKETPLACES_PATH);
   const entry = findKnownMarketplace(raw);
   if (!entry) {
     errors2.push(`Missing ${MARKETPLACE_ID} entry in ${KNOWN_MARKETPLACES_PATH}.`);
@@ -5413,13 +7897,13 @@ function validateKnownMarketplaces() {
 function validatePluginAgents2(pluginRoot) {
   const errors2 = [];
   const agentsDir = path9.join(pluginRoot, "agents");
-  if (!fs7.existsSync(agentsDir)) {
+  if (!fs6.existsSync(agentsDir)) {
     errors2.push(`Missing plugin agents directory: ${agentsDir}`);
     return errors2;
   }
   for (const agentName of ZCODE_AGENT_SMOKE_NAMES) {
     const agentPath = path9.join(agentsDir, `${agentName}.md`);
-    if (!fs7.existsSync(agentPath)) {
+    if (!fs6.existsSync(agentPath)) {
       errors2.push(`Missing plugin agent file: ${agentPath}`);
     }
   }
@@ -5434,7 +7918,7 @@ function buildMarketplaceJson() {
 }
 function runInit3(scope, dryRun) {
   const notes = ensureLocalHarnessRepo(dryRun);
-  const projectRoot = resolveProjectRoot();
+  const projectRoot = resolveProjectRoot2();
   if (scope === "project") {
     const checkoutPath = path9.join(projectRoot, ZCODE_PLUGIN_CHECKOUT_PROJECT);
     notes.push(...ensureGitCheckout(REPO_URL, checkoutPath, dryRun));
@@ -5443,15 +7927,15 @@ function runInit3(scope, dryRun) {
     notes.push(`Materialized local ZCode plugin checkout at ${ZCODE_PLUGIN_CHECKOUT_PROJECT} for smoke checks (the registered marketplace still points at the github repo).`);
   }
   if (!dryRun) {
-    if (!fs7.existsSync(MARKETPLACE_DIR))
-      fs7.mkdirSync(MARKETPLACE_DIR, { recursive: true });
-    writeJson(MARKETPLACE_JSON_PATH, buildMarketplaceJson());
+    if (!fs6.existsSync(MARKETPLACE_DIR))
+      fs6.mkdirSync(MARKETPLACE_DIR, { recursive: true });
+    writeJson2(MARKETPLACE_JSON_PATH, buildMarketplaceJson());
   }
   notes.push(`Wrote ZCode marketplace: ${MARKETPLACE_JSON_PATH}`);
-  const knownRaw = readJson(KNOWN_MARKETPLACES_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 → Plugin Management → Discover → install ${PLUGIN_NAME} from the ${MARKETPLACE_ID} marketplace.`);
   return {
@@ -5463,11 +7947,11 @@ function runDoctor3(scope) {
   const errors2 = [];
   errors2.push(...validateLocalHarnessRepo());
   if (scope === "project") {
-    const projectRoot = resolveProjectRoot();
+    const projectRoot = resolveProjectRoot2();
     const checkoutPath = path9.join(projectRoot, ZCODE_PLUGIN_CHECKOUT_PROJECT);
     errors2.push(...validateGitCheckout(checkoutPath, ZCODE_PLUGIN_MARKER));
     const gitignorePath = path9.join(projectRoot, ".gitignore");
-    const gitignore = fs7.existsSync(gitignorePath) ? fs7.readFileSync(gitignorePath, "utf8") : "";
+    const gitignore = fs6.existsSync(gitignorePath) ? fs6.readFileSync(gitignorePath, "utf8") : "";
     if (!gitignore.split(/\r?\n/).includes(ZCODE_PLUGIN_CHECKOUT_PROJECT)) {
       errors2.push(`Missing .gitignore entry: ${ZCODE_PLUGIN_CHECKOUT_PROJECT}`);
     }
@@ -5508,51 +7992,21 @@ function getAdapter(target) {
 var SUPPORTED_TARGETS = ["opencode", "cursor", "codex", "zcode", "omp"];
 
 // src/utils.ts
-import fs8 from "node:fs";
 import path10 from "node:path";
-import { fileURLToPath as fileURLToPath2 } from "node:url";
 function parseCsv(raw) {
   if (!raw)
     return;
   return raw.split(",").map((item) => item.trim()).filter(Boolean);
 }
-function readJson2(filePath) {
-  if (!fs8.existsSync(filePath))
-    return {};
-  const content = fs8.readFileSync(filePath, "utf8").trim();
-  if (!content)
-    return {};
-  try {
-    return JSON.parse(content);
-  } catch (error) {
-    throw new Error(`Invalid JSON in ${filePath}: ${error.message}`);
-  }
-}
-function writeJson2(filePath, value) {
-  const parent = path10.dirname(filePath);
-  if (!fs8.existsSync(parent))
-    fs8.mkdirSync(parent, { recursive: true });
-  fs8.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}
-`, "utf8");
-}
-function resolveProjectRoot2() {
+function resolveProjectRoot3() {
   const candidate = process.env.MSTAR_CLI_PROJECT_ROOT || process.env.INIT_CWD || process.env.PWD;
   if (candidate && candidate.trim())
     return path10.resolve(candidate);
-  return process.cwd();
-}
-function readHarnessVersion2() {
-  const packageJsonPath = path10.resolve(path10.dirname(fileURLToPath2(import.meta.url)), "../package.json");
-  try {
-    const parsed = JSON.parse(fs8.readFileSync(packageJsonPath, "utf8"));
-    return parsed.version || "0.0.0";
-  } catch {
-    return "0.0.0";
-  }
+  return resolveProjectRoot();
 }
 
 // src/index.ts
-var packageVersion = readHarnessVersion2();
+var packageVersion = readHarnessVersion();
 var program2 = new Command;
 function logStep(message) {
   console.log(import_picocolors.default.cyan(message));
@@ -5694,8 +8148,8 @@ function runDoctor4(options) {
 function resolvePluginRoot(options) {
   if (options.root)
     return path11.resolve(options.root);
-  let candidate = resolveProjectRoot2();
-  while (!fs9.existsSync(path11.join(candidate, "plugin.json"))) {
+  let candidate = resolveProjectRoot3();
+  while (!fs7.existsSync(path11.join(candidate, "plugin.json"))) {
     const parent = path11.dirname(candidate);
     if (parent === candidate)
       break;
@@ -5729,7 +8183,751 @@ var pluginCommand = program2.command("plugin").description("Agent Plugins v1.0.0
 pluginCommand.command("validate").description("Validate a plugin package against Agent Plugins v1.0.0").option("--root <path>", "Plugin root directory to validate (default: project root)").action((options) => {
   runPluginValidate(options);
 });
+var pathCommand = program2.command("path").description("harness/specs dir resolution checks (engine-backed)");
+pathCommand.command("resolve").description("Resolve {HARNESS_DIR} + {SPECS_DIR} from a start dir (exit 1 when no harness dir resolves)").argument("[path]", "Start dir to resolve from (default: cwd)").option("--json", "Machine-readable JSON output (ok, harnessDir, specsDir, guidance on failure)").action((pathArg, options) => {
+  const startDir = pathArg ? path11.resolve(pathArg) : process.cwd();
+  const harnessDir = resolveHarnessDir(startDir);
+  if (!harnessDir) {
+    const guidance = "no harness dir found (probed .mstar/, .agents/, .plans/, plans/ walking up from " + `${startDir}) \u2014 run \`mstar init\` to bootstrap, or pass a start dir inside a harness-enabled project`;
+    if (options.json) {
+      console.log(JSON.stringify({ ok: false, startDir, harnessDir: null, specsDir: null, guidance }));
+    } else {
+      console.error(import_picocolors.default.red(`path resolve: no harness dir from ${startDir}`));
+      console.error(`  guidance: ${guidance}`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+  const specsDir = resolveSpecsDir(harnessDir, { create: false });
+  if (options.json) {
+    console.log(JSON.stringify({ ok: true, startDir, harnessDir, specsDir }));
+  } else {
+    console.log(import_picocolors.default.green(`harness dir: ${harnessDir}`));
+    console.log(import_picocolors.default.green(`specs dir:   ${specsDir}`));
+  }
+});
+var statusCommand = program2.command("status").description("status.json schema + residual lifecycle checks (engine-backed)");
+function resolveStatusFilePath(pathArg) {
+  if (pathArg)
+    return path11.resolve(pathArg);
+  const harnessDir = resolveHarnessDir();
+  if (!harnessDir) {
+    throw new Error(`harness dir not found from ${process.cwd()} \u2014 pass a status.json path or set MSTAR_HARNESS_DIR`);
+  }
+  return path11.join(harnessDir, "status.json");
+}
+statusCommand.command("validate").description("Validate status.json (schema, severity enum, root-only residual_findings)").argument("[path]", "status.json path (default: {HARNESS_DIR}/status.json)").action((pathArg) => {
+  let statusPath;
+  try {
+    statusPath = resolveStatusFilePath(pathArg);
+    if (!fs7.existsSync(statusPath)) {
+      throw new Error(`status file not found: ${statusPath}`);
+    }
+    const gate2 = validateStatus(statusPath);
+    if (gate2.ok) {
+      console.log(import_picocolors.default.green(`${statusPath}: OK`));
+      return;
+    }
+    const count = gate2.violations.length;
+    console.error(import_picocolors.default.red(`${statusPath}: FAIL (${count} violation${count === 1 ? "" : "s"})`));
+    for (const violation7 of gate2.violations) {
+      console.error(`  - [${violation7.severity}] ${violation7.code}: ${violation7.message}`);
+      if (violation7.fix)
+        console.error(`    fix: ${violation7.fix}`);
+    }
+    process.exitCode = 1;
+  } catch (error) {
+    console.error(import_picocolors.default.red(`status validate failed: ${error.message}`));
+    process.exitCode = 1;
+  }
+});
+statusCommand.command("archive-residuals").description("Archive a plan's open residuals to archived/residuals/<plan-id>.json").argument("<plan-id>", "Plan id whose open residuals are archived").option("--harness <path>", "Harness dir override (default: resolved {HARNESS_DIR})").action(async (planId, options) => {
+  try {
+    const harnessDir = options.harness ?? resolveHarnessDir();
+    if (!harnessDir) {
+      throw new Error(`harness dir not found from ${process.cwd()} \u2014 pass --harness or set MSTAR_HARNESS_DIR`);
+    }
+    const result = await archiveResiduals(planId, harnessDir);
+    if (result.archived === 0) {
+      console.log(import_picocolors.default.yellow(`No open residuals for plan ${planId}`));
+    } else {
+      console.log(import_picocolors.default.green(`Archived ${result.archived} residual(s) for ${planId} -> ${result.archivePath}`));
+    }
+  } catch (error) {
+    console.error(import_picocolors.default.red(`archive-residuals failed: ${error.message}`));
+    process.exitCode = 1;
+  }
+});
+var leaseCommand = program2.command("lease").description("execution_lease checks (engine-backed) \u2014 integration_merge_lease validation stays import-only via @mstar-harness/engine until a dedicated subcommand exists");
+function resolveLeaseHarnessDir(harnessArg) {
+  if (harnessArg)
+    return path11.resolve(harnessArg);
+  const harnessDir = resolveHarnessDir();
+  if (!harnessDir) {
+    throw new Error(`harness dir not found from ${process.cwd()} \u2014 pass --harness or set MSTAR_HARNESS_DIR`);
+  }
+  return harnessDir;
+}
+leaseCommand.command("verify").description("Verify a plan's execution_lease (missing/invalid/non-SSOT location \u2192 exit 1 with violations)").argument("<plan-id>", "Plan id whose execution_lease is verified").option("--harness <path>", "Harness dir override (default: resolved {HARNESS_DIR})").action((planId, options) => {
+  try {
+    const harnessDir = resolveLeaseHarnessDir(options.harness);
+    const statusPath = path11.join(harnessDir, "status.json");
+    if (!fs7.existsSync(statusPath)) {
+      throw new Error(`status file not found: ${statusPath}`);
+    }
+    const doc = readJson2(statusPath);
+    const plans = Array.isArray(doc.plans) ? doc.plans : [];
+    const matches = plans.filter((row) => row?.id === planId || row?.plan_id === planId);
+    if (matches.length === 0) {
+      console.error(import_picocolors.default.red(`${statusPath}: FAIL plan ${planId}`));
+      console.error(`  - [high] lease.verify.plan-not-found: no plan row with id/plan_id ${planId}`);
+      process.exitCode = 1;
+      return;
+    }
+    if (matches.length > 1) {
+      console.error(import_picocolors.default.red(`${statusPath}: FAIL plan ${planId}`));
+      console.error("  - [high] lease.verify.ambiguous: multiple plan rows match (id and plan_id both present)");
+      process.exitCode = 1;
+      return;
+    }
+    const result = verifyPlanExecutionLease(matches[0], planId);
+    if (result.ok) {
+      const holder = String(result.lease.holder ?? "");
+      console.log(import_picocolors.default.green(`${statusPath}: OK plan ${planId} \u2014 execution_lease valid (holder ${holder})`));
+      return;
+    }
+    const count = result.violations.length;
+    console.error(import_picocolors.default.red(`${statusPath}: FAIL plan ${planId} (${count} violation${count === 1 ? "" : "s"})`));
+    for (const violation7 of result.violations) {
+      console.error(`  - [${violation7.severity}] ${violation7.code}: ${violation7.message}`);
+      if (violation7.fix)
+        console.error(`    fix: ${violation7.fix}`);
+    }
+    process.exitCode = 1;
+  } catch (error) {
+    console.error(import_picocolors.default.red(`lease verify failed: ${error.message}`));
+    process.exitCode = 1;
+  }
+});
+function failScript(error, context) {
+  if (error instanceof SddScriptError) {
+    console.error(import_picocolors.default.red(`${context} failed: ${error.message}`));
+    process.exitCode = error.exitCode;
+    return;
+  }
+  console.error(import_picocolors.default.red(`${context} failed: ${error.message}`));
+  process.exitCode = 1;
+}
+var sddCommand = program2.command("sdd").description("SDD workspace / task-brief / review-package helpers (engine-backed)");
+sddCommand.command("workspace").description("Resolve and ensure {SDD_DIR} for a plan (exit 1 on resolution failures, 2 on usage errors)").argument("[plan-id]", "Plan id whose SDD dir is resolved/created").argument("[control-root]", "Control worktree root (default: MSTAR_CONTROL_ROOT or the cwd's git top-level)").action((planId, controlRoot) => {
+  try {
+    if (!planId) {
+      throw new SddScriptError(`usage: mstar sdd workspace PLAN_ID [CONTROL_ROOT]
+` + "  Set MSTAR_CONTROL_ROOT=<control_worktree_path> when running from a feature worktree.", 2);
+    }
+    const sddDir = sddWorkspace(planId, controlRoot ? { controlRoot } : {});
+    console.log(import_picocolors.default.green(`sdd dir: ${sddDir}`));
+  } catch (error) {
+    failScript(error, "sdd workspace");
+  }
+});
+sddCommand.command("task-brief").description("Extract the `## Task N` section of a plan into a brief file (exit 3 when task N is missing)").argument("[plan-file]", "Plan markdown file").argument("[task-number]", "Task number whose brief is extracted").argument("[outfile]", "Output file (default: {SDD_DIR}/task-N-brief.md)").action((planFile, taskNumber, outfile) => {
+  try {
+    if (!planFile || !taskNumber) {
+      throw new SddScriptError("usage: mstar sdd task-brief PLAN_FILE TASK_NUMBER [OUTFILE]", 2);
+    }
+    const out = taskBrief(planFile, Number(taskNumber), outfile);
+    console.log(import_picocolors.default.green(`task ${taskNumber} brief: ${out}`));
+  } catch (error) {
+    failScript(error, "sdd task-brief");
+  }
+});
+sddCommand.command("review-package").description("Write commits + stat + diff -U10 for BASE..HEAD into a review file (exit 2 on bad refs)").argument("[base]", "Base ref (commit SHA)").argument("[head]", "Head ref (commit SHA)").argument("[outfile]", "Output file (default: {SDD_DIR}/review-<short-base>..<short-head>.diff)").action((base, head, outfile) => {
+  try {
+    if (!base || !head) {
+      throw new SddScriptError("usage: mstar sdd review-package BASE HEAD [OUTFILE]", 2);
+    }
+    const out = reviewPackage(base, head, outfile);
+    console.log(import_picocolors.default.green(`review package: ${out}`));
+  } catch (error) {
+    failScript(error, "sdd review-package");
+  }
+});
+var iterationCommand = program2.command("iteration").description("iteration phase-gate + push-cadence checks (engine-backed)");
+function printChecklist(label, gate2) {
+  if (gate2.ok) {
+    console.log(import_picocolors.default.green(`${label}: OK`));
+    return;
+  }
+  const count = gate2.violations.length;
+  console.error(import_picocolors.default.red(`${label}: FAIL (${count} violation${count === 1 ? "" : "s"})`));
+  for (const violation7 of gate2.violations) {
+    console.error(`  - [${violation7.severity}] ${violation7.code}: ${violation7.message}`);
+    if (violation7.fix)
+      console.error(`    fix: ${violation7.fix}`);
+  }
+}
+iterationCommand.command("gate").description("Evaluate the phase-transition gate: prints the transition (phase-2-execute / phase-3-close / phase-4-pr-delivery) " + "plus the \xA73.1 entry and \xA73.5 exit checklists. Exit 1 when the gate verdict fails \u2014 during the Phase-3 window " + "(transition: phase-3-close) exit 1 is EXPECTED until the \xA73.4 close items (status: completed + end_date) are " + "written: the exit checklist gates Phase 4, not the Phase-3 entry (qc2 F-003)").requiredOption("--status <path>", "status.json path").requiredOption("--compass <path>", "delivery-compass.md path").option("--branch <branch>", "Current branch probe (exit \xA73.5 item 5)").option("--integration <branch>", "Spec integration branch probe (exit \xA73.5 item 5)").option("--target <branch>", "PR base branch probe (exit \xA73.5 item 6)").action((options) => {
+  try {
+    const statusPath = path11.resolve(options.status);
+    const compassPath = path11.resolve(options.compass);
+    if (!fs7.existsSync(statusPath))
+      throw new Error(`status file not found: ${statusPath}`);
+    if (!fs7.existsSync(compassPath))
+      throw new Error(`compass file not found: ${compassPath}`);
+    const result = evaluatePhaseGate(readJson2(statusPath), parseCompassFrontmatter(compassPath), {
+      currentBranch: options.branch,
+      specIntegrationBranch: options.integration,
+      prBaseBranch: options.target
+    });
+    console.log(`transition: ${result.transition}`);
+    printChecklist("entry (close \xA73.1)", result.entry);
+    printChecklist("exit (close \xA73.5)", result.exit);
+    if (!result.ok)
+      process.exitCode = 1;
+  } catch (error) {
+    console.error(import_picocolors.default.red(`iteration gate failed: ${error.message}`));
+    process.exitCode = 1;
+  }
+});
+iterationCommand.command("push-cadence").description("\xA75.1a push-cadence probe: never push while CI or an AI review wave is running (exit 1 when blocked)").option("--ci-running", "CI checks are still queued/in_progress on the current head").option("--review-wave", "An AI/bot review wave is still running on the current head").action((options) => {
+  const result = pushCadenceProbe(Boolean(options.ciRunning), Boolean(options.reviewWave));
+  if (result.ok) {
+    console.log(import_picocolors.default.green("push allowed: CI idle, no AI review wave"));
+    return;
+  }
+  const count = result.violations.length;
+  console.error(import_picocolors.default.red(`push blocked (${count} violation${count === 1 ? "" : "s"})`));
+  for (const violation7 of result.violations) {
+    console.error(`  - [${violation7.severity}] ${violation7.code}: ${violation7.message}`);
+    if (violation7.fix)
+      console.error(`    fix: ${violation7.fix}`);
+  }
+  process.exitCode = 1;
+});
+var dispatchCommand = program2.command("dispatch").description("Assignment field + default-branch gate checks (engine-backed)");
+dispatchCommand.command("validate").description("Validate an Assignment markdown file: required header fields + exactly-one branch form, " + "then the default-protected-branch gate (exit 1 on violations, 2 on usage)").argument("[assignment-file]", "Assignment markdown file").option("--branch <branch>", "Gate branch context (default: derived from the Assignment's own branch forms, then $MSTAR_WORKING_BRANCH)").action((assignmentFile, options) => {
+  try {
+    if (!assignmentFile) {
+      throw new SddScriptError("usage: dispatch validate <assignment-file> [--branch <branch>]", 2);
+    }
+    const file = path11.resolve(assignmentFile);
+    if (!fs7.existsSync(file)) {
+      throw new Error(`assignment file not found: ${file}`);
+    }
+    const text = fs7.readFileSync(file, "utf8");
+    const readOnly = isReadOnlyAssignmentRole(parseAssignmentFields(text).executeAs ?? "");
+    const violations = [...validateAssignmentFields(text, { writable: readOnly ? false : undefined }).violations];
+    if (!readOnly) {
+      const forms = parseAssignmentBranchForms(text);
+      const branch = forms.createForm?.name ?? forms.workingBranch ?? forms.directOn?.branch ?? options.branch ?? process.env.MSTAR_WORKING_BRANCH;
+      if (branch !== undefined && branch.trim() !== "") {
+        const directOnException = parseBranchPolicyDirectOnBranch(text) === branch.trim();
+        violations.push(...assertDefaultBranchProtected(branch, { directOnException }).violations);
+      }
+    }
+    printChecklist("dispatch validate", { ok: violations.length === 0, violations });
+    if (violations.length > 0)
+      process.exitCode = 1;
+  } catch (error) {
+    failScript(error, "dispatch validate");
+  }
+});
+var worktreeCommand = program2.command("worktree").description("L1/L2 pre-dispatch worktree checks (engine-backed)");
+function parseTracksArg(tracksJson) {
+  let parsed;
+  try {
+    parsed = JSON.parse(tracksJson);
+  } catch {
+    throw new SddScriptError("usage: worktree check --l2 --tracks <json> \u2014 invalid JSON", 2);
+  }
+  if (!Array.isArray(parsed)) {
+    throw new SddScriptError("usage: worktree check --l2 --tracks <json> \u2014 expected a JSON array of {worktreePath, workingBranch}", 2);
+  }
+  const tracks = [];
+  for (const item of parsed) {
+    const record = item;
+    if (record === null || typeof record !== "object" || typeof record.worktreePath !== "string" || typeof record.workingBranch !== "string") {
+      throw new SddScriptError("usage: worktree check --l2 --tracks <json> \u2014 every track needs string worktreePath + workingBranch", 2);
+    }
+    tracks.push({ worktreePath: record.worktreePath, workingBranch: record.workingBranch });
+  }
+  return tracks;
+}
+worktreeCommand.command("check").description("L1: verify the plan's execution_lease worktree vs control path (isolation, existence, branch alignment) from " + "status.json; --l2: verify parallel writable tracks (exit 1 on violations, 2 on usage)").argument("[plan-id]", "Plan id whose execution_lease drives the L1 input (alternative to --plan)").option("--plan <plan-id>", "Plan id whose execution_lease drives the L1 input").option("--status <path>", "status.json path override (default: {HARNESS_DIR}/status.json)").option("--control <path>", "Control worktree path override (default: status.json metadata.control_worktree_path)").option("--l2", "Run the L2 within-plan check (parallel writable tracks) instead of L1").option("--tracks <json>", 'L2 tracks JSON: [{"worktreePath": "/abs/path", "workingBranch": "feature/x"}] (required with --l2)').action((planId, options) => {
+  try {
+    if (options.l2) {
+      if (!options.tracks) {
+        throw new SddScriptError("usage: worktree check --l2 --tracks <json>", 2);
+      }
+      const gate3 = l2PreDispatchCheck({ tracks: parseTracksArg(options.tracks) });
+      printChecklist("worktree L2 check", gate3);
+      if (!gate3.ok)
+        process.exitCode = 1;
+      return;
+    }
+    const plan = options.plan ?? planId;
+    if (!plan) {
+      throw new SddScriptError("usage: worktree check <plan-id> [--status <path>] [--control <path>] (or --plan <plan-id>)", 2);
+    }
+    const statusPath = options.status ? path11.resolve(options.status) : resolveStatusFilePath();
+    if (!fs7.existsSync(statusPath)) {
+      throw new Error(`status file not found: ${statusPath}`);
+    }
+    const doc = readJson2(statusPath);
+    const plans = Array.isArray(doc.plans) ? doc.plans : [];
+    const matches = plans.filter((row2) => row2?.id === plan || row2?.plan_id === plan);
+    if (matches.length === 0) {
+      console.error(import_picocolors.default.red(`${statusPath}: FAIL plan ${plan}`));
+      console.error(`  - [high] worktree.l1.plan-not-found: no plan row with id/plan_id ${plan}`);
+      process.exitCode = 1;
+      return;
+    }
+    if (matches.length > 1) {
+      console.error(import_picocolors.default.red(`${statusPath}: FAIL plan ${plan}`));
+      console.error("  - [high] worktree.l1.ambiguous: multiple plan rows match (id and plan_id both present)");
+      process.exitCode = 1;
+      return;
+    }
+    const row = matches[0];
+    const lease = row.execution_lease ?? {};
+    const metadata = doc.metadata ?? {};
+    const input = {
+      controlWorktreePath: options.control ? path11.resolve(options.control) : String(metadata.control_worktree_path ?? ""),
+      leaseWorktreePath: String(lease.worktree_path ?? ""),
+      leaseWorkingBranch: String(lease.working_branch ?? ""),
+      planId: plan
+    };
+    const gate2 = l1PreDispatchCheck(input);
+    printChecklist("worktree L1 check", gate2);
+    if (!gate2.ok)
+      process.exitCode = 1;
+  } catch (error) {
+    failScript(error, "worktree check");
+  }
+});
+var reviewCommand = program2.command("review").description("QC seat-mapping checks (engine-backed)");
+function parseAssignmentExecutionMode(assignmentText) {
+  for (const line of assignmentText.split(/\r?\n/)) {
+    const match = line.match(/^\*\*\s*Execution mode\s*\*\*\s*:\s*(.*)$/) ?? line.match(/^Execution mode\s*:\s*(.*)$/);
+    if (match)
+      return match[1].trim();
+  }
+  return "";
+}
+reviewCommand.command("seats").description("Map an Assignment's execution mode to its QC seat count N; with --reviewers, verify tri identity on sdd " + "(exit 1 on violations, 2 on usage)").argument("[assignment-file]", "Assignment markdown file").option("--mode <mode>", "Execution mode override (sdd | inline | targeted; default: the Assignment's Execution mode field)").option("--reviewers <list>", "Comma-separated reviewer roles (targeted seats; tri-identity checked when mode is sdd)").action((assignmentFile, options) => {
+  try {
+    if (!assignmentFile) {
+      throw new SddScriptError("usage: review seats <assignment-file> [--mode sdd|inline|targeted] [--reviewers <role1,role2,...>]", 2);
+    }
+    const file = path11.resolve(assignmentFile);
+    if (!fs7.existsSync(file)) {
+      throw new Error(`assignment file not found: ${file}`);
+    }
+    const text = fs7.readFileSync(file, "utf8");
+    const mode = options.mode ?? parseAssignmentExecutionMode(text);
+    const reviewers = (options.reviewers ?? "").split(",").map((role) => role.trim()).filter((role) => role !== "");
+    const result = executionModeToN(mode, { seats: reviewers });
+    if (!result.ok) {
+      printChecklist("review seats", result);
+      process.exitCode = 1;
+      return;
+    }
+    const normalizedMode = mode.trim().toLowerCase().split(/\s+/)[0] ?? "";
+    if (normalizedMode === "sdd" && reviewers.length > 0) {
+      const tri = assertTriIdentity(reviewers);
+      if (!tri.ok) {
+        printChecklist("review seats (tri identity)", tri);
+        process.exitCode = 1;
+        return;
+      }
+    }
+    console.log(import_picocolors.default.green(`seats: ${result.n}`));
+  } catch (error) {
+    failScript(error, "review seats");
+  }
+});
+function lookupTable(values) {
+  const table = {};
+  for (const value of values)
+    table[value] = true;
+  return table;
+}
+var LINT_SKIP_DIRS = {
+  node_modules: true,
+  ".git": true,
+  dist: true,
+  coverage: true,
+  ".turbo": true
+};
+var LINT_CODE_EXTENSIONS = {
+  ".ts": true,
+  ".tsx": true,
+  ".mts": true,
+  ".cts": true,
+  ".js": true,
+  ".jsx": true,
+  ".mjs": true,
+  ".cjs": true,
+  ".py": true,
+  ".go": true,
+  ".rs": true,
+  ".sh": true,
+  ".bash": true,
+  ".zsh": true,
+  ".rb": true,
+  ".java": true,
+  ".kt": true,
+  ".swift": true
+};
+function lintTargetType(filePath) {
+  const base = path11.basename(filePath);
+  if (base === "STRATEGY.md")
+    return "strategy";
+  if (base === "SKILL.md")
+    return "skill";
+  if (/^task-\d+-report\.md$/i.test(base))
+    return "report";
+  const dir = path11.dirname(filePath);
+  if (dir.includes(`${path11.sep}plans${path11.sep}`) || dir.endsWith(`${path11.sep}plans`))
+    return "plan";
+  if (/^\d{8}-[a-z0-9.-]+\.md$/i.test(base))
+    return "plan";
+  if (LINT_CODE_EXTENSIONS[path11.extname(base).toLowerCase()] === true)
+    return "code";
+  return null;
+}
+function collectLintTargets(dir) {
+  const targets = [];
+  const walk = (current) => {
+    for (const entry of fs7.readdirSync(current, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        if (LINT_SKIP_DIRS[entry.name] !== true)
+          walk(path11.join(current, entry.name));
+      } else if (entry.isFile() && lintTargetType(path11.join(current, entry.name)) !== null) {
+        targets.push(path11.join(current, entry.name));
+      }
+    }
+  };
+  walk(dir);
+  return targets;
+}
+function lintOneFile(filePath) {
+  const abs = path11.resolve(filePath);
+  const text = fs7.readFileSync(abs, "utf8");
+  const violations = [];
+  const markers = [];
+  switch (lintTargetType(abs)) {
+    case "plan":
+      violations.push(...planQualityBar(text).violations);
+      break;
+    case "skill":
+      violations.push(...lintSkillFrontmatter(text).violations);
+      break;
+    case "strategy":
+      violations.push(...lintStrategySections(text).violations);
+      break;
+    case "report":
+      violations.push(...assertSddTddTriple(text).violations);
+      break;
+    case "code": {
+      for (const marker of findSimplifyMarkers(text)) {
+        markers.push(`simplify marker @${marker.line}: ${marker.text}`);
+      }
+      const temporary = findTemporaryMarkers(text);
+      for (const marker of temporary.markers) {
+        const removal = marker.removalPath === null ? "no removal path" : `removal: ${marker.removalPath}`;
+        markers.push(`temporary marker @${marker.line}: ${marker.text} (${removal})`);
+      }
+      violations.push(...temporary.violations);
+      break;
+    }
+    default:
+      throw new SddScriptError(`usage: lint <target> \u2014 unsupported file type "${path11.basename(abs)}" (lintable: plan files, SKILL.md, STRATEGY.md, task-N-report.md, code files)`, 2);
+  }
+  return { violations, markers };
+}
+var lintCommand = program2.command("lint").description("lint harness artifacts by content type (engine-backed): plan files \u2192 quality bar, SKILL.md \u2192 frontmatter, " + "STRATEGY.md \u2192 required sections, task-N-report.md \u2192 SDD TDD triple, code files \u2192 simplify:/temporary markers");
+lintCommand.description("Lint <target> (file or dir) \u2014 exit 1 on violations, 2 on usage").argument("[target]", "File or directory to lint").action((target) => {
+  try {
+    if (!target)
+      throw new SddScriptError("usage: lint <target> (file or dir)", 2);
+    const abs = path11.resolve(target);
+    if (!fs7.existsSync(abs))
+      throw new Error(`lint target not found: ${abs}`);
+    const targets = fs7.statSync(abs).isDirectory() ? collectLintTargets(abs) : [abs];
+    if (targets.length === 0) {
+      console.log(import_picocolors.default.yellow(`lint: no lintable files under ${target}`));
+      return;
+    }
+    let violations = 0;
+    for (const file of targets) {
+      const label = `lint ${file}`;
+      let result;
+      try {
+        result = lintOneFile(file);
+      } catch (error) {
+        if (error instanceof SddScriptError)
+          throw error;
+        console.error(import_picocolors.default.red(`${label}: ERROR \u2014 ${error.message}`));
+        violations++;
+        continue;
+      }
+      for (const marker of result.markers)
+        console.log(`  ${import_picocolors.default.cyan(marker)}`);
+      if (result.violations.length === 0) {
+        console.log(import_picocolors.default.green(`${label}: OK`));
+        continue;
+      }
+      violations += result.violations.length;
+      const count = result.violations.length;
+      console.error(import_picocolors.default.red(`${label}: FAIL (${count} violation${count === 1 ? "" : "s"})`));
+      for (const violation7 of result.violations) {
+        console.error(`  - [${violation7.severity}] ${violation7.code}: ${violation7.message}`);
+        if (violation7.fix)
+          console.error(`    fix: ${violation7.fix}`);
+      }
+    }
+    if (violations > 0)
+      process.exitCode = 1;
+  } catch (error) {
+    failScript(error, "lint");
+  }
+});
+function stripFrontmatter(text) {
+  const lines = text.replace(/^\uFEFF/, "").split(/\r?\n/);
+  if (lines.length === 0 || lines[0].trim() !== "---")
+    return text;
+  for (let i = 1;i < lines.length; i++) {
+    if (lines[i].trim() === "---")
+      return lines.slice(i + 1).join(`
+`);
+  }
+  return text;
+}
+var designMdCommand = program2.command("design-md").description("DESIGN.md token frontmatter / light-dark parity / completeness checks (engine-backed)");
+designMdCommand.command("validate").description("Validate DESIGN.md in <dir>: token frontmatter, light/dark parity when DESIGN.dark.md exists, " + "and the completeness level (exit 1 on violations, 2 on usage)").argument("[dir]", "Directory containing DESIGN.md").action((dir) => {
+  try {
+    if (!dir)
+      throw new SddScriptError("usage: design-md validate <dir>", 2);
+    const abs = path11.resolve(dir);
+    const lightPath = path11.join(abs, "DESIGN.md");
+    if (!fs7.existsSync(lightPath))
+      throw new Error(`design file not found: ${lightPath}`);
+    const light = fs7.readFileSync(lightPath, "utf8");
+    const violations = [];
+    const tokens = validateDesignTokenFrontmatter(light);
+    printChecklist("design-md validate (tokens)", tokens);
+    violations.push(...tokens.violations);
+    const darkPath = path11.join(abs, "DESIGN.dark.md");
+    if (fs7.existsSync(darkPath)) {
+      const parity = assertLightDarkParity(light, fs7.readFileSync(darkPath, "utf8"));
+      printChecklist("design-md validate (light/dark parity)", parity);
+      violations.push(...parity.violations);
+    }
+    const level = completenessLevel(light);
+    console.log(`design-md completeness level: ${level.level}`);
+    if (level.missing.length > 0)
+      console.log(`  missing for next level: ${level.missing.join(", ")}`);
+    if (level.bodyUnverified) {
+      console.log(import_picocolors.default.yellow("  note: body-only checklist items not verified \u2014 Production caps at Standard"));
+    }
+    if (violations.length > 0)
+      process.exitCode = 1;
+  } catch (error) {
+    failScript(error, "design-md validate");
+  }
+});
+function parseAuditFindings(text) {
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new SddScriptError("usage: audit scaffold \u2014 findings file is not valid JSON", 2);
+  }
+  if (!Array.isArray(parsed))
+    throw new SddScriptError("usage: audit scaffold \u2014 findings file must be a JSON array", 2);
+  return parsed.map((raw, index) => {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+      throw new SddScriptError(`usage: audit scaffold \u2014 findings[${index}] is not an object`, 2);
+    }
+    const finding = raw;
+    const title = typeof finding.title === "string" ? finding.title.trim() : "";
+    const impact = typeof finding.description === "string" ? finding.description.trim() : "";
+    const priority = typeof finding.priority === "string" ? finding.priority : "";
+    const effort = typeof finding.effort === "string" ? finding.effort : "";
+    const risk = typeof finding.risk === "string" ? finding.risk : "";
+    const category = typeof finding.category === "string" ? finding.category : "";
+    if (title === "" || impact === "") {
+      throw new SddScriptError(`usage: audit scaffold \u2014 findings[${index}] needs non-empty title and description`, 2);
+    }
+    if (AUDIT_PRIORITY_LOOKUP[priority] !== true) {
+      throw new SddScriptError(`usage: audit scaffold \u2014 findings[${index}].priority must be one of ${AUDIT_PRIORITIES.join("|")}`, 2);
+    }
+    if (AUDIT_EFFORT_LOOKUP[effort] !== true) {
+      throw new SddScriptError(`usage: audit scaffold \u2014 findings[${index}].effort must be one of ${AUDIT_EFFORTS.join("|")}`, 2);
+    }
+    if (AUDIT_RISK_LOOKUP[risk] !== true) {
+      throw new SddScriptError(`usage: audit scaffold \u2014 findings[${index}].risk must be one of ${AUDIT_RISKS.join("|")}`, 2);
+    }
+    if (AUDIT_CATEGORY_LOOKUP[category] !== true) {
+      throw new SddScriptError(`usage: audit scaffold \u2014 findings[${index}].category must be one of ${AUDIT_CATEGORIES.join("|")}`, 2);
+    }
+    const rawDependsOn = typeof finding.dependsOn === "string" && finding.dependsOn.trim() !== "" ? finding.dependsOn.trim() : undefined;
+    if (rawDependsOn !== undefined && !/^(?:none|plans\/\d{3}-[\w.*-]+\.md|\d{3})$/i.test(rawDependsOn)) {
+      throw new SddScriptError(`usage: audit scaffold \u2014 findings[${index}].dependsOn must be "none", "plans/NNN-*.md", or a plan number NNN`, 2);
+    }
+    const dependsOn = rawDependsOn === undefined ? undefined : /^\d{3}$/.test(rawDependsOn) ? `plans/${rawDependsOn}-*.md` : rawDependsOn;
+    return {
+      title,
+      category,
+      impact,
+      effort,
+      risk,
+      confidence: "MED",
+      evidence: [],
+      priority,
+      dependsOn
+    };
+  });
+}
+var auditCommand = program2.command("audit").description("audit plan scaffold (engine-backed)");
+function resolveAuditShortSha(cwd, override) {
+  if (override !== undefined && override !== "")
+    return override;
+  try {
+    const out = execFileSync6("git", ["rev-parse", "--short", "HEAD"], {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+    return out.trim();
+  } catch {
+    return "unknown";
+  }
+}
+auditCommand.command("scaffold").description("Scaffold an audit-<date>/ plan directory (numbered plan files + README index) from a JSON findings file " + "(exit 2 on usage)").argument("[findings-file]", "JSON file: array of {title, priority, effort, risk, category, dependsOn?, description}").option("--dir <out-dir>", "Output directory (default: ./audit-<date> from --date or today)").option("--sha <commit>", "Short commit SHA for the Planned-at field (default: git rev-parse --short HEAD)").option("--date <YYYY-MM-DD>", "Audit date (default: today)").option("--repo <name>", "Repository name for the README title (default: repo)").action((findingsFile, options) => {
+  try {
+    if (!findingsFile)
+      throw new SddScriptError("usage: audit scaffold <findings-file> [--dir <out-dir>]", 2);
+    const abs = path11.resolve(findingsFile);
+    if (!fs7.existsSync(abs))
+      throw new Error(`findings file not found: ${abs}`);
+    if (options.date !== undefined && !/^\d{4}-\d{2}-\d{2}$/.test(options.date)) {
+      throw new SddScriptError("usage: audit scaffold \u2014 --date must be YYYY-MM-DD", 2);
+    }
+    if (options.sha !== undefined && !/^[0-9a-f]{7,40}$/.test(options.sha)) {
+      throw new SddScriptError("usage: audit scaffold \u2014 --sha must be a 7-40 char hex commit SHA", 2);
+    }
+    const date = options.date ?? new Date().toISOString().slice(0, 10);
+    const outDir = options.dir !== undefined ? path11.resolve(options.dir) : path11.resolve(`audit-${date}`);
+    const findings = parseAuditFindings(fs7.readFileSync(abs, "utf8"));
+    const sha = resolveAuditShortSha(process.cwd(), options.sha);
+    const result = scaffoldAuditPlan(outDir, findings, { date, repoName: options.repo, repoShortSha: sha });
+    const count = result.files.length;
+    console.log(import_picocolors.default.green(`audit scaffold: OK \u2014 ${count} plan file${count === 1 ? "" : "s"} in ${result.outDir}`));
+    for (const file of result.files)
+      console.log(`  created: ${file}`);
+  } catch (error) {
+    failScript(error, "audit scaffold");
+  }
+});
+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 {
+    if (!docPath)
+      throw new SddScriptError("usage: compound validate <doc-path> [--knowledge-dir <dir>]", 2);
+    const abs = path11.resolve(docPath);
+    if (!fs7.existsSync(abs))
+      throw new Error(`knowledge doc not found: ${abs}`);
+    const text = fs7.readFileSync(abs, "utf8");
+    const violations = [];
+    const schema = validateSchemaYaml(text);
+    printChecklist("compound validate (schema)", schema);
+    violations.push(...schema.violations);
+    if (options.knowledgeDir !== undefined) {
+      const knowledgeDir = path11.resolve(options.knowledgeDir);
+      const index = assertIndexRows(knowledgeDir);
+      printChecklist("compound validate (index rows)", index);
+      violations.push(...index.violations);
+      const scope = scopeGuard(abs, [knowledgeDir]);
+      printChecklist("compound validate (scope guard)", scope);
+      violations.push(...scope.violations);
+    }
+    if (violations.length > 0)
+      process.exitCode = 1;
+  } catch (error) {
+    failScript(error, "compound validate");
+  }
+});
+var AUDIT_PRIORITY_LOOKUP = lookupTable(AUDIT_PRIORITIES);
+var AUDIT_EFFORT_LOOKUP = lookupTable(AUDIT_EFFORTS);
+var AUDIT_RISK_LOOKUP = lookupTable(AUDIT_RISKS);
+var AUDIT_CATEGORY_LOOKUP = lookupTable(AUDIT_CATEGORIES);
+var HOST_SIGNALS = [
+  "subagent_type",
+  "question",
+  "task_subagent",
+  "task_agent_batch",
+  "ask",
+  "hub",
+  "Agent",
+  "AgentSwarm",
+  "AskUserQuestion",
+  "EnterPlanMode",
+  "TodoWrite",
+  "plan_slash",
+  "goal",
+  "functions.*",
+  "tool_search"
+];
+var HOST_SIGNAL_LOOKUP = lookupTable(HOST_SIGNALS);
+var hostCommand = program2.command("host").description("host detection from session tool shapes (engine-backed)");
+hostCommand.command("detect").description("Detect the active host from --signals (comma-separated tool-shape tokens): prints the host id or " + "'ambiguous' (exit 2 on usage)").option("--signals <list>", "Comma-separated tool-shape signals (e.g. question,ask,hub)").action((options) => {
+  try {
+    if (!options.signals)
+      throw new SddScriptError("usage: host detect --signals <comma-list>", 2);
+    const signals2 = options.signals.split(",").map((signal) => signal.trim()).filter((signal) => signal !== "");
+    if (signals2.length === 0)
+      throw new SddScriptError("usage: host detect --signals <comma-list>", 2);
+    for (const signal of signals2) {
+      if (HOST_SIGNAL_LOOKUP[signal] !== true) {
+        throw new SddScriptError(`usage: host detect \u2014 unknown signal "${signal}" (valid: ${HOST_SIGNALS.join(", ")})`, 2);
+      }
+    }
+    const result = detectHost(signals2);
+    if (result === "ambiguous") {
+      console.log(import_picocolors.default.yellow("host: ambiguous \u2014 apply the mstar-host detection table and prompt judgment"));
+    } else {
+      console.log(import_picocolors.default.green(`host: ${result}`));
+    }
+  } catch (error) {
+    failScript(error, "host detect");
+  }
+});
+var skillCommand = program2.command("skill").description("skill-authoring lints (engine-backed)");
+skillCommand.command("lint").description("Lint <skill-dir>/SKILL.md: frontmatter contract (name lowercase-hyphen, description trigger contract) " + "+ the five-question body (exit 1 on violations, 2 on usage)").argument("[skill-dir]", "Skill directory containing SKILL.md").action((skillDir) => {
+  try {
+    if (!skillDir)
+      throw new SddScriptError("usage: skill lint <skill-dir>", 2);
+    const skillFile = path11.join(path11.resolve(skillDir), "SKILL.md");
+    if (!fs7.existsSync(skillFile))
+      throw new Error(`SKILL.md not found: ${skillFile}`);
+    const text = fs7.readFileSync(skillFile, "utf8");
+    const violations = [];
+    const frontmatter = lintSkillFrontmatter(text);
+    printChecklist("skill lint (frontmatter)", frontmatter);
+    violations.push(...frontmatter.violations);
+    const fiveQuestion = lintFiveQuestion(stripFrontmatter(text));
+    printChecklist("skill lint (five questions)", fiveQuestion);
+    violations.push(...fiveQuestion.violations);
+    if (violations.length > 0)
+      process.exitCode = 1;
+  } catch (error) {
+    failScript(error, "skill lint");
+  }
+});
 program2.parseAsync(process.argv).catch((error) => {
   console.error(import_picocolors.default.red(`Setup failed: ${error.message}`));
-  process.exit(1);
+  process.exitCode = 1;
 });