@playcraft/cli 0.0.57 → 0.0.59

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

@@ -0,0 +1,254 @@
+# 迭代1 · context flow(上下文构建)
+
+> 阶段执行序文档。角色:game-designer。被 `pipeline/iteration-1-core.mjs` 的 `context.flowRef` 引用。
+>
+> 稳定职责(skill 探索方法、来源标记)在 `.claude/agents/game-designer.md`。本文件只写这阶段的序、产物、评价。
+
+## 目标
+
+把 `docs/design.md` 中已确认的最小核心交互循环与 skill 库匹配,先通过 atom-tree 中间产物完成 Atom 引入,再拆成一份**计划等价物**: `docs/todo_list.md` 中的完整任务卡 + 机器态 todo 池。`docs/atom-tree.json` / `docs/atom-tree.md` 只服务于 Atom 推荐、选择、link 与模板初始化,不是 generate 阶段的计划文档;调度者从机器态 todo 派发,developer 从 dispatch 展开的 `context` 获取任务卡语义后执行。`docs/todo_list.md` 是任务卡质量载体,机器态 todo 是派发与状态载体,两者必须保持一致。
+
+本阶段目标要**收窄**:只围绕“核心玩法闭环成立”去组织实现入口,不是把完整游戏实现过程预先穷举成大而全的开发分工表。todo 池应收敛为 **1-5 个** 高价值功能点(主附融合场景可到 6 个),优先表达“先做哪些功能点就足以把核心玩法跑起来、验证起来”,而不是“所有可能要做的技术事项”。超出 5 个前,先反查是否把同一功能点过度拆碎,或把本应并入已有 slice 的支撑工作单独列项了。
+
+本阶段只消费已确认的 `docs/design.md`;`docs/design-brief.md` 只是追溯设计原因和 skill 探索发现的记录文档,不是下游执行合同。不重新发起 web research / brainstorm 来改玩法。如果发现 `docs/design.md` 缺少可拆 todo 的核心规则、成功失败或玩家反馈,STOP 写 blocker,由 orchestrator 回 ideate 补设计,不要在 context 阶段自行补新玩法。
+
+### 收敛与最小交互循环
+
+**收敛职责**:design.md 在 ideate 阶段允许发散——它会探索完整游戏预期、反馈层级、乐趣来源,这些是设计探索的产物。context 的工作是**收敛**:从 design.md 的全部探索中只取"让核心循环能转起来"的那一节,翻译成 todo。design 写了五层反馈,context 只取最小循环所必需的那几层;design 描述了完整乐趣链,context 只取循环能成立的最小一段。
+
+收敛针对的是 **design.md 的发散内容**,不是参库的 atom。参库里的 atom 是"参考其设计 & 体验"的来源,只要它服务最小交互循环的某一环(看见/意图/动作/响应/反馈/决策),就应该尽量用上——用参库的现成参考托住循环这一环的成熟度,而不是凭空自造一个简陋版本。实验中"选了 arrow-puzzle-data 数据层就停手,把 path_input_handler / path_animation 这些核心交互入口和反馈动画的 atom 标成可省"是错误的收敛——它把"最小交互循环的循环结构最小"误解成了"atom 数量最小",结果动作和反馈两个环节没有参库参考托住,循环质量必然在衔接处断裂。**收敛不等于少选 atom,等于只选服务最小循环的 atom**——服务整局游戏的 packaging atom 不选,但服务循环某一环的核心 atom 都该拉进来作为参考。
+
+**最小交互循环**:指玩家在一个最小可重复局面中走完一轮的闭环——看见局面 → 产生意图 → 执行动作 → 系统按规则响应 → 给出可感知反馈 → 反馈引出下一次决策或最简成功/失败。它是一条**玩家路径**,不是一份功能清单,也不是一篇文章的结构。design.md 可能用任意章节组织这些内容(可能叫"核心循环""玩法规则""反馈""胜负"或其他),context 要做的是**用概念识别这条路径**,而不是锚定某个章节号去摘抄——不论内容写在 design.md 哪里,只要它属于"玩家走完一轮闭环所必需的看见/意图/动作/响应/反馈/决策",就是 context 要收敛的对象;只要它属于"让循环转得更爽、反馈更丰富、体验更完整",就是 context 要放给后续迭代的内容。
+
+"最小"指循环结构上的最小闭环,不是质量或内容上的简陋。这条循环本身应该是**高质量的完整核心交互体验**——视觉、反馈、手感、可读性都要做到位,只是它的范围收在"一轮闭环"而不是"整局游戏"。达成高质量的方式是**参考参库里已有的设计与体验**,而不是从零自造。参库里的 atom 是经过验证的设计参考和体验参考:它们承载了成熟的设计思路、参数取值、反馈节奏、可读性处理。context 应优先发现这些参考,让 design 描述的核心交互体验能落在已被验证的设计范式上,而不是凭空发明。
+
+但参考 ≠ 无脑 scaffold + 机械融合。atom 提供 scaffold 是为了省去重复实现已验证模式的工作,不是为了替代核心设计判断。真正决定循环质量的,是**融合点上的设计**——不同机制衔接处的体验过渡、反馈层之间的节奏配合、核心动作到系统响应的转译、玩家可感知状态的可读性。这些点不能靠 scaffold 自动产生,必须由 context 主动设计:看清每个 atom 解决什么问题、留下什么缝隙、缝隙之间如何衔接成一条连贯的玩家路径。如果只是把 atom scaffold 进来再机械粘合,核心交互体验会在衔接处断裂——这正是要避免的。所以 context 的工作是:用参库的设计/体验参考托住核心交互的成熟度,同时主动设计融合点,把分散的参考收敛成一条质量到位、体验连贯的核心循环。这是目标也是路径——目标是对齐 design 的核心交互体验,路径是参考参库设计 + 主动设计融合。
+
+context 的聚焦点是**实现最小交互循环**——todo 池存在的唯一理由,是把这条循环跑通到可验证。design.md 里所有不直接服务于此的内容(完整反馈层级、完整乐趣链、完整游戏体验预期),即使写得很完整,也不进入 todo。
+
+**atom 的软硬槽位认知**:每个 atom 内部都可能有多个 slot,这些 slot 分软硬。硬槽位是"不给它实现,循环这一环就裸奔"的——例如 path_input_handler 不引入,动作环节就裸奔;path_animation 不引入,反馈环节就裸奔。硬槽位关联的核心玩法 atom 一起引入,接入和合并难度小,反而是不一起引入才会在后续制造融合点断裂。软槽位是"去掉它循环照样转"的——bgMusic、终稿面板、背景图、角色表演等,这些属于 later-packaging,不进入迭代1 todo。判别判据同一:硬槽位不给它循环就裸奔,软槽位去掉它循环仍能转。
+
+除了构成循环环节的玩法 atom,还有一类 atom 不直接构成循环环节,但能对实现的质量保证和加速起作用——**工具类 atom**:地图生成器、可解性验证工具、屏幕适配工具等。这类 atom 的引入判据不是"它是不是循环一环",而是"它降低循环实现或验证的成本、提高产物质量"。地图生成器省去手写可解关卡、验证工具省去自证可玩、适配工具省去手写布局数学。它们是最小交互循环的补充——循环本身靠玩法 atom 托住,循环的实现质量靠工具类 atom 加速和保证。
+
+循环的每一环都应该有参库参考托住。最小交互循环不是"自己写最少代码让循环跑起来",而是"用参库最快出效果让循环跑起来"。参库里的 atom 都是"可参考"的对象——写也好、接入也好,dev 自己决定,但前提是先看到参库里有现成的参考和产物在那里,而不是默认从零自造。agent 倾向于"为了最小交互自己手写一个简陋版本"是错误的收敛——它把"最小"理解成了"自己写最少",实际上应该是"用参库最快"。判断标准是:循环这一环需要什么能力,参库里有没有现成的参考或产物能直接托住?有就参考它,没有再考虑手写,手写是 fallback 不是首选。
+
+**参数来源继承**:context 不规定玩法数值——关卡尺寸、路径数量、砖块数量、HP、计时、连击阈值、粒子数量等,这些都从已选 atom 的 schema / default / sample / scaffold 输出直接继承。todo 只说"采用 scaffold 默认测试数据验证循环能跑通",不在任务卡里另写具体数字。循环的输入数据(关卡、配置、初始局面)是循环的一部分,不是后续包装。生成它的工具(关卡生成器、配置 sample)和循环实现 atom 应该一起引入——不存在"先手写 fixture 跑通循环,后续再换生成器"这种顺序,直接用生成器的产物作为循环的合法输入。工具能生成带验证、带成熟范式的产物,参考它的设计 & 体验即可;只有工具不可用或失败时才手写 fallback,并在任务卡里标注为非合同的 fixture。**把临时数字写进 todo acceptance,等于把验证数据变成玩法合同**,会让后续为了凑这个数字而扩张实现范围。
+
+### 拆 todo 的原则
+
+**todo slice 定义**:除 engine setup 这类一次性基础设施外,每个 todo 都应是玩家路径上的 vertical slice(纵向切片):它必须能说明玩家看到什么、做什么、系统响应什么、状态如何推进,以及完成后游戏比上一个状态多了哪段可玩能力。slice 不是越小越好,它首先是一个**功能点**。一个 slice 可以同时落到多个文件、包含多个实现点、覆盖多个验证点;只要这些工作共同服务于同一个玩家能力,并且通常需要一起实现、一起验证,就应该合并在同一个 todo 里。不要按 parser / renderer / input / animation / UI (User Interface, 用户界面) 技术横切层机械拆 todo;纯数据、渲染、音频、面板、资源绑定等支撑工作默认并入能证明玩家路径的 slice。
+
+**slice 完成边界**:一个 slice 完成后,游戏在最小循环上前进了一个**可观测节点**——玩家从状态 A 转移到状态 B,A 和 B 都是循环上的可判状态(例如"无棋盘→有棋盘""不可点击→可点击消除""无攻击→飞弹击中砖块")。"让反馈更丰富""让游戏更好玩""把剩余 VFX 都接上"不是 slice 的完成目标,这些属于后续打磨。如果一个 todo 的 acceptance 不是"循环前进了一节点",而是"游戏完整了 / 反馈齐全了 / 体验好了",说明它把完整游戏体验当成了 slice 目标,会自然把所有剩余反馈一次性塞进去。
+
+**主附玩法切片顺序**:当 design.md 包含主玩法 + 副玩法的融合结构时,不要一个 todo 把主附玩法一次做完。切片顺序应该是**主 → 副+融合**,不是"主→副→融合再切碎"。把融合点切碎到后续多个 todo 里,最后合并的代价远大于一开始就让副玩法带着融合一起做。主玩法切片先把核心循环本身跑通(例如箭头消除循环),副玩法切片把副玩法实体和它与主玩法的融合链路一起做完(例如怪物实体 + 箭头飞出→命中怪物 + 砖块破坏,这是一整个副+融合切片,不再拆开)。这样每个切片完成后都是一个可独立验证的增量,融合点的难度被控制在单次切片内,不会跨 todo 累积。
+
+**融合点作为独立设计对象**:主副玩法之间的融合点不是主玩法或副玩法的附属,是独立的设计对象——主玩法产出的状态如何驱动副玩法、副玩法的变化如何反馈到主玩法决策。这部分需要 context 主动设计,不是 scaffold 自动产生。它要解决的是衔接处的体验过渡和状态转译。融合点切片的 acceptance 应该聚焦"融合链路本身是否成立",不用重复验证主玩法和副玩法各自的正确性(已在前面切片验证过)——这是"主→副+融合"切法的好处:降低融合切片的验证复杂度。
+
+**slice 最小可验证的判断**:一个 slice 是否"最小可验证",看的是它是否已经形成一个适合单独派发和单独验收的功能点,而不是看它改了多少文件、写了多少代码。可从这些角度判断:
+
+- **功能点是否完整**:做完后能明确回答"玩家新增了什么能力",例如"能点击箭头并得到成功/失败反馈",而不是"多了一个 parser"。
+- **验证是否成闭环**:虽然可以有多个检查点,但这些检查点合起来应服务同一个验收结论。若必须把 A/B/C 都做完才能证明这个功能点成立,那它们通常应该是同一个 todo。
+- **实现是否天然耦合**:如果几个实现点共用同一个 atom 的核心代码、同一条运行时链路或同一组关键状态,拆开后只会让后续 todo 重复读同一批 ref、重复验证同一条链,那应合并执行。
+- **拆开后是否仍可独立验收**:若拆开的子项各自都无法单独给出有意义的通过/失败判断,只是等待兄弟 todo 补完,说明已经拆过细。
+- **合并后是否仍是单一玩家能力**:如果一个 todo 同时覆盖两个互相独立的玩家能力,任一能力都可以单独派发/单独验证,那说明又合得过粗,应该拆开。
+
+可验证不等于都必须肉眼看到完整交互;它至少要能从某个维度给出基础验证信息:
+
+- **设计追踪**:能回链 `docs/design.md` 的最小核心交互循环片段,说明兑现哪个玩家承诺。
+- **静态合约**:文件/模块/API/config/event/payload/asset binding 是否存在且名称一致。
+- **运行时合约**:`window.__playable`、状态机、事件流、输入处理或自动演示 hook 是否能证明路径可达。
+- **状态变化**:输入、匹配、消除、进度、成功/失败等至少一个关键状态转移可被脚本、日志或调试入口观察。
+- **构建/类型/资源链**:build/typecheck、source -> preload -> display、无 404 或 manifest 证据。
+- **自动演示准备度**:说明本 todo 暴露或保留了哪些玩家动作等价入口,或为什么暂不接入但不阻断后续 runtime harness;不得把直接写终态、调用胜利函数或跳过规则当作自动演示。
+
+纯功能清单不是合格 todo;例如只列"禁止输入、射击、匹配检测、消除"会拆断核心交互循环,除非这些项合起来就是同一个功能点,并且共享同一套验收证据。若两个技术项只有合在一起才能证明一段玩家路径,或它们都依赖同一个 atom 的核心实现并适合一次性验证完,就合并为同一个 slice。`npm run dev` 只能作为打开运行环境的步骤,不能单独作为 verifier。
+
+**切片数量**:默认 1-5 个 todo 收住迭代1核心玩法闭环。主附融合场景下,由于副+融合切片本身承载了较多工作,切片数允许到 **6 个**——前提是每个切片都有独立可验证的增量,不能为了凑数而拆。
+
+### 边界
+
+**自动演示边界**:context 只要求核心交互 todo 保留可被外部驱动的玩家动作入口或输入路径。不要把自动演示、通关验证、录屏验证写成玩法机制、任务目标或 verifier;这些属于编排侧在 generate 末尾/optimize 阶段注入的 runtime harness 工作。不得要求 developer 直接设置 removed / win / lose / ENDCARD,调用胜利函数,或在玩法规则里新增专用 shortcut。
+
+## 输入
+
+- `docs/design.md`(已确认的最小核心交互循环,本阶段主输入)
+- `docs/design-brief.md`(过程日志,只用于追溯来源 / 候选 / skill 探索发现)
+- `docs/atom-tree.json`(Atom 引入中间文件;如不存在,由 `playcraft skills init-atom-tree` 生成)
+
+## 必读 Skill
+
+- `playcraft-skill-recommender` — context 阶段主 skill。用于探索候选、刷新 match、选择 atom、link/scaffold,不读它就不要写 skill 选型与 scaffold 判断。
+- context 阶段不选择最终 runtime win、recording 或 delivery verifier。todo 的 `verifier` 只描述本玩家能力 slice 的基础证据;如果证明对象已经变成自动通关链路、录屏或交付闭环,不要在 context 里写命令名,由 orchestrator 后续系统 todo / optimize flow 处理。
+
+## 关键步骤
+
+1. **探索候选 + 刷新 match 快照 — 由 recommender 教学驱动**
+   - 加载 `playcraft-skill-recommender`。先用 `gettags` / `filter` / `match` 探索候选,不要一上来 `select-atom`。
+   - 从 `docs/design.md` 的最小核心交互循环提取 intent 关键词(genre / core action / feedback / progress)。可以先跑 `match` 看完整推荐;确定 intent 和倾向 engine 后,再用 `init-atom-tree` 刷新 `docs/atom-tree.json` 的 `meta.skillsMatch` 快照:
+     ```bash
+     playcraft skills gettags --category gameplay --json
+     playcraft skills filter --category gameplay --tags "<candidate-tags>" --json
+     playcraft skills match --intent "<genre,core-action,feedback,progress>" --engine <phaser|threejs> --json
+     playcraft skills init-atom-tree --intent "<genre,core-action,feedback,progress>" --engine <phaser|threejs>
+     ```
+   - 此时 `docs/atom-tree.json` 只是 Atom 引入中间状态,只有 `meta.skillsMatch` 快照,还不代表已选定 atom。不要把 match 结果直接当 selectedAtoms。
+   - 不手写 atom-tree 作为任务计划或执行状态。除非工具命令缺口导致必须小范围修补 selection metadata,否则只通过 `playcraft skills` CLI (Command-Line Interface, 命令行界面) 更新 `docs/atom-tree.json`;修补时必须说明原因,不得手写完整树。
+   - 如果多轮 filter / match 没有强相关 atom,不要假装匹配成功;在对应 todo card 的 `Skill Use` 中记录 no-match reason、fallback strategy 和 confidence,再按 `design-only` 或最小自实现拆 slice。
+   - TODO(C2):把这串命令封装成 context 阶段脚本,避免手工选择 atom 时漏掉 validate/link。
+2. **筛选候选 — 分层读取,禁止探索期批量深读**
+   - 从 `meta.skillsMatch.items` / `mediaGroups` 和 filter 结果中筛候选。先看轻量头(名字/Tags/DESC/role/engine 级),只对**强相关**的 atom 执行 `inspect` / `read` 并深读其 `ref/` 源码,提取真实 API (Application Programming Interface, 应用程序编程接口) / config / 事件 / 资产引用。
+   - **铁律**:读 SKILL.md ≠ 了解 atom,以 `ref/` 源码为准(与 developer role "Read Before You Change" 一致)。
+3. **评分筛选** — 维度:Tags 匹配 / DESC 语义 / 复用程度 / 依赖完整性。玩法规则类 atom 要拆"实体层 / 机制层"分别评分(实体层元素相同即可复用,别因机制层不匹配整体判 0)。
+   - 复用等级只使用 `.claude/agents/refs/atom-skill-library.md` 定义的 `scaffold` / `reference` / `design-only`,不要在 flow 内另造等级。
+   - 引擎不一致不会直接淘汰 atom,但不能高估复用等级;除非 ref 源能证明可直接迁移,否则不要标 `scaffold`。
+   - 对每个强相关 skill 做范围分类:
+     - `core-now`:兑现 `docs/design.md` 最小核心交互循环必需,可进入 selectedAtoms / todo。
+     - `support-if-cheap`:支撑核心路径,但不能单独扩大范围;只能并入已有 slice,不能新增 acceptance。
+     - `later-packaging`:去掉它玩家仍能完成核心循环、只是觉得没那么爽的内容——Hook、教程包装、EndCard、CTA (Call To Action, 行动召唤)、下载按钮、BGM (Background Music, 背景音乐)、SFX (Sound Effects, 音效)、角色反应、视觉终稿、反馈增强类 VFX / 动效等。判别判据是"去掉后循环是否仍能转":能转就是 later-packaging。只记录候选,不 seed 迭代1 todo。
+     - `reject/noise`:传递依赖、主题不符或会引入未确认玩法;记录原因,不得下沉到任务卡。
+4. **select atoms + 依赖链解析** — 基于评分结果执行 `select-atom`,让工具补齐硬依赖并写入 `meta.selectedAtoms`;此后才进入 validate/link:
+   ```bash
+   playcraft skills select-atom --id "<atomId1,atomId2>"
+   playcraft skills validate-atom-tree-selection
+   playcraft skills link --from-atom-tree --prune
+   playcraft skills gen-atom-tree-md
+   ```
+   `meta.selectedAtoms` 是 Atom 引入的桥接输入,供 `link --from-atom-tree` 和 `playcraft remix init-template --from-atom-tree` 使用;没有 selectedAtoms,不要 link / scaffold / init-template。
+   `link --from-atom-tree` 会把 selected atom 软连接到项目内 `.claude/skills/<atomId>/`,并维护 `.claude/skills/.playcraft-dag-links.json`。后续任务卡和机器态 `requiredContext` 必须优先写项目内路径,不要只写 atomId 或让 developer 自己全仓搜索。
+5. **锁定引擎 / 核心动作** — selectedAtoms 与 engineDecision 已确定运行时引擎(skill 选型天然绑定引擎)。把引擎和核心动作锁进全局不可变决策,后续拆 todo 与 generate 都据此:
+   ```bash
+   npm run state:set -- sharedDecisionsPatch='{"engine":"phaser","coreAction":"tap-to-clear"}'
+   ```
+   这是 generate 之前唯一锁引擎的时机;锁定后不可在 generate 阶段更改。
+6. **初始化项目模板 / 必要 scaffold** — 这一步发生在 selectedAtoms validate + link 之后。先用 atom-tree 中间产物初始化项目模板,让 engine/layout/input/render 基座按 selectedAtoms 落地,而不是手写替换 placeholder:
+   ```bash
+   playcraft remix init-template --from-atom-tree
+   ```
+   如仍有 `scaffold` 级 atom 没有被模板落地,再按 recommender 的 scaffold 教学处理。先 `inspect` 确认文件,再 `--dry-run`,最后才落地:
+   ```bash
+   playcraft skills inspect "<atomId>" --json
+   playcraft skills scaffold --engine <phaser|threejs> --atoms <atomId1,atomId2,...> --out ./src --dry-run
+   ```
+   记录 `init-template` / scaffold 实际落地文件或 blocker。若有 `docs/scaffold-manifest.md`,后续 todo 的 `requiredContext` 必须包含它,让 developer 先知道哪些文件已由哪个 atom 落地。engine 基座未落地时不要把 generate todo 写成"实现完整游戏";应先补初始化 blocker 或拆一个明确的 setup todo。
+7. **按玩家路径纵向拆 todo** — 每个 todo = 一个可独立派发、能说明"做完后项目多了什么可玩能力"的功能点,且必须在 `docs/todo_list.md` 有一张同名完整任务卡。默认目标是 **1-5 个 todo 收住迭代1核心玩法闭环**(主附融合场景可到 6 个)。slice 的定义、完成边界、主附切片顺序、融合点设计、切片数量等判断标准见 § 目标「拆 todo 的原则」;步骤这里不重复,按那节概念判断。任务卡字段:
+   - `title` — 机器态和派发总览里的短标题,用于调度者识别任务。
+   - `goal` — 一句话说明本 slice 完成后,玩家路径新增什么能力。
+   - `context` — 机器态 todo 中的任务卡镜像:从 `docs/todo_list.md#todo-<id>` 提取 Scope / Skill Use / Context Reuse / Acceptance / Verifier 等关键语义,保证 dispatch 展开时不丢信息。`Skill Use` 不能只列 ref 路径,必须写清 atom 对本 slice 的引用价值,让 developer 看任务卡就能判断为什么值得采用 scaffold / ref。
+   - `contextReuse` — 可选的复用 key。当多个 developer todo 连续使用同一批大段设计 / atom ref / scaffold 源时填写同一个值;为空表示不可复用。复用细节仍写在任务卡 `Context Reuse` 小节中,不得暗示一次做多个 todo。
+   - `acceptance` — 做到这就停的可验证条件,必须写明验证维度和基础证据
+   - `verifier` — 建议验证器或证据说明(如 `verify:contract`;没有现成脚本时写明代码审查点、状态日志、截图/录屏或操作步骤 + 预期结果)。写脚本名之前先读对应 skill,确认它实际检查的对象、产物路径和通过条件。
+   - `role` — 建议角色(generate 阶段一般 developer)
+8. **落盘 + seed 池** — 先写 `docs/todo_list.md` 完整任务卡,再把每个 todo 镜像进机器态 todo 池。不要跳过 `docs/todo_list.md` 直接写薄 todo;机器态 todo 的 `context` 必须从对应任务卡抽取完整切片语义,`requiredContext` 第一项保留任务卡锚点,再附上必要 design section 和 skill ref:
+   ```bash
+   npm run todo:add -- id=<id> role=developer title="..." \
+     goal="玩家路径新增什么能力" \
+     contextFile=<path-to-extracted-task-card-or-context> \
+     acceptance="feedback visible;progress+1" verifier=verify:contract \
+     requiredContext="docs/todo_list.md#todo-<id>;docs/design.md#<section>;<docs/scaffold-manifest.md-if-present>;.claude/skills/<atomId>/SKILL.md;.claude/skills/<atomId>/ref/<key-file>" \
+     contextReuse="<shared-key-or-empty>" \
+     createdBy=game-designer
+   ```
+   `contextFile` 可指向临时抽取文件,内容应来自同名任务卡,避免命令行摘要化导致信息丢失。
+   多个 todo 必须按计划顺序串行 `todo:add`;不要并行 seed。`contextReuse` 的连续复用判断依赖 todo 池顺序,并行写入只保证状态原子性,不保证业务顺序。
+   本阶段 game-designer 在 canWriteTodo 白名单内,seed todo 池是你的核心动作。
+
+## 产出物
+
+- `docs/atom-tree.json` — Atom 引入中间文件:记录 match 快照、selectedAtoms 与引擎选择,供 link / init-template / scaffold 使用;不承载 todo、handoff 或执行状态。
+- `docs/atom-tree.md` — 可选的人读 companion,由 `gen-atom-tree-md` 从中间状态生成;不作为第二份真源,不手写执行计划。
+- `docs/todo_list.md` — 计划等价物:按 todo 分组的完整任务卡。
+- 机器态 todo 池 seed 完成(派发和状态载体,调度者 `state:get` 读、派活用)。
+
+todo_list.md 结构:
+
+```markdown
+# 技术 TODO — {游戏名}(迭代1)
+
+## 派发总览
+
+| id  | slice | title | contextReuse | acceptance | verifier |
+| --- | ----- | ----- | ------------ | ---------- | -------- |
+
+## 已选 Skill 合同
+
+只列 `select-atom` 后被当前 todo 使用的 atoms。未选择候选、弱相关、待定候选、later-packaging、传递依赖不在主表披露。
+
+| atom | reuseLevel | usedBy | scaffoldValue | mustPreserve | sourceOfTruth |
+| ---- | ---------- | ------ | ------------- | ------------ | ------------- |
+
+## 缺口
+
+### 软槽位未填充
+
+只列会阻塞当前核心 slice 或必须在 generate 阶段显式处理的 slot。later-packaging 类 slot(包装、音频、面板、角色、CTA、反馈增强 VFX / 动效等)不列入本节——它们属于后续迭代,不进当前 todo 的视野。
+
+| slot 所属 atom | slot 名 | role | 处理方式 | 影响 |
+| -------------- | ------- | ---- | -------- | ---- |
+
+## TODO <id> — <玩家可感知任务名>
+
+### Goal
+
+{一句话:本 slice 完成后,玩家路径新增什么能力。}
+
+### Scope
+
+- Player-facing capability:{这个功能点做完后,玩家现在能做什么 / 看到什么 / 理解什么}
+- Included work:{为闭合这个功能点必须一起完成的支撑工作,例如同一 atom 的核心状态、输入、渲染、反馈链路}
+- Done boundary:{做到什么程度就停,交给 Acceptance / Verifier 判定}
+
+### Skill Use
+
+| atom             | scaffoldValue                          | use                                                                                          | mustPreserve                                | sourceOfTruth                     |
+| ---------------- | -------------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------- | --------------------------------- |
+| <selectedAtomId> | <它为本 slice 省掉/稳定了什么实现风险> | <adopt-scaffold/configure-scaffold/extend-scaffold/use-as-reference/reject-for-slice + 用法> | <必须保留的 API/event/config/asset binding> | <SKILL/ref/manifest/落地文件路径> |
+
+- `scaffoldValue`:写当前 todo 为什么值得引用该 atom,例如“提供 rows×cols 到屏幕坐标的稳定映射,避免本 slice 重新实现棋盘布局数学”。不要只写“参考 ref”或“使用 scaffold”。
+- `use`:如果 context 已经执行 scaffold,写 `adopt-scaffold` / `configure-scaffold` / `extend-scaffold` 中的一种,并说明应使用的入口;如果只是参考或不适用,写 `use-as-reference` 或 `reject-for-slice` 的条件。developer 可按实际代码降级,但必须在 handoff 记录原因。这里的 `use-as-reference` 是本 todo 的采用方式,不要和全局 `reuseLevel=reference` 混淆。
+- `sourceOfTruth`:优先列 `docs/scaffold-manifest.md`、项目内 `.claude/skills/<atomId>/SKILL.md`、关键 `.claude/skills/<atomId>/ref/...` 源和已落地文件。路径服务于重新读取,价值判断必须写在 `scaffoldValue`。不要只写 atomId、`playcraft skills read` 命令或外部 skills 包路径;developer 的稳定入口是项目内 `.claude/skills/<atomId>/`。
+
+### Context Reuse
+
+- key: <共享上下文 key;不可复用时写 none>
+- sharedContext: <可沿用的设计章节 / atom ref / scaffold 源>
+- mustReRead: <本 todo 必须重新读取的任务卡、设计小节或新增 ref>
+- invalidatesWhen: <哪些变化会让调度者不得复用,如 blocker / engine 变化 / selected atom 变化 / allowedFiles 跨域>
+
+### Acceptance
+
+- [ ] <验证维度>:<基础证据或 verifier 能判断的条件>
+- [ ] 自动演示准备度:如本 todo 涉及核心交互入口,必须保留可被外部驱动的玩家动作等价路径,不得直接设置 removed / win / lose / ENDCARD 或调用胜利函数。
+
+### Verifier
+
+- `npm run <script>` 或人工/代码审查证据说明。不要只写 `npm run dev` 或"手动验证";若需人工观察,写清操作步骤、预期状态和留下什么证据。最终 runtime win / recording / delivery verifier 不在 context 阶段选择。
+```
+
+## 评价(退出判据)
+
+对应 spec `context.exit`:
+
+- todo 池数量控制在 **1-5 个**(主附融合场景可到 6 个),并且**覆盖核心玩法闭环成立所必需的关键功能点**,不是完整游戏实现清单。
+- todo 按玩家路径纵向切片,不是按 parser / renderer / input / animation / UI 技术横切层机械拆分;支撑工作已并入能证明玩家路径的功能点,或有明确单独成 todo 的阻塞理由。
+- skill 已按 `core-now` / `support-if-cheap` / `later-packaging` / `reject/noise` 分类;只有 `core-now` 直接 seed todo,后续包装类 skill 没有进入迭代1 todo。
+- selectedAtoms 已由 `select-atom` 写入,且 `validate-atom-tree-selection` / `link --from-atom-tree --prune` 已完成;项目模板已通过 `playcraft remix init-template --from-atom-tree` 落地,或有明确初始化 blocker / setup todo。
+- atom-tree 只被用作 Atom 引入中间产物;任务计划、验收、上下文复用和执行状态都落在 `docs/todo_list.md` / 机器态 todo / handoff 中。
+- 每个 todo 的 `acceptance` 写明验证维度和基础证据(不是"做个 X"或"npm run dev 手动看"这种没法验的空目标)。
+- 每个 todo 的 `verifier` 都是本 slice 的基础证据,或明确写成人工/代码审查证据说明;不能只抄命令名,也不能把最终 runtime win / recording / delivery verifier 提前写入 context todo。
+- 每个 todo 在 `docs/todo_list.md` 都有同名任务卡,且机器态 todo 的 `context` 镜像该任务卡关键语义。
+- 需要上下文复用的连续 todo 必须填写同一个 `contextReuse`;不可把上下文复用写成合并执行。
+- 已选 skill 只披露 selectedAtoms 中被当前 todo 使用的项;任务卡 `Skill Use` 与机器态 todo 的 `context` / `requiredContext` 能让下游 developer 按图复用而非重造。
+
+## 反模式
+
+- 同一个功能点依赖同一个 atom 核心实现、同一条状态链路、同一组验证证据,却被人为拆成多个 todo,导致实现和验证必须捆绑进行。
+- 在 `docs/todo_list.md` 主体披露未选择候选、弱相关技能、需从零实现清单或可选/待定候选,导致 developer 误以为都要执行。
+- 按功能列表拆 todo,但每个功能都没有验证维度、基础证据或 design trace,导致 generate 无法证明核心玩法。
+- acceptance 写成无法验证的主观描述。
+- verifier 只写 `npm run dev` / 手动验证,没有操作路径、预期结果或留存证据。
+- 只在机器态 todo 里写一句摘要,没有 `docs/todo_list.md` 任务卡全文,导致 developer 拿不到 context 阶段的计划细节。
+- 手写或反复编辑 `docs/atom-tree.json` / `docs/atom-tree.md` 来承载任务计划、执行日志、handoff 或验收状态,导致 atom 引入中间产物变成第二套计划源。
+- dispatch 时手抄 todo 摘要,绕过 state 中 active todo 的 `context` 展开,或漏掉 `docs/todo_list.md#todo-<id>` 任务卡引用。
+- 给 todo 填 `contextReuse`,但任务卡没有稳定 key / mustReRead / 失效条件,导致 developer 复用过期上下文。
+- 探索期就批量深读 atom 源码,把 context 拖成实现阶段。
+- 拆 todo 时引入 design.md 里没有的玩法(越过 ideate 的确认)。

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

