@mstar-harness/dsh 3.8.3 → 3.9.1

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

@@ -91,7 +91,7 @@ When **`Execution mode: sdd`** (`mstar-sdd`):
 - **SDD 单 plan 内**：独立 ready tasks 默认并行；每轨先完成 L2 隔离，fresh session 与独立产物路径，PM 唯一写共享 ledger。规则 → **`mstar-sdd`** § Ready-task scheduling。
 - **跨 plan（迭代 Phase 2）≠ 单 plan 内并行**：不同 `plan_id` 的 feature implement **允许** lease 门控并行（每 plan 独立 verified snapshot `plans[].execution_lease` + feature worktree，L1）**仅当** coordination 路径 same-host 独占写锁可用且每次协调变更持锁 → **`mstar-iteration`** §2.0 #5 · **`mstar-artifacts`**。**跨主机 / 无共享 flock** → 默认 **`Plan parallelism: serial`** 或 Assignment 仍写并行 → **Blocked**（用户本轮 `Cross-host lease race: accepted` + audit `notes` 除外）。**无 flock 不豁免** control/feature worktree 或 lease。**`Worktree mode: waived` 不豁免**跨 plan 并行安全闸。**禁止**因默认 gitignore 导致 feature 缺 plans 而 waive worktree（harness 经 control 绝对路径）→ **`mstar-branch-worktree`**。**禁止**无 lease 的跨 plan 可写派发（lease 闸未 waive 时）。
 - **`integration_merge_lease`**：`spec_integration_branch` 上的 merge **始终串行**（一次仅一 holder）→ **`mstar-iteration`** · **`mstar-artifacts`**。
-- **`Plan parallelism: serial`**：仅强制跨 plan implement **调度串行**；**不** waive control worktree / `execution_lease` / `integration_merge_lease`（`Worktree mode: waived` 才是 lease/worktree 豁免）→ **`mstar-iteration`** §2.0 #5。
+- **`Plan parallelism: serial`**：仅强制跨 plan implement **调度串行**；**不** waive worktree/lease 闸（integration worktree、feature worktree、`execution_lease`、`integration_merge_lease`）（`Worktree mode: waived` 才是 lease/worktree 豁免）→ **`mstar-iteration`** §2.0 #5。
 - **Plan QC tri** after SDD task loop（`Execution mode: sdd`）；**单席**仅 `inline` / hotfix。共用 `Review cwd` / `Working branch` / `plan_id` / `Review range`（**`mstar-branch-worktree`**）。
 - **Tri 同消息规则**：plan QC tri（SDD 或 Assignment 显式 `QC mode: full tri-review`）时三席 **同一条消息**、**同一套** scope 字段。
 

package/harness-skills/mstar-engine-legacy/references/lease-protocol.md

@@ -1,10 +1,12 @@
 # Lease claim protocol (full prose, archived)
 
 > Engine-absent fallback: the full lease protocol prose displaced from `mstar-iteration` / `mstar-artifacts` when engine validators (`validateExecutionLease` / `validateIntegrationMergeLease` / CLI `mstar lease verify --workflow <id>`) took over the same contract. Engine-present hosts read the runtime skills' engine-check pointers instead.
+>
+> **v1 field note:** snapshot key `control_worktree_path` is **v1-historical** — a read-alias only. The canonical snapshot member is **`integration_worktree_path`** (the dedicated integration checkout on `branch.integration`, distinct from the main worktree). `readWorkflowSnapshot` normalizes the alias in memory with a medium diagnostic (`workflow.snapshot.legacy-control-worktree-path`); canonical writers reject the old key. The **control root** (process-SSOT holder) is the **primary checkout / main worktree**, derived from Git — not a snapshot field.
 
 ## When it applies
 
-**Iteration Phase 2 only** (after control-worktree entry, or primary checkout when `Worktree mode: waived`). Defaults are **hard** unless the current turn explicitly waives via Assignment `Worktree mode: waived` (or equivalent user instruction). `Plan parallelism: serial` is **not** a waiver — it only forces serial cross-plan **implement** scheduling while control worktree + leases remain required. Phase 1 Review & Edit may stay on the primary checkout; the control-worktree gate starts at **Phase 2 entry**. **`Worktree mode: waived` does not waive the cross-plan parallel safety gate**.
+**Iteration Phase 2 only** (after integration-worktree entry). Defaults are **hard** unless the current turn explicitly waives via Assignment `Worktree mode: waived` (or equivalent user instruction). `Plan parallelism: serial` is **not** a waiver — it only forces serial cross-plan **implement** scheduling while the worktree + lease gates remain required. Phase 1 Review & Edit may edit uncommitted docs on the primary checkout under the Prepare policy; the integration-worktree gate starts at **Phase 2 entry**. **`Worktree mode: waived` does not waive the cross-plan parallel safety gate**.
 
 ## Coordination SSOT and lock discipline
 
@@ -16,11 +18,12 @@ Lease mutations happen on the **control copy** of the coordination file — the
 - Manual fallback when no engine writer exists: atomic `mkdir` on `{WORKFLOW_DIR}/<id>/.status-write.lockdir/` — success acquires; existing dir → **Blocked** (another writer holds the lock); `rmdir` the directory only after successful verify or explicit rollback. The dsh notes-ledger writer uses the same lockdir pattern (`{WORKFLOW_DIR}/<id>/.ledger-write.lockdir`). Do **not** invent a distributed CAS CLI.
 
 ```bash
-CONTROL_ROOT="<snapshot top-level control_worktree_path>"
+MAIN_ROOT="<derived main worktree root (control root; Git readMainWorktree)>"
+INTEGRATION_WORKTREE="<snapshot top-level integration_worktree_path>"
 HARNESS=".mstar"   # or resolved {HARNESS_DIR}
 WORKFLOW_ID="<plan-or-iteration-id>"
-SNAPSHOT="$CONTROL_ROOT/$HARNESS/workflows/$WORKFLOW_ID/snapshot.json"
-LOCKDIR="$CONTROL_ROOT/$HARNESS/workflows/$WORKFLOW_ID/.status-write.lockdir"
+SNAPSHOT="$MAIN_ROOT/$HARNESS/workflows/$WORKFLOW_ID/snapshot.json"
+LOCKDIR="$MAIN_ROOT/$HARNESS/workflows/$WORKFLOW_ID/.status-write.lockdir"
 (
   mkdir "$LOCKDIR" || exit 1
   trap 'rmdir "$LOCKDIR"' EXIT
@@ -38,7 +41,7 @@ A Phase 2 session **MUST** claim before moving a plan from `Todo`/`Blocked` to `
 2. **Resume (not steal):** if `execution_lease` exists and `holder` **equals this session** → verify-held: confirm `worktree_path` and `working_branch` match the Assignment; continue (not Blocked, not a new claim).
 3. **Blocked:** if `execution_lease` exists and `holder` **differs** → stop. No timestamp, TTL, or inactivity makes it stealable.
 4. **Orphan:** if `status` is `InProgress` but `execution_lease` is absent → **STOP** (see Orphan recovery). Do not writable-dispatch or invent a lease.
-5. Create or verify the dedicated feature worktree and branch (default `<repoRoot>/.worktrees/<plan-id>-<slug>`; `worktree_path` ≠ `control_worktree_path`).
+5. Create or verify the dedicated feature worktree and branch (default `<repoRoot>/.worktrees/<plan-id>-<slug>`; `worktree_path` ≠ the main worktree (control root) ≠ `integration_worktree_path`).
 6. Acquire the same-host write lock (above); re-read the coordination file; if row/status/lease changed, restart from step 1.
 7. In **one complete-file update** (under lock), set `status: "InProgress"` and write the full `execution_lease` object. Use a temp file in the same directory + atomic replace; never expose partial JSON.
 8. Re-read the stored row; verify `holder`, `worktree_path`, `working_branch` exactly match the attempted claim. Writable dispatch is forbidden until verification succeeds.
@@ -59,14 +62,14 @@ V1: **manual release only** — omit `expires_at`; readers **MUST NOT** treat un
 
 Feature implementation may run in parallel across plan IDs **only when** the cross-plan parallel hard gate is satisfied (same-host lock on the coordination file, default `Plan parallelism: serial`, or current-turn `Cross-host lease race: accepted` + audit — **not** by `Worktree mode: waived` alone); when the lease gate is active, each plan also needs a verified `execution_lease` and distinct feature worktree. Mutations of `spec_integration_branch` are **serial**. Plan status after QC/QA is `InReview` with `execution_lease` retained until merge succeeds (when lease gate active); `Done` + lease deletion happen **after** the integration merge commit is recorded.
 
-1. From `control_worktree_path`: clean working tree; checked-out branch = resolved `spec_integration_branch`.
+1. From the **integration worktree** (`integration_worktree_path`): clean working tree; checked-out branch = resolved `spec_integration_branch`. Never merge from the primary checkout.
 2. Re-read the coordination file under the same-process write lock. If `integration_merge_lease` exists:
