@mstar-harness/dsh 2.3.0 → 2.4.1

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # Blob hashes (git hash-object) of each side as of the last confirmation that
 # both languages say the same thing (dsh i18n contract: a pair is three
 # sibling files; editing either side obligates re-confirming and re-recording).
-README.md: ebaf2a22fa9965e40e006ff311fafdc3971c6376
-README.zh.md: a520154b43d50ef20c2fcf300af74571ff1b0f85
+README.md: d942e880bbc5c8dc34940251df7666cf81345042
+README.zh.md: 7a3e913084e5d79271828b5f3f5f27e41aca85fe

package/README.md

@@ -12,6 +12,8 @@ How a dsh app consumes the plugin — install paths, configuration, what mounts
 
 The package ships as a workspace package (`workspaces: ["packages/*"]`) with the engine bundled into `dist/` at build time (`bun run build`; dist is gitignored). The install path is the **profile bundle**, added to the shipped `web` profile (`dsh --profile web` — the ready-made web app profile, `dsh web`), through the `dsh.bundle.patch` manifest — a patch layer mounted over the dsh-base defaults:
 
+**One-command CLI entry (recommended)** — `npx @mstar-harness/cli init --target dsh` installs the full capability in one go: it runs the two `dsh plugin --profile web add` installs below in order (the mstar bundle first, then `dsh-llm-fallbacks`), and `npx @mstar-harness/cli doctor --target dsh` reports each plugin row as `uninstalled` / `disabled` / `mounted`. It is the same two-command install, orchestrated; `--no-fallbacks` skips the second row (and with it the seeded roles — see What you get below).
+
 **(a) Registry install (published form)** — the npm package carries the built `dist/` (no build step on install):
 
 ```sh
@@ -35,6 +37,10 @@ dsh plugin --profile web add dsh-llm-fallbacks
 
 The **two-command install is the contract** — folding a `dsh-llm-fallbacks` row into this bundle's patch is explicitly rejected (roadmap §8.3 F4): the loader has no insert-if-absent semantics, so a same-`id` insert is a `duplicate loader entry id` boot failure (the whole dsh session fails to start), and a different-`id` insert mounts the plugin twice — two `apply()` runs with split fallback state (per-context state stores, double listeners, config-override lottery) for anyone who also installs the package directly. Layer order is the reconcile append order: `dsh-llm-fallbacks` lands **after `dsh-base`/`llm-retry`** (its hard ordering requirement) and after the mstar row. Single-command multi-activation is an upstream feature gap (reconcile dedup or insert-if-absent patch semantics), not actionable from this repo.
 
+**What you get with zero configuration** — with BOTH rows installed (via the CLI entry or the two commands above), the mstar plugin declares the 13 `mode: subagent` mstar role seeds (derived from the bundled `harness-agents/` mirror, `project-manager` excluded) into the fallbacks taxonomy at boot: each seeded role's persona defaults to its mirror `description` plus the mandatory role-loading guidance line, the seeded state stays revertible (the `fallbacks/revert-seed` gateway / the settings rollback button), and the runtime advisory reports missing ids and persona overrides. The seeds mechanism is B4 (delivered iter-20260816-dsh-seeds-bridges) — the installed-deployment e2e (`tests/install-e2e.spec.ts`) closes the verification loop: a real `init --target dsh` install into a temp `DSH_HOME`, booted from the installed artifacts, asserts all 13 ids present in the effective taxonomy with non-empty personas. Not included: model routing, automatch dispatch, or the dsh TUI.
+
+> **Fresh-publish age window**: pnpm's `minimumReleaseAge` gate can make a `dsh plugin add <spec>` range resolution pick an older published version (without the seeds surface) for up to ~24h after a fresh publish — re-run `npx @mstar-harness/cli init --target dsh` after the window (or pin the version) to converge on the latest surface.
+
 ### Configuration
 
 | Key | Type | Default | Meaning |

package/README.zh.md

@@ -12,6 +12,8 @@ dsh 应用如何使用本插件——安装路径、配置、挂载时发生什
 
 本包以 workspace 包形式发布（`workspaces: ["packages/*"]`），构建时把 engine 打进 `dist/`（`bun run build`；dist 已被 gitignore）。安装途径是 **profile bundle**，装进现成的 `web` profile（`dsh --profile web`——开箱即用的 web 应用 profile，即 `dsh web`），经 `dsh.bundle.patch` 清单——一个叠在 dsh-base 默认层之上的补丁层：
 
+**一条命令的 CLI 入口（推荐）**——`npx @mstar-harness/cli init --target dsh` 一次性装齐全量能力：它按序运行下面两条 `dsh plugin --profile web add` 安装（先 mstar bundle，再 `dsh-llm-fallbacks`），并可用 `npx @mstar-harness/cli doctor --target dsh` 逐行报告 `uninstalled` / `disabled` / `mounted`。它编排的仍是同一条双命令安装；`--no-fallbacks` 跳过第二行（连带跳过 seeded 角色——见下文「零配置获得什么」）。
+
 **（a）registry 安装（发布形态）**——npm 包自带构建好的 `dist/`（安装时无需构建）：
 
 ```sh
@@ -35,6 +37,10 @@ dsh plugin --profile web add dsh-llm-fallbacks
 
 **双命令安装即契约**——把 `dsh-llm-fallbacks` 行折叠进本 bundle 的补丁**明确否决**（roadmap §8.3 F4）：loader 没有 insert-if-absent 语义，因此同 `id` 插入是 `duplicate loader entry id` 启动失败（整个 dsh 会话无法启动）；异 `id` 插入则插件被挂载两次——对同时直接安装该包的人，会出现两次 `apply()` 与分裂的 fallback 状态（各自独立的 state store、双份监听器、配置覆盖抽签）。层序为 reconcile 追加序：`dsh-llm-fallbacks` 落在 **`dsh-base`/`llm-retry` 之后**（其硬性排序要求）并位于 mstar 行之后。单命令多激活是上游功能缺口（reconcile 去重或 insert-if-absent 补丁语义），本仓库无法实施。
 
