@mstar-harness/dsh 2.1.1

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

@@ -0,0 +1,165 @@
+---
+name: mstar-plan-conventions
+description: Morning Star (启明星) harness 计划目录约定 —— `{HARNESS_DIR}` / `{PLAN_DIR}` / `{SDD_DIR}` / `{ITERATION_DIR}` / `{KNOWLEDGE_DIR}` / `{SPECS_DIR}` 发现与初始化（默认 `.mstar/`，兼容 `.agents/`）、`docs` 与 harness 子树边界、review bundle、未启用 plan 时的工作方式、Spec 集成分支与多 Plan 实现分支（显式 base / merge 靶 / PR target）、Morning Star plan-writing path gate、工期预估（agent-oriented）。**必须**在读写 `.mstar/` / `.agents/`、初始化 harness、编排含 plan 的任务、或对齐 `metadata.primary_spec` 时 Read；`@project-manager` 开 plan 任务前必读。plan 文件 / status / residual / review bundle / knowledge → **`mstar-plan-artifacts`**；分支与 QC 检出 → **`mstar-branch-worktree`**。
+---
+
+## Load order（必读顺序）
+
+**首次 Read 本 skill 前：必须先 Read `mstar-harness-core`（SKILL.md）。** 本 skill 只约定 **目录与路径**；不突破状态机与门禁。冲突时 **以 `mstar-harness-core` 为准**。
+
+| 你还可能要 Read | 何时 |
+|-----------------|------|
+| `mstar-plan-artifacts` | 主 plan、review bundle 摘要、`status.json`、residual、InReview/QC 波次、knowledge |
+| `mstar-branch-worktree` | Assignment 写分支 / worktree / QC 检出 |
+| `mstar-review-qc` | 派 QC（PM 同轮必读；SDD 强制 tri） |
+| `mstar-sdd` | PM 执行 `Execution mode: sdd` 的 implement 波次 |
+
+## 路径符号（SSOT）
+
+| 符号 | 默认 |
+|------|------|
+| `{HARNESS_DIR}` | `.mstar/` |
+| `{PLAN_DIR}` | `{HARNESS_DIR}/plans/` |
+| `{SDD_DIR}` | `{HARNESS_DIR}/sdd/<plan-id>/`（SDD 运行时 scratch + review bundle；gitignored） |
+| `{ITERATION_DIR}` | `{HARNESS_DIR}/iterations/` |
+| `{KNOWLEDGE_DIR}` | `{HARNESS_DIR}/knowledge/` |
+| `{SPECS_DIR}` | `{HARNESS_DIR}/specs/`（默认）；解析见下文「`{SPECS_DIR}` 解析」 |
+
+> **Engine check (when available):** import `resolveHarnessDir` / `resolvePlanDir` / `resolveSddDir` / `resolveIterationDir` / `resolveSpecsDir` from `@mstar-harness/engine` in a host hook — or run `mstar path resolve [path]` (`--json` for machine output) to print the resolved dirs — to confirm the resolution below. On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
+
+### `{HARNESS_DIR}` 解析顺序（找到即停；探测**永不越过工作区根**——CLI=start 的 git top-level（非 git→start 自身）；dsh=会话工作区）
+
+1. `.mstar/` → `{HARNESS_DIR}=.mstar/`, `{PLAN_DIR}=.mstar/plans/`
+2. 否则 `.agents/` → legacy `{HARNESS_DIR}=.agents/`, `{PLAN_DIR}=.agents/plans/`
+3. 否则 `.plans/` 或 `plans/` → 遗留同目录 `{HARNESS_DIR}={PLAN_DIR}`
+4. 皆无 → 未启用 plan；进度走对话与 Completion Report
+
+并存时 **`.mstar/` 优先**；仅当项目已有 `.agents/` 且无 `.mstar/` 时继续沿用 `.agents/`。
+
+### `{SPECS_DIR}` 解析（找到非空目录即停）
+
+1. `{HARNESS_DIR}/specs/`（默认 `.mstar/specs/`）
+2. `docs/specs/`
+3. `specs/`（仓库根）
+
+**空目录规则**：候选路径存在但无任何文件 → 视为不存在，继续下一候选。
+
+**创建默认**：全部缺失或皆空 → 创建并使用 `{HARNESS_DIR}/specs/`（统一落在 `.mstar/` 下）。**禁止**在 greenfield init 时优先创建裸仓库根 `specs/`。
+
+**Legacy（仅兼容读）**：若以上皆无内容，但 `{HARNESS_DIR}/designs/` 或仓库根 `designs/` **非空**，可作 `{SPECS_DIR}` 使用；init 时**不**新建 `designs/`。
+
+> **Engine check (when available):** import `resolveSpecsDir` from `@mstar-harness/engine` in a host hook — or run `mstar path resolve` (prints the resolved specs dir) — to confirm the candidate order (empty-dir-as-absent included). On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
+
+可选项目选择：部分 spoke 仓库另跟踪 `{HARNESS_DIR}/roadmap.md` — **非**默认 tracked；仅在项目 opt-in 时提及。
+
+## 内容边界（摘要）
+
+| 区域 | 内容 |
+|------|------|
+| `docs/` | 人类文档：安装、贡献 |
+| `{SPECS_DIR}` | 冻结规格 / ADR |
+| `{ITERATION_DIR}` | 迭代 package（compass + guides/specs） |
+| `{KNOWLEDGE_DIR}` | 实现 SSOT、可复用设计 |
+| `{PLAN_DIR}/` | 主 plan、durable gate summaries、可选 residual prose |
+
+单 plan 的 QC/QA **原始过程报告**默认进入 **`{SDD_DIR}/review/`**（gitignored review bundle），非 `docs/`，也不默认进入 `{PLAN_DIR}`。主 plan 仅保留 durable gate summary；R# open 状态以 `{HARNESS_DIR}/status.json` 为 SSOT。细则 → **`mstar-plan-artifacts`**。
+
+## 初始化 Plan 目录
+
+PM 在需要持久化追踪时：
+
+1. 建 `.mstar/`、`plans/`、`status.json`（空模板见 **`mstar-plan-artifacts/templates/status.empty.json`**）
+2. 可选 `notes.json`（模板 **`mstar-plan-artifacts/templates/notes.empty.json`**）、`knowledge/`、`iterations/`、`{HARNESS_DIR}/specs/`、`sdd/`（空目录占位；运行时 per-plan 子目录由 **`mstar-sdd`** → `mstar sdd workspace <plan-id>` 创建）
+3. 项目根 `.gitignore` 追加 Morning Star **进程产物**忽略集（见下文「Git 跟踪策略」）— CLI `init` 可自动添加
+4. Git：**进程本地、结果共享** — 默认跟踪 `{HARNESS_DIR}/AGENTS.md`、`{KNOWLEDGE_DIR}/**`、`{SPECS_DIR}/**`；`plans/`、`iterations/`、`status.json` 等为**本地会话 SSOT**，默认 gitignored。跨 clone 持久 handoff = knowledge + specs + `{HARNESS_DIR}/AGENTS.md`（及根 `CONCEPTS.md` / `STRATEGY.md` 若使用）；须跨 clone 的 residual 须提升（compound）或写入 tracked results — **勿**默认 `git add` `status.json` / `plans/`。
+
+步骤与 `{HARNESS_DIR}/AGENTS.md` 分层 → **`references/harness-bootstrap-and-agents-layering.md`**。
+
+## Git 跟踪策略（进程 vs 结果）
+
+**原则**：进程留在本地；结果与团队共享。
+
+**默认 tracked（`{HARNESS_DIR}` 下）**：
+
+- `{HARNESS_DIR}/AGENTS.md`
+- `{KNOWLEDGE_DIR}/**`
+- `{HARNESS_DIR}/specs/`（即解析后的 `{SPECS_DIR}` 在 harness 下的默认落点）
+
+**默认 gitignored（`{HARNESS_DIR}` 下）**：
+
+- `archived/`
+- `iterations/`
+- `plans/`
+- `sdd/`
+- `notes.json`
+- `status.json`
+
+Legacy `.agents/` 项目：将上表路径前缀 `.mstar/` 换为 `.agents/`。
+
+**多 worktree（iteration L1）**：默认 gitignored 的进程产物**不会**随 `git worktree add` 进入 feature 检出。读写须经 **control worktree** 绝对路径（`<control_worktree_path>/{HARNESS_DIR}/…`）；产品代码改在 feature worktree。细则与反模式（禁止因 feature 缺 plans 而 `Worktree mode: waived`）→ **`mstar-branch-worktree`**「Harness path SSOT under default gitignore」。
+
+**Canonical `.gitignore` snippet**（skills 与 CLI `init` 对齐）：
+
+```gitignore
+# Morning Star harness (.mstar/)
+# Principle: process stays local; results are shared with the team.
+# Default-ignore everything under .mstar/, then re-include the tracked results.
+.mstar/**
+!.mstar/AGENTS.md
+!.mstar/knowledge/
+!.mstar/knowledge/**
+!.mstar/specs/
+!.mstar/specs/**
+```
+
+Legacy `.agents/` 等价：
+
+```gitignore
+# Morning Star harness (.agents/) — legacy
+# Default-ignore everything under .agents/, then re-include the tracked results.
+.agents/**
+!.agents/AGENTS.md
+!.agents/knowledge/
+!.agents/knowledge/**
+!.agents/specs/
+!.agents/specs/**
+```
+
+> **Engine check (when available):** import `emitGitignoreSnippet` / `validateGitignore` from `@mstar-harness/engine` in a host hook to emit or validate the canonical snippet above. On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
+
+## Spec 驱动的分支模型（多 Plan · 同一 Spec）
+
+- **Iteration base branch**：创建 Spec/iteration 集成分支的祖先分支或 ref；必须显式记录，不能默认 `main` / `master`。
+- **Spec 集成分支**：从 `iteration_base_branch` 创建；各 Plan 实现 merge 回此线后再视为 Spec 在代码侧集成。
+- **Plan 实现分支**：每 `plan_id` 一条（PM 书面）。
+- **PR target**：全部 Plans 与 iteration-close 完成后，向显式 `target_branch` 提 PR（窄例外见 Assignment `Branch policy`）。
+- Git 操作与 QC 单一 `HEAD` → **`mstar-branch-worktree`**。
+- `status.json` 登记 root `metadata.iteration_base_branch` / `metadata.target_branch`，以及 plan `metadata.spec_integration_branch` / `merge_target` → **`mstar-plan-artifacts`**。
+
+**解析顺序**（`mstar-iteration` §2.3）：`status.json` metadata → compass frontmatter → 向用户确认。**禁止**因仓库默认分支名为 `main`/`master` 就自动采用。
+
+## Plan-Writing Path Gate
+
+Plans are written to **`{PLAN_DIR}`** when persistent plan tracking is enabled. Do not introduce external default plan directories.
+
+> **Engine check (when available):** import `assertPlanWritingPath` from `@mstar-harness/engine` in a host hook to enforce the gate above. On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
+
+## 状态与权限（摘要）
+
+`Todo` | `InProgress` | `InReview` | `Blocked` | `Done` — **`Done` 仅 PM 或 QA**。字段与 residual → **`mstar-plan-artifacts`**。主 plan checkbox → **`mstar-plan-artifacts`**。
+
+## 未启用 Plan 时
+
+无 plan 目录：PM 用对话追踪；门禁（QC/QA）仍适用；复杂度上升时可建议初始化。
+
+## 实现角色最小阅读
+
+仅需路径符号与 `plans[].metadata` 的 `primary_spec` / `spec_refs` 时：读本 SKILL 至「路径符号」+ **`mstar-plan-artifacts/references/knowledge-and-designs.md`** 即可，**不必**通读 status/residual 全文。
+
+## References
+
+- `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、review bundle / durable summaries、`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,50 @@
+# 产物存储路径（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-plan-conventions` SKILL.md「Git 跟踪策略」：**进程本地、结果共享** — `plans/`、`iterations/`、`status.json`、`sdd/` 等默认 gitignored；`AGENTS.md`、`knowledge/`、`specs/` 默认 tracked。
+
+| 产物 | 解析后路径（默认 `.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`（gitignored；本地会话 SSOT） | PM / `mstar-plan-artifacts` |
+| **Review bundle（QC/QA 原始过程报告）** | `{HARNESS_DIR}/sdd/<plan-id>/review/`（gitignored；默认 `.mstar/sdd/<plan-id>/review/`） | `mstar-sdd`、`mstar-review-qc`、`qa-engineer` |
+| **SDD scratch** | `{HARNESS_DIR}/sdd/<plan-id>/`（gitignored；含 per-task handoff 与 `review/` bundle） | `mstar-sdd` |
+| **status.json** | `.mstar/status.json`（gitignored；本地会话 SSOT） | `mstar-plan-artifacts` |
+| **迭代 package** | `.mstar/iterations/<iteration-id>/`（gitignored；`delivery-compass.md`、`guides/`、`specs/`、可选 `README.md`） | `mstar-iteration`（读写）；close 时 `mstar-compound`（提升读；默认排除 compass） |
+| **迭代索引** | `.mstar/iterations/README.md`（gitignored；一行 = 一次迭代） | `mstar-iteration`（读写） |
+| **规格** | `{HARNESS_DIR}/specs/`（默认 tracked；解析见 `mstar-plan-conventions`） | `mstar-plan-artifacts` |
+| **harness AGENTS** | `.mstar/AGENTS.md`（tracked） | PM / init |
+| **archived residuals** | `.mstar/archived/residuals/<plan-id>.json`（gitignored） | `mstar-plan-artifacts` |
+| **archived knowledge** | `.mstar/archived/knowledge/`（保留原 `{KNOWLEDGE_DIR}` 相对路径） | `mstar-iteration` §1.6 corpus hygiene、`mstar-plan-artifacts` |
+| **archived specs** | `.mstar/archived/specs/`（保留原 `{SPECS_DIR}` 相对路径） | `mstar-iteration` §1.6 corpus hygiene、`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}/` | 迭代 package（compass + guides/specs）；知识文档不放此处 |
+| `{SPECS_DIR}/` | 仅限冻结规格/ADR，运行时知识不放此处 |
+| `{PLAN_DIR}/reports/` | Legacy / explicit audit mode only；默认 QC/QA 原始过程报告进 `{SDD_DIR}/review/`，知识文档不放此处 |
+
+## `<category>` 取值
+
+知识文档的 `<category>` 子目录由 `mstar-compound` 的 `references/category-mapping.md` 定义，在 `{KNOWLEDGE_DIR}` 下按需创建。示例：`runtime-errors/`、`conventions/`、`architecture-patterns/` 等。

