@mstar-harness/opencode 0.6.21 → 0.6.23

package/harness-skills/mstar-iteration/SKILL.md

@@ -0,0 +1,273 @@
+---
+name: mstar-iteration
+description: Morning Star 迭代管理 —— iteration-start（锁定迭代范围与 roadmap）、Autonomous Execute（per-plan 派发循环：分支→实现→QC→QA→Done→合并，含跨 plan 进度追踪与 push 纪律）、iteration-close（收口知识结晶 `mstar-compound`、更新 roadmap、标记迭代完成）。触发：PM 启动新迭代、跨 plan 编排时、或迭代内所有 plan Done 后。迭代 compass 落盘 `{ITERATION_DIR}/<iteration-id>-delivery-compass.md`；per-plan 状态 SSOT 仍为 `{HARNESS_DIR}/status.json`。适用于一次迭代锁定几个 spec 点（specify+clarify）、多个 plan、每个 plan 多个 tasks 的实践模式。
+---
+
+# mstar-iteration（迭代管理）
+
+## Load order
+
+**Read `mstar-harness-core` first.** Path symbols → **`mstar-plan-conventions`**. Per-plan gates → **`mstar-phase-gates`**. Knowledge crystallization → **`mstar-compound`**. On conflict, **`mstar-harness-core` wins**.
+
+## 设计思路
+
+mstar 实践模式通常是：一次迭代锁定几个 spec 点（`specify + clarify`），产生多个 `plan`，每个 plan 含多个 tasks。**per-plan 生命周期有完整的闭环**（Prepare → Execute → QC → Done）。Compound 不是 per-plan 活动——它是**迭代级收口**，在迭代内所有 plan Done 后，沉淀一轮知识。
+
+本 skill 管理三个迭代节点：
+
+```
+iteration-start → [per-plan lifecycle × N] → iteration-close → PR → merge
+     │                                               │
+     │ 锁定范围、创建 compass                        │ compound、更新 roadmap
+     │ 登记 plans 到 compass                         │ 标记迭代完成
+     │ 创建 integration 分支                          │ commit 到 integration 分支
+     │                                               │
+     └──────── iteration-drive（跨 plan 追踪）────────┘
+```
+
+**关键定位**：iteration-close 是 iteration-drive 命令的**最后一个 Phase**，在 integration 分支上执行，**完成后再创建 PR**。所有 compound 产物（knowledge docs、compass 更新、CONCEPTS.md）作为迭代交付的一部分随 PR 合入 main。一次迭代 = 一个 PR。
+
+**per-plan 状态 SSOT**：`{HARNESS_DIR}/status.json`（per-plan Todo/InProgress/InReview/Done）。
+**迭代状态 SSOT**：`{ITERATION_DIR}/<id>-delivery-compass.md` frontmatter `status` + `{ITERATION_DIR}/README.md` 索引。
+
+## 产物存储位置
+
+**SSOT**: `mstar-plan-conventions/references/artifact-storage-paths.md`。迭代 compass → `{ITERATION_DIR}/<iteration-id>-delivery-compass.md`；迭代索引 → `{ITERATION_DIR}/README.md`。
+
+---
+
+## Phase 1: iteration-start（启动迭代）
+
+PM 在新迭代启动时执行。
+
+### 1.1 收集上下文
+
+1. 读 `{ITERATION_DIR}/README.md`（若存在），了解历史迭代
+2. 读 `STRATEGY.md`（若存在），对齐战略方向（见 `mstar-strategy`）
+3. 如果有未完成的 roadmap 残余（上一迭代标记为 `next` 的 plan），纳入本次迭代范围候选
+
+### 1.2 定义迭代范围
+
+与用户/产品对齐后，确定：
+
+| 字段 | 说明 |
+|------|------|
+| **Iteration ID** | 唯一标识，推荐 `v<major>.<minor>` 或 `iter-<YYYY-QN>` |
+| **范围** | 本迭代要锁定的 spec 点（问题陈述清单） |
+| **Plans** | 预期在本迭代中完成的 plan 列表（允许中途增减） |
+| **里程碑** | 关键节点与日期 |
+| **验收标准** | 迭代级别的 Done 定义 |
+| **非目标** | 明确排除在本次迭代外的事项 |
+| **Roadmap 上下文** | 本迭代在整体 roadmap 中的位置（本批做什么 / 下批做什么） |
+
+### 1.3 创建迭代 compass
+
+写入 `{ITERATION_DIR}/<iteration-id>-delivery-compass.md`：
+
+```markdown
+---
+iteration_id: <id>
+start_date: YYYY-MM-DD
+status: active
+plans: []
+---
+
+# <iteration-id> Delivery Compass
+
+## Scope
+<本迭代要锁定的 spec 点>
+
+## Plans
+
+| plan_id | Name | Status | Notes |
+|---------|------|--------|-------|
+| <id> | <name> | Todo | |
+| ... | ... | ... | |
+
+## Milestones
+| Milestone | Target date | Status |
+|-----------|-------------|--------|
+
+## Acceptance Criteria
+- <迭代级验收项>
+
+## Non-Goals
+- <明确排除的事项>
+
+## Roadmap Position
+- 本批：<what this iteration delivers>
+- 下批：<what comes next, owner, trigger>
+```
+
+### 1.4 更新索引
+
+在 `{ITERATION_DIR}/README.md` 中添加一行（首次创建时建立表头）：
+
+| Document | Iteration | Description | Status |
+|----------|-----------|-------------|--------|
+| `<iteration-id>-delivery-compass.md` | `<iteration-id>` | `<简短描述>` | `active` |
+
+### 1.5 登记到 status.json（可选）
+
+若使用 `status.json`，在 `plans[].metadata` 中为受影响的 plan 设置 `iteration_refs`。
+
+---
+
+## Phase 2: Autonomous Execute（per-plan 派发驱动）
+
+**本 Phase 是本 skill 的核心**——定义 per-plan 派发循环的完整流程：前置条件检查、session todos、backlog 读取、integration 分支管理、per-plan dispatch 循环（分支→实现→QC→QA→Done→合并）、dispatch-first 约束、push 纪律。PM 读取本 Phase 即可执行迭代。
+
+### 2.0 前置条件（三道闸）
+
+进入 Autonomous Execute 前必须满足：
+
+1. `{HARNESS_DIR}/status.json` 中至少一条 plan `status` ≠ `Done`
+2. **Pre-implement gate = GO**：plan 已 locked、tasks ready（见 `mstar-phase-gates`）
+3. 用户意图为 **continue Execute**（`/pm`、"推进 iteration"、"继续 plans" 等）
+
+任一 false → **stop**。Prepare 未完成 → 引导先跑 `/iteration-start`。
+
+### 2.1 Session todos（派发前设护栏）
+
+每个 plan wave 启动前设定 host todos，防止范围漂移：
+
+| Host | 工具 | 最小集合 |
+|------|------|---------|
+| **Cursor** | `TodoWrite` / CreatePlan todos | 当前 `plan_id`；下一批 gates（implement/QC/QA）；分支 checkpoint |
+| **Codex** | `update_plan` / Goal UI | 同上 |
+| **OpenCode** | host todo/plan UI（如有） | 同上 |
+
+SSOT = `{HARNESS_DIR}/status.json` + `{PLAN_DIR}/`。todos 只追踪本轮下一步。
+
+### 2.2 Read backlog
+
+1. 读 `mstar-plan-artifacts` + `{HARNESS_DIR}/status.json`
+2. 列出 `status` ∈ `{Todo, InProgress, InReview, Blocked}` 的 plan（优先级：`InProgress` → `InReview` → `Todo` → unblock `Blocked`）
+3. 读 `metadata.spec_integration_branch` / `merge_target` / `primary_spec` 链接
+
+### 2.3 Integration branch
+
+1. 从 `status.json` 解析 `spec_integration_branch`
+2. **checkout 或创建**该分支；`git branch --show-current` 确认
+3. 若 metadata 缺失 → **stop**，读 `mstar-plan-conventions` + 用户确认（`mstar-branch-worktree`）；同轮写入 plan + status
+
+此分支是本迭代内所有 plan feature branch 的 merge target。
+
+### 2.4 Per-plan loop（直到全部 Done）
+
+对每个 active `plan_id`：
+
+1. **Plan start — feature branch**：Assignment 用 `Working branch: create <plan-feature-branch> from <spec_integration_branch>`。一个 plan 一条专用实现分支；内部并行 → topic branches + worktrees（`mstar-branch-worktree`）
+2. **Implement → InReview**：dispatch-only 循环（`§ 2.5`）；每次 Completion Report v2 后更新 `status.json` + 主 plan
+3. **QC → QA → Done**：三审 + QA（`mstar-review-qc`）；gate 全部通过后 PM 标记 `Done`
+4. **Plan complete — merge back**：合并 plan feature branch → `spec_integration_branch`；在下一 plan 或 QC 前解决冲突
+5. **Cross-plan 进度同步**：更新 `{ITERATION_DIR}/<iteration-id>-delivery-compass.md` 的 `## Plans` 表状态列
+6. **Next plan** 从步骤 1 继续
+
+全部 plan `Done` → 停止循环，进入 **Phase 3: iteration-close**。
+
+### 2.5 Dispatch-first（implement 派发约束）
+
+| Do | Don't |
+|----|------|
+| **Loop:** `## Assignment` → invoke → Completion Report v2 → 更新 status → next | PM 亲自 Write/Edit/Shell 产品代码 |
+| 1 Assignment ⇒ 1 invoke | Assignment 只写 markdown 不 invoke |
+| merge/branch/handoff 写入 Assignment | 因"上下文已有"而跳过 subagent |
+
+- **NEVER** implement while staying PM — 实现一律 delegate dev 角色
+- Delegate scope：`mstar-roles` → PM Execution Boundary
+- 例外：用户显式要求 PM thread 实现；hotfix（`mstar-phase-gates`）
+
+### 2.6 Push 纪律
+
+- 不因 harness 基础问题常问"是否继续"—— 决策、记录、**dispatch**
+- 未知 → 读 `mstar-*`；**`Blocked`** 或仅对 stop/secrets/不可逆范围缺口/冲突后升级
+- 实际 Git ≠ `working_branch` → **同轮**更新 plan + status
+
+---
+
+## Phase 3: iteration-close（收口迭代）
+
+PM 在迭代内全部 plan Done 后执行。**本 Phase 在 integration 分支上运行**，产出物 commit 到 integration 分支，随迭代 PR 合入 main。触发方：`commands/iteration-drive.md`（在 Autonomous Execute loop 全部 Done 后自动进入）。
+
+### 3.1 前置检查
+
+确认以下条件全部满足后，方可进入 iteration-close：
+
+- [ ] 所有 compass 中登记的 plan 状态均为 `Done`
+- [ ] 所有 plan 的 residual findings 已收口（closed 或 accepted）
+- [ ] `{ITERATION_DIR}/<iteration-id>-delivery-compass.md` 各 plan 状态已同步到最新
+- [ ] 迭代验收标准已达成或显式豁免
+
+### 3.2 知识结晶（Compound）—— 迭代级核心收口
+
+**Compound 在此执行，不在 per-plan Done 后独立执行。**
+
+PM 触发 `mstar-compound`（可批量）：
+
+1. **收集素材**：回顾本迭代所有 plan 的实现、debug、review 过程，识别以下类型的可结晶知识：
+   - 非平凡 bug 修复及其诊断过程
+   - 新引入的架构模式或约定
+   - 工具链决策及其理由
+   - 跨 plan 重复出现的模式
+   - 有价值的排错经验
+
+2. **逐条结晶**：对每条识别出的知识，调用 `mstar-compound` 写入 `{KNOWLEDGE_DIR}/<category>/<slug>.md`
+
+3. **是否值得结晶**：PM 使用 `mstar-compound` 中的「是否值得结晶」自检清单逐条评估（见 `mstar-compound` § 是否值得结晶）。
+
+4. **CONCEPTS.md 协同**：若迭代中引入了新的领域词汇，更新 `<repo-root>/CONCEPTS.md`
+
+### 3.3 更新 roadmap
+
+1. 更新 compass 中的 `## Roadmap Position`：
+   - 本批状态标记为 `delivered`
+   - 下批更新为即将开始的内容
+2. 若 `status.json` 中有 `plans[].metadata.roadmap` 字段，同步更新
+3. 若 `STRATEGY.md` 存在，可建议更新 `## Decision Log`（若有重大架构决策）
+
+### 3.4 标记迭代完成 + Commit
+
+1. 将 compass frontmatter `status` 更新为 `completed`，添加 `end_date`
+2. 更新 `{ITERATION_DIR}/README.md` 索引中该迭代行的 Status 为 `completed`
+3. compass 正文末尾追加 Compound Round Summary 和 Retrospective（见 compass 模板）
+
+**Commit 到 integration 分支**：iteration-close 产出的所有 harness 制品必须 commit 到当前 integration 分支，随迭代 PR 合入 main：
+
+```bash
+git add {ITERATION_DIR}/<id>-delivery-compass.md {ITERATION_DIR}/README.md {KNOWLEDGE_DIR}/ CONCEPTS.md
+git commit -m "chore(iteration): close <iteration-id> — compound round, roadmap update"
+git push origin <spec_integration_branch>
+```
+
+### 3.5 可选：触发 compound-refresh
+
+若本轮 compound 新增了较多知识文档，或 compass 标记了可能过时的旧知识，触发 `mstar-compound-refresh` 对有重叠的知识文档做维护。
+
+---
+
+## 迭代 compass 模板
+
+完整模板见 `references/iteration-compass-template.md`。
+
+## 与其它技能的关系
+
+| 技能 | 关系 |
+|------|------|
+| `mstar-dispatch-gates` | Dispatch rules — per-plan loop 引用 |
+| `mstar-phase-gates` | per-plan gate 判定 |
+| `mstar-plan-conventions` | 路径符号（`{ITERATION_DIR}`、`{HARNESS_DIR}`） |
+| `mstar-plan-artifacts` | `status.json` SSOT、`{ITERATION_DIR}` 索引维护 |
+| `mstar-review-qc` | QC 三审 — per-plan loop 引用 |
+| `mstar-branch-worktree` | 分支/merge/worktree 隔离 |
+| `mstar-compound` | iteration-close 中触发知识结晶 |
+| `mstar-compound-refresh` | iteration-close 后可触发知识维护 |
+| `mstar-strategy` | iteration-start 时读 `STRATEGY.md` 对齐方向 |
+
+## NOT to do
+
+- 不要在 per-plan Done 后立即单独 compound——等 iteration-close 统一做
+- 不要在 iteration-drive 中修改 per-plan gate 判定
+- 不要用 compass 替代 `status.json` 作为 plan 状态 SSOT
+- 不要在没有完成 per-plan 前置检查的情况下进入 iteration-close
+- 不要跳过 compound——如果本迭代确实没有可结晶的知识，在 compass 中写 `Compound Round Summary: 无可结晶知识（原因：<简述>）`