-   - **Resume (not steal):** `holder` equals this session → verify `plan_id`, `source_branch`, `target_branch` match the intended merge; confirm control worktree state; continue (not Blocked).
+   - **Resume (not steal):** `holder` equals this session → verify `plan_id`, `source_branch`, `target_branch` match the intended merge; confirm integration worktree state; continue (not Blocked).
    - **Blocked:** `holder` differs → stop. No timestamp, TTL, or inactivity makes it stealable.
 3. If unclaimed, claim the merge lease with the same read-check-replace-verify discipline as execution claims. `source_branch`/`plan_id` must match the feature; `target_branch` must match `spec_integration_branch`.
-4. Only the stored merge-lease holder runs integration from `control_worktree_path`.
+4. Only the stored merge-lease holder runs integration from `integration_worktree_path`.
 5. On success: record merge commit/evidence; **delete** `integration_merge_lease`; in the **same** locked update set plan `status: "Done"` and **delete** `execution_lease`.
-6. On conflict/failure: retain both leases; plan stays `InReview` — do not set `Done`. Release the merge lease only after the control worktree is clean and in a known state.
+6. On conflict/failure: retain both leases; plan stays `InReview` — do not set `Done`. Release the merge lease only after the integration worktree is clean and in a known state.
 
 Execution and merge leases may coexist; the merge lease does not grant execution ownership for the source plan.
 

package/harness-skills/mstar-engine-legacy/references/status-field-history.md

@@ -83,7 +83,7 @@ Closed residual entries added: `lifecycle`, `closed_at`, `closure_note`; optiona
 | --- | --- | --- | --- |
 | `holder` | non-empty string | Yes | Opaque cooperative owner identity (recommended `<host>:<stable-session-id>`, e.g. `cursor:bc-1234`); stable for claim lifetime; **no credentials**; used for ownership comparison — not `session_label`. |
 | `claimed_at` | RFC 3339 UTC (`Z`) | Yes | Acquisition time (audit only; **not** an expiry clock). |
-| `worktree_path` | absolute path string | Yes | Dedicated feature-worktree root; **MUST** differ from `metadata.control_worktree_path`. |
+| `worktree_path` | absolute path string | Yes | Dedicated feature-worktree root; **MUST** differ from `metadata.control_worktree_path` (v1-historical name; canonical snapshot member = `integration_worktree_path`). |
 | `working_branch` | non-empty string | Yes | Feature branch at `worktree_path`; MUST agree with Assignment `Working branch`. |
 | `session_label` | string | No | Human display only — **MUST NOT** authorize or compare ownership. |
 
@@ -99,7 +99,7 @@ Writers **delete** `execution_lease` on release; `null` and tombstone objects ar
 | `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# (engine `techDebtRollup`). |
-| `control_worktree_path` | absolute path string | Iteration Phase 2: canonical repository root checked out to active `spec_integration_branch`; coordination + serial merge cwd. |
+| `control_worktree_path` | absolute path string | **v1-historical (read-alias)**. Iteration Phase 2: canonical repository root checked out to active `spec_integration_branch`; coordination + serial merge cwd. Canonical snapshot member = **`integration_worktree_path`** (dedicated integration checkout, distinct from the main worktree); `readWorkflowSnapshot` normalizes the old key in memory with a medium diagnostic — canonical writers reject it. |
 | `integration_merge_lease` | object | While one integration merge is owned; **absent** = unclaimed. Writers **delete** the key on release — never `null`/tombstones. |
 
 ## v1 residual entry contract (9 required fields + severity/lifecycle)
@@ -163,7 +163,7 @@ Legacy read paths (root `residual_findings` / `metadata.residual_findings` / `ar
 | root `plans[]` rows | `{WORKFLOW_DIR}/<id>/snapshot.json` → `plans[]` (legacy PlanRow shape verbatim) |
 | root `plans[].execution_lease` | snapshot plan row `execution_lease` |
 | root `metadata.integration_merge_lease` | snapshot top-level `integration_merge_lease` |
-| root `metadata.control_worktree_path` | snapshot top-level `control_worktree_path` |
+| root `metadata.control_worktree_path` | snapshot top-level `integration_worktree_path` (v1 key is a read-alias; canonical writers emit only the new name) |
 | root `metadata.iteration_base_branch` / `target_branch` / `spec_integration_branch` / `merge_target` | snapshot top-level `branch.{base,integration,target}` |
 | root `metadata.plan_parallelism` / `worktree_mode` / `push_policy` | snapshot `execution_policy` |
 | root `metadata.notes` / legacy row `notes` | `{WORKFLOW_DIR}/<id>/notes.jsonl` (runtime ledger; row `notes` kept verbatim as legacy copy) |

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

@@ -10,7 +10,7 @@ Parallel PM dispatch: read **`parallel-dispatch.md`** only when Codex exposes an
 
 - Plugin source: `.codex-plugin/plugin.json`.
 - Runtime skills: repo `skills/` mounted by the Codex plugin (`"skills": "./skills/"`).
-- Custom agent source: repo `codex/agents/*.toml`; CLI/manual install links these into `~/.codex/agents/` or project `.codex/agents/`.
+- Custom agent source: repo `codex/agents/*.toml`; CLI install copies these as regular files into `~/.codex/agents/` or project `.codex/agents/`.
 - **`/pm`** or **`pm` skill**: force PM entry → `mstar-roles` → `project-manager.md` (Codex primary; Cursor/OpenCode for general per-plan work). **`commands/`** when running iteration Phase 1–5; project CLI install (`mstar-harness init --target codex --scope project`) materializes `iteration-start`, `iteration-drive`, and `iteration-loop` as `.agents/skills/<name>/SKILL.md` symlinks.
 - Role files under root `agents/` are for hosts that load OpenCode/Cursor-style agent shells; Codex uses `codex/agents/*.toml` and still loads `mstar-roles` references directly.
 - Tool and plugin availability can be lazy-loaded or session-dependent. Use the tools actually present in the current session; do not infer capability from documentation alone.
@@ -35,9 +35,11 @@ Use skill names in prompts and references. Avoid absolute local paths unless the
 
 ## Dispatch and role execution
 
-- **No invoke tool / no linked custom agent = no dispatch**: printing `## Assignment` does not start another Codex worker.
-- If Codex exposes custom-agent / multi-agent tools and matching Morning Star agents are linked, PM may dispatch through those tools and must follow `parallel-dispatch.md`.
+- **No invoke tool / no available custom agent = no dispatch**: printing `## Assignment` does not start another Codex worker.
+- If Codex exposes custom-agent / multi-agent tools and matching Morning Star agents are available, PM may dispatch through those tools and must follow `parallel-dispatch.md`.
 - If no invoke tool is present when dispatch is required, return **`Blocked`** — report missing invoke capability to the user. Do not substitute single-session role execution in the PM thread unless the user explicitly overrides harness dispatch for this turn.
+- Bind the role using the actual invoke schema. For example, when `collaboration.spawn_agent` exposes `agent_type`, set `agent_type: "fullstack-dev"` for `Execute as: fullstack-dev`; do not guess another host's parameter name.
+- Discovery does not prove loading: an advertised role may still fail to start. Record the actual invocation error; a role-load failure is not a missing-tool failure. For installed TOML issues, use `mstar-harness doctor --target codex --scope <global|project>` and repair via `init` for that scope, then retry the named role. Claim dispatch only after a successful invocation.
 - QC: N rules → **`parallel-dispatch.md`** (**`Execution mode: sdd`** → N=3; **`inline`** → N=1) when a callable invoke tool exists. Cannot emit required **N** → **`Blocked`**.
 - Leaf executors still follow `mstar-dispatch-gates`: no recursive Task/subagent calls unless Assignment says `Delegation: allowed (...)`.
 
@@ -56,6 +58,6 @@ Use skill names in prompts and references. Avoid absolute local paths unless the
 
 ## Gotchas
 
-- Codex plugin install gives skills; Morning Star role subagents require custom agent TOML files linked from `codex/agents/`.
+- Codex plugin install gives skills; Morning Star role subagents require regular custom agent TOML files installed from `codex/agents/`.
 - Tool discovery (`tool_search`) can reveal capabilities, but availability is not authorization; Assignment `Delegation` still controls use.
 - Session plans, Goal Mode text, chat summaries, and UI todos are not durable harness SSOT unless mirrored to `{HARNESS_DIR}`.

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

