@mstar-harness/opencode 3.1.2 → 3.2.0

package/harness-commands/iteration-drive.md

@@ -15,114 +15,33 @@ Drive the active Morning Star iteration forward. **Boot loads skills; this comma
 
 **Done 定义**：**仅** Phase 5 §5.5 exit checklist 全 `[x]`。**Phase 3 close ≠ Done；Phase 4 开 PR ≠ Done。**
 
-## Continuous execution（HARD — Phase 2–5）
+## 共享 invariants / preflight / todos / STOP
 
-Execute **`mstar-iteration` §2.6**（Continuous execution SSOT：自 Phase 2 进入至 Phase 5 §5.5 exit 前 PM **连续编排**，进度汇报后下一条必须是 dispatch 或下一 phase 步骤，不向用户例行 yes/no check-in）。
-
-**合法 STOP（仅此升级用户）**：
-
-- §2.0 / Phase 4 branch metadata 缺失（`iteration_base_branch` / `target_branch`）
-- **`Blocked`**：真冲突、secrets、不可逆范围缺口、Phase 5 多轮仍无法 merge-ready
-- 用户本轮显式打断
-
-**Turn 收束纪律**：若 host 即将结束本轮，最后一条 assistant 内容必须是 **in-flight 动作**（invoke 已发出、或写明下一 dispatch 的 Assignment 字段），**不得**以对用户的确认问句结尾。
-
-## PM invariants（Phase 2–5 全程有效）
-
-| 禁止（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-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 就结束会话 |
-| Phase 5 自己改产品代码 | 需改产品代码时 **dispatch** `fullstack-dev` / `ops-engineer` |
-
-派发细则 → **`mstar-dispatch-gates`** + **`mstar-host`**。Phase 3 细则 → **`mstar-iteration` §3** + **`mstar-compound`**。
-
-**Session todos**：
-
-| Todo id | 何时追加 | 何时可勾掉 |
-|---------|----------|------------|
-| plan-wave todos | 进入 Phase 2 | 各 plan `Done` |
-| `phase-3-iteration-close` | 仅剩 1 个非 `Done` plan | Phase 3 §3.5 exit 全 `[x]` |
-| `phase-4-create-pr` | Phase 3 完成后 | PR 已创建并记录 URL/number |
-| `phase-5-pr-merge-ready` | Phase 4 完成后 | Phase 5 §5.5 exit 全 `[x]` |
+Phase 2–5 共享内容（PM invariants、assignment preflight、session todos、continuous-execution STOP）→ **`mstar-iteration/references/command-shared-invariants.md`**（SSOT；不在本命令重复）。
 
 ## Boot
 
-1. `mstar-harness-core`
-2. `mstar-roles` → `references/project-manager.md`
-3. `mstar-iteration` → **§ Phase 2–5**（§3 close gate；§4 PR delivery；§5 merge-ready loop）
-4. `mstar-compound` — Phase 3 §3.2 前加载（含 Phase 6 索引登记）
-5. `mstar-dispatch-gates` + host reference
-6. **`mstar-sdd`** — **before first implement dispatch** in Phase 2（per-task loop SSOT；多 task plan 默认 `Execution mode: sdd`）
-7. `mstar-review-qc` — before first QC dispatch in Phase 2
-8. `mstar-plan-artifacts`, `mstar-plan-conventions`, `mstar-branch-worktree`
-9. **`mstar-iteration/references/phase-2-worktree-lease.md`** — Phase 2 control worktree、`execution_lease`、serial `integration_merge_lease`（§2.0 #5 未 waive）
+按 **`mstar-iteration`** Load order 加载（`mstar-harness-core` → `mstar-roles` → `references/project-manager.md` → `mstar-iteration` § Phase 2–5 + `command-shared-invariants.md` → `mstar-compound` → `mstar-dispatch-gates` + host reference → **`mstar-sdd`**（first implement dispatch 前）→ `mstar-review-qc`（first QC 前）→ `mstar-artifacts` / `mstar-conventions` / `mstar-branch-worktree` → **`mstar-iteration/references/phase-2-worktree-lease.md`**）。完整 load list → **`mstar-roles`**。
 
 ## Phase 2: Autonomous Execute
 
-**Continuous execution applies**（上节）。Execute **`mstar-iteration` § Phase 2** exactly：§2.0 前置五道闸（含 branch metadata #4 + control-worktree/lease #5）→ §2.1 session todos → §2.2 read backlog（`status.json` + branch metadata）→ §2.3 integration branch + control worktree（record `metadata.control_worktree_path`；status/SDD via control path）→ §2.4 per-plan loop（**lease-gated parallel** across plan IDs unless `Plan parallelism: serial`；claim/resume `execution_lease`；feature worktree；**SDD** per-task 串行；QC full tri-review **N=3** + QA；serial merge via `integration_merge_lease`；cross-plan sync → compass）→ §2.5 dispatch-first → §2.6 push 纪律。全部 plan `Done` → **STOP**（Phase flow）→ 打印 `## Phase 3: iteration-close`；**不得**进入 Phase 4。
-
-**Assignment preflight**（`mstar-harness` bin 未安装时静默跳过）: 在每次 implement/QC/QA 派发前（**SDD** 下为最新 `{SDD_DIR}/task-N-brief.md` 或临时写盘的 Assignment），若本机装有 CLI，校验最新 Assignment。模式由迭代 compass frontmatter 的 `enforcement` 键决定（Slice 5）：
-
-- **默认（compass 无 `enforcement: hard`）— 可选 warn-only**：exit 1 仅提示，不阻断派发（Slice 3 行为不变）：
-
-```bash
-command -v mstar-harness >/dev/null 2>&1 && mstar-harness dispatch validate "<latest-assignment-file>"
-```
-
-- **`enforcement: hard`（迭代 compass frontmatter 声明）— fail-fast**：校验失败即 `exit 1` 阻断派发（bin 缺失仍静默跳过）：
+Execute **`mstar-iteration` § Phase 2** exactly（§2.0 五道闸 → §2.1 session todos → §2.2 backlog → §2.3 integration branch + control worktree → §2.4 per-plan loop（lease-gated；SDD per-task；QC tri N=3 + QA；serial merge）→ §2.5 dispatch-first → §2.6 push 纪律）。全部 plan `Done` → **STOP** → 打印 `## Phase 3: iteration-close`。
 
-```bash
-if command -v mstar-harness >/dev/null 2>&1; then mstar-harness dispatch validate "<latest-assignment-file>" || exit 1; fi
-```
-
-> 路径必须加引号且替换为具体文件（如最新 `{SDD_DIR}/task-N-brief.md`，勿留尖括号）——agent 代入的路径不得进入 shell 无引号展开。
+**Assignment preflight**：每次 implement/QC/QA 派发前按 **`mstar-iteration/references/command-shared-invariants.md`** 执行。
 
 ## Phase 3: iteration-close
 
-当 **every** plan 为 `Done`：
-
-1. **STOP** per-plan loop — 不得开 PR、不得进入 Phase 4/5、不得输出「迭代完成」摘要。
-2. 打印标题 **`## Phase 3: iteration-close`**（用户可见的 phase 边界）。
-3. Execute **`mstar-iteration` § Phase 3**（→ **`references/phase-3-iteration-close.md`** §3.0→§3.5）：§3.0.5 compass 规范化 → §3.1 close entry checklist（**HARD GATE**，必须打印）→ §3.2 compound + **`<iteration-id>/` package promotion**（`mstar-compound` Phase 6 索引登记）→ §3.3 roadmap → §3.4 frontmatter `status: completed` + `end_date` → §3.5 close exit checklist + commit → push。
-4. §3.5 exit 全 `[x]` 且 compass `status: completed` 后 → 打印 **`## Phase 4: Create PR`**。
-
-**Phase 3 exit（非 iteration-drive Done）**: §3.5 checklist `[x]` + compass frontmatter `completed`。
+当 **every** plan 为 `Done`：**STOP** per-plan loop → 打印 **`## Phase 3: iteration-close`** → execute **`mstar-iteration` § Phase 3**（→ **`references/phase-3-iteration-close.md`** §3.0→§3.5；§3.1 entry checklist HARD GATE；§3.2 compound + package promotion；§3.4 `status: completed` + `end_date`）→ §3.5 exit 全 `[x]` 后打印 **`## Phase 4: Create PR`**。
 
 ## Phase 4: Create PR
 