package/harness-skills/mstar-iteration/references/iteration-compass-template.md

@@ -0,0 +1,96 @@
+# Iteration Compass Template
+
+Copy this template when creating a new iteration compass in `{ITERATION_DIR}/`.
+
+```markdown
+---
+iteration_id: <id>
+start_date: YYYY-MM-DD
+end_date: <filled at close>
+status: active
+plans: []
+---
+
+# <iteration-id> Delivery Compass
+
+## Scope
+
+本迭代锁定的 spec 点：
+
+- <spec point 1>
+- <spec point 2>
+
+## Plans
+
+| plan_id | Name | Status | Notes |
+|---------|------|--------|-------|
+| <plan-id-1> | <plan name> | Todo | |
+| <plan-id-2> | <plan name> | Todo | |
+
+Status values: `Todo` | `InProgress` | `InReview` | `Done` | `Blocked`
+
+## Milestones
+
+| Milestone | Target date | Status |
+|-----------|-------------|--------|
+| Spec freeze | YYYY-MM-DD | pending |
+| Dev complete | YYYY-MM-DD | pending |
+| QC complete | YYYY-MM-DD | pending |
+| Iteration close | YYYY-MM-DD | pending |
+
+## Acceptance Criteria
+
+- <迭代级验收项 1>
+- <迭代级验收项 2>
+
+## Non-Goals
+
+- <明确排除项 1>
+- <明确排除项 2>
+
+## Roadmap Position
+
+- **本批（<iteration-id>）**：<what this iteration delivers>
+- **下批**：<what comes next>，触发条件：<condition>，owner：<who>
+- **最终目标**：<the long-term Done definition this iteration contributes to>
+
+## Risk Register
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|------------|
+| <risk> | Low/Med/High | Low/Med/High | <mitigation> |
+
+## Compound Round Summary
+
+> Filled at iteration-close.
+
+- 结晶文档数：<N>
+- 新增 CONCEPTS.md 条目：<N>
+- 触发 compound-refresh：<是/否>
+
+## Iteration Retrospective (minimal)
+
+> Filled at iteration-close.
+
+- 做得好的：
+- 可改进的：
+- 下迭代建议：
+```
+
+## Fields guide
+
+| Field | Required | When to fill |
+|-------|----------|-------------|
+| `iteration_id` | Yes | iteration-start |
+| `start_date` | Yes | iteration-start |
+| `end_date` | No (fill at close) | iteration-close |
+| `status` | Yes | iteration-start → `active`; iteration-close → `completed` |
+| `plans` (frontmatter) | Recommended | iteration-start (initial), iteration-drive (add new) |
+| `## Plans` table | Yes | iteration-drive (sync status), iteration-close (final) |
+| `## Milestones` | Recommended | iteration-start, iteration-drive (update) |
+| `## Acceptance Criteria` | Yes | iteration-start |
+| `## Non-Goals` | Yes | iteration-start |
+| `## Roadmap Position` | Yes | iteration-start, iteration-close (update) |
+| `## Risk Register` | Optional | iteration-start, iteration-drive (update) |
+| `## Compound Round Summary` | Yes | iteration-close |
+| `## Iteration Retrospective` | Recommended | iteration-close |

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

