@mstar-harness/omp 3.6.0-alpha.4

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

@@ -0,0 +1,136 @@
+# Kimi host reference
+
+Load when **`mstar-host`** detection resolves **kimi** (Kimi Code CLI session, `Agent` / `AgentSwarm` / `AskUserQuestion` / `EnterPlanMode` tools, or `/morning-star-harness:*` plugin commands).
+
+Plan mode: read **`kimi-plan-mode-bridge.md`** when `EnterPlanMode` / `ExitPlanMode`, `/plan`, or `kimi --plan` is active.
+
+Parallel PM dispatch: read **`parallel-dispatch.md`** when dispatching **N ≥ 2** concurrent `Agent` invocations.
+
+## Kimi-only context
+
+- Plugin manifest: **`.kimi-plugin/plugin.json`** (plugin root is the **repo root**; paths stay `./skills/` and `./commands/`).
+- Runtime skills: repo `skills/` mounted by the plugin (`"skills": "./skills/"`).
+- Plugin commands: repo `commands/` → `/morning-star-harness:<name>` (e.g. `/morning-star-harness:iteration-start`).
+- **`sessionStart.skill: pm`** auto-loads the PM entry shim on new sessions; `pm` → **Read next** → `mstar-harness-core` → `project-manager.md`.
+- **`/skill:pm`** or **`pm` skill**: same PM entry when invoked manually.
+- Install (user-scoped): in Kimi TUI `/plugins install https://github.com/btspoony/mstar-harness` then `/plugins reload` (or `/new`).
+- Plugins are **user-scoped** (all projects); managed copy lives under `$KIMI_CODE_HOME/plugins/managed/` after `/plugins install`.
+- Project `.agents/skills/` symlinks are **not** required when using the plugin — commands and skills come from the plugin mount.
+
+## Skill loading
+
+1. On session start: `pm` (via `sessionStart.skill`) → **Read next** loads `mstar-harness-core`, then `mstar-roles` → `project-manager.md` when PM is active.
+2. Read `mstar-host` and this Kimi reference.
+3. If Plan mode is active, read `kimi-plan-mode-bridge.md`.
+4. Load `mstar-roles` and the active role reference.
+5. Load topic skills on demand per the role reference.
+
+Use skill names in prompts and references. Avoid absolute local paths unless maintaining this repository or skills are not installed. Skill-root resolve (plugin mount `./skills/<name>/`) → `mstar-host` § Resolve loaded skill root.
+
+## Tools map (default agent)
+
+| Kimi tool | Harness use |
+|-----------|-------------|
+| **Agent** | Primary dispatch — delegate one subagent task (`subagent_type`: `coder` \| `explore` \| `plan`) |
+| **AgentSwarm** | Parallel batch when **same** role/profile and prompts differ only by task slice; prefer **N× Agent** when roles differ |
+| **AskUserQuestion** | Structured clarify (1–4 questions, 2–4 options each); prefer over free-form when choices are known |
+| **EnterPlanMode** / **ExitPlanMode** | Plan mode entry/approval → **`kimi-plan-mode-bridge.md`** |
+| **TodoList** | Session UX only; mirror to SSOT plan / workflow snapshot (`{WORKFLOW_DIR}/<id>/snapshot.json`) when durable |
+| **Bash** | Commands, git, tests — evidence per `mstar-coding-behavior` |
+| **Read** / **ReadMediaFile** | File reads |
+| **Glob** / **Grep** | Search (prefer over shell find/grep) |
+| **Write** / **Edit** | Edits |
+| **WebSearch** / **FetchURL** | External docs / facts |
+| **TaskList** / **TaskOutput** / **TaskStop** | Long-running task management when present |
+
+OpenCode-style `question` and Cursor **Task** are **not** Kimi tools — do not assume them.
+
+## Role agents (C5 — hard constraint)
+
+Kimi ships **built-in subagent types only**. Valid **`subagent_type`** values:
+
+| `subagent_type` | Kimi profile | Harness mapping |
+|-----------------|--------------|-----------------|
+| `explore` | Read-only exploration | Orientation, codebase survey, Prepare explore passes |
+| `plan` | Plan-mode subagent | Prepare plan-only work when host is already in plan context |
+| `coder` | General implementation | **All other Morning Star roles** (`product-manager`, `fullstack-dev`, `qc-specialist`, …) |
+
+Morning Star role ids (`project-manager`, `fullstack-dev`, `qc-specialist`, …) are **not** valid `subagent_type` values. The host cannot register custom named agents like Codex TOML or Cursor `subagent_type` role ids.
+
+### Role binding in prompt (C5b — required)
+
+Role-binding contract + Assignment template → **`_shared/host-role-binding-core.md`** (C5/C5b). Kimi-specific invoke shapes, same turn:
+
+```text
+Agent(
+  subagent_type: "coder",
+  prompt: "<full Assignment body including Act as + skill load>"
+)
+```
+
+For **`explore`** orientation:
+
+```text
+Agent(subagent_type: "explore", prompt: "... Act as explore-only orientation; Execute as: n/a ...")
+```
+
+For Prepare plan-only when plan subagent is appropriate:
+
+```text
+Agent(subagent_type: "plan", prompt: "... Act as architect for plan design; load mstar-roles → architect.md ...")
+```
+
+## PM dispatch (`Agent` / `AgentSwarm`)
+
+Harness **dispatch** on Kimi = **one or more `Agent` tool calls** with correct **`subagent_type`** and role-bound prompts (C5b → **`_shared/host-role-binding-core.md`**). N-parallel / 1-Assignment-1-invoke / paste-only mechanics → **`parallel-dispatch.md`**.
+
+| Harness | Kimi |
+|---------|------|
+| `Execute as: <role-id>` | Role id in Assignment + **Act as** + skill load in **Agent** prompt (C5b) |
+| `subagent_type` for invoke | `coder` \| `explore` \| `plan` only (see mapping) |
+| Parallel batch **N** | **N `Agent`** calls in **one assistant message** when roles may differ; **`AgentSwarm`** only when same role/profile |
+
+### QC default
+
+- **`Execution mode: sdd`**: **N=3** `Agent` calls (`qc-specialist`, `qc-specialist-2`, `qc-specialist-3`) — each prompt **Act as** the respective QC role, all `subagent_type: "coder"` (N rules → `parallel-dispatch.md`).
+- **`inline`**: **N=1** per `parallel-dispatch.md`.
+
+Cannot emit required **N** → **`Blocked`**.
+
+### SDD implement (serial)
+
+- **`Execution mode: sdd`**: one implementer **`Agent`** per task id; task reviewer = new **`Agent`** with **Act as `code-reviewer`** (Kimi L2 review; not qc-specialist*), always via generic fallback `subagent_type: "coder"` per C5 — no sticky resume unless host adds it later. Serial rule → **`parallel-dispatch.md`** § SDD implement.
+- **Never** multiple implementer Agents in one message for the same plan.
+
+## Clarify
+
+- Prefer **`AskUserQuestion`** for 1–3 high-impact choices with known options.
+- Fallback: one concise Markdown question after codebase exploration cannot answer it.
+- `AskUserQuestion` for plan approval is wrong in Plan mode — use **`ExitPlanMode`** for plan sign-off.
+- “Question asked” ≠ clarify done; blocking ambiguity → **`Blocked`** or escalation.
+
+## Commands and skills paths
+
+| Surface | Path / invocation |
+|---------|-------------------|
+| Plugin skills | `/skill:<skill-name>` or auto-load from `skills/` via plugin |
+| Plugin commands | `/morning-star-harness:iteration-start` etc. |
+| Session entry | `sessionStart.skill: pm` → `mstar-harness-core` via pm **Read next** |
+
+## Files, shell, and approvals
+
+- Prefer **Glob** / **Grep** for search; **Write** / **Edit** for edits.
+- Respect Kimi approval prompts for destructive operations.
+- Do not edit `$KIMI_CODE_HOME` credentials, managed plugin copies, or user secrets without explicit consent.
+
+## Git and final evidence
+
+- Git work follows `mstar-branch-worktree` and Assignment **Working branch** / **Branch policy**.
+- Completion reports cite concrete commands, artifacts, and commit lines when required.
+
+## Gotchas
+
+- Plugin install copies source to managed dir — edit checkout + reinstall to pick up harness changes.
+- **`AgentSwarm`** shares one template — not for mixed-role QC tri-review; use **3× Agent** instead.
+- Session plan file and `TodoList` are not durable SSOT unless mirrored to `{HARNESS_DIR}`.
+- No custom Kimi agent profiles for Morning Star roles — role binding is **always** prompt + skill load (C5b).

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

