@mstar-harness/opencode 1.5.3 → 1.5.5

package/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to the `@mstar-harness/opencode` package are documented in t
 
 The monorepo root [CHANGELOG.md](../../CHANGELOG.md) summarizes cross-surface releases.
 
+## 1.5.5
+
+- Version alignment with harness **1.5.5** (bundled skills: control-path harness under default gitignore + `sdd-workspace` `MSTAR_CONTROL_ROOT`).
+
+See root [CHANGELOG.md](../../CHANGELOG.md) **1.5.5**.
+
+## 1.5.4
+
+- Version alignment with harness **1.5.4** (bundled skills/commands: Cursor Task flat invoke schema in `mstar-host`).
+
+See root [CHANGELOG.md](../../CHANGELOG.md) **1.5.4**.
+
 ## 1.5.3
 
 - Version alignment with harness **1.5.3** (bundled skills/commands: frontmatter YAML quotes + `/iteration-loop` scale `XL`).

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

@@ -1,6 +1,6 @@
 ---
 name: mstar-branch-worktree
-description: "Morning Star business-repo Git feature branches, worktree isolation layers **L1** (iteration cross-plan — control worktree + per-plan feature worktrees + `execution_lease`) and **L2** (within-plan — `references/parallel-writable-pre-dispatch.md`; N parallel Task invokes do NOT satisfy isolation), plan/Spec integration branches, and QC/QA checkout alignment (`Review cwd`, `Working branch`, `plan_id`, `Review range` / `Diff basis` must match verbatim across three QC reviewers and QA). Read when PM writes `Working branch` / `Branch policy`, iteration Phase 2 control vs feature worktree paths, dispatches ≥2 concurrent writable implement tracks on one repo, `Worktree isolation: required`, two or more writable streams touch one repo, dispatching QC tri-review or QA after merging to a single `HEAD`, dev/QA/ops before first `git commit`, or explaining worktree paths. Required for `project-manager` parallel implement or pre-QC orchestration; `fullstack-dev*` / `frontend-dev` / `qa-engineer` / `ops-engineer` on repo writes; `qc-specialist*` before review. Does not replace the state machine (`mstar-harness-core`)."
+description: "Morning Star business-repo Git feature branches, worktree isolation layers **L1** (iteration cross-plan — control worktree + per-plan feature worktrees + `execution_lease`; under default gitignore, process harness SSOT via absolute control paths — plans/iterations/status/sdd — while product edits stay on the feature worktree; do not waive worktree because feature lacks plans) and **L2** (within-plan — `references/parallel-writable-pre-dispatch.md`; N parallel Task invokes do NOT satisfy isolation), plan/Spec integration branches, and QC/QA checkout alignment (`Review cwd`, `Working branch`, `plan_id`, `Review range` / `Diff basis` must match verbatim across three QC reviewers and QA). Read when PM writes `Working branch` / `Branch policy`, iteration Phase 2 control vs feature worktree paths, dispatches ≥2 concurrent writable implement tracks on one repo, `Worktree isolation: required`, two or more writable streams touch one repo, dispatching QC tri-review or QA after merging to a single `HEAD`, dev/QA/ops before first `git commit`, or explaining worktree paths. Required for `project-manager` parallel implement or pre-QC orchestration; `fullstack-dev*` / `frontend-dev` / `qa-engineer` / `ops-engineer` on repo writes; `qc-specialist*` before review. Does not replace the state machine (`mstar-harness-core`)."
 ---
 
 ## Load order（必读顺序）