@@ -1,6 +1,6 @@
 ---
 name: mstar-phase-gates
-description: Morning Star (启明星) Spec-Driven 双阶段门禁 —— Prepare（`specify → clarify → plan`）、Execute（`plan(locked) → tasks → implement`）、意图门禁、长期目标优先、分批 roadmap 强制落盘、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`。
+description: Morning Star (启明星) Spec-Driven 双阶段门禁 —— Prepare（`specify → clarify → plan`）、Execute（`plan(locked) → tasks → implement`）、意图门禁、长期目标优先、分批 roadmap 强制落盘、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`。迭代级活动（iteration-start / iteration-close / compound）见 `mstar-iteration`。
 ---
 
 ## Load order（必读顺序）
@@ -50,7 +50,7 @@ description: Morning Star (启明星) Spec-Driven 双阶段门禁 —— Prepare
 - 非热修（non-hotfix）任务默认强制执行全链路门禁。
 - 热修可走压缩路径，但必须补事后 `clarify/RCA` 记录。
 
-## 两阶段门禁
+## 两阶段门禁（per-plan Playbook）
 
 ### A. Prepare
 
@@ -100,6 +100,16 @@ description: Morning Star (启明星) Spec-Driven 双阶段门禁 —— Prepare
 - `@qa-engineer`
   - 在 `InReview` 阶段验证实现与验收映射是否一致。
 
