mstar-iteration

name	mstar-iteration
description	Morning Star 迭代管理 —— Phase 1（默认 interactive direction lock；opt-in autonomous；specs + `<iteration-id>/` package；禁止直写 knowledge）、Autonomous Execute、iteration-close（compound 提升 package → knowledge）、PR 交付、PR merge-ready loop。分支 SSOT：`status.json` + compass frontmatter。

mstar-iteration（迭代管理）

Load order

Read mstar-harness-core first. Path symbols → mstar-plan-conventions. Per-plan gates → mstar-phase-gates. Knowledge crystallization → mstar-compound. Phase 2 entry（control worktree + lease）→ references/phase-2-worktree-lease.md + mstar-branch-worktree。Phase 2 implement 波次（进入 per-plan implement 前）→ mstar-sdd + mstar-dispatch-gates。Phase 2 QC 前 → mstar-review-qc。On conflict, mstar-harness-core wins.

设计思路

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

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

Phase 1: iteration-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 3 在 integration 分支收口 compound / roadmap；开 PR（Phase 4）≠ 迭代交付完成。
• Phase 5 是 merge-ready loop：修复 →（等 CI/review 波次结束再）push → 再验证，直至 §5.5 exit。Loop 理念与 push cadence SSOT 在本 skill（§5.1a）；宿主 command 可叠加额外 non-mstar-* helper（优先 babysit / *-babysit；greploop 可选 — 仅当仓库具备 Greptile/greploop 时采用），但不写入 mstar-* load order。
• 一次迭代 = 一个 PR；compound 产物随 PR 合入 metadata.target_branch。

Phase transition gates（HARD — 防跳步）

边界	触发	必须	禁止
→ Phase 3	status.json 中 compass 登记的全部 plan 均为 Done	打印 ## Phase 3: iteration-close；执行 §3.0→§3.5；host todo phase-3-iteration-close 保持 open 直至 §3.5	开 PR；宣称迭代交付完成；仅依赖 final plan closure
→ Phase 4	§3.5 exit checklist 全 [x]；frontmatter status: completed + end_date	打印 ## Phase 4: PR delivery；开 PR 到 metadata.target_branch（§4）	跳过 §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
→ 迭代交付完成	§5.5 exit checklist 全 [x]	PR mergeable；required CI 全绿；reviews resolved	Phase 4 开 PR 即宣称完成
iteration-start → integration branch	§1.6 Review & Edit chain	三角色按序 invoke；specs 为主产出；禁止 start 链向 {KNOWLEDGE_DIR}/ 新增；writing-specialist corpus hygiene + compass status: locked	PM 代做专业编辑；并行三角色；product/architect 写 knowledge；临时笔记进 specs

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

per-plan 状态 SSOT：{HARNESS_DIR}/status.json（per-plan Todo/InProgress/InReview/Done）。 迭代状态 SSOT：{ITERATION_DIR}/<id>/delivery-compass.md frontmatter status + {ITERATION_DIR}/README.md 索引（一行 = 一次迭代）。 迭代分支 SSOT：root metadata.iteration_base_branch + metadata.target_branch（status.json）；compass frontmatter 镜像同名字段。解析顺序见 §2.3。禁止因仓库存在 main/master 就假定 base 或 PR 目标。

产物存储位置

SSOT: mstar-plan-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 仅兼容读。

---

Phase 1: iteration-start（启动迭代）

PM 在新迭代启动时执行。

1.1 收集上下文

1. 读 {ITERATION_DIR}/README.md（若存在），了解历史迭代
2. 读 STRATEGY.md（若存在），对齐战略方向（见 mstar-strategy）
3. 如果有未完成的 roadmap 残余（上一迭代标记为 next 的 plan），纳入本次迭代范围候选

1.2 定义迭代范围

与用户/产品对齐后（或按下方 autonomous 模式锁定后），确定：

字段	说明
Iteration ID	唯一标识，推荐 v<major>.<minor> 或 iter-<YYYY-QN>
范围	本迭代要锁定的 spec 点（问题陈述清单）
Plans	预期在本迭代中完成的 plan 列表（允许中途增减）
里程碑	关键节点与日期
验收标准	迭代级别的 Done 定义
非目标	明确排除在本次迭代外的事项
Roadmap 上下文	本迭代在整体 roadmap 中的位置（current iteration / next iteration）
Delivery branch policy	iteration_base_branch（integration 分支从何处分出）、spec_integration_branch、target_branch（最终 PR 目标）
Scale budget（可选）	仅当 caller 显式给出或选用 autonomous 时适用：S = 1 业务 plan；M = 2–3；L = 3–4（上限 4）；XL = >4（5+）。只计实际业务交付 plan，不计 harness 流程性工作（Review 链 / QC / QA / compound / close / PR 等）。interactive 默认不强制 S/M/L/XL。计数细则 → references/autonomous-direction-lock.md § Scale budget

Direction lock modes

compass/plans 初稿落盘前，必须锁定单一迭代方向、成功标准、非目标，并确认 delivery branch policy；决策写入 compass ## Scope / ## Acceptance Criteria / ## Non-Goals 与 Delivery Branch Policy。

