gplan-2/.zcode/skills/req-card/SKILL.md

name, description

name

description

req-card

g-plan2（Dungeon Sweeper）仓库写需求卡片的固定流程与结构。当用户要求起草/修订需求卡片、给迭代需求写实施文档、或迭代规划进入写卡阶段时使用。固化需求卡片必备结构——尤其「关联文档同步面」必填节（2026-10-17 文档同步闸 v3：卡片服务的是**代码实现批**，该批禁写 `design/` 与根规则文件，要改文档的点一律列进 `reports/` 反哺点清单，用户在会话中裁决后归文档批落文）、「改动—验收对照表」（2026-10-11 立，2026-10-21 升级：每个需求点与每个行为改动都必须有真实入口断言和判据绑定面；无验收标准的需求点＝卡片不成立，/iter 开工门同规拦截）与「落位与可复用性预检」必填节（2026-10-21 立：新增文件/函数/数据件前先核仓库既有实现，能复用不新增，落点唯一、禁散落 helper、跨层交互显式声明）、「实现规范预算」必填节（2026-10-27 迭代 39 实证立规：新增件接口块/成员面先对 gdstyle 默认阈值做预算——公开方法 ≤20、类变量 ≤15、迁移函数对账基线键，超了写卡段拆件，例外走显式申报＋用户特批，禁把超预算面带进实现段）与「拆分边界纪律」结构类卡必填条款（2026-10-28 用户裁立：拆分边界沿职责轴不沿阈值轴——拆出单元须有职责语句/单一变化原因/集体身份，凑计数袋禁、阈值只作发现信号、拆不出内聚单元停卡呈报走豁免通道，判据权威=code-conventions §1.1）。任务卡 T0..Tn 的步骤写作遵循 superpowers:writing-plans 方法论（2026-10-19 起按本项目适配内联：卡前文件结构图/范围检查/任务右尺寸/步骤粒度/步骤内容四分/接口声明/禁行句式/自审六查）。复核门含判据出处行锚逐行实读（2026-11-07 起，对照表每行锚所指文档行实读核句子在位且内容匹配——机检 C5 只查存在性）与引擎技术面三查（2026-11-04 起，godot-master 窄口径：NEVER/Gotchas/性能预算＋按需领域 reference，权威仍在项目规范）。复核发现按四类去向处置（2026-11-05 立：自判＝查规范或查代码有唯一答案，复核者自己改卡；补写＝卡里漏写，回炉补全；待裁＝多种做法都不违规且代价不同，才交用户；退回上游＝文档线或美术线未闭合、或架构与代码规范本身冲突）；卡片必带「复核记录」节（缺节＝不成立，机检=pipeline_gate），复核先于提交、提交先于合回，顺序没走完禁对用户称完成。

需求卡片写作规范（g-plan2）

需求卡片 = 一个需求单位的实施文档（roadmap 迭代行里的「卡①②③」是需求单位，需求卡片是它的展开）。文件落 reports/需求卡片-<批名>-<日期>.md。

第〇步·设计闭合检查（2026-10-18 五段流水线立规，先于一切写卡动作）

写卡是五段流水线（登记 → 文档设计／美术设计 → 写需求卡片 → 迭代编排 → 实现，流程纪律见 design/engineering/process-conventions.md §2）的第三段，输入=第二段的设计线闭合凭据。动笔前先定位需求来源对应的待办清单条目（待办清单.md；条目格式与状态机权威见 design/engineering/doc-conventions.md §12），按条目状态段与改动面逐项核：

• 设计线条目（状态行含文档线段或美术线段）：放行判据=设计闭合凭据齐——状态已到「待写卡」或更后（已写卡／已编迭代 N，含修订重写场景）；状态尚停在轨闭合态而未标待写卡的（文档设计已闭合（文档路径＋版本号）／美术设计已闭合（样张过审＋art-bible 条款版本）／两条线并列时两段全带闭合凭据），同样算闭合成立、放行，写完直接把状态推进到「已写卡（卡片路径）」。画面类需求（触碰画面呈现规格：新增画面要素／布局／配色／动效）放行另核一项：设计段预览图已人审在案（ux/ 规格文档内嵌预览节随附像素级判据句；义务出处=process-conventions §2 段二行）——预览图缺或未见人审记录＝拒写卡退 doc-design。凭据缺、状态还停在 待文档设计／文档设计中／待美术设计／美术设计中、或两线只闭合了一段 → 拒写卡，呈报退回设计段（文档线退 doc-design，美术线退 asset-ingest，两线并列时退未闭合的那段），禁硬写。
• 需求性工程条目（状态行整行无设计线段、首段直落待写卡，限缺陷修复／重构等改游戏行为的四类）：核对条目实况里有证据指认；状态落「待执行」的直改类条目（工程债／测试基建／工具维护，不动游戏行为）不属写卡范围（bug 证据带 file:line，或工程债条目）。无证据 → 拒写卡呈报，禁凭口头描述开工。
• 直改类条目（禁写卡，2026-10-25 用户裁·改动四类）：条目属工程改动（tools/、闸件、模拟测量工具、纯测试维护——不动游戏行为）、文档设计改动或美术素材改动 → 拒写需求卡片，呈报改走直改通道：登记 →（如需设计讨论）→ 用户发令直改 → 按改动域跑闸 → 完成删条目。判据＝改动会不会被打进游戏、被玩家玩到：会＝需求改动（可写卡）；不会＝直改类。注意：跳过设计线≠当然可写卡——改游戏行为的缺陷修复/重构＝需求改动可写卡；配套维护类禁写卡。
• **反哺点专条（状态取待裁决／已写入）：不属写卡范围，分流呈报（反哺点走 doc-design 的写入通道，见 process-conventions §2 段二）。
• 定位不到对应待办清单条目 → 呈报先补登记（登记是流水线第一段，条目格式由流水线闸 tools/pipeline_gate.py 强制），禁跳过登记直接写卡。
• 条目不是 §12 格式（缺「改动面」属性或标题缺登记元数据）→ 呈报待整改批换代，禁自行猜测所属设计线与改动面硬写（现行待办清单尚未整改时，闸对这些条目整体红属预期）。

