@mstar-harness/opencode 1.7.1 → 1.8.1

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

@@ -21,249 +21,77 @@ Knowledge that isn't captured evaporates when the session ends. Knowledge that i
 
 **SSOT**: `mstar-plan-conventions/references/artifact-storage-paths.md`。本 skill 不重定义路径；知识文档 → `{HARNESS_DIR}/knowledge/<category>/<slug>.md`，CONCEPTS.md → `<repo-root>/CONCEPTS.md`。`<category>` 取值见 `references/category-mapping.md`。
 
-## 是否值得结晶（自检清单 · 必须逐条回答）
+## 是否值得结晶（自检门禁）
 
-在调用本 skill 前，PM（或触发方）**必须**逐条回答以下问题。得分仅用于辅助决策，不替代判断。
+调用本 skill 前，PM（或触发方）**必须**对候选问题逐条自检 Q1–Q8（诊断耗时 / 非显而易见性 / 可复用性 / 项目特异性 / 既有重叠 / 架构影响 / 失败尝试价值 / 跨模块）。完整问题表、决策矩阵（Yes≥4 强烈建议；Yes=3 Lightweight；Yes≤2 跳过；Q5=Yes 高重叠不新建）与示例判定 → **`references/compound-workflow.md`**「是否值得结晶」。
 
-### 自检问题（每条回答 Yes / No / Not sure）
-
-| # | 问题 | 说明 |
-|---|------|------|
-| Q1 | 这个问题的诊断过程耗时是否 ≥ 15 分钟（或 ≥ 3 次尝试）？ | 若只是 1-2 次尝试就找到答案，可能太琐碎 |
-| Q2 | 解决方案是否涉及**非显而易见**的知识（隐含假设、框架行为、workaround）？ | 显而易见的知识无需文档化（如"少了个分号"） |
-| Q3 | 同一个开发者在未来遇到类似问题时，是否可能**再次花费相似的时间**来诊断？ | 核心问题：知识能否复用？ |
-| Q4 | 问题的**根因**是否是项目特定的（不是通用语言/框架问题）？ | 通用问题可搜索到，项目特定问题必须自己记录 |
-| Q5 | `{KNOWLEDGE_DIR}` 中是否**已有**与此高度重叠的文档？ | 若有 → 更新已有文档，不新建（见 Phase 2 重叠检测） |
-| Q6 | 此解决方案是否可能**引导未来架构决策**或成为约定？ | Knowledge track 的典型触发条件 |
-| Q7 | 此解决方案中的"**什么没起作用**"部分是否有价值？ | 失败的尝试往往是最有教学价值的部分 |
-| Q8 | 问题是否涉及** ≥ 2 个模块/组件**的交互？ | 跨模块问题最难排查，最值得记录 |
-
-### 决策矩阵
-
-| 得分 | 行动 |
-|------|------|
-| **Yes ≥ 4**（含 Q5=No） | **强烈建议结晶**。执行完整 Phase 1-7。 |
-| **Yes = 3** | **建议结晶**。使用 Lightweight 模式（Phase 1 单遍）。 |
-| **Yes ≤ 2** | **跳过**。在 conversation/Completion Report 中注明"跳过结晶（<简述原因>）"。 |
-| **Q5 = Yes（高重叠）** | 无论其它得分如何，**不要新建**。执行 Phase 2 重叠检测，更新已有文档即可。 |
-| **任一 Not sure** | 倾向于回答者的默认判断。若 Q1-Q4 有 ≥ 2 个 Yes，仍建议结晶。 |
-
-### 示例判定
-
-```
-Q1: Yes — debug 了 40 分钟
-Q2: Yes — ActiveRecord 的 counter_cache 在 after_destroy 回调中的时序问题
-Q3: Yes — 下次遇到类似时序问题仍会踩坑
-Q4: Yes — 是项目特有 model 结构导致的
-Q5: No  — grep 了 knowledge/ 无匹配
-Q6: No  — 纯 bug 修复
-Q7: Yes — 第一次尝试了手动更新 counter 导致数据不一致
-Q8: No  — 只涉及一个 model
-→ Yes = 5 → 强烈建议结晶（Bug track）
-```
+**快判**：Q5 高重叠 → 更新已有文档，**不新建**；其余按决策矩阵 Yes 数。
 
 ## Integration with mstar lifecycle
 
-Compound 在迭代收口时触发（`mstar-iteration` § iteration-close），不在 per-plan Done 后单独执行：
-
-```
-iteration-start → [plan lifecycle × N: specify→...→Done] → iteration-close
-                                                                  │
-                                                             mstar-compound
-                                                             (per-iteration round)
-                                                                  │
-                                                             {KNOWLEDGE_DIR}
-                                                                  │
-                                               feeds back into next iteration's specify / plan
-```
-
-迭代内所有 plan Done 后，PM 回顾整轮迭代中产生的可结晶知识，批量 compound。per-plan Done 是 per-plan 的闭环终点；compound 是迭代级收口活动。
+Compound 在迭代收口时触发（`mstar-iteration` § iteration-close），不在 per-plan Done 后单独执行：`iteration-start → [plan lifecycle × N] → iteration-close → mstar-compound（per-iteration round）→ {KNOWLEDGE_DIR} → feeds next iteration's specify/plan`。迭代内所有 plan Done 后，PM 回顾整轮迭代可结晶知识，批量 compound。per-plan Done 是 per-plan 闭环终点；compound 是迭代级收口活动。
 
 ### Iteration package promotion（iteration-close 强制盘点）
 
