ai-plan/public/README.md

@@ -25,23 +25,10 @@ help the current worktree land on the right recovery documents without scanning
   - Purpose: continue the AI-First config runtime, generator, and consumer DX work for `GFramework.Game`.
   - Tracking: `ai-plan/public/ai-first-config-system/todos/ai-first-config-system-tracking.md`
   - Trace: `ai-plan/public/ai-first-config-system/traces/ai-first-config-system-trace.md`
-- `coroutine-optimization`
-  - Purpose: continue the coroutine semantics, host integration, observability, regression coverage, and migration-doc
-    follow-up work.
-  - Tracking: `ai-plan/public/coroutine-optimization/todos/coroutine-optimization-tracking.md`
-  - Trace: `ai-plan/public/coroutine-optimization/traces/coroutine-optimization-trace.md`
 - `cqrs-rewrite`
   - Purpose: continue the CQRS migration, registry hardening, and related PR follow-up.
   - Tracking: `ai-plan/public/cqrs-rewrite/todos/cqrs-rewrite-migration-tracking.md`
   - Trace: `ai-plan/public/cqrs-rewrite/traces/cqrs-rewrite-migration-trace.md`
-- `data-repository-persistence`
-  - Purpose: continue the data repository persistence hardening plus the settings / serialization follow-up backlog.
-  - Tracking: `ai-plan/public/data-repository-persistence/todos/data-repository-persistence-tracking.md`
-  - Trace: `ai-plan/public/data-repository-persistence/traces/data-repository-persistence-trace.md`
-- `documentation-governance-and-refresh`
-  - Purpose: continue the documentation governance, README hardening, and `docs/zh-CN` accuracy refresh work.
-  - Tracking: `ai-plan/public/documentation-governance-and-refresh/todos/documentation-governance-and-refresh-tracking.md`
-  - Trace: `ai-plan/public/documentation-governance-and-refresh/traces/documentation-governance-and-refresh-trace.md`
 
 ## Worktree To Active Topic Map
 
@@ -55,16 +42,6 @@ help the current worktree land on the right recovery documents without scanning
   - Worktree hint: `GFramework-cqrs`
   - Priority 1: `ai-plan-governance`
   - Priority 2: `cqrs-rewrite`
-- Branch: `feat/coroutine-optimization`
-  - Worktree hint: `GFramework-coroutine-optimization`
-  - Priority 1: `coroutine-optimization`
-  - Priority 2: `ai-plan-governance`
-- Branch: `feat/data-repository-persistence`
-  - Worktree hint: `GFramework-data-repository-persistence`
-  - Priority 1: `data-repository-persistence`
-- Branch: `docs/sdk-update-documentation`
-  - Worktree hint: `GFramework-update-documentation`
-  - Priority 1: `documentation-governance-and-refresh`
 
 ## Archived Topics
 

ai-plan/public/ai-plan-governance/todos/ai-plan-governance-tracking.md

@@ -17,9 +17,10 @@
 - 恢复点编号：`AI-PLAN-GOV-RP-005`
 - 当前阶段：`Phase 3`
 - 当前焦点：
-  - 继续扫描其他 worktree 是否仍有遗留的 `local-plan` 或其他平铺 durable recovery 目录
-  - 保持 active `todos/` / `traces/` 只保留当前恢复点、活跃事实、活跃风险、下一步与 archive 指针
-  - 确保 `ai-plan/public/README.md` 与各 topic active 文档对 worktree 映射、恢复点和下一步的描述保持同步
+  - 将"主题内 `archive/` 已存在"升级为"active todo/trace 过长时必须归档已完成且已验证阶段"的显式规则
+  - 让 active `todos/` / `traces/` 只保留当前恢复点、活跃事实、活跃风险、下一步与 archive 指针
+  - 将 `ai-plan-governance`、`ai-first-config-system` 与 `cqrs-rewrite` 的历史阶段从默认启动入口移出
+  - 将当前工作树遗留的 `local-plan` 示例迁入 `ai-plan/public/<topic>/`，验证治理规则对新 topic 迁移同样成立
 
 ### 已知风险
 
@@ -48,28 +49,7 @@
   - `ai-plan/public/analyzer-warning-reduction/traces/`
   - `ai-plan/public/analyzer-warning-reduction/archive/todos/`
   - `ai-plan/public/analyzer-warning-reduction/archive/traces/`
-- 已将当前工作树遗留的 documentation governance and refresh 恢复文档从 `local-plan/` 迁入：
-  - `ai-plan/public/documentation-governance-and-refresh/todos/`
-  - `ai-plan/public/documentation-governance-and-refresh/traces/`
-  - `ai-plan/public/documentation-governance-and-refresh/archive/todos/`
-  - `ai-plan/public/documentation-governance-and-refresh/archive/traces/`
-- 已将当前工作树遗留的 coroutine early-plan 恢复文档从 `local-plan/` 迁入：
-  - `ai-plan/public/coroutine-optimization/todos/`
-  - `ai-plan/public/coroutine-optimization/traces/`
-  - `ai-plan/public/coroutine-optimization/archive/todos/`
-  - `ai-plan/public/coroutine-optimization/archive/traces/`
-- 已将当前工作树遗留的 settings / persistence / serialization 混合恢复文档从 `local-plan/` 迁入：
-  - `ai-plan/public/data-repository-persistence/todos/`
-  - `ai-plan/public/data-repository-persistence/traces/`
-  - `ai-plan/public/data-repository-persistence/archive/todos/`
-  - `ai-plan/public/data-repository-persistence/archive/traces/`
 - 已同步更新 `ai-plan/public/README.md`，将分支 `fix/analyzer-warning-reduction-batch` 映射到新 topic
-- 已同步更新 `ai-plan/public/README.md`，将分支 `docs/sdk-update-documentation` 映射到
-  `documentation-governance-and-refresh`
-- 已同步更新 `ai-plan/public/README.md`，将分支 `feat/coroutine-optimization` 映射到
-  `coroutine-optimization`
-- 已同步更新 `ai-plan/public/README.md`，将分支 `feat/data-repository-persistence` 映射到
-  `data-repository-persistence`
 - 已同步更新 `AGENTS.md`、`ai-plan/README.md` 与 `gframework-boot`，明确 active 文档不是追加式日志，已完成且已验证阶段必须归档
 
 ## 验证
@@ -77,21 +57,12 @@
 - `find ai-plan/public -maxdepth 5 -type f | sort`
   - 结果：通过
   - 备注：活跃主题、主题内归档文件与主题级归档都已按新目录语义落位
+- `wc -l ai-plan/public/ai-plan-governance/todos/ai-plan-governance-tracking.md ai-plan/public/ai-plan-governance/traces/ai-plan-governance-trace.md ai-plan/public/ai-first-config-system/todos/ai-first-config-system-tracking.md ai-plan/public/ai-first-config-system/traces/ai-first-config-system-trace.md ai-plan/public/cqrs-rewrite/todos/cqrs-rewrite-migration-tracking.md ai-plan/public/cqrs-rewrite/traces/cqrs-rewrite-migration-trace.md`
+  - 结果：通过
+  - 备注：6 个 active 入口文件当前合计 `249` 行，已从治理前的 `3046` 行显著收短
 - `find ai-plan/public/analyzer-warning-reduction -maxdepth 3 -type f | sort`
   - 结果：通过
   - 备注：新 topic 已按 `todos/`、`traces/` 与主题内 `archive/` 目录语义落位
-- `find ai-plan/public/documentation-governance-and-refresh -maxdepth 3 -type f | sort`
-  - 结果：通过
-  - 备注：文档治理 topic 已按 `todos/`、`traces/` 与主题内 `archive/` 目录语义落位
-- `find ai-plan/public/coroutine-optimization -maxdepth 3 -type f | sort`
-  - 结果：通过
-  - 备注：更早期、只有 todo 没有 trace 的 coroutine 计划也已按治理规则补齐 active 入口与 archive
-- `find ai-plan/public/data-repository-persistence -maxdepth 3 -type f | sort`
-  - 结果：通过
-  - 备注：只有单文件且混合承担 todo / trace 的 legacy `local-plan` 也已按治理规则拆分为 active 入口与主题内 archive
-- `test ! -e local-plan`
-  - 结果：通过
-  - 备注：当前工作树根目录已不再保留 legacy `local-plan/`
 - `dotnet build GFramework.Core.Abstractions/GFramework.Core.Abstractions.csproj -c Release -p:RestoreFallbackFolders=`
   - 结果：通过
   - 备注：`GFramework.Cqrs.Abstractions` 与 `GFramework.Core.Abstractions` 构建通过，`0 warning / 0 error`
@@ -103,6 +74,6 @@
 
 ## 下一步
 
