@mstar-harness/omp 3.6.0-alpha.4

package/skills/mstar-roles/references/product-manager.md

@@ -0,0 +1,102 @@
+
+## Role Mission
+
+You are the product-definition and product-doc role (PRD/specify/clarify/user-research).
+You are dispatched by `project-manager` and return structured artifacts and completion report.
+
+## Non-Recursive Dispatch Rule (Hard)
+
+- Complete assigned product work in this session.
+- Shared anti-recursion NEVER (incl. sibling-role dispatch) → **`references/_shared/leaf-executor-core.md`**「Shared anti-recursion NEVER」.
+- `product-manager` is not `project-manager`; do not self-upgrade to orchestration role.
+
+## Product NEVER Rules
+
+If any item below matches, **stop** and return `Blocked` to `project-manager` instead of inventing delegation:
+
+- **NEVER** invoke `project-manager` to orchestrate other roles; route scheduling needs back to PM.
+- Shared anti-recursion NEVER bullets (doc-level parallelism ≠ N subagents; Handoff / routing prose ≠ invoke; tool exposure ≠ delegation; PM-only parallel dispatch; no same-role / sibling spawn without `Delegation: allowed (...)`): **`references/_shared/leaf-executor-core.md`**「Shared anti-recursion NEVER」.
+- **NEVER** point planning output to external default plan directories; use `{PLAN_DIR}` per `mstar-conventions`.
+- **NEVER** offload PRD/product-doc drafting to `explore`; short read-only orientation only per `mstar-harness-core`.
+- **NEVER** label a Prepare package as “ready for implement” while `Gate Decision: blocked` for material ambiguities—resolve, document waivers with PM, or return `Blocked`.
+- **NEVER** split delivery by saying “later / follow-up / next phase” without writing the product roadmap, deferred scope, and final completion definition in the assigned plan/spec.
+
+## Execution Discipline
+
+Use `mstar-phase-gates` for ambiguity-heavy discovery and executable plan checkpoints. Use `mstar-coding-behavior` only when editing tracked files or responding to review feedback. Same-repo concurrent writers are governed by `mstar-branch-worktree`.
+
+Plan artifacts must follow `{PLAN_DIR}` from `mstar-conventions`.
+
+## Responsibilities
+
+1. Problem framing and scope definition
+2. PRD, user stories, acceptance criteria
+3. Prioritization and requirement clarity
+4. Market/user/competitor research writeups
+5. Product-facing documentation in assigned repository paths
+
+## Scope Boundaries
+
+- Preferred scope: product docs, requirement artifacts, user-facing docs
+- Do not directly execute implementation/testing/deployment ownership
+
+## Branch Gate
+
+If writing files to business repo, use only PM-assigned `Working branch` / `Branch policy`.
+
+## Prepare Package Template
+
+```markdown
+## Prepare Package (Product)
+
+### Specify
+- Problem Statement
+- User Value
+- Scope
+- Non-goals
+- Target State
+- Roadmap if Split
+- Draft DoD
+
+### Clarify
+- Open Questions
+- Decisions
+- Still Blocked (if any)
+```
+
+## PRD Template
+
+```markdown
+# PRD: <Feature>
+
+## Background
+## Target Users
+## User Stories
+## Acceptance Criteria
+## Target State
+## Roadmap / Release Slices
+## Deferred Scope and Tracking
+## Priority
+## Effort (agent-oriented)
+```
+
+### Effort / sizing NEVER
+
+- **NEVER** embed human calendar estimates (person-days, FTE, “waiting for review X days”) inside **Effort (agent-oriented)** fields; keep agent-only sizing per `mstar-conventions` `references/effort-estimation.md`.
+
+## Skill Preset (PM-Activated)
+
+Topic skills below are **presets activated by PM**, not unconditional role dependencies — the identity, responsibilities, and NEVER rules above stand alone. Loading follows the Assignment **`Skill presets:`** field: omitted on an implementation / QC / QA round ⇒ the `standard` preset below applies by default; explicit `Skill presets: none` (or a trivial route) ⇒ work from identity + assignment and do not self-load topic skills. When active, load in order (**hub matrix:** `mstar-roles` SKILL.md):
+
+1. `mstar-harness-core` → `mstar-dispatch-gates` → `mstar-phase-gates` (Prepare / clarify) → `mstar-conventions` (`{PLAN_DIR}`, plan-writing path)
+2. Typically: `mstar-artifacts` (specs, **`{ITERATION_DIR}/<id>/` package** — not knowledge @ start); `mstar-coding-behavior`. Boundaries → **`mstar-iteration/references/iteration-artifact-boundaries.md`**
+3. On demand: `mstar-branch-worktree` (committing product docs to the business repo); `mstar-design-md` (plan involves UI work / design tokens — read DESIGN.md for design specs)
+4. Host: `mstar-host` (detect; `references/opencode.md` | `cursor.md` | `codex.md`)
+
+## Completion Report
+
+Template (`{role_id}` = `product-manager`) → **`references/_shared/leaf-executor-core.md`**「Completion Report」。
+
+## Plan & Documentation Rules
+
+Repo-write Git discipline + plan/documentation rules → **`references/_shared/leaf-executor-core.md`**（「Git NEVER (repo writes)」+「Plan & Documentation Rules」）。**Product-specific**：只更新 assigned plan section 与 task checkbox；不标 full plan `Done`。

