@mstar-harness/opencode 0.2.0

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

@@ -0,0 +1,78 @@
+# 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-harness-core`** `references/branch-and-worktree.md` 约束。
+
+## 可选：`Done` 计划行冷快照（`{HARNESS_DIR}/archived/plans/`）
+
+**背景**：多条 `Done` 的 `plans[]` 行常带大块 `metadata`（`gates`、QC 摘要、`tests`、`commits`、长 `scope`/`description`），`status.json` 会无限膨胀；而**根级 `residual_findings` 中的 open 项**（canonical 见 `mstar-plan-conventions` **SKILL.md** 开篇）宜保持有界（已关闭项应迁出至 **`{HARNESS_DIR}/archived/residuals/`**，见 `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`** 或依赖冷快照 / `reports/`。
+- 一旦快照已写入，热行**不得**再承载完整 `gates`、`qc_status`、`tests`、`commits`、长 `description`/`scope` 等；**以 `archived_record` 指向文件为准**。
+- 单条 **`plans[].notes`** 字符串若仍在用，保持**极短**（如指向 `reports/<plan-id>/`）；**不要**重复 QC 报告大段原文。
+
+## Profile B（可选）— 热文件不保留任何 `Done` 行（统一压缩）
+
+- **Done 快照路径**：`{HARNESS_DIR}/archived/plans/<plan-id>.json`（保存完整 `plans[]` 行快照）。
+- **Done 目录路径**：`{HARNESS_DIR}/archived/plans-done.json`（最小索引，便于统一发现已完成计划）。
+- **`plans-done.json` 推荐最小字段**：`id`、`title`、`done_at`、`plan_file`、`archived_record`。
+- **热文件行为**：`status.json.plans[]` 只保留非 `Done`（`Todo` / `InProgress` / `InReview` / `Blocked`）；计划变为 `Done` 后，从热文件移除该行。
+- **读取约定**：当前执行状态读取 `status.json`；历史 `Done` 列表读取 `archived/plans-done.json`，详情读取 `archived/plans/<plan-id>.json`。
+
+## 原子更新约束（Profile A / B 通用）
+
+- 将计划标记为 `Done` 时，冷快照写入与 `status.json` 更新应在**同一变更集**完成（或紧随合并后一次性完成）。
+- 采用 **Profile B** 时，必须在同一变更集中同时完成：  
+  1) 写入/更新 `archived/plans/<plan-id>.json`，  
+  2) 写入/更新 `archived/plans-done.json`，  
+  3) 从 `status.json.plans[]` 删除该 `Done` 行。  
+- 若无法满足以上三步，视为未完成 `Done` 收口，不应宣称已完成压缩迁移。
+
+**可选索引**：`{HARNESS_DIR}/archived/plans/_index.json` — `plan-id` → 相对路径，便于不依赖 glob 的工具。
+
+**可选滚动保留**：进一步缩小 `plans[]` 时，可只在热文件中保留**最近窗口**的瘦 `Done` 行，更旧 id 仅出现在 `_index.json` 与快照文件中；若采用，须在项目 `AGENTS.md` 中写明，并检查依赖「热文件中必有全部历史 id」的脚本。
+
+## 采纳说明
+
+- 未写快照、热文件中仍保留完整 `Done` 行在历史仓库里依然可读；但新落地时建议先确定并固定使用 **Profile A** 或 **Profile B**，避免同仓混跑。
+- 从 Profile A 迁到 Profile B 前，先检查依赖 `status.json.plans[]` 扫描全部历史 `Done` 的脚本与流程，必要时先切换读取源到 `archived/plans-done.json`。
+
+## 仓库级采用声明模板（贴到项目 `AGENTS.md`）
+
+### Template A（默认，保留瘦 Done 行）
+
+```markdown
+### Plan compaction profile (this repository)
+
+This repository uses **Profile A** from the Morning Star `mstar-plan-conventions` 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-conventions` 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` (minimal catalog).
+- Historical `Done` discovery MUST read `archived/plans-done.json`, not `status.json.plans[]`.
+```

package/harness-skills/mstar-plan-conventions/references/effort-estimation.md