-1. 继续扫描是否还有遗留的 `local-plan` 或其他非 `ai-plan` 的 durable recovery 文档目录，尤其关注单文件混合 tracking/trace 或只有 todo 没有 trace 的更早期计划
+1. 继续扫描是否还有遗留的 `local-plan` 或其他非 `ai-plan` 的 durable recovery 文档目录
 2. 后续只要某个 active 主题积累了多个已完成且已验证阶段，就在同一变更里将其细节迁入该主题自己的 `archive/`
 3. 若某个主题整体完成，再将整个主题目录移入 `ai-plan/public/archive/<topic>/`

ai-plan/public/ai-plan-governance/traces/ai-plan-governance-trace.md

@@ -24,7 +24,7 @@
   - `ai-plan/public/cqrs-rewrite/archive/todos/cqrs-rewrite-history-through-rp043.md`
   - `ai-plan/public/cqrs-rewrite/archive/traces/cqrs-rewrite-history-through-rp043.md`
 
-### 下一步 — 归档收口
+### 下一步
 
 1. 未来若 active 入口再次因为已完成阶段累积而膨胀，直接按同一模式归档，不再保留为追加式历史日志
 2. 后续新增 topic 时，默认同步创建 `todos/`、`traces/` 与 `archive/` 目录
@@ -43,77 +43,7 @@
   - `find ai-plan/public/analyzer-warning-reduction -maxdepth 3 -type f | sort`
   - `dotnet build GFramework.Core.Abstractions/GFramework.Core.Abstractions.csproj -c Release -p:RestoreFallbackFolders=`
 
-### 下一步 — analyzer-warning-reduction 迁移
+### 下一步
 
 1. 后续若再发现 `local-plan` 一类目录，直接按 topic 归属迁入 `ai-plan/public/<topic>/`
 2. 保持新 topic 的 active 入口精简，避免把迁移动作变成简单目录平移
-
-### 阶段：文档治理 local-plan 迁移验证（RP-005）
-
-- 再次复核当前工作树后确认：遗留的 `local-plan/` 内容属于 documentation governance and refresh 主题
-- 按同一治理规则建立 `ai-plan/public/documentation-governance-and-refresh/`，并补齐：
-  - `todos/`
-  - `traces/`
-  - `archive/todos/`
-  - `archive/traces/`
-- 将旧 `local-plan` 中详细的文档治理 todo / trace 收入主题内归档，只保留精简版 active 入口
-- 在 `ai-plan/public/README.md` 中建立
-  `docs/sdk-update-documentation` -> `documentation-governance-and-refresh` 的 worktree 映射
-- 删除旧 `local-plan` 文件，验证当前工作树已无 legacy 根目录恢复入口
-- 额外完成验证：
-  - `find ai-plan/public/documentation-governance-and-refresh -maxdepth 3 -type f | sort`
-  - `test ! -e local-plan`
-
-### 下一步 — 文档治理迁移
-
-1. 后续若其他 worktree 仍存在 `local-plan` 一类目录，继续按 topic 归属迁入对应 `ai-plan/public/<topic>/`
-2. 继续保持 topic active 入口精简，避免把迁移后的公共目录重新写成追加式日志
-
-### 阶段：coroutine early-plan local-plan 迁移验证（RP-005）
-
-- 复核当前工作树后确认：遗留的 `local-plan/` 内容属于 coroutine 主题，但它比前两次迁移更早，只保留了 `5` 份 todo，
-  没有任何独立 trace
-- 按同一治理规则建立 `ai-plan/public/coroutine-optimization/`，并补齐：
-  - `todos/`
-  - `traces/`
-  - `archive/todos/`
-  - `archive/traces/`
-- 将旧 `local-plan` 中分散的五个阶段计划整合进主题内历史跟踪归档，并额外补写一份基于 todo 基线整理出的历史 trace，
-  显式记录"缺少原始 trace，只能恢复稳定结论"的边界
-- 新建精简版 active tracking / trace 入口，只保留当前恢复点、活跃事实、风险与下一步
-- 在 `ai-plan/public/README.md` 中建立
-  `feat/coroutine-optimization` -> `coroutine-optimization` 的 worktree 映射，并把 `ai-plan-governance` 作为 secondary topic 保留
-- 删除旧 `local-plan` 目录，验证当前工作树根目录已不再保留 legacy 私有恢复入口
-- 额外完成验证：
-  - `find ai-plan/public/coroutine-optimization -maxdepth 3 -type f | sort`
-  - `test ! -e local-plan`
-  - `dotnet build GFramework.Core.Abstractions/GFramework.Core.Abstractions.csproj -c Release -p:RestoreFallbackFolders=`
-
-### 下一步 — coroutine 早期计划迁移
-
-1. 后续若再遇到"只有 todo、没有 trace"的更早期计划，继续按同一模式迁入 topic archive，并明确标注推导边界
-2. 保持新 topic 的 active 入口精简，不把补写 trace 变成伪造逐日执行日志
-
-### 阶段：单文件 local-plan 迁移验证（RP-005）
-
-- 复核当前工作树后确认：遗留的 `local-plan/` 只剩一份
-  `settings-persistence-serialization-tracking.md`，它同时承担 todo 与 trace 角色，不符合当前 `ai-plan` 目录语义
-- 按同一治理规则建立 `ai-plan/public/data-repository-persistence/`，并补齐：
-  - `todos/`
-  - `traces/`
-  - `archive/todos/`
-  - `archive/traces/`
-- 将旧混合文件拆分为主题内历史跟踪归档与基于同一材料整理的历史 trace，显式保留“原始材料并非独立 trace”的边界
-- 新建精简版 active tracking / trace 入口，只保留当前恢复点、活跃事实、风险与下一步
-- 在 `ai-plan/public/README.md` 中建立
-  `feat/data-repository-persistence` -> `data-repository-persistence` 的 worktree 映射
-- 删除旧 `local-plan` 目录，验证当前工作树根目录已不再保留 legacy 私有恢复入口
-- 额外完成验证：
-  - `find ai-plan/public/data-repository-persistence -maxdepth 3 -type f | sort`
-  - `test ! -e local-plan`
-  - `dotnet build GFramework.Core.Abstractions/GFramework.Core.Abstractions.csproj -c Release -p:RestoreFallbackFolders=`
-
-### 下一步 — 单文件计划迁移
-
-1. 后续若再遇到“单文件同时承担 tracking / trace”的更早期计划，继续按同一模式迁入 topic archive，并显式标注来源边界
-2. 保持新 topic 的 active 入口精简，避免把拆分后的公共目录重新写回旧式混合日志

ai-plan/public/coroutine-optimization/archive/todos/coroutine-optimization-history-pre-rp001.md

