@mstar-harness/dsh 3.5.1 → 3.6.0-alpha.2

package/dist/index.js

@@ -4036,6 +4036,13 @@ function formatViolation(violation14) {
 function asRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value) ? value : undefined;
 }
+var CATALOG_STATE_JOIN_LIMIT = 8;
+function joinCapped(items, cap, separator, render) {
+  const visible = items.slice(0, cap).map(render);
+  if (items.length > cap)
+    visible.push(`+${items.length - cap} more`);
+  return visible.join(separator);
+}
 function resolveSeamHard(harnessDir, config) {
   if (config.enforcement === "hard")
     return true;
@@ -5491,7 +5498,7 @@ function renderEngineStatusCatalog(source) {
       if (state.selection.kind === "active" && state.selection.warning !== undefined) {
         lines.push(`workflow warning: ${state.selection.warning.code} ${state.selection.warning.message}`);
       }
-      lines.push(`plans: ${state.plans.length === 0 ? "none registered" : state.plans.map((p) => `${p.id}(${p.status})`).join(" ")}`);
+      lines.push(`plans: ${state.plans.length === 0 ? "none registered" : joinCapped(state.plans, CATALOG_STATE_JOIN_LIMIT, " ", (p) => `${p.id}(${p.status})`)}`);
       lines.push(`residuals: ${state.residuals.length === 0 ? "none open" : state.residuals.map((r) => `${r.severity} ${r.count}`).join(", ")}`);
       if (state.iterationBaseBranch !== null && state.targetBranch !== null) {
         const integration = state.specIntegrationBranch !== null ? ` (spec integration: ${state.specIntegrationBranch})` : "";
@@ -5504,7 +5511,7 @@ function renderEngineStatusCatalog(source) {
       ].filter((part) => part !== null).join("; ");
       if (policy !== "")
         lines.push(`policy: ${policy}`);
-      lines.push(`leases: ${state.leases.length === 0 ? "none active" : state.leases.map((l) => `${l.planId} → ${l.holder}${l.worktreePath !== null ? ` (${l.worktreePath})` : ""}`).join("; ")}`);
+      lines.push(`leases: ${state.leases.length === 0 ? "none active" : joinCapped(state.leases, CATALOG_STATE_JOIN_LIMIT, "; ", (l) => `${l.planId} → ${l.holder}${l.worktreePath !== null ? ` (${l.worktreePath})` : ""}`)}`);
       if (state.knowledge !== null) {
         lines.push(`knowledge: ${state.knowledge.docCount} doc${state.knowledge.docCount === 1 ? "" : "s"} (${state.knowledge.categories.join(", ")})`);
       }
@@ -7206,112 +7213,111 @@ function unquote(value) {
   return value.length >= 2 && value.startsWith('"') && value.endsWith('"') ? value.slice(1, -1) : value;
 }
 
-// src/gates/fallbacks-probe.ts
-var FALLBACKS_ENTRY_NAME = "dsh-llm-fallbacks";
-function fallbacksService(ctx) {
-  return ctx.get("llm-fallbacks");
-}
-function fallbacksEntry(ctx) {
-  const loader = ctx.get("loader");
-  if (loader === undefined)
-    return;
-  for (const entry of loader.entries()) {
-    if (entry.options.name !== FALLBACKS_ENTRY_NAME)
-      continue;
-    if (entry.options.group)
-      continue;
-    if (entry.disabled)
-      continue;
-    return entry;
-  }
-  return;
-}
-function fallbacksMounted(ctx) {
-  if (fallbacksService(ctx) !== undefined)
-    return true;
-  const entry = fallbacksEntry(ctx);
-  if (entry === undefined)
-    return false;
-  return entry.fiber !== undefined;
-}
-
-// src/gates/fallbacks-decoration.ts
-var DECORATION_LOGGER = "mstar/subagent-decoration";
-var PERSONA_SECTION_NAME = "mstar:role-persona";
-var PERSONA_SECTION_ORDER = 1;
-var decorationLogSink = () => {};
-function setDecorationLogger(sink) {
-  const prior = decorationLogSink;
-  decorationLogSink = sink;
+// src/gates/role-persona.ts
+var ROLE_PERSONA_LOGGER = "mstar/role-persona";
+var SUBAGENTS_SERVICE = "subagents";
+var rolePersonaLogSink = () => {};
+function setRolePersonaLogger(sink) {
+  const prior = rolePersonaLogSink;
+  rolePersonaLogSink = sink;
   return prior;
 }
-var decorationAgentsDir;
+var rolePersonaAgentsDir;
 var mirrorAbsentDebugged = false;
-function setDecorationAgentsDir(dir) {
-  const prior = decorationAgentsDir;
-  decorationAgentsDir = dir;
+function setRolePersonaAgentsDir(dir) {
+  const prior = rolePersonaAgentsDir;
+  rolePersonaAgentsDir = dir;
   mirrorAbsentDebugged = false;
   return prior;
 }
-function seededTaskPrompt(child) {
-  for (const event of child.session.events) {
-    if (event.type !== "user/message")
-      continue;
-    const text = event.data.content.filter((block) => block.type === "text").map((block) => block.text).join(`
-`);
-    if (text.trim().length > 0)
-      return text;
-  }
-  return;
+var wrapperCache = new WeakMap;
+function registerRolePersonaChannel(ctx, config) {
+  const rolePersonas = config.rolePersonas;
+  ctx.on("internal/get", (_readCtx, name, _error, next) => {
+    const value = next();
+    if (name !== SUBAGENTS_SERVICE)
+      return value;
+    try {
+      return wrapSubagentsService(value, rolePersonas);
+    } catch (error) {
+      log2("warn", `role persona channel degraded to pass-through (subagent starts unaffected): ${errorMessage2(error)}`);
+      return value;
+    }
+  });
 }
-function decorateSubagentStart(ctx, config, info) {
-  try {
-    const personas = config.rolePersonas;
-    const agentsDir = decorationAgentsDir;
-    if ((personas == null || Object.keys(personas).length === 0) && agentsDir === undefined)
-      return;
-    const agents = ctx.get("agents");
-    if (agents === undefined) {
-      log2("debug", "agents service absent — mstar:role-persona decoration skipped (composition without dsh-agent)");
-      return;
+function wrapSubagentsService(value, rolePersonas) {
+  if (typeof value !== "object" || value === null)
+    return value;
+  const service = value;
+  if (typeof service.start !== "function" || typeof service.getProvider !== "function")
+    return value;
+  const cached = wrapperCache.get(value);
+  if (cached !== undefined && cached.rolePersonas === rolePersonas)
+    return cached.wrapper;
+  const wrapper = Object.create(value);
+  wrapper.start = (name, request) => {
+    let merged = request;
+    try {
+      merged = withRolePersona(service, name, request, rolePersonas, "one-shot");
+    } catch (error) {
+      log2("warn", `role persona merge degraded to pass-through (subagent start unaffected): ${errorMessage2(error)}`);
     }
-    const child = agents.get(info.id);
-    if (child === undefined)
-      return;
-    const taskPrompt = seededTaskPrompt(child);
-    if (taskPrompt === undefined)
-      return;
-    const executeAs = parseAssignmentFields(assignmentHeaderRegion(taskPrompt)).executeAs;
-    if (executeAs === undefined)
-      return;
-    const persona = personaFor(executeAs, { rolePersonas: config.rolePersonas, agentsDir }, (message) => log2("warn", message));
-    if (persona === undefined) {
-      if (agentsDir === undefined && !mirrorAbsentDebugged) {
-        mirrorAbsentDebugged = true;
-        log2("debug", "harness-agents mirror absent — mstar:role-persona skipped (config-only lookups; mirror defaults unavailable)");
+    return service.start(name, merged);
+  };
+  if (typeof service.startContinuable === "function") {
+    wrapper.startContinuable = (spec) => {
+      let merged = spec;
+      try {
+        const mergedRequest = withRolePersona(service, spec.provider, spec.request, rolePersonas, "continuable");
+        if (mergedRequest !== spec.request)
+          merged = { ...spec, request: mergedRequest };
+      } catch (error) {
+        log2("warn", `role persona merge degraded to pass-through (continuable subagent start unaffected): ${errorMessage2(error)}`);
       }
-      return;
-    }
-    child.ctx.systemPrompt.section({
-      name: PERSONA_SECTION_NAME,
-      order: PERSONA_SECTION_ORDER,
-      text: persona.text
-    });
-    if (fallbacksMounted(ctx)) {
-      log2("info", `dsh-llm-fallbacks mounted (v${fallbacksService(ctx)?.version ?? "unknown"}) — mstar:role-persona injected for role '${executeAs}'`);
-    } else {
-      log2("debug", `dsh-llm-fallbacks unmounted — mstar:role-persona injected from ${persona.source === "config" ? "mstar Config" : "harness-agents default"} for role '${executeAs}' (decoration channel unchanged)`);
-    }
-  } catch (error) {
-    log2("warn", `mstar:role-persona decoration aborted (degraded — subagent dispatch unaffected): ${errorMessage2(error)}`);
+      return service.startContinuable(merged);
+    };
   }
+  wrapperCache.set(value, { rolePersonas, wrapper });
+  return wrapper;
+}
+function withRolePersona(service, providerName, request, rolePersonas, surface) {
+  if (request.persona !== undefined)
+    return request;
+  const personas = rolePersonas;
+  const agentsDir = rolePersonaAgentsDir;
+  if ((personas == null || Object.keys(personas).length === 0) && agentsDir === undefined)
+    return request;
+  const taskPrompt = (request.prompt ?? []).filter((block) => block.type === "text").map((block) => block.text ?? "").join(`
+`);
+  if (taskPrompt.trim().length === 0)
+    return request;
+  const executeAs = parseAssignmentFields(assignmentHeaderRegion(taskPrompt)).executeAs;
+  if (executeAs === undefined)
+    return request;
+  const persona = personaFor(executeAs, { rolePersonas: personas, agentsDir }, (message) => log2("warn", message));
+  if (persona === undefined) {
+    if (agentsDir === undefined && !mirrorAbsentDebugged) {
+      mirrorAbsentDebugged = true;
+      log2("debug", "harness-agents mirror absent — role persona skipped (config-only lookups; mirror defaults unavailable)");
+    }
+    return request;
+  }
+  const provider = service.getProvider(providerName);
+  if (provider === undefined)
+    return request;
+  if (surface === "one-shot" ? provider.capabilities?.persona !== true : typeof provider.prepareContinuable !== "function") {
+    log2("debug", surface === "one-shot" ? `subagent provider '${providerName}' lacks the persona capability — role persona for '${executeAs}' skipped (start proceeds unchanged)` : `subagent provider '${providerName}' does not support continuable children — role persona for '${executeAs}' skipped (the native continuable start fails loud its own way)`);
+    return request;
+  }
+  log2("debug", `role persona delivered via the native subagent persona channel for role '${executeAs}' (${surface} start, source: ${persona.source === "config" ? "mstar Config" : "harness-agents default"})`);
+  return { ...request, persona: persona.text };
 }
 function errorMessage2(error) {
   return error instanceof Error ? error.message : String(error);
 }
 function log2(level, message) {
   try {
-    decorationLogSink(level, message);
+    rolePersonaLogSink(level, message);
   } catch {}
 }
 
@@ -7992,6 +7998,35 @@ ${mstarLoadLine(roleId)}` });
   return { declared, skipped, preserved, outcome };
 }
 
+// src/gates/fallbacks-probe.ts
+var FALLBACKS_ENTRY_NAME = "dsh-llm-fallbacks";
+function fallbacksService(ctx) {
+  return ctx.get("llm-fallbacks");
+}
+function fallbacksEntry(ctx) {
+  const loader = ctx.get("loader");
+  if (loader === undefined)
+    return;
+  for (const entry of loader.entries()) {
+    if (entry.options.name !== FALLBACKS_ENTRY_NAME)
+      continue;
+    if (entry.options.group)
+      continue;
+    if (entry.disabled)
+      continue;
+    return entry;
+  }
+  return;
+}
+function fallbacksMounted(ctx) {
+  if (fallbacksService(ctx) !== undefined)
+    return true;
+  const entry = fallbacksEntry(ctx);
+  if (entry === undefined)
+    return false;
+  return entry.fiber !== undefined;
+}
+
 // src/gates/fallbacks-advisory.ts
 var ADVISORY_LOGGER = "mstar/fallbacks-advisory";
 var advisoryLogSink = () => {};
@@ -8276,12 +8311,6 @@ function engineStatusProvider(ctx, resolver, bootHarnessDir) {
   };
 }
 var DIGEST_PLAN_CAP = 8;
-function joinCapped(items, cap, separator, render) {
-  const visible = items.slice(0, cap).map(render);
-  if (items.length > cap)
-    visible.push(`+${items.length - cap} more`);
-  return visible.join(separator);
-}
 function engineStatusSummary(source) {
   const lines = [`mstar engine status: v${source.version}`];
   const state = source.state;
@@ -8404,16 +8433,14 @@ function apply(ctx, config) {
     else
       logger.info(message);
   });
-  setDecorationLogger((level, message) => {
-    const logger = ctx.logger(DECORATION_LOGGER);
+  setRolePersonaLogger((level, message) => {
+    const logger = ctx.logger(ROLE_PERSONA_LOGGER);
     if (level === "debug")
       logger.debug(message);
-    else if (level === "info")
-      logger.info(message);
     else
       logger.warn(message);
   });
-  setDecorationAgentsDir(packagedAgentsDir());
+  setRolePersonaAgentsDir(packagedAgentsDir());
   setHarnessPromptLogger((level, message) => {
     const logger = ctx.logger(HARNESS_PROMPT_LOGGER);
     if (level === "debug")
@@ -8526,9 +8553,9 @@ function apply(ctx, config) {
     ctx.on("fs/write-intent", (target, actor, next) => seamWriteIntentListener(ctx, resolver, config, seam, target, actor, next), { prepend: true });
   }
   ctx.on("tools/pre-execute", (exec, next) => preExecuteListener(ctx, resolver, config, adapter, exec, next), { prepend: true });
-  ctx.events.on("subagent/start", (info) => {
+  registerRolePersonaChannel(ctx, config);
+  ctx.events.on("subagent/start", () => {
     runAdvisoryPass();
-    decorateSubagentStart(ctx, config, info);
   });
   const ttlMs = config.catalogTtlMs ?? DEFAULT_CATALOG_TTL_MS;
   const explicitKey = bootHarnessDir !== null ? EXPLICIT_CACHE_KEY : undefined;
@@ -8547,10 +8574,11 @@ function apply(ctx, config) {
 }
 export {
   skillLocalConfig,
-  setDecorationLogger,
-  setDecorationAgentsDir,
+  setRolePersonaLogger,
+  setRolePersonaAgentsDir,
   setAdvisoryLogger,
   runFallbacksAdvisory,
+  registerRolePersonaChannel,
   recordWorkflowVerdict,
   recordSettle,
   recordDispatch,
@@ -8564,17 +8592,14 @@ export {
   lintCompoundWrite,
   lintAuditWrite,
   inject,
-  decorateSubagentStart,
   apply,
   SkillLintVetoError,
   SeamVetoError,
   SETTLE_SEAM,
-  PERSONA_SECTION_ORDER,
-  PERSONA_SECTION_NAME,
+  ROLE_PERSONA_LOGGER,
   HarnessResolver,
   DshMstar,
   DshHostAdapter,
-  DECORATION_LOGGER,
   Config,
   AGENT_FLOW_MAX_EVENTS,
   AGENT_FLOW_FILE,

package/harness-skills/mstar-artifacts/references/status-and-residuals.md

@@ -43,29 +43,33 @@ Canonical vs legacy residual definitions → **`mstar-artifacts` SKILL.md**（"`
 ```json
 {
   "schema_version": 1,
-  "id": "<plan-id-or-iteration-id>",
-  "type": "plan | iteration",
-  "status": "running | paused | completed | failed | stopped",
-  "started_at": "YYYY-MM-DD",
-  "ended_at": null,
-  "updated_at": "YYYY-MM-DD",
+  "id": "iter-demo",
+  "type": "iteration",
+  "status": "running",
+  "started_at": "2026-08-30",
+  "updated_at": "2026-08-30",
   "phase": "phase-2-execute",
   "plans": [
     {
       "id": "plan-id",
       "title": "Plan title",
       "file": "{PLAN_DIR}/plan-id-feature-name.md",
-      "status": "Todo | InProgress | InReview | Blocked | Done",
+      "status": "InProgress",
       "owner": "@project-manager",
       "agents": ["@fullstack-dev"],
       "progress": 0,
       "tags": [],
-      "created_at": "YYYY-MM-DD",
-      "updated_at": "YYYY-MM-DD",
+      "created_at": "2026-08-29",
+      "updated_at": "2026-08-30",
       "done_at": null,
       "notes": [],
       "metadata": {},
-      "execution_lease": {}
+      "execution_lease": {
+        "holder": "omp:demo-session",
+        "claimed_at": "2026-08-30T02:30:00Z",
+        "worktree_path": "/tmp/worktrees/demo-plan",
+        "working_branch": "feature/demo-plan"
+      }
     }
   ],
   "execution_policy": {
@@ -73,14 +77,22 @@ Canonical vs legacy residual definitions → **`mstar-artifacts` SKILL.md**（"`
     "worktree_mode": "",
     "push_policy": ""
   },
-  "integration_merge_lease": {},
-  "branch": { "base": "", "integration": "", "target": "" },
+  "integration_merge_lease": {
+    "holder": "omp:demo-session",
+    "claimed_at": "2026-08-30T03:00:00Z",
+    "plan_id": "plan-id",
+    "source_branch": "feature/demo-plan",
+    "target_branch": "iteration/iter-demo"
+  },
+  "branch": { "base": "main", "integration": "iteration/iter-demo", "target": "main" },
   "control_worktree_path": "/abs/repo/root",
   "legacy_metadata": {},
-  "compass_ref": "iterations/<iteration-id>/delivery-compass.md"
+  "compass_ref": "iterations/iter-demo/delivery-compass.md"
 }
 ```
 
+- The example above depicts the **held** state (both leases populated, illustrative placeholder values) and passes `validateWorkflowSnapshot`; the released state is **key absence** (delete-key-on-release below), never `null` or `{}`, and enum scalars (`type` / `status` / plan-row `status`) are always single values — the full enum sets are `type`: `plan | iteration`, snapshot `status`: `running | paused | completed | failed | stopped`, plan-row `status`: `Todo | InProgress | InReview | Blocked | Done`.
+
 - `plans[]` rows are the **legacy PlanRow shape verbatim** (unknown row fields preserved, never re-bucketed). Per-row `execution_lease` stays on the row; `integration_merge_lease` is **top-level** (the v1 root-`metadata` home is gone).
 - Terminal statuses (`completed` / `failed` / `stopped`) require `ended_at` and no dangling leases.
 - `execution_policy` keys are copied from v1 root `metadata` at migrate; values are accepted-but-opaque this iteration (no semantic gate).

package/harness-skills/mstar-coding-behavior/SKILL.md

@@ -31,6 +31,8 @@ The failure mode: "correct" code that is alien to the codebase — works but loo
 
 ## 2) Simplicity First
 
+**Upstream invariants**: the global engineering rules live in `mstar-harness-core`（核心研发守则）——no backward-compat layers, simplest implementation, layered growth, modularity, dependency discipline, long-term architecture; this section is their implementation-level playbook.
+
 Implement the smallest durable slice that satisfies the request and acceptance criteria.
 
 **The Ladder.** A reflex hierarchy for every decision — stop at the first rung that holds:

package/harness-skills/mstar-harness-core/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mstar-harness-core
-description: Morning Star (启明星) harness **强制全局入口** —— 信息源优先级、最小交付循环、状态机与 Done 权限、Task category 路由（含 quick 禁豁免）、@explore 边界、长任务纪律、护栏不变量、反模式索引、Morning Star Skill 索引与宿主入口。**任何**非平凡任务开始前必须先 Read 本 skill；再按角色与任务 **按需** Read 其它 `mstar-*` 专题（勿默认通读全部）。`@project-manager` 开轮必读 + `mstar-dispatch-gates` / `mstar-phase-gates` / `mstar-conventions` 等；实现/审查/QA 必读本 skill + `mstar-coding-behavior` 及角色清单（见 `mstar-roles`）。Prepare/派发/Git/residual/QC 细则在专题 skill，不在此重复。
+description: Morning Star (启明星) harness **强制全局入口** —— 信息源优先级、最小交付循环、状态机与 Done 权限、Task category 路由（含 quick 禁豁免）、@explore 边界、长任务纪律、核心研发守则、护栏不变量、反模式索引、Morning Star Skill 索引与宿主入口。**任何**非平凡任务开始前必须先 Read 本 skill；再按角色与任务 **按需** Read 其它 `mstar-*` 专题（勿默认通读全部）。`@project-manager` 开轮必读 + `mstar-dispatch-gates` / `mstar-phase-gates` / `mstar-conventions` 等；实现/审查/QA 必读本 skill + `mstar-coding-behavior` 及角色清单（见 `mstar-roles`）。Prepare/派发/Git/residual/QC 细则在专题 skill，不在此重复。
 ---
 
 # Morning Star Harness Core（启明星核心）
@@ -121,6 +121,18 @@ Read **`mstar-host`** after this skill; detect host per its table, then Read the
 | Kimi | `Agent`/`AgentSwarm`（仅 `coder`/`explore`/`plan`）；角色绑定在 prompt（C5b）；Plan 双写 → `references/kimi.md` · `kimi-plan-mode-bridge.md` |
 | 其它 | 同 `mstar-host` skill；按工具信号选 reference |
 
+## 核心研发守则
+
+全局工程不变量，适用于所有角色；实现级操作细节（The Ladder、surgical、debugging 等）→ **`mstar-coding-behavior`**。
+
+- Do not preserve backward compatibility. Remove obsolete paths instead of adding compatibility layers, fallbacks, or migrations.
+- Choose the simplest implementation that fully meets the current requirements. Avoid speculative abstractions, configuration, and indirection.
+- Grow the system in layers. Start from the smallest version that works end to end, and add each new capability on top of a product that already works. Never trade a working product for unfinished complexity.
+- Keep components modular and concerns clearly separated.
+- Prefer established, well-maintained libraries when they reduce overall complexity or improve reliability. Do not reimplement common functionality without a clear reason.
+- Lean on the dependencies already in the project before writing your own implementation or adding packages. Do not assume a library lacks a capability without checking its documentation and types.
+- Make architectural decisions for the long term. Do not accept a stopgap that only works for now and is meant to be replaced later.
+
 ## 护栏（不变量）
 
 - 未经用户同意不改宿主配置文件与用户凭据。

package/harness-skills/mstar-iteration/SKILL.md

@@ -45,7 +45,7 @@ Phase 5: PR merge-ready loop —— 至 mergeable + CI 全绿 + reviews resolved
 | **→ 迭代交付完成** | §5.5 exit checklist 全 `[x]` | PR mergeable；required CI 全绿；reviews resolved | Phase 4 开 PR 即宣称完成 |
 | **start → integration branch** | §1.6 Review & Edit chain | 三角色按序 invoke；**specs** 为主产出；**禁止** start 链向 `{KNOWLEDGE_DIR}/` 新增；writing-specialist corpus hygiene + compass `status: locked` | PM 代做专业编辑；并行三角色；product/architect 写 knowledge；临时笔记进 specs |
 
-> **Engine check (when available):** run `mstar iteration gate --workflow <id> --compass <delivery-compass.md>` (or `import { evaluatePhaseGate } from "@mstar-harness/engine"` in a host hook) to evaluate the transition gate above against the workflow snapshot. On `fail` (gate-blocking violations) -> do not proceed; fix and re-run. Note: during the Phase-3 window (`transition: phase-3-close`) the gate exits 1 until the §3.4 close items (`status: completed` + `end_date`) are written — that exit-1 is the expected "close work pending" signal (the exit checklist gates Phase 4, not the Phase-3 entry), so proceed with Phase 3 per the table below. Skill text below remains authoritative when the runtime is absent.
+> **Engine check (when available):** run `mstar iteration gate --workflow <id> --compass <delivery-compass.md> --branch "$(git branch --show-current)" --integration <spec_integration_branch> --target <target_branch>` (or `import { evaluatePhaseGate } from "@mstar-harness/engine"` with the `currentBranch` / `specIntegrationBranch` / `prBaseBranch` probe inputs in a host hook) to evaluate the transition gate above against the workflow snapshot — the branch probes cover §3.5 exit item 5 (`EXIT_BRANCH_MISMATCH` when the commit checkout is not on `spec_integration_branch`; verify **before** the §3.5 close commit, not after). On `fail` (gate-blocking violations) -> do not proceed; fix and re-run. Note: during the Phase-3 window (`transition: phase-3-close`) the gate exits 1 until the §3.4 close items (`status: completed` + `end_date`) are written — that exit-1 is the expected "close work pending" signal (the exit checklist gates Phase 4, not the Phase-3 entry), so proceed with Phase 3 per the table below. Skill text below remains authoritative when the runtime is absent.
 
 **误判信号**：对话里出现 compound 摘要、roadmap 更新、或「所有 plan 已完成」但 **未** 打印 §3.1 / §3.5 checklist → 视为 **Phase 3 未执行**，回到 §3.0。
 

package/harness-skills/mstar-iteration/references/phase-3-iteration-close.md

@@ -80,14 +80,24 @@ PM 打印 **iteration-close exit checklist**；全部为 `[x]` 后方可 `git co
 - [ ] 当前分支是 `spec_integration_branch`
 - [ ] PR base = snapshot `branch.target`（`target_branch`，与 compass frontmatter 一致）；**不是**未记录的 `main`
 
-**Commit 到 integration 分支**：
+**Commit 前提（HARD — branch-anchored，防递交到控制分支）**：§3.5 的 commit 是 **branch 锚定**的——`git commit` 落在**当前检出分支**，`<spec_integration_branch>` 只出现在 push 参数里。当控制 worktree（或任一检出）不在 integration 分支时，未经下述核对直接执行本配方，compound 会把 tracked 的 `{KNOWLEDGE_DIR}/`、`{SPECS_DIR}/`、`CONCEPTS.md` 递交到控制分支（如 `main`），integration 分支的 PR 永远带不上这些 shared 产物。因此 **任何 `git add` 之前**必须先验分支；mismatch → **STOP**（不得 commit、不得 push、不得「先提交后挪」），改在正确检出上重做（见下）。
+
+1. 解析 `<spec_integration_branch>`：snapshot `branch.integration`（workflows/<id>/snapshot.json）→ 缺失时 compass frontmatter `spec_integration_branch`；仍缺 → STOP 补齐，不得默认 `main`。
+2. **先验后提交**（在执行 commit 的检出处）：`git branch --show-current` === `<spec_integration_branch>`。§3.2–§3.4 产生的 tracked close 产物本就应处于未提交状态等待本 commit，**不要求**此处工作树干净。engine 可用 → 在 add/commit **前**运行 `mstar iteration gate --workflow <id> --compass <delivery-compass.md> --branch <current> --integration <spec_integration_branch> --target <target_branch>` 并确认 exit 无 `EXIT_BRANCH_MISMATCH` / `EXIT_PR_BASE_MISMATCH`（Phase-3 窗口预期的其它 exit-1 除外，见 Phase transition gates 注）。
+3. **mismatch 时**：不产生任何提交。tracked 子树（`{KNOWLEDGE_DIR}/`、`{SPECS_DIR}/`、`CONCEPTS.md`、迭代 package 中 tracked 部分）在**检出 `<spec_integration_branch>` 的 worktree** 重新写入或在 commit 前恢复（它们默认 tracked、随 Git 分支走；进程产物 plans/iterations/status/sdd 经 control 绝对路径不受影响）。然后重跑本 checklist。
+
+**在 `<spec_integration_branch>` 检出上执行**：
 
 ```bash
-git add {ITERATION_DIR}/<id>/ {ITERATION_DIR}/README.md {KNOWLEDGE_DIR}/ CONCEPTS.md
+git branch --show-current   # must print <spec_integration_branch> — mismatch → STOP, see above
+git add {ITERATION_DIR}/<id>/ {ITERATION_DIR}/README.md {KNOWLEDGE_DIR}/ {SPECS_DIR}/ CONCEPTS.md
+git add STRATEGY.md   # only if updated in §3.3 (tracked root file); skip line otherwise
 git commit -m "chore(iteration): close <iteration-id> — compound round, roadmap update"
 git push origin <spec_integration_branch>
 ```
 
+Staging 说明：`{SPECS_DIR}` 为解析后的实际 specs 目录（候选链见 `mstar-conventions`，如 `{HARNESS_DIR}/specs/`、`docs/specs/`、`specs/`）；本轮更新过才加入。§3.3 更新过的 tracked 项目层 roadmap tracker 若为 tracked 文件，一并 stage（gitignored 的 process 产物不进 commit）。
+
 PR 目标使用 snapshot `branch.target`；缺失时停止并补齐，不得默认 `main`。
 
 ## 3.6 可选：触发 compound-refresh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mstar-harness/dsh",
-  "version": "3.5.1",
+  "version": "3.6.0-alpha.2",
   "description": "Morning Star harness dsh (DeepSeek Harness) cordis function plugin — in-process engine gates (status/dispatch/lease) with hard refusal channels.",
   "keywords": [
     "dsh",
@@ -44,7 +44,7 @@
     },
     "client": {
       "inject": [
-        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-store",
         "@deepseek-ai/dsh-client-ui-conversation",
         "@deepseek-ai/dsh-client-locale"
       ],
@@ -56,31 +56,30 @@
     "test": "bun test",
     "typecheck:tests": "bunx tsc --noEmit -p tests/tsconfig.json",
     "bundle-assets": "bun run scripts/bundle-harness-assets.ts",
-    "build": "bun run bundle-assets && rm -rf dist && bun build src/index.ts src/invariant.ts --target node --outdir dist --external @deepseek-ai/cordis --external @deepseek-ai/dsh-skill-filesystem --external @deepseek-ai/dsh-tools --external @deepseek-ai/dsh-llm --external dsh-llm-fallbacks && bun run build-client && bunx tsc",
+    "build": "bun run bundle-assets && rm -rf dist && bun build src/index.ts src/invariant.ts --target node --outdir dist --external @deepseek-ai/cordis --external @deepseek-ai/dsh-skill-filesystem --external @deepseek-ai/dsh-tools --external @deepseek-ai/dsh-llm && bun run build-client && bunx tsc",
     "build-client": "bun run scripts/build-client-bundle.ts",
     "prepublishOnly": "bun run build"
   },
   "engines": {
     "bun": ">=1.2.17"
   },
-  "dependencies": {
-    "dsh-llm-fallbacks": "^0.3.0"
-  },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-agent": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-client-locale": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-client-runtime": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-commands": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-fs": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-jobs": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-llm": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-skill": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-skill-filesystem": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-tools": "^0.1.1-rc.2"
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-agent": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-client-locale": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-client-store": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-client-ui-chat": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-commands": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-fs": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-jobs": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-llm": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-skill": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-skill-filesystem": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-tools": "^0.1.2-alpha.2"
   },
   "publishConfig": {
     "access": "public"
@@ -91,6 +90,7 @@
     "@types/react": "~18.3.1",
     "js-yaml": "^4.1.0",
     "bun-types": "^1.2.17",
+    "dsh-llm-fallbacks": "^0.4.0-alpha.1",
     "schemastery": "^3.18.0",
     "typescript": "^5.9.3",
     "vitest": "^4.1.8",