@@ -0,0 +1,32 @@
+# omp Plan mode bridge
+
+Load with **`omp.md`** when omp Plan mode is active (`/plan`, plan-yolo / plan-model flows, or read-only-with-resolve plan UX). Shared contract → **`references/_shared/plan-mode-bridge-core.md`** (dual-write SSOT rule + priority, bootstrap init, Build resume contract, bootstrap todos, implement done-gate, Phase 1 gate, shared anti-patterns). This bridge covers omp plan-UX specifics only.
+
+## Dual-write contract
+
+omp session plans, composer todos, and plan-mode UI text are **session UX only**. Durable SSOT remains **`{HARNESS_DIR}`** (default `.mstar/`, legacy `.agents/`):
+
+| Artifact | SSOT |
+|----------|------|
+| Main plan | `{PLAN_DIR}/<plan-id>-<name>.md` |
+| Plan registry | `{HARNESS_DIR}/status.json` (v2 root `workflows[]`) + `{WORKFLOW_DIR}/<id>/snapshot.json` (`plans[]` rows) |
+| Iteration compass | `{ITERATION_DIR}/…` when in formal iteration |
+
+Bootstrap before treating a plan as ready for Execute (read `mstar-conventions` + `mstar-artifacts`; ensure `{HARNESS_DIR}` / `{PLAN_DIR}` exist with process-artifact gitignore entries; mirror the active omp plan into the SSOT main plan path; register the root `workflows[]` entry + snapshot plan row when required by Prepare gates) → core.
+
+**Never** use only the omp session plan / UI todo list as **Plan Path**.
+
+## `mstar-iteration` Phase 1 in Plan mode
+
+When formal iteration Phase 1 runs under omp Plan UX, the shared gate → core: single SSOT draft plan path (no silent second plan file); feedback-driven in-place edits; **do not** run Review & Edit chain, commit, or create integration branch until the user leaves Plan mode / approves implementation (Build-equivalent). Recommended branch policy still applies — no silent work on `main`/`master` (`mstar-iteration` §1.2).
+
+## Clarify vs plan approval
+
+- Use **`ask`** for high-impact product/tech choices while drafting.
+- Plan sign-off is the host Plan resolve / approval path, not a casual chat question.
+- After approval, resume as **`project-manager`**: reload `mstar-harness-core` + `omp.md`, then dispatch implementation through **`task`** (C5/C5b). Parent plan session must **not** implement product code unless the user explicitly overrides harness dispatch.
+
+## Gotchas
+
+- Plan-yolo / prewalk model switches are host UX — they do not waive Morning Star gates, Assignment, or evidence rules.
+- Isolated task worktrees from omp are orthogonal to Morning Star L1 lease/worktree fields; when L1 is active, still record harness **Worktree path** / leases.

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