-正式迭代收口时，compound **除** plan 实现/debug/review 素材外，**必须**盘点当前迭代的 package：
+正式迭代收口时，compound **除** plan 实现/debug/review 素材外，**必须**盘点当前迭代 package。
 
 **路径**：`{ITERATION_DIR}/<iteration-id>/**`（含 `guides/`、`specs/`、扁平 `.md`；**默认排除** `delivery-compass.md` 除非 PM 显式纳入。Legacy 根目录 `*-delivery-compass.md` 同理排除）。
 
 | 步骤 | 动作 |
 |------|------|
-| 1. Inventory | 列出 package 下全部 `.md`（除默认排除的 compass）；读各文件 + package `README.md`（若有） |
+| 1. Inventory | 列出 package 下全部 `.md`（除默认排除 compass）；读各文件 + package `README.md`（若有） |
 | 2. Triage | 每篇：**Promote** / **Keep snapshot** / **Skip**（理由写入 compound 摘要） |
 | 3. Promote | 值得跨迭代复用 → 走 Q1–Q8（或轻量判定）→ Phase 2 重叠检测 → Phase 3–6 **结构化重写**进 `{KNOWLEDGE_DIR}/`（**禁止**无改写整文件复制） |
 | 4. Trace | 源文件顶栏或 package README：`Promoted to: <knowledge-path>`；`{KNOWLEDGE_DIR}/README.md` 的 Source 可记 `iteration:<iteration-id>/<relpath>` |
 | 5. Summary | PM 写入 compass `## Compound Round Summary`：提升篇数、保留快照、跳过及原因 |
 
-**Promote 典型**：迭代 spec 已验证且指导未来实现；guide 含非显而易见的过程知识或失败尝试。
-
-**Keep snapshot**：仅迭代史、已被 `{SPECS_DIR}/` 取代的草案、或自检 ≤2 Yes 的琐碎笔记。
+**Promote 典型**：迭代 spec 已验证且指导未来实现；guide 含非显而易见过程知识或失败尝试。**Keep snapshot**：仅迭代史、已被 `{SPECS_DIR}/` 取代的草案、或自检 ≤2 Yes 的琐碎笔记。边界 SSOT → **`mstar-iteration/references/iteration-artifact-boundaries.md`**。
 
-边界 SSOT → **`mstar-iteration/references/iteration-artifact-boundaries.md`**。
+## When to use / Skip
 
-## When to use (trigger)
+**Use**：迭代收口（`mstar-iteration` § iteration-close）批量回顾；独立触发（非迭代或紧急，任何非平凡问题解决后）；重大 bug 修复后（`mstar-iteration` 未启用时手动）。
 
-- **迭代收口时**（`mstar-iteration` § iteration-close）：PM 批量回顾所有 plan 的产物
-- **独立触发**（非迭代模式或紧急情况）：任何非平凡问题解决后，PM 或开发者手动触发
-- **Debug 后**：`mstar-iteration` 尚未启用时，重大 bug 修复后手动触发
-
-### Skip when
-
-- 自检清单判定 ≤ 2 个 Yes
-- Q5 高重叠（应更新已有文档而非新建）
-- 纯机械性工作：格式化、依赖升级、typo 修复
-- 问题仍在进行中或方案未经验证
+**Skip**：自检 ≤2 Yes；Q5 高重叠（更新已有而非新建）；纯机械工作（格式化、依赖升级、typo）；问题未经验证。
 
 ## Two tracks
 
-The skill classifies work into one of two tracks based on problem type:
-
 | Track | What it captures | Section structure |
 |-------|-----------------|-------------------|
 | **Bug** | Incident-level fix — "X broke, here's why and how we fixed it" | Problem, Symptoms, What Didn't Work, Solution, Why This Works, Prevention |
 | **Knowledge** | Durable guidance — "this is how we do X, and why" | Context, Guidance, Why This Matters, When to Apply, Examples |
 
-Track is determined by `problem_type`. See `references/category-mapping.md` for the full mapping.
+Track 由 `problem_type` 决定，完整映射见 `references/category-mapping.md`。
 
 ## Execution modes
 
 | Mode | When | Behavior |
 |------|------|----------|
-| **Full** (default) | Most cases | Dispatches research subagents for context analysis, solution extraction, and overlap detection |
+| **Full** (default) | Most cases | Dispatches research subagents for context analysis, solution extraction, overlap detection |
 | **Lightweight** | Simple fixes, context-tight sessions | Single-pass documentation, no subagents, faster |
 
 In Cursor, Full mode dispatches subagents via Task tool. PM selects mode.
 
