# Mstar Routing Eval

> [Cursor maint] Morning Star 路由与 prompt 迭代评估 —— 维护/回归专用（非日常 PM 编排 runtime）。路径：本仓库 `.cursor/skills/mstar-routing-eval/`。(1) PM 路由回归：`assets/routing-evals.json`；(2) Prompt/规则迭代评估；(3) Routing Eval Report 模板。变更 PM 路由或 harness 门禁、`@prompt-engineer` 改 agents/skills、或显式跑场景集时 Read。

- Skill: `btspoony/mstar-routing-eval` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add btspoony/mstar-routing-eval`
- Raw SKILL.md: https://api.skillmd.com/api/skills/btspoony/mstar-routing-eval/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: btspoony (https://skillmd.com/u/btspoony)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/btspoony/mstar-routing-eval

---


## Maintainer scope（维护专用 · Cursor）

- **不是 runtime pack**：日常 `specify → implement → QC` **不要求** Read 本 skill；已从 `skills/mstar-*` 运行时包中拆出，避免与「每轮必读」混淆。
- **Canonical 位置**：本仓库内 **仅此目录**（`.cursor/skills/mstar-routing-eval/`）为正文 + `assets/` SSOT；**不再**维护 `skills/mstar-routing-eval/` 副本。
- **谁在读**：`@prompt-engineer` 改规则前；维护者改 `project-manager` / harness 门禁后跑回归；`repo-maintenance` 清单涉及路由时。

## Load order（必读顺序）

**在同一会话或任务中首次 Read 本 skill 时：必须先 Read `mstar-harness-core` skill（SKILL.md，以及评估路由与门禁时需要的 `mstar-harness-core/references/`）。** 本 skill 的 `routing-evals.json` 场景**校验的是对 harness 的遵守情况**；若未建立 harness 上下文，评估易与真实门禁脱节。冲突时 **以 `mstar-harness-core` 为准**。

**摘要**：`mstar-harness-core` — 期望路由与 phase gate；本 skill — 场景集、`Routing Eval Report` 模板与回归方法。

# Morning Star Routing & Evaluation Harness

## 1. PM 路由评估

本节用于验证 `@project-manager` 是否将任务路由到正确的 agent 和门禁。

### 输入

- **场景集**：本 skill 的 **`assets/routing-evals.json`**
- **路由策略来源**：`mstar-roles` skill 的 `project-manager` 角色
- **全局约束**：`mstar-harness-core` skill（含 harness 不变量与 skill 索引）

### 评估方法

对每个场景：

1. 将实际路由与 `expected_route` 进行比对。
2. 检查所需产出是否已规划并最终产出。
3. 验证没有 `hard_fail_if` 条件被违反。
4. 验证 `Context Loaded` 已声明且包含必要文件。
5. 验证 Assignment 的语言契约：字段名英文、任务正文可中文、执行产出/报告英文（除非用户明确要求其他语言）。
6. 记录路由质量和缺失的证据。

### 评估执行步骤（1-2-3）

1. **准备输入**：加载当前 `assets/routing-evals.json`、`project-manager.md`、`mstar-harness-core`（含 references）。
2. **逐案判定**：按 `expected_route` / `must_have_artifacts` / `hard_fail_if` 打分并记录证据。
3. **输出报告**：按下文 **`Routing Eval Report`** 模板汇总（含 `phase_gate_compliance_rate`）。

### 评分

- `Pass`：路由和产出满足预期，无硬性失败。
- `Borderline`：存在轻微偏差但质量门禁得到保留。
- `Fail`：触发硬性失败条件或跳过关键门禁。

### Phase Gate 评分细则

用于量化 `specify -> clarify -> plan -> tasks -> implement` 合规度。

- `Pass`
  - 非 hotfix：Prepare 与 Execute 门禁均完整通过；无跳步实现。
  - hotfix：允许压缩路径，但已明确事后 `clarify/RCA` 补记安排。
- `Borderline`
  - 门禁顺序总体正确，但存在可修复的轻微缺项（例如 `Phase Gate Checklist` 字段漏写但证据可追溯）。
  - 未出现"先实现后补 gate"的行为。
- `Fail`
  - 非 hotfix 跳过 `clarify` 或 `tasks`。
  - 已知 plan drift 仍继续实现，且无 plan 回写。
  - hotfix 未承诺或未记录事后 `clarify/RCA`。

### 建议量化指标

- `phase_gate_compliance_rate = pass_cases / total_cases`
- 建议门槛：
  - 日常迭代：`>= 0.9`
  - 关键发布前：`= 1.0`

## 2. 回归信号

如果以下情况在两个或以上场景中出现，则说明路由逻辑退化：

- 实现类任务省略了 **QA gate 决策**（`mandatory` 或 `pm-acceptance` 须落 Assignment；禁止无字段即 Done）
- QC 路径相对任务类型被过度或不足使用
- 跨模块工作缺少 architect/探索阶段
- 未按 `specify -> clarify -> plan` 完成准备阶段即进入实现
- `plan` 完成后未进行 `tasks` 拆解就直接实现
- 非热修复任务使用了热修复路径
- 对业务 Git 仓库的实现类分派缺少 **`Working branch`** 或明确的 **`Branch policy`**（见 **`mstar-branch-worktree`** `SKILL.md`）
- `Context Loaded` 缺失或缺少必要的 plan 路径
- 非热修缺陷在未记录根因或可证伪假设前大规模改代码
- 生产/高危运维变更缺少回滚说明或高危清单
- 声明 Report-only 的 QA 任务却改动业务逻辑，或无谓触发全量三审
- Hotfix / clean small non-UI 误派 `qa-engineer`（应为 `QA gate: pm-acceptance`）
- UI 可见变更跳过 mandatory QA 或无 observable 证据
- Assignment 语言契约不一致（字段名漂移为中文、或要求英文报告却回报为中文且无用户豁免）
- 实现类 Assignment **缺少 `Task category`** 或与 **`Execute as`**、`Why this agent` 明显矛盾（或缺少 **`Execute as`**）
- **意图门禁**缺失：Prepare 未书面收敛真实目标/成功判据/非目标即进入开发分派
- **Dev 三角失衡**：在「新 API + 多文件/用户可见 UI」或**可并行的双模块**场景下，长期**仅**派 `@fullstack-dev`、从不派 `@frontend-dev` / `@fullstack-dev-2`，且 Assignment 未写明 `Dev routing: single-stream — …`
- **误把「单轨串行」当「全程仅 fullstack-dev」**：计划写不并行 / 逐波串行，但 PM Task Board 上多行可对等 dev 单元却**无理由**全部 `fullstack-dev`、未按 `project-manager.md` Dev 三角 §6 round-robin，也未写 `Dev owner tie-break: single id — …`
- **并行技能标签缺失**：已下发 **≥2 条并行实现 Assignment**（或 `Dev routing: parallel` / tasks 并行标记）且走 Superpowers 工作流时，**Status Update 或 Assignment 的 `Superpowers` 未**出现 **`dispatching-parallel-agents`**（或同义短语）；或 **同仓 ≥2 可写并发** 却未叠 **`using-git-worktrees`** 与检出约定
- **N invoke ≠ worktree 隔离**：同条消息已发 ≥2 implement invoke，但 Assignment 无绝对 **`Worktree path`** / 未在 invoke 前 `git worktree add`（见 **`mstar-branch-worktree`** → **`references/parallel-writable-pre-dispatch.md`**）
- **跨 plan 无 lease 并行**：迭代 Phase 2 跨 plan 可写派发无 verified **`plans[].execution_lease`** + 独立 feature **`Worktree path`**；或 steal / 覆盖活跃 **`execution_lease`** / **`integration_merge_lease`**；或并行 integration merge；或 **`InProgress`** 无 lease 未恢复即 writable-dispatch（见 **`mstar-iteration`** §2.6 · **`mstar-dispatch-gates`**）
- **跨 plan 并行无 same-host 锁**：跨主机 / 无共享 flock 仍 dispatch 跨 plan 并行可写 implement，且 **无** 用户本轮 `Cross-host lease race: accepted`（或等价）+ audit `plans[].notes`；应 **Blocked** 或改为 **`Plan parallelism: serial`**（见 **`mstar-artifacts`** · **`mstar-iteration`** §2.0 #5）— **含 `Worktree mode: waived`**
- **`Worktree mode: waived` 误作并行授权**：Assignment 含 waived 且无 same-host 锁、无 serial、无 `Cross-host lease race: accepted` + audit 仍 dispatch 跨 plan 并行可写 implement
- **invoke 角色字段缺失（静默 generic 回退）**：已发 Task/subagent invoke，但 item 漏写与 **`Execute as`** 匹配的角色绑定字段（omp **`agent`** / Cursor **`subagent_type`** / OpenCode **`subagent`** / Kimi·ZCode **`subagent_type`**）⇒ 宿主静默回退 generic worker，却因 count=N 通过而误判「派发完成」（见 **`mstar-dispatch-gates`**、**`mstar-host/references/parallel-dispatch.md`**）。**N=1 顺序 Review-&-Edit 链**最易触发——count 门恒过，字段门是唯一保护
- **scoped 会话越界**：作用域 PM 已绑定指定 plan 仍驱动非指定行（例如第一个未完成 plan）；或把 `project-manager` 当 subagent 派发而非在当前主会话 boot；或为 scoped 路由加载整迭代 boot 产物（compound、Phase 3-6 细则）；或把 plan / coordinator 会话路径传进 child Assignment 或 child invoke（case `plan-scope-addresses` · 见 **`mstar-iteration`** → `references/plan-scoped-pm.md`）
- **重复 fresh claim 被当 resume**：第二个终端对同一 Assignment 再 bind 时发明 resume token 或自动挂到活跃 holder；或把终端标签、pane 状态、idle 时长、TTL 当身份，或抢 lease；或把同一 Assignment 的 fresh bind 当隐式 same-holder resume（期望 engine 以 `coordination.duplicate-holder` 拒绝；case `plan-scope-duplicate` · 见 **`mstar-iteration`** → `references/plan-scoped-pm.md`）
- **未知或残缺参数回退整迭代**：`--workflow`/`--plan` 残缺、混合或未知时回退到无参整迭代路由；或静默补全缺项、挑默认 plan；或声称畸形调用执行成功、改状态让它「成功」（case `plan-scope-unknown-args` · 见 **`mstar-iteration`** → `references/plan-scoped-pm.md`）
- **无参路由被 scoped 化**：把无参路由当作对 global boot 的 scoped 过滤；或在无参路由上要求 `--workflow`/`--plan` 或 Assignment；或为它 seed 一个 scoped session（case `plan-scope-noargs` · 见 **`mstar-iteration`** → `references/plan-scoped-pm.md`）
- **最后一个 plan 越权收尾**：因是最后一个未完成 plan 而进入 `## Phase 3: iteration-close` 或跑 compound；或从 scoped session 写 `status: Done`、删 `execution_lease`；或开迭代 PR、启动 PR merge-ready loop（期望停在 `mstar plan handoff` 后的 `InReview`；case `plan-scope-last-plan` · 见 **`mstar-iteration`** → `references/plan-scoped-pm.md`）
- **scoped session 自证 Done**：plan session 置 `Done` 或释放行 execution lease / integration merge lease；或没有已验证的 coordinator merge proof 就报完成；或信任调用方给的成功标志、用第二次 merge 代替 `reconcile`（case `plan-scope-handoff-done` · 见 **`mstar-iteration`** → `references/plan-scoped-pm.md`）
- **leaf 升格或收凭据**：leaf 自升为 PM / coordinator 并吸收 plan scope；或递归派发 PM 或任何 subagent；或接受、保存、回显 Assignment 给的 session path / credential（case `plan-scope-leaf` · 见 **`mstar-dispatch-gates`**）
- **Phase 2 线性等待**：存在 running child 即进入 wait，未先按 `Rescheduling checkpoint`（`before-wait`）评估独立 ready task / 已 prepare plan；或把 plan / task 编号当串行理由（case `phase2-ready-before-wait` · home 指针 → **`mstar-iteration`** → `references/phase-2-worktree-lease.md` §2.4）
- **review 返回不推动调度**：task review 返回后仍等无关 plan 的整个 lifecycle 结束才派发无关 ready 实现；或让并行轨共用同一可写 session / resumed reviewer（case `phase2-review-overlap` · home 指针 → **`mstar-iteration`** → `references/phase-2-worktree-lease.md` §2.4）
- **依赖提前释放或活动 base 被改**：review 通过即释放 dependent task；或对已派发活动 task re-split / 改 `BASE_SHA`（case `phase2-base-dependency` · home 指针 → **`mstar-iteration`** → `references/phase-2-worktree-lease.md` §2.4）
- **重复 owned 工作 / 超容量 primary**：重复派发 owned / running 工作，或在最后一个 primary 槽位被占时再起 primary；或用 pane idle / 终端标签当 ownership（case `phase2-owned-and-capacity` · home 指针 → **`mstar-iteration`** → `references/phase-2-worktree-lease.md` §2.4）
- **空 ready 循环**：无 ready work 时反复自证同一事实、timer / 轮询、tick 计数或「still waiting」notice；为保持忙碌造工作（case `phase2-quiet-wait` · home 指针 → **`mstar-iteration`** → `references/phase-2-worktree-lease.md` §2.4）
- **scoped primary 越界调度**：scoped plan primary 驱动 sibling plan、跑 integration merge 或进入 Phase 3–6（case `phase2-scoped-primary` · home 指针 → **`mstar-iteration`** → `references/phase-2-worktree-lease.md` §2.4）