@@ -53,7 +53,7 @@ or a custom profile).
   rides it), and the pinned **meta dock** (version + harness dir; never
   scrolls). The workspace-state digest (plans ≤5 time-desc + `+N more`,
   open residual findings ≤10 with severity chips + overflow hint, policy
-  with **enforcement first** then push / worktree / control worktree,
+  with **enforcement first** then push / worktree / integration worktree,
   leases, knowledge, direction) renders IN FLOW at the end of the scroll
   body, closed by the freshness footer (`snapshot {time} · turn {turn}` —
   the served snapshot's own timestamp + turn, never "live"). The three

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

@@ -1,6 +1,6 @@
 ---
 name: mstar-iteration
-description: "Use when starting, driving, resuming, or closing a Morning Star iteration, or running an autonomous Phase 1–5 loop — including without a slash command (e.g. 'start an iteration', 'drive the iteration', 'run an autonomous loop'). Manages Phase 1 (default interactive direction lock; opt-in autonomous), Autonomous Execute, iteration-close (compound promotes knowledge), PR delivery, and the PR merge-ready loop. Branch SSOT: workflow snapshot (`workflows/<id>/snapshot.json`) + compass frontmatter."
+description: "Use when starting, driving, resuming, or closing a Morning Star iteration, or running an autonomous Phase 1–6 loop — including without a slash command (e.g. 'start an iteration', 'drive the iteration', 'run an autonomous loop'). Manages Phase 1 (default interactive direction lock; opt-in autonomous), Autonomous Execute, iteration-close (compound promotes knowledge), PR delivery, the PR merge-ready loop, and the Phase 6 post-merge close. Branch SSOT: workflow snapshot (`workflows/<id>/snapshot.json`) + compass frontmatter."
 ---
 
 # mstar-iteration（迭代管理）
@@ -15,7 +15,7 @@ description: "Use when starting, driving, resuming, or closing a Morning Star it
 
 mstar 实践模式通常是：一次迭代锁定几个 spec 点（`specify + clarify`），产生多个 `plan`，每个 plan 含多个 tasks。**per-plan 生命周期有完整的闭环**（Prepare → Execute → QC → Done）。Compound 不是 per-plan 活动——它是**迭代级收口**，在迭代内所有 plan Done 后，沉淀一轮知识。
 
-本 skill 管理迭代 **Phase 1–5**（command 层可聚合编排，但 **不得**反向引用 command 名；第三方 helper 仅由 command 按需发现）：
+本 skill 管理迭代 **Phase 1–6**（command 层可聚合编排，但 **不得**反向引用 command 名；第三方 helper 仅由 command 按需发现）：
 
 ```
 Phase 1: start
@@ -28,6 +28,8 @@ Phase 4: PR delivery（开 PR）
      ↓
 Phase 5: PR merge-ready loop —— 至 mergeable + CI 全绿 + reviews resolved
      ↓
+Phase 6: post-merge close —— PR merged 后 §6.1–§6.4
+     ↓
 迭代交付完成
 ```
 
@@ -35,6 +37,7 @@ Phase 5: PR merge-ready loop —— 至 mergeable + CI 全绿 + reviews resolved
 
 - **Phase 3** 在 integration 分支收口 compound / roadmap；**开 PR（Phase 4）≠ 迭代交付完成**。
 - **Phase 5** 是 **merge-ready loop**（修复 → 等 CI/review 波次结束再 push → 再验证，至 §5.5 exit）；**Loop 理念与 push cadence SSOT 在本 skill**（§2.6；push cadence 细则 §5.1a → `references/phase-4-5-pr-delivery.md`）；宿主 command 可叠加额外 **non-`mstar-*`** helper（**优先** `babysit` / `*-babysit`；**`greploop` 可选**），但不写入 `mstar-*` load order。
+- **Phase 6** 是 **post-merge close**（PR **merged** 后 §6.1–§6.4：terminal snapshot → unregister → 投影对齐 → cleanup（`mstar worktree cleanup`，dry-run 默认；守卫契约本体 → `mstar-branch-worktree`「Worktree / branch cleanup」））；**§5.5 exit / PR mergeable ≠ 生命周期已关闭**（`references/phase-6-post-merge-close.md`）。
 - 一次迭代 = 一个 PR；compound 产物随 PR 合入 snapshot `branch.target`。
 
 ## Phase route map（唯一路由表 — 按当前动作加载）
@@ -42,9 +45,10 @@ Phase 5: PR merge-ready loop —— 至 mergeable + CI 全绿 + reviews resolved
 | 当前动作 | 必读 detail（按需加载，勿通读） |
 |---------|--------------------------------|
 | **start**（启动迭代 / 重开方向锁定） | **`references/phase-1-prepare.md`**（§1.1–§1.6：上下文、范围与 direction lock、compass、索引、v2 状态面、产物边界、§1.6 Review & Edit 链） |
-| **execute / resume**（推进或恢复 per-plan 循环） | **`references/phase-2-worktree-lease.md`**（§2.0 五道闸、§2.1–§2.5 loop/dispatch 细则、control worktree + lease 全文） |
+| **execute / resume**（推进或恢复 per-plan 循环） | **`references/phase-2-worktree-lease.md`**（§2.0 五道闸、§2.1–§2.5 loop/dispatch 细则、control root + integration worktree + lease 全文） |
 | **close**（全部 plan Done 后收口迭代） | **`references/phase-3-iteration-close.md`**（§3.0–§3.6：entry checklist、compound、roadmap、完成标记、exit checklist + commit） |
 | **PR / merge-ready**（开 PR、推进合并就绪 loop） | **`references/phase-4-5-pr-delivery.md`**（§4–§5.2：开 PR、§5.1a push cadence、loop、exit checklist） |
+| **Phase 6 / post-merge close**（PR merged 后关闭 lifecycle） | **`references/phase-6-post-merge-close.md`**（entry（verified merged）+ §6.1 terminal write → §6.2 unregister → §6.3 projection reconciliation → §6.4 cleanup：`mstar worktree cleanup`，dry-run 默认，`--apply` 才变更） |
 | **Phase 5 helper discovery**（仅 command 层按需） | **`references/phase5-helper-discovery.md`**（babysit / greploop 发现） |
 
 一次只加载当前 route 一行；phase 切换按下方 **Phase transition gates** 走。
@@ -53,20 +57,21 @@ Phase 5: PR merge-ready loop —— 至 mergeable + CI 全绿 + reviews resolved
 
 | 边界 | 触发 | 必须 | 禁止 |
 |------|------|------|------|
-| **→ Phase 2**（entry / resume） | §2.0 五道闸全过（细则 → `references/phase-2-worktree-lease.md`） | 继续 Autonomous Execute per-plan loop（phase-2 reference §2.4） | 五道闸任一 false 仍派发；branch metadata 缺失用 `main`/`master` 补位 |
-| **→ Phase 3** | workflow snapshot（`workflows/<id>/snapshot.json`）中 compass 登记的全部 plan 均为 `Done` | 打印 `## Phase 3: iteration-close`；执行 §3.0→§3.5（`references/phase-3-iteration-close.md`）；host todo `phase-3-iteration-close` 保持 open 直至 §3.5 | 开 PR；宣称迭代交付完成；仅依赖 final plan closure |
+| **→ Phase 2**（entry / resume） | §2.0 五道闸全过（细则 → `references/phase-2-worktree-lease.md`） | 继续 Autonomous Execute per-plan loop（phase-2 reference §2.4）；主 worktree 驻留 = 记录的 **`Main worktree branch`**，integration 分支检出在专属 integration worktree | 五道闸任一 false 仍派发；branch metadata 缺失用 `main`/`master` 补位；把生命周期分支切到主 checkout |
+| **→ Phase 3** | workflow snapshot（`workflows/<id>/snapshot.json`）中 compass 登记的全部 plan 均为 `Done` | 打印 `## Phase 3: iteration-close`；执行 §3.0→§3.5（`references/phase-3-iteration-close.md`）；host todo `phase-3-iteration-close` 保持 open 直至 §3.5；close commit 在 **integration worktree** 执行 | 开 PR；宣称迭代交付完成；仅依赖 final plan closure；在主 checkout 上 commit close 产物 |
 | **→ Phase 4** | §3.5 exit checklist 全 `[x]`；frontmatter `status: completed` + `end_date` | 打印 `## Phase 4: PR delivery`；开 PR 到 snapshot `branch.target`（§4 → `references/phase-4-5-pr-delivery.md`） | 跳过 §3.1 entry checklist 或 compound Phase 6 |
 | **→ Phase 5** | Phase 4 PR 已创建 | 打印 `## Phase 5: PR merge-ready`；执行 §5 loop 至 §5.5 exit（含 §5.1a push cadence） | 开 PR 后停止；跳过 review resolve / CI loop；**CI/AI review 仍在跑时 push** |
-| **→ 迭代交付完成** | §5.5 exit checklist 全 `[x]` | PR mergeable；required CI 全绿；reviews resolved | Phase 4 开 PR 即宣称完成 |
+| **→ Phase 6** | PR **已 merge**（verified merged；mergeable ≠ merged，由 PM 核实） | 打印 `## Phase 6: post-merge close`；按 §6.1→§6.4 执行（`references/phase-6-post-merge-close.md`）；todo `phase-6-post-merge-close` 保持 open 直至 §6.4 | mergeable 即视为 merged；未核实 merge 就调用 close；§6.1–§6.3 之间夹带 tracked commit |
+| **→ 迭代交付完成** | Phase 6 §6.1–§6.4 完成（`references/phase-6-post-merge-close.md`） | snapshot `completed` + `ended_at`；根 `status.json` 条目注销（`mstar status workflow-close --workflow <id>` exit 0）；投影一致 | §5.5 exit 或 PR merge 即宣称交付完成；为 close 释放 lease 或伪造 Done/关闭 residual |
 | **start → integration branch** | §1.6 Review & Edit chain（`references/phase-1-prepare.md`） | 三角色按序 invoke；**specs** 为主产出；**禁止** start 链向 `{KNOWLEDGE_DIR}/` 新增；writing-specialist corpus hygiene + compass `status: locked` | PM 代做专业编辑；并行三角色；product/architect 写 knowledge；临时笔记进 specs |
 
 > **Engine check (when available):** run `mstar iteration gate --workflow <id> --compass <delivery-compass.md> --branch "$(git branch --show-current)" --integration <spec_integration_branch> --target <target_branch>` (or `import { evaluatePhaseGate } from "@mstar-harness/engine"` with the `currentBranch` / `specIntegrationBranch` / `prBaseBranch` probe inputs in a host hook) to evaluate the transition gate above against the workflow snapshot — the branch probes cover §3.5 exit item 5 (`EXIT_BRANCH_MISMATCH` when the commit checkout is not on `spec_integration_branch`; verify **before** the §3.5 close commit, not after). On `fail` (gate-blocking violations) -> do not proceed; fix and re-run. Note: during the Phase-3 window (`transition: phase-3-close`) the gate exits 1 until the §3.4 close items (`status: completed` + `end_date`) are written — that exit-1 is the expected "close work pending" signal (the exit checklist gates Phase 4, not the Phase-3 entry), so proceed with Phase 3 per the table below. Skill text below remains authoritative when the runtime is absent.
 
 **误判信号**：对话里出现 compound 摘要、roadmap 更新、或「所有 plan 已完成」但 **未** 打印 §3.1 / §3.5 checklist → 视为 **Phase 3 未执行**，回到 `references/phase-3-iteration-close.md` §3.0。
 
-**per-plan 状态 SSOT**：`{WORKFLOW_DIR}/<id>/snapshot.json` 的 `plans[]` 行（per-plan Todo/InProgress/InReview/Done）；根 `{HARNESS_DIR}/status.json` `workflows[]` 登记活跃 lifecycle。
+**per-plan 状态 SSOT**：`{WORKFLOW_DIR}/<id>/snapshot.json` 的 `plans[]` 行（per-plan Todo/InProgress/InReview/Done）；根 `{HARNESS_DIR}/status.json` `workflows[]` 登记活跃 lifecycle。Phase 6 close 后 snapshot 终态（`completed` + `ended_at`）保留为归档，根条目注销（removal-at-terminal；`references/phase-6-post-merge-close.md` §6.1–§6.2）。
 **迭代状态 SSOT**：`{ITERATION_DIR}/<id>/delivery-compass.md` frontmatter `status` + `{ITERATION_DIR}/README.md` 索引（一行 = 一次迭代）。
-**迭代分支 SSOT**：snapshot `branch.base`（= `iteration_base_branch`）+ `branch.target`（= `target_branch`）与 `branch.integration`（= `spec_integration_branch`）（`workflows/<id>/snapshot.json`）；compass frontmatter 镜像同名字段。解析顺序见 phase-2 reference §2.3。**禁止**因仓库存在 `main`/`master` 就假定 base 或 PR 目标。
+**迭代分支 SSOT**：snapshot `branch.base`（= `iteration_base_branch`）+ `branch.target`（= `target_branch`）与 `branch.integration`（= `spec_integration_branch`）（`workflows/<id>/snapshot.json`）；compass frontmatter 镜像同名字段。解析顺序见 phase-2 reference §2.3。**禁止**因仓库存在 `main`/`master` 就假定 base 或 PR 目标。**`branch.base` 是创建/merge 锚点，不是驻留事实**——主 worktree（control root）驻留分支在生命周期写入前由 PM 记录为主 plan 头的 **`Main worktree branch`**，全程不切换；integration 分支检出在专属 integration worktree（snapshot `integration_worktree_path`）。
 
 ## 产物存储位置
 
@@ -97,7 +102,7 @@ Phase 5: PR merge-ready loop —— 至 mergeable + CI 全绿 + reviews resolved
 
 - **`mstar-compound`** — iteration-close 中触发知识结晶（**唯一**默认 knowledge 新增路径）
 - **`references/phase-1-prepare.md`** — start route detail（§1.1–§1.6）
-- **`references/phase-2-worktree-lease.md`** — execute/resume route detail（per-plan loop + control worktree、`execution_lease`、`integration_merge_lease`）
+- **`references/phase-2-worktree-lease.md`** — execute/resume route detail（per-plan loop + integration worktree、`execution_lease`、`integration_merge_lease`）
 - **`references/autonomous-direction-lock.md`** — §1.2 autonomous direction lock、scale budget、branch resolve
 - **`references/iteration-artifact-boundaries.md`** — Phase 1 specs / iteration package / knowledge 分工
 - **`references/iteration-corpus-hygiene.md`** — §1.6 writing-specialist specs 卫生细则
@@ -107,16 +112,17 @@ Phase 5: PR merge-ready loop —— 至 mergeable + CI 全绿 + reviews resolved
 共享反递归红线全清单见 **`mstar-roles/references/_shared/leaf-executor-core.md`**「Shared anti-recursion NEVER」。迭代级高频陷阱（其余各 Phase 内已含对应 hard rule）：
 
 - **不要将 Phase 4 开 PR 等同于迭代交付完成** — 必须完成 Phase 5 §5.2 merge-ready loop
+- **不要将 §5.5 exit 或 PR merge 当作生命周期终点** — merged 后必须进入 Phase 6（`references/phase-6-post-merge-close.md` §6.1–§6.4）；禁止为通过 close 释放 lease 或伪造 Done/关闭 residual
 - **不要在 Phase 5 CI 仍跑或 AI review 波次未结束时 push**（§5.1a）— 本地可提前修，push 等 idle
-- **不要为 Phase 5 另开 feature/fix worktree**，也不要把 Phase 2 control 产品编辑禁令套到 Phase 5 — 直接在集成分支 checkout 上修
+- **不要在 integration worktree 或主 checkout（control root）上直接编辑产品代码** — Phase 5 修复走 fix feature worktree，review 后 merge 回 integration worktree（`phase-4-5-pr-delivery.md` §5.0）
 - **不要在缺 `iteration_base_branch` / `target_branch` 时默认 `main` / `master`**
 - **不要在 Phase 1 §1.6 由 product/architect 向 `{KNOWLEDGE_DIR}/` 新增**（知识 → iteration-close **`mstar-compound`**）
 - **不要在 per-plan Done 后立即 compound** — 等 iteration-close 统一做
 
 ## Workflow
 
-Phase 1–5 总览见上文 **`## 设计思路`** 图。执行时按 **`## Phase route map`** 选当前动作的一行 detail：`start`（范围 + compass + §1.6 Review & Edit 链）→ `Autonomous Execute`（五道闸 → §2.4 per-plan 循环：分支 → 实现 → QC → QA gate → Done → 串行 merge）→ `iteration-close`（§3.1–§3.5 + `mstar-compound`）→ `PR delivery`（Phase 4）→ `PR merge-ready loop`（Phase 5 至 §5.5 exit）。每波用 §2.1 session todos 设护栏防范围漂移；phase 切换以上方 **Phase transition gates** 为准。
+Phase 1–6 总览见上文 **`## 设计思路`** 图。执行时按 **`## Phase route map`** 选当前动作的一行 detail：`start`（范围 + compass + §1.6 Review & Edit 链）→ `Autonomous Execute`（五道闸 → §2.4 per-plan 循环：分支 → 实现 → QC → QA gate → Done → 串行 merge）→ `iteration-close`（§3.1–§3.5 + `mstar-compound`）→ `PR delivery`（Phase 4）→ `PR merge-ready loop`（Phase 5 至 §5.5 exit）→ `post-merge close`（Phase 6，PR merged 后 §6.1–§6.4）。每波用 §2.1 session todos 设护栏防范围漂移；phase 切换以上方 **Phase transition gates** 为准。
 
 ## Evidence
 
-迭代交付完成 = Phase 5 §5.5 exit checklist 全 `[x]` + PR mergeable + required CI 全绿 + reviews resolved。Phase 3 完成标志 = compass frontmatter `status: completed` + `end_date`（§3.4）+ §3.5 exit checklist。close 证据在磁盘产物（compass / plans / specs 修订 + 索引 + metadata），不要求单独迭代审查报告（§1.6，`references/phase-1-prepare.md`）。
+迭代交付完成 = Phase 5 §5.5 exit checklist 全 `[x]` **且 PR merged 已核实** **且 Phase 6 §6.1–§6.4 完成**（snapshot `completed` + `ended_at`、根 `status.json` 条目注销、投影一致；`references/phase-6-post-merge-close.md`）。Phase 3 完成标志 = compass frontmatter `status: completed` + `end_date`（§3.4）+ §3.5 exit checklist。close 证据在磁盘产物（compass / plans / specs 修订 + 索引 + metadata），不要求单独迭代审查报告（§1.6，`references/phase-1-prepare.md`）。

package/harness-skills/mstar-iteration/references/command-shared-invariants.md

@@ -17,7 +17,7 @@ Phase 2–5 全程有效（drive + loop 共有的行）：
 | Write/Edit/Shell 产品代码、写测试、跑 QC（Phase 2） | 每条 implement/QC/QA Assignment ⇒ **1 次 `Task`** |
 | **多 task plan 用 inline 大包派发**（整份 plan / T1–Tn 贴进一个 dev Assignment） | **SDD**：`mstar-sdd` per-task 循环 — `mstar sdd task-brief` → implementer → `mstar sdd review-package` → task reviewer → `progress.md` |
 | 只写 Assignment 就进入下一 gate | 同轮 dispatch：每条 Assignment ⇒ **1 次 invoke**（`Subagent invokes issued: N`，N = Assignment 条数） |
-| 最后一个 plan `Done` 后直接开 PR / 汇报结束 | **Phase 3 → 4 → 5** 顺序执行 |
+| 最后一个 plan `Done` 后直接开 PR / 汇报结束；§5.2 exit 或 PR merged 即宣称交付完成 | **Phase 3 → 4 → 5 → 6** 顺序执行（Phase 6 = PR merged 后 post-merge close，`references/phase-6-post-merge-close.md`） |
 | Phase 5 自己改产品代码 | 需改产品代码时 **dispatch** `fullstack-dev` / `ops-engineer` |
 
 派发细则 → **`mstar-dispatch-gates`** + **`mstar-host`**。Phase 3 细则 → **`mstar-iteration/references/phase-3-iteration-close.md`** + **`mstar-compound`**。
@@ -48,6 +48,7 @@ if command -v mstar-harness >/dev/null 2>&1; then mstar-harness dispatch validat
 | `phase-3-iteration-close` | 仅剩 1 个非 `Done` plan | Phase 3 §3.5 exit 全 `[x]` |
 | `phase-4-create-pr` | Phase 3 完成后 | PR 已创建并记录 URL/number |
 | `phase-5-pr-merge-ready` | Phase 4 完成后 | Phase 5 §5.5 exit 全 `[x]` |
+| `phase-6-post-merge-close` | §5.2 exit 后 PR **已 merge**（mergeable ≠ merged） | Phase 6 §6.1–§6.4 完成（`mstar status workflow-close --workflow <id>` exit 0 + 投影一致） |
 
 ## Continuous execution STOP list（重叠行；start / drive / loop 共有）
 

package/harness-skills/mstar-iteration/references/phase-1-prepare.md

@@ -152,4 +152,6 @@ Phase 1 与 §1.6 须遵守 **`references/iteration-artifact-boundaries.md`**（
 
 **完成证据** = 磁盘上的 compass / plans / specs / iteration 文档修订 + specs（与既有 knowledge）卫生/归档（如有）+ 索引与 metadata 更新 + compass `status: locked`。**不**要求单独的迭代审查报告——迭代审查的 SSOT 是被编辑的文档本身，无 per-plan QC 式审计链。
 
+**Uncommitted-docs exception（bounded — Phase 1 only）**：Review & Edit 链的文档编辑（compass / plans / specs / `<iteration-id>/` package）可以**未提交**状态落在主 checkout（control root = 主 worktree）——这是 worktree 默认在 Phase 1 的唯一例外，主 checkout 分支**不**切换、不产生 feature commit。**§6 创建 integration worktree 后**：只把**已 review 的本轮文档改动** transfer 到 integration worktree 并在其上 commit（tracked results 写在目标分支所在的检出），随后恢复主 checkout 上对应的未提交文档改动（不切分支）；**禁止**搬运主 checkout 上无关的既有用户改动。
+
 **反模式**：PM 线程代替三角色完成全部编辑而不 invoke；或将本链三角色并行派发 —— 见 **`mstar-roles/references/_shared/leaf-executor-core.md`**「Shared anti-recursion NEVER」。

package/harness-skills/mstar-iteration/references/phase-2-worktree-lease.md

@@ -1,4 +1,4 @@
-# Phase 2: Autonomous Execute — per-plan loop + control worktree + lease
+# Phase 2: Autonomous Execute — per-plan loop + integration worktree + lease
 
 > Loaded by `mstar-iteration` SKILL.md on the **execute / resume** route, and by the Phase 2+ command layer. **Read `mstar-harness-core` first.** Entry = §2.0 五道闸全过；continuous execution / push 纪律（§2.6）的 SSOT 仍在 `mstar-iteration` SKILL.md。
 
@@ -14,14 +14,15 @@ full protocol here.
 **Phase 2**（SKILL.md execute/resume route + `iteration-drive` / `iteration-loop`
 command layer；`iteration-start` ends before this）. Defaults are **hard** unless the current turn
 explicitly waives via Assignment `Worktree mode: waived` (or equivalent user
-instruction). `Plan parallelism: serial` is **not** a waiver — it only forces
-serial cross-plan **implement** scheduling while control worktree + leases remain
+instruction), within the limited scope in § Waiver; main residency and the
+dedicated integration checkout remain mandatory. `Plan parallelism: serial` is **not** a waiver — it only forces
+serial cross-plan **implement** scheduling while the worktree + lease gates remain
 required.
 