@@ -1,211 +0,0 @@
-# Coroutine Optimization 历史跟踪（Pre-RP-001）
-
-## 背景
-
-本文件整合自旧 `local-plan/todos/coroutine/*.md`。这些材料属于更早期的计划基线，记录了当时已经完成的第一轮实现、
-仍待收口的后续任务、风险和验收标准，但没有与之配套的 durable trace。
-
-## 来源文档
-
-- `local-plan/todos/coroutine/01-core-semantics.md`
-- `local-plan/todos/coroutine/02-core-control-and-observability.md`
-- `local-plan/todos/coroutine/03-godot-runtime-integration.md`
-- `local-plan/todos/coroutine/04-tests-and-regressions.md`
-- `local-plan/todos/coroutine/05-docs-and-migration.md`
-
-## 历史阶段基线
-
-- 当时的整体判断：协程体系已经完成第一轮实现、基础回归和主路径文档同步，后续任务主要是围绕语义一致性、
-  宿主基础设施化、运行时回归覆盖和迁移说明收口
-- 该阶段没有留下独立 trace，因此下述内容应视为“早期计划与状态快照整合稿”，而不是逐日执行日志
-
-## Phase 1：Core Semantics
-
-### 已有基础
-
-- `CoroutineScheduler` 已支持 `realtimeTimeSource`
-- 已新增 `CoroutineExecutionStage`
-- `WaitForSecondsRealtime` 已优先使用真实时间源
-- `WaitForFixedUpdate` / `WaitForEndOfFrame` 已只在匹配阶段推进
-
-### 目标
-
-- 继续让 Core API 的名字和真实行为完全一致
-- 降低不同宿主对同一等待指令的理解偏差
-
-### 后续必做项
-
-- 评估 `Delay` 与 `WaitForSecondsScaled` 是否需要长期并存
-- 评估 `WaitForNextFrame` 与 `WaitOneFrame` 的命名差异是否值得保留
-- 为阶段型等待补更多跨宿主说明与样例
-- 审视 `WaitForCoroutine` 在父子调度器不同阶段时的语义
-
-### 可选增强
-
-- 为等待指令补统一的语义类别元数据
-- 支持宿主自定义阶段映射
-
-### 风险与验收
-
-- 风险：阶段等待在旧调用路径中可能表现为“以前能过、现在会一直等”
-- 风险：文档与示例若不同步强调阶段前提，会放大兼容性误解
-- 验收标准：等待指令名称不再过度承诺，Core 文档能清楚解释时间与阶段语义
-
-### 当时状态
-
-- 已完成第一轮实现与回归测试
-- 下一步原计划：继续审视其他等待指令的命名与边界
-
-## Phase 2：Core Control And Observability
-
-### 已有基础
-
-- 调度器已新增 `CoroutineCompletionStatus`
-- 已新增 `WaitForCompletionAsync(...)`
-- 已新增 `TryGetCompletionStatus(...)`
-- 已新增 `TryGetSnapshot(...)`
-- 已新增 `GetActiveSnapshots()`
-- 已新增 `OnCoroutineFinished`
-
-### 目标
-
-- 让协程不仅能运行，还能稳定接入业务控制、调试和诊断链路
-
-### 后续必做项
-
-- 评估是否需要完成历史的上限或清理策略
-- 为快照补更多可观测字段时保持分配与遍历成本可控
-- 审查取消、终止、异常三种完成路径的外部可见语义
-- 评估是否需要暴露最后异常查询 API
-
-### 可选增强
-
-- 编辑器或调试面板中的协程列表
-- 导出运行中协程报告
-
-### 风险与验收
-
-- 风险：完成历史无限增长会带来内存累积风险
-- 风险：同步完成事件必须保持主线程安全假设
-- 验收标准：业务代码可以等待、查询并区分协程最终状态；运行时诊断不需要反射或私有字段访问
-
-### 当时状态
-
-- 第一版完成状态与快照 API 已落地
-- 下一步原计划：评估历史清理策略和异常可观测性
-
-## Phase 3：Godot Runtime Integration
-
-### 已有基础
-
-- `Timing` 已为各段提供缩放时间源与真实时间源
-- `PhysicsProcess` / `DeferredProcess` 已与阶段语义对齐
-- 已新增 `RunOwnedCoroutine(...)` 与 `Node.RunCoroutine(...)`
-- 节点退树时已终止归属协程
-- 已新增节点归属数量和句柄快照查询
-
-### 目标
-
-- 把 Godot 协程从“可运行”提升到“宿主级基础设施”
-
-### 后续必做项
-
-- 验证节点归属协程在复杂场景切换中的行为
-- 评估是否需要为 `SceneTree` 或页面级作用域提供批量清理 API
-- 评估是否要把 `ProcessIgnorePause` 独立暴露更多调试指标
-- 评估节点退出与 `queue_free` 之间的行为是否还需更早终止
-
-### 可选增强
-
-- 编辑器内协程调试面板
-- 与 Pause 系统的更细粒度联动
-
-### 风险与验收
-
-- 风险：Godot 线程限制要求所有宿主回调保持主线程驱动
-- 风险：节点归属逻辑需要持续验证信号解绑是否完整
-- 验收标准：节点归属协程在退树时不再泄漏，`WaitForFixedUpdate` 与 `WaitForEndOfFrame` 在 Godot 中语义真实
-
-### 当时状态
-
-- 第一版宿主接入已落地，并补充了基础时间源测试
-- 下一步原计划：增加更贴近运行时的集成测试
-
-## Phase 4：Tests And Regressions
-
-### 已有基础
-
-- 已补充 Core 协程增强测试
-- 已补充 Godot 时间源测试项目
-
-### 目标
-
-- 为后续协程能力扩展提供稳定回归网
-
-### 后续必做项
-
-- 增加 Godot 运行时级测试，覆盖节点归属、退树、暂停和各 segment 差异
-- 补异常传播、完成历史与快照字段的更多边界测试
-- 评估是否需要把 `GFramework.Godot.Tests` 接入解决方案级测试流
-
-### 可选增强
-
-- 文档样例 smoke test
-- 基准测试或分配回归测试
-
-### 风险与验收
-
-- 风险：Godot 运行时测试可能需要额外的测试宿主或场景搭建
-- 风险：解决方案外测试项目容易被遗漏
-- 验收标准：Core 与 Godot 两侧关键协程行为都具备自动化回归；新增阶段和生命周期语义有明确测试覆盖
-
-### 当时状态
-
-- `dotnet test GFramework.Core.Tests -c Release --filter "FullyQualifiedName~Coroutine"` 已通过
-- `dotnet test GFramework.Godot.Tests/GFramework.Godot.Tests.csproj -c Release` 已通过
-- 下一步原计划：规划 Godot 集成测试宿主
-
-## Phase 5：Docs And Migration
-
-### 已有基础
-
-- 已更新 `docs/zh-CN/core/coroutine.md`
-- 已更新 `docs/zh-CN/godot/coroutine.md`
-- 已更新 `docs/zh-CN/tutorials/coroutine-tutorial.md`
-
-### 已修正重点
-
-- 时间语义与阶段语义说明
-- 节点归属协程入口
-- `StartCoroutine()/StopCoroutine()` 旧示例误导
-
-### 目标
-
-- 让用户看到的主文档与当前实现保持一致
-
-### 后续必做项
-
-- 继续扫描仓库中其他 `StartCoroutine()/StopCoroutine()` 文档残留
-- 为迁移场景补“旧示例到新入口”的对照说明
-- 为 `WaitForFixedUpdate` / `WaitForEndOfFrame` 的宿主前提补更多页面说明
-
-### 可选增强
-
-- 增加 FAQ 和排障章节
-- 增加 Godot 场景级最佳实践示例
-
-### 风险与验收
-
-- 风险：老文档残留会继续制造错误接入路径
-- 验收标准：用户按主文档示例能直接跑通当前 API，旧接口误导在主路径文档中被清理
-
-### 当时状态
-
-- 主文档与教程已对齐当前实现
-- 下一步原计划：继续清理其他文档残留并补迁移说明
-
-## 历史结论
-
-- 旧 `local-plan` 记录的不是“待从零开始”的需求池，而是“第一轮实现已完成后仍待收口的 follow-up backlog”
-- 由于当时没有同步留下 trace，后续恢复时不应把本文件视作完整执行历史；真正要继续推进时，应基于 active tracking
-  重新选择一个最小切入点，并补回当轮 trace 与验证记录

ai-plan/public/coroutine-optimization/archive/traces/coroutine-optimization-history-pre-rp001.md

@@ -1,40 +0,0 @@
-# Coroutine Optimization 历史追踪（Pre-RP-001）
-
-## 说明
-
-旧 `local-plan/` 只保留了五份 coroutine todo，没有逐日 trace。本文件是基于这些早期计划文档整理出的历史追踪基线，
-用于说明当时已经完成的第一轮工作、仍然打开的 follow-up 面，以及哪些结论属于“由 todo 推导出的恢复信息”。
-
-## 2026-04-19
-
-### 阶段：早期 coroutine 计划基线补录（RP-001）
-
-- 复核 `local-plan/todos/coroutine/` 后确认，共存在 `5` 份主题文档，覆盖：
-  - Core semantics
-  - Core control and observability
-  - Godot runtime integration
-  - Tests and regressions
-  - Docs and migration
-- 这些文档都明确指向同一个状态：第一轮 coroutine 语义、宿主接入、基础测试和主路径文档已经完成，后续任务主要是补收口
-- 从文档文字可推导出的已完成能力包括：
-  - `CoroutineScheduler` 已支持真实时间源
-  - `CoroutineExecutionStage` 与阶段型等待已落地
-  - 完成状态、等待完成、快照查询和完成事件 API 已落地
-  - Godot 的分段时间源、节点归属协程和退树终止语义已落地
-  - `docs/zh-CN` 下的 coroutine 主文档与教程已完成一轮纠偏
-- 从文档文字可推导出的未收口面包括：
-  - 命名与真实行为的一致性仍需继续审视
-  - 完成历史清理策略、异常可观测性与更多快照字段仍待评估
-  - Godot 复杂场景切换、暂停、`queue_free` 等行为仍需更强验证
-  - 更贴近运行时的集成测试与迁移对照文档仍待补齐
-- 已显式记录信息缺口：
-  - 没有原始执行 trace
-  - 没有与每个阶段一一对应的完整验证日志
-  - 没有可直接还原当时提交边界的恢复点编号
-- 因此，本轮迁移不伪造“已执行的逐步流水”，只把早期计划中可稳定恢复的结论提炼为 archive 基线
-
-### 后续恢复约束
-
-1. 若继续 coroutine 主题，应把本文件当作“早期计划背景”，而不是完整实现日志
-2. 新一轮推进时必须重新建立当轮 trace、验证命令和恢复点编号
-3. 如果需要更强历史精度，只能再从 Git 历史、测试记录或代码差异中补证，不能把旧 todo 当作完整 trace 使用

ai-plan/public/coroutine-optimization/todos/coroutine-optimization-tracking.md

