@playcraft/cli 0.0.57 → 0.0.58

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

@@ -0,0 +1,75 @@
+# 迭代1 · optimize flow(优化)
+
+> 阶段执行序文档。角色:developer。被 `pipeline/iteration-1-core.mjs` 的 `optimize.flowRef` 引用。
+
+## 目标
+
+把 generate 产出的 game 打磨成**可自动演示并录像**的交付物,并确认实现没有偏离 `docs/design.md` 的最小核心交互循环。DoD (Definition of Done, 完成定义) 当前保持运行时/视频闭环:build 通过 → runtime contract 通过 → autoplay 能复现核心路径 → first win 通过 → fusion 检查 → 录像产出。autoplay 只作为行为外挂模拟用户行为,用于驱动真实玩家路径;它不应侵入玩法规则。脚本绿灯是基础证据,不是玩法语义的全部结论。
+
+## 关键步骤(DoD 三步序)
+
+1. **build & 修错**
+   - `npm run build`,有报错就定位修复。
+2. **接入 autoplay**
+   - 把游戏接成可自动演示(无需人手操作即可跑完一局核心闭环)。autoplay 是可复现的玩家路径执行器:通过公开合约 / 输入层 / 外层控制器模拟用户行为,作为行为外挂驱动真实玩法路径,不是直接通关开关。
+   - 正常情况下,generate 末尾的系统 todo `firstwin-harness` 已完成最小 runtime harness 接线;本阶段优先重跑和修复,不要重新设计通关路径。
+   - 如需暴露 hook,只暴露玩家动作等价入口(如 tap / drag / release)和状态观察点;不要在核心玩法里新增 `autoplay` 分支、测试专用胜利条件、跳规则 shortcut 或直接写终态的逻辑。
+   - 先跑 `npm run verify:contract`,确认 `window.__playable` 合约已接线。
+   - 跑 `npm run verify:firstwin`,确认自动演示从初始状态出发,经过至少一次核心玩家动作等价步骤,产生设计中声明的反馈 / 进度变化,再到达成功或 ENDCARD。
+   - 跑 `npm run verify:fusion`,确认多玩法融合设计与源码接线不冲突。
+3. **设计回查 + 实际路径检查**
+   - 回读 `docs/design.md` 的最小核心交互循环,把"玩家意图 / 动作 / 系统响应 / 反馈或进度 / 成功失败"逐项对照当前实现。
+   - 至少尝试一次真实点击 / 输入路径,确认人工玩家路径不是只靠 autoplay 才能成立。记录操作步骤、观察到的反馈和偏离项。
+   - 如果录屏或运行路径没有体现核心动作、反馈或进度变化,即使 contract / firstwin / record 为绿,也要记录 blocker 后修复。
+4. **build & 录像**
+   - 依赖 atom skill **`playable-record`**:headed 60fps 录像(`record:mp4 --headed --fps=60`),产出交付证据 MP4 (MPEG-4 Part 14, 视频容器格式)。
+   - 需要语义视频评审时跑 `npm run verify:vlm-video`。
+
+5. **跑 DoD 检查** — 上述步骤走完后,本阶段以 DoD 检查收尾(不是单个 verifier):
+   ```bash
+   npm run dod:check
+   ```
+   在 handoff summary 里逐项报告 build / autoplay / record 的 pass/fail。`autoplay` 当前是无脚本 DoD;确认自动演示能跑完整闭环后,由 orchestrator 显式写入:
+   ```bash
+   npm run state:set -- gatePatch='{"stageDoD":{"autoplay":"passed"}}'
+   ```
+
+## 产出物
+
+- `game/**`(可自动演示)
+- `recordings/*.mp4`(录像证据)
+- `validate/**`(校验报告/证据,按实际 verifier 输出)
+
+## 评价(退出判据)
+
+对应 spec `optimize.exit` / DoD: `build` / `contract` / `firstLevelWin` / `fusion` / `autoplay` / `record`:
+
+- build 通过(无报错)。
+- contract 通过(`window.__playable` 可用)。
+- autoplay 能通过玩家动作等价入口复现核心路径,不是直接设置终态或调用胜利函数。
+- first win 通过(自动演示经过核心动作 / 反馈 / 进度后到达成功或 ENDCARD)。
+- fusion 检查通过或明确 no-op。
+- 录像产出。
+- 已回查 `docs/design.md`,并记录真实点击 / 输入路径的观察结果。
+
+## Skill 接入状态
+
+本阶段接入运行时/视频相关 skill。UI (User Interface, 用户界面) / focus playground 等质量环路后移。
+
+| skill               | 干啥                                                     | 对应 DoD 步      |
+| ------------------- | -------------------------------------------------------- | ---------------- |
+| `playable-autoplay` | autoPlay / firstwin harness 的实现方法                   | ② first win 接线 |
+| `playable-debug`    | autoPlay / 一键通关排障说明                              | ② first win 排障 |
+| `playable-record`   | runtime contract / first win / fusion + headed 60fps MP4 | ②/③ 验证 + 录像  |
+| `playable-validate` | 当前最小 video validation loop                           | ③ 录像后语义评审 |
+
+注意:本阶段仍聚焦运行时交付验证(build / contract / firstwin / fusion / autoplay / record / vlm-video)。`verify:lifecycle`、`verify:ui`、focus playground 暂不迁入。
+
+## 反模式
+
+- 跳过 autoplay 直接录人手操作。
+- autoplay 或 firstwin 直接设置 ENDCARD / win 状态,跳过核心玩家动作和反馈。
+- 为 autoplay 在玩法代码里新增快捷通关分支、隐藏胜利条件或绕过规则的状态写入。
+- build 有报错就标 DoD 通过。
+- 在 optimize 阶段改玩法(应只打磨,不改 design 已定的核心玩法)。
+- 只看 contract / firstwin / record 是否绿,不回查 design,也不实际尝试玩家路径。

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

