Refactor code structure for improved readability and maintainability

.zcode/skills/batch-closure/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: batch-closure
+description: g-plan2（Dungeon Sweeper）批后收尾与中间文档退役入口。当用户说「迭代 N 收尾／批后收尾／落完反哺点收个尾」「清理中间文档／清理暂存地」「把某份报告退役」时使用。做两类事：①iter 批后收尾——反哺点落文凭据核对（落文本身委托 doc-design，本技能禁代写）、reports/ 产出物（实现报告／反哺点清单／验收审计报告）退役判据核对与删除、待办清单条目整条删除、roadmap 迭代行与顶部「当前位」三行换代；②中间文档退役——中间文档唯一暂存地 `reports/`（需求卡片／迭代产出物／提案／审计／需求澄清过程稿）按「吸收即死」判据核对后删除（需求卡片死期=所属迭代实现批合回 master）。规则权威=doc-conventions §11＋concept-conventions §2，本技能只做执行编排、不复写规则；与 doc-consistency-check 分工=那边定期体检只读只报、这边被点名后执行清理。工程/文档改动批（直改类）：可写 design/ 与 roadmap.md，收尾跑 --docs 文档域闸。仓库在 D:/code/g-plan2。
+---
+
+# batch-closure——批后收尾与中间文档退役（g-plan2）
+
+你做的是批次结束后的清库工作：把已完成批次留下的中间文档，按「吸收即死」（规则权威=`design/engineering/doc-conventions.md` §11，删除手法=`design/engineering/concept-conventions.md` 第 2 节删除概念 SOP）退役掉，并随手把账面（roadmap、待办清单）换到与现实一致。**本技能只做执行编排，禁在本文件复写或改判规则**——判据与本文件冲突时以 §11/§12 现行文本为准，并停工呈报。
+
+## 职责边界（先读）
+
+- **反哺落文不归本技能**：把反哺点写进 GDD/art-bible 走 doc-design 技能（其「反哺点写入模式」触发）。本技能只核对落文结果（待办清单反哺点专条状态=已写入＋落点+版本号），核对不过就把落文委托给 doc-design（唯一出口，落文完成后接着收尾），**禁代写落文**。
+- **只报不删的体检不归本技能**：doc-consistency-check 定期体检只读、只呈报问题；本技能是执行臂——用户点名（含体检报出后点名）才动手删。
+- **触发词分界**：「落反哺点／处理反哺点清单／反哺点裁决写入」=doc-design；「收尾／清理中间文档／清理暂存地／退役××文档」=本技能。
+
+## 批性质与共同纪律
+
+- **仓库路径**：项目在 `D:/code/g-plan2`，本文路径相对它。
+- **本技能属工程/文档改动批（直改类）**：可写 `design/` 目录与 `roadmap.md`（账面换代正是本批产出）；禁跑 `tools/run_all_gates.sh` 全量档（不带参数）与任何游戏测试、MC 跑批；收尾＝手动跑 `--docs`（文档域覆盖 `game/` 内 `.md`、design/、根规则文件、reports/、tools/、.zcode/ 等一切非代码面改动），全绿后按车道合回，合回落地 post-merge 钩子推送触发远端 CI 验证。
+- **车道铁律**：reports/ 产出物与账面换代（roadmap/待办清单）都是 tracked 文件——一切改动走独立 worktree（建区粒度＝回合，会话单区等细则见 `design/engineering/process-conventions.md` §1），收口＝冻结→件核→并 master→主区 `git merge --no-ff`→删区；迭代批自身的 worktree 收口动作（merge＋remove）照旧；`.zcode/` 与 `.qoder/` 技能文件不入 git，主区直改。
+- **删除三步强制**：先 grep 引用面 → 改写指路句（改法=结论内联或换 git 提交号）→ 再删文件；收尾死链检查必须绿（`tools/doc_link_audit.py`，随 --docs 跑）。
+- **判据不过禁删**：任一文件的退役判据不过，逐份呈报等用户裁，禁「顺手清掉」；用户明示强行退役才照办，并在提交信息记 `〔用户特批 YYYY-MM-DD 退役××〕`（标记须带日期，doc-conventions §12.4）。本技能无特权，禁自答放行。
+- 白话写作（doc-conventions §2）与流水线词汇（§12）全程生效。
+
+## 主流程 A：iter 批后收尾
+
+触发：用户说「迭代 N 收尾／批后收尾／落完反哺点了收个尾」。
+
+### 第 1 步：盘点该迭代的在飞面
+
+1. 读 `roadmap.md` 迭代 N 行（状态列应已是或应改为「已完成」）与 `reports/` 下该迭代全部文件（实现报告／反哺点清单／验收审计报告，文件名形如 `iter<N>-*-<日期>.md`）。
+2. 读待办清单：该迭代各条目（状态应走到「已编迭代 N」）、本迭代产出的反哺点专条。
+3. **前置核对反哺点是否已落文**：反哺点清单还在且待办清单对应专条未到「已写入（落点+版本）」→ 直接转 doc-design 反哺模式把落文办完，再接着收尾；用户明示本批暂不落文的，反哺点清单保留、只清其余件，呈报里写明这个例外。
+
+### 第 2 步：逐份过退役判据
+
+| 文件 | 退役判据 | 不过怎么办 |
+|---|---|---|
+| `iter<N>-反哺点-*.md` | 已随落文退役（doc-design 第 5 步），或全部条目已落文（待办清单专条=已写入＋落点+版本号） | 第 1 步已拦，委托 doc-design |
+| `iter<N>-实现报告-*.md` | 遗留读数义务逐条已迁（体验验证清单或待办清单在册）；实机目检项已登记体验验证清单 | 未决先迁再死：先迁待办清单/体验验证清单再退役 |
+| `iter<N>-验收审计-*.md` | 审计结论已并入实现报告、无未决项 | 未决项先迁再死：先迁待办清单/实现报告再退役 |
+
+更旧迭代（M<N）在 `reports/` 的残留件，同表过判据后随本批一并清——「证据只留最新」（§11）：新证据落位后旧份同批退役。
+
+### 第 3 步：引用面改写
+
+对每份待删文件：grep 文件名于 `design/`＋`roadmap.md`＋`AGENTS.md`，把指路句改写为结论内联或 git 提交号。roadmap 迭代 N 行实现报告列同步改「已退役（git 历史可考）」（doc-conventions §12.2 保留字）。
+
+### 第 4 步：删除与账面换代
+
+1. 删除判据全过的文件。
+2. 待办清单账面：该迭代条目「完成即整条删除」；已写入的反哺点专条整条删除（两者均 §12.1 状态机出口）。
+3. roadmap 账面：迭代 N 行状态列改「已完成（YYYY-MM-DD）」；顶部「当前位」三行（阶段／迭代位／下一步）换代——只回答「现在该做什么」，禁扩写成状态快照（doc-conventions §10）。
+
+### 第 5 步：收尾闸
+
+`python tools/run_all_gates.sh --docs` 全绿 → 按车道合回 master（独立 worktree→主区 `git merge --no-ff`→删区）。
+
+## 主流程 B：中间文档退役（单份或批量）
+
+触发：用户点名某份中间文档要退役，或说「清理暂存地」。
+
+1. **候选呈报**：点名=直接核该份；「清理暂存地」=扫 `reports/`（中间文档唯一暂存地：需求卡片、迭代产出物、提案／审计／需求澄清／评估过程稿；入内文件默认到期即死，需求卡片死期=所属迭代实现批合回 master），按「结论已吸收？未决已迁？」初筛，呈候选清单等用户点名后才动手。
+   - **`design/` 下禁止过程件目录**（`design/research/` 已于 2026-10-21 退役，熵增闸退役路径清单收它，目录再现即判红）：扫到落在 `design/` 里的提案／审计／调研／需求澄清稿即属违规件，呈报迁 `reports/`；文件自称「常驻／已追认／不受吸收即死约束」一律无效，确实要长期留用的退役内容只走 `design/content-archive/` 转正一条路。
+   - **根目录 `playnote.md` 不入候选清单**：它是用户本人试玩随手记，只由用户增删，不属任何文档族、不受吸收即死管辖。
+2. **判据核对（逐份）**：结论已被权威文档吸收（GDD 对应节/art-bible/架构文档〔仅约束面且须用户落文——2026-11-07 用户裁架构文档写权限＝用户专属〕/术语表 grep 得到）；未决内容已迁待办清单或 roadmap 卡；证据类另核「证据只留最新」。既没被吸收又不肯迁出的，只有「转正迁 `design/content-archive/`」与「呈用户裁决」两条出口，禁原地自封常驻。
+   - **需求卡片特殊**：`reports/` 下的需求卡片须另核 roadmap 行——行内已填「已退役（git 历史可考）」或卡片已被新版替代才可退役，迭代仍引用的卡片禁删。
+3. 未吸收 → 呈报建议落点（落文走 doc-design 或用户直裁），禁先删；判据过 → 引用面改写 → 删 → 死链检查绿。
+4. 收尾闸 `--docs` 全绿 → 按车道合回 master（独立 worktree→主区 `git merge --no-ff`→删区）。
+
+## 纪律
+
+- 平实简体中文，禁自造黑话；吸收即死/退役/未决先迁再死/证据只留最新等词按 doc-conventions §11 用法一致使用。
+- 删除是不可逆动作：同批删除清单在呈报里逐份列名，用户看得见每一份才动手。
+- 本技能不写需求卡片、不做设计讨论、不碰代码——上游各归其段：落文=doc-design，体检=doc-consistency-check。