@mstar-harness/opencode 1.5.5 → 1.6.0

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.6.0
+
+- Version alignment with harness **1.6.0** (no OpenCode plugin change in this release; ZCode host surface is added at the harness/CLI layer, not bundled into the OpenCode package).
+
+See root [CHANGELOG.md](../../CHANGELOG.md) **1.6.0**.
+
+## 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`).

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

@@ -149,6 +149,7 @@ Read **`mstar-host`** after this skill; detect host per its table, then Read the
 | `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-host/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mstar-host
-description: Morning Star host adapter (OpenCode, Cursor, Codex, Kimi). Use after mstar-harness-core whenever host entry, clarify, dispatch, or plan UX differs by platform - OpenCode question/task-tool subagent invoke, Cursor /pm and CreatePlan/SwitchMode dual-write and Task parallel QC, Codex plugin skills plus Plan/Goal Mode, Kimi Agent/AgentSwarm with built-in subagent types only (coder/explore/plan) and role-in-prompt binding, sandboxed tools, and tool discovery. Auto-detect host from session tools; then Read references/<host>.md. Always load after mstar-harness-core.
+description: Morning Star host adapter (OpenCode, Cursor, Codex, Kimi, ZCode). Use after mstar-harness-core whenever host entry, clarify, dispatch, or plan UX differs by platform - OpenCode question/task-tool subagent invoke, Cursor /pm and CreatePlan/SwitchMode dual-write and Task parallel QC, Codex plugin skills plus Plan/Goal Mode, Kimi Agent/AgentSwarm with built-in subagent types only (coder/explore/plan) and role-in-prompt binding, ZCode Agent/AskUserQuestion/EnterPlanMode with built-in subagent types and role-in-prompt binding, sandboxed tools, and tool discovery. Auto-detect host from session tools; then Read references/<host>.md. Always load after mstar-harness-core.
 ---
 
 # Morning Star Host Adapter
@@ -32,7 +32,8 @@ Use **capability signals** (not filesystem paths):
 | **Task** + `subagent_type`, no CreatePlan | `cursor` | `references/cursor.md` |
 | **Codex app/CLI/plugin context**, `/plan`, `/goal`, Goal tools, `functions.*`, `codex_app.*`, `tool_search`, Browser plugin tools | `codex` | `references/codex.md`; Plan/Goal mode also `references/codex-plan-goal-mode-bridge.md` |
 | **`Agent`** / **`AgentSwarm`** / **`AskUserQuestion`** / **`EnterPlanMode`**, Kimi plugin (`.kimi-plugin/plugin.json`), `/morning-star-harness:*` commands | `kimi` | `references/kimi.md`; Plan mode also `references/kimi-plan-mode-bridge.md` |
-| Still ambiguous | - | Read sections in **`cursor.md`**, **`opencode.md`**, **`codex.md`**, and **`kimi.md`** that match tools you have; **`mstar-harness-core` wins** on conflict |
+| **`Agent`** / **`AskUserQuestion`** / **`EnterPlanMode`** / **`TodoWrite`**, no `AgentSwarm`, ZCode plugin (`.zcode-plugin/plugin.json`), `/morning-star-harness:*` commands | `zcode` | `references/zcode.md`; Plan mode also `references/zcode-plan-mode-bridge.md` |
+| Still ambiguous | - | Read sections in **`cursor.md`**, **`opencode.md`**, **`codex.md`**, **`kimi.md`**, and **`zcode.md`** that match tools you have; **`mstar-harness-core` wins** on conflict |
 
 ## Parallel dispatch (invoke-capable hosts)
 

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

@@ -0,0 +1,55 @@
+# ZCode Plan Mode × Harness Dual-Write Bridge
+
+> **Load order**: Read **`mstar-harness-core`** first, then **`mstar-plan-conventions`** and **`mstar-plan-artifacts`** when Plan mode is active. Path symbols `{HARNESS_DIR}`, `{PLAN_DIR}`, `{SPECS_DIR}` are defined in `mstar-plan-conventions`. On conflict, **`mstar-harness-core`** wins.
+
+## Purpose
+
+ZCode **Plan mode** (`EnterPlanMode` / `ExitPlanMode`) uses read-only exploration for design and a plan approval gate before implementation. Morning Star **SSOT** lives on disk under **`{HARNESS_DIR}`** (default `.mstar/`, legacy `.agents/`). This reference defines **dual-write**: mirror durable plan artifacts to the repo; never treat the ZCode session todo list alone as the handoff surface.
+
+## Priority (hard)
+
+1. User explicit instructions (this turn)
+2. Project `AGENTS.md` / `CLAUDE.md`
+3. **`{HARNESS_DIR}` / `{PLAN_DIR}` / `status.json`** (harness SSOT)
+4. ZCode `TodoWrite` UI (session UX mirror)
+
+**NEVER** cite only a session todo list path in Assignment **Plan Path**, **Context Loaded**, or Completion Report when `{PLAN_DIR}/<plan-id>-<name>.md` should exist.
+
+## When this applies
+
+- ZCode **Plan mode** is active (`EnterPlanMode` succeeded).
+- Morning Star plugin is installed (`.zcode-plugin/plugin.json` skills loaded) or **`/morning-star-harness:pm`** / **`pm` skill** is in use.
+
+## Before entering Plan mode
+
+1. **Read** (minimum): `mstar-plan-conventions`, `mstar-plan-artifacts` (SKILL.md); Prepare gates from `mstar-phase-gates` if not hotfix.
+2. **Discover** `{HARNESS_DIR}` / `{PLAN_DIR}` per `mstar-plan-conventions`.
+3. **Initialize** if absent: `{HARNESS_DIR}/`, `{PLAN_DIR}/`, `status.json` from `mstar-plan-artifacts/templates/status.empty.json`, `archived/residuals/`, Morning Star process-artifact gitignore set (see `mstar-plan-conventions` SKILL.md「Git 跟踪策略」).
+
+## Plan mode workflow (dual-write)
+
+| Step | ZCode session | Harness SSOT |
+|------|---------------|--------------|
+| Enter | `EnterPlanMode` — explore read-only | Ensure `{HARNESS_DIR}` exists; register `plan_id` in `status.json` when known |
+| Design | Draft plan content; surface via `ExitPlanMode` plan text | Mirror main plan to `{PLAN_DIR}/<plan-id>-<name>.md` with task checkboxes |
+| Clarify | `AskUserQuestion` for blocking ambiguity only | Record decisions in plan / spec when durable |
+| Exit | `ExitPlanMode` — user approves plan to implement | SSOT plan locked; `status.json` row updated |
+| Implement | Agent mode resumes | Per-task commits, Working branch, dispatch per `mstar-dispatch-gates` |
+
+`TodoWrite` and ZCode UI todos are **session progress only** — sync meaningful state to SSOT plan checkboxes and `status.json` when coordination requires it.
+
+## ExitPlanMode gate
+
+Do **not** treat ExitPlanMode approval as Morning Star **Done**. Implementation still follows phase gates, per-task commits, QC, and QA per the SSOT plan.
+
+## `mstar-iteration` Phase 1
+
+When iteration Phase 1 runs in Plan mode:
+
+- Use **one** plan session; iterate the **same** plan content and SSOT mirror in place (feedback-driven edits).
+- Do **not** run Review & Edit, commit integration branch, or dispatch implementers until the user approves via `ExitPlanMode` (or explicit go-ahead after plan lock).
+- After approval: reload `mstar-harness-core` + `zcode.md`; resume as `project-manager` orchestration.
+
+## Enforcement
+
+Conflict with harness invariants → **`mstar-harness-core`** wins. Full Cursor CreatePlan bridge detail lives in `cursor-plan-mode-bridge.md` when hosts differ; ZCode uses this lighter Enter/Exit bridge only.

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

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

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 前必须满足：
@@ -325,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）
 
@@ -336,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
 
 ---
 
@@ -370,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 占位节）

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` |

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

@@ -98,6 +98,7 @@ The **`**You are a leaf executor. You MUST NOT:**`** section (previously just pr
 **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>

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).

package/package.json

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