@@ -0,0 +1,63 @@
+# 迭代1 · wrapup flow(迭代整理)
+
+> 阶段执行序文档。无角色派发(`dispatchableRoles: []`),由脚本/编排执行。被 `pipeline/iteration-1-core.mjs` 的 `wrapup.flowRef` 引用。
+
+## 目标
+
+迭代收尾:清理本迭代留下的运行态副作用,并把 `CLAUDE.md` 刷新成后续 agent 的导航索引。它帮助别人快速找到状态、设计、代码、证据和缺口,不是验收报告或成果总结。
+
+## 关键步骤
+
+1. **回收测试资源、释放端口占用**
+   - 关闭 optimize 阶段起的 dev server / record 占用的端口。
+   - 清理临时录像/校验产物中无需留存的部分(保留交付证据 MP4)。
+2. **刷新 CLAUDE.md 项目入口卡片**
+   - 因为本迭代新增了 design.md / todo_list.md / game/ 等文件,项目目录状态已变。
+   - 本阶段先按下面"入口卡片刷新规则"手工更新 CLAUDE.md;后续再沉淀成 `playcraft-project-entry-refresh` skill 与脚本。
+   - CLAUDE.md 只描述当前工程身份、目录地图、状态入口、关键产物位置、验证证据状态与全员边界;不复制调度剧本、不写完整 todo 池、不写 handoff 历史、不写主观质量结论。
+
+## CLAUDE.md 入口卡片刷新规则(迭代1手工版)
+
+把 CLAUDE.md 当成项目速览 / 导航索引:它应帮助任何 agent 在 30 秒内知道"这是哪类工程、从哪里读状态、目录怎么走、常用命令是什么、关键设计/任务/证据在哪里、有哪些全员边界"。它不是调度剧本,不是第二份状态源,也不是质量评价报告。
+
+### 收集顺序
+
+1. **包与命令** — 读 `package.json` 的项目名、模板版本、核心 scripts。只记录可稳定复用的命令:dev/build/typecheck/state/todo/handoff/DoD。不存在或尚未接入的验证脚本要标明是缺口。
+2. **入口与运行时** — 查 `index.html`、`main.ts`、`game/index.ts`、`.playcraft-engine`(若存在),说明当前是 placeholder 还是已应用 engine pack。
+3. **状态与设计产物** — 通过 `npm run state:get` 读取轻量摘要:iteration、stage、engine、coreAction、devStatus;再列关键产物是否存在,如 `docs/design.md`、`docs/design-brief.md`、`docs/atom-tree.json`、`docs/todo_list.md`。`docs/project-state.json` 只是过程文件,不要把直接读取 JSON 当成常规入口。
+4. **目录地图** — 列 `game/`、`assets/`、`docs/`、`docs/harness/`、`docs/harness/orchestrator-flow.md`、`skills/_shared/scripts/`、`.claude/agents/`、`.claude/skills/` 的用途。只解释目录职责,不展开全部文件。
+5. **验证与证据索引** — 列当前可用证据位置和状态,如 `validate/**`、`recordings/*.mp4`、DoD 结果、autoplay / firstwin / record 是否已验证。证据缺失就写 missing / pending,不要改写成完成。
+6. **工程约定** — 写全员可见的状态规则和 agent 边界:主会话执行 `npm run state:get` 后始终作为 orchestrator;具名 subagent 只读 `npm run state:get -- --json dispatch`;subagent 不升级成 orchestrator,也不自行 `todo:set`;写状态走脚本。
+7. **关键缺口** — 只保留 2-4 条会影响继续制作的高层缺口,并链接到具体文件或证据位置。
+
+### 写入标准
+
+- 写具体事实,少写口号。例如"game/index.ts 仍是 engine placeholder",不要写"工程结构清晰"。
+- 记录当前工程形态,不是未来计划。未来计划只用链接指向 harness 文档。
+- 只写事实和证据状态,不要写"质量很好"、"玩法完成"、"已充分验证"这类无法从 state / artifact 直接证明的判断。
+- 如果 DoD、录像、autoplay 或设计回查证据不足,如实写 missing / pending / blocker。
+- 保留入口分流规则:主会话读 global state 并保持 orchestrator;具名 subagent 只读 dispatch,匹配 role 才执行。
+- 每次 wrapup 只刷新工程速览和关键缺口;不要把每次 handoff、todo 明细、用户确认细节写进来。
+
+### 不要写入
+
+- `stageExit` / `dispatchableRoles` / `canWriteTodo` 等调度者专属信息。
+- 完整 todo 列表、完整 handoff 历史、未来迭代细节。
+- role card 的职责全文或 pipeline spec 全文。
+- 成果宣传、主观质量评价、没有证据支撑的完成判断。
+
+## 产出物
+
+无新设计产物。副作用:
+
+- 端口干净、无悬挂进程。
+- CLAUDE.md 已按当前目录刷新为导航索引。
+
+## 评价(退出判据)
+
+对应 spec `wrapup.exit`:
+
+- 端口回收完成(无悬挂 dev/record 进程)。
+- CLAUDE.md 已按入口卡片规则刷新,能定位状态、设计、代码、证据和缺口。
+
+满足后,advanceStage 在 wrapup→下一迭代边界会再次校验 `todosCleared`(本迭代 todo 必须已清空),通过后进入迭代2 的 ideate。

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