+## 迭代级活动
+
+per-plan 门禁通过后，PM 在**迭代层面**管理以下活动（不计入 per-plan gate）：
+
+- **迭代启动**（`mstar-iteration` § Phase 1 iteration-start）：锁定迭代范围（本迭代包含哪些 plan）、里程碑、验收标准，产出 `{ITERATION_DIR}/<iteration-id>-delivery-compass.md`。
+- **迭代驱动**（`mstar-iteration` § Phase 2 Autonomous Execute）：per-plan 派发循环（分支→实现→QC→QA→Done→合并），跨 plan 进度追踪，更新 compass 中各 plan 状态。
+- **迭代收口**（`mstar-iteration` § Phase 3 iteration-close）：迭代内所有 plan Done 后，执行一轮知识结晶（`mstar-compound`）沉淀迭代经验，更新 roadmap，标记迭代完成。
+
+per-plan Done 是 per-plan 的闭环终点；compound 是迭代级收口活动，不影响 per-plan 状态判定。
+
 ## Plan 目录与审查报告（启用 `{PLAN_DIR}` 时）
 
 - 进入 `InReview` 后，QC 书面产出落入 `{PLAN_DIR}/reports/<plan-id>/`（如 `qc1.md` … `qc-consolidated.md`）；**fix 后默认 targeted re-review**（原位更新同文件，不默认 `-rev2`），见 **`mstar-plan-artifacts/references/plan-files-and-reports.md`**。**多 batch**：完整三审**默认在整 plan dev 完成后一次**（非每 batch）。
