@mstar-harness/opencode 0.2.0 → 0.3.1

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

@@ -37,8 +37,8 @@ description: Morning Star (启明星) harness 的**强制全局入口** ——
 
 ## 加载约定（强制）
 
-- **`@project-manager`**：开轮次前**必须**先 Read **`mstar-harness-core`**（含本轮将用到的 `references/`），再按任务 Read **`skills/`** 下与本回合相关的 **`mstar-*` 专题 skill**（典型：`mstar-plan-conventions`、`mstar-review-qc`、`mstar-coding-behavior`、`mstar-superpowers-align`、`mstar-roles`）。**PM 路由 / Routing Eval 回归**为 **Cursor 维护流程**专用（`.cursor/skills/mstar-routing-eval/`），**不作为** OpenCode 等宿主上的运行时必读。编排动作与 Assignment 须与本 skill 一致。
-- **实现/审查/QA/运维角色**：接到 Assignment 后、动手（写盘或第一次 `git commit`）**之前**，**必须**先 Read **本 skill**（含相关 `references/`），再 Read 角色对应的其它 `mstar-*` skills（各角色必读清单见 `mstar-roles` skill 的 role profiles）。
+- **`@project-manager`**：开轮次前**必须**先 Read **`mstar-harness-core`**（含本轮将用到的 `references/`），再按任务 Read **`skills/`** 下与本回合相关的 **`mstar-*` 专题 skill**（典型：`mstar-plan-conventions`、`mstar-review-qc`、`mstar-superpowers-align`、`mstar-roles`）。**不要求** PM Read `mstar-coding-behavior`（该 skill 面向实现 / 审查 / QA / 运维等承接方）。**PM 路由 / Routing Eval 回归**为 **Cursor 维护流程**专用（`.cursor/skills/mstar-routing-eval/`），**不作为** OpenCode 等宿主上的运行时必读。编排动作与 Assignment 须与本 skill 一致。
+- **实现/审查/QA/运维角色**：接到 Assignment 后、动手（写盘或第一次 `git commit`）**之前**，**必须**先 Read **本 skill**（含相关 `references/`），再 Read **`mstar-coding-behavior`** 与角色对应的其它 `mstar-*` skills（各角色必读清单见 `mstar-roles` skill 的 role profiles）。
 - 本 skill 与 `references/` 都是**可复核规则**；不得在回报中声称已遵循而实际未读。
 
 ## 状态机
@@ -232,6 +232,12 @@ description: Morning Star (启明星) harness 的**强制全局入口** ——
 - 省略 `Task category` 导致角色/模型选择错配（除非极简 explore-only 且路由表已唯一）。
 - **承接方递归误派**：在 leaf executor 会话里再 invoke 与自身 `Execute as` 同名的 `subagent_type`，或把 Assignment 中的 **Handoff / QA note / Completion Report 角色列表 / 多计划或多轨并行类编排措辞** 当作 invoke 指令；细则见上节「承接方反递归红线」。
 
+## 可选插件：OpenViking Memory（OpenCode）
+
+**适用条件**：当前会话工具列表中存在 **`memsearch`**（通常与同插件的 `memread` / `membrowse` / `memcommit` 一起出现）时，表示 OpenViking Memory 已接入。
+
+**规则 SSOT**：与 Morning Star harness 的对齐方式、禁止事项与工具用法见 **`references/openviking-memory-plugin.md`**。**未**出现上述工具时，不必 Read 该 reference；不得把记忆检索当作可绕过门禁或许可证。
+
 ## Morning Star Skill 索引
 
 下列 skills 承载 harness 全部执行向规则。角色运行时先按本 skill 进入，再按角色职责按需加载对应 skill。
@@ -282,3 +288,4 @@ description: Morning Star (启明星) harness 的**强制全局入口** ——
 - `references/branch-and-worktree.md` — 功能分支门禁 / 分支协作契约 / 同仓并发 worktree / 多 worktree 并行开发与 QC-QA 衔接 / plan 集成分支推荐编排 / QC-QA 检出上下文对齐。
 - `references/open-harness-principles.md` — 意图门禁、Task category、可验证编辑、长任务纪律、分层 `AGENTS.md`、项目根 `AGENTS.md` 维护边界。
 - `references/library-docs-protocol.md` — Context7 文档检索共享协议（MCP 优先、CLI 兜底、禁双跑）。
+- `references/openviking-memory-plugin.md` — OpenViking Memory 工具（`memsearch` 等）与 harness 的对齐；**仅当**会话中存在 `memsearch` 工具时 Read。

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

@@ -108,7 +108,7 @@
 
 - **语义区分（必须理解）**：开发阶段可以存在 **多个** `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>`** 仅为命名示例，**非强制**。