@@ -0,0 +1,223 @@
+# 迭代2 · context flow(差异上下文构建)
+
+> 阶段执行序文档。角色:game-designer。被 `pipeline/iteration-2-wrap.mjs` 的 `context.flowRef` 引用。
+
+## 目标
+
+context 阶段接收 ideate 已经明确的进入路径和设计信息,直接读取 `docs-last/` 与当前 `docs/` 的差异,把差异转换成下游可执行的 TODO 上下文。
+
+本阶段只回答三件事:
+
+- **要做什么** — 从 design 差异推导出的玩家可感知工作。
+- **上下文是什么** — 这项工作来自哪个设计章节、brief 决策、历史状态和当前代码区域。
+- **参考是什么** — 可复用 / 必须保留 / 必须避开的 atom、skill、API (Application Programming Interface, 应用程序编程接口)、event、config、asset binding。
+
+本阶段不写 `docs/design-brief.md`,不补设计结论,不提前侵入 verifier 或 optimize 验证体系。如果 design / brief 信息不足,STOP 写 blocker,路由回 ideate。
+
+## 输入
+
+- `docs-last/` — 进入迭代2前的 docs 快照,用于读取历史状态和差异来源。
+- `docs/design.md` — 已由 ideate 按路径 A 包装构建或路径 B 目标优化更新。
+- `docs/design-brief.md` — 已记录 ideate 路径判断、用户输入、设计取舍。
+- `docs/todo_list.md` — 原 todo 文档,本阶段继续追加迭代2任务卡,不创建 `todo_list_v2.md`。
+- `docs/atom-tree.json` — Atom 引入中间文件;如存在,根据迭代2意图更新或补充参考。
+- `.claude/skills/**` / `skills/**` / `.claude/agents/refs/atom-skill-library.md` — skill 库与本地参考索引,用于查找可复用能力。
+- 当前 `game/**` — 用来判断工作应落到哪些系统/文件区域;context 阶段不实现。
+
+## 关键步骤
+
+### 1. 读取 ideate 路径
+
+从 `docs/design.md` 与 `docs/design-brief.md` 确认本轮是:
+
+- `Packaging Build` — 核心玩法完成后的包装构建。
+- `Target Optimization` — 已执行一轮后的目标优化。
+
+如果路径不明确,STOP 写 blocker 回 ideate。context 不自行补判定。
+
+### 2. 读取 docs 差异
+
+- 比较 `docs-last/design.md` 与 `docs/design.md`,找出本轮新增 / 改写的设计目标。
+- 比较 `docs-last/design-brief.md` 与 `docs/design-brief.md`,确认新增决策、用户输入和取舍来源。
+- 比较 `docs-last/todo_list.md` 与 `docs/todo_list.md`(如存在),避免重复派发已完成或已存在任务。
+
+差异读取目的不是重新设计,而是确认“这次目标变化要求开发做什么”。
+
+### 3. 按意图区分任务粒度
+
+**3a. 功能差异分类**
+
+| 类型     | 判断标准                                                     | 分发粒度                                                    |
+| -------- | ------------------------------------------------------------ | ----------------------------------------------------------- |
+| 重写     | 改动会替换已实现的核心状态、关卡流程、胜负表达或主要事件顺序 | 单独 todo,范围窄,上下文必须写清旧状态和新状态               |
+| 优化     | 不改变规则,但提升反馈、节奏、引导、文案、可读性或趣味        | 可合并同一玩家路径上的小优化,上下文必须说明玩家观察到的变化 |
+| 功能补充 | 新增关卡、引导、失败恢复、成功演出、包装反馈等玩家可感知能力 | 一个功能闭环一个 todo,上下文必须写清进入条件和完成条件      |
+
+路径 A 通常会产生多个包装构建 todo;路径 B 通常只产生受用户输入或执行反馈影响的少量优化 / 重写 todo。不要因为进入迭代2就重新拆完整游戏。
+
+**3b. 技术维度评估（动态确认，非固定清单）**
+
+在确认功能差异之后,评估当前 game 代码是否已有以下技术基础设施。**每项只问"已有/缺失/部分"**,对缺失项判断是否会阻塞功能 todo 的实现——若会阻塞,则作为独立的基础设施 todo 优先排入;若不会阻塞(可在功能 todo 内顺带建立),则并入对应功能 todo 并在 Context 小节说明。
+
+| 技术维度             | 评估问题                                                                                                                                | 如果缺失且阻塞                                                 |
+| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| **Scene 状态机骨架** | game 中是否已有 HOOK / TUTORIAL / GAMEPLAY / WIN / FAIL / ENDCARD 六个阶段的状态机入口和转换触发?autoPlay 能否驱动完整路径?             | 独立 todo `packaging-scene-fsm`,必须先于其他包装 todo 完成     |
+| **分层渲染架构**     | 是否定义了 Game Layer / HUD Layer / Overlay Layer / Effect Layer / EndCard Layer 的 z-index 层级?引导层和 endcard 层是否会遮挡游戏内容? | 独立 todo `packaging-layer-arch`,先于需要叠加 UI 的功能 todo   |
+| **输入控制分层**     | Tutorial 阶段是否能限制输入只响应引导区域?是否有统一的输入开关入口?                                                                     | 可并入 Tutorial 功能 todo,但必须在 Context 里说明接入点        |
+| **声音状态机**       | BGM 是否随 scene 切换有淡入淡出?SFX 是否按事件触发而非分散 if-else?Win/Fail 音效是否与视觉同步?                                         | 可并入对应 scene 功能 todo,但必须在 Context 里说明接入点       |
+| **反馈引擎**         | 核心动作的视觉反馈(闪光/粒子/形变)是否有统一调用入口?是否与 ideate 定义的反馈规格有对应关系?                                            | 可并入核心动作相关 todo,但必须说明统一入口或已有分散实现的清点 |
+| **资产加载策略**     | 包装层新增资产(hook frame / win 演出 / endcard 背景)是否已规划首帧必须 vs lazy load?资产加载是否会影响 HOOK scene 时长?                 | 可并入 packaging-scene-fsm 或首个触达该资产的 todo             |
+
+评估结果写入 `docs/todo_list.md` 的"迭代2技术基础设施评估"小节:每项标注状态(已有/缺失-阻塞/缺失-不阻塞)和处理方式(独立 todo ID / 并入哪个功能 todo)。不要跳过这步——没有评估的技术维度将在 generate 阶段产生不可预期的接线冲突。
+
+### 4. 查找并更新参考上下文
+
+- 根据新的 design 意图检查 `docs/atom-tree.json` 的 Atom 引入中间状态是否仍匹配。
+- 如果现有参考不足,从 skill 库继续查找:
+  - 先查 `.claude/agents/refs/atom-skill-library.md`、`.claude/skills/*/SKILL.md`、`skills/*/SKILL.md` 的名称、Tags、DESC、使用场景。
+  - 可用 `rg` 按 design 关键词搜索 skill / reference / scripts,例如 hook、tutorial、feedback、level、vfx、sprite、audio、record、playable。
+  - 不要批量深读;只把强相关候选纳入下一步。
+- 对强相关参考深读:
+  - `SKILL.md` 的触发条件、输入、输出、限制。
+  - `references/`、`ref/`、模板文件、scripts 中是否有可执行实现流程。
+  - 如有代码实现过程,提取流程步骤、入口文件、命令、API / event / config / asset binding、可复用片段和注意事项。
+  - 如只有概念参考没有实现过程,也要说明“concept only”,避免 developer 误以为已有代码路径。
+- 可基于当前意图刷新或补充 `docs/atom-tree.json`,但只维护 match / selectedAtoms / link 所需 metadata,不把任务计划、执行日志或 handoff 状态写进去。
+- 如果参考内容发生变化,必须在 `docs/todo_list.md` 的“迭代2参考变化”中明确指出:
+  - 新增参考是什么。
+  - 替换 / 废弃了什么。
+  - 变化原因来自哪个 design 差异。
+  - 是否存在代码实现过程或模板。
+  - 下游 developer 必须保留或避开的 API / event / config / asset binding。
+- 如果参考变化暴露设计缺口,STOP 写 blocker 回 ideate;不要在本阶段补 brief。
+
+### 5. 追加 `docs/todo_list.md`
+
+不创建 `docs/todo_list_v2.md`。在原文件追加独立章节:
+
+```markdown
+## 迭代2:玩法包装 TODO
+
+### 本轮路径
+
+- Entry Mode: Packaging Build / Target Optimization
+- Source: `docs/design.md#...`; `docs/design-brief.md#...`
+- Summary: {本轮 design 变化的摘要}
+
+### 迭代2技术基础设施评估
+
+| 技术维度         | 状态                           | 处理方式                                                           |
+| ---------------- | ------------------------------ | ------------------------------------------------------------------ |
+| Scene 状态机骨架 | 已有 / 缺失-阻塞 / 缺失-不阻塞 | 独立 todo `packaging-scene-fsm` / 并入 `<todo-id>` / 已有无需处理  |
+| 分层渲染架构     | 已有 / 缺失-阻塞 / 缺失-不阻塞 | 独立 todo `packaging-layer-arch` / 并入 `<todo-id>` / 已有无需处理 |
+| 输入控制分层     | 已有 / 缺失-阻塞 / 缺失-不阻塞 | 并入 `<todo-id>` / 已有无需处理                                    |
+| 声音状态机       | 已有 / 缺失-阻塞 / 缺失-不阻塞 | 并入 `<todo-id>` / 已有无需处理                                    |
+| 反馈引擎         | 已有 / 缺失-阻塞 / 缺失-不阻塞 | 并入 `<todo-id>` / 已有无需处理                                    |
+| 资产加载策略     | 已有 / 缺失-阻塞 / 缺失-不阻塞 | 并入 `<todo-id>` / 已有无需处理                                    |
+
+### 差异总览
+
+| diffId | 来源章节 | 类型(重写/优化/功能补充) | 玩家影响 | 分发策略 |
+| ------ | -------- | ------------------------ | -------- | -------- |
+
+### 迭代2参考变化
+
+| reference | change | reason | implementation process | downstream constraint |
+| --------- | ------ | ------ | ---------------------- | --------------------- |
+
+### 差异覆盖矩阵
+
+| diffId | todoId | 类型 | 覆盖状态 |
+| ------ | ------ | ---- | -------- |
+
+### TODO 依赖关系
+
+| todoId | dependsOn | 可并行 | 原因 |
+| ------ | --------- | ------ | ---- |
+
+### TODO <id> — <玩家可感知任务名>
+
+#### Work
+
+- Do: {下游需要完成什么}
+- Type: 重写 / 优化 / 功能补充
+- Player Impact: {玩家会看到或感受到什么变化}
+- Entry / Completion: {如是功能补充,写清进入条件和完成条件}
+
+#### Context
+
+- Design Source: `docs/design.md#...`
+- Brief Source: `docs/design-brief.md#...`
+- History Source: `docs-last/<source-file>#...`
+- Current Code Area: `game/...` / `assets/...` / other
+- Keep: {必须保持不变的核心动作、胜负语义、合约或已完成能力}
+- Avoid: {禁止顺手重写或越界处理的内容}
+
+#### Reference
+
+| reference | reuseLevel | implementation process | mustKeep | note |
+| --------- | ---------- | ---------------------- | -------- | ---- |
+
+#### Implementation Notes
+
+- Existing Process: {如 skill / reference / script 提供了实现过程,写路径和步骤;没有则写 none / concept only}
+- Code Entry: {可参考的文件、模板、脚本或 API;没有则写 none}
+- Integration Notes: {developer 需要知道的接入点、约束、避免事项}
+```
+
+任务卡里不要写 `Verifier` 小节。不要把 `Acceptance` 写成验证脚本清单。下游需要知道的是任务、上下文和参考;验证由 generate / optimize / 调度执行层按阶段标准处理。
+
+### 6. seed 机器态 todo 池
+
+每个 todo 的 `requiredContext` 第一项必须回到 `docs/todo_list.md#todo-<id>`,保证 developer 执行时能读到 context 阶段生产的完整任务卡。
+
+机器态 todo 只存摘要:
+
+- `doWhat` — 对应任务卡 `Work.Do` 的一句话。
+- `requiredContext` — 任务卡全文 + design / brief / docs-last / reference / skill 实现过程路径。
+- `acceptance` — 如脚本字段需要,只写”完成任务卡 Work 中定义的玩家可感知变化,并保持 Context.Keep 不变”这类最小约束,不要写 verifier 细节。
+- `verifier` — 不在 context 中指定;如脚本默认写入,不把它作为任务卡内容或设计判断。
+
+**系统 todo `packaging-scene-fsm` 由调度者注入,不由 game-designer seed**。context 阶段只在技术基础设施评估表里标注 Scene 状态机骨架的状态(已有 / 缺失-阻塞 / 缺失-不阻塞)即可;调度者读到”缺失-阻塞”后负责追加该 todo,并确保它在其他包装功能 todo 之前执行。
+
+示例:
+
+```bash
+npm run todo:add -- id=wrap-success-failure-context role=developer \
+  doWhat="Implement the success/failure packaging work described in the iteration-2 task card" \
+  acceptance="complete Work in docs/todo_list.md#todo-wrap-success-failure-context;keep Context.Keep unchanged" \
+  requiredContext="docs/todo_list.md#todo-wrap-success-failure-context;docs/design.md#迭代2玩法包装升级;docs/design-brief.md#iteration-2-packaging-build-log;docs-last/design.md" \
+  createdBy=game-designer
+```
+
+## 产出物
+
+- `docs/todo_list.md` — 原文件追加“迭代2:玩法包装 TODO”章节,包含工作、上下文、参考。
+- 当前 iteration todo 池 — seed 完成,机器态 todo 指回任务卡全文。
+- `docs/atom-tree.json` — 如 Atom 参考变化,已按新意图更新中间状态;若无需变化,在 todo_list 中明确说明 no-op。
+
+## 评价(退出判据)
+
+对应 spec `context.exit`:
+
+- 已读取 ideate 路径,并在 todo_list 中记录 `Packaging Build` 或 `Target Optimization`。
+- 每个 todo 都来自明确 docs 差异点,并标注重写 / 优化 / 功能补充。
+- 每个 todo 都清楚说明要做什么、上下文是什么、参考是什么。
+- todo 粒度与差异类型匹配;路径 B 没有无依据重拆完整包装。
+- 如参考树发生变化,`docs/todo_list.md` 明确说明变化原因、是否有代码实现过程和下游约束。
+- `docs/todo_list.md` 有差异覆盖矩阵和 TODO 依赖关系。
+- 当前 iteration todo 池非空,且每个 todo 的 `requiredContext` 指回对应任务卡全文。
+- 本阶段未写 `docs/design-brief.md`;设计缺口以 blocker 形式回 ideate。
+
+## 反模式
+
+- 无视 ideate 路径,直接凭感觉拆 todo。
+- 无视 `docs-last/`,不说明目标变化来源。
+- 把所有差异都按同一种粒度拆。
+- 创建 `todo_list_v2.md`。
+- 在任务卡中写 `Verifier` 或提前指定 optimize 验证脚本。
+- 只沿用旧 atom-tree,没有按迭代2 design 意图去 skill 库查找新参考。
+- 把 atom-tree 当成迭代2任务计划或执行记录来手写维护。
+- 找到 skill 但不检查是否有 references / scripts / templates 里的实现过程。
+- 参考内容变化但不告知下游。
+- context 阶段补写 brief 或新增设计结论。

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

