@mstar-harness/dsh 2.1.1

package/harness-skills/mstar-iteration/references/phase-4-5-pr-delivery.md

@@ -0,0 +1,84 @@
+# Phase 4 & 5: PR delivery + merge-ready loop
+
+> Loaded by `mstar-iteration` SKILL.md when entering Phase 4/5. **Read `mstar-harness-core` first.** 进入前置：Phase 3 §3.5 exit 全 `[x]`（Phase 4）；Phase 4 PR 已创建（Phase 5）。
+
+## Phase 4: PR delivery（开 PR）
+
+**Precondition**: Phase 3 §3.5 exit 全 `[x]`；close commit 已 push 到 `spec_integration_branch`。
+
+1. 打印 **`## Phase 4: PR delivery`**
+2. Resolve target：`metadata.target_branch`（compass frontmatter 镜像）；缺失 → **STOP**，问用户
+3. 创建 PR：`spec_integration_branch` → `target_branch`
+4. 记录 PR URL / number（Phase 5 会话 SSOT）
+5. **Immediately** 进入 **Phase 5** — **Phase 4 exit ≠ 迭代交付完成**
+
+---
+
+## Phase 5: PR merge-ready loop
+
+**Precondition**: Phase 4 PR 已创建且 head = `spec_integration_branch`。
+
+**Loop 理念**（mstar SSOT）：PR 开完后进入 **验证—修复—再验证** 循环，直至 PR 可合并。与 Phase 2 per-plan loop 类似，但对象是 **PR 级** merge 门禁（CI、review、冲突），不是 plan 实现。
+
+### 5.0 Phase boundary
+
+- Phase 5 在 PR head（`spec_integration_branch`）上 push 修复；**禁止**另开替代分支
+- **Checkout / worktree（HARD）**：Phase 5 是 PR 级 **hotfix** loop，**不是** Phase 2 plan 实现。修复直接在 **control worktree**（已检出 `spec_integration_branch` 的 checkout）上编辑、commit、再按 §5.1a push。**禁止**为 Phase 5 另开 feature / fix worktree；**禁止**把 Phase 2「control 禁止产品编辑 / 须 feature worktree」套用到 Phase 5。另开 worktree 浪费时间、磁盘与计算，与 Phase 5 快速收敛 CI/review 的目标相悖。
+- 产品代码修复 → PM **dispatch** dev/ops（`mstar-dispatch-gates`）；Assignment **`Worktree path`** / cwd = control（`metadata.control_worktree_path` 或当前已在集成分支上的 checkout）；PM 线程不代写实现
+- 禁止为「让 CI 变绿」而改 workflow，除非用户明确授权
+- **Push cadence** → **§5.1a**（本地可提前修；**禁止**在 CI / AI review 波次未结束时 push）
+
+### 5.1a Push cadence（HARD — 防打断 CI / AI review）
+
+发现 CI 失败或 review 问题时，**允许本地提前修**（含 dispatch implement/ops、落盘 commit），但 **`git push`（更新 PR head）必须等上一波次跑完**。
+
+| 允许 | 禁止 |
+|------|------|
+| CI/review **进行中**就开始本地诊断与修复 | 当前 head 上仍有 **CI queued/in_progress**，或 **AI review 波次**（Bugbot / Greptile / 等价 bot）未结束时 **push** |
+| CI **全部结束后**出现新的 review 评论 → 继续本地修，批完再 push | 为「抢时间」在 CI 仍在跑时 push（会取消/孤儿化进行中的 CI 与 **AI reviews**，浪费 token 且无完整结果） |
+| 一批本地修复 **合并为一次 push**（本 head 波次 settled 后） | 同一波次未 settled 就连续多次 push |
+
+**Push gate（每次 push 前必须核对）**：
+
+1. 当前 PR head 的 **required CI**（及已启动的检查）均已 **completed**（success / failure / cancelled — 不得仍为 queued / in_progress）
+2. 附着在该 head 的 **AI / bot review 波次**已跑完（无进行中的 review job；若宿主无法探测 job，则至少等 CI settled **且** review 评论不再增长一小段稳定窗口后再 push）
+3. 仅当 **1–2 满足** 且本地仍有未推送修复时，才 **push 一次**
+4. Push 后：等 **新 head** 的 CI + reviews 全部跑完 → 再决定下一轮本地修 / push
+
+**顺序记忆**：`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.
+
+### 5.1 Loop（repeat until §5.5 exit）
+
+1. **Status** — PR mergeable？required CI？unresolved review threads？**任一 CI/AI review 是否仍在跑？**
+2. **Merge conflicts** — blocking 则在 integration 分支**本地**解决；**仅当 §5.1a push gate 满足时**再 push（意图冲突 → **Blocked**）
+3. **Reviews** — fetch unresolved threads；triage；dispatch **本地**修复（可在上一波次仍在跑时开工）
+4. **CI** — 失败项在 PR 范围内**本地**修复（可提前开工）；**不**在 CI 仍在跑时 push
+5. **Push** — 仅当 §5.1a 满足：无 in-flight CI，上一波 CI **与** reviews 均已跑完 → **一次** push 本批修复
+6. **Review fix hygiene**（每次因 review 而 push 后）：
+   - 在同 thread **comment**（改动 + 验证）
+   - **Resolve** when addressed
+7. Return to step 1（CI 结束后若出现 **新** reviews → 继续本地修，再等 idle 后 push）
+
+**Optional host helpers（command 层发现；非 `mstar-*` load order）**：
+
+| Priority | Helper | When |
+|----------|--------|------|
+| 1 | `babysit` or any `*-babysit` skill（first readable `SKILL.md`） | **Default prefer** — CI green + reviews resolved loop |
+| 2 | `greploop` | **Optional** — only when the **repo** uses Greptile / has `greploop` available; then run for Greptile **5/5** in addition to babysit/`*-babysit` (or fallback) gates |
+| 3 | neither | Command fallback = babysit-equivalent CI + reviews gates |
+
+When both babysit/`*-babysit` and greploop apply: **babysit/`*-babysit` first**（CI + reviews），then optional greploop for Greptile score. Discovery paths → host `commands/iteration-drive` / `iteration-loop` Phase 5.
+
+### 5.2 Phase 5 exit checklist（迭代交付完成）
+
+打印 **`## Phase 5 exit checklist`**；全 `[x]` 后方可宣称 **迭代交付完成**：
+
+- [ ] PR mergeable（无 blocking merge conflicts）
+- [ ] All **required** CI checks green on latest head
+- [ ] All review threads **resolved**（或用户书面 waive 特定 thread）
+- [ ] §5.1 review comment + resolve 已覆盖本轮所有 addressed feedback
+- [ ] Host todo `phase-5-pr-merge-ready` 可勾选
+
+PR **merge** 本身可仍由用户手动执行，除非 Assignment 明确授权 auto-merge。

