mstar-iteration（迭代管理）

Load order

Read mstar-harness-core first. Path symbols → mstar-conventions. Per-plan gates → mstar-phase-gates. Knowledge crystallization → mstar-compound. Phase 2 implement 波次（进入 per-plan implement 前）→ mstar-sdd + mstar-dispatch-gates；Phase 2 QC 前 → mstar-review-qc。Git/worktree 载体（有 git 写或 lease 时）→ mstar-branch-worktree。Phase 1 角色派发 preflight（每次 invoke 前的 assignment preflight；enforcement: hard fail-fast）→ references/command-shared-invariants.md（本 skill 直接触发时不依赖 command 层）。On conflict, mstar-harness-core wins.

Phase detail 不在本 skill 正文：按下方 Phase route map 只加载当前动作对应的一行 detail——禁止无条件通读全部 phase references。

Scoped primary route（/iteration-drive --assignment|--workflow/--plan|--resume）→ references/plan-scoped-pm.md，且先于本 skill 的全局 todo / backlog / last-plan 逻辑判定。

Scoped primary route（先于全局 Phase 逻辑）

/iteration-drive 的 scoped 形态在本 skill 的任何全局 Phase 逻辑之前改道：

• 先选 route，再 seed todo：不得先按整迭代 boot 建立全局 session todos / backlog / last-plan Phase 3 判断，再把 scoped 会话当作过滤器处理。
• scoped finish = durable handoff（plan 保持 InReview、保留 execution_lease）。status: Done、两个 lease 的删除、Phase 3–6、compass / index / root 投影与迭代 PR 仅 coordinator 拥有。
• 无参数调用语义不变（Phase 2 → 3 → 4 → 5 → 6）；非法非空形态 fail closed，禁止回落整迭代路线；leaf 收到该命令 → 角色边界拒绝。
• boot / plan-local drive / finish / coordinator 序列全文 → references/plan-scoped-pm.md。

设计思路

mstar 实践模式通常是：一次迭代锁定几个 spec 点（specify + clarify），产生多个 plan，每个 plan 含多个 tasks。per-plan 生命周期有完整的闭环（Prepare → Execute → QC → Done）。Compound 不是 per-plan 活动——它是迭代级收口，在迭代内所有 plan Done 后，沉淀一轮知识。

本 skill 管理迭代 Phase 1–6（command 层可聚合编排，但 不得反向引用 command 名；第三方 helper 仅由 command 按需发现）：

Phase 1: start
     ↓
Phase 2: Autonomous Execute  —— [per-plan lifecycle × N]
     ↓
Phase 3: iteration-close
     ↓
Phase 4: PR delivery（开 PR）
     ↓
Phase 5: PR merge-ready loop —— 至 mergeable + CI 全绿 + reviews resolved
     ↓
Phase 6: post-merge close —— PR merged 后 §6.1–§6.4
     ↓
迭代交付完成

关键定位：

• Phase 3 在 integration 分支收口 compound / roadmap；开 PR（Phase 4）≠ 迭代交付完成。
• Phase 5 是 merge-ready loop（修复 → 等 CI/review 波次结束再 push → 再验证，至 §5.5 exit）；Loop 理念与 push cadence SSOT 在本 skill（§2.6；push cadence 细则 §5.1a → references/phase-4-5-pr-delivery.md）；宿主 command 可叠加额外 non-mstar-* helper（优先 babysit / *-babysit；greploop 可选），但不写入 mstar-* load order。
• Phase 6 是 post-merge close（PR merged 后 §6.1–§6.4：terminal snapshot → unregister → 投影对齐 → cleanup（mstar worktree cleanup，dry-run 默认；守卫契约本体 → mstar-branch-worktree「Worktree / branch cleanup」））；§5.5 exit / PR mergeable ≠ 生命周期已关闭（references/phase-6-post-merge-close.md）。
• 一次迭代 = 一个 PR；compound 产物随 PR 合入 snapshot branch.target。

Phase route map（唯一路由表 — 按当前动作加载）

