@playcraft/cli 0.0.56 → 0.0.58

package/project-template-v2/docs/standards/README.md

@@ -0,0 +1,225 @@
+# Standards 文档组织
+
+`docs/standards/` 放目标态标准。这里的文档不是当前 flow 的复述,而是用来校准 role card、flow、skill 使用方式、state scripts 和验证脚本的预期。
+
+## 两类文档
+
+### 1. `agent-behavior-standards.md`
+
+全局 agent 行为评价标准。只写跨迭代、跨 flow 都成立的稳定表现,用于评价“这个 role 像不像这个 role”,不写某个 flow 的执行步骤。
+
+它回答:
+
+- 每个 role 的稳定职责是什么?
+- agent 被派发后通用地应该体现哪些行为品质?
+- orchestrator 与 subagent 的权限边界是什么?
+- dispatch、handoff、state 写入的全局规则是什么?
+- skill 对 agent 是什么关系:何时应考虑使用、使用到什么程度才算合格、何时不能替代判断?
+- 哪些行为在任何迭代都不允许?
+
+它不回答:
+
+- 某个 iteration 的 ideate/context/generate 具体要产出什么。
+- 某个 dispatch 应该带哪些文件路径。
+- `docs/design.md` 在迭代1具体要写哪些章节。
+- 某个 DoD (Definition of Done, 完成定义) key 在某阶段是否必跑。
+
+判断标准:如果一条规则换到迭代2/3仍成立,放这里。如果只对某个 iteration 或 stage 成立,不要放这里。
+
+### 2. `iter<N>-agent-behavior-standards.md`
+
+单迭代 agent 行为评价标准。按 iteration 拆,文档内先写本迭代共享的调度者预期和执行诊断,再按 flow/stage 拆。它不是 flow 手册的复刻,但必须说明该 flow 的预期流程形态,否则无法评价 agent 是否走偏。
+
+建议命名:
+
+- `iter1-agent-behavior-standards.md`
+- `iter2-agent-behavior-standards.md`
+- `iter3-agent-behavior-standards.md`
+
+它回答:
+
+- 本迭代每个 flow 的目标是什么?
+- orchestrator 在本迭代中应如何判断、派发、relay、验收和推进?
+- 派发信息应该满足什么评价标准:role、用户意图转述、requiredContext、allowedFiles、forbiddenTasks、acceptance、verifier。
+- 被派发 agent 在该 flow 里的预期流程是什么,以及哪些行为算走偏。
+- 该 flow 应引用哪些产物评价标准,以及本 flow 对产物有哪些额外边界。
+- 该 flow 的 state 流转是什么。
+- 该 flow 的验证证据是什么。
+- 该 flow 的执行过程是否健康:失败重试、参数错误、耗时异常、read/update/edit 时间分布、上下文准备时长。
+- 哪些当前 flow 与目标标准不一致,需要回改。
+
+它不回答:
+
+- role 的稳定身份定义。
+- 所有 iteration 都通用的 dispatch / handoff 基础协议。
+- skill 的跨阶段通用原则。
+
+判断标准:如果一条规则必须知道“当前是 iteration 1 的 context”才说得清,放 iter 文档。
+
+## 推荐结构
+
+### `agent-behavior-standards.md`
+
+```markdown
+# Agent Behavior Standards
+
+## 写法约定
+
+## <Role Name>
+
+### 预期
+
+### 不应当做
+
+### Skill 覆盖与时机
+```
+
+写全局 agent 标准前,必须先阅读:
+
+- 对应 role card;
+- role card 明确引用的稳定 refs;
+- 标准中点名的 skill 文档。
+
+如果标准里写到某个 skill、某类 skill 或某个工具链能力,必须已经读过对应 skill 或代表性 skill,再抽象成跨迭代评价标准。不能只凭 skill 名称推断职责。
+
+### `iter1-agent-behavior-standards.md`
+
+```markdown
+# Iteration 1 Agent Behavior Standards
+
+## 迭代目标
+
+## 全 flow 执行过程诊断
+
+## 迭代调度者工作预期
+
+## ideate
+
+### Flow 目标
+
+### skill/文档引用
+
+### 派发信息评价
+
+### 预期流程
+
+### 不符合预期的流程
+
+### 产物评价引用
+
+### 本 flow 额外产物边界
+
+### State / Handoff 评价
+
+## context
+
+...
+
+## generate
+
+...
+
+## optimize
+
+...
+
+## wrapup
+
+...
+```
+
+## 去重原则
+
+- `agent-behavior-standards.md` 写“协议和边界”。
+- `iter<N>-agent-behavior-standards.md` 写“本迭代各 flow 的预期流程形态和评价点”。
+- flow 文档仍是执行手册,standards 是验收和校准依据。
+- role card 只保留稳定身份和能力,不写流程剧本。
+- skill 文档只写领域方法,不写 orchestration 决策。
+
+## Flow 标准写作规范
+
+写某个 flow 的标准前,必须先阅读:
+
+- 对应 flow 文档,如 `docs/harness/iteration-1/ideate-flow.md`;
+- 被派发 role 的 role card;
+- flow 明确或隐含使用的 skill 文档;
+- 相关工具脚本或命令说明,如 state、todo、handoff、DoD 脚本;
+- 被引用的 artifact 评价标准。
+
+flow 标准应写“预期流程”,但不能照搬 flow 步骤。推荐写法:
+
+- 用 3-6 条概括该 flow 应呈现的关键行为顺序或判断链;
+- 每条都能判断“做到了 / 没做到 / 做偏了”;
+- 只保留评价所需的信息,不复制命令示例和长协议;
+- 对 skill 的描述写“在本 flow 中应该如何使用”,而不是复述 skill 全文;
+- 对产物只写本 flow 的额外边界,通用质量标准引用 `artifacts/`。
+
+每个 iteration 文档必须有 `迭代调度者工作预期` 章节。它评价 orchestrator 在本轮迭代里是否正确履行控制职责,包括:
+
+- 是否读取 state 并识别 active dispatch / pending user input / stage exit;
+- 是否把当前 stage/flow 收窄成合适 dispatch,而不是替 role 产出内容;
+- 是否正确处理用户 relay、handoff、todo 状态和 stage 推进;
+- 是否没有把调度者视图泄漏给 subagent;
+- 是否能在 blocker / failed evidence 出现时路由或暂停,而不是硬推进。
+
+flow 小节中不再重复写完整调度者职责;只在该 flow 有特殊调度边界时补充一两条。例如 ideate 可以补充“中途 brainstorm answer 不等于最终 user-confirm”。
+
+每个 flow 必须覆盖执行过程诊断。当前推荐把这些异常信号合并进 `不符合预期的流程`,不单独展开成大章节。它评价本 flow 的执行过程是否健康,不只看最终产物。至少覆盖:
+
+- 是否出现某类行为执行失败,失败后是否有原因归类和下一步处理;
+- 是否出现工具/命令参数用错,尤其同一参数错误是否重复发生;
+- 是否有同一 verifier / tool / write 操作多次未通过仍继续硬跑;
+- 是否有单个行为耗时明显过长,且没有产出相称的信息或证据;
+- read、update/edit、工具调用、用户等待、验证各自大约花了多久;
+- 从 dispatch 到“上下文准备好可开始产出”花了多久;
+- 失败和耗时信息是否进入 handoff / run notes,方便调度者判断继续、重派或修改 flow。
+
+这些诊断信息不要求一开始全部脚本化采集,但 flow 标准里要说明哪些异常会被视为不健康执行。
+
+例:
+
+- 可以写:`ideate 应体现 discovery -> brainstorm -> sufficiency check -> core design 收敛;缺任一环节则不应进入 user-confirm。`
+- 可以写:`迭代调度者只负责派发、relay、验收和推进;不应替 subagent 写产物。`
+- 可以写:`ideate 如果连续多次 skill filter 无有效结果,应记录 no-match / low-confidence,而不是继续无目标搜索。`
+- 不要写:把 `ideate-flow.md` 的关键步骤、relay 协议和 design 模板整段复制过来。
+
+## 产物评价标准
+
+产物评价标准单独放在 `docs/standards/artifacts/`。flow 文档和 iteration 标准只引用这些标准,不复制完整内容。
+
+建议命名:
+
+- `design-brief.md`
+- `design.md`
+- `todo-list.md`
+- `atom-tree.md`
+- `game-code.md`
+- `recording-evidence.md`
+
+判断标准:如果内容是在评价“某个产物好不好”,放 artifacts;如果内容是在说明“某个 flow 下 agent 应该如何做”,放 iter 文档。
+
+## Artifact 标准写作规范
+
+artifact 标准只评价产物本身,不评价 agent 是否按流程执行。
+
+推荐结构:
+
+```markdown
+# <Artifact> Quality Standard
+
+## 应当具备的特点
+
+## 不应当具备的特点
+
+## 可接受证据
+
+## 常见低质量信号
+```
+
+写作要求:
+
+- 轻量,能说清楚即可;
+- 不为填章节而列章节;
+- 不写 flow state、dispatch、handoff 细节;
+- 允许写“本产物在某迭代中的边界”,但如果边界只属于某个 flow,优先写在 iter 文档中;
+- flow 可引用 artifact 标准,并补充该 flow 的额外评价边界。

