@mstar-harness/opencode 0.7.4 → 0.7.5

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（摘要）
 
@@ -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 各对应 **一条**分支快照与 **一套**对齐字段。
@@ -140,7 +140,7 @@ description: Morning Star business-repo Git feature branches, same-repo concurre
 - **`@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-harness-core/SKILL.md

@@ -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-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) |

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

@@ -104,7 +104,7 @@ description: Morning Star (启明星) Spec-Driven 双阶段门禁 —— Prepare
 
 per-plan 门禁通过后，PM 在**迭代层面**管理以下活动（不计入 per-plan gate）：
 
-- **迭代启动**（`mstar-iteration` § Phase 1 iteration-start）：锁定迭代范围（本迭代包含哪些 plan）、里程碑、验收标准，产出 `{ITERATION_DIR}/<iteration-id>-delivery-compass.md`。
+- **迭代启动**（`mstar-iteration` § Phase 1）：锁定迭代范围、**显式 branch policy**（`iteration_base_branch` / `target_branch`）、产出 compass。
 - **迭代驱动**（`mstar-iteration` § Phase 2 Autonomous Execute）：per-plan 派发循环（分支→实现→QC→QA→Done→合并），跨 plan 进度追踪，更新 compass 中各 plan 状态。
 - **迭代收口**（`mstar-iteration` § Phase 3 iteration-close）：迭代内所有 plan Done 后，执行一轮知识结晶（`mstar-compound`）沉淀迭代经验，更新 roadmap，标记迭代完成。
 

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

@@ -39,7 +39,7 @@
 - **After `Request Changes` (default — targeted re-review)**：PM maps each **blocking** finding to the QC seat that raised it (`source` on R#, consolidated table, or the originating `qcN.md` / `F-###`). Dispatch **only** those reviewers (`QC re-review: targeted — reviewers: qc-specialist, qc-specialist-2, …`). Each re-reviewing QC **updates the same** `qc1.md` / `qc2.md` / `qc3.md` in place (add `## Revalidation`, refresh verdict / `generated_at`); **do not** add `qc1-rev2.md` siblings on this path. PM **updates the same** `qc-consolidated.md` in place. Git history is the audit trail.
 - **Full tri re-review (exception)**：Only when Assignment states **`QC re-review: full tri-review`**. Run **three** parallel reviews again; use **new basenames** (`qc1-rev2.md` … `qc3-rev2.md`, `qc-consolidated-rev2.md`) so wave-1 files stay immutable; PM states **active wave** in consolidated decision. See `mstar-review-qc` · `mstar-dispatch-gates`.
 - **显式例外**：仅当用户与 PM 书面同意**中间门禁**时，在 Assignment 写清 **`QC gate: incremental — <scope>`**（或等价），并仍须保证该次三审的 **`plan_id` + `Review range` / `Diff basis`** 三份一致；**优先**用子范围子目录，避免与终局 `qc1..3.md` 混名。
-- **同仓多 worktree 并行 dev**：**推荐**在排各 batch / 各轨 worktree 前确立 **plan 集成分支** 与各轨 topic 线及 **merge 靶**（见 `mstar-branch-worktree` **「推荐默认编排：先建 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 路径覆盖未合并的其他并行轨。
+- **同仓多 worktree 并行 dev**：**推荐**在排各 batch / 各轨 worktree 前确立 **plan 集成分支** 与各轨 topic 线及 **merge 靶**（见 `mstar-branch-worktree` **「推荐默认编排：先建 plan 集成分支，再挂各 worktree」**）。**多 `plan_id` 同属一条 `primary_spec`（Spec 文档）时**：该「集成分支」在计划语义上即 **Spec 集成分支**；各 Plan 的 topic 分支 **merge 回 Spec 集成分支**，**全部 Plans 完成后** 向显式 `target_branch` **走 PR**，见 `mstar-plan-conventions` SKILL.md **「Spec 驱动的分支模型」**。终局（或增量）三审派单前，PM 仍须满足 **单一待审 `Working branch` / `HEAD`** 或已按上条 **拆 scope**；**不得**假设「整 plan 一次三审」可只靠某一个开发 worktree 路径覆盖未合并的其他并行轨。
 
 ### 多 `plan_id` 同时 `InReview`（PM 编排）
 

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

@@ -109,8 +109,8 @@ In old JSON, **`"severity": "warning"`** is read and rolled up as **`low`**. **F
 | Key | Type | Purpose |
 | --- | --- | --- |
 | `working_branch` | string | Implementation branch; aligns with Assignment **`Working branch`** (SSOT) |
-| `spec_integration_branch` | string | (Multi-plan same **Spec**) integration branch name; plan branches merge here before `main` (`mstar-plan-conventions`) |
-| `merge_target` | string | Next merge target; multi-plan + Spec → usually `spec_integration_branch`; `main` via PR |
+| `spec_integration_branch` | string | (Multi-plan same **Spec**) integration branch name; created from root `metadata.iteration_base_branch`; plan branches merge here before final PR (`mstar-plan-conventions`) |
+| `merge_target` | string | Next merge target; multi-plan + Spec → usually `spec_integration_branch`; final PR target is root `metadata.target_branch` |
 | `branch_policy` | string | One-line policy per `mstar-harness-core` |
 | `phase` | string | Program/roadmap label |
 | `priority` | `high` \| `medium` \| `low` | PM scheduling |
