@mstar-harness/opencode 0.3.1 → 0.4.0

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

@@ -0,0 +1,129 @@
+---
+name: mstar-phase-gates
+description: Morning Star (启明星) Spec-Driven 双阶段门禁 —— Prepare（`specify → clarify → plan`）、Execute（`plan(locked) → tasks → implement`）、意图门禁、clarify 核心纪律（共享理解 / 先探索 / 每问推荐答案）、hotfix 压缩路径、可验证编辑、Phase Gate 最小证据。**必须**在 PM 判定 gate、首次 implement 派单前、产品/架构参与 Prepare、或解释为何不能跳过 plan/clarify 时 Read；`@project-manager` 每轮编排非 hotfix 任务必读；`@product-manager` / `@architect` 写规格与锁 plan 时必读 Prepare 节；实现角色 Read Execute 与 hotfix 例外即可。Task category 与 `quick` 禁豁免规则仍在 `mstar-harness-core`。并行 Superpowers 短语见 `mstar-superpowers-align`。
+---
+
+## 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 未通过。
+
+### B. Execute：`plan(locked) → tasks → implement`
+
+- **`plan(locked)`** — 冻结基线；实现中出现新约束时**先回写 plan 再继续**。
+- **`tasks`** — 含依赖顺序、并行标记、完成判据；每任务可追踪到 plan 与验收标准。
+  - **并行标签**：若 PM 将 ≥2 条实现轨 **同时** 分派，须在 `Superpowers` 中写入 `dispatching-parallel-agents`；同仓 ≥2 可写并发时叠 `using-git-worktrees`（见 **`mstar-superpowers-align`** 与 **`mstar-branch-worktree`**）。
+- **`implement`** — 按 tasks 顺序执行并提交自检证据；完成进入 `InReview`；遵循 **`mstar-coding-behavior`**。
+
+### 可验证编辑与上下文纪律
+
+- **读后再改**：修改文件前以磁盘内容为准重读（`Read`/等价工具）。
+- **小步应用**：Patch 失败**禁止**在同一过时锚点连试；重读、缩小变更单元或拆步。
+- **多文件改动**：逐项核对路径与引用，避免未验证的批量替换。
+
+### Hotfix 例外
+
+- 压缩为 `specify(min) → plan(min) → implement`；必须在回报或 plan notes 补记事后 **`clarify/RCA`**。
+
+## Phase Gate Playbook
+
+本手册将 `specify -> clarify -> plan -> tasks -> implement` 变成可执行动作，供 `@project-manager`、开发与 QA 在日常交付中快速对齐。
+
+## 适用范围
+
+- 非热修（non-hotfix）任务默认强制执行全链路门禁。
+- 热修可走压缩路径，但必须补事后 `clarify/RCA` 记录。
+
+## 两阶段门禁
+
+### A. Prepare
+
+顺序：`specify -> clarify -> plan`
+
+- `specify`
+  - 目标：定义问题、范围、验收。
+  - 最小产物：问题陈述、目标用户价值、非目标、DoD 草案。
+- `clarify`
+  - 目标：收敛会影响方案或验收的歧义。
+  - 最小产物：歧义清单 + 结论；若未收敛则 `blocked`。
+  - **意图**：区分字面请求与真实目标；手段/目标混淆须在此收敛（见本 skill `SKILL.md` Intent gate）。
+  - **结构化澄清**：与用户核对歧义或决策时，`@project-manager`（及直接与用户对话的角色）在**宿主支持**时优先用 `question` 类能力拉齐输入；否则用等价结构化正文。宿主差异细则见当前宿主的 `mstar-host` skill。
+  - **`clarify` 核心纪律**（见 **`mstar-phase-gates` SKILL.md** Prepare · `clarify`）：逐方面核对至共享理解；沿设计决策树逐枝、一次一决；能探索代码库则先探索；每问附推荐答案；阶段末汇总已决与仍 open 假设。
+- `plan`
+  - 目标：给出可执行技术方案与风险控制。
+  - 最小产物：方案、模块边界/接口契约、风险与回滚、验证计划。
+  - **准入**：能书面写出真实目标、成功判据、非目标后再锁 plan（同 `SKILL.md`）。
+
+### B. Execute
+
+顺序：`plan locked -> tasks -> implement`
+
+- `plan locked`
+  - 目标：冻结本轮基线，防止边做边漂移。
+  - 最小动作：在 plan 或 notes 记录当前锁定版本（日期或 hash）。
+- `tasks`
+  - 目标：把 plan 拆成可执行任务与依赖顺序。
+  - 最小产物：任务列表、并行标记、完成判据、映射到验收标准。
+  - **PM**：若并行标记对应「多轨同时 implement」，在对外 **Status Update** 与实现 Assignment 的 **`Superpowers`** 中写入 **`dispatching-parallel-agents`**（或同义短语）；同仓多可写并发时叠 **`using-git-worktrees`**（见 `mstar-superpowers-align`）。
+- `implement`
+  - 目标：按任务执行并提交证据，进入审查。
+  - 最小产物：实现 diff、自检证据、回报与 handoff。
+  - **行为准则**：执行中遵循 `mstar-coding-behavior`（不静默假设、优先简单方案、只做与任务直接相关的手术式改动、按 `Step -> verify` 推进）。
+  - **编辑纪律**：改文件前以磁盘为准重读；Patch 失败则重读、缩小步长，禁止盲试（见 **`mstar-phase-gates` SKILL.md**「可验证编辑与上下文纪律」）。
+  - **知识库 / 迭代 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`
+  - 在 `InReview` 阶段验证实现与验收映射是否一致。
+
+## Plan 目录与审查报告（启用 `{PLAN_DIR}` 时）
+
+- 进入 `InReview` 后，QC 书面产出按 `mstar-plan-conventions` 落入 `{PLAN_DIR}/reports/<plan-id>/`（如 `*-qc1.md` … `*-qc-consolidated.md`）；勿与主 plan 文件混写为「唯一草稿」后又删，保留可追溯历史。**多 batch 的同一 plan**：完整 QC 三审**默认在整 plan dev 完成后一次**（非每 batch），见 `mstar-plan-conventions`「QC 三审触发时机」。
+- 非阻断项与后续技术债：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. `tasks` 是否完成？
+6. Assignment 是否含 **`Task category`**（实现类任务）并与 Owner 一致？
+7. 若中途出现 plan drift，是否先回写再继续？
+8. 实现说明中是否体现"最小解法 + 手术式改动 + 可验证检查"？
+
+任一项为「否」时，`Gate decision` 必须是 `blocked`。
+
+## Hotfix 例外
+
+- 允许路径：`specify(min) -> plan(min) -> implement`
+- 必须补记：
+  - 事后 `clarify/RCA`
+  - 触发条件、影响范围、修复与回滚摘要
+
+## 最小证据要求
+
+- Prepare 阶段证据：问题定义、歧义结论、plan 链接。
+- Execute 阶段证据：tasks 清单、实现自检、审查/验证证据。
+- 结论证据：不得仅写"done"，必须可复核（命令、输出、截图或复现步骤）。

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

@@ -0,0 +1,30 @@
+---
+name: mstar-plan-artifacts
+description: Morning Star plan harness artifacts — `{PLAN_DIR}` main plans and `reports/`, `{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 reports, 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 `reports/**/*.md`; `@qa-engineer` before closing R#. Verdict rules in `mstar-review-qc`; paths in `mstar-plan-conventions`.
+---
+
+## Load order（必读顺序）
+
+**首次 Read 本 skill 前：必须先 Read `mstar-harness-core`（SKILL.md），并按需 Read `mstar-plan-conventions`（路径符号）。** 涉及 Git 分支 / worktree / QC 检出 → **`mstar-branch-worktree`**。冲突时 **以 `mstar-harness-core` 为准**。
+
+## Scope（plan 目录工件）
+
+| Topic | 详见 |
+|-------|------|
+| 主 plan、reports 命名、QC 波次、residual 与 plan 索引顺序 | `references/plan-files-and-reports.md` |
+| knowledge / iterations / specs 边界与索引 | `references/knowledge-and-designs.md` |
+| Done 行瘦身 Profile A/B | `references/done-compaction.md` |
+| `status.json`、residual severity、生命周期、`jq` | `references/status-and-residuals.md` |
+
+**Out of scope:** 分支与 QC/QA 检出对齐 → **`mstar-branch-worktree`**；QC 清单与 verdict → **`mstar-review-qc`**；`{HARNESS_DIR}` 发现与初始化 → **`mstar-plan-conventions`**。
+
+## `status.json` 与 open residual（摘要）
+
+- **`{HARNESS_DIR}/status.json`**：`plans[]` 行状态 + 根级 **`residual_findings[<plan-id>]`**（open 列表 **SSOT**）。
+- **Canonical**：新登记只写根级 `residual_findings`；**`metadata.residual_findings`** 仅 legacy 读，**禁止**双写。
+- **生命周期**：open → 验证关闭 → **`archived/residuals/<plan-id>.json`**；**`severity`** 机器枚举见 reference。
+- **`notes.json`**、**`tech_debt_summary`**（可选聚合视图）。
+
+字段、severity 映射表、归档与 `jq` 示例 → **`references/status-and-residuals.md`**。
+
+**Templates：** `mstar-plan-conventions/templates/status.empty.json`、`templates/notes.empty.json`（本仓库 `skills/mstar-plan-conventions/templates/`）。

package/harness-skills/{mstar-plan-conventions → mstar-plan-artifacts}/references/done-compaction.md

@@ -1,10 +1,10 @@
 # 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` 约束。
+> **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-conventions` **SKILL.md** 开篇）宜保持有界（已关闭项应迁出至 **`{HARNESS_DIR}/archived/residuals/`**，见 `status-and-residuals.md`）。
+**背景**：多条 `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`）。本节为**可选**做法：在**不破坏可到达性**（快照文件须提交进仓库）的前提下给热文件瘦身。
 

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

@@ -0,0 +1,86 @@
+# `{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_DIR}`**（可选） | `*-delivery-compass-*`、`*-program-compass-*`、版本范围/验收/风险、遗留 `v1.*` 规划快照 | Agent handoff；**不**替代 `{SPECS_DIR}` |
+| **`{KNOWLEDGE_DIR}`**（可选） | 实现细节 SSOT、架构细则、契约说明、跨版本 tracker、性能基线 | Agent handoff；**不**覆盖 `{SPECS_DIR}` 中的规范性条款 |
+| **`{PLAN_DIR}/`** | 单 plan 主文件、`reports/`、可选 `residuals/` | 计划执行与审查留档 |
+
+
+**不应**放入 `docs/` 的内容：迭代 compass 正文、作为**特定 plan 输入/输出**的评审结论、实施笔记、未稳定规格草案、QC 报告 —— 分别落 `{ITERATION_DIR}`、`{KNOWLEDGE_DIR}`、`{SPECS_DIR}` 或 `{PLAN_DIR}/reports/`。
+
+## `{ITERATION_DIR}`（可选·迭代/版本级 compass）
+
+- **物理路径**：`**{ITERATION_DIR}/**`（推荐布局下常为 `**.agents/iterations/**`，与 `{KNOWLEDGE_DIR}`、`{PLAN_DIR}` 并列）。
+- **放什么**：某一**交付版本或迭代**的范围、里程碑、验收、风险、program 备注；命名示例 `v1.15-delivery-compass-v1.md`、`*-program-compass-*.md`；遗留非标准 `v1.*` 规划快照可保留于此并列入索引。
+- **不放什么**：可跨版本复用的实现 SSOT（进 `{KNOWLEDGE_DIR}`）；冻结产品/API 规范（进 `{SPECS_DIR}`）；单 plan 的 QC 留档（进 `{PLAN_DIR}/reports/`）。
+- **索引**：**必须**维护 `**{ITERATION_DIR}/README.md**`：至少 **Document**、**Version / iteration**、**Description**；可按「Delivery compasses」与「Legacy artifacts」分表（参考 Nexus `.agents/iterations/README.md`）。
+- **与 plan 的链接**：在 `**plans[].metadata**` 中可用 `**iteration_compass**`（单文件）或 `**iteration_refs**`（`string[]`）登记仓库内相对路径；PM 在 Assignment 点名本轮须读的 compass。
+- **维护**：`@product-manager` / `@architect` 起草；`**@project-manager**` 维护 README 与 metadata 挂接；compass 定稿后**少改多版本**（新版本优先新文件名 `v<N>` 或新 compass 文件）。
+
+## `{KNOWLEDGE_DIR}`（可选·实施知识库）
+
+- `{SPECS_DIR}` 定义：优先 `{HARNESS_DIR}/specs/`，否则 `{HARNESS_DIR}/designs/`；若两者都不存在，建议新建 `{HARNESS_DIR}/specs/`。
+- **必须**维护 `**{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}/`，**不要**与 `{KNOWLEDGE_DIR}` 中跨版本 SSOT 混放同一命名空间。
+
+## 与 `status.json` 的链接
+
+- 某 plan 的**权威设计输入**在知识库、迭代 compass 或规格目录中时，在 `**plans[].metadata**` 中登记路径，推荐使用已列标准键：`**primary_spec**`（单文件）、`**spec_refs**`（`string[]`）、`**iteration_compass**` / `**iteration_refs**`（迭代级，可选）。路径为**仓库内相对路径**（推荐布局下常写作 `**.agents/knowledge/....md**`、`**.agents/iterations/....md**` 或 `**.agents/specs/....md**`；兼容旧目录时也可为 `**.agents/designs/....md**`）。
+- 执行方在 **implement 前**须按 metadata 读取这些文件，并与主 plan 核对；不得在未读链接文档的情况下**静默偏离**其中已写明的决策（若需偏离，先回写 knowledge 或 plan 并走 PM/architect 门禁）。
+
+## 维护规则
+
+1. **新增**：按命名规则添加 `.md` → 在 `{KNOWLEDGE_DIR}/README.md` 或 `{ITERATION_DIR}/README.md` 索引表增加一行 → 在相关 `plans[].metadata` 更新 `primary_spec` / `spec_refs` / `iteration_*`（若该文档为本 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_DIR}/**`：偏 **可复用的实现向设计上下文**（架构细则、决策、分析），可被后续 plan 或多会话反复引用。
+- `**{ITERATION_DIR}/**`：偏 **某一迭代/版本** 的 compass 与规划快照，通常按版本索引而非按单 plan 长期复用。
+- 四者（reports / 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 条目为准）。
+
+
+| 与相邻目录的分工                                  | 典型内容                                                                  |
+| ----------------------------------------- | --------------------------------------------------------------------- |
+| `**{PLAN_DIR}/reports/<plan-id>/**`       | QC / review **流程留档**（`-qc*.md`、consolidated 等），只读历史链                  |
+| **本目录 `{PLAN_DIR}/residuals/<plan-id>/`** | 针对**仍 open** 的某一 R#：defer 背景、遗留原因、代码锚点、后续接手提示等**长文**                  |
+| `**{KNOWLEDGE_DIR}/**`            | 可跨 plan 复用的**实现向**设计上下文、规格修订、gap 分析（若文中顺带提到 residual，仍以 JSON + residuals 为跟踪权威） |
+| `**{ITERATION_DIR}/**`            | 迭代/版本级 compass；**不**替代 `{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***` 宿主白名单通常**不含**本目录——审查结论仍以 `**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 → mstar-plan-artifacts}/references/plan-files-and-reports.md

@@ -1,6 +1,6 @@
 # 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`** 为准。
+> **Load order（与其它 `mstar-*` skill 一致）**：依赖本 reference 排 reports / QC 波次前，须已 Read **`mstar-harness-core`** skill（SKILL.md；多 worktree 与 QC 单一 `HEAD` 见 **`mstar-branch-worktree`**）。冲突以 **`mstar-harness-core`** 为准。
 
 ## Plan 文件（`{PLAN_DIR}/<name>.md`）
 
@@ -23,7 +23,7 @@
 
 ## 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、关闭与归档流程**以该数组为准**。
+- **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、关闭与归档流程**以该数组为准**。
 - **推荐操作顺序**（避免 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** 开篇）。
@@ -36,7 +36,7 @@
 - **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」**）。**多 `plan_id` 同属一条 `primary_spec`（Spec 文档）时**：该「集成分支」在计划语义上即 **Spec 集成分支**；各 Plan 的 topic 分支 **merge 回 Spec 集成分支**，**全部 Plans 完成后** 合入 `main`/`master` **须走 PR**，见 `mstar-plan-conventions` SKILL.md **「Spec 文档驱动的分支模型」**。终局（或增量）三审派单前，PM 仍须满足 **单一待审 `Working branch` / `HEAD`** 或已按上条 **拆 scope**；**不得**假设「整 plan 一次三审」可只靠某一个开发 worktree 路径覆盖未合并的其他并行轨。
+- **同仓多 worktree 并行 dev**：**推荐**在排各 batch / 各轨 worktree 前确立 **plan 集成分支** 与各轨 topic 线及 **merge 靶**（见 `mstar-branch-worktree` **「推荐默认编排：先建 plan 集成分支，再挂各 worktree」**）。**多 `plan_id` 同属一条 `primary_spec`（Spec 文档）时**：该「集成分支」在计划语义上即 **Spec 集成分支**；各 Plan 的 topic 分支 **merge 回 Spec 集成分支**，**全部 Plans 完成后** 合入 `main`/`master` **须走 PR**，见 `mstar-plan-conventions` SKILL.md **「Spec 文档驱动的分支模型」**。终局（或增量）三审派单前，PM 仍须满足 **单一待审 `Working branch` / `HEAD`** 或已按上条 **拆 scope**；**不得**假设「整 plan 一次三审」可只靠某一个开发 worktree 路径覆盖未合并的其他并行轨。
 
 ### 多 `plan_id` 同时 `InReview`（PM 编排）
 

package/harness-skills/{mstar-plan-conventions → mstar-plan-artifacts}/references/status-and-residuals.md

@@ -1,9 +1,9 @@
 # `{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 索引」。
+> **Load order（与其它 `mstar-*` skill 一致）**：依赖本 reference 改 SSOT / residual 前，须已 Read **`mstar-harness-core`** skill（SKILL.md；同仓分支与 worktree 见 **`mstar-branch-worktree`**）。冲突以 **`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` 示例**。
+`status.json` 位于 **`{HARNESS_DIR}/status.json`**，是 **`plans[]` 行状态**与 **仍处 `open` 的 residual findings** 的**单一事实来源（SSOT）**。  
+**residual 的 canonical / legacy fallback 定义**见 **`mstar-plan-artifacts` SKILL.md**「`status.json` 与 open residual（摘要）」；本文件展开**字段、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 宜在验证或豁免决策明确后**及时关闭并归档**——节奏可按里程碑灵活安排，但**不应默认「口头说过即可」**。
@@ -128,7 +128,9 @@ QC 报告模板见 `mstar-review-qc`。把 finding 登记进根级 `**residual_f
 | `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[]） |
+| `primary_spec`                    | string                    | 主规格/设计文档路径（仓库内相对路径；**常为** `{KNOWLEDGE_DIR}/...` 或 `{SPECS_DIR}/...`，其中 `{SPECS_DIR}` 支持 `specs/` 与 `designs/`）；多文档可用 `spec_refs`（string[]） |
+| `iteration_compass`               | string                    | 可选：本轮依赖的迭代/版本 compass（`{ITERATION_DIR}/...`） |
+| `iteration_refs`                  | string[]                  | 可选：多个迭代 compass 或 program 快照路径 |
 | `qc_status` / `tests` / `commits` | string                    | **InReview / Done** 前后的可验证快照（结论摘要、测试统计、commit 提示），**非**替代正式报告文件                                                                                    |