@@ -118,7 +128,9 @@ description: Morning Star (启明星) Spec-Driven 双阶段门禁 —— Prepare
 9. 若中途出现 plan drift，是否先回写再继续？
 10. 实现说明中是否体现"最小耐久切片 + 手术式改动 + 可验证检查"？
 
-任一项为「否」时，`Gate decision` 必须是 `blocked`。
+**任一项为「否」时，`Gate decision` 必须是 `blocked`**。
+
+> 迭代级活动（compound / iteration-close）见 `mstar-iteration`；不属于 per-plan gate 判定项。
 
 ## Hotfix 例外
 

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

@@ -53,6 +53,7 @@
 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/`**（该处用于**计划行**冷快照）；知识库用索引状态表达生命周期即可。
+5. **结晶（Compound）**：PM 在迭代收口时（`mstar-iteration` § iteration-close）批量触发 `mstar-compound`，将整轮迭代的经验沉淀为结构化知识文档（`{KNOWLEDGE_DIR}/<category>/<slug>.md`，YAML frontmatter + 双轨模板）。compound 是迭代级活动，不在 per-plan Done 后单独执行。定期维护由 `mstar-compound-refresh` 执行。详见 **`mstar-compound`**、**`mstar-iteration`** 与 **`mstar-compound-refresh`**。
 
 ## 与 `reports/`、`{PLAN_DIR}/residuals/` 的区分
 

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

@@ -84,5 +84,6 @@ PM 在需要持久化追踪时：
 
 - `references/harness-bootstrap-and-agents-layering.md` — 新仓 harness + AGENTS 分层
 - `references/effort-estimation.md` — agent-oriented 工期（禁人天/FTE）
+- `references/artifact-storage-paths.md` — **产物存储路径 SSOT**（知识文档、CONCEPTS.md、STRATEGY.md 等落盘位置；`mstar-compound`、`mstar-compound-refresh`、`mstar-strategy` 等技能引用此表，不得本地重定义）
 
 **Plan 工件细则**（主 plan、reports、`status.json`、residual、knowledge、Done 归档、**`templates/`**）→ skill **`mstar-plan-artifacts`**（`references/` 与 `templates/`）。

package/harness-skills/mstar-plan-conventions/references/artifact-storage-paths.md

@@ -0,0 +1,46 @@
+# 产物存储路径（SSOT · 路径符号解析后）
+
+> **Authority**: `mstar-plan-conventions` `references/artifact-storage-paths.md`.
+> Symbol definitions (`{HARNESS_DIR}`, `{KNOWLEDGE_DIR}`, `{PLAN_DIR}`, etc.) → `mstar-plan-conventions` SKILL.md § 路径符号。
+> All `mstar-*` skills that produce or operate on files **must** follow this table; do not redefine paths locally.
+
+## Harness 子树内（`{HARNESS_DIR}/` 下）
+
+这些是 agent handoff 用的结构化产物，随 `.git` 追踪，不面向人类直接阅读。
+
+| 产物 | 解析后路径（默认 `.mstar/`） | 读写的技能 |
+|------|---------------------------|-----------|
+| **知识文档** | `.mstar/knowledge/<category>/<slug>.md` | `mstar-compound`（写）、`mstar-compound-refresh`（读写） |
+| **知识索引** | `.mstar/knowledge/README.md` | `mstar-compound`（写）、`mstar-compound-refresh`（读写） |
+| **主 plan** | `.mstar/plans/<plan-id>-<name>.md` | PM / `mstar-plan-artifacts` |
+| **QC 报告** | `.mstar/plans/reports/<plan-id>/qcN.md` | `mstar-review-qc` |
+| **status.json** | `.mstar/status.json` | `mstar-plan-artifacts` |
+| **迭代 compass** | `.mstar/iterations/<iteration-id>-delivery-compass.md` | `mstar-iteration`（读写） |
+| **迭代索引** | `.mstar/iterations/README.md` | `mstar-iteration`（读写） |
+| **规格** | `specs/`（优先），否则 `designs/` | `mstar-plan-artifacts` |
+| **archived residuals** | `.mstar/archived/residuals/<plan-id>.json` | `mstar-plan-artifacts` |
+
+## 仓库根目录（`<repo-root>/`，与 `.git/` 同级）
+
+这些是人类和所有 agent 的共同入口，**不在** `{HARNESS_DIR}` 子树内。
+
+| 产物 | 解析后路径 | 读写的技能 |
+|------|----------|-----------|
+| **CONCEPTS.md** | `<repo-root>/CONCEPTS.md` | `mstar-compound`（写/协同）、`mstar-compound-refresh`（reconciliation/bootstrapping） |
+| **STRATEGY.md** | `<repo-root>/STRATEGY.md` | `mstar-strategy`（读写） |
+| **AGENTS.md 更新** | `<repo-root>/AGENTS.md`（或 `CLAUDE.md`） | `mstar-compound`（可发现性检查编辑）、`mstar-strategy`（索引编辑） |
+
+## 禁止操作区域
+
+以下目录**不属于** harness 知识/策略的产出目标，skills 不得在其中写入：
+
+| 路径 | 说明 |
+|------|------|
+| `docs/` | 人类文档（安装、贡献指南等），知识产物不放此处 |
+| `{ITERATION_DIR}/` | 仅限迭代 compass，知识文档不放此处 |
+| `{SPECS_DIR}/` | 仅限冻结规格/ADR，运行时知识不放此处 |
+| `{PLAN_DIR}/reports/` | 仅限 QC 报告，知识文档不放此处 |
+
+## `<category>` 取值
+
+知识文档的 `<category>` 子目录由 `mstar-compound` 的 `references/category-mapping.md` 定义，在 `{KNOWLEDGE_DIR}` 下按需创建。示例：`runtime-errors/`、`conventions/`、`architecture-patterns/` 等。

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

@@ -49,6 +49,15 @@ description: Morning Star QC/QA review baseline — tri-review workflow, checkli
 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` **「回合结束方式」**）。
 