package/project-template-v2/docs/standards/agent-behavior-standards.md

@@ -0,0 +1,174 @@
+# Agent Behavior Standards
+
+> 全局 agent 行为评价标准。这里只写跨 iteration、跨 flow 都成立的判断标准;具体 flow 下要读什么、写什么、交付什么,放 `iter<N>-agent-behavior-standards.md`。
+
+## 写法约定
+
+- 用“预期 / 不应当做 / skill 覆盖与时机”描述标准。
+- 不展开 flow 步骤。
+- 不复制 role card。
+- 不写某个 iteration 的产物结构。
+
+## 全局协议
+
+预期:
+
+- agent 先确认自己是否被派发,再执行任务;主会话保持 orchestrator 身份,具名 subagent 只读自己的 workticket。
+- dispatch 只承载本次工作需要的信息:目标、上下文、可写边界、禁止事项、验收信号和验证方式。
+- role 产物、state 更新、handoff 和用户确认各有边界;完成与推进必须有 artifact、verifier 或明确用户确认支撑。
+- skill 是能力来源和方法约束,不是替代判断的借口;合格使用应能说明“为什么用、用到哪里、采纳了什么、拒绝了什么”。
+- 任何失败、重复重试、参数错误、耗时异常或证据缺口都应进入 handoff / run notes,让调度者能判断继续、重派或暂停。
+
+不应当做:
+
+- subagent 不升级成 orchestrator,不自行决定下一阶段、下一角色或全局 todo 状态。
+- dispatch 不泄漏完整 stage spec、todo pool、调度者内部字段或未来阶段计划。
+- 不把手写总结当作 verifier,不把中途用户回答当作最终 gate 确认。
+- 不在未读上下文、未读 ref 源、未确认边界的情况下产出确定结论。
+
+## Orchestrator
+
+预期:
+
+- 每次接管先读 state,再判断 active dispatch、pending user input、todo pool、stage exit。
+- 能把 stage 目标收窄成一个 role workticket,不把完整流程剧本下发给 subagent。
+- 能区分“继续 active dispatch”“relay 用户输入”“派发新任务”“验收并推进”这几类动作。
+- 根据 handoff、artifact、verifier 和用户确认推进 state,而不是根据自己的口头判断推进。
+- 能识别执行异常,如重复失败、参数错误、耗时异常,并暂停、重派或修改 flow。
+- 信息派发是准确的，没有自行发散
+
+不应当做:
+
+- 不替 role 写设计、todo、代码、视觉产物或 review verdict。
+- 不在 dispatch 中泄漏 stageExit、完整 todo pool、dispatchableRoles、canWriteTodo 或未来阶段计划。
+- 不把中途 brainstorm answer 当作最终 user-confirm。
+- 不在 blocker 或 failed evidence 未处理时硬推进 stage。
+- 不做subagent能拿到信息的复述进行压缩传递
+- 不会外行指导内行自行脑补流程
+- 不读state相关的内容，而是直接使用stat:get来执行驱动
+
+## Game Designer
+
+预期:
+
+- 主动判断是否需要 web research、skill exploration、brainstorming,而不是一股脑全跑或完全不跑。
+- research / skill 获取到的信息能及时沉淀到 brief,并标明来源。
+- 使用 PlayCraft skill 时能分层探索:先看 tag/keyword/role,再 filter/match,必要时 read 强相关 atom,不把一次 match 当结论。
+- 使用 brainstorming 时能批量整理关键问题,提供选项、推荐项和影响说明,而不是开放式逐个追问。
+- 决策前有 discovery 与 brainstorm 记录,不是直接写最终结论。
+- 只描述玩家体验和设计取舍,不写 runtime 文件、类名、函数签名、事件 payload。
+- 对获取的信息能甄别,能说明采纳、拒绝或暂存的原因。
+
+不应当做:
+
+- 把实现计划当设计。
+- 用 skill match 替代玩法判断。
+- 没有用户确认就把假设写成 confirmed。
+- 在未授权 flow 中写 todo、改 state、指定下一个 role。
+- 为了让 developer 好做而改掉已确认的玩家体验。
+
+skill 覆盖与时机:
+
+- `brainstorming`:当需求存在玩法方向、机制、节奏或用户偏好不确定时使用。合格表现是能提出可比较选项,并在用户回答后继续收敛。
+- `playcraft-skill-recommender`:当需要判断已有 atom 能否支撑玩法、或需要把设计转成可复用上下文时使用。合格表现是分层筛选,不是只跑一次 match。
+- `playcraft-research`:当本地 skill 或常识不足以支撑玩法判断时使用。合格表现是把可操作结论写回 brief,而非堆引用。
+
+## Developer
+
+预期:
+
+- 先读 dispatch,再读 requiredContext,确认目标、边界和验收信号后再改代码。
+- 先理解现有 runtime 和已引入 atom/ref/scaffold,不盲改、不重写没读过的代码。
+- 对于引用的atom会阅读其skill，大部份还会愿意去读其ref文件等；对于价值较高的还会直接scaffold
+- 实现保持最小闭环,只满足当前 acceptance。可以做的更完整，但是不因为看了todolist就顺手做未来工作。
+- 写完之后会主动去验证，不直接宣告开发结束
+- 使用 verifier 证明完成,不能用手写总结替代通过证据。
+- 失败时能区分实现 bug、设计缺口、资产缺口、环境问题,并写清 blocker。
+- 在制作的时候是有设计的，而不是硬写
+- 对参考atom的参数、配置等信息会很愿意去了解。不自行脑补参数
+- 对当前的代码有足够的了解才动手，而不是看了一个文件就认为完整了
+
+不应当做:
+
+- 重写设计意图。
+- 未读 atom ref 就接 API (Application Programming Interface, 应用程序编程接口) / event / config。
+- 为了通过验证改玩法语义或 fake success。
+- 创建生产美术、最终资产 manifest 或自审最终质量（可使用placeholder来引入占位图）
+- 越过 allowedFiles 或做 forbiddenTasks。
+
+skill 覆盖与时机:
+
+- `playcraft-skill-recommender`:当需要确认 atom/ref/scaffold 使用方式时使用,尤其 context 已选 atom 后。
+- atom `SKILL.md` + `ref/`:改动前必须读强相关源码;源码优先于说明文档。
+- `playable-record` / `playable-debug` / `playable-validate`:optimize 或 verifier 要求 runtime contract、first win、record、video validation 时使用。
+
+## Artist
+
+预期:
+
+- 产出视觉意图、MC (Master Composite, 主合成图)、ASR (Asset State Reference, 资产状态参考) 或参考 artifact,帮助后续生产判断风格和状态。
+- 根据 design/brief 中的玩家体验和视觉需求工作,不自行改玩法。
+- 输出应能被 TA (Technical Artist, 技术美术) 或 developer 使用,不是装饰性灵感散文。
+
+不应当做:
+
+- 定义 gameplay mechanics。
+- 实现 runtime files。
+- 创建 TA production manifest。
+- 代替 reviewer 判定最终 playable 质量。
+
+skill 覆盖与时机:
+
+- `playcraft-art-style-guide`:当派发风格方向或受众/品类适配判断时使用。合格表现是说明风格为何适配游戏类型、受众、生产成本和 TA 管线。
+- `playcraft-storyboard`:当派发 MC (Master Composite, 主合成图) 或 5 屏体验流参考时使用。合格表现是保证每格为完整 9:16 H5 (HTML5, 超文本标记语言第五版) 视口,并能服务 gameplay / hook / onboarding / endcard / CTA (Call To Action, 行动召唤) 表达。
+- `playcraft-image-generation`:当派发概念图、参考图或孤立素材生成时使用。合格表现是先确认模型、reference image、尺寸、透明/色幕策略,并对失败有回退。
+- `playcraft-asset-state-sheet`:当派发 ASR (Asset State Reference, 资产状态参考) 时使用。合格表现是只为已确认 MC 方案生成 UI (User Interface, 用户界面) / element 状态板,并保证格内元素可被 TA crop 和去背。
+- `playcraft-audio-generation`:当派发音频方向或音频资产时使用。合格表现是区分 SFX (Sound Effects, 音效) / BGM (Background Music, 背景音乐),并记录循环、压缩、响度等后处理需求。
+- 使用上述 skill 时应输出可复用参考、约束和取舍,不只输出漂亮描述。
+
+## Technical Artist
+
+预期:
+
+- 把资产 readiness、路径映射、生产 manifest、集成 blocker 做成可执行、可验证的信息。
+- 每个生产文件声明都有磁盘证据。
+- blocker 应说明原因和 owner,方便 orchestrator 路由。
+
+不应当做:
+
+- 设计 gameplay。
+- 创作 style direction。
+- 实现 runtime integration。
+- 审最终 playable quality。
+
+skill 覆盖与时机:
+
+- `playcraft-image-ops`:当派发 crop、resize、trim、overlay、convert 等本地图像处理时使用。合格表现是按 extract / process / transform / compose / verify 阶段记录输入输出。
+- `playcraft-masking`:当派发去背、分割、蒙版或从 MC / ASR 提取对象时使用。合格表现是能区分 ASR 网格优先 crop、复杂对象用 segment、纯色背景用 floodfill。
+- `playcraft-sprite-sheet`:当派发图集或动画帧合并时使用。合格表现是输出 PNG (Portable Network Graphics, 便携式网络图形) / JSON (JavaScript Object Notation, JavaScript 对象表示法) 坐标元数据,并记录 frame 尺寸、列数和 key。
+- `playcraft-batch-pipeline`:当派发批量处理时使用。合格表现是根据是否有 AI 生成、是否需要并发、是否需要 assemble 选择 Node.js script、batch 或 pipeline。
+- `playcraft-vfx-animation`:当派发反馈特效或动画精灵图时使用。合格表现是按游戏事件选择 VFX (Visual Effects, 视觉特效) / animate 预设,并控制帧数、体积和记录。
+- `playcraft-style-qa`:当派发风格一致性检查或微批次验证时使用。合格表现是先解释 style intent,低信心时提问,微批次低分时停止而不是批量扩散错误。
+- `ta-atlas-deliverable-standard`:当派发 runtime atlas / manifest readiness 时使用。合格表现是 WebP (Web Picture format, 网络图片格式) / JSON sidecar、透明通道、深色背景验证和 atlas coverage 都有证据。
+- 使用工具后应记录输入、输出路径、验证结果和 blocker owner。
+
+## Reviewer
+
+预期:
+
+- 只审证据,不生产证据。
+- 独立读取 artifact、validate result、recording、代码引用或视觉证据,不继承生产者口头结论。
+- verdict 必须映射 acceptance,每个 fail 都有责任归属。
+- 缺证据就是 fail 或 blocked。
+
+不应当做:
+
+- 修改 game code。
+- 生成或替换 assets。
+- 重写 design intent。
+- 只凭观感 pass。
+
+skill 覆盖与时机:
+
+- review / validation 相关 skill:当 dispatch 要求审 evidence package 或视频语义时使用。
+- 不主动发明验证路径;除非 dispatch 要求复现,否则只审已给证据。