-Execute **`mstar-iteration` § Phase 4**（→ **`references/phase-4-5-pr-delivery.md`**）：打印 `## Phase 4: Create PR` → resolve `metadata.target_branch`（compass fallback；缺失 → **STOP**，never default `main`/`master`）→ 创建 PR `spec_integration_branch` → `target_branch` → 记录 PR URL + number（Phase 5 SSOT）→ 勾掉 host todo `phase-4-create-pr` → **Immediately** 打印 **`## Phase 5: PR merge-ready`**（**禁止**在此停止或汇报 Done）。
-
-**Phase 4 exit（非 iteration-drive Done）**: PR 已创建且 head = `spec_integration_branch`。
+Execute **`mstar-iteration` § Phase 4**（→ **`references/phase-4-5-pr-delivery.md`**）：打印 `## Phase 4: Create PR` → resolve `metadata.target_branch`（缺失 → **STOP**，never default `main`/`master`）→ 创建 PR `spec_integration_branch` → `target_branch` → 记录 PR URL + number → 勾掉 `phase-4-create-pr` → **Immediately** 打印 **`## Phase 5: PR merge-ready`**（**禁止**在此停止或汇报 Done）。
 
 ## Phase 5: PR merge-ready（babysit loop）
 
-Execute **`mstar-iteration` § Phase 5**（→ **`references/phase-4-5-pr-delivery.md`** §5.0–§5.2；**§5.1a push cadence HARD**）。**§5.5 exit 全 `[x]` = iteration-drive Done.**
-
-本 command **叠加**可选 helper skill 发现（**non-`mstar-*`**；不写入 `mstar-*` load order）：
-
-### 5.0 Discover optional helper skills
-
-Helper 搜索路径 → **`mstar-iteration/references/phase5-helper-discovery.md`**（babysit / `*-babysit` / greploop 路径清单；first readable `SKILL.md` wins per name）。
-
-| Priority | Condition | Read before loop | Primary done signal |
-|----------|-----------|------------------|---------------------|
-| 1 | `babysit` **or** any `*-babysit` found | that skill’s `SKILL.md`（prefer exact `babysit`, else first matching `*-babysit`） | Required CI **all green** + **all** review threads **resolved** |
-| 2 | `greploop` found **and** repo has Greptile/greploop | `greploop` SKILL.md | Greptile score **5/5** on this PR（**additive** — does not replace priority-1 gates） |
-| 3 | else neither babysit/`*-babysit` | —（fallback = babysit 同级 CI + reviews 门禁） | Required CI **all green** + **all** review threads **resolved** |
-
-**Both babysit/`*-babysit` and greploop apply**: run **babysit/`*-babysit` first**（CI + reviews），then optional greploop until Greptile **5/5**（串行；§5.5 仍须满足全部 exit 项）。Do **not** prefer greploop over babysit。**No greploop / repo without Greptile**: skip greploop entirely。**All modes** share §5.5 exit checklist（Greptile 5/5 only when greploop mode ran or repo shows a Greptile score）。
-
-### 5.1 Loop + review fix hygiene（all modes）
-
-Execute **`mstar-iteration` §5.1 loop**（`references/phase-4-5-pr-delivery.md` §5.1）：status（`gh pr view <number> --json mergeable,mergeStateStatus,statusCheckRollup,reviewDecision` 或宿主等价 API）→ merge conflicts → unresolved reviews → CI → **§5.1a idle push**（一批修复一次 push）→ mode-specific pass（babysit SKILL / greploop / fallback）→ §5.1 review fix hygiene（**comment on same thread + resolve**）→ repeat until §5.5。Fixes **push 到 `spec_integration_branch`**（PR head）；禁止另开分支替代。**Checkout（HARD，§5.0）**：直接在 control / 集成分支 checkout 上修；**禁止**另开 Phase 5 fix worktree，**禁止**套用 Phase 2 control 产品编辑禁令。产品代码修复 → **dispatch** dev/ops（Assignment cwd = control）；PM 线程不代写。**禁止**为「让 CI 变绿」而改 workflow，除非用户明确授权。多轮仍 blocked → 升级用户。
-
-### 5.2 Phase 5 exit checklist（iteration-drive Done）
+Execute **`mstar-iteration` § Phase 5**（→ **`references/phase-4-5-pr-delivery.md`** §5.0–§5.2；**§5.1a push cadence HARD**）。**§5.5 exit checklist 全 `[x]` = 本 command Done.**
 
-Print **`## Phase 5 exit checklist`** per **`mstar-iteration` §5.2**（`references/phase-4-5-pr-delivery.md` §5.2：PR mergeable、required CI green、review threads resolved（或用户书面 waive）、§5.1 comment + resolve、todo `phase-5-pr-merge-ready`；Greptile 5/5 仅当 greploop mode / repo 可见分数）→ 全 `[x]` 后结束本 command。
+本 command **叠加**可选 helper skill 发现（**non-`mstar-*`**；不写入 `mstar-*` load order）→ **`mstar-iteration/references/phase5-helper-discovery.md`**（babysit / `*-babysit` / greploop / fallback 路径清单；first readable `SKILL.md` wins）。Loop + review fix hygiene + exit checklist → §5.1–§5.2（同上 reference）。
 
 **Then** report: iteration id, plans completed, compound summary, PR link, merge-ready evidence（CI snapshot + review resolution + Greptile if applicable）。
 

package/harness-commands/iteration-loop.md

@@ -46,94 +46,54 @@ Parse: if the last token is exactly `S`/`M`/`L`/`XL` (case-insensitive), treat i
 
 ## Continuous execution（HARD — Phase 1 lock 后至 Phase 5 exit）
 
-Execute **`mstar-iteration` §2.6**（Continuous execution SSOT）。**合法 STOP（仅此升级用户）**：branch metadata 按 **`mstar-iteration`** autonomous resolve 顺序仍无法确定（**禁止**静默默认 `main`/`master`）；代码/roadmap **无可信候选**且无 `direction` 参数；**`Blocked`**（真冲突、secrets、不可逆范围缺口、Phase 5 多轮仍无法 merge-ready）；用户本轮显式打断。**Turn 收束纪律**：最后一条内容必须是 **in-flight 动作**（invoke 已发出或下一 Assignment），**不得**以确认问句结尾。
+Execute **`mstar-iteration` §2.6**（Continuous execution SSOT）+ **`mstar-iteration/references/command-shared-invariants.md`** STOP list（branch metadata 缺失 / **`Blocked`** / 用户显式打断 — 不在本命令重复）。**Loop 特有 STOP**：branch metadata 按 **`mstar-iteration`** autonomous resolve 顺序仍无法确定（**禁止**静默默认 `main`/`master`）；代码/roadmap **无可信候选**且无 `direction` 参数。**Turn 收束纪律**：最后一条内容必须是 **in-flight 动作**（invoke 已发出或下一 Assignment），**不得**以确认问句结尾。
 