特批通道（设计前置的唯一例外，2026-10-18 按 doc-conventions §12.4 固化）：只有用户明示「跳过设计前置」才可走，执行一律两段式——①对象已有内容（设计讨论确有记录）→ 直接在待办清单条目状态写 〔用户特批 YYYY-MM-DD 跳过××〕；②对象没有任何内容 → 必须回呈实况，经用户再次确认后才写标记。标记与状态词并存写：标记只豁免设计段、不替代状态机推进，跳过后状态照状态机记（例：「〔用户特批 2026-10-18 跳过文档设计〕待写卡」）；只写标记不留状态词，流水线闸判「状态行内容为空」红。标记必须带日期，无日期=非法、不构成放行；条目已带合法特批标记的，等同凭据齐放行。禁自援特权：写卡会话自己觉得该跳，只能呈报后停，禁自行写特批标记。

写作前

1. 先读对应待办清单条目、相关 GDD 权威定义节、roadmap 迭代行——需求卡片的事实源是它们。
2. 现状事实必须代码级考证（file:line 实查），禁凭记忆写「现状」。
3. 设计前置检查（2026-10-10 用户立规）：新玩法/新系统/新内容类需求必须有设计定稿前置（GDD/art-bible 待裁点清零）——设计未定稿不写卡，回设计段；缺陷修复/工程债/测试基建/重构类工程需求凭 bug 证据或待办清单在册条目直接写卡，无设计前置要求。（2026-10-18 起本检查由上方「第〇步·设计闭合检查」统一执行：凭据核、证据核与特批通道以第〇步为准。）
4. 参考既有范本：reports/ 下现行在役的需求卡片（批名与日期见 roadmap.md 迭代总表「需求卡片」列）。原三份范本（内容数据驱动扩展批／混编遭遇首批投放批／武器锻造系统设计提案批）已按「吸收即死」退役，git 历史可考。（范本成文早于 2026-10-19 任务卡写作纪律——学其事实密度、契约与范围边界的写法；T 卡步骤粒度按新纪律收紧，禁照抄范本的粗步骤。）
5. 任务卡方法论上游（2026-10-19 立）：任务卡 T0..Tn 的写作遵循 superpowers:writing-plans 技能的任务/步骤纪律。该技能的通用纪律已按本项目实际适配内联于下文「任务卡写作纪律」节与「纪律」节自审七查——内联版即执行依据，写卡不要求另行加载该技能；若写卡时会话在役加载了 writing-plans，可以它的任务结构/步骤粒度/自审三节为上游参照，两者冲突时以本技能与 AGENTS.md 为准。writing-plans 的文档落位（docs/superpowers/plans/）与执行交接节（让用户在两种执行方式里挑）不适用本项目——本项目的计划文档就是需求卡片本身，执行走 /iter 发令。

必备结构（缺节不开工）