-Phase 1 Review & Edit may stay on the primary checkout. The control-worktree gate
+Phase 1 Review & Edit may edit uncommitted docs on the primary checkout under the Prepare policy (bounded exception; the main worktree never switches branch). The integration-worktree + lease gate
 starts at **Phase 2 entry**.
 
-**Phase scope**：本参考仅约束 **Phase 2**（含 serial integration merge 与「control 禁止产品编辑 / 每 plan feature worktree」）。**Phase 5** PR merge-ready 修复 **不**沿用该产品编辑隔离——直接在 control / `spec_integration_branch` 上改，**禁止**另开 Phase 5 fix worktree → **`phase-4-5-pr-delivery.md`** §5.0。
+**Phase scope**：本参考仅约束 **Phase 2**（含 serial integration merge 与「control root / integration worktree 禁止产品编辑 / 每 plan feature worktree」）。**Phase 5** PR merge-ready 修复同样 **不**直接在 integration checkout 上改——产品修复走独立 fix feature worktree，review 后 merge 回 integration worktree → **`phase-4-5-pr-delivery.md`** §5.0。
 
 **本 Phase 定义 per-plan 派发循环的完整流程**：前置条件检查、session todos、backlog 读取、integration 分支管理、per-plan dispatch 循环（分支→实现→QC→**QA gate**→Done→合并）、dispatch-first 约束。PM 读取本 Phase（含 §2.0–§2.5 与下方 lease 细则）即可执行迭代。
 