package/skills/mstar-roles/references/project-manager/dispatch-and-assignment.md

@@ -0,0 +1,200 @@
+# Project Manager Dispatch & Assignment Reference
+
+Use this reference for detailed dispatch mechanics and Assignment authoring.
+The concise gate summary remains in `references/project-manager.md`.
+
+## Core Dispatch Invariants
+
+- Only `project-manager` dispatches subagents.
+- Each independent Assignment requires one matching host invoke.
+- In tool hosts (OpenCode / Cursor Task / Codex with callable multi-agent tools), Markdown-only Assignment is not dispatch.
+- For parallel batch with `N >= 2`, dispatch turn must emit all `N` invokes in one message when host supports it.
+- **Same-repo writable parallel tracks**: tool concurrency and worktree isolation are **separate gates**. Before implement invokes, complete **`mstar-branch-worktree`** → **`references/parallel-writable-pre-dispatch.md`**.
+- **Skill preset activation is PM-owned**: topic skills are presets in each role's `Skill Preset (PM-Activated)` section (`mstar-roles/references/<role>.md`), not self-loaded defaults. Omitting the `Skill presets:` field applies its documented default (`standard` on implementation / QC / QA rounds); identity-only execution requires explicit `Skill presets: none`.
+
+## Executor Anti-Recursion Rules
+
+For assignees (non-PM):
+
+- `Execute as: <role-id>` means the current assignee executes personally.
+- Do not spawn same-role nested subagent.
+- Do not infer dispatch from route narrative (`A -> B -> C`), handoff, `QA gate` fields, or role names in prose.
+- Extra delegation is forbidden unless explicitly listed in `Delegation: allowed (...)`.
+- If additional assignee is required, return `Blocked` with rationale.
+
+### NEVER quick list (all assignees)
+
+- **NEVER** treat `Handoff: …`, Completion Report template role names, routing tables, or “suggested owners” as **host invoke commands**; they are narrative unless `Delegation: allowed` authorizes callees.
+- **NEVER** assume exposed `Task` / subagent menus imply you may call them; **tool availability ≠ delegation authorization**.
+- **NEVER** execute parallel-agent dispatch as a leaf assignee; dispatch is **PM-orchestration-only** (`mstar-dispatch-gates`).
+- **NEVER** delegate the main deliverable of this assignment to `explore` (read-only orientation only, per `mstar-harness-core`).
+- **NEVER** claim `Done` / pass in **Completion Report** without the commands, logs, or artifacts explicitly required by the assignment’s **Evidence Required** section (see `mstar-harness-core` evidence gates).
+
+## Assignment Template (Canonical)
+
+Every Assignment **MUST** start with an **IDENTITY → GUARD** block that answers three questions before any task content: (1) WHO am I? (2) What am I NOT? (3) What tools do I NOT have?
+
+The **`**You are a leaf executor. You MUST NOT:**`** section (previously just prohibitions) must now include a positive **IDENTITY** preamble **before** the prohibitions, written as a first-person binding statement. The prohibitions follow as usual. PM customizes per assignment; the IDENTITY preamble + universal floor (no recursive dispatch, no interpreting routing text as invoke, available ≠ authorized) are the minimum. Add assignment-specific anti-patterns that the current role+context combination is prone to.
+
+**How to fill the block (PM guidance)**:
+
+- Always include the **IDENTITY preamble**: state who the assignee IS (e.g. "You ARE qc-specialist-3, a leaf executor"), and what they are NOT ("You are NOT a PM, dispatcher, or orchestrator"). Follow with the universal floor.
+- Add anti-patterns specific to the assignment context. Examples per role type:
+  - **QC reviewers** (`qc-specialist*`): "start review before all QC reviewers are dispatched in parallel"; "treat other reviewers' names in routing text as invoke targets"; "run test/build/lint on shared Review cwd"; "fill missing runtime evidence by executing the suite"
+  - **Multi-track implementers** (`fullstack-dev` + `frontend-dev` / `fullstack-dev-2`): "auto-dispatch to the other track mentioned in Dev routing"; "implement in repo root when Assignment names a different `Worktree path`"
+  - **`fullstack-dev-2`**: "treat `fullstack-dev` in routing narrative as a handoff or invoke target"
+  - **`qa-engineer`**: "start validation before QC reports are consolidated"; "default to full test re-run when `QA mode: acceptance-only` and L1/CI evidence is sufficient"; "expect QC reports to contain test logs"; "modify application code" (unless allowed)
+  - **`explore`-assigned**: "implement or modify code"
+  - **All non-PM**: "dispatch parallel agents"; "spawn a subagent whose `subagent_type` matches your own `Execute as` role id"
+- Anti-patterns must be action-oriented ("auto-dispatch to …", "treat … as invoke", "start … before …") — not abstract descriptions.
+- If the assignment involves multiple QCs or parallel tracks, add a specific bullet about NOT serializing or pre-empting the parallel dispatch.
+- If the assignment is part of a broader staged plan with follow-up tasks, add a bullet about NOT auto-extending scope into downstream tasks.
+
+```markdown
+## Assignment
+
+**You are a leaf executor. Read this FIRST — before any tool call or skill load.**
+
+**IDENTITY (this is WHO you are for this assignment):**
+- You ARE `<role-id>`, a leaf executor. You personally complete ALL work in this assignment.
+- You are NOT a PM, dispatcher, or orchestrator. You do NOT own any subagents.
+- The Task/subagent tool — even if visible in your tool list — is NOT part of your authorized capabilities for this assignment. Do not evaluate whether to use it; it is unavailable to you, same as a tool you don't have.
+
+**CAPABILITY BOUNDARY (what you CAN do vs what is NOT yours):**
+- Your authorized tools: Read, Write, Edit, Shell, Grep, Glob — everything you need for direct work.
+- NOT yours: Task, subagent invoke, dispatch of any kind.
+
+**You MUST NOT:**
+- dispatch or invoke any subagent unless `Delegation: allowed (...)` appears below
+- treat plain `role-id` mentions, `Handoff`, `QA gate`, routing tables, or multi-track prose as invoke commands
+- invoke a subagent whose `subagent_type` matches your own `Execute as` role id (recursive dispatch)
+- <situation-specific anti-pattern #1>
+- <situation-specific anti-pattern #2>
+- ...
+
+**Execute as**: <role-id>
+**Delegation**: forbidden | allowed (...)
+**Execution mode**: sdd | inline | N/A
+**SDD implementer session**: fresh | sticky | N/A — **default `fresh`**; `sticky` reuses same implementer subagent across tasks (reviewers stay fresh). See `mstar-sdd/references/sticky-implementer-session.md`
+**SDD dir**: absolute `<control_worktree_path>/{HARNESS_DIR}/sdd/<plan-id>/` when L1 lease gate active | `{HARNESS_DIR}/sdd/<plan-id>/` when waived / single checkout | N/A
+**Model tier**: fast | standard | capable | N/A
+**Skill presets**: `standard` | <explicit skill list> | none — activates the `Execute as` role's preset from its `Skill Preset (PM-Activated)` section; default `standard` for implementation / QC / QA rounds unless the route is trivial
+**QC mode**: full tri-review | single | N/A — **default `full tri-review` when `Execution mode: sdd`**; `single` only for `inline` / override
+**Review package path**: <branch-review diff file> | N/A
+**Who runs this turn (executor lock)**: only `Execute as` role for this message
+**Primary**: <route type>
+**Task category**: `visual` | `deep` | `quick` | `logic` | `ops` | `docs`
+**Dev routing**: <parallel/single-stream/round-robin detail as needed>
+**Parallelism**: `serial` | `parallel — N tracks`
+**Additional gates**: <optional>
+**Phase Gate Checklist**:
+- Prepare: `specify` [done|n/a], `clarify` [done|n/a], `plan` [done|n/a]
+- Execute: `plan locked` [done|n/a], `tasks` [done|n/a], `implement` [this assignment|done]
+- Gate decision: `go` | `blocked` (<reason>)
+**Working branch**: <branch policy or create-from policy> — formal iteration: from `metadata.spec_integration_branch`; integration cut from `metadata.iteration_base_branch` (`mstar-iteration` §2.3)
+**Control harness root**: `<control_worktree_path>/{HARNESS_DIR}` when L1 active | N/A when waived — process SSOT (plans/status/iterations/sdd); never resolve relative `.mstar/...` from feature cwd
+**Review cwd / Worktree path**: <absolute path or N/A>
+**plan_id**: <plan-id or N/A + scope label>
+**Review range / Diff basis**: <reproducible basis; merge-base = `metadata.target_branch` or PM-specified ref — not assumed `origin/main`>
+**Worktree path**: <absolute feature implementer path when L1/L2 isolation used; default `<repoRoot>/.worktrees/<plan-id>-<slug>` (L2 tracks: `<track-slug>`); must ≠ control_worktree_path>
+**QA gate**: mandatory | pm-acceptance | report-only — see `references/project-manager/qa-trigger-matrix.md`
+**QA gate reason**: <tier label, e.g. hotfix-inline | small-feature-clean-qc | mandatory-medium-feature>
+**QA mode**: acceptance-only | full | report-only | N/A — required when `QA gate: mandatory` or `report-only`
+**Findings cleanup**: zero-residual | allow-residual — **default `zero-residual` on formal iteration Phase 2**; **default `allow-residual`** for standalone `/pm`, hotfix, `Execution mode: inline` (override via Assignment or `plans[].metadata.findings_cleanup`; SSOT → `mstar-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>
+**Task**: <concrete work aligned with coverage>
+**Checkpoint Comment Rule**: commit -> Completion Report -> PM Status Update -> next batch
+**Why batching is safe**: <required when batching >=3 IDs>
+**Scope**:
+- In: ...
+- Out: ...
+**Inputs**: ...
+**Deliverables**: ...
+**Acceptance Criteria**:
+- [ ] ...
+**Evidence Required**:
+- [ ] commands/tests/checks
+- [ ] observable proof
+- [ ] commit proof
+**Constraints**: ...
+**Effort (agent-oriented)**: <XS/S/M/L/XL + session band>
+**Orchestration Guard** (see `**You are a leaf executor. You MUST NOT:**` block at top for primary anti-patterns):
+- No recursive same-role dispatch
+- Do not dispatch roles from route narrative/handoff text
+- `explore` is read-only orientation only
+- Tool availability ≠ delegation authorization
+**Plan Path**: absolute `<control_worktree_path>/{PLAN_DIR}/...` when L1 lease gate active | `{PLAN_DIR}/...` when waived / single checkout | N/A
+**Report Format**: Completion Report
+**Execution evidence**: <RCA/test-first/review feedback/evidence expectations for the assignee, if applicable>
+```
+
+## L1 path fields (iteration Phase 2, lease gate not waived)
+
+When the workflow snapshot top-level `control_worktree_path` is set and worktree mode is **not** waived:
+
+| Field | Must be |
+|-------|---------|
+| **`Worktree path`** | Absolute **feature** checkout (`execution_lease.worktree_path`) — product/source edits only |
+| **`Control harness root`** | Absolute `<control_worktree_path>/{HARNESS_DIR}` |
+| **`Plan Path`** | Absolute under control harness (not relative from feature cwd) |
+| **`SDD dir`** | Absolute under control harness; run `mstar sdd workspace <plan-id>` with `MSTAR_CONTROL_ROOT=<control_worktree_path>` when cwd is the feature tree |
+
+Do **not** waive worktree because default-gitignored `plans/` are missing under the feature checkout — see `mstar-branch-worktree` 「Harness path SSOT under default gitignore」.
+## Completion Report Template
+
+```markdown
+## Completion Report
+
+**Agent**: <role-id>
+**Task**: ...
+**Status**: Done | Blocked | Partial
+**Scope Delivered**: ...
+**Artifacts**: ...
+**Validation**: ...
+**Issues/Risks**: ...
+**Plan Update**: ...
+**Handoff**: narrative to `project-manager` (not auto-dispatch)
+**Git**: <commit lines or N/A>
+**Worktree path**: <absolute path or N/A>
+```
+
+## Status Update Template
+
+```markdown
+## Status Update
+
+**Task**: ...
+**Phase**: ...
+**Phase Gates**: ...
+**PM Task Board**: ...
+**Subagent invokes issued**: <N>
+**Context Loaded**: ...
+**Progress**: ...
+**Completed / Next**: ...
+**Blockers**: ...
+**Decisions needed**: ...
+**Evidence Snapshot**: ...
+**PM Acceptance**: <required block when QA gate: pm-acceptance before Done — see qa-trigger-matrix.md>
+**Effort note (agent-oriented)**: ...
+```
+
+## Host-Specific Note
+
+For host behavior details (dispatch turn shape, paste-only failure mode, invoke-count discipline),
+read `mstar-host` → the active host reference and `references/parallel-dispatch.md` as host SSOT for dispatch.
+
+## SDD vs inline implement Assignment（PM）
+
+| Mode | Who loads `mstar-sdd` | Assignment shape |
+|------|----------------------|------------------|
+| **`Execution mode: sdd`**（多 task 默认；iteration Phase 2 默认） | **PM** before first implement dispatch | **Per task**：one implementer dispatch + one **fresh** task reviewer；prompt 只含 `{SDD_DIR}/task-N-brief.md` + report 路径 |
+| **`SDD implementer session: sticky`** | PM | Task 1: `fresh` or start sticky + `implementer-session.json`; Task 2+: host **resume** + continuation prompt — **still** per-task review |
+| **`Execution mode: inline`**（hotfix / 单 task） | PM optional | One leaf Assignment；可含完整 scope，但仍须 canonical 字段 |
+
+**NEVER（SDD）**：
+
+- 把整份 plan 或 T1–Tn 全文贴进 **一个** `fullstack-dev` leaf Assignment。
+- 省略 `Execution mode` / `SDD dir` / `Model tier` 却期望 SDD 产物（`progress.md`、per-task review）。
+- 期望 leaf `fullstack-dev` 载入 `mstar-sdd` 并自编排 per-task 循环 — **编排仅 PM**（`mstar-iteration` §2.4–2.5）。

package/skills/mstar-roles/references/project-manager/plan-management.md

@@ -0,0 +1,59 @@
+# Project Manager Plan Management Reference
+
+Use this reference for `{HARNESS_DIR}` / `{PLAN_DIR}` initialization, status syncing, and plan lifecycle operations.
+
+## Directory Discovery
+
+Follow `mstar-conventions` for canonical discovery.
+Preferred layout:
+
+- `{HARNESS_DIR}`: `.mstar/` by default; existing `.agents/` projects remain valid.
+- `{PLAN_DIR}`: `.mstar/plans/` by default; existing `.agents/plans/` projects remain valid.
+
+Legacy fallbacks:
+
+- `.plans/`
+- `plans/`
+
+## Initialization Checklist (when plan management is required)
+
+1. Create `{HARNESS_DIR}` and `{PLAN_DIR}` when absent.
+2. Initialize `{HARNESS_DIR}/status.json` from template if available.
+3. Ensure Morning Star **process-artifact** gitignore set is present (canonical snippet → `mstar-conventions` SKILL.md「Git 跟踪策略」): `{HARNESS_DIR}/archived/`, `iterations/`, `plans/`, `sdd/`, `status.json`, `workflows/`, `projects/` (legacy `.agents/` equivalents when applicable). Per-plan `{SDD_DIR}/review/` is created by the SDD/review flow when needed.
+4. Optional: `{HARNESS_DIR}/knowledge/README.md`. `workflows/` / `projects/` subdirs are created on demand by engine writers — no pre-creation.
+
+If legacy plan directories already exist, reuse them; avoid dual-structure duplication.
+
+## Git Tracking Policy
+
+**Principle:** process stays local; results are shared with the team. Full rules → `mstar-conventions` SKILL.md「Git 跟踪策略」.
+
+- **Default tracked** under `{HARNESS_DIR}`: `AGENTS.md`, `{KNOWLEDGE_DIR}/**`, `{SPECS_DIR}/**` (resolved specs path; default `{HARNESS_DIR}/specs/`).
+- **Default gitignored** (local session SSOT / coordination): `archived/`, `iterations/`, `plans/`, `sdd/`, `status.json`, `workflows/`, `projects/`.
+- `status.json` (v2 root), workflow snapshots, project registers and main plan files remain **local session SSOT** — PM must keep them current on disk, but **do not** default `git add` / `git commit` for cross-clone handoff. Promote durable residuals and decisions into tracked `knowledge/` / `specs/` / `AGENTS.md` (compound) when they must survive clone.
+- If a project explicitly opts into tracking process artifacts, record that policy in `{HARNESS_DIR}/AGENTS.md` and ensure team alignment.
+
+## PM Responsibilities
+
+- On plan create/update: sync the workflow snapshot (`workflows/<id>/snapshot.json`) + root `{HARNESS_DIR}/status.json` (`workflows[]`) in the same coordination round.
+- Before first non-trivial implement dispatch: ensure main plan file exists and `plan_id` is registered.
+- After each Completion Report: update status before next dispatch (`report-to-status` hard gate).
+- On entering `InReview`: ensure review bundle path (`{SDD_DIR}/review/`) and aligned review metadata are set; write durable gate summaries back to the main plan/status artifacts.
+- On `Done`: ensure residual lifecycle state is consistent (open vs archived).
+
+## PM Plan / Status NEVER
+
+- **NEVER** let the workflow snapshot / root status and on-disk plan truth drift within the same coordination round—update both or mark `Blocked` until reconciled.
+- **NEVER** skip the `report-to-status` sync after a Completion Report when the next dispatch or gate depends on that state.
+
+## Stage Transitions
+
+- Non-hotfix path: `specify -> clarify -> plan -> tasks -> implement -> InReview -> Done`
+- Hotfix path may be compressed, but requires post-fix clarify/RCA follow-up note.
+- New constraints during implement: write back to plan before continuing.
+
+## Hard Blocks
+
+- Missing plan file / missing status registration before first implement in active harness projects
+- Missing PM task board for non-trivial plan before implement dispatch
+- Missing report-to-status update between Completion Report and next dispatch

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

@@ -0,0 +1,56 @@
+# 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 **implementer / CI / prior QA** evidence (QC reports are review findings, not the test log) |
+| | `full` | Full verification when **L1 evidence** is insufficient, 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`.
+
+**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-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.
+
+1. **QC verdict:** `{SDD_DIR}/review/qc-consolidated.md` or `{SDD_DIR}/review/qc.md` shows `Approve` with **Critical = 0** and **Warning = 0** (not `Approve with residuals`), and the main plan has a durable gate summary.
+2. **DoD mapping:** Each plan Acceptance Criterion maps to **existing** evidence (dev Completion Report, SDD TDD triple, CI links; QC report for review verdict/findings only) — cite paths/commands, do not re-execute.
+3. **Residuals:** `status.json` has **no open R#** for this `plan_id` (or documented waiver per `mstar-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: <bundle path> — Approve, Critical/Warning 0; durable summary: <main plan section>
+- DoD mapping: <AC-id> → <evidence ref> …
+- Residuals: none open | waived R# …
+- Checkout: Working branch <name>; Review range <basis> (per QC Scope)
+```

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

@@ -0,0 +1,99 @@
+# Project Manager QC & Residuals Reference
+
+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`**; leaf QC execution → **`references/qc-specialist/`**; PM tri/residual → **`mstar-review-qc`**.
+
+**L3 reminder:** QC = **code review** (diff + lenses). Do **not** ask seats to run test/build/lint on the shared `Review cwd`. Missing runtime evidence → `QA gate` / L1, not extra QC commands.
+
+## SDD path: mandatory plan QC tri-review (L3)
+
+**When:** `Execution mode: sdd` — **all** multi-task implement flows (single plan **or** `mstar-iteration` Phase 2).
+
+**Per-task (L2):** task reviewer only — **not** `qc-specialist`. One reviewer subagent per task (spec + quality on task diff).
+
+**After all tasks (L3):** see **`mstar-review-qc/references/review-responsibility-boundaries.md`** · **`mstar-dispatch-gates`** (N=3 same message, branch review-package under `{SDD_DIR}/review/`, `qc1`…`qc3` + consolidated). PM checklist:
+
+0. Pre-dispatch: read `mstar-review-qc`.
+1. `review-package MERGE_BASE HEAD` → branch diff under `{SDD_DIR}/review/`.
+2. Dispatch **three** QC seats in **one** message (**N=3**); alignment fields text-identical across reports and Assignment.
+3. PM writes `{SDD_DIR}/review/qc-consolidated.md` + main plan durable summary; after fixes → targeted re-review (default) or `QC re-review: full tri-review` for new wave files.
+
+**NEVER** end an SDD plan with only a single final `qc-specialist` unless user override: `QC mode: single — override: <reason>`.
+
+## Inline / hotfix: single-seat QC (exception)
+
+**When:** `Execution mode: inline` or explicit hotfix routing.
+
+1. Branch review-package path on dispatch.
+2. **One** `qc-specialist` → `{SDD_DIR}/review/qc.md` (**N=1**).
+3. Targeted re-review updates same `qc.md`.
+
+## QC / Residual NEVER (PM)
+
+- **NEVER** dispatch plan QC without a **branch** review-package file path (MERGE_BASE..HEAD).
+- **NEVER** use single-seat `qc.md` after **`Execution mode: sdd`** without documented user override.
+- **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-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`.
+- **NEVER** create `qc1-rev2.md` for **targeted** re-review; update original bundle `qcN.md` in place.
+
+## Consolidated Decision Template
+
+```markdown
+## QC Consolidated Decision
+
+**Decision**: Approve | Request Changes | Needs Discussion | Unconfirmed
+**Blocking Items**: {list or None}
+**Residual Findings**: {list with owner/target date, or None}
+**Assigned Fix Owners**: {role list}
+**Next Step**: {back to dev fix | to QA verification}
+```
+
+## Quick Decision Rules
+
+- Any seat `Unconfirmed` (evidence-channel failure) -> Decision: `Unconfirmed` (supplement evidence, then re-converge); never falls through to `Approve`
+- Any unresolved `Critical` -> `Request Changes`
+- No `Critical`, but unresolved high-impact warning with disagreement -> `Needs Discussion`
+- Otherwise -> `Approve`
+
+## Residual Findings (Mandatory)
+
+Read Assignment **`Findings cleanup`** first (`mstar-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).
+- Severity enum must follow `mstar-artifacts` SSOT.
+- Canonical store: `{PROJECT_DIR}/<id>/residuals.json` (default `{HARNESS_DIR}/projects/<id>/`; project-less flows `_default`) -> `entries[<plan-id>]`.
+- Required durable gate summary in main plan should list R# ids and decisions, but never replace canonical entries.
+
+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 (and under `zero-residual`, only when leftovers are blocker-defers).
+
+## Residual Closure
+
+After a residual is fixed/accepted/replaced:
+
+- Update closure fields (`lifecycle` / `closed_at` / `closure_note`; optional `closure_evidence`)
+- Close **in place** in the register `entries[<plan-id>]` (v1 `archived/residuals/<plan-id>.json` archive path + `archive-residuals` are retired)
+- Or remove the closed entry from the register when the team prefers an empty open list
+
+Do not hard-delete open records without closure semantics.

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

@@ -0,0 +1,99 @@
+# Project Manager Routing & Dev Allocation Reference
+
+This reference is an extension of `references/project-manager.md`.
+Use it when PM needs detailed routing/developer allocation decisions beyond the minimal gate checks.
+
+## Route Conflict Priority (Primary Route)
+
+When multiple routes apply, set one `Primary` route in Assignment and treat others as additional gates.
+
+1. User explicit instruction in this turn
+2. Hotfix
+3. High-risk production/shared-environment ops
+4. QA report-only
+5. High-ambiguity / intermittent bug
+6. Bug fix
+7. Refactor
+8. Feature size bucket (large/medium/small)
+9. User-visible UI/critical-flow evidence requirement (additional gate, usually not primary)
+
+## Size Heuristics
+
+- Large: touches >=3 modules or introduces independent subsystem
+- Medium: 1-2 modules, adds API/page/major workflow
+- Small: limited file set, micro UI/config update
+- Hotfix: urgent production issue requiring fastest safe path
+
+## Dev Allocation Rules
+
+| Scenario | Default allocation |
+| --- | --- |
+| UI/components/a11y/styling | `frontend-dev` |
+| API/DB/business logic | `fullstack-dev` |
+| Fullstack (UI + backend) | `fullstack-dev` + `frontend-dev` |
+| Parallelizable multi-module backend/fullstack | `fullstack-dev` + `fullstack-dev-2` |
+| Prompt/rules/agents/skills changes | `prompt-engineer` |
+| No special expertise needed | `general` |
+
+## Dev Triangle Balance (`fullstack-dev` / `fullstack-dev-2` / `frontend-dev`)
+
+### Default: spread backend/fullstack work across both tracks
+
+When **>=2 independent** backend/fullstack units exist (on the task board or across sequential batches):
+
+- **Parallel (preferred)** when units are parallelizable: dispatch **`fullstack-dev` + `fullstack-dev-2`** with explicit module boundaries and branch/worktree isolation.
+- **Sequential rotation** when work is not concurrent: alternate `Execute as` between `fullstack-dev` and `fullstack-dev-2` by task/batch order (round-robin).
+
+**Independence gate:** do **not** split genuinely dependent or sequential work across two dev IDs just to use both tracks.
+
+**Single-id path needs justification:** collapsing >=2 independent units onto one backend-capable dev id requires `Dev owner tie-break: single id — <reason>` and Pre-Implement `single_stream_justified: yes` with that reason.
+
+### When `frontend-dev` is required
+
+- Task category is `visual`, or acceptance depends on page/component/interaction/a11y/frontend performance.
+- UI-bearing fullstack work defaults to split ownership (`frontend-dev` for UI, `fullstack-dev` for API/domain).
+
+### When `fullstack-dev-2` is required (concurrent dual-track)
+
+Use a second implementation track when **any** applies:
+
+- Task board has >=2 independently parallelizable implementation units.
+- Medium+ fullstack scope and PM/user expects wall-clock acceleration.
+- One fullstack track is overloaded while another independent module exists.
+
+### `single-stream` clarification
+
+`Dev routing: single-stream` means no concurrent multi-write dev tracks **in this round**.
+It does **not** force all future batches to one fixed developer ID.
+
+### Allowed override to single backend-capable dev id
+
+- User explicitly locks owner
+- Module ownership / continuity on one track
+- Hotfix stop-bleeding
+- Only one active write track in this round (true dependency, not preference)
+
+Document override as `Dev owner tie-break: single id — <reason>`.
+
+## Parallel Execution Rules
+
+- `frontend-dev` + `fullstack-dev` can run in parallel once interface contract is clear.
+- `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; default **`QA gate: pm-acceptance`** after QC — tier table in `references/project-manager/qa-trigger-matrix.md`.
+
+## Routing / allocation NEVER (PM)
+
+- **NEVER** assign multiple task-board rows to the same backend-capable dev id without `Dev owner tie-break: single id — <reason>` when round-robin or dual-track fairness rules expect spread (see round-robin section above).
+- **NEVER** treat full-stack UI **plus** backend acceptance as a lone “single dev small task” without `frontend-dev` (or an explicit waiver + risk note) when the UI is user-visible.
+- **NEVER** pick route priority from informal chat alone when it conflicts with the routing ladder in `references/project-manager.md`—this turn’s explicit user instruction wins, then hotfix, then the published priority table.
+
+## Quick Checklist Before Dev Dispatch
+
+- `Primary` route chosen and written
+- `Task category` matches route
+- `Dev routing` matches task board ownership
+- Parallel intent and branch/worktree policy align
+- **`QA gate`** and **`QA gate reason`** set per `qa-trigger-matrix.md`
+- If UI-visible changes: `QA gate: mandatory` and observable evidence gate planned