GFramework/ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-rp-023-to-rp-025-2026-04-24.md

Documentation Full Coverage Governance Trace History RP-023 To RP-025

以下内容从 active trace 中迁出，用于保留 DOCUMENTATION-FULL-COVERAGE-GOV-RP-023 到 DOCUMENTATION-FULL-COVERAGE-GOV-RP-025 的执行时间线、关键决策与主要验证结果。默认 boot 只需要读取 active trace 中的最新恢复点；若需要追溯 2026-04-23 到 2026-04-24 的批处理执行顺序，再回到本归档文件。

2026-04-24

当前恢复点：RP-025

• 继续沿用 $gframework-batch-boot 75，基线保持 origin/main（2de57f5，2026-04-23T23:03:40+08:00）。
• 本轮目标从“继续治理公开文档边界”切换为“清空 docs/zh-CN 中仍然完全缺 frontmatter 的页面，同时把触达页暴露的真实格式错误一并收口”。
• 本轮执行的修复：
  • 为 best-practices、getting-started、source-generators、tutorials 等目录下共 22 个页面补齐 title / description frontmatter
  • 修复 docs/zh-CN/best-practices/multiplayer.md 末尾缺失的代码块闭合符
  • 修复 docs/zh-CN/source-generators/*.md 与 docs/zh-CN/troubleshooting.md 中一组缺少 .md 后缀或目录索引写法不兼容当前 validator 的站内链接

当前决策（RP-025）

• 对文档批处理，优先选择“元数据缺口 + 顺手修复真实结构错误”的组合，而不扩成正文语义刷新或大规模 code fence language 治理。
• 当 focused validator 暴露的是触达页上的真实错误（如坏链、未闭合代码块）时，同批次直接收口；仅把纯 warning 留给下一轮专门治理。
• 本轮结束时，docs/zh-CN 已没有“完全缺 frontmatter”的页面；下一批最稳定的切片是 docs/zh-CN/index.md 与 docs/zh-CN/tutorials/basic/01-07.md 这 8 个“已有 frontmatter 但缺 title / description”的页面。
• 当前已提交分支 diff 仍为 39 个文件；将本轮工作连同 tracking / trace 提交后，预计累计 branch diff 约为 63 个文件，仍低于 $gframework-batch-boot 75 的停止阈值。

当前验证（RP-025）

• frontmatter 缺口巡检：
  • for f in $(find docs/zh-CN -type f -name '*.md' | sort); do if ! head -n 5 "$f" | grep -q '^---$'; then echo "$f"; fi; done
  • 结果：本轮前命中 22 个页面，当前已全部补齐。
• focused validator：
  • 逐个校验本轮触达的 22 个页面
  • 结果：通过；只剩 best-practices/architecture-patterns.md、best-practices/index.md、contributing.md、 troubleshooting.md 与 tutorials/index.md 的既有代码块语言 warning。
• 站点构建：
  • bun run build（工作目录：docs/）
  • 结果：通过；仅保留既有大 chunk warning。
• 后续候选扫描：
  • python3 - <<'PY' ...（扫描已有 frontmatter 但缺 title / description 的页面）
  • 结果：命中 docs/zh-CN/index.md 与 docs/zh-CN/tutorials/basic/01-07.md 共 8 个页面，可作为下一批 metadata 修复入口。

下一步

1. 继续执行 $gframework-batch-boot 75 时，优先补齐 docs/zh-CN/index.md 与 tutorials/basic/01-07.md 的 title / description 缺口。
2. 若仍有余量，再按目录收口 best-practices、contributing、troubleshooting、tutorials/index.md 的代码块语言 warning，而不是跨全站混做。

当前恢复点：RP-024

• 根据用户反馈，将本轮目标重定义为“清理公开文档中的治理盘点式内容，并把同类约束补进仓库规范与 doc-refresh skill”。
• 用户随后补充明确使用 $gframework-batch-boot 75，因此继续沿用 origin/main 作为固定基线，并把 75 changed files 作为主停止条件。
• 本轮执行的修复：
  • 在 AGENTS.md、.agents/skills/_shared/DOCUMENTATION_STANDARDS.md 与 .agents/skills/gframework-doc-refresh/SKILL.md 中新增公开文档边界规则，禁止把 inventory、覆盖基线、 恢复点、review backlog 和治理批次写入 README.md 与 docs/**
  • 将 docs/zh-CN/core/index.md、core/cqrs.md、game/index.md、 abstractions/core-abstractions.md、abstractions/game-abstractions.md、ecs/index.md、 ecs/arch.md、abstractions/ecs-arch-abstractions.md 的 XML 覆盖 / inventory 段落改写成读者导向的源码阅读入口
  • 继续收口 api-reference/index.md、contributor/development-environment.md 与 source-generators/*.md 中的内部术语，例如 landing page、验证基线、目标类型基线
  • 为 docs/zh-CN/contributor/development-environment.md 补齐 frontmatter，使其满足当前文档规范

当前决策（RP-024）

• 公开文档只承载采用路径、阅读入口、模块边界和可验证示例；治理盘点、覆盖状态和恢复点一律留在 ai-plan/**。
• 当 XML 治理结果需要体现在公开文档里时，只输出“优先看哪些类型 / 命名空间 / 契约以及为什么”，不输出计数、日期或状态表。
• $gframework-batch-boot 75 的基线采用 origin/main（2de57f5，2026-04-23T23:03:40+08:00）。
• 由于当前 HEAD 仍与 origin/main 对齐，分支级 diff 暂时仍为 0；提交前工作树待提交范围为 16 个文件、 224 changed lines，因此本轮仍远低于 75 文件阈值。
• 在完成“公开文档边界”收口后，继续沿同一阈值推进一个新的低风险批次：为 docs/zh-CN/core/*.md 历史页面补齐 frontmatter。
• 当 validator 因本轮触达页面暴露真实坏链时，直接在同批次内修复；当只剩历史 warning（如缺少代码块语言标记）时，本轮停止扩张。

当前验证（RP-024）

• 同类治理内容巡检：
  • rg -n 'XML Inventory|XML 覆盖基线|XML 状态|基线状态|盘点|治理优先级|审计入口|覆盖基线|恢复点|验证基线|目标类型基线|目标字段基线|类型审计|契约审计|源码 / API' docs/zh-CN README.md -g '*.md'
  • 结果：公开页已无同类命中；剩余 inventory 命中仅来自正常代码示例变量名。
• skill 自检：
  • python3 .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Core
  • python3 .agents/skills/gframework-doc-refresh/scripts/scan_module_evidence.py Game
  • 结果：均通过；代表模块的 README / docs 入口映射仍有效。
• 全量 docs 校验：
  • bash .agents/skills/gframework-doc-refresh/scripts/validate-all.sh docs/zh-CN
  • 结果：失败；暴露 53 个仓库既有历史问题（缺少 frontmatter、坏链、未标语言代码块），不属于本轮改动。
• focused validator：
  • 逐个校验本轮触达的 13 个公开文档页面
  • 结果：全部通过。
• 站点构建：
  • bun run build（工作目录：docs/）
  • 结果：通过；仅保留既有大 chunk warning。
• core frontmatter 波次：
  • 已补齐 docs/zh-CN/core/*.md 中 21 个历史页面的 frontmatter。
  • 过程中修复 docs/zh-CN/core/ioc.md 的 ReaderWriterLockSlim 坏链，以及 docs/zh-CN/core/state-management.md 的 4 处缺少 .md 后缀的站内链接。
  • python3 - <<'PY' ... 检查结果为 ALL_HAVE_FRONTMATTER，说明 docs/zh-CN/core/ 目录当前已无 frontmatter 缺口。
  • focused validator 对这 21 个页面全部通过；剩余输出仅为既有代码块语言 warning。
  • bun run build 在修复后再次通过。
• 当前阈值状态：
  • git diff --name-only origin/main...HEAD | wc -l => 18
  • git diff --name-only | wc -l => 21
  • git diff --numstat 汇总 => 126 changed lines
  • 结论：当前已提交分支 diff 仍为 18 个文件，待提交新批次再增加 21 个文件；即使提交后也仍低于 75 文件阈值。

下一步

1. 继续执行 $gframework-batch-boot 75 时，优先按目录做历史 frontmatter / code fence language / 坏链修复，而不是把不同风格的文档语义刷新混成一批。
2. 当前批次在 core 目录已经不再是“同样机械”的模式，后续若继续应转向其他目录或专门做代码块语言标记治理。

2026-04-23

当前恢复点：RP-023

• 按当前使用反馈继续执行 documentation-full-coverage-governance 下的 skill 文档治理。
• 本轮目标定义为“继续沿用上一批的 GitHub 外链策略，收口专题页里的裸路径 README 入口”。
• 本轮执行的修复：
  • 将 docs/zh-CN/core/cqrs.md 与 ecs/arch.md 的仓库 README 入口改为 GitHub main blob 外链
  • 将 docs/zh-CN/abstractions/ecs-arch-abstractions.md、game/scene.md、game/ui.md 的回跳 README 入口改为可点击链接
  • 将 docs/zh-CN/source-generators/priority-generator.md、context-aware-generator.md、 bind-node-signal-generator.md、godot-project-generator.md、get-node-generator.md、 auto-register-exported-collections-generator.md 的推荐阅读 README 入口改为可点击链接
  • 同步更新 active tracking / trace，记录第二批导航治理与新的恢复点

当前决策（RP-023）

• 继续使用 origin/main 作为 $gframework-batch-boot 75 的固定基线，并以“分支累计 diff 文件数”作为主状态指标。
• 对文档治理类批次，优先选择“导航可达性 / 渲染一致性”这类不改变产品语义的低风险切片。
• 在 docs 页面里出现仓库内 README 路径时，优先使用可点击的相对链接，而不是裸路径代码片段。
• 当 docs 页需要跳转到 docs/ 外部的 README 时，使用 GitHub main 分支 blob 外链，而不是跨出 docs/ 根目录的相对路径。
• 第二批继续沿用同一外链策略，避免在同一 docs surface 中混用“裸路径 / 相对死链 / GitHub 外链”三套入口风格。

当前验证（RP-023）

• 导航热点巡检：
  • rg -n 'GFramework\.[^]+/README\\.md|docs/zh-CN/[^]+\.md|仓库根 README\.md' docs/zh-CN -g '*.md'
  • 结果：命中 landing / API 导航页中的裸路径仓库入口，已按本轮批次收口 7 个页面。
• 第二批专题页巡检：
  • rg -n 'GFramework\.[^]+/README\\.md|仓库根 README\\.md' docs/zh-CN -g '*.md'`
  • 结果：命中 core/cqrs.md、ecs/arch.md、abstractions/ecs-arch-abstractions.md、game/scene.md、 game/ui.md 与 6 个 source-generators/*.md 专题页，均已修复。
• 构建校验：
  • bun run build（工作目录：docs/）
  • 结果：通过；将仓库 README 跳转改为 GitHub main blob 外链后，不再触发 VitePress dead link；仅保留既有大 chunk warning。
• 当前阈值状态：
  • git diff --name-only origin/main...HEAD | wc -l => 24
  • git diff --numstat origin/main...HEAD 汇总 => 264 changed lines
  • 结论：尚未接近 75 文件阈值，但剩余命中主要是正文语义性提及，当前批次在低风险模板化导航治理上可先收口。

归档摘要（RP-022）

• 为 .agents/skills/gframework-batch-boot/SKILL.md 与 .agents/skills/README.md 补齐数字速记 stop condition 语义。
• 明确 $gframework-batch-boot 75 / 75 2000 默认绑定 origin/main 累计 diff 口径。
• 完成第一批 landing / API 导航页 README 外链治理，并通过 docs/ 站点构建。

归档指针

• ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-validation-history-through-rp-007.md
• ai-plan/public/documentation-full-coverage-governance/archive/todos/documentation-full-coverage-governance-status-history-through-rp-016.md
• ai-plan/public/documentation-full-coverage-governance/archive/traces/documentation-full-coverage-governance-trace-history-through-rp-016.md

下一步

1. 提交并推送本地修正后，再次抓取 PR #272，确认 Greptile open thread 是否已在新 head commit 上消失。
2. 若继续执行文档治理批处理，优先排查剩余的非导航型裸路径引用、标题锚点与站内链接热点，而不是扩成跨模块大波次。