1. 目标与完成定义——这批做什么、什么状态算完。
2. 设计事实源（必填，2026-10-18 五段流水线立规）——本卡设计依据的唯一出处声明，三选一填写：① GDD 文档节＋版本号（例：design/gdd/systems/xxx.md v1.2 §核心规则）；② 样张过审＋art-bible 条款版本；③ 跳过设计线的证据指认（需求性工程条目或直改类条目）（bug 证据带 file:line／工程债条目）。所填必须与待办清单条目状态里的闭合凭据（或工程类证据指认）一致——本节是后续迭代编排五查与 /iter 开工核验的比对对象，缺失＝卡片不成立。合格写法两种（2026-10-18 卡片冲突修订批与机检对齐，禁按小节名字面卡死——库内合规卡多用写法乙）：甲＝独立小节「## 设计事实源」；乙＝头部条目「来源：…（唯一事实源：…）」。机检＝tools/pipeline_gate.py 判据 C2：全文含「设计事实源」或「唯一事实源」任一即合格，生效＝文件名日期 ≥2026-10-18，更早的卡属历史留档不回头改。
3. 现状事实——代码级，开工自行复核；每条带 file:line。
4. 设计契约——违反即返工的红线条款，标 🔴（触碰=L3 停机呈报）。
5. 范围边界——做什么不做什么；明示不收件的去向（待办清单登记/后续批）。
6. 关联文档同步面（必填，2026-10-17 改口径：实现批禁写文档）——三列：文档｜关联点（本批实现会改变它的哪条陈述）｜同步义务。同步义务分三层标注：设计权威文档（GDD/art-bible）与机械面文档（roadmap 行/术语表/体验验证清单/README）对代码实现批一律不直改——实现批禁写 design/ 整个目录与根规则文件，把该改哪一节、改成什么、依据是什么逐条列进 reports/iter<N>-反哺点-<日期>.md，由用户在会话中裁决后归文档批落文（不设文档 skill，文档靠会话讨论落地）。实现批唯一可写目录＝reports/（2026-10-18 用户裁：根目录会话状态文件已废除，无任何例外）。写卡时就要把「实现会影响哪些文档的哪些说法」查全；查不出也要写「无关联文档」四字，不许省略本节。机检（2026-10-18 卡片冲突修订批补）＝tools/pipeline_gate.py 判据 C1「文档义务口径」：同步面表内目标格指向 design/（含 ../gdd/ 等相对写法）或根规则文件、而义务格仍写「随批」者红——旧口径措辞「机械面随批」自 2026-10-17 起作废，写卡禁沿用；生效＝文件名日期 ≥2026-10-17。
7. 任务卡 T0..Tn——逐卡估时；末卡必含「产出物落位卡」：轻闸全绿后、合并前，把 reports/ 两份写齐——实现报告（各卡状态＋实机目检总清单＋遗留读数义务＋实现决定记录）、反哺点清单（同步面所列每条都要有落点），方算收口。禁把任何 design/ 文件或根规则文件的编辑写进实现批的任务卡（那是文档批的活）（AGENTS.md 批次工作流 §3.13）。（T 卡内步骤说明的写作纪律见下文「任务卡写作纪律」节，2026-10-19 立。）
8. 验证闸（改动—验收对照表，2026-10-11 立，2026-10-21 升级；2026-10-28 判据口径换代）——每个需求点列明验收测试内容；每个行为改动也要有一行。表列至少七格：需求点｜改动（文件:行/行为）｜验收测试（名称＋落点＋尾缀）｜层级（单元/接口/集成/探针）｜真实入口｜判据绑定面｜能力行（2026-10-29 起：既有：<能力名>／新增：<能力名>；两形态的名称都须在 game/tests/README.md 能力表在场，机检=pipeline_gate）。能力行当场入表（2026-10-29 用户裁，废「滞后一个迭代」）：写卡时同批维护能力清单（game/tests/README.md，四列＝能力｜系统｜真实入口｜代表用例）——本批新增能力当场增行（真实入口取自设计文档已定的入口；代表用例＝本卡定死的计划测试 文件:函数 名）；受影响存量行（入口／用例名变更）同批更新；能力退役删行。实现照单落名：测试函数名以清单为唯一依据，名实不符＝本卡没写清＝停卡退回；实现批禁写 README 的红线不变，批末收尾只核对表上名字与实际落地一致（改名则回表）。落点位置二选一：写在对应 T 卡里，或集中列在验证闸节逐条编号、由 T 卡交叉引用。每个需求点至少一行；每行必须有真实入口和判据绑定面——缺任一项＝该需求点未验收，卡片不成立。判据出处行锚（2026-11-05 起，对文件名日期不早于该日的卡生效）：「需求点」格每行必须带判据出处行锚——该行验收判据所依据的现行文档句子，格式 <文档相对路径>:<行号>（如 design/gdd/ux/camp.md:16）；已退役卡片不算现行文档；规格缺席写不出锚＝停卡退回需求澄清（test-conventions §8.3，机检=pipeline_gate C5）。画面类需求的锚指向 ux/ 文档内嵌预览节的判据句（预览图=设计段已人审的目标画面效果图，也是实现批基线冻结时用户对照的参照——test-conventions §8.2）。基线审核关卡特殊标注（2026-11-08 用户立）：需求点触碰渲染黄金图基线（新增锚面／换代／迁移／容差修订）时，该行验收标准必须显式标注「触发基线审核关卡」——基线逐张呈报用户审核确认后才入库生效，T 卡步骤须含呈报审核点；漏标＝复核门退回补写（test-conventions §8.2 审核关卡）。承接 AGENTS.md 硬红线「新功能必配新测试」：那条只兜「有没有」，本表兜「测得对不对、是不是钉在这个改动上」——写卡期不定稿，实现期就自由发挥。
   • 测试方式两分法（2026-10-11 用户定）：能力验证＝调试接口直改游戏数据（改钥石/槽位/解锁状态等，不走正常资源积累流程，沿用现役 DebugOverlay/DS_DEBUG 门控）；正常流程体验验证＝用户目检，观测项写进 reports/iter<N>-实现报告-<日期>.md 的实机目检总清单（2026-10-17 起：体验验证清单.md 属设计文档，实现批禁写，入册该体验验证清单的条目作为反哺点由文档批落）。每张卡写明哪些点归调试接口验、哪些点归用户目检验。用户目检一律「登记不阻塞」（2026-10-12 用户立规）：登记完成即卡内义务了结，验收时间由用户自行安排，不得作为批末收尾、合并或下一迭代开工的前置条件。
   • 闸口径（2026-10-17 改按域；2026-10-26 判据改按文件性质）：轻闸/重闸按 AGENTS.md 分级周期口径——重闸＝tools/run_all_gates.sh 按本批改动域选档（改动含 game/ 下非 .md 的行为载体 → --code；只有文档件——game/ 内 .md、design/、根规则文件、tools/ 工具脚本 → --docs；两类都有或改闸件本身 → 不带参数全量），所选域全绿才合并。卡内禁写死闸件名单与"全量档"字样（域划分的唯一出处在脚本里）；批末四闸语义改述为「代码域闸全绿（冒烟＋单元＋探针＋渲染/静态）＋改前改后读数对拍」。改完即测铁规照履行：卡内改动落笔即测自己改过的那部分，不请示。
   • 回归措辞模板（2026-10-14 闸机轮次纪律，AGENTS.md 同源）：禁用「每步对拍+全量回归」「每轮全量回归」类措辞——会被执行侧解读成每次修复跑全套；改用模板句：「里程碑步（波/T 段）出口跑一次全套闸；波内修复只做出红最小单元的最窄确认；新增测试/工具先行孤立验证再并入全套」。
   • 判据绑定面口径（2026-10-24／2026-10-28 用户两裁：全项目禁变异类测试、禁撤销类取证——两者都是人为制造红，属伪造证据）：每个行为改动的验收断言从真实入口进入、判据绑被测改动特有的可观测提交面（信号/事件/入参/状态源取值/绘制记录），在当轮真实跑批中执行并通过；判据绑不上（纯防御分支、release 独有位）＝静态判据＋评审注记申报观测面局限，证明做不出＝停卡呈报，禁自造注入破坏或回退 hunk 取证。卡内不得再出现「撤销证明」「变异证明」列或步骤。配判据时按强弱分层配齐：运行期断言（可见性/树序/状态源取值）抓状态类缺陷，golden 逐像素抓内容观感类缺陷，占比/统计类判据只兜「整框空白/整框糊」，是补充不是主力（细则=test-conventions §8.4）。
   • 测试削弱申报（2026-10-21 立）：卡内列出允许改/删的旧断言及理由；实现期未申报的删除断言、放宽阈值、缩小扫描面、换下层直调，由独立验收审计判红。
   • 独立验收审计（2026-10-21 立）：卡内写明审计入口与报告文件（reports/iter<N>-验收审计-<日期>.md）；审计由没参与实现的会话或子代理执行，未过不得合并（细则=test-conventions §8.7＋iter 技能第 5 步）。