@@ -1,53 +0,0 @@
-# Coroutine Optimization 跟踪
-
-## 目标
-
-继续以“先收敛语义一致性，再补宿主验证和迁移文档”为原则推进当前协程体系，避免 Core 与 Godot 两侧 API 名称、
-阶段语义、可观测性和文档入口再次发生漂移。
-
-## 当前恢复点
-
-- 恢复点编号：`COROUTINE-OPTIMIZATION-RP-001`
-- 当前阶段：`Phase 1`
-- 当前焦点：
-  - 已将 worktree-root 遗留的 `local-plan/` 迁入 `ai-plan/public/coroutine-optimization/`，active 入口只保留当前恢复信息
-  - 基于早期计划中已经完成的第一轮实现，重新收敛后续切入点，避免把语义命名、宿主集成、测试扩面和文档清理混成一次大任务
-  - 明确记录“旧计划没有 durable trace，只有 todo 基线”，后续恢复时先读 active 入口，再按需展开 archive
-
-## 当前状态摘要
-
-- Core 协程第一轮语义收拢已完成，包括真实时间源、执行阶段与阶段型等待的基础行为调整
-- 调度器第一版控制与可观测能力已落地，包括完成状态、等待完成、快照查询和完成事件
-- Godot 宿主第一版接入已落地，包括分段时间源、节点归属协程入口与退树终止语义
-- Core 与 Godot 两侧已经具备一轮基础测试与文档更新，但更贴近运行时的集成验证、兼容性说明和迁移对照仍未收口
-
-## 当前活跃事实
-
-- 本主题的详细历史不是从已有 trace 迁入，而是由旧 `local-plan/todos/coroutine/*.md` 整合出的计划基线
-- `RP-001` 的详细工作流拆分、验收标准和缺失 trace 说明已归档到主题内 `archive/`
-- 当前工作树分支 `feat/coroutine-optimization` 已在 `ai-plan/public/README.md` 建立 topic 映射
-
-## 当前风险
-
-- 语义兼容性风险：`Delay`、`WaitForSecondsScaled`、`WaitForNextFrame`、`WaitOneFrame` 等命名与行为若继续调整，可能影响既有调用认知
-  - 缓解措施：下一轮只先挑一个语义面收敛，并同步补足迁移说明与宿主前提文档
-- 宿主验证缺口风险：Godot 节点归属、退树、暂停与各 segment 差异仍缺少更贴近运行时的自动化回归
-  - 缓解措施：优先规划 Godot 集成测试宿主，再决定是否扩展更多运行时诊断 API
-- 历史信息稀疏风险：旧计划没有同步保留当时的执行 trace 与完整验证记录
-  - 缓解措施：active 文档只保留当前结论；需要历史语义时回看 archive，并明确哪些内容是从早期 todo 推导出的基线
-
-## 活跃文档
-
-- 历史跟踪归档：[coroutine-optimization-history-pre-rp001.md](../archive/todos/coroutine-optimization-history-pre-rp001.md)
-- 历史 trace 归档：[coroutine-optimization-history-pre-rp001.md](../archive/traces/coroutine-optimization-history-pre-rp001.md)
-
-## 验证说明
-
-- 旧 `local-plan` 的五份 coroutine todo 已整合进主题内历史归档，不再作为 worktree-root durable recovery 入口保留
-- active 跟踪文件只保留当前恢复点、活跃事实、风险与下一步，避免把更早期计划直接平移成新的追加式日志
-
-## 下一步
-
-1. 若继续该主题，先在 `Core Semantics`、`Control And Observability`、`Godot Runtime Integration`、`Tests And Regressions`、`Docs And Migration` 中只选一个切入点推进
-2. 若优先补验证，先规划 Godot 集成测试宿主与节点归属/退树/暂停场景，再扩运行时诊断 API
-3. 若优先补文档与迁移说明，先清理其余 `StartCoroutine()/StopCoroutine()` 残留，再为阶段等待和新入口补统一对照说明

ai-plan/public/coroutine-optimization/traces/coroutine-optimization-trace.md

@@ -1,34 +0,0 @@
-# Coroutine Optimization 追踪
-
-## 2026-04-19
-
-### 阶段：legacy local-plan 迁移建档（RP-001）
-
-- 复核当前工作树后确认：`local-plan/` 仅保存 coroutine 主题的早期 todo 基线，共 `5` 份分阶段文档，没有独立 trace
-- 按 `ai-plan` 治理规则建立 `ai-plan/public/coroutine-optimization/` 主题目录，并补齐：
-  - `todos/`
-  - `traces/`
-  - `archive/todos/`
-  - `archive/traces/`
-- 将旧 `local-plan` 中分散的五个阶段计划整合为主题内历史跟踪归档，避免后续恢复仍依赖 worktree-root 私有目录
-- 因旧计划没有 durable trace，本次额外补写一份“基于早期 todo 基线整理出的历史 trace”，显式记录信息缺口与推导边界
-- 新建精简版 active tracking / trace 入口，并在 `ai-plan/public/README.md` 中建立
-  `feat/coroutine-optimization` -> `coroutine-optimization` 的 worktree 映射
-- 删除旧 `local-plan` 目录，确保后续 `boot` 只从 `ai-plan/public/coroutine-optimization/` 进入
-- 额外完成验证：
-  - `find ai-plan/public/coroutine-optimization -maxdepth 3 -type f | sort`
-  - `test ! -e local-plan`
-  - `dotnet build GFramework.Core.Abstractions/GFramework.Core.Abstractions.csproj -c Release -p:RestoreFallbackFolders=`
-
-### Archive Context
-
-- 历史跟踪归档：
-  - `ai-plan/public/coroutine-optimization/archive/todos/coroutine-optimization-history-pre-rp001.md`
-- 历史 trace 归档：
-  - `ai-plan/public/coroutine-optimization/archive/traces/coroutine-optimization-history-pre-rp001.md`
-
-### 下一步
-
-1. 后续若继续 coroutine 主题，只从 `ai-plan/public/coroutine-optimization/` 进入，不再恢复 `local-plan/`
-2. 下一轮只选择一个主切入点推进，避免语义、宿主、测试和文档扩面同时发生
-3. 若 active 入口后续积累多轮已完成且已验证阶段，再按同一模式迁入该主题自己的 `archive/`

ai-plan/public/data-repository-persistence/archive/todos/data-repository-persistence-history-pre-rp001.md

