GFramework/ai-plan/public/documentation-full-coverage-governance/todos/documentation-full-coverage-governance-tracking.md

Documentation Full Coverage Governance 跟踪

目标

建立一个长期 active topic，持续治理 GFramework 的 README、docs/zh-CN、站点导航、XML 文档和 API 参考链路，避免阶段性刷新完成后再次回漂。

• 用源码、测试、*.csproj 和必要的 ai-libs/ 证据校正文档
• 以模块族为单位闭环 README、landing page、专题页、教程入口和 API 参考链路
• 明确哪些目录是可直接消费模块，哪些只是内部支撑模块
• 把 XML 文档缺口纳入治理范围，而不是只刷新 Markdown

当前恢复点

• 恢复点编号：DOCUMENTATION-FULL-COVERAGE-GOV-RP-034
• 当前阶段：Phase 5 - Governance Maintenance
• 当前焦点：
  • 按本轮 $gframework-batch-boot 50 约束继续使用 origin/main（984fb21，2026-04-25 11:11:56 +08:00）作为唯一 baseline，只推进低风险、可切片的文档治理批次
  • 本轮已收口三类目标：5 个模块 README 的语义化链接标签、7 个 Core 热点页的代码块语言标记、7 个基础教程页的代码块语言标记
  • 当前已接收 worker A 的 README 切片结果；其余代码块标记批次由主线程统一复核并补齐
  • 本轮 19 个文档文件连同 active tracking / trace 已落地；当前 branch diff 已确认达到 21 / 50 个 changed files，仍处于当前批次阈值安全区间
  • 下一轮若继续批处理，优先挑选新的低风险 reader-facing 缺口，并保持单批次预计落地规模不超过剩余 headroom

当前状态摘要

• Core、Ecs.Arch、Cqrs、Game、Godot 五个模块族当前都已有 README / landing / topic / API 参考层级的已验证入口。
• 2026-04-25 worker A 已完成并提交 5 个模块 README 的 reader-facing 链接标签修正，提交为 bd5cdb5（docs(readme): 优化链接标签）；当前批次已接受该切片结果。
• 2026-04-25 主线程补齐了 docs/zh-CN/core/configuration.md、extensions.md、ioc.md、localization.md、pause.md、pool.md、system.md 的裸 fenced code block opening 语言标记。
• 2026-04-25 教程批次当前覆盖 docs/zh-CN/tutorials/basic/01-environment.md 到 07-summary.md，补齐的内容以目录树、流程图和控制台输出为主，统一显式标注为 text。
• 2026-04-25 当前实际 branch diff 已更新为 21 / 50 个 changed files；其中 5 个文件来自已提交的 README 标签切片，16 个文件来自本轮代码块标记与 active tracking / trace 更新。
• 2026-04-25 本轮目录级验证已覆盖 docs/zh-CN/core 与 docs/zh-CN/tutorials/basic，README 目标文件链接校验和 docs/ 站点构建也都已通过。
• Game persistence docs surface 当前以 docs/zh-CN/game/data.md、storage.md、serialization.md、setting.md 作为最小巡检集合；若后续 README、runtime public API 或 PersistenceTests 变动，应优先复核这一组页面。
• Godot runtime 与 generator 入口当前以 GFramework.Godot/README.md、 GFramework.Godot.SourceGenerators/README.md、docs/zh-CN/godot/index.md、 docs/zh-CN/source-generators/index.md、docs/zh-CN/tutorials/godot-integration.md 维持统一 owner / adoption path。
• 2026-04-23 到 2026-04-24 的批次细节、验证日志与旧恢复建议已迁入： ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-status-history-rp-023-to-rp-025-2026-04-24.md

当前风险