package/harness-skills/mstar-plan-conventions/references/effort-estimation.md

@@ -0,0 +1,38 @@
+# 工期与工作量预估（Agent 语境 · Morning Star）
+
+> **Load order（与其它 `mstar-*` skill 一致）**：写 Effort 字段前须已 Read **`mstar-harness-core`** skill（SKILL.md）以对齐「仅 agent-oriented、禁止人天/日历」的全局不变量；本 reference 为口径细则展开。
+
+在 OpenCode / Cursor 等多角色 agent 编排下，**所有「工期 / 工作量 / Effort」类预估只描述 agent 实施量级**：在规格与验收已就绪、上下文可加载的前提下，**agent 连续或少量会话内**完成实现与基础自证（跑通命令/单测等）需要多少**agent 工作量**。
+
+## 硬性规则（不得混入人工时间）
+
+凡使用本 harness 的计划、PRD、架构文档、Assignment、Status Update 中的 **Effort / 工期 / 预估** 表述：
+
+- **必须**只反映 **agent 执行与会话**（见下节尺码与会话带）。
+- **禁止**纳入任何**人类时间**，包括但不限于：人天 / person-days / FTE、人类日历天或周、等待人工评审、会议、排期空档、发布窗口、合规签批排队、跨团队人类响应时间。
+- **禁止**用「标了轴的人天」变相写人类时间；**本节字段内不要使用人天 / FTE / 人类日历**。
+- **QC/QA 在流程中的迭代**：视为 **agent 会话**的一部分（可多算几次会话），**不要**单独加「人类审查要等 X 天」。
+
+若业务方必须另做**人类排期或合同人天**，须在**与本 Effort 字段完全分离**的文档或章节（例如路线图、商务附件）中撰写，**不得**写进 `Effort (agent-oriented)` 或同名小节，以免与 agent 预估混读。
+
+## 推荐写法：T 恤尺码 + agent 会话带
+
+1. **XS**：单文件 / 单测点 / 配置微调 — 通常 **<1** 次完整 agent 回合可交付。  
+2. **S**：局部模块小改 — 约 **1** 次专注会话。  
+3. **M**：单功能横切少量文件 — 约 **1–3** 次会话（含流程内 QC/QA agent 迭代则取上沿）。  
+4. **L**：多模块、新子系统、或强依赖摸底 — 约 **3–8** 次会话；**应拆里程碑**。  
+5. **XL**：接近子系统级或未知域 — **先 spike / 原型**，未摸底前不给紧凑数字预估。
+
+「**会话**」指：一次连贯的 agent 运行（读上下文 → 实现 → 运行验证），**不是**人类 8 小时工作日。
+
+## 文档与模板中的字段名（建议）
+
+- **PRD / 产品文档**：**`## Effort (agent-oriented)`** — 仅 **Complexity (XS–XL) + agent session band + 假设**（规格已锁、契约稳定等）。  
+- **架构 / 技术计划**：**`### Implementation effort (agent-oriented)`** — 同上；区分 **spike** vs **build**。  
+- **PM Assignment `Constraints`**：**`Effort (agent-oriented)`**: `M, ~2–4 agent sessions — assumes plan locked and contracts stable`。  
+- **Status Update**：剩余工作仅用 agent 会话语言（如「约 1 次会话可收口」），**不写**人类日历或人天。
+
+## 与不确定性的关系
+
+- **规格未锁、接口未定、依赖外部凭证**：标 **`blocked` / `spike required`**，改为「先 1 次摸底会话再更新 Effort」，仍**只**用 agent 会话描述。  
+- **高危变更 / 生产发布**：人类审批或发布节奏**不计入**本节 Effort；若需记录依赖，用 **阻塞/依赖清单**（非时间预估字段）。

