@mstar-harness/opencode 1.3.2 → 1.5.0

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

@@ -0,0 +1,163 @@
+# Kimi host reference
+
+Load when **`mstar-host`** detection resolves **kimi** (Kimi Code CLI session, `.kimi-plugin/plugin.json` plugin installed, `Agent` / `AgentSwarm` / `AskUserQuestion` / `EnterPlanMode` tools, or `/morning-star-harness:*` plugin commands).
+
+Plan mode: read **`kimi-plan-mode-bridge.md`** when `EnterPlanMode` / `ExitPlanMode`, `/plan`, or `kimi --plan` is active.
+
+Parallel PM dispatch: read **`parallel-dispatch.md`** when dispatching **N ≥ 2** concurrent `Agent` invocations.
+
+## Kimi-only context
+
+- Plugin manifest: **`.kimi-plugin/plugin.json`** (plugin root is the **repo root**; paths stay `./skills/` and `./commands/`).
+- Runtime skills: repo `skills/` mounted by the plugin (`"skills": "./skills/"`).
+- Plugin commands: repo `commands/` → `/morning-star-harness:<name>` (e.g. `/morning-star-harness:iteration-start`).
+- **`sessionStart.skill: pm`** auto-loads the PM entry shim on new sessions; `pm` → **Read next** → `mstar-harness-core` → `project-manager.md`.
+- **`/skill:pm`** or **`pm` skill**: same PM entry when invoked manually.
+- Install (user-scoped): in Kimi TUI `/plugins install https://github.com/btspoony/mstar-harness` then `/plugins reload` (or `/new`).
+- Plugins are **user-scoped** (all projects); managed copy lives under `$KIMI_CODE_HOME/plugins/managed/` after `/plugins install`.
+- Project `.agents/skills/` symlinks are **not** required when using the plugin — commands and skills come from the plugin mount.
+
+## Skill loading
+
+1. On session start: `pm` (via `sessionStart.skill`) → **Read next** loads `mstar-harness-core`, then `mstar-roles` → `project-manager.md` when PM is active.
+2. Read `mstar-host` and this Kimi reference.
+3. If Plan mode is active, read `kimi-plan-mode-bridge.md`.
+4. Load `mstar-roles` and the active role reference.
+5. Load topic skills on demand per the role reference.
+
+Use skill names in prompts and references. Avoid absolute local paths unless maintaining this repository or skills are not installed.
+
+## Tools map (default agent)
+
+| Kimi tool | Harness use |
+|-----------|-------------|
+| **Agent** | Primary dispatch — delegate one subagent task (`subagent_type`: `coder` \| `explore` \| `plan`) |
+| **AgentSwarm** | Parallel batch when **same** role/profile and prompts differ only by task slice; prefer **N× Agent** when roles differ |
+| **AskUserQuestion** | Structured clarify (1–4 questions, 2–4 options each); prefer over free-form when choices are known |
+| **EnterPlanMode** / **ExitPlanMode** | Plan mode entry/approval → **`kimi-plan-mode-bridge.md`** |
+| **TodoList** | Session UX only; mirror to SSOT plan / `status.json` when durable |
+| **Bash** | Commands, git, tests — evidence per `mstar-coding-behavior` |
+| **Read** / **ReadMediaFile** | File reads |
+| **Glob** / **Grep** | Search (prefer over shell find/grep) |
+| **Write** / **Edit** | Edits |
+| **WebSearch** / **FetchURL** | External docs / facts |
+| **TaskList** / **TaskOutput** / **TaskStop** | Long-running task management when present |
+
+OpenCode-style `question` and Cursor **Task** are **not** Kimi tools — do not assume them.
+
+## Role agents (C5 — hard constraint)
+
+Kimi ships **built-in subagent types only**. Valid **`subagent_type`** values:
+
+| `subagent_type` | Kimi profile | Harness mapping |
+|-----------------|--------------|-----------------|
+| `explore` | Read-only exploration | Orientation, codebase survey, Prepare explore passes |
+| `plan` | Plan-mode subagent | Prepare plan-only work when host is already in plan context |
+| `coder` | General implementation | **All other Morning Star roles** (`product-manager`, `fullstack-dev`, `qc-specialist`, …) |
+
+Morning Star role ids (`project-manager`, `fullstack-dev`, `qc-specialist`, …) are **not** valid `subagent_type` values. The host cannot register custom named agents like Codex TOML or Cursor `subagent_type` role ids.
+
+### Role binding in prompt (C5b — required)
+
+Because Kimi cannot bind roles via agent config, every dispatch **must** carry the played Morning Star role in the **Assignment** and in the **`Agent` prompt**:
+
+1. **`Execute as: <role-id>`** in Assignment (harness routing SSOT).
+2. **`Act as <role-id>`** (or equivalent) at the top of the Agent prompt.
+3. **Skill load list** — instruct the subagent to read `mstar-roles` → `references/<role-id>.md` (or shared reference + parameters) and topic skills per that reference.
+4. **`subagent_type`** — pick from the mapping table above only.
+
+Paste-only Assignment without an **`Agent`** call is **not** dispatch.
+
+### Assignment / Agent-prompt template
+
+```markdown
+## Assignment
+
+**Execute as**: fullstack-dev
+**Delegation**: forbidden
+**Working branch**: feat/example
+**Plan Path**: .mstar/plans/20260717-example.md
+
+**IDENTITY:** You ARE `fullstack-dev`. Act as `fullstack-dev` for this task.
+Load: `mstar-harness-core` → `mstar-host` → `kimi.md` → `mstar-roles` → `references/fullstack-dev-shared.md` → topic skills per that reference.
+
+<task body>
+```
+
+PM dispatch invocation (same turn):
+
+```text
+Agent(
+  subagent_type: "coder",
+  prompt: "<full Assignment body including Act as + skill load>"
+)
+```
+
+For **`explore`** orientation:
+
+```text
+Agent(subagent_type: "explore", prompt: "... Act as explore-only orientation; Execute as: n/a ...")
+```
+
+For Prepare plan-only when plan subagent is appropriate:
+
+```text
+Agent(subagent_type: "plan", prompt: "... Act as architect for plan design; load mstar-roles → architect.md ...")
+```
+
+## PM dispatch (`Agent` / `AgentSwarm`)
+
+Harness **dispatch** on Kimi = **one or more `Agent` tool calls** with correct **`subagent_type`** and role-bound prompts.
+
+| Harness | Kimi |
+|---------|------|
+| `Execute as: <role-id>` | Role id in Assignment + **Act as** + skill load in **Agent** prompt |
+| `subagent_type` for invoke | `coder` \| `explore` \| `plan` only (see mapping) |
+| 1 Assignment ⇒ 1 invoke | **1 `Agent`** call with full Assignment prompt |
+| Parallel batch **N** | **N `Agent`** calls in **one assistant message** when roles may differ; **`AgentSwarm`** only when same role/profile |
+| No `Agent` call | **Not dispatched** — paste-only / `dispatch incomplete` |
+
+### QC default
+
+- **`Execution mode: sdd`**: **N=3** `Agent` calls (`qc-specialist`, `qc-specialist-2`, `qc-specialist-3`) — each prompt **Act as** the respective QC role, all `subagent_type: "coder"`.
+- **`inline`**: **N=1** per `parallel-dispatch.md`.
+
+Cannot emit required **N** → **`Blocked`**.
+
+### SDD implement (serial)
+
+- **`Execution mode: sdd`**: one implementer **`Agent`** per task id; task reviewer = new **`Agent`** (no sticky resume unless host adds it later).
+- **Never** multiple implementer Agents in one message for the same plan.
+
+## Clarify
+
+- Prefer **`AskUserQuestion`** for 1–3 high-impact choices with known options.
+- Fallback: one concise Markdown question after codebase exploration cannot answer it.
+- `AskUserQuestion` for plan approval is wrong in Plan mode — use **`ExitPlanMode`** for plan sign-off.
+- “Question asked” ≠ clarify done; blocking ambiguity → **`Blocked`** or escalation.
+
+## Commands and skills paths
+
+| Surface | Path / invocation |
+|---------|-------------------|
+| Plugin skills | `/skill:<skill-name>` or auto-load from `skills/` via plugin |
+| Plugin commands | `/morning-star-harness:iteration-start` etc. |
+| Session entry | `sessionStart.skill: pm` → `mstar-harness-core` via pm **Read next** |
+
+## Files, shell, and approvals
+
+- Prefer **Glob** / **Grep** for search; **Write** / **Edit** for edits.
+- Respect Kimi approval prompts for destructive operations.
+- Do not edit `$KIMI_CODE_HOME` credentials, managed plugin copies, or user secrets without explicit consent.
+
+## Git and final evidence
+
+- Git work follows `mstar-branch-worktree` and Assignment **Working branch** / **Branch policy**.
+- Completion reports cite concrete commands, artifacts, and commit lines when required.
+
+## Gotchas
+
+- Plugin install copies source to managed dir — edit checkout + reinstall to pick up harness changes.
+- **`AgentSwarm`** shares one template — not for mixed-role QC tri-review; use **3× Agent** instead.
+- Session plan file and `TodoList` are not durable SSOT unless mirrored to `{HARNESS_DIR}`.
+- No custom Kimi agent profiles for Morning Star roles — role binding is **always** prompt + skill load (C5b).