@@ -1,176 +0,0 @@
-# Settings / Persistence / Serialization 历史任务单
-
-> 说明：本归档由 `2026-04-19` 的 legacy `local-plan/settings-persistence-serialization-tracking.md` 迁移生成。
-> 原文件同时承担 todo 与 trace 角色；本文件保留任务目标、已完成改动、验证与 backlog，供后续主题恢复引用。
-
-## 目标
-
-围绕 `GFramework` 当前的设置、持久化、序列化系统，先完成一轮高优先级收敛：
-
-- 修正文档与当前实现不一致的问题
-- 补足关键直接测试，避免只靠侧面覆盖
-- 修复本轮实现中暴露出来的真实缺陷
-- 为后续更大的存档迁移 / 持久化策略统一保留清晰恢复点
-
-## 历史阶段完成情况
-
-### 代码
-
-- [x] `JsonSerializer` 支持注入 `JsonSerializerSettings`
-- [x] `JsonSerializer` 暴露 `Converters` 入口，允许按实例追加 converter
-- [x] `JsonSerializer` 反序列化失败会带上目标类型上下文
-- [x] `JsonSerializer.Serialize(object, Type)` 保持 `obj == null` 时输出 `"null"` 的兼容行为
-- [x] `JsonSerializer` 不再把参数校验抛出的 `ArgumentException` 包装成 `InvalidOperationException`
-- [x] `DataRepository.SaveAllAsync(...)` 改为批量提交语义，只发送 `DataBatchSavedEvent`
-- [x] `DataRepository.DeleteAsync(...)` 仅在目标真实存在时发送删除事件
-- [x] `DataRepository` 在批量保存时保留运行时数据类型，避免自动备份读取到退化的 `IData` 类型
-- [x] `SettingsModel.GetData<T>()` 在初始化后新增设置数据时会立即注册数据类型
-- [x] `SettingsModel.RegisterApplicator<T>()` 会同步注册 applicator 绑定的数据类型
-- [x] `SettingsModel.RegisterMigration(...)` 会失效对应类型的迁移缓存，避免 cache warm-up 后新增迁移不生效
-- [x] 修复 `UnifiedSettingsDataRepository.SaveAsync(...)` 首次保存时可能发生的自锁死锁
-- [x] `UnifiedSettingsDataRepository` 对齐 `DataRepositoryOptions` 契约，支持统一文件级自动备份
-- [x] `UnifiedSettingsDataRepository.LoadAsync<T>()` 改为发送 `DataLoadedEvent<T>`，不再退化为
-  `DataLoadedEvent<IData>`
-- [x] `UnifiedSettingsDataRepository.SaveAllAsync(...)` 改为批量提交语义，不再隐式重复发送单项保存事件
-- [x] `UnifiedSettingsDataRepository` 改为“快照 -> 持久化 -> 交换缓存”的提交模型，避免失败写入污染内存中的已提交状态
-- [x] `ISaveRepository<T>` 增加正式的 `ISaveMigration<T>` 迁移接口
-- [x] `SaveRepository<T>` 在 `LoadAsync(slot)` 时支持按版本链自动迁移并回写升级后的存档
-- [x] `SaveRepository<T>` 的迁移注册表增加并发访问保护，禁止同一 `FromVersion` 重复注册被静默覆盖
-
-### 测试
-
-- [x] 新增 `JsonSerializer` 直接单测
-- [x] 新增 `SettingsModel` 直接单测
-- [x] 新增 `FileStorage` / `SaveRepository` / `UnifiedSettingsDataRepository` 持久化测试
-- [x] 新增 `SaveRepository` 迁移链、重复注册和缺失迁移链的直接单测
-- [x] 新增 `DataRepository` 批量事件与自动备份直接单测
-- [x] 新增 `DataRepository.SaveAllAsync(...)` 运行时类型批量覆盖回归测试
-- [x] 新增 `SettingsSystem` 直接测试，覆盖 `ApplyAll / Reset / SaveAll / ResetAll`
-- [x] 新增 `UnifiedSettingsDataRepository` 事件开启场景下的上下文集成测试
-- [x] 新增 `UnifiedSettingsDataRepository` 保存/删除失败时缓存一致性回归测试
-- [x] 定向测试通过：`JsonSerializerTests | SettingsModelTests | PersistenceTests`
-- [x] 定向测试通过：`SettingsModelTests | PersistenceTests | SettingsSystemTests`
-- [x] 定向测试通过：`PersistenceTests | SettingsSystemTests`
-- [x] 定向测试通过：`PersistenceTests | SettingsSystemTests | SettingsModelTests`
-- [x] 全量 `GFramework.Game.Tests` 通过
-
-### 文档
-
-- [x] 重写 `docs/zh-CN/game/setting.md`，对齐当前 `ISettingsModel` / `SettingsSystem` / `ISettingsData`
-- [x] 修正 `docs/zh-CN/game/data.md`，把存档迁移文档更新为 `ISaveRepository<T>.RegisterMigration(...)` 的内建能力说明
-- [x] 修正 `docs/zh-CN/game/data.md`，补充 `IDataRepository` / `UnifiedSettingsDataRepository` 的统一事件与备份语义说明
-- [x] 修正 `docs/zh-CN/game/data.md`，补充 `UnifiedSettingsDataRepository` 的最小接入示例、
-  `RegisterDataType(...)` 说明与 `DataLoadedEvent<T>` 兼容性说明
-- [x] 修正 `docs/zh-CN/game/index.md` 中 `JsonSerializer` 示例缺少 `Newtonsoft.Json` using 的问题
-- [x] `setting.md` 中迁移接口示例统一改为 `ISettingsData`，清掉残留旧术语
-- [x] 当时已更新 `AGENTS.md`，强调实现完成后必须同步维护恢复文档；当前仓库已由 `ai-plan` 治理规则接管该职责
-
-## 历史改动文件
-
-### 生产代码
-
-- `GFramework.Game/Serializer/JsonSerializer.cs`
-- `GFramework.Game/Setting/SettingsModel.cs`
-- `GFramework.Game/Data/UnifiedSettingsDataRepository.cs`
-- `GFramework.Game/Data/DataRepository.cs`
-- `GFramework.Game.Abstractions/Data/ISaveMigration.cs`
-- `GFramework.Game.Abstractions/Data/ISaveRepository.cs`
-- `GFramework.Game/Data/SaveRepository.cs`
-- `GFramework.Game.Abstractions/Data/DataRepositoryOptions.cs`
-
-### 测试
-
-- `GFramework.Game.Tests/Serializer/JsonSerializerTests.cs`
-- `GFramework.Game.Tests/Setting/SettingsModelTests.cs`
-- `GFramework.Game.Tests/Setting/SettingsSystemTests.cs`
-- `GFramework.Game.Tests/Data/PersistenceTestUtilities.cs`
-- `GFramework.Game.Tests/Data/PersistenceTests.cs`
-
-### 文档
-
-- `AGENTS.md`
-- `docs/zh-CN/game/setting.md`
-- `docs/zh-CN/game/data.md`
-- `docs/zh-CN/game/index.md`
-
-## 已验证结果
-
-已执行：
-
-```bash
-dotnet test GFramework.Game.Tests/GFramework.Game.Tests.csproj --filter "JsonSerializerTests"
-dotnet test GFramework.Game.Tests/GFramework.Game.Tests.csproj --filter "JsonSerializerTests|SettingsModelTests|PersistenceTests"
-dotnet test GFramework.Game.Tests/GFramework.Game.Tests.csproj
-dotnet test GFramework.Game.Tests/GFramework.Game.Tests.csproj -c Release --filter "PersistenceTests"
-dotnet test GFramework.Game.Tests/GFramework.Game.Tests.csproj -c Release
-dotnet test GFramework.Game.Tests/GFramework.Game.Tests.csproj -c Release --filter "PersistenceTests|SettingsSystemTests"
-dotnet test GFramework.Game.Tests/GFramework.Game.Tests.csproj -c Release --filter "PersistenceTests|SettingsSystemTests|SettingsModelTests"
-```
-
-结果：
-
-- `JsonSerializerTests`：通过
-- `JsonSerializerTests | SettingsModelTests | PersistenceTests`：12 个通过
-- `PersistenceTests`（Release）：7 个通过
-- `PersistenceTests | SettingsSystemTests`（Release）：16 个通过
-- `PersistenceTests | SettingsSystemTests | SettingsModelTests`（Release）：18 个通过
-- `PersistenceTests | SettingsSystemTests`（Release，补充回归后）：19 个通过
-- `PersistenceTests | SettingsSystemTests | SettingsModelTests`（Release，补充回归后）：21 个通过
-- `GFramework.Game.Tests` 全量（Release）：89 个通过
-
-## 本轮发现的真实问题
-
-### 已修复
-
-- `UnifiedSettingsDataRepository.SaveAsync(...)` 在未加载状态下会先拿 `_lock`，再进入 `EnsureLoadedAsync()`，
-  导致首次保存等待同一把 `SemaphoreSlim`，形成死锁
-- `UnifiedSettingsDataRepository` 在删除或保存时先原地修改 `_file` 再写盘，如果持久化失败会让内存缓存领先于
-  磁盘状态，后续无关保存可能把失败修改意外落盘；现已改为快照提交模型
-- `SaveRepository<T>` 的迁移注册表在注册与加载并发时缺少同步保护，且重复注册相同 `FromVersion` 会被静默覆盖，
-  已改为加锁访问并显式拒绝重复注册
-
-### 已确认但暂未展开
-
-- `SettingsSystem` / `SettingsModel` 仍依赖上下文事件发送，单元测试需要显式提供上下文
-
-## 当前剩余待办
-
-### P0
-
-- [x] 统一 `DataRepository` 与 `UnifiedSettingsDataRepository` 的持久化策略约定
-
-### P1
-
-- [ ] 评估是否要给 `JsonSerializer` 增加更明确的只读配置说明，例如线程安全和实例级 converter 使用方式
-- [x] 为 `SettingsSystem` 增加直接测试，覆盖 `ApplyAll / Reset / SaveAll` 的系统层语义
-- [x] 为 `UnifiedSettingsDataRepository` 增加事件开启场景下的上下文集成测试
-
-### P2
-
-- [ ] 评估把设置、存档、通用仓库的版本迁移模型做统一抽象
-- [ ] 评估压缩 / 加密 / 元数据策略是否应放进更明确的 codec / persistence pipeline
-
-## 下次恢复建议
-
-建议从这里继续：
-
-1. 先评估 `JsonSerializer` 的只读配置、线程安全与实例级 converter 使用说明
-2. 再考虑设置 / 存档 / 通用仓库的迁移模型是否进一步统一
-3. 最后评估压缩 / 加密 / 元数据策略是否抽成更明确的 codec / persistence pipeline
-
-恢复时优先查看：
-
-- `GFramework.Game/Data/SaveRepository.cs`
-- `GFramework.Game/Data/UnifiedSettingsDataRepository.cs`
-- `GFramework.Game/Data/DataRepository.cs`
-- `GFramework.Game/Setting/SettingsModel.cs`
-- `GFramework.Game/Setting/SettingsSystem.cs`
-- `GFramework.Game/Serializer/JsonSerializer.cs`
-- `GFramework.Game.Tests/Data/PersistenceTests.cs`
-- `GFramework.Game.Tests/Setting/SettingsSystemTests.cs`
-- `docs/zh-CN/game/data.md`
-
-## 备注
-
-- 该历史阶段形成时，仓库存在大量与本任务无关的既有改动
-- 后续继续实施时，应继续把改动严格收敛在设置 / 持久化 / 序列化相关文件，避免误碰其他重构主线

ai-plan/public/data-repository-persistence/archive/traces/data-repository-persistence-history-pre-rp001.md