Mode	何时选用	行为
interactive	默认（未显式声明 mode 时一律用此）	与用户/产品逐问收敛方向与 branch policy；不得静默默认 main/master
autonomous	仅当 caller / Assignment 显式声明 Direction lock mode: autonomous（或等价书面 opt-in）	代码优先调研 → 排序候选 → 锁定推荐方向并落盘 rationale；不因「是否同意该方向」例行问用户。细则 → references/autonomous-direction-lock.md

宿主 Plan UX（interactive）：若宿主提供 Plan 会话（先写 session plan、后点 Build 才执行 todos）：

• 允许 先 scaffold 空白 Phase 1 文档/todos，再以 用户反馈驱动 收敛：Agent 探索并写入推荐，原地更新同一份 session plan；用户提方向/意见，不以例行问卷为主路径。
• Branch policy：在 plan 中写推荐值 + rationale（不得静默 main/master）；用户可用反馈改正；仅在用户明确结束反馈后仍缺字段时再追问。
• 访谈式收敛 仅在反馈结束后仍有阻塞缺口时可选发起。
• 禁止为更新内容再开第二份 session plan。

非 Plan 会话仍按「收敛后再写 compass/plans 初稿」的默认顺序。此条 不改变 autonomous 路径，也 不要求非 Plan 宿主先写空文件。

禁止：在未显式 opt-in 时自行切换到 autonomous（例如仅因读了本 skill 或存在 roadmap next）。

Branch policy gate（interactive — 默认路径）：若用户、现有 roadmap、或项目约定未明确 iteration_base_branch / target_branch，PM 必须检查当前分支并向用户确认（Plan 会话走上方「推荐写入 plan + 反馈改正」；非 Plan 仍须确认）。不得因为存在 main / master 就默认从默认分支开 iteration 或向默认分支提 PR。

Autonomous branch resolve：仅 autonomous 模式；解析顺序与 STOP 规则见 references/autonomous-direction-lock.md（勿把该顺序套用到 interactive 以跳过向用户确认）。

1.3 创建迭代 package + compass

创建 {ITERATION_DIR}/<iteration-id>/，写入 delivery-compass.md（canonical；禁止新写根目录 <id>-delivery-compass.md）。必须使用 references/iteration-compass-template.md 完整结构（YAML frontmatter + ## Roadmap Position + close 占位节）。end_date 仅在 iteration-close 填入；禁止用正文 completion prose 替代 frontmatter status。按需创建 guides/、specs/ 与 package README.md。

---
iteration_id: <id>
start_date: YYYY-MM-DD
status: active
iteration_base_branch: <branch-or-ref>
target_branch: <branch>
plans: []
---

# <iteration-id> Delivery Compass

## Scope
<本迭代要锁定的 spec 点>

## Plans

| plan_id | Name | Status | Notes |
|---------|------|--------|-------|
| <id> | <name> | Todo | |
| ... | ... | ... | |

## Milestones
| Milestone | Target date | Status |
|-----------|-------------|--------|

## Acceptance Criteria
- <迭代级验收项>

## Non-Goals
- <明确排除的事项>

## Roadmap Position
- Current iteration: <what this iteration delivers>
- Next iteration: <what comes next, owner, trigger>

## Delivery Branch Policy

| Field | Value |
|-------|-------|
| iteration_base_branch | <branch-or-ref> |
| spec_integration_branch | iteration/<iteration-id> |
| target_branch | <PR target> |

1.4 更新索引

在 {ITERATION_DIR}/README.md 中添加一行（首次创建时建立表头；一行 = 一次迭代，不拆 compass/workspace 双行）：

Iteration	Path	Description	Status
<iteration-id>	[<iteration-id>/](/)	<简短描述>	active

1.5 登记到 status.json（formal iteration 必填）

iteration 正式全流程必须写入 {HARNESS_DIR}/status.json：

• root metadata.iteration_base_branch — 创建 spec_integration_branch 的祖先 ref（不是隐式 main）
• root metadata.target_branch — iteration-close 后 PR 的目标分支
• 各 plan metadata.iteration_refs、spec_integration_branch、merge_target（merge_target 通常为 spec_integration_branch）

compass frontmatter 的 iteration_base_branch / target_branch 必须与 status.json 一致；若仅写在 compass 而 status 缺失，§2.3 同轮 backfill。

1.5.5 产物边界（specs · iterations · knowledge）

Phase 1 与 §1.6 须遵守 references/iteration-artifact-boundaries.md（HARD）：

树	iteration-start 主责	说明
{SPECS_DIR}/	product-manager、architect	长期规范性产出：锁定规格、ADR、契约；plan primary_spec / spec_refs 主要挂此处
{ITERATION_DIR}/	product-manager、architect、PM	<iteration-id>/ package（delivery-compass.md + 迭代级 specs & guides）
{KNOWLEDGE_DIR}/	非 start/execute 直写；mstar-compound @ iteration-close（含 package 提升）	可复用实施 SSOT

禁止：product/architect 在 §1.6 向 {KNOWLEDGE_DIR}/ 新增；把迭代级草案写入 {SPECS_DIR}/（应进 <iteration-id>/specs/ 或 guides）。

1.6 Review & Edit chain（integration 分支前强制）

Phase 1 在 PM lock 前不算完成——compass/plans 初稿落盘 ≠ Done。