package/harness-skills/mstar-host/references/parallel-dispatch.md

@@ -1,6 +1,6 @@
 # Parallel dispatch (invoke-capable hosts)
 
-Shared PM dispatch contract for **any** host that uses subagent / Task / named-role invoke (OpenCode, Cursor Task, Codex only when a callable multi-agent / Task tool is actually available). Process SSOT also in `mstar-dispatch-gates`.
+Shared PM dispatch contract for **any** host that uses subagent / Task / Agent invoke (OpenCode task tool, Cursor Task, Kimi **Agent** / **AgentSwarm**, Codex only when a callable multi-agent / Task tool is actually available). Process SSOT also in `mstar-dispatch-gates`.
 
 If the active host has no callable invoke tool, this reference does not create delegation capability — mark dispatch **`Blocked`** and report to the user. Do not substitute PM-thread or single-session role execution unless the user explicitly overrides harness dispatch for this turn.
 
@@ -17,7 +17,7 @@ Printing `## Assignment` in the main thread **without** matching host invocation
 
 1. Finalize all `N` Assignment payloads (after any prerequisite turn).
 2. Count distinct `Execute as` sessions (`N`).
-3. Issue **`N` host invocations first** — OpenCode: **N `task` tool** calls with **subagent**; Cursor: **N `Task`** with `subagent_type`; each with one Assignment body. For parallel work, **all `N` tool calls in one assistant message** when the host allows.
+3. Issue **`N` host invocations first** — OpenCode: **N `task` tool** calls with **subagent**; Cursor: **N `Task`** with `subagent_type`; Kimi: **N `Agent`** calls (each prompt carries **Act as** + skill load; `subagent_type` ∈ {`coder`,`explore`,`plan`} only — see `kimi.md` C5/C5b); each with one Assignment body. For parallel work, **all `N` tool calls in one assistant message** when the host allows.
 4. Optionally post a short **Status Update** after invocations (audit trail only — does not replace step 3).
 
 ## Hard rules

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