@@ -1,62 +0,0 @@
-# Data Repository Persistence 历史追踪
-
-> 说明：旧 `local-plan` 没有独立 trace，而是由
-> `local-plan/settings-persistence-serialization-tracking.md` 同时承担 tracking / trace 职责。
-> 本文件基于该混合材料整理，只保留可稳定确认的事实、决策、验证与 backlog，不补写无法从原文推导的逐时序细节。
-
-## 历史阶段：设置 / 持久化 / 序列化第一轮收敛（pre-RP001）
-
-### 关键目标
-
-- 修正文档与当前实现不一致的问题
-- 补足关键直接测试，避免只靠侧面覆盖
-- 修复本轮实现中暴露出来的真实缺陷
-- 为后续更大的存档迁移 / 持久化策略统一保留清晰恢复点
-
-### 已确认落地的实现决策
-
-- 为 `JsonSerializer` 补齐实例级配置入口，并保留 `Serialize(object, Type)` 在 `null` 场景下输出 `"null"` 的兼容语义
-- 将 `DataRepository` 与 `UnifiedSettingsDataRepository` 的批量保存语义收口到批量提交事件，避免重复发送单项保存事件
-- 让 `DataRepository` / `UnifiedSettingsDataRepository` 在批量保存和加载时保留运行时数据类型与泛型事件类型，避免回退到
-  `IData`
-- 为 `SettingsModel` 的动态注册、applicator 绑定与 migration cache 失效补齐直接语义
-- 为 `UnifiedSettingsDataRepository` 引入“快照 -> 持久化 -> 交换缓存”的提交模型，避免失败写入污染已提交缓存
-- 为 `ISaveRepository<T>` / `SaveRepository<T>` 建立正式的 `ISaveMigration<T>` 迁移链能力，并为注册表并发访问补同步保护
-
-### 已确认落地的验证
-
-- 已新增 `JsonSerializer`、`SettingsModel`、`SettingsSystem`、`Persistence` 等直接测试
-- 已验证 `SaveRepository<T>` 迁移链、重复注册、缺失迁移链、批量事件、自动备份、运行时类型覆盖与缓存一致性回归
-- 已同步更新 `docs/zh-CN/game/setting.md`、`docs/zh-CN/game/data.md` 与 `docs/zh-CN/game/index.md`
-- 原始记录中的测试命令包括：
-  - `dotnet test GFramework.Game.Tests/GFramework.Game.Tests.csproj --filter "JsonSerializerTests"`
-  - `dotnet test GFramework.Game.Tests/GFramework.Game.Tests.csproj --filter "JsonSerializerTests|SettingsModelTests|PersistenceTests"`
-  - `dotnet test GFramework.Game.Tests/GFramework.Game.Tests.csproj`
-  - `dotnet test GFramework.Game.Tests/GFramework.Game.Tests.csproj -c Release --filter "PersistenceTests"`
-  - `dotnet test GFramework.Game.Tests/GFramework.Game.Tests.csproj -c Release`
-  - `dotnet test GFramework.Game.Tests/GFramework.Game.Tests.csproj -c Release --filter "PersistenceTests|SettingsSystemTests"`
-  - `dotnet test GFramework.Game.Tests/GFramework.Game.Tests.csproj -c Release --filter "PersistenceTests|SettingsSystemTests|SettingsModelTests"`
-- 原始记录确认的结果包括：
-  - `JsonSerializerTests`：通过
-  - `JsonSerializerTests | SettingsModelTests | PersistenceTests`：12 个通过
-  - `PersistenceTests`（Release）：7 个通过
-  - `PersistenceTests | SettingsSystemTests`（Release）：16 个通过，补充回归后为 19 个通过
-  - `PersistenceTests | SettingsSystemTests | SettingsModelTests`（Release）：18 个通过，补充回归后为 21 个通过
-  - `GFramework.Game.Tests` 全量（Release）：89 个通过
-
-### 从历史材料中确认的真实问题
-
-- `UnifiedSettingsDataRepository.SaveAsync(...)` 在未加载状态下可能发生自锁死锁，已修复
-- `UnifiedSettingsDataRepository` 持久化失败时会让缓存领先于磁盘状态，已改为快照提交模型
-- `SaveRepository<T>` 迁移注册表缺少并发保护且会静默覆盖重复 `FromVersion` 注册，已改为加锁并显式拒绝重复注册
-
-### 留存 backlog
-
-- P1：评估 `JsonSerializer` 的只读配置、线程安全与实例级 converter 使用说明是否需要进一步补强
-- P2：评估设置、存档、通用仓库的版本迁移模型是否应进一步统一抽象
-- P2：评估压缩 / 加密 / 元数据策略是否应抽成更明确的 codec / persistence pipeline
-
-### 恢复边界
-
-- 这份历史追踪来自单文件混合材料，不包含独立的逐日执行日志
-- 后续如需继续该主题，应以 active tracking / trace 为恢复入口，再回看本文件的稳定历史结论

ai-plan/public/data-repository-persistence/todos/data-repository-persistence-tracking.md

@@ -1,53 +0,0 @@
-# Data Repository Persistence 跟踪
-
-## 目标
-
-继续收敛 `GFramework.Game` 当前的数据仓库持久化、设置模型与序列化语义，确保第一轮高优先级修复、测试与文档
-同步之后，剩余设计性 follow-up 仍有清晰、可共享的恢复入口。
-
-## 当前恢复点
-
-- 恢复点编号：`DATA-REPOSITORY-PERSISTENCE-RP-001`
-- 当前阶段：`Phase 1`
-- 当前焦点：
-  - 已将根目录 legacy `local-plan/settings-persistence-serialization-tracking.md` 迁入
-    `ai-plan/public/data-repository-persistence/`
-  - 第一轮 settings / persistence / serialization 修复、测试与文档同步已完成，并收入主题内 `archive/`
-  - 下一轮需要继续评估 `JsonSerializer` 配置说明、迁移模型统一抽象与 codec / persistence pipeline 边界
-
-## 当前状态摘要
-
-- 高优先级实现、测试与文档对齐已在本主题历史阶段完成，当前 active 入口主要保留后续 design/backlog 恢复点
-- 当前分支 `feat/data-repository-persistence` 已在 `ai-plan/public/README.md` 建立 topic 映射
-- 旧单文件不再同时承担 todo 与 trace 角色，后续恢复统一从本 topic 的 active tracking / trace 进入
-
-## 当前活跃事实
-
-- 原 `local-plan` 只有一份混合 tracking 文件，没有独立的 `todos/` 与 `traces/`
-- 详细历史已拆分迁入主题内 `archive/`，active tracking / trace 只保留当前恢复点、风险与下一步
-- 历史已验证结果包括 `GFramework.Game.Tests` 的定向与全量通过，以及 `docs/zh-CN/game/*` 的同步更新
-
-## 当前风险
-
-- 只读配置 / 线程安全说明缺口：`JsonSerializer` 新增 settings 与 converter 扩展后，若不补充约束说明，后续容易被误用
-  - 缓解措施：下一轮先核对源码与文档，必要时补 XML docs 或采用文档
-- 迁移模型分叉风险：`SettingsModel`、`DataRepository` 与 `SaveRepository<T>` 的版本演进机制仍可能继续分叉
-  - 缓解措施：在新增更多 persistence feature 前，先评估能否抽出统一的 migration abstraction
-- Active 入口回膨胀风险：若后续把实现细节继续堆回 active 文档，会重新退化成旧 `local-plan`
-  - 缓解措施：后续阶段完成并验证后，继续迁入本 topic 的 `archive/`
-
-## 活跃文档
-
-- 历史跟踪归档：[data-repository-persistence-history-pre-rp001.md](../archive/todos/data-repository-persistence-history-pre-rp001.md)
-- 历史 trace 归档：[data-repository-persistence-history-pre-rp001.md](../archive/traces/data-repository-persistence-history-pre-rp001.md)
-
-## 验证说明
-
-- 旧混合 `local-plan` 已拆分迁入主题内 archive
-- active 跟踪文件已按 `ai-plan` 治理规则精简为当前恢复入口
-
-## 下一步
-
-1. 先评估 `JsonSerializer` 的只读配置、线程安全与实例级 converter 使用说明是否需要补足
-2. 再评估设置 / 通用仓库 / 存档仓库的迁移模型是否要统一抽象
-3. 最后评估压缩 / 加密 / 元数据策略是否应落入更明确的 codec / persistence pipeline

ai-plan/public/data-repository-persistence/traces/data-repository-persistence-trace.md

