@playcraft/cli 0.0.57 → 0.0.58

package/project-template-v2/docs/harness/iteration-2/ideate-flow.md

@@ -0,0 +1,267 @@
+# 迭代2 · ideate flow(玩法包装创意)
+
+> 阶段执行序文档。角色:game-designer。被 `pipeline/iteration-2-wrap.mjs` 的 `ideate.flowRef` 引用,派发时给路径不复述。
+
+## 目标
+
+ideate 是迭代2的第一个阶段。它不是固定做“再写一版包装”,而是先判断本轮为什么进入迭代2,再选择完全不同的文档扩充方式。
+
+### 路径 A:包装构建
+
+适用状态:迭代1核心玩法已经做完 / 已确认,但还没有形成完整 playable 包装。
+
+目标:把核心动作升级成完整短时体验,补齐玩家第一眼为什么行动、关卡如何递进、引导如何让玩家自然完成第一步、成功 / 失败如何形成有趣反馈和下一步动机。
+
+设计策略:偏发散和补全。允许基于已有 brief / design 做合理推断,但不能改坏迭代1确认的核心动作和胜负语义。
+
+### 路径 B:目标优化
+
+适用状态:已经执行过一轮包装 / 实现 / 验证,现在带着用户输入、录像反馈、handoff 或当前文件状态继续优化。
+
+目标:确认新信息影响了什么,把用户输入或执行反馈收敛成明确的设计修正。此时不是重做一套包装,而是更新既有包装目标、边界和取舍。
+
+设计策略:偏确认和收敛。先判断用户信息是在确认原方向、要求局部优化,还是改变包装 / 关卡 / 引导 / 成功失败方向;再改文档。
+
+game-designer 必须在 handoff 中说明本轮采用路径 A 还是路径 B,依据是什么。如无法判断,提出推荐判断和问题,由调度者区分“可自行结论”还是真实用户确认。
+
+## 共同输入
+
+- `docs/design.md` — 迭代1核心玩法设计;本阶段只迭代原文件,不创建 v2 / v3 设计文件。
+- `docs/design-brief.md` — 过程日志;本阶段继续追加包装探索、用户输入、取舍来源。
+- `docs-last/` — 如需查看进入迭代2前的历史文档,从这里读取;它由调度者维护,game-designer 不创建、不覆盖。
+- 当前 `game/**` — 用来判断核心玩法是否已完成、包装是否已执行过一轮;ideate 阶段不改代码。
+- 最近 handoff / 录像证据(如存在) — 用来判断上一轮实际完成度、用户反馈和待优化目标。
+
+## 共同入口判定
+
+1. 读取用户最新输入、`docs/design.md`、`docs/design-brief.md`、当前 `game/**`、最近 handoff / 录像证据。
+2. 判断进入路径:
+   - 选路径 A:核心玩法成立,但 hook、关卡、引导、成功 / 失败、完整体验流程还没有被包装成完整 playable。
+   - 选路径 B:已有一轮包装 / 实现 / 验证结果,现在需要根据用户输入或当前结果继续修正目标。
+3. 在 `docs/design-brief.md` 追加 `Iteration 2 Entry Decision`,记录:
+   - `Entry Mode` — `Packaging Build` 或 `Target Optimization`。
+   - `Evidence` — 来自 design、brief、game、handoff、录像或用户输入的依据。
+   - `User Signal` — 是否有用户输入;如有,标 `[USER]` 并记录影响范围。
+   - `Open Question` — 如有问题,写推荐判断和为什么不能从当前资料直接确定。
+
+## 路径 A:包装构建流程
+
+### 1. 读取包装线索
+
+- 从 `docs/design-brief.md` 中抽取 hook、玩家情绪、广告动机、可用题材线索。
+- 从 `docs/design.md` 中确认迭代1核心玩法边界:核心动作、胜负语义、节奏、引导、当前成功 / 失败定义。
+- 参考迭代1已经做过的 Core Loop / Layout / Pacing / Win-Lose / Synergy / Visuals+Engine signals / Tutorial,以及爽感放大 / 差异机制 / 情绪曲线 / 视觉辨识等维度;不要默认重问同一批问题。
+
+### 2. 找包装缺口
+
+至少确认以下缺口:
+
+**Hook 心理机制**
+
+- 包装 hook:玩家第一眼看到什么,为什么愿意立刻操作。
+- hook 触发类型:本游戏适合哪种认知触发机制 —— Challenge Hook（展示 near-fail 状态触发 Cognitive Closure）/ Fail & Fix（先演失败再演正确操作）/ Sensory Impact（高饱和+动态粒子+即时音效叠加）/ Identity Hook（"你能通过这关吗"触发 Winner / Not-a-Loser 身份认同）;不要只写视觉描述,要说明触发机制。
+- 玩家身份心理:本游戏在 15-45 秒内主要激活哪种身份心理 —— Winner（需明显进度感/快速正反馈）/ Not-a-Loser（near-win 是主动力,失败应可重试）/ Unique（发现隐藏路径或特殊连锁）/ In-Control（策略选择/风险-奖励可见）;至少需要激活 1 种,主次都要说明。
+
+**包装规则与叙事**
+
+- 包装规则:成功 / 失败的完整玩法规则如何被包装;核心玩法、副玩法是否需要包装;整体故事背景和信息是否需要二次包装。
+- 包装叙事与情绪弧线:15-45 秒内玩家为什么在意,情绪如何推进。
+
+**关卡地图设计**
+
+- 关卡补充:是否有 first win、节奏递进、失败风险、目标变化。
+- 关卡意图:每个展示关卡教什么、验证什么、制造什么挑战或 near-win。
+- 空间结构可读性:目标区 / 危险区 / 操作区是否一眼可区分;布局是否避免视觉死角或错误引导;第一次尝试是否有合理成功空间。
+- 节奏分段:每关内的张弛节奏是否被刻意设计;15-45 秒内是否有至少 1 个明确的高潮帧(near-win 或 climax);高潮帧的位置和触发条件。
+- 递进梯度:关卡 1 → N 引入了哪些新变量(新障碍类型/速度/空间收窄);每个新变量是否有 Learn → Play → Challenge 的安全环境过渡;playable ad 通常只有 2-3 关,梯度要压缩但仍可感知。
+- 风险-奖励路径:是否存在多条通关路径(高风险高收益 vs 保守路线);高风险路径的收益信号是否玩家可读;做对了是否能感受到"我发现了更好的打法"。
+- 关卡差异化:每关是否有视觉或机制上的明显区别(防止第 2 关感觉与第 1 关相同而退出);是否有至少 1 个"只在这关出现"的特殊元素。
+- 完成信号:每关的结束信号是否清晰;关卡间过渡时长是否 ≤ 1s;最后展示关卡是否有刻意设计的 cliffhanger 或"想看更多"动机。
+
+**引导与反馈**
+
+- 引导补充:第一屏提示、首个动作引导、停滞提示、错误恢复是否足够。
+- 成功 / 失败升级:胜利反馈、失败反馈、趣味来源、情绪曲线、endcard 前状态是否完整。
+- 核心动作反馈规格:为核心动作定义反馈意图而非实现方案 —— 即时视觉信号(闪光/粒子/形变的强度描述)、音效匹配描述(何种声音对应何种动作结果)、强度时刻(什么情况下需要 screen shake / hit stop / slow-mo);没有反馈规格,developer 只能功能正确但无 feel。
+
+**布局与可读性**
+
+- 布局与可读性:玩家一眼能否看出目标、可操作对象、风险、进度。
+
+### 3. 扩充 `docs/design.md`
+
+在原文件中追加或更新独立章节:
+
+```markdown
+## 迭代2:玩法包装升级
+
+### 进入路径
+
+{Packaging Build;为什么判断核心玩法已可进入包装构建}
+
+### 包装 hook
+
+{玩家第一眼看到什么,为什么愿意立刻操作,它如何不改变基础核心动作}
+
+### Hook 心理机制
+
+{本游戏采用哪种 Hook 触发类型(Challenge Hook / Fail & Fix / Sensory Impact / Identity Hook);激活哪种玩家身份心理(Winner / Not-a-Loser / Unique / In-Control);为什么这种机制适合本游戏的核心动作}
+
+### 包装
+
+{成功 / 失败规则的包装方式;核心玩法、副玩法是否包装;故事背景和信息是否二次包装}
+
+### 关卡地图设计
+
+{每关的空间结构:目标区/危险区/操作区布局描述;节奏分段:张弛节奏和高潮帧位置;递进梯度:关卡 1→N 引入的新变量和 Learn→Challenge 过渡;风险-奖励路径:是否存在多路径选择;关卡差异化:每关的视觉/机制区别标志;完成信号:结束是否清晰、最后关卡的 cliffhanger}
+
+### 关卡补充
+
+{first win 关卡、节奏递进、失败风险、关卡内玩家看到的目标变化}
+
+### 关卡意图
+
+{每个展示关卡教什么、验证什么、制造什么挑战或 near-win}
+
+### 核心动作反馈规格
+
+{核心动作的即时视觉信号描述(闪光/粒子/形变强度);音效匹配意图(何种声音对应何种结果);强度时刻(何时需要 screen shake / hit stop / slow-mo);成功反馈与失败反馈的情绪对比;不写具体实现参数,只定义反馈意图}
+
+### 引导补充
+
+{第一屏提示、首个动作引导、停滞提示、错误恢复}
+
+### 成功 / 失败升级
+
+{胜利反馈、失败反馈、趣味来源、情绪曲线、是否进入 endcard 前状态}
+
+### 布局与可读性意图
+
+{屏幕主要区域如何服务目标、操作、风险、进度;不写具体实现路径}
+
+### 完整体验流程
+
+{Hook → Tutorial → Gameplay → EndCard 的时间线;玩家看到什么、做什么、情绪如何过渡;各阶段进入条件和退出触发(例如:Tutorial 完成首个动作后自动进入 Gameplay;Win 后 X 秒自动进入 EndCard)}
+
+### 包装叙事与情绪弧线
+
+{Narrative Level / Emotional Arc:玩家为什么在意、15-45 秒内情绪如何被推进}
+
+### 与基础玩法的边界
+
+{保留哪些迭代1核心动作 / 规则 / 胜负底层语义;哪些是包装层改动}
+```
+
+### 4. 扩充 `docs/design-brief.md`
+
+追加 `Iteration 2 Packaging Build Log`:
+
+- `Packaging Signals` — 从原 brief / design / game 状态读到的线索。
+- `Packaging Gaps` — 本次识别到的包装缺口。
+- `Decisions` — 本次确认的包装、关卡、引导、成功 / 失败改动。
+- `Rejected / Deferred` — 明确不做或留到后续的内容。
+- `Questions For Orchestrator` — 如有问题,写推荐判断和影响范围。
+
+## 路径 B:目标优化流程
+
+### 1. 确认新信息
+
+- 读取用户输入、handoff、录像观察、当前 game 状态和已有 design / brief。
+- 判断新信息类型:
+  - `confirm` — 用户或结果确认原包装方向。
+  - `tune` — 只要求局部优化,例如节奏、引导、反馈强度、关卡表达。
+  - `change` — 改变包装方向、关卡目标、引导方式、成功 / 失败表达或核心玩法边界。
+  - `unclear` — 用户信息不足以判断,需要调度者结论或真实用户确认。
+
+### 2. 归纳目标差异
+
+目标优化不重新拆 context TODO,但必须说明设计目标如何变化:
+
+- 原设计哪些保持不变。
+- 用户输入或执行结果要求改什么。
+- 改动属于包装、关卡、引导、成功 / 失败、节奏、视觉可读性还是基础玩法边界。
+- 哪些问题是设计目标变化,哪些只是后续 context / generate / optimize 的实现问题。
+- 如果用户输入与原设计冲突,以用户为准,并记录取舍原因。
+
+### 3. 更新 `docs/design.md`
+
+在原“迭代2:玩法包装升级”章节中追加或更新 `目标优化记录`。不要重写成另一套完整方案,除非用户输入明确要求改变方向。
+
+```markdown
+### 目标优化记录
+
+{Target Optimization;本轮优化来源:用户输入 / 录像反馈 / handoff / 当前实现状态}
+
+#### 本轮修正
+
+{需要修改的包装目标、关卡意图、引导、成功 / 失败、节奏或可读性}
+
+#### 用户输入处理
+
+{用户输入如何被解释;哪些直接生效;哪些由调度者自行结论或等待真实用户确认}
+
+#### 设计边界
+
+{哪些不能改;哪些允许进入 context / generate 形成任务}
+```
+
+如果目标优化发现原“迭代2:玩法包装升级”章节缺失必要信息,只补缺失小节,并在 `目标优化记录` 说明为什么补。
+
+### 4. 扩充 `docs/design-brief.md`
+
+追加 `Iteration 2 Target Optimization Log`:
+
+- `Incoming Signal` — 用户输入、录像反馈、handoff 或当前状态摘要。
+- `Signal Type` — `confirm` / `tune` / `change` / `unclear`。
+- `Impact` — 影响包装、关卡、引导、成功 / 失败、节奏、可读性或核心玩法边界的哪一部分。
+- `Decision` — 采用的设计修正;如以用户为准,标 `[USER]`。
+- `Kept` — 明确保持不变的设计。
+- `Question For Orchestrator` — 如有问题,写推荐判断、影响范围、是否建议真实用户确认。
+
+## 问题与确认
+
+game-designer 可以提出问题,handoff 必须写清:
+
+- 问题是什么。
+- 推荐判断是什么。
+- 影响范围是什么。
+- 为什么无法从现有文档、用户输入、game 状态或录像证据中直接确定。
+
+handoff 示例:
+
+```bash
+npm run handoff:append -- role=game-designer \
+  status=awaiting_user_input \
+  summary="Needs orchestrator decision for iteration-2 ideate" \
+  artifactRefs="docs/design.md;docs/design-brief.md" \
+  blockers="decision-needed:<question-id>" \
+  pendingUserInput='{"status":"awaiting_user_input","id":"<question-id>","prompt":"<question>","options":[{"label":"<option>","description":"<impact>"}],"recommended":"<recommended>","impact":"<why it matters>"}'
+```
+
+结论明确后,需设置 `userConfirm=confirmed`。
+
+## 产出物
+
+- `docs/design.md` — 原文件迭代。路径 A 新增 / 更新“迭代2:玩法包装升级”;路径 B 新增 / 更新“目标优化记录”并按需修正相关小节。
+- `docs/design-brief.md` — 原 brief 继续追加。路径 A 写 `Iteration 2 Packaging Build Log`;路径 B 写 `Iteration 2 Target Optimization Log`。
+
+## 评价(退出判据)
+
+对应 spec `ideate.exit`:
+
+- 已明确本轮采用路径 A 包装构建或路径 B 目标优化,并在 brief / handoff 中写明依据。
+- 路径 A: `docs/design.md` 补齐 hook、包装、关卡补充、关卡意图、引导、成功 / 失败升级、布局可读性、完整体验流程、包装叙事和基础玩法边界。
+- 路径 B: `docs/design.md` 明确保持不变项、本轮修正项、用户输入处理和设计边界;没有无依据重写整套包装。
+- `docs/design-brief.md` 记录本阶段新增判断;如有用户输入影响玩法,以 `[USER]` 来源记录并优先生效。
+- 成功 / 失败不只是条件,还说明反馈、趣味、情绪和下一步动机;若目标优化不触碰成功 / 失败,需说明保持不变。
+- 如当前信息不足且不能合理默认,已通过 handoff 明确待确认问题、推荐判断和影响范围;调度者已区分为自行结论或真实用户确认。
+- 调度者确认本阶段可进入 context,并设置 `pipeline.userConfirm=confirmed`。
+
+## 反模式
+
+- 不判断进入路径,直接套用同一套包装步骤。
+- 路径 A 只写包装主题,不补关卡、引导、成功 / 失败。
+- 路径 B 把用户反馈当成重新发散理由,无依据重写整套设计。
+- 创建 `design_v2.md` / `design_v3.md` 等新设计文件。
+- 在 ideate 阶段执行 docs 快照覆盖,或把 context 阶段的差异拆 TODO 提前塞进设计师任务。
+- 有用户输入但 brief 不记录,或与用户输入相冲突。