package/harness-skills/mstar-iteration/references/phase5-helper-discovery.md

@@ -0,0 +1,24 @@
+# Phase 5 helper skill discovery（babysit / greploop）
+
+> Loaded by host `commands/iteration-drive` / `iteration-loop`（Phase 5 §5.0）before the first merge-ready loop pass. Search for optional **non-`mstar-*`** helper skills；first readable `SKILL.md` wins per name. Does **not** enter `mstar-*` load order.
+
+## Search paths（示例，按宿主扩展）
+
+| Skill | Search paths |
+|-------|--------------|
+| `babysit` / `*-babysit` | `skills/babysit/SKILL.md`；`skills/*-babysit/SKILL.md`；`~/.cursor/skills-cursor/babysit/SKILL.md`；`~/.cursor/skills-cursor/*-babysit/SKILL.md`；`~/.agents/skills/babysit/SKILL.md`；`~/.agents/skills/*-babysit/SKILL.md` |
+| `greploop`（optional） | `skills/greploop/SKILL.md`；`~/.cursor/skills-cursor/greploop/SKILL.md`；`~/.agents/skills/greploop/SKILL.md`；Codex plugin `skills/greploop/` — **only adopt when the repo uses Greptile / has greploop** |
+
+## Mode selection（babysit-first）
+
+| 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` | —（command 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**（串行）。Do **not** prefer greploop over babysit。
+
+**No greploop / repo without Greptile**: skip greploop entirely — babysit/`*-babysit` or fallback only。
+
+**All modes** share the §5.2 exit checklist（CI + reviews + mergeable；Greptile 5/5 only when greploop mode ran or repo shows a Greptile score）。

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

@@ -0,0 +1,112 @@
+---
+name: mstar-phase-gates
+description: "Morning Star Spec-Driven 双阶段门禁：Prepare（`specify → clarify → plan`）、Execute（`plan(locked) → tasks → implement`；多 task 默认 `Execution mode: sdd`）。覆盖意图门禁、长期目标优先、分批 roadmap 强制落盘、clarify 纪律、hotfix 压缩路径、可验证编辑、Phase Gate 最小证据。Read when judging Prepare/Execute gates, before first implement dispatch, when product/architect enter Prepare, or to justify not skipping plan/clarify. `@project-manager` 每轮非 hotfix 必读；`@product-manager`/`@architect` 锁规格/plan 必读 Prepare；实现角色读 Execute + hotfix 例外。`quick` 禁豁免规则在 `mstar-harness-core`。"
+---
+
+## Load order（必读顺序）
+
+**首次 Read 本 skill 前：必须先 Read `mstar-harness-core`（SKILL.md）。** `{PLAN_DIR}` / plan 文件落盘见 **`mstar-plan-conventions`**。冲突时 **以 `mstar-harness-core` 为准**。
+
+## Spec-Driven 双阶段门禁（非热修强制）
+
+### A. Prepare：`specify → clarify → plan`
+
+- **`specify`** — 问题陈述、用户价值、范围/非目标、DoD 草案。
+- **`clarify`** — 关键歧义清单与结论；高影响歧义必须收敛，否则 `Blocked`。
+  - **意图核对（Intent gate）**：区分**用户字面表述**与**待解决的真正问题**；手段与目标混淆须在此收敛。
+  - **结构化澄清**：宿主提供 `question` 工具时优先使用；否则用结构化正文选项。宿主细节在各自的 `mstar-host` skill。
+  - **`clarify` 核心纪律（Prepare）**：对 plan/方案的**每个方面**持续核对，直到与用户达成**共享理解**；沿**设计决策树**逐枝下行，**一次只收敛一个决策点**及其依赖，再进入下一枝。
+    1. **能查库则查库**：若问题可通过探索代码库（实现、配置、`{SPECS_DIR}`、`{KNOWLEDGE_DIR}`、`{ITERATION_DIR}` 等）得到答案，**先探索、不向用户提问**。
+    2. **每问带推荐**：每个仍需用户确认的问题，须给出**推荐答案**（及简短理由），便于快速对齐。
+    3. **收口摘要**：`clarify` 结束前列出：已决事项、仍 open 的假设、对 `plan` 的约束。
+- **`plan`** — 技术方案、长期目标状态、模块边界/接口契约、风险与回滚点、验证计划。
+  - **意图门禁**：锁 plan 前须能书面写清**真实目标 / 成功判据 / 非目标**三项；否则 Prepare 未通过。
+  - **长期方案优先**：默认先设计目标状态，再裁剪本轮可交付切片；不得以“临时方案 / 混合方案 / 以后再说”替代目标设计。
+  - **Durable Roadmap Gate**：若本轮只做部分范围，plan 必须写明 roadmap（批次、依赖、暂缓项、owner/触发条件、最终完成定义）。只有一句“后续再做 / next plan”视为未通过 plan gate。
+
+### B. Execute：`plan(locked) → tasks → implement`
+
+- **`plan(locked)`** — 冻结基线；实现中出现新约束时**先回写 plan 再继续**。
+- **`tasks`** — 含依赖顺序、并行标记、完成判据；每任务可追踪到 plan、roadmap 批次与验收标准。
+  - **并行标签**：≥2 条实现轨同时分派 → `Dispatch mode: parallel independent tracks`；同仓可写并发 → `Worktree isolation: required`（清单 **`mstar-branch-worktree`** → **`references/parallel-writable-pre-dispatch.md`**）。
+- **`implement`** — 按 tasks 顺序执行；多 task plan **默认** `Execution mode: sdd`（`mstar-sdd`）；hotfix 可 `inline`。完成进入 `InReview`；遵循 **`mstar-coding-behavior`**。
+
+### 可验证编辑与上下文纪律
+
+- **读后再改**：修改文件前以磁盘内容为准重读（`Read`/等价工具）。
+- **小步应用**：Patch 失败**禁止**在同一过时锚点连试；重读、缩小变更单元或拆步。
+- **多文件改动**：逐项核对路径与引用，避免未验证的批量替换。
+
+### Hotfix 例外
+
+压缩路径与事后补记见下文 **§ Hotfix 例外**（Playbook 末尾）。
+
+## Phase Gate Playbook
+
+执行动作与最小产物见上文 **§ Spec-Driven 双阶段门禁**。本节仅 **Playbook 补充**（不重复 Prepare/Execute 长文）。
+
+### Execute 补充（Playbook 专有）
+
+- **`plan locked`**
+  - 最小动作：在 plan 或 notes 记录当前锁定版本（日期或 hash）。
+  - **Plan 质量门**（新 plan / 大改）：无 placeholder（`...`、`TBD`、`etc.`）；含 **Global Constraints** 与 per-task **Interfaces**；PM self-review 三问（每 task 可独立验证？依赖顺序清晰？无隐含假设？）— 见 `mstar-plan-artifacts/templates/plan.main.md` + **`mstar-plan-artifacts/references/plan-quality-bar.md`**（自包含/验证门/STOP 条件/drift check/done criteria）。
+- **`implement`**
+  - 最小产物：实现 diff、自检证据、回报与 handoff；行为准则 → **`mstar-coding-behavior`**；编辑纪律 → 上文「可验证编辑与上下文纪律」。
+  - **知识库 / 迭代 compass**：若 `plans[].metadata` 登记了 `primary_spec` / `spec_refs` / `iteration_compass` / `iteration_refs`，**开工前**须阅读并在回报中说明已对齐 → **`mstar-plan-conventions`** · **`mstar-plan-artifacts/references/knowledge-and-designs.md`**。
+
+## 角色职责
+
+- `@project-manager`
+  - 负责门禁判定与 Assignment 中的 `Phase Gate Checklist`。
+  - 在 `Status Update` 汇报当前 gate 状态。
+- 开发角色（`@frontend-dev` / `@fullstack-dev` / `@fullstack-dev-2`）
+  - 仅在 Execute gate 放行后开始实现。
+  - 发现新约束时先回报并请求回写 plan。
+- `@qa-engineer` — when **`QA gate: mandatory`**, L4 per `mstar-roles/references/qa-engineer/acceptance-gate.md`; `pm-acceptance` is PM-only (`qa-trigger-matrix.md`).
+
+## 迭代级活动
+
+per-plan 门禁通过后，PM 在**迭代层面**管理以下活动（不计入 per-plan gate）：
+
+- **迭代启动**（`mstar-iteration` § Phase 1）：锁定迭代范围、**显式 branch policy**（`iteration_base_branch` / `target_branch`）、产出 compass。
+- **迭代驱动**（`mstar-iteration` § Phase 2 Autonomous Execute）：per-plan 派发循环（分支→实现→QC→**QA gate**→Done→合并），跨 plan 进度追踪，更新 compass 中各 plan 状态。
+- **迭代收口**（`mstar-iteration` § Phase 3 iteration-close）：迭代内所有 plan Done 后，执行一轮知识结晶（`mstar-compound`）沉淀迭代经验，更新 roadmap，标记迭代完成。
+
+per-plan Done 是 per-plan 的闭环终点；compound 是迭代级收口活动，不影响 per-plan 状态判定。
+
+> **Engine check (when available):** run `mstar iteration gate --status <status.json> --compass <delivery-compass.md>` (or `import { evaluatePhaseGate } from "@mstar-harness/engine"` in a host hook) to evaluate the iteration phase-transition gate (Phase 2 → 3 → 4) when iteration-level activities above are reached — per-plan Prepare/Execute gate judgment stays prompt. On `fail` (gate-blocking violations) -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
+
+## Plan 目录与审查证据（启用 `{PLAN_DIR}` 时）
+
+- 进入 `InReview` 后，QC/QA 原始过程报告默认落入 `{SDD_DIR}/review/`（**SDD 默认 tri** `qc1`…`qc-consolidated`；**inline** 单席 `qc.md`）。**fix 后默认 targeted re-review**。SDD per-task review 在 implement 波次内完成（`mstar-sdd` task reviewer）。PM 将 durable gate summary 回写主 plan / `status.json`，而不是把 raw reports 作为默认 git 产物。
+- 非阻断项与后续技术债：PM 汇总后写入 `{HARNESS_DIR}/status.json` 根级 `residual_findings[<plan-id>]`（**open**，与 `plans` 平级；canonical 见 **`mstar-plan-artifacts` SKILL.md**）；关闭后迁入 `{HARNESS_DIR}/archived/residuals/<plan-id>.json`，与 `mstar-review-qc` 一致。每条 **`severity`** 遵守 **`mstar-plan-artifacts/references/status-and-residuals.md`**「Residual findings：severity（SSOT，机器字段）」。
+
+## 快速判定（PM）
+
+1. `specify` 是否完成？
+2. `clarify` 是否完成（高影响歧义是否收敛）？
+3. 意图门禁是否满足（真实目标 / 成功判据 / 非目标已写明）？
+4. `plan` 是否完成并可引用？
+5. 若 plan 涉及 UI 工作：`DESIGN.md` 是否存在且满足声明的 completeness level（见 `mstar-design-md`）？
+6. 若分批/暂缓/临时绕行，roadmap 是否落在 plan/status 中，而不是只在对话里？
+7. `tasks` 是否完成？
+8. Assignment 是否含 **`Task category`**（实现类任务）并与 Owner 一致？
+9. 若中途出现 plan drift，是否先回写再继续？
+10. 实现说明中是否体现"最小耐久切片 + 手术式改动 + 可验证检查"？
+
+**任一项为「否」时，`Gate decision` 必须是 `blocked`**。
+
+> 迭代级活动（compound / iteration-close）见 `mstar-iteration`；不属于 per-plan gate 判定项。
+
+## Hotfix 例外
+
+- 允许路径：`specify(min) -> plan(min) -> implement`
+- 必须补记：
+  - 事后 `clarify/RCA`
+  - 触发条件、影响范围、修复与回滚摘要
+
+## 最小证据要求
+
+- Prepare 阶段证据：问题定义、歧义结论、plan 链接。
+- Execute 阶段证据：tasks 清单、实现自检、审查/验证证据。
+- 结论证据：不得仅写"done"，必须可复核（命令、输出、截图或复现步骤）。

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

@@ -0,0 +1,46 @@
+---
+name: mstar-plan-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, Done compaction, plus `{HARNESS_DIR}/status.json` and root `residual_findings` (severity SSOT, open/archived lifecycle, `notes.json`). Read when writing plans or QC/QA review bundles, maintaining knowledge/iteration indexes, reading or writing `status.json` / R#, Done compaction, 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`. Paths in `mstar-plan-conventions`."
+---
+
+## 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**.
+
+## Scope (plan directory artifacts)
+
+| Topic | See |
+|-------|-----|
+| Main plan, review bundle naming, durable summaries, QC waves, residual and plan index order | `references/plan-files-and-reports.md` |
+| Plan template (Global Constraints, Interfaces) | `templates/plan.main.md` |
+| knowledge / iterations / specs boundaries and indexes | `references/knowledge-and-designs.md` |
+| 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`) |
+
+**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`**.
+
+## `status.json` and open residual (summary)
+
+- **`{HARNESS_DIR}/status.json`**: `plans[]` row status + root **`residual_findings[<plan-id>]`** (open list **SSOT**).
+- **Canonical**: register new findings only at root `residual_findings`; **`metadata.residual_findings`** is legacy read-only — **do not** dual-write.
+
+> **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.
+
+- **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.
+
+- **`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.
+
+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`).