当前动作	必读 detail（按需加载，勿通读）
scoped primary（/iteration-drive 带 --assignment / --workflow --plan / --resume）	references/plan-scoped-pm.md（scoped boot → plan-local drive → handoff finish → coordinator 序列；先于整迭代 todo / last-plan 逻辑）
start（启动迭代 / 重开方向锁定）	references/phase-1-prepare.md（§1.1–§1.6：上下文、范围与 direction lock、compass、索引、v2 状态面、产物边界、§1.6 Review & Edit 链）
execute / resume（推进或恢复 per-plan 循环）	references/phase-2-worktree-lease.md（§2.0 五道闸、§2.1–§2.5 loop/dispatch 细则、control root + integration worktree + lease 全文）
close（全部 plan Done 后收口迭代）	references/phase-3-iteration-close.md（§3.0–§3.6：entry checklist、compound、roadmap、完成标记、exit checklist + commit）
PR / merge-ready（开 PR、推进合并就绪 loop）	references/phase-4-5-pr-delivery.md（§4–§5.2：开 PR、§5.1a push cadence、loop、exit checklist）
Phase 6 / post-merge close（PR merged 后关闭 lifecycle）	references/phase-6-post-merge-close.md（entry（verified merged）+ §6.1 terminal write → §6.2 unregister → §6.3 projection reconciliation → §6.4 cleanup：mstar worktree cleanup，dry-run 默认，--apply 才变更）
Phase 5 helper discovery（仅 command 层按需）	references/phase5-helper-discovery.md（babysit / greploop 发现）

一次只加载当前 route 一行；phase 切换按下方 Phase transition gates 走。

Phase transition gates（HARD — 防跳步）

边界	触发	必须	禁止
→ Phase 2（entry / resume）	§2.0 五道闸全过（细则 → references/phase-2-worktree-lease.md）	继续 Autonomous Execute per-plan loop（phase-2 reference §2.4）；主 worktree 驻留 = 记录的 Main worktree branch，integration 分支检出在专属 integration worktree	五道闸任一 false 仍派发；branch metadata 缺失用 main/master 补位；把生命周期分支切到主 checkout
→ Phase 3	workflow snapshot（workflows/<id>/snapshot.json）中 compass 登记的全部 plan 均为 Done	打印 ## Phase 3: iteration-close；执行 §3.0→§3.5（references/phase-3-iteration-close.md）；host todo phase-3-iteration-close 保持 open 直至 §3.5；close commit 在 integration worktree 执行	开 PR；宣称迭代交付完成；仅依赖 final plan closure；在主 checkout 上 commit close 产物
→ Phase 4	§3.5 exit checklist 全 [x]；frontmatter status: completed + end_date	打印 ## Phase 4: PR delivery；开 PR 到 snapshot branch.target（§4 → references/phase-4-5-pr-delivery.md）	跳过 §3.1 entry checklist 或 compound Phase 6
→ Phase 5	Phase 4 PR 已创建	打印 ## Phase 5: PR merge-ready；执行 §5 loop 至 §5.5 exit（含 §5.1a push cadence）	开 PR 后停止；跳过 review resolve / CI loop；CI/AI review 仍在跑时 push
→ Phase 6	PR 已 merge（verified merged；mergeable ≠ merged，由 PM 核实）	打印 ## Phase 6: post-merge close；按 §6.1→§6.4 执行（references/phase-6-post-merge-close.md）；todo phase-6-post-merge-close 保持 open 直至 §6.4	mergeable 即视为 merged；未核实 merge 就调用 close；§6.1–§6.3 之间夹带 tracked commit
→ 迭代交付完成	Phase 6 §6.1–§6.4 完成（references/phase-6-post-merge-close.md）	snapshot completed + ended_at；根 status.json 条目注销（mstar status workflow-close --workflow <id> exit 0）；投影一致	§5.5 exit 或 PR merge 即宣称交付完成；为 close 释放 lease 或伪造 Done/关闭 residual
start → integration branch	§1.6 Review & Edit chain（references/phase-1-prepare.md）	三角色按序 invoke；specs 为主产出；禁止 start 链向 {KNOWLEDGE_DIR}/ 新增；writing-specialist corpus hygiene + compass status: locked	PM 代做专业编辑；并行三角色；product/architect 写 knowledge；临时笔记进 specs