## 3. 迭代规则

如果任一场景失败：

- 向用户提议对 `mstar-roles` skill 的 `project-manager` 角色 或 `mstar-*` skills 的修改（全局配置写入仅由用户本人执行，agent 不得直接落盘）
- 重新运行完整场景集
- 在 plan notes 中记录变更内容及原因

## 4. Prompt/规则迭代评估（独立于单次对话）

### 为什么需要这个

没有评估的 prompt 修改容易过拟合到单次对话。使用小型但可重复的评估体系，让改进提升可靠性，而非仅仅优化风格。

### 迭代循环

1. 定义变更假设（若涉及「库文档怎么查」或宿主差异，先对照 `mstar-harness-core` 的共享协议与当前宿主 adapter skill，避免双轨说明漂移）。
2. 运行一组固定的代表性任务提示词。
3. 对比变更前后的行为。
4. 记录发现并更新提示词/skill 文档。
5. 重复直到收益趋于平稳。

### 测试集设计

维护一组紧凑的提示词，覆盖：

- 小型功能交付
- 中等规模跨模块变更
- 缺陷调查与修复
- 审查密集型路径（含评审意见冲突）
- 提示词/规则重构任务
- 间歇性/高歧义缺陷（RCA 先于大改）
- 用户可见前端回归（`QA gate: mandatory` + 可观察 QA 证据）
- Hotfix / clean small non-UI（`QA gate: pm-acceptance`，不派 QA）
- 生产或高危运维变更（回滚与清单）
- QA Report-only（无业务代码改动）

