# Iteration 命令共享 invariants + preflight

本文件是 `commands/iteration-*.md`（`iteration-start` / `iteration-drive` / `iteration-loop`）**重叠内容**的单一共享副本（SSOT）。**只收录出现在 ≥2 个命令中的行**；命令专属内容保留在命令正文，**不**复制进本文件：

- `iteration-start` interactive direction lock via the bundled `grill-me`, the host Plan-mode Phase 1 path and `pause` semantics — start-specific
- `iteration-loop`「Do not Read `skills/grill-me/SKILL.md`」— loop 专属
- `iteration-loop` session todo `phase-1-autonomous-start`（Boot → compass `locked` + integration branch pushed）— loop 专属

命令正文经一行指针引用本文件，不重复定义以下 invariants / preflight / todos / STOP。

## PM invariants（重叠行）

Phase 2–5 全程有效（drive + loop 共有的行）：

| 禁止（PM 线程） | 必须 |
|-----------------|------|
| Write/Edit/Shell 产品代码、写测试、跑 QC（Phase 2） | 每条 implement/QC/QA Assignment ⇒ **1 次 `Task`** |
| **多 task plan 用 inline 大包派发**（整份 plan / T1–Tn 贴进一个 dev Assignment） | **SDD**：`mstar-sdd` per-task 循环 — `mstar sdd task-brief` → implementer → `mstar sdd review-package` → task reviewer → `progress.md` |
| 只写 Assignment 就进入下一 gate | 同轮 dispatch：每条 Assignment ⇒ **1 次 invoke**（`Subagent invokes issued: N`，N = Assignment 条数） |
| 最后一个 plan `Done` 后直接开 PR / 汇报结束；§5.2 merge-ready exit 或 PR merged 即宣称交付完成 | **Phase 3 → 4 → 5 → 6** 顺序执行（Phase 6 = PR merged 后 post-merge close，`references/phase-6-post-merge-close.md`） |
| Phase 5 自己改产品代码 | 需改产品代码时 **dispatch** `fullstack-dev` / `ops-engineer` |

派发细则 → **`mstar-dispatch-gates`** + **`mstar-host`**。Phase 3 细则 → **`mstar-iteration/references/phase-3-iteration-close.md`** + **`mstar-compound`**。

## Assignment preflight（bash 块 — byte-identical 共享副本）

`mstar-harness` bin 未安装时静默跳过；在每次 implement/QC/QA 派发前（**SDD** 下为最新 `{SDD_DIR}/task-N-brief.md` 或临时写盘的 Assignment）校验。模式由迭代 compass frontmatter 的 `enforcement` 键决定（Slice 5）：

- **默认（compass 无 `enforcement: hard`）— 可选 warn-only**：exit 1 仅提示，不阻断派发（Slice 3 行为不变）：

```bash
command -v mstar-harness >/dev/null 2>&1 && mstar-harness dispatch validate "<latest-assignment-file>"
```

- **`enforcement: hard`（迭代 compass frontmatter 声明）— fail-fast**：校验失败即 `exit 1` 阻断派发（bin 缺失仍静默跳过）：

```bash
if command -v mstar-harness >/dev/null 2>&1; then mstar-harness dispatch validate "<latest-assignment-file>" || exit 1; fi
```

> 路径必须加引号且替换为具体文件（如最新 `{SDD_DIR}/task-N-brief.md`，勿留尖括号）——agent 代入的路径不得进入 shell 无引号展开。

## Session todos（重叠行；drive + loop 共有）

The primary coordinator projects the entire selected iteration into the table below; a row completing does not discharge its parent delivery obligations.

| Todo id | 何时追加 | 何时可勾掉 |
|---------|----------|------------|
| plan-wave todos | 进入 Phase 2 | 各 plan `Done` |
| `phase-3-iteration-close` | 仅剩 1 个非 `Done` plan | Phase 3 §3.5 exit 全 `[x]` |
| `phase-4-create-pr` | Phase 3 完成后 | PR 已创建并记录 URL/number |
| `phase-5-pr-merge-ready` | Phase 4 完成后 | Phase 5 merge-ready：§5.2 第 1–5 项全 `[x]`（第 7 项是 merge 前置、第 8 项 merged 后才可勾，均不属于本 todo） |
| `phase-6-post-merge-close` | §5.2 第 7 项（§5.3 授权）成立后 PR **已 merge**（mergeable ≠ merged） | Phase 6 §6.1–§6.4 完成（`mstar status workflow-close --workflow <id>` exit 0 + 投影一致） |

Phase/gate 转换按 **`mstar-host`**「Phase-transition todo refresh (host-agnostic)」刷新：依据 ACTIVE 执行行与 authored plan 证据勾掉完成项，保留未决 gate / 未来 phase，再追加下一批；todos 只是投影，不授权转换。

## Continuous execution STOP list（重叠行；start / drive / loop 共有）

Execute **`mstar-iteration` §2.6**（Continuous execution SSOT：自 Phase 2 进入至 Phase 5 merge-ready（§5.2 第 1–5 项全 `[x]`）前 PM **连续编排**，进度汇报后下一条必须是 dispatch 或下一 phase 步骤，不向用户例行 yes/no check-in；`reviewed-auto` 下继续至 §5.3 授权成立并 merge，`owner-gated` 在此停等**人类 owner**（操作者/用户，不是 coordinator 席位）的书面批准）。

**合法 STOP（仅此升级用户）**：

- 迭代 branch metadata 缺失（`iteration_base_branch` / `target_branch`）
- **§5.3 merge 授权未满足**：`owner-gated` 停等**人类 owner**（操作者/用户，不是 coordinator 席位）对当前 PR head 的书面批准；`reviewed-auto` 停等 settled、已 posted、且 `head` 等于当前 PR head 的 `ship it` 报告；`pr_merge_policy` 缺失则回 Phase 1 补齐。这是设计的等待点，不是流程问题
- **`Blocked`**：真冲突、secrets、不可逆范围缺口、Phase 5 多轮仍无法 merge-ready
- 用户本轮显式打断

**Turn closure during Phase 2–5 continuous execution**: retain the existing in-flight-action discipline (invoke issued or next dispatch Assignment named); do not end with a routine user-confirmation question.

**Phase 1 distinction**: interactive prototype feedback and explicit current-revision design confirmation (§1.2.5) are required before formal authoring, not forbidden routine execution check-ins. Explicit autonomous opt-in instead retains a reasoned prototype/disposition without routine human approval. Neither route waives host Plan-mode permissions or implementation authorization.