@mstar-harness/opencode 0.2.0

package/harness-skills/mstar-harness-core/references/branch-and-worktree.md

@@ -0,0 +1,131 @@
+# Git 功能分支、同仓并发与 Worktree 对齐（Morning Star）
+
+本 reference 涵盖：功能分支门禁、分支协作契约、同仓并发写入、多 worktree 并行开发与 QC/QA 衔接、plan 集成分支推荐编排。
+
+## Git 功能分支门禁（业务仓库）
+
+适用于 cwd 为 **Git 托管的业务/应用仓库** 且本轮会产生**仓库内可合并 diff** 的任务（代码、业务向测试与 fixture、影响构建或运行时的配置等）。**不**用于约束 `~/.config/opencode/` 全局配置目录（该目录对 agent 只读；落盘仅由用户执行）。
+
+### 默认规则
+
+- 不得在**默认保护分支**（常见名：`main`、`master`；以项目约定为准）上直接实现功能改动，除非 Assignment 含显式例外。
+- 例外须在 Assignment 中写明一行：**`Branch policy: direct on <branch> — <reason>`**（典型：团队约定的热修直接打默认分支）。
+
+### `<base>` 与叠分支（stacked branches）
+
+- 门禁的目标是**不在未授权的默认分支上直接提交**，不是「只能从 `main` 开新分支」。
+- 当需要**从已有功能分支继续拆新分支**时，Assignment 应写清**祖先分支** `<base>`，例如：`create feature/foo-part2 from feature/foo`。
+- **`<base>` 可取**：`main` / `master`（或项目默认分支名）、任意已存在的 `feature/*` / `fix/*`、远程跟踪分支名、或 **`current`**（表示以执行者检出时的 `HEAD` 为祖先，用于「就在当前分支上再拉一枝」）。
+- 若只写 **`Working branch`: `feature/foo`且无「create … from …」**：表示**沿用 / 切到**该已存在分支上开发，不要求新建。
+- 若写新建但未写 `<base>`：实现侧应**停下问** `@project-manager`（或按项目 `AGENTS.md` 的默认 base）；**禁止**擅自假设「一定是 `main`」。
+
+### 角色职责
+
+- **`@project-manager`（唯一分支决策入口）**：向 `@product-manager`（向项目仓库提交产品文档时）、`@architect`（向项目仓库提交技术/架构/契约类文档时）、`@fullstack-dev` / `@frontend-dev` / `@fullstack-dev-2`、以及会向仓库提交工件的 `@qa-engineer`、会改仓库内文件的 `@ops-engineer`、对**项目仓库**落盘的 `@prompt-engineer` 分派前，核对分支策略；在 Assignment 中写明 **`Working branch`**（沿用已有分支名，或 `create <new-branch> from <base>`，其中 `<base>` 遵守上一节）。若用户已指定分支/祖先，照抄进 Assignment。**只有 `@project-manager` 可以决定是否新开分支、从哪个 `<base>` 开分支。**
+- **实现 / QA / 运维 / prompt / product-manager / architect（项目侧）**：在**首次**编辑仓库内文件或执行 `git commit` 前，核对当前分支与 Assignment，并在回报中明确"正在哪个分支上工作"。**禁止自行决定新开分支、禁止自行切回 `main`/`master` 重开分支。**若未授权 `Branch policy` 且当前在默认分支，则仅可按 PM 已写明的 `Working branch` 执行切换/开枝；若 Assignment 未写清或与现场分支不一致，先回报 `@project-manager`，不得擅自处理。
+
+## 分支协作契约（Branch Collaboration Contract）
+
+### 适用范围
+
+- 当任务会在项目 Git 仓库产生可合并 diff 时适用。
+- 适用于 `@project-manager`、`@product-manager`、`@architect`、`@fullstack-dev`、`@frontend-dev`、`@fullstack-dev-2`、`@qa-engineer`、`@ops-engineer`、`@prompt-engineer`（项目侧写入）。
+
+### 唯一分支决策者
+
+- 只有 `@project-manager` 可以决定分支策略：
+  - 继续在现有分支开发，或
+  - 使用 `create <new-branch> from <base>` 新开分支，或
+  - 使用 `Branch policy: direct on <branch> — <reason>`。
+- 其他可写角色不得自行决定开分支。
+
+### PM 必须先与用户确认
+
+在派发实现任务前，PM 必须先检查当前分支；若已在非默认开发分支（如 `feature/*`、`fix/*`），必须先与用户确认。
+
+未获得用户明确确认前，PM 不得切回 `main`/`master` 并新开分支。
+
+#### PM 确认话术模板
+
+面向用户沟通时，使用以下结构：
+
+```markdown
+当前检测到在分支：`<current-branch>`。
+请确认本次任务是：
+1) 继续在 `<<current-branch>>` 上开发
+2) 新开分支：`<new-branch>`，基于 `<base-branch>`
+
+未确认前，我不会切回 `main`/`master` 或新开分支。
+```
+
+### Assignment 要求（PM）
+
+每个可写 Assignment 必须且只能包含以下之一：
+
+- `Working branch: <existing-branch>`
+- `Working branch: create <new-branch> from <base>`
+- `Branch policy: direct on <branch> — <reason>`
+
+若是新开分支但缺少 `<base>`，必须暂停并向用户澄清，不能猜测。
+
+### 可写角色执行规则
+
+在首次写仓库或 `commit` 之前：
+
+1. 校验当前分支与 Assignment 是否一致。
+2. 只能执行 PM 在 Assignment 中定义的分支策略。
+3. 禁止自行切回 `main`/`master` 再重开分支流程。
+4. 若 Assignment 含糊或与本地分支状态冲突，先停下并回报 PM。
+
+### 回报要求
+
+可写角色在 Completion Report 中必须明确当前工作分支，例如：
+
+- `Working branch used: <branch-name>`
+
+## 同仓并发写入与 Git worktree（强制）
+
+**首要场景是开发阶段**：多条可写流 **并发** 改 **同一仓库** 时，用 worktree 做 **写入侧目录隔离**。下列规则针对该类开发并发；**QC / QA 阶段的检出约定**见下一小节。
+
+当 **`@project-manager` 在同一调度轮次内并发启动多个** subagent（含宿主侧「并行 Task / 并行 subagent」），且 **≥2 个承接方**可能对 **同一 Git 仓库的同一工作区（同一 cwd 检出目录）**产生写文件或 `git commit` 级改动时：
+
+- **必须**为每条并发写流使用 **独立检出目录**：以 **`git worktree`** 隔离（流程与目录安全要求见 Superpowers **`using-git-worktrees`**；未安装插件时仍须达到同等隔离效果，可 Read 该技能文件并按 `git worktree` 手册执行）。
+- **必须**与既有分支门禁一致：每个可写承接方的 Assignment 仍须含 PM 已批准的 **`Working branch`** / **`Branch policy`**；在某一 worktree 内 **不得**擅自 `checkout` 到未授权分支或私自新建分支。
+- **PM 须在 Assignment 中写清**各并发写流的 **检出约定**（例如预期 **`Worktree path`** / 命名规则，或「由承接方按 `using-git-worktrees` 创建并在 Completion Report 回报路径」），避免多代理默认共享同一目录导致互相覆盖、冲突或半写入状态。
+- **同仓、同一 plan、≥2 可写并行轨**：**推荐**在首次向各轨下发实现 Assignment **之前**，先由 PM 与用户确认 **`Branch policy`**，并 **明确 plan 集成分支与各轨 topic 分支的关系**（见下节 **「推荐默认编排：先建 plan 集成分支，再挂各 worktree」**），再为各轨约定 **`git worktree`**。这样 QC 前可把各轨 **自然归并**到同一条 **`HEAD`**，减少「多头分支、无合并靶」导致的误派。
+
+**可不强制新开 worktree** 的情形包括：并发流 **全部为只读**；各写入者针对 **不同 Git 仓库根**；或写入 **串行**（同一时刻仅一个代理持有该仓工作区）。
+
+### 并发 subagent 与同仓工作树（对齐）
+
+当多个可写 subagent **并发**修改 **同一仓库** 时，**不得**共用同一检出目录作为写入 cwd。PM 在分派前应规划 **`git worktree`** 隔离（Superpowers **`using-git-worktrees`**），并在各承接方 Assignment 中写明 **`Working branch`** / **`Branch policy`** 及 **检出路径约定**（或要求回报实际 worktree 路径）。单分支决策权仍仅属 PM；worktree 只解决「目录与工作区隔离」，不替代分支授权。
+
+**同仓、同一 plan、多可写并行轨（推荐）**：在挂齐各轨 `git worktree` **之前**，先与用户确认并写明 **plan 集成分支**（从商定 `<base>` 创建）及各轨 **topic 分支** 如何从该线分出或如何 **merge 回** 该线；QC 前再将待一并验收的提交 **全部归并**到 PM 指定为 QC **`Working branch`** 的那条分支的 **`HEAD`**。分步说明与示例命名边界见下节 **「推荐默认编排：先建 plan 集成分支，再挂各 worktree」**。
+
+**QC / QA 与 feature**：开发常在 **feature 分支的 worktree** 中完成；进入 **QC 三审**与随后的 **QA 验证**时，PM 须在 Assignment 中写明 **`Review cwd` / `Worktree path`**、**`Working branch`**、**`plan_id`**（无 plan 流程时 `N/A` + 不可歧义 **Feature / scope label**）与 **`Review range` / `Diff basis`**；**三份 QC Assignment 与 QA Assignment 中 `plan_id` 与 `Review range` / `Diff basis` 须逐字相同**，保证三票审 **同一 plan/feature 与同一 diff 范围**。
+
+## 多 worktree 并行开发与 QC / QA 的门禁衔接（强制；避免误派）
+
+- **语义区分（必须理解）**：开发阶段可以存在 **多个** `Worktree path`（每条约流一条检出目录）；**一轮**正式 QC 三审及与之 **逐字对齐** 的 QA 验证，在 harness 中仍只对应 **一套** `Review cwd` / `Worktree path` + **`Working branch`** + **`Review range` / `Diff basis`**（三票 QC 与 QA **共用且逐字相同**）。**不要**把「多个开发 worktree」误解成「QC 应轮流进多个目录各审一半」。
+- **推荐默认编排：先建 plan 集成分支，再挂各 worktree（PM；强推荐）**：在 **同仓**、**同一 plan** 且 **≥2 条可写并行轨** 时，按下列顺序编排可最大幅度降低 QC/QA 误用单一开发目录的风险。**此为推荐套路，不是唯一合法 Git 拓扑**；若采用其它拓扑，仍须满足本节下文 **强制**条款（派 QC 前 **单一**待审 `HEAD` + 一套对齐字段）。
+  1. **先起集成分支（再挂 worktree）**：在派发各轨 **实现** Assignment 之前，PM 与用户确认 **`Branch policy`**，并建立 **plan 集成分支**（Assignment 使用 **`Working branch: create <plan-integration-branch> from <base>`** 或等价明确写法；`<base>` 通常为 `origin/main` 或团队既定主线，**不得**未授权假设）。**分支名由 PM 指定**；下文 **`feature/<plan-id>-integrate`**、**`integrate/<plan-id>`** 仅为命名示例，**非强制**。
+  2. **再挂各轨 worktree**：为每条并行轨分配 **独立** `git worktree` + **`Worktree path`**；各轨 **`Working branch`** 一般为 **从集成分支出** 的 topic 分支（`create <topic-i> from <plan-integration-branch>`）或 PM 书面约定的等价结构（例如从同一 `<base>` 出 topic、但 **书面指定** 合并时 **以集成分支为靶**）。**禁止**承接方擅自把未授权功能提交直接堆在 `main`/`master`。
+  3. **进 QC 之前**：将全部 **须同一轮三审覆盖** 的提交 **merge / rebase / cherry-pick**（以 PM 指定的团队方式）**归并**到 **同一条** PM 将作为 QC **`Working branch`** 的分支的 **`HEAD`**（**通常即 plan 集成分支**；若 PM 已将集成分支重命名或快进为最终 `feature/*`，以 Assignment 为准）。**在此**解决冲突；**勿**在 QC Assignment 仍指向「只含部分轨」的旧 `HEAD` 时派三审。
+  4. **QC / QA 的 `Working branch` 与合并主线**：派发 QC 三审与对齐的 QA 时，**`Working branch`** **即为**上一步 **已含全部待审提交** 的那条分支（常见为 plan 集成分支）。**`Review range` / `Diff basis`** 通常相对 **尚未合并 feature 的** 主线参照（例如 `merge-base: origin/main` + `tip: HEAD`），审查的是 **「feature 线 vs 主线」** 的差异；**默认不要求**在 QC **通过前** 已把该分支 merge 进 `main`（除非 **`Branch policy`** 或用户明确约定 trunk 式例外）。
+  5. **本推荐不适用时**：单轨、多仓库、或 plan 已 **拆 scope / 多轮增量三审**（见 `mstar-plan-conventions`）— 仍须 **逐轮**满足 **强制**条款：每轮 QC 对应 **一条**快照、**一套**逐字相同的 `plan_id` + `Review range` / `Diff basis`。
+- **单一待审 Git 快照（派 QC 前置条件）**：若本 plan 下曾有多条 **可写** 并行轨落在 **同一业务仓** 且其成果分布在 **不同分支**、或 **未互相合并进同一条分支的 `HEAD`**，则在派发 **QC 三审**（及同范围的 QA）**之前**，**必须**先在 Git 中完成 **归并**（merge / rebase / 按团队约定的集成方式），使 **全部**待审提交都出现在 **同一条** PM 指定的 **`Working branch`** 的 **`HEAD`** 上；**然后**再填写 **一个** `Review cwd`（可为该分支上新开的只读审查 worktree）与 **一个** 可复现的 **`Review range` / `Diff basis`**。**禁止**仅填写并行轨 **A** 的开发用 `Worktree path` 作为 `Review cwd`，却期望审查覆盖仍只存在于并行轨 **B** 的分支或提交上的变更（在该变更 **未进入** 轨 A 所检出分支的 `HEAD` 时，这在 Git 上不可复现，属 **Assignment 错误**）。
+- **不应合并为一次审时的做法**：若两轨 **有意**保持独立可合并单元（例如两条独立 PR），**不得**共用 **同一套** `plan_id` + **`Review range` / `Diff basis`** 假装「一轮三审覆盖全部」。应 **拆分 scope**：分轮次审查、不同 **`Feature / scope label`**、不同 `plan_id`、或按 `mstar-plan-conventions` 写明的 **显式增量三审** 例外，使每轮 QC 各对应 **一条**分支快照与 **一套**对齐字段。
+- **同分支多目录的例外**：若所有并行轨 **始终**在同一条已授权的 **`Working branch`** 上协作（每流仅目录不同、提交已互相 `pull`/推送收敛），则任一该分支的检出目录在 **更新到含全部提交的 `HEAD`** 后，均可作为 `Review cwd`；**不得**使用仍停留在旧提交的 worktree 路径。
+
+## QC 三审、QA 验证与 feature 检出上下文（强制）
+
+开发在 **feature 分支**上完成（往往在 **独立 worktree** 中实现）后，**QC 审查与 QA 验证针对的都是这份 feature**，而不是 `main` 或任意未对齐的默认 cwd。
+
+- **`@project-manager`** 分派 **QC** 时须在 Assignment 写明与待审实现一致的 **`Working branch`**，并写明 **`Review cwd` / `Worktree path`**：**优先**沿用开发 **Completion Report** 中回报的业务仓 **实现检出路径**（即「该 feature 的 worktree」）**当且仅当**该路径上的检出分支 **`HEAD` 已包含本轮待审的全部提交**（含曾发生在其他并行 worktree、现已归并到该分支的变更）。否则 **必须**改用 **集成完成后的** `Working branch` 与对应检出路径（或按 **`using-git-worktrees`** 在该分支上 **另开** 审查专用目录）。若开发未用 worktree，则写明单一明确的业务仓根路径。若审查需与开发目录 **物理分离** 但仍审 **同一分支**，可指示按 **`using-git-worktrees`** 在 **`Working branch`** 上 **另加** 一个 worktree 专供审查（只读使用业务仓）。**多流并行开发**时的前置归并、**推荐默认编排（plan 集成分支先行）** 与误派禁令见上一小节。
+- **三票审同一功能（强制对齐）**：分派 **QC 三审**时，除上述字段外，**必须**在 **三份 Assignment 中逐字写入相同**的 **`plan_id`** 与 **`Review range` / `Diff basis`**：
+  - **`plan_id`**：与 `{PLAN_DIR}/reports/<plan-id>/` 及主 **Plan Path** 一致；无 `{PLAN_DIR}` 流程时写 **`plan_id: N/A`**，并另给一行 **`Feature / scope label`**（不可歧义，足以与并行其它 feature 区分）。
+  - **`Review range` / `Diff basis`**：明确本次审查所针对的 **diff/提交范围**（例如 `merge-base: origin/main` + `tip: HEAD`；或 `rev-range: <full-40>..<full-40>`；或一句 `equivalent to: git diff <merge-base>...HEAD`，以团队可复现为准）。**三名 reviewer 的 Assignment 间该字段必须完全一致**；**@qa-engineer** 验证同一 feature 时 **复用同一 `plan_id` 与同一 `Review range` / `Diff basis`**。**热修 / QC 单审**路径也须含 **同一组字段**，仅承接方份数为 1。
+- **三审并行**时，三名 reviewer **共用同一组 `Review cwd` / `Worktree path` + `Working branch` + `plan_id` + `Review range` / `Diff basis`**（对业务仓只读分析）；**一般不必**为每位 reviewer 各开一个 worktree，除非宿主或执行环境要求进程级隔离。
+- QC 的 **报告落盘**仍仅限 `{PLAN_DIR}/reports/`；上述约定保证 `git diff`、`git log`、lint 与所读文件与 **待合并 feature** 一致。
+- **`@project-manager`** 分派 **`@qa-engineer`** 做 **本 feature 的验证**（跑测试、复现、可观察取证、或向业务仓提交测试/配置）时，须在 Assignment 中写明 **同一套** **`Review cwd` / `Worktree path`**、**`Working branch`**、**`plan_id`** 与 **`Review range` / `Diff basis`**（与 QC 三审 **逐字相同**；若 QC 已写清，QA **照抄**）。**@qa-engineer** 在执行业务仓命令前须核对当前目录与分支与 Assignment 一致；**Report-only**、且本轮 **不涉及** 业务仓内命令/路径依赖时，若 Assignment 未写 `Review cwd`，须在回报中说明验证所基于的检出或环境，缺失则 `Blocked` 并请 PM 补全。
+- 若 **QA 与同仓其他可写角色并发**提交测试代码，仍须遵守上文「同仓并发写入」的 **worktree** 规则（可为 QA 单开一条写入 worktree，**同一 `Working branch`**，由 PM 在 Assignment 写明）。

