@mstar-harness/opencode 0.7.3 → 0.7.5

package/INSTALL.md

@@ -6,14 +6,11 @@
 
 ## Installation
 
-Add Morning Star to the `plugin` array in your `opencode.json` (global or project-level).
-
-If you use Superpowers together, use:
+Add Morning Star to the `plugin` array in your `opencode.json` (global or project-level):
 
 ```json
 {
   "plugin": [
-    "superpowers@git+https://github.com/obra/superpowers.git",
     "@mstar-harness/opencode@latest"
   ]
 }
@@ -64,7 +61,7 @@ The `@mstar-harness/cli` package (`npx @mstar-harness/cli init`) migrates that e
 
 ### Plugin not loading
 
-1. Check logs: `opencode run --print-logs "hello" 2>&1 | grep -i superpowers`
+1. Check logs: `opencode run --print-logs "hello" 2>&1 | grep -i mstar`
 2. Verify the plugin line in your `opencode.json`
 3. Make sure you're running a recent version of OpenCode
 

package/harness-commands/iteration-drive.md

@@ -1,6 +1,6 @@
 ---
 name: iteration-drive
-description: Drive the active iteration to completion — run the Autonomous Execute loop (Phase 2 of mstar-iteration) until all plans are Done, then run iteration-close (Phase 3: compound + compass + roadmap update) on the integration branch, then create PR to target branch (default main)
+description: Drive the active iteration to completion — run the Autonomous Execute loop (Phase 2 of mstar-iteration) until all plans are Done, then run iteration-close (Phase 3: compound + compass + roadmap update) on the integration branch, then create PR to the recorded target branch
 agent: project-manager
 ---
 
@@ -20,12 +20,20 @@ Drive the active Morning Star iteration forward. The canonical flow is in **`mst
 
 ## Phase 2: Autonomous Execute
 
+**Branch policy first** — before any plan dispatch（`mstar-iteration` §2.3）:
+
+| Field | SSOT | If missing |
+|-------|------|------------|
+| `iteration_base_branch` | `status.json` `metadata` → compass frontmatter | **STOP** — ask user; **never** default `main` |
+| `spec_integration_branch` | plan `metadata` | backfill from iteration-start / compass |
+| `target_branch` | `status.json` `metadata` → compass frontmatter | **STOP** — ask user |
+
 Execute **`mstar-iteration` § Phase 2** exactly. Summary:
 
-1. **Precondition gate** (§ 2.0) — three checks before entering
+1. **Precondition gate** (§ 2.0) — **four** checks（含 branch metadata #4）
 2. **Session todos** (§ 2.1) — set host todos per plan wave
-3. **Read backlog** (§ 2.2) — `status.json` + `spec_integration_branch`
-4. **Integration branch** (§ 2.3) — checkout/create
+3. **Read backlog** (§ 2.2) — `status.json` + branch metadata
+4. **Integration branch** (§ 2.3) — `git checkout -b <spec_integration_branch> <iteration_base_branch>` when creating（**not** implicit `main`）
 5. **Per-plan loop** (§ 2.4) — for each non-`Done` plan:
    - Create plan feature branch from integration
    - Dispatch implement subagents (dispatch-first)
@@ -63,8 +71,9 @@ git push origin <spec_integration_branch>
 
 All iteration-close changes committed to integration branch:
 
-- Resolve PR target branch from `status.json` → `target_branch`（default `main`）
-- Create PR from `spec_integration_branch` to target
+- Resolve PR target: `status.json` → `metadata.target_branch`（fallback：compass frontmatter `target_branch`）
+- If missing → **stop and ask**; never default `main` / `master`
+- Create PR: `spec_integration_branch` → `target_branch`
 - Report summary: plans completed, compound round（结晶文档数）, target branch, PR link
 
 PR 合并后（babysit loop 或手动），本次迭代完整结束。

package/harness-commands/iteration-start.md

@@ -1,6 +1,6 @@
 ---
 name: iteration-start
-description: Start a new harness iteration — research backlog, lock direction with grill-me, produce compass/plans, run mandatory Review & Edit chain via Task dispatch (product-manager → architect → writing-specialist each review-and-edit, then PM final lock), then integration branch. Not Done until review chain completes and compass is locked.
+description: Start a new harness iteration — research backlog, lock direction with grill-me, produce compass/plans, run mandatory Review & Edit chain via Task dispatch (product-manager → architect → writing-specialist each review-and-edit, then PM final lock), then create the integration branch from an explicit base. Not Done until review chain completes, compass is locked, and base/target branches are recorded.
 agent: project-manager
 ---
 
@@ -56,14 +56,18 @@ Run the **grill-me skill** to stress-test candidate directions with the user:
 - Walk through trade-offs for each candidate
 - Converge on a **single iteration direction** with shared understanding
 - Document: locked direction, success criteria, non-goals
+- Confirm delivery branch policy:
+  - `iteration_base_branch`: branch/ref used to create `spec_integration_branch`
+  - `target_branch`: PR target after iteration-close
+  - If either is not explicit, inspect the current branch and ask. **Do not default to `main` / `master` just because those names exist.**
 
 ## 4. Write Compass & Plans
 
-Produce harness artifacts per **`mstar-iteration` § 1.3 创建迭代 compass**（template: `mstar-iteration/references/iteration-compass-template.md`）：
+Produce harness artifacts per **`mstar-iteration` § 1.3**（template: `mstar-iteration/references/iteration-compass-template.md`）：
 
-- `{ITERATION_DIR}/<iteration-id>-delivery-compass.md` — iteration scope, plans table, milestones, acceptance criteria, non-goals, roadmap position
+- `{ITERATION_DIR}/<iteration-id>-delivery-compass.md` — YAML frontmatter **must** include `iteration_base_branch`, `target_branch`, `status: active`
 - `{PLAN_DIR}/<plan-id>-<name>.md` for each plan in this iteration
-- Register all plans in `{HARNESS_DIR}/status.json`（per `mstar-plan-artifacts`）
+- Register all plans in `{HARNESS_DIR}/status.json`（per `mstar-plan-artifacts` §1.5：root `metadata` + plan `spec_integration_branch`）
 - Update `{ITERATION_DIR}/README.md` index（per `mstar-iteration` § 1.4）
 
 ## 5. Review & Edit Chain（HARD GATE — do not commit before this）
@@ -103,12 +107,22 @@ PM must print this block before §6; all `[ ]` must be `[x]`:
 - [ ] @architect Task completed — compass / specs edited
 - [ ] @writing-specialist Task completed — iteration docs edited
 - [ ] PM final lock: compass `status: locked`; Prepare gates pass (blocked plans documented)