+**零配置获得什么**——两条行都装上后（经 CLI 入口或上面两条命令），mstar 插件在 boot 时把 13 个 `mode: subagent` 的 mstar 角色种子（从打包的 `harness-agents/` 镜像派生，排除 `project-manager`）声明进 fallbacks taxonomy：每个 seeded 角色的 persona 默认取其镜像 `description` 外加一行强制角色加载引导；seeded 状态保持可 revert（`fallbacks/revert-seed` 网关 / settings 回滚按钮）；运行时 advisory 报告缺失 id 与 persona 覆盖。该 seeds 机制即 B4（iter-20260816-dsh-seeds-bridges 已交付）——installed-deployment e2e（`tests/install-e2e.spec.ts`）本轮把验证闭环：真实 `init --target dsh` 安装进临时 `DSH_HOME`、从安装产物 boot，断言 13 个 id 全部出现在 effective taxonomy 且 persona 非空。不含模型路由、不含 automatch 派发、不含 dsh-tui。
+
+> **fresh publish 年龄窗口提示**：pnpm 的 `minimumReleaseAge` 门禁可能让 `dsh plugin add <spec>` 的 range 解析在全新发布后约 24h 内选中旧版本（不含 seeds surface）——窗口过后重跑 `npx @mstar-harness/cli init --target dsh`（或显式 pin 版本）即可收敛到最新 surface。
+
 ### Configuration
 
 | Key | Type | Default | Meaning |

package/dist/index.js

@@ -3604,12 +3604,44 @@ var FIVE_QUESTION_SECTIONS = [
   { key: "references", label: "References", question: "additional resources to open when the main path is not enough" }
 ];
 var HEADING_RE = /^#{1,6}\s+[^\r\n]+$/;
