@mstar-harness/dsh 3.6.3 → 3.7.0

package/dist/index.js

@@ -1149,11 +1149,11 @@ import { dirname as dirname4, join as join7, resolve as resolve5, sep } from "no
 import { execFileSync as execFileSync2 } from "node:child_process";
 import { existsSync as existsSync7 } from "node:fs";
 import { isAbsolute as isAbsolute5, resolve as resolve8 } from "node:path";
-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 { basename as basename4, dirname as dirname6, isAbsolute as isAbsolute6, join as join10, relative as relative3, resolve as resolve9 } from "node:path";
 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";
 import { existsSync as existsSync10 } from "node:fs";
 import { join as join14 } from "node:path";
 var SEVERITY_ORDER = ["critical", "high", "medium", "low", "nit"];
@@ -2467,6 +2467,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);
@@ -2626,6 +2645,16 @@ function l2PreDispatchCheck(input, opts = {}) {
   });
   return gate(violations);
 }
+function assertBranchAlignment(worktreePath, expectedBranch, opts = {}) {
+  const violations = [];
+  const probe = probeBranch(worktreePath, opts);
+  if ("error" in probe) {
+    violations.push(violation7("high", "worktree.branch-probe-failed", `cannot probe branch at "${worktreePath}": ${probe.error}`, "verify the path is a git worktree checkout on the expected branch (not detached)"));
+  } else if (probe.branch !== expectedBranch) {
+    violations.push(violation7("high", "worktree.branch-mismatch", `worktree "${worktreePath}" is on branch "${probe.branch}", expected "${expectedBranch}" (Assignment Working branch)`, `checkout ${expectedBranch} in that worktree`));
+  }
+  return gate(violations);
+}
 class SddScriptError extends Error {
   exitCode;
   constructor(message, exitCode) {
@@ -2763,6 +2792,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");
@@ -2770,8 +2809,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) {
@@ -2780,6 +2823,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(`
@@ -2804,7 +2854,98 @@ 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 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 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 violation8(severity, code, message, fix) {
   return { ok: false, severity, code, message, fix };
@@ -3590,7 +3731,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("/"));
       }
     }
   }
@@ -3847,6 +3988,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;
@@ -3880,11 +4029,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 };
@@ -3920,6 +4080,17 @@ var FIVE_QUESTION_SECTIONS = [
   { 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" }
 ];
+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 HEADING_RE = /^#{1,6}\s+[^\r\n]+$/;
 function collectHeadings(bodyText) {
   const headings = [];
@@ -3935,6 +4106,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": [
@@ -4176,7 +4357,7 @@ import { basename as basename2, join as join5, resolve as resolve6 } from "node:
 
 // src/gates/workflow-selection.ts
 import { existsSync as existsSync5, readdirSync as readdirSync2, statSync as statSync2 } from "node:fs";
-import { dirname as dirname7, join as join3, relative as relative3 } from "node:path";
+import { dirname as dirname7, join as join3, relative as relative4 } from "node:path";
 var TERMINAL_STATUS_CACHE_MAX = 64;
 var terminalStatusCache = new Map;
 function terminalStatusOf(snapshotPath) {
@@ -4298,7 +4479,7 @@ function resolveReadWorkflow(harnessDir) {
     if (verdict === undefined || !verdict.terminal)
       continue;
     if (best === undefined || verdict.mtimeMs > best.mtimeMs) {
-      best = { workflowId: entry.name, dir: join3(relative3(harnessDir, workflowsDir), entry.name), mtimeMs: verdict.mtimeMs };
+      best = { workflowId: entry.name, dir: join3(relative4(harnessDir, workflowsDir), entry.name), mtimeMs: verdict.mtimeMs };
     }
   }
   for (const cachedPath of terminalStatusCache.keys()) {
@@ -5923,14 +6104,14 @@ function agentDigestKey(agent, cwd) {
 
 // src/gates/status.ts
 import { existsSync as existsSync14, readdirSync as readdirSync7 } from "node:fs";
-import { basename as basename5, join as join11, relative as relative5, resolve as resolve10 } from "node:path";
+import { basename as basename5, join as join11, relative as relative6, resolve as resolve10 } from "node:path";
 var LOGGER_NAME = "mstar/status-gate";
 function harnessDocKindOfTarget(harnessDir, targetPath) {
   const resolved = resolve10(targetPath);
   const name = basename5(resolved);
   if (name !== STATUS_FILE && name !== WORKFLOW_SNAPSHOT_FILE && name !== PROJECT_REGISTER_FILE)
     return null;
-  const rel = relative5(harnessDir, resolved);
+  const rel = relative6(harnessDir, resolved);
   if (name === STATUS_FILE && rel === STATUS_FILE)
     return "status";
   let workflowDir;
@@ -5942,9 +6123,9 @@ function harnessDocKindOfTarget(harnessDir, targetPath) {
     workflowDir = join11(harnessDir, "workflows");
     projectDir = join11(harnessDir, "projects");
   }
-  if (name === WORKFLOW_SNAPSHOT_FILE && /^[^/]+\/snapshot\.json$/.test(relative5(workflowDir, resolved)))
+  if (name === WORKFLOW_SNAPSHOT_FILE && /^[^/]+\/snapshot\.json$/.test(relative6(workflowDir, resolved)))
     return "snapshot";
-  if (name === PROJECT_REGISTER_FILE && /^[^/]+\/residuals\.json$/.test(relative5(projectDir, resolved)))
+  if (name === PROJECT_REGISTER_FILE && /^[^/]+\/residuals\.json$/.test(relative6(projectDir, resolved)))
     return "register";
   return null;
 }
@@ -6093,17 +6274,6 @@ ${violations.map(formatViolation).join(`
     this.violations = violations;
   }
 }
-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 EPHEMERAL_CODES = {
   "task-artifact": "skill.ephemeral.task-artifact",
   "sdd-deeplink": "skill.ephemeral.sdd-deeplink"
@@ -6116,19 +6286,23 @@ function ephemeralViolation(citation) {
     message: `ephemeral citation \`${citation.match}\` on line ${citation.line} — durable skill text must reference in-repo artifacts only (knowledge conventions/skill-content-porting-discipline.md §3)`
   };
 }
-function lintSkillDoc(doc) {
+function lintSkillDoc(doc, options = {}) {
   const violations = [];
   const frontmatter = lintSkillFrontmatter(doc);
   if (!frontmatter.ok)
     violations.push(...frontmatter.violations);
-  const body = lintFiveQuestion(stripFrontmatter(doc));
-  if (!body.ok)
-    violations.push(...body.violations);
+  const profile = classifySkillLint(options.skillId);
+  if (profile.mode !== null) {
+    const body = lintFiveQuestion(stripFrontmatter(doc), profile.mode);
+    if (!body.ok)
+      violations.push(...body.violations);
+  }
   violations.push(...findEphemeralCitations(doc).map(ephemeralViolation));
   return violations.length === 0 ? { ok: true, violations } : { ok: false, violations };
 }
 function lintSkillWrite(doc, options) {
-  const result = lintSkillDoc(doc);
+  const skillId = basename7(dirname9(resolve13(options.target)));
+  const result = lintSkillDoc(doc, { skillId });
   if (options.hard && !result.ok) {
     throw new SkillLintVetoError(options.target, result.violations);
   }
@@ -6176,7 +6350,7 @@ function gateSkillIntent(ctx, harnessDir, config, target) {
       });
       return;
     }
-    const result = lintSkillDoc(doc);
+    const result = lintSkillDoc(doc, { skillId: basename7(dirname9(skillPath)) });
     if (result.ok)
       return;
     const hard = resolveSeamHard(harnessDir, config);
@@ -8368,9 +8542,17 @@ function packagedCommandsDir() {
     return;
   }
 }