@@ -0,0 +1,91 @@
+# 迭代1 · generate flow(生成)
+
+> 阶段执行序文档。角色:developer。被 `pipeline/iteration-1-core.mjs` 的 `generate.flowRef` 引用。
+>
+> developer 的稳定职责(atom skill 复用、Read Before You Change、Self-Check)在 `.claude/agents/developer.md`。本文件只写这阶段的任务循环、产物、评价。
+
+## 目标
+
+按 todo 池**分玩法**生产代码。每个 todo 只完成 dispatch 展开的 `context` 里那一个清楚增量,并按它的 `acceptance` / `verifier` 留下证据;不越界做 CTA / 包装 / 视觉。本迭代结束前 todo 池**必须清空**。
+
+## 调度关系
+
+developer 看不到 todo 池全貌——调度者从池里挑一个 todo,收窄成 `state.dispatch`(一份工单)写进 state,developer 只 `npm run state:get -- --json dispatch` 读这一份。干完调度者再挑下一个,直到清空。
+
+### 上下文复用模式
+
+当调度者用 `sendMessage` 恢复同一个 developer 会话并说明命中 `contextReuse` 时,developer 可以复用上一 todo 已经读过的共同设计 / atom ref / scaffold 源,但必须遵守:
+
+- 重新运行 `npm run state:get -- --json dispatch`,以新的 dispatch 为准。
+- 必须读取新 dispatch 展开的 todo `context`。
+- `requiredContext` 中未读过或发生变化的路径必须补读;不能只靠记忆做新 todo。
+- 每个 todo 仍单独实现、验证、`handoff:append`;不要因为上下文相同而提前做后续 todo。
+- 如果发现新任务与旧上下文冲突,或 `allowedFiles` / selected atom / engine 假设变化,STOP 写 blocker,让 orchestrator 普通重派。
+
+## 任务循环(每个 dispatch 走一遍)
+
+1. **define active target** — 从 dispatch 读 `goal` / `acceptance` / `allowedFiles`;干活前先认定这个 todo 要证明的增量和证据。
+2. **read inputs**(role 纪律已覆盖) — 先读 `npm run state:get -- --json dispatch` 中展开的 `context`,再按 `requiredContext` 读取当前 `docs/todo_list.md#todo-<id>` 任务卡、设计文档、现有代码、已引入的 skill ref/scaffold 源;改前先读,`ref/` 源权威。上下文复用模式下也必须读新 todo context 与未读过的 `requiredContext`;不要只读标题和 goal。
+3. **confirm boundary** — 列将改文件(必在 `allowedFiles` 内);确认本 todo 能按 dispatch context 的证据说明完成。若任务同时包含音频、build、完整游戏循环、first playable、录制等多个目标,或只写 `npm run dev 手动验证`,STOP 写 blocker,让 orchestrator 回 context 拆分 / 补证据,不硬猜。
+4. **implement scoped closure** — 只做 acceptance 所列;不加表面分支掩盖不清的状态模型;不碰 `forbiddenTasks`。
+5. **validate locally** — 跑 dispatch 的 `verifier`(如 `verify:contract`)或按 dispatch context 的证据说明验证。`npm run dev` 只证明环境能打开,不能单独作为 done 证据;人工观察必须写清操作路径、预期状态和结果。
+6. **STOP 记账** — 只 `handoff:append`(summary + acceptanceResults / blockers;有产物路径仍可放 handoff artifactRefs)。todo 状态由 orchestrator 读 handoff 后执行 `todo:set`,developer 不自验收。
+
+### 系统 firstwin harness todo(调度者注入)
+
+context 结束后、进入 generate 前,orchestrator 基于已 seed 的 todoPool 检查当前迭代是否已有 `firstwin-harness` 或等价 `verify:firstwin` todo。若没有,用现有 `todo:add` 追加一个系统 todo:
+
+```bash
+npm run todo:add -- id=firstwin-harness role=developer \
+  title="接入 first win 自动验证链路" \
+  goal="让当前核心玩法可通过平台 runtime harness 自动跑到首胜终态" \
+  context="只接平台 runtime harness:暴露 autoPlay/getState,通过玩家动作等价入口驱动已实现玩法,不得直接写终态或补包装。" \
+  requiredContext="skills/playable-autoplay/SKILL.md;docs/design.md;game/**" \
+  acceptance="window.__playable.autoPlay() exists and is wired through the debug-gated trigger;window.__playable.getState() returns currentPhase and isGameOver;autoPlay drives player-equivalent input or controller actions instead of direct terminal-state writes;npm run verify:firstwin exits 0" \
+  verifier=verify:firstwin createdBy=orchestrator-system
+```
+
+这个 todo 不写入 `docs/todo_list.md`,也不需要 atom ref。generate 正常按 todo 逐个派发;当 developer 收到 `firstwin-harness` dispatch 时,先读 `skills/playable-autoplay/SKILL.md`,再只接平台 runtime harness:
+
+- 暴露 `window.__playable.autoPlay()` 与 `window.__playable.getState()`。
+- 让 autoPlay 通过玩家动作等价入口或外层控制器驱动已实现玩法。
+- 用 `npm run verify:firstwin` 自证。
+- 不改设计、不补包装、不录屏、不写专用胜利 shortcut,也不直接写 ENDCARD / isGameOver。
+
+## 本阶段特有权限
+
+generate 阶段 developer / reviewer 在 canWriteTodo 白名单内。当你发现 dispatch 没覆盖、但明显属于本阶段范围的活,可加 todo(只加本阶段范围内的):
+
+```bash
+npm run todo:add -- id=<new-id> role=<role> title="..." goal="..." context="..." acceptance="..." createdBy=<your-role>
+```
+
+不要加越出本阶段(包装/视觉/CTA)的 todo —— 那是后续迭代的事。
+
+## 产出物
+
+- `game/**` — 按玩法逐个交付的可玩代码。
+- handoff 逐个记录产出;todo 池由 orchestrator 逐个标 done / failed。
+
+## 评价(退出判据)
+
+对应 spec `generate.exit`(硬约束):
+
+- **todo 池全部 done,本迭代结束前必须清空**(advanceStage 在 generate→optimize 边界强制校验 `todosCleared`,有 pending/in_progress/failed 残留则 exit 2 拦截)。
+- 每个 done 来自 verifier 结果。
+- 如果没有脚本 verifier,done 必须来自 dispatch context 列出的证据说明,并在 handoff 中记录操作路径 / 代码审查点 / 日志 / 截图 / 录屏等 artifact。
+- 接口契约闭合:emit 都有 listener、payload 一致、资产链 source→preload→display 不断、design 分辨率下无 404。
+- 每个 dispatch 都能展开当前 todo 的完整 `context`,且实现没有绕过其中的 Reuse Contract / Forbidden 边界。
+- 上下文复用 dispatch 只减少重复读共享 ref,不减少新 todo context / verifier / handoff。
+- 核心交互相关实现应保留可被 autoplay 驱动的动作入口或输入路径;暂不接入时要说明不会阻断 optimize 的 autoplay。
+
+## 反模式
+
+- 一次想做完所有 todo(应一个 dispatch 一个闭环)。
+- 越 `allowedFiles` 写边界、做 `forbiddenTasks`(CTA/包装/视觉)。
+- 从手写总结标 done 而非 verifier。
+- 把 `npm run dev` 打开页面当作完成证据。
+- 为了省事把多个目标合并完成,导致没有一个目标有清楚证据。
+- 重写没读过的现有代码 / scaffold(丢失它携带的决策)。
+- 只读 dispatch 标题不读展开的 todo context,导致漏掉 atom API / asset binding / design contract。
+- 在上下文复用模式下跳过新 todo context 或把多个连续 todo 合并成一次 handoff。

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

