@mstar-harness/dsh 3.9.3 → 3.10.0

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

@@ -179,6 +179,7 @@ Legacy `.agents/` 等价：
 - **Spec 集成分支**：从 `iteration_base_branch` 创建；各 Plan 实现 merge 回此线后再视为 Spec 在代码侧集成。
 - **Plan 实现分支**：每 `plan_id` 一条（PM 书面）。
 - **PR target**：全部 Plans 与 iteration-close 完成后，向显式 `target_branch` 提 PR（窄例外见 Assignment `Branch policy`）。
+- **Standalone development plan**：单 plan 交付不经迭代集成序列——交付分支上完成 compound disposition 后向显式 target 提交 PR，PR 身份（repo/head/target）在提交时记录；序列与语义 → `mstar-artifacts/references/plan-workflow-lifecycle-contract.md`（迭代序列不变，见上）。
 - Git 操作与 QC 单一 `HEAD` → **`mstar-branch-worktree`**。
 - workflow snapshot 登记顶层 `branch.base`（`iteration_base_branch`）/ `branch.target`（`target_branch`）/ `branch.integration`（`spec_integration_branch`），以及 plan 行 `metadata.spec_integration_branch` / `merge_target` → **`mstar-artifacts`**。
 

package/harness-skills/mstar-conventions/references/effort-estimation.md

@@ -25,6 +25,8 @@
 
 「**会话**」指：一次连贯的 agent 运行（读上下文 → 实现 → 运行验证），**不是**人类 8 小时工作日。
 
+任务层使用：每 task 的容量判据（单轮闭合其 Files 与验证门、命名 split point）→ **`mstar-artifacts/references/plan-quality-bar.md`** item 7（Task shape / session fit）；本尺码只是规模预估，**不**定义单轮上限。
+
 ## 文档与模板中的字段名（建议）
 
 - **PRD / 产品文档**：**`## Effort (agent-oriented)`** — 仅 **Complexity (XS–XL) + agent session band + 假设**（规格已锁、契约稳定等）。  

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

@@ -1,6 +1,6 @@
 ---
 name: mstar-dispatch-gates
-description: Morning Star 派发与委派门禁 —— 仅 PM 可增派 subagent、`Execute as` 与 `Delegation`、承接方反递归 NEVER 红线、SDD 独立就绪任务并行派发、**SDD 路径 plan QC 强制 tri-review（N=3）**、inline 单席 QC 例外、Assignment 文案≠派发、未齐不发、**invoke 角色字段必填（漏写=静默 generic 回退=派发未完成）**。`project-manager` 派发时必读；leaf 动手前必读反递归。worktree 见 `mstar-branch-worktree`；SDD 见 `mstar-sdd`；宿主见 `mstar-host`。
+description: Morning Star 派发与委派门禁 —— 仅 PM 可增派 subagent、`Execute as` 与 `Delegation`、承接方反递归 NEVER 红线、**子 Assignment 继承 plan 作用域且 credential/session 不下发 leaf**、SDD 独立就绪任务并行派发、**SDD 路径 plan QC 强制 tri-review（N=3）**、inline 单席 QC 例外、Assignment 文案≠派发、未齐不发、**invoke 角色字段必填（漏写=静默 generic 回退=派发未完成）**。`project-manager` 派发时必读；leaf 动手前必读反递归。worktree 见 `mstar-branch-worktree`；SDD 见 `mstar-sdd`；宿主见 `mstar-host`；scoped plan 路线见 `mstar-iteration` `plan-scoped-pm.md`。
 ---
 
 ## Load order（必读顺序）
@@ -36,6 +36,14 @@ description: Morning Star 派发与委派门禁 —— 仅 PM 可增派 subagent
 
 > **Engine 执行范围（caller-scoped，#156）**：engine `antiRecursionPrecheck` 比较的是**派发方自身角色**（caller）与新 Assignment 的 `Execute as`（target）。只有 **dsh**（Config `dispatchBinding`）能观察派发方身份并在 engine 层硬执行（含 `callerRequired` 空绑定 fail-closed）；omp / OpenCode / Cursor 的角色绑定字段是**派发目标**——目标 == `Execute as` 正是 C5 合规派发模式——这些宿主上红线保持 prompt 级约束（本节），engine 不做判定。
 
+## Plan 作用域与 credential 不下发（preflight 强制）
+
+派发前，与工具并发 / 角色绑定字段同级的硬门禁：
+
+- **子 Assignment 继承父 plan 作用域**：`plan_id` + 绝对 `Plan Path`（L1 另含 `SDD dir` / `Control harness root`）逐字下发。child **不得**自选或新建 plan、写 workflow snapshot / root register / 共享索引、释放 `execution_lease` / `integration_merge_lease`。缺失、相对路径或暗示「child 自行选 plan」= **派发未完成**（`mstar-roles/references/project-manager/dispatch-and-assignment.md` § Assignment Template `Plan scope`）。
+- **credential 不下发 leaf**：session JSON 路径、`mstar plan --session` 写凭据、`--expect <revision>` 等**只由派发方（PM/coordinator）持有**。leaf 拿到 session 路径或写凭据即视为越权 → 停止并回报（`mstar-iteration/references/plan-scoped-pm.md` §8）。
+- **`project-manager` 不是派发目标**：PM 是 primary-session 角色，无 subagent shell（规则家 → `mstar-roles/references/project-manager.md` § Plan-scoped authority；宿主派发面 → `mstar-host/references/omp.md` § C5）；scoped primary drive（`/iteration-drive --assignment | --workflow --plan | --resume`）在**主会话**启动 PM，不是 subagent。任何 `Execute as: project-manager` 的 invoke = 派发缺陷。
+
 ## 调度防串扰（强制；leaf executor 已在上方读过反递归红线，此处为完整规则供 PM/对照用）
 
 - 只有 **`project-manager`** 可以决定增加/并行 subagent；承接方**默认不得二次分派**。