@@ -7,7 +7,7 @@ description: Morning Star 迭代管理 —— Phase 1（默认 interactive direc
 
 ## Load order
 
-**Read `mstar-harness-core` first.** Path symbols → **`mstar-plan-conventions`**. Per-plan gates → **`mstar-phase-gates`**. Knowledge crystallization → **`mstar-compound`**. **Phase 2 implement 波次**（进入 per-plan implement 前）→ **`mstar-sdd`** + **`mstar-dispatch-gates`**。Phase 2 QC 前 → **`mstar-review-qc`**。On conflict, **`mstar-harness-core` wins**.
+**Read `mstar-harness-core` first.** Path symbols → **`mstar-plan-conventions`**. Per-plan gates → **`mstar-phase-gates`**. Knowledge crystallization → **`mstar-compound`**. **Phase 2 entry**（control worktree + lease）→ **`references/phase-2-worktree-lease.md`** + **`mstar-branch-worktree`**。**Phase 2 implement 波次**（进入 per-plan implement 前）→ **`mstar-sdd`** + **`mstar-dispatch-gates`**。Phase 2 QC 前 → **`mstar-review-qc`**。On conflict, **`mstar-harness-core` wins**.
 
 ## 设计思路
 
@@ -32,7 +32,7 @@ Phase 5: PR merge-ready loop —— 至 mergeable + CI 全绿 + reviews resolved
 **关键定位**：
 
 - **Phase 3** 在 integration 分支收口 compound / roadmap；**开 PR（Phase 4）≠ 迭代交付完成**。
-- **Phase 5** 是 **merge-ready loop**：修复 → push → 再验证，直至 §5.5 exit。**Loop 理念 SSOT 在本 skill**；宿主 command 可叠加额外 helper，但不写入 `mstar-*` load order。
+- **Phase 5** 是 **merge-ready loop**：修复 → push → 再验证，直至 §5.5 exit。**Loop 理念 SSOT 在本 skill**；宿主 command 可叠加额外 **non-`mstar-*`** helper（**优先** `babysit` / `*-babysit`；**`greploop` 可选** — 仅当仓库具备 Greptile/`greploop` 时采用），但不写入 `mstar-*` load order。
 - 一次迭代 = 一个 PR；compound 产物随 PR 合入 `metadata.target_branch`。
 
 ## Phase transition gates（HARD — 防跳步）
@@ -208,7 +208,7 @@ Phase 1 与 §1.6 须遵守 **`references/iteration-artifact-boundaries.md`**（
 
 **本 Phase 是本 skill 的核心**——定义 per-plan 派发循环的完整流程：前置条件检查、session todos、backlog 读取、integration 分支管理、per-plan dispatch 循环（分支→实现→QC→**QA gate**→Done→合并）、dispatch-first 约束、push 纪律。PM 读取本 Phase 即可执行迭代。
 