@@ -0,0 +1,214 @@
+# 迭代1 · ideate flow(创意)
+
+> 阶段执行序文档。角色:game-designer。被 `pipeline/iteration-1-core.mjs` 的 `ideate.flowRef` 引用,派发时给路径不复述。
+>
+> 本文件只写**这个阶段按什么序走、产什么结构的物、怎么算做对**。角色的稳定职责(研究契约、脑暴契约、充分性自检、来源标记)在 `.claude/agents/game-designer.md`;MDA / game feel / 五轴等框架材料按需查阅,不作为迭代1必读前置。
+
+## 目标
+
+把一句话需求,经研究 + 脑暴 + 自检,先形成**完整游戏玩法预期**,再从中收敛出**最小核心交互循环**,最终产出 `docs/design.md`。`docs/design-brief.md` 是过程记录,只在有助于保留发现、候选、用户输入或取舍时追加;后续流转以 `docs/design.md` 为准。本阶段只把核心交互循环写进 `docs/design.md`;包装、广告节奏、完整教程、复杂关卡和视觉终稿用于帮助判断核心玩法是否站得住,但只作为过程输入,不成为当前设计合同。
+
+**核心交互循环定义**:玩家在一个最小可重复局面中看到什么、产生什么意图、执行什么动作、系统按什么规则响应、给出什么反馈 / 进度信号,以及该反馈如何引出下一次决策或最简成功 / 失败。
+
+**完整游戏玩法预期定义**:designer 需要先判断如果它成为完整 playable,玩家第一眼为什么行动、如何被引导完成第一步、核心局面如何递进、成功 / 失败如何反馈、结束后给玩家什么下一步动机。这是选择核心玩法的判断背景,不是迭代1的实现范围;只有影响候选或取舍的信息才需要进入 brief。
+
+**当前设计合同定义**:`docs/design.md` 只约束玩家目标、核心动作、规则响应、反馈、进度和最简成功 / 失败。Playable Ad Flow(广告体验流:Hook / 教程 / 完整游戏段 / EndCard / CTA, Call To Action, 行动召唤)可以作为思考背景或 brief 过程记录,但不能写进迭代1 `docs/design.md`,也不能把包装候选当作已确认设计合同。
+
+**默认画面方向**:所有 playable 默认按手机竖屏设计;除非用户明确要求横屏。
+
+**Confirmed Decisions 定义**:`Confirmed Decisions` 只记录用户明确确认的决策,或从用户确认内容中直接、必要推出的设计合同项。`[AGENT]` 自答、skill match 结果、引擎选择、实现方案、包装候选和后续增强项不能因为"看起来合理"就写成 confirmed;未确认但暂用的判断写入 `Open Assumptions` 或候选记录。
+
+**融合探索原则**:当用户原始需求包含两个以上强玩法/主题信号时,按 `.claude/agents/game-designer.md` 的 Gameplay Fusion Contract 先提取关键意图,再围绕这些意图做 discovery / skill exploration,基于找到的信息分别探索每个意图能承担的玩法角色,最后才进行融合脑暴并确认主玩法 + 附玩法 / 包装抽象如何关联。不要先按成熟 skill 把复合意图压成单玩法;skill 只能支撑候选落地,不能替代用户意图定义玩法。
+
+**autoplay 边界**:本阶段只定义真实玩家可执行、后续可被模拟的动作语义;不要把 autoplay 写成玩法机制、通关条件或设计合同的一部分。自动演示接入属于 optimize 阶段的行为外挂,只能模拟玩家路径,不能改变核心规则。
+
+## 执行步骤
+
+1. **关键意图提取前置** — 在做 web / skill discovery 前,先从用户原始需求拆出强意图信号(如输入方式 / 目标对象 / 反馈语义 / 视觉题材 / 胜负目标),写入 `docs/design-brief.md` 的 `User Intent Exploration`，这一步只做意图提取和问题定义。
+2. **基于意图的双 discovery**(role 强制) — web research + skill library exploration 围绕第 1 步提取的意图展开,边查边写 `docs/design-brief.md` § Discovery Feed,带 `[WEB]/[SKILL]/[USER]` 来源标记。每个强意图都要探索它可能承担的玩法角色(输入 / 目标 / 反馈 / 规则 / 包装 / 进度);skill discovery 记录的是"哪些意图能被支撑 / 需要转译 / 有缺口",不是直接替用户决定玩法。
+3. **完整游戏玩法预期建模** — 在生成融合候选时,每个候选先写一个简短完整 playable 预期:Hook 如何让玩家理解目标、教程如何让第一步自然发生、完整游戏段如何从 first success 进入一次可完成挑战、成功 / 失败如何反馈、结束动机如何承接。这个预期只服务于判断"核心玩法将来能否扩成完整体验",不得作为单独顶层章节重复展开,也不得直接下沉到 `docs/design.md`。
+4. **融合脑暴与用户确认** — 加载 `brainstorming` skill 取对话协议,基于第 1-3 步已提取的意图、发现的信息和完整游戏预期,生成 2-3 个保留强意图信号的融合候选。按 `读日志→找缺口→自答或发起 state-relay 用户输入→更新 brief→重复` 循环推进;用户偏好和关键分叉要尽早 relay,不要等到写完 design 才确认。落进 `docs/design.md` 的只保留用户确认后的最小核心交互循环。
+   生成候选前,至少过一遍这些启发 lens:First input / Visible carrier / Immediate feedback / Progress signal / Pressure-risk / Twist-differentiation / Fusion strength / 15-30s playable arc。lens 是思考工具,不要求逐项写入 brief。
+   每个候选只写方向卡片,不要写成设计合同:
+   - 一句话候选:玩家做什么,两个强信号如何同时可见。
+   - 完整 playable 可行性:这个方向能否自然长出 Hook / 第一步 / 完成目标,一到两句即可。
+   - 主/附连接:哪个信号承载主动作,另一个信号如何作为目标、反馈、资源或压力接入。
+   - 关键取舍 / 风险:保留什么、弱化什么、最大退化风险是什么。
+     禁止在候选里展开数值、血量、关卡参数、完整反馈链、状态机、失败分支细则或实现式规则;这些只在用户确认方向后进入 `docs/design.md`。
+     给出推荐方案和取舍理由,通过 relay 让用户确认主玩法 + 附属意图的连接方式。用户确认后,把最终选择写入 `Confirmed Decisions`,并在被选候选下追加极短 `Selected Outcome`;未确认候选留在 brief。最终可以是单玩法,但必须是融合后的单玩法:多个强意图被吸收到同一个核心动作 / 目标 / 反馈链中,且主副信号都能从画面与交互中被真实感知。
+     角色是 subagent,不能直接发起用户交互;需要用户输入时,通过 handoff 的 `pendingUserInput` 更新 state,等待编排者问用户并 `sendMessage` 恢复同一 subagent 会话。
+5. **基于确认方向补全核心玩法** — 主/附关系和核心动作确认后,按 `refs/game-designer-gameplay-sufficiency.md` 的 8 角度充分性清单补核心玩法;只有某个角度判断不清或需要更细依据时,才查阅 MDA / game feel / 五轴等框架材料。补全重点包括 MDA (Mechanics, Dynamics, Aesthetics, 机制-动态-美学)、game feel、可读性、first success、胜负和进度等。此时可以主动提差异化方向(爽感放大 / 差异机制 / 情绪曲线 / 视觉辨识),每组含一个"保持标准"选项;补全只能服务已确认的融合方向,不能重新引入未确认玩法作为当前合同。
+6. **充分性自检**(阻塞门) — 跑 `refs/game-designer-gameplay-sufficiency.md` 的 8 角度,任一 ❌ 回到第 3-5 步定点补;**全 ✅ 才能写 design.md**。其中 Playable Ad Flow 角度检查核心玩法能否支撑 first success / near-fail / 成功失败反馈;不要把完整 Hook / 教程 / EndCard / CTA 写成迭代1设计合同。
+7. **design.md 落盘与 handoff 自检** — `docs/design.md` 到这一步才写;自检结论写入 handoff summary。如最后出现新的确认或取舍,可按需补一条 brief 日志,但不补齐章节。
+8. **用户确认** — 编排者向用户确认核心玩法方向(user-confirm 门)。注意 `AskUserQuestion` 会交还控制权、结束本 turn;脑暴中途的多轮问答靠编排者 relay + resume,角色不自行处理跨-session 握手。
+
+## Designer 对 brief 的认知
+
+`docs/design-brief.md` 是 designer 的工作日志,不是报告、不是合同、不是验收清单。它服务于 designer 在 ideate 中保留上下文:当时发现了什么、为什么出现某个候选、用户在哪个分叉上做了选择、哪些假设暂时成立。
+
+designer 写 brief 的原则:
+
+- 只在信息会影响候选、取舍、用户问题或最终设计判断时写。
+- 写当时的判断,不要事后整理成完整说明书。
+- 可以很短,可以缺段落,不需要为了显得完整而补章节。
+- 候选只写方向卡片;完整规则、反馈链、胜负细则留给 `docs/design.md`。
+
+designer 不写 brief 的情况:
+
+- 只是把 discovery 再总结一遍时,不写。
+- 只是把 `docs/design.md` 的规则提前展开时,不写。
+- 只是为了补齐章节名或显得完整时,不写。
+- 自检结论只在 handoff summary 报告,不写整张表进 brief。
+
+## 阶段对 brief 的需求
+
+ideate 阶段的硬产物是 `docs/design.md`。`docs/design-brief.md` 只承担过程追溯作用,不作为阶段退出的硬验收对象。阶段能否退出,看 `docs/design.md` 是否说清核心玩法、用户是否确认、handoff 是否说明自检通过或仍有阻塞。
+
+阶段只要求 brief 满足这些边界:
+
+- 如果 ideate 中发生了关键 discovery、用户选择、候选淘汰或未确认假设,brief 应保留足够线索,方便后续理解设计为什么这样收敛。
+- 不要求存在固定章节,不要求覆盖所有候选,不要求完整复述 discovery。
+- 不允许把 gate / handoff / stage 状态写进 brief;这些属于 project-state。
+- context / generate 默认读取 `docs/design.md`;只有需要追溯取舍原因时才回看 brief。
+
+## Orchestrator Relay 协议
+
+当 game-designer 需要用户确认某个脑暴分叉时:
+
+1. game-designer 追加 handoff,写入机器态 `pendingUserInput`:
+   ```bash
+   npm run handoff:append -- role=game-designer \
+     status=awaiting_user_input \
+     summary="Needs user input for q-core-loop-1 before locking core loop" \
+     artifactRefs="docs/design-brief.md" \
+     blockers="user-input-needed:q-core-loop-1" \
+     pendingUserInput='{"status":"awaiting_user_input","id":"q-core-loop-1","prompt":"Which core loop should we lock?","options":[{"label":"Recommended: tap-to-clear chain","description":"Fastest first-success."},{"label":"Drag-to-place setup","description":"More strategic but slower."}],"recommended":"Recommended: tap-to-clear chain","impact":"Locks the first player action and feedback rhythm."}'
+   ```
+2. game-designer 暂停等待。当前 dispatch 仍然 active,不是任务完成;不要 `dispatch:clear`,不要重新派发,不要新开 subagent。
+3. 编排者读取 `npm run state:get`。当看到:
+   - `pendingUserInput.status=awaiting_user_input`
+   - `orchestratorAction=ask_user_then_sendMessage_to_active_subagent`
+   - `activeTodoId` 仍为当前 ideate dispatch
+     先向用户提问,而不是恢复普通执行。
+4. 用户回答后,编排者记录答案到 state,然后用 `sendMessage` 发回同一个 game-designer subagent 会话:
+   ```bash
+   npm run state:set -- pendingUserInputPatch='{"status":"answered","answer":"<user answer>","answeredAt":"<ISO timestamp>"}'
+   ```
+   再次 `state:get` 应显示 `orchestratorAction=sendMessage_answer_to_active_subagent`;`sendMessage` 内容只转述用户答案和 question id,不替 designer 扩写玩法。
+5. game-designer 在原上下文内继续:把答案写入 `docs/design-brief.md` 的 `Brainstorm Log` / `Confirmed Decisions`,并把当前问题标为 resolved:
+   ```bash
+   npm run state:set -- pendingUserInputPatch='{"status":"resolved"}'
+   ```
+   然后继续脑暴 / 自检 / 产出。本阶段允许 game-designer 只为当前用户输入问题写 `pendingUserInputPatch.status=resolved`;其他流程状态仍归编排者。
+
+最终核心玩法方向确认同样由编排者问。只有用户明确批准 `docs/design.md` 中的方向后,才设置 `userConfirm=confirmed`。中途脑暴回答只是设计输入,不等同于阶段门确认。
+
+## 本阶段特有操作
+
+- **触发 userConfirm 门** — 向用户呈现核心玩法方向、用户明确认可后:
+  ```bash
+  npm run state:set -- userConfirm=confirmed
+  ```
+  只有用户显式批准方向才设;这是 ideate 退出的前置。
+
+> 引擎 / 核心动作的锁定不在本阶段 —— ideate 只发散玩家视角的核心玩法方向,不做技术选型。引擎在 context 阶段随 skills match 确定后才锁(见 context-flow)。
+
+## 产出物
+
+### `docs/design-brief.md` — 过程日志
+
+不是事后写的范围说明,而是**边脑暴边沉淀的过程记录**。brief 只记录对当时判断有用的信息;不追求完整,也不自动进入迭代1 `docs/design.md`。
+
+常见片段如下,按需出现即可:
+
+- `User Intent Exploration` — 把用户原始需求拆成强意图信号,分别探索每个信号可能承担的玩法角色(输入 / 目标 / 反馈 / 规则 / 包装 / 进度)
+- `Discovery Feed` — 围绕强意图信号学到了什么,按 `[WEB]/[SKILL]/[USER]/[AGENT]` 标源
+- `Main/Sub Fusion Candidates` — 2-3 个主玩法 + 附玩法 / 包装抽象 / 附属输入方向卡片。每个候选只写一句话候选、完整 playable 可行性、主/附连接、关键取舍 / 风险;不要写成 `docs/design.md` 的规则、反馈链和胜负细则
+- `Brainstorm Log` — 只记录真实用户分叉问答:问了什么、用户答了什么、它改变了哪个候选或取舍。不是脑暴正文
+- `Confirmed Decisions` — 用户拍板的项,或由用户拍板内容直接、必要推出的设计合同项,标源;不得放引擎、skill match、实现方案、`[AGENT]` 自答增强或包装候选
+- `Rejected Variants` — 用户明确不要的同类变体
+- `Open Assumptions` — 暂定未确认项 + 置信度 + 后续处理;会影响核心规则或 todo 范围的假设不得下沉为设计合同
+
+**机制边界**:brief 不保存 gate/handoff/stage 状态,这些属于 project-state。brief 也不保存完整自检表;需要补设计时,回到对应日志片段补充产生变化的事实或取舍。
+**边界**:brief 不作为下游执行合同;context / generate 默认读取 `docs/design.md` 的核心交互循环,只在需要追溯决策原因时回看 brief。
+
+### `docs/design.md` — 核心玩法体验设计
+
+从玩家体验视角描述**最小核心交互循环**,从 brief 收敛而来。它是后续 context / generate 的设计合同,必须聚焦,不做包装。
+
+文档结构(精简版,迭代1 只到核心玩法):
+
+```markdown
+# {游戏名} — 核心玩法设计(迭代1)
+
+## 一、一句话玩法
+
+{玩家目标 + 核心动作 + 核心乐趣,一段}
+
+## 二、最小核心交互循环
+
+{玩家看到的最小局面 → 玩家意图 → 单次动作 → 系统规则响应 → 玩家可感知反馈/进度 → 下一次决策或最简成功/失败}
+
+## 三、核心规则与玩家可见对象
+
+{从玩家视角:对象、合法/非法操作、状态变化、推进。只写规则语义,不写 API 签名}
+
+## 四、主玩法 / 附属意图连接
+
+{单玩法时说明多个强意图如何融合进同一个核心动作 / 目标 / 反馈链,并写清两个信号分别由什么画面主体 / 目标实体 / 反馈层承载。多玩法时必须明确主玩法、附玩法 / 包装抽象 / 附属输入:主玩法如何完成最小闭环,附属意图何时介入、解决什么节奏或反馈问题,主玩法交互结果如何流入副玩法,二者如何串联成整体;只写用户已确认的组合}
+
+## 五、最简成功 / 失败
+
+{最简胜负条件。成功失败、关卡信息由 skills 自然引导,不在此过度设计}
+
+## 六、核心乐趣与反馈
+
+{乐趣来自哪里;输入→反馈→满足链怎么让玩家感受到}
+```
+
+**边界规则(强制)**:
+
+- ✅ 可写:玩家规则、反馈体验、交互闭环、可读性。
+- ✅ 可在 brief 记录但不写入 design:教程想法、关卡扩展、广告节奏、包装叙事、视觉方向候选。
+- ❌ 不写:Hook、完整教程脚本、EndCard、下载按钮、CTA、广告话术、30 秒投放节奏、BGM (Background Music, 背景音乐) / SFX (Sound Effects, 音效) 终稿或角色表演。
+- ❌ 不写:`src/`/`game/` 文件路径、文件树、类名/函数签名、`interface`/`constructor`/`import`、引擎初始化代码、事件 payload。实现细节留给下游 todo / developer。
+- ❌ 不写:autoplay 专用规则、自动通关条件、测试分支或会改变玩法语义的验证外挂设计。
+- ❌ 不把 brief 中未确认的完整体验发散改写成当前迭代设计合同。
+
+**写完自检(全过才算 design.md 完成)**:
+
+- [ ] 说清了最小核心交互循环:玩家看到什么、想做什么、做什么、系统如何响应、反馈如何引出下一次决策?
+- [ ] 说清了核心乐趣来源,而非只列功能?
+- [ ] 单玩法/多玩法/最简成功失败都覆盖了?
+- [ ] 如用户原始需求有多个强意图信号,design 已说明它们在最终方案中如何被承载或为何被放弃?
+- [ ] 如为多玩法或多机制融合,design 已说清主玩法、附属意图和连接方式?
+- [ ] 两个强信号都能在画面或交互反馈中找到真实承载,而不是一个信号是主体、另一个只存在于命名或解释文字里?
+- [ ] 包装、教程、广告节奏、复杂关卡只留在 brief 候选,没有进入当前 design 合同?
+- [ ] `Confirmed Decisions` 没有混入 `[AGENT]` 自答、引擎/skill 选型、实现方案或包装候选?
+- [ ] 没有把 autoplay 写成玩法机制、通关条件或核心规则?
+- [ ] 没有出现代码/API 签名/文件树?
+
+## 评价(退出判据)
+
+调度者据此判断 ideate 是否可退出(对应 spec `ideate.exit`):
+
+- 8 角度充分性自检全 ✅。
+- design.md 通过上面的写完自检,核心玩法能无歧义说清"玩家做 X → 系统响应 Y → 产生下一次决策 Z"。
+- design-brief.md 如存在,应体现过程日志性质;但不因缺少某个片段阻塞阶段退出。
+- 用户原始需求含多个强意图信号时,最终 design 已说明主玩法 / 附属意图 / 包装抽象如何关联。
+- 最终确认方案里,两个强信号都在玩家可感知体验中有真实承载:至少能指出各自对应的画面主体、目标实体或反馈层,而不是只靠文档命名解释融合。
+- 用户已确认核心玩法方向。
+
+## 反模式
+
+- brief 是事后总结(Brainstorm Log 空,Core Gameplay 却满)。
+- design.md 出现代码/文件树/API。
+- 把引擎、skill match 分数、实现方案或 `[AGENT]` 自答增强写成 `Confirmed Decisions`。
+- 跳过充分性自检直接写 design.md。
+- 没有先形成完整 playable 预期,就直接按某个核心动作写设计。
+- 用户需求明显包含多个强意图信号,但没有分开探索,直接用某个成熟 skill 把需求压成只保留一个信号的单玩法。
+- 多玩法不分主副,把两个玩法并列堆进 design.md,或未说明主玩法交互后的单位 / 状态 / 包装抽象 / 附属输入如何连接就要求用户确认。
+- 把用户强意图词降级成皮肤、背景或后续包装,但没有在 brief 里作为取舍点取得用户确认。
+- 一个强信号承担了所有可见主体、输入和反馈,另一个强信号只存在于比喻、命名或文档解释里,录像里几乎感受不到。
+- 把 autoplay / 自动通关写成玩家规则,导致后续实现为了验证而侵入玩法。
+- 在迭代1 就设计包装/视觉/CTA/复杂关卡。