package/harness-skills/mstar-plan-conventions/references/harness-bootstrap-and-agents-layering.md

@@ -0,0 +1,93 @@
+# Harness 初始化与 `AGENTS.md` 分层策略（Morning Star）
+
+> **Load order**：使用本参考初始化仓库前，须先 Read `mstar-harness-core` 与 `mstar-plan-conventions`；冲突以 `mstar-harness-core` 为准。
+
+## 目标
+
+给新仓或迁移仓提供一套可复制的启动方式，确保：
+
+- `status.json` / residual / review bundle 有唯一落点；
+- 根规则与 harness 规则不互相覆盖；
+- 目录级 `AGENTS.md` 只承载增量边界，不变成重复手册。
+
+## Bootstrap 最小步骤
+
+1. 创建 `{HARNESS_DIR}`（推荐 `.mstar/`）与 `{PLAN_DIR}`（推荐 `.mstar/plans/`）。
+2. 初始化 `status.json`：从 **`mstar-plan-artifacts/templates/status.empty.json`** 复制；residual canonical 见 **`mstar-plan-artifacts` SKILL.md**；字段与生命周期见 **`mstar-plan-artifacts/references/status-and-residuals.md`**。
+3. 初始化可选 `notes.json`（**`mstar-plan-artifacts/templates/notes.empty.json`**）；`sdd/` 空目录占位（per-plan 子目录由 **`mstar-sdd`** → `mstar sdd workspace <plan-id>` 创建）。
+4. 项目根 `.gitignore` 追加 Morning Star **进程产物**忽略集（canonical snippet → `mstar-plan-conventions` SKILL.md「Git 跟踪策略」；legacy `.agents/` 有等价表）。
+5. **Profile B**（统一 Done 压缩）时另建 `{HARNESS_DIR}/archived/plans/` 与 `archived/plans-done.json`（自 **`mstar-plan-artifacts/templates/plans-done.empty.json`** 复制；schema 仅 `{ "plans": [] }`，见 **`mstar-plan-artifacts/references/done-compaction.md`**）。
+6. 可选：创建 `{ITERATION_DIR}`（`iterations/` + `README.md`）与 `{KNOWLEDGE_DIR}`（`knowledge/` + `README.md`）；`{HARNESS_DIR}/specs/`（解析后的 `{SPECS_DIR}` 默认落点）；内容边界见 `mstar-plan-conventions` SKILL.md 与 `references/knowledge-and-designs.md`。
+7. 创建 `{HARNESS_DIR}/AGENTS.md`（harness 子树规则；**tracked**）：符号表可复述 `{HARNESS_DIR}`、`{PLAN_DIR}`、`{ITERATION_DIR}`、`{KNOWLEDGE_DIR}`、`{SPECS_DIR}` 与 `docs/` 分工；新项目推荐 `.mstar/AGENTS.md`，已有项目可继续使用 `.agents/AGENTS.md`。
+8. 校准根 `AGENTS.md`：只保留仓库级长期约束，显式引用 `{HARNESS_DIR}/AGENTS.md` 作为 harness SSOT。
+9. 仅在确有稳定边界时新增目录级 `AGENTS.md`（如 `contracts/`、`gateway/`、`sdk/`）。
+
+## Git 跟踪策略（进程 vs 结果）
+
+**原则**：进程留在本地；结果与团队共享。完整规则与 canonical `.gitignore` snippet → **`mstar-plan-conventions` SKILL.md「Git 跟踪策略」**。
+
+| 类别 | 默认 tracked | 默认 gitignored |
+|------|--------------|-----------------|
+| 结果（跨 clone handoff） | `{HARNESS_DIR}/AGENTS.md`、`{KNOWLEDGE_DIR}/**`、`{SPECS_DIR}/**` | — |
+| 进程（本地会话 SSOT） | — | `plans/`、`iterations/`、`status.json`、`notes.json`、`sdd/`、`archived/` |
+
+跨 clone 须持久的 residual 或决策：经 **`mstar-compound`** 提升入 `{KNOWLEDGE_DIR}/`、写入 `{SPECS_DIR}/`，或记入 tracked `{HARNESS_DIR}/AGENTS.md` — **勿**默认 `git add` `status.json` / `plans/`。
+
+## 三层 `AGENTS.md` 职责切分
+
+### 根 `AGENTS.md`（项目层）
+
+- 放：仓库身份、技术边界、构建/测试接口、安全与分支策略、规格路由表。
+- 不放：动态状态、当前批次进展、R# 明细、QC 单次结论。
+
+### `{HARNESS_DIR}/AGENTS.md`（harness 层）
+
+- 放：`{HARNESS_DIR}`/`{PLAN_DIR}`/`{ITERATION_DIR}`/`{KNOWLEDGE_DIR}`/`{SPECS_DIR}` 契约、`docs/` 与 harness 子树内容边界、状态推进门禁、QC/QA 对齐规则、residual 生命周期、Done compaction profile（Profile B 时声明 `archived/plans-done.json` 仅为 `{ "plans": [<plan-id>, ...] }`，细则见 **`mstar-plan-artifacts/references/done-compaction.md`**）。
+- 不放：语言/框架编码细节、业务模块实现约束。
+
+### `<subdir>/AGENTS.md`（边界层）
+
+- 放：该目录独有的边界、禁区、接口命令与升级触发。
+- 不放：根级通用规则复写、harness 全量规则拷贝。
+
+## 分目录 `AGENTS.md` 创建准入
+
+仅当满足任一条件时创建：
+
+- 目录具备独立风险模型（如链上合约 vs 网关服务）；
+- 目录有单独发布面或对外 API 面；
+- 目录有稳定且长期存在的专属约束（构建、依赖、数据/安全边界）。
+
+若仅是代码组织而无新增约束，不创建目录级 `AGENTS.md`。
+
+## 推荐模板骨架（目录级）
+
+```markdown
+# AGENTS.md — `<dir>/`
+
+## Source Priority
+1. Current user instruction
+2. Root `AGENTS.md`
+3. This file
+4. `{HARNESS_DIR}/AGENTS.md`
+
+## Boundary Rules
+- ...
+
+## Build & Test (interface)
+- ...
+
+## Escalation Triggers
+- ...
+```
+
+## 反模式与修正
+
+- 反模式：在根 `AGENTS.md` 维护当前计划进展与 commit 列表。  
+  修正：迁移到 `status.json` 的 `plans[].metadata` 与 `notes.json`。
+
+- 反模式：每个子目录复制一份完整 harness 规则。  
+  修正：保留一行引用 `{HARNESS_DIR}/AGENTS.md`，仅写本目录增量约束。
+
+- 反模式：目录级规则未声明 Source Priority，冲突时不可裁决。  
+  修正：统一四级优先级模板并在每个目录级文件开头声明。

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

