@mstar-harness/opencode 1.5.4 → 1.5.6

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.6
+
+- Version alignment with harness **1.5.6** (bundled skills: `Findings cleanup: zero-residual` mode).
+
+See root [CHANGELOG.md](../../CHANGELOG.md) **1.5.6**.
+
+## 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`).

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,11 +143,13 @@ 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 |
 | 混淆跨 plan lease 门控并行与单 plan 内 SDD 并行 implementer | `mstar-dispatch-gates` · `mstar-sdd` |
 | residual 只写 plan 不写 SSOT | `mstar-plan-artifacts` |
+| `zero-residual` 下把可修 findings 登记为 open R# / 草草 `Approve with residuals` | `mstar-plan-artifacts` Findings cleanup modes · `mstar-review-qc` |
 | 角色文件塞流程长文 | 用专题 skill |
 | 无证据宣称完成 | `mstar-coding-behavior` / verification |
 | CreatePlan 不落盘 / 无 `{HARNESS_DIR}` mirror | `mstar-host` · `cursor-plan-mode-bridge` |

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

@@ -208,6 +208,8 @@ 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 即可执行迭代。
 
+**Findings cleanup（默认）**：Phase 2 每个 plan Assignment 默认 **`Findings cleanup: zero-residual`**（可修 findings 当轮 fix→re-review 清干净；仅真 blocker-defer + Durable Roadmap 可留 open R#）。compass 或 Assignment 可显式覆写为 `allow-residual`。SSOT → **`mstar-plan-artifacts`**「Findings cleanup modes」。
+
 ### 2.0 前置条件（五道闸）
 
 进入 Autonomous Execute 前必须满足：
@@ -216,7 +218,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 +255,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 +285,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}`
@@ -321,6 +327,7 @@ Iteration Phase 2 附加：
 - PM **NEVER** 在 PM 线程实现产品代码（delegate dev；hotfix 例外见 **`mstar-phase-gates`**）
 - `Subagent invokes issued: 0` 而 Assignment 已写出 → **`dispatch incomplete`**；下一条补发 invoke，禁止 PM 顶替
 - QC 初轮：**SDD → N=3**；**inline → N=1**；plan QC tri 三席 **同条消息 N=3**（非 implement 轨数）
+- **`Findings cleanup: zero-residual`（默认）**：QC 后可修 Warning/Suggestion → 继续 fix→targeted re-review，直至 clean `Approve` 或仅剩真 blocker-defer；**禁止**把可修项登记为 open residual 草草 `Approve with residuals`
 
 ### 2.6 Push 纪律（Autonomous Execute）
 
@@ -332,6 +339,7 @@ Iteration Phase 2 附加：
 - 实际 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
+- **zero-residual（默认）**：单 plan QC findings 尽量在当轮清干净；仅真 blocker 才 defer 到后续迭代（须 Durable Roadmap）— 见 **`mstar-plan-artifacts`** Findings cleanup modes
 
 ---
 
@@ -366,7 +374,7 @@ PM 在迭代内全部 plan Done 后执行。**本 Phase 在 integration 分支
 **STOP**: 打印下方 checklist，且全部为 `[x]` 后，才可进入 §3.2 Compound。
 
 - [ ] 所有 compass 中登记的 plan 在 `{HARNESS_DIR}/status.json` 均为 `Done`
-- [ ] 所有 plan 的 residual findings 已收口（closed 或 accepted；见 `mstar-plan-artifacts`）
+- [ ] 所有 plan 的 residual findings 已收口：优先 empty open 列表；若仍有 open R#，须均为 Phase 2 `zero-residual` 允许的 blocker-defer + roadmap，或已 closed/accepted/waived 归档（见 `mstar-plan-artifacts` Findings cleanup modes）
 - [ ] compass `## Plans` 表状态列已与 `status.json` 同步
 - [ ] 迭代 `## Acceptance Criteria` 已达成或显式豁免（compass 或对话记录原因）
 - [ ] compass shape 已满足（frontmatter + `## Roadmap Position` + close 占位节）