+- [ ] Branch policy locked: `iteration_base_branch`, `spec_integration_branch`, and `target_branch` recorded in compass / `status.json`
 - [ ] **THEN**: git commit + push `iteration/<iteration-id>`
 
 ## 6. Integration Branch
 
 **Precondition**: §5 complete — compass `status: locked`; specialist Tasks returned; Prepare gates confirmed.
 
-- Create `iteration/<iteration-id>` from `main`
-- Register `spec_integration_branch` in `{HARNESS_DIR}/status.json`
+- Create `spec_integration_branch` (e.g. `iteration/<iteration-id>`) **from** the locked `iteration_base_branch`:
+
+```bash
+git fetch origin   # if needed
+git checkout -b <spec_integration_branch> <iteration_base_branch>
+# or: git checkout <spec_integration_branch>  if it already exists
+```
+
+- Register `iteration_base_branch`, `spec_integration_branch`, and `target_branch` in compass frontmatter **and** `{HARNESS_DIR}/status.json` root `metadata`
 - Commit all documents to the integration branch and push to remote
+
+**STOP** if `iteration_base_branch` or `target_branch` is missing. Ask the user or derive only from an already documented project/iteration policy; never silently substitute `main`.

package/harness-skills/mstar-branch-worktree/SKILL.md

@@ -7,7 +7,7 @@ description: Morning Star business-repo Git feature branches, same-repo concurre
 
 **首次 Read 本 skill 前：必须先 Read `mstar-harness-core`（SKILL.md）。** 冲突时 **以 `mstar-harness-core` 为准**。
 
-**Spec 多 plan 命名**（`spec_integration_branch`、合入 `main` 的 PR 门禁）→ **`mstar-plan-conventions`**。下文为 **Git 操作与 QC/QA 检出对齐** 全文（无单独 reference 层）。
+**Spec 多 plan 命名**（`iteration_base_branch`、`spec_integration_branch`、`target_branch` PR 门禁）→ **`mstar-plan-conventions`**。下文为 **Git 操作与 QC/QA 检出对齐** 全文（无单独 reference 层）。
 
 ## Scope（摘要）
 
@@ -105,16 +105,16 @@ description: Morning Star business-repo Git feature branches, same-repo concurre
 
 当 **`@project-manager` 在同一调度轮次内并发启动多个** subagent（含宿主侧「并行 Task / 并行 subagent」），且 **≥2 个承接方**可能对 **同一 Git 仓库的同一工作区（同一 cwd 检出目录）**产生写文件或 `git commit` 级改动时：
 
-- **必须**为每条并发写流使用 **独立检出目录**：以 **`git worktree`** 隔离（流程与目录安全要求见 Superpowers **`using-git-worktrees`**；未安装插件时仍须达到同等隔离效果，可 Read 该技能文件并按 `git worktree` 手册执行）。
+- **必须**为每条并发写流使用 **独立检出目录**：优先使用宿主原生 worktree/checkout 隔离能力；没有原生能力时使用 `git worktree`，并按本 skill 的目录、分支和 QC/QA 对齐规则执行。
 - **必须**与既有分支门禁一致：每个可写承接方的 Assignment 仍须含 PM 已批准的 **`Working branch`** / **`Branch policy`**；在某一 worktree 内 **不得**擅自 `checkout` 到未授权分支或私自新建分支。
-- **PM 须在 Assignment 中写清**各并发写流的 **检出约定**（例如预期 **`Worktree path`** / 命名规则，或「由承接方按 `using-git-worktrees` 创建并在 Completion Report 回报路径」），避免多代理默认共享同一目录导致互相覆盖、冲突或半写入状态。
+- **PM 须在 Assignment 中写清**各并发写流的 **检出约定**（例如预期 **`Worktree path`** / 命名规则，或「由承接方创建/使用隔离 worktree 并在 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 只解决「目录与工作区隔离」，不替代分支授权。
+当多个可写 subagent **并发**修改 **同一仓库** 时，**不得**共用同一检出目录作为写入 cwd。PM 在分派前应规划 worktree/checkout 隔离，并在各承接方 Assignment 中写明 **`Working branch`** / **`Branch policy`** 及 **检出路径约定**（或要求回报实际 worktree 路径）。单分支决策权仍仅属 PM；worktree 只解决「目录与工作区隔离」，不替代分支授权。
 
 **同仓、同一 plan、多可写并行轨（推荐）**：在挂齐各轨 `git worktree` **之前**，先与用户确认并写明 **plan 集成分支**（从商定 `<base>` 创建）及各轨 **topic 分支** 如何从该线分出或如何 **merge 回** 该线；QC 前再将待一并验收的提交 **全部归并**到 PM 指定为 QC **`Working branch`** 的那条分支的 **`HEAD`**。分步说明与示例命名边界见下节 **「推荐默认编排：先建 plan 集成分支，再挂各 worktree」**。
 
@@ -124,10 +124,10 @@ description: Morning Star business-repo Git feature branches, same-repo concurre
 
 - **语义区分（必须理解）**：开发阶段可以存在 **多个** `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>`** 仅为命名示例，**非强制**。**多 `plan_id` 同源一条 `primary_spec`（Spec 文档）时**：该集成分支在计划语义上即 **Spec 集成分支**；各 Plan 的 feature 线 merge 回此线，**全部 Plans 完成后** 合入默认保护分支须 **走 PR**（见 `mstar-plan-conventions` SKILL.md「Spec 文档驱动的分支模型」）。
