@mstar-harness/opencode 0.3.2 → 0.4.1

package/harness-skills/{mstar-harness-core/references/phase-gate-playbook.md → mstar-phase-gates/SKILL.md}

@@ -1,4 +1,45 @@
-# Phase Gate Playbook（Morning Star）
+---
+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 在日常交付中快速对齐。
 
@@ -21,7 +62,7 @@
   - 最小产物：歧义清单 + 结论；若未收敛则 `blocked`。
   - **意图**：区分字面请求与真实目标；手段/目标混淆须在此收敛（见本 skill `SKILL.md` Intent gate）。
   - **结构化澄清**：与用户核对歧义或决策时，`@project-manager`（及直接与用户对话的角色）在**宿主支持**时优先用 `question` 类能力拉齐输入；否则用等价结构化正文。宿主差异细则见当前宿主的 `mstar-host` skill。
-  - **`clarify` 核心纪律**（见 `mstar-harness-core` SKILL.md Prepare · `clarify`）：逐方面核对至共享理解；沿设计树逐枝、一次一决；能探索代码库则先探索；每问附推荐答案；阶段末汇总已决与仍 open 假设。
+  - **`clarify` 核心纪律**（见 **`mstar-phase-gates` SKILL.md** Prepare · `clarify`）：逐方面核对至共享理解；沿设计决策树逐枝、一次一决；能探索代码库则先探索；每问附推荐答案；阶段末汇总已决与仍 open 假设。
 - `plan`
   - 目标：给出可执行技术方案与风险控制。
   - 最小产物：方案、模块边界/接口契约、风险与回滚、验证计划。
@@ -42,8 +83,8 @@
   - 目标：按任务执行并提交证据，进入审查。
   - 最小产物：实现 diff、自检证据、回报与 handoff。
   - **行为准则**：执行中遵循 `mstar-coding-behavior`（不静默假设、优先简单方案、只做与任务直接相关的手术式改动、按 `Step -> verify` 推进）。
-  - **编辑纪律**：改文件前以磁盘为准重读；Patch 失败则重读、缩小步长，禁止盲试（见 `SKILL.md`「可验证编辑与上下文纪律」）。
-  - **知识库 / 迭代 compass**：若项目在 `plans[].metadata` 中登记了 `primary_spec` / `spec_refs` / `iteration_compass` / `iteration_refs`，**开工前**须阅读并在回报中说明已对齐；规则见 `mstar-plan-conventions` 与 `references/knowledge-and-designs.md`（`{KNOWLEDGE_DIR}`、`{ITERATION_DIR}`）。
+  - **编辑纪律**：改文件前以磁盘为准重读；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`**。
 
 ## 角色职责
 
@@ -59,7 +100,7 @@
 ## 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-conventions` **SKILL.md** 开篇）；关闭后迁入 `{HARNESS_DIR}/archived/residuals/<plan-id>.json`，与 `mstar-review-qc` 一致。每条 **`severity`** 遵守 `mstar-plan-conventions`「Residual findings：severity（SSOT，机器字段）」。
+- 非阻断项与后续技术债：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）
 

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

@@ -0,0 +1,31 @@
+---
+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` |
+| 空仓库 `status.json` / `notes.json` 模板 | `templates/status.empty.json`、`templates/notes.empty.json`（见 `templates/README.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（本 skill）：** `templates/status.empty.json`、`templates/notes.empty.json` — 复制到 `{HARNESS_DIR}/`（说明见 `templates/README.md`）。

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-conventions → mstar-plan-artifacts}/references/knowledge-and-designs.md

@@ -1,6 +1,6 @@
 # `{KNOWLEDGE_DIR}`、`{ITERATION_DIR}` 与 `{SPECS_DIR}` / `residuals/` 散文（Morning Star）
 