package/project-template-v2/docs/standards/artifacts/design-brief.md

@@ -0,0 +1,19 @@
+# Design Brief Quality Standard
+
+评价对象:`docs/design-brief.md`。
+
+## 应当具备的特点
+
+- 是过程记录,不是事后总结。
+- 有 discovery、brainstorm、confirmed decisions、rejected variants 或 open assumptions 中的必要信息。
+- 关键判断带来源标记,如 `[WEB]`、`[SKILL]`、`[USER]`、`[AGENT]`。
+- 用户问题记录能说明选项、推荐项和影响。
+- 能看出为什么最终方向比备选方向更适合 playable ad。
+
+## 不应当具备的特点
+
+- 只有最终结论,没有探索路径。
+- 把未确认假设写成 confirmed。
+- 把 flow state、handoff、gate 状态写进 brief。
+- 记录大量实现细节,但没有玩家意图和玩法取舍。
+- 这里应该只记录原始的信息 & 决策，不应包含太多的思考细节

package/project-template-v2/docs/standards/artifacts/design.md

@@ -0,0 +1,22 @@
+# Design Quality Standard
+
+评价对象:`docs/design.md`。
+
+## 应当具备的特点
+
+- 交互流程详尽准确
+- 玩法的核心规则准确完善
+- 有涉及玩法的完整性/乐趣其来源点。其可能会设计地图设计、关卡设计、概念包装等
+- 玩法的流程应当是完整的，有明确的成功失败规则
+- 有关键启发的atom披露/约定俗成的关键字（如有的话）
+- 对于多玩法有单独的思考设计，有其关联的设计
+
+## 不应当具备的特点
+
+- 描述过于细节
+- 地图等信息就只是自己去发散而没参考atomskill里面的信息
+- 出现代码文件树、类名、函数签名、事件 payload 或 engine 初始化。
+- 只描述主题和美术,没有交互闭环。
+- 写入未确认的包装、CTA (Call To Action, 行动召唤)、复杂关卡或视觉终稿。
+- 成功/失败条件模糊,导致下游只能猜。
+- 写入的信息没价值，只是为了填充章节而写/标准里面有写而写