+var FRONTMATTER_FIELD_RE = /^[ \t]*:[ \t]*(.+)$/;
 function commandFrontmatterField(frontmatter, label) {
-  const match = new RegExp(`^${label}[ \\t]*:[ \\t]*(.+)$`, "m").exec(frontmatter);
-  return match?.[1]?.trim();
+  for (const line of frontmatter.split(`
+`)) {
+    if (!line.startsWith(label))
+      continue;
+    const match = FRONTMATTER_FIELD_RE.exec(line.slice(label.length));
+    if (match)
+      return match[1].trim();
+  }
+  return;
 }
 function unquote2(value) {
   return value.length >= 2 && value.startsWith('"') && value.endsWith('"') ? value.slice(1, -1) : value;

package/dist/types.d.ts

@@ -108,8 +108,7 @@ export interface HarnessPlanView {
     readonly doneAt: string | null;
     /**
      * The `status.json` plan row `metadata.iteration_refs` (array of iteration
-     * ids the plan is registered under). ALWAYS-present array (plan
-     * `20260813-panel-quick-fixes` Task 2): a missing/non-array value projects
+     * ids the plan is registered under). ALWAYS-present array: a missing/non-array value projects
      * to `[]` — the empty default, never an omitted field (lossless JSON).
      */
     readonly iterationRefs: string[];
@@ -204,8 +203,7 @@ export interface MstarHarnessState {
      * projected loose (`string`) like `HarnessPlanView.status`. ALWAYS-present
      * nullable scalar (lossless JSON, never omitted): missing/empty → `null`;
      * `null` on selection error (no snapshot read). Added for the slim
-     * `mstar:engine-status` digest (plan `20260820-dsh-engine-status-slim`).
-     */
+     * `mstar:engine-status` digest.   */
     readonly workflowType: string | null;
     /**
      * The selected workflow snapshot's top-level lifecycle `status`
@@ -269,8 +267,7 @@ export interface MstarHarnessState {
 }
 /**
  * One agent-flow ledger event in the catalog view. Optional fields (dispatch/
- * settle + the W-B2 `workflow-*` kinds — plan `20260815-dsh-workflow-ledger`
- * Task 2) are OMITTED (never `undefined`-valued properties — `Session.append`
+ * settle + the W-B2 `workflow-*` kinds — plan  ) are OMITTED (never `undefined`-valued properties — `Session.append`
  * rejects non-lossless JSON) using the `iterationViolationView` omit pattern.
  */
 export interface AgentFlowEventView {
@@ -292,7 +289,7 @@ export interface AgentFlowEventView {
     /** Settle duration in ms (settle events only, when recorded). */
     readonly durationMs?: number | null;
     /**
-     * Settle rows only (plan `20260811-panel-f4-timeliness` Task 1): true when
+     * Settle rows only : true when
      * the settle carries the PAIRED dispatch's identity (`role`/`planId`/
      * `taskId` — same fields + semantics as the dispatch event) — the client
      * pairs exactly on that identity. ABSENT on unpaired (legacy) settles →

package/harness-commands/iteration-drive.md

@@ -7,7 +7,7 @@ input: "[no args]"
 
 # Drive Iteration
 
-Drive the active Morning Star iteration forward. **Boot loads skills; this command sequences Phase 2 → 3 → 4 → 5.** Phase gate SSOT → **`mstar-iteration`** §2–§5；本 command 仅补充 **可选第三方 helper skill 发现**（Phase 5），不反向写入 `mstar-*`。
+Drive the active Morning Star iteration forward. **Boot loads skills; this command sequences Phase 2 → 3 → 4 → 5.** Phase route + gate SSOT → **`mstar-iteration`** Phase route map + **Phase transition gates** table（§2 detail → `references/phase-2-worktree-lease.md`；§3 → `references/phase-3-iteration-close.md`；§4–§5 → `references/phase-4-5-pr-delivery.md`）；本 command 仅补充 **可选第三方 helper skill 发现**（Phase 5），不反向写入 `mstar-*`。
 
 ## Phase flow（禁止跳步）
 
@@ -21,25 +21,25 @@ Phase 2–5 共享内容（PM invariants、assignment preflight、session todos
 
 ## Boot
 
-按 **`mstar-iteration`** Load order 加载（`mstar-harness-core` → `mstar-roles` → `references/project-manager.md` → `mstar-iteration` § Phase 2–5 + `command-shared-invariants.md` → `mstar-compound` → `mstar-dispatch-gates` + host reference → **`mstar-sdd`**（first implement dispatch 前）→ `mstar-review-qc`（first QC 前）→ `mstar-artifacts` / `mstar-conventions` / `mstar-branch-worktree` → **`mstar-iteration/references/phase-2-worktree-lease.md`**）。完整 load list → **`mstar-roles`**。
+按 **`mstar-iteration`** Load order 加载（`mstar-harness-core` → `mstar-roles` → `references/project-manager.md` → `mstar-iteration`（按当前 Phase 查 route map，只加载一行 detail）+ `command-shared-invariants.md` → `mstar-compound` → `mstar-dispatch-gates` + host reference → **`mstar-sdd`**（first implement dispatch 前）→ `mstar-review-qc`（first QC 前）→ `mstar-artifacts` / `mstar-conventions` / `mstar-branch-worktree` → **`mstar-iteration/references/phase-2-worktree-lease.md`**）。完整 load list → **`mstar-roles`**。
 
 ## Phase 2: Autonomous Execute
 
-Execute **`mstar-iteration` § Phase 2** exactly（§2.0 五道闸 → §2.1 session todos → §2.2 backlog → §2.3 integration branch + control worktree → §2.4 per-plan loop（lease-gated；SDD per-task；QC tri N=3 + QA；serial merge）→ §2.5 dispatch-first → §2.6 push 纪律）。全部 plan `Done` → **STOP** → 打印 `## Phase 3: iteration-close`。
+Execute **`mstar-iteration/references/phase-2-worktree-lease.md`** §2.0–§2.5 exactly（§2.0 五道闸 → §2.1 session todos → §2.2 backlog → §2.3 integration branch + control worktree → §2.4 per-plan loop（lease-gated；SDD per-task；QC tri N=3 + QA；serial merge）→ §2.5 dispatch-first；§2.6 push 纪律 → main skill `## 2.6`）。全部 plan `Done` → **STOP** → 打印 `## Phase 3: iteration-close`。
 
 **Assignment preflight**：每次 implement/QC/QA 派发前按 **`mstar-iteration/references/command-shared-invariants.md`** 执行。
 
 ## Phase 3: iteration-close
 
-当 **every** plan 为 `Done`：**STOP** per-plan loop → 打印 **`## Phase 3: iteration-close`** → execute **`mstar-iteration` § Phase 3**（→ **`references/phase-3-iteration-close.md`** §3.0→§3.5；§3.1 entry checklist HARD GATE；§3.2 compound + package promotion；§3.4 `status: completed` + `end_date`）→ §3.5 exit 全 `[x]` 后打印 **`## Phase 4: Create PR`**。
+当 **every** plan 为 `Done`：**STOP** per-plan loop → 打印 **`## Phase 3: iteration-close`** → execute **`mstar-iteration/references/phase-3-iteration-close.md`** §3.0→§3.5（§3.1 entry checklist HARD GATE；§3.2 compound + package promotion；§3.4 `status: completed` + `end_date`）→ §3.5 exit 全 `[x]` 后打印 **`## Phase 4: Create PR`**。
 
 ## Phase 4: Create PR
 
-Execute **`mstar-iteration` § Phase 4**（→ **`references/phase-4-5-pr-delivery.md`**）：打印 `## Phase 4: Create PR` → resolve `metadata.target_branch`（缺失 → **STOP**，never default `main`/`master`）→ 创建 PR `spec_integration_branch` → `target_branch` → 记录 PR URL + number → 勾掉 `phase-4-create-pr` → **Immediately** 打印 **`## Phase 5: PR merge-ready`**（**禁止**在此停止或汇报 Done）。
+Execute **`mstar-iteration/references/phase-4-5-pr-delivery.md`** §4：打印 `## Phase 4: Create PR` → resolve `metadata.target_branch`（缺失 → **STOP**，never default `main`/`master`）→ 创建 PR `spec_integration_branch` → `target_branch` → 记录 PR URL + number → 勾掉 `phase-4-create-pr` → **Immediately** 打印 **`## Phase 5: PR merge-ready`**（**禁止**在此停止或汇报 Done）。
 
 ## Phase 5: PR merge-ready（babysit loop）
 
-Execute **`mstar-iteration` § Phase 5**（→ **`references/phase-4-5-pr-delivery.md`** §5.0–§5.2；**§5.1a push cadence HARD**）。**§5.5 exit checklist 全 `[x]` = 本 command Done.**
+Execute **`mstar-iteration/references/phase-4-5-pr-delivery.md`** §5.0–§5.2（**§5.1a push cadence HARD**）。**§5.5 exit checklist 全 `[x]` = 本 command Done.**
 
 本 command **叠加**可选 helper skill 发现（**non-`mstar-*`**；不写入 `mstar-*` load order）→ **`mstar-iteration/references/phase5-helper-discovery.md`**（babysit / `*-babysit` / greploop / fallback 路径清单；first readable `SKILL.md` wins）。Loop + review fix hygiene + exit checklist → §5.1–§5.2（同上 reference）。
 

package/harness-commands/iteration-loop.md

@@ -16,7 +16,7 @@ Run a **full** Morning Star iteration with minimal human intervention. **Done =
 | `iteration-drive` | Phase 2→5 re-entry / resume on an already locked iteration |
 | **`iteration-loop`** | Phase 1→5 end-to-end; **autonomous** direction lock |
 
-Phase gate SSOT → **`mstar-iteration`** §1–§5. This command is a **consumer**; it does not redefine skill semantics.
+Phase route + gate SSOT → **`mstar-iteration`** **Phase route map** + **Phase transition gates** table. This command is a **consumer**; it does not redefine skill semantics.
 
 ## Args（最多 2 个）
 
@@ -29,7 +29,7 @@ Phase gate SSOT → **`mstar-iteration`** §1–§5. This command is a **consume
 | `direction` | Iteration direction / feedback constraint (free text) | Code-first research → **auto-lock recommended** |
 | `scale` | `S` \| `M` \| `L` \| `XL` | **`M`** |
 
-**Scale budget**（写入 compass；约束 **业务** plan 数量）→ **`mstar-iteration`** §1.2 + `references/autonomous-direction-lock.md`：
+**Scale budget**（写入 compass；约束 **业务** plan 数量）→ **`mstar-iteration/references/phase-1-prepare.md`** §1.2 + `references/autonomous-direction-lock.md`：
 
 - **S** → 1 business plan
 - **M** → 2–3 business plans
@@ -52,7 +52,7 @@ Execute **`mstar-iteration` §2.6**（Continuous execution SSOT）+ **`mstar-ite
 
 ## Boot
 
-按 **`mstar-iteration`** Load order 加载（`mstar-harness-core` → `mstar-roles` → `references/project-manager.md` → `mstar-iteration` § Phase 1–5 + `command-shared-invariants.md` → `mstar-dispatch-gates` → `mstar-phase-gates` → `mstar-conventions` / `mstar-artifacts` → `mstar-host` → `mstar-compound`（Phase 3 前）→ **`mstar-sdd`**（first implement 前）→ `mstar-review-qc`（first QC 前）→ `mstar-branch-worktree` → **`mstar-iteration/references/phase-2-worktree-lease.md`**）。完整 load list → **`mstar-roles`**。
+按 **`mstar-iteration`** Load order 加载（`mstar-harness-core` → `mstar-roles` → `references/project-manager.md` → `mstar-iteration`（按当前 Phase 查 route map，只加载一行 detail）+ `command-shared-invariants.md` → `mstar-dispatch-gates` → `mstar-phase-gates` → `mstar-conventions` / `mstar-artifacts` → `mstar-host` → `mstar-compound`（Phase 3 前）→ **`mstar-sdd`**（first implement 前）→ `mstar-review-qc`（first QC 前）→ `mstar-branch-worktree` → **`mstar-iteration/references/phase-2-worktree-lease.md`**）。完整 load list → **`mstar-roles`**。
 
 **Session todos（loop 专属；Phase 2–5 共享 rows → `command-shared-invariants.md`）**：
 
@@ -62,7 +62,7 @@ Execute **`mstar-iteration` §2.6**（Continuous execution SSOT）+ **`mstar-ite
 
 ## Phase 1: Autonomous start
 
-Execute **`mstar-iteration` § Phase 1**（**autonomous** direction lock + scale budget + branch resolve SSOT → `references/autonomous-direction-lock.md`）：
+Execute **`mstar-iteration/references/phase-1-prepare.md`**（§1.1–§1.6；**autonomous** direction lock + scale budget + branch resolve SSOT → `references/autonomous-direction-lock.md`）：
 
 ### 1–4. Research → Explore → Lock → Write
 
@@ -70,7 +70,7 @@ Survey structured harness dirs（`{HARNESS_DIR}/status.json`、`{ITERATION_DIR}/
 
 ### 5. Review & Edit Chain（HARD GATE）
 
-Execute **`mstar-iteration` §1.6**：`product-manager` → `architect` → `writing-specialist` 顺序 invoke（**禁止** `{KNOWLEDGE_DIR}/` 新增；corpus hygiene）→ PM lock。**Assignment preflight** per **`command-shared-invariants.md`**。
+Execute **`mstar-iteration/references/phase-1-prepare.md` §1.6**：`product-manager` → `architect` → `writing-specialist` 顺序 invoke（**禁止** `{KNOWLEDGE_DIR}/` 新增；corpus hygiene）→ PM lock。**Assignment preflight** per **`command-shared-invariants.md`**。
 
 **Pre-commit checklist**（print before §6；all `[x]`）：
 
@@ -84,7 +84,7 @@ Execute **`mstar-iteration` §1.6**：`product-manager` → `architect` → `wri
 
 ### 6. Integration Branch
 
-Per **`mstar-iteration` §2.3**（create from `iteration_base_branch`；register branch fields；commit docs；push）。**STOP** if base/target missing。**Immediately** print `## Phase 2: Autonomous Execute` → continue（勾掉 `phase-1-autonomous-start`）。
+Per **`mstar-iteration/references/phase-2-worktree-lease.md` §2.3**（create from `iteration_base_branch`；register branch fields；commit docs；push）。**STOP** if base/target missing。**Immediately** print `## Phase 2: Autonomous Execute` → continue（勾掉 `phase-1-autonomous-start`）。
 
 ---
 
@@ -92,7 +92,7 @@ Per **`mstar-iteration` §2.3**（create from `iteration_base_branch`；register
 
 Delegate to **`iteration-drive`**（Phase 2 → §2、Phase 3 → §3 + `references/phase-3-iteration-close.md`、Phase 4/5 → §4–§5 + `references/phase-4-5-pr-delivery.md`、Phase 5 helper discovery → `phase5-helper-discovery.md`）。**Assignment preflight** per **`command-shared-invariants.md`**。
 
-**Loop 特有**：Phase 5 push cadence（HARD）→ **`mstar-iteration` §5.1a**；exit checklist → §5.2（`references/phase-4-5-pr-delivery.md`）。
+**Loop 特有**：Phase 5 push cadence（HARD）→ **`mstar-iteration/references/phase-4-5-pr-delivery.md`** §5.1a；exit checklist → §5.2（同 reference）。
 
 **Then** report: iteration id, locked direction + scale, plans completed, compound summary, PR link, merge-ready evidence。
 

package/harness-commands/iteration-start.md

@@ -30,7 +30,7 @@ Start a new Morning Star harness iteration. **Phase 1 is not complete until the
 |-----------------|------------------------|
 | 自己 Edit compass/plans/specs 冒充 product-manager / architect / writing-specialist 的审查编辑 | §5.1 → §5.2 → §5.3 **顺序**各 **1 次 invoke**；上一角色返回后再派发下一角色 |
 | 只写 `## Assignment` 或 checklist 就声称 review chain 完成 | **几条角色 ⇒ 几条 invoke**；零 invoke = `dispatch incomplete`（`mstar-dispatch-gates`） |
-| §5 完成前 commit / 创建 integration 分支 | 5.4 PM lock 在 subagent 返回且磁盘产物已修订之后（`mstar-iteration` §1.6） |
+| §5 完成前 commit / 创建 integration 分支 | 5.4 PM lock 在 subagent 返回且磁盘产物已修订之后（`mstar-iteration/references/phase-1-prepare.md` §1.6） |
 
 派发细则 → **`mstar-dispatch-gates`**（specialist review-and-edit dispatch）+ **`mstar-host`**（宿主 invoke 能力）。**不得**在 PM 线程加载其他 role reference 代劳。
 
@@ -49,7 +49,7 @@ Start a new Morning Star harness iteration. **Phase 1 is not complete until the
 
 ## 0. Boot
 
-按 **`mstar-iteration`** Load order 加载（`mstar-harness-core` → `mstar-roles` → `references/project-manager.md` → `mstar-iteration` § Phase 1 + `mstar-phase-gates` + `mstar-dispatch-gates` + `mstar-conventions/artifacts` + `mstar-host` → active host reference）。Cursor Plan mode 另读 **`cursor-plan-mode-bridge.md`**（`mstar-iteration` Phase 1 in Plan mode）。完整 load list → **`mstar-roles`**。
+按 **`mstar-iteration`** Load order 加载（`mstar-harness-core` → `mstar-roles` → `references/project-manager.md` → `mstar-iteration`（route map：start → **`references/phase-1-prepare.md`**）+ `mstar-phase-gates` + `mstar-dispatch-gates` + `mstar-conventions/artifacts` + `mstar-host` → active host reference）。Cursor Plan mode 另读 **`cursor-plan-mode-bridge.md`**（`mstar-iteration` Phase 1 in Plan mode）。完整 load list → **`mstar-roles`**。
 
 **若 Cursor Plan mode 活跃 → 进入 §P；否则继续 §1。**
 
@@ -76,17 +76,17 @@ Scope **2–4** candidates targeting **product completeness**（default to defer
 
 > **非 Plan 路径**。Cursor Plan mode 用 §P feedback loop + deferred grill（主路径不是 grill）。
 
-**Direction lock mode: `interactive`**（`mstar-iteration` §1.2 默认；本命令不使用 `autonomous`）。This command bundles a **non-`mstar-*`** skill at `skills/grill-me/SKILL.md` — **only this command step** references it.
+**Direction lock mode: `interactive`**（`mstar-iteration/references/phase-1-prepare.md` §1.2 默认；本命令不使用 `autonomous`）。This command bundles a **non-`mstar-*`** skill at `skills/grill-me/SKILL.md` — **only this command step** references it.
 
-**Before this step:** Read `skills/grill-me/SKILL.md`. Run **grill-me** to stress-test candidate directions with the user: walk through trade-offs, converge on a **single iteration direction** with shared understanding, document locked direction + success criteria + non-goals。**If `direction` arg given** — seed grill-me with it (still interactive; the hint does **not** skip grill-me)。Confirm delivery branch policy（`iteration_base_branch` / `target_branch`）per **`mstar-iteration` §1.2** — **Do not default to `main`/`master` just because those names exist.**
+**Before this step:** Read `skills/grill-me/SKILL.md`. Run **grill-me** to stress-test candidate directions with the user: walk through trade-offs, converge on a **single iteration direction** with shared understanding, document locked direction + success criteria + non-goals。**If `direction` arg given** — seed grill-me with it (still interactive; the hint does **not** skip grill-me)。Confirm delivery branch policy（`iteration_base_branch` / `target_branch`）per **`mstar-iteration/references/phase-1-prepare.md` §1.2** — **Do not default to `main`/`master` just because those names exist.**
 
 ## 4. Write Compass & Plans
 
-Produce harness artifacts per **`mstar-iteration` §1.3–§1.5**（template: `mstar-iteration/references/iteration-compass-template.md`）：compass（frontmatter **must** include `iteration_base_branch`、`target_branch`、`status: active`）、plans、`status.json` 登记（§1.5）、`{ITERATION_DIR}/README.md` 索引（一行 = 一次迭代）、package dirs（`{ITERATION_DIR}/<iteration-id>/{guides,specs}/`）。
+Produce harness artifacts per **`mstar-iteration/references/phase-1-prepare.md` §1.3–§1.5**（template: `mstar-iteration/references/iteration-compass-template.md`）：compass（frontmatter **must** include `iteration_base_branch`、`target_branch`、`status: active`）、plans、`status.json` 登记（§1.5）、`{ITERATION_DIR}/README.md` 索引（一行 = 一次迭代）、package dirs（`{ITERATION_DIR}/<iteration-id>/{guides,specs}/`）。
 
 ## 5. Review & Edit Chain（HARD GATE — do not commit before this）
 
-Execute **`mstar-iteration` §1.6**（SSOT）：顺序 `product-manager` → `architect` → `writing-specialist` → PM lock（**禁止**并行三 roles；OpenCode plain role id — `mstar-host/references/opencode.md`）；**禁止** `{KNOWLEDGE_DIR}/` 新增；writing-specialist corpus hygiene（`iteration-artifact-boundaries.md` + `iteration-corpus-hygiene.md`）。Tool rule → **`mstar-dispatch-gates`** specialist review-and-edit（每 role 1 invoke，等磁盘修订返回）。Exception: user explicitly waives subagent dispatch ("PM-only review").
+Execute **`mstar-iteration/references/phase-1-prepare.md` §1.6**（SSOT）：顺序 `product-manager` → `architect` → `writing-specialist` → PM lock（**禁止**并行三 roles；OpenCode plain role id — `mstar-host/references/opencode.md`）；**禁止** `{KNOWLEDGE_DIR}/` 新增；writing-specialist corpus hygiene（`iteration-artifact-boundaries.md` + `iteration-corpus-hygiene.md`）。Tool rule → **`mstar-dispatch-gates`** specialist review-and-edit（每 role 1 invoke，等磁盘修订返回）。Exception: user explicitly waives subagent dispatch ("PM-only review").
 
 **Assignment preflight**：每次 invoke 前按 **`mstar-iteration/references/command-shared-invariants.md`** 执行（warn-only + `enforcement: hard` fail-fast；bin 缺失静默跳过）。
 
@@ -109,13 +109,13 @@ PM must print this block before §6; all `[ ]` must be `[x]`:
 
 ## 6. Integration Branch
 
-Per **`mstar-iteration` §2.3**：create `spec_integration_branch` from `iteration_base_branch`（`git fetch` → `git checkout -b <spec_integration_branch> <iteration_base_branch>`）；register `iteration_base_branch` / `spec_integration_branch` / `target_branch` in compass frontmatter **and** `status.json` metadata；commit docs；push。**STOP** if `iteration_base_branch` / `target_branch` missing — never default `main`/`master`.
+Per **`mstar-iteration/references/phase-2-worktree-lease.md` §2.3**：create `spec_integration_branch` from `iteration_base_branch`（`git fetch` → `git checkout -b <spec_integration_branch> <iteration_base_branch>`）；register `iteration_base_branch` / `spec_integration_branch` / `target_branch` in compass frontmatter **and** `status.json` metadata；commit docs；push。**STOP** if `iteration_base_branch` / `target_branch` missing — never default `main`/`master`.
 
 ---
 
 ## 7. Phase 2–5（auto-continue）
 
-**`pause` arg → command ends here**（Phase 1 locked + integration pushed；run `/iteration-drive` later）。**Default（no `pause`）→ auto-continue**：execute **`iteration-drive`**（Phase 2 → **`mstar-iteration` §2**；Phase 3 → §3 + `references/phase-3-iteration-close.md`；Phase 4/5 → §4–§5 + `references/phase-4-5-pr-delivery.md`；Phase 5 helper discovery → `phase5-helper-discovery.md`）。Shared invariants / preflight / STOP → **`mstar-iteration/references/command-shared-invariants.md`**。
+**`pause` arg → command ends here**（Phase 1 locked + integration pushed；run `/iteration-drive` later）。**Default（no `pause`）→ auto-continue**：execute **`iteration-drive`**（Phase 2 → **`mstar-iteration/references/phase-2-worktree-lease.md`**；Phase 3 → `references/phase-3-iteration-close.md`；Phase 4/5 → `references/phase-4-5-pr-delivery.md`；Phase 5 helper discovery → `phase5-helper-discovery.md`）。Shared invariants / preflight / STOP → **`mstar-iteration/references/command-shared-invariants.md`**。
 
 **Done = Phase 5 §5.5 exit checklist 全 `[x]`**（同 `iteration-drive`）。**Then** report: iteration id, direction lock summary, plans completed, compound summary, PR link, merge-ready evidence（CI snapshot + review resolution + Greptile if applicable）。