@@ -561,5 +569,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/SKILL.md

@@ -26,9 +26,10 @@ description: "Morning Star plan harness artifacts — `{PLAN_DIR}` main plans an
 - **`{HARNESS_DIR}/status.json`**: `plans[]` row status + root **`residual_findings[<plan-id>]`** (open list **SSOT**).
 - **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.
+- **Findings cleanup**: Assignment **`Findings cleanup: zero-residual | allow-residual`** (+ optional `metadata.findings_cleanup`); iteration Phase 2 defaults to **`zero-residual`** → **`references/status-and-residuals.md`** (“Findings cleanup modes”).
 - **`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`**.
+Field semantics, severity mapping, findings cleanup modes, archive flow, and `jq` examples → **`references/status-and-residuals.md`**.
 
 **Templates (this skill):** `templates/status.empty.json`, `templates/notes.empty.json` — copy into `{HARNESS_DIR}/` (`templates/README.md`).

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

@@ -106,10 +106,47 @@ In old JSON, **`"severity": "warning"`** is read and rolled up as **`low`**. **F
 
 ---
 
+## Findings cleanup modes
+
+Plan-level policy for whether non-blocking QC/QA findings may remain as open residuals or must be cleared in the current plan session.
+
+### Assignment + metadata
+
+| Surface | Values |
+| ------- | ------ |
+| Assignment **`Findings cleanup`** | `zero-residual` \| `allow-residual` |
+| `plans[].metadata.findings_cleanup` | same strings (optional mirror; Assignment wins when both set) |
+
+**Defaults**
+
+| Context | Default |
+| ------- | ------- |
+| Formal **iteration Phase 2** (Autonomous Execute) | `zero-residual` (compass or Assignment may override to `allow-residual`) |
+| Standalone `/pm`, hotfix, `Execution mode: inline` | `allow-residual` |
+
+### `zero-residual` (clean-session)
+
+Intent: clear findings in the current plan session whenever possible. Open residuals only for **true blocker-defers**.
+
+1. After QC: default path is **fix-now + targeted re-review**, not `Approve with residuals`.
+2. Do **not** register open R# for items that can be fixed in this session.
+3. **`nit`**: fix in-session **or** drop with no R# (existing “no tracking needed”); **never** open residual for style-only nits.
+4. **`Approve with residuals`** only when every remaining open item is a true blocker-defer (`decision: defer`, `target` = next iteration/milestone, Durable Roadmap Gate written).
+5. **True defer** only: external dependency; product/scope decision for a later iteration; or explicit **current-turn** user defer — plus Durable Roadmap Gate.
+6. **`waived` / `risk-accepted`**: still require PM + user/architect alignment; **close/archive** (do not leave open). Prefer a cheap fix over waive-as-shortcut.
+7. Plan **Done**: prefer empty `residual_findings[<plan_id>]`. If any open R# remain, **every** entry must be blocker-defer + roadmap; otherwise keep `InReview` / `Blocked`.
+
+### `allow-residual` (legacy default)
+
+Non-blocking Warning/Suggestion may ship with open R# registration and `Approve with residuals` when no unresolved Critical remains (existing residual lifecycle unchanged).
+
+---
+
 ## `plans[].metadata` standard optional fields
 
 | Key | Type | Purpose |
 | --- | --- | --- |
+| `findings_cleanup` | `zero-residual` \| `allow-residual` | Mirror of Assignment **`Findings cleanup`**; see **Findings cleanup modes** |
 | `working_branch` | string | Implementation branch; aligns with Assignment **`Working branch`** (SSOT) |
 | `spec_integration_branch` | string | (Multi-plan same **Spec**) integration branch name; created from root `metadata.iteration_base_branch`; plan branches merge here before final PR (`mstar-plan-conventions`) |
 | `merge_target` | string | Next merge target; multi-plan + Spec → usually `spec_integration_branch`; final PR target is root `metadata.target_branch` |
@@ -207,7 +244,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-review-qc/SKILL.md