package/harness-skills/mstar-harness-core/references/library-docs-protocol.md

@@ -0,0 +1,35 @@
+# Context7 Library Docs Protocol (Shared)
+
+This protocol is shared by all hosts in Morning Star. Host adapter skills should consume this section, not redefine it.
+
+## When to use
+
+- The question is about library/framework/SDK/CLI/cloud API syntax, config options, migration behavior, or version-specific usage.
+- The answer quality depends on current docs rather than model memory.
+
+## When not to use
+
+- Pure refactoring strategy.
+- Writing scripts from scratch without external API dependence.
+- Business logic debugging not tied to third-party docs.
+- Generic programming concepts.
+- PR/code review judgment.
+
+## Single-path policy
+
+Use one path per question. Do not run MCP and CLI in parallel for the same library/question pair.
+
+1. **Primary path: Context7 MCP (if available)**
+   - Read tool schema first.
+   - Query with the user's full question.
+   - Prefer versioned library IDs when version is known.
+2. **Fallback path: ctx7 CLI (only if MCP unavailable/fails)**
+   - `npx ctx7@latest library <name> "<user question>"`
+   - `npx ctx7@latest docs <libraryId> "<user question>"`
+   - Max 3 commands per question.
+
+## Guardrails
+
+- Never include secrets in commands or queries.
+- Switch to fallback only after primary path fails.
+- Report uncertainty when docs retrieval fails on both paths.