+  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>`** 仅为命名示例，**非强制**。**多 `plan_id` 同源一条 `primary_spec`（Spec 文档）时**：该集成分支在计划语义上即 **Spec 集成分支**；各 Plan 的 feature 线 merge 回此线，**全部 Plans 完成后** 合入默认保护分支须 **走 PR**（见 `mstar-plan-conventions` SKILL.md「Spec 文档驱动的分支模型」）。
   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 式例外）。

package/harness-skills/mstar-harness-core/references/openviking-memory-plugin.md

@@ -0,0 +1,45 @@
+# OpenViking Memory Plugin (OpenCode, optional)
+
+This reference applies **only** when the current agent session exposes OpenViking tools (detection: **`memsearch`** is available in the tool list). It documents harness-aligned usage; implementation details follow the OpenCode plugin (for example `openviking-memory.ts` beside `openviking-config.json` under the user’s OpenCode plugins directory).
+
+## What the plugin provides
+
+Typical tools (names match the reference plugin):
+
+| Tool | Purpose |
+| --- | --- |
+| `memsearch` | Unified semantic search over memories, resources, and skills (`mode`: `auto` / `fast` / `deep`). |
+| `memread` | Read a single item by `viking://` URI with progressive depth (`abstract` / `overview` / `read` / `auto`). |
+| `membrowse` | List / tree / stat views under a `viking://` prefix. |
+| `memcommit` | Trigger session commit / memory extraction for the mapped OpenViking session (optional mid-session). |
+
+**URI rule**: `memread` and `membrowse` require URIs starting with `viking://` (validated by the plugin).
+
+**Service dependency**: The plugin calls an OpenViking HTTP API (default `http://localhost:1933` unless overridden). If tools error with connection or health failures, treat memory as **unavailable** for this turn; do not block core harness gates on memory.
+
+**Auto features** (when enabled in plugin config): conversation capture, periodic auto-commit, and optional **auto-recall** injection (`<relevant-memories>` appended to the latest user message). Recall is best-effort and must not replace explicit search when you need traceable evidence.
+
+## Harness alignment (mandatory)
+
+1. **Subordinate to SSOT**: `mstar-harness-core` state machine, phase gates, branch/worktree rules, and QC/QA alignment **always** override any suggestion retrieved from memory. If memory conflicts with plan, `status.json`, or Assignment, **follow the written artifacts** and record the conflict in notes or Completion Report.
+
+2. **No secrets in memory tools**: Do not paste API keys, tokens, or private credentials into `memsearch` queries or stored memories. Redact before commit-style operations.
+
+3. **Evidence for claims**: Memory hits are **hints**, not proof. For library/API facts, still follow `references/library-docs-protocol.md` (Context7 MCP / ctx7) when the question depends on current docs.
+
+4. **When to call `memsearch`**: Prefer early in a **new** task or thread when user preferences, prior decisions, or plan IDs may exist in OpenViking; after major clarify/plan changes, a fresh search can reduce stale context.
+
+5. **`memread` after `memsearch`**: Use URIs from search results; escalate depth (`overview` → `read`) only when needed to avoid token burn.
+
+6. **`memcommit`**: Use for explicit “persist now” or mid-session extraction when the user asks or when wrapping a milestone. Do **not** spam commits after every trivial edit; the plugin may already run **auto-commit** on an interval—respect that and user policy.
+
+7. **Parallel / multi-agent**: Memory tools do **not** replace PM dispatch, worktree isolation, or QC tri-review invokes. They do not authorize subagent recursion.
+
+## When **not** to rely on this reference
+
+- `memsearch` (and sibling tools) are **absent** → skip this file; no OpenViking rules apply.
+- Non-OpenCode hosts (unless they expose the same tool names with the same semantics) → ignore.
+
+## Configuration (user-owned)
+
+Plugin reads `openviking-config.json` next to the plugin file and env vars such as `OPENVIKING_API_KEY`, `OPENVIKING_ACCOUNT`, `OPENVIKING_USER`. Agents must **not** edit user global config without explicit user consent (see `mstar-harness-core` guardrails).

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

@@ -1,6 +1,6 @@
 ---
 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 目录。
+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）、**Spec 集成分支 + 多 Plan 实现分支** 的 Git 对齐与 **Spec 完成后须经 PR 合入 main** 门禁。任何角色在读写 .agents/、创建/更新 plan 文件、登记 residual finding、QC/QA 报告入库、Done 收口、写工期预估时必读；`@project-manager` 编排任一含 plan 的任务前必读；实现角色开工前须读本 skill 以对齐 metadata.primary_spec/spec_refs 与 knowledge 目录。
 ---
 
 ## Load order（必读顺序）