-## Phase 1: Gather context
-
-Read the conversation history **and**, when `iteration_id` is known, scan **`{ITERATION_DIR}/<iteration-id>/`** package per **Iteration package promotion** above.
-
-Understand:
-- What problem was solved (the concrete issue)
-- What was tried and didn't work
-- What the working solution was
-- Why the solution works (root cause)
-- Which files/modules were involved
-- The plan_id if applicable (link to `status.json`)
-
-If `{KNOWLEDGE_DIR}/README.md` exists, scan its index for related existing documents.
-
-Classify the problem into a track (bug vs knowledge) and category using `references/category-mapping.md`.
-
-## Phase 2: Overlap detection
-
-Before creating a new doc, check if an existing doc covers the same ground:
-
-1. Extract keywords from the problem (module names, error messages, technical terms)
-2. Search `{KNOWLEDGE_DIR}/**/*.md` using frontmatter fields (`module:`, `tags:`, `problem_type:`)
-3. Score overlap across dimensions: problem statement, root cause, solution approach, referenced files, prevention
-
-| Overlap | Action |
-|---------|--------|
-| **High** (4-5 dimensions match) | **Update** the existing doc with fresher context instead of creating a new one. Add `last_updated` field. |
-| **Moderate** (2-3 dimensions match) | Create new doc; flag for consolidation review (potential `mstar-compound-refresh` trigger) |
-| **Low/None** | Create new doc normally |
-
-## Phase 3: Write the document
-
-### 3.1 Determine path
-
-Category → directory under `{KNOWLEDGE_DIR}/`. Examples:
-- Bug track: `build-errors/`, `runtime-errors/`, `performance-issues/`, `database-issues/`, `security-issues/`, `integration-issues/`
-- Knowledge track: `architecture-patterns/`, `design-patterns/`, `conventions/`, `workflow-patterns/`, `tooling-decisions/`, `best-practices/`
-
-Filename: `<sanitized-slug>.md` (lowercase, hyphen-separated, no date prefix).
-
-### 3.2 Frontmatter
-
-Required fields for both tracks (SSOT: `references/schema.yaml`):
-
-```yaml
----
-module: <area>
-date: YYYY-MM-DD
-problem_type: <enum value>
-category: <directory name>
-severity: critical|high|medium|low
-plan_id: <optional, link to status.json>
-tags: [<keywords>]
----
-```
-
-Bug-track adds: `symptoms`, `root_cause`, `resolution_type`.
-Knowledge-track adds: `applies_when` (optional).
-
-### 3.3 Body
-
-Follow the section structure from `assets/resolution-template.md` for the determined track.
-
-### 3.4 Validate
-
-After writing, validate the YAML frontmatter:
-- `---` delimiters are correct
-- All required fields present
-- Enum values match allowed values
-- `date` is YYYY-MM-DD format
-- Array fields use `[item1, item2]` syntax
-
-## Phase 4: Discoverability check
-
-Check whether the project's `AGENTS.md` or `CLAUDE.md` would lead a future agent to discover `{KNOWLEDGE_DIR}`.
-
-If `{KNOWLEDGE_DIR}` is not mentioned in the root instruction file, propose the smallest addition that surfaces the knowledge store. Example:
-
-```markdown
-- `{HARNESS_DIR}/knowledge/` — captured solutions and reusable patterns
-```
-
-Ask for user consent before applying (PM can approve). If the user declines, the doc is still written — only the discoverability edit is skipped.
-
-## Phase 5: CONCEPTS.md synergy
+## Workflow skeleton（Phase 1–7）
 
-If the captured learning introduces or clarifies a domain term whose meaning is project-specific and not obvious to a newcomer, propose adding it to `CONCEPTS.md` at the repo root.
+完整步骤细节（Gather context / Overlap detection / Write document 含 frontmatter schema + path + validate / Discoverability check / CONCEPTS.md synergy / Update indexes / Refresh trigger）→ **`references/compound-workflow.md`**。每 Phase 一个关键决策：
 
-Read `references/concepts-vocabulary.md` for inclusion rules. Only propose when the term meets the qualifying bar:
-- Its meaning in this project is precise enough that a new engineer would need it defined
-- It is not general programming vocabulary
-
-If `CONCEPTS.md` doesn't exist yet, ask whether to seed it. A seed populates the core domain nouns of the area the learning touches; a full repo-wide bootstrap is the job of `mstar-compound-refresh`.
-
-## Phase 6: Update indexes
-
-1. Add a row to `{KNOWLEDGE_DIR}/README.md` index table (create if missing):
-   - Document (link), Source Plan (`plan_id`), Description, Status (`Active`)
-
-2. If `plan_id` was provided, optionally update `status.json` metadata to reference this doc under `knowledge_refs`.
-
-**iteration-close gate**: `mstar-iteration` §3.2 #5 — **each** new doc in the compound round must complete this phase; do not skip for lightweight captures.
-
-## Phase 7: Refresh trigger
-
-After capturing, check if the new learning suggests an older doc may now be stale (contradicted, superseded, or in a refactored domain). If so, recommend:
-
-```
-Consider: /pm compound-refresh <scope hint>
-```
-
-Do not automatically run refresh — only flag when there's a concrete reason.
-
-## CONCEPTS.md bootstrap requests
-
-If invoked specifically to create CONCEPTS.md from scratch (not to document a solved problem), redirect to `mstar-compound-refresh` (which handles full repo-wide vocabulary bootstrapping). `mstar-compound` only seeds vocabulary as a side effect of capturing a real learning.
+1. **Gather** — 读对话史 + iteration package；分类 track/category（`references/category-mapping.md`）
+2. **Overlap** — 高重叠 → 更新已有（加 `last_updated`）；中度 → 新建并标 consolidation review；低/无 → 正常新建
+3. **Write** — path + frontmatter（SSOT `references/schema.yaml`）+ body（`assets/resolution-template.md`）+ YAML validate
+4. **Discoverability** — 若 root `AGENTS.md`/`CLAUDE.md` 未提 `{KNOWLEDGE_DIR}`，提议最小补充（需用户同意；拒绝则仅跳过该编辑，doc 仍写）
+5. **CONCEPTS.md** — 项目特定领域词满足 qualifying bar 时提议入 `CONCEPTS.md`（规则见 `references/concepts-vocabulary.md`）；全仓 bootstrap 归 `mstar-compound-refresh`
+6. **Indexes** — `{KNOWLEDGE_DIR}/README.md` 加行（Document / Source Plan / Description / Status）；可选 `status.json` `knowledge_refs`。**iteration-close gate**：每篇新 doc 必须 Phase 6
+7. **Refresh trigger** — 新知识暗示旧 doc 过时 → 推荐 `/pm compound-refresh <scope>`（不自动跑，仅 flag）
 
 ## Support files
 