package/project-template-v2/docs/harness/iteration-2/optimize-flow.md

@@ -0,0 +1,164 @@
+# 迭代2 · optimize flow(完整游戏优化)
+
+> 阶段执行序文档。角色:developer。被 `pipeline/iteration-2-wrap.mjs` 的 `optimize.flowRef` 引用。
+
+## 目标
+
+optimize 阶段验证并修正迭代2包装后的完整游戏体验。它承接 generate 已落地的任务卡,不重新设计、不新增包装方向。
+
+本阶段做两类确认:
+
+- **实现一致性** — 已完成内容是否遵守 `docs/todo_list.md` 中每个迭代2任务卡的 Work / Context / Reference / Implementation Notes。
+- **完整游戏质量** — build、contract、first win、fusion、autoplay、record 通过后,录像能证明包装后的 playable 清晰、有趣、可完成。
+
+## 输入
+
+- `docs/todo_list.md` — 迭代2任务卡、差异覆盖矩阵、TODO 历史总览。
+- `docs/design.md` — 迭代2包装构建或目标优化设计。
+- `docs/design-brief.md` — 迭代2路径、用户输入、设计取舍。
+- 当前 `game/**` / `assets/**` — generate 已实现内容。
+- validate / recordings 目录 — 本阶段产出的验证证据。
+
+## 关键步骤
+
+### 1. 回读任务卡和路径
+
+- 确认本轮是 `Packaging Build` 还是 `Target Optimization`。
+- 回读所有迭代2 done todo 的任务卡,抽取:
+  - Work 是否都已落地。
+  - Context.Keep 是否应保持。
+  - Reference / Implementation Notes 是否有必须遵守的 API (Application Programming Interface, 应用程序编程接口)、event、config、asset binding。
+- 如果发现实现与任务卡冲突,先按任务卡修正;如果任务卡本身与 design 冲突,STOP 写 blocker 回 context / ideate,不要在 optimize 重新设计。
+
+### 2. build 与接线修复
+
+运行:
+
+```bash
+npm run build
+```
+
+只修复构建、资源链路、事件接线、类型错误或包装接线问题。不得借修错重写玩法目标。
+
+### 3. 合约与 first win
+
+运行:
+
+```bash
+npm run verify:contract
+npm run verify:firstwin
+npm run verify:lifecycle
+```
+
+检查重点:
+
+- playable runtime 合约不破。
+- first win 仍可达。
+- `verify:lifecycle` 确认 phase path 从 HOOK 出发并经过连续阶段到达 ENDCARD,中间不跳过;如果 phasePath 缺失 TUTORIAL 或 WIN/FAIL,说明状态机骨架不完整,路由回 generate 修复 `packaging-scene-fsm`。
+- `Packaging Build` 路径: first win 应经过迭代2新增或确认的 hook / 引导 / 成功反馈。
+- `Target Optimization` 路径: first win 不应被本轮局部修正破坏;若本轮目标影响 first win,必须能看到对应修正。
+
+### 4. fusion 检查
+
+运行:
+
+```bash
+npm run verify:fusion
+```
+
+如果 fusion 对本项目是 no-op,在 handoff 中明确说明 no-op 原因。
+
+### 5. autoplay 与录像
+
+- 确认 autoplay 能完整演示包装后的游戏路径。
+- 运行:
+
+```bash
+npm run record:mp4
+```
+
+录像目的不是证明某个按钮能点,而是证明完整 playable 成立。
+
+### 6. 完整游戏评价
+
+按现有 verify 脚本和 project-template 验证标准判断,不要发明另一套孤立检查。
+
+视频分段检查:
+
+| segment  | 检查重点                                             |
+| -------- | ---------------------------------------------------- |
+| HOOK     | 0-3s 目标是否清晰,无空白 / 占位 / 错位               |
+| TUTORIAL | 3-8s 首步引导是否可见、可执行                        |
+| GAMEPLAY | 核心操作是否有效,反馈是否有趣,失败 / 风险是否可读    |
+| ENDCARD  | 成功 / 失败后的 CTA 前状态是否清楚,CTA 不被 HUD 抢戏 |
+
+完整游戏 8 角度评价（每角度失败时的 routeTo）:
+
+| 角度               | 检查重点                                                                         | 失败时 routeTo                                  |
+| ------------------ | -------------------------------------------------------------------------------- | ----------------------------------------------- |
+| MDA / Mechanics    | 规则、可做 / 不可做动作清楚                                                      | generate(对应功能 todo)                         |
+| MDA / Dynamics     | 连续操作后的节奏、风险、反馈循环成立                                             | generate(重写或优化 todo)                       |
+| MDA / Aesthetics   | 情绪来源明确,不只写”好玩”;hook 触发机制是否在录像中可感知                        | ideate(路径 B 目标优化)                         |
+| Game Feel / Juice  | 输入、成功、失败反馈有强度;核心动作反馈与 ideate 定义的规格基本一致              | generate(反馈引擎 todo 或对应功能 todo)         |
+| Visual Readability | 目标、可操作对象、风险、进度一眼可读;引导层不遮挡游戏内容                        | generate(分层渲染架构 todo 或引导 todo)         |
+| Level Progression  | first win、教学点、挑战点、near-win 或高潮帧明确;关卡差异化可感知                | generate(关卡 todo) 或 ideate(关卡地图设计缺口) |
+| Playable Ad Flow   | Hook → Tutorial → Gameplay → EndCard 短时闭环成立;lifecycle phasePath 完整无跳跃 | generate(packaging-scene-fsm 修复)              |
+| Data Derivation    | 没有从数据结构反推玩法;数据只服务设计                                            | generate(对应 todo)                             |
+
+路径差异:
+
+- `Packaging Build` — 重点确认包装层把基础玩法补成完整游戏;8 角度都要评价。
+- `Target Optimization` — 重点确认用户输入 / 执行反馈影响的目标已被修正,且未引入无关变化;只评价受影响角度,其余标注”unchanged”。
+
+### 7. DoD (Definition of Done, 完成定义) 检查
+
+运行:
+
+```bash
+npm run dod:check
+```
+
+无脚本 DoD 由调度者明确写入 `gate.stageDoD`。若某项失败,按失败类型路由:
+
+- 构建 / 合约 / 资源链路问题:留在 optimize 修复。
+- 单个任务卡实现缺失:回 generate 补对应 todo 或追加本阶段范围内 todo。
+- 设计目标冲突或用户信息不足:回 ideate / context,不要在 optimize 直接改设计。
+
+## handoff
+
+handoff 应记录:
+
+- build / contract / first win / lifecycle / fusion / autoplay / record 结果。
+- lifecycle phasePath 完整路径(HOOK → … → ENDCARD)。
+- 录像路径和关键观察。
+- 包装构建或目标优化的完整游戏评价摘要(8 角度每项 pass / fail / unchanged,fail 时写 routeTo)。
+- 如有失败,写明 routeTo: optimize / generate / context / ideate。
+
+## 产出物
+
+- `game/**` / `assets/**` — 修复后的完整包装版本。
+- `recordings/*.mp4` 或实际 record 输出路径 — 录像证据。
+- `validate/**` — 校验报告 / 证据,按实际脚本输出。
+- handoff — 验证结果、录像观察、路由建议。
+
+## 评价(退出判据)
+
+对应 spec `optimize.exit`:
+
+- build 通过。
+- contract 通过。
+- first win 通过,且符合本轮路径要求。
+- lifecycle 通过:phasePath 从 HOOK 出发,包含 TUTORIAL 和 GAMEPLAY,到达 ENDCARD,无跳跃。
+- fusion 检查通过或明确 no-op。
+- autoplay 能跑完完整游戏路径。
+- 录像产出,并能从完整游戏角度看到 hook、引导、成功 / 失败和基础玩法闭环。
+- 任务卡 Work / Context / Reference 没有被实现偏离。
+- 8 角度评价已逐项记录 pass / fail / unchanged;所有 fail 项有明确 routeTo;P0 级问题已修复,P1/P2 有 nextAction。
+
+## 反模式
+
+- 录像只证明某个功能点存在,看不出完整游戏。
+- 为通过 first win 跳过引导或成功 / 失败表达。
+- optimize 阶段重新设计包装方向。
+- 目标优化阶段引入与用户输入无关的大改。
+- 验证失败时直接改 design / brief。