每个测试应指定：

- 预期路由（应使用哪些 agent）
- 预期产出（计划、审查摘要、验证证据）
- 硬性失败条件（缺少 QA gate、无 pm-acceptance 清单即 Done、跳过审查等）
- 阶段门禁轨迹（`specify -> clarify -> plan -> tasks -> implement`）

### 评分维度

每次运行按 1-5 分评分：

- 路由准确性：正确的 agent、正确的阶段、最少的交接摩擦
- 策略合规性：计划更新、状态流转、签收规则
- 证据质量：具体验证而非模糊声明
- 吞吐量：每轮产出进展，避免不必要的等待
- 鲁棒性：失败或歧义后的恢复质量
- 阶段适度性：任务体量与门禁深度匹配（小改动不套全量"计划评审"链，大改动不跳过 RCA/契约）
- Phase Gate 合规：非 hotfix 不得跳过 `clarify` 与 `tasks`
- 行为准则合规：是否符合 `mstar-coding-behavior`（显式假设、最小解法、手术式改动、`Step -> verify`）

### Prompt 变更的最低接受标准

提示词/规则变更只有在满足以下条件时才可接受：

- 策略合规性不下降
- 不增加可避免的交接循环
- 至少 3/5 场景中证据质量持平或更好
- 关键场景中 `Phase Gate` 合规率不低于变更前（建议目标：100%）
- 行为准则合规不下降（尤其是"无关改动率"与"不可追溯改动"）