@@ -64,7 +72,7 @@ description: Morning Star 派发与委派门禁 —— 仅 PM 可增派 subagent
 
 在支持具名角色 / Task 的宿主上，`## Assignment` **正文不会**拉起子会话。PM 须在**同一条 assistant 消息**（或宿主等价机制）发出与 Assignment **条数一致**的 invoke / Task；仅打印 Markdown = **分派未完成**。**几条 Assignment ⇒ 几次 tool 调用**（默认同消息并行）。
 
-> **Engine check (when available):** run `mstar dispatch validate <assignment-file> [--branch <branch>]` (or `import { validateAssignmentFields, assertDefaultBranchProtected } from "@mstar-harness/engine"` in a host hook) to validate the Assignment field contract and the default-branch gate (normative default-branch prose: **`mstar-branch-worktree`** SKILL.md § "Git 功能分支门禁（业务仓库）" — this skill covers dispatch mechanics only). On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
+> **Engine check (when available):** run `mstar dispatch validate <assignment-file> [--branch <branch>]` (or `import { validateAssignmentFields, assertDefaultBranchProtected } from "@mstar-harness/engine"` in a host hook) to validate the Assignment field contract — including the canonical **`Task budget (implement / ops rounds)`** header field on non-review / non-audit rounds: presence-only in the header region, absent / empty / `N/A` → validation fail (field guidance → `mstar-roles/references/project-manager/dispatch-and-assignment.md`; capacity criterion → `mstar-artifacts/references/plan-quality-bar.md` item 7) — and the default-branch gate (normative default-branch prose: **`mstar-branch-worktree`** SKILL.md § "Git 功能分支门禁（业务仓库）" — this skill covers dispatch mechanics only). On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
 
 ## SDD implement 波次（PM only）
 
@@ -73,6 +81,7 @@ When **`Execution mode: sdd`** (`mstar-sdd`):
 - **依赖驱动**：按 **`mstar-sdd`** § Ready-task scheduling 并行派发独立 ready tasks；各 task 后一位 fresh reviewer。真实依赖、共享写目标和 integration merge 串行。
 - **`SDD implementer session: sticky`**：same implementer subagent may **resume** across tasks when host supports it; **reviewers never resume** — see **`mstar-sdd/references/sticky-implementer-session.md`**.
 - File handoffs only — no pasted plan/diff/history in dispatch prompts.
+- **scope 与凭据边界**：`{SDD_DIR}/task-N-brief.md` 携带继承的 plan 作用域（plan id + 绝对路径）；**不下发** session JSON、`--expect <revision>` 等写凭据，也不得让 implementer/reviewer 自选 plan 或释放 lease（见 § Plan 作用域与 credential 不下发）。
 - Record per-task BASE SHA; use `review-package` for diffs — **never `HEAD~1`**.
 - After all tasks: branch `review-package` in `{SDD_DIR}/review/` → **mandatory tri-review N=3** when `Execution mode: sdd`; **N=1** only for `inline` / explicit single override.
 

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

@@ -32,7 +32,7 @@ description: Morning Star (启明星) harness **生命周期 / 授权语义权
 
 ## 最小交付循环
 
-**per-plan**：`specify → clarify → plan` → `plan(locked) → tasks → implement`（多 task 默认 SDD）→ plan QC tri + **QA gate**（`mandatory` 派 QA 或 `pm-acceptance`）→ Done（`inline` 单席例外）。阶段细则 → **`mstar-phase-gates`**；QA 分级 → **`mstar-roles/references/project-manager/qa-trigger-matrix.md`**。
+**per-plan**：`specify → clarify → plan` → `plan(locked) → tasks → implement`（多 task 默认 SDD）→ plan QC tri + **QA gate**（`mandatory` 派 QA 或 `pm-acceptance`）→ Done（`inline` 单席例外）。阶段细则 → **`mstar-phase-gates`**；QA 分级 → **`mstar-roles/references/project-manager/qa-trigger-matrix.md`**。独立交付 development plan 在 Done 后继续交付尾段 `compound disposition → submit PR → merge-ready（resumable milestone）→ verify merge → terminal close/unregister/reconcile`（`verification/report-only` 按注册声明的替代完成政策，无强制 PR；注册与尾段语义/失败行为的权威 = 冻结契约 **`mstar-artifacts/references/plan-workflow-lifecycle-contract.md`**，PM 步骤序列 → **`mstar-roles/references/project-manager/plan-management.md`**）。迭代内 plan 行不各自走尾段，迭代整体走一次（见下行）。
 
 **迭代级**：`iteration-start → [per-plan cycle × N] → iteration-close → PR delivery → PR merge-ready loop`。细则 → **`mstar-iteration`**。
 
@@ -72,7 +72,7 @@ PM 在 Assignment 写 **`Task category`**（主类 + 可选 `secondary`）：
 | `docs` | `@product-manager` / `@architect` / `@writing-specialist` |
 | `audit` | `@code-reviewer`（mstar-audit 承载；大型仓库经 Assignment `Delegation: allowed (scout/explore only, read-only)` 扇出只读 scout；read-only advisory；不进入状态机） |
 
-**硬规则**：`quick` **从不**跳过 `specify → clarify → plan`；禁止把新 CLI/API/多模块/新测例标为 `quick`。已启用 `{HARNESS_DIR}` 时，首次 implement 前须有主 plan 路径 + `status.json` 登记（见 **`mstar-conventions`**）。
+**硬规则**：`quick` **从不**跳过 `specify → clarify → plan`；禁止把新 CLI/API/多模块/新测例标为 `quick`。已启用 `{HARNESS_DIR}` 时，首次 implement 前须有主 plan 路径 + `status.json` 登记（见 **`mstar-conventions`**）。workflow 注册本身是 authorized domain operation（经授权 producer 的引擎原语，不自创第二注册机制），语义 → 冻结契约 `mstar-artifacts/references/plan-workflow-lifecycle-contract.md`。
 
 ## `@explore` 边界
 

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