-## PM invariants
+**Do not** Read `skills/grill-me/SKILL.md` for this command.
 
-| 禁止（PM 线程） | 必须 |
-|-----------------|------|
-| 自己 Edit 冒充 product-manager / architect / writing-specialist；只写 Assignment 就声称 review 完成 | §5.1 → §5.2 → §5.3 **顺序**各 **1 次 invoke**；5.4 PM lock 在 subagent 返回之后（**`mstar-iteration` §1.6**） |
-| 加载 `grill-me` | **Autonomous** direction lock（`mstar-iteration` §1.2） |
-| Write/Edit/Shell 产品代码、写测试、跑 QC；多 task plan inline 大包派发 | 每条 implement/QC/QA Assignment ⇒ **1 次 `Task`**；**SDD** per-task 循环 |
-| 最后 plan `Done` 后直接开 PR；Phase 5 自己改产品代码 | **Phase 3 → 4 → 5**；dispatch `fullstack-dev` / `ops-engineer` |
+## Boot
 
-派发细则 → **`mstar-dispatch-gates`** + **`mstar-host`**。
+按 **`mstar-iteration`** Load order 加载（`mstar-harness-core` → `mstar-roles` → `references/project-manager.md` → `mstar-iteration` § Phase 1–5 + `command-shared-invariants.md` → `mstar-dispatch-gates` → `mstar-phase-gates` → `mstar-conventions` / `mstar-artifacts` → `mstar-host` → `mstar-compound`（Phase 3 前）→ **`mstar-sdd`**（first implement 前）→ `mstar-review-qc`（first QC 前）→ `mstar-branch-worktree` → **`mstar-iteration/references/phase-2-worktree-lease.md`**）。完整 load list → **`mstar-roles`**。
 
-**Session todos**：
+**Session todos（loop 专属；Phase 2–5 共享 rows → `command-shared-invariants.md`）**：
 
 | Todo id | 何时追加 | 何时可勾掉 |
 |---------|----------|------------|
 | `phase-1-autonomous-start` | Boot | compass `locked` + integration committed |
-| plan-wave todos | 进入 Phase 2 | 各 plan `Done` |
-| `phase-3-iteration-close` | 仅剩 1 个非 `Done` plan | Phase 3 §3.5 exit 全 `[x]` |
-| `phase-4-create-pr` | Phase 3 完成后 | PR 已创建 |
-| `phase-5-pr-merge-ready` | Phase 4 完成后 | Phase 5 §5.5 exit 全 `[x]` |
-
-## Boot
-
-1. `mstar-harness-core`
-2. `mstar-roles` → `references/project-manager.md`
-3. `mstar-iteration` → **§ Phase 1**（含 **autonomous** direction lock / scale budget / branch resolve）+ **§ Phase 2–5**
-4. `mstar-dispatch-gates`
-5. `mstar-phase-gates` → Prepare
-6. `mstar-plan-conventions`, `mstar-plan-artifacts`
-7. `mstar-host` → active host reference
-8. `mstar-compound` — before Phase 3 §3.2
-9. **`mstar-sdd`** — before first implement dispatch in Phase 2
-10. `mstar-review-qc` — before first QC dispatch in Phase 2
-11. `mstar-branch-worktree` — when Git/write or QC checkout
-12. **`mstar-iteration/references/phase-2-worktree-lease.md`** — Phase 2 control worktree + lease（§2.0 #5 未 waive）
-
-**Do not** Read `skills/grill-me/SKILL.md` for this command.
-
----
 
 ## Phase 1: Autonomous start
 
-### 1. Research
-
-Survey structured harness dirs（`{HARNESS_DIR}/status.json`、`{ITERATION_DIR}/`、`{KNOWLEDGE_DIR}/`、`{SPECS_DIR}/`）+ glob for planning artifacts（`**/roadmap*.md`、`**/deferred*.md`、`**/features*.md`、`**/backlog*.md`、`**/TODO*.md`、`**/*.plan.md`）；read `STRATEGY.md` if present。Prioritize deferred / roadmap `next` items（code-first — **explore before guessing**）。
+Execute **`mstar-iteration` § Phase 1**（**autonomous** direction lock + scale budget + branch resolve SSOT → `references/autonomous-direction-lock.md`）：
 
-### 2–4. Explore → Lock → Write
+### 1–4. Research → Explore → Lock → Write
 
-Scope **2–4** candidates targeting product completeness（prefer deferred / roadmap `next`）→ **autonomous** direction lock（**`mstar-iteration` §1.2** + `references/autonomous-direction-lock.md`：`direction` arg 约束候选或 rank 后 **lock recommended**；落盘 rationale + success criteria + non-goals + scale budget；autonomous branch resolve — never silent `main`/`master`；**STOP** if no credible candidate and no `direction` arg；**do not** ask user to confirm）→ write compass + plans per **`mstar-iteration` §1.3–§1.5**（template `references/iteration-compass-template.md`；**business** plan count within scale budget）。
+Survey structured harness dirs（`{HARNESS_DIR}/status.json`、`{ITERATION_DIR}/`、`{KNOWLEDGE_DIR}/`、`{SPECS_DIR}/`）+ planning artifacts（`**/roadmap*.md`、`**/deferred*.md`、`**/features*.md`、`**/backlog*.md`、`**/TODO*.md`、`**/*.plan.md`）+ `STRATEGY.md`（if present）→ scope **2–4** candidates → **autonomous** lock（`direction` arg 约束；落盘 rationale + success criteria + non-goals + scale budget；branch resolve — never silent `main`/`master`；**STOP** if no credible candidate and no `direction` arg）→ write compass + plans per §1.3–§1.5（business plan count within scale budget）。
 
 ### 5. Review & Edit Chain（HARD GATE）
 
-Execute **`mstar-iteration` §1.6**：`product-manager` → `architect` → `writing-specialist` **顺序** invoke（编辑 compass / plans / specs / `<iteration-id>/` package；**禁止** `{KNOWLEDGE_DIR}/` 新增；writing-specialist corpus hygiene → `iteration-artifact-boundaries.md` + `iteration-corpus-hygiene.md`）→ PM lock（compass `status: locked` + Prepare gates）。Tool rule → **`mstar-dispatch-gates`**。Exception: user waives ("PM-only review").
+Execute **`mstar-iteration` §1.6**：`product-manager` → `architect` → `writing-specialist` 顺序 invoke（**禁止** `{KNOWLEDGE_DIR}/` 新增；corpus hygiene）→ PM lock。**Assignment preflight** per **`command-shared-invariants.md`**。
 
-**Pre-commit checklist**（print before §6; all `[x]`）：autonomous direction lock rationale in compass（not grill-me）；scale budget applied；compass + plans + `status.json` registered；三角色 invokes completed（**未**向 `{KNOWLEDGE_DIR}/` 新增）；PM final lock + Prepare gates；branch policy locked（`iteration_base_branch` / `spec_integration_branch` / `target_branch`）。**THEN** commit + push `iteration/<iteration-id>`.
+**Pre-commit checklist**（print before §6；all `[x]`）：
 
-### 6. Integration Branch
+- [ ] Autonomous direction lock rationale recorded in compass（**not** grill-me）
+- [ ] Scale budget applied（business plan 按 S/M/L/XL 名额）
+- [ ] compass + plans + `status.json` registered
+- [ ] product-manager / architect / writing-specialist invokes completed（**未**向 `{KNOWLEDGE_DIR}/` 新增）
+- [ ] PM final lock：compass `status: locked` + Prepare gates pass
+- [ ] Branch policy locked：`iteration_base_branch` / `spec_integration_branch` / `target_branch` recorded
+- [ ] **THEN** commit + push `iteration/<iteration-id>`
 