+### Deep Review 模式（自动触发，透镜制）
+
+QC reviewer 在开工时按 `references/deep-review-personas.md` § 触发规则自行判定是否启用 deep review（≥2 条信号即触发）。**不派发子代理**，不依赖 PM 显式标注 mode。
+
+- **触发信号**：变更规模、敏感模块、新领域、数据结构变更、plan 高风险声明、多模块耦合 —— 达 2 条即触发。
+- **审查方式**：单人加载**透镜（lens）**——结构化检查表，逐项覆盖（如 Security Lens、Auth Lens、Data Migration Lens），不派发 persona subagent（反递归红线）。
+- **透镜选择**：默认透镜 + 按触发信号追加。详见 `references/deep-review-personas.md`。
+- **报告中体现**：`## Scope` 写 `Deep review: triggered (<signals>)` + `Lenses applied: <list>`；发现归入主报告 Findings，`Source Type` 标注为 `deep-lens: <lens-name>`。
+
 ## 共享审查清单
 
 ### 代码质量

package/harness-skills/mstar-review-qc/references/deep-review-personas.md

@@ -0,0 +1,151 @@
+# QC Deep Review Lenses（审查透镜 · 单人模式）
+
+> **关键约束**：mstar 派发模型下，QC reviewer 是 PM 派发的 **leaf executor**（`Delegation: forbidden`），**禁止**自行派发任何 subagent 或 persona（`mstar-dispatch-gates` § 承接方反递归 NEVER 红线）。
+> 本文件的设计选择：**透镜（lens）而非代理（subagent）**——QC reviewer **本人**在审查时额外覆盖的检查维度，每个透镜是一组结构化问题，审查者在本地逐一回答即可。
+> 不派发子 agent，不产生额外对话轮次，不违反反递归约束。
+
+## Deep review 触发规则（自动判定，无需人工指定）
+
+QC reviewer 在开工时根据以下信号自判是否启用 deep review。满足 **≥2 条**即触发。
+
+### 触发信号
+
+| # | 信号 | 检测方式 |
+|---|------|---------|
+| S1 | **变更规模大** | `git diff --stat <Review range>` → 变更行数 ≥ 200 或 变更文件数 ≥ 8 |
+| S2 | **触及敏感模块** | diff 中包含 `auth/`、`payment/`、`security/`、`permission/`、`login/`、`migration/`、`db/migrate/`、`schema/` 路径 |
+| S3 | **首次涉足新领域** | `{KNOWLEDGE_DIR}` 中不存在 diff 触及的模块名；或 plan metadata 标记为首次实现 |
+| S4 | **数据结构变更** | diff 中包含 DDL（`CREATE TABLE`、`ALTER TABLE`、`ADD COLUMN`、schema 文件、migration 文件） |
+| S5 | **plan 显式声明高风险** | plan 正文或 `status.json` 的 plan metadata 中包含 `high-risk`、`critical-path`、`breaking-change` 标记 |
+| S6 | **多模块耦合** | diff 跨越 ≥3 个不同模块/包/目录边界 |
+
+**判定**：满足 ≥2 条 → 启用 deep review。QC reviewer 在报告 `## Scope` 节中写明判定依据（例：`Deep review: triggered (S1: 350 lines / 12 files, S2: auth/ + payment/)`）。
+
+## 透镜选择
+
+触发后，QC reviewer 根据信号匹配相关透镜。每个 reviewer 身份有默认透镜，再按触发的信号追加特定透镜。
+
+### 默认透镜（各 reviewer 始终覆盖）
+
+| Reviewer | 默认透镜 |
+|----------|---------|
+| QC1 (architecture/maintainability) | **Modularity Lens** + **Contract Lens** |
+| QC2 (security/correctness) | **Security Lens** + **Correctness Lens** |
+| QC3 (performance/reliability) | **Performance Lens** + **Reliability Lens** |
+
+### 按信号追加透镜
+
+| 触发信号 | 追加透镜 | 适用于 |
+|---------|---------|-------|
+| S2 (敏感模块) | **Auth Lens**（若涉及 auth/login）、**Data Migration Lens**（若涉及 DDL/migration）、**Input Validation Lens**（若涉及用户输入/API） | 全体 |
+| S3 (新领域) | **Standards Lens**、**Testing Lens** | 全体 |
+| S4 (数据结构变更) | **Data Migration Lens** | 全体 |
+| S5 (显式高风险) | **全部透镜**（每个 reviewer 覆盖自己身份相关的所有透镜） | 全体 |
+
+---
+
+## 透镜清单（结构化检查表）
+
+每个透镜是一组审查问题。QC reviewer 在报告中按透镜分节列出发现，每个发现标注来自哪个透镜。
+
+### Modularity Lens
+- [ ] 本次变更是否引入了新的模块依赖？方向是否合理？
+- [ ] 是否有逻辑被放在不合适的模块/层级中（如 controller 中的业务逻辑、model 中的视图逻辑）？
+- [ ] 新引入的公共接口是否职责单一、边界清晰？
+- [ ] 是否存在循环依赖或隐含的耦合将被后续变更放大？
+
+### Contract Lens
+- [ ] 任何公共 API/接口签名是否发生了不兼容变更？
+- [ ] 若有 breaking change，是否在 plan 中声明？是否有迁移说明？
+- [ ] 新增的 API 端点是否遵循现有命名和参数约定？
+- [ ] 接口返回类型是否稳定（新增字段不使用破坏已有字段解析的方式）？
+
+### Security Lens
+- [ ] 变更是否涉及认证/授权流程？session、token、permission 逻辑是否正确？
+- [ ] 是否存在未验证的用户输入被直接用于数据库查询、命令执行或文件操作？
+- [ ] 敏感数据（密钥、token、密码、PII）是否在日志/错误信息/返回值中泄露？
+- [ ] 新增的访问控制点是否覆盖了所有调用路径？
+
+### Correctness Lens
+- [ ] 错误处理是否显式、可恢复？是否有吞掉关键异常的 catch-all？
+- [ ] 边界条件是否覆盖？（空值、零值、溢出、并发冲突）
+- [ ] 状态转换逻辑是否一致？是否存在中间状态会被外部观察到？
+- [ ] 返回值/副作用是否与声明一致？
+
+### Performance Lens
+- [ ] 是否引入了 N+1 查询？新增的 ORM 调用是否有 eager loading？
+- [ ] 循环或批处理中是否有无界操作？
+- [ ] 新索引是否必要且不会造成写入性能退化？
+- [ ] 大对象/大列表是否做分页或流式处理？
+
+### Reliability Lens
+- [ ] 资源（连接、文件句柄、锁）是否在异常路径中也正确释放？
+- [ ] 外部服务调用是否有超时和重试策略？
+- [ ] 缓存失效策略是否正确（不会长期返回过期数据）？
+- [ ] 是否存在可能无限增长的结构（无界缓存、无界日志、无界队列）？
+
+### Auth Lens
+- [ ] 认证中间件是否覆盖了所有新增端点？
+- [ ] 权限检查是否在业务逻辑执行前完成（先鉴权再操作）？
+- [ ] session 生命周期管理是否正确（创建、续期、失效）？
+- [ ] 是否有权限提升路径（如 admin 操作需二次确认）？
+
+### Input Validation Lens
+- [ ] 所有外部输入（query params、body、headers）是否经过类型/范围/格式验证？
+- [ ] 是否存在可通过输入触发的路径遍历、注入或 XSS？
+- [ ] 文件上传是否有大小/类型检查？
+- [ ] API 返回的错误信息是否在暴露内部实现细节？
+
+### Data Migration Lens
+- [ ] migration 是否可回滚？`down` 方法是否存在且正确？
+- [ ] 是否对大数据量表使用了非阻塞的 migration 策略？
+- [ ] 数据迁移是否保持了一致性（不丢数据、不产生中间脏状态）？
+- [ ] 是否考虑了并发写入场景下的迁移安全性？
+
+### Error Handling Lens
+- [ ] 异常层级是否清晰（业务异常 vs 系统异常）？
+- [ ] 面向用户的错误消息是否安全（不泄露内部细节）？
+- [ ] 关键操作失败后的副作用是否被正确处理（事务回滚、补偿操作）？
+- [ ] 是否有"静默失败"的路径（错误被忽略但后续逻辑假定成功）？
+
+### Standards Lens
+- [ ] 代码风格、命名、文件组织是否符合项目已有约定？
+- [ ] 是否引入了与现有方案冲突的重复实现？
+- [ ] 新依赖的引入是否有充分理由？
+- [ ] 是否遵循了项目 `AGENTS.md` 中的维护契约？
+
+### Testing Lens
+- [ ] 对关键逻辑路径是否有测试覆盖？
+- [ ] 边界和异常路径是否被测试覆盖？
+- [ ] 是否存在仅验证 happy path 而跳过了 failure mode 的测试？
+- [ ] 集成测试是否覆盖了与外部服务的交互边界？
+
+---
+
+## 透镜发现与主审查的整合
+
+所有透镜发现归入主报告的 `## Findings` 三节（Critical / Warning / Suggestion）中，每个发现的 `Source Type` 标注为对应透镜名（如 `deep-lens: Security Lens`），与主审查者的 `manual-reasoning` 发现同等待遇。
+
+```markdown
+## Scope
+- plan_id: <id>
+- Review range: <hash..hash>
+- Deep review: triggered (S1: 280 lines / 10 files, S2: auth/ + migration/)
+- Lenses applied: Security Lens, Auth Lens, Data Migration Lens, Modularity Lens, Contract Lens
+
+## Findings
+### 🔴 Critical
+- [DS-001] Auth middleware missing on POST /api/admin/users → <fix>
+  - Source Type: deep-lens: Auth Lens
+  - Confidence: High
+```
+
+报告中无需专门统计透镜数量或列出"未应用的透镜"——报告中只出现实际应用且有发现的透镜。无任何发现的透镜不出现在报告中。
+
+## 例外：不适用 deep review 的情况
+
+即使触发信号阈值达标，以下情况 QC reviewer 仍按默认单透镜模式审查：
+
+- **Re-review（targeted re-review）**：只在原报告基础上验证修复点，不重新扩展审查范围
+- **Hotfix**：时间窗口不允许扩展审查，按 hotfix 压缩路径处理（事后在 plan notes 中补 deep review 追记）
+- **上下文限制**：宿主会话上下文不足以加载透镜内容时，标记为 `Deep review: skipped (context constraint)` 并仅执行默认审查