@mstar-harness/opencode 0.2.0

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

@@ -0,0 +1,391 @@
+# `{HARNESS_DIR}/status.json` 与 Residual Findings（Morning Star）
+
+> **Load order（与其它 `mstar-*` skill 一致）**：依赖本 reference 改 SSOT / residual 前，须已 Read **`mstar-harness-core`** skill（SKILL.md；同仓分支与 worktree 见 `mstar-harness-core/references/branch-and-worktree.md`）。冲突以 **`mstar-harness-core`** 为准；专题索引见该 SKILL.md「Morning Star Skill 索引」。
+
+`status.json` 位于 `**{HARNESS_DIR}/status.json**`，是 `**plans[]` 行状态**与 **仍处 `open` 的 residual findings** 的**单一事实来源（SSOT）**。  
+**residual 的 canonical / legacy fallback 定义**见本 skill **`SKILL.md` 开篇「\`status.json\` 与 open residual（canonical）」**；本文件展开**字段、severity、生命周期、归档与 `jq` 示例**。
+**已关闭**的 residual **不应长期堆在**本文件中；权威档案见 `**{HARNESS_DIR}/archived/residuals/<plan-id>.json`**（见「Residual findings 生命周期」）。
+
+**编排语义（为何不是「多写几个字」）**：open 列表与 `archived/residuals/` 是跨会话、跨 agent 的**风险与决策交接面**。若非阻断结论只留在对话或单次 QC 报告里、**不进 SSOT**，下一任实现/审查方**无法可靠继承**已 defer、已风险接受或待跟进的约定；`Done` 也会与「已知债是否对仓库可见」**脱钩**，复盘或线上问题时常出现**无单一事实可引用**。因此 `**@project-manager`** 宜在审查收口后尽快把应跟踪项**登记为 open**；`**@qa-engineer`** 与 PM 宜在验证或豁免决策明确后**及时关闭并归档**——节奏可按里程碑灵活安排，但**不应默认「口头说过即可」**。
+
+## 基本结构
+
+```json
+{
+  "version": 1,
+  "updated_at": "YYYY-MM-DD",
+  "plans": [
+    {
+      "id": "plan-id",
+      "title": "计划标题",
+      "file": "{PLAN_DIR}/plan-id-feature-name.md",
+      "status": "Todo | InProgress | InReview | Blocked | Done",
+      "owner": "@project-manager",
+      "agents": ["@fullstack-dev"],
+      "progress": 0,
+      "tags": [],
+      "created_at": "YYYY-MM-DD",
+      "updated_at": "YYYY-MM-DD",
+      "done_at": null,
+      "notes": "",
+      "metadata": {}
+    }
+  ],
+  "residual_findings": {
+    "plan-id": [
+      {
+        "id": "R1",
+        "title": "Finding title",
+        "severity": "critical | high | medium | low | nit",
+        "source": "QC-#1, QC-#3, review, …",
+        "scope": "Affected file or component",
+        "decision": "defer | accept | risk-accepted",
+        "owner": "@fullstack-dev",
+        "target": "Before plan 02 / YYYY-MM-DD / milestone",
+        "tracking": "Issue URL or null",
+        "detail_doc": "{PLAN_DIR}/residuals/plan-id/R1-short-label.md"
+      }
+    ]
+  },
+  "metadata": {}
+}
+```
+
+**空仓库可复制模板**：本仓库 **`mstar-plan-conventions/templates/status.empty.json`**；可选 **`templates/notes.empty.json`** → `{HARNESS_DIR}/notes.json`。说明见 **`mstar-plan-conventions/templates/README.md`**。
+
+**已关闭条目**在以上字段之外补充：`lifecycle`、`closed_at`、`closure_note`；可选 `closure_evidence`、`superseded_by`。语义见下「Residual findings 生命周期」。
+
+**Open 条目可选 `detail_doc`**：仓库内相对路径，指向 `**{PLAN_DIR}/residuals/<plan-id>/**` 下与该条 `**id**`（如 `R1`）配套的散文 `.md`（若启用散文层，见 `knowledge-and-designs.md`）；未使用散文层则**省略**该键。
+
+## Residual findings：severity（SSOT，机器字段）
+
+`residual_findings[<plan-id>][]` 里每条记录的 `**severity`** 只能是本节定义的枚举值（若仓库仅有 legacy 键位，读法见文末 **`jq` 示例**）。QC 报告 Markdown 里的 **Critical / Warning / Suggestion** 是**章节标题**，**不得**原样当作 JSON 里的 `severity`（二者关系见下表）。
+
+### 1. 允许取值
+
+仅此五种，**必须小写英文**：
+
+`critical`、`high`、`medium`、`low`、`nit`
+
+### 2. 全序（从重到轻）
+
+`critical` ＞ `high` ＞ `medium` ＞ `low` ＞ `nit`
+
+- `**nit` 恒轻于 `low`**，禁止把两档颠倒或等同。
+- **禁止**把 `severity` 写成 `warning`、`Major`、中文或其它未列出的字符串。
+
+### 3. 各档含义与门禁关系
+
+
+| `severity` | 含义要点                                                                     |
+| ---------- | ------------------------------------------------------------------------ |
+| `critical` | 合并阻断级；与 QC 报告 **Critical** findings 对应。                                  |
+| `high`     | 非阻断但影响大（安全、正确性、数据、显著技术债）；须修复、显式升级决策，或 open residual 并由 PM 明确跟进。          |
+| `medium`   | 当前或下一里程碑应处理；可 open residual。                                             |
+| `low`      | 影响面小、修复成本低；可 open residual。                                              |
+| `nit`      | 最低档：风格、命名偏好、措辞、非行为文档笔误等；**轻于 `low`**。PM 判断无需跟踪时可不写入 `residual_findings`。 |
+
+
+与 `mstar-review-qc` 的对应关系（摘要）：未解决的 `**critical**` 通常导致 `Request Changes`；`**high**` 常与「合并前须处理或显式拍板」同列；`**medium` / `low` / `nit**` 可作为带 residual 的跟踪项（具体 **Verdict** 以 PM 汇总为准）。
+
+### 4. QC 报告小节 → JSON 里写什么 `severity`
+
+QC 报告模板见 `mstar-review-qc`。把 finding 登记进根级 `**residual_findings**` 时，按下表选择字段值：
+
+
+| 报告 Findings 小节 | 写入 JSON 的 `severity`                                                        |
+| -------------- | --------------------------------------------------------------------------- |
+| **Critical**   | 默认 `critical`。若 PM 明确记录「本次不阻断但须尽快跟进」，可记 `high` 并在 `title`/`scope` 写清理由。     |
+| **Warning**    | `high` 或 `medium`：偏安全/正确性/数据 → `high`；其它实质性非阻断 → `medium`；**不确定时取 `high`**。 |
+| **Suggestion** | `low` 或 `nit`：有实质改进 → `low`；纯风格/可有可无 → `nit`。                               |
+
+
+**易错点**：报告里的 **Warning** 不是合法 `severity` 字符串；合法值里**没有** `warning`（见第 5 节历史兼容）。
+
+### 5. 历史数据中的 `"severity": "warning"`
+
+旧 JSON 若出现 `**"severity": "warning"`**：读取、汇总、`tech_debt_summary` 统计时**一律视为 `low`**。**禁止**在新条目中使用该值。
+
+---
+
+## `plans[].metadata` 标准可选字段
+
+与业务仓库实践对齐的推荐键（均为可选；项目可只选子集）：
+
+
+| 键                                 | 类型                        | 用途                                                                                                                                                 |
+| --------------------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `working_branch`                  | string                    | 本 plan 实现所用分支名，与 Assignment `**Working branch`** 对齐（SSOT）                                                                                          |
+| `merge_target`                    | string                    | 预期合并目标分支（如 `main`）；默认分支以项目约定为准                                                                                                                     |
+| `branch_policy`                   | string                    | 与 `mstar-harness-core` 一致的一行策略说明（如 `direct on main — <reason>` 或 `create feature/x from main`）                                                     |
+| `phase`                           | string                    | 程序/路线图阶段标签（如 `Phase 0`、`v1.0`）                                                                                                                     |
+| `priority`                        | `high` | `medium` | `low` | PM 编排优先级                                                                                                                                           |
+| `description` / `scope`           | string                    | 一句话范围或目标；**同一仓库内择一**为主，避免两键长期混填不同内容                                                                                                                |
+| `gates`                           | object                    | 门禁结果摘要；**推荐子键**（按需）：`qc`、`qa`、`typecheck`、`tests`、`lint`… 值为短字符串（如 `PASS (…)`、`FAIL — see report`）                                                 |
+| `blocked_since`                   | `YYYY-MM-DD`              | 当 `status` 为 `Blocked` 时建议填写                                                                                                                       |
+| `blocked_reason`                  | string                    | 阻塞原因（可与顶层 `notes` 互引，metadata 便于机器过滤）                                                                                                              |
+| `blocked_by_plan_id`              | string                    | 若阻塞来自另一计划，填对方 `**plans[].id`**                                                                                                                     |
+| `dependency`                      | string                    | 其它依赖说明（接口、外部团队）；与 `blocked_by_plan_id` 互补                                                                                                          |
+| `next_action`                     | string                    | 当前解锁后或审查后的下一步（给谁、做什么）                                                                                                                              |
+| `primary_spec`                    | string                    | 主规格/设计文档路径（仓库内相对路径；**常为** `{HARNESS_DIR}/knowledge/...` 或 `{SPECS_DIR}/...`，其中 `{SPECS_DIR}` 支持 `specs/` 与 `designs/`）；多文档可用 `spec_refs`（string[]） |
+| `qc_status` / `tests` / `commits` | string                    | **InReview / Done** 前后的可验证快照（结论摘要、测试统计、commit 提示），**非**替代正式报告文件                                                                                    |
+
+
+### 建议补充：交付型状态账本（phase + batches + verification）
+
+当 plan 包含多批次推进或多角色协作时，推荐采用以下三组字段，减少“只知道状态，不知道为什么”的信息损失：
+
+| 键 | 类型 | 用途 |
+| --- | --- | --- |
+| `phase` | string | 当前交付阶段标签（如 `spec-drafting`、`batches-done-pending-merge`、`awaiting-qa`） |
+| `batches` | array<object> | 批次执行账本：每批覆盖任务、owner、状态、commit 证据、自检结论 |
+| `verification` | object | 与该批次相关的命令级验证快照（如 `cargo_check_workspace: ok`） |
+
+**`batches[]` 推荐子字段**（按需）：
+
+- `index`: number，批次序号（1-based）。
+- `covers`: string[]，覆盖的任务 ID（如 `T3`、`T4`）。
+- `status`: `planned | in_progress | done | blocked`。
+- `owner`: string，负责角色。
+- `commits`: string[]，commit 短哈希 + 一行摘要（便于审计）。
+- `a2_self_audit`（或同义键）：string，规则自检结论。
+- `verification`: object，批次级验证结果（可覆盖全局 verification）。
+
+> 约束：`batches`/`verification` 是证据索引，不替代 `{PLAN_DIR}/reports/` 正式审查文档，也不替代根级 `residual_findings` 的风险追踪。
+
+### `plans[].notes` 与 `{HARNESS_DIR}/notes.json` 的协同
+
+推荐保留双层日志语义，避免把所有轨迹塞进单条字符串：
+
+- `plans[].notes`：该 plan 的关键时间线（可用字符串数组，按时间追加）。
+- `{HARNESS_DIR}/notes.json`：跨 plan 程序里程碑。
+
+若仓库历史上 `plans[].notes` 是字符串，也可保留；新项目建议从一开始使用字符串数组，记录“时间 + 事件 + 证据锚点（commit/PR/report）”。
+
+## 根级 `metadata` 标准可选字段
+
+除 `**residual_findings`**（SSOT）外，推荐可选：
+
+
+| 键                           | 类型     | 用途                                                                                                               |
+| --------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------- |
+| `versioning`                | object | 跨 plan 约定，如 `phase_1_branch_prefix`、`release` 等（自由键，团队自定）                                                        |
+| `notes`                     | array  | **遗留/不推荐**：曾用于程序级时间线；**新仓库请用** `**{HARNESS_DIR}/notes.json`**，以免 `status.json` 随日志变长。若仍存在，可与 `notes.json` 并存直至迁出 |
+| `residual_findings_history` | object | **遗留/不推荐**：同型剪切区；**新归档请用** `{HARNESS_DIR}/archived/residuals/<plan-id>.json`                                     |
+| `tech_debt_summary`         | object | **可选**：技术债**一览/rollup**，与 `**residual_findings` 互补**（见下专节）；由 `**@project-manager`** 维护                           |
+
+
+## 通用约束
+
+- 每条 `plans[]` 可带 `**metadata` 对象**（可选）。无扩展需求时可省略该键或置 `{}`。
+- 初始化时若尚无 findings，使用平级 `"residual_findings": {}`；**勿**与 legacy 侧**双写**（定义见本 skill **`SKILL.md` 开篇**）。**程序时间线**请用可选 `**{HARNESS_DIR}/notes.json`**（见下），**勿**在 `status.json` 根级 `metadata` 中长期堆 `notes` 数组（遗留仓库若已有 `metadata.notes`，可择机迁出后删键）。
+- `**plans[].id`** 与根级 `**residual_findings**` 的键应对齐（同一 `plan-id`）；若仍存在 legacy 侧残留映射，其 **plan-id 键名**也应与之一致，便于 `jq` 与报告目录 `reports/<plan-id>/` 一致。**不要**再存 `residual_findings_plan_id`（与 `id` 重复）。
+- `**residual_findings` 空键**：某 `plan-id` 下**已无 open 条目**时，应从根级 `**residual_findings**`（及 legacy 侧同键，若有）**删除该键**（勿保留 `"plan-id": []` 空数组），减少噪声与误读。**注意**：这仅指 residual 映射对象上的键；`**plans[]` 是否仍保留该 plan 行**由团队决定（Done 瘦行、冷快照与「滚动保留」见 `done-compaction.md`），二者独立。
+- `**residual_summary`（可选）**：单行人类可读摘要；**仅描述仍 open 且仍挂在** `residual_findings[<plan-id>]`（与 legacy 侧同口径若仍存在）**的项**（已关闭项应在 `**{HARNESS_DIR}/archived/residuals/`** 与可选 `**{HARNESS_DIR}/notes.json**` 中体现）。
+
+---
+
+## Residual findings 生命周期（关闭、归档、移除）
+
+本节约定技术债条目在**已修复、已豁免、被替代或误登**之后如何更新 JSON，与「登记」流程闭环。
+
+### 条目状态 `lifecycle`（可选，默认视为 open）
+
+
+| `lifecycle`  | 含义                             | 关闭时 `closure_note` 应说明              |
+| ------------ | ------------------------------ | ----------------------------------- |
+| `open`       | 未关闭（**省略该字段时按 open 处理**，兼容旧数据） | —                                   |
+| `resolved`   | 已在代码/配置/文档中解决，且**已验证**         | 改了什么、如何验证（可与 `closure_evidence` 互指） |
+| `waived`     | 经明确决策**不修复**（承担风险或产品接受）        | 谁决策、为何不修、是否登记 `tracking` Issue      |
+| `superseded` | 被新 finding、新规格或重构方案取代          | 指向 `superseded_by`（另一条 `id` 或知识库路径） |
+| `duplicate`  | 重复录入或与另一 R# 实质相同               | 指向 canonical 的 `id` 或说明误登           |
+
+
+**关闭必填**：凡 `lifecycle` 为 `resolved` / `waived` / `superseded` / `duplicate`，须填写 `**closed_at`**（`YYYY-MM-DD`）与 `**closure_note**`（一句即可）。**推荐**填写 `**closure_evidence`**（PR、commit、测试结果、文档锚点），以满足可审计与 `verification-before-completion` 一致。
+
+### 谁更新、何时更新
+
+
+| 动作               | 建议负责方                                                      | 时机                                   |
+| ---------------- | ---------------------------------------------------------- | ------------------------------------ |
+| 实现修复             | `@fullstack-dev` / 对应 owner                                | Completion Report 中说明对应 R# 与证据       |
+| 验证               | `@qa-engineer`                                             | 回归或验收中确认 R# 已满足                      |
+| 写回 `status.json` | `**@project-manager**` 或 `**@qa-engineer**`（与 Done 收口权限一致） | 验证通过后同一提交或紧随其后；豁免/替代由 PM 与用户或架构对齐后写回 |
+
+
+**不得**在未落盘的情况下，仅从对话或主 plan 文案中宣称「R3 已修」而不更新 SSOT。
+
+**对 `@project-manager` / `@qa-engineer` 的预期（可灵活，须诚实）**：PM 在 `**Approve with residuals`** 或 consolidated QC 后**主动补齐** open 登记（或与 QC 报告交叉引用且 SSOT 中可追溯）；QA 在验收叙述中**显式交代**每条相关 R#（仍 open / 本次已验证 resolved / 需 PM 与用户裁决豁免），避免「只写测试通过」而 SSOT 与报告对不上。长期 open 与已关闭双写、或主列表与归档文件**长期不一致**，会削弱 handoff 可信度，应在本里程碑内收敛。
+
+### 推荐策略：关闭后迁入 `archived/residuals/<plan-id>.json`（控制 `status.json` 体积）
+
+为避免 `**status.json` 随已关闭 R# 无限膨胀**，在 `**closed_at` / `closure_note`（及推荐 `closure_evidence`）已齐备** 且 `**@qa-engineer`** 或 `**@project-manager**` 已确认可关闭后：
+
+1. **追加**到 `**{HARNESS_DIR}/archived/residuals/<plan-id>.json`**（文件名与 `**plans[].id**` 一致；遗留同目录布局下全路径可能为 `**plans/archived/residuals/<plan-id>.json**` 等，视解析结果而定）。
+2. 从 **open 列表**（根级 **`residual_findings[<plan-id>]`**，条目若仅存于 legacy 侧则从该处）**删除**该条（主列表**只保留 open**）。若删除后该数组为空，**删除**对应的 `**plan-id` 键（见上文「空键」约定）。
+3. 更新根级 `**updated_at`**；可选在 `**{HARNESS_DIR}/notes.json**` 追加一条里程碑（**优先**于根级 `metadata.notes`，见「`notes.json`」专节）。
+
+**归档文件格式**（每个 `plan-id` 一个 JSON 文件，可多次追加 `entries`）：
+
+```json
+{
+  "plan_id": "01-data-infrastructure",
+  "schema_version": 1,
+  "entries": [
+    {
+      "id": "R1",
+      "title": "…",
+      "severity": "medium",
+      "source": "QC-#1",
+      "scope": "…",
+      "decision": "defer",
+      "owner": "@fullstack-dev",
+      "target": "…",
+      "tracking": null,
+      "lifecycle": "resolved",
+      "closed_at": "2026-04-06",
+      "closure_note": "…",
+      "closure_evidence": "PR #42 / commit …",
+      "archived_at": "2026-04-07"
+    }
+  ]
+}
+```
+
+- **首次**为该 `plan-id` 归档时创建文件；**后续**关闭项 **append** 到同一文件的 `entries`（合并时读入—追加—写回，注意 JSON 格式化与冲突）。
+- 每条归档对象 **必须**含 `**archived_at`**（迁入文件当日 `YYYY-MM-DD`），与 `closed_at` 可不同。
+- **审计**：已关闭记录**只存在于**上述文件（及 QC `reports/` 原文）；`status.json` 不再承载该条。
+- **一览**：若使用 `**metadata.tech_debt_summary`**，批量归档或关闭后应**刷新**聚合数字，与仍 open 的 R# 对齐（见「`metadata.tech_debt_summary`」专节）。
+
+### 临时原位关闭（仅短过渡）
+
+在写入归档文件**之前**，可先在 **open 列表**（根级或仅存 legacy 侧时从该处）内补全 `lifecycle` / `closed_*`（便于同一次 PR 内 diff）；**应在同一里程碑内**完成「迁入 `**{HARNESS_DIR}/archived/residuals/`** + 从主列表删除」，避免长期双写。
+
+### 遗留：`metadata.residual_findings_history`（不推荐）
+
+根级 `**residual_findings_history**` 曾用于在单文件内剪切已关闭项；**新仓库请优先**使用 `**{HARNESS_DIR}/archived/residuals/<plan-id>.json`**，以免 `status.json` 仍随历史变长。若仓库已存在 `residual_findings_history`，可由 `**@project-manager**` 择机迁到 `**{HARNESS_DIR}/archived/residuals/**` 后删除该键。
+
+### 移除（硬删除）
+
+- **禁止**对 `**open`** 条目从 `status.json` **硬删**。
+- 已归档条目**不要**从 `archived/residuals/*.json` **删除**；错关时追加更正说明条目或新开 R# 引用原 `id`。
+- 仅**误登且未进入任何留档**时，经 `**@project-manager`** 可从 `residual_findings` 删除；更稳妥为标 `**duplicate**` 后走关闭归档流程。
+
+### 查询 open 项与已归档（示例）
+
+首条 `jq` 中 `//` 右侧为 **legacy 读取路径**（键名与语义见本 skill **`SKILL.md` 开篇**）。
+
+```bash
+jq '.residual_findings["01-data-infrastructure"] // .metadata.residual_findings["01-data-infrastructure"]' .agents/status.json
+jq '.entries[] | select(.id == "R1")' .agents/archived/residuals/01-data-infrastructure.json
+jq '.metadata.tech_debt_summary' .agents/status.json
+```
+
+---
+
+## `{HARNESS_DIR}/notes.json`（可选·程序时间线）
+
+**定位**：**追加型**程序日志，记录合并收口、批量归档、`tech_debt_summary` 刷新等里程碑，**不**与 `**plans[].status` / open residual** 争 SSOT；目的是让 `**status.json` 保持短小**、仍可被 agent 按路径单独读取。
+
+**推荐结构**（字段可按项目增减）：
+
+```json
+{
+  "schema_version": 1,
+  "updated_at": "YYYY-MM-DD",
+  "entries": [
+    {
+      "at": "2026-04-08",
+      "message": "Short milestone description",
+      "plan_id": "01-data-infrastructure"
+    }
+  ]
+}
+```
+
+- `**entries**`：**按时间追加**；`plan_id` 可选（跨 plan 事件可省略或写多个说明在 `message` 内）。
+- `**updated_at`**：建议与**最后一条** `entries[].at` 同步，便于扫读。
+- **维护**：`**@project-manager`**（与写回 `status.json` 同权限节奏）。**禁止**为「改历史叙述」而重写已提交条目正文；更正走**新 `entries` 条**说明勘误。
+- **与 `plans[].notes`**：`plans[].notes` 仍是**单条计划**的短字符串（可选）；本文件承载**跨计划 / 跨里程碑**的日志，二者不重复长文。
+
+---
+
+## `metadata.tech_debt_summary`（可选·技术债一览）
+
+**定位**：在根级 `**residual_findings**`（按 `plan-id` 分列的 **open** R#）之上，提供**跨 plan 的聚合视图**，便于路线图、排期与「还有多少 open」一眼扫读。**不替代**单条 R# 的权威字段；新增/关闭 R# 时仍以根级 `residual_findings` 与 `**{HARNESS_DIR}/archived/residuals/`** 为准。
+
+**维护**：`**@project-manager`** 在重大里程碑后更新（例如 QC 波次结束、批量归档 resolved、版本封板前）。可选在 `**{HARNESS_DIR}/notes.json**` 记一条「已刷新 `tech_debt_summary`」。
+
+**推荐结构**（字段可按项目删减；`cross_cutting` 可省略）：
+
+```json
+{
+  "tech_debt_summary": {
+    "updated_at": "YYYY-MM-DD",
+    "total_open": 29,
+    "by_severity": {
+      "critical": 0,
+      "high": 10,
+      "medium": 10,
+      "low": 5,
+      "nit": 1
+    },
+    "by_target": {
+      "V1.0": 5,
+      "V1.1": 18
+    },
+    "by_plan": {
+      "domain-models": 4,
+      "cli-daemon-foundation": 11,
+      "cross-cutting": 1
+    },
+    "cross_cutting": [
+      {
+        "id": "DEBT-X1",
+        "title": "Short cross-plan theme (e.g. shared DB pooling)",
+        "severity": "high",
+        "scope": "crates/foo, crates/bar",
+        "target": "V1.1 — unified strategy",
+        "relates_to": ["CLI-R9", "SYNC-R4"]
+      }
+    ]
+  }
+}
+```
+
+- `**total_open` / `by_***`：应与当前 **open 列表**（根级 `**residual_findings**`；若仅存 legacy 侧则与该口径对齐）中所有 **open**（未归档）条目的数量与严重度**大致一致**；若有意的「跨 plan 合并视角」导致计数口径不同，在 `**{HARNESS_DIR}/notes.json`** 或 `cross_cutting` 中说明。
+- `**by_plan**`：键可为 **短标签** 或 `**plans[].id` 前缀**，与仓库约定一致即可。
+- `**cross_cutting`**：用于**跨多 plan / 多条 R#** 的主题债（架构层、重复实现等）；`**relates_to`** 列出对应 `**id**`（与 `residual_findings` 内 R# 对齐），避免与单条 R# 重复叙述时可只在此处保留总述。
+
+---
+
+## 合并前：`status.json` 须反映事实（建议门禁）
+
+在合并关闭计划相关工作的分支或打开 PR 前，`**@project-manager**`（或项目约定角色）宜核对：`plans[].status`、`plans[].metadata.gates`（若热行仍保留）、根级 `**residual_findings**`（核对是否与 legacy 侧误双写，见本 skill **`SKILL.md` 开篇**）、`**metadata.tech_debt_summary**`（若使用）、`**{HARNESS_DIR}/notes.json**`（若使用）与审查结论、CI/测试结果一致。**SSOT 与事实不一致时，不宜视为可合并**，应先修正。
+
+**常见疏漏**（与业务无关的通用项）：
+
+- 关闭或新增 R# 后 `**tech_debt_summary` 未刷新**（`total_open`、`by_severity` 与 open 列表脱节）。
+- 仅在 `**plans[].notes`** 或对话中描述 finding，**未**写入根级 `**residual_findings[<plan-id>]`**（canonical，见本 skill **`SKILL.md` 开篇**）。
+- 团队若用 `**notes.json**`（或遗留 `**metadata.notes**`）作程序时间线：重大合并或批量归档后**未**追加条目，导致后续 agent 缺少上下文。
+
+## 兼容性与键名映射（推荐）
+
+不同仓库可能使用 `id` 或 `plan_id` 作为计划键名。建议新仓统一用 `id`，并在迁移期遵循：
+
+- 读取时允许 `id` / `plan_id` 双兼容；
+- 写回时只写一种（推荐 `id`）；
+- 与目录键（如 `reports/<plan-id>/`、`residual_findings[<plan-id>]`）保持同一 canonical 值。
+
+若短期不迁移，至少在仓库的 `.agents/AGENTS.md` 写清“canonical key 使用哪一个”，避免多 agent 混写。
+
+## 常用查询示例
+
+第二条 `jq` 中 `//` 右侧含义见上文「**查询 open 项与已归档（示例）**」。
+
+```bash
+# Replace .agents with your resolved {HARNESS_DIR} if different.
+jq '.plans[] | select(.id == "01-data-infrastructure")' .agents/status.json
+jq '.residual_findings["01-data-infrastructure"] // .metadata.residual_findings["01-data-infrastructure"]' .agents/status.json
+```
+

package/harness-skills/mstar-plan-conventions/templates/README.md

@@ -0,0 +1,8 @@
+# Plan harness file templates
+
+Copy these into `{HARNESS_DIR}` when bootstrapping a project (paths resolve per `mstar-plan-conventions`).
+
+| File | Copy to | Notes |
+|------|---------|--------|
+| `status.empty.json` | `{HARNESS_DIR}/status.json` | Matches **SKILL.md** opening: root `residual_findings` only. Replace `updated_at` with the real date. |
+| `notes.empty.json` | `{HARNESS_DIR}/notes.json` | Optional program timeline. Replace `updated_at` when first edited. |

package/harness-skills/mstar-plan-conventions/templates/notes.empty.json

@@ -0,0 +1,5 @@
+{
+  "schema_version": 1,
+  "updated_at": "1970-01-01",
+  "entries": []
+}

package/harness-skills/mstar-plan-conventions/templates/status.empty.json

@@ -0,0 +1,7 @@
+{
+  "version": 1,
+  "updated_at": "1970-01-01",
+  "plans": [],
+  "residual_findings": {},
+  "metadata": {}
+}

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

@@ -0,0 +1,177 @@
+---
+name: mstar-review-qc
+description: Morning Star (启明星) QC 审查基线与 QA 验证契约 —— 三名 QC reviewer 的共享审查工作流、代码质量/安全正确性/性能可靠/可维护性清单、标准审查报告 Markdown 模板（YAML frontmatter + Findings 三档 + Source Trace + Summary + Verdict）、QC 三审分派时机（与 plan-batch 对齐）、高危变更（运维/数据/生产）最小检查、门禁规则（Approve / Request Changes / Needs Discussion）、CI 门禁补充、Residual Findings 留档门禁与关闭验证。`@qc-specialist` / `@qc-specialist-2` / `@qc-specialist-3` 开工审查前必读；`@qa-engineer` 对同 feature 做验证前必读；`@project-manager` 派发 QC 三审或 high-risk 变更审查前必读；所有涉及 QC 报告、Residual 登记或门禁判定的角色都应该优先 Read 本 skill。
+---
+
+## Load order（必读顺序）
+
+**在同一会话或任务中首次 Read 本 skill 时：必须先 Read `mstar-harness-core` skill（SKILL.md，以及 `mstar-harness-core/references/branch-and-worktree.md` 中与 `Review cwd` / `Working branch` / `Review range` 相关的章节）。** 本 skill 只定义 QC/QA **工作流与报告形态**；**谁可派 subagent**、**三审字段逐字对齐**、**同仓 worktree 与单一待审 `HEAD`** 等不变量以 **`mstar-harness-core`** 为准。冲突时 **以 `mstar-harness-core` 为准**。
+
+**摘要**：`mstar-harness-core` — QC-QA 检出与并行门禁；本 skill — 审查清单、报告模板、verdict 与 residual 留档契约。
+
+# Morning Star QC Review Baseline（QC 审查基线）
+
+本 skill 定义所有 QC 审查员的共享基线。三份 QC 角色提示词在流程、门禁与要点上应与本 skill 一致且彼此对齐：**共用正文以`mstar-roles` skill 的 `qc-specialist-shared`为准**；`-2` / `-3` 仅保留 frontmatter、开场白中的 Reviewer 编号、`## 并行审查时本 reviewer 的侧重` 一节，以及 Completion Report 模板里的 **Agent** 名。
+
+## 分派时机（与 plan / batch 对齐）
+
+- **默认**：`@project-manager` 在 **该 plan 的实现范围已由 dev team 全部交付**、准备进入预合并门禁时，分派完整 QC 三审。**同一 `plan_id` 下多 batch 滚动实现时，不默认每 batch 跑一轮全套三审**（避免 `reports/<plan-id>/` 多套报告与范围串线）；中间阶段靠自检与 PM 协调，**显式增量三审**须在 Assignment 写明（见 `mstar-plan-conventions` `references/plan-files-and-reports.md`「QC 三审触发时机」）。
+- **同仓多 worktree 并行开发**：一轮 QC 三审仍只对应 **一套** `Review cwd` + `Working branch` + `Review range` / `Diff basis`（三票逐字相同）。若成果曾分布在 **未合并** 的多条分支或多个 `HEAD`，PM **须先**完成 Git 归并到 **单一**待审分支再派 QC；**不得**指望 reviewer 自行在多个开发 worktree 之间拼凑审查范围。**推荐** PM 在并行开发开始前已建立 **plan 集成分支** 作为各轨 merge 靶（见 `mstar-harness-core` `references/branch-and-worktree.md` 同节 **「推荐默认编排：先建 plan 集成分支，再挂各 worktree」**）。细则见 `mstar-harness-core` `references/branch-and-worktree.md` **「多 worktree 并行开发与 QC / QA 的门禁衔接」**。
+- **Request Changes 后**：再审为**新波次**，落盘用新文件名（如 `-rev2` / `wave2-`），PM 汇总时标明有效波次。
+
+## 三审身份与模型独立性门禁（PM 强制）
+
+在 PM 发出 QC 三审后、进入汇总前，必须先完成以下校验：
+
+- 三个实际运行会话的角色 ID 必须分别为 `qc-specialist`、`qc-specialist-2`、`qc-specialist-3`。
+- 三个会话的运行模型应与 `opencode.json` 的对应角色配置一致。
+- 若出现“Assignment 写的是 #2/#3，但实际拉起仍为 `qc-specialist`”或模型映射不符，判定为 `dispatch invalid`，不得进入 consolidated 结论，必须重派。
+- 若宿主故障导致三审退化为同模型且无法即时修复，需在 Status Update 明确标记 `degraded tri-review` 并请求用户确认是否继续（默认不放行）。
+
+## 共享基线（所有审查员）
+
+每位 QC 审查员必须检查：
+
+- 行为回归是否已被显式确认
+- 阻塞级安全或数据一致性风险是否已被识别
+- 变更行为的测试覆盖是否充分
+- 若启用功能分支策略：变更分支与 Assignment 的 **`Working branch` / `Branch policy`** 是否一致；且审查在 Assignment 写明的 **`Review cwd` / `Worktree path`**（feature 检出上下文）上执行，而非未核对的默认 cwd；若曾同仓多流并行开发，还须核对 **`HEAD` 是否已含本 scope 全部待审提交**（见 `mstar-harness-core` `references/branch-and-worktree.md` **「多 worktree 并行开发与 QC / QA 的门禁衔接」**）
+- **三审对齐**：Assignment 已写明 **`plan_id`**（或 `N/A` + **Feature / scope label**）与 **`Review range` / `Diff basis`**；报告 **Scope** 须 **逐字回写** PM 下发的这两字段，**禁止**与同伴 reviewer 使用不同范围或不同 plan 锚点
+
+## 标准审查工作流
+
+1. **对齐待审检出（feature 上下文）**：在动手审查前，按 Assignment 进入 **`Review cwd` / `Worktree path`**（若已写明）；执行 `git rev-parse --show-toplevel`、`git branch --show-current`（或等价）确认 **当前目录即待审 feature 的检出**，且分支与 **`Working branch`** 一致。核对 Assignment 中的 **`plan_id`**（或 `N/A` + **Feature / scope label**）与 **`Review range` / `Diff basis`** 已填写；缺任一项应向 `@project-manager` 申请补全，**禁止**自行假设审查范围。后续 **`git diff` / `git log`** 必须 **按 `Review range` / `Diff basis` 可复现地覆盖待审变更**（若与本地 `HEAD` 不一致，先回报 `Blocked`）。若 Assignment 未写 `Review cwd` / `Worktree path` 但开发回报了实现用 worktree，应先向 `@project-manager` 申请补全 Assignment，**禁止**在未核对路径与分支的情况下假设在审 `main` 或其它提交。细则见 `mstar-harness-core` `references/branch-and-worktree.md`「QC 三审、QA 验证与 feature 检出上下文」。**`@qa-engineer`** 对同一 feature 做验证时须使用 Assignment 中 **同一 `Review cwd` / `Worktree path`** 及 **同一 `plan_id` + `Review range` / `Diff basis`**（见该节 QA 条款）。
+2. 用 `git diff` / `git show` 与内置 `glob` / `grep` / `read` 构建变更上下文；仅在跨模块或陌生路径需要快速导航时**可选**短调用 `@explore`。**禁止**把审查步骤、结论或清单执行外包给 `@explore`（见 `mstar-harness-core` SKILL.md「内置 `@explore` 能力边界」）。
+3. 检查 `git diff` 及相关历史；若 Assignment 启用功能分支策略，再次核对当前分支与 **`Working branch` / `Branch policy`** 一致（无授权则不应在默认分支上堆功能改动）。
+4. 运行对应语言的 lint 和静态分析。
+5. 按本 skill 审查清单进行人工审查。
+6. 产出带严重等级和证据的结构化发现。PM 将条目写入 **`{HARNESS_DIR}/status.json`** 根级 **`residual_findings[<plan-id>][]`**（canonical 见 `mstar-plan-conventions` **SKILL.md** 开篇）时，其 **`severity`** **仅允许** `mstar-plan-conventions` `references/status-and-residuals.md` 中 **「Residual findings：severity（SSOT，机器字段）」** 的枚举与映射表（报告小节 **Critical / Warning / Suggestion** → JSON 档位）；**不要**把报告标题字符串直接当作 `severity`。
+7. **报告入库（Git）**：将 QC 报告 **`.md`** 写入 `{PLAN_DIR}/reports/<plan-id>/` 后，在业务仓根执行 **`git add`**（**仅**本次报告路径）与 **`git commit`**，并在 Completion Report 给出 **真实** `git log -1 --oneline`。**禁止**仅完成 Write/Edit 而不提交（权限与例外见各 `agents/qc-specialist*.md`）。
+8. **禁止收尾套话**：报告与 commit 成功后，**不得**向终端用户追问「是否要交付报告」「下一步是否通知 PM」等；须在同一轮内输出完整 **Completion Report v2** 结束（见各 `agents/qc-specialist*.md` **「回合结束方式」**）。
+
+## 共享审查清单
+
+### 代码质量
+
+- [ ] 命名清晰且一致。
+- [ ] 职责没有过度混合。
+- [ ] 错误处理显式且可执行。
+- [ ] 注释说明意图，而非实现细节的琐碎描述。
+
+### 安全与正确性
+
+- [ ] 输入已验证，边界检查显式。
+- [ ] 无明显的注入/路径遍历/权限问题。
+- [ ] 敏感数据处理方式恰当。
+- [ ] 不变量和状态转换逻辑连贯。
+- [ ] LLM/Agent 边界：不可信输入未直接驱动特权操作；提示注入面已识别。
+
+### 性能与可靠性
+
+- [ ] 热路径避免了可避免的开销。
+- [ ] 资源生命周期处理正确。
+- [ ] 无界操作的风险已被处理。
+- [ ] 退化和失败行为可观测。
+
+### 可维护性
+
+- [ ] 契约和接口仍然易于理解。
+- [ ] 引入依赖有充分理由。
+- [ ] 破坏性变更附带迁移指引。
+- [ ] 优先复用而非重复逻辑。
+
+## 标准输出模板
+
+落盘到 **`{PLAN_DIR}/reports/<plan-id>/<plan-id>-qc#.md`** 时：文件**最上方**须为 YAML frontmatter（`report_kind`、`reviewer`、`reviewer_index`、`plan_id`、`verdict`、`generated_at` 等，见 `agents/qc-specialist*.md`），**紧接着**再写下列 Markdown 正文（可将 **Reviewer Metadata** 与 frontmatter 对齐，避免矛盾）。**Findings 下三节标题**（Critical / Warning / Suggestion）为**人类可读分类**；PM 将条目写入根级 **`residual_findings`**（见 `mstar-plan-conventions` **SKILL.md** 开篇）时的 **`severity` 机器字段**以 `mstar-plan-conventions` `references/status-and-residuals.md` **「Residual findings：severity（SSOT，机器字段）」** 为准。
+
+```markdown
+# Code Review Report
+
+## Reviewer Metadata
+- Reviewer: @qc-specialist | @qc-specialist-2 | @qc-specialist-3
+- Runtime Agent ID: {qc-specialist | qc-specialist-2 | qc-specialist-3}
+- Runtime Model: {provider/model-id}
+- Review Perspective: {role-specific primary focus}
+- Report Timestamp: {ISO-8601}
+
+## Scope
+- plan_id: {same as Assignment — or `N/A` + Feature / scope label from Assignment}
+- Review range / Diff basis: {exact copy from Assignment}
+- Working branch (verified): {name}
+- Review cwd (verified): {path from git rev-parse --show-toplevel}
+- Files reviewed: {count}
+- Commit range (if not identical to Review range line, explain): {hash..hash}
+- Tools run: {list}
+
+## Findings
+### 🔴 Critical
+- {issue} -> {fix}
+
+### 🟡 Warning
+- {issue} -> {fix}
+
+### 🟢 Suggestion
+- {improvement}
+
+## Source Trace
+- Finding ID: {F-001}
+- Source Type: {git-diff | linter | static-analysis | doc-rule | manual-reasoning}
+- Source Reference: {command/snippet/file}
+- Confidence: High | Medium | Low
+
+## Summary
+| Severity | Count |
+|----------|-------|
+| 🔴 Critical | {n} |
+| 🟡 Warning | {n} |
+| 🟢 Suggestion | {n} |
+
+**Verdict**: Approve | Request Changes | Needs Discussion
+```
+
+## 高危变更与破坏性操作（运维 / 数据 / 生产）
+
+适用于：`@ops-engineer` 主导的迁移、生产配置变更、数据删除或批量变更、证书轮转、共享环境上的破坏性脚本等。`@project-manager` 应在 Assignment 中标注 **high-risk** 并写清允许的目录与环境。
+
+**最小检查（未满足则应 `Needs Discussion` 或 `Request Changes`）**
+
+- [ ] 影响范围与维护窗口（或对用户的影响）已写明。
+- [ ] 回滚步骤可执行且已评审。
+- [ ] 备份、快照或等价恢复手段已确认（如适用）。
+- [ ] 变更与验证步骤可审计（命令、流水线或 runbook 引用，而非一次性黑箱）。
+- [ ] 涉及应用代码时仍走默认开发门禁（QC/QA），不因"只是运维"而跳过。
+
+## 门禁规则
+
+- 存在未解决的 `Critical` 或 `Warning` → `Request Changes`
+- 无 `Critical` / `Warning`，但有高影响且未定案的取舍（通常来自 Suggestion 的架构级分歧）→ `Needs Discussion`
+- 仅在 `Critical = 0` 且 `Warning = 0`（未解决项）时，方可 `Approve`
+
+### CI 门禁补充（强制）
+
+- 任何与本次变更范围相关的 CI 失败（编译、测试、lint、类型检查、构建、发布前校验）默认按 **>= Warning** 处理，进入本轮必须修复项。
+- CI 失败未修复前，不得给出 `Approve`；应按上方门禁判定为 `Request Changes`。
+- 若判断为 CI 环境波动而非代码问题，报告必须给出可复核证据（失败日志、复跑结果、隔离结论）并由 PM 明确记录处置决定；在未形成一致结论前，维持 `Needs Discussion` 或 `Request Changes`，不得直接放行。
+
+## Residual Findings 留档门禁
+
+- 当阻断项（`Critical`）修复后仍有未关闭 **Warning / Suggestion** 类问题或技术债，不得仅在对话中口头说明，必须留档；登记 **`severity`** 时遵守 `mstar-plan-conventions` `references/status-and-residuals.md` **「Residual findings：severity（SSOT，机器字段）」**。
+- **启用 plan 管理且存在 `plan-id` 时**：**待跟踪（open）** residual 的 **SSOT** 为 **`{HARNESS_DIR}/status.json`** 根级 **`residual_findings[<plan-id>]`**（与 `plans` 平级；canonical 见 `mstar-plan-conventions` **SKILL.md** 开篇）；PM 在 consolidated 决策中分配 **稳定 `id`（R1…）** 后须**写入该数组**（`source` 指回 `-qc*.md` 等）。**已关闭**条目归档至 **`{HARNESS_DIR}/archived/residuals/<plan-id>.json`**（字段与严重等级见 `mstar-plan-conventions`），与 **`{PLAN_DIR}/reports/<plan-id>/`** 交叉引用。
+- **主 plan**：仅作**人类可读索引**（可选）——复述 `id` 与摘要并指向 **`{HARNESS_DIR}/status.json`**；**不得**作为与 SSOT 脱钩的唯一登记处（见 `mstar-plan-conventions` `references/plan-files-and-reports.md`「Residual findings：权威在哪」）。
+- 可选：`@project-manager` 维护 **`metadata.tech_debt_summary`** 作为跨 plan 聚合视图（与 `residual_findings` 互补，见 `mstar-plan-conventions`）。
+- 若无 `{PLAN_DIR}`：写入项目认可的进度载体或根级 `notes`（结构化条目），仍须含 `id` 与跟踪字段。
+- 每条 residual finding 至少包含：`id`、`title`、`severity`、`source`、`scope`、`decision`（defer/accept/risk-accepted）、`owner`、`target milestone/date`、`tracking link`。
+- `Approve with residuals` 仅在无未关闭 `Critical` 时允许，且 PM 汇总结论中必须包含 residual 清单与跟踪位置。
+- 未完成 residual 留档，不应进入最终 `Done` 收口。
+
+### Residual 关闭与验证（与 `mstar-plan-conventions` 对齐）
+
+- 后续轮次中若某 R# 已修复：审查/QA 结论应**指向**可复核证据（diff、测试、复现步骤）；**`@project-manager`** 或 **`@qa-engineer`** 补全关闭字段后，将条目 **追加**至 **`{HARNESS_DIR}/archived/residuals/<plan-id>.json`**，并从 **open 列表**（根级 **`residual_findings[<plan-id>]`**；若仅存 legacy 侧则从该处）中**移除**（主列表仅保留 **open**）。
+- **`waived` / `superseded` / `duplicate`** 须在 `closure_note`（及必要时 `superseded_by`）中写清依据；豁免类应与产品/风险口径一致，不得由执行方单方面静默关闭。
+- **不得**从主列表删除仍为 **open** 的项；**不推荐**把已关闭项长期留在 **`{HARNESS_DIR}/status.json`**（应用文件归档减负，见 `mstar-plan-conventions`）。
+
+## 证据规则
+
+- Critical 发现必须包含触发条件、影响范围和修复建议。
+- 低置信度发现必须包含后续验证步骤。
+- 跨任务反复出现的发现应标记为重复模式。