9. 异常分级——L1 自救/L2 记录继续/L3 停机写报告等用户；新增件/重构类卡的 L3 必含「机检预算互斥＝上游缺陷停卡退回写卡段」条（2026-10-27 立，与第 13/14 节条款合流）。
10. 代拍板白名单——允许 agent 自行拍板的微决策清单（逐条列，超清单记入实现报告「实现决定记录」节）。
11. 待裁点——全备选案并列（推荐案+淘汰依据），设计权归用户；零待裁点也要写明「零待裁点，开工门=U0」。
12. 落位与可复用性预检（必填，2026-10-21 用户立规）——定义 T 卡前，对本批每一个新增文件、新增函数/方法、新增数据件逐条过三问，答案写成卡内独立小节（节名「落位与可复用性预检」，与第 7 节的文件结构图互指）：

• 复用面：仓库里是否已有做同样事的东西？先 grep 现成实现（同职责的视图/工厂件/服务/工具脚本/测试套件与夹具），能复用就复用、能扩展就扩展；确需新增必须写明「为什么不能复用既有那一个」——写不出理由＝不该新增。
• 唯一面：同一份数据、同一段逻辑、同一个常量是否只落在一处？落点唯一——一个职责一个文件，禁多处定义同名事实，禁为省事把 helper 散落到「就近的文件」里；新增前先 grep 同名与同义标识符，确认盘上没有第二处。
• 分层与交互面：新增件之间、以及与既有系统的交互路径显式声明——谁调谁、经哪个出口、跨层时走哪条契约（Core 零 UI、玩法数值只经 ConfigDB 单点、随机只经 RngService 等既有红线不因新增而绕）。分层按职责切，不为「放得下」把跨层逻辑塞进同一文件。
• 缺本节＝卡片不成立；本节与文件结构图一并作为 grilling 复核门的审点（见「纪律」节自审七查⑥）。机检只在结构层查不到语义，复用判断由写卡人与复核门负责。