-Read on demand at the step that needs them:
-
-- `references/schema.yaml` — canonical frontmatter schema (Phase 3)
-- `references/category-mapping.md` — problem_type → directory + track mapping (Phase 1)
-- `references/concepts-vocabulary.md` — CONCEPTS.md rules (Phase 5)
-- `assets/resolution-template.md` — section structure per track (Phase 3)
+读 `references/compound-workflow.md`（Q1–Q8 + Phase 1–7）、`references/schema.yaml`（frontmatter）、`references/category-mapping.md`（track/path 映射）、`references/concepts-vocabulary.md`（CONCEPTS.md 规则）、`assets/resolution-template.md`（track 正文结构）。
 
 ## Skill dependencies
 
-This skill integrates with:
-- **`mstar-plan-conventions`** — path symbols (`{KNOWLEDGE_DIR}`, `{HARNESS_DIR}`)
-- **`mstar-plan-artifacts`** — `status.json` linking, index maintenance
-- **`mstar-compound-refresh`** — for knowledge maintenance after capture
+- **`mstar-plan-conventions`** — path symbols（`{KNOWLEDGE_DIR}`、`{HARNESS_DIR}`）
+- **`mstar-plan-artifacts`** — `status.json` linking、index maintenance
+- **`mstar-compound-refresh`** — capture 后知识维护；CONCEPTS.md 全仓 bootstrap
 
 ## NOT to do
 

package/harness-skills/mstar-compound/references/compound-workflow.md