package/harness-skills/mstar-harness-core/references/open-harness-principles.md

@@ -0,0 +1,73 @@
+# 开源 Agent Harness 理念（Morning Star）
+
+## 定位
+
+本文归纳从公开 agent harness 实践中提炼的**流程理念**，并已写入 `mstar-harness-core`、`mstar-roles` skill 的 `project-manager` 角色 等，作为本配置的默认行为约定。
+
+## 已内化的原则（执行时必须遵守）
+
+| 理念 | 含义 | 在本仓库的落点 |
+|------|------|----------------|
+| **意图优先于字面** | 先弄清「用户真正要达成什么」，再分类与分派 | `mstar-harness-core` SKILL.md「意图门禁」；PM「第一性原理」与 `clarify` |
+| **先准备再实现** | 访谈式规划、锁范围、再写代码 | Prepare：`specify -> clarify -> plan`；Execute：`plan locked -> tasks -> implement` |
+| **按任务类别选能力与模型** | 视觉/深读/快改/硬逻辑等用不同强项 | `mstar-harness-core` SKILL.md「Task category」；Assignment 字段 **`Task category`**；宿主侧按角色配置 model（如 OpenCode 的 `opencode.json`） |
+| **可验证编辑** | 减少「凭记忆 Patch」导致的漂移与损坏 | `mstar-harness-core` SKILL.md「可验证编辑与上下文纪律」：读后再改、失败则重读 |
+| **持续推进与可核对完成** | 长任务有清单、有关门证据，避免空转 | `mstar-superpowers-align` 的 `verification-before-completion`；PM 对 `tasks`/Phase Gate 的拉回 |
+| **编码行为约束（轻量）** | 降低静默假设、过度设计与无关改动 | `mstar-coding-behavior`：Think Before Coding / Simplicity First / Surgical Changes / Goal-Driven Execution |
+| **并行与边界** | 多线任务不踩同一写归属、不绕过分支门禁；**开发**阶段同仓多可写并发须独立 **`git worktree`**；**QC / QA** 在 **同一检出**（`Review cwd`）与 **同一 `plan_id` + `Review range` / `Diff basis`** 上审查与验证，保证三票同一功能 | `mstar-harness-core` SKILL.md「并行规则」与 `references/branch-and-worktree.md`；`mstar-review-qc`；`mstar-superpowers-align` 的 **`using-git-worktrees`** |
+| **分层上下文（可选）** | 大仓库用目录级 `AGENTS.md` 降噪；根 `AGENTS.md` 维护边界见下文专节 | `mstar-harness-core` SKILL.md「分层上下文」；由业务项目维护者按需添加 |
+| **结构化澄清（按宿主）** | 向用户澄清/抉择时，**有 `question` 类能力则优先**；否则结构化正文；长问兜底 | `mstar-harness-core` SKILL.md「Spec-Driven」下 `clarify`；当前宿主的 `mstar-host` skill；`mstar-roles` skill 的 `project-manager` 角色 |
+
+## 与常见 harness 说法的对照（帮助理解角色分工）
+
+| 常见说法 | 本仓库实体 |
+|----------|------------|
+| 总编排 | `@project-manager` |
+| 规划/访谈 | `@product-manager` / `@architect` + Prepare 阶段 |
+| category 路由 | **`Task category`** + 路由表 + 子代理选择 |
+| 持续推进 / 不半途而废 | Phase Gate + Todo/`tasks` + 验证门禁 |
+| 行级哈希锚定编辑 | 本仓库以 **读后再改 + 小步 Patch** 纪律落实（见 `mstar-harness-core`） |
+
+## 项目根 `AGENTS.md` 写什么、不写什么（建议）
+
+业务仓库根目录（或分层中的目录级）`AGENTS.md` 适合承载：**长期有效的规则、技术栈约束、工作流门禁**；不宜承载易变状态或已另有 SSOT 的内容，以免双轨漂移。
+
+### 宜放入
+
+- 技术栈与架构边界（变更时更新）
+- 开发与验证命令、目录布局、命名约定
+- 与 harness 对齐的**持久**规则（分支策略引用、**`{HARNESS_DIR}`** / **`{PLAN_DIR}`** 路径说明等）
+
+### 不宜放入（应指向专门落点）
+
+| 内容 | 更合适的落点 |
+|------|----------------|
+| 详细计划状态、阻塞列表、当前 sprint 叙述 | `{HARNESS_DIR}/status.json`（及可选 `{HARNESS_DIR}/notes.json` 程序时间线） |
+| 规格正文、枚举定义、API 契约全文 | 项目约定的冻结规格目录（如 `docs/spec/`、`.agents/designs/...`，名称自定） |
+| 某一 plan 的评审稿、gap 分析、实施笔记 | `{HARNESS_DIR}/knowledge/`（并维护索引 README，见 `mstar-plan-conventions`） |
+| 临时 workaround、仅本轮有效的结论 | 主 plan 文件或 knowledge，收口后提炼再考虑进 `AGENTS.md` |
+
+### 更新前自检（避免污染单一权威）
+
+- 是否为**持久规则**，而非一两次性的当前状态？
+- 是否适用于**整个项目**，而非单个 plan？
+- 是否与冻结规格**重复**？若重复，应改为「引用路径」而非粘贴全文。
+- 是否其实属于 **`{HARNESS_DIR}/status.json`**（状态、门禁摘要、时间线）？
+
+### 典型信息源层级（模板）
+
+项目可自定义目录名；逻辑顺序常为：
+
+1. **冻结规格 / 设计权威**（版本化、显式变更流程）
+2. **根 `AGENTS.md`** — 项目级规则与约定
+3. **`{HARNESS_DIR}/status.json`** — 当前执行状态与 open residual 的 SSOT
+4. **`{HARNESS_DIR}/knowledge/`** — 支撑实施的上下文文档
+
+若 `AGENTS.md` 与冻结规格冲突，**以规格为准**，并修订 `AGENTS.md` 对齐。细节分工与可到达性要求见 `mstar-plan-conventions`。
+
+## 延伸阅读
+
+- 按能力选配 MCP/skills：当前宿主的 `mstar-host` skill 的「按能力选配」章节
+- Superpowers 与门禁对齐：`mstar-superpowers-align`
+- 库文档检索共享协议：`mstar-harness-core` `references/library-docs-protocol.md`
+- 跨角色编码行为准则（轻量、可复用）：`mstar-coding-behavior`

