docs(规约): 文件头第三轮定稿——介绍本模块入规范（Python 存在性条款成文）+白名单两类+一切文档反向链接废止（用户令）

§1.4.1 换代：头注存在性=pyguide §3.8.2 明文要求（module docstring 介绍 contents and usage）+PEP 257；白名单五类砍两类（①职责摘要 ②使用约束）；黑名单新增一切文档反向链接（实现 GDD：/指路：废止，追溯归 GDD 文档与 registry 侧）；§1.4 GDD 锚行条款同步废止；§2.1 删留指路行死句；CLAUDE.md 红线同步

CLAUDE.md

@@ -61,7 +61,7 @@
 - 用语红线——一切对用户输出禁自造黑话，需要作者解释的词必须展开成完整白话句（doc-conventions 第 4 节三形态表）
 - 呈报六问——What 现状差异 / Why 动机与不做代价 / How 方案与全部备选 / Where 影响面 / 验收判据 / 不确定点单列收尾；Who/When 不进正文；仅首次描述需求/bug/方案适用
 - 真人检测只登记不阻塞——登记进 07 清单/实现报告即完成义务，禁以等目检为停工理由或收口前置
-- 文件头 = `##` 文档注释 ≤8 行白名单制（code-conventions §1.4.1；写法权威 = Google Python Style Guide §3.8 + PEP 257；机器闸 tools/audit_file_headers.py）
+- 文件头 = `##` 文档注释，介绍本模块，≤8 行两类白名单（①职责摘要 ②使用约束；禁一切文档反向链接；code-conventions §1.4.1，规范权威 = Google pyguide §3.8 + PEP 257；机器闸 tools/audit_file_headers.py）
 - 数值单一事实源——玩法数值只存 `data/tables/`（.tres）经 ConfigDB 单点读取；禁数值字面量与自建 `load()` 表路径
 - RNG 单点——禁 `randomize()`/自建 RandomNumberGenerator，随机只经 `RngService` 统一流
 - 架构事实唯一源——架构事实只认 `design/dev/architecture/architecture.md`；禁立第二架构文档或决策文档体系，历史决策记录只进 git commit log

design/dev/code-conventions.md

@@ -19,17 +19,19 @@
 依赖方向唯一：`views →（信号）→ 组合根 →（写调用）→ core`。视图零核心写调用（纯 setter / 信号外发优先）；"读核心状态 → 拼展示文案"集中于装配器（presenter）；核心写接口（settle_batch / submit_window_selection / runner 推进）只允许在组合根出现。
 
 ### 1.4 命名 = 领域命名，禁止系统 ID 前缀
-文件名与类名禁止 `a1_`/`b1_`/`c1_` 等系统 ID 前缀（`a1_board_generator.gd` → `board_generator.gd`）。设计追溯不靠前缀：每个核心实现文件头注必须带一行 `# 实现 GDD：design/gdd/systems/<循环>/<系统文档>.md（系统 ID Xn）`；系统 ID 只作为文档与 registry 的追溯锚。豁免：D2 schema 类与 autoload；文档/夹具登记名（如 b4_golden）属文档层。
+文件名与类名禁止 `a1_`/`b1_`/`c1_` 等系统 ID 前缀（`a1_board_generator.gd` → `board_generator.gd`）。设计追溯不靠前缀：代码↔设计的追溯由 GDD 文档与 registry 侧承担，系统 ID 只作为文档与 registry 的追溯锚；文件头注不承担追溯职责，不写任何文档链接（§1.4.1）。豁免：D2 schema 类与 autoload；文档/夹具登记名（如 b4_golden）属文档层。
 
-### 1.4.1 文件头 = `##` 文档注释，≤8 行，白名单制
+### 1.4.1 文件头 = `##` 文档注释，介绍本模块，≤8 行，两类白名单制
 