@@ -1,30 +0,0 @@
-# Data Repository Persistence 追踪
-
-## 2026-04-19
-
-### 阶段：legacy local-plan 迁移建档（RP-001）
-
-- 复核当前工作树后确认：根目录 `local-plan/` 只剩一份
-  `settings-persistence-serialization-tracking.md`，它同时承担 todo 与 trace 角色
-- 按 `ai-plan` 治理规则建立 `ai-plan/public/data-repository-persistence/` 主题目录，并补齐：
-  - `todos/`
-  - `traces/`
-  - `archive/todos/`
-  - `archive/traces/`
-- 将旧混合文件拆分为主题内历史跟踪归档与基于同一材料整理的历史 trace，active 入口只保留当前恢复点、
-  活跃事实、风险与下一步
-- 在 `ai-plan/public/README.md` 中建立
-  `feat/data-repository-persistence` -> `data-repository-persistence` 的 worktree 映射
-- 同步更新 `ai-plan-governance` 的 tracking / trace，记录 legacy 单文件计划也已按新目录语义收口
-
-### Archive Context
-
-- 历史跟踪归档：
-  - `ai-plan/public/data-repository-persistence/archive/todos/data-repository-persistence-history-pre-rp001.md`
-- 历史 trace 归档：
-  - `ai-plan/public/data-repository-persistence/archive/traces/data-repository-persistence-history-pre-rp001.md`
-
-### 下一步
-
-1. 后续继续该主题时，只从 `ai-plan/public/data-repository-persistence/` 进入，不再恢复 `local-plan/`
-2. 若 active 入口再次积累多轮已完成且已验证阶段，继续按同一模式迁入该主题自己的 `archive/`

ai-plan/public/documentation-governance-and-refresh/archive/todos/documentation-governance-and-refresh-history-through-2026-04-18.md

@@ -1,163 +0,0 @@
-# GFramework 文档治理与重写任务单
-
-> 说明：本归档由 `2026-04-19` 的 `local-plan/` 迁移生成，原历史内容已按当前 `ai-plan` 目录语义做最小整理。
-
-目标：
-
-- 重建 `GFramework` 的总入口、模块入口和 `docs/zh-CN` 采用链路，避免继续传播失真的 API、安装方式和目录结构。
-- 把文档更新责任写入 `AGENTS.md`，避免未来继续出现“新增模块没有 `README.md`”或“改行为不改文档”的回归。
-- 建立主题恢复文档与执行轨迹，让后续 AI 或人工可以在任意阶段无损接手。
-
-阶段完成标准：
-
-- `AGENTS.md` 明确规定 README、docs、示例真实性与恢复文档维护要求
-- 根 `README.md` 与 VitePress 顶层信息架构一致，不再包含错误入口
-- `getting-started` 入口与最小示例不再依赖失真的旧文档
-- 高优先级模块至少补齐或重写以下 README：
-  - `GFramework.Cqrs`
-  - `GFramework.Cqrs.Abstractions`
-  - `GFramework.Game`
-  - `GFramework.Game.Abstractions`
-  - `GFramework.Core`
-  - `GFramework.Core.Abstractions`
-  - `GFramework.Game.SourceGenerators`
-  - `GFramework.Cqrs.SourceGenerators`
-  - `GFramework.Core.SourceGenerators`
-- `docs/zh-CN/abstractions/` 拥有真实 landing page，且导航不再悬空
-
----
-
-## 事实来源
-
-当前文档工作必须遵守以下证据优先级：
-
-1. 源码、`*.csproj`、包关系、生成器 targets
-2. 测试与 snapshot
-3. `CoreGrid` 的真实接入方式与目录组织
-4. 现有 `README.md` 与 `docs/zh-CN`
-
-说明：
-
-- 旧文档只作为待修输出，不作为行为真相。
-- `CoreGrid` 仅用于补充真实采用路径，不反向定义框架规范。
-
----
-
-## 当前阶段
-
-Status: 🟡 In Progress
-
-当前阶段目标：
-
-- [x] 建立主题 todo 与 trace
-- [x] 收紧 `AGENTS.md` 文档治理规则
-- [x] 修复根 `README.md` 的信息架构和错误入口
-- [x] 为 `docs/zh-CN/abstractions/` 补 landing page，并接回导航
-- [x] 重写 `getting-started/index.md`
-- [x] 重写 `getting-started/quick-start.md`
-- [x] 补齐 / 重写高优先级模块 README
-- [x] 运行一轮链接与文档存在性校验
-
----
-
-## P0 必做
-
-### 1. 文档治理规则收口
-
-Status: 🟢 Implemented
-
-- [x] 明确 README 必须随模块建立
-- [x] 明确文档证据优先级
-- [x] 明确根 `README.md` 必须镜像站点 IA
-- [x] 明确文档任务必须维护恢复文档
-
-### 2. 总入口修复
-
-Status: 🟢 Implemented
-
-- [x] 修复根 `README.md` 中不存在的入口
-- [x] 统一文档栏目命名
-- [x] 调整根 README 到栏目 landing page 的链接
-- [x] 校正根 README 中的包选择说明
-
-### 3. 采用链路重写
-
-Status: 🟢 Implemented
-
-- [x] 重写 `docs/zh-CN/getting-started/index.md`
-- [x] 重写 `docs/zh-CN/getting-started/quick-start.md`
-- [x] 为 `abstractions` 栏目补 landing page
-
-### 4. 模块 README 第一批
-
-Status: 🟢 Implemented
-
-- [x] `GFramework.Cqrs`
-- [x] `GFramework.Cqrs.Abstractions`
-- [x] `GFramework.Game`
-- [x] `GFramework.Game.Abstractions`
-- [x] `GFramework.Core`
-- [x] `GFramework.Core.Abstractions`
-- [x] `GFramework.Game.SourceGenerators`
-- [x] `GFramework.Cqrs.SourceGenerators`
-- [x] `GFramework.Core.SourceGenerators`
-
-### 5. 最小化验证
-
-Status: 🟢 Implemented
-
-- [x] 确认旧错误入口 `tutorials/getting-started.md` 不再被引用
-- [x] 确认 `abstractions` landing page 已接回导航
-- [x] 确认第一批高优先级 README 文件均已存在
-- [x] 运行 `bun install`
-- [x] 运行 `bun run build`
-
----
-
-## 当前恢复点
-
-Recovery Point ID: `doc-refresh-phase0-1-and-module-readmes`
-
-当前推荐恢复步骤：
-
-1. 以 `core/`、`game/`、`source-generators/` 三个栏目为单位继续核对专题页内容真实性
-2. 按栏目整理“旧文档仍失真”的页面清单
-3. 把第二轮重写拆成按栏目推进的 todo
-
----
-
-## 已接受的并行工作
-
-- `CQRS` README 子任务：补写 `GFramework.Cqrs/README.md` 与 `GFramework.Cqrs.Abstractions/README.md`
-- `Game` README 子任务：重写 `GFramework.Game/README.md` 与 `GFramework.Game.Abstractions/README.md`
-
-已验收结果：
-
-- `CQRS` README 已按当前代码结构补齐运行时、契约层、生成注册表与反射回退协作说明
-- `Game` README 已按运行时实现、契约层边界与 CoreGrid 实际接法重写
-
-主代理负责：
-
-- `AGENTS.md`
-- 根 `README.md`
-- 主题恢复文档
-- `docs/.vitepress/config.mts`
-- `docs/zh-CN/getting-started/*`
-- `docs/zh-CN/abstractions/index.md`
-- `GFramework.Core*` 与 Source Generator 相关 README
-
----
-
-## 风险与注意事项
-
-- 现有 `docs/zh-CN` 中不少示例看起来“像真的”，但不能直接复用，必须回到代码核实。
-- 根包 `GeWuYou.GFramework` 当前只聚合 `Core` 与 `Game`，文档不能再把它描述为全部模块集合。
-- `LICENSE` 与部分包元数据之间可能存在历史漂移，本轮先以仓库根许可证和当前用户可见入口为准，不顺带修包元数据。
-
----
-
-## 下一步
-
-- 按栏目继续重写 `docs/zh-CN/core/*`
-- 再推进 `docs/zh-CN/game/*` 与 `docs/zh-CN/source-generators/*`
-- 视内容漂移程度决定是否补第二轮模块 README 或直接切专题页

ai-plan/public/documentation-governance-and-refresh/archive/traces/documentation-governance-and-refresh-history-through-2026-04-18.md