13. 禁为机检文本保留无效成员（重构类卡必填条款，2026-10-25 立，与 code-conventions §1.1 同款）——重构类需求卡片必须写明：禁止为迎合机检消息文本（含计数）而保留或新增无效成员/别名；机检键与卡片契约互斥时，实现段一律停卡呈报，不得自造第三条路。
14. 实现规范预算（必填，2026-10-27 迭代 39 实证立规）——定义接口块/文件结构图前，对本批每一个新增文件对照 gdstyle 默认阈值做预算，写成卡内独立小节（节名「实现规范预算」，与接口块及文件结构图互指）。现行默认口径（gdstyle v0.4.0 实测：公开方法 ≤20、类变量 ≤15、单函数分支 ≤8、返回 ≤6；阈值取工具默认、改阈值=基线口径变须随批重生成）：

• 新件三查：①接口块公开方法数 ≤20——超出＝拆件或砍面（砍面＝退设计段裁职责）；②成员变量数 ≤15——超出＝收编进内聚结构或拆件；③迁移函数对账——自存量文件迁入的函数，先查 tools/gdstyle_baseline.txt 源函数键，branches/returns/函数长有超默认登记值的，迁移即拆函数（拆分不改语义，不算迎合机检——与第 13 节区分：那条禁保留无效成员凑数，本条要求真拆）。
• 存量触面一查：本卡触碰的存量文件，T0 读数步骤写明「S13 键较登记值只降不升」的预期与达成手段。
• 指标例外通道：确需超默认的（架构先例如组合根超限），卡片设「指标例外申报」节——键名＋理由＋用户特批落基线；未申报的超预算面进实现段＝停卡退回写卡段（写进本卡异常分级 L3）。
• 缺本节＝卡片不成立；预算节数字与接口块实数的一致性是 grilling 复核门审点（自审七查⑦）。
• 生效＝文件名日期 ≥2026-10-27；此前卡片属历史留档不回头改。

15. 拆分边界纪律（结构类卡必填条款，2026-10-28 用户裁立，判据权威=code-conventions §1.1 拆分判据）——拆分/收敛/重构类需求卡片必须在设计契约区写明红线条款（卡内写条款，判据定义以 code-conventions 为权威、不复制定文）：①每个拆出单元（私有函数族/新件/段件/状态件/参数束）须有可陈述的职责语句与单一变化原因（实现报告逐件一行承载）；②拆出单元须有集体身份——命不出名字、只能说「剩下的成员」的打包＝凑计数袋，禁；③「过阈值」只许作为发现信号，作为拆分或收拢的动机即违规；④按纪律拆不出内聚单元 → 停卡呈报走豁免/还债通道，禁硬拆凑绿（写进本卡异常分级 L3）。先例＝迭代 41 两卡 v1.2（核心数据面契约 7／呈现层契约 9）。生效＝文件名日期 ≥2026-10-28；此前卡片属历史留档不回头改。
16. 验收档申报（必填，2026-11-05 生效）——卡片头部信息区（与设计事实源声明同区）申报一个验收档：高／中／低。判据＝失败代价单维：这条改动做错了，后果随存档或结算传播的（存档写读与迁移、RNG 流、战斗结算公式与乘区、经济入账、数值表结构校验）＝高；后果玩家可见但不损持久状态的（常规玩法逻辑、门控、交互逻辑、呈现数据面）＝中；后果即看即知且无状态残留的（文案、纯呈现样式、布局微调）＝低；一张卡触多档按最高档申报。用户批卡（U0）时确认或改判；档位只调节独立验收审计深度（梯度表＝test-conventions §8.7），闸机与 CI 的档位、域划分、全量强制档一概不变。机检＝tools/pipeline_gate.py 判据 C4：文件名日期 ≥2026-11-05 的卡必含「验收档：高／中／低」申报行；未申报档位的卡（旧卡）按高档全量审计。
17. 复核记录（必填，2026-11-05 用户立规）——本卡经过的对抗复核逐轮登记，五格：轮次｜复核者身份（写明未参与本卡撰写，形态＝只读子代理或独立会话）｜发现（一句话）｜去向（四类之一，定义见「纪律」节复核发现四类分流）｜处置结果（改了卡内哪一节、退给了哪一段、或用户裁决的结论）。缺本节、或任一条发现没有去向标记＝卡片不成立。复核凭据＝本节自身，不另设复核报告文件（2026-11-06 用户裁：复核内容回写本节即全部凭据）。机检＝tools/pipeline_gate.py 卡片复核判据（生效＝文件名日期 ≥2026-11-06；此前成文的卡属历史留档不回头改）。复核分类得对不对属语义判断，机检只查结构在位，语义归复核者与本节申报人。

任务卡写作纪律（2026-10-19 立；任务/步骤规范借自 superpowers:writing-plans，按 g-plan2 实际适配）

