Refactor code structure for improved readability and maintainability

.qoder/skills/doc-consistency-check/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: doc-consistency-check
+description: g-plan2（Dungeon Sweeper）仓库的文档一致性定期检查固定流程：四个脚本自动检查（GDD 格式规则/死链/退役术语/目录结构）加六项人工核对（数值三处同步、根索引与文档树同步、待办清单现状、当前位与现实一致、会话状态文件复发检查、待办清单闭合凭据的版本号落后）。只读检查、只呈报问题不修改、不运行任何游戏测试。当用户要求做文档一致性检查、文档体检，或定时任务触发文档检查时使用。
+---
+
+# 文档一致性检查（g-plan2 定期检查流程）
+
+## 这是什么、为什么需要
+
+g-plan2 的每个开发批次出口都带文档脚本检查，但脚本抓不住"该改的正文没改"这类失同步。真实先例：敌人系统.md 的护甲列写的是旧口径，与数值表不一致，拖到 2026-10-05 才在批次里补掉；更早的 2026-09-17 数值压缩批只改了数据表，GDD 正文表格、registry、待办清单三处都没同步（该登记处于 2026-10-19 注销）。
+
+本流程把文档一致性检查固化成固定步骤，定期把仓库文档整体对一遍。**只负责找出问题，不负责修复**——修复由用户决定，走正常批次流程（独立 worktree 分支）。
+
+## 硬约束（先读完再动手）
+
+1. **全程只读**：不修改任何文件、不创建任何文件、不提交、不合并、不切分支。
+2. **禁跑游戏测试**：冒烟测试、单元测试、MC 模拟、场景探针一律不跑（本项目"测试执行两入口铁规"）。本流程只允许运行下面列出的四个文档审计脚本，它们只扫文档、不启动游戏。
+3. **检查范围 = 主工作区（master 检出）**：并行开发中 worktree 里的改动还没合并进 master，不作为判读依据。先跑 `git worktree list` 知悉当前在飞的批次，避免把"worktree 已改、master 未合"误报成失同步。
+4. **所有命令从仓库根目录运行**（含 project.godot 的那一层）——审计脚本按相对路径找 design/gdd/，从别的目录运行会静默报"扫描域为空"，看起来像通过其实是没扫到。
+
+## 检查清单
+
+### 第一组：脚本自动检查（四件）
+
+从仓库根目录逐个运行，读输出：
+
+| # | 命令 | 查什么 |
+|---|---|---|
+| 1 | `python tools/gdd_lint.py` | GDD 格式规则（散文段落长度、变更记录节禁设、计数词一致等）；另 `--changelog-only` 档扫全 design/ 树拦版本历史/修订记录类节 |
+| 2 | `python tools/doc_link_audit.py` | markdown 链接与反引号路径引用的死链 |
+| 3 | `python tools/doc_term_audit.py` | 已退役术语在正文的残留。工具把命中分两类：输出里标"疑似现行"的需人工看一遍，"留档类"（带日期/退役信号或在版本历史节里）默认忽略 |
+| 4 | `python tools/repo_structure_audit.py` | 顶层目录白名单、根文件白名单、图像白名单、退役路径四查 |
+
+**判读口径 = 只报新增**：先找最近一份批次出口报告（`reports/` 下按日期最新的 `iter<N>-实现报告`，其"闸绿记录"节记有当次各项存量数），与本次输出对比。与存量持平 = 通过；多出来的命中逐条人工看。找不到近期出口报告时，全部命中逐条人工看。
+
+### 第二组：人工核对（六件）
+
+5. **数值三处同步**：先跑 `git log --oneline --since="7 days ago" -- game/data/tables design/gdd` 找近期的数值变更提交；对每一次 .tres 数值行变更，核对其对应的 GDD 正文表格、`data/tables/` schema 校验域、`待办清单.md` 现状描述这三处是否同步（doc-conventions 第 5 节强制收口条款：三处任一未更新，该变更就不算完成）。7 天内没有数值变更提交，就记录"本项跳过"。
+6. **根索引与文档树同步**：列出 `design/gdd/` 与 `design/gdd/systems/` 各子目录下实际的 .md 文件，对照 `design/gdd/02-系统清单.md` 的导航条目——文档增删必须同步根索引（AGENTS.md Project Layout 规则），新增或删除了文档而索引没跟上就是失同步。
+7. **待办清单现状**：对照 git log 最近合并进 master 的批次提交与 roadmap.md 里的落地标注，检查待办清单.md 里相关条目的状态是否已刷新；条目还写着进行中、但对应批次实际已合并的，报滞后。
+8. **当前位与现实一致**：`roadmap.md` 顶部「当前位」三行所述的阶段与迭代位，对照 `git log --oneline -10` 的近期合入与本文迭代总表末行；「当前位」写出三行以上、或待办清单里条目状态与近期已合并批次矛盾，都报滞后。
+9. **状态文件复发检查**：仓库根出现 `active.md` 或任何同类会话状态文件、任何文档里重新长出「当前状态快照」节，一律报（2026-10-18 用户裁废除，见 doc-conventions 第 10 节）。只报不修。
+10. **闭合凭据的版本号落后**：待办清单条目状态行里的「文档设计已闭合（design/gdd/xxx.md v1.2）」「美术设计已闭合（样张过审、art-bible v3.x）」这类凭据，括号里的版本号记的是**被引文档当时的现行版**。08c 流水线闸只校验凭据在场与形态、不校验它是否仍是现行版，所以要人工比对：先 `grep -oE "（[^）]*v[0-9]+\.[0-9]+[^）]*）" 待办清单.md` 抓出全部带版本凭据（2026-10-18 实测 12 处），再对每个被引文档取现行版——看文首状态行/头注的「现行为 vX.Y」（版本历史表已于 2026-10-19 禁设，文档内不再逐版登记）；凭据里的文档名常是裸名甚至省略 `.md`（如「元进度.md v1.0」「art-bible v3.15」），要按名字在 `design/gdd/`、`design/art/` 树下定位。不等即报「凭据指向旧版」，含义是这条设计闭合判据所依据的文档已被后续批次超越，闭合是否仍成立要重看。只报不修。（前身是 `tools/loop_dashboard.py` 的失效面检测器，它比对的是体验验证清单头部「当前批次来源」行；那一行在后续改版中已不存在，所以本件按现存格式重立到待办清单凭据面上，工具本身 2026-10-18 删除。）
+
+## 产出格式
+
+报告直接写在对话输出里，不落盘成文件。
+
+- **全部通过**：一句话，例如"文档一致性检查完成：脚本检查四件与人工核对四件全部通过，与最近出口报告的基线持平"。
+- **有问题**：逐条列出，每条包含四样——哪份文档哪个位置、与什么不一致、证据（文件:行号）、建议修法（一句话）。按误导程度排序：会误导读者或后续开发的失同步 > 滞后未刷新 > 格式类。
+- **拿不准的**：单独列"存疑"一节，写清为什么拿不准，不下结论、也不当问题报。
+
+## 边界
+
+- 不检查 `reports/` 里中间文档的内容质量——`reports/` 是中间文档唯一暂存地（`design/research/` 已于 2026-10-21 退役），文件寿命到处理完毕为止；验证取证照旧不进 `design/`。
+- 不修改 `design/gdd/术语表.md` 的登记（修订登记是拥有该概念的文档所在批次的职责），只核对它与其他文档是否一致。