-Per **`mstar-iteration` §2.3**（`git fetch` → `git checkout -b <spec_integration_branch> <iteration_base_branch>`；register branch fields in compass + `status.json`；commit docs；push）。**STOP** if `iteration_base_branch` / `target_branch` still missing after autonomous resolve.
+### 6. Integration Branch
 
-**Immediately** print `## Phase 2: Autonomous Execute` → continue below（勾掉 `phase-1-autonomous-start`）。
+Per **`mstar-iteration` §2.3**（create from `iteration_base_branch`；register branch fields；commit docs；push）。**STOP** if base/target missing。**Immediately** print `## Phase 2: Autonomous Execute` → continue（勾掉 `phase-1-autonomous-start`）。
 
 ---
 
 ## Phase 2–5: Execute → close → PR → merge-ready
 
-Delegate to **`iteration-drive`**（Phase 2 → **`mstar-iteration` §2**、Phase 3 → **§3** + `references/phase-3-iteration-close.md`、Phase 4/5 → **§4–§5** + `references/phase-4-5-pr-delivery.md`、Phase 5 helper discovery → `mstar-iteration/references/phase5-helper-discovery.md`）。
-
-**Assignment preflight**（`mstar-harness` bin 未安装时静默跳过）: 每次 implement/QC/QA 派发前校验最新 Assignment（**SDD** 下为最新 `{SDD_DIR}/task-N-brief.md` 或临时写盘的 Assignment），同 `iteration-drive`。模式由迭代 compass frontmatter 的 `enforcement` 键决定（Slice 5）：
-
-- **默认（compass 无 `enforcement: hard`）— 可选 warn-only**：exit 1 仅提示，不阻断派发（Slice 3 行为不变）：
-
-```bash
-command -v mstar-harness >/dev/null 2>&1 && mstar-harness dispatch validate "<latest-assignment-file>"
-```
-
-- **`enforcement: hard`（迭代 compass frontmatter 声明）— fail-fast**：校验失败即 `exit 1` 阻断派发（bin 缺失仍静默跳过）：
-
-```bash
-if command -v mstar-harness >/dev/null 2>&1; then mstar-harness dispatch validate "<latest-assignment-file>" || exit 1; fi
-```
-
-> 路径必须加引号且替换为具体文件（如最新 `{SDD_DIR}/task-N-brief.md`，勿留尖括号）——agent 代入的路径不得进入 shell 无引号展开。
+Delegate to **`iteration-drive`**（Phase 2 → §2、Phase 3 → §3 + `references/phase-3-iteration-close.md`、Phase 4/5 → §4–§5 + `references/phase-4-5-pr-delivery.md`、Phase 5 helper discovery → `phase5-helper-discovery.md`）。**Assignment preflight** per **`command-shared-invariants.md`**。
 
-**Loop 特有**：Phase 5 push cadence（HARD）→ **`mstar-iteration` §5.1a**；exit checklist → **`mstar-iteration` §5.2**（`references/phase-4-5-pr-delivery.md` §5.2）。
+**Loop 特有**：Phase 5 push cadence（HARD）→ **`mstar-iteration` §5.1a**；exit checklist → §5.2（`references/phase-4-5-pr-delivery.md`）。
 
-**Then** report: iteration id, locked direction + scale, plans completed, compound summary, PR link, merge-ready evidence.
+**Then** report: iteration id, locked direction + scale, plans completed, compound summary, PR link, merge-ready evidence。
 
 PR merge itself may remain manual unless user authorized auto-merge.

package/harness-commands/iteration-start.md

@@ -22,7 +22,7 @@ Start a new Morning Star harness iteration. **Phase 1 is not complete until the
 
 **Parse**: if any token is exactly `pause` (case-insensitive), treat as the `pause` flag; the remaining tokens (joined) are the `direction` hint. `/iteration-start pause` = pause with empty direction.
 
-## PM invariants（本命令全程有效 — 读完再动手）
+## PM invariants（Phase 1 review-chain — 本命令全程有效）
 
 你是 **`project-manager` 编排者**，不是三专业角色的合并替身。
 
@@ -36,9 +36,7 @@ Start a new Morning Star harness iteration. **Phase 1 is not complete until the
 
 **Phase 1 完成定义**：compass `status: locked` + 三角色 invoke 已返回 + pre-commit checklist 全 `[x]` — 不是初稿落盘。**Command Done**（§7 auto-continue）= Phase 5 §5.5 exit checklist 全 `[x]`（同 `iteration-drive`）；`pause` 时 = Phase 1 完成。
 
-Detailed workflow → **`mstar-iteration` § Phase 1**；per-plan Prepare gates → **`mstar-phase-gates`**（specify → clarify → plan）。
-
-**Phase 2–5 auto-continue（§7）invariants** → **`iteration-drive`**「PM invariants」表（不写产品代码 / 不 inline 大包 / 每 Assignment 1 invoke / Phase 3→4→5 顺序 / Phase 5 dispatch 改代码）。
+**Phase 2–5 共享 invariants / preflight / todos / STOP** → **`mstar-iteration/references/command-shared-invariants.md`**（不在本命令重复）。
 
 ## Path split（HARD — 路由）
 
@@ -51,13 +49,7 @@ Detailed workflow → **`mstar-iteration` § Phase 1**；per-plan Prepare gates
 
 ## 0. Boot
 
-1. `mstar-harness-core`
-2. `mstar-roles` → `references/project-manager.md`
-3. `mstar-iteration` → **§ Phase 1**（迭代范围、compass 模板、**§1.5.5 产物边界**、§1.6 Review & Edit chain、状态初始化）
-4. `mstar-dispatch-gates`
-5. `mstar-phase-gates` → Prepare（specify → clarify → plan）
-6. `mstar-plan-conventions`, `mstar-plan-artifacts`
-7. `mstar-host` → active host reference（invoke 能力）；若 Cursor Plan mode → 另读 **`cursor-plan-mode-bridge.md`**（`mstar-iteration` Phase 1 in Plan mode）
+按 **`mstar-iteration`** Load order 加载（`mstar-harness-core` → `mstar-roles` → `references/project-manager.md` → `mstar-iteration` § Phase 1 + `mstar-phase-gates` + `mstar-dispatch-gates` + `mstar-conventions/artifacts` + `mstar-host` → active host reference）。Cursor Plan mode 另读 **`cursor-plan-mode-bridge.md`**（`mstar-iteration` Phase 1 in Plan mode）。完整 load list → **`mstar-roles`**。
 
 **若 Cursor Plan mode 活跃 → 进入 §P；否则继续 §1。**
 
@@ -68,51 +60,35 @@ Execute **`mstar-host/references/cursor-plan-mode-bridge.md`** § **"mstar-itera
 Command-unique 补充（bridge 未枚举）：
 
 - **空白脚手架字段**：Direction / Scope / Acceptance Criteria / Non-Goals / Delivery Branch Policy（`iteration_base_branch` / `spec_integration_branch` / `target_branch`）/ Plans / Feedback log / Deferred grill log
-- **Build 才勾的 todos**（顺序）：`harness-init` → `finalize-compass-plans`（**同一份** CreatePlan 落成 compass + plans + `status.json` 登记 + 索引）→ review-edit-product-manager → review-edit-architect → review-edit-writing-specialist → `pm-lock` → `integration-branch`
+- **Build 才勾的 todos**（顺序）：`harness-init` → `finalize-compass-plans`（同一 CreatePlan 落成 compass + plans + `status.json` 登记 + 索引）→ review-edit-product-manager → review-edit-architect → review-edit-writing-specialist → `pm-lock` → `integration-branch`
 
 ## 非 Plan 路径从这里继续 ↓
 
 ## 1. Research
 
