diff --git a/.planning/HANDOFF.json b/.planning/HANDOFF.json new file mode 100644 index 0000000..be67c52 --- /dev/null +++ b/.planning/HANDOFF.json @@ -0,0 +1,66 @@ +{ + "version": "1.0", + "timestamp": "2026-09-11T03:15:41.841Z", + "phase": "03", + "phase_name": "data-completion", + "phase_dir": ".planning/phases/03-data-completion", + "plan": 12, + "task": 2, + "total_tasks": 2, + "status": "paused", + "completed_tasks": [ + { + "id": 1, + "name": "Move event registrations into modules", + "status": "done", + "commit": "9c39895" + }, + { + "id": 2, + "name": "Update registration-table regression tests", + "status": "done", + "commit": "d2ebf1c" + } + ], + "remaining_tasks": [ + {"id": 13, "name": "Direct Statement[] event insertion", "status": "not_started"}, + {"id": 14, "name": "Synchronous replay correction", "status": "not_started"}, + {"id": 10, "name": "Legacy compatibility boundary", "status": "not_started"}, + {"id": 11, "name": "Existing SaveSystem preservation", "status": "not_started"}, + {"id": 15, "name": "Independent replay command classes", "status": "not_started"} + ], + "blockers": [ + { + "description": "User requested a session pause for personal reasons.", + "type": "human_action", + "workaround": "Resume with /gsd-resume-work." + } + ], + "async_jobs": [], + "human_actions_pending": [], + "decisions": [ + { + "decision": "Legacy remains compatibility-only; no new legacy boundary or MemorySaveSystem is allowed.", + "rationale": "User structural review supersedes the original Phase 3 Node/legacy decisions.", + "phase": "03" + }, + { + "decision": "Replay commands remain synchronous and independent; @shouldReplay() placement is user-owned.", + "rationale": "Async replay obscures call-stack/source semantics and the user will place decorators on state mutation methods.", + "phase": "03" + }, + { + "decision": "eventInsertEvent accepts Statement[] and executes directly.", + "rationale": "It is an inline event body operation, not an event-store ID lookup.", + "phase": "03" + } + ], + "uncommitted_files": [ + " M .planning/phases/03-data-completion/03-CONTEXT.md", + " M .planning/phases/03-data-completion/03-EVENT-CONTRACT.md", + " M .planning/phases/03-data-completion/03-REPLAY-CONTRACT.md", + " M .planning/phases/03-data-completion/03-VERIFICATION.md" + ], + "next_action": "Run /gsd-resume-work, then execute correction Plan 03-13 after confirming the supersession records are present.", + "context_notes": "Plan 03-12 completed successfully. Do not execute Plan 03-10 or 03-11 before the dependency order says they are ready; the planner assigned 03-13 and 03-14 before the later legacy/save cleanup. Do not modify @shouldReplay() placement on HeroAttribute.set/mul or other user-owned state methods." +} diff --git a/.planning/phases/03-data-completion/.continue-here.md b/.planning/phases/03-data-completion/.continue-here.md new file mode 100644 index 0000000..049f91b --- /dev/null +++ b/.planning/phases/03-data-completion/.continue-here.md @@ -0,0 +1,68 @@ +--- +context: phase +phase: 03-data-completion +task: 12 +total_tasks: 15 +status: paused +last_updated: 2026-09-11T03:15:41.841Z +--- + +## Current State + +Phase 3 structural correction is paused after correction Plan 03-12 completed. The original Phase 3 implementation is not accepted as structurally final because the user superseded several initial design decisions. + +## Completed Work + +- Plans 03-10 through 03-15 were created, reviewed, revised, and passed the plan checker. +- Plan 03-12 completed and committed as `9c39895`, `d2ebf1c`, and `83ca6d6`. +- `data-state/src/event/index.ts` now has registration/exports ownership changes from Plan 03-12. +- User supersession records are present in: + - `.planning/phases/03-data-completion/03-CONTEXT.md` + - `.planning/phases/03-data-completion/03-EVENT-CONTRACT.md` + - `.planning/phases/03-data-completion/03-REPLAY-CONTRACT.md` +- Structural review gaps are recorded in `03-VERIFICATION.md`. + +## Remaining Work + +Execute the reviewed correction plans in dependency order: + +1. `03-13` — direct `Statement[]` event insertion +2. `03-14` — synchronous replay correction +3. `03-10` — remove Phase 3 legacy boundary and restore existing compatibility path +4. `03-11` — remove `MemorySaveSystem` and preserve `SaveSystem` +5. `03-15` — independent replay command classes + +After execution: + +1. Run the full Phase 3 data suite. +2. Run `pnpm test:data-node`. +3. Run `script/check-data-type.ts` and `script/check-data-circular.ts`. +4. Run scoped ESLint and Prettier. +5. Re-run the Phase 3 verifier and update `03-VERIFICATION.md`. + +## User-Owned Boundary + +Do not implement or relocate `@shouldReplay()` decorators. The user will add them to actual state-changing methods such as `HeroAttribute.set` and `HeroAttribute.mul` using the updated Stage 3 decorator configuration. + +## Required Reading + +1. `dev.md` — project rules and layer boundaries. +2. `.planning/phases/03-data-completion/03-CONTEXT.md` — latest supersession decisions S-01 through S-04. +3. `.planning/phases/03-data-completion/03-VERIFICATION.md` — correction gaps. +4. `.planning/phases/03-data-completion/03-13-PLAN.md` — first next plan. +5. `.planning/phases/03-data-completion/03-14-PLAN.md` — synchronous replay contract. +6. `.planning/phases/03-data-completion/03-10-PLAN.md` and `03-11-PLAN.md` — legacy/save restoration. +7. `.planning/phases/03-data-completion/03-15-PLAN.md` — final replay class split. + +## Uncommitted Files + +The following planning artifacts are intentionally uncommitted and must be preserved: + +- `.planning/phases/03-data-completion/03-CONTEXT.md` +- `.planning/phases/03-data-completion/03-EVENT-CONTRACT.md` +- `.planning/phases/03-data-completion/03-REPLAY-CONTRACT.md` +- `.planning/phases/03-data-completion/03-VERIFICATION.md` + +## Resume + +Run `/gsd-resume-work` to restore this state. Do not start a new Phase 3 plan from scratch. diff --git a/.planning/phases/03-data-completion/03-CONTEXT.md b/.planning/phases/03-data-completion/03-CONTEXT.md index 0886f8f..3fd6bc6 100644 --- a/.planning/phases/03-data-completion/03-CONTEXT.md +++ b/.planning/phases/03-data-completion/03-CONTEXT.md @@ -54,6 +54,15 @@ ### the agent's Discretion 没有授权 AI 在接口语义或系统边界上自行决策的事项。 +### 用户结构审查 supersession（2026-09-10） + +以下用户决定晚于上方 Phase 3 初始决策，作为本次 correction gap 的更高优先级约束： + +- **S-01：** Legacy 内容只保留兼容行为，不新增 legacy 系统、加载边界或专用适配层；`CoreState` 保留既有 `SaveSystem` 与 legacy loading 路径。该决定 supersedes D-18、D-19、D-28 中关于 `MemorySaveSystem`、Node-safe legacy boundary 和跳过既有 loading 回调的部分；暂不把存档迁移到渲染端。 +- **S-02：** replay 指令只处理同步状态变化，不等待移动控制器、事件链或其他 Promise；既有录像系统只做保证运行所需的最小兼容修改。该决定 supersedes D-06 及 replay contract 中关于 command completion 等待的部分。 +- **S-03：** `eventInsertEvent` 接收 `Statement[]` 事件语句列表并直接执行，不按事件 ID 查找或转发到 ID 序列路径。该决定 supersedes D-24 与旧 `03-EVENT-CONTRACT.md` 中单事件 ID 的语义。 +- **S-04：** `@shouldReplay()` 的最终落点由用户自行处理。本次 correction 不修改 `HeroAttribute.set`、`HeroAttribute.mul` 或其他用户指定状态修改方法的 decorator placement。 + diff --git a/.planning/phases/03-data-completion/03-EVENT-CONTRACT.md b/.planning/phases/03-data-completion/03-EVENT-CONTRACT.md index 2455266..c13dee3 100644 --- a/.planning/phases/03-data-completion/03-EVENT-CONTRACT.md +++ b/.planning/phases/03-data-completion/03-EVENT-CONTRACT.md @@ -4,6 +4,15 @@ event built-ins；不加入完整 legacy 事件目录，不保留未决字段，也不把渲染行为放入 数据端函数。 +## User structural supersession + +本节晚于初始 checkpoint，优先于下方旧参数记录： + +- `data-state/src/event/index.ts` 只负责稳定注册项和 barrel exports，不承载参数解析、环境形状检查或其他业务逻辑。 +- built-in 调用不在热路径重复执行运行时参数类型判断；具体函数直接消费已确定的参数契约。 +- `eventInsertEvents` 保留现有事件 ID 序列语义；`eventInsertEvent` 改为接收 `Statement[]` 并直接通过现有解释器执行，不读取 event store，也不接受事件 ID。 +- 事件函数仍可按既有事件执行器契约等待事件链；本节只修正 `eventInsertEvent` 的输入和 `index.ts` 的职责，不把 replay command 的同步约束扩展到普通事件执行器。 + ## Shared contract - 每个函数都使用 `(param, env)` 调用形式。 diff --git a/.planning/phases/03-data-completion/03-REPLAY-CONTRACT.md b/.planning/phases/03-data-completion/03-REPLAY-CONTRACT.md index 6709827..e513f41 100644 --- a/.planning/phases/03-data-completion/03-REPLAY-CONTRACT.md +++ b/.planning/phases/03-data-completion/03-REPLAY-CONTRACT.md @@ -1,5 +1,14 @@ # Phase 3 Plan 03: Replay Command Contract +## User structural supersession + +本节晚于初始 replay checkpoint，优先于下方关于异步 command completion 和 decorator +placement 的旧记录： + +- replay command 的状态操作必须同步完成；command 不等待移动控制器、事件链或其他 Promise，不能用异步恢复 collection context。 +- 既有 `ReplaySystem`、route 和 sandbox 只做使同步 command 正常运行所需的最小兼容调整，不重新设计录像系统。 +- `@shouldReplay()` 不在本次 correction 中移动或新增；其最终位置由用户自行放到真正改变最终状态的方法上。 + ## Approval The `confirm-record` checkpoint response approves one top-level replay command diff --git a/.planning/phases/03-data-completion/03-VERIFICATION.md b/.planning/phases/03-data-completion/03-VERIFICATION.md index c931be3..a83597f 100644 --- a/.planning/phases/03-data-completion/03-VERIFICATION.md +++ b/.planning/phases/03-data-completion/03-VERIFICATION.md @@ -1,7 +1,7 @@ --- phase: 03-data-completion verified: 2026-09-10T13:09:33Z -status: passed +status: gaps_found score: 26/26 must-haves verified covered_files: - .planning/REQUIREMENTS.md @@ -268,7 +268,52 @@ N/A — this is an infrastructure/data-layer phase with no user-facing UI or ext ## Gaps Summary -All three prior blockers are closed in the current codebase. Serialized events now enter through the internal CoreState load path and bind raw map event ids before replay; all eight built-in registration functions safely resolve for nullish parameters; and production replay commands use the approved safety decoration only at state-changing entrances. The sequential full data regression passes **19 files / 105 tests**, `pnpm test:data-node` passes, the scoped type gate reports **0 in-scope / 27 outside-scope**, the circular gate reports **0 cycles**, and scoped lint/Prettier checks pass. No blocking gaps remain. +The prior implementation passed its original behavioral gate, but the user structural review identified principle-level corrections that supersede parts of the Phase 3 design. These corrections must be planned and verified before the phase can be considered structurally acceptable. + +## Gaps + +- gap_id: CORR-03-01 + truth: "Phase 3 must not add new legacy systems or new legacy loading boundaries; legacy code remains compatibility-only." + status: failed + reason: "Phase 3 introduced legacy dependency and serialized-event loading infrastructure instead of limiting legacy changes to retention." + severity: blocker + test: structural-review +- gap_id: CORR-03-02 + truth: "Data-state CoreState must not add a MemorySaveSystem or a Node-specific save adapter; save-system restructuring is deferred to the rendering refactor." + status: failed + reason: "CoreState and legacy dependencies select MemorySaveSystem for Node execution and move save initialization behind a new dependency boundary." + severity: blocker + test: structural-review +- gap_id: CORR-03-03 + truth: "data-state/src/event/index.ts contains exports and registration only; event handlers do not perform repeated runtime parameter-shape validation." + status: failed + reason: "The event barrel contains parser helpers, environment guards, and parameter type checks on every built-in invocation." + severity: blocker + test: structural-review +- gap_id: CORR-03-04 + truth: "eventInsertEvent receives a Statement[] event body and executes that body directly; it does not resolve an event by ID." + status: failed + reason: "The current implementation interprets eventInsertEvent as a one-ID wrapper around eventInsertEvents." + severity: blocker + test: structural-review +- gap_id: CORR-03-05 + truth: "Replay command execution remains synchronous and preserves the existing replay system with only the minimum required changes." + status: failed + reason: "Phase 3 added Promise-based movement/equipment command execution and async replay-safety context restoration." + severity: blocker + test: structural-review +- gap_id: CORR-03-06 + truth: "Each replay instruction is an independent class in one replay command file, with no shared command entrance object or inter-command dependency." + status: failed + reason: "The current implementation centralizes all commands in ReplayCommandEntrances and creates command closures around that shared object." + severity: blocker + test: structural-review + +## Deferred Follow-Ups + +- item: "Move @shouldReplay() decorators onto the actual state-changing methods such as HeroAttribute.set and HeroAttribute.mul." + status: user-owned + reason: "The user will implement and validate the Stage 3 decorator placement; this correction run must not modify it." ---