### 回归记录

当变更导致回归时，记录：

- 提示词版本和变更部分
- 失败的场景
- 可能的根因
- 回滚或后续调整

将此日志保存在相关 plan 文件的 notes 或 failure log 中。

## 5. Routing Eval Report（输出模板）

当使用 `assets/routing-evals.json` 跑回归时，建议统一输出以下结构，便于横向比较：

```markdown
# Routing Eval Report

## Run Metadata
- date: YYYY-MM-DD
- ruleset version: {version}
- evaluator: {agent/person}

## Overall
- total_cases: {n}
- pass_cases: {n}
- borderline_cases: {n}
- fail_cases: {n}
- phase_gate_compliance_rate: {pass_cases / total_cases}

## Failed Cases
- {case-id}: {reason}
- {case-id}: {reason}

## Borderline Cases
- {case-id}: {what is missing and why still borderline}

## Regression Signals
- {signal}: {count}

## Recommended Actions
- {doc or prompt change proposal}
```

最小要求：

- 每个失败用例必须对应 `hard_fail_if` 中的具体条目，避免"主观失败"。
- 必须单独报告 `Phase Gate` 相关失败（`clarify/tasks/plan-drift/hotfix-post-rca`）。
- 报告应可回溯到本次评估使用的 `routing-evals.json` 版本。

## 6. 实践指引

- 每次迭代只改变一个主要行为维度。
- 优先删除低价值指令，而非添加更多文本。
- 将评审中反复出现的评论转化为明确的模板或检查。
- 将持久性规则提升到对应 `mstar-*` skill 中；保持角色文件简洁。
- 对"最小解法/手术式改动"建议做抽样 diff 审计，避免 prompt 变更后再次膨胀。

## Assets

- `assets/routing-evals.json` — PM 路由回归场景集（结构：`cases[].prompt / expected_route / must_have_artifacts / hard_fail_if`）。评估时用 `cat` 或 `jq` 读取；**更新场景集须与本 skill 同 PR 维护**以避免版本漂移。本 skill 侧的维护事实：场景集当前为 **`version` 32 · 63 例**（含 `plan-scope-*` 7 例与 `phase2-*` 6 例，其防守信号均登记在 § 2）；数字以场景集文件为准，此处只随更新改写。