@@ -0,0 +1,38 @@
+# 工期与工作量预估（Agent 语境 · Morning Star）
+
+> **Load order（与其它 `mstar-*` skill 一致）**：写 Effort 字段前须已 Read **`mstar-harness-core`** skill（SKILL.md）以对齐「仅 agent-oriented、禁止人天/日历」的全局不变量；本 reference 为口径细则展开。
+
+在 OpenCode / Cursor 等多角色 agent 编排下，**所有「工期 / 工作量 / Effort」类预估只描述 agent 实施量级**：在规格与验收已就绪、上下文可加载的前提下，**agent 连续或少量会话内**完成实现与基础自证（跑通命令/单测等）需要多少**agent 工作量**。
+
+## 硬性规则（不得混入人工时间）
+
+凡使用本 harness 的计划、PRD、架构文档、Assignment、Status Update 中的 **Effort / 工期 / 预估** 表述：
+
+- **必须**只反映 **agent 执行与会话**（见下节尺码与会话带）。
+- **禁止**纳入任何**人类时间**，包括但不限于：人天 / person-days / FTE、人类日历天或周、等待人工评审、会议、排期空档、发布窗口、合规签批排队、跨团队人类响应时间。
+- **禁止**用「标了轴的人天」变相写人类时间；**本节字段内不要使用人天 / FTE / 人类日历**。
+- **QC/QA 在流程中的迭代**：视为 **agent 会话**的一部分（可多算几次会话），**不要**单独加「人类审查要等 X 天」。
+
+若业务方必须另做**人类排期或合同人天**，须在**与本 Effort 字段完全分离**的文档或章节（例如路线图、商务附件）中撰写，**不得**写进 `Effort (agent-oriented)` 或同名小节，以免与 agent 预估混读。
+
+## 推荐写法：T 恤尺码 + agent 会话带
+
+1. **XS**：单文件 / 单测点 / 配置微调 — 通常 **<1** 次完整 agent 回合可交付。  
+2. **S**：局部模块小改 — 约 **1** 次专注会话。  
+3. **M**：单功能横切少量文件 — 约 **1–3** 次会话（含流程内 QC/QA agent 迭代则取上沿）。  
+4. **L**：多模块、新子系统、或强依赖摸底 — 约 **3–8** 次会话；**应拆里程碑**。  
+5. **XL**：接近子系统级或未知域 — **先 spike / 原型**，未摸底前不给紧凑数字预估。
+
+「**会话**」指：一次连贯的 agent 运行（读上下文 → 实现 → 运行验证），**不是**人类 8 小时工作日。
+
+## 文档与模板中的字段名（建议）
+
+- **PRD / 产品文档**：**`## Effort (agent-oriented)`** — 仅 **Complexity (XS–XL) + agent session band + 假设**（规格已锁、契约稳定等）。  
+- **架构 / 技术计划**：**`### Implementation effort (agent-oriented)`** — 同上；区分 **spike** vs **build**。  
+- **PM Assignment `Constraints`**：**`Effort (agent-oriented)`**: `M, ~2–4 agent sessions — assumes plan locked and contracts stable`。  
+- **Status Update**：剩余工作仅用 agent 会话语言（如「约 1 次会话可收口」），**不写**人类日历或人天。
+
+## 与不确定性的关系
+
+- **规格未锁、接口未定、依赖外部凭证**：标 **`blocked` / `spike required`**，改为「先 1 次摸底会话再更新 Effort」，仍**只**用 agent 会话描述。  
+- **高危变更 / 生产发布**：人类审批或发布节奏**不计入**本节 Effort；若需记录依赖，用 **阻塞/依赖清单**（非时间预估字段）。

package/harness-skills/mstar-plan-conventions/references/harness-bootstrap-and-agents-layering.md