@@ -152,10 +152,31 @@ Legacy string `plans[].notes` is OK; new repos should use arrays with time + eve
 | Key | Type | Purpose |
 | --- | --- | --- |
 | `versioning` | object | Cross-plan conventions (team-defined) |
+| `iteration_base_branch` | string | Branch/ref used to create `spec_integration_branch`; required for formal iterations |
+| `target_branch` | string | Final PR target after iteration-close; required for formal iterations |
 | `notes` | array | **Legacy** — prefer **`{HARNESS_DIR}/notes.json`** |
 | `residual_findings_history` | object | **Legacy** — prefer **`archived/residuals/<plan-id>.json`** |
 | `tech_debt_summary` | object | Optional rollup over open R#; maintain via script (below) |
 
+**Formal iteration example** (root `metadata`; values are project-specific — **do not** copy `main` by default):
+
+```json
+"metadata": {
+  "iteration_base_branch": "release/1.76",
+  "target_branch": "release/1.77"
+}
+```
+
+Plan row (per active iteration plan):
+
+```json
+"metadata": {
+  "spec_integration_branch": "iteration/v1.77-live-teels",
+  "merge_target": "iteration/v1.77-live-teels",
+  "iteration_refs": ["v1.77"]
+}
+```
+
 ## General constraints
 
 - Each `plans[]` row may include optional **`metadata`** (`{}` or omit).

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

@@ -1,6 +1,6 @@
 ---
 name: mstar-plan-conventions
-description: Morning Star (启明星) harness 计划目录约定 —— `{HARNESS_DIR}` / `{PLAN_DIR}` / `{ITERATION_DIR}` / `{KNOWLEDGE_DIR}` / `{SPECS_DIR}` 发现与初始化（默认 `.mstar/`，兼容 `.agents/`）、`docs/` 与 harness 子树边界、未启用 plan 时的工作方式、Spec 集成分支与多 Plan 实现分支（merge 靶与 PR 合 main）、Morning Star plan-writing path gate、工期预估（agent-oriented）。**必须**在读写 `.mstar/` / `.agents/`、初始化 harness、编排含 plan 的任务、或对齐 `metadata.primary_spec` 时 Read；`@project-manager` 开 plan 任务前必读。plan 文件 / status / residual / reports / knowledge → **`mstar-plan-artifacts`**；分支与 QC 检出 → **`mstar-branch-worktree`**。
+description: Morning Star (启明星) harness 计划目录约定 —— `{HARNESS_DIR}` / `{PLAN_DIR}` / `{ITERATION_DIR}` / `{KNOWLEDGE_DIR}` / `{SPECS_DIR}` 发现与初始化（默认 `.mstar/`，兼容 `.agents/`）、`docs/` 与 harness 子树边界、未启用 plan 时的工作方式、Spec 集成分支与多 Plan 实现分支（显式 base / merge 靶 / PR target）、Morning Star plan-writing path gate、工期预估（agent-oriented）。**必须**在读写 `.mstar/` / `.agents/`、初始化 harness、编排含 plan 的任务、或对齐 `metadata.primary_spec` 时 Read；`@project-manager` 开 plan 任务前必读。plan 文件 / status / residual / reports / knowledge → **`mstar-plan-artifacts`**；分支与 QC 检出 → **`mstar-branch-worktree`**。
 ---
 
 ## Load order（必读顺序）
@@ -58,11 +58,14 @@ PM 在需要持久化追踪时：
 
 ## Spec 驱动的分支模型（多 Plan · 同一 Spec）
 
-- **Spec 集成分支**：各 Plan 实现 merge 回此线后再视为 Spec 在代码侧集成。
+- **Iteration base branch**：创建 Spec/iteration 集成分支的祖先分支或 ref；必须显式记录，不能默认 `main` / `master`。
+- **Spec 集成分支**：从 `iteration_base_branch` 创建；各 Plan 实现 merge 回此线后再视为 Spec 在代码侧集成。
 - **Plan 实现分支**：每 `plan_id` 一条（PM 书面）。
-- **合入 `main`**：全部 Plans 完成后 **必须 PR**（窄例外见 Assignment `Branch policy`）。
+- **PR target**：全部 Plans 与 iteration-close 完成后，向显式 `target_branch` 提 PR（窄例外见 Assignment `Branch policy`）。
 - Git 操作与 QC 单一 `HEAD` → **`mstar-branch-worktree`**。
-- `status.json` 登记 `spec_integration_branch` / `merge_target` → **`mstar-plan-artifacts`**。
+- `status.json` 登记 root `metadata.iteration_base_branch` / `metadata.target_branch`，以及 plan `metadata.spec_integration_branch` / `merge_target` → **`mstar-plan-artifacts`**。
+
+**解析顺序**（`mstar-iteration` §2.3）：`status.json` metadata → compass frontmatter → 向用户确认。**禁止**因仓库默认分支名为 `main`/`master` 就自动采用。
 
 ## Plan-Writing Path Gate
 