+  1. **先起集成分支（再挂 worktree）**：在派发各轨 **实现** Assignment 之前，PM 与用户确认 **`Branch policy`**，并建立 **plan 集成分支**（Assignment 使用 **`Working branch: create <plan-integration-branch> from <base>`** 或等价明确写法；`<base>` 必须是 PM 明确记录的 base，例如 root `metadata.iteration_base_branch`、现有 feature 分支、远程跟踪分支或团队既定主线，**不得**未授权假设）。**分支名由 PM 指定**；下文 **`feature/<plan-id>-integrate`**、**`integrate/<plan-id>`** 仅为命名示例，**非强制**。**多 `plan_id` 同源一条 `primary_spec`（Spec 文档）时**：该集成分支在计划语义上即 **Spec 集成分支**；各 Plan 的 feature 线 merge 回此线，**全部 Plans 完成后** 向显式 `target_branch` **走 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 式例外）。
+  4. **QC / QA 的 `Working branch` 与合并主线**：派发 QC 三审与对齐的 QA 时，**`Working branch`** **即为**上一步 **已含全部待审提交** 的那条分支（常见为 plan 集成分支）。**`Review range` / `Diff basis`** 通常相对 **尚未合并 feature 的**显式目标或 base 参照（例如 `merge-base: <target_branch-or-base-ref>` + `tip: HEAD`），审查的是 **「feature 线 vs 目标线」** 的差异；**默认不要求**在 QC **通过前** 已把该分支 merge 进目标分支（除非 **`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 各对应 **一条**分支快照与 **一套**对齐字段。
@@ -137,10 +137,10 @@ description: Morning Star business-repo Git feature branches, same-repo concurre
 
 开发在 **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 集成分支先行）** 与误派禁令见上一小节。
+- **`@project-manager`** 分派 **QC** 时须在 Assignment 写明与待审实现一致的 **`Working branch`**，并写明 **`Review cwd` / `Worktree path`**：**优先**沿用开发 **Completion Report** 中回报的业务仓 **实现检出路径**（即「该 feature 的 worktree」）**当且仅当**该路径上的检出分支 **`HEAD` 已包含本轮待审的全部提交**（含曾发生在其他并行 worktree、现已归并到该分支的变更）。否则 **必须**改用 **集成完成后的** `Working branch` 与对应检出路径（或在该分支上 **另开** 审查专用 worktree）。若开发未用 worktree，则写明单一明确的业务仓根路径。若审查需与开发目录 **物理分离** 但仍审 **同一分支**，可指示在 **`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。
+  - **`Review range` / `Diff basis`**：明确本次审查所针对的 **diff/提交范围**（例如 `merge-base: <target_branch-or-base-ref>` + `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 补全。

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

@@ -1,6 +1,6 @@
 ---
 name: mstar-coding-behavior
-description: Morning Star (启明星) 跨角色通用编码行为准则 —— Think Before Coding（先读懂再改、显式假设、不静默猜测、读 imports/test/项目模式）、Simplicity First（YAGNI 优先不写代码、The Ladder 决策层级含依赖评估、删除优于添加、简洁优于聪明、5 项具名反模式速查、`simplify:` 标记天花板与升级路径、最小耐久切片）、Surgical Changes（改动可追溯、Bug 修根因先 grep 所有调用点、不顺手重构、不 piggyback）、Debugging（读完整报错与栈追踪、先复现、一步一测、根因分析、Bug 修复前先写复现测试、卡住时坦白）、Goal-Driven Execution（非平凡逻辑必留一个可运行检查、模糊请求转可验证结果、测行为不测实现、已有测试前后对比、不能测试说理由、Step → verify 微模板、分批留 roadmap）、Communication（说做了什么及为什么、标记顾虑、精确表达不确定性、不解释已知的、commit message 质量）。任何实现、调试、重构、审查任务都应优先 Read 本 skill；`@fullstack-dev` / `@frontend-dev` / `@fullstack-dev-2` / `@architect` / `@qa-engineer` / `@ops-engineer` / `@prompt-engineer` 动手前必读；QC 审查员核对变更是否只做了该做的手术时必读。本 skill 不覆盖分支门禁、QC/QA 路由、Assignment 权限、Done 所有权等不变量（那些以 `mstar-harness-core` 为准）。
+description: Morning Star (启明星) 跨角色通用编码行为准则 —— Think Before Coding（先读懂再改、显式假设、不静默猜测、读 imports/test/项目模式）、Simplicity First（YAGNI 优先不写代码、The Ladder 决策层级含依赖评估、删除优于添加、简洁优于聪明、5 项具名反模式速查、`simplify:` 标记天花板与升级路径、最小耐久切片）、Surgical Changes（改动可追溯、Bug 修根因先 grep 所有调用点、不顺手重构、不 piggyback）、Debugging（读完整报错与栈追踪、先复现、一步一测、根因分析、Bug 修复前先写复现测试、卡住时坦白）、Review Feedback Handling（先核实反馈再改、逐项处理、可用证据反驳错误建议）、Goal-Driven Execution（非平凡逻辑必留一个可运行检查、模糊请求转可验证结果、测行为不测实现、已有测试前后对比、不能测试说理由、Step → verify 微模板、分批留 roadmap）、Communication（说做了什么及为什么、标记顾虑、精确表达不确定性、不解释已知的、commit message 质量）。任何实现、调试、重构、审查任务都应优先 Read 本 skill；`@fullstack-dev` / `@frontend-dev` / `@fullstack-dev-2` / `@architect` / `@qa-engineer` / `@ops-engineer` / `@prompt-engineer` 动手前必读；QC 审查员核对变更是否只做了该做的手术时必读。本 skill 不覆盖分支门禁、QC/QA 路由、Assignment 权限、Done 所有权等不变量（那些以 `mstar-harness-core` 为准）。
 ---
 
 ## Load order（必读顺序）
@@ -166,7 +166,31 @@ Micro template:
 - **Test behavior, not implementation.** A test that checks whether a constructor sets properties is worthless. A test that checks whether validation actually rejects bad input is valuable. Focus on the interesting cases.
 - **If you cannot write a test, say why.** "I cannot easily test this because the database calls are tightly coupled to the business logic" is useful information that may signal a need for restructuring. Do not skip testing without an explanation.
 
-## 6) Communication
+## 6) Review Feedback Handling
+
+Core idea: review feedback is technical input, not an order to perform unverified edits.
+
+When receiving code review, QA, CI, or human feedback:
+
+1. Read all feedback before editing.
+2. Clarify ambiguous items before partial implementation.
+3. Verify each suggestion against codebase reality.
+4. Apply technically correct feedback one item at a time.
+5. Test each fix individually where practical.
+6. Push back with evidence when feedback is incorrect, obsolete, risky, out of scope, or violates YAGNI.
+
+Feedback priority:
+
+| Feedback type | Handling |
+|---|---|
+| Security, correctness, data loss, build/test failure | Fix or escalate before proceeding. |
+| Scope mismatch, reviewer misunderstanding, obsolete assumption | Verify and push back with evidence. |
+| Style-only suggestion | Apply only if it matches project conventions or is requested by the user/PM. |
+| New feature disguised as review | Route through PM/plan unless explicitly in scope. |
+
+Do not perform agreement. State the technical action, the verification result, or the technical reason for disagreement.
+
+## 7) Communication
 
 Core idea: how you communicate about code matters as much as the code itself.
 
@@ -178,8 +202,7 @@ Core idea: how you communicate about code matters as much as the code itself.
 
 ## Integration Notes
 
-- This skill is additive to `verification-before-completion` (见 `mstar-superpowers-align`) and other Morning Star controls.
-- It must not be used to bypass:
+- This skill must not be used to bypass:
   - branch constraints,
   - QC/QA gate definitions,
   - assignment authority,

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

@@ -1,6 +1,6 @@
 ---
 name: mstar-dispatch-gates
-description: Morning Star 派发与委派门禁 —— 仅 PM 可增派 subagent、`Execute as` 与 `Delegation`、承接方反递归 NEVER 红线、同条消息 N 次 invoke、QC 三审禁止串行 rollout、Assignment 文案≠派发（invoke 条数须对齐）、未齐不发（emit zero until batch-ready）。**必须**在 `@project-manager` 每轮派发、QC 三审并发、双轨 implement、或 leaf 角色疑惑能否 Task 时 Read；所有非 PM 承接方动手前必读反递归与自检。同仓 worktree 与 QC 检出对齐见 `mstar-branch-worktree`。Superpowers 并行短语见 `mstar-superpowers-align`。宿主细则见 `mstar-host`（`references/parallel-dispatch.md` 与各宿主 reference）。
+description: Morning Star 派发与委派门禁 —— 仅 PM 可增派 subagent、`Execute as` 与 `Delegation`、承接方反递归 NEVER 红线、同条消息 N 次 invoke、QC 三审禁止串行 rollout、Assignment 文案≠派发（invoke 条数须对齐）、未齐不发（emit zero until batch-ready）。**必须**在 `@project-manager` 每轮派发、QC 三审并发、双轨 implement、或 leaf 角色疑惑能否 Task 时 Read；所有非 PM 承接方动手前必读反递归与自检。同仓 worktree 与 QC 检出对齐见 `mstar-branch-worktree`。宿主细则见 `mstar-host`（`references/parallel-dispatch.md` 与各宿主 reference）。
 ---
 
 ## Load order（必读顺序）
@@ -14,7 +14,7 @@ description: Morning Star 派发与委派门禁 —— 仅 PM 可增派 subagent
 > **先回到你 Assignment 最顶部的 `**IDENTITY**` 块重读一遍** —— 那里已经告诉你：你是谁、你不是谁、Task 工具不属于你。本节是那个身份断言的加固版。
 
 **身份断言（牢记，不动摇）：**
-- **你就是** `Execute as` 写的那个角色。你**不是 PM**，不是调度者，不是 `dispatching-parallel-agents` 的使用者。
+- **你就是** `Execute as` 写的那个角色。你**不是 PM**，不是调度者，不是 parallel-agent dispatch 的使用者。
 - Task/subagent 工具即使在你的工具列表里出现，它**不属于你**。把它当作你没见过的工具 —— 不是"不能用"，是"你没有"。
 - 所有工作由你**本人**在当前会话内完成（Read / Write / Edit / Shell / Grep / Glob）。任何"这样做更高效"的想法都不构成 dispatch 的理由。
 - 遇到超出能力范围的需求 → 写 `## Blocked` 回报 PM，**不是**尝试 dispatch。Blocked 是你能发出的正确信号，dispatch 不是。
