@mstar-harness/opencode 1.5.5 → 1.5.6

package/CHANGELOG.md

@@ -4,6 +4,12 @@ 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`).

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-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.5.6",
   "description": "Morning Star harness OpenCode plugin (skills bootstrap and agent loading).",
   "license": "MIT",
   "repository": {