读者画像先立住：T 卡的执行者（/iter 施工方）是没见过这份规格、也没见过邻卡的工程师——他按本项目语言写惯代码，只要给足确切接口、确切测试、确切取值，他就能写对；他不可能知道的是写卡人定了什么：动哪些文件、哪些名字与签名、规格里的哪个值、哪条测试证明这张卡成立。把这些写全，其余不代劳。生效＝2026-10-19，此前卡片属历史留档不回头改。

卡前·文件结构图

定义 T 卡前，先把本批新建/修改的文件列全——每个文件一行：路径＋职责。边界清晰、一文件一职责；一起改的文件放在一起，按职责切分不按技术层切分；既有代码库跟随既有模式——库内大文件不擅自拆，但本批要改的文件已臃肿到不可单手握住时，把拆分写进本批计划也合理。结构图定分解，T 卡从它生，禁跳图直接列卡。**每个文件行同时标「行为改动/非行为改动」；行为改动行写对应验收对照表行号，定结构图时就确认每个行为改动有验收落点。**结构图与「落位与可复用性预检」节互指：每个新增件（文件、函数、数据件）在结构图里标「复用既有」或「新增」，标新增的必须能在预检节指到它的「为什么不能复用」理由与落点唯一性核查——两处对不上就是卡片不成立。

范围检查

一批规格覆盖多个相互独立的子系统、设计段又没拆开的，建议拆批（roadmap 迭代行内的卡①②③即此机制）——每批各自产出可独立验收的交付物，禁一张大卡混装多个子系统。

任务右尺寸

一张 T 卡 = 自带一轮测试周期、值得一道独立审查门的最小单位。画界规则：环境搭建、配置、脚手架、文档类步骤折进需要它的交付物那张卡，不单独立卡；只在「审查者可能否决这张而放行隔壁那张」处才切；每张卡以独立可测的交付物收尾。本项目铁律「验收测试随对应 T 卡同轮落地」（/iter 纪律）由此获得尺寸依据——卡大到一轮测不完，就是切小了。

步骤粒度

一步 = 一个动作 + 一个可核查结果；用 - [ ] 复选框记步（/iter 逐轮推进对账用）。反例：「实装微光并补断言」是两步（装了两个动作）；「改 shader 看效果」不是步（没有可核查结果）。一步禁装第二个动作，禁无可核查结果的描述。

步骤内容四分

每类步骤只带让它无歧义必需的信息，不多带：

• 验收步骤：断言名＋断言内容（规格的确切值写进断言，禁「按规格取值」类指代）＋测试落点（哪套冒烟段/单元套/探针/闸段）＋真实入口（测试从哪个真实入口驱动）＋判据绑定面（绑被测改动特有的可观测提交面）。
• 实装步骤：确切签名（名字/参数/返回类型）＋文件落点（file:line）＋规格钉住的取值；实现体不写——签名与验收已定的不写；只有签名和测试都定不了的算法才给代码块，且只给那段算法。
• 验证步骤：跑哪道闸（确切命令）＋什么输出算过（期望输出或判据）。
• 引用步骤：引用别卡的接口块，不重复别卡的代码。

T 卡间接口声明

每张 T 卡声明两块——取用（本卡从早前卡用什么，带确切签名）与产出（后续卡依赖本卡的什么，带确切名字与类型）。/iter 按卡逐轮施工，施工方只见本卡——接口块是邻卡名字与类型的唯一来处；后卡引用的名字必须与早卡定义逐字一致（自审第三查兜这一条）。

禁行句式（不决定任何事的行）

「TBD」「酌情处理」「适当优化」「如上所述的测试」「后续批再说」、任何本批任务未定义的类型或函数名——这些行不决定任何事，留在卡里只能让实施期自由发挥。计划 = 实施者无法独自做出的决策集合；计划比它描述的规格还长 = 在抄写程序，不是计划。

纪律