-Survey structured harness dirs（`{HARNESS_DIR}/status.json`、`{ITERATION_DIR}/`、`{KNOWLEDGE_DIR}/`、`{SPECS_DIR}/`）+ glob for planning artifacts（`**/roadmap*.md`、`**/deferred*.md`、`**/features*.md`、`**/backlog*.md`、`**/TODO*.md`、`**/*.plan.md`）；read matches with iteration-level / deferred-scope information；read `STRATEGY.md`（if exists）。Prioritize deferred / incomplete items from prior iterations。
+Survey structured harness dirs（`{HARNESS_DIR}/status.json`、`{ITERATION_DIR}/`、`{KNOWLEDGE_DIR}/`、`{SPECS_DIR}/`）+ glob for planning artifacts（`**/roadmap*.md`、`**/deferred*.md`、`**/features*.md`、`**/backlog*.md`、`**/TODO*.md`、`**/*.plan.md`）；read `STRATEGY.md`（if exists）and `{KNOWLEDGE_DIR}/README.md`（if exists — Active index rows are Research candidates）。Prioritize deferred / incomplete items from prior iterations。
 
 ## 2. Explore Directions
 
-Scope **2–4** candidates targeting **product completeness**（default to deferred items from previous iterations；allow substantive refactoring where it accelerates product maturity）。**If `direction` arg given** — narrow candidates to that hint (still scope 2–4 unless the hint is explicitly singular); record the hint in grill-me context。**非 Plan 路径**（Plan mode 已由 §P 处理）。
+Scope **2–4** candidates targeting **product completeness**（default to deferred items from previous iterations；allow substantive refactoring where it accelerates product maturity）。**If `direction` arg given** — narrow candidates to that hint (still scope 2–4 unless explicitly singular)；record the hint in grill-me context。
 
 ## 3. Lock Direction — bundled `grill-me`
 
-> **非 Plan 路径**。Cursor Plan mode 用 §P.3 feedback loop + §P.3.5 deferred grill（主路径不是 grill）。
-
-**Direction lock mode: `interactive`**（`mstar-iteration` §1.2 默认；本命令不使用 `autonomous`）。
+> **非 Plan 路径**。Cursor Plan mode 用 §P feedback loop + deferred grill（主路径不是 grill）。
 
-This command bundles a **non-`mstar-*`** skill at `skills/grill-me/SKILL.md`. **Only this command step**（及 §P.3.5 deferred grill）references it — **do not** load it from `mstar-harness-core` or other `mstar-*` skills.
+**Direction lock mode: `interactive`**（`mstar-iteration` §1.2 默认；本命令不使用 `autonomous`）。This command bundles a **non-`mstar-*`** skill at `skills/grill-me/SKILL.md` — **only this command step** references it.
 
-**Before this step:** Read `skills/grill-me/SKILL.md`. Run **grill-me** to stress-test candidate directions with the user: walk through trade-offs, converge on a **single iteration direction** with shared understanding, document locked direction + success criteria + non-goals。**If `direction` arg given** — seed grill-me with it as the recommended direction (still interactive: user may correct/refine; the hint does **not** skip grill-me)。Confirm delivery branch policy（`iteration_base_branch`、`target_branch`）per **`mstar-iteration` §1.2** — **Do not default to `main` / `master` just because those names exist.**
+**Before this step:** Read `skills/grill-me/SKILL.md`. Run **grill-me** to stress-test candidate directions with the user: walk through trade-offs, converge on a **single iteration direction** with shared understanding, document locked direction + success criteria + non-goals。**If `direction` arg given** — seed grill-me with it (still interactive; the hint does **not** skip grill-me)。Confirm delivery branch policy（`iteration_base_branch` / `target_branch`）per **`mstar-iteration` §1.2** — **Do not default to `main`/`master` just because those names exist.**
 
 ## 4. Write Compass & Plans
 
-Produce harness artifacts per **`mstar-iteration` §1.3–§1.5**（template: `mstar-iteration/references/iteration-compass-template.md`）：compass（frontmatter **must** include `iteration_base_branch`、`target_branch`、`status: active`）、plans、`status.json` 登记（`mstar-iteration` §1.5）、`{ITERATION_DIR}/README.md` 索引（一行 = 一次迭代）、package dirs（`{ITERATION_DIR}/<iteration-id>/{guides,specs}/`）。**非 Plan 路径**。
+Produce harness artifacts per **`mstar-iteration` §1.3–§1.5**（template: `mstar-iteration/references/iteration-compass-template.md`）：compass（frontmatter **must** include `iteration_base_branch`、`target_branch`、`status: active`）、plans、`status.json` 登记（§1.5）、`{ITERATION_DIR}/README.md` 索引（一行 = 一次迭代）、package dirs（`{ITERATION_DIR}/<iteration-id>/{guides,specs}/`）。
 
 ## 5. Review & Edit Chain（HARD GATE — do not commit before this）
 
-Execute **`mstar-iteration` §1.6**（SSOT）：顺序 `product-manager` → `architect` → `writing-specialist` → PM lock（**禁止**并行三角色；OpenCode plain role id — `mstar-host/references/opencode.md` § Role-mention hygiene）；**禁止** `{KNOWLEDGE_DIR}/` 新增；writing-specialist specs corpus hygiene（`iteration-artifact-boundaries.md` + `iteration-corpus-hygiene.md`）。Tool rule → **`mstar-dispatch-gates`** specialist review-and-edit（每角色 1 invoke，等磁盘修订返回）。Exception: user explicitly waives subagent dispatch ("PM-only review").
-
-**Assignment preflight**（`mstar-harness` bin 未安装时静默跳过）: 在每次角色 invoke 前，若本机装有 CLI，校验最新落盘的 Assignment（临时写盘或既有 brief）。模式由迭代 compass frontmatter 的 `enforcement` 键决定（Slice 5）：
-
-- **默认（compass 无 `enforcement: hard`）— 可选 warn-only**：exit 1 仅提示，不阻断派发（Slice 3 行为不变）：
-
-```bash
-command -v mstar-harness >/dev/null 2>&1 && mstar-harness dispatch validate "<latest-assignment-file>"
-```
+Execute **`mstar-iteration` §1.6**（SSOT）：顺序 `product-manager` → `architect` → `writing-specialist` → PM lock（**禁止**并行三 roles；OpenCode plain role id — `mstar-host/references/opencode.md`）；**禁止** `{KNOWLEDGE_DIR}/` 新增；writing-specialist corpus hygiene（`iteration-artifact-boundaries.md` + `iteration-corpus-hygiene.md`）。Tool rule → **`mstar-dispatch-gates`** specialist review-and-edit（每 role 1 invoke，等磁盘修订返回）。Exception: user explicitly waives subagent dispatch ("PM-only review").
 
-- **`enforcement: hard`（迭代 compass frontmatter 声明）— fail-fast**：校验失败即 `exit 1` 阻断派发（bin 缺失仍静默跳过）：
-
-```bash
-if command -v mstar-harness >/dev/null 2>&1; then mstar-harness dispatch validate "<latest-assignment-file>" || exit 1; fi
-```
-
-> 路径必须加引号且替换为具体文件（如最新 `{SDD_DIR}/task-N-brief.md`，勿留尖括号）——agent 代入的路径不得进入 shell 无引号展开。
+**Assignment preflight**：每次 invoke 前按 **`mstar-iteration/references/command-shared-invariants.md`** 执行（warn-only + `enforcement: hard` fail-fast；bin 缺失静默跳过）。
 
 **Prepare gate (per plan in compass)**:
 