-### 2.0 前置条件（四道闸）
+### 2.0 前置条件（五道闸）
 
 进入 Autonomous Execute 前必须满足：
 
@@ -216,6 +216,7 @@ Phase 1 与 §1.6 须遵守 **`references/iteration-artifact-boundaries.md`**（
 2. **Pre-implement gate = GO**：plan 已 locked、tasks ready（见 `mstar-phase-gates`）
 3. 用户意图为 **continue Autonomous Execute**（推进迭代 Execute、继续 per-plan 循环等）
 4. **Branch metadata gate**：root `metadata.iteration_base_branch`、`metadata.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 路径读写 `status.json` / `{SDD_DIR}`，并在可写派发前 claim `plans[].execution_lease` / `integration_merge_lease`。`Plan parallelism: serial` **不** waive 本闸——仅强制跨 plan **implement** 串行调度；control worktree + lease 仍须满足。**跨 plan 并行安全闸**（**不可**被 `Worktree mode: waived` 豁免）：跨 plan **并行可写 implement** 须满足下列之一——(a) coordination 路径（control 或 waived 时主 checkout `{HARNESS_DIR}/status.json`）上 **same-host 独占写锁可用且每次 status/协调变更持锁**；(b) 默认 **`Plan parallelism: serial`**（**waived 时尤其优先默认串行**）；(c) 用户本轮显式 `Cross-host lease race: accepted`（或等价）+ `plans[].notes` 审计。**禁止**将 `Worktree mode: waived` 当作跨主机无锁并行的授权。细则 → **`references/phase-2-worktree-lease.md`**。
 
 任一 false → **stop**。Phase 1 / Prepare 未完成 → 先完成 Phase 1 或 per-plan Prepare，再进入本 Phase。
 
@@ -237,7 +238,7 @@ SSOT = `{HARNESS_DIR}/status.json` + `{PLAN_DIR}/`。todos 只追踪本轮下一
 2. 列出 `status` ∈ `{Todo, InProgress, InReview, Blocked}` 的 plan（优先级：`InProgress` → `InReview` → `Todo` → unblock `Blocked`）
 3. 读 root `metadata.iteration_base_branch` / `metadata.target_branch`，以及 plan `metadata.spec_integration_branch` / `merge_target` / `primary_spec` 链接
 
-### 2.3 Integration branch
+### 2.3 Integration branch + control worktree（Phase 2 入口）
 
 **Metadata 解析顺序**（任一环节缺失则 STOP，**禁止**默认 `main`/`master`）：
 
@@ -245,23 +246,40 @@ SSOT = `{HARNESS_DIR}/status.json` + `{PLAN_DIR}/`。todos 只追踪本轮下一
 2. 若 (1) 缺字段 → 读当前迭代 compass frontmatter 同名键：优先 `{ITERATION_DIR}/<iteration-id>/delivery-compass.md`；若无则 legacy `{ITERATION_DIR}/<iteration-id>-delivery-compass.md`
 3. 若 compass 有值而 `status.json` 无 → **同轮 backfill** `status.json`
 4. 仍缺 → 向用户确认 base / PR target；**不得**因 `git symbolic-ref refs/remotes/origin/HEAD` 指向 `main` 就自动采用
+5. 所有参与本轮迭代的 active plan **必须**解析到**同一** `spec_integration_branch`；不一致 → **STOP**
 
-**Git 操作**：
+**Control worktree（§2.0 #5 未 waive 时 — HARD）**：
+
+1. 解析或创建 **control worktree**（通常 primary checkout 或 PM 指定路径），检出到上一步的 `spec_integration_branch`
+2. `git fetch`（按需）；`git branch --show-current` 确认在 `spec_integration_branch`
+3. 将规范绝对仓库根路径写入 control 副本 `metadata.control_worktree_path`（仓库根，非 `{HARNESS_DIR}` 子路径）
+4. 此后 **status / SDD SSOT** 均经 control 路径解析：
+   - `<control_worktree_path>/{HARNESS_DIR}/status.json`
+   - `<control_worktree_path>/{HARNESS_DIR}/sdd/<plan-id>/`
+5. 若 integration 分支尚不存在：在 control worktree 内 `git checkout -b <spec_integration_branch> <iteration_base_branch>`（**必须**从记录的 base 创建）
+
+**Git 操作（无 control worktree 时 — 仅 `Worktree mode: waived`）**：
 
 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` 检出）
+2. **checkout 或创建** `spec_integration_branch`（同上）
 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`。
+`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）
 