Engine check (when available): run mstar iteration gate --workflow <id> --compass <delivery-compass.md> --branch "$(git branch --show-current)" --integration <spec_integration_branch> --target <target_branch> (or import { evaluatePhaseGate } from "@mstar-harness/engine" with the currentBranch / specIntegrationBranch / prBaseBranch probe inputs in a host hook) to evaluate the transition gate above against the workflow snapshot — the branch probes cover §3.5 exit item 5 (EXIT_BRANCH_MISMATCH when the commit checkout is not on spec_integration_branch; verify before the §3.5 close commit, not after). On fail (gate-blocking violations) -> do not proceed; fix and re-run. Note: during the Phase-3 window (transition: phase-3-close) the gate exits 1 until the §3.4 close items (status: completed + end_date) are written — that exit-1 is the expected "close work pending" signal (the exit checklist gates Phase 4, not the Phase-3 entry), so proceed with Phase 3 per the table below. Skill text below remains authoritative when the runtime is absent.

误判信号：对话里出现 compound 摘要、roadmap 更新、或「所有 plan 已完成」但 未 打印 §3.1 / §3.5 checklist → 视为 Phase 3 未执行，回到 references/phase-3-iteration-close.md §3.0。

per-plan 状态 SSOT：{WORKFLOW_DIR}/<id>/snapshot.json 的 plans[] 行（per-plan Todo/InProgress/InReview/Done）；根 {HARNESS_DIR}/status.json workflows[] 登记活跃 lifecycle。Phase 6 close 后 snapshot 终态（completed + ended_at）保留为归档，根条目注销（removal-at-terminal；references/phase-6-post-merge-close.md §6.1–§6.2）。 迭代状态 SSOT：{ITERATION_DIR}/<id>/delivery-compass.md frontmatter status + {ITERATION_DIR}/README.md 索引（一行 = 一次迭代）。 迭代分支 SSOT：snapshot branch.base（= iteration_base_branch）+ branch.target（= target_branch）与 branch.integration（= spec_integration_branch）（workflows/<id>/snapshot.json）；compass frontmatter 镜像同名字段。解析顺序见 phase-2 reference §2.3。禁止因仓库存在 main/master 就假定 base 或 PR 目标。branch.base 是创建/merge 锚点，不是驻留事实——主 worktree（control root）驻留分支在生命周期写入前由 PM 记录为主 plan 头的 Main worktree branch，全程不切换；integration 分支检出在专属 integration worktree（snapshot integration_worktree_path）。

产物存储位置

SSOT: mstar-conventions/references/artifact-storage-paths.md。迭代 package → {ITERATION_DIR}/<iteration-id>/（含 delivery-compass.md、guides/、specs/）；根索引 → {ITERATION_DIR}/README.md。Legacy flat {ITERATION_DIR}/<id>-delivery-compass.md 仅兼容读。

2.6 Continuous execution + push 纪律（Phase 2–5 通用 SSOT）

Continuous execution（HARD）：Phase 2 Autonomous Execute 经 Phase 5 merge-ready exit 全程 — 不向用户做例行 yes/no check-in。

• 不因 harness 流程问题常问「是否继续」「要不要现在启动」—— 决策、记录、dispatch
• 进度汇报 / subagent Completion Report 后，下一条必须是 dispatch 或下一 gate 动作，不得以确认问句收束 turn
• 未知 → 读 mstar-*；仅 Blocked、secrets、不可逆范围缺口、branch metadata 缺失、或 Phase 5 多轮仍 blocked 时升级用户
• 实际 Git ≠ working_branch → 同轮更新 plan + snapshot + execution_lease.working_branch（如适用）
• 跨 plan implement 并行安全闸与 integration merge 串行 → references/phase-2-worktree-lease.md §2.0 #5 /「Multi-plan parallelism」（无论 Worktree mode: waived）
• plan 内 SDD 独立 ready tasks 并行，真实依赖与共享写目标串行 — phase-2 reference §2.4、§2.5、mstar-sdd Ready-task scheduling
• allow-residual（默认）：open R# 先登记 project register，且各决策面披露（清单 + severity + 跟踪位置；close 面另含 blocker-defer 标记）；unresolved critical 仍阻断 Approve；zero-residual 为显式 opt-in（可修当轮清干净，仅真 blocker-defer + Durable Roadmap）— 登记与披露职责 → mstar-artifacts Findings cleanup modes
• iteration 命令共享的 PM invariants / preflight / todos / STOP → references/command-shared-invariants.md