@@ -0,0 +1,60 @@
+---
+name: mstar-review-qc
+description: "Morning Star QC orchestration — **SDD mandatory plan QC tri-review** (`{SDD_DIR}/review/qc1.md`…`qc3.md` + consolidated); inline/hotfix single-seat (`qc.md` in review bundle); PM dispatch timing, tri identity gate, residual registration contract, layer boundaries, durable plan summary. Leaf QC execution → **`mstar-roles/references/qc-specialist/`**. Per-task review is **`mstar-sdd`** (L2). Primary reader: **`project-manager`** when dispatching or consolidating QC."
+---
+
+## Load order（必读顺序）
+
+**首次 Read 本 skill 时：必须先 Read `mstar-harness-core`。** 同仓检出与派发 → **`mstar-branch-worktree`** · **`mstar-dispatch-gates`**。冲突时 **以 `mstar-harness-core` 为准**。
+
+**摘要**：职责分层 → **`references/review-responsibility-boundaries.md`**（**L3 = code reviewer / diff+logic；不跑 test/build**；运行时验证归 L1/L4）。Leaf QC 执行 → **`mstar-roles/references/qc-specialist/`**。L4 验收 → **`mstar-roles/references/qa-engineer/`**。
+
+# Morning Star QC Orchestration（PM · 编排层）
+
+## L3 是什么（派发前对齐）
+
+- Plan QC seats are **reviewers**: whole-branch **diff / logic / risk** lenses — same family as PR review, not a parallel QA test lane.
+- **Do not** instruct QC in Assignment to “run the suite / build / lint to confirm” on shared tri cwd; that causes peer `Blocked` and collapses L3 into L4.
+- Runtime proof stays with **implementer evidence** and **`QA gate`** (`qa-engineer` or PM acceptance).
+
+## 分派时机（与 plan / batch 对齐）
+
+- **`Execution mode: sdd`**：全部 task + L2 task reviewers 完成后 → **强制 tri-review**（`QC mode: full tri-review`，**N=3**）。Assignment 须含 **branch review-package** 路径与 `{SDD_DIR}/review/qcN.md` report paths。PM 汇总 `{SDD_DIR}/review/qc-consolidated.md` 并回写主 plan durable summary。
+- **`Execution mode: inline`**：单席 `qc-specialist` → `{SDD_DIR}/review/qc.md`（**N=1**），或按 hotfix 路由跳过。
+- **After `Request Changes` (default)**：**Targeted re-review** — PM dispatches only seats that **raised** blocking findings; each updates **the same** `{SDD_DIR}/review/qcN.md` (`## Revalidation`, update verdict). **Do not** spawn `qcN-rev2.md` for targeted re-review. Naming → **`mstar-plan-artifacts/references/plan-files-and-reports.md`** § QC 三审触发时机.
+- **Full tri re-review (exception)**：Assignment **`QC re-review: full tri-review`** → new basenames (`qc1-rev2.md` …); PM marks **active wave** in consolidated decision.
+
+> **Engine check (when available):** run `mstar review seats <assignment-file> [--mode sdd|inline|targeted] [--reviewers <role1,role2,...>]` (or `import { executionModeToN, assertTriIdentity } from "@mstar-harness/engine"` in a host hook) to map `Execution mode` to its QC seat count N above and assert tri identity. On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
+
+## 三审身份与模型独立性门禁（PM 强制）
+
+在 PM 发出 **initial** QC 三审后、进入汇总前：
+
+- **Initial wave**：三个角色 ID 须为 `qc-specialist`、`qc-specialist-2`、`qc-specialist-3`；模型与宿主配置一致。
+- **Targeted re-review**：仅校验 Assignment 列出的席位；映射错误 → `dispatch invalid`，重派。
+- 并行 QC 退化为同模型且无法修复 → Status Update 标记 `degraded tri-review`；默认不放行。
+
+## Residual Findings 留档门禁（PM）
+
+- 先读 Assignment **`Findings cleanup`**（及可选 `plans[].metadata.findings_cleanup`）→ **`mstar-plan-artifacts/references/status-and-residuals.md`**「Findings cleanup modes」。
+- **`Findings cleanup: zero-residual`**（iteration Phase 2 默认）：可修 **Warning / Suggestion / Critical** → **fix-now + targeted re-review**，**禁止**把可修项登记为 open R# 或用 `Approve with residuals` 收口；**`nit`** 当场修或丢弃（无 R#）。仅 **真 blocker-defer**（外部依赖 / 须下轮产品决策 / 用户本轮显式 defer + Durable Roadmap）可登记 open R#（`decision: defer`）。此时 `Approve with residuals` **仅**允许剩余项全是该类 defer。
+- **`Findings cleanup: allow-residual`**（standalone / hotfix / inline 默认）：阻断项修复后仍有 **Warning / Suggestion** 或技术债 → 必须留档；**`Approve with residuals`** 仅当无 open **Critical**；PM 汇总结论须含 residual 清单与跟踪位置。
+- **`severity`** 仅允许 `mstar-plan-artifacts/references/status-and-residuals.md` 枚举。
+- **Open SSOT**：`{HARNESS_DIR}/status.json` 根级 **`residual_findings[<plan-id>]`**；PM 在 consolidated 决策分配 **R1…** 并写入。关闭 → **`{HARNESS_DIR}/archived/residuals/<plan-id>.json`**。
+- 主 plan 仅作人类索引；不得作为唯一 SSOT。
+- 未完成 residual 留档（`allow-residual`）或未清干净可修 findings（`zero-residual`）→ 不得进入 plan **Done**。
+
+### Residual 关闭与验证
+
+- R# 修复后：审查/QA 结论指向可复核证据；**`project-manager`** 或 **`qa-engineer`**（`QA gate: mandatory`）补全关闭字段后归档并从 open 列表移除。
+- **`waived` / `superseded` / `duplicate`** 须在 `closure_note` 写清依据。
+
+## PM consolidated 门禁（摘要）
+
+Leaf reviewers apply verdict per **`mstar-roles/references/qc-specialist/report-template.md`**. PM **`{SDD_DIR}/review/qc-consolidated.md`** synthesizes tri (or single-seat `qc.md`) into one gate decision for implement fix waves and QA gate, then records the durable summary in the main plan/status artifacts.
+
+## 证据规则（PM · consolidated 输入）
+
+- Critical 发现须含触发条件、影响范围、修复建议。
+- 低置信度发现须含后续验证步骤。
+- 跨任务重复模式应标记。