@@ -27,7 +27,7 @@ description: Morning Star 派发与委派门禁 —— 仅 PM 可增派 subagent
 - **NEVER** 把 Assignment 里出现的 **任何** `@<role>`、反引号 `` `<role-id>` ``、**Handoff**、**QA note**、**Completion Report** 模板里的角色名、路由表下游角色当成「立刻 invoke」的指令；这些是**叙事 / 路由文档 / 后续 PM 编排意图**，不是命令。
 - **NEVER** 把「分解为多个计划 / 多 phase / 多 track」等**设计产物层面**的并行或拆分读成「应 invoke 与子会话数量对应的多个 subagent」。**纸面产物**由本会话写盘完成；并行**调度**由 PM 在后续轮次决定。
 - **NEVER** 因宿主**暴露**了 `Task` 或若干 `subagent_type` 名称就推断可以调用。**工具可用 ≠ 授权使用**；授权只来自 **`Delegation: allowed (...)`**。
-- **NEVER**（非 PM）主动执行 `dispatching-parallel-agents` 来分派子代理；需要并行时回报 PM。
+- **NEVER**（非 PM）主动执行 parallel-agent dispatch 来分派子代理；需要并行时回报 PM。
 - **DO NOT** 在 Assignment 缺少 `Execute as` / `Delegation` / `Who runs this turn` 时自行「补齐」为 PM；缺字段时按 **leaf executor** 解释：亲自完成或 **`Blocked`**。
 - **DO NOT** 用「Assignment 太长 / 像编排稿」当作分派依据；先交付本会话任务再回报，分派由 PM 下一轮决定。
 
@@ -47,7 +47,7 @@ description: Morning Star 派发与委派门禁 —— 仅 PM 可增派 subagent
 - 额外代理仅以 **`Delegation: allowed (...)`** 为准；未显式写时视为 **`Delegation: forbidden`**。
 - Assignment 正文中的 `@xxx` 默认按「文本引用」解释，**不**视为自动调用命令。
 - 承接方若判断必须增加 subagent，应先回报 **`Blocked`** 请 PM 重分派。
-- **Superpowers `subagent-driven-development`**：per-task 子步**勿**用 `@qc-specialist*`；用 `@general` / `generalPurpose` 或 PM 标明的 informal `@qa-engineer`。详见 **`mstar-superpowers-align`**。
+- Per-task informal review, when PM explicitly allows it, must not use `@qc-specialist*`; use `@general` / `generalPurpose` or PM-marked informal `@qa-engineer`. Formal QC remains `mstar-review-qc`.
 
 ## 并发分派完整性门禁（PM 强制）
 

package/harness-skills/mstar-dispatch-gates/references/leaf-executor-checklist.md

@@ -16,7 +16,7 @@ Before any Task/subagent call (if I somehow forget the preamble):
 4. Is `subagent_type` equal to my `Execute as`? If yes → **forbidden** (recursive dispatch).
 5. Am I treating `@roles`, Handoff, QA note, Completion Report roles, or multi-plan/multi-track **design text** as invoke commands? If yes → **stop**; deliver in-session.
 6. Am I invoking because the tool exists? **Available ≠ authorized.**
-7. Need parallel work or PM-only `dispatching-parallel-agents`? → **`Blocked`**; PM dispatches on the next round.
+7. Need parallel work or PM-only dispatch? → **`Blocked`**; PM dispatches on the next round.
 
 If blocked, report: `## Blocked — recursive dispatch refused (<which NEVER or reason>)`
 

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

