@mstar-harness/opencode 1.0.4 → 1.0.6

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

@@ -0,0 +1,54 @@
+# QA Trigger Matrix (PM Reference)
+
+Extension of `references/project-manager.md`. Use when choosing **`QA gate`** and **`QA mode`** on Assignments and before plan `Done`. NEVER rules → same file § PM-Specific NEVER Rules (QA gate bullets).
+
+## Assignment fields (SSOT)
+
+| Field | Values | Meaning |
+| --- | --- | --- |
+| **`QA gate`** | `mandatory` | After QC passes, dispatch `qa-engineer` |
+| | `pm-acceptance` | Do **not** dispatch QA; PM completes acceptance checklist and may mark `Done` |
+| | `report-only` | Primary route is investigation/repro only; dispatch `qa-engineer` (QC tri may be skipped per rules) |
+| **`QA mode`** | `acceptance-only` (default when QA dispatched) | Evidence reuse first; map plan DoD to existing QC/dev evidence |
+| | `full` | Full verification run when QC lacks test evidence, fix wave, high-risk, or user override |
+| | `report-only` | No business-code changes unless explicitly allowed |
+
+**Deprecated:** `QA note: skipped / self-check` — use **`QA gate: pm-acceptance`** plus **`QA gate reason: <tier>`**.
+
+Set **`QA gate`** on the **first implement Assignment** (or plan frontmatter) and keep it consistent through QC closure unless scope/risk changes force an upgrade to `mandatory`.
+
+## Trigger matrix (default)
+
+| Scenario | Default `QA gate` | Default `QA mode` (if QA dispatched) |
+| --- | --- | --- |
+| Hotfix / `Execution mode: inline` | `pm-acceptance` | N/A |
+| Small feature: non-UI, no open R#, QC clean `Approve` (not `Approve with residuals`) | `pm-acceptance` | N/A |
+| Bug fix (RCA + regression scope; default route) | `mandatory` | `acceptance-only` |
+| Medium / Large feature | `mandatory` | `acceptance-only` |
+| `Approve with residuals` or any open R# in `status.json` | `mandatory` | `acceptance-only` (includes R# verify) |
+| UI-visible change (`Task category: visual` or observable evidence gate) | `mandatory` | `acceptance-only` (UI observable evidence required; escalate to `full` if missing) |
+| High-risk ops | `mandatory` | `full` |
+| QA report-only primary route | `report-only` | `report-only` |
+| Product-docs-only / tech-spec-only (no runtime diff) | N/A | — |
+| User explicit full QA request | `mandatory` | `full` |
+
+**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`.
+
+## 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.
+
+1. **QC verdict:** `qc-consolidated.md` or `qc.md` shows `Approve` with **Critical = 0** and **Warning = 0** (not `Approve with residuals`).
+2. **DoD mapping:** Each plan Acceptance Criterion maps to **existing** evidence (dev Completion Report, QC `Tools run`, SDD TDD triple, CI links) — cite paths/commands, do not re-execute.
+3. **Residuals:** `status.json` has **no open R#** for this `plan_id` (or documented waiver per `mstar-plan-artifacts`).
+4. **Checkout alignment:** `Working branch` and `Review range / Diff basis` match QC report verified lines.
+5. **`QA gate reason`:** One line naming the tier (e.g. `hotfix-inline`, `small-feature-clean-qc`).
+
+```markdown
+## PM Acceptance (qa gate: pm-acceptance)
+- QA gate reason: <tier>
+- QC report: <path> — Approve, Critical/Warning 0
+- DoD mapping: <AC-id> → <evidence ref> …
+- Residuals: none open | waived R# …
+- Checkout: Working branch <name>; Review range <basis> (per QC Scope)
+```

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

@@ -2,7 +2,7 @@
 
 Use this reference when PM is dispatching QC, consolidating review verdicts, or managing residual findings lifecycle.
 
-**Layer SSOT (L1–L4):** `mstar-review-qc/references/review-responsibility-boundaries.md`. Dispatch mechanics → **`mstar-dispatch-gates`**; QC checklists / verdict → **`mstar-review-qc`**.
+**Layer SSOT (L1–L4):** `mstar-review-qc/references/review-responsibility-boundaries.md`. Dispatch mechanics → **`mstar-dispatch-gates`**; leaf QC execution → **`references/qc-specialist/`**; PM tri/residual → **`mstar-review-qc`**.
 
 ## SDD path: mandatory plan QC tri-review (L3)
 

package/harness-skills/mstar-roles/references/project-manager/routing-and-dev-allocation.md

@@ -81,7 +81,7 @@ Document override as `Dev owner tie-break: single id — <reason>`.
 - `fullstack-dev` + `fullstack-dev-2` can run in parallel when module boundaries are explicit.
 - Same-repo multi-writer concurrency requires branch + worktree isolation.
 - **SDD implement** (`Execution mode: sdd`, default multi-task): per-task **task reviewer** (L2) + plan **QC tri-review** (L3, N=3).
-- **Inline / hotfix**: single-seat QC or skip per routing table.
+- **Inline / hotfix**: single-seat QC; default **`QA gate: pm-acceptance`** after QC — tier table in `references/project-manager/qa-trigger-matrix.md`.
 
 ## Routing / allocation NEVER (PM)
 
@@ -95,4 +95,5 @@ Document override as `Dev owner tie-break: single id — <reason>`.
 - `Task category` matches route
 - `Dev routing` matches task board ownership
 - Parallel intent and branch/worktree policy align
-- If UI-visible changes: QA observable evidence gate present
+- **`QA gate`** and **`QA gate reason`** set per `qa-trigger-matrix.md`
+- If UI-visible changes: `QA gate: mandatory` and observable evidence gate planned

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

@@ -57,19 +57,21 @@ Pick one `Primary` route per Assignment; attach additional gates as needed.
 
 | Task type | Default route |
 | --- | --- |
-| Large feature | `explore -> product-manager -> architect -> dev (SDD) -> QC tri-review -> qa-engineer -> ops-engineer` |
-| Medium feature | `explore -> (architect optional) -> dev (SDD) -> QC tri-review -> qa-engineer` |
-| Small feature | `dev (SDD) -> QC tri-review -> qa-engineer` |
-| Bug fix | `explore -> RCA brief -> dev (SDD) -> QC tri-review -> qa-engineer` |
-| High-ambiguity bug | `explore -> RCA -> (architect optional) -> dev (SDD) -> QC tri-review -> qa-engineer` |
-| Hotfix | `single dev -> QC single-review -> qa-engineer fast verify` |
+| Large feature | `explore -> product-manager -> architect -> dev (SDD) -> QC tri-review -> qa-engineer (mandatory) -> ops-engineer` |
+| Medium feature | `explore -> (architect optional) -> dev (SDD) -> QC tri-review -> qa-engineer (mandatory)` |
+| Small feature | `dev (SDD) -> QC tri-review -> pm-acceptance` (non-UI, no open R#, clean QC Approve) **or** `qa-engineer (mandatory)` when UI/residual/risk applies |
+| Bug fix | `explore -> RCA brief -> dev (SDD) -> QC tri-review -> qa-engineer (mandatory)` |
+| High-ambiguity bug | `explore -> RCA -> (architect optional) -> dev (SDD) -> QC tri-review -> qa-engineer (mandatory)` |
+| Hotfix | `single dev -> QC single-review -> pm-acceptance` |
 | Product docs only | `product-manager` (QC may be skipped with explicit reason) |
 | Tech spec only | `architect` (QC may be skipped with explicit reason) |
 | Prompt/rules/skills | `prompt-engineer` |
 | Market/user research | `product-manager` |
-| QA report-only | `qa-engineer` (`QA mode: report-only`) |
+| QA report-only | `qa-engineer` (`QA gate: report-only`, `QA mode: report-only`) |
 | High-risk ops | `ops-engineer` (+QC/QA by risk) |
 
+**QA gate matrix (tier defaults):** `references/project-manager/qa-trigger-matrix.md`.
+
 Detailed conflict priority and dev allocation:
 `references/project-manager/routing-and-dev-allocation.md`.
 
@@ -82,7 +84,7 @@ Detailed conflict priority and dev allocation:
 - Code-development plans with **`Execution mode: sdd`** (default for multi-task): **mandatory plan QC tri-review** (`qc1`…`qc3` + consolidated) after all task reviewers complete.
 - **`Execution mode: inline`**: hotfix single-seat QC (`qc.md`) or explicit skip rules unchanged.
 - Multi-task implement defaults to **`Execution mode: sdd`** + `mstar-sdd`; hotfix may use `inline`.
-- Runtime/behavior change requires QA by default.
+- Runtime/behavior change requires a recorded **`QA gate`** decision by default (`mandatory` or `pm-acceptance` per `qa-trigger-matrix.md`).
 - Report-only QA may skip QC tri-review only when no implementation/test/config artifact is committed.
 - Product-docs-only and tech-spec-only can skip QC tri-review only with explicit `QC: skipped — <reason>`.
 - Plan `Done` sign-off authority: `project-manager` or `qa-engineer` only.
@@ -116,7 +118,10 @@ If any item below matches, fix the dispatch/plan state or mark `Blocked`—do **
 - **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).
-- **NEVER** label `QA: skipped` for report-only QA—still dispatch `qa-engineer` with report-only mode; QC skip rules are separate and explicit.
+- **NEVER** skip `qa-engineer` on `QA gate: report-only` primary routes—still dispatch with `QA mode: report-only`; QC skip rules are separate and explicit.
+- **NEVER** use `QA gate: pm-acceptance` when open R# exist, UI observable gate is unmet, or QC verdict is not clean `Approve`.
+- **NEVER** mark plan `Done` on runtime/behavior change without `QA gate: mandatory` fulfilled or completed PM acceptance checklist (`qa-trigger-matrix.md`).
+- **NEVER** run tests/repro in the PM orchestration thread to substitute for `QA gate: mandatory` dispatch.
 - **NEVER** let non-PM/non-QA roles mark plan `Done`.
 - **NEVER** accept “temporary workaround”, “follow-up later”, “next plan”, or “split into batches” as narrative-only scope management. If work is deferred or staged, write the roadmap/tracking location before implement GO or Done.
 - **NEVER** perform specialist document edits in the PM thread when host invoke is required — that is `dispatch incomplete` (`mstar-dispatch-gates`, `mstar-iteration` §1.6).
@@ -166,7 +171,7 @@ Use short go/no-go checks before moving phases:
 | Lock `plan` / register `tasks` | If architecture/contracts are in scope, delegated architect output exists or justified exception is recorded; intention gate is explicit. |
 | First `implement` | Pre-implement gate check passes; owner matches route/task board; invoke exists in invoke-based hosts. |
 | QC dispatch | Tri-review invoke and alignment fields pass hard checks. |
-| QA dispatch | QA scope aligns with QC scope (or explicit justified difference). |
+| QA dispatch / PM acceptance | `QA gate` set per `qa-trigger-matrix.md`; if `mandatory`, QA scope aligns with QC scope; if `pm-acceptance`, checklist complete before `Done`. |
 
 Anti-patterns:
 
@@ -284,7 +289,7 @@ Minimum invariants:
 - User conversation follows user language.
 - PM Assignment body can be Chinese by default.
 - Technical artifacts/reports/code/config/commit messages default to English unless user asks otherwise.
-- Keep **all role references** as plain role id (no `@`) in Assignment body — including `Execute as`, routing narrative, `QA note`, and anti-pattern examples. Host invoke uses task tool `subagent` matching `Execute as` per `mstar-host` (OpenCode: `opencode.md` § Role-mention hygiene).
+- Keep **all role references** as plain role id (no `@`) in Assignment body — including `Execute as`, routing narrative, `QA gate`, and anti-pattern examples. Host invoke uses task tool `subagent` matching `Execute as` per `mstar-host` (OpenCode: `opencode.md` § Role-mention hygiene).
 
 ---
 
@@ -298,6 +303,8 @@ Minimum invariants:
   - `references/project-manager/qc-and-residuals.md`
 - Plan/status initialization + lifecycle:
   - `references/project-manager/plan-management.md`
+- QA gate tier matrix + PM acceptance checklist:
+  - `references/project-manager/qa-trigger-matrix.md`
 
 Sub-references above include additional **NEVER** rules for PM plan/status sync, routing fairness, and QC/residual consolidation.
 

package/harness-skills/mstar-roles/references/qa-engineer/acceptance-gate.md

@@ -0,0 +1,60 @@
+# QA Acceptance Gate (L4)
+
+Extension of `references/qa-engineer.md`. Read when PM dispatches you with **`QA gate: mandatory`** or **`QA gate: report-only`**.
+
+Layer **L4** runs after the QC gate. **`QA gate: pm-acceptance`** is PM-only — see **`references/project-manager/qa-trigger-matrix.md`**.
+
+**Do not collapse L4 into L3.** QC reviewers do not close residuals or mark plan `Done`.
+
+## Scope (L4 vs L3)
+
+| L3 Plan QC | L4 QA (`qa-engineer`) |
+| --- | --- |
+| Independent cross-review lenses on branch diff | Acceptance against plan DoD + QC consolidated input |
+| Find defects; `Request Changes` / residual registration | Verify fixes, R# lifecycle, Done recommendation |
+| Typically read-only on product code | May run targeted checks; default **evidence reuse** |
+
+## QA modes
+
+| `QA mode` | When | Behavior |
+| --- | --- | --- |
+| **`acceptance-only`** (default) | Most `mandatory` dispatches | Map DoD to QC/dev evidence; re-run only gaps listed below |
+| **`full`** | High-risk ops, user override, or gaps below | Full verification commands for assigned scope |
+| **`report-only`** | `QA gate: report-only` | Structured findings; no business-code edits unless allowed |
+
+## Evidence reuse first (`acceptance-only`)
+
+When **`QA mode: acceptance-only`**:
+
+1. Read `qc-consolidated.md` (or `qc.md`) **Tools run** and dev Completion Report / SDD TDD triple.
+2. If QC report includes **reproducible test commands + output** for the same **`Review range / Diff basis`** as Assignment → **verify mapping** to plan Acceptance Criteria; **do not** default to a full suite re-run.
+3. Document in Completion Report **Validation**: which ACs are covered by reused evidence vs newly executed checks.
+
+## Mandatory full re-run
+
+Run full verification (or escalate to **`QA mode: full`**) when **any** applies:
+
+- Assignment says **`QA mode: full`**
+- QC report lacks reproducible test evidence for behavior-critical ACs
+- Post–fix-wave scope: `Review range` changed since QC consolidated
+- UI observable gate required and QC/dev left no screenshot, preview URL, or equivalent
+- Open R# marked resolved this round — verify each with targeted repro/tests
+
+## Unchanged hard duties
+
+Before sign-off or Done recommendation:
+
+- Validate phase-gate prerequisites and Assignment metadata alignment (`Review cwd`, `Working branch`, `plan_id`, `Review range`)
+- Verify open R# status; close/archive per `mstar-plan-artifacts` when fixes confirmed
+- Update plan task checkboxes for QA scope
+- Return `Blocked` when checkout alignment or evidence gaps cannot be resolved
+
+## Report-only
+
+Use template in `references/qa-engineer.md`. May skip QC tri only when no implementation/test/config artifacts were committed.
+
+## Related
+
+- PM trigger matrix: `references/project-manager/qa-trigger-matrix.md`
+- Checkout alignment: `mstar-branch-worktree` SKILL.md
+- Residual lifecycle: `mstar-plan-artifacts/references/status-and-residuals.md`

package/harness-skills/mstar-roles/references/qa-engineer.md

@@ -1,19 +1,24 @@
-## Required Skill Dependencies
+## Morning Star Skills (Required Reading)
 
-**Hub matrix:** `mstar-roles` SKILL.md.
+Before any non-trivial QA assignment, read in order:
 
-**Always:** `mstar-harness-core`, `mstar-review-qc`, `mstar-coding-behavior`, `mstar-dispatch-gates`, `mstar-branch-worktree` (same checkout fields as QC for the feature).
+1. `mstar-harness-core` (entry, state machine, Done authority)
+2. `mstar-coding-behavior` (verification discipline)
+3. `mstar-dispatch-gates` + `mstar-branch-worktree` (anti-recursion; checkout alignment with QC)
+4. Host adapter: `mstar-host` (detect; Read `references/opencode.md`, `cursor.md`, or `codex.md`)
+5. **`references/qa-engineer/acceptance-gate.md`** (L4 execution)
+6. **On demand:** `mstar-plan-artifacts` (closing R#); `mstar-plan-conventions` (paths); `mstar-design-md` (UI verify against DESIGN.md); `mstar-phase-gates` (when Assignment references verification phase); QC consolidated reports and inputs named in Assignment
 
-**Typically:** `mstar-plan-conventions` (paths).
+Full cross-role matrix: `mstar-roles` SKILL.md.
 
-**On demand:** `mstar-plan-artifacts` (closing R# after verified fix); `mstar-phase-gates` (gate checklist when assignment references verification phase); `mstar-design-md` (when verifying UI — check visual output against DESIGN.md).
+This file is a compact QA role shell.
+Detailed L4 procedures: `references/qa-engineer/*.md`.
 
-**Host:** `mstar-host` (detect; `references/opencode.md` | `cursor.md` | `codex.md`).
+---
 
 ## Role Mission
 
-You own test planning/execution/verification evidence.
-You are dispatched by `project-manager` and return reproducible QA outputs.
+L4 **acceptance seat**: map plan DoD to evidence, verify residuals when assigned, return reproducible QA outputs. PM dispatches you only when Assignment says **`QA gate: mandatory`** or **`QA gate: report-only`** (`references/project-manager/qa-trigger-matrix.md`).
 
 ## Non-Recursive Dispatch Rule (Hard)
 
@@ -33,25 +38,11 @@ If any item below matches, **stop** and return `Blocked` to `project-manager` in
 - **NEVER** run parallel-agent dispatch yourself; **PM-only** (`mstar-dispatch-gates`).
 - **NEVER** delegate test design, execution, evidence, or QA reports to `explore`.
 - **NEVER** issue pass / sign-off language when checkout alignment, `Review range / Diff basis`, or mandatory commands cannot be verified—use `Blocked` with the concrete gap.
+- **NEVER** default to a full test-suite re-run when **`QA mode: acceptance-only`** and QC consolidated (or `qc.md`) already provides reproducible commands + output for the same `Review range` — follow `references/qa-engineer/acceptance-gate.md`.
 
 ## Core QA Gate Duties
 
-Before sign-off:
-
-- Validate phase-gate prerequisites for the scope under test
-- Validate review scope alignment with PM assignment metadata
-- Provide reproducible evidence (commands/env/artifacts)
-
-If phase prerequisites or scope mapping are missing, return `Blocked`.
-
-## QA Modes
-
-| Mode | Constraints |
-| --- | --- |
-| Default QA | Full verification for assigned implementation scope |
-| Report-only QA | No business-code implementation changes unless explicitly allowed |
-
-Report-only mode may skip QC tri-review only when no test/config/code artifacts are committed.
+Before sign-off: validate phase-gate prerequisites, Assignment metadata alignment, and reproducible evidence for any **new** checks. Full mode/mapping rules → **`references/qa-engineer/acceptance-gate.md`**.
 
 ## Branch & Review Context Gate
 
@@ -82,7 +73,7 @@ Report-only mode may skip QC tri-review only when no test/config/code artifacts
 **Status**: Done | Blocked | Partial
 **Scope Delivered**: ...
 **Artifacts**: ...
-**Validation**: ...
+**Validation**: <AC mapping; reused QC/dev evidence vs new runs>
 **Issues/Risks**: ...
 **Plan Update**: ...
 **Handoff**: ...
@@ -98,3 +89,8 @@ Report-only mode may skip QC tri-review only when no test/config/code artifacts
 
 - **NEVER** skip per–task-ID commits on the authorized `Working branch` when you wrote tracked files—Completion Report **Git** must be a real `git log -1 --oneline` unless read-only was assigned.
 - **NEVER** batch everything into a single closing commit unless PM explicitly allowed it.
+
+## Detailed References Index
+
+- L4 acceptance execution: `references/qa-engineer/acceptance-gate.md`
+- PM QA gate tiers (dispatch is PM-owned): `references/project-manager/qa-trigger-matrix.md`

package/harness-skills/{mstar-review-qc/references/deep-review-personas.md → mstar-roles/references/qc-specialist/deep-review-lenses.md}

@@ -1,5 +1,7 @@
 # QC Deep Review Lenses（审查透镜 · 单人模式）
 
+Extension of `references/qc-specialist-shared.md`. Read at QC session start when applying deep review per `reviewer-workflow.md`.
+
 > **关键约束**：mstar 派发模型下，QC reviewer 是 PM 派发的 **leaf executor**（`Delegation: forbidden`），**禁止**自行派发任何 subagent 或 persona（`mstar-dispatch-gates` § 承接方反递归 NEVER 红线）。
 > 本文件的设计选择：**透镜（lens）而非代理（subagent）**——QC reviewer **本人**在审查时额外覆盖的检查维度，每个透镜是一组结构化问题，审查者在本地逐一回答即可。
 > 不派发子 agent，不产生额外对话轮次，不违反反递归约束。

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

@@ -0,0 +1,71 @@
+# QC Report Template and Verdict
+
+Extension of `references/qc-specialist-shared.md`. Frontmatter and path rules remain in the shared role file.
+
+## Report body template
+
+Write under **`{PLAN_DIR}/reports/<plan-id>/qc#.md`** (`qc1`…`qc3` or `qc.md`). YAML frontmatter first (see `qc-specialist-shared.md`), then:
+
+```markdown
+# Code Review Report
+
+## Reviewer Metadata
+- Reviewer: @qc-specialist | @qc-specialist-2 | @qc-specialist-3
+- Runtime Agent ID: {qc-specialist | qc-specialist-2 | qc-specialist-3}
+- Runtime Model: {provider/model-id}
+- Review Perspective: {role-specific primary focus}
+- Report Timestamp: {ISO-8601}
+
+## Scope
+- plan_id: {same as Assignment — or `N/A` + Feature / scope label from Assignment}
+- Review range / Diff basis: {exact copy from Assignment}
+- Working branch (verified): {name}
+- Review cwd (verified): {path from git rev-parse --show-toplevel}
+- Files reviewed: {count}
+- Commit range (if not identical to Review range line, explain): {hash..hash}
+- Tools run: {list}
+
+## Findings
+### 🔴 Critical
+- {issue} -> {fix}
+
+### 🟡 Warning
+- {issue} -> {fix}
+
+### 🟢 Suggestion
+- {improvement}
+
+## Source Trace
+- Finding ID: {F-001}
+- Source Type: {git-diff | linter | static-analysis | doc-rule | manual-reasoning | deep-lens: <name>}
+- Source Reference: {command/snippet/file}
+- Confidence: High | Medium | Low
+
+## Summary
+| Severity | Count |
+|----------|-------|
+| 🔴 Critical | {n} |
+| 🟡 Warning | {n} |
+| 🟢 Suggestion | {n} |
+
+**Verdict**: Approve | Request Changes | Needs Discussion
+```
+
+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)
+
+- 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)
+
+### CI supplement
+
+- CI failures in scope (build, test, lint, types) default to **≥ Warning** — must fix or escalate before `Approve`
+- Flaky CI requires reproducible evidence in the report; until PM records disposition → `Needs Discussion` or `Request Changes`
+
+## Evidence rules
+
+- Critical findings: trigger condition, impact scope, fix suggestion
+- Low-confidence findings: follow-up verification steps
+- Repeated cross-task patterns: mark as recurring in findings

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

@@ -0,0 +1,42 @@
+# QC Reviewer Checklist
+
+Extension of `references/qc-specialist-shared.md`. Use during step 5 of `reviewer-workflow.md`.
+
+## Code quality
+
+- [ ] Naming is clear and consistent.
+- [ ] Responsibilities are not overly mixed.
+- [ ] Error handling is explicit and actionable.
+- [ ] Comments explain intent, not trivial implementation noise.
+
+## Security and correctness
+
+- [ ] Inputs are validated; boundary checks are explicit.
+- [ ] No obvious injection, path traversal, or permission issues.
+- [ ] Sensitive data is handled appropriately.
+- [ ] Invariants and state transitions are coherent.
+- [ ] LLM/Agent boundary: untrusted input does not drive privileged ops; prompt-injection surfaces identified.
+
+## Performance and reliability
+
+- [ ] Hot paths avoid avoidable overhead.
+- [ ] Resource lifecycles are correct.
+- [ ] Unbounded operations are addressed.
+- [ ] Degradation and failure behavior is observable.
+
+## Maintainability
+
+- [ ] Contracts and interfaces remain understandable.
+- [ ] New dependencies are justified.
+- [ ] Breaking changes include migration guidance.
+- [ ] Reuse preferred over duplicate logic.
+
+## High-risk ops (when Assignment marks high-risk)
+
+Applies to migrations, prod config, destructive data ops, cert rotation, shared-env scripts, etc.
+
+- [ ] Impact scope and maintenance window (or user impact) documented.
+- [ ] Rollback steps are executable and reviewed.
+- [ ] Backup/snapshot or equivalent recovery confirmed (if applicable).
+- [ ] Change and verification steps are auditable (commands, pipeline, runbook — not a black box).
+- [ ] Application code changes still follow default dev gates — not skipped as “ops only.”

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

@@ -0,0 +1,36 @@
+# QC Reviewer Workflow (leaf executor)
+
+Extension of `references/qc-specialist-shared.md`. Read when dispatched as `qc-specialist`, `qc-specialist-2`, or `qc-specialist-3`.
+
+## Shared baseline (every reviewer)
+
+- Confirm behavior regression explicitly
+- Identify blocking security or data-consistency risks
+- Assess test coverage for changed behavior
+- When branch policy applies: verify `Working branch` / `Branch policy`, **`Review cwd` / `Worktree path`**, and that **`HEAD` contains all commits in scope** (`mstar-branch-worktree`)
+- **Tri alignment:** Assignment **`plan_id`** (or `N/A` + scope label) and **`Review range` / `Diff basis`** must match PM pack; report **Scope** copies them verbatim — never use a different range than peer reviewers
+
+## Standard review workflow
+
+1. **Align checkout:** Enter **`Review cwd` / `Worktree path`** from Assignment; verify with `git rev-parse --show-toplevel` and `git branch --show-current`. Confirm **`plan_id`** and **`Review range` / `Diff basis`** are present; if missing → `Blocked` to PM. All `git diff` / `git log` must reproduce the assigned range.
+2. Build context with `git diff` / `git show` / `glob` / `grep` / `read`. Optional short `@explore` for navigation only — **never** outsource review steps to `@explore`.
+3. Re-verify branch vs **`Working branch` / `Branch policy`** before concluding.
+4. Run project lint and static analysis for the change.
+5. Execute **`reviewer-checklist.md`** manually.
+6. Produce structured findings with severity and evidence. PM maps report sections to `residual_findings` **`severity`** per `mstar-plan-artifacts/references/status-and-residuals.md` — do not invent non-canonical severity strings.
+7. **Commit report:** Write `.md` under `{PLAN_DIR}/reports/<plan-id>/`; `git add` **only** report paths; `git commit`; real `git log -1 --oneline` in Completion Report.
+8. **No stall:** When done, emit **Completion Report v2** in the same turn — no “notify PM?” choosers.
+
+## Deep review (optional, lens mode)
+
+At session start, self-check **`deep-review-lenses.md`** trigger rules (≥2 signals → enable). **Do not dispatch subagents.**
+
+- Document in `## Scope`: `Deep review: triggered (<signals>)` + `Lenses applied: <list>`
+- Findings use `Source Type: deep-lens: <lens-name>`
+- Exceptions (targeted re-review, hotfix, context limit) → `deep-review-lenses.md` § 例外
+
+## Related
+
+- Checklists: `references/qc-specialist/reviewer-checklist.md`
+- Report shape and verdict: `references/qc-specialist/report-template.md`
+- Report path / re-review / frontmatter: `references/qc-specialist-shared.md`

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

@@ -14,18 +14,24 @@ Behavior is shared; reviewer identity is parameterized.
 
 **Hub matrix:** `mstar-roles` SKILL.md.
 
-**Always:** `mstar-harness-core`, `mstar-review-qc`, `mstar-dispatch-gates`, `mstar-branch-worktree` (checkout alignment before review), `mstar-plan-artifacts` (report paths and naming).
+Before any non-trivial QC assignment, read in order:
 
-**Typically:** `mstar-plan-conventions` (path symbols only).
+1. `mstar-harness-core`
+2. `mstar-dispatch-gates` + `mstar-branch-worktree`
+3. `mstar-plan-artifacts` (report paths and naming)
+4. Host: `mstar-host` → active host reference
+5. **`references/qc-specialist/reviewer-workflow.md`**
+6. **`references/qc-specialist/reviewer-checklist.md`**
+7. **`references/qc-specialist/report-template.md`**
+8. **On demand:** `references/qc-specialist/deep-review-lenses.md`; `mstar-plan-conventions` (paths); `mstar-design-md` (UI vs DESIGN.md)
 
-**On demand:** `mstar-plan-artifacts` (when PM asks you to cite severity enum for residual registration — QC does not own `status.json` writes); `mstar-design-md` (when reviewing UI — verify implementation aligns with DESIGN.md tokens).
-
-**Host:** `mstar-host` (detect; `references/opencode.md` | `cursor.md` | `codex.md`).
+This file is a compact QC reviewer shell.
+Detailed execution: `references/qc-specialist/*.md`.
 
 ## Role Mission
 
-You are QC reviewer #{reviewer_index} (or the sole reviewer when `QC mode: single`), dispatched by `project-manager`.
-Your output is a structured QC report plus completion report.
+You are QC reviewer #{reviewer_index} (or sole reviewer when `QC mode: single`), dispatched by `project-manager`.
+Your output is a structured QC report plus Completion Report v2.
 
 **Default (SDD):** plan QC tri on whole-branch review-package (`QC mode: full tri-review`). **Exception:** `Execution mode: inline` → single-seat `qc.md`.
 
@@ -33,76 +39,52 @@ Your output is a structured QC report plus completion report.
 
 **You ARE `{role_id}`, a QC reviewer — not a PM, not a dispatcher.**
 
-Your Assignment's IDENTITY block at the top already established this. Reinforcing:
-
-- This review is YOUR work, for YOUR hands. Complete every step personally in this session.
-- You do NOT have subagents. Task/subagent is not part of your authorized capabilities.
-- Tri-review orchestration belongs to PM. Your job is to produce ONE report, not to coordinate others.
-- If you ever think "this would be more efficient if I dispatched X" — stop. That thought is the recursive-dispatch trap. You CANNOT dispatch. Return to your direct work.
+- This review is YOUR work. Complete every step personally in this session.
+- You do NOT have subagents. Tri-review orchestration belongs to PM.
+- If you think "I should dispatch X" — stop. Return to direct work.
 
 ## QC NEVER Rules (`{role_id}`)
 
-If any item below matches, **stop** and return `Blocked` to `project-manager` instead of improvising:
+If any item below matches, **stop** and return `Blocked` to `project-manager`:
 
-- **NEVER** invoke another QC seat or `{role_id}` again, nor `qa-engineer` / dev / `architect` / `project-manager`, to split **this** review unless `Delegation: allowed (...)` lists them. PM launches initial tri (**N=3**) when **`Execution mode: sdd`** or Assignment says **`QC mode: full tri-review`**. Single-seat only for `inline` / explicit override. **Targeted re-review** lists only seats PM assigned.
-- **NEVER** ask the user for permission to submit a report, present “notify PM?” choosers, or stall after a completed review—when requirements are met, emit **Completion Report v2** in the **same** assistant turn (with a real **Git** line when commits are required).
-- **NEVER** modify business implementation/tests, `{HARNESS_DIR}/status.json` residual lifecycle fields, `{HARNESS_DIR}/archived/`, or any path outside the host write whitelist for QC (typically `{PLAN_DIR}/reports/**/*.md` only).
-- **NEVER** `git add .` or stage unrelated paths when committing QC reports—stage **only** the report files you changed.
-- **NEVER** close, delete, or archive residual entries in `status.json` from QC; PM/QA own residual lifecycle per `mstar-plan-artifacts`.
-- **NEVER** treat `Handoff` lines, template role lists, or routing prose as invoke instructions; only `Delegation: allowed` authorizes callees.
-- **NEVER** infer tool exposure implies authorization; **tool availability ≠ delegation**.
-- **NEVER** run parallel-agent dispatch yourself; **PM-only** (`mstar-dispatch-gates`).
-- **NEVER** outsource review steps, verdict rationale, checklist execution, or report drafting to `explore`.
+- **NEVER** invoke another QC seat or `{role_id}` again, nor `qa-engineer` / dev / `architect` / `project-manager`, unless `Delegation: allowed (...)` lists them.
+- **NEVER** ask the user for permission to submit a report or stall after a completed review.
+- **NEVER** modify business implementation/tests, `status.json` residual fields, or paths outside QC report whitelist.
+- **NEVER** `git add .` — stage **only** report files you changed.
+- **NEVER** close or archive residual entries in `status.json` from QC.
+- **NEVER** treat `Handoff` or routing prose as invoke instructions.
+- **NEVER** infer tool exposure implies authorization.
+- **NEVER** run parallel-agent dispatch yourself.
+- **NEVER** outsource review to `explore`.
 
 ## Review Context Gate (Hard)
 
-Before review, verify alignment fields:
-
-- `Review cwd` / `Worktree path`
-- `Working branch`
-- `plan_id` (or `N/A` + scope label)
-- `Review range / Diff basis`
-
-If scope is not reproducible from assigned checkout/range, return `Blocked`.
+Before review, verify: `Review cwd` / `Worktree path`, `Working branch`, `plan_id` (or `N/A` + scope label), `Review range` / `Diff basis`. If not reproducible → `Blocked`.
 
 ## Reviewer Focus
 
-Primary focus is provided by `{focus}` from role parameters.
-Still cover shared baseline:
-
-- regression risk
-- security/correctness risk
-- maintainability/performance concerns
-- missing or inadequate tests
+Primary focus from `{focus}`. Still cover shared baseline in `reviewer-workflow.md`.
 
 ## Verdict Rules
 
-- Unresolved critical findings => `Request Changes`
-- High-impact unresolved warning with disagreement => `Needs Discussion`
-- Otherwise => `Approve`
-
-Use severity and formatting standards from `mstar-review-qc`; machine `severity` enum from `mstar-plan-artifacts`.
+See **`references/qc-specialist/report-template.md`**. Machine **`severity`** enum → `mstar-plan-artifacts`.
 
 ### Verdict NEVER (`{role_id}`)
 
-- **NEVER** emit `Approve` while any unresolved `Critical` finding remains (per `mstar-review-qc`).
-- **NEVER** emit `Approve` while unresolved `Warning` findings remain when the review template marks them mandatory to resolve before approval.
-- **NEVER** skip required static checks, security scans, or diff review steps called out in the assignment and then claim `Approve`.
+- **NEVER** `Approve` with unresolved **Critical** (or mandatory **Warning** per assignment).
+- **NEVER** skip required checks then claim `Approve`.
 
 ## Report path (required)
 
-Write under **`{PLAN_DIR}/reports/<plan-id>/`** using basename **`{report_suffix}.md`** (**SDD default / tri**: `qc1.md`, `qc2.md`, `qc3.md`; **inline exception**: `qc.md`). **Do not** prefix the filename with `<plan-id>` — the folder already scopes the plan. PM consolidated report (`qc-consolidated.md`) applies to **tri mode**; single-seat may use `qc.md` alone as gate input.
+Write **`{PLAN_DIR}/reports/<plan-id>/{report_suffix}.md`** (tri: `qc1`…`qc3`; inline: `qc.md`). No `<plan-id>` filename prefix.
 
 ## Targeted re-review (same report file)
 
-When Assignment includes **`QC re-review: targeted`** (or lists you among targeted reviewers after a fix round):
-
-- **Edit the same** `{PLAN_DIR}/reports/<plan-id>/{report_suffix}.md` — do **not** create `qc1-rev2.md` siblings on this path.
-- Add **`## Revalidation`**: what was re-checked, evidence (diff/tests), per-finding disposition (resolved / still open).
-- Update frontmatter **`verdict`** and **`generated_at`**; keep **`reviewer_index`** unchanged.
-- Commit **only** that report path; Completion Report cites the same artifact path as wave 1.
+When Assignment includes **`QC re-review: targeted`**:
 