派发机制 → mstar-dispatch-gates（specialist review-and-edit dispatch，顺序链）。PM 不得将迭代 harness 文档 commit 到 spec_integration_branch，直到：

1. product-manager → architect → writing-specialist 已按序 invoke 编辑 compass、plans、{SPECS_DIR}/ 与 {ITERATION_DIR}/<iteration-id>/ package（guides/specs，按需）；不得在 start 链向 {KNOWLEDGE_DIR}/ 新增
2. writing-specialist 完成 corpus hygiene：全库 {SPECS_DIR}/ + 既有 {KNOWLEDGE_DIR}/ 卫生；错放迁回 <iteration-id>/ package；细则 → iteration-corpus-hygiene.md、iteration-artifact-boundaries.md
3. PM 将 compass status 设为 locked，并确认各 plan 的 Prepare gate（specify / clarify / plan）

顺序理由：产品范围与优先级 → 架构与长期契约（specs）→ 行文、规格库卫生与错放纠正（须在 PM/architect 定稿后扫全库 specs）。并行会导致后手重复劳动或覆盖前手未定稿内容。OpenCode：plain role id — mstar-host/references/opencode.md § Role-mention hygiene。

完成证据 = 磁盘上的 compass / plans / specs / iteration 文档修订 + specs（与既有 knowledge）卫生/归档（如有）+ 索引与 metadata 更新 + compass status: locked。不要求单独的迭代审查报告——迭代审查的 SSOT 是被编辑的文档本身，无 per-plan QC 式审计链。

反模式：PM 线程代替三角色完成全部编辑而不 invoke；或将本链三角色并行派发 —— 见 mstar-harness-core 反模式索引。

---

Phase 2: Autonomous Execute（per-plan 派发驱动）

本 Phase 是本 skill 的核心——定义 per-plan 派发循环的完整流程：前置条件检查、session todos、backlog 读取、integration 分支管理、per-plan dispatch 循环（分支→实现→QC→QA gate→Done→合并）、dispatch-first 约束、push 纪律。PM 读取本 Phase 即可执行迭代。

Findings cleanup（默认）：Phase 2 每个 plan Assignment 默认 Findings cleanup: zero-residual（可修 findings 当轮 fix→re-review 清干净；仅真 blocker-defer + Durable Roadmap 可留 open R#）。compass 或 Assignment 可显式覆写为 allow-residual。SSOT → mstar-plan-artifacts「Findings cleanup modes」。

2.0 前置条件（五道闸）

进入 Autonomous Execute 前必须满足：

1. {HARNESS_DIR}/status.json 中至少一条 plan status ≠ Done
2. Pre-implement gate = GO：plan 已 locked、tasks ready（见 mstar-phase-gates）
3. 用户意图为 continue Autonomous Execute（推进迭代 Execute、继续 per-plan 循环等）
4. Branch metadata gate：root metadata.iteration_base_branch、metadata.target_branch 已登记，且至少一条 active plan 有 metadata.spec_integration_branch（或可从 compass 同轮 backfill）。缺失 → STOP，不得用 main/master 补位。
5. Control-worktree + lease defaults（iteration 命令；可被 Worktree mode: waived 豁免）：除非本轮 Assignment 显式 Worktree mode: waived（或等价用户指令），Phase 2 必须在入口建立 control worktree、经 control 路径读写默认 gitignored 的 harness 进程产物（status.json、{PLAN_DIR}、{ITERATION_DIR}、{SDD_DIR} 等），并在可写派发前 claim plans[].execution_lease / integration_merge_lease。可写 Assignment 须含绝对 feature Worktree path + 绝对 control 系 Plan Path / SDD dir（见 mstar-branch-worktree「Harness path SSOT under default gitignore」）。禁止因 feature worktree 在默认 gitignore 下看不到 plans 而推断 Worktree mode: waived。Plan parallelism: serial 不 waive 本闸——仅强制跨 plan implement 串行调度；control worktree + lease 仍须满足。跨 plan 并行安全闸（不可被 Worktree mode: waived 豁免）：跨 plan 并行可写 implement 须满足下列之一——(a) coordination 路径（control 或 waived 时主 checkout {HARNESS_DIR}/status.json）上 same-host 独占写锁可用且每次 status/协调变更持锁；(b) 默认 Plan parallelism: serial（waived 时尤其优先默认串行；无 flock / 无共享锁时只触发本条，不豁免 worktree）；(c) 用户本轮显式 Cross-host lease race: accepted（或等价）+ plans[].notes 审计。禁止将 Worktree mode: waived 当作跨主机无锁并行的授权。细则 → references/phase-2-worktree-lease.md。

任一 false → stop。Phase 1 / Prepare 未完成 → 先完成 Phase 1 或 per-plan Prepare，再进入本 Phase。

2.1 Session todos（派发前设护栏）

每个 plan wave 启动前设定 host todos，防止范围漂移：

Host	工具	最小集合
Cursor	TodoWrite / CreatePlan todos	当前 plan_id；下一批 gates（implement/QC/QA gate）；分支 checkpoint；仅剩 1 个非 Done plan 时追加 phase-3-iteration-close（open 直至 §3.5）；Phase 4 后 phase-5-pr-merge-ready（open 直至 §5.5）
Codex	update_plan / Goal UI	同上
OpenCode	host todo/plan UI（如有）	同上