package/project-template-v2/docs/standards/artifacts/game-code.md

@@ -0,0 +1,41 @@
+# Game Code Quality Standard
+
+评价对象:`game/**` 和支撑运行的项目代码。
+
+## 应当具备的特点
+
+- 实现满足当前 dispatch 的 acceptance,并保持最小可玩闭环。
+- 玩家可见规则、输入反馈、进度、成功失败状态与 `docs/design.md` 一致。
+- 事件、payload、状态流、资产链路 source -> preload -> display 闭合。
+- 有合理的设计 & 拆分，不是一个脚本硬撸
+- 实现记录有记录dev log，其中包含了关键的决策
+- 设计有复用其atom的设计的痕迹
+- 复用 atom 时保留其关键 API (Application Programming Interface, 应用程序编程接口)、event、config、asset binding 或明确记录偏离原因。
+- 复用atom， 但是并不是无脑引入而是了解 & 使用 & 修改，把它真的变成项目的一部份
+- 自动演示入口、运行时合约和验证脚本所需 hook 不与核心玩法互相绕开。
+- 有自动游玩的流程，并且这个是游离于系统之外的辅助脚本。没有侵入游戏基础的设计
+- 代码改动和内容符合当前的设计需求，或完善于设计。但是没有引入其他无关的系统
+- 资产都被正常加载进来了
+- 使用atom提供的图/placeholder来生成图使用，而不是直接图形绘制
+
+## 不应当具备的特点
+
+- 为通过 verifier 而 fake success,但玩家闭环不可达。
+- 重写未读过的 scaffold 或现有模块,导致已有契约丢失。
+- scaffole进来的代码。但是其直接是孤儿
+- scaffold进来了之后，发现其不适合并不删除而是强行写
+- 未能理解原设计，没了解其参数，直接无脑写进去
+- 玩法语义被实现便利性改写。
+- 资产路径、帧名、事件名靠猜测接线。
+- debug / autoplay 代码污染发布路径且没有可关闭配置。
+
+## 可接受证据
+
+- 对应 verifier 通过,并能回链到 dispatch acceptance。
+- 关键 runtime 状态可通过自动演示或录制证据观察到。
+- 代码引用能证明设计承诺实际被使用,不是只写在文档中。
+
+## 常见低质量信号
+
+- build 能过,但 first win、contract 或手动运行无法到达核心成功状态。
+- 多玩法设计存在,但源码只有其中一条玩法路径。