-对每个 active `plan_id`：
+**跨 plan 默认**（**无论** `Worktree mode: waived`）：**不同 `plan_id` 可并行 implement** 须满足 §2.0 #5 跨 plan 并行安全闸——(a) coordination 路径 same-host 独占写锁可用且每次 status/协调变更持锁，或 (b) **`Plan parallelism: serial`**（waived 时默认），或 (c) 用户本轮 `Cross-host lease race: accepted` + audit `notes`；否则 Assignment 仍写并行 → **Blocked**。**merge 入 `spec_integration_branch` 仍串行**（`metadata.integration_merge_lease`；waived 时无 merge lease 仍须串行 merge）。未 waive 时 **禁止**无 verified `execution_lease` 的跨 plan 可写派发。
+
+对每个本轮要推进的 active `plan_id`（可交错/并行，非强制 plan A 全 Done 再 plan B）：
 
-1. **Plan start — feature branch**：Assignment 用 `Working branch: create <plan-feature-branch> from <spec_integration_branch>`。一个 plan 一条专用实现分支；plan 内多可写并行轨 → **`mstar-branch-worktree`** **`references/parallel-writable-pre-dispatch.md`**
-2. **Implement → InReview**（`§ 2.5`）：
+1. **Claim / resume — execution lease**（§2.0 #5 未 waive）：
+   - 自 control 路径 **重读** `status.json` 定位 plan 行
+   - 若已有 `execution_lease` 且 `holder` **等于本 session** → **resume**：校验 `worktree_path` / `working_branch` 与 Assignment 一致后继续（**不是** steal / Blocked）
+   - 若 `execution_lease` 存在且 `holder` **不同** → **Blocked**
+   - 若 `status: InProgress` 但 **无** `execution_lease` → **STOP** 升级（孤儿状态恢复 → **`mstar-plan-artifacts`**；本 skill 不自行补 lease）
+   - 否则按 **`references/phase-2-worktree-lease.md`** claim：`Todo`/`Blocked` → `InProgress` + 写入完整 `execution_lease`；verify 通过前 **禁止**可写派发
+2. **Plan start — feature worktree + branch**：创建/校验 dedicated feature worktree；Assignment 须含绝对 `Worktree path` + `Working branch`（与 lease 一致）。plan 内多可写并行轨 → **`mstar-branch-worktree`** **`references/parallel-writable-pre-dispatch.md`**
+3. **Implement → InReview**（`§ 2.5`；产品编辑在 feature worktree，status/SDD 经 control 路径）：
    - **默认 `Execution mode: sdd`**（多 task plan；hotfix 可 `inline`）。
    - PM 载入 **`mstar-sdd`** 后，按 plan task 顺序 **串行** per-task 循环（**不是**一次派发 dev 做全部 tasks）：
      1. `sdd-workspace <plan-id>` → `{SDD_DIR}`
@@ -272,10 +290,10 @@ SSOT = `{HARNESS_DIR}/status.json` + `{PLAN_DIR}/`。todos 只追踪本轮下一
      6. Fix loop 直至 review clean；append `{SDD_DIR}/progress.md`；更新 `status.json` / plan checkbox
      7. Next task
    - 每次 Completion Report v2 后更新 `status.json` + 主 plan
-3. **QC → QA gate → Done**：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/status）+ **`QA gate`**（`mandatory` → `qa-engineer`；`pm-acceptance` → PM checklist）。
-4. **Plan complete — merge back**：合并 plan feature branch → `spec_integration_branch`；在下一 plan 或 QC 前解决冲突
-5. **Cross-plan 进度同步**：更新 `{ITERATION_DIR}/<iteration-id>/delivery-compass.md` 的 `## Plans` 表状态列
-6. **Next plan** 从步骤 1 继续
+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/status）+ **`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 `metadata.integration_merge_lease` → 将 plan feature branch 合并入 `spec_integration_branch`（仅 merge-lease holder；细则 → **`references/phase-2-worktree-lease.md`**）→ 记录 merge commit 证据 → 释放 merge lease；**同轮**设 `Done` 并删除 `execution_lease`。merge 失败：保持 `InReview` + 保留 lease，不得标 `Done`。
+6. **Cross-plan 进度同步**：更新 `{ITERATION_DIR}/<iteration-id>/delivery-compass.md` 的 `## Plans` 表状态列
+7. **Next plan / parallel wave** 从步骤 1 继续（可并行推进其他已 claim 的 plan；merge 仍排队串行）
 
 全部 plan `Done` → **Phase transition gate**（见上文 **Phase transition gates**）：
 