@@ -124,56 +100,23 @@ if command -v mstar-harness >/dev/null 2>&1; then mstar-harness dispatch validat
 
 PM must print this block before §6; all `[ ]` must be `[x]`:
 
-- [ ] direction lock decisions recorded in compass（Plan 路径：Feedback log + 可选 Deferred grill log；非 Plan：grill-me）
+- [ ] direction lock decisions recorded in compass（Plan 路径：Feedback log + deferred grill log；非 Plan：grill-me）
 - [ ] Draft compass + plans + `status.json` registered
-- [ ] product-manager / architect / writing-specialist invokes completed — 编辑 compass / plans / specs / **`<iteration-id>/` package**；**未**向 `{KNOWLEDGE_DIR}/` 新增；writing-specialist specs corpus hygiene done
+- [ ] product-manager / architect / writing-specialist invokes completed — 编辑 compass / plans / specs / **`<iteration-id>/` package**；**未**向 `{KNOWLEDGE_DIR}/` 新增
 - [ ] PM final lock: compass `status: locked`; Prepare gates pass (blocked plans documented)
-- [ ] Branch policy locked: `iteration_base_branch`, `spec_integration_branch`, and `target_branch` recorded in compass / `status.json`
-- [ ] **THEN**: git commit + push `iteration/<iteration-id>`
+- [ ] Branch policy locked: `iteration_base_branch` / `spec_integration_branch` / `target_branch` recorded in compass / `status.json`
+- [ ] **THEN**: commit + push `iteration/<iteration-id>`
 
 ## 6. Integration Branch
 
-**Precondition**: §5 complete — compass `status: locked`; specialist Tasks returned; Prepare gates confirmed.
-
-- Create `spec_integration_branch` (e.g. `iteration/<iteration-id>`) **from** the locked `iteration_base_branch`:
-
-```bash
-git fetch origin   # if needed
-git checkout -b <spec_integration_branch> <iteration_base_branch>
-# or: git checkout <spec_integration_branch>  if it already exists
-```
-
-- Register `iteration_base_branch`, `spec_integration_branch`, and `target_branch` in compass frontmatter **and** `{HARNESS_DIR}/status.json` root `metadata`
-- Commit all documents to the integration branch and push to remote
-
-**STOP** if `iteration_base_branch` or `target_branch` is missing. Ask the user or derive only from an already documented project/iteration policy; never silently substitute `main`.
+Per **`mstar-iteration` §2.3**：create `spec_integration_branch` from `iteration_base_branch`（`git fetch` → `git checkout -b <spec_integration_branch> <iteration_base_branch>`）；register `iteration_base_branch` / `spec_integration_branch` / `target_branch` in compass frontmatter **and** `status.json` metadata；commit docs；push。**STOP** if `iteration_base_branch` / `target_branch` missing — never default `main`/`master`.
 
 ---
 
-## 7. Phase 2–5: Execute → close → PR → merge-ready（auto-continue）
-
-**`pause` arg → command ends here.** Phase 1 locked + integration branch pushed；run `/iteration-drive` later to resume。
-
-**Default（no `pause`）→ auto-continue** into Phase 2→5。
-
-### Phase 2 boot（load before delegating）
-
-1. `mstar-iteration` → **§ Phase 2–5**（§2 Autonomous Execute、§3 close、§4 PR、§5 merge-ready）
-2. **`mstar-sdd`** — before first implement dispatch（per-task loop SSOT）
-3. `mstar-review-qc` — before first QC dispatch
-4. `mstar-compound` — before Phase 3 §3.2
-5. `mstar-branch-worktree` + **`mstar-iteration/references/phase-2-worktree-lease.md`** — control worktree + lease（§2.0 #5 未 waive）
-
-### Delegate to `iteration-drive` Phase 2→5
-
-Execute **`iteration-drive`** Phase 2–5 exactly：Phase 2 → **`mstar-iteration` §2**（§2.0 五道闸 → §2.6 push 纪律；SDD per-task；QC tri N=3 + QA）、Phase 3 → **§3** + `references/phase-3-iteration-close.md`、Phase 4/5 → **§4–§5** + `references/phase-4-5-pr-delivery.md`、Phase 5 helper discovery → `mstar-iteration/references/phase5-helper-discovery.md`。
-
-**Continuous execution（HARD）**：自 Phase 2 进入至 Phase 5 §5.5 exit，PM **连续编排**（**`mstar-iteration` §2.6**），进度汇报后下一条必须是 dispatch 或下一 phase 步骤，不向用户例行 yes/no check-in。合法 STOP 仅限：branch metadata 缺失、真冲突 / secrets / 不可逆范围缺口、Phase 5 多轮仍无法 merge-ready、用户本轮显式打断。
-
-**Assignment preflight**：同 §5（每次 implement/QC/QA 派发前校验；`mstar-harness` bin 未安装时静默跳过）。
+## 7. Phase 2–5（auto-continue）
 
-**Done = Phase 5 §5.5 exit checklist 全 `[x]`**（同 `iteration-drive`）。
+**`pause` arg → command ends here**（Phase 1 locked + integration pushed；run `/iteration-drive` later）。**Default（no `pause`）→ auto-continue**：execute **`iteration-drive`**（Phase 2 → **`mstar-iteration` §2**；Phase 3 → §3 + `references/phase-3-iteration-close.md`；Phase 4/5 → §4–§5 + `references/phase-4-5-pr-delivery.md`；Phase 5 helper discovery → `phase5-helper-discovery.md`）。Shared invariants / preflight / STOP → **`mstar-iteration/references/command-shared-invariants.md`**。
 
-**Then** report: iteration id, direction lock summary, plans completed, compound summary, PR link, merge-ready evidence（CI snapshot + review resolution + Greptile if applicable）。
+**Done = Phase 5 §5.5 exit checklist 全 `[x]`**（同 `iteration-drive`）。**Then** report: iteration id, direction lock summary, plans completed, compound summary, PR link, merge-ready evidence（CI snapshot + review resolution + Greptile if applicable）。
 
 PR merge itself may remain manual unless user authorized auto-merge.

package/harness-commands/pr-deep-review.md

