@mstar-harness/omp 3.6.0-alpha.4

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

@@ -0,0 +1,196 @@
+---
+name: mstar-harness-core
+description: Morning Star (启明星) harness **强制全局入口** —— 信息源优先级、最小交付循环、状态机与 Done 权限、Task category 路由（含 quick 禁豁免）、@explore 边界、长任务纪律、核心研发守则、护栏不变量、反模式索引、Morning Star Skill 索引与宿主入口。**任何**非平凡任务开始前必须先 Read 本 skill；再按角色与任务 **按需** Read 其它 `mstar-*` 专题（勿默认通读全部）。`@project-manager` 开轮必读 + `mstar-dispatch-gates` / `mstar-phase-gates` / `mstar-conventions` 等；实现/审查/QA 必读本 skill + `mstar-coding-behavior` 及角色清单（见 `mstar-roles`）。Prepare/派发/Git/residual/QC 细则在专题 skill，不在此重复。
+---
+
+# Morning Star Harness Core（启明星核心）
+
+本 skill 是 harness 的**唯一全局入口与裁决层**。专题 skill 展开细节；**冲突时以本 skill 的状态机、Done 权限与索引为准**。
+
+## 与其它 `mstar-*` skill 的加载契约
+
+- 凡 **`mstar-*`**（`name` ≠ `mstar-harness-core`）假定读者**已 Read 本 skill**。
+- **仅读专题、未读核心** → 未完成 harness 加载。
+- 各专题 SKILL.md 含 **Load order**；按 **`mstar-harness-core`** 专题 skill 索引 + 角色 load contract 按需加载，**禁止**为「保险」通读全部专题。
+- **加载条件（`mstar-engine-legacy`）**：`mstar-engine-legacy` 是**条件契约档案**（engine-absent fallback）。**engine 约束激活（或宿主含 engine 能力）时不加载**——engine-present 宿主以运行时 skills 的 engine-check 指针 + engine 校验为权威；仅 engine-absent 宿主（无 `mstar` CLI / engine import）为找回被 engine 校验接管的 contract 全文而读取（触发契约见其 description）。
+
+## Standalone harness（`mstar-*` 自洽）
+
+- **`mstar-*` skill 体系**在本仓库内自洽运行：正文与 load order **不得**依赖仓库外的 skills、CLI、或 MCP 服务。
+- **Commands**（如 `/iteration-start`）可引用本仓库 bundled、**非 `mstar-*`** 的辅助资产（例如 `skills/grill-me/`）；该引用**仅**存在于 command 层，**不**进入 `mstar-*` 专题索引或 load matrix。
+- 框架/SDK/API 问题：先 Read/Grep 项目内文档与源码；不将第三方文档工具写入 `mstar-*` 必读路径。
+
+## 信息源优先级
+
+1. 当轮用户显式指令  
+2. 项目 `AGENTS.md` / `CLAUDE.md`  
+3. `{KNOWLEDGE_DIR}/README.md` 索引（**若该文件存在**；发现 Active 行并仅跟随与当轮相关的文档）  
+4. `mstar-*` skills（本 skill + 专题）  
+5. `mstar-roles` 角色正文  
+
+冲突且用户未覆盖 → **暂停升级人工**。Knowledge **永不**高于用户 / `AGENTS.md`。
+
+## 最小交付循环
+
+**per-plan**：`specify → clarify → plan` → `plan(locked) → tasks → implement`（多 task 默认 SDD）→ plan QC tri + **QA gate**（`mandatory` 派 QA 或 `pm-acceptance`）→ Done（`inline` 单席例外）。阶段细则 → **`mstar-phase-gates`**；QA 分级 → **`mstar-roles/references/project-manager/qa-trigger-matrix.md`**。
+
+**迭代级**：`iteration-start → [per-plan cycle × N] → iteration-close → PR delivery → PR merge-ready loop`。细则 → **`mstar-iteration`**。
+
+## 加载约定（强制）
+
+| 角色 | 始终 | 按任务追加（典型） |
+|------|------|-------------------|
+| **全部** | 本 skill | — |
+| **`@project-manager`** | 本 skill | `mstar-dispatch-gates`、`mstar-phase-gates`、`mstar-conventions`、`mstar-roles`；implement 波次 `mstar-sdd`；派 QC 前 `mstar-review-qc`；并行/审查 `mstar-branch-worktree`；plan/status/review bundle `mstar-artifacts`；UI 类 plan Prepare 阶段 `mstar-design-md`（DESIGN.md 门禁）；新建/大改 skill 时 `mstar-skill-authoring`；迭代管理 `mstar-iteration`（Phase 1–5）；战略性工作 `mstar-strategy`；`audit` 类请求 `mstar-audit`（执行归 `@code-reviewer`）。**不**读 `mstar-coding-behavior` |
+| **实现/审查/运维** | 本 skill + `mstar-coding-behavior` + 角色 ref | 有 git 写：`mstar-branch-worktree`；有 plan 路径：`mstar-conventions`；**PM** 派 QC 前：`mstar-review-qc`；**`qc-specialist*`**：`mstar-roles` → `references/qc-specialist/`；`qa-engineer`：`references/qa-engineer/`；改 status/residual：`mstar-artifacts`；UI：`mstar-design-md`；知识库：`mstar-compound`（PM） |
+| **leaf 承接方** | 上栏 + **`mstar-dispatch-gates`**（反递归节） | — |
+
+Routing eval（Cursor 插件内回归用，**非**运行时必读）→ `.cursor/skills/mstar-routing-eval/`。
+
+## 状态机
+
+`Todo` → `InProgress` → `InReview` → `Done` | `Blocked`
+
+- **`Done`**：仅 `@project-manager` 或 `@qa-engineer`。
+- 实现类可设 **`InReview`**，不可设 **`Done`**。
+
+`status.json`（v2 根）/ workflow snapshot / project register 字段与 residual → **`mstar-artifacts`**。
+
+## Task category（路由摘要）
+
+PM 在 Assignment 写 **`Task category`**（主类 + 可选 `secondary`）：
+
+| Category | 倾向角色 |
+|----------|----------|
+| `visual` | `@frontend-dev`（复杂 IA 可前置 `@product-manager`） |
+| `deep` | `@explore` → dev / `@architect` |
+| `quick` | `@general` 或单 dev — **不豁免 Prepare** |
+| `logic` | `@architect` + dev |
+| `ops` | `@ops-engineer` |
+| `docs` | `@product-manager` / `@architect` / `@writing-specialist` |
+| `audit` | `@code-reviewer`（mstar-audit 承载；大型仓库经 Assignment `Delegation: allowed (scout/explore only, read-only)` 扇出只读 scout；read-only advisory；不进入状态机） |
+
+**硬规则**：`quick` **从不**跳过 `specify → clarify → plan`；禁止把新 CLI/API/多模块/新测例标为 `quick`。已启用 `{HARNESS_DIR}` 时，首次 implement 前须有主 plan 路径 + `status.json` 登记（见 **`mstar-conventions`**）。
+
+## `@explore` 边界
+
+- 已分派角色的 Assignment：**禁止**用 `@explore` 代替实现/测试/审查/文档交付。
+- 允许短窄只读辅助；`glob`/`grep`/`read` 够用时不必 `@explore`。
+- PM 分派前摸底：**推荐**；分派后承接方**勿**转包。
+
+## 长任务纪律
+
+可追踪清单（plan `tasks` 或 Todo）；偏离时 PM 拉回；完成前须可核对证据（实现侧自检见 **`mstar-coding-behavior`**；门禁证据见 **`mstar-phase-gates`** / **`mstar-review-qc`**）。
+
+**Durable Roadmap Gate**：凡声明“分批 / 后续 / next plan / later / temporary workaround”的非热修任务，必须在 `{PLAN_DIR}` 主 plan、CreatePlan mirror、`status.json`/residual、或 PM Task Board 中写清后续路线（批次、依赖、owner/触发条件、完成定义）。只在对话或 Completion Report 里说“以后做”不算可追踪，不能进入 implement GO 或 Done。
+
+## 专题 skill 索引
+
+| Skill | 职责 |
+|-------|------|
+| `mstar-harness-core` | 本文件：入口、状态机、Task category、explore、索引、护栏 |
+| `mstar-phase-gates` | per-plan 双阶段门禁：Prepare/Execute、意图门禁、hotfix、可验证编辑 |
+| `mstar-iteration` | 迭代管理：Phase 1–5（start / Autonomous Execute / iteration-close / PR delivery / PR merge-ready loop） |
+| `mstar-dispatch-gates` | 派发、Delegation、反递归、SDD 串行、SDD 路径 plan QC 强制 tri |
+| `mstar-engine-legacy` | 条件契约档案（engine-absent fallback）：status v1→v2 字段历史、lease 协议全文、各宿主 N=3/N=1 重述、反递归全清单、Engine-check 样板；engine 激活时不加载 |
+| `mstar-sdd` | Subagent-driven development：file handoff、per-task review、ledger |
+| `mstar-branch-worktree` | 功能分支、worktree、QC/QA 检出对齐 |
+| `mstar-conventions` | `{HARNESS_DIR}` 发现、初始化、Spec 分支模型摘要、产物路径 SSOT |
+| `mstar-artifacts` | 主 plan、review bundle / durable summaries、`status.json`（v2 根）+ workflow snapshots + project register、residual、knowledge |
+| `mstar-project-governance` | 项目治理层：`projects/<id>/roadmap.md` 编写约定 + `residuals.json` register 生命周期（open → verified close in place）、`_default` 回退、provenance；schema 与 engine `project.ts` 逐字一致 |
+| `mstar-design-md` | DESIGN.md 设计系统规范 —— 创建/审计/维护 design tokens，三级检查清单，light/dark 双主题 |
+| `mstar-review-qc` | PM：QC tri 编排、residual 留档、四层边界；leaf 执行 → `mstar-roles/references/qc-specialist/` |
+| `mstar-coding-behavior` | Think / Simplicity / Surgical / Debugging / Review Feedback / Goal-Driven / Communication |
+| `mstar-compound` | 知识结晶 —— 已解决问题→结构化知识文档，双轨（Bug/Knowledge），「是否值得结晶」自检清单，重叠检测，可发现性检查，CONCEPTS.md 协同 |
+| `mstar-compound-refresh` | 知识维护 —— 审查/更新/合并/删除 `{KNOWLEDGE_DIR}` 文档；**项目知识 bootstrap**（无/残旧 STRATEGY.md、CONCEPTS.md、`{KNOWLEDGE_DIR}`）→ `references/project-knowledge-bootstrap.md` |
+| `mstar-strategy` | `STRATEGY.md` 全局战略方向 —— 产品愿景、技术方向、决策原则 |
+| `mstar-skill-authoring` | 通用 skill 撰写门控（SkillsBench 六原则）：trigger 契约、紧凑 5 问 body、渐进披露、paired 证据 |
+| `mstar-audit` | Variant carrier：common core（hard rules、recon、vet、variant dispatch）+ SKILL.md `## Plan output (all variants)`（Status block、plan files、handoff）+ `references/codebase-audit.md`（full-audit 变体：9 类别 fan-out、effort、scope variants、Phase 4 excerpt/reconcile、audit index 模板）+ `references/security-review.md`（security 深查：exploitability 门槛、FP 纪律、LLM/供应链面）+ `references/pr-review.md`（`pr` 变体）；`audit-playbook` + `finding-format` + `plan-quality-bar` |
+| `mstar-roles` | 角色正文 hub |
+| `mstar-host` | 宿主适配（自动识别；`references/opencode.md` / `cursor.md` / `codex.md` / `kimi.md` / `parallel-dispatch.md`） |
+
+## 宿主 `mstar-host`
+
+Read **`mstar-host`** after this skill; detect host per its table, then Read the matching reference.
+
+| 宿主 | 要点 |
+|------|------|
+| OpenCode | `question`、**task tool**（**subagent** 参数）→ `references/opencode.md` |
+| Cursor | Task 并行 QC；Plan 双写 → `references/cursor.md` · `cursor-plan-mode-bridge.md` |
+| Codex | plugin skills、sandbox/apply_patch/tool discovery；无 invoke 工具时不声称 subagent dispatch → `references/codex.md` |
+| Kimi | `Agent`/`AgentSwarm`（仅 `coder`/`explore`/`plan`）；角色绑定在 prompt（C5b）；Plan 双写 → `references/kimi.md` · `kimi-plan-mode-bridge.md` |
+| 其它 | 同 `mstar-host` skill；按工具信号选 reference |
+
+## 核心研发守则
+
+全局工程不变量，适用于所有角色；实现级操作细节（The Ladder、surgical、debugging 等）→ **`mstar-coding-behavior`**。
+
+- Do not preserve backward compatibility. Remove obsolete paths instead of adding compatibility layers, fallbacks, or migrations.
+- Choose the simplest implementation that fully meets the current requirements. Avoid speculative abstractions, configuration, and indirection.
+- Grow the system in layers. Start from the smallest version that works end to end, and add each new capability on top of a product that already works. Never trade a working product for unfinished complexity.
+- Keep components modular and concerns clearly separated.
+- Prefer established, well-maintained libraries when they reduce overall complexity or improve reliability. Do not reimplement common functionality without a clear reason.
+- Lean on the dependencies already in the project before writing your own implementation or adding packages. Do not assume a library lacks a capability without checking its documentation and types.
+- Make architectural decisions for the long term. Do not accept a stopgap that only works for now and is meant to be replaced later.
+
+## 护栏（不变量）
+
+- 未经用户同意不改宿主配置文件与用户凭据。
+- 行为变更须有验证证据。
+- 业务仓默认功能分支（Assignment `Branch policy` 例外）→ **`mstar-branch-worktree`**。
+- **Dev 三角**：`@fullstack-dev` 后端主导；UI → `@frontend-dev`；第二轨 → `@fullstack-dev-2`（`mstar-roles` PM 节）。
+- 工期仅 agent-oriented → **`mstar-conventions`** · effort-estimation。
+- plan-writing artifacts land in `{PLAN_DIR}`, not external default plan directories.
+- PM Assignment 键名英文；任务正文可中文；产出/报告默认英文。
+
+## 库文档 / API 问题
+
+先 Read/Grep 项目内文档、规格与源码；仍不确定时再向用户澄清。**不**将第三方 MCP/CLI 文档工具写入 `mstar-*` load order。
+
+## 升级触发
+
+验收仍模糊、评审冲突、重复失败、根因不可收敛 → 升级报告（状态、方案、推荐路径）。
+
+## 反模式（索引）
+
+| 反模式 | 详见 |
+|--------|------|
+| SDD paste-only / 跳过 task review / 并行 implementer | `mstar-sdd` · `mstar-dispatch-gates` |
+| SDD plan 以单席 `qc.md` 收尾 / 跳过 plan tri | `mstar-dispatch-gates` · `mstar-review-qc` · `mstar-sdd` |
+| fix 后无脑重派三审 / 用 `-rev2` 代替原位复验 | `mstar-artifacts` · `mstar-review-qc` |
+| 递归误派 / 误读 Handoff | `mstar-dispatch-gates` |
+| `quick` 跳过 Prepare | 上表 + `mstar-phase-gates` |
+| 多 worktree 未归并就 QC | `mstar-branch-worktree` |
+| 因默认 gitignore 致 feature 缺 plans 而 `Worktree mode: waived`（应保留 feature worktree + control 绝对 Plan Path / SDD dir；无 flock 仅 → `Plan parallelism: serial`） | `mstar-branch-worktree` · `mstar-iteration` §2.0 #5 · `phase-2-worktree-lease` |
+| 并行 writable implement 无隔离（L2 同 plan 多轨：N invoke ≠ worktree；L1 跨 plan：无 verified `execution_lease` + feature worktree） | `mstar-branch-worktree` L1/L2 · `mstar-iteration` §2.6 · `references/parallel-writable-pre-dispatch.md` |
+| 跨 plan 可写派发无 verified `execution_lease` / steal 活跃 lease / 并行 merge 入 `spec_integration_branch` | `mstar-iteration` · `mstar-artifacts`（leases）· `mstar-branch-worktree` L1 |
+| `InProgress` 无 `execution_lease`（snapshot 行）未恢复即可写派发 | `mstar-artifacts` — orphan recovery |
+| 混淆跨 plan lease 门控并行与单 plan 内 SDD 并行 implementer | `mstar-dispatch-gates` · `mstar-sdd` |
+| residual 只写 plan 不写 SSOT | `mstar-artifacts` |
+| `zero-residual` 下把可修 findings 登记为 open R# / 草草 `Approve with residuals` | `mstar-artifacts` Findings cleanup modes · `mstar-review-qc` |
+| 角色文件塞流程长文 | 用专题 skill |
+| 无证据宣称完成 | `mstar-coding-behavior` / verification |
+| CreatePlan 不落盘 / 无 `{HARNESS_DIR}` mirror | `mstar-host` · `cursor-plan-mode-bridge` |
+| 临时方案 / 后续计划只写在对话里 | `mstar-phase-gates` · Durable Roadmap Gate |
+| Phase 1 review chain 未完成即 commit | `mstar-iteration` §1.6；PM 代做专业角色编辑；或三角色并行派发 |
+| OpenCode prompt 含多个 prefix-style role mention | `mstar-host/references/opencode.md` § Role-mention hygiene |
+| Phase 2 paste-only / PM 自实现 | `mstar-dispatch-gates` |
+| Phase 3 折叠进 final plan closure / 跳过 §3.1 gate | `mstar-iteration` §3.0–§3.5 |
+| Phase 4 开 PR 后跳过 merge-ready loop | `mstar-iteration` §5 |
+| Phase 5 在 CI / AI review 仍在跑时 push | `mstar-iteration` §5.1a |
+| iteration-close 无 frontmatter completed / 漏 compound Phase 6 | `mstar-iteration` §3.0.5、§3.4、§3.2 #5 |
+| iteration 默认 `main` 作 base 或 PR 目标 | `mstar-iteration` §1.2、§2.3；`mstar-conventions` Spec 分支模型 |
+
+## 常见 harness 说法对照（帮助理解角色分工）
+
+| 常见说法 | 本仓库实体 |
+|----------|------------|
+| 总编排 | `@project-manager` |
+| 规划/访谈 | `@product-manager` / `@architect` + Prepare 阶段 |
+| category 路由 | **`Task category`** + 路由表 + 子代理选择 |
+| 持续推进 / 不半途而废 | Phase Gate + Todo/`tasks` + 验证门禁 |
+| 行级哈希锚定编辑 | 以 **读后再改 + 小步 Patch** 纪律落实（`mstar-phase-gates`） |
+
+项目根 **`AGENTS.md` 写什么、分层 bootstrap** → **`mstar-conventions`** `references/harness-bootstrap-and-agents-layering.md`（勿在 core 重复长文）。
+
+**专题 skill**（规则在各自 `SKILL.md`）：`mstar-phase-gates`、`mstar-branch-worktree`、`mstar-artifacts` 等 — 见上表索引。

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