SSOT = {HARNESS_DIR}/status.json + {PLAN_DIR}/。todos 只追踪本轮下一步。

2.2 Read backlog

1. 读 mstar-plan-artifacts + {HARNESS_DIR}/status.json
2. 列出 status ∈ {Todo, InProgress, InReview, Blocked} 的 plan（优先级：InProgress → InReview → Todo → unblock Blocked）
3. 读 root metadata.iteration_base_branch / metadata.target_branch，以及 plan metadata.spec_integration_branch / merge_target / primary_spec 链接

2.3 Integration branch + control worktree（Phase 2 入口）

Metadata 解析顺序（任一环节缺失则 STOP，禁止默认 main/master）：

1. {HARNESS_DIR}/status.json → metadata.iteration_base_branch、metadata.target_branch；plan → metadata.spec_integration_branch
2. 若 (1) 缺字段 → 读当前迭代 compass frontmatter 同名键：优先 {ITERATION_DIR}/<iteration-id>/delivery-compass.md；若无则 legacy {ITERATION_DIR}/<iteration-id>-delivery-compass.md
3. 若 compass 有值而 status.json 无 → 同轮 backfill status.json
4. 仍缺 → 向用户确认 base / PR target；不得因 git symbolic-ref refs/remotes/origin/HEAD 指向 main 就自动采用
5. 所有参与本轮迭代的 active plan 必须解析到同一 spec_integration_branch；不一致 → STOP

Control worktree（§2.0 #5 未 waive 时 — HARD）：

1. 解析或创建 control worktree（通常 primary checkout 或 PM 指定路径），检出到上一步的 spec_integration_branch
2. git fetch（按需）；git branch --show-current 确认在 spec_integration_branch
3. 将规范绝对仓库根路径写入 control 副本 metadata.control_worktree_path（仓库根，非 {HARNESS_DIR} 子路径）
4. 此后 harness 进程产物 SSOT（默认 gitignored）均经 control 绝对路径解析：
   • <control_worktree_path>/{HARNESS_DIR}/status.json
   • <control_worktree_path>/{PLAN_DIR}/（主 plan）
   • <control_worktree_path>/{ITERATION_DIR}/（compass / iteration package）
   • <control_worktree_path>/{HARNESS_DIR}/sdd/<plan-id>/
   • 同树：notes.json、archived/（若使用） Feature worktree 只承载产品/源码编辑；其同名 {HARNESS_DIR} 不是 SSOT。Assignment Plan Path / SDD dir 须写 control 绝对路径。
5. 若 integration 分支尚不存在：在 control worktree 内 git checkout -b <spec_integration_branch> <iteration_base_branch>（必须从记录的 base 创建）

Git 操作（无 control worktree 时 — 仅 Worktree mode: waived）：

1. git fetch（按需）确认 iteration_base_branch 存在
2. checkout 或创建 spec_integration_branch（同上）
3. git branch --show-current 确认在 spec_integration_branch

spec_integration_branch 是本迭代内所有 plan feature branch 的 merge target。QC Review range / Diff basis 的 merge-base 参照优先用 metadata.target_branch（或 PM 书面指定的 base ref），禁止无 Assignment 依据写死 origin/main。

2.4 Per-plan loop（直到全部 Done）

跨 plan 默认（无论 Worktree mode: waived）：不同 plan_id 可并行 implement 须满足 §2.0 #5 跨 plan 并行安全闸——(a) coordination 路径 same-host 独占写锁可用且每次 status/协调变更持锁，或 (b) Plan parallelism: serial（waived 时默认），或 (c) 用户本轮 Cross-host lease race: accepted + audit notes；否则 Assignment 仍写并行 → Blocked。merge 入 spec_integration_branch 仍串行（metadata.integration_merge_lease；waived 时无 merge lease 仍须串行 merge）。未 waive 时 禁止无 verified execution_lease 的跨 plan 可写派发。

对每个本轮要推进的 active plan_id（可交错/并行，非强制 plan A 全 Done 再 plan B）：

1. Claim / resume — execution lease（§2.0 #5 未 waive）：
   • 自 control 路径 重读 status.json 定位 plan 行
   • 若已有 execution_lease 且 holder 等于本 session → resume：校验 worktree_path / working_branch 与 Assignment 一致后继续（不是 steal / Blocked）
   • 若 execution_lease 存在且 holder 不同 → Blocked
   • 若 status: InProgress 但 无 execution_lease → STOP 升级（孤儿状态恢复 → mstar-plan-artifacts；本 skill 不自行补 lease）
   • 否则按 references/phase-2-worktree-lease.md claim：Todo/Blocked → InProgress + 写入完整 execution_lease；verify 通过前 禁止可写派发