@@ -0,0 +1,79 @@
+# Harness 初始化与 `AGENTS.md` 分层策略（Morning Star）
+
+> **Load order**：使用本参考初始化仓库前，须先 Read `mstar-harness-core` 与 `mstar-plan-conventions`；冲突以 `mstar-harness-core` 为准。
+
+## 目标
+
+给新仓或迁移仓提供一套可复制的启动方式，确保：
+
+- `status.json` / residual / reports 有唯一落点；
+- 根规则与 harness 规则不互相覆盖；
+- 目录级 `AGENTS.md` 只承载增量边界，不变成重复手册。
+
+## Bootstrap 最小步骤
+
+1. 创建 `{HARNESS_DIR}`（推荐 `.agents/`）与 `{PLAN_DIR}`（推荐 `.agents/plans/`）。
+2. 初始化 `status.json`：推荐从 **`mstar-plan-conventions/templates/status.empty.json`** 复制；residual canonical 见 **`mstar-plan-conventions` SKILL.md** 开篇，字段与生命周期见 `status-and-residuals.md`。
+3. 初始化可选 `notes.json`（可复制 **`mstar-plan-conventions/templates/notes.empty.json`**）与 `plans/reports/README.md`。
+4. 创建 `.agents/AGENTS.md`（harness 子树规则）。
+5. 校准根 `AGENTS.md`：只保留仓库级长期约束，显式引用 `.agents/AGENTS.md` 作为 harness SSOT。
+6. 仅在确有稳定边界时新增目录级 `AGENTS.md`（如 `contracts/`、`gateway/`、`sdk/`）。
+
+## 三层 `AGENTS.md` 职责切分
+
+### 根 `AGENTS.md`（项目层）
+
+- 放：仓库身份、技术边界、构建/测试接口、安全与分支策略、规格路由表。
+- 不放：动态状态、当前批次进展、R# 明细、QC 单次结论。
+
+### `.agents/AGENTS.md`（harness 层）
+
+- 放：`{HARNESS_DIR}`/`{PLAN_DIR}` 契约、状态推进门禁、QC/QA 对齐规则、residual 生命周期、Done compaction profile。
+- 不放：语言/框架编码细节、业务模块实现约束。
+
+### `<subdir>/AGENTS.md`（边界层）
+
+- 放：该目录独有的边界、禁区、接口命令与升级触发。
+- 不放：根级通用规则复写、harness 全量规则拷贝。
+
+## 分目录 `AGENTS.md` 创建准入
+
+仅当满足任一条件时创建：
+
+- 目录具备独立风险模型（如链上合约 vs 网关服务）；
+- 目录有单独发布面或对外 API 面；
+- 目录有稳定且长期存在的专属约束（构建、依赖、数据/安全边界）。
+
+若仅是代码组织而无新增约束，不创建目录级 `AGENTS.md`。
+
+## 推荐模板骨架（目录级）
+
+```markdown
+# AGENTS.md — `<dir>/`
+
+## Source Priority
+1. Current user instruction
+2. Root `AGENTS.md`
+3. This file
+4. `.agents/AGENTS.md`
+
+## Boundary Rules
+- ...
+
+## Build & Test (interface)
+- ...
+
+## Escalation Triggers
+- ...
+```
+
+## 反模式与修正
+
+- 反模式：在根 `AGENTS.md` 维护当前计划进展与 commit 列表。  
+  修正：迁移到 `status.json` 的 `plans[].metadata` 与 `notes.json`。
+
+- 反模式：每个子目录复制一份完整 harness 规则。  
+  修正：保留一行引用 `.agents/AGENTS.md`，仅写本目录增量约束。
+
+- 反模式：目录级规则未声明 Source Priority，冲突时不可裁决。  
+  修正：统一四级优先级模板并在每个目录级文件开头声明。

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