-> **Load order（与其它 `mstar-*` skill 一致）**：依赖本 reference 维护知识库 / 迭代 compass / 规格挂接前，须已 Read **`mstar-harness-core`** skill（SKILL.md；仓库写操作与分支门禁见 `mstar-harness-core/references/branch-and-worktree.md`）。冲突以 **`mstar-harness-core`** 为准。
+> **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 目录发现」。
 

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 宜在验证或豁免决策明确后**及时关闭并归档**——节奏可按里程碑灵活安排，但**不应默认「口头说过即可」**。
@@ -51,7 +51,7 @@
 }
 ```
 
-**空仓库可复制模板**：本仓库 **`mstar-plan-conventions/templates/status.empty.json`**；可选 **`templates/notes.empty.json`** → `{HARNESS_DIR}/notes.json`。说明见 **`mstar-plan-conventions/templates/README.md`**。
+**空仓库可复制模板**：本 skill **`templates/status.empty.json`**；可选 **`templates/notes.empty.json`** → `{HARNESS_DIR}/notes.json`。说明见 **`templates/README.md`**。
 
 **已关闭条目**在以上字段之外补充：`lifecycle`、`closed_at`、`closure_note`；可选 `closure_evidence`、`superseded_by`。语义见下「Residual findings 生命周期」。
 

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

@@ -0,0 +1,8 @@
+# Plan harness file templates
+
+Copy these into `{HARNESS_DIR}` when bootstrapping a project. Path symbols (`{HARNESS_DIR}`, `{PLAN_DIR}`, …) → **`mstar-plan-conventions`**. Field semantics and residual lifecycle → **`mstar-plan-artifacts/references/status-and-residuals.md`**.
+
+| File | Copy to | Notes |
+|------|---------|--------|
+| `status.empty.json` | `{HARNESS_DIR}/status.json` | Root `residual_findings` only (see **`mstar-plan-artifacts` SKILL.md**). 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/SKILL.md

@@ -1,302 +1,87 @@
 ---
 name: mstar-plan-conventions
-description: Morning Star (启明星) harness 的计划目录约定 —— {HARNESS_DIR}、{PLAN_DIR}、{ITERATION_DIR}、{KNOWLEDGE_DIR}、{SPECS_DIR} 的发现与初始化、docs/ 与 harness 子树内容边界、status.json 的 SSOT 结构与状态权限、residual findings 登记/归档/生命周期、severity 枚举（SSOT，机器字段）、notes.json 程序时间线、tech_debt_summary 技术债一览、reports/ 审查留档命名、QC 三审触发时机、主 plan Done 标记、archived/plans Profile A/B、工期预估（仅 agent-oriented）、**Spec 集成分支 + 多 Plan 实现分支** 的 Git 对齐与 **Spec 完成后须经 PR 合入 main** 门禁。任何角色在读写 .agents/、创建/更新 plan 文件、登记 residual finding、QC/QA 报告入库、Done 收口、写工期预估时必读；`@project-manager` 编排任一含 plan 的任务前必读；实现角色开工前须读本 skill 以对齐 metadata.primary_spec/spec_refs 与 knowledge/iterations 目录。
+description: Morning Star (启明星) harness 计划目录约定 —— `{HARNESS_DIR}` / `{PLAN_DIR}` / `{ITERATION_DIR}` / `{KNOWLEDGE_DIR}` / `{SPECS_DIR}` 发现与初始化、`docs/` 与 harness 子树边界、未启用 plan 时的工作方式、Spec 集成分支与多 Plan 实现分支（merge 靶与 PR 合 main）、Superpowers `writing-plans` 落盘门限、工期预估（agent-oriented）。**必须**在读写 `.agents/`、初始化 harness、编排含 plan 的任务、或对齐 `metadata.primary_spec` 时 Read；`@project-manager` 开 plan 任务前必读。plan 文件 / status / residual / reports / knowledge → **`mstar-plan-artifacts`**；分支与 QC 检出 → **`mstar-branch-worktree`**。
 ---
 
 ## Load order（必读顺序）
 
-**在同一会话或任务中首次 Read 本 skill 时：必须先 Read `mstar-harness-core` skill（SKILL.md，以及本任务将涉及的 `mstar-harness-core/references/`，尤其是并行 / worktree / QC-QA 检出时读 `references/branch-and-worktree.md`）。** 本 skill 只约定 `{HARNESS_DIR}` / `{PLAN_DIR}`、`status.json`、residuals、reports 等**计划资产**形态；**不得**突破 harness 的状态机、门禁与路由。冲突时 **以 `mstar-harness-core` 为准**。
+**首次 Read 本 skill 前：必须先 Read `mstar-harness-core`（SKILL.md）。** 本 skill 只约定 **目录与路径**；不突破状态机与门禁。冲突时 **以 `mstar-harness-core` 为准**。
 
-**摘要**：`mstar-harness-core` — 全局 SSOT 与「Morning Star Skill 索引」；本 skill — plan 目录、SSOT JSON、归档与工期口径的专题展开。**派发 QC 或处理 `InReview` 闸门**：还须 Read **`mstar-review-qc`**（本 skill 不承载 QC 清单与 verdict 规则）。
+| 你还可能要 Read | 何时 |
+|-----------------|------|
+| `mstar-plan-artifacts` | 主 plan、reports、`status.json`、residual、InReview/QC 波次、knowledge |
+| `mstar-branch-worktree` | Assignment 写分支 / worktree / QC 检出 |
+| `mstar-review-qc` | 派 QC 三审（PM 同轮必读） |
 
-# Morning Star Plan Conventions（计划管理约定）
+## 路径符号（SSOT）
 
-本 skill 定义 Morning Star harness 中**计划（plan）目录的发现、初始化和使用规范**，所有 agent 共享此约定；角色提示词中不再重复描述，仅引用本 skill 与其 `references/`。
-
-## Harness 与 Plan 目录发现
-
-引入 **Harness 根目录** 与若干**路径符号**（与 Nexus 等采用 Morning Star 的业务仓库对齐；项目可在 `{HARNESS_DIR}/AGENTS.md` 复述下表并声明本地偏差）：
-
-| 符号 | 含义 | 默认路径 |
-|------|------|----------|
-| `{HARNESS_DIR}` | Agent 计划与编排产物根 | `.agents/` |
-| `{PLAN_DIR}` | 主 plan 正文与按 `plan-id` 的审查留档 | `{HARNESS_DIR}/plans/` |
-| `{ITERATION_DIR}` | 迭代/版本级 program compass、交付范围与遗留规划快照 | `{HARNESS_DIR}/iterations/` |
-| `{KNOWLEDGE_DIR}` | 实施细节 SSOT、可复用技术设计（**不**替代冻结规格） | `{HARNESS_DIR}/knowledge/` |
-| `{SPECS_DIR}` | 冻结规格目录别名（见下节解析） | `{HARNESS_DIR}/specs/` 或 `{HARNESS_DIR}/designs/` |
-
-- **`{HARNESS_DIR}`**：承载 SSOT、时间线、迭代 compass、知识库、归档、冻结规格等**非「单文件 plan 正文 + 审查报告」**类资产。
-- **`{PLAN_DIR}`**：**仅**存放主 plan Markdown、按 `plan-id` 分目录的 **`reports/`** 等**计划与审查留档**；**默认** `{PLAN_DIR} = {HARNESS_DIR}/plans/`。
-- **`{ITERATION_DIR}`**（可选）：**迭代/版本维度**的交付罗盘（如 `*-delivery-compass-*.md`、`*-program-compass-*.md`）、gap 分析、遗留 `v1.*` 规划快照；**不**放可跨版本复用的实现 SSOT（那些进 `{KNOWLEDGE_DIR}`）。须维护 **`{ITERATION_DIR}/README.md`** 索引（见 `references/knowledge-and-designs.md`）。
-- **`{KNOWLEDGE_DIR}`**（可选）：**实现向**长寿命技术上下文（架构细则、契约说明、跨版本 tracker、性能基线等）；须维护 **`{KNOWLEDGE_DIR}/README.md`** 索引。下文凡写 `knowledge/` 均指 **`{KNOWLEDGE_DIR}`**。
-- **`{SPECS_DIR}`**：规格文档目录别名，用于统一表示 `{HARNESS_DIR}/specs` 与 `{HARNESS_DIR}/designs` 两种标准，减少规则与模板中的硬编码路径。
-
-### `{SPECS_DIR}` 解析规则
-
-1. 若存在 `{HARNESS_DIR}/specs/`：`{SPECS_DIR} = {HARNESS_DIR}/specs/`（优先）。
-2. 否则若存在 `{HARNESS_DIR}/designs/`：`{SPECS_DIR} = {HARNESS_DIR}/designs/`（兼容旧标准）。
-3. 若两者都不存在：默认建议新建 `{HARNESS_DIR}/specs/`，并令 `{SPECS_DIR} = {HARNESS_DIR}/specs/`。
-
-> 并存兼容：当 `specs/` 与 `designs/` 同时存在时，`primary_spec` 推荐挂到 `{SPECS_DIR}`（即 `specs/`）；`spec_refs` 可同时引用两处路径。
-
-### 解析顺序（找到 harness 即停止）
-
-1. 若存在 **`.agents/`** 目录： **`{HARNESS_DIR} = .agents/`**， **`{PLAN_DIR} = .agents/plans/`**（若尚无 `plans/` 子目录，初始化时创建）。
-2. 否则若存在 **`.plans/`** 目录：**遗留同目录布局** — **`{HARNESS_DIR} = {PLAN_DIR} = .plans/`**（`status.json`、主 plan、`reports/` 等与旧版一致，共处于同一目录树）。
-3. 否则若存在 **`plans/`** 目录：**遗留同目录布局** — **`{HARNESS_DIR} = {PLAN_DIR} = plans/`**。
-4. 若以上均不存在：视为**该项目未启用 plan 管理**。此时 agent 仍可正常工作，只是不维护 plan 文档和 `status.json`，任务进度通过对话和回报传递。
-
-**并存目录**：若仓库中**同时**存在 **`.agents/`** 与 **`.plans/`**（或根目录 **`plans/`**），仍按上表**优先级 1** 采用 **`.agents/`** 作为 **`{HARNESS_DIR}`**；其余路径可能为迁移残留，宜合并或重命名，避免误读两套 harness。
-
-> **约定**：下文凡写 **`{HARNESS_DIR}/…`**、**`{PLAN_DIR}/…`**、**`{ITERATION_DIR}/…`**、**`{KNOWLEDGE_DIR}/…`** 均指上表解析后的实际路径。推荐布局下 **`{PLAN_DIR}` 绝不等于** 仓库根，而是 **`{HARNESS_DIR}` 下的 `plans/` 子目录**。
-
-## 内容边界：`docs/` 与 harness 子树（推荐）
-
-与 Nexus harness 分层一致；项目根 `AGENTS.md` 宜用短表指向本节，避免在多处维护长文。
-
-| 区域 | 典型内容 | 受众 / 权威 |
-|------|----------|-------------|
-| **`docs/`**（或项目约定的用户文档根） | 安装、quickstart、稳定架构概览、贡献指南 | 人类贡献者与终端用户；clone 后应可读 |
-| **`{SPECS_DIR}`**（可选） | 冻结 **v1-spec**、ADR、program **roadmap** — 产品/API 行为最高权威 | 全员；变更须显式版本/评审流程 |
-| **`{ITERATION_DIR}`**（可选） | 某交付版本/迭代的 **compass**（范围、里程碑、验收、风险）、gap 分析、遗留规划快照 | Agent handoff；**不**替代 `{SPECS_DIR}` |
-| **`{KNOWLEDGE_DIR}`**（可选） | 实现细节 SSOT、可复用技术设计、跨版本 tracker | Agent handoff；**不**覆盖 `{SPECS_DIR}` 中的规范性条款 |
-| **`{PLAN_DIR}/`** | 单 plan 执行：主 plan、`reports/`、可选 `residuals/` | 计划级 SSOT 与审查留档 |
-
-**不应**放入 `docs/` 的内容：作为**特定 plan 输入/输出**的评审结论、迭代 compass 正文、未稳定规格草案、QC 报告 —— 分别落 `{KNOWLEDGE_DIR}`、`{ITERATION_DIR}`、`{SPECS_DIR}` 或 `{PLAN_DIR}/reports/`（见 `references/knowledge-and-designs.md`）。
-
-## 目录布局（推荐）
-
-与审查留档、并行 QC、归档分层的典型布局如下（**推荐**：`{HARNESS_DIR}` 常为 **`.agents/`**，`{PLAN_DIR}` 常为 **`.agents/plans/`**）：
-
-```text
-{HARNESS_DIR}/                   # 默认 .agents/
-├── status.json                   # SSOT：plans[] + open residual（已关闭见 archived/residuals/）
-├── notes.json                    # 可选：程序里程碑 / 时间线（减轻 status.json 体积）
-├── specs/                        # 可选：规格主目录（推荐）；若存在则作为 {SPECS_DIR}
-├── designs/                      # 可选：兼容旧目录；当 specs/ 不存在时可作为 {SPECS_DIR}
-├── iterations/                   # 可选：{ITERATION_DIR} — 迭代/版本级 compass（见 references/knowledge-and-designs.md）
-│   └── README.md
-├── knowledge/                    # 可选：{KNOWLEDGE_DIR} — 实施知识库（见 references/knowledge-and-designs.md）
-│   └── README.md
-├── archived/                     # 可选：已关闭 residual、Done 计划行冷快照
-│   ├── residuals/
-│   │   └── <plan-id>.json
-│   ├── plans/
-│   │   └── <plan-id>.json
-│   ├── plans-done.json           # 可选（Profile B）
-│   └── plans/_index.json         # 可选索引
-└── plans/                        # {PLAN_DIR} — 主 plan、reports/，及可选 residuals/
-    ├── <plan-id>-<plan-name>.md  # 主计划文件
-    ├── reports/                  # 审查类补充报告（只读历史留档）
-    │   ├── README.md
-    │   └── <plan-id>/ …
-    └── residuals/                # 可选：open residual 散文详情（与 SSOT 配套）
-        └── <plan-id>/
-            └── <finding-id>-<short-label>.md
-```
-
-- **主计划**：技术方案、任务清单、Sign-off 仍以 **`{PLAN_DIR}/<plan-id>-<plan-name>.md`** 与 **`{HARNESS_DIR}/status.json`** 为权威。
-- **`{PLAN_DIR}/reports/`**：架构评审、QC 分报告、QC 汇总结论；**视为只读历史**，不在此反复改写同一结论（修正走新报告或回写主计划 / `status.json`）。
-- **`{PLAN_DIR}/residuals/<plan-id>/`**（可选）：对仍 **open** 的 residual 提供**长于 JSON 字段**的散文说明；**不替代**根级 `residual_findings` 的 SSOT（见上文「`status.json` 与 open residual」），见 `references/knowledge-and-designs.md`「open residual 散文详情」。
-- **`{ITERATION_DIR}`**：**版本/迭代维度**的交付罗盘与规划快照；与 `{KNOWLEDGE_DIR}`、`{SPECS_DIR}` 分工见上文「内容边界」与 `references/knowledge-and-designs.md`。
-- **`{KNOWLEDGE_DIR}`**：规格修订、架构评审产出、设计决策与 gap 分析等**实施上下文**（**非**迭代 compass 的首选落点）；与 `docs/`、`{ITERATION_DIR}` 分工见 `references/knowledge-and-designs.md`。
-- **`{SPECS_DIR}`**（可选）：规格目录别名，支持 `{HARNESS_DIR}/specs/` 与 `{HARNESS_DIR}/designs/`；用于冻结规格、少变基线或可对外参考文档（具体分工见 `references/knowledge-and-designs.md`）。
-- **residual findings（未关闭）**：**当前仍待跟踪**的条目写在 **`{HARNESS_DIR}/status.json`** 根级 `residual_findings[<plan-id>]`（canonical 见上文）；**已验证关闭**的条目迁出至 **`{HARNESS_DIR}/archived/residuals/<plan-id>.json`**，避免 `status.json` 无限膨胀。详见 `references/status-and-residuals.md`。
-
-## `status.json` 与 open residual（canonical）
-
-- **Canonical**：**`{HARNESS_DIR}/status.json`** 根级 **`residual_findings`**（`plan-id` → open 条目数组），与 **`plans`** **平级**；**新写入**只维护此处。
-- **`metadata.residual_findings`**：仅**未迁移的旧文件**上的**读取 fallback**，**不是**第二套 SSOT；**不要**为新工作再建一套嵌套映射。读取可先根级、再 fallback；关闭/迁移时勿与根级**双写**长期并存（操作与 `jq` 见 `references/status-and-residuals.md`）。
-
-## 已提交文档与计划产物的可到达性（强制建议）
-
-凡是**会进入 Git**且用于贡献者阅读或 **agent handoff** 的文档（例如根目录 `README`、`docs/`、`AGENTS.md`、主 plan 正文），以及落在 **`{HARNESS_DIR}` / `{PLAN_DIR}` 且被跟踪**的计划与报告，应满足：
-
-- **不得**引用仅在本机存在、被 `.gitignore` 排除、或 **`git clone` 后默认不存在**的路径；读者按文内引用应能在仓库内打开对应文件。
-- **不得**引用**本仓库根目录以外**的路径（例如 `~/.config/...`、用户主目录绝对路径、任意未作为子模块/子树纳入的「兄弟目录」）。若必须依赖外部上下文：**将要点摘入本仓库**，或给出**稳定、可公开访问**的 URL（并注明适用范围与版本）。
-- 违反上述约定会破坏 **onboarding** 与跨环境交接；若项目将 **`{HARNESS_DIR}`**（或遗留模式下整个 `{PLAN_DIR}`）**整体**加入 `.gitignore`，则已提交的 `docs/`、`README`、`AGENTS.md` 等**不得**把被忽略路径下的文件当作**唯一**权威引用。
-- 需要 handoff 的 plan / `{PLAN_DIR}/reports/` / **`{ITERATION_DIR}`** / **`{KNOWLEDGE_DIR}`** 宜 **Git 跟踪**；若某路径刻意不提交，则不要在已提交文档中写死为必读单一来源。
-
-## 初始化 Plan 目录
-
-当 `@project-manager` 判断某项目需要 plan 管理但尚无 plan 目录时：
-
-1. 创建 **`.agents/`** 作为 **`{HARNESS_DIR}`**（首选，对原有项目结构侵入小）。
-2. 创建 **`{PLAN_DIR}`** = **`.agents/plans/`**（子目录）。
-3. 在 **`{HARNESS_DIR}/`** 下创建 **`status.json`**：可复制本仓库 **`templates/status.empty.json`**；字段与 residual 生命周期见 `references/status-and-residuals.md`（canonical 见本 SKILL 开篇）。
-4. 可选：创建 **`{HARNESS_DIR}/notes.json`**：可复制 **`templates/notes.empty.json`**（或空 `entries: []`），用于程序里程碑，避免日后向 `status.json` 堆日志。模板索引见 **`templates/README.md`**。
-5. 创建 **`{PLAN_DIR}/reports/README.md`**，用途与命名约定与仓库内其它说明一致即可。
-6. 可选：若采用 **`{PLAN_DIR}/residuals/<plan-id>/`** 散文详情，在**首次**需要长文补充某 open R# 时再创建对应 **`residuals/<plan-id>/`** 子目录；无需为空 plan 预建占位目录。
-7. 若启用 **`{KNOWLEDGE_DIR}`**：创建目录及 **`{KNOWLEDGE_DIR}/README.md`** 空索引表（见 `references/knowledge-and-designs.md`）。
-8. 若启用 **`{ITERATION_DIR}`**：创建目录及 **`{ITERATION_DIR}/README.md`** 空索引表（delivery compass / program compass 等；见 `references/knowledge-and-designs.md`）。
-9. 可选：创建 **`{HARNESS_DIR}/specs/`**（推荐）或 **`{HARNESS_DIR}/designs/`**（兼容），并维护简短 **`README.md`**；后续统一按 `{SPECS_DIR}` 引用。
-10. **Git 策略（与项目 `AGENTS.md` 一致）**
-   - **推荐（团队交付 / agent handoff）**：**不要**将 **`{HARNESS_DIR}`** 整体加入 `.gitignore`，以便 clone 后计划与报告路径可达。
-   - **仅本机私密**：若必须 ignore 整个 **`{HARNESS_DIR}`**，则按上文「可到达性」约束已提交文档；敏感片段另用密钥或私密渠道管理。
-11. 如果项目已有 **`.plans/`** 或 **`plans/`** 目录（遗留同目录布局），**不要再创建** **`.agents/`**，直接使用已有目录作为 **`{HARNESS_DIR} = {PLAN_DIR}`**，并视需要补建 **`reports/`**、**`residuals/`**、**`{KNOWLEDGE_DIR}`**、**`{ITERATION_DIR}`**、**`archived/residuals/`**、可选 **`notes.json`** 与 `metadata` 结构。
-
-## Spec 文档驱动的分支模型（多 Plan 归属同一 Spec）
-
-当 **`metadata.primary_spec`**（及可选 **`spec_refs`**）指向**单一规格主线**，且 PM 将工作拆成 **多个 `plan_id`** 并行或串行交付时，业务仓库的 Git 拓扑建议按下述对齐，避免「实现分支直接打 main」与「多 Plan 无集成靶」两类漂移。**同仓 worktree、QC 前归并到单一 `HEAD` 等强制条款**仍以 **`mstar-harness-core`** `references/branch-and-worktree.md` 为准；本节只补充 **Spec ↔ 分支** 的命名级契约。
-
-### 分支角色
-
-| 概念 | 含义 |
+| 符号 | 默认 |
 |------|------|
-| **Spec 文档** | 该次交付冻结或主规格（常为 `{SPECS_DIR}` / `knowledge/` 下路径；与 `primary_spec` 对齐）。 |
-| **Spec 集成分支** | **一条**与「该 Spec 所覆盖的全部 Plans」对应的 **集成线**：各 Plan 实现成果 **merge 回** 此分支后，才视为该 Spec 在代码侧已集成。 |
-| **Plan 实现分支** | **每个 `plan_id`** 一条（或 PM 书面拆分的子轨）；**仅**承载该 Plan 范围内的提交与 QC/QA 前归并。 |
-
-### 工作流（默认推荐）
-
-1. **开线**：由 **`@project-manager`** 与用户确认后，建立 **Spec 集成分支**（Assignment 写明 `Working branch: create <spec-integration-branch> from <base>` 或等价；`<base>` 见 `branch-and-worktree.md`，**禁止**未授权默认）。
-2. **拆 Plan**：每个从该 Spec 拆出的 plan 使用 **各自的 Plan 实现分支**（通常 `create <plan-feature-branch> from <spec-integration-branch>` 或 PM 规定的等价拓扑）；**实现 / QA / 运维等可写角色**在本 Plan 周期内 **只操作 Assignment 写明的该 Plan 分支**（及 PM 授权的 worktree 检出），**不得**擅自把未授权提交直接堆到默认保护分支。
-3. **Plan 收口**：该 Plan 完成 **QC 三审 + QA** 等 harness 要求后，将其变更 **merge（或团队书面约定的 rebase/cherry-pick）回 Spec 集成分支**；**不是**在「仅完成单个 Plan」时默认直接 merge 进 `main`/`master`，除非 Assignment 含显式 **`Branch policy`** 例外。
-4. **与 `mstar-harness-core` 的「plan 集成分支」关系**：**同仓、同一 plan、多并行轨**时，该 skill 推荐的 **plan 集成分支** 在「多 Plan、同源 Spec」场景下 **即** 本条所述 **Spec 集成分支**；各 Plan 的 topic 线 **merge 靶** 优先为 **Spec 集成分支**，而非彼此随意交叉除非 PM 书面约定。
-
-### 合入默认保护分支（main）：必须经 PR
-
-当 **归属该 Spec 的全部 Plans** 已在计划状态上完成（且代码变更已按团队流程 **汇总到 Spec 集成分支**）时：
-
-- **禁止**将 Spec 集成分支 **直接本地 merge / fast-forward push** 到 **`main`/`master`**（或项目约定的其它默认保护分支）作为**常规完成路径**。
-- **必须**通过 **Pull Request（或宿主平台等价的受控合入流程）** 将 Spec 集成分支合入默认分支，以满足 **审查、CI、权限与审计** 等团队门禁。
-
-**窄例外**（须 **Assignment 显式** **`Branch policy: direct on <branch> — <reason>`**，与 `mstar-harness-core` 一致）：例如已批准的热修、或用户与团队书面采用的无 PR 流程。**不得**由 agent 自行认定「可以跳过 PR」。
-
-### 登记建议
-
-在 **`{HARNESS_DIR}/status.json`** 的 **`plans[].metadata`**（或根级 **`metadata.versioning`** 等团队约定节）中记录 **`spec_integration_branch`**、各 plan 的 **`working_branch`**，以及 **`merge_target`**（对 Plan 实现分支通常为 **Spec 集成分支名**，而非 `main`）。字段表见 `references/status-and-residuals.md`。
-
-## Harness 初始化蓝图（含 `AGENTS.md` 分层策略）
-
-当仓库从 0 到 1 启用 harness，建议按下面顺序初始化，避免后续出现规则散落与双轨 SSOT：
-
-1. 建 `{HARNESS_DIR}`（默认 `.agents/`）与 `{PLAN_DIR}`（默认 `.agents/plans/`），并初始化 `status.json`（见 **`templates/status.empty.json`**）、可选 `notes.json`（**`templates/notes.empty.json`**）、`reports/README.md`。
-2. 在 `{HARNESS_DIR}` 下新增 **`.agents/AGENTS.md`**（harness 子树规则），只放 **harness 资产约束**：目录语义、状态机映射、QC/QA 落盘门禁、residual 生命周期、归档策略。
-3. 在仓库根保留 **`AGENTS.md`**（项目级规则），只放 **代码库约束**：技术栈边界、构建/测试入口、安全与分支约束、规范文档路由，不复制 harness 细则。
-4. 当子目录存在显著边界（如 `contracts/`、`gateway/`、`sdk/`、`examples/`）时，再新增目录级 `AGENTS.md`，仅覆盖该目录的增量规则，禁止重复根规则或 `.agents/AGENTS.md` 细则。
-5. 每个目录级 `AGENTS.md` 必须显式写 `Source Priority`，确保冲突裁决可预测（用户指令 > 根规则 > 本目录规则 > `.agents/AGENTS.md`）。
-
-### `.agents/AGENTS.md` 应保存什么
-
-- harness 结构与路径契约：`{HARNESS_DIR}`、`{PLAN_DIR}`、`{ITERATION_DIR}`、`{KNOWLEDGE_DIR}`、`{SPECS_DIR}` 的实际路径约定；`docs/` 与 harness 子树内容边界（可引用本 skill「内容边界」表）。
-- plan/status 生命周期门禁：`Todo/InProgress/InReview/Blocked/Done` 的推进与角色权限映射。
-- QC/QA 证据契约：三审独立性、同一 `plan_id` + `Review range` 对齐、报告落盘目录与命名。
-- residual 管理契约：severity 枚举、open/closed/archived 流转、归档路径。
-- profile 选择（如 Done 压缩 Profile A/B）与仓库级采纳声明。
+| `{HARNESS_DIR}` | `.agents/` |
+| `{PLAN_DIR}` | `{HARNESS_DIR}/plans/` |
+| `{ITERATION_DIR}` | `{HARNESS_DIR}/iterations/` |
+| `{KNOWLEDGE_DIR}` | `{HARNESS_DIR}/knowledge/` |
+| `{SPECS_DIR}` | `specs/` 优先，否则 `designs/` |
 
-### 根/分目录 `AGENTS.md` 不应保存什么
+### 解析顺序（找到即停）
 
-- 动态状态：里程碑日志、当前进度、commit 列表、PR 号（应进 `status.json` / `notes.json`）。
-- 单次计划细节：某一 plan 的临时决策与实施笔记（应进主 plan、reports 或 knowledge）。
-- 与 harness SSOT 重复的完整规则正文（应引用 `.agents/AGENTS.md` 或 `mstar-*` skills）。
+1. `.agents/` → `{HARNESS_DIR}=.agents/`, `{PLAN_DIR}=.agents/plans/`
+2. 否则 `.plans/` 或 `plans/` → 遗留同目录 `{HARNESS_DIR}={PLAN_DIR}`
+3. 皆无 → 未启用 plan；进度走对话与 Completion Report
 
-### 分目录 `AGENTS.md` 何时创建（最小策略）
+并存时 **`.agents/` 优先**。
 
-- **创建**：目录有独立技术边界、独立发布面或独立风险模型（例如合约、网关、SDK）。
-- **不创建**：目录仅是实现细分且无新增约束（沿用根规则即可）。
-- **拆分深度**：默认只到一级业务边界目录；除非出现稳定且长期的二级差异，不继续下钻。
-- **体积控制**：目录级文件目标 60-150 行，强调“边界 + 禁区 + 接口命令”，避免复制大段通用规范。
+`{SPECS_DIR}`：有 `specs/` 用之；否则 `designs/`；皆无则建议新建 `specs/`。
 
-## 与 Superpowers `writing-plans`（提示词门限）
+## 内容边界（摘要）
 
-上游 **Superpowers** 插件自带的 `writing-plans` 技能默认将计划保存到 `docs/superpowers/plans/`，与本 skill `{PLAN_DIR}` 约定冲突。
-
-**Harness 门限（优于技能正文中的保存路径）**：任一角色在加载并执行 **`writing-plans`** 时，须将新计划写入按上文解析到的 **`{PLAN_DIR}`**（推荐文件名 **`<plan-id>-<plan-name>.md`**，或与项目既有 plan 命名一致；亦可用 `YYYY-MM-DD-<feature-name>.md` 等可追溯形式），**禁止**在业务仓库中默认使用 `docs/superpowers/plans/`。需要新建 **`{HARNESS_DIR}`** / **`{PLAN_DIR}`**、**`{HARNESS_DIR}/status.json`**、可选 **`{HARNESS_DIR}/notes.json`**、**`{PLAN_DIR}/reports/README.md`**、可选 **`{KNOWLEDGE_DIR}/README.md`** / **`{ITERATION_DIR}/README.md`**、Git 策略时，按上文 **「初始化 Plan 目录」**；`status.json` 的登记与状态仍由 `@project-manager` 负责。
-
-各角色提示词中对本门限有短引用（见 `mstar-roles` skill 的 `project-manager` 角色、`product-manager.md`、`architect.md`）；完整消解表见 `mstar-superpowers-align`。
-
-## `tasks` 拆解：并行标记与 Superpowers（示例）
-
-`mstar-harness-core` 要求 `tasks` 产出含 **依赖顺序**、**并行标记** 与完成判据。若 `@project-manager` 将 **≥2 条实现轨同时** 分派（同 plan、无串行依赖），须在 **Status Update** 与各实现方 Assignment 的 **`Superpowers`** 中显式写入 **`dispatching-parallel-agents`**（或 `mstar-superpowers-align` 表中同义短语）；**同一业务仓库** 上 **≥2 名可写承接方并发** 时还须叠 **`using-git-worktrees`**（或同义短语）并写明各流 **检出路径约定**（见 `agents/project-manager.md`「条件加载」、`mstar-harness-core` `references/branch-and-worktree.md`）。
-
-**编排面**：PM 须在 Status Update 发与主 plan 对齐的 **`PM Task Board`**，implement Assignment 写 **`PM Task Board coverage`**（见 `agents/project-manager.md`）。
-
-**QC pre-dispatch gate (mandatory)**: before PM dispatches any QC task (`@qc-specialist*`), PM must read **`mstar-review-qc`** skill (including relevant `references/`) **in the same coordination round**, then issue QC assignments. **Rationale**: `mstar-plan-conventions` alone does **not** carry QC checklists, report YAML, verdict rules, or tri-review field parity — skipping `mstar-review-qc` is a common cause of missed or batched-wrong QC.
-
-**InReview backlog gate (mandatory for PM orchestration)**: whenever **`{HARNESS_DIR}/status.json`** has one or more `plans[]` rows with **`status: InReview`**, PM must **not** treat plan orchestration as “implement-only”. Either **dispatch per-`plan_id` QC → QA** (per rules below) or set **`Blocked`** / user-approved deferral **in writing** in the same Status Update. Silent continuation into new implement waves while multiple plans sit `InReview` without QC artifacts is **`Blocked`-class drift**.
-
-以下为 plan 正文内 **tasks** 片段示例（字段名可按团队习惯调整，语义对齐即可）：
-
-```markdown
-## Tasks
-
-| ID | Task | Depends on | Parallel | Owner (planned) | Done criteria |
-|----|------|------------|----------|-----------------|---------------|
-| T1 | Lock export API contract (OpenAPI snippet in plan) | — | no | @architect | Contract section merged into plan |
-| T2 | Implement `GET /orders/export` | T1 | **yes** | @fullstack-dev | API + tests green locally |
-| T3 | Export entry UI + download flow | T1 | **yes** | @frontend-dev | UI wired; happy path manual check |
-
-**Parallelism**: `parallel — 2 tracks` (T2 ∥ T3 after T1).
-
-**Superpowers (for implement Assignments when plugin on)**:
-- `dispatching parallel agents` — two independent implement tracks after T1.
-- `using git worktrees` — same business repo; **Track A** worktree `…/repo-wt-api`, **Track B** `…/repo-wt-ui`; same **`Working branch`** unless PM branches per track.
-```
+| 区域 | 内容 |
+|------|------|
+| `docs/` | 人类文档：安装、贡献 |
+| `{SPECS_DIR}` | 冻结规格 / ADR |
+| `{ITERATION_DIR}` | 迭代 compass 快照 |
+| `{KNOWLEDGE_DIR}` | 实现 SSOT、可复用设计 |
+| `{PLAN_DIR}/` | 主 plan、`reports/` |
 
-Assignment 模板中的 **`Parallelism`** 行应与上表 **`Parallelism`** / **Dev routing** 一致，避免「plan 写并行、Assignment 未声明」。
+单 plan 评审结论、QC 报告 → **`{PLAN_DIR}/reports/`**，非 `docs/`。细则 → **`mstar-plan-artifacts`**。
 
-## 状态值
+## 初始化 Plan 目录
 
-- `Todo` — 待开始
-- `InProgress` — 进行中
-- `InReview` — 待审查
-- `Blocked` — 阻塞
-- `Done` — 完成
+PM 在需要持久化追踪时：
 
-## 状态更新权限
+1. 建 `.agents/`、`plans/`、`status.json`（空模板见 **`mstar-plan-artifacts/templates/status.empty.json`**）
+2. 可选 `notes.json`（模板 **`mstar-plan-artifacts/templates/notes.empty.json`**）、`reports/README.md`、`knowledge/`、`iterations/`、`specs/`
+3. Git：团队交付 **勿** ignore 整个 `{HARNESS_DIR}`（handoff 需 clone 可达）
 
-- 主 plan 内 **Markdown 任务勾选**（checkbox）规则见 `references/plan-files-and-reports.md`「主 plan 内任务清单」；与 `status.json` 的**计划级**状态字段分离管理。
-- **Done** 只能由 `@project-manager` 或 `@qa-engineer` 设置。
-- 可写盘 agent（dev / qa / ops）完成任务后可将状态更新为 `InReview`。
-- **`@product-manager`**、**`@architect`** 可写 plan 文档中各自负责部分（含本人任务 checkbox），但**不**应擅自将整条计划在 `status.json` 中改为 `InReview` 或 `Done`（除非 Assignment 明确授权且与 PM 对齐）；**`Done` 仍仅限** PM/QA。
-- **`@qc-specialist`** / **`@qc-specialist-2`** / **`@qc-specialist-3`**：可按宿主白名单**直接写入** `{PLAN_DIR}/reports/**/*.md`；**不得**改主 plan checkbox；**其它路径**仍转达 `@project-manager`。
-- **PM report-to-status gate（mandatory）**：PM receives any implementation/review/QA `Completion Report v2` and must update `{HARNESS_DIR}/status.json` in the same coordination turn (at minimum: status/progress/notes or residual linkage relevant to that report). If not updated in-turn, mark `Blocked` and do not proceed to the next dispatch.
+步骤与 `.agents/AGENTS.md` 分层 → **`references/harness-bootstrap-and-agents-layering.md`**。
 
-## 未启用 Plan 管理时的工作方式
+## Spec 驱动的分支模型（多 Plan · 同一 Spec）
 
-当项目中不存在 plan 目录时：
+- **Spec 集成分支**：各 Plan 实现 merge 回此线后再视为 Spec 在代码侧集成。
+- **Plan 实现分支**：每 `plan_id` 一条（PM 书面）。
+- **合入 `main`**：全部 Plans 完成后 **必须 PR**（窄例外见 Assignment `Branch policy`）。
+- Git 操作与 QC 单一 `HEAD` → **`mstar-branch-worktree`**。
+- `status.json` 登记 `spec_integration_branch` / `merge_target` → **`mstar-plan-artifacts`**。
 
-- `@project-manager` 通过对话和回报传递任务进度，不创建 plan 文件。
-- 各 agent 在 Completion Report 中汇报状态，不引用 plan 路径。
-- 如果任务复杂度增加到需要持久化追踪，`@project-manager` 可建议用户启用 plan 管理（按上述初始化流程创建目录）。
-- 所有门禁和审查流程照常运行，不受 plan 目录有无影响。
+## Superpowers `writing-plans` 门限
 
-## 生命周期与产物位置（摘要）
+计划写入 **`{PLAN_DIR}`**，**禁止**默认 `docs/superpowers/plans/`。见 **`mstar-superpowers-align`**。
 
-| 阶段 | 含义 | 典型产物 |
-|------|------|----------|
-| `Todo` | 已登记，未开工 | 主 plan 文件 + `status.json` 条目 |
-| `InProgress` | 实现或准备阶段进行中 | 更新的主 plan、`tasks` 勾选；编码前已读 `metadata` 指向的 **`{KNOWLEDGE_DIR}`** / **`{ITERATION_DIR}`** / `{SPECS_DIR}` 文档（若有） |
-| `InReview` | 审查与验证中 | `{PLAN_DIR}/reports/<plan-id>/` 下 `*-review.md`、`*-qc*.md`、`*-qc-consolidated.md`（见 `references/plan-files-and-reports.md`） |
-| `Done` | 已合并/收口 | 主 plan Sign-off、**`{HARNESS_DIR}/status.json`** 的 `done_at`；仍 open 的 R# 留在根级 `residual_findings`（见本 SKILL 开篇），已关闭的已迁入 **`{HARNESS_DIR}/archived/residuals/<plan-id>.json`** |
-| `Blocked` | 等待外部输入或决策 | 顶层 `notes` + 建议填 `plans[].metadata.blocked_*` / `blocked_by_plan_id` |
+## 状态与权限（摘要）
 
-## InReview 与 QC+QA：多 plan 编排硬门禁（`@project-manager`）
+`Todo` | `InProgress` | `InReview` | `Blocked` | `Done` — **`Done` 仅 PM 或 QA**。字段与 residual → **`mstar-plan-artifacts`**。主 plan checkbox → **`mstar-plan-artifacts`**。
 
-**典型反模式**：多个 **`plan_id`** 已进入 **`InReview`**，PM 仍持续派发**新的**实现单（下一 topic / 其它 plan），或试图把多个 plan **攒成一次 QC**、混用单一 `plan_id` / 单一 `Review range` —— 均偏离 harness，易导致 **QC 被跳过或审错范围**。
+## 未启用 Plan 时
 
-1. **`InReview` 语义**：该 **`plan_id`** 的实现约定范围**已交付待闸**；下一协调动作应进入 **QC 三审 →（汇总）→ QA → `Done`** 管线，或显式 **`Blocked` / 延期说明**。**禁止**长期 `InReview` 却无 `{PLAN_DIR}/reports/<plan-id>/` 下有效 `-qc*.md` 波次且无解释。
-2. **一 plan 一套三审（默认）**：每个 **`plan_id`** **单独**一组 QC Assignment：`plan_id`、`Review cwd` / `Worktree path`、`Working branch`、`Review range` / `Diff basis` **仅对应该 plan 的待审变更**；三份 QC + 后续 QA **逐字对齐同一组字段**。**禁止**用一次三审 Assignment 覆盖多个不同 `plan_id` 的合并 diff（若需「多 plan 同一发布火车」，须拆成**显式** scope 与用户同意的集成策略，仍须每 plan 可审计的 QC 产物或书面豁免）。
-3. **多 plan 同时 InReview**：允许 **并行**派发多组三审（每组不同 `plan_id`、不同 `reports/<plan-id>/`），**不**等于省略某一 plan 的 QC；也**不**要求强行「一个大 QC session」串所有 plan。若资源上必须串行，**顺序**由 PM 写明，但**每个** `plan_id` 仍须完整三审 + QA，不得合并为单套 `Review range`。
-4. **与「仅读 plan skill」的关系**：编排 `InReview`、写 QC/QA Assignment、或解释 `reports/<plan-id>/` 时，**必须**已读 **`mstar-review-qc`**（见上文 **QC pre-dispatch gate**）。**仅加载 `mstar-plan-conventions`** 不能替代 QC 基线。
+无 plan 目录：PM 用对话追踪；门禁（QC/QA）仍适用；复杂度上升时可建议初始化。
 
-## 各角色与 Plan 的关系
+## 实现角色最小阅读
 
-- **`@project-manager`**：负责发现 plan 目录、创建/登记 plan、分配任务、推进状态、Done 收口。分配时须告知 subagent plan 目录的实际路径；涉及业务 Git 仓库写操作时须在 Assignment 中写明 **`Working branch`** 或 **`Branch policy`**（见 `mstar-harness-core` `references/branch-and-worktree.md`）。启用 **`{KNOWLEDGE_DIR}`** / **`{ITERATION_DIR}`** 时维护对应 **README** 索引，并在 Assignment 中点名 **`primary_spec` / `spec_refs`**（及本轮相关的 iteration compass 路径，若适用）。**多 Plan 归属同一 Spec 时**：按上文 **「Spec 文档驱动的分支模型」** 声明 **Spec 集成分支**、各 **Plan 实现分支** 与 **merge 靶**；在 `status.json` 登记 **`spec_integration_branch` / `merge_target`**（见 `references/status-and-residuals.md`）；**全部 Plans 完成后** 合入 `main`/`master` **走 PR**，不得默认直接 merge。**维护 `status.json` 时**：若存在 **`InReview`** 行，每轮 Status Update **自检**是否对该 `plan_id` 已派或未派 QC；派发前 **Read `mstar-review-qc`**。
-- **`@architect`** / **`@product-manager`**：产出规格或评审结论若适合跨会话复用，写入 **`{KNOWLEDGE_DIR}`**、**`{ITERATION_DIR}`**（迭代 compass）或 **`{SPECS_DIR}`**（冻结规格），并更新对应 **README**；建议由 PM 在 `plans[].metadata` 挂接路径。
-- **可写盘 agent**（dev / qa / ops）：完成任务后更新主 plan 中**本人负责**的任务 checkbox（见 `references/plan-files-and-reports.md`）、相关 Sign-off 栏位，并更新 `status.json`（权限见上）。**实现前**若 `plans[].metadata` 含 `primary_spec` / `spec_refs`，须先阅读对应文件（见 `references/knowledge-and-designs.md`）。
-- **`@product-manager`**：可更新 plan 文档中需求/验收/用户故事等产品负责部分，并在交付后勾选**与之对应**的主 plan 任务 checkbox；**不得**将 `status.json` 中计划状态设为 `Done`；如需改 `progress`/`notes`，以 Assignment 为准或交由 PM 收口。
-- **`@architect`**：可更新 plan 文档中架构、接口契约、技术里程碑等章节，并在交付后勾选**与之对应**的主 plan 任务 checkbox；**不得**将 `status.json` 中计划状态设为 `Done`；一般不擅自将整条计划改为 `InReview`（与 PM 对齐）。
-- **`@qc-specialist*`**：仅可写 **`{PLAN_DIR}/reports/**/*.md`**；**不**修改主 plan checkbox；其它落盘转达 `@project-manager`。
-- **所有 agent**：完成后提醒 `@project-manager` 同步 plan 状态。
+仅需路径符号与 `plans[].metadata` 的 `primary_spec` / `spec_refs` 时：读本 SKILL 至「路径符号」+ **`mstar-plan-artifacts/references/knowledge-and-designs.md`** 即可，**不必**通读 status/residual 全文。
 
 ## References
 
-- 本 SKILL **「Spec 文档驱动的分支模型（多 Plan 归属同一 Spec）」** — Spec 集成分支、Plan 实现分支、merge 回集成线、**全部完成后经 PR 合入 main**（与 `mstar-harness-core` `references/branch-and-worktree.md` 并用）。
-- `references/status-and-residuals.md` — `{HARNESS_DIR}/status.json` SSOT 结构、`plans[].metadata` 标准字段、根级 `metadata` 字段、residual findings 的 **severity** 枚举（SSOT）、生命周期（open → closed → archived）、`notes.json` 程序时间线、`tech_debt_summary` 技术债一览、常用 jq 查询。
-- `references/knowledge-and-designs.md` — `{KNOWLEDGE_DIR}` / `{ITERATION_DIR}` / `{SPECS_DIR}` 分工与索引、`{PLAN_DIR}/residuals/<plan-id>/` open residual 散文详情、与 `reports/` 的分工。
-- `references/plan-files-and-reports.md` — 主 plan 文件命名、审查报告命名表、QC 分报告与 consolidated 保留原则、**QC 三审触发时机（单 plan · 多 batch）**、**多 `plan_id` 同时 `InReview` 的 QC 编排**、residual findings 权威位置与顺序、主 plan Markdown checkbox 规则、Done 标记方式、QC 落盘宿主权限。
-- `references/done-compaction.md` — `Done` 计划行冷快照（`{HARNESS_DIR}/archived/plans/`）、Profile A（瘦 Done 行）/ Profile B（不留 Done 行）、原子更新约束、仓库级采用声明模板、合并前 SSOT 与事实一致门禁。
-- `references/effort-estimation.md` — Agent-oriented 工期与工作量预估（T 恤尺码 + agent 会话带）；**禁止**混入人天 / FTE / 人类日历；Assignment / PRD / 架构文档字段名建议。
-- `references/harness-bootstrap-and-agents-layering.md` — 新仓初始化蓝图：`{HARNESS_DIR}` 建立步骤、根与 `.agents/AGENTS.md` 职责切分、分目录 `AGENTS.md` 触发条件与模板。
+- `references/harness-bootstrap-and-agents-layering.md` — 新仓 harness + AGENTS 分层
+- `references/effort-estimation.md` — agent-oriented 工期（禁人天/FTE）
+
+**Plan 工件细则**（主 plan、reports、`status.json`、residual、knowledge、Done 归档、**`templates/`**）→ skill **`mstar-plan-artifacts`**（`references/` 与 `templates/`）。