@@ -0,0 +1,155 @@
+# mstar-compound — 工作流详情
+
+> Loaded by `mstar-compound` SKILL.md at the self-check and Phase 1–7 steps. **Read `mstar-harness-core` first.** Path symbols → `mstar-plan-conventions`.
+
+## 是否值得结晶 —— 完整自检（Q1–Q8）
+
+在调用本 skill 前，PM（或触发方）**必须**逐条回答以下问题。得分仅辅助决策，不替代判断。每条回答 Yes / No / Not sure。
+
+| # | 问题 | 说明 |
+|---|------|------|
+| Q1 | 这个问题的诊断过程耗时是否 ≥ 15 分钟（或 ≥ 3 次尝试）？ | 若只是 1-2 次尝试就找到答案，可能太琐碎 |
+| Q2 | 解决方案是否涉及**非显而易见**的知识（隐含假设、框架行为、workaround）？ | 显而易见的知识无需文档化（如"少了个分号"） |
+| Q3 | 同一个开发者在未来遇到类似问题时，是否可能**再次花费相似的时间**来诊断？ | 核心问题：知识能否复用？ |
+| Q4 | 问题的**根因**是否是项目特定的（不是通用语言/框架问题）？ | 通用问题可搜索到，项目特定问题必须自己记录 |
+| Q5 | `{KNOWLEDGE_DIR}` 中是否**已有**与此高度重叠的文档？ | 若有 → 更新已有文档，不新建（见 Phase 2 重叠检测） |
+| Q6 | 此解决方案是否可能**引导未来架构决策**或成为约定？ | Knowledge track 的典型触发条件 |
+| Q7 | 此解决方案中的"**什么没起作用**"部分是否有价值？ | 失败的尝试往往是最有教学价值的部分 |
+| Q8 | 问题是否涉及** ≥ 2 个模块/组件**的交互？ | 跨模块问题最难排查，最值得记录 |
+
+### 决策矩阵
+
+| 得分 | 行动 |
+|------|------|
+| **Yes ≥ 4**（含 Q5=No） | **强烈建议结晶**。执行完整 Phase 1-7。 |
+| **Yes = 3** | **建议结晶**。使用 Lightweight 模式（Phase 1 单遍）。 |
+| **Yes ≤ 2** | **跳过**。在 conversation/Completion Report 中注明"跳过结晶（<简述原因>）"。 |
+| **Q5 = Yes（高重叠）** | 无论其它得分如何，**不要新建**。执行 Phase 2 重叠检测，更新已有文档即可。 |
+| **任一 Not sure** | 倾向于回答者的默认判断。若 Q1-Q4 有 ≥ 2 个 Yes，仍建议结晶。 |
+
+### 示例判定
+
+```
+Q1: Yes — debug 了 40 分钟
+Q2: Yes — ActiveRecord 的 counter_cache 在 after_destroy 回调中的时序问题
+Q3: Yes — 下次遇到类似时序问题仍会踩坑
+Q4: Yes — 是项目特有 model 结构导致的
+Q5: No  — grep 了 knowledge/ 无匹配
+Q6: No  — 纯 bug 修复
+Q7: Yes — 第一次尝试了手动更新 counter 导致数据不一致
+Q8: No  — 只涉及一个 model
+→ Yes = 5 → 强烈建议结晶（Bug track）
+```
+
+## Phase 1: Gather context
+
+Read the conversation history **and**, when `iteration_id` is known, scan **`{ITERATION_DIR}/<iteration-id>/`** package per **Iteration package promotion** (SKILL.md).
+
+Understand:
+- What problem was solved (the concrete issue)
+- What was tried and didn't work
+- What the working solution was
+- Why the solution works (root cause)
+- Which files/modules were involved
+- The plan_id if applicable (link to `status.json`)
+
+If `{KNOWLEDGE_DIR}/README.md` exists, scan its index for related existing documents.
+
+Classify the problem into a track (bug vs knowledge) and category using `references/category-mapping.md`.
+
+## Phase 2: Overlap detection
+
+Before creating a new doc, check if an existing doc covers the same ground:
+
+1. Extract keywords from the problem (module names, error messages, technical terms)
+2. Search `{KNOWLEDGE_DIR}/**/*.md` using frontmatter fields (`module:`, `tags:`, `problem_type:`)
+3. Score overlap across dimensions: problem statement, root cause, solution approach, referenced files, prevention
+
+| Overlap | Action |
+|---------|--------|
+| **High** (4-5 dimensions match) | **Update** the existing doc with fresher context instead of creating a new one. Add `last_updated` field. |
+| **Moderate** (2-3 dimensions match) | Create new doc; flag for consolidation review (potential `mstar-compound-refresh` trigger) |
+| **Low/None** | Create new doc normally |
+
+## Phase 3: Write the document
+
+### 3.1 Determine path
+
+Category → directory under `{KNOWLEDGE_DIR}/`. Examples:
+- Bug track: `build-errors/`, `runtime-errors/`, `performance-issues/`, `database-issues/`, `security-issues/`, `integration-issues/`
+- Knowledge track: `architecture-patterns/`, `design-patterns/`, `conventions/`, `workflow-patterns/`, `tooling-decisions/`, `best-practices/`
+
+Filename: `<sanitized-slug>.md` (lowercase, hyphen-separated, no date prefix).
+
+### 3.2 Frontmatter
+
+Required fields for both tracks (SSOT: `references/schema.yaml`):
+
+```yaml
+---
+module: <area>
+date: YYYY-MM-DD
+problem_type: <enum value>
+category: <directory name>
+severity: critical|high|medium|low
+plan_id: <optional, link to status.json>
+tags: [<keywords>]
+---
+```
+
+Bug-track adds: `symptoms`, `root_cause`, `resolution_type`.
+Knowledge-track adds: `applies_when` (optional).
+
+### 3.3 Body
+
+Follow the section structure from `assets/resolution-template.md` for the determined track.
+
+### 3.4 Validate
+
+After writing, validate the YAML frontmatter:
+- `---` delimiters are correct
+- All required fields present
+- Enum values match allowed values
+- `date` is YYYY-MM-DD format
+- Array fields use `[item1, item2]` syntax
+
+## Phase 4: Discoverability check
+
+Check whether the project's `AGENTS.md` or `CLAUDE.md` would lead a future agent to discover `{KNOWLEDGE_DIR}`.
+
+If `{KNOWLEDGE_DIR}` is not mentioned in the root instruction file, propose the smallest addition that surfaces the knowledge store. Example:
+
+```markdown
+- `{HARNESS_DIR}/knowledge/` — captured solutions and reusable patterns
+```
+
+Ask for user consent before applying (PM can approve). If the user declines, the doc is still written — only the discoverability edit is skipped.
+
+## Phase 5: CONCEPTS.md synergy
+
+If the captured learning introduces or clarifies a domain term whose meaning is project-specific and not obvious to a newcomer, propose adding it to `CONCEPTS.md` at the repo root.
+
+Read `references/concepts-vocabulary.md` for inclusion rules. Only propose when the term meets the qualifying bar:
+- Its meaning in this project is precise enough that a new engineer would need it defined
+- It is not general programming vocabulary
+
+If `CONCEPTS.md` doesn't exist yet, ask whether to seed it. A seed populates the core domain nouns of the area the learning touches; a full repo-wide bootstrap is the job of `mstar-compound-refresh`.
+
+## Phase 6: Update indexes
+
+1. Add a row to `{KNOWLEDGE_DIR}/README.md` index table (create if missing):
+   - Document (link), Source Plan (`plan_id`), Description, Status (`Active`)
+
+2. If `plan_id` was provided, optionally update `status.json` metadata to reference this doc under `knowledge_refs`.
+
+**iteration-close gate**: `mstar-iteration` §3.2 #5 — **each** new doc in the compound round must complete this phase; do not skip for lightweight captures.
+
+## Phase 7: Refresh trigger
+
+After capturing, check if the new learning suggests an older doc may now be stale (contradicted, superseded, or in a refactored domain). If so, recommend:
+
+```
+Consider: /pm compound-refresh <scope hint>
+```
+
+Do not automatically run refresh — only flag when there's a concrete reason.

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

@@ -105,19 +105,14 @@ When **`Execution mode: sdd`** (`mstar-sdd`):
 
 ## 反模式（派发）
 
+完整反模式索引见 **`mstar-harness-core`**；lease / worktree / Phase 相关反模式见 **`mstar-branch-worktree`** 与 **`mstar-iteration`**。本节仅列派发机制专属：
+
 - QC 三审拆在多条消息（tri 模式）或单席却未附 review-package 路径。
 - 仅 1 次 invoke 却声称「tri-review 已并行启动」（tri 模式 N=3）。