@@ -35,7 +36,7 @@ starts at **Phase 2 entry**.
 2. **Pre-implement gate = GO**：plan 已 locked、tasks ready（见 `mstar-phase-gates`）
 3. 用户意图为 **continue Autonomous Execute**（推进迭代 Execute、继续 per-plan 循环等）
 4. **Branch metadata gate**：snapshot `branch.base`（`iteration_base_branch`）、`branch.target`（`target_branch`）已登记，且至少一条 active plan 有 `metadata.spec_integration_branch`（或可从 compass 同轮 backfill）。**缺失 → STOP**，不得用 `main`/`master` 补位。
-5. **Control-worktree + lease defaults**（iteration 命令；可被 `Worktree mode: waived` 豁免）：除非本轮 Assignment 显式 `Worktree mode: waived`（或等价用户指令），Phase 2 **必须**在入口建立 control worktree、经 control 路径读写默认 gitignored 的 harness 进程产物（根 `status.json`、`workflows/`、`projects/`、`{PLAN_DIR}`、`{ITERATION_DIR}`、`{SDD_DIR}` 等），并在可写派发前 claim workflow snapshot 的 `plans[].execution_lease` / 顶层 `integration_merge_lease`。可写 Assignment 须含绝对 feature **`Worktree path`** + 绝对 control 系 **`Plan Path`** / **`SDD dir`**（见 **`mstar-branch-worktree`**「Harness path SSOT under default gitignore」）。**禁止**因 feature worktree 在默认 gitignore 下看不到 plans 而推断 `Worktree mode: waived`。`Plan parallelism: serial` **不** waive 本闸——仅强制跨 plan **implement** 串行调度；control worktree + lease 仍须满足。**跨 plan 并行安全闸**（**不可**被 `Worktree mode: waived` 豁免）：跨 plan **并行可写 implement** 须满足下列之一——(a) coordination 路径（control snapshot 或 waived 时主 checkout `{HARNESS_DIR}/status.json`）上 **same-host 独占写锁可用且每次 status/协调变更持锁**；(b) 默认 **`Plan parallelism: serial`**（**waived 时尤其优先默认串行**；**无 flock / 无共享锁时只触发本条，不豁免 worktree**）；(c) 用户本轮显式 `Cross-host lease race: accepted`（或等价）+ `plans[].notes` 审计。**禁止**将 `Worktree mode: waived` 当作跨主机无锁并行的授权。细则 → 下方「Control worktree」「Execution lease」「Multi-plan parallelism」「Waiver」各节。
+5. **Worktree + lease defaults**（iteration 命令；waiver 范围见下方「Waiver」）：所有模式的 Phase 2 **必须**在入口确认 control root（= **主 checkout / main worktree**，进程 SSOT；其驻留分支 = 主 plan 头记录的 **`Main worktree branch`**，且非任何未终结 workflow 的分支）并建立独立 integration worktree、经 control 绝对路径读写默认 gitignored 的 harness 进程产物（根 `status.json`、`workflows/`、`projects/`、`{PLAN_DIR}`、`{ITERATION_DIR}`、`{SDD_DIR}` 等），；未 waive 时在可写派发前 claim workflow snapshot 的 `plans[].execution_lease` / 顶层 `integration_merge_lease`。可写 Assignment 须含绝对 feature **`Worktree path`** + 绝对 control 系 **`Plan Path`** / **`SDD dir`**（见 **`mstar-branch-worktree`**「Harness path SSOT under default gitignore」三域表）。**禁止**因 feature worktree 在默认 gitignore 下看不到 plans 而推断 `Worktree mode: waived`。`Plan parallelism: serial` **不** waive 本闸——仅强制跨 plan **implement** 串行调度；integration worktree + lease 仍须满足（**串行不豁免 worktree**）。**跨 plan 并行安全闸**（**不可**被 `Worktree mode: waived` 豁免）：跨 plan **并行可写 implement** 须满足下列之一——(a) coordination 路径（control root = 主 checkout `{HARNESS_DIR}/` 下 snapshot / `status.json`）上 **same-host 独占写锁可用且每次 status/协调变更持锁**；(b) 默认 **`Plan parallelism: serial`**（**waived 时尤其优先默认串行**；**无 flock / 无共享锁时只触发本条，不豁免 worktree**）；(c) 用户本轮显式 `Cross-host lease race: accepted`（或等价）+ `plans[].notes` 审计。**禁止**将 `Worktree mode: waived` 当作跨主机无锁并行的授权。细则 → 下方「Integration worktree (Phase 2 entry)」「Execution lease」「Multi-plan parallelism」「Waiver」各节。
 
 > **Engine-check（lease verify / verify-integration）唯一规范体：** `mstar-artifacts` `SKILL.md`（Engine check lease 行；standalone 保证同文）。
 
