@mstar-harness/opencode 2.1.1 → 2.3.0

package/harness-skills/mstar-roles/references/qc-specialist/deep-review-lenses.md

@@ -33,8 +33,8 @@ QC reviewer 在开工时根据以下信号自判是否启用 deep review。满
 | Reviewer | 默认透镜 |
 |----------|---------|
 | QC1 (architecture/maintainability) | **Modularity Lens** + **Contract Lens** |
-| QC2 (security/correctness) | **Security Lens** + **Correctness Lens** |
-| QC3 (performance/reliability) | **Performance Lens** + **Reliability Lens** |
+| QC2 (security/correctness) | **Security Lens** + **Correctness Lens** + **Bounds Lens** + **Real-Entry-Path Lens** |
+| QC3 (performance/reliability) | **Performance Lens** + **Reliability Lens** + **Enforcement-Path Lens** + **Ownership / Derived-State Lens** |
 
 ### 按信号追加透镜
 
@@ -47,22 +47,27 @@ QC reviewer 在开工时根据以下信号自判是否启用 deep review。满
 
 ---
 
-## 透镜清单（每透镜一行焦点；详细追问由 reviewer 按专业判断展开）
+## 透镜清单（每透镜一行焦点；详细追问由 reviewer 按专业判断展开；新增透镜各附 ≤4 条结构化追问，均可由 diff/read/grep 回答）
 
 每个透镜是一组审查焦点。QC reviewer 在报告中按透镜分节列出发现，每个发现标注来自哪个透镜（`Source Type: deep-lens: <Lens>`）。
 
 - **Modularity Lens** — 新依赖方向合理；无逻辑错放层级（controller 业务逻辑、model 视图逻辑）；公共接口职责单一边界清晰；无循环依赖/隐含耦合。
-- **Contract Lens** — 公共 API/接口签名无未声明 breaking change（有则 plan 声明 + 迁移说明）；新端点遵循命名/参数约定；返回类型稳定（新字段不破坏已有解析）。
-- **Security Lens** — 认证/授权/session/token/permission 逻辑正确；未验证输入未直入 DB/命令/文件；敏感数据（密钥/token/PII）未在日志/错误/返回值泄露；新访问控制点覆盖所有调用路径。
+- **Contract Lens** — 公共 API/接口签名无未声明 breaking change（有则 plan 声明 + 迁移说明）；新端点遵循命名/参数约定；返回类型稳定（新字段不破坏已有解析）；docs-match-code：config/defaults/errors/wire fields/events 变更同 diff 更新 README/JSDoc；双语仓对照同步。
+- **Security Lens** — 认证/授权/session/token/permission 逻辑正确；未验证输入未直入 DB/命令/文件；敏感数据（密钥/token/PII）未在日志/错误/返回值泄露；新访问控制点覆盖所有调用路径。（与 **Enforcement-Path Lens** 互指：访问控制点自身的正确性归本透镜；拒绝/校验路径的执行与旁路追迹归 Enforcement-Path）
 - **Correctness Lens** — 错误处理显式可恢复（无吞关键异常的 catch-all）；边界条件覆盖（空/零/溢出/并发）；状态转换一致（无外部可观察中间态）；返回值/副作用与声明一致。
 - **Performance Lens** — 无 N+1 查询（ORM eager loading）；循环/批处理无无界操作；新索引必要且不退化写入；大对象/列表分页或流式。
-- **Reliability Lens** — 资源（连接/句柄/锁）异常路径也释放；外部调用有超时+重试；缓存失效正确（不长期返回过期）；无可能无限增长的结构（无界缓存/日志/队列）。
+- **Reliability Lens** — 资源（连接/句柄/锁）异常路径也释放；外部调用有超时+重试；缓存失效正确（不长期返回过期）；无可能无限增长的结构（无界缓存/日志/队列）。（与 **Lifecycle & Concurrency Lens** 互指：资源释放/超时重试/缓存失效归本透镜；对象生命周期与并发时序（发布竞态/取消/重入/清理完整性）归 Lifecycle & Concurrency）
 - **Auth Lens** — 认证中间件覆盖所有新端点；权限检查在业务逻辑前（先鉴权再操作）；session 生命周期正确（创建/续期/失效）；权限提升路径需二次确认。
 - **Input Validation Lens** — 外部输入（query/body/headers）经类型/范围/格式验证；无可触发路径遍历/注入/XSS；文件上传有大小/类型检查；错误信息不暴露内部实现细节。
 - **Data Migration Lens** — migration 可回滚（`down` 存在且正确）；大表用非阻塞策略；数据一致（不丢/无脏中间态）；并发写入下安全。
 - **Error Handling Lens** — 异常层级清晰（业务 vs 系统）；面向用户错误消息安全；关键操作失败副作用正确处理（事务回滚/补偿）；无"静默失败"路径。
 - **Standards Lens** — 风格/命名/文件组织符项目约定；无与现有冲突的重复实现；新依赖有充分理由；遵循项目 `AGENTS.md` 维护契约。