-- SDD 并行 implementer dispatch（**同一 plan 内**多 task）— **不同于**跨 plan lease 门控并行（后者见上节 L1）。
-- 跨 plan 可写派发无 verified `execution_lease`；steal / 覆盖活跃 `execution_lease` 或 `integration_merge_lease`；并行 integration merge。
-- 跨 plan **并行**可写派发在 **无** same-host 独占写锁（跨主机 / 无共享 flock）且 **无** 用户本轮 `Cross-host lease race: accepted` + audit `notes` — **无论** `Worktree mode: waived`。
-- 将 **`Worktree mode: waived`** 当作跨 plan 无锁并行授权（须 serial 或 race-accepted + audit）。
-- 因 feature worktree 在默认 gitignore 下看不到 `plans/` 而设 **`Worktree mode: waived`**（应保留 feature worktree + control 绝对 `Plan Path` / `SDD dir`）。
-- `InProgress` 无 `execution_lease` 未走 orphan recovery 即 writable-dispatch。
-- 同仓多轨 writable implement：**N invoke ≠ worktree 隔离**（L2）→ **`mstar-branch-worktree`** **`references/parallel-writable-pre-dispatch.md`**。
+- SDD 并行 implementer dispatch（**同一 plan 内**多 task）— **不同于**跨 plan lease 门控并行（后者见上节 L1 / **`mstar-branch-worktree`**）。
 - 递归同角色 subagent；把 Handoff / 多轨编排措辞当 invoke。
 - Review-and-edit 链未完成即 commit integration 分支；PM 代做专业角色编辑而不 invoke。
 - Phase 1 review-and-edit 链三角色并行派发，或未等上一角色返回即派发下一角色。
-- 全部 plan `Done` 后跳过 Phase 3 直接 PR；final plan closure 替代 `mstar-iteration` §3.1–§3.5。
 - Assignment 已写、invoke 为零（paste-only）却进入下一 gate。
 
 ## References

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

@@ -39,7 +39,7 @@ description: Morning Star (启明星) harness **强制全局入口** —— 信
 | 角色 | 始终 | 按任务追加（典型） |
 |------|------|-------------------|
 | **全部** | 本 skill | — |
-| **`@project-manager`** | 本 skill | `mstar-dispatch-gates`、`mstar-phase-gates`、`mstar-plan-conventions`、`mstar-roles`；implement 波次 `mstar-sdd`；派 QC 前 `mstar-review-qc`；并行/审查 `mstar-branch-worktree`；plan/status/review bundle `mstar-plan-artifacts`；UI 类 plan Prepare 阶段 `mstar-design-md`（DESIGN.md 门禁）；新建/大改 skill 时 `mstar-skill-authoring`；迭代管理 `mstar-iteration`（Phase 1–5）；战略性工作 `mstar-strategy`。**不**读 `mstar-coding-behavior` |
+| **`@project-manager`** | 本 skill | `mstar-dispatch-gates`、`mstar-phase-gates`、`mstar-plan-conventions`、`mstar-roles`；implement 波次 `mstar-sdd`；派 QC 前 `mstar-review-qc`；并行/审查 `mstar-branch-worktree`；plan/status/review bundle `mstar-plan-artifacts`；UI 类 plan Prepare 阶段 `mstar-design-md`（DESIGN.md 门禁）；新建/大改 skill 时 `mstar-skill-authoring`；迭代管理 `mstar-iteration`（Phase 1–5）；战略性工作 `mstar-strategy`；`audit` 类请求 `mstar-audit`。**不**读 `mstar-coding-behavior` |
 | **实现/审查/运维** | 本 skill + `mstar-coding-behavior` + 角色 ref | 有 git 写：`mstar-branch-worktree`；有 plan 路径：`mstar-plan-conventions`；**PM** 派 QC 前：`mstar-review-qc`；**`qc-specialist*`**：`mstar-roles` → `references/qc-specialist/`；`qa-engineer`：`references/qa-engineer/`；改 status/residual：`mstar-plan-artifacts`；UI：`mstar-design-md`；知识库：`mstar-compound`（PM） |
 | **leaf 承接方** | 上栏 + **`mstar-dispatch-gates`**（反递归节） | — |
 
@@ -66,6 +66,7 @@ PM 在 Assignment 写 **`Task category`**（主类 + 可选 `secondary`）：
 | `logic` | `@architect` + dev |
 | `ops` | `@ops-engineer` |
 | `docs` | `@product-manager` / `@architect` / `@writing-specialist` |
+| `audit` | `@architect` / read-only `scout` subagents → `mstar-audit`（read-only advisory；不进入状态机） |
 
 **硬规则**：`quick` **从不**跳过 `specify → clarify → plan`；禁止把新 CLI/API/多模块/新测例标为 `quick`。已启用 `{HARNESS_DIR}` 时，首次 implement 前须有主 plan 路径 + `status.json` 登记（见 **`mstar-plan-conventions`**）。
 
@@ -100,6 +101,7 @@ PM 在 Assignment 写 **`Task category`**（主类 + 可选 `secondary`）：
 | `mstar-compound-refresh` | 知识维护 —— 审查/更新/合并/删除 `{KNOWLEDGE_DIR}` 文档；**项目知识 bootstrap**（无/残旧 STRATEGY.md、CONCEPTS.md、`{KNOWLEDGE_DIR}`）→ `references/project-knowledge-bootstrap.md` |
 | `mstar-strategy` | `STRATEGY.md` 全局战略方向 —— 产品愿景、技术方向、决策原则 |
 | `mstar-skill-authoring` | mstar-native skill authoring: trigger contracts, progressive disclosure, pressure scenarios, behavior-change evidence |
+| `mstar-audit` | Read-only codebase audit → prioritized, self-contained improvement plans（`audit-playbook` 9 类别 + `finding-format` + `plan-quality-bar`） |
 | `mstar-roles` | 角色正文 hub |
 | `mstar-host` | 宿主适配（自动识别；`references/opencode.md` / `cursor.md` / `codex.md` / `kimi.md` / `parallel-dispatch.md`） |
 

