| 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 收集上下文
- 读
{ITERATION_DIR}/README.md（若存在），了解历史迭代
- 读
STRATEGY.md（若存在），对齐战略方向（见 mstar-strategy）
- 如果有未完成的 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，直到：
- product-manager → architect → writing-specialist 已按序 invoke 编辑 compass、plans、
{SPECS_DIR}/ 与 {ITERATION_DIR}/<iteration-id>/ package（guides/specs，按需）；不得在 start 链向 {KNOWLEDGE_DIR}/ 新增
- writing-specialist 完成 corpus hygiene：全库
{SPECS_DIR}/ + 既有 {KNOWLEDGE_DIR}/ 卫生；错放迁回 <iteration-id>/ package；细则 → iteration-corpus-hygiene.md、iteration-artifact-boundaries.md
- 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 前必须满足：
{HARNESS_DIR}/status.json 中至少一条 plan status ≠ Done- Pre-implement gate = GO：plan 已 locked、tasks ready（见
mstar-phase-gates）
- 用户意图为 continue Autonomous Execute（推进迭代 Execute、继续 per-plan 循环等）
- Branch metadata gate：root
metadata.iteration_base_branch、metadata.target_branch 已登记，且至少一条 active plan 有 metadata.spec_integration_branch（或可从 compass 同轮 backfill）。缺失 → STOP，不得用 main/master 补位。
- 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
- 读
mstar-plan-artifacts + {HARNESS_DIR}/status.json
- 列出
status ∈ {Todo, InProgress, InReview, Blocked} 的 plan（优先级：InProgress → InReview → Todo → unblock Blocked）
- 读 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）：
{HARNESS_DIR}/status.json → metadata.iteration_base_branch、metadata.target_branch；plan → metadata.spec_integration_branch- 若 (1) 缺字段 → 读当前迭代 compass frontmatter 同名键：优先
{ITERATION_DIR}/<iteration-id>/delivery-compass.md；若无则 legacy {ITERATION_DIR}/<iteration-id>-delivery-compass.md
- 若 compass 有值而
status.json 无 → 同轮 backfill status.json
- 仍缺 → 向用户确认 base / PR target；不得因
git symbolic-ref refs/remotes/origin/HEAD 指向 main 就自动采用
- 所有参与本轮迭代的 active plan 必须解析到同一
spec_integration_branch；不一致 → STOP
Control worktree（§2.0 #5 未 waive 时 — HARD）：
- 解析或创建 control worktree（通常 primary checkout 或 PM 指定路径），检出到上一步的
spec_integration_branch
git fetch（按需）；git branch --show-current 确认在 spec_integration_branch- 将规范绝对仓库根路径写入 control 副本
metadata.control_worktree_path（仓库根，非 {HARNESS_DIR} 子路径）
- 此后 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 绝对路径。
- 若 integration 分支尚不存在：在 control worktree 内
git checkout -b <spec_integration_branch> <iteration_base_branch>（必须从记录的 base 创建）
Git 操作（无 control worktree 时 — 仅 Worktree mode: waived）：
git fetch（按需）确认 iteration_base_branch 存在- checkout 或创建
spec_integration_branch（同上）
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）：
- 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 通过前 禁止可写派发
- Plan start — feature worktree + branch：创建/校验 dedicated feature worktree；Assignment 须含绝对
Worktree path + Working branch（与 lease 一致）。plan 内多可写并行轨 → mstar-branch-worktree references/parallel-writable-pre-dispatch.md
- 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）：
sdd-workspace <plan-id> → {SDD_DIR}task-brief <plan-file> N → {SDD_DIR}/task-N-brief.md；记录 BASE_SHA- Dispatch one implementer subagent（
references/implementer-prompt.md：brief 路径 + report 路径 + Model tier；禁止贴整份 plan）
- Implementer
DONE → review-package BASE HEAD → task diff 文件
- Dispatch one task reviewer subagent（brief + report + diff + Global Constraints）
- Fix loop 直至 review clean；append
{SDD_DIR}/progress.md；更新 status.json / plan checkbox
- Next task
- 每次 Completion Report v2 后更新
status.json + 主 plan
- 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。
- 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。
- Cross-plan 进度同步：更新
{ITERATION_DIR}/<iteration-id>/delivery-compass.md 的 ## Plans 表状态列
- Next plan / parallel wave 从步骤 1 继续（可并行推进其他已 claim 的 plan；merge 仍排队串行）
全部 plan Done → Phase transition gate（见上文 Phase transition gates）：
- STOP per-plan loop — 禁止 merge 后继续下一 plan、禁止开 PR、禁止会话结束语。
- 打印
## Phase 3: iteration-close。
- 按 §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。
PM 必须在对话中打印本 checklist；不得默认同过。
3.2 知识结晶（Compound）—— 迭代级核心收口
Compound 在此执行，不在 per-plan Done 后独立执行。 工作流 SSOT → mstar-compound（Q1–Q8 自检、Phase 1–7、Phase 6 索引登记强制）。
PM 批量触发后须：
- 收集本迭代 plan 实现 / debug / review 素材，筛候选知识
- 盘点
{ITERATION_DIR}/<iteration-id>/** package（guides/、specs/；默认排除 delivery-compass.md）— mstar-compound「Iteration package promotion」；提升值得保留者进 {KNOWLEDGE_DIR}/
- 逐条过
mstar-compound 自检；跳过项记入 compass ## Compound Round Summary
- 写入或更新
{KNOWLEDGE_DIR}/<category>/<slug>.md；新领域词更新 CONCEPTS.md
- 每篇新 doc 完成 Phase 6（
{KNOWLEDGE_DIR}/README.md 登记）
若无结晶且无 package 提升，仍在 ## Compound Round Summary 写明 无可结晶知识 / package 盘点结论及原因。
3.3 更新 roadmap
- 更新 compass
## Roadmap Position（§3.0.5 已确保本节存在）：
- current iteration 行标记为
delivered（或等价明确措辞）
- next iteration 更新为即将开始的内容、触发条件、owner
- 若
status.json 中有 plans[].metadata.roadmap 字段，同步更新
- 若存在 deferred-features / roadmap tracker 类文档，按项目惯例刷新
- 若
STRATEGY.md 存在，可更新 ## Decision Log（重大架构决策时）
3.4 标记迭代完成
- compass YAML frontmatter：
status: completed，end_date: YYYY-MM-DD（必须；见 §3.0.5）
- 更新
{ITERATION_DIR}/README.md 索引中该迭代行 Status 为 completed
- 填充 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）：
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。
- 打印
## Phase 4: PR delivery
- Resolve target：
metadata.target_branch（compass frontmatter 镜像）；缺失 → STOP，问用户
- 创建 PR：
spec_integration_branch → target_branch
- 记录 PR URL / number（Phase 5 会话 SSOT）
- 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 前必须核对）：
- 当前 PR head 的 required CI（及已启动的检查）均已 completed（success / failure / cancelled — 不得仍为 queued / in_progress）
- 附着在该 head 的 AI / bot review 波次已跑完（无进行中的 review job；若宿主无法探测 job，则至少等 CI settled 且 review 评论不再增长一小段稳定窗口后再 push）
- 仅当 1–2 满足 且本地仍有未推送修复时，才 push 一次
- 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）
- Status — PR mergeable？required CI？unresolved review threads？任一 CI/AI review 是否仍在跑？
- Merge conflicts — blocking 则在 integration 分支本地解决；仅当 §5.1a push gate 满足时再 push（意图冲突 → Blocked）
- Reviews — fetch unresolved threads；triage；dispatch 本地修复（可在上一波次仍在跑时开工）
- CI — 失败项在 PR 范围内本地修复（可提前开工）；不在 CI 仍在跑时 push
- Push — 仅当 §5.1a 满足：无 in-flight CI，上一波 CI 与 reviews 均已跑完 → 一次 push 本批修复
- Review fix hygiene（每次因 review 而 push 后）：
- 在同 thread comment（改动 + 验证）
- Resolve when addressed
- 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 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 串行）
