@mstar-harness/omp 3.6.0-alpha.4

package/skills/mstar-coding-behavior/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: mstar-coding-behavior
+description: Morning Star 跨角色通用编码行为准则 —— 任何实现、调试、重构、审查任务动手前必读。约束 Think Before Coding（先读懂再改、显式假设、不静默猜测）、Simplicity First（YAGNI、The Ladder、`simplify:` 标记、最小耐久切片）、Surgical Changes（改动可追溯、Bug 修根因先 grep 所有调用点、不 piggyback）、Debugging（先复现、一步一测、修前写复现测试）、Review Feedback Handling（先核实再改、证据反驳）、Goal-Driven Execution（非平凡逻辑留可运行检查、Step→verify）、Communication。`@fullstack-dev*` / `@frontend-dev` / `@architect` / `@qa-engineer` / `@ops-engineer` / `@prompt-engineer` 必读；QC 核对手术范围时必读。不覆盖分支门禁、QC/QA 路由、Assignment 权限。
+---
+
+## Load order（必读顺序）
+
+**在同一会话或任务中首次 Read 本 skill 时：必须先 Read `mstar-harness-core` skill（SKILL.md）。** 本 skill 只约束 **编码与改动风格**（Think / Simplicity / Surgical / Debugging / Goal-Driven / Communication）；**Done 所有权、状态机** 仍以 **`mstar-harness-core`** 为准；**分支 / worktree / QC-QA 检出字段** → **`mstar-branch-worktree`**；**调度防串扰** → **`mstar-dispatch-gates`**。冲突时 **以 `mstar-harness-core` 为准**。
+
+**摘要**：`mstar-harness-core` — 不变量与门禁；本 skill — 实现与审查时的工程习惯，不替代 harness。
+
+Priority remains（同 `mstar-harness-core`「信息源优先级」）：① 当轮用户显式指令 ② 项目 `AGENTS.md` / `CLAUDE.md` ③ `mstar-harness-core` ④ 其它 `mstar-*`（含本 skill）⑤ `mstar-roles` 角色正文。
+
+**Scope**：适用于非平凡编码/调试/重构/审查任务；trivial one-liner 用判断、保持低开销。定义执行行为，不定义分支策略或门禁所有权。
+
+# Morning Star Coding Behavior Guidelines
+
+Lightweight, host-agnostic coding-behavior principles that reduce common agent mistakes. Complements other Morning Star skills; does not override stage gates or role routing.
+
+## 1) Think Before Coding
+
+Do not silently choose an interpretation when ambiguity exists. State assumptions explicitly when material; if multiple plausible interpretations exist, present options and ask. Surface tradeoffs affecting scope/risk/maintainability. If critical context is missing, pause and clarify instead of guessing.
+
+Quick check: can another reviewer see the assumptions made? If assumptions are wrong, will the user detect it before large edits happen?
+
+**Never lazy about understanding.** Shorten the solution, never the reading. Read the task and every file the change touches fully first; trace the actual flow end to end. A small diff in the wrong place is not efficiency — it is a second bug shipped with confidence.
+
+**Read before you write.** Before generating code in an existing project: inspect imports (which libraries the project actually uses — do not introduce a different library for the same purpose); look at nearby tests (they document expected behavior more precisely than comments); follow existing patterns (API routes, file structure, error handling — match it, do not silently introduce a different one). If no precedent exists, say so and ask. If not 100% sure a signature/parameter exists, check source/docs before using it — confidently calling a non-existent API may compile then fail at runtime.
+
+The failure mode: "correct" code that is alien to the codebase — works but looks like a different person wrote it, forcing a rewrite or permanent inconsistency.
+
+## 2) Simplicity First
+
+**Upstream invariants**: the global engineering rules live in `mstar-harness-core`（核心研发守则）——no backward-compat layers, simplest implementation, layered growth, modularity, dependency discipline, long-term architecture; this section is their implementation-level playbook.
+
+Implement the smallest durable slice that satisfies the request and acceptance criteria.
+
+**The Ladder.** A reflex hierarchy for every decision — stop at the first rung that holds:
+
+1. **Does this need code at all?** Speculative need → skip it (YAGNI).
+2. **Already in this codebase?** A helper, util, type, or pattern that already lives here → reuse it. Look before you write.
+3. **Stdlib / built-in covers it?** Use it.
+4. **Native platform feature covers it?** CSS over JS, DB constraint over app code, OS primitive over a library.
+5. **Already-installed dependency solves it?** Use it. Never add a new dependency for what a few lines can do. When a new dependency appears necessary, evaluate: (a) can this be done with what is already in the project? (b) can the standard library do it? (c) is the package maintained (check last commit date and issue tracker) and reasonably sized? If you add it, state why in one sentence — silently adding packages is not acceptable.
+6. **Can it be one line?** One line.
+7. **Only then:** the minimum durable code that works.
+
+The ladder runs after understanding, not instead of it. Two rungs work → take the higher one.
+
+**Deletion over addition. Boring over clever.** Removing unnecessary code is a feature; cleverness is what someone decodes at 3am — prefer a boring, obvious solution a tired reviewer verifies in seconds. Do not add unrequested features/flags/configurability; avoid new abstractions for single-use logic; prefer straightforward local fixes over framework-level reshaping **only when they fit the target design**; reject speculative error handling for impossible paths unless required by project policy.
+
+**Simplification markers.** When a deliberate shortcut has a known ceiling (global lock, O(n²) scan, naive heuristic), mark it with a `simplify:` comment naming the ceiling and the upgrade path:
+
+```text
+// simplify: global lock on cache misses. Replace with per-key lock if throughput matters.
+```
+
+This signals intent — the simplicity is deliberate, not an oversight — and gives the next person the upgrade path without research.
+
+- Do not confuse "minimum" with "temporary." A small implementation must still align with the long-term target state, stable interfaces, and known follow-up plan.
+- If a workaround is unavoidable, label it `simplify:` / `temporary`, explain why, and record the removal path in the plan/status artifact before claiming the task complete.
+
+> **Engine check (when available):** run `mstar lint <target>` (or `import { findSimplifyMarkers, findTemporaryMarkers } from "@mstar-harness/engine"` in a host hook) to check the marker convention above — every `simplify:` / `temporary` comment is reported, and `temporary` markers without a recorded plan/status removal path are violations. On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
+
+**Simplicity anti-patterns — stop and reconsider when you spot these:**
+
+| Anti-pattern | Signal |
+|---|---|
+| **Premature abstraction** | Writing a class/interface/strategy where a single function suffices. |
+| **Speculative error handling** | Wrapping code in try/catch for errors that cannot happen. |
+| **Unnecessary configurability** | Making a value configurable (env var, parameter) that will never change. Hardcode it until there is a real reason not to. |
+| **Dead flexibility** | An interface with one implementation, or a generic type with one instantiation — cost with zero benefit until a second use exists. |
+| **"In case we need to"** | Justification for abstraction includes a guess about future requirements. "In case we need to" is a guess, and guesses about the future are usually wrong. |
+
+**Durability check**: can this slice be extended by the next batch without undoing its core shape? Are deferred items captured in an existing roadmap/task board/residual tracker (not just chat)? Would a reviewer understand whether this is the final approach, a staged slice, or a deliberate simplification?
+
+## 3) Surgical Changes
+
+Every changed line should be traceable to the task. Touch only files/regions needed for the requested outcome; do not opportunistically refactor adjacent code; match existing style unless a change is explicitly requested; remove only artifacts made unused by your own change; report unrelated issues separately instead of piggyback editing.
+
+**Traceability test**: each hunk maps to a user requirement, acceptance criterion, or required fix-up.
+
+**Bug fix = root cause, not symptom.** A bug report names a symptom, not the cause. Before editing, grep every caller of the function or code path you are about to touch. The fix belongs where all callers route through — one guard in the shared function is smaller than a guard in every caller. Patching only the path the ticket names leaves every sibling caller still broken. Fix it once, at the narrowest shared point.
+
+## 4) Debugging
+
+When something does not work, investigate; do not guess.
+
+- **Read the error message entirely**, including the full stack trace — a `TypeError` can mean a hundred things; the message and trace tell you which one.
+- **Reproduce before fixing.** If you cannot reproduce, you cannot verify. "I think this should fix it" is gambling.
+- **Change one thing at a time.** Changing three things and seeing the bug disappear tells you nothing about which change fixed it — or what new bugs the other two introduced.
+- **Fix the root cause, not the symptom.** If a value is unexpectedly null, do not just add a null check — figure out why it is null (see Surgical Changes · bug=root-cause).
+- **Write a reproduction test before fixing a bug.** Minimal test reproducing the reported behavior → watch it fail → apply fix → watch it pass. The only way to prove you fixed the actual problem, not merely suppressed symptoms.
+- **Run existing tests before and after changes.** If they passed before and fail after, you broke something. If they were already failing, say so.
+- **If stuck, say so.** "I tried X and Y; neither worked. I'm seeing Z. I think it might be W but am not sure" is infinitely more useful than silently trying random things for 20 iterations.
+
+**Dataflow-directed diagnosis — how to locate, verify, and falsify** (for where to fix, see Surgical Changes · bug=root-cause; for the pre-fix repro test, see the bullets above):
+- **Map the data flow before judging.** Trace input → processing → storage → output, noting who writes and who reads at each step. A bug is a state deviation from expectation at some point in that flow (expected state vs observed state) — locate it from the data, not by static code reading.
+- **Four verifiable cross-checks.** Every hypothesis must be cross-checkable: re-run the repro / log comparison / input-output comparison / dual-path comparison. A hypothesis that cannot be verified on the spot is not a conclusion.
+- **Falsify the fix.** After the fix, re-run the original repro and compare output with expectation. If the problem did not disappear, the root cause was wrong — report "verification failed" explicitly; never pretend success.
+
+## 5) Goal-Driven Execution
+
+Convert vague requests into verifiable outcomes and iterate until verified. Define concrete success criteria before major edits; use brief `Step -> verify` checkpoints for multi-step tasks; for split delivery, maintain a durable roadmap (current slice, later slices, dependencies, owner/trigger, completion condition); prefer evidence-backed completion (tests, command output, reproducible checks). If verification fails, loop on diagnosis and fix before declaring completion. Do not finish with "next plan / later / follow-up" only in prose — remaining work must be written to the plan/status artifact or the task reports `Partial` / `Blocked`.
+
+**Minimal check for non-trivial logic.** Any non-trivial change (a branch, a loop, a parser, a data transformation, a money or security path) must leave behind ONE runnable check — the smallest thing that fails if the logic breaks. An inline self-check, a quick `assert`-based demo, or one minimal test. No frameworks, no fixtures, no per-function suites unless asked. Trivial one-liners need none — YAGNI applies to tests too.
+
+Micro template:
+
+```text
+1. [Step]
+   Verify: [specific check]
+2. [Step]
+   Verify: [specific check]
+```
+
+**Verification discipline**: test behavior, not implementation (a test checking whether a constructor sets properties is worthless; one checking whether validation rejects bad input is valuable — focus on interesting cases). If you cannot write a test, say why ("I cannot easily test this because the database calls are tightly coupled to the business logic" may signal a need for restructuring — do not skip testing without an explanation).
+
+## 6) Review Feedback Handling
+
+Review feedback is technical input, not an order to perform unverified edits. When receiving code review, QA, CI, or human feedback: read all feedback before editing; clarify ambiguous items before partial implementation; verify each suggestion against codebase reality; apply technically correct feedback one item at a time; test each fix individually where practical; push back with evidence when feedback is incorrect, obsolete, risky, out of scope, or violates YAGNI.
+
+Feedback priority:
+
+| Feedback type | Handling |
+|---|---|
+| Security, correctness, data loss, build/test failure | Fix or escalate before proceeding. |
+| Scope mismatch, reviewer misunderstanding, obsolete assumption | Verify and push back with evidence. |
+| Style-only suggestion | Apply only if it matches project conventions or is requested by the user/PM. |
+| New feature disguised as review | Route through PM/plan unless explicitly in scope. |
+
+Do not perform agreement. State the technical action, the verification result, or the technical reason for disagreement.
+
+## 7) Communication
+
+- **Say what you did and why** — not just a code dump ("moved validation into a separate function because it was duplicated in three places and this makes it testable independently").
+- **Flag concerns proactively** ("this works but makes a DB call per item — if the list grows large this will be slow; want me to batch it?").
+- **Be precise about uncertainty** ("I'm not sure if this library supports streaming responses" is useful; "I think this should work" is not — tell the reviewer exactly what to verify).
+- **Match explanation to context** — do not explain REST to someone who asked for a REST endpoint, or indexes to someone who asked for an index.
+- **Write specific commit messages** — "Fix null pointer in user lookup when email contains uppercase chars", not "Fix bug".
+
+## Integration Notes
+
+- **SDD implementer reports** (`mstar-sdd`): completion evidence must include TDD triple — test file(s), command, output — in `task-N-report.md`; fix rounds add the same for new/changed tests.
+
+> **Engine check (when available):** run `mstar lint <task-N-report.md>` (or `import { assertSddTddTriple } from "@mstar-harness/engine"` in a host hook) to assert the TDD triple above — test file(s), runnable command, and output evidence must all be present in the report. On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
+
+- This skill must not be used to bypass branch constraints, QC/QA gate definitions, assignment authority, or `Done` ownership rules.
+
+## Anti-Bloat Rule for Prompt Maintenance
+
+- Keep these principles centralized here.
+- Role prompts should reference this skill instead of duplicating long prose.
+- Only role-specific triggers, boundaries, and artifacts belong in role prompt files.
+
+## Workflow
+
+Apply the seven sections in reading order: **1) Think Before Coding**（读懂再改）→ **2) Simplicity First**（最小耐久切片）→ **3) Surgical Changes**（可追溯改动 / 根因修复）→ **4) Debugging**（先复现、一步一测）→ **5) Goal-Driven Execution**（Step → verify）→ **6) Review Feedback Handling**（先核实再改、证据反驳）→ **7) Communication**（说明做了什么与为什么）。
+
+## Evidence
+
+正确结果 = 可运行检查通过并附输出：非平凡逻辑留下一个**最小可失败检查**（§5）；bug 修复先写复现测试、红转绿（§4）；回报引用检查结果与输出，而非「我觉得应该没问题」。
+
+## References
+
+- 角色正文与加载矩阵 → **`mstar-roles`**
+- 阶段门禁 / 意图门禁 / 可验证编辑 → **`mstar-phase-gates`**