package/harness-skills/mstar-host/references/_shared/host-role-binding-core.md

@@ -0,0 +1,44 @@
+# Host role-binding core (C5/C5b)
+
+Shared role-binding contract for hosts that **cannot bind Morning Star roles via agent config** (Kimi, ZCode, omp). Cursor / OpenCode / Codex bind roles through agent config or `subagent_type` role ids and do **not** use this file. Read from the active host reference when dispatching.
+
+## C5 — built-in invoke types only
+
+- The host ships **built-in subagent types only**; the active host reference's C5 mapping table is the authoritative type list.
+- Morning Star role ids (`project-manager`, `fullstack-dev`, `qc-specialist`, …) are **not** valid invoke types on these hosts — never invent agent names.
+
+## C5b — role binding in prompt (required)
+
+Because the host cannot bind roles via agent config, every dispatch **must** carry the played Morning Star role in the **Assignment** and in the **invoke prompt**:
+
+1. **`Execute as: <role-id>`** in Assignment (harness routing SSOT).
+2. **`Act as <role-id>`** (or equivalent) at the top of the invoke prompt.
+3. **Skill load list** — instruct the subagent to read `mstar-roles` → `references/<role-id>.md` (or shared reference + parameters) and topic skills per that reference.
+4. **`subagent_type` / `agent`** — pick from the host's built-in types only (C5 table in the host reference).
+
+Paste-only Assignment **without** an invoke call is **not** dispatch.
+
+## Invocation rules
+
+- **1 Assignment ⇒ 1 invoke**: one invoke call carrying the full Assignment body per assignee.
+- **Parallel batch N**: **N** invocations in **one** assistant message (mechanics → **`parallel-dispatch.md`**).
+- **No invoke call** → **Not dispatched** — paste-only / `dispatch incomplete`.
+- **Anti-recursion NEVER**: leaf executors are already `Execute as` — **no** recursive invoke of the same role; Assignment wins (`Delegation: forbidden` unless stated). **Never** multiple implementer invokes in one message for the same plan (SDD serial → **`parallel-dispatch.md`** § SDD implement).
+
+## Assignment / prompt template
+
+```markdown
+## Assignment
+
+**Execute as**: fullstack-dev
+**Delegation**: forbidden
+**Working branch**: feat/example
+**Plan Path**: .mstar/plans/20260717-example.md
+
+**IDENTITY:** You ARE `fullstack-dev`. Act as `fullstack-dev` for this task.
+Load: `mstar-harness-core` → `mstar-host` → `<host>.md` → `mstar-roles` → `references/fullstack-dev-shared.md` → topic skills per that reference.
+
+<task body>
+```
+
+The active host reference shows the matching invoke shape (same turn).

package/harness-skills/mstar-host/references/_shared/plan-mode-bridge-core.md