@@ -33,7 +33,7 @@ description: Morning Star (启明星) harness **强制全局入口** —— 信
 | 角色 | 始终 | 按任务追加（典型） |
 |------|------|-------------------|
 | **全部** | 本 skill | — |
-| **`@project-manager`** | 本 skill | `mstar-dispatch-gates`、`mstar-phase-gates`、`mstar-plan-conventions`、`mstar-superpowers-align`、`mstar-roles`；派 QC 前 `mstar-review-qc`；并行/审查 `mstar-branch-worktree`；plan/status/reports `mstar-plan-artifacts`；UI 类 plan Prepare 阶段 `mstar-design-md`（DESIGN.md 门禁）；迭代管理 `mstar-iteration`（iteration-start/drive/close 含 compound）；战略性工作 `mstar-strategy`。**不**读 `mstar-coding-behavior` |
+| **`@project-manager`** | 本 skill | `mstar-dispatch-gates`、`mstar-phase-gates`、`mstar-plan-conventions`、`mstar-roles`；派 QC 前 `mstar-review-qc`；并行/审查 `mstar-branch-worktree`；plan/status/reports `mstar-plan-artifacts`；UI 类 plan Prepare 阶段 `mstar-design-md`（DESIGN.md 门禁）；新建/大改 skill 时 `mstar-skill-authoring`；迭代管理 `mstar-iteration`（iteration-start/drive/close 含 compound）；战略性工作 `mstar-strategy`。**不**读 `mstar-coding-behavior` |
 | **实现/审查/QA/运维** | 本 skill + `mstar-coding-behavior` + 角色 ref | 有 git 写：`mstar-branch-worktree`；有 plan 路径：`mstar-plan-conventions`（路径符号节）；QC/QA：`mstar-review-qc`；改 status/residual：`mstar-plan-artifacts`；UI 任务：`mstar-design-md`（读取 DESIGN.md tokens）；写入知识库 `{KNOWLEDGE_DIR}`：`mstar-compound`（PM 触发） |
 | **leaf 承接方** | 上栏 + **`mstar-dispatch-gates`**（反递归节） | — |
 
@@ -71,7 +71,7 @@ PM 在 Assignment 写 **`Task category`**（主类 + 可选 `secondary`）：
 
 ## 长任务纪律
 
-可追踪清单（plan `tasks` 或 Todo）；偏离时 PM 拉回；完成前须可核对证据（**`mstar-superpowers-align`** · `verification-before-completion`）。
+可追踪清单（plan `tasks` 或 Todo）；偏离时 PM 拉回；完成前须可核对证据（实现侧自检见 **`mstar-coding-behavior`**；门禁证据见 **`mstar-phase-gates`** / **`mstar-review-qc`**）。
 
 **Durable Roadmap Gate**：凡声明“分批 / 后续 / next plan / later / temporary workaround”的非热修任务，必须在 `{PLAN_DIR}` 主 plan、CreatePlan mirror、`status.json`/residual、或 PM Task Board 中写清后续路线（批次、依赖、owner/触发条件、完成定义）。只在对话或 Completion Report 里说“以后做”不算可追踪，不能进入 implement GO 或 Done。
 
@@ -88,11 +88,11 @@ PM 在 Assignment 写 **`Task category`**（主类 + 可选 `secondary`）：
 | `mstar-plan-artifacts` | 主 plan、reports、`status.json`、residual、knowledge、Done 归档 |
 | `mstar-design-md` | DESIGN.md 设计系统规范 —— 创建/审计/维护 design tokens，三级检查清单，light/dark 双主题 |
 | `mstar-review-qc` | QC 工作流、模板、verdict、residual 留档、deep review 透镜 |
-| `mstar-coding-behavior` | Think / Simplicity / Surgical / Debugging / Goal-Driven / Communication |
+| `mstar-coding-behavior` | Think / Simplicity / Surgical / Debugging / Review Feedback / Goal-Driven / Communication |
 | `mstar-compound` | 知识结晶 —— 已解决问题→结构化知识文档，双轨（Bug/Knowledge），「是否值得结晶」自检清单，重叠检测，可发现性检查，CONCEPTS.md 协同 |
 | `mstar-compound-refresh` | 知识维护 —— 审查/更新/合并/删除 `{KNOWLEDGE_DIR}` 文档 |
 | `mstar-strategy` | `STRATEGY.md` 全局战略方向 —— 产品愿景、技术方向、决策原则 |
-| `mstar-superpowers-align` | Superpowers × harness 优先级与短语 |
+| `mstar-skill-authoring` | mstar-native skill authoring: trigger contracts, progressive disclosure, pressure scenarios, behavior-change evidence |
 | `mstar-roles` | 角色正文 hub |
 | `mstar-host` | 宿主适配（自动识别；`references/opencode.md` / `cursor.md` / `codex.md` / `parallel-dispatch.md`） |
 
@@ -114,7 +114,7 @@ Read **`mstar-host`** after this skill; detect host per its table, then Read the
 - 业务仓默认功能分支（Assignment `Branch policy` 例外）→ **`mstar-branch-worktree`**。
 - **Dev 三角**：`@fullstack-dev` 后端主导；UI → `@frontend-dev`；第二轨 → `@fullstack-dev-2`（`mstar-roles` PM 节）。
 - 工期仅 agent-oriented → **`mstar-plan-conventions`** · effort-estimation。
-- `writing-plans` 落盘 `{PLAN_DIR}`，非 `docs/superpowers/plans/`。
+- plan-writing artifacts land in `{PLAN_DIR}`, not external default plan directories.
 - PM Assignment 键名英文；任务正文可中文；产出/报告默认英文。
 
 ## 库文档（Context7）
@@ -142,6 +142,7 @@ Read **`mstar-host`** after this skill; detect host per its table, then Read the
 | iteration-start commit before review chain | `mstar-iteration` §1.6；PM 模拟三角色编辑而不派发 Task |
 | Phase 3 折叠进 final plan closure / 跳过 §3.1 gate | `mstar-iteration` §3.0–§3.5；`iteration-drive` Phase 3 |
 | iteration-close 无 frontmatter completed / 漏 compound Phase 6 | `mstar-iteration` §3.0.5、§3.4、§3.2 #5 |
+| iteration 默认 `main` 作 base 或 PR 目标 | `mstar-iteration` §1.2、§2.3；`mstar-plan-conventions` Spec 分支模型 |
 
 ## 可选：OpenViking Memory
 

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