package/project-template-v2/docs/standards/artifacts/todo-list.md

@@ -0,0 +1,41 @@
+# Todo List Quality Standard
+
+评价对象:`docs/todo_list.md` 与机器态 todo 池的一致性。`docs/todo_list.md` 是任务卡质量载体,机器态 todo 是派发与状态载体;任务消费者通过 dispatch view 读取机器态 todo 镜像出的完整任务切片语义。
+
+## 应当具备的特点
+
+- 每个 todo 是一个可独立交付的玩法子任务,不是整局游戏或函数级琐事
+- 每个 todo 都有同名任务卡,并包含 Goal、Scope、Skill Use、Context Reuse、Acceptance、Verifier
+- Reuse Contract 说明选用 atom 的复用等级、关键 API (Application Programming Interface, 应用程序编程接口) / event / config / asset binding
+  - 其引用的 atom skill 对当前 todo 真的有价值
+  - 有说清楚引用的 atom skill 的价值
+- 如 todo 标记上下文可复用,必须包含稳定 `contextReuse` key、可沿用的 shared context、必须重新读取的内容和失效条件
+- 每个机器态 todo 都有 `title` / `goal` / `context` / `acceptance` / `verifier` / `requiredContext`;其中 `context` 必须镜像 `docs/todo_list.md#todo-<id>` 任务卡的关键语义
+- `state:get -- --json dispatch` 能展开 active todo 的完整 `context`,让下游 agent 读到 context 阶段生产的任务切片语义
+- todo做完应该完整可验证
+- acceptance 可验证,能由 verifier、运行时观察或明确证据判断完成
+- todo 池机器态与文档任务卡语义一致,不会一边写 A、一边派发 B
+
+## 不应当具备的特点
+
+- 一个 todo 覆盖整场游戏,或拆到“改某个函数”这种没有玩家可感知闭环的粒度。
+- 一个 todo 的点过于详细，无法验证/其偶合度非常高可以一起做
+- acceptance 是“优化体验”“完善功能”等无法判断通过的描述。
+- 缺少任务卡全文,只在机器态里放一句摘要。
+- 机器态 todo 的 `context` 没有镜像任务卡关键语义,导致 dispatch 展开后仍然信息不足。
+- 引入 `docs/design.md` 未确认的玩法
+- 复用结论只写 atom 名,没有说明必须保留的接口、事件、资产或约束。
+- 标记 context reuse 但没有说明哪些上下文可复用、哪些内容必须重读、何时失效。
+
+## 可接受证据
+
+- 每个 todo 能被 dispatch 精确引用,且 dispatch view 能展开该 todo 的完整 `context`。
+- todo 池非空且覆盖本迭代所有玩法子任务。
+- 每个 todo 的 verifier 与 acceptance 能对应上。
+- `docs/todo_list.md` 中每个 todo 都有同名任务卡;机器态 todo `context` 与该任务卡语义一致。
+
+## 常见低质量信号
+
+- downstream developer 只靠猜测才能知道该读哪个设计章节或 atom ref。
+- 多个 todo 共享大段 ref 但没有标复用,或标了复用却没有写清 must-re-read / invalidatesWhen,导致调度者无法安全 `sendMessage` 续派。
+- 任务卡里的边界为空,导致 generate 阶段顺手做了后续迭代内容。