@mstar-harness/dsh 2.2.0 → 2.4.0

package/harness-agents/writing-specialist.md

@@ -0,0 +1,35 @@
+---
+name: writing-specialist
+description: |-
+  写作专家 - 文档写作、小说写作、文案写作与脚本写作。
+  Writing Specialist - documentation, fiction, copywriting, and script writing.
+mode: subagent
+tools:
+  write: true
+  edit: true
+  bash: true
+permission:
+  bash:
+    "*": allow
+  task:
+    "*": deny
+    explore: allow
+---
+
+## Morning Star Role Binding
+
+You are `writing-specialist`. The complete role prompt is provided by the `mstar-roles` skill.
+
+- Skill: `mstar-roles` skill
+- Role reference: `references/writing-specialist.md` in the `mstar-roles` skill
+- Role parameters: `role_id=writing-specialist`, `mode=subagent`
+
+## Mandatory First Steps
+
+This file is a routing shell — NOT your complete role prompt. **Before any work, load in order:**
+
+1. `skill` → `mstar-harness-core` (state machine, gates, routing — global SSOT)
+2. `skill` → `mstar-roles` (role mapping & parameter table)
+3. `Read` → `references/writing-specialist.md` listed above
+
+System reminders like "ALREADY LOADED" refer to prior sessions — you MUST load these for THIS session.

package/harness-commands/codebase-audit.md

@@ -2,7 +2,7 @@
 name: codebase-audit
 description: Survey a codebase as a senior advisor and produce prioritized, self-contained improvement plans. Read-only on source code. Use standalone before iteration-start to discover what's worth doing, or independently to build a prioritized backlog.
 agent: project-manager
-input: "[no args]"
+input: "[simplify]"
 ---
 
 # Audit Codebase