• 平实中文，禁自造缩写与名词堆叠；仓库既有术语照用。
• 估时给区间+切分预案（超软盒预挂）。
• 任务卡自审七查（2026-10-19 立五查，2026-10-21 补第六查，2026-10-27 补第七查；借自 superpowers:writing-plans 自审节适配）：任务卡写完、交 grilling 复核前必跑——①规格覆盖：逐条过「目标与完成定义」的规格项/需求点，每条都能指到一张 T 卡，并指到验收对照表的一行，指不到的补卡/补行；②步骤扫描：每步只能让实施者写出一个合情合理的东西、且一步不多带——不决定事的行是缺口，签名与验收已定的函数体是抄写，两样都就地改；③类型一致性：后卡引用的签名/属性名与早卡定义逐字一致；④审查焦点＋改动覆盖：规格暗示、但没有任何 T 卡测试覆盖的失败模式——对照「验证闸」节逐条过，把最可能坑到玩家的列出来、挂到责任 T 卡补验收条目；同时核文件结构图里的每个行为改动都能指到对照表行，指不到的补测试或标非行为改动；查完确实没有才写「无」；⑤篇幅比例：卡片比它实现的规格长几倍＝在抄程序，代码块占大半就把函数体换成签名＋断言名，再验每步仍无歧义；⑥落位与复用（2026-10-21 用户立规）：逐条过本批每个新增文件、新增函数、新增数据件——**盘上是否已有做同样事的东西（grep 同职责实现、grep 同名与同义标识符）？该功能是否已有唯一落点？同一事实是否只在一处定义、有无 helper 散落「就近的文件」？新增件之间的调用路径与跨层出口是否显式声明？**答案写进卡内「落位与可复用性预检」节并与文件结构图对得上（标「新增」的必须能指到不能复用的理由）；对不上就改成复用既有件、或把重复的落点并进唯一一处；⑦指标预算（2026-10-27 迭代 39 实证立规）：逐条过本批每个新增文件——「实现规范预算」节三查一查的数字与接口块/文件结构图实数一致（数接口块 func 行、数成员 var 行、迁移函数逐个对 tools/gdstyle_baseline.txt 源键），少报、漏对账或预算节缺失的回炉补节，存量触面写明「S13 键只降不升」预期。七查发现问题就地改完再交复核，不用再自审一轮；自审在 grilling 之前跑，不替代 grilling 对抗复核。
• grilling 复核门（2026-10-10 用户立规；2026-11-05 补处置登记义务）：卡片成文后必经 grilling 多轮复核，裁决全落、零待裁点，卡片才算成立；每轮发现与处置逐条写进卡内「复核记录」节（必备结构第 17 节）。复核审点含验收清单：逐需求点过「测什么/怎么测/谁验」三问，答不上来的需求点回炉（2026-10-11 用户立规）；并核对照表两端是否对得上、真实入口是否绕过改动点、判据绑定面是否绑被测改动特有的可观测提交面（2026-10-21 立）；再核「落位与可复用性预检」节与文件结构图是否对得上——每个标「新增」的件都要有不能复用的理由与唯一落点，给不出的回炉改成复用（2026-10-21 用户立规）；再核「实现规范预算」节数字与接口块/文件结构图实数一致——少报方法数、漏迁移函数对账、预算节缺失的回炉（2026-10-27 用户立规）；再核「拆分边界纪律」条款在位、每个拆出单元有职责语句与集体身份——凑计数袋形态回炉（2026-10-28 用户立规）；再核「验证闸」对照表每行判据出处行锚逐行实读**（2026-11-07 用户立）——打开锚所指文档行，核句子在位且内容与该行判据匹配；机检 C5 只查存在性、查不出内容错位，写卡后文档被其他批改动会使锚漂移（2026-11-07 退役卡 ux 四锚漂移实证）；锚失位＝发现清单一条，按四类分流处置；再核引擎技术面三查（接口与边界见下条）：①卡内签名与实装步骤涉及的 Godot API 在 4.7 存在且行为如卡所述；②实装步骤不踩 godot-master NEVER list 与 Gotchas；③热路径/批量/线程形态匹配其性能预算——产出发现清单，逐条按「复核发现四类分流」处置（2026-11-04 用户立规；2026-11-05 补去向口径：只有待裁类归用户裁决，自判与补写两类由复核者自己落卡，退回上游类退对应段）。**
• 引擎技术面复核接口（2026-11-04 立，godot-master 窄口径接入）：本条是 req-card 对 godot-master 技能的唯一引用面，四条收窄——①取用白名单：只取其 SKILL.md 内三块——Part 4 NEVER list（33 条）、Part 8 Gotchas（8 条）、Part 5 性能预算表；卡涉及具体领域（物理/动画/UI/存档/寻路等）时另按其 Part 2 决策矩阵加载与改动面直接相关的 reference，至多 2 个；禁加载工作流链、genre 蓝图与其余整库。②权威边界：只取引擎事实（API 行为、已知坑、预算数字），不取其工程组织主张（目录结构、autoload/signal bus 模式）——架构/分层/数值判断权威仍是本项目 architecture.md、code-conventions 与 data/tables；两者冲突时项目规范赢，冲突本身当轮作为待裁点呈报用户，禁按任一方默默改卡。③输出形态：复核产出＝发现清单（卡内位置＋违反条目号如 NEVER-7/Gotcha-1＋一句依据）＋四类去向之一，其中待裁与退回上游两类不改写方案，自判与补写两类的处置就是把卡改对；引用条目须给编号，判不了标「未判」禁硬判。④成本约束：成本地板＝hub SKILL.md 单文件；卡内 T 步不含节点/信号/Tween/Resource/物理/线程/渲染面时只跑②清单对照，不加载领域 reference；每个领域 reference 一轮复核只加载一次。
• 复核发现四类分流（2026-11-05 用户立规）：复核者每拿到一条发现，先问「答案从哪来」，四选一登记去向（写进卡内「复核记录」节的去向格）；前两类的处置由复核者自己完成，禁转成问句向用户求裁：
  • 自判——查权威文档或查代码现状就能得到唯一答案。权威文档＝本卡设计事实源那一份 owner 文档＋design/engineering/ 五份规约与 architecture＋术语表＋在册先例（git 提交信息与库内已入库实现）。处置＝复核者当场下结论并把卡改成那个答案，处置格写结论＋文件:行号 依据。禁问用户：这类问题问出去等于把可查的事推给人决策。
  • 补写——权威文档不反对，但卡里漏写：具体名字与参数、测试落点、判据绑定面、规格钉住的取值、实现规范预算数字。处置＝回炉补进对应节（判据形态照「任务卡写作纪律」的实装步骤与「禁行句式」两条——卡里不许留没定义的名字）。禁问用户：漏写不是分叉，问了等于让用户替写卡段补卡。
  • 待裁——几种做法都不违反权威文档、代价不同、影响玩法或体验取向。这才是待裁点：全部备选案并列＋各自代价＋推荐案与淘汰依据交用户裁决（口径同 process-conventions §3 第 2 条与 doc-design 的禁代裁条）。必须问用户。
  • 退回上游——写卡段动不了的未闭合或规范冲突，三个退口：①文档设计线未闭合（缺设计定稿，或 owner 文档仍留未裁的设计点）退 doc-design；②美术设计线未闭合（样张未过审或 art-bible 条款缺）退 asset-ingest，两线并列时退未闭合那段（判据沿用第〇步的拒写卡分流，不另立标准）；③架构或代码规范本身有问题（architecture 与 code-conventions／test-conventions 互相冲突、缺项、或与卡片要求打架）退 design/engineering/ 规约修订通道（归口 doc-design），随呈报写清哪两条冲突、两种改法各自的代价。处置＝停笔呈报，禁在卡内绕开规范自造第三条路（形态同第 13 节「机检键与卡片契约互斥时一律停卡呈报」）。边界：owner 文档给了取值域没给具体值＝属退口①，既不由复核者自钉，也不当实现问题问用户。
  • 两条配套细则（2026-11-05 拿两份双审报告 56 条发现回放后补）：①一条发现只记一个主去向，连带动作走既有通道不另立第五类——要改文档面句子的列进「关联文档同步面」当反哺点，本卡范围外要日后做的登记待办清单一条；②「判定不改」也是自判，处置格写「不改＋依据」（依据可以是既有裁决记录属历史留档、命中面不涉本批、或既有规范本就如此），观察类发现照样要在记录里占一行。