@@ -0,0 +1,91 @@
+# Plan-Mode Bridge Core (shared)
+
+> **Load order**: Read **`mstar-harness-core`** first, then **`mstar-host`** and the host reference + this bridge. When plan management is required, also read **`mstar-plan-conventions`** and **`mstar-plan-artifacts`** before creating or claiming any durable plan state. Path symbols `{HARNESS_DIR}`, `{PLAN_DIR}`, `{SPECS_DIR}` are defined in `mstar-plan-conventions`. On conflict, **`mstar-harness-core`** wins.
+
+Each per-host bridge (`cursor-plan-mode-bridge.md`, `codex-plan-goal-mode-bridge.md`, `kimi-plan-mode-bridge.md`, `zcode-plan-mode-bridge.md`, `omp-plan-mode-bridge.md`) loads this core and adds its host-specific plan UX (plan tooling, approval gate, todo UI, command surfaces).
+
+## Dual-write SSOT rule
+
+The host **Plan mode** (session plan file, todos, UI) is a **session UX mirror**. Morning Star **SSOT** lives on disk under **`{HARNESS_DIR}`** (default `.mstar/`, legacy `.agents/`): the main plan in `{PLAN_DIR}/<plan-id>-<name>.md`, the plan registry in `{HARNESS_DIR}/status.json`, the iteration compass under `{ITERATION_DIR}/…` when in a formal iteration. Mirror every durable plan artifact to the repo; never treat the host plan file/URI/UI alone as the handoff surface.
+
+### Priority (hard)
+
+1. User explicit instructions (this turn)
+2. Project `AGENTS.md` / `CLAUDE.md`
+3. **`{HARNESS_DIR}` / `{PLAN_DIR}` / `status.json`** (harness SSOT)
+4. Host session plan / todos / UI (session UX mirror) — the host bridge names its surfaces
+
+**NEVER** cite only a host plan path / session todo list / chat summary in Assignment **Plan Path**, **Context Loaded**, or Completion Report when `{PLAN_DIR}/<plan-id>-<name>.md` should exist.
+
+## Before the first plan (bootstrap init)
+
+1. **Read** (minimum): `mstar-plan-conventions`, `mstar-plan-artifacts` (SKILL.md); Prepare gates from `mstar-phase-gates` if not hotfix.
+2. **Discover** `{HARNESS_DIR}` / `{PLAN_DIR}` per `mstar-plan-conventions` (prefer `.mstar/` + `.mstar/plans/`; reuse legacy `.agents/` only when already present and `.mstar/` is absent).
+3. **Initialize** if absent: `{HARNESS_DIR}/`, `{PLAN_DIR}/`, `status.json` from `mstar-plan-artifacts/templates/status.empty.json`, `archived/residuals/`, Morning Star process-artifact gitignore set (canonical snippet → `mstar-plan-conventions` SKILL.md「Git 跟踪策略」). Full PM checklist: `mstar-roles/references/project-manager/plan-management.md`.
+
+## Build resume contract
+
+Host **Build** / plan approval resumes the current plan in Agent mode. Do **not** assume it replays `/pm` or re-enters a role skill automatically.
+
+First action after Build, before product-code edits:
+
+1. Reload the harness entry: `mstar-harness-core` → `mstar-host` host reference → this bridge.
+2. If the plan is a Morning Star plan, resume as `project-manager` for coordination and dispatch only.
+3. Read the SSOT plan and `status.json`; use them as the source of truth over the host plan URI/UI.
+4. For each implement/code todo, require a PM Assignment with `Execute as`, `Delegation`, `Working branch` or `Branch policy`, and SSOT `Plan Path`.
+5. If the Assignment or SSOT state is missing, report **Blocked** and repair the harness state before implementation.
+
+Allowed in the parent Build session: plan/status maintenance, routing decisions, Assignment writing, and host task dispatch.
+
+Not allowed in the parent Build session by default: product implementation, test implementation, QC execution, QA execution, deployment, or ops changes. Those follow the normal PM dispatch rules unless the user explicitly overrides the harness.
+
+## CreatePlan: fixed bootstrap todos (prefix)
+
+**Emit these three todos first**, in order, **before** any implement / code todos. Do **not** mark implement todos in progress until all three are **done**.
+
+| Todo ID (use in title) | Goal | On-disk outcome |
+|------------------------|------|-----------------|
+| **`harness-init`** | Bootstrap harness tree | `{HARNESS_DIR}/`, `{PLAN_DIR}/`, process-artifact gitignore set, `archived/residuals/`, `status.json` initialized |
+| **`spec-register`** | Register plan in SSOT | New `plans[]` row in `status.json` (`id`, `status`, `file`, `metadata`); spec stub in `{SPECS_DIR}` or plan frontmatter |
+| **`mirror-plan`** | SSOT main plan file | `{PLAN_DIR}/<plan-id>-<name>.md` with task checkboxes aligned to the host plan body |
+
+After the host plan is created, keep the host plan body and mirror file **in sync** when scope changes (update both in the same coordination round).
+
+## Implement todo completion gate (every code todo)
+
+**Before marking the todo done:**
+
+1. **Commit**: `git add` + `git commit` on the authorized **Working branch** for this **task id** (one commit per task unless PM explicitly allowed batched commits in Assignment).
+2. **Plan checkbox**: Set `- [x]` on the matching line in `{PLAN_DIR}/<plan-id>-<name>.md`.
+3. **status.json** (when PM round requires): bump `plans[].status` (e.g. `InProgress`) or append coordination notes per `mstar-plan-artifacts`.
+4. **Evidence**: Record real `git log -1 --oneline` in Completion Report **Git** (or the plan-mode status note if executing as PM in Plan mode).
+
+**NEVER**
+
+- Mark implement todos done without a commit when tracked files changed.
+- Batch all work into one closing commit unless PM documented an exception.
+- Mark plan-level `Done` in `status.json` without PM/QA authority and without recorded **`QA gate`** (`mandatory` fulfilled or `pm-acceptance` checklist per `qa-trigger-matrix.md`).
+
+Dev-role NEVER rules also apply when executing as implementer: `mstar-roles/references/fullstack-dev-shared.md` (Git NEVER).
+
+## `mstar-iteration` Phase 1 in Plan mode (shared gate)
+
+- **Single plan session**: use **one** plan file (host or SSOT draft); iterate the **same** file in place with feedback-driven edits. If a duplicate plan file was created by mistake: merge into the original, delete the duplicate.
+- **Do not** run Review & Edit, commit, or create the integration branch until the user approves implementation (host approval gate: **Build** / **`ExitPlanMode`** / plan resolve). Plan mode ≠ executing todos — approval is the Phase 1 executable gate (Review chain, lock, branch).
+- Prepare phase (`specify → clarify → plan`) still applies; the mirrored plan is the harness **`plan`** artifact, not a substitute for clarify.
+- Branch policy in the plan session: write **recommended** `iteration_base_branch` / `target_branch` (+ short rationale) into the plan — do **not** silently default to `main`/`master`.
+- Host plan approval is **not** Morning Star **Done**. Implementation still follows phase gates, per-task commits, QC, and QA per the SSOT plan.
+
+## Anti-patterns (shared)
+
+| Anti-pattern | Fix |
+|--------------|-----|
+| Host plan only, no `{HARNESS_DIR}` files | Run bootstrap todos; write mirror plan + status.json |
+| Todo done, no commit | Commit per task; paste `git log -1` evidence |
+| Drift between host plan and SSOT plan | Update both in same round |
+| Host plan URI as Plan Path | Use `{PLAN_DIR}/...` path |
+| Skip `spec-register` | Add `plans[]` row before implement |
+| Build starts coding in the parent session | Resume PM context; dispatch implement work or block on missing Assignment |
+| Host plan approval treated as Done authority | Check harness plan/status/QC/QA gates first |
+| Resume starts coding from host chat summary | Reload harness context and SSOT plan/status first |
+| Phase 1 Plan mode: Review / commit / branch before Build | Keep Pre-Build document-only; execute those todos after approval |