-- **Testing Lens** — 关键逻辑路径有覆盖；边界/异常路径覆盖；无仅 happy-path 跳 failure-mode；集成测试覆盖外部服务交互边界。
+- **Testing Lens** — 关键逻辑路径有覆盖；边界/异常路径覆盖；无仅 happy-path 跳 failure-mode；集成测试覆盖外部服务交互边界；断言必须在目标回归上失败；验证外部状态/logs/events/disposal，不复述实现、不信任 agent 自报。
+- **Lifecycle & Concurrency Lens** — 对象生命周期与并发时序：① publication 前无竞态（无其他路径可观察到未初始化状态）？② await 期间取消/超时传播到被等待任务且资源正确回收？③ reentry 前所有权已转移或显式保留？④ detach 清理完整（监听器/句柄移除），disposal 在 quiescent（无 in-flight 任务）时执行？（与 **Reliability Lens** 互指：资源/超时/缓存归 Reliability；生命周期/并发时序归本透镜）
+- **Ownership / Derived-State Lens** — ① 每个保留值（字段/闭包捕获/缓存条目）是 borrowed 还是 owned，借用方生命周期不超过所有者？② 每个 cache/UI echo/replay/query view 追溯到 documented success point 与 authoritative source？③ 派生状态（缓存/投影/回显）的失效点与权威源同步声明？
+- **Bounds Lens** — ① 完整产出（含 wrapper/metadata/封套行）的 owner 明确，边界检查覆盖完整产出而非仅载荷？② tiny/exact limit 被探测（空/最小/恰好等于上限）？③ 超大单块（单条记录超上限）被拒绝/截断而非绕过按行/按条门禁？④ 多字节文本（UTF-8 多字节字符）按字节上限而非字符数处理？
+- **Enforcement-Path Lens** — ① 每个 deny/veto 路径追到实际执行拒绝的操作（而非仅声明策略）？② 直调/wrapper/facade/schema-less 路径/listener 顺序等旁路调用方是否都经同一校验点？③ 观察/记录侧（listener/consumer/回调）不会绕过主校验路径写入状态或缓存？（与 **Security Lens** 互指：访问控制点自身正确性归 Security；拒绝/校验路径的执行与旁路追迹归本透镜）
+- **Real-Entry-Path Lens** — ① 测试/覆盖走 shipped entry（CLI/bin/loader/plugin boot）而非 hand-mounted 等价物（手工装配的组件实例）？② 真实入口的启动/挂载顺序（注册时序）被覆盖？
 
 ---
 
@@ -70,6 +75,8 @@ QC reviewer 在开工时根据以下信号自判是否启用 deep review。满
 
 所有透镜发现归入主报告的 `## Findings` 三节（Critical / Warning / Suggestion）中，每个发现的 `Source Type` 标注为对应透镜名（如 `deep-lens: Security Lens`），与主审查者的 `manual-reasoning` 发现同等待遇。
 