2. Plan start — feature worktree + branch：创建/校验 dedicated feature worktree；Assignment 须含绝对 Worktree path + Working branch（与 lease 一致）。plan 内多可写并行轨 → mstar-branch-worktree references/parallel-writable-pre-dispatch.md
3. Implement → InReview（§ 2.5；产品编辑在 feature worktree；plans / status / iterations / SDD 经 control 绝对路径）：
   • 默认 Execution mode: sdd（多 task plan；hotfix 可 inline）。
   • PM 载入 mstar-sdd 后，按 plan task 顺序 串行 per-task 循环（不是一次派发 dev 做全部 tasks）：
     1. sdd-workspace <plan-id> → {SDD_DIR}
     2. task-brief <plan-file> N → {SDD_DIR}/task-N-brief.md；记录 BASE_SHA
     3. Dispatch one implementer subagent（references/implementer-prompt.md：brief 路径 + report 路径 + Model tier；禁止贴整份 plan）
     4. Implementer DONE → review-package BASE HEAD → task diff 文件
     5. Dispatch one task reviewer subagent（brief + report + diff + Global Constraints）
     6. Fix loop 直至 review clean；append {SDD_DIR}/progress.md；更新 status.json / plan checkbox
     7. Next task
   • 每次 Completion Report v2 后更新 status.json + 主 plan
4. QC → QA gate（plan 保持 InReview；保留 execution_lease）：per-plan 审查链 → mstar-sdd（L1–L2）+ mstar-review-qc/references/review-responsibility-boundaries.md（L3 tri / inline 单席；raw reports in {SDD_DIR}/review/，durable summary in main plan/status）+ QA gate（mandatory → qa-engineer；pm-acceptance → PM checklist）。禁止在 integration merge 成功前设 Done 或删除 execution_lease。
5. Plan complete — serial merge back（§2.0 #5 未 waive）：自 control worktree claim/resume metadata.integration_merge_lease → 将 plan feature branch 合并入 spec_integration_branch（仅 merge-lease holder；细则 → references/phase-2-worktree-lease.md）→ 记录 merge commit 证据 → 释放 merge lease；同轮设 Done 并删除 execution_lease。merge 失败：保持 InReview + 保留 lease，不得标 Done。
6. Cross-plan 进度同步：更新 {ITERATION_DIR}/<iteration-id>/delivery-compass.md 的 ## Plans 表状态列
7. Next plan / parallel wave 从步骤 1 继续（可并行推进其他已 claim 的 plan；merge 仍排队串行）

全部 plan Done → Phase transition gate（见上文 Phase transition gates）：

1. STOP per-plan loop — 禁止 merge 后继续下一 plan、禁止开 PR、禁止会话结束语。
2. 打印 ## Phase 3: iteration-close。
3. 按 §3.0 起独立执行至 §3.5。final plan 的 Assignment / closure 仅作输入，不能替代 Phase 3 gate。

2.5 Dispatch-first（implement 派发约束）

派发纪律 SSOT → mstar-dispatch-gates · mstar-sdd · mstar-host/references/parallel-dispatch.md。

SDD implement（Phase 2 默认） — PM 已载入 mstar-sdd 后执行：

规则	说明
串行	同一 plan 内 one implementer at a time；每 task 后 one fresh task reviewer
Sticky（可选）	Assignment SDD implementer session: sticky + implementer-session.json；implementer resume，reviewer fresh — mstar-sdd/references/sticky-implementer-session.md
文件交接	brief / report / diff / progress.md 在 {SDD_DIR}；dispatch prompt 只给路径，不贴 plan 全文或 task 历史
Assignment 字段	每个 implement dispatch 须含 Execution mode: sdd、SDD dir、Model tier；§2.0 #5 未 waive 时还须含绝对 Worktree path + verified execution_lease；禁止省略 Model tier
大包 inline	禁止把 T1–Tn 或整份 plan 写进 一个 fullstack-dev leaf Assignment 冒充 SDD
分支 diff	全部 task 完成后 review-package MERGE_BASE HEAD → {SDD_DIR}/review/ branch diff → plan QC tri（N=3）

Iteration Phase 2 附加：

• PM NEVER 在 PM 线程实现产品代码（delegate dev；hotfix 例外见 mstar-phase-gates）
• Subagent invokes issued: 0 而 Assignment 已写出 → dispatch incomplete；下一条补发 invoke，禁止 PM 顶替
• QC 初轮：SDD → N=3；inline → N=1；plan QC tri 三席 同条消息 N=3（非 implement 轨数）
• Findings cleanup: zero-residual（默认）：QC 后可修 Warning/Suggestion → 继续 fix→targeted re-review，直至 clean Approve 或仅剩真 blocker-defer；禁止把可修项登记为 open residual 草草 Approve with residuals

2.6 Push 纪律（Autonomous Execute）

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 + status + execution_lease.working_branch（如适用）
• 跨 plan implement（无论 Worktree mode: waived）：并行可写 implement 须满足 §2.0 #5 跨 plan 并行安全闸——same-host 独占写锁 + 每次协调变更持锁，或默认 Plan parallelism: serial（waived 时尤其优先），或用户本轮 Cross-host lease race: accepted + audit notes；禁止将 waived 当作无锁跨主机并行授权；未 waive 时另须 verified execution_lease + feature worktree。integration merge 串行（integration_merge_lease 或 waived 下无 lease 仍须串行 merge）
• plan 内 SDD task 串行 — 见 §2.4、§2.5、mstar-sdd Continuous execution
• zero-residual（默认）：单 plan QC findings 尽量在当轮清干净；仅真 blocker 才 defer 到后续迭代（须 Durable Roadmap）— 见 mstar-plan-artifacts Findings cleanup modes

---

Phase 3: iteration-close（收口迭代）