@@ -0,0 +1,37 @@
+---
+name: pr-deep-review
+description: Use when asked to deeply review a pull request, branch, or diff before merge — deciding whether a change is safe to ship with evidence-backed findings, rather than a shallow "looks good" pass. Produces a `ship it` / `needs review` / `blocked` verdict. Also for a batch of sibling PRs. Do not use for self-checking a change you just authored.
+agent: project-manager
+input: "[pr|branch|scope] [full]"
+---
+
+# Deep PR Review
+
+Run a read-only, evidence-first deep review of a pull request, branch, or diff and decide whether it is safe to ship. Output: verdict + findings presented to the user; optional `gh pr comment` is a separate explicit step — never auto-approve or merge.
+
+**Read-only advisory.** The review does not enter the harness plan state machine (`Todo → InProgress → InReview → Done`). Reviewers never edit the worktree, never merge, and never approve-as-merge.
+
+## Boot
+
+1. `mstar-harness-core`
+2. `mstar-audit` → SKILL.md（common core）+ `references/pr-review.md`（`pr` variant 全量）
+3. `mstar-coding-behavior` (evidence discipline)
+4. `mstar-branch-worktree` (worktree isolation)
+5. `mstar-host` → active host reference (invoke capability for parallel subagents)
+
+## Routing（谁执行 review）
+
+| Context | Who runs the review |
+|---------|-------------------|
+| **Small PR / single pass** | PM dispatches a single `@code-reviewer` — review, then vet and synthesize the verdict |
+| **Batch of sibling PRs** | PM 按 PR 业务信息（业务域 / 变更面 / 技术栈）**平均分配**到四个席位：`@code-reviewer`（general）、`@fullstack-dev`、`@fullstack-dev-2`、`@frontend-dev` — 每个席位承载约 N/4 个 PR，摊薄同模型并发，降低 rate-limit。All worktrees created first, then all reviewers dispatched in one batch; each reviewer owns review + comment for its PRs only |
+
+All review seats (`code-reviewer` / `fullstack-dev` / `fullstack-dev-2` / `frontend-dev`) are **read-only** in this flow: never edit the reviewed worktree, never merge, never approve-as-merge. Implementer seats run in **Audit Mode** (shared contract → `mstar-roles` `references/_shared/leaf-executor-core.md`). PM dispatches; each reviewer executes the `pr` variant and returns findings + verdict to PM for consolidation.
+
+## Execute
+
+Execute **`mstar-audit`** § `pr` variant end to end（SKILL.md common core：recon + three-way attack & vet；variant detail：**`references/pr-review.md`** —— scope → guidance load → concern lenses → evidence → verdict → output）. Review is run in a dedicated worktree against a diff from the PR's **real base** — resolve the base per `references/pr-review.md` § Worktree isolation (never assume `main`).
+
+Review findings that need fixing can be turned into self-contained plans for the normal Prepare → Execute flow (reusing `mstar-audit` SKILL.md **`## Plan output (all variants)`** — same contract as the `pr` variant).
+
+Output verdict + findings to the user; `gh pr comment` is a separate explicit step — never auto-approve or merge.

package/harness-skills/{mstar-plan-artifacts → mstar-artifacts}/SKILL.md

@@ -1,11 +1,11 @@
 ---
-name: mstar-plan-artifacts
+name: mstar-artifacts
 description: "Morning Star plan harness artifacts — `{PLAN_DIR}` main plans and durable review summaries, `{SDD_DIR}/review/` ephemeral QC/QA bundles, `{KNOWLEDGE_DIR}` / `{ITERATION_DIR}` indexes, plus `{HARNESS_DIR}/status.json` (v2 root register) / `{WORKFLOW_DIR}/<id>/snapshot.json` (plan rows + leases) and `{PROJECT_DIR}/<id>/residuals.json` (residual register; severity SSOT, open/close lifecycle). Read when writing plans or QC/QA review bundles, maintaining knowledge/iteration indexes, reading or writing status/snapshot/register, or mapping QC severity to JSON. Required for `@project-manager` on status, residuals, and InReview/QC waves; `@qc-specialist*` before writing review bundle reports; `@qa-engineer` before closing R# when `QA gate: mandatory`. Verdict rules: leaf → `mstar-roles/references/qc-specialist/report-template.md`; PM → `mstar-review-qc`."
 ---
 
 ## Load order
 
-**Before first Read of this skill: Read `mstar-harness-core` (SKILL.md), and `mstar-plan-conventions` when path symbols matter.** Git branch / worktree / QC checkout → **`mstar-branch-worktree`**. On conflict, **`mstar-harness-core` wins**.
+**Before first Read of this skill: Read `mstar-harness-core` (SKILL.md), and `mstar-conventions` when path symbols matter.** Git branch / worktree / QC checkout → **`mstar-branch-worktree`**. On conflict, **`mstar-harness-core` wins**.
 
 ## Scope (plan directory artifacts)
 