@@ -28,11 +28,13 @@ description: "Morning Star QC orchestration — **SDD mandatory plan QC tri-revi
 
 ## Residual Findings 留档门禁（PM）
 
-- 阻断项修复后仍有 **Warning / Suggestion** 或技术债 → 必须留档；**`severity`** 仅允许 `mstar-plan-artifacts/references/status-and-residuals.md` 枚举。
+- 先读 Assignment **`Findings cleanup`**（及可选 `plans[].metadata.findings_cleanup`）→ **`mstar-plan-artifacts/references/status-and-residuals.md`**「Findings cleanup modes」。
+- **`Findings cleanup: zero-residual`**（iteration Phase 2 默认）：可修 **Warning / Suggestion / Critical** → **fix-now + targeted re-review**，**禁止**把可修项登记为 open R# 或用 `Approve with residuals` 收口；**`nit`** 当场修或丢弃（无 R#）。仅 **真 blocker-defer**（外部依赖 / 须下轮产品决策 / 用户本轮显式 defer + Durable Roadmap）可登记 open R#（`decision: defer`）。此时 `Approve with residuals` **仅**允许剩余项全是该类 defer。
+- **`Findings cleanup: allow-residual`**（standalone / hotfix / inline 默认）：阻断项修复后仍有 **Warning / Suggestion** 或技术债 → 必须留档；**`Approve with residuals`** 仅当无 open **Critical**；PM 汇总结论须含 residual 清单与跟踪位置。
+- **`severity`** 仅允许 `mstar-plan-artifacts/references/status-and-residuals.md` 枚举。
 - **Open SSOT**：`{HARNESS_DIR}/status.json` 根级 **`residual_findings[<plan-id>]`**；PM 在 consolidated 决策分配 **R1…** 并写入。关闭 → **`{HARNESS_DIR}/archived/residuals/<plan-id>.json`**。
 - 主 plan 仅作人类索引；不得作为唯一 SSOT。