PM 在迭代内全部 plan Done 后执行。本 Phase 在 integration 分支上运行，产出物 commit 到 integration 分支，随迭代 PR 合入 root metadata.target_branch。入口：Phase 2 全部 plan Done 后按 Phase transition gates 进入。

Close Done 定义：§3.1→§3.5 全部完成；compass frontmatter 写入 status: completed + end_date；每篇新增 knowledge doc 已登记 {KNOWLEDGE_DIR}/README.md。只在 final plan 中写了 compound / roadmap / PR 说明，不算 iteration-close 完成。

3.0 Phase boundary（HARD）

• Phase 3 是 iteration 级收口，不是任一 plan 的子任务。
• final plan closure、plan notes、plan compaction 可作为输入，但不能替代 §3.1→§3.5。
• 读过 mstar-iteration / mstar-compound 不等于执行 gate；必须打印 checklist 并写入产物。

3.0.5 Compass shape normalization（legacy 漂移修复）

进入 §3.1 前，先确认 compass 具有 close 可写入的结构。若缺失，PM 在本 thread 做最小规范化，不委派、不重写无关内容。

检查	缺则补齐
YAML frontmatter：iteration_id, start_date, status	从文件名 / 正文提取；收口前 status 保持 active 或 locked
## Roadmap Position	从 general context / roadmap prose 迁移为本节
## Quality Gate Summary	按模板补占位，§3.4 填写
## Compound Round Summary	按模板补占位，§3.4 填写
## Iteration Retrospective (minimal)	按模板补占位，§3.4 填写

正文 completion status 只能作为历史注释；最终状态必须写入 frontmatter status: completed + end_date。

3.1 Close entry checklist（HARD GATE）

STOP: 打印下方 checklist，且全部为 [x] 后，才可进入 §3.2 Compound。

• 所有 compass 中登记的 plan 在 {HARNESS_DIR}/status.json 均为 Done
• 所有 plan 的 residual findings 已收口：优先 empty open 列表；若仍有 open R#，须均为 Phase 2 zero-residual 允许的 blocker-defer + roadmap，或已 closed/accepted/waived 归档（见 mstar-plan-artifacts Findings cleanup modes）
• compass ## Plans 表状态列已与 status.json 同步
• 迭代 ## Acceptance Criteria 已达成或显式豁免（compass 或对话记录原因）
• compass shape 已满足（frontmatter + ## Roadmap Position + close 占位节）

PM 必须在对话中打印本 checklist；不得默认同过。

3.2 知识结晶（Compound）—— 迭代级核心收口

Compound 在此执行，不在 per-plan Done 后独立执行。 工作流 SSOT → mstar-compound（Q1–Q8 自检、Phase 1–7、Phase 6 索引登记强制）。

PM 批量触发后须：