@@ -13,9 +13,9 @@
 | **`clarify` 核心纪律** | 逐方面核对至共享理解；沿设计决策树逐枝、一次一决；能探索代码库则先探索；每问带推荐答案 | **`mstar-phase-gates`** SKILL.md（含 Phase Gate Playbook） |
 | **按任务类别选能力与模型** | 视觉/深读/快改/硬逻辑等用不同强项 | `mstar-harness-core` SKILL.md「Task category」；Assignment 字段 **`Task category`**；宿主侧按角色配置 model（如 OpenCode 的 `opencode.json`） |
 | **可验证编辑** | 减少「凭记忆 Patch」导致的漂移与损坏 | `mstar-phase-gates` SKILL.md「可验证编辑与上下文纪律」：读后再改、失败则重读 |
-| **持续推进与可核对完成** | 长任务有清单、有关门证据，避免空转 | `mstar-superpowers-align` 的 `verification-before-completion`；PM 对 `tasks`/Phase Gate 的拉回 |
+| **持续推进与可核对完成** | 长任务有清单、有关门证据，避免空转 | `mstar-phase-gates` / `mstar-review-qc`；实现侧自检见 `mstar-coding-behavior` |
 | **编码行为约束（轻量）** | 降低静默假设、过度设计与无关改动 | `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-branch-worktree`；`mstar-review-qc`；`mstar-superpowers-align` **`using-git-worktrees`** |
+| **并行与边界** | 多线任务不踩同一写归属、不绕过分支门禁；**开发**阶段同仓多可写并发须独立 **`git worktree`**；**QC / QA** 在 **同一检出**（`Review cwd`）与 **同一 `plan_id` + `Review range` / `Diff basis`** 上审查与验证，保证三票同一功能 | `mstar-branch-worktree`；`mstar-review-qc`；`mstar-dispatch-gates` |
 | **分层上下文（可选）** | 大仓库用目录级 `AGENTS.md` 降噪；根 `AGENTS.md` 维护边界见下文专节 | `mstar-harness-core` SKILL.md「分层上下文」；由业务项目维护者按需添加 |
 | **结构化澄清（按宿主）** | 向用户澄清/抉择时，**有 `question` 类能力则优先**；否则结构化正文；长问兜底 | `mstar-phase-gates` SKILL.md Prepare · `clarify`；当前宿主的 `mstar-host` skill；`mstar-roles` · `project-manager` |
 
@@ -71,6 +71,6 @@
 ## 延伸阅读
 
 - 按能力选配 MCP/skills：OpenCode → `mstar-host` `references/opencode.md`；其它宿主见 `mstar-host` 检测表
-- Superpowers 与门禁对齐：`mstar-superpowers-align`
+- Evidence and checkpoints: `mstar-phase-gates` / `mstar-review-qc`; implementation self-checks: `mstar-coding-behavior`
 - 库文档检索共享协议：`mstar-harness-core` `references/library-docs-protocol.md`
 - 跨角色编码行为准则（轻量、可复用）：`mstar-coding-behavior`

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

@@ -197,7 +197,7 @@ When `/pm` runs under Plan mode:
 
 ## Related skills
 
-- `mstar-plan-conventions` — discovery, init, `writing-plans` path gate
+- `mstar-plan-conventions` — discovery, init, plan-writing path gate
 - `mstar-plan-artifacts` — `status.json`, reports, checkboxes, residual
 - `mstar-phase-gates` — Prepare / Execute order
 - `mstar-roles/references/project-manager/dispatch-and-assignment.md` — Checkpoint: commit → Completion Report → Status Update

package/harness-skills/mstar-host/references/cursor.md

@@ -61,9 +61,9 @@ Enforcement: `rules/mstar-cursor-plan-mode.mdc` when plugin active.
 - No `question` tool: structured Markdown or Cursor UI.
 - “Question asked” ≠ clarify done; high-impact ambiguity → `Blocked` or escalation.
 
-## Superpowers
+## Execution Discipline
 
-If no Skill invocation tool: `mstar-superpowers-align` “plugin not installed”; **Read** upstream `SKILL.md` before execution.
+Implementation roles use `mstar-coding-behavior` for RCA, test-first checks, review feedback, and completion evidence. Plan checkpoints remain in `mstar-phase-gates`; external skill plugins are not required.
 
 ## Gotchas
 

package/harness-skills/mstar-host/references/opencode.md

@@ -8,7 +8,7 @@ Parallel PM dispatch: **`parallel-dispatch.md`** (read in dispatch rounds).
 
 - **Role shell**: `agents/<id>.md` referenced by `opencode.json` `agent.<id>` (frontmatter + role binding only).
 - **Role body**: `mstar-roles` `references/<id>.md` (or shared references + parameters).
-- Superpowers conflicts: `mstar-superpowers-align`.
+- Implementation evidence and RCA behavior: `mstar-coding-behavior`.
 
 ## OpenCode-specific capabilities
 
@@ -48,7 +48,7 @@ Aligned with `mstar-harness-core` `references/open-harness-principles.md`. Editi
 | **Repo graph** | Impact / PR risk | e.g. GitNexus |
 | **Browser / E2E** | Observable QA evidence | agent-browser, Playwright |
 | **Git workflow** | Atomic commits, branch closure | git-commit, finishing-a-development-branch |
-| **Systematic debugging** | RCA before fix | `mstar-superpowers-align` |
+| **Systematic debugging** | RCA before fix | `mstar-coding-behavior` |
 | **OpenViking memory** | Long-term memory tools | Only if `memsearch` present; `openviking-memory-plugin.md` |
 
 **Not recommended**: overlapping search MCPs; extra tools to mask missing harness baseline.

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

@@ -1,6 +1,6 @@
 ---
 name: mstar-iteration
-description: Morning Star 迭代管理 —— iteration-start（锁定范围、Review & Edit chain 硬门禁）、Autonomous Execute（per-plan 派发循环）、iteration-close（独立 Phase：close gate、compound、roadmap、compass completed）。触发：PM 启动新迭代、跨 plan 编排、或全部 plan Done 后收口。compass：`{ITERATION_DIR}/<iteration-id>-delivery-compass.md`；per-plan SSOT：`{HARNESS_DIR}/status.json`。
+description: Morning Star 迭代管理 —— iteration-start（显式 `iteration_base_branch` / `target_branch`、Review & Edit chain 硬门禁）、Autonomous Execute（per-plan 派发；禁止默认 `main`）、iteration-close（独立 Phase gate）。compass：`{ITERATION_DIR}/`；分支 SSOT：`status.json` metadata + compass frontmatter。
 ---
 
 # mstar-iteration（迭代管理）