-- **`Approve with residuals`**：仅当无 open **Critical**；PM 汇总结论须含 residual 清单与跟踪位置。
-- 未完成 residual 留档 → 不得进入 plan **Done**。
+- 未完成 residual 留档（`allow-residual`）或未清干净可修 findings（`zero-residual`）→ 不得进入 plan **Done**。
 
 ### Residual 关闭与验证
 

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,13 +90,15 @@ 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`
+**Findings cleanup**: zero-residual | allow-residual — **default `zero-residual` on formal iteration Phase 2**; **default `allow-residual`** for standalone `/pm`, hotfix, `Execution mode: inline` (override via Assignment or `plans[].metadata.findings_cleanup`; SSOT → `mstar-plan-artifacts` Findings cleanup modes)
 **Why this agent**: <role-fit>
 **PM Task Board coverage**: <task ids>
 **Roadmap / deferred scope**: <required when staged, partial, or temporary; otherwise N/A>
@@ -121,11 +123,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/qa-trigger-matrix.md

@@ -34,6 +34,8 @@ Set **`QA gate`** on the **first implement Assignment** (or plan frontmatter) an
 
 **Upgrade rule:** If conditions change mid-round (e.g. QC becomes `Approve with residuals`, UI scope added, open R# registered), change `QA gate` from `pm-acceptance` to `mandatory` before `Done`.
 
+**Findings cleanup note:** Under Assignment **`Findings cleanup: zero-residual`** (iteration Phase 2 default), prefer clean QC `Approve` with **no open R#** — that restores the small-feature `pm-acceptance` path when other tier rules allow. Any remaining open R# (even blocker-defer) still force **`QA gate: mandatory`** like the residual row above. See `mstar-plan-artifacts` Findings cleanup modes.
+
 ## PM acceptance checklist (required before `Done` when `QA gate: pm-acceptance`)
 
 PM completes this in **Status Update** (or plan closure note). PM **does not** run bash tests or reproduction in the orchestration thread.

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

@@ -34,6 +34,7 @@ Use this reference when PM is dispatching QC, consolidating review verdicts, or
 - **NEVER** dispatch only QC#2 and QC#3 while skipping QC#1 on initial SDD tri wave — full **N=3** cross-review required (all three seats).
 - **NEVER** consolidate tri-review into `Approve` when any QC report's alignment fields differ from Assignment (character-level).
 - **NEVER** register or rewrite residual `severity` outside `mstar-plan-artifacts` machine enum.
+- **NEVER** under `Findings cleanup: zero-residual`, use `Approve with residuals` or open R# for fixable findings — fix-now + re-review; residual only for true blocker-defer + roadmap.
 - **NEVER** drop residual tracking to chat-only when `Approve with residuals` applies.
 - **NEVER** treat "two of three QC reports arrived" as sufficient — missing seat → `Blocked`.
 - **NEVER** re-dispatch all three after routine fix when only one or two had blockers — **targeted re-review** unless `QC re-review: full tri-review`.
@@ -59,6 +60,18 @@ Use this reference when PM is dispatching QC, consolidating review verdicts, or
 
 ## Residual Findings (Mandatory)
 
+Read Assignment **`Findings cleanup`** first (`mstar-plan-artifacts` — Findings cleanup modes).
+
+### When `Findings cleanup: zero-residual`
+
+- Prefer **fix-now + targeted re-review** for Critical / Warning / Suggestion that can be fixed this session.
+- **NEVER** park fixable findings as open R# or use `Approve with residuals` for them.
+- Register open R# **only** for true blocker-defers (`decision: defer` + Durable Roadmap + `target` next iteration/milestone).
+- `nit`: fix or drop (no R#).
+- Plan Done: prefer empty open list; any remaining open R# must all be blocker-defer + roadmap.
+
+### When `Findings cleanup: allow-residual` (or unset outside iteration Phase 2)
+
 When blocking issues are fixed but non-blocking warnings/suggestions remain:
 
 - Must register residual findings (do not leave as chat-only).
@@ -70,7 +83,7 @@ Each residual record should include:
 
 - `id`, `title`, `severity`, `source`, `scope`, `decision`, `owner`, `target milestone/date`, `tracking link`
 
-`Approve with residuals` is only valid when no unresolved blocking items remain.
+`Approve with residuals` is only valid when no unresolved blocking items remain (and under `zero-residual`, only when leftovers are blocker-defers).
 
 ## Residual Closure & Archive
 

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

@@ -115,6 +115,7 @@ If any item below matches, fix the dispatch/plan state or mark `Blocked`—do **
 - **NEVER** split a required **parallel batch** of `N >= 2` invokes across multiple assistant messages when the host requires a single dispatch turn with all `N` calls.
 - **NEVER** register residuals only inside the plan narrative while skipping root `{HARNESS_DIR}/status.json` `residual_findings[<plan_id>]` when plan conventions require the SSOT field.
 - **NEVER** write non-canonical residual `severity` strings—use only the machine enum from `mstar-plan-artifacts`.
+- **NEVER** under `Findings cleanup: zero-residual`, park fixable Critical/Warning/Suggestion as open R# or use `Approve with residuals` for them — fix-now + re-review; open residual only for true blocker-defer + Durable Roadmap (`mstar-plan-artifacts` Findings cleanup modes).
 - **NEVER** use `Task category: quick` to skip mandatory Prepare (`specify → clarify → plan`) for substantive work (`mstar-harness-core` hard rule).
 - **NEVER** dispatch same-repo **≥2 concurrent writable implement** tracks without **`references/parallel-writable-pre-dispatch.md`**（per-track worktree + absolute **`Worktree path`**；**N invokes ≠ isolation** — also `mstar-dispatch-gates` dual-gate table).
 - **NEVER** point QC at a single dev worktree/`Review cwd` that cannot contain **all** claimed changes from parallel tracks until Git integration lands on one `Working branch` `HEAD` (`mstar-branch-worktree` QC/QA alignment).
@@ -133,6 +134,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.4",
+  "version": "1.5.6",
   "description": "Morning Star harness OpenCode plugin (skills bootstrap and agent loading).",
   "license": "MIT",
   "repository": {