package/harness-skills/mstar-review-qc/references/review-responsibility-boundaries.md

@@ -0,0 +1,54 @@
+# Review responsibility boundaries (1.0.0+)
+
+## Four layers (orthogonal — do not collapse)
+
+| Layer | Who | When | Scope | Input |
+|-------|-----|------|-------|--------|
+| **L1** Implementer | dev subagent | Per task | Write code + **run** TDD / verification evidence | `task-N-brief.md` |
+| **L2** Task reviewer | `code-reviewer` (default; generic fallback when the host agent list lacks it) — PM-dispatched subagent (SDD) | Per task, after implementer | Spec + quality for **one task** (diff-first; no full suite) | brief, report, **task-level** diff |
+| **L3** Plan QC tri (cross-review) | `qc-specialist` + `qc-specialist-2` + `qc-specialist-3` | After **all** tasks on branch | **Code-review seat** — diff, language/logic, security & contract lenses on **whole branch**; **not** the test-execution path | Branch `review-package` MERGE_BASE..HEAD |
+| **L4** QA | `qa-engineer` when **`QA gate: mandatory`**; else PM acceptance | After QC gate | DoD acceptance, residual verify, targeted/full **command** verification, Done recommendation | Review bundle + plan + **L1 evidence** + `status.json` |
+
+PM sets **`QA gate`** per `mstar-roles/references/project-manager/qa-trigger-matrix.md`. L4 execution when dispatched → `mstar-roles/references/qa-engineer/acceptance-gate.md`.
+
+### L3 vs L4 vs L1 — who runs commands?
+
+| Duty | Owner | QC (`qc-specialist*`) |
+|------|-------|------------------------|
+| Produce runnable test/build evidence | **L1** implementer | **Does not** own |
+| Diff / logic / vulnerability / contract review | **L3** QC (and L2 task reviewer) | **Primary job** |
+| Map DoD → evidence; re-run gaps; close residuals | **L4** QA (or PM acceptance) | **Does not** own |
+| Full / targeted test suites, builds, installs | **L1** and/or **L4** | **NEVER** — leave to QA/dev |
+
+**Why:** SDD plan QC is **N=3 parallel** on a **shared** `Review cwd`. Build/test/lint toolchains contend for caches and locks and falsely `Blocked` peer reviewers. QC is a **reviewer**, not a second QA lane.
+
+**SDD rule:** Layers L1–L2 run **per task** (serial). Layer L3 is **mandatory full tri-review** (`N=3`) whenever **`Execution mode: sdd`** — single-plan **and** iteration **and** multi-plan iteration. Layer L3 is **not** optional “final single review”.
+
+**Non-SDD (`Execution mode: inline`):** hotfix / single-stream — plan QC may be **single-seat** (`qc.md`) or skipped per PM routing.
+
+Per-task spec/quality is **done** in L2 before L3. QC seats do not re-derive each task from scratch; they cross-review the **whole branch** for gaps L2 could not see.
+
+## Plan QC tri (SDD mandatory)
+
+- Assignment: **`QC mode: full tri-review`** (implicit when `Execution mode: sdd`; PM may state explicitly).
+- **N=3** same dispatch message: QC#1 architecture/maintainability → `{SDD_DIR}/review/qc1.md`; QC#2 security/correctness → `{SDD_DIR}/review/qc2.md`; QC#3 performance/reliability → `{SDD_DIR}/review/qc3.md`.
+- PM **`{SDD_DIR}/review/qc-consolidated.md`** — cross-review synthesis; PM gate input and source for durable main-plan summary.
+- Dispatch must include **Review package path** (branch diff file).
+- **NEVER** substitute a single `qc-specialist` for L3 when SDD was used, unless user override: `QC mode: single — override: <reason>`.
+
+## Plan QC single-seat (inline / exception only)
+
+- Report: `{SDD_DIR}/review/qc.md`
+- `Execution mode: inline` hotfix paths; or explicit override on SDD plan.
+- `N=1`; no `qc-consolidated.md` required.
+
+## Fix waves
+
+| After | Fix dispatch |
+|-------|----------------|
+| Task review Critical/Important | Task fix subagent → task re-review (L2) |
+| Plan QC Critical/Important | **One** fix subagent with **complete** finding list → **targeted** QC re-review (listed seats) |
+
+## Minor findings
+
+Task reviewer Minor → `{SDD_DIR}/progress.md` § Minor. Plan QC Minor → `{SDD_DIR}/review/qcN.md` + optional residual via PM.

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