@@ -52,13 +52,20 @@ On **dsh** only, read-only fan-out of **N ≥ 3** seats runs through the native
 
 ## `/goal` directive (host-agnostic)
 
-**Applicability is by capability, not host identity**: any host that exposes a `/goal` command (currently Codex Goal Mode and omp; other code agents may add it later) attaches a persistent objective to the thread. **Exception — dsh:** mstar **stops arming** a goal there and never uses a `/goal` objective or a goal round loop as the progression driver — dsh runs on the native workflow (workflow snapshot phases + dispatch gates + **subagent settle notifications**; Phase 2 is a PM-local dispatch → wait for the child's settle notification → next dispatch, and a manually armed `/goal` stays outside mstar's flow). Full rule → `references/dsh.md`. Rule — **always set the goal to running the complete flow to the end**, never a sub-stage:
+**Applicability is by capability, not host identity**: any host that exposes a `/goal` command (currently Codex Goal Mode and omp; other code agents may add it later) attaches a persistent objective to the thread. **Exception — dsh:** mstar **stops arming** a goal there and never uses a `/goal` objective or a goal round loop as the progression driver — dsh runs on the native workflow (workflow snapshot phases + dispatch gates + **subagent settle notifications**; each settle notification is a **`result-settled` Rescheduling checkpoint** — run that checkpoint and dispatch the ready independent work before any wait, never "one settle → one dispatch", per `mstar-iteration` `references/phase-2-worktree-lease.md` §2.4; a manually armed `/goal` stays outside mstar's flow). Full rule → `references/dsh.md`. Rule — **always set the goal to running the complete flow to the end**, never a sub-stage:
 
 - **Advancing an iteration**: set the goal to **complete the entire iteration flow** (`iteration-start → per-plan cycles → iteration-close → PR delivery → PR merge-ready loop`). Do not set a sub-stage goal (e.g. "finish Phase 1 only").
-- **Advancing non-iteration work** (single plan / hotfix / one-off task): set the goal to **complete the entire per-plan flow** (`specify → clarify → plan → tasks → implement → plan QC tri + QA gate → Done`). Do not set a sub-stage goal (e.g. "write the plan" or "implement one task").
+- **Advancing non-iteration work** (single plan / hotfix / one-off task): set the goal to **complete the entire per-plan flow** (`specify → clarify → plan → tasks → implement → plan QC tri + QA gate → Done`; standalone development plans continue through the delivery tail to verified merge + terminal close — `mstar-harness-core`「最小交付循环」/ `mstar-artifacts/references/plan-workflow-lifecycle-contract.md`). Do not set a sub-stage goal (e.g. "write the plan" or "implement one task").
+- **Scoped primary route** (`/iteration-drive --assignment | --workflow <id> --plan <id> | --resume <session.json>`): the goal is the **active plan scope only** — `mstar plan bind` → constrain → tasks → per-task review → plan QC tri / QA → `mstar plan handoff`. Never set a goal that spans the iteration flow, sibling plans, or Phase 3–6: those stay in the coordinator's own primary session, not this plan-scoped one (`mstar-iteration` `references/plan-scoped-pm.md` §5).
 
 Goal text is a session-level objective only: `{HARNESS_DIR}` / `{PLAN_DIR}` / `status.json` remain SSOT, and goal completion is **not** harness Done. Mirror goal success criteria into the SSOT plan; when the goal changes, update goal text and the SSOT in the same round.
 
+## Phase-transition todo refresh (host-agnostic)
+
+At **every phase transition** (Prepare → Execute → InReview waves → Phase 3 close → Phase 4 PR → Phase 5 merge-ready → Phase 6 post-merge; likewise per-plan gate crossings), the PM refreshes the host session `todo` list **before the next action or dispatch**: close only the finished phase's **completed** entries, preserve any still-pending gate or future-phase item, and append the next phase's entries. Scoped primary sessions project only their assigned plan through handoff — never global Phase 3–6 tasks (`mstar-iteration` `references/command-shared-invariants.md` § Session todos; `references/phase-2-worktree-lease.md` §2.1).
+
+`todo` entries are a projection, not SSOT: they reflect existing snapshot phase / plan states and named plan/gate evidence, and cannot authorize or invent a state transition. Snapshot and plan artifacts remain the state authorities; this is freshness discipline, not a new host hook, tool, or deterministic enforcement mechanism.
+
 ## Resolve loaded skill root
 
 Docs name assets as skill **`<name>`** → `scripts/…` / `references/…`. **Resolve the loaded skill directory first** — do **not** open `skills/<name>/…` from a consumer app cwd (that layout exists in the harness source / plugin package only).

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

@@ -49,6 +49,8 @@ Not allowed in the parent Build session by default: product implementation, test
 | **`spec-register`** | Register plan in SSOT | New root `workflows[]` entry (`{HARNESS_DIR}/status.json` v2) + `plans[]` row in `{WORKFLOW_DIR}/<id>/snapshot.json` (`id`, `status`, `file`, `metadata`); spec stub in `{SPECS_DIR}` or plan frontmatter |
 | **`mirror-plan`** | SSOT main plan file | `{PLAN_DIR}/<plan-id>-<name>.md` with task checkboxes aligned to the host plan body |
 
+`spec-register` is an authorized domain operation (engine producer primitives), declares the workflow's delivery kind, and blocks implementation until complete — plan-mode resumes owe the same registration obligation. Semantics → `mstar-artifacts/references/plan-workflow-lifecycle-contract.md`.
+
 After the host plan is created, keep the host plan body and mirror file **in sync** when scope changes (update both in the same coordination round).
 
 ## Implement todo completion gate (every code todo)

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

@@ -2,7 +2,7 @@
 
 Load when **`mstar-host`** detection resolves **codex** (Codex app/CLI session, `/plan` / `/goal` slash commands, Goal tools, or Codex tool namespaces such as `functions.*`, `codex_app.*`, `tool_search`, `image_gen`, or Browser plugin tools).
 
-Plan Mode: read **`references/_shared/plan-mode-bridge-core.md`** when Codex Plan Mode (`/plan`) is active. Goal Mode (`/goal`, goal tools, or goal progress controls) follows the host-agnostic **`/goal`** rule in `mstar-host` SKILL.md — applicability is by the `/goal` command, not host identity. Codex session plans, UI todos, and goal text are not durable harness SSOT.
+Plan Mode: read **`references/_shared/plan-mode-bridge-core.md`** when Codex Plan Mode (`/plan`) is active. Goal Mode (`/goal`, goal tools, or goal progress controls) follows the host-agnostic **`/goal`** rule in `mstar-host` SKILL.md — applicability is by the `/goal` command, not host identity. On the scoped route (`/iteration-drive --assignment | --workflow --plan | --resume`) the goal is that **plan's scope only** — never the iteration flow, sibling plans, or Phase 3–6. Codex session plans, UI todos, and goal text are not durable harness SSOT.
 
 Parallel PM dispatch: read **`parallel-dispatch.md`** only when Codex exposes an actual multi-agent / Task-style invocation tool. If no callable invoke tool exists, Assignment Markdown is coordination text only; do **not** claim subagent dispatch.
 

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

@@ -360,10 +360,20 @@ armed and the agent is idle, and it knows nothing about running subagents, so
 an operator who arms `/goal` manually can still get rounds firing while a
 dispatched child owns the critical path.
 
-**Phase 2 continuous execution is a PM-local loop**: dispatch → **wait for the
-child's settle notification** → next dispatch. When a dispatched child owns the
-critical path, the correct action is to **wait** — not to open another unit of
-work against the same worktree.
+**Phase 2 continuous execution is a PM-local loop**, not a one-wave-at-a-time
+queue: each child's settle notification is a **`result-settled`
+`Rescheduling checkpoint`** — run that checkpoint and dispatch what is already
+ready and authorized (independent plans and plan-local tasks, each in its own
+isolated track) before waiting, and wait only when it finds none. Waiting stays
+the correct action for work a running child already owns — never open another
+unit of work **against the same worktree**. Procedure (and its frozen reason
+vocabulary) → `mstar-iteration/references/phase-2-worktree-lease.md` §2.4.
+
+The **scoped plan route** changes none of this: `/iteration-drive --assignment |
+--workflow --plan | --resume` still never arms a goal on dsh, and its
+progression stays the plan-scoped native workflow (`mstar plan bind → progress →
+handoff`, coordinator `accept` / `integration-*` / `complete`) —
+`mstar-iteration/references/plan-scoped-pm.md`.
 
 ### QC default
 

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

@@ -101,7 +101,7 @@ Single-task shorthand may exist depending on host version — always match the l
 
 ### Notes
 
-- PM is the **primary** orchestration seat via the `pm` skill (no PM agent shell is bundled here — the `mode: primary` shell is OpenCode-only, `packages/opencode/agents/`). Do not dispatch PM-to-PM via `task` unless the live schema explicitly lists it **and** the Assignment requires it.
+- PM is the **primary** orchestration seat via the `pm` skill (no PM agent shell is bundled here — the `mode: primary` shell is OpenCode-only, `packages/opencode/agents/`). Do not dispatch PM-to-PM via `task` unless the live schema explicitly lists it **and** the Assignment requires it. The **scoped primary route** (`/iteration-drive --assignment | --workflow --plan | --resume`) likewise runs in the **primary session** — it is never a `task` target, and a plan session may not reach sibling rows, the root register / shared projections, or Phase 3–6 (`mstar-iteration` `references/plan-scoped-pm.md`).
 - Host generics (`scout`, `reviewer`, `designer`, …) remain useful for non-role orientation / assist — they do not replace a listed Morning Star role agent for role-owned deliverables.
 
 ### Role binding in prompt (C5b — required)
@@ -210,7 +210,9 @@ Cannot emit required **N** → **`Blocked`**.
 
 ## In-process engine binding (omp ≥ 17.2.11)
 
-- **Surfaces** (npm package root = plugin root; sources live in `packages/omp/src/`): `hooks/pre/mstar-gates.js` — one `tool_call` pre-hook that returns `{ block: true, reason }` (structured refusal the model sees as the tool error) or `undefined` (pass); `tools/mstar_{status_validate,dispatch_validate,lease_verify,path_resolve,iteration_gate,worktree_check}.js` — six model-callable validator tools (engine validators only, Zod params via `pi.zod`). omp discovers these by convention from the installed package root (`<pkg>/hooks/pre/` any file, `<pkg>/tools/` direct `*.js` files — the sub-directory scan only accepts `tools/<name>/index.ts`), not from `dist/`.
+- **Surfaces** (npm package root = plugin root; sources live in `packages/omp/src/`): `hooks/pre/mstar-gates.js` — one `tool_call` pre-hook that returns `{ block: true, reason }` (structured refusal the model sees as the tool error) or `undefined` (pass); `extensions/model-handoff.js` — the coordinator model-handoff extension, published through the manifest `omp.extensions` entry (see **Model handoff** below); `tools/mstar_{status_validate,dispatch_validate,lease_verify,path_resolve,iteration_gate,worktree_check}.js` — six model-callable validator tools (engine validators only, Zod params via `pi.zod`). omp discovers `hooks/` and `tools/` by convention from the installed package root (`<pkg>/hooks/pre/` any file, `<pkg>/tools/` direct `*.js` files — the sub-directory scan only accepts `tools/<name>/index.ts`), not from `dist/`; `extensions/` is discovered from the manifest entry.
+
+- **Surfaces** (npm package root = plugin root; sources live in `packages/omp/src/`): `hooks/pre/mstar-gates.js` — one `tool_call` pre-hook that returns `{ block: true, reason }` (structured refusal the model sees as the tool error) or `undefined` (pass); `extensions/phase2-orchestration.js` — the Phase-2 reminder + launch-bookkeeping extension (`mstar_phase2`), published through the manifest `omp.extensions` entry (see **Phase-2 plan instances** below); `tools/mstar_{status_validate,dispatch_validate,lease_verify,path_resolve,iteration_gate,worktree_check}.js` — six model-callable validator tools (engine validators only, Zod params via `pi.zod`). omp discovers these by convention from the installed package root (`<pkg>/hooks/pre/` any file, `<pkg>/tools/` direct `*.js` files — the sub-directory scan only accepts `tools/<name>/index.ts`), not from `dist/`.
 |- **Enforcement semantics**: block ONLY under `Enforcement: hard`. Both gates read the repo `.mstarc` `[config] enforcement`, else the harness compass frontmatter (`enforcement: hard`, active/locked iterations only); the dispatch gate ALSO honors each Assignment's own header flag (`assignmentHeaderRegion` — a body example never hardens). A hard repo setting therefore hardens flag-less dispatches (Gate 1 / dsh `resolveDispatchHard` parity). Soft-mode dispatch violations are warn-logged through the extension logger (never blocked); soft status-write violations stay a silent pass. Rollback = unset the flag (or `.mstarc` `soft`). Never global.
 - **Anti-recursion scope (issue #156)**: the engine's `antiRecursionPrecheck` is **caller-scoped** — it compares the DISPATCHING agent's own role against the new Assignment's `Execute as`. omp's `tool_call` event carries no caller identity and the task entry `agent` is the spawn TARGET, which equals `Execute as` on every compliant dispatch (C5 above) — so Gate 2 does NOT run the precheck on omp (the pre-#156 wiring hard-blocked every compliant hard-mode dispatch on `self-type`, or on `empty-binding` when `agent` was omitted). The NEVER red line stays prompt-level on this host (`mstar-dispatch-gates`); dsh enforces it in-engine via Config `dispatchBinding`.
 - **Engine dependency**: the npm package **bundles the engine inline** into every hook/tool bundle at build time — zero runtime package resolution, so module link can never fail on a missing package (the 2026-09-03 hotfix for the bare-import load failure). The maintainer `omp plugin link` path (now `<repo>/packages/omp`) still resolves the engine via the workspace member — run `bun install && bun run engine:build && bun run --cwd packages/omp build` in the checkout first (the member's `dist/` and the package's generated mirrors are gitignored).
@@ -220,6 +222,64 @@ Cannot emit required **N** → **`Blocked`**.
 - **Engine version compatibility**: the hook and tools degrade gracefully until the engine release exporting both `composeDispatchGate` and `parseCompassFrontmatter` (published 2.0.2 predates both). Missing exports never fail module load: the hook's dispatch gate needs `composeDispatchGate` — on older engines Gate 2 (task dispatch) is skipped with a one-time warning while Gate 1 (status) stays active — and `mstar_dispatch_validate` / `mstar_iteration_gate` report an explicit upgrade error instead of loading (no silent absence; CLI fallbacks: `mstar dispatch validate`, `mstar iteration gate`).
 - **Reload**: edits are picked up by a new session (`?mtime` cache-buster); in-session `/reload-plugins` (omp ≥ 17.2.11) applies them without a new session.
 
+## Model handoff (native settings)
+
+A second extension entry from this package: `extensions/model-handoff.js` (manifest `omp.extensions`; engine inlined, its single `@oh-my-pi/pi-coding-agent` import resolved by the running host). It is a **coordinator model policy owned by native settings**, not a user command — no session, flag, goal or prose can enable it.
+
+| Surface | Contract |
+|---|---|
+| Native path | `/settings` → **Plugins** → **`@mstar-harness/omp`** — the rows are the schema keys: `modelHandoff` (boolean, default `false`) and `handoffTarget` (`@default` \| `@smol`, default `@default`). No activation command, no harness settings file, no second settings UI. |
+| Persistence | Host plugin settings (user-scope `omp-plugins.lock.json`, plus project `plugin-overrides.json`), reread through the exported helper at entry **and again at fire time** — a mid-flight enable never retro-arms an iteration already under way, and disabling at fire time suppresses the switch without terminalizing the binding. |
+| Scope | That panel lists **user-scope** installs; a project-scope npm install has no native row (host limitation, documented rather than worked around). Use the user-scope path — never double-install or add a private settings parser/UI. |
+| Supported entries | `/iteration-start`, `/iteration-loop`, and a natural-language / skill-driven start (`skill-start`) as labelled from the host's own `input` event. `/iteration-drive` in any form never arms — the scoped-plan route only restores the session's existing binding, and a start call after it is refused `scoped-plan-route`. |
+| Inert contexts | Ordinary chat, unrelated commands, leaf/subagent sessions (host `session_init` marker), plan-scoped PM sessions, other hosts, and an iteration whose coordinator never armed. |
+| PM binding | Tool `mstar_model_handoff`: the PM's **first preparation action** of a new iteration (`{operation:"start", workflowId:"<id>"}`) and the completion checkpoint (`{operation:"phase1-complete", …}`). Session identity, cwd, entry route, task-session state and coordinator authority are host-derived from the ledger, the workflow's own session envelopes and the root register; the call carries an explicit workflow id and nothing else. |
+| Ownership | One explicitly named workflow and control root own the coordinator. Missing, foreign or ambiguous ownership fails closed — no `workflows[0]`, latest-mtime, unique-new-row or "most recent" inference, and a concurrent sibling iteration stays untouched. Only the bound coordinator session changes model; role mappings, other sessions, subagents, goal objective and workflow snapshot status are never written. |
+| Full readiness | Fire requires the sequential specialist returns for that iteration, PM-confirmed Prepare gates for every registered plan with `compass status: locked`, a distinct same-repository integration checkout on its recorded branch, and a remote tip equal to the validated integration HEAD. `evaluatePhaseGate` is a later-phase gate and is never readiness evidence; a draft compass, a lock alone, a missing checkout or an unpushed commit is not ready. |
+| Cancellation | While pending, an unowned model change — history or live model — cancels the not-yet-executed switch, and the arm's own transition can never cancel it. Cancellation is deliberately conservative (it can also catch another extension's change; there is no exact user-selection event), and it never clears the saved preference. Navigation arriving during an invoked action is refused immediately; navigation arriving first fences the action instead of letting it start. |
+| Replay | Full session ledger with exact session-id filtering. A persisted attempt with no recorded outcome restores as `uncertain` — never retried, never reported as a successful handoff because the current model happens to match. Tree/branch/reload replay the ledger; a fork or new session id inherits nothing. |
+| Failure visibility | Refusals appear in the tool result, state transitions also as a durable session notice; the session keeps the model it actually has and there is no automatic retry loop. Missing auth, an unresolvable role and missing evidence are reported as failures, never as a handoff. |
+| Modes | Arming is observed from the host's `input` event, so it is documented for the interactive entries above only — no print/JSON/RPC automatic-behaviour claim exists (E1 boundary). The completion checkpoint is an ordinary tool call whose result the host renders like any other tool result. |
+
+Do not describe this feature as a `pause` flag, as a goal, or as a switch performed by any other session, and do not require a provider-side or upstream change to use it.
+
+## Phase-2 plan instances (native settings + optional transport)
+
+An extension entry from this package: `extensions/phase2-orchestration.js` (manifest `omp.extensions`; engine inlined, and its one runtime host import — `getPluginSettings` from `@oh-my-pi/pi-coding-agent/extensibility/plugins`, the public uncached settings reader — resolved by the running host, declared as an optional peer). It supplies one bounded Phase-2 advisory plus the `mstar_phase2` bookkeeping tool. It never spawns, merges, rewrites workflow state or releases leases — the optional skill below performs every CLI call, and engine scope/lease/revision/worktree/merge verbs stay authoritative.
+
+Phase 2 only. Ordinary sessions, leaf/subagent sessions, scoped-plan PM sessions and Phase 1/3–6 never activate the reminder or a launch.
+
+| Surface | Contract |
+|---|---|
+| Native path | `/settings` → **Plugins** → **`@mstar-harness/omp`** — the rows are the schema keys: `phase2PlanInstances` (boolean, default `false`) and `maxPlanInstances` (number, default `2`, minimum `1`, step `1`) with **no ceiling of 2**. |
+| Launch-only opt-in | `phase2PlanInstances` gates **extra primary launches only**. Native background task concurrency and the bounded reminder are independent of it: a disabled opt-in neither silences the reminder nor limits ordinary `task` dispatch. |
+| Configurable capacity | `maxPlanInstances` counts concurrently active **plan-scoped primaries** plus owned pending launch intents — the union by plan id, each counted once. The iteration coordinator and task subagents are excluded. Lowering it stops further launches and never kills running work. |
+| Invalid values | A present-but-malformed key (non-boolean, non-integer, below 1, unparsable) **fails visibly** and authorizes no launch — never coerced to the default, never an unbounded mode, never a silent hard limit. Absent keys take the schema defaults. |
+| Reminder | At most one advisory per **changed** opportunity observation, emitted at `agent_end` only; the observation key is recorded before the message, so identical unchanged state never re-fires and A→B→A does not re-nudge A. No timer, no polling, no invented job-settled event; a `null` snapshot means "unavailable", never "no jobs". Native completion delivery stays authoritative and is never duplicated. The advisory text asserts nothing about a plan being ready. |
+| Checkpoint pointer | The advisory only points at the shared Phase-2 rescheduling checkpoint (`mstar-iteration/references/phase-2-worktree-lease.md` §2.4). It never copies the decision matrix — this section does not either. |
+| Scope limitation (host behaviour) | The native `/settings` → Plugins panel lists **user-scope** plugin installs; a `--scope project` install has no row there (documented, not worked around). The runtime still reads the saved preference through the host's own settings helper. |
+
+### PM call sequence (tool `mstar_phase2`)
+
+Not a user activation command: nothing is spawned, merged, leased or written to engine state by the tool, and no session/flag/goal/prose can substitute for the calls below.
+
+1. **`bind`** — the coordinator's **first Phase-2 host action**, independent of any setting or model handoff, and also required on a no-argument `/iteration-drive` resume: `{operation:"bind", workflowId, coordinatorSessionPath}`. Authority is derived host-side from the session envelope plus the named snapshot, never from the call: it re-reads the engine coordinator/session identity, the workflow id, the control harness root, the accepted phase (`phase-2-execute`; an unknown/missing phase is disabled) and the checkout root (main worktree or the recorded integration worktree), and it rejects leaf/`session_init` sessions, foreign workflows, scoped-plan PM sessions and terminal workflows. It records a session **identity pointer** only — this is plugin observation binding, not engine `plan bind`, and it writes no engine credential.
+2. **`checkpoint`** — acknowledge that PM ran the shared scheduling procedure against the sample taken at that moment: `{operation:"checkpoint", reason, decision, note}`, `reason` ∈ `before-wait | result-settled | dependency-changed | ownership-changed | capacity-changed`, `decision` ∈ `dispatched | wait | blocked`. The runtime attaches the sampled key; the caller cannot choose or reset it. `blocked` suppresses advisory continuation until a new explicit user turn or a later checkpoint clears it — never a timer or incidental snapshot churn. A checkpoint carries a decision and note, never a ready list.
+3. **`reserve-launch`** — `{operation:"reserve-launch", planId, transport:"herdr"|"tmux", skill:{name,source}, capability:{executable,version,target}}`. Admission additionally requires the enabled opt-in, a valid latest capacity, a coordinator-prepared row with no plan binding/lease/handoff, the identical prepared Assignment hash, an existing canonical **distinct** feature worktree on its assigned branch, and the transport prerequisites. Only `applied:true` authorizes a side effect; an identical duplicate returns the recorded intent with `applied:false` and authorizes nothing, while a different live intent/binding for that plan refuses. Intents are journaled at `<workflow dir>/omp-launches.json` — a plugin-owned transport journal, never a lifecycle register.
+4. **`record-launch`** — one transition per observed step, each recorded **before** its matching side effect: `{operation:"record-launch", intentId, observation, target?, evidencePath}` with `observation` ∈ `starting | created | submitting | submitted | refused | uncertain`. Strict forward order `reserved → starting → created → submitting → submitted`; `starting` permits pane creation, `created` (which **requires the returned opaque target**) permits starting OMP in it, `submitting` permits the single scoped prompt. Only a newly persisted transition reports `applied:true`; PM acts only on that. `refused` is legal only for an observed failure that provably precedes any process/prompt side effect; from `submitting` onward a lost outcome is `uncertain`, which is terminal. A recorded target is never re-pointed, and settings/capacity/ownership are re-read before each side-effecting transition.
+
+### Optional transport (skill-driven — no compiled bridge)
+
+Every prerequisite is required and checked per launch: the **corresponding optional skill actually present in the catalog and read** (the `herdr` skill today; a tmux skill only if one truly exists — binary existence is not skill availability), the CLI executable available, and this session actually inside the matching managed environment (`HERDR_ENV=1`; `TMUX` set for tmux). Two managed environments visible at once is a visible refusal, not a focus-based choice. A missing prerequisite is a **visible no-op**: no process start, no silently substituted plan, native background scheduling intact, never a fabricated success. This never becomes a mandatory load-order dependency of the standalone `mstar-*` skill set.
+
+**Herdr** (the currently available contract — read the skill and its current group help/status at use): create the pane with `herdr pane split --current --direction <chosen> --cwd <prepared-worktree> --no-focus` and use the returned `result.pane.pane_id` verbatim as the opaque target; then `herdr agent start <unique-name> --kind omp --pane <returned-id>`; then submit exactly once with `herdr agent prompt <unique-name> "/iteration-drive --assignment <absolute-prepared-assignment>"`, without waiting for plan completion. Preserve CLI argument boundaries.
+
+**tmux** (conditional): only where a matching tmux skill is actually present **and read**, the CLI supports that skill's command forms, `TMUX` identifies this caller, and its explicit target is resolved. Use the skill's detached/non-focus creation with explicit cwd and returned pane id, launch OMP in it, and submit the same absolute scoped route; inspect help instead of guessing flags, and never shell-type into the user's focused pane. **No tmux skill exists in the current catalog**, so tmux is unavailable here — an unsupported seam to be named honestly, not a failed implementation and not a silent Herdr substitution.
+
+**Uncertainty, scope and ownership**: PM uses only returned opaque targets, records the observed command output before proceeding, and treats `agent_not_ready`, blocked UI, a timeout, a vanished response or a stalled submission as terminal — reported, never re-sent, never retried, with no fabricated id and no credential passed (no session JSON path, no `--expect` revision, no `--resume`). A created empty pane may be removed only with proven ownership and no possibly-active primary; panes are never killed to free capacity. Pane ready/idle/done means prompt transport is ready — never plan completion, lease release or ownership. The child obtains its own engine session through a fresh `plan bind`, runs only the prepared scope and stops at its durable handoff; the coordinator alone keeps serial integration and Phase 3–6 closure.
+
+**Evidence boundary**: this transport guidance is supported by **simulated** scripted skill/CLI observation traces (PM action sequences scored for command order, prepared cwd, non-focus creation, credential absence, opaque-target reuse, stopping on uncertainty and no blind resend) — not by a native end-to-end Herdr/tmux run, not by any probe of user terminals, and not by a real OMP child process.
+
 ## Files, shell, and approvals
 
 - Prefer host search/edit tools over shell find/sed when available.

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

@@ -11,6 +11,17 @@ description: "Use when starting, driving, resuming, or closing a Morning Star it
 
 **Phase detail 不在本 skill 正文**：按下方 **Phase route map** 只加载当前动作对应的一行 detail——**禁止**无条件通读全部 phase references。
 
+**Scoped primary route**（`/iteration-drive --assignment|--workflow/--plan|--resume`）→ **`references/plan-scoped-pm.md`**，且**先于**本 skill 的全局 todo / backlog / last-plan 逻辑判定。
+
+## Scoped primary route（先于全局 Phase 逻辑）
+
+`/iteration-drive` 的 scoped 形态在**本 skill 的任何全局 Phase 逻辑之前**改道：
+
+- **先选 route，再 seed todo**：不得先按整迭代 boot 建立全局 session todos / backlog / last-plan Phase 3 判断，再把 scoped 会话当作过滤器处理。
+- **scoped finish = durable handoff**（plan 保持 `InReview`、保留 `execution_lease`）。`status: Done`、两个 lease 的删除、Phase 3–6、compass / index / root 投影与迭代 PR **仅 coordinator** 拥有。
+- 无参数调用**语义不变**（Phase 2 → 3 → 4 → 5 → 6）；非法非空形态 **fail closed**，**禁止**回落整迭代路线；leaf 收到该命令 → 角色边界拒绝。
+- boot / plan-local drive / finish / coordinator 序列全文 → **`references/plan-scoped-pm.md`**。
+
 ## 设计思路
 
 mstar 实践模式通常是：一次迭代锁定几个 spec 点（`specify + clarify`），产生多个 `plan`，每个 plan 含多个 tasks。**per-plan 生命周期有完整的闭环**（Prepare → Execute → QC → Done）。Compound 不是 per-plan 活动——它是**迭代级收口**，在迭代内所有 plan Done 后，沉淀一轮知识。
@@ -44,6 +55,7 @@ Phase 6: post-merge close —— PR merged 后 §6.1–§6.4
 
 | 当前动作 | 必读 detail（按需加载，勿通读） |
 |---------|--------------------------------|
+| **scoped primary**（`/iteration-drive` 带 `--assignment` / `--workflow --plan` / `--resume`） | **`references/plan-scoped-pm.md`**（scoped boot → plan-local drive → handoff finish → coordinator 序列；**先于**整迭代 todo / last-plan 逻辑） |
 | **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 root + integration worktree + lease 全文） |
 | **close**（全部 plan Done 后收口迭代） | **`references/phase-3-iteration-close.md`**（§3.0–§3.6：entry checklist、compound、roadmap、完成标记、exit checklist + commit） |
@@ -87,7 +99,7 @@ Phase 6: post-merge close —— PR merged 后 §6.1–§6.4
 - 实际 Git ≠ `working_branch` → **同轮**更新 plan + snapshot + `execution_lease.working_branch`（如适用）
 - **跨 plan implement 并行安全闸**与 **integration merge 串行** → `references/phase-2-worktree-lease.md` §2.0 #5 /「Multi-plan parallelism」（**无论** `Worktree mode: waived`）
 - plan 内 SDD 独立 ready tasks **并行**，真实依赖与共享写目标串行 — phase-2 reference §2.4、§2.5、`mstar-sdd` Ready-task scheduling
-- **zero-residual（默认）**：单 plan QC findings 尽量当轮清干净；仅真 blocker 才 defer（须 Durable Roadmap）— 见 **`mstar-artifacts`** Findings cleanup modes
+- **allow-residual（默认）**：open R# 先登记 project register，且各决策面披露（清单 + severity + 跟踪位置；close 面另含 blocker-defer 标记）；unresolved `critical` 仍阻断 Approve；`zero-residual` 为显式 opt-in（可修当轮清干净，仅真 blocker-defer + Durable Roadmap）— 登记与披露职责 → **`mstar-artifacts`** Findings cleanup modes
 - iteration 命令共享的 PM invariants / preflight / todos / STOP → **`references/command-shared-invariants.md`**
 
 **Push cadence（§5.1a HARD）**：本地可提前修，**禁止**在 CI / AI review 波次未结束时 `git push` — 细则 → `references/phase-4-5-pr-delivery.md` §5.1a。

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

@@ -22,6 +22,8 @@ Phase 2–5 全程有效（drive + loop 共有的行）：
 
 派发细则 → **`mstar-dispatch-gates`** + **`mstar-host`**。Phase 3 细则 → **`mstar-iteration/references/phase-3-iteration-close.md`** + **`mstar-compound`**。
 
+**Scoped primary route 例外**（`references/plan-scoped-pm.md`）：scoped plan 会话只驱动**本 plan**——不 seed 全局 phase todos，不做「最后一个 plan `Done` → Phase 3」判断，不加载 compound；其 finish 是 **durable handoff**，`Done`、lease 删除与 Phase 3–6 归 coordinator。
+
 ## Assignment preflight（bash 块 — byte-identical 共享副本）
 
 `mstar-harness` bin 未安装时静默跳过；在每次 implement/QC/QA 派发前（**SDD** 下为最新 `{SDD_DIR}/task-N-brief.md` 或临时写盘的 Assignment）校验。模式由迭代 compass frontmatter 的 `enforcement` 键决定（Slice 5）：
@@ -42,6 +44,8 @@ if command -v mstar-harness >/dev/null 2>&1; then mstar-harness dispatch validat
 
 ## Session todos（重叠行；drive + loop 共有）
 
+**Scoped primary route 不 seed 本表任何条目**：其 session todos 是 plan-local 任务列表，finish = handoff，**不**追加 `phase-3-*` / `phase-4-*` / `phase-5-*` / `phase-6-*` → **`plan-scoped-pm.md`** §4–§5。下表仅适用于整迭代路线（no-args `iteration-drive` / `iteration-loop`）。
+
 | Todo id | 何时追加 | 何时可勾掉 |
 |---------|----------|------------|
 | plan-wave todos | 进入 Phase 2 | 各 plan `Done` |
@@ -50,6 +54,8 @@ if command -v mstar-harness >/dev/null 2>&1; then mstar-harness dispatch validat
 | `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 + 投影一致） |
 
+Phase/gate 转换时按 **`mstar-host`**「Phase-transition todo refresh (host-agnostic)」按上表刷新会话 todos：先按 snapshot / plan 证据勾掉已完成 phase 条目，保留未决 gate / 未来 phase 条目，再追加下一 phase 条目；todos 只是投影，不授权状态转换。
+
 ## Continuous execution STOP list（重叠行；start / drive / loop 共有）
 
 Execute **`mstar-iteration` §2.6**（Continuous execution SSOT：自 Phase 2 进入至 Phase 5 §5.5 exit 前 PM **连续编排**，进度汇报后下一条必须是 dispatch 或下一 phase 步骤，不向用户例行 yes/no check-in）。

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

@@ -124,6 +124,8 @@ iteration 正式全流程**必须**登记 `{HARNESS_DIR}/status.json`（v2 根
 
 compass frontmatter 的 `iteration_base_branch` / `target_branch` **必须与** snapshot `branch` 一致；若仅写在 compass 而 snapshot 缺失，Phase 2 §2.3 同轮 backfill。
 
+**中途增减范围（已存在且仍在 Prepare 的 workflow）**：用户/产品批准的范围扩张**不得**手改受保护状态。先以 `mstar plan bind --coordinator --workflow <id>` 建立该 workflow 的 coordinator 会话，再经受守卫入口 `mstar workflow show-prepare` 读取快照与 compass 两个字节版本，并以 `mstar workflow amend-prepare` 追加已批准的 Todo 行、登记已 review 的 integration checkout 与 `plan_parallelism`（仅 Prepare 且无执行所有权时可用；无 force/replace/init 通道）。守卫与字段权威 → **`mstar-artifacts`** `references/status-and-residuals.md`「Prepare workflow amendment」；forms / exit codes → `docs/cli.md` § `mstar-harness workflow`。
+
 ## 1.5.5 产物边界（specs · iterations · knowledge）
 
 Phase 1 与 §1.6 须遵守 **`references/iteration-artifact-boundaries.md`**（HARD）：