@@ -59,7 +60,7 @@ SSOT = `{WORKFLOW_DIR}/<id>/snapshot.json` + `{PLAN_DIR}/`。todos 只追踪本
 2. 列出 snapshot 中 `status` ∈ `{Todo, InProgress, InReview, Blocked}` 的 plan（优先级：`InProgress` → `InReview` → `Todo` → unblock `Blocked`）
 3. 读 snapshot `branch.base` / `branch.target`，以及 plan `metadata.spec_integration_branch` / `merge_target` / `primary_spec` 链接
 
-## 2.3 Branch anchors + integration branch + control worktree（Phase 2 入口）
+## 2.3 Branch anchors + integration branch + integration worktree（Phase 2 入口）
 
 **Branch anchors 解析顺序**（任一环节缺失则 STOP，**禁止**默认 `main`/`master`）：
 
@@ -69,35 +70,44 @@ SSOT = `{WORKFLOW_DIR}/<id>/snapshot.json` + `{PLAN_DIR}/`。todos 只追踪本
 4. 仍缺 → 向用户确认 base / PR target；**不得**因 `git symbolic-ref refs/remotes/origin/HEAD` 指向 `main` 就自动采用
 5. 所有参与本轮迭代的 active plan **必须**解析到**同一** `spec_integration_branch`；不一致 → **STOP**
 
-**Control worktree（§2.0 #5 未 waive 时 — HARD）**按下方「Control worktree (Phase 2 entry)」checklist 执行（含：若 integration 分支尚不存在，在 control worktree 内 `git checkout -b <spec_integration_branch> <iteration_base_branch>`——**必须**从记录的 base 创建）。
+**Integration worktree（所有模式 — HARD）**按下方「Integration worktree (Phase 2 entry)」checklist 执行（integration 分支不存在时**必须**从记录的 base 创建，命令见下方）。
 
-**Git 操作（无 control worktree 时 — 仅 `Worktree mode: waived`）**：
+**Git 操作（含 `Worktree mode: waived`）**：
 
-1. `git fetch`（按需）确认 `iteration_base_branch` 存在
-2. **checkout 或创建** `spec_integration_branch`（同上）
-3. `git branch --show-current` 确认在 `spec_integration_branch`
+1. 在主 checkout 按需 `git fetch` 确认记录的 `iteration_base_branch` 存在；主 checkout 保持记录分支。
+2. 用 `git worktree add <integration-path> <spec_integration_branch>` 建立独立 integration checkout；分支不存在时用 `git worktree add -b <spec_integration_branch> <integration-path> <iteration_base_branch>`。
+3. `git -C <integration-path> branch --show-current` 确认 integration 分支；后续 merge 仅在该 checkout。waiver 仅豁免每 plan feature worktree 默认，不豁免 integration 协调 checkout；产品写入仍须避开主 checkout 和 integration checkout。
 
 `spec_integration_branch` 是本迭代内所有 plan feature branch 的 merge target。QC **`Review range` / `Diff basis`** 的 merge-base 参照优先用 snapshot `branch.target`（或 PM 书面指定的 base ref），**禁止**无 Assignment 依据写死 `origin/main`。
 
-## Control worktree (Phase 2 entry)
+## Integration worktree (Phase 2 entry) + control root
 
 1. Resolve all active plans' `metadata.spec_integration_branch` to the **same**
    integration branch (STOP if mismatch).
-2. Resolve or create the **control worktree** (usually primary checkout or
-   PM-designated path) checked out to that `spec_integration_branch`.
-3. Verify `git branch --show-current` equals `spec_integration_branch`; working
-   tree clean before merge operations.
-4. Record canonical absolute repository-root path in the workflow
-   snapshot top-level `control_worktree_path` (not `{HARNESS_DIR}`; canonicalize symlinks).
-5. Resolve coordination paths from that root (default-gitignored process artifacts live on the **control filesystem**, not as Git blobs):
-   - status register: `<control_worktree_path>/{HARNESS_DIR}/status.json` (v2 root — active workflow entries)
-   - snapshot SSOT: `<control_worktree_path>/{WORKFLOW_DIR}/<id>/snapshot.json` (plan rows + leases + branch anchors)
-   - project register: `<control_worktree_path>/{PROJECT_DIR}/<id>/residuals.json`
-   - plans SSOT: `<control_worktree_path>/{PLAN_DIR}/` (or `<control>/{HARNESS_DIR}/plans/`)
-   - iterations SSOT: `<control_worktree_path>/{ITERATION_DIR}/`
-   - SDD tree: `<control_worktree_path>/{HARNESS_DIR}/sdd/<plan-id>/`
-
-All sessions MUST reread the **control copy** of the workflow snapshot immediately before
+2. Resolve the **control root** = the **primary checkout** (main worktree) via
+   Git (`readMainWorktree`); verify its attached branch equals the recorded
+   **`Main worktree branch`** from the main plan header and is not owned by any
+   non-terminal workflow — mismatch → **STOP** (never switch main; never
+   substitute `branch.base`).
+3. Create the dedicated **integration worktree**:
+   `git worktree add <path> <spec_integration_branch>` (create the branch from
+   the recorded base first if absent) — a linked checkout **distinct from the
+   main worktree**; never reuse the primary checkout for integration.
+4. Verify `git -C <integration> branch --show-current` equals
+   `spec_integration_branch`; working tree clean before merge operations.
+5. Record canonical absolute repository-root path in the workflow snapshot
+   top-level `integration_worktree_path` (not `{HARNESS_DIR}`; canonicalize
+   symlinks). The main worktree is **not** recorded in the snapshot — it is
+   derived from Git every session.
+6. Resolve coordination paths from the **control root** (default-gitignored process artifacts live on the **main-worktree filesystem**, not as Git blobs):
+   - status register: `<main-repo-root>/{HARNESS_DIR}/status.json` (v2 root — active workflow entries)
+   - snapshot SSOT: `<main-repo-root>/{WORKFLOW_DIR}/<id>/snapshot.json` (plan rows + leases + branch anchors)
+   - project register: `<main-repo-root>/{PROJECT_DIR}/<id>/residuals.json`
+   - plans SSOT: `<main-repo-root>/{PLAN_DIR}/`
+   - iterations SSOT: `<main-repo-root>/{ITERATION_DIR}/`
+   - SDD tree: `<main-repo-root>/{HARNESS_DIR}/sdd/<plan-id>/`
+
+All sessions MUST reread the **control-root copy** of the workflow snapshot immediately before
 claim, release, transfer, plan-status transition, or merge-lease mutation.
 
 **Do not** set `Worktree mode: waived` because a feature worktree lacks