@@ -1,81 +0,0 @@
-# GFramework 文档治理执行轨迹
-
-> 说明：本归档由 `2026-04-19` 的 `local-plan/` 迁移生成，原历史内容已按当前 `ai-plan` 目录语义做最小整理。
-
-## 2026-04-18
-
-### 关键事实
-
-- 根 `README.md` 存在错误入口：`docs/zh-CN/tutorials/getting-started.md` 并不存在。
-- VitePress 顶层导航已采用 `getting-started / core / game / godot / tutorials / more` 的信息架构，但根 README
-  仍在使用另一套命名。
-- `docs/zh-CN/abstractions/` 在 sidebar 中已存在分类，但缺少 `index.md` landing page。
-- 多个对外模块缺失 `README.md`，尤其是 `GFramework.Cqrs`、`GFramework.Cqrs.Abstractions`、
-  `GFramework.Game.SourceGenerators`、`GFramework.Cqrs.SourceGenerators`。
-- `GFramework.Game/README.md` 与 `GFramework.Game.Abstractions/README.md` 存在明显失真，无法承担模块入口职责。
-
-### 已执行决策
-
-- 接受“旧文档不可默认信任”的前提，后续文档以代码、测试和 `CoreGrid` 真实用法为准。
-- 保留 `abstractions` 为独立栏目，并为其补 landing page 与导航入口，而不是继续让它悬空。
-- 把根 `README.md` 重写为站点 IA 的 GitHub 镜像入口，不再维护另一套栏目命名。
-- 把 README 命名规范统一为 `README.md`，后续不新增 `ReadMe.md` 变体。
-
-### 并行委派
-
-- 子任务 A：`GFramework.Cqrs/README.md` 与 `GFramework.Cqrs.Abstractions/README.md`
-- 子任务 B：`GFramework.Game/README.md` 与 `GFramework.Game.Abstractions/README.md`
-
-### 已接受的子任务结论
-
-- `GFramework.Cqrs/README.md`
-  - 已按当前 runtime 结构补充 dispatcher、注册器、上下文扩展、source generator 协作与反射回退说明。
-- `GFramework.Cqrs.Abstractions/README.md`
-  - 已明确其仅为协议层，不提供默认 dispatcher 或注册逻辑。
-- `GFramework.Game/README.md`
-  - 已按配置、数据、设置、Scene/UI 路由、存储、序列化等真实运行时子系统重写。
-- `GFramework.Game.Abstractions/README.md`
-  - 已按契约边界、适用场景与 CoreGrid 的真实依赖方式重写。
-
-### 当前主线改动
-
-- 更新 `AGENTS.md` 文档治理规则
-- 建立主题恢复文档
-- 重写根 `README.md`
-- 调整 `docs/.vitepress/config.mts`
-- 重写 `docs/zh-CN/getting-started/index.md`
-- 重写 `docs/zh-CN/getting-started/quick-start.md`
-- 新增 `docs/zh-CN/abstractions/index.md`
-- 重写 `GFramework.Core/README.md`
-- 重写 `GFramework.Core.Abstractions/README.md`
-- 新增 `GFramework.Game.SourceGenerators/README.md`
-- 新增 `GFramework.Cqrs.SourceGenerators/README.md`
-- 重写 `GFramework.Core.SourceGenerators/README.md`
-- 审阅并接纳 `CQRS` / `Game` 两组 README 子任务结果
-
-### 验证结果
-
-- `rg` 校验确认：
-  - 旧错误入口 `docs/zh-CN/tutorials/getting-started.md` 已不再被引用
-  - `docs/zh-CN/getting-started/` 内已无跨到仓库根 README 的相对链接
-- 文件存在性校验确认：
-  - `GFramework.Cqrs`
-  - `GFramework.Cqrs.Abstractions`
-  - `GFramework.Game`
-  - `GFramework.Game.Abstractions`
-  - `GFramework.Core`
-  - `GFramework.Core.Abstractions`
-  - `GFramework.Game.SourceGenerators`
-  - `GFramework.Cqrs.SourceGenerators`
-  - `GFramework.Core.SourceGenerators`
-  均已拥有 `README.md`
-- 文档站验证：
-  - 在 `docs/` 下执行 `bun install`
-  - 在 `docs/` 下执行 `bun run build`
-  - 构建成功；仅出现既有的大 chunk warning，无阻塞错误
-
-### 下一步
-
-- 继续核对 `docs/zh-CN/core/*` 的示例真实性
-- 按栏目推进 `game/*` 与 `source-generators/*` 的专题页重写
-- 视专题页真实情况决定第二轮是否拆分新的恢复子任务

ai-plan/public/documentation-governance-and-refresh/todos/documentation-governance-and-refresh-tracking.md

@@ -1,54 +0,0 @@
-# Documentation Governance And Refresh 跟踪
-
-## 目标
-
-继续以“文档必须可追溯到源码、测试与真实接入方式”为原则，收敛 `GFramework` 的仓库入口、模块入口与
-`docs/zh-CN` 采用链路，避免未来再次出现 API、安装方式与目录结构失真。
-
-## 当前恢复点
-
-- 恢复点编号：`DOCUMENTATION-GOVERNANCE-REFRESH-RP-001`
-- 当前阶段：`Phase 1`
-- 当前焦点：
-  - 已将当前工作树根目录的 legacy `local-plan/` 迁入 `ai-plan/public/documentation-governance-and-refresh/`
-  - 第一轮治理已完成 `AGENTS.md`、根 `README.md`、`getting-started` 与第一批高优先级模块 `README.md`
-  - 下一轮需要继续按栏目核对并重写 `docs/zh-CN/core/*`、`docs/zh-CN/game/*` 与
-    `docs/zh-CN/source-generators/*`
-
-## 当前状态摘要
-
-- 文档治理规则已收口到仓库规范，README、站点入口与采用链路不再依赖旧文档自证
-- 高优先级模块入口已补齐，首轮文档站构建校验已经通过
-- 当前主题仍是 active topic，因为核心栏目专题页仍可能包含与实现漂移的旧内容
-
-## 当前活跃事实
-
-- 旧 `local-plan/` 的详细 todo 与 trace 已迁入主题内 `archive/`
-- 当前分支 `docs/sdk-update-documentation` 已在 `ai-plan/public/README.md` 建立 topic 映射
-- active 跟踪文件只保留当前恢复点、活跃事实、风险与下一步，不再重复保存已完成阶段的长篇历史
-
-## 当前风险
-
-- 旧专题页示例失真风险：`docs/zh-CN/core/*`、`game/*` 与 `source-generators/*` 中仍可能保留看似合理但与
-  真实实现不一致的示例
-  - 缓解措施：继续按源码、测试、`*.csproj` 与 `CoreGrid` 真实接法核对，不把旧文档当事实来源
-- 采用路径误导风险：根聚合包与模块边界若再次被写错，会继续误导消费者的包选择
-  - 缓解措施：保持“源码与包关系优先”的证据顺序，改动采用说明时同步核对包依赖与生成器 wiring
-- Active 入口回膨胀风险：后续若把栏目级重写过程直接追加到 active 文档，会再次拖慢恢复
-  - 缓解措施：阶段完成并验证后，继续把细节迁入本 topic 的 `archive/`
-
-## 活跃文档
-
-- 历史跟踪归档：[documentation-governance-and-refresh-history-through-2026-04-18.md](../archive/todos/documentation-governance-and-refresh-history-through-2026-04-18.md)
-- 历史 trace 归档：[documentation-governance-and-refresh-history-through-2026-04-18.md](../archive/traces/documentation-governance-and-refresh-history-through-2026-04-18.md)
-
-## 验证说明
-
-- 旧 `local-plan/` 的详细实施历史与文档站构建结果已迁入主题内归档
-- active 跟踪文件已按 `ai-plan` 治理规则精简为当前恢复入口
-
-## 下一步
-
-1. 继续按栏目核对 `docs/zh-CN/core/*`，列出仍失真的页面与示例
-2. 再推进 `docs/zh-CN/game/*` 与 `docs/zh-CN/source-generators/*` 的专题页重写
-3. 若下一轮重写完成且验证通过，将栏目级详细过程迁入本 topic 的 `archive/`

ai-plan/public/documentation-governance-and-refresh/traces/documentation-governance-and-refresh-trace.md

@@ -1,31 +0,0 @@
-# Documentation Governance And Refresh 追踪
-
-## 2026-04-19
-
-### 阶段：local-plan 迁移收口（RP-001）
-
-- 复核当前工作树后确认：worktree 根目录仅剩一个 legacy `local-plan/`，其内容属于文档治理与重写主题的
-  durable recovery state，不应继续作为独立根目录入口存在
-- 按 `ai-plan` 治理规则建立 `ai-plan/public/documentation-governance-and-refresh/` 主题目录，并补齐：
-  - `todos/`
-  - `traces/`
-  - `archive/todos/`
-  - `archive/traces/`
-- 将原 `local-plan` 中的详细 tracking / trace 迁入主题内历史归档，并为 active 入口只保留当前恢复点、
-  活跃事实、风险与下一步
-- 在 `ai-plan/public/README.md` 中建立
-  `docs/sdk-update-documentation` -> `documentation-governance-and-refresh` 的 worktree 映射
-- 同步更新 `ai-plan-governance` 的 tracking / trace，记录本次迁移已验证当前工作树不再依赖 worktree-root
-  `local-plan/`
-
-### Archive Context
-
-- 历史跟踪归档：
-  - `ai-plan/public/documentation-governance-and-refresh/archive/todos/documentation-governance-and-refresh-history-through-2026-04-18.md`
-- 历史 trace 归档：
-  - `ai-plan/public/documentation-governance-and-refresh/archive/traces/documentation-governance-and-refresh-history-through-2026-04-18.md`
-
-### 下一步
-
-1. 后续继续该主题时，只从 `ai-plan/public/documentation-governance-and-refresh/` 进入，不再恢复 `local-plan/`
-2. 若 active 入口再次积累多轮已完成且已验证阶段，继续按同一模式迁入该主题自己的 `archive/`