+每个透镜 finding 必须附 **diff / read / grep 锚点** + **预期 vs 实际（Expected vs observed）**——无锚点不入报告（宁可漏报不虚报）。
+
 ```markdown
 ## Scope
 - plan_id: <id>
@@ -81,6 +88,8 @@ QC reviewer 在开工时根据以下信号自判是否启用 deep review。满
 ### 🔴 Critical
 - [DS-001] Auth middleware missing on POST /api/admin/users → <fix>
   - Source Type: deep-lens: Auth Lens
+  - Verification: diff/read/grep anchor（`src/routes/admin.ts:41-52` 缺 auth 中间件引用 vs `src/middleware/auth.ts` 注册路径）
+  - Expected vs observed: 预期所有 `/api/admin/*` 经 auth 中间件 vs 实际 `POST /api/admin/users` 直入 handler
   - Confidence: High
 ```
 

package/harness-skills/mstar-roles/references/qc-specialist/report-template.md

@@ -28,18 +28,28 @@ Write under the Assignment-provided **`{SDD_DIR}/review/qc#.md`** (`qc1`…`qc3`
 ## Findings
 ### 🔴 Critical
 - {issue} -> {fix}
+  - Verification: {re-run repro | log comparison | input-output comparison | dual-path comparison | diff/read/grep anchor}
+  - Expected vs observed: {expected state} vs {actual observation}
 
 ### 🟡 Warning
 - {issue} -> {fix}
+  - Verification: {re-run repro | log comparison | input-output comparison | dual-path comparison | diff/read/grep anchor}
+  - Expected vs observed: {expected state} vs {actual observation}
 
 ### 🟢 Suggestion
 - {improvement}
+  - Verification: {diff/read/grep anchor}
+  - Expected vs observed: {expected state} vs {actual observation}
+
+### ⚪ Unconfirmed
+- {finding} — channel gap: {reason}
 
 ## Source Trace
 - Finding ID: {F-001}
 - Source Type: {git-diff | read | grep | doc-rule | manual-reasoning | deep-lens: <name> | assignment-ci-note}
 - Source Reference: {path/snippet — not a test/build log you produced}
 - Confidence: High | Medium | Low
+- Note: every finding carries `Verification` + `Expected vs observed` — see the Findings entry format above
 
 ## Summary
 | Severity | Count |
@@ -47,14 +57,18 @@ Write under the Assignment-provided **`{SDD_DIR}/review/qc#.md`** (`qc1`…`qc3`
 | 🔴 Critical | {n} |
 | 🟡 Warning | {n} |
 | 🟢 Suggestion | {n} |
+| ⚪ Unconfirmed | {n} |
 
-**Verdict**: Approve | Request Changes | Needs Discussion
+**Verdict**: Approve | Request Changes | Needs Discussion | Unconfirmed
 ```
 
 Report **Critical / Warning / Suggestion** sections are human-readable; PM maps to machine **`severity`** in `status.json` per `mstar-plan-artifacts/references/status-and-residuals.md`.
 
 ## Verdict rules (reviewer applies)
 
+- Evidence channel failure (Review range cannot be established / key file unreadable) → `Unconfirmed` — report states the failure reason; PM-side handling per `mstar-review-qc` consolidated
+- **Partial** evidence-channel failure → mark only the affected findings **Unconfirmed** (keep verifiable findings; state channel gaps in Summary)
+- Any `Unconfirmed` finding (with or without Critical/Warning) → verdict `Unconfirmed`, never `Approve`; `Approve` additionally requires every finding's evidence channel intact
 - Unresolved **Critical** or **Warning** → `Request Changes`
 - No Critical/Warning but high-impact unresolved trade-off (often architectural Suggestion) → `Needs Discussion`
 - **Approve** only when Critical = 0 and Warning = 0 (unresolved)
@@ -67,6 +81,8 @@ Report **Critical / Warning / Suggestion** sections are human-readable; PM maps
 
 ## Evidence rules
 
+- **If you cannot state a verifiable cross-check, do not report the finding** (prefer omission to fabrication)
+- **A failed evidence channel is not "no problem"** — when the review-package is missing, the diff cannot be parsed, or a referenced file is unreadable, mark the affected scope **Unconfirmed**; never default to "no findings"
 - Critical findings: trigger condition, impact scope, fix suggestion (from source reasoning)
 - Low-confidence / runtime-only doubts: follow-up steps for **L4 QA** or implementer — not self-executed suites
 - Repeated cross-task patterns: mark as recurring in findings

package/harness-skills/mstar-roles/references/qc-specialist-shared.md

@@ -102,9 +102,11 @@ report_kind: qc
 reviewer: {role_id}
 reviewer_index: {reviewer_index}
 plan_id: "<id>"
-verdict: "Approve | Request Changes | Needs Discussion"
+verdict: "Approve | Request Changes | Needs Discussion | Unconfirmed"
 generated_at: "YYYY-MM-DD"
 ---
+
+Verdict enumeration and rules (incl. `Unconfirmed` semantics) → **`references/qc-specialist/report-template.md`**.
 ```
 
 ## Completion Report

package/harness-skills/mstar-roles/references/writing-specialist.md

@@ -49,6 +49,39 @@ If any item below matches, **stop** and return `Blocked` to `project-manager` in
 - If unspecified, choose the clearest structure for target audience
 - Keep writing usable and publication-ready
 - Include source notes when factual claims require evidence
+- Durable harness artifacts (knowledge docs, plans, README, promoted guides) must pass the **HEAD-resolvability test**: a reader at HEAD — no chat transcripts, dispatch prompts, or unmerged drafts — can resolve every reference and verify every claim.
+- Leakage taxonomy and keep rules (mstar-sanctioned): SSOT → `mstar-compound/references/compound-workflow.md`.
+- The same rubric applies to writing scenarios; do not duplicate its prose here.
+
+### Complete-proposition rule
+
+Before trimming or restating a passage, enumerate the propositions it makes:
+
+- actor + action
+- condition / timing / ordering
+- modality (must / may / must not)
+- negative guarantee + exception
+- ownership / side-effect / failure / consequence
+
+Trim modifiers, repetition, or narration **only when every factual clause survives** the edit. Word count alone is not an improvement — a shorter sentence that drops a guarantee, a condition, or an ownership boundary changes the contract, not the prose.
+
+### Coverage-by-artifact
+
+One explanation has one home; essential contract facts may repeat locally. Each durable artifact type has a coverage focus:
+
+| Artifact | Coverage focus |
+|----------|----------------|
+| Knowledge docs | unique rationale, alternatives considered, shipped verification evidence, named coverage gaps |
+| Plans | prerequisites, actions, observable verification |
+| Review bundles | defect / location / impact / evidence; blockers separated from suggestions |
+| SKILL.md | behavioral guardrails + explicit "guidance, not script" scope limitation |
+| README | consumer contract: config / semantics / failures / limitations / extension points — durable gaps, not cleanup inventories |
+| Completion reports | what / why / verification |
+
+### Doc standards
+
+- **Atomic-move rule**: a move = remove + add + fixing every inbound link in the same change; no orphaned references may survive the change set.
+- **Tutorial vs reference**: user-facing docs are either a tutorial (ordered steps to an observable outcome) or a reference (explicitly scoped lookup).
 
 ## Completion Report
 

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

@@ -87,7 +87,11 @@ Host mapping → **`mstar-host`** references (`model` / Task field).
 
 1. `mstar sdd review-package MERGE_BASE HEAD` → branch diff in `{SDD_DIR}/review/`
 2. PM dispatches **plan QC tri-review (L3)** — **`QC mode: full tri-review`**, **N=3** — with branch review-package path and report paths under `{SDD_DIR}/review/` → **`mstar-review-qc`** · **`mstar-dispatch-gates`**. Layer SSOT → **`mstar-review-qc/references/review-responsibility-boundaries.md`**. PM writes `{SDD_DIR}/review/qc-consolidated.md` and durable main-plan gate summary. **Mandatory whenever `Execution mode: sdd`** (single-plan or iteration).
-3. Critical/Important QC findings → **one** fix dispatch (full list), then targeted re-review
+3. Critical/Important QC findings → **one** fix dispatch (full list), then targeted re-review. Fix rounds run on four mechanics — the per-task fix loop applies the same (`references/file-handoffs.md`):
+    - **Unverified rounds count**: a fix round without verification evidence (reviewer not confirmed / report not on disk) is **not clean** — re-check and count the round; never enter the convergence branch.
+    - **Full re-entry**: the next fix dispatch carries **all** open findings (including last round's unverified items) — never slice a subset.
+    - **Capped cross-round excerpt**: from round ≥2, the fix dispatch attaches an excerpt of prior rounds' findings and dispositions (advisory caps: ~500 words per round, ~1500 total — suggested values, not hard limits).
+    - **Honest non-convergence**: open findings at wave close → list them in detail and state the disposition — re-feed to the next fix round **or** transfer to residual tracking — never silently close.
 4. QA gate → **`mstar-harness-core`** Done rules; PM **`mstar-roles/references/project-manager/qa-trigger-matrix.md`**
 
 ## Progress ledger

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

@@ -48,6 +48,8 @@ Fix subagent appends to same `task-N-report.md` with test evidence:
 
 Re-dispatch reviewer only when all three are present.
 
+The per-task fix loop applies the same fix-round mechanics as plan-level QC fix waves (SKILL.md · "After all tasks" — unverified rounds count, full re-entry, capped cross-round excerpt, honest non-convergence): from round ≥2 the excerpt of prior rounds' findings/dispositions goes into the fix dispatch brief, and the round tally/verification history lands in `$SDD_DIR/progress.md`.
+
 ## Progress ledger
 
 On clean task review, append to `$SDD_DIR/progress.md`:

package/harness-skills/mstar-skill-authoring/SKILL.md

@@ -152,11 +152,13 @@ Agents 按 **skill 名** 发现 skill；文档若给出完整仓内相对路径
 - Progressive disclosure:
 - Evidence for behavior change (P6):
 - Stale references checked:
-- Verdict: Approve | Request Changes | Needs Discussion
+- Verdict: Approve | Request Changes | Needs Discussion | Unconfirmed
+- Unconfirmed: paired evidence (P6) cannot be established or verified
 ```
 
 ## References
 
 | 何时 | 打开 |
 |------|------|
-| 需要完整 skill-writer 流程、原则细则、输出模板 | `references/skillsbench-authoring.md` |
+| 需要完整 skill-writer 流程、原则细则、输出模板 | `references/skillsbench-authoring.md` |
+| 需要把「真实产物」固化为可重跑断言（P6 重武器选项） | `references/regression-fixation.md` |

package/harness-skills/mstar-skill-authoring/references/regression-fixation.md

@@ -0,0 +1,46 @@
+# 回归固化参考（Regression Fixation Reference）
+
+行为塑形改动（skill 正文流程、命令序列、CLI 行为面）的 paired evidence 武器库之一（P6 **重武器选项**）。默认证据仍是 SKILL.md「验证门控」的 P6 before/after + 应用案例；仅当行为可脚本化、且该行为面值得长期固化时，用本手法。
+
+## 何时用（When）
+
+- 行为面有**可执行产物**：skill 正文里的流程脚本 / 命令序列 / CLI 调用链。
+- 该面曾出过行为 bug，或改动触碰宿主边界（解析、打包、路径解析、子进程执行）。
+- 例外：纯文案 / 无可观测行为的规则微调 → 走默认 P6，不加载本参考。
+
+## 手法（Technique）
+
+1. **真实产物当被测对象（real artifact as test subject）**
+   不 import 源码、不 mock 掉被测面本身——直接运行用户/agent 实际触达的产物（built bundle、命令序列、宿主钩子驱动的完整流程）。产物侧跑通，才能覆盖「源码 import 跑不到」的缺陷面（bundle 解码、产物路径解析、子进程环境）。
+   → 本仓实例：`packages/cli/test/bundle-smoke.test.ts`（2026-08-16 落地）对 **built bundle** `dist/mstar-harness.js` 子进程执行 `dispatch validate` 并断言 exit code，而非 import `src/index.ts`。
+
+2. **Mock 宿主钩子（mock host hooks）**
+   把宿主边界替换为受控桩：mstar 面对应 dispatch / file IO / CLI 调用。固定输入（fixture 文件、argv、环境变量），断言行为输出（exit code、stdout/stderr、副作用文件）。钩子命名沿用宿主自身词汇，不引入外部系统 hook 名。
+
+3. **双路径断言一致（dual-path assertion）**
+   同一断言集对两条路径各跑一遍并断言一致：**真实模块路径**（import 产物 / 源码）与**被测路径**（vm 求值真实脚本 / 子进程 bundle）。任一路径偏离 → 立即暴露「实现与产物行为漂移」。
+
+4. **修复固化（fix solidification）**
+   行为 bug 修复流程：先写复现用例见 FAIL → 修 → 用例见 PASS → 进回归集。此后每次改动重跑回归集，同类 bug 不再复发（回归集随修复轮增长）。
+
+## 最小骨架（Skeleton，零外部依赖）
+
+```js
+// node:test + vm：求值「真实脚本文本」，不复制逻辑到测试
+import test from "node:test";
+import vm from "node:vm";
+
+const script = readFileSync("flow.js", "utf8"); // 真实产物
+const sandbox = { dispatch: mockDispatch, fileIO: mockFileIO }; // mock 宿主钩子
+vm.runInNewContext(script, sandbox);             // 被测路径
+assert.deepEqual(sandbox.events, expected);      // 断言行为输出
+// 双路径：同一断言集对真实模块路径再跑一遍，assert 一致
+```
+
+bun test 同理：`Bun.spawnSync` 子进程跑 bundle + `expect` 断言（见本仓 bundle-smoke 实例）。
+
+## 边界（Boundaries）
+
+- **零外部依赖**：Node 内置 `vm` / `node:test`（或 bun test）即可，不引入第三方测试框架。
+- **不强制**：默认仍是 P6 before/after + 应用案例；本参考是重武器选项。
+- **只固化可观测行为**：模型判断、触发精确性等不可脚本化断言的面，仍走压力场景（SKILL.md「验证门控」）。

package/harness-skills/mstar-skill-authoring/references/skillsbench-authoring.md

@@ -76,6 +76,43 @@ Do **not** restate generic knowledge the model already has — that wastes token
 6. **Pressure / paired check** — 2–3 prompts that fail without the skill; confirm improvement (P4, P6).
 7. **Ship note** — list deletions/compressions (P2/P5) and how P6 was verified.
 
+## Authoring devices
+
+Small, composable techniques for specific authoring problems; each maps onto one or two
+principles above. Pull one in when it fits — do not encode all six into every skill.
+
+1. **Calibrated examples file** (serves P2/P5) — keep one small reference of real cases
+   distilled into annotated judgments; readers identify the governing principle, not text
+   templates, and it is written back when a new rule settles. In this harness: the Q1–Q8
+   worked judgments in `mstar-compound` `references/compound-workflow.md`; this iteration's
+   fold-B overcorrection checklist (device 3) is a softer second instance.
+
+2. **Recall batteries** (serves P5) — for audit/hunt skills: over-matching probes that
+   force a semantic judgment, plus a documented list of known false-positive families; a
+   zero-hit pattern proves nothing until you have seen it match. In this harness: the recon
+   hints `mstar-audit` fans out to scout subagents — scoping facts, domain risk hints, and
+   decided-tradeoff "don't report" pointers.
+
+3. **Overcorrection traps** (adjacent to P6) — a short section per skill naming the failure
+   modes of over-applying its own rules, so the skill guards its own bias. In this harness:
+   the overcorrection-traps row in `mstar-compound` `references/compound-workflow.md`
+   (obligation↛endorsement flips, hypotheticals stay marked, delete clauses, not sentences).
+
+4. **Required-explicit-input** (adjacent to P3) — when the required scope or answers are
+   missing, report and stop; never infer a repo-wide default. In this harness: `mstar-audit`
+   asks which findings to turn into plans — "do not write 30 plans nobody asked for" —
+   instead of inferring the scope itself.
+
+5. **Questions ≠ write authority** (serves P6) — interaction and calibration gates never
+   change edit authority; only the evaluation does. In this harness: `grill-me` interviews
+   without editing, and `mstar-sdd` keeps the per-task reviewer's report separate from the
+   implementer's application.
+
+6. **Invocation boundary** (adjacent to P3) — declare expensive workflows user-invocable
+   only; never put them in a skill load order. In this harness: the `/iteration-*` lifecycle
+   lives in `commands/`; `mstar-harness-core` keeps command-layer references out of the
+   `mstar-*` load matrix.
+
 ## Output template
 
 ```markdown

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mstar-harness/opencode",
-  "version": "2.1.1",
+  "version": "2.3.0",
   "description": "Morning Star harness OpenCode plugin — skills bootstrap + engine-backed runtime hooks (status lint, dispatch validation, Enforcement: hard gates).",
   "license": "MIT",
   "repository": {
@@ -36,6 +36,6 @@
     "access": "public"
   },
   "devDependencies": {
-    "@mstar-harness/engine": "2.1.1"
+    "@mstar-harness/engine": "workspace:*"
   }
 }