@@ -0,0 +1,245 @@
+# omp host reference
+
+Load when **`mstar-host`** detection resolves **omp** (Oh My Pi / `omp` session, **`task`** tool with **`agent`** / **`tasks[]`** batch shape, **`ask`** tool, **`hub`** tool, or `/skill:pm` / `/iteration-*` from this plugin).
+
+Plan mode: read **`omp-plan-mode-bridge.md`** when `/plan`, plan-yolo, or plan-model / read-only-with-resolve plan UX is active.
+
+Parallel PM dispatch: read **`parallel-dispatch.md`** when dispatching **N ≥ 2** concurrent `task` invocations.
+
+## omp-only context
+
+- Plugin markers: **`.omp-plugin/plugin.json`** (Morning Star host marker) and **`.claude-plugin/plugin.json`** (Claude-compatible marketplace discovery). The **npm package** (`@mstar-harness/omp`) ships its own package-root `plugin.json` + `skills/` + `commands/` + `agents/` + `hooks/` + `tools/` mirrors; the **maintainer link path** is now `<repo>/packages/omp` (built) — hooks/tools moved into the package (2026-09-03), so linking the repo root provides skills/commands/agents only, with NO runtime gates.
+- Runtime skills: package `skills/` (or repo `skills/` on the link path) discovered after `omp plugin install` / `omp plugin link` (OMP extension-package sub-discovery) or Claude marketplace install.
+- Plugin commands: `commands/<name>.md` → slash **`/<name>`** (e.g. `/iteration-start`). omp uses the **filename** as the command name (no `morning-star-harness:` prefix).
+- Plugin agents: **`agents/*.md`** are discovered into the live **`task.agent`** list after install/link + reload. Morning Star **subagent** role ids (`product-manager`, `architect`, `fullstack-dev`, `qc-specialist`, …) are valid `agent` values **when listed** — see C5. `project-manager` is **`mode: primary`** (orchestration seat), not a typical `task` dispatch target.
+- **No Kimi-style `sessionStart.skill`** — enter PM manually via **`/skill:pm`** (or the `pm` skill), then **Read next** → `mstar-harness-core` → `project-manager.md`.
+- Install (user-scoped, recommended):
+  - `omp plugin install @mstar-harness/omp`
+  - or CLI: `npx @mstar-harness/cli init --target omp --scope global` (links `~/.mstar/harness`)
+- Project scope: `omp plugin install @mstar-harness/omp --scope project` or `npx @mstar-harness/cli init --target omp --scope project`.
+- Local maintainers: `omp plugin link /path/to/mstar-harness/packages/omp` (or the CLI-managed `~/.mstar/harness/packages/omp` checkout) — the linked package tree resolves the engine via the workspace member, so run `bun install && bun run engine:build && bun run --cwd packages/omp build` in the checkout first. Linking the repo root no longer provides the runtime gates (hooks/tools moved into the package); the npm install stays the primary path.
+- After install/link: `omp plugin list` should show package **`@mstar-harness/omp`** (npm) or **`morning-star`** (root `package.json` name, link path). Reload / new session to pick up skills, commands, and agents.
+
+## Skill loading
+
+1. On entry: invoke **`pm`** via `/skill:pm` → **Read next** loads `mstar-harness-core`, then `mstar-roles` → `project-manager.md` when PM is active.
+2. Read `mstar-host` and this omp reference.
+3. If Plan mode is active, read `omp-plan-mode-bridge.md`.
+4. Load `mstar-roles` and the active role reference.
+5. Load topic skills on demand per the role reference.
+
+Use skill names in prompts and references. Prefer `skill://<name>/…` / `/skill:<name>` over absolute local paths unless maintaining this repository. Full skill-root table (all hosts) → `mstar-host` § Resolve loaded skill root.
+
+## Internal URLs
+
+omp resolves **internal URL schemes** natively (see <https://omp.sh/#urls>), so skills and shared content stay addressable wherever omp installs the plugin — prefer URLs over absolute local paths:
+
+| Scheme | Use |
+|--------|-----|
+| `skill://<name>` | Load a skill's `SKILL.md` — e.g. `skill://mstar-harness-core`, `skill://mstar-host` |
+| `skill://<name>/<path>` | Read a file inside a skill — e.g. `skill://mstar-host/references/omp.md` |
+| `local://<name>.md` | Share context / assignments with subagents — prefer over pasting large payloads inline |
+| `artifact://<id>` / `agent://<id>` | Read a subagent's output artifact / a nested child's output |
+| `history://<id>` | Read-only transcript of a (sub)agent session |
+
+`/skill:<name>` (slash command to **invoke**) and `skill://<name>` (URL the model can **`Read`**) resolve to the same skill. Put URLs in `task` assignment bodies and skill **Read next** lists so a role subagent loads the right skill regardless of install path — this is what makes cross-host skill references portable on omp.
+
+## Tools map (default agent)
+
+| omp tool | Harness use |
+|----------|-------------|
+| **`task`** | Primary dispatch — fan out one or more subagents (`agent` = live-schema id; prefer Morning Star role id; batch via `tasks[]` + shared `context`) |
+| **`ask`** | Structured clarify (options + recommended); prefer over free-form when choices are known |
+| **`hub`** | Optional peer messaging / long-running process control among subagents — not a substitute for Assignment + `task` |
+| **bash** | Commands, git, tests — evidence per `mstar-coding-behavior` |
+| **read** / **write** / **edit** | File I/O (and host AST/edit variants when present) |
+| **grep** / **glob** | Search (prefer over shell find/grep) |
+| **web_search** / URL fetch tools | External docs / facts when present |
+
+OpenCode **`question`** / **`task`+`subagent`**, Cursor **Task**+`subagent_type`, and Kimi/ZCode **Agent** / **AskUserQuestion** are **not** omp tools — do not assume them.
+
+### `task` shape (operational SSOT)
+
+Prefer the live tool schema every session. Typical batch shape:
+
+```text
+task(
+  context: "<shared batch context>",
+  tasks: [
+    {
+      name: "CamelCaseId",
+      agent: "<Execute as role-id>",   # prefer live-schema role agent — see C5
+      task: "<full Assignment body including Act as + skill load>"
+    }
+  ]
+)
+```
+
+Single-task shorthand may exist depending on host version — always match the live schema. Parallel **N** Morning Star assignees ⇒ **one** `task` call with **N** `tasks[]` entries **or** **N** `task` calls in one assistant message when the host requires that shape. Count emitted dispatches = **N**.
+
+**Envelope-first**: write `agent` + `name` as the first fields of each `tasks[]` entry, before the long `task` body — the body crowds them out and `agent` gets silently dropped (omp defaults to generic `task`, no error). SSOT → `parallel-dispatch.md` § Mandatory order.
+
+## Role agents (C5 — hard constraint)
+
+**Live `task` tool schema is SSOT every session.** Exact `agent` names vary by omp version and which `agents/*.md` were discovered after plugin install/link. Read the tool's Available Agents list before dispatch — do not invent names; do not hard-code stale tables over the live list.
+
+### Selection order (required)
+
+1. **Role match first** — if Assignment `Execute as: <role-id>` appears in the live `task.agent` list, set **`agent: "<role-id>"`**. Examples commonly present after Morning Star plugin discovery: `product-manager`, `architect`, `frontend-dev`, `fullstack-dev`, `fullstack-dev-2`, `ops-engineer`, `prompt-engineer`, `qa-engineer`, `qc-specialist`, `qc-specialist-2`, `qc-specialist-3`, `writing-specialist`.
+2. **Generic built-in only as fallback** — when the role id is **absent** from the live schema, pick the closest host built-in and keep full C5b prompt binding:
+
+| Fallback `agent` | When |
+|------------------|------|
+| `scout` / `explore` | Read-only orientation / codebase survey / Prepare explore |
+| `reviewer` / `security-reviewer` | Optional QC assist **only if** the matching `qc-specialist*` agent is missing |
+| `designer` | UI-heavy work when `frontend-dev` is missing |
+| `librarian` | External library/API research assist |
+| `sonic` / `quick_task` | Mechanical / low-reasoning transcription only |
+| `task` (or omit if schema says omit = general worker) | Last resort general worker when no specialist fits |
+
+3. **Anti-pattern** — **`agent: "task"` (or omitting agent) while a matching role agent is listed** is incorrect dispatch. Prefer the specialist; generic `task` is not the Morning Star default when role agents are available.
+
+### Notes
+
+- `project-manager` is the **primary** orchestration agent (`agents/project-manager.md` `mode: primary`). Do not dispatch PM-to-PM via `task` unless the live schema explicitly lists it **and** the Assignment requires it.
+- Host generics (`scout`, `reviewer`, `designer`, …) remain useful for non-role orientation / assist — they do not replace a listed Morning Star role agent for role-owned deliverables.
+
+### Role binding in prompt (C5b — required)
+
+omp C5/C5b SSOT is **this file** — do **not** use `_shared/host-role-binding-core.md` (that file is Kimi/ZCode only). Even when `agent` already matches the role id, still bind Morning Star process in the Assignment / `task` body (agent shell ≠ full role prompt; skill load is not automatic).
+
+Required in every role dispatch:
+
+1. **`Execute as: <role-id>`** in Assignment (harness routing SSOT).
+2. **`Act as <role-id>`** (or equivalent) at the top of the `task` body.
+3. **Skill load list** — instruct the subagent to read `mstar-roles` → `references/<role-id>.md` (or shared reference + parameters) and topic skills per that reference.
+4. **`agent`** — live-schema role id per C5 above (not “always `task`”).
+
+Paste-only Assignment **without** a `task` invoke is **not** dispatch.
+
+Assignment / prompt template:
+
+```markdown
+## Assignment
+
+**Execute as**: fullstack-dev
+**Delegation**: forbidden
+**Working branch**: feat/example
+**Plan Path**: .mstar/plans/20260717-example.md
+
+**IDENTITY:** You ARE `fullstack-dev`. Act as `fullstack-dev` for this task.
+
+Load: `mstar-harness-core` → `mstar-host` → `omp.md` → `mstar-roles` → `references/fullstack-dev-shared.md` → topic skills per that reference.
+
+<task body>
+```
+
+omp invoke shapes, same turn:
+
+```text
+task(
+  context: "Morning Star dispatch for plan 20260717-example",
+  tasks: [{
+    name: "ImplementAuth",
+    agent: "fullstack-dev",   # live-schema role id matching Execute as
+    task: "<full Assignment body including Act as + skill load>"
+  }]
+)
+```
+
+Review & Edit / Prepare specialist chain (sequential, **N=1** each turn — re-set **`agent`** on **every** dispatch; at N=1 the count gate is trivial, so the **field** gate is the only protection):
+
+```text
+# pass 1 — product-manager
+task(
+  context: "Review & Edit — product scope",
+  tasks: [{ name: "ReviewEditProduct", agent: "product-manager",
+            task: "<Assignment: Execute as product-manager; Act as + skill load>" }]
+)
+# repeat for architect, writing-specialist, … — each a separate N=1 dispatch with agent re-set
+```
+
+For explore-only orientation (no Morning Star role deliverable):
+
+```text
+task(
+  tasks: [{
+    name: "ExploreAuth",
+    agent: "scout",   # or explore if that is what the live schema lists
+    task: "... Act as explore-only orientation; Execute as: n/a ..."
+  }]
+)
+```
+
+## PM dispatch (`task`)
+
+Harness **dispatch** on omp = **one or more `task` tool calls** with correct **`agent`** values and role-bound assignment text (C5 + C5b in this file). N-parallel / 1-Assignment-1-invoke / paste-only mechanics → **`parallel-dispatch.md`**.
+
+| Harness | omp |
+|---------|-----|
+| `Execute as: <role-id>` | **`agent: "<role-id>"`** when listed in live schema; else generic built-in + C5b |
+| Role identity / skills | Assignment **Act as** + skill load in **task** body (C5b) — always |
+| Parallel batch **N** | **N** `tasks[]` entries in **one** `task` call, or **N** `task` calls in **one** assistant message |
+
+### QC default
+
+- **`Execution mode: sdd`**: **N=3** task entries — prefer `agent: "qc-specialist"`, `"qc-specialist-2"`, `"qc-specialist-3"` when listed; each body still **Act as** the respective QC role + QC skill load. If a seat is missing from the live schema, fall back per C5 (generic + C5b) for that seat only. N rules → `parallel-dispatch.md`.
+- **`inline`**: **N=1** per `parallel-dispatch.md`.
+
+Cannot emit required **N** → **`Blocked`**.
+
+### SDD implement (serial)
+
+- **`Execution mode: sdd`**: one implementer `task` entry per task id with `agent` matching the implementer role when listed; task reviewer = new entry with `agent: "code-reviewer"` (omp L2 review; not qc-specialist*) or `agent: "reviewer"`/`"task"` as fallback + C5b — no sticky resume unless host resume/id is available and recorded. Serial rule → **`parallel-dispatch.md`** § SDD implement.
+- **Never** multiple implementer entries in one message for the same plan.
+
+## Clarify
+
+- Prefer **`ask`** for 1–3 high-impact choices with known options (`recommended` when there is a default).
+- Fallback: one concise Markdown question after codebase exploration cannot answer it.
+- Plan approval in Plan mode follows **`omp-plan-mode-bridge.md`** — do not treat a casual `ask` as plan lock.
+- “Question asked” ≠ clarify done; blocking ambiguity → **`Blocked`** or escalation.
+
+## Commands and skills paths
+
+| Surface | Path / invocation |
+|---------|-------------------|
+| Plugin skills | `/skill:<skill-name>` or auto-load from `skills/` via plugin discovery |
+| Plugin commands | `/iteration-start`, `/iteration-drive`, `/iteration-loop` (filename-based) |
+| Session entry | `/skill:pm` → `mstar-harness-core` via pm **Read next** |
+
+## In-process engine binding (omp ≥ 17.2.11)
+
+- **Surfaces** (npm package root = plugin root; sources live in `packages/omp/src/`): `hooks/pre/mstar-gates.js` — one `tool_call` pre-hook that returns `{ block: true, reason }` (structured refusal the model sees as the tool error) or `undefined` (pass); `tools/mstar_{status_validate,dispatch_validate,lease_verify,path_resolve,iteration_gate,worktree_check}.js` — six model-callable validator tools (engine validators only, Zod params via `pi.zod`). omp discovers these by convention from the installed package root (`<pkg>/hooks/pre/` any file, `<pkg>/tools/` direct `*.js` files — the sub-directory scan only accepts `tools/<name>/index.ts`), not from `dist/`.
+|- **Enforcement semantics**: block ONLY under `Enforcement: hard`. Both gates read the repo `.mstarc` `[config] enforcement`, else the harness compass frontmatter (`enforcement: hard`, active/locked iterations only); the dispatch gate ALSO honors each Assignment's own header flag (`assignmentHeaderRegion` — a body example never hardens). A hard repo setting therefore hardens flag-less dispatches (Gate 1 / dsh `resolveDispatchHard` parity). Soft-mode dispatch violations are warn-logged through the extension logger (never blocked); soft status-write violations stay a silent pass. Rollback = unset the flag (or `.mstarc` `soft`). Never global.
+- **Anti-recursion scope (issue #156)**: the engine's `antiRecursionPrecheck` is **caller-scoped** — it compares the DISPATCHING agent's own role against the new Assignment's `Execute as`. omp's `tool_call` event carries no caller identity and the task entry `agent` is the spawn TARGET, which equals `Execute as` on every compliant dispatch (C5 above) — so Gate 2 does NOT run the precheck on omp (the pre-#156 wiring hard-blocked every compliant hard-mode dispatch on `self-type`, or on `empty-binding` when `agent` was omitted). The NEVER red line stays prompt-level on this host (`mstar-dispatch-gates`); dsh enforces it in-engine via Config `dispatchBinding`.
+- **Engine dependency**: the npm package **bundles the engine inline** into every hook/tool bundle at build time — zero runtime package resolution, so module link can never fail on a missing package (the 2026-09-03 hotfix for the bare-import load failure). The maintainer `omp plugin link` path (now `<repo>/packages/omp`) still resolves the engine via the workspace member — run `bun install && bun run engine:build && bun run --cwd packages/omp build` in the checkout first (the member's `dist/` and the package's generated mirrors are gitignored).
+- **Graceful degradation (explicit)**: module load failure → `mstar_*` tools skipped, hook absent (no blocking), `commands/*.md` shell-out fallback intact. Caveat: a partial failure is SILENT — no in-band signal that gates are off; verify with `omp -p '/extensions'`.
+|- **`MSTAR_HARNESS_DIR` override / `.mstarc`**: the hook and tools discover `{HARNESS_DIR}` via `resolveHarnessDir` — a repo `.mstarc` `[config] harness_dir` (gitignored local config) first, then the probe `.mstar/` → `.agents/` → `.plans/`/`plans/`. Repos using a non-standard harness root can declare it in `.mstarc` or MUST export `MSTAR_HARNESS_DIR` (absolute path) in the omp session env — without either the status gate does not cover those roots and tools like `mstar_path_resolve` / `mstar_lease_verify` error out (parity with the opencode binding).
+- **Edit-path limitation**: the status gate validates the on-disk file for `edit` events (pre-edit state) — a corrupting edit is caught by the next write or `mstar_status_validate` (known v1 limitation, parity with opencode).
+- **Engine version compatibility**: the hook and tools degrade gracefully until the engine release exporting both `composeDispatchGate` and `parseCompassFrontmatter` (published 2.0.2 predates both). Missing exports never fail module load: the hook's dispatch gate needs `composeDispatchGate` — on older engines Gate 2 (task dispatch) is skipped with a one-time warning while Gate 1 (status) stays active — and `mstar_dispatch_validate` / `mstar_iteration_gate` report an explicit upgrade error instead of loading (no silent absence; CLI fallbacks: `mstar dispatch validate`, `mstar iteration gate`).
+- **Reload**: edits are picked up by a new session (`?mtime` cache-buster); in-session `/reload-plugins` (omp ≥ 17.2.11) applies them without a new session.
+
+## Files, shell, and approvals
+
+- Prefer host search/edit tools over shell find/sed when available.
+- Respect omp approval prompts (`approval-mode`, write/yolo) for destructive operations.
+- Do not edit `~/.omp/` credentials, plugin lockfiles, or user secrets without explicit consent.
+
+## Git and final evidence
+
+- Git work follows `mstar-branch-worktree` and Assignment **Working branch** / **Branch policy**.
+- omp may offer task isolation / worktrees (`task.isolation`, `~/.omp/wt`) — that is **host-level** task isolation **outside** the Morning Star convention; Morning Star **`Worktree path`** stays `<repoRoot>/.worktrees/` (record it + leases when L1 gates apply).
+- Completion reports cite concrete commands, artifacts, and commit lines when required.
+
+## Gotchas
+
+- Installed npm plugin package name is **`@mstar-harness/omp`** (git/link path: root **`morning-star`**); Morning Star display name remains **morning-star-harness**.
+- Marketplace (Claude) installs and `omp plugin install` are different discovery providers — prefer one install path per machine to avoid duplicate skill listings.
+- Session plan UI / todos are not durable SSOT unless mirrored to `{HARNESS_DIR}`.
+- After install/link, **reload / new session** so `agents/*.md` appear in the live `task.agent` list — stale sessions may only show host generics and wrongly push you to `agent: "task"`.
+- Role agent shell ≠ full role prompt: **C5b skill load remains required** even when `agent` already equals the role id.
+- omp has no `sessionStart.skill`; new sessions do **not** auto-load PM — invoke `/skill:pm` manually.
+- Do not confuse omp **`task.agent`** with OpenCode **`subagent`** or Cursor **`subagent_type`**.
+- Do not treat Kimi/ZCode “built-ins only → always `coder`/`task`” habits as omp defaults when Morning Star role agents are listed.
+- **Sequential N=1 Review-&-Edit turns are where `agent` gets dropped**: the “all N in one message” pressure is absent and the count gate passes trivially — re-verify **`agent: "<Execute as>"`** on every single dispatch; `tasks:[{task:"…"}]` with no `agent` is a silent generic fallback, not a valid role invoke.

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

@@ -0,0 +1,76 @@
+# OpenCode host reference
+
+Load when **`mstar-host`** detection resolves **opencode** (`question` tool, **task tool** with **subagent** parameter, or OpenCode session).
+
+Parallel PM dispatch: **`parallel-dispatch.md`** (read in dispatch rounds).
+
+## Role loading
+
+- Skill root: load by skill **name** from `@mstar-harness/opencode` (`harness-skills/<name>/` inside the package). Never `process.cwd()/skills/` — see `mstar-host` § Resolve loaded skill root.
+- **PM entry**: **`/pm`** or **`pm` skill** → `project-manager` for general orchestration; host **`commands/`** for formal iteration Phase 1–5 (semantics → **`mstar-iteration`**).
+- **Role shell**: `agents/<id>.md` referenced by `opencode.json` `agent.<id>` (frontmatter + role binding only).
+- **Role body**: `mstar-roles` `references/<id>.md` (or shared references + parameters).
+- Implementation evidence and RCA behavior: `mstar-coding-behavior`.
+
+## OpenCode-specific capabilities
+
+- **Structured clarify**: prefer **`question`** tool (title, prompt, options, optional custom text). Requires `permission.question` in config (user-maintained; do not edit global config without consent).
+- **Built-in subagents** (via **task tool**): **explore** (read-only), **general**; subject to `mstar-harness-core` explore boundaries.
+- **Named role subagents**: Morning Star roles configured under `opencode.json` `agent.<id>` — PM must **call the task tool** with **`subagent`** set to that agent id. Assignment Markdown alone does not open subagent sessions.
+- **Per-role models**: configurable per subagent in `opencode.json`.
+
+## PM dispatch (task tool + subagent)
+
+Harness **dispatch** on OpenCode = **one or more `task` tool calls**, each with **`subagent: <agent-id>`** (read the tool schema every session). N-parallel / 1-Assignment-1-invoke / paste-only mechanics → **`parallel-dispatch.md`**.
+
+| Harness | OpenCode |
+|---------|----------|
+| `Execute as: <role-id>` | **`subagent`** on **task tool** = same agent id |
+| Parallel batch **N** | **N task tool** calls in **one assistant message** when the host allows (`parallel-dispatch.md`) |
+
+PM workflow: finalize Assignment → **call task tool** with **subagent** + generated prompt → wait for subagent Completion Report → update plan / status.
+
+**SDD sticky implementer:** if the task tool exposes **resume** / agent id, follow **`mstar-sdd/references/sticky-implementer-session.md`** and the active host reference. If resume is **not** available, use **micro-batch** (2–3 tasks, one invoke) or **`SDD implementer session: fresh`** per task — do not assume sticky without host support.
+
+**SDD task reviewer:** each task review is a **new** task tool call with `subagent: "code-reviewer"` (OpenCode L2 review; not qc-specialist*) when that agent is configured, else generic built-in fallback + C5b — no sticky resume for reviewers (fresh per task).
+
+## Role-mention hygiene (OpenCode)
+
+OpenCode may **auto-append** system lines when prompt text stacks multiple agent-id **prefix mentions**. Typical boilerplate (host-generated — **not** harness Assignment):
+
+```text
+Use the above message and context to generate a prompt and call the task tool with subagent: <agent-id>
+```
+
+(Same sentence repeated with different **subagent** values — mechanical template, not user prose.)
+
+| Do | Don't |
+|----|-------|
+| Use **plain role ids** (`product-manager`) in skill / command / Assignment prose | Stack prefix-style role mentions that trigger multi-**subagent** boilerplate |
+| Sequential chains: **one task tool / one subagent per dispatch turn** | Treat auto-appended **task tool + subagent** lines as authorized parallel batch |
+| Real dispatch: PM **calls task tool** with explicit Assignment + **`Delegation`** rules | Confuse boilerplate with **`Delegation: allowed`** |
+
+When documenting this in harness text, avoid embedding prefix-style role examples in the warning — that can re-trigger the host.
+
+## Prepare phase — serial roles still require invoke
+
+`mstar-roles` **project-manager** may route `explore → product-manager → architect` **sequentially**. Each handoff still needs a real **task tool** call with the matching **subagent** and Assignment (**`N = 1`** per dispatch turn). Writing PRD / architecture only in the PM chat is **not** a substitute.
+
+## Gotchas
+
+- `question` availability is config-dependent; if unavailable, structured Markdown clarify.
+- **explore** subagent (via task tool) is orientation only — not role-owned implementation or review deliverables.
+- More MCPs do not replace phase gates or evidence rules.
+
+## Session noise control
+
+- Large unrelated platform injections (e.g. long ecosystem prompts): prefer on-demand / `alwaysApply: false` when not stack-relevant.
+- One default channel per capability class (search, docs).
+
+## Standalone harness note
+
+Bundled **`mstar-*` skills** are self-contained in this repository. User-installed host MCPs, external skills, or CLIs are **outside harness SSOT** — do not add them to `mstar-*` load order or treat them as required for gates.
+
+## Maintenance boundary
+
+Runtime only — do not modify `opencode.json`, `secrets.env`, or `.secrets/*` without explicit user consent.

package/harness-skills/mstar-host/references/parallel-dispatch.md

@@ -0,0 +1,68 @@
+# Parallel dispatch (invoke-capable hosts)
+
+Shared PM dispatch contract for **any** host that uses subagent / Task / Agent invoke (OpenCode task tool, Cursor Task, Kimi **Agent** / **AgentSwarm**, omp **`task`** with **`agent`** / **`tasks[]`**, Codex only when a callable multi-agent / Task tool is actually available). Process SSOT also in `mstar-dispatch-gates`.
+
+If the active host has no callable invoke tool, this reference does not create delegation capability — mark dispatch **`Blocked`** and report to the user. Do not substitute PM-thread or single-session role execution unless the user explicitly overrides harness dispatch for this turn.
+
+## Paste-only failure
+
+Printing `## Assignment` in the main thread **without** matching host invocations is **not** delegation; downstream work **does not start**. Parallel dispatch makes this worse (N Assignments printed, zero invokes).
+
+## Prerequisite vs dispatch turn
+
+- **Prerequisite turn** (optional): `bash` / `read` / `glob` / `grep` to collect facts (`merge-base`, `Review range`, `git rev-parse`, paths). **Do not** emit **any** batch dispatch in this message unless `N = 1` and that single call *is* the dispatch.
+- **Dispatch turn** (when `N ≥ 2`): the **first** message that emits **any** dispatch for the batch must contain **all `N`** invocations. If not ready for all `N`, emit **zero** dispatches — finish prep, then one message with **`N`** calls.
+
+## Mandatory order (dispatch turn)
+
+1. Finalize all `N` Assignment payloads (after any prerequisite turn). **Build each invoke entry envelope-first**: set the role-binding field (omp `agent` / Cursor `subagent_type` / OpenCode `subagent` / Kimi·ZCode `subagent_type`) + `name` *before* writing the long Assignment body.
+2. Count distinct `Execute as` sessions (`N`).
+3. Issue **`N` host invocations first** — OpenCode: **N `task` tool** calls with **subagent**; Cursor: **N `Task`** with `subagent_type` (JSON field shape → `cursor.md` § Task invoke schema); Kimi: **N `Agent`** calls (each prompt carries **Act as** + skill load; `subagent_type` ∈ {`coder`,`explore`,`plan`} only — see `kimi.md` C5/C5b); omp: **one `task` call with N `tasks[]`** (or N `task` calls) with `agent` = live-schema role id matching `Execute as` when listed (else generic built-in) + **Act as** / skill load (see `omp.md` C5/C5b); each with one Assignment body. For parallel work, **all `N` tool calls in one assistant message** when the host allows.
+4. Optionally post a short **Status Update** after invocations (audit trail only — does not replace step 3).
+
+## Hard rules
+
+- **Emit zero until batch-ready**: if `N ≥ 2` and only one invoke is possible now, **do not** send that one; complete payloads, then **`N` in one message**.
+- Do not end the dispatch turn until **`N` invocations emitted**, or mark `Blocked` / `dispatch incomplete`.
+- Dual-track implement: **`N = 2` ⇒ two invocations in one message** when parallel is required.
+- Status Update on dispatch turns: **`Subagent invokes issued: N`** (must match Assignment count). If Assignments were written but `N = 0` → **`dispatch failed — paste-only`**; fix next message.
+- **Per-item field completeness (same severity as paste-only)**: every invocation must carry the role-binding field set to **`Execute as`** — omp **`agent`** / Cursor **`subagent_type`** / OpenCode **`subagent`** / Kimi·ZCode **`subagent_type`**. A missing field (e.g. omp omitting `agent` ⇒ silent generic `task` fallback) = **dispatch incomplete** even though count = N passes. Sequential **N=1** Review-&-Edit turns are not exempt — re-set the field on **every** dispatch.
+
+## QC default (initial wave)
+
+- **`Execution mode: sdd`**: **N=3** tri-review + branch review-package path → `{SDD_DIR}/review/qc1.md`…`qc3.md` + consolidated.
+- **`inline` / override**: **N=1** → `{SDD_DIR}/review/qc.md`.
+
+## QC iteration / SDD (same rule)
+
+Formal iteration Phase 2 uses the same SDD + tri rule — not a separate carve-out.
+
+## QC full tri-review（非 SDD 但显式 tri）
+
+当 plan 为 **`Execution mode: inline`** 或单轨，但 Assignment 仍写 **`QC mode: full tri-review`** 时：
+
+- Launch `qc-specialist`, `qc-specialist-2`, `qc-specialist-3` in **one** dispatch turn (**N=3**).
+- Post-dispatch: verify three distinct agent IDs; on mismatch → invalid dispatch.
+
+（**SDD 默认**已在上一节；本节仅覆盖显式 tri 的非 SDD 场景。）
+
+## SDD implement (serial — not parallel)
+
+- **`Execution mode: sdd`**: implementer and task reviewer dispatches are **one at a time** per task.
+- **Never** multiple implementer Tasks in one message for the same plan.
+- See **`mstar-sdd`**.
+
+## QC targeted re-review (after fixes)
+
+- Assignment: **`QC re-review: targeted — reviewers: <role-ids>`** → **N** = listed seats only (1–3), **one** dispatch turn with **N** invocations.
+- Do **not** default to three invocations after a routine fix round.
+- Post-dispatch: verify only **dispatched** seats returned; PM updates same bundle `qc-consolidated.md` and durable plan summary (see `mstar-artifacts/references/plan-files-and-reports.md`).
+
+## Self-check before send
+
+1. Required assignments this turn? (`N`)
+2. Prerequisite-only message? → **zero** batch dispatches unless `N = 1`.
+3. Dispatch message contains **exactly `N`** invocation calls?
+4. **Each** invocation carries its role-binding field set to **`Execute as`** (omp `agent` / Cursor `subagent_type` / OpenCode `subagent` / Kimi·ZCode `subagent_type`)? A bare `task`/prompt item with no role field = **incomplete**, even at **N=1**.
+5. QC initial: **`Execution mode: sdd`** → **N=3**? **`inline`** → **N=1**? Targeted re-review → **N** = Assignment reviewer count?
+6. SDD implement → **serial** (never batch implementers); sticky = **resume** same implementer, not parallel

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

@@ -0,0 +1,36 @@
+# ZCode Plan Mode × Harness Dual-Write Bridge
+
+> **Load order**: Read **`mstar-harness-core`** first, then **`mstar-host`** and **`references/zcode.md`**, then **`references/_shared/plan-mode-bridge-core.md`** (shared contract) + this bridge. When Plan mode is active, also read **`mstar-conventions`** and **`mstar-artifacts`**. Path symbols `{HARNESS_DIR}`, `{PLAN_DIR}`, `{SPECS_DIR}` are defined in `mstar-conventions`. On conflict, **`mstar-harness-core`** wins.
+
+**Shared contract** (dual-write SSOT rule + priority, bootstrap init, Build resume contract, bootstrap todos, implement done-gate, Phase 1 gate, shared anti-patterns) → **`references/_shared/plan-mode-bridge-core.md`**. This bridge covers ZCode plan-UX specifics only.
+
+ZCode **Plan mode** (`EnterPlanMode` / `ExitPlanMode`) uses read-only exploration for design and a plan approval gate before implementation; the session todo list is a **session UX mirror** — **NEVER** cite only a session todo list path in Assignment **Plan Path**, **Context Loaded**, or Completion Report when `{PLAN_DIR}/<plan-id>-<name>.md` should exist.
+
+## When this applies
+
+- ZCode **Plan mode** is active (`EnterPlanMode` succeeded).
+- Morning Star plugin is installed (`.zcode-plugin/plugin.json` skills loaded) or **`/morning-star-harness:pm`** / **`pm` skill** is in use.
+
+## Plan mode workflow (dual-write)
+
+| Step | ZCode session | Harness SSOT |
+|------|---------------|--------------|
+| Enter | `EnterPlanMode` — explore read-only | Ensure `{HARNESS_DIR}` exists; register the root `workflows[]` entry + snapshot plan row when known |
+| Design | Draft plan content; surface via `ExitPlanMode` plan text | Mirror main plan to `{PLAN_DIR}/<plan-id>-<name>.md` with task checkboxes |
+| Clarify | `AskUserQuestion` for blocking ambiguity only | Record decisions in plan / spec when durable |
+| Exit | `ExitPlanMode` — user approves plan to implement | SSOT plan locked; snapshot plan row updated |
+| Implement | Agent mode resumes | Per-task commits, Working branch, dispatch per `mstar-dispatch-gates` |
+
+`TodoWrite` and ZCode UI todos are **session progress only** — sync meaningful state to SSOT plan checkboxes and the workflow snapshot (`{WORKFLOW_DIR}/<id>/snapshot.json` → `plans[]`) when coordination requires it.
+
+## ExitPlanMode gate
+
+Host plan approval (`ExitPlanMode`) is **not** Morning Star **Done** (gate → core). Implementation still follows phase gates, per-task commits, QC, and QA per the SSOT plan.
+
+## `mstar-iteration` Phase 1
+
+When iteration Phase 1 runs in Plan mode, the shared gate (single plan session, feedback-driven in-place edits, no Review & Edit / commit / integration branch until approval) → core. After approval: reload `mstar-harness-core` + **`zcode.md`**; resume as `project-manager` orchestration.
+
+## Enforcement
+
+Conflict with harness invariants → **`mstar-harness-core`** wins. Full Cursor CreatePlan bridge detail lives in `cursor-plan-mode-bridge.md` when hosts differ; ZCode uses this lighter Enter/Exit bridge only.