• 当前 Core / Core.Abstractions、Ecs.Arch、Cqrs、Game 的 XML 治理证据仍主要来自类型与入口级阅读，不等于成员级契约全审计；这类治理状态只应保留在 ai-plan/**，不应再暴露到公开文档。
• GFramework.Cqrs 在当前 WSL / dotnet 环境下仍会读取失效的 fallback package folder，并在标准 build 中触发 MSB4276 / MSB4018；这是已知环境阻塞，不属于本轮文档回归。
• 当前 WSL 会话里 git.exe 可解析但不能执行，应继续使用显式 --git-dir / --work-tree 绑定作为默认 Git 策略。
• README 链接标签与 Core / 教程代码块标记这两类低风险批次已经消化完本轮目标文件，但 docs/zh-CN 其他目录仍可能保留未显式标语言的历史代码块。
• PR #287 的 latest-head review 是否还有 open thread 尚未在本轮重新抓取；若继续下一轮，应先复核远端 review 状态再扩批。

归档指针

• 详细验证历史（RP-001 到 RP-007）： ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-through-rp-007.md
• 阶段状态归档（RP-001 到 RP-016）： ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-status-history-through-rp-016.md
• 阶段状态归档（RP-023 到 RP-025）： ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-status-history-rp-023-to-rp-025-2026-04-24.md
• 时间线归档（RP-001 到 RP-016）： ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-through-rp-016.md
• 时间线归档（RP-023 到 RP-025）： ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-rp-023-to-rp-025-2026-04-24.md

最新验证

• 2026-04-25 bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Core/README.md
  • 结果：通过；README 链接目标有效。
• 2026-04-25 bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Core.SourceGenerators/README.md
  • 结果：通过；README 链接目标有效。
• 2026-04-25 bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Cqrs.SourceGenerators/README.md
  • 结果：通过；README 链接目标有效。
• 2026-04-25 bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Ecs.Arch/README.md
  • 结果：通过；README 链接目标有效。
• 2026-04-25 bash .agents/skills/gframework-doc-refresh/scripts/validate-links.sh GFramework.Game.SourceGenerators/README.md
  • 结果：通过；README 链接目标有效。
• 2026-04-25 rg -n '\\[[^\\]]*(README\\.md|\\.md|\\.md/|/zh-CN/[^\\]]*)\\]\\([^)]*\\)' GFramework.Core/README.md GFramework.Core.SourceGenerators/README.md GFramework.Cqrs.SourceGenerators/README.md GFramework.Ecs.Arch/README.md GFramework.Game.SourceGenerators/README.md
  • 结果：无命中；本轮 5 个 README 已无可见路径式 / 文件名式 Markdown 链接标签残留。
• 2026-04-25 bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/core
  • 结果：通过；Core 栏目本轮触达页面的 frontmatter、链接与代码块校验均通过。
• 2026-04-25 bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN/tutorials/basic
  • 结果：通过；基础教程栏目本轮触达页面的 frontmatter、链接与代码块校验均通过。
• 2026-04-25 bun run build（工作目录：docs/）
  • 结果：通过；README 标签修正与 Core / 基础教程代码块语言标记补齐后站点仍可构建，仅保留既有大 chunk warning。
• 2026-04-24 python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/current-pr-review.json
  • 结果：通过；PR #284 处于 OPEN，latest head commit 77540c07f0890cc05b10a849722c87b8bed8f561 有 3 条 CodeRabbit 与 1 条 Greptile open thread，测试汇总为 2156 passed，仅剩 Title check 的 inconclusive PR 元数据提示。
• 2026-04-24 rg -n --pcre2 '\\]\\(/zh-CN/[^)]+(?<!\\.md)\\)' docs/zh-CN/troubleshooting.md
  • 结果：当前无命中；/zh-CN/core/architecture 与 /zh-CN/faq 已统一补成显式 .md 链接。
• 2026-04-24 bun run build（工作目录：docs/）
  • 结果：通过；文档标题本地化、站内链接修正与 ai-plan 归档瘦身落地后站点仍可正常构建，仅保留既有大 chunk warning。
• 2026-04-24 python3 - <<'PY' ...（扫描 docs/zh-CN/**/*.md frontmatter 是否缺 title / description）
  • 结果：通过；当前带 frontmatter 的 docs/zh-CN 页面已无 title / description 缺口。
• 2026-04-24 bun run build（工作目录：docs/）
  • 结果：通过；首页与基础教程 metadata 补齐后站点仍可正常构建，仅保留既有大 chunk warning。
• 2026-04-24 python3 - <<'PY' ...（扫描 docs/zh-CN/**/*.md 中以 ./、../、/zh-CN/ 开头且未带扩展名的 Markdown 链接）
  • 结果：通过；当前 docs/zh-CN 站内 Markdown 链接已无缺失扩展名的命中。
• 2026-04-24 bun run build（工作目录：docs/）
  • 结果：通过；25 个页面的站内链接补齐为显式 .md / index.md 后站点仍可正常构建，仅保留既有大 chunk warning。
• 2026-04-24 bun run build（工作目录：docs/）
  • 结果：通过；模块 README、中文落地页 reader-facing 文档入口对齐，以及 docs/index.md metadata 调整后站点仍可正常构建，仅保留既有大 chunk warning。
• 2026-04-24 python3 - <<'PY' ...（扫描 docs/zh-CN/**/*.md 中纯英文 title）
  • 结果：通过；经过三轮标题本地化后，仅剩 CQRS 与 GFramework 两个品牌/缩写型标题。
• 2026-04-24 bun run build（工作目录：docs/）
  • 结果：通过；根 README.md reader-friendly 链接标签修正与 docs/zh-CN 多页标题本地化落地后站点仍可正常构建，仅保留既有大 chunk warning。
• 2026-04-25 python3 .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Core
  • 结果：通过；技能仍能正常解析 Core 模块证据面，说明新增的 reader-facing 输出约束未破坏模块扫描主流程。
• 2026-04-25 python3 .agents/skills/gframework-pr-review/scripts/fetch_current_pr_review.py --json-output /tmp/current-pr-review.json
  • 结果：通过；PR #287 处于 OPEN，latest head commit 8209d7a29f35d969fca6258b9817da9b33a203a3 仅剩 1 条 Greptile open thread，无 failed checks，测试汇总为 2156 passed。
• 2026-04-25 bun run build（工作目录：docs/）
  • 结果：通过；docs/zh-CN/api-reference/index.md 的站内入口标签统一为语义化写法后站点仍可正常构建，仅保留既有大 chunk warning。
• 2026-04-25 bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN
  • 结果：通过；本轮触达页面的 frontmatter、链接与代码块校验均通过，脚本仅继续报告仓库中既有页面的“代码块缺少语言标记”警告。

下一步

1. 若继续下一轮 $gframework-batch-boot 50，优先重新抓取 $gframework-pr-review 确认 PR #287 的 latest-head review 是否还有 open thread；当前相对阈值仍有 29 个 changed files 的 headroom。
2. 后续若继续处理 reader-facing 文档问题，优先筛查剩余页面里的维护者视角限制说明、模块 README 中仍可能存在的裸路径标签，以及 docs/zh-CN 其他目录里的代码块语言标记缺口。
3. 若后续分支继续调整 Game persistence runtime、README 或公共 API，优先复核 docs/zh-CN/game/data.md、 storage.md、serialization.md、setting.md 与 landing page 是否仍保持同一套职责边界。
4. 若后续分支继续调整 Godot generator 接法，优先复核 GFramework.Godot.SourceGenerators/README.md、 docs/zh-CN/tutorials/godot-integration.md 与相关专题页是否仍保持一致。