1. 收集本迭代 plan 实现 / debug / review 素材，筛候选知识
2. 盘点 {ITERATION_DIR}/<iteration-id>/** package（guides/、specs/；默认排除 delivery-compass.md）— mstar-compound「Iteration package promotion」；提升值得保留者进 {KNOWLEDGE_DIR}/
3. 逐条过 mstar-compound 自检；跳过项记入 compass ## Compound Round Summary
4. 写入或更新 {KNOWLEDGE_DIR}/<category>/<slug>.md；新领域词更新 CONCEPTS.md
5. 每篇新 doc 完成 Phase 6（{KNOWLEDGE_DIR}/README.md 登记）

若无结晶且无 package 提升，仍在 ## Compound Round Summary 写明 无可结晶知识 / package 盘点结论及原因。

3.3 更新 roadmap

1. 更新 compass ## Roadmap Position（§3.0.5 已确保本节存在）：
   • current iteration 行标记为 delivered（或等价明确措辞）
   • next iteration 更新为即将开始的内容、触发条件、owner
2. 若 status.json 中有 plans[].metadata.roadmap 字段，同步更新
3. 若存在 deferred-features / roadmap tracker 类文档，按项目惯例刷新
4. 若 STRATEGY.md 存在，可更新 ## Decision Log（重大架构决策时）

3.4 标记迭代完成

1. compass YAML frontmatter：status: completed，end_date: YYYY-MM-DD（必须；见 §3.0.5）
2. 更新 {ITERATION_DIR}/README.md 索引中该迭代行 Status 为 completed
3. 填充 compass ## Quality Gate Summary、## Compound Round Summary 与 ## Iteration Retrospective (minimal)（见模板）

3.5 Close exit checklist + commit

Precondition: §3.1 checklist [x]；§3.4 frontmatter completed + end_date 已写。

PM 打印 iteration-close exit checklist；全部为 [x] 后方可 git commit；然后进入 Phase 4（§4）：

• §3.1 前置 gate 已打印并满足
• §3.2 compound 完成；<iteration-id>/ package 已盘点（提升 / 保留 / 跳过已记入 Compound Summary）；新增 knowledge doc 均已登记 {KNOWLEDGE_DIR}/README.md（或已记录无可结晶原因）
• §3.3 ## Roadmap Position current iteration 已标 delivered；tracker / STRATEGY 已按需更新
• §3.4 frontmatter status: completed + end_date；Quality Gate Summary + Compound Summary + Retrospective 已填
• 当前分支是 spec_integration_branch
• PR base = metadata.target_branch（与 compass frontmatter 一致）；不是未记录的 main

Commit 到 integration 分支：

git add {ITERATION_DIR}/<id>/ {ITERATION_DIR}/README.md {KNOWLEDGE_DIR}/ CONCEPTS.md
git commit -m "chore(iteration): close <iteration-id> — compound round, roadmap update"
git push origin <spec_integration_branch>

PR 目标使用 root metadata.target_branch；缺失时停止并补齐，不得默认 main。

3.6 可选：触发 compound-refresh

若本轮 compound 新增了较多知识文档，或 compass 标记了可能过时的旧知识，触发 mstar-compound-refresh 对有重叠的知识文档做维护。

---

Phase 4: PR delivery（开 PR）

Precondition: Phase 3 §3.5 exit 全 [x]；close commit 已 push 到 spec_integration_branch。

1. 打印 ## Phase 4: PR delivery
2. Resolve target：metadata.target_branch（compass frontmatter 镜像）；缺失 → STOP，问用户
3. 创建 PR：spec_integration_branch → target_branch
4. 记录 PR URL / number（Phase 5 会话 SSOT）
5. Immediately 进入 Phase 5 — Phase 4 exit ≠ 迭代交付完成

---

Phase 5: PR merge-ready loop

Precondition: Phase 4 PR 已创建且 head = spec_integration_branch。

Loop 理念（mstar SSOT）：PR 开完后进入 验证—修复—再验证 循环，直至 PR 可合并。与 Phase 2 per-plan loop 类似，但对象是 PR 级 merge 门禁（CI、review、冲突），不是 plan 实现。

5.0 Phase boundary

• Phase 5 在 PR head（spec_integration_branch）上 push 修复；禁止另开替代分支
• 产品代码修复 → PM dispatch dev/ops（mstar-dispatch-gates）；PM 线程不代写实现
• 禁止为「让 CI 变绿」而改 workflow，除非用户明确授权
• Push cadence → §5.1a（本地可提前修；禁止在 CI / AI review 波次未结束时 push）

5.1a Push cadence（HARD — 防打断 CI / AI review）

发现 CI 失败或 review 问题时，允许本地提前修（含 dispatch implement/ops、落盘 commit），但 git push（更新 PR head）必须等上一波次跑完。

允许	禁止
CI/review 进行中就开始本地诊断与修复	当前 head 上仍有 CI queued/in_progress，或 AI review 波次（Bugbot / Greptile / 等价 bot）未结束时 push
CI 全部结束后出现新的 review 评论 → 继续本地修，批完再 push	为「抢时间」在 CI 仍在跑时 push（会取消/孤儿化进行中的 CI 与 AI reviews，浪费 token 且无完整结果）
一批本地修复 合并为一次 push（本 head 波次 settled 后）	同一波次未 settled 就连续多次 push

Push gate（每次 push 前必须核对）：

1. 当前 PR head 的 required CI（及已启动的检查）均已 completed（success / failure / cancelled — 不得仍为 queued / in_progress）
2. 附着在该 head 的 AI / bot review 波次已跑完（无进行中的 review job；若宿主无法探测 job，则至少等 CI settled 且 review 评论不再增长一小段稳定窗口后再 push）
3. 仅当 1–2 满足 且本地仍有未推送修复时，才 push 一次
4. Push 后：等 新 head 的 CI + reviews 全部跑完 → 再决定下一轮本地修 / push

顺序记忆：observe findings → fix locally early → wait until CI + review wave idle → push batch → wait new wave → repeat。

5.1 Loop（repeat until §5.5 exit）

1. Status — PR mergeable？required CI？unresolved review threads？任一 CI/AI review 是否仍在跑？
2. Merge conflicts — blocking 则在 integration 分支本地解决；仅当 §5.1a push gate 满足时再 push（意图冲突 → Blocked）
3. Reviews — fetch unresolved threads；triage；dispatch 本地修复（可在上一波次仍在跑时开工）
4. CI — 失败项在 PR 范围内本地修复（可提前开工）；不在 CI 仍在跑时 push
5. Push — 仅当 §5.1a 满足：无 in-flight CI，上一波 CI 与 reviews 均已跑完 → 一次 push 本批修复
6. Review fix hygiene（每次因 review 而 push 后）：
   • 在同 thread comment（改动 + 验证）
   • Resolve when addressed
7. Return to step 1（CI 结束后若出现 新 reviews → 继续本地修，再等 idle 后 push）

Optional host helpers（command 层发现；非 mstar-* load order）：

Priority	Helper	When
1	babysit or any *-babysit skill（first readable SKILL.md）	Default prefer — CI green + reviews resolved loop
2	greploop	Optional — only when the repo uses Greptile / has greploop available; then run for Greptile 5/5 in addition to babysit/*-babysit (or fallback) gates
3	neither	Command fallback = babysit-equivalent CI + reviews gates

When both babysit/*-babysit and greploop apply: babysit/*-babysit first（CI + reviews），then optional greploop for Greptile score. Discovery paths → host commands/iteration-drive / iteration-loop Phase 5.

5.2 Phase 5 exit checklist（迭代交付完成）

打印 ## Phase 5 exit checklist；全 [x] 后方可宣称 迭代交付完成：

• PR mergeable（无 blocking merge conflicts）
• All required CI checks green on latest head
• All review threads resolved（或用户书面 waive 特定 thread）
• §5.1 review comment + resolve 已覆盖本轮所有 addressed feedback
• Host todo phase-5-pr-merge-ready 可勾选

PR merge 本身可仍由用户手动执行，除非 Assignment 明确授权 auto-merge。

---

迭代 compass 模板

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

与其它技能的关系

技能	关系
mstar-dispatch-gates	Dispatch rules — per-plan loop 引用
mstar-phase-gates	per-plan gate 判定
mstar-plan-conventions	路径符号（{ITERATION_DIR}、{HARNESS_DIR}）
mstar-plan-artifacts	status.json SSOT、{ITERATION_DIR} 索引维护
mstar-sdd	SDD implement 波次 — per-plan loop
mstar-review-qc	SDD 强制 plan QC tri — per-plan loop
mstar-branch-worktree	分支/merge/worktree 隔离
mstar-compound	iteration-close 中触发知识结晶（唯一默认 knowledge 新增路径）
mstar-compound-refresh	iteration-close 后可触发知识维护
references/iteration-artifact-boundaries.md	Phase 1 specs / iteration package / knowledge 分工
references/iteration-workspace-readme-template.md	<iteration-id>/README.md 可选模板（Documents 单表）
references/iteration-corpus-hygiene.md	§1.6 writing-specialist specs 卫生细则
references/autonomous-direction-lock.md	§1.2 autonomous direction lock、scale budget、branch resolve
references/phase-2-worktree-lease.md	Phase 2 control worktree、execution_lease、integration_merge_lease
mstar-strategy	iteration-start 时读 STRATEGY.md 对齐方向

NOT to do

• 不要在 per-plan Done 后立即单独 compound——等 iteration-close 统一做
• 不要在 Autonomous Execute（Phase 2）中修改 per-plan gate 判定
• 不要在 Phase 2 用 inline 大包 Assignment 替代 SDD per-task 循环（除非 plan 显式 Execution mode: inline / hotfix）
• 不要用 compass 替代 status.json 作为 plan 状态 SSOT
• 不要在没有完成 per-plan 前置检查的情况下进入 iteration-close
• 不要在缺少 iteration_base_branch / target_branch 时默认使用 main / master
• 不要将 Phase 3 折叠进 final plan closure——须显式 §3.0→§3.5
• 不要用 prose completion status 替代 compass frontmatter status: completed + end_date
• 不要跳过 compound Phase 6（{KNOWLEDGE_DIR}/README.md 索引）——即使只结晶一篇文档
• 不要跳过 compound——如果本迭代确实没有可结晶的知识，在 compass ## Compound Round Summary 写 无可结晶知识（原因：<简述>）
• 不要将 Phase 4 开 PR 等同于 迭代交付完成 — 必须完成 Phase 5 §5.5 merge-ready loop
• 不要在 Phase 5 于 CI 仍在跑或 AI review 波次未结束时 push（浪费 token、打断 review；§5.1a）— 本地可提前修，push 必须等 idle
• 不要在 iteration-start §1.6 由 product/architect 向 {KNOWLEDGE_DIR}/ 新增文档（知识 → iteration-close mstar-compound）
• 不要把迭代级草案写入 {SPECS_DIR}/（应进 {ITERATION_DIR}/<iteration-id>/specs/ 或 guides/）
• 不要在 iteration-close 跳过 <iteration-id>/ package 盘点（compound 提升 SSOT → mstar-compound）
• 不要新写根目录 <iteration-id>-delivery-compass.md（canonical：<iteration-id>/delivery-compass.md；legacy flat 仅兼容读）
• 不要在 {ITERATION_DIR}/README.md 为同一迭代登记 compass + workspace 双行（一行 = 一次迭代）
• 不要在 iteration-start §1.6 跳过 writing-specialist 全库 specs corpus hygiene（仅改当轮 compass/plans 而不扫 {SPECS_DIR}/）
• 不要在 SDD plan 上以单席 qc.md 收尾（除非用户书面 QC mode: single — override）
• 不要在未显式 Direction lock mode: autonomous 时跳过与用户收敛方向（interactive 仍为默认）
• 不要在 autonomous mode 下例行问用户「是否同意该方向」（须落盘 rationale；无候选且无约束时 STOP）
• 不要把 harness 流程（Review 链 / QC / QA / compound / close / PR 等）计进 Scale budget 的 plan 数量，也不得为此单独建 process plan 占坑
• 不要在 Phase 2 无 verified execution_lease 就做可写 implement 派发（resume 仅限同 holder verify-held-lease）
• 不要 steal / 覆盖他人 execution_lease 或 integration_merge_lease（除非用户本轮显式 override + audit notes）
• 不要从 feature worktree 的 {HARNESS_DIR} 路径当作 plans / status / iterations / SDD SSOT（control worktree 绝对路径为准；默认 gitignore 下 feature 缺 plans 不得推断 Worktree mode: waived）
• 不要把「无 flock」与「gitignore / feature 缺 plans」捆成一次 waive（无锁 → Plan parallelism: serial only；gitignore → control-path harness）
• 不要并行 merge 入 spec_integration_branch（merge 必须经 integration_merge_lease 串行）