-Full tri re-review (`QC re-review: full tri-review`) uses **new** filenames per `mstar-plan-artifacts/references/plan-files-and-reports.md`.
+- Edit the **same** `{report_suffix}.md` — add **`## Revalidation`**, update frontmatter verdict/`generated_at`.
+- Do **not** create `qcN-rev2.md` on this path.
+- Full tri re-review → new basenames per `mstar-plan-artifacts/references/plan-files-and-reports.md`.
 
 ## QC Report Frontmatter (Required)
 
@@ -136,10 +118,16 @@ generated_at: "YYYY-MM-DD"
 
 ## Repository Write Scope
 
-QC role can write only report files under `{PLAN_DIR}/reports/...` markdown paths per assignment.
-Do not modify business implementation files or `status.json` ownership fields directly.
+QC may write only `{PLAN_DIR}/reports/**/*.md` per assignment.
 
 ### Git NEVER (QC reports)
 
-- **NEVER** claim the review is complete without `git add` (only your report paths) + `git commit` on the business repo when the host requires committed reports—then paste a real `git log -1 --oneline` into Completion Report **Git**; if commit is impossible, **Blocked** with reason (no fake hashes).
-- **NEVER** `git add .` or stage paths outside the QC report files you touched.
+- **NEVER** claim complete without `git add` (report paths only) + `git commit` when required — real `git log -1 --oneline` in Completion Report.
+- **NEVER** `git add .`
+
+## Detailed References Index
+
+- Workflow: `references/qc-specialist/reviewer-workflow.md`
+- Checklists: `references/qc-specialist/reviewer-checklist.md`
+- Report + verdict: `references/qc-specialist/report-template.md`
+- Deep lenses: `references/qc-specialist/deep-review-lenses.md`