Refactor code structure for improved readability and maintainability

.zcode/skills/iter-plan/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: iter-plan
+description: g-plan2（Dungeon Sweeper）五段流水线第四段的迭代编排入口。当用户要求编排迭代、把卡片编入迭代、凑一个迭代、开新一轮迭代、做迭代规划时使用。流程：扫待办清单「已写卡」条目呈编排候选清单→用户点名卡与迭代号→开工前预检（拟编卡集只读事实面实核八类，P1 红项停编排退回写卡段）→编排五查（卡片存在/设计闭合凭据齐/估时与冻结线/复核记录在位/写完 roadmap 行跑流水线闸确认绿）→写 roadmap 迭代总表一行六列→待办清单状态推进「已编迭代 N」→呈报编排结果。本技能不动卡片内容、不写实现报告，发现卡片问题呈报退回写卡段。仓库在 D:/code/g-plan2。
+---
+
+# iter-plan——迭代编排段入口（g-plan2 五段流水线）
+
+你在五段流水线（登记 → 文档设计／美术设计 → 写卡 → 迭代编排 → 实现，流程纪律见 `design/engineering/process-conventions.md` §2）的第四段做编排：把用户点名的已写卡需求卡片编进 roadmap 迭代总表一行。格式权威=`design/engineering/doc-conventions.md` §12.2（roadmap 迭代行六列），动笔前先读它。本技能**不动卡片内容、不写实现报告**——发现卡片有问题，呈报退回写卡段（req-card），禁代修。
+
+## 批性质与共同纪律（先读）
+
+- **仓库路径**：项目在 `D:/code/g-plan2`，本文路径相对它。
+- **本技能属工程/文档改动批（直改类）**：可写 `design/` 目录与 `roadmap.md`（本批产出=roadmap 迭代行＋待办清单状态）；**禁跑 `tools/run_all_gates.sh` 全套（不带参数档）与任何游戏测试**；收尾＝手动跑 `--docs`（文档域闸），全绿后按车道合回，合回落地 post-merge 钩子推送触发远端 CI 验证。
+- **车道铁律**：本技能写面（roadmap 行＋待办清单状态）全是 tracked 文件——一切改动走独立 worktree（建区粒度＝回合，会话单区等细则见 `design/engineering/process-conventions.md` §1），收口＝冻结→件核→并 master→主区 `git merge --no-ff`→删区；`.zcode/` 与 `.qoder/` 技能文件不入 git，主区直改。
+- **特批两段式**：只有用户明示才能跳过本技能流程中的某步（典型=带未裁凭据硬编入）。对象（待办清单条目/roadmap 格）已有内容 → 直接写入标记 `〔用户特批 YYYY-MM-DD 跳过××〕`；对象没有任何内容 → 必须回呈实况、经用户再次确认后才写标记。标记必须带日期，无日期=非法（doc-conventions §12.4）。
+- **禁自援特权**：执行中你自己觉得某步该跳（如觉得某卡凭据「显然没问题」），只能呈报后停，**禁自己援引特批**。
+- **闸过渡期口径**：现行待办清单与 roadmap 还是旧格式，`python tools/pipeline_gate.py` 对它们整体红属预期。**红项若全部来自旧格式存量、与本次操作对象无关，注明即可；本次操作对象自身的格式必须合规**（本次写入的迭代行与改写状态的条目，必须按 §12 新格式写）。
+- 本技能只固化本段特有条款；车道铁律、会话落记等仓库级纪律按 `design/engineering/process-conventions.md` 现行文本执行。
+
+## 流程
+
+### 第 1 步：扫候选并呈报
+
+扫 `待办清单.md` 中状态为「已写卡」的条目，逐条打开其状态里登记的卡片文件读取估时，呈报**编排候选清单**，一行一条：
+
+- 条目名 ／ 卡片路径 ／ 估时 ／ 设计闭合凭据（文档线/美术线各报各的；无设计线段条目报实况里的证据指认）。
+
+旧格式条目状态词不属新状态机（如「待编入」「待排期」）时，先向用户确认其真实状态与卡片路径，按 doc-conventions §12.1 补齐格式（「已写卡」必须在状态里带 `reports/` 卡片路径）再纳入候选——禁凭旧词自行推断状态。
+
+候选为零时如实呈报「无可编卡」，结束本轮，禁硬凑。
+
+### 第 2 步：用户点名与迭代号
+
+1. 用户点名哪些卡进哪个迭代（点名内容=卡＋迭代号）。**点名的卡不在第 1 步候选清单（条目状态非「已写卡」）→ 呈报该条不可编入及原因（还停在哪一段），禁编入**；用户坚持「凭据差不多齐了直接编」也只能呈报后停（禁自援特权）。
+2. **迭代号=roadmap 迭代总表现行最大号+1**（旧格式 roadmap 无总表，从迭代进度等现行记事取最大号）；编入已有未完成迭代用其现号，**新开迭代行经用户确认**后才立。
+3. 需求卡片列格内顺序=执行顺序：用户点名时一并给定就照抄；用户未给序 → 呈建议序（按卡片依赖与估时）请确认后再写。
+4. 旧格式 roadmap 没有六列迭代总表区时，呈报用户「总表区尚不存在，本次按 §12.2 新立表区再写行」，经确认后立表（这属本次操作对象格式合规动作）。
+
+### 第 3 步：开工前预检（2026-11-07 用户立）
+
+收令点名卡集后、编排五查与落表前，对拟编卡集做一轮**只读事实面预检**。目标＝尽量减少实现期停工，**不是杜绝**：预检之后其他批次合回、文档再被改动等环境漂移，以及卡片被并行修改，仍可能在实现期停工——那部分由实现段异常分级（iter 技能 L3 停机呈报）与 iter T0 开工日 file:line 窄复核兜底。
+
+- **对象**：用户点名的卡集；补编进未完成迭代的场景，交集类检查对象还要加上该迭代已编入的卡。
+- **形态**：只读实核，不建区、不落笔、不改任何文件。执行方式＝未参与写卡的只读子代理并行分片实核＋主会话汇总裁决；每片按 file:line 清单逐条回「一致／漂移／缺＋实际行号引用」。
+- **发现是中间产物（吸收即死）**：P1 项退回写卡段修订，处置随卡「复核记录」节留痕；预检清单文件即删、永不提交。
+
+八类检查逐类过，发现按 P1/P2/P3 分级：
+
+| # | 检查类 | 查法 |
+|---|---|---|
+| 1 | 卡内一致性互证 | 🔴契约 vs 任务卡 vs 验证闸对照表 vs 落位预检互相印证——汇总级抽查即可，逐条细查归写卡段复核（req-card grilling 门） |
+| 2 | 代码现状锚实核 | 卡片「现状事实」每条 file:line 打开实读；落位预检的新名 grep 全仓应零命中；「计划新增」件核不存在、「复用既有」件核存在 |
+| 3 | 判据出处行锚实核 | 对照表每行锚所指文档行打开实读，核句子在位**且内容与该行判据匹配**——机检 C5 只查存在性，查不出内容错位；写卡后文档被其他批改动会使锚漂移（2026-11-07 退役卡 ux 四锚漂移实证） |
+| 4 | 验收协议可执行性 | 对拍／等价／重放类判据的「改前基线＋改后载体」两腿齐备：基线怎么来（采集步骤在卡内）、载体在盘可跑（工具在 tools/、锚在 sim-data/、golden 基线在 game/tests/golden/） |
+| 5 | 跨卡触碰面交集与卡序语义依赖 | 点名卡集两两过文件交集；同文件改动的语义序（前卡删除面 vs 后卡引用面）；卡序与卡片内取用/产出声明一致 |
+| 6 | 跨批次断言钉死面 | 在飞或刚合回批次新增的断言（词表在册、表值钉、行为断言）是否钉住本批要改的退役面 |
+| 7 | 在盘件核对 | 卡片依赖的盘上件在位：MC 现行锚、分析工具、golden 基线、历史日志等 |
+| 8 | 上游文档版本时效 | 卡引版本号 vs 文件头现行版本；设计闭合后文档是否又被其他批改动 |
+
+分级与去向：
+
+- **P1（不改卡必停工）**——实现与代码事实错位、验收协议缺腿、跨卡对撞、判据锚失位指向错句：停编排，逐条呈报退回写卡段修订，禁编入；修订合回后用户重新收令再编排。
+- **P2（随卡修订顺带）**——措辞失实、引用失实、登记面缺口：呈报，随同批修订顺带处置或由用户裁去向。
+- **P3（记录留痕）**——行号小漂、注释滞后类：呈报留痕，开工自行复核可兜的，随卡修顺手改。
+
+零 P1（P2/P3 已处置或用户认账）→ 进第 4 步编排五查。
+
+### 第 4 步：编排五查（逐卡核，任何一查不过即停）
+
+1. **卡片文件存在**：状态里登记的路径在盘上真有该文件。缺 → 呈报退回写卡段。
+2. **设计闭合凭据齐**：文档线段在场则报文档路径+版本号；美术线段在场则报样张过审＋art-bible 条款版本；无设计线段条目（状态整行无设计线段）报实况里证据指认在。凭据缺或「已闭合」不带凭据 → 呈报退回对应设计段，禁代补。
+3. **估时与冻结线**：所选卡估时按区间**中值**求和（单位工作日、写精确值不取整）。**卡片任何工作量均可编入**（2026-10-25 用户立：工作量限制属迭代层、非卡片层——不足 5 天不再拒编）；编入后总量 **低于 5 个工作日**＝迭代行状态写「冻结待凑批」（不可开工；凑批 ≥5 后由本段改「待开工」，可呈报待编池候选等用户裁）；**5–10 个工作日**为常规区间；**超过 10 个工作日**须经用户确认——确认前呈报整批/拆批两案**等用户裁，禁自行拆分或塞入**，确认后在迭代行写带日期的特批标记（roadmap 格，须带日期；对还没有内容的行，先回呈实况、经用户再次确认后才写标记）；**超过 20 个工作日**禁止编（硬上限，用户确认也不放行，必须拆批）。
+4. **复核记录在位（2026-11-05 用户立规；2026-11-06 用户裁凭据换代——复核凭据＝「复核记录」节自身，不另查报告文件）**：逐卡核卡内有「复核记录」节。缺节、或节内任一条发现没有去向标记 → 呈报退回写卡段，禁编入迭代。边界：复核本身是写卡段的义务，本查只核「做没做、记录在不在」——禁本段替卡补记录、禁本段自跑复核、禁把缺记录的卡当旧卡放行。生效＝卡片文件名日期 ≥2026-11-06（与 `tools/pipeline_gate.py` 该条卡片判据同口径），更早的卡属历史留档不回头改。
+5. **流水线闸绿**：roadmap 行写完后跑 `python tools/pipeline_gate.py` 确认绿。过渡期存量红注明即可，**本次操作对象（新写迭代行＋被改状态条目）自身零红**，有红改到绿。
+
+### 第 5 步：写 roadmap 迭代总表一行
+
+按 doc-conventions §12.2 六列，一行写齐：
+
+```
+| 迭代代号 | 状态 | 需求卡片 | 编入时间 | 预计周期 | 实现报告 |
+```
+
+- **迭代代号**：写「迭代 N」（N=第 2 步定的号）。
+- **状态**：待开工。
+- **需求卡片**：只写文件路径；一格内一行一卡，格内排列顺序=执行顺序。
+- **编入时间**：当天（YYYY-MM-DD）。
+- **预计周期**：写所选卡估时中值之和的精确值（不取整），形态「≈N 个工作日」（1 周＝5 个工作日）；超过 10 个工作日的随带日期特批标记。
+- **实现报告**：「—」（未完成）。
+- **行内禁一切事项说明**——卡序叙述、门依赖、读数、裁点记录一概不入行；卡间依赖写在卡片自身。
+
+### 第 6 步：待办清单状态推进
+
+状态行按**状态段累积制**书写（doc-conventions §12.1）：每推进一段就把新段接在状态行末尾，段与段用＋号连接，书写顺序=推进顺序，**跨线的段一律保留、禁删（同一设计线只留最新一段）**——闭合凭据要留在行内，供编排五查与开工核验比对。本步对每条所选条目：**在既有状态行末尾追加「＋已编迭代 N」**，已写卡段（含括号内卡片路径）原样保留——「已编迭代↔已写卡段↔迭代行卡片列」交叉核拿它比对，删了就断链。累积形态例：
+
+`文档设计已闭合（design/gdd/systems/xxx.md v1.2）＋已写卡（reports/需求卡片-xxx.md）＋已编迭代 31`
+
+若某卡经特批硬编入，标记写在该条目状态处。
+
+改完**复跑一次** `python tools/pipeline_gate.py`——交叉核要 roadmap 与待办清单两文件都改完才核得到，以这次结果为呈报口径。
+
+### 第 7 步：呈报编排结果
+
+呈报四件：迭代号 ／ 卡片清单（路径+顺序） ／ 总估时 ／ 流水线闸结果（绿/存量红注明）。呈报后停——**编入不等于开工**，实现段由用户以 `/iter <N>` 另行发令（段间不自动流转）。
+
+## 边界
+
+- 本技能不动卡片内容：卡片有错、缺验收清单、待裁点未清 → 呈报退回写卡段，禁代修。
+- 本技能不写实现报告：实现报告是实现批的产出物。
+- 编排五查＋开工前预检是本段把关义务，查过即止——禁顺手替实现段做开工检查（那是 iter 技能 T0 的活，T0 开工日 file:line 窄复核兜预检后的环境漂移）。
+
+## 纪律
+
+- 平实简体中文，禁自造黑话；流水线词汇（登记/文档设计/美术设计/改动面/特批标记/流水线闸/需求性工程条目/待执行/已写卡/已编迭代）按 doc-conventions §12 用法一致使用。
+- 迭代代号、状态词、列名一律照 §12.2 白名单形态写，禁变体（「迭代 N+」「已编入」等旧口径词退役）。