@@ -121,11 +131,11 @@ distributed CAS CLI.
 **Cross-plan parallel hard gate:** Applies **whether or not** `Worktree mode: waived`.
 Lease-gated **cross-plan parallel** writable implement is allowed **only when**
 this same-host lock is **available on the coordination snapshot path and
-used for every coordination mutation** in that Phase 2 session (control path
-when lease gate active; primary checkout `{HARNESS_DIR}/status.json` + snapshot
-when waived). Agents on **different hosts** or with **no shared flock/lockdir** →
+used for every coordination mutation** in that Phase 2 session (the snapshot
+under the **control root** = the primary checkout / main worktree — waived
+included). Agents on **different hosts** or with **no shared flock/lockdir** →
 default **`Plan parallelism: serial`** (preferred when waived). **No flock
-does not waive** control worktree / feature worktree / leases — serial
+does not waive** the integration worktree / feature worktree / leases — serial
 scheduling only. Assignment still
 claiming cross-plan parallel without lock availability → **Blocked** until PM
 sets serial scheduling or the user gives current-turn override
@@ -147,7 +157,7 @@ mismatch → **STOP**.
 
 1. **Claim / resume — execution lease**（§2.0 #5 未 waive）：按下方「Execution lease」claim/resume 规则——同 `holder` → resume（校验 `worktree_path` / `working_branch` 与 Assignment 一致）；异 `holder` → **Blocked**；`InProgress` 无 lease → **STOP** 升级（孤儿恢复 → **`mstar-artifacts`**）；verify 通过前 **禁止**可写派发
 2. **Plan start — feature worktree + branch**：创建/校验 dedicated feature worktree（默认 `<repoRoot>/.worktrees/<plan-id>-<slug>`）；Assignment 须含绝对 `Worktree path` + `Working branch`（与 lease 一致）。plan 内多可写并行轨 → **`mstar-branch-worktree`** **`references/parallel-writable-pre-dispatch.md`**
-3. **Implement → InReview**（产品编辑在 feature worktree；plans / snapshot / iterations / SDD 经 control 绝对路径）：
+3. **Implement → InReview**（产品编辑在 feature worktree；plans / snapshot / iterations / SDD 经 control root 绝对路径）：
    - **默认 `Execution mode: sdd`**（多 task plan；hotfix 可 `inline`）。
    - PM 载入 **`mstar-sdd`** 后，按依赖与 ownership 派发 **独立 ready tasks 并行** 的 per-task 循环（**不是**一次派发 dev 做全部 tasks）：
      1. `mstar sdd workspace <plan-id>` → `{SDD_DIR}`
@@ -159,7 +169,7 @@ mismatch → **STOP**.
      7. 放行已满足依赖的 next task；不等待无依赖任务，PM 独占共享 progress / snapshot 写入
    - 每次 Completion Report 后更新 snapshot（`workflows/<id>/snapshot.json`）+ 主 plan
 4. **QC → QA gate**（plan 保持 **`InReview`**；**保留** `execution_lease`）：per-plan 审查链 → **`mstar-sdd`**（L1–L2）+ **`mstar-review-qc/references/review-responsibility-boundaries.md`**（L3 tri / inline 单席；raw reports in `{SDD_DIR}/review/`，durable summary in main plan/snapshot）+ **`QA gate`**（`mandatory` → `qa-engineer`；`pm-acceptance` → PM checklist）。**禁止**在 integration merge 成功前设 `Done` 或删除 `execution_lease`。
-5. **Plan complete — serial merge back**（§2.0 #5 未 waive）：自 **control worktree** claim/resume snapshot 顶层 `integration_merge_lease` → 将 plan feature branch 合并入 `spec_integration_branch`（仅 merge-lease holder；细则 → 下方「Integration merge lease」）→ 记录 merge commit 证据 → 释放 merge lease；**同轮**设 `Done` 并删除 `execution_lease`。merge 失败：保持 `InReview` + 保留 lease，不得标 `Done`。
+5. **Plan complete — serial merge back**（§2.0 #5 未 waive）：自 **integration worktree** claim/resume snapshot 顶层 `integration_merge_lease` → 将 plan feature branch 合并入 `spec_integration_branch`（仅 merge-lease holder；细则 → 下方「Integration merge lease」）→ 记录 merge commit 证据 → 释放 merge lease；**同轮**设 `Done` 并删除 `execution_lease`（此即 owner 的 lease 释放动作），并在**同一 locked update** 内把 `metadata.working_branch` / `metadata.worktree_path` 持久化到该 plan 行（归属生产者义务；语义唯一 home → `mstar-branch-worktree`「Worktree / branch cleanup」Ownership）。merge 失败：保持 `InReview` + 保留 lease，不得标 `Done`。merge 成功即打开该 plan 的**同轮 cleanup 资格**（timing lane 1 → 下方「Same-round plan cleanup」）。
 6. **Cross-plan 进度同步**：更新 `{ITERATION_DIR}/<iteration-id>/delivery-compass.md` 的 `## Plans` 表状态列
 7. **Next plan / parallel wave** 从步骤 1 继续（可并行推进其他已 claim 的 plan；merge 仍排队串行）
 
@@ -169,6 +179,19 @@ mismatch → **STOP**.
 2. 打印 **`## Phase 3: iteration-close`**。
 3. 按 **`references/phase-3-iteration-close.md`** §3.0 起独立执行至 §3.5。final plan 的 Assignment / closure 仅作输入，**不能**替代 Phase 3 gate。
 
+### Same-round plan cleanup（timing lane 1；merge 成功同轮）
+
+integration merge 成功且 plan 行 `Done`、`execution_lease` 已删除的**同一轮**，即可回收该 plan/track 的 feature worktree + 已合并分支 —— **父迭代仍在运行不影响资格**：不存在「父须终结」的一刀切，这是 cleanup 的明确设计而非遗漏。命令与守卫契约本体（ownership、合并证据、refusals、apply 顺序）→ **`mstar-branch-worktree`**「Worktree / branch cleanup」（唯一 home；本节只放 call site）：
+
+```text
+mstar worktree cleanup --workflow <id> [--harness <path>] [--apply] [--worktree <path>]
+```
+
+- 先 dry-run 看 `verdict | kind | ref | reason`（merge 刚完成 → 该 Done 行 eligible）；`--apply` 才变更。lane 1 只清**本地面**（无 `--remote`；远端残留留给 Phase 6）。
+- 分支可能仍被该 Done-child worktree 检出 → apply 内部先移 worktree，再 re-probe / re-plan 删分支（**worktree 移除 ≠ 分支删除**；细则 → 契约本体）。
+- **lease 释放是手工 owner 动作、cleanup 范围外**：上方步骤 5 的 `Done` + `execution_lease` 删除就是 owner 释放动作；cleanup **从不**替 owner 释放任何 lease。standalone plan（无 integration）以 `branch.target` 为证据 base，且须**先 terminal close**。
+- **禁止**为让 cleanup 通过而推进/终结父迭代或改 snapshot 状态；受保护行保持 `refuse` 是正确行为，不是失败。
+
 ## 2.5 Dispatch-first（implement 派发约束）
 
 派发纪律 SSOT → **`mstar-dispatch-gates`** · **`mstar-sdd`** · **`mstar-host/references/parallel-dispatch.md`**。
@@ -195,9 +218,9 @@ Iteration Phase 2 附加：
 
 - Each concurrently active plan uses a **distinct** absolute feature-worktree
   path and dedicated feature branch from `spec_integration_branch`.