@@ -0,0 +1,96 @@
+---
+name: mstar-host
+description: Morning Star host adapter (OpenCode, Cursor, Codex, Kimi, ZCode, omp, dsh). Use after mstar-harness-core whenever host entry, clarify, dispatch, or plan UX differs by platform - OpenCode question/task-tool subagent invoke, Cursor /pm and CreatePlan/SwitchMode dual-write and Task parallel QC, Codex plugin skills plus Plan/Goal Mode, Kimi Agent/AgentSwarm with built-in subagent types only (coder/explore/plan) and role-in-prompt binding, ZCode Agent/AskUserQuestion/EnterPlanMode with built-in subagent types and role-in-prompt binding, omp task/ask/hub preferring live-schema role agents (agents/*.md) with C5b skill-load binding (generic task/scout only as fallback), dsh (DeepSeek Harness) subagent tool with in-process engine gates and bundled mstar commands, sandboxed tools, and tool discovery. Auto-detect host from session tools; then Read references/<host>.md. Always load after mstar-harness-core.
+---
+
+# Morning Star Host Adapter
+
+Host-specific **capabilities and entry behavior** for Morning Star. Process gates and invariants stay in `mstar-harness-core` and topic `mstar-*` skills.
+
+## Load order
+
+**本 skill 总是在 `mstar-harness-core` 之后加载**（先 Read `mstar-harness-core` SKILL.md；宿主注入项目 `AGENTS.md` 也不跳过，见下 `## First action`）。本 skill 只适配宿主入口 / 检测 / 计划 UX；状态机与门禁以 `mstar-harness-core` 为准。
+
+## First action
+
+Read **`mstar-harness-core`** before this skill (even when the host injects project `AGENTS.md`).
+
+## Default path
+
+1. Read `mstar-harness-core`
+2. Read **`mstar-host`** (this skill) and detect host below
+3. Read **`references/<host>.md`** for the active host
+4. Load role via `mstar-roles`
+5. Execute with evidence-first completion checks
+
+Load topic skills **on demand** per `mstar-roles` (do not read every `mstar-*` skill by default). Cursor routing-eval (`.cursor/skills/mstar-routing-eval/`) is regression tooling only — not part of runtime load order.
+
+## Detect active host
+
+Detect from **session tool shapes and available commands** — not from plugin markers on disk. The `*-plugin/plugin.json` files **cannot** identify the host: they all coexist in this harness source repo and in any multi-host install.
+
+| Signal | Host | Next read |
+|--------|------|-----------|
+| **`subagent_type`** param on the Task tool (plus **CreatePlan**/**SwitchMode** when Plan mode is active) | `cursor` | `references/cursor.md`; Plan mode also `references/cursor-plan-mode-bridge.md` |
+| **`question`** tool, or **`task`** tool with **`subagent`** (singular) — no `tasks[]` batch | `opencode` | `references/opencode.md` |
+| **`task`** tool with **`agent`** / **`tasks[]`** batch, **`ask`**, **`hub`** (omp also exposes `/goal`; goal rule is host-agnostic per below) | `omp` | `references/omp.md`; Plan mode also `references/omp-plan-mode-bridge.md` |
+| **`subagent`** tool (dsh's model-facing delegation tool — `@deepseek-ai/dsh-tool-subagent` default `toolName`) | `dsh` | `references/dsh.md` |
+| **`Agent`** / **`AskUserQuestion`** / **`EnterPlanMode`** + **`AgentSwarm`** (Kimi-only) | `kimi` | `references/kimi.md`; Plan mode also `references/kimi-plan-mode-bridge.md` |
+| **`Agent`** / **`AskUserQuestion`** / **`EnterPlanMode`** / **`TodoWrite`**, **no `AgentSwarm`** | `zcode` | `references/zcode.md`; Plan mode also `references/zcode-plan-mode-bridge.md` |
+| `/plan`, `/goal` slash commands; **Goal tools**; `functions.*` / `codex_app.*` tool namespaces; `tool_search`; Browser plugin tools | `codex` | `references/codex.md`; Plan mode also `references/_shared/plan-mode-bridge-core.md` |
+| Still ambiguous | - | Read sections in **`cursor.md`**, **`opencode.md`**, **`codex.md`**, **`kimi.md`**, **`zcode.md`**, **`omp.md`**, and **`dsh.md`** that match tools you have; **`mstar-harness-core` wins** on conflict |
+
+Order matters: check `cursor` → `opencode` → `omp` → `dsh` → `kimi` → `zcode` → `codex`. `subagent_type` (Cursor) vs `subagent` (OpenCode) vs `agent`/`tasks[]` (omp) is the sharpest split among the Task-based hosts; dsh's `subagent` tool collides with no other row, so it sits with the agent-tool hosts.
+
+> **Engine check (when available):** run `mstar host detect --signals <comma-list>` (or `import { detectHost } from "@mstar-harness/engine"` in a host hook) to resolve the detection table above from session tool shapes (prints the host id, or `ambiguous` to fall back on the table + judgment). On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
+
+## Parallel dispatch (invoke-capable hosts)
+
+When PM dispatches **N >= 2** concurrent assignees (QC tri-review, dual-track implement, etc.) and the host exposes actual invoke / Task / subagent tools, read **`references/parallel-dispatch.md`** in the dispatch round (shared with `mstar-dispatch-gates`). Without a callable invoke tool when dispatch is required → **`Blocked`**; Assignment Markdown alone is not dispatch.
+
+## `/goal` directive (host-agnostic)
+
+**Applicability is by capability, not host identity**: any host that exposes a `/goal` command (currently Codex Goal Mode and omp; other code agents may add it later) attaches a persistent objective to the thread. Rule — **always set the goal to running the complete flow to the end**, never a sub-stage:
+
+- **Advancing an iteration**: set the goal to **complete the entire iteration flow** (`iteration-start → per-plan cycles → iteration-close → PR delivery → PR merge-ready loop`). Do not set a sub-stage goal (e.g. "finish Phase 1 only").
+- **Advancing non-iteration work** (single plan / hotfix / one-off task): set the goal to **complete the entire per-plan flow** (`specify → clarify → plan → tasks → implement → plan QC tri + QA gate → Done`). Do not set a sub-stage goal (e.g. "write the plan" or "implement one task").
+
+Goal text is a session-level objective only: `{HARNESS_DIR}` / `{PLAN_DIR}` / `status.json` remain SSOT, and goal completion is **not** harness Done. Mirror goal success criteria into the SSOT plan; when the goal changes, update goal text and the SSOT in the same round.
+
+## Resolve loaded skill root
+
+Docs name assets as skill **`<name>`** → `scripts/…` / `references/…`. **Resolve the loaded skill directory first** — do **not** open `skills/<name>/…` from a consumer app cwd (that layout exists in the harness source / plugin package only).
+
+| Host | Prefer | Filesystem fallback (only if the host cannot load by name) |
+|------|--------|--------------------------------------------------------------|
+| **omp** | `skill://<name>` / `skill://<name>/<rel>` / `/skill:<name>` | Plugin package root `skills/<name>/` after install/link — not app cwd |
+| **Cursor** | Skill **name** via plugin skills | Global `~/.cursor/plugins/local/morning-star-harness/skills/<name>/`; project `.cursor/plugins/morning-star-harness/skills/<name>/` |
+| **Codex** | Skill **name** via plugin | Plugin-mounted `skills/<name>/`; project command skills under `.agents/skills/<name>/` |
+| **OpenCode** | Skill **name** via `@mstar-harness/opencode` | Package-internal `harness-skills/<name>/` — never `process.cwd()/skills/` |
+| **dsh** | Skill **name** via the mstar skill-local provider (`providerName: mstar`) | `$DSH_BUNDLED_SKILL_DIR/<name>[/<rel>]` — the packaged `harness-skills/` mirror mounted package-relative by `@mstar-harness/dsh`; never app cwd |
+| **Kimi / ZCode** | Skill **name** / `/skill:<name>` | Plugin mount `./skills/<name>/` from the installed plugin root |
+
+Authoring convention: **`mstar-skill-authoring`** § Skill-relative script and asset paths. Per-host URI / mount detail: `references/<host>.md`.
+
+> **Engine check (when available):** run `mstar host skill-root --host <id> --skill <name>` (or import `resolveSkillRoot` from `@mstar-harness/engine` in a host hook) to resolve the loaded skill root per the table above. On `fail` -> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.
+
+## Conflict order（Decision Rules）
+
+1. User explicit instructions (this turn)
+2. Project `AGENTS.md` / `CLAUDE.md`
+3. `mstar-harness-core` and related `mstar-*` skills
+4. This `mstar-host` skill and `references/*`
+
+## Workflow
+
+按 `## Default path` 执行：Read `mstar-harness-core` → 读本 skill 并按 `## Detect active host` 检测宿主（`cursor` → `opencode` → `omp` → `dsh` → `kimi` → `zcode` → `codex`）→ 读 `references/<host>.md`（计划模式另读对应 plan-mode bridge）→ 经 `mstar-roles` 加载角色 → 执行并以证据收尾。topic skill 按需加载，不默认通读。
+
+## Evidence
+
+正确结果 = 检测输出：`mstar host detect --signals <comma-list>` 打印 `host: <id>`（或 `ambiguous` → 按检测表 + 判断降级）；已加载的是**对应当前宿主工具形状**的 `references/<host>.md`。计划模式按宿主 plan-mode bridge 完成双写 / 对齐。
+
+## References
+
+- 各宿主适配细则 → `references/<host>.md`（cursor / opencode / omp / dsh / kimi / zcode / codex；计划模式另见 plan-mode bridge references）
+- invoke-capable 宿主并行派发 → `references/parallel-dispatch.md`
+- 角色加载与参数 → **`mstar-roles`**

package/harness-skills/mstar-host/references/_shared/host-role-binding-core.md

@@ -0,0 +1,51 @@
+# Host role-binding core (C5/C5b)
+
+Shared role-binding contract for **Kimi / ZCode** — hosts where Morning Star role ids are **never** valid invoke types, so picking `subagent_type` alone cannot carry Assignment IDENTITY + skill load.
+
+Other hosts follow their own `references/<host>.md` and do **not** use this file for agent selection. Read this file only when the active host reference is Kimi or ZCode.
+
+## C5 — invoke type selection (Kimi / ZCode)
+
+| Host | Invoke-type selection (C5) | Prompt role binding (C5b) |
+|------|----------------------------|---------------------------|
+| **Kimi / ZCode** | Built-in types only (`coder` / `explore` / `plan`, …). Morning Star role ids are **never** valid invoke types. | **Required** |
+
+- **Never invent** agent / subagent names. The **live tool schema** (plus the active host reference C5 table) is SSOT every session.
+- Morning Star role ids (`product-manager`, `fullstack-dev`, `qc-specialist`, …) are **not** valid invoke types — map via the host reference table (`coder` / `explore` / `plan`, …), then rely on C5b.
+
+## C5b — role binding in prompt (required)
+
+Every dispatch on Kimi / ZCode **must** carry the played Morning Star role in the **Assignment** and in the **invoke prompt**:
+
+1. **`Execute as: <role-id>`** in Assignment (harness routing SSOT).
+2. **`Act as <role-id>`** (or equivalent) at the top of the invoke prompt.
+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. **`subagent_type`** — pick from the live built-in set per the host C5 table (not a Morning Star role id).
+
+Paste-only Assignment **without** an invoke call is **not** dispatch.
+
+## Invocation rules
+
+- **1 Assignment ⇒ 1 invoke**: one invoke call carrying the full Assignment body per assignee.
+- **Parallel batch N**: **N** invocations in **one** assistant message (mechanics → **`parallel-dispatch.md`**).
+- **No invoke call** → **Not dispatched** — paste-only / `dispatch incomplete`.
+- **Anti-recursion NEVER**: leaf executors are already `Execute as` — **no** recursive invoke of the same role; Assignment wins (`Delegation: forbidden` unless stated). **Never** multiple implementer invokes in one message for the same plan (SDD serial → **`parallel-dispatch.md`** § SDD implement).
+
+## 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` → `<host>.md` → `mstar-roles` → `references/fullstack-dev-shared.md` → topic skills per that reference.
+
+<task body>
+```
+
+The active host reference shows the matching invoke shape (same turn) — e.g. Kimi/ZCode `Agent` with `subagent_type: "coder"` plus this C5b body.

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

@@ -0,0 +1,91 @@
+# Plan-Mode Bridge Core (shared)
+
+> **Load order**: Read **`mstar-harness-core`** first, then **`mstar-host`** and the host reference + this bridge. When plan management is required, also read **`mstar-conventions`** and **`mstar-artifacts`** before creating or claiming any durable plan state. Path symbols `{HARNESS_DIR}`, `{PLAN_DIR}`, `{SPECS_DIR}` are defined in `mstar-conventions`. On conflict, **`mstar-harness-core`** wins.
+
+Each per-host bridge (`cursor-plan-mode-bridge.md`, `kimi-plan-mode-bridge.md`, `zcode-plan-mode-bridge.md`, `omp-plan-mode-bridge.md`) loads this core and adds its host-specific plan UX (plan tooling, approval gate, todo UI, command surfaces). Codex Plan Mode reads this core directly via `references/codex.md` (no per-host codex plan bridge; the `/goal` rule is host-agnostic in `mstar-host` SKILL.md).
+
+## Dual-write SSOT rule
+
+The host **Plan mode** (session plan file, todos, UI) is a **session UX mirror**. Morning Star **SSOT** lives on disk under **`{HARNESS_DIR}`** (default `.mstar/`, legacy `.agents/`): the main plan in `{PLAN_DIR}/<plan-id>-<name>.md`, the plan registry in `{HARNESS_DIR}/status.json` (v2 root `workflows[]`) + per-lifecycle `{WORKFLOW_DIR}/<id>/snapshot.json` (`plans[]` rows + leases), the iteration compass under `{ITERATION_DIR}/…` when in a formal iteration. Mirror every durable plan artifact to the repo; never treat the host plan file/URI/UI alone as the handoff surface.
+
+### Priority (hard)
+
+1. User explicit instructions (this turn)
+2. Project `AGENTS.md` / `CLAUDE.md`
+3. **`{HARNESS_DIR}` / `{PLAN_DIR}` / `status.json` (v2) + workflow snapshot** (harness SSOT)
+4. Host session plan / todos / UI (session UX mirror) — the host bridge names its surfaces
+
+**NEVER** cite only a host plan path / session todo list / chat summary in Assignment **Plan Path**, **Context Loaded**, or Completion Report when `{PLAN_DIR}/<plan-id>-<name>.md` should exist.
+
+## Before the first plan (bootstrap init)
+
+1. **Read** (minimum): `mstar-conventions`, `mstar-artifacts` (SKILL.md); Prepare gates from `mstar-phase-gates` if not hotfix.
+2. **Discover** `{HARNESS_DIR}` / `{PLAN_DIR}` per `mstar-conventions` (prefer `.mstar/` + `.mstar/plans/`; reuse legacy `.agents/` only when already present and `.mstar/` is absent).
+3. **Initialize** if absent: `{HARNESS_DIR}/`, `{PLAN_DIR}/`, `status.json` from `mstar-artifacts/templates/status.empty.json` (v2 shape), Morning Star process-artifact gitignore set (canonical snippet → `mstar-conventions` SKILL.md「Git 跟踪策略」; `workflows/` / `projects/` subdirs are created on demand by engine writers, not pre-created). Full PM checklist: `mstar-roles/references/project-manager/plan-management.md`.
+
+## Build resume contract
+
+Host **Build** / plan approval resumes the current plan in Agent mode. Do **not** assume it replays `/pm` or re-enters a role skill automatically.
+
+First action after Build, before product-code edits:
+
+1. Reload the harness entry: `mstar-harness-core` → `mstar-host` host reference → this bridge.
+2. If the plan is a Morning Star plan, resume as `project-manager` for coordination and dispatch only.
+3. Read the SSOT plan and `status.json`; use them as the source of truth over the host plan URI/UI.
+4. For each implement/code todo, require a PM Assignment with `Execute as`, `Delegation`, `Working branch` or `Branch policy`, and SSOT `Plan Path`.
+5. If the Assignment or SSOT state is missing, report **Blocked** and repair the harness state before implementation.
+
+Allowed in the parent Build session: plan/status maintenance, routing decisions, Assignment writing, and host task dispatch.
+
+Not allowed in the parent Build session by default: product implementation, test implementation, QC execution, QA execution, deployment, or ops changes. Those follow the normal PM dispatch rules unless the user explicitly overrides the harness.
+
+## CreatePlan: fixed bootstrap todos (prefix)
+
+**Emit these three todos first**, in order, **before** any implement / code todos. Do **not** mark implement todos in progress until all three are **done**.
+
+| Todo ID (use in title) | Goal | On-disk outcome |
+|------------------------|------|-----------------|
+| **`harness-init`** | Bootstrap harness tree | `{HARNESS_DIR}/`, `{PLAN_DIR}/`, process-artifact gitignore set, `status.json` (v2) initialized (`workflows/` / `projects/` created on demand by engine writers) |
+| **`spec-register`** | Register plan in SSOT | New root `workflows[]` entry (`{HARNESS_DIR}/status.json` v2) + `plans[]` row in `{WORKFLOW_DIR}/<id>/snapshot.json` (`id`, `status`, `file`, `metadata`); spec stub in `{SPECS_DIR}` or plan frontmatter |
+| **`mirror-plan`** | SSOT main plan file | `{PLAN_DIR}/<plan-id>-<name>.md` with task checkboxes aligned to the host plan body |
+
+After the host plan is created, keep the host plan body and mirror file **in sync** when scope changes (update both in the same coordination round).
+
+## Implement todo completion gate (every code todo)
+
+**Before marking the todo done:**
+
+1. **Commit**: `git add` + `git commit` on the authorized **Working branch** for this **task id** (one commit per task unless PM explicitly allowed batched commits in Assignment).
+2. **Plan checkbox**: Set `- [x]` on the matching line in `{PLAN_DIR}/<plan-id>-<name>.md`.
+3. **status.json / snapshot** (when PM round requires): bump the snapshot plan row `plans[].status` (e.g. `InProgress`) or append coordination notes to `{WORKFLOW_DIR}/<id>/notes.jsonl` per `mstar-artifacts`.
+4. **Evidence**: Record real `git log -1 --oneline` in Completion Report **Git** (or the plan-mode status note if executing as PM in Plan mode).
+
+**NEVER**
+
+- Mark implement todos done without a commit when tracked files changed.
+- Batch all work into one closing commit unless PM documented an exception.
+- Mark plan-level `Done` in `status.json` without PM/QA authority and without recorded **`QA gate`** (`mandatory` fulfilled or `pm-acceptance` checklist per `qa-trigger-matrix.md`).
+
+Dev-role NEVER rules also apply when executing as implementer: `mstar-roles/references/fullstack-dev-shared.md` (Git NEVER).
+
+## `mstar-iteration` Phase 1 in Plan mode (shared gate)
+
+- **Single plan session**: use **one** plan file (host or SSOT draft); iterate the **same** file in place with feedback-driven edits. If a duplicate plan file was created by mistake: merge into the original, delete the duplicate.
+- **Do not** run Review & Edit, commit, or create the integration branch until the user approves implementation (host approval gate: **Build** / **`ExitPlanMode`** / plan resolve). Plan mode ≠ executing todos — approval is the Phase 1 executable gate (Review chain, lock, branch).
+- Prepare phase (`specify → clarify → plan`) still applies; the mirrored plan is the harness **`plan`** artifact, not a substitute for clarify.
+- Branch policy in the plan session: write **recommended** `iteration_base_branch` / `target_branch` (+ short rationale) into the plan — do **not** silently default to `main`/`master`.
+- Host plan approval is **not** Morning Star **Done**. Implementation still follows phase gates, per-task commits, QC, and QA per the SSOT plan.
+
+## Anti-patterns (shared)
+
+| Anti-pattern | Fix |
+|--------------|-----|
+| Host plan only, no `{HARNESS_DIR}` files | Run bootstrap todos; write mirror plan + status.json/snapshot |
+| Todo done, no commit | Commit per task; paste `git log -1` evidence |
+| Drift between host plan and SSOT plan | Update both in same round |
+| Host plan URI as Plan Path | Use `{PLAN_DIR}/...` path |
+| Skip `spec-register` | Add the snapshot `plans[]` row + root `workflows[]` entry before implement |
+| Build starts coding in the parent session | Resume PM context; dispatch implement work or block on missing Assignment |
+| Host plan approval treated as Done authority | Check harness plan/status/QC/QA gates first |
+| Resume starts coding from host chat summary | Reload harness context and SSOT plan/status first |
+| Phase 1 Plan mode: Review / commit / branch before Build | Keep Pre-Build document-only; execute those todos after approval |

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

@@ -0,0 +1,61 @@
+# Codex host reference
+
+Load when **`mstar-host`** detection resolves **codex** (Codex app/CLI session, `/plan` / `/goal` slash commands, Goal tools, or Codex tool namespaces such as `functions.*`, `codex_app.*`, `tool_search`, `image_gen`, or Browser plugin tools).
+
+Plan Mode: read **`references/_shared/plan-mode-bridge-core.md`** when Codex Plan Mode (`/plan`) is active. Goal Mode (`/goal`, goal tools, or goal progress controls) follows the host-agnostic **`/goal`** rule in `mstar-host` SKILL.md — applicability is by the `/goal` command, not host identity. Codex session plans, UI todos, and goal text are not durable harness SSOT.
+
+Parallel PM dispatch: read **`parallel-dispatch.md`** only when Codex exposes an actual multi-agent / Task-style invocation tool. If no callable invoke tool exists, Assignment Markdown is coordination text only; do **not** claim subagent dispatch.
+
+## Codex-only context
+
+- Plugin source: `.codex-plugin/plugin.json`.
+- Runtime skills: repo `skills/` mounted by the Codex plugin (`"skills": "./skills/"`).
+- Custom agent source: repo `codex/agents/*.toml`; CLI/manual install links these into `~/.codex/agents/` or project `.codex/agents/`.
+- **`/pm`** or **`pm` skill**: force PM entry → `mstar-roles` → `project-manager.md` (Codex primary; Cursor/OpenCode for general per-plan work). **`commands/`** when running iteration Phase 1–5; project CLI install (`mstar-harness init --target codex --scope project`) materializes `iteration-start`, `iteration-drive`, and `iteration-loop` as `.agents/skills/<name>/SKILL.md` symlinks.
+- Role files under root `agents/` are for hosts that load OpenCode/Cursor-style agent shells; Codex uses `codex/agents/*.toml` and still loads `mstar-roles` references directly.
+- Tool and plugin availability can be lazy-loaded or session-dependent. Use the tools actually present in the current session; do not infer capability from documentation alone.
+
+## Skill loading
+
+1. Read `mstar-harness-core`.
+2. Read `mstar-host` and this Codex reference.
+3. If Plan Mode is active, read `references/_shared/plan-mode-bridge-core.md`; Goal Mode follows the `/goal` rule in `mstar-host` SKILL.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 the user is maintaining this repository or the skill is not installed and must be read from the checkout. Skill-root resolve (plugin `skills/<name>/`, project `.agents/skills/<name>/`) → `mstar-host` § Resolve loaded skill root.
+
+## Clarify
+
+- Codex does not imply an OpenCode-style `question` tool.
+- If a structured user-input tool is available in the active mode, use it for concise 1-3 choice decisions.
+- Otherwise ask one concise Markdown question only after codebase exploration cannot answer it.
+- `update_plan` / local todo UI is session progress only; it does not replace `{PLAN_DIR}` plans or `{HARNESS_DIR}/status.json` (v2 root `workflows[]`) + `{WORKFLOW_DIR}/<id>/snapshot.json` (`plans[]` rows).
+- Codex Goal Mode objective is completion criteria for the host thread, not Morning Star Done authority; mirror it into the SSOT plan when the work is implementation-sized.
+
+## Dispatch and role execution
+
+- **No invoke tool / no linked custom agent = no dispatch**: printing `## Assignment` does not start another Codex worker.
+- If Codex exposes custom-agent / multi-agent tools and matching Morning Star agents are linked, PM may dispatch through those tools and must follow `parallel-dispatch.md`.
+- If no invoke tool is present when dispatch is required, return **`Blocked`** — report missing invoke capability to the user. Do not substitute single-session role execution in the PM thread unless the user explicitly overrides harness dispatch for this turn.
+- QC: N rules → **`parallel-dispatch.md`** (**`Execution mode: sdd`** → N=3; **`inline`** → N=1) when a callable invoke tool exists. Cannot emit required **N** → **`Blocked`**.
+- Leaf executors still follow `mstar-dispatch-gates`: no recursive Task/subagent calls unless Assignment says `Delegation: allowed (...)`.
+
+## Files, shell, and approvals
+
+- Prefer `rg` / `rg --files` for search and `apply_patch` for manual edits.
+- Respect Codex sandbox and approval prompts. If a required command fails because of sandbox or network restrictions, request escalation through the host approval mechanism.
+- Do not edit global Codex plugin metadata, marketplace files, credentials, secrets, or user config without explicit user consent.
+- Browser, image, document, spreadsheet, presentation, and automation capabilities are host tools. Use them only when the user request or verification need calls for them.
+
+## Git and final evidence
+
+- Git work still follows `mstar-branch-worktree` and the Assignment `Working branch` / `Branch policy`.
+- Codex app git directives, when available, are audit annotations only. Emit them only after the underlying git action succeeds; never use a directive as a substitute for staging, committing, pushing, or PR creation evidence.
+- Completion reports should cite concrete commands, artifacts, and commit lines when required by the Assignment.
+
+## Gotchas
+
+- Codex plugin install gives skills; Morning Star role subagents require custom agent TOML files linked from `codex/agents/`.
+- Tool discovery (`tool_search`) can reveal capabilities, but availability is not authorization; Assignment `Delegation` still controls use.
+- Session plans, Goal Mode text, chat summaries, and UI todos are not durable harness SSOT unless mirrored to `{HARNESS_DIR}`.