• 写卡段的完成判据与呈报口径（2026-11-05 用户立规）：卡片成文不是终点。固定顺序＝自审七查 → 派未参与撰写的只读复核者做对抗复核（子代理或独立会话，至少一轮）→ 发现逐条四类分流处置 → 待裁类全部呈完且用户裁决通过 → 处置逐条写进「复核记录」节 → 待办清单状态推进「已写卡」→ 提交 → 合回（收口六步细则见 process-conventions §1 第 2 条，本文不重列）。这条顺序没走完，禁对用户说「完成」「做完了」「卡片已写好」这类收工表述——此时只能报「卡片成文、复核未跑完」并点明缺哪一步。理由：commit 点零钩子检查、全量验证在合回后的远端 CI，卡片是否真被复核过机器看不出来，只由「复核记录」节＋流水线闸该节判据＋本条呈报口径三处兜住。
• 卡片落盘时点（2026-11-04 用户裁立；2026-11-05 补凭据形态；2026-11-06 用户裁凭据换代）：收口序列（冻结→件核→并 master→删区，车道铁律 §1）只对完成态事项执行；写卡段的完成判据＝grilling 复核裁决全落＋用户裁决通过（卡片成立）。复核凭据＝卡内「复核记录」节（不另设报告文件），缺节按未完成态处置，禁落 commit。成文未复核的卡片禁套用收口序列——卡片成文、grilling 多轮改稿与待办清单状态推进一律只存在于 worktree，master 不落未成立卡；成立后同 worktree 一次合回（合回即删区照车道铁律）。已合回卡片若复核产生修订，修订版在新 worktree 落笔再走成立裁决与合回，禁在 master 直改卡片。复核先于提交（2026-11-05 用户裁）：grilling 复核跑完、缺陷清单裁完之前禁把卡片落 commit——先复核、后提交、再合回；细则同 design/engineering/process-conventions.md §1 第 2 条「卡片复核前置判据」。
• 待办清单状态回写义务（2026-10-10 用户立规；2026-10-18 按五段流水线换代；2026-11-06 复核凭据换代）：卡片写完必把第〇步定位到的待办清单条目状态推进为「已写卡（reports/ 下需求卡片路径）」（判据＝doc-conventions §12.1「已写卡」证据项）——条目在登记段已存在，禁另立重复条目，防遗忘义务由状态承载；原「待编入/已编入/已开工/已入库」旧状态词停用，编入迭代后由编排段（iter-plan）记「已编迭代 N」；实现批完成入库后按待办清单退役规则整条删除。
• 需求卡片是中间文档：批入库后按「吸收即死」退役，结论迁现行事实源（GDD/待办清单/roadmap）。
• 开工令与执行归 /iter 技能（需求卡片统一经迭代编排执行，2026-10-25 用户裁：无迭代外执行通道）；需求卡片写完呈用户裁决后才可开工。