package/project-template-v2/docs/harness/iteration-2/wrapup-flow.md

@@ -0,0 +1,115 @@
+# 迭代2 · wrapup flow(迭代整理)
+
+> 阶段执行序文档。无角色派发(`dispatchableRoles: []`),由脚本/编排执行。被 `pipeline/iteration-2-wrap.mjs` 的 `wrapup.flowRef` 引用。
+
+## 目标
+
+wrapup 只在迭代2真实跑完后执行。它负责回收运行态副作用、确认文档链可追溯、刷新当前项目入口信息,并在第二轮结束后把完整包装结果交给用户确认。
+
+补模板流程规则时不要执行本阶段动作,尤其不要提前改 `CLAUDE.md`。
+
+## 输入
+
+- `docs/project-state.json` / `docs/project-state.md` — 当前机器态与人读状态。
+- `docs-last/` — 进入迭代2前的 docs 快照。
+- `docs/design.md` / `docs/design-brief.md` — 迭代2设计和决策记录。
+- `docs/todo_list.md` — 迭代2任务卡和 TODO 历史总览。
+- optimize handoff / validate / recordings — 完整游戏验证证据。
+- 当前 `game/**` / `assets/**` — 真实落地后的项目状态。
+
+## 关键步骤
+
+### 1. 回收测试资源、释放端口占用
+
+- 关闭 optimize 阶段启动的 dev server、record 进程、临时 watcher。
+- 确认端口未被本轮测试进程占用。
+- 清理无需留存的临时校验产物,保留关键录像、validate 报告和 handoff 证据。
+
+### 2. 确认 todo 清空
+
+- 当前 iteration todo 必须全部 `done`。
+- 有 `failed` / `pending` / `in_progress` 时不得 wrapup。
+- 如果 todo 池状态与 `docs/todo_list.md` 历史不一致,先由调度者修正状态或补历史记录。
+
+### 3. 确认 docs 差异链可追溯
+
+必须能从以下链路追到本轮变化:
+
+- `docs-last/` — 迭代2进入前的历史状态。
+- `docs/design.md` — 迭代2路径 A 包装构建或路径 B 目标优化章节。
+- `docs/design-brief.md` — Entry Decision、Packaging Build Log 或 Target Optimization Log。
+- `docs/todo_list.md` — 迭代2任务卡、差异覆盖矩阵、参考变化、TODO 依赖关系。
+- handoff / validate / recordings — generate 和 optimize 的落地证据。
+
+不要删除 `docs-last/`。它是 context 差异和 wrapup 审计的依据。
+
+### 4. 确认 TODO 历史总览
+
+`docs/todo_list.md` 必须包含当前 todo 与之前 todo 合并后的“TODO 历史总览”:
+
+```markdown
+## TODO 历史总览
+
+| iteration | todoId | 类型 | 状态 | 交付摘要 | artifactRefs |
+| --------- | ------ | ---- | ---- | -------- | ------------ |
+```
+
+如果 generate 阶段尚未整理,wrapup 阶段由调度者补齐。这里只整理历史,不改变任务卡原语义。
+
+### 5. 刷新 `CLAUDE.md`
+
+仅在迭代2真实完成后执行。刷新内容应来自当前目录事实:
+
+- 当前 pipeline iteration / stage / status。
+- 当前 playable 是否已形成完整包装版本。
+- design / brief / todo / docs-last 的实际存在状态。
+- 当前 `game/**`、`assets/**`、validate / recordings 的关键状态。
+- 高影响已知缺口。
+
+不要写:
+
+- 完整 todo 池。
+- handoff 全历史。
+- 未来迭代计划。
+- 尚未真实发生的流程假设。
+
+### 6. 第二轮结束用户确认
+
+迭代1结束后可自动进入迭代2;迭代2结束后需要把完整包装结果交给用户确认。
+
+确认信息应基于 optimize 证据,至少包含:
+
+- 当前包装版本做到了什么。
+- 录像 / validate 证据在哪里。
+- 是否存在 P1 / P2 遗留问题和建议下一步。
+- 需要用户确认的是“接受当前完整 playable 包装结果”还是“提出新的目标优化输入”。
+
+用户确认前,不得无条件进入下一轮目标优化或后续迭代。
+
+## 产出物
+
+无新设计产物。副作用:
+
+- 测试进程关闭、端口干净。
+- `docs/todo_list.md` 有完整 TODO 历史总览。
+- `CLAUDE.md` 已按真实项目状态刷新。
+- 调度者已向用户发出第二轮结束确认,或记录需要用户确认的 pending 状态。
+
+## 评价(退出判据)
+
+对应 spec `wrapup.exit`:
+
+- 测试资源回收完成,无本轮遗留端口占用。
+- 当前 iteration todo 全部 done。
+- docs 差异链完整可追溯。
+- TODO 历史总览已合并当前 todo 与之前 todo。
+- 包装流程真实落地后,`CLAUDE.md` 已反映当前工程状态。
+- 第二轮结束确认已面向用户发起,或机器态记录为等待用户确认。
+
+## 反模式
+
+- 只补模板流程规则时提前改 `CLAUDE.md`。
+- todo 未清空就进入下一迭代。
+- 删除 `docs-last/` 导致无法追溯迭代2差异。
+- 没有 optimize 证据就宣称包装完成。
+- 迭代2结束后不经用户确认直接进入下一轮。