@@ -0,0 +1,70 @@
+# `{HARNESS_DIR}/knowledge/` 开发过程知识库与 `{SPECS_DIR}` / `residuals/` 散文（Morning Star）
+
+> **Load order（与其它 `mstar-*` skill 一致）**：依赖本 reference 维护知识库 / 规格挂接前，须已 Read **`mstar-harness-core`** skill（SKILL.md；仓库写操作与分支门禁见 `mstar-harness-core/references/branch-and-worktree.md`）。冲突以 **`mstar-harness-core`** 为准。
+
+本节将「用户文档」与「agent / 实施用知识」分开，**与具体业务仓库无关**；项目可在根目录 `AGENTS.md` 用一小段指向本 reference 或复述分界关键词，避免重复维护长文。
+
+## 与公开文档目录的分工（典型为 `docs/`）
+
+
+| 区域                               | 典型内容                                            | 受众                                       |
+| -------------------------------- | ----------------------------------------------- | ---------------------------------------- |
+| `**docs/`**（或项目约定的用户文档根）         | 安装/quickstart、稳定架构概览、贡献指南、对外 API 说明             | 人类贡献者与终端用户；clone 后应可读                    |
+| `**{HARNESS_DIR}/knowledge/**`   | 架构评审报告、规格修订稿、gap 分析、约束清单、**某一 plan 的输入/输出设计材料** | Agent handoff、跨会话连续；**不**默认当作对外产品文档      |
+| `**{SPECS_DIR}`**（可选）             | 规格主目录（支持 `{HARNESS_DIR}/specs/` 或 `{HARNESS_DIR}/designs/`） | 与 `knowledge/` 分工由团队定义；**不**默认替代 `docs/` |
+
+
+**不应**放入用户文档树的内容（宜放 `knowledge/`、`{SPECS_DIR}` 或主 plan）：作为**特定 plan 的输入/输出**的评审结论、实施笔记、未稳定的规格草案。
+
+## 目录与索引
+
+- `{SPECS_DIR}` 定义：优先 `{HARNESS_DIR}/specs/`，否则 `{HARNESS_DIR}/designs/`；若两者都不存在，建议新建 `{HARNESS_DIR}/specs/`。
+
+- 知识库物理路径：`**{HARNESS_DIR}/knowledge/`**（推荐布局下常为 `**.agents/knowledge/**`，与 `**{PLAN_DIR}**` 并列）。
+- **必须**维护 `**{HARNESS_DIR}/knowledge/README.md`** 作为**目录索引**：至少包含表格列 **Document（链接）**、**Source Plan（`plans[].id`）**、**Description**、**Status**（如 `Active` / `Superseded by implementation (<plan-id>)` / `Archived`）。
+- 初始化启用知识库时：创建空表头的 `README.md`，随文档递增行。
+
+## 文件命名
+
+- 推荐：`<topic>-<qualifier>-v<N>.md`（例：`sync-contract-gap-analysis-v1.md`），便于同主题多版共存。
+- 避免与主 plan 文件名混淆：主 plan 仍建议 `<plan-id>-<plan-name>.md` 且放在 `{PLAN_DIR}/` 根下，而非塞进 `knowledge/` 根（除非团队明确约定）。
+
+## 与 `status.json` 的链接
+
+- 某 plan 的**权威设计输入**在知识库或规格目录中时，在 `**plans[].metadata`** 中登记路径，推荐使用已列标准键：`**primary_spec**`（单文件）或 `**spec_refs**`（`string[]`）。路径为**仓库内相对路径**（推荐布局下常写作 `**.agents/knowledge/....md`** 或 `**.agents/specs/....md`**；兼容旧目录时也可为 `**.agents/designs/....md**`）。
+- 执行方在 **implement 前**须按 metadata 读取这些文件，并与主 plan 核对；不得在未读链接文档的情况下**静默偏离**其中已写明的决策（若需偏离，先回写 knowledge 或 plan 并走 PM/architect 门禁）。
+
+## 维护规则
+
+1. **新增**：按命名规则添加 `.md` → 在 `knowledge/README.md` 索引表增加一行 → 在相关 `plans[].metadata` 更新 `primary_spec` / `spec_refs`（若该文档为本 plan 输入/输出）。
+2. **阅读**：开发类 agent 在开始编码前，**必须**阅读当前 plan 在 `metadata` 中指向的 knowledge 文档（若存在）；`@project-manager` 在 Assignment 中可再次点名路径。
+3. **修订**：评审或规格变更若改动了 knowledge 文件，同步更新 README 中 **Status** 或 Description；版本迭代优先新文件名 `v<N+1>` 或保留旧版并标明 Superseded。
+4. **归档**：当文档内容已完全反映到已合并代码中时：**保留文件不删除**（保留设计考据）；将索引 **Status** 标为 `Superseded by implementation (...)` 或 `Archived`。**不要**把知识库产物搬进 `**{HARNESS_DIR}/archived/plans/`**（该处用于**计划行**冷快照）；知识库用索引状态表达生命周期即可。
+
+## 与 `reports/`、`{PLAN_DIR}/residuals/` 的区分
+
+- `**reports/<plan-id>/`**：偏 **审查流程留档**（review、QC1/2/3、consolidated），只读历史。
+- `**{PLAN_DIR}/residuals/<plan-id>/`**：偏 **仍 open 的 R# 长文补充**（与根级 `**residual_findings**` 配套，canonical 见 `mstar-plan-conventions` **SKILL.md** 开篇）；见下文「open residual 散文详情」。
+- `**knowledge/**`：偏 **可复用的设计上下文**（规格、决策、分析），可被后续 plan 或多会话反复引用；三者可互链，但职责不混写。
+
+---
+
+## `{PLAN_DIR}/residuals/<plan-id>/`（可选·open residual 散文详情）
+
+当某条 open residual 需要**多于** open 列表（根级 `residual_findings[<plan-id>][]`；若仅存 legacy 侧则同口径）里结构化字段所能承载的叙述时，可在本目录增加 **Markdown 散文**，作为 **SSOT 的补充**（**不替代** JSON；**权威仍以** `**{HARNESS_DIR}/status.json`** 中的 open 条目为准）。
+
+
+| 与相邻目录的分工                                  | 典型内容                                                                  |
+| ----------------------------------------- | --------------------------------------------------------------------- |
+| `**{PLAN_DIR}/reports/<plan-id>/**`       | QC / review **流程留档**（`-qc*.md`、consolidated 等），只读历史链                  |
+| **本目录 `{PLAN_DIR}/residuals/<plan-id>/`** | 针对**仍 open** 的某一 R#：defer 背景、遗留原因、代码锚点、后续接手提示等**长文**                  |
+| `**{HARNESS_DIR}/knowledge/`**            | 可跨 plan 复用的**设计**上下文、规格修订、gap 分析（若文中顺带提到 residual，仍以 JSON + 本目录为跟踪权威） |
+
+
+**文件命名（推荐）**：`<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***` 宿主白名单通常**不含**本目录——审查结论仍以 `**reports/`** 为准，散文由 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-conventions/references/plan-files-and-reports.md