@@ -294,7 +312,7 @@ SSOT = `{HARNESS_DIR}/status.json` + `{PLAN_DIR}/`。todos 只追踪本轮下一
 | 串行 | 同一 plan 内 **one implementer at a time**；每 task 后 **one fresh task reviewer** |
 | Sticky（可选） | Assignment **`SDD implementer session: sticky`** + `implementer-session.json`；implementer **resume**，reviewer **fresh** — `mstar-sdd/references/sticky-implementer-session.md` |
 | 文件交接 | brief / report / diff / `progress.md` 在 `{SDD_DIR}`；dispatch prompt **只给路径**，不贴 plan 全文或 task 历史 |
-| Assignment 字段 | 每个 implement dispatch 须含 `Execution mode: sdd`、`SDD dir`、`Model tier`；**禁止**省略 `Model tier` |
+| Assignment 字段 | 每个 implement dispatch 须含 `Execution mode: sdd`、`SDD dir`、`Model tier`；§2.0 #5 未 waive 时还须含绝对 `Worktree path` + verified `execution_lease`；**禁止**省略 `Model tier` |
 | 大包 inline | **禁止**把 T1–Tn 或整份 plan 写进 **一个** `fullstack-dev` leaf Assignment 冒充 SDD |
 | 分支 diff | 全部 task 完成后 `review-package MERGE_BASE HEAD` → `{SDD_DIR}/review/` branch diff → plan QC tri（N=3） |
 
@@ -311,8 +329,9 @@ Iteration Phase 2 附加：
 - 不因 harness 流程问题常问「是否继续」「要不要现在启动」—— **决策、记录、dispatch**
 - 进度汇报 / subagent Completion Report 后，下一条必须是 **dispatch 或下一 gate 动作**，不得以确认问句收束 turn
 - 未知 → 读 `mstar-*`；仅 **`Blocked`**、secrets、不可逆范围缺口、branch metadata 缺失、或 Phase 5 多轮仍 blocked 时升级用户
-- 实际 Git ≠ `working_branch` → **同轮**更新 plan + status
-- Per-plan loop **串行**（plan A Done 后再 plan B）；plan 内 SDD task **串行** — 见 §2.4、§2.5、`mstar-sdd` Continuous execution
+- 实际 Git ≠ `working_branch` → **同轮**更新 plan + status + `execution_lease.working_branch`（如适用）
+- **跨 plan implement**（**无论** `Worktree mode: waived`）：并行可写 implement 须满足 §2.0 #5 跨 plan 并行安全闸——same-host 独占写锁 + 每次协调变更持锁，或默认 **`Plan parallelism: serial`**（waived 时尤其优先），或用户本轮 `Cross-host lease race: accepted` + audit `notes`；**禁止**将 waived 当作无锁跨主机并行授权；未 waive 时另须 verified `execution_lease` + feature worktree。**integration merge 串行**（`integration_merge_lease` 或 waived 下无 lease 仍须串行 merge）
+- plan 内 SDD task **串行** — 见 §2.4、§2.5、`mstar-sdd` Continuous execution
 
 ---
 
@@ -447,6 +466,16 @@ PR 目标使用 root `metadata.target_branch`；缺失时停止并补齐，不
    - **Resolve** when addressed
 6. Return to step 1
 
+**Optional host helpers（command 层发现；非 `mstar-*` load order）**：
+
+| Priority | Helper | When |
+|----------|--------|------|
+| 1 | `babysit` or any `*-babysit` skill（first readable `SKILL.md`） | **Default prefer** — CI green + reviews resolved loop |
+| 2 | `greploop` | **Optional** — only when the **repo** uses Greptile / has `greploop` available; then run for Greptile **5/5** in addition to babysit/`*-babysit` (or fallback) gates |
+| 3 | neither | Command fallback = babysit-equivalent CI + reviews gates |
+
+When both babysit/`*-babysit` and `greploop` apply: **babysit/`*-babysit` first**（CI + reviews），then optional greploop for Greptile score. Discovery paths → host `commands/iteration-drive` / `iteration-loop` Phase 5.
+
 ### 5.2 Phase 5 exit checklist（迭代交付完成）
 
 打印 **`## Phase 5 exit checklist`**；全 `[x]` 后方可宣称 **迭代交付完成**：
@@ -482,6 +511,7 @@ PR **merge** 本身可仍由用户手动执行，除非 Assignment 明确授权
 | `references/iteration-workspace-readme-template.md` | `<iteration-id>/README.md` 可选模板（Documents 单表） |
 | `references/iteration-corpus-hygiene.md` | §1.6 writing-specialist specs 卫生细则 |
 | `references/autonomous-direction-lock.md` | §1.2 autonomous direction lock、scale budget、branch resolve |
+| `references/phase-2-worktree-lease.md` | Phase 2 control worktree、`execution_lease`、`integration_merge_lease` |
 | `mstar-strategy` | iteration-start 时读 `STRATEGY.md` 对齐方向 |
 
 ## NOT to do