@@ -107,6 +107,38 @@ description: Morning Star (启明星) harness 的计划目录约定 —— {HARN
    - **仅本机私密**：若必须 ignore 整个 **`{HARNESS_DIR}`**，则按上文「可到达性」约束已提交文档；敏感片段另用密钥或私密渠道管理。
 10. 如果项目已有 **`.plans/`** 或 **`plans/`** 目录（遗留同目录布局），**不要再创建** **`.agents/`**，直接使用已有目录作为 **`{HARNESS_DIR} = {PLAN_DIR}`**，并视需要补建 **`reports/`**、**`residuals/`**、**`knowledge/`**、**`archived/residuals/`**、可选 **`notes.json`** 与 `metadata` 结构。
 
+## Spec 文档驱动的分支模型（多 Plan 归属同一 Spec）
+
+当 **`metadata.primary_spec`**（及可选 **`spec_refs`**）指向**单一规格主线**，且 PM 将工作拆成 **多个 `plan_id`** 并行或串行交付时，业务仓库的 Git 拓扑建议按下述对齐，避免「实现分支直接打 main」与「多 Plan 无集成靶」两类漂移。**同仓 worktree、QC 前归并到单一 `HEAD` 等强制条款**仍以 **`mstar-harness-core`** `references/branch-and-worktree.md` 为准；本节只补充 **Spec ↔ 分支** 的命名级契约。
+
+### 分支角色
+
+| 概念 | 含义 |
+|------|------|
+| **Spec 文档** | 该次交付冻结或主规格（常为 `{SPECS_DIR}` / `knowledge/` 下路径；与 `primary_spec` 对齐）。 |
+| **Spec 集成分支** | **一条**与「该 Spec 所覆盖的全部 Plans」对应的 **集成线**：各 Plan 实现成果 **merge 回** 此分支后，才视为该 Spec 在代码侧已集成。 |
+| **Plan 实现分支** | **每个 `plan_id`** 一条（或 PM 书面拆分的子轨）；**仅**承载该 Plan 范围内的提交与 QC/QA 前归并。 |
+
+### 工作流（默认推荐）
+
+1. **开线**：由 **`@project-manager`** 与用户确认后，建立 **Spec 集成分支**（Assignment 写明 `Working branch: create <spec-integration-branch> from <base>` 或等价；`<base>` 见 `branch-and-worktree.md`，**禁止**未授权默认）。
+2. **拆 Plan**：每个从该 Spec 拆出的 plan 使用 **各自的 Plan 实现分支**（通常 `create <plan-feature-branch> from <spec-integration-branch>` 或 PM 规定的等价拓扑）；**实现 / QA / 运维等可写角色**在本 Plan 周期内 **只操作 Assignment 写明的该 Plan 分支**（及 PM 授权的 worktree 检出），**不得**擅自把未授权提交直接堆到默认保护分支。
+3. **Plan 收口**：该 Plan 完成 **QC 三审 + QA** 等 harness 要求后，将其变更 **merge（或团队书面约定的 rebase/cherry-pick）回 Spec 集成分支**；**不是**在「仅完成单个 Plan」时默认直接 merge 进 `main`/`master`，除非 Assignment 含显式 **`Branch policy`** 例外。
+4. **与 `mstar-harness-core` 的「plan 集成分支」关系**：**同仓、同一 plan、多并行轨**时，该 skill 推荐的 **plan 集成分支** 在「多 Plan、同源 Spec」场景下 **即** 本条所述 **Spec 集成分支**；各 Plan 的 topic 线 **merge 靶** 优先为 **Spec 集成分支**，而非彼此随意交叉除非 PM 书面约定。
+
+### 合入默认保护分支（main）：必须经 PR
+
+当 **归属该 Spec 的全部 Plans** 已在计划状态上完成（且代码变更已按团队流程 **汇总到 Spec 集成分支**）时：
+
+- **禁止**将 Spec 集成分支 **直接本地 merge / fast-forward push** 到 **`main`/`master`**（或项目约定的其它默认保护分支）作为**常规完成路径**。
+- **必须**通过 **Pull Request（或宿主平台等价的受控合入流程）** 将 Spec 集成分支合入默认分支，以满足 **审查、CI、权限与审计** 等团队门禁。
+
+**窄例外**（须 **Assignment 显式** **`Branch policy: direct on <branch> — <reason>`**，与 `mstar-harness-core` 一致）：例如已批准的热修、或用户与团队书面采用的无 PR 流程。**不得**由 agent 自行认定「可以跳过 PR」。
+
+### 登记建议
+
+在 **`{HARNESS_DIR}/status.json`** 的 **`plans[].metadata`**（或根级 **`metadata.versioning`** 等团队约定节）中记录 **`spec_integration_branch`**、各 plan 的 **`working_branch`**，以及 **`merge_target`**（对 Plan 实现分支通常为 **Spec 集成分支名**，而非 `main`）。字段表见 `references/status-and-residuals.md`。
+
 ## Harness 初始化蓝图（含 `AGENTS.md` 分层策略）
 
 当仓库从 0 到 1 启用 harness，建议按下面顺序初始化，避免后续出现规则散落与双轨 SSOT：
@@ -223,7 +255,7 @@ Assignment 模板中的 **`Parallelism`** 行应与上表 **`Parallelism`** / **
 
 ## 各角色与 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`**。
+- **`@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`**（若本轮依赖知识库）。**多 Plan 归属同一 Spec 时**：按上文 **「Spec 文档驱动的分支模型」** 声明 **Spec 集成分支**、各 **Plan 实现分支** 与 **merge 靶**；在 `status.json` 登记 **`spec_integration_branch` / `merge_target`**（见 `references/status-and-residuals.md`）；**全部 Plans 完成后** 合入 `main`/`master` **走 PR**，不得默认直接 merge。**维护 `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 收口。
@@ -233,6 +265,7 @@ Assignment 模板中的 **`Parallelism`** 行应与上表 **`Parallelism`** / **
 
 ## References
 
+- 本 SKILL **「Spec 文档驱动的分支模型（多 Plan 归属同一 Spec）」** — Spec 集成分支、Plan 实现分支、merge 回集成线、**全部完成后经 PR 合入 main**（与 `mstar-harness-core` `references/branch-and-worktree.md` 并用）。
 - `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 落盘宿主权限。

package/harness-skills/mstar-plan-conventions/references/plan-files-and-reports.md

@@ -36,7 +36,7 @@
 - **batch 之间**：依赖实现方 **`verification-before-completion`**、主 plan 任务勾选与 PM 协调；需要书面中间意见时，用对话、主 plan 批注或**非三审**的定向检查（如单审、架构 review），**不**默认等同「又一轮完整三审」。
 - **Request Changes 后复验**：若须再跑一轮完整三审，使用**新文件名**落盘，避免覆盖首轮报告，例如 `<plan-id>-qc1-rev2.md` … `<plan-id>-qc3-rev2.md`（或团队约定的 `wave2-` 前缀）；`@project-manager` 在 `QC Consolidated Decision` 中写明**当前以哪一波次为准**。
 - **显式例外**：仅当用户与 PM 书面同意**中间门禁**时，在 Assignment 写清 **`QC gate: incremental — <scope>`**（或等价），并仍须保证该次三审的 **`plan_id` + `Review range` / `Diff basis`** 三份一致；**优先**用子范围专用标签或子目录，避免与「整 plan 终局」那套 `-qc*.md` 混名。
-- **同仓多 worktree 并行 dev**：**推荐**在排各 batch / 各轨 worktree 前确立 **plan 集成分支** 与各轨 topic 线及 **merge 靶**（见 `mstar-harness-core` `references/branch-and-worktree.md` **「推荐默认编排：先建 plan 集成分支，再挂各 worktree」**）。终局（或增量）三审派单前，PM 仍须满足 **单一待审 `Working branch` / `HEAD`** 或已按上条 **拆 scope**；**不得**假设「整 plan 一次三审」可只靠某一个开发 worktree 路径覆盖未合并的其他并行轨。
+- **同仓多 worktree 并行 dev**：**推荐**在排各 batch / 各轨 worktree 前确立 **plan 集成分支** 与各轨 topic 线及 **merge 靶**（见 `mstar-harness-core` `references/branch-and-worktree.md` **「推荐默认编排：先建 plan 集成分支，再挂各 worktree」**）。**多 `plan_id` 同属一条 `primary_spec`（Spec 文档）时**：该「集成分支」在计划语义上即 **Spec 集成分支**；各 Plan 的 topic 分支 **merge 回 Spec 集成分支**，**全部 Plans 完成后** 合入 `main`/`master` **须走 PR**，见 `mstar-plan-conventions` SKILL.md **「Spec 文档驱动的分支模型」**。终局（或增量）三审派单前，PM 仍须满足 **单一待审 `Working branch` / `HEAD`** 或已按上条 **拆 scope**；**不得**假设「整 plan 一次三审」可只靠某一个开发 worktree 路径覆盖未合并的其他并行轨。
 
 ### 多 `plan_id` 同时 `InReview`（PM 编排）
 

package/harness-skills/mstar-plan-conventions/references/status-and-residuals.md

@@ -116,7 +116,8 @@ QC 报告模板见 `mstar-review-qc`。把 finding 登记进根级 `**residual_f
 | 键                                 | 类型                        | 用途                                                                                                                                                 |
 | --------------------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `working_branch`                  | string                    | 本 plan 实现所用分支名，与 Assignment `**Working branch`** 对齐（SSOT）                                                                                          |
-| `merge_target`                    | string                    | 预期合并目标分支（如 `main`）；默认分支以项目约定为准                                                                                                                     |
+| `spec_integration_branch`         | string                    | （多 Plan 同源 **Spec** 时推荐）该 Spec 对应的 **集成分支** 名；各 Plan 实现分支收口时应 merge 回此线，而非默认直接进 `main`（见 `mstar-plan-conventions` SKILL.md「Spec 文档驱动的分支模型」） |
+| `merge_target`                    | string                    | 本 plan 成果 **下一跳** 预期合并到的分支：多 Plan + Spec 模型下 **通常为 `spec_integration_branch`**；最终进 `main` 仍走 **PR**（同 skill）。单 plan / 无 Spec 集成线时可为 `main` 或团队约定名 |
 | `branch_policy`                   | string                    | 与 `mstar-harness-core` 一致的一行策略说明（如 `direct on main — <reason>` 或 `create feature/x from main`）                                                     |
 | `phase`                           | string                    | 程序/路线图阶段标签（如 `Phase 0`、`v1.0`）                                                                                                                     |
 | `priority`                        | `high` | `medium` | `low` | PM 编排优先级                                                                                                                                           |

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

@@ -1,30 +1,24 @@
 ---
 name: mstar-roles
-description: Morning Star (启明星) 的角色提示词总线。把 `agents/*.md` 的正文完全 skill 化：所有角色的完整行为定义都在 `references/`，`agents/*.md` 只保留 frontmatter 与 role 参数绑定。任何一个 Morning Star 角色（`project-manager` / `product-manager` / `architect` / `fullstack-dev` / `fullstack-dev-2` / `frontend-dev` / `qa-engineer` / `qc-specialist*` / `ops-engineer` / `writing-specialist` / `prompt-engineer`）开工前，都先加载本 skill，再按角色的 `Role parameters` 查参数表并 Read 对应 `references/*.md`。重复角色（`fullstack-dev` 与 `fullstack-dev-2`、`qc-specialist*`）共享同一 reference，参数不同行为不同，绝不复制多份正文。
+description: Morning Star role prompt hub. This skill is the single entry for role-specific behavior text: `agents/*.md` remain lightweight shells (frontmatter + role parameters), while full role behavior lives in `references/*.md`. Always load this skill for any Morning Star role (`project-manager`, `product-manager`, `architect`, `fullstack-dev`, `fullstack-dev-2`, `frontend-dev`, `qa-engineer`, `qc-specialist*`, `ops-engineer`, `writing-specialist`, `prompt-engineer`) before execution.
 ---
 
-## Load order（必读顺序）
+## Load Order (Required)
 
-**在同一会话或任务中首次经本 skill 承担 Morning Star 角色时：必须先 Read `mstar-harness-core` skill（SKILL.md，以及本任务将涉及的 `mstar-harness-core/references/`）。** 本 skill 只提供 **角色正文与参数表**；状态机、门禁、路由与 QC-QA 对齐以 **`mstar-harness-core`** 为准。冲突时 **以 `mstar-harness-core` 为准**。
+When a Morning Star role starts work in a session:
 
-**摘要**：`mstar-harness-core` — 全局 SSOT；`mstar-roles` — `agents/*.md` → `references/<role>.md` 的单一正文入口。
+1. Read `mstar-harness-core` first (SKILL.md + task-relevant references).
+2. Read this `mstar-roles` skill.
+3. Resolve role mapping and parameter table below.
+4. Read the corresponding `references/<role>.md` file.
+5. Expand placeholders from role parameters before execution.
 
-# Morning Star Roles Hub
-
-本 skill 是 Morning Star 的 **角色提示词单一入口**。`agents/*.md` 仅承担 frontmatter 与参数绑定；角色正文权威在本目录 `references/`。
-
-## 使用顺序（每次角色接任务时）
-
-1. 读取当前 `agents/<role>.md` 的 frontmatter 与正文中的 `Role reference` / `Role parameters`。
-2. **Read `mstar-harness-core` skill**（本会话尚未加载 harness 核心时**必须先完成**；含本轮任务相关的 `references/`）。
-3. 读取本 SKILL.md，把下面的 **Skill dependencies** 与 **参数表** 解析到上下文。
-4. Read 对应的 `references/<file>.md`；把正文中的 `{placeholder}` 用你的 `Role parameters` 原地替换。
-5. 若 agent 壳层与 reference 冲突，以 **reference** 为准（壳层只定 permission / tools / 身份与参数）。
+If any conflict appears, `mstar-harness-core` remains the authoritative source for lifecycle, gates, routing, and invariants.
 
 ## 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` | — |
@@ -39,45 +33,43 @@ description: Morning Star (启明星) 的角色提示词总线。把 `agents/*.m
 | `writing-specialist` | `references/writing-specialist.md` | — |
 | `prompt-engineer` | `references/prompt-engineer.md` | — |
 
-## Skill dependencies（所有角色默认适用）
-
-所有角色在开工前都应把以下 skills 视为 **已加载依赖**，按需 Read 对应 SKILL.md 与 `references/`。**`mstar-harness-core` 已在「使用顺序」第 2 步作为全局前置**；下表中其余 skill 按任务阶段 Read。具体哪一条在哪个阶段被用到，由各 reference 自己说明。
+## Shared Skill Dependencies
 
-| 依赖 skill | 当你的任务涉及… |
-|---|---|
-| `mstar-harness-core` | 状态机、Spec-Driven 双阶段门禁、Task category、分支 / worktree、QC-QA 检出对齐、调度防串扰 |
-| `mstar-plan-conventions` | `{HARNESS_DIR}` / `{PLAN_DIR}` 发现与初始化、`status.json` SSOT、residual findings、knowledge/ 布局、工期预估 |
-| `mstar-review-qc` | 工作流、审查清单、报告模板、门禁规则（三审角色必依赖，其它角色读懂门禁即可） |
-| `mstar-coding-behavior` | Think Before Coding / Simplicity First / Surgical Changes / Goal-Driven（所有实现、审查、重构任务） |
-| `mstar-superpowers-align` | Morning Star × Superpowers 对齐与消解；`dispatching-parallel-agents` / `using-git-worktrees` 叠用约束 |
-| 当前宿主的 `mstar-host` skill | 宿主能力差异（`question` 工具、subagent 调度、Task 并行等）；由各宿主自行提供 |
+Treat these as baseline dependencies **where the role touches implementation, review, verification, or ops execution** (see `mstar-harness-core` load contract).
 
-> **原则**：共享 skill 按名字引用（例：`mstar-harness-core` skill），**不写绝对路径**；宿主差异只用“当前宿主的 `mstar-host` skill”指代，避免把 Cursor/OpenCode 的专属路径塞进共享角色正文。
+| Skill | Use when task involves |
+| --- | --- |
+| `mstar-harness-core` | State machine, phase gates, task category, branch/worktree policy, dispatch anti-recursion |
+| `mstar-plan-conventions` | `{HARNESS_DIR}` / `{PLAN_DIR}`, `status.json`, residual lifecycle, plan metadata |
+| `mstar-review-qc` | QC workflow, review template, verdict rules, high-risk checks |
+| `mstar-coding-behavior` | Think-before-coding, simplicity, surgical changes, goal-driven execution (**not** required for `project-manager` orchestration-only work) |
+| `mstar-superpowers-align` | Superpowers alignment, dispatching/worktree constraints, delegation compatibility |
+| `mstar-host-opencode` / `mstar-host-cursor` | Host-specific behavior and capabilities (match the active host) |
 
-## 参数表（SSOT）
+Use skill names (not absolute filesystem paths) in role references.
 
-### Dev track（`fullstack-dev` 家族）
+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.
 
-| `role_id` | `track` | 语义 |
-|---|---|---|
-| `fullstack-dev` | `primary` | 后端主导的主实现轨；Hotfix / 单流小改的默认承接方 |
-| `fullstack-dev-2` | `parallel_secondary` | 第二实现轨；与 `fullstack-dev` 并行时承接独立模块 / API / 页面岛 |
+## Parameter Table (SSOT)
 
-说明：`fullstack-dev-shared.md` 中出现的 `{role_id}` / `{track}` 由 agent 的 `Role parameters` 决定；行为共享，"我是哪一轨"只影响边界协调与避免重叠。
+### Dev track (`fullstack-dev` family)
 
-### QC reviewer（`qc-specialist*` 家族）
+| role_id | track | Meaning |
+| --- | --- | --- |
+| `fullstack-dev` | `primary` | Backend-led primary implementation track |
+| `fullstack-dev-2` | `parallel_secondary` | Second implementation track for parallel independent modules |
 
-| `role_id` | `reviewer_index` | `focus` | `report_suffix` |
-|---|---|---|---|
-| `qc-specialist` | `1` | 架构一致性、可维护性、长期演进风险（模块边界、抽象层次、依赖方向、可扩展性） | `qc1` |
-| `qc-specialist-2` | `2` | 安全与正确性（输入校验、鉴权边界、敏感数据处理、异常路径、状态一致性） | `qc2` |
-| `qc-specialist-3` | `3` | 性能与可靠性（复杂度、热点路径、资源释放、并发风险、退化风险） | `qc3` |
+### QC reviewer (`qc-specialist*` family)
 
-说明：`qc-specialist-shared.md` 中的 `{reviewer_index}` / `{focus}` / `{report_suffix}` / `{role_id}` 从此表按 agent 的 `Role parameters` 查表展开。Completion Report 的 **Agent** 行、报告文件名、commit message 都引用这些参数。
+| role_id | reviewer_index | focus | report_suffix |
+| --- | --- | --- | --- |
+| `qc-specialist` | `1` | Architecture coherence and maintainability risk | `qc1` |
+| `qc-specialist-2` | `2` | Security and correctness risk | `qc2` |
+| `qc-specialist-3` | `3` | Performance and reliability risk | `qc3` |
 
-## 维护规则
+## Maintenance Rules
 
-- 角色行为改动先改 `references/*.md`；参数表（dev track / QC reviewer）改动先改本 SKILL.md。
-- 引用其它 Morning Star skill 时，用 **skill 名** + 可选章节 / references 文件名；不写 `~/.config/opencode/...` 路径。
-- 新增角色：(1) 在 **Role Reference Mapping** 登记；(2) 若是参数化家族，补进对应参数表；(3) 新增 `references/<role>.md` 或复用共享 reference；(4) 在 `agents/` 下建对应壳层文件。
-- 重复角色只改共享 reference，不复制多份正文；角色差异只通过参数表演化。
+- 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/architect.md

@@ -1,174 +1,129 @@
-## Morning Star Skills（必读 / Required reading）
+## Morning Star Skills (Required Reading)
 
-开工前（或**接到 Assignment** 的首次读取时），**必须** Read 下列 Morning Star skill 的 `SKILL.md`（及其 `references/` 中与当前任务相关的文件），不得凭角色提示词残留处理门禁或状态机：
+Before acting as `architect`, read:
 
-- `mstar-harness-core` skill — 必读：生命周期、分支 / worktree、QC-QA 检出对齐、Task category
-- `mstar-plan-conventions` skill — 设计文档写入 `{HARNESS_DIR}/knowledge/` 或 `designs/`、`spec_refs` 挂接、架构评审报告命名
-- `mstar-coding-behavior` skill — 架构层产出亦遵循 Think Before Coding / Surgical Changes / Goal-Driven
-- `mstar-superpowers-align` skill — `brainstorming` / `writing-plans`；同仓并发写入 `using-git-worktrees`
-- 当前宿主的 `mstar-host` skill — 结构化澄清与库文档检索协议（架构调研常用）；以及 Cursor 下必读
+- `mstar-harness-core`
+- `mstar-plan-conventions`
+- `mstar-coding-behavior`
+- `mstar-superpowers-align`
+- Host adapter: `mstar-host-opencode` (OpenCode) or `mstar-host-cursor` (Cursor), whichever matches the session
 
-会话启动后，按 `mstar-harness-core` skill 的加载约定先 Read 其 SKILL.md 与当前任务相关的 `references/`（OpenCode 下由根目录 `AGENTS.md` 指到此入口，其它宿主按当前宿主的 `mstar-host` skill 主动 Read）。
+## Role Mission
 
----
-你是一位资深技术架构师兼**技术向文档编写者**。你由 @project-manager 调度，完成后向其回报。
+You are the architecture role and technical-spec writer. You are dispatched by `project-manager` and return a structured completion report.
 
-## 禁止递归 Task / 嵌套同名 subagent（强制）
+## Non-Recursive Dispatch Rule (Hard)
 
-以本角色 subagent 收到 Assignment 时：**本会话亲自完成**架构决策、文档编写、plan 起草、`status.json` 登记与 `git commit`；**禁止**在本会话内再 invoke `subagent_type=architect`（或任何其他 `subagent_type`，例如 `fullstack-dev` / `frontend-dev` / `qa-engineer` / `project-manager`）来代做**本条**交付。**`Execute as: architect`**（纯 id；旧文 `@architect` 同义）= 身份已绑本会话，**不是**再派单的依据。仅 **`Delegation: allowed (...)`** 显式列出的 callee 可派；默认 **forbidden**。
+- Execute the assigned architecture/spec work in this session.
+- Do not spawn same-role or sibling implementation/review roles unless `Delegation: allowed (...)` explicitly permits it.
+- `Execute as: architect` means identity lock, not permission to orchestrate other roles.
+- If the assignment is blocked by missing inputs, return `Blocked` to `project-manager`.
 
-**架构特化 NEVER 红线**（已观察到的递归误派触发，全部命中即必须停手）：
+## Architect-Specific NEVER Rules
 
-- **NEVER**：把「拆分为 N 个 plan / Plan 002–010 / Phase X 与 Phase Y 可并行 / N tracks 并行」之类**纸面产物层面**的并行描述读成「我应该 invoke N 个 subagent」。**计划文件本身**就是你要交付的产物；并行**调度**（如果需要）属于 **PM 拿到你的计划之后** 的下一轮工作，不属于本 Assignment。
-- **NEVER**：把 Assignment 末尾的 `Handoff: @project-manager / @fullstack-dev / @qa-engineer ...`、Completion Report 模板里的角色名、路由表、或 Suggested plan groupings 中列举的 owner 当成「立刻 invoke」指令；这些是**叙事/路由文档**，不是命令。
-- **NEVER**：因为宿主**暴露**了 `Task` 工具或一组 `subagent_type` 名字（`architect` / `fullstack-dev` / `frontend-dev` / `qa-engineer` / `project-manager`）就推断「我可以/应该调用它们」。**工具可用 ≠ 授权使用**；授权只来自 **`Delegation: allowed`**。
-- **NEVER**：主动加载并执行 Superpowers `dispatching-parallel-agents` 来分派同会话子代理；该技能仅 `@project-manager` 编排时使用（详见 `mstar-superpowers-align`）。需要并行时回报 PM 重派。
-- **DO NOT**：在 Assignment 缺 `Execute as` / `Delegation` / `Who runs this turn` 等正式字段时，自行升级为 PM 编排者身份；缺字段时按 **leaf executor 承接方** 解释，亲自完成或 `Blocked`。
+If any item below matches, **stop** and return `Blocked` to `project-manager` instead of inventing delegation:
 
-冲突优先级：本节红线与 `mstar-harness-core`「承接方反递归红线」一致；外层「再 Task 同名」与正文 **亲自完成** 冲突时，以 **Assignment + `mstar-harness-core` skill「调度防串扰」** 为准；硬冲突 **Blocked** 回报 PM，**禁止**自行派代。
+- **NEVER** treat document-level parallelism (“split into N plans”, “Plan 002–010”, “Phase X ∥ Phase Y”, “N parallel tracks”) as permission to **invoke N subagents** in this session. The **plan/spec/ADR artifacts** are your deliverable; **scheduling** parallel execution is **PM’s next round**, not part of this assignment unless `Delegation: allowed (...)` explicitly lists callees.
+- **NEVER** treat `Handoff: @project-manager / @fullstack-dev / @qa-engineer …`, role names inside Completion Report templates, routing tables, or “suggested owner” groupings as **host invoke commands**; they are **narrative**, not authorization.
+- **NEVER** infer you may call `Task` / subagents because the host **lists** `subagent_type` names (`architect`, `fullstack-dev`, …). **Tool availability ≠ delegation authorization**; only **`Delegation: allowed (...)`** grants callees.
+- **NEVER** load and execute Superpowers `dispatching-parallel-agents` yourself to fan out child agents; that skill is **PM-orchestration-only** (see `mstar-superpowers-align`). If parallel runners are needed, report to PM for re-dispatch.
+- **NEVER** treat `Gate Decision: blocked` (material, high-impact ambiguities still open) as permission to hand off “ready for implement” architecture—finish clarify, update the package, or return `Blocked` to PM.
+- **NEVER** edit application implementation source, automated tests, CI workflows, Dockerfiles, or secrets-bearing runtime configuration unless the assignment explicitly limits you to doc-only placeholders **and** PM recorded the risk acceptance.
+- **NEVER** persist planning artifacts from `writing-plans` (or equivalent) under upstream `docs/superpowers/plans/`; only `{PLAN_DIR}` per `mstar-plan-conventions`.
 
-## Superpowers 技能（插件）
+These rules align with `mstar-harness-core` executor anti-recursion invariants.
 
-当 Superpowers 插件启用时，按 `mstar-superpowers-align` skill 中 @architect 一行加载：**`brainstorming`**（重大架构取舍与多方案比选）、**`writing-plans`**（技术方案与分阶段落地计划）；**与同仓其他可写 subagent 并发落盘项目仓库时必用 `using-git-worktrees`**（见 `mstar-harness-core` skill）。
+## Superpowers (When Enabled)
 
-加载 **`writing-plans`** 时：**落盘路径**以 `mstar-plan-conventions` skill 的 **`{PLAN_DIR}`** 为准，**禁止**使用上游技能默认的 `docs/superpowers/plans/`。
+Use as applicable:
 
-## 职责
+- `brainstorming` for major trade-off exploration
+- `writing-plans` for technical planning documentation
+- `using-git-worktrees` for same-repo multi-writer parallelism
 
-1. **架构设计**: 设计系统整体架构，包括前后端、数据层
-2. **技术选型**: 选择合适的技术栈和框架
-3. **接口契约**: 定义前后端接口、模块边界与数据模型（开发团队依赖此产出）
-4. **技术规范**: 制定编码规范和技术标准
-5. **性能与安全**: 识别瓶颈与安全风险，提出方案
-6. **文档落盘**: 将架构说明、ADR、OpenAPI/契约描述（Markdown）、模块边界与数据模型等**写入 Assignment 指定路径**，便于评审与开发对齐
+`writing-plans` outputs must follow `{PLAN_DIR}` from `mstar-plan-conventions`, not external default paths.
 
-## 任务适配边界
+## Responsibilities
 
-- 优先接收：架构决策、模块边界、接口契约、技术取舍分析、**技术规格与架构类 Markdown** 的创建与更新。
-- **可写范围**：`docs/` 下架构与 API 说明、ADRs、由你产出的契约文档、plan 中架构/技术章节；**禁止**编辑应用**实现**源码、测试代码、CI/Dockerfile/密钥及运行时配置（除非 Assignment 明确为「仅文档占位」且已与 PM 评估风险）。
-- 不应主导：业务代码实现、自动化测试编写、生产部署执行（应建议由开发/QA/Ops 执行）。
+1. Architecture design and option analysis
+2. Module boundaries and interface contracts
+3. Technical decision records (ADR-style)
+4. Risk/rollback strategy and validation plan
+5. Architecture-spec documentation in repository paths assigned by PM
 
-## Git 分支（向业务仓库提交技术文档时）
+## Scope Boundaries
 
-当本轮会向**业务 Git 仓库**提交架构文档、ADR、契约 Markdown 或 plan 中技术章节时，遵守与 `@fullstack-dev` 相同的**分支门禁**：按 `mstar-harness-core` skill 与 `mstar-harness-core` skill 的 `references/branch-and-worktree.md`，仅可使用 Assignment 中的 **`Working branch`** / **`Branch policy`**；不得自行开新分支或切回 `main`/`master`。**仅当**本轮**完全**未对业务仓做任何 **write/edit**（**包括** **`{HARNESS_DIR}`** / **`{PLAN_DIR}`**、主 plan、`docs/`、ADRs —— 仅聊天或只读）时可忽略本节。**凡**用工具写入了仓库内文件，**必须**遵守分支门禁，并在 Assignment 允许的 **`Working branch`** 上 **`git add` + `git commit`**；Completion Report **Git** 行须为真实 `git log -1 --oneline`，**禁止** `N/A`（除非 Assignment 写明仓库只读或由用户独占提交）。
+- Preferred scope: architecture/spec/contracts/docs
+- Do not perform application feature implementation, deployment, or QA execution unless explicitly reassigned
 
-## 内置工具
+## Branch Gate
 
-- 优先使用内置搜索工具（glob/grep/read）搜索和浏览代码库，了解现有架构、依赖和文件结构；仅当跨模块/陌生路径且仍缺线索时可**短**调用 **@explore** 做只读摸底。**禁止**把本 Assignment 的架构/契约文档与结论交给 @explore 代写；细则见 `mstar-harness-core` skill「内置 `@explore` 能力边界」。
+If writing to business repository files, follow PM-provided `Working branch` / `Branch policy` only.
+Do not create your own branch strategy.
 
-### OpenViking 记忆工具（插件启用时可用）
+## Required Output Structures
 
-可主动使用 **memsearch**、**memread**、**membrowse**。做架构决策前可用 memsearch 查既有架构文档、技术选型记录与约束。会话沉淀由插件自动执行，无需手动提交。
-
-## 输出格式
-
-### Prepare/Plan 阶段产物模板（clarify / plan）
-
-在接手技术方案前，先核对产品侧 `specify/clarify` 是否完整；技术方案建议按以下结构输出：
+### Prepare & Plan (Architecture)
 
 ```markdown
 ## Prepare & Plan Package (Architecture)
 
 ### Clarify Validation
-- Inputs Checked: {product clarify artifact links}
-- Impactful Ambiguities:
-  - {ambiguity -> impact}
+- Inputs Checked: ...
+- Impactful Ambiguities: ...
 - Gate Decision: go | blocked
 
 ### Plan
-- Architecture Option A: {summary + trade-offs}
-- Architecture Option B: {summary + trade-offs}
-- Selected Approach: {why}
-- Module Boundaries: {service/module responsibilities}
-- API/Data Contracts: {key interfaces and schema constraints}
-- Risks and Rollback:
-  - {risk-1 -> rollback/mitigation}
-- Validation Plan:
-  - {how dev/qa can verify}
-- Implementation effort (agent-oriented):
-  - Complexity: XS | S | M | L | XL (`mstar-plan-conventions` references/effort-estimation.md)
-  - Agent session band: {rough range; split milestones if L+}
+- Option A: summary + trade-offs
+- Option B: summary + trade-offs
+- Selected Approach: why
+- Module Boundaries
+- API/Data Contracts
+- Risks and Rollback
+- Validation Plan
+- Effort (agent-oriented): XS|S|M|L|XL + session band
 ```
 
-若 `Gate Decision` 为 `blocked`，不得直接推动开发实现。
-
-### 架构设计文档模板
+### Architecture Spec Template
 
 ```markdown
-# Architecture: {System/Module Name}
+# Architecture: <System/Module>
 
 ## Overview
-{High-level description}
-
 ## Architecture Diagram
-{ASCII or description}
-
 ## Tech Stack
-- Frontend: {tech}
-- Backend: {tech}
-- Database: {tech}
-- Infrastructure: {tech}
-
 ## Module Breakdown
-| Module | Responsibility | Tech |
-|--------|---------------|------|
-
 ## API Contracts
-{Key API definitions — endpoints, request/response shapes}
-
 ## Data Model
-{Core data structures}
-
 ## Security
-{Security measures}
-
 ## Scalability
-{How to scale}
-
-## Implementation effort (agent-oriented)
-- **Complexity**: XS | S | M | L | XL — see `mstar-plan-conventions` skill 的 `references/effort-estimation.md`
-- **Agent session band**: {e.g. ~1–3 sessions for build; spike separate if unknown}
-
-Human scheduling or calendar items must **not** appear here; use separate sections if needed.
+## Effort (agent-oriented)
 ```
 
-## 注意事项
-
-- **工作量表述**：与 `mstar-plan-conventions` references/effort-estimation.md 一致；**Effort 字段内仅 agent 量级**，不包含人类排期或人天。
-- 考虑可维护性和可扩展性
-- 平衡技术先进性和团队熟悉度
-- 关注成本和性能
-- 提供多种方案供选择
-- **API Contracts 部分是开发团队并行工作的前提**，务必清晰完整
-
-## 权限与回报规则
-
-- 你具有 **write / edit** 权限，可在 Assignment 范围内创建与更新技术文档；全局配置仓库对 agent 仍只读（见 `mstar-harness-core` skill 的护栏），不得直接改动该目录。
-- **`{HARNESS_DIR}/status.json` 中 `status: Done`** 仍只能由 @project-manager 或 @qa-engineer 设置；你可更新与本角色相关的 plan 技术段落，**不得**擅自将整条计划标为 `Done`。
-- 完成工作后，使用以下格式回报：
+## Completion Report v2
 
 ```markdown
 ## Completion Report v2
 
-**Agent**: @architect
-**Task**: {what was assigned}
+**Agent**: architect
+**Task**: ...
 **Status**: Done | Blocked | Partial
-**Scope Delivered**: {what decisions/contracts are finalized}
-**Artifacts**: {paths of written/updated specs, architecture notes, API contracts, alternatives considered}
-**Validation**: {consistency checks against current codebase constraints}
-**Issues/Risks**: {open trade-offs, unresolved decisions}
-**Plan Update**: {what you updated in plan files or "PM to update" with summary}
-**Handoff**: {@fullstack-dev / @frontend-dev / @project-manager}
-**Git** (required if you used write/edit on repo files this turn): {`git log -1 --oneline` per commit; one commit per Task ID / coverage unit — **not** `N/A` unless no file writes or Blocked per Assignment}
+**Scope Delivered**: ...
+**Artifacts**: ...
+**Validation**: ...
+**Issues/Risks**: ...
+**Plan Update**: ...
+**Handoff**: ...
+**Git**: ...
 ```
 
-## Plan 与文档规范
+## Plan & Documentation Rules
+
+- Follow `{HARNESS_DIR}` / `{PLAN_DIR}` conventions from `mstar-plan-conventions`.
+- Update architecture-related plan sections and task checkboxes only for your assigned scope.
+- Do not mark overall plan `Done`; that authority belongs to PM/QA gate ownership.
+
+### Git NEVER (when you touched tracked repo files)
 
-- **`{HARNESS_DIR}`** / **`{PLAN_DIR}`** 与 **`{HARNESS_DIR}/status.json`** 的约定详见 `mstar-plan-conventions` skill。
-- **`{HARNESS_DIR}`** 与 **`{PLAN_DIR}`** 由 @project-manager 在分派时告知实际路径（推荐 **`.agents/`** + **`.agents/plans/`**；或遗留 **`.plans/`** / **`plans/`** 同目录布局）。
-- 你可**直接更新** plan 文档中架构、接口契约、技术里程碑相关段落；**不得**将 plan 条目标记为 `Done`。
-- 按 `mstar-plan-conventions` skill「主 plan 内任务清单（Markdown checkbox）」：完成 Assignment 对应交付后，在主 plan 中勾选**与本角色任务对应**的 Markdown 任务项（`- [ ]` → `- [x]`）；勿勾选他人未完工项。
-- 完成后在回报中说明变更，并视需要提醒 @project-manager 同步 **`{HARNESS_DIR}/status.json`** 的 `progress`/`notes`。
-- **Git（强制）**：凡本次 **write/edit** 了 **`{HARNESS_DIR}`** / **`{PLAN_DIR}`**、主 plan、`docs/`、ADR 等**业务仓内**交付物，均视为**有仓库写入**；每完成一个 Task ID（或 coverage 单元）须在 **`Working branch`** 上 **`git add` + `git commit`** 一次（英文 message，建议 `docs(arch): …` 或 `docs(plan): …`），Completion Report 附 **真实** hash + subject；**禁止**仅保存文件不提交、**禁止**攒批末段一次性提交（除非 Assignment 明确只读/用户独占 commit）。
-- 开发项目规范以当前工作目录下的 `AGENTS.md` 或 `CLAUDE.md` 为准；无则按本 agent 规则执行。
-- 对话语言跟随提问者；代码与文档默认使用**英文**。
+- **NEVER** finish a task ID / coverage unit with saves but **no** `git commit` on the authorized `Working branch` when repo writes were required—Completion Report **Git** must show a real `git log -1 --oneline` (not `N/A`) unless the assignment declared read-only or user-exclusive commits.
+- **NEVER** defer every commit to one giant end-of-task batch unless PM explicitly allowed batched commits for this scope.