package/harness-skills/mstar-plan-artifacts/references/done-compaction.md

@@ -0,0 +1,88 @@
+# Done 计划行冷快照与 status.json 瘦身（Morning Star）
+
+> **Load order（与其它 `mstar-*` skill 一致）**：依赖本 reference 做 Done 瘦身 / 归档前，须已 Read **`mstar-harness-core`** skill（SKILL.md）与 **`mstar-plan-conventions`** SKILL.md（plan SSOT 总线）。合并与分支事实仍受 **`mstar-branch-worktree`** 约束。
+
+## 可选：`Done` 计划行冷快照（`{HARNESS_DIR}/archived/plans/`）
+
+**背景**：多条 `Done` 的 `plans[]` 行常带大块 `metadata`（`gates`、QC 摘要、`tests`、`commits`、长 `scope`/`description`），`status.json` 会无限膨胀；而**根级 `residual_findings` 中的 open 项**（canonical 见 `mstar-plan-artifacts` **SKILL.md** 开篇）宜保持有界（已关闭项应迁出至 **`{HARNESS_DIR}/archived/residuals/`**，见 `mstar-plan-artifacts/references/status-and-residuals.md`）。
+
+**定位**：**`{HARNESS_DIR}/status.json`** 仍为**当前执行**的 SSOT（非终态计划、根 `metadata`、**open** 的 `residual_findings`）。本节为**可选**做法：在**不破坏可到达性**（快照文件须提交进仓库）的前提下给热文件瘦身。
+
+**冷存储路径**：`{HARNESS_DIR}/archived/plans/<plan-id>.json`
+
+**快照内容**：将该 plan 标为 `Done` 时，**完整的**对应 `plans[]` 元素（含当时全部 `metadata`），供审计与 handoff。
+
+**与 residual 归档的关系**：**`{HARNESS_DIR}/archived/residuals/<plan-id>.json`** 存**已关闭 finding 行**；**`{HARNESS_DIR}/archived/plans/<plan-id>.json`** 存**计划行快照**。不要把计划快照当作 **open** `residual_findings` 的第二份权威来源。
+
+## Profile A（默认）— 热文件保留瘦 `Done` 行
+
+- **最小集**（机器导航够用）：**`id`**、**`status`**（`Done`）、**`file`**（主 plan 路径）、**`metadata`** 仅含：
+  - **`archived_record`**：相对 **`{HARNESS_DIR}`** 的路径，例如 `archived/plans/<plan-id>.json`（冷快照内为**完整**当时 `plans[]` 元素，含臃肿字段）
+  - 若该 `plan-id` 在 **open 列表**（根级 **`residual_findings`**；若仅存 legacy 侧则同口径）中仍有 **open** 行，在 **`metadata`** 内保留 **`residual_summary`**（语义见 `status-and-residuals.md` **`residual_summary`（可选）** 小节）
+- **可选**（人类扫表友好，非必须）：**`title`** 一行、**`done_at`**；勿把长叙述塞回热行——放进 **`{HARNESS_DIR}/notes.json`**、主 plan gate summary、archived residuals，或依赖冷快照。
+- 一旦快照已写入，热行**不得**再承载完整 `gates`、`qc_status`、`tests`、`commits`、长 `description`/`scope` 等；**以 `archived_record` 指向文件为准**。
+- 单条 **`plans[].notes`** 字符串若仍在用，保持**极短**（如指向主 plan gate summary 或 R#）；**不要**重复 QC/QA 原始报告大段原文。
+- **可选索引**：`{HARNESS_DIR}/archived/plans/_index.json` — `plan-id` → 相对路径，便于不依赖 glob 的工具。
+- **可选滚动保留**：进一步缩小 `plans[]` 时，可只在热文件中保留**最近窗口**的瘦 `Done` 行，更旧 id 仅出现在 `_index.json` 与快照文件中；若采用，须在项目 `AGENTS.md` 中写明，并检查依赖「热文件中必有全部历史 id」的脚本。
+
+## Profile B（可选）— 热文件不保留任何 `Done` 行（统一压缩）
+
+- **Done 快照路径**：`{HARNESS_DIR}/archived/plans/<plan-id>.json` — 单个 **`plans[]` 行对象**（含当时全部 `metadata`）；**不是**包装层，勿再套 `plan_id` / `snapshot` 外壳。
+- **Done 目录路径**：`{HARNESS_DIR}/archived/plans-done.json` — **仅** plan id 列表（见下）；**勿**使用 `_index.json`、对象数组目录或其它并行索引。
+- **`plans-done.json` schema（唯一权威；不得扩展）**：
+
+```json
+{
+  "plans": ["01-data-infrastructure", "02-auth-refactor"]
+}
+```
+
+  - 根对象**只允许**键 **`plans`**（字符串数组）。
+  - 数组元素为 **`plans[].id`**（= `archived/plans/<plan-id>.json` 的 basename；通常亦为主 plan `.md` 去扩展名）。
+  - 标题、`done_at`、主 plan 路径、`archived_record` 等**只**存在于 `archived/plans/<plan-id>.json` 快照内。
+  - 初始化：`mstar-plan-artifacts/templates/plans-done.empty.json` → `{ "plans": [] }`。
+- **热文件行为**：`status.json.plans[]` 只保留非 `Done`；`Done` 后从热文件**删除**该行。
+- **读取约定**：活跃计划 → `status.json`；历史 Done id 列表 → `plans-done.json`.`plans`；单条详情 → `archived/plans/<plan-id>.json`（路径由 id 拼接，**不**读目录内嵌路径字段）。
+
+## 原子更新约束（Profile A / B 通用）
+
+- 将计划标记为 `Done` 时，冷快照写入与 `status.json` 更新应在**同一变更集**完成（或紧随合并后一次性完成）。
+- 采用 **Profile B** 时，必须在同一变更集中同时完成：  
+  1) 写入/更新 `archived/plans/<plan-id>.json`，  
+  2) 将 `<plan-id>` 追加进 `archived/plans-done.json` 的 **`plans`** 数组（去重；勿写额外字段），  
+  3) 从 `status.json.plans[]` 删除该 `Done` 行。  
+- 若无法满足以上三步，视为未完成 `Done` 收口，不应宣称已完成压缩迁移。
+
+## 采纳说明
+
+- 未写快照、热文件中仍保留完整 `Done` 行在历史仓库里依然可读；但新落地时建议先确定并固定使用 **Profile A** 或 **Profile B**，避免同仓混跑。
+- 从 Profile A 迁到 Profile B 前，先检查依赖 `status.json.plans[]` 扫描全部历史 `Done` 的脚本与流程，并改为读取 `archived/plans-done.json`.`plans`。
+- 若仓库 `plans-done.json` 仍为非 `{ "plans": [...] }` 形态（例如对象数组、顶层 `entries`/`catalog`），**整文件改写**为仅 id 列表；勿保留兼容层或双写富字段。
+
+## 仓库级采用声明模板（贴到项目 `AGENTS.md`）
+
+### Template A（默认，保留瘦 Done 行）
+
+```markdown
+### Plan compaction profile (this repository)
+
+This repository uses **Profile A** from the Morning Star `mstar-plan-artifacts` skill (`references/done-compaction.md`).
+
+- `status.json.plans[]` keeps active plans and may keep **slim `Done` rows**.
+- `archived/plans/<plan-id>.json` is used as cold snapshot when available.
+- Historical tooling may read both `status.json.plans[]` and `archived/plans/`.
+```
+
+### Template B（统一压缩，不保留 Done 行）
+
+```markdown
+### Plan compaction profile (this repository)
+
+This repository uses **Profile B** from the Morning Star `mstar-plan-artifacts` skill (`references/done-compaction.md`).
+
+- `status.json.plans[]` keeps **non-`Done`** plans only.
+- Every `Done` plan MUST be represented in:
+  - `archived/plans/<plan-id>.json` (full snapshot), and
+  - `archived/plans-done.json` (`{ "plans": ["<plan-id>", ...] }` only).
+- Historical `Done` discovery MUST read `archived/plans-done.json` **`plans`**, not `status.json.plans[]`; per-plan detail from `archived/plans/<plan-id>.json`.
+```

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