@@ -0,0 +1,86 @@
+---
+name: mstar-roles
+description: Morning Star role prompt hub — `agents/*.md` shells plus full behavior in `references/*.md`, each with a **Required Skill Dependencies** list (which `mstar-*` topic skills to load after `mstar-harness-core`). Always load for any Morning Star role (`project-manager`, `product-manager`, `architect`, `code-reviewer`, `fullstack-dev`, `fullstack-dev-2`, `frontend-dev`, `qa-engineer`, `qc-specialist*`, `ops-engineer`, `writing-specialist`, `prompt-engineer`). Cross-role **Role → typical topic skills** summary in this SKILL.md; per-role lists in `references/*.md` are authoritative for that role's session. Full topic skill index → **`mstar-harness-core`**.
+---
+
+## Load Order (Required)
+
+When a Morning Star role starts work in a session:
+
+1. Read `mstar-harness-core` first (SKILL.md), then **only** the topic `mstar-*` skills required for this role/task (see matrix below — do not read all topic skills by default).
+2. Read this `mstar-roles` skill.
+3. Resolve role mapping and parameter table below.
+4. Read the corresponding `references/<role>.md` file — each role file lists **Required Skill Dependencies** for that role (canonical per-role load list).
+5. Expand placeholders from role parameters before execution.
+
+If any conflict appears, `mstar-harness-core` remains the authoritative source for lifecycle, gates, routing, and invariants. The table below is the cross-role summary; when a role file lists different **on-demand** skills, follow the role file for that session.
+
+## Role Reference Mapping
+
+| Agent id | Reference file | Parameterized slots |
+| --- | --- | --- |
+| `project-manager` | `references/project-manager.md` | — |
+| `product-manager` | `references/product-manager.md` | — |
+| `architect` | `references/architect.md` | — |
+| `code-reviewer` | `references/code-reviewer.md` | — |
+| `fullstack-dev` | `references/fullstack-dev-shared.md` | `role_id`, `track` |
+| `fullstack-dev-2` | `references/fullstack-dev-shared.md` | `role_id`, `track` |
+| `frontend-dev` | `references/frontend-dev.md` | — |
+| `qa-engineer` | `references/qa-engineer.md` | — |
+| `qc-specialist` | `references/qc-specialist-shared.md` | `role_id`, `reviewer_index`, `focus`, `report_suffix` |
+| `qc-specialist-2` | `references/qc-specialist-shared.md` | `role_id`, `reviewer_index`, `focus`, `report_suffix` |
+| `qc-specialist-3` | `references/qc-specialist-shared.md` | `role_id`, `reviewer_index`, `focus`, `report_suffix` |
+| `ops-engineer` | `references/ops-engineer.md` | — |
+| `writing-specialist` | `references/writing-specialist.md` | — |
+| `prompt-engineer` | `references/prompt-engineer.md` | — |
+
+### Role → typical topic skills (after `mstar-harness-core`)
+
+| Role | Typical adds |
+| --- | --- |
+| `project-manager` | `mstar-dispatch-gates`, `mstar-phase-gates`, `mstar-plan-conventions`, `mstar-roles` ref; + `references/project-manager/qa-trigger-matrix.md` for QA gate tiers; + `mstar-review-qc` before QC; + `mstar-branch-worktree` / `mstar-plan-artifacts` as the round requires; + `mstar-skill-authoring` for skill work; + `mstar-iteration` for iteration lifecycle (start/drive/close); + `mstar-strategy` for strategic alignment; + `mstar-compound` / `mstar-compound-refresh` pre-loaded by `mstar-iteration` § iteration-close |
+| `fullstack-dev*`, `frontend-dev` | `mstar-coding-behavior`, `mstar-dispatch-gates`, `mstar-branch-worktree` (if repo writes); plan path symbols from `mstar-plan-conventions` (minimal); `mstar-design-md` when implementing styled UI |
+| `qc-specialist*` | `mstar-branch-worktree`, `mstar-plan-artifacts` (review bundle paths); `references/qc-specialist/` (workflow, checklist, template, lenses); `mstar-design-md` when reviewing UI |
+| `qa-engineer` | `mstar-branch-worktree`, `mstar-plan-artifacts` (closing R#); `references/qa-engineer/acceptance-gate.md`; `mstar-design-md` when verifying visual output |
+| `architect`, `product-manager` | `mstar-phase-gates` (Prepare), `mstar-plan-artifacts` (knowledge/specs); `mstar-design-md` (creator + design intent); `mstar-strategy` (STRATEGY.md creation/maintenance) |
+| `code-reviewer` | `mstar-sdd` (per-task review mode); `mstar-audit` (audit mode: full workflow); `mstar-plan-conventions` (paths); `mstar-plan-artifacts` (plan-quality-bar for audit plans) |
+| `ops-engineer` | `mstar-coding-behavior`, `mstar-branch-worktree` |
+| `prompt-engineer` | All topic skills when editing harness text |
+
+Use skill names (not absolute filesystem paths) in role references.
+
+Role `references/*.md` files include explicit **`NEVER`** sections (anti-recursion, tool misuse, Git discipline). Treat those bullets as **hard gates** alongside `mstar-harness-core`; do not treat them as optional style tips.
+
+## Parameter Table (SSOT)
+
+### Dev track (`fullstack-dev` family)
+
+| role_id | track | Meaning |
+| --- | --- | --- |
+| `fullstack-dev` | `primary` | Backend-led primary implementation track |
+| `fullstack-dev-2` | `parallel_secondary` | Second implementation track for parallel independent modules |
+
+### QC reviewer (`qc-specialist*` family)
+
+**Job:** Independent **code review** on the plan branch diff (logic, security, contracts, maintainability, reliability). **Not** test execution — suites/builds belong to implementer (L1) and `qa-engineer` (L4). See `mstar-review-qc/references/review-responsibility-boundaries.md`.
+
+**Default (SDD):** plan QC tri-review — `qc-specialist` / `qc-specialist-2` / `qc-specialist-3` → `{SDD_DIR}/review/qc1.md`…`qc3.md` + `qc-consolidated.md` when **`Execution mode: sdd`**.
+
+**Exception (`inline` / hotfix):** single-seat → `{SDD_DIR}/review/qc.md` (`QC mode: single`).
+
+| role_id | reviewer_index | focus | report_suffix |
+| --- | --- | --- | --- |
+| `qc-specialist` | `1` | Architecture coherence and maintainability risk | `qc1` → `{SDD_DIR}/review/qc1.md` |
+| `qc-specialist-2` | `2` | Security and correctness risk | `qc2` → `{SDD_DIR}/review/qc2.md` |
+| `qc-specialist-3` | `3` | Performance and reliability risk | `qc3` → `{SDD_DIR}/review/qc3.md` |
+
+PM consolidated (tri mode): `{SDD_DIR}/review/qc-consolidated.md` (same folder; no `<plan-id>` basename prefix) + durable main-plan summary. Naming SSOT: `mstar-plan-artifacts/references/plan-files-and-reports.md`.
+
+> **Engine check (when available):** import `validateRoleMapping` / `lintLoadOrder` from `@mstar-harness/engine` in a host hook to validate the mapping and parameter tables above against the on-disk `references/*.md` layout (shared families included) and lint the load-order declarations (no CLI form yet). On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
+
+## Maintenance Rules
+
+- Edit behavior in `references/*.md`.
+- Edit role family parameters in this file.
+- Keep shared-family roles (`fullstack-dev*`, `qc-specialist*`) on one shared reference file.
+- Add new roles by updating mapping, parameters (if needed), and adding corresponding `agents/*.md` shell.

package/harness-skills/mstar-roles/references/_shared/leaf-executor-core.md

@@ -0,0 +1,46 @@
+# Leaf Executor Core (shared blocks)
+
+> Shared by all leaf-executor role references in `mstar-roles/references/`. Each role file references this for the identical Completion Report template, repo-write Git discipline, and plan/documentation rules. **Read `mstar-harness-core` first.** Role-specific NEVER rules, mission, and responsibilities stay in each role file — this file holds only the uniform blocks.
+
+## Completion Report
+
+Every leaf executor returns this template (only `**Agent**` and content fields change per role):
+
+```markdown
+## Completion Report
+
+**Agent**: {role_id}
+**Task**: ...
+**Status**: Done | Blocked | Partial
+**Scope Delivered**: ...
+**Artifacts**: ...
+**Validation**: ...
+**Issues/Risks**: ...
+**Plan Update**: ...
+**Handoff**: ...
+**Git**: ...
+```
+
+`{role_id}` = the role's own id (e.g. `fullstack-dev`, `frontend-dev`, `ops-engineer`, `qa-engineer`, `architect`, `code-reviewer`, `product-manager`, `prompt-engineer`, `writing-specialist`, `qc-specialist*`).
+
+## Git NEVER (repo writes)
+
+Apply when the assignment writes tracked repo files:
+
+- **NEVER** skip per–task-ID commits on the authorized `Working branch` when you wrote tracked files — Completion Report **Git** must be a real `git log -1 --oneline` unless read-only was assigned.
+- **NEVER** batch everything into a single closing commit unless PM explicitly allowed it.
+
+## Plan & Documentation Rules
+
+- Follow `{HARNESS_DIR}` / `{PLAN_DIR}` conventions from `mstar-plan-conventions`.
+- Update assigned task checkboxes and plan notes for your scope.
+- Do not mark full plan `Done` (only `project-manager` or `qa-engineer` per `mstar-harness-core`).
+
+## Non-Recursive Dispatch Rule (shared shape)
+
+All leaf executors share this hard rule (role-specific sibling lists stay in each role file):
+
+- Complete assigned work in this session.
+- Do not recursively dispatch sibling roles unless explicitly authorized via `Delegation: allowed (...)`.
+- `Execute as: {role_id}` is identity lock, not orchestration permission.
+- If required inputs are missing or prerequisites unmet, return `Blocked` to PM rather than inventing delegation.