@@ -0,0 +1,129 @@
+# 迭代2 · generate flow(包装生成)
+
+> 阶段执行序文档。角色:developer。被 `pipeline/iteration-2-wrap.mjs` 的 `generate.flowRef` 引用。
+
+## 目标
+
+按当前 dispatch 对应的 `docs/todo_list.md` 迭代2任务卡实现包装升级。generate 不重新拆任务、不重写设计,只把 context 阶段产出的 **Work / Context / Reference / Implementation Notes** 落到代码里。
+
+本阶段的评价视角是完整游戏:包装构建要让核心玩法变成清晰、有趣、可完成的 playable;目标优化只修改用户输入或执行反馈影响到的部分,不能无依据重做整套包装。
+
+## 调度关系
+
+developer 只处理当前 dispatch。调度者从 todo 池挑一个 todo 写入 `state.dispatch`,developer 通过:
+
+```bash
+npm run state:get -- --json dispatch
+```
+
+读取当前工单。完成后只追加 handoff;todo 状态由调度者读取 handoff 后更新。
+
+## 任务循环(每个 dispatch 走一遍)
+
+### 1. 读取任务卡全文
+
+先读 dispatch 的 `requiredContext`,第一项必须是 `docs/todo_list.md#todo-<id>`。从任务卡中提取:
+
+- `Work` — 当前要做什么、类型是重写 / 优化 / 功能补充、玩家影响、进入 / 完成条件。
+- `Context` — design / brief / docs-last 来源、当前代码区域、必须保持不变的内容、禁止越界的内容。
+- `Reference` — 可复用或必须避开的 atom / skill / API (Application Programming Interface, 应用程序编程接口) / event / config / asset binding。
+- `Implementation Notes` — skill / reference / script / template 是否提供代码实现过程、入口文件和接入注意事项。
+
+如果任务卡缺少 Work、Context 或 Reference,STOP 写 blocker,不要凭 dispatch 摘要硬做。
+
+### 2. 确认本轮路径和执行边界
+
+- `Packaging Build` — 可以实现包装构建任务卡中定义的 hook、关卡、引导、成功 / 失败、反馈或流程闭环,但不能改坏迭代1核心动作和胜负语义。
+- `Target Optimization` — 只改任务卡中列出的保持不变项之外的受影响部分;不要顺手重写完整包装。
+
+再按类型确认边界:
+
+| 类型     | developer 应做                                         | 必须避免               |
+| -------- | ------------------------------------------------------ | ---------------------- |
+| 重写     | 替换任务卡指定旧行为,避免新旧逻辑并存                  | 顺手重构无关系统       |
+| 优化     | 保持规则不变,增强玩家可观察反馈 / 节奏 / 引导 / 可读性 | 改变核心规则或胜负条件 |
+| 功能补充 | 实现进入条件、运行路径、反馈、完成条件                 | 只有入口没有闭环       |
+
+### 3. 读取参考实现过程
+
+对任务卡 Reference / Implementation Notes 中列出的强相关参考,先读后改:
+
+- 如有 `SKILL.md`,读取触发条件、输入输出、限制。
+- 如有 `references/`、`ref/`、templates、scripts,读取与当前任务相关的实现步骤或代码入口。
+- 如任务卡标记 `concept only`,只吸收设计原则,不要假设已有可复制代码。
+- 如参考提供 API / event / config / asset binding,实现时必须沿用任务卡指定约束。
+
+如果参考路径缺失、实现过程与当前代码冲突,或任务卡引用的 API 不存在,STOP 写 blocker 给调度者;不要临时发明替代协议。
+
+### 4. 实现 scoped closure
+
+- 只修改当前任务卡允许的代码区域。
+- 保留 `Context.Keep` 中的核心动作、胜负语义、运行时合约和已完成能力。
+- 遵守 `Context.Avoid`,不做 CTA、视觉大改、无关资产流程或后续阶段工作。
+- 对重写任务,先定位旧行为并替换;对优化任务,在原路径上增强;对功能补充任务,实现一个玩家可感知闭环。
+- 保持 `window.__playable` 等 playable runtime 合约不破。
+
+### 5. 本地自检
+
+generate 阶段可以做必要的轻量检查,但不把 optimize 的验证体系前置到任务卡里。
+
+至少自检:
+
+- 当前 Work 是否完成。
+- Context.Keep 是否仍成立。
+- Reference / Implementation Notes 中的接入约束是否被遵守。
+- 完整游戏视角下,玩家是否仍能理解目标、完成 first win,并看到成功 / 失败或对应优化反馈。
+
+如 dispatch 或项目已有 verifier 字段 / 脚本,可按调度者提供的工单执行;没有时不要自行补写 verifier 规则。完整录像、自动游玩和阶段 DoD (Definition of Done, 完成定义) 留给 optimize。
+
+### 6. handoff
+
+developer 不自行 `todo:set`。完成或阻塞都追加 handoff:
+
+- `summary` — 做了什么,对应哪个 Work。
+- `artifactRefs` — 修改的文件。
+- `selfCheck` — Work / Context.Keep / Reference 约束 / 完整游戏视角的结果。
+- `blockers` — 如有,说明缺失的设计信息、参考实现、代码入口或调度决策。
+
+## 开发完成后的 TODO 历史整理
+
+这是调度者动作,不是单个 developer dispatch 的工作。
+
+当前 iteration todo 全部 done 后,调度者把迭代1 todo 与迭代2 todo 合并成完整历史视图,写回 `docs/todo_list.md` 的“TODO 历史总览”章节:
+
+```markdown
+## TODO 历史总览
+
+| iteration | todoId | 类型 | 状态 | 交付摘要 | artifactRefs |
+| --------- | ------ | ---- | ---- | -------- | ------------ |
+```
+
+这一步只整理历史,不改变已完成任务卡语义。如果已有脚本化历史导出,优先用脚本;没有脚本时由调度者按 state + handoff 整理。
+
+## 产出物
+
+- `game/**` / `assets/**` — 当前任务卡要求的包装实现。
+- handoff — 每个 todo 的产出、阻塞或自检结果。
+- `docs/todo_list.md` — 所有迭代2 todo 完成后,由调度者追加 TODO 历史总览。
+
+## 评价(退出判据)
+
+对应 spec `generate.exit`:
+
+- 当前 iteration todo 全部 `done`,无 pending / in_progress / failed。
+- 每个 done 都能回链到 `docs/todo_list.md` 的迭代2任务卡。
+- 每个实现都遵守任务卡的 Work / Context / Reference / Implementation Notes。
+- 包装构建任务让 game 作为完整游戏更清晰、有趣、可完成;目标优化任务只修改受影响目标,没有无依据重做整套包装。
+- 重写没有遗留旧行为冲突;优化有玩家可观察改善;功能补充有完整闭环。
+- `docs/todo_list.md` 已合并当前 todo 与之前 todo,形成完整历史视图。
+
+## 反模式
+
+- 只读 dispatch 摘要,不读任务卡全文。
+- 忽略 Implementation Notes,不查 skill / reference / script / template 的实现过程。
+- 把 `concept only` 参考当成可复制代码。
+- 目标优化任务顺手重写完整包装。
+- 重写任务留下新旧逻辑并存。
+- 优化任务没有玩家可观察变化。
+- 功能补充只有入口,没有完成条件或反馈。
+- developer 自行标记 todo done。