-function lintFiveQuestion(bodyText) {
-  const headings = bodyText.split(/\r?\n/).filter((line) => HEADING_RE.test(line)).map((line) => line.replace(/^#{1,6}\s+/, "").trim().toLowerCase());
+function collectHeadings(bodyText) {
+  const headings = [];
+  let inFence = false;
+  for (const line of bodyText.split(/\r?\n/)) {
+    if (line.startsWith("```") || line.startsWith("~~~")) {
+      inFence = !inFence;
+      continue;
+    }
+    if (!inFence && HEADING_RE.test(line)) {
+      headings.push(line.replace(/^#{1,6}\s+/, "").trim().toLowerCase());
+    }
+  }
+  return headings;
+}
+var RUNTIME_HEADING_ALIASES = {
+  workflow: ["process", "playbook"],
+  "decision-rules": [
+    "hard rules",
+    "core rules",
+    "rule",
+    "gate",
+    "not to do",
+    "red flags",
+    "反模式",
+    "红线",
+    "规则",
+    "门禁"
+  ],
+  evidence: ["output format", "证据"],
+  references: ["dependencies", "关系"]
+};
+function lintFiveQuestion(bodyText, mode = "authoring") {
+  const headings = collectHeadings(bodyText);
   const violations = [];
   for (const section of FIVE_QUESTION_SECTIONS) {
     const label = section.label.toLowerCase();
-    const covered = headings.some((heading) => heading.includes(label));
+    const aliases = mode === "runtime" ? RUNTIME_HEADING_ALIASES[section.key] ?? [] : [];
+    const covered = headings.some((heading) => heading.includes(label) || aliases.some((alias) => heading.includes(alias)));
     if (!covered) {
       violations.push(violation11("low", `skill-authoring.five-question.${section.key}`, `body does not answer "${section.question}" — no "${section.label}" section (mstar-skill-authoring § Body 必须回答的 5 问 / § 默认 Body 结构)`, `add a "## ${section.label}" section covering ${section.question}`));
     }

package/harness-commands/iteration-drive.md

@@ -32,7 +32,7 @@ Execute **`mstar-iteration` §2.6**（Continuous execution SSOT：自 Phase 2
 | 禁止（PM 线程） | 必须 |
 |-----------------|------|
 | Write/Edit/Shell 产品代码、写测试、跑 QC 审查（Phase 2） | 每条 implement/QC/QA Assignment ⇒ **1 次 `Task`** |
-| **多 task plan 用 inline 大包派发**（整份 plan / T1–Tn 贴进一个 dev Assignment） | **SDD**：`mstar-sdd` per-task 循环 — `mstar sdd task-brief` → implementer → `mstar sdd review-package` → task reviewer → `progress.md` |
+| **多 task plan 用 inline 大包派发**（整份 plan / T1–Tn 贴进一个 dev Assignment） | **SDD**：`mstar-sdd` per-task 循环 — `mstar-harness sdd task-brief` → implementer → `mstar-harness sdd review-package` → task reviewer → `progress.md` |
 | 只写 Assignment 就进入下一 gate | 同轮 dispatch：`Subagent invokes issued: N`（N = Assignment 条数） |
 | 最后一个 plan `Done` 后直接开 PR / 汇报结束 | **Phase 3 → 4 → 5** 顺序执行 |
 | Phase 4 开 PR 后停止 | Phase 5 loop 至 merge-ready；**禁止**未过 §5.5 就结束会话 |

package/harness-skills/mstar-branch-worktree/SKILL.md

@@ -178,7 +178,7 @@ Default process artifacts (`plans/`, `iterations/`, `status.json`, `sdd/`, `note
 
 ## QC / QA 检出对齐与多 worktree 门禁衔接（强制；避免误派）
 
-### 对齐字段契约（canonical）
+### 对齐字段契约（canonical · Evidence）
 
 分派 **QC 三审** 与对齐的 **QA 验证** 时，PM **必须**在 Assignment 写明与待审实现一致的 **`Review cwd` / `Worktree path`**、**`Working branch`**、**`plan_id`**、**`Review range` / `Diff basis`**。开发在 **feature 分支**（往往在独立 worktree 中）完成后，QC/QA 针对的都是这份 feature，不是 `main` 或任意未对齐默认 cwd。
 
@@ -189,7 +189,7 @@ Default process artifacts (`plans/`, `iterations/`, `status.json`, `sdd/`, `note
 - **逐字对齐（强制）**：三份 QC Assignment 与 QA Assignment 间 **`plan_id`** 与 **`Review range` / `Diff basis`**（连同 `Review cwd` / `Working branch`）**必须完全相同**；**`qa-engineer`** 验证同一 feature 时**复用同一组字段**。**热修 / QC 单审**路径也须含**同一组字段**，仅承接方份数为 1。
 - 三审并行时三名 reviewer **共用同一组**字段（对业务仓**只读 diff 审查**）；一般不必为每位 reviewer 各开 worktree，除非宿主/环境要求进程级隔离。
 
-> **Engine check (when available):** import `assertQcAlignment` / `singleReviewSnapshot` from `@mstar-harness/engine` in a host hook to assert the QC/QA alignment fields above (byte-identical `plan_id` + `Review range` / `Diff basis` across tri + QA; single review snapshot before dispatch). On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
+> **Engine check (when available):** run `mstar worktree qc-alignment <assignment-file>...`（或 import `assertQcAlignment` / `singleReviewSnapshot` from `@mstar-harness/engine` in a host hook）以断言上述 QC/QA 对齐字段（tri + QA 间 `plan_id` 与 `Review range` / `Diff basis` 逐字相同；派发前 single review snapshot）。On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
 
 ### 多 worktree 并行 → 单一待审快照（派 QC 前置）
 
@@ -224,3 +224,13 @@ Default process artifacts (`plans/`, `iterations/`, `status.json`, `sdd/`, `note
 - Rewrite 推送后：重新 fetch heads；rewrite 前的 review threads / approvals / check 结果**不再是当前证据** — merge 结论前须重审（commit hash 与 inline-comment anchor 已失效）。
 - 证据最窄原则（audit / QA Assignment 场景）：选择会在目标回归上失败的**最窄**检查；不因「push 在即」重跑已通过的检查。
 - 本节只管 rewrite / lease / 证据失效面；CI / review 波次 push 门禁（时序）SSOT → `mstar-iteration` §5.1a。
+
+## Workflow
+
+主链：**PM 唯一分支决策**（`Working branch` / `Branch policy`，写进 Assignment）→ 实现者在 feature worktree 写产品编辑（L1：control worktree 管 harness SSOT、feature 管源码）→ **QC 前**全部待审提交归并到**单一 `Working branch` `HEAD`** → 派 QC 三审 / QA 时共用**同一套对齐字段**（`Review cwd` / `Working branch` / `plan_id` / `Review range` / `Diff basis`，逐字相同）→ 集成分支 merge 串行（`integration_merge_lease`）。并发写流在派发**前**完成 worktree 隔离（L1 跨 plan / L2 同 plan）。
+
+## References
+
+- 派发与反递归红线 → **`mstar-dispatch-gates`**
+- SDD implement 波次（file handoff / reviewer）→ **`mstar-sdd`**
+- 迭代 Phase 2 control worktree + lease 细则 → **`mstar-iteration`** §2（`references/phase-2-worktree-lease.md`）

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

@@ -150,3 +150,16 @@ Do not perform agreement. State the technical action, the verification result, o
 - Keep these principles centralized here.
 - Role prompts should reference this skill instead of duplicating long prose.
 - Only role-specific triggers, boundaries, and artifacts belong in role prompt files.
+
+## Workflow
+
+Apply the seven sections in reading order: **1) Think Before Coding**（读懂再改）→ **2) Simplicity First**（最小耐久切片）→ **3) Surgical Changes**（可追溯改动 / 根因修复）→ **4) Debugging**（先复现、一步一测）→ **5) Goal-Driven Execution**（Step → verify）→ **6) Review Feedback Handling**（先核实再改、证据反驳）→ **7) Communication**（说明做了什么与为什么）。
+
+## Evidence
+
+正确结果 = 可运行检查通过并附输出：非平凡逻辑留下一个**最小可失败检查**（§5）；bug 修复先写复现测试、红转绿（§4）；回报引用检查结果与输出，而非「我觉得应该没问题」。
+
+## References
+
+- 角色正文与加载矩阵 → **`mstar-roles`**
+- 阶段门禁 / 意图门禁 / 可验证编辑 → **`mstar-phase-gates`**

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

@@ -103,3 +103,7 @@ In Cursor, Full mode dispatches subagents via Task tool. PM selects mode.
 - Do not edit AGENTS.md without user consent
 - Do not create CONCEPTS.md entries for general programming vocabulary
 - Do not modify product code — this skill writes documentation only
+
+## Evidence
+
+正确结果 = 一篇**可发现**的结晶文档：`{KNOWLEDGE_DIR}/<category>/<slug>.md` 通过 `references/schema.yaml` frontmatter 校验（Phase 3 Write）+ `{KNOWLEDGE_DIR}/README.md` 索引行（Phase 6 Indexes，iteration-close 强制）+ 达标领域词入 `CONCEPTS.md`（Phase 5）+ 源文件 / package README 标注 `Promoted to: <knowledge-path>`（Phase 4 Trace）。

package/harness-skills/mstar-compound-refresh/SKILL.md

@@ -143,3 +143,12 @@ Read that file from the mstar-compound skill directory before Phase 6.
 - Do not ask PM about mechanical updates (path fixes, renamed modules)
 - Do not change code to match outdated docs — update docs to match code
 - Do not run without PM approval for destructive actions (Delete, Replace)
+
+## Evidence
+
+正确结果 = 每篇候选文档有明确 verdict（Keep / Update / Consolidate / Replace / Delete）并落到产物：文档改动 + `{KNOWLEDGE_DIR}/README.md` 索引更新（Phase 4）+ `status.json` 引用同步 + 维护报告（Phase 5：reviewed / kept / updated / consolidated / replaced / deleted / flagged）+ `CONCEPTS.md` 对账（Phase 6）。
+
+## References
+
+- 捕获侧规则与 CONCEPTS.md vocabulary 规则 → **`mstar-compound`**（Phase 6 前读 `references/concepts-vocabulary.md`）
+- 路径符号与产物存储 SSOT → **`mstar-plan-conventions`**（`references/artifact-storage-paths.md`）

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

@@ -60,7 +60,7 @@ DESIGN.md is a **Prepare-stage artifact** (like spec). It must be created and re
 
 For **hotfix** or plans with no UI changes, DESIGN.md check may be skipped.
 
-## Completeness levels
+## Completeness levels（Evidence）
 
 DESIGN.md supports three levels, each with built-in upgrade path:
 

package/harness-skills/mstar-dispatch-gates/SKILL.md

@@ -49,7 +49,7 @@ description: Morning Star 派发与委派门禁 —— 仅 PM 可增派 subagent
 - 承接方若判断必须增加 subagent，应先回报 **`Blocked`** 请 PM 重分派。
 - Per-task informal review, when PM explicitly allows it, must not use `qc-specialist*`; use `code-reviewer` (generic fallback only when the role agent is absent on the host) or PM-marked informal `qa-engineer`. Formal QC remains `mstar-review-qc`.
 
-## 并发分派完整性门禁（PM 强制）
+## 并发分派完整性门禁（PM 强制 · Evidence）
 
 当 PM 声明「并发分派」时，须同时满足**文案并发**与**工具并发**：
 
@@ -123,6 +123,10 @@ When **`Execution mode: sdd`** (`mstar-sdd`):
 - Assignment 已写、invoke 为零（paste-only）却进入下一 gate。
 - Task/subagent item 漏写角色绑定字段（omp 漏 `agent` / Cursor 漏 `subagent_type` / OpenCode 漏 `subagent`）⇒ **静默回退 generic worker**，却因 count=N 通过而误判「派发完成」；属 paste-only 同级的 **dispatch-incomplete**。N=1 顺序 Review-&-Edit 链最易在此漏字段。
 
+## Workflow
+
+派发检查顺序：承接方先读 Assignment 顶部 **IDENTITY / 反模式块**确认 leaf 身份（反递归红线）→ PM 核对字段契约（`Execute as` / `Delegation` / 角色绑定字段；**先自检字段再发送**）→ 同一条消息**一次性发满 N 次** invoke（工具并发；N 按 `Execution mode` 映射）→ 派发前完成同仓写隔离（L1/L2 worktree）→ SDD 波次**串行** implement + fresh reviewer → task 全完成后 `{SDD_DIR}/review/` review-package → **强制 tri-review N=3**（或 inline 单席 N=1）。准备用 read/bash 不计入 N，且与派发回合分离（**未齐不发**）。
+
 ## References
 
 - `references/leaf-executor-checklist.md` — 承接方一页自检清单。

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

@@ -7,6 +7,10 @@ description: Morning Star host adapter (OpenCode, Cursor, Codex, Kimi, ZCode, om
 
 Host-specific **capabilities and entry behavior** for Morning Star. Process gates and invariants stay in `mstar-harness-core` and topic `mstar-*` skills.
 
+## Load order
+
+**本 skill 总是在 `mstar-harness-core` 之后加载**（先 Read `mstar-harness-core` SKILL.md；宿主注入项目 `AGENTS.md` 也不跳过，见下 `## First action`）。本 skill 只适配宿主入口 / 检测 / 计划 UX；状态机与门禁以 `mstar-harness-core` 为准。
+
 ## First action
 
 Read **`mstar-harness-core`** before this skill (even when the host injects project `AGENTS.md`).
@@ -68,11 +72,25 @@ Docs name assets as skill **`<name>`** → `scripts/…` / `references/…`. **R
 
 Authoring convention: **`mstar-skill-authoring`** § Skill-relative script and asset paths. Per-host URI / mount detail: `references/<host>.md`.
 
-> **Engine check (when available):** import `resolveSkillRoot` from `@mstar-harness/engine` in a host hook to resolve the loaded skill root per the table above (no CLI form yet). On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
+> **Engine check (when available):** run `mstar host skill-root --host <id> --skill <name>` (or import `resolveSkillRoot` from `@mstar-harness/engine` in a host hook) to resolve the loaded skill root per the table above. On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
 
-## Conflict order
+## Conflict order（Decision Rules）
 
 1. User explicit instructions (this turn)
 2. Project `AGENTS.md` / `CLAUDE.md`
 3. `mstar-harness-core` and related `mstar-*` skills
 4. This `mstar-host` skill and `references/*`
+
+## Workflow
+
+按 `## Default path` 执行：Read `mstar-harness-core` → 读本 skill 并按 `## Detect active host` 检测宿主（`cursor` → `opencode` → `omp` → `dsh` → `kimi` → `zcode` → `codex`）→ 读 `references/<host>.md`（计划模式另读对应 plan-mode bridge）→ 经 `mstar-roles` 加载角色 → 执行并以证据收尾。topic skill 按需加载，不默认通读。
+
+## Evidence
+
+正确结果 = 检测输出：`mstar host detect --signals <comma-list>` 打印 `host: <id>`（或 `ambiguous` → 按检测表 + 判断降级）；已加载的是**对应当前宿主工具形状**的 `references/<host>.md`。计划模式按宿主 plan-mode bridge 完成双写 / 对齐。
+
+## References
+
+- 各宿主适配细则 → `references/<host>.md`（cursor / opencode / omp / dsh / kimi / zcode / codex；计划模式另见 plan-mode bridge references）
+- invoke-capable 宿主并行派发 → `references/parallel-dispatch.md`
+- 角色加载与参数 → **`mstar-roles`**

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

@@ -226,7 +226,7 @@ Phase 1 与 §1.6 须遵守 **`references/iteration-artifact-boundaries.md`**（
 4. **Branch metadata gate**：root `metadata.iteration_base_branch`、`metadata.target_branch` 已登记，且至少一条 active plan 有 `metadata.spec_integration_branch`（或可从 compass 同轮 backfill）。**缺失 → STOP**，不得用 `main`/`master` 补位。
 5. **Control-worktree + lease defaults**（iteration 命令；可被 `Worktree mode: waived` 豁免）：除非本轮 Assignment 显式 `Worktree mode: waived`（或等价用户指令），Phase 2 **必须**在入口建立 control worktree、经 control 路径读写默认 gitignored 的 harness 进程产物（`status.json`、`{PLAN_DIR}`、`{ITERATION_DIR}`、`{SDD_DIR}` 等），并在可写派发前 claim `plans[].execution_lease` / `integration_merge_lease`。可写 Assignment 须含绝对 feature **`Worktree path`** + 绝对 control 系 **`Plan Path`** / **`SDD dir`**（见 **`mstar-branch-worktree`**「Harness path SSOT under default gitignore」）。**禁止**因 feature worktree 在默认 gitignore 下看不到 plans 而推断 `Worktree mode: waived`。`Plan parallelism: serial` **不** waive 本闸——仅强制跨 plan **implement** 串行调度；control worktree + lease 仍须满足。**跨 plan 并行安全闸**（**不可**被 `Worktree mode: waived` 豁免）：跨 plan **并行可写 implement** 须满足下列之一——(a) coordination 路径（control 或 waived 时主 checkout `{HARNESS_DIR}/status.json`）上 **same-host 独占写锁可用且每次 status/协调变更持锁**；(b) 默认 **`Plan parallelism: serial`**（**waived 时尤其优先默认串行**；**无 flock / 无共享锁时只触发本条，不豁免 worktree**）；(c) 用户本轮显式 `Cross-host lease race: accepted`（或等价）+ `plans[].notes` 审计。**禁止**将 `Worktree mode: waived` 当作跨主机无锁并行的授权。细则 → **`references/phase-2-worktree-lease.md`**。
 
-> **Engine check (when available):** run `mstar lease verify <plan-id>` (or `import { validateExecutionLease } from "@mstar-harness/engine"` in a host hook — `validateIntegrationMergeLease` is import-only; no CLI form yet). On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
+> **Engine check (when available):** run `mstar lease verify <plan-id>` 或 `mstar lease verify-integration`（或 import `validateExecutionLease` / `validateIntegrationMergeLease` from `@mstar-harness/engine` in a host hook）以校验上述迭代 lease（execution_lease / integration_merge_lease）。On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
 
 任一 false → **stop**。Phase 1 / Prepare 未完成 → 先完成 Phase 1 或 per-plan Prepare，再进入本 Phase。
 
@@ -391,3 +391,11 @@ Iteration Phase 2 附加：
 - **不要在缺 `iteration_base_branch` / `target_branch` 时默认 `main` / `master`**
 - **不要在 iteration-start §1.6 由 product/architect 向 `{KNOWLEDGE_DIR}/` 新增**（知识 → iteration-close **`mstar-compound`**）
 - **不要在 per-plan Done 后立即 compound** — 等 iteration-close 统一做
+
+## Workflow
+
+Phase 1–5 总览见上文 **`## 设计思路`** 图：`iteration-start`（范围 + compass + §1.6 Review & Edit 链）→ `Autonomous Execute`（§2.4 per-plan 循环：分支 → 实现 → QC → QA gate → Done → 串行 merge）→ `iteration-close`（§3.1–§3.5 + `mstar-compound`）→ `PR delivery`（Phase 4）→ `PR merge-ready loop`（Phase 5 至 §5.5 exit）。每波用 §2.1 session todos 设护栏防范围漂移。
+
+## Evidence
+
+迭代交付完成 = Phase 5 §5.5 exit checklist 全 `[x]` + PR mergeable + required CI 全绿 + reviews resolved。Phase 3 完成标志 = compass frontmatter `status: completed` + `end_date`（§3.4）+ §3.5 exit checklist。close 证据在磁盘产物（compass / plans / specs 修订 + 索引 + metadata），不要求单独迭代审查报告（§1.6）。

package/harness-skills/mstar-phase-gates/SKILL.md

@@ -110,3 +110,9 @@ per-plan Done 是 per-plan 的闭环终点；compound 是迭代级收口活动
 - Prepare 阶段证据：问题定义、歧义结论、plan 链接。
 - Execute 阶段证据：tasks 清单、实现自检、审查/验证证据。
 - 结论证据：不得仅写"done"，必须可复核（命令、输出、截图或复现步骤）。
+
+## References
+
+- plan 文件落盘与路径符号 → **`mstar-plan-conventions`**
+- 多 task 默认 `Execution mode: sdd` 的 implement 波次 → **`mstar-sdd`**
+- QC / QA 审查链与 residual 登记 → **`mstar-review-qc`**

package/harness-skills/mstar-plan-artifacts/SKILL.md

@@ -17,7 +17,7 @@ description: "Morning Star plan harness artifacts — `{PLAN_DIR}` main plans an
 | Done row compaction Profile A/B | `references/done-compaction.md` |
 | `status.json`, residual severity, lifecycle, `jq` | `references/status-and-residuals.md` |
 | Empty-repo `status.json` / `notes.json` / Profile B `plans-done.json` templates | `templates/status.empty.json`, `templates/notes.empty.json`, `templates/plans-done.empty.json` (`templates/README.md`) |
-| Tech-debt rollup (read-only) | engine `techDebtRollup` import (no CLI form; see `references/status-and-residuals.md`) |
+| Tech-debt rollup (read-only) | `mstar status tech-debt [path]` (engine `techDebtRollup`; see `references/status-and-residuals.md`) |
 
 **Out of scope:** branch and QC/QA checkout alignment → **`mstar-branch-worktree`**; leaf QC checklist and verdict → **`mstar-roles/references/qc-specialist/`**; PM QC orchestration → **`mstar-review-qc`**; `{HARNESS_DIR}` discovery and init → **`mstar-plan-conventions`**.
 
@@ -35,13 +35,34 @@ description: "Morning Star plan harness artifacts — `{PLAN_DIR}` main plans an
 
 - **Findings cleanup**: Assignment **`Findings cleanup: zero-residual | allow-residual`** (+ optional `metadata.findings_cleanup`); iteration Phase 2 defaults to **`zero-residual`** → **`references/status-and-residuals.md`** (“Findings cleanup modes”).
 
-> **Engine check (when available):** import `findingsCleanupGate` from `@mstar-harness/engine` in a host hook to enforce the cleanup mode above. On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
+> **Engine check (when available):** run `mstar status findings-cleanup <plan-id>` (or import `findingsCleanupGate` from `@mstar-harness/engine` in a host hook) to enforce the Findings cleanup mode above. On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
 
 - **`notes.json`**, optional **`tech_debt_summary`** (rollup view; compute via engine `techDebtRollup` — **`references/status-and-residuals.md`**).
 - **Iteration Phase 2 leases** (`metadata.control_worktree_path`, `plans[].execution_lease`, `metadata.integration_merge_lease`): claim-before-`InProgress`, resume vs steal, orphan recovery → **`references/status-and-residuals.md`** (“Iteration execution leases”).
 
-> **Engine check (when available):** run `mstar lease verify <plan-id>` (or `import { validateExecutionLease } from "@mstar-harness/engine"` in a host hook — `validateIntegrationMergeLease` is import-only; no CLI form yet). On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
+> **Engine check (when available):** run `mstar lease verify <plan-id>` or `mstar lease verify-integration` (or import `validateExecutionLease` / `validateIntegrationMergeLease` from `@mstar-harness/engine` in a host hook) to validate the iteration leases above (execution_lease / integration_merge_lease). On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
 
 Field semantics, severity mapping, findings cleanup modes, archive flow, and `jq` examples → **`references/status-and-residuals.md`**.
 
 **Templates (this skill):** `templates/status.empty.json`, `templates/notes.empty.json` — copy into `{HARNESS_DIR}/` (`templates/README.md`).
+
+## Workflow
+
+产物生命周期主链：主 plan 落盘 `{PLAN_DIR}`（命名见 `references/plan-files-and-reports.md`）→ 实现推进时更新 `{HARNESS_DIR}/status.json`（`plans[]` 行 + root `residual_findings`）→ 审查波次产出 `{SDD_DIR}/review/` bundle（raw QC/QA reports）+ durable gate summary 回写主 plan / status → 关闭后 residual 归档 `{HARNESS_DIR}/archived/residuals/<plan-id>.json` → Done 行 compaction（Profile A/B，`references/done-compaction.md`）。索引（`{KNOWLEDGE_DIR}` / `{ITERATION_DIR}` / `{PLAN_DIR}`）随产物更新。
+
+## Decision Rules
+
+- residual **severity** 是机器字段 SSOT（`references/status-and-residuals.md`）；每条新 finding 只登记 root `residual_findings`，`metadata.residual_findings` 仅 legacy 只读，**禁止**双写。
+- **`Findings cleanup: zero-residual`** 默认（迭代 Phase 2）：可修 findings 当轮 fix → re-review 清干净；仅真 blocker 可 defer 且须 Durable Roadmap。
+- 登记前必须过 `validateResidual` / `validateStatus`（fail-loud handoff）；malformed → reject + rewrite。
+
+## Evidence
+
+正确结果 = 可复核产物链：`{SDD_DIR}/review/` 审查 bundle 落盘 + 主 plan / `status.json` 的 durable gate summary + residual 生命周期间档（open → verified close → archived）+ Done 行 compaction 完成。拒绝「仅对话声称」。
+
+## References
+
+- `references/plan-files-and-reports.md` — 主 plan / review bundle 命名、QC 波次、durable summaries
+- `references/status-and-residuals.md` — `status.json`、residual severity / lifecycle / `jq`
+- `references/done-compaction.md` — Done 行 compaction Profile A/B
+- `references/knowledge-and-designs.md` — knowledge / iterations / specs 边界与索引

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

@@ -483,7 +483,7 @@ Prefer **`archived/residuals/`**; migrate and delete history key when possible.
 # Replace .mstar with your resolved {HARNESS_DIR}; legacy projects may use .agents.
 jq '.residual_findings["01-data-infrastructure"] // .metadata.residual_findings["01-data-infrastructure"]' .mstar/status.json
 jq '.entries[] | select(.id == "R1")' .mstar/archived/residuals/01-data-infrastructure.json
-# Engine rollup (read-only, no CLI form): import { techDebtRollup } from "@mstar-harness/engine" in a host hook
+# Engine rollup (read-only): import { techDebtRollup } from "@mstar-harness/engine" in a host hook — CLI form: mstar status tech-debt <path>
 ```
 
 (`//` right-hand side = legacy read path.)
@@ -519,6 +519,7 @@ Append-only log for merge closure, batch archive, `tech_debt_summary` refresh, e
 // Engine check (when available) — pass status.json path if not .mstar/status.json
 import { techDebtRollup } from "@mstar-harness/engine";
 const rollup = techDebtRollup(".mstar/status.json"); // { computed, stored, checks, overall }
+// CLI form (same output; exit 1 on DRIFT): mstar status tech-debt <path> (default: {HARNESS_DIR}/status.json)
 ```
 
 - Prints computed `total_open`, `by_severity`, `by_target`, `by_plan`.

package/harness-skills/mstar-plan-conventions/SKILL.md

@@ -14,6 +14,10 @@ description: Morning Star (启明星) harness 计划目录约定 —— `{HARNES
 | `mstar-review-qc` | 派 QC（PM 同轮必读；SDD 强制 tri） |
 | `mstar-sdd` | PM 执行 `Execution mode: sdd` 的 implement 波次 |
 
+## Workflow
+
+主链：按「路径符号」+「`{HARNESS_DIR}` 解析顺序」确定目录（默认 `.mstar/`，兼容 `.agents/`）→ 按「初始化 Plan 目录」建 `plans/` / `status.json` 并追加 gitignore 进程产物集（进程本地、结果共享）→ 多 Plan · 同一 Spec 时按「Spec 驱动的分支模型」登记 iteration base / spec 集成分支 / 各 Plan 实现分支 / PR target → 主 plan 写入 `{PLAN_DIR}`（**Plan-Writing Path Gate**，不引入外部默认 plan 目录）。未启用 plan 时 → 对话追踪，门禁（QC/QA）照常。
+
 ## 路径符号（SSOT）
 
 | 符号 | 默认 |
@@ -156,6 +160,10 @@ Plans are written to **`{PLAN_DIR}`** when persistent plan tracking is enabled.
 
 仅需路径符号与 `plans[].metadata` 的 `primary_spec` / `spec_refs` 时：读本 SKILL 至「路径符号」+ **`mstar-plan-artifacts/references/knowledge-and-designs.md`** 即可，**不必**通读 status/residual 全文。
 
+## Evidence
+
+正确结果 = 落盘产物可复核：`{HARNESS_DIR}/status.json` 含对应 plan 行（状态 + `metadata` 分支字段），plan 文件存在于 `{PLAN_DIR}`，`{HARNESS_DIR}/AGENTS.md` 分层与 gitignore 与本文约定一致（进程本地 / 结果共享），`mstar path resolve` 输出与路径符号表一致。
+
 ## References
 
 - `references/harness-bootstrap-and-agents-layering.md` — 新仓 harness + AGENTS 分层

package/harness-skills/mstar-review-qc/SKILL.md

@@ -64,3 +64,13 @@ Leaf reviewers apply verdict per **`mstar-roles/references/qc-specialist/report-
 - Critical 发现须含触发条件、影响范围、修复建议。
 - 低置信度发现须含后续验证步骤。
 - 跨任务重复模式应标记。
+
+## Workflow
+
+QC 编排主链：plan 全部 task + L2 完成后 → PM 按 `Execution mode` 定座次（sdd 强制 tri **N=3** / inline 单席 **N=1**）→ 同一条消息发满 N 个 QC Assignment（含 branch review-package + `{SDD_DIR}/review/qcN.md` report paths）→ 席位按 `references/qc-specialist/report-template.md` 落盘 verdict → PM 汇总 `{SDD_DIR}/review/qc-consolidated.md`（覆盖语义：**未提及 = 未审查**；汇总层零注入）→ `Request Changes` 走 targeted re-review（同 `qcN.md` `## Revalidation` 原位更新 verdict）→ residual 按 `Findings cleanup` 留档 / 关闭 → durable summary 回写主 plan。
+
+## References
+
+- Leaf QC 执行（checklist / 报告模板 / 透镜）→ **`mstar-roles/references/qc-specialist/`**
+- Per-task review（L2，implement 波次内）→ **`mstar-sdd`**
+- Review bundle 命名与 QC 触发时机 → **`mstar-plan-artifacts/references/plan-files-and-reports.md`**

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

@@ -76,7 +76,7 @@ Role `references/*.md` files include explicit **`NEVER`** sections (anti-recursi
 
 PM consolidated (tri mode): `{SDD_DIR}/review/qc-consolidated.md` (same folder; no `<plan-id>` basename prefix) + durable main-plan summary. Naming SSOT: `mstar-plan-artifacts/references/plan-files-and-reports.md`.
 
-> **Engine check (when available):** import `validateRoleMapping` / `lintLoadOrder` from `@mstar-harness/engine` in a host hook to validate the mapping and parameter tables above against the on-disk `references/*.md` layout (shared families included) and lint the load-order declarations (no CLI form yet). On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
+> **Engine check (when available):** run `mstar roles validate` (or import `validateRoleMapping` / `lintLoadOrder` from `@mstar-harness/engine` in a host hook) to validate the mapping and parameter tables above against the on-disk `references/*.md` layout (shared families included) and lint the load-order declarations. On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
 
 ## Maintenance Rules
 
@@ -84,3 +84,16 @@ PM consolidated (tri mode): `{SDD_DIR}/review/qc-consolidated.md` (same folder;
 - Edit role family parameters in this file.
 - Keep shared-family roles (`fullstack-dev*`, `qc-specialist*`) on one shared reference file.
 - Add new roles by updating mapping, parameters (if needed), and adding corresponding `agents/*.md` shell.
+
+## Workflow
+
+加载顺序：Read `mstar-harness-core` → Read 本 skill（角色映射 + 参数表）→ 解析对应 `references/<role>.md` → 展开角色参数（`role_id` / `track` / `reviewer_index` 等）→ 按该角色文件的 Required Skill Dependencies 追加加载 → 执行。映射 / 参数表与磁盘 `references/*.md` 布局不符时先修再继续。
+
+## Evidence
+
+正确结果 = 角色映射与加载契约可机器校验：`mstar roles validate` 通过（映射 + 加载顺序 0 violations，见上方 Engine check blockquote 的 import 形态），`references/*.md` 布局与上表一一对应，shared-family 角色共用同一 reference 文件（引擎校验可用时先跑；不可用时以本文件为准）。
+
+## References
+
+- 角色正文 → `references/<role>.md`（本 skill 内；leaf QC / QA 等子目录见 `references/qc-specialist/`、`references/qa-engineer/`）
+- 全局角色 → `mstar-harness-core` 加载矩阵与专题 skill 索引

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

@@ -38,7 +38,7 @@ Before Task 1, scan plan once for:
 
 Batch all findings for the human in one message. If clean, proceed silently.
 
-## Per-task loop (PM only)
+## Per-task loop (PM only · Workflow)
 
 1. Record `BASE_SHA` (never use `HEAD~1` later)
 2. `mstar sdd workspace <plan-id>` → `SDD_DIR`（iteration L1 从 feature cwd 调用时：`MSTAR_CONTROL_ROOT=<control_worktree_path>` 或 `mstar sdd workspace <plan-id> <control_worktree_path>`；缺 status.json 的 linked worktree 会 fail closed）
@@ -94,7 +94,7 @@ Host mapping → **`mstar-host`** references (`model` / Task field).
     - **Honest non-convergence**: open findings at wave close → list them in detail and state the disposition — re-feed to the next fix round **or** transfer to residual tracking — never silently close.
 4. QA gate → **`mstar-harness-core`** Done rules; PM **`mstar-roles/references/project-manager/qa-trigger-matrix.md`**
 
-## Progress ledger
+## Progress ledger（Evidence）
 
 At start: `cat {SDD_DIR}/progress.md`. Tasks marked complete are DONE — do not re-dispatch after compaction.
 

package/harness-skills/mstar-skill-authoring/SKILL.md

@@ -17,7 +17,11 @@ description: Agent skill 撰写 / 重写 / 优化规范（SkillsBench 实验门
 
 详细 writer 流程与输出模板 → `references/skillsbench-authoring.md`（需要完整循环时再读）。
 
-## 6 条作者原则（必须遵守）
+## Workflow
+
+主链：按「Frontmatter Contract」先定触发契约（原则 3）→ 按「Body 必须回答的 5 问」写默认紧凑 body（原则 2）→ 变体细节按「Progressive Disclosure」进 `references/` / `templates/` / `scripts/` → 行为塑形改动按「验证门控（Evidence，原则 4 + 6）」留 paired 证据 → 按「Review Template」自审并完成「完成时主动说明」三问。
+
+## 6 条作者原则（Decision Rules，必须遵守）
 
 来源：SkillsBench 大规模实验。违反任一都会降低 agent 性能。
 
@@ -42,6 +46,20 @@ description: Agent skill 撰写 / 重写 / 优化规范（SkillsBench 实验门
 
 答不进这 5 问的内容 → 删或移到 `references/`。
 
+### 运行时别名（runtime alias map）
+
+已发布的 `mstar-*` 专题 skill 允许**运行时模式**（`lintFiveQuestion(body, "runtime")`）用**锁定别名表**回答同一问题（引擎常量 `RUNTIME_HEADING_ALIASES`）：
+
+| 问题 | 运行时别名（标题子串，大小写不敏感） |
+|------|------|
+| Workflow | `process`、`playbook` |
+| Decision Rules | `hard rules`、`core rules`、`rule`、`gate`、`not to do`、`red flags`、`反模式`、`红线`、`规则`、`门禁` |
+| Evidence | `output format`、`证据` |
+| References | `dependencies`、`关系` |
+
+- 别名表是**锁定表**：改表必须同步引擎回归测试与 corpus。
+- **新写 / greenfield skill（authoring / strict）仍要求 canonical 标题**；运行时别名只豁免已发布专题 skill 的机械 lint，**不豁免语义**——别名标题必须真实回答对应问题，正文不得因别名而缩水。
+
 ## Skill Purpose Test
 
 仅当全部成立才新建 / 扩写 skill：
@@ -109,7 +127,7 @@ Agents 按 **skill 名** 发现 skill；文档若给出完整仓内相对路径
 
 多宿主 / 多域细节按文件拆分，并在 body 写明「何时打开哪份」。
 
-## 验证门控（原则 4 + 6）
+## 验证门控（Evidence，原则 4 + 6）
 
 行为塑形改动必须留下证据，任选可观测形式：
 

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

@@ -128,3 +128,17 @@ Ask for consent before applying.
 - Do not create without PM/architect input (ask the questions)
 - Do not keep outdated strategy as "historical reference" — git preserves it
 - Do not conflate strategy (direction) with conventions (how-to)
+
+## Workflow
+
+主链：**创建**（Phase 1 收集上下文 → Phase 2 访谈 PM → Phase 3 落盘 `<repo-root>/STRATEGY.md` → Phase 4 可发现性检查）→ **维护**（方向变更时果断替换旧策略、Decision Log 记决策理由、保持最新）→ **定期评审**（重大架构决策后 / 新技术栈引入时 / 季度评审）。作为 brainstorm / plan 的上游锚点被引用。
+
+## Evidence
+
+正确结果 = `<repo-root>/STRATEGY.md` 通过 `lintStrategySections` 六节检查（Vision / What we build / What we don't build / Guiding Principles / Technology Direction / Decision Log，`mstar lint <STRATEGY.md>`），一屏可读完，且 Decision Log 记录的是**理由**而非仅结论。
+
+## References
+
+- 迭代级战略对齐（iteration-start §1.1 读 STRATEGY.md）→ **`mstar-iteration`**
+- 知识维护 / bootstrap（战略变更后的知识对账）→ **`mstar-compound-refresh`**
+- 路径符号与产物存储 SSOT → **`mstar-plan-conventions`**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mstar-harness/dsh",
-  "version": "2.3.0",
+  "version": "2.4.1",
   "description": "Morning Star harness dsh (DeepSeek Harness) cordis function plugin — in-process engine gates (status/dispatch/lease) with hard refusal channels.",
   "keywords": [
     "dsh",
@@ -68,19 +68,19 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-client-locale": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-client-runtime": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-commands": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-fs": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-jobs": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-skill": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-skill-filesystem": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6"
+    "@deepseek-ai/dsh-agent": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-client-locale": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-client-runtime": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-commands": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-fs": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-jobs": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-skill": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-skill-filesystem": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.7"
   },
   "publishConfig": {
     "access": "public"