package/harness-skills/mstar-harness-core/references/phase-gate-playbook.md

@@ -0,0 +1,87 @@
+# Phase Gate Playbook（Morning Star）
+
+本手册将 `specify -> clarify -> plan -> tasks -> implement` 变成可执行动作，供 `@project-manager`、开发与 QA 在日常交付中快速对齐。
+
+## 适用范围
+
+- 非热修（non-hotfix）任务默认强制执行全链路门禁。
+- 热修可走压缩路径，但必须补事后 `clarify/RCA` 记录。
+
+## 两阶段门禁
+
+### A. Prepare
+
+顺序：`specify -> clarify -> plan`
+
+- `specify`
+  - 目标：定义问题、范围、验收。
+  - 最小产物：问题陈述、目标用户价值、非目标、DoD 草案。
+- `clarify`
+  - 目标：收敛会影响方案或验收的歧义。
+  - 最小产物：歧义清单 + 结论；若未收敛则 `blocked`。
+  - **意图**：区分字面请求与真实目标；手段/目标混淆须在此收敛（见本 skill `SKILL.md` Intent gate）。
+  - **结构化澄清**：与用户核对歧义或决策时，`@project-manager`（及直接与用户对话的角色）在**宿主支持**时优先用 `question` 类能力拉齐输入；否则用等价结构化正文。宿主差异细则见当前宿主的 `mstar-host` skill。
+- `plan`
+  - 目标：给出可执行技术方案与风险控制。
+  - 最小产物：方案、模块边界/接口契约、风险与回滚、验证计划。
+  - **准入**：能书面写出真实目标、成功判据、非目标后再锁 plan（同 `SKILL.md`）。
+
+### B. Execute
+
+顺序：`plan locked -> tasks -> implement`
+
+- `plan locked`
+  - 目标：冻结本轮基线，防止边做边漂移。
+  - 最小动作：在 plan 或 notes 记录当前锁定版本（日期或 hash）。
+- `tasks`
+  - 目标：把 plan 拆成可执行任务与依赖顺序。
+  - 最小产物：任务列表、并行标记、完成判据、映射到验收标准。
+  - **PM**：若并行标记对应「多轨同时 implement」，在对外 **Status Update** 与实现 Assignment 的 **`Superpowers`** 中写入 **`dispatching-parallel-agents`**（或同义短语）；同仓多可写并发时叠 **`using-git-worktrees`**（见 `mstar-superpowers-align`）。
+- `implement`
+  - 目标：按任务执行并提交证据，进入审查。
+  - 最小产物：实现 diff、自检证据、回报与 handoff。
+  - **行为准则**：执行中遵循 `mstar-coding-behavior`（不静默假设、优先简单方案、只做与任务直接相关的手术式改动、按 `Step -> verify` 推进）。
+  - **编辑纪律**：改文件前以磁盘为准重读；Patch 失败则重读、缩小步长，禁止盲试（见 `SKILL.md`「可验证编辑与上下文纪律」）。
+  - **知识库**：若项目启用 `{HARNESS_DIR}/knowledge/` 且当前计划在 `{HARNESS_DIR}/status.json` 的 `plans[].metadata` 中登记了 `primary_spec` / `spec_refs`，**开工前**须阅读并在回报中说明已对齐；规则见 `mstar-plan-conventions`「`{HARNESS_DIR}/knowledge/` 开发过程知识库」。
+
+## 角色职责
+
+- `@project-manager`
+  - 负责门禁判定与 Assignment 中的 `Phase Gate Checklist`。
+  - 在 `Status Update` 汇报当前 gate 状态。
+- 开发角色（`@frontend-dev` / `@fullstack-dev` / `@fullstack-dev-2`）
+  - 仅在 Execute gate 放行后开始实现。
+  - 发现新约束时先回报并请求回写 plan。
+- `@qa-engineer`
+  - 在 `InReview` 阶段验证实现与验收映射是否一致。
+
+## Plan 目录与审查报告（启用 `{PLAN_DIR}` 时）
+
+- 进入 `InReview` 后，QC 书面产出按 `mstar-plan-conventions` 落入 `{PLAN_DIR}/reports/<plan-id>/`（如 `*-qc1.md` … `*-qc-consolidated.md`）；勿与主 plan 文件混写为「唯一草稿」后又删，保留可追溯历史。**多 batch 的同一 plan**：完整 QC 三审**默认在整 plan dev 完成后一次**（非每 batch），见 `mstar-plan-conventions`「QC 三审触发时机」。
+- 非阻断项与后续技术债：PM 汇总后写入 `{HARNESS_DIR}/status.json` 根级 `residual_findings[<plan-id>]`（**open**，与 `plans` 平级；canonical 见 `mstar-plan-conventions` **SKILL.md** 开篇）；关闭后迁入 `{HARNESS_DIR}/archived/residuals/<plan-id>.json`，与 `mstar-review-qc` 一致。每条 **`severity`** 遵守 `mstar-plan-conventions`「Residual findings：severity（SSOT，机器字段）」。
+
+## 快速判定（PM）
+
+1. `specify` 是否完成？
+2. `clarify` 是否完成（高影响歧义是否收敛）？
+3. 意图门禁是否满足（真实目标 / 成功判据 / 非目标已写明）？
+4. `plan` 是否完成并可引用？
+5. `tasks` 是否完成？
+6. Assignment 是否含 **`Task category`**（实现类任务）并与 Owner 一致？
+7. 若中途出现 plan drift，是否先回写再继续？
+8. 实现说明中是否体现"最小解法 + 手术式改动 + 可验证检查"？
+
+任一项为「否」时，`Gate decision` 必须是 `blocked`。
+
+## Hotfix 例外
+
+- 允许路径：`specify(min) -> plan(min) -> implement`
+- 必须补记：
+  - 事后 `clarify/RCA`
+  - 触发条件、影响范围、修复与回滚摘要
+
+## 最小证据要求
+
+- Prepare 阶段证据：问题定义、歧义结论、plan 链接。
+- Execute 阶段证据：tasks 清单、实现自检、审查/验证证据。
+- 结论证据：不得仅写"done"，必须可复核（命令、输出、截图或复现步骤）。

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

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