@playcraft/cli 0.0.57 → 0.0.58

package/project-template-v2/docs/harness/orchestrator-flow.md

@@ -0,0 +1,364 @@
+# Orchestrator Flow
+
+> 调度者运行手册。主会话 agent 读取本文件;具名角色 subagent 不读取本文件。state 用来判断"当前工作应该给谁",不单独判断"当前进程是谁"。
+
+## 入口
+
+主会话每次接管项目先运行:
+
+```bash
+npm run state:get
+```
+
+主会话始终是 orchestrator。用返回值判断下一步控制动作:
+
+- `dispatchedRole` 非空 → 当前已有 active dispatch。主会话不要内联执行角色工作,应恢复/调用对应角色读取 dispatch。
+- `dispatchedRole` 为空 → 没有 active dispatch,按当前 `pipeline.stage` 选择下一步。
+- 状态不明确 → 不猜。先修正 state 或写入明确 dispatch。
+
+具名角色 subagent 的入口是:
+
+```bash
+npm run state:get -- --json dispatch
+```
+
+如果 `dispatch.role` 不是自己,subagent 停止并说明未被派发;subagent 不能升级成 orchestrator。
+
+## 主循环
+
+1. 读 orchestrator view:
+   ```bash
+   npm run state:get
+   ```
+2. 识别 `pipeline.iteration` / `pipeline.stage`。
+3. 读取当前阶段 flow。flow 路径由当前 iteration 决定:
+   - `docs/harness/iteration-1/ideate-flow.md`
+   - `docs/harness/iteration-1/context-flow.md`
+   - `docs/harness/iteration-1/generate-flow.md`
+   - `docs/harness/iteration-1/optimize-flow.md`
+   - `docs/harness/iteration-1/wrapup-flow.md`
+   - `docs/harness/iteration-2/ideate-flow.md`
+   - `docs/harness/iteration-2/context-flow.md`
+   - `docs/harness/iteration-2/generate-flow.md`
+   - `docs/harness/iteration-2/optimize-flow.md`
+   - `docs/harness/iteration-2/wrapup-flow.md`
+     调度者也可从 `state:get` / pipeline spec 暴露的 `flowRef` 确认具体路径;不要在 iteration 2 继续读取 iteration 1 flow。进入 iteration 2 ideate 前,调度者先清空并复制当前 `docs/` 到 `docs-last/`,供后续差异分析使用。
+4. 结合 orchestrator view 中的 `stageExit`、`dispatchableRoles`、`canWriteTodo`、`todoPool`、`stageDod` 判断下一步。
+5. 如果已有 `dispatchedRole`,恢复/调用该角色继续执行当前 dispatch。
+6. 需要新角色执行时,先把当前阶段 flow 收窄成一张角色工单(`dispatch`),再派发对应角色。
+7. 角色 STOP 后,读取 handoff,由 orchestrator 决定 todo 状态、失败处理、继续派发或推进阶段。
+8. 当前 dispatch 已处理完毕后,清空 dispatch;否则主会话重新进入时会继续恢复同一角色。
+
+如果 `state:get` 显示 `pendingUserInput.status=awaiting_user_input`,当前 dispatch 仍 active 但任务暂停等待用户输入。不要清空 dispatch,不要新建 dispatch,也不要新开 subagent;先按"用户确认"里的 relay 协议问用户,再用 `sendMessage` 恢复同一个 subagent 会话。
+
+## Subagent 调用权限
+
+调度者调用具名角色 subagent 时,运行模式必须设为 `bypassPermissions`。这是 subagent 工具调用参数,不是 `state.dispatch` 字段。
+
+- 新建 role subagent 时:使用 `mode=bypassPermissions`。
+- 恢复已有 active dispatch 对应的 subagent 时:仍使用 `mode=bypassPermissions`。
+- 用户 relay 后用 `sendMessage` 恢复同一个 subagent 会话时:仍使用 `mode=bypassPermissions`。
+
+不要使用默认权限模式、只读模式或 ask/confirm 模式派发角色。否则 subagent 可能无法按 `allowedFiles` 写产物、调用项目脚本或追加 handoff,导致流程假性阻塞。
+
+## 角色信息分发协议
+
+派发单位是 `role + title/goal + flowRef + workId`,不是 `stage` 本身。stage 只决定调度者该读哪份 flow、哪些角色可派、退出条件是什么;subagent 只收到自己这次要完成的一张窄工单。
+
+`state:get` 是统一的信息入口:
+
+- 主会话读 `npm run state:get`,获得 orchestrator view。
+- 具名角色读 `npm run state:get -- --json dispatch`,获得自己的 workticket。
+- dispatch 不重复完整 state,只补充"这次派给谁、做什么、读哪里、写哪里、做到什么停"。
+
+调度者在信息阶段的职责:
+
+1. 读取 `state:get` 的 orchestrator view。
+2. 读取当前阶段 flow。
+3. 把阶段目标压缩成本次 `dispatch`。
+4. 调用对应角色。
+5. STOP 后验收 handoff 并更新 state。
+
+调度者不在信息阶段替角色完成产物。尤其:
+
+- ideate 阶段不由调度者写 `docs/design-brief.md` / `docs/design.md`,只派发 `game-designer`。
+- context 阶段不由调度者内联选择 atom、生成 `docs/atom-tree.json`、拆 `docs/todo_list.md`,只把 recommender 教学和产物边界派给 `game-designer`。`docs/atom-tree.json` / `docs/atom-tree.md` 是 Atom 引入中间产物,不是任务计划或执行状态。
+- generate 阶段不由调度者实现 `game/`,只按 todo 派发 `developer`。
+- optimize 阶段不由调度者猜修复方案,先运行 DoD (Definition of Done, 完成定义),再按失败 key 路由角色。
+
+dispatch 里只给执行所需且有明确来源的最小信息:
+
+- 当前 `workId` / `activeTodoId`。
+- 被派发 `role`。
+- 本次 `title` / `goal`。
+- `flowRef` 或等价的 `requiredContext` 路径。
+- 必读上下文中 state 无法推断的文件,例如 `docs/design.md`、`docs/design-brief.md`、相关 skill ref。
+- 可写文件边界:仅当 flow / todo / artifactRules 已明确给出时写。
+- 明确不做的事:仅当 flow / todo / stage 边界已明确给出时写。
+- 停止条件、产物、验证方式。
+
+信息写法优先转述,不要自行扩展:
+
+- `guidance` 只能摘录 / 压缩已有来源:用户原始输入、`state:get`、当前阶段 flow、最近 handoff、已落盘设计文档。
+- `allowedFiles` / `forbiddenTasks` 没有确切来源时不要写;宁愿让字段为空,也不要为"看起来完整"而编造边界或禁令。
+- 不把自己的判断扩写成新玩法、新规则、新技术方案或新执行步骤。
+- 如果必须补一句判断,明确标成"调度判断",且只用于路由 / 边界 / 验收,不替角色产出内容。
+- 不把模糊信息润色成确定结论;缺信息就写成缺口或 blocker。
+
+dispatch 里不要泄漏调度者视图:
+
+- 不重复 `pipeline` / `gate` / `recentHandoffHistory` / `sharedDecisions` 等 orchestrator view 已有字段。
+- 不写 `stageExit` / `dispatchableRoles` / `canWriteTodo`。
+- 不写完整 todo pool。
+- 不写未来阶段计划。
+- 不要求 subagent 判断自己处于哪个 stage / gate。
+- 不要求 subagent 自己决定 next role。
+
+如果 `state:get` 已显示 `dispatchedRole` 非空,主会话只恢复/调用该角色继续当前工单;不要重新解释阶段目标,也不要绕过当前 dispatch 直接生产产物。
+
+## Dispatch 写入规则
+
+调度者写给 subagent 的 dispatch 必须比全局流程窄:
+
+写入 dispatch 后,实际调用 / 恢复 subagent 时必须确认设置参数 `mode=bypassPermissions`;只写 state dispatch 不等于完成派发。
+
+- `activeTodoId` — 当前 todo id;阶段型任务可用 `stage:<stage>` 形式,不要依赖空值表示任务。
+- `role` — 被派发角色。
+- `goal` — 本次只做什么。
+- `guidance` — 从用户输入 / state / 当前 stage flow / handoff 摘取的短指导;只转述边界和已知事实,不自行扩展。
+- `requiredContext` — 建议读取的文件;必须包含当前 iteration 对应 flowRef,例如 `docs/harness/iteration-1/context-flow.md` 或 `docs/harness/iteration-2/context-flow.md`。
+- `allowedFiles` — 可写边界;仅在来源明确时填写,无来源可留空。
+- `forbiddenTasks` — 本次明确不做的事项;仅在来源明确时填写,无来源可留空。
+- `acceptance` — 达到哪些条件就停。
+- `verifier` — 本次建议验证命令或 DoD key。
+
+写入阶段型 dispatch:
+
+```bash
+npm run dispatch:set -- id=stage:<stage> role=<role> goal="..." \
+  requiredContext="docs/harness/iteration-<n>/<stage>-flow.md;docs/..." \
+  acceptance="..."
+```
+
+若 `allowedFiles` / `forbiddenTasks` 有明确来源,再追加对应参数;没有就不要写。
+
+写入真实 todo dispatch,并把 todo 标为 `in_progress`:
+
+```bash
+npm run dispatch:set -- id=<todo-id> role=<role> goal="..." \
+  requiredContext="docs/..." allowedFiles="game/**" acceptance="..." --mark-todo
+```
+
+如果 `goal` / `requiredContext` / `acceptance` / `verifier` 未显式传入,`dispatch:set` 会从同 id 的机器态 todo 继承这些字段。`npm run state:get -- --json dispatch` 会动态展开 active todo 的 `title` / `context`,这样 developer 只读 dispatch 也能拿到 context 阶段写入的完整任务上下文。
+
+### Generate 上下文复用派发
+
+generate 阶段允许复用同一个 `developer` subagent 的已读上下文,但只用于减少重复读大段设计 / atom ref,不改变“一次一个 todo”的执行和验收模型。满足以下条件时,调度者可以在写入下一个 todo dispatch 后用 `sendMessage` 恢复同一个 developer 会话:
+
+- 下一个 pending todo 有非空 `contextReuse`。
+- 它与上一个刚完成的 developer todo 在当前 iteration todo 队列中连续,role 相同,`contextReuse` 相同。
+- 最近 handoff 无 blocker,上一 todo 已由调度者验收并标为 `done`。
+- 当前连续复用段长度不超过 3;第 4 个同 key todo 必须新开 / 重建上下文。
+- 调度者没有发现设计、代码结构、engine、selected atom 或 allowedFiles 发生会让旧上下文失效的变化。
+
+`contextReuse` 依赖 todo 池顺序判断“连续”。context 阶段 seed todo 时必须串行执行 `todo:add`,不要并行写入同一批 todo。
+
+推荐顺序:
+
+```bash
+npm run todo:set -- id=<previous-id> status=done
+npm run dispatch:clear
+npm run dispatch:set -- id=<next-id> role=developer allowedFiles="game/**" --mark-todo
+```
+
+随后用 `sendMessage` 发给同一个 developer subagent。消息只包含:
+
+- 下一个 todo 已写入 dispatch,要求重新读取 `npm run state:get -- --json dispatch`。
+- 本次命中 `contextReuse=<key>`,允许复用上一 todo 已读的共同上下文。
+- 必须读取新 dispatch 展开的 todo `context`,以及 dispatch 中未读过的 `requiredContext`。
+- 每个 todo 仍需单独实现、验证、`handoff:append`;不得顺手做后续 todo。
+
+如果当前工具环境无法 `sendMessage` 恢复同一个 developer subagent,或 `state:get` 的 `contextReuseHint.eligibleForSendMessage` 不是 `true`,就按普通新 dispatch 派发。不要为了复用而把多个 todo 合并成一个 dispatch。
+
+角色 STOP 后由 orchestrator 根据 handoff 判断是否推进阶段、补 todo、或更新 todo 状态。不要要求 subagent 自行 `todo:set`。
+
+当前 dispatch 已处理完毕后清空:
+
+```bash
+npm run dispatch:clear
+```
+
+TODO(C2):补 `dispatch:next` 脚本,自动从 stage spec + todo 合成 dispatch。
+
+## Stage 行为
+
+### ideate
+
+- 迭代1目标:产出 `docs/design-brief.md` 和 `docs/design.md`;先在 brief 建立完整 playable 玩法预期,再在 design 锁定核心玩法方向。
+- 迭代2目标:读取 `docs/design-brief.md` 的 hook 包装线索,在原 `docs/design.md` / `docs/design-brief.md` 中追加或更新迭代2章节,锁定玩法包装方向。
+- 派发:`game-designer`。
+- dispatch 范围:只传用户原始意图、当前 iteration 的 ideate flowRef、产物路径、禁止实现/技术选型边界。
+- 调度者不写设计文档、不补玩法细节、不给引擎建议。
+- 用户确认由 orchestrator 处理;角色不自行跨 session 继续。
+- 退出前确认:
+  - 迭代1:`docs/design-brief.md` 是过程日志,包含完整 playable 玩法预期与取舍;`docs/design.md` 只写核心玩法,不写代码细节。
+  - 迭代2:`docs-last/` 快照存在;`docs/design.md` 有迭代2包装章节;`docs/design-brief.md` 继续记录包装探索、差异点和用户输入;明确 hook、完整体验流程、布局意图、关卡意图、引导、成功失败、包装叙事和情绪弧线。
+  - `pipeline.userConfirm` 已确认。
+
+### context
+
+- 迭代1目标:生成 / 刷新 Atom 引入中间产物 `docs/atom-tree.json`,写 `docs/todo_list.md` 完整任务卡,并 seed 当前 iteration todo。
+- 迭代2目标:基于 `docs-last/` 与当前 docs 的差异,在原 `docs/todo_list.md` 追加迭代2任务卡,seed 当前 iteration 包装 todo。
+- 派发:`game-designer`。
+- 迭代1关键 skill:`playcraft-skill-recommender`。
+- dispatch 范围:传当前 iteration 的 context flowRef、已确认设计文档、todo seed 产物边界。
+- 调度者不内联选择 atom、不自行写 todo 清单、不把 context 做成实现计划;这些由被派发角色按 flow 和 skill 完成。
+- 退出前确认:
+  - 迭代1:`docs/atom-tree.json` 作为 Atom 引入中间产物存在,或明确记录无法生成原因。
+  - 迭代2:`docs/todo_list.md` 有迭代2任务卡,每个 todo 来自明确差异点,并标注重写 / 优化 / 功能补充。
+  - 迭代2 context 禁止写 `docs/design-brief.md`;发现设计缺口时回 ideate。
+  - todoPool 当前 iteration 非空。
+  - 每个 todo 有 role / title / goal / context / acceptance / requiredContext / verifier。
+  - 每个 todo 都在当前 iteration 的 `docs/todo_list.md` 有同名任务卡,机器态 `context` 镜像该任务卡关键语义。
+  - 迭代1 context 完成后、推进 generate 前,调度者基于 todoPool 追加系统 todo `firstwin-harness`(若当前迭代还没有等价 `verify:firstwin` 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
+    ```
+
+    - 这是调度者动作,不是 context 输出,不要求 `docs/todo_list.md` 同名任务卡,也不需要 atom ref。
+    - 该 todo 的 `requiredContext` 必须包含 `skills/playable-autoplay/SKILL.md`;目标是最后把已完成核心玩法接到平台 runtime harness。
+
+  - 迭代2 context 完成后、推进 generate 前,调度者检查 context 阶段的技术基础设施评估结果。若 Scene 状态机骨架为"缺失-阻塞",追加系统 todo `packaging-scene-fsm`(若 todoPool 中还没有等价项):
+
+    ```bash
+    npm run todo:add -- id=packaging-scene-fsm role=developer \
+      title="建立完整包装游戏的 Scene 状态机骨架" \
+      goal="实现 HOOK/TUTORIAL/GAMEPLAY/WIN/FAIL/ENDCARD 六阶段状态机入口和转换触发;扩展 autoPlay 能驱动完整包装路径" \
+      context="骨架只定义状态转换入口,不实现各 scene 内部逻辑;内部逻辑由其他包装任务卡实现后接入。必须保持 window.__playable 合约不破:autoPlay/getState 接口签名不变,初始 currentPhase 仍为 HOOK。autoPlay 扩展只能通过玩家动作等价路径驱动各 scene,不得直接写 currentPhase 或调用 forceWin/showWinScreen。" \
+      requiredContext="skills/playable-autoplay/SKILL.md;skills/playable-record/scripts/verify-lifecycle.mjs;docs/design.md#完整体验流程;docs/todo_list.md#迭代2技术基础设施评估;game/**" \
+      acceptance="game/ 中存在覆盖 HOOK/TUTORIAL/GAMEPLAY/WIN/FAIL/ENDCARD 的状态机入口;每个阶段有明确进入和退出触发;window.__playable.autoPlay() 能驱动完整路径;npm run verify:lifecycle exits 0(phasePath 包含 HOOK/TUTORIAL/GAMEPLAY/ENDCARD)" \
+      verifier=verify:lifecycle createdBy=orchestrator-system
+    ```
+
+    - 这是调度者动作,不是 context 输出,不要求 `docs/todo_list.md` 同名任务卡。
+    - 若技术基础设施评估中 Scene 状态机骨架已标注"已有",跳过此步。
+    - `packaging-scene-fsm` 必须在其他包装功能 todo 之前完成,因为其他 todo 依赖状态转换入口存在。
+
+### generate
+
+- 目标:按 todo 逐个实现当前 iteration 的玩家可感知闭环。迭代1是核心玩法;迭代2是玩法包装升级,制作标准基本一致,评价按完整游戏判断。
+- 派发:`developer`。
+- 每次只派一个 todo。
+- 迭代1的 todoPool 应包含调度者在 context 后追加的 `firstwin-harness`;它按普通 todo 派发给 developer,通常排在普通核心玩法 todo 之后执行。
+- 如果 todo failed:
+  - 读取 handoff blocker。
+  - 判断是补充设计 / 修复实现 / 增加 reviewer todo。
+  - 不推进阶段,直到当前 iteration todo 全部 `done`。
+- 退出前确认:
+  - 当前 iteration todo 全部 `done`。
+  - 没有 pending / in_progress / failed todo。
+  - 迭代2结束 generate 时,`docs/todo_list.md` 已整理当前 todo 与之前 todo 的完整历史总览。
+
+### optimize
+
+- 目标:build、autoplay、record、DoD 收敛。迭代2还要确认录像能呈现完整游戏体验,包括包装 hook / 引导 / 成功失败表达。
+- 派发:`developer`;必要时按失败路由给 technical-artist / reviewer。
+- 运行:
+  ```bash
+  npm run dod:check
+  ```
+- 退出前确认:
+  - 有脚本的 DoD 已通过。
+  - 无脚本 DoD 已被 orchestrator 明确确认并写入 `gate.stageDoD.<key>=passed`,或记录 blocker。
+
+### wrapup
+
+- 目标:清理运行态副作用,刷新 `CLAUDE.md` 项目速览。
+- 不派发角色;由 orchestrator / 脚本执行。
+- 按当前 iteration 的 wrapup flowRef 刷新入口文档。补模板流程规则时不要提前改 `CLAUDE.md`;只有对应迭代真实落地后才改。
+- 退出前确认:
+  - 无悬挂 dev / record 进程。
+  - `CLAUDE.md` 反映当前目录事实。
+  - 当前 iteration todo 全部 `done`。
+
+### 迭代2结束用户确认
+
+- 迭代1结束后自动进入迭代2,不在两轮之间询问用户是否修改包装。
+- 迭代2 wrapup / optimize 完成后,编排者再向用户确认第二轮包装后的完整游戏是否接受。
+- 若用户要求修改,由调度者根据问题性质新增当前 iteration follow-up todo 或回退到合适 stage;不要把用户反馈伪装成已确认状态。
+
+## 推进阶段
+
+只有当前阶段退出条件满足时才推进:
+
+```bash
+npm run stage:advance -- --accepted
+```
+
+`stage:advance` 会强制检查硬门槛:没有 active dispatch;ideate 必须 `userConfirm=confirmed`;context 必须 seed 当前 iteration todo;generate / wrapup 必须当前 iteration todo 全 done;optimize 必须当前 stage DoD 全 pass。其他非结构化退出条件仍由 orchestrator 人工判断。
+
+## 失败处理
+
+- `todo.status=failed` 不是清空状态,会阻塞当前 iteration 关闭。
+- 失败后不要直接改成 done。
+- 先读最近 handoff 的 blocker、summary 和 acceptanceResults。
+- 再选择:
+  - 改写 dispatch 让同角色修复;
+  - 新增 follow-up todo;
+  - 路由给更合适角色;
+  - 若 todo 不再适用,明确移除并记录原因。
+
+## 用户确认
+
+只有 orchestrator 可以向用户确认流程门:
+
+- ideate:核心玩法方向确认。
+- iteration 2 ideate:包装方向是否修改。
+- 其他用户门按对应 stage flow 执行。
+
+用户确认后用 state 记录,例如:
+
+```bash
+npm run state:set -- userConfirm=confirmed
+```
+
+### Brainstorm Relay
+
+`game-designer` 在 ideate 阶段会使用 `brainstorming` 的问题质量协议,但不能直接调用用户交互。编排者负责把 designer 写入 state 的 `pendingUserInput` 转成用户确认:
+
+1. 识别 state:
+   - `pendingUserInput.status=awaiting_user_input`
+   - `orchestratorAction=ask_user_then_sendMessage_to_active_subagent`
+   - `activeTodoId` / `dispatchedRole` 仍指向当前 subagent workticket
+2. 读取 `pendingUserInput.prompt/options/recommended/impact`。只转述问题、选项、推荐项和影响,不要自行补玩法。
+3. 保持 dispatch active。不要执行:
+   ```bash
+   npm run dispatch:clear
+   npm run dispatch:set ...
+   ```
+4. 向用户确认。收到答案后记录到 state:
+   ```bash
+   npm run state:set -- pendingUserInputPatch='{"status":"answered","answer":"<user answer>","answeredAt":"<ISO timestamp>"}'
+   ```
+5. 再次 `state:get` 应显示 `orchestratorAction=sendMessage_answer_to_active_subagent`。用 `sendMessage` 把答案发回同一个 `game-designer` subagent 会话。消息只包含 question id、用户答案、要求继续原任务并把答案以 `[USER]` 来源写入 `docs/design-brief.md`。
+6. 如果当前工具环境无法 `sendMessage` 恢复同一个 subagent,这是流程 blocker。不要伪装成正常重派,因为新会话会丢失脑暴上下文。
+
+最终 ideate 退出门仍是 `pipeline.userConfirm`:用户明确批准核心玩法方向后才设 `userConfirm=confirmed`。中途脑暴回答只作为设计输入,不等同于阶段确认。
+
+## 不要做
+
+- 不让 subagent 读取完整 todo 池后自行挑活。
+- 不把 stage 当成任务直接派给角色;必须转成 `role + goal + flowRef + workId`。
+- 不在 ideate/context 信息阶段替角色产出设计、atom-tree 或 todo_list。
+- 不让 subagent 自己标记 todo done;todo 状态由 orchestrator 根据 handoff 更新。
+- 不把 `stageExit` / `dispatchableRoles` / `canWriteTodo` 写入 dispatch。
+- 不让角色决定 next role。
+- 不手改 `docs/project-state.md`。
+- 不把 todo failed 当作完成。

package/project-template-v2/docs/project-state.json

@@ -0,0 +1,60 @@
+{
+  "schemaVersion": 3,
+  "specVersion": "pipeline",
+  "userIntent": "",
+  "settings": {},
+  "pipeline": {
+    "iteration": 1,
+    "stage": "ideate",
+    "stageStatus": "pending",
+    "userConfirm": "pending"
+  },
+  "dispatch": {
+    "activeTodoId": "none",
+    "role": "",
+    "goal": "",
+    "guidance": "",
+    "skillHints": [],
+    "requiredContext": [],
+    "contextReuse": "",
+    "allowedFiles": [],
+    "forbiddenTasks": [],
+    "acceptance": [],
+    "verifier": ""
+  },
+  "todos": [],
+  "handoff": {
+    "history": [],
+    "pendingUserInput": {
+      "status": "none",
+      "id": "",
+      "requestedBy": "",
+      "prompt": "",
+      "options": [],
+      "recommended": "",
+      "impact": "",
+      "answer": "",
+      "answeredAt": ""
+    },
+    "sharedDecisions": {
+      "engine": "unset",
+      "coreAction": "unset"
+    }
+  },
+  "gate": {
+    "stageDoD": {},
+    "canAskUser": "no"
+  },
+  "devPreview": {
+    "devStatus": "pending",
+    "devUrl": "unset",
+    "devStartedBy": "none",
+    "devLastChecked": "unset",
+    "loadCheck": "pending",
+    "loadCheckNotes": "unset",
+    "uiReviewStatus": "deferred",
+    "uiDiffNotes": "deferred",
+    "uiReworkRound": "0",
+    "devBlockers": []
+  }
+}

package/project-template-v2/docs/project-state.md

@@ -0,0 +1,72 @@
+# Project State (generated — do not edit)
+
+<!-- GENERATED — do not hand-edit. Read via `npm run state:get`; process backing file: docs/project-state.json. Write via `npm run state:set`. -->
+
+> **Agent entry**: run `npm run state:get` first. Do **not** hand-edit this file — it is generated from the process backing file `docs/project-state.json`. Write via `npm run state:set`.
+
+## User Intent
+
+> {{user intent — ≤2 sentences}}
+
+## Pipeline
+
+| field       | value    |
+| ----------- | -------- |
+| specVersion | pipeline |
+| iteration   | 1        |
+| stage       | ideate   |
+| stageStatus | pending  |
+| userConfirm | pending  |
+
+## Current Dispatch
+
+- role: @—
+- todo: none — —
+- read: —
+- context reuse: —
+- write boundary: —
+- forbidden: —
+- acceptance: —
+- verifier: —
+
+## TODO Pool (iteration 1)
+
+_no todos yet_
+
+## Last Handoff
+
+_no handoff entries yet_
+
+## Pending User Input
+
+none
+
+## Stage DoD
+
+| canAskUser |
+| ---------- |
+| no         |
+
+## Dev Preview
+
+> Written programmatically. Do not hand-edit.
+
+| Field          | Value    |
+| -------------- | -------- |
+| devStatus      | pending  |
+| devUrl         | unset    |
+| devStartedBy   | none     |
+| devLastChecked | unset    |
+| loadCheck      | pending  |
+| loadCheckNotes | unset    |
+| uiReviewStatus | deferred |
+| uiDiffNotes    | deferred |
+| uiReworkRound  | 0        |
+| devBlockers    | none     |
+
+## Shared Decisions
+
+| Key        | Value |
+| ---------- | ----- |
+| engine     | unset |
+| coreAction | unset |