@@ -0,0 +1,66 @@
+# Plan 文件与 Reports 留档（Morning Star）
+
+> **Load order（与其它 `mstar-*` skill 一致）**：依赖本 reference 排 reports / QC 波次前，须已 Read **`mstar-harness-core`** skill（SKILL.md；多 worktree 与 QC 单一 `HEAD` 见 `mstar-harness-core/references/branch-and-worktree.md`）。冲突以 **`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}` 下的实际路径。
+
+**审查报告文件**（置于 `{PLAN_DIR}/reports/<plan-id>/`）：
+
+| 类型 | 文件名 |
+|------|--------|
+| 架构/设计评审 | `<plan-id>-review.md` |
+| QC 并行报告 | `<plan-id>-qc1.md`、`-qc2.md`、`-qc3.md` |
+| QC 汇总结论 | `<plan-id>-qc-consolidated.md` |
+
+## QC 分报告与 consolidated：可否只留一份？
+
+- **不要删除** `<plan-id>-qc1.md`、`-qc2.md`、`-qc3.md`**只因为**已写入 `<plan-id>-qc-consolidated.md`。`reports/` 在此约定下是**只读历史 / 审计链**：分 reviewer 原文保留**证据出处、分歧与独立视角**；**consolidated** 是 PM 的**门控摘要**，二者**叠加**，**不互为替代**。
+- **极窄例外**（须团队显式采纳并承担审计缺口）：例如仓库体积极敏感时，仅保留 consolidated + 指向外部归档的链接——**不在**本默认 harness 中推荐；默认仍保留三份 `-qc*.md`。
+
+## Residual findings（R#）：权威在哪、和主 plan 谁先谁后？
+
+- **Open 条目的单一事实来源（SSOT）**是 **`{HARNESS_DIR}/status.json`** 根级 **`residual_findings[<plan-id>]`**（与 `plans` 平级；canonical 见 `mstar-plan-conventions` **SKILL.md** 开篇；字段见 `status-and-residuals.md`）。跨会话 handoff、关闭与归档流程**以该数组为准**。
+- **推荐操作顺序**（避免 plan 与 JSON 两套 ID 漂移）：
+  1. `@project-manager` 读完三份 QC 报告并完成「QC 三审轻量汇总」：对 finding **去重合并**，为每条待跟踪项分配**稳定 `id`**（如 `R1`、`R2`，全 plan 内唯一）。
+  2. **立即**将上述条目写入根级 **`residual_findings[<plan-id>]`**（含 `source` 指向哪位 QC / 哪份报告文件名，便于回溯）；**勿**与 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）
+
+- **默认（推荐）**：同一 **`plan_id`** 下，**完整 QC 三审**（`qc1` + `qc2` + `qc3` 并行）**仅在 dev team 按该 plan 约定范围全部交付之后**执行**一次**，再进入 `@project-manager` 汇总与 `@qa-engineer` 验证。**不要**在每个中间 **batch** / 子里程碑都跑全套三审：否则 `reports/<plan-id>/` 会堆积多套并列报告，**`Review range` / `Diff basis` 与结论**易混淆，handoff 成本高。
+- **batch 之间**：依赖实现方 **`verification-before-completion`**、主 plan 任务勾选与 PM 协调；需要书面中间意见时，用对话、主 plan 批注或**非三审**的定向检查（如单审、架构 review），**不**默认等同「又一轮完整三审」。
+- **Request Changes 后复验**：若须再跑一轮完整三审，使用**新文件名**落盘，避免覆盖首轮报告，例如 `<plan-id>-qc1-rev2.md` … `<plan-id>-qc3-rev2.md`（或团队约定的 `wave2-` 前缀）；`@project-manager` 在 `QC Consolidated Decision` 中写明**当前以哪一波次为准**。
+- **显式例外**：仅当用户与 PM 书面同意**中间门禁**时，在 Assignment 写清 **`QC gate: incremental — <scope>`**（或等价），并仍须保证该次三审的 **`plan_id` + `Review range` / `Diff basis`** 三份一致；**优先**用子范围专用标签或子目录，避免与「整 plan 终局」那套 `-qc*.md` 混名。
+- **同仓多 worktree 并行 dev**：**推荐**在排各 batch / 各轨 worktree 前确立 **plan 集成分支** 与各轨 topic 线及 **merge 靶**（见 `mstar-harness-core` `references/branch-and-worktree.md` **「推荐默认编排：先建 plan 集成分支，再挂各 worktree」**）。终局（或增量）三审派单前，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 与 `reports/<plan-id>/`）；若 PM 选择串行，须在 Status Update 写明顺序——**每组仍须完整三审 + QA**，不是「一个大 QC」混审。
+- **读 skill**：书写或派发 QC 相关 Assignment 前，PM **必须** Read **`mstar-review-qc`** skill（`mstar-plan-conventions` 不重复 QC 清单与 verdict 规则）。见 `mstar-plan-conventions` SKILL.md **QC pre-dispatch gate** 与 **InReview 与 QC+QA** 小节。
+
+**QC 落盘与宿主权限**：`@qc-specialist` / `@qc-specialist-2` / `@qc-specialist-3` 在支持路径白名单的宿主上（如 OpenCode 的 **`permission.edit`**），**仅可** Write/Edit **`{PLAN_DIR}/reports/`** 下 **`.md`**（全局 agent 提示词中已配置 `.agents/plans/reports/**`、`.plans/reports/**`、`plans/reports/**` 相对路径）。报告文件**必须**以 YAML **frontmatter** 开头（键见各 QC agent 提示词）。**若** 项目的 `{PLAN_DIR}` 不落在上述三种根下，须在**项目级**宿主配置（如 OpenCode）中为 QC 角色追加对应的 `edit` allow 规则。
+
+**QC 报告与 Git**：报告落盘后，各 QC 角色须在业务仓内对**本次报告文件**执行 **`git add` + `git commit`**（细则与 bash 权限见 `agents/qc-specialist*.md`）；**禁止**仅落盘不提交导致 `clone` 后不可见。**PM / architect / product-manager** 对 **`{HARNESS_DIR}`** / **`{PLAN_DIR}`** 与主 plan 的创建与更新亦须在业务仓内 **commit**（见 `agents/project-manager.md` Plan 初始化与 PM 职责、`agents/architect.md` / `agents/product-manager.md` Git 小节）。
+
+## 主 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（宿主仅允许 `{PLAN_DIR}/reports/**/*.md`）；审查结论落在 `reports/<plan-id>/` 内。若主 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` 对应条目。