package/skills/mstar-compound/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: mstar-compound
+description: Morning Star 知识结晶 —— 将已解决问题的经验沉淀为结构化知识文档，存入 `{KNOWLEDGE_DIR}`；迭代收口时从 `{ITERATION_DIR}/<iteration-id>/` package 提升 specs/guides。支持 Bug track 与 Knowledge track 双轨。含重叠检测、可发现性检查、CONCEPTS.md 协同。触发：iteration-close（`mstar-iteration` §3.2）或独立触发。产出：`{KNOWLEDGE_DIR}/<category>/<slug>.md`。
+---
+
+# mstar-compound（知识结晶）
+
+## Load order
+
+**Read `mstar-harness-core` first.** Path symbols (`{KNOWLEDGE_DIR}`, `{HARNESS_DIR}`) → **`mstar-conventions`**. On conflict, **`mstar-harness-core` wins**.
+
+## Purpose
+
+After solving a non-trivial problem, `mstar-compound` captures the learning as a structured document in `{KNOWLEDGE_DIR}`, so future plan research, debugging, and implementation can find and reuse it.
+
+**In the mstar lifecycle**, compound is triggered at iteration-close (`mstar-iteration` § Phase 3), not per-plan Done. It can also be invoked standalone for ad-hoc captures outside formal iterations.
+
+Knowledge that isn't captured evaporates when the session ends. Knowledge that is captured but not discoverable is equally lost. This skill addresses both.
+
+## 产物存储位置
+
+**SSOT**: `mstar-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（或触发方）**必须**对候选问题逐条自检 Q1–Q8（诊断耗时 / 非显而易见性 / 可复用性 / 项目特异性 / 既有重叠 / 架构影响 / 失败尝试价值 / 跨模块）。完整问题表、决策矩阵（Yes≥4 强烈建议；Yes=3 Lightweight；Yes≤2 跳过；Q5=Yes 高重叠不新建）与示例判定 → **`references/compound-workflow.md`**「是否值得结晶」。
+
+**快判**：Q5 高重叠 → 更新已有文档，**不新建**；其余按决策矩阵 Yes 数。
+
+## Integration with mstar lifecycle
+
+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。
+
+**路径**：`{ITERATION_DIR}/<iteration-id>/**`（含 `guides/`、`specs/`、扁平 `.md`；**默认排除** `delivery-compass.md` 除非 PM 显式纳入。Legacy 根目录 `*-delivery-compass.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 的琐碎笔记。边界 SSOT → **`mstar-iteration/references/iteration-artifact-boundaries.md`**。
+
+## When to use / Skip
+
+**Use**：迭代收口（`mstar-iteration` § iteration-close）批量回顾；独立触发（非迭代或紧急，任何非平凡问题解决后）；重大 bug 修复后（`mstar-iteration` 未启用时手动）。
+
+**Skip**：自检 ≤2 Yes；Q5 高重叠（更新已有而非新建）；纯机械工作（格式化、依赖升级、typo）；问题未经验证。
+
+## Two tracks
+
+| 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 由 `problem_type` 决定，完整映射见 `references/category-mapping.md`。
+
+## Execution modes
+
+| Mode | When | Behavior |
+|------|------|----------|
+| **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.
+
+## Workflow skeleton（Phase 1–7）
+
+完整步骤细节（Gather context / Overlap detection / Write document 含 frontmatter schema + path + validate / Discoverability check / CONCEPTS.md synergy / Update indexes / Refresh trigger）→ **`references/compound-workflow.md`**。每 Phase 一个关键决策：
+
+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）；可选 workflow snapshot plan 行 `metadata.knowledge_refs`（`{WORKFLOW_DIR}/<id>/snapshot.json`）。**iteration-close gate**：每篇新 doc 必须 Phase 6
+7. **Refresh trigger** — 新知识暗示旧 doc 过时 → 推荐 `/pm compound-refresh <scope>`（不自动跑，仅 flag）
+
+> **Engine check (when available):** run `mstar compound validate <doc-path> [--knowledge-dir <dir>]` (or `import { validateSchemaYaml, assertIndexRows } from "@mstar-harness/engine"` in a host hook) to validate the frontmatter against `references/schema.yaml` (Phase 3 Write) and assert every doc has its `{KNOWLEDGE_DIR}/README.md` index row (Phase 6 Indexes). On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
+
+## Support files
+
+读 `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
+
+- **`mstar-conventions`** — path symbols（`{KNOWLEDGE_DIR}`、`{HARNESS_DIR}`）
+- **`mstar-artifacts`** — workflow snapshot / project register linking、index maintenance
+- **`mstar-compound-refresh`** — capture 后知识维护；CONCEPTS.md 全仓 bootstrap
+
+## NOT to do
+
+- Do not create a doc for trivial fixes (typos, formatting, dep bumps)
+- Do not write the doc before the solution is verified
+- Do not skip the overlap check — creating duplicates degrades the knowledge store
+- Do not edit AGENTS.md without user consent
+- Do not create CONCEPTS.md entries for general programming vocabulary
+- Do not modify product code — this skill writes documentation only
+
+## Evidence
+
+正确结果 = 一篇**可发现**的结晶文档：`{KNOWLEDGE_DIR}/<category>/<slug>.md` 通过 `references/schema.yaml` frontmatter 校验（Phase 3 Write）+ `{KNOWLEDGE_DIR}/README.md` 索引行（Phase 6 Indexes，iteration-close 强制）+ 达标领域词入 `CONCEPTS.md`（Phase 5）+ 源文件 / package README 标注 `Promoted to: <knowledge-path>`（Phase 4 Trace）。

package/skills/mstar-compound/assets/resolution-template.md

@@ -0,0 +1,94 @@
+# Resolution templates for mstar-compound
+
+## Bug track template
+
+```markdown
+---
+module: <area>
+date: YYYY-MM-DD
+problem_type: <enum>
+category: <directory>
+severity: <critical|high|medium|low>
+symptoms: ["<symptom 1>", "<symptom 2>"]
+root_cause: <fundamental cause>
+resolution_type: <enum>
+tags: [<keyword1>, <keyword2>]
+---
+
+# <Title>
+
+## Problem
+<1-2 sentence description of the issue>
+
+## Symptoms
+- <Observable symptom 1>
+- <Observable symptom 2>
+
+## What Didn't Work
+- <Failed approach 1>: <why it failed>
+- <Failed approach 2>: <why it failed>
+
+## Solution
+<The actual fix with code examples when applicable>
+
+```lang
+// Before
+<broken code>
+
+// After
+<fixed code>
+```
+
+## Why This Works
+<Root cause explanation and why the solution addresses it>
+
+## Prevention
+- <Strategy 1 to avoid recurrence>
+- <Strategy 2>
+- <Test case or lint rule if applicable>
+```
+
+## Knowledge track template
+
+```markdown
+---
+module: <area>
+date: YYYY-MM-DD
+problem_type: <enum>
+category: <directory>
+severity: <critical|high|medium|low>
+applies_when: ["<condition 1>", "<condition 2>"]
+tags: [<keyword1>, <keyword2>]
+---
+
+# <Title>
+
+## Context
+<What situation, gap, or friction prompted this guidance>
+
+## Guidance
+<The practice, pattern, or recommendation>
+
+```lang
+// Example of the pattern
+<code>
+```
+
+## Why This Matters
+<Rationale and impact of following or not following this guidance>
+
+## When to Apply
+- <Condition or situation 1>
+- <Condition or situation 2>
+
+## Examples
+### Before
+```lang
+<code before>
+```
+
+### After
+```lang
+<code after>
+```
+```

package/skills/mstar-compound/references/category-mapping.md

@@ -0,0 +1,37 @@
+# Category mapping: problem_type → directory under {KNOWLEDGE_DIR}
+
+## Bug track
+
+| problem_type | directory | track |
+|---|---|---|
+| `build_error` | `build-errors/` | bug |
+| `test_failure` | `test-failures/` | bug |
+| `runtime_error` | `runtime-errors/` | bug |
+| `performance_issue` | `performance-issues/` | bug |
+| `database_issue` | `database-issues/` | bug |
+| `security_issue` | `security-issues/` | bug |
+| `ui_bug` | `ui-bugs/` | bug |
+| `integration_issue` | `integration-issues/` | bug |
+| `logic_error` | `logic-errors/` | bug |
+| `config_error` | `config-errors/` | bug |
+
+## Knowledge track
+
+| problem_type | directory | track |
+|---|---|---|
+| `best_practice` | `best-practices/` | knowledge |
+| `convention` | `conventions/` | knowledge |
+| `architecture_pattern` | `architecture-patterns/` | knowledge |
+| `design_pattern` | `design-patterns/` | knowledge |
+| `tooling_decision` | `tooling-decisions/` | knowledge |
+| `testing_pattern` | `testing-patterns/` | knowledge |
+| `api_design` | `api-design/` | knowledge |
+| `workflow_issue` | `workflow-patterns/` | knowledge |
+| `developer_experience` | `developer-experience/` | knowledge |
+| `documentation_gap` | `documentation/` | knowledge |
+
+## Rules
+
+1. The `category` field in frontmatter must match the directory name (without trailing slash).
+2. Prefer the narrowest applicable `problem_type`. Use `best_practice` only when no narrower knowledge-track value fits.
+3. When creating a new directory under `{KNOWLEDGE_DIR}`, add it to this mapping and create an empty directory.

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

@@ -0,0 +1,171 @@
+# 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-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 the workflow snapshot plan row)
+
+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 the workflow snapshot plan row>
+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
+
+### 3.5 知识文档质量门：HEAD-resolvability & prose hygiene
+
+写作完成、进入 Phase 4 前，对文档运行本质量门（writing-specialist 编辑 durable harness artifacts 时适用同一 rubric — 见 `mstar-roles/references/writing-specialist.md` Output Guidance 指针）：
+
+- **The one test**：读者在 HEAD（无 chat transcript / dispatch prompt / 未合并草稿访问权）能否解析每个引用并验证每个声明？
+- **mstar 泄漏分类**（vantage 来自 authoring session 而非仓库现状；修剪或重述）：
+  - dead session citations：chat-only decision 序号 → 引 plan/knowledge/roadmap 属主路径，或独立重述事实
+  - durable docs 中的 change narration：knowledge/roadmap/README 陈述现状；已修回归 → counterfactual-present（「without X, Y happens」）
+  - review choreography：谁在哪轮确认 → 平实事实；finding id 留在 review bundle（其 sanctioned genre）
+  - reviewer-addressed justification（向评审自辩的措辞）
+  - control-flow narration（过程/控制流叙述）
+  - hedges without markers → 既有 `simplify:` / `temporary` 标记约定（`mstar-coding-behavior`；引用不重复）
+  - authoring-language slips：双语对之外的 zh/en 混杂
+- **Keep 规则（mstar-sanctioned）**：review bundle / QC report 内的 R# 与 finding id（durable 文档引用 QC 证据的 sanctioned pattern 是经 review bundle 路径引用：finding id 留在 bundle 内，durable 文档只引用 bundle 路径本身）；issue 引用；带 provenance 词的 measured bounds；runtime old/new 生命周期态；Alternatives-considered genre 节；HEAD 持久工件中的 iteration/plan id
+- **过度修正陷阱**：义务↛背书翻转；hypothetical 保持标记；共享一句时删子句不删句。「修剪前枚举命题」→ complete-proposition rule（`mstar-roles/references/writing-specialist.md` Output Guidance — SSOT，不在本节重述）
+
+## 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 the workflow snapshot plan row (`workflows/<id>/snapshot.json` → `plans[].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/skills/mstar-compound/references/concepts-vocabulary.md

@@ -0,0 +1,44 @@
+# CONCEPTS.md vocabulary rules
+
+`CONCEPTS.md` **must** live at the repository root (`<repo-root>/CONCEPTS.md`, same level as `.git/` and `AGENTS.md`), **never** inside `{HARNESS_DIR}` or any subdirectory. It defines the words that mean something specific in this codebase — substrate that `{KNOWLEDGE_DIR}` and `AGENTS.md` can cite without redefinition.
+
+## How terms enter
+
+Two paths:
+
+- **Accretion** — a learning surfaces a term whose meaning wasn't obvious, so it gets defined. Catches *peripheral* terms (friction surfaces them).
+- **Seeding** — proactively defines **core domain nouns** the area's declared domain model exposes. Catches *stable-central* terms accretion never reaches.
+
+### What earns a slot
+
+A term qualifies when its meaning here is precise enough that a new engineer would need it defined to follow conversations, tickets, or code. General programming vocabulary does not belong.
+
+### Per entry
+
+- **Definition**: one sentence — what the term means in this domain, what makes it distinct from neighbors.
+- A term with non-obvious behavioral rules (lifecycle, cancellation semantics, ownership invariants) earns a second paragraph.
+- When retired synonyms exist: `*Avoid:* old-name, other-name`.
+- No implementation specifics (file paths, class names, table names), no status/date/owner fields, no version-specific claims.
+
+### Organization
+
+Cluster by domain relationship — entities with their states, processes with their stages. A flat list works when the file is small. Reshape as it grows.
+
+### Flagged ambiguities (tail of file)
+
+When two terms were used interchangeably and the team settled on a distinction, record the resolution as a one-line note.
+
+## One illustrative entry
+
+```markdown
+## MyDomain
+
+### Reservation
+A future commitment to seat a Party at a specified date and time.
+*Avoid:* Booking, appointment
+
+A Reservation owns its Party but does not own a Table — Tables are acquired only when the Party arrives, through a Seating. Lifecycle: Booked → Seated → Completed → No-Show.
+
+### Party
+The guests committed to a Reservation. Each Reservation has exactly one Party.
+```