@@ -0,0 +1,100 @@
+# `{KNOWLEDGE_DIR}`、`{ITERATION_DIR}` 与 `{SPECS_DIR}` / `residuals/` 散文（Morning Star）
+
+> **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 目录发现」。
+
+本节将「用户文档」与「agent / 实施用知识」分开，**与具体业务仓库无关**；项目可在根目录 `AGENTS.md` 用一小段指向本 reference 或复述分界关键词，避免重复维护长文。
+
+## 与公开文档目录的分工（典型为 `docs/`）
+
+
+| 区域 | 典型内容 | 受众 / 权威 |
+|------|----------|-------------|
+| **`docs/`**（或项目约定的用户文档根） | 安装/quickstart、稳定架构概览、贡献指南、对外 API 说明 | 人类贡献者与终端用户；clone 后应可读 |
+| **`{SPECS_DIR}`**（可选） | 冻结 v1-spec、ADR、program roadmap — **跨迭代长期权威** | 产品/API 规范性最高权威；**iteration-start** 由 product/architect 主写 |
+| **`{ITERATION_DIR}`**（可选） | **`<iteration-id>/` package**（`delivery-compass.md` + `guides/`、`specs/`） | Agent handoff；迭代级草稿；close 时 compound **提升** → knowledge |
+| **`{KNOWLEDGE_DIR}`**（可选） | 实现细节 SSOT、架构细则、契约说明、跨版本 tracker — **经 `mstar-compound` 结晶** | Agent handoff；**不**在 iteration-start 由 product/architect 新增 |
+| **`{PLAN_DIR}/`** | 单 plan 主文件、durable gate summary、可选 `residuals/` | 计划执行与长期决策留档 |
+
+
+**不应**放入 `docs/` 的内容：迭代 compass 正文、作为**特定 plan 输入/输出**的评审结论、实施笔记、未稳定规格草案、QC/QA 原始过程报告 —— 分别落 `{ITERATION_DIR}`、`{KNOWLEDGE_DIR}`、`{SPECS_DIR}` 或 `{SDD_DIR}/review/`；长期 gate 摘要回写主 plan。
+
+## `{ITERATION_DIR}`（可选·迭代/版本级 package）
+
+- **物理路径**：`**{ITERATION_DIR}/**`（推荐布局下常为 `**.mstar/iterations/**`，与 `{KNOWLEDGE_DIR}`、`{PLAN_DIR}` 并列；legacy 项目可继续为 `.agents/iterations/`）。
+- **放什么**：**`<iteration-id>/` package** — `delivery-compass.md`（迭代状态 SSOT）；`guides/`（探索、过程）；`specs/`（迭代级规格草案）；可选 package `README.md`；遗留规划快照。
+- **不放什么**：已锁定的仓库级规范（→ **`{SPECS_DIR}/`**）；已提升的跨迭代实施 SSOT（→ **`{KNOWLEDGE_DIR}/`**，经 compound）；单 plan QC/QA 原始报告（→ `{SDD_DIR}/review/`）。
+- **索引**：`**{ITERATION_DIR}/README.md**` **一行 = 一次迭代**（指向 `<iteration-id>/`）；`<iteration-id>/README.md` 登记 package 内文档（Documents 单表）。
+- **维护**：`@product-manager` / `@architect` 起草 package；`**@project-manager**` 维护索引与 metadata；**iteration-close** 时 **`mstar-compound`** 盘点 package 并**提升**至 `{KNOWLEDGE_DIR}/`。
+- **Compass 路径**：canonical `{ITERATION_DIR}/<iteration-id>/delivery-compass.md`；legacy flat `{ITERATION_DIR}/<iteration-id>-delivery-compass.md` 仅兼容读。
+
+## `{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}` 解析」。
+- **放什么**：跨迭代有效、已锁定或待锁定的产品/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`** 主要指向此处。
+
+## `{KNOWLEDGE_DIR}`（可选·实施知识库）
+
+- **新增 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 为准。
+- 初始化启用知识库时：创建空表头的 `README.md`，随文档递增行。
+
+## 文件命名
+
+- 推荐：`<topic>-<qualifier>-v<N>.md`（例：`sync-contract-gap-analysis-v1.md`），便于同主题多版共存。
+- 避免与主 plan 文件名混淆：主 plan 仍建议 `<plan-id>-<plan-name>.md` 且放在 `{PLAN_DIR}/` 根下，而非塞进 `{KNOWLEDGE_DIR}` 根（除非团队明确约定）。
+- 迭代 compass 放在 `{ITERATION_DIR}/<iteration-id>/delivery-compass.md`，**不要**与 `{KNOWLEDGE_DIR}` 中跨版本 SSOT 混放同一命名空间；**不要**新写根目录 flat `*-delivery-compass.md`。
+
+## 与 `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 门禁）。
+
+## 维护规则
+
+1. **新增**：
+   - **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 中可再次点名路径。
+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`**。
+   - **其它时机**：当文档内容已完全反映到已合并代码中、且非 iteration-start 扫库时：可将索引 **Status** 标为 `Superseded by implementation (...)` 或 `Archived`；可保留原位或迁入 `archived/knowledge/`。**不要**把知识库产物搬进 `{HARNESS_DIR}/archived/plans/`（该处用于**计划行**冷快照）。
+5. **结晶（Compound）**：PM 在 **iteration-close** 触发 **`mstar-compound`**：plan 素材 + **`{ITERATION_DIR}/<iteration-id>/` package 提升** → `{KNOWLEDGE_DIR}/`。不在 per-plan Done 后单独执行。维护 → **`mstar-compound-refresh`**。
+
+## 与 review bundle、`{PLAN_DIR}/residuals/` 的区分
+
+- `**{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# 长文补充**（与根级 `**residual_findings**` 配套，canonical 见 `mstar-plan-conventions` **SKILL.md** 开篇）；见下文「open residual 散文详情」。
+- `**{KNOWLEDGE_DIR}/**`：偏 **可复用的实现向设计上下文**（架构细则、决策、分析），可被后续 plan 或多会话反复引用。
+- `**{ITERATION_DIR}/**`：偏 **某一迭代/版本** 的 package（compass + guides/specs），通常按版本索引而非按单 plan 长期复用。
+- review bundle、gate summary、residuals、knowledge、iterations 可互链，但职责不混写。
+
+---
+
+## `{PLAN_DIR}/residuals/<plan-id>/`（可选·open residual 散文详情）
+
+当某条 open residual 需要**多于** open 列表（根级 `residual_findings[<plan-id>][]`；若仅存 legacy 侧则同口径）里结构化字段所能承载的叙述时，可在本目录增加 **Markdown 散文**，作为 **SSOT 的补充**（**不替代** JSON；**权威仍以** `**{HARNESS_DIR}/status.json`** 中的 open 条目为准）。
+
+
+| 与相邻目录的分工                                  | 典型内容                                                                  |
+| ----------------------------------------- | --------------------------------------------------------------------- |
+| `**{SDD_DIR}/review/**`       | QC / QA **流程临时证据**（`qc1.md` … `qc-consolidated.md`、`qa.md` 等），gitignored                  |
+| **本目录 `{PLAN_DIR}/residuals/<plan-id>/`** | 针对**仍 open** 的某一 R#：defer 背景、遗留原因、代码锚点、后续接手提示等**长文**                  |
+| `**{KNOWLEDGE_DIR}/**`            | 可跨 plan 复用的**实现向**设计上下文、规格修订、gap 分析（若文中顺带提到 residual，仍以 JSON + residuals 为跟踪权威） |
+| `**{ITERATION_DIR}/**`            | 迭代 package（`<id>/delivery-compass.md` 等）；**不**替代 `{KNOWLEDGE_DIR}` 中的跨版本 SSOT |
+
+
+**文件命名（推荐）**：`<finding-id>-<short-label>.md`，其中 `**finding-id`** 与该条在 **open 列表**（根级 `**residual_findings**`，见 `mstar-plan-conventions` **SKILL.md** 开篇）中的 `**id**`（如 `R1`）或团队约定的 `**td-*` 等技术债编号**一致，便于 `detail_doc` 与目录互查。
+
+**登记**：在对应 open 条目中填写可选 `**detail_doc`**（仓库内相对路径，常形如 `**{PLAN_DIR}/residuals/<plan-id>/R1-….md**`）。**禁止**只写散文、不在 SSOT 中登记 open 行。
+
+**维护**：`**@project-manager`**（或与 Assignment 一致的可写角色）；`**@qc-specialist***` 宿主白名单通常**不含**本目录——审查结论仍以 Assignment 指定的 `**{SDD_DIR}/review/`** 为准，散文由 PM/实现方据结论整理。
+
+**关闭与归档**：当该条从 **open 列表**（根级 **`residual_findings[<plan-id>]`**；若仅存 legacy 侧则从该处）移除并**追加**至 `**{HARNESS_DIR}/archived/residuals/<plan-id>.json`** 时，应将对应 `**.md**` 一并收口：可迁入 `**{HARNESS_DIR}/archived/knowledge/**`（若视为历史考据）、或团队约定的 `**{HARNESS_DIR}/archived/residuals/**` 子路径（与 `**.json**` 同批变更可追溯）；并在归档条目的 `**closure_evidence` / `closure_note**`（或团队约定字段）中**写明散文最终路径**。勿长期保留「JSON 已关闭而散文仍留在 `residuals/` 且声称仍 open」的状态。

package/harness-skills/mstar-plan-artifacts/references/plan-files-and-reports.md

@@ -0,0 +1,99 @@
+# Plan 文件与 Review Bundle 留档（Morning Star）
+
+> **Load order（与其它 `mstar-*` skill 一致）**：依赖本 reference 排 review bundle / QC 波次前，须已 Read **`mstar-harness-core`** skill（SKILL.md；多 worktree 与 QC 单一 `HEAD` 见 **`mstar-branch-worktree`**）。冲突以 **`mstar-harness-core`** 为准。
+
+## Plan 文件（`{PLAN_DIR}/<name>.md`）
+
+每个 plan 的详细内容（任务清单、决策、Sign-off）。
+
+**命名（推荐）**：`<plan-id>-<plan-name>.md`（例：`01-data-infrastructure.md`）。`status.json` 中 `file` 字段填相对仓库根或 `{PLAN_DIR}` 下的实际路径。
+
+## Review bundle（`{SDD_DIR}/review/`）
+
+QC/QA 原始过程报告默认是 **ephemeral review bundle**，置于 `{SDD_DIR}/review/`（即 `{HARNESS_DIR}/sdd/<plan-id>/review/`）。该目录随 `{SDD_DIR}` gitignored，不作为长期 git 审计链。
+
+**QC basename rule**：`{SDD_DIR}` 已含 `<plan-id>` — **do not** repeat it in report filenames. Put `plan_id` in YAML frontmatter only.
+
+| 类型 | 文件名（相对 `{SDD_DIR}/review/`） |
+|------|--------|
+| QC 三审报告（**SDD 默认** `Execution mode: sdd`） | `qc1.md`、`qc2.md`、`qc3.md` |
+| QC 单席报告（**`inline` / hotfix 例外**） | `qc.md` |
+| QC 汇总结论（tri 模式） | `qc-consolidated.md` |
+| QA 验收报告（`QA gate: mandatory`） | `qa.md`（或 Assignment 指定的同目录 basename） |
+
+`{PLAN_DIR}/reports/` is **legacy / explicit audit mode only**. Use it only when the user or project policy explicitly requires tracked raw reports; the default harness path is `{SDD_DIR}/review/`.
+
+## SDD 运行时（不入 reports）
+
+Per-task briefs, implementer reports, review diffs, branch review packages, and QC/QA bundle files live under **`{SDD_DIR}`** (`mstar-plan-conventions`). Gitignored. Main plan may index `{SDD_DIR}` / `{SDD_DIR}/review/` paths only — do not paste SDD bodies or raw QC/QA reports into plan markdown.
+
+Plan template with Global Constraints / Interfaces → **`templates/plan.main.md`**.
+
+## QC 模式（L3 plan 级）
+
+职责分层 L1–L4 → **`mstar-review-qc/references/review-responsibility-boundaries.md`**。bundle basename 见上表；触发时机与 re-review 波次见下节 **§ QC 三审触发时机**。
+
+## Durable summaries（主 plan / status）
+
+Raw bundle files may disappear after the working context is gone. Before Done, PM must preserve the durable decision surface:
+
+- Main plan `## Review Gate Summary`:
+  - `Decision`: `Approve` | `Approve with residuals` | `Request Changes` | `Needs Discussion`
+  - `Review range / Diff basis`
+  - `Review bundle`: `{SDD_DIR}/review/`
+  - `QC inputs`: `qc1.md` / `qc2.md` / `qc3.md` or `qc.md`
+  - `Blocking result`: fixed / none / deferred with reason
+  - `Residual findings`: R# ids + short titles + owner/target
+- Main plan `## QA Gate Summary` when QA applies:
+  - `QA gate` / `QA mode`
+  - evidence reused vs newly run checks
+  - related R# closure recommendations
+- `{HARNESS_DIR}/status.json` root `residual_findings[<plan-id>]`: open R# machine SSOT.
+
+The durable summary is not a paste of raw reports. It is a small gate record sufficient for handoff after `{SDD_DIR}` is unavailable.
+
+## Residual findings（R#）：权威在哪、和主 plan 谁先谁后？
+
+- **Open 条目的单一事实来源（SSOT）**是 **`{HARNESS_DIR}/status.json`** 根级 **`residual_findings[<plan-id>]`**（与 `plans` 平级；canonical 见 `mstar-plan-artifacts` **SKILL.md** 开篇；字段见 `mstar-plan-artifacts/references/status-and-residuals.md`）。**同一工作副本内**的会话 handoff、关闭与归档流程**以该数组为准**（本地 SSOT，默认 gitignored）；**跨 clone** 须持久的 residual 须提升入 tracked `{KNOWLEDGE_DIR}/` / `{SPECS_DIR}/` 等（见 `mstar-plan-conventions`「Git 跟踪策略」）。
+- **推荐操作顺序**（避免 plan 与 JSON 两套 ID 漂移）：
+  1. `project-manager` 读完 review bundle 并完成「QC 三审轻量汇总」：对 finding **去重合并**，为每条待跟踪项分配**稳定 `id`**（如 `R1`、`R2`，全 plan 内唯一）。
+  2. **立即**将上述条目写入根级 **`residual_findings[<plan-id>]`**（含 `source` 指向 reviewer seat + bundle basename + finding id + review range，便于回溯）；**勿**与 legacy 侧双写（见 `mstar-plan-conventions` **SKILL.md** 开篇）。
+  3. **可选**：在主 plan 中增加 **「Residual findings（索引）」** 小节，**仅复述** `id` + 短标题 + 决策摘要，并写明「**权威列表见** `status.json` 根级 `residual_findings[<plan-id>]`（见 `mstar-plan-conventions` **SKILL.md** 开篇）」。**不要**只在主 plan 里「发明」R# 而不写回 SSOT。
+- **不要**反过来把主 plan 当作唯一登记处：若仅更新 plan、`status.json` 未同步，下一任 agent **无法**依赖 SSOT 继承债务状态。
+
+## QC 三审触发时机（单 plan · 多 batch）
+
+- **默认（SDD）**：同一 **`plan_id`** 下，**plan QC tri-review**（`qc-specialist` ×3 → `{SDD_DIR}/review/qc1.md`…`qc3.md` + `qc-consolidated.md`）**仅在** dev team 按该 plan 约定范围全部交付、且 **L2 task reviewers** 均已通过后执行 **一次**。**不要**在每个中间 batch 跑完整三审。
+- **单席例外**：`Execution mode: inline` / hotfix → 交付完成后 **一次** `qc.md`（`QC mode: single`）。
+- **batch 之间**：依赖实现方按 **`mstar-coding-behavior`** 提供完成证据、主 plan 任务勾选与 PM 协调；需要书面中间意见时，用对话、主 plan 批注或**非三审**的定向检查（如单审、架构 review），**不**默认等同「又一轮完整三审」。
+- **After `Request Changes` (default — targeted re-review)**：PM maps each **blocking** finding to the QC seat that raised it (`source` on R#, consolidated table, or the originating `qcN.md` / `F-###`). Dispatch **only** those reviewers (`QC re-review: targeted — reviewers: qc-specialist, qc-specialist-2, …`). Each re-reviewing QC **updates the same** bundle file (`qc1.md` / `qc2.md` / `qc3.md`) in place (add `## Revalidation`, refresh verdict / `generated_at`); **do not** add `qc1-rev2.md` siblings for targeted re-review. PM **updates the same** `qc-consolidated.md` and durable plan summary.
+- **Full tri re-review (exception)**：Only when Assignment states **`QC re-review: full tri-review`**. Run **three** parallel reviews again; use **new bundle basenames** (`qc1-rev2.md` … `qc3-rev2.md`, `qc-consolidated-rev2.md`) so wave-1 files stay distinct; PM states **active wave** in consolidated decision and durable plan summary. See `mstar-review-qc` · `mstar-dispatch-gates`.
+- **显式例外**：仅当用户与 PM 书面同意**中间门禁**时，在 Assignment 写清 **`QC gate: incremental — <scope>`**（或等价），并仍须保证该次三审的 **`plan_id` + `Review range` / `Diff basis`** 三份一致；**优先**用 `{SDD_DIR}/review/<scope>/` 子目录，避免与终局 `qc1..3.md` 混名。
+- **同仓多 worktree 并行 dev**：**推荐**在排各 batch / 各轨 worktree 前确立 **plan 集成分支** 与各轨 topic 线及 **merge 靶**（见 `mstar-branch-worktree` **「推荐默认编排：先建 plan 集成分支，再挂各 worktree」**）。**多 `plan_id` 同属一条 `primary_spec`（Spec 文档）时**：该「集成分支」在计划语义上即 **Spec 集成分支**；各 Plan 的 topic 分支 **merge 回 Spec 集成分支**，**全部 Plans 完成后** 向显式 `target_branch` **走 PR**，见 `mstar-plan-conventions` SKILL.md **「Spec 驱动的分支模型」**。终局（或增量）三审派单前，PM 仍须满足 **单一待审 `Working branch` / `HEAD`** 或已按上条 **拆 scope**；**不得**假设「整 plan 一次三审」可只靠某一个开发 worktree 路径覆盖未合并的其他并行轨。
+
+### 多 `plan_id` 同时 `InReview`（PM 编排）
+
+- **流程**：实现完成 → 该 **`plan_id`** 进入 **`InReview`** → **QC 三审（仅针对该 plan 的 `Review range`）** → PM consolidated → **QA** → **`Done`**。**禁止**在多个 `plan_id` 已 `InReview` 的情况下，只推进新实现、不派 QC，或把多个 plan 的变更**伪装成**一套三审字段（单一 `plan_id` / 单一 diff 范围覆盖多 plan）。
+- **并行 vs 串行**：不同 `plan_id` **相互独立**时，可 **并行**派发多组三审（每组各自的 Assignment 与 `{SDD_DIR}/review/`）；若 PM 选择串行，须在 Status Update 写明顺序——**每组仍须完整三审 + QA**，不是「一个大 QC」混审。
+- **读 skill**：书写或派发 QC 相关 Assignment 前，PM **必须** Read **`mstar-review-qc`**（编排与 residual）；leaf `qc-specialist*` → **`mstar-roles/references/qc-specialist/`**。见 `mstar-plan-conventions` SKILL.md **QC pre-dispatch gate**。
+
+**QC 落盘与宿主权限**：`qc-specialist` / `qc-specialist-2` / `qc-specialist-3` 在支持路径白名单的宿主上（如 OpenCode 的 **`permission.edit`**），默认 **仅可** Write/Edit Assignment 指定的 **`{SDD_DIR}/review/`** 下 **`.md`**。全局 agent 提示词应允许 `.mstar/sdd/**`、`.agents/sdd/**` 及 worktree 下对应路径。报告文件**必须**以 YAML **frontmatter** 开头（键见各 QC agent 提示词）。
+
+**QC 报告与 Git**：默认 raw QC/QA bundle **不**执行 `git add` / `git commit`。PM 将 durable gate summary 写入主 plan（本地会话 SSOT；默认 gitignored）并在当轮更新 `{HARNESS_DIR}/status.json` 的 open residuals（本地 SSOT，默认 gitignored）。**跨 clone 须持久的** residual 或决策须提升入 tracked `{KNOWLEDGE_DIR}/` / `{SPECS_DIR}/` 或 `{HARNESS_DIR}/AGENTS.md`（见 `mstar-plan-conventions`「Git 跟踪策略」）— **勿**默认 `git add` `status.json` / `plans/`。若项目显式 opt-in 跟踪审计报告，在 Assignment 写 `Review archive mode: tracked reports` 并使用项目 allow rules。
+
+## 主 plan 内任务清单（Markdown checkbox）
+
+- **谁应更新**：`fullstack-dev` / `frontend-dev` / `fullstack-dev-2`、`qa-engineer`、`ops-engineer`、`architect`、`product-manager` 在**完成本人 Assignment 范围内的工作后**，须在主 plan（`<plan-id>-<plan-name>.md`）中把**对应条目**的 Markdown 任务标记为已完成（常见：`- [ ]` → `- [x]`；若项目用其它清单记号，保持同文件内一致）。与 Completion Report **并列**，作为跨会话可核对的**落盘痕迹**。
+- **范围**：**只勾选与当前任务直接对应、且已由本角色交付证据支撑的条目**；不得代为勾选他人负责或未完工项。若正文用分段、Owner 或角色标签区分任务，以 Assignment 与文内约定为准。
+- **与 `status.json` / frontmatter 的关系**：勾选任务**不**等于整条计划收口。`plans[].status` 及主 plan frontmatter 的 **`Done`** 仍**仅** `project-manager` / `qa-engineer`（见「状态更新权限」）。`architect` / `product-manager` **不得**擅自将整条计划标为 `Done`；是否将 `status.json` 推进为 `InReview` 等仍按下文「状态更新权限」与 Assignment。
+- **`qc-specialist*`**：**不得**修改主 plan（宿主仅允许 Assignment 指定的 review bundle `.md`）；审查结论落在 `{SDD_DIR}/review/` 内。若主 plan 需新增或勾选与审查相关的条目，由 `project-manager` 或 Assignment 明确授权的角色据报告回写。
+- **只读角色**：不直接改主 plan；将建议交给 `project-manager` 代为更新清单。
+
+Plan 正文与 `status.json` 必须保持一致；不一致时以 `status.json` 的条目状态为准并尽快纠正正文或登记 notes。
+
+## Done 标记方式
+
+1. **Frontmatter**（首选）：添加 `status: Done` 和可选的 `done_at: YYYY-MM-DD`。
+2. **文件名**（备选）：重命名为 `DONE__<name>.md` 或 `<name>.done.md`。
+
+同时更新 `status.json` 对应条目。