Push cadence（§5.1a HARD）：本地可提前修，禁止在 CI / AI review 波次未结束时 git push — 细则 → references/phase-4-5-pr-delivery.md §5.1a。

迭代 compass 模板

完整模板见 references/iteration-compass-template.md。

与其它技能的关系

完整 topic-skill 索引见 mstar-harness-core。本 skill 迭代级关键引用：

• mstar-compound — iteration-close 中触发知识结晶（唯一默认 knowledge 新增路径）
• references/phase-1-prepare.md — start route detail（§1.1–§1.6）
• references/phase-2-worktree-lease.md — execute/resume route detail（per-plan loop + integration worktree、execution_lease、integration_merge_lease）
• references/autonomous-direction-lock.md — §1.2 autonomous direction lock、scale budget、branch resolve
• references/iteration-artifact-boundaries.md — Phase 1 specs / iteration package / knowledge 分工
• references/iteration-corpus-hygiene.md — §1.6 writing-specialist specs 卫生细则

NOT to do

共享反递归红线全清单见 mstar-roles/references/_shared/leaf-executor-core.md「Shared anti-recursion NEVER」。迭代级高频陷阱（其余各 Phase 内已含对应 hard rule）：

• 不要将 Phase 4 开 PR 等同于迭代交付完成 — 必须完成 Phase 5 §5.2 merge-ready loop
• 不要将 §5.5 exit 或 PR merge 当作生命周期终点 — merged 后必须进入 Phase 6（references/phase-6-post-merge-close.md §6.1–§6.4）；禁止为通过 close 释放 lease 或伪造 Done/关闭 residual
• 不要在 Phase 5 CI 仍跑或 AI review 波次未结束时 push（§5.1a）— 本地可提前修，push 等 idle
• 不要在 integration worktree 或主 checkout（control root）上直接编辑产品代码 — Phase 5 修复走 fix feature worktree，review 后 merge 回 integration worktree（phase-4-5-pr-delivery.md §5.0）
• 不要在缺 iteration_base_branch / target_branch 时默认 main / master
• 不要在 Phase 1 §1.6 由 product/architect 向 {KNOWLEDGE_DIR}/ 新增（知识 → iteration-close mstar-compound）
• 不要在 per-plan Done 后立即 compound — 等 iteration-close 统一做

Workflow

Phase 1–6 总览见上文 ## 设计思路 图。执行时按 ## Phase route map 选当前动作的一行 detail：start（范围 + compass + §1.6 Review & Edit 链）→ Autonomous Execute（五道闸 → §2.4 per-plan 循环：分支 → 实现 → QC → QA gate → Done → 串行 merge）→ iteration-close（§3.1–§3.5 + mstar-compound）→ PR delivery（Phase 4）→ PR merge-ready loop（Phase 5 至 §5.5 exit）→ post-merge close（Phase 6，PR merged 后 §6.1–§6.4）。每波用 §2.1 session todos 设护栏防范围漂移；phase 切换以上方 Phase transition gates 为准。

Evidence

迭代交付完成 = Phase 5 §5.5 exit checklist 全 [x] 且 PR merged 已核实 且 Phase 6 §6.1–§6.4 完成（snapshot completed + ended_at、根 status.json 条目注销、投影一致；references/phase-6-post-merge-close.md）。Phase 3 完成标志 = compass frontmatter status: completed + end_date（§3.4）+ §3.5 exit checklist。close 证据在磁盘产物（compass / plans / specs 修订 + 索引 + metadata），不要求单独迭代审查报告（§1.6，references/phase-1-prepare.md）。