@@ -25,10 +25,11 @@ iteration-start → [per-plan lifecycle × N] → iteration-close → PR → mer
      └──────── iteration-drive（跨 plan 追踪）────────┘
 ```
 
-**关键定位**：iteration-close 是 iteration-drive 命令的**最后一个 Phase**，在 integration 分支上执行，**完成后再创建 PR**。所有 compound 产物（knowledge docs、compass 更新、CONCEPTS.md）作为迭代交付的一部分随 PR 合入 main。一次迭代 = 一个 PR。
+**关键定位**：iteration-close 是 iteration-drive 命令的**最后一个 Phase**，在 integration 分支上执行，**完成后再创建 PR**。所有 compound 产物（knowledge docs、compass 更新、CONCEPTS.md）作为迭代交付的一部分随 PR 合入已记录的 `target_branch`。一次迭代 = 一个 PR。
 
 **per-plan 状态 SSOT**：`{HARNESS_DIR}/status.json`（per-plan Todo/InProgress/InReview/Done）。
 **迭代状态 SSOT**：`{ITERATION_DIR}/<id>-delivery-compass.md` frontmatter `status` + `{ITERATION_DIR}/README.md` 索引。
+**迭代分支 SSOT**：root `metadata.iteration_base_branch` + `metadata.target_branch`（`status.json`）；compass frontmatter 镜像同名字段。解析顺序见 §2.3。**禁止**因仓库存在 `main`/`master` 就假定 base 或 PR 目标。
 
 ## 产物存储位置
 
@@ -59,6 +60,9 @@ PM 在新迭代启动时执行。
 | **验收标准** | 迭代级别的 Done 定义 |
 | **非目标** | 明确排除在本次迭代外的事项 |
 | **Roadmap 上下文** | 本迭代在整体 roadmap 中的位置（current iteration / next iteration） |
+| **Delivery branch policy** | `iteration_base_branch`（integration 分支从何处分出）、`spec_integration_branch`、`target_branch`（最终 PR 目标） |
+
+**Branch policy gate**：若用户、现有 roadmap、或项目约定未明确 `iteration_base_branch` / `target_branch`，PM 必须检查当前分支并向用户确认。**不得**因为存在 `main` / `master` 就默认从默认分支开 iteration 或向默认分支提 PR。
 
 ### 1.3 创建迭代 compass
 
@@ -69,6 +73,8 @@ PM 在新迭代启动时执行。
 iteration_id: <id>
 start_date: YYYY-MM-DD
 status: active
+iteration_base_branch: <branch-or-ref>
+target_branch: <branch>
 plans: []
 ---
 
@@ -97,6 +103,14 @@ plans: []
 ## Roadmap Position
 - Current iteration: <what this iteration delivers>
 - Next iteration: <what comes next, owner, trigger>
+
+## Delivery Branch Policy
+
+| Field | Value |
+|-------|-------|
+| iteration_base_branch | <branch-or-ref> |
+| spec_integration_branch | iteration/<iteration-id> |
+| target_branch | <PR target> |
 ```
 
 ### 1.4 更新索引
@@ -107,9 +121,15 @@ plans: []
 |----------|-----------|-------------|--------|
 | `<iteration-id>-delivery-compass.md` | `<iteration-id>` | `<简短描述>` | `active` |
 
-### 1.5 登记到 status.json（可选）
+### 1.5 登记到 status.json（formal iteration 必填）
+
+iteration-start / iteration-drive 正式流程**必须**写入 `{HARNESS_DIR}/status.json`：
+
+- root `metadata.iteration_base_branch` — 创建 `spec_integration_branch` 的祖先 ref（**不是**隐式 `main`）
+- root `metadata.target_branch` — iteration-close 后 PR 的目标分支
+- 各 plan `metadata.iteration_refs`、`spec_integration_branch`、`merge_target`（`merge_target` 通常为 `spec_integration_branch`）
 
-若使用 `status.json`，在 `plans[].metadata` 中为受影响的 plan 设置 `iteration_refs`。
+compass frontmatter 的 `iteration_base_branch` / `target_branch` **必须与** `status.json` 一致；若仅写在 compass 而 status 缺失，§2.3 同轮 backfill。
 
 ### 1.6 Review & Edit chain（integration 分支前强制）
 
@@ -132,13 +152,14 @@ PM **不得**将迭代 harness 文档 commit 到 `spec_integration_branch`，直
 
 **本 Phase 是本 skill 的核心**——定义 per-plan 派发循环的完整流程：前置条件检查、session todos、backlog 读取、integration 分支管理、per-plan dispatch 循环（分支→实现→QC→QA→Done→合并）、dispatch-first 约束、push 纪律。PM 读取本 Phase 即可执行迭代。
 
-### 2.0 前置条件（三道闸）
+### 2.0 前置条件（四道闸）
 
 进入 Autonomous Execute 前必须满足：
 
 1. `{HARNESS_DIR}/status.json` 中至少一条 plan `status` ≠ `Done`
 2. **Pre-implement gate = GO**：plan 已 locked、tasks ready（见 `mstar-phase-gates`）
-3. 用户意图为 **continue Execute**（`/pm`、"推进 iteration"、"继续 plans" 等）
+3. 用户意图为 **continue Execute**（`/pm`、`/iteration-drive`、"推进 iteration" 等）
+4. **Branch metadata gate**：root `metadata.iteration_base_branch`、`metadata.target_branch` 已登记，且至少一条 active plan 有 `metadata.spec_integration_branch`（或可从 compass 同轮 backfill）。**缺失 → STOP**，不得用 `main`/`master` 补位。
 
 任一 false → **stop**。Prepare 未完成 → 引导先跑 `/iteration-start`。
 
@@ -158,15 +179,26 @@ SSOT = `{HARNESS_DIR}/status.json` + `{PLAN_DIR}/`。todos 只追踪本轮下一
 
 1. 读 `mstar-plan-artifacts` + `{HARNESS_DIR}/status.json`
 2. 列出 `status` ∈ `{Todo, InProgress, InReview, Blocked}` 的 plan（优先级：`InProgress` → `InReview` → `Todo` → unblock `Blocked`）
-3. 读 `metadata.spec_integration_branch` / `merge_target` / `primary_spec` 链接
+3. 读 root `metadata.iteration_base_branch` / `metadata.target_branch`，以及 plan `metadata.spec_integration_branch` / `merge_target` / `primary_spec` 链接
 
 ### 2.3 Integration branch
 
-1. 从 `status.json` 解析 `spec_integration_branch`
-2. **checkout 或创建**该分支；`git branch --show-current` 确认
-3. 若 metadata 缺失 → **stop**，读 `mstar-plan-conventions` + 用户确认（`mstar-branch-worktree`）；同轮写入 plan + status
+**Metadata 解析顺序**（任一环节缺失则 STOP，**禁止**默认 `main`/`master`）：
 