-文件头注释只用 `##` 文档注释（Godot 官方载体，进编辑器 F1 帮助），总行数 ≤8 行（不含空行，从文件首个非空行到首个非注释代码行）。写法权威 = Google Python Style Guide §3.8 + PEP 257（GDScript 官方风格指南对文件头零条款，语法近 Python，沿用其规范——不自造标准）。
+头注的存在性与内容范围以 Python 规范为权威（GDScript 语法近 Python，官方风格指南对文件头零条款，不自造标准）：Google Python Style Guide §3.8.2 明文要求——"Files should start with a docstring describing the contents and usage of the module"（文件应以描述模块内容与用法的 docstring 开头）；PEP 257——模块一般都应有 docstring，摘要压一行。
 
-白名单（只许五类，超出一类即违规）：①一行职责摘要——这是什么；②用途/验证问题一行——它为什么存在；③GDD 锚行（§1.4 格式）；④硬使用约束——使用本文件前必须知道的禁令，每条一行；⑤指路行——架构文档/契约文档的位置。
+载体与上限：只用 `##` 文档注释（Godot 官方载体，进编辑器 F1 帮助），总行数 ≤8（不含空行，从文件首个非空行到首个非注释代码行）。
 
-黑名单（出现即违规）：日期与变更叙事——改动史查 `git log`/`git blame`，变更背景读对应迭代实现报告；与 code-conventions、架构文档重复的段落——规范与架构各有唯一权威文档，文件头只指路不复制；场景结构、生命周期等代码机制描述——"Never describe the code"（pyguide §3.8.5）。
+白名单（只许两类）：①职责摘要——这是什么，一句话；项目语境（垂直切片状态/验证目标）以括号并入本行。②使用约束——使用本文件前必须知道的禁令与边界，每条一行。
 
-机器闸：`tools/audit_file_headers.py`（static_scan S10：行数上限+黑名单机械可判子集；信号契约成文位置见 §2.1）。存量头注按白名单清偿后挂入收口闸序列；此间新增/改动的文件头必须即合规。
+黑名单（出现即违规）：日期与变更叙事——改动史查 `git log`/`git blame`，变更背景读迭代实现报告；与其他文档或其他文件头重复的内容——零新信息不写（pyguide §3.8.2.1）；场景结构、生命周期等代码机制描述——"Never describe the code"（pyguide §3.8.5）；一切文档反向链接——「实现 GDD：xxx」「指路：架构见 xxx」一类全部废止，代码↔设计追溯由 GDD 文档与 registry 侧承担。
+
+机器闸：`tools/audit_file_headers.py`（static_scan S10：行数上限+黑名单机械可判子集）。存量头注按白名单清偿（约 90 文件，清偿批进行中）；清偿落地后闸增补「头注必须 `##` 开头」锁死载体；此间新增/改动的文件头必须即合规。
 
 ### 1.5 禁止事实约定
 任何"大家默认这么做"的惯例必须成文进本文件（或 CLAUDE.md）才算存在。写代码时发现未成文但必须遵守的约定 → 当场补条文，不许靠惯性延续。
@@ -39,7 +41,7 @@
 ## 2. 契约纪律——跨层/跨类调用的语义
 
 ### 2.1 信号与事件契约成文
-每个跨类信号：参数语义、发送时点、消费方依赖，必须在发送方 `##` 文档注释成文，每信号一行；计入 §1.4.1 的 8 行上限，塞不下时迁契约文档并在文件头留指路行。状态机的每次迁移路径都必须发出对应事件——**缺一条路径的事件 = 消费方永久等待 = 软锁**。
+每个跨类信号：参数语义、发送时点、消费方依赖，必须在发送方 `##` 文档注释成文，每信号一行；计入 §1.4.1 的 8 行上限，装不下时迁契约文档。状态机的每次迁移路径都必须发出对应事件——**缺一条路径的事件 = 消费方永久等待 = 软锁**。
 
 ### 2.2 跨层标识符语义单一且成文
 位置（index）/ 句柄（handle）/ 键（key）是三种不同的东西。跨类传递标识符时，传递方的语义必须与接收方契约逐字一致，禁止凭"当前恰好相等"传值。