@@ -33,7 +33,7 @@ The audit is **advisory** — it does not enter the per-plan state machine (`Tod
 
 ## Execute
 
-Execute **`mstar-audit`** end to end（SKILL.md：Recon → Audit → Vet & prioritize → Write plans；effort `quick` / `standard` / `deep`；scope variants `security` / `perf` / `tests` / `branch` / `next` / `roadmap`）。Plans → `{PLAN_DIR}/audit-<YYYY-MM-DD>/NNN-<slug>.md` + `README.md` index，per **`mstar-plan-artifacts/references/plan-quality-bar.md`**。
+Execute **`mstar-audit`** end to end（SKILL.md：Recon → Audit → Vet & prioritize → Write plans；effort `quick` / `standard` / `deep`；scope variants `security` / `perf` / `tests` / `branch` / `next` / `roadmap` / `simplify`）。Plans → `{PLAN_DIR}/audit-<YYYY-MM-DD>/NNN-<slug>.md` + `README.md` index，per **`mstar-plan-artifacts/references/plan-quality-bar.md`**。
 
 Executor: PM dispatches `@code-reviewer`；大型仓库 scout 扇出经 Assignment `Delegation: allowed (scout/explore only, read-only)`（Routing 表）。
 

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-audit/SKILL.md

@@ -70,6 +70,21 @@ Every finding follows **`references/finding-format.md`** — read it before the
 
 ### Phase 3 — Vet, prioritize, confirm
 
+**Attack before vet — claims must survive an adversarial pass first.** Take the top candidate findings (by leverage; scale the count to finding volume — attack the whole table when small, the head when large) and run a three-way attack on each:
+
+1. **Counter-example** — find a boundary case that makes the claim not hold.
+2. **Simpler explanation** — does a simpler explanation cover the same evidence?
+3. **Evidence verifiability** — open the cited `file:line` and check it actually supports the claim.
+
+Dispose per the five-state rule (single-pass version — the four dispositions below implement the survey's five-state semantics: uncovered-keep == 未提及保留; never-drop == 全空/null 回流):
+
+- **Survived** — passes to vet unchanged.
+- **Refuted** — drop, and record in the index's "considered and rejected" section: `- <finding>: not worth doing because <one line>`.
+- **Hallucinated** — the attack surfaced a claim never in the original finding set: discard it and log a red-team record line in the index (never into the findings table; it does not occupy a "considered and rejected" slot — it was never a finding). Disambiguation: hallucinated = a claim the attack itself produced; fabricated/unsupported evidence inside the original finding goes to **Refuted** via the evidence-verifiability axis, not to Hallucinated.
+- **Uncovered** — the attack did not reach a finding: treat as unreviewed and keep for vet. Never drop a finding just because the attack missed it.
+
+Where the attack step decides whether a claim stands on its face, vet below confirms the code itself — opening cited files and disposing by-design / mis-attribution / duplicate cases; survived findings hand to vet below.
+
 **Vet before presenting — subagents over-report.** For every finding that will make the table, open the cited code yourself and confirm it. Three failure classes to expect:
 
 1. **By-design behavior** reported as a bug or vulnerability (e.g. honoring `https_proxy` flagged as SSRF — standard proxy convention; or a tradeoff explicitly recorded in an ADR).
@@ -112,6 +127,7 @@ If an audit directory from a previous run exists, **reconcile, don't duplicate**
 | Category focus (`security`, `perf`, `tests`, ...) | Recon, then that category only, then plan | Useful for targeted sweeps |
 | `branch` | Current branch changes only | Files changed since merge-base with default branch + their direct importers. Tag every finding `introduced` or `pre-existing` |
 | `next` / `roadmap` | Direction category only, in depth | 4–6 grounded suggestions; selected ones become design/spike plans |
+| `simplify` | DEBT-focused deep pass: dead / duplicated / speculative / over-built / added-then-removed / hand-rolled-where-a-dependency-exists surfaces | Prove-or-reject per playbook §5; findings use Category DEBT; tiny-real items → "considered and rejected" rows, never inline TODOs (Hard Rule 1) |
 
 ## Output format
 
@@ -138,6 +154,10 @@ If an audit directory from a previous run exists, **reconcile, don't duplicate**
 ## Findings considered and rejected
 
 - <finding>: not worth doing because <one line>.
+
+## Red-team dispositions
+
+- <finding>: <survived / refuted / hallucination-dropped / uncovered-kept>, <one-line reason>
 ```
 
 Status values: `TODO` | `IN PROGRESS` | `DONE` | `BLOCKED` | `REJECTED`

package/harness-skills/mstar-audit/references/audit-playbook.md

@@ -18,6 +18,8 @@ The highest-trust category — real bugs found by reading, not speculation.
 - Concurrency: check-then-act on shared resources, missing transactions around multi-write operations, idempotency of retried operations (webhooks, queues).
 - Type escape hatches: `any` / `as` casts / `@ts-ignore` clusters — each one is a place the compiler was overruled.
 - Resource leaks: unclosed handles, connections, subscriptions; missing `finally`.
+- Derived-state drift: every cache, replay, projection, denormalized copy, or UI echo must trace to an authoritative source and an invalidation point; flag retained state with neither.
+- Bounds covering the final operation: who owns the complete emitted/retained result (wrappers and metadata included)? Probe tiny/exact limits, oversized single chunks, and multibyte text against byte limits.
 
 ## 2. Security
 
@@ -34,6 +36,7 @@ Review only what is directly supported by code evidence. Keep findings framed as
 - Dependency posture: run the ecosystem's audit command (`npm audit`, `pip-audit`, `cargo audit`) in read-only mode. Report only critical/high advisories that affect reachable runtime code.
 - Production configuration: overly broad CORS where credentials are allowed, missing response-hardening headers (e.g. CSP), cookies missing appropriate `HttpOnly`/`Secure`/`SameSite` attributes, debug/verbose behavior enabled in production.
 - Data minimization: PII or sensitive operational data in logs, stack traces returned to clients, internal error details exposed through API responses.
+- Enforcement bypass: for every validation/rejection point, look for alternate callers that route around it — direct calls, wrappers, facades, schema-less paths, listener ordering.
 
 ## 3. Performance
 
@@ -56,6 +59,9 @@ The goal is not a percentage — it's *which untested code is dangerous*.
 - Existing test quality: tests that assert nothing meaningful, heavy mocking that tests the mocks, snapshot tests nobody reads, flaky patterns (real timers, real network, order dependence).
 - Missing test layers: unit-only suites with zero integration coverage on API boundaries, or the inverse.
 - Verification infrastructure: is there a one-command way to know the codebase works? If not, that's finding #1 and a prerequisite plan for any risky change.
+- Real entry path: do tests exercise the shipped entry (CLI, loader, plugin boot) rather than a hand-mounted equivalent?
+- Externally observable state: assertions verify logs, events, files, exit codes — never implementation restatement or agent-reported success.
+- User-visible output is behavior (conditional): in repos shipping UI copy, CLI output, API error shapes, or prompt text, wording is behavior — snapshot or e2e coverage should pin it.
 
 ## 5. Tech Debt & Architecture
 
@@ -65,6 +71,27 @@ The goal is not a percentage — it's *which untested code is dangerous*.
 - God objects/modules: files an order of magnitude larger than the repo median that everything touches; functions with double-digit parameters or deep conditional nesting.
 - Inconsistent patterns: three ways of doing data fetching / error handling / styling — pick the winner (the one the team converged on most recently) and plan the consolidation.
 - Abstraction mismatches: premature abstractions with a single implementation, or missing abstractions where the same change always requires touching N files in lockstep.
+- Public-but-one-caller: a public method on a generic service with a single internal caller is a private-capability closure candidate.
+- Unjustified defaults/public options: flag defaults or public operations/formats with no current-consumer evidence or prior art.
+
+### Prove-or-reject before reporting DEBT (`simplify` scope)
+
+**Prove before reporting dead code.** Classify consumers first — production corpus / tests-docs-only / ambiguous (examples, scripts: inspect, don't assume). Grep the exact symbol, plus event/field/config names, both quoted and bare. Read the call sites — a grep hit is a lead, not a verdict. "Tests are the only consumer" is a finding-enabler when the pinned behavior is non-load-bearing; "an invariant/test existing only to protect an unused API" is itself the signal.
+
+**Hand-rolled vs dependency swap bar.** Name the exact surface the package covers — residual semantics count against the swap. Health-check the dependency honestly. A recorded decision (ADR/knowledge doc) beats the swap claim — re-litigating a settled tradeoff needs new evidence. Weigh net deletion: implementation + dedicated tests + docs − remaining glue. A wrapper that relocates the same complexity is not a win.
+
+**Mirrored-fact test.** When several mechanisms track the same liveness/settlement fact, propose one controller — but preserve machinery protecting publication, rollback, callback containment, and first-terminal arbitration.
+
+**Strong-candidate families** (one line per family):
+- Symbols with no production consumer.
+- Tests/docs-only consumers pinning non-load-bearing behavior.
+- Two representations mirroring the same fact.
+- Seam methods fully implemented for support but with zero consumption.
+- Speculative product generality.
+- Invariants/rollbacks/expected-outputs existing only to protect an unused API.
+- Hand-rolled where a dependency exists.
+
+**Guards.** A production caller exists → feature decision, not cleanup (reject). A recorded seam/ADR rationale → new evidence must beat it. Tiny-but-real items → "considered and rejected" rows in the index, never inline TODOs (Hard Rule 1).
 
 ## 6. Dependencies & Migrations
 

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 前置）
 
@@ -217,3 +217,20 @@ Default process artifacts (`plans/`, `iterations/`, `status.json`, `sdd/`, `note
 - 若 **QA 与同仓其他可写角色并发**提交测试代码，仍须遵守上文「同仓并发写入」**worktree** 规则（可为 QA 单开一条写入 worktree，**同一 `Working branch`**，由 PM 在 Assignment 写明）。
 
 派发前清单与常见反模式 → **`references/parallel-writable-pre-dispatch.md`**。
+
+## History rewrite 与推送安全
+
+- 已推送分支的任何 history rewrite：先 `git fetch` 记录远端**精确 OID**，发布用 `--force-with-lease=<branch>:<observed-oid>`；**禁止**裸 `--force`。
+- 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

@@ -92,6 +92,11 @@ When something does not work, investigate; do not guess.
 - **Run existing tests before and after changes.** If they passed before and fail after, you broke something. If they were already failing, say so.
 - **If stuck, say so.** "I tried X and Y; neither worked. I'm seeing Z. I think it might be W but am not sure" is infinitely more useful than silently trying random things for 20 iterations.
 
+**Dataflow-directed diagnosis — how to locate, verify, and falsify** (for where to fix, see Surgical Changes · bug=root-cause; for the pre-fix repro test, see the bullets above):
+- **Map the data flow before judging.** Trace input → processing → storage → output, noting who writes and who reads at each step. A bug is a state deviation from expectation at some point in that flow (expected state vs observed state) — locate it from the data, not by static code reading.
+- **Four verifiable cross-checks.** Every hypothesis must be cross-checkable: re-run the repro / log comparison / input-output comparison / dual-path comparison. A hypothesis that cannot be verified on the spot is not a conclusion.
+- **Falsify the fix.** After the fix, re-run the original repro and compare output with expectation. If the problem did not disappear, the root cause was wrong — report "verification failed" explicitly; never pretend success.
+
 ## 5) Goal-Driven Execution
 
 Convert vague requests into verifiable outcomes and iterate until verified. Define concrete success criteria before major edits; use brief `Step -> verify` checkpoints for multi-step tasks; for split delivery, maintain a durable roadmap (current slice, later slices, dependencies, owner/trigger, completion condition); prefer evidence-backed completion (tests, command output, reproducible checks). If verification fails, loop on diagnosis and fix before declaring completion. Do not finish with "next plan / later / follow-up" only in prose — remaining work must be written to the plan/status artifact or the task reports `Partial` / `Blocked`.
@@ -145,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/references/compound-workflow.md

@@ -113,6 +113,22 @@ After writing, validate the YAML frontmatter:
 - `date` is YYYY-MM-DD format
 - Array fields use `[item1, item2]` syntax
 
+### 3.5 知识文档质量门：HEAD-resolvability & prose hygiene
+
+写作完成、进入 Phase 4 前，对文档运行本质量门（writing-specialist 编辑 durable harness artifacts 时适用同一 rubric — 见 `mstar-roles/references/writing-specialist.md` Output Guidance 指针）：
+
+- **The one test**：读者在 HEAD（无 chat transcript / dispatch prompt / 未合并草稿访问权）能否解析每个引用并验证每个声明？
+- **mstar 泄漏分类**（vantage 来自 authoring session 而非仓库现状；修剪或重述）：
+  - dead session citations：chat-only decision 序号 → 引 plan/knowledge/roadmap 属主路径，或独立重述事实
+  - durable docs 中的 change narration：knowledge/roadmap/README 陈述现状；已修回归 → counterfactual-present（「without X, Y happens」）
+  - review choreography：谁在哪轮确认 → 平实事实；finding id 留在 review bundle（其 sanctioned genre）
+  - reviewer-addressed justification（向评审自辩的措辞）
+  - control-flow narration（过程/控制流叙述）
+  - hedges without markers → 既有 `simplify:` / `temporary` 标记约定（`mstar-coding-behavior`；引用不重复）
+  - authoring-language slips：双语对之外的 zh/en 混杂
+- **Keep 规则（mstar-sanctioned）**：review bundle / QC report 内的 R# 与 finding id（durable 文档引用 QC 证据的 sanctioned pattern 是经 review bundle 路径引用：finding id 留在 bundle 内，durable 文档只引用 bundle 路径本身）；issue 引用；带 provenance 词的 measured bounds；runtime old/new 生命周期态；Alternatives-considered genre 节；HEAD 持久工件中的 iteration/plan id
+- **过度修正陷阱**：义务↛背书翻转；hypothetical 保持标记；共享一句时删子句不删句。「修剪前枚举命题」→ complete-proposition rule（`mstar-roles/references/writing-specialist.md` Output Guidance — SSOT，不在本节重述）
+
 ## Phase 4: Discoverability check
 
 Check whether the project's `AGENTS.md` or `CLAUDE.md` would lead a future agent to discover `{KNOWLEDGE_DIR}`.

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

@@ -50,6 +50,9 @@ For each candidate document, classify into one of five outcomes:
 | **Replace** | Old doc is misleading; known better replacement exists | Create trustworthy successor, then delete old |
 | **Delete** | No longer useful, applicable, or distinct | Delete — git history preserves it |
 
+> **Guardrail — rejected approaches:** a captured rejected approach stays only while the losing idea remains a tempting, meaningful mistake; delete it once obsolete or no longer plausible.
+> **Calibration:** first real run of this axis — 9 size-divergent knowledge docs (36–78 lines) under `{KNOWLEDGE_DIR}/architecture-patterns/` classified at fold time, all kept by future value (evidence: `.mstar/plans/20260815-mstar-knowledge-prose-folds.md` `## Review Gate Summary` → Task evidence); length proved not to be a criterion.
+
 ## Core rules
 
 1. **Evidence over opinion.** Signals are inputs, not a scorecard. Use engineering judgment.
@@ -58,6 +61,7 @@ For each candidate document, classify into one of five outcomes:
 4. **Be decisive.** When evidence is clear (file renamed, class moved), apply. Only ask PM when genuinely ambiguous.
 5. **Avoid low-value churn.** Don't edit for typos, polish, or cosmetic changes that don't improve accuracy.
 6. **Delete, don't archive** — **except** formal **iteration-start** §1.6 corpus hygiene (`mstar-iteration/references/iteration-corpus-hygiene.md`), which **moves** superseded/redundant knowledge/specs to `{HARNESS_DIR}/archived/knowledge|specs/`. Outside that gate, git history is the archive; `git log --diff-filter=D -- <path>` finds deleted docs.
+   > **Not adopted:** frozen-archive seal machinery, `Archived:` triplets, or a verifier — they contradict rule 6 (delete, don't archive; git history is the archive); do not reintroduce.
 7. **Evaluate document-set design.** Check whether two+ docs overlap and should be consolidated. Redundant docs silently drift apart.
 
 ## Scope selection
@@ -92,6 +96,7 @@ For each doc, check:
 2. **Referenced conventions still match?** — check against current `AGENTS.md`, `CONCEPTS.md`, lint configs.
 3. **Solution still the recommended approach?** — has a newer pattern superseded it?
 4. **Overlap with other docs?** — search for same module/tags to find duplicates.
+5. **Future decision value?** — rationale / alternatives considered / negative guarantees / reintroduction conditions that would still guide a future change → **Keep, regardless of length**. A completed decision whose body has no future leverage left (one-off fix detail, superseded mechanics) enters the Delete candidate pool. Word count and age remain discovery aids, never criteria.
 
 ### Phase 3: Classify and act
 
@@ -138,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-iteration/references/phase-4-5-pr-delivery.md

@@ -48,6 +48,7 @@
 **顺序记忆**：`observe findings → fix locally early → wait until CI + review wave idle → push batch → wait new wave → repeat`。
 
 > **Engine check (when available):** run `mstar iteration push-cadence [--ci-running] [--review-wave]` (or `import { pushCadenceProbe } from "@mstar-harness/engine"` in a host hook) to probe the push gate above. On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
+History rewrite / force-with-lease / 改写后证据失效规则 SSOT → `mstar-branch-worktree`「History rewrite 与推送安全」节；本节只管 push 时序。
 
 ### 5.1 Loop（repeat until §5.5 exit）
 

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`**.
 
@@ -28,19 +28,41 @@ description: "Morning Star plan harness artifacts — `{PLAN_DIR}` main plans an
 
 > **Engine check (when available):** run `mstar status validate <path>` (or `import { validateStatus } from "@mstar-harness/engine"` in a host hook). On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
 
+- **Fail-loud handoff**: findings must pass `validateResidual` (per entry) / `validateStatus` (whole file) before registration; malformed → reject + rewrite → **`references/status-and-residuals.md`** (“Fail-loud handoff contract”).
 - **Lifecycle**: open → verified close → **`archived/residuals/<plan-id>.json`**; machine **`severity`** enum in reference.
 
 > **Engine check (when available):** run `mstar status archive-residuals <plan-id>` (or `import { archiveResiduals } from "@mstar-harness/engine"` in a host hook). On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
 
 - **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

@@ -59,6 +59,14 @@ Canonical vs legacy residual definitions → **`mstar-plan-artifacts` SKILL.md**
 
 **Open `detail_doc` (optional):** repo-relative path under **`{PLAN_DIR}/residuals/<plan-id>/`** matching **`id`** (e.g. `R1`); omit if prose layer unused (`knowledge-and-designs.md`).
 
+## Fail-loud handoff contract
+
+Findings must pass engine validation **before** registration into `residual_findings`: `validateResidual(entry)` per entry, `validateStatus(doc)` for the whole file (`mstar status validate` / engine import). Malformed entries — **non-object**, missing any of the nine required fields (`id`, `title`, `severity`, `source`, `scope`, `decision`, `owner`, `target`, `tracking` — mirroring engine `RESIDUAL_REQUIRED_FIELDS` in `packages/engine/src/status.ts`), or **severity** outside the enum — are **rejected** (`ok:false` + violation): fix and rewrite — never silent pass-through, downgrade-write, or “write then patch”.
+
+dsh-derived findings map their keys per the engine-residual validation verification spec §5; dsh keys never enter the schema.
+
+---
+
 ## Residual findings: `severity` (SSOT, machine field)
 
 Each `residual_findings[<plan-id>][]` entry’s **`severity`** must be from this enum (legacy read paths → **`jq` examples** at end). QC report Markdown **Critical / Warning / Suggestion** are **section titles** — **do not** copy them verbatim into JSON `severity`.
@@ -475,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.)
@@ -511,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

@@ -53,8 +53,24 @@ description: "Morning Star QC orchestration — **SDD mandatory plan QC tri-revi
 
 Leaf reviewers apply verdict per **`mstar-roles/references/qc-specialist/report-template.md`**. PM **`{SDD_DIR}/review/qc-consolidated.md`** synthesizes tri (or single-seat `qc.md`) into one gate decision for implement fix waves and QA gate, then records the durable summary in the main plan/status artifacts.
 
+### 覆盖语义（未提及 = 未审查）
+
+- **未提及 = 未审查**：某 finding / severity 项 / 声明未被任何席位报告提及 → 不得在汇总中标记为已解决或通过；如实标注 `unreviewed`，按需转 targeted re-review 或补充席位。
+- **汇总层零注入**：consolidated 中每条发现可溯源到某 `qcN.md`；PM 不得在汇总层引入席位报告之外的新声明（PM 自身观察走独立 Status Update，不混入 gate 决策输入）。
+- **Unconfirmed 传导**：任一席位 verdict = `Unconfirmed`（`report-template.md` 定义的证据通道失败态）→ gate 决策不得为 `Approve`——先补证据（重发 review-package / 修 diff 基线）再收敛；受影响席位走既有 targeted re-review 机制（同 `qcN.md` `## Revalidation` 原位更新 verdict），不新增 re-review 形态、不改 N 规则。
+
 ## 证据规则（PM · consolidated 输入）
 
 - 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 索引