-此分支是本迭代内所有 plan feature branch 的 merge target。
+1. `{HARNESS_DIR}/status.json` → `metadata.iteration_base_branch`、`metadata.target_branch`；plan → `metadata.spec_integration_branch`
+2. 若 (1) 缺字段 → 读当前迭代 `{ITERATION_DIR}/<iteration-id>-delivery-compass.md` frontmatter 同名键
+3. 若 compass 有值而 `status.json` 无 → **同轮 backfill** `status.json`
+4. 仍缺 → 向用户确认 base / PR target；**不得**因 `git symbolic-ref refs/remotes/origin/HEAD` 指向 `main` 就自动采用
+
+**Git 操作**：
+
+1. `git fetch`（按需）确认 `iteration_base_branch` 存在
+2. **checkout 或创建** `spec_integration_branch`：
+   - 已存在 → `git checkout <spec_integration_branch>`
+   - 不存在 → `git checkout -b <spec_integration_branch> <iteration_base_branch>`（**必须**从记录的 base 创建，不是从当前未记录的 `main` 检出）
+3. `git branch --show-current` 确认在 `spec_integration_branch`
+
+此分支是本迭代内所有 plan feature branch 的 merge target。QC **`Review range` / `Diff basis`** 的 merge-base 参照优先用 `metadata.target_branch`（或 PM 书面指定的 base ref），**禁止**无 Assignment 依据写死 `origin/main`。
 
 ### 2.4 Per-plan loop（直到全部 Done）
 
@@ -203,7 +235,7 @@ SSOT = `{HARNESS_DIR}/status.json` + `{PLAN_DIR}/`。todos 只追踪本轮下一
 
 ## Phase 3: iteration-close（收口迭代）
 
-PM 在迭代内全部 plan Done 后执行。**本 Phase 在 integration 分支上运行**，产出物 commit 到 integration 分支，随迭代 PR 合入 main。触发方：`commands/iteration-drive.md`（Autonomous Execute 全部 Done 后进入）。
+PM 在迭代内全部 plan Done 后执行。**本 Phase 在 integration 分支上运行**，产出物 commit 到 integration 分支，随迭代 PR 合入 root `metadata.target_branch`。触发方：`commands/iteration-drive.md`（Autonomous Execute 全部 Done 后进入）。
 
 **Close Done 定义**：§3.1→§3.5 全部完成；compass frontmatter 写入 `status: completed` + `end_date`；每篇新增 knowledge doc 已登记 `{KNOWLEDGE_DIR}/README.md`。只在 final plan 中写了 compound / roadmap / PR 说明，不算 iteration-close 完成。
 
@@ -287,6 +319,7 @@ PM 打印 **iteration-close exit checklist**；全部为 `[x]` 后方可 `git co
 - [ ] §3.3 `## Roadmap Position` current iteration 已标 `delivered`；tracker / STRATEGY 已按需更新
 - [ ] §3.4 frontmatter `status: completed` + `end_date`；Compound Summary + Retrospective 已填
 - [ ] 当前分支是 `spec_integration_branch`
+- [ ] PR base = `metadata.target_branch`（与 compass frontmatter 一致）；**不是**未记录的 `main`
 
 **Commit 到 integration 分支**：
 
@@ -296,6 +329,8 @@ git commit -m "chore(iteration): close <iteration-id> — compound round, roadma
 git push origin <spec_integration_branch>
 ```
 
+PR 目标使用 root `metadata.target_branch`；缺失时停止并补齐，不得默认 `main`。
+
 ### 3.6 可选：触发 compound-refresh
 
 若本轮 compound 新增了较多知识文档，或 compass 标记了可能过时的旧知识，触发 `mstar-compound-refresh` 对有重叠的知识文档做维护。
@@ -326,6 +361,7 @@ git push origin <spec_integration_branch>
 - 不要在 iteration-drive 中修改 per-plan gate 判定
 - 不要用 compass 替代 `status.json` 作为 plan 状态 SSOT
 - 不要在没有完成 per-plan 前置检查的情况下进入 iteration-close
+- 不要在缺少 `iteration_base_branch` / `target_branch` 时默认使用 `main` / `master`
 - 不要将 Phase 3 折叠进 final plan closure——须显式 §3.0→§3.5
 - 不要用 prose completion status 替代 compass frontmatter `status: completed` + `end_date`
 - 不要跳过 compound Phase 6（`{KNOWLEDGE_DIR}/README.md` 索引）——即使只结晶一篇文档

package/harness-skills/mstar-iteration/references/iteration-compass-template.md

@@ -7,6 +7,8 @@ Copy this template when creating a new iteration compass in `{ITERATION_DIR}/`.
 iteration_id: <id>
 start_date: YYYY-MM-DD
 status: active
+iteration_base_branch: <branch-or-ref>
+target_branch: <branch>
 plans: []
 ---
 
@@ -53,6 +55,16 @@ Status values: `Todo` | `InProgress` | `InReview` | `Done` | `Blocked`
 - **Next iteration**：<what comes next>，触发条件：<condition>，owner：<who>
 - **最终目标**：<the long-term Done definition this iteration contributes to>
 
+## Delivery Branch Policy
+
+> Mirror of frontmatter; keep in sync with `{HARNESS_DIR}/status.json` `metadata`.
+
+| Field | Value |
+|-------|-------|
+| `iteration_base_branch` | <branch-or-ref integration branch is cut from> |
+| `spec_integration_branch` | <e.g. iteration/<iteration-id>> |
+| `target_branch` | <PR target after iteration-close> |
+
 ## Risk Register
 
 | Risk | Likelihood | Impact | Mitigation |
@@ -84,6 +96,8 @@ Status values: `Todo` | `InProgress` | `InReview` | `Done` | `Blocked`
 | `start_date` | Yes | iteration-start |
 | `end_date` | No | Add at iteration-close §3.4 only |
 | `status` | Yes | iteration-start → `active` / `locked`（§1.6 PM lock）；iteration-close §3.4 → **`completed`**（YAML frontmatter，非 prose completion status） |
+| `iteration_base_branch` | Yes | iteration-start; integration branch must be created from this ref |
+| `target_branch` | Yes | iteration-start; final PR target after iteration-close |
 | `plans` (frontmatter) | Recommended | iteration-start (initial), iteration-drive (add new) |
 | `## Plans` table | Yes | iteration-drive (sync status), iteration-close (final) |
 | `## Milestones` | Recommended | iteration-start, iteration-drive (update) |