-- `execution_lease.worktree_path` MUST differ from
-  `control_worktree_path` (never reuse the control checkout for product
-  edits).
+- `execution_lease.worktree_path` MUST differ from the main worktree (control
+  root) and from snapshot `integration_worktree_path` — never product-edit
+  either the primary checkout or the integration checkout.
 - `Worktree path` MUST appear in the writable Assignment and in the snapshot
   plan row's `execution_lease.worktree_path` before first writable implement dispatch.
 - Product/source edits run from the feature worktree; plans, iterations,
@@ -257,8 +280,8 @@ waived` is in effect — waiver does **not** authorize lockless cross-host paral
 - **Feature implementation** MAY proceed in parallel across **different plan IDs**
   only when **one** of:
   1. Same-host exclusive write lock is available on the coordination
-     snapshot path (control path when lease gate active; primary checkout
-     `{HARNESS_DIR}/status.json` + snapshot when waived) and used for every coordination
+     snapshot path under the **control root** (the primary checkout /
+     main worktree — waived included) and used for every coordination
      mutation in that session; **and** when lease gate is not waived, each plan
      holds a verified, distinct `execution_lease` and feature worktree.
   2. **`Plan parallelism: serial`** (default when waived; preferred default under
@@ -276,18 +299,18 @@ Required shape (v1): `holder`, `claimed_at`, `plan_id`, `source_branch`,
 `target_branch` (= resolved `spec_integration_branch`); optional `session_label`.
 Lives top-level on the snapshot — `{WORKFLOW_DIR}/<id>/snapshot.json`.
 
-1. From control worktree: clean tree; branch = `spec_integration_branch`.
+1. From the **integration worktree** (`integration_worktree_path`): clean tree; branch = `spec_integration_branch`. Never run the merge from the primary checkout.
 2. Under write lock, re-read the snapshot. If `integration_merge_lease` exists:
    - **Same `holder` as this session** → **resume**: verify `plan_id`,
-     `source_branch`, `target_branch` match intended merge; confirm control
+     `source_branch`, `target_branch` match intended merge; confirm integration
      worktree state; continue (not steal/block).
    - **Different `holder`** → **Blocked** (cannot expire or steal).
 3. If unclaimed, claim merge lease (same read-check-replace-verify as execution claim).
-4. Only merge-lease holder runs integration from `control_worktree_path`.
+4. Only merge-lease holder runs integration from `integration_worktree_path`.
 5. On success: record merge commit/evidence; delete merge lease; set plan
    **`Done`** and delete `execution_lease` in the same locked update.
 6. On conflict/failure: retain leases; plan stays **`InReview`** — do not set
-   `Done`. Release merge lease only after control worktree is clean and known state.
+   `Done`. Release merge lease only after the integration worktree is clean and known state.
 
 Execution and merge leases may coexist; merge lease does not grant execution
 ownership for the source plan.
@@ -297,8 +320,9 @@ ownership for the source plan.
 Explicit `Worktree mode: waived` (or equivalent user instruction) this turn
 waives **only**:
 
-- Control worktree establishment and control-path SSOT routing
-- Per-plan feature worktree defaults
+- Per-plan feature worktree defaults. The dedicated integration coordination
+  checkout remains required; the primary checkout keeps its recorded branch
+  and remains the process-SSOT holder via absolute control-root paths.
 - Snapshot lease claim/hold/release defaults (`plans[].execution_lease` and top-level `integration_merge_lease`)
 
 It does **not** waive the **cross-plan parallel safety gate**. Under waiver,
@@ -309,7 +333,7 @@ snapshot plan `notes` / `notes.jsonl`. **Prefer serial scheduling when waived**;
 only with the race-accepted override (or same-host lock when mutating shared
 state).
 
-`Plan parallelism: serial` does **not** waive control worktree or leases.
+`Plan parallelism: serial` does **not** waive the worktree or lease gates.
 
 Iteration commands MUST NOT infer waiver from missing worktrees or single-session
 starts. Explicit override this turn only.

package/harness-skills/mstar-iteration/references/phase-3-iteration-close.md

@@ -2,7 +2,7 @@
 
 > Loaded by `mstar-iteration` SKILL.md when entering Phase 3. **Read `mstar-harness-core` first.** Phase 2 全部 plan `Done` 后按 **Phase transition gates** 进入本 Phase。
 
-PM 在迭代内全部 plan Done 后执行。**本 Phase 在 integration 分支上运行**，产出物 commit 到 integration 分支，随迭代 PR 合入 snapshot `branch.target`（`target_branch`）。入口：Phase 2 全部 plan `Done` 后按 **Phase transition gates** 进入。
+PM 在迭代内全部 plan Done 后执行。**本 Phase 在 integration worktree（snapshot `integration_worktree_path`，检出 `spec_integration_branch` 的专用检出）中运行**，产出物 commit 到 integration 分支，随迭代 PR 合入 snapshot `branch.target`（`target_branch`）。入口：Phase 2 全部 plan `Done` 后按 **Phase transition gates** 进入。
 
 **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 完成。
 
@@ -80,13 +80,13 @@ PM 打印 **iteration-close exit checklist**；全部为 `[x]` 后方可 `git co
 - [ ] 当前分支是 `spec_integration_branch`
 - [ ] PR base = snapshot `branch.target`（`target_branch`，与 compass frontmatter 一致）；**不是**未记录的 `main`
 
-**Commit 前提（HARD — branch-anchored，防递交到控制分支）**：§3.5 的 commit 是 **branch 锚定**的——`git commit` 落在**当前检出分支**，`<spec_integration_branch>` 只出现在 push 参数里。当控制 worktree（或任一检出）不在 integration 分支时，未经下述核对直接执行本配方，compound 会把 tracked 的 `{KNOWLEDGE_DIR}/`、`{SPECS_DIR}/`、`CONCEPTS.md` 递交到控制分支（如 `main`），integration 分支的 PR 永远带不上这些 shared 产物。因此 **任何 `git add` 之前**必须先验分支；mismatch → **STOP**（不得 commit、不得 push、不得「先提交后挪」），改在正确检出上重做（见下）。
+**Commit 前提（HARD — branch-anchored，防递交到主 checkout 驻留分支）**：§3.5 的 close commit **在 integration worktree（`integration_worktree_path`）中执行，**绝不**在主 checkout（control root）或任一 feature worktree 上执行**——`git commit` 落在**当前检出分支**，`<spec_integration_branch>` 只出现在 push 参数里。当执行 commit 的检出不在 integration 分支时，未经下述核对直接执行本配方，compound 会把 tracked 的 `{KNOWLEDGE_DIR}/`、`{SPECS_DIR}/`、`CONCEPTS.md` 递交到主 checkout 驻留分支（如 `main`），integration 分支的 PR 永远带不上这些 shared 产物。因此 **任何 `git add` 之前**必须先验分支；mismatch → **STOP**（不得 commit、不得 push、不得「先提交后挪」），改在正确检出上重做（见下）。
 
 1. 解析 `<spec_integration_branch>`：snapshot `branch.integration`（workflows/<id>/snapshot.json）→ 缺失时 compass frontmatter `spec_integration_branch`；仍缺 → STOP 补齐，不得默认 `main`。
 2. **先验后提交**（在执行 commit 的检出处）：`git branch --show-current` === `<spec_integration_branch>`。§3.2–§3.4 产生的 tracked close 产物本就应处于未提交状态等待本 commit，**不要求**此处工作树干净。engine 可用 → 在 add/commit **前**运行 `mstar iteration gate --workflow <id> --compass <delivery-compass.md> --branch <current> --integration <spec_integration_branch> --target <target_branch>` 并确认 exit 无 `EXIT_BRANCH_MISMATCH` / `EXIT_PR_BASE_MISMATCH`（Phase-3 窗口预期的其它 exit-1 除外，见 Phase transition gates 注）。
-3. **mismatch 时**：不产生任何提交。tracked 子树（`{KNOWLEDGE_DIR}/`、`{SPECS_DIR}/`、`CONCEPTS.md`、迭代 package 中 tracked 部分）在**检出 `<spec_integration_branch>` 的 worktree** 重新写入或在 commit 前恢复（它们默认 tracked、随 Git 分支走；进程产物 plans/iterations/status/sdd 经 control 绝对路径不受影响）。然后重跑本 checklist。
+3. **mismatch 时**：不产生任何提交。tracked 子树（`{KNOWLEDGE_DIR}/`、`{SPECS_DIR}/`、`CONCEPTS.md`、迭代 package 中 tracked 部分）在 **integration worktree**（检出 `<spec_integration_branch>` 的专用检出）重新写入或在 commit 前恢复（它们默认 tracked、随 Git 分支走；进程产物 plans/iterations/status/sdd 经 control root 绝对路径不受影响）。然后重跑本 checklist。
 
-**在 `<spec_integration_branch>` 检出上执行**：
+**在 integration worktree（`integration_worktree_path`，检出 `<spec_integration_branch>`）中执行 —— never the primary checkout**：
 
 ```bash
 git branch --show-current   # must print <spec_integration_branch> — mismatch → STOP, see above