@@ -18,7 +18,7 @@ description: "Morning Star plan harness artifacts — `{PLAN_DIR}` main plans an
 | Empty-repo `status.json` template | `templates/status.empty.json` (`templates/README.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`**.
+**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-conventions`**.
 
 ## `status.json`, workflow snapshots, and open residual (summary)
 

package/harness-skills/{mstar-plan-artifacts → mstar-artifacts}/references/knowledge-and-designs.md

@@ -2,7 +2,7 @@
 
 > **Load order（与其它 `mstar-*` skill 一致）**：依赖本 reference 维护知识库 / 迭代 compass / 规格挂接前，须已 Read **`mstar-harness-core`** skill（SKILL.md；仓库写操作与分支门禁见 **`mstar-branch-worktree`**）。冲突以 **`mstar-harness-core`** 为准。
 
-**路径符号（默认）**：`**{KNOWLEDGE_DIR}** = **{HARNESS_DIR}/knowledge/**`；`**{ITERATION_DIR}** = **{HARNESS_DIR}/iterations/**`。完整符号表见 `mstar-plan-conventions` SKILL.md「Harness 与 Plan 目录发现」。
+**路径符号（默认）**：`**{KNOWLEDGE_DIR}** = **{HARNESS_DIR}/knowledge/**`；`**{ITERATION_DIR}** = **{HARNESS_DIR}/iterations/**`。完整符号表见 `mstar-conventions` SKILL.md「Harness 与 Plan 目录发现」。
 
 本节将「用户文档」与「agent / 实施用知识」分开，**与具体业务仓库无关**；项目可在根目录 `AGENTS.md` 用一小段指向本 reference 或复述分界关键词，避免重复维护长文。
 
@@ -32,7 +32,7 @@
 
 ## `{SPECS_DIR}`（可选·长期规格）
 
-- `{SPECS_DIR}` 解析（非空即停）：`{HARNESS_DIR}/specs/` → `docs/specs/` → 仓库根 `specs/`；皆无或皆空则 init 创建 `{HARNESS_DIR}/specs/`。Legacy 只读：`{HARNESS_DIR}/designs/` 或根 `designs/` 非空时可用。细则 → `mstar-plan-conventions` SKILL.md「`{SPECS_DIR}` 解析」。
+- `{SPECS_DIR}` 解析（非空即停）：`{HARNESS_DIR}/specs/` → `docs/specs/` → 仓库根 `specs/`；皆无或皆空则 init 创建 `{HARNESS_DIR}/specs/`。Legacy 只读：`{HARNESS_DIR}/designs/` 或根 `designs/` 非空时可用。细则 → `mstar-conventions` SKILL.md「`{SPECS_DIR}` 解析」。
 - **放什么**：跨迭代有效、已锁定或待锁定的产品/API 规范、ADR、契约 — **iteration-start 主产出**（product/architect）。
 - **不放什么**：本迭代-only 探索（→ `<iteration-id>/guides/`）；迭代级 spec 草案（→ `<iteration-id>/specs/`）；实施踩坑原文（→ package 或 plan 素材，**close 时 compound 提升**）。
 - **索引**：非 trivial 树建议 `{SPECS_DIR}/README.md`；plan **`primary_spec` / `spec_refs`** 主要指向此处。
@@ -41,7 +41,7 @@
 
 - **新增 SSOT 默认路径**：**iteration-close** 时经 **`mstar-compound`** 写入；**iteration-start §1.6 禁止** product/architect 新增（见 **`mstar-iteration/references/iteration-artifact-boundaries.md`**）。
 - **必须**维护 `**{KNOWLEDGE_DIR}/README.md**` 作为**目录索引**：至少包含表格列 **Document（链接）**、**Source Plan（`plans[].id`）**、**Description**、**Status**（如 `Active` / `Superseded by implementation (<plan-id>)` / `Archived`）。
-- 可选：目录级 `**{KNOWLEDGE_DIR}/AGENTS.md**` 承载命名、维护节奏、与 `{SPECS_DIR}` 的权威边界（Nexus 模式）；harness 宽规则仍以 `mstar-plan-conventions` 与本 reference 为准。
+- 可选：目录级 `**{KNOWLEDGE_DIR}/AGENTS.md**` 承载命名、维护节奏、与 `{SPECS_DIR}` 的权威边界（Nexus 模式）；harness 宽规则仍以 `mstar-conventions` 与本 reference 为准。
 - 初始化启用知识库时：创建空表头的 `README.md`，随文档递增行。
 
 ## `{PROJECT_DIR}/<id>/references/`（可选·主题化研究语料）
@@ -50,7 +50,7 @@
 - **放什么**：**主题化研究** — surveys、epic roadmaps、第三方 notes，与拥有它的项目（`<id>`）绑定（compass ruling 1）。项目缺失用 `_default`（`{PROJECT_DIR}/_default/references/`）。
 - **不放什么**：冻结规格 / ADR（→ `{SPECS_DIR}/`）；compound 结晶的实现 SSOT（→ `{KNOWLEDGE_DIR}/`）；迭代内 ranking notes 与草稿 spec（→ `{ITERATION_DIR}/<id>/guides|specs/`）。研究**不**迁入这三处 corpora，三处内容也**不**迁入 `references/`。
 - **engine 职责边界**：`listProjectReferenceFiles(projectDir)` 只返回**文件名**（相对路径、`/` 分隔、code-unit 排序；跳过根级 `roadmap.md` / `residuals.json`；缺失目录 → `[]`）；**不**读文件正文，**不**做 markdown schema 校验 — 归属语义是本 reference（技能散文）契约，不是 engine 校验。
-- **历史 dump**：harness 根 `.mstar/references/` 已退役（dogfood 后缺省或仅一行 redirect）；当前路径由 `mstar-project-governance` Scope 表与 `mstar-plan-conventions` `references/artifact-storage-paths.md` 命名。
+- **历史 dump**：harness 根 `.mstar/references/` 已退役（dogfood 后缺省或仅一行 redirect）；当前路径由 `mstar-project-governance` Scope 表与 `mstar-conventions` `references/artifact-storage-paths.md` 命名。
 
 ## 文件命名
 
@@ -61,7 +61,7 @@
 ## 与 `status.json` 的链接
 
 - 某 plan 的**权威设计输入**在规格、迭代 compass 或（已有）知识库中时，在 `**plans[].metadata**` 中登记路径：`**primary_spec**` / `**spec_refs**` → 优先 **`{SPECS_DIR}/`**；`**iteration_compass**` / `**iteration_refs**` → **`{ITERATION_DIR}/`**；已有 **`{KNOWLEDGE_DIR}/`** 链接保留，但 **iteration-start 不得新增** knowledge 路径。
-- 执行方在 **implement 前**须按 metadata 读取这些文件，并与主 plan 核对；不得在未读链接文档的情况下**静默偏离**其中已写明的决策（若需偏离，先回写 knowledge 或 plan 并走 PM/architect 门禁）。
+- 执行方在 **implement 前**：先扫 `{KNOWLEDGE_DIR}/README.md` 索引（若存在），发现并阅读与当轮相关的 **Active** 行（发现式阅读，不要求通读全库）；再按 metadata 读取已登记路径；均与主 plan 核对；不得在未读链接文档的情况下**静默偏离**其中已写明的决策（若需偏离，先回写 knowledge 或 plan 并走 PM/architect 门禁）。
 
 ## 维护规则
 
@@ -69,7 +69,7 @@
    - **Specs（长期）**：`{SPECS_DIR}/` → spec 索引（若有）→ `plans[].metadata` 的 `primary_spec` / `spec_refs`
    - **迭代 package**：`{ITERATION_DIR}/<iteration-id>/guides|specs/` → `{ITERATION_DIR}/README.md`（目录一行）+ package README → `iteration_refs`
    - **Knowledge**：**`mstar-compound`** @ iteration-close（含 package **提升**）→ `{KNOWLEDGE_DIR}/README.md`
-2. **阅读**：开发类 agent 在开始编码前，**必须**阅读当前 plan 在 `metadata` 中指向的 knowledge 文档（若存在）；`@project-manager` 在 Assignment 中可再次点名路径。
+2. **阅读**：开发类 agent 在开始编码前，**先扫** `{KNOWLEDGE_DIR}/README.md` 索引（若存在），发现并阅读与当轮相关的 **Active** 行（不要求通读全库）；随后**必须**阅读当前 plan 在 `metadata` 中指向的 knowledge 文档（若存在）；`@project-manager` 在 Assignment 中可再次点名路径。
 3. **修订**：评审或规格变更若改动了 knowledge 文件，同步更新 README 中 **Status** 或 Description；版本迭代优先新文件名 `v<N+1>` 或保留旧版并标明 Superseded。
 4. **归档**：
    - **iteration-start（强制）**：`writing-specialist` §1.6 以 **`{SPECS_DIR}/` 全库卫生为主**；对**既有** `{KNOWLEDGE_DIR}/` 仅归档/错放纠正，**不**新增 knowledge。细则 → **`mstar-iteration/references/iteration-corpus-hygiene.md`**。
@@ -80,7 +80,7 @@
 
 - `**{SDD_DIR}/review/`**：偏 **审查流程临时证据**（review package、QC1/2/3、consolidated、QA），gitignored，可在 Done 后丢失。
 - `**主 plan gate summary**`：偏 **长期门禁决策摘要**（verdict、review range、R#、QA gate），随主 plan 追踪。
-- `**{PLAN_DIR}/residuals/<plan-id>/`**：偏 **仍 open 的 R# 长文补充**（与 project register `entries[<plan-id>]` 配套，canonical 见 `mstar-plan-conventions` **SKILL.md** 开篇）；见下文「open residual 散文详情」。
+- `**{PLAN_DIR}/residuals/<plan-id>/`**：偏 **仍 open 的 R# 长文补充**（与 project register `entries[<plan-id>]` 配套，canonical 见 `mstar-conventions` **SKILL.md** 开篇）；见下文「open residual 散文详情」。
 - `**{KNOWLEDGE_DIR}/**`：偏 **可复用的实现向设计上下文**（架构细则、决策、分析），可被后续 plan 或多会话反复引用。
 - `**{ITERATION_DIR}/**`：偏 **某一迭代/版本** 的 package（compass + guides/specs），通常按版本索引而非按单 plan 长期复用。
 - `**{PROJECT_DIR}/<id>/references/**`：偏 **主题化研究**（surveys、epic 备注、第三方 notes），随项目绑定；与 specs / knowledge / iteration guides 职责不混写。
@@ -101,7 +101,7 @@
 | `**{ITERATION_DIR}/**`            | 迭代 package（`<id>/delivery-compass.md` 等）；**不**替代 `{KNOWLEDGE_DIR}` 中的跨版本 SSOT |
 
 
-**文件命名（推荐）**：`<finding-id>-<short-label>.md`，其中 `**finding-id`** 与该条在 register（`projects/<id>/residuals.json` → `entries[<plan-id>]`，见 `mstar-plan-conventions` **SKILL.md** 开篇）中的 `**id`**（如 `R1`）或团队约定的 `**td-*` 等技术债编号**一致，便于 `detail_doc` 与目录互查。
+**文件命名（推荐）**：`<finding-id>-<short-label>.md`，其中 `**finding-id`** 与该条在 register（`projects/<id>/residuals.json` → `entries[<plan-id>]`，见 `mstar-conventions` **SKILL.md** 开篇）中的 `**id`**（如 `R1`）或团队约定的 `**td-*` 等技术债编号**一致，便于 `detail_doc` 与目录互查。
 
 **登记**：在对应 open 条目中填写可选 `**detail_doc`**（仓库内相对路径，常形如 `**{PLAN_DIR}/residuals/<plan-id>/R1-….md**`）。**禁止**只写散文、不在 register 中登记 open 行。