package/harness-skills/mstar-roles/references/project-manager/dispatch-and-assignment.md

@@ -82,10 +82,10 @@ The **`**You are a leaf executor. You MUST NOT:**`** section (previously just pr
 - Prepare: `specify` [done|n/a], `clarify` [done|n/a], `plan` [done|n/a]
 - Execute: `plan locked` [done|n/a], `tasks` [done|n/a], `implement` [this assignment|done]
 - Gate decision: `go` | `blocked` (<reason>)
-**Working branch**: <branch policy or create-from policy>
+**Working branch**: <branch policy or create-from policy> — formal iteration: from `metadata.spec_integration_branch`; integration cut from `metadata.iteration_base_branch` (`mstar-iteration` §2.3)
 **Review cwd / Worktree path**: <absolute path or N/A>
 **plan_id**: <plan-id or N/A + scope label>
-**Review range / Diff basis**: <reproducible basis; identical across QC/QA for same scope>
+**Review range / Diff basis**: <reproducible basis; merge-base = `metadata.target_branch` or PM-specified ref — not assumed `origin/main`>
 **Worktree path**: <implementer path if used>
 **QA note**: <PM-scheduled / skipped / self-check>
 **Why this agent**: <role-fit>

package/harness-skills/mstar-roles/references/project-manager/qc-and-residuals.md

@@ -8,7 +8,7 @@ Use this reference when PM is dispatching QC, consolidating review verdicts, or
 1. Dispatch three independent QC assignments.
 2. Collect reports and verify alignment fields:
    - `plan_id`
-   - `Review range / Diff basis`
+   - `Review range / Diff basis` — use `metadata.target_branch` or PM-specified base ref for merge-base; **do not** assume `origin/main` in formal iterations (`mstar-iteration` §2.3)
    - `Review cwd / Worktree path`
    - `Working branch`
 3. Verify runtime identity/model mapping for three distinct QC roles.

package/harness-skills/mstar-roles/references/project-manager.md

@@ -134,7 +134,7 @@ If any fail -> do not dispatch implement.
 
 ### PM entry sessions (`/pm` or OpenCode PM switch)
 
-When the session entered via **`/pm`**, **`pm` skill**, or OpenCode PM orchestration, follow **`skills/pm/SKILL.md`** — especially **Host entry**, **Autonomous Execute driver** (status.json backlog, `spec_integration_branch`, per-plan feature branches), and **Dispatch-first**. Routing, gates, Task Board, QC, and templates remain in this file and topic `mstar-*` skills.
+When the session entered via **`/pm`**, **`pm` skill**, or OpenCode PM orchestration, follow **`skills/pm/SKILL.md`** — especially **Host entry**, **iteration branch policy**（`iteration_base_branch` / `spec_integration_branch` / `target_branch`）, **Autonomous Execute**（status.json backlog, per-plan feature branches）, and **Dispatch-first**. Routing, gates, Task Board, QC, and templates remain in this file and topic `mstar-*` skills.
 
 ---
 

package/harness-skills/pm/SKILL.md

@@ -60,6 +60,18 @@ Before §6 Integration Branch, print **`iteration-start` pre-commit checklist**
 - 每篇新增 compound doc 必须完成 `mstar-compound` Phase 6（`{KNOWLEDGE_DIR}/README.md`）。
 - compass 完成形式：frontmatter `status: completed` + `end_date` + `## Roadmap Position` current iteration `delivered`——prose completion status 不算。
 
+## iteration branch policy（start + drive）
+
+| 字段 | 含义 | 禁止 |
+|------|------|------|
+| `iteration_base_branch` | 创建 `spec_integration_branch` 的祖先 ref | 未记录时假定 `main` |
+| `spec_integration_branch` | plan feature 分支 merge 靶 | 从当前 checkout 随意开枝 |
+| `target_branch` | iteration-close 后 PR 目标 | 未记录时 PR 到 `main` |
+
+- **iteration-start**：grill-me / §6 与用户锁定；写入 compass frontmatter + `status.json` `metadata`。
+- **iteration-drive**：§2.0 #4 + §2.3 执行前校验；创建 integration 分支必须用记录的 base。
+- QC `Review range` merge-base：用 `target_branch` 或 PM 书面 ref（`mstar-iteration` §2.3），禁止无依据写死 `origin/main`。
+
 ## Cursor Plan mode
 
 CreatePlan / SwitchMode: Read **`mstar-host/references/cursor-plan-mode-bridge.md`**. Bootstrap todos `harness-init` → `spec-register` → `mirror-plan` before implement todos; evidence on **subagent** work.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mstar-harness/opencode",
-  "version": "0.7.4",
+  "version": "0.7.5",
   "description": "Morning Star harness OpenCode plugin (skills bootstrap and agent loading).",
   "license": "MIT",
   "repository": {