@mstar-harness/engine 3.6.2 → 3.7.0

package/dist/engine.js

@@ -2095,6 +2095,25 @@ function assertSafePathComponent(value, what) {
     throw new Error(`${what} must be a single safe path component ([A-Za-z0-9._-]+; not "", ".", "..", or containing "/" or "\\") — got ${JSON.stringify(value)}`);
   }
 }
+function canonicalizeNearestExisting(path) {
+  const abs = resolve7(path);
+  let dir = abs;
+  const tail = [];
+  for (;; ) {
+    if (existsSync6(dir)) {
+      try {
+        return join9(realpathSync2(dir), ...tail);
+      } catch {
+        return abs;
+      }
+    }
+    const parent = dirname5(dir);
+    if (parent === dir)
+      return abs;
+    tail.unshift(basename3(dir));
+    dir = parent;
+  }
+}
 function resolveSddDir(harnessDir, planId) {
   assertSafePathComponent(planId, "planId");
   const base = resolve7(harnessDir);
@@ -2489,9 +2508,10 @@ function singleReviewSnapshot(assignments) {
   return gate(violations);
 }
 // src/sdd.ts
-import { execFileSync as execFileSync3 } from "node:child_process";
+import { execFileSync as execFileSync3, spawn } from "node:child_process";
 import { mkdirSync as mkdirSync6, readdirSync as readdirSync6, readFileSync as readFileSync7, realpathSync as realpathSync3, statSync as statSync4, writeFileSync as writeFileSync4 } from "node:fs";
-import { basename as basename4, dirname as dirname6, isAbsolute as isAbsolute6, join as join10, resolve as resolve9 } from "node:path";
+import { constants as osConstants } from "node:os";
+import { basename as basename4, dirname as dirname6, isAbsolute as isAbsolute6, join as join10, relative as relative3, resolve as resolve9 } from "node:path";
 class SddScriptError extends Error {
   exitCode;
   constructor(message, exitCode) {
@@ -2629,6 +2649,16 @@ 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);
   }
+  const bound = opts.context;
+  const observedCwd = opts.cwd ?? process.cwd();
+  if (bound) {
+    const inputPlan = canonicalizeNearestExisting(resolve9(observedCwd, planFile));
+    if (inputPlan !== canonicalizeNearestExisting(bound.planFile)) {
+      throwGateFail([
+        contextViolation("high", "sdd.context.plan-file-mismatch", `plan file "${planFile}" does not match the bound context plan file "${bound.planFile}" — ` + "bound mode extracts only the resolved context's plan; refused before any read or write")
+      ]);
+    }
+  }
   let content;
   try {
     content = readFileSync7(planFile, "utf8");
@@ -2636,8 +2666,12 @@ function taskBrief(planFile, taskN, outFile, opts = {}) {
     throw new SddScriptError(`no such plan file: ${planFile}`, 2);
   }
   let out;
+  let mkdirAfterGate = null;
   if (outFile) {
-    out = outFile;
+    out = bound ? resolve9(observedCwd, outFile) : outFile;
+  } else if (bound) {
+    out = join10(bound.sddDir, `task-${taskN}-brief.md`);
+    mkdirAfterGate = bound.sddDir;
   } else {
     const sddDir = opts.sddDir ?? process.env.SDD_DIR;
     if (!sddDir) {
@@ -2646,6 +2680,13 @@ function taskBrief(planFile, taskN, outFile, opts = {}) {
     mkdirSync6(sddDir, { recursive: true });
     out = join10(sddDir, `task-${taskN}-brief.md`);
   }
+  if (bound) {
+    const gate2 = checkSddAction(bound, { kind: "artifact", cwd: observedCwd, target: out });
+    if (!gate2.ok)
+      throwGateFail(gate2.violations);
+    if (mkdirAfterGate !== null)
+      mkdirSync6(mkdirAfterGate, { recursive: true });
+  }
   const records = content.endsWith(`
 `) ? content.split(`
 `).slice(0, -1) : content.split(`
@@ -2670,13 +2711,15 @@ function taskBrief(planFile, taskN, outFile, opts = {}) {
   if (printed.length === 0) {
     throw new SddScriptError(`task ${taskN} not found in ${planFile} (no heading matching Task ${taskN})`, 3);
   }
-  return out;
+  return bound ? resolve9(observedCwd, out) : 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 bound = opts.context;
+  const cwd = bound && opts.cwd === undefined ? bound.featureCwd : opts.cwd ?? process.cwd();
+  const observedCwd = opts.cwd ?? process.cwd();
   const verifyRef = (ref, what) => {
     try {
       execFileSync3("git", ["rev-parse", "--verify", "--quiet", ref], { cwd, stdio: ["ignore", "pipe", "pipe"] });
@@ -2687,8 +2730,14 @@ function reviewPackage(base, head, outFile, opts = {}) {
   verifyRef(base, "BASE");
   verifyRef(head, "HEAD");
   let out;
+  let mkdirAfterGate = null;
   if (outFile) {
-    out = outFile;
+    out = bound ? resolve9(observedCwd, outFile) : outFile;
+  } else if (bound) {
+    const shortBase = gitOut(cwd, ["rev-parse", "--short", base]) ?? base;
+    const shortHead = gitOut(cwd, ["rev-parse", "--short", head]) ?? head;
+    out = join10(bound.sddDir, `review-${shortBase}..${shortHead}.diff`);
+    mkdirAfterGate = bound.sddDir;
   } else {
     const sddDir = opts.sddDir ?? process.env.SDD_DIR;
     if (!sddDir) {
@@ -2699,6 +2748,13 @@ function reviewPackage(base, head, outFile, opts = {}) {
     const shortHead = gitOut(cwd, ["rev-parse", "--short", head]) ?? head;
     out = join10(sddDir, `review-${shortBase}..${shortHead}.diff`);
   }
+  if (bound) {
+    const gate2 = checkSddAction(bound, { kind: "artifact", cwd: observedCwd, target: out });
+    if (!gate2.ok)
+      throwGateFail(gate2.violations);
+    if (mkdirAfterGate !== null)
+      mkdirSync6(mkdirAfterGate, { recursive: true });
+  }
   const run = (args) => execFileSync3("git", args, { cwd, maxBuffer: GIT_CAPTURE_MAX_BYTES });
   const parts = [
     Buffer.from(`# Review package: ${base}..${head}
@@ -2716,7 +2772,7 @@ function reviewPackage(base, head, outFile, opts = {}) {
     run(["diff", "-U10", `${base}..${head}`])
   ];
   writeFileSync4(out, Buffer.concat(parts));
-  return out;
+  return bound ? resolve9(observedCwd, out) : out;
 }
 function assertBaseSha(ref, opts = {}) {
   if (typeof ref !== "string" || !/^[0-9a-f]{4,40}$/i.test(ref)) {
@@ -2774,9 +2830,356 @@ function implementerSessionStickyRules(input) {
   }
   return { resume: true, reason: `sticky resume OK: host_agent_id ${session.host_agent_id}, next task ${nextTask}` };
 }
+function isPlainObject6(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isInside(child, ancestor) {
+  const rel = relative3(ancestor, child);
+  return rel === "" || !rel.startsWith("..") && !isAbsolute6(rel);
+}
+function canonicalDir(path) {
+  try {
+    return statSync4(path).isDirectory() ? realpathSync3(path) : null;
+  } catch {
+    return null;
+  }
+}
+function contextViolation(severity, code, message, fix) {
+  return { ok: false, severity, code, message, fix };
+}
+function throwGateFail(violations) {
+  const detail = violations.map((v) => `${v.code}: ${v.message}${v.fix ? ` (fix: ${v.fix})` : ""}`).join(`
+  `);
+  throw new SddScriptError(`SDD execution context rejected:
+  ${detail}`, 1);
+}
+function throwUsage(message) {
+  throw new SddScriptError(message, 2);
+}
+function readActiveWorkflowIds(controlHarnessRoot) {
+  const statusPath = join10(controlHarnessRoot, "status.json");
+  if (!isFile2(statusPath))
+    return null;
+  let doc;
+  try {
+    doc = readJson(statusPath);
+  } catch {
+    return null;
+  }
+  if (!isPlainObject6(doc) || doc.version !== 2 || !Array.isArray(doc.workflows))
+    return null;
+  const ids = new Set;
+  for (const entry of doc.workflows) {
+    if (isPlainObject6(entry) && typeof entry.id === "string")
+      ids.add(entry.id);
+  }
+  return ids;
+}
+function findWorkflowPlanRow(controlHarnessRoot, planId) {
+  let workflowsDir;
+  try {
+    workflowsDir = resolveWorkflowDir(controlHarnessRoot, { harnessDir: controlHarnessRoot });
+  } catch {
+    return { kind: "none" };
+  }
+  if (!isDirectory2(workflowsDir))
+    return { kind: "none" };
+  let workflowIds;
+  try {
+    workflowIds = readdirSync6(workflowsDir, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+  } catch {
+    return { kind: "none" };
+  }
+  const matches = [];
+  for (const id of workflowIds) {
+    const snapshotPath = join10(workflowsDir, id, WORKFLOW_SNAPSHOT_FILE);
+    if (!isFile2(snapshotPath))
+      continue;
+    let doc;
+    try {
+      doc = readJson(snapshotPath);
+    } catch {
+      continue;
+    }
+    const plans = doc.plans;
+    if (!Array.isArray(plans))
+      continue;
+    for (const row of plans) {
+      if (isPlainObject6(row) && (row.id === planId || row.plan_id === planId)) {
+        matches.push({ workflowId: id, row });
+        break;
+      }
+    }
+  }
+  if (matches.length === 0)
+    return { kind: "none" };
+  const registeredActive = readActiveWorkflowIds(controlHarnessRoot);
+  if (registeredActive === null) {
+    return { kind: "row", workflowId: matches[0].workflowId, row: matches[0].row };
+  }
+  const active = matches.filter((m) => registeredActive.has(m.workflowId));
+  if (active.length === 0)
+    return { kind: "none" };
+  if (active.length > 1) {
+    return { kind: "ambiguous", workflowIds: active.map((m) => m.workflowId) };
+  }
+  return { kind: "row", workflowId: active[0].workflowId, row: active[0].row };
+}
+function resolveSddExecutionContext(input) {
+  const { planId, workingBranch } = input;
+  if (typeof planId !== "string" || planId.trim() === "") {
+    throwUsage("SddExecutionContext.planId must be a non-empty string");
+  }
+  if (typeof workingBranch !== "string" || workingBranch.trim() === "") {
+    throwUsage("SddExecutionContext.workingBranch must be a non-empty string");
+  }
+  for (const field of ["controlHarnessRoot", "featureCwd", "planFile", "sddDir"]) {
+    const value = input[field];
+    if (typeof value !== "string" || value.trim() === "") {
+      throwUsage(`SddExecutionContext.${field} must be a non-empty string`);
+    }
+    if (!isAbsolute6(value)) {
+      throwUsage(`SddExecutionContext.${field} must be an absolute path (A3: all paths normalized absolute); got ${JSON.stringify(value)}`);
+    }
+  }
+  try {
+    assertSafePathComponent(planId, "SddExecutionContext.planId");
+  } catch (err) {
+    throwUsage(`SddExecutionContext rejected: ${err.message}`);
+  }
+  const canonicalControlHarnessRoot = canonicalDir(input.controlHarnessRoot);
+  if (canonicalControlHarnessRoot === null) {
+    throwGateFail([
+      contextViolation("high", "sdd.context.control-root-missing", `controlHarnessRoot "${input.controlHarnessRoot}" does not exist or is not a directory — a declared control root is authoritative and is never re-inferred from the feature cwd (A3)`)
+    ]);
+  }
+  const stem = basename4(input.planFile).replace(/\.md$/, "");
+  if (stem !== planId) {
+    throwUsage(`SddExecutionContext.planFile "${input.planFile}" does not match plan "${planId}" — the plan file must be {PLAN_DIR}/<plan-id>.md under the declared control harness`);
+  }
+  if (!isFile2(input.planFile)) {
+    throwUsage(`no such plan file: ${input.planFile}`);
+  }
+  const planGate = assertPlanWritingPath(input.planFile, input.controlHarnessRoot);
+  if (!planGate.ok) {
+    if (planGate.code === "plan-path.symlink-escape") {
+      throwGateFail([planGate]);
+    }
+    throwUsage(`SddExecutionContext.planFile rejected: ${planGate.code}: ${planGate.message}`);
+  }
+  const composedSddDir = resolveSddDir(canonicalControlHarnessRoot, planId);
+  const canonicalComposedSddDir = canonicalizeNearestExisting(composedSddDir);
+  const canonicalSddDir = canonicalizeNearestExisting(input.sddDir);
+  if (canonicalSddDir !== canonicalComposedSddDir) {
+    if (!isInside(canonicalSddDir, canonicalControlHarnessRoot)) {
+      throwGateFail([
+        contextViolation("high", "sdd.context.sdd-dir-escape", `sddDir "${input.sddDir}" canonicalizes to "${canonicalSddDir}", outside the control harness "${canonicalControlHarnessRoot}" — symlink escape refused (environmental gate failure)`)
+      ]);
+    }
+    throwUsage(`SddExecutionContext.sddDir "${input.sddDir}" does not match plan "${planId}" — expected the {SDD_DIR} composition ${composedSddDir}`);
+  }
+  const canonicalFeatureCwd = canonicalDir(input.featureCwd);
+  if (canonicalFeatureCwd === null) {
+    throwGateFail([
+      contextViolation("high", "sdd.context.feature-cwd-missing", `featureCwd "${input.featureCwd}" does not exist or is not a directory — the feature worktree is the required cwd for product edits`, `create the feature worktree first (git worktree add ${input.featureCwd} ${workingBranch})`)
+    ]);
+  }
+  const controlCheckout = dirname6(canonicalControlHarnessRoot);
+  if (isInside(canonicalFeatureCwd, controlCheckout)) {
+    throwGateFail([
+      contextViolation("critical", "sdd.context.feature-in-control", `featureCwd "${canonicalFeatureCwd}" is inside the control checkout "${controlCheckout}" — product edits never land in the control checkout (execution_lease.worktree_path MUST differ from metadata.control_worktree_path)`, "use a distinct feature worktree for the plan")
+    ]);
+  }
+  if (isInside(canonicalControlHarnessRoot, canonicalFeatureCwd)) {
+    throwGateFail([
+      contextViolation("critical", "sdd.context.control-inside-feature", `controlHarnessRoot "${canonicalControlHarnessRoot}" is inside featureCwd "${canonicalFeatureCwd}" — a feature worktree's same-looking {HARNESS_DIR} is not the SSOT; the control harness must live outside the feature checkout`)
+    ]);
+  }
+  const match = findWorkflowPlanRow(canonicalControlHarnessRoot, planId);
+  if (match.kind === "ambiguous") {
+    throwGateFail([
+      contextViolation("high", "sdd.context.workflow-plan-ambiguous", `plan "${planId}" appears in multiple registered active workflows (${match.workflowIds.join(", ")}) — ` + "the governing execution_lease is undecidable; resolve the duplicate registration before dispatch")
+    ]);
+  }
+  const row = match.kind === "row" ? match.row : null;
+  if (row !== null && row.execution_lease !== undefined) {
+    const leaseVerify = verifyPlanExecutionLease(row, planId);
+    if (!leaseVerify.ok)
+      throwGateFail(leaseVerify.violations);
+    const lease = leaseVerify.lease;
+    const l1 = l1PreDispatchCheck({
+      controlWorktreePath: controlCheckout,
+      leaseWorktreePath: lease.worktree_path,
+      leaseWorkingBranch: lease.working_branch,
+      planId
+    });
+    if (!l1.ok)
+      throwGateFail(l1.violations);
+    if (canonicalizeNearestExisting(lease.worktree_path) !== canonicalFeatureCwd) {
+      throwGateFail([
+        contextViolation("high", "sdd.context.lease-worktree-mismatch", `SddExecutionContext.featureCwd "${canonicalFeatureCwd}" does not match the verified execution_lease.worktree_path "${String(lease.worktree_path)}" — the context must match the verified lease (A3)`)
+      ]);
+    }
+    if (workingBranch !== lease.working_branch) {
+      throwGateFail([
+        contextViolation("high", "sdd.context.lease-branch-mismatch", `SddExecutionContext.workingBranch "${workingBranch}" does not match the verified execution_lease.working_branch "${String(lease.working_branch)}" (plan "${planId}")`)
+      ]);
+    }
+  } else if (row !== null && row.status === "InProgress") {
+    throwGateFail(verifyPlanExecutionLease(row, planId).violations);
+  } else {
+    const branchGate = assertBranchAlignment(canonicalFeatureCwd, workingBranch);
+    if (!branchGate.ok)
+      throwGateFail(branchGate.violations);
+  }
+  return {
+    planId,
+    controlHarnessRoot: canonicalControlHarnessRoot,
+    featureCwd: canonicalFeatureCwd,
+    workingBranch,
+    planFile: realpathSync3(input.planFile),
+    sddDir: canonicalSddDir
+  };
+}
+function checkSddAction(context, action) {
+  const violations = [];
+  const add = (code, message, fix) => {
+    violations.push(contextViolation("high", code, message, fix));
+  };
+  if (action.kind !== "source" && action.kind !== "artifact" && action.kind !== "launch") {
+    add("sdd.context.kind-unknown", `unknown action kind ${JSON.stringify(action.kind)} — expected "source" | "artifact" | "launch"`);
+    return { ok: false, violations };
+  }
+  if (typeof action.cwd !== "string" || action.cwd.trim() === "") {
+    add("sdd.context.cwd-missing", "action.cwd (the observed invocation cwd) is required — never an Assignment echo");
+    return { ok: false, violations };
+  }
+  const featureReal = canonicalDir(context.featureCwd);
+  const canonicalSddDir = canonicalizeNearestExisting(context.sddDir);
+  const canonicalPlanFile = canonicalizeNearestExisting(context.planFile);
+  const cwdResolved = resolve9(action.cwd);
+  const checkTarget = (baseDir, target, kind) => {
+    if (featureReal === null)
+      return;
+    const targetAbs = resolve9(baseDir, target);
+    const canonical = canonicalizeNearestExisting(targetAbs);
+    if (!isInside(canonical, featureReal)) {
+      const declaredPrefix = targetAbs === featureReal || targetAbs.startsWith(`${featureReal}/`);
+      if (declaredPrefix) {
+        add("sdd.context.target-symlink-escape", `${kind} target "${target}" canonicalizes to "${canonical}", outside the feature worktree — symlink escape refused before mutation`);
+      } else {
+        add(`sdd.context.${kind}-target-outside-feature`, `${kind} target "${target}" resolves to "${targetAbs}", outside the feature worktree "${featureReal}" — refused before mutation`);
+      }
+    }
+  };
+  if (action.kind === "source") {
+    const cwdReal = canonicalDir(cwdResolved);
+    if (cwdReal === null) {
+      add("sdd.context.cwd-missing", `observed source cwd "${action.cwd}" does not exist or is not a directory`);
+      return { ok: false, violations };
+    }
+    if (featureReal === null || !isInside(cwdReal, featureReal)) {
+      add("sdd.context.source-cwd-outside-feature", `observed source cwd "${cwdReal}" is outside the feature worktree "${context.featureCwd}" — a declared-correct context does not make a wrong-checkout write safe (A3)`, `run the source action from inside ${context.featureCwd}`);
+      return { ok: false, violations };
+    }
+    if (action.target !== undefined)
+      checkTarget(cwdReal, action.target, "source");
+  } else if (action.kind === "artifact") {
+    if (typeof action.target !== "string" || action.target.trim() === "") {
+      add("sdd.context.target-missing", "artifact checks require the destination target");
+      return { ok: false, violations };
+    }
+    const targetAbs = resolve9(cwdResolved, action.target);
+    const canonical = canonicalizeNearestExisting(targetAbs);
+    if (!isInside(canonical, canonicalSddDir) && canonical !== canonicalPlanFile) {
+      const rawSddDir = resolve9(context.sddDir);
+      const declaredPrefix = targetAbs === rawSddDir || targetAbs.startsWith(`${rawSddDir}/`) || targetAbs === canonicalSddDir || targetAbs.startsWith(`${canonicalSddDir}/`) || targetAbs === canonicalPlanFile;
+      if (declaredPrefix) {
+        add("sdd.context.artifact-symlink-escape", `artifact target "${targetAbs}" canonicalizes to "${canonical}", outside the plan's control sddDir — symlink escape refused before write`);
+      } else {
+        add("sdd.context.artifact-outside-plan", `artifact target "${targetAbs}" is outside the plan's control sddDir "${context.sddDir}" and is not the declared planFile "${context.planFile}" — legitimate control artifact edits stay inside the plan's artifacts; arbitrary control source edits are not allowed (A3)`);
+      }
+    }
+  } else {
+    if (featureReal === null) {
+      add("sdd.context.launch-cwd-missing", `feature worktree "${context.featureCwd}" does not exist or is not a directory — cannot bind the child's starting cwd`);
+    } else {
+      violations.push(...assertBranchAlignment(featureReal, context.workingBranch).violations);
+    }
+    if (action.target !== undefined && action.target.trim() !== "" && featureReal !== null) {
+      checkTarget(featureReal, action.target, "launch");
+    }
+  }
+  return { ok: violations.length === 0, violations };
+}
+function signalExitNumber(signal) {
+  return osConstants.signals[signal] ?? 0;
+}
+async function runInSddContext(context, argv) {
+  if (!Array.isArray(argv) || argv.length === 0 || typeof argv[0] !== "string" || argv[0].trim() === "") {
+    throwUsage("runInSddContext: argv must be [executable, ...args] with a non-empty executable — the array is passed to the child literally (no shell)");
+  }
+  const resolved = resolveSddExecutionContext(context);
+  const gate2 = checkSddAction(resolved, { kind: "launch", cwd: process.cwd() });
+  if (!gate2.ok)
+    throwGateFail(gate2.violations);
+  return await new Promise((settle, reject) => {
+    let child;
+    try {
+      child = spawn(argv[0], argv.slice(1), {
+        cwd: resolved.featureCwd,
+        shell: false,
+        stdio: "inherit"
+      });
+    } catch (err) {
+      if (err.code === "ENOENT") {
+        settle(127);
+        return;
+      }
+      throw err;
+    }
+    let done = false;
+    let spawnError = null;
+    const forward = (signal) => {
+      if (!done && child.exitCode === null && child.signalCode === null)
+        child.kill(signal);
+    };
+    const cleanup = () => {
+      process.removeListener("SIGINT", forward);
+      process.removeListener("SIGTERM", forward);
+    };
+    process.on("SIGINT", forward);
+    process.on("SIGTERM", forward);
+    child.on("error", (err) => {
+      spawnError = err;
+      if (err.code !== "ENOENT" && !done) {
+        done = true;
+        cleanup();
+        reject(err);
+      }
+    });
+    child.on("close", (code, signal) => {
+      if (done)
+        return;
+      done = true;
+      cleanup();
+      if (spawnError !== null) {
+        if (spawnError.code === "ENOENT")
+          settle(127);
+        else
+          reject(spawnError);
+        return;
+      }
+      if (signal !== null)
+        settle(128 + signalExitNumber(signal));
+      else
+        settle(code ?? 0);
+    });
+  });
+}
 // src/migrate.ts
 import { copyFileSync, mkdirSync as mkdirSync7, readFileSync as readFileSync8, readdirSync as readdirSync7, writeFileSync as writeFileSync5 } from "node:fs";
-import { dirname as dirname7, isAbsolute as isAbsolute7, join as join11, relative as relative3, resolve as resolve10, sep as sep2 } from "node:path";
+import { dirname as dirname7, isAbsolute as isAbsolute7, join as join11, relative as relative4, resolve as resolve10, sep as sep2 } from "node:path";
 var MIGRATE_STATUS_FILE = "status.json";
 var ARCHIVED_STATUS_V1_FILE = "archived/status.v1.json";
 var NOTES_LEDGER_FILE = "notes.jsonl";
@@ -2793,7 +3196,7 @@ var ROOT_METADATA_LIFT_KEYS = {
   program_roadmap: true,
   updated_at: true
 };
-function isPlainObject6(value) {
+function isPlainObject7(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function dateString(value) {
@@ -2973,10 +3376,10 @@ function applyRootMetadataLift(snapshot, metadata, migrationNotes, activeIterati
   if (typeof metadata.control_worktree_path === "string" && metadata.control_worktree_path !== "") {
     data.control_worktree_path = metadata.control_worktree_path;
   }
-  if (isPlainObject6(metadata.integration_merge_lease)) {
+  if (isPlainObject7(metadata.integration_merge_lease)) {
     data.integration_merge_lease = metadata.integration_merge_lease;
   }
-  const legacyMetadata = isPlainObject6(data.legacy_metadata) ? { ...data.legacy_metadata } : {};
+  const legacyMetadata = isPlainObject7(data.legacy_metadata) ? { ...data.legacy_metadata } : {};
   for (const [key, value] of Object.entries(metadata)) {
     if (key === "harness_root")
       continue;
@@ -3032,7 +3435,7 @@ function buildRegister(residualFindings, byPlan, projectId, migratedAt) {
     const raw = residualFindings[planId];
     if (!Array.isArray(raw))
       continue;
-    const open = raw.filter((entry) => isPlainObject6(entry) && isOpenResidual(entry)).sort((a, b) => {
+    const open = raw.filter((entry) => isPlainObject7(entry) && isOpenResidual(entry)).sort((a, b) => {
       const aId = typeof a.id === "string" ? a.id : "";
       const bId = typeof b.id === "string" ? b.id : "";
       return compareIds(aId, bId);
@@ -3121,12 +3524,12 @@ function migrateHarnessTree(root, opts = {}) {
   if (legacy.version === undefined) {
     throw new Error(`refusing to migrate: no v1 status.json found at ${statusPath} (nothing to migrate)`);
   }
-  const rows = Array.isArray(legacy.plans) ? legacy.plans.filter(isPlainObject6) : [];
+  const rows = Array.isArray(legacy.plans) ? legacy.plans.filter(isPlainObject7) : [];
   if (Array.isArray(legacy.plans)) {
     const unLiftable = [];
     const idCounts = new Map;
     for (const row of legacy.plans) {
-      if (!isPlainObject6(row) || rowIdOf(row) === null) {
+      if (!isPlainObject7(row) || rowIdOf(row) === null) {
         unLiftable.push(row);
         continue;
       }
@@ -3142,7 +3545,7 @@ function migrateHarnessTree(root, opts = {}) {
       throw new Error(`refusing to migrate: ${duplicates.length} duplicate plan id(s) (${duplicates.join(", ")}) — every v1 row must land in exactly one snapshot`);
     }
   }
-  const metadata = isPlainObject6(legacy.metadata) ? legacy.metadata : {};
+  const metadata = isPlainObject7(legacy.metadata) ? legacy.metadata : {};
   const rootUpdatedAt = dateString(legacy.updated_at) ?? dateString(metadata.updated_at) ?? todayString3();
   const migratedAt = dateString(metadata.updated_at) ?? rootUpdatedAt;
   const migrationNotes = [];
@@ -3179,9 +3582,9 @@ function migrateHarnessTree(root, opts = {}) {
     migrationNotes.push("no active iteration snapshot found — root metadata execution-policy/branch keys have no lift home and stay unmapped (visible here, not silently dropped)");
   }
   const notesFiles = collectNotesFiles(snapshots);
-  const residualFindings = isPlainObject6(legacy.residual_findings) ? legacy.residual_findings : {};
+  const residualFindings = isPlainObject7(legacy.residual_findings) ? legacy.residual_findings : {};
   const register = buildRegister(residualFindings, byPlan, projectId, migratedAt);
-  const programRoadmap = isPlainObject6(metadata.program_roadmap) ? metadata.program_roadmap : null;
+  const programRoadmap = isPlainObject7(metadata.program_roadmap) ? metadata.program_roadmap : null;
   let roadmap = null;
   if (programRoadmap) {
     const rawTitle = typeof programRoadmap.title === "string" && programRoadmap.title !== "" ? programRoadmap.title : "Program roadmap";
@@ -3250,8 +3653,8 @@ async function applyMigratePlan(plan) {
   if (!isAbsolute7(plan.workflowDir) || !isAbsolute7(plan.projectDir)) {
     throw new Error(`refusing to apply migration: plan workflowDir/projectDir must be absolute (got ${JSON.stringify(plan.workflowDir)} / ${JSON.stringify(plan.projectDir)})`);
   }
-  const workflowTargetOf = (canonicalFile) => join11(workflowRoot, relative3("workflows", canonicalFile));
-  const projectTargetOf = (canonicalFile) => join11(projectRoot, relative3("projects", canonicalFile));
+  const workflowTargetOf = (canonicalFile) => join11(workflowRoot, relative4("workflows", canonicalFile));
+  const projectTargetOf = (canonicalFile) => join11(projectRoot, relative4("projects", canonicalFile));
   const allDestinations = [
     plan.archive.file,
     ...plan.snapshots.map((snapshot) => snapshot.file),
@@ -4469,7 +4872,7 @@ function planFileRel(outDir, planFile) {
 }
 // src/compound.ts
 import { existsSync as existsSync9, readdirSync as readdirSync9, readFileSync as readFileSync10 } from "node:fs";
-import { basename as basename6, isAbsolute as isAbsolute8, join as join13, relative as relative4, resolve as resolve12, sep as sep4 } from "node:path";
+import { basename as basename6, isAbsolute as isAbsolute8, join as join13, relative as relative5, resolve as resolve12, sep as sep4 } from "node:path";
 function violation10(severity, code, message, fix) {
   return { ok: false, severity, code, message, fix };
 }
@@ -4807,7 +5210,7 @@ function collectKnowledgeDocs(dir) {
       if (entry.isDirectory()) {
         stack.push(full);
       } else if (entry.name.endsWith(".md") && entry.name !== "README.md" && entry.name !== "index.md") {
-        docs.push(relative4(dir, full).split(sep4).join("/"));
+        docs.push(relative5(dir, full).split(sep4).join("/"));
       }
     }
   }
@@ -4920,7 +5323,7 @@ function findTemporaryMarkers(fileText) {
     }
     markers.push({ line: i + 1, text, removalPath });
     if (removalPath === null) {
-      violations.push(violation11("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"'));
+      violations.push(violation11("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 20991231-example-plan removes this"'));
     }
   }
   return { ok: violations.length === 0, violations, markers };
@@ -5219,6 +5622,14 @@ function validateRoleMapping(rolesDir, options = {}) {
   return { ok: violations.length === 0, violations };
 }
 var LOAD_ORDER_HEADING_RE = /^#{1,6}\s+[^\r\n]*\b(?:load[\s-]*order|first\s+action)\b[^\r\n]*$/i;
+var HUB_BOOTSTRAP_ASSERTIONS = [
+  { marker: "identity-first", why: "identity boundary before any skill list" },
+  { marker: "skill presets", why: "Assignment Skill presets decision field" },
+  { marker: "none", why: "explicit none => identity only, no optional topic preset" },
+  { marker: "standard", why: "omitted on a substantive round => standard preset" },
+  { marker: "role-owned", why: "role-owned methods / evidence obligations load regardless of preset" },
+  { marker: "unknown preset", why: "unknown preset / missing identity => Needs Context / Blocked, never infer PM" }
+];
 function extractLoadOrderSection(text) {
   const lines = text.split(/\r?\n/);
   let start = -1;
@@ -5252,11 +5663,22 @@ function lintLoadOrder(skillTexts) {
       continue;
     const section = extractLoadOrderSection(text);
     if (section === null) {
-      violations.push(violation12("medium", "roles.loadorder.section.missing", `skill "${name}" has no Load Order / First action section — every mstar-* topic skill must declare its first read (mstar-harness-core § 加载约定; mstar-roles § Load Order (Required))`, `add a "## Load Order" section naming mstar-harness-core as the first read`));
+      violations.push(violation12("medium", "roles.loadorder.section.missing", `skill "${name}" has no Load Order / First action section — every mstar-* topic skill must declare its first read (mstar-harness-core § 加载契约; mstar-roles § Load Order = single load-selection authority)`, `add a "## Load Order" section: topics name mstar-harness-core first; mstar-roles declares the Skill presets decision matrix`));
+      continue;
+    }
+    if (name === "mstar-roles") {
+      const lower = section.toLowerCase();
+      const missing = HUB_BOOTSTRAP_ASSERTIONS.filter((a) => !lower.includes(a.marker.toLowerCase()));
+      if (missing.length > 0) {
+        violations.push(violation12("medium", "roles.loadorder.hub.bootstrap.missing", `skill "${name}" Load Order section is missing the hub bootstrap decision matrix: ${missing.map((m) => `"${m.marker}" (${m.why})`).join("; ")} (mstar-roles § Load Order = single load-selection authority)`, "declare identity-first, the Skill presets none/standard decision, role-owned methods, and the unknown-preset / missing-identity refusal in the Load Order section"));
+      }
+      if (!section.includes("mstar-harness-core")) {
+        violations.push(violation12("medium", "roles.loadorder.core.missing", `skill "${name}" Load Order section does not point at mstar-harness-core — the hub bootstrap is exempt from core-first, but core remains the lifecycle/authorization conflict authority and global entry whenever loaded`, "keep the conditional mstar-harness-core pointer (global entry / conflict authority) in the Load Order section"));
+      }
       continue;
     }
     if (!section.includes("mstar-harness-core")) {
-      violations.push(violation12("medium", "roles.loadorder.core.missing", `skill "${name}" Load Order section does not declare mstar-harness-core as its first dependency (mstar-harness-core § 加载约定: 凡 mstar-*（name ≠ mstar-harness-core）假定读者已 Read 本 skill)`, "name mstar-harness-core first in the Load Order section"));
+      violations.push(violation12("medium", "roles.loadorder.core.missing", `skill "${name}" Load Order section does not declare mstar-harness-core as its first dependency (mstar-harness-core § 加载契约: directly-invoked topics keep core as first dependency; the mstar-roles hub bootstrap is the only exception)`, "name mstar-harness-core first in the Load Order section"));
     }
   }
   return { ok: violations.length === 0, violations };
@@ -5338,6 +5760,16 @@ function collectHeadings(bodyText) {
   }
   return headings;
 }
+function classifySkillLint(skillId) {
+  const id = skillId ?? "";
+  if (id === "mstar-harness-core")
+    return { kind: "core", mode: null };
+  if (id === "mstar-skill-authoring")
+    return { kind: "authoring", mode: "authoring" };
+  if (id.startsWith("mstar-"))
+    return { kind: "runtime", mode: "runtime" };
+  return { kind: "authoring", mode: "authoring" };
+}
 var RUNTIME_HEADING_ALIASES = {
   workflow: ["process", "playbook"],
   "decision-rules": [
@@ -5413,7 +5845,7 @@ function computePrTally(input) {
 var REVIEW_SCHEMA_ID = "mstar.review/v1";
 var INSPECTOR_VERDICTS = ["comment", "request_changes", "approve"];
 var INSPECTOR_SEVERITIES = ["critical", "warning", "suggestion", "info"];
-function isPlainObject7(value) {
+function isPlainObject8(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 var TALLY_COUNT_KEYS = ["mustFix", "shouldFix", "nit", "unverified"];
@@ -5424,7 +5856,7 @@ function checkProvidedTallyShape(tally, violations) {
   if (typeof tally.scorePct !== "number" || !Number.isInteger(tally.scorePct) || tally.scorePct < 0 || tally.scorePct > 100) {
     violations.push(violation14("high", "review.tally-malformed", `tally.scorePct must be an integer in [0, 100] - got ${String(tally.scorePct)}`));
   }
-  if (!isPlainObject7(tally.tally)) {
+  if (!isPlainObject8(tally.tally)) {
     violations.push(violation14("high", "review.tally-malformed", "tally.tally must be an object carrying the four class counts"));
   } else {
     for (const key of TALLY_COUNT_KEYS) {
@@ -5440,7 +5872,7 @@ function checkProvidedTallyShape(tally, violations) {
 }
 function validateMstarReviewV1(doc) {
   const violations = [];
-  if (!isPlainObject7(doc)) {
+  if (!isPlainObject8(doc)) {
     return {
       ok: false,
       violations: [violation14("high", "review.not-object", "review document must be a JSON object")]
@@ -5467,7 +5899,7 @@ function validateMstarReviewV1(doc) {
     violations.push(violation14("high", "review.findings-not-array", "findings must be an array"));
   } else {
     doc.findings.forEach((finding, index) => {
-      if (!isPlainObject7(finding)) {
+      if (!isPlainObject8(finding)) {
         violations.push(violation14("high", "review.invalid-finding", `findings[${index}] must be an object`));
         return;
       }
@@ -5507,7 +5939,7 @@ function validateMstarReviewV1(doc) {
     });
   }
   if (doc.tally !== undefined) {
-    if (!isPlainObject7(doc.tally)) {
+    if (!isPlainObject8(doc.tally)) {
       violations.push(violation14("high", "review.invalid-tally", "tally must be a PrTallyResult object"));
     } else {
       checkProvidedTallyShape(doc.tally, violations);
@@ -5517,7 +5949,7 @@ function validateMstarReviewV1(doc) {
     }
   }
   if (doc.target !== undefined) {
-    if (!isPlainObject7(doc.target)) {
+    if (!isPlainObject8(doc.target)) {
       violations.push(violation14("high", "review.invalid-target", "target must be an object"));
     } else {
       if (doc.target.owner !== undefined && typeof doc.target.owner !== "string") {
@@ -6198,7 +6630,10 @@ export {
   assertTriIdentity,
   assignmentHeaderRegion,
   canSteal,
+  canonicalizeNearestExisting,
+  checkSddAction,
   claimLease,
+  classifySkillLint,
   closeProjectRegisterEntry,
   completenessLevel,
   composeDispatchGate,
@@ -6267,10 +6702,12 @@ export {
   resolveRepoEnforcement,
   resolveScaffoldDirs,
   resolveSddDir,
+  resolveSddExecutionContext,
   resolveSkillRoot,
   resolveSpecsDir,
   resolveWorkflowDir,
   reviewPackage,
+  runInSddContext,
   sameHolderResume,
   scaffoldAuditPlan,
   scaffoldHarness,