@@ -507,3 +537,7 @@ PR **merge** 本身可仍由用户手动执行，除非 Assignment 明确授权
 - **不要在未显式 `Direction lock mode: autonomous` 时跳过与用户收敛方向**（interactive 仍为默认）
 - **不要在 `autonomous` mode 下例行问用户「是否同意该方向」**（须落盘 rationale；无候选且无约束时 STOP）
 - **不要把 harness 流程（Review 链 / QC / QA / compound / close / PR 等）计进 Scale budget 的 plan 数量**，也不得为此单独建 process plan 占坑
+- **不要在 Phase 2 无 verified `execution_lease` 就做可写 implement 派发**（resume 仅限同 `holder` verify-held-lease）
+- **不要 steal / 覆盖他人 `execution_lease` 或 `integration_merge_lease`**（除非用户本轮显式 override + audit `notes`）
+- **不要从 feature worktree 的 `{HARNESS_DIR}` 路径当作 status/SDD SSOT**（control worktree 路径为准）
+- **不要并行 merge 入 `spec_integration_branch`**（merge 必须经 `integration_merge_lease` 串行）

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

@@ -0,0 +1,179 @@
+# Phase 2 control worktree + execution lease
+
+Normative field names and claim/release/merge semantics → maintenance ADR
+`.harness/docs/2026-07-22-iteration-worktree-plan-lease.md` (this repo) or
+`mstar-plan-artifacts/references/status-and-residuals.md` (runtime SSOT after
+plan-artifacts sync). This reference is the **iteration-command execution
+checklist**; do not invent alternate lease field names.
+
+## When it applies
+
+**Iteration commands only** (`iteration-start` ends before this; `iteration-drive`
+/ `iteration-loop` Phase 2+). 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**.
+
+## Control worktree (Phase 2 entry)
+
+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
+   `metadata.control_worktree_path` (not `{HARNESS_DIR}`; canonicalize symlinks).
+5. Resolve coordination paths from that root:
+   - status SSOT: `<control_worktree_path>/{HARNESS_DIR}/status.json`
+   - SDD tree: `<control_worktree_path>/{HARNESS_DIR}/sdd/<plan-id>/`
+
+All sessions MUST reread the **control copy** of `status.json` immediately before
+claim, release, transfer, plan-status transition, or merge-lease mutation.
+
+### Same-host exclusive write lock
+
+All control-path lease mutations (claim, release, transfer, merge-lease
+claim/release) **MUST** run inside a same-host exclusive write lock for the full
+read-check-replace-verify sequence. Prefer `flock` on
+`{HARNESS_DIR}/.status-write.lock`; alternative: atomic `mkdir` on
+`{HARNESS_DIR}/.status-write.lockdir/`. Do **not** invent a 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 `status.json` path and
+used for every status/coordination mutation** in that Phase 2 session (control
+path when lease gate active; primary checkout `{HARNESS_DIR}/status.json` when
+waived). Agents on **different hosts** or with **no shared flock/lockdir** →
+default **`Plan parallelism: serial`** (preferred when waived). Assignment still
+claiming cross-plan parallel without lock availability → **Blocked** until PM
+sets serial scheduling or the user gives current-turn override
+`Cross-host lease race: accepted` (or equivalent) + audit on `plans[].notes`.
+**`Worktree mode: waived` alone is not** this override.
+
+Immediately before **any** writable implement dispatch, re-read control
+`status.json` and re-verify `execution_lease` holder + paths match this session;
+mismatch → **STOP**.
+
+## Feature worktree (per plan)
+
+- 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
+  `metadata.control_worktree_path` (never reuse the control checkout for product
+  edits).
+- `Worktree path` MUST appear in the writable Assignment and in
+  `plans[].execution_lease.worktree_path` before first writable implement dispatch.
+- Product/source edits run from the feature worktree; status and SDD
+  coordination reads/writes run through the control path.
+- Default **L1**: one writable track per plan. Within-plan multi-writable tracks
+  still follow L2 `parallel-writable-pre-dispatch` (`mstar-branch-worktree`).
+
+## Execution lease (`plans[].execution_lease`)
+
+Required shape (v1): `holder`, `claimed_at` (RFC 3339 UTC with `Z`),
+`worktree_path`, `working_branch`; optional `session_label` (display only).
+
+### Claim (before `InProgress` or writable dispatch)
+
+1. Read control `status.json`; locate exactly one plan row (`id` or `plan_id`).
+2. If `execution_lease` exists:
+   - **Same `holder` as this session** → **resume**: verify `worktree_path` and
+     `working_branch` match the Assignment; continue (not steal/block).
+   - **Different `holder`** → **Blocked** (no timestamp makes it stealable).
+3. Create or verify dedicated feature worktree + branch.
+4. Re-read `status.json` under write lock; if row/status/lease changed, restart claim.
+5. One complete-file update (still under lock): `status: "InProgress"` + full `execution_lease`.
+   Use temp file + atomic replace; never expose partial JSON.
+6. Re-read and verify `holder`, `worktree_path`, `working_branch` match before
+   any writable dispatch.
+
+### Hold, release, override
+
+- Lease stays active across `InProgress` and `InReview` (including post-QC/QA
+  ready-to-merge) unless released or transferred.
+- Normal release: re-read control `status.json` under write lock; confirm stored `holder` matches
+  this session — mismatch → **Blocked**; then **delete** `execution_lease`
+  (never `null` or tombstone).
+- `Done` authority deletes `execution_lease` in the same update as `status: "Done"`
+  — **only after** successful integration merge (when lease gate not waived).
+- Override of another holder requires **explicit user instruction this turn** +
+  audit note on plan `notes` (prior holder, new holder/release, user authorized).
+- V1: **manual release only** — no `expires_at`, TTL, or heartbeat authority.
+
+### Orphan `InProgress` without lease
+
+If a plan row is `InProgress` but has **no** `execution_lease`, STOP and
+escalate — do not invent a lease or writable-dispatch. Unattended "Recover with
+claim" is permitted **only** for the **same** stable `holder`; different holder
+requires verified quiescence + handoff or current-turn user override + audit.
+Recovery semantics → `mstar-plan-artifacts` (not iteration skill).
+
+## Multi-plan parallelism
+
+**Cross-plan parallel safety gate** applies **whether or not** `Worktree mode:
+waived` is in effect — waiver does **not** authorize lockless cross-host parallel.
+
+- **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
+     `status.json` path (control path when lease gate active; primary checkout
+     `{HARNESS_DIR}/status.json` when waived) and used for every status/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
+     waiver).
+  3. Current-turn `Cross-host lease race: accepted` (or equivalent) + audit
+     `plans[].notes`.
+  Cross-host / no shared lock without (2) or (3) → **Blocked** if Assignment still
+  claims cross-plan parallel writable implement.
+- **Integration merge** into `spec_integration_branch` is **serial** (one at a time),
+  with or without lease gate.
+
+## Integration merge lease (`metadata.integration_merge_lease`)
+
+Required shape (v1): `holder`, `claimed_at`, `plan_id`, `source_branch`,
+`target_branch` (= resolved `spec_integration_branch`); optional `session_label`.
+
+1. From control worktree: clean tree; branch = `spec_integration_branch`.
+2. Under write lock, reread root `metadata`. If `integration_merge_lease` exists:
+   - **Same `holder` as this session** → **resume**: verify `plan_id`,
+     `source_branch`, `target_branch` match intended merge; confirm control
+     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`.
+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.
+
+Execution and merge leases may coexist; merge lease does not grant execution
+ownership for the source plan.
+
+## Waiver
+
+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
+- `plans[].execution_lease` and `metadata.integration_merge_lease` claim/hold/release
+  defaults
+
+It does **not** waive the **cross-plan parallel safety gate**. Under waiver,
+cross-plan **parallel writable** implement still requires same-host exclusive
+write lock on the coordination `status.json` path, default **`Plan parallelism:
+serial`**, or current-turn `Cross-host lease race: accepted` + audit
+`plans[].notes`. **Prefer serial scheduling when waived**; parallel under waiver
+only with the race-accepted override (or same-host lock when mutating shared
+status).
+
+`Plan parallelism: serial` does **not** waive control worktree or leases.
+
+Iteration commands MUST NOT infer waiver from missing worktrees or single-session
+starts. Explicit override this turn only.

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

@@ -27,6 +27,7 @@ description: Morning Star plan harness artifacts — `{PLAN_DIR}` main plans and
 - **Canonical**: register new findings only at root `residual_findings`; **`metadata.residual_findings`** is legacy read-only — **do not** dual-write.
 - **Lifecycle**: open → verified close → **`archived/residuals/<plan-id>.json`**; machine **`severity`** enum in reference.
 - **`notes.json`**, optional **`tech_debt_summary`** (rollup view; compute via **`scripts/tech-debt-rollup.sh`**).
+- **Iteration Phase 2 leases** (`metadata.control_worktree_path`, `plans[].execution_lease`, `metadata.integration_merge_lease`): claim-before-`InProgress`, resume vs steal, orphan recovery → **`references/status-and-residuals.md`** (“Iteration execution leases”).
 
 Field semantics, severity mapping, archive flow, and `jq` examples → **`references/status-and-residuals.md`**.