@@ -121,16 +121,32 @@ Established at iteration **Phase 2 entry** (Phase 1 Review & Edit may stay on th
 
 | Worktree role | Checked-out branch | Path recorded in `status.json` | Writable product edits |
 |---------------|-------------------|-------------------------------|------------------------|
-| **Control worktree** | Resolved `spec_integration_branch` (same across active plans) | `metadata.control_worktree_path` — canonical **repository root** (not `{HARNESS_DIR}`) | **Forbidden** — coordination, status/SDD SSOT, serial integration merge only |
+| **Control worktree** | Resolved `spec_integration_branch` (same across active plans) | `metadata.control_worktree_path` — canonical **repository root** (not `{HARNESS_DIR}`) | **Forbidden** — harness coordination SSOT + serial integration merge only |
 | **Feature worktree** (per plan) | Plan `Working branch` / feature branch from integration | `plans[].execution_lease.worktree_path` | **Required cwd** for that plan's product/source edits |
 
+### Harness path SSOT under default gitignore (L1)
+
+Default process artifacts (`plans/`, `iterations/`, `status.json`, `sdd/`, `notes.json`, `archived/`) are **gitignored** (`mstar-plan-conventions`「Git 跟踪策略」). `git worktree add` does **not** copy them into a new feature checkout. They live on the **control worktree filesystem** (the checkout of `spec_integration_branch`), not as Git blobs on that branch.
+
+| Path role | Resolve from |
+|-----------|--------------|
+| **Control harness root** | `<control_worktree_path>/{HARNESS_DIR}/` |
+| **Process / coordination SSOT** (read + write) | Absolute under control harness root: `status.json`, `plans/`, `iterations/`, `sdd/<plan-id>/`, `notes.json`, `archived/` |
+| **Tracked results** (`AGENTS.md`, `knowledge/`, `specs/`) | Available in any worktree via Git; absolute control paths in Assignment are still fine |
+| **Product / source edits** | Feature worktree only (`execution_lease.worktree_path`) |
+
 **Hard rules**
 
 - `execution_lease.worktree_path` **MUST** differ from `metadata.control_worktree_path`.
-- Status SSOT: `<control_worktree_path>/{HARNESS_DIR}/status.json`. SDD SSOT: `<control_worktree_path>/{HARNESS_DIR}/sdd/<plan-id>/`. A feature worktree's same-looking `{HARNESS_DIR}` path is **not** the SSOT.
-- Absolute **`Worktree path`** MUST appear in the writable Assignment and in `execution_lease.worktree_path` before first writable implement dispatch for that plan.
+- A feature worktree's same-looking `{HARNESS_DIR}` path is **not** the SSOT — **never** treat it as the source of plans/status/SDD, and **never** bootstrap a second plans/status/SDD tree there.
+- Absolute **`Worktree path`** (feature) MUST appear in the writable Assignment and in `execution_lease.worktree_path` before first writable implement dispatch for that plan.
+- When L1 lease gate is active (not `Worktree mode: waived`), Assignment **`Plan Path`** and **`SDD dir`** MUST be **absolute paths under the control harness root** (not relative `.mstar/...` resolved from the feature cwd). Prefer also writing **`Control harness root: <control_worktree_path>/{HARNESS_DIR}`**.
 - Writable dispatch for a plan requires a **verified** `execution_lease` (same read-check-replace-verify discipline as the iteration reference). Full claim tables are **not** duplicated here.
 
+**Anti-pattern (forbidden)**
+
+- Inferring `Worktree mode: waived` because “feature worktree has no plans” under default gitignore. Correct response: keep feature worktrees; route harness I/O through control absolute paths. Missing same-host write lock → **`Plan parallelism: serial`** only — that is a **separate** gate and does **not** waive worktree/lease.
+
 **Naming conventions (PM / ops; examples only — paths MUST be canonical absolute)**
 
 1. **Control worktree** — usually the primary checkout or a PM-designated path on `spec_integration_branch`; record once in `metadata.control_worktree_path`.

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

@@ -86,7 +86,7 @@ When **`Execution mode: sdd`** (`mstar-sdd`):
 
 - 独立模块可并行 **implement 轨道**（不同 dev Assignment）；**同仓 ≥2 可写并发** → **`mstar-branch-worktree`** **`references/parallel-writable-pre-dispatch.md`**（先于 invoke；同 plan 多轨 = L2）。
 - **SDD 单 plan 内**：task / implementer **仍串行**（`mstar-sdd`）；**禁止**同一 plan 内并行 SDD implementer（写冲突）。
-- **跨 plan（迭代 Phase 2）≠ 单 plan 内并行**：不同 `plan_id` 的 feature implement **允许** lease 门控并行（每 plan 独立 verified `plans[].execution_lease` + feature worktree，L1）**仅当** coordination 路径 same-host 独占写锁可用且每次协调变更持锁 → **`mstar-iteration`** §2.0 #5 · **`mstar-plan-artifacts`**。**跨主机 / 无共享 flock** → 默认 **`Plan parallelism: serial`** 或 Assignment 仍写并行 → **Blocked**（用户本轮 `Cross-host lease race: accepted` + audit `notes` 除外）。**`Worktree mode: waived` 不豁免**跨 plan 并行安全闸。**禁止**无 lease 的跨 plan 可写派发（lease 闸未 waive 时）。
+- **跨 plan（迭代 Phase 2）≠ 单 plan 内并行**：不同 `plan_id` 的 feature implement **允许** lease 门控并行（每 plan 独立 verified `plans[].execution_lease` + feature worktree，L1）**仅当** coordination 路径 same-host 独占写锁可用且每次协调变更持锁 → **`mstar-iteration`** §2.0 #5 · **`mstar-plan-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-plan-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 QC tri** after SDD task loop（`Execution mode: sdd`）；**单席**仅 `inline` / hotfix。共用 `Review cwd` / `Working branch` / `plan_id` / `Review range`（**`mstar-branch-worktree`**）。
@@ -111,6 +111,7 @@ When **`Execution mode: sdd`** (`mstar-sdd`):
 - 跨 plan 可写派发无 verified `execution_lease`；steal / 覆盖活跃 `execution_lease` 或 `integration_merge_lease`；并行 integration merge。
 - 跨 plan **并行**可写派发在 **无** same-host 独占写锁（跨主机 / 无共享 flock）且 **无** 用户本轮 `Cross-host lease race: accepted` + audit `notes` — **无论** `Worktree mode: waived`。
 - 将 **`Worktree mode: waived`** 当作跨 plan 无锁并行授权（须 serial 或 race-accepted + audit）。
+- 因 feature worktree 在默认 gitignore 下看不到 `plans/` 而设 **`Worktree mode: waived`**（应保留 feature worktree + control 绝对 `Plan Path` / `SDD dir`）。
 - `InProgress` 无 `execution_lease` 未走 orphan recovery 即 writable-dispatch。
 - 同仓多轨 writable implement：**N invoke ≠ worktree 隔离**（L2）→ **`mstar-branch-worktree`** **`references/parallel-writable-pre-dispatch.md`**。
 - 递归同角色 subagent；把 Handoff / 多轨编排措辞当 invoke。

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

@@ -143,6 +143,7 @@ Read **`mstar-host`** after this skill; detect host per its table, then Read the
 | 递归误派 / 误读 Handoff | `mstar-dispatch-gates` |
 | `quick` 跳过 Prepare | 上表 + `mstar-phase-gates` |
 | 多 worktree 未归并就 QC | `mstar-branch-worktree` |
+| 因默认 gitignore 致 feature 缺 plans 而 `Worktree mode: waived`（应保留 feature worktree + control 绝对 Plan Path / SDD dir；无 flock 仅 → `Plan parallelism: serial`） | `mstar-branch-worktree` · `mstar-iteration` §2.0 #5 · `phase-2-worktree-lease` |
 | 并行 writable implement 无隔离（L2 同 plan 多轨：N invoke ≠ worktree；L1 跨 plan：无 verified `execution_lease` + feature worktree） | `mstar-branch-worktree` L1/L2 · `mstar-iteration` §2.6 · `references/parallel-writable-pre-dispatch.md` |
 | 跨 plan 可写派发无 verified `execution_lease` / steal 活跃 lease / 并行 merge 入 `spec_integration_branch` | `mstar-iteration` · `mstar-plan-artifacts`（leases）· `mstar-branch-worktree` L1 |
 | `InProgress` 无 `execution_lease` 未恢复即可写派发 | `mstar-plan-artifacts` — orphan recovery |

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

@@ -64,7 +64,7 @@ When Assignment has **`SDD implementer session: sticky`** (`mstar-sdd/references
 
 ## Dispatch execution（canonical）
 
-Cursor PM dispatch = **`Task`** with `subagent_type` matching the Assignment `Execute as` role.
+Cursor PM dispatch = **`Task`** with `subagent_type` matching the Assignment `Execute as` role. Flat JSON field shape → **Task invoke schema (Cursor)** below.
 
 - **1 Assignment ⇒ 1 Task**; parallel batches ⇒ **N Tasks in one message** (`parallel-dispatch.md`, `mstar-dispatch-gates`).
 - Assignment Markdown **does not** start work. PM thread **must not** implement, review, or edit specialist deliverables by loading another role reference in the same session (`Acting as role: …` is **not** dispatch).
@@ -73,6 +73,84 @@ Cursor PM dispatch = **`Task`** with `subagent_type` matching the Assignment `Ex
 - Concurrent writers / QC cwd alignment → **`mstar-branch-worktree`** (not a separate “mode”).
 - Implement subagents: recipient is already `Execute as`; **no** recursive Task with same `subagent_type`. Assignment wins (`Delegation: forbidden` unless stated).
 
+## Task invoke schema (Cursor)
+
+Cursor’s live **Task** tool expects a **flat** JSON argument object. `prompt` and `subagent_type` are **sibling fields** — not nested, not stringified. Official behavior docs cover subagents/parallel/resume; the flat field shape below is Morning Star’s operational SSOT for Cursor (live-tool contract).
+
+### Canonical flat shape
+
+```json
+{
+  "description": "3-5 word UI title",
+  "prompt": "<full Assignment Markdown body>",
+  "subagent_type": "<Execute as role id or built-in>",
+  "model": "<optional host slug>",
+  "run_in_background": false
+}
+```
+
+### Required vs optional fields
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| `prompt` | yes | Full Assignment Markdown string (IDENTITY, gates, Plan Path, Working branch, …) |
+| `subagent_type` | yes | Must equal Assignment `Execute as` (Morning Star role id when using custom agents) |
+| `description` | recommended | Short UI title only (3–5 words); never the Assignment body |
+| `model` | optional | Host slug from Assignment **Model tier** mapping |
+| `run_in_background` | optional | Default false unless PM intentionally backgrounds |
+| `resume` | sticky continue only | Omit on fresh dispatch; see sticky section |
+
+### Must-have example (single dispatch)
+
+```text
+Task(
+  description: "Implement auth middleware",
+  prompt: "<full Assignment body>",
+  subagent_type: "fullstack-dev",
+  model: "<optional>",
+  run_in_background: false
+)
+```
+
+Rules:
+
+- `subagent_type` **=** Assignment `Execute as` — never OpenCode’s `subagent` key.
+- `prompt` = plain Markdown Assignment text, **not** a JSON object string of the whole call.
+- `description` = UI title only; do not put the Assignment there.
+
+### Parallel batch (N Tasks, one message)
+
+When `N ≥ 2`, emit **N** separate Task tool calls in **one** assistant message (`parallel-dispatch.md`). Each call is still a flat object with its own `prompt` + `subagent_type`.
+
+### Anti-patterns (do not send)
+
+| Anti-pattern | Correct |
+|--------------|---------|
+| Args as one stringified JSON blob | Flat sibling fields on the Task tool |
+| Field name `subagent` (OpenCode) | `subagent_type` |
+| `CallMcpTool` / MCP wrap for Task | Native Task tool only |
+| Missing `subagent_type` | Always set; match `Execute as` |
+| Assignment JSON stuffed only into `prompt`, no top-level `subagent_type` | Both `prompt` and `subagent_type` present |
+| Nested `{ "arguments": { ... } }` Task payload | Flat object at tool-call top level |
+| Treating paste-only `## Assignment` as dispatch | Must emit Task call(s) |
+
+### Self-check before send
+
+1. Tool name is **Task** (not MCP, not OpenCode `task`+`subagent`).
+2. Top-level keys include **`prompt`** and **`subagent_type`** (siblings).
+3. `subagent_type` equals Assignment `Execute as`.
+4. `prompt` is Markdown Assignment text, not stringified JSON of the whole call.
+5. If sticky continue: `resume` + continuation prompt per sticky section; else omit `resume`.
+6. If `N ≥ 2`: this message contains **exactly N** Task calls (`parallel-dispatch.md`).
+
+### Sticky / resume (pointer)
+
+First vs resume field set → **SDD sticky implementer (Cursor Task resume)** above. Do not restate those tables here.
+
+- Fresh: `subagent_type` + full implementer prompt; capture agent id.
+- Continue: `resume: <host_agent_id>` + continuation prompt; still flat sibling fields.
+- Reviewers: never `resume`.
+
 ## Clarify
 
 - No `question` tool: structured Markdown or Cursor UI.

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

@@ -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`; 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.
+3. Issue **`N` host invocations first** — OpenCode: **N `task` tool** calls with **subagent**; Cursor: **N `Task`** with `subagent_type` (JSON field shape → `cursor.md` § Task invoke schema); 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

@@ -216,7 +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`**。
+5. **Control-worktree + lease defaults**（iteration 命令；可被 `Worktree mode: waived` 豁免）：除非本轮 Assignment 显式 `Worktree mode: waived`（或等价用户指令），Phase 2 **必须**在入口建立 control worktree、经 control 路径读写默认 gitignored 的 harness 进程产物（`status.json`、`{PLAN_DIR}`、`{ITERATION_DIR}`、`{SDD_DIR}` 等），并在可写派发前 claim `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 或 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` 当作跨主机无锁并行的授权。细则 → **`references/phase-2-worktree-lease.md`**。
 
 任一 false → **stop**。Phase 1 / Prepare 未完成 → 先完成 Phase 1 或 per-plan Prepare，再进入本 Phase。
 
@@ -253,9 +253,13 @@ SSOT = `{HARNESS_DIR}/status.json` + `{PLAN_DIR}/`。todos 只追踪本轮下一
 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 路径解析：
+4. 此后 **harness 进程产物 SSOT**（默认 gitignored）均经 control 绝对路径解析：
    - `<control_worktree_path>/{HARNESS_DIR}/status.json`
+   - `<control_worktree_path>/{PLAN_DIR}/`（主 plan）
+   - `<control_worktree_path>/{ITERATION_DIR}/`（compass / iteration package）
    - `<control_worktree_path>/{HARNESS_DIR}/sdd/<plan-id>/`
+   - 同树：`notes.json`、`archived/`（若使用）
+   Feature worktree 只承载产品/源码编辑；其同名 `{HARNESS_DIR}` **不是** SSOT。Assignment **`Plan Path`** / **`SDD dir`** 须写 control 绝对路径。
 5. 若 integration 分支尚不存在：在 control worktree 内 `git checkout -b <spec_integration_branch> <iteration_base_branch>`（**必须**从记录的 base 创建）
 
 **Git 操作（无 control worktree 时 — 仅 `Worktree mode: waived`）**：
@@ -279,7 +283,7 @@ SSOT = `{HARNESS_DIR}/status.json` + `{PLAN_DIR}/`。todos 只追踪本轮下一
    - 若 `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 路径）：
+3. **Implement → InReview**（`§ 2.5`；产品编辑在 feature worktree；plans / status / iterations / 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}`
@@ -561,5 +565,6 @@ PR **merge** 本身可仍由用户手动执行，除非 Assignment 明确授权
 - **不要把 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 路径为准）
+- **不要从 feature worktree 的 `{HARNESS_DIR}` 路径当作 plans / status / iterations / SDD SSOT**（control worktree 绝对路径为准；默认 gitignore 下 feature 缺 plans **不得**推断 `Worktree mode: waived`）
+- **不要把「无 flock」与「gitignore / feature 缺 plans」捆成一次 waive**（无锁 → `Plan parallelism: serial` only；gitignore → control-path harness）
 - **不要并行 merge 入 `spec_integration_branch`**（merge 必须经 `integration_merge_lease` 串行）

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

@@ -28,13 +28,21 @@ starts at **Phase 2 entry**.
    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:
+5. Resolve coordination paths from that root (default-gitignored process artifacts live on the **control filesystem**, not as Git blobs):
    - status SSOT: `<control_worktree_path>/{HARNESS_DIR}/status.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>/`
+   - also under control harness root when used: `notes.json`, `archived/`
 
 All sessions MUST reread the **control copy** of `status.json` immediately before
 claim, release, transfer, plan-status transition, or merge-lease mutation.
 
+**Do not** set `Worktree mode: waived` because a feature worktree lacks
+`plans/` under default gitignore — keep feature worktrees and pass absolute
+control **`Plan Path`** / **`SDD dir`** in Assignments
+(`mstar-branch-worktree` 「Harness path SSOT under default gitignore」).
+
 ### Same-host exclusive write lock
 
 All control-path lease mutations (claim, release, transfer, merge-lease
@@ -49,7 +57,9 @@ 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
+default **`Plan parallelism: serial`** (preferred when waived). **No flock
+does not waive** control 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
 `Cross-host lease race: accepted` (or equivalent) + audit on `plans[].notes`.
@@ -68,8 +78,11 @@ mismatch → **STOP**.
   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.
+- Product/source edits run from the feature worktree; plans, iterations,
+  status, and SDD coordination reads/writes run through **absolute control
+  paths** (never relative `.mstar/...` from the feature cwd when L1 is active).
+- Assignment MUST include absolute feature **`Worktree path`** and absolute
+  control **`Plan Path`** / **`SDD dir`** before writable implement dispatch.
 - Default **L1**: one writable track per plan. Within-plan multi-writable tracks
   still follow L2 `parallel-writable-pre-dispatch` (`mstar-branch-worktree`).
 

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

@@ -207,7 +207,7 @@ Cooperative coordination through the **control worktree** copy of `{HARNESS_DIR}
 
 **When fields apply:** iteration Phase 2 (after control worktree entry, or primary checkout when `Worktree mode: waived`). Control worktree + lease fields are waived only by explicit current-turn user instruction (`Worktree mode: waived` or equivalent). `Plan parallelism: serial` does **not** waive leases. **`Worktree mode: waived` does not waive the cross-plan parallel safety gate** (see hard gate below).
 
-**Path SSOT:** status and SDD reads/writes use `<control_worktree_path>/{HARNESS_DIR}/…`. A feature worktree's same-looking `{HARNESS_DIR}` path is **not** the SSOT.
+**Path SSOT:** Default-gitignored process artifacts — `status.json`, `plans/`, `iterations/`, `sdd/`, `notes.json`, `archived/` — read/write via `<control_worktree_path>/{HARNESS_DIR}/…` (absolute). A feature worktree's same-looking `{HARNESS_DIR}` path is **not** the SSOT. Missing plans under a feature checkout (gitignore) is **not** grounds for `Worktree mode: waived` — keep feature worktrees and use control absolute **`Plan Path`** / **`SDD dir`**. Detail → **`mstar-branch-worktree`** 「Harness path SSOT under default gitignore」.
 
 ### Same-host exclusive write lock (control `status.json`)
 

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

@@ -92,6 +92,8 @@ PM 在需要持久化追踪时：
 
 Legacy `.agents/` 项目：将上表路径前缀 `.mstar/` 换为 `.agents/`。
 
+**多 worktree（iteration L1）**：默认 gitignored 的进程产物**不会**随 `git worktree add` 进入 feature 检出。读写须经 **control worktree** 绝对路径（`<control_worktree_path>/{HARNESS_DIR}/…`）；产品代码改在 feature worktree。细则与反模式（禁止因 feature 缺 plans 而 `Worktree mode: waived`）→ **`mstar-branch-worktree`**「Harness path SSOT under default gitignore」。
+
 **Canonical `.gitignore` snippet**（skills 与 CLI `init` 对齐）：
 
 ```gitignore

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

@@ -75,7 +75,7 @@ The **`**You are a leaf executor. You MUST NOT:**`** section (previously just pr
 **Delegation**: forbidden | allowed (...)
 **Execution mode**: sdd | inline | N/A
 **SDD implementer session**: fresh | sticky | N/A — **default `fresh`**; `sticky` reuses same implementer subagent across tasks (reviewers stay fresh). See `mstar-sdd/references/sticky-implementer-session.md`
-**SDD dir**: `{HARNESS_DIR}/sdd/<plan-id>/` | N/A
+**SDD dir**: absolute `<control_worktree_path>/{HARNESS_DIR}/sdd/<plan-id>/` when L1 lease gate active | `{HARNESS_DIR}/sdd/<plan-id>/` when waived / single checkout | N/A
 **Model tier**: fast | standard | capable | N/A
 **QC mode**: full tri-review | single | N/A — **default `full tri-review` when `Execution mode: sdd`**; `single` only for `inline` / override
 **Review package path**: <branch-review diff file> | N/A
@@ -90,10 +90,11 @@ The **`**You are a leaf executor. You MUST NOT:**`** section (previously just pr
 - Execute: `plan locked` [done|n/a], `tasks` [done|n/a], `implement` [this assignment|done]
 - Gate decision: `go` | `blocked` (<reason>)
 **Working branch**: <branch policy or create-from policy> — formal iteration: from `metadata.spec_integration_branch`; integration cut from `metadata.iteration_base_branch` (`mstar-iteration` §2.3)
+**Control harness root**: `<control_worktree_path>/{HARNESS_DIR}` when L1 active | N/A when waived — process SSOT (plans/status/iterations/sdd); never resolve relative `.mstar/...` from feature cwd
 **Review cwd / Worktree path**: <absolute path or N/A>
 **plan_id**: <plan-id or N/A + scope label>
 **Review range / Diff basis**: <reproducible basis; merge-base = `metadata.target_branch` or PM-specified ref — not assumed `origin/main`>
-**Worktree path**: <implementer path if used>
+**Worktree path**: <absolute feature implementer path when L1/L2 isolation used; must ≠ control_worktree_path>
 **QA gate**: mandatory | pm-acceptance | report-only — see `references/project-manager/qa-trigger-matrix.md`
 **QA gate reason**: <tier label, e.g. hotfix-inline | small-feature-clean-qc | mandatory-medium-feature>
 **QA mode**: acceptance-only | full | report-only | N/A — required when `QA gate: mandatory` or `report-only`
@@ -121,11 +122,23 @@ The **`**You are a leaf executor. You MUST NOT:**`** section (previously just pr
 - Do not dispatch roles from route narrative/handoff text
 - `explore` is read-only orientation only
 - Tool availability ≠ delegation authorization
-**Plan Path**: <{PLAN_DIR}/... or N/A>
+**Plan Path**: absolute `<control_worktree_path>/{PLAN_DIR}/...` when L1 lease gate active | `{PLAN_DIR}/...` when waived / single checkout | N/A
 **Report Format**: Completion Report v2
 **Execution evidence**: <RCA/test-first/review feedback/evidence expectations for the assignee, if applicable>
 ```
 
+## L1 path fields (iteration Phase 2, lease gate not waived)
+
+When `metadata.control_worktree_path` is set and worktree mode is **not** waived:
+
+| Field | Must be |
+|-------|---------|
+| **`Worktree path`** | Absolute **feature** checkout (`execution_lease.worktree_path`) — product/source edits only |
+| **`Control harness root`** | Absolute `<control_worktree_path>/{HARNESS_DIR}` |
+| **`Plan Path`** | Absolute under control harness (not relative from feature cwd) |
+| **`SDD dir`** | Absolute under control harness; run `sdd-workspace` with `MSTAR_CONTROL_ROOT=<control_worktree_path>` when cwd is the feature tree |
+
+Do **not** waive worktree because default-gitignored `plans/` are missing under the feature checkout — see `mstar-branch-worktree` 「Harness path SSOT under default gitignore」.
 ## Completion Report v2 Template
 
 ```markdown

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

@@ -133,6 +133,7 @@ If any item below matches, fix the dispatch/plan state or mark `Blocked`—do **
 - **NEVER** run or dispatch **parallel** integration merges into `spec_integration_branch` — merge is **serial** via `metadata.integration_merge_lease` from the control worktree (`mstar-iteration` §2.6 · `mstar-branch-worktree` L1).
 - **NEVER** cross-plan writable implement without distinct per-plan verified `execution_lease` + feature worktree; `Plan parallelism: serial` forces serial **scheduling** only — it does **not** waive control worktree or lease gates (`mstar-iteration` §2.0 #5).
 - **NEVER** dispatch **cross-plan parallel** writable implement when same-host exclusive write lock is **not** available on the coordination `status.json` path (cross-host / no shared flock) — default **`Plan parallelism: serial`** or **Blocked** if Assignment still claims parallel; exception only on current-turn user `Cross-host lease race: accepted` (or equivalent) + audit `plans[].notes` — **including when `Worktree mode: waived`** (`mstar-plan-artifacts` — “Hard gate — cross-plan parallel writable implement”).
+- **NEVER** set `Worktree mode: waived` because default-gitignored `plans/` are missing under a feature worktree — keep feature worktrees; put absolute control **`Plan Path`** / **`SDD dir`** / **`Control harness root`** on Assignments (`mstar-branch-worktree` 「Harness path SSOT under default gitignore」). No flock → serial scheduling only, not worktree waiver.
 
 ---
 

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

@@ -39,7 +39,7 @@ Batch all findings for the human in one message. If clean, proceed silently.
 ## Per-task loop (PM only)
 
 1. Record `BASE_SHA` (never use `HEAD~1` later)
-2. `sdd-workspace <plan-id>` → `SDD_DIR`
+2. `sdd-workspace <plan-id>` → `SDD_DIR`（iteration L1 从 feature cwd 调用时：`MSTAR_CONTROL_ROOT=<control_worktree_path>` 或 `sdd-workspace <plan-id> <control_worktree_path>`；缺 status.json 的 linked worktree 会 fail closed）
 3. `task-brief <plan> N` → brief file
 4. Dispatch implementer:
    - **`SDD implementer session: fresh`** (default) — new subagent; templates: `references/implementer-prompt.md`
@@ -113,7 +113,7 @@ From repo: `skills/mstar-sdd/scripts/` (bundled in OpenCode as `harness-skills/m
 
 | Script | Usage |
 |--------|--------|
-| `sdd-workspace` | `PLAN_ID` → creates `{SDD_DIR}`, prints path |
+| `sdd-workspace` | `PLAN_ID [CONTROL_ROOT]` → creates `{SDD_DIR}` under control harness when set (`MSTAR_CONTROL_ROOT` or 2nd arg); fail closed on linked worktree without `status.json` |
 | `task-brief` | `PLAN_FILE TASK_N [OUTFILE]` |
 | `review-package` | `BASE HEAD [OUTFILE]` |
 

package/harness-skills/mstar-sdd/references/file-handoffs.md

@@ -5,6 +5,10 @@ PM and subagents move artifacts as **files**, not pasted text. Pasted content st
 ## Before implementer dispatch
 
 1. `export SDD_DIR=$(skills/mstar-sdd/scripts/sdd-workspace <plan-id>)`
+   - Iteration L1 (implementer cwd = feature worktree):  
+     `export MSTAR_CONTROL_ROOT=<control_worktree_path>`  
+     or `sdd-workspace <plan-id> <control_worktree_path>`  
+     so `{SDD_DIR}` lands on the control harness (default-gitignored plans/status/sdd). Do not create a second SDD tree under the feature checkout.
 2. `skills/mstar-sdd/scripts/task-brief <plan-file> <N> "$SDD_DIR/task-N-brief.md"`
 3. Record `BASE_SHA` (`git rev-parse HEAD` before dispatch).
 4. Dispatch implementer with:

package/harness-skills/mstar-sdd/scripts/sdd-workspace

@@ -1,18 +1,82 @@
 #!/usr/bin/env bash
 # Resolve and ensure {SDD_DIR} for Morning Star SDD artifacts.
-# Usage: sdd-workspace PLAN_ID
+# Usage: sdd-workspace PLAN_ID [CONTROL_ROOT]
+#   CONTROL_ROOT — optional absolute repo root of the control worktree
+#   (or set MSTAR_CONTROL_ROOT). Required when cwd is a linked feature
+#   worktree that lacks harness status.json (default gitignore).
 # Prints absolute path to {HARNESS_DIR}/sdd/<plan-id>/ (or legacy .agents/sdd/).
 set -euo pipefail
 
-if [ $# -ne 1 ]; then
-  echo "usage: sdd-workspace PLAN_ID" >&2
+if [ $# -lt 1 ] || [ $# -gt 2 ]; then
+  echo "usage: sdd-workspace PLAN_ID [CONTROL_ROOT]" >&2
+  echo "  Set MSTAR_CONTROL_ROOT=<control_worktree_path> when running from a feature worktree." >&2
   exit 2
 fi
 
 plan_id=$1
-root=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+control_root="${2:-${MSTAR_CONTROL_ROOT:-}}"
 
-if [ -d "$root/.mstar" ]; then
+abs_dir() {
+  (cd "$1" && pwd -P)
+}
+
+if [ -n "$control_root" ]; then
+  if [ ! -d "$control_root" ]; then
+    echo "sdd-workspace: CONTROL_ROOT / MSTAR_CONTROL_ROOT is not a directory: $control_root" >&2
+    exit 1
+  fi
+  root=$(abs_dir "$control_root")
+else
+  root=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+  root=$(abs_dir "$root")
+fi
+
+resolve_harness_with_status() {
+  local r=$1
+  if [ -f "$r/.mstar/status.json" ]; then
+    printf '%s\n' "$r/.mstar"
+    return 0
+  fi
+  if [ -f "$r/.agents/status.json" ]; then
+    printf '%s\n' "$r/.agents"
+    return 0
+  fi
+  return 1
+}
+
+# Linked worktree from `git worktree add`: --git-dir ≠ --git-common-dir
+is_linked_worktree() {
+  local r=$1
+  local git_dir common
+  git_dir=$(git -C "$r" rev-parse --git-dir 2>/dev/null) || return 1
+  common=$(git -C "$r" rev-parse --git-common-dir 2>/dev/null) || return 1
+  case "$git_dir" in
+    /*) ;;
+    *) git_dir="$r/$git_dir" ;;
+  esac
+  case "$common" in
+    /*) ;;
+    *) common="$r/$common" ;;
+  esac
+  # Path contains /worktrees/ → definitely linked
+  case "$git_dir" in
+    */.git/worktrees/*|*/worktrees/*) return 0 ;;
+  esac
+  local gd_parent cm_abs
+  gd_parent=$(abs_dir "$(dirname "$git_dir")")
+  cm_abs=$(abs_dir "$common")
+  [ "$gd_parent/$(basename "$git_dir")" != "$cm_abs" ] && [ "$git_dir" != "$cm_abs" ]
+}
+
+if harness=$(resolve_harness_with_status "$root"); then
+  :
+elif [ -z "$control_root" ] && is_linked_worktree "$root"; then
+  echo "sdd-workspace: linked worktree at $root has no {HARNESS_DIR}/status.json (default gitignore)." >&2
+  echo "  Refusing to create a second SDD tree under the feature checkout." >&2
+  echo "  Re-run with MSTAR_CONTROL_ROOT=<control_worktree_path> or: sdd-workspace $plan_id <control_worktree_path>" >&2
+  echo "  See mstar-branch-worktree «Harness path SSOT under default gitignore»." >&2
+  exit 1
+elif [ -d "$root/.mstar" ]; then
   harness="$root/.mstar"
 elif [ -d "$root/.agents" ]; then
   harness="$root/.agents"

package/package.json

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