Merge pull request 'docs(serial-tool): 清理过时的「待 CH340」说法，A1–A8 编号改语义短语，销登记簿跟踪行' (#71 ) from issue-52-serial-tool-doc-cleanup into master

Reviewed-on: http://100.123.83.113:3001/wandering1/STM32F4-Base/pulls/71
docs(serial-tool): 清理过时的「待 CH340」说法，A1–A8 编号改语义短语，销登记簿跟踪行
2026-11-03 06:53:03 +08:00 · 2026-11-02 23:58:18 +08:00 · 2026-11-02 23:06:42 +08:00 · 2026-11-02 22:39:48 +08:00 · 2026-11-02 22:22:15 +08:00 · 2026-11-02 22:22:10 +08:00
639 changed files with 42421 additions and 6069 deletions
@@ -13,7 +13,7 @@
    "stack-overflow-hook-impl": "03a383dda578d12a",
    "malloc-failed-hook-impl": "fcd7250e5cd6403b",
    "stack-overflow-hook-helper": "cacd9fd028be9b5b",
-    "watchdog-module": "07808632996d66e8",
+    "watchdog-module": "5fd7efd90a78fe5a",
    "net-msgq-adopt": "a0f913e3f34c8e9e",
    "reset-cause-latch": "983927d587cb9f48",
    "iwdg-hal-driver": "4b902875a84554e9",
@@ -23,11 +23,11 @@
    "ioc-task-stacks": "58ee94dd2a093177",
    "adc1-hal-enabled": "1a8ed6cff34f7ba6",
    "adc1-calibration-call": "8d5f4b40fb218913",
-    "adc1-calibration-impl": "d33bc4323e243248",
-    "adc-tick-tim3-branch": "39c3548c37f6c4ae",
+    "adc1-calibration-impl": "25723dd0449ac701",
+    "adc-tick-tim3-branch": "17d43a565f50c6f2",
    "ioc-adc-trig-t3trgo": "a9939de260ee46f8",
    "ioc-adc-dma-continuous": "189126670d85d80a",
-    "adc1-dma-link": "397fce92dca3b728",
+    "adc1-dma-link": "8a57c70611db1a02",
    "adc1-dma-irq-priority": "beff08e91333229b"
  },
  "_note": "CubeMX 存活审计基线；改动用 --write 重建"
@@ -14,7 +14,7 @@ whenToUse: 要跑板级测试套件（CH395F/STORAGE/GD5F/RTC）回归、要开/
  实测 GD5F 整轮破坏性跑一次即多记一个 NAND 坏块（容量 95248→95200），
  计数持久化在 dhara journal checkpoint 头里，普通格式化恢复不回来。
 - 提交门禁：pre-commit 钩子 `test-suite-switch` 默认拦截测试构建
-  （确需提交用 `ALLOW_TEST_BUILD=1` 显式放行）——**跑完务必改回全注释并 `@build`**。
+  （确需提交用 `ALLOW_TEST_BUILD=1` 显式放行）——**跑完务必改回全注释并 `/keil-build`**。

 ## 一键回归（推荐路径，勿手工循环）

@@ -28,15 +28,15 @@ whenToUse: 要跑板级测试套件（CH395F/STORAGE/GD5F/RTC）回归、要开/
 - 脚本 try/finally **无条件还原 `test_config.h`**（含 Ctrl-C 路径）——这是它存在的核心
  理由：跑完忘还原 = 测试固件进库。`--keep-config` 仅调试用。
 - 退出码 0=全 PASS / 1=有 FAIL / 2=环境错误；4 套件真机一轮数分钟起，**仅回归窗口用，绝不挂 pre-commit**。
- 手工循环时的顺序（每轮）：改宏（只开一个）→ `@build` 0错0警 → 烧录 →
+- 手工循环时的顺序（每轮）：改宏（只开一个）→ `/keil-build` 0错0警 → 烧录 →
  `serial-assistant` 采集（open→clear→烧录→wait-idle）→ 判读套件汇总行。

 ## 跑后检查清单（必做）

 1. `test_config.h` 恢复全注释（用 run_all_suites.py 则已自动）；
-2. `@build` 确认产品构建 0 错 0 警；
+2. `/keil-build` 确认产品构建 0 错 0 警；
 3. 若开过破坏性开关：核对开机日志容量数字（健康满值 96064 pages / 187 MB），
-   掉了 → 按 `docs/测试说明/存储维护与容量恢复.md` 走恢复动作；
+   掉了 → 按 `docs/测试说明/专项验证/存储维护与容量恢复.md` 走恢复动作；
 4. 提交前 `test-suite-switch` 门禁会再兜一道。

 ## 三个维护动作别混用（存储类）
@@ -47,8 +47,8 @@ whenToUse: 要跑板级测试套件（CH395F/STORAGE/GD5F/RTC）回归、要开/
 | B 容量恢复 | A + `STORAGE_RECOVERY_FULL_WIPE`（擦净 2044 块 + 断电重启） | 卷全失，约 4s 擦除 |
 | C 日常回归 | 只开 `TEST_SUITE_*`，不开破坏性 | 无（只读模式，横幅 `mode: READ-ONLY`） |

-原理与完整步骤见 `docs/测试说明/存储维护与容量恢复.md`；各套件用例清单/判读见
-`docs/测试说明/` 对应 `*_Test_Guide.md`；流程规范 `docs/测试说明/测试开发标准流程.md` §3。
+原理与完整步骤见 `docs/测试说明/专项验证/存储维护与容量恢复.md`；各套件用例清单/判读见
+`docs/测试说明/` 对应 `*_Test_Guide.md`；流程规范 `docs/测试说明/流程与规范/测试开发标准流程.md` §3。

 ## 其它项目怎么套

@@ -0,0 +1,73 @@
+---
+name: board-ui-nav
+description: 板端 UI 交互的唯一正确入口：先问固件"我在哪"（STATUS 身份查询），再决定按键；到页用闭环 --to 或 bench 直开 --goto。附 #69 实证的四类走错页根因与恢复配方。
+whenToUse: 需要上真机/台架进某页面看图（如故障录波、回放、定值）、在板端做 UI 取证、或从错误页面/待机态/未知屏恢复时。**写任何注键/取帧代码之前先读本技能**。
+---
+
+# 板端 UI 导航（唯一入口 = scripts/board_ui_nav.py）
+
+一句话纪律：**一切"进页面看图"都走 `scripts/board_ui_nav.py`，禁止另写一次性注键脚本。**
+2026-11-02 #38 调试里"总是进错误页面浪费大量时间"的直接原因，就是临时手搓
+`board_walk*.py` 盲按 `d*9`——而闭环导航器 2026-10-25 起就已存在（10-25 盲走事故
+9 个目标只有 3 个落对，`docs/UI设计/UI_自动化测试流程.md` §7.1）。
+
+## 为什么不能自己搓（#69 复盘四类根因，全部有实证）
+
+1. **协议旧版零身份反馈**：KEY 的 ACK 是空帧，"发了 5 个键"≠"到了第 5 层"。（已修：
+   7003 新增 STATUS 命令，固件直读 `s_depth/s_path/s_sel` + 当前内容页 id，见下）
+2. **N−1 屏坑**：KEY ACK 与 LCDMEM 推流共用同一条 TCP，`sleep(0.30)` 就抓帧拿到的是
+   上一屏（规则①：排空到帧流静默 ≥900 ms；现在 `key()` 代码已真正执行排空+双帧比对）。
+3. **物理陷阱**：待机态按 `e` 是**重开最近页**不是进菜单；级联列光标记忆上次行不归零；
+   根列最后两行的子列弹框被 160×160 屏裁掉（selftest/runlog 因此"读不到选带"）。
+4. **认屏误判**：菜单子列标签与页标题同字（记录查询子列里的 事故记录/操作记录…），
+   像素分类器会把级联菜单判成 PAGE——**有 STATUS 时以 STATUS 为准**，trace 留痕不一致。
+
+## 命令（python 一律 .venv；真机动作必须已持 bench 锁并加 --i-hold-bench-lock）
+
+```powershell
+# 我在哪？（固件身份 + 像素双口径，不一致会留痕打印）
+.venv\Scripts\python.exe scripts\board_ui_nav.py --where --i-hold-bench-lock
+
+# 到页：闭环步行（像素态设备/老固件也能用；每键重认屏，绝不猜步数）
+.venv\Scripts\python.exe scripts\board_ui_nav.py --board --to wave_play --grab C:\temp\wx --i-hold-bench-lock
+
+# 到页：bench 固件直开页（一次往返直达，不注键；见下"直开页的边界"）
+.venv\Scripts\python.exe scripts\board_ui_nav.py --goto wave_play --grab C:\temp\wx --i-hold-bench-lock
+
+# 提交门禁快检（无台架、无模拟器产物也要绿）
+.venv\Scripts\python.exe scripts\board_ui_nav.py --selftest-quick
+```
+
+`--list` 列出全部合法页 id 与菜单路径；`--trace 路径` 落步迹 jsonl（排错先看它）。
+退出码：0 成功 / 1 分类或导航失败 / 2 环境错误 / 3 拒动（未持锁确认位等）。
+
+## 身份回读与直开页（#69 新增，两端共享 ui_net_sink.h 契约）
+
+- **STATUS（命令 4）**：应答 `[ver][kind][depth][n][id_len][path][sel][page id]`；
+  kind = MENU/PAGE/STANDBY（待机优先判）。老固件不应答 → 主机打印一次后自动退回纯像素。
+  生产固件也支持 STATUS（只读、零画面副作用）。
+- **GOTO（命令 5）**：**编译期双闸** `DTU_BENCH`（临时 bench 固件）或模拟器宏
+  `UI_REMO_ALLOW_GOTO`；生产固件恒拒 `status=4`。拒绝码：1 无此页 id / 2 执行类页 /
+  3 开页失败 / 5 待机态（先按键唤醒再来）。直开按查看权限 `UI_PERM_VIEW` 进入，
+  **不弹密码**——所以它只用于调试取证，不能当作"过密码"的旁路写路径。
+- 执行类页面 `clear`/`reset`（第二次 ENTER 即真执行）主机与固件**双侧**默认拒绝，
+  `--allow-exec-pages` 才放行，放行 = 接受后果。
+
+## 走错页 / 未知屏恢复配方（按序，不跳步）
+
+1. `--where` 先看 STATUS：`PAGE` → 按 `s` 关页（导航器 `--to` 自动做）；
+   `STANDBY` → 按 `e` 唤醒（注意规则②：home 上 `e` 可能重开最近页）；
+   `MENU depth>0` → 按 `s` 或 `l` 都收一级（台架复核 2026-11-02：菜单态 `s` 与 `l` 同走
+   `menu_back`，父列选中留在原地；旧说法"`s` 不收列"系把待机态 `s` 无效误读成菜单行为）。
+2. STATUS 无应答（老固件）才吃退避键序（默认 `esl`，`--backoff-keys sl` 可去 ENTER）；
+   ENTER 上限 1 次是硬闸（BACKOFF_MAX_E），报停机就 dump 帧人眼看，不许连按。
+3. 反复落错页且 trace 里出现"像素与 STATUS 不一致" → 分类器或固件有账要记，
+   把留痕帧 `--dump-fail` 存下交 Lead，**不要**改判据迁就现状。
+
+## 边界
+
+- 本脚本不申请锁、不碰串口与烧录；锁的取还见 task-worktree 技能
+  （`lock acquire bench --task <ID>`）。
+- 台架证据只进 `ci-artifacts/`（`--walk` 默认 `ci-artifacts/uinav/walk/`，与 BOARD_TRUTH
+  读取目录已并一），不进工作树。
+- UI 源码改动的前后回归是 ui-verify 技能（5 门禁），本技能只管"人到板上去看"。
@@ -1,6 +1,6 @@
 ---
 name: cubemx-regen
-description: CubeMX 重生成存活工作流（L1 写进 .ioc → L2 USER CODE 区/宏改名 → L3 审计兜底）：重生成前后各跑什么、哪些定制会被静默覆盖、审计脚本 check_cubemx_survival.py 的 --check/--write 语义。STM32CubeMX 项目通用方法论 + 本仓库清单。
+description: CubeMX 重生成存活工作流（写进 .ioc → 搬进 USER CODE 区/宏改名 → 审计兜底三层）：重生成前后各跑什么、哪些定制会被静默覆盖、审计脚本 check_cubemx_survival.py 的 --check/--write 语义。STM32CubeMX 项目通用方法论 + 本仓库清单。
 whenToUse: 要用 CubeMX 重新生成工程（改 .ioc / 外设配置）、改动 Src/Inc 生成区附近代码、或排查"重生成后定制丢失/行为变了但编译不报错"时。
 ---

@@ -12,12 +12,12 @@ whenToUse: 要用 CubeMX 重新生成工程（改 .ioc / 外设配置）、改

 ## 三层优先级（防丢失的唯一正确顺序）

-1. **L1 写进 `.ioc`**（权限最高）：凡 CubeMX 界面能表达的配置（任务栈/优先级/队列/
+1. **写进 `.ioc`**（第一层，权限最高）：凡 CubeMX 界面能表达的配置（任务栈/优先级/队列/
   事件组/堆大小/IWDG 参数/FreeRTOS 钩子开关）必须在 GUI 里设——重生成只会照写。
   ⚠ **别凭印象断言"界面里没有该项"**，先翻标签页或查 `db/mcu/IP/*_Modes.xml`
   （实测 `configCHECK_FOR_STACK_OVERFLOW=2` 在 FreeRTOS → Config parameters →
   Hook function related definitions 里，自造宏区被抹两次后才找到）。
-2. **L2 搬进 `USER CODE` 区**：只信 CubeMX **当前模板真实生成**的区名（优先
+2. **搬进 `USER CODE` 区**（第二层）：只信 CubeMX **当前模板真实生成**的区名（优先
   `USER CODE BEGIN 0` 这类从未变过的标准位）。**不要依赖"自造标记区"**——
   模板换代时自造区连同内容一起消失（实测中断函数模板换代的教训）。
   生成区内要**去掉一句调用** → 宏改名：`USER CODE BEGIN 0` 里放空实现 +
@@ -26,12 +26,12 @@ whenToUse: 要用 CubeMX 重新生成工程（改 .ioc / 外设配置）、改
   要**替换生成实体定义**（如 4 个 Fault Handler 本体）→ 我们的定义放
   `USER CODE BEGIN 0`，**必须写在 `#define X X_Gen` 之前**（写在之后会被自己的宏改名），
   生成区恢复原样，链接器自动移除未引用的 `*_Gen`。
-3. **L3 审计兜底**：清单 + 哈希基线漂移检测（见下）。
+3. **审计兜底**（第三层）：清单 + 哈希基线漂移检测（见下）。

 ## 重生成前后固定动作

 ```powershell
-# 重生成前：把能在 GUI 表达的都写进 .ioc（L1 检查）
+# 重生成前：把能在 GUI 表达的都写进 .ioc（第一层检查）
 # 重生成后【立刻】：
 & '.venv\Scripts\python.exe' scripts/check_cubemx_survival.py            # 人读报告
 & '.venv\Scripts\python.exe' scripts/check_cubemx_survival.py --check    # 门禁模式（pre-commit 同款）
@@ -41,21 +41,21 @@ whenToUse: 要用 CubeMX 重新生成工程（改 .ioc / 外设配置）、改

 - 退出码 0=通过 / 1=有 FAIL 项；已挂 pre-commit `cubemx-survival` 钩子
  （改 `.ioc`/`Src/`/`Inc/`/`.uvprojx` 触发）。
- **L3 清单已清空 = 重生成应当零 diff**；仍有 diff 就是被覆盖了，直接跑脚本定位。
+- **审计清单已清空 = 重生成应当零 diff**；仍有 diff 就是被覆盖了，直接跑脚本定位。
 - `uvprojx` 不参与漂移检测（每次构建被 UV4 改写），只保留"源文件仍挂载"断言。

 ## 实测陷阱清单

 - CubeMX 对 System Exception（HardFault/MemManage/BusFault/UsageFault）**只生成优先级、
  从不生成使能代码**；`.ioc` 里 `NVIC.MemoryManagement_IRQn=true` ≠ 已使能（只是向量可见）。
-  `SHCSR` 使能位只能手工写（L2）+ 审计项兜底。
+  `SHCSR` 使能位只能手工写（第二层）+ 审计项兜底。
 - 启用 FreeRTOS 后模板会生成 `USER CODE BEGIN 4 / 5` 区（默认空桩）——**钩子实现必须
  整体写进这两个区**，且 helper 函数放更早的区（同名两处定义 = 编译错）。
 - 生成文件行尾/末尾空行按工具自身风格，**勿用改写型钩子去修剪**（已豁免，勿"顺手格式化"）。
- 重生成后除审计脚本外，照常走 `@build`（0 错 0 警）+ 必要时 `@test` 闭环。
+- 重生成后除审计脚本外，照常走 `/keil-build`（0 错 0 警）+ 必要时 `/serial-boot-test` 闭环。

 ## 其它 CubeMX 项目怎么套

-L1/L2/L3 方法论与"宏改名两招"完全通用；本仓库的清单/基线在
+这三层方法论与"宏改名两招"完全通用；本仓库的清单/基线在
 `scripts/check_cubemx_survival.py`（21 项 + `.cubemx_survival_baseline.json`），
 新项目照它建自己的清单。方法论详见 `docs/子系统设计/看门狗设计说明.md` §10.1/§10.2。
@@ -1,12 +1,14 @@
 ---
 name: draw-diagram
-description: docs/ 文档技术配图绘制流程（精确布局图用 SVG 生成器 / 拓扑图用 Mermaid）：挑脚本 → 改顶部数据 → 重跑生成 → 目检 → md 相对路径引用 → 脚本+产物一并提交，产物统一放 docs/images/。
-whenToUse: 需要新增/修改 docs/ 文档的技术配图（协议帧、分层架构、依赖/就绪屏障、流程图、时序、状态机），或用户要求"画个图 / 生成图 / 更新架构图 / 帧格式图"时。
+description: docs/ 文档技术配图绘制流程（精确布局图用 tools/arch_diagram/ 的纯标准库 SVG 生成器 / 拓扑图用 Mermaid）：挑脚本或照抄骨架新建生成器 → 改顶部数据 → 跑生成并把 check_fit/OVERFLOW 溢出预检清零 → Windows 无渲染器时用 headless Chrome/Edge 截图 + read_image 回读目检 → 回改生成器重跑 → 过 generated-fresh 逐字节幂等 → md 相对路径引用 → 脚本+产物一并提交，产物统一放 docs/images/。
+whenToUse: 需要新增/修改 docs/ 文档的技术配图（协议帧、分层架构、依赖/就绪屏障、台阶/泳道对照、刻度尺、流程图、时序、状态机），从零新写一个 gen_*_svg.py 生成器，在 Windows 上想"目检"一张 SVG，或用户要求"画个图 / 生成图 / 更新架构图 / 帧格式图"时。
 ---

 # 文档配图绘制（SVG / Mermaid）

-`docs/` 文档技术配图的统一流程；完整选型依据 / 约定 / 检查清单见 `docs/架构设计/图形绘制流程.md`。**产物统一放 `docs/images/`**（专门配图目录，`.svg` 入库；PNG 预览属本地派生物、不入库）。
+`docs/` 文档技术配图的统一流程；完整选型依据 / 约定 / 检查清单见 `docs/架构设计/图形绘制流程.md`。**产物统一放 `docs/images/`**（专门配图目录，`.svg` 入库；PNG 预览属本地派生物、不入库，`.gitignore` 已含 `docs/images/*.png` 与 `ci-artifacts/`）。
+
+> 本窗实测（2026-10-29，新建 2 张图）：**"浏览器打开 SVG 目检"这一步在 Windows 上不可直接执行**——没有现成 SVG 栅格化工具，只能走 headless Chrome/Edge 截图 + 图片回读；且 `generated-fresh` 是**逐字节**门禁，生成器自己的控制台打印也会成为失败源（见 §五）。

 ## 工具选型

@@ -15,15 +17,15 @@ whenToUse: 需要新增/修改 docs/ 文档的技术配图（协议帧、分层
 | 协议帧 / 字节布局（字段宽 ∝ 字节数、偏移标尺） | SVG：`tools/arch_diagram/gen_frame_svg.py` |
 | 分层架构 / 模块依赖 | SVG：`tools/arch_diagram/gen_arch_svg.py` |
 | 就绪屏障 / 生产者-消费者 | SVG：`tools/arch_diagram/gen_barrier_svg.py` |
+| 台阶 / 泳道对照 / 刻度尺等"高度差、并列对照"类 | SVG：**新写一个** `tools/arch_diagram/gen_<主题>_svg.py`（照抄最近生成器的骨架，见 §二） |
 | 其他精确布局图 | **复制**最接近的生成器改顶部数据（`build()` 与数据解耦，通用） |
-| 流程 / 时序 / 状态机 / ER（只表达拓扑关系） | Markdown 内嵌 ` ```mermaid ` 代码块（`flowchart` / `sequenceDiagram` / `stateDiagram-v2` / `erDiagram`），无需生成图片 |
+| 流程 / 时序 / 状态机 / ER（只表达拓扑关系） | Markdown 内嵌 ```mermaid 代码块（`flowchart` / `sequenceDiagram` / `stateDiagram-v2` / `erDiagram`），无需生成图片 |

-> Mermaid 盒子按文本自适应宽、自动加有向边，**只适合"关系"类图**；凡需精确像素 / 比例的布局图一律走 SVG 生成器。
+> Mermaid 盒子按文本自适应宽、自动加有向边，**只适合"关系"类图**；凡需精确像素 / 比例 / 高度差的布局图一律走 SVG 生成器（实测教训：五级"台阶"用 Mermaid 会被压成同一高度，"还差一级"就看不出来了）。

-## SVG 生成流程（仓库根目录执行）
+## 一、改既有图（最短路线）

-1. **挑 / 复制脚本**：新类型图复制最接近的生成器，只改顶部数据区。
-2. **改顶部数据**：字段 / 节点 / 标题 / 配色。沿用既有调色板（主色 / 底色）：
+1. 改**顶部数据 / 常量区**（字段、节点、标题、配色），不改 `build()` 结构。配色沿用既有调色板（主色 / 底色）：

   | 语义 | 主色 | 底色 |
   |---|---|---|
@@ -35,38 +37,175 @@ whenToUse: 需要新增/修改 docs/ 文档的技术配图（协议帧、分层
   | 灰 | `#475569` | `#f1f5f9` |
   | 玫红 | `#e11d48` | `#fff1f2` |

-3. **重跑**（脚本内置 `ElementTree` 自检，XML 不合法直接抛错）：
+2. 重跑（仓库根；脚本内置 `ET.fromstring` 自检，XML 不合法直接抛错）：

   ```powershell
   & '.venv\Scripts\python.exe' tools/arch_diagram/gen_xxx.py
-   # 成功输出：OK <字节> bytes, canvas <W>x<H> -> <路径>
+   # 期望：OK <字节> bytes, canvas <W>x<H> -> <路径>，且没有 OVERFLOW WARN / overflow warnings 行
   ```

-4. **目检**：浏览器打开 `docs/images/*.svg`——文字不溢出盒外、框 / 线 / 标签对齐、配色符合调色板。
-5. **md 引用**（相对路径）：`docs/` 根的 md 写 `![标题](images/xxx.svg)`；`docs/UI设计/` 等子目录 md 写 `![…](../images/xxx.svg)`。
-6. **提交**：生成器脚本（源）+ 生成的 `.svg`（产物）**一并**提交。
+3. 目检（§三）→ 引用（§四）→ 幂等与门禁（§五）→ 提交（§六）。

-## SVG 约定（手写 / 新增生成器必须遵循）
+## 二、从零新写生成器（先抄骨架，别裸写）

- **纯标准库**拼 SVG（只用 `html` / `os`（+ `math`）），不引第三方库（SVG 由浏览器用系统字体渲染）
- 所有文本经 `html.escape(s, quote=True)`，防止破坏 XML
- 字体栈：`Microsoft YaHei, Segoe UI, PingFang SC, sans-serif`
- 文本宽估算（自适应盒宽）：CJK / 全角 / 圈码 / 箭头 ≈ `1.0em`，其余 ≈ `0.58em`（**宁大勿小**防溢出）
- 落盘：`open(OUT, "w", encoding="utf-8", newline="\n")`（UTF-8 无 BOM + LF）
- 写盘后 `xml.etree.ElementTree.fromstring(svg)` 自检
- 产物放 `docs/images/`，命名 `<主题>.svg`（可与同名 `.md` 对应）
+1. **先读同目录 1~2 个最近的脚本**（如 `tools/arch_diagram/gen_adc_frontend_svg.py`、`gen_adc_code_scale_svg.py`），抄它们的三条约定：
+   - **文件头 docstring** 写清四件事：产物路径 + 这张图回答什么问题 + **「为什么不用 Mermaid」** + 用法（"仓库根目录，任意 python3"）与"改内容 vs 调坐标"的边界；
+   - **顶部集中常量块**：画布与几何（`W` / `H` / `PAD` / `RIGHT`）→ `FONT` → 各级字号 → 调色板 → 文案（`TITLE` / `SUB*` / 逐条目 / `FOOTNOTE`）；坐标一律由常量推导，别在 `build()` 里塞魔法数；
+   - **纯标准库**：`import html / os / sys / xml.etree.ElementTree as ET`，helpers 只有 `esc` / `text_w` / `txt` / `line` / `rect` / `wrap` / `check_fit` / `emit` / `build`。
+2. **照抄预检三件套**（`gen_adc_frontend_svg.py` 里还没有；从 `tools/arch_diagram/gen_data_trust_ladder_svg.py` 抄）：`OVERFLOW = []` + `check_fit(s, fs, avail, where)` + `wrap(s, fs, avail, max_lines, where)`，标题 / 副标题 / 盒内标题走 `check_fit`，盒内正文与脚注走 `wrap`（`wrap` 按估宽折行、超行数用 `…` 收尾并记一条 OVERFLOW）。`build()` 末尾：`emit("OK ...")` 之后 `if OVERFLOW: emit("!! %d overflow warnings" % len(OVERFLOW))`。估宽口径不变：CJK / 全角 / 圈码 / 箭头 ≈ `1.0em`，其余 ≈ `0.58em`（宁大勿小）。
+3. **照抄 `emit()`**（幂等门禁的地基，见 §五）：

-## SVG → PNG（可选，本地派生物不入库）
+   ```python
+   def emit(s):
+       """控制台打印按目标编码替换，绝不因 GBK 终端遇上 ²/− 之类字符而崩
+       （generated-fresh 钩子会把本脚本拷进临时目录重跑，崩了就是一片假红）。"""
+       enc = getattr(sys.stdout, "encoding", None) or "ascii"
+       sys.stdout.write(s.encode(enc, "replace").decode(enc, "replace") + "\n")
+   ```

- 最简单：浏览器打开 `.svg` → 另存为图片
- 脚本化：`& '.venv\Scripts\python.exe' -m pip install cairosvg` 后
-  `& '.venv\Scripts\python.exe' -c "import cairosvg; cairosvg.svg2png(url='docs/images/xxx.svg', write_to='x.png', scale=2)"`
- `.gitignore` 已含 `docs/images/*.png`
+4. 路径锚在脚本自身位置，别用 cwd（临时目录重跑才不会漂）：

-## 提交前检查清单
+   ```python
+   ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+   OUT = os.path.join(ROOT, "docs", "images", "<主题>.svg")
+   ```

- [ ] 生成器输出 `OK … bytes`（无异常 = XML 合法）
- [ ] 浏览器目检：文字不溢出、框 / 线 / 标签对齐、配色符合调色板
- [ ] 引用它的 `.md` 里图片**相对路径**正确（能显示）
- [ ] 脚本 + 产物 `.svg` **一并**暂存
- [ ] `pre-commit run --files <脚本> <svg> <md>` 全过（无乱码 / 行尾空白 / 编码 OK）
+5. 跑 `& '.venv\Scripts\python.exe' tools/arch_diagram/gen_<主题>_svg.py`，**把 OVERFLOW 告警打到 0 再进目检**——预检能在渲染前就报出 `foot: 974 > 968` 这类溢出（本窗实测两张图首跑各报一条脚注超宽），比靠眼睛反复量便宜一个数量级。
+6. 新脚本落库时**同批**把行加进 `tools/arch_diagram/README.md` 的「**产物清单**」——那张表按图逐行，列 =
+   图 / 生成器 / 这张图答什么 / 顶部数据区 / 挂在（`文档:行号`）。**全仓只此一张逐脚本清单**：
+   `docs/架构设计/图形绘制流程.md` 曾另立一张三列表，结果两张各漏各的（2026-10-30 实测 README 漏 5 个、
+   那张漏 9 个），现已换成指针。所以新图只加一行，别在第二篇文档再起一张表。
+
+## 三b、大图（几十框几十边）加一道碰撞审计，别只靠眼睛
+
+边数一多，像素回读就查不全（本窗实测：42 框 37 边的端到端链路图，缩略 PNG 看着干净，
+审计器一眼报出 23 条：边标签压节点、走线穿框、标签出画布）。做法是**解析自己生成的 SVG**
+而不是解析渲染结果——`ET.parse` 产物，按 `font-size`/`fill` 分诊文字，估宽口径直接复用生成器的
+`text_w()`（两边同一把尺子才不会假绿），然后判三件事：
+
+1. **边标签的「文字盒」vs 节点框**（不是白片盒）：交集 > 6 px² 就算问题——节点在边之后画，
+   压上去的**文字**会被节点白底吃掉半个字（本窗症状：「串行执行」渲染成「行执行」）。
+   白片本身压到框边角是**无害**的（白片先画、节点后画，只是盖住一点白底，不改字）。
+   除「有没有压上」，还要打印**文字与最近框的最小水平余量**并按 < 3px 报问题：
+   本窗「TRGO 触发」余量 0.7px、「帧 B 下发」1.5px，都没压上却随时会被真实字宽吃笔画，
+   缩短标签后升到 3.5px 以上才算安全。
+2. **走线段 vs 节点框**（内缩 2px 再判，排除贴边端点）：线穿框是硬伤，改边的出入框方位或独占通道。
+3. **标签互压 / 出画布**：白片两两求交；`box[3] > H-2` 查脚注贴底。
+4. **零余量复扫（生成器侧，别只跑 SVG 侧那一遍）**：SVG 反推不出哪两个框是本边端点，
+   走线只能内缩着查 → 1~3px 的切边照不到。用生成器自己的 `Box` / `route()` / `label_at()`
+   真值再扫一遍：框不膨胀不内缩、只跳本边两端。跑 SVG 侧与真值侧两遍都归零才算收工。
+
+脚本骨架与判据见 `reference/svg-collision-audit.py`（可直接拷进 `ci-artifacts/` 当一次性工具用，
+**别放 `tools/arch_diagram/`**——那里只放生成器，非 `gen_*.py` 的脚本混进去会让人以为在册）。
+
+配套的两条几何纪律（都是本窗踩出来的）：
+
+- **同轴直连不要插退化折点**：同行两框若按「同轴 → 加一段 gx 走廊」的通用规则生成，会产出
+  `[(195,176),(219,176),(219,176),(243,176)]` 这种点集——线还是直的，但**标签落点算成第一半的中点**，
+  整格偏移半个通道 → 压框。正解：出框轴与入框轴同轴且已对齐时直接返回两点线。
+- **标签落点用弧长中点，不用「最长段中点」**：多段折线里最长段可能有多条（对称 Z 字），
+  取第一条会把标签推到拐角上；沿总弧长取 50% 再定位，配合 `seg`/`t` 旋钮微调。
+
+**先验审计器本身，再信它的「0 条」**：本窗把 `hi > y0` 复制粘贴成 `hi > x0`，零余量那一遍
+凭空报出 3 条「穿框」，差点为此重排三条边的走线。判据脚本的假阳性比漏报更贵——它会让你
+去改一张本来没问题的图。规矩：写完后挑一条**已知干净**的边（例如两框正对的直连边）单独跑一遍，
+确认它不报，再跑全量。
+
+## 三、目检（Windows：本机没有任何现成 SVG 渲染器）
+
+**先探测，别照抄 cairosvg 命令**：本仓 `.venv` 无 `cairosvg`（`ModuleNotFoundError: No module named 'cairosvg'`），`rsvg-convert` 不存在，只有 Edge / Chrome：
+
+```bash
+# ops_bash（git-bash）里探测；哪个存在用哪个
+ls -1 "/c/Program Files/Google/Chrome/Application/chrome.exe" \
+      "/c/Program Files (x86)/Microsoft/Edge/Application/msedge.exe" 2>/dev/null
+command -v rsvg-convert inkscape magick convert 2>/dev/null || echo "no CLI rasterizer"
+```
+
+```powershell
+Test-Path "C:\Program Files\Google\Chrome\Application\chrome.exe"
+Test-Path "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe"
+```
+
+截图（**`--screenshot=` 必须给绝对 Windows 路径 + 绝对 `file:///` 输入**，并且**固定用
+`--headless=new`**：本窗用旧 `--headless` 同一套命令时成时不成——一次写出了 168 KB，
+下一次静默不写文件；也别把 stderr 丢进 `/dev/null`，成功标志就是它自己打印的那行字数）：
+
+```bash
+mkdir -p ci-artifacts                      # Chrome 没有建目录的参数，先自己建
+OUT="D:\\Code\\DTU Code\\<工作树名>\\ci-artifacts\\<主题>.png"   # 绝对路径、反斜杠
+"/c/Program Files/Google/Chrome/Application/chrome.exe" \
+  --headless=new --disable-gpu --hide-scrollbars --force-device-scale-factor=1 \
+  --window-size=1060,712 \
+  --screenshot="$OUT" \
+  "file:///D:/Code/DTU Code/<工作树名>/docs/images/<主题>.svg" 2>&1 | tail -2
+```
+
+成功标志是 Chrome 自己打印的 `<N> bytes written to file D:\...`。**回读 PNG 才算目检完成**：
+
+```ts
+const r = await tools.read_image({ file_path: "D:\\Code\\DTU Code\\<工作树名>\\ci-artifacts\\<主题>.png" });
+console.log(r.image.width + "x" + r.image.height, "bytes=" + r.image.bytes);   // 应等于 --window-size / 画布
+```
+
+看什么：文字压框 / 溢出盒外、标签互撞（本窗实测两轮才干净：台阶图首轮"文字压到盒下方 + 标签互撞"，第二、三轮才修完）、`wrap` 收尾的省略号 `…`（有 = 文案超长）、虚线与盒边线重叠、配色是否还在调色板里。发现问题**回改生成器常量并重跑预检**，然后**重新截图**（PNG 是派生物，不会自己更新），`--window-size` 跟着 `canvas WxH` 改。
+
+## 四、md 引用（相对路径）
+
+`docs/` 根的 md：`![标题](images/xxx.svg)`；`docs/任务规划/`、`docs/UI设计/` 等子目录 md：`![…](../images/xxx.svg)`（本窗实例：`docs/任务规划/数据可信.md` 写 `![数据可信是五级台阶，现在踩在第 2 级](../images/数据可信台阶.svg)`）。alt 文本写成"这张图的结论是什么"，别只重复文件名。
+
+## 五、generated-fresh：逐字节幂等门禁（新图长期不假红的前提）
+
+`generated-fresh` 把 `tools/arch_diagram/gen_*.py`（`docs-svg` 项：`per_script: true`、`pattern: gen_*.py`、`mode: exact`）**逐个拷进系统临时目录重跑**，与工作区产物**逐字节**比对：内容不同 = `DIFF`（生成物比生成器旧）、临时目录多出一个工作区没有的文件 = `NEW`、`rc≠0` = 「生成器报错」。由此推出四条硬约束：
+
+1. **生成器只能写那一个 `.svg`**：绝不在脚本里顺手导出 PNG 预览（预览写 `ci-artifacts/`，不进 `docs/images/`）。
+2. **stdout 不许崩**：GBK 终端遇上 `²` / `−` / CJK 路径会 `UnicodeEncodeError` → 钩子 `rc≠0`，一片假红。所以打印一律走 `emit()`，脚本里不留裸 `print()`（本窗实测：两份新生成器只改了一份，另一份照旧崩）。
+3. **产物内容零不确定**：SVG 里不写时间戳 / 绝对路径 / 主机名；浮点坐标一律 `%g` / `%.1f` 定形；字典与 `os.listdir` 结果参与布局时先 `sorted()`。
+4. **`gen_*.py` 命名即自动在册**（pattern 就是 `gen_*.py`）——故意不叫这个名字等于躲开门禁，门禁最大盲区正是"未登记的生成器"，别利用它。
+
+自查（仓库根）：
+
+```bash
+.venv/Scripts/python.exe tools/arch_diagram/gen_<主题>_svg.py
+sha1sum docs/images/<主题>.svg
+.venv/Scripts/python.exe tools/arch_diagram/gen_<主题>_svg.py   # 重跑后 sha1 必须不变
+.venv/Scripts/python.exe scripts/check_generated_fresh.py        # 期望 rc=0，无 DIFF/NEW，[BASELINE] 不增
+```
+
+```powershell
+& '.venv\Scripts\python.exe' scripts/check_generated_fresh.py          # 单独跑（不 stash 别人在飞的改动）
+& '.venv\Scripts\python.exe' scripts/check_generated_fresh.py --list   # 只看在册声明
+& '.venv\Scripts\python.exe' -m pre_commit run generated-fresh --files tools/arch_diagram/gen_<主题>_svg.py docs/images/<主题>.svg
+```
+
+⚠ **别跑不带 `--files` 也不带 `--all-files` 的裸 `pre_commit run`**（会 stash 掉别人在飞的改动）；判读口径 → `docs/门禁说明/generated-fresh.md` §4。
+
+## 六、提交
+
+生成器脚本（源）+ `docs/images/<主题>.svg`（产物）+ 引用它的 `.md` + `tools/arch_diagram/README.md`「产物清单」那一行**同一笔**提交；PNG 预览不入库。
+
+```powershell
+& '.venv\Scripts\python.exe' -m pre_commit run --files <脚本> <svg> <md> <README.md>
+```
+
+## 陷阱（本窗实测）
+
+- **想装渲染器再转 PNG**：`cairosvg` 不在 `.venv`（`ModuleNotFoundError`）、`requirements.txt` 里也没有，`rsvg-convert` / `inkscape` / `magick` 这台机器上都不存在 → 用 §三 的 headless Chrome/Edge（权威命令在 `docs/架构设计/图形绘制流程.md` §四，2026-10-30 已同步成这套，别再往回写）。**没真渲染出 PNG 的情况下不要声称"已目检"。**
+- **`--screenshot=ci-artifacts/ladder.png`（相对路径）** → `EXIT 2` + `Failed to write file ci-artifacts/ladder.png: 系统找不到指定的路径。 (0x3)`，PNG 压根没落盘；换绝对 Windows 路径后写出 95549 bytes。这条报错**不区分**"相对路径"与"目录不存在"两种成因（实测 `mkdir -p ci-artifacts` 已先跑过、仍报同一句），排查时两条都排。
+- **只做预检 + 缩略目检就收工（大图）**：`check_fit` 归零、PNG 看着干净，仍可能有二十来条标签压框——节点白底后画会吃掉压上去的标签；大图必须走 §三b 的解析式审计。
+- **只做预检就收工**：`check_fit` / `OVERFLOW` 归零也不代表干净——本窗实测"门标签压第 5 级盒、蓝底标签挤、多余虚线"三类碰撞只有 PNG 回读看得见；反过来只目检不预检，脚注溢出就得靠眼睛反复量。**两者都要 0**。
+- **手改 SVG 成品**：等于制造「不是我改的」diff，且 `generated-fresh` 立刻 DIFF；也**不要退化成 ASCII 框图**（AGENTS.md 明令勿手绘）。一切修改都落在生成器常量上再重跑。
+- **批量改生成器时 `old_string` 不匹配**：一批 `edit` 会在中途抛错，但**前面的编辑已经落盘** → 半成品生成器（本窗实测：`emit` helper 缺失却仍打印 OK，几轮之后才查出）。正解：改前先 `read` 出精确原文，逐条改，末尾统一复验（`grep -n "def emit"`、`grep -c print`、再重跑看 rc 与 OK 行）。
+- **PNG 尺寸 ≠ 画布**：`--window-size` 忘了跟着 `W`/`H` 改 → 截出来带大片空白或裁掉底部脚注；回读 `r.image.width/height` 与 `canvas WxH` 对一下再判定。
+- **`docs/images/` 下手写 `.svg` 或放 PNG 预览**：前者没有生成器（NEW / 躲过门禁），后者污染"临时目录多了文件"判定。
+
+## 验证清单
+
+- [ ] 生成器输出 `OK … bytes, canvas WxH`，**无** `OVERFLOW WARN` / `!! N overflow warnings`；`grep -n "def emit"` 命中、`grep -c print` = 0。
+- [ ] 绝对路径 PNG 存在、尺寸 = 画布，`read_image` 回读确认：无文字压框 / 溢出、无标签互撞、无 `…` 截断收尾、配色在调色板内。
+- [ ] 连跑两次产物 sha1 不变；`scripts/check_generated_fresh.py` rc=0（无 DIFF / NEW，`[BASELINE]` 未增加）。
+- [ ] 大图（≥20 边）：跑一遍 §三b 的碰撞审计，报数归零（标签压框 / 走线穿框 / 标签出画布）。
+- [ ] 引用它的 `.md` 相对路径正确（根目录 `images/`，子目录 `../images/`）；`tools/arch_diagram/README.md`「产物清单」已加行，「挂在」列的 `文档:行号` 用 `grep -rn "<图名>.svg" docs/ --include=*.md` 现扫核对（**别抄旧行号**，行号一漂整列就废）。
+- [ ] 脚本 + 产物 `.svg` + `.md` + README 行一并暂存；`pre-commit run --files …` 全过（无乱码 / 行尾空白 / 编码 OK）。
+
+> **与规范文档的分工（2026-10-30 已对齐）**：`docs/架构设计/图形绘制流程.md` 是规范归属（AGENTS.md：同一事实只在一处详述），本 skill 是执行侧。该文档 §3.1 第 4 步与 §四 原先写的「浏览器打开 SVG / 给 `.venv` 装 cairosvg 转 PNG」在本机走不通，已同步成 headless Edge/Chrome 那套（命令只在 §四 详述，本 skill §三 留判据指针）；**改渲染命令时两处一起改**——做图判据以本 skill 为准，规范条文以该文档为归属。
@@ -0,0 +1,154 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""一次性碰撞审计（拷进 `ci-artifacts/` 用，**不要放进 `tools/arch_diagram/`**）：
+解析自己生成的 SVG，报「边标签压节点 / 走线穿框 / 标签互压 / 文字出画布 / 节点文字出框 /
+标签余量过窄」，并打印最紧的三条「标签文字 ↔ 最近框」水平余量。
+
+为什么需要它：`check_fit` 预检只量**框内**文字；几十框几十边的大图，
+标签压框与走线穿框在缩略 PNG 里根本看不全（实测 42 框 37 边报出 23 条），
+而像素回读又慢又主观。解析产物是确定性的。
+
+依赖：待审图对应的生成器模块必须能被 import（脚本靠它复用同一把估宽尺子 `text_w()`
+与几何常量 `CW` / `CH` / `EDGE_FONT` / `ECOL`，两边同尺子才不会假绿）。
+生成器侧要求：边标签白片用 `fill-opacity="0.94"`、节点框用 `fill="#ffffff"` 且
+`width==CW`、`height==CH`（本脚本靠这两条分诊）；文字用 `<text font-size fill>`。
+
+**这一遍照不到的东西**（别把它当唯一判据）：
+- 走线检查必须把框**内缩**几像素，否则合法的「线接在框边上」会全报成穿框——从 SVG
+  反推不出哪两个框是本边的端点。代价：1~3px 的切边也照不到。要零余量就在**生成器侧**
+  再用 `Box` / `route()` / `label_at()` 的真值扫一遍（线段 vs 不膨胀的框，只跳本边两端）。
+- 白片比通道宽一点、被节点白底盖住边角：无害（白片先画、节点后画），不用改；
+  要盯的是**文字**的余量，上面那三条数就是。
+- 自写的判据脚本先拿一条**已知干净**的边验它不报，再信它的「0 条」：实测一条
+  `hi > x0` 写成 `hi > y0` 的复制粘贴错，凭空报出 3 条「穿框」，差点为此重排走线。
+
+用法（仓库根）：
+    python ci-artifacts/label_audit.py <生成器模块名> [svg 路径]
+    # 例：python ci-artifacts/label_audit.py gen_arch_endtoend_svg
+    #     python ci-artifacts/label_audit.py gen_wave_record_flow_svg docs/images/故障录波数据流.svg
+退出码：0 = 无问题，1 = 有问题（打印明细）。
+别的生成器若没有同名常量（多数用 `CHIP_FONT` / 自己的线色变量），改脚本顶部 `EDGE_COLORS` 与 `edge_labels` 那两处筛选即可——估宽必须继续用该生成器自己的 `text_w()`，别换一把尺子。
+"""
+import sys
+import xml.etree.ElementTree as ET
+
+sys.path.insert(0, "tools/arch_diagram")
+sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+
+mod_name = sys.argv[1]
+G = __import__(mod_name)
+svg_path = sys.argv[2] if len(sys.argv) > 2 else G.OUT
+
+MASK_OP = "0.94"            # 边标签白片的 fill-opacity（生成器侧约定）
+EDGE_COLORS = set(G.ECOL.values())   # 边标签颜色（生成器侧的线色表）
+
+def box_of_text(el):
+    """<text> → (x0, y0, x1, y1, 文本, 字号, 颜色)。baseline y 之上约 0.85em、之下 0.22em。"""
+    x, y = float(el.get("x")), float(el.get("y"))
+    fs = float(el.get("font-size"))
+    s = "".join(el.itertext())
+    w = G.text_w(s, fs)
+    a = el.get("text-anchor", "start")
+    x0 = x if a == "start" else (x - w / 2 if a == "middle" else x - w)
+    return (x0, y - fs * 0.85, x0 + w, y + fs * 0.22, s, fs, el.get("fill"))
+
+def area(a, b):
+    ix = min(a[2], b[2]) - max(a[0], b[0])
+    iy = min(a[3], b[3]) - max(a[1], b[1])
+    return ix * iy if (ix > 0.5 and iy > 0.5) else 0.0
+
+def segs_of(d):
+    n = [float(v) for v in d.replace("M", " ").replace("L", " ").replace(",", " ").split()]
+    pts = list(zip(n[0::2], n[1::2]))
+    return list(zip(pts, pts[1:]))
+
+def seg_hits_rect(sg, r, m=2.0):
+    """轴对齐线段 vs 矩形（内缩 m 排除贴边的合法端点）。斜段一律算可疑。"""
+    (x0, y0), (x1, y1) = sg
+    rx0, ry0, rx1, ry1 = r[0] + m, r[1] + m, r[2] - m, r[3] - m
+    if abs(y0 - y1) < 0.5:
+        return ry0 < y0 < ry1 and min(x0, x1) < rx1 - m and max(x0, x1) > rx0 + m
+    if abs(x0 - x1) < 0.5:
+        return rx0 < x0 < rx1 and min(y0, y1) < ry1 - m and max(y0, y1) > ry0 + m
+    return True
+
+root = ET.parse(svg_path).getroot()
+W, H = float(root.get("width")), float(root.get("height"))
+texts, nodes, masks, paths = [], [], [], []
+for el in root.iter():
+    tag = el.tag.split("}")[-1]                     # 去命名空间，否则一个都匹配不上
+    if tag == "text":
+        texts.append(box_of_text(el))
+    elif tag == "rect":
+        w, h = float(el.get("width")), float(el.get("height"))
+        x, y = float(el.get("x")), float(el.get("y"))
+        if el.get("fill") == "#ffffff" and abs(w - G.CW) < 0.6 and abs(h - G.CH) < 0.6:
+            nodes.append((x, y, x + w, y + h, "node"))
+        elif el.get("fill") == "#ffffff" and el.get("fill-opacity") == MASK_OP:
+            masks.append((x, y, x + w, y + h, "mask"))
+    elif tag == "path" and el.get("fill") == "none":
+        paths.append(segs_of(el.get("d")))
+
+edge_labels = [t for t in texts if t[6] in EDGE_COLORS and t[5] == G.EDGE_FONT]
+bad = []
+for lb in edge_labels:
+    b = lb[:4]
+    for n in nodes:
+        a = area(b, n)
+        if a > 6:                                   # 压到框边 6 px² 以上就会被节点吃掉半个字
+            bad.append("标签压节点 %-12s 压 node@(%.0f,%.0f) %.0f px²" % (lb[4][:12], n[0], n[1], a))
+    for ob in edge_labels:
+        if ob is not lb and area(b, ob[:4]) > 6:
+            bad.append("标签互压 %s / %s" % (lb[4][:10], ob[4][:10]))
+    if b[0] < 2 or b[2] > W - 2 or b[3] > H - 2 or b[1] < 2:
+        bad.append("标签出画布 %s box=(%.0f,%.0f,%.0f,%.0f) 画布 %.0fx%.0f"
+                   % (lb[4][:12], b[0], b[1], b[2], b[3], W, H))
+for segs in paths:
+    for sg in segs:
+        for n in nodes:
+            if seg_hits_rect(sg, n):
+                bad.append("走线穿框 (%d,%d)-(%d,%d) 压 node@(%.0f,%.0f)"
+                           % (sg[0][0], sg[0][1], sg[1][0], sg[1][1], n[0], n[1]))
+                break
+# 「节点文字出框」只能按几何判：文字中心落在某个节点框里，却没被该框完整包住。
+# 别拿 font-size 当筛选——本仓惯例里副题字号 = 边标签字号 = 脚注字号（9.5），按字号筛会全灭。
+for t in texts:
+    cx, cy = (t[0] + t[2]) / 2, (t[1] + t[3]) / 2
+    host = [n for n in nodes if n[0] <= cx <= n[2] and n[1] <= cy <= n[3]]
+    for n in host:
+        if not (t[0] >= n[0] - 1 and t[2] <= n[2] + 1 and t[1] >= n[1] - 1 and t[3] <= n[3] + 1):
+            bad.append("节点文字出框 %r 超 node@(%.0f,%.0f)" % (t[4][:16], n[0], n[1]))
+            break
+
+# 余量比「有没有压上」更早暴露问题：本仓约定边标签整段落在框间通道里，
+# 只要文字离最近框 < 3px，字宽估算稍偏（本脚本与生成器共用同一把尺子，
+# 但真实字体度量和它有出入）就会被后画的节点吃掉笔画。
+MIN_CLEAR = 3.0
+clears = []
+for lb in edge_labels:
+    b = lb[:4]
+    worst, wid = None, None
+    for n in nodes:
+        if min(b[3], n[3]) - max(b[1], n[1]) <= 0:      # 竖直方向不相干
+            continue
+        c = max(n[0] - b[2], b[0] - n[2])               # 正=间距，负=压进去多深
+        if worst is None or c < worst:
+            worst, wid = c, (n[0], n[1])
+    if worst is not None:
+        clears.append((worst, lb[4][:12], wid))
+        if worst < MIN_CLEAR:
+            bad.append("标签余量过窄 %r 距 node@%s 仅 %.1fpx（< %.1f）"
+                       % (lb[4][:12], wid, worst, MIN_CLEAR))
+
+seen = []
+for b in bad:
+    if b not in seen:
+        seen.append(b)
+print("%s：边标签 %d / 节点 %d / 文字 %d / 路径 %d"
+      % (svg_path, len(edge_labels), len(nodes), len(texts), len(paths)))
+for c in sorted(clears)[:3]:
+    print("  最紧余量 %.1fpx  标签 %r  邻 node@%s" % (c[0], c[1], c[2]))
+for b in seen:
+    print("  ! " + b)
+print("合计问题 %d 条" % len(seen))
+sys.exit(1 if seen else 0)
@@ -34,5 +34,5 @@ python tools/font_gen/extract_cn.py              # 扫描 UI 源码字符串 →
 - `requirements.txt` 必须**纯 ASCII**（Windows 下 pip 按 GBK 解码，中文注释 → UnicodeDecodeError）
 - 生僻字（宋体可能无字形）→ **写码前先手动验证字形**，避免"代码写完才发现是空白"
 - 生成成功后跑 `ui-verify` skill 全回归；黄金参考因字形变化而 FAIL 属预期 → `check_content_pages.py --update` 刷新
- 字数变化时同步更新文档中的字符集计数（当前 179 汉字/符号 + ASCII 0x20-0x7E，共 274 字形）：`UI_中文字体生成与配置.md`、`UI_界面制作流程.md` C3、`UI_设计架构.md`、`simulator/README.md` 已知坑 #4
+- 字数变化时同步更新文档中的字符集计数（当前 **224** 汉字/符号 + ASCII 0x20-0x7E，共 **319** 字形；2026-10-29 实测：`ui_cn_chars.txt` 唯一码点 224、`ui_font_cn_12.c` 的 `.bitmap_index` 320 条含 notdef → 319 字形。历史上 119/214 → 179/274 → 185/280 → 218/313 均为当时快照）：`UI_中文字体生成与配置.md`、`UI_界面制作流程.md` C3、`UI_设计架构.md`、`simulator/README.md` 已知坑 #4
 - **新增字低于既有最小码位**（如 Ⅰ U+2160）会下探稀疏 cmap 起点并吞掉单码位补回条目（实测 ▶ 箭头全变方框而旧版 coverage 全绿）——`make_font.py`（2026-10-25 起）按 LVGL 首命中语义插入/守卫/校验，扩字后模拟器像素回归**必跑**
@@ -0,0 +1,119 @@
+---
+name: id-family-semantic-migration
+description: 编号族整族清退/停发 playbook：把一个编号族（字母+数字如保护功能号 L1-x~L5-x、网络条目号 F-*、登记簿旧号 N-x、台架阶段裸形 T1~T3、用例号 TC-*，或中文前缀「卡」+ 数字这类门禁语料里**没有机器识别面**的族）在全仓代码注释、测试、活文档与门禁配置里改成语义短语（含销项删行与逐号换算表入档），或把「不清退」裁定写成硬口径入档。触发语：清退某族编号、编号改成语义名或语义短语、还有多少号可清、残留多少、批次二/批次三/批次五、「卡 0」「卡 0b」「卡 1~12」、销项删行并去除相关编号、id-check 报悬空引用或不可判定超限、不可判定引用绝对数涨点、「这一族不做了」。
+whenToUse: 用于**整族**处理：先判这一族有没有机器识别面 → 清点存量 → 逐族分类 → 分批派单清退 → 收口 → 回写 docs/编号规范.md 对应节。单条待办行销项并写 void 别名用 ledger-row-retire-void-id；某个事实数（页数、叶数、钩子数）变了要同步全仓用 stale-doc-count-sweep；单个文件改名或挪目录用 scripts/rename_ref.py；跑 HEAD 版对照组用 task-worktree 的净室 worktree。这四类不由本技能覆盖，但「涨点归因」一节会用到净室 worktree。
+version: 1.1.0
+---
+
+# 编号族清退成语义标识
+
+**2026-10-29 用户裁定：全族一律停发**（含 `docs/编号规范.md` §4.1 那五个存量族）——本 playbook 的「停发」分支默认已成立，
+现在唯一还需要决策的是**要不要清退存量**（全仓改语义 + 销项删行 + 逐号换算表入档）。
+
+**动手前先判这一族有没有「机器识别面」**——它决定计数口径的来源与落地去处，两条路的做法**正好相反**：
+
+| 族形态 | 计数口径来源 | 改名手段 | `scripts/archive/id_gate/id_aliases.json` |
+|---|---|---|---|
+| 字母+数字，且在 `scripts/archive/id_gate/check_ids.py` 语料内（`id_registry.json` 有族、族 pattern 能匹配它） | 门禁自身计数（`ck.refs` / `ck.stats` / 报告行） | `scripts/rename_ids.py`（映射表 + 显式 scope + 默认干跑） | **要登记**：死号 `void`、转短语 `retired-to-phrase` |
+| 中文前缀（「卡」+ 数字）、纯散文里的号、圈号 ①②③ | **自建带标签正则扫描器**（门禁看不见它，2026-10-28 退役前的 id-check 全库报告与本族无关；两道门禁现都已退役（2026-10-28 / 2026-10-29），要普查形态就手工跑归档脚本 scripts/archive/id_gate/check_ids_new.py --range） | 逐处替换 + 断言命中数（`rename_ids.py` 靠族 pattern 驱动，这里用不上） | **刻意不登记**：登记了机器也看不见，只多一张没人核的表；停发只靠规范 + 评审 |
+
+怎么判（三条，任一为否即无识别面）：① `grep -nE '"name"|"pattern"' scripts/archive/id_gate/id_registry.json`，没有任何族 pattern 能匹配该形态；② `./.venv/Scripts/python.exe scripts/archive/id_gate/check_ids.py --top 0` 的任何校验里找不到它；③ registry 的 `blind_spots` 已明写不判（圈号与正常列举无法机械区分、裸形同字母多义只在属主登记处判）。实测：「卡」+ 数字**没有族**（中文形态只有 `malformed` 里 `陷阱 ?[0-9]` 那条禁令，管的是陷阱编号不是卡号），该族真实站点 288 处 / 56 文件，而门禁对它贡献 0。
+
+判错的代价是双向的：拿门禁计数当中文字面量族的口径 → 得出「0 处待改」的**假归零**；给无识别面的族登记别名 → 制造「有机器兜底」的错觉，真正生效的两条（§4.1.1 停发行、§9.3 换算表）反而没人写。
+
+其余铁律照旧：**不要凭 grep 估数、不要凭印象决定改哪几处、不要把「不做」只划掉一行。**
+
+## 口径：三套计数都要挑明，先问再比
+
+| 口径 | 怎么数 | 用途 |
+|---|---|---|
+| 门禁 refs（去重） | `ck.refs`：字面量 → 文件集合，**只记属主登记处文档之外**的引用 | 门禁趋势、批次验收线 |
+| 逐行站点 | 按族正则重扫 `ck.iter_files()` 语料，**含属主文档的定义行** | **排工作量、拆单** |
+| 自建扫描器站点 | 无识别面族：带标签正则全仓 walk（排除 `.git`） | 该族唯一口径，**不能拿 id-check 输出代替** |
+
+实测例：保护功能号一族「字面量 28 / 站点 184 / 文件 58」（`ck.refs`）与队友报的「219 站点 / 38 文件」并存且都对。队友报任何合并数（指纹、站点数）之前**先问口径**，不要拿自己的数去否他的数。**每个数字标明是本回合实测、动手前基线还是沿用昨日值**；**形似噪声号另立分母**（中文族一节第 4 步），绝不与待清族合并成一个总数。
+
+## Steps（字母+数字族：门禁看得见的那一路）
+
+1. 确认范围与定调
+2. 按族实测三口径（字面量 / 站点 / 文件），不用 grep 估数
+3. 逐族先分类再动手
+4. 映射表由属主文档生成
+5. 按写域拆道并行派单
+6. 门禁配置注释也是本族写入面
+7. 每处替换断言命中数
+8. 同步更新门禁侧配置
+9. 生成器文本改动必须同笔重跑产物
+10. 核队友交付
+11. 分笔提交走真实 pre-commit 钩子
+12. 收口只认门禁自身计数
+13. 回写 docs/编号规范.md
+14. 裁定「不做」也要写成可执行硬口径入档
+> 本节全文（逐字搬移、未改写，含命令与实测数字）→ [steps-alpha-numeric-family.md](reference/steps-alpha-numeric-family.md)。动手前先读那篇。
+
+## Steps（中文前缀族：连归档扫描工具都咬不到的那一路）
+
+1. 先确认连归档扫描工具也咬不到（两道编号门禁 2026-10-28 / 29 已退役，"咬不咬"从此只是工具层面的事），并把这句话写进交付
+2. 销项删行前先核证据属主
+3. 自建带标签正则扫描脚本
+4. 该族与形似噪声号分开计数，各自给分母
+5. 派单前写一份 spec 文件
+6. 逐处替换断言命中数
+7. 落地位置写死（这一族只有这几条兜）
+8. 替换后三道二次清洗
+9. 收尾复跑 + 清中间产物
+> 本节全文（逐字搬移、未改写，含命令与实测数字）→ [steps-chinese-prefix-family.md](reference/steps-chinese-prefix-family.md)。动手前先读那篇。
+
+## 不可判定引用绝对数涨点的净室归因
+
+「不可判定引用绝对数」比今日低点涨了 N 处时：
+
+1. **禁止**用「对提交新增行 grep 字母+数字形态」归因：`git diff -U0` 的加行里绝大多数文本是从旧行搬来的**存量上下文**（注释整段重写、表格加一列、Markdown 重新折行），形态匹配数出来的是「哪段文字最近被搬动」，不是「哪里涨了 N 处」——用它归因必然把老引用算成增量。`diff -U0` 只在**已定位到文件之后**用来绑笔次与行号。
+2. **正解 A（首选，同一计数器相减）**：在**仓外 detached worktree 跑 HEAD 版**（`task-worktree` skill 的净室测量仪；不 stash、不碰在飞工作区），两边都用同一个 `check_ids.py` 计数器导出 `(rel, literal)` 多重集（`ck.findings` 或 `err_groups(ck)`），做**逐文件集合差**，落差的 N 处直接指向具体文件与字面量。
+3. **正解 B（逐文件注入）**：一次只把一个文件换成在飞版跑计数器——涨点在哪个文件上，就只在注入它时出现；文件多时按 `git diff --name-only` 折半。
+4. **当轮跑不完就如实说**：本轮未跑净室归因时，只报「现值需要重新实测」并说明**需要跑净室归因**，**不得**给出候选归因对象，**不得**把上一轮的现值或余量当本回合实测值报出（每个数标明来源与时刻）。
+5. 与其它交付口径冲突的差值**登记为待查项**（两套计数可能都对），不当场判谁对谁错。
+
+## Pitfalls
+
+- 拿门禁计数当中文字面量族的口径
+- 给无机器识别面的族登记 id_aliases.json
+- 拿 grep 计数跟人吵口径
+- heredoc 里嵌 Python 正则 / 中文
+- 扫描没排除 .git
+- 凭记忆敲 old 串
+- 替换后不做同句重复检测
+- 换算表里复述字面量
+- | head 之后读 $?
+- 占位符泄漏
+- 删行前不核证据属主、不查当初为什么保留
+- 涨点归因拿 diff 新增行 grep 形态
+- 全局查找替换
+- 未分类就动手
+- 按简称匹配文件清单
+- 复现不了队友的合并指纹就怀疑丢文件
+- 替换 token 含
+- 只改生成器文案不重跑产物
+- grep 'A\|B' 空返回当文件干净
+- 一次 run_code 串 5 × wait_agent(118000) ≈ 590s 整段 abort、进度全丢
+- 游标整型比较静默不生效
+- git add 目录路径带进别道文件
+- amend 被 gitlint B1 拦
+- 改「只动注释」要拿机器证据
+- 冻结历史与原始证据不改
+- *.uvprojx 抖动不入库
+> 本节全文（逐字搬移、未改写，含命令与实测数字）→ [pitfalls.md](reference/pitfalls.md)。动手前先读那篇。
+
+## Verification
+
+1. `scripts/archive/id_gate/check_ids.py --strict` 与 plain **均 rc=0**（`[OK] 校验 1~6 无错误`），悬空引用为 0。
+2. 编号字面量与**不可判定引用绝对数**只降不升、不超 `undecidable_total_ceiling`；可判定比例不低于 `id_registry.json` 基线（86.0%）。
+3. 本族剩余站点复扫归零：有识别面族从 `ck.refs` 按族正则过滤字面量逐条打印；除冻结历史/原始证据行外无残留。
+4. `pre-commit run generated-fresh --all-files` PASS + 目检 svg diff 只有文案与框宽自适应（只在动过生成器时适用）；`check_doc_links.py --all` 通过。
+5. `/keil-build`：`BUILD=0`、0 错 0 警、`Program Size` 与改前同数（零行为改动证据，**本回合真跑**）；相关主机组（如 `net_socket 457/457`）全绿。
+6. 真实 pre-commit 钩子全绿（如 `passed=33 failed=0`）；提交笔内不含他道文件。
+7. 规范与台账已回写并复跑核数：自己先前写进规范的清点数字要么按最终实测改对，要么标明为动手前基线；「等你裁定」残留 = 0；「不做」裁定已在 §4.1.1 + §9.1 + 批次结论段落三处落地（原「变更记录」那一处已随 2026-10-28 清流水退场）。
+8. **无识别面族**：`git grep -nE '卡[ ]*[0-9]' -- .` 无输出（裸跑读 rc）；自建扫描器的站点/文件数与提交正文一致；交付里明写「本族不在 check_ids 语料内、门禁判不到」与「刻意不进 `id_aliases.json`」的理由；§4.1.1 停发行 + §9.3 换算表 + 批次结论段落三处齐全，换算表行数 = 该族字面量数（实测 14），且写明旧号永久作废、不得重新取走。
+9. **二次清洗三道各有实测数**：同句重复短语 0 行、各空格形态先计数后归一（复扫 0）、固定正则残留 0；被代码头注释引用的设计约束章节仍在（`git diff` 里没被动过）。
+10. **叙述同步**：`AGENTS.md` / `docs/README.md` / `docs/任务规划/README.md` / `docs/任务规划/登记簿.md` 里旧口径（「三项」「卡 N」类）实测归零；`ci-artifacts/` 里本次 spec 与中间产物已删。
+11. 门禁复跑清单齐：`check_ids.py` plain + `--strict`、`check_doc_links.py --all`、`bom-guard`、`no-mojibake`、`git diff --check`、`/keil-build` 或受影响单测——**每个数字标明是本回合实测**。
@@ -0,0 +1,30 @@
+# Pitfalls（自 SKILL.md 外置）
+
+> 本文由 id-family-semantic-migration 的 SKILL.md「Pitfalls」一节逐字外置而来（渐进展开：主文件只留索引与指针）。步骤号沿用原文，未重编。
+
+- **拿门禁计数当中文字面量族的口径** → 得出「0 处待改」的假归零（实测该族真实站点 288 处 / 56 文件）；先跑自建扫描器报「站点 / 文件」，并在交付里写明该族不在语料内、门禁判不到。
+- **给无机器识别面的族登记 `id_aliases.json`** → 中文前缀不进语料，登记了机器也看不见，只制造「有门禁兜底」的错觉；执行面是 §4.1.1 停发行 + §9.3 换算表 + 评审。反过来，有识别面的族不登记别名 → 门禁把旧号引用判成悬空。
+- **拿 grep 计数跟人吵口径**：先拿实测三口径，再谈拆单；两套计数不一致不是有人算错（见上表）。**形似噪声号并进总数** → 把 132 处里程碑噪声算进 420 处待改，动手就改坏 `docs/芯片手册/` 原文。
+- **heredoc 里嵌 Python 正则 / 中文** → `invalid escape sequence` 与语法错；脚本落文件再跑。中文正则用 **raw 串 + `\uXXXX`**：非 raw 串的 `"\b"` 会被解成退格符，正则**静默失配不报错**。
+- **扫描没排除 `.git`** → `.git/COMMIT_MSG_*.txt` 的 GBK 乱码历史被当残留，越清越多；**靠控制台看中文** → 一律写 UTF-8 报告文件再解析，判乱码统计 `EF BF BD` 字节数。
+- **凭记忆敲 `old` 串** → 中文引号与 ASCII 双引号形态不同，命中 0；回读原文取真身，断言前先看 `git status` 自证文件未变。
+- **替换后不做同句重复检测** → 留下「运行参数段（「数据可信」运行参数段交付）」这类句子（实测 12 行）；**同一短语两种空格形态不归一** → 全仓口径漂移（归一前先 `git grep -c -F` 数各形态）。
+- **换算表里复述字面量** → 讲规则的文档变成自己的引用站点（规范本身在门禁语料里）。
+- **`| head` 之后读 `$?`** → 永远是 0，把「还有残留」当「已归零」。
+- **占位符泄漏**：为躲转义把反引号写成 `«` / `»` 再全文替换，落盘后**必须核占位符残留 = 0**（实测 22 行泄漏到本节之外，含不是自己写的行）。
+- **删行前不核证据属主、不查当初为什么保留** → 要么删掉唯一记录，要么把已撤销的「✅ 保留行」例外当常态。
+- **涨点归因拿 diff 新增行 grep 形态** → 把存量上下文当增量；**把上一轮现值当本回合实测**、未跑净室归因就报具体归因对象 = 猜测。
+- **全局查找替换**：跨族撞号（`S3` 三义）。必走 `rename_ids.py` 映射表 + 显式 scope + 干跑；无识别面族则逐处手写 + 断言命中数。
+- **未分类就动手**：把变压器位号、Mermaid 节点名、数学记号、gitlint 规则名当编号改坏硬件资料；位号目录进 `excluded_paths`，记号进噪声表。
+- **按简称匹配文件清单** → 误报 8 个文件丢失；比对前展开真实路径。
+- **复现不了队友的合并指纹就怀疑丢文件**：先问口径（自定义顺序不可复现），改落自有逐文件 16 位基线并把跨道文件单列。
+- **替换 token 含 `**` 加粗标记** → 命中数断言 0；取反引号最小形态。
+- **只改生成器文案不重跑产物** → `generated-fresh` 必红（实证 `0f7b5a87` 同类）；「反正就是注释，不影响图」是错的，该文本进产物。
+- **`grep 'A\|B'` 空返回当文件干净**：交替竖线在多层 bash 引号里被吃掉，是探针坏不是文件干净 → 反证为空的搜索必须换 `grep -F` 复测。
+- **一次 run_code 串 `5 × wait_agent(118000)` ≈ 590s 整段 abort、进度全丢**；且一次串多条长中文 `send_message` 也撑爆 120s（发出 1 条后 abort，剩余未发）。轮询上限 4×118s，长消息拆开发。
+- **游标整型比较静默不生效**（字符串形态）；抬完用 `--strict` 与 plain 双验。
+- **`git add` 目录路径带进别道文件**、`git add -A` 卷进在飞改动；撤销自己的改动只按文件点名 `git restore scripts/archive/id_gate/id_registry.json`，不碰同树其它道文件。
+- **amend 被 gitlint B1 拦**：正文行 >80，别把 ASCII 双引号写成正文首字符。
+- **改「只动注释」要拿机器证据**：`/keil-build` 0 错 0 警且 `Program Size` 与改前**逐字节同数**（本回合真跑，引用历史提交正文自报的数字不算证据），别口头承诺。
+- **冻结历史与原始证据不改**：boot 串口日志等采集现场是冻结证据，改了就是篡改；历史「修改记录」行按裁定保持改名后形态（号已全仓退役，留一个查无此号的引用比留改过名的条目更坏）。
+- **`*.uvprojx` 抖动不入库**；`ci-artifacts/` 里的 spec 与扫描中间产物收尾删掉，别当交付物留下。
@@ -0,0 +1,66 @@
+# Steps（字母+数字族：门禁看得见的那一路）（自 SKILL.md 外置）
+
+> 本文由 id-family-semantic-migration 的 SKILL.md「Steps（字母+数字族：门禁看得见的那一路）」一节逐字外置而来（渐进展开：主文件只留索引与指针）。步骤号沿用原文，未重编。
+
+1. **确认范围与定调**：先按开头的表判识别面（无识别面 → 走下一节）；再读 `docs/编号规范.md` §4.1（族总表，穷举）、§4.1.1（已停发栏），存量与批次见 `scripts/archive/id_gate/编号治理历史.md` §9，明确本族属主登记处（`owner_docs_glob`）；旧判据「有脚本按字面量匹配它」自 2026-10-29 起作废——全族一律停发。清退 = 全仓改语义；停发 = 在规范表里写死不再新增引用（`id_registry.json` 的游标冻结只是裁定留痕，2026-10-29 起无机器读者）。
+2. **按族实测三口径（字面量 / 站点 / 文件），不用 grep 估数**。`Checker.refs` 是 **dict（字面量 → 文件集合）不是方法**，`ck.refs(fam)` 这种写法会 `TypeError`；站点数门禁不直接给，用族正则重扫它自己的语料：
+   ```python
+   import sys; sys.path.insert(0, "scripts")
+   import check_ids as ci
+   reg = ci.load_json(ci.REGISTRY_FILE, "r"); al = ci.load_json(ci.ALIASES_FILE, "a")
+   ck = ci.Checker(reg, al); ck.run()            # run() 填充 refs / stats / findings
+   for name in ("N", "S-LDG", "TC", "FEAT"):     # 族名以 id_registry.json 的 "name" 为准
+       rx = next(f for f in ck.families if f["name"] == name)["_re"]
+       lits  = {l for l in ck.refs if rx.fullmatch(l)}        # 字面量（属主文档之外）
+       files = {r for l in lits for r in ck.refs[l]}          # 文件
+       sites = sum(len(rx.findall(line))
+                   for rel in ck.iter_files()                 # 与门禁同一语料
+                   for line in ck.read(rel).splitlines())     # 含属主文档定义行
+       print(name, "literals", len(lits), "sites", sites, "files", len(files))
+   ```
+   全库扫一遍不便宜（数十秒量级）：可丢后台 job，不要和别的长活串在同一个 120s 预算里。把活族清单与每族数字记下来作为**动手前基线**（拆批次与派单依据）。新测试套件发号导致 `id-check` 校验 3 报悬空引用时，**先按号前缀聚合**定位是哪个套件/哪个族（`check_ids.py 2>&1 | grep -a '悬空引用' | ...` 前缀计数），别逐条读。
+3. **逐族先分类再动手**——不是每个命中的裸形都是编号，四类分治（实测 T1/T2/T3 的 41 处里只有部分是编号）：
+   - 真编号 → 语义短语 / 功能名；
+   - 硬件位号（变压器 T1~T3 等）→ 把目录整目录登记进 `check_ids` 的 `excluded_paths`（如 `excluded_paths += tools/netlist_semantics/`），**不逐处改位号名**；
+   - Mermaid 流程图节点名 → 改语义名但**节点数与连线关系不变**，图结构不动；
+   - 数学记号 → 进噪声表；门禁自身的规则名（gitlint `T2 Title has trailing whitespace`）→ 不改。
+   分类前先把剩余每处原文打出来看（`grep -F` 逐文件），否则会把硬件资料改坏。
+4. **映射表由属主文档生成**：从属主文档取「编号 → 功能名/语义短语」全表（实测 42 个定义 / 28 个在用），改名走 `scripts/rename_ids.py`（映射表驱动 + **显式 scope** + **默认干跑** + 自动往 `scripts/archive/id_gate/id_aliases.json` 写 scoped 旧号→新号条目，状态 `renamed` / `retired-to-phrase` / `void`）。**绝不全局查找替换**：同一裸形字面量可能同时属多个族（实测 `S3` 三义），全局替换等于造新撞号。
+5. **按写域拆道并行派单**（代码与测试半 / 文档半 / 某功能面各一条道），同笔用 `send_message` 下发**统一改写口径**（措辞、是否动字符串字面量、生成器归属、冻结历史行怎么处理），避免各道自定措辞；口径长就先落成 spec 文件（中文族一节第 5 步的做法同样适用）。看板任务只认 `team_task_update` 的 `task_id` / `expected_revision` / `action=reassign` / `owner` 四个字段。
+6. **门禁配置注释也是本族写入面**：`.pre-commit-config.yaml` 的注释里会挂着功能号（实测 `7h) ADC 采样有效性校验（语义取数与有效性层）`、`7i) 保护定值模型（P1 / 动作留痕层载体）`、`规划 §3.3 保护判据层`）。配置属 Lead 写域，Lead 自己改（注释不占钩子行为、不影响 51 条钩子口径），但**必须计入批次范围并在提交正文写清是 Lead 改的 config**。
+7. **每处替换断言命中数**，不做整文件正则批量改写（批量改写会静默漏改）：
+   ```python
+   def sub(path, pairs):
+       p = pathlib.Path(path); t = p.read_text(encoding='utf-8')
+       for old, new, want in pairs:
+           got = t.count(old); assert got == want, (path, old, got, want)
+           t = t.replace(old, new)
+       p.write_text(t, encoding='utf-8')
+   ```
+   **token 取最小形态**：文档里被反引号/加粗包住的号，替换单位取反引号形（```T4```）而**不含 `**` 标记**（第 225 行是 `**裸形 `T4`**`，按「裸形 `T4`」替就命中 0）。讲编号的文档改成**形态描述**（如「字母 T 紧跟数字 4」）能把不可判定绝对数还回余量：实测 4 处 → 982 降到 978，且 lesson 不丢。
+8. **同步更新归档扫描器的配置**：`check_ids` 的 `excluded_paths` 与噪声表按第 3 步的分类结果改，使剩余命中不再是「假编号」；新测试套件发号的悬空引用要先定**定义位**：
+   - 定义位**只能落一处**——注册表族（`scripts/archive/id_gate/id_registry.json`）或该套件说明文档，**两处并存比没有定义位更坏**；文档真写出来了（含判据与上板清单）就以文档为准、**撤族**；
+   - 要建族就照现有同类族克隆（`pattern` / `digit_width` / `owner_docs_glob` / `scope` / `cursor`），别自造字段；
+   - **抬游标前先确认游标是字符串形态**（`'cursor': 'TC-UIDATA-026'`）——整型比较会静默不生效（实测踩坑），用字符串解析或正则取序号再比。
+9. **生成器文本改动必须同笔重跑产物**：`tools/arch_diagram/gen_*.py` 里的 docstring/文案会进产物，`generated-fresh` 把生成器拷到临时目录重跑逐字节比对，**只改源不改产物必红**。这类站点整包转给生成器属主，「谁改谁跑生成器」，脚本 + 全部 svg 产物同一笔：
+   ```bash
+   ./.venv/Scripts/python.exe tools/arch_diagram/gen_net_instability_svg.py 2>&1 | tail -3
+   pre-commit run generated-fresh --all-files   # 单钩子复跑必须带 --all-files 或 --files
+   ```
+   ⚠ **不带这两个参数的裸 `pre-commit run` 会进 staged_files_only 上下文并 stash 别道在飞的改动**（`docs/门禁说明/generated-fresh.md` §2）；`pre-commit` 不在 PATH 时改用 `& '.venv\Scripts\python.exe' -m pre_commit run generated-fresh --all-files`。PASS 后再目检 diff：只应文字变长、框宽自适应（526→551、右缘未越界、画布不变）。不把该站点从批次里悄悄丢掉：登记为「待未完成半批」，收口时核对。
+10. **核队友交付**（按写域并行后必做）：
+    - 文件清单**先展开真实路径再比**：按简称匹配会误报丢失（作者列 `phasor.py`/`adc_health.py` 等 8 个，实为 `test/host/<模块>/run_unit_test.py`）；用 `git -c core.quotepath=false diff --name-only` 取全路径做集合差。
+    - 合并指纹对不上先问口径：作者按**自定义顺序**算的数 Lead 侧复现不了（`d0a289b7` vs 报的 `a45e7e2b`）。改建 **Lead 自有逐文件 16 位基线**存 `ci-artifacts/lead_lane_b_files.json`，并把**跨道文件单列**（实测 `App/algo/README.md`）——autostash 后按逐文件比对，不假称对上别人的合并数。
+11. **分笔提交走真实 pre-commit 钩子**：`git add` 用显式清单。坑：`git add -- App/algo` 把文档道的 `App/algo/README.md`（26 处）带上车，正文按 48 只文件写就不准了 → 该笔未 push 时 `--amend` 挪到文档笔并补一句归属说明；`git add -A` 会把别道在飞文件卷进来（覆盖率钩子在他编译不过的半成品上报红）→ 撤出他人域后重跑。提交正文每行 ≤80（gitlint B1），别把 ASCII 双引号写成正文首字符。
+12. **收口只认门禁自身计数**（**仅限语料内的族**；无识别面族见下一节第 8~9 步），并核**只减不增**：
+    ```bash
+    ./.venv/Scripts/python.exe scripts/archive/id_gate/check_ids.py 2>&1 | grep -aE '扫描|可判定 |不可判定引用' | head -4
+    ./.venv/Scripts/python.exe scripts/archive/id_gate/check_ids.py --strict 2>&1 | tail -1   # [OK] 校验 1~6 无错误
+    ```
+    报告「字面量 8787→8299→7828」「不可判定绝对数 1161→984→982→978（上限 1166）」「可判定比例 88.14%（基线 86.0%，容差 0.1pp）」。**绝对数与比例两根线都要报**：把可判定引用改成散文会稀释比值，所以另有不可判定绝对数上限。涨点归因见「净室归因」一节。
+13. **回写 `docs/编号规范.md`**：§4.1 族表（停发/待清栏）、§4.1.1 已停发栏；存量表与批次结果表在 `scripts/archive/id_gate/编号治理历史.md` §9（只减不增、清点数字按最终实测同步）；表格若保留动手前的清点数，**明确标注「不是当前存量，是动手前基线」**，否则就是拿旧数当现状。**用户裁定原文与理由直接写进对应节**（§4.1.1 停发行 + 该族的批次结论段落）——2026-10-28 起不再往变更记录写流水（`docs/文档规范.md` §5.1）。
+14. **裁定「不做」也要写成可执行硬口径入档**（不是只划掉一行——「不做」最容易被读成「那还可以继续发号」）：
+    - §4.1.1「已停发」栏新增该族一行：**游标冻结、现存号只减不增、新用例改用语义化测试函数名 + 文档表格行名**，并写清与 §4.1 存量族栏的关系（那五族 2026-10-29 起也一律停发）；
+    - 批次段落写明裁定原文与理由（归档 `scripts/archive/id_gate/编号治理历史.md` §9.1——§9 一族的事实源已在归档篇，规范正文只留口径）（该族是唯一真被脚本按字面量匹配的族：C 断言标签 + 测试函数名 + 文档用例表三处同一号），并给出**将来真要清退的前置条件**：追溯器（`check_test_traceability.py`）先同时认新旧两种形态、并行核对通过，**不许先改文档再改代码**；
+    - 全文核「等你裁定 / 需你裁定」悬空表述残留数归 0；
+    - 无机器识别面的族落地面不同（`docs/编号规范.md` §4.1.1 一行 + 归档 `编号治理历史.md` §9.3 换算表 + 叙述同步三处），见下一节第 7 步。
@@ -0,0 +1,65 @@
+# Steps（中文前缀族：连归档扫描工具都咬不到的那一路）（自 SKILL.md 外置）
+
+> 本文由 id-family-semantic-migration 的 SKILL.md「Steps（中文前缀族：门禁咬不到的那一路）」一节逐字外置而来（渐进展开：主文件只留索引与指针）。步骤号沿用原文，未重编。
+
+1. **先确认连归档扫描工具也咬不到，并把这句话写进交付**（两道编号门禁已退役，机器面整体消失）：`scripts/archive/id_gate/check_ids.py` 的族 pattern 是拉丁形态、中文前缀不进语料 → **id-check 的 refs / 可判定比例 / 悬空引用与本族无关**；报告开头写「本族不在 check_ids 语料内，口径 = 自建扫描器」。
+2. **销项删行前先核证据属主**（这是删行的唯一许可证）：
+   - 先取历史口径：`git log --oneline -20 -- <文档>`、`git show <rev>:<文档> | sed -n '/^## 5/,/^## 6/p'` 找回被删的卡表与当初「完成即销项删行 / 标 ✅ 保留行」的理由；
+   - 核对判据与实测记录**已完整沉淀进属主章节**（实测：「已知电压注入验证」六项判据全 PASS、斜率 6544.2 码/V、偏差 −0.14 % 全在 `docs/硬件平台/ADC通道映射说明.md` §8.1，执行侧在 `docs/测试说明/专项验证/ADC前端注入验证流程.md`）；
+   - **删的是任务规划侧的行与结论块，不是证据本体**；被代码头注释指称的设计约束章节（§2~§4 那类）**原样保留**，只删已完成记录；
+   - 该行若当初是被「代码头注释按号引用」当例外保住的（实测 `App/task/adc_task.c` 的 v3.3 修订行按卡号当口径出处），必须**先把引用侧改成语义短语**，例外才成立撤销，并在规范里写明撤销理由（上一笔「完成即保留行」的例外就是这么随引用侧改动被撤掉的）；
+   - 删完逐行通读被改小节，报**行数变化**，不留孤立残句（实测 J7 dropped line 234 len=639、J13 闭环结论块 6 行删除并注明证据属主）。
+3. **自建带标签正则扫描脚本**——四条硬规矩，全是实测返工换来的：
+   - 脚本**落文件**（`ci-artifacts/scan_ka_refs.py`）再跑，**不用 bash heredoc**（heredoc 里的 `\s` 被多层引号咬坏：`SyntaxWarning: invalid escape sequence` + 语法错）；
+   - 正则**一律 raw 字符串**、汉字写 `\uXXXX`：`KA = r"\u5361"`。非 raw 串里 `"\b"` 会先被 Python 解成退格符（0x08）→ 正则**静默失配且不报错**；`"\s"` 只是警告还能跑，`"\b"` 是真错；
+   - **排除 `.git`**（连同 `.venv`、`ci-artifacts`、`__pycache__`、`node_modules`）——实测扫进 `.git/COMMIT_MSG_*.txt`，一堆 GBK 乱码历史被当成残留，越清越多；
+   - 报告**写 UTF-8 文件**（`ci-artifacts/ka_refs.txt`）再本地解析，别靠控制台输出（Windows 控制台按 GBK 渲染中文 = 乱码）；判乱码统计 `EF BF BD` 字节数，别信终端渲染。
+
+   ```python
+   # -*- coding: utf-8 -*-
+   """扫描中文前缀任务卡号与同期形似噪声号；报告写 UTF-8 文件。"""
+   import io, os, re
+   KA = r"\u5361"                                    # 卡
+   PATS = [("CARD_ANY", re.compile(KA + r"\s*[0-9]")),
+           ("KA0B",     re.compile(KA + r"\s*0b")),
+           ("KA12",     re.compile(KA + r"\s*12")),
+           ("M4",       re.compile(r"\bM4\b")),
+           ("M5",       re.compile(r"\bM5\b")),
+           ("M6",       re.compile(r"\bM6\b"))]
+   SKIP = {".git", ".venv", "ci-artifacts", "__pycache__", "node_modules"}
+   out = io.open("ci-artifacts/ka_refs.txt", "w", encoding="utf-8")
+   for root, dirs, names in os.walk("."):
+       dirs[:] = [d for d in dirs if d not in SKIP]
+       for n in names:
+           p = os.path.join(root, n)
+           try:
+               txt = io.open(p, encoding="utf-8", errors="ignore").read()
+           except OSError:
+               continue
+           for i, line in enumerate(txt.splitlines(), 1):
+               for tag, rx in PATS:
+                   if rx.search(line):
+                       out.write("===== %s\n" % p)   # 同一行可命中多标签 → 按标签分别计数
+                       out.write("%d [%s] %s\n" % (i, tag, line.strip()[:200]))
+   out.close()
+   ```
+   末尾打 `TOTAL_SITES / FILES / SCANNED / 各标签计数`；**带标签**才拆得开噪声（同一行可同时命中 `CARD_ANY` 与 `KA12`）。
+4. **该族与形似噪声号分开计数，各自给分母**：一遍扫描出 `TOTAL_SITES 420 FILES 85 SCANNED 1025`，必须再拆成**卡族 288 处 / 56 文件** 与 **里程碑噪声 132 处 / 44 文件**（`M4/M5/M6` 大片落在 `docs/芯片手册/` 参考手册与料号上下文里）。两套数字各自给分母——**「420 处待改」是错的**：把 132 处噪声算进清退范围就会去改芯片手册原文。噪声侧一律保持原样，是否清退等用户单独裁定，**不要顺手做**。
+5. **派单前写一份 spec 文件**（`ci-artifacts/card_retire_spec.md`），作为各道唯一口径来源，含五块：① 背景与**用户裁定原文**；② 逐号映射表（旧号形态 → 语义短语 → 属主出处）；③ 措辞规则（补短语时括号怎么降级、动不动字符串字面量、生成器归属、悬空引用怎么判）；④ 硬约束（BOM 原样补回、行尾由 `.gitattributes` 写死、冻结历史行与原始证据不回改、代码头注释引用的设计约束章节保留、带 BOM 文件名单）；⑤ 自检与交付格式（逐文件命中数、删了哪几行、残留数、门禁复跑结果）。`send_message` 只发路径 + 关键裁定，长中文正文不要整段塞进消息（一次串多条长消息会撑爆 120s，发出 1 条后 abort，剩余未发）。
+6. **逐处替换断言命中数**（同第 7 步的 `rep(tag, old, new, want)`），且 `old` 串**从原文取、不凭记忆敲**：本仓中文引号与 ASCII 双引号混用（实测某文档里的「中文引号」其实是 ASCII `"`），凭印象写 `old` 必 `got=0`；断言抛错后先 `git status --porcelain=v1 -- <文件>` 自证文件未被别道改动，再回读该行真身重跑。删行类改动单独记 tag 并打印删了几行、行号与原行长度。多道并行时同一文件常被别道改过：`edit` 报 `file changed since it was read` → 重新 `read` 再改；报 `ReplaceFileW EIO (Win32 1175)` → 先自证文件字节完好（BOM / CRLF / `EF BF BD` 三项）再重试同一笔，不要顺手改内容。
+7. **落地位置写死（这一族只有这几条兜）**：
+   - `docs/编号规范.md` **§4.1.1「已停发的族」表加一行**，三列齐全，第三列直写「⚠ **这一族从来没有机器面**：中文前缀不进任何编号语料（族 pattern 全是拉丁形态），而两道编号门禁已于 2026-10-28 / 29 退役 → 只有本表 + 归档换算表 + 评审三条兜；`id_aliases.json` 刻意不登记（没有机器读者，登记等于多一张没人核的表）」；
+   - `scripts/archive/id_gate/编号治理历史.md` **§9.3 逐号换算表**（旧号形态 → 语义短语 → 现行口径出处；本族实测 14 行 = 0、0b、1~12）+ 同篇 §9 批次段落（裁定原文与逐号结论都落在归档正文），**写明旧号永久作废、不得重新取走**；
+   - 表内**把形态写成「卡」+ 数字而不复述字面量**：规范本身是门禁语料，复述字面量会把「讲规则的文档」变成自己的引用站点；
+   - **同步叙述**：`AGENTS.md`「文档与图形」的销项条目、`docs/README.md`（例：`数据可信.md = 三项阻塞任务` → 两项）、`docs/任务规划/README.md`、`docs/任务规划/登记簿.md`——「剩余三项」这类旧口径实测归零；
+   - **与有识别面族的判别写进同一张表**：能被脚本按字面量匹配 → 走 `rename_ids.py` + 别名登记；匹配不到（中文前缀、纯散文号、圈号）→ 走规范换算表，**不登记别名**；
+   - 要机械化怎么办：得先给「中文前缀 + 数字」设计候选形态，属追溯机制改造，按 §7.3 单独开卡，**别夹在清退批里顺手做**。
+8. **替换后三道二次清洗**（缺一必留疤，全部实测过）：
+   ```bash
+   git grep -c -F '端子 / 子板变比确认' -- . ; git grep -c -F '端子/子板变比确认' -- .   # 先数各形态再归一
+   git grep -nE '卡[ ]*[0-9]' -- . ; echo "rc=$?"                                        # 裸跑读 rc；1 = 归零
+   ```
+   - **同句重复短语**：编号位置补上的语义短语与原句已有短语撞车 → 扫「同一行里同一短语出现 ≥2 次」（实测 12 行，如 `.pre-commit-config.yaml:401`「运行参数段（「数据可信」运行参数段交付）」、`App/algo/README.md:110`「遥测快照发布（L2 发布侧，「数据可信」遥测快照发布）」）→ 改法是**把括号里的引用降级**成不含该短语的写法（「道D 交付项」「波次」「该点 DoD 原句」），逐处断言命中 = 1，别删信息；
+   - **空格与引号形态归一**：同一语义短语可能有 `端子 / 子板变比确认` 与 `端子/子板变比确认` 两种形态 → **先 `git grep -c -F` 分别数**（实测带空格 8 处），再整文件归一，归一后复扫到 0（残留常藏在表格单元格里，逐行打印定位）；引号形态同理；
+   - **固定正则复扫**：`卡[ ]*[0-9]` 全仓无输出。⚠ 判 rc 时**不要把命令接在 `| head` 之后再读 `$?`**（那拿到的是 `head` 的 0，会把「还有残留」读成「已归零」）。
+9. **收尾复跑 + 清中间产物**：`check_ids.py`（plain 与 `--strict`）、`check_doc_links.py --all`、bom 与乱码两道（`pre-commit run bom-guard --files <改过的文件>`、`pre-commit run no-mojibake --files <改过的文件>`）、`git diff --check`；**纯注释/纯文档改动不算免编译**——仍跑一次 `/keil-build` 取「0 错误 0 警告」且 `Program Size` 与改前同数（**本回合真跑**，引用历史提交正文自报的四个数不算），受影响的主机组单测照跑。最后**删掉 spec 与全部扫描中间产物**，别往 `ci-artifacts/` 再堆 log/txt。
@@ -1,7 +1,7 @@
 ---
 name: keil-build
-description: Keil MDK-ARM 命令行编译闭环（自带独立脚本 keil_build.py，纯标准库，拷到任何 Keil 项目即用）：UV4 -b 构建 → "0 错误 0 警告"判定 → build_log 定位报错。封装入口约定、退出码判读、UV4 改写工程文件的入库陷阱。
-whenToUse: 需要编译 Keil MDK 工程、验证代码改动是否 0 错误 0 警告、或解读 UV4 构建日志时。
+description: "Keil MDK-ARM 命令行编译闭环（自带独立脚本 keil_build.py，纯标准库，拷到任何 Keil 项目即用），覆盖 UV4 -b 构建、「0 错误 0 警告」判定、build_log 定位报错、PowerShell 与 bash 两种调用形态及各自的 exit 2 归属、退出码与 build 锁持有者名判读（含插件树的 pw: 前缀）、exit 2 时 UV4.exe 的候选路径探测与单次调用 env 注入闭环、UV4 改写工程文件的入库陷阱、构建副产物「%SystemDrive% 字面量垃圾目录」的取证、清理与入库排除。"
+whenToUse: "需要编译 Keil MDK 工程、跑 /keil-build 验证代码改动（只改 .c 注释也算改动）是否「0 错误 0 警告」、/keil-build 报 BUILD_ENV_ERROR 与 UV4.exe not found（退出码 2；DSH 会话看不见用户级 DTU_KEIL_UV4）、解读 UV4 构建日志、退出码 2/4 或 build 锁持有者名（含 pw: 前缀），在 bash / ops_bash 里执行 PowerShell 形态的编译命令行报 syntax error near unexpected token，或构建后 git status 冒出 %SystemDrive% 目录时。"
 ---

 # keil-build — Keil 命令行编译（独立可运行 skill）
@@ -10,21 +10,82 @@ whenToUse: 需要编译 Keil MDK 工程、验证代码改动是否 0 错误 0
 （纯标准库，任意 python3；拷整个 skill 目录到别的 Keil 项目即可用，不依赖仓库脚本）。

 ```powershell
-# cwd = 项目根目录
+# cwd = 项目根目录；PowerShell 形态（AGENTS「构建与验证」的编译入口）
 & $PY ".dsh\skills\keil-build\scripts\keil_build.py"
 # 覆盖：--project X.uvprojx --uv4 UV4.exe --target 名字 --log 路径 --timeout 600
 ```

-解析顺序（命令行 > 项目档案 `.serialtest/config.json` > 环境 > 探测）：
-工程 `uvprojx`（档案缺省时自动搜 cwd 下唯一 `*.uvprojx`）；UV4 `uv4` >
-`$DSH_KEIL_UV4` > `$DTU_KEIL_UV4` > PATH（**显式设了但路径无效 = 立即报错，不静默回退**）。
-退出码：`0`=PASS(0错0警) / `1`=构建失败（打印报错行）/ **`2`=环境错误**（UV4 找不到或
-路径无效、工程找不到、档案解析失败）/ `3`=用法错误 / `4`=build 锁被占用（并发 `-b` 不可行）。
+⚠ **改本文件 frontmatter 要么整值加双引号，要么一个 ASCII 冒号都别写**（2026-10-30 这份就因此整份加载失败）。
+DSH 用 `yaml` 包的 `parse()` 读 frontmatter（`@deepseek-ai/dsh-skill-filesystem` 的 `parseFrontmatter()`），
+plain scalar 里出现 **ASCII「冒号 + 空格」**（例如把报错原文 `BUILD_ENV_ERROR: UV4.exe not found` 或
+`pw: 前缀` 直接写进 description）就报 `Nested mappings are not allowed in compact mappings at line 2,
+column 14` → **技能整份不加载**（`skill()` 读不到、也不进技能目录）。**`js-yaml` 能吃下去** ——
+拿它自检会假绿，必须用 DSH 自带的那个解析器验。另 — 值首字符不能是 `%`（directive indicator）或 `&`
+（anchor），双引号里的 `%SystemDrive%` 之类不受影响。落盘后**让 DSH 真加载一次**再收口。

-> 2026-10-12 修正：旧实现把环境错误写成 `raise SystemExit("...")` → 实际退出码是 **1**，
-> 而用法错误由 argparse 抛 `SystemExit(2)` → 恰好占了"环境错误"的位置。故 `AGENTS.md` /
-> `new-machine-setup` 里写的"报 exit 2 = 环境问题"当时**不成立**。现按文档口径改正：
-> 环境错误 → 2（`BuildEnvError`），用法错误 → 3（覆盖 argparse 的 `error()`）。
+## 调用形态：先认执行器是哪个 shell（2026-10-26 实测）
+
+- 同一条编译命令，PowerShell 与 bash 是两种写法：bash 侧要去掉前导 & 并把路径改正斜杠（照抄 AGENTS 的 PowerShell 形态进 ops_bash 会语法错秒退 exit 2）
+- ⚠ 那个 exit 2 不是脚本的环境错误 2：stderr 含 syntax error near unexpected token = 写法问题，换 bash 形态重跑，别去查 DTU_KEIL_UV4、别当环境错误排障
+- 后台跑（run_in_background: true）要自己收码，且别把脚本接进管道：实测 $? 取到的是 tail 的码（恒 0）；要看报错行就单独 grep MDK-ARM/build_log.txt
+- 解析顺序：命令行 > 项目档案 .serialtest/config.json > 环境 > 探测；UV4 显式设了但路径无效 = 立即报错，不静默回退
+- 退出码 0=PASS(0错0警) / 1=构建失败 / 2=环境错误 / 3=用法 / 4=build 锁被占用；2026-10-12 修正过 2 与 3 的归属，该篇末尾记了前后口径
+- **bash / `ops_bash` 侧「构建到底过没过」的一次自查**（2026-10-26 实测口径）：先 `cd` 到仓库根（或该 worktree 根），跑 `.venv/Scripts/python.exe .dsh/skills/keil-build/scripts/keil_build.py; echo BUILD_RC=$?` —— 正斜杠、**无前导 `&`**，退出码归 python、不归 bash；再单独读日志计数 `grep -a -E "Error\(s\)|error:|Warning\(s\)" MDK-ARM/build_log.txt`。报结论要三样齐 —— **`BUILD_RC=0` + `UV4_RC: 0` + `BUILD_OK: 0 errors, 0 warnings`**（脚本自己判「无 `error:` 行 且 尾行含 `0 Error(s), 0 Warning(s)`」）；bash 吐的 `syntax error near unexpected token` **既不是构建通过也不是构建失败**，那是写法问题，别拿它当构建结论报。
+> 本节全文（逐字搬移、未改写，含命令与实测数字）→ [executor-shell-forms.md](reference/executor-shell-forms.md)。动手前先读那篇。
+
+## exit 2 实战闭环：`UV4.exe not found` 的探测 → 注入 → 复核（2026-10-30 实测）
+
+**先定性，别动源码**：脚本报
+`BUILD_ENV_ERROR: UV4.exe not found (--uv4 / config 'uv4' / $DSH_KEIL_UV4 / $DTU_KEIL_UV4 / PATH)`
+且**退出码 2** = **环境错，不是构建失败**——本次 **UV4 根本没启动、`MDK-ARM/build_log.txt` 也没被改写**，
+日志里看到的是上一次的。此时去改 `.c`/`.h` 或怀疑代码，就是把环境问题当编译问题排。
+（会话为什么看不见：DSH 会话的 shell 由常驻服务派生，**服务启动之后**设的用户级变量不会自动进来；
+`run_code` 起的 Node 进程 `process.env` 干脆是空的——AGENTS.md「会话不继承用户级变量」同记此坑。
+所以**变量"已设但本会话看不见"是常态**，不是用户没设。）
+
+1. **探测候选安装路径**（逐个 `fs.existsSync` / `test -f`，命中即取绝对路径）——
+   `C:/Keil_v5/UV4/UV4.exe`、`C:/Keil/UV4/UV4.exe`、`D:/Keil_v5/UV4/UV4.exe`、`D:/Keil/UV4/UV4.exe`、
+   `C:/Program Files/Keil_v5/UV4/UV4.exe`、`D:/Program Files/Keil_v5/UV4/UV4.exe`
+   （2026-10-30 实测只命中 `C:/Keil_v5/UV4/UV4.exe`，其余五个都不存在）。
+   ```bash
+   for p in 'C:/Keil_v5/UV4/UV4.exe' 'C:/Keil/UV4/UV4.exe' 'D:/Keil_v5/UV4/UV4.exe' \
+            'D:/Keil/UV4/UV4.exe' 'C:/Program Files/Keil_v5/UV4/UV4.exe' 'D:/Program Files/Keil_v5/UV4/UV4.exe'; do
+     [ -f "$p" ] && echo "HIT $p"; done
+   ```
+2. **读用户级来源确认"值本来就对"**（同一轮里顺手做掉，别只靠猜路径）：
+   bash / Node 侧 `reg query HKCU\Environment`（整表打出来再找 `DTU_KEIL_UV4` / `DSH_KEIL_UV4`），
+   PowerShell 侧 `[Environment]::GetEnvironmentVariable('DTU_KEIL_UV4','User')`。
+   有值 → 直接用它；没值/值指向旧目录 → 用第 1 步的命中路径。
+   ⚠ **不替用户改全局**：不要 `setx`、不要 `SetEnvironmentVariable(...,'User')`——那是用户自己在真终端里
+   做的事（`docs/环境与部署/本地工具路径环境变量方案.md`）；本闭环只解决"这一次构建怎么跑起来"，
+   报告里也必须这么写。
+3. **只给这一次调用注入**再重跑（两种等价形态，二选一）：
+   ```js
+   // run_code：options.env 是**整体替换**，所以要连 SystemRoot / Path / USERPROFILE 一起给
+   const { execSync } = await import('node:child_process');
+   execSync('".venv/Scripts/python.exe" .dsh/skills/keil-build/scripts/keil_build.py', {
+     cwd: MAIN, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024,
+     env: { SystemRoot: 'C:\\Windows', Path: 'C:\\Windows;C:\\Windows\\System32',
+            USERPROFILE: 'C:\\Users\\<你>', DTU_KEIL_UV4: 'C:\\Keil_v5\\UV4\\UV4.exe' } });
+   ```
+   - bash / `ops_bash` 侧的等价写法 = 显式参数 `--uv4 'C:\Keil_v5\UV4\UV4.exe'`（值含空格要整体加引号）。
+   - `run_code` 的 `timeoutMs` 给足：注入后这次构建实测 **10 s** 跑完，但首次冷构建更长（我给的 500000）。
+   - **别顺手加 `--no-lock`**：注入重跑时锁链照旧（`LOCK: 已获取 build 锁（task=build-cli）` → `已释放锁`）。
+4. **复核口径**（三样齐了才算真跑过，缺一样就是没构建）：脚本回显
+   `UV4: <绝对路径>  (<来源>)`（来源随注入方式变：`$DTU_KEIL_UV4` 或 `--uv4`）→
+   `UV4_RC: 0` → `BUILD_OK: 0 errors, 0 warnings`，且**外层退出码 0**（自己包 execSync 就显式把码打出来，
+   别接管道，见「调用形态」）。报告里写清"本次注入 + 来源"，**不得声称已永久设置系统/用户环境变量**。
+
+- ⚠ 注入的若是**注册表里那个陈旧值**，会撞同族的另一种 2：
+  `BUILD_ENV_ERROR: $DTU_KEIL_UV4 is set but not a file: … (fix the value; no silent fallback)`
+  —— 值在但指向旧盘符/旧目录名（本仓踩过 `D:\Code\DTU 程序\…` 搬迁）。脚本**刻意不静默回退**，
+  回到第 1 步用探测命中的路径覆盖它，别去猜目录、更别改脚本让它"猜 C 盘"（设计上明确禁止从旧路径猜）。
+- ⚠ 本闭环只回答"UV4 在哪儿"，**不回答"调用写法对不对"**：从 bash 侧照抄 PowerShell 的 `&` 也是 exit 2，
+  但 stderr 是 `syntax error near unexpected token`（见「调用形态」）。**先看 stderr 再决定排障方向**，
+  两种 2 的处置完全不同。
+- **改 `.c` 注释（哪怕只改一行中文注释）也必须跑完这道构建验证**：2026-10-30 的实测就是
+  「改注释 → `/keil-build` → 吃 rc=2 → 探测+注入 → 10 s 通过」。注释类坑（BOM 被剥 → `#870-D`、
+  注释里写 `**` 路径 → 9-D）只在**重编译那个 TU 时**才暴露，"以前 0 警告"不代表安全。

 ## build 锁：脚本自持自释（2026-10-12）

@@ -35,7 +96,7 @@ Agent 手工 `lock acquire build` 后忘了 `release`，锁要挂到 TTL 才被

 | 开关 | 作用 |
 |---|---|
-| `--lock-task <ID>` | 持有者名。默认 `$DTU_TASK_ID` → 从 cwd 的 `_wt/<ID>-<slug>/` 反推 `<ID>` → `build-cli` |
+| `--lock-task <ID>` | 持有者名。默认 `$DTU_TASK_ID` → 从 cwd 反推：`_wt/<ID>-<slug>/` → `<ID>`（`@task` 那批）；`.dsh-worktrees/worktree/<name>/` → `pw:<name>`（DSH worktree **插件**建的树，`plugin_tree_owner()`）→ 都没有才落 `build-cli` |
 | `--lock-wait <N>` | 锁被占时等待 N 秒（默认 0 = 立即失败，退出码 4） |
 | `--no-lock` | 完全不加锁（危险：并发 `-b` 互相干扰） |
 | `DTU_LOCK_HELD=build` | 环境变量：**调用方已持锁**时设它，本脚本跳过自持自释（`task-worktree done` 的门禁即如此用） |
@@ -46,39 +107,68 @@ Agent 手工 `lock acquire build` 后忘了 `release`，锁要挂到 TTL 才被
 - 锁工具 = 兄弟 skill `task-worktree/scripts/task_worktree.py`；**找不到则降级为不加锁
  并告警**（保持本 skill 可独立搬运）。
 - ⚠ 从 `_wt/<ID>-<slug>/` 反推持有者名，意味着"手工 `lock acquire build --task <ID>`
-  后再跑 `@build`"仍**幂等**（同名即视为自己持有），不会自我死锁。
+  后再跑 `/keil-build`"仍**幂等**（同名即视为自己持有），不会自我死锁。
+- **退出码 4 的持有者名带 `pw:`（如 `pw:refactor-logging`）= 插件在 `.dsh-worktrees/worktree/<name>/` 里跑的构建占着 UV4，不是某个 `@task` 任务 ID**：
+  插件树**没有台账**，别拿它去 `lock release <ID>`（释放不掉别人的锁）、更别去杀 UV4 进程。正解 =
+  等那次构建自己 `finally` 释放（自持自释；崩溃则按自报 TTL 兜底），或本次加 `--lock-wait <N>` 排队；
+  想知道是哪棵树的谁：`"$PY" "$TW" plugin list`（缺联接再 `plugin adopt <name>`）→ 细节归
+  `task-worktree` skill F 节（插件桥）。
 - **只 build 锁自动；`bench` 锁仍须 Agent 手工持**（它是**会话作用域**，跨
-  烧录→`@test`→探针多条命令，逐命令自动释放会让别的任务插进来扰动设备）。
+  烧录→`/serial-boot-test`→探针多条命令，逐命令自动释放会让别的任务插进来扰动设备）。
+
+## 构建副产物：`%SystemDrive%` 字面量垃圾目录（2026-10-26 两次复发 → 2026-10-28 定性并加守卫）
+
+- 症状：/keil-build（或 check_font_charset.py 这类 fontTools 工具）跑完，仓库根冒出未跟踪的 %SystemDrive%/ProgramData/…/Caches/（几个 .db，约 1 MB）= 本机缓存被按字面量原地复刻
+- 根因（2026-10-28 实测）：run_code 的 Node 进程 process.env 是空的 → known-folder 可展开串展不开变成相对路径 → 按当前目录建在仓库根；同族还会冒出 %USERPROFILE%/AppData/Local/Temp
+- 清理有安全阀：⚠ 绝不用 cmd / PowerShell 直接删（rd /s /q %SystemDrive% 会被展开成 C:）；只用 bash 引号形态，先 find '%SystemDrive%' -type l 预检再 rm -rf --。它是工具副产物，直接删、别 stash、更别提交
+- 两层防线均已落地可核验：.gitignore:167 挡入库 + 脚本 harden_windows_env() 回填环境变量、check_percent_literal_junk() 只告警不自动删；守卫是兜底不是许可，/keil-build 仍要走 ops_bash / PowerShell
+- **取证在前，处置在后**（2026-10-28 实测，别一上来 `rm -rf`）：`ls -laR -- "%SystemDrive%"` + `du -sh "%SystemDrive%"` 枚举内容与体积，再 `find "%SystemDrive%" -printf "%T@ %p\n" | sort -rn | head -3` 看**最新 mtime** —— 最近几分钟还在被重建 = 环境仍残缺（脚本会打 `WARN: ENV_SPARSE:`），先断源头（换 `ops_bash`/PowerShell 跑，或按「UV4.exe not found」一节把 `env` 传全）再删，否则删完立刻长回来；顺带确认仓库里只有这一个该名字的东西（`find . -maxdepth 1 -name "*SystemDrive*"`）
+- **要留证据就搬走、别就地删** —— ⚠ **shell 的 `mv` 搬不动它**：`mv "%SystemDrive%/..."` 报 `cannot stat`（含 `%` 的目录名被当变量展开 / 吃掉，路径根本对不上）。改用 Python 遍历搬到**仓库外**的临时目录 —— `os.walk` + `shutil.move`（或 `glob.glob("%SystemDrive%/*")` 逐个 `shutil.move` 到 `os.environ["TEMP"]` 下）；确认是纯工具副产物（几个 `.db` 缓存）才 `rm -rf --`
+- **入库排除要落成条目并核验**：补 `.gitignore` 前先 `grep -n "SystemDrive" .gitignore` 定位精确原文行再 Edit（凭记忆写 `old_string` 必不匹配，2026-10-28 踩过）。本仓条目 = `.gitignore:167` 的 `%SystemDrive%/`，上面那段注释就是复发证据（新增条目也照此**写明第几次复发、谁造的**）。收尾核验 —— `git status --porcelain` 里该目录零命中（且别的未跟踪产物一个没少）、`git check-ignore -v` 落在那一行、`git add -A --dry-run` 零命中；**绝不提交**（把本机缓存塞进历史）
+> 本节全文（逐字搬移、未改写，含命令与实测数字）→ [systemdrive-junk-dir.md](reference/systemdrive-junk-dir.md)。动手前先读那篇。

 ## 本仓库

-**`@build` = 本 skill**（2026-10-10 起为仓库文档口径）：在仓库根目录跑
-`& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py`。
-判定口径（与原 `MDK-ARM/build.bat` 同款；该文件已于 2026-10-10 删除，本 skill 即 `@build`）：
+**本 skill 的调用名 = `/keil-build`**（**技能调用名不是 shell 命令**——原样敲进终端是 command not found / syntax error，可执行形态永远是下面这条命令行）：在仓库根目录跑
+`& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py`——
+**bash / `ops_bash` 下要写成 `'.venv/Scripts/python.exe' .dsh/skills/keil-build/scripts/keil_build.py`**
+（原因见「调用形态」）。
+判定口径（与原 `MDK-ARM/build.bat` 同款；该文件已于 2026-10-10 删除，本 skill 即编译入口）：
 先删旧日志 → `-b -j0 -o` → 无 `error:` 且含 `0 Error(s), 0 Warning(s)`。
 本 skill 另有超时保护、UV4 多级解析链（含 PATH 兜底）、失败只打报错行。
-环境变量 `DTU_KEIL_UV4`（用户级，指向 UV4.exe）。
+环境变量 `DTU_KEIL_UV4`（用户级，指向 UV4.exe）——注意**它设了不等于本会话能看见**，仍报退出码 2 时走「exit 2 实战闭环」那一节，别先去找用户。

 ## 铁律与陷阱（实测教训）

 - **任何代码改动后必须先编译验证（0 错误 0 警告）再谈烧录/提交**——编译不过就进
-  硬件闭环只会把编译错误伪装成运行问题。
- **警告也算失败**：判 PASS 只认退出码 0，别只看"有没有 error:"。
+  硬件闭环只会把编译错误伪装成运行问题。**只改 `.c` 里一行中文注释也算改动**（2026-10-30 实测：
+  改注释 → `/keil-build` → 环境错 → 探测注入 → 10 s 通过）：BOM/嵌套注释这类坑只在重编译那个 TU 时才暴露。
+- **警告也算失败**：判 PASS 只认退出码 0，别只看"有没有 error:"（取退出码的管道陷阱见「调用形态」）。
 - **`MDK-ARM/*.uvprojx` 每次构建后被 UV4 自动改写，改动一律不入库**：UV4 会把工程
  XML 归一化成本机风格（`<Tag />` → `<Tag></Tag>`、XML 声明加 `standalone="no"`）并把
  `PackID` 降到**本机装的 DFP 版本**（属降级——提交后会把别人的 Pack 版本一起改掉）。
  判断：`git diff` 里只见 XML 格式/`PackID` 差异而**无源文件挂载增删** →
  `git checkout -- <uvprojx>` 丢弃；只有真的增删了源文件（grep 文件名计数变化）才提交。
  同目录的 `*.uvoptx` / `*.uvguix.*` 是 IDE 个人设置，已在 `.gitignore` 里，不会露出来。
+- **构建后仓库根冒出 `%SystemDrive%/`** = UV4 / 字体工具在残缺环境（缺 `SystemDrive`、`ProgramData`）
+  里按**未展开的 known-folder 字面量**建出来的**相对路径**目录，不是任何人在飞的改动：
+  `rm -rf -- '%SystemDrive%'`（bash 引号形态）删掉即可，**严禁 `rd /s /q %SystemDrive%`——cmd 会把它
+  展开成 `C:`**；`.gitignore` 已兜住 + 脚本已加 `ENV_SPARSE`/`JUNK_DIR` 守卫 → 见「构建副产物」一节。
 - 报错定位读日志别只看终端回显：本仓库 = `MDK-ARM\build_log.txt`。
- **exit 2 先分清"真没设"还是"会话没继承"**（2026-10-10 实测）：agent 的 shell 由
-  常驻服务派生，服务启动**之后**设置的用户级环境变量不会自动进来。查
-  `[Environment]::GetEnvironmentVariable('DTU_KEIL_UV4','User')`，有值就
-  `$env:DTU_KEIL_UV4 = <该值>` 注入本会话再跑，别急着让用户去设。
+- **exit 2 先分三种再动手**（2026-10-10 / 2026-10-26 / 2026-10-30 实测）：① **bash 语法错**——stderr 有
+  `syntax error near unexpected token`，是把 PowerShell 形态丢进了 `ops_bash`，换写法即可；
+  ② **真没设** `DTU_KEIL_UV4`；③ **已设但本会话看不见**（agent 的 shell 由常驻服务派生，服务启动**之后**
+  设的用户级变量不会进来；`run_code` 的 `process.env` 直接是空的）。
+  ②③ 一律走 **「exit 2 实战闭环」** 那一节：探测候选路径 + 读 `HKCU\Environment`，
+  再**只往那一次调用**的 env / `--uv4` 里注入命中路径重跑——别急着让用户去设，也别替他改全局。
 - 编码类报错（`#870-D: invalid multibyte character sequence` 等）先怀疑源文件
  BOM/编码被改写，而不是代码本身（见仓库 AGENTS.md 编码铁律）。

 ## 与其它 skill 的衔接

+- **build 锁的对面是谁**（`BUILD_LOCK_BUSY`、退出码 4、`pw:<name>` 插件树、`@task plugin list` / `plugin adopt`、`_wt/` 台账与合并回收）归 `task-worktree` skill（F 节 = DSH worktree 插件桥）；换机/新克隆时 `DTU_*` 工具路径变量的设立与「会话不继承」坑 = `new-machine-setup` skill。
 - 烧录/回读 = `stlink-flash` skill；串口闭环 = `serial-boot-test` skill
  （其档案 `flash_cmd`/`readback_cmd` 即 stlink-flash 的入口命令）。
+- 收尾固定链（2026-10-26 实证）：`/keil-build` → `scripts/ram_baseline.py --update` →
+  体积门禁盖戳 → 内存数字回填与 `--scan` → 复跑 `ci_local` 静态段，
+  直到钩子全绿且 0 错误 0 警告（RAM/栈口径见 `mem-budget` skill）。
@@ -0,0 +1,43 @@
+# 调用形态：先认执行器是哪个 shell（2026-10-26 实测）（自 SKILL.md 外置）
+
+> 本文由 keil-build 的 SKILL.md「调用形态：先认执行器是哪个 shell（2026-10-26 实测）」一节逐字外置而来（渐进展开：主文件只留索引与指针）。步骤号沿用原文，未重编。
+
+同一条编译命令，**PowerShell 与 bash 是两种写法**；`ops_bash` / `run_code` 起的是
+`/usr/bin/bash -c`，**不认 PowerShell 形态**，照抄仓库 `AGENTS.md` 会直接语法错退出。
+
+| 执行器 | 正确写法（cwd = 仓库根） |
+|---|---|
+| PowerShell | `& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py` |
+| bash（`ops_bash`） | `'.venv/Scripts/python.exe' .dsh/skills/keil-build/scripts/keil_build.py` |
+
+- bash 侧**去掉前导 `&`**（bash 里 `&` 是"丢后台"，不是调用操作符）、**路径改正斜杠**
+  （`\Scripts\python.exe` 的反斜杠在 bash 是转义，路径根本解析不出来）。
+- 实测（step 41→42）：把 PowerShell 形态丢进 `ops_bash` 后台任务 → 任务**秒退**、
+  `exit 2`，stderr 只有这一行：
+
+```text
+/usr/bin/bash: -c: line 1: syntax error near unexpected token `&'
+```
+
+- ⚠ **这个 2 不是脚本的环境错误 2**：脚本自己报环境错误会打出 `BuildEnvError` /
+  中文诊断（UV4 找不到、工程找不到、档案解析失败），而语法错**连解释器都没启动**，
+  `MDK-ARM/build_log.txt` 不会被改写。判据：stderr 含 `syntax error near unexpected token`
+  = 写法问题 → 换 bash 形态重跑，**别去查 `DTU_KEIL_UV4`、别当环境错误排障**。
+- 后台跑（`run_in_background: true`）时要自己收码，且**别把脚本接进管道**：
+  `'.venv/Scripts/python.exe' .dsh/skills/keil-build/scripts/keil_build.py; rc=$?; echo RC=$rc`。
+  实测 `脚本 | tail -6; echo RC=$?` 里的 `$?` 是 `tail` 的退出码（恒 0），
+  拿它当 PASS/FAIL 会永远"绿"；`set -o pipefail` 能透出非零码，但尾巴上挂的 `grep`
+  无匹配时同样报 1，也不可信。要看报错行就单独 grep 日志：
+  `grep -a -E 'Error|error:|Warning' MDK-ARM/build_log.txt`。
+
+解析顺序（命令行 > 项目档案 `.serialtest/config.json` > 环境 > 探测）：
+工程 `uvprojx`（档案缺省时自动搜 cwd 下唯一 `*.uvprojx`）；UV4 `uv4` >
+`$DSH_KEIL_UV4` > `$DTU_KEIL_UV4` > PATH（**显式设了但路径无效 = 立即报错，不静默回退**）。
+退出码：`0`=PASS(0错0警) / `1`=构建失败（打印报错行）/ **`2`=环境错误**（UV4 找不到或
+路径无效、工程找不到、档案解析失败）/ `3`=用法错误 / `4`=build 锁被占用（并发 `-b` 不可行）。
+**收到 2 先确认它是脚本打的还是 shell 语法错打的**（见上节），再走"环境错误"排障。
+
+> 2026-10-12 修正：旧实现把环境错误写成 `raise SystemExit("...")` → 实际退出码是 **1**，
+> 而用法错误由 argparse 抛 `SystemExit(2)` → 恰好占了"环境错误"的位置。故 `AGENTS.md` /
+> `new-machine-setup` 里写的"报 exit 2 = 环境问题"当时**不成立**。现按文档口径改正：
+> 环境错误 → 2（`BuildEnvError`），用法错误 → 3（覆盖 argparse 的 `error()`）。
@@ -0,0 +1,44 @@
+# 构建副产物：`%SystemDrive%` 字面量垃圾目录（2026-10-26 两次复发 → 2026-10-28 定性并加守卫）（自 SKILL.md 外置）
+
+> 本文由 keil-build 的 SKILL.md「构建副产物：`%SystemDrive%` 字面量垃圾目录（2026-10-26 两次复发 → 2026-10-28 定性并加守卫）」一节逐字外置而来（渐进展开：主文件只留索引与指针）。步骤号沿用原文，未重编。
+
+**症状**：`/keil-build`（或 `scripts/check_font_charset.py` 这类 fontTools 字体工具）跑完，仓库根
+冒出未跟踪目录 `%SystemDrive%/ProgramData/Microsoft/Windows/Caches/`，里面是几个 `.db`
+（`cversions.2.db` + `{6AF0698E-…}` 图标缓存 + `{DDF571F2-…}` 字体缓存，合计约 1 MB）——
+就是本机 `C:\ProgramData\Microsoft\Windows\Caches` 那份缓存被**按字面量原地复刻**了一份。
+
+**根因（2026-10-28 实测）**：Windows 的 known-folder 路径在注册表里是**可展开串**；展开不了，
+它就变成一个**相对路径**，于是按「当前目录」（= 仓库根）建出来。三条现场证据：
+
+```bash
+reg.exe query HKCU\Environment     # 本机 TMP/TEMP = REG_EXPAND_SZ %USERPROFILE%\AppData\Local\Temp
+env | wc -l                        # ops_bash 里 = 74（完整环境）
+node -e "console.log(Object.keys(process.env).length)"   # run_code 里 = 0（空环境！）
+```
+
+`run_code` 的 Node 进程 `process.env` 是**空的**，从它里面 `spawn` 出去的 UV4 / 字体脚本就拿不到
+`SystemDrive`/`ProgramData`/`ALLUSERSPROFILE`；实测 `os.path.expandvars("%SystemDrive%\ProgramData")`
+原样返回、且 `os.path.isabs()` = **False** → 目录就长在工作区里（同族还会冒出
+`%USERPROFILE%/AppData/Local/Temp`）。**正解不是「让用户去设环境变量」**，是别在残缺环境里跑构建（见第 2 条）。
+
+**清理（有安全阀）**：
+
+- ⚠ **绝不用 cmd / PowerShell 直接删**：`rd /s /q %SystemDrive%` 会被 cmd **展开成 `C:`**——
+  等于对整块系统盘下令递归强删且不带确认。
+- ✅ 只用 bash 引号形态（`%` 在 bash 里没有特殊含义）：先 `find '%SystemDrive%' -type l` 确认不是
+  reparse point / 符号链接，再 `rm -rf -- '%SystemDrive%'`；或 Node
+  `fs.rmSync("%SystemDrive%", { recursive: true, force: true })`。
+- 它是**工具副产物**，不是谁在飞的改动——直接删，别 stash、更别提交（提交它 = 把本机缓存塞进历史）。
+
+**让它不再污染工作区（两层，均已落地、可核验）**：
+
+1. **进不了版本库**：`.gitignore:167` 的 `%SystemDrive%/`（2026-10-26 入库，注释里就写着复发证据）。
+   核验三步（2026-10-28 复跑全绿）：造一份同名目录 + `.db` → `git status --porcelain` 零命中 →
+   `git check-ignore -v <路径>` 落在 `.gitignore:167:%SystemDrive%/` → `git add -A --dry-run` 零暂存。
+2. **根本别再长出来**：本 skill 脚本 2026-10-28 起在拉起 UV4 前跑 `harden_windows_env()`——回填
+   `SystemDrive`/`SystemRoot`/`windir`/`ComSpec`/`ProgramData`/`ALLUSERSPROFILE`/`ProgramFiles` 与
+   `USERPROFILE`/`APPDATA`/`LOCALAPPDATA`/`TMP`/`TEMP`，就地展开环境里未展开的 `%VAR%` 字面量，
+   并把 `TMP`/`TEMP` 指到真实目录；命中即打 `WARN: ENV_SPARSE:`。构建后再跑
+   `check_percent_literal_junk()`，看到 `%SystemDrive%`/`%USERPROFILE%` 一类字面量目录就打
+   `WARN: JUNK_DIR:`（**只告警不自动删**——删目录不该由构建脚本代劳）。守卫是兜底不是许可：
+   **`/keil-build` 仍要走 `ops_bash` / PowerShell（继承完整环境）**，非在 Node 里 spawn 就把 `env` 传全。
@@ -14,7 +14,7 @@
         （环境变量**显式设了但路径无效 = 立即报错，不静默回退**）
  日志   --log > 档案 "build_log" > <工程目录>\\build_log.txt

-判定口径（实测教训沉淀；原仓库 MDK-ARM/build.bat 已删除，本脚本即 @build）:
+判定口径（实测教训沉淀；原仓库 MDK-ARM/build.bat 已删除，本脚本即仓库编译入口）:
  1. 先删旧日志——UV4 -o 只在真跑了构建才写日志，残留旧日志会被当成本次结果
  2. UV4 单实例：IDE 开着时 -b 可能被转发给 IDE（退出码丢失）→ 只 WARN 不杀进程
  3. PASS = 日志存在 + 无 "error:"（大小写不敏感）+ 含 "0 Error(s), 0 Warning(s)"
@@ -64,6 +64,117 @@ class BuildEnvError(Exception):
    """环境/前置错误（UV4 或工程找不到、档案解析失败）→ 退出码 2。"""


+def _expand_deep(v):
+    """展开未展开的 REG_EXPAND_SZ 字面量（百分号形态的变量引用），最多四轮，防自指死循环。"""
+    for _ in range(4):
+        nv = os.path.expandvars(v)
+        if nv == v:
+            break
+        v = nv
+    return v
+
+
+def harden_windows_env():
+    """拉起 UV4 前补齐/展开子进程环境——堵住仓库根的「%SystemDrive%/」字面量垃圾目录。
+
+    Windows 的 known-folder 路径在注册表里是**可展开串**：ProgramData 的真实取值来自
+    「%SystemDrive%/ProgramData/…」，本机 HKCU Environment 里的 TMP/TEMP 实测就是未展开的
+    「%USERPROFILE%/AppData/Local/Temp」。父进程环境残缺时（典型：Agent 在 Node
+    child_process / run_code 里 spawn，子进程继承到一个**空环境**，SystemDrive、ProgramData、
+    USERPROFILE 一个都没有）这些串展不开、留在原地就成了**相对路径**，于是 UV4 / fontTools 类
+    字体工具按它在**当前目录**（= 仓库根）建出
+    「%SystemDrive%/ProgramData/Microsoft/Windows/Caches/*.db」（图标+字体缓存库，约 1 MB），
+    污染 git status（2026-10-26 同一会话两次复发；仓库 .gitignore 已入库兜住它，但正解是
+    **根本别让它长出来**）。故此处回填 + 展开，并打可定位的 WARN：ENV_SPARSE。
+    """
+    if os.name != "nt":
+        return
+    filled, expanded = [], []
+
+    for key, val in list(os.environ.items()):
+        if isinstance(val, str) and "%" in val:
+            new = _expand_deep(val)
+            if new != val and "%" not in new:
+                os.environ[key] = new
+                expanded.append(key)
+
+    root = os.environ.get("SystemRoot") or os.environ.get("windir") or ""
+    root = _expand_deep(root)
+    if "%" in root or (root and not os.path.isdir(root)):
+        root = os.path.join(os.path.abspath(os.sep), "Windows")   # 兜底：当前盘根下的 Windows 目录
+    drive = os.path.splitdrive(root)[0] or os.path.abspath(os.sep)[:2]
+    drive = drive.rstrip(os.sep) or "C:"
+    sysroot = drive + os.sep
+    user = _expand_deep(os.environ.get("USERPROFILE") or "")
+    if "%" in user:
+        user = ""
+    defaults = {
+        "SystemDrive": drive,
+        "SystemRoot": root,
+        "windir": root,
+        "ComSpec": os.path.join(root, "System32", "cmd.exe"),
+        "ProgramData": os.path.join(sysroot, "ProgramData"),
+        "ALLUSERSPROFILE": os.path.join(sysroot, "ProgramData"),
+        "ProgramFiles": os.path.join(sysroot, "Program Files"),
+    }
+    if not user:
+        guess = _expand_deep(os.path.expanduser("~"))
+        if not guess.startswith("~") and "%" not in guess:
+            user = guess
+    if user:
+        defaults["USERPROFILE"] = user
+        defaults["APPDATA"] = os.path.join(user, "AppData", "Roaming")
+        defaults["LOCALAPPDATA"] = os.path.join(user, "AppData", "Local")
+        defaults["TMP"] = os.path.join(user, "AppData", "Local", "Temp")
+        defaults["TEMP"] = defaults["TMP"]
+    for key, val in defaults.items():
+        if not os.environ.get(key):
+            os.environ[key] = val
+            filled.append(key)
+
+    # TMP/TEMP 必须落在真实目录：留未展开值 = 工具按字面量在当前目录建「%USERPROFILE%/…」垃圾树
+    td = os.environ.get("TEMP") or os.environ.get("TMP") or ""
+    if "%" in td or (td and not os.path.isdir(td)):
+        cand = []
+        lad = os.environ.get("LOCALAPPDATA") or ""
+        if lad and "%" not in lad:
+            cand.append(os.path.join(lad, "Temp"))
+        cand.append(os.path.join(sysroot, "Temp"))
+        picked = next((c for c in cand if os.path.isdir(c)), None)
+        if not picked:
+            for c in cand:
+                try:
+                    os.makedirs(c, exist_ok=True)
+                    picked = c
+                    break
+                except OSError:
+                    continue
+        if picked:
+            os.environ["TEMP"] = picked
+            os.environ["TMP"] = picked
+            filled.append("TEMP/TMP=" + picked)
+
+    if filled or expanded:
+        print("WARN: ENV_SPARSE: 子进程环境残缺/含未展开字面量 —— 已回填[{}] 已展开[{}]".format(
+            ", ".join(sorted(filled)) or "-", ", ".join(sorted(expanded)) or "-"))
+        print("      正解：用继承**完整环境**的 shell 跑编译（ops_bash / PowerShell），"
+              "别从 Node spawn（空 process.env）直接起 UV4 或字体门禁脚本")
+
+
+def check_percent_literal_junk():
+    """构建后自检：环境残缺时 Windows 会在**当前目录**按字面量建 %SystemDrive%/ 之类的垃圾树。
+
+    只告警、不自动删——删除口径见本 skill「构建副产物」一节：必须用 bash 引号形态，
+    绝不能用 cmd（cmd 会把 %SystemDrive% 展开成 C:，等于对整块系统盘下 rd /s /q）。
+    """
+    for name in ("%SystemDrive%", "%USERPROFILE%", "%LOCALAPPDATA%", "%APPDATA%",
+                 "%ProgramData%", "%TEMP%", "%TMP%"):
+        if os.path.isdir(name):
+            print("WARN: JUNK_DIR: 工作区出现字面量目录 {}（未展开的 known-folder 路径；"
+                  ".gitignore 已兜住，不得入库）".format(name))
+            print("      清理（只用 bash 引号形态，禁用 cmd 以免展开成 C:）: rm -rf -- '{}'".format(name))
+
+
 class _ArgumentParser(argparse.ArgumentParser):
    """用法错误 → 退出码 3。

@@ -162,8 +273,25 @@ def find_lock_tool():
    return cand if cand.is_file() else None


+def plugin_tree_owner(cwd: Path):
+    """DSH worktree 插件的树（仓库内 .dsh-worktrees/worktree/<name>）→ 持有者名 pw:<name>。
+
+    2026-10-29 与 task-worktree skill 的 `plugin` 子命令对齐：插件建的树不在 _wt/ 约定里，
+    以前在这里跑构建，持有者名一律落成 "build-cli"——`lock status` 看不出是谁在占 UV4，
+    多个插件树 / 主树并发时就只剩猜。名字里的多段斜杠压平成 -，与
+    task_worktree.py 的 plugin_lock_owner() 完全一致（同一个可 grep 的标识）。
+    """
+    parts = cwd.parts
+    if ".dsh-worktrees" not in parts:
+        return None
+    tail = parts[parts.index(".dsh-worktrees") + 1:]
+    if tail and tail[0] == "worktree":
+        tail = tail[1:]
+    return "pw:" + "-".join(tail) if tail else "pw:?"
+
+
 def default_lock_task():
-    """持有者名：$DTU_TASK_ID > cwd 反推 `_wt/<ID>-<slug>/` 的 `<ID>` > "build-cli"。"""
+    """持有者名：$DTU_TASK_ID > cwd 反推 `_wt/<ID>-<slug>/` 的 `<ID>` > 插件树 `pw:<name>` > "build-cli"。"""
    v = os.environ.get("DTU_TASK_ID")
    if v:
        return v
@@ -174,7 +302,7 @@ def default_lock_task():
    for p in (cwd, *cwd.parents):
        if p.parent.name == "_wt":
            return p.name.split("-", 1)[0] or p.name
-    return "build-cli"
+    return plugin_tree_owner(cwd) or "build-cli"


 def build_lock_ttl_hours(timeout_s):
@@ -242,6 +370,9 @@ def run_build(args):
    print("PROJ: {}  target={}".format(proj, target or "(default)"))
    print("LOG: {}".format(log))

+    # 环境残缺守卫：先补齐/展开，否则 UV4 会在仓库根按字面量建 %SystemDrive%/ 垃圾树
+    harden_windows_env()
+
    # UV4 单实例陷阱：IDE 开着时 -b 可能被转发（退出码丢失、GUI 弹出）——只 WARN
    try:
        tl = subprocess.run(["tasklist", "/fi", "imagename eq UV4.exe", "/nh"],
@@ -268,6 +399,7 @@ def run_build(args):
        print("BUILD_FAIL: UV4 timed out after {}s (hung or forwarded to IDE?)".format(args.timeout))
        return 1
    print("UV4_RC: {}".format(rc))
+    check_percent_literal_junk()

    if not log.is_file():
        print("BUILD_FAIL: no build log produced - UV4 did not run or hung")
@@ -33,14 +33,14 @@ PC 上编译运行与 MCU **同一份** UI 源码（CMake + MSVC + SDL2，x64，

 ## UI 改动回归 → 用 `ui-verify` skill（勿在此零散手跑）

-5 步门禁 = 构建 → `check_menu_rows.py`（菜单 8 状态像素 + 池基线）→ `check_content_pages.py`（文本断言 + 11 页黄金参考 + 往返池）→ `@build` → `coding-standard`。
+5 步门禁 = 构建 → `check_menu_rows.py`（菜单 8 状态像素 + 池基线）→ `check_content_pages.py`（文本断言 + 66 张黄金参考 + 往返池）→ `/keil-build` → `coding-standard`。
 RemoDispBus 推流回归单独跑：`.venv\Scripts\python.exe simulator/tests/check_remo_sink.py`。
-黄金参考 `tests/ref/` 是**本地生成物不入库**：换机后先 `check_content_pages.py --update` 生成，再 `regen_ref_png.py` 出目检 PNG。
+黄金参考 `tests/ref/*.bin` **随仓库入库**（`.gitignore` 在全仓 *.bin 兜底之后又显式反选，2026-10-22 起；缺基准 = 新克隆跑 `ui-golden` 必 FAIL）：不入库的只是派生目检图 `ref/*.png`，换机后先 `check_content_pages.py --update` 生成，再 `regen_ref_png.py` 出目检 PNG。

 ## 两条铁律

 - **改 `simulator/lv_conf.h` 触发 `lv-conf-sync` 门禁**：它与 MCU 端 `Lib/lv_conf.h` 必须保持同一特性子集（按**生效值**比对，未定义取 `lv_conf_internal.h` 兜底）；四类判定与端专属白名单 → `docs/门禁说明/lv-conf-sync.md`；顶层 exclude 的教训 → `docs/代码规范/pre-commit使用说明.md` §5.5
- **模拟器代码与固件同标准受检**（`cppcheck` / `coding-standard` / 乱码 / 改写型钩子 / `doc-links` 全覆盖 `simulator/`）；**改动触及 `sim/` 任何后端，必须同步在 `docs/测试说明/模拟器差距清单.md` 登记一行**——模拟器跑过 ≠ 真机跑过
+- **模拟器代码与固件同标准受检**（`cppcheck` / `coding-standard` / 乱码 / 改写型钩子 / `doc-links` 全覆盖 `simulator/`）；**改动触及 `sim/` 任何后端，必须同步在 `docs/测试说明/专项验证/模拟器差距清单.md` 登记一行**——模拟器跑过 ≠ 真机跑过

 ## 构建/运行报错速查（详解 `simulator/README.md`「四、已知坑（构建/运行）」）

@@ -1,7 +1,7 @@
 ---
 name: mem-budget
-description: 嵌入式 RAM/栈预算核算工作流：Keil .map/.htm 静态报告（ram_report/stack_report）+ 串口运行时水位叠加 + DBG 日志成本模型（每条约 90B Flash/216B 栈）。"改任务/缓冲/栈之前必须核算"的固定动作与判读口径。
-whenToUse: 新增任务/加大缓冲/改栈/接入日志之前之后、链接报 L6406E 或 RAM 溢出、串口 [STACK] 水位余量低于底线、或需要回答"这个改动花多少 RAM/Flash"时。
+description: 嵌入式 RAM/栈预算核算工作流：Keil .map/.htm 静态报告（ram_report/stack_report）+ 串口运行时水位叠加 + 权威构建后的台账回填（ram_baseline.py --update 只往 ram_baseline.tsv 追加趋势行、--write 才同步 RAM预算台账 受管区、check_mem_numbers.py --write 同步文档快照区）+ DBG 日志成本模型（每条约 90B Flash/216B 栈）+ 跨树（worktree）测量的身份口径——脚本按 __file__ 定位产物、什么才算一次新测量、多条链同涨同一数值的共享帧/幻影环归因法。"改任务/缓冲/栈之前必须核算"、"这个数属于哪棵树、哪次构建"与"内存/Flash 数字钩子红了、提交前台账怎么回填"的固定动作和判读口径。
+whenToUse: 新增任务/加大缓冲/改栈/接入日志之前之后、链接报 L6406E 或 RAM 溢出、串口 [STACK] 水位余量低于底线、要回答"这个改动花多少 RAM/Flash"；以及要复算或比对另一个 worktree 的栈数字、独立验证某个栈回归该记在哪一笔提交上、判断多次启动的栈峰值抖动算不算劣化时；还有 /keil-build 之后要把内存数字回填进台账/文档、纠结该跑 ram_baseline.py --write 还是 --update、提交时 mem-budget / mem-numbers 两条钩子报"与 .map 不一致"时。
 ---

 # mem-budget — RAM/栈预算核算
@@ -9,26 +9,120 @@ whenToUse: 新增任务/加大缓冲/改栈/接入日志之前之后、链接报
 ## 固定动作（改前、改后各跑一次）

 ```powershell
-# cwd = 项目根；先 @build 保证 .htm/.map 是最新的
+# cwd = 项目根；先 /keil-build 保证 .htm/.map 是最新的（产物按脚本自身位置定位，见下节）
 & '.venv\Scripts\python.exe' ".dsh\skills\mem-budget\scripts\mem_check.py"
 # 等价于分别跑：
 #   scripts/ram_report.py            （.map → RAM/Flash 分区与按文件占用表）
 #   scripts/stack_report.py          （.htm 静态调用图 → 每任务最坏链 vs 配置栈）
+# 报告落盘留档（改前/改后各一份，供逐帧差分）：
+& '.venv\Scripts\python.exe' scripts/stack_report.py -o ci-artifacts/sr_before.md
 # 叠加运行时水位（有真机日志时）：
 & '.venv\Scripts\python.exe' scripts/stack_report.py -s .dsh\skills\serial-assistant\scripts\state\serial.log
 ```

 退出码：0=全部通过 / 1=有任务不达标 / 2=解析错误（.htm/.map 缺失先重跑构建）。
+别整篇读输出，抓关键行：`grep -aE 'iec104|margin|FAIL|ISR|Rule' ci-artifacts/sr_before.md`。
+
+**「改前 / 改后」必须是两次不同的 Linker run**（两个不同的产物身份）：同一份 .htm/.map 上跑两遍
+只是把同一个数字复述两遍，不构成"改后已复验"。
+
+## 测量身份口径（先钉树与时刻，再看数字）
+
+1. 脚本按 __file__ 定位产物，不按 cwd —— 跨树必须换脚本（在主树跑脚本量任务树 = 拿旧 .map 当真值）
+2. 重跑报告脚本不算新测量（复述 ≠ 复验）：只有新的 Linker run 才算一次新测量
+3. 钉身份的取数法：.htm/.map 按约定不入库 → 把时刻写进正文/台账；记录最小格式 = tree/commit + Linker run 时刻 + 产物来源（本次构建 / 盘上既有）
+> 本节全文（逐字搬移、未改写，含命令与实测数字）→ [measurement-identity.md](reference/measurement-identity.md)。动手前先读那篇。
+
+## 静态最坏链回归的归因（同涨同一数值 = 共享帧，不是调用方）
+
+- 多条任务链分毫不差同涨/同降同一个数值 ⇒ 加深在这些任务共用的被调帧 / 共享尾段上，不在任何一个调用方（别先猜「新增了大局部缓冲」，实测猜错过一次）
+- 逐棵树逐帧比 frame size、不只比总数：stack_report.py 的 own-frame 表锁链尾公共段；grep -ac 'In Cycle' 在 .htm 里找环（实测 17 处）—— 链接器幻影环能在无人改栈配置时让全仓链齐涨
+- Maximum Stack Usage 里的 + Unknown(Cycles, Untraceable Function Pointers) 说明静态数是估计值，别当精确值上报；不采信口头结论，用目标树的脚本 + .venv 解释器自己复算
+- 处置后的下一步：抬栈（Src/freertos.c 的 USER CODE 区，属 Ask-first）或收紧共享缓冲 / 断环；改前改后各跑一次 stack_report.py + ram_report.py，且「改后」那次必须落在一次新的 Linker run 上
+> 本节全文（逐字搬移、未改写，含命令与实测数字）→ [shared-frame-attribution.md](reference/shared-frame-attribution.md)。动手前先读那篇。

 ## 判读口径

 - **静态**：`stack_report.py` 的 Max Depth（最坏调用链累计）vs `Src/freertos.c` 配置栈；
  默认要求余量 ≥30%（`--min-free-pct`），ISR 另留 `--isr-margin`（默认 1024B）。
+  判定式 `margin = cfg - max(static_max_depth, runtime_peak)` 须 ≥ `max(isr_margin, 30% of cfg)`。
 - **运行时**：开机日志 `[STACK] <task> peak_used=…/… free_min=…` 与静态值对照——
-  静态是上界、运行时是下界证据，**两者都要看**；余量 <1KB 底线要上报。
+  **静态最坏链是上界（硬线）、运行时峰值是下界证据（趋势）**，两者都要看；余量 <1KB 底线要上报。
 - **RAM 总量**：`ram_report.py` 对 Grand Totals 与 `docs/内存管理/` 预算表核对；
  链接错 `L6406E` = 已经溢出，用按文件表找大头。
- 任务表一致性由 pre-commit `task-table` 钩子保证（改栈后 `gen_task_table.py` 同步 AGENTS.md）。
+- 任务表一致性由 pre-commit `task-table` 钩子保证；`mem-budget` 钩子拦 RW_IRAM1/RW_CCM >92%，
+  **并核台账受管区是否与 .map 同源**；`mem-numbers` 钩子核文档里的内存数字——
+  数字与树/时刻脱钩、或**构建后只跑了 `--update` 没回填受管区**时，响的就是这两条（回填见下一节）。
+
+## 权威构建后的台账回填（三个旗标，别混）
+
+`.map` 是内存/Flash 数字的**唯一事实源**；台账与文档里的数字由脚本从它生成——**不手抄、不手改**
+（`docs/内存管理/RAM预算台账.md` 首段就写着"数字不手抄"）。三份落点 = 三个旗标，一条命令只干其中一件：
+`ram_baseline.py` 的 `--gate/--write/--update/--trend` 是 `add_mutually_exclusive_group()`
+（`scripts/ram_baseline.py:415-419`），想干两件就得调两次。
+
+| 落点 | 旗标 | 实际改了什么 |
+|---|---|---|
+| `scripts/ram_baseline.tsv` 趋势基线（顺带刷 `scripts/size_attestation.json` 同码凭证） | `ram_baseline.py --update` | **只**追加/覆盖当日那一行趋势（Code/RO/RW/ZI + 三区水位 + Top-10 RW+ZI）。**不碰台账正文** |
+| `docs/内存管理/RAM预算台账.md` 的 `<!-- MEM_BUDGET:BEGIN/END -->` 受管区 | `ram_baseline.py --write` | 从 .map 重渲染区域水位 + 子系统配额对照（打印「已同步台账受管区。」或「台账受管区已是最新。」） |
+| `docs/内存管理/RAM使用分析与优化方案.md` 的 `<!-- MEM_SNAPSHOT:BEGIN/END -->` 快照区 | `check_mem_numbers.py --write` | 从**同一份** .map 重渲染内存/Flash 快照表（打印「已更新内存快照：…」） |
+
+**AGENTS.md 与台账 §4 那句「每次 `/keil-build` 后跑 `scripts/ram_baseline.py --update`」喂的是趋势行，不等于回填受管区。**
+实测代价：照那句跑完 `--update` 就提交 → `mem-budget`、`mem-numbers` 两条钩子当场红。
+`mem-budget` 的 entry 是 `python scripts/ram_baseline.py --gate`（`.pre-commit-config.yaml:571`）——它在 92% 阈值之外
+还核**台账受管区与 .map 的一致性**，漂移即 `[FAIL] 台账受管区与 .map 不一致（区域水位或子系统配额表漂移）`
+并打印 `修复：python scripts/ram_baseline.py --write`（`scripts/ram_baseline.py:221-224`）；
+`mem-numbers` 的 entry 是 `python scripts/check_mem_numbers.py --scan`（同文件 :193），不一致时打印
+`修复：运行 python scripts/check_mem_numbers.py --write`（`scripts/check_mem_numbers.py:416`）。
+改用两个 `--write` 后重提，同一笔提交触发的 26 条钩子全 Passed。
+
+### 提交前固定顺序（构建 → 回填 → 真钩子提交）
+
+```powershell
+# cwd = 项目根，一律 .venv 解释器
+# 0) 权威构建先行（0 错 0 警）：回填读的是**盘上那份 .map**，构建没落定就 --write = 把旧数字写进台账，钩子照样红
+& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py
+
+# 1) 趋势行（纪律项，不是回填）：覆盖 tsv 当日行 + 顺带刷体积同码凭证
+& '.venv\Scripts\python.exe' scripts/ram_baseline.py --update
+
+# 2) 回填台账受管区（mem-budget 钩子核的就是这一段）
+& '.venv\Scripts\python.exe' scripts/ram_baseline.py --write
+
+# 3) 回填文档快照区（mem-numbers 钩子核的就是这一张表）
+& '.venv\Scripts\python.exe' scripts/check_mem_numbers.py --write
+
+# 4) 逐字自跑提交时会跑的这两条 entry（比事后翻 pre-commit 输出快）
+& '.venv\Scripts\python.exe' scripts/ram_baseline.py --gate        # 0 = 阈值 + 受管区都过
+& '.venv\Scripts\python.exe' scripts/check_mem_numbers.py --scan   # 0 = 快照区与 .map 一致
+
+# 5) 把刚落盘的落点一并 add，然后**真钩子**提交（绝不 --no-verify、绝不手改数字）
+git add docs/内存管理/RAM预算台账.md docs/内存管理/RAM使用分析与优化方案.md scripts/ram_baseline.tsv scripts/size_attestation.json
+```
+
+退出码：`ram_baseline.py` 0=通过或跳过 / **1=阈值超限或受管区漂移** / 2=.map 解析失败；
+`check_mem_numbers.py` 0=一致 / 1=不一致、缺受管锚点或找不到事实源。
+
+### 回填链上的坑（实测）
+
+- --write 说「已是最新」而钩子还红
+- tsv 落后只 WARN、不拦
+- --gate 无 .map → SKIP，而脚本自己写明「SKIP 不等于 PASS」
+- --map <path> 只换读、不换写
+- --scan 的散句告警 --write 不替你改
+- --update 的盖戳排在索引后面
+- 改写型钩子当场改文件是流程不是故障
+- mem-budget 触发面很宽
+> 本节全文（逐字搬移、未改写，含命令与实测数字）→ [backfill-pitfalls.md](reference/backfill-pitfalls.md)。动手前先读那篇。
+
+## 运行时峰值抖动与"算不算劣化"
+
+- 同一份镜像连续启动 5 次，`uiTask` 峰值实测在 4116~4188 之间摆 **72 B** ⇒ 跨启动本身就有几十 B 抖动，
+  "相对上一轮 +100 B"**不可归因**于被测改动。判据写成"栈水位不劣于上一轮"必然假红。
+- 可执行修法（二选一，别都留着）：
+  1. 同一份像**≥3 次启动取最大值**互比，并加容差（**±128 B 量级**）；
+  2. 硬线改用 `stack_report.py` 的**静态最坏链**，运行时峰值降级为趋势参考。
+- 判据一改要同步**所有落点**：判据正文、跑判据的脚本、记录判据的文档三处一起改，只改一处等于各说各话。

 ## 成本模型（实测，估算用）

@@ -42,8 +136,21 @@ whenToUse: 新增任务/加大缓冲/改栈/接入日志之前之后、链接报
 - **自研代码禁 C 库堆**（MicroLIB 堆仅 512B）：只用 `pvPortMalloc/vPortFree`（FreeRTOS 堆），
  模拟器 CRT 堆照不出 MCU 堆分配失败。

+## 验证（这轮测量算数了吗）
+
+1. 报告头 `- Source:` 的相对路径落在**我要量的那棵树**下（不是裸文件名，更不是别的树）；
+2. `- Linker run:`（或 .htm 的 `Last Updated:` / mtime）与本轮那次构建对得上，且**不同于**上一轮那次的时刻
+   ——相同就是复述，回去先做一次构建再比；
+3. 树身份已按 `tree/commit + 时刻 + 产物来源` 写进提交正文/台账，而不是只留在终端输出里；
+4. 结论里互比的数字必须来自**同一棵树同一次链接**；跨树比较要各自给出树与时刻；
+5. 涉及劣化判定时注明依据的是静态最坏链（硬线）还是运行时峰值（趋势），并已计入跨启动抖动。
+6. 要入库的数字：本轮已按「`/keil-build` → `ram_baseline.py --update` → `ram_baseline.py --write` →
+   `check_mem_numbers.py --write`」回填，并逐字自跑 `ram_baseline.py --gate` 与 `check_mem_numbers.py --scan` 各返 0；
+   台账 / 文档 / tsv 的改动与代码同一笔入库，**未手改数字、未用 `--no-verify`**。
+
 ## 其它项目怎么套

 模式通用：链接器 map + 调用图 htm 是**免硬件**的栈可观测源；固定"改前改后各跑一次
-报告 + 运行时水位叠加 + 余量阈值"三件套。本仓库两个报告脚本按 Keil 输出格式解析，
-换工具链（GCC newlib + `-fstack-usage`）需替换解析层，工作流不变。
+报告 + 运行时水位叠加 + 余量阈值"三件套，**外加一条身份口径——脚本按自身位置定位产物，
+跨树比的是"两棵树各自的脚本 + 各自的链接时刻"，重跑同一份产物永远只是复述**。
+本仓库两个报告脚本按 Keil 输出格式解析，换工具链（GCC newlib + `-fstack-usage`）需替换解析层，工作流不变。
@@ -0,0 +1,29 @@
+# 回填链上的坑（实测）（自 SKILL.md 外置）
+
+> 本文由 mem-budget 的 SKILL.md「回填链上的坑（实测）」一节逐字外置而来（渐进展开：主文件只留索引与指针）。步骤号沿用原文，未重编。
+
+- **`--write` 说「已是最新」而钩子还红** ≠ 钩子坏了，是**落点找错了**：tsv / 台账受管区 / 文档快照区
+  三处各归一个旗标。按上表对号，别把同一个旗标重跑三遍；手改台账数字更不行——下次 `--write` 直接覆盖你，
+  钩子仍按 .map 判漂移。
+- **tsv 落后只 WARN、不拦**：`--gate` 对「tsv 末行落后于当前 .map」只打印 `[WARN] …请跑 --update`
+  （`ram_baseline.py:232`），**拦下来的是受管区漂移**。所以"钩子绿"绝不等于"趋势行也补了"，反之亦然，各查各的。
+- **`--gate` 无 .map → SKIP，而脚本自己写明「SKIP 不等于 PASS」**（`ram_baseline.py:177`）：
+  新开的 task-worktree 从没在这棵树上构建过时必然走到这里；同一状态下 `--write` 直接
+  `[FAIL] 找不到 .map 事实源，先 /keil-build`（`ram_baseline.py:250`）——不是代码缺陷，是这棵树还没测过体积。
+  无需 Keil 的强制兜底是 `scripts/check_size_gate.py --local`（= `scripts/ci_local.py` 的体积门禁步）与 CI 的 `--ci`。
+- **`--map <path>` 只换读、不换写**：`LEDGER`（`ram_baseline.py:45`）与 `TARGETS`（`check_mem_numbers.py:53-54`）
+  都由 `REPO_ROOT = Path(__file__).resolve().parent.parent` 算出。拿主仓脚本配 `--map <另一棵树>/…map` 去 `--write`，
+  等于用别的树的数字**改写主仓的台账**——比"半棵树混合数字"更糟，因为它落盘了。回填永远用本树自己的脚本。
+- **`--scan` 的散句告警 `--write` 不替你改**：正文里手抄的旧值（"现 RW_IRAM1 62.6%" 这类散句）只告警，
+  脚本明确写着「`--write` 不会自动改写正文」（`check_mem_numbers.py:418`）→ 人工按受管区改那一行
+  （Edit 精确替换；含中文的文档绝不整文件重写）。
+- **`--update` 的盖戳排在索引后面**：它顺带调 `check_size_gate.cmd_stamp()`（`ram_baseline.py:345`），
+  而凭证指纹按 **git 索引内容**生成，有未 staged 的脏改动时**拒盖**，且这里只 `[WARN]`、不改返回值
+  → 现象是 tsv 多了一行而凭证仍是旧的，要等 `ci_local` 的体积门禁步 / CI 体积门禁那一侧才报出来。
+  要么先 `git add` 再 `--update`，要么补跑 `python scripts/check_size_gate.py --stamp`。
+- **改写型钩子当场改文件是流程不是故障**：`trailing-whitespace` / `end-of-file-fixer` 报
+  `files were modified by this hook`（新建的 .c 最常触发）时，先读 `ci-artifacts/cui.log` 的真实报错确认是哪几条红，
+  `git add` 被改写的文件后重提。两条改写红 + 两条内存红混在同一次里时，别顺手把内存那条也当"钩子误报"绕过去。
+- **`mem-budget` 触发面很宽**：`files:` 覆盖 `App/` `Drivers/BSP/` `Src/` `Inc/` `Lib/lv_conf.h`
+  `test/board/` `scripts/ram_baseline.` `docs/内存管理/` `.pre-commit-config.yaml`，且 pre-commit 4.x 已无
+  `always: true` —— 纯 UI / 纯文档提交照样被它拦：盘上 .map 与台账不同源就红，跟这笔提交碰没碰内存文件无关。
@@ -0,0 +1,58 @@
+# 测量身份口径（先钉树与时刻，再看数字）（自 SKILL.md 外置）
+
+> 本文由 mem-budget 的 SKILL.md「测量身份口径（先钉树与时刻，再看数字）」一节逐字外置而来（渐进展开：主文件只留索引与指针）。步骤号沿用原文，未重编。
+
+### 1. 脚本按 `__file__` 定位产物，不按 cwd —— 跨树必须换脚本
+
+```python
+# scripts/stack_report.py:36-38
+REPO_ROOT   = pathlib.Path(__file__).resolve().parent.parent
+HTM_DEFAULT = REPO_ROOT / "MDK-ARM" / "STM32F407-Demo" / "STM32F407-Demo.htm"
+FREERTOS_C  = REPO_ROOT / "Src" / "freertos.c"        # 配置栈来源，无命令行开关
+# scripts/ram_report.py:16-18 同样用 dirname(dirname(abspath(__file__))) 定位 .map
+```
+
+⇒ `cd 进别的 worktree 再跑主仓的脚本` 量的仍是**主仓**那份 .htm/.map，数字不可比。
+实测代价：这样一次"独立复算"量到主仓的 1,544 B / margin 1,016 B FAIL，据此写下的 +80 B 归因
+被队友的逐树逐帧差分表推翻——目标 worktree 的真数是 1,464 B / margin 1,096 B / PASS。
+
+正确做法：**量哪棵树就跑那棵树自己的脚本**（该树必须已在这棵树上构建过、有自己的 .htm/.map；
+开树与合并的生命周期见 `task-worktree` skill）：
+
+```bash
+'.venv/Scripts/python.exe' "<目标树>/scripts/stack_report.py"
+'.venv/Scripts/python.exe' "<目标树>/scripts/ram_report.py"
+```
+
+⚠ 只给主仓脚本传 `-i <另一棵树的 .htm>`（或位置参数传另一棵树的 .map）**不够**：
+`stack_report.py` 的配置栈仍从**脚本所在那棵树**的 `Src/freertos.c` 读（`FREERTOS_C` 写死自 `__file__`，
+没有开关），两树栈配置一旦不同就是"半棵树的混合数字"。要整支脚本换树跑。
+
+自检（每次复算都做）：报告头两行 `- Source: ...` 与 `- Linker run: ...` 就是你实际量的树和时刻。
+`Source` 若只打印一个裸文件名（不带 `MDK-ARM/...` 相对路径），说明 `-i` 指到了脚本 `REPO_ROOT` 之外的产物。
+
+### 2. 重跑报告脚本**不算新测量**（复述 ≠ 复验）
+
+`stack_report.py` / `ram_report.py` 只是解析盘上那一份 .htm/.map；产物没变，再跑一次数字必然不变。
+那只能叫"复述"，**不能写成"我复验过"**。要拿到新数字必须先有一次**新的 Linker run**（增量构建也算），
+并把新时刻与产物来源一并写进记录。
+
+⚠ `ram_report.py` 正文里的 `> Generated: …` 是**脚本运行时刻**，重跑就变——它不是链接时刻，
+不能拿来当"这是新测量"的凭证。
+
+### 3. 钉身份的取数法（.htm/.map 按约定不入库 → 把时刻写进正文/台账）
+
+```bash
+grep -aE 'Last Updated|Maximum Stack Usage' MDK-ARM/STM32F407-Demo/STM32F407-Demo.htm | head -2
+# → "ARM Linker, 5060960: Last Updated: Mon Oct 26 22:52:12 2026"
+```
+
+- .htm 里唯一的链接时刻锚点是 **`Last Updated:`**；`Linker run` 只是 `stack_report.py` 自己输出里的标签，
+  `Date of Link`、`Image component` **不在 .htm 里**（实测按它们 grep 全空，白跑一轮）。
+- 取不到该字段时退回产物 mtime；同一笔链接里 .htm 与 .map 的 mtime 只差 ~0.1 s，可据此确认两份产物同源。
+  再配 `git log -1 --format=%H` 与该树 `git status` 的未跟踪文件数。
+- 记录最小格式：**`tree/commit + Linker run 时刻 + 产物来源（本次构建 / 盘上既有）`**。
+  本仓 .htm/.map 不入库，不钉时刻就等于把数字和树脱钩，下一个读数字的人无从判断它描述哪棵树。
+- 归属还能机械证明时顺手做掉：`git log --name-only <那笔>..HEAD -- "*.c" "*.h"` 逐行筛（排除 `.uvprojx`）。
+  若那笔之后没有任何提交再碰固件源文件，产物描述的就是**在库那棵树**，不是提交前快照。
+- 同族坑：`git show :path` / `git show HEAD:path` 读的是索引/HEAD，**不是工作区**。
@@ -0,0 +1,24 @@
+# 静态最坏链回归的归因（同涨同一数值 = 共享帧，不是调用方）（自 SKILL.md 外置）
+
+> 本文由 mem-budget 的 SKILL.md「静态最坏链回归的归因（同涨同一数值 = 共享帧，不是调用方）」一节逐字外置而来（渐进展开：主文件只留索引与指针）。步骤号沿用原文，未重编。
+
+- **多条任务链分毫不差同涨/同降同一个数值**（实测 default/net/iec104 三条 +80 B；断环后九条链各 −80 B）
+  ⇒ 加深在这些任务**共用的被调帧 / 共享尾段**上，不在任何一个调用方。别逐个调用方翻，
+  也**别先猜"新增了大局部缓冲"**——实测猜错过一次（`con_ring_try` 只有 24 B 帧、没有数组）。
+- 逐棵树逐帧比 frame size，不要只比总数：
+  - `stack_report.py` 输出的「Frame-size ranking (own frame)」表 + 每任务最坏链文本，锁定**链尾公共段**
+    （实测落在 `dbg_console_write_line → con_append → dbg_console_drain`，据此把账记到上一笔提交上）；
+  - 直接在 .htm 里找环：`grep -ac 'In Cycle' MDK-ARM/STM32F407-Demo/STM32F407-Demo.htm`（实测 17 处），
+    形态为 `Max Depth = 280 + In Cycle` 与 `Call Chain = Error_Handler => dbg_console_write_line (Cycle)`。
+    `+ In Cycle` 表示 armlink 把**环上所有帧**计入含该环的每一条任务链——**链接器幻影环**能在无人改栈配置时让全仓链齐涨。
+  - 实测样本（无人改栈配置、全仓链却齐涨的那种）：taskEXIT_CRITICAL ⇒ vPortExitCritical ⇒ configASSERT ⇒
+    vApplicationAssertFailed ⇒ dbg_console_write_raw ⇒ 回到 console_log 内部 ⇒ 再进临界区；
+    它使 `vApplicationAssertFailed` 的 Max Depth 由 ~40 B 变 128 B + In Cycle，差 88 B ≈ 三条链同涨 80 B 的来源。
+    断环方向：内核临界区改 PRIMASK 保存/恢复（保存量放局部变量）→ 零调用帧、不成环；
+    断环的**图证**（该帧从「136 B + In Cycle」变成「8 B、不再 In Cycle」）比数字更有说服力。
+- `Maximum Stack Usage = N bytes + Unknown(Cycles, Untraceable Function Pointers)` 里的 `+ Unknown(...)`
+  说明静态图对环与函数指针不可完全解析，静态数是估计值，别当精确值上报。
+- 不采信任何口头结论：用**目标树的脚本 + `.venv` 解释器**自己复算；复算同样先按上节钉身份。
+- 处置后的下一步：抬栈（`Src/freertos.c` 的 `USER CODE` 区，属 Ask-first 动作）或收紧共享缓冲 / 断环，
+  **改前改后各一次** `stack_report.py` + `ram_report.py`，且"改后"那次必须落在一次新的 Linker run 上；
+  抬栈后跑 `gen_task_table.py` 同步任务表。
@@ -36,5 +36,5 @@ cmake --build simulator/build --config Debug   # 0 警告
 - **禁止**把源文件复制进 `simulator/`——两端共用 `Drivers/BSP/` 原件（UI_界面制作流程.md C7）
 - 只注册 `.c`（含 `.s`）；`.h` 靠 include 路径找到，不加工程
 - 漏注册的典型症状：一端编译失败（undefined reference）或一端行为悄悄停留在旧逻辑
- 注册完成后跑回归：UI 文件 → `ui-verify` skill；其他模块 → `@test`（`.dsh/skills/serial-boot-test/scripts/run_boot_test.py`）
+- 注册完成后跑回归：UI 文件 → `ui-verify` skill；其他模块 → `/serial-boot-test`（`.dsh/skills/serial-boot-test/scripts/run_boot_test.py`）
 - 改过 `CMakeLists.txt` 后需重新 `cmake -B build` 配置
@@ -2,7 +2,7 @@
 # -*- coding: utf-8 -*-
 """serial_tool — Python 串口助手（常驻 daemon + 薄 CLI + 日志文件即接口）。

-设计文档：docs/测试说明/串口助手设计说明.md
+设计文档：docs/测试说明/测试工具/串口助手设计说明.md

 架构：
    CLI（短命进程，硬超时） --HTTP JSON--> daemon（detached 单实例，127.0.0.1）
@@ -19,7 +19,7 @@
    status                      全状态（单条 JSON）
    log --tail N --grep P       读日志（先过滤后截尾；-i 忽略大小写 / --regex 正则）
    clear                       清空日志（原子截断 + 代际递增）
-    wait-idle                   等 RX 静默（@test 用；--settle-ms / --max-ms / --first-timeout-ms）
+    wait-idle                   等 RX 静默（/serial-boot-test 用；--settle-ms / --max-ms / --first-timeout-ms）
    start / stop / restart      daemon 生命周期（其余命令会自动拉起 daemon）
    selftest                    无头自检（行拆分/解码回退/截头算法，无需硬件）

@@ -615,10 +615,10 @@ class Daemon:
    def wait_idle(self, settle_s, max_s, first_timeout_s=None):
        """等 RX 静默，返回 reason ∈ {idle, no_data, timeout}。

-        2026-10-09 修三处（旧实现会让 @test 在"板子全程没输出"时误判收尾）：
+        2026-10-09 修三处（旧实现会让 /serial-boot-test 在"板子全程没输出"时误判收尾）：
          1. no_data 判据：旧实现比的是"进入函数时 daemon 累计 rx_bytes 是否为 0"。
             daemon 常驻（本机实测 rx_bytes=1.2MB）→ 永远 >0 → 板子一个字节都不发
-             也返回 idle:true，@test 的 no_data 拦截形同虚设。现按**本次增量**判。
+             也返回 idle:true，/serial-boot-test 的 no_data 拦截形同虚设。现按**本次增量**判。
          2. 首字节门：旧实现从进入即开始计静默时间，板子第一行比 settle_ms 来得
             晚就提前收尾（"开机日志缺尾巴"的另一半成因）。现首字节到达前不启动
             settle 计时，改由 first_timeout_s 兜底（默认 = max_s）。
@@ -1123,26 +1123,26 @@ def run_selftest():
    def check(name, cond, detail=""):
        results.append((name, bool(cond), detail))

-    # T1 行拆分：CRLF / 多行 / 残行冲刷
+    # 行拆分：CRLF / 多行 / 残行冲刷
    sp = LineSplitter()
    got = [l for _, l in sp.feed(b"abc\r\n", 1000.0)]
-    check("T1a CRLF 行", got == [b"abc"], repr(got))
+    check("行拆分：CRLF 行", got == [b"abc"], repr(got))
    got = [l for _, l in sp.feed(b"de\nf\n", 1001.0)]
-    check("T1b 多行", got == [b"de", b"f"], repr(got))
-    check("T1c 残行不入文件", sp.feed(b"ghi", 1002.0) == [] and sp.buf == b"ghi")
+    check("行拆分：多行", got == [b"de", b"f"], repr(got))
+    check("行拆分：残行不入文件", sp.feed(b"ghi", 1002.0) == [] and sp.buf == b"ghi")
    got = [l for _, l in sp.flush_partial()]
-    check("T1d 残行冲刷", got == [b"ghi"], repr(got))
+    check("行拆分：残行冲刷", got == [b"ghi"], repr(got))
    got = sp.feed(b"\n\n", 1003.0)
-    check("T1e 空行忽略", all(not raw for _, raw in got) and sp.buf == b"", repr(got))
+    check("行拆分：空行忽略", all(not raw for _, raw in got) and sp.buf == b"", repr(got))

-    # T2 解码回退链
+    # 解码回退链
    check("T2a UTF-8", decode_line("中文ok".encode("utf-8")) == "中文ok")
    check("T2b GBK", decode_line("中文".encode("gbk")) == "中文")
    check("T2c HEX 兜底", decode_line(b"\xff\xfe\x01") == "HEX:fffe01")

-    # T3 时间戳格式
+    # 时间戳格式
    s = line_at(time.time(), "RX", "x")
-    check("T3 行格式", s.startswith("[RX] ") and "T" in s.split(" ")[1], s)
+    check("时间戳行格式", s.startswith("[RX] ") and "T" in s.split(" ")[1], s)

    # T4 截头算法（保留尾部 + 截后继续追加）
    pat = b"0123456789abcdef"
@@ -1298,8 +1298,8 @@ def run_selftest():
        except OSError:
            pass

-    # T10 端口建议：换 USB 口后 COM 号变了，唯一候选直接给（多候选不猜）
-    check("T10 port_hint 唯一候选才给建议",
+    # 端口建议：换 USB 口后 COM 号变了，唯一候选直接给（多候选不猜）
+    check("端口建议：唯一候选才给建议",
          port_hint("COM7", ["COM6"]) == "COM6"
          and port_hint("COM7", ["COM6", "COM9"]) is None
          and port_hint("COM6", ["COM6"]) is None)
@@ -1353,7 +1353,7 @@ def build_parser():

    sub.add_parser("clear", parents=[common], help="清空日志（代际 +1）")

-    p = sub.add_parser("wait-idle", parents=[common], help="等 RX 静默（@test 用）")
+    p = sub.add_parser("wait-idle", parents=[common], help="等 RX 静默（/serial-boot-test 用）")
    p.add_argument("--settle-ms", type=int, default=8000,
                   help="静默判据毫秒（默认 8000：boot 有 3~4s 自然静默间隙）")
    p.add_argument("--max-ms", type=int, default=30000, help="最长等待毫秒（默认 30000）")
@@ -14,9 +14,11 @@ whenToUse: 需要向目标板烧录或复位后，用串口日志自动判定运
 | 脚本 | 作用 |
 |---|---|
 | `.dsh/skills/serial-boot-test/scripts/run_boot_test.py` | 一键闭环：open+clear → 烧录 → wait-idle → 提取 boot log → 烧录回读校验 → 标记校验。串口助手按 `$DSH_SERIAL_TOOL` > 同目录 > `../serial-assistant/scripts/serial_tool.py` 解析 |
-| `.dsh/skills/serial-boot-test/scripts/verify_log.py` | 对任意日志文件做标记校验（Required/Forbidden/锚点计数/顺序/耗时），可单独用。`--exact` 做**整行 `^…$` 锚定**（子串口径照不出"行还在但行首被吃掉/行内被插字节"那一类损坏）、`--pair` 做跨复位配对、`--allow-residual/--head-char` 服务崩溃注入腿、`--selftest` 跑内置判别用例（**证明这套判据不是空跑**）。四个行级开关（`--exact` / `--pair` / `--allow-residual` / `--head-char`）同时接进了 `run_boot_test.py`，@test 闭环直接可用 |
+| `.dsh/skills/serial-boot-test/scripts/verify_log.py` | 对任意日志文件做标记校验（Required/Forbidden/锚点计数/顺序/耗时），可单独用。`--exact` 做**整行 `^…$` 锚定**（子串口径照不出"行还在但行首被吃掉/行内被插字节"那一类损坏）、`--pair` 做跨复位配对、`--allow-residual/--head-char` 服务崩溃注入腿、`--selftest` 跑内置判别用例（**证明这套判据不是空跑**）。四个行级开关（`--exact` / `--pair` / `--allow-residual` / `--head-char`）同时接进了 `run_boot_test.py`，/serial-boot-test 闭环直接可用 |

-> **判据取向（重要，会复发）**：`--exact` 默认**只锚文本、不钉长度**——字节长度属于某一份构建，钉死它会在无辜改动上假红（`@@LEN=<n>` 是显式逃生口，不是默认）。子串 `--required` 不能用于"可能丢行首/被插字节"的行。来龙去脉与固定动作见本仓 `docs/测试说明/启动日志原子性复验流程.md`。
+> **`/serial-boot-test` 是 DSH 会话的技能调用名、不是 shell 命令**（同 `/keil-build`，见 AGENTS「构建与验证」总口径）：可执行形态 = 上表 `run_boot_test.py` 命令行（仓库根跑）；项目配置与判据见本仓 `docs/测试说明/流程与规范/自动化测试流程.md`。
+
+> **判据取向（重要，会复发）**：`--exact` 默认**只锚文本、不钉长度**——字节长度属于某一份构建，钉死它会在无辜改动上假红（`@@LEN=<n>` 是显式逃生口，不是默认）。子串 `--required` 不能用于"可能丢行首/被插字节"的行。来龙去脉与固定动作见本仓 `docs/测试说明/专项验证/启动日志原子性复验流程.md`。

 交互式串口操作（open/send/log/wait-idle/status 等）不属于本 skill——
 **用 `serial-assistant` skill**。
@@ -19,7 +19,7 @@
  5. verify_log.py 标记校验（含启动锚点计数 config "boot_marker" + --max-boot-count；
     --expect-reset-cause 原因白名单；--require-order 标记顺序；
     --done-marker + --max-boot-ms 开机耗时）
-  6. （仅当 --require-selftest-pass）自检台账联合判定（S7）：默认**只判本次启动新增**
+  6. （仅当 --require-selftest-pass）自检台账联合判定：默认**只判本次启动新增**
     ——烧录前先经 FTP 取 /log/selftest.log 基线，启动后再取一次，只把"基线之后新增"的
     记录交给判定（该文件是 512 条环形累计历史，"非空即 FAIL"判一次启动永远不可能过）。
     设备侧无此文件 = 台账干净 = PASS；**抓取失败 / 没有数据源 / 基线被环覆盖 → FAIL**，
@@ -140,8 +140,8 @@ def _split_cmd(cmd_str):
    直接交给 subprocess、**不经 `cmd /c`**：CreateProcess 能直接跑 .bat，且 Python
    会给含空格的路径正确加引号。旧写法 `['cmd','/c', 串]` 在本仓库（目录名
    `DTU Code` 含空格）会被 cmd 的 /c 引号规则玩坏——实测报
-    `'D:\Code\DTU' is not recognized`，回读校验被假判成"芯片内容不一致"。
-    路径本身含空格时把该段用引号包住（`"D:\some dir\flash_tool.bat" flash`）。
+    「'D:\Code\DTU' is not recognized」，回读校验被假判成"芯片内容不一致"。
+    路径本身含空格时把该段用引号包住（「"D:\some dir\flash_tool.bat" flash」）。
    posix=False 是必须的：posix=True 会吃掉 Windows 路径里的反斜杠。
    """
    return [p.strip('"') for p in shlex.split(cmd_str, posix=False)]
@@ -226,7 +226,7 @@ def _ftp_quit(ftp):
 def _prune_out_dir(out_dir, keep):
    """只保留最近 N 份产物（`boot_log_*.txt` / `selftest_log_*.log`）。

-    这些文件按 `%Y%m%d_%H%M%S` 命名、每次 @test 各留一份，旧实现从不清理——
+    这些文件按 `%Y%m%d_%H%M%S` 命名、每次 /serial-boot-test 各留一份，旧实现从不清理——
    本机实测 out 目录已堆到 31 份 boot_log + 7 份 selftest_log（2026-10-10）。
    文件名含时间戳 → 按名字排序即按时间排序。
    """
@@ -294,7 +294,7 @@ def _fetch_selftest_log(device_ip, out_dir, stamp, ftp_user="admin", ftp_pass="a
    2026-10-02 台架修复：原实现只 `except OSError`，而 ftplib 的 error_temp /
    error_perm 继承自 Exception 而非 OSError —— 台账"仅故障才写"，干净设备上
    /log/selftest.log 根本不存在，RETR 返回 450 直接抛出未捕获异常，令整个
-    `@test --require-selftest-pass` 在最后一步崩掉（而它本该是 PASS 路径）。
+    `run_boot_test.py --require-selftest-pass` 在最后一步崩掉（而它本该是 PASS 路径）。
    现把"设备侧无此文件"单列为正常路径（INFO），其余 FTP 错误保留 WARN。
    """
    local = Path(out_dir) / "selftest_log_{}.log".format(stamp)
@@ -313,7 +313,7 @@ def _fetch_selftest_log(device_ip, out_dir, stamp, ftp_user="admin", ftp_pass="a
    try:
        ftp.retrbinary("RETR /log/selftest.log", buf.extend)
    except ftplib.all_errors as e:
-        # 450/550 = 设备侧无此文件：干净台账，S7 判 PASS（正常路径，非故障）
+        # 450/550 = 设备侧无此文件：干净台账 → 判定 PASS（正常路径，非故障）
        print("SELFTEST_FETCH: {} -> (ledger absent: {}) 台账干净"
              .format(device_ip, str(e).strip()))
        _ftp_quit(ftp)
@@ -357,7 +357,7 @@ def main(argv=None):
                    help="suite names that MUST appear as '=== <name>: N/M PASSED (failed=0) ===' "
                         "with N>0, ';' separated. Empty = off")
    ap.add_argument("--require-selftest-pass", action="store_true", default=None,
-                    help="jointly judge /log/selftest.log (S7): missing/empty = PASS, "
+                    help="jointly judge /log/selftest.log: missing/empty = PASS, "
                         "any 64B record = FAIL")
    ap.add_argument("--selftest-log", default=None,
                    help="local copy of /log/selftest.log (skips device-side fetch when given)")
@@ -526,7 +526,7 @@ def main(argv=None):
    print("Port: {} @ {}  settle={}ms  max={}ms".format(
        port, args.baud_rate, args.settle_ms, args.max_wait_ms))

-    # 0.6 自检台账基线（S7「只看本次新增」）：**必须排在串口采集武装之前**。
+    # 0.6 自检台账基线（只看本次新增）：**必须排在串口采集武装之前**。
    #     /log/selftest.log 是 512 条环形累计历史，用"文件非空即 FAIL"去判一次启动，在任何
    #     做过故障注入或长跑的设备上永远不可能 PASS（本仓台架实测：抓到的 29 条记录时间戳
    #     全是 2026-10-10 ~ 10-14 留下的，与本次启动无关）。这里记下基线的最后一条记录，
@@ -698,7 +698,7 @@ def main(argv=None):
            print("RUN_TEST_ERROR: flash readback mismatch (chip content != built image)")
            return 2

-    # 5.5 自检记录判定（S7）：默认只判「本次启动新增」，累计口径要显式指定。
+    # 5.5 自检记录判定：默认只判「本次启动新增」，累计口径要显式指定。
    #     三种抓取结果必须分开对待（旧实现把后两种都当"无记录 → PASS"，就是假绿）：
    #       absent（设备侧无此文件）    → 台账干净 → 无新增 → PASS
    #       error（连不上/登录被拒/故障）→ 未知 → FAIL（要求判定却没数据，不能当通过）
@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 """verify_log.py - 对抓取的 MCU 调试日志做标记校验（纯标准库，2026-09-20 替代 verify_log.ps1）。

-用于 @test 闭环：烧录后从串口助手日志提取的开机日志交给本脚本 grep 标记，
+用于 /serial-boot-test 闭环：烧录后从串口助手日志提取的开机日志交给本脚本 grep 标记，
 输出结构化判定（格式与旧 PowerShell 版逐字一致，下游文档/习惯不受影响）。

 用法:
@@ -16,10 +16,15 @@
      [--require-order 'App init OK>Network Init>net init: OK']
      [--done-marker 'net init: OK'] [--max-boot-ms 8000] [--json]

-退出码（与旧版一致）:
+退出码（2026-10-27 task-32 起把 2 讲清楚；/serial-boot-test 那层的码不变）:
  0 = PASS（所有 Required 标记找到，Forbidden 零命中，汇总行要求满足）
-  1 = FAIL（缺 Required / 命中 Forbidden / 汇总行要求不满足）
-  2 = ERROR（日志文件不存在/不可读）
+  1 = FAIL（**设备侧真有坏消息**：缺 Required / 命中 Forbidden / 汇总行不满足 / 顺序或耗时超限）
+  2 = **测量没成立**（日志不存在或不可读；或开了 --max-boot-count 却零启动锚点 = 采集器没开、
+      日志被清、或采集没从复位开始）——这**不是**一次设备故障，按码聚合的脚本必须把它和 1
+      分开算，否则"采集断了"会被统计成"又崩了一次"。verdict 字段给 MEASUREMENT_BROKEN，
+      JSON 里 measurement.* 带三计数明细（payload_lines / boot_anchor_count / exact_hits /
+      loose_neighbours）。注意优先级：**零锚点但同时有 Forbidden 命中或自检故障记录时仍判 1**，
+      测量问题最多在旁边加一行 WARN——绝不能把真崩溃降级成"没数据"。

 默认 Required 标记对应 STM32F4-Base 启动序列（见 App/app/app_main.c + App/task/net_task.c），
 按测试用例覆盖，例如:
@@ -41,7 +46,7 @@
    命中即判 PASS，**套件是否跑到汇总行、断言数是否为 0 完全不可见**（套件中途
    挂死/复位、或 Phase 宏全关时会被误判为通过）。`--require-suite-summary`
    要求日志中出现 `=== <名称>: N/M PASSED (failed=0) ===` 且 **N > 0**。
-  - 自检记录联合判定（S7，2026-10 实机窗口；判据 2026-10-22 改为"只看本次新增"）：
+  - 自检记录联合判定（2026-10 实机窗口；判据 2026-10-22 改为"只看本次新增"）：
    `--require-selftest-pass` 对 /log/selftest.log 的本地副本（定长 64B 记录，格式见
    App/log/sys_log.h）判定。自检仅故障写盘（v1 不记通过项）：**文件缺失 / 0 字节 = 无故障
    → PASS**；存在记录 = FAIL（退出码 1），逐条打印时间戳 + 描述。
@@ -49,7 +54,7 @@
    run_boot_test.py 在烧录前取基线、启动后只把"基线之后新增"的记录写成临时副本交给本
    函数（`--selftest-scope this-run`，默认）。**抓取失败/无数据源/无法证明无新增一律由
    调用方判 FAIL**——旧实现把这些都当"无记录 → PASS"，是假绿（详见
-    docs/测试说明/自动化测试流程.md 的自检结果判定节）。
+    docs/测试说明/流程与规范/自动化测试流程.md 的自检结果判定节）。
  - 启动锚点计数（2026-10-10）：`--max-boot-count N`（run_boot_test.py 默认传 1）统计
    `reset cause:` 锚点出现次数——**0 次** = 采集没从复位开始（标记全中也可能只是上一轮
    的残留日志）；**>N 次** = 板子在采集窗口内自己复位过（IWDG 咬狗 / Fault 后
@@ -224,6 +229,31 @@ def _reset_cause_of(line, marker):
    return tail[:j] if j > 0 else tail


+# --- measurement-vs-device classification (task-32; bench-runner night rule) ---
+# Three counters decide which kind of "nothing found" we are looking at, and they must not
+# be conflated: an all-zero read is a BROKEN MEASUREMENT, not a healthy device.
+#   hits=0, loose_neighbours=0, boot anchors=0  -> measurement broke (wrong file, closed
+#       serial port, dead collector). Nothing was observed -> no verdict is meaningful.
+#   hits=0, loose_neighbours>=1                 -> the line exists but is damaged (head
+#       eaten / bytes spliced in) -> that is a real device-side defect, --exact's purpose.
+#   hits=0, loose_neighbours=0, anchors>=1      -> the boot DID happen; the marker is
+#       genuinely absent -> allowed to read as a functional miss.
+# Reported as its own exit code (2, the existing "measurement/environment did not happen"
+# family) so aggregation by exit code never counts a dead collector as a device failure.
+def classify_measurement(n_lines, boot_count, boot_check_on, exact_checked, hits, neighbours):
+    """(broken, reason). Only judges when a boot anchor check was actually requested."""
+    if not boot_check_on:
+        return False, "anchor check off (max_boot_count=0) -> cannot classify"
+    if n_lines == 0:
+        return True, "zero payload lines (collector closed / log truncated / wrong file)"
+    if boot_count == 0:
+        return True, ("log readable (%d line(s)) but ZERO boot anchor -> capture did not "
+                      "start at a reset" % n_lines)
+    if exact_checked and hits == 0 and neighbours == 0:
+        return False, "anchors present: exact markers genuinely absent (functional miss, not measurement)"
+    return False, "measurement ok (hits=%d neighbours=%d anchors=%d)" % (hits, neighbours, boot_count)
+
+
 def verify(log_path, required=REQUIRED_DEFAULT, forbidden=FORBIDDEN_DEFAULT,
           show_tail=40, out=print, suite_summary="",
           selftest_pass=False, selftest_log="",
@@ -519,6 +549,39 @@ def verify(log_path, required=REQUIRED_DEFAULT, forbidden=FORBIDDEN_DEFAULT,
        for ln in lines[-show_tail:]:
            out(ln)

+    # ---- measurement vs device (task-32) ----
+    n_exact_checked = len(exact or [])
+    n_exact_hits = sum(1 for e in (res.get("exact_ok") or []) if "hits=0" not in e["detail"])
+    n_neighbours = 0
+    for e in (res.get("exact_ok") or []) + (res.get("exact_bad") or []):
+        m = re.search(r"loose_neighbours=(\d+)", e.get("detail", ""))
+        if m:
+            n_neighbours += int(m.group(1))
+    b_on = max_boot_count > 0
+    b_cnt = (res.get("boot") or {}).get("count", 0)
+    broken, m_reason = classify_measurement(len(payloads), b_cnt, b_on,
+                                           n_exact_checked > 0, n_exact_hits, n_neighbours)
+    res["measurement"] = {"broken": broken, "reason": m_reason, "payload_lines": len(payloads),
+                          "boot_anchor_count": b_cnt, "anchor_check_on": b_on,
+                          "exact_checked": n_exact_checked, "exact_hits": n_exact_hits,
+                          "loose_neighbours": n_neighbours}
+    # A broken capture must never mask real device-side bad news: if the log carries
+    # Forbidden hits or selftest fault records, that evidence stands and we report FAIL(1)
+    # with the measurement problem noted on top of it (worst outcome = a real crash quietly
+    # re-labelled as "no data").
+    if broken and (hits or selftest_fail):
+        out("")
+        out("[WARN] capture also looks incomplete: " + m_reason)
+        out("       but device-side bad news is present -> verdict stays FAIL, not MEASUREMENT-BROKEN")
+        broken = False
+    if broken:
+        out("")
+        out("[MEASUREMENT-BROKEN] " + m_reason)
+        out("    no verdict is meaningful here -- fix the measurement first (open the port,")
+        out("    assert the collector is alive, capture from a reset). Exit 2, NOT 1:")
+        out("    a dead collector must not be counted as one more device failure.")
+        return finish(2)
+
    out("")
    if (missing or hits or bad_summary or selftest_fail or boot_issue
            or order_issue or timing_issue or exact_bad or pair_bad):
@@ -579,6 +642,19 @@ def selftest(out=print):
    chk("blind spot proven: legacy substring PASSES where --exact FAILS",
        legacy_present and not exact_ok_here, True)

+    # measurement-vs-device classification (task-32): the three-counter rule IS this function,
+    # so it is pinned here -- an all-zero read must not be reportable as a healthy device.
+    chk("measure: good capture -> not broken", classify_measurement(137, 1, True, True, 1, 0)[0], False)
+    chk("measure: zero payload lines -> broken", classify_measurement(0, 0, True, True, 0, 0)[0], True)
+    chk("measure: readable but no boot anchor -> broken",
+        classify_measurement(1, 0, True, True, 0, 0)[0], True)
+    chk("measure: anchor check off -> abstain (non-boot logs stay usable)",
+        classify_measurement(0, 0, False, True, 0, 0)[0], False)
+    chk("measure: damaged lines are device-side, not 'no data'",
+        classify_measurement(120, 1, True, True, 0, 3)[0], False)
+    chk("measure: anchors present + no neighbour = functional miss",
+        classify_measurement(120, 1, True, True, 0, 0)[0], False)
+
    bad = 0
    for name, ok, detail in cases:
        out("{} {}".format("[OK]  " if ok else "[FAIL]", name))
@@ -0,0 +1,73 @@
+---
+name: stale-doc-count-sweep
+description: 全仓陈旧计数同步 playbook——某个事实数（黄金参考页数/张数、菜单树叶数与已绑叶数、字库字数与字形数、提交钩子数等）变了之后：每个数先剔伪命中再双源互证定真值 → 全形态全命中面扫描（含 .pre-commit 钩子显示名与 .dsh/skills 正文）→ 逐条分类（当前态改 / 历史行冻结（只有保留变更记录的 5 篇真台账与 scripts/archive/ 归档） / 同数不同义不动 / 带日期戳的测量只加「当时」/ 数字对但口径描述错另起一笔）→ 每处先读现文再字面替换并断言命中数 → 全文通读核对各小节 → 提交后再按全部旧形态复扫归零 → 跑门禁分笔提交。
+whenToUse: 某个计数/数字变了要跨 md/yaml/py/txt 同步、用户说「同步一下 / 全仓改一遍 / 这个页数（张数、叶数、字形数、钩子数）不对」、怀疑某个数是伪命中或口径错了（含 notdef 吗、含 ASCII 吗、是张数还是页数）、发现文档数字与实测不符、或同一份文档两节数字/顺序对不上要先核口径时。
+---
+
+# 陈旧计数全仓同步
+
+适用：**一个事实数变了**（黄金参考 27→40→47→53→60→66、已绑叶数 22→28→30、主机单测套数 28→33→41→44、无专属钩子套数 18→19→22、字库 185/280→218/313→224/319、菜单节点行数 42→43、钩子 51→52→51→52…），仓库里多处引用它的当前态表述要跟着变，而历史记录、同数异义、带日期戳的测量**不能**跟着变。
+
+本仓已跑过四轮，照序列复跑、别临场重新发明分类：`b24b2b5f`（27→40，13 文件）、`31ca4a1f`（40→47，11 文件）、UI 补齐批（`94b0d790` 落地 → `cbb4fdb8` 产品需求同步 → `11d60057` 架构总览补漏 → `6daa01ae` 字体**口径**更正）、钩子一增一减（`1668842d`，52→51）、**第五轮 2026-10-29 录波落地**（套数 41→44、无专属钩子 19→22、黄金 60→66、菜单 42→43 节点 / 33→34 叶、已绑 28→30、字库 218/313→224/319；改动面含 `.pre-commit-config.yaml` 显示名与 `docs/门禁说明/README.md` 成对、三个 skill 正文）。
+
+## 各计数的权威口径速查（本仓实测值，动手前先对表）
+
+| 计数 | 真值来源（**至少两处互证**） | 已知伪命中 / 换算 |
+|---|---|---|
+| 内容页黄金参考**张数** | `simulator/tests/ref/` 下 `shot_*.bin` 实数（2026-10-29 实测 **66**）＝ `simulator/tests/check_content_pages.py` 的 `PAGES` 条目数（实测 **66**，其中 2 个 `_p2` 分页 → 页面 64） | 分页页要**单独再拍一张**（id 加 `_p2`，如 `runreport_p2`）→ **张数 = 页面个数 + 分页多出的张数**；两个数分开报，不许互相冒充（53 张时代的一个 12 行分页页会让 55 页变 56 张这类差 1） |
+| 已绑内容页**叶数** | `Drivers/BSP/UI/ui_page_registry.h` 的 `#define UI_PAGE_MAP_COUNT 30u`（由 `tools/menu_gen/gen_menu.py` 生成；2026-10-29 录波道绑两叶后 28→30） | `grep -c '#page=' ui_menu_tree.txt` 得 **31**：第 5 行是菜单文件**头部注释里的示例行** → 剔掉注释/模板行后的 30 才是真值 |
+| 提交**钩子数** | YAML 解析后的条目数（实测 **51**）：自查命令见 `docs/门禁说明/README.md` §2 首条；与 AGENTS.md「共 N 个钩子」、该目录 §2 标题**三数同源** | `grep -c` 配置里的声明行 = 52（多算一条**被注释掉的** clang-format 候选）；在配置**注释里复述那个 grep 字面量**会让文本计数再虚高 1 |
+| 字库**唯一字数** | `ui_cn_chars.txt` 唯一码点数（2026-10-29 实测 **224**，其中 ASCII 区 **0** 个） | `make_font.py` 的 `-r 0x20-0x7E` 是 ASCII 子集参数，**不算进字数** |
+| **字形数** | `Drivers/BSP/UI/ui_font_cn_12.c` 里 `.bitmap_index` 出现次数 **320 条含 notdef → 319 字形**；换算式 = 224 汉字/符号 + ASCII 95 = 319 | 直接报 314 就是把 notdef 当字形；文档必须写出「不含 ASCII」「含 notdef 共 314 条」这类口径句 |
+| 变更记录**保留篇数** | 变体标题感知的普查（`grep -rn "^## " docs scripts` 再看哪些标题是变更记录 / 修订记录）；当前态清单以 `docs/文档规范.md` §5.1 那行为准 | 只 grep 裸 `^## 变更记录` 会**漏算带编号与中文序号的标题**（实测 5 篇真台账里 2 篇是 `## 6.` / `## 九、`，另有 `## 修订记录` 变体）——2026-10-29 就差点把 5 改成 3 |
+| 菜单**节点数 / 叶子数** | `ui_menu_tree.txt` 头部规则：缩进即层级（每级 2 空格）、`#` 开头为注释、空行忽略；叶子 = **不存在更深缩进后继行**的行 | 43 是节点行数、34 才是叶子（2026-10-29 现值；42 / 33 是此前时点）；`未绑 = 待做 + 不做` 要与分类表逐项闭合 |
+
+## Steps
+
+1. 实测真值：先剔伪命中，再双源互证
+2. 全形态 + 全命中面扫描
+3. 逐条分类，五类各走各的路
+4. 每处先读现文，再逐条字面替换并断言命中数
+5. 一笔只装一类事
+6. 被改文件全文通读，核对其余小节
+7. 提交后再复扫一遍
+8. 跑门禁、分笔提交
+> 本节全文（逐字搬移、未改写，含命令与实测数字）→ [steps.md](reference/steps.md)。动手前先读那篇。
+
+## Pitfalls
+
+- 把伪命中计进真值
+- 字形数没剔 notdef
+- 数字对但口径描述错
+- 权威脚本乱码就臆读或退回抄文档
+- 钩子数用 grep 声明行
+- 张数与页数互相冒充
+- 只扫 docs/
+- 提交完就收工
+- 去已删掉变更记录的文档里「补一行流水」
+- 历史行被当陈旧值改掉
+- 照抄用户给的数
+- 把节点行当叶子数
+- 整文件正则批处理
+- 反引号截断
+- 只改记得的那节
+- 误报跟着改
+- 带日期戳的测量臆改新数
+- 用截断的 grep 输出判定
+- 新写文本撞编号门禁
+> 本节全文（逐字搬移、未改写，含命令与实测数字）→ [pitfalls.md](reference/pitfalls.md)。动手前先读那篇。
+
+## Verification
+
+提交前逐条打勾；回报时**逐处列文件 + 命中数断言**，不要笼统说「已全部更新」。
+
+- [ ] 每个数都写了**两个独立来源**且数值一致（`ref/shot_*.bin` 实数 ＝ `PAGES` 条目数；`UI_PAGE_MAP_COUNT` ＝ 剔伪命中后的 `#page=` 计数），并在结论里贴出该数字与伪命中取舍理由
+- [ ] 字形数说明**是否剔除 notdef**并给出条目数→字形数的换算（条目数 − 1 = 字形数，2026-10-29 现值 320 − 1 = 319）；字数说明**是否含 ASCII**，且该口径句与实测一致
+- [ ] 分类表逐条列出：改了哪些当前态、哪些历史行保留、哪些误报不动（附理由）、哪些只加「当时」、哪些属**口径错**并已另起一笔
+- [ ] 替换脚本打印了每处 `old -> new xN` 且每处 `assert` 通过（无半落地；报错时已 `git diff --stat` 确认零写入）
+- [ ] 命中面覆盖 `.pre-commit-config.yaml` 钩子 `name:`、AGENTS.md、`docs/**`、`scripts/**`、`.dsh/skills/*/SKILL.md`，逐条在改动清单里出现
+- [ ] 被改文件已全文通读，同文档各小节与配套 README/清单的顺序、计数、完成状态一致；口径闭合（如 `未绑 = 待做 + 不做`）
+- [ ] 变更记录：**保留的 5 篇真台账**（清单 → `docs/文档规范.md` §5.1）历史行原文未动；其余文档本轮**零新增流水行**（当前态改完即止）；钩子一增一减这类过程细节写进提交正文，不写进文档
+- [ ] **提交后**又按全部旧形态复扫一次，当前态残留 = **0**，每条剩余命中都能归类（历史行 / 误报 / 已加「当时」）；发现的漏网当前态已单独补一笔
+- [ ] `check_doc_links.py --all --sections-strict` 打印「文档路径检查通过（N 个文档）」；`ci_local.py` / `pre-commit` 全绿（RC=0、`failed=0`）；BOM 与原文件一致、无 `EF BF BD`
+- [ ] 分笔提交完成，回报 commit 号 + 每笔改了哪些文件 + 没动的那几类及理由
@@ -0,0 +1,24 @@
+# Pitfalls（自 SKILL.md 外置）
+
+> 本文由 stale-doc-count-sweep 的 SKILL.md「Pitfalls」一节逐字外置而来（渐进展开：主文件只留索引与指针）。步骤号沿用原文，未重编。
+
+- **把伪命中计进真值**：`grep '#page='` 的首条是菜单文件头部注释里的示例行，29 里含它；真值是注册表 `UI_PAGE_MAP_COUNT` 的 28。任何「数出现次数」式计数，先打印全部命中逐条看，剔注释行/模板行/示例行。
+- **字形数没剔 notdef**：`.bitmap_index` 314 条里第 1 条是 notdef，字形数是 **313**；照抄 314 就把占位符当成了字形。
+- **数字对但口径描述错**：218 这个数两处都对，错在「含 ASCII/符号」这句口径（实测 218 个码点全为非 ASCII）。它不进任何数字 diff，只能逐句读口径句；且必须**另起一笔**，混进数字同步那笔会让 review 者以为只是顺手改措辞。
+- **权威脚本乱码就臆读或退回抄文档**：Windows 代码页下 `font-charset` 的整行输出退化成 U+FFFD 替换字符时，改数源文件符号出现次数，别猜、别抄旧文档。
+- **钩子数用 `grep` 声明行**：多算一条注释掉的候选钩子（51 变 52）；反过来在配置注释里复述那个 grep 字面量会让文本计数再虚高 1。口径只认 YAML 解析后的条目数，且要与 AGENTS.md、`docs/门禁说明/README.md` §2 标题、`ci_local.py` 实跑 passed+failed+skipped 三数同源。
+- **张数与页数互相冒充**：一个 12 行分页页第 2 页要单独拍一张，于是「+2 页」可能等于「+3 张」。两个数分别报、分别换算，别互相顶替。
+- **数篇数只 grep 裸标题**：`^## 变更记录` 漏掉 `## 6. 变更记录`、`## 九、变更记录`、`## 修订记录` 三种写法 → 篇数直接少数一半，拿这个错数去"同步"全仓就是把对的改成错的（2026-10-29 实测：5 篇真台账只数出 3 篇，改到第 10 处才发现）。普查一律 `grep -rn "^## " docs scripts` 再看标题，或直接读 `docs/文档规范.md` §5.1 那行的例外清单。
+- **只扫 docs/**：漏 `.pre-commit-config.yaml` 钩子 `name:` 显示名里的页数、AGENTS.md 钩子清单、`.dsh/skills/*/SKILL.md` 自带的计数与脚本路径（skill 正文也是命中面：font-regen 的 179/274 本窗最后才改）。
+- **提交完就收工**：第 7 步的提交后复扫才是把漏网当前态（架构总览 §3）揪出来的那一步；漏了它，仓库里就留下一行「当前态写旧数」直到别人再扫。
+- **去已删掉变更记录的文档里「补一行流水」**：2026-10-29 起全仓只剩 **5 篇**真台账保留变更记录表（清单 → `docs/文档规范.md` §5.1），外加 `scripts/archive/` 归档；其余文档**没有这一节**。计数同步**只改当前态**、过程交给 `git log`，别再到别的文档里找或加变更记录行。真要往那 5 篇的台账里加行，历史坑照旧：它们的表按日期**升序** → 新行**追加为末行**，插表顶会把首行「初版」挤成第二行。
+- **历史行被当陈旧值改掉**：「47 → 53 页」是当天事实，改了就是伪造历史；正确动作是**只改当前态那几处**、历史行一个字不动（保留变更记录的 5 篇真台账要写台账也只追加、不回改）。**历史行被写坏**时按无反引号兜底写法整行重写，别用同样写法再改一遍。
+- **照抄用户给的数**：用户说「从 40 扩到 47」也要自己数 `ref/*.bin`；数出来不一定是 47。
+- **把节点行当叶子数**：42 是 `ui_menu_tree.txt` 的节点行数、33 才是叶子；不读文件头规则就数错（实测把错数写进两份文档，下一轮才自查出来）。
+- **整文件正则批处理**：第一次尝试的正则没编译过、整批零落地。改法 = 逐条字面替换 + 每处 `assert count == expect`。
+- **反引号截断**：脚本里含 `ui-golden`、`#page=` 这类反引号时，经 TS 模板字符串/内嵌 heredoc 传递会被截断，表现为「整批零落地」或「历史行写坏」。落成脚本文件再执行，或用 `chr(96)` / `String.fromCharCode(96)` 拼。
+- **只改记得的那节**：上一笔只改 §2 与开篇、漏改 §1，用户当场问出「§1 说 16 叶、§2 说剩 3 项，自相矛盾」。改完必须全文通读同一文档所有小节。
+- **误报跟着改**：「< 40KB」是绘制缓冲红线，与页数无关。
+- **带日期戳的测量臆改新数**：「2026-10-26 实跑 …覆盖 40 页」改成 47 就是把历史测量冒充现值；只加「当时」。
+- **用截断的 grep 输出判定**：`cut -c` 截掉的后半句常含日期戳/口径，据此分类必错。
+- **新写文本别再造编号**：两道编号门禁都已退役（全库八项校验 2026-10-28、只查新增行 2026-10-29，脚本与白名单在 `scripts/archive/id_gate/`），**撞号不再有机器报警**，只剩规范与评审——所以这批文本的形态自查要自己做（`docs/编号规范.md` §1 三句；要机器帮忙就手工跑 `scripts/archive/id_gate/check_ids_new.py --worktree`）。
@@ -0,0 +1,88 @@
+# Steps（自 SKILL.md 外置）
+
+> 本文由 stale-doc-count-sweep 的 SKILL.md「Steps」一节逐字外置而来（渐进展开：主文件只留索引与指针）。步骤号沿用原文，未重编。
+
+1. **实测真值：先剔伪命中，再双源互证**（不抄用户口述、不抄另一处文档）。逐数走上面那张表；两个来源对不上时**先找分歧根因**（把全部命中逐条打印出来看），不要取第一个、不要取平均，并在结论里写明分歧与取舍（实测：菜单 `#page=` 计数 29 对 注册表 28，根因是头部注释示例行）。
+
+   ```bash
+   cd "<repo>"
+   ls simulator/tests/ref/shot_*.bin | wc -l                     # 张数（判据 = 入库实数）
+   awk '/^PAGES = \[/,/^\]/' simulator/tests/check_content_pages.py | grep -cE '^ *\("'   # 页数（第二个来源，两者必须一致）
+   grep -n '#page=' ui_menu_tree.txt | head -3                    # 先看首条是不是注释示例行，再定叶数
+   grep -rn 'UI_PAGE_MAP_COUNT' Drivers/BSP/UI/ui_page_registry.h  # 已绑叶数（生成物）
+   grep -c '\.bitmap_index' Drivers/BSP/UI/ui_font_cn_12.c         # 314 = 含 notdef；字形 = 该数 - 1
+   & '.venv\Scripts\python.exe' -c "import yaml;d=yaml.safe_load(open('.pre-commit-config.yaml',encoding='utf-8'));print(sum(len(r['hooks']) for r in d['repos']))"   # 钩子数口径
+   ```
+
+   ⚠ **权威脚本输出乱码时**（`check_font_charset.py` 在 GBK 代码页下整行打印成 U+FFFD 替换字符串 + `: PASS`，数字全读不出来），**改为直接数源文件里符号出现次数**（`.bitmap_index` / `.range_start` / 码点唯一化）——不许臆读乱码，也不许因此退回去抄文档里的旧数。
+
+2. **全形态 + 全命中面扫描**。一个数一次列出它全部历史形态，别只扫当前旧值：本轮 = `122/217`、`179/274`、`185/280`、`47 → 53`、`53 → 60`、`PAGES = 53`、`UI_PAGE_MAP_COUNT = 22`、`已绑 22 叶`、`未绑 11`、`内容页 53 页`。
+
+   ```bash
+   grep -rn --include=*.md --include=*.py --include=*.yaml --include=*.txt --include=*.c --include=*.h \
+     -E '122 唯一字|217 字形|179 汉字|274 字形|185 唯一字|280 字形|47 → 53|53 → 60|内容页 53|PAGES = 53|UI_PAGE_MAP_COUNT = 22|已绑 22|未绑 11' . \
+     | grep -v -E '^\./(ci-artifacts|\.mnemon|\.dsh/runs)/'
+   ```
+
+   **命中面比「文档」宽**，至少包含：`docs/**`、`AGENTS.md`、`.pre-commit-config.yaml`（**钩子 `name:` 显示名内嵌页数**：`name: UI 像素回归（菜单 8 状态 + 内容页 60 页 黄金参考）` 就是命中点）、`scripts/*.py`、`simulator/**/README.md`、以及 **`.dsh/skills/*/SKILL.md`**（本窗 `font-regen` 正文自带 179/274 计数，直到 step 150 才发现；编号门禁退役那轮 `id-family-semantic-migration`、`task-worktree` 两个 skill 正文与 `scripts/README.md` 同样是引用面）。
+
+   先列出 `文件:行:全文`，**判定前必须看整行**——`cut -c1-120` 会截掉后半句（那里常写着日期戳或口径）。
+
+3. **逐条分类，五类各走各的路**（本 playbook 的核心，别用一条规则套全部命中）：
+
+   | 类别 | 判定 | 动作 |
+   |---|---|---|
+   | 当前态陈述 | 描述「现在是多少」 | 改成实测真值 |
+   | 变更记录历史行 | 形如「47 → 53 页」的当日事实 | **原样冻结不回改**——但这条**只适用于保留变更记录的 5 篇真台账**（台账 / 被别处当唯一证据出处的文档，清单 → `docs/文档规范.md` §5.1）与 `scripts/archive/` 归档；其余文档没有变更记录节，**不再追加任何流水行**，数字同步只改**当前态** |
+   | 同数不同义 | `最坏路径 < 40KB` 这类内存/绘制缓冲红线 | **不动**，并在结论里写明「为什么不动」 |
+   | 带日期戳的测量 | 「2026-10-26 实跑 …覆盖当时 40 页中的」 | **不臆改新数**，只补「当时」两字锁口径；新数留待下次实跑回填 |
+   | 数字对但**口径描述错** | 数没错、句子把口径讲错了（实测：写「218 字（含 ASCII/符号，共 313 字形）」，而 `ui_cn_chars.txt` 的 218 个码点**全为非 ASCII**） | **另起一笔只改口径的提交**（`6daa01ae`），不与数字同步混笔；这类命中在任何数字 diff 里都看不见，只能把口径句逐句读一遍 |
+
+   拿不准就回到第 2 步把整行打印出来再判；判错历史行 = 把当天事实改成假账。
+
+4. **每处先读现文，再逐条字面替换并断言命中数**（弃用整文件正则批处理）。本窗两度返工都是没先读现文：step 45 断言 `HIT 0` 抛错（目标串与现文不一致），step 44 是脚本语法错。脚本写成临时文件再跑（内嵌 heredoc/模板字符串里的反引号会截断整脚本），按**字节**替换以保 BOM 与行尾不动：
+
+   ```python
+   import pathlib, sys
+   sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+   JOBS = [  # (文件, old, new, 期望命中数)
+       ('AGENTS.md', '内容页 53 页黄金参考', '内容页 60 页黄金参考', 1),
+       ('.pre-commit-config.yaml', '内容页 53 页 黄金参考', '内容页 60 页 黄金参考', 1),
+       ('docs/架构设计/项目架构总览.md', '122 字/217 字形', '218 字/313 字形', 1),
+       ('docs/UI设计/UI_自动化测试流程.md', '文本断言 **310 条**、覆盖 40 页中的', '文本断言 **310 条**、覆盖当时 40 页中的', 1),
+   ]
+   for path, old, new, expect in JOBS:
+       p = pathlib.Path(path); raw = p.read_bytes()
+       o, n = old.encode('utf-8'), new.encode('utf-8')
+       got = raw.count(o)
+       assert got == expect, f'{path}: 命中 {got}，期望 {expect}（未写入）'
+       assert o != n, f'{path}: old 与 new 相同'
+       p.write_bytes(raw.replace(o, n))
+       print(f'OK {path}: {old} -> {new} x{got}')
+   ```
+
+   每行打印 `old -> new xN`，收口时这串输出就是「改了哪几处」的账。脚本报错/没编译过，**先 `git diff --stat` 确认零写入**再换写法（不要在半落地状态上叠改）。
+
+   - **反引号**：TS 侧先用可见占位符（如 `~TB~`）写文本，落盘前再还原成真反引号 —— `const BT = String.fromCharCode(96); const q = s => s.split(TOKEN).join(BT)`（本窗实测：直接把带反引号的串塞进模板字符串/heredoc，整批零落地或把变更记录行写坏）。用 `tools.edit` 批量改时同样先 `await tools.read` 现文再传 `old_string`；批量里若某条 `old_string` 与 `new_string` 相同会报 `must differ` —— **只有该条作废、其余已落盘**，别整批重跑。
+   - **历史行被写坏**（反引号及紧随其后的字符经工具传递被吞 → 变更记录行只剩半行、尾部出现 `??` 这类残迹）：立刻按**无反引号兜底写法整行重写**——裸词 `accident / oper / alarm / start / yk`、页面绑定写成不带反引号的 `#page=`——而不是拿同样带反引号的串再改一遍（实测连返工三次：step 81→82→83→85）。
+
+5. **一笔只装一类事**。数字同步一笔（`cbb4fdb8`：11 处 + 变更记录一行）；口径更正另起一笔（`6daa01ae`）；提交后复扫逮到的漏网当前态再补独立一笔（`11d60057`）。钩子一增一减写成一个当日行的两个阶段（51 → 52 加 `id-check-new`、随即 52 → 51 摘 `id-check`），别写两行互相打脸。提交说明如实写（「先认一笔自己的错：上一笔的未绑 21 叶是探针错」），别把口径修正包装成「补充说明」。
+
+6. **被改文件全文通读，核对其余小节**——不是只看 diff。同一文档内互相引用的小节必须一致（本窗产品需求：§2.4 立项未排、§5.14 FR-SOE-3、§8.2 绑定现状、§8.3 已绑分页表、§9.1 差距表、§9.2 顺序表六处同时引用这四个数；`docs/任务规划/README.md` §1 当前执行表 vs §2 全项目顺序表）。若发现上一笔自己写进文档的数**口径就错了**，明确认错并改正，同时把**可复核的重算方法**写进文档（「按缩进判叶子：有更深缩进后继者即非叶子」），防止再错。
+
+7. **提交后再复扫一遍**（收尾硬步骤，不许省，也不许只在提交前扫）。按第 2 步的**全部**旧形态整仓再扫一次，逐条分类为 当前态 / 历史行 / 同数不同义：本窗 `cbb4fdb8` 提交后复扫得 14 条命中，12 条以上都在变更记录历史行（`47 → 53`、`53 → 60`、`122/217` 冻结），**唯一残留的当前态命中**是 `docs/架构设计/项目架构总览.md` §3「界面层」那行 → 单独补一笔 `11d60057`。说不出归属的就是漏改。
+
+   ```bash
+   grep -rn -E '22 叶|未绑 11|11 叶|53 页|122 唯一字|217 字形|185 唯一字|280 字形|内容页 53|PAGES = 53|UI_PAGE_MAP_COUNT = 22' \
+     . | grep -v -E '^\./(ci-artifacts|\.mnemon|\.dsh/runs)/'
+   ```
+
+8. **跑门禁、分笔提交**（`git commit` 属 Ask first，须用户明确指示后再做）：
+
+   ```bash
+   & '.venv\Scripts\python.exe' scripts/check_doc_links.py --all --sections-strict   # 期望「文档路径检查通过（N 个文档）」
+   & '\.venv\Scripts\python.exe' scripts/archive/id_gate/check_ids_new.py --range A..B   # 编号形态普查（两道门禁 2026-10-28 / 2026-10-29 都已退役，不再是提交钩子）
+   & '.venv\Scripts\python.exe' scripts/ci_local.py                                    # 或 pre-commit run --files <被改文件>
+   ```
+
+   PowerShell 形态把 `./.venv/Scripts/python.exe` 换成 `& '.venv\Scripts\python.exe'`。提交信息一律 `git commit -F <UTF-8 无 BOM 文件>`，别用 `-m`（中文长标题易超 100 字符、终端代码页会转码）；标题 ≤100、**正文每行 ≤80**（实测把正文压到 66/78 字符才过 gitlint）。
@@ -47,7 +47,7 @@ whenToUse: 需要向 STM32 目标烧录 .hex/.bin、只复位重启目标、校
  被拒，本 skill 会打印 `RESET_NOTE` 并**自动降级**为这条系统复位（仍按降级结果给 rc）。
 - 探针在位先 `list`；`Programming Complete` 但行为像旧固件 → 先怀疑缺 `-Rst -Run`，
  再怀疑 hex 没重编（对比 hex 时间戳）。
- 完整复位语义/故障排查（本仓库）：`docs/测试说明/ST-LINK_CLI_复位使用说明.md`。
+- 完整复位语义/故障排查（本仓库）：`docs/测试说明/测试工具/ST-LINK_CLI_复位使用说明.md`。

 ## 与其它 skill 的衔接

@@ -1,166 +1,104 @@
 ---
 name: task-worktree
-description: 多任务并行开发的空间管理（git worktree 生命周期）：new 开一棵工作树 + 任务分支、目录联接共享 .venv 与模拟器 SDK、活跃任务硬上限 3 与腾位、build/bench 两类独占锁（含非登记任务占锁后「缺台账」释放不掉的正解）、done 预演合并回主干、门禁未全绿的补基线收尾、并集合并残留审计。规格见 docs/环境与部署/并行任务工作树方案.md。
-whenToUse: 要同时推进多个任务、担心同分支同文档互相冲突；要为新任务开一个隔离空间；要把任务合并回主干；或遇到 `new` 报「已有 3 个活跃任务（上限 3）」、`lock release` 报「任务 X 不存在（缺台账）」、`done` 报「门禁未全绿：工作树与分支保留，未清场」、两个任务抢 COM6 / UV4、"改了文档被覆盖"、并集合并残留时。
+description: >-
+  并行开发的空间管理（git worktree 生命周期；`@task` 只是文档别名不是可执行命令，DSH 会话显式调用 `/task-worktree`）：开任务树与分支、联接共享 `.venv` 与模拟器 SDK、build/bench 独占锁、并发上限与腾位（A）、放不掉的锁（B）、`done` 是合并点不是查看器与补绿链（C）、主树被别的会话弄脏时的手工合并（C2）、门禁指标异常的净室归因（D）、回收非登记树与悬挂台账（E）、与 DSH worktree 插件共存及联接分级（F）、树内跑门禁与消息禁词（G）、树内自查与合并后补绿命令化（`precheck` / `postmerge`）。规格 = docs/环境与部署/并行任务工作树方案.md；深规程全文在 reference/。
+whenToUse: >-
+  要为新任务开隔离空间、同时推进多个任务、把任务合回主干或回收工作树；或撞到 `new` 报「已有 8 个活跃任务（上限 8）」、`lock release` 报「任务 X 不存在（缺台账）」、`done` 报「门禁未全绿」或「主工作树不干净」而那份脏改动是别的会话/插件留的、两个任务抢 COM6 或 UV4、并集合并残留；或在任务树里跑门禁写输出报 ENOENT、`--all` 的问题全在 `simulator/SDL2` 联接下；或门禁指标异常增长查不出哪个文件造成；或要回收 `list` 台账看不到的树、清 branch/path 都已不存在的悬挂台账；或要确认插件树里 `.venv` 与 `simulator/SDL2` 哪个必须补；或要改并行上限这个数字并同步全仓口径。
 ---
+# task-worktree — 多任务并行开发空间（`@task` 仅为文档别名；DSH 显式调用 `/task-worktree`；可执行形态见「固定命令」）

-# task-worktree — 多任务并行开发空间（短命令 `@task`）
+- **执行体** = `.dsh/skills/task-worktree/scripts/task_worktree.py`（纯标准库；拷整个 skill 目录即可换项目用）。
+- **深规程全文在 reference/ 下：做 C2 / D / E / F / G 任何一条之前先把对应那篇读完**——本文只留判得出来「要不要读」的判据。
+- 为什么这么拆：本文件受 dsh-mnemon 写侧上限 **65536 字节**（`skill-size` 钩子 49152 告警；实测 72,601 字节的技能照常可读可提交，只是自进化每次「生成草案」被拒、永久卡在「生成中」）→ **新增深规程进 reference/，本文只加判据**。瘦身前 frontmatter 原文 → [frontmatter-history.md](reference/frontmatter-history.md)。

-**执行体 = 本 skill 自带脚本** `.dsh/skills/task-worktree/scripts/task_worktree.py`
-（纯标准库，任意 python3；拷整个 skill 目录到别的项目即可用）。
+## 症状 → 去哪一节

-```powershell
-# cwd = 仓库根（或任意子目录）
-& $PY ".dsh\skills\task-worktree\scripts\task_worktree.py" <子命令> [参数]
-```
-
-bash（`ops_bash`）里固定两个变量，下文用 `$TW` 代指脚本：
-
-```bash
-PY=".venv/Scripts/python.exe"; TW=".dsh/skills/task-worktree/scripts/task_worktree.py"
-"$PY" "$TW" list
-```
-
-退出码：`0`=成功 / `1`=操作失败 / `2`=前置或环境错误 / `3`=用法。
-**⚠ 这几个码只有「不接管道」时才读得到**——原因与对策见「读输出」一节。
+| 现场 / 目标 | 去 |
+|---|---|
+| 开新树 / 看全景 / 追平主干 / 放弃任务 | 固定命令、典型流程 |
+| `new` 报「已有 8 个活跃任务（上限 8）」 | **A** |
+| `lock release` 报「任务 X 不存在（缺台账）」，锁照旧挂着 | **B** |
+| `done` 做了什么、红了怎么补绿、能不能反悔、怎么算「真完成」 | **C** |
+| `done` 报「主工作树不干净」，而那份脏是别的会话/插件留的 | **C2** → [merge-dirty-main-tree.md](reference/merge-dirty-main-tree.md) |
+| 门禁指标异常增长要逐文件归因（主树全程只读） | **D** → [clean-room-measure.md](reference/clean-room-measure.md) |
+| `list` 台账里没有的树要回收 / detached / 有在飞内容 / 悬挂台账 | **E** → [reclaim-unregistered.md](reference/reclaim-unregistered.md) |
+| 插件树缺联接、锁归属 `pw:<name>`、「有插件为何还自持生命周期」 | **F** → [dsh-plugin-bridge.md](reference/dsh-plugin-bridge.md) |
+| 树内写门禁输出 ENOENT、`--all` 假红、写提交/合并信息、字节体检 | **G** → [gates-in-tree.md](reference/gates-in-tree.md) |
+| 收工前树内自查、或合并后体积凭证/台账红了想一条命令补绿 | `precheck` / `postmerge`（固定命令表 + C 节第 5~6 步） |
+| 退出码读到 0 其实是 2、`tail` 之后误判「有冲突」 | 读输出 |
+| 谁不许跑 `done`/`abort`、清场前必做什么、任务期哪些文件不许改 | 铁律 1–9 |
+| 收工前最后一遍自查（各节该留什么证据）／全部实测坑 | [verification.md](reference/verification.md) ／ [pitfalls.md](reference/pitfalls.md) |

 ## 固定命令

+```bash
+PY=".venv/Scripts/python.exe"; TW=".dsh/skills/task-worktree/scripts/task_worktree.py"
+"$PY" "$TW" <子命令> [参数]    # PowerShell：& $PY ".dsh\skills\task-worktree\scripts\task_worktree.py" <子命令>（cwd = 仓库根或任意子目录）
+```
+
 | 命令 | 作用 |
 |---|---|
-| `new <ID> <slug>` | 建分支 `task/<ID>-<slug>` + 工作树 + 共享联接 + 台账；打印新空间路径 |
-| `list` | 所有任务一览：分支 / 落后领先 / 脏文件数 / 台架状态 + 两个锁的归属 |
-| `status <ID>` | 单任务详情（未提交清单、相对基线漂移、台架记录、已建联接） |
-| `sync <ID>` | 在任务工作树里 `rebase` 追平主干，把冲突控制在任务分支上 |
-| `lock acquire|release|status <build|bench>` | 独占资源锁 |
+| `new <ID> <slug>` | 建分支 `task/<ID>-<slug>` + 工作树 + 共享联接 + 台账，打印新空间路径 |
+| `list` | 分支 / 落后领先 / 脏文件数 / 台架状态 + 两把锁归属。**只遍历台账** → 非登记树看不见（E 节） |
+| `status <ID>` | 未提交清单、相对基线漂移、台架记录、已建联接 |
+| `sync <ID>` | 在任务树里 `rebase` 追平主干，把冲突留在任务分支上 |
+| `lock acquire|release|status <build\|bench>` | 独占资源锁（→ 铁律 3、B 节） |
+| `plugin list|adopt|unadopt [插件树名]` | 插件桥：看清单 / 补共享联接 / 摘联接（**不删树**）→ F 节 |
 | `done <ID>` | 预演 → 合入主干 → 并集残留审计 → 重生成产物 → 门禁 → 清场 |
-| `abort <ID>` | 放弃任务（工作树 + 分支一起删，**永久丢弃**） |
+| `abort <ID>` | 工作树 + 分支一起删，**永久丢弃** |
+| `precheck` | 树内自查（**只读**）：BOM 漂移 / CR / U+FFFD + docs 逐档门禁 + `--msgfile --ban` 消息检查；顺手补 `ci-artifacts/`（G 节机械项） |
+| `postmerge` | 主树合并后补绿：体积凭证**自动诊断**（新鲜跳过；红→先短链 `--update`，只读复检真漂了才升全链）+ `check_doc_links --all` + 列待提交文件，**不代提交** |

-`new` 常用开关：`--base <分支>`（默认 `v2-on-ui`）· `--needs-bench`（无台架 PASS 则 `done` 拒合）·
-`--lean`（跳过 Git LFS smudge）· `--no-bootstrap`（不建联接）·
-`--force`（**仅跳过并发上限 3 的检查**，不解决「谁该让位」，见 A 节）。
-
-`done` 常用开关：`--dry-run`（只预演，零改动）· `--skip-build` · `--skip-gates` · `--force`（清场时强制移除工作树）。
-
-`lock` 开关：`--task <ID>`（acquire 必填）· `--wait <秒>` · `--ttl <小时>`（自报窗口）· `--note <文本>` ·
-`--bench-pass`（release 时给台账记 PASS）· `--force`。
-⚠ `--note` 只在 **acquire** 时写进锁 payload，**release 时被忽略**——别指望它留下验收证据（证据写进主干提交说明或文档）。
-
-**环境变量**（高级）：`DTU_WT_ROOT`（任务容器位置，默认仓库同级 `_wt/`）·
-`DTU_TASK_BASE`（默认基线分支，默认 `v2-on-ui`）·
-`DTU_INTEGRATION_WORKTREE`（集成点，默认主工作树——用于隔离演练/测试）。
+- **退出码** `0` 成功 / `1` 操作失败 / `2` 前置或环境错误 / `3` 用法——**只有不接管道才读得到**（→ 读输出）。
+- `new`：`--base`（默认 `v2-on-ui`）· `--needs-bench`（无台架 PASS 则 `done` 拒合）· `--lean`（跳 LFS smudge，只省磁盘不省时间）· `--no-bootstrap`（不建联接）· `--force`（**只跳过并发上限检查**，不解决谁让位 → A）
+- `done`：`--dry-run` · `--skip-build` · `--skip-gates` · `--force`。⚠ `--dry-run` **只保护预演段、不保护清场段**（实测：对已合入的分支它照样摘联接、删分支、清台账；且它的前置也要抢 `build` 锁）→ 用完复验 `git worktree list`，细节 → 陷阱清单。
+- `lock`：`--task`（acquire 必填）· `--wait <秒>` · `--ttl <小时>`（默认 `build`=1h / `bench`=6h，超期视为陈旧、下次 acquire 自动接管）· `--note` · `--bench-pass` · `--force`。⚠ `--note` 只在 **acquire** 写进 payload，**release 时被忽略** → 验收证据写主干提交说明或文档。
+- 环境变量：`DTU_WT_ROOT`（默认仓库同级 `_wt/`）· `DTU_TASK_BASE`（默认基线）· `DTU_INTEGRATION_WORKTREE`（集成点，用于隔离演练）。

 ## 典型流程

-```powershell
-& $PY ".dsh\skills\task-worktree\scripts\task_worktree.py" new N21 dhara-isfree --needs-bench
-# → 把新会话的工作目录切到打印出来的 _wt/N21-dhara-isfree/，在那里干活
-
-& $PY ".dsh\skills\task-worktree\scripts\task_worktree.py" lock acquire bench --task N21
-# 烧录 / @test / 板级套件……
-& $PY ".dsh\skills\task-worktree\scripts\task_worktree.py" lock release bench --task N21 --bench-pass
-
-# 回到主工作树执行回收
-& $PY ".dsh\skills\task-worktree\scripts\task_worktree.py" done N21
+```bash
+"$PY" "$TW" new N21 dhara-isfree --needs-bench   # 把新会话工作目录切到打印出来的 _wt/N21-dhara-isfree/
+"$PY" "$TW" lock acquire bench --task N21        # 烧录 / /serial-boot-test / 板级套件
+"$PY" "$TW" lock release bench --task N21 --bench-pass
+"$PY" "$TW" done N21                             # 回主工作树（铁律 1）；先 --dry-run 读全量
 ```

 ## 读输出：管道与截断（两起误判的共同根因）

-1. **`... 2>&1 | tail -N` 的退出码是 `tail` 的，恒为 0** → 脚本的 `1` / `2` 全被吞。实测三条印着
-   「rc=0」的输出其实都是 exit 2：`new` 撞活跃上限、`lock release` 缺台账两次。
-   所以**判据先看文本**（`[ok]` / `!!` / `前置/环境错误：` / `失败：`），要真码就**直接执行不接管道**或补一句
-   `echo RC=$?`；坚持接管道就在 bash 里取 `${PIPESTATUS[0]}`。
-2. **`done` / `done --dry-run` 的输出不要用 `tail -2` 截**：接管道时 python 的 stdout 是块缓冲、git
-   子进程的 stderr 不缓冲，两股流错位混排，`tail -2` 只剩「--dry-run：到此为止…」加上 stderr 里带
-   `conflict` 字样的片段 → 据此误判「有冲突」。实测：`tail -2` 误读成 conflict，放宽到 `tail -10` 才看到
-   `[ok] 无冲突，预演结果树 <sha>`。dry-run 全文只有 5~8 行，直接读全量。
+1. **`| tail -N` 之后的退出码是 `tail` 的，恒 0** → 脚本的 1/2 全被吞（实测三条「rc=0」真码都是 2）。判据先看文本（`[ok]` / `!!` / `前置/环境错误：` / `失败：`），要真码就**不接管道**或取 `${PIPESTATUS[0]}`。
+2. **`done` 的输出别 `tail -2`**：管道下 python stdout 块缓冲、git 子进程 stderr 不缓冲，两股流错位 → 只剩尾部那句「--dry-run：到此为止…」加带 `conflict` 字样的 stderr 片段，据此误判「有冲突」。dry-run 全文 5~8 行，**读全量**。

-## 分步操作（三条运行时机制）
+## 分步操作（节号 A–G/C2、各节步骤号与铁律编号被 reference/ 与 docs 引用，**不许重排**）

-### A. `new` 被拒「已有 3 个活跃任务（上限 3）」——怎么腾位
+### A. `new` 撞并发上限 → 腾位

-1. 读原文：`前置/环境错误：已有 3 个活跃任务（上限 3）；先 done/abort，或加 --force`（exit 2）。
-   上限是脚本常量 `MAX_CONCURRENT = 3`；**「活跃」的判据 = `_wt/.state/<ID>.json` 台账存在，且台账里
-   `path` 指向的目录还在**（手工删了工作树目录就不占名额，但会留下悬挂台账，见第 5 步）。
-2. `$TW list` 看全景（分支 / 落后领先 / 脏文件数）决定谁让位：**已完成的先 `done`**（合并回收，一步不省）。
-3. 没人认领、零提交、尚未 claim 的空闲树 → `abort <ID>` 腾位（实测就是 abort 掉排在后面的空闲树换出名额）。
-   `abort` = 工作树 + 分支一起删、**永久丢弃**；工作树有未提交改动或已有提交时脚本会拒绝，确认可弃再加 `--force`。
-4. 确实要同时开第 4 棵才 `new <ID> <slug> --force`：磁盘代价约 **83 MB/棵**（`--lean` 约 45 MB），
-   并行度上去了、**冲突面与台架排队也一起上去**——不是免费的。
-5. **别用手工 `git worktree remove` 腾位**：台账不会被删（下次 `new` 同 ID 会报「任务 <ID> 已存在」），
-   还绕过了「先摘联接」（铁律 5），有让 git 递归进联接把主工作树 `.venv` 删掉的风险。
-6. 腾位后复验：`$TW list` 的条目数与 `ls _wt` 的目录数一致，再 `new`。
+1. 认原文 `前置/环境错误：已有 8 个活跃任务（上限 8）；先 done/abort，或加 --force`（exit 2）。「活跃」= `_wt/.state/<ID>.json` 在且台账 `path` 目录还在 → **手工删目录不占名额、但留悬挂台账**（E 第 6 步）。
+2. `$TW list` 定谁让位：**已完成的先 `done`**（合并回收一步不省）。
+3. 无人认领、零提交、未 claim 的空闲树 → `abort <ID>`；有未提交或有提交时脚本会拒，确认可弃才 `--force`。
+4. 真要第 9 棵才 `--force`：并行度上去，**冲突面与台架排队一起上去**（每棵磁盘代价见铁律 6）。
+5. **别用手工 `git worktree remove` 给登记任务腾位**：台账不删（同 ID 报「任务已存在」）、又绕过「先摘联接」（铁律 5），有让 git 递归进联接删掉主树 `.venv` 的风险。要回收的是**非登记树**（`list` 里没有它）→ **E 节**。
+6. 复验：`list` 条目数 == `ls _wt` 目录数，再 `new`。

-### B. 自己占的锁没有台账：`lock release` 报「任务 X 不存在（缺台账）」
+### B. 非登记持有者的锁放不掉

-**症状**（lead 在主工作树跑台架验收窗，用临时名占锁：`lock acquire bench --task acceptwin`）：
+症状：`lock release bench --task acceptwin --bench-pass`（带 `--force` 同）报 `前置/环境错误：任务 acceptwin 不存在（缺台账 _wt/.state/acceptwin.json）`，**锁照旧挂着**。根因：`release` 带 `--bench-pass` 就先 `load_state(task)`，而 `acquire` 侧不查台账 → 「释放」被「记账」挡死；锁没放，`done` 的 `release_stale_locks()` 对未到 TTL 的活锁判失败 → **一个没登记的名字挡住所有任务收口**。

-```
-"$PY" "$TW" lock release bench --task acceptwin --bench-pass
-前置/环境错误：任务 acceptwin 不存在（缺台账 _wt/.state/acceptwin.json）
-"$PY" "$TW" lock release bench --task acceptwin --force --bench-pass   # 同一句错误，锁仍在
-```
+**2026-10-29 已修**：无台账降级为 `[warn] …跳过 PASS 记录，仅释放锁`，**不再需要手写占位台账**。
+1. `$TW lock status` 认现场（持有者 / pid / 已持有 / TTL）——别对同一句报错反复重试。
+2. `$TW lock release <build|bench> --task <NAME> [--bench-pass]` 直接放；PASS 记不上会 warn，锁照放。
+3. **PASS 后面还要用**（`done` 只认台账 `bench_pass`）→ 从一开始就用已 `new` 的 ID 占锁，或把结论写进主干提交/文档。插件树 `pw:<name>` 天然无台账 → F 节。
+4. 最后手段：锁 = `_wt/.state/locks/<name>.lock` 的单行 JSON（`name/task/pid/host/epoch/at/note/ttl`），`release` 就是 unlink 它——手工删 = 不记 PASS 的强制释放，前面各步都不可用才做。**早期为绕坑手写的占位台账现在有害**（既占上限名额又被 `list` 当任务）→ E 第 6 步备份后删。

-**根因**（读脚本确认）：`release` 分支里**只要带 `--bench-pass` 就先 `load_state(task)`** 去给台账写 PASS，
-台账不在就抛「前置/环境错误」，**根本走不到释放那一步**；`--force` 只覆盖「持有者与 `--task` 不符」和
-acquire 的陈旧接管，管不到台账缺失。而 `acquire` 侧**不查台账**——这个不对称就是坑本身；报错文案里的
-「任务不存在」也别误读成「我没占过锁」。
+### C. `done <ID>`：它是合并点，不是查看器

-1. 先 `$TW lock status` 确认持有者 / pid / 持有时长 / TTL（如 `bench  acceptwin 持有（pid=2784，
-   已 0.1 / TTL 6.0 小时）`）——**别反复重试 release**。
-2. **不需要同步记 PASS** → 直接 `$TW lock release bench --task <NAME>`（不带 `--bench-pass`）就能释放。
-3. **需要 `--bench-pass` 而这个名字不是登记任务** → 手写**最小占位台账** `_wt/.state/<NAME>.json`
-   （键与 `new` 写出的完全一致，共 11 个）：
-
-```json
-{
-  "id": "acceptwin",
-  "slug": "lead-window",
-  "branch": "(none: lead 验收窗占位台账)",
-  "path": "D:\\Code\\DTU Code\\STM32F4-Base",
-  "base": "v2-on-ui",
-  "created_at": "2026-10-26 17:00:00",
-  "junctions": [],
-  "needs_bench": true,
-  "bench_pass": false,
-  "note": "lead 验收窗（非工作树任务，为 lock 台账占位）",
-  "lean": true
-}
-```
-
-   用写文件的工具落 UTF-8（无 BOM），别用 `echo` / `Set-Content`（中文乱码铁律）。
-4. `$TW lock release bench --task <NAME> --bench-pass` → `[ok] 已为任务 … 记录台架 PASS` +
-   `已释放锁 bench（原持有者 …）`。
-5. **立刻删掉占位文件**：它活着期间会被 `list` 当任务列出，并**占掉 3 个活跃名额之一**（`path` 指向的
-   目录存在就算活跃）；而且**绝不对这个 ID 跑 `done` / `abort`**——清场会拿台账里的 `path` / `branch`
-   去 `git worktree remove` 和删分支。
-6. 复验 `$TW lock status`：`build  空闲（TTL 1.0h）` / `bench  空闲（TTL 6.0h）`。
-7. 占位台账一删，那条 PASS 也随之消失。**这个 PASS 后面还要用的话，从一开始就用已登记的任务 ID 占锁**
-   （lead 的验收窗借某个已 `new` 出来的 ID 最省事），或把验收结论写进主干提交说明/文档。
-8. **为什么必须马上释放**：`done` 的前置会跑 `release_stale_locks()`——**未到 TTL 的活锁直接判失败**：
-   `独占资源 bench 仍被 acceptwin 占用（已 0.1 / TTL 6.0 小时），先 release`。lead 挂着锁 = 挡住所有任务
-   的收口；只有超过 TTL 的锁才会被自动接管。
-9. 最后手段（脚本本身都走不通时）：锁就是 `_wt/.state/locks/<name>.lock` 里的单行 JSON
-   （`name/task/pid/host/epoch/at/note/ttl`），`release` 的实现就是 unlink 它——手工删这个文件等价于
-   「不记 PASS 的强制释放」，只在前面几步都不可用时才用。
-
-### C. `done <ID>` 的正确用法（它是合并点，不是查看器）
-
-1. **合并前确认任务属主已把全部改动提交完**。`$TW status <ID>` 看未提交清单与领先提交数；跨会话任务
-   再问一句属主（`send_message`）。实测教训：属主还剩「2/2」没提交就 `done`，把只含 1/2 的分支合进了主干，
-   只能另开一棵树补后半并向对方说明（是自己的时序错，不是分支问题）。
-2. **先 `--dry-run`，并读全量输出**（别 `tail -2`，见「读输出」）。判据两行：
-   `[ok] 前置检查通过（领先 <base> 共 N 个提交）` + `[ok] 无冲突，预演结果树 <sha>`；
-   **N 必须等于属主应交的提交数**，对不上回到第 1 步。dry-run 零改动。
+1. **合并前确认属主提交完**：`$TW status <ID>` 看未提交与领先数，跨会话再问属主一句。实测教训：属主还剩「2/2」没提交就 `done` → 只含 1/2 的分支进了主干，只能另开一棵树补后半（自己的时序错，不是分支问题）。
+2. 先 `--dry-run` 且**读全量**。判据两行：`[ok] 前置检查通过（领先 <base> 共 N 个提交）` + `[ok] 无冲突，预演结果树 <sha>`；**N 必须等于属主应交的提交数**，对不上回第 1 步。
 3. 正式 `$TW done <ID>`——**必须在主工作树**（铁律 1）。
-4. 输出 `!! 门禁未全绿：工作树与分支**保留**，未清场` 时，紧跟的 `主干已含合并提交 <sha>` 已经说明
-   **合并落进主干了**。
-   - ✅ 走提示里的 **a) 在主工作树修正后追加提交**；
-   - ❌ **绝不用 b) 的 `git -C "<主树>" reset --hard <sha>`**——那是丢弃已入库的合并提交，而
-     `reset --hard` 本身是项目级 Never（会连未提交工作一起丢）。提示 b 只是列出的可能性，不是建议。
-   - 先定位是**哪条钩子**红：门禁输出里的 `[SUMMARY] L0: pre-commit hooks -- passed=N failed=M`，
-     不同根因处置不同（见陷阱「`done` 的门禁 = `pre-commit run --all-files`」）。最常态是 `.map` 滞后 → 第 5 步。
-5. 补绿固定链（2026-10-25 实测；顺序即因果，全在**主工作树**跑，逐条不接管道看退出码）：
+4. 见 `!! 门禁未全绿：工作树与分支**保留**，未清场` 时，紧跟的 `主干已含合并提交 <sha>` 说明**合并已落主干**；先定位哪条钩子红（`[SUMMARY] static: pre-commit hooks -- passed=N failed=M`），最常态是 `.map` 滞后 → 第 5 步。
+   - ✅ 走提示 a)：主工作树修正后追加提交。
+   - ❌ **绝不用 b) 的 `reset --hard <sha>`**——那是丢弃已入库的合并提交，且 `reset --hard` 是项目级 Never（连未提交工作一起丢）。提示 b 是列出的可能性，不是建议。
+5. 补绿固定链（顺序即因果，全在主工作树，逐条不接管道看退出码）：

 ```bash
 "$PY" scripts/check_mem_numbers.py    --write            # 台账受管区 ↔ 新 .map 对齐
@@ -168,119 +106,68 @@ acquire 的陈旧接管，管不到台账缺失。而 `acquire` 侧**不查台
 "$PY" scripts/ram_baseline.py         --update           # 趋势基线追加一行
 "$PY" scripts/check_test_coverage.py  --update-baseline  # 覆盖率基线（新单测 / 新套件时必刷）
 "$PY" scripts/check_doc_links.py      --all              # 文档链接与章节引用
-git add <上面几条刷出来的基线/快照文件>   # 显式列文件，别 -A 把别人在飞的改动一起提交
-git commit -F <UTF-8 无 BOM 的正文文件>   # 提交属 Ask first（AGENTS.md 边界），按用户指示再做
+git add <上面刷出来的基线/快照文件>    # 显式列文件，别 -A 把别人在飞的改动一起提交
+git commit -F <UTF-8 无 BOM 的正文文件> # 提交属 Ask first（AGENTS.md 边界）
 ```

-   为什么必然要补，见陷阱「`done` 的门禁跑在 `@build` 之前」。
-6. **重跑 `done` 之前主工作树必须干净**——否则前置检查直接
-   `失败：主工作树不干净（…）——合并会把未提交改动卷进来`，所以第 5 步的产物必须**先提交**。重跑时若分支
-   已并入，会打印 `[i] task/<ID>-<slug> 已合入 <base>，跳过合并，直接清场` → 摘联接 → `完成（分支此前已合入）`。
-7. 清场完成后再敲一次 `done <ID>` 会得到 `前置/环境错误：任务 <ID> 不存在（缺台账 …json）`（exit 2）——
-   **这不是失败**：清场的最后一步 unlink 了台账。判完成以 `git log` 为准。
+   为什么必然要补 → 陷阱「`done` 的门禁跑在 `/keil-build` 之前」。合并解过冲突时，**合并提交期 pre-commit 只查冲突文件**（→ G 节第 3 条）→ 落主干后必须另跑全量。
+   **注释/文档-only 但碰了 .c/.h 的短链**：先比 `Program Size` 与合并前是否逐项相同——相同就只 `ram_baseline.py --update` 重写体积凭证（`scripts/size_attestation.json` 跟着补提交笔走），**别 `--write` 动受管区**（等于给在飞分支造冲突面）；数字变了才走上面全链。**已命令化**：`"$PY" "$TW" postmerge`——新鲜直接跳过；红则先短链，再用只读 `check_mem_numbers` 复检裁定是否升全链；末尾跑 `--all` 并列出待提交文件（不代提交）。上面的手工全链仍是权威兜底。
+6. **重跑 `done` 前主树必须干净**，否则 `失败：主工作树不干净（…）——合并会把未提交改动卷进来` → 第 5 步产物先提交。分支已并时重跑打印 `[i] task/<ID>-<slug> 已合入 <base>，跳过合并，直接清场`——**该路径在门禁之前就返回，不会替你复绿**：上一次门禁没跑到的尾巴（主树 `ci_local.py` + `check_doc_links.py --all`；体积/文档那半可 `postmerge` 一把跑）必须自己补。主树脏且那份脏不是你的 → **C2**。
+7. 清场后再敲一次 `done <ID>` 得 `前置/环境错误：任务 <ID> 不存在（缺台账 …json）`（exit 2）——**不是失败**：清场最后一步 unlink 了台账。**判完成以 `git log` 为准**。
+
+### C2. `done` 被「主工作树不干净」挡住，而那份脏是**别的并发会话**留的
+
+- **不许**对它做 stash / checkout / reset / 提交 / 删除（项目级 Never，你不知它写没写完）。`done` 要求主树干净 → 合并与回收一起被挡，**那是保护不是工具坏了**。
+- 正解六步，编号与 [reference/merge-dirty-main-tree.md](reference/merge-dirty-main-tree.md) 第 1~6 步一一对应（每步的确切命令与判据在那篇）：**取证**（mtime + diff 定性有无交集，顺带 `worktree list` 看有无别人中途新建的树）→ **预演** `git merge-tree --write-tree <base> <task>`（打出结果树 sha 且 RC=0）→ **主树手工合并** `git merge --no-ff --no-edit -F ci-artifacts/merge-msg-<slug>.txt <task>` → **对账**（合并后 blob id 与 stat 同合并前存值逐项一致）→ **备份台账** `cp <ID>.json <ID>.json.state-bak` 后让 `done` 自己摘联接拆树 → **复验** `worktree list` + `lock status`。
+- **blob id 变了 = stash pop 半冲突**：立刻停止收工，把两份 blob id 与 diff 交给该文件属主，绝不 `checkout` 抹平。
+- **报告要点名**：绕开 `done` 的理由 + 补回它的证据（预演 sha 与 RC、blob 对账、主树全库 `check_doc_links.py --all`、两把锁空闲）+ 那份外部脏文件与中途冒出来的第二棵树（谁的、你没动它的证据）。合并信息也过 G 的禁词自检；「这份脏通常是谁」见陷阱清单。
+
+### D. 门禁指标异常增长 → 净室逐文件归因（主树全程只读）
+
+三条判据：仓外 detached 树当净室、**一次只注入一份在飞文件**、与 HEAD 基线逐文件差分；主树前后 `git status --porcelain` 逐行一致才算「全程只读」。全文 → [reference/clean-room-measure.md](reference/clean-room-measure.md)。
+
+### E. 回收**非登记**工作树（`list` 为空 / detached / 树里有在飞或未跟踪内容）
+
+三条不可跳过：① 逐文件内容**三桶归类**（与主线工作区/HEAD 比对；「很久没动」不是判据）② 动手前跑**只读 reparse 预扫**，拿到 `REPARSE: none` 才许 `git worktree remove`（铁律 5）③ 唯一未合并残留先备份再 `--force`，拆完复验 + 清悬挂台账。**绝不跑 `done`/`abort`**（铁律 9）。全文（第 1~6 步 + 两份探针脚本）→ [reference/reclaim-unregistered.md](reference/reclaim-unregistered.md)。
+
+### F. 与 DSH worktree 插件（`/worktree`、`worktree_create`）共存
+
+| 联接 | 级别 | 依据 | 缺了会怎样 | 逃生门 |
+|---|---|---|---|---|
+| `simulator/SDL2` | **硬需求** | `simulator/CMakeLists.txt:12` 的 `set(SDL2_DIR …)` **非 `CACHE`**，include / `lib/x64` / `SDL2.dll` 全从它派生 | `build_sim.bat` 当场失败 | **无** |
+| `.venv` | 软需求 | `scripts/ci_local.py` 有 `DTU_PRECOMMIT_PYTHON` + 五级解释器候选 | **静默**落机器级解释器（缺 fontTools → `generated-fresh` 假红） | 环境变量 |
+
+- `plugin adopt` 两条都补只是因为便宜，不代表两条都硬。插件树占锁记 `pw:<name>`、**回收仍归 /worktree**（本 skill 不删插件树，插件也不删 `_wt/`）。「有插件为何还自持生命周期」＝先读插件包（`npm root -g`）再 grep 三个概念名报命中数，插件侧零命中就是理由——取证姿势与答案边界 → [reference/dsh-plugin-bridge.md](reference/dsh-plugin-bridge.md) F-2。
+
+### G. 任务树内跑门禁：落点、`--all` 假红、消息禁词
+
+- **新树没有 `ci-artifacts/`**（被 ignore → 不检出）：重定向/写文件直接 `ENOENT` 且**整段程序零执行** → 落盘前先单独一条 `mkdir -p ci-artifacts`；树内输出一律树内相对路径（`cd` 进树后 `../_wt/x.txt` 落到 `_wt/_wt/`）。一次性产物**不进仓库根**。
+- **文档门禁树内按单文件跑；全库 `--all` 留到合并后在主树跑**——树内 `simulator/SDL2` 是同一份仓库的联接，`--all` 把它一起扫成假红（实测 RC=1 而问题全在联接下、要改的文档一条没有）。非要树内跑：① 主树同命令拿基线 ② 过滤联接下的问题行 ③ 剩下的逐行比。**只做一步就是误判。**
+- **合并提交期 pre-commit 只查冲突文件**（日志首行 `[INFO] Checking merge-conflict files only.`，其余全 `(no files to check) Skipped`）→ 合并落主干后**必须另跑全量** `scripts/ci_local.py`。
+- **跨层改动拆不成「按层分笔」**：钩子看到的世界 = HEAD + 本笔 staged（未暂存被 stash；未跟踪文件不被 stash 但会拖红同一棵树上别人的提交）→ 登记文件 / 生成物 / 互锁引用的文档分到他笔，本笔必被整仓门禁拦（`doc-links`/`registration-check`/`generated-fresh`/`mem-numbers`）。判据：**一笔提交必须自洽**。
+- **跑门禁前字节体检**：`lines / bytes / BOM / CR / U+FFFD / 三连续空行 / 行尾空格 / 末行单个 LF` + Markdown 表格每行列数一致性（单元格内竖线写成反斜杠竖线，否则被当分隔符断列）。坏行**未必是本次改动**，先定归属。`doc-links`/`no-mojibake` 只覆盖编码那半。机械项已命令化：`"$TW" precheck`（BOM 漂移 / CR / U+FFFD + docs 逐档门禁，只读）；列数一致性与归属判定仍人做。
+- **提交/合并信息一律 `-F` 读文件**（UTF-8 无 BOM、标题 ≤100、正文每行 ≤80，放 `ci-artifacts/`）；清退类任务加**禁词自检**：`git log -1 --pretty=%B | grep -c '<关键词>'` 必须是 **0**。未推送前发现消息写错 → `--amend -F` 就地修，别追加「更正」提交（等于把禁词写回历史）。BOM/CRLF/行长/禁词一次查：`"$TW" precheck --msgfile <文件> --ban <词1> --ban <词2>…`。
+- 全文（第 1~7 条，含 stash 机制与四道整仓门禁现场）→ [reference/gates-in-tree.md](reference/gates-in-tree.md)。

 ## 铁律

-1. **`done` 只能在主工作树执行**——主干分支检出在主工作树，git 不允许同一分支在两处检出。
-2. **`done` 不 push**。它结束于本地合入 + 门禁全绿；推送需用户明确许可（项目既有纪律）。
-3. **`build` 与 `bench` 都必须串行**：UV4 不能两个实例同时 `-b`；串口 COM6、ST-LINK、
-   设备 IP `192.168.1.100` 各只有一份。**构建与烧录都不可并发。**
-   - `build` 锁由 **`@build` 自持自释**，调用方无需手工 acquire/release；
-   - `bench` 锁**必须手工**：`lock acquire bench --task <ID>` → 烧录/`@test`/探针 →
-     `lock release bench --task <ID> --bench-pass`。非登记任务（lead 的验收窗）占了锁怎么放 → B 节。
-4. **单写者文档**：`docs/任务规划/`（整个文件夹）、`AGENTS.md` 的任务表块、`MDK-ARM/*.uvprojx`、
-   `.pre-commit-config.yaml`、内存快照 —— 任务期**不在任务工作树里改**，留到 `done` 统一处理。
-5. **清场必须先摘联接**：脚本会先 `os.rmdir` 掉 `.venv` / `simulator/SDL2` 联接再
-   `git worktree remove`。**手工清场时千万别直接 `git worktree remove`**——git 可能递归进联接，
-   把主工作树的 `.venv` 一起删掉。
-6. **活跃任务硬上限 3**（脚本常量 `MAX_CONCURRENT = 3`，每棵约 83 MB 检出）。满了 `new` 直接 exit 2，
-   腾位顺序与 `--force` 的代价 → A 节。
-7. **工作树放仓库同级 `_wt/`，绝不在仓库内部**——否则污染 `git status`、`pre-commit --all-files` 与全库搜索。
-8. **`done` 是合并点**：属主没提交完就别 `done`；合并提交一旦进了主干，只用「主工作树补提交」收尾，
-   **不用 `reset --hard` 反悔** → C 节。
+1. **`done` 只能在主工作树执行**——主干分支检出在主树，git 不允许同一分支两处检出。
+2. **`done` 不 push**：它结束于本地合入 + 门禁全绿；推送需用户明确许可。
+3. **`build` 与 `bench` 都必须串行**（UV4 不能两个实例同时 `-b`；COM6、ST-LINK、设备 IP `192.168.1.100` 各一份）。`build` 锁由 **/keil-build 自持自释**（`keil_build.py`）→ 调用方**不要**手工 acquire/release；`bench` 锁**必须手工** acquire → 烧录 / `/serial-boot-test` → release `--bench-pass`。非登记持有者怎么放 → B 节；插件树 → F 节。
+4. **单写者文档**：`docs/任务规划/`（整个文件夹）、`AGENTS.md` 任务表块、`MDK-ARM/*.uvprojx`、`.pre-commit-config.yaml`、内存快照 —— 任务期**不在任务树里改**，留到 `done` 统一处理；用户显式豁免时（在任务树写、由 done 合回）要在交付报告里点名这条例外。
+5. **清场必须先摘联接**：脚本先 `os.rmdir` 掉 `.venv` / `simulator/SDL2` 联接再 `git worktree remove`。手工拆树前必跑 **E 第 3 步**预扫拿到 `REPARSE: none`——否则 git 可能递归进联接把主树 `.venv` 一起删掉。
+6. **活跃任务硬上限 8 = 脚本常量 `MAX_CONCURRENT`（`task_worktree.py:30`）——唯一事实源**：报错文案与 `new` 的插件树提示都插值它，AGENTS.md / 方案文档 / frontmatter / A 节的数字全是引用同步。改这个数字 → 全形态扫描走 `stale-doc-count-sweep` skill + 隔离小仓验证上限真生效；每棵磁盘代价按实测口径重述、别照抄旧数（细节 → 验证清单末条）。满了 exit 2 → A；悬挂台账 → E 第 6 步。
+7. **工作树放仓库同级 `_wt/`，绝不在仓库内部**（否则污染 `git status`、`--all-files` 与全库搜索）。唯一例外 = 插件写死的仓内 `.dsh-worktrees/`（改不了，已用预置 .gitignore + 三个全库扫描排除兜住 → F 节）。
+8. **`done` 是合并点**：属主没提交完就别跑；合并提交进了主干就只用「主树补提交」收尾，**不用 `reset --hard`** 反悔 → C 节。
+9. **非登记 / detached 的树绝不跑 `done` / `abort`**：两者都以台账为前置（无台账 exit 2），带残留台账时 `abort --force` 会绕过内容保全把别人在飞的改动连树一起删 → E 节。

-## 陷阱（实测）
+## 陷阱与验证（收工前各扫一遍）

- **`--force` 不是万能钥匙**：它只覆盖四类检查——并发上限、持有者与 `--task` 不符、陈旧锁接管、
-  清场时强制移除工作树。**台账缺失这类前置/环境错误（exit 2）跟它无关**（实测 `lock release
-  --force --bench-pass` 报的是同一句话，锁照旧没放）。
- **联接不是符号链接**：本仓库 `core.symlinks=false`，git 里的 symlink 会被检出成
-  「内容是目标路径的文本文件」。共享 `.venv` 只能用 Windows **目录联接**（`mklink /J`，
-  不需要管理员权限），且联接必须建在版本控制之外。
-  实测（2026-10-12）：用 ctypes 直调 `DeviceIoControl(FSCTL_SET_REPARSE_POINT)`
-  会被系统拒绝（Win32 4392），`mklink /J` 正常——所以脚本走后者，参数以列表交给
-  subprocess，含空格的路径（本项目 `DTU Code`）由 subprocess 自动加引号。
- **联接建失败不中止 `new`**：只告警并打印手工补建命令，避免留下半成品任务空间；
-  但该任务里跑不了 `.venv\Scripts\python.exe`，`@build` / `ci_local.py` 会找不到解释器。
- **`done` 前主工作树必须干净**：否则未提交改动会被卷进合并（补完基线再重跑 `done` 时最容易忘，见 C 第 6 步）。
- **⚠ `done` 的门禁跑在 `@build` 之前 → 依赖 `.map` 的钩子会误报**（2026-10-12 实测）：
-  `done` 的顺序是「合并 → 重生成 → **门禁（ci_local）** → `@build`」，而
-  `mem-budget`（登记簿条目「缩堆迁 CCM 后半（暂缓）」）/ `mem-numbers` 是拿**文档快照 vs `.map`** 比对 —— 门禁跑时
-  `.map` 还是**主工作树合并前**的旧产物，与刚合并进来的新台账**必然不一致** →
-  误报 `[FAIL] 台账受管区与 .map 不一致`。`@build` 跑完后 `.map` 才是新的。
-  **处置（2026-10-25 补全）**：按 C 节第 5 步的完整链补——`check_mem_numbers.py --write` →
-  `ram_baseline.py --write` → `ram_baseline.py --update` → `check_test_coverage.py --update-baseline` →
-  `check_doc_links.py --all` → 提交 → 重跑 `done`（它会检测到「已合入」直接清场）。
-  此时主干已含合并提交，**绝不能用提示里的 `reset --hard` 回退**。
- **`done` 的门禁 = `ci_local.py` = `pre-commit run --all-files`（50 条钩子全跑）**（2026-10-26）：红了先读
-  `[SUMMARY] L0: pre-commit hooks -- passed=N failed=M skipped=K`，**按钩子 id 定根因**，别一律当「`.map` 滞后」
-  去跑补基线链。典型例外：`generated-fresh`（生成器幂等性，触发面 `tools/**`、`docs/images/*.svg`、UI 生成文件）——
-  合进来的分支改了生成器却没重跑产物时，补基线链救不了，处置是在**主工作树重跑那个生成器**、脚本与产物同一笔提交，
-  再重跑 `done`。另注意 `pre-commit run --all-files` 只跑 pre-commit stage，个别只在 commit-msg / 手工阶段跑的守卫不在此列
-  （口径见 `scripts/ci_local.py` 头部说明）。
- **⚠ 新建工作树从未构建过 → 体积类门禁必然红**（2026-10-25 实测）：`.map` 是每棵树各自的
-  构建产物、不入版本库，所以 `new` 出来的空间里 `mem-numbers` / `mem-budget` / `ci_local.py`
-  的 L0c 都拿不到事实源，报 `[FAIL] 找不到 .map 事实源`（脚本提示已写明原因，不是代码缺陷）。
-  同理 `done` 的重生成步骤会 `[skip] 未找到 .map，跳过内存快照同步（需先 @build）`。
-  **处置**：新空间第一次提交前先 `@build` 一次（`build` 锁自动排队，与别的树串行）。与上一条
-  的区别要分清：上一条是「有 `.map` 但是旧的」，本条是「根本没有 `.map`」，处置动作不同。
- **⚠ 增量构建可能不重链 → `.map` 数字瞬态不一致**（2026-10-12 实测）：
-  `@build` 若判定无需重链，`.map` 保持旧值，此时 `--write` 生成的快照是**瞬态值**
-  （实测同一份源码两次读到 223,560 与 223,724，差 164 B）。**以主工作树（集成点）
-  的 `.map` 为准**；改完 RAM 相关代码后确认重链再刷新快照。
- **`ram_baseline.py` 的 help 串里有未转义的 `%`**（2026-10-25 实测：某些直调姿势会渲染 argparse help 并崩）——
-  查用法读脚本头部 docstring，别靠 `--help`；修脚本本身属 `mem-budget` skill 的范围。
- **合并冲突常落在「生成物」上**：`docs/内存管理/RAM使用分析与优化方案.md`（mem-numbers
-  快照）在双方都改过时必冲突，且**两边都不能直接选**（各自基于不同基线）——
-  正确做法是解冲突后用**合并后的实际构建**重新生成，不要挑一侧。
- **并集合并残留**：双方都改过的文件（尤其 `.gitignore`）会被 git 自动并成**并集**，
-  可能留下指向已删目录的死规则或重复条目。脚本会自动报「双方都改过」的文件清单 +
-  连续重复行；**权威判据是 base / 两个 tip 三方对比**（`git show <ref>:<file>` 逐项 `grep -F`），
-  别用 `tail -N` 目测。
- **`.workbuddy-ai/` 刻意不共享**：记忆不随任务分叉，也不给联接递归删除的机会。
-  任务工作树自己的记忆由 `done` / `abort` 在清场前归并回主工作树。
- **`--lean` 只省磁盘不省时间**：实测全量 smudge 7.25 s / 83 MB，跳过 smudge 7.05 s / 45 MB，
-  两者工作区都干净。默认走全量（参考图可用），磁盘紧张时才用 `--lean`。
- **锁不绑定进程存活**：`lock acquire` 本身是短命进程，而真正用资源的烧录/构建在别的进程里跑。
-  所以判「陈旧」只看**时效**（该锁的 TTL）加显式 `--force`；pid 仅作排障记录。
-  同任务重复 acquire 是幂等的（不会把自己锁死）。
- **TTL 按锁分设**（2026-10-12）：`build` = **1h**、`bench` = **6h**（`LOCK_TTL_HOURS`）。
-  口径是「兜底窗口应与操作真实时长同量级」——编译是秒~分钟级，6h 的兜底太钝；
-  bench 是会话级（flash→`@test`→探针），才配得上小时级。持有者还可用
-  `lock acquire ... --ttl <小时>` **自报**更精确的窗口（`keil_build.py` 即按其 `--timeout` 自报）。
- **陈旧锁自动接管**：超过该锁 TTL 未释放即视为陈旧，下次 `acquire` 会接管并提示；
-  未到 TTL 的活锁需 `--force`。`done` 的收口前置也会**自动释放陈旧锁**（不再硬失败），但
-  **未到 TTL 的活锁会把 `done` 挡在前置检查**（B 节第 8 步）。
- **`build` 锁不必手工持**（2026-10-12 起）：`@build`（`keil_build.py`）**自持自释**——
-  进入 acquire、`finally` 无条件 release，所以"Agent 忘了 release、锁一直挂到 TTL"这条在构建路径上已消除。
-  `done` 的门禁自己持锁并给子进程设 `DTU_LOCK_HELD=build` 告知跳过（新旧脚本都兼容）。
-  **`bench` 锁仍须 Agent 手工持**（会话作用域：跨烧录→`@test`→探针，见 `keil-build` SKILL.md）。
-
-## 验证
-
- `$TW list`：条目数 = `ls _wt` 的目录数且 ≤ 3；刚回收的任务与 B 节的占位条目都不再出现。
- `$TW lock status`：`build  空闲（TTL 1.0h）` + `bench  空闲（TTL 6.0h）`——没有本会话留下的持有者。
- `git log --oneline -3`：能看到 `merge: task/<ID>-<slug> 合入 <base>` 与其后的补基线提交；
-  `git status --porcelain` 为空（补链改动已提交，才谈得上重跑 `done`）。
- `ls _wt/.state/`：该 ID 的台账已无（清场最后一步 unlink）；重复 `done` 报「任务不存在」不必再追。
- 补绿链的每一条都自己 `echo RC=$?` 看到 0，最后以重跑 `done` 打出的**清场日志**（`已摘除联接` /
-  `已删除分支` / `完成（分支此前已合入）`）为成功判据，而不是 `tail` 出来的最后一行。
+- [reference/pitfalls.md](reference/pitfalls.md)：全部实测坑逐条（含 `--dry-run` 不保护清场段、门禁跑在 `/keil-build` 之前、未跟踪文件在 `git log` 与合并里都不留痕、并集合并残留、新树从未构建 → 体积类门禁必然红、注释-only 也刷红体积凭证、「已合入」快路径在门禁前返回不替你复绿、`--force` 只覆盖四类检查、联接不是 symlink（`core.symlinks=false`）、锁不绑进程存活、文件工具先读后改按绝对路径记账、中文门禁回显乱码但 rc 可信）。收工前扫一眼。
+- [reference/verification.md](reference/verification.md)：每节要留的证据（预演 sha + `MT_RC=0`、blob id 对账、两把锁空闲、禁词计数 0、`REPARSE: none`、改上限数字后的全形态扫描）。

 ## 与其它 skill 的衔接

- 构建 = `keil-build` skill（`@build`）；烧录/回读 = `stlink-flash` skill；串口闭环 = `serial-boot-test` skill
- 烧录产物的真实 hex 路径以 `.serialtest/config.json` 的 hex 键为准（实测
-  `MDK-ARM/Objects/STM32F407-Demo.hex` 这个路径并不存在），拷错等于烧了旧镜像 → `serial-boot-test` skill
- 新 `.c` 文件 = `new-source-file` skill（`uvprojx` 与 `CMakeLists.txt` 双端注册）
- `.map` 口径 / RAM 台账与趋势 → `mem-budget` skill；UI 回归 → `ui-verify` skill
- 完整机制与目录分配 → `docs/环境与部署/并行任务工作树方案.md`
+- 构建 = `keil-build`· 烧录/回读 = `stlink-flash` · 串口闭环 = `serial-boot-test`（真实 hex 路径以 `.serialtest/config.json` 的 hex 键为准——实测 `MDK-ARM/Objects/STM32F407-Demo.hex` 不存在，拷错 = 烧旧镜像）
+- 新 `.c` 双端注册 = `new-source-file` · RAM/.map 台账 = `mem-budget` · UI 回归 = `ui-verify` · 计数同步 = `stale-doc-count-sweep` · 卡死的技能台账行 = `mnemon-skill-ledger-stuck-repair`
+- DSH worktree 插件（`/worktree` / `worktree_create`，仓内 `.dsh-worktrees/`）与本 skill 的分工、桥接命令、锁归属 → F 节 · 完整机制与目录分配 → `docs/环境与部署/并行任务工作树方案.md`
@@ -0,0 +1,58 @@
+### D. 门禁指标异常增长 → 逐文件归因（把净室工作树当**测量仪**，主树全程只读）
+
+**场景**（2026-10-27 实测）：`id-check` 突然 FAIL「不可判定 1,178 > 上限 1,166」——比上一轮量到的 1,162 又涨了 **+16**，
+而主工作树里同时压着 4 条在飞任务道的未提交改动。**不许 stash / checkout / reset**（那是搬动甚至丢弃别人未提交的工作，
+项目级 Never；`git status` 一乱，整条道的现场就没了），**不许改门禁脚本本身**（它就是那把尺子，改了数字就不可信），
+**也别在脏主树里跑门禁**（那测的是 4 条道 + 未跟踪文件的混合体，永远分不出谁）。正解：**在仓库之外另起一棵
+detached HEAD 的干净工作树当净室，一次只往里注入一份在飞文件**，与基线差分即得每个文件的独立贡献。两步：
+**净室建树 → 单文件注入测量**。
+
+1. **建净室 + 先落基线数**（路径必须**在仓库目录之外**；铁律 7 对临时树同样成立——放仓内就污染 `git status` /
+   `pre-commit --all-files` / 全库搜索）：
+
+```bash
+MAIN="D:/Code/DTU Code/STM32F4-Base"           # 主工作树绝对路径（含空格 → 变量整体加引号）
+WT="$MAIN/../_wt/und-attr"                     # 仓外同级 _wt/ 下；一次测量固定用同一个名字
+rm -rf "$WT" 2>/dev/null
+git -C "$MAIN" worktree add --detach "$WT" HEAD >/dev/null 2>&1 || { echo WT_FAIL; exit 9; }
+git -C "$WT" status --porcelain                # 应为空
+"$PY" "$WT/scripts/archive/id_gate/check_ids.py" 2>&1 | tail -25     # ← 口径：id-check 钩子已于 2026-10-28 退役（脚本移入 scripts/archive/id_gate/），按该脚本自身默认参数跑；基线与注入用**同一条命令**
+```
+
+   - `--detach`（**不要 `-b`**）：净室没有分支、不写 `_wt/.state/<ID>.json` 台账 → **不占 `MAX_CONCURRENT = 8`
+     名额、不出现在 `$TW list`**，也没人会被误指去对它跑 `done`（建与拆都不走 `$TW new` / `$TW done`）。
+   - 能这么量的前提：该门禁**只读仓库内文本**。依赖本树构建产物的门禁（`mem-numbers` / `mem-budget` 要 `.map`）
+     在净室里必然报「找不到 .map 事实源」（见陷阱「新建工作树从未构建过」）——**那类指标不能这么归因**。
+   - `git status --porcelain` 非空 = 有别人的未跟踪文件被带进净室 → 先 `git clean -xdn` **干扫**（别去 `n`）
+     看清会删什么，只挪走多出来的那些再测；语料被污染出来的数字与 CI 不可比。
+2. **一次只注入一份在飞文件 → 跑同一个扫描器 → 与基线差分**（得到的是每个文件的**独立**贡献，不是合计）：
+
+```bash
+for f in "App/log/sys_log_mcu.c" "test/host/sys_log_mcu/sys_log_mcu_test.c" "docs/子系统设计/运行与自检记录设计说明.md"; do
+  mkdir -p "$WT/$(dirname "$f")"
+  cp "$MAIN/$f" "$WT/$f"                       # 拷进净室；主树那份只读、一字节不动
+  echo "== $f =="; "$PY" "$WT/scripts/archive/id_gate/check_ids.py" 2>&1 | tail -25    # ← 与第 1 步同一条命令
+  git -C "$WT" checkout -- "$f"                # 只还原净室里自己刚拷进来的那份
+done
+```
+
+   实测：`run_par.c` / `board_ui_nav.py` / `check_nested_comment.py` / keil `SKILL.md` **各 +0**，
+   而 log 道那三个文件 **+6 / +8 / +2**，合计**正好 +16**。**Σ(逐文件增量) ≠ 观察到的涨幅 → 还有没被注入的
+   在飞文件，或存在文件间交互项**，不许就此交卷。
+3. **定性增量是哪一类字面量**（只有「谁」没有「为什么」= 给不出可执行的改法）：同一计数器在 **HEAD 版**与
+   **在飞版**各数一遍，**差值才是新增行带来的**（存量的不算这条道的账）；再对新增行直接 grep。本次 16 处全是
+   **裸形 「字母 T 累进数字 4」**（`T` 在 `scripts/archive/id_gate/id_registry.json` 的 `bare_check_letters` 里，规范形态是连字符形），
+   全部落进 `skip_bare_unmanaged` —— 到这一步结论才配发给属主。
+4. **闭合 + 复验主树一个字节没被污染**：
+
+```bash
+git -C "$MAIN" worktree remove --force "$WT"   # 净室里只有自己的拷贝、没有原件，--force 安全
+git -C "$MAIN" worktree list                   # 不该再有 und-attr
+git -C "$MAIN" status --porcelain | sort       # 与测量前**逐行一致**（测量前先存一份基线清单）
+```
+
+   ⚠ **上面第一行的前提是有条件的**：树里混进了别人的在飞 / 未跟踪内容时「只有自己的拷贝」就不成立了，
+   `--force` 直接拆等于替别人把唯一版本删掉 → 先走 **E 节**（全景 → 逐文件分桶 → 联接预扫 → 唯一残留先备份），
+   再回来执行本步；复验按 **E 第 5 步**做（拆前/拆后主树 `status --porcelain -uall` 行数必须相同）。
+   **同一棵净室树的第二种用法**：按指定 commit **只读**构建出像 / 烧录验收——不搬动任何在飞改动，也不为台架
+   提前抢发一笔提交；构建与烧录都在这棵树里做（不在主树），仍受 `bench` / `build` 锁串行（铁律 3）。
@@ -0,0 +1,87 @@
+### F. 与 DSH worktree 插件（`/worktree`、模型工具 `worktree_create`）共存
+
+本仓现在有**两套**隔离空间。别混用，也别互相回收：
+
+| | 本 skill（文档别名 `@task`，DSH 显式调用 `/task-worktree`） | DSH worktree 插件（`dsh-task-worktree`） |
+|---|---|---|
+| 树在哪 | 仓库**外** `../_wt/<ID>-<slug>/` | 仓库**内** `.dsh-worktrees/worktree/<name>/` |
+| 谁建 | `new <ID> <slug>`（人来敲命令） | 会话选「Worktree模式」/ 模型调 `worktree_create`（零命令） |
+| 台账 | `_wt/.state/<ID>.json`（本 skill） | `.dsh-worktrees/manifest.json`（插件私有格式，别去改） |
+| 分支名 | `task/<ID>-<slug>` | `worktree/<name>` |
+| 共享联接 | `new` 自动建 | **建树时没有** → 要 `plugin adopt` 补 |
+| 回收 | `done`（预演 / 合并 / 门禁 / 清场）或 `abort` | 用户敲 `/worktree finish\|bring-back\|remove\|prune`（模型碰不到收尾命令） |
+
+**为什么允许它把树建在仓内**（铁律 7 的唯一例外）：路径写死在插件里（`WORKTREE_NAMESPACE = worktree`
+ `<repo>/.dsh-worktrees/`），而暴露给模型的工具只有 `worktree_create` / `worktree_list` /
+`worktree_status` 三个，配置面改不动。兜法三件（均已落地）：
+
+1. `.gitignore` **预置** `.dsh-worktrees/` —— 插件首次 `create` 会往 `.gitignore` 追加一模一样的字面量，
+   `ensureIgnored()` 见到同名规则即跳过；不预置就等于让插件在会话中途改这份受控文件（diff 里冒出
+   一行"不是我加的"）。
+2. 全库扫描的排除面登记了它：`scripts/check_doc_links.py` 的 `SKIP_PARTS`、
+   `tools/refgraph/gen_refgraph.py` 的 `EXCLUDE_DIRNAMES`、`scripts/check_layer_deps.py` 的 `os.walk` 兜底。
+   一份仓库副本被全库扫描吞进去 = 文档链接假红 + 配图生成物逐字节漂移砸在某位同事头上。
+3. 联接与锁归属由本节命令接上（下面三步）。
+
+**这棵树是不是插件的**：`git worktree list` 里路径含 `.dsh-worktrees/` 就是。`$TW list` 现在会在台账段
+下面另起一段列出它们，联接列**点名缺哪一样**（`已联` / `缺 .venv` / `缺 SDL2` / `齐(实体SDL2)`）。**插件树不占
+`MAX_CONCURRENT = 8` 名额**——回收不归本 skill，
+硬计入只会让别人那棵关不掉的树把 `new` 挡死（`new` 会打印一行「另有 N 个插件工作树不计入上限」提醒并发代价）。
+
+三步接上（`<name>` 可带 `worktree/` 前缀，也可多段如 `refactor/logging`）：
+
+```bash
+"$PY" "$TW" plugin list                      # 一览：分支 / 脏 / 缺哪个联接（缺项另起一行说后果）
+"$PY" "$TW" plugin adopt N21-dhara-isfree    # 只补缺失的 .venv 与 simulator/SDL2 联接
+"$PY" "$TW" plugin unadopt N21-dhara-isfree  # 只摘联接（os.rmdir），绝不动目标内容与树里文件
+```
+
+- **两条联接坏了的样子完全不同**：缺 `.venv` → `ci_local.py` 的四级解释器回退**静默**落到机器级
+  python（无 fontTools = `generated-fresh` 假红的老根因，AGENTS.md 记着）；缺 `simulator/SDL2` →
+  `build_sim.bat` 当场报错（`SDL2_DIR` 是裸 `set`，没有 env 逃生口）。所以列表只说「已联」不够——
+  它按缺的那一样分别给后果，`adopt` 没补齐也只报「还不能算就绪」，不许说「现在可以跑」。
+- **adopt 只碰联接**：已联的跳过；`simulator/SDL2` 若已是实体目录只告警不动；`.dsh-worktrees/` 之外的路径
+  一律 exit 2（实测 `plugin adopt ".."` 被拒）——这道闸防的是把主树或 `_wt` 目录当插件树遮蔽掉真实内容。
+- **锁归属现在认得出来**：`/keil-build` 在插件树里自持自释时，持有者名从 cwd 反推成 `pw:<name>`（多段名压平成
+  `-`），与 `plugin adopt` 打印的那个名字逐字相同（`keil_build.py: plugin_tree_owner()` ↔
+  `task_worktree.py: plugin_lock_owner()`）→ `lock status` 不再一律落成 `build-cli`。
+- 上台架仍须手工占锁、用同一个名：`lock acquire bench --task pw:<name> --note <说明>` →
+  `lock release bench --task pw:<name> --bench-pass`。插件树没有台账 → 按 B 节只 warn、锁照常放。
+- **命名建议**：插件 `<name>` 沿用本 skill 的 `<ID>-<slug>` 形态（如 `N21-dhara-isfree`），两套视图同名好对账；
+  但分支前缀必然不同（`worktree/` vs `task/`），别把两者说成同一个分支。
+- **收尾不在这**：`done` / `abort` 拿插件树名下手只会 exit 2（这是保护，别绕过去手工 `git worktree remove`；
+  要拆先 `plugin unadopt` 摘联接，再由**用户** `/worktree remove`）。`/worktree bring-back` 要求主工作树干净，
+  本仓常有在飞改动 → 提交或 stash 由用户定。反过来插件也不会碰 `_wt/`（路径根不同，谁也删不掉谁）。
+
+### F-1. 两条共享联接**不是同级需求**（按仓库实配定级；别答成「两个都必须」）
+
+- **`simulator/SDL2` = 硬需求**：`simulator/CMakeLists.txt:12` 是
+  `set(SDL2_DIR "\${CMAKE_CURRENT_SOURCE_DIR}/SDL2/SDL2-2.32.10")`——普通 `set()`、**非 `CACHE`**，所以既没有环境变量入口、
+  命令行 `-DSDL2_DIR=` 也会被这个普通变量盖掉；`SDL2_INCLUDE_DIR`（:34）、`SDL2_INCLUDE_PARENT`（:70）、`SDL2_LIB_X64`（:71）、
+  链接目录（:180）、`SDL2.dll` 拷贝（:207）**全部从它派生**。缺它 `build_sim.bat` 当场配不出来（脚本里的 `SDL2_DIR` 同样是
+  裸 `set`，也没有 env 逃生口）。
+- **`.venv` = 软需求**（有显式逃生门，但绕开有代价）：`scripts/ci_local.py` 的解释器解析顺序（:108-:138）——
+  ① `DTU_PRECOMMIT_PYTHON`（显式配置，指错**立即报错**、不静默降级）→ ② `sys.executable` → ③ 仓库 `.venv` →
+  ④ `shutil.which("python")` → ⑤ `_global_python_candidates()` 的常见机器级位置。树内没有 `.venv` 时会**静默**落到机器级
+  解释器 → 无 fontTools → `generated-fresh` 假红（AGENTS.md 记着的老根因）；可以用 `DTU_PRECOMMIT_PYTHON` 顶掉，
+  但要每台机器自己配——这就是它「软」的意思：有路可走，走得不爽。
+
+结论口径：**要补就两条都补（`plugin adopt` 一次干完，成本近乎零），但「都必须」是错的**——SDL2 没有任何替代路径，
+`.venv` 有 `DTU_PRECOMMIT_PYTHON` 这条门。现役命令形式仍是 `plugin list` / `plugin adopt <name>`；**不改代码、
+不改 `CMakeLists.txt`**（真要给 SDL2 加 CACHE 逃生门属于改模拟器构建口径，另案 → `lvgl-simulator` skill）。
+
+### F-2. 「DSH 都有 worktree 插件了，为什么还自持 Python 生命周期」——取证姿势与答案边界
+
+这题不许凭印象答，口径 = **实读插件源码**：在 DSH 安装目录定位插件包（`npm root -g` → `<global>/node_modules/@deepseek-ai/dsh/`，
+或读 profile 的 `dsh.profile.bundles` 找包名），**记下版本号与文件路径**，再对三个概念名逐个 grep 并**报出命中数**：
+
+1. 独占锁 / 资源串行（`lock`、`acquire`、`release`、TTL）——插件侧**零命中**：它的模型是「一棵树一个会话」，没有跨会话排队概念。
+2. 共享目录联接（`.venv`、`simulator/SDL2`、`mklink /J`、reparse point）——零命中：插件建树就是纯 `git worktree add`，
+   所以插件树天生缺这两条联接（定级见 F-1）。
+3. 联接状态显示（三态：已联 / 缺 .venv / 缺 SDL2 / 齐(实体SDL2)）——零命中。
+
+**重叠面要说清**：两侧底层是**同一条** `git worktree add`，本 skill 没有重造「建树」；重叠只在**开**与**收**两个动作，
+而插件的收（`/worktree finish|bring-back|remove|prune`）是**人类命令**、模型碰不到，也没有「合并前预演 → 并集残留审计 →
+补基线 → 门禁 → 先摘联接」这条编排。本仓为什么必须自持：硬件各只有一份（一块 ST-LINK、一套 Keil 授权、一个 COM6、
+一个 `192.168.1.100`）→ 要 `build` / `bench` 锁串行；SDL2 是模拟器硬依赖且无逃生门 → 要共享联接；台架 PASS 要留给
+`done` 记账 → 要台账。**给不出版本号与 grep 命中数，就不要下结论。**
@@ -0,0 +1,9 @@
+# 原 frontmatter（2026-10-29 因超 65536 字节写侧上限而瘦身，原文逐字留档）
+
+本技能正文受 dsh-mnemon 插件写侧上限 65536 字节约束（只在写侧校验，加载侧不查），超限时自进化每次「生成草案」都会被拒、行永久卡在「生成中」。以下是瘦身前的 description / whenToUse 原文，触发词语义更全，写路由时可参考；如需恢复请连正文一起改回并先确认总体积 < 65536。
+
+---
+name: task-worktree
+description: 多任务并行开发的空间管理（git worktree 生命周期）：new 开一棵工作树 + 任务分支、目录联接共享 .venv 与模拟器 SDK、活跃任务硬上限 8 与腾位、build/bench 两类独占锁（含非登记任务占锁后「缺台账」释放不掉的正解）、done 预演合并回主干、**主工作树被别的并发会话弄脏时的手工合并路径（取证 → `merge-tree` 预演 → `merge --no-ff -F` → 外部改动 blob id 前后对账 → C2 节）**、门禁未全绿的补基线收尾、并集合并残留审计、**任务树内门禁与审计输出的落点（`<tree>/ci-artifacts/` 先 `mkdir -p`；文档链接按单文件在树内跑、全库 `--all` 基线合并后在主树跑；`simulator/SDL2` 联接假红 → G 节）**、**非登记工作树（detached HEAD / 无台账 / 树内有在飞或未跟踪内容）的安全回收**（逐文件内容分桶 + 联接/reparse 预扫 + 唯一残留先备份再 --force + 悬挂台账清理复验），以及**把仓外 detached worktree 当净室测量仪**——门禁指标异常增长时一次只注入一份在飞文件、与基线差分做逐文件归因；**以及与 DSH worktree 插件（`/worktree`、模型工具 `worktree_create`，树在仓内 .dsh-worktrees/）的桥接**——`plugin adopt` 补共享联接、锁归属 `pw:<name>`、回收仍归 /worktree。规格见 docs/环境与部署/并行任务工作树方案.md。
+whenToUse: 要同时推进多个任务、担心同分支同文档互相冲突；要为新任务开一个隔离空间；要把任务合并回主干；或遇到 `new` 报「已有 8 个活跃任务（上限 8）」、`lock release` 报「任务 X 不存在（缺台账）」、`done` 报「门禁未全绿：工作树与分支保留，未清场」、或 `done` 报「主工作树不干净」而那份未提交改动是**别的会话/插件**留下的（不能提交也不能丢弃 → C2 节手工合并）、两个任务抢 COM6 / UV4、"改了文档被覆盖"、并集合并残留时；或**要在任务树里跑文档/审计门禁**——`--all` 报一堆问题却全在 `simulator/SDL2` 联接下、或往 `ci-artifacts/` 写输出报 ENOENT / No such file or directory（→ G 节）；或**门禁指标异常增长（如 id-check 的不可判定数从 1,162 涨到 1,178、+16）却查不出是哪个文件 / 哪条任务道造成的**、主工作树压着多条在飞改动而不许 stash / 提交 / 改门禁脚本、要按 HEAD 基线只读出像验收时；或**要回收 `@task list` 里根本看不到的工作树**（`git worktree list` 有它、台账没有 / detached HEAD / 树里疑似留着别的会话的在飞或未跟踪内容）、或**要清台账里 branch / path 都已不存在的悬挂条目**（`@task list` 输出发怪、`new` 报「任务已存在」或白占 8 个名额之一）；或**这棵隔离空间是 DSH worktree 插件开的**（会话选了「Worktree模式」/ `/worktree create`，树在仓库内 `.dsh-worktrees/`）——进去发现 `.venv` 不在、`@build` 与门禁全部起跑失败，或想看清谁在占 UV4 / 台架 → F 节。
+---
@@ -0,0 +1,61 @@
+### G. 任务树内跑门禁与审计：输出落点（ci-artifacts）与 SDL2 联接假红
+
+三条硬规矩，全是 2026-10-29 实测付过失败成本的（两起 ENOENT + 一次假红误判）：
+
+1. **门禁/审计输出只落 `<tree>/ci-artifacts/`，而新树里它不存在 → 落盘前先 `mkdir -p`**。`ci-artifacts/` 被
+   `.gitignore` 忽略（不污染脏行数，E 第 4 步的备份同理），但也因此**不会被检出**——`$TW new` 出来的树里没有这个
+   目录。直接 `fs.writeFileSync("<tree>/ci-artifacts/head-md.md", …)` 当场 `ENOENT: no such file or directory`，
+   **整段程序零执行**（实测：那一轮的门禁体检与快照读取全没跑成，白重跑一次）。用 Node 写之前先
+   `fs.mkdirSync(dir, { recursive: true })`；用 bash 重定向就先单独敲一条 `mkdir -p ci-artifacts` 再落盘
+   ——重定向在命令执行**之前**解析，目录没建出来时是同一条命令直接失败，后面串着的 `grep` 跟着一起报
+   `No such file or directory`，看着像「门禁没跑出结果」，其实是写错了地方。
+2. **`cd` 进任务树之后，`../_wt/x.txt` 不是你以为的地方**：`cd` 之后 `..` = `_wt`，`../_wt/x.txt` 落到
+   `_wt/_wt/x.txt`（实测就是这么报的）。**树内命令的输出一律用树内相对路径**（`ci-artifacts/xxx.txt`）；
+   要绝对路径就写完整绝对路径，跨树取文件用 `$MAIN/…`、`$WTROOT/…` 这种变量打头的全路径，
+   不靠 `cd` 之后的相对层级往上跳。
+3. **任务树内文档门禁按单文件跑；全库 `--all` 基线留到合并后在主树跑**。任务树的 `simulator/SDL2` 是指向
+   主树同一份的**目录联接**（`new` 的第 2/3 步建的），`--all` 会把这份「仓库里的第二份仓库副本」一起扫：
+   实测任务树里 `check_doc_links.py --all` 打 `检查 222 个文档，35 处问题`、RC=1，而 **35 处全落在
+   `simulator/SDL2` 联接下**、要改的文档一条都没有 → 判红纯属联接带来的假红。单文件检查不受影响
+   （扫描根就是那一个文件，联接目录不在面内）。主树本身没有 SDL2 时不产生这类假红（联接如实镜像主树，
+   F 节那棵树连 SDL2 都没得联），但**别据此认为 `--all` 在树内可信**。
+
+```bash
+F="docs/<子目录>/<本次改动的文件>.md"   # 本次改动的那一个文件
+"$PY" scripts/check_doc_links.py "$F" > ci-artifacts/dl-<slug>.txt 2>&1; echo RC=$?
+cat ci-artifacts/dl-<slug>.txt
+```
+
+   逐文件跑的实测读数：需求文档 161 处章节引用 / 98% 机器可判定 / rc=0；方案文档 16 处 / 88% / rc=0。
+   确实要在树内跑 `--all` 时（例如怀疑主干基线本身），判红顺序**固定三步**，缺一步都不许下结论：
+   ① 在**主树**跑同一条命令拿基线；② 过滤掉 `simulator/SDL2` 联接下的问题行；③ 剩下的与主树基线逐行比。
+   只跑 `--all` 见 RC=1 就回「文档门禁挂了」= 把基线噪声算成本任务的账；只跑「过滤后为空」就回「全绿」
+   = 会漏掉真红。全库 `--all` 的正解位置是**合并后的主工作树**：实测合入后在主树跑 `check_doc_links.py --all`
+   = 2,597 处章节引用 / 194 个文档 / rc=0 —— 这才证明「就地删叙述」没打断任何引用。
+   另：**不因 `--all` 的既有假红跳过对本次改动文件的单文件复检**（假红是基线的事，你的文件仍要逐个过）。
+
+4. **文档改动在树内提交前的固定体检**（2026-10-29 实测）：`lines / bytes / BOM / CR / U+FFFD / 三连续空行 /
+   行尾空格 / 末行单个 LF` + 一个自写的 **Markdown 表格每行列数一致性**检查（数格子前先把转义管道 `\|` 还原成占位符，
+   否则会把 `\|` 当成列边界数错）。为什么要自己数：`doc-links` 只管链接与章节、`no-mojibake` 只管编码面，
+   **表格断列与删段留下的三连续空行没有任何钩子会报**。
+   实测读数：需求文档 `lines=2665 bytes=196137 BOM=false CR=0 U+FFFD=0 tripleBlank=0 trailingWS=0 endLF=true`，
+   表格体检另报两处坏表格（`L988-992 counts=5/7`、`L2472-2486 counts=2/3`）——**与本次编辑无关的历史行**。
+   所以体检要**区分「本次改动 bad=0」与「整份文件 bad=0」**：先定位归属再决定动不动手，顺手改别人的区域等于把
+   没打算提交的内容卷进这笔改动（报告里写「本次改动引入 0 处」，并点名那两处是存量）。
+
+5. **提交 / 合并信息一律 `-F` 读文件；清退类任务还要做禁词自检**（2026-10-29 两遍实测）：消息文件写在
+   `ci-artifacts/`（被忽略 → 不污染脏行数），UTF-8 无 BOM、CR=0、标题 ≤100 字符、正文每行 ≤80（实测标题 31 / 32 字符、
+   正文最长行 50 / 55）——`-m` 会把中文按终端代码页转码搞坏，长中文标题还容易撞 gitlint。硬自检：
+
+```bash
+git log -1 --pretty=%B | grep -c '485'       # 被清退主题的关键词：必须是 0
+git log -1 --pretty=%B | grep -ci '\bDE\b'   # 同主题的次要关键词：同样 0
+```
+
+   关键词不许出现在**标题、正文、合并信息**任何一处（实测标题改写成「删除与本方案无关的其它串口通道对照内容」这种
+   语义短语替掉了它）——否则「别让我看到 X」这条要求在 `git log` 里当场破产。合并信息是另一份文件：
+   `ci-artifacts/merge-msg-<slug>.txt` 落盘后**同样 grep 一遍**再 `git merge --no-ff --no-edit -F`（C2 第 3 步）。
+   自审发现消息里的行数 / 统计算错而**尚未推送** → `git commit --amend -F <改好的文件>` 就地修（实测就这么修掉一次
+   off-by-one）；**别追加一笔「更正」提交**——那等于把禁词和被更正的错数一起写回历史。
+6. **合并提交期 pre-commit 只查冲突文件（2026-10-29 实测）**：合并那一次提交的钩子日志首行是 `[INFO] Checking merge-conflict files only.`，其余钩子全打 `(no files to check) Skipped` —— 于是「合并提交通过了 30 项钩子」这句话**只覆盖冲突文件**，别拿它当全量绿。正解：合并落主干后立刻在主工作树跑全量 `scripts/ci_local.py`（静态 + 提交信息 + 主机侧单测 + manual 段），实测全量这一步才会抓到「表格断列」「章节引用悬空」这类跨文件问题。合并解冲突时若上游把 Markdown 表格重排过，注意**单元格里的竖线必须写成反斜杠竖线**（先例 `docs/子系统设计/运行与自检记录设计说明.md` 的 `FA_WRITE\|FA_SEEKEND`），否则 `FA_WRITE|FA_OPEN_APPEND` 会被当列分隔符打断，而 `doc-links` 不查表格列数——要自己数（第 4 条）。
+7. **跨层改动拆不成「按层分笔」提交（2026-10-29 实测，四笔改一笔）**：钩子看到的世界 = HEAD + 本笔 staged——pre-commit 会 stash 已跟踪文件的未暂存改动，而**未跟踪文件不在 `git diff-index` 里、不会被藏**（`git add -N` 也救不了，pre-commit 会把它撤下索引、文件仍在盘上）。后果：把双端登记（`MDK-ARM/*.uvprojx` / `simulator/CMakeLists.txt`）、生成器产物、互锁引用的文档分到别的笔里，本笔必被 `doc-links`（引用了还没入册的小节）、`registration-check`（源文件登记在另一笔）、`generated-fresh`（`#page=` 找不到页面描述符、字库清单与源不一致）、`mem-numbers`（受管区还是旧 .map 的数）四道**整仓**门禁一起拦。判据：**一笔提交必须自洽**——互锁的改动（代码 + 登记 + 生成物 + 文档）走同一笔；机制与三条处置结论（半成品要么先落地要么先挪出工作树）→ `docs/代码规范/pre-commit使用说明.md` §2「stash 覆盖面」。
@@ -0,0 +1,86 @@
+### C2. `done` 被「主工作树不干净」挡住，而那份脏改动是**别的并发会话**留下的
+
+**场景**（2026-10-29 同一套流程在同一天跑了两遍，两遍都撞上它）：任务树里的文档改完、准备合回 `v2-on-ui`，
+主工作树却压着一个自己从没碰过的未提交改动（两次都是 `M .dsh/skills/serial-boot-test/scripts/run_boot_test.py`，
+另一个并发会话/插件留下的）。它既不能提交（不是我的改动，也不知道写没写完），也不能
+stash / checkout / reset / 删除（项目级 Never：丢弃别人的工作）。`$TW done <ID>` 的前置正好卡在这——
+它要求主工作树干净，否则未提交改动会被卷进合并（见 C 第 6 步），于是**合并与回收一起被挡**。
+
+**正解 = 取证 → `merge-tree` 预演 → 主树手工 `--no-ff` 合并 → 自证外部文件没被动过 → 照常收工**，六步：
+
+1. **先取证再动手**（别一看见脏就下「谁弄坏的」结论）。记下它的 mtime 与 diff 内容，判断与本合并有无交集，
+   并把**合并前**的 blob id 与 `diff --stat` 存进 `ci-artifacts/`（第 4 步拿它对账）：
+
+```bash
+MAIN="D:/Code/DTU Code/STM32F4-Base"
+EXT=".dsh/skills/serial-boot-test/scripts/run_boot_test.py"   # 外部脏文件的仓库相对路径
+mkdir -p ci-artifacts
+git -C "$MAIN" status --porcelain                 # 全量脏清单（本会话只认自己那几条）
+stat -c "%y %s %n" "$MAIN/$EXT"                 # mtime + 字节数：定性是谁在什么时候改的
+git -C "$MAIN" diff -- "$EXT" | cat             # 内容性质；与本次合并有无同文件同区域
+git -C "$MAIN" hash-object "$MAIN/$EXT" | tee ci-artifacts/ext-blob-before.txt   # ← 存下这个 blob id
+git -C "$MAIN" diff --stat -- "$EXT" | tee ci-artifacts/ext-stat-before.txt      # ← 以及这份统计（几加几减）
+```
+
+   实测：mtime 落在另一会话的活跃时段内，diff 是「docstring 引号改写」2+/2−，与要合的文档毫无交集 →
+   定性为**与本合并无交集、不丢弃**。顺手 `git -C "$MAIN" worktree list` 看一眼有没有**别人中途新建的任务树**
+   （两次里都撞见第二棵树 `data-trust-restructure`，正是这份外部改动的来路）——这是并发会话的硬证据。
+2. **`merge-tree` 预演：先证明能干净合并，再碰主干**。`$TW done --dry-run` 在这条路上同样被前置挡住，
+   预演只能自己敲（git 2.38+ 的新语法，打印的是**结果树 sha**）：
+
+```bash
+git -C "$MAIN" merge-tree --write-tree v2-on-ui task/<ID>-<slug>; echo MT_RC=$?
+```
+
+   判据 = **打印出一个 tree sha 且 RC=0**（实测打出 `4220906b…` + `MT_RC=0` 才敢往下走）。⚠ 本机 git 太旧没有
+   这个子命令时退回 `$TW done <ID> --dry-run`——它的前置也是「主树干净」，可用环境变量 `DTU_INTEGRATION_WORKTREE`
+   把集成点指到一棵干净的临时树去演练（见本文开头的环境变量）；**别为了跑 dry-run 去动主树那份脏改动**。
+   预演报冲突 → 回到冲突本身处理，不许直接 `--no-ff` 硬合。
+3. **主工作树里手工 `--no-ff` 合并**（合并信息走 `-F` 文件，放在被忽略的 `ci-artifacts/`；编码口径同 C 第 5 步：
+   UTF-8 无 BOM、正文每行 ≤80 字符；标题格式 `merge: task/<ID>-<slug> 合入 <base>`）：
+
+```bash
+git -C "$MAIN" merge --no-ff --no-edit -F ci-artifacts/merge-msg-<slug>.txt task/<ID>-<slug>
+```
+
+   pre-commit 会**自己**把那份未提交改动 stash 起来、跑完钩子再放回（输出里能看到 `[INFO] Stashing unstaged files to …`）
+   ——**这条不是让你去手工 stash**，正好相反：钩子的 stash 往返让它自己走完，你只需在第 4 步验证它把东西原样还回来了。
+   **为什么可以绕开 `done`**（报告里要写清这句）：`done` 的前置要求主工作树干净，而那份外部改动既不能提交也不能
+   丢弃，所以合并只剩「手工预演 + 手工合并」一条合法路径；被跳过的门禁与审计由第 2 步（预演 sha + RC=0）、
+   第 4 步（blob id 对账）、G 节（合并后在主树跑全库基线）、第 6 步（`lock status`）逐项补回。
+   **这不是绕过保护**，是把保护要求的证据逐条自己交出来。
+4. **自证那份外部改动原样还在**（本节唯一的硬证据，两次实测都靠它结案）：合并后**再跑一次**同一对命令，
+   与第 1 步存的两个值**逐项相同**：
+
+```bash
+git -C "$MAIN" hash-object "$MAIN/$EXT" | tee ci-artifacts/ext-blob-after.txt
+git -C "$MAIN" diff --stat -- "$EXT" | tee ci-artifacts/ext-stat-after.txt
+diff ci-artifacts/ext-blob-before.txt ci-artifacts/ext-blob-after.txt    # 空输出才算过
+git -C "$MAIN" status --porcelain                # 该文件仍是 M：没被顺手提交，也没被清成干净
+```
+
+   实测：合并前后 blob id 同为 `369380ca8eb024b593d872455b6a020797abcd8d`、`diff --stat` 同为 2+/2−
+   → 证明 pre-commit 的 stash 往返没动别人的工作；合进主干的那份文档另按 G 节复核（零残留 + 全库基线）。
+   blob id 变了 = stash pop 出了半冲突（现场会留下 stash 与冲突标记）→ **立刻停止收工**，把两份 blob id 与两份
+   diff 原样贴进报告交给该文件属主；**绝不用 `git checkout -- $EXT` 抹平**（那是销毁别人的工作，项目级 Never）。
+5. **收工仍走技能自身的代码路径，别自己手写 rm**：先把台账**备份成 `*.state-bak`**（后缀与 E 第 6 步统一），
+   再让脚本自己摘联接：
+
+```bash
+cp "$WTROOT/.state/<ID>.json" "$MAIN/ci-artifacts/<ID>.json.state-bak"   # 先备份再动
+"$PY" "$TW" done <ID>     # 打「已合入 <base>，跳过合并，直接清场」→ 先摘 .venv 与 simulator/SDL2 联接 → 删工作树 → 删分支 → unlink 台账
+```
+
+   实测这条路径能走完（日志：`state backup -> ci-artifacts\screenlink-doc-history.json.state-bak` +
+   `[ok] 已摘除联接 .venv` + `[ok] 已摘除联接 simulator/SDL2`）。**若它仍拿「主工作树不干净」挡在合并前**（没走到
+   清场分支），改走 **E 节**的手工回收路径：台账仍按本步先 `cp` 成 `.state-bak`；第 1~2 步的前置换成
+   「`status --porcelain -uall` 为空 + 唯一提交为空 + `merge-base --is-ancestor` 判 MERGED」三条（本次实测三条齐），
+   第 3 步的联接预扫 + `rmdir` 摘联接**一步不能省**；再 `git worktree remove`（三条前置齐了就不必 `--force`）、
+   删分支、`git worktree prune`。清完再敲一次 `done` 会得到「任务 <ID> 不存在（缺台账 …json）」（exit 2）——
+   **这不是失败**（台账已被 unlink；判完成以 `git log` 为准，见 C 第 7 步）。
+6. **复验收工**：`git -C "$MAIN" worktree list` 只剩主树 + **别人的树**（那棵不是你的，保留并在报告里点名，
+   别顺手回收 → E 节）；`"$PY" "$TW" lock status` 打 `build  空闲（TTL 1.0h）` + `bench  空闲（TTL 6.0h）` 才收工。
+
+**并发会话证据必须写进报告**：主树里那份外部脏文件、中途冒出来的第二棵任务树，都要点名——是谁的、
+你怎么定性的、对这次合并的影响（本例：与本合并无交集 / 不丢弃 / 不进本次提交），以及你**没动它**的证据
+（blob id 前后一致）。「不能丢弃别人的工作」类问题九成是并发会话造成的，不写清就等于没取证。
@@ -0,0 +1,134 @@
+## 陷阱（实测）
+
+- **`--force` 不是万能钥匙**：它只覆盖四类检查——并发上限、持有者与 `--task` 不符、陈旧锁接管、
+  清场时强制移除工作树。**台账缺失这类前置/环境错误（exit 2）跟它无关**（实测 `lock release
+  --force --bench-pass` 报的是同一句话，锁照旧没放）。同理 `abort --force` 也只覆盖「树里有东西」这一条拒绝，
+  **不会**替你做 E 节的内容保全——它只会删得更快。
+- **未跟踪文件在 `git log`、提交门禁与 `done` 的合并里都不留痕**（2026-10-29 回收现场）：钩子按 HEAD tree 的
+  diff-index 取文件，未跟踪文件从没进过任何钩子的视野；`git log` 也照不出「唯一未合并」——它压根没被提交过。
+  所以「这棵树没有遗留改动」这种结论**只能**由 E 第 2 步的逐文件内容比对给出，`log --oneline -1` + 脏计数都不够。
+- **`git status --porcelain` 不带 `-uall` 会折叠未跟踪目录**（E 第 1 步）：「全景」少一项、分桶少一个文件，
+  最后拆掉的是别人唯一的草稿。回收路径上**一律 `-uall`**。
+- **`$TW list` 空 ≠ 没有工作树**：`list` 只遍历台账（A 第 1 步），用户说的「那 3 棵 done 掉」很可能在 `$TW list` 里
+  一个都不存在（实测就是）→ 别照 `$TW list` 的空结果回「没有任务」，先 `git worktree list` 拿全集再逐棵定性（E 节）。
+  2026-10-29 起 `list` 还会另起一段列出插件树（`.dsh-worktrees/`，F 节）——**"看见"不等于"归 `done` 管"**。
+- **「这棵树很久没动」不是回收判据**：实测 `bench-*` 两棵既没台账也没脏文件、mtime 很旧，但真正决定去留的是
+  `git merge-base --is-ancestor <c> HEAD` = MERGED（提交已进主线）+ 未跟踪层为空；而另一棵 mtime 更新的树反而
+  全是已在主线的副本。**判据是内容与祖先关系，不是时间戳。**
+- **「我记得没建过联接」不是安全判据**：判据只有扫出来的 `REPARSE: none`（E 第 3 步实测 `bench-*` 各挂一个 `.venv`
+  联接，正是「不是自己建的」那类）。
+- **联接不是符号链接**：本仓库 `core.symlinks=false`，git 里的 symlink 会被检出成
+  「内容是目标路径的文本文件」。共享 `.venv` 只能用 Windows **目录联接**（`mklink /J`，
+  不需要管理员权限），且联接必须建在版本控制之外。
+  实测（2026-10-12）：用 ctypes 直调 `DeviceIoControl(FSCTL_SET_REPARSE_POINT)`
+  会被系统拒绝（Win32 4392），`mklink /J` 正常——所以脚本走后者，参数以列表交给
+  subprocess，含空格的路径（本项目 `DTU Code`）由 subprocess 自动加引号。
+  但**读属性**用 ctypes 没问题：`GetFileAttributesW` + `FILE_ATTRIBUTE_REPARSE_POINT` 就是 E 第 3 步的预扫手段。
+- **联接建失败不中止 `new`**：只告警并打印手工补建命令，避免留下半成品任务空间；
+  但该任务里跑不了 `.venv\Scripts\python.exe`，`/keil-build` / `ci_local.py` 会找不到解释器。
+- **`done` 前主工作树必须干净**：否则未提交改动会被卷进合并（补完基线再重跑 `done` 时最容易忘，见 C 第 6 步）。
+- **⚠ 任务树里 `check_doc_links.py --all` 的红多半是 `simulator/SDL2` 目录联接的假红**：全库扫描会吞下那份
+  「仓库里的第二份仓库副本」（实测任务树 222 个文档 / 35 处问题全在联接下、RC=1，而主树同命令基线全绿）。
+  判红必须先过滤 `simulator/SDL2` 下的问题行、再与主树**同一条命令**的基线比对；正解是树内按单文件跑、
+  `--all` 基线合并后在主树跑 → **G 节**。
+- **新建的任务树里没有 `ci-artifacts/`**（被 `.gitignore` 忽略 → 不被检出）：`> ci-artifacts/x.txt` 与
+  `fs.writeFileSync("<tree>/ci-artifacts/x", …)` 都会 `ENOENT`；`cd` 进树后再用 `../_wt/x.txt` 落到 `_wt/_wt/` →
+  `No such file or directory`（两起实测，第二次直接废掉一整轮体检）。落盘前先 `mkdir -p ci-artifacts`，
+  树内输出一律用树内相对路径 → **G 节**。
+- **`done` 报「主工作树不干净」而那份脏改动不是你的**（别的并发会话 / 插件留下的，实测两次都是
+  `.dsh/skills/serial-boot-test/scripts/run_boot_test.py`）：**不许用 stash / 提交 / 删除去清场**（项目级 Never，
+  你也无从判断它写没写完）→ 走 **C2**：取证（mtime + diff + `hash-object` 存进 ci-artifacts）→ `merge-tree` 预演
+  → 主树 `merge --no-ff -F` → 合并前后 blob id 与 `diff --stat` 对账。**「它看着像废弃的」不是丢弃判据**。
+- **⚠ `done` 的门禁跑在 `/keil-build` 之前 → 依赖 `.map` 的钩子会误报**（2026-10-12 实测）：
+  `done` 的顺序是「合并 → 重生成 → **门禁（ci_local）** → `/keil-build`」，而
+  `mem-budget`（登记簿条目「缩堆迁 CCM 后半（暂缓）」）/ `mem-numbers` 是拿**文档快照 vs `.map`** 比对 —— 门禁跑时
+  `.map` 还是**主工作树合并前**的旧产物，与刚合并进来的新台账**必然不一致** →
+  误报 `[FAIL] 台账受管区与 .map 不一致`。`/keil-build` 跑完后 `.map` 才是新的。
+  **处置（2026-10-25 补全）**：按 C 节第 5 步的完整链补——`check_mem_numbers.py --write` →
+  `ram_baseline.py --write` → `ram_baseline.py --update` → `check_test_coverage.py --update-baseline` →
+  `check_doc_links.py --all` → 提交 → 重跑 `done`（它会检测到「已合入」直接清场）。
+  此时主干已含合并提交，**绝不能用提示里的 `reset --hard` 回退**。
+- **`done` 的门禁 = `ci_local.py` = `pre-commit run --all-files`（50 条钩子全跑）**（2026-10-26）：红了先读
+  `[SUMMARY] static: pre-commit hooks -- passed=N failed=M skipped=K`，**按钩子 id 定根因**，别一律当「`.map` 滞后」
+  去跑补基线链。典型例外：`generated-fresh`（生成器幂等性，触发面 `tools/**`、`docs/images/*.svg`、UI 生成文件）——
+  合进来的分支改了生成器却没重跑产物时，补基线链救不了，处置是在**主工作树重跑那个生成器**、脚本与产物同一笔提交，
+  再重跑 `done`。另注意 `pre-commit run --all-files` 只跑 pre-commit stage，个别只在 commit-msg / 手工阶段跑的守卫不在此列
+  （口径见 `scripts/ci_local.py` 头部说明）。
+- **⚠ 新建工作树从未构建过 → 体积类门禁必然红**（2026-10-25 实测）：`.map` 是每棵树各自的
+  构建产物、不入版本库，所以 `new` 出来的空间里 `mem-numbers` / `mem-budget` / `ci_local.py`
+  的体积门禁步都拿不到事实源，报 `[FAIL] 找不到 .map 事实源`（脚本提示已写明原因，不是代码缺陷）。
+  同理 `done` 的重生成步骤会 `[skip] 未找到 .map，跳过内存快照同步（需先 /keil-build）`。
+  **处置**：新空间第一次提交前先 `/keil-build` 一次（`build` 锁自动排队，与别的树串行）。与上一条
+  的区别要分清：上一条是「有 `.map` 但是旧的」，本条是「根本没有 `.map`」，处置动作不同。
+- **⚠ 只改注释里的文档路径，也会把「体积同码凭证」刷红**（2026-10-30 实测，`done testdoc`）：
+  `scripts/check_size_gate.py` 的判据是**索引 blob 指纹**（实测 1466 个文件），**不是体积数字**——
+  那笔全库路径同步顺带改了 20 个 `.c/.h` 的注释，`Program Size` 逐项没变
+  （Code=246160 / RO-data=29816 / RW-data=2036 / ZI-data=149700），凭证照旧红：
+  `本次代码（指纹 172c6c78b8fb…，1466 文件）与体积测量（指纹 1ed4267c77f6…，2026-10-30T01:15:01）不同码`。
+  **处置比上一条那条补绿链短**：合并后 `done` 自己那次 `/keil-build` 已 0 错 0 警，此时只需
+  `ram_baseline.py --update` 重写凭证（改的是 `scripts/size_attestation.json`；同日同数字时
+  `ram_baseline.tsv` 连趋势行都不会新增），**别顺手 `--write` 去动内存受管快照**——数字没变就改受管区，
+  等于给别的在飞分支造冲突面（台账归属口径见 `mem-budget` skill）。
+  **判据顺序**：先比 `Program Size` 与合并前是否逐项相同 → 相同就只补凭证；不同才走 C 节第 5 步全链。
+  连带的第二个坑：`done` 对「分支已合入」的路径**在门禁之前就 return**（`cmd_done` 里
+  `already and ahead == 0` 那条分支直接清场），所以补完凭证重跑 `done` **不会替你复绿**——
+  落主干后的全量证据得自己跑：`scripts/ci_local.py`（实测 47 runner / 3896 断言全绿）
+  + 主树 `check_doc_links.py --all`（实测 215 个文档 / 2993 处章节引用 rc=0）。
+- **⚠ 增量构建可能不重链 → `.map` 数字瞬态不一致**（2026-10-12 实测）：
+  `/keil-build` 若判定无需重链，`.map` 保持旧值，此时 `--write` 生成的快照是**瞬态值**
+  （实测同一份源码两次读到 223,560 与 223,724，差 164 B）。**以主工作树（集成点）
+  的 `.map` 为准**；改完 RAM 相关代码后确认重链再刷新快照。
+- **`ram_baseline.py` 的 help 串里有未转义的 `%`**（2026-10-25 实测：某些直调姿势会渲染 argparse help 并崩）——
+  查用法读脚本头部 docstring，别靠 `--help`；修脚本本身属 `mem-budget` skill 的范围。
+- **合并冲突常落在「生成物」上**：`docs/内存管理/RAM使用分析与优化方案.md`（mem-numbers
+  快照）在双方都改过时必冲突，且**两边都不能直接选**（各自基于不同基线）——
+  正确做法是解冲突后用**合并后的实际构建**重新生成，不要挑一侧。
+- **并集合并残留**：双方都改过的文件（尤其 `.gitignore`）会被 git 自动并成**并集**，
+  可能留下指向已删目录的死规则或重复条目。脚本会自动报「双方都改过」的文件清单 +
+  连续重复行；**权威判据是 base / 两个 tip 三方对比**（`git show <ref>:<file>` 逐项 `grep -F`），
+  别用 `tail -N` 目测。
+- **⚠ 别用 heredoc 打补丁改门禁脚本造探针**（2026-10-27 实测三连败，白烧一整轮）：heredoc 里的 python
+  把门禁脚本改坏——`patched 3` 之后 `PROBE_RC=1`、`SyntaxError: unterminated string literal (detected at
+  line 882)`，而它**正是被测对象**，改完的数不可信；另一处 `replace('\', '/')`（想把 Windows 反斜杠换成正斜杠）里的反斜杠被多层引号吞掉
+  → `SyntaxError (detected at line 16)`。**正解**：探针落成**独立 `.py` 文件**（写文件的工具，UTF-8 无 BOM）
+  再 `"$PY" probe.py`；非用 heredoc 不可就用单引号定界 `<<'PY'`（防变量展开），且**路径一律 `as_posix()`、
+  一个反斜杠都不写**——反斜杠字面量要穿「JS 模板串 → bash → shell 引号 → python」四层，必被吞。
+  E 节那两段扫描脚本同理：**落成 `ci-artifacts/*.py` 再跑**（该目录已被忽略，不会污染第 5 步复验用的脏行数）。
+- **取门禁数字：import 门禁模块，别猜输出、别打补丁**（2026-10-27；grep 源码 / 手抄正则 / 解析 stdout 三种姿势
+  都拿不到可复核的数，换成这句立刻拿到）：先读门禁脚本的 `main()`（直读末尾那几十行）看它怎么装配检查器，
+  把**那几行照抄**进探针——`sys.path.insert(0, 'scripts')` → `import check_ids as ci` →
+  `ci.load_json(ci.REGISTRY_FILE, 'reg')` + `ci.load_json(ci.ALIASES_FILE, 'alias')` →
+  `ck = ci.Checker(reg, al, verbose=False)` → `ck.run()` → `print(ck.stats)`。别猜键名：先
+  `print(sorted(ck.stats))` 列出全量计数项，再按精确键取数（顺带 `git diff` 确认门禁脚本自己**没被改过**）。
+- **别把「不可判定」当成一个数**（2026-10-27）：`id-check` 有两种口径——检查器自己算的**硬不可判定**实测只有
+  **2** 处，而门禁红线（`scripts/archive/id_gate/id_registry.json` 的 `undecidable_total_ceiling`）量的是**派生值**
+  `refs_total - decidable`（实测 8,744 - 7,582 = **1,162**，拆开 = `skip_bare_unmanaged` 834 +
+  `noise_allowed` 326 + 硬不可判定 2，**三数精确闭合**）。所以**带属主登记处的族（TC-XXX 这类）加多少引用都算
+  「可判定」、一点不吃这条余量**，真正吃余量的是**裸形字母+数字**字面量；反过来「把可判定引用改写成散文」才是
+  **稀释比值**的动作，那才是绝对数红线要防的。口径混用会当场给整条道下错指令（本次就下错过、量完立刻撤回）。
+- **队友的自查结论要复核，小心它测的是错变量**（2026-10-27）：log 道做过受控实验、结论是「我们没推高这个数」——
+  他们改的是 TC 号、盯的是 `skip_bare_unmanaged`，那个组合当然不动；而 +16 走的是另一条路（新增裸形 「字母 T 累进数字 4」）。
+  定责用 D 节：逐文件注入 + HEAD/在飞两版同一计数器相减 + 对新增行 grep；闭合后 +16 = 16 处裸形 「字母 T 累进数字 4」，
+  **推翻**了自查结论。口头自查与 `--note` 都不是证据，**可复核的差分数字才是**。
+- **`.workbuddy-ai/` 刻意不共享**：记忆不随任务分叉，也不给联接递归删除的机会。
+  任务工作树自己的记忆由 `done` / `abort` 在清场前归并回主工作树。⚠ **手工回收（E 节）没有这一步归并**：
+  拆之前顺手 `ls <tree>/.workbuddy-ai/` 看一眼，有内容就一并备份进 `ci-artifacts/wt-leftover-backup/`。
+- **`--lean` 只省磁盘不省时间**：实测全量 smudge 7.25 s / 83 MB，跳过 smudge 7.05 s / 45 MB，
+  两者工作区都干净。默认走全量（参考图可用），磁盘紧张时才用 `--lean`。
+- **锁不绑定进程存活**：`lock acquire` 本身是短命进程，而真正用资源的烧录/构建在别的进程里跑。
+  所以判「陈旧」只看**时效**（该锁的 TTL）加显式 `--force`；pid 仅作排障记录。
+  同任务重复 acquire 是幂等的（不会把自己锁死）。
+- **TTL 按锁分设**（2026-10-12）：`build` = **1h**、`bench` = **6h**（`LOCK_TTL_HOURS`）。
+  口径是「兜底窗口应与操作真实时长同量级」——编译是秒~分钟级，6h 的兜底太钝；
+  bench 是会话级（flash→`/serial-boot-test`→探针），才配得上小时级。持有者还可用
+  `lock acquire ... --ttl <小时>` **自报**更精确的窗口（`keil_build.py` 即按其 `--timeout` 自报）。
+- **陈旧锁自动接管**：超过该锁 TTL 未释放即视为陈旧，下次 `acquire` 会接管并提示；
+  未到 TTL 的活锁需 `--force`。`done` 的收口前置也会**自动释放陈旧锁**（不再硬失败），但
+  **未到 TTL 的活锁会把 `done` 挡在前置检查**（B 节第 8 步）。
+- **`build` 锁不必手工持**（2026-10-12 起）：`/keil-build`（`keil_build.py`）**自持自释**——
+  进入 acquire、`finally` 无条件 release，所以"Agent 忘了 release、锁一直挂到 TTL"这条在构建路径上已消除。
+  `done` 的门禁自己持锁并给子进程设 `DTU_LOCK_HELD=build` 告知跳过（新旧脚本都兼容）。
+  **`bench` 锁仍须 Agent 手工持**（会话作用域：跨烧录→`/serial-boot-test`→探针，见 `keil-build` SKILL.md）。
+- **⚠ `done --dry-run` 只保护预演段、不保护清场段**（2026-10-29 实测）：`done <ID> --dry-run --skip-build --skip-gates` 在「分支已合入主干」这条路上**照样执行清场**——摘 `.venv` / `simulator/SDL2` 联接、删分支、清台账，然后打「完成（分支此前已合入）」。想真·零改动就只跑不带 `--skip-gates` 的 `--dry-run` 并停在预演输出；用完一律 `git worktree list` 复验（判完成以 `git log` 为准，不是以有没有再敲一次 `done` 为准）。另：`--dry-run` 的前置检查同样要抢 `build` 锁——被别的任务占着时它会直接报「独占资源 build 仍被 X 占用，先 release」，此时加 `--skip-build` 或先 release，**别为了预演去抢别人的锁**。
+- **⚠ 文件工具「先读后改」按解析后的绝对路径记账，切树后要重新读**（2026-10-30 实测，屏板链路任务树）：开新树后先用**相对路径**读过一批文件（读历史记到当时解析到的主树文件上），再进任务树直接 `edit` → 6 条并行编辑全被 `file has not been read — read the file, then retry` 拒。判据：**树内改动一律用树内绝对路径，先 read 再改**——读历史不跨路径复用，工具不做「同名相对路径」宽容。
+- **⚠ 中文门禁输出回显乱码 ≠ 路径坏**（2026-10-30 实测）：对含中文文件名的文档跑 `check_doc_links.py`，终端回显整段乱码，但 **rc 与判定计数全部正确**。只认 `[SUMMARY]` 行与退出码，别误诊成「文档丢失」；脚本化批量调用走 python subprocess + 显式 `encoding`，别经命令行中转中文名。
@@ -0,0 +1,203 @@
+### E. 回收**非登记**工作树（`$TW list` 为空 / detached HEAD / 树里有在飞或未跟踪内容）
+
+**这类树的判定特征**（命中任意一条就适用本节）：`git worktree list` 里有它、但 `_wt/.state/<ID>.json` 台账不存在；
+HEAD 是 detached（`git rev-parse --abbrev-ref HEAD` 打 `HEAD`）；或树里的改动不属于本会话（别的会话留下的未提交 /
+未跟踪文件）。典型来源：D 节的 `--detach` 净室、`new` 之后被手工删目录只剩台账的残骸、别人手工 `git worktree add` 建的分析树
+（2026-10-28 实测一次回收 3 棵：`verify-task16` / `verify-batch` / `und-attr`，各 89 MB，全部无台账 + detached）。
+
+**为什么 `done` / `abort` 在这里整体不适用**（铁律 9）：两条子命令的前置都是 `load_state()`，无台账 →
+`前置/环境错误：任务 <ID> 不存在（缺台账 …json）`（exit 2）当场停住、什么也不会发生；而**假如有**一份残留台账，
+`abort --force` 会拿台账的 `path` 直接 `git worktree remove` —— **绕过下面第 1~4 步的全部内容保全**，把别的会话的唯一版本一次删光；
+`done` 则会去找那条（多半已不存在的）`task/` 分支做合并。另：本路径没有「合并」这一步，所以 `done` 的并集合并残留审计
+在这里不发生，也没有三方对比可依据 —— **唯一性只由第 2 步的内容分桶给出**。回收只能手工走本节第 1~5 步 + 第 6 步清台账。
+
+1. **建全景（全程只读）**：先看 `git worktree list` 的全集，再**逐棵**记三件事（脏行数含未跟踪 / 树顶提交 / 有无分支）
+   加一条台账判定，同时存下主树的拆前基线清单：
+
+```bash
+MAIN="D:/Code/DTU Code/STM32F4-Base"; WTROOT="$MAIN/../_wt"
+git -c core.quotePath=false worktree list                      # 全集：登记树 + 非登记树都在这份里
+MAIN_SHA=$(git -C "$MAIN" rev-parse --short HEAD)              # 下面所有比对都以这一版为主线尺子
+mkdir -p ci-artifacts
+git -C "$MAIN" status --porcelain -uall > ci-artifacts/wt-main-before.txt   # 拆前主树基线（第 5 步逐行比）
+wc -l < ci-artifacts/wt-main-before.txt                        # 记下行数（实测 0）
+for t in "$WTROOT"/*/; do
+  echo "--- $t"
+  git -c core.quotePath=false -C "$t" status --porcelain -uall | wc -l   # 脏 + 未跟踪行数
+  git -c core.quotePath=false -C "$t" log --oneline -1                   # 树顶提交
+  git -C "$t" rev-parse --abbrev-ref HEAD                                # 打 HEAD = detached，压根没分支可 done
+  ls "$WTROOT/.state/$(basename "$t").json" 2>/dev/null || echo "NO-LEDGER"   # 台账位置随 DTU_WT_ROOT
+done
+```
+
+   - **`-uall` 不是可选**：默认 `status --porcelain` 会把未跟踪目录折叠成一行 `dir/`，`-uall` 才展开到文件级；少了它
+     第 2 步的分桶就漏项（实测 `und-attr` 唯一那份就是未跟踪 `?? scripts/check_nested_comment.py`）。
+   - 路径含空格（本项目 `DTU Code`）→ 变量整体加引号；`core.quotePath=false` 让中文路径原样输出，便于逐行核对。
+   - 判定「是不是登记树」看两样：**台账在不在 + HEAD 是否 detached**。两者都指「非登记」→ 从这里开始**禁止**
+     `done` / `abort`（见本节开头），继续第 2 步。
+2. **逐文件与主线 HEAD 比内容并分三桶**：`IN-MAINLINE`（内容等价，拆 = 零损失）/ `UNIQUE-UNMERGED`（主线没有这份
+   内容，拆 = 丢）/ `OLDER-DRAFT`（同路径主线已有更新版本）。落成独立只读探针跑（别用 heredoc 现写现改，
+   见陷阱「别用 heredoc 打补丁造探针」）：
+
+```python
+# ci-artifacts/wt_bucket_scan.py — 只读：逐文件与主线工作区/HEAD 比对，三桶归类
+import os, subprocess, tempfile
+MAIN = r"D:\Code\DTU Code\STM32F4-Base"
+WTROOT = os.path.join(os.path.dirname(MAIN), "_wt")
+TREES = ["verify-task16", "verify-batch", "und-attr"]      # ← 第 1 步全景里挑出的非登记树
+SKIP_TOP = {".venv", "MDK-ARM", ".git", "ci-artifacts"}    # 联接 / 构建产物 / 忽略区，按项目调
+def git(*a):
+    return subprocess.run(("git", "-c", "core.quotePath=false", "-C", MAIN) + a,
+                          capture_output=True, text=True, errors="replace")
+def bucket(rel, tree):
+    p = os.path.join(tree, rel)
+    if not os.path.exists(p):
+        return "OTHER", "工作树里已不存在（多为已 staged 删除）"
+    tf = tempfile.NamedTemporaryFile(delete=False)
+    tf.write(open(p, "rb").read()); tf.close()
+    # 1) 与主线工作区（= 当前 HEAD 的检出内容）逐字节比
+    if git("diff", "--no-index", "--quiet", tf.name, rel).returncode == 0:
+        os.unlink(tf.name); return "IN-MAINLINE", "与主线 HEAD 逐字节相同"
+    # 2) 与主线历史各版比：内容等价于某个旧 commit → 只是主线又往前走了
+    hist = [x.strip() for x in git("log", "--format=%H", "HEAD", "--", rel).stdout.splitlines()]
+    for sha in hist[1:]:
+        old = git("show", f"{sha}:{rel}")
+        if old.returncode == 0 and old.stdout == open(p, encoding="utf-8", errors="replace").read():
+            os.unlink(tf.name); return "IN-MAINLINE", f"内容等价于主线历史版 {sha[:8]}"
+    # 3) 主线从没这条路径 → 唯一；否则同路径主线有更新版 → 更旧草稿（再用 blob diff 定性方向）
+    os.unlink(tf.name)
+    if not hist:
+        return "UNIQUE-UNMERGED", "主线 HEAD 与历史都没有此路径"
+    return "OLDER-DRAFT", "同路径主线有更新版本（用 diff --stat <HEAD> -- <f> 定性）"
+for name in TREES:
+    tree = os.path.join(WTROOT, name)
+    lines = subprocess.run(("git", "-c", "core.quotePath=false", "-C", tree,
+                            "status", "--porcelain", "-uall"),
+                           capture_output=True, text=True, errors="replace").stdout.splitlines()
+    tally = {}
+    for line in lines:
+        rel = line[3:].split(" -> ")[-1].strip('"')     # 兼容 ?? / M / A / R 的箭头形态
+        if rel.split("/")[0] in SKIP_TOP:
+            continue
+        b, why = bucket(rel, tree)
+        tally.setdefault(b, []).append((rel, why))
+    g = lambda k: len(tally.get(k, []))
+    print(f"== {name}: IN-MAINLINE={g('IN-MAINLINE')} UNIQUE-UNMERGED={g('UNIQUE-UNMERGED')} "
+          f"OLDER-DRAFT={g('OLDER-DRAFT')} OTHER={g('OTHER')}")
+    for b in ("UNIQUE-UNMERGED", "OLDER-DRAFT", "OTHER"):
+        for rel, why in tally.get(b, []):
+            print(f"    {b}: {rel}  # {why}")
+```
+
+   报告里必须**逐桶给计数 + 判定证据**（实测：`verify-task16` IN-MAINLINE=6 / UNIQUE=0；`verify-batch` IN-MAINLINE=35 /
+   UNIQUE=1；`und-attr` IN-MAINLINE=0 / UNIQUE=1）。两个非空桶再各钉一条命令把证据坐实：
+
+```bash
+# 「唯一未合并」是真更新还是更旧草稿？blob 级 diff + 逐行看方向
+git -c core.quotePath=false -C "$MAIN" diff --stat "$MAIN_SHA" -- simulator/tests/README.md
+diff <(git -C "$MAIN" show "$MAIN_SHA":simulator/tests/README.md) "$WTROOT/verify-batch/simulator/tests/README.md"
+# 「树顶提交要不要保」只看一件事：是否已并入 HEAD。别拿「目录很久没动」当判据
+for c in 77779d49 1d4b6a17; do
+  git -C "$MAIN" merge-base --is-ancestor "$c" HEAD && echo "$c MERGED" || echo "$c NOT-merged"
+done
+```
+
+   实测：那份 `simulator/tests/README.md` 树内写「27 页 × 3200 B」、主线 HEAD 已是「60 张 × 3200 B」→ **更旧草稿**（被取代的
+   早先版本），不是未合并成果；`bench-21-77779d49` / `bench-23-1d4b6a17` 两棵 `merge-base --is-ancestor` 判 **MERGED** 且脏数 = 0
+   → **保留不动**（不属本节，等属主自己收，报告里点名说清为什么留）。
+   **回收判据不是「看着旧」**：唯一内容如果没被提交过，`git log` 里根本看不见它；反过来「提交已 MERGED」也不等于可以拆——
+   还得看未跟踪那一层。`UNIQUE-UNMERGED` 非空又确实要留 → 它进第 4 步的备份，**不许靠 `--force` 顺手带走**。
+3. **拆前扫联接 / reparse point（物理安全性 = 铁律 5 的可执行判据）**。存成 `ci-artifacts/wt_junction_scan.py` 再跑：
+
+```python
+# 只读预扫：一个路径是不是 reparse point（Windows 目录联接在这里现形）；发现即停止深入，绝不 walk 进联接
+import os, ctypes
+FILE_ATTRIBUTE_REPARSE_POINT = 0x400
+GA = ctypes.windll.kernel32.GetFileAttributesW
+def is_reparse(p):
+    a = GA(p)
+    return a != -1 and bool(a & FILE_ATTRIBUTE_REPARSE_POINT)
+for name in ["verify-task16", "verify-batch", "und-attr", "bench-21-77779d49", "bench-23-1d4b6a17"]:
+    top = os.path.join(r"D:\Code\DTU Code\_wt", name)
+    hits, entries = [], 0
+    for root, ds, fs in os.walk(top):
+        bad = [d for d in ds if is_reparse(os.path.join(root, d))]
+        if bad:
+            hits += [os.path.join(root, d) + "/" for d in bad]
+            ds[:] = []                    # 有联接就不再深入：防转进主树 .venv 把别人整棵树数一遍
+        hits += [os.path.join(root, f) for f in fs if is_reparse(os.path.join(root, f))]
+        entries += len(ds) + len(fs)
+    print(f"== {name}  scanned entries={entries}")
+    print("   REPARSE: none → 可直接 git worktree remove --force"
+          if not hits else "   REPARSE:\n   " + "
+   ".join(hits))
+```
+
+   实测输出 `== verify-task16 ... REPARSE: none`（每棵的体积 / 条目数 + 零联接就是证据），而 `bench-*` 两棵各挂一个 `.venv`
+   联接 → 判 **KEEP**（本节不拆它们；将来真要拆，先 `rmdir` 摘掉联接再 remove）。
+   **判据是「扫出来一个都没有」，不是「我记得没建过联接」**：`new --no-bootstrap` 的树、别的手工 `mklink /J` 的树都可能带着指向主树的联接。
+   摘联接用 `rmdir`（只删联接本身；**不是** `rd /s`，更不是 `rm -rf`——那会顺着联接删目标）。
+   非 Windows 环境改用 `os.path.islink` / `find <tree> -type l`（本项目是 Windows + Keil 工具链，按上面这条走）。
+   **到这里才算「拆前唯一性自检 + 物理安全预扫」齐**：`--force` 的安全前提 = 第 2 步 `UNIQUE-UNMERGED` 为 0
+   （或剩下的已全部进第 4 步备份）**且**这里 `REPARSE: none`。
+4. **唯一内容先备份，再 `--force` 拆**。`UNIQUE-UNMERGED` 与需要留档的 `OLDER-DRAFT` 一律先备份进主树
+   `ci-artifacts/wt-leftover-backup/`（`ci-artifacts/` 已被 `.gitignore` 忽略 → **备份不会改变主树脏行数**；仓库根不放一次性产物），
+   **文件名 + 字节数必须打进输出**当证据：
+
+```bash
+BK="$MAIN/ci-artifacts/wt-leftover-backup"; mkdir -p "$BK"
+# 命名约定：<树名>__<原路径里的 / 换成 _>，反向可定位；台账备份统一后缀 .state-bak
+cp "$WTROOT/verify-batch/simulator/tests/README.md"   "$BK/verify-batch__simulator_tests_README.md"
+cp "$WTROOT/und-attr/scripts/check_nested_comment.py" "$BK/und-attr__scripts_check_nested_comment.py"
+ls -l "$BK"   # 实测：verify-batch__simulator_tests_README.md 1769 bytes / und-attr__scripts_check_nested_comment.py 14827 bytes
+for t in verify-task16 verify-batch und-attr; do
+  git -C "$MAIN" worktree remove --force "$WTROOT/$t"; echo "$t remove_rc=$?"   # 不接管道才读得到码（见「读输出」）
+done
+git -C "$MAIN" worktree prune    # 顺带清 .git/worktrees 里的残籍
+```
+
+   自检：**备份条目数 = 第 2 步里判「要留档」的条目数**，且每个都带字节数。这一步就是本节相对 D 第 4 步的增量——
+   D 的前提是「净室里只有自己的拷贝」，本节的树里混着别人在飞的东西，`--force` 是一次不可逆删除，**先备份才谈得上安全**。
+5. **复验：主树一个字节没动 + 树确实没了**：
+
+```bash
+git -C "$MAIN" status --porcelain -uall > ci-artifacts/wt-main-after.txt
+wc -l < ci-artifacts/wt-main-before.txt; wc -l < ci-artifacts/wt-main-after.txt   # 两个数必须相同（实测 0 → 0）
+diff ci-artifacts/wt-main-before.txt ci-artifacts/wt-main-after.txt               # 空输出 = 逐行一致
+git -c core.quotePath=false -C "$MAIN" worktree list    # 已拆路径逐条消失；主树与判「保留」的树原样在列
+```
+
+   行数不同 = 备份或摘除碰到了主线（多半是备份写进了未被忽略的目录，或漏摘联接）→ 立刻定位，别报「回收完成」。
+   第 2 步判「保留不动」的树还在 `worktree list` 里是**预期结果**，在报告里点名解释为什么留（附 `MERGED` 判据）。
+6. **顺手清悬挂台账**（branch / path 都已不存在的 `_wt/.state/<ID>.json`；它会让 `$TW list` 打出一行怪条目、并让下次
+   `new` 同 ID 报「任务 <ID> 已存在」）。先给证据、后动手：
+
+```bash
+for j in "$WTROOT"/.state/*.json; do          # 台账位置随 DTU_WT_ROOT
+  id=$(basename "$j" .json)
+  br=$("$PY" -c "import json,sys;print(json.load(open(sys.argv[1],encoding='utf-8')).get('branch',''))" "$j")
+  pp=$("$PY" -c "import json,sys;print(json.load(open(sys.argv[1],encoding='utf-8')).get('path',''))" "$j")
+  git -C "$MAIN" rev-parse --verify "$br" >/dev/null 2>&1 && b=branch-OK || b=branch-MISSING
+  [ -d "$pp" ] && p=path-OK || p=path-MISSING
+  echo "$id  $b  $p   <- $j"
+done
+```
+
+   实测这条判据打出的正是 `v5tool2  branch-MISSING  path-MISSING`：`git rev-parse task/v5tool2-v11` 报
+   `fatal: ambiguous argument 'task/v5tool2-v11': unknown revision ...`，台账 `path` 指的目录已无，`git worktree list` 里也没有这棵树。
+   **三条齐（rev-parse fatal + path 目录不存在 + worktree list 无此树）才叫悬挂**；缺任何一条都回到第 1~2 步查是不是真有东西要保。
+   然后**备份 → 删 → 复跑两条 list 复验**：
+
+```bash
+cp "$WTROOT/.state/v5tool2.json" "$BK/v5tool2.json.state-bak" && rm "$WTROOT/.state/v5tool2.json"
+"$PY" "$TW" list            # 该条目消失（全空时打「（没有任务空间。用 new <ID> <slug> 建一个）」），echo RC=$? 应为 0
+"$PY" "$TW" lock status     # build 空闲（TTL 1.0h）/ bench 空闲（TTL 6.0h）—— 证明清台账没牵连两把锁
+ls "$WTROOT"/.state/locks/ 2>/dev/null   # 若该 ID 名下还有 .lock，先按 B 节释放，再删台账
+```
+
+   - **必须 `cp` 先备份再 `rm`**：台账里存着 base / junctions / needs_bench / bench_pass，是真出纠纷时唯一的现场记录。
+   - 悬挂条目按定义 `path` 已不存在 → 通常**不占** `MAX_CONCURRENT = 8` 名额（A 第 1 步的「活跃」判据要求 path 目录还在），
+     但它把 `$TW list` 搅成怪输出、并永久挡住同 ID 复用；**path 还在的占位/残留台账才占名额**（早期为绕 B 节那个坑手写的占位台账就是这种）。两种都要清。
+   - **仍不对这个 ID 跑 `done` / `abort`**：清场会拿台账里的死 `path` / 死 `branch` 去做 `git worktree remove` 和删分支
+     （这正是 A 第 5 步说的「手工删目录留下的尾巴」，正解就是本步）。历史遗留的占位台账同理——活着时也别
+     `done` / `abort`，用完直接删文件（来历与现状见 B 末条）。
@@ -0,0 +1,44 @@
+## 验证
+
+- `$TW list`：台账段条目数 = `ls _wt` 的目录数且 ≤ 8（`MAX_CONCURRENT`）；刚回收的任务与历史占位条目都不再出现
+  （插件树另起一段，不参与这条计数）。
+- `$TW lock status`：`build  空闲（TTL 1.0h）` + `bench  空闲（TTL 6.0h）`——没有本会话留下的持有者。
+- `git log --oneline -3`：能看到 `merge: task/<ID>-<slug> 合入 <base>` 与其后的补基线提交；
+  `git status --porcelain` 为空（补链改动已提交，才谈得上重跑 `done`）。
+- `ls _wt/.state/`：该 ID 的台账已无（清场最后一步 unlink）；重复 `done` 报「任务不存在」不必再追。
+- **E 节回收**：`git worktree list` 只剩主树 + 判「保留不动」的树（已拆路径逐条消失）；**拆前/拆后主树
+  `git status --porcelain -uall` 行数相同且 `diff` 为空**（实测 0 → 0）；`ci-artifacts/wt-leftover-backup/` 里每个留档件都打印过
+  文件名与字节数、条目数 = 分桶判「要留档」的条目数；每棵被拆的树都留有 `REPARSE: none` 预扫记录；全景输出里
+  `UNIQUE-UNMERGED` 归零（或全部已备份）；保留树在报告里点名给出判据（`merge-base --is-ancestor` = MERGED）。
+- **E 第 6 步清悬挂台账**：该 json 已从 `_wt/.state/` 消失（`.state-bak` 在备份目录里）、`$TW list` 不再打出它、
+  `$TW lock status` 两把锁仍空闲；全程未对该 ID 跑 `done` / `abort`。
+- **F 节桥接**：`plugin list` 的「联接」列按实际三态点名（`已联` / `缺 .venv` / `缺 SDL2` /
+  `齐(实体SDL2)`——旧实现只取样 `.venv`，半联树会说谎）；**adopt/unadopt 前后主树 `.venv` 与树内文件都
+  还在**；主线缺 SDL2 时 `adopt` 打 `[skip]` + 「还不能算就绪」而不打「现在可以跑」；`plugin adopt ".."`
+  必须 exit 2；打印的 `pw:<name>` 与 `keil_build.py` 从 cwd 反推的名字逐字相同；`done <插件树名>` 只 exit 2。
+- **C2 主树被别的会话弄脏时的手工合并**：合并前打印过 `git merge-tree --write-tree` 的结果树 sha 且 `MT_RC=0`；
+  合并用 `git merge --no-ff --no-edit -F ci-artifacts/merge-msg-<slug>.txt`（UTF-8 无 BOM）并写明绕开 `done` 的理由；
+  外部文件合并前后的 `git hash-object` **逐字符相同**、`git diff --stat` 同一组数字、`status` 里仍是 `M`
+  （没被提交也没被清掉；实测同为 `369380ca…`、2+/2−）；台账先 `cp` 成 `<ID>.json.state-bak` 再由 `$TW done`
+  （或 E 节手工路径）摘联接拆树；收工前 `git worktree list` 只剩主树 + 别人的在飞树（点名保留）、
+  `$TW lock status` 两把锁均空闲（`build 空闲（TTL 1.0h）` / `bench 空闲（TTL 6.0h）`）。
+- **G 节树内门禁**：`<tree>/ci-artifacts/` 先 `mkdir -p` 再写、事后 `ls` 得到真实文件（`cat` 读得到内容）；
+  树内 `check_doc_links.py` 按**单文件**跑并打印「N 处 / 机器可判定百分比 / rc」（实测 161 处/98%/rc=0、16 处/88%/rc=0）；
+  全库 `--all` 只在合并后的**主树**跑（实测 2,597 处 / 194 个文档 / rc=0）；若树内跑过 `--all` 且判红，报告里
+  必须给得出「过滤 `simulator/SDL2` 后与主树同命令基线对比」这一步。
+- D 节归因：测量前后 `git -C "$MAIN" status --porcelain` **逐行一致**（主树全程只读）；
+  `git worktree list` 里净室路径已消失；逐文件增量之和 **等于**观察到的涨幅（实测 +6+8+2 = +16），且每处增量
+  都指到具体字面量类别（裸形 「字母 T 累进数字 4」）与属主；取数走 `import check_ids` 读 `ck.stats`，且门禁脚本自身 `git diff` 为空。
+- 补绿链的每一条都自己 `echo RC=$?` 看到 0，最后以重跑 `done` 打出的**清场日志**（`已摘除联接` /
+  `已删除分支` / `完成（分支此前已合入）`）为成功判据，而不是 `tail` 出来的最后一行。
+- **树内提交 / 合并信息（G 节）**：`git log -1 --pretty=%B | grep -c '<被清退主题关键词>'` 打出 **0**（标题 + 正文 +
+  合并信息三处都查过）；消息文件在 `ci-artifacts/`、UTF-8 无 BOM、CR=0、标题 ≤100、正文最长行 ≤80（实测 31/50、32/55）；
+  自审发现消息统计算错是在**未推送**状态下 `--amend -F` 修掉的，历史里没有「更正」提交。
+- **文档改动体检（G 节）**：提交前打印过 `lines/bytes/BOM/CR/U+FFFD/三连续空行/行尾空格/末行 LF` 与表格列数一致性，
+  并区分「本次改动引入 = 0」与「文件里既有的坏行」（实测两处历史坏表格与本次无关，只在报告里点名）。
+- **F 节分级与自持理由**：判 `simulator/SDL2` 为硬需求要给出 `simulator/CMakeLists.txt:12`（非 CACHE）+ 派生路径行号
+  （:34/:70/:71/:180/:207）；判 `.venv` 为软需求要给出 `DTU_PRECOMMIT_PYTHON` 与 `ci_local.py` 五级解释器候选顺序；
+  答「为什么不用插件」时报出插件包版本、文件与三个概念的 grep 命中数，并说明重叠只在 `git worktree add` 的开/收两个动作。
+- **改并行上限数字**：唯一事实源 = `task_worktree.py` 的 `MAX_CONCURRENT`（报错文案与 `new` 提示都 `.format()` 插值它，
+  实测 `:764-766` / `:768-771`），其余全是引用同步；隔离小仓验证到「8 棵成功、第 9 棵不带 `--force` 被拒」，
+  且没在真仓 `../_wt` 及其 `.state/` 留下验证树。
@@ -27,12 +27,12 @@ for _stream in (sys.stdout, sys.stderr):
 EXIT_OK, EXIT_FAIL, EXIT_ENV, EXIT_USAGE = 0, 1, 2, 3

 BRANCH_PREFIX = "task/"
-MAX_CONCURRENT = 3
+MAX_CONCURRENT = 8
 LOCK_NAMES = ("build", "bench")
 # 按锁分设陈旧窗口（小时）——兜底窗口应与「操作真实时长」同量级：
 #   build：编译是秒~分钟级（keil_build.py 自持自释，持有窗口 ≈ UV4 运行时长，
 #          上限 = --timeout，默认 600s）；崩溃泄漏时应在数十分钟内即可接管 → 1h。
-#   bench：会话级（flash → @test → 探针，天然几十分钟~数小时）→ 保留 6h。
+#   bench：会话级（flash → /serial-boot-test → 探针，天然几十分钟~数小时）→ 保留 6h。
 # 另：锁 payload 里持有者可用 `ttl` 字段自报窗口（见 lock_acquire(ttl=...)），
 # 优先于这里的默认值——这样 build 锁的窗口能自动跟随其 --timeout。
 LOCK_TTL_HOURS = {"build": 1.0, "bench": 6.0}
@@ -82,6 +82,15 @@ BASE_BRANCH = os.environ.get("DTU_TASK_BASE", "v2-on-ui")
 STATE_DIR = WT_ROOT / ".state"
 LOCKS_DIR = STATE_DIR / "locks"

+# DSH 的 worktree 插件（包名 dsh-task-worktree；模型工具 worktree_create、人类命令
+# /worktree）把任务树建在**仓库内**这个命名空间下，与本 skill 的仓外 _wt/ 刻意分开。
+# .gitignore 里预置同名规则，正是为了让插件的 ensureIgnored() 见到就跳过、
+# 不在会话中途往这份受控文件里追加一行。
+PLUGIN_ROOT = REPO_ROOT / ".dsh-worktrees"
+PLUGIN_NAMESPACE = "worktree"            # 插件侧 WORKTREE_NAMESPACE：name 即分支尾段
+PLUGIN_SUBDIR = PLUGIN_ROOT / PLUGIN_NAMESPACE
+PLUGIN_LOCK_PREFIX = "pw"                # 插件树在锁 payload 里的持有者前缀
+

 # --------------------------------------------------------------------- 基础工具

@@ -390,33 +399,232 @@ def bootstrap(wt: Path):
    return made


+# --------------------------------------------------------------------- DSH 插件工作树
+#
+# 插件建的树（.dsh-worktrees/worktree/<name>）缺三样东西，下面的命令逐条补。
+# 回收**不在这里**：插件树由「/worktree remove|prune」收，done/abort 也不该拿去处理它。
+#   1. 共享联接——没有 .venv 与 simulator 的 SDL2 SDK，插件树里「.venv\Scripts\python.exe」
+#      直接找不到解释器：/keil-build、ci_local.py、所有 scripts/check_*.py 全部起跑失败；
+#   2. 可见性——插件树不在台账里，「list」看不见它，8 个活跃名额也只数登记任务；
+#   3. 独占资源归属——build 锁由 keil_build.py 自持自释（按 cwd 反推持有者名，
+#      插件树里算成 pw:<name>），bench 锁仍要人占，占锁名得和「lock status」对得上。
+
+
+def plugin_lock_owner(name: str) -> str:
+    """插件树在锁 payload 里的持有者名：pw:<name>（多段名压平成 -）。
+
+    必须与 keil_build.py 的 default_lock_task() 对同一种树算出的名字一致——这样构建
+    自持自释留下的归属，和手工「lock acquire bench --task pw:x」才是同一个可 grep 的标识。
+    """
+    # 与 plugin_dir_for 同样容忍「worktree/」前缀，否则同一棵树会出现两个持有者名
+    # （pw:refactor-logging vs pw:worktree-refactor-logging），lock status 就散了。
+    segs = [s for s in name.replace(os.sep, "/").strip("/").split("/") if s]
+    if segs and segs[0] == PLUGIN_NAMESPACE:
+        segs = segs[1:]
+    return "{}:{}".format(PLUGIN_LOCK_PREFIX, "-".join(segs) or "?")
+
+
+def plugin_dir_for(name: str) -> Path:
+    """插件 worktree 名 → 树目录；**只允许落在 .dsh-worktrees/worktree/ 里面**。
+
+    adopt/unadopt 会在解析出的目录上建/摘目录联接；不加这道闸，等于允许把主工作树或
+    任意 _wt 目录当插件树动手（联接会遮蔽真实内容，事后很难看出来）。
+    """
+    raw = (name or "").strip().replace(os.sep, "/").strip("/")
+    if not raw:
+        raise EnvError("缺插件 worktree 名（先跑「plugin list」看现有树）")
+    if raw == PLUGIN_NAMESPACE or raw.startswith(PLUGIN_NAMESPACE + "/"):
+        raw = raw[len(PLUGIN_NAMESPACE):].strip("/")
+    p = (PLUGIN_SUBDIR / raw).resolve()
+    base = PLUGIN_SUBDIR.resolve()
+    if p == base or base not in p.parents:
+        raise EnvError("拒绝 {}：只接受 {} 里面的树".format(p, PLUGIN_SUBDIR))
+    return p
+
+
+def junction_states(wt: Path):
+    """每个共享联接的三态：link（目录联接）/ real（实体内容）/ absent（真缺）。
+
+    这是「联没联上」的**唯一**判定处——列表显示与 adopt 收尾都读它。早先列表只取样
+    JUNCTION_SPECS 的第一项，于是「有 .venv、缺 simulator/SDL2」的半联树被报成已联，
+    而 adopt 可以只成功一条（主线缺 SDL2 走 skip、联接失败走 warn）→ 说谎的正是这一列。
+    """
+    st = {}
+    for rel, _desc in JUNCTION_SPECS:
+        link = wt / rel
+        if is_reparse(link):
+            st[rel] = "link"
+        elif os.path.lexists(str(link)):
+            st[rel] = "real"
+        else:
+            st[rel] = "absent"
+    return st
+
+
+def junction_label(st) -> str:
+    """把三态压成一列短标签：缺什么都点名，实体内容也算「齐」但不算共享。"""
+    tag = {rel: rel.rsplit("/", 1)[-1] for rel in st}
+    absent = [tag[r] for r, s in st.items() if s == "absent"]
+    real = [tag[r] for r, s in st.items() if s == "real"]
+    if absent:
+        return "缺 " + "+".join(absent)
+    return "齐(实体" + "+".join(real) + ")" if real else "已联"
+
+
+def plugin_trees():
+    """.dsh-worktrees/worktree/ 下的工作树（事实源 = git worktree list，不读插件 manifest）。
+
+    manifest.json 是插件私有格式（MANIFEST_VERSION 1，字段随版本变），而 git 的注册表
+    同时覆盖「插件正常建的树」和「manifest 丢了 / 树被手工删」的残留——桥接命令要看的
+    是真实存在的东西。
+    """
+    try:
+        base = PLUGIN_SUBDIR.resolve()
+    except OSError:
+        return []
+    trees = []
+    for ent in worktree_entries():
+        p = ent["path"]
+        try:
+            rp = p.resolve()
+        except OSError:
+            continue
+        if rp == base or base not in rp.parents:
+            continue
+        dirty = (len(git_out("status", "--porcelain", cwd=p, check=False).splitlines())
+                 if p.is_dir() else -1)
+        trees.append({
+            "name": rp.relative_to(base).as_posix(),
+            "path": str(p),
+            "branch": ent.get("branch") or "(detached)",
+            "dirty": dirty,
+            "jn": junction_states(p),
+        })
+    return trees
+
+
+def print_plugin_trees() -> int:
+    """打印插件树一览（无树则静默），返回数量——「list」与「new」共用同一事实。"""
+    trees = plugin_trees()
+    if not trees:
+        return 0
+    print()
+    print("DSH 插件工作树（{} 下；**不在本 skill 台账** → 不占 {} 个名额、done/abort "
+          "管不到，回收走 /worktree remove|prune）：".format(PLUGIN_SUBDIR, MAX_CONCURRENT))
+    print("{:<26} {:<34} {:>4} {:>16}".format("名称", "分支", "脏", "联接"))
+    for t in trees:
+        print("{:<26} {:<34} {:>4} {:>16}".format(
+            t["name"], t["branch"], "-" if t["dirty"] < 0 else str(t["dirty"]),
+            junction_label(t["jn"])))
+    def miss(rel):
+        return any(t["jn"].get(rel) == "absent" for t in trees)
+    if miss(".venv"):
+        print("  缺 .venv：进去跑 /keil-build / ci_local.py 会**静默**落到机器级解释器（无 "
+              "fontTools，generated-fresh 假红的老根因）")
+    if miss("simulator/SDL2"):
+        print("  缺 simulator/SDL2：模拟器 build_sim.bat 直接报错——CMakeLists.txt 的 "
+              "SDL2_DIR 是裸 set，没有环境变量逃生口")
+    if miss(".venv") or miss("simulator/SDL2"):
+        print("  补法：「plugin adopt <name>」——只建缺失的联接，不碰树里任何文件")
+    return len(trees)
+
+
+def adopt_junctions(wt: Path):
+    """只补**缺失**的共享联接（已联的跳过、实体目录绝不碰），返回 (已有, 本次新建)。"""
+    already, made = [], []
+    st = junction_states(wt)
+    for rel, desc in JUNCTION_SPECS:
+        link = wt / rel
+        if st[rel] == "link":
+            already.append(rel)
+            continue
+        if st[rel] == "real":
+            print("[warn] {} 已是实体目录/文件（不是联接）——不动它".format(rel))
+            already.append(rel)
+            continue
+        target = REPO_ROOT / rel
+        if not target.exists():
+            print("[skip] {}（{}）主线里不存在，跳过".format(rel, desc))
+            continue
+        try:
+            make_junction(link, target)
+        except (Fail, EnvError) as err:
+            print("[WARN] {} 联接失败：{}".format(rel, err))
+            continue
+        made.append(rel)
+        print("[ok]   联接 {} -> {}".format(rel, target))
+    return already, made
+
+
+def cmd_plugin(a) -> int:
+    if a.action == "list":
+        if print_plugin_trees() == 0:
+            print("（{} 下没有插件工作树）".format(PLUGIN_SUBDIR))
+            print("  建法：新会话输入框选「Worktree模式」/ 让模型调 worktree_create / "
+                  "/worktree create <name>")
+            print("  建完回来「plugin adopt <name>」补共享联接，才能在里面跑 /keil-build 与门禁。")
+        return EXIT_OK
+
+    wt = plugin_dir_for(a.name)
+    if not wt.is_dir():
+        raise EnvError("目录不存在：{}（先用插件建树：/worktree create 或 worktree_create）".format(wt))
+
+    if a.action == "adopt":
+        if git("rev-parse", "--git-dir", cwd=wt, check=False).returncode != 0:
+            raise EnvError("{} 不是 git 工作树（别拿普通目录当插件树）".format(wt))
+        print("为插件树补共享联接：{}".format(wt))
+        already, made = adopt_junctions(wt)
+        owner = plugin_lock_owner(a.name)
+        # 复算一次：adopt 里 skip/warn/失败都不算成功，「已有 N + 新建 M」两两相加可能对不上
+        # 总数——就绪判定只能按**现在的实际状态**说，否则又是把没联上的说成联上了
+        still = [r for r, s in junction_states(wt).items() if s == "absent"]
+        print()
+        print("[ok] 联接：已有 {} 个、本次新建 {} 个".format(len(already), len(made)))
+        if still:
+            print("[warn] 仍缺 {}：主线里该路径不存在或联接失败——先补主线再复跑 adopt"
+                  "（这棵树还不能算就绪）".format("、".join(still)))
+        else:
+            print("该目录现在可以跑 /keil-build / ci_local.py / /serial-boot-test")
+        print("build 锁由 keil_build.py 自持自释，持有者名就是 {}".format(owner))
+        print("上台架前：$TW lock acquire bench --task {} --note <说明>".format(owner))
+        print("下台架后：$TW lock release bench --task {}".format(owner))
+        print("回收仍归插件：/worktree remove {}（本 skill 不删插件树）".format(a.name))
+        return EXIT_OK
+
+    removed = [rel for rel, _spec in JUNCTION_SPECS if remove_junction(wt / rel)]
+    print("[ok] 摘掉联接：{}（只摘联接本身，绝不动目标内容与树里文件）".format(
+        "、".join(removed) if removed else "无（该树没有联接着）"))
+    return EXIT_OK
+
+
 # --------------------------------------------------------------------- 子进程脚本


+
 def regen(cwd: Path) -> None:
    run_script("scripts/gen_task_table.py", ["--write"], cwd, "重生成 FreeRTOS 任务表")
    if list((Path(cwd) / "MDK-ARM").glob("**/*.map")):
        run_script("scripts/check_mem_numbers.py", ["--write"], cwd, "同步内存/Flash 快照")
    else:
-        print("[skip] 未找到 .map，跳过内存快照同步（需先 @build）")
+        print("[skip] 未找到 .map，跳过内存快照同步（需先 /keil-build）")


 def run_gates(cwd: Path, skip_build: bool) -> bool:
-    ok = run_script("scripts/ci_local.py", [], cwd, "L0 + L0.5 本地等价 CI")
+    ok = run_script("scripts/ci_local.py", [], cwd, "静态门禁 + 主机侧纯逻辑单测 本地等价 CI")
    if skip_build:
-        print("[skip] 按 --skip-build 跳过 @build")
+        print("[skip] 按 --skip-build 跳过 /keil-build")
        return ok
    got, info = lock_acquire("build", "__done__", wait=900)
    if not got:
-        print("!! build 锁被 {} 占用（UV4 不能并发构建），跳过 @build".format(info.get("task")))
+        print("!! build 锁被 {} 占用（UV4 不能并发构建），跳过 /keil-build".format(info.get("task")))
        return False
-    # 告知 @build「调用方已持锁」：新版 keil_build.py 自持自释（见其 docstring），
+    # 告知 /keil-build「调用方已持锁」：新版 keil_build.py 自持自释（见其 docstring），
    # 读到本变量即跳过，避免自我死锁；**旧版根本不看此变量、也不会自锁**，
    # 故此处对「工作树里还是旧脚本」的在途任务同样安全（向后兼容）。
    os.environ["DTU_LOCK_HELD"] = "build"
    try:
        if not run_script(".dsh/skills/keil-build/scripts/keil_build.py", [], cwd,
-                          "@build（0 错 0 警）"):
+                          "/keil-build（0 错 0 警）"):
            ok = False
    finally:
        os.environ.pop("DTU_LOCK_HELD", None)
@@ -557,6 +765,10 @@ def cmd_new(a) -> int:
        raise EnvError("已有 {} 个活跃任务（上限 {}）；先 done/abort，或加 --force".format(
            len(active), MAX_CONCURRENT))

+    n_plugin = len(plugin_trees())
+    if n_plugin:
+        print("[i] 另有 {} 个 DSH 插件工作树（.dsh-worktrees/，不计入上限 {}）；"
+              "磁盘与 UV4 / 台架仍是共享资源——「plugin list」看清单".format(n_plugin, MAX_CONCURRENT))
    WT_ROOT.mkdir(parents=True, exist_ok=True)
    print("[1/3] 建工作树（分支 {}，基线 {}{}）…".format(
        branch, a.base, "，跳过 LFS smudge" if a.lean else ""))
@@ -577,7 +789,7 @@ def cmd_new(a) -> int:
    print()
    print("下一步：把新会话的工作目录切到")
    print("  " + str(wt))
-    print("在该目录里干活、跑 @build 与 ci_local.py（并行安全）；")
+    print("在该目录里干活、跑 /keil-build 与 ci_local.py（并行安全）；")
    print("要动台架先 `lock acquire bench --task {}`，完事 `lock release bench --task {} --bench-pass`。".format(
        a.task_id, a.task_id))
    print("回收用 `done {}`（**必须在主工作树执行**）。".format(a.task_id))
@@ -588,6 +800,7 @@ def cmd_list(a) -> int:
    states = all_states()
    if not states:
        print("（没有任务空间。用 `new <ID> <slug>` 建一个）")
+        print_plugin_trees()
        return EXIT_OK
    print("{:<12} {:<32} {:>5} {:>5} {:>4}  {}".format(
        "任务", "分支", "落后", "领先", "脏", "台架"))
@@ -612,6 +825,7 @@ def cmd_list(a) -> int:
        else:
            print("锁 {:<6} {} 持有（已 {:.1f} 小时，于 {}）".format(
                n, info.get("task"), lock_age_hours(info), info.get("at")))
+    print_plugin_trees()
    return EXIT_OK


@@ -692,10 +906,19 @@ def cmd_lock(a) -> int:
    if a.bench_pass:
        if not a.task:
            raise EnvError("--bench-pass 需要 --task <ID>")
-        st = load_state(a.task)
-        st["bench_pass"] = True
-        save_state(st)
-        print("[ok] 已为任务 {} 记录台架 PASS".format(a.task))
+        # 非登记持有者（lead 的验收窗、插件树 pw:*）没有台账。以前这里先 load_state
+        # 就抛「任务 X 不存在（缺台账）」，**根本走不到释放**：锁还挂着，而 done 的前置
+        # 会因活锁判失败——一个名字没登记，就挡住所有任务的收口。现在降级为显式告警 +
+        # 照常释放：PASS 没进台账是事实，但不该拿「锁放不掉」当代价。
+        if state_file(a.task).is_file():
+            st = load_state(a.task)
+            st["bench_pass"] = True
+            save_state(st)
+            print("[ok] 已为任务 {} 记录台架 PASS".format(a.task))
+        else:
+            print("[warn] 任务 {} 无台账（{}）→ **跳过 PASS 记录，仅释放锁**；要把 PASS 留在"
+                  "台账里就得用已「new」出来的任务 ID 占锁，或把验收结论写进主干提交说明/文档"
+                  .format(a.task, state_file(a.task)))
    ok, msg = lock_release(a.name, a.task, force=a.force)
    print(msg)
    return EXIT_OK if ok else EXIT_FAIL
@@ -747,13 +970,15 @@ def cmd_done(a) -> int:
        raise Fail("任务分支相对 {} 没有新提交，无需合并".format(base))
    if already and ahead == 0:
        print("[i] {} 已合入 {}，跳过合并，直接清场".format(branch, base))
+        print("[i] 该路径在门禁之前就返回——不替你复绿；上一次门禁没跑到的尾巴，"
+              "清场后去主树跑 `postmerge`（或手工 ci_local + check_doc_links --all）")
        print("=== 清场 ===")
        teardown_worktree(st, force=a.force, base=base)
        print("\n完成（分支此前已合入）。")
        return EXIT_OK

    if st.get("needs_bench") and not st.get("bench_pass"):
-        raise Fail("任务标记 --needs-bench 但无台架 PASS 记录；跑完 @test 后执行 "
+        raise Fail("任务标记 --needs-bench 但无台架 PASS 记录；跑完 /serial-boot-test 后执行 "
                   "`lock release bench --task {} --bench-pass`".format(st["id"]))
    print("[ok] 前置检查通过（领先 {} 共 {} 个提交）".format(base, ahead))

@@ -797,6 +1022,7 @@ def cmd_done(a) -> int:
        print("!! 门禁未全绿：工作树与分支**保留**，未清场。")
        print("   主干已含合并提交 {}".format(base_after[:12]))
        print("   可选：a) 在主工作树修正后追加提交（推荐）")
+        print("         ——体积凭证/台账红就用 `postmerge` 自动诊断回填，别手抄补链")
        print("         b) 回退本次合并：git -C \"{}\" reset --hard {}".format(main, base_before[:12]))
        return EXIT_FAIL

@@ -808,6 +1034,130 @@ def cmd_done(a) -> int:
    return EXIT_OK


+# ------------------------------------------------- 树内预检 / 合并后补绿（机械化）
+
+
+HYGIENE_BINARY = (".png", ".jpg", ".gif", ".ico", ".ttf", ".bin", ".hex", ".elf",
+                  ".axf", ".o", ".crf", ".lst", ".zip", ".gz", ".pdf", ".cur")
+CR_EXEMPT = (".bat", ".cmd")  # .gitattributes 强制 CRLF
+
+
+def _git_bytes(*args, cwd=None):
+    r = subprocess.run(["git"] + [str(x) for x in args], cwd=str(cwd or REPO_ROOT),
+                       capture_output=True, stdin=subprocess.DEVNULL)
+    return r.stdout if r.returncode == 0 else None
+
+
+def _changed_paths(cwd: Path):
+    q = ("-c", "core.quotePath=false")  # 中文文件名不许被八进制转义出去
+    tracked = git(*q, "diff", "--name-only", "HEAD", cwd=cwd, check=False).stdout
+    others = git(*q, "ls-files", "--others", "--exclude-standard", cwd=cwd, check=False).stdout
+    return ([p.strip() for p in tracked.splitlines() if p.strip()],
+            [p.strip() for p in others.splitlines() if p.strip()])
+
+
+def cmd_precheck(a) -> int:
+    """树内自查（只读）：字节体检 + docs 逐档门禁 + 可选提交信息检查。绝不代改。"""
+    cwd = Path.cwd()
+    (cwd / "ci-artifacts").mkdir(exist_ok=True)  # 新树没有 ci-artifacts（G 节：ENOENT 坑）
+    tracked, untracked = _changed_paths(cwd)
+    print("[i] {}：改动 {} 个（tracked {} + untracked {}）".format(
+        cwd, len(tracked) + len(untracked), len(tracked), len(untracked)))
+    bom3, cr, fffd = bytes.fromhex("efbbbf"), b"\r", bytes.fromhex("efbfbd")
+    problems, docs = 0, []
+    for p in tracked + untracked:
+        f = cwd / p
+        if not f.is_file() or p.lower().endswith(HYGIENE_BINARY):
+            continue
+        b = f.read_bytes()
+        bad = []
+        if cr in b and not p.lower().endswith(CR_EXEMPT):
+            bad.append("CR")
+        n = b.count(fffd)
+        if n:
+            bad.append("U+FFFD x{}".format(n))
+        if p in tracked:
+            hb = _git_bytes("show", "HEAD:" + p, cwd=cwd)
+            if hb is not None and hb.startswith(bom3) and not b.startswith(bom3):
+                bad.append("BOM 漂移（HEAD 有 BOM、工作区没了——bom-guard 会拦）")
+        if p.startswith("docs/") and p.endswith(".md"):
+            docs.append(p)
+        if bad:
+            problems += 1
+            print("!! {}：{}".format(p, " / ".join(bad)))
+    for d in docs:
+        if not run_script("scripts/check_doc_links.py", [d], cwd, "文档门禁 " + d, tail=6):
+            problems += 1
+    if a.msgfile:
+        m = Path(a.msgfile)
+        if not m.is_file():
+            raise EnvError("消息文件不存在：{}".format(m))
+        mb = m.read_bytes()
+        if mb.startswith(bom3):
+            problems += 1
+            print("!! 消息带 BOM（commit -F 要 UTF-8 无 BOM）")
+        if cr in mb:
+            problems += 1
+            print("!! 消息含 CRLF")
+        ml = mb.decode("utf-8", "replace").splitlines()
+        for i, ln in enumerate(ml):
+            lim = 100 if i == 0 else 80
+            if len(ln) > lim:
+                problems += 1
+                print("!! 消息第 {} 行长 {} > {}".format(i + 1, len(ln), lim))
+                break
+        for w in a.ban:
+            c = mb.decode("utf-8", "replace").lower().count(w.lower())
+            print("[i] 禁词 {!r}：{} 次".format(w, c))
+            if c:
+                problems += 1
+    print("完成：问题 {} 个".format(problems))
+    return EXIT_OK if problems == 0 else EXIT_FAIL
+
+
+def cmd_postmerge(a) -> int:
+    """主树合并后补绿：体积凭证自动诊断（短链/全链）+ 文档全量。列文件，不提交。
+
+    裁定外包给现有门禁：凭证红 → 先短链（--update 重写）→ 用只读的
+    check_mem_numbers 复检裁定数字是否真变——红了才升级全链（--write 族）。
+    """
+    main = main_worktree()
+    if Path.cwd().resolve() != main.resolve():
+        raise EnvError("postmerge 必须在主工作树跑：{}".format(main))
+    if not list((main / "MDK-ARM").glob("**/*.map")):
+        raise EnvError("主树没有 .map——先 /keil-build 0/0 再回来（C.5 的前提）")
+    gate = "scripts/check_size_gate.py"
+    if not a.force and run_script(gate, ["--local"], main, "体积凭证检查（同码）", tail=8):
+        print("[ok] 凭证同码新鲜，无需补链")
+    else:
+        run_script("scripts/ram_baseline.py", ["--update"], main, "短链：重写体积凭证", tail=6)
+        mem_ok = (a.skip_mem or run_script("scripts/check_mem_numbers.py", [], main,
+                                           "受管区一致性复检（只读）", tail=8))
+        if not mem_ok:
+            print("[i] 快照与 .map 真漂了 → 升级全链（数字变了才动受管区）")
+            run_script("scripts/check_mem_numbers.py", ["--write"], main, "同步内存快照")
+            run_script("scripts/ram_baseline.py", ["--write"], main, "同步 RAM 预算台账")
+        if a.coverage:
+            run_script("scripts/check_test_coverage.py", ["--update-baseline"], main,
+                       "覆盖率基线刷新", tail=6)
+        if not run_script(gate, ["--local"], main, "凭证复检（期望绿）", tail=8):
+            print("!! 凭证复检仍红——贴输出查 check_size_gate 原因，别硬提交")
+            return EXIT_FAIL
+    ok = True
+    if not a.skip_docs:
+        ok = run_script("scripts/check_doc_links.py", ["--all"], main, "文档全库检查", tail=8)
+    dirty = git("-c", "core.quotePath=false", "diff", "--name-only", "HEAD",
+                cwd=main, check=False).stdout.splitlines()
+    dirty = [x.strip() for x in dirty if x.strip()]
+    if dirty:
+        print()
+        print("[i] 回填产物（提交属 Ask first，本命令不代提交）：")
+        for p in dirty:
+            print("  - " + p)
+        print("   建议：git add <上面列的文件> && git commit -F <正文文件>")
+    return EXIT_OK if ok else EXIT_FAIL
+
+
 def cmd_abort(a) -> int:
    st = load_state(a.task_id)
    wt = Path(st["path"])
@@ -874,11 +1224,17 @@ def build_parser():
                   help="release bench 时顺带为该任务记录台架 PASS")
    p.set_defaults(func=cmd_lock)

+    p = sub.add_parser("plugin", help="DSH worktree 插件的树（.dsh-worktrees/）：list / adopt / unadopt")
+    p.add_argument("action", choices=["list", "adopt", "unadopt"])
+    p.add_argument("name", nargs="?", default="",
+                   help="插件 worktree 名（可带 worktree/ 前缀或多段斜杠）")
+    p.set_defaults(func=cmd_plugin)
+
    p = sub.add_parser("done", help="回收：预演 → 合入主干 → 审计 → 重生成 → 门禁 → 清场")
    p.add_argument("task_id")
    p.add_argument("--base", default=None)
    p.add_argument("--dry-run", action="store_true", help="只预演，不做任何改动")
-    p.add_argument("--skip-build", action="store_true", help="跳过 @build")
+    p.add_argument("--skip-build", action="store_true", help="跳过 /keil-build")
    p.add_argument("--skip-gates", action="store_true", help="跳过全部门禁")
    p.add_argument("--force", action="store_true", help="清场时强制移除工作树")
    p.set_defaults(func=cmd_done)
@@ -887,6 +1243,18 @@ def build_parser():
    p.add_argument("task_id")
    p.add_argument("--force", action="store_true")
    p.set_defaults(func=cmd_abort)
+
+    p = sub.add_parser("precheck", help="树内自查（只读）：字节体检 + docs 逐档门禁 + 可选消息检查")
+    p.add_argument("--msgfile", default=None, help="附带检查提交信息文件（BOM/CRLF/行长/禁词）")
+    p.add_argument("--ban", action="append", default=[], help="禁词，可重复")
+    p.set_defaults(func=cmd_precheck)
+
+    p = sub.add_parser("postmerge", help="主树合并后补绿：体积凭证自动诊断（短/全链）+ 文档全量；不代提交")
+    p.add_argument("--force", action="store_true", help="凭证新鲜也强制走一遍 --update")
+    p.add_argument("--coverage", action="store_true", help="附带覆盖率基线刷新")
+    p.add_argument("--skip-docs", action="store_true", help="跳过 check_doc_links --all")
+    p.add_argument("--skip-mem", action="store_true", help="只挪凭证，跳过受管区复检/全链")
+    p.set_defaults(func=cmd_postmerge)
    return ap


@@ -31,7 +31,7 @@ cmake --build simulator/build --config Debug   # 0) 构建模拟器（须 0 警
 |---|---|---|
 | 内容页 FAIL，且**有意**改了该页视觉 | 预期变化 | 先肉眼确认新效果正确（窗口模式或 `i1_to_png.py` 出图对照 mockup），再 `.venv\Scripts\python.exe simulator/tests/check_content_pages.py --update` 刷参考，`git diff` 检查 ref/ 变化后随代码提交 |
 | 内容页 FAIL，但**未**有意改视觉 | bug（缺字/几何漂移/样式回归） | 修代码；**禁止**刷参考掩盖 |
-| 池水位门禁失败但像素一致 | 结构/样式变更（常量样式转换、增删框体等） | 确认新值合理（残留分解见 `菜单页面设计.md` §9.5）→ 更新脚本常量 + 在流程文档变更记录登记 |
+| 池水位门禁失败但像素一致 | 结构/样式变更（常量样式转换、增删框体等） | 确认新值合理（残留分解见 `菜单页面设计.md` §9.5）→ 更新脚本常量 + 把新值与它的实测来源写进 `docs/UI设计/UI_自动化测试流程.md` 正文常量表（2026-10-28 起不再记流水，见 `docs/文档规范.md` §5.1） |
 | 菜单回归失败 | 结构断言（白带占比/边框/往返一致） | 按脚本打印的未过断言清单逐项修代码，无参考文件可刷 |

 ## 池水位门禁常量（在脚本头部）
@@ -47,7 +47,7 @@ cmake --build simulator/build --config Debug   # 0) 构建模拟器（须 0 警

 ## 关联注意

- `.venv` 缺失/换机：`& <本机任一 python ≥3.10> -m venv .venv; & '.venv\Scripts\python.exe' -m pip install -r requirements.txt`（`requirements.txt` 已含 `pre-commit`，重建后 L0 门禁直接可跑）
+- `.venv` 缺失/换机：`& <本机任一 python ≥3.10> -m venv .venv; & '.venv\Scripts\python.exe' -m pip install -r requirements.txt`（`requirements.txt` 已含 `pre-commit`，重建后静态门禁直接可跑）
 - 新增 UI `.c` 文件先走 `new-source-file` skill 双端注册，否则一端静默缺文件
 - 改 `ui_menu_tree.txt` 或界面里的中文字符串 → **同一笔**重跑生成器（`tools/menu_gen/gen_menu.py`；字体走 **font-regen** 四步），否则提交门禁 `generated-fresh` 直接拦：它把生成器拷进系统临时目录重跑、与工作区逐字节比对（实证 `0f7b5a87` 改了模板没重跑）→ `docs/门禁说明/generated-fresh.md`
 - 字体重生成后全页大面积像素差异属预期：确认字形正确后 `--update` 刷参考
@@ -1,22 +1,24 @@
 # Gitea Actions CI —— STM32F4-Base 持续集成
 #
-# 覆盖范围（**只做不依赖硬件的层**，见 docs/测试说明/测试开发标准流程.md §1/§9）：
-#   L0   静态门禁 = pre-commit 全部钩子（等价本地 `pre-commit run --all-files`）
-#   L0.5 主机侧纯逻辑单测 = test/host/**（MSVC 离线编译，零硬件）
+# 覆盖范围（**只做不依赖硬件的层**，见 docs/测试说明/流程与规范/测试开发标准流程.md §1/§9）：
+#   静态门禁 static = pre-commit 全部钩子（等价本地 `pre-commit run --all-files`）
+#      + 手动阶段三根（覆盖率总闸 / 全量 cppcheck / test-cppcheck，`--hook-stage manual`；
+#        它们在 .pre-commit-config.yaml 里带 stages: [manual]，提交期不跑，由本 job 强制）
+#   主机侧纯逻辑单测 host-unit = test/host/**（MSVC 离线编译，零硬件）
 #
-#   ⛔ L1 板端套件（test/board/，需真机 + ST-LINK）/ L2 @test 闭环 / L3 人工目检
+#   ⛔ 板端测试套件（test/board/，需真机 + ST-LINK）/ 主机侧回归（/serial-boot-test 闭环）/ 人工目检
 #      **不上 CI** —— 需要开发板与烧录器，只能在本地跑。
 #
 # 明确不做的两件事（都是刻意为之）：
-#   1. `@build`（Keil UV4）—— 需本机 Keil 授权，runner 上不具备；且 L0 的 cppcheck +
+#   1. `/keil-build`（Keil UV4）—— 需本机 Keil 授权，runner 上不具备；且静态门禁的 cppcheck +
 #      代码规范已覆盖"编译前的静态问题"，真编译仍是开发者的本地红线（AGENTS.md）。
 #   2. `mem-numbers` / `mem-budget` 两根钩子 —— 事实源都是 `MDK-ARM/**/*.map`（Keil
-#      构建产物、已 gitignore），无 `@build` 即无 `.map`。故本 workflow 在**检测不到
+#      构建产物、已 gitignore），无 `/keil-build` 即无 `.map`。故本 workflow 在**检测不到
 #      .map 时自动跳过它们**（见下方 "决定跳过哪些钩子" 步骤），有 .map 的 runner 照常跑。
 #
 # 🔴 体积门禁：盲区已关闭为**强制路径**（2026-10-25 起；原先只做到"声明"）
 #   跳过钩子只解释了"runner 没有 Keil"，没解决**"没跑 = 通过"**：钩子在无 .map 时
-#   自适应 SKIP 并返回 0，于是 CI 全绿仍可能被读成"体积也守住了"。现由 L0 作业**最后
+#   自适应 SKIP 并返回 0，于是 CI 全绿仍可能被读成"体积也守住了"。现由静态门禁作业**最后
 #   一步** `python scripts/check_size_gate.py --ci` 在**不需要 Keil** 的前提下补两条判据：
 #     · 同码性：`scripts/size_attestation.json` 的源码指纹必须等于本次检出树的指纹，
 #       而该凭证只能由"新鲜 .map + 当时未超线"的真实链接测量写出（见 --stamp 三道前置）
@@ -59,7 +61,7 @@
 #     · 仓库 `.venv` 已 gitignore，runner 的全新工作区里**根本不存在**。
 #   唯一可用的机器级解释器（`C:\ProgramData\anaconda3\python.exe`）不再被探测，而文档
 #   要求的机器级 `DTU_PRECOMMIT_PYTHON` 从未设置（Machine 作用域一个 DTU_* 都没有）
-#   → run 14/15 的 L0 **全部死在"环境自检"，一个钩子都没跑**。cppcheck 同理：
+#   → run 14/15 的静态门禁 **全部死在"环境自检"，一个钩子都没跑**。cppcheck 同理：
 #   旧写法"不在 PATH 就把 C:\Program Files\Cppcheck 加进 PATH"的兜底也被删了。
 #   **故探测逻辑搬进 `scripts/ci_find_python.ps1`**（两个 job 共用、可离线跑、失败时
 #   打印全部候选），并恢复常见机器级安装位置兜底；`DTU_*` 仍是最高优先级、
@@ -86,7 +88,7 @@
 #   - 该 Gitea 实例已启用 Actions：`[actions] ENABLED = true`（site admin 配置）
 #   - 已注册一个 **Windows** runner（labels 含 `windows`），且装有：
 #       Python 3.x、cppcheck、pre-commit、MSVC（VS2019/2022 的 C++ 工具链 + Windows SDK）
-#   - 缺 MSVC 时 L0.5 步骤会**降级为提示并跳过**（不硬失败），但会打印醒目 WARNING
+#   - 缺 MSVC 时主机侧单测步骤会**降级为提示并跳过**（不硬失败），但会打印醒目 WARNING
 #
 # 🔧 runner 机器级环境变量（可选项覆盖；runner 以 SYSTEM 服务运行，用户级变量不可见）：
 #   DTU_PRECOMMIT_PYTHON / DTU_CPPCHECK / DTU_MSVC_CL —— 未设置时按 PATH / 标准 VS 布局自动发现。
@@ -119,10 +121,10 @@ concurrency:

 jobs:
  # ------------------------------------------------------------------
-  # L0：静态门禁（pre-commit 钩子全集）
+  # 静态门禁（pre-commit 钩子全集）
  # ------------------------------------------------------------------
-  l0-gates:
-    name: L0 静态门禁 (pre-commit)
+  static-gates:
+    name: 静态门禁 (pre-commit)
    runs-on: windows
    steps:
      - uses: actions/checkout@v4
@@ -141,7 +143,7 @@ jobs:
          #   * both jobs share ONE implementation,
          #   * it can be run (and its failure list inspected) offline,
          #   * the well-known machine-wide install locations stay probed.
-          # The previous inline 2-candidate probe is what killed every L0 run
+          # The previous inline 2-candidate probe is what killed every static-gate run
          # since 33a4aa4 -- see the file header.
          #
          # The script prints diagnostics with Write-Host and emits ONLY the
@@ -163,7 +165,7 @@ jobs:
          # The directory fallback is NOT cosmetic: the runner service runs as
          # SYSTEM, whose PATH has no Cppcheck entry (a USER-scope PATH entry is
          # invisible to it), and no machine-level DTU_CPPCHECK is set on a
-          # stock runner. Dropping this fallback in 33a4aa4 is what made L0 die
+          # stock runner. Dropping this fallback in 33a4aa4 is what made the static-gate job die
          # on cppcheck as well, right after the Python probe had been fixed.
          $found = $null
          $envCpp = $env:DTU_CPPCHECK
@@ -266,14 +268,14 @@ jobs:
              Out-File -FilePath $env:GITHUB_STEP_SUMMARY -Append -Encoding utf8
          } else {
            Write-Host "::warning::no .map found (no Keil build) -- SKIPPING mem-numbers and mem-budget, so absolute Flash/RAM numbers are NOT recomputed here."
-            Write-Host "::warning::that gap is no longer silent: the final step of this job runs scripts/check_size_gate.py --ci (forced path: attestation parity + 92% budget re-check). Locally: scripts/ci_local.py step L0c."
+            Write-Host "::warning::that gap is no longer silent: the final step of this job runs scripts/check_size_gate.py --ci (forced path: attestation parity + 92% budget re-check). Locally: scripts/ci_local.py size step."
            "value=mem-numbers,mem-budget" | Out-File -FilePath $env:GITHUB_OUTPUT -Append -Encoding ascii
            "sizegate=off" | Out-File -FilePath $env:GITHUB_OUTPUT -Append -Encoding ascii
            "> :warning: Volume gates (mem-numbers, mem-budget): **NOT RUN** -- no `.map` (no Keil build); compensated by the size-gate step below." |
              Out-File -FilePath $env:GITHUB_STEP_SUMMARY -Append -Encoding utf8
          }

-      - name: 运行 L0 门禁（--all-files）
+      - name: 运行静态门禁（--all-files）
        shell: powershell
        env:
          SKIP: ${{ steps.skip.outputs.value }}
@@ -287,7 +289,7 @@ jobs:
          # would ABORT the pipeline. Relax the preference around the pipeline and
          # restore it afterwards (same pattern as the env-check step above).
          New-Item -ItemType Directory -Force -Path 'ci-artifacts' | Out-Null
-          $log = 'ci-artifacts\l0-pre-commit.log'
+          $log = 'ci-artifacts\static-pre-commit.log'
          if ($env:SKIP) { Write-Host "SKIP=$env:SKIP" }
          $saved = $ErrorActionPreference
          $ErrorActionPreference = 'Continue'
@@ -301,17 +303,58 @@ jobs:
          $passed = @($lines | Select-String -Pattern 'Passed$').Count
          $failed = @($lines | Select-String -Pattern 'Failed$').Count
          $skipd  = @($lines | Select-String -Pattern 'Skipped$').Count
-          $summary = "L0: pre-commit hooks -- passed=$passed failed=$failed skipped=$skipd (log: $log)"
+          $summary = "static: pre-commit hooks -- passed=$passed failed=$failed skipped=$skipd (log: $log)"
          Write-Host "::notice::$summary"
-          Add-Content -Path $env:GITHUB_STEP_SUMMARY -Value "### L0 static gates" -Encoding utf8
+          Add-Content -Path $env:GITHUB_STEP_SUMMARY -Value "### 静态门禁 (static gates)" -Encoding utf8
          Add-Content -Path $env:GITHUB_STEP_SUMMARY -Value $summary -Encoding utf8

          if ($rc -ne 0) {
-            Write-Host "::error::L0 static gates failed (see output above and $log)"
+            Write-Host "::error::static gates failed (see output above and $log)"
            exit $rc
          }

-      - name: 归档 L0 日志（供下载/排障）
+      # ------------------------------------------------------------
+      # 手动阶段门禁（2026-10-28 用户裁定）：主机单测覆盖率总闸 + 全量 cppcheck。
+      # 这三根钩子在 .pre-commit-config.yaml 里带 `stages: [manual]`，**不在 git commit 时跑**
+      # （实测合计 ~165 s = 一次带代码提交耗时的三分之二）；提交期只跑快的那些，全量扫描由本 job 强制。
+      # 逐根调用而不是一条命令：`pre_commit run <a> <b>` 不支持多 id（实测 argparse 报
+      # "unrecognized arguments"）。
+      - name: 手动阶段门禁（覆盖率总闸 + 全量 cppcheck）
+        if: always()
+        shell: powershell
+        run: |
+          # Pure ASCII only (see file header). Same $ErrorActionPreference dance as the
+          # static-gate step above: the runner injects 'Stop', and '2>&1 |' turns a
+          # native command's stderr into an ErrorRecord that would abort the pipeline.
+          New-Item -ItemType Directory -Force -Path 'ci-artifacts' | Out-Null
+          $log = 'ci-artifacts/manual-stage.log'
+          if (Test-Path $log) { Remove-Item $log -Force }
+          $rc = 0
+          $hooks = @('cppcheck', 'test-cppcheck', 'test-coverage')
+          foreach ($h in $hooks) {
+            Write-Host "== manual hook: $h =="
+            $saved = $ErrorActionPreference
+            $ErrorActionPreference = 'Continue'
+            & $env:PYTHON -s -m pre_commit run --all-files --hook-stage manual $h 2>&1 |
+              Tee-Object -FilePath $log -Append
+            $one = $LASTEXITCODE
+            $ErrorActionPreference = $saved
+            Write-Host "manual hook $h rc=$one"
+            if ($one -ne 0) { $rc = $one }
+          }
+          $lines  = Get-Content $log -ErrorAction SilentlyContinue
+          $passed = @($lines | Select-String -Pattern 'Passed$').Count
+          $failed = @($lines | Select-String -Pattern 'Failed$').Count
+          $summary = "manual-stage: coverage + cppcheck -- passed=$passed failed=$failed (log: $log)"
+          Write-Host "::notice::$summary"
+          Add-Content -Path $env:GITHUB_STEP_SUMMARY -Value "### manual stage gates (coverage + cppcheck)" -Encoding utf8
+          Add-Content -Path $env:GITHUB_STEP_SUMMARY -Value $summary -Encoding utf8
+          if ($rc -ne 0) {
+            Write-Host "::error::manual-stage gates failed (see output above and $log)"
+            exit $rc
+          }
+
+      - name: 归档静态门禁日志（供下载/排障）
        if: always()
        shell: powershell
        run: |
@@ -319,17 +362,22 @@ jobs:
          # actions/upload-artifact (inner networks may not fetch outer actions);
          # instead we keep the log on the runner AND surface its path + tail in
          # the step summary, so the UI is self-sufficient for triage.
-          if (Test-Path 'ci-artifacts\l0-pre-commit.log') {
-            $size = (Get-Item 'ci-artifacts\l0-pre-commit.log').Length
-            Write-Host "archived: ci-artifacts/l0-pre-commit.log ($size bytes)"
+          if (Test-Path 'ci-artifacts\static-pre-commit.log') {
+            $size = (Get-Item 'ci-artifacts\static-pre-commit.log').Length
+            Write-Host "archived: ci-artifacts/static-pre-commit.log ($size bytes)"
            Add-Content -Path $env:GITHUB_STEP_SUMMARY -Value "" -Encoding utf8
-            Add-Content -Path $env:GITHUB_STEP_SUMMARY -Value "Archived log: ``ci-artifacts/l0-pre-commit.log`` ($size bytes on runner)" -Encoding utf8
+            Add-Content -Path $env:GITHUB_STEP_SUMMARY -Value "Archived log: ``ci-artifacts/static-pre-commit.log`` ($size bytes on runner)" -Encoding utf8
          }
-          Write-Host "::notice::L0 artifacts kept on runner at: ci-artifacts\l0-pre-commit.log"
+          if (Test-Path 'ci-artifacts\manual-stage.log') {
+            $msize = (Get-Item 'ci-artifacts\manual-stage.log').Length
+            Write-Host "archived: ci-artifacts/manual-stage.log ($msize bytes)"
+            Add-Content -Path $env:GITHUB_STEP_SUMMARY -Value "Archived log: ``ci-artifacts/manual-stage.log`` ($msize bytes on runner)" -Encoding utf8
+          }
+          Write-Host "::notice::static-gate artifacts kept on runner at: ci-artifacts\ (static-pre-commit.log, manual-stage.log)"

      # ------------------------------------------------------------
      # 强制体积门禁（2026-10-25）：不需要 Keil，也不需要 .map
-      # 放在 L0 作业**最后**且 if: always()——L0 失败时这条结论同样要看得到，
+      # 放在静态门禁作业**最后**且 if: always()——静态门禁失败时这条结论同样要看得到，
      # 而它自己失败会让整个作业变红（这正是"强制"的含义）。
      - name: 体积门禁（强制路径：同码凭证 + 92% 红线，无需 Keil）
        if: always()
@@ -393,10 +441,10 @@ jobs:
          }

  # ------------------------------------------------------------------
-  # L0.5：主机侧纯逻辑单测（零硬件；缺 MSVC 则跳过）
+  # 主机侧纯逻辑单测（零硬件；缺 MSVC 则跳过）
  # ------------------------------------------------------------------
-  l05-host-unit-tests:
-    name: L0.5 主机侧单测 (MSVC)
+  host-unit-tests:
+    name: 主机侧单测 (MSVC)
    runs-on: windows
    steps:
      - uses: actions/checkout@v4
@@ -454,7 +502,7 @@ jobs:
          if ($found) {
            "value=yes" | Out-File -FilePath $env:GITHUB_OUTPUT -Append -Encoding ascii
          } else {
-            Write-Host "::warning::runner has no MSVC (VS C++ toolchain) -- skipping L0.5. Install VS BuildTools and re-run."
+            Write-Host "::warning::runner has no MSVC (VS C++ toolchain) -- skipping host-side unit tests. Install VS BuildTools and re-run."
            "value=no" | Out-File -FilePath $env:GITHUB_OUTPUT -Append -Encoding ascii
          }

@@ -463,9 +511,9 @@ jobs:
        if: steps.msvc.outputs.value == 'yes'
        shell: powershell
        run: |
-          # Resolve a working Python with the SAME shared probe as L0 (no
+          # Resolve a working Python with the SAME shared probe as the static-gate job (no
          # -NeedPreCommit: these harnesses are stdlib-only). The old inline
-          # probe here had the same 2-candidate blind spot as L0 -- it only
+          # probe here had the same 2-candidate blind spot as the static-gate job -- it only
          # survived by luck, because the stdlib tests also run on the msys64
          # python that happens to be on SYSTEM's PATH.
          $py = & './scripts/ci_find_python.ps1' -WriteEnv
@@ -491,12 +539,12 @@ jobs:
          $sumPass = 0
          $sumTotal = 0
          # Relax preference around each `2>&1 | Tee-Object` pipeline (native stderr
-          # becomes ErrorRecord -> 'Stop' would abort). See L0 step for details.
+          # becomes ErrorRecord -> 'Stop' would abort). See the static-gate steps for details.
          $savedPref = $ErrorActionPreference
          foreach ($r in $runners) {
            $runnerCount++
            $name = $r.Directory.Name
-            $log = "ci-artifacts\l05-$name.log"
+            $log = "ci-artifacts\host-unit-$name.log"
            Write-Host "================================"
            Write-Host "run: $($r.FullName)"
            Write-Host "================================"
@@ -522,19 +570,19 @@ jobs:
            }
          }

-          $agg = "L0.5: $runnerCount runner(s), $sumPass/$sumTotal assertions passed, fail=$fail"
+          $agg = "host-unit: $runnerCount runner(s), $sumPass/$sumTotal assertions passed, fail=$fail"
          Write-Host "::notice::$agg"
-          Add-Content -Path $env:GITHUB_STEP_SUMMARY -Value "### L0.5 host-side unit tests" -Encoding utf8
+          Add-Content -Path $env:GITHUB_STEP_SUMMARY -Value "### 主机侧纯逻辑单测 (host-unit)" -Encoding utf8
          Add-Content -Path $env:GITHUB_STEP_SUMMARY -Value $agg -Encoding utf8
          "count=$runnerCount" | Out-File -FilePath $env:GITHUB_OUTPUT -Append -Encoding ascii
          "agg=$agg" | Out-File -FilePath $env:GITHUB_OUTPUT -Append -Encoding ascii
          exit $fail

-      - name: 归档 L0.5 日志（供下载/排障）
+      - name: 归档主机侧单测日志（供下载/排障）
        if: always()
        shell: powershell
        run: |
-          # Result visibility: same zero-dependency archival as L0.
+          # Result visibility: same zero-dependency archival as the static-gate job.
          if (Test-Path 'ci-artifacts') {
            $logs = Get-ChildItem -Path 'ci-artifacts' -Filter '*.log' -ErrorAction SilentlyContinue
            foreach ($f in $logs) {
@@ -546,15 +594,15 @@ jobs:
              Add-Content -Path $env:GITHUB_STEP_SUMMARY -Value "Archived logs on runner: $names" -Encoding utf8
            }
          } else {
-            Write-Host "no ci-artifacts directory (L0.5 skipped or failed early)"
+            Write-Host "no ci-artifacts directory (host-side unit tests skipped or failed early)"
          }

-      - name: L0.5 跳过说明
+      - name: 主机侧单测跳过说明
        if: steps.msvc.outputs.value == 'no'
        shell: powershell
        run: |
-          Write-Host "L0.5 skipped: runner has no MSVC."
+          Write-Host "host-side unit tests skipped: runner has no MSVC."
          Write-Host "Local equivalent: & '.venv\Scripts\python.exe' scripts/ci_local.py"
-          Add-Content -Path $env:GITHUB_STEP_SUMMARY -Value "### L0.5 host-side unit tests" -Encoding utf8
+          Add-Content -Path $env:GITHUB_STEP_SUMMARY -Value "### 主机侧纯逻辑单测 (host-unit)" -Encoding utf8
          Add-Content -Path $env:GITHUB_STEP_SUMMARY -Value ":warning: **NOT RUN** -- runner has no MSVC (VS C++ toolchain)." -Encoding utf8
          exit 0
@@ -139,7 +139,10 @@ docs/images/*.png
 .dsh/skills/serial-assistant/scripts/state/

 # agent 会话草稿（2026-10-14 定）：提交信息草稿 / 门禁输出 / 台架日志 / 一次性改名
-# 脚本 / 故障注入 patch —— 一律不入库。判据三条，命中任一就不值得留：
+# 脚本 / 故障注入 patch —— 一律不入库，**而且不落仓库根**（写进 ci-artifacts/ 或系统临时
+# 目录：2026-10-28 清理仓库根时那里堆着四个一次性计数改名脚本 + 一份提交信息草稿，全是
+# 未跟踪的 ?? —— 一次 git add -A 就进历史；仓库根只留工程配置与生成器输入两份 .txt）。
+# 判据三条，命中任一就不值得留：
 #   ① 能重跑的（门禁输出、日志）；② 内容已在 git 历史里的（已合并实现的过程 diff）；
 #   ③ 离开已丢弃的任务分支就跑不通的（依赖 NET_FAULT_INJECT 的注入产物）——
 #   这种提交进去是"看着有证据、实际不可复现"的假证据，**方法应沉淀成文档文字**
@@ -163,3 +166,18 @@ docs/images/*.png
 # 副产物，不兜住就会被某次 git add -A 带进历史。正解仍是继承完整环境跑这类工具。
 %SystemDrive%/
 ci-artifacts/
+
+# 提交信息草稿的兜底反选（上一条草稿块的「不入库」靠人自觉把文件写进 ci-artifacts/，
+# 但 `git commit -F` 那份文件随手落在仓库根就会以 ?? 出现，被某次 add -A 带走）：
+# 正文已经进了 commit message，落盘副本零信息量 → 根目录锚定挡掉这个命名。
+/commitmsg*.txt
+
+# DSH worktree 插件（dsh-task-worktree）把任务树建在**仓库内**这个命名空间下，与
+# @task skill 的仓外 _wt/ 两套并存。这一行必须**先由我们自己写好**：插件首次 create
+# 会往 .gitignore 追加分毫不相同的字面量（ensureIgnored 见同名规则即跳过），但那等于
+# 在会话中途改这份受控文件——门禁 diff 里冒出一行"不是我加的"最坑人。
+# 该目录同时登记进了 check_doc_links / gen_refgraph / check_layer_deps 的排除面
+# （整份仓库副本不能进全库扫描）；细节 → .dsh/skills/task-worktree/SKILL.md
+.dsh-worktrees/
+
+.obsidian/
@@ -76,6 +76,11 @@ repos:
    hooks:
      - id: cppcheck
        name: cppcheck
+        # ⚠ stages: [manual]（2026-10-28 用户裁定）：全库扫描实测 ~20 s，不压在提交期；
+        #   由**远端 CI** 强制（.gitea/workflows/ci.yml 的「手动阶段门禁（覆盖率总闸 + 全量 cppcheck）」步），
+        #   本地的等价入口 = scripts/ci_local.py（manual 段）或
+        #   python -m pre_commit run --all-files --hook-stage manual cppcheck
+        stages: [manual]
        entry: cppcheck
        # 注意：YAML 流序列中逗号是元素分隔符，含逗号/空格的参数必须加引号
        args: ['--enable=warning,performance,portability,style', '--error-exitcode=1',
@@ -115,6 +120,9 @@ repos:
      #     依据：docs/审查记录/测试与架构改进建议.md §3.4；实机测试实施指南.md §8.1
      - id: test-cppcheck
        name: cppcheck (test/, warning only)
+        # ⚠ stages: [manual]（2026-10-28，同 cppcheck）：实测 ~38 s；由远端 CI 与
+        #   scripts/ci_local.py 的 manual 段跑，提交期不跑。
+        stages: [manual]
        entry: cppcheck
        args: ['--enable=warning', '--error-exitcode=1',
               '--inline-suppr', '--std=c99', '--quiet',
@@ -179,6 +187,29 @@ repos:
            MDK-ARM/RTE/|
            docs/芯片手册/
          )
+      #    mermaid 图：围栏内确定性语法预检（第 52 条，2026-10-30 加，口径 51 → 52，提交期实跑 48 → 49）。
+      #    为什么要有：屏板链路设计说明.md §1 的 flowchart 里 `-.|"文字"|`（`-.` 直接跟管道，不是任何合法
+      #      箭头 token）让 mermaid 渲染 `Syntax error in text`——该图 2026-10-29 落库、期间 doc-links 等
+      #      全绿：文档门禁查链接与章节，**从不查围栏内图表语法**，这是它们的共同盲区。
+      #    v1 只查「错了必渲染失败」三条（不重造解析器）：R1 缺/错图类型头；R2 `-.` 后直接跟 `|`
+      #      （带文字点线合法形态只有 `-.->|t|` 与 `-. 文字 .->`，selftest 证明两种合法形态不误伤）；
+      #      R3 flowchart 的 subgraph 与独占行 `end` 计数配对、sequence 的块起点与 `end` 计数配对。
+      #    存量基线：接线当日 --all 实测 29 个自有文件 60 块围栏、0 命中 ⇒ **空基线零语料**（还清类
+      #      先例：id-check-new）；docs/芯片手册/ 是导入转录、围栏不受控，与 doc-links 同排除面不进语料。
+      #    自证：--selftest 五条（正例含三种合法点线 / 本坑形态必响 / 缺 end 必响 / 假头必响且
+      #      sequence alt-else-end 不误伤 / 基线吞得下且清空后同命中算新发）。
+      - id: mermaid-syntax
+        name: "mermaid 围栏语法预检（图类型头 / 非法点线管道 / 块配对）"
+        entry: python scripts/check_mermaid.py
+        language: system
+        files: \.md$
+        exclude: |
+          (?x)^(
+            \.opencode/node_modules/|
+            Lib/lvgl/|
+            MDK-ARM/RTE/|
+            docs/芯片手册/
+          )
      #    数值：README/AGENTS 任务表须与 Src/freertos.c 一致
      - id: task-table
        name: FreeRTOS 任务表一致性
@@ -233,7 +264,7 @@ repos:
      #    累计 / 100ms 节流 / tick 回绕）是纯逻辑，板端套件无法穷举边界；本钩子
      #    用 MSVC 离线编译真实源文件（#include 纳入）并用可观测桩驱动，秒级、零
      #    硬件、不占 MCU RAM。仅在被测文件或其平台层 / 测试变动时触发。
-      #    详见 docs/测试说明/看门狗单元测试说明.md
+      #    详见 docs/测试说明/单元测试/看门狗单元测试说明.md
      - id: watchdog-unit-test
        name: 看门狗判定状态机单测（主机侧）
        entry: python test/host/watchdog/run_unit_test.py
@@ -271,7 +302,7 @@ repos:
        files: ^(App/cfg/cfg_file\.(c|h)|App/cfg/cfg_file_store\.h|App/log/sys_log\.h|test/host/cfg_file/.*|test/host/common/unit_test_harness\.py)$
        pass_filenames: false

-      # 7d) 相量层（L2）主机侧单元测试（2026-10-10 加）
+      # 7d) 相量层（全周傅氏相量）主机侧单元测试（2026-10-10 加）
      #     背景：App/algo/ 为**纯算法**层（无寄存器、无 RTOS、无外设依赖），是本项目
      #     首个可完全离线验证的算法层。板端**无信号源**，无法注入已知幅值/相位/频率的
      #     标准波形，故"读数 = 设定值"这一核心判据在板上不可验；本钩子用 MSVC 离线编译
@@ -285,7 +316,7 @@ repos:
        files: ^(App/algo/(phasor|sample_ring)\.(c|h)|test/host/phasor/.*|test/host/common/unit_test_harness\.py)$
        pass_filenames: false

-      # 7e) ADC 输入层（L1）主机侧单元测试（2026-10-10 加）
+      # 7e) ADC 输入层（语义取数与有效性）主机侧单元测试（2026-10-10 加）
      #     背景：adc_input.c 的核心是"通道号 <-> Rank 顺序 <-> 语义"三者映射的正确性；
      #     板端无信号源，无法注入已知电压验证"读到的是哪只脚"（映射说明 §8）。本钩子用
      #     MSVC 离线编译真实源文件（#include 纳入）+ HAL/TPAFE 可注入桩：给每个 Rank
@@ -344,7 +375,7 @@ repos:
        files: ^(App/sync/time_sync\.(c|h)|App/util/task_watchdog\.h|test/host/time_sync/.*|test/host/common/unit_test_harness\.py)$
        pass_filenames: false

-      # 7h) ADC 采样有效性校验（L1-6）主机侧单元测试（2026-10-11 加）
+      # 7h) ADC 采样有效性校验主机侧单元测试（2026-10-11 加）
      #     背景：adc_health.c 是"静默/丢帧/序号倒退/错误计数增量"的判定层——这些
      #     故障在健康台架上**不可复现**（复现 = 拔芯片/改驱动），板端闭环只能证明
      #     "健康时不误报"，证不了"故障时必报"；100ms 门限、tick 回绕、事件边沿
@@ -358,7 +389,7 @@ repos:
        files: ^(App/algo/adc_health\.(c|h)|App/task/adc_task\.c|test/host/adc_health/.*|test/host/common/unit_test_harness\.py)$
        pass_filenames: false

-      # 7h2) 通道标定层（L1.5，「数据可信」卡 2/卡 4）主机侧单元测试（2026-10-25 加，道A）
+      # 7h2) 通道标定层（标定折算，「数据可信」标定折算与落盘整定）主机侧单元测试（2026-10-25 加，道A）
      #     背景：标定折算是"码值→工程量"的唯一插入点，Q16 系数/零点两段落盘 +
      #     合法带哨兵回退 + 两点标定公式——板端无标准源、坏文件注入路径在真机
      #     上难以复现，只有离线端能逐系数钉死。钩子用 MSVC 编译真实源文件
@@ -371,7 +402,7 @@ repos:
        language: system
        files: ^(App/algo/adc_cal\.(c|h)|App/algo/adc_health\.(c|h)|App/cfg/cfg_file\.(c|h)|App/task/adc_task\.c|test/host/adc_cal/.*|test/host/common/unit_test_harness\.py)$
        pass_filenames: false
-      # 7h3) 量纲回归（「数据可信」卡 7，道A）主机侧单元测试（2026-10-25 加）
+      # 7h3) 量纲回归（「数据可信」"不该动作时不动作"用例，道A）主机侧单元测试（2026-10-25 加）
      #     背景：台架曾长期缺"不该动作时不动作"的判据，码值/工程量错配曾以
      #     恒假动作的形态混过验收。本钩子用真实链（adc_cal→ring→phasor→
      #     prot_elm）+ 显式换算的合成波把七类元件的量纲钉死：折算点被旁路
@@ -383,11 +414,11 @@ repos:
        files: ^(App/algo/(adc_cal|prot_elm|prot_set|phasor|sample_ring|freq)\.(c|h)|App/task/(adc_task|protect_task)\.c|test/host/prot_dim/.*|test/host/common/unit_test_harness\.py)$
        pass_filenames: false

-      # 7h4) 遥测快照层（L2 发布侧，「数据可信」卡 8，道D）主机侧单元测试（2026-10-25 加）
-      #     背景：卡 8 的 DoD 一半是并发与结构类判据——双区切换无撕裂（撕裂窗
+      # 7h4) 遥测快照层（全周傅氏相量发布侧，「数据可信」遥测快照发布，道D）主机侧单元测试（2026-10-25 加）
+      #     背景：遥测快照发布项的 DoD 一半是并发与结构类判据——双区切换无撕裂（撕裂窗
      #     200 ms 量级，台架人工比对观测不到）、seq 只增、§4.5 布局与字段偏移
-      #     （卡 9/UI 直接按整体拷贝消费，破布局 = 破协议）、CLIPPED 品质汇总
-      #     （削顶位图要等卡 12 标定才真实出现）。主机侧以 #include 原样纳入
+      #     （104 与 UI 直接按整体拷贝消费，破布局 = 破协议）、CLIPPED 品质汇总
+      #     （削顶位图要等两点标定才真实出现）。主机侧以 #include 原样纳入
      #     meas/phasor/sample_ring 生产源，合成 9 通道帧序列一次性钉死；
      #     读数与注入源比对类判据仍归台架（实测采样类）。files 覆盖被测源、
      #     同链核（phasor/sample_ring）、编排方 adc_task 与 harness 本身。
@@ -398,7 +429,7 @@ repos:
        files: ^(App/algo/meas\.(c|h)|App/algo/(phasor|sample_ring)\.(c|h)|App/task/adc_task\.c|test/host/meas/.*|test/host/common/unit_test_harness\.py)$
        pass_filenames: false

-      # 7h5) 运行参数段（「数据可信」卡 10，道D）主机侧单元测试（2026-10-25 加）
+      # 7h5) 运行参数段（「数据可信」道D 交付项）主机侧单元测试（2026-10-25 加）
      #     死区把守突发上报的量、104 整定段是现场唯一远程写入口：注册契约、
      #     分档量程守卫、两段式、系数直通的合法带与生效值回显必须离线钉死。
      - id: run-par-unit-test
@@ -409,7 +440,7 @@ repos:
        pass_filenames: false


-      # 7i) 保护定值模型（P1 / L5-1 载体）主机侧单元测试（2026-10-11 加）
+      # 7i) 保护定值模型（定值校验和载体）主机侧单元测试（2026-10-11 加）
      #     定值是保护动作的"输入宪法"：范围校验、整表装载 all-or-nothing、
      #     校验和封存-自检-闭锁（参考 tagPRS dwTagSum/dwTagSumN 模式）必须在
      #     任何元件接线之前钉死——板端无法穷举越界定值注入，主机侧毫秒级全跑。
@@ -420,7 +451,7 @@ repos:
        files: ^(App/algo/prot_set\.(c|h)|test/host/prot_set/.*|test/host/common/unit_test_harness\.py)$
        pass_filenames: false

-      # 7j) 保护元件框架（L3 P1 子集）主机侧单元测试（2026-10-11 加）
+      # 7j) 保护元件框架（保护判据 P1 子集）主机侧单元测试（2026-10-11 加）
      #     判据核（滞回/定时限/欠量方向/闭锁联动/时基回绕）是纯逻辑，
      #     板端复现需要标准源 + 故障注入，主机侧用合成测量序列即可穷举
      #     1.2×/0.9× 验收口径（规划 §8）。
@@ -431,10 +462,10 @@ repos:
        files: ^(App/algo/prot_elm\.(c|h)|App/algo/prot_set\.(c|h)|App/algo/phasor\.(c|h)|App/algo/freq\.(c|h)|test/host/prot_elm/.*|test/host/common/unit_test_harness\.py)$
        pass_filenames: false

-      # 7j2) 频率测量层（L2.5，B8）主机侧单元测试（2026-10-12 加）
+      # 7j2) 频率测量层（测频与遥测快照，B8）主机侧单元测试（2026-10-12 加）
      #      自适应窗测频（K_eff 对齐负序泄漏纹波周期）的 J1~J6 判据
      #      （扫频/噪声/收敛/阶跃/浮空 valid=0/钳制恢复）是纯合成信号
-      #      可穷举的精度契约；板端无标准源照不出来（规划 §3.3 L3-5）。
+      #      可穷举的精度契约；板端无标准源照不出来（规划 §3.3 过频 / 低频）。
      - id: freq-unit-test
        name: 频率测量单测（主机侧）
        entry: python test/host/freq/run_unit_test.py
@@ -467,7 +498,7 @@ repos:

      # 7m) IEC 60870-5-104 被控站协议栈主机侧单元测试（2026-10-12 加，B4）
      #     APCI 重组/STARTDT/总召分片/COV/k-w-t1~t3/遥控定值两段式/C_CS/错误
-      #     应答——link 层 tick 注入 + pts 数据源 vtable 抽象就是为 L0.5 全离线
+      #     应答——link 层 tick 注入 + pts 数据源 vtable 抽象就是为主机侧纯逻辑单测全离线
      #     穷举设计（分层约束）；板端复现这些分支要真主站+真等待。
      #     触发面含数据源依赖（prot_set/prot_elm/phasor/sample_ring）——测试
      #     直接 #include 这些生产源，签名变了要立刻在这里暴露。
@@ -475,7 +506,7 @@ repos:
        name: IEC104 协议栈单测（主机侧）
        entry: python test/host/iec104/run_unit_test.py
        language: system
-        # 卡 10 起本 TU 链入真实 cfg_file/adc_cal/run_par（板端真源链），触发面同步扩
+        # 运行参数段落地起本 TU 链入真实 cfg_file/adc_cal/run_par（板端真源链），触发面同步扩
        files: ^(App/protocol/iec104/iec104_(asdu|pts|link)\.(c|h)|App/algo/(prot_set|prot_elm|phasor|sample_ring|adc_input|freq|meas|adc_cal|run_par)\.(c|h)|App/cfg/cfg_file(_store)?\.(c|h)|test/host/iec104/.*|test/host/common/unit_test_harness\.py)$
        pass_filenames: false

@@ -483,7 +514,7 @@ repos:
      #      64 B 定长记录（类型/seq/CP56Time2a/epoch/校验和）是磁盘上的
      #      字节级契约——编解码错了要 FTP 下载+解码才看得见；纯 codec
      #      零平台依赖（soe_store 胶水 SIM_EXEMPT），主机侧穷举往返/
-      #      截断/坏校验/IV 位/seq 连续性（规划 §3.4 L4）。
+      #      截断/坏校验/IV 位/seq 连续性（规划 §3.4 出口与记录）。
      - id: soe-unit-test
        name: SOE 动作记录编解码单测（主机侧）
        entry: python test/host/soe/run_unit_test.py
@@ -641,7 +672,7 @@ repos:
      #       疑似 MSBuild 节点争用；此后 3 次干净树连跑均绿。判据：单次失败先复跑一次再看，
      #       连续两次失败才当真（不许直接 --no-verify 绕过）。
      - id: ui-golden
-        name: UI 像素回归（菜单 8 状态 + 内容页 40 页 黄金参考）
+        name: UI 像素回归（菜单 8 状态 + 内容页 66 张 黄金参考）
        entry: python scripts/check_ui_golden.py
        language: system
        files: ^(Drivers/BSP/UI/|App/task/ui_task\.(c|h)$|simulator/(tests|sim|src)/|simulator/main\.c$|simulator/CMakeLists\.txt$|simulator/lv_conf\.h$|scripts/check_ui_golden\.py$|\.pre-commit-config\.yaml$)
@@ -651,7 +682,7 @@ repos:
      #      背景：大窗实测——靠预置键序盲走到深页时，9 帧里只有 3 帧真是它声称的态；
      #      KEY 的 ACK 是空应答、不携带状态，所以**画面是唯一事实源**。判据脚本
      #      scripts/board_ui_nav.py 据此改成闭环：每按一键重新认屏再决定下一个键。
-      #      本钩子跑它的**快检档** --selftest-quick：只核"认屏认得对"（18 张黄金参考 +
+      #      本钩子跑它的**快检档** --selftest-quick：只核"认屏认得对"（接线当时 18 张、现 66 张黄金参考 +
      #      真机留档帧，目录不在版本控制里、缺就整段跳过），秒级、无构建产物依赖。
      #      ⚠ 不挂完整 --selftest：第三段闭环需要 lvgl_sim.exe（构建产物，新工作树里没有）
      #        —— 正是同一天 mem-numbers 缺 .map 那课的形状；脚本对缺 exe 报 FAIL 并给出
@@ -667,32 +698,17 @@ repos:
        files: ^(scripts/board_ui_nav\.py$|simulator/tests/ref/.*\.bin$)
        pass_filenames: false

-      # 13) 编号门禁（2026-10-20 加，docs/编号规范.md §8 的 8 项校验）
-      #     背景：§1.2 用仓内证据列了 10 类编号事故（同字母多义 / 跨文档同号不同义 /
-      #     销项删行后残留悬空引用 / 自造前缀 / 会话临时号入册…），而 36 个钩子里
-      #     **只有 TC 一族**有机械检查（check_test_traceability.py，且未挂钩子、正则还漏 [示例]
-      #     `TC-AI-01A` [示例] 这类大写后缀）——E/N/S/B/C/D/A/U/O/gen/Trap 全部裸奔。本钩子把
-      #     规范 §8 的 8 项机械化：配置两份 `scripts/id_registry.json`（前缀 → 属主登记处
-      #     /形态/冻结/游标，逐项来自规范 §4 总表）+ `scripts/id_aliases.json`（旧号→新号，
-      #     照搬 section_aliases.json 的成功范式）。
-      #     判据要点：「定义」= 字面量出现在该族**属主登记处文档**里；于是 §5.5 的
-      #     「销项 = 删行 + 清全库引用」只做一半，校验 3 立刻报（销项号被重新取走那类撞号正是这条）。
-      #     盲区显式登记在 registry 的 `blind_spots` / `unmanaged_bare`：裸形同字母多义
-      #     （§1.2：P1 五义 / L1 四义 / UI 状态机号四义）与元器件位号同形（§4.4），机械全库判定
-      #     必然一边倒误报 → 裸形族只在属主文档内判越游标、文档外降告警；收口属 §9 阶段
-      #     1-② 的迁移批次。**不是「检查通过」，是记在案上的盲区。**
-      #     ⚠ 当前 warn-only（§8 上线节奏：先清 backlog → 清零后 entry 加 --strict 拦提交，
-      #       与 doc-links 章节校验同一条路径）。校验 8 的「可判定比例」跌破
-      #       id_registry.json 里的基线时**任何模式都失败**——那根线就是防回退的本体。
-      #     ⚠ pre-commit 4.x 已移除 `always: true` → files 必须覆盖所有能改编号的触发面
-      #       （任意 md/c/h/py/yaml/json/txt + 本配置文件）；扫描范围恒为全库
-      #       （悬空/孤儿/重复定义是跨文件判定，pass_filenames: false）。
-      - id: id-check
-        name: 编号门禁（docs/编号规范.md §8 八项校验）
-        entry: python scripts/check_ids.py --strict
-        language: system
-        files: \.(md|c|h|py|ya?ml|json|txt)$|^\.pre-commit-config\.yaml$
-        pass_filenames: false
+      # 13) 编号门禁的历史：2026-10-20 起曾有一版「全库语料审计」（规范 §8 的 8 项校验 +
+      #     99 族 registry + 别名表）。它 2026-10-28 退役——维护成本高过收益（近 80 笔提交
+      #     61 笔被编号体系牵连），脚本与语料整体移入 `scripts/archive/id_gate/`
+      #     （保留可复现性，**不再进提交门禁**）。退役路线与判据替换见规范 §8.5。
+
+      # 14) 编号门禁（2026-10-28 上线只查新增行那一道；2026-10-29 用户裁定**整体退役**，钩子已摘）
+      #     退役后编号形态没有机器面：判据回到 docs/编号规范.md §1 三句自问 + §4.1 族总表 + 评审。
+      #     脚本移入 scripts/archive/id_gate/check_ids_new.py（手工可跑，--self-test 保留），留档说明
+      #     → docs/门禁说明/id-check-new.md；手工普查与恢复机器面 → docs/编号规范.md §8.5。
+      #     ⚠ 计数口径：本条摘除使 YAML 解析条目 52 → **51**，须与 AGENTS.md 的「共 N 个钩子」、
+      #       docs/门禁说明/README.md §2 标题三数同源同批改（自查命令见该条；别在注释里写数钩子的字面量）。

      # 14) 分层方向门禁（2026-10-22 加，结构债的"防扩大"那一半）
      #     背景：AGENTS.md 与 项目架构总览.md 早就写着"六层单向依赖"，但**从来没有机械检查**
@@ -733,24 +749,29 @@ repos:
      #    为什么现在才挂：接线前本文件只有 16 个 *-unit-test 钩子，而仓库已有 28 套主机单测——
      #    P1 新增的 12 套不在任何提交钩子里。原先"再加一份全量插桩等于同一件事做两遍"
      #    这条理由到现在已经**反了**（现状是有一遍没做），所以必须挂；缺口此前如实登记在
-      #    docs/测试说明/主机单测覆盖率口径.md §8。
-      #    为什么挂这一根而不是补 12 个 per-module 钩子：本钩子跑**全部 28 套**，并且守 §5 的
+      #    docs/测试说明/单元测试/主机单测覆盖率口径.md §8。
+      #    为什么挂这一根而不是补 12 个 per-module 钩子：本钩子当时跑**全部 28 套**（现值 47 套，台账见
+      #    docs/门禁说明/host-unit-tests.md §6 第 4 条），并且守 §5 的
      #    回退台账（某套被删、或某文件的已覆盖行变少 → [REGRESS] 直接红）。这是 per-module
      #    钩子做不到的——删掉一套测试，它那根钩子只会因为"没有文件要检查"而静默跳过。
      #    ⚠ FAIL 语义（用户裁定 2026-10-24）：找不到 mscoverage 时脚本退出码 2 → 本钩子**失败**，
      #    不做 skip。理由：skip 等于造一根会静默失效的门禁（与 pre-commit 4.x 移除 always: true
      #    是同一类坑）；宁可在没装组件的机器上被挡一次、看清 [ENV] 那行提示，也不要一根假绿的闸。
      #    本机与 CI runner 同一台；实测两份 VS 安装都自带该 exe（口径 §7 第 8 条已按实测更正）。
-      #    口径 / 分母 / 基线 / 盲区详解都在 docs/测试说明/主机单测覆盖率口径.md，本处只留接线事实。
+      #    口径 / 分母 / 基线 / 盲区详解都在 docs/测试说明/单元测试/主机单测覆盖率口径.md，本处只留接线事实。
      #    触发面**含门禁自身**（.pre-commit-config.yaml）：不带自身就等于谁改坏这根闸的 files:
      #    模式，它就再也不跑且无人察觉（同 lv-conf-sync / bsp-err 的既有做法）。
-      #    ⚠ 读输出的坑（2026-10-24 连踩两次才定位）：本钩子没写 stages: → 默认属于**所有阶段**，
-      #    于是同一次提交的输出里它出现两次：pre-commit 阶段那一遍才可能实跑；commit-msg 阶段
-      #    那一遍的"文件"是提交信息文件，几乎必然 (no files to check)Skipped。**只看输出结尾会
-      #    把"实跑通过"读成"根本没跑"**——判它跑没跑要认**第一次**出现的那一行。
-      #    实跑证据：只改本文件的提交（e327636 / c4ca292）里 test-coverage 与 bsp-err 都是 Passed。
+      #    ⚠ stages: [manual]（2026-10-28 用户裁定）：本钩子跑光全部 47 套单测（41 套时实测 ~105 s，套件数
+      #    涨了耗时就涨，47 套这轮未重测耗时；
+      #    占一次带代码提交耗时的三分之二）→ 不压在提交期，由**远端 CI** 强制
+      #    （.gitea/workflows/ci.yml 的「手动阶段门禁（覆盖率总闸 + 全量 cppcheck）」步），本地等价入口 =
+      #    scripts/ci_local.py（manual 段）；手工复跑：
+      #      python -m pre_commit run --all-files --hook-stage manual test-coverage
+      #    另：此前它没写 stages: → 默认属于所有阶段，同一次提交输出里出现两次（commit-msg
+      #    阶段那遍几乎必然 Skipped，只看结尾会把实跑读成"没跑"）。固定 manual 阶段后不再有这一坑。
      - id: test-coverage
        name: 主机单测覆盖率（增量拦截：已覆盖行只增不减）
+        stages: [manual]
        entry: python scripts/check_test_coverage.py
        language: system
        files: ^(App/|Drivers/BSP/|test/host/|scripts/check_test_coverage\.py|scripts/test_coverage_baseline\.json|\.pre-commit-config\.yaml$)
@@ -777,7 +798,7 @@ repos:
      #       交实测解到 C:/Python314（无 fontTools）→ 字体链报 No module named fontTools = 假红。所以脚本
      #       自己按「显式 DTU_GEN_PYTHON > 当前解释器 > 仓库 .venv > PATH」解析并**逐个探针校验**（要真能
      #       import fontTools 才算数），整轮统一用同一个解释器；挑不出来打 [ENV]+候选表+修法、退出码 2 不
-      #       SKIP。不把 entry 写死成 .venv 路径：那是 ci_local 2026-10-11「候选收窄 → runner 上 L0 全灭」
+      #       SKIP。不把 entry 写死成 .venv 路径：那是 ci_local 2026-10-11「候选收窄 → runner 上静态门禁全灭」
      #       的同一条坑（详解 docs/门禁说明/generated-fresh.md §4）。
      #     ⚠ 字体链外部工具（node + 全局 lv_font_conv + 系统 simsun.ttc / seguisym.ttf）缺失时该项 SKIP 并
      #       打印 [SKIP]，--strict-env 才升 FAIL——与 test-coverage「缺 mscoverage 必 FAIL」刻意不同：
@@ -791,3 +812,54 @@ repos:
        language: system
        files: ^(tools/.+|Drivers/BSP/UI/.+|docs/images/.*\.svg|App/task/ui_task\.(c|h)|ui_menu_tree\.txt|ui_cn_chars\.txt|MDK-ARM/STM32F407-Demo\.uvprojx|simulator/CMakeLists\.txt|scripts/check_generated_fresh\.py|scripts/check_font_charset\.py|\.pre-commit-config\.yaml)$
        pass_filenames: false
+      #     ── 块注释嵌套（第 51 条，2026-10-27 加，task-29）─────────────────────────────
+      #     查什么：C/C++ 块注释体内再出现 /* —— ARMCC 诊断 9-D「nested comment is not allowed」。
+      #       本仓的诱因是「在注释里写作用域 / 通配路径」这种常态写法：Drivers/BSP/UI/** 里那个
+      #       /* 就是第二次注释的起点（C 的块注释不嵌套）。
+      #     为什么要闸：它**只在重编译那个 TU 时才暴露**，历史「0 警告」不代表安全；而且按包含者
+      #       数量刷屏——一份被广泛 include 的头里一处嵌套 = 每个包含者一行警告（实测一例扩散到 16
+      #       条，把整批真警告挤到看不见）。有了这根，提交时就报，不用等 /keil-build。
+      #     接线当日实证（冻结引用，别去翻构建日志——它每次 /keil-build 就被覆盖、也不入库）：当日 02:22
+      #       那次构建日志报过  ..\App\algo\run_par.c(267): warning:  #9-D: nested comment is not
+      #       allowed   ——那是别人**未提交**的在飞状态。原文抄在 docs/门禁说明/nested-comment.md §2.1；
+      #       已提交历史回放 281 份旧字节 0 命中 ⇒ 这类问题一直靠人工在编译后清，从没被机器拦过。
+      #     存量基线（只减不增，除这 2 处外**零豁免**）：全仓 --all 实扫 403 个 C/H，新发 0，存量
+      #       2 处 = test/host/common/ch395f_fake.h:7 与 fatfs_fake.h:9（注释里写 test/host/**，属
+      #       test/ 写域，等那侧改成语义短语；还清后删 BASELINE 行，--prune 打台账）。
+      #     自证：--selftest 四项（正例照得出 / 字符串与行注释不误报 / 基线吞得下 / 只减不增有牙），
+      #       另有 10 项形态电池（含「注释里写 UI/*」「块注释内行首再开 /*」等真形态）。
+      #     ⚠ 计数口径：本条使 YAML 解析条目 50 → **51**；配置里那条被注释掉的 clang-format 候选仍
+      #       在，所以**按文本 grep 声明行会得 52**（多算那条候选）——那不是口径。本行刻意不复现那个字面量，
+      #       否则注释自己也会被 grep 数进去（2026-10-27 实测踩过：写过一次，计数立刻虚高 1）。
+      #       口径与自查命令见 docs/门禁说明/README.md §2 首条。
+      - id: nested-comment
+        name: "块注释体内不得再出现 /*（ARMCC 9-D 嵌套注释）"
+        entry: python scripts/check_nested_comment.py
+        language: system
+        types: [c]
+
+      # ─── SKILL.md 体积与 reference/ 指针门禁（第 52 条，2026-10-29 加）─────────────────────
+      #   为什么要有：dsh-mnemon 插件对技能正文有 65536 字节的**写侧**硬上限（validateSkillContent），
+      #     但**加载侧不查**——超限的 SKILL.md 照常可读、照常进技能目录，只有一件事会坏：自进化每次
+      #     「生成草案」都在落盘那一步被拒，那一行永久卡在「生成中」、界面只剩转圈、连「忽略」都不出现
+      #     （Draft/Dismiss 只在 pending 渲染）。实测 2026-10-29 一天内两个技能各卡一次（第二个 72,601
+      #     字节），每次白烧一个 30 分钟的草案 Agent。**在加这根之前，仓库里没有任何一处会告诉你某个
+      #     技能已经废了**——文件能读、能改、能提交，全绿。
+      #   判据：> 65536 FAIL（与插件同数、同口径：utf-8 字节数不是字符数）；>= 49152（75%）WARN 不拦
+      #     （越线通常只隔一次草案采纳：实测 49821 → 62806）；正文里 (reference/xxx.md) 指向的文件不在
+      #     → FAIL；带 UTF-8 BOM → FAIL（插件按 utf-8 解析，BOM 会让 frontmatter 读歪）。
+      #   全树扫不只看变更文件：钩子拿到 filenames 只当触发用，判定始终扫整个 .dsh/skills/——因为改
+      #     reference/*.md 时 SKILL.md 没动，但它可能正是被那次外置撑过线/掏空的那一份。
+      #   为什么 entry 敢用裸 python：AGENTS.md「钩子 entry 的裸 python 不等于 .venv」那条教训针对的是
+      #     第三方依赖（fontTools）；本脚本纯标准库，任意 python3 均可（实测 .venv 3.12 与 PATH 上 3.14
+      #     都跑通），所以不需要脚本内再自解析解释器。
+      #   ⚠ 盲区：只管仓库内 .dsh/skills/；用户级 ~/.dsh/skills/ 不在仓库里，本钩子照不到（手工
+      #     `node "$HOME/.dsh/scripts/mnemon-skill-ledger-doctor.mjs" --root .` 或本脚本 --root 都只报，
+      #     要拦得另配 shell 钩子）。只认 markdown 链接形态的指针，纯文本里写的路径不算。
+      #   自证：--selftest 五形态（干净 0 / 75% 线 0 带 WARN / 超上限 1 / 悬空指针+BOM 1 / 根不存在 2）。
+      #   详解与限制 → docs/门禁说明/skill-size.md。
+      - id: skill-size
+        name: "SKILL.md 不超插件写侧上限 65536 且 reference/ 指针不悬空"
+        entry: python scripts/check_skill_size.py
+        language: system
+        files: ^\.dsh/skills/
@@ -1,5 +1,5 @@
 {
-  "portName": "COM6",
+  "portName": "COM3",
  "baudRate": 115200,

  "flash_cmd": ".venv\\Scripts\\python.exe .dsh\\skills\\stlink-flash\\scripts\\stlink_flash.py flash",
@@ -16,7 +16,7 @@ FreeRTOS/CMSIS-RTOS API**（见 `AGENTS.md`「平台约束」）。
 | `app/` | **应用入口与全局**：`app_main.c/h`（初始化入口）、`app_cfg.h`（裁剪决策占位说明，当前无宏）、`sys_events.h`（就绪事件） | [`app/README.md`](app/README.md) |
 | `cfg/` | **配置引擎**：`/config.ini` 解析 + 原子持久化（旧二进制档已废弃，2026-10-10） | [`cfg/README.md`](cfg/README.md) |
 | `sync/` | **时间同步任务**：`time_sync.c/h` | [`sync/README.md`](sync/README.md) |
-| `algo/` | **采集与算法层（L1/L2/L3）**：语义取数 + 有效性判定 + 采样环/相量/测频 + 定值模型 + 保护元件框架 | [`algo/README.md`](algo/README.md)（索引）；设计 → `docs/算法/采集与算法层设计说明.md` |
+| `algo/` | **采集与算法层**：语义取数 + 有效性判定 + 采样环/相量/测频 + 定值模型 + 保护元件框架 | [`algo/README.md`](algo/README.md)（索引）；设计 → `docs/算法/采集与算法层设计说明.md` |
 | `log/` | **日志子系统**：syslog（NAND）+ 控制台单写者日志 | [`log/README.md`](log/README.md) |
 | `task/` | **FreeRTOS 任务实现**（6 个任务） | [`task/README.md`](task/README.md) |
 | `util/` | **通用工具**：CRC / 环形缓冲 / 墙钟时间 | [`util/README.md`](util/README.md) |
@@ -1,4 +1,4 @@
-# App/algo/ — 采集与算法层（L1 / L2 / L3）
+# App/algo/ — 采集与算法层（语义取数与有效性 / 全周傅氏相量 / 保护判据）

 > 本目录的**索引**：文件清单、依赖、逐文件的"改代码必须知道"、构建与测试入口、新增模块动作。
 > **详细设计——机制、契约、判据、为什么这样设计 → `docs/算法/采集与算法层设计说明.md`**（本文不复制其内容）。
@@ -9,21 +9,25 @@

 | 文件 | 层 | 作用（一句话） | 主要对外入口 | 覆盖规划项 |
 |---|---|---|---|---|
-| `adc_input.h` / `.c` | L1 | 统一语义取数：两片转换器的码值按语义（`UA…IN` / 温度）暴露，并消费 STM32 ADC1 的 DMA 乒乓缓冲 | `adc_input_init()` `adc_input_poll()` `adc_input_raw()` | L1-2 / L1-3 / L1-4 |
-| `adc_health.h` / `.c` | L1 | 采样有效性判定：吃计数快照，产出静默 / 丢帧 / 单调性 / 错误增量故障位（判定与告警编排分离）；L5-2 残余的码值贴轨观察器同层 | `adc_health_check()` `adc_health_flags()` `adc_health_rail_watch()` | L1-6 / L5-2（残余） |
-| `adc_cal.h` / `.c` | L1.5 | 通道标定折算（「数据可信」卡 2/卡 4）：工程量 =(code+b)×k，Q16 系数/零点两段落盘 + 三态 flags + 合法带哨兵 + 两点公式 | `adc_cal_apply()` `adc_cal_flags()` `adc_cal_set()` | L1-5（M4 半边） |
-| `meas.h` / `.c` | L2 发布 | 遥测快照（「数据可信」卡 8，M5 地基）：200 ms 基波有效值 + 品质快照，双区无锁读，全仓唯一发布者 = adcTask | `meas_tick()` `meas_get()` `meas_seq()` | M5（卡 9/11 与 UI 是读者） |
-| `sample_ring.h` / `.c` | L2 输入 | 按语义通道存最近 2 周波（40 点），供相量层"以当前时刻为终止"取窗 | `sample_ring_push_frame()` `sample_ring_window()` | L2 输入（为 L2-6 供数） |
-| `phasor.h` / `.c` | L2 | 全周傅氏：一周波 20 点 DFT → 基波 / 谐波相量（有效值口径），双区原子切换供无锁读 | `phasor_run()` `phasor_get()` `phasor_calc()` | L2-1 / L2-2 / L2-3 / L2-6 / L2-7 |
-| `freq.h` / `.c` | L2 派生量 | 频率测量：相邻两拍基波相量共轭乘积取角 + 自适应窗滑动平均 + 假值钳制 + 幅值门（UA→IA 源回退） | `freq_run()` `freq_get()` `freq_valid()` | L3-5 测量侧（测频范围 → `docs/算法/继电保护功能复现规划.md` §4.2） |
-| `prot_set.h` / `.c` | L3 输入 | 保护定值模型：Q10 定点 RAM 表 + 范围校验 + 校验和封存 / 自检 / 闭锁 + 持久化 blob 纯逻辑 | `prot_set_load_raw()` `prot_set_get_f()` `prot_set_selfcheck()` | L5-1 载体 |
-| `prot_elm.h` / `.c` | L3 | 保护元件框架：通用"越限 + 返回系数滞回 + 定时限"核 + 数据驱动实例表（过流三段 / 过负荷 / 过压 / 欠压 / 零序过压 / 过频 / 低频） | `prot_elm_run()` `prot_elm_eval()` `prot_elm_active_mask()` | L3-1 / L3-3 / L3-4 / L3-5 / L3-6（软件侧） |
+| `adc_input.h` / `.c` | 语义取数与有效性 | 统一语义取数：两片转换器的码值按语义（`UA…IN` / 温度）暴露，并消费 STM32 ADC1 的 DMA 乒乓缓冲 | `adc_input_init()` `adc_input_poll()` `adc_input_raw()` | TPAFE 快照消费 / STM32 ADC1 启动与扫描 / 通道语义映射 |
+| `adc_health.h` / `.c` | 语义取数与有效性 | 采样有效性判定：吃计数快照，产出静默 / 丢帧 / 单调性 / 错误增量故障位（判定与告警编排分离）；「采样通道自检」残余的码值贴轨观察器同层 | `adc_health_check()` `adc_health_flags()` `adc_health_rail_watch()` | 「采样有效性校验」/「采样通道自检」（残余） |
+| `adc_cal.h` / `.c` | 标定折算 | 通道标定折算（「数据可信」标定折算与落盘整定）：工程量 =(code+b)×k，Q16 系数/零点两段落盘 + 三态 flags + 合法带哨兵 + 两点公式 | `adc_cal_apply()` `adc_cal_flags()` `adc_cal_set()` | 「通道标定（一次系数 + 零漂）」（M4 半边） |
+| `meas.h` / `.c` | 全周傅氏相量发布 | 遥测快照（「数据可信」遥测快照发布，M5 地基）：200 ms 基波有效值 + 品质快照，双区无锁读，全仓唯一发布者 = adcTask | `meas_tick()` `meas_get()` `meas_seq()` | M5（104 改读快照与频率点绑定、UI 是读者） |
+| `sample_ring.h` / `.c` | 全周傅氏相量输入 | 按语义通道存最近 2 周波（40 点），供相量层"以当前时刻为终止"取窗 | `sample_ring_push_frame()` `sample_ring_window()` | 全周傅氏相量输入（为「每 1 ms 滑动窗刷新」供数） |
+| `phasor.h` / `.c` | 全周傅氏相量 | 全周傅氏：一周波 20 点 DFT → 基波 / 谐波相量（有效值口径），双区原子切换供无锁读 | `phasor_run()` `phasor_get()` `phasor_calc()` | 全周傅氏系数表 / 基波相量实例 / 相量有效值输出 / 每 1 ms 滑动窗刷新 / 双区指针原子交换 |
+| `freq.h` / `.c` | 全周傅氏相量的派生量 | 频率测量：相邻两拍基波相量共轭乘积取角 + 自适应窗滑动平均 + 假值钳制 + 幅值门（UA→IA 源回退） | `freq_run()` `freq_get()` `freq_valid()` | 「过频 / 低频」测量侧（测频范围 → `docs/算法/继电保护功能复现规划.md` §4.2） |
+| `prot_set.h` / `.c` | 保护判据输入 | 保护定值模型：Q10 定点 RAM 表 + 范围校验 + 校验和封存 / 自检 / 闭锁 + 持久化 blob 纯逻辑 | `prot_set_load_raw()` `prot_set_get_f()` `prot_set_selfcheck()` | 「定值校验和」载体 |
+| `prot_elm.h` / `.c` | 保护判据 | 保护元件框架：通用"越限 + 返回系数滞回 + 定时限"核 + 数据驱动实例表（过流三段 / 过负荷 / 过压 / 欠压 / 零序过压 / 过频 / 低频） | `prot_elm_run()` `prot_elm_eval()` `prot_elm_active_mask()` | 「三段式相间过流」/「过负荷」/「过压 / 欠压」/「过频 / 低频」/「零序过压」（软件侧） |
+| `wave_ring.h` / `.c` | 故障录波数据面 | 录波环与冻结状态机：int16 × 320 点 × 8 路按通道分列，触发即冻结写指针、后触发计满 160 点封段、落盘回执才解冻、冷却期只加溢出计数 | `wave_ring_push()` `wave_ring_tick()` `wave_ring_request()` `wave_ring_sealed()` `wave_ring_read_ch()` | 「故障录波」数据面（环 + 触发冻结语义） |
+| `wave_store.h` / `.c` | 故障录波段格式 | 段文件字节层的编解码与分次搬运游标：段头 + 通道表 + 两处 CRC-16/MODBUS + 段名轮转与反解 + 整段自检；不碰文件系统 | `wave_store_crc()` `wave_store_head_build()` `wave_store_head_parse()` `wave_store_seg_check()` `wave_store_pack_next()` `wave_store_seg_path()` | 「故障录波」段格式（布局 + 自检） |

 依赖（自下而上、无环）：`adc_input.h`（纯枚举 + 声明）← `adc_cal`（另依赖 `cfg_file.h` 接口，
 纯头文件级）← `sample_ring` ← `phasor` ← `freq`；`meas` ← `sample_ring` + `phasor`
 （仅 `phasor_calc` 纯核；频率/品质由调用方注入，**不链** `freq`/`adc_cal`）；
 `prot_set` **独立**；`prot_elm` ← `prot_set` + `phasor` + `freq`。
-`adc_health` 只吃调用方喂进来的计数 / 码值，不反向依赖 L1 实现（L5-2 贴轨门限由调用方
+`wave_store` **独立**（只用 `stdint.h` 与 `stddef.h`，编码与解码共用同一个字段校验函数）；`wave_ring` ← `wave_store`（只取段头类型与返回码；**不链** `adc_cal`——封存瞬间的系数由
+adcTask 现取现填后交棒，本层不复制第二个事实源）。两份录波文件同样零平台依赖、不碰文件系统。
+`adc_health` 只吃调用方喂进来的计数 / 码值，不反向依赖 语义取数与有效性实现（「采样通道自检」贴轨门限由调用方
 从 `adc_cal_rail_ths()` 取，本层仍零算法依赖）。

 **除 `adc_input.c` 外全部零平台依赖**（只用 `stdint.h` / `math.h` / `stddef.h` 与本目录头）
@@ -32,57 +36,62 @@

 ## 2. 一拍的数据流（一眼版）

-`adc_input_poll()` → `adc_input_raw()` ×9 → `adc_cal_apply()` ×9（L1.5 折算，现口径 =
-ADC 引脚电压 V）+ `adc_health_rail_watch()` ×9（L5-2，码值域）→ `sample_ring_push_frame()`
-→ `phasor_run()` → `freq_run()` → 消费者（`adcTask` 心跳与 L1 健康判定；`protectTask` 每 20 ms 取相量 / 频率跑
-`prot_elm_run()`；**每 200 ms** `meas_tick()` 发布遥测快照供 iec104Task / uiTask 读，卡 8）。节拍 = TIM3 1 kHz 更新事件，两片转换器同源触发。
+`adc_input_poll()` → `adc_input_raw()` ×9 → `adc_cal_apply()` ×9（标定折算折算，现口径 =
+ADC 引脚电压 V）+ `adc_health_rail_watch()` ×9（「采样通道自检」，码值域）→ `sample_ring_push_frame()`
+→ `phasor_run()` → `freq_run()` → 消费者（`adcTask` 心跳与 语义取数与有效性健康判定；`protectTask` 每 20 ms 取相量 / 频率跑
+`prot_elm_run()`；**每 200 ms** `meas_tick()` 发布遥测快照供 iec104Task / uiTask 读，即「数据可信」遥测快照发布）。节拍 = TIM3 1 kHz 更新事件，两片转换器同源触发。
 完整数据流图与初始化落点 → `docs/算法/采集与算法层设计说明.md` §2。

+录波支路（与上面这条相量主线**并行**、同拍只多走两步，互不阻塞）：`adc_input_raw()` 取 8 路 →
+`wave_ring_push()` → `wave_ring_tick()`（触发即冻结写指针，后触发计满 160 点封段）→ defaultTask
+只见 `wave_ring_sealed()` 与已封存区读口 → 游标分次搬运落盘 → `wave_ring_write_done()` 才解冻。
+→ docs/子系统设计/故障录波设计说明.md §4.2 与 §5.1。
+
 ## 3. 逐文件要点（只留"改代码时必须知道"的；机制与理由见设计文档）

 > **改本目录前先记五条红线**：① 取数只经 `adc_input_raw()`，不写死下标；② **禁止跨转换器**做
-> 相位 / 功率 / 矢量运算（双转换器无共同采样触发）；③ 帧值已是 L1.5 工程量，但 **未标定（`adc_cal_flags()` 无
+> 相位 / 功率 / 矢量运算（双转换器无共同采样触发）；③ 帧值已是 标定折算工程量，但 **未标定（`adc_cal_flags()` 无
 > VALID）时单位只是 ADC 引脚电压**，不是端子二次值——下游消费精度判据见「数据可信」§4.2 三态
 > 表；④ 工程量 → 帧的唯一折算点是 `adc_cal_apply()`，禁止旁路再乘系数；⑤ 本层不建任务、
 > 不等事件、不写日志（`adc_cal` 的 `[ERR]` 哨兵留痕是唯一例外，且每通道每开机一次），
 > `*_init()` 才可在内核前调。
 > 全文 → `docs/算法/采集与算法层设计说明.md` §10。

-### 3.1 `adc_input.c` / `adc_input.h` — L1 语义取数
+### 3.1 `adc_input.c` / `adc_input.h` — 语义取数与有效性语义取数
 - 语义映射表 `k_adc_map[]` 的**内容**唯一权威是 `docs/硬件平台/ADC通道映射说明.md`；V0.2 改版只改表内容，API 不动。
 - `adc_input_poll()` **仅任务上下文**（TPAFE 快照是临界区）；STM32 侧固定滞后 1 拍。
 - 四类 STM32 计数（`adc1_seq` / `adc1_gap` / `adc1_err` / `adc1_hw`）成因不同，**勿混读**。
 - 本目录**唯一**允许出现 HAL 调用的文件。→ `docs/算法/采集与算法层设计说明.md` §3。

-### 3.2 `sample_ring.c` / `.h` — L2 输入采样环
+### 3.2 `sample_ring.c` / `.h` — 全周傅氏相量输入采样环
 - 整帧写入后才推进写指针 → 取到的窗永远落在整帧边界。
 - 本拍取数失败 → **整拍跳过入环**（`adc_task.c` 的 `skip`），**绝不补 0 点**。
 - 不做跨通道运算、不做丢帧判定（只出 `frames()` 计数）。→ `docs/算法/采集与算法层设计说明.md` §5。

-### 3.3 `phasor.c` / `.h` — L2 相量计算
+### 3.3 `phasor.c` / `.h` — 全周傅氏相量计算
 - 系数表预乘 √2/N → `fAmSQ` **直接是有效值**（口径 `docs/算法/傅氏算法详解.md` §2.3）。
 - 实例表 `k_inst[]` 数据驱动：**新增实例只在表尾加一行**。
 - 任一实例不足一周波 → **本拍整体不产出**（不切使用区）；每拍 20 点**全部重算**（不做增量递推）。
 - → `docs/算法/采集与算法层设计说明.md` §6。

-### 3.4 `adc_health.c` / `.h` — L1 有效性判定
+### 3.4 `adc_health.c` / `.h` — 语义取数与有效性判定
 - 三类位**严格分开**：电平（可自愈）/ 锁存（必留痕）/ 边沿事件（仅当拍）；**静默 ≠ 丢帧**。
 - **gap 不告警**（消费者超拍是已知现象）；告警编排在 `adc_task.c`，不在本层。
 - 首拍 `check()` 只建基线。→ `docs/算法/采集与算法层设计说明.md` §4。

-### 3.5 `prot_set.c` / `.h` — 保护定值模型（L5-1 载体）
+### 3.5 `prot_set.c` / `.h` — 保护定值模型（「定值校验和」载体）
 - 装载 **all-or-nothing**：任一项越界整表不装载，越界项由 `prot_set_bad_mask()` 指认。
 - 批量 `prot_set_set()` 后**必须** `prot_set_seal()`；单项原子写用 `prot_set_set_sealed()`。
 - 定值项 / 实例**只许尾部追加**（枚举序 = 数组序 = 校验和覆盖序）。
 - blob **换代（返回 2）≠ 损坏（返回负）**：前者打 INFO、不记自检。→ `docs/算法/采集与算法层设计说明.md` §8、§12.3。

-### 3.6 `prot_elm.c` / `.h` — L3 保护元件框架
+### 3.6 `prot_elm.c` / `.h` — 保护判据元件框架
 - 数据缺失两种处理**刻意不同**：相量类任一未就绪 → 整拍跳过；频率类无有效读数 → 按方向填"必不启动"值，**不整拍跳过**。
 - `prot_set_locked()` 或投退 = 0 → 元件整体复位不判据；跨上下文复归走 `prot_elm_request_reset()`。
 - 零序过流（IN 走 STM32）**故意不在实例表**；OF / UF 无独立 104 遥信点，只经 YX15 总聚合可见。
 - `prot_elm_init()` 须在 `phasor_init()` 之后。→ `docs/算法/采集与算法层设计说明.md` §9。

-### 3.7 `freq.c` / `.h` — 频率测量（L3-5 的测量输入）
+### 3.7 `freq.c` / `.h` — 频率测量（「过频 / 低频」的测量输入）
 - `freq_run()` **仅 adcTask 上下文**，须在 `phasor_run()` 之后同拍调；保护口径 =
  `freq_get() == 0 && freq_valid() == 1`。
 - 精度靠**自适应窗长**（窗长 = 泄漏纹波周期的整数倍）；定长平均压不到 0.02 Hz，
@@ -90,48 +99,104 @@ ADC 引脚电压 V）+ `adc_health_rail_watch()` ×9（L5-2，码值域）→ `s
 - 源切换即废相位基准重建（UA / IA 无共同相位基准，即双转换器无共同采样触发）。
 - 判据 **J1~J6** 与实测口径 → `docs/算法/采集与算法层设计说明.md` §7.2（与 `test/host/freq/freq_test.c` 文件头同源）。

-### 3.8 `adc_cal.c` / `.h` — L1.5 通道标定折算（「数据可信」卡 2 / 卡 4）
+### 3.8 `adc_cal.c` / `.h` — 标定折算通道标定折算（「数据可信」标定折算与落盘整定）
 - 折算模型：工程量 = (code + b) × k；**k 落盘用 int32 Q16（µV/码 × 65536）**、b 用
  int32 码值（负零点靠 `CFG_VAL_INT`）——单位与定点格式的选型依据见
  `docs/任务规划/数据可信.md` §4.1，勿改回 V/码 直存（Q16 只剩 20 个刻度）。
- **ROM 默认 = 卡 1 定死的引脚侧 LSB**（TPAFE 152.59 / STM32 805.66 µV/码，
+- **ROM 默认 = 量程口径冻结定死的引脚侧 LSB**（TPAFE 152.59 / STM32 805.66 µV/码，
  `docs/硬件平台/ADC通道映射说明.md` §7.1）；表下标 = 语义枚举（UA0…IN7），
  V0.2 改版与本目录 `adc_input` 映射表同步改。
- 三态可用性 `adc_cal_flags()`：VALID（已按变比标定，二次值成立——卡 0b/12 前恒 0）
+- 三态可用性 `adc_cal_flags()`：VALID（已按变比标定，二次值成立——端子变比确认与两点标定前恒 0）
  / CLIPPED（运行期按来源派生，V0.2 后自动清零）。**消费者判「能不能信」只许查它**，
  `adc_cal_apply()` 不返回可用性（「数据可信」§8 风险表）。
 - 合法带哨兵：k ∉ ROM×[0.5,2.0] 或 |b| > 8192 → 折算回退 ROM + 每通道每开机一条
  `[ERR]` + VALID 被压制（**即便文件位图说已标定**）；这层兜底同时挡坏文件与坏标定。
 - `adc_cal_set()` / `adc_cal_two_point()`：整定与两点公式的算术核已齐备（单测还原合成
-  k/b）；**台架两点标定（卡 12）待实测**，本层不含注入。
+  k/b）；**台架两点标定待实测**，本层不含注入。
 - cfg 两段 `[adc_cal]` / `[adc_cal_ofs]` **不挂回调**（RAM 副本即生效值，引擎 load/poll
  原地改写，逐点现读）；注册在 `app_main_init()` 内核前完成，必须先于 `cfg_file_load`。

-### 3.9 `meas.c` / `.h` — 遥测快照发布（L2 发布侧，「数据可信」卡 8）
+### 3.9 `meas.c` / `.h` — 遥测快照发布（全周傅氏相量发布侧，「数据可信」波次）
 - **唯一发布者 = adcTask**：`phasor_run()`/`freq_run()` 同拍、200 ms **tick 经过**分频
  调 `meas_tick()`（非拍计数——idle/skip 拍拉长名义节拍）。docs/任务规划/数据可信.md §8
  风险表"快照双写"行 = 评审判据：全仓 `meas_tick` 调用点数须为 1；iec104Task /
  uiTask 只读。
- 值口径（批 2 卡 8 A-lite 裁决）：**基波有效值瞬时透传**，与 phasor 使用区
+- 值口径（第二轮「遥测快照发布」的 A-lite 裁决）：**基波有效值瞬时透传**，与 phasor 使用区
  **同拍同核逐位相等**（单测钉死）；**不做** 4 点平均 / 谐波方和根——按
  docs/任务规划/数据可信.md §4.5"上送节拍非平均窗，再平均引入滞后"；谐波 k-bin 轨
-  （docs/算法/继电保护功能复现规划.md L2-8）扩展只许结构尾部追加，
+ （docs/算法/继电保护功能复现规划.md 「遥测谐波轨（可选）」）扩展只许结构尾部追加，
  docs/任务规划/数据可信.md §4.5 字段序 = 协议（布局由单测按偏移钉死，72 B × 双区）。
- 并发 = phasor 双区 + 单字节索引翻转（L2-7 同型，无锁）；seq 只增供消费者判换帧。
+- 并发 = phasor 双区 + 单字节索引翻转（「双区指针原子交换」同型，无锁）；seq 只增供消费者判换帧。
 - 品质注入：削顶位图唯一源 = `adc_cal_flags()`（口径 docs/任务规划/数据可信.md §4.2
  三态表；由 adc_task 编排注入，本层不链 `adc_cal`）；TEMP = 最新一拍原始值透传 +
  `NT`（「数据可信」决策 5）；`MEAS_QDS_*` 低字节与 104 QDS 线上字节同值
  （本层**不** include 协议层头——分层方向）。
- 104 死区迁移 / 频率点绑定 = 卡 9/卡 11（道D 后续分支）；读数与注入源比对 = **待台架实测**。
+- 104 死区迁移 / 频率点绑定 = 104 改读快照那一波（道D 后续分支）；读数与注入源比对 = **待台架实测**。
+
+### 3.10 `wave_ring.c` / `wave_ring.h` — 录波环与冻结状态机（「故障录波」数据面）
+- **形态三条钉死**（动它之前读 docs/子系统设计/故障录波设计说明.md §6.2 与 §7）：只存 `int16`
+  原始码值（不做折算、不许 `float`）、**按通道分列**（不按帧交错——回放与搬运都是整列取）、
+  `ch_count` 固定 8（TEMP 本波不录：未折算的非线性量进录波只多占字节不增信息）。环本体 5120 B，
+  本层全部可写静态 5298 B，落 SRAM1（scatter 的 `RW_IRAM1` 收 `.ANY (+RW +ZI)`，代码里**没有**
+  任何 section 属性；CCM 只放 FreeRTOS 堆，那 5 KB 既塞不进也不该塞）。
+- **冻结 ≠ 停采集**：触发冻住的是覆盖窗口（写指针停走），丢的只是录波样本，`drop_cnt` 的单位是
+  「点」（一拍 8 路 = 8 点）；`sample_ring` / 相量 / 保护在同拍照常跑，本层不碰它们。
+- **点序**：触发那一拍的样本落在段内点 159（预触发窗最后一点），点 160 起是触发后第一拍，两半
+  各 160 点、不重叠；回放页横轴与 PC 脚本都按这条对齐（设计说明未钉死 ±1，本层按不重叠实现）。
+- **封存握手（顺序不许换，单测逐拍钉死）**：`wave_ring_tick()` 计满那一拍返回
+  `WAVE_RING_EVT_SEALED` → adcTask 才去取标定事实并 `wave_ring_latch_meta()` → `wave_ring_sealed()`
+  要求「状态 SEALED **且**已 latch」才返 1（两个标志并成一个，落盘道不可能拿半份快照落盘）→
+  defaultTask 只读锁副本 → `wave_ring_write_done(0 / 非 0)` 是唯一解冻入口：成功才推进轮转号与段
+  计数，失败只计 err 且**保持同号**（下一段重写同一个文件，盘上不留半截）。
+- **两条不许把环焊死的兜底**：SEALED 滞留超过 `WAVE_SEAL_TIMEOUT_MS`（2000 拍，待台架核）自弃本段
+  并计 err；冷却窗 `WAVE_RING_COOL_MS`（500 拍，待台架核）**只在回执之后**计时——「落完解冻」用的是
+  状态不是时间，回执前任何新触发只加 `ovf_cnt` 不重录。
+- **上下文归属直接长在函数命名上**（跨任务安全不靠约定）：`wave_ring_init` / `push` / `tick` /
+  `latch_meta` 只能在 adcTask（⚠ 严禁挂到 TIM3 回调：那是 ISR 且比调度器早约 100 ms，本层没有
+  消费者就绪门）；`wave_ring_write_done` 只能在 defaultTask；`request` / `state` / `sealed` /
+  `sealed_meta` / `read_ch` / `read_cb` / `get_stat` / `col` 任意上下文可调。**本层不提供任何读活
+  缓冲的口子**（docs/子系统设计/故障录波设计说明.md §5.2 第一条陷阱：`sample_ring_window()` 无临界区，本波不复用）。
+- `seg_idx` 只是本次上电的本地计数；盘上的下一个写号归落盘道自持（开机扫目录用
+  `wave_store_idx_from_name()` 重建、写成功后 `wave_store_next_idx()` 推进）。
+
+### 3.11 `wave_store.c` / `wave_store.h` — 段文件字节层（「故障录波」段格式）
+- **只做字节**：文件落点、路径拼法、标定系数、数据本体全部由调用方注入（meta 由 adcTask 填、
+  数据经 `wave_reader_fn` 回调取、路径由落盘道拼）→ 两份文件零平台依赖，主机单测免桩 `#include`
+  原样纳入；`wave_store_meta_init()` 只填格式侧静态事实（并把通道表 `sem` 钉成下标、按归属填
+  `conv` / `bits`），`avail` / `k_q16` / `b_codes` 一律留 0 等封存瞬间现取现填——不复制第二个事实源。
+- **尺寸等式**（单测钉死，落盘道拿它比对写回字节数）：整段 = 32 + 12×通道数 + 2×点数×通道数 + 2；
+  当前口径（8 路 320 点）= 头 128 + 数据 5120 + 尾 CRC 2 = **5250 字节**（这条等式是给落盘道比对写回
+  字节数用的）：FatFs 该移植在簇分配失败时会返回 FR_OK + 短写且无错误码，判成功必须校验字节数
+  （故障录波设计说明「四条已知陷阱」第二条）。
+- **CRC-16/MODBUS 自带无表实现**（反射多项式 0xA001、初值 0xFFFF、异或输出 0，自检锚点字符串
+  "123456789" = 0x4B37）。设计说明 §6.2 原写「与屏板链路同一张表」经全仓实测**不成立**（这张表不
+  存在：crc.c 与 crc.h 已于 2026-10-02 删除，屏板侧 `remo_crc()` 是单字节异或）——文档等文档道回改，
+  代码不擅自改口径，也不再新造第三张表。
+- **编解码同一把尺**：`wave_store_head_build()` 与 `wave_store_head_parse()` 走同一个字段校验函数，
+  判据与 PC 侧读段脚本的拒绝清单逐条对齐（零长度、每周波点数不足 2、每通道点数不够一周波、
+  预触发点数超段长、通道表项语义号不等于下标、版本号与魔数第三字节不一致）——防的就是「板端
+  写得出、PC 读不了」。反过来**不设**任何品质侧不变式：`avail` 同时带有效与削顶是合法事实
+  （lead 裁定 2026-10-29），编码器如实透传、解码器不许据此判废。
+- **游标分次搬运**（256 B 缓冲够用，整段绝不驻留 RAM；数据 CRC 走增量中间值）：
+  `wave_store_pack_next()` 头那一步要求缓冲容量不小于整头 128，否则返 `WAVE_ST_E_PARAM` 且**不推进
+  游标**；没有数据源却进数据区 → `WAVE_ST_E_STATE` 且**不产空字节**（产空字节等于写出「长度对、
+  内容全 0」的段 = docs/子系统设计/故障录波设计说明.md §8.1 明令禁止的伪造证据）。
+- 段名严格 8.3（该移植 `FF_USE_LFN=0`）：`wave_store_seg_path()` 当前布局恒返回 16 个字符（不含结束
+  符），**调用方缓冲至少 17 字节**（`WAVE_ST_PATH_MAX`，原写 16 会让结束符写到缓冲外一字节）；
+  100 个号轮转，`wave_store_next_idx()` 回绕，`wave_store_idx_from_name()` 只认 basename 上的段名。
+- `wave_store_head_build()` / `wave_ring_read_ch()` 这类函数**成功时返回实际字节数 / 点数**（不是
+  `WAVE_ST_OK`），负值才是错误码——写断言前先读头文件的「返 回 值」行（本层单测两次踩在这上面）。

 ## 4. 构建与测试

 ### 4.1 挂载与模拟器边界
- 九个 `.c` 已登记在 `MDK-ARM/STM32F407-Demo.uvprojx`；`../App/algo` 已在 `<IncludePath>` 内。
- 本层**不进** `simulator/CMakeLists.txt`（UI 模拟器不跑采集链路）：九个文件全部登记在
+- 十一个 `.c` 已登记在 `MDK-ARM/STM32F407-Demo.uvprojx`；`../App/algo` 已在 `<IncludePath>` 内。
+- 模拟器侧分两类（Lead 裁定 2026-10-29）：`wave_ring.c` 与 `wave_store.c` **真实参与**
+  `simulator/CMakeLists.txt`——回放页要在模拟器里出真波形，两份又零平台依赖，与「双端共享核心、不造
+  第二真相」同一条口径，故**不进** `SIM_EXEMPT`；其余九个采集链文件（UI 模拟器不跑采集链路）仍登记在
  `scripts/check_registration.py` 的 `SIM_EXEMPT`（附理由），`registration-check` 钩子反向校验（登记簿条目「rs485_task 白名单缺口」）。

-### 4.2 主机侧单测（L0.5）——生产源文件以 `#include` 原样纳入
+### 4.2 主机侧纯逻辑单测——生产源文件以 `#include` 原样纳入

 | 模块 | 命令 | pre-commit 钩子 |
 |---|---|---|
@@ -143,26 +208,48 @@ ADC 引脚电压 V）+ `adc_health_rail_watch()` ×9（L5-2，码值域）→ `s
 | 频率测量 | `& '.venv\Scripts\python.exe' test/host/freq/run_unit_test.py` | `freq-unit-test` |
 | 通道标定（含真实 cfg_file 引擎集成） | `& '.venv\Scripts\python.exe' test/host/adc_cal/run_unit_test.py` | `adc-cal-unit-test` |
 | 遥测快照（布局钉死/双区无撕裂/品质汇总） | `& '.venv\Scripts\python.exe' test/host/meas/run_unit_test.py` | `meas-unit-test` |
+| 录波环（几何与点序 / 冻结与丢样 / 封存握手 / 读窗夹取 / 自弃与冷却） | `& '.venv\Scripts\python.exe' test/host/wave_ring/run_unit_test.py` | 无专属钩子：靠 `test-coverage` 总闸真跑 |
+| 录波段格式（尺寸等式 / CRC 锚点 / 编解码往返与拒绝清单 / 搬运游标 / 段名轮转） | `& '.venv\Scripts\python.exe' test/host/wave_store/run_unit_test.py` | 同上 |
+| 录波触发与全链路（三条来路 / 同拍多请求 / 已封存区不变 / 字节逐列对环） | `& '.venv\Scripts\python.exe' test/host/wave_trig/run_unit_test.py` | 同上 |

 改本目录任一 `.c/.h`，提交时对应钩子自动跑。**用例清单与判据数字的属主**是各
 `test/host/<模块>/` 与 `docs/测试说明/` 下的单测说明，本文不复制（三处抄数字必然打架）。

+录波三套**刻意不新增专属钩子**（Lead 裁定 2026-10-27：钩子口径冻结，新增套数由 `test-coverage`
+总闸全量真跑并守基线回退，失败照样拦，只是归因落在总闸输出上）。两套录波单测之间刻意留了
+一份**分工**：环那套管语义、段格式那套管字节、`wave_trig` 管「接起来之后的语义」（含把封存区
+逐列读出来与打包游标产出的字节逐字节对齐）。两套合成段落在临时目录并把绝对路径打进日志（日志里
+同时标明是哪一份形态），要跟 PC 侧读段脚本互验时把当次产物拷进 `ci-artifacts/wave_interop/` 再报
+路径——**别拿旧副本当本次产物**（踩过：拷过一次之后没刷，别人读到的是上一轮的字节）。
+
 ### 4.3 板端
-`@build` 0 错误 0 警告 → `@test` 看 `[ADC_TASK]` 首拍 / 心跳（`phasor(...)`、`freq(...)`、
+`/keil-build` 0 错误 0 警告 → `/serial-boot-test` 看 `[ADC_TASK]` 首拍 / 心跳（`phasor(...)`、`freq(...)`、
 `cal: ua_mv=… vl=0x00 cl=0xE6 rail=…`、`ring` / `skip` / `adc1_*` / `tgap`）；
 健康判据 = **零 `[ERR]`**（健康告警与标定哨兵全以 `[ERR]` 开头，误报会被闭环直接抓住；
-`vl` 在未标定默认构建必须为 0x00，卡 5 闭锁落地后 `cal:` 行就是台架期望的直接证据）。
+`vl` 在未标定默认构建必须为 0x00，未标定即闭锁落地后 `cal:` 行就是台架期望的直接证据）。
 → `docs/算法/采集与算法层设计说明.md` §12。

 ## 5. 新增一个算法模块的固定动作

 1. 在本目录建 `xxx.c/h`，文件头写模块注释块（规范 V1.0），**尽量零平台依赖**以便免桩单测。
+   需要 `NULL` 的 `.c` 自己 `#include` 一个 `stddef.h`：ARMCC 的 `stdint.h` 不提供 `NULL`，而主机侧
+   MSVC / gcc 会传递性把它拉进来，**主机单测照不出这个分叉**（2026-10-29 台基线构建实测报 22 条
+   identifier "NULL" 未定义，根因即此；与 `sample_ring.c` / `freq.c` 同口径，别塞进公共头）。
 2. 用 `new-source-file` skill 注册到 `MDK-ARM/STM32F407-Demo.uvprojx`（新建子目录还要补 `<IncludePath>`）。
   模拟器侧二选一：有消费路径 → 加 `simulator/CMakeLists.txt`；纯算法无消费路径 → 加
   `scripts/check_registration.py` 的 `SIM_EXEMPT`（照本目录既有七条写理由），否则 `registration-check` 拦。
-3. 加 `test/host/<模块>/` 主机单测 + `.pre-commit-config.yaml` 钩子（照 `phasor-unit-test` 抄）。
+3. 加 `test/host/<模块>/` 主机单测（照 `test/host/meas` 或 `test/host/soe_store` 抄目录形态与
+   `run_unit_test.py`）。**要不要补 `.pre-commit-config.yaml` 专属钩子按 Lead 裁定 2026-10-27：默认不补**，
+   由 `test-coverage` 总闸全量真跑；确有秒级归因需求再单独申请。用例标题写「它在验证什么」这类语义
+   短语，**不要发字母紧跟数字的新编号**（`docs/编号规范.md` §4.1「已停发」栏：停发不等于可以新发）。
 4. 消费者写在 `App/task/`，本层只出"数"；跨转换器禁令见 §3 开头四条红线。
 5. 在本 README §1 清单加一行，并在 `docs/算法/采集与算法层设计说明.md` 里写清该模块的契约与理由。
+6. **单测产出的互验字节（要被别人的脚本读的那些）：跑测之后立刻刷新副本并记下 sha256**。三套录波单测把合成段落
+   在临时目录、并把**绝对路径 + 是哪一份形态**打进日志，所以「跑完顺手拷一次、以后再没刷」必然留下旧副本——
+   本仓这类坑不止一次（旧副本被当本次证据引用过：一次是别人拿上一轮的字节下了「字节级已闭合」的结论）。
+   判据：引用方只认**当次运行日志里那条路径 + 当次 sha256**；产物有第二种形态（例如本波真值形态与「已标定后
+   仍削顶」的构造形态）就在文件名或日志里把形态写明，别让读者靠猜；拷进 `ci-artifacts/wave_interop/` 之类的
+   共享目录时，同一笔操作里就把新 sha 一起报给对岸，别隔一轮。

 ## 6. 相关文档

@@ -171,5 +258,8 @@ ADC 引脚电压 V）+ `adc_health_rail_watch()` ×9（L5-2，码值域）→ `s
 - 分层与功能项清单：`docs/算法/继电保护功能复现规划.md`
 - 傅氏算法与有效值口径：`docs/算法/傅氏算法详解.md`
 - 采样节拍（TIM3 1 kHz + TRGO 触发 ADC1 / DMA）：`docs/子系统设计/ADC采样节拍设计说明.md`
- 相量层 / ADC 输入层单测细则：`docs/测试说明/相量层单元测试说明.md`、`docs/测试说明/ADC输入层单元测试说明.md`
+- **故障录波**（数据面 / 段格式 / 现场回放契约）：docs/子系统设计/故障录波设计说明.md §6.2 是段文件
+  字节布局的属主，同一篇的 docs/子系统设计/故障录波设计说明.md §6.3 是字段口径裁定——两节合起来是板端
+  编码器与 PC 读段脚本两份独立实现的共同依据；板级判据与执行顺序 → docs/子系统设计/故障录波设计说明.md §10
+- 相量层 / ADC 输入层单测细则：`docs/测试说明/单元测试/相量层单元测试说明.md`、`docs/测试说明/单元测试/ADC输入层单元测试说明.md`
 - RAM 与栈台账：`docs/内存管理/RAM使用分析与优化方案.md`
@@ -1,9 +1,9 @@
 /*
- * 模块名称：通道标定与量纲折算（L1.5）——实现
+ * 模块名称：通道标定与量纲折算（标定折算）——实现
 * 模块功能：见 adc_cal.h。折算模型（工程量 = (code + b) × k × 1e-6，k 为 Q16
 *           µV/码）与两段 cfg 布局（[adc_cal]：k_* + valid 位图；[adc_cal_ofs]：
 *           b_*）照 docs/任务规划/数据可信.md §4.1 / §4.4 落地；系数口径
- *           （ROM 默认 = 卡 1 定死的引脚侧 LSB）见 docs/硬件平台/ADC通道映射说明.md
+ *           （ROM 默认 = 量程口径冻结定死的引脚侧 LSB）见 docs/硬件平台/ADC通道映射说明.md
 *           §7.1。
 *         并发契约：cfg RAM 副本属主 = 配置引擎（defaultTask 的 load/poll 原地
 *           改写），本层逐点折算现读——int32 对齐字在 Cortex-M4 上读写原子，
@@ -15,10 +15,10 @@
 *           VALID，每通道每次开机首见沿打一条 [ERR]（adc_cal_init 重置留痕）。
 * 适用平台：STM32F407ZGTx（Cortex-M4F，硬件 FPU）
 * 作者：DTU 项目组
- * 创建日期：2026-10-25（道A 卡 2/卡 4）
+ * 创建日期：2026-10-25（道A 标定折算与落盘整定）
 * 修改记录：
 *   v1.0  2026-10-25  DTU 项目组  创建：Q16 系数/零点两段落盘 + 折算 + 三态 flags
- *   v1.1  2026-10-25  DTU 项目组  卡 10（道D）：新增 adc_cal_b_codes() 生效零点
+ *   v1.1  2026-10-25  DTU 项目组  运行参数段（道D）：新增 adc_cal_b_codes() 生效零点
 *                                 读取口；set() 授权写者扩至 iec104Task 直通路径
 *                                 （run_par 0x8040~/0x8048~，契约同 §4.4）
 *                                 + 合法带哨兵回退 + 两点标定公式（台架注入待跑）
@@ -27,6 +27,9 @@
 *                                 DTU_BENCH 旁路同时收成全仓唯一一处；此前该判据在
 *                                 protect_task.c 与 ui_data_feed.c 各写一份，两处一旦
 *                                 漂移，屏上「未标定」与判据实际停走就不是同一件事
+ *   v1.3  2026-10-29  DTU 项目组  故障录波 task-2：新增 adc_cal_k_q16() int32 原值直读口
+ *                                 （段头 k 字段 LSB 精确，float 反推在 5.28e7 掉尾数，
+ *                                 口径见 docs/子系统设计/故障录波设计说明.md §6.3）
 */

 /* 头文件包含区 */
@@ -61,7 +64,7 @@ typedef struct {
    uint8_t valid;
 } adc_cal_kcfg_t;

-/* [adc_cal_ofs] 段 RAM 副本：b 按语义下标 0..7（int32 有符号，卡 3 的
+/* [adc_cal_ofs] 段 RAM 副本：b 按语义下标 0..7（int32 有符号，有符号零点类型
 * CFG_VAL_INT 是负零点偏移能干净落盘的前提） */
 typedef struct {
    int32_t b[8];
@@ -70,12 +73,12 @@ typedef struct {
 static adc_cal_kcfg_t  s_kcfg;        /* 生效系数副本（引擎原地更新） */
 static adc_cal_bcfg_t  s_bcfg;        /* 生效零点副本 */

-/* 工厂默认（ROM 理论系数，卡 1 定死，「数据可信」§4.4）：**下标 = 语义枚举**
+/* 工厂默认（ROM 理论系数，量程口径冻结定死，「数据可信」§4.4）：**下标 = 语义枚举**
 * （UA0 / UB1 / UC2 / UN3 / IA4 / IB5 / IC6 / IN7）——UA/UN/IA 走 TPAFE
 * （16 位 ±5 V 档），UB/UC/IB/IC/IN 走 STM32 ADC1；逐路对过
 * docs/硬件平台/ADC通道映射说明.md §3（IN=ADC11/STM32，勿再按分组顺序误写）。
 * ROM 表按**当前 V0.1 来源排布**显式书写（不查 desc 运行期派生），因为它是
- * 卡 1 定稿的存档事实；V0.2 改版（消除双转换器无共同采样触发）时本表与 adc_input 映射表同步改，
+ * 量程口径冻结定稿的存档事实；V0.2 改版（消除双转换器无共同采样触发）时本表与 adc_input 映射表同步改，
 * 上层语义与 API 不动。CLIPPED 位则**运行期按来源派生**（见 adc_cal_flags） */
 static const adc_cal_kcfg_t s_kcfg_rom = {
    /* idx0 UA / idx1 UB / idx2 UC / idx3 UN */
@@ -92,6 +95,15 @@ static const adc_cal_bcfg_t s_bcfg_rom = { { 0L, 0L, 0L, 0L, 0L, 0L, 0L, 0L } };
 * adc_cal_init 清零 = 新一轮观测窗） */
 static uint8_t s_err_latched;

+/*
+ * 观测计数（三态语义唯一落点在 adc_cal.h，这里只写"怎么自增"）：与上面那个留痕位
+ * 不同，这三个数一个 [ERR] 都不打、也不参与任何判定，因此 **adc_cal_init() 刻意不清**
+ * ——清了水位与计数就失配，会凭空造出一段"假未落盘"差额。
+ */
+static volatile uint32_t s_st_set_ok;        /* 成功改写 RAM 副本的次数 */
+static volatile uint32_t s_st_set_reject;    /* 被拒次数（非法通道 / 越出合法带） */
+static volatile uint32_t s_st_persist_water; /* 落盘水位：盖写，绝不自增 */
+
 /* 键表：offset 用 offsetof 取真值（k[0]@0 / k[1]@4 … valid@32） */
 static const cfg_key_def_t s_k_keys_tbl[9] = {
    { "k_ua",  CFG_VAL_INT,  offsetof(adc_cal_kcfg_t, k[0]),  4u },
@@ -327,12 +339,31 @@ float adc_cal_k_uv(adc_semantic_t sem) {
    return ((float)k) / 65536.0f;
 }

+/*
+ * 函数功能：读通道当前生效系数的 int32 Q16 原值（adc_cal_k_uv 孪生，见 .h 声明）
+ * 入口参数：sem - 语义通道  adc_semantic_t
+ * 返 回 值：k[Q16]；TEMP/越界返 0  int32_t
+ * 限定条件：无（任意上下文，纯读）
+ * 函数说明：与 adc_cal_k_uv() 共用 s_eff_kb 生效视图（越带回退 ROM 口径一致），
+ *          差别只在不做浮点还原——录波段头按 LSB 精确记账必须走本口（§6.3）
+ */
+int32_t adc_cal_k_q16(adc_semantic_t sem) {
+    int32_t k;
+    int32_t b;
+
+    if ((unsigned)sem >= (unsigned)ADC_SEM_TEMP) {
+        return 0;
+    }
+    (void)s_eff_kb((unsigned)sem, &k, &b);
+    return k;
+}
+
 /*
 * 函数功能：读通道当前生效零点偏移（码值，浮点）——adc_cal_k_uv 孪生入口
 * 入口参数：sem - 语义通道  adc_semantic_t
 * 返 回 值：b[码值]（越带时 s_eff_kb 已回 0）；TEMP/越界返 0  float
 * 限定条件：无（任意上下文，纯读）
- * 函数说明：卡 10 的 104 b 覆盖回显 + k 单侧改写 RMW 读侧（App/algo/run_par.c）
+ * 函数说明：运行参数段的 104 b 覆盖回显 + k 单侧改写 RMW 读侧（App/algo/run_par.c）
 */
 float adc_cal_b_codes(adc_semantic_t sem) {
    int32_t k;
@@ -346,30 +377,60 @@ float adc_cal_b_codes(adc_semantic_t sem) {
 }

 /*
- * 函数功能：整定入口——写通道系数与零点，并置位 VALID（「数据可信」卡 4）
+ * 函数功能：整定入口——写通道系数与零点，并置位 VALID（「数据可信」标定落盘与整定入口）
 * 入口参数：sem - 语义通道；k_q16 - 系数（µV/码×65536）；b_codes - 零点（码值）
 * 返 回 值：0 - 成功；-1 - 参数非法/越出合法带（RAM 不动，[ERR] 留痕）  int
 * 限定条件：整定路径上下文（defaultTask 整定/标定链；iec104Task 经 run_par
- *          直通为卡 10 授权写者，单字原子契约同 §4.4）；落盘由属主经 cfg_file_save
+ *          直通为运行参数段授权写者，单字原子契约同 §4.4）；落盘由属主经 cfg_file_save
 * 函数说明：见 adc_cal.h 同名声明
 */
 int adc_cal_set(adc_semantic_t sem, int32_t k_q16, int32_t b_codes) {
    if ((unsigned)sem >= (unsigned)ADC_SEM_TEMP) {
+        s_st_set_reject++;           /* 观测：连通道号都非法，RAM 未动 */
        return -1;
    }
    if (s_kband_ok((unsigned)sem, k_q16, b_codes) == 0) {
        DBG_ERROR("set ch=%u rejected: k_q16=%ld b=%ld out of ROM band [0.5x,2x]/|b|<=%ld",
                  (unsigned)sem, (long)k_q16, (long)b_codes, (long)ADC_CAL_B_MAX);
+        s_st_set_reject++;           /* 观测：越出合法带，RAM 未动（[ERR] 由上一行打） */
        return -1;
    }
    s_kcfg.k[sem] = k_q16;
    s_bcfg.b[sem] = b_codes;
    s_kcfg.valid |= (uint8_t)(1u << (unsigned)sem);
+    s_st_set_ok++;                   /* 观测：RAM 副本确实被改写了（与落盘无关） */
    return 0;
 }

 /*
- * 函数功能：两点标定公式（卡 12 的算术核，纯函数无状态）
+ * 函数功能：读标定层观测计数（不取锁、不取时刻、任意上下文可读）
+ * 返 回 值：无  void
+ * 限定条件：无；adc_cal_init() 之前可读（全 0 = 本层还没被改写过）
+ * 函数说明：见 adc_cal.h 同名声明（三态语义与那张成对读表都在那里，本处只取数）
+ */
+void adc_cal_get_stats(adc_cal_stats_t *p_out) {
+    if (p_out == NULL) {
+        return;                      /* 观测件不得反过来制造故障 */
+    }
+    p_out->set_ok           = s_st_set_ok;
+    p_out->set_reject       = s_st_set_reject;
+    p_out->persisted_set_ok = s_st_persist_water;
+}
+
+/*
+ * 函数功能：落盘成功回执——把水位盖写为当前的 set_ok（不是自增）
+ * 返 回 值：无  void
+ * 限定条件：仅"整档保存已成功"那一条路径（当前唯一调用点 run_par_store_save()）
+ * 函数说明：盖写而非自增的理由与回归用例见 adc_cal.h 同名声明。水位直接取 set_ok 的
+ *          当前值，因此它**在结构上不可能越过** set_ok——差额是 uint32 相减，一旦越过
+ *          就绕回成一个巨大的假未落盘数，这里不留那种可能
+ */
+void adc_cal_note_persisted(void) {
+    s_st_persist_water = s_st_set_ok;   /* 水位只会追平，不会越过 */
+}
+
+/*
+ * 函数功能：两点标定公式（标定项的算术核，纯函数无状态）
 * 入口参数：c_lo/c_hi、v_lo_uv/v_hi_uv、p_k_q16/p_b  见 adc_cal.h 同名声明
 * 返 回 值：0 成功 / -1 参数或斜率非法 / -2 零点越 ±B_MAX  int
 * 限定条件：无（int64 中间量，主机可测；台架注入待跑）
@@ -403,7 +464,8 @@ int adc_cal_two_point(int32_t c_lo, int32_t c_hi, int32_t v_lo_uv, int32_t v_hi_
 }

 /*
- * 函数功能：通道码值域贴轨带门限（L5-2 判定的门限来源，按 FS 百分比）
+ * 函数功能：通道码值域贴轨带门限（采样通道自检 判定的门限来源，按 FS 百分比）
+ *（保护功能清单见 docs/算法/继电保护功能复现规划.md）
 * 入口参数：sem - 语义通道；p_lo_th/p_hi_th - 输出下/上轨带界  int32_t *
 * 返 回 值：0 - 已给出门限；-1 - TEMP/越界/参数空（不做贴轨监视）  int
 * 限定条件：无
@@ -1,5 +1,5 @@
 /*
- * 模块名称：通道标定与量纲折算（L1.5，「数据可信」卡 2/卡 4）
+ * 模块名称：通道标定与量纲折算（标定折算，「数据可信」标定折算与落盘整定）
 * 模块功能：把 adc_input 的原始码值折算成工程量——模型与系数口径的唯一落点：
 *             工程量 = (code + b) × k_f，k_f = k[µV/码] × 1e-6
 *           k 以 int32 **Q16**（µV/码 × 65536）落盘、b 以 int32 码值落盘，
@@ -8,29 +8,33 @@
 *           即生效值，逐点折算现取现用（1 kHz × 9 通道 = 9k 次/秒浮点乘，可忽略）。
 *           三态可用性：ADC_CAL_F_VALID（已按变比标定 → 工程量为二次值）与
 *           ADC_CAL_F_CLIPPED（V0.1 硬件削顶）由 adc_cal_flags() 单点查询，
- *           104 / UI / 保护闭锁（卡 5）共用（docs/任务规划/数据可信.md §4.2）。
+ *           104 / UI / 保护闭锁（未标定即闭锁）共用（docs/任务规划/数据可信.md §4.2）。
 *           **未标定闭锁的判定本身也归本层**（`adc_cal_prot_blocked()`）：它讲的是
 *           「这几路标定齐了没」，属标定层事实，不是任务编排逻辑——保护任务与 UI
 *           组装器都只是它的消费者（道F task-16 把此前的两份实现收成一份）。
- *         ⚠ 输出单位口径 = **ADC 引脚电压 V**（eng=0）：ROM 默认系数按卡 1
+ *         ⚠ 输出单位口径 = **ADC 引脚电压 V**（eng=0）：ROM 默认系数按量程口径冻结
 *           定死的引脚侧 LSB（TPAFE 152.59 µV/码、STM32 805.66 µV/码，见
- *           docs/硬件平台/ADC通道映射说明.md §7.1）；端子变比（卡 0b）与两点
- *           标定（卡 12）完成前不得把输出当二次值消费。TEMP 不参与线性标定
+ *           docs/硬件平台/ADC通道映射说明.md §7.1）；端子/子板变比确认与两点
+ *           标定完成前不得把输出当二次值消费。TEMP 不参与线性标定
 *           （决策 5），adc_cal_apply() 原样透传码值。
 *         本层**纯算法 + 纯数据**：不碰寄存器、不等事件；adc_cal_init() 内核前
 *           可调（注册进引擎必须先于 cfg_file_load，FTP 鉴权确立的契约）；apply/flags
 *           任意上下文可读（cfg RAM 副本 4 字节对齐字读写在 Cortex-M4 上原子，
 *           与 defaultTask 的 load/poll 复位存在 µs 级混窗——设计接受，见 .c 头）。
- * 适用平台：STM32F407ZGTx（Cortex-M4F）；主机侧 L0.5 单测 test/host/adc_cal/
+ * 适用平台：STM32F407ZGTx（Cortex-M4F）；主机侧纯逻辑单测 test/host/adc_cal/
 * 作者：DTU 项目组
- * 创建日期：2026-10-25（道A 卡 2/卡 4）
+ * 创建日期：2026-10-25（道A 标定折算与落盘整定）
 * 修改记录：
 *   v1.0  2026-10-25  DTU 项目组  创建：Q16 系数/零点 + 折算/flags/集
- *   v1.1  2026-10-25  DTU 项目组  卡 10：+adc_cal_b_codes()（run_par 回显/RMW 用）
+ *   v1.1  2026-10-25  DTU 项目组  运行参数段：+adc_cal_b_codes()（run_par 回显/RMW 用）
 *   v1.2  2026-10-26  DTU 项目组  道F task-16：+adc_cal_prot_blocked()——「UA/UN/IA
 *                                 三路 VALID 是否齐」这份判据停走条件从
 *                                 protect_task.c 与 ui_data_feed.c 的两份重复实现收成本层
 *                                 单点（DTU_BENCH 旁路同时收成一处）
+ *   v1.3  2026-10-29  DTU 项目组  故障录波 task-2：新增 adc_cal_k_q16()——k 的 int32
+ *                                 Q16 原值直读口（adc_cal_k_uv 的孪生）。录波段头 k 字段
+ *                                 是 LSB 精确记账，float 在 5.28e7 码字上掉尾数，
+ *                                 禁止经浮点反推（docs/子系统设计/故障录波设计说明.md §6.3）
 */

 #ifndef ADC_CAL_H
@@ -45,11 +49,11 @@ extern "C" {
 #endif

 /* 通道可用性标志（adc_cal_flags() 返回值位） */
-#define ADC_CAL_F_VALID       (0x01u)   /* k 已按变比标定 → 工程量为二次值（卡 12 后置位） */
+#define ADC_CAL_F_VALID       (0x01u)   /* k 已按变比标定 → 工程量为二次值（两点标定后置位） */
 #define ADC_CAL_F_CLIPPED     (0x02u)   /* 硬件削顶（V0.1 STM32 侧单极性无偏置）→ 交流量不可信 */

 /*
- * ROM 默认系数（int32 Q16 = µV/码 × 65536，卡 1 定死的引脚侧口径）：
+ * ROM 默认系数（int32 Q16 = µV/码 × 65536，量程口径冻结定死的引脚侧口径）：
 *   TPAFE ±5 V 档：10 V 跨度 / 65536 码 = 152.587890625 µV/码 → ×65536 = 10,000,000（整）
 *   STM32 0~3.3 V：3.3 V / 4096 码 = 805.6640625 µV/码 → ×65536 = 52,800,000（整）
 * 两个默认值在 Q16 下**无舍入**（系数定点舍入项从误差预算里抹掉，
@@ -99,7 +103,7 @@ float adc_cal_apply(adc_semantic_t sem, int32_t code);
 uint32_t adc_cal_flags(adc_semantic_t sem);

 /*
- * 函数功能：**未标定闭锁判定**——保护判据所需的三路标定是否齐（「数据可信」卡 5
+ * 函数功能：**未标定闭锁判定**——保护判据所需的三路标定是否齐（「数据可信」未标定即闭锁
 *           / §4.3；道F task-16 把它从两处重复实现收敛成这一份真源）
 * 入口参数：无
 * 返 回 值：1 - 闭锁（UA/UN/IA 中至少一路 `ADC_CAL_F_VALID` 未置位，判据链应停走）；
@@ -111,7 +115,8 @@ uint32_t adc_cal_flags(adc_semantic_t sem);
 *            的测量通道；UB/UC/IB/IC/IN 即使将来标定也另受 `CLIPPED` 品质约束
 *            （M5 快照层处理），不掺进本闭锁源。
 *          ② ⚠ **不得当「保护在跑」的总括用**：判据停走共四路来源，本函数只覆盖
- *            第二路——(a) L5-4 采样故障闭锁（`adc_health_flags()`）；(b) 本函数
+ *            第二路——(a) 自检失败闭锁 采样故障闭锁（`adc_health_flags()`）；(b) 本函数
+ *（保护功能清单见 docs/算法/继电保护功能复现规划.md）
 *            （未标定）；(c) 定值校验和失配闭锁（`prot_set_locked()`）；(d) 全局软压板
 *            退出（`PS_GLOBAL_EN` = 0）。要判「这拍到底评估了没有」必须四路一起看
 *            （编排顺序见 `App/task/protect_task.c`）。
@@ -134,7 +139,7 @@ uint8_t adc_cal_prot_blocked(void);
 * 入口参数：sem - 语义通道  adc_semantic_t
 * 返 回 值：k[µV/码]（回退后口径）；TEMP / 越界返 0  float
 * 限定条件：无
- * 函数说明：L5-2 门限换算、日志与整定界面回显用；勿据其反推二次值（看 flags）
+ * 函数说明：采样通道自检 门限换算、日志与整定界面回显用；勿据其反推二次值（看 flags）
 */
 float adc_cal_k_uv(adc_semantic_t sem);

@@ -143,27 +148,42 @@ float adc_cal_k_uv(adc_semantic_t sem);
 * 入口参数：sem - 语义通道  adc_semantic_t
 * 返 回 值：b[码值]（越带时为 0，与折算同视图）；TEMP/越界返 0  float
 * 限定条件：无
- * 函数说明：104 运行参数段（「数据可信」卡 10）b 覆盖回显与 k 单侧改写的 RMW
+ * 函数说明：104 运行参数段（「数据可信」这一项）b 覆盖回显与 k 单侧改写的 RMW
 *          读侧用（App/algo/run_par.c）；勿据其反推二次值（看 flags）。
 */
 float adc_cal_b_codes(adc_semantic_t sem);

 /*
- * 函数功能：整定入口——写通道系数与零点，并置位 VALID（「数据可信」卡 4）
+ * 函数功能：读通道当前生效系数的 **int32 Q16 原值**（µV/码 × 65536）——
+ *           adc_cal_k_uv() 的孪生入口，给「必须 LSB 精确」的消费者用
+ * 入口参数：sem - 语义通道  adc_semantic_t
+ * 返 回 值：k[Q16 原值]（与折算同一生效视图：越带回退 ROM、b 不参与）；TEMP/越界返 0  int32_t
+ * 限定条件：无（任意上下文，纯读）
+ * 函数说明：故障录波段头的 k 字段是 int32 LSB 精确记账（docs/子系统设计/故障录波设计说明.md
+ *          §6.3 裁定）——float 还原后在 5.28e7 码字上掉尾数，**禁止**拿
+ *          adc_cal_k_uv() 反乘 65536 回算落盘，故开本原值口。
+ */
+int32_t adc_cal_k_q16(adc_semantic_t sem);
+
+/*
+ * 函数功能：整定入口——写通道系数与零点，并置位 VALID（「数据可信」标定落盘与整定入口）
 * 入口参数：sem     - 语义通道（电气 8 路）  adc_semantic_t
 *           k_q16   - 系数，µV/码 × 65536  内 int32_t
 *           b_codes - 零点偏移，码值  内 int32_t
 * 返 回 值：0 - 成功；-1 - 参数非法/越出合法带（RAM 不动，[ERR] 留痕）  int
- * 限定条件：**整定路径上下文**（defaultTask 标定流程/整定链；卡 10 起 iec104Task
+ * 限定条件：**整定路径上下文**（defaultTask 标定流程/整定链；运行参数段落地起 iec104Task
 *          经 App/algo/run_par.c 的 0x8040~/0x8048~ 直通写亦为授权写者——写的仍是
 *          引擎对齐 int32 单字，µs 级混窗契约同「数据可信」§4.4）。勿在 adcTask 调用
- * 函数说明：只写 RAM 副本；落盘由属主经 cfg_file_save 完成（卡 10 前整定链
- *          未接，台架两点标定（卡 12）是首个消费者）
+ * 函数说明：**只写 RAM 副本，不置脏、不落盘、不返回"稍后会存"的承诺**——落盘由属主经
+ *          cfg_file_save 完成，而"要不要落盘"这件事只有一个真源：run_par 的脏标志。
+ *          因此授权写者是 run_par 的语义 setter（写值 + 置脏成对发生，lead 裁②）；
+ *          绕过它直调本函数 = 值只活在 RAM 里，重启即丢且**没有错误返回**，
+ *          该形态现可被本层观测计数抓到（差分口径见下方 adc_cal_stats_t 那张表）
 */
 int adc_cal_set(adc_semantic_t sem, int32_t k_q16, int32_t b_codes);

 /*
- * 函数功能：两点标定公式（「数据可信」卡 12 的算术核，纯函数无状态）
+ * 函数功能：两点标定公式（「数据可信」标定项的算术核，纯函数无状态）
 * 入口参数：c_lo/c_hi           - 两点码值（c_hi > c_lo）  int32_t
 *           v_lo_uv/v_hi_uv     - 两点实测电压（µV，v_hi > v_lo，端子/引脚域均可）  int32_t
 *           p_k_q16 / p_b       - 输出：系数（Q16）与零点偏移（码值）  int32_t *
@@ -177,17 +197,78 @@ int adc_cal_two_point(int32_t c_lo, int32_t c_hi, int32_t v_lo_uv, int32_t v_hi_
                      int32_t *p_k_q16, int32_t *p_b);

 /*
- * 函数功能：通道码值域「贴轨带」门限（L5-2 越界检出的门限来源，按 FS 百分比）
+ * 函数功能：通道码值域「贴轨带」门限（采样通道自检 越界检出的门限来源，按 FS 百分比）
 * 入口参数：sem     - 语义通道  adc_semantic_t
 *           p_lo_th - 下轨带上界（code ≤ 此值判触底）  int32_t *
 *           p_hi_th - 上轨带下界（code ≥ 此值判触顶）  int32_t *
 * 返 回 值：0 - 已给出门限；-1 - TEMP/越界（不做贴轨监视）  int
 * 限定条件：无
 * 函数说明：TPAFE 双极性 ±98% FS（±32112）；STM32 上轨 98% FS（4013）、
- *          下轨 2% FS（81）；判定状态机在 adc_health_rail_watch()（L5-2）
+ *          下轨 2% FS（81）；判定状态机在 adc_health_rail_watch()（采样通道自检）
 */
 int adc_cal_rail_ths(adc_semantic_t sem, int32_t *p_lo_th, int32_t *p_hi_th);

+/*
+ * 观测计数：把「改了没落盘」从意图式陈述变成可诊断事实（道G task-43 第②项；
+ * 先例 App/fs/vol_lock.h 的同族设计——只计数、不取锁、不在调用点打日志、不打 [ERR]）
+ *
+ * 三态语义（**定义只在本头文件这一处**，消费者只描述取数与断言，不重定义）：
+ *   set_ok            RAM 副本被本层 API 成功改写的累计次数
+ *   set_reject        被本层拒掉的整定请求累计次数（参数非法 / 越出合法带）
+ *   persisted_set_ok  **水位**而不是计数：最近一次随整档保存落盘成功时的
+ *                     set_ok 快照（由 adc_cal_note_persisted() 盖写，永不越过 set_ok）
+ *
+ * 未落盘差额 = set_ok − persisted_set_ok，即"自上次成功落盘之后被改写的次数"。
+ * 单看差额不够定性，必须与 run_par_dirty_peek() 成对读（两列一起才只有一种解释）：
+ *
+ *   差额   run_par_dirty_peek()   说的是什么事
+ *   ------ ---------------------- ----------------------------------------------
+ *   0      0                      盘与 RAM 齐（或压根没改过）——健康
+ *   >0     1                      改了、还没到落盘时机——正常在途
+ *   >0     0                      **改了且永远不会落盘**：写者绕过 run_par 的语义
+ *                                 setter 直调 adc_cal_set()（运行参数段起的事）
+ *
+ * 消费者告诫（与 vol_lock_get_stats() 同一套，别重犯）：
+ *   ① 本组接口不取锁、不取时刻，任意上下文可读；三个数各自是 uint32 单字读写，
+ *      Cortex-M4 上原子，但三个数之间**没有共同时刻**——别把它们拼成"一个瞬间的快照"
+ *      下结论，定性只按上面那张两列表成对读。
+ *   ② 需要"被观测到的时刻"请在消费者侧自盖并冠 obs_ 前缀命名（先例：喂狗点单写者 latch），
+ *      本层不存时刻——存了就得连带管溢出与单位。
+ *   ③ 这些计数**不参与任何判定**：能不能信只看 adc_cal_flags() /
+ *      adc_cal_prot_blocked()，要不要落盘只看 run_par 的脏标志。别拿差额去改控制流，
+ *      那等于把观测升级成第二真源（标定写入口已由 run_par 语义 setter 收口，不再加口）。
+ *   ④ 写清盲区：本层刻意**不挂** cfg_file 回调，因此"盘 → RAM 的覆盖"（cfg_file_load
+ *      与外部变更重载）不产生任何计数；未落盘的改值被一次重载无声吞掉，正是这三个
+ *      数照不到的那一条。要照它得先给本层挂回调 = 行为改动，另行立项处置。
+ */
+typedef struct {
+    uint32_t set_ok;           /* 成功改写 RAM 副本次数（见上方唯一落点） */
+    uint32_t set_reject;       /* 被拒次数（见上方唯一落点） */
+    uint32_t persisted_set_ok; /* 落盘水位，不是计数（见上方唯一落点） */
+} adc_cal_stats_t;
+
+/*
+ * 函数功能：读标定层观测计数（只读，不改任何状态）
+ * 入口参数：p_out - 输出：三个观测计数  adc_cal_stats_t *
+ * 返 回 值：无  void
+ * 限定条件：任意上下文可读（含 ISR 与内核启动前）；adc_cal_init() 之前可读，得全 0
+ * 函数说明：p_out 为 NULL 时静默返回——观测件不得反过来制造故障
+ */
+void adc_cal_get_stats(adc_cal_stats_t *p_out);
+
+/*
+ * 函数功能：落盘成功回执——把水位 persisted_set_ok 盖写为当前的 set_ok（**不是自增**）
+ * 入口参数：无  void
+ * 返 回 值：无  void
+ * 限定条件：只允许配置引擎属主侧"整档保存已成功"那一条路径调用；当前唯一调用点 =
+ *          App/algo/run_par.c 的 run_par_store_save() 中 cfg_file_save() 返 0 之后
+ * 函数说明：为什么盖写不自增——一次 save 覆盖整档，可能对应多次整定改写（逐通道
+ *          标定 3 路 = 3 次 adc_cal_set + 1 次 save）；自增会留下 2 次"假未落盘"。
+ *          水位语义让差额只反映"上次落盘之后的改写"，回归锁见
+ *          test/host/adc_cal/adc_cal_test.c 的 TC-ADCCAL-021
+ */
+void adc_cal_note_persisted(void);
+
 #ifdef __cplusplus
 }
 #endif
@@ -1,5 +1,6 @@
 /*
- * 模块名称：ADC 采样有效性校验（L1 采集与预处理，规划项 L1-6）
+ * 模块名称：ADC 采样有效性校验（语义取数与预处理）
+ *（保护功能清单见 docs/算法/继电保护功能复现规划.md）
 * 模块功能：见 adc_health.h 文件头。本文件为**纯逻辑实现**：输入计数快照、
 *          输出故障位/事件位，零平台依赖（仅 stdint.h/string.h 标准 C）→
 *          主机侧免桩单测。
@@ -7,18 +8,18 @@
 * 作者：王建锋
 * 创建日期：2026-10-11
 * 修改记录：
- *   v1.0  2026-10-11  王建锋  创建：L1-6 采样有效性校验
+ *   v1.0  2026-10-11  王建锋  创建：采样有效性校验
 *   v1.1  2026-10-21  王建锋  新增 adc_health_age_stale()：无模块状态的帧年龄
 *                             纯判据（参照系由调用方自存），供 protectTask 的
 *                             兜底新鲜度门使用，见 adc_health.h 同名声明
- *   v1.2  2026-10-25  DTU 项目组  新增 L5-2 残余：码值越界（贴轨）观察器
+ *   v1.2  2026-10-25  DTU 项目组  新增 采样通道自检 残余：码值越界（贴轨）观察器
 *                             （rail_watch/rail_sticky/rail_init），判据与释放
- *                             沿理由见 adc_health.h L5-2 段注释
+ *                             沿理由见 adc_health.h 采样通道自检 段注释
 */

 #include "adc_health.h"

-#include <string.h>   /* memset（L5-2 贴轨观察器数组复位） */
+#include <string.h>   /* memset（采样通道自检 贴轨观察器数组复位） */

 /* ===================== 内部状态 ===================== */

@@ -42,7 +43,7 @@ static uint32_t s_flags;    /* 电平位（stall 可自愈；backward 锁存在
 static uint32_t s_sticky;   /* 锁存位（含电平位历史并集） */
 static uint32_t s_tpafe_gaps;

-/* L5-2 贴轨观察器（每通道独立小状态机，单写者 = adcTask） */
+/* 采样通道自检 贴轨观察器（每通道独立小状态机，单写者 = adcTask） */
 typedef struct {
    uint16_t run_hi;    /* 连续贴上轨计数（饱和 0xFFFF） */
    uint16_t run_lo;    /* 连续贴下轨计数 */
@@ -257,7 +258,7 @@ uint32_t adc_health_tpafe_gaps(void) {
    return s_tpafe_gaps;
 }

-/* ===================== L5-2 贴轨观察器实现 ===================== */
+/* ===================== 采样通道自检 贴轨观察器实现 ===================== */

 /*
 * 函数功能：贴轨观察器复位（幂等；adc_health_init() 已内含）
@@ -1,5 +1,6 @@
 /*
- * 模块名称：ADC 采样有效性校验（L1 采集与预处理，规划项 L1-6）
+ * 模块名称：ADC 采样有效性校验（语义取数与预处理）
+ *（保护功能清单见 docs/算法/继电保护功能复现规划.md）
 * 模块功能：对两片转换器的"节拍是否还在喂数据"做**判定层**（观测计数由
 *          `adc_input` / `tpafe5160` 驱动提供，本模块只做判定与告警位）：
 *          ① 静默（stall）：帧序号连续 >= ADC_HEALTH_STALL_MS 无前进；
@@ -8,19 +9,19 @@
 *          ④ 错误计数增量：FRSTDATA 跳变 / HAL ADC·DMA 错误 / STM32 停摆计数。
 *          ⚠ 本层**纯逻辑**：不碰寄存器、不取数、不打日志——输入是调用方
 *            采集的计数快照，输出是故障位；日志与自检上报由消费者
- *            （`App/task/adc_task.c`）按位执行 → 主机侧可单测（L0.5）。
+ *            （`App/task/adc_task.c`）按位执行 → 主机侧可纯逻辑单测。
 * 适用平台：STM32F407ZGTx + TPAFE5160
 * 作者：王建锋
 * 创建日期：2026-10-11
 * 修改记录：
- *   v1.0  2026-10-11  王建锋  创建：L1-6 采样有效性校验（静默/丢帧/单调性/错误增量）
+ *   v1.0  2026-10-11  王建锋  创建：采样有效性校验（静默/丢帧/单调性/错误增量）
 *   v1.1  2026-10-21  王建锋  新增 adc_health_age_stale()（无模块状态的帧年龄
 *                             纯判据，参照系由调用方自存）与 ADC_HF_STALE 位：
 *                             判定层的 stall/backward 位只在 adcTask 每拍跑
 *                             check() 时才可能置起，节拍源停摆会把本任务卡在
 *                             osThreadFlagsWait 上 → 那些位永远是 0，而相量冻在
 *                             最后一帧仍被 protectTask 用于判据。该纯判据让保护侧
- *                             能用**自己的时基 + 中断侧计数器**独立判"数据还新不新" *   v1.2  2026-10-25  DTU 项目组  新增 L5-2 残余「码值越界（贴轨）检出」：
+ *                             能用**自己的时基 + 中断侧计数器**独立判"数据还新不新" *   v1.2  2026-10-25  DTU 项目组  新增 采样通道自检 残余「码值越界（贴轨）检出」：
 *                             adc_health_rail_watch()/rail_sticky()/rail_init()
 *                             ——连续 N 拍贴满量程带且该通道见过释放沿才锁存
 *                             （空载恒 0 / 开机恒 0 是合法工况，不误报）；
@@ -44,7 +45,7 @@ extern "C" {
 #define ADC_HEALTH_STALL_MS   100U

 /* 电平故障位（adc_health_flags()，当前活跃；stall 可自愈清除，backward 锁存）
- * ——供后续 L5-4「自检失败闭锁」直接消费 */
+ * ——供后续「自检失败闭锁」直接消费 */
 #define ADC_HF_TPAFE_STALL    (1uL << 0)   /* TPAFE 帧序号静默 */
 #define ADC_HF_STM32_STALL    (1uL << 1)   /* STM32 DMA 完成计数静默 */
 #define ADC_HF_SEQ_BACKWARD   (1uL << 2)   /* 帧序号倒退（锁存，不自愈） */
@@ -142,7 +143,7 @@ uint8_t adc_health_age_stale(adc_health_age_t *a_p_age, uint32_t a_cur_seq,
 * 入口参数：无
 * 返 回 值：ADC_HF_TPAFE_STALL / ADC_HF_STM32_STALL / ADC_HF_SEQ_BACKWARD 组合
 * 限定条件：无
- * 函数说明：供 L5-4 闭锁判定与 UI；与 check() 出参 flags 同源。
+ * 函数说明：供自检失败闭锁判定与 UI；与 check() 出参 flags 同源。
 */
 uint32_t adc_health_flags(void);

@@ -165,7 +166,7 @@ uint32_t adc_health_sticky(void);
 */
 uint32_t adc_health_tpafe_gaps(void);

-/* ===================== L5-2 残余：码值越界（贴轨）检出，2026-10-25 ===================== */
+/* ===================== 采样通道自检 残余：码值越界（贴轨）检出，2026-10-25 ===================== */

 /* 贴轨锁存的连续拍数：20 拍 = 1 kHz 节拍下一个 50 Hz 周波。削顶/触轨波形的
 * 贴带段持续 ≥ 半周波；噪声毛刺不可能连续 20 拍钉在同侧轨带内（短板评测 §6.2
@@ -185,7 +186,7 @@ uint32_t adc_health_tpafe_gaps(void);
 void adc_health_rail_init(void);

 /*
- * 函数功能：单通道单拍贴轨观察（L5-2 码值越界检出，纯算术）
+ * 函数功能：单通道单拍贴轨观察（采样通道自检 码值越界检出，纯算术）
 * 入口参数：ch     - 通道号（0..ADC_RAIL_CH_NUM-1，越界忽略）  uint8_t
 *           code   - 本拍原始码值（**码值域**，与标定无关）  int32_t
 *           lo_th  - 下轨带上界（code ≤ 此值算贴底）  int32_t
@@ -205,7 +206,7 @@ uint32_t adc_health_rail_watch(uint8_t ch, int32_t code, int32_t lo_th, int32_t
 * 入口参数：无
 * 返 回 值：bit ch = 该通道曾检出贴轨（1 kHz × 9 路 → 低 9 位有效）  uint32_t
 * 限定条件：无
- * 函数说明：供心跳日志 / 后续品质位映射（卡 8/9 的 qds 消费者）只读。
+ * 函数说明：供心跳日志 / 后续品质位映射（遥测快照发布与 104 消费的 qds 消费者）只读。
 */
 uint32_t adc_health_rail_sticky(void);

@@ -1,13 +1,14 @@
 /*
- * 模块名称：ADC 输入层（L1 采集与预处理）
- * 模块功能：语义通道映射（L1-4）+ STM32 ADC1 采样消费（L1-3，TIM3 TRGO 触发 +
+ * 模块名称：ADC 输入层（语义取数与预处理）
+ * 模块功能：语义通道映射（通道语义映射）+ STM32 ADC1 采样消费（STM32 ADC1 启动与扫描，TIM3 TRGO 触发 +
+ *（保护功能清单见 docs/算法/继电保护功能复现规划.md）
 *          DMA 双缓冲）+ TPAFE 快照消费。
 *          消费侧经 adc_input_raw() 按语义取数，不写死下标。
 * 适用平台：STM32F407ZGTx + TPAFE5160
 * 作者：王建锋
 * 创建日期：2026-10-10
 * 修改记录：
- *   v1.0  2026-10-10  王建锋  创建：L1-3（STM32 ADC1 扫描）+ L1-4（语义映射）
+ *   v1.0  2026-10-10  王建锋  创建：STM32 ADC1 启动与扫描（STM32 ADC1 扫描）+ 通道语义映射（语义映射）
 *   v2.0  2026-10-10  王建锋  STM32 侧由"软件触发 + 逐通道轮询"改为
 *                             "TIM3 TRGO 硬件触发 + DMA 双缓冲消费"：本层不再触发
 *                             也不等待转换（消除最坏 2~3 ms 忙等）；新增三个 HAL
@@ -37,7 +38,7 @@
 /* 连续"无新帧"达到该拍数才计一次停摆故障（单拍是相位伪影，见 stm32_take 注释） */
 #define ADC_INPUT_STALL_RUN_MAX     2U

-/* ===== 语义映射表（L1-4）=====
+/* ===== 语义映射表（通道语义映射）=====
 * 权威口径：docs/硬件平台/ADC通道映射说明.md（2026-10-09 硬件确认的语义分配）。
 * index 含义：TPAFE 源 = 驱动 buf 下标 0..7；STM32 源 = ADC1 通道号 0..15。
 * ⚠ 消费侧一律经本表按语义取数，**不得写死下标**（V0.1 有 13/17 路被置换，
@@ -83,7 +84,7 @@ static int      s_stm32_rc;         /* STM32 最近一次扫描状态码 */
 static uint32_t s_stm32_errs;       /* STM32 扫描累计失败次数 */

 /*
- * 函数功能：消费一帧 STM32 ADC1 采样（L1-3，DMA 双缓冲）
+ * 函数功能：消费一帧 STM32 ADC1 采样（STM32 ADC1 启动与扫描，DMA 双缓冲）
 * 入口参数：无
 * 返 回 值：0 - 取到新一帧；-2 - 本拍无新帧（TIM3 未启动 / ADC 停摆 / DMA 出错）
 * 限定条件：仅任务上下文调用；adc_input_init() 已挂好 DMA
@@ -154,7 +155,8 @@ static int stm32_take(void) {
 *          buf[0..7]；② STM32 源的通道号必须出现在 k_stm32_rank_ch[] 中，
 *          否则该通道永远不会被扫描（读到的恒为陈旧值）。这是"通道宏写错 →
 *          读到另一只脚/读不到"这一警告的代码级兜底（警告口径与逐通道验证方法：
- *          docs/硬件平台/ADC通道映射说明.md §5、§8；台架无信号源时注入验证做不了）。
+ *          docs/硬件平台/ADC通道映射说明.md §5、§8。台架注入验证只在台架做一次，
+ *          本自检每次开机都跑，两者不互相替代）。
 */
 static int map_check(void) {
    uint8_t s;
@@ -1,9 +1,10 @@
 /*
- * 模块名称：ADC 输入层（L1 采集与预处理）
+ * 模块名称：ADC 输入层（语义取数与预处理）
 * 模块功能：把两片转换器的原始码值按**语义**（UA/UB/UC/UN/IA/IB/IC/IN/温度）统一
 *          暴露，使上层（UI / 自检 / 保护算法）**按语义取数，不写死下标**：
- *          ① 语义通道映射表（L1-4）——权威口径 docs/硬件平台/ADC通道映射说明.md；
- *          ② STM32 ADC1 9 通道采样（L1-3）——由 **TIM3 TRGO 硬件触发 + DMA 双缓冲
+ *          ① 语义通道映射表（通道语义映射）——权威口径 docs/硬件平台/ADC通道映射说明.md；
+ *（保护功能清单见 docs/算法/继电保护功能复现规划.md）
+ *          ② STM32 ADC1 9 通道采样（STM32 ADC1 启动与扫描）——由 **TIM3 TRGO 硬件触发 + DMA 双缓冲
 *             搬运**，本层只消费、不触发、不等待。
 *          V0.1 上 8 路电气量分属两片转换器（硬件缺陷：双转换器无共同采样触发）：UA/UN/IA 走
 *          TPAFE5160（16 位 / ±5 V 双极性），UB/UC/IB/IC/IN 走 STM32 ADC1
@@ -13,7 +14,7 @@
 * 作者：王建锋
 * 创建日期：2026-10-10
 * 修改记录：
- *   v1.0  2026-10-10  王建锋  创建：L1-3（STM32 ADC1 扫描）+ L1-4（语义映射）
+ *   v1.0  2026-10-10  王建锋  创建：STM32 ADC1 启动与扫描（STM32 ADC1 扫描）+ 通道语义映射（语义映射）
 *   v2.0  2026-10-10  王建锋  STM32 侧改 TIM3 TRGO 硬件触发 + DMA 双缓冲消费：
 *                             消除逐通道轮询的 2 ms 忙等；节拍源 TIM6 -> TIM3
 *                             （换源判据：F4 上 ADC1 收不到 TIM6/TIM7 的 TRGO，见
@@ -1,5 +1,5 @@
 /*
- * 模块名称：频率测量层（L2 派生量）——实现
+ * 模块名称：频率测量层（全周傅氏相量的派生量）——实现
 * 模块功能：见 freq.h。相邻两拍基波相量共轭乘积取角（= 每拍相位增量，免
 *           显式解缠绕）+ **自适应窗长滑动平均** + 瞬时值钳制 + 幅值门。
 *           输入 = phasor 使用区基波相量（UA 优先，UA 无幅值用 IA）。
@@ -1,13 +1,14 @@
 /*
- * 模块名称：频率测量层（L2 派生量，L3-5 过频/低频的测量输入）
- * 模块功能：由 L2 相量使用区的基波相量导出系统频率——相邻两拍基波相量取
+ * 模块名称：频率测量层（全周傅氏相量的派生量，过频 / 低频的测量输入）
+ *（保护功能清单见 docs/算法/继电保护功能复现规划.md）
+ * 模块功能：由 全周傅氏相量使用区的基波相量导出系统频率——相邻两拍基波相量取
 *          **共轭乘积** P = Z(m)·conj(Z(m-1))（其角 = 每拍相位增量，纯音 =
 *          +2πf/Fs，免显式解缠绕），再对**自适应窗长**的相位增量做滑动平均：
 *          K_eff = round(8·Fs/(2·f_hat)) ≈ 泄漏纹波周期 fs/(2f) 的整数倍
 *          -> 非整周波 DFT 负序泄漏造成的 ~10 ms 周期相位纹波相消
 *          （定长窗平均实测扫频误差 0.2~0.32 Hz，自适应窗进入 0.01 Hz 量级，
 *          推导与实测见 freq.c 文件头与 test/host/freq 输出）。
- *          覆盖规划 §3.3 L3-5 的测量侧与 §4.2 测频范围（45~55 Hz 建议段）。
+ *          覆盖规划 §3.3 过频 / 低频 的测量侧与 §4.2 测频范围（45~55 Hz 建议段）。
 *
 * 原理与判据（详见 docs/算法/采集与算法层设计说明.md §7 与 test/host/freq/）：
 *   - 采样率 Fs = 1000 Hz（TIM3 节拍，与 phasor 同源）；45~55 Hz 段每拍
@@ -21,7 +22,7 @@
 *   - 信号源优先级：UA 基波 → IA 基波（UA 无幅值时用 IA，台架只注电流亦可测频）。
 *
 * ⚠ 本层**纯算法**：不碰寄存器、不碰 RTOS、不自己取数（输入 = phasor 使用区）
- *   → 主机侧可免桩单测（L0.5）。
+ *   → 主机侧可免桩纯逻辑单测。
 * 适用平台：STM32F407ZGTx（Cortex-M4F，硬件 FPU）
 * 作者：DTU 项目组
 * 创建日期：2026-10-12（B8）
@@ -49,14 +50,14 @@
 #define FREQ_INST_MIN_HZ  35.0f
 #define FREQ_INST_MAX_HZ  65.0f

-/* 幅值门限（有效值，**二次值 V 口径**，「数据可信」卡 6 重定，依据其 §2.3 表第 1 行）：
+/* 幅值门限（有效值，**二次值 V 口径**，「数据可信」下游常数按工程量重定的结果，依据其 §2.3 表第 1 行）：
 * 低于该值判"无有效波形"。取值 50 V = 0.5×Un（相电压标称 100 V，与
 * App/algo/prot_set.c 头部量纲基准同源）：正常带载 UA 在 0.9~1.1×Un，
 * 50 V 之下只可能是断保险/PT 空载/浮空噪声（浮空实测 ~1.7 V 引脚域、
 * 二次域更小），不会吃掉正常纹波（纹波谷值远大于 0.5×Un）。
- * ⚠ 过渡期行为（eng=0，卡 12 标定前）：帧值还是引脚电压（≤5 V < 50 V），
- * 本门**恒失效** → freq_valid()=0 → OF/UF 按"必不启动"填充复位——与卡 5
- * 未标定闭锁同向（判据链本就停走），不构成额外风险；标定后自动恢复本意。
+ * ⚠ 过渡期行为（eng=0，两点标定完成前）：帧值还是引脚电压（≤5 V < 50 V），
+ * 本门**恒失效** → freq_valid()=0 → OF/UF 按"必不启动"填充复位——与未标定即闭锁
+ * 同向（判据链本就停走），不构成额外风险；标定后自动恢复本意。
 * 数值沿用原 50.0f 属巧合（原为"远小于千级码值"的拟定值），不是漏改。 */
 #define FREQ_AMP_MIN      50.0f

@@ -1,16 +1,17 @@
 /*
- * 模块名称：遥测快照发布层（L2 派生·发布侧，「数据可信」卡 8）
+ * 模块名称：遥测快照发布层（全周傅氏相量派生·发布侧，「数据可信」§4.5）
 * 模块功能：实现见 meas.h——200 ms 基波有效值 + 品质快照，双区无锁读。
 *          本文件纯算法：输入 = sample_ring 取窗 + 调用方注入（频率/削顶位图），
 *          无 RTOS / 无寄存器 / 无日志（「数据可信」层内禁令：本目录不写日志）。
- * 双区不变量（docs/任务规划/数据可信.md §4.5，L2-7 同型，先例 = App/algo/
+ * 双区不变量（docs/任务规划/数据可信.md §4.5，双区指针原子交换 同型，先例 = App/algo/
+ *（保护功能清单见 docs/算法/继电保护功能复现规划.md）
 *          phasor.c 的双区注释）：写侧只碰**非使用区**，全部字段填完后一次
 *          volatile 单字节 store 翻转使用区；读者先取索引再整体拷贝 → 拷贝期
 *          间写者不可能改读者所在区（两帧间隔 200 ms 远大于 72 B 拷贝）。
 *          单核顺序执行，无需内存屏障；volatile 阻编译器把字段写入挪到翻转后。
 * 适用平台：STM32F407ZGTx（Cortex-M4F，硬件 FPU）
 * 作者：DTU 项目组
- * 创建日期：2026-10-25（道D 卡 8）
+ * 创建日期：2026-10-25（道D 遥测快照发布）
 * 修改记录：
 *   v1.0  2026-10-25  DTU 项目组  创建：200 ms 遥测快照 + 双区无锁读
 */
@@ -22,7 +23,7 @@
 #include "phasor.h"       /* phasor_calc()：基波 DFT 纯函数核（与使用区同核） */
 #include "sample_ring.h"  /* sample_ring_window()：以本拍为终止的一周波窗 */

-/* ===== 双区（计算区 / 使用区），口径同 App/algo/phasor.c 的 L2-7 ===== */
+/* ===== 双区（计算区 / 使用区），口径同 App/algo/phasor.c 的 双区指针原子交换===== */
 static meas_snap_t      s_ms_snap[2];
 static volatile uint8_t s_ms_use;
 static uint8_t          s_ms_ready;   /* 使用区是否已产出过有效结果 */
@@ -1,33 +1,34 @@
 /*
- * 模块名称：遥测快照发布层（L2 派生·发布侧，「数据可信」卡 8）
- * 模块功能：每 **200 ms** 从 L2 层取一次基波有效值 + 品质，产出一份全仓唯一的
+ * 模块名称：遥测快照发布层（全周傅氏相量派生·发布侧，「数据可信」§4.5）
+ * 模块功能：每 **200 ms** 从 全周傅氏相量层取一次基波有效值 + 品质，产出一份全仓唯一的
 *          遥测快照（meas_snap_t，布局权威 = docs/任务规划/数据可信.md §4.5），
 *          让 104 与 UI **共用同一份上游**——"什么时候算新值、品质怎么判"只此
- *          一处决定（M5 遥测链的地基；104 改读快照属卡 9，UI 侧 ui_data_feed 属
+ *          一处决定（M5 遥测链的地基；104 侧消费见「数据可信」104 改读快照，UI 侧 ui_data_feed 属
 *          「UI 扩展」波次，两者都只是本快照的读者）。
- *          值口径（批 2 卡 8 的 A-lite 裁决，2026-10-25）：**基波有效值瞬时透传**
- *          （同拍 phasor 使用区口径，系数已在 L1.5 折算进帧值——现单位 = ADC
+ *          值口径（批 2「遥测快照发布」的 A-lite 裁决，2026-10-25）：**基波有效值瞬时透传**
+ *          （同拍 phasor 使用区口径，系数已在 标定折算折算进帧值——现单位 = ADC
 *          引脚电压 V，二次值语义等 adc_cal_flags() 出 VALID，见
 *          docs/算法/采集与算法层设计说明.md §10 红线③）；**不做** 4 点平均 /
 *          谐波方和根——docs/任务规划/数据可信.md §4.5 明示"200 ms 是上送节拍
 *          不是平均窗，再平均引入滞后"；谐波 k-bin 轨（docs/算法/继电保护功能
- *          复现规划.md L2-8）将来扩展时只许在本结构**尾部追加**或留在发布侧
+ *          复现规划.md 遥测谐波轨（可选））将来扩展时只许在本结构**尾部追加**或留在发布侧
+ *（保护功能清单见 docs/算法/继电保护功能复现规划.md）
 *          内部状态，既有字段序不得变更。
 *          TEMP 通道（「数据可信」决策 5：不参与线性标定）：yc = 最新一拍原始
 *          帧值透传，qds 恒置 NT——值在场但非交流量语义，UI 按「数据可信」§4.2
 *          三态表显示占位符，104 无对应点。
 *          并发（docs/任务规划/数据可信.md §4.5 原文口径）：沿用 phasor 的
- *          **双区 + 单字节活跃索引翻转**（L2-7 同型，不是新机制）——写侧填满
+ *          **双区 + 单字节活跃索引翻转**（双区指针原子交换 同型，不是新机制）——写侧填满
 *          计算区后一次 store 翻转，读者先取索引再整体拷贝，全程无锁；
 *          seq 只增，消费者据此判"是否换帧"。
 *          本层**纯算法**：不碰寄存器、不碰 RTOS、不自己取数（窗自 sample_ring、
- *          频率/品质由调用方注入）→ 主机侧免桩单测 test/host/meas/（L0.5）。
+ *          频率/品质由调用方注入）→ 主机侧免桩纯逻辑单测 test/host/meas/。
 * 发布纪律：唯一发布者 = adcTask（在 phasor_run()/freq_run() 之后 200 ms 分频
 *          调 meas_tick()）。评审判据 = 全仓 meas_tick 调用点数 == 1（「数据可信」
 *          §8 风险表"快照双写"行）；其余任务/模块**只读**。
 * 适用平台：STM32F407ZGTx（Cortex-M4F，硬件 FPU）
 * 作者：DTU 项目组
- * 创建日期：2026-10-25（道D 卡 8）
+ * 创建日期：2026-10-25（道D 遥测快照发布）
 * 修改记录：
 *   v1.0  2026-10-25  DTU 项目组  创建：200 ms 遥测快照 + 双区无锁读
 */
@@ -50,19 +51,19 @@ extern "C" {
 /* 每点品质位（uint16）。**低字节与线上 104 QDS 字节同值**（OV/NT/IV，数值
 * 口径同 App/protocol/iec104/iec104_asdu.h 的 IEC104_QDS_*）——但本层**不得**
 * include 协议层头（分层方向：算法层在协议层之下，反向依赖禁止），故在此自
- * 定义同值常量；卡 9 的 104 侧消费直接截低字节上送，一致性由本目录单测与
+ * 定义同值常量；104 侧消费（104 改读快照）直接截低字节上送，一致性由本目录单测与
 * test/host/iec104/ 既有断言双向钉住。高字节为 meas 域扩展位（线上不直接
 * 出现，由消费者映射）： */
-#define MEAS_QDS_OV        (0x0001u)   /* 溢出（留位，卡 8 不产出——判据待运行参数化） */
+#define MEAS_QDS_OV        (0x0001u)   /* 溢出（留位，本项不产出——判据待运行参数化） */
 #define MEAS_QDS_NT        (0x0020u)   /* 非当前值：未就绪 / 语义未处理（TEMP） */
 #define MEAS_QDS_IV        (0x0080u)   /* 无效：该路取窗失败，无有效读数 */
 #define MEAS_QDS_CLIPPED   (0x0100u)   /* 硬件削顶（adc_cal_flags 位图直通，
                                        * 「数据可信」§4.2 三态表；AC 量不可信，
-                                        * 消费者应映射为品质无效，如卡 9 的 104 IV） */
+                                        * 消费者应映射为品质无效，如 104 改读快照侧的 IV） */

 /* 遥测快照（docs/任务规划/数据可信.md §4.5 权威布局；实测 72 B，2×72 ≈ 144 B
- * 双区 = 卡 8 DoD 预算口径，由 test/host/meas/ 的布局钉死用例锁字段偏移——
- * 改字段 = 破协议，须同步卡 9 / UI） */
+ * 双区 = 本项 DoD 预算口径，由 test/host/meas/ 的布局钉死用例锁字段偏移——
+ * 改字段 = 破协议，须同步 104 改读快照 / UI） */
 typedef struct {
    uint32_t seq;                 /* 只增；消费者据此判断是否换帧 */
    uint32_t tick_ms;             /* 发布拍时基（osKernelGetTickCount 原值） */
@@ -1,12 +1,12 @@
 /*
- * 模块名称：相量计算层（L2 相量计算）
+ * 模块名称：相量计算层（全周傅氏相量计算）
 * 模块功能：全周傅氏算法（单频 DFT）——系数表预乘 √2/N，fAmSQ 直接即有效值。
- *          覆盖 L2-1 系数表 / L2-2 实例 / L2-3 有效值 / L2-6 滑动窗 / L2-7 双区交换。
+ *          覆盖 全周傅氏系数表 / 基波相量实例 / 相量有效值输出 / 每 1 ms 滑动窗刷新 / 双区指针原子交换。
 * 适用平台：STM32F407ZGTx（Cortex-M4F，硬件 FPU）
 * 作者：王建锋
 * 创建日期：2026-10-10
 * 修改记录：
- *   v1.0  2026-10-10  王建锋  创建：L2-1/2/3/6/7
+ *   v1.0  2026-10-10  王建锋  创建：全周傅氏系数表 等
 */

 #include "phasor.h"
@@ -16,7 +16,7 @@

 #include "sample_ring.h"

-/* ===== L2-1 全周傅氏系数表 =====
+/* ===== 全周傅氏系数表 =====
 * g_fFFTSin20[k] = sin(2πk/N)·(√2/N)
 * g_fFFTCos20[k] = cos(2πk/N)·(√2/N)      N = PHASOR_N = 20
 * 权威口径：docs/算法/傅氏算法详解.md §2.3（"把 √2 藏进系数表"）。
@@ -41,23 +41,23 @@ static const float k_fft_cos[PHASOR_N] = {
 /* √2：幅值 = √2 × 有效值（与系数表的 √2 折算互逆） */
 #define PHASOR_SQRT2   1.4142135623730951f

-/* ===== L2-2 相量实例表 =====
+/* ===== 基波相量实例表 =====
 * 参考项目为 **4 个实例**（C01 基波 I/U、C02 零序基波、C03 二次谐波、C04 五次谐波，
 * `APP/CLS100_Dsp/InstCalCell.c`）。本项目按 V0.1 **有效通道**（`UA`/`UN`/`IA`，
 * 见 docs/算法/继电保护功能复现规划.md §1.6：`UB/UC/IB/IC/IN` 无中点偏置 → 削顶不可用）展开——C01 的"I/U"
- * 拆为两行（IA 电流 / UA 电压），并补出 C04 的五次谐波轨（L1-9）。
+ * 拆为两行（IA 电流 / UA 电压），并补出 C04 的五次谐波轨（二次谐波/五次谐波提取入口）。
 * 新增实例只需在表尾加一行，其余代码自动适配。 */
 static const phasor_inst_t k_inst[] = {
-    { "C01-IA-F1", ADC_SEM_IA, 1u },    /* A 相电流基波（L3-1 过流 / L3-3 过负荷） */
-    { "C02-UA-F1", ADC_SEM_UA, 1u },    /* A 相电压基波（L3-4 过压/欠压、L3-5 频率） */
-    { "C03-UN-F1", ADC_SEM_UN, 1u },    /* 零序电压基波（L3-6 零序过压） */
-    { "C04-IA-F2", ADC_SEM_IA, 2u },    /* 二次谐波（L3-7 涌流制动） */
-    { "C05-IA-F5", ADC_SEM_IA, 5u },    /* 五次谐波（L1-9 选线） */
+    { "C01-IA-F1", ADC_SEM_IA, 1u },    /* A 相电流基波（三段式相间过流 / 过负荷） */
+    { "C02-UA-F1", ADC_SEM_UA, 1u },    /* A 相电压基波（过压 / 欠压、过频 / 低频） */
+    { "C03-UN-F1", ADC_SEM_UN, 1u },    /* 零序电压基波（零序过压） */
+    { "C04-IA-F2", ADC_SEM_IA, 2u },    /* 二次谐波（涌流制动） */
+    { "C05-IA-F5", ADC_SEM_IA, 5u },    /* 五次谐波（二次谐波/五次谐波提取入口（选线用）） */
 };

 #define PHASOR_INST_N   (sizeof(k_inst) / sizeof(k_inst[0]))

-/* ===== L2-7 双区（计算区 / 使用区）=====
+/* ===== 双区指针原子交换（计算区 / 使用区）=====
 * 本拍结果先写入"计算区"，全部实例写完后**一次性**切换 s_use_zone
 * （单字节 store，Cortex-M 上原子），消费侧读"使用区" → 无锁、无撕裂。
 * s_use_zone 声明 volatile：阻止编译器把结果写入挪到切换之后
@@ -83,7 +83,7 @@ static void phasor_zero(phasor_t *p) {
 }

 /*
- * 函数功能：对 n 点窗口算 harm 次相量（L2-1 系数表 + L2-3 有效值）
+ * 函数功能：对 n 点窗口算 harm 次相量（全周傅氏系数表 + 相量有效值输出）
 * 入口参数：x    - 采样窗（按时间序，旧 → 新）
 *           n    - 窗长（必须等于 PHASOR_N）
 *           harm - 谐波次数（>=1）
@@ -134,7 +134,7 @@ int phasor_init(void) {
 }

 /*
- * 函数功能：取相量实例数（L2-2）
+ * 函数功能：取相量实例数
 * 入口参数：无
 * 返 回 值：实例个数
 * 限定条件：无
@@ -159,7 +159,7 @@ const phasor_inst_t *phasor_inst(uint8_t idx) {
 }

 /*
- * 函数功能：重算全部实例 + 双区原子切换（L2-6 / L2-7）
+ * 函数功能：重算全部实例 + 双区原子切换（每 1 ms 滑动窗刷新 / 双区指针原子交换）
 * 入口参数：无
 * 返 回 值：无
 * 限定条件：仅任务上下文调用；须先 sample_ring_push_frame() 压入本拍数据
@@ -1,18 +1,19 @@
 /*
- * 模块名称：相量计算层（L2 相量计算）
+ * 模块名称：相量计算层（全周傅氏相量计算）
 * 模块功能：全周傅氏（全周波傅里叶）算法——对一周波 20 点采样做单频 DFT，
 *          产出基波/谐波相量。系数表**预乘 √2/N**（口径见
 *          `docs/算法/傅氏算法详解.md` §2.3），故 `fAmSQ = √(fRe²+fIm²)`
 *          **直接就是有效值**，无需再除 √2。
- *          覆盖规划 §3.2：L2-1 系数表 / L2-2 实例 / L2-3 有效值输出 /
- *          L2-6 每 1 ms 滑动窗 / L2-7 双区指针原子交换。
+ *          覆盖规划 §3.2：全周傅氏系数表 / 基波相量实例 / 相量有效值输出 /
+ *（保护功能清单见 docs/算法/继电保护功能复现规划.md）
+ *          每 1 ms 滑动窗刷新 / 双区指针原子交换。
 *          ⚠ 本层**纯算法**：不碰寄存器、不碰任务调度、不自己取数（输入由
- *            `sample_ring` 提供）→ 主机侧可单测（L0.5）。
+ *            `sample_ring` 提供）→ 主机侧可纯逻辑单测。
 * 适用平台：STM32F407ZGTx（Cortex-M4F，硬件 FPU）
 * 作者：王建锋
 * 创建日期：2026-10-10
 * 修改记录：
- *   v1.0  2026-10-10  王建锋  创建：L2-1/2/3/6/7（基波 + 谐波相量）
+ *   v1.0  2026-10-10  王建锋  创建：全周傅氏系数表 等（基波 + 谐波相量）
 */

 #ifndef PHASOR_H
@@ -35,7 +36,7 @@ extern "C" {
 *   fIm   - 虚部 = b1/√2（有效值相量虚部）
 *   fAm   - 幅值 = √2·√(fRe²+fIm²)（正弦峰值 A1）
 *   fAmSQ - 有效值 = √(fRe²+fIm²)（系数已折算 √2/N，故直接即有效值）
- * 相位（L2-4）按需由 `atan2(fIm, fRe)` 导出，不常驻本结构。 */
+ * 相位输出按需由 `atan2(fIm, fRe)` 导出，不常驻本结构。 */
 typedef struct {
    float fRe;
    float fIm;
@@ -43,7 +44,7 @@ typedef struct {
    float fAmSQ;
 } phasor_t;

-/* 相量实例（L2-2）：**数据驱动**——新增实例只需在实例表尾加一行 */
+/* 基波相量实例：**数据驱动**——新增实例只需在实例表尾加一行 */
 typedef struct {
    const char    *name;    /* 实例名（日志 / UI 用） */
    adc_semantic_t sem;     /* 语义通道 */
@@ -60,7 +61,7 @@ typedef struct {
 int phasor_init(void);

 /*
- * 函数功能：取相量实例数（L2-2）
+ * 函数功能：取相量实例数
 * 入口参数：无
 * 返 回 值：实例个数
 * 限定条件：无
@@ -78,7 +79,7 @@ uint8_t phasor_inst_count(void);
 const phasor_inst_t *phasor_inst(uint8_t idx);

 /*
- * 函数功能：重算全部实例并从计算区原子切换到使用区（L2-6 滑动窗 + L2-7 双区交换）
+ * 函数功能：重算全部实例并从计算区原子切换到使用区（每 1 ms 滑动窗刷新 + 双区指针原子交换）
 * 入口参数：无
 * 返 回 值：无
 * 限定条件：仅任务上下文调用；须先经 `sample_ring_push_frame()` 压入本拍数据
@@ -99,7 +100,7 @@ void phasor_run(void);
 int phasor_get(uint8_t idx, phasor_t *out);

 /*
- * 函数功能：对 n 点窗口算 harm 次相量（L2-1 系数表 + L2-3 有效值）
+ * 函数功能：对 n 点窗口算 harm 次相量（全周傅氏系数表 + 相量有效值输出）
 * 入口参数：x    - 采样窗（按时间序，旧 → 新；长度须 = PHASOR_N）
 *           n    - 窗长（必须等于 PHASOR_N）
 *           harm - 谐波次数（>=1）
@@ -1,5 +1,5 @@
 /*
- * 模块名称：保护元件框架（L3，P1 子集）——实现
+ * 模块名称：保护元件框架（保护判据，P1 子集）——实现
 * 模块功能：见 prot_elm.h。判据核 prot_elm_eval() 为纯逻辑（prot_set RAM +
 *           测量数组 → 状态机），prot_elm_run() 是 phasor→测量的薄适配层。
 *
@@ -53,7 +53,7 @@ static const pe_cfg_t k_pe[PE_COUNT] = { /* ← 表头注释见上，行内列
    { "OV-UA",  1u, PE_SRC_PHASOR, PS_OV_EN,  PROT_ELM_NO_TRIP, PS_OV_VOL,  PS_OV_DLY,  PS_RET_OVER,  "C02" },
    { "UV-UA",  0u, PE_SRC_PHASOR, PS_UV_EN,  PROT_ELM_NO_TRIP, PS_UV_VOL,  PS_UV_DLY,  PS_RET_UNDER, "C02" },
    { "3U0-UN", 1u, PE_SRC_PHASOR, PS_3U0_EN, PROT_ELM_NO_TRIP, PS_3U0_VOL, PS_3U0_DLY, PS_RET_OVER,  "C03" },
-    /* 过频/低频（L3-5，B8）：测量量 = freq 层测得频率（Hz），返回系数独立
+    /* 过频/低频（过频 / 低频，B8）：测量量 = freq 层测得频率（Hz），返回系数独立
     * （RET_OF/RET_UF——频率滞回带与电气量不同量级，勿共用 0.95/1.05） */
    { "OF-F",   1u, PE_SRC_FREQ,   PS_OF_EN,  PROT_ELM_NO_TRIP, PS_OF_HZ,   PS_OF_DLY,  PS_RET_OF,    0 },
    { "UF-F",   0u, PE_SRC_FREQ,   PS_UF_EN,  PROT_ELM_NO_TRIP, PS_UF_HZ,   PS_UF_DLY,  PS_RET_UF,    0 },
@@ -136,7 +136,8 @@ void prot_elm_request_reset(void) {
 * 入口参数：now_ms - 单调时基（tick ms，差值法回绕安全）
 *           meas   - PE_COUNT 个测量值（工程量 A/V）；NULL 视为全 0
 * 返 回 值：无
- * 函数说明：投退=0 或定值闭锁（L5-1）→ 状态整体复位、不判据；
+ * 函数说明：投退=0 或定值闭锁（定值校验和）→ 状态整体复位、不判据；
+ *（保护功能清单见 docs/算法/继电保护功能复现规划.md）
 *           滞回 = 已启动用返回门槛（定值×系数）、未启动用动作门槛；
 *           延时 dly=0 → 启动同拍即动作；返回即时（P4 接出口时再补返回延时）。
 */
@@ -203,8 +204,8 @@ void prot_elm_eval(uint32_t now_ms, const float meas[PE_COUNT]) {
 * 函数功能：适配层——按实例表 src 组装测量数组后调判据核
 * 入口参数：now_ms - 单调时基（tick ms）
 * 返 回 值：无
- * 限定条件：仅保护消费者任务上下文；测量已是 L1.5 工程量（未标定域由
- *          protectTask 卡 5 闭锁挡在门外，本函数不感知标定态）
+ * 限定条件：仅保护消费者任务上下文；测量已是 标定折算工程量（未标定域由
+ *          protectTask 未标定即闭锁挡在门外，本函数不感知标定态）
 * 函数说明：src=PHASOR 行任一相量未就绪（未满一周波）→ **整拍跳过**，
 *           不引入陈旧/半新测量（B5 口径）。src=FREQ 行：freq 有有效读数
 *           （started 且幅值门 OK）→ 填测得频率；否则按方向填"必不启动"值
@@ -259,7 +260,7 @@ void prot_elm_state(prot_elm_id_t id, prot_elm_state_t *out) {
 /*
 * 函数功能：聚合动作位图
 * 入口参数：无
- * 返 回 值：bit i = 元件 i asserted（供 L4 出口 / 心跳日志）
+ * 返 回 值：bit i = 元件 i asserted（供 出口与记录 / 心跳日志）
 */
 uint32_t prot_elm_active_mask(void) {
    uint32_t mask = 0u;
@@ -1,15 +1,16 @@
 /*
- * 模块名称：保护元件框架（L3，P1 子集）
+ * 模块名称：保护元件框架（保护判据，P1 子集）
 * 模块功能：通用"越限 + 返回系数滞回 + 定时限"元件核 + 实例表（数据驱动，
 *           同 phasor 实例表模式）。判据为**纯逻辑**（吃测量值 + 定值），
- *           主机侧可离线单测；出口/SOE（L4）与任务编排为后续。
+ *           主机侧可离线单测；出口/SOE（出口与记录）与任务编排为后续。
 *
 * V0.1 有效实例（双转换器无共同采样触发 → 仅 TPAFE 三路）：
- *   OC1/OC2/OC3 三段式相间过流（A 相 IA，L3-1）
- *   OL          过负荷（A 相 IA，L3-3）
- *   OV/UV       过压/欠压（UA，L3-4）
- *   3U0         零序过压（UN 外部零序电压通道，L3-6）
- *   OF/UF       过频/低频（测量量 = freq 层测得频率，L3-5，B8 落地）
+ *   OC1/OC2/OC3 三段式相间过流（A 相 IA）
+ *（保护功能清单见 docs/算法/继电保护功能复现规划.md）
+ *   OL          过负荷（A 相 IA）
+ *   OV/UV       过压/欠压（UA，过压 / 欠压）
+ *   3U0         零序过压（UN 外部零序电压通道）
+ *   OF/UF       过频/低频（测量量 = freq 层测得频率，过频 / 低频，B8 落地）
 *
 * 测量数组口径：相量类实例 = 基波有效值（A/V）；OF/UF = 测得频率（Hz）。
 *   run() 按实例表 src 字段取数（0=phasor rms，1=freq）。freq 无有效读数
@@ -22,9 +23,9 @@
 *   - 返回**即时**（参考 GRly_TimeRelay 带 10 ms 返回延时——V0.1 无出口硬件，
 *     抖动只影响日志，P4 接出口时再补返回延时）；
 *   - 复压/方向/无压无流闭锁（dwSetFyCtrl 类）随 P2/P3 元件扩展；
- *   - 测量输入 = adc_task 经 adc_cal_apply() 折算后的工程量（L1.5，卡 2 已落地）：
+ *   - 测量输入 = adc_task 经 adc_cal_apply() 折算后的工程量（标定折算，标定折算已落地）：
 *     未标定（VALID=0）时单位只是 ADC 引脚电压——该域下判据必然错配，由
- *     protectTask 的未标定闭锁（卡 5）停走整条判据链，元件核本身不掺和
+ *     protectTask 的「数据可信」未标定即闭锁停走整条判据链，元件核本身不掺和
 *     标定语义（保持纯逻辑）；标定后单位 = 二次值，定值口径才名副其实。
 *
 * 线程约定：init 内核启动前或保护消费者任务上下文；eval/run 仅保护消费者任务
@@ -48,8 +49,8 @@ typedef enum {
    PE_OV,        /* 过压（UA） */
    PE_UV,        /* 欠压（UA，欠量方向） */
    PE_3U0,       /* 零序过压（UN） */
-    PE_OF,        /* 过频（测量量 = freq 层测得频率，B8，L3-5） */
-    PE_UF,        /* 低频（测量量 = freq 层测得频率，欠量方向，B8，L3-5） */
+    PE_OF,        /* 过频（测量量 = freq 层测得频率，B8，过频 / 低频） */
+    PE_UF,        /* 低频（测量量 = freq 层测得频率，欠量方向，B8，过频 / 低频） */
    PE_COUNT
 } prot_elm_id_t;

@@ -81,7 +82,7 @@ void prot_elm_request_reset(void);
 *           meas   - PE_COUNT 个测量值（工程量：A / V），NULL 视为全 0
 * 返 回 值：无
 * 限定条件：仅保护消费者任务上下文；调用方保证定值已装载
- * 函数说明：越限方向由实例表决定；投退=0 或定值闭锁（L5-1）→ 状态复位、
+ * 函数说明：越限方向由实例表决定；投退=0 或定值闭锁（定值校验和）→ 状态复位、
 *           不判据。延时判定用 (uint32_t)(int32_t)(now - t0) >= dly，回绕安全。
 */
 void prot_elm_eval(uint32_t now_ms, const float meas[PE_COUNT]);
@@ -97,7 +98,7 @@ void prot_elm_run(uint32_t now_ms);
 /* 状态快照拷贝（NULL 安全；越界全零） */
 void prot_elm_state(prot_elm_id_t id, prot_elm_state_t *out);

-/* 动作位图（bit i = 元件 i asserted），供 L4 出口 / 心跳日志 */
+/* 动作位图（bit i = 元件 i asserted），供 出口与记录 / 心跳日志 */
 uint32_t prot_elm_active_mask(void);

 /* 启动位图（bit i = 元件 i picked），供「保护启动」记录边沿（task-10，2026-10-26）：
@@ -1,16 +1,17 @@
 /*
- * 模块名称：保护定值模型（P1，L5-1 载体）——实现
+ * 模块名称：保护定值模型（P1，定值校验和 载体）——实现
+ *（保护功能清单见 docs/算法/继电保护功能复现规划.md）
 * 模块功能：见 prot_set.h。纯逻辑，零平台依赖（仅 stdint.h + 自身头）。
 *
 * ⚠ 默认值/范围为拟定值（参考 EEPROM 出厂默认表不在本仓库，规划 §10.3 待补）；
 *   通讯地址逐项对照参考 Comm/Pub/Const_CommSetPara.c g_tCommSetParaTab。
 *
- * 量纲口径（「数据可信」卡 6 复核，2026-10-25）：A/V 项 = **二次值**工程量，
+ * 量纲口径（「数据可信」下游常数按工程量重定一项复核，2026-10-25）：A/V 项 = **二次值**工程量，
 *   标称基准 100 V / 1 A（UA/UB/UC 相电压、3U0、OV/UV 同域——OV 120 = 1.2×Un、
 *   UV 20 = 0.2×Un、3U0 15 = 0.15×Un；OC1/2/3 = 10/5/2 ×Ir、OL = 1.0×Ir，
 *   三段递升与过负荷低于速断均自洽）。ADC 帧仅在 adc_cal VALID 置位后才处
- *   于此域（未标定 = 引脚电压域，由卡 5 闭锁停走判据，见 protect_task.c）；
- *   min/max 范围覆盖 0~4×标称，无需随本卡改动数值——换算依据与三处下游
+ *   于此域（未标定 = 引脚电压域，由未标定即闭锁停走判据，见 protect_task.c）；
+ *   min/max 范围覆盖 0~4×标称，无需随这一项改动数值——换算依据与三处下游
 *   常数同源，见 docs/任务规划/数据可信.md §2.3。
 *
 * 创建日期：2026-10-11
@@ -55,7 +56,7 @@ const prot_set_meta_t g_prot_set_meta[PS_ID_COUNT] = {
    { 0x8825, 0u,  PROT_SET_Q10(100.0),  PROT_SET_Q10(1.0),  PROT_SET_Q10(10000.0) },
    { 0x8826, 0u,  PROT_SET_Q10(5.0),    PROT_SET_Q10(1.0),  PROT_SET_Q10(10.0) },
    { 0x0000, 1u,  PROT_SET_Q10(1),      0,             PROT_SET_Q10(1)      }, /* 全局软压板投退（YK12，B7） */
-    /* --- 过频 / 低频（L3-5，B8）：地址全 0 = 本地项（参考逐项地址不在
+    /* --- 过频 / 低频（B8）：地址全 0 = 本地项（参考逐项地址不在
     *     本仓库，规划 §5.1 仅示"8820~8882 含低压/低频"类目）；
     *     默认值/范围**拟定**（DTU 馈线典型量级），待对照参考出厂表修订 --- */
    { 0x0000, 1u,  PROT_SET_Q10(1),      0,             PROT_SET_Q10(1)      }, /* OF 投退（本地） */
@@ -75,7 +76,7 @@ static volatile uint8_t s_act;           /* 活跃区下标（0/1）；交换 =
 static uint32_t s_sum;                   /* 封存的正码 */
 static uint32_t s_sumn;                  /* 封存的反码 */
 static uint64_t s_bad_mask;              /* load_raw/parse 越界位图（B8：40 项 → 64 位） */
-static uint8_t  s_locked;                /* 定值非法 → 闭锁（L5-1） */
+static uint8_t  s_locked;                /* 定值非法 → 闭锁（定值校验和） */
 static uint8_t  s_dirty;                 /* 未落盘定值改动（B7 持久化脏标志） */

 /*
@@ -293,7 +294,7 @@ void prot_set_seal(void) {
 }

 /*
- * 函数功能：定值自检（L5-1）——重算 sum32 并与封存值比对
+ * 函数功能：定值自检（定值校验和）——重算 sum32 并与封存值比对
 * 入口参数：无
 * 返 回 值：0 通过 / -1 失配（已置闭锁）
 * 函数说明：失配 → s_locked 置位并保持，直到下一次 seal；
@@ -1,5 +1,5 @@
 /*
- * 模块名称：保护定值模型（P1，L5-1 载体）
+ * 模块名称：保护定值模型（P1，定值校验和 载体）
 * 模块功能：保护定值的 RAM 模型——编号 / 通讯地址 / 范围 / 默认值 / 校验和自检，
 *           以及 B7 定值持久化的**纯逻辑层**（blob 序列化/解析 + 原子装载）。
 *           文件读写胶水在 App/cfg/prot_set_store.c（MCU 端）。
@@ -8,7 +8,7 @@
 *   - 定点存储：Q10（×1024），与参考系统定点系数 2^10 一致（§5.3）；
 *   - 通讯地址：与参考 g_tCommSetParaTab（Comm/Pub/Const_CommSetPara.c）逐项对齐，
 *     基址 0x8820（=34848）；告警类沿用运行参数段 0x8027/0x8029；
- *   - 校验和（L5-1）：sum32 正码 + 反码成对封存（参考 tagPRS 的
+ *   - 校验和（定值校验和）：sum32 正码 + 反码成对封存（参考 tagPRS 的
 *     dwTagSum/dwTagSumN 模式），selfcheck 失配 → 置闭锁；
 *   - ⚠ 默认值/范围为**拟定值**：参考 EEPROM 出厂默认表未在本仓库，
 *     待对照后逐项修订（规划 §10.3 待补项）；范围先按 DTU 馈线典型量级。
@@ -36,7 +36,7 @@

 /* 定值项编号（枚举序 = RAM 数组序 = 校验和覆盖序，只增不删不改序） */
 typedef enum {
-    /* --- 三段式相间过流（A 相，L3-1）：投退/跳闸投退/电流/延时 --- */
+    /* --- 三段式相间过流（A 相）：投退/跳闸投退/电流/延时 --- */
    PS_OC1_EN = 0,   /* 0x8856 Ⅰ段投退 */
    PS_OC1_TRIP,     /* 0x8857 Ⅰ段跳闸投退（0 告警 / 1 跳闸） */
    PS_OC1_CUR,      /* 0x8858 Ⅰ段电流定值（A，二次值） */
@@ -49,19 +49,19 @@ typedef enum {
    PS_OC3_TRIP,     /* 0x885F */
    PS_OC3_CUR,      /* 0x8860 */
    PS_OC3_DLY,      /* 0x8861 */
-    /* --- 过负荷（A 相，L3-3） --- */
+    /* --- 过负荷（A 相） --- */
    PS_OL_EN,        /* 0x8871 */
    PS_OL_TRIP,      /* 0x8872 */
    PS_OL_CUR,       /* 0x8873 */
    PS_OL_DLY,       /* 0x8874 */
-    /* --- 过压 / 欠压（UA，L3-4；沿用参考告警段 0x8029/0x8027） --- */
+    /* --- 过压 / 欠压（UA；沿用参考告警段 0x8029/0x8027） --- */
    PS_OV_EN,        /* 本地投退（参考告警类无独立投退，V0.1 补） */
    PS_OV_VOL,       /* 0x8029 过电压门限（V，二次值） */
    PS_OV_DLY,       /* 0x802A 过电压延时（ms） */
    PS_UV_EN,        /* 本地投退 */
    PS_UV_VOL,       /* 0x8027 低电压门限（V，二次值） */
    PS_UV_DLY,       /* 0x8028 低电压延时（ms） */
-    /* --- 零序过压（UN，L3-6） --- */
+    /* --- 零序过压（UN） --- */
    PS_3U0_EN,       /* 0x888E */
    PS_3U0_VOL,      /* 0x888F 3U0 定值（V，二次值） */
    PS_3U0_DLY,      /* 0x8890 延时（ms） */
@@ -74,7 +74,7 @@ typedef enum {
    PS_CT_SEC,       /* 0x8826 CT 二次额定（A） */
    /* --- 全局软压板（B7）：104 YK12 两段式投退；0 = 保护退出服务 --- */
    PS_GLOBAL_EN,    /* 本地项（无通讯地址，经 YK12 写、C_RD 不可读） */
-    /* --- 过频 / 低频（L3-5，B8）：投退/动作频率/延时 + 各自返回系数 ---
+    /* --- 过频 / 低频（B8）：投退/动作频率/延时 + 各自返回系数 ---
     * ⚠ 通讯地址：参考 g_tCommSetParaTab 的保护定值段（0x8820~0x8882）
     *   含"低压/低频"类目（规划 §5.1），但 OF/UF 的**逐项地址不在本仓库**
     *   （参考 Comm 源文件未随仓库提供）→ 按"找不到对应即本地项"规则全部
@@ -130,7 +130,7 @@ int32_t prot_set_get(prot_set_id_t id);          /* Q10 原值 */
 float   prot_set_get_f(prot_set_id_t id);        /* 工程量浮点 */
 uint8_t prot_set_get_ctl(prot_set_id_t id);      /* 投退项：!=0 视为投入 */

-/* 校验和（L5-1）：sum32 覆盖 RAM 值区；seal 封存正/反码对 */
+/* 校验和（定值校验和）：sum32 覆盖 RAM 值区；seal 封存正/反码对 */
 uint32_t prot_set_checksum(void);
 void     prot_set_seal(void);
 /* 自检：重算并与封存值比对，失配 → 置闭锁并返回 -1（已闭锁也返回 -1） */
@@ -1,13 +1,13 @@
 /*
- * 模块名称：运行参数段（L2/L3 整定层，「数据可信」卡 10）——实现
- * 模块功能：见 run_par.h。工厂默认 = 「数据可信」卡 6 额定 0.5 % 档（电压 500
+ * 模块名称：运行参数段（全周傅氏相量/保护判据整定层，「数据可信」这一项）——实现
+ * 模块功能：见 run_par.h。工厂默认 = 「数据可信」下游常数按工程量重定后的额定 0.5 % 档（电压 500
 *           mV / 电流 5 mA / 频率 500 mHz，毫单位 int32 定点落盘）；[run_par]
 *           段 9 键（db_ua…db_freq，均 ≤15 字符）≤ CFG_FILE_MAX_KEYS 不拆段
 *           （通道系数覆盖**不落本段**——直通 adc_cal 的 [adc_cal]/[adc_cal_ofs]，
 *           系数唯一真源在那两段，lead 裁②a）。
 * 适用平台：STM32F407ZGTx（Cortex-M4F，硬件 FPU）
 * 作者：DTU 项目组
- * 创建日期：2026-10-25（道D 卡 10）
+ * 创建日期：2026-10-25（道D 运行参数段）
 * 修改记录：
 *   v1.0  2026-10-25  DTU 项目组  创建：[run_par] 段 + 104 映射 + 直通 adc_cal
 *                                 + B7 式脏标志落盘请求
@@ -52,7 +52,7 @@ typedef struct {
 } run_par_db_t;

 static const run_par_db_t s_db_rom = {
-    { 500L, 500L, 500L, 500L,     /* UA/UB/UC/UN：0.5 V（卡 6 额定档） */
+    { 500L, 500L, 500L, 500L,     /* UA/UB/UC/UN：0.5 V（工程量重定后的额定档） */
      5L, 5L, 5L, 5L,             /* IA/IB/IC/IN：0.005 A */
      500L }                      /* 频率：0.5 Hz（绝对档，非额定百分比） */
 };
@@ -77,10 +77,21 @@ static uint8_t s_dirty;

 /* 内部函数实现区 */

+/*
+ * 函数功能：毫单位定点 → 工程量浮点（**本模块唯一换算点**）
+ * 入口参数：milli - 毫单位  内 int32_t
+ * 返 回 值：工程量  内 float
+ * 限定条件：仅本文件内使用（消费侧一律走 run_par_deadband()/run_par_db_range()，
+ *          不许各自再写一次 /1000——那才是"第二真源"最常见的样子）
+ */
+static float s_milli_to_eng(int32_t milli) {
+    return (float)milli / 1000.0f;
+}
+
 /*
 * 函数功能：死区点量程上限（毫单位）
 * 入口参数：idx - 0..8  uint8_t
- * 返 回 值：上限；idx 越界返 0 长（一切值皆拒） 内 int32_t
+ * 返 回 值：上限；idx 越界返 0 内 int32_t
 */
 static int32_t s_db_cap_milli(uint8_t idx) {
    if (idx < 4u) {
@@ -156,7 +167,29 @@ float run_par_deadband(uint8_t idx) {
    if (idx >= RUN_PAR_DB_N) {
        return 0.0f;
    }
-    return ((float)s_db.db[idx]) / 1000.0f;   /* 毫→工程唯一换算点 */
+    return s_milli_to_eng(s_db.db[idx]);    /* 毫→工程：唯一换算点 = s_milli_to_eng */
+}
+
+/*
+ * 函数功能：取第 idx 路死区的合法域（工程量）——**合法域的唯一出口**
+ * 入口参数：idx - 0..8  uint8_t；lo/hi - 输出下限/上限（工程量 V/A/Hz）  float *
+ * 返回值：0 - 已写出；-1 - idx 越界或指针为空（调用方不得回退成自造默认域）  int
+ * 限定条件：任意上下文（纯常量读，无锁、无 I/O）
+ * 函数说明：为什么公开这个口：UI 整定页要给数字编辑器设 min/max，而这些上限的
+ *          真源是本模块的 RUN_PAR_DB_MAX_*（电压 50V / 电流 1A / 频率 5Hz，
+ *          "额定 × 二档裕量"）。页面里抄一份就是第二真源——判据「不新增第二份
+ *          真源」最典型的复发形态是"顺手把常量写进界面代码"。因此本函数的
+ *          消费者是装配层 App/app/ui_data_feed.c 的注入表实现，不是页面本身。
+ *          ⚠ 给的是**粗守域**（挡误写），不是工况域；真提交仍由 s_db_check
+ *          同源守卫裁（104 选择段与 UI 编辑器共用同一批常量，不会漂移）。
+ */
+int run_par_db_range(uint8_t idx, float *lo, float *hi) {
+    if ((idx >= RUN_PAR_DB_N) || (lo == NULL) || (hi == NULL)) {
+        return -1;
+    }
+    *lo = 0.0f;
+    *hi = s_milli_to_eng(s_db_cap_milli(idx));
+    return 0;
 }

 /*
@@ -198,19 +231,74 @@ int run_par_104_read(uint32_t addr, float *out) {
 }

 /*
- * 函数功能：104 运行参数地址写（两段式；k/b 直通 adc_cal_set——**run_par 不存
+ * 函数功能：写某路系数 k（µV/码）**并在同一函数内置脏**——整定的语义写入口
+ * 入口参数：sem - 电气语义通道  adc_semantic_t；k_uv - 系数（µV/码，>0）  float
+ * 返回值：0 - RAM 副本已写 + 已置脏；-1 - 粗守或执行段拒（副本未动、不置脏）  int
+ * 限定条件：整定路径上下文（iec104Task 的 104 执行段；UI 经 ui_data_yt_ops_t 由
+ *          装配层 App/app/ui_data_feed.c 转进来）。勿在 adcTask 调用
+ * 函数说明：**为什么"写值 + 置脏"必须长在一个函数里**（lead 裁②，2026-10-27）：
+ *          置脏是持久化承诺，写值是 RAM 事实，两者拆开就会出现"屏上已改、盘上
+ *          永不落、且没有任何错误返回"这种无人报错的状态——本仓今天已实测到它的
+ *          既有形态（绕过本模块直调 adc_cal_set() 的写者不置脏，值永远不落盘，
+ *          另立 task-43 处置）。所以这里不提供单独的 mark_dirty 公开口：它一旦
+ *          存在就一定有人只调它（同"零消费者的状态查询口"那条教训）。
+ *          零点 b 走 RMW 取**当前生效值**（经合法带哨兵，天然满足再写校验）。
+ *          粗守（0 < k ≤ RUN_PAR_K_MAX_UV）只为挡误写，真带在 adc_cal 执行段裁：
+ *          两层各说各的，页面上"合法域内仍被拒(ERR)"就是执行段拒的，不伪装。
+ */
+int run_par_cal_k_set(adc_semantic_t sem, float k_uv) {
+    int32_t k_q16;
+    int32_t b_codes;
+
+    /* 通道号不在这里判：adc_cal_set 自带合法性与合法带裁决（越界一律 -1），
+     * 本层再判一次就是第二真源。粗守只挡误写：0 < k ≤ RUN_PAR_K_MAX_UV */
+    if (!isfinite(k_uv) || !(k_uv > 0.0f) || (k_uv > RUN_PAR_K_MAX_UV)) {
+        return -1;
+    }
+    k_q16   = (int32_t)lrintf(k_uv * 65536.0f);
+    b_codes = (int32_t)lrintf(adc_cal_b_codes(sem));
+    if (adc_cal_set(sem, k_q16, b_codes) != 0) {
+        return -1;    /* 执行段拒：副本未动，脏位也不置 = 不承诺任何持久化 */
+    }
+    s_dirty = 1u;
+    return 0;
+}
+
+/*
+ * 函数功能：写某路零点偏移 b（码值）并置脏（与 k 同款语义，粗守 ±1e6 码）
+ * 入口参数：sem - 电气语义通道  adc_semantic_t；b_codes - 零点（码值）  int32_t
+ * 返回值：0 - 已写并置脏；-1 - 粗守或执行段拒（副本未动、不置脏）      int
+ * 限定条件：同 run_par_cal_k_set()
+ * 函数说明：k 侧 RMW 用当前生效值；±8192 真带由 adc_cal 执行段裁（粗守目的是
+ *          挡误写不是限工况）。本函数的消费者 = 104 的 0x8048~ 分支（改造后），
+ *          不是"为将来预留"的口
+ */
+int run_par_cal_b_set(adc_semantic_t sem, int32_t b_codes) {
+    int32_t k_q16;
+
+    if (((float)b_codes < -1.0e6f) || ((float)b_codes > 1.0e6f)) {
+        return -1;
+    }
+    k_q16 = (int32_t)lrintf(adc_cal_k_uv(sem) * 65536.0f);
+    if (adc_cal_set(sem, k_q16, b_codes) != 0) {
+        return -1;
+    }
+    s_dirty = 1u;
+    return 0;
+}
+
+/*
+ * 函数功能：104 运行参数地址写（两段式；k/b 经本模块语义 setter——**run_par 不存
 *           系数**，系数唯一真源 = [adc_cal]/[adc_cal_ofs]，lead 裁②a）
 * 返 回 值：0 接受 / -1 拒绝 / -2 非本段（调用方落 prot_set）  int
 * 函数说明：选择段 = 校验不提交（死区走与 set 同源守卫；k/b 的 adc_cal 合法带
 *           由执行段裁决——IEC104 允许执行段 PN，两段结果可不一致，注释在此
- *           明说防"选择过了怎么还 PN"的现场困惑）；k/b 单侧写 RMW 用**当前
- *           生效值**做另一侧（生效值经合法带哨兵，天然满足再写校验）。
+ *           明说防"选择过了怎么还 PN"的现场困惑）。k/b 两支自 2026-10-27 起一律
+ *           走 run_par_cal_k_set() / run_par_cal_b_set()：写值与置脏在同一个函数
+ *           里发生，本函数不再自己碰 s_dirty（lead 裁②：消除两份置脏逻辑）。
 */
 int run_par_104_write(uint32_t addr, float v, uint8_t select) {
    uint8_t slot;                /* 每个命中分支先赋值再使用（无未init读路径） */
-    int32_t k_q16;
-    int32_t b_codes;
-    int     rc;

    if ((addr >= RUN_PAR_IOA_DB0) && (addr < RUN_PAR_IOA_DB0 + RUN_PAR_DB_N)) {
        int32_t milli;
@@ -234,29 +322,20 @@ int run_par_104_write(uint32_t addr, float v, uint8_t select) {
        if (select != 0u) {
            return 0;   /* 粗守过了 ≠ 执行必过：合法带裁决在执行段（见函数头） */
        }
-        k_q16   = (int32_t)lrintf(v * 65536.0f);
-        b_codes = (int32_t)lrintf(adc_cal_b_codes((adc_semantic_t)slot));
-        rc = adc_cal_set((adc_semantic_t)slot, k_q16, b_codes);
-        if (rc == 0) {
-            s_dirty = 1u;
-        }
-        return rc;
+        /* 写值 + 置脏收进语义 setter（粗守 0<k≤上限 也在里面，与本支
+         * 原先那条逐字同值守卫一致，行为不变）*/
+        return run_par_cal_k_set((adc_semantic_t)slot, v);
    }
    if ((addr >= RUN_PAR_IOA_B0) && (addr < RUN_PAR_IOA_B0 + RUN_PAR_CH_N)) {
        slot = (uint8_t)(addr - RUN_PAR_IOA_B0);
-        if (!isfinite(v) || (v < -1000000.0f) || (v > 1000000.0f)) {
-            return -1;             /* 粗守 ±1e6 码；±8192 真带由 adc_cal 执行段裁 */
+        if (!isfinite(v)) {
+            return -1;             /* NaN/Inf 不得进 lrintf（该转换是 UB） */
        }
        if (select != 0u) {
            return 0;
        }
-        b_codes = (int32_t)lrintf(v);
-        k_q16   = (int32_t)lrintf(adc_cal_k_uv((adc_semantic_t)slot) * 65536.0f);
-        rc = adc_cal_set((adc_semantic_t)slot, k_q16, b_codes);
-        if (rc == 0) {
-            s_dirty = 1u;
-        }
-        return rc;
+        /* 同款语义 setter：粗守 ±1e6 码在 setter 内，±8192 真带由 adc_cal 执行段裁 */
+        return run_par_cal_b_set((adc_semantic_t)slot, (int32_t)lrintf(v));
    }
    return -2;
 }
@@ -275,6 +354,9 @@ uint8_t run_par_dirty_peek(void) {
 * 限定条件：defaultTask（配置引擎属主）上下文，SYS_EVT_RUN_PAR_SAVE 驱动
 * 函数说明：一次 save 同时覆盖 [run_par] 9 键与刚被 adc_cal_set 改写的
 *          [adc_cal]/[adc_cal_ofs] 副本（lead 裁②：一条事件位一次 save）。
+ *          成功路径上给标定层盖一次落盘水位（adc_cal_note_persisted()）——它是
+ *          **观测回执**，不参与本函数任何判定；失败路径不盖，于是"save 一直失败"
+ *          在标定层侧表现为差额长期不归零（道G task-43 第②项）。
 */
 int run_par_store_save(void) {
    if (s_dirty == 0u) {
@@ -285,5 +367,6 @@ int run_par_store_save(void) {
        return -1;
    }
    s_dirty = 0u;
+    adc_cal_note_persisted();   /* 观测回执：水位追平，差额归零（不是判定输入） */
    return 0;
 }
@@ -1,17 +1,17 @@
 /*
- * 模块名称：运行参数段（L2/L3 整定层，「数据可信」卡 10）
+ * 模块名称：运行参数段（全周傅氏相量/保护判据整定层，「数据可信」这一项）
 * 模块功能：遥测死区（9 点）与通道标定系数覆盖（k/b 各 8 路）的**单一真源**：
 *           - 死区 = 本模块 int32 毫单位 RAM 副本（注册进 cfg 引擎 [run_par] 段，
- *             工厂默认 = 「数据可信」卡 6 额定 0.5 % 档），104 消费侧
+ *             工厂默认 = 「数据可信」下游常数按工程量重定后的额定 0.5 % 档），104 消费侧
 *             （App/protocol/iec104/iec104_pts.c）每拍实时读取——无投递、无缓存
- *             副本（卡 9 曾在 pts 侧留运行时副本 s_yc_db，卡 10 落地后收编于此，
+ *             副本（104 改读快照曾在 pts 侧留运行时副本 s_yc_db，运行参数段落地后收编于此，
 *             双源必打架）；
 *           - 系数覆盖 = **直通 adc_cal_set()**（[adc_cal]/[adc_cal_ofs] 是系数
- *             唯一真源，卡 4 已定；本模块只加 104 地址映射 + 落盘请求，不另存
+ *             唯一真源，标定落盘与整定入口已定；本模块只加 104 地址映射 + 落盘请求，不另存
 *             一份系数——同 D1 裁"两处判断必打架"逻辑）。
 *           104 地址映射（docs/算法/继电保护功能复现规划.md §5.1 运行参数类
 *           0x8020H~0x8058H；逐项表原文"待补"（参考项目 CommPara_ConfigTable
- *           不在仓），本表即卡 10 的落实，送检点表若另给权威地址只改常量段：
+ *           不在仓），本表即运行参数段的落实，送检点表若另给权威地址只改常量段：
 *             0x8030~0x8038 = 死区 UA/UB/UC/UN/IA/IB/IC/IN/FREQ（工程量 V/A/Hz）；
 *             0x8040~0x8047 = k 覆盖（µV/码）；0x8048~0x804F = b 覆盖（码值，可负）；
 *             其余留白（未启用类别），**0x8027~0x802A 属 prot_set 告警段**，本表
@@ -22,6 +22,18 @@
 *           保存（含 [run_par] 与刚被 adc_cal_set 改写的 [adc_cal]/[adc_cal_ofs]
 *           副本）→ 成功清脏；失败留脏 = 下轮天然重试。本模块自身零文件 IO
 *           （属主纪律）。
+ *           ⚠ 三份职责别混（道G task-43 第③项，此前只有意图式陈述）：
+ *           - **谁写 RAM**：系数/零点的唯一真源是 adc_cal 的引擎副本，而本模块那两支
+ *             语义 setter（run_par_cal_k_set / run_par_cal_b_set，task-7 落地）是**唯一
+ *             "写值 + 置脏"成对发生**的入口；任何消费者绕过它们直调 adc_cal_set()，
+ *             值只进 RAM、脏标志不动 ⇒ 屏上"当前生效"是新的、盘上仍是旧的、重启即丢，
+ *             且该路径**没有错误返回**。这条形态现在可观测：adc_cal 侧
+ *             set_ok 与落盘水位的差额 > 0，而 run_par_dirty_peek() 恒为 0。
+ *           - **谁落盘 / 什么时机**：只有 defaultTask 的 run_par_store_save()（由
+ *             iec104Task peek 后置的 SYS_EVT_RUN_PAR_SAVE 驱动）；本模块零文件 IO。
+ *           - **cfg_file_poll() 不是保存路径**：它的方向是**盘 → RAM 的重载**（外部
+ *             改档 → 沉降去抖 → 重载），拿它"兜住"未落盘的改值会把 FTP 侧的旧档倒灌
+ *             回 RAM，比不兜更坏。设计依据见 docs/算法/采集与算法层设计说明.md §10.1。
 * 并发契约：引擎副本 int32 对齐字读写在 Cortex-M4 上原子；poll 重载 µs 级窗口
 *           为「数据可信」§4.4 明载设计（adc_cal 同款）。写路径 = 104 执行段
 *           （iec104Task）与引擎读路径互不加锁，勿改成"读侧缓存"（缓存 = 新真源）。
@@ -29,10 +41,22 @@
 *           接口级）→ 主机侧可单测（test/host/run_par，链真 cfg 引擎 + 真 adc_cal）。
 * 适用平台：STM32F407ZGTx（Cortex-M4F，硬件 FPU）
 * 作者：DTU 项目组
- * 创建日期：2026-10-25（道D 卡 10）
+ * 创建日期：2026-10-25（道D 运行参数段）
 * 修改记录：
 *   v1.0  2026-10-25  DTU 项目组  创建：[run_par] 段 + 104 地址映射 + 直通
 *                                 adc_cal + B7 式脏标志落盘请求
+ *   v1.1  2026-10-27  DTU 项目组  道F task-7（遥测整定两页）配套：新增语义
+ *                                 setter run_par_cal_k_set / run_par_cal_b_set
+ *                                 （写值 + 置脏成对；104 的 k/b 两支同批改调它，
+ *                                 消除两份置脏逻辑）+ 合法域唯一出口
+ *                                 run_par_db_range() + 系数粗守上限
+ *                                 RUN_PAR_K_MAX_UV；毫→工程换算收进模块内单点
+ *                                 s_milli_to_eng()（顺带把 task-43 第①项所需的
+ *                                 "写值必置脏"这一半满足掉）
+ *   v1.2  2026-10-27  DTU 项目组  道G task-43 第②③项：run_par_store_save() 成功路径
+ *                                 给标定层盖一次落盘水位（纯观测回执，不参与判定）；
+ *                                 本头把"谁写 RAM / 谁落盘 / 什么时机 / poll 不是保存
+ *                                 路径"从意图式陈述改成逐条契约
 */

 #ifndef RUN_PAR_H
@@ -40,6 +64,7 @@

 #include <stdint.h>

+#include "adc_cal.h"   /* adc_semantic_t：公开语义 setter 的形参类型（同层 algo→algo，方向不逆）*/
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -48,6 +73,11 @@ extern "C" {
 #define RUN_PAR_DB_N     9u
 #define RUN_PAR_CH_N     8u

+/* 系数 k 的**粗守**上限（µV/码）：只为挡误写（如把 mV 当 µV 填），不是工况域；
+ * 真合法带在 adc_cal 执行段裁（µV/码 ×[0.5,2.0]），两层各说各的、互不掩盖。
+ * 公开它是因为 UI 整定页要给编辑器设上限——上限在这里，就不许页面再抄一份。*/
+#define RUN_PAR_K_MAX_UV  1.0e9f
+
 /*
 * 函数功能：运行参数初始化——副本置工厂默认 + 注册 [run_par] 段进 cfg 引擎
 * 入口参数：无
@@ -64,7 +94,9 @@ void run_par_init(void);
 * 入口参数：idx - 0..7 = 语义通道序（UA..IN），8 = 频率  uint8_t
 * 返 回 值：死区 V / A / Hz；idx 越界返 0.0（调用方按"无死区"保守处理）  float
 * 限定条件：任意上下文（int32 单字读原子；104 COV 每拍调用）
- * 函数说明：毫单位 → 浮点的换算点（除以 1000 唯一在此，勿在消费侧另写）。
+ * 函数说明：毫单位 → 浮点的换算在本模块内也只有一处（run_par.c 的
+ *          s_milli_to_eng()，run_par_deadband 与 run_par_db_range 共用）；
+ *          消费侧一律取本模块给的工程量，不要再各自除 1000。
 */
 float run_par_deadband(uint8_t idx);

@@ -72,8 +104,11 @@ float run_par_deadband(uint8_t idx);
 * 函数功能：写第 idx 路死区（工程量，含范围守卫 + 脏置位）
 * 入口参数：idx - 同上  uint8_t；db - 死区工程量（V/A/Hz，≥0）  float
 * 返 回 值：0 成功；-1 越界/越程/NaN（副本不动）  int
- * 限定条件：**iec104Task 上下文**（104 执行段 / 卡 11 后的整定路径；UI 若整定
- *          需另行走配置引擎属主路径，勿跨任务直写）
+ * 限定条件：写者两门——**iec104Task**（104 C_SE 执行段）与 **uiTask**（遥测死区页
+ *          经 ui_data 通道五注入转达，道F task-7 起；ui_data.h 通道五表注：合法域
+ *          与"写值+置脏"必须原子发生在执行侧）。两门都只写 RAM 副本 + 置脏，
+ *          落盘统一收敛在 defaultTask（勿在 adcTask 调用；此句为 2026-10-27 措辞
+ *          收口——原写"UI 若整定需另行走属主路径"是 task-2 期遗留，task-7 已接线）
 * 函数说明：合法域按点型分档——电压 0~50 V、电流 0~1 A、频率 0~5 Hz（上限 =
 *          额定 × 二档裕量，守卫目的是挡误写不是限工况；见 .c 常量段）。
 *          成功即置脏（落盘请求，见文件头持久化契约）。
@@ -105,6 +140,40 @@ int run_par_104_read(uint32_t addr, float *out);
 */
 int run_par_104_write(uint32_t addr, float v, uint8_t select);

+/*
+ * 函数功能：写某路系数 k（µV/码）**并在同一函数内置脏**——整定的语义写入口
+ * 入口参数：sem - 电气语义通道（adc_semantic_t 枚举序）  adc_semantic_t；
+ *           k_uv - 系数（µV/码，须 >0 且 <= RUN_PAR_K_MAX_UV）  float
+ * 返回值：0 - RAM 副本已写且已置脏；-1 - 粗守或执行段拒（副本未动、不置脏）  int
+ * 限定条件：整定路径上下文（iec104Task 的 C_SE 执行段；UI 侧由装配层
+ *          App/app/ui_data_feed.c 经 ui_data_yt_ops_t 转进来）。勿在 adcTask 调用
+ * 函数说明：**写值与置脏成对，不许拆开**（lead 裁②）：拆开就等于"屏上已改、
+ *          盘上永不落、且没有任何错误返回"。因此本模块**不提供**公开的
+ *          mark_dirty——单独调它等于空承诺；零点 b 由本函数 RMW 取当前生效值。
+ */
+int run_par_cal_k_set(adc_semantic_t sem, float k_uv);
+
+/*
+ * 函数功能：写某路零点偏移 b（码值）并置脏（与 k 同款语义，粗守 ±1e6 码）
+ * 入口参数：sem - 电气语义通道  adc_semantic_t；b_codes - 零点（码值）  int32_t
+ * 返回值：0 - 已写并置脏；-1 - 粗守或执行段拒（副本未动、不置脏）        int
+ * 限定条件：同 run_par_cal_k_set()
+ * 函数说明：k 侧 RMW 取当前生效值；±8192 真带由 adc_cal 执行段裁。消费者 =
+ *          104 的 0x8048~ 分支（改造后走这里），不是为将来预留的口
+ */
+int run_par_cal_b_set(adc_semantic_t sem, int32_t b_codes);
+
+/*
+ * 函数功能：取第 idx 路死区的合法域（工程量）——**合法域的唯一出口**
+ * 入口参数：idx - 0..8  uint8_t；lo/hi - 输出下限/上限（V/A/Hz）  float *
+ * 返回值：0 - 已写出；-1 - idx 越界或指针空（调用方不得回退成自造默认域）  int
+ * 限定条件：任意上下文（纯常量读）
+ * 函数说明：存在的唯一理由：UI 整定页要给编辑器设 min/max，而这些上限的真源是
+ *          本模块的 RUN_PAR_DB_MAX_*；页面抄一份就是第二真源。给的是**粗守域**，
+ *          真提交仍由与 104 选择段同源的守卫裁，两条路不会漂移到两套数字。
+ */
+int run_par_db_range(uint8_t idx, float *lo, float *hi);
+
 /*
 * 函数功能：落盘脏标志探查（非消费）
 * 入口参数：无
@@ -1,11 +1,11 @@
 /*
- * 模块名称：采样环缓冲（L2 相量计算的输入）
- * 模块功能：按语义通道保存最近 2 个周波（40 点）采样值，供 L2 相量计算按窗取数。
+ * 模块名称：采样环缓冲（全周傅氏相量计算的输入）
+ * 模块功能：按语义通道保存最近 2 个周波（40 点）采样值，供 全周傅氏相量计算按窗取数。
 * 适用平台：STM32F407ZGTx（纯算法，无寄存器/无 RTOS 依赖）
 * 作者：王建锋
 * 创建日期：2026-10-10
 * 修改记录：
- *   v1.0  2026-10-10  王建锋  创建：L2 输入环缓冲（20 点/周波 × 2 周波）
+ *   v1.0  2026-10-10  王建锋  创建：全周傅氏相量输入环缓冲（20 点/周波 × 2 周波）
 */

 #include "sample_ring.h"
@@ -48,7 +48,7 @@ void sample_ring_init(void) {
 * 入口参数：values - 按语义通道顺序排列的一帧采样值（长度须 = ADC_SEM_COUNT）
 *           n      - 实际长度（必须等于 ADC_SEM_COUNT）
 * 返 回 值：0 - 成功；-1 - 参数错
- * 限定条件：同一帧内各通道须同刻（同族量同刻性由上游 L1 负责）
+ * 限定条件：同一帧内各通道须同刻（同族量同刻性由上游 语义取数与有效性负责）
 * 函数说明：整帧写入完毕后**统一**推进写指针——单帧内不存在"半新半旧"，
 *          消费侧取到的窗永远落在整帧边界上（无帧内撕裂）。
 */
@@ -73,28 +73,41 @@ int sample_ring_push_frame(const float *values, uint8_t n) {

 /*
 * 函数功能：取指定语义通道最近 n 点的窗（按时间序，旧 → 新）
- * 入口参数：ch  - 语义通道
- *           n   - 取点数（1..SAMPLE_RING_DEPTH）
- *           out - 输出缓冲（长度须 >= n）
+ * 入口参数：ch  - 语义通道（0 .. ADC_SEM_COUNT-1）
+ *           n   - 取点数（1 .. SAMPLE_RING_DEPTH）
+ *           out - 输出缓冲（调用方保证长度 >= n，本层不校验容量）
 * 返 回 值：0 - 成功；-1 - 参数错；-2 - 已累积点数不足 n
- * 限定条件：无
- * 函数说明：out[n-1] 为最新一点。最老点下标 = head - n（模 DEPTH）。
+ * 限定条件：仅 adcTask 上下文（写者与读者同任务串行，故不加锁、不用 volatile）；
+ *           须在同拍 sample_ring_push_frame() 之后调用。
+ * 函数说明：以最新一点为终点、向前回溯 n 点；out[0] 最老、out[n-1] 最新，
+ *           与 phasor_run() 的求和方向一致。
+ *           为什么需要这一层、环内布局与窗首下标的推导 →
+ *           docs/算法/采集与算法层设计说明.md §5（本文件只留落地要点）。
 */
 int sample_ring_window(adc_semantic_t ch, uint8_t n, float *out) {
    uint16_t start;
    uint16_t i;

+    /* 通道号先转 unsigned 再比：枚举底层可为有符号，负值会骗过 ch >= COUNT 的判据。 */
    if ((out == NULL) || ((unsigned int)ch >= (unsigned int)ADC_SEM_COUNT)) {
        return -1;
    }
+    /* n = 0 是空窗；n > DEPTH 一个环装不下连续 n 点（回绕会把同一点重复读出）。 */
    if ((n == 0u) || (n > SAMPLE_RING_DEPTH)) {
        return -1;
    }
+    /* -2 = 窗还没攒够，调用方跳过本拍即可（首周波启动期必然出现），不是故障。 */
    if (s_filled < (uint16_t)n) {
        return -2;
    }

+    /* 窗首 = s_head - n（s_head 是"下一待写"位置，故窗尾 = s_head - 1）。
+     * 必须先加 DEPTH 再减：直接减在 s_head < n 时下溢或得负数，而
+     * (x mod 65536) mod 40 不等于 x mod 40、C99 的负数取模也不是同余解。
+     * 加 DEPTH 不改同余类，并把中间值锁在 [0, 2·DEPTH - 2]。详见设计说明 §5.3。 */
    start = (uint16_t)((s_head + SAMPLE_RING_DEPTH - (uint16_t)n) % SAMPLE_RING_DEPTH);
+
+    /* 逐点取模拷贝：窗可能跨环尾，环在内存里首尾不相连，不能用一次 memcpy。 */
    for (i = 0u; i < (uint16_t)n; i++) {
        out[i] = s_ring[ch][(uint16_t)((start + i) % SAMPLE_RING_DEPTH)];
    }
@@ -117,7 +130,8 @@ uint16_t sample_ring_filled(void) {
 * 入口参数：无
 * 返 回 值：累计入环帧数
 * 限定条件：无
- * 函数说明：供心跳日志 / 丢帧观测（L1-6 判据之一）。
+ * 函数说明：供心跳日志 / 丢帧观测（采样有效性校验 判据之一）。
+ *（保护功能清单见 docs/算法/继电保护功能复现规划.md）
 */
 uint32_t sample_ring_frames(void) {
    return s_frames;
@@ -1,16 +1,16 @@
 /*
- * 模块名称：采样环缓冲（L2 相量计算的输入）
- * 模块功能：按**语义通道**保存最近若干周波的采样值，供 L2 相量计算按窗取数。
+ * 模块名称：采样环缓冲（全周傅氏相量计算的输入）
+ * 模块功能：按**语义通道**保存最近若干周波的采样值，供 全周傅氏相量计算按窗取数。
 *          V0.1 上 8 路电气量分属两片转换器（双转换器无共同采样触发），本层只做"按时序
- *          存/取"，**不做任何跨通道运算**——同刻性由上游（L1）保证，本层不假设。
+ *          存/取"，**不做任何跨通道运算**——同刻性由上游（语义取数与有效性）保证，本层不假设。
 *          容量取 **2 个周波（40 点）**，与参考系统 `CN_BUFSAM_CYCLE = 2`
 *          （规划 §10.1）一致，为后续加长数据窗（1.5~2 周波，抗衰减直流，
 *          见 `傅氏算法详解.md` §9 Q4）预留空间。
- * 适用平台：STM32F407ZGTx（**纯算法**：不碰寄存器、不碰 RTOS → 可主机侧单测 L0.5）
+ * 适用平台：STM32F407ZGTx（**纯算法**：不碰寄存器、不碰 RTOS → 可主机侧纯逻辑单测）
 * 作者：王建锋
 * 创建日期：2026-10-10
 * 修改记录：
- *   v1.0  2026-10-10  王建锋  创建：L2 输入环缓冲（20 点/周波 × 2 周波）
+ *   v1.0  2026-10-10  王建锋  创建：全周傅氏相量输入环缓冲（20 点/周波 × 2 周波）
 */

 #ifndef SAMPLE_RING_H
@@ -45,7 +45,7 @@ void sample_ring_init(void);
 * 入口参数：values - 按语义通道顺序排列的一帧采样值（浮点工程量，长度须 = ADC_SEM_COUNT）
 *           n      - 实际长度（必须等于 ADC_SEM_COUNT，否则拒收）
 * 返 回 值：0 - 成功；-1 - 参数错（空指针或长度不符）
- * 限定条件：调用方保证同一帧内各通道**同刻**（同族量同刻性由上游 L1 负责）
+ * 限定条件：调用方保证同一帧内各通道**同刻**（同族量同刻性由上游 语义取数与有效性负责）
 * 函数说明：整帧一次性写入，写完统一推进写指针——单帧内不可能出现"半新半旧"，
 *          即天然无帧内撕裂。消费侧读到的窗永远是**整帧**边界。
 */
@@ -59,6 +59,9 @@ int sample_ring_push_frame(const float *values, uint8_t n);
 * 返 回 值：0 - 成功；-1 - 参数错；-2 - 已累积点数不足 n
 * 限定条件：无
 * 函数说明：out[n-1] 为最新一点。相量层以本函数取"以当前时刻为终止的一周波"。
+ *           ⚠ 仅 adcTask 上下文调用（写者与读者同任务串行，本层不加锁）；
+ *           为什么需要这一层、环内布局与窗首下标的推导 →
+ *           `docs/算法/采集与算法层设计说明.md` §5。
 */
 int sample_ring_window(adc_semantic_t ch, uint8_t n, float *out);

@@ -76,7 +79,8 @@ uint16_t sample_ring_filled(void);
 * 入口参数：无
 * 返 回 值：累计入环帧数（32 位，1 kHz 下约 49.7 天回绕）
 * 限定条件：无
- * 函数说明：与 L1 的 `tpafe5160_frame_seq()` 对照可判丢帧（L1-6 采样有效性校验
+ * 函数说明：与 语义取数与有效性的 `tpafe5160_frame_seq()` 对照可判丢帧（采样有效性校验
+ *（保护功能清单见 docs/算法/继电保护功能复现规划.md）
 *          的判据之一，本层只提供计数，不做判定）。
 */
 uint32_t sample_ring_frames(void);
@@ -0,0 +1,58 @@
+/*
+ * 模块名称：屏板状态灯位映射（业务状态 → LED 位掩码）
+ * 模块功能：sb_led_map_eval()——状态快照进、32 位 LED 掩码出。位定义与理由全在
+ *          sb_led_map.h（映射表唯一出处），本文件只做折算。
+ * 适用平台：平台无关（纯标准 C）
+ * 作者：王建锋
+ * 创建日期：2026-10-29
+ * 修改记录：
+ *     2026-10-29  王建锋  创建初始版本（批 3 的 3-1）
+ */
+
+#include <stddef.h>   /* NULL：纯逻辑不经 main.h，NULL 要自己带来 */
+
+#include "sb_led_map.h"
+
+/* NULL 输入归一用的全零快照（static const：不占 RAM，语义就是"什么都没发生"） */
+static const sb_led_in_t s_in_zero = { 0UL, 0UL, 0UL, 0U, { 0U, 0U, 0U } };
+
+/*
+ * 函数功能：把状态快照折算成屏板 LED 32 位掩码（契约见 sb_led_map.h）
+ * 入口参数：p_in   - 状态快照，允许 NULL（= 全零输入，只跑心跳）
+ *           now_ms - 毫秒时基（只用于运行灯相位）
+ * 返回值：32 位 LED 掩码（bit i = 灯 ID i；本函数不触碰 bit0 与 ID 6~19）
+ * 限定条件：任意上下文，纯函数
+ * 函数说明：心跳相位取 (now_ms / SB_LED_BLINK_HALF_MS) 的奇偶——用**除法取奇偶**
+ *           而不是"与上次比差值再翻转"，因为后者要把相位存成静态量，纯函数就没了
+ *           （单测要能不开机就验完整个闪烁序列）。回绕只截短一个半周期，无害。
+ */
+uint32_t sb_led_map_eval(const sb_led_in_t *p_in, uint32_t now_ms)
+{
+    const sb_led_in_t *q    = (p_in != NULL) ? p_in : &s_in_zero;
+    uint32_t           mask = 0UL;
+
+    /* ID 1 运行心跳：偶数个 500 ms 段 = 亮 */
+    if (((now_ms / SB_LED_BLINK_HALF_MS) & 1UL) == 0UL)
+    {
+        mask |= SB_LED_BIT_RUN;
+    }
+
+    if (q->prot_active != 0UL)
+    {
+        mask |= SB_LED_BIT_ALARM;
+    }
+    if (q->iec104_run != 0U)
+    {
+        mask |= SB_LED_BIT_COMM;
+    }
+    if (q->adc_flags != 0UL)
+    {
+        mask |= SB_LED_BIT_ADC_FAULT;
+    }
+    if (q->prot_pick != 0UL)
+    {
+        mask |= SB_LED_BIT_PICKUP;
+    }
+
+    return mask;
+}
@@ -0,0 +1,101 @@
+/*
+ * 模块名称：屏板状态灯位映射（业务状态 → LED 位掩码）
+ * 模块功能：把装置的业务状态（保护动作 / 保护启动 / 采样故障 / 104 主站在线 /
+ *          运行心跳）折算成屏板帧 B `info[0..3]` 的 32 位 LED 掩码。
+ *          ⚠ 本层**纯逻辑**：不碰 HAL、不读全局、不打日志——输入是调用方
+ *            （uiTask）采好的状态快照，输出是一个 uint32_t → 主机侧可纯逻辑单测
+ *            （test/host/sb_led_map/）。与 Drivers/BSP/ScreenLink/sb_proto 同一分层理由。
+ * 适用平台：平台无关（纯标准 C）
+ * 作者：王建锋
+ * 创建日期：2026-10-29
+ * 修改记录：
+ *     2026-10-29  王建锋  创建初始版本（映射表口径见 docs/子系统设计/屏板链路设计说明.md §6）
+ *
+ * 这张表为什么必须"自定"：屏板源码（DTU-LCD LED_Printf）只规定了"位 → 灯号"的
+ * 物理口径（bit1~bit19 → ID 1~19，ID 0 电源灯硬件常亮、不看位，bit20~31 未使用），
+ * **"哪路状态占哪一位"在参考主机源码里不存在**（参考的 LCD_LED_Update 实现在
+ * 未开源的屏板 BSP 库里）。出处 docs/产品需求/产品需求设计文档.md §5.16.3 ①。
+ */
+#ifndef SB_LED_MAP_H
+#define SB_LED_MAP_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <stdint.h>
+
+/* ============================================================================
+ * 一、位定义（屏板物理口径：bit i = 灯 ID i；bit0 被屏板忽略，别指望用它）
+ * ==========================================================================*/
+
+/* ID 1 = 运行灯：装置活着的心跳，500 ms 半周期闪烁（与主板 LED1~3 心跳节奏同源，
+ * docs/产品需求/产品需求设计文档.md §5.8）。它**不取决于任何输入状态**——只要这段
+ * 代码还在被调度，灯就在闪；灯不闪 = uiTask 停了，这正是操作员要看的信号。 */
+#define SB_LED_BIT_RUN          (1UL << 1)
+
+/* ID 2 = 告警灯：任一保护元件处于**动作**态（prot_elm_active_mask != 0）。
+ * ⚠ 产品构建处于「未标定闭锁」（App/task/protect_task.c 的 VALID 门禁），
+ *   标定前恒灭——与屏上"保护动作 N"同一已知口径，不是本灯的缺陷。 */
+#define SB_LED_BIT_ALARM        (1UL << 2)
+
+/* ID 3 = 通信灯：IEC 60870-5-104 链路处于 RUN（STARTDT 已确认 = 主站真的在线在
+ * 轮询）。选 RUN 而不选"TCP 已建连"：连上不发 STARTDT 的扫描器不该点亮它。 */
+#define SB_LED_BIT_COMM         (1UL << 3)
+
+/* ID 4 = 采样故障灯：ADC 采样有效性**电平**故障位非零（adc_health_flags，
+ * 静默/倒退等，当前活跃、可自愈熄灭）。选电平不选 sticky：这盏灯要能熄灭，
+ * "曾经故障过"的账在自检记录里，不该用一盏长明灯喊给操作员。 */
+#define SB_LED_BIT_ADC_FAULT    (1UL << 4)
+
+/* ID 5 = 保护启动灯：任一保护元件处于**启动**（picked）态（prot_elm_pick_mask）。
+ * picked 早于 asserted，"越限启动了但没到动作点"这段过程只在这盏灯上可见
+ * （与 104「保护启动」记录同一动机，App/algo/prot_elm.h 的 pick_mask 注释）。
+ * 同样受未标定闭锁口径约束。 */
+#define SB_LED_BIT_PICKUP       (1UL << 5)
+
+/* 已赋义位的并集（判据用：掩码里不得出现本表之外的置位）。
+ * ID 6~19 保留未用，恒 0；将来扩展从 ID 6 顺序取，跳号留白不回收语义。 */
+#define SB_LED_BITS_DEFINED     (SB_LED_BIT_RUN | SB_LED_BIT_ALARM | SB_LED_BIT_COMM | \
+                                 SB_LED_BIT_ADC_FAULT | SB_LED_BIT_PICKUP)
+
+/* 运行灯闪烁半周期（ms）：0 ~ SB_LED_BLINK_HALF_MS-1 亮，下一个 500 ms 灭，交替。
+ * 取 500 是为与主板 LED 心跳（defaultTask 500 ms 翻转）同拍，两套灯闪烁同相。 */
+#define SB_LED_BLINK_HALF_MS    (500U)
+
+/* ============================================================================
+ * 二、状态输入快照（调用方每拍现采，本模块不缓存、不加锁）
+ * ==========================================================================*/
+
+typedef struct
+{
+    uint32_t prot_active;  /* prot_elm_active_mask()：bit i = 元件 i 动作 */
+    uint32_t prot_pick;    /* prot_elm_pick_mask()：bit i = 元件 i 启动 */
+    uint32_t adc_flags;    /* adc_health_flags()：ADC_HF_* 电平故障位 */
+    uint8_t  iec104_run;   /* 1 = IEC 104 链路 RUN（iec104_serv_link_run()） */
+    uint8_t  pad[3];       /* 显式补齐：结构体大小固定 16 B，主机/目标端一致 */
+} sb_led_in_t;
+
+/* ============================================================================
+ * 三、求值入口
+ * ==========================================================================*/
+
+/*
+ * 函数功能：把状态快照折算成屏板 LED 32 位掩码（纯函数，映射表唯一出处见本头 §一）
+ * 入口参数：p_in   - 状态快照；**允许 NULL**：等价于全零输入（只跑运行灯心跳——
+ *                    心跳证明的是"这段代码活着"，与别的状态无关，不该被空输入连坐）
+ *           now_ms - 当前毫秒时基（运行灯相位唯一依赖；osKernelGetTickCount 同域）
+ * 返回值：32 位 LED 掩码（bit i = 灯 ID i；bit0 与 ID 6~19 恒 0，直接进帧 B info[0..3]）
+ * 限定条件：任意上下文（纯计算：无分支副作用、不读写任何静态量、时基回绕安全——
+ *           回绕瞬间至多把一个半周期截短或延长 1 拍，500 ms 的心跳灯看不出来）
+ * 函数说明：闪烁相位 = (now_ms / 500) 的奇偶，偶 = 亮。上电 first 500 ms 为亮，
+ *           "刚上电灯就在闪"是最直观的自检信号。各状态位相互独立，任一非零即置位，
+ *           无优先级、无互斥（告警与通信可以同时亮，那是两件同时在真发生的事）。
+ */
+uint32_t sb_led_map_eval(const sb_led_in_t *p_in, uint32_t now_ms);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* SB_LED_MAP_H */
@@ -0,0 +1,535 @@
+/*
+ * 模块名称：录波环（故障录波 · 数据面纯逻辑层：滚动环 + 触发冻结状态机 + 已封存区读口）
+ * 模块功能：见 App/algo/wave_ring.h 的文件头注释块——所有权矩阵、封存握手、跨任务安全、
+ *           形态钉死与预算全部写在那里，本文件不重抄一遍，只在实现处补「为什么这么写」。
+ *         本文件是纯逻辑：只 include App/algo/wave_ring.h（它带 wave_store.h），
+ *           不 include HAL / CMSIS / RTOS 头、不调 FatFs、不建任何 RTOS 对象、不打日志。
+ *           临界区也不需要：写者只有 adcTask 一个，读者只碰 SEALED 期间冻结的已封存区，
+ *           §5.2 第一条陷阱（无临界区的活缓冲窗口）在本层根本不成立，因为没有那种入口。
+ * 适用平台：STM32F407ZGTx（Cortex-M4，小端）；主机侧单测 test/host/wave_ring/
+ *           与 test/host/wave_trig/
+ * 作者：DTU 项目组
+ * 创建日期：2026-10-29（故障录波 task-1 · 数据面纯逻辑层）
+ * 修改记录：
+ *   v1.0  2026-10-29  DTU 项目组  创建
+ *   v1.1  2026-10-29  DTU 项目组  触发挂号改单字节载荷编码（lead 评审：三段写在
+ *         adcTask 抢占下会把段头的触发源 / 元件号录成上一段的旧值，溯源字段作废）
+ */
+
+#include "wave_ring.h"
+
+/* ARMCC 的 stdint.h 不提供 NULL，而主机侧 gcc / MSVC 会传递性把它拉进来 ——
+ * 这个差别主机单测照不出来（2026-10-29 台基线实跑 /keil-build 才暴露：本层
+ * wave_ring.c 报 22 条 identifier "NULL" 未定义）。与 App/algo/sample_ring.c、App/algo/freq.c
+ * 同一口径：谁用 NULL 谁自己 include stddef.h，不往公共头里塞（少波及别人的 TU）。 */
+#include <stddef.h>
+
+/* 触发挂号的载荷编码（v1.1）：挂号量必须**一次单字节存写**才原子，所以把载荷本身编进
+ * 那一个字节 —— 0 = 无请求，非 0 = (触发源 << 位移) | 元件号。触发源取值 1 到 3 占高 3 位、
+ * 元件号取 prot_elm 的 picked 位号（uint32 位图 → 0 到 31）占低 5 位，合起来 8 位够用。
+ * 本层双端编译（板端 ARMCC 与模拟器），不能引 FreeRTOS / CMSIS 的临界区内在函数，
+ * 所以「把三个字节压成一个字节」是唯一既原子又不依赖平台的写法。 */
+#define WAVE_RG_REQ_SHIFT    (5u)     /* 载荷里触发源的低位置 */
+#define WAVE_RG_REQ_ELM_MSK  (0x1Fu)  /* 载荷里元件号的位掩码（低 5 位） */
+#define WAVE_RG_REQ_ELM_MAX  (32u)    /* 元件号合法上界（不含），picked 位图只有 32 位 */
+
+/* ===== 一、静态对象（全部文件作用域 static，禁堆分配；落位与字节数见头注第七节） ===== */
+
+/* 数据区：按通道分列，8 列 × 320 点 × 2 字节 = 5120 字节（§7 预算的大头）。
+ * 不许改成 float、不许按帧交错（§12：形态错一次 RAM 翻倍 + 跨步取数）。
+ * 不放在 CCM：DMA 看不见它，且 .sct 里 RW_CCM 只收 heap_4.o，普通 .bss 天然落 SRAM1 */
+static int16_t s_ring[WAVE_RING_CH][WAVE_RING_PTS];
+
+/* 已封存段的段头：latch 之前只有环侧字段有效，latch 之后才是完整段头。
+ * 这是 defaultTask 与 uiTask 能看到的唯一「段头视图」——内部指针一律不外露 */
+static wave_seg_meta_t s_sealed;
+
+/* 观测计数（§9 周期行的 seg= / ovf= / drop= / err= 全从这里取，落盘道不数第二份账） */
+static uint32_t s_seg_total;   /* 成功 ACK 的段数 */
+static uint32_t s_ovf_cnt;     /* 被忽略的触发数 */
+static uint32_t s_drop_cnt;    /* SEALED 窗口丢弃的点数（单位 = 点，一次丢一拍 = 加 8） */
+static uint32_t s_err_cnt;     /* 落盘失败 + 滞留超时自弃 */
+static uint32_t s_last_t0_ms;  /* 最近一段段首毫秒 */
+static uint32_t s_last_seq;    /* 最近一段段首帧序号 */
+
+/* 状态机与索引 */
+static uint16_t s_head;        /* 下一个写入点（滚动位置） */
+static uint16_t s_base;        /* 已封存 / 正在录的段首在环内的下标（段内点 0） */
+static uint16_t s_post_left;   /* 后触发还差多少点封段 */
+static uint16_t s_cool_left;   /* 冷却剩余拍数 */
+static uint16_t s_seal_hold;   /* SEALED 已滞留拍数 */
+static uint8_t s_state;        /* wave_ring_state_t */
+/* 触发请求挂号：0 = 无请求；非 0 = (触发源 << WAVE_RG_REQ_SHIFT) | 元件号。
+ * 刻意只用这一个字节承载「是谁要录波」：旧实现分三个字节写（先写挂号位、后写载荷），
+ * adcTask 抢在两条指令之间就会把上一段的旧触发源 / 旧元件号抄进本段 —— 而这两个字段是
+ * 这段记录唯一的溯源信息（现场靠它与 /log/start.log 对表），错一次事后无从发现。
+ * 单字节存写在 Cortex-M4 上原子，写序不再有意义，所以不需要任何顺序假设或屏障。 */
+static uint8_t s_req;
+static uint8_t s_trig_src;     /* 本段实际用的触发源（钉基址时从请求抄过来） */
+static uint8_t s_trig_elm;     /* 本段实际用的元件序号 */
+static uint8_t s_meta_ready;   /* 1 = 段头已 latch */
+static uint8_t s_seg_idx;      /* 本次上电的轮转下标（跨上电接号由落盘道自持，见头注） */
+
+/* 语义号 → 列号（本波恒等，但把这条恒等式收在一处：二期带 TEMP 时只改这张表，
+ * 写死下标的调用点会静默错位，走本函数的不会） */
+static const int8_t s_col_of_sem[(uint8_t)WAVE_ST_CH_MAX] = {
+    0, 1, 2, 3, 4, 5, 6, 7, -1
+};
+
+/* ===== 二、内部小工具 ===== */
+
+/*
+ * 函数功能：环内下标 +n 后取模
+ * 入口参数：a_idx 当前下标；a_step 步长（小于环长）
+ * 返 回 值：取模后的下标  uint16_t
+ * 限定条件：仅本文件；a_idx 与 a_step 均在环长量级，无溢出风险
+ * 函数说明：环长 320 是 2 的幂吗？不是（320 = 64×5），所以老老实实取模，
+ *           不用位与——写错一次就是「看起来能跑、偶尔串段」的那种 bug。
+ */
+static uint16_t wave_rg_wrap(uint16_t a_idx, uint16_t a_step) {
+    uint16_t v = (uint16_t)(a_idx + a_step);
+
+    if (v >= (uint16_t)WAVE_RING_PTS) {
+        v = (uint16_t)(v - (uint16_t)WAVE_RING_PTS);
+    }
+    return v;
+}
+
+/*
+ * 函数功能：把已封存段的「环侧字段」初始化（封存瞬间调，标定字段一律清零待 latch）
+ * 入口参数：a_now_ms 段首毫秒；a_frame_seq 段首帧序号
+ * 返 回 值：无  void
+ * 限定条件：仅本文件；只在钉基址那一拍调一次
+ * 函数说明：先把 ch[] 全部清成「sem = 下标、其余 0」，是为了让**没有 latch** 的段
+ *           不可能带着上一段的系数被写进文件：sealed() 在未 latch 时本就是 0，
+ *           但清零让「万一有人绕过握手直接读 s_sealed」也读不出旧真值。
+ */
+static void wave_rg_seal_reset(uint32_t a_now_ms, uint32_t a_frame_seq) {
+    uint8_t i;
+
+    s_sealed.fs_hz = (uint16_t)WAVE_ST_FS_DEF;
+    s_sealed.pts_per_cycle = (uint8_t)WAVE_ST_PPC_DEF;
+    s_sealed.ch_count = (uint8_t)WAVE_RING_CH;
+    s_sealed.pts_per_ch = (uint16_t)WAVE_RING_PTS;
+    s_sealed.pre_pts = (uint16_t)WAVE_RING_PRE;
+    s_sealed.trig_src = s_trig_src;
+    s_sealed.trig_elm = s_trig_elm;
+    s_sealed.t0_ms = a_now_ms;
+    s_sealed.wall = 0u;
+    s_sealed.eng = (uint8_t)WAVE_ENG_PIN;
+    s_sealed.flags_seq = 0u;
+    s_sealed.clip_mask = 0u;
+    s_sealed.frame_seq = a_frame_seq;
+    for (i = 0u; i < (uint8_t)WAVE_ST_CH_MAX; i++) {
+        s_sealed.ch[i].sem = i;
+        s_sealed.ch[i].conv = 0u;
+        s_sealed.ch[i].bits = 0u;
+        s_sealed.ch[i].avail = 0u;
+        s_sealed.ch[i].k_q16 = 0;
+        s_sealed.ch[i].b_codes = 0;
+    }
+}
+
+/* ===== 三、初始化与压环 ===== */
+
+/*
+ * 函数功能：复位环与全部状态
+ * 入口参数：无
+ * 返 回 值：无  void
+ * 限定条件：只能在 adcTask 调，且在开始压环之前（见头文件同函数注释）
+ * 函数说明：数据区显式清零而不是依赖 .bss 清零：本函数也可能在运行中被重新调
+ *           （显式重配 / 单测复用），留旧数据就等于留下「上一段的尾巴混进下一段」的口子。
+ */
+void wave_ring_init(void) {
+    uint8_t c;
+    uint16_t i;
+
+    for (c = 0u; c < (uint8_t)WAVE_RING_CH; c++) {
+        for (i = 0u; i < (uint16_t)WAVE_RING_PTS; i++) {
+            s_ring[c][i] = 0;
+        }
+    }
+    s_head = 0u;
+    s_base = 0u;
+    s_post_left = 0u;
+    s_cool_left = 0u;
+    s_seal_hold = 0u;
+    s_state = (uint8_t)WAVE_RING_ST_IDLE;
+    s_req = 0u;
+    s_trig_src = (uint8_t)WAVE_TRIG_NONE;
+    s_trig_elm = 0u;
+    s_meta_ready = 0u;
+    s_seg_idx = 0u;
+    s_seg_total = 0u;
+    s_ovf_cnt = 0u;
+    s_drop_cnt = 0u;
+    s_err_cnt = 0u;
+    s_last_t0_ms = 0u;
+    s_last_seq = 0u;
+    wave_rg_seal_reset(0u, 0u);
+}
+
+/*
+ * 函数功能：压入一拍的 8 路原始码值
+ * 入口参数：p_codes 语义序数组（前 8 项）；a_n 必须等于 WAVE_RING_CH
+ * 返 回 值：WAVE_ST_OK 已写入；WAVE_ST_DONE 本拍被丢弃（SEALED 窗口）；WAVE_ST_E_PARAM 参数错  int32_t
+ * 限定条件：只能在 adcTask 调，每拍一次
+ * 函数说明：写的是「列优先」的 8 个分散地址（每列同一行）——这就是 §6.2 分列形态的代价，
+ *           换来的是落盘与回放都能按列连续搬，不用跨步长取数。
+ */
+int32_t wave_ring_push(const int16_t *p_codes, uint8_t a_n) {
+    uint8_t c;
+
+    if ((p_codes == NULL) || (a_n != (uint8_t)WAVE_RING_CH)) {
+        return WAVE_ST_E_PARAM;
+    }
+    if (s_state == (uint8_t)WAVE_RING_ST_SEALED) {
+        /* 冻结窗口丢样本（§4.2）：计数单位是点，一次丢一整拍 = WAVE_RING_CH 点 */
+        s_drop_cnt += (uint32_t)a_n;
+        return WAVE_ST_DONE;
+    }
+    for (c = 0u; c < (uint8_t)WAVE_RING_CH; c++) {
+        s_ring[c][s_head] = p_codes[c];
+    }
+    s_head = wave_rg_wrap(s_head, 1u);
+    return WAVE_ST_OK;
+}
+
+/* ===== 四、触发、推进、交棒、ACK ===== */
+
+/*
+ * 函数功能：投递一次录波请求
+ * 入口参数：a_src 触发源（1 手动 / 2 保护 / 3 bench）；a_elm 元件序号（0 到 31）
+ * 返 回 值：WAVE_ST_OK 受理；WAVE_ST_DONE 被忽略（ovf 已加一）；WAVE_ST_E_PARAM 触发源
+ *           非法或元件号越界  int32_t
+ * 限定条件：任意上下文（**只写一个字节**，理由见 s_req 声明处）
+ * 函数说明：这里判「非 IDLE 就拒」而不是「非 IDLE 就排队」——本波不做多段排队（已定裁定），
+ *           而且排队会把「最近一次故障」降级成「上上次故障」。
+ *           s_req 已挂号时也拒：同一拍内多个元件同时 picked 只该录一段。
+ *           两条入参校验排在状态判断之前：非法调用是调用方的错，不该记进 ovf 账 ——
+ *           ovf 的语义是「真来了第二次触发」。
+ *           元件号上界写死在这里：今天没有调用方会越界（picked 是 uint32 位图），这条是给
+ *           二期加元件的人留的牙 —— 载荷只有 5 位，越界必须当场拒，不许静默截断。
+ */
+int32_t wave_ring_request(uint8_t a_src, uint8_t a_elm) {
+    if ((a_src < (uint8_t)WAVE_TRIG_MANUAL) || (a_src > (uint8_t)WAVE_TRIG_BENCH)) {
+        return WAVE_ST_E_PARAM;
+    }
+    if (a_elm >= (uint8_t)WAVE_RG_REQ_ELM_MAX) {
+        return WAVE_ST_E_PARAM;
+    }
+    if ((s_state != (uint8_t)WAVE_RING_ST_IDLE) || (s_req != 0u)) {
+        s_ovf_cnt++;
+        return WAVE_ST_DONE;
+    }
+    /* 一次存写：触发源与元件号同字节落地。别的上下文要么看到「没请求」、要么看到
+     * 「完整的这次请求」，不存在读到半份载荷的中间态 */
+    s_req = (uint8_t)(((uint32_t)a_src << (uint32_t)WAVE_RG_REQ_SHIFT) | (uint32_t)a_elm);
+    return WAVE_ST_OK;
+}
+
+/*
+ * 函数功能：推进一拍状态机
+ * 入口参数：a_now_ms 当前相对上电毫秒；a_frame_seq 当前帧序号
+ * 返 回 值：wave_ring_evt_t（本拍刚封段返回 WAVE_RING_EVT_SEALED）  int32_t
+ * 限定条件：只能在 adcTask 调，每拍在 wave_ring_push 之后一次
+ * 函数说明：五个分支各管一件事，互不重叠：
+ *           IDLE    —— 消费挂号、钉段首基址、转 FREEZE
+ *           FREEZE  —— 后触发计点，计满转 SEALED
+ *           SEALED  —— 只计滞留，超时自弃（绝不让环永久焊死）
+ *           COOL    —— 递减冷却，到 0 回 IDLE
+ *           段首基址 = 触发那一拍写入点的「往前 160 点」，于是段内点 0 是最老的预触发点、
+ *           点 160 正好是触发后第一点；后触发的 160 点落在环的另一半（本来就即将被覆盖的
+ *           最老那 160 槽），所以「冻结」在物理上是**停止滚动覆盖**，不是停止写入。
+ */
+int32_t wave_ring_tick(uint32_t a_now_ms, uint32_t a_frame_seq) {
+    int32_t evt = (int32_t)WAVE_RING_EVT_NONE;
+
+    switch (s_state) {
+    case (uint8_t)WAVE_RING_ST_IDLE:
+        s_cool_left = 0u;
+        s_seal_hold = 0u;
+        {
+            /* 只读一次快照再解码：分两次读就会把两次请求的字段拼成一段的身份 */
+            uint8_t req = s_req;
+
+            if (req != 0u) {
+                /* 钉基址：本拍的样本已写进 (head-1)，段首 = head - 预触发点数 */
+                s_trig_src = (uint8_t)((uint32_t)req >> (uint32_t)WAVE_RG_REQ_SHIFT);
+                s_trig_elm = (uint8_t)((uint32_t)req & (uint32_t)WAVE_RG_REQ_ELM_MSK);
+                s_req = 0u;
+                s_base = wave_rg_wrap(s_head, (uint16_t)((uint32_t)WAVE_RING_PTS - (uint32_t)WAVE_RING_PRE));
+                s_post_left = (uint16_t)WAVE_RING_POST;
+                s_meta_ready = 0u;
+                s_last_t0_ms = a_now_ms;
+                s_last_seq = a_frame_seq;
+                wave_rg_seal_reset(a_now_ms, a_frame_seq);
+                s_state = (uint8_t)WAVE_RING_ST_FREEZE;
+            }
+        }
+        break;
+
+    case (uint8_t)WAVE_RING_ST_FREEZE:
+        if (s_post_left > 0u) {
+            s_post_left--;
+        }
+        if (s_post_left == 0u) {
+            /* 封段：此刻起 s_head 正好回到 s_base，再写就覆盖段内点 0 —— 所以 push 开始丢 */
+            s_state = (uint8_t)WAVE_RING_ST_SEALED;
+            s_seal_hold = 0u;
+            evt = (int32_t)WAVE_RING_EVT_SEALED;
+        }
+        break;
+
+    case (uint8_t)WAVE_RING_ST_SEALED:
+        /* 兜底：defaultTask 挂住 / 卷没挂载 / 落盘道被更高优先级的事挡住，都不能让环
+         * 永久冻结——下一次真故障无波可录是比丢一段更贵的代价（lead 裁定） */
+        s_seal_hold++;
+        if (s_seal_hold >= (uint16_t)WAVE_SEAL_TIMEOUT_MS) {
+            s_err_cnt++;
+            s_meta_ready = 0u;
+            s_seal_hold = 0u;
+            s_cool_left = (uint16_t)WAVE_RING_COOL_MS;
+            s_state = (uint8_t)WAVE_RING_ST_COOL;
+        }
+        break;
+
+    case (uint8_t)WAVE_RING_ST_COOL:
+        /* 冷却只在 ACK（或自弃）之后计时：它是二次抑制窗，不是冻结窗 */
+        if (s_cool_left > 0u) {
+            s_cool_left--;
+        }
+        if (s_cool_left == 0u) {
+            s_state = (uint8_t)WAVE_RING_ST_IDLE;
+        }
+        break;
+
+    default:
+        /* 状态字节被写坏（跑飞 / 越界写）时回到 IDLE 而不是卡死：录波宁可多录也不能停 */
+        s_state = (uint8_t)WAVE_RING_ST_IDLE;
+        break;
+    }
+    return evt;
+}
+
+/*
+ * 函数功能：封存交棒——把封存瞬间事实锁进段头
+ * 入口参数：p_cal 封存瞬间事实（不可为 NULL）
+ * 返 回 值：WAVE_ST_OK 已锁存；WAVE_ST_E_STATE 不在待交棒态；WAVE_ST_E_PARAM 参数错  int32_t
+ * 限定条件：只能在 adcTask 调，只在 EVT_SEALED 那一拍调一次
+ * 函数说明：只 copy 封存瞬间的事实，不动环侧字段（点数 / 采样率 / 预触发这些
+ *           在封段那刻已按 §6.2 定死）。重复调用直接拒，不覆盖已有锁存：
+ *           半路换系数会让落盘道写进去的头与它已经在搬的数据不同源。
+ */
+int32_t wave_ring_latch_meta(const wave_seal_cal_t *p_cal) {
+    uint8_t i;
+
+    if (p_cal == NULL) {
+        return WAVE_ST_E_PARAM;
+    }
+    if (p_cal->eng > (uint8_t)WAVE_ENG_PRI) {
+        return WAVE_ST_E_PARAM;
+    }
+    if ((s_state != (uint8_t)WAVE_RING_ST_SEALED) || (s_meta_ready != 0u)) {
+        return WAVE_ST_E_STATE;
+    }
+    s_sealed.eng = p_cal->eng;
+    s_sealed.flags_seq = p_cal->flags_seq;
+    s_sealed.clip_mask = p_cal->clip_mask;
+    s_sealed.wall = p_cal->wall;
+    for (i = 0u; i < s_sealed.ch_count; i++) {
+        s_sealed.ch[i].conv = p_cal->ch[i].conv;
+        s_sealed.ch[i].bits = p_cal->ch[i].bits;
+        s_sealed.ch[i].avail = p_cal->ch[i].avail;
+        s_sealed.ch[i].k_q16 = p_cal->ch[i].k_q16;
+        s_sealed.ch[i].b_codes = p_cal->ch[i].b_codes;
+    }
+    s_meta_ready = 1u;
+    return WAVE_ST_OK;
+}
+
+/*
+ * 函数功能：落盘 ACK
+ * 入口参数：a_result 0 = 成功；非 0 = 失败（短写 / 打开失败 / CRC 自弃）
+ * 返 回 值：WAVE_ST_OK 已解冻并起冷却；WAVE_ST_E_STATE 当前不在 SEALED  int32_t
+ * 限定条件：只能由 defaultTask 调，一段一次
+ * 函数说明：无论成败都解冻 + 起冷却：错误只计数不冻结（环冻着的代价是下一次故障无波可录）。
+ *           成功才推进轮转号与段计数（失败段留同号，下次重写覆盖，不留半截文件）。
+ */
+int32_t wave_ring_write_done(int32_t a_result) {
+    if (s_state != (uint8_t)WAVE_RING_ST_SEALED) {
+        return WAVE_ST_E_STATE;
+    }
+    if (s_meta_ready == 0u) {
+        /* 没 latch 就没有「段」可 ACK：这时候段头从未就绪，落盘道根本拿不到
+         * wave_ring_sealed_meta()，绝不可能真写出文件。若在这里放过 ACK，
+         * 就会白推进轮转号（号 +1 而盘上没那个文件 = 凭空吃掉一个号）并把
+         * seg_total 报成一个没发生过的数（串口周期行的 seg=NN 从此对不上账）。
+         * 拒绝而不是记账，把「没交棒就 ACK」变成调用方看得见的错误。
+         * 本段的出口只有一个：滞留到 WAVE_SEAL_TIMEOUT_MS 自弃（那一路照实计 err）。 */
+        return WAVE_ST_E_STATE;
+    }
+    if (a_result == 0) {
+        s_seg_idx = wave_store_next_idx(s_seg_idx);
+        s_seg_total++;
+    } else {
+        s_err_cnt++;
+    }
+    s_meta_ready = 0u;
+    s_seal_hold = 0u;
+    s_cool_left = (uint16_t)WAVE_RING_COOL_MS;
+    s_state = (uint8_t)WAVE_RING_ST_COOL;
+    return WAVE_ST_OK;
+}
+
+/* ===== 五、状态查询与已封存区读口 ===== */
+
+/*
+ * 函数功能：查当前状态
+ * 入口参数：无
+ * 返 回 值：wave_ring_state_t 取值  uint8_t
+ * 限定条件：任意上下文（只读单字节）
+ */
+uint8_t wave_ring_state(void) {
+    return s_state;
+}
+
+/*
+ * 函数功能：查「有已封存段可读」——跨任务唯一握手量
+ * 入口参数：无
+ * 返 回 值：1 = SEALED 且段头已 latch；0 = 不可用  uint8_t
+ * 限定条件：任意上下文（只读单字节）
+ */
+uint8_t wave_ring_sealed(void) {
+    if ((s_state == (uint8_t)WAVE_RING_ST_SEALED) && (s_meta_ready != 0u)) {
+        return 1u;
+    }
+    return 0u;
+}
+
+/*
+ * 函数功能：取已封存段的段头快照
+ * 入口参数：p_out 输出（整份拷出）
+ * 返 回 值：WAVE_ST_OK；WAVE_ST_E_PARAM 空指针；WAVE_ST_E_STATE 无就绪段  int32_t
+ * 限定条件：任意上下文（defaultTask / uiTask 只读）
+ */
+int32_t wave_ring_sealed_meta(wave_seg_meta_t *p_out) {
+    uint16_t i;
+    const uint8_t *p_src;
+    uint8_t *p_dst;
+
+    if (p_out == NULL) {
+        return WAVE_ST_E_PARAM;
+    }
+    if (wave_ring_sealed() == 0u) {
+        return WAVE_ST_E_STATE;
+    }
+    /* 逐字节拷出而不是 *p_out = s_sealed：结构体赋值在 ARMCC 上会调 __aeabi_memcpy，
+     * 这里没必要为一个赋值多拉一层依赖，量也就 136 字节 */
+    p_src = (const uint8_t *)&s_sealed;
+    p_dst = (uint8_t *)p_out;
+    for (i = 0u; i < (uint16_t)sizeof(wave_seg_meta_t); i++) {
+        p_dst[i] = p_src[i];
+    }
+    return WAVE_ST_OK;
+}
+
+/*
+ * 函数功能：按通道读已封存区的连续点窗
+ * 入口参数：a_ch 列号；a_from 段内起点；a_cnt 期望点数（超出段尾自动夹）；p_dst 输出
+ * 返 回 值：实际点数；WAVE_ST_E_PARAM / WAVE_ST_E_RANGE / WAVE_ST_E_STATE  int32_t
+ * 限定条件：任意上下文，只读已封存区（本层没有任何读活缓冲的入口）
+ * 函数说明：按 s_base 取模展开，读者看到的是 320 点的线性数组。
+ */
+int32_t wave_ring_read_ch(uint8_t a_ch, uint16_t a_from, uint16_t a_cnt, int16_t *p_dst) {
+    uint16_t left;
+    uint16_t n;
+    uint16_t idx;
+    uint16_t i;
+
+    if ((p_dst == NULL) || (a_cnt == 0u)) {
+        return WAVE_ST_E_PARAM;
+    }
+    if ((a_ch >= (uint8_t)WAVE_RING_CH) || (a_from >= (uint16_t)WAVE_RING_PTS)) {
+        return WAVE_ST_E_RANGE;
+    }
+    if (wave_ring_sealed() == 0u) {
+        return WAVE_ST_E_STATE;
+    }
+    left = (uint16_t)((uint16_t)WAVE_RING_PTS - a_from);
+    n = (a_cnt < left) ? a_cnt : left;
+    idx = wave_rg_wrap(s_base, a_from);
+    for (i = 0u; i < n; i++) {
+        p_dst[i] = s_ring[a_ch][idx];
+        idx = wave_rg_wrap(idx, 1u);
+    }
+    return (int32_t)n;
+}
+
+/*
+ * 函数功能：读口的 wave_reader_fn 形态适配（落盘道直接把它交给打包游标）
+ * 入口参数：p_user 未用；其余同 wave_ring_read_ch（点数与起点是 uint32 形态）
+ * 返 回 值：实际点数；负 = WAVE_ST_E_*  int32_t
+ * 限定条件：任意上下文，只读已封存区
+ * 函数说明：32 位入参先夹到 16 位形态再转调，越界一律报错不夹成 0 ——
+ *           夹成 0 会让落盘道以为「这一列读完了」而写出一个短段。
+ */
+int32_t wave_ring_read_cb(void *p_user, uint8_t a_ch, uint32_t a_from,
+                          uint32_t a_cnt, int16_t *p_dst) {
+    (void)p_user;
+
+    if (a_cnt > (uint32_t)WAVE_RING_PTS) {
+        return WAVE_ST_E_PARAM;
+    }
+    if (a_from > (uint32_t)WAVE_RING_PTS) {
+        return WAVE_ST_E_RANGE;
+    }
+    return wave_ring_read_ch(a_ch, (uint16_t)a_from, (uint16_t)a_cnt, p_dst);
+}
+
+/*
+ * 函数功能：取观测计数快照
+ * 入口参数：p_out 输出（不可为 NULL）
+ * 返 回 值：WAVE_ST_OK；WAVE_ST_E_PARAM 空指针  int32_t
+ * 限定条件：任意上下文（只读）
+ */
+int32_t wave_ring_get_stat(wave_ring_stat_t *p_out) {
+    if (p_out == NULL) {
+        return WAVE_ST_E_PARAM;
+    }
+    p_out->state = s_state;
+    p_out->trig_src = s_trig_src;
+    p_out->trig_elm = s_trig_elm;
+    p_out->meta_ready = s_meta_ready;
+    p_out->seg_idx = s_seg_idx;
+    /* 对外字段是 8 位：本波后触发最多 160 点，不会溢出；真溢出说明环长被改过，
+     * 饱和在 255 让它在日志里显眼，而不是绕回 0 假装快封段了 */
+    p_out->post_left = (s_post_left > 255u) ? 255u : (uint8_t)s_post_left;
+    p_out->rsv1 = 0u;
+    p_out->rsv2 = 0u;
+    p_out->cool_left = s_cool_left;
+    p_out->seal_hold = s_seal_hold;
+    p_out->seg_total = s_seg_total;
+    p_out->ovf_cnt = s_ovf_cnt;
+    p_out->drop_cnt = s_drop_cnt;
+    p_out->err_cnt = s_err_cnt;
+    p_out->last_t0_ms = s_last_t0_ms;
+    p_out->last_seq = s_last_seq;
+    return WAVE_ST_OK;
+}
+
+/*
+ * 函数功能：语义通道号 → 本环列号
+ * 入口参数：a_sem 语义号
+ * 返 回 值：列号；WAVE_ST_E_RANGE = 该语义不录  int32_t
+ * 限定条件：任意上下文（纯计算）
+ */
+int32_t wave_ring_col(uint8_t a_sem) {
+    if (a_sem >= (uint8_t)WAVE_ST_CH_MAX) {
+        return WAVE_ST_E_RANGE;
+    }
+    if (s_col_of_sem[a_sem] < 0) {
+        return WAVE_ST_E_RANGE;
+    }
+    return (int32_t)s_col_of_sem[a_sem];
+}
@@ -0,0 +1,406 @@
+/*
+ * 模块名称：录波环形缓冲层（故障录波 · 8 路 × 320 点原始码值环 + 触发冻结状态机）
+ * 模块功能：按拍把 8 路电气量的原始码值压进环形缓冲，在「预触发 + 后触发」窗口计满后
+ *           把这一段冻结成只读的已封存区，等落盘道取走并明确 ACK 之后才解冻。口径属主 =
+ *           docs/子系统设计/故障录波设计说明.md §4.2（段长与冻结语义）、§5.1（任务所有权）、
+ *           §5.2（三条陷阱）、§6.2 与 §6.3（段格式；本层的已封存区就是数据区的字节形态）、
+ *           §7（预算与落位）、§12（风险表）。本文件是它的机器可执行形态；冲突以设计文档
+ *           为准并回报 lead，不在代码里单方面「修正」。
+ *         纯逻辑层纪律：不 include HAL / CMSIS / RTOS 头、不建任务、不打日志、不碰文件系统，
+ *           也不链 App/algo/adc_cal —— 折算档位、有效性位图、削顶位图、epoch 秒与每路
+ *           k_q16 / b_codes 由 adcTask 在「刚封存那一拍」作为参数交棒（见 wave_ring_latch_meta
+ *           与下面的「封存握手顺序」），本层只负责把它们随段头一起锁存。因此本层可被
+ *           主机侧单测 test/host/wave_ring/ 与 test/host/wave_trig/ 原样纳入断言、零桩。
+ *         与 sample_ring 的关系（为什么另起一个环）：App/algo/sample_ring.c 是相量与保护的
+ *           上游、float 形态、深度 256，且它的 sample_ring_window() 没有临界区
+ *           （§5.2 第一条陷阱）。录波要的是 int16 原始码值、320 点、跨任务只读，复用那个环
+ *           要么改它的形态与深度（动相量链），要么在跨任务读上继续裸奔 —— 两条都比另起
+ *           一个环贵，故本波解耦（§2.1 第 3 条结构约束）。
+ *
+ * 形态钉死（§7 预算 + §12 风险表，动这里之前先读）：
+ *   - 元素类型 int16，不许 float：float 让环从 5120 字节变 10240 字节，直接顶穿 §7 的
+ *     约 5.9 KB 静态增量目标；
+ *   - 按通道分列（一路连续 320 点），不按帧交错：回放页只画一路、PC 重算全周傅氏也逐路
+ *     独立，交错布局两种用法都要跨步长取数（§6.2 末段「为什么按通道分列」）；
+ *   - 通道数固定 8，TEMP 不录：温度是片内 ADC 的 12 位单极性原始值、非线性且未参与线性
+ *     标定（docs/任务规划/数据可信.md §7 已定案），进录波只多占 640 字节，并让回放页多一
+ *     格会被误读成电气量的通道；带 TEMP 属二期，且必须连 flags_seq 与 clip_mask 一起升
+ *     版本（§6.2 那两行的括注）；
+ *   - 落位 SRAM1：本层全部是普通文件级静态，链接脚本 MDK-ARM/STM32F407-Demo/
+ *     STM32F407-Demo.sct 把 RW_IRAM1 的 .ANY (+RW +ZI) 收在 0x20000000，CCM 只收
+ *     heap_4.o 与 .noinit → 不加任何段属性就落在 SRAM1。CCM 只剩 7904 字节没有余量，
+ *     而本环不是 DMA 可见对象，也没有非进 CCM 不可的理由。
+ *
+ * 封存握手顺序（唯一合法次序，写死在这里，接线道与后续改动都必须照此）：
+ *   1) adcTask 每拍 wave_ring_push() 然后 wave_ring_tick()；
+ *   2) tick 计满后触发点返回 WAVE_RING_EVT_SEALED —— 此刻状态进 WAVE_RING_ST_SEALED 但
+ *      **尚未就绪**，wave_ring_sealed() 仍返 0；
+ *   3) adcTask 在**同一拍**现取封存瞬间事实（adc_cal_k_q16 / adc_cal_flags / sys_clock /
+ *      削顶位图）并调 wave_ring_latch_meta() 一次 —— 只在第 2 步那一拍取一次，
+ *      既不每拍读 adc_cal（1 kHz 下 8 路白读），也不低频刷新（低频刷新等于快照可能
+ *      来自标定之前的旧值，正是 §12「标定落地后老文件被解释错」的入口）；
+ *   4) 此后 wave_ring_sealed() 才返 1，defaultTask 才准开文件落盘；meta 未就绪时
+ *      defaultTask 必须把本段当「不可用」处理并计 err，**不许拿半份快照落盘**；
+ *   5) defaultTask 搬完（成功或失败都算搬完）调 wave_ring_write_done(result) 明确 ACK；
+ *      ACK 之前冻结一直有效、新触发一律只加 ovf；ACK 之后才起冷却抑制窗。
+ *   为什么必须用状态而不是用时间来挡（lead 裁定 2026-10-29）：若解冻靠计时，会出现
+ *   「冷却走完、adcTask 重新推进写指针，而 defaultTask 还在读那份已封存区」→
+ *   半新半旧的段落进文件且没有任何错误码 —— §5.2 第一条陷阱的翻版。
+ *   兜底：WAVE_RING_ST_SEALED 滞留超过 WAVE_SEAL_TIMEOUT_MS（写者没来取：卷未挂载、
+ *   落盘链卡死都算）→ 自弃本段、err 计数加一、走冷却解冻。**绝不许让录波把环永久焊死**，
+ *   那会让下一次真故障无波可录。
+ *
+ * 跨任务安全（§5.1 与 §5.2 第一条；本层的唯一并发契约）：
+ *   写者只有 adcTask，读者是 defaultTask 与 uiTask，因此只暴露「已封存」标志与已封存区
+ *   读口，不给任何跨任务读活缓冲的路径：
+ *     只能在 adcTask 调：wave_ring_init、wave_ring_push、wave_ring_tick、
+ *                        wave_ring_latch_meta；
+ *     只能由文件系统唯一写者 defaultTask 调：wave_ring_write_done；
+ *     任意上下文可调：wave_ring_request（只投一个字节，protectTask / uiTask /
+ *                        bench 都走它）、wave_ring_state、wave_ring_sealed、
+ *                        wave_ring_sealed_meta、wave_ring_read_ch、wave_ring_read_cb、
+ *                        wave_ring_get_stat、wave_ring_col。
+ *   为什么这样就够、不需要临界区：单字节状态量与请求量在 Cortex-M4 上单字读写天然原子；
+ *   sealed 为 1 期间已封存区对 adcTask 是只读不写（写指针被冻在窗口之外），读者看到的数据
+ *   不会在脚下变；请求走「单字投递 + 下一拍由 adcTask 自己消费」，与 App/algo/prot_elm.c
+ *   的 prot_elm_request_reset() 同一模式。
+ *   「单字」是硬要求不是措辞（lead 评审 2026-10-29）：投递方是 protectTask（Normal）与
+ *   uiTask（BelowNormal），消费者是 adcTask（AboveNormal，会**抢占**它们）。旧实现先写挂号位
+ *   再写触发源与元件号（三个字节、两条指令的窗口），adcTask 抢在中间就会把上一段的旧触发源
+ *   与旧元件号抄进本段 —— 波形没错，错的恰好是这段记录唯一的溯源字段（现场靠它与
+ *   /log/start.log 对表），一次故障只录一段、错过事后无从发现。现在载荷本身编进那一个字节
+ *   （0 = 无请求，非 0 = 触发源占高位 | 元件号占低 5 位），一次存写要么看不见、要么看见完整
+ *   一份，不需要顺序假设，也不需要任何平台相关的屏障或临界区（本层双端编译，禁止引
+ *   FreeRTOS / CMSIS 内在函数）。
+ *
+ *   观测计数的已知容差（**不修、只入档**，lead 裁定 2026-10-29）：ovf 与 err 两个计数是跨上下文
+ *   的读-改-自增（ovf 由任意上下文的拒绝路径加、err 由 adcTask 的超时自弃与 defaultTask 的落盘
+ *   失败分别加），本层不设临界区，所以在并发拒绝 / 并发失败时理论上可能少计一次。定性成
+ *   **观测计数的已知容差**：它们只用于趋势与判读，不作为任何判据的唯一依据 —— 要坐实「冷却期
+ *   内确实来了第二次触发」，同时看 armed 位与 /log/start.log 的时刻，别只盯 ovf 数字。
+ *
+ * 触发与冻结语义（§4.2，严格按此实现，别「顺手优化」）：
+ *   IDLE →（触发）FREEZE：段首基址当拍钉死（预触发区从此不再被覆盖，后触发区继续写入），
+ *   后触发计满 160 点 → SEALED：整段只读，新样本一律丢弃并计 drop，等 meta latch 与落盘
+ *   ACK → （ACK）COOL：恢复正常滚动写入，但本窗口内新触发只加 ovf 不重录 → IDLE。
+ *   冻结期间丢的是录波样本：sample_ring、相量、保护照常跑，本层不碰它们、也无权影响它们。
+ *
+ * 适用平台：STM32F407ZGTx（Cortex-M4，小端）；主机侧单测 test/host/wave_ring/、
+ *           test/host/wave_trig/
+ * 作者：DTU 项目组
+ * 创建日期：2026-10-29（故障录波 task-1 · 数据面纯逻辑层）
+ * 修改记录：
+ *   v1.0  2026-10-29  DTU 项目组  创建：8 路 × 320 点 int16 分列环、请求/冻结/封段/ACK/
+ *                                 冷却状态机（含 SEALED 滞留超时自弃）、段头锁存与
+ *                                 已封存区按通道读口
+ */
+
+#ifndef WAVE_RING_H
+#define WAVE_RING_H
+
+/* 本头对外只暴露 stdint 的类型；文件里出现的 NULL 全在注释内（「不可为 NULL」这类
+ * 约束说明），所以这里刻意不 include stddef.h —— 需要 NULL 的是包含本头的 .c，
+ * 它们自己 include（台基线实测：ARMCC 的 stdint.h 不带 NULL）。 */
+#include <stdint.h>
+#include "wave_store.h"   /* 同层配对头：wave_seg_meta_t / wave_ch_desc_t / wave_reader_fn /
+                             WAVE_ST_* 返回码（本层复用同一套 int 返回码通道，不另发明） */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* ===== 一、环几何（数值属主 = docs/子系统设计/故障录波设计说明.md §4.2 与 §7） ===== */
+
+/* 每通道点数 = 预触发 8 周波 + 后触发 8 周波 = 160 + 160 = 320 点（1 kHz 下 320 ms） */
+#define WAVE_RING_PTS         (320u)
+/* 预触发点数：触发点之前保留 8 周波；回放画触发光标的位点就是这个数（也是段内触发点下标） */
+#define WAVE_RING_PRE         (160u)
+/* 后触发点数：触发点之后采满 8 周波才封段 */
+#define WAVE_RING_POST        (160u)
+/* 通道数 = 8（TEMP 不录，理由见本文件头注）；必须与 WAVE_ST_CH_NUM 相等，单测里钉住 */
+#define WAVE_RING_CH          (8u)
+/* 冷却抑制窗：ACK 之后这么多拍内新触发只加 ovf 不重录（§4.2「只记第一次」）。
+ * 500 拍 = 500 ms @1 kHz。注意：「覆盖一轮落盘窗口」这件事由 ACK 保证，本数值只是
+ * ACK 之后的二次抑制（防同一次故障的抖动重复触发），待台架核。 */
+#define WAVE_RING_COOL_MS     (500u)
+/* 已封存滞留上限：SEALED 状态超过这么多拍仍没人来取（卷未挂载、落盘链卡死都算）
+ * → 自弃本段 + err 计数加一 + 走冷却解冻。2000 拍 = 2 s @1 kHz，待台架核。
+ * 判据是 tick 的推进次数（也就是 adcTask 的存活），不是墙上时间：adcTask 自己挂了
+ * 就轮到看门狗处理，本层不越权。 */
+#define WAVE_SEAL_TIMEOUT_MS  (2000u)
+
+/* 环数据区字节数：int16 × 320 × 8 = 5120（§7 预算里最大的一项；动它等于动预算） */
+#define WAVE_RING_BYTES       (WAVE_RING_PTS * WAVE_RING_CH * (uint32_t)sizeof(int16_t))
+
+/* ===== 二、类型 ===== */
+
+/* wave_ring_tick 的事件：返回值语义是「本拍发生了什么」，不是错误 */
+typedef enum {
+    WAVE_RING_EVT_NONE    = 0,   /* 正常推进，无事件 */
+    WAVE_RING_EVT_SEALED  = 1    /* 本拍刚计满后触发：**adcTask 必须在本拍调
+                                  * wave_ring_latch_meta() 交棒封存瞬间事实**；
+                                  * 不调则本段永不就绪，最终由 WAVE_SEAL_TIMEOUT_MS
+                                  * 自弃（err 加一），可从串口周期行看到 */
+} wave_ring_evt_t;
+
+/* 环状态。迁移只发生在 wave_ring_tick 与 wave_ring_write_done 里（单写者） */
+typedef enum {
+    WAVE_RING_ST_IDLE    = 0,   /* 滚动：新样本覆盖最旧点，接受触发 */
+    WAVE_RING_ST_FREEZE  = 1,   /* 已触发：段首基址已钉死（预触发区不再被覆盖），
+                                   后触发区继续写入，直到计满 WAVE_RING_POST 点 */
+    WAVE_RING_ST_SEALED  = 2,   /* 已封存：整段只读，新样本一律丢弃并计 drop；
+                                   等 meta latch、等 defaultTask 落盘并 ACK */
+    WAVE_RING_ST_COOL    = 3    /* 冷却：已 ACK 解冻、恢复正常滚动，但新触发只加 ovf */
+} wave_ring_state_t;
+
+/* 封存瞬间必须由 adcTask 交棒的事实（本层不链 App/algo/adc_cal，全靠这份入参）。
+ * 段长 / 采样率 / 每周波点数 / 预触发点数 / 触发源与序号 / t0_ms / frame_seq 由本层自己填
+ * （环就是这些数的物理实现，让调用方填只会多一个「忘了填」的失败面）。 */
+typedef struct {
+    uint8_t  eng;          /* 折算档位（wave_eng_t：0 引脚域 / 1 二次值 / 2 一次值） */
+    uint8_t  flags_seq;    /* bit s = 语义通道 s 的 ADC_CAL_F_VALID（§6.3） */
+    uint16_t clip_mask;    /* bit s = 语义通道 s 的 ADC_CAL_F_CLIPPED（V0.1 恒 0xE6） */
+    uint32_t wall;         /* 对时后的 epoch 秒（未对时 0；未对时就写 0，不许拿上电毫秒冒充） */
+    wave_ch_desc_t ch[WAVE_ST_CH_MAX];  /* 通道表前 8 项的 avail / k_q16 / b_codes：
+                                           必须取 adc_cal_k_q16() 的 int32 原值，
+                                           不许经 adc_cal_k_uv() 的 float 回算（§6.3：
+                                           float 在 5.28e7 量级掉尾数）；
+                                           conv 与 bits 也在这里给（本层无从知道两片
+                                           转换器的归属）；sem 由本层按「表内语义号 == 下标」
+                                           自己钉，传进来的 sem 被忽略 */
+} wave_seal_cal_t;
+
+/* 观测快照（给 §9 那条周期行 wave: 与主机单测；字段序 ≈ 日志序，别随手换） */
+typedef struct {
+    uint8_t  state;        /* wave_ring_state_t */
+    uint8_t  trig_src;     /* 当前/最近一段的触发源（wave_trig_src_t；未触发为 0） */
+    uint8_t  trig_elm;     /* 触发元件序号（prot_elm 实例下标；手动与 bench 为 0） */
+    uint8_t  meta_ready;   /* 1 = 段头已 latch 可落盘；SEALED 期间为 0 就是「本段不可用」 */
+    uint8_t  seg_idx;      /* 下一个要写的段号 0..99（轮转号由本层持有，defaultTask 照它取名） */
+    uint8_t  post_left;    /* 后触发还差多少点封段（FREEZE 期间有意义；>255 时饱和在 255） */
+    uint8_t  rsv1;         /* 对齐补齐 */
+    uint8_t  rsv2;         /* 对齐补齐 */
+    uint16_t cool_left;    /* 冷却剩余拍数 */
+    uint16_t seal_hold;    /* 本段已在 SEALED 滞留多少拍（与 WAVE_SEAL_TIMEOUT_MS 对照） */
+    uint32_t seg_total;    /* 累计成功 ACK 的段数（给日志 seg=NN 与对账） */
+    uint32_t ovf_cnt;      /* 被丢弃的触发数：ACK 前重复触发 + 冷却期内触发（§9 ovf=） */
+    uint32_t drop_cnt;     /* 冻结窗口丢弃的录波点数，单位 = 点不是拍（§9 drop=） */
+    uint32_t err_cnt;      /* 落盘失败（write_done 非 0，含短写与 CRC 自弃）
+                              + SEALED 滞留超时自弃 的次数（§9 err=） */
+    uint32_t last_t0_ms;   /* 最近一段段首相对上电毫秒 */
+    uint32_t last_seq;     /* 最近一段段首帧序号（与串口周期行的 frames 对账） */
+} wave_ring_stat_t;
+
+/* ===== 三、生命周期（写者侧） ===== */
+
+/*
+ * 函数功能：复位环与全部状态（清 5120 字节数据区 + 索引 + 状态机 + 观测计数 + 轮转号）
+ * 入口参数：无
+ * 返 回 值：无  void
+ * 限定条件：**只能在 adcTask 调**，且只能在开始压环之前调（启动期或显式重配）。
+ *           内核启动前调用也安全：本函数不调任何 RTOS API、不建对象，纯数组清零
+ *           （平台约束「osKernelStart 之前禁止创建类 API」对本层不适用）
+ * 函数说明：观测计数（seg_total / ovf_cnt / drop_cnt / err_cnt）与轮转号一并归零：
+ *           重启录波就是重新起账，不留旧账，免得串口周期行的累计数与段文件对不上。
+ *           轮转号归零意味着**本层的 seg_idx 只是本次上电的本地计数**（供日志与首轮参考），
+ *           不是盘上真值：跨上电的权威下标必须由落盘道自持——启动扫目录用
+ *           wave_store_idx_from_name 重建、每次写成功后用 wave_store_next_idx 推进。
+ *           若照本层归零后的 0 直接取名，重启后第一笔覆盖的就是上次上电的**最新**段，
+ *           与轮转「新证据优先」的初衷正相反（§6.2 轮转语义）。
+ */
+void wave_ring_init(void);
+
+/*
+ * 函数功能：压入一拍的 8 路原始码值（数据面的唯一写入路径）
+ * 入口参数：p_codes  8 路码值数组，顺序 = adc_semantic_t 的前 8 项
+ *                    （UA UB UC UN IA IB IC IN，即语义号升序，与段文件通道表列序
+ *                     同一口径，§6.3）
+ *           a_n      数组长度，必须等于 WAVE_RING_CH
+ * 返 回 值：WAVE_ST_OK = 已写入；WAVE_ST_DONE = 本拍样本被丢弃（SEALED 窗口，drop 已加一）；
+ *           WAVE_ST_E_PARAM = 空指针或长度不对  int32_t
+ * 限定条件：**只能在 adcTask 调**，每拍一次（1 kHz）；不得从其它任务或 ISR 调。
+ *           尤其禁止图省事挂在 Src/freertos.c 的 TIM3 回调里（adc_tick_irq_notify()
+ *           旁边）：那是 ISR 上下文，且 ISR 比调度器早约 100 ms 启动
+ *           （docs/子系统设计/看门狗设计说明.md §10.1），本层没有「消费者就绪」门，
+ *           挂上去就是拿 ISR 改状态机。
+ * 函数说明：IDLE、FREEZE、COOL 三态都写入；SEALED 一律丢弃并计数 —— 这就是 §4.2
+ *           「冻结期间丢的是录波样本」，不是丢采样链路：sample_ring、相量、保护照常被
+ *           adcTask 喂，本层无权也不该影响它们。
+ *           码值是转换器原始输出：TPAFE 为 16 位补码双极性、片内 ADC 为 0..4095 原样
+ *           正数，**不做中点偏置、不做折算**（§6.3「样本编码」行：加偏置等于伪造双极性）。
+ */
+int32_t wave_ring_push(const int16_t *p_codes, uint8_t a_n);
+
+/* ===== 四、触发请求、每拍推进、封存交棒、落盘 ACK ===== */
+
+/*
+ * 函数功能：投递一次录波请求（单字投递，不碰环、不碰索引）
+ * 入口参数：a_src  触发源（wave_trig_src_t 的 1 / 2 / 3；0 与其它值按参数错拒绝）
+ *           a_elm  触发元件序号（prot_elm 的 picked 位号，**必须小于 32**；
+ *                  手动与 bench 定时传 0。越界当场拒，不许静默截断 —— 载荷只有 5 位）
+ * 返 回 值：WAVE_ST_OK = 已受理（下一拍由 adcTask 自己钉段首基址）；
+ *           WAVE_ST_DONE = 被忽略（处于 FREEZE 或 SEALED 或 COOL，或请求还没被消费；
+ *                          ovf 计数已加一，§9 的 ovf=）；
+ *           WAVE_ST_E_PARAM = 触发源非法或元件号越界（参数错**不记 ovf 账**）  int32_t
+ * 限定条件：**任意上下文可调**（protectTask 的 picked 上升沿、uiTask 的手动确认、
+ *           bench 定周期、adcTask 自己），它只写**一个字节**（载荷编码见文件头
+ *           「跨任务安全」段），与 App/algo/prot_elm.c 的 prot_elm_request_reset()
+ *           同一模式（§5.1）
+ * 函数说明：本函数不产生「立刻冻结」的效果 —— 段首基址由 adcTask 在下一拍
+ *           wave_ring_tick 里钉，避免跨上下文改环索引。最坏延迟一拍 = 1 ms，
+ *           相对 160 点的预触发窗可以忽略。
+ *           **ACK 前一律只加 ovf**（lead 裁定）：SEALED 期间再来触发不重录、不排队，
+ *           本波不做多段排队。
+ *           **返回 WAVE_ST_E_PARAM 的两条路径不触碰任何计数**（ovf / err / drop 一个都不加，
+ *           也不留挂号）：那是调用方传错参数，与「第二次真触发」是两回事。台架不得拿 ovf
+ *           当「谁误用了接口」的证据——误用只在返回值里体现（lead 裁定 2026-10-29）。
+ */
+int32_t wave_ring_request(uint8_t a_src, uint8_t a_elm);
+
+/*
+ * 函数功能：推进一拍状态机（消费请求钉基址、计后触发点数、到点进 SEALED、
+ *           冷却递减、SEALED 滞留超时自弃）
+ * 入口参数：a_now_ms    当前相对上电毫秒（填段头 t0_ms；用 adcTask 已有的时基即可）
+ *           a_frame_seq 当前帧序号（填段头 frame_seq，与串口周期行的 frames 对账）
+ * 返 回 值：wave_ring_evt_t（WAVE_RING_EVT_NONE / WAVE_RING_EVT_SEALED）  int32_t
+ * 限定条件：**只能在 adcTask 调**，且每拍在 wave_ring_push 之后调一次
+ *           （先写样本再算点数，后触发才正好 160 个点）
+ * 函数说明：FREEZE 期间写入行为与滚动无异，只是段首基址已钉死、预触发区不再被覆盖
+ *           —— 这就是 §4.2「触发即冻结写指针」的准确含义：冻住的是覆盖窗口，
+ *           不是停止采集。计满 WAVE_RING_POST 点的本拍返回 WAVE_RING_EVT_SEALED。
+ *           SEALED 期间本函数只做「滞留计时 + 超时自弃」，不动数据、不动基址。
+ */
+int32_t wave_ring_tick(uint32_t a_now_ms, uint32_t a_frame_seq);
+
+/*
+ * 函数功能：封存交棒 —— 把「环已知字段 + adcTask 现取的封存瞬间事实」拼成完整段头并锁存
+ * 入口参数：p_cal  封存瞬间事实（折算档位 / 有效性位图 / 削顶位图 / epoch 秒 / 通道表的
+ *                  conv、bits、avail、k_q16、b_codes；不可为 NULL）
+ * 返 回 值：WAVE_ST_OK = 已锁存，wave_ring_sealed() 从此为 1；
+ *           WAVE_ST_E_STATE = 不在「刚封段待交棒」态（含已 latch 过第二次、非 SEALED）；
+ *           WAVE_ST_E_PARAM = 空指针或折算档位非法  int32_t
+ * 限定条件：**只能在 adcTask 调**，且只在 wave_ring_tick 返回 WAVE_RING_EVT_SEALED 的
+ *           那一拍调一次（重复调返回 WAVE_ST_E_STATE 且不覆盖已有锁存值 —— 半路覆盖
+ *           会让落盘道读到的头与数据不同源）
+ * 函数说明：为什么系数要调用方传、而不让本层自己读 adc_cal —— 本层要能被主机单测零桩
+ *           纳入；更根本的是 §12 的要求：标定一旦落地，老文件必须还能按**当时**的系数
+ *           解释，所以 eng / k / b / clip 属于段头、不属于当前固件状态。
+ *           取值只能在第 3 步那一拍做一次（不每拍读、不低频刷），理由见本文件头注。
+ */
+int32_t wave_ring_latch_meta(const wave_seal_cal_t *p_cal);
+
+/*
+ * 函数功能：落盘 ACK —— defaultTask 明确告知本段已搬完（成功或失败），据此解冻并起冷却
+ * 入口参数：a_result  0 = 落盘成功（打开、写入字节数相符、目录可用）；
+ *                     非 0 = 失败（含 f_write 短写、打开/建目录失败、CRC 自弃）——
+ *                     失败时段已丢，但环必须解冻，错误只计数不冻结
+ * 返 回 值：WAVE_ST_OK = 已 ACK 并转入冷却；WAVE_ST_E_STATE = 当前不在 SEALED
+ *           （重复 ACK 或没有段可 ACK —— 不静默改状态，防落盘道把上一段的 ACK 打到新段），
+ *           或段头还没 latch（第 3 步没做）：这时候落盘道拿不到 sealed_meta，根本没可能
+ *           写出文件，放过 ACK 等于白吃一个轮转号并把 seg=NN 报成没发生过的数，
+ *           故一律拒绝。这种段唯一的出口是滞留到 WAVE_SEAL_TIMEOUT_MS 自弃并计 err  int32_t
+ * 限定条件：**只能由文件系统唯一写者 defaultTask 调**，一段一次，调之前先看
+ *           wave_ring_sealed()（它就是「SEALED 且已 latch」的合并判据）
+ * 函数说明：失败不推进轮转号（下一段仍用同号重写，同号文件按 FA_CREATE_ALWAYS 截断，
+ *           不留半截文件骗过 PC 脚本）；成功才推进 seg_idx 与 seg_total。
+ *           本函数不删文件、不碰 FatFs：那些都在落盘道（§5.1 所有权）。
+ */
+int32_t wave_ring_write_done(int32_t a_result);
+
+/* ===== 五、状态查询与已封存区读口（跨任务安全的唯一入口） ===== */
+
+/*
+ * 函数功能：查当前状态
+ * 入口参数：无
+ * 返 回 值：wave_ring_state_t 的取值  uint8_t
+ * 限定条件：任意上下文（只读单字节）
+ */
+uint8_t wave_ring_state(void);
+
+/*
+ * 函数功能：查「有已封存段可读」标志 —— 跨任务的唯一握手量（§5.2 第一条陷阱）
+ * 入口参数：无
+ * 返 回 值：1 = 状态为 SEALED **且段头已 latch**，此刻起 wave_ring_sealed_meta 与
+ *           wave_ring_read_ch 可用；0 = 不可用  uint8_t
+ * 限定条件：任意上下文（只读单字节）
+ * 函数说明：为什么把「已 latch」并进来而不是单开一个查询：省得 defaultTask 自己
+ *           拼两个标志、拼错就是拿半份快照落盘（第 4 步明写的禁忌）。
+ *           为 1 期间已封存区对 adcTask 只读不写，读者可以慢慢分次取、不需要临界区；
+ *           为 0 时所有读口一律返 WAVE_ST_E_STATE 而**不是返回旧数据** ——
+ *           把上一段的字节当这一段，等于伪造证据。
+ */
+uint8_t wave_ring_sealed(void);
+
+/*
+ * 函数功能：取已封存段的段头快照（落盘道编头、回放页画标题都用它）
+ * 入口参数：p_out  输出（整份拷出，约 136 字节；不可为 NULL）
+ * 返 回 值：WAVE_ST_OK；WAVE_ST_E_PARAM 空指针；WAVE_ST_E_STATE 无就绪段  int32_t
+ * 限定条件：任意上下文（defaultTask / uiTask 只读）。整份拷贝、不暴露内部指针，
+ *           免得调用方攥着指针跨到下一段去看
+ * 函数说明：这里的 fs_hz / pts_per_cycle / pre_pts 是**数据**，回放页与 PC 脚本必须
+ *           从这里读，不许当编译期常量（§2.1 第 1 条）。
+ */
+int32_t wave_ring_sealed_meta(wave_seg_meta_t *p_out);
+
+/*
+ * 函数功能：按通道读已封存区的连续点窗（回放页画一路、落盘道搬一路都走它）
+ * 入口参数：a_ch    列号 = 通道表下标 = 语义号（0 到 WAVE_RING_CH-1）
+ *           a_from  段内起始点下标（0 = 段首 = 最早的一点。点序口径：触发那一拍的
+ *                     样本落在点 WAVE_RING_PRE-1（预触发窗的最后一点），段内点
+ *                     WAVE_RING_PRE 起是触发之后的第一拍——预触发 8 周波与后触发
+ *                     8 周波各 160 点，故障时刻正好是两半的分界（§4.2）
+ *           a_cnt   点数（1 起；超出段尾时函数内部夹到剩余点数，不报错）
+ *           p_dst   输出 int16 数组（不可为 NULL；画窗 40 点或搬运 128 点按调用方给的容量）
+ * 返 回 值：不小于 0 = 实际读出的点数（到段尾会少于 a_cnt）；
+ *           WAVE_ST_E_PARAM 空指针或 a_cnt 为 0；WAVE_ST_E_RANGE 列号或起始点越界；
+ *           WAVE_ST_E_STATE 无就绪段  int32_t
+ * 限定条件：任意上下文，但**只读已封存区**：本层不提供任何读活缓冲的接口，
+ *           IDLE / FREEZE / COOL 下一律 WAVE_ST_E_STATE（§5.2 第一条：不给跨任务读活环的路径）
+ * 函数说明：内部按段首基址取模展开，对读者来说已封存区就是一段 320 点的线性数组。
+ *           回放页画 2 周波 = 40 点（§8.1）一次调用即可；字节形态 = 段文件数据区的
+ *           字节形态（int16 小端），所以落盘道能直接把它交给 wave_store 的打包游标。
+ */
+int32_t wave_ring_read_ch(uint8_t a_ch, uint16_t a_from, uint16_t a_cnt, int16_t *p_dst);
+
+/*
+ * 函数功能：同上，形态适配 App/algo/wave_store.h 的 wave_reader_fn（落盘道直接传它）
+ * 入口参数：p_user  上下文（本层是单例，忽略，传 NULL 即可）
+ *           a_ch    列号
+ *           a_from  段内起始点下标
+ *           a_cnt   点数
+ *           p_dst   输出 int16 数组
+ * 返 回 值：实际读出的点数（不小于 0）；负 = WAVE_ST_E_*（同上三条）  int32_t
+ * 限定条件：任意上下文；只读已封存区（同上）
+ * 函数说明：存在的唯一理由是让 wave_store_pack_start 的 p_reader 直接指过来，
+ *           省掉接线索里一个只为转发的包装函数。
+ */
+int32_t wave_ring_read_cb(void *p_user, uint8_t a_ch, uint32_t a_from,
+                          uint32_t a_cnt, int16_t *p_dst);
+
+/*
+ * 函数功能：取观测计数快照（给 §9 的周期行与主机单测）
+ * 入口参数：p_out  输出（不可为 NULL）
+ * 返 回 值：WAVE_ST_OK；WAVE_ST_E_PARAM 空指针  int32_t
+ * 限定条件：任意上下文（只读；一次拷约 44 字节，个别字段可能与 adcTask 的推进错开一拍，
+ *           这是观测量的固有精度，不构成判据错误）
+ * 函数说明：err_cnt 的两条来源都在本层收口（write_done 非 0、SEALED 滞留超时自弃），
+ *           所以 §9 日志行的 err= 直接取它即可 —— 落盘道不需要自己数第二份账。
+ */
+int32_t wave_ring_get_stat(wave_ring_stat_t *p_out);
+
+/*
+ * 函数功能：把「语义通道号」换算成本环的列号（列序 = 语义号升序，§6.3）
+ * 入口参数：a_sem  语义号（adc_semantic_t 值）
+ * 返 回 值：0 到 WAVE_RING_CH-1 = 列号；WAVE_ST_E_RANGE = 该语义不录（TEMP 与越界值）  int32_t
+ * 限定条件：任意上下文（纯计算）
+ * 函数说明：本波只录前 8 个语义通道，所以「列号 == 语义号」这条恒等式成立；
+ *           但调用方必须走这个函数而不是自己写死下标 —— 二期带 TEMP 时列号与语义号
+ *           就会分叉，写死下标的地方会静默错位。
+ */
+int32_t wave_ring_col(uint8_t a_sem);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* WAVE_RING_H */
@@ -0,0 +1,981 @@
+/*
+ * 模块名称：录波段格式层实现（故障录波 · 段文件字节布局编解码 + 打包游标 + 段名轮转）
+ * 模块功能：见 App/algo/wave_store.h 的文件头注释块——口径属主、职责边界、跨任务安全、
+ *           二期不返工的约束全部写在那里，本文件不重复一遍。
+ *         本文件是纯逻辑：只 include App/algo/wave_store.h 与 C 标准库的 stdint/stddef，
+ *           不 include HAL / CMSIS / RTOS 头、不调 FatFs、不碰文件系统、不打日志。
+ * 适用平台：STM32F407ZGTx（Cortex-M4，小端）；主机侧单测 test/host/wave_store/
+ * 作者：DTU 项目组
+ * 创建日期：2026-10-29（故障录波 task-1 · 数据面纯逻辑层）
+ * 修改记录：
+ *   v1.0  2026-10-29  DTU 项目组  创建
+ */
+
+#include "wave_store.h"
+
+/* ARMCC 的 stdint.h 不提供 NULL，而主机侧 gcc / MSVC 会传递性把它拉进来 ——
+ * 这个差别主机单测照不出来（2026-10-29 台基线实跑 /keil-build 才暴露：本层
+ * wave_store.c 报 22 条 identifier "NULL" 未定义）。与 App/algo/sample_ring.c、App/algo/freq.c
+ * 同一口径：谁用 NULL 谁自己 include stddef.h，不往公共头里塞（少波及别人的 TU）。 */
+#include <stddef.h>
+
+/* 打包游标一次最多从数据源取多少个点（128 字节栈上临时区，落盘道在 defaultTask 上跑，
+ * 不在 1 kHz 采集链上；取批是为了把「每点一次回调」压成「每 64 点一次回调」） */
+#define WAVE_ST_BATCH      (64u)
+/* 数据区点下标非法时的内部哨兵（对外一律走 wave_store_data_off 的 0xFFFFFFFFu） */
+#define WAVE_ST_BAD_OFF    (0xFFFFFFFFu)
+
+/* ===== 内部：小端读写（显式移位拼装，不依赖宿主字节序，板端与 PC 侧同一判据） ===== */
+
+/*
+ * 函数功能：写 16 位小端
+ * 入口参数：p  目标位置（至少 2 字节）；v 值
+ * 返 回 值：无  void
+ * 限定条件：调用方保证 p 可写 2 字节
+ */
+static void wave_st_put16(uint8_t *p, uint16_t v) {
+    p[0] = (uint8_t)(v & 0xFFu);
+    p[1] = (uint8_t)((v >> 8) & 0xFFu);
+}
+
+/*
+ * 函数功能：写 32 位小端
+ * 入口参数：p  目标位置（至少 4 字节）；v 值
+ * 返 回 值：无  void
+ * 限定条件：调用方保证 p 可写 4 字节
+ */
+static void wave_st_put32(uint8_t *p, uint32_t v) {
+    p[0] = (uint8_t)(v & 0xFFu);
+    p[1] = (uint8_t)((v >> 8) & 0xFFu);
+    p[2] = (uint8_t)((v >> 16) & 0xFFu);
+    p[3] = (uint8_t)((v >> 24) & 0xFFu);
+}
+
+/*
+ * 函数功能：读 16 位小端
+ * 入口参数：p  源位置（至少 2 字节）
+ * 返 回 值：值  uint16_t
+ * 限定条件：调用方保证 p 可读 2 字节
+ */
+static uint16_t wave_st_get16(const uint8_t *p) {
+    return (uint16_t)((uint16_t)p[0] | ((uint16_t)p[1] << 8));
+}
+
+/*
+ * 函数功能：读 32 位小端
+ * 入口参数：p  源位置（至少 4 字节）
+ * 返 回 值：值  uint32_t
+ * 限定条件：调用方保证 p 可读 4 字节
+ */
+static uint32_t wave_st_get32(const uint8_t *p) {
+    return ((uint32_t)p[0]) | (((uint32_t)p[1]) << 8) |
+           (((uint32_t)p[2]) << 16) | (((uint32_t)p[3]) << 24);
+}
+
+/*
+ * 函数功能：把 int16 写成小端两字节
+ * 入口参数：p  目标位置；v 码值
+ * 返 回 值：无  void
+ * 限定条件：调用方保证 p 可写 2 字节
+ * 函数说明：先转 uint16 再移位——负数右移是实现定义行为，转成无符号后行为确定。
+ */
+static void wave_st_put_code(uint8_t *p, int16_t v) {
+    wave_st_put16(p, (uint16_t)v);
+}
+
+/* ===== 内部：段头字段一致性自检（编码前与解码后各跑一次，同一把尺子） ===== */
+
+/*
+ * 函数功能：校验段头元数据的**几何与表序**是否自相矛盾
+ * 入口参数：p_meta  段头元数据（非空）
+ * 返 回 值：WAVE_ST_OK = 合法；WAVE_ST_E_SIZE 长度类不成立（零通道 / 零点数 / 预触发超段长）；
+ *           WAVE_ST_E_FORMAT 档位 / 触发源 / 表序非法  int
+ * 限定条件：p_meta 由调用方保证非空
+ * 函数说明：为什么编码侧也要跑：写一个「看起来像样的坏段文件」比拒写糟得多——落盘道会
+ *           把 CRC 与长度都算自洽的垃圾写进 NAND，等到回放页或 PC 脚本才发现，那时
+ *           现场已经没了（§8.1「画成一条直线等于伪造证据」是同一条忌讳的另一半）。
+ */
+static int wave_st_meta_check(const wave_seg_meta_t *p_meta) {
+    uint8_t i;
+
+    /* 零通道 / 零点数：这一段连长度都不成立（§6.2 末行「长度为 0 判废」） */
+    if ((p_meta->ch_count == 0u) || (p_meta->ch_count > (uint8_t)WAVE_ST_CH_MAX)) {
+        return WAVE_ST_E_SIZE;
+    }
+    if (p_meta->pts_per_ch == 0u) {
+        return WAVE_ST_E_SIZE;
+    }
+    /* 预触发点数不能大于一段的点数；后触发 = pts_per_ch - pre_pts，允许为 0（手动触发
+     * 撞上落盘窗口等极端情形），但不允许负数——那是把段长算错 */
+    if (p_meta->pre_pts > p_meta->pts_per_ch) {
+        return WAVE_ST_E_SIZE;
+    }
+    /* 采样率与每周波点数是数据，但为 0 的数据没法解释（回放与 PC 都要拿它做除数） */
+    if ((p_meta->fs_hz == 0u) || (p_meta->pts_per_cycle == 0u)) {
+        return WAVE_ST_E_SIZE;
+    }
+    /* 与 PC 侧 reader 的拒绝清单对齐（谁都不能产出一段「自己写得出、对面读不了」的文件）：
+     * 每周波不足 2 点连一个周期都描不出来；段长不足一个整周期则基波算法无从取窗。 */
+    if (p_meta->pts_per_cycle < 2u) {
+        return WAVE_ST_E_SIZE;
+    }
+    if (p_meta->pts_per_ch < (uint32_t)p_meta->pts_per_cycle) {
+        return WAVE_ST_E_SIZE;
+    }
+    if (p_meta->eng > (uint8_t)WAVE_ENG_PRI) {
+        return WAVE_ST_E_FORMAT;
+    }
+    if (p_meta->trig_src > (uint8_t)WAVE_TRIG_BENCH) {
+        return WAVE_ST_E_FORMAT;
+    }
+    /* 表序：第 i 项的语义号必须等于下标（§6.3「通道表序与列序」行）——
+     * 数据区第 i 列归第 i 项解释，错一位就是拿 IB 的波形配 IC 的系数 */
+    for (i = 0u; i < p_meta->ch_count; i++) {
+        if (p_meta->ch[i].sem != i) {
+            return WAVE_ST_E_FORMAT;
+        }
+        if (p_meta->ch[i].conv > (uint8_t)1u) {
+            return WAVE_ST_E_FORMAT;
+        }
+        /* 位宽留个合理域：本波只有 16（TPAFE）与 12（片内 ADC），但格式层不写死这两个值，
+         * 只挡明显不成立的（0 位、超过 32 位）——二期换转换器不必改这里 */
+        if ((p_meta->ch[i].bits == 0u) || (p_meta->ch[i].bits > 32u)) {
+            return WAVE_ST_E_FORMAT;
+        }
+    }
+    return WAVE_ST_OK;
+}
+
+/* ===== CRC-16/MODBUS ===== */
+
+/*
+ * 函数功能：CRC-16/MODBUS 增量计算
+ * 入口参数：a_crc  上一次的中间值（首次传 WAVE_ST_CRC_INIT）
+ *           p_data 数据（NULL 视为空操作）
+ *           a_len  字节数
+ * 返 回 值：新的中间值  uint16_t
+ * 限定条件：任意上下文；纯计算
+ * 函数说明：反射形态 = 右移、异或 0xA001、初值 0xFFFF、异或输出 0；
+ *           写进文件时低字节在前（§6.3）。无表实现的理由见 wave_store.h 头注。
+ */
+uint16_t wave_store_crc_update(uint16_t a_crc, const uint8_t *p_data, uint32_t a_len) {
+    uint16_t crc = a_crc;
+    uint32_t i;
+
+    if (p_data == NULL) {
+        return crc;
+    }
+    for (i = 0u; i < a_len; i++) {
+        uint8_t b = p_data[i];   /* 身兼两职：本路字节 + 下面内层 8 次的计数器 */
+
+        crc = (uint16_t)(crc ^ (uint16_t)b);
+        for (b = 0u; b < 8u; b++) {
+            if ((crc & 0x0001u) != 0u) {
+                crc = (uint16_t)((crc >> 1) ^ WAVE_ST_CRC_POLY);
+            } else {
+                crc = (uint16_t)(crc >> 1);
+            }
+        }
+    }
+    /* 异或输出恒 0：写成宏引用，换异或输出时只改一处 */
+    return (uint16_t)(crc ^ WAVE_ST_CRC_XOROUT);
+}
+
+/*
+ * 函数功能：CRC-16/MODBUS 一次算完
+ * 入口参数：p_data 数据；a_len 字节数
+ * 返 回 值：CRC；空输入返回初值定义  uint16_t
+ * 限定条件：任意上下文。零长度的判废由调用方做（见 wave_store.h 同函数注释）
+ */
+uint16_t wave_store_crc(const uint8_t *p_data, uint32_t a_len) {
+    return wave_store_crc_update(WAVE_ST_CRC_INIT, p_data, a_len);
+}
+
+/*
+ * 函数功能：CRC 实现自检（对规范锚点，不是自算自验）
+ * 入口参数：无
+ * 返 回 值：WAVE_ST_OK 相符；WAVE_ST_E_FORMAT 不符  int
+ * 限定条件：任意上下文；开机或首次落盘前一次，不在每拍路径上
+ * 函数说明：锚点串「123456789」的 CRC-16/MODBUS = 0x4B37（§6.3）。字面量必须纯 ASCII，
+ *           所以这里用显式字节数组而不是把中文塞进字符串。
+ */
+int wave_store_crc_selftest(void) {
+    static const uint8_t s_anchor[9] = {
+        (uint8_t)0x31u, (uint8_t)0x32u, (uint8_t)0x33u,
+        (uint8_t)0x34u, (uint8_t)0x35u, (uint8_t)0x36u,
+        (uint8_t)0x37u, (uint8_t)0x38u, (uint8_t)0x39u
+    };
+    uint16_t got;
+
+    got = wave_store_crc(s_anchor, (uint32_t)sizeof(s_anchor));
+    if (got != WAVE_ST_CRC_CHECK) {
+        return WAVE_ST_E_FORMAT;
+    }
+    return WAVE_ST_OK;
+}
+
+/* ===== 段头编解码 ===== */
+
+/* 语义通道的转换器归属与位宽（0 = TPAFE5160，1 = 片内 ADC1；口径属主是
+ * docs/硬件平台/ADC通道映射说明.md，本表是其抄本，改硬件接线时两处一起改）。
+ * 第 9 项 TEMP 本波不录入段文件（ch_count 恒 8），仍按实际归属填，
+ * 免得将来放开 TEMP 时这里是个 0。 */
+static const uint8_t s_sem_conv[(uint8_t)WAVE_ST_CH_MAX] = {
+    (uint8_t)0u, (uint8_t)1u, (uint8_t)1u,
+    (uint8_t)0u, (uint8_t)0u, (uint8_t)1u, (uint8_t)1u, (uint8_t)1u, (uint8_t)1u
+};
+static const uint8_t s_sem_bits[(uint8_t)WAVE_ST_CH_MAX] = {
+    16u, 12u, 12u,
+    16u, 16u, 12u, 12u, 12u, 12u
+};
+
+/*
+ * 函数功能：把段头元数据填成本波默认值（只填格式侧静态事实）
+ * 入口参数：p_meta  输出
+ * 返 回 值：WAVE_ST_OK；WAVE_ST_E_PARAM 空指针  int
+ * 限定条件：任意上下文
+ * 函数说明：填三样格式侧的静态事实：语义号 = 下标（§6.3 表序口径，也是 PC 侧判据）、
+ *           conv / bits 按两片转换器的归属（下面那张表的口径属主是
+ *            docs/硬件平台/ADC通道映射说明.md 的抄本，本层刻意不带 adc_input.h，
+ *           这样格式层在主机侧不需要任何假件就能编译；单测里 0xE6 的算术交叉验证
+ *           会同时钉住这套顺序，抄错就会红）。
+ *           不填 avail / k_q16 / b_codes：那些是封存瞬间的事实，必须由调用方现取现填
+ *           （adc_cal_k_q16 / adc_cal_flags / sys_clock），本层不链它们；
+ *           调用方忘填 k_q16 与 avail 不会让编码失败（0 是合法整数），
+ *           但会让 PC 侧把波形解释成一条 0 线——所以单测里有一条专门检查
+ *           「填了系数的往返」与「没填系数时段的形状仍然正确、只是幅值归零」。
+ */
+int wave_store_meta_init(wave_seg_meta_t *p_meta) {
+    uint8_t i;
+
+    if (p_meta == NULL) {
+        return WAVE_ST_E_PARAM;
+    }
+    p_meta->fs_hz = (uint16_t)WAVE_ST_FS_DEF;
+    p_meta->pts_per_cycle = (uint8_t)WAVE_ST_PPC_DEF;
+    p_meta->ch_count = (uint8_t)WAVE_ST_CH_NUM;
+    p_meta->pts_per_ch = (uint16_t)WAVE_ST_PTS_DEF;
+    p_meta->pre_pts = (uint16_t)WAVE_ST_PRE_DEF;
+    p_meta->trig_src = (uint8_t)WAVE_TRIG_NONE;
+    p_meta->trig_elm = 0u;
+    p_meta->t0_ms = 0u;
+    p_meta->wall = 0u;
+    p_meta->eng = (uint8_t)WAVE_ENG_PIN;
+    p_meta->flags_seq = 0u;
+    p_meta->clip_mask = 0u;
+    p_meta->frame_seq = 0u;
+    for (i = 0u; i < (uint8_t)WAVE_ST_CH_MAX; i++) {
+        p_meta->ch[i].sem = i;
+        p_meta->ch[i].conv = s_sem_conv[i];
+        p_meta->ch[i].bits = s_sem_bits[i];
+        p_meta->ch[i].avail = 0u;
+        p_meta->ch[i].k_q16 = 0;
+        p_meta->ch[i].b_codes = 0;
+    }
+    return WAVE_ST_OK;
+}
+
+/*
+ * 函数功能：内部——把固定头 + 通道表写进缓冲（不含头 CRC）
+ * 入口参数：p_meta  段头；p_out 缓冲（容量须 >= 头 CRC 覆盖区）
+ * 返 回 值：写入字节数（= 头 CRC 覆盖区长度）  uint32_t
+ * 限定条件：p_meta 已过 wave_st_meta_check、p_out 容量已核过
+ */
+static uint32_t wave_st_head_raw(const wave_seg_meta_t *p_meta, uint8_t *p_out) {
+    uint8_t i;
+    const uint32_t tbl_n = (uint32_t)p_meta->ch_count * WAVE_ST_CH_BYTES;
+
+    p_out[WAVE_ST_OFF_MAGIC] = (uint8_t)WAVE_ST_MAGIC0;
+    p_out[WAVE_ST_OFF_MAGIC + 1u] = (uint8_t)WAVE_ST_MAGIC1;
+    /* 魔数第三字节 = 版本号：与 ver 字段同源同值（§6.2 第 0 行 + §6.3 判废口径） */
+    p_out[WAVE_ST_OFF_MAGIC + 2u] = (uint8_t)WAVE_ST_VER;
+    p_out[WAVE_ST_OFF_VER] = (uint8_t)WAVE_ST_VER;
+    wave_st_put16(&p_out[WAVE_ST_OFF_FS_HZ], p_meta->fs_hz);
+    p_out[WAVE_ST_OFF_PTS_CYC] = p_meta->pts_per_cycle;
+    p_out[WAVE_ST_OFF_CH_CNT] = p_meta->ch_count;
+    wave_st_put16(&p_out[WAVE_ST_OFF_PTS_CH], p_meta->pts_per_ch);
+    wave_st_put16(&p_out[WAVE_ST_OFF_PRE_PTS], p_meta->pre_pts);
+    p_out[WAVE_ST_OFF_TRIG_SRC] = p_meta->trig_src;
+    p_out[WAVE_ST_OFF_TRIG_ELM] = p_meta->trig_elm;
+    wave_st_put32(&p_out[WAVE_ST_OFF_T0_MS], p_meta->t0_ms);
+    wave_st_put32(&p_out[WAVE_ST_OFF_WALL], p_meta->wall);
+    p_out[WAVE_ST_OFF_ENG] = p_meta->eng;
+    p_out[WAVE_ST_OFF_FLAGS] = p_meta->flags_seq;
+    wave_st_put16(&p_out[WAVE_ST_OFF_CLIP], p_meta->clip_mask);
+    wave_st_put32(&p_out[WAVE_ST_OFF_SEQ], p_meta->frame_seq);
+
+    for (i = 0u; i < p_meta->ch_count; i++) {
+        uint32_t pos = (uint32_t)WAVE_ST_OFF_TBL + ((uint32_t)i * WAVE_ST_CH_BYTES);
+
+        p_out[pos + WAVE_ST_CH_OFF_SEM] = p_meta->ch[i].sem;
+        p_out[pos + WAVE_ST_CH_OFF_CONV] = p_meta->ch[i].conv;
+        p_out[pos + WAVE_ST_CH_OFF_BITS] = p_meta->ch[i].bits;
+        p_out[pos + WAVE_ST_CH_OFF_AVAIL] = p_meta->ch[i].avail;
+        /* int32 系数按小端原样落 4 字节：右移到 24 位前把符号扩展掉，
+         * 保证板端 ARMCC 与主机 CRT 写出同一串字节 */
+        wave_st_put32(&p_out[pos + WAVE_ST_CH_OFF_KQ16], (uint32_t)p_meta->ch[i].k_q16);
+        wave_st_put32(&p_out[pos + WAVE_ST_CH_OFF_BCODE], (uint32_t)p_meta->ch[i].b_codes);
+    }
+    return (uint32_t)WAVE_ST_OFF_TBL + tbl_n;
+}
+
+/*
+ * 函数功能：编码段头（固定头 + 通道表 + 头 CRC）
+ * 入口参数：p_meta  段头元数据；p_out 输出缓冲；a_cap 容量
+ * 返 回 值：>= 0 写入字节数；负 = WAVE_ST_E_*  int
+ * 限定条件：任意上下文；无静态缓冲、可重入
+ * 函数说明：头 CRC 覆盖 [0, 30+12×ch_count)、自身紧随其后、低字节在前（§6.3）。
+ */
+int wave_store_head_build(const wave_seg_meta_t *p_meta, uint8_t *p_out, uint32_t a_cap) {
+    uint32_t crc_pos;
+    uint16_t crc;
+    int rc;
+
+    if ((p_meta == NULL) || (p_out == NULL)) {
+        return WAVE_ST_E_PARAM;
+    }
+    rc = wave_st_meta_check(p_meta);
+    if (rc != WAVE_ST_OK) {
+        return rc;
+    }
+    crc_pos = WAVE_ST_HEAD_CRC_POS(p_meta->ch_count);
+    if (a_cap < (crc_pos + 2u)) {
+        return WAVE_ST_E_PARAM;
+    }
+    (void)wave_st_head_raw(p_meta, p_out);
+    crc = wave_store_crc(p_out, crc_pos);
+    /* 低字节在前（§6.3 首行）：put16 本来就是小端，这里不额外翻转 */
+    wave_st_put16(&p_out[crc_pos], crc);
+    return (int)(crc_pos + 2u);
+}
+
+/*
+ * 函数功能：解码 + 全套判废（魔数 / 版本 / 缓冲长度 / 几何 / 表序 / 头 CRC）
+ * 入口参数：p_buf 头字节流；a_len 可读字节数；p_meta 输出
+ * 返 回 值：WAVE_ST_OK 或 WAVE_ST_E_*（见 wave_store.h）  int
+ * 限定条件：任意上下文
+ * 函数说明：顺序刻意是「先验魔数与版本，再算整头长度，再验 CRC，最后验语义」——
+ *           前两步决定我们**有没有资格**按这份布局去数偏移；反过来先按 ch_count 算长度，
+ *           一个被写坏的 ch_count 就能让我们读到缓冲外面去。
+ */
+int wave_store_head_parse(const uint8_t *p_buf, uint32_t a_len, wave_seg_meta_t *p_meta) {
+    uint8_t ch_count;
+    uint32_t crc_pos;
+    uint32_t head_sz;
+    uint16_t want;
+    uint16_t got;
+    int rc;
+    wave_seg_meta_t tmp;
+
+    if ((p_buf == NULL) || (p_meta == NULL)) {
+        return WAVE_ST_E_PARAM;
+    }
+    /* 固定头是 30 + 1 字节通道数才能算出整头长度，至少得读到偏移 7 */
+    if (a_len < ((uint32_t)WAVE_ST_OFF_CH_CNT + 1u)) {
+        return WAVE_ST_E_PARAM;
+    }
+    if ((p_buf[WAVE_ST_OFF_MAGIC] != (uint8_t)WAVE_ST_MAGIC0) ||
+        (p_buf[WAVE_ST_OFF_MAGIC + 1u] != (uint8_t)WAVE_ST_MAGIC1)) {
+        return WAVE_ST_E_FORMAT;
+    }
+    /* ver 必须等于魔数第三字节、且等于本层认识的版本（§6.2 末行） */
+    if ((p_buf[WAVE_ST_OFF_VER] != p_buf[WAVE_ST_OFF_MAGIC + 2u]) ||
+        (p_buf[WAVE_ST_OFF_VER] != (uint8_t)WAVE_ST_VER)) {
+        return WAVE_ST_E_FORMAT;
+    }
+    ch_count = p_buf[WAVE_ST_OFF_CH_CNT];
+    head_sz = wave_store_head_bytes(ch_count);
+    if (head_sz == 0u) {
+        return WAVE_ST_E_SIZE;
+    }
+    if (a_len < head_sz) {
+        return WAVE_ST_E_PARAM;
+    }
+    crc_pos = WAVE_ST_HEAD_CRC_POS(ch_count);
+    want = wave_st_get16(&p_buf[crc_pos]);
+    got = wave_store_crc(p_buf, crc_pos);
+    if (want != got) {
+        return WAVE_ST_E_CRC;
+    }
+
+    /* 头 CRC 过了才开始解释字段：下面填的是一份可交回调用方的完整元数据 */
+    tmp.fs_hz = wave_st_get16(&p_buf[WAVE_ST_OFF_FS_HZ]);
+    tmp.pts_per_cycle = p_buf[WAVE_ST_OFF_PTS_CYC];
+    tmp.ch_count = ch_count;
+    tmp.pts_per_ch = wave_st_get16(&p_buf[WAVE_ST_OFF_PTS_CH]);
+    tmp.pre_pts = wave_st_get16(&p_buf[WAVE_ST_OFF_PRE_PTS]);
+    tmp.trig_src = p_buf[WAVE_ST_OFF_TRIG_SRC];
+    tmp.trig_elm = p_buf[WAVE_ST_OFF_TRIG_ELM];
+    tmp.t0_ms = wave_st_get32(&p_buf[WAVE_ST_OFF_T0_MS]);
+    tmp.wall = wave_st_get32(&p_buf[WAVE_ST_OFF_WALL]);
+    tmp.eng = p_buf[WAVE_ST_OFF_ENG];
+    tmp.flags_seq = p_buf[WAVE_ST_OFF_FLAGS];
+    tmp.clip_mask = wave_st_get16(&p_buf[WAVE_ST_OFF_CLIP]);
+    tmp.frame_seq = wave_st_get32(&p_buf[WAVE_ST_OFF_SEQ]);
+    for (ch_count = 0u; ch_count < (uint8_t)WAVE_ST_CH_MAX; ch_count++) {
+        tmp.ch[ch_count].sem = 0u;
+        tmp.ch[ch_count].conv = 0u;
+        tmp.ch[ch_count].bits = 0u;
+        tmp.ch[ch_count].avail = 0u;
+        tmp.ch[ch_count].k_q16 = 0;
+        tmp.ch[ch_count].b_codes = 0;
+    }
+    for (ch_count = 0u; ch_count < p_buf[WAVE_ST_OFF_CH_CNT]; ch_count++) {
+        uint32_t pos = (uint32_t)WAVE_ST_OFF_TBL + ((uint32_t)ch_count * WAVE_ST_CH_BYTES);
+        tmp.ch[ch_count].sem = p_buf[pos + WAVE_ST_CH_OFF_SEM];
+        tmp.ch[ch_count].conv = p_buf[pos + WAVE_ST_CH_OFF_CONV];
+        tmp.ch[ch_count].bits = p_buf[pos + WAVE_ST_CH_OFF_BITS];
+        tmp.ch[ch_count].avail = p_buf[pos + WAVE_ST_CH_OFF_AVAIL];
+        tmp.ch[ch_count].k_q16 = (int32_t)wave_st_get32(&p_buf[pos + WAVE_ST_CH_OFF_KQ16]);
+        tmp.ch[ch_count].b_codes = (int32_t)wave_st_get32(&p_buf[pos + WAVE_ST_CH_OFF_BCODE]);
+    }
+    rc = wave_st_meta_check(&tmp);
+    if (rc != WAVE_ST_OK) {
+        return rc;
+    }
+    *p_meta = tmp;
+    return WAVE_ST_OK;
+}
+
+/* ===== 长度 / 偏移换算 ===== */
+
+/*
+ * 函数功能：整头字节数
+ * 入口参数：a_ch_count 通道数
+ * 返 回 值：字节数；通道数非法返回 0  uint32_t
+ * 限定条件：任意上下文
+ */
+uint32_t wave_store_head_bytes(uint8_t a_ch_count) {
+    if ((a_ch_count == 0u) || (a_ch_count > (uint8_t)WAVE_ST_CH_MAX)) {
+        return 0u;
+    }
+    return WAVE_ST_HEAD_BYTES(a_ch_count);
+}
+
+/*
+ * 函数功能：按头部字段算整段应有字节数
+ * 入口参数：p_meta 段头
+ * 返 回 值：期望字节数；字段非法返回 0  uint32_t
+ * 限定条件：任意上下文
+ * 函数说明：等式 = 32 + 12×ch_count + pts_per_ch×ch_count×2 + 2（§6.3；
+ *           8 路 320 点 = 5250）。落盘道拿它比对 f_write 写回字节数与 f_size。
+ */
+uint32_t wave_store_seg_size(const wave_seg_meta_t *p_meta) {
+    if (p_meta == NULL) {
+        return 0u;
+    }
+    if ((p_meta->ch_count == 0u) || (p_meta->ch_count > (uint8_t)WAVE_ST_CH_MAX)) {
+        return 0u;
+    }
+    if (p_meta->pts_per_ch == 0u) {
+        return 0u;
+    }
+    return WAVE_ST_SEG_TOTAL(p_meta->ch_count, p_meta->pts_per_ch);
+}
+
+/*
+ * 函数功能：数据区某点的文件绝对偏移
+ * 入口参数：a_ch_count 通道数；a_pts_ch 每通道点数；a_ch 列号；a_pt 段内点下标
+ * 返 回 值：偏移；非法返回 0xFFFFFFFFu 哨兵  uint32_t
+ * 限定条件：任意上下文
+ * 函数说明：按通道分列 → 偏移 = 整头长 + (列 × 点数 + 点下标) × 2。单通道整列是连续的，
+ *           这正是 §6.2「只读那一路」能一次连续读的原因。
+ */
+uint32_t wave_store_data_off(uint8_t a_ch_count, uint16_t a_pts_ch,
+                             uint8_t a_ch, uint32_t a_pt) {
+    uint32_t head_sz = wave_store_head_bytes(a_ch_count);
+
+    if ((head_sz == 0u) || (a_pts_ch == 0u) || (a_ch >= a_ch_count)) {
+        return WAVE_ST_BAD_OFF;
+    }
+    if (a_pt >= (uint32_t)a_pts_ch) {
+        return WAVE_ST_BAD_OFF;
+    }
+    return head_sz + (((uint32_t)a_ch * (uint32_t)a_pts_ch) + a_pt) * 2u;
+}
+
+/*
+ * 函数功能：从某点起当前列还能连续读多少字节
+ * 入口参数：a_pts_ch 每通道点数；a_pt 起始点下标；a_want 想读点数
+ * 返 回 值：可连续读字节数（参数非法返回 0）  uint32_t
+ * 限定条件：任意上下文
+ */
+uint32_t wave_store_data_bytes_avail(uint16_t a_pts_ch, uint32_t a_pt, uint32_t a_want) {
+    uint32_t left;
+    uint32_t n;
+
+    if ((a_pts_ch == 0u) || (a_want == 0u)) {
+        return 0u;
+    }
+    if (a_pt >= (uint32_t)a_pts_ch) {
+        return 0u;
+    }
+    left = (uint32_t)a_pts_ch - a_pt;
+    n = (a_want < left) ? a_want : left;
+    return n * 2u;
+}
+
+/*
+ * 函数功能：小端字节 → int16 点序列
+ * 入口参数：p_raw 原始字节；a_len 字节数；p_out 输出；a_max_pts 容量；p_pts 实际点数（可空）
+ * 返 回 值：WAVE_ST_OK；WAVE_ST_E_PARAM 空指针 / 奇数字节 / 容量不足  int
+ * 限定条件：任意上下文
+ * 函数说明：奇数字节按参数错处理而不是「丢掉尾巴」——半截样本被静默吞掉，
+ *           回放页画出来的波形会比真的少最后一个点，而这种误差正好最难查。
+ */
+int wave_store_le_decode(const uint8_t *p_raw, uint32_t a_len,
+                         int16_t *p_out, uint32_t a_max_pts, uint32_t *p_pts) {
+    uint32_t n;
+    uint32_t i;
+
+    if ((p_raw == NULL) || (p_out == NULL)) {
+        return WAVE_ST_E_PARAM;
+    }
+    if (((a_len & 0x00000001u) != 0u) || (a_len > (a_max_pts * 2u))) {
+        return WAVE_ST_E_PARAM;
+    }
+    n = a_len / 2u;
+    for (i = 0u; i < n; i++) {
+        /* 先攒成 uint16 再转 int16：补码回绕在 C 里是实现定义但两大编译器一致，
+         * 而这里需要的正是「按补码位型解释」——TPAFE 的 16 位补码就是这么存的 */
+        p_out[i] = (int16_t)wave_st_get16(&p_raw[i * 2u]);
+    }
+    if (p_pts != NULL) {
+        *p_pts = n;
+    }
+    return WAVE_ST_OK;
+}
+
+/*
+ * 函数功能：码值 → 定点毫单位（mV）
+ * 入口参数：p_desc 通道表项（必须来自段文件头）；a_code 码值；p_milli 输出 mV
+ * 返 回 值：WAVE_ST_OK；WAVE_ST_E_PARAM 空指针  int
+ * 限定条件：任意上下文（只在回放页与单测用，不在 1 kHz 采集链上；用 int64 中间量）
+ * 函数说明：模型 eng = (code + b) × k × 1e-6（§6.3，与 adc_cal_apply() 同式），
+ *           k = k_q16 / 65536 µV/码 → mV = (code + b) × k_q16 / 65536000，四舍五入。
+ *           中间量最大约 (32767 + 8192) × 5.28e7 ≈ 2.2e12，int64 宽裕。
+ */
+int wave_store_code_to_milli(const wave_ch_desc_t *p_desc, int16_t a_code,
+                             int32_t *p_milli) {
+    int64_t num;
+    int64_t den = 65536000;
+    int64_t v;
+
+    if ((p_desc == NULL) || (p_milli == NULL)) {
+        return WAVE_ST_E_PARAM;
+    }
+    num = ((int64_t)a_code + (int64_t)p_desc->b_codes) * (int64_t)p_desc->k_q16;
+    if (num >= 0) {
+        v = (num + (den / 2)) / den;
+    } else {
+        v = -(((-num) + (den / 2)) / den);
+    }
+    *p_milli = (int32_t)v;
+    return WAVE_ST_OK;
+}
+
+/* ===== 整段校验 ===== */
+
+/*
+ * 函数功能：整段镜像自检（头 + 数据区 + 数据 CRC）
+ * 入口参数：p_img 镜像；a_len 长度；p_meta 输出段头（可空）
+ * 返 回 值：WAVE_ST_OK 或 WAVE_ST_E_*（见 wave_store.h）  int
+ * 限定条件：任意上下文；整段驻留时用（本波 5250 字节）
+ * 函数说明：三条判废一条都不能省：长度 0 或不等、头 CRC、数据 CRC。
+ *           期望总长用**头里的字段**算，不用编译期常量——文件是自己说它多长，
+ *           与镜像实际长度不一致就是坏段（§6.2 末行）。
+ */
+int wave_store_seg_check(const uint8_t *p_img, uint32_t a_len, wave_seg_meta_t *p_meta) {
+    wave_seg_meta_t meta;
+    uint32_t want_total;
+    uint32_t data_off;
+    uint32_t data_len;
+    uint16_t want;
+    uint16_t got;
+    int rc;
+
+    if (p_img == NULL) {
+        return WAVE_ST_E_PARAM;
+    }
+    if (a_len == 0u) {
+        return WAVE_ST_E_SIZE;
+    }
+    rc = wave_store_head_parse(p_img, a_len, &meta);
+    if (rc != WAVE_ST_OK) {
+        return rc;
+    }
+    want_total = wave_store_seg_size(&meta);
+    if (want_total == 0u) {
+        return WAVE_ST_E_SIZE;
+    }
+    if (a_len != want_total) {
+        return WAVE_ST_E_SIZE;
+    }
+    data_off = wave_store_head_bytes(meta.ch_count);   /* 数据区起点 = 整头字节数 */
+    data_len = a_len - 2u - data_off;
+    if (data_len == 0u) {
+        return WAVE_ST_E_SIZE;
+    }
+    want = wave_st_get16(&p_img[a_len - 2u]);
+    got = wave_store_crc(&p_img[data_off], data_len);
+    if (want != got) {
+        return WAVE_ST_E_CRC;
+    }
+    if (p_meta != NULL) {
+        *p_meta = meta;
+    }
+    return WAVE_ST_OK;
+}
+
+/* ===== 打包游标 ===== */
+
+/*
+ * 函数功能：初始化打包游标
+ * 入口参数：p_ctx 游标；p_meta 段头；p_reader 数据源（可空 = 只产头）；p_user 上下文
+ * 返 回 值：WAVE_ST_OK 或 WAVE_ST_E_*  int
+ * 限定条件：任意上下文（纯计算）；一段一个游标
+ * 函数说明：段头整份拷进游标——搬运窗口几十毫秒，期间调用方完全可以去改它自己那份
+ *           （比如 adcTask 又跑了几拍），本段的字节不能受影响。
+ */
+int wave_store_pack_start(wave_pack_ctx_t *p_ctx, const wave_seg_meta_t *p_meta,
+                          wave_reader_fn p_reader, void *p_user) {
+    int rc;
+
+    if ((p_ctx == NULL) || (p_meta == NULL)) {
+        return WAVE_ST_E_PARAM;
+    }
+    rc = wave_st_meta_check(p_meta);
+    if (rc != WAVE_ST_OK) {
+        p_ctx->phase = (uint8_t)WAVE_PACK_IDLE;
+        return rc;
+    }
+    p_ctx->total = wave_store_seg_size(p_meta);
+    if (p_ctx->total == 0u) {
+        p_ctx->phase = (uint8_t)WAVE_PACK_IDLE;
+        return WAVE_ST_E_SIZE;
+    }
+    p_ctx->phase = (uint8_t)WAVE_PACK_HEAD;
+    p_ctx->ch = 0u;
+    p_ctx->head_done = 0u;
+    p_ctx->ch_done = 0u;
+    p_ctx->tail_done = 0u;
+    p_ctx->rsv = 0u;
+    p_ctx->crc_data = WAVE_ST_CRC_INIT;
+    p_ctx->sent = 0u;
+    p_ctx->p_reader = p_reader;
+    p_ctx->p_user = p_user;
+    p_ctx->meta = *p_meta;
+    return WAVE_ST_OK;
+}
+
+/*
+ * 函数功能：取整段字节流的下一片
+ * 入口参数：p_ctx 游标；p_out 缓冲；a_cap 容量；p_len 实际产出字节数
+ * 返 回 值：WAVE_ST_OK 还有后续；WAVE_ST_DONE 整段产完；负 = WAVE_ST_E_*  int
+ * 限定条件：任意上下文，同一游标不得并发使用
+ * 函数说明：三段推进——头（一次给完，要求容量 >= 整头）、数据区（按列连续、整样本切，
+ *           绝不切半个 int16，也不跨列，便于回调按列读）、尾 CRC 两字节。
+ *           数据 CRC 边产边算（增量中间值），所以全程不需要整段驻留 RAM。
+ */
+int wave_store_pack_next(wave_pack_ctx_t *p_ctx, uint8_t *p_out,
+                         uint32_t a_cap, uint32_t *p_len) {
+    uint32_t n = 0u;
+
+    if ((p_ctx == NULL) || (p_out == NULL) || (p_len == NULL)) {
+        return WAVE_ST_E_PARAM;
+    }
+    *p_len = 0u;
+    if ((p_ctx->phase == (uint8_t)WAVE_PACK_IDLE) || (a_cap == 0u)) {
+        return WAVE_ST_E_STATE;
+    }
+    if (p_ctx->phase == (uint8_t)WAVE_PACK_DONE) {
+        return WAVE_ST_DONE;
+    }
+
+    /* --- 头：整头一次产完（接线索按 §7 给 256 字节缓冲，足够 128 字节整头） --- */
+    if (p_ctx->phase == (uint8_t)WAVE_PACK_HEAD) {
+        uint32_t head_sz;
+        int rc;
+
+        head_sz = wave_store_head_bytes(p_ctx->meta.ch_count);
+        if (head_sz == 0u) {
+            return WAVE_ST_E_SIZE;
+        }
+        if (a_cap < head_sz) {
+            /* 不拆着头给：半截头意味着游标要存 128 字节中间态，纯浪费 */
+            return WAVE_ST_E_PARAM;
+        }
+        rc = wave_store_head_build(&p_ctx->meta, p_out, a_cap);
+        if (rc < 0) {
+            return rc;
+        }
+        n = (uint32_t)rc;
+        p_ctx->head_done = (uint16_t)n;
+        p_ctx->sent += n;
+        *p_len = n;
+        p_ctx->phase = (uint8_t)WAVE_PACK_DATA;
+        return WAVE_ST_OK;
+    }
+
+    /* --- 数据区：按列推进，一次最多一批 --- */
+    if (p_ctx->phase == (uint8_t)WAVE_PACK_DATA) {
+        int16_t batch[WAVE_ST_BATCH];
+
+        if (p_ctx->p_reader == NULL) {
+            /* 没有数据源却进了数据区：宁可报错也不产空字节。
+             * 产空字节会写出「长度对、内容是 0」的段文件，回放页会画出一条直线——
+             * 那正是 §8.1 明令禁止的伪造证据形态。 */
+            return WAVE_ST_E_STATE;
+        }
+        while ((n < a_cap) && (p_ctx->ch < p_ctx->meta.ch_count)) {
+            uint32_t room_pts = (a_cap - n) / 2u;
+            uint32_t col_left = (uint32_t)p_ctx->meta.pts_per_ch - (uint32_t)p_ctx->ch_done;
+            uint32_t take;
+            int32_t got;
+            uint32_t i;
+
+            if (col_left == 0u) {
+                p_ctx->ch++;
+                p_ctx->ch_done = 0u;
+                continue;
+            }
+            if (room_pts == 0u) {
+                break;
+            }
+            take = (room_pts < col_left) ? room_pts : col_left;
+            if (take > (uint32_t)WAVE_ST_BATCH) {
+                take = (uint32_t)WAVE_ST_BATCH;
+            }
+            got = p_ctx->p_reader(p_ctx->p_user, p_ctx->ch, (uint32_t)p_ctx->ch_done,
+                                  take, batch);
+            if (got < 0) {
+                return (int)got;
+            }
+            if ((uint32_t)got != take) {
+                /* 数据源给不满就是数据源的问题（越界 / 未封存），不拿半批凑长度 */
+                return WAVE_ST_E_STATE;
+            }
+            uint32_t base_n = n;
+            for (i = 0u; i < take; i++) {
+                wave_st_put_code(&p_out[n], batch[i]);
+                n += 2u;
+            }
+            p_ctx->crc_data = wave_store_crc_update(p_ctx->crc_data, &p_out[base_n], take * 2u);
+            p_ctx->ch_done = (uint16_t)((uint32_t)p_ctx->ch_done + take);
+        }
+        if (p_ctx->ch >= p_ctx->meta.ch_count) {
+            /* 最后一列的最后一点产出后，「列走完了」要到下一次进循环才发现，
+             * 所以这一拍可能一个字节都没产。这时候不许当参数错报出去：整段就差
+             * 最后两片 CRC，报 E_PARAM 会让落盘道把一次真故障判成落盘失败（白丢）。
+             * 让它落到下面的尾段分支，在同一次调用里把尾产完。 */
+            p_ctx->phase = (uint8_t)WAVE_PACK_TAIL;
+        }
+        p_ctx->sent += n;
+        *p_len = n;
+        if (n > 0u) {
+            return WAVE_ST_OK;
+        }
+        if (p_ctx->phase != (uint8_t)WAVE_PACK_TAIL) {
+            return WAVE_ST_E_PARAM;   /* 容量连一个整样本都装不下 */
+        }
+    }
+
+    /* --- 尾：数据区 CRC，低字节在前 --- */
+    if (p_ctx->phase == (uint8_t)WAVE_PACK_TAIL) {
+        if (p_ctx->tail_done == 0u) {
+            p_out[n] = (uint8_t)(p_ctx->crc_data & 0xFFu);
+            n++;
+            p_ctx->tail_done = 1u;
+        }
+        if ((p_ctx->tail_done == 1u) && (n < a_cap)) {
+            p_out[n] = (uint8_t)((p_ctx->crc_data >> 8) & 0xFFu);
+            n++;
+            p_ctx->tail_done = 2u;
+            p_ctx->phase = (uint8_t)WAVE_PACK_DONE;
+        }
+        p_ctx->sent += n;
+        *p_len = n;
+        return (p_ctx->phase == (uint8_t)WAVE_PACK_DONE) ? WAVE_ST_DONE : WAVE_ST_OK;
+    }
+    return WAVE_ST_E_STATE;
+}
+
+/*
+ * 函数功能：游标已产出字节数
+ * 入口参数：p_ctx 游标
+ * 返 回 值：字节数；空指针返回 0  uint32_t
+ * 限定条件：任意上下文（只读）
+ */
+uint32_t wave_store_pack_offset(const wave_pack_ctx_t *p_ctx) {
+    return (p_ctx == NULL) ? 0u : p_ctx->sent;
+}
+
+/*
+ * 函数功能：游标对应整段的期望总长
+ * 入口参数：p_ctx 游标
+ * 返 回 值：字节数；空指针返回 0  uint32_t
+ * 限定条件：任意上下文（只读）
+ */
+uint32_t wave_store_pack_total(const wave_pack_ctx_t *p_ctx) {
+    return (p_ctx == NULL) ? 0u : p_ctx->total;
+}
+
+/* ===== 段文件名轮转（只算名字，不碰文件系统） ===== */
+
+/*
+ * 函数功能：内部——把两位十进制写进缓冲
+ * 入口参数：p 目标（至少 2 字节）；a_idx 0..99
+ * 返 回 值：无  void
+ * 限定条件：a_idx 已由调用方限制在 0..99
+ */
+static void wave_st_put_idx2(char *p, uint8_t a_idx) {
+    p[0] = (char)('0' + (a_idx / 10u));
+    p[1] = (char)('0' + (a_idx % 10u));
+}
+
+/*
+ * 函数功能：按段号生成段文件路径
+ * 入口参数：p_out 缓冲；a_cap 容量；a_idx 段号 0..99
+ * 返 回 值：>= 0 写入字符数（不含结束符）；WAVE_ST_E_PARAM / WAVE_ST_E_RANGE  int
+ * 限定条件：任意上下文；纯字符拼装（不用格式化函数），板端与 PC 侧逐字节一致
+ * 函数说明：形态 = 目录 / 前缀 + 两位十进制 + 扩展名，严格 8.3（§5.2 第三条）。
+ */
+int wave_store_seg_path(char *p_out, uint32_t a_cap, uint8_t a_idx) {
+    static const char s_dir[] = WAVE_ST_DIR;
+    static const char s_pfx[] = WAVE_ST_PFX;
+    static const char s_ext[] = WAVE_ST_EXT;
+    uint32_t pos = 0u;
+    uint32_t i;
+    char buf[WAVE_ST_PATH_MAX];
+
+    if (p_out == NULL) {
+        return WAVE_ST_E_PARAM;
+    }
+    if (a_idx >= (uint8_t)WAVE_ST_SEG_MAX) {
+        return WAVE_ST_E_RANGE;
+    }
+    for (i = 0u; i < ((uint32_t)sizeof(s_dir) - 1u); i++) {
+        buf[pos++] = s_dir[i];
+    }
+    buf[pos++] = '/';
+    for (i = 0u; i < ((uint32_t)sizeof(s_pfx) - 1u); i++) {
+        buf[pos++] = s_pfx[i];
+    }
+    wave_st_put_idx2(&buf[pos], a_idx);
+    pos += 2u;
+    for (i = 0u; i < ((uint32_t)sizeof(s_ext) - 1u); i++) {
+        buf[pos++] = s_ext[i];
+    }
+    if (pos >= (uint32_t)sizeof(buf)) {
+        /* 宏与拼装长度漂移时的兜底：宁可给不出名字，也绝不把结束符写到别人缓冲外 */
+        return WAVE_ST_E_SIZE;
+    }
+    buf[pos] = '\0';
+    /* 容量必须容得下结束符：写成 a_cap < pos 会放过「刚好差一个字节」的调用方，
+     * 于是把 p_out[pos] 写到别人缓冲外面（越界写在板子上是静默的） */
+    if (a_cap <= pos) {
+        return WAVE_ST_E_PARAM;
+    }
+    for (i = 0u; i <= pos; i++) {
+        p_out[i] = buf[i];
+    }
+    return (int)pos;
+}
+
+/*
+ * 函数功能：下一个轮转段号
+ * 入口参数：a_idx 当前段号（越界按 0 处理）
+ * 返 回 值：下一个段号  uint8_t
+ * 限定条件：任意上下文
+ */
+uint8_t wave_store_next_idx(uint8_t a_idx) {
+    if (a_idx >= (uint8_t)WAVE_ST_SEG_MAX) {
+        return 0u;
+    }
+    if (a_idx >= ((uint8_t)WAVE_ST_SEG_MAX - 1u)) {
+        return 0u;
+    }
+    return (uint8_t)(a_idx + 1u);
+}
+
+/*
+ * 函数功能：内部——大小写无关地比对一个字符
+ * 入口参数：a 待测字符（视作 ASCII）；b 期望字符（取自段名宏）
+ * 返 回 值：1 相同；0 不同  uint8_t
+ * 限定条件：两侧都是 ASCII；非字母字符原样比
+ * 函数说明：**两侧都**归一化成小写再比。只归一化一侧是个真踩过一次的坑——
+ *           段名宏 WAVE_ST_PFX / WAVE_ST_EXT 是大写形态（FatFs 8.3 短名就是大写），
+ *           只把待测串转小写等于「小写 vs 大写」永不相等，反解会拒绝掉全部合法段名
+ *           （单测 用例：首轮 100% 拒绝就是这个）。盘上大小写与宏写法
+ *           谁都不该去猜，故两侧各归一一次。
+ */
+static uint8_t wave_st_ci_eq(char a, char b) {
+    char x = a;
+    char y = b;
+
+    if ((x >= 'A') && (x <= 'Z')) {
+        x = (char)(x + ('a' - 'A'));
+    }
+    if ((y >= 'A') && (y <= 'Z')) {
+        y = (char)(y + ('a' - 'A'));
+    }
+    return (x == y) ? 1u : 0u;
+}
+
+/*
+ * 函数功能：从文件名或路径反解段号
+ * 入口参数：p_path 路径或纯文件名；p_idx 输出
+ * 返 回 值：WAVE_ST_OK；WAVE_ST_E_PARAM 空指针；WAVE_ST_E_NAME 不是本层命名形态  int
+ * 限定条件：任意上下文
+ * 函数说明：只认 basename 上的「wave + 两位数字 + .bin」（大小写都收）。
+ *           不匹配就返回错误，**绝不**把陌生名字当录波段——扫目录重建段账时误认一个
+ *           别的文件，等于把别人的文件当波形解释（名字/参数类错误码严禁升级成卷操作，
+ *           存储架构说明 §10.1 同一条教训）。
+ */
+int wave_store_idx_from_name(const char *p_path, uint8_t *p_idx) {
+    static const char s_pfx[] = WAVE_ST_PFX;
+    static const char s_ext[] = WAVE_ST_EXT;
+    const char *base = p_path;
+    const char *q = p_path;
+    uint32_t i;
+    uint32_t len = 0u;
+    uint8_t hi;
+    uint8_t lo;
+
+    if ((p_path == NULL) || (p_idx == NULL)) {
+        return WAVE_ST_E_PARAM;
+    }
+    /* 找 basename：支持反斜杠形态（PC 侧脚本拼出来的路径可能被原样传进来） */
+    while (*q != '\0') {
+        if ((*q == '/') || (*q == '\\')) {
+            base = q + 1;
+        }
+        q++;
+    }
+    q = base;
+    while ((*q != '\0') && (len < (uint32_t)WAVE_ST_PATH_MAX)) {
+        q++;
+        len++;
+    }
+    if ((*q != '\0') || (len != ((uint32_t)sizeof(s_pfx) - 1u) + 2u +
+                          ((uint32_t)sizeof(s_ext) - 1u))) {
+        return WAVE_ST_E_NAME;
+    }
+    for (i = 0u; i < ((uint32_t)sizeof(s_pfx) - 1u); i++) {
+        if (wave_st_ci_eq(base[i], s_pfx[i]) == 0u) {
+            return WAVE_ST_E_NAME;
+        }
+    }
+    hi = (uint8_t)base[i];
+    lo = (uint8_t)base[i + 1u];
+    if ((hi < '0') || (hi > '9') || (lo < '0') || (lo > '9')) {
+        return WAVE_ST_E_NAME;
+    }
+    for (i = (i + 2u); i < len; i++) {
+        if (wave_st_ci_eq(base[i], s_ext[i - ((uint32_t)sizeof(s_pfx) - 1u) - 2u]) == 0u) {
+            return WAVE_ST_E_NAME;
+        }
+    }
+    *p_idx = (uint8_t)(((hi - '0') * 10u) + (lo - '0'));
+    return WAVE_ST_OK;
+}
@@ -0,0 +1,491 @@
+/*
+ * 模块名称：录波段格式层（故障录波 · 段文件字节布局编解码 + 打包游标 + 段名轮转）
+ * 模块功能：把「一段录波」在内存字节缓冲与结构化元数据之间逐字节翻译，并给落盘道
+ *           提供分次搬运的打包游标。口径唯一属主 = docs/子系统设计/故障录波设计说明.md §6.2
+ *           （字节布局）与 §6.3（九问裁定：板端编码器与 PC 解码器 test/host/wave_read.py
+ *           两份独立实现的共同依据）。本文件是它的机器可执行形态，不在此重新定义任何口径；
+ *           两处冲突以设计文档为准并回报 lead，不在代码里单方面「修正」。
+ *           纯逻辑层纪律：不 include HAL / CMSIS / RTOS 头、不调 FatFs、不碰文件系统、
+ *           不建任务、不打日志（文件 I/O 与任务钩子全在接线层 App/task/ 里做），
+ *           因此可被主机侧单测 test/host/wave_store/ 原样纳入做逐字节断言。
+ *         职责边界（为什么这样切）：
+ *           1) 固定头 + 通道表编解码、头 CRC 与数据区 CRC 自检 —— 格式知识只此一处；
+ *           2) 打包游标（分次搬运）：文件系统唯一写者只要「每次给我不超过 256 字节的下一片」，
+ *              整段 5250 字节不驻留 RAM（设计说明 §7：搬运缓冲 256 B × 2，不做整段驻留）；
+ *           3) 段文件名轮转与反解：只算名字，不打开文件（FatFs FF_USE_LFN=0 只能严格
+ *              8.3 短名，见 docs/架构设计/STM32F4-Base存储架构说明.md §10.1）；
+ *           4) 数据区偏移换算 + 小端解码：回放页只画一路（设计说明 §8.1），按通道分列
+ *              让「只读那一路」成为一次连续读。
+ *         不链 App/algo/adc_cal（零依赖 = 主机免桩可测）：通道表里的 k_q16 / b_codes /
+ *         可用性由调用方在封存瞬间取 int32 原值填进 meta 后交给本层编码。系数必须走
+ *         adc_cal_k_q16()（接线道补的 int32 直读入口），不得经 adc_cal_k_uv() 的 float
+ *         通道回算 —— float 在 5.28e7 量级掉尾数（设计说明 §6.3「k / b 宽度与角色」行）。
+ *         CRC 一张表的原始说法不成立，lead 已在 §6.3 记录实测依据：全仓无可复用的
+ *         CRC-16 表（App/util/README.md 记 crc.c 与 crc.h 已于 2026-10-02 删除；屏板链路
+ *         Drivers/BSP/UI/ui_net_sink.c 的 remo_crc() 是单字节异或、不是 CRC-16）。
+ *         故本层自带无表位运算 CRC-16/MODBUS，并用规范锚点自校验。
+ * 适用平台：STM32F407ZGTx（Cortex-M4，小端）；主机侧单测 test/host/wave_store/
+ * 作者：DTU 项目组
+ * 创建日期：2026-10-29（故障录波 task-1 · 数据面纯逻辑层）
+ * 修改记录：
+ *   v1.0  2026-10-29  DTU 项目组  创建：段头/通道表编解码、CRC-16/MODBUS 无表实现、
+ *                                 打包游标、段名轮转与反解、数据区偏移换算与小端解码
+ *
+ * 二期不返工的结构约束（设计说明 §2.1，改本层前先读）：
+ *   1) 采样率与每周波点数是写进文件头的数据，不是编译期假设 —— 回放端与 PC 脚本一律
+ *      从头里读，本层算长度也照 meta 里的值算，不在代码里写死 1000 / 20；
+ *   2) 版本号并进魔数第三字节，换格式即变；本层解到不认识的版本一律判废；
+ *   3) 「带 TEMP 就要连 flags_seq 与 clip_mask 一起升版本」同源（§6.2 那两行的括注），
+ *      所以本层的通道数上限留到 9，但本波实际只用 8。
+ */
+
+#ifndef WAVE_STORE_H
+#define WAVE_STORE_H
+
+/* 同 App/algo/wave_ring.h：本头的 NULL 只出现在注释里（字段与入参的约束说明），
+ * 代码只用 stdint 的类型，故不 include stddef.h；用 NULL 的 .c 自己带。 */
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* ===== 一、段文件布局常量（逐字段照 docs/子系统设计/故障录波设计说明.md §6.2 与 §6.3） ===== */
+
+/* 魔数前两字节固定 'W' 与 'R'，第三字节 = 版本号（设计说明 §6.2 偏移 0 行） */
+#define WAVE_ST_MAGIC0        (0x57u)     /* 'W' */
+#define WAVE_ST_MAGIC1        (0x52u)     /* 'R' */
+/* 版本：本波恒 1。ver 字段必须同时等于魔数第三字节与本宏，否则整段判废（§6.2 末行） */
+#define WAVE_ST_VER           (1u)
+
+/* 固定头字段偏移（字节，小端） */
+#define WAVE_ST_OFF_MAGIC     (0u)        /* 3 字节：'W' 'R' ver */
+#define WAVE_ST_OFF_VER       (3u)        /* 1 字节 */
+#define WAVE_ST_OFF_FS_HZ     (4u)        /* 2 字节 本波 1000 */
+#define WAVE_ST_OFF_PTS_CYC   (6u)        /* 1 字节 本波 20 */
+#define WAVE_ST_OFF_CH_CNT    (7u)        /* 1 字节 本波 8 */
+#define WAVE_ST_OFF_PTS_CH    (8u)        /* 2 字节 本波 320 */
+#define WAVE_ST_OFF_PRE_PTS   (10u)       /* 2 字节 本波 160 */
+#define WAVE_ST_OFF_TRIG_SRC  (12u)       /* 1 字节 */
+#define WAVE_ST_OFF_TRIG_ELM  (13u)       /* 1 字节 */
+#define WAVE_ST_OFF_T0_MS     (14u)       /* 4 字节 u32 */
+#define WAVE_ST_OFF_WALL      (18u)       /* 4 字节 u32 */
+#define WAVE_ST_OFF_ENG       (22u)       /* 1 字节 */
+#define WAVE_ST_OFF_FLAGS     (23u)       /* 1 字节 */
+#define WAVE_ST_OFF_CLIP      (24u)       /* 2 字节 */
+#define WAVE_ST_OFF_SEQ       (26u)       /* 4 字节 u32 */
+#define WAVE_ST_OFF_TBL       (30u)       /* 通道表起点 */
+
+/* 通道表一路 12 字节 = 语义号 1 + 来源转换器 1 + 位宽 1 + 可用性 1 + k_q16 4 + b_codes 4
+ * 设计说明 §6.3「LSB 从哪来」：不设独立 LSB 字段，k_q16 就是 LSB（单位 µV/码 × 65536） */
+#define WAVE_ST_CH_OFF_SEM    (0u)        /* 1 字节 */
+#define WAVE_ST_CH_OFF_CONV   (1u)        /* 1 字节 */
+#define WAVE_ST_CH_OFF_BITS   (2u)        /* 1 字节 */
+#define WAVE_ST_CH_OFF_AVAIL  (3u)        /* 1 字节 = adc_cal_flags(sem) 低 8 位原值，不自造位义 */
+#define WAVE_ST_CH_OFF_KQ16   (4u)        /* 4 字节 int32 */
+#define WAVE_ST_CH_OFF_BCODE  (8u)        /* 4 字节 int32 */
+#define WAVE_ST_CH_BYTES      (12u)
+
+/* 本波通道数固定 8（TEMP 不录：理由见 §6.3 末段与 docs/任务规划/数据可信.md §7） */
+#define WAVE_ST_CH_NUM        (8u)
+/* 通道数上限：给二期「带 TEMP 且同时升版本」留位；真正的口径是 meta 里的 ch_count 字段 */
+#define WAVE_ST_CH_MAX        (9u)
+/* 每通道点数默认（= 预触发 + 后触发 = 160 + 160；长度是文件里的数据，宏只作默认值） */
+#define WAVE_ST_PTS_DEF       (320u)
+#define WAVE_ST_PRE_DEF       (160u)
+#define WAVE_ST_FS_DEF        (1000u)
+#define WAVE_ST_PPC_DEF       (20u)
+
+/* 尺寸一律由字段算出，不写死字面量（改通道数/点数时自动跟着走）：
+ *   头 CRC 覆盖区 = 30 + 12 × ch_count；头 CRC 自身紧随其后 2 字节；数据区自 32 + 12 × ch 起
+ * ch_count = 8 时：覆盖区 126、整头 128、数据区 5120、整段 5250（§6.3「CRC 覆盖范围」行） */
+#define WAVE_ST_HEAD_CRC_POS(ch)  ((uint32_t)(WAVE_ST_OFF_TBL) + \
+                                   ((uint32_t)(ch) * WAVE_ST_CH_BYTES))
+#define WAVE_ST_HEAD_BYTES(ch)    ((uint32_t)(WAVE_ST_HEAD_CRC_POS(ch)) + 2u)
+#define WAVE_ST_DATA_BYTES(ch, pts) ((uint32_t)(pts) * (uint32_t)(ch) * 2u)
+#define WAVE_ST_SEG_TOTAL(ch, pts)  (WAVE_ST_HEAD_BYTES(ch) + \
+                                     WAVE_ST_DATA_BYTES(ch, pts) + 2u)
+/* 本波实际值（只给注释与单测引用，代码里一律用上面的参数化形态） */
+#define WAVE_ST_HEAD_SZ_CUR   (128u)
+#define WAVE_ST_SEG_SZ_CUR    (5250u)
+
+/* 段目录与轮转（设计说明 §5.2 第三条：只能严格 8.3 短名；目录与 /log 平级、FTP 根下可见）
+ * 名字形态 = 目录 + 前缀 + 两位十进制 + 扩展名，号 0..99 共 100 个轮转覆盖 */
+#define WAVE_ST_DIR           "/wave"
+#define WAVE_ST_PFX           "WAVE"
+#define WAVE_ST_EXT           ".BIN"
+#define WAVE_ST_SEG_MAX       (100u)
+#define WAVE_ST_PATH_MAX      (17u)       /* /wave/WAVE00.BIN = 16 字符 + 结束符 = 17 字节 */
+
+/* CRC-16/MODBUS：多项式 0x8005 反射形态 = 0xA001、初值 0xFFFF、异或输出 0、低字节在前 */
+#define WAVE_ST_CRC_POLY      (0xA001u)
+#define WAVE_ST_CRC_INIT      (0xFFFFu)
+#define WAVE_ST_CRC_XOROUT    (0x0000u)
+/* 自检锚点：串 123456789 的 CRC（§6.3 首行钉的常量） */
+#define WAVE_ST_CRC_CHECK     (0x4B37u)
+
+/* ===== 二、返回码（int 通道；调用方必须接住或显式 (void)，不得裸丢） ===== */
+
+#define WAVE_ST_OK            (0)         /* 成功 */
+#define WAVE_ST_DONE          (1)         /* 打包游标：整段已产完（不是错误） */
+#define WAVE_ST_E_PARAM       (-1)        /* 空指针 / 容量不足 / 字段非法 */
+#define WAVE_ST_E_CRC         (-2)        /* CRC 不符（头或数据区）：整段判废 */
+#define WAVE_ST_E_FORMAT      (-3)        /* 魔数不符 / 版本不认识 / 表内语义号不等于下标 */
+#define WAVE_ST_E_SIZE        (-4)        /* 长度为 0 或长度与头部字段矛盾：整段判废 */
+#define WAVE_ST_E_RANGE       (-5)        /* 列号 / 点下标 / 段号越界 */
+#define WAVE_ST_E_STATE       (-6)        /* 状态错：未封存就读、未 start 就步进、缺数据源 */
+#define WAVE_ST_E_NAME        (-7)        /* 文件名不是本层命名形态（扫目录重建段账时用） */
+
+/* ===== 三、类型 ===== */
+
+/* 触发源（§6.2 偏移 12 的取值；0 表示「无触发」，只出现在段外的状态查询里） */
+typedef enum {
+    WAVE_TRIG_NONE    = 0,   /* 无 */
+    WAVE_TRIG_MANUAL  = 1,   /* 手动（UI「手动录波」确认，task-2 接线） */
+    WAVE_TRIG_PROTECT = 2,   /* 保护启动（App/algo/prot_elm.c 的 picked 上升沿） */
+    WAVE_TRIG_BENCH   = 3    /* bench 定周期自抓（只在 DTU_BENCH 构建里有这条来路） */
+} wave_trig_src_t;
+
+/* 折算档位（§6.2 偏移 22；单位一律以头里的 eng 为准，PC 不许按当前固件口径猜） */
+typedef enum {
+    WAVE_ENG_PIN      = 0,   /* 引脚域（未标定；V0.1 产品构建停在这档） */
+    WAVE_ENG_SEC      = 1,   /* 二次值 */
+    WAVE_ENG_PRI      = 2    /* 一次值 */
+} wave_eng_t;
+
+/* 通道表一路的内存形态（字段序 = §6.2 通道表字节序） */
+typedef struct {
+    uint8_t sem;             /* 语义号（adc_semantic_t 值；必须等于表内下标，§6.3） */
+    uint8_t conv;            /* 来源转换器（adc_source_t 值：0 = TPAFE，1 = STM32） */
+    uint8_t bits;            /* 转换器输出位宽（TPAFE 16 / STM32 12） */
+    uint8_t avail;           /* 可用性 = adc_cal_flags(sem) 低 8 位原值（不自造位义） */
+    int32_t k_q16;           /* 封存瞬间生效系数：µV/码 × 65536，就是 LSB */
+    int32_t b_codes;         /* 封存瞬间生效零点偏移：码值 */
+} wave_ch_desc_t;
+
+/* 段头元数据 = 固定头 + 通道表的内存形态。
+ * 这是「待编码的段头」，不是「已写盘的证据」：打包游标只读它、不改它。 */
+typedef struct {
+    uint16_t fs_hz;          /* 采样率 Hz（从文件读出来的数据，不是编译期常量） */
+    uint8_t  pts_per_cycle;  /* 每周波点数 */
+    uint8_t  ch_count;       /* 通道数（本波 8） */
+    uint16_t pts_per_ch;     /* 每通道点数（本波 320） */
+    uint16_t pre_pts;        /* 预触发点数（本波 160；回放画触发光标用） */
+    uint8_t  trig_src;       /* 触发源（wave_trig_src_t） */
+    uint8_t  trig_elm;       /* 触发元件序号（prot_elm 实例下标；手动与定时为 0） */
+    uint32_t t0_ms;          /* 段首相对上电毫秒 */
+    uint32_t wall;           /* 对时后的 epoch 秒（未对时 0） */
+    uint8_t  eng;            /* 折算档位（wave_eng_t） */
+    uint8_t  flags_seq;      /* bit s = 语义通道 s 的 ADC_CAL_F_VALID（§6.3） */
+    uint16_t clip_mask;      /* bit s = 语义通道 s 的 ADC_CAL_F_CLIPPED（V0.1 恒 0xE6） */
+    uint32_t frame_seq;      /* 段首帧序号（与串口周期行的 frames 对账） */
+    wave_ch_desc_t ch[WAVE_ST_CH_MAX];   /* 通道表（前 ch_count 项有效） */
+} wave_seg_meta_t;
+
+/* 打包游标阶段（对外只用于「已搬完」判定与观测日志；推进全在 wave_store_pack_next 内部） */
+typedef enum {
+    WAVE_PACK_IDLE = 0,      /* 未初始化 */
+    WAVE_PACK_HEAD = 1,      /* 正在产头（固定头 + 通道表 + 头 CRC） */
+    WAVE_PACK_DATA = 2,      /* 正在产数据区（按通道分列，一列一列产） */
+    WAVE_PACK_TAIL = 3,      /* 只剩数据区 CRC 两字节 */
+    WAVE_PACK_DONE = 4       /* 整段已产完 */
+} wave_pack_phase_t;
+
+/* 数据源回调：把「第 a_ch 列、段内第 a_from 点起的 a_cnt 个点」取进 p_dst。
+ * 返 回 值：实际拷贝的点数（等于 a_cnt 表示全给到）；负 = 错误码  int32_t
+ * 只允许读已封存区：本层不提供、也不允许任何跨任务读活缓冲的路径
+ * （设计说明 §5.2 第一条陷阱：App/algo/sample_ring.c 的 sample_ring_window() 无临界区，
+ *  本波不复用它，跨任务只传「已封存」标志）。
+ * 生产实现 = wave_ring_read_cb()（签名一致，可直接传给 wave_store_pack_start）。 */
+typedef int32_t (*wave_reader_fn)(void *p_user, uint8_t a_ch, uint32_t a_from,
+                                  uint32_t a_cnt, int16_t *p_dst);
+
+/* 打包游标：段文件字节流的「拉模式」状态机。
+ * 为什么拉模式 + 小缓冲：defaultTask 是文件系统唯一写者，落盘窗口几十毫秒量级，
+ * 一次心跳最多一段；整段驻留 RAM 既超预算也没必要（设计说明 §7）。
+ * 游标不校验写回字节数 —— 那是调用方对着 f_write 做的事（§5.2 第二条陷阱：本移植
+ * f_write 簇分配失败会返 FR_OK + 短写、没有错误码，必须靠比对写回字节数判失败）。 */
+typedef struct {
+    uint8_t  phase;          /* wave_pack_phase_t */
+    uint8_t  ch;             /* 数据区当前列 */
+    uint16_t head_done;      /* 头区已产出字节数（含头 CRC 两字节） */
+    uint16_t ch_done;        /* 当前列已产出点数 */
+    uint8_t  tail_done;      /* 尾部数据 CRC 已产出字节数（0..2） */
+    uint8_t  rsv;            /* 补齐用，保持结构体偶数字节 */
+    uint16_t crc_data;       /* 数据区运行 CRC（增量中间值，避免整段驻留） */
+    uint32_t total;          /* 整段期望字节数 */
+    uint32_t sent;           /* 已产出字节数（= 下一片的文件偏移） */
+    wave_seg_meta_t meta;    /* 段头快照（start 时拷入；搬运期间调用方改自己那份不影响） */
+    wave_reader_fn p_reader; /* 数据源；NULL = 只产头 */
+    void *p_user;            /* 数据源上下文 */
+} wave_pack_ctx_t;
+
+/* ===== 四、CRC-16/MODBUS（无表位运算） ===== */
+
+/*
+ * 函数功能：CRC-16/MODBUS 增量计算（输入输出均低位在前）
+ * 入口参数：a_crc   上一次的中间值（首次传 WAVE_ST_CRC_INIT）
+ *           p_data  数据指针（NULL 且 a_len = 0 视为空操作，原样返回 a_crc）
+ *           a_len   字节数
+ * 返 回 值：新的中间值（写文件时低字节在前，见 §6.3 首行）  uint16_t
+ * 限定条件：任意上下文（含 adcTask 之外的 defaultTask / uiTask）；纯计算、无静态状态、
+ *           不碰外设、不取临界区
+ * 函数说明：为什么自带实现 —— 全仓没有可复用的 CRC-16 表（依据见本文件头注）。
+ *           无表 = 零新增表 RAM 与表 Flash；数据区 5120 字节每字节 8 次移位，在 168 MHz
+ *           上量级是几十微秒，且只在 defaultTask 的落盘链上出现，不在 1 kHz 采集链上。
+ */
+uint16_t wave_store_crc_update(uint16_t a_crc, const uint8_t *p_data, uint32_t a_len);
+
+/*
+ * 函数功能：CRC-16/MODBUS 一次算完（从初值起步）
+ * 入口参数：p_data  数据指针
+ *           a_len   字节数
+ * 返 回 值：CRC  uint16_t
+ * 限定条件：任意上下文。p_data 为 NULL 或 a_len = 0 时返回 WAVE_ST_CRC_INIT —— 这是
+ *           空输入的定义值，不是「算好的段 CRC」：零长度一律判废，调用方必须先判长度
+ *           （设计说明 §6.2 末行：长度为 0 → 整段作废）
+ */
+uint16_t wave_store_crc(const uint8_t *p_data, uint32_t a_len);
+
+/*
+ * 函数功能：CRC 自检 —— 用规范锚点验算实现是否仍是 CRC-16/MODBUS
+ * 入口参数：无
+ * 返 回 值：WAVE_ST_OK 相符；WAVE_ST_E_FORMAT 不符（实现或编译配置被改坏）  int
+ * 限定条件：任意上下文；开机或首次落盘前调一次即可，不在每拍路径上
+ * 函数说明：锚点 = 串 123456789 的 CRC = 0x4B37（§6.3）。这条是机器可执行的口径锚，
+ *           防的是「自算自验永远相符」：只有对已知常数才咬得住（换机、换编译器、
+ *           反射方向写反都在这里暴露）。落盘前失败就自弃本段并计入 err（§9 观测行）。
+ */
+int wave_store_crc_selftest(void);
+
+/* ===== 五、段头编解码 ===== */
+
+/*
+ * 函数功能：把段头元数据填成本波默认值（只填格式侧的静态事实）
+ * 入口参数：p_meta  输出（调用方持有的结构；本层不返回静态地址）
+ * 返 回 值：WAVE_ST_OK；WAVE_ST_E_PARAM 空指针  int
+ * 限定条件：任意上下文；不碰文件系统
+ * 函数说明：填 fs_hz = 1000、pts_per_cycle = 20、ch_count = 8、pts_per_ch = 320、
+ *           pre_pts = 160，以及通道表的 sem = 下标 + conv / bits 按两片转换器
+ *           （UA / UN / IA 走 TPAFE 16 位；UB / UC / IB / IC / IN 走片内 ADC 12 位 ——
+ *            通道归属口径属主是 docs/硬件平台/ADC通道映射说明.md，本函数只是它的抄本，
+ *            单测里对 0xE6 的算术交叉验证会同时钉住这套顺序）。
+ *           不填 avail / k_q16 / b_codes / trig_* / t0_ms / wall / eng / flags_seq /
+ *           clip_mask / frame_seq：那些是封存瞬间的事实，必须由调用方现取现填
+ *           （adc_cal_k_q16 / adc_cal_flags / sys_clock / wave_ring），本层不链它们。
+ */
+int wave_store_meta_init(wave_seg_meta_t *p_meta);
+
+/*
+ * 函数功能：把段头元数据编码成段文件头字节流（固定头 + 通道表 + 头 CRC，全小端）
+ * 入口参数：p_meta  段头元数据（只读）
+ *           p_out   输出缓冲
+ *           a_cap   缓冲容量（须不小于按 ch_count 算出的整头字节数）
+ * 返 回 值：不小于 0 = 实际写入字节数；负 = WAVE_ST_E_*  int
+ * 限定条件：任意上下文；无静态缓冲、可重入；不碰文件系统
+ * 函数说明：编码前先自检字段一致性 —— ch_count 为 0 或越界、pts_per_ch = 0、
+ *           pre_pts 大于 pts_per_ch、表内语义号不等于下标（§6.3「通道表序与列序」那条
+ *           PC 侧判据在编码侧同样成立）一律拒绝：不把坏头写成看起来像样的文件。
+ */
+int wave_store_head_build(const wave_seg_meta_t *p_meta, uint8_t *p_out, uint32_t a_cap);
+
+/*
+ * 函数功能：把段文件头字节流解回元数据，并做全套判废检查（魔数 / 版本 / 长度 / 表序 / 头 CRC）
+ * 入口参数：p_buf   头字节流
+ *           a_len   可读字节数
+ *           p_meta  输出元数据（判废时内容不保证有效，调用方不得消费）
+ * 返 回 值：WAVE_ST_OK；WAVE_ST_E_PARAM 空指针或缓冲不足；WAVE_ST_E_FORMAT 魔数 / 版本 /
+ *           表序不符；WAVE_ST_E_SIZE 零长度或长度与字段矛盾；WAVE_ST_E_CRC 头 CRC 不符  int
+ * 限定条件：任意上下文（uiTask 与 defaultTask 都可调）。UI 与 PC 侧必须用同一套判废语义：
+ *           解不过就只能显示「该段不可读」，绝不允许退化画一条直线
+ *           （设计说明 §8.1 空态行：画直线等于伪造证据）
+ * 函数说明：a_len 不足「按头里 ch_count 推出来的整头长度」时按缓冲不足返回，不猜没读到
+ *           的字节；ver 不等于魔数第三字节、或不等于 WAVE_ST_VER 一律判废。
+ */
+int wave_store_head_parse(const uint8_t *p_buf, uint32_t a_len, wave_seg_meta_t *p_meta);
+
+/* ===== 六、整段校验与长度 / 偏移换算（读侧） ===== */
+
+/*
+ * 函数功能：整段镜像自检 —— 头 + 数据区 + 数据 CRC 三道全过才算「这一段可读」
+ * 入口参数：p_img   整段文件镜像（调用方已读进内存）
+ *           a_len   镜像长度
+ *           p_meta  输出段头（可为 NULL）
+ * 返 回 值：WAVE_ST_OK；WAVE_ST_E_PARAM 空指针；WAVE_ST_E_SIZE 长度为 0 或与期望总长不符；
+ *           WAVE_ST_E_CRC 任一 CRC 不符；WAVE_ST_E_FORMAT 头本身判废  int
+ * 限定条件：任意上下文；只在整段驻留（本波 5250 字节）时用。回放页不要走这条 ——
+ *           用 wave_store_head_parse + wave_store_data_off + wave_store_crc_update 分段查，
+ *           才符合 §7 的 256 字节读窗预算
+ * 函数说明：这是「段文件 CRC 不符时脚本必须拒绝而不是画出东西」那条判据在板侧的同一份
+ *           实现，也是本层与 PC 解码器逐字节同解的对照物（两套主机单测互验）。
+ */
+int wave_store_seg_check(const uint8_t *p_img, uint32_t a_len, wave_seg_meta_t *p_meta);
+
+/*
+ * 函数功能：按头部字段算整段文件应有的字节数（写侧记账与读侧长度判废共用）
+ * 入口参数：p_meta  段头元数据
+ * 返 回 值：期望字节数（8 路 320 点 = 5250）；字段非法（含零长度）返回 0  uint32_t
+ * 限定条件：任意上下文
+ * 函数说明：返回 0 就是「这一段连长度都不成立」，据此判废。不要拿 0 去开缓冲，
+ *           也不要拿 0 去比对 f_write 的写回字节数（那会把失败读成成功）。
+ */
+uint32_t wave_store_seg_size(const wave_seg_meta_t *p_meta);
+
+/*
+ * 函数功能：整头字节数（固定头 + 通道表 + 头 CRC 两字节）
+ * 入口参数：a_ch_count  通道数
+ * 返 回 值：字节数；通道数为 0 或越界返回 0  uint32_t
+ * 限定条件：任意上下文
+ */
+uint32_t wave_store_head_bytes(uint8_t a_ch_count);
+
+/*
+ * 函数功能：数据区某一点在段文件里的绝对偏移（按通道分列 → 单通道是一整段连续区）
+ * 入口参数：a_ch_count  通道数
+ *           a_pts_ch    每通道点数
+ *           a_ch        列号（= 通道表下标 = 语义号，0 到 a_ch_count-1）
+ *           a_pt        段内点下标（0 到 a_pts_ch-1）
+ * 返 回 值：文件偏移；参数非法返回 0xFFFFFFFFu 哨兵（这个值不是任何合法偏移）  uint32_t
+ * 限定条件：任意上下文
+ * 函数说明：回放页据此定位「只读那一路」，配合 wave_store_data_bytes_avail 一次连续读；
+ *           PC 侧同一算法，两份实现互验。
+ */
+uint32_t wave_store_data_off(uint8_t a_ch_count, uint16_t a_pts_ch,
+                             uint8_t a_ch, uint32_t a_pt);
+
+/*
+ * 函数功能：从某点起当前列还能连续读多少字节（不跨列、不越段尾）
+ * 入口参数：a_pts_ch  每通道点数
+ *           a_pt      起始点下标
+ *           a_want    想读的点数
+ * 返 回 值：可连续读字节数 = 2 × 实际可给点数；参数非法返回 0  uint32_t
+ * 限定条件：任意上下文
+ */
+uint32_t wave_store_data_bytes_avail(uint16_t a_pts_ch, uint32_t a_pt, uint32_t a_want);
+
+/*
+ * 函数功能：把段文件读出的小端字节解码成 int16 点序列（按时间序，旧到新）
+ * 入口参数：p_raw      原始字节（来自文件，2 × 点数）
+ *           a_len      字节数（须为偶数，且不大于 a_max_pts × 2）
+ *           p_out      输出 int16 数组
+ *           a_max_pts  输出容量（点数）
+ *           p_pts      输出实际点数（可为 NULL）
+ * 返 回 值：WAVE_ST_OK；WAVE_ST_E_PARAM 空指针 / 奇数字节 / 容量不足  int
+ * 限定条件：任意上下文
+ * 函数说明：显式按小端逐字节拼装，不依赖宿主字节序，所以板端与 PC 侧同一判据。
+ *           片内 ADC 那几路的值本就是 0..4095 的原样正数，不做中点偏置
+ *           （§6.3「样本编码」行：加偏置等于伪造双极性）。
+ */
+int wave_store_le_decode(const uint8_t *p_raw, uint32_t a_len,
+                         int16_t *p_out, uint32_t a_max_pts, uint32_t *p_pts);
+
+/*
+ * 函数功能：把一路的 int16 码值折成定点毫单位（回放页峰值标注用；纯整数，不用 float）
+ * 入口参数：p_desc   该路通道表项（k_q16 / b_codes 来自段文件头，不来自当前固件）
+ *           a_code   原始码值
+ *           p_milli  输出四舍五入后的毫单位（k_q16 是 µV/码 → 输出单位 mV）（不可为 NULL）
+ * 返 回 值：WAVE_ST_OK；WAVE_ST_E_PARAM 空指针  int
+ * 限定条件：任意上下文（只在回放页与单测里用，不在 1 kHz 采集链上；内部用 int64 中间量，
+ *           落在这条路径上时可接受）
+ * 函数说明：算式 eng = (code + b) × k × 1e-6，与 App/algo/adc_cal.c 的 adc_cal_apply()
+ *           同一模型（§6.3）。输出单位是 mV；单位含义由段头 eng 字段决定（eng = 0 是
+ *           引脚域，别读成二次值）。必须用段文件里的 k / b，不许拿当前固件的系数解释
+ *           老文件（§12 风险表「标定落地后老文件被解释错」）。
+ */
+int wave_store_code_to_milli(const wave_ch_desc_t *p_desc, int16_t a_code,
+                             int32_t *p_milli);
+
+/* ===== 七、打包游标（分次搬运，给文件系统唯一写者） ===== */
+
+/*
+ * 函数功能：初始化打包游标（段头拷进游标，随后逐次拉整段字节流）
+ * 入口参数：p_ctx     游标（调用方持有，栈上或静态都行；本层不记它的地址）
+ *           p_meta    段头元数据（内部拷贝；搬运期间调用方改自己那份不影响本段）
+ *           p_reader  数据源回调；NULL = 只产头（回放页只校验头 / 主机单测只测头）
+ *           p_user    数据源上下文（生产传 NULL，wave_ring 是单例不需要）
+ * 返 回 值：WAVE_ST_OK；WAVE_ST_E_PARAM 空指针；WAVE_ST_E_FORMAT 段头字段非法；
+ *           WAVE_ST_E_SIZE 算不出合法长度  int
+ * 限定条件：任意上下文（纯计算，无临界区）；一段一个游标，搬完再 start 下一段
+ * 函数说明：p_reader 为 NULL 而 ch_count 大于 0 时，游标仍能产头，但进数据区那一步
+ *           返回 WAVE_ST_E_STATE —— 不静默跳过数据区，否则调用方会写出一个
+ *           「长度看着对、内容是空的」段文件（那正是 §8.1 要防的伪造证据形态）。
+ */
+int wave_store_pack_start(wave_pack_ctx_t *p_ctx, const wave_seg_meta_t *p_meta,
+                          wave_reader_fn p_reader, void *p_user);
+
+/*
+ * 函数功能：取整段字节流的下一片（分次搬运的唯一推进口）
+ * 入口参数：p_ctx  已 start 的游标
+ *           p_out  输出缓冲
+ *           a_cap  本片容量（建议 256 字节，见 §7；数据区不切半点，奇数容量会少产 1 字节）
+ *           p_len  输出本片实际字节数（不可为 NULL）
+ * 返 回 值：WAVE_ST_OK 产出本片且还有后续；WAVE_ST_DONE 整段已产完（*p_len 可为 0）；
+ *           负 = WAVE_ST_E_*（未 start / 容量为 0 / 数据源回调返错 / 游标状态错）  int
+ * 限定条件：任意上下文，但同一游标不得并发使用（文件系统唯一写者单线程推进）
+ * 函数说明：头区字节流与 wave_store_head_build 完全一致（内部同一份写字段函数）；
+ *           **头那一步要求 a_cap 不小于整头字节数**（本波 8 路 = 128），否则返回
+ *           WAVE_ST_E_PARAM 且不推进游标——不拆着头给，是为了让游标不必存 128 字节
+ *           中间态；§7 的 256 字节搬运缓冲天然满足。
+ *           数据区 CRC 走增量中间值，整段最后两片是数据 CRC 的低字节、高字节。
+ *           调用方每写完一片都必须比对 f_write 写回字节数，短写按失败处理（§5.2）。
+ */
+int wave_store_pack_next(wave_pack_ctx_t *p_ctx, uint8_t *p_out,
+                         uint32_t a_cap, uint32_t *p_len);
+
+/*
+ * 函数功能：读游标已产出字节数（= 当前文件偏移；供记账、观测与「写没写全」判定）
+ * 入口参数：p_ctx  游标
+ * 返 回 值：已产出字节数；p_ctx 为 NULL 返回 0  uint32_t
+ * 限定条件：任意上下文（只读）
+ */
+uint32_t wave_store_pack_offset(const wave_pack_ctx_t *p_ctx);
+
+/*
+ * 函数功能：读游标对应整段文件的期望总长（写完与 f_size / 累计写回字节数比对）
+ * 入口参数：p_ctx  游标
+ * 返 回 值：期望总字节数；p_ctx 为 NULL 返回 0  uint32_t
+ * 限定条件：任意上下文（只读）
+ */
+uint32_t wave_store_pack_total(const wave_pack_ctx_t *p_ctx);
+
+/* ===== 八、段文件名轮转（只算名字，不碰文件系统） ===== */
+
+/*
+ * 函数功能：按段号生成段文件路径（严格 8.3 短名：目录 + 前缀 + 两位十进制 + 扩展名）
+ * 入口参数：p_out  输出缓冲（容量须不小于 WAVE_ST_PATH_MAX）
+ *           a_cap  容量
+ *           a_idx  段号 0 到 WAVE_ST_SEG_MAX-1
+ * 返 回 值：不小于 0 = 写入的字符数（不含结束符；当前布局恒为 16，故缓冲至少要 17 字节）；
+ *           WAVE_ST_E_PARAM 空指针或容量不足；
+ *           WAVE_ST_E_RANGE 段号越界  int
+ * 限定条件：任意上下文；纯字符拼装（不用 sprintf，见 CODE-RULE-06 系），逐字节可预期
+ * 函数说明：号 0..99 轮转覆盖，共 100 个名字，写满回绕盖最老的（§5.2 第三条）。
+ *           本函数不检查文件是否存在、不建目录：那些都是接线道的职责。
+ */
+int wave_store_seg_path(char *p_out, uint32_t a_cap, uint8_t a_idx);
+
+/*
+ * 函数功能：下一个轮转段号（到 99 后回 0）
+ * 入口参数：a_idx  当前段号（越界输入按 0 处理，不猜）
+ * 返 回 值：下一个段号  uint8_t
+ * 限定条件：任意上下文
+ */
+uint8_t wave_store_next_idx(uint8_t a_idx);
+
+/*
+ * 函数功能：从文件名或路径反解段号（掉电后靠扫目录重建段账用）
+ * 入口参数：p_path  路径或纯文件名（只看最后一段，大小写都收）
+ *           p_idx   输出段号（不可为 NULL）
+ * 返 回 值：WAVE_ST_OK；WAVE_ST_E_PARAM 空指针；WAVE_ST_E_NAME 不是本层命名形态  int
+ * 限定条件：任意上下文
+ * 函数说明：只认「前缀 + 两位数字 + 扩展名」，其余（目录名、长名、以点开头）一律判不匹配
+ *           —— 扫目录重建账时不许把陌生名字当录波段；名字/参数类错误码严禁升级成卷操作
+ *           （docs/架构设计/STM32F4-Base存储架构说明.md §10.1 的同一条教训）。
+ */
+int wave_store_idx_from_name(const char *p_path, uint8_t *p_idx);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* WAVE_STORE_H */
@@ -17,19 +17,22 @@
 #include "stm32f4xx_it.h" /* fault_handler_enable() */
 #include "usart.h"       /* huart5 */
 #include "tim.h"         /* htim3：1 kHz 采样节拍（TIM3 更新中断触发 CONVST + TRGO 触发 ADC1） */
+#include "adc.h"         /* adc1_disable()：挂 DMA 前把 ADC 关掉，让 Start_DMA 自己使能 */
 #include "rs485.h"
+#include "sb_link.h"      /* 屏板链路传输层：sb_link_init()（USART1 收中断，批 1 的 1-3） */
 #include "sd2506.h"
+#include "boot_stats.h"   /* 开机账本：上电次数（RTC 用户 SRAM）+ 本次复位原因快照（道G task-12） */
 #include "sys_clock.h"
 #include "gd5f2gq5ue.h"
 #include "tpafe5160.h"
-#include "adc_input.h"   /* L1 采集层：adc_input_init()（语义映射 + STM32 ADC1 扫描） */
-#include "adc_cal.h"     /* L1.5 标定层：adc_cal_init()（ROM 系数 + cfg 两段注册，道A 卡2/4） */
-#include "run_par.h"     /* 运行参数段：run_par_init()（[run_par] 注册 + 104 地址映射真源，道D 卡10） */
+#include "adc_input.h"   /* 语义取数与有效性层：adc_input_init()（语义映射 + STM32 ADC1 扫描） */
+#include "adc_cal.h"     /* 标定折算层：adc_cal_init()（ROM 系数 + cfg 两段注册，道A 标定折算与落盘整定） */
+#include "run_par.h"     /* 运行参数段：run_par_init()（[run_par] 注册 + 104 地址映射真源，道D 这一项） */
 #include "iec104_comm.h"  /* [comm] 段：iec104_comm_init()（ca/端口注册，道G task-8） */
-#include "phasor.h"      /* L2 相量层：phasor_init()（系数表 + 实例 + 双区交换） */
-#include "freq.h"        /* L2 派生量：freq_init()（相位解缠绕测频，B8） */
-#include "prot_set.h"    /* L3 定值模型：prot_set_init()（B5，内核前封存） */
-#include "prot_elm.h"    /* L3 元件框架：prot_elm_init()（B5，解析相量索引） */
+#include "phasor.h"      /* 全周傅氏相量层：phasor_init()（系数表 + 实例 + 双区交换） */
+#include "freq.h"        /* 全周傅氏相量的派生量：freq_init()（相位解缠绕测频，B8） */
+#include "prot_set.h"    /* 保护判据定值模型：prot_set_init()（B5，内核前封存） */
+#include "prot_elm.h"    /* 保护判据元件框架：prot_elm_init()（B5，解析相量索引） */
 #include "sys_log.h"
 #include "task_watchdog.h"  /* task_wd_seg_report()：第 8 轮复位不丢"进段打点"上报 */
 #include "test_config.h"    /* 套件开关：身份戳的构建变体串（FW_BUILD_VARIANT）依赖本头，
@@ -76,23 +79,11 @@ volatile uint32_t g_rcc_csr_latched;
 *           兜底，两者同时置位时报告看门狗更有价值）。纯 ASCII，防编码坑。
 */
 static void reset_cause_str(uint32_t csr, char *buf, unsigned int len) {
-    const char *cause;
-
-    if ((csr & RCC_CSR_IWDGRSTF) != 0u) {
-        cause = "IWDG (independent watchdog)";
-    } else if ((csr & RCC_CSR_WWDGRSTF) != 0u) {
-        cause = "WWDG (window watchdog)";
-    } else if ((csr & RCC_CSR_SFTRSTF) != 0u) {
-        cause = "software (NVIC_SystemReset)";
-    } else if ((csr & RCC_CSR_PORRSTF) != 0u) {
-        cause = "power-on (POR)";
-    } else if ((csr & RCC_CSR_PINRSTF) != 0u) {
-        cause = "external pin (NRST)";
-    } else if ((csr & RCC_CSR_BORRSTF) != 0u) {
-        cause = "brown-out (BOR)";
-    } else {
-        cause = "unknown";
-    }
+    /* 优先级链**不在这里再写一遍**：改由 boot_stats 出一份（IWDG > WWDG > 软件 >
+     * POR > PIN > BOR）。原先这条 if-else 链与页面上要显示的编码各写一份，两份早晚
+     * 会漂——漂了的症状是串口说 "IWDG"、屏幕写 "software"，两条却都"看着有据"。
+     * 顺序本身的理由见本函数上方原注释与 App/util/boot_stats.h 的函数头。 */
+    const char *cause = boot_stats_cause_str(boot_stats_cause_from_csr(csr));

    /* 简单有界拼接（不引 snprintf，避免依赖与栈开销） */
    if (buf == NULL || len == 0u) {
@@ -118,7 +109,7 @@ static void reset_cause_str(uint32_t csr, char *buf, unsigned int len) {
 *             1) 时间子系统（SD2506 RTC → 墙钟基准）
 *             2) RS-485
 *             3) GD5F NAND
- *             4) TPAFE5160 ADC → ADC 输入层（L1，语义映射 + STM32 ADC1）
+ *             4) TPAFE5160 ADC → ADC 输入层（语义取数与有效性，语义映射 + STM32 ADC1）
 *             5) SD2506 诊断信息
 *             6) 启动 TIM3 1 kHz 采样节拍（ISR 内脉冲 CONVST；同一更新事件经 TRGO 硬件触发 ADC1 + DMA）
 */
@@ -139,7 +130,7 @@ int app_main_init(void) {

    /* 固件身份戳（2026-10-10）：__DATE__/__TIME__ 由编译器展开，与前面的字面量做
     * C 字符串拼接 → .rodata 里是一段连续 ASCII，可直接在 .hex 里原样搜到。
-     * 用途：@test 把"芯片里正在跑的镜像"和"刚编出来的镜像"对上号。此前开机标记
+     * 用途：/serial-boot-test 把"芯片里正在跑的镜像"和"刚编出来的镜像"对上号。此前开机标记
     * 全是固定串（App init OK / Network Init / ...），旧镜像也照样全中，于是
     * "反复重下载、芯片一直是旧镜像"这类事故在自动闭环里完全不可见
     * （AGENTS.md 烧录铁律记的正是它）。代价：1 条 DBG ≈ 90 B Flash + 30 B 常量。
@@ -187,15 +178,44 @@ int app_main_init(void) {
        bsp_err_t rtc_ret = sd2506_init();
        DBG_INFO("SD2506 init: %s (ret=%d)",
                 (rtc_ret == BSP_OK) ? "OK" : "FAILED", rtc_ret);
+        /* 1b) 开机账本（道G task-12）：紧接 sd2506_init 之后，是**唯一**的调用点。
+         *     为什么放这儿而不是 defaultTask 的存储 bring-up：
+         *     ① 这一步只做 1 次 I2C 读 + 至多 1 次 I2C 写，落在内核启动前——
+         *        单线程、非 ISR、调度器还没跑（本函数不调任何创建类内核 API，
+         *        AGENTS「内核前禁调创建类 API」那条与此无关）；
+         *     ② 保持介质是 RTC 用户 SRAM，不是文件系统：不必等 STORAGE_READY，
+         *        也就不必在喂狗点上碰卷锁（这条链上根本没有卷操作可言）；
+         *     ③ sd2506_init 失败时这里自然走"读不到"那一支：状态标成不可信、
+         *        且不回写，不会把可能还完好的记录覆盖掉。
+         *     失败一律不打日志（可观测性事件不进 [ERR]），状态留在 boot_stats_get()。 */
+        boot_stats_init();
    }
    if (sys_clock_init() != 0) {
        syslog_post(SYSLOG_SELFTEST, "clock chip fault");
    }

-    /* 2) RS-485 初始化（UART4 + PD0 方向控制），初始化即自动开启接收 */
+    /* 2) RS-485 初始化（UART4 + 方向脚 = ST_DIR4 宏：V0.1 板实测 PA15，V0.0 曾是 PD0，
+     *     轮换记录 = docs/硬件平台/V0.1_网表详细分析报告.md 的 V0.0→V0.1 引脚迁移表），
+     *     初始化即自动开启接收 */
    rs485_init(&g_rs485, &huart4, ST_DIR4_GPIO_Port, ST_DIR4_Pin);
    DBG_INFO("RS485 init: OK (UART4, DE=PA15)");

+    /* 2b) 屏板链路初始化（USART1，700 kbaud 8N1，IDLE 中断接收）。
+     *     放在 NAND 全片扫描之前：这一步只是挂接收（µs 级），挂上之后屏板的周期召唤
+     *     就已经能被收下来并计数，台架不必等启动跑完才能看到链路状态。
+     *     波特率不在本调用里设——在 Src/usart.c 的 USER CODE 区（CubeMX 重生成只保护那里），
+     *     本调用只做一次交叉核对，对不上会报 BSP_ERR_STATE 并打 ERR 行。 */
+    {
+        bsp_err_t sb_ret = sb_link_init(&huart1);
+        /* BRR 直接读出来打：1-2 的判据是"实测位宽误差 < 1 %"，而 BRR 是位宽的唯一决定量——
+         * 84 MHz / (16 x 700 kHz) = 7.5 → 期望 0x0078（整数 7、小数 0.5x16 = 8），误差 0 %。
+         * 有这一行就不必为了核波特率去架示波器：BRR 对不上就说明 USER CODE 覆盖没生效。 */
+        DBG_INFO("ScreenLink init: %s (ret=%d, USART1 %lu baud, BRR=0x%04lX)",
+                 (sb_ret == BSP_OK) ? "OK" : "FAILED",
+                 sb_ret, (unsigned long)SB_LINK_BAUD,
+                 (unsigned long)huart1.Instance->BRR);
+    }
+
    /* 3) GD5F 初始化测试（BBT 全片扫描，启动段最耗时的一步） */
    int ret = gd5f2gq5ue_init();
    DBG_INFO("NAND init: %s",
@@ -220,7 +240,25 @@ int app_main_init(void) {
        syslog_post(SYSLOG_SELFTEST, "ADC fault");
    }

-    /* 4b) ADC 输入层（L1）初始化：清原始码值缓冲与统计 + **语义映射表自洽性自检**
+    /* 4b-pre) 挂 DMA 之前**先把 ADC 关掉**，让使能动作由 HAL_ADC_Start_DMA 内部完成
+     *     （它自己 __HAL_ADC_ENABLE + 等 Tstab ~20 µs，然后紧接着开 CR2.DMA 并启流）。
+     *
+     *     为什么必须这样做：MX_ADC1_Init() 在 main() 里就调用了，而挂 DMA 在这里，
+     *     中间隔着 GD5F 全片 BBT 扫描（数秒）。台架实测（同一次开机内用无 DMA 单通道
+     *     探针取真值对照，9/9 完美置换）：**ADC 使能后闲置数秒才挂 DMA，DMA 乒乓缓冲
+     *     会整体 +2 格旋转** —— 槽 i 装的是 rank ((i+1) mod 9)+1，9 路通道按 rank 序
+     *     整体错开 2 位。表象是"接地 AIN2、UB 却读到别的通道的值"，极易被误判成
+     *     映射表写错或夹子位置不对。
+     *     把使能与挂 DMA 压到同一时刻后旋转消失（台架 4/4 次，同开机对照差值 ≤4 码）。
+     *     证据与复现方法见 docs/子系统设计/ADC采样节拍设计说明.md §4.5。
+     *
+     *     ⚠ 顺序不可调换：本调用必须严格早于下面的 adc_input_init()。
+     *       若 ADC 在本步之后仍处于使能态，旋转会重新出现。 */
+    if (adc1_disable() != 0) {
+        DBG_ERROR("ADC1 disable before DMA arm: TIMEOUT");
+    }
+
+    /* 4b) ADC 输入层（语义取数与有效性）初始化：清原始码值缓冲与统计 + **语义映射表自洽性自检**
     *     （映射指向了不会被扫描的通道 → 返回 -1，避免"读到恒为陈旧值"的静默错）
     *     + 挂载一次 STM32 ADC1 的 DMA（失败返回 -2）。
     *     ADC1 外设已由 MX_ADC1_Init()（main.c）配好 9 通道 / 144 cycles /
@@ -240,21 +278,21 @@ int app_main_init(void) {
        }
    }

-    /* 4c) 相量层（L2）初始化：清双区结果与有效标志 + 复位采样环缓冲。
+    /* 4c) 相量层（全周傅氏相量）初始化：清双区结果与有效标志 + 复位采样环缓冲。
     *     纯算法层（无外设 / 无 RTOS 依赖，见 docs/算法/继电保护功能复现规划.md
     *     §3.2），须在启动采样节拍（步骤 6）之前。幂等、当前无失败路径
     *     （返回值保留供后续自检扩展）。 */
    (void)phasor_init();
    DBG_INFO("phasor layer init: OK (inst=%u)", (unsigned)phasor_inst_count());

-    /* 4c-2) 测频层（L2 派生量，B8）初始化：清平均窗/相位基准/有效标志。
+    /* 4c-2) 测频层（全周傅氏相量的派生量，B8）初始化：清平均窗/相位基准/有效标志。
     *     纯算法（输入 = phasor 使用区），消费在 adcTask（freq_run 每拍）
     *     与 protectTask（OF/UF 判据经 prot_elm_run 取数）。 */
    (void)freq_init();
    DBG_INFO("freq layer init: OK");

-    /* 4c-3) 通道标定层（L1.5，「数据可信」卡 2/卡 4）初始化：RAM 系数副本置
-     *     ROM 默认（卡 1 定死的引脚侧 LSB，docs/硬件平台/ADC通道映射说明.md §7.1）
+    /* 4c-3) 通道标定层（标定折算，「数据可信」标定折算与落盘整定）初始化：RAM 系数副本置
+     *     ROM 默认（量程口径冻结定死的引脚侧 LSB，docs/硬件平台/ADC通道映射说明.md §7.1）
     *     + 向配置引擎注册 [adc_cal] / [adc_cal_ofs] 两段。注册必须先于
     *     defaultTask 的 cfg_file_load（「先注册后 load」契约）→ 只能落内核前；
     *     折算消费在 adcTask 每拍（adc_cal_apply），标定文件值随 load/poll 原地
@@ -263,7 +301,7 @@ int app_main_init(void) {
    DBG_INFO("adc cal init: OK (k_q16 tpafe=%ld stm32=%ld)",
             (long)ADC_CAL_K_Q16_TPAFE, (long)ADC_CAL_K_Q16_STM32);

-    /* 4c2) 运行参数段初始化（「数据可信」卡 10）：死区 9 点工厂默认 + 注册
+    /* 4c2) 运行参数段初始化（「数据可信」这一项）：死区 9 点工厂默认 + 注册
     *     [run_par] 段。同 adc_cal 的「先注册后 load」契约 → 必须内核前；
     *     104 消费（COV 实时读 / 0x8020 段读写映射）在 iec104Task 启动后进行。 */
    run_par_init();
@@ -22,11 +22,12 @@ extern "C" {
 * 由 MX_FREERTOS_Init 在 freertos.c 的 generated 区域自动声明并 osEventFlagsNew 创建） */
 extern osEventFlagsId_t sys_evtHandle;

-/* 各子系统"就绪"事件位（32 位上限内的 bit 0~30） */
+/* 各子系统"就绪"事件位（32 位上限内的 bit 0~30）。**bit0 / bit1 在用，bit2 / bit3 是预留位**
+ * ——逐位的生产者与消费者对照表 = docs/架构设计/项目启动顺序管理.md §3.2 */
 #define SYS_EVT_NET_READY      (1u << 0)  /* netTask：net_init + PHY 稳定完成 */
 #define SYS_EVT_STORAGE_READY  (1u << 1)  /* defaultTask：FTL/FatFS 挂载完成 */
-#define SYS_EVT_FTP_READY      (1u << 2)  /* ftpTask：lftpd_start 完成 */
-#define SYS_EVT_TIMESYNC_READY (1u << 3)  /* timeSyncTask：首次时间同步完成 */
+#define SYS_EVT_FTP_READY      (1u << 2)  /* ftpTask：lftpd_start 完成后置位；暂无消费者（预留） */
+#define SYS_EVT_TIMESYNC_READY (1u << 3)  /* 预留：timeSyncTask 在跑但不置本位，生产者消费者都没有 */
 #define SYS_EVT_NET_RECONFIG   (1u << 4)  /* UI：请求立即应用新网口配置（netTask 消费后重建网络） */
 #define SYS_EVT_CFG_SAVE       (1u << 5)  /* UI：网口配置保存请求（defaultTask = 配置引擎属主，消费并写盘） */
 #define SYS_EVT_CONSOLE_TX     (1u << 6)  /* 控制台单写者：生产者入环形缓冲后置位，defaultTask 消费并发送
@@ -34,7 +35,7 @@ extern osEventFlagsId_t sys_evtHandle;
 #define SYS_EVT_PROT_SET_SAVE  (1u << 7)  /* 保护定值落盘请求（B7）：iec104Task 检测到定值脏置位，
                                           * defaultTask（配置引擎属主）消费并写 /prot_set.bin
                                           * （消费型命令位；写盘失败脏标志保留 → 下轮再通知重试） */
-#define SYS_EVT_RUN_PAR_SAVE   (1u << 8)  /* 运行参数段落盘请求（「数据可信」卡 10）：iec104Task
+#define SYS_EVT_RUN_PAR_SAVE   (1u << 8)  /* 运行参数段落盘请求（「数据可信」这一项）：iec104Task
                                           * 检测到 run_par 脏（死区 9 键 / 系数覆盖联动 [adc_cal]）
                                           * 置位，defaultTask 消费并 cfg_file_save 整档外科保存
                                           * （消费型命令位；失败脏保留 → 下轮重试，B7 同款） */
@@ -24,6 +24,14 @@
 *                                （定值写路径出队 → 闭锁/越界预检 → set_sealed，
 *                                见 s_param_ops）；② 参数帧尾填 cal_block（未标定
 *                                闭锁徽标，三路口径同 protect_task.c，不用 eng）
+ *     v1.3  2026-10-27  DTU 项目组  道F task-7：遥测整定注入表（ui_data_yt_ops_t）
+ *     v1.4  2026-10-27  DTU 项目组  道G task-9：通讯参数注入表（ui_data_comm_ops_t，
+ *                               通讯设置页）；port_104 快照从 IEC104_SERV_PORT 宏
+ *                               切 iec104_comm_port() 真源（宏同笔删除，交接口径见
+ *                               IEC104上行设计说明.md §8）
+ *                                装配层实现 + 首轮懒绑（时序与通道四绑定等价，
+ *                                见 feed_yt_bind_once 函数头）；行数等值由编译期
+ *                                守卫钉，量纲分档与合法域分档同源同序
 *     v1.2  2026-10-26  DTU 项目组  道F task-16：删除本地镜像 feed_cal_block()，
 *                                两个调用点（填帧 / 门控比较）改调
 *                                adc_cal_prot_blocked()——同一份三路判定此前在
@@ -37,6 +45,8 @@
 #include <string.h>

 #include "cmsis_os.h"       /* osKernelGetTickCount：与 adc_task 同一 ms 时基 */
+#include "boot_stats.h"     /* 运行报告：上电次数 + 本次复位原因快照（道G task-12 数据面） */
+#include "iec104_serv.h"    /* 运行报告：四个 104 只读观测计数（本次开机以来，跨重连不清零） */

 #include "ui_data_feed.h"

@@ -55,13 +65,14 @@

 /* 同层（App）数据源 */
 #include "adc_input.h"      /* ADC_SEM_COUNT / adc_input_raw（TEMP 码值） */
-#include "adc_cal.h"        /* adc_cal_flags：VALID/CLIPPED 三态可用性；adc_cal_prot_blocked：未标定闭锁单点 */
+#include "adc_cal.h"        /* adc_cal_flags：VALID/CLIPPED 三态可用性；adc_cal_prot_blocked：未标定闭锁单点；adc_cal_k_uv：系数当前生效值（与 104 回显同视图） */
+#include "run_par.h"        /* 道F task-7 遥测整定注入表：死区/合法域/系数 setter/脏位（真源全在本模块与 adc_cal，feed 只转达） */
 #include "phasor.h"         /* 基波/谐波有效值（fAmSQ） */
 #include "freq.h"           /* 测频读数与新鲜度 */
 #include "prot_elm.h"       /* 元件动作态（遥信位图来源） */
 #include "prot_set.h"       /* 40 项定值 Q10 + 校验和 + 闭锁 + 越界位图 */
 #include "sys_clock.h"      /* 墙钟字符串 */
-#include "iec104_serv.h"    /* IEC104_SERV_PORT：实际监听端口（非协议层同名常量） */
+#include "iec104_comm.h"     /* 道G task-9：[comm] 真源 getter/setter/脏位；快照端口切 getter，IEC104_SERV_PORT 字面宏同笔删除 */
 #include "iec104_pts.h"     /* task-15 批4：遥信点数与单/双点性质（点表事实的唯一来源） */

 /* 私有宏定义区 */
@@ -135,8 +146,8 @@ static uint8_t  s_map_done;
 /* 发布节拍与参数变化检测状态
 * par 帧有**三个各自独立**的变化源，任一变了就要重发一帧（详见 tick 里的门控注释）：
 *   s_par_sum       定值改动（校验和）
- *   s_par_locked    定值闭锁（L5-1 自检失配，校验和不动）
- *   s_par_cal_block 未标定闭锁（卡 12 标定完成，校验和也不动）
+ *   s_par_locked    定值闭锁（定值校验和自检失配，校验和不动）
+ *   s_par_cal_block 未标定闭锁（两点标定完成，校验和也不动）
 * 后两个各占一字节——省下来就是"屏上状态与真值脱拍"这笔债 */
 static uint32_t s_last_rt_ms;
 static uint32_t s_par_sum;
@@ -459,7 +470,7 @@ static int feed_param_check(uint8_t a_id, int32_t a_q10) {
 * 函数说明：用 prot_set_set_sealed()（影子拷贝→改→重封→单字交换，**每项自带置脏**，
 *          落盘由 defaultTask 50 ms 圈扫脏写 /prot_set.bin，本模块不碰 FatFs）。
 *          ⚠ 不得改成 prot_set_set() + 批末 prot_set_seal()：两条路径之间有
- *          "已改未封存"窗口，prot_set.c 明令不得交错，撞上就被 L5-1 自检判成
+ *          "已改未封存"窗口，prot_set.c 明令不得交错，撞上就被定值校验和自检判成
 *          "定值被非法改写"→ 整台保护闭锁
 */
 static int feed_param_apply(uint8_t a_id, int32_t a_q10) {
@@ -476,6 +487,206 @@ static const ui_data_param_ops_t s_param_ops = {
    feed_param_apply
 };

+/*
+ * ======================= 道F task-7：遥测整定注入表（ui_data_yt_ops_t）装配
+ *
+ * 两页唯一的执行侧转达处。四条装配纪律：
+ * ① 数值与合法域**都**现给执行侧（run_par_deadband / run_par_db_range /
+ *    adc_cal_k_uv / RUN_PAR_K_MAX_UV）——本文件不出现任何范围数字字面量；
+ *    系数真带（µV/码执行段裁）没有公开访问器，也**不在此补一份**（task-43 收口），
+ *    真带拒的值经 set 原样返 -1，页面反显 + 保存行 ERR，两层守卫互不掩盖。
+ * ② 写走语义 setter（写值与置脏同一函数内发生，run_par_cal_k_set 文件头契约）；
+ *    本层不存在"只置脏不写值"或"只写值不置脏"的组合，UI 永远够不到裸脏位。
+ * ③ 跨任务写口径：真机默认档 = iec104Task 的 C_SE；本文件的调用在 uiTask，
+ *    这**正是** Lead 裁定（task-7 派发②）批准的"装配层转达"整定路径——与 104
+ *    走同一批 setter、同一 int32 单字原子契约，不新开工；run_par.h 里死区旧
+ *    接口"iec104Task 上下文"的限定条件语写于该裁定之前，语义已被裁定覆盖
+ *    （系数两支的限定条件已明写装配层入口，措辞同步归算法层下一笔）。
+ * ④ 落盘不靠本表：写成功置脏 → defaultTask 每轮无条件 run_par_store_save()
+ *    （查实：唯一 cfg_file_save 调用者，首行"无脏立即返回"；104 的 peek→事件位
+ *    只是加速器不是必经链）——所以"OK = 盘上真落了"在真机与模拟器（pump 清脏）
+ *    两端口径一致，黄金参考拍的 WAIT/OK 不是表演。
+ */
+
+/* 跨层行数等值守卫：BSP 侧契约值 ↔ 执行侧真值。本文件是全仓第一处两份头
+ * 同时可见的编译单元——BSP 物理上无法自证（看不到 App 头），守卫落这里 */
+typedef char feed_yt_db_n_check_t[(UI_DATA_YT_DB_N == (uint8_t)RUN_PAR_DB_N) ? 1 : -1];
+typedef char feed_yt_ch_n_check_t[(UI_DATA_YT_CH_N == (uint8_t)RUN_PAR_CH_N) ? 1 : -1];
+
+/*
+ * 函数功能：死区点数（执行侧真值直通）
+ * 入口参数：无
+ * 返回值：RUN_PAR_DB_N  uint8_t
+ * 限定条件：uiTask（注入表回调）
+ * 函数说明：行数从这一头出、BSP 契约常量在文件头编译期守卫对表——两边不等
+ *          编不过，等值不靠注释维持
+ */
+static uint8_t feed_yt_db_n(void) {
+    return (uint8_t)RUN_PAR_DB_N;
+}
+
+/*
+ * 函数功能：读第 idx 行死区现状（值 + 粗守域现给；量纲按点型分档）
+ * 入口参数：idx - 0..8（0..7 电气语义通道序，8 频率）  uint8_t
+ *           a_out - 行现状  ui_data_yt_row_t *
+ * 返回值：0 - 已写出；-1 - 越界 / 指针空（run_par_db_range 自判，本层不重复判）  int
+ * 函数说明：unit 的分档（前 4 电压、中 4 电流、末 1 频率）**必须**与
+ *          run_par_db_range 的档位分档同序——两处真源都没导出量纲，唯一防线是
+ *          run_par.h 地址映射表（0x8030~0x8038 = UA..IN/FREQ）与本表同序这条
+ *          写死的对表纪律 + 黄金像素（档位漂了屏上会呈现"0~50"配 "A" 的肉眼矛盾）；
+ *          decimals 取 3 = 死区在引擎里的存储分辨率（毫单位 int32，换算单点
+ *          s_milli_to_eng 在 run_par.c，本层不重除）
+ */
+static int feed_yt_db_row(uint8_t a_idx, ui_data_yt_row_t *a_out) {
+    float lo;
+    float hi;
+
+    if (run_par_db_range(a_idx, &lo, &hi) != 0) {
+        return -1;
+    }
+    a_out->val      = run_par_deadband(a_idx);
+    a_out->lo       = lo;
+    a_out->hi       = hi;
+    a_out->decimals = 3u;
+    a_out->unit     = (a_idx < 4u) ? UI_DATA_YT_UNIT_V
+                    : ((a_idx < 8u) ? UI_DATA_YT_UNIT_A : UI_DATA_YT_UNIT_HZ);
+    return 0;
+}
+
+/* 函数功能：写第 idx 行死区（直通语义 setter；返回值原样上抛，页面据此记账）  int */
+static int feed_yt_db_set(uint8_t a_idx, float a_eng) {
+    return run_par_deadband_set(a_idx, a_eng);
+}
+
+static uint8_t feed_yt_cal_n(void) {
+    return (uint8_t)RUN_PAR_CH_N;
+}
+
+/*
+ * 函数功能：读第 idx 路系数现状（k = adc_cal **当前生效值**，µV/码）
+ * 返回值：0 - 已写出；-1 - idx 越界或指针空  int
+ * 函数说明：显示值与 104 C_RD 回显同视图（run_par_104_read 用的就是 adc_cal_k_uv：
+ *          文件坏值被真带回退 ROM 时，屏与主站看到同一份 ROM——"页面值按比例
+ *          变化"判据因此量的就是执行段真正吃的数）；
+ *          lo/hi 只有粗守一层（0..RUN_PAR_K_MAX_UV，上限来自 run_par 唯一出口），
+ *          真带在执行段裁——两层守卫的注释纪律见 ui_w_ytview 头注；
+ *          decimals 取 0 是**显示域容量约束**不是精度偏好：粗守上限 1e9 在
+ *          ui_w_setlist 的 int32 显示域里只够零位小数（带 2 位则上限装不下），
+ *          屏上输入按整 µV 量化、写口仍收 float；要小数位得收紧粗守或改组件
+ *          值通道，都不在本批，也不许在此抄一份更小的假上限
+ */
+static int feed_yt_cal_row(uint8_t a_idx, ui_data_yt_row_t *a_out) {
+    if ((a_out == NULL) || (a_idx >= (uint8_t)RUN_PAR_CH_N)) {
+        return -1;
+    }
+    a_out->val      = adc_cal_k_uv((adc_semantic_t)a_idx);
+    a_out->lo       = 0.0f;    /* 下限 0 由写口拒 k<=0 兜住，这里只给输入框边界 */
+    a_out->hi       = RUN_PAR_K_MAX_UV;
+    a_out->decimals = 0u;
+    a_out->unit     = UI_DATA_YT_UNIT_UV;
+    return 0;
+}
+
+/* 函数功能：写第 idx 路系数 k（越界防御后再进语义 setter——setter 形参是枚举，
+ *           编译器帮不上越界忙；返回码直通）  int */
+static int feed_yt_cal_k_set(uint8_t a_idx, float a_uv) {
+    if (a_idx >= (uint8_t)RUN_PAR_CH_N) {
+        return -1;
+    }
+    return run_par_cal_k_set((adc_semantic_t)a_idx, a_uv);
+}
+
+/* 函数功能：未标定闭锁徽标源（task-16 单点访问器，与判据停走同一个判定）  uint8_t */
+static uint8_t feed_yt_cal_blocked(void) {
+    return (adc_cal_prot_blocked() != 0) ? 1u : 0u;
+}
+
+/* 函数功能：整档落盘脏位（保存行三态判据；与 104 留痕同一个 peek，不另发明）  uint8_t */
+static uint8_t feed_yt_pending(void) {
+    return run_par_dirty_peek();
+}
+
+/* 遥测整定注入表（八件齐全；ui_data_yt_bind 拒残表，缺件就是装配错） */
+static const ui_data_yt_ops_t s_yt_ops = {
+    feed_yt_db_n,
+    feed_yt_db_row,
+    feed_yt_db_set,
+    feed_yt_cal_n,
+    feed_yt_cal_row,
+    feed_yt_cal_k_set,
+    feed_yt_cal_blocked,
+    feed_yt_pending
+};
+
+/* ======================= 道G task-9：通讯参数注入表（ui_data_comm_ops_t）===
+ *
+ * 页面形状（两行的名/序）归 ui_page_comm.c；本层只转达值与合法带——
+ * lo/hi 现取 iec104_comm.h 带宏（唯一出口），值现取 getter（带内自愈），
+ * 装配层**不写第二份数值**（通道五同一条纪律）。
+ */
+
+/*
+ * 函数功能：读第 idx 行通讯参数现状（值 + 合法带）
+ * 入口参数：idx - UI_DATA_COMM_ROW_CA/_PORT  uint8_t
+ *           a_out - 行现状  ui_data_comm_row_t *
+ * 返回值：0 - 已整份写出；-1 - idx 越界（不猜、不顶替）  int
+ * 限定条件：uiTask 页面绘制链（经 ui_data 通道六转发）
+ */
+static int feed_comm_row(uint8_t a_idx, ui_data_comm_row_t *a_out) {
+    if (a_idx == UI_DATA_COMM_ROW_CA) {
+        a_out->val = iec104_comm_ca();
+        a_out->lo  = IEC104_COMM_CA_MIN;
+        a_out->hi  = IEC104_COMM_CA_MAX;
+        return 0;
+    }
+    if (a_idx == UI_DATA_COMM_ROW_PORT) {
+        a_out->val = iec104_comm_port();
+        a_out->lo  = IEC104_COMM_PORT_MIN;
+        a_out->hi  = IEC104_COMM_PORT_MAX;
+        return 0;
+    }
+    return -1;
+}
+
+/*
+ * 函数功能：写第 idx 行通讯参数（守卫在 setter：带外拒、副本不动、不置脏）
+ * 返回值：0 - 已写并置脏；-1 - idx 越界或带外拒  int
+ * 限定条件：uiTask 按键链（编辑提交）
+ * 函数说明：a_val > 65535 不在此先裁——截断成 u16 会把 65536 洗成 0 再被
+ *          setter 合法拒掉，等于替屏幕编了个假值；越界一律原样送 setter 拒
+ */
+static int feed_comm_set(uint8_t a_idx, uint32_t a_val) {
+    if (a_val > 65535uL) {
+        return -1;
+    }
+    if (a_idx == UI_DATA_COMM_ROW_CA) {
+        return iec104_comm_ca_set((uint16_t)a_val);
+    }
+    if (a_idx == UI_DATA_COMM_ROW_PORT) {
+        return iec104_comm_port_set((uint16_t)a_val);
+    }
+    return -1;
+}
+
+/* 函数功能：[comm] 段落盘脏位（与页面 WAIT/OK 同一枚 peek，不另发明）  uint8_t */
+static uint8_t feed_comm_pending(void) {
+    return iec104_comm_dirty_peek();
+}
+
+/* 通讯参数注入表（三件齐全；ui_data_comm_bind 拒残表） */
+static const ui_data_comm_ops_t s_comm_ops = {
+    feed_comm_row,
+    feed_comm_set,
+    feed_comm_pending
+};
+
+/* 首轮懒绑一次：ui_data_feed_tick() 的首个调用点在 App/task/ui_task.c 里先于
+ * ui_menu_init()（首帧发布那次），与通道四 ui_data_maint_bind 的绑定时序等价；
+ * 不在 ui_task.c 直接绑是为了本批写域收在派发单列出的文件里。残表是真故障，
+ * 必须能在启动日志里看见，不能静默（通道四同口径） */
+static uint8_t s_yt_bound;
+static uint8_t s_comm_bound;   /* 道G task-9 通讯参数表懒绑门（同款先置位防刷日志） */
+

 /*
 * 函数功能：组装参数快照（40 项定值 Q10 + 校验和 + 封存态 + 越界位图 + 未标定闭锁）
@@ -523,10 +734,12 @@ static void feed_fill_par(ui_data_par_t *p_snap, uint32_t sum) {
 */
 static void feed_fill_info(ui_data_info_t *p_snap, uint32_t tick_ms) {
    const ftp_cfg_t *p_ftp = ftp_cfg_get();
+    boot_stats_t        boot;
+    iec104_serv_stats_t st104;

    p_snap->valid     = 1u;
    p_snap->uptime_s  = tick_ms / 1000u;
-    p_snap->port_104  = (uint16_t)IEC104_SERV_PORT;
+    p_snap->port_104  = iec104_comm_port();   /* 真源 = [comm] RAM 副本（getter 带内恒成立，u16 读原子） */
    p_snap->port_disp = (uint16_t)UI_NET_SINK_PORT;
    feed_copy_str(p_snap->model, sizeof(p_snap->model), FEED_MODEL);
    feed_copy_str(p_snap->sw_ver, sizeof(p_snap->sw_ver), FEED_SW_VER);
@@ -538,6 +751,19 @@ static void feed_fill_info(ui_data_info_t *p_snap, uint32_t tick_ms) {
    } else {
        p_snap->ftp_user[0] = '\0';
    }
+    /* 运行报告四数（2026-10-28 UI 补齐）：纯搬运，页面不得自己去 include 这两个头。
+     * uptime_s 仍由本函数用 tick 差算——boot_stats 不提供时长，别在那里再算一份。 */
+    boot_stats_get(&boot);
+    iec104_serv_get_stats(&st104);
+    p_snap->boot_count        = boot.boot_count;
+    p_snap->boot_seq_state    = boot.seq_state;
+    p_snap->boot_write_failed = boot.write_failed;
+    p_snap->rst_cause         = boot.rst_cause;
+    p_snap->boot_ready        = boot.ready;
+    p_snap->iec104_conn_up    = st104.conn_up;
+    p_snap->iec104_apdu_tx    = st104.apdu_tx;
+    p_snap->iec104_tx_fail    = st104.tx_fail;
+    p_snap->iec104_rx_bytes   = st104.rx_bytes;
 }

 /*
@@ -558,6 +784,19 @@ void ui_data_feed_tick(void) {
    uint32_t sum;
    uint8_t  due_rt;

+    if (s_yt_bound == 0u) {
+        s_yt_bound = 1u;    /* 先置位再绑：失败也不每轮重试刷日志（90 B/条） */
+        if (ui_data_yt_bind(&s_yt_ops) != 0) {
+            DBG_ERROR("UI yt bind: FAIL");
+        }
+    }
+    if (s_comm_bound == 0u) {
+        s_comm_bound = 1u;  /* 道G task-9：同款一轮一绑；两表时序等价（先于 ui_menu_init） */
+        if (ui_data_comm_bind(&s_comm_ops) != 0) {
+            DBG_ERROR("UI comm bind: FAIL");
+        }
+    }
+
    now = osKernelGetTickCount();

    if (s_map_done == 0u) {
@@ -595,7 +834,7 @@ void ui_data_feed_tick(void) {
     * 但"校验和没变"不等于"页面该看的没变"——本帧里还有两个与校验和无关的事实：
     *   · locked（定值闭锁）：自检失配时置位，校验和一字不变，
     *     而整定页保存行要显示 LOCK 并禁编辑；
-     *   · cal_block（未标定闭锁）：卡 12 两点标定写完 [adc_cal] 的 valid 就翻转，
+     *   · cal_block（未标定闭锁）：两点标定写完 [adc_cal] 的 valid 就翻转，
     *     校验和同样不动，而标题上的"未标定"徽标要当场消失。
     * 只盯校验和，这两件事都到不了屏上（真机现象：标定做完了屏上徽标永远挂着，
     * 直到某次定值改动才被顺带刷掉——那是把两件不相干的事当同步点）。
@@ -10,7 +10,7 @@
 | `cfg_file.c/h` | **配置引擎核心**：解析 / 查询 / 保存 / 2s 周期 `cfg_file_poll` |
 | `cfg_file_store.h` | **存储后端抽象接口**（MCU=FreeRTOS 堆 / 模拟器=宿主堆，共享核心零分配符号） |
 | `cfg_file_store_mcu.c` | **MCU 端后端实现**：`/config.ini`（临时名由目标路径同目录推导 + `f_rename` 原子写） |
-| `prot_set_store.c/h` | **保护定值持久化胶水（B7）**：`/prot_set.bin` blob 读写（blob 格式/校验/原子装载在 `App/algo/prot_set.c` 纯逻辑层）；装载 = storage bring-up（屏障前），落盘 = defaultTask 消费 `SYS_EVT_PROT_SET_SAVE` |
+| `prot_set_store.c/h` | **保护定值持久化胶水**：`/prot_set.bin` blob 读写（blob 格式/校验/原子装载在 `App/algo/prot_set.c` 纯逻辑层）；装载 = storage bring-up（屏障前），落盘 = defaultTask 消费 `SYS_EVT_PROT_SET_SAVE` |

 ## 设计要点

@@ -25,7 +25,7 @@
 *                              s_gen_document 两处 `off += snprintf(...)` 改检查式（截断即
 *                              返回 -1，不再跳过缓冲末尾）；注册拒超长键名（≤ 15 字符），
 *                              使每行 112 字节余量成为可编译期验证的前提
- *     v1.5  2026-10-25  DTU 项目组  数据可信卡 3：新增值类型 CFG_VAL_INT（有符号十进制，
+ *     v1.5  2026-10-25  DTU 项目组  「数据可信」有符号零点类型：新增值类型 CFG_VAL_INT（有符号十进制，
 *                              len 1/2/4 小端补码）——s_decode_int() 用 strtol + ERANGE +
 *                              宽度上下界校验，s_encode() 带负号输出；负零点偏移从此可
 *                              干净落盘（动因见 docs/任务规划/数据可信.md §4.4 与 §7 决策 3）
@@ -43,7 +43,7 @@

 #include <ctype.h>

-#include <errno.h>     /* ERANGE：strtol 饱和判别（INT 键解码需要，数据可信卡 3） */
+#include <errno.h>     /* ERANGE：strtol 饱和判别（INT 键解码需要，「数据可信」有符号零点类型） */

 #include "cfg_file.h"

@@ -358,7 +358,7 @@ static int s_decode_uint(uint8_t *p_dst, size_t len, const char *p_val) {
 }

 /*
- * 函数功能：解析有符号十进制值（小端补码写入，数据可信卡 3）
+ * 函数功能：解析有符号十进制值（小端补码写入，「数据可信」有符号零点类型）
 * 入口参数：p_dst - 目标字段  uint8_t *
 *           len   - 字段字节数（1/2/4）  size_t
 *           p_val - 值文本（可带 +/- 号）  const char *
@@ -828,7 +828,7 @@ static int s_surgical(char *p_in, size_t in_len, char *p_out, size_t out_cap, si
                            char v[80];
                            /* s_encode 成功返回文本长度（≥1），失败返回 -1：
                             * 故判成功必须 `< 0` 取反，不能写 `== 0`（恒假，
-                             * 使补写路径沦为死码，见 2026-10-02 L0.5 修复） */
+                             * 使补写路径沦为死码，见 2026-10-02 主机侧纯逻辑单测修复） */
                            if (s_encode(p_key, (const uint8_t *)s_sections[idx].p_data + p_key->offset,
                                         v, sizeof(v)) >= 0) {
                                if (s_emit_kv(p_out, out_cap, &off, p_key->name, v) != 0) {
@@ -15,7 +15,7 @@
 *                              超长；超长处置补自检留痕
 *     v1.3  2026-10-15  王建锋  新增公开常量
 *                              CFG_FILE_MAX_NAME_LEN（段名/键名上限 15 字符）
- *     v1.4  2026-10-25  DTU 项目组  数据可信卡 3：新增 CFG_VAL_INT 有符号十进制值类型
+ *     v1.4  2026-10-25  DTU 项目组  「数据可信」有符号零点类型：新增 CFG_VAL_INT 有符号十进制值类型
 *                              （len = 1/2/4，小端补码）——标定零点偏移等负值需有符号
 *                              落盘，动因与取舍见 docs/任务规划/数据可信.md §4.4
 */
@@ -52,7 +52,7 @@ static uint32_t s_ld32(const uint8_t *p) {
 *           -1 损坏被拒
 * 函数说明：读失败与"文件不存在"同归 1——启动期卷锁无竞争（本任务独占
 *           bring-up），try-lock 失败即真 I/O 故障，此时保持出厂默认并让
- *           调用方按"无档"处理是安全侧（定值仍封存自洽，L5-1 不误锁）。
+ *           调用方按"无档"处理是安全侧（定值仍封存自洽，定值校验和不误锁）。
 *           **换代与损坏分开**（B8）：magic 完好但 ver/cnt 与当前固件不符 =
 *           定值表升级（如 B8 32→40 项），是**预期升级路径**不是损坏 →
 *           归 2 并打 INFO（"version change"措辞），调用方不得按 CORRUPT
@@ -16,7 +16,7 @@
 *          ⚠ 边界（勿当成掉电保护）：本板无掉电检测硬件，"掉电前强制 flush"
 *          不可行；"单次写事务进行中掉电"的丢失边界也不因本模块改变。
 * 适用平台：STM32F407ZGTx + FreeRTOS（CMSIS-RTOS V2）；仅 MCU 端，
- *          主机侧 L0.5 单测 test/host/vol_idle_sync/
+ *          主机侧纯逻辑单测 test/host/vol_idle_sync/
 * 作者：DTU 项目组
 * 创建日期：2026-10-25（道F 批 2：写回缓存空闲 flush 收口）
 * 修改记录：
@@ -6,7 +6,8 @@
 * 创建日期：2026-10-02
 * 修改记录：
 *     v1.0  2026-10-02  王建锋  创建
- *     v1.1  2026-10-26  DTU 项目组  道G task-17：① 新增 4 个观测计数（T-a/T2/T3/T4，
+ *     v1.1  2026-10-26  DTU 项目组  道G task-17：① 新增 4 个观测计数（持锁 / try 超时 /
+ *                              分片退让 / 零互斥 四态，
 *                              共 16 B 静态）与 vol_lock_get_stats() 只读口 —— 不取锁、
 *                              零外部调用、零局部变量，13 处调用点一字未动；
 *                              ② 修 :38「返回值」注释与代码相反的错（fail-open 原被
@@ -34,10 +35,10 @@ static osMutexId_t s_lock;   /* 卷串行化互斥锁（vol_lock_init 创建）
 * 并发：多个任务可同时自增同一个计数，竞态下少计不会多计（判据是"是否 > 0 / 是否还
 * 在增长"，不是精确值），所以不为此上临界区 —— 上临界区反倒把观测做成了故障本身。
 * volatile：跨任务读写且无锁保护，禁止把读侧重复读优化掉。 */
-static volatile uint32_t s_st_acquired;     /* T-a 真取到互斥 */
-static volatile uint32_t s_st_try_timeout;  /* T2 try（timeout=0）失败：卷被别人占住 */
-static volatile uint32_t s_st_blk_timeout;  /* T3 分片等待超时：ftpTask 正常退让 */
-static volatile uint32_t s_st_failopen;     /* T4 锁不存在却返 1：谎报成功那一态 */
+static volatile uint32_t s_st_acquired;     /* 持锁态：真取到互斥（四态定义见 vol_lock.h） */
+static volatile uint32_t s_st_try_timeout;  /* try 超时态：timeout=0 没取到，卷被别人占住 */
+static volatile uint32_t s_st_blk_timeout;  /* 分片退让态：分片等待超时，ftpTask 正常退让 */
+static volatile uint32_t s_st_failopen;     /* 零互斥态：锁不存在却返 1，谎报成功那一态 */

 /* 函数定义区 */

@@ -73,18 +74,18 @@ int vol_lock_wait(uint32_t timeout_ms) {
    if (s_lock == NULL) {
        (void)vol_lock_init();
        if (s_lock == NULL) {
-            s_st_failopen++;   /* T4：返 1 但零互斥 —— 谎报成功那一态 */
+            s_st_failopen++;   /* 零互斥态：返 1 但零互斥 —— 谎报成功那一态 */
            return 1;   /* 锁创建失败：fail-open（不阻塞，保持启动段可用） */
        }
    }
    if (osMutexWait(s_lock, timeout_ms) == osOK) {
-        s_st_acquired++;       /* T-a：真持锁 */
+        s_st_acquired++;       /* 持锁态：真持锁 */
        return 1;
    }
    if (timeout_ms == 0u) {
-        s_st_try_timeout++;    /* T2：压根没等（喂狗点/绘制路径只有这一态会发生） */
+        s_st_try_timeout++;    /* try 超时态：压根没等（喂狗点/绘制路径只有这一态会发生） */
    } else {
-        s_st_blk_timeout++;    /* T3：等了一会儿没等到（分片退让），语义与 T2 不同 */
+        s_st_blk_timeout++;    /* 分片退让态：等了一会儿没等到，与 try 超时态语义不同 */
    }
    return 0;
 }
@@ -72,13 +72,14 @@ int vol_lock_wait(uint32_t timeout_ms);

 /*
 * 卷锁观测计数（道G task-17「卷锁 5 态可观测性」）。四个字段就是四态，语义**不得**合并：
- *   T-a `acquired`    = 真取到互斥的次数
- *   T2  `try_timeout` = timeout=0 的 try 失败次数（卷被别的任务占住；defaultTask/uiTask
- *                       的喂狗与绘制路径只有这一态会发生）
- *   T3  `blk_timeout` = timeout>0 的分片等待超时次数（ftpTask 100 ms 分片正常退让，
- *                       语义与 T2 不同：那是"等了一会儿没等到"，这是"压根没等"）
- *   T4  `failopen`    = 锁不存在却返 1 的次数（**谎报成功**那一态，见 wait 的函数头）
- * T1「从未调用过」不占计数：三个计数全 0 就说明这条路径没跑过——区分"没跑过"与
+ *   `acquired`     持锁态      = 真取到互斥的次数
+ *   `try_timeout`  try 超时态  = timeout=0 的 try 失败次数（卷被别的任务占住；
+ *                                defaultTask/uiTask 的喂狗与绘制路径只有这一态会发生）
+ *   `blk_timeout`  分片退让态  = timeout>0 的分片等待超时次数（ftpTask 100 ms 分片正常
+ *                                退让；与 try 超时态语义不同：那是"等了一会儿没等到"，
+ *                                这是"压根没等"）
+ *   `failopen`     零互斥态    = 锁不存在却返 1 的次数（**谎报成功**那一态，见 wait 函数头）
+ * 「未调用」这一态不占计数：三个计数全 0 就说明这条路径没跑过——区分"没跑过"与
 * "跑了但一直忙"正是本卡的目的（此前两者在日志上完全一样）。
 * ⚠ 本层**刻意不记时刻**：记时刻就得读 tick，等于给 defaultTask 的取锁链添一个
 *   callee 与几字节帧，而这条链的余量我们整天都在省着花（诊断不值那几个字节）。
@@ -10,8 +10,8 @@
 | `sys_log.h` | **日志接口（平台无关）**：定长 64B 记录，七类各一个 `/log` 文件（run / selftest / accid / alarm / start / oper / yk）|
 | `sys_log_mcu.c` | `sys_log` 的 MCU 端后端实现（NAND + FatFs） |
 | `console_log.c/h` | **控制台单写者日志**：多任务日志经队列汇入唯一写者，避免串口输出交错 |
-| `soe_rec.c/h` | **SOE 记录纯编解码**（B9）：64B 定长记录（CP56Time2a 时标 + 类型 + 元件号 + 单调序号 + 值 + sum8 撕裂校验），零 I/O 零 OS 依赖，主机单测覆盖 |
-| `soe_store.c/h` | **SOE 落盘胶水**（B9）：`/log/soe.log`，protectTask 投递（零文件系统）→ defaultTask 排空落盘 |
+| `soe_rec.c/h` | **SOE 记录纯编解码**：64B 定长记录（CP56Time2a 时标 + 类型 + 元件号 + 单调序号 + 值 + sum8 撕裂校验），零 I/O 零 OS 依赖，主机单测覆盖 |
+| `soe_store.c/h` | **SOE 落盘胶水**：`/log/soe.log`，protectTask 投递（零文件系统）→ defaultTask 排空落盘 |

 ## 关键机制

@@ -42,7 +42,7 @@
  `syslog_request_clear()` 调用内就删完了，因此 `WAIT` 态在模拟器上永不出现
  （同 `syslog_post` 在两端"有队列 / 直写无队列"的差异）

-### 五类记录与「记录类型 = 日志 ID」（道F task-10，2026-10-26；task-11 记录 5 页按此做）
+### 五类记录与「记录类型 = 日志 ID」（道F task-10，2026-10-26；task-11 记录 5 页按此做，2026-10-28 五页已落地）

 **决策一：记录类型就是 `syslog_id_t` 本身，一类记录 = `/log` 下一个严格 8.3 短名的文件。**
 64B 定长记录体里**没有类型字段位**：`[0..18]` 时标 / `[19]` 空格 / `[20..29]` epoch /
@@ -59,11 +59,11 @@

 | 记录 | 日志 ID / 文件 | 容量上限 | 写入点 | 触发判据 |
 |---|---|---|---|---|
-| 事故 | `SYSLOG_ACCIDENT` / `accid.log` | 512 | `App/task/protect_task.c:181` | `asserted` 上升沿**且**该元件跳闸投退项 = 1 |
-| 保护告警 | `SYSLOG_ALARM` / `alarm.log` | 1024 | 同文件 `184` | `asserted` 上升沿**且**跳闸投退项 = 0 或该元件无此项 |
-| 保护启动 | `SYSLOG_START` / `start.log` | 1024 | 同文件 `176` | `picked` 上升沿（越限电平，早于/等于动作） |
-| 操作 | `SYSLOG_OPER` / `oper.log` | 512 | `App/protocol/iec104/iec104_pts.c:574/602`、`App/task/default_task.c:242`、`App/log/sys_log_mcu.c:646`（宿主 `sim_syslog.c:245`） | 强制复归受理 / 软压板投退落地 / 定值**真落盘成功** / 清除记录成功 |
-| 遥控 | `SYSLOG_YK` / `yk.log` | 256 | `App/protocol/iec104/iec104_pts.c:573/576/582/586/596/598/609` | 104 双点命令的选择段、执行段、非法 DPC、未知 IOA 各一条 |
+| 事故 | `SYSLOG_ACCIDENT` / `accid.log` | 512 | `App/task/protect_task.c:188` | `asserted` 上升沿**且**该元件跳闸投退项 = 1 |
+| 保护告警 | `SYSLOG_ALARM` / `alarm.log` | 1024 | 同文件 `191` | `asserted` 上升沿**且**跳闸投退项 = 0 或该元件无此项 |
+| 保护启动 | `SYSLOG_START` / `start.log` | 1024 | 同文件 `183` | `picked` 上升沿（越限电平，早于/等于动作） |
+| 操作 | `SYSLOG_OPER` / `oper.log` | 512 | `App/protocol/iec104/iec104_pts.c:582/610`、`App/task/default_task.c:266`、`App/log/sys_log_mcu.c:682`（宿主 `sim_syslog.c:245`） | 强制复归受理 / 软压板投退落地 / 定值**真落盘成功** / 清除记录成功 |
+| 遥控 | `SYSLOG_YK` / `yk.log` | 256 | `App/protocol/iec104/iec104_pts.c:581/584/590/594/604/606/617` | 104 双点命令的选择段、执行段、非法 DPC、未知 IOA 各一条 |

 - **"哪些元件算跳闸"只有一个真源**：定值表 `g_prot_set_meta` 里的 `PS_*_TRIP`（枚举注释
  即"0 告警 / 1 跳闸"）+ 实例表 `k_pe[]` 的 `trip_ctl` 列。分类入口
@@ -78,7 +78,7 @@
  任务用（**protectTask、iec104Task 必须用它**），丢弃只累加 `syslog_post_dropped()`、
  由唯一写者 defaultTask 在 `syslog_drain()` 里按差值补一条留痕——同 `soe_store_post`
  当年那条 `872 → 1192 B FAIL` 的实证纪律。收/丢判据两个口完全一致。
- **读侧契约（给 task-11）**：`syslog_count(id)` + `syslog_get_record(id, idx, ts, ts_len,
+- **读侧契约（给 task-11；2026-10-28 五页已按此接上）**：`syslog_count(id)` + `syslog_get_record(id, idx, ts, ts_len,
  desc, desc_len)` 与运行/自检记录**同一枚 reader**，"最近 20 条"= 从 `count-20` 起读；
  `count()==0` 就是空态，页面显示"无记录"。**不要**在共享代码里调 MCU 专属的
  `syslog_clear_apply()`（模拟器不实现 → 链接期报错是故意的）；清除一律走
@@ -90,7 +90,7 @@
 - 多任务的生产者 → **单写者消费者**，消除任务间日志行交错
 - 设计详见 `docs/子系统设计/控制台单写者日志设计说明.md`

-### soe（SOE 事件顺序记录，B9）
+### soe（SOE 事件顺序记录，SOE 记录）

 - **记录 = 64 B 定长二进制**（`soe_rec.h` 布局），落 `/log/soe.log`；
  与 run.log 分文件——run.log 是文本记录、有 UI/主机读取方，二进制 SOE
@@ -1,5 +1,5 @@
 /*
- * 模块名称：Console Single-Writer Logging — 控制台单写者日志（USART1）实现
+ * 模块名称：Console Single-Writer Logging — 控制台单写者日志（RS232#1 / UART5）实现
 * 模块功能：控制台单写者日志的环形缓冲 + 唯一写者发送实现（API 见 console_log.h）；
 *          兼载 MicroLIB printf 底层 fputc 重定向
 * 适用平台：STM32F407ZGTx（仅 MCU 端）
@@ -62,6 +62,13 @@
 *              三本账分开（docs §13-O2）：新增 dbg_console_tx_timeout()，dropped 只记
 *              真丢的，tx_fault 仍只记软复位自愈次数；[ERR] dropped 行改为"发成功才
 *              销账"，通道不可用期间不再把丢弃证据一起冲掉。
+ *     2026-10-28  王建锋  **根因归因更正（纯注释，无行为变更）**：原注释把 ORE 锁存
+ *              写成"PA10 悬空 / 未接线"，用户确认 PA10 **一直是接线的**，该归因不成立。
+ *              真正的充分条件是"**RX 使能了却从不读 DR**"——线上任意一个字节或一个
+ *              噪声沿使 RXNE 置位后无人读，下一个事件即锁存 ORE（ORE 只能靠"先读 SR
+ *              再读 DR"清除 ⇒ 永不自愈）；引脚悬空只影响发生率，不是必要条件。
+ *              缓解措施与结论不变，仅改注释；机制详见
+ *              docs/子系统设计/控制台单写者日志设计说明.md §12。
 */

 #include "console_log.h"
@@ -92,6 +99,18 @@
 *          与当场直发逐字节相同。ISR / 调度器未启动两种上下文放行（不许等）。
 * 约束：不新增任务、不动态分配；环形缓冲为 BSS（SRAM1，非 CCM），无 DMA 可达性冲突。
 */
+
+/* ===== 控制台端口（单点收口）=====
+ * 换口只改这一段：句柄 / IRQn / 初始化函数。时钟宏随句柄走——UART5 在 APB1、
+ * USART1 在 APB2，别照抄；串口模式与波特率在 Src/usart.c 的 MX_*_Init 里，本模块不管。
+ * 控制台在 RS232#1/UART5（USART1 专用给屏板链路——700 kbaud 只有它 MCU 引脚直出）。
+ * 端口排布、台架端子与判据见 docs/子系统设计/屏板链路设计说明.md 的 §2 与 §3.2。 */
+#define CON_UART                huart5
+#define CON_UART_IRQN           UART5_IRQn
+#define CON_UART_CLK_DISABLE()  __HAL_RCC_UART5_CLK_DISABLE()
+#define CON_UART_CLK_ENABLE()   __HAL_RCC_UART5_CLK_ENABLE()
+#define CON_UART_INIT()         MX_UART5_Init()
+
 #define DBG_CON_RING_SIZE  4096U    /* 环形缓冲字节数（必须为 2 的幂） */
 #define DBG_CON_CHUNK_MAX  256U     /* 写者单次 HAL_UART_Transmit 字节上限 */
 #define DBG_CON_WAIT_MS    200U     /* 缓冲满时生产者最长等待（ms），仍满则丢弃并计数 */
@@ -133,7 +152,7 @@ static volatile uint8_t  s_con_draining;    /* 1 = 处于 drain 中（重入保
 static volatile uint8_t  s_con_writer_up;   /* 1 = 写者已注册（此后走环形缓冲） */
 static volatile uint8_t  s_con_dwt_up;      /* 1 = DWT CYCCNT 已使能（硬上界基准可用） */
 static TaskHandle_t      s_con_writer_task; /* 写者任务句柄（自等保护用） */
-/* 行级单一所有者（道G task-23，O1 第二实例）：USART1 数据寄存器同一时刻只允许
+/* 行级单一所有者（道G task-23，O1 第二实例）：控制台串口数据寄存器同一时刻只允许
 * 一个上下文在逐字节轮询写入。NULL = 空闲。
 * ⚠ 这不是"锁"，是**所有权凭证**：拿不到就当场让路，绝不排队等待（见
 *   con_tx_try_claim 函数头：裸发一行 @115200 约 7.8 ms，把它包进临界区等于给
@@ -168,7 +187,7 @@ static TaskHandle_t      s_con_writer_task; /* 写者任务句柄（自等保护
 *   窗口可能被更高优先级上下文再次进入，共享量会被它改写、退出时就恢复错了。
 * ⚠ 只允许包住"几条指令"的量级，**绝不允许**包住串口发送本身：一行 90 B @115200
 *   约 7.8 ms，把它关进中断等于给启动窗口塞 7.8 ms 中断延迟与最坏喂狗抖动
- *   （红线与机器判据见 con_tx_bounded 函数头与主机单测 TC-CONLOG-015b/177）。
+ *   （红线与机器判据见 con_tx_bounded 函数头与主机单测 TC-CONLOG-015b 与 TC-CONLOG-177）。
 */
 #define CON_CRIT_ENTER(pm_var)  do { (pm_var) = __get_PRIMASK(); __disable_irq(); } while (0)
 #define CON_CRIT_EXIT(pm_var)   do { __set_PRIMASK(pm_var); } while (0)
@@ -221,7 +240,7 @@ static void con_dwt_ensure(void) {
 * 入口参数：u     - USART 寄存器基址（调用方已判非 NULL）  USART_TypeDef *
 *           p_buf - 待发数据；len - 字节数
 * 返回值：HAL_OK - 已发出；HAL_TIMEOUT - 计数上界内未完成（本块放弃）
- * 限定条件：USART1 已初始化
+ * 限定条件：控制台串口已初始化
 * 函数说明：刻意不用 HAL_UART_Transmit——理由见 CON_TX_GUARD_MAX 处注释
 *          （tick 依赖不可信 + 其调用链污染所有任务的最坏栈链）
 */
@@ -251,12 +270,12 @@ static HAL_StatusTypeDef con_tx_counted(USART_TypeDef *u, const uint8_t *p_buf,
 * 函数功能：有界裸发送（不依赖 uwTick / HAL 超时）
 * 入口参数：p_buf - 待发数据；len - 字节数（调用方已限 ≤ DBG_CON_CHUNK_MAX）
 * 返回值：HAL_OK - 已全部写入发送寄存器；HAL_TIMEOUT - 有界上界内未完成
- * 限定条件：USART1 已初始化
+ * 限定条件：控制台串口已初始化
 * 函数说明：寄存器级轮询 TXE/TC，超时判据用 DWT CYCCNT（CON_TX_TIMEOUT_CYC）；
 *          DWT 未使能时走 con_tx_counted（指令计数上界，2026-10-10 取代
 *          HAL_UART_Transmit 回退）。本函数只做 TX，
 *          不触碰 RX/错误标志——僵尸通道自愈由调用方按返回值处理。
- *          ⚠ USART1 未初始化（huart1.Instance == NULL，如 HAL_Init 早期或
+ *          ⚠ 控制台串口未初始化（CON_UART.Instance == NULL，如 HAL_Init 早期或
 *          断言/故障上报路径）时立即返回 HAL_ERROR：否则会解引用 NULL 去读写
 *          地址 0（flash 别名区）→ 在故障处理里再触发故障（2026-10-02 台架实测）。
 */
@@ -266,14 +285,14 @@ static HAL_StatusTypeDef con_tx_bounded(const uint8_t *p_buf, uint16_t len) {
    uint16_t i;

    con_dwt_ensure();
-    if (huart1.Instance == NULL) {
-        return HAL_ERROR;               /* USART1 未初始化：无可用通道，安全让位（不是超时，不记超时账） */
+    if (CON_UART.Instance == NULL) {
+        return HAL_ERROR;               /* 控制台串口未初始化：无可用通道，安全让位（不是超时，不记超时账） */
    }
    if (s_con_dwt_up == 0U) {
-        return con_tx_counted(huart1.Instance, p_buf, len);
+        return con_tx_counted(CON_UART.Instance, p_buf, len);
    }

-    u = huart1.Instance;
+    u = CON_UART.Instance;
    t0 = DWT->CYCCNT;
    for (i = 0U; i < len; i++) {
        while ((u->SR & USART_SR_TXE) == 0U) {
@@ -292,7 +311,7 @@ static HAL_StatusTypeDef con_tx_bounded(const uint8_t *p_buf, uint16_t len) {
 }

 /*
- * 函数功能：尝试取得"USART1 整行发送所有权"（**非阻塞**，道G task-23）
+ * 函数功能：尝试取得"控制台串口整行发送所有权"（**非阻塞**，道G task-23）
 * 返回值：CON_TX_HELD 已持有（发完必须 con_tx_release）/ CON_TX_BYPASS 放行且不记账
 *         / CON_TX_NO 别人正持有整行，调用方须让路
 * 限定条件：任意上下文（内部只有一次几条指令的临界区，绝不睡眠、绝不长期关中断）
@@ -408,7 +427,7 @@ void dbg_console_tx_end(void) {
 *   · 拿到所有权 -> 整行一次发完，中途不会有别人的字节插进来；
 *   · 拿不到 -> **本行不丢**，改投既有环形缓冲延后发。竞争失败不该变成丢行，更不该
 *     变成 [ERR]：台架那个未注册窗口每 3 次启动命中 2 次，按"丢弃 + [ERR]"处理只会
- *     把静默缺陷换成常红的门禁（[ERR] 是 @test 的 Forbidden 标记）。
+ *     把静默缺陷换成常红的门禁（[ERR] 是 /serial-boot-test 的 Forbidden 标记）。
 *     入环的是**同一批字节原文**，本模块与 drain 都不补前缀、不重打时间戳（DBG_* 的
 *     前缀在调用点就已 snprintf 进调用方缓冲）-> 延后发出去的行与它当场直发时
 *     逐字节相同（判据⑦），取证时不会出现"证据说谎"；
@@ -466,20 +485,24 @@ uint8_t dbg_console_writer_ready(void) {
 }

 /*
- * 函数功能：USART1 僵尸通道自愈（清错误锁存 + 整外设重初始化）
- * 函数说明：RX 悬空噪声（PA10 未接线）锁存的 ORE/NE/FE/PE 使 HAL 轮询 TX 恒快速失败
- *       （控制台静默、系统不复位）；发送器卡死状态则使 TXE 等待耗满超时（冻结唯一
- *       写者 → 看门狗误复位，2026-10-02 台架实证）。外设软复位清锁存与卡死状态后
- *       重新初始化，故障时间被单块超时限定
+ * 函数功能：控制台串口僵尸通道自愈（清错误锁存 + 整外设重初始化）
+ * 函数说明：**RX 使能了却从不读 DR** → 线上任意一个字节或一个噪声沿使 RXNE 置位后无人读，
+ *       下一个事件即锁存 ORE（常伴 NE/FE/PE）；ORE 只能靠"先读 SR 再读 DR"清除 ⇒ 永不自愈。
+ *       锁存后 HAL 轮询 TX 恒快速失败（控制台静默、系统不复位）；发送器卡死状态则使 TXE
+ *       等待耗满超时（冻结唯一写者 → 看门狗误复位，2026-10-02 台架实证）。外设软复位清锁存与卡死状态后
+ *       重新初始化，故障时间被单块超时限定。
+ *       ⚠ 2026-10-28 更正：原注释把根因写成"PA10 未接线 / 悬空"，用户确认 PA10 一直是接线的；
+ *       充分条件是"RX 使能却不消费 DR"，与引脚是否悬空无关
+ *       （详见 docs/子系统设计/控制台单写者日志设计说明.md §12）。
 */
 static void con_uart_reinit(void) {
-    __NVIC_ClearPendingIRQ(USART1_IRQn);
-    __HAL_RCC_USART1_CLK_DISABLE();
-    __HAL_RCC_USART1_CLK_ENABLE();
-    huart1.gState = HAL_UART_STATE_RESET;
-    huart1.RxState = HAL_UART_STATE_RESET;
-    huart1.ErrorCode = HAL_UART_ERROR_NONE;
-    (void)MX_USART1_UART_Init();
+    __NVIC_ClearPendingIRQ(CON_UART_IRQN);
+    CON_UART_CLK_DISABLE();
+    CON_UART_CLK_ENABLE();
+    CON_UART.gState = HAL_UART_STATE_RESET;
+    CON_UART.RxState = HAL_UART_STATE_RESET;
+    CON_UART.ErrorCode = HAL_UART_ERROR_NONE;
+    (void)CON_UART_INIT();
 }

 /*
@@ -501,7 +524,7 @@ void dbg_console_drain(void) {
        return;                        /* 重入保护：写者自记录不触发嵌套 drain */
    }

-    /* 整行所有权（道G task-23）：本函数按块直写 USART1->DR，若此刻别的应用上下文
+    /* 整行所有权（道G task-23）：本函数按块直写 CON_UART->DR，若此刻别的应用上下文
     * 还在未注册期那条裸发里发到自己一半（attach 就发生在 defaultTask 里，与别的
     * 任务裸发**可以**前后脚撞上），两边就会逐字节交错——那正是本卡要修的形态。
     * 拿不到就**本轮让位**：tail 不推进 => 环里一条不少，主循环 ≤50 ms 后再试，
@@ -549,7 +572,7 @@ void dbg_console_drain(void) {

        if (st != HAL_OK) {
            if (st == HAL_ERROR) {
-                /* 2026-10-24 修复：USART1 **未初始化**（huart1.Instance == NULL，
+                /* 2026-10-24 修复：控制台串口 **未初始化**（CON_UART.Instance == NULL，
                 * 只可能出现在 HAL_Init 早期或断言/故障上报路径）与"僵尸通道"是两回事：
                 * 这里**绝不做外设重初始化**——那会在 HAL 尚未就绪时跑 MspInit 重配
                 * RCC/GPIO；也不计 tx_fault（那本账的语义是"软复位自愈次数"）。
@@ -1,5 +1,5 @@
 /*
- * 模块名称：Console Single-Writer Logging — 控制台单写者日志（USART1 调试串口）
+ * 模块名称：Console Single-Writer Logging — 控制台单写者日志（RS232#1 / UART5）
 * 模块功能：调试控制台单写者环形缓冲的公共 API：所有任务/上下文（含 printf）只把
 *          已格式化整行文本入环形缓冲，写者任务（defaultTask）为唯一
 *          HAL_UART_Transmit 发送点（行级原子 + 指针可控）
@@ -50,7 +50,7 @@ extern "C" {
 *                              （道G task-23）。诊断；[ERR] CONSOLE dropped 行报的就是它。
 *                              ⚠ 抢不到所有权但成功让路入环的那条行**不入本账**（它没丢，
 *                              只是晚一点发）——这本账必须保持"红得有意义"，因为
- *                              [ERR] 是 @test 的 Forbidden 标记）
+ *                              [ERR] 是 /serial-boot-test 的 Forbidden 标记）
 *   dbg_console_tx_fault     - 因僵尸通道软复位自愈的次数（诊断，语义不变）
 *   dbg_console_tx_timeout   - 写者排空时观察到的块超时次数（TXE / TC 两条硬上界都算）。
 *                              三本账分开：看日志有没有在丢 -> dropped；看外设自愈了几次
@@ -2,9 +2,9 @@
 * 模块名称：SOE Record — 事件顺序记录编解码（纯逻辑，双端可测）
 * 模块功能：定长 64B SOE（Sequence-of-Events）记录的构建与解析：
 *           CP56Time2a 时标 + 记录类型 + 元件号 + 单调序号 + 值 + 校验和。
- *           **零 I/O、零 OS 依赖**（仅 stdint/string）→ 主机侧 L0.5 离线单测
+ *           **零 I/O、零 OS 依赖**（仅 stdint/string）→ 主机侧纯逻辑离线单测
 *           （分层约束：协议/记录与硬件 I/O 分离）。
- * 记录口径（docs/算法/继电保护功能复现规划.md §3.4 L4-4/L4-5，B9）：
+ * 记录口径（docs/算法/继电保护功能复现规划.md §3.4「SOE 记录」「动作记录」，B9）：
 *   落盘文件 = /log/soe.log（8.3 合规；FF_USE_LFN=0 约束），定长 64B 一条
 *   （照 run.log 先例：count = filesize/64 O(1)、容量满删除重建）。
 *   独立于 run.log 的理由：run.log 是文本记录（时间戳+epoch+UTF-8 描述，
@@ -61,7 +61,7 @@ extern "C" {
 *   4 软压板投入 value = 1
 *   5 采样闭锁   value = adc_health 闭锁位图（触发时的 hf & mask）
 *   6 采样恢复   value = 0
- *   7 标定闭锁   value = UA/UN/IA VALID 未齐的通道位图（卡 5，2026-10-25）
+ *   7 标定闭锁   value = UA/UN/IA VALID 未齐的通道位图（未标定即闭锁，2026-10-25）
 *   8 标定复归   value = 0
 */
 typedef enum {
@@ -71,7 +71,7 @@ typedef enum {
    SOE_T_PLATE_IN,
    SOE_T_SAMPLE_BLOCK,
    SOE_T_SAMPLE_RESUME,
-    /* 未标定闭锁（「数据可信」卡 5，2026-10-25 道A 追加）：UA/UN/IA 的 VALID
+    /* 未标定闭锁（「数据可信」未标定即闭锁一项，2026-10-25 道A 追加）：UA/UN/IA 的 VALID
     * 未全置位 → 判据停走；与采样闭锁分型，边沿各留一条记录 */
    SOE_T_CAL_BLOCK,
    SOE_T_CAL_RESUME,
@@ -185,7 +185,7 @@ static int s_soe_append(const uint8_t *rec) {
        fr = f_write(&f, rec, SOE_REC_SIZE, &bw);
        (void)f_close(&f);
        if ((fr != FR_OK) || (bw != SOE_REC_SIZE)) {
-            /* L1 文件级自愈：**只有写失败**才删除重建、重试一次（打开失败走下面
+            /* 文件级自愈：**只有写失败**才删除重建、重试一次（打开失败走下面
             * 的 else，不删——见函数头 ④）。unlink 返回值刻意不检查：失败也只是
             * 重试失败 → 留痕计数，绝不升级成卷操作。 */
            (void)f_unlink(SOE_PATH);
@@ -44,7 +44,8 @@ extern "C" {
 *   同理二进制 SOE 通道的 soe_type_t 本轮**不动**：改它必须同步 UI 侧的类型名表
 *   （类型名表在 UI 侧 <Drivers/BSP/UI/ui_w_soe.c>，不在本道写域），而且 SOE
 *   页与这五页是两套读者。
- *   口径与五个写入点已登记进 App/log/README.md（task-11「记录 5 页」按此做）。
+ *   口径与五个写入点已登记进 App/log/README.md（task-11「记录 5 页」按此做——五个页面已于
+     *   2026-10-28 落地：ui_page_accident / oper / alarm / start / yk，各页只读一个文件）。
 */
 typedef enum {
    SYSLOG_RUN = 0u,       /* 运行记录 /log/run.log：上电/重启事件 */
@@ -7,6 +7,15 @@
 * 作者：王建锋
 * 创建日期：2026-09-14
 * 修改记录：
+ *     v1.8  2026-10-27  DTU 项目组  道G task-40：syslog_drain() 尾部按**边沿**补投一条
+ *                              卷锁 fail-open（零互斥那一态）自检记录。锁层只自增计数不产日志
+ *                              （唯一能写的通道自己也要这把**非递归**卷锁），留痕必须由
+ *                              唯一写者做；一个 episode（= 一次上电）只投一条，不打
+ *                              DBG 错级、不打 [ERR]（[ERR] 是"设备出故障"的唯一信号
+ *                              通道，塞进可观测性事件就变成第二个信号源——与 task-23
+ *                              "日志让路不计 [ERR]"同一根判据）。
+ *                              成本：.bss +48 B（3 枚计数/标志 + 静态快照 + 静态行缓冲），
+ *                              **零栈增量**（缓冲全静态；前后两表见 task-40 交付）。
 *     v1.7  2026-10-26  王建锋  「记录 5 页」的数据面（task-10）：syslog_id_t 尾部追加
 *                              SYSLOG_ACCIDENT / ALARM / START / OPER / YK 五枚，本文件
 *                              s_paths[]/s_caps[] 同步到七项（**必须与枚举同序**，越界
@@ -162,6 +171,33 @@ static volatile uint8_t s_post_pboot_full_reported;/* 启动前数组满丢弃
 static volatile uint32_t s_quiet_drop;      /* quiet 通道累计丢弃条数 */
 static uint32_t          s_quiet_reported;  /* drain 侧已上报水位（唯一写者私有） */

+/* 卷锁 fail-open（零互斥那一态）的边沿留痕（道G task-40，2026-10-27）
+ * ------------------------------------------------------------------
+ * 锁层只**自增计数**、绝不产日志：唯一能把事写下来的通道（/log/wdev.log 等）自己也要
+ * 取这把卷锁，而卷锁**非递归**——被卷忙挡住时既写不出东西，也不许在失败分支里再去取
+ * 同一把锁（App/fs/vol_lock.h「可观测性」段 + task-17 查出的事实）。所以留痕由唯一写者
+ * （defaultTask）在这里按**边沿**补投，投的是自检记录。
+ * ⚠ episode = 一次上电，只投一条。fail-open 的成因是"互斥体从未创建成功"（vol_lock.c
+ *   的那一支），一旦成立，后面每一次取锁都零互斥；若"计数每前进一次报一条"
+ *   就等于每轮 drain 一条记录 + 一次 NAND 写——诊断自己变成负载，正是上面 s_quiet_drop
+ *   那条纪律要避免的事（同款先例另有 App/fs/vol_idle_sync.c 的 s_vol_sync_fail_latch）。
+ * ⚠ **不打 DBG 错级、不打 [ERR]**：[ERR] 在本仓是"设备出故障"的唯一信号通道（/serial-boot-test 的
+ *   Forbidden 标记也依赖它，四个 Fault 的崩溃日志都以 [ERR] 开头）。把一个可观测性事件
+ *   塞进 [ERR]，它就同时不再是故障、也不再是禁令，两边一起失去意义——与 task-23 里
+ *   "日志让路不计 [ERR]"是同一根判据。机器判据 = TC-SYSLOG-137 里的 g_sys_err_count == 0。
+ * 时刻：本模块在这里**不读 tick**（读一次 tick 就给 defaultTask 的 drain 最坏链多挂一个
+ *   callee，而这条链的余量我们一直在省着花）。记录自带的 ts 字段就是"**被观测到的时刻**"
+ *   ——不是发生时刻，粒度 = 一轮 drain；这正是 vol_lock.h 第②条告诫要求消费方自己说清的
+ *   那件事，所以这里不另造 obs_first_ms/obs_last_ms 字段（那只会造出第二个"看起来像发生
+ *   时刻"的东西）。要"何时开始忙"的精确窗口，请读 vol_lock_get_stats() 的现值。
+ * 成本：3 枚计数/标志 + 一份静态快照 + 一行静态文本 ≈ 48 B .bss，**零栈增量**
+ *   （缓冲全静态，照 App/util/task_prof.c 的 s_prof_line 先例；前后 stack_report 两表
+ *   见 task-40 交付）。 */
+static volatile uint32_t s_vl_failopen_seen;  /* drain 侧上次读到的 fail-open 计数 */
+static uint8_t           s_vl_reported;       /* 本 boot 已留痕（1 = 本 episode 不再投） */
+static vol_lock_stats_t  s_vl_now;            /* 静态快照，不走调用方栈 */
+static char              s_vl_note[32];       /* 记录文本（落盘按 SYSLOG_DESC_MAX=28 截断） */
+
 /* 日志读写放大收口（2026-10-15，读侧）：8 条滑动读窗口 + 写者代数。
 * 窗口 512 B 走静态（不吃任务栈；defaultTask/uiTask 最坏链见 stack_report.py，
 * 预算余量见 docs/内存管理/RAM预算台账.md）。s_rd_gen 由写者自增、读者比对，
@@ -243,7 +279,7 @@ static volatile int8_t  s_clear_st[SYSLOG_COUNT];   /* SYSLOG_CLEAR_NONE / OK /
 */
 /*
 * 函数功能：判定一个 f_open 返回码是否属于"把自己的日志文件删掉重建一次"能修好
- *           的那一类，即 L1 文件级自愈的触发集（D 项整改，逐码依据见上方资料块）
+ *           的那一类，即文件级自愈的触发集（D 项整改，逐码依据见上方资料块）
 * 入口参数：fr - f_open 的返回码  FRESULT
 * 返回值：1 - 属触发集，可 unlink 后重开一次；0 - 不属，一律立即失败、不 unlink、
 *         不计卷损坏  int
@@ -326,8 +362,8 @@ static int s_append_rec(syslog_id_t id, const uint8_t *p_rec) {
            return -1;
        }
    }
-    /* L1 文件级自愈：陈旧/损坏条目 → 丢弃重建、重试一次（与上方容量满重建
-     * 同一机制）；L2 错误去重：持续故障只报第一次，恢复前静默（消除"每次
+    /* 文件级自愈：陈旧/损坏条目 → 丢弃重建、重试一次（与上方容量满重建
+     * 同一机制）；错误去重：持续故障只报第一次，恢复前静默（消除"每次
     * 开机同一错误刷屏"）。打开模式必须带 FA_WRITE 位：本 FatFs 移植的
     * FA_OPEN_APPEND(0x30) 不含 FA_WRITE(0x02)，不带写位打开的文件 f_write
     * 恒返回 FR_DENIED(7)——2026-09-20 台架实测 /log 写失败 ×5/开机 真根因 */
@@ -843,6 +879,22 @@ void syslog_drain(void) {
        s_quiet_reported = s_quiet_drop;
        DBG_ERROR("quiet drop total=%lu", (unsigned long)s_quiet_drop);
    }
+    /* 卷锁 fail-open（零互斥那一态）边沿补投一条自检记录（约束与理由全在上面那组静态量旁边）。
+     * vol_lock_get_stats() 不取锁、不关中断、不阻塞：卷被长期占住时正是最需要读它的
+     * 时刻，观测口若再去抢同一把锁，就把观测做成了故障的一部分。
+     * 必须排在 s_clear_service() 之前吗？不必——两者无先后关系（清除的是记录文件，
+     * 本条是**新增**一条自检记录）；但必须排在下面 soe_store_drain() 之前，因为本函数
+     * 这条支路不持卷锁，而 soe_store_drain() 自己 try 锁（沿用本函数既有纪律）。 */
+    vol_lock_get_stats(&s_vl_now);
+    if (s_vl_now.failopen != s_vl_failopen_seen) {
+        s_vl_failopen_seen = s_vl_now.failopen;   /* 水位每轮都追：别让下一轮误判"新增" */
+        if (s_vl_reported == 0U) {
+            s_vl_reported = 1U;                   /* 一个 episode 一条（= 一次上电） */
+            (void)snprintf(s_vl_note, sizeof(s_vl_note), "vollock failopen=%lu",
+                           (unsigned long)s_vl_failopen_seen);
+            syslog_post(SYSLOG_SELFTEST, s_vl_note);
+        }
+    }
    /* 「清除记录」的落地半边——必须在上面的条目排空**之后**（顺序是判据的一部分：
     * 先删后写会把本轮刚排空的旧记录又落回去，count 不归零 = 没实际效果的按钮），
     * 也在 soe_store_drain() 之前：本函数自带卷锁 try，绝不在此持锁状态下调用。
@@ -11,7 +11,7 @@

 | 子目录 | 协议 | 说明 |
 |---|---|---|
-| `iec104/` | IEC 60870-5-104 被控站（TCP 2404 上行） | **纯逻辑**三件套（asdu/pts/link，零 I/O，数据源 vtable 注入）→ 全栈 L0.5 主机单测；板端胶水与点表决策 → `docs/子系统设计/IEC104上行设计说明.md` |
+| `iec104/` | IEC 60870-5-104 被控站（TCP 工厂默认 2404 上行） | **纯逻辑**三件套（asdu/pts/link，零 I/O，数据源 vtable 注入）→ 全栈主机侧纯逻辑单测；板端胶水与点表决策 → `docs/子系统设计/IEC104上行设计说明.md` |

 ## 何时使用本目录

@@ -1,7 +1,7 @@
 /*
 * 模块名称：IEC 60870-5-104 ASDU 编解码（应用层，纯逻辑）
 * 模块功能：104 规约应用服务数据单元（ASDU）的类型/传送原因常量、组帧与解析。
- *           **零 I/O、零平台依赖**（仅 stdint.h）→ 主机侧 L0.5 可离线单测
+ *           **零 I/O、零平台依赖**（仅 stdint.h）→ 主机侧可离线纯逻辑单测
 *           （分层约束：协议解析与硬件 I/O 分离）。
 * 口径来源：docs/算法/继电保护功能复现规划.md §1.5（B0 产品定义）——
 *   公共地址 2 字节、传送原因 2 字节、信息体地址 IOA **3 字节**（101 为 2 字节）；
@@ -40,6 +40,13 @@ static const iec104_comm_t s_comm_rom = {
    IEC104_COMM_DEF_CA, IEC104_COMM_DEF_PORT
 };

+/* 落盘脏位（B7 形态，run_par/prot_set 同款）：setter 成功置 1，
+ * iec104_comm_store_save() 写盘成功清 0。**不挂回调、不加事件位**（task-8
+ * D5 裁定的持久化面延续）：defaultTask 每轮无条件调 store_save，无脏空转。
+ * 单字节标志：uiTask 写、defaultTask 读清——置 1 幂等、清零窗口最坏
+ * 多跑一轮 save，语义无损（run_par s_dirty 同一条竞态分析）。 */
+static volatile uint8_t s_comm_dirty;
+
 /* 键表（s_comm 布局内偏移，同 net_cfg/ftp_cfg 写法） */
 static const cfg_key_def_t s_comm_keys[] = {
    { "ca",   CFG_VAL_UINT, offsetof(iec104_comm_t, ca),   2u },
@@ -57,6 +64,7 @@ int iec104_comm_init(void) {
    cfg_section_reg_t reg;

    (void)memcpy(&s_comm, &s_comm_rom, sizeof(s_comm));
+    s_comm_dirty = 0u;

    (void)memset(&reg, 0, sizeof(reg));
    reg.name = IEC104_COMM_SEC;
@@ -100,27 +108,63 @@ uint16_t iec104_comm_port(void) {
 /*
 * 函数功能：写 ca 进 RAM 副本（守卫 = getter 同带；非法不提交）
 * 入口参数：ca - 公共地址  uint16_t
- * 返回值：0 提交；-1 带外（副本不动）  int
- * 限定条件：UI 保存交接路（task-9）；落盘走 SYS_EVT_CFG_SAVE 整档外科 save
+ * 返回值：0 提交并置落盘脏；-1 带外（副本不动、不置脏）  int
+ * 限定条件：UI 保存交接路（通讯设置页经 ui_data 通道六转进来）与宿主测试；
+ *          落盘 = defaultTask 每轮无条件 iec104_comm_store_save()（无事件位）
 */
 int iec104_comm_ca_set(uint16_t ca) {
    if ((ca < IEC104_COMM_CA_MIN) || (ca > IEC104_COMM_CA_MAX)) {
        return -1;
    }
    s_comm.ca = ca;
+    s_comm_dirty = 1u;
    return 0;
 }

 /*
 * 函数功能：写 port 进 RAM 副本（守卫 = getter 同带；非法不提交）
 * 入口参数：port - 监听端口  uint16_t
- * 返回值：0 提交；-1 带外（副本不动）  int
- * 限定条件：同 iec104_comm_ca_set
+ * 返回值：0 提交并置落盘脏；-1 带外（副本不动、不置脏）  int
+ * 限定条件：同 iec104_comm_ca_set（生效时刻 = 下一次重 bind 监听）
 */
 int iec104_comm_port_set(uint16_t port) {
    if ((port < IEC104_COMM_PORT_MIN) || (port > IEC104_COMM_PORT_MAX)) {
        return -1;
    }
    s_comm.port = port;
+    s_comm_dirty = 1u;
+    return 0;
+}
+
+/*
+ * 函数功能：落盘脏探查（非消费）——页面保存行 WAIT/OK 的唯一判定源
+ * 返回值：1 有未落盘改动；0 干净  uint8_t
+ * 限定条件：无（任意上下文纯读）
+ * 函数说明：脏位是全段级（ca+port 一次 save 一起落）：归零只证明
+ *          「这一档落盘了」，不证明「我这一项单独落盘」；104 侧无自动
+ *          写者（ca/port 不经 C_SE 整定），比 run_par 少一条「他人再改」
+ *          干扰，页面仍按「结果锁存」画（run_par 页同口径，别做两套）
+ */
+uint8_t iec104_comm_dirty_peek(void) {
+    return s_comm_dirty;
+}
+
+/*
+ * 函数功能：执行落盘（整档外科 save 成功后清脏；失败脏保持 = 下轮重试）
+ * 返回值：0 成功/无脏；-1 写盘失败  int
+ * 限定条件：**defaultTask（配置引擎属主）上下文**——run_par_store_save()
+ *          同一调用点旁挂，每轮无条件
+ * 函数说明：失败不打日志是刻意的（App/protocol 零日志惯例，本文件无 DBG）：
+ *          cfg_file_save 自身已有 DBG_ERROR 留痕 + 脏位保留 = 屏上 ERR 的
+ *          判定源，再打一条就是重复锚点（AGENTS 日志成本口径）
+ */
+int iec104_comm_store_save(void) {
+    if (s_comm_dirty == 0u) {
+        return 0;
+    }
+    if (cfg_file_save() != 0) {
+        return -1;
+    }
+    s_comm_dirty = 0u;
    return 0;
 }
@@ -7,12 +7,15 @@
 *           判定；初版曾寄身 iec104_pts.c 尾段，2026-10-26 lead 纠偏迁出）。
 * 修改记录：
 *     2026-10-26  DTU 项目组  创建（道G task-8）；同日实现位置改配对拆分。
+ *     2026-10-27  DTU 项目组  道G task-9：脏位 + iec104_comm_dirty_peek() /
+ *                               store_save()（run_par B7 同款，通讯设置页与
+ *                               defaultTask 轮询的消费面）。
 * 线程约定：注册/复位 = app_main_init 内核前（run_par_init / adc_cal_init 同款
 *           "先注册后 load"契约）；load/save/poll = defaultTask（配置引擎属主，
 *           netTask/uiTask 不得直接触碰引擎）；getter = 任意消费上下文（u16
 *           半字对齐读天然原子，重载瞬间最坏 = 单字段新旧值之一）；setter =
 *           UI 保存交接路（task-9，net_cfg_set_* 先例）。
- * 生效语义：**改后重启生效**（docs/任务规划/UI补齐.md §2 第 5 行验收口径）——
+ * 生效语义：**改后重启生效**（通讯设置页验收口径，docs/任务规划/UI补齐.md §2）——
 *           iec104Task 启动时取一次 getter 填 link cfg；端口另在下次重 bind
 *           （拆链/网络代次重建）自然生效，不必整机重启。不挂段回调、不新增
 *           事件位、不走 SYS_EVT_NET_RECONFIG（网络代次链语义不同；且 CH395F
@@ -34,9 +37,10 @@ extern "C" {
 /* 段名（cfg_file 引擎注册用；≤ CFG_FILE_MAX_NAME_LEN） */
 #define IEC104_COMM_SEC       "comm"

-/* 工厂默认：CA = 1（点表口径，V0.1 沿用）；端口 = 2404（DL/T 634.5104 标准，
- * 与 App/task/iec104_serv.h 的 IEC104_SERV_PORT 同值——该宏现仅作
- * ui_data_feed 快照兼容出口保留，运行期真源 = 本段 getter） */
+/* 工厂默认：CA = 1（点表口径，V0.1 沿用）；端口 = 2404（DL/T 634.5104 标准）。
+ * 原同名宏 IEC104_SERV_PORT（App/task/iec104_serv.h）已随道G task-9 快照切
+ * getter 删除——本段 getter 自 task-8 起就是运行期唯一真源，本头文件是这两个
+ * 常量的唯一出口 */
 #define IEC104_COMM_DEF_CA    1u
 #define IEC104_COMM_DEF_PORT  2404u

@@ -79,8 +83,9 @@ uint16_t iec104_comm_port(void);
 * 函数功能：写 ca 到 RAM 副本（守卫 = getter 合法带；非法值不提交）
 * 入口参数：ca - 公共地址 1..65535  uint16_t
 * 返回值：0 - 提交；-1 - 带外（副本不动）  int
- * 限定条件：调用方 = UI 保存交接路（task-9）；落盘经 SYS_EVT_CFG_SAVE
- *           整档外科 save（net_cfg_save_request 同款交接，本模块不写盘）
+ * 限定条件：调用方 = 通讯设置页（ui_data 通道六注入转 uiTask 上下文）；
+ *           成功置落盘脏——写盘 = defaultTask 每轮无条件
+ *           iec104_comm_store_save()（run_par B7 同款，无事件位、不写盘于本模块）
 */
 int iec104_comm_ca_set(uint16_t ca);

@@ -88,10 +93,28 @@ int iec104_comm_ca_set(uint16_t ca);
 * 函数功能：写 port 到 RAM 副本（守卫 = getter 合法带；非法值不提交）
 * 入口参数：port - 监听端口 1024..65535  uint16_t
 * 返回值：0 - 提交；-1 - 带外（副本不动）  int
- * 限定条件：同 iec104_comm_ca_set
+ * 限定条件：同 iec104_comm_ca_set（生效时刻 = 下一次重 bind 监听，改后不必重启）
 */
 int iec104_comm_port_set(uint16_t port);

+/*
+ * 函数功能：落盘脏探查（非消费）——页面保存行 ENTER/WAIT/OK 判定源
+ * 返回值：1 - 有已改未落盘；0 - 干净  uint8_t
+ * 限定条件：无（任意上下文纯读）
+ * 函数说明：脏位段级（ca+port 同档共落）；页面按「结果锁存」画，与 run_par
+ *          页同一条纪律（ui_w_ytview 文件头）
+ */
+uint8_t iec104_comm_dirty_peek(void);
+
+/*
+ * 函数功能：执行落盘（整档外科 save 成功清脏；失败脏保持下轮重试）
+ * 返回值：0 - 成功/无脏；-1 - 写盘失败（屏上 ERR 的判定源）  int
+ * 限定条件：**defaultTask（配置引擎属主）上下文**；由 default_task.c 的
+ *           run_par_store_save() 同点位每轮无条件调用（本模块不挂回调、
+ *           不设事件位——task-8 D5 口径的持久化面）
+ */
+int iec104_comm_store_save(void);
+
 #ifdef __cplusplus
 }
 #endif
@@ -9,9 +9,10 @@
 *           → clock_sync 回调）、试验（C_TS）与进程复位（C_RP，清快照）。
 *           **零 I/O**：收 = on_rx 喂 TCP 流片段，发 = send_apdu 回调，
 *           时基 = 调用方注入 now_ms（tick ms，回绕安全：差值法）
- *           → 全栈（asdu+pts+link）主机侧 L0.5 可离线跑（分层约束）。
+ *           → 全栈（asdu+pts+link）主机侧纯逻辑单测可离线跑（分层约束）。
 * 参数（DL/T 634.5104 标准默认，§1.5 未另定）：k=12 w=8 t1=15s t2=10s t3=20s。
- * 端口：TCP **2404**（§1.5 B0 定义；本 DTU = 被控站/服务器，主站连入）。
+ * 端口：TCP **2404** = 工厂默认（§1.5 B0 定义 / IEC 60870-5-104 标准端口；
+ *   本 DTU = 被控站/服务器，主站连入）。真源与可改性见本文件下方 [comm] 段说明。
 * 线程约定：单实例单任务上下文（板端 = 104 服务在 netTask 消息循环内驱动，
 *   见 iec104_serv 胶水层）；非线程安全，禁止多任务共享一实例。
 * 失败语义：send_apdu 内**不得阻塞**；发送失败由胶水层断链（主站会重连），
@@ -1,24 +1,24 @@
 /*
 * 模块名称：IEC 60870-5-104 点表与数据源适配（实现）
 * 模块功能：实现 iec104_pts.h——YC/YX/YK/定值点表（ROM）、板端默认源
- *           （**L2 遥测快照**（卡 9）/ prot_elm / prot_set）、COV 比对（遥信变位 +
+ *           （**测频与遥测快照**（104 改读快照）/ prot_elm / prot_set）、COV 比对（遥信变位 +
 *           遥测死区 2 点确认 + 品质变化）。点表口径见 iec104_pts.h 文件头与
 *           设计文档 §3。
 * 线程约定：init/bind 建服务前；其余仅 104 服务任务上下文（快照非原子）。
 * 创建日期：2026-10-12（B4）
 * 修改记录：
- *   2026-10-25  DTU 项目组  卡 6（「数据可信」）：YC 死区由拟定码值域重定为
+ *   2026-10-25  DTU 项目组  下游常数按工程量重定（「数据可信」）：YC 死区由拟定码值域重定为
 *                           二次值工程量域（额定 0.5 % 规则），判据依据见
- *                           k_yc 表头注释；数值随卡 9 迁运行参数，本表将退化为
+ *                           k_yc 表头注释；数值随 104 改读快照迁运行参数，本表将退化为
 *                           ROM 默认载体。
- *   2026-10-25  DTU 项目组  卡 9/卡 11（「数据可信」，道D）：YC 板端源改读
- *                           L2 遥测快照（App/algo/meas.h，meas_get 无锁双区）；
+ *   2026-10-25  DTU 项目组  104 改读快照与频率点绑定（「数据可信」，道D）：YC 板端源改读
+ *                           测频与遥测快照（App/algo/meas.h，meas_get 无锁双区）；
 *                           削顶五路由快照品质 CLIPPED 驱动线上 IV（不再绑死 -1，
- *                           V0.2 消除双转换器无共同采样触发后零改动自动启用）；0x401d 绑频率源（卡 11）；
+ *                           V0.2 消除双转换器无共同采样触发后零改动自动启用）；0x401d 绑频率源（频率点绑定）；
 *                           死区改运行时副本 + set/get 入口；COV 遥测腿 = 死区
 *                           连续 2 点确认（板端按快照 seq 去重）+ 品质翻转即报。
 *                           单测 = test/host/iec104 TC-IEC104-025~028。
- *   卡 10  2026-10-25  DTU 项目组  死区真源收编 App/algo/run_par.c（本层 s_yc_db
+ *   运行参数段  2026-10-25  DTU 项目组  死区真源收编 App/algo/run_par.c（本层 s_yc_db
 *                           副本删除，set/get 转转发壳，壳保留清确认计数语义）；
 *                           定值读写路由 = run_par 表先、prot_set 后（0x8020~
 *                           0x8058 运行参数段 C_RD/C_SE，系数覆盖直通 adc_cal）。
@@ -36,36 +36,36 @@
 #include <string.h>

 #include "iec104_asdu.h"    /* QDS/DIQ 品质位常量 */
-#include "meas.h"         /* 板端源：遥测 = L2 遥测快照（卡 9；品质域位同源） */
-#include "run_par.h"        /* 卡 10：死区真源 + 运行参数段 104 读写路由 */
+#include "meas.h"         /* 板端源：遥测 = 测频与遥测快照（104 改读快照；品质域位同源） */
+#include "run_par.h"        /* 运行参数段：死区真源 + 104 读写路由 */
 #include "prot_elm.h"       /* 板端源：遥信 = 元件状态 */
 #include "prot_set.h"       /* 板端源：定值 + 闭锁 */
 #include "sys_log.h"        /* task-10：遥控记录（SYSLOG_YK）/ 操作记录（SYSLOG_OPER） */
 #include "adc_input.h"      /* adc_semantic_t（phasor 实例按语义绑定） */

 /* ---------------- YC 表（§1.5 点号 4011+；死区列 = ROM 默认值） ------------ */
-/* 源类型（「数据可信」卡 11：YC 表加 src 类型区分相量/频率） */
-#define PTS_SRC_MEAS  0u     /* L2 快照槽 sem（电气量，yc/qds 直读） */
+/* 源类型（「数据可信」频率点绑定：YC 表加 src 类型区分相量/频率） */
+#define PTS_SRC_MEAS  0u     /* 全周傅氏相量快照槽 sem（电气量，yc/qds 直读） */
 #define PTS_SRC_FREQ  1u     /* 快照频率（freq_valid 门 → IV） */

 typedef struct {
    uint32_t ioa;
    int8_t   sem;         /* 快照 yc 槽 = 语义通道（-1 = 非测量量点，当前仅频率） */
-    float    db_default;  /* 死区工厂默认（生效真源 = run_par [run_par] 段，卡 10） */
+    float    db_default;  /* 死区工厂默认（生效真源 = run_par [run_par] 段 = 运行参数段真源） */
    uint8_t  src;         /* PTS_SRC_* 源类型 */
 } pts_yc_def_t;

-/* 死区规则 = 额定二次值的 0.5 %（「数据可信」§2.3 表第 2 行建议规则，卡 6 采纳；
+/* 死区规则 = 额定二次值的 0.5 %（「数据可信」§2.3 表第 2 行建议规则，随下游常数按工程量重定采纳；
 * 额定基准 100 V / 1 A 与 App/algo/prot_set.c 头部同源，勿在此另立口径）：
 *   电压类 0.5 % × 100 V = 0.5 V   电流类 0.5 % × 1 A = 0.005 A
 * 频率点不适用"额定百分比"（额定附近 0.5 Hz 与旧值同量级，维持 0.5 并随
- * 卡 10 运行参数段可调）。自卡 9 起本表**只作工厂默认载体**：生效死区 =
- * App/algo/run_par.c 的 [run_par] 引擎副本（卡 10 真源收编，本层不再存副本）；削顶五路不再 sem=-1 绑死，而是绑快照槽、由品质 CLIPPED
+ * 运行参数段可调）。自 104 改读快照起本表**只作工厂默认载体**：生效死区 =
+ * App/algo/run_par.c 的 [run_par] 引擎副本（运行参数段真源收编，本层不再存副本）；削顶五路不再 sem=-1 绑死，而是绑快照槽、由品质 CLIPPED
 * 驱动线上 IV——V0.2 削顶消失后点位零改动自动启用（docs/任务规划/
 * 数据可信.md §10 的「双转换器无共同采样触发」行）。
- * ⚠ 过渡期（eng=0 引脚电压域，卡 12 标定前）：上送值本身非二次值，死区
+ * ⚠ 过渡期（eng=0 引脚电压域，两点标定完成前）：上送值本身非二次值，死区
 * 数字按本域偏保守（迟报不漏报）；标定落地后复核（「数据可信」§2.3 表
- * 第 2 行）。判定 = 死区连续 2 点确认（卡 9），见 iec104_pts.h COV 说明。 */
+ * 第 2 行）。判定 = 死区连续 2 点确认（104 改读快照），见 iec104_pts.h COV 说明。 */
 static const pts_yc_def_t k_yc[] = {
    { 0x4011u, (int8_t)ADC_SEM_UA,  0.5f, PTS_SRC_MEAS },  /* 1Ua：0.5 % × 100 V */
    { 0x4012u, (int8_t)ADC_SEM_UB,  0.5f, PTS_SRC_MEAS },  /* 1Ub：削顶 → 品质驱动 IV */
@@ -75,12 +75,12 @@ static const pts_yc_def_t k_yc[] = {
    { 0x4016u, (int8_t)ADC_SEM_IB, 0.005f, PTS_SRC_MEAS }, /* 1Ib：削顶 → 品质驱动 IV */
    { 0x4017u, (int8_t)ADC_SEM_IC, 0.005f, PTS_SRC_MEAS }, /* 1Ic：同上 */
    { 0x4018u, (int8_t)ADC_SEM_IN, 0.005f, PTS_SRC_MEAS }, /* 1I0：同上 */
-    { 0x401Du, -1,                  0.5f, PTS_SRC_FREQ },  /* 1f：卡 11 绑频率源，
+    { 0x401Du, -1,                  0.5f, PTS_SRC_FREQ },  /* 1f：频率点绑定——绑频率源，
                                                            * freq_valid=0 → IV */
 };
 #define YC_N  ((uint8_t)(sizeof(k_yc) / sizeof(k_yc[0])))

-/* ===== 遥测 COV 运行时状态（卡 9；仅 iec104Task 上下文访问，无并发） =====
+/* ===== 遥测 COV 运行时状态（104 改读快照；仅 iec104Task 上下文访问，无并发） =====
 * 判据链：新测量点 → |v − 上次上送值| > 死区？→ 连续 2 点确认 → 置变化位。
 * 基准 = **上次上送值**（非上次读值——否则慢漂移永不出死区，参考系统同款）；
 * 品质（线上 qds）翻转 = 事件：不参与 2 点计数、当拍直报。 */
@@ -124,7 +124,7 @@ static uint8_t  s_yx_snap_ok;
 /*
 * 函数功能：初始化点表模块（死区装 ROM 默认、清 COV/快照状态、恢复默认源）
 * 限定条件：内核启动前或 104 服务启动前，调一次
- * 函数说明：卡 9 起不再扫 phasor 实例（数据源 = 快照，槽位 = 语义通道，编译期
+ * 函数说明：104 改读快照起不再扫 phasor 实例（数据源 = 快照，槽位 = 语义通道，编译期
 *          直接可定）；重复调用 = 全状态复位（单测 reset 依赖此语义）。
 */
 void iec104_pts_init(void) {
@@ -172,12 +172,12 @@ uint32_t iec104_pts_yc_ioa(uint8_t idx) {
 }

 /*
- * 函数功能：品质域位映射（uint16 meas 域 → uint8 线上 QDS，卡 9）
+ * 函数功能：品质域位映射（uint16 meas 域 → uint8 线上 QDS，104 改读快照）
 * 入口参数：q16 - 源侧品质（低字节与线上同值；高字节为 MEAS_QDS_CLIPPED 域内位）
 * 返 回 值：线上 QDS 字节  uint8_t
 * 函数说明：CLIPPED（硬件削顶，104 无对应位）映射为 IV——「削顶通道 104 恒
- *          IV」口径（docs/任务规划/数据可信.md §8 风险表末行）改由快照品质
- *          驱动，不再靠点表绑死 -1；OV/NT/IV 透传，其余高位丢弃。
+ *          IV」口径（docs/任务规划/数据可信.md §8 风险表「削顶通道被当成可测」
+ *          行）改由快照品质驱动，不再靠点表绑死 -1；OV/NT/IV 透传，其余高位丢弃。
 */
 static uint8_t s_q_map(uint16_t q16) {
    uint8_t w = (uint8_t)(q16 & (uint16_t)(IEC104_QDS_OV | IEC104_QDS_NT
@@ -195,7 +195,7 @@ static uint8_t s_q_map(uint16_t q16) {
 * 返 回 值：0 有效；-1 IV（含 CLIPPED 映射）；-2 NT（未就绪）  int
 * 函数说明：ex 源在场 → 品质由源给（板端 = 快照槽位透传）；否则退 legacy
 *          yc_read，品质从返回值推导（-1→IV / -2→NT / 0→无位）——旧注入源
- *          行为与卡 9 前**完全一致**（单测假源零改动）。判定顺序 IV > NT：
+ *          行为与 104 改读快照前**完全一致**（单测假源零改动）。判定顺序 IV > NT：
 *          开机首帧 qds=IV|NT 按无效处理（NT 只留给纯暂态）。任何无效 →
 *          信息体清零（线上口径：主站只信品质）。
 */
@@ -245,14 +245,14 @@ int iec104_pts_yc_read(uint8_t idx, float *v, uint8_t *qds) {
 }

 /*
- * 函数功能：写死区（卡 9 API 壳，转发 run_par 真源 + 清本层确认计数）
+ * 函数功能：写死区（104 改读快照的 API 壳，转发 run_par 真源 + 清本层确认计数）
 * 入口参数：idx - YC 表下标  db - 工程量绝对死区（≥0，分档上限见 run_par）
 * 返 回 值：0 成功；-1 越界/负值/NaN/越程（run_par 副本不动）  int
 * 限定条件：**iec104Task 上下文**（run_par 副本写 = 引擎对齐 int32 单字，
 *          104 执行段之外调用需自行避免与 104 写并发）
 * 函数说明：成功时清零该点待确认计数——跨死区档位不保留半截确认序列；
 *          不隐式重建基线（上送基准延续，新死区即刻生效）。落盘由 run_par
- *          脏标志 + SYS_EVT_RUN_PAR_SAVE 走 defaultTask（卡 10 持久化链）。
+ *          脏标志 + SYS_EVT_RUN_PAR_SAVE 走 defaultTask（运行参数段持久化链）。
 */
 int iec104_pts_yc_set_deadband(uint8_t idx, float db) {
    if (idx >= YC_N) {
@@ -348,7 +348,7 @@ void iec104_pts_cov_check(iec104_pts_cov_t *cov) {
        s_yx_snap_ok = 1u;
    }

-    /* YC（卡 9）：测点推进 = 板端源按快照换帧（100 ms poll vs 200 ms 快照，
+    /* YC（104 改读快照）：测点推进 = 板端源按快照换帧（100 ms poll vs 200 ms 快照，
     * 不去重则同一帧计两次 → "连续 2 点确认"退化成"连续 2 次轮询"，单帧
     * 噪声即可被确认，抗噪语义失效）；注入源 = 每次调用一测点。
     * 判定 = 死区连续 2 点确认 + 品质翻转直报（口径全文 → iec104_pts.h）。 */
@@ -383,7 +383,7 @@ void iec104_pts_cov_check(iec104_pts_cov_t *cov) {
                    continue;
                }
                if (q != s_yc_repq[i]) {
-                    /* 品质翻转 = 事件直报（含 0x401d 的 IV 进出，卡 11） */
+                    /* 品质翻转 = 事件直报（含 0x401d 的 IV 进出，频率点绑定） */
                    local.yc_changed |= (uint16_t)(1u << i);
                    s_yc_repq[i]      = q;
                    s_yc_cnf[i]       = 0u;
@@ -458,15 +458,15 @@ int iec104_pts_set_write(uint32_t addr, float v, uint8_t select) {
 /* ============================ 板端默认源 ================================= */

 /*
- * 函数功能：板端默认源 - 遥测 = L2 遥测快照直读（「数据可信」卡 9/卡 11）
+ * 函数功能：板端默认源 - 遥测 = 测频与遥测快照直读（「数据可信」104 改读快照与频率点绑定）
 * 入口参数：idx - YC 表下标  out/qds - 值 + uint16 域品质（MEAS_QDS_*）
 * 返 回 值：0 / -1 越界或频率未新鲜（IV）/ -2 快照从未发布（NT）  int
 * 限定条件：iec104Task 上下文（meas_get 为双区无锁读，App/algo/meas.h）
 * 函数说明：**不做任何本地判断**——电气路值/品质整体透传快照槽（削顶路快照
 *          已置 CLIPPED，s_q_map 映上线 IV；开机首帧 IV|NT 由 s_yc_point 按
- *          IV 处理），"新不新、能不能信"全在发布侧一处决定（卡 8 设计意图，
+ *          IV 处理），"新不新、能不能信"全在发布侧一处决定（遥测快照发布的设计意图，
 *          两处判断必打架）。频率路（PTS_SRC_FREQ）：snap.freq_valid==0 →
- *          IV（卡 11 DoD 原句）；有效时值 = snap.freq_hz，与 freq_get() 同源。
+ *          IV（频率点绑定 DoD 原句）；有效时值 = snap.freq_hz，与 freq_get() 同源。
 */
 static int s_src_yc_read_ex(uint8_t idx, float *out, uint16_t *qds) {
    meas_snap_t snap;
@@ -633,7 +633,7 @@ static int s_src_set_read(uint32_t addr, float *out) {
        return -1;
    }
    if (run_par_104_read(addr, out) == 0) {
-        return 0;                   /* 运行参数段命中（卡 10） */
+        return 0;                   /* 运行参数段命中 */
    }
    for (i = 0u; i < (uint32_t)PS_ID_COUNT; i++) {
        if ((g_prot_set_meta[i].comm_addr != 0u)
@@ -6,7 +6,7 @@
 *           （asdu+pts+link）可离线跑（分层约束：协议解析与硬件 I/O 分离）。
 * 点表口径（docs/算法/继电保护功能复现规划.md §1.5，验收 = 省电科院点表）：
 *   - YC：IOA 0x4011~0x4018 + 0x401d（频率），短浮点、系数 1；数据源 =
- *     L2 遥测快照（App/algo/meas.h，「数据可信」卡 9/11）：电气 8 路绑快照槽，
+ *     测频与遥测快照（App/algo/meas.h，「数据可信」104 改读快照与频率点绑定）：电气 8 路绑快照槽，
 *     有效性由快照品质驱动——V0.1 削顶路（docs/算法/继电保护功能复现规划.md
 *     §1.6）快照置 CLIPPED → 本层映射为线上 IV（V0.2 后自动启用，绑定零
 *     改动，见 docs/任务规划/数据可信.md §10「双转换器无共同采样触发」行）；0x401d 绑频率源，
@@ -25,11 +25,11 @@
 * 线程约定：init/bind 内核启动前或建服务前；cov_check/read 仅 104 服务任务上下文。
 * 创建日期：2026-10-12（B4）
 * 修改记录：
- *   2026-10-25  DTU 项目组  卡 9/卡 11（「数据可信」，道D）：YC 数据源 = L2 遥测
+ *   2026-10-25  DTU 项目组  104 改读快照与频率点绑定（「数据可信」，道D）：YC 数据源 = 全周傅氏相量遥测
 *                           快照（削顶路由品质驱动 IV）；死区改运行时副本 +
 *                           set/get 入口；COV 遥测腿 = 死区 2 点确认（seq 去重）
 *                           + 品质变化即报；0x401d 绑频率源（freq_valid → IV）。
- *   2026-10-25  DTU 项目组  卡 10：死区真源迁 run_par（[run_par] cfg 段 +
+ *   2026-10-25  DTU 项目组  运行参数段：死区真源迁 run_par（[run_par] cfg 段 +
 *                           0x8020~0x8058 读写映射；本层 set/get 为转发壳）。
 */
 #ifndef IEC104_PTS_H
@@ -52,7 +52,7 @@ typedef struct {
    int      (*set_read)(uint32_t addr, float *out);
    /* 定值写：select=1 预置校验（范围）/ 0 执行写入。返回 0 / -1 越界或未知 */
    int      (*set_write)(uint32_t addr, float v, uint8_t select);
-    /* 遥测读（带品质，卡 9 追加于表尾——旧源 NULL = 走 yc_read 退路，品质由
+    /* 遥测读（带品质，104 改读快照时追加于表尾——旧源 NULL = 走 yc_read 退路，品质由
     * 返回值推导：-1 → IV、-2 → NT、0 → 无位，行为与旧源完全一致）。
     * qds = uint16 域位（App/algo/meas.h MEAS_QDS_*：低字节 = 线上 QDS 同值，
     * 高字节 CLIPPED 由本层映射线上 IV）；返回 0 / -1 IV / -2 NT */
@@ -83,11 +83,11 @@ uint32_t iec104_pts_yc_ioa(uint8_t idx);
 /* 读 YC：v 有效值（无效时为 0）；qds 输出线上品质位（IV/NT/OV，CLIPPED 已映射
 * 为 IV）。返回 0/无效-1（NT 亦无效，品质位区分） */
 int      iec104_pts_yc_read(uint8_t idx, float *v, uint8_t *qds);
-/* 死区写（卡 9 API；卡 10 起 = 转发 App/algo/run_par.c 真源 + 清本层确认计数）：
+/* 死区写（104 改读快照 API；运行参数段起 = 转发 App/algo/run_par.c 真源 + 清本层确认计数）：
 * db = 工程量绝对值 ≥0（电压 50 V / 电流 1 A / 频率 5 Hz 分档上限）；越界/负值/
 * NaN → -1 且真源不动；成功时清零该点待确认计数（跨档位不残留半截确认——此壳
 * 行为有单测钉住）。仅 104 服务任务上下文调用。落盘 = run_par 脏 → 事件 →
- * defaultTask（卡 10 持久化链，docs/子系统设计/IEC104上行设计说明.md §3.4）。 */
+ * defaultTask（运行参数段持久化链，docs/子系统设计/IEC104上行设计说明.md §3.4）。 */
 int      iec104_pts_yc_set_deadband(uint8_t idx, float db);
 /* 读当前生效死区（越界 idx 返 0） */
 float    iec104_pts_yc_deadband(uint8_t idx);
@@ -104,12 +104,12 @@ void     iec104_pts_yx_read(uint8_t idx, uint8_t *out);
 * 函数功能：读全表并与上次比对（遥信变位 + 遥测死区 2 点确认 + 品质变化），
 *          输出变化集
 * 入口参数：cov - 输出（可为 NULL = 只刷快照不取变化）
- * 函数说明：遥测判据（「数据可信」卡 9，对标参考系统 CalfYcMea 死区 2 点确认，
+ * 函数说明：遥测判据（「数据可信」104 改读快照，对标参考系统 CalfYcMea 死区 2 点确认，
 *          短板评测口径）：**连续 2 个新测量点** |v - 上次上送值| > 死区才置变化位
 *          （单点尖峰不确认——噪声回摆即撤销候选）；品质位（线上 qds）相对上次
 *          上送值翻转 → 当拍直接置位（不等 2 点，有效性变化必须即时可见，
 *          含 0x401d 的 IV 进出）。死区 = 运行时副本（ROM 默认 = 点表列，
- *          iec104_pts_yc_set_deadband() 覆盖——卡 10 运行参数段的接线点）。
+ *          iec104_pts_yc_set_deadband() 覆盖——运行参数段的接线点）。
 *          测量点定义：板端默认源 = **快照换帧**（meas seq 前进；100 ms poll 对
 *          200 ms 快照，同一帧重复比对会计数两次 → seq 去重是确认语义成立的
 *          前提）；注入源（单测假源）= 每次调用一测点。首次读到有效值只建基线
@@ -10,6 +10,11 @@
 *   v1.1  2026-08-28  王建锋  改为 TCP Server，迁入独立任务 timeSyncTask，
 *                           所有 socket 操作经 net_socket 线程安全 API 走消息队列，
 *                           netTask 仅负责 net_poll/net_process_messages，多任务并发安全
+ *   v1.3  2026-10-27  DTU 项目组  道G task-50：对时**成功应用**后投一条 quiet
+ *                           操作记录（"clock set by 8888"）——task-49 盘点盘出
+ *                           "104 对时留痕、本端口不留"的同类不对称，Lead 批准补齐；
+ *                           被拒不落痕；epoch 时标语义未裁定，本改动不碰、不补
+ *                           任何时区补偿。
 *   v1.2  2026-10-02  王建锋  第 8b 轮消抖：等待片长 200ms→50ms，并把各处长
 *                           等待（500/2000/200ms）统一走 time_sync_delay_fed()
 *                           按 ≤50ms 分片、每片喂心跳——消除"心跳滑出两个连续
@@ -21,6 +26,7 @@
 #include "net_socket.h"
 #include "sys_clock.h"
 #include "sys_events.h"
+#include "sys_log.h"
 #include "task_watchdog.h"

 /* 深调用链模块（timeSyncTask 栈仅 2048 B，本任务链 = 建监听 → net_bind → CH395F）：
@@ -33,11 +39,11 @@
 #define TIME_SYNC_PORT   8888

 /*
- * 头阻塞修复 + L3 pending 化（timeSync 侧；lftpd 侧见 lftpd_inet.c）：
+ * 头阻塞修复 + 挂起请求（pending）化（timeSync 侧；lftpd 侧见 lftpd_inet.c）：
 * 旧实现用单次 30s 阻塞 net_recv（默认 NET_RECV_TIMEOUT_MS）等时间包——等待期间
 * netTask（全部 socket 操作的唯一执行者）被独占，其余任务的网络操作（远端显示 /
 * FTP）整体停摆（历史审计遗留问题）。
- * 2026-09-22 先落地分片有界读（5ms 片），同日 L3 pending 化后改为"挂起请求"：
+ * 2026-09-22 先落地分片有界读（5ms 片），同日 pending 化后改为"挂起请求"：
 * 每次等待 = 一次挂起登记（netTask 零占用，完成按主循环节拍检查），调用方
 * 单次超时 = 剩余总预算（总等待 ≤ TIME_SYNC_TOTAL_BUDGET_MS，语义与旧 30s
 * 一致）；等待期间调用方在自己上下文睡任务通知，旧分片协议（片长/片间让出）退役。
@@ -136,7 +142,7 @@ static void time_sync_handle_conn(int conn_sock) {
    TickType_t t0 = xTaskGetTickCount();

    while (got < (int)sizeof(buf)) {
-        /* 单次预算 = 剩余总预算（L3 pending：等待期 netTask 零占用，调用方
+        /* 单次预算 = 剩余总预算（pending：等待期 netTask 零占用，调用方
         * 在自己上下文睡任务通知，旧片间 vTaskDelay(1) 让出退役）
         * ⚠ 看门狗约束：本任务在 required_mask 内，而单次 net_recv_to 可睡满
         * 30s 预算 —— 等待期必须周期性喂心跳，否则"对端连上但不发时间包"这种
@@ -176,7 +182,17 @@ static void time_sync_handle_conn(int conn_sock) {
                             ((uint32_t)buf[5] << 16) |
                             ((uint32_t)buf[6] << 8)  |
                             ((uint32_t)buf[7]);
-            sys_clock_set_unix(epoch);
+            if (sys_clock_set_unix(epoch) == 0) {
+                /* 操作留痕（道G task-50）：对时改的是装置时钟——与 104 的
+                 * "clock set by 104"（App/task/iec104_serv.c 对时处）同类同口径，
+                 * 补齐 task-49 盘出的不对称。**被拒不投**：失败不得记成"时钟被改过"；
+                 * 连续两次成功各投一条——每次对时是独立事件，无合并语义。
+                 * quiet 口：本任务栈 2048 B（见本文件 DBG_LINE_BUF_MAX 段），
+                 * syslog_post 的两个满态留痕分支各内联约 216 B 行缓冲，不选它。
+                 * ⚠ 记录里的时标语义（本端口写钟面、104 写 UTC 的 8 小时差）
+                 *   未裁定——留痕按现有通道原样落，不做任何时区补偿。 */
+                syslog_post_quiet(SYSLOG_OPER, "clock set by 8888");
+            }
            DBG_INFO("time_sync: wall clock updated (epoch=%lu)", (unsigned long)epoch);
        }
    } else {
@@ -1,7 +1,7 @@
 /*
 * 模块名称：ADC Sampling Task
- * 模块功能：ADC 采集消费 + L2 相量计算——TPAFE5160 快照 + STM32 ADC1 DMA 乒乓帧消费
- *          （经 L1 层 App/algo/adc_input.c 按语义取数）→ 压入采样环
+ * 模块功能：ADC 采集消费 + 全周傅氏相量计算——TPAFE5160 快照 + STM32 ADC1 DMA 乒乓帧消费
+ *          （经 语义取数与有效性层 App/algo/adc_input.c 按语义取数）→ 压入采样环
 *          （App/algo/sample_ring.c）→ 全周傅氏相量重算（App/algo/phasor.c）
 *          + 帧统计（节拍由 TIM3 硬件定时器提供）
 * 状态说明：**B1 已落地（2026-10-10）**——本任务从空桩转为真实消费者：
@@ -15,9 +15,10 @@
 *          消除 0~1 ms 的 tick 量化相位抖动与"超拍永久落后 → 空转"风险；本任务优先级
 *          同步由 Normal 提到 **AboveNormal**（唤醒即抢占）。详见
 *          docs/子系统设计/ADC采样节拍设计说明.md §6。
- *          **L1 采集层**：取数改走 App/algo/adc_input.c——
+ *          **语义取数与有效性层**：取数改走 App/algo/adc_input.c——
 *          本任务每拍调 adc_input_poll()（TPAFE 快照 + STM32 ADC1 9 通道扫描），
- *          经 adc_input_raw() **按语义**读通道（L1-3/L1-4），不再直接触碰驱动缓冲。
+ *          经 adc_input_raw() **按语义**读通道（STM32 ADC1 启动与扫描 / 通道语义映射），不再直接触碰驱动缓冲。
+ *（保护功能清单见 docs/算法/继电保护功能复现规划.md）
 *          V0.1 上只有 TPAFE 三路（UA/UN/IA）测量有效；本任务只取数，不做保护运算。
 * 接入前必读：取数只用 adc_input_raw() / tpafe5160_snapshot()（临界区原子快照，
 *          仅任务上下文；旧的 get_buf/data_ready/clear_ready 已删除）；接消费者前的
@@ -37,18 +38,18 @@
 *                             就绪前挂起上报，就绪后补报最近一帧。
 *   v2.2  2026-10-10  王建锋  采样节拍改由 TIM3 更新中断（1 kHz）硬件触发；本任务
 *                             删除自行触发，退化为纯消费者（见文件头"采样节拍"）。
- *   v2.3  2026-10-10  王建锋  L1-3/L1-4：取数改走 App/algo/adc_input.c（语义映射 +
+ *   v2.3  2026-10-10  王建锋  STM32 ADC1 启动与扫描 / 通道语义映射：取数改走 App/algo/adc_input.c（语义映射 +
 *                             STM32 ADC1 9 通道扫描）；首帧日志补全 8 路电气量 + 温度，
 *                             心跳日志增 adc1_rc / adc1_err 观测 STM32 侧健康度。
- *   v2.4  2026-10-10  王建锋  L2：接入相量层——每拍把 9 路语义值压入采样环
+ *   v2.4  2026-10-10  王建锋  全周傅氏相量：接入相量层——每拍把 9 路语义值压入采样环
 *                             （sample_ring）并重算全部相量实例（phasor_run）；
 *                             攒满一周波后**首拍即落一次相量日志**（开机证据，不等
 *                             10 s 心跳），心跳日志增 ring / skip 计数与各实例相量
 *                             （Re/Im/有效值，×0.1 定点打印，因 MicroLIB 的 snprintf
 *                             无 %f）。
- *                             ⚠ L1-5 通道标定未实现（缺标准源）→ 暂以**原始码值**
+ *                             ⚠ 通道标定（一次系数 + 零漂）未实现（缺标准源）→ 暂以**原始码值**
 *                             充作工程量（系数 = 1），故相量读数只证明**链路通**，
- *                             不可作幅值精度判据（同 L1-3 的替代口径）。
+ *                             不可作幅值精度判据（同 STM32 ADC1 启动与扫描 的替代口径）。
 *   v2.5  2026-10-10  王建锋  常开耗时测量埋点：单拍加探针
 *                             （task_prof ADC_BEAT），用于判定本任务是否超拍
 *                             （名义节拍 1 ms = 168000 周期）而挤占低优先级任务
@@ -70,7 +71,7 @@
 *                             §3.2）；STM32 侧改 DMA 双缓冲
 *                             消费，adc_input_poll() 不再忙等；心跳日志增
 *                             adc1_seq / adc1_hw（adc1_err 语义改为"本拍无新帧"）
- *   v2.9  2026-10-11  王建锋  L1-6 采样有效性校验：每拍调 adc_health_check()
+ *   v2.9  2026-10-11  王建锋  采样有效性校验：每拍调 adc_health_check()
 *                             （App/algo/adc_health.c，纯逻辑判定：静默/丢帧/
 *                             单调性/错误计数增量）——严重事件与故障电平上升沿
 *                             打 DBG_ERROR + 每类每次开机一次 SYSLOG_SELFTEST；
@@ -84,37 +85,55 @@
 *                             者；该入口同时不再打日志——它落在本任务静态最坏链上，
 *                             每条 DBG_* 约 216 B 栈，而这一行毫无诊断价值（本任务
 *                             存活由首帧日志与 TASK_WD_ADC 心跳证明）
- *   v3.1  2026-10-25  DTU 项目组  L1.5 折算 + L5-2 贴轨观测（「数据可信」卡 2，道A）：
+ *   v3.1  2026-10-25  DTU 项目组  标定折算折算 + 采样通道自检 贴轨观测（「数据可信」标定折算落地，道A）：
 *                             frame[s] 由 (float)code 改 adc_cal_apply()——工程量 =
- *                             (code+b)×k，现口径 = ADC 引脚电压 V（eng=0，卡 1 冻结的
+ *                             (code+b)×k，现口径 = ADC 引脚电压 V（eng=0，量程口径冻结的
 *                             ROM 系数，docs/硬件平台/ADC通道映射说明.md §7.1）；同拍
- *                             经 adc_health_rail_watch() 逐通道贴轨观察（L5-2 残余，
+ *                             经 adc_health_rail_watch() 逐通道贴轨观察（采样通道自检 残余，
 *                             门限 adc_cal_rail_ths，码值域与标定正交），锁存边沿 →
 *                             DBG_ERROR + 每开机一次 SYSLOG；心跳增 cal: 行（mV 定点
 *                             + valid/clipped 位图 + rail 锁存），台架注入口径见该行判读
- *   v3.2  2026-10-25  DTU 项目组  L2 遥测快照发布（「数据可信」卡 8，道D，M5）：新模块
+ *   v3.2  2026-10-25  DTU 项目组  测频与遥测快照发布（「数据可信」这一项，道D，M5）：新模块
 *                             App/algo/meas.c——本任务为唯一发布者，新帧拍内
 *                             freq_run() 之后按 200 ms **tick 经过**分频调
 *                             meas_tick()（全仓调用点 = 1，评审判据）；品质注入源 =
 *                             adc_cal_flags() 削顶位图，频率 = 同拍 freq 读数；心跳新增
 *                             meas: 行（seq/v/ua·un·ia_mv/f/fv），读数比对类判据待台架实测
+ *   v3.3  2026-10-27  DTU 项目组  已知电压注入验证台架读出口：心跳新增 adc: 行——连续输出 9 路
+ *                             **原始码值**（与 first: 行同序同格式）。动因 = 注入验证
+ *                             原本只能靠"改电压 + 复位 + 抓一次 first:"，8 个通道 × 3 个
+ *                             注入点要复位二十余次；改为每 10 s 一行后可全程免复位。
+ *                             不并进 cal: 行是因为 9 个码值会把该行推到 168 字符、
+ *                             撞 DBG_CON_LINE_MAX(192) 的静默截断边界（见该行注释）。
+ *                             无新增跨任务状态、无新增外设访问，栈 +36 B（局部码值数组）
+ *   v3.4  2026-10-29  DTU 项目组  故障录波数据面接线（task-2）：新增 2c——每拍把 8 路
+ *                             语义原码压进 wave_ring 并 tick 推进；EVT_SEALED 那一拍现取
+ *                             折算/有效性/墙钟事实组 wave_seal_cal_t 并 latch_meta 恰好
+ *                             一次（握手次序照 App/algo/wave_ring.h 头注唯一合法次序）；
+ *                             心跳末尾加 §9 唯一周期行 wave:（字段逐字，取数
+ *                             wave_ring_get_stat）；新增 2d——bench 定周期自抓，只在
+ *                             DTU_BENCH 且 WAVE_BENCH_AUTOCAP 非 0 的双层编译门内存在，
+ *                             默认关闭 + 5 分钟时长上限 + 启动一次性告警（§10 红线）；
+ *                             adc_task_init 内接 wave_ring_init（init 禁日志约束不破）
 */

 #include "adc_task.h"
 #include "cmsis_os.h"
 #include "task_handles.h"   /* adcTaskHandle（原为本文件局部 extern） */
-#include "adc_input.h"      /* L1 采集层：adc_input_poll()/adc_input_raw()（按语义取数） */
-#include "sample_ring.h"    /* L2 输入：sample_ring_push_frame()（采样环缓冲） */
-#include "phasor.h"         /* L2 相量层：phasor_run()/phasor_get()（全周傅氏） */
-#include "freq.h"           /* L2 派生量：freq_run()/freq_get()（测频，B8） */
-#include "adc_health.h"     /* L1-6：采样有效性校验（静默/丢帧/单调性/错误增量/贴轨） */
-#include "adc_cal.h"        /* L1.5：通道标定折算（「数据可信」卡 2；flags 供 cal 心跳行） */
-#include "meas.h"           /* L2 发布侧：遥测快照 meas_tick()（「数据可信」卡 8，道D） */
+#include "adc_input.h"      /* 语义取数与有效性层：adc_input_poll()/adc_input_raw()（按语义取数） */
+#include "sample_ring.h"    /* 全周傅氏相量输入：sample_ring_push_frame()（采样环缓冲） */
+#include "phasor.h"         /* 全周傅氏相量层：phasor_run()/phasor_get()（全周傅氏） */
+#include "freq.h"           /* 全周傅氏相量的派生量：freq_run()/freq_get()（测频，B8） */
+#include "adc_health.h"     /* 采样有效性校验（静默/丢帧/单调性/错误增量/贴轨） */
+#include "adc_cal.h"        /* 标定折算：通道标定折算（「数据可信」标定折算落地；flags 供 cal 心跳行） */
+#include "meas.h"           /* 全周傅氏相量发布侧：遥测快照 meas_tick()（「数据可信」遥测快照发布，道D） */
 #include "tpafe5160.h"
 #include "task_watchdog.h"
 #include "console_log.h"
 #include "sys_log.h"        /* SYSLOG_SELFTEST：采样故障留痕（仅故障才写） */
 #include "task_prof.h"      /* 常开耗时探针：单拍耗时 */
+#include "wave_ring.h"      /* 故障录波环（task-2 数据面接线）：push/tick/latch_meta/get_stat */
+#include "sys_clock.h"      /* 封存交棒的 wall 字段：sys_clock_get() epoch 秒（UINT32_MAX=未对时，写 0） */

 #define DBG_TAG "[ADC_TASK]"
 #include "dbg_log.h"
@@ -124,31 +143,56 @@
 *  消费节拍改由 TIM3 ISR 置位 ADC_WAKE_FLAG 提供，与生产同源，不再自定周期） */
 #define ADC_TASK_REPORT_MS      10000U

+/* bench 定周期自抓（§10 红线「默认关闭 + 有时长上限 + 启动打一次告警」的落点）：
+ * WAVE_BENCH_AUTOCAP 默认 0——产品档连外层 DTU_BENCH 都没有，双层编译门保证
+ * 产品镜像里 2d 段整段不存在；台架确实要定周期刷段时才本地改 1 重编译，
+ * 用完立刻回 0（每 2 s 一段 = 每 5 分钟一轮 NAND 写，长挂白烧写次数，dhara
+ * 坏块记账还是持久代价）。宏形态照 App/algo/adc_cal.c 的 adc_cal_prot_blocked()：
+ * 联合条件放 #if，未定义宏恒为假，不把 cppcheck 引到旁路上。
+ * 周期/上限取自 §10 的算式：2 s/段、300 s 自动停。 */
+#define WAVE_BENCH_AUTOCAP      0
+#define WAVE_BENCH_PERIOD_MS    2000u
+#define WAVE_BENCH_MAX_MS       300000u
+
 /* 统计：已消费帧数 / 无新帧次数（首拍必为无新帧，之后应稳定为 0 增量）。
- * 原始码值缓冲由 L1 层 App/algo/adc_input.c 持有（消费侧按语义取数，不写死下标） */
+ * 原始码值缓冲由 语义取数与有效性层 App/algo/adc_input.c 持有（消费侧按语义取数，不写死下标） */
 static uint32_t s_frames_consumed;
 static uint32_t s_frames_idle;
 /* 因通道尚未首次成功而**整拍跳过入环**的次数（不向相量窗注入 0 点） */
 static uint32_t s_frames_skip;

-/* L1-6 告警编排状态：
+/* 采样有效性校验 告警编排状态：
 *   s_health_prev  - 上次电平故障位（判上升/下降沿，避免每拍重复告警）
 *   s_health_logged- 已写 SYSLOG_SELFTEST 的位（每类每次开机只留痕一次，
 *                    防持续故障刷屏把 32KB selftest.log 写满） */
 static uint32_t s_health_prev;
 static uint32_t s_health_logged;

-/* L5-2 贴轨编排状态（锁存本体在 adc_health 内，这里只留编排层视角）：
+/* 采样通道自检 贴轨编排状态（锁存本体在 adc_health 内，这里只留编排层视角）：
 *   s_rail_edge_latched - 本开机以来出现过锁存边沿的通道位图（心跳 cal: 行展示）
 *   s_rail_syslogged    - SYSLOG 留痕只写一次的闸门（init 重置） */
 static uint32_t s_rail_edge_latched;
 static uint8_t  s_rail_syslogged;

-/* 遥测快照发布闸门（「数据可信」卡 8）：上次发布拍时基。分频用 **tick 经过**
+/* 遥测快照发布闸门（「数据可信」这一项）：上次发布拍时基。分频用 **tick 经过**
 * 对比 MEAS_PERIOD_MS，非拍计数——idle/skip 拍会把拍计数口径拉得超过名义
 * 200 ms（与 v2.6 修"重复采样污染 DFT 窗"同族误差，勿"优化"成拍计数） */
 static uint32_t s_meas_ms;

+/* 故障录波环接线状态（task-2；状态机与计数全在 App/algo/wave_ring.c，这里只搬运）：
+ *   s_wave_codes - 本拍 8 路语义原码（文件级 static，不上单拍的栈——本任务静态
+ *                  最坏链余量按 1024 B ISR 底线核）
+ *   s_wave_cal   - EVT_SEALED 拍的交棒结构（同理不放局部：整块 ~160 B） */
+static int16_t         s_wave_codes[WAVE_RING_CH];
+static wave_seal_cal_t s_wave_cal;
+#if defined(DTU_BENCH) && (WAVE_BENCH_AUTOCAP != 0)
+/* bench 自抓编排：on = 已过写者就绪门开始跑；off = 到时自动停（init 重置） */
+static uint8_t  s_wave_bench_on;
+static uint8_t  s_wave_bench_off;
+static uint32_t s_wave_bench_t0;
+static uint32_t s_wave_bench_next;
+#endif
+

 /* 消费者就绪门：由 adcTask 自己在进入等待前置 1；单写者 = 本任务，ISR 只读。
 * ⚠ 为什么必须有这道门：TIM3 在 app_main_init()（Src/main.c:140）里就
@@ -186,7 +230,7 @@ void adc_tick_irq_notify(void) {
 * 限定条件：仅任务上下文；调用方须保证 dbg_console_writer_ready() 为真
 * 函数说明：MicroLIB 的 snprintf **不支持 %f** → 以 ×0.1 定点整数打印
 *          （打印值 = 实际值 × 10，分辨率 0.1）。逐实例数据驱动输出，
- *          实例表加行即自动覆盖。输入自 v3.1 起为 L1.5 折算后的工程量
+ *          实例表加行即自动覆盖。输入自 v3.1 起为 标定折算折算后的工程量
 *          （现口径 = ADC 引脚电压 V，见 cal: 心跳行与文件头 v3.1 记录）；
 *          二次值语义仅在 adc_cal_flags() 出 VALID 后成立。
 */
@@ -206,7 +250,7 @@ static void log_phasors(const char *tag) {
        }
    }

-    /* 测频行（B8，L3-5 测量侧台架可见性）：同样 x0.01 定点（分辨率 0.01 Hz）。
+    /* 测频行（B8，过频 / 低频 测量侧台架可见性）：同样 x0.01 定点（分辨率 0.01 Hz）。
     * valid=0 = 未启动收敛或幅值门失效（浮空输入 rms≈0），此时 f 为保持值
     * （从未收敛则 0）——判读：正常带波形应 valid=1 且 f≈5000。 */
    {
@@ -219,7 +263,7 @@ static void log_phasors(const char *tag) {
 }

 /*
- * 函数功能：L1-6 判定结果的告警编排（边沿 → 日志 + 自检留痕）
+ * 函数功能：采样有效性校验 判定结果的告警编排（边沿 → 日志 + 自检留痕）
 * 入口参数：hs - adc_health_check() 判定结果快照
 * 返 回 值：无
 * 限定条件：仅任务上下文；日志仍受写者就绪门控（SYSLOG 不受——内核前有
@@ -278,8 +322,15 @@ int adc_task_init(void) {
    s_rail_edge_latched = 0u;
    s_rail_syslogged = 0u;
    s_meas_ms = 0u;
-    adc_health_init();   /* 内含 L5-2 贴轨观察器复位（rail_init） */
+    adc_health_init();   /* 内含 采样通道自检 贴轨观察器复位（rail_init） */
    (void)meas_init();   /* 遥测快照双区/序号复位（幂等；发布状态属本任务，init 无日志） */
+    wave_ring_init();    /* 录波环纯清 RAM（无内核依赖；本函数在开闸前跑，init 禁日志不破） */
+#if defined(DTU_BENCH) && (WAVE_BENCH_AUTOCAP != 0)
+    s_wave_bench_on   = 0u;
+    s_wave_bench_off  = 0u;
+    s_wave_bench_t0   = 0u;
+    s_wave_bench_next = 0u;
+#endif
    return 0;
 }

@@ -321,7 +372,7 @@ void adc_task_func(void *arg) {
         * （osPriorityBelowNormal），是"UI 心跳缺席"的候选占用者之一 */
        task_prof_enter(TASK_PROF_ADC_BEAT);

-        /* 1) 采集一拍：L1 层 adc_input_poll() = TPAFE 原子快照 + 消费一帧 STM32 ADC1
+        /* 1) 采集一拍：语义取数与有效性层 adc_input_poll() = TPAFE 原子快照 + 消费一帧 STM32 ADC1
         *    DMA 双缓冲（仅任务上下文；TPAFE 侧 1=有新帧 0=无新帧 -1=参数错）。
         *    采样节拍由 TIM3 更新事件提供（ISR 内触发 CONVST + TRGO 触发 ADC1），
         *    本任务既不触发也不等待转换。
@@ -339,8 +390,8 @@ void adc_task_func(void *arg) {
            /* r == -1：参数错。调用点 count 为常量，不可达；不计入 idle 以区分异常 */
        }

-        /* 2) L2 输入 + 相量重算：把本拍 9 路语义值转浮点帧压入采样环，再重算全部
-         *    相量实例（L2-6 滑动窗：每拍以"当前时刻为终止的前一周波"整窗重算）。
+        /* 2) 全周傅氏相量输入 + 相量重算：把本拍 9 路语义值转浮点帧压入采样环，再重算全部
+         *    相量实例（每 1 ms 滑动窗刷新：每拍以"当前时刻为终止的前一周波"整窗重算）。
         *
         *    ⚠ **仅在本拍确有新帧（r == 1）时**才压环。
         *    原实现在 r == 0（TPAFE 无新帧）时**仍然**压环 + phasor_run()，只有 r == -1
@@ -366,14 +417,14 @@ void adc_task_func(void *arg) {
                    all_ok = 0u;
                    break;
                }
-                /* L1.5 折算（「数据可信」卡 2，§4.1 模型）：工程量 = (code + b) × k。
-                 * 现口径 = **ADC 引脚电压 V**（eng=0，卡 1 冻结的 ROM 系数，见
-                 * docs/硬件平台/ADC通道映射说明.md §7.1）；卡 0b/卡 12 写入标定
+                /* 标定折算折算（「数据可信」标定折算落地，§4.1 模型）：工程量 = (code + b) × k。
+                 * 现口径 = **ADC 引脚电压 V**（eng=0，量程口径冻结的 ROM 系数，见
+                 * docs/硬件平台/ADC通道映射说明.md §7.1）；端子变比确认与两点标定写入标定
                 * 系数（adc_cal_flags() 出 VALID）后才按二次值消费。TEMP 透传码值
                 * 不折算（决策 5）。*/
                frame[s] = adc_cal_apply((adc_semantic_t)s, code);

-                /* L5-2 码值越界（贴轨）观察：在**码值域**判定，与标定正交——
+                /* 采样通道自检 码值越界（贴轨）观察：在**码值域**判定，与标定正交——
                 * 连续一周波贴轨带且此前见过释放沿才锁存（空载恒 0 不误报）。
                 * TEMP 无「轨」语义，adc_cal_rail_ths() 返 -1 自然跳过。*/
                if (adc_cal_rail_ths((adc_semantic_t)s, &lo_th, &hi_th) == 0) {
@@ -386,11 +437,11 @@ void adc_task_func(void *arg) {
            if (all_ok != 0u) {
                (void)sample_ring_push_frame(frame, (uint8_t)ADC_SEM_COUNT);
                phasor_run();
-                /* L2 派生量测频（B8）：同拍紧随 phasor_run——本拍使用区已
+                /* 全周傅氏相量的派生量测频（B8）：同拍紧随 phasor_run——本拍使用区已
                 * 切换，freq 读的就是本拍相量（1 ms 同上下文，无竞态） */
                freq_run();

-                /* L2 遥测快照发布（「数据可信」卡 8，道D，M5）：200 ms tick 经过分频。
+                /* 测频与遥测快照发布（「数据可信」这一项，道D，M5）：200 ms tick 经过分频。
                 * 唯一发布者 = 本任务（全仓 meas_tick 调用点数 = 1 为评审判据，
                 * 「数据可信」§8 风险表"快照双写"行）；只在**压环成功的真新帧拍**发布
                 * ——idle/skip 拍压环未推进，发布 = 重复旧窗。品质注入唯一源 =
@@ -428,7 +479,7 @@ void adc_task_func(void *arg) {
            }
        }

-        /* 2b) L1-6 采样有效性校验（每拍，常数次整数运算）：把驱动侧观测计数交给
+        /* 2b) 采样有效性校验（每拍，常数次整数运算）：把驱动侧观测计数交给
         *     纯逻辑判定层，本任务只做告警编排。⚠ 计数一律取**本拍 poll 之后**
         *     的值——与刚消费的帧同一时点，避免"下一拍的增量被提前看到"。 */
        {
@@ -446,10 +497,107 @@ void adc_task_func(void *arg) {
            adc_health_report(&h_st);
        }

+        /* 2c) 故障录波环泵送（task-2 数据面接线；状态机与计数全在 App/algo/wave_ring.c，
+         *     本段只做搬运）。每拍取 8 路语义**原码**压环 + tick 推进；触发那拍的样本
+         *     落在段内点 WAVE_RING_PRE-1（点序 lead 钉死）。只存原码不存折算工程量——
+         *     §6.3 裁定：样本域 = 原始码，折算系数进段头，回放/PC 侧统一换算。
+         *     某路取不到（开机头几拍）保持上值（与 adc: 心跳行同一兜底口径）。
+         *     tick 返 EVT_SEALED 的那拍必须**同拍** latch meta（头注唯一合法次序），
+         *     漏了 = 2 s 后环自弃计 err，defaultTask 根本不会见到这一段。 */
+        {
+            uint8_t w;
+            int32_t wev;
+
+            for (w = 0u; w < WAVE_RING_CH; w++) {
+                int32_t wc = 0;
+
+                if (adc_input_raw((adc_semantic_t)w, &wc) == 0) {
+                    s_wave_codes[w] = (int16_t)wc;
+                }
+            }
+            (void)wave_ring_push(s_wave_codes, WAVE_RING_CH);
+            wev = wave_ring_tick(now, s_frames_consumed);
+
+            if (wev == WAVE_RING_EVT_SEALED) {
+                uint8_t c;
+
+                /* 封存瞬间事实（交棒结构 s_wave_cal 为文件级 static，不上栈）：
+                 * eng / VALID 位图 / CLIPPED 位图 / 墙钟 / 逐路 conv+bits+avail+k+b。
+                 * eng 口径 = adc_cal.h 注③ 的 8 路量纲标签（判据源
+                 * App/app/ui_data_feed.c feed_eng()，与 prot_blocked 的三路口径**不是**
+                 * 一件事）：8 路电气量全 VALID 才是二次值；V0.1 无 CT 变比，一次值不可达。
+                 * wall 未对时写 0（sys_clock_get 失败 = UINT32_MAX，不许拿上电毫秒冒充）。
+                 * k 取 adc_cal_k_q16() int32 原值；b 的 float 回乘在本域无损
+                 * （|b| 限幅 8192 << 2^24，float32 精确表示整数；禁用浮点只针对 k）。 */
+                s_wave_cal.flags_seq = 0u;
+                s_wave_cal.clip_mask = 0u;
+                for (c = 0u; c < WAVE_RING_CH; c++) {
+                    const uint32_t f = adc_cal_flags((adc_semantic_t)c);
+                    const adc_channel_desc_t *d = adc_input_desc((adc_semantic_t)c);
+
+                    if ((f & ADC_CAL_F_VALID) != 0u) {
+                        s_wave_cal.flags_seq |= (uint8_t)(1u << c);
+                    }
+                    if ((f & ADC_CAL_F_CLIPPED) != 0u) {
+                        s_wave_cal.clip_mask |= (uint16_t)(1u << c);
+                    }
+                    s_wave_cal.ch[c].conv = (d != NULL) ? (uint8_t)d->source
+                                                        : (uint8_t)ADC_SRC_STM32;
+                    s_wave_cal.ch[c].bits = (s_wave_cal.ch[c].conv == (uint8_t)ADC_SRC_TPAFE)
+                                            ? 16u : 12u;
+                    s_wave_cal.ch[c].avail   = (uint8_t)f;
+                    s_wave_cal.ch[c].k_q16   = adc_cal_k_q16((adc_semantic_t)c);
+                    s_wave_cal.ch[c].b_codes = (int32_t)adc_cal_b_codes((adc_semantic_t)c);
+                }
+                s_wave_cal.eng = (s_wave_cal.flags_seq == 0xFFu)
+                                 ? (uint8_t)WAVE_ENG_SEC : (uint8_t)WAVE_ENG_PIN;
+                {
+                    uint32_t wall = sys_clock_get();
+
+                    s_wave_cal.wall = (wall == UINT32_MAX) ? 0u : wall;
+                }
+                /* 只在 EVT_SEALED 拍调一次；返错不补救——环 2 s 超时自弃兜底，
+                 * 这里补第二行日志就违反 §9「不在已留痕处重复锚点」 */
+                (void)wave_ring_latch_meta(&s_wave_cal);
+            }
+        }
+
+        /* 2d) bench 定周期自抓（§10 红线落点：默认关闭 + 时长上限 + 启动一次性告警）。
+         *     编译门 = DTU_BENCH 且 WAVE_BENCH_AUTOCAP 非 0，产品镜像无本段。
+         *     节拍：每 WAVE_BENCH_PERIOD_MS 投一次 bench 请求（环侧冷却/去重自管，
+         *     被丢的计入 ovf——这是 bench 的预期观测面，不是故障）。
+         *     计时起点等写者就绪门（v2.1 理由：就绪前直发会与 defaultTask 存储
+         *     日志字节级交错）；到时自动停 + 一次性 STOP 行，之后不再投任何请求。
+         *     ⚠ 这两条 WARN/STOP 是一次性生命周期日志，不是周期行，§9 一条线约束不破 */
+#if defined(DTU_BENCH) && (WAVE_BENCH_AUTOCAP != 0)
+        if (s_wave_bench_off == 0u) {
+            if (s_wave_bench_on == 0u) {
+                if (dbg_console_writer_ready() != 0u) {
+                    s_wave_bench_on = 1u;
+                    s_wave_bench_t0 = now;
+                    s_wave_bench_next = now + WAVE_BENCH_PERIOD_MS;
+                    /* [WARN] 进正文（本仓无 WARN 级；用 ERR 级会带 [ERR] 误触 /serial-boot-test 禁用标记） */
+                    DBG_INFO("[WARN] wave bench autocap ON: 1 seg / %u ms, auto-stop %u s (BENCH BUILD ONLY)",
+                             (unsigned int)WAVE_BENCH_PERIOD_MS,
+                             (unsigned int)(WAVE_BENCH_MAX_MS / 1000u));
+                }
+            } else if ((uint32_t)(now - s_wave_bench_t0) >= WAVE_BENCH_MAX_MS) {
+                s_wave_bench_off = 1u;
+                DBG_INFO("wave bench autocap STOP after %u s",
+                         (unsigned int)(WAVE_BENCH_MAX_MS / 1000u));
+            } else if ((uint32_t)(now - s_wave_bench_next) >= WAVE_BENCH_PERIOD_MS) {
+                s_wave_bench_next = now + WAVE_BENCH_PERIOD_MS;
+                (void)wave_ring_request((uint8_t)WAVE_TRIG_BENCH, 0u);
+            } else {
+                /* 本拍未到周期点：无事可做（比较用无符号差值，回绕安全） */
+            }
+        }
+#endif
+
        /* 3) 首帧码值上报：**写者就绪后**才落日志。写者未注册时 con_append 走
         *     无锁直发路径，与 defaultTask 的存储初始化日志会字节级交错
         *     （2026-10-10 台架实测）；此时挂起上报，就绪后补报最近一帧。
-         *     8 路电气量 + 温度全部经 adc_input_raw() **按语义**取数（L1-4），
+         *     8 路电气量 + 温度全部经 adc_input_raw() **按语义**取数（通道语义映射），
         *     用于验证"语义 → 物理通道"映射与两片转换器取数契约 */
        if ((first_logged == 0u) && (s_frames_consumed != 0u) &&
            (dbg_console_writer_ready() != 0u)) {
@@ -472,9 +620,9 @@ void adc_task_func(void *arg) {
                     (long)ia, (long)ib, (long)ic, (long)in, (long)temp);
        }

-        /* 4) 首拍相量上报：攒满一周波（20 ms）后立即落一次，作为 L2 链路的开机证据。
-         *    不依赖 10 s 心跳 → 台架 @test 的 settle 窗口内即可见（否则会被静默判据
-         *    截断，见 docs/测试说明/自动化测试流程.md 的 settle 口径）。 */
+        /* 4) 首拍相量上报：攒满一周波（20 ms）后立即落一次，作为 全周傅氏相量链路的开机证据。
+         *    不依赖 10 s 心跳 → 台架 /serial-boot-test 的 settle 窗口内即可见（否则会被静默判据
+         *    截断，见 docs/测试说明/流程与规范/自动化测试流程.md 的 settle 口径）。 */
        if ((first_phasor_logged == 0u) && (dbg_console_writer_ready() != 0u)) {
            phasor_t p;

@@ -487,7 +635,7 @@ void adc_task_func(void *arg) {
        /* 5) 看门狗心跳（本任务已纳入 required_mask） */
        task_wd_beat(TASK_WD_ADC);

-        /* 6) 周期心跳日志：帧统计 + 驱动侧 FRSTDATA 错误计数 + L2 相量。
+        /* 6) 周期心跳日志：帧统计 + 驱动侧 FRSTDATA 错误计数 + 全周傅氏相量。
         *    写者就绪前抑制（同 3) 的交错理由）；到点无论是否落日志都推进下个上报点 */
        {
            if ((int32_t)(now - report_at) >= 0) {
@@ -500,7 +648,7 @@ void adc_task_func(void *arg) {
                     *   adc1_hw  = HAL ADC/DMA 错误回调
                     * 判读：adc1_seq 停增而 seq 仍涨 → STM32 侧停摆；
                     *       adc1_gap 增长 → 本任务耗时超拍（看 adcm/adcn）；
-                     *       tgap = TPAFE 侧同类丢帧计数（L1-6，与 adc1_gap 对称） */
+                     *       tgap = TPAFE 侧同类丢帧计数（采样有效性校验，与 adc1_gap 对称） */
                    DBG_INFO("frames=%lu idle=%lu skip=%lu seq=%lu frst_err=%u ring=%lu"
                             " adc1_rc=%d adc1_err=%lu adc1_seq=%lu adc1_gap=%lu adc1_hw=%lu"
                             " tgap=%lu",
@@ -519,11 +667,36 @@ void adc_task_func(void *arg) {

                    log_phasors("hb");

-                    /* L1.5/L5-2 台架观测面（×1000 mV 定点，MicroLIB 无 %f）：
+                    /* 全 9 路**原始码值**（「数据可信」已知电压注入验证的唯一连续读出口）：
+                     * 与 first: 行同序同格式（UA/UB/UC/UN/IA/IB/IC/IN/T），台架
+                     * "改电压 → 读一行"即可对表，不必为每个注入点反复复位去抓只在开机
+                     * 出现一次的 first: 行。两处的通道顺序是同一份约定，改一处必须同步另一处。
+                     * ⚠ 为何单独一行、不并进下面的 cal: 行：cal: 已 75 字符，9 个码值最坏
+                     *   再加 93 字符，逼近 DBG_CON_LINE_MAX(192) 的截断边界——截断**不报错**，
+                     *   只会静默少打几路，是最难发现的台架假数据来源；分行后各自留足余量。
+                     * ⚠ 取数失败（-2 该来源无有效数据）时该槽保持 0，故"9 路全 0"读作
+                     *   "没数据"，不读作"九路都是 0 V"——判据是 frames 心跳是否仍在涨。 */
+                    {
+                        int32_t rc[ADC_SEM_COUNT];
+                        uint8_t j;
+
+                        for (j = 0u; j < (uint8_t)ADC_SEM_COUNT; j++) {
+                            rc[j] = 0;
+                            (void)adc_input_raw((adc_semantic_t)j, &rc[j]);
+                        }
+                        DBG_INFO("adc: UA=%ld UB=%ld UC=%ld UN=%ld IA=%ld IB=%ld IC=%ld IN=%ld T=%ld",
+                                 (long)rc[ADC_SEM_UA], (long)rc[ADC_SEM_UB],
+                                 (long)rc[ADC_SEM_UC], (long)rc[ADC_SEM_UN],
+                                 (long)rc[ADC_SEM_IA], (long)rc[ADC_SEM_IB],
+                                 (long)rc[ADC_SEM_IC], (long)rc[ADC_SEM_IN],
+                                 (long)rc[ADC_SEM_TEMP]);
+                    }
+
+                    /* 标定折算/采样通道自检 台架观测面（×1000 mV 定点，MicroLIB 无 %f）：
                     *   ua/un/ia_mv = 三路 TPAFE 引脚电压毫伏（未标定域，**不是**
-                     *     二次值；卡 12 注入验证的读数落点，偏差判据 ≤2 %）
+                     *     二次值；两点标定注入验证的读数落点，偏差判据 ≤2 %）
                     *   vl = VALID 位图（默认构建应恒 0x00——未标定即未标定，
-                     *     卡 5 的闭锁判据在 protect 侧同源消费这个位）
+                     *     未标定即闭锁的判据在 protect 侧同源消费这个位）
                     *   cl = CLIPPED 位图（V0.1 应恒 0xE6 = UB/UC/IB/IC/IN）
                     *   rail/edge = 贴轨锁存/历史边沿位图（注入饱和电平后应起）*/
                    {
@@ -577,6 +750,46 @@ void adc_task_func(void *arg) {
                                 (long)(ms.freq_hz * 100.0f),
                                 (unsigned)ms.freq_valid);
                    }
+
+                    /* 录波环周期行（docs/子系统设计/故障录波设计说明.md §9 逐字模板，
+                     * 字段名与顺序**不许动**——PC/台架脚本按行名 grep）。全链路只加这一条
+                     * 周期行（每条 DBG ≈90 B Flash + 216 B 栈，§9 明令不加第二条）：
+                     *   seg  = 累计成功 ACK 的段数（wave_ring_stat.seg_total，不是轮转号）
+                     *   armed= 1 表示此刻有段在飞（FREEZE/SEALED；IDLE/COOL 为 0——
+                     *          COOL 只挡新触发不录新段，画进 armed 会让台架误读）
+                     *   src  = 触发源 M 手动 / P 保护 / T bench 定时，- = 本 boot 未触发过
+                     *   err  = 落盘失败 + SEALED 超时自弃（环内 err_cnt 收口，落盘道不数
+                     *          第二份账）；ovf = ACK 前重复触发与冷却期丢弃数；
+                     *   drop = 冻结窗口丢弃的录波点数（单位=点）
+                     * 判读：bench 自抓一轮后 seg_total 应增长；err 涨而 seg 不涨 =
+                     * 落盘道在丢段，查 defaultTask 侧 [WAVE] 失败行 */
+                    {
+                        wave_ring_stat_t wst;
+
+                        (void)wave_ring_get_stat(&wst);
+                        {
+                            const char *sc;
+
+                            if (wst.trig_src == (uint8_t)WAVE_TRIG_MANUAL) {
+                                sc = "M";
+                            } else if (wst.trig_src == (uint8_t)WAVE_TRIG_PROTECT) {
+                                sc = "P";
+                            } else if (wst.trig_src == (uint8_t)WAVE_TRIG_BENCH) {
+                                sc = "T";
+                            } else {
+                                sc = "-";
+                            }
+                            DBG_INFO("wave: seg=%lu armed=%u src=%s pts=%u err=%lu ovf=%lu drop=%lu",
+                                     (unsigned long)wst.seg_total,
+                                     (unsigned)((wst.state == (uint8_t)WAVE_RING_ST_FREEZE) ||
+                                                (wst.state == (uint8_t)WAVE_RING_ST_SEALED)) ? 1u : 0u,
+                                     sc,
+                                     (unsigned int)WAVE_RING_PTS,
+                                     (unsigned long)wst.err_cnt,
+                                     (unsigned long)wst.ovf_cnt,
+                                     (unsigned long)wst.drop_cnt);
+                        }
+                    }
                }
                report_at = now + ADC_TASK_REPORT_MS;
            }
@@ -26,6 +26,18 @@
 *   v1.3  2026-10-25  DTU 项目组  写回缓存空闲 flush 接线：主循环 syslog 排空
 *                          之后调 vol_idle_sync_poll()（卷空闲周期 CTRL_SYNC 兜底，
 *                          模块 = App/fs/vol_idle_sync.[ch]，道F 批 2）
+ *   v1.4  2026-10-29  DTU 项目组  故障录波落盘道（task-2）：vol_idle_sync_poll 之后
+ *                          新增 wave_store_drain()——一次心跳整段搬完（lead 裁③：
+ *                          一次 try 锁内 pack_next 256 B 分片 + 完整 open...close），
+ *                          持锁耗时 >50 ms 补一条 WARN、峰值 ms 记本层静态；
+ *                          轮转号自持（启动扫 /wave 重建，成功 ACK 才推进，lead 裁(b)）；
+ *                          失败 = 先 unlink 半成品再 write_done(-1)（lead 裁①）；
+ *                          卷未就绪 / 环未封存静默跳过（§5.1 所有权 + §9 一条线约束）
+ *   v1.5  2026-10-29  DTU 项目组  Lead 复核补第四道并发陷阱（本道与 adcTask 的抢占窗）：
+ *                          搬段中途 adcTask 可能正好走到 SEALED 滞留自弃（2 s）甚至
+ *                          已封出下一段——CRC 是对"读到的字节"算的，半新半旧的段照样
+ *                          自洽，只能靠写完关档后复检环侧身份（握手量 + 段首 t0/帧序）
+ *                          判废：判废即 unlink、不 ACK、号不推进，失败按既有单条留痕
 */

 #include "default_task.h"
@@ -38,9 +50,10 @@
 #include "nand_ftl.h"
 #include "net_cfg.h"
 #include "cfg_file.h"
-#include "run_par.h"     /* 运行参数段落盘（卡 10，配置引擎属主 = 本任务） */
+#include "run_par.h"     /* 运行参数段落盘（「数据可信」这一项，配置引擎属主 = 本任务） */
 #include "prot_set_store.h"
 #include "prot_set.h"      /* task-10：prot_set_dirty_peek（区分"无待写"与"真落盘"） */
+#include "iec104_comm.h"   /* 道G task-9：[comm] 段落盘（脏位轮询同款，通讯设置页） */
 #include "sys_log.h"
 #include "sys_events.h"
 /* 深调用链模块（本任务 = 存储 bring-up + 配置引擎属主 + syslog 唯一写者，
@@ -52,6 +65,8 @@
 #include "task_prof.h"        /* 各任务最坏耗时上报 */
 #include "vol_lock.h"
 #include "vol_idle_sync.h"   /* 写回缓存空闲 flush 兜底（App/fs/vol_idle_sync.h） */
+#include "wave_ring.h"       /* 录波环消费侧：sealed/sealed_meta/read_cb/write_done（task-2） */
+#include "wave_store.h"      /* 段打包游标 + 段号轮转纯函数（落盘道本体，task-2） */
 #include "task_handles.h"   /* 任务句柄与属性块的引用契约（定义处仍是 Src/freertos.c） */

 /* Private defines -----------------------------------------------------------*/
@@ -71,6 +86,14 @@
 * （自检已上报、卷保留、不重格式化），等下次上电重新 resume */
 #define STORAGE_BRINGUP_RETRIES 3u

+/* 录波段落盘持锁耗时告警线（lead 裁③i）：一次心跳整段 5250 B（约 21 次 256 B
+ * f_write），设计 §4.2 预估落盘窗「几十 ms」；越过本线说明本段在占用 defaultTask
+ * 喂狗链前的最慢一段，按事件补一条 WARN（不是周期行），并把历史峰值留在本层
+ * 静态里供收工报告核喂狗余量（vol_lock.h 铁律「等锁即毁喂狗链」的前例在案） */
+#define WAVE_DRAIN_HELD_WARN_MS   50u
+/* 搬运缓冲（§7 的 256 B；wave_store_pack_next 头阶段要求 cap >= 128，lead 转告(d)） */
+#define WAVE_DRAIN_CHUNK_B        256u
+
 /* Private typedef -------------------------------------------------------------*/
 typedef struct {
    const char *p_name;
@@ -96,6 +119,7 @@ static void stack_probe_poll(void);
 #if !defined(TEST_SUITE_STORAGE)
 static void default_task_net_cfg_save_notify(void);
 static FRESULT storage_bring_up(FATFS *fs);
+static void wave_store_drain(void);
 #endif

 /*
@@ -241,9 +265,12 @@ void default_task_func(void *argument) {
        if ((prot_set_dirty_peek() != 0u) && (prot_set_store_save() == 0)) {
            syslog_post(SYSLOG_OPER, "settings saved");
        }
-        /* 运行参数段落盘（卡 10）：同款脏语义；save = 引擎整档外科写
+        /* 运行参数段落盘（「数据可信」这一项）：同款脏语义；save = 引擎整档外科写
         * （[run_par] 9 键 + 被 adc_cal_set 联动改写的 [adc_cal] 两段一趟落） */
        (void)run_par_store_save();
+        /* [comm] 段落盘（道G task-9 通讯设置页）：同款脏位、每轮无条件，
+         * 无事件位（task-8 D5 口径——ca 改后重启生效，落盘只保断电不丢） */
+        (void)iec104_comm_store_save();
        #endif
        /* 配置文件变更轮询（2s 周期；沉降去抖在引擎内） */
        if ((cfg_poll_cnt++ % 40u) == 0u) {
@@ -297,6 +324,10 @@ void default_task_func(void *argument) {
         * 一次 f_close 同型的同步段。放在 drain 之后：本拍若写过日志，close
         * 已同步过，这里随即 clean 短路——漏网脏页的驻留窗由周期封顶 */
        vol_idle_sync_poll();
+        /* 录波段落盘（task-2）：卷空闲 + 环已封存才搬，就绪门/try 锁全在函数内；
+         * 一次心跳最多一段（lead 裁③）。放在 idle sync 之后：本拍若刚写过录波段，
+         * 下一拍空闲 flush 会兜住残留脏页，语义与 syslog 排空同位 */
+        wave_store_drain();
        #endif
        /* 栈水位观测：首次 5s 后报告，此后每 2s 采样、出现更深峰值才打印 */
        task_wd_seg(TASK_WD_SEG_STACK);
@@ -328,7 +359,7 @@ void default_task_func(void *argument) {
 * 节奏：首次 STACK_PROBE_FIRST_MS 后报告（bring-up 深链已跑过），此后每
 * STACK_PROBE_PERIOD_MS 采样一次，只在出现更深峰值时打印——既不改串口静默
 * 窗口，也不漏掉之后才走到的更深分支（如卷修复/配置保存路径）。
- * 输出（纯 ASCII，便于 @test 采集）：
+ * 输出（纯 ASCII，便于 /serial-boot-test 采集）：
 *   [STACK] <task> peak_used=<B>/<cfg> free_min=<B> (<pct>%)
 *   [STACK] heap free=<B> min_ever=<B>
 * 未覆盖 idle/timer 任务（内核静态小栈、纯循环，未取句柄）。
@@ -561,6 +592,248 @@ static FRESULT storage_bring_up(FATFS *fs) {
 }
 #endif /* !TEST_SUITE_STORAGE */

+/*
+ * 函数功能：故障录波落盘道——把已封存的 wave_ring 段整段搬进 /wave（task-2）
+ * 入口参数：无  void
+ * 返回值：无  void
+ * 限定条件：仅 defaultTask 主循环调用（vol_idle_sync_poll 之后）；内部绝不阻塞——
+ *          try 锁 + 有界段长（5250 B / 256 B ≈ 21 次 f_write，设计 §4.2 预估几十 ms），
+ *          绝不把喂狗点做成等待态（vol_lock.h 使用约定：defaultTask 一律 try）
+ * 函数说明：所有权按 docs/子系统设计/故障录波设计说明.md §5.1——环的生产者是
+ *          adcTask，本道是唯一落盘消费者；跨任务握手只认 wave_ring_sealed()。
+ *          本道承担五条口径：
+ *          ① 打开一律 FA_WRITE|FA_OPEN_APPEND：本移植 FA_OPEN_APPEND 不含 FA_WRITE
+ *             （docs/架构设计/STM32F4-Base存储架构说明.md §10.1 陷阱一），少写位
+ *             f_write 恒 FR_DENIED；
+ *          ② 每次 f_write 比对写回字节数：本移植簇分配失败返 FR_OK+短写无错误码
+ *             （同处陷阱二），短写一律判失败；
+ *          ③ 轮转号由本道自持（lead 转告(b)）：ring.seg_idx 只是本 boot 本地计数，
+ *             盘上权威下标 = 首次持锁扫 /wave 用 wave_store_idx_from_name() 重建
+ *             （取已存在最大号 +1，空目录 = 0，陌生名字不入账），写成功才
+ *             wave_store_next_idx() 推进；失败不推进、重试同号；
+ *          ④ 成败都必须 wave_ring_write_done() ACK——ACK 前环一直冻结；err 账
+ *             由 ring 的 err_cnt 单点收口（§9），本道不数第二份（ACK 前环已
+ *             超时自弃的那次例外：skip 掉 ACK，不去补第二笔账）；
+ *          ⑤ 锁跨越一次完整 open...close（vol_lock.h 铁律），持锁耗时超
+ *             WAVE_DRAIN_HELD_WARN_MS 按事件补一条 WARN（§9 唯一周期行不在本道），
+ *             历史峰值 s_wheld_ms_max 供核 defaultTask 喂狗余量（lead 裁③）。
+ *          失败处置（lead 裁①）：开过文件才 unlink 半成品（未开成的失败不动盘，
+ *             绝不拿未初始化的路径误删旧段）；unlink 失败照旧 ACK(-1)——最坏留
+ *             一个坏段文件，PC 侧被 CRC 判废，不会画成证据。
+ *          静默跳过（不刷屏）：卷未就绪 / 环未封存 / try 锁没到（下轮再来，
+ *          环侧 2 s 超时自弃是兜底账，本道不为此打日志）。
+ *          （上面五条口径就是本函数功能「把已封存段整段搬进 /wave」的逐条展开，
+ *           细则出处 docs/子系统设计/故障录波设计说明.md §5.1 与 §10）
+ */
+static void wave_store_drain(void) {
+    static FIL             s_wfil;        /* static：FF_FS_TINY=0 时 FIL ~528 B，
+                                           * 绝不上栈（FS_VOL_PROBE 同一理由） */
+    static uint8_t         s_wbuf[WAVE_DRAIN_CHUNK_B];
+    static wave_pack_ctx_t s_wpack;
+    static wave_seg_meta_t s_wmeta;
+    static char            s_wpath[WAVE_ST_PATH_MAX];
+    static DIR             s_wdir;
+    static FILINFO         s_wfno;
+    static uint8_t         s_wnext_idx;    /* 本道自持的下一个段号 0..99 */
+    static uint8_t         s_wscan_done;   /* 1 = 本 boot 已扫过 /wave */
+    static uint8_t         s_wdir_ready;   /* 1 = /wave 已建或已存在 */
+    static uint8_t         s_wcrc_state;   /* 0 未验 1 过 2 败（败=永久自弃，不烧垃圾段） */
+    static uint32_t        s_wheld_ms_max; /* 持锁搬段历史峰值 ms（收工报告核余量用） */
+    uint32_t    t0_ms;
+    uint32_t    held_ms;
+    uint32_t    written = 0u;
+    uint32_t    len = 0u;
+    uint32_t    iter;
+    uint8_t     opened = 0u;
+    uint8_t     skip_ack = 0u;             /* 1 = 环已自行了断本段，本道不 ACK 不补账 */
+    wave_ring_stat_t wst2;                 /* 关档后复检环侧身份用（v1.5） */
+    const char *why = NULL;
+    FRESULT     fr;
+    UINT        bw;
+    int         rc;
+
+    /* 就绪门（同 vol_idle_sync_poll 的四级门风格） */
+    if (sys_evtHandle == NULL) {
+        return;
+    }
+    if ((osEventFlagsGet(sys_evtHandle) & SYS_EVT_STORAGE_READY) == 0u) {
+        return;
+    }
+    /* 封存门：只搬已封存段（唯一跨任务握手量，§5.1） */
+    if (wave_ring_sealed() == 0u) {
+        return;
+    }
+    /* 空闲门：try 锁；卷被 syslog/配置/FTP 占住 → 本轮放弃，不排队不打日志 */
+    if (vol_lock_wait(0u) == 0u) {
+        return;
+    }
+    t0_ms = (uint32_t)xTaskGetTickCount();
+
+    /* CRC 锚点自检每 boot 一次（落盘前失败 = 整族失败，永久自弃免得白烧写次数） */
+    if (s_wcrc_state == 0u) {
+        s_wcrc_state = (wave_store_crc_selftest() == WAVE_ST_OK) ? 1u : 2u;
+    }
+    if (s_wcrc_state == 2u) {
+        why = "crc selftest FAIL";
+    }
+    if ((why == NULL) && (s_wdir_ready == 0u)) {
+        fr = f_mkdir(WAVE_ST_DIR);
+        if ((fr == FR_OK) || (fr == FR_EXIST)) {
+            s_wdir_ready = 1u;
+        } else {
+            why = "mkdir /wave";
+        }
+    }
+    if ((why == NULL) && (s_wscan_done == 0u)) {
+        FRESULT rr;
+
+        fr = f_opendir(&s_wdir, WAVE_ST_DIR);
+        if (fr == FR_OK) {
+            uint8_t found = 0u;
+            uint8_t mx    = 0u;
+
+            for (;;) {
+                uint8_t ix;
+
+                rr = f_readdir(&s_wdir, &s_wfno);
+                if ((rr != FR_OK) || (s_wfno.fname[0] == 0)) {
+                    break;
+                }
+                if (wave_store_idx_from_name(s_wfno.fname, &ix) == WAVE_ST_OK) {
+                    if ((found == 0u) || (ix > mx)) {
+                        mx = ix;
+                    }
+                    found = 1u;
+                }
+            }
+            (void)f_closedir(&s_wdir);
+            if (rr == FR_OK) {
+                /* max+1 即下一写号；回绕号复用由 PC 侧 t0/frame_seq 对账兜底，
+                 * 目录里没有的事实不去猜更多（陌生名字一律不入账） */
+                s_wnext_idx  = (found != 0u) ? wave_store_next_idx(mx) : 0u;
+                s_wscan_done = 1u;
+            } else {
+                why = "readdir /wave";
+            }
+        } else {
+            why = "opendir /wave";
+        }
+    }
+    if ((why == NULL) && (s_wscan_done != 0u)) {
+        if (wave_ring_sealed_meta(&s_wmeta) != WAVE_ST_OK) {
+            /* sealed 检查与此读之间环 2 s 超时自弃（err 已由环计过）：
+             * 本道不 ACK、不补账、不打日志，放锁走人 */
+            skip_ack = 1u;
+        }
+    }
+    if ((why == NULL) && (skip_ack == 0u)) {
+        /* lead 转告(e)：E_FORMAT/E_SIZE = 坏段头，一律当落盘失败丢段计 err，
+         * 不当参数错吞掉 */
+        rc = wave_store_pack_start(&s_wpack, &s_wmeta, wave_ring_read_cb, NULL);
+        if (rc != WAVE_ST_OK) {
+            why = "pack_start";
+        }
+    }
+    if ((why == NULL) && (skip_ack == 0u)) {
+        if (wave_store_seg_path(s_wpath, (uint32_t)sizeof(s_wpath),
+                                s_wnext_idx) <= 0) {
+            why = "seg_path";
+        } else {
+            fr = f_open(&s_wfil, s_wpath, FA_WRITE | FA_OPEN_APPEND);
+            if (fr != FR_OK) {
+                why = "f_open";
+            } else {
+                opened = 1u;
+            }
+        }
+    }
+    iter = 0u;
+    while ((why == NULL) && (opened != 0u)) {
+        rc = wave_store_pack_next(&s_wpack, s_wbuf,
+                                  (uint32_t)sizeof(s_wbuf), &len);
+        if ((rc != WAVE_ST_OK) && (rc != WAVE_ST_DONE)) {
+            why = "pack_next";
+            break;
+        }
+        if (len != 0u) {
+            bw = 0u;
+            fr = f_write(&s_wfil, s_wbuf, (UINT)len, &bw);
+            if ((fr != FR_OK) || (bw != (UINT)len)) {
+                why = "f_write short";   /* ②：FR_OK+短写 = 本移植独有失败形态 */
+                break;
+            }
+            written += len;
+        }
+        if (rc == WAVE_ST_DONE) {
+            break;
+        }
+        if (++iter > 32u) {              /* 5250/256 = 21 片；游标卡死时的有界保险 */
+            why = "pack stall";
+            break;
+        }
+    }
+    if (opened != 0u) {
+        fr = f_close(&s_wfil);
+        if ((why == NULL) && (skip_ack == 0u) && (fr != FR_OK)) {
+            why = "f_close";
+        }
+    }
+    if ((why == NULL) && (skip_ack == 0u) && (opened != 0u)) {
+        if (written != wave_store_pack_total(&s_wpack)) {
+            why = "len mismatch";        /* 长度等式（§6.3）：半截文件骗不过这条 */
+        }
+    }
+    /* v1.5（lead 复核）：adcTask 优先级高于本道，搬段中途它可能正好把滞留 2 s 的本段
+     * 自弃（甚至已经封出下一段）。数据区的 CRC 是对"本道读到的字节"算的，半新半旧的
+     * 段一样自洽 → 关档后必须复检：握手量没了、或段首身份不是本段，一律判废。
+     * 判废走既有失败路：unlink 本道开过的文件 + write_done(-1)（此时多半回 E_STATE，
+     * 环侧的 err 已由自弃计过，这里不重复补账）+ 段号不推进（同号重写覆盖）。 */
+    if ((why == NULL) && (skip_ack == 0u)) {
+        if ((wave_ring_sealed() == 0u) || (wave_ring_get_stat(&wst2) != WAVE_ST_OK)
+            || (wst2.last_t0_ms != s_wmeta.t0_ms) || (wst2.last_seq != s_wmeta.frame_seq)) {
+            why = "ring abandoned";
+        }
+    }
+    if (skip_ack == 0u) {
+        /* 失败留痕边沿锁存（搬进本块，lead 裁方案 A）：
+         * ① 它是 static，初值只在编译期发生一次、不是每次进块重置；
+         * ② 它是"上一拍是否处于失败态"的边沿锁存，所以必须跨调用存活；
+         * ③ 单独放这里而不在函数入口那 12 连排台账里，因为 variableScope
+         *    检查要求把局部量收进真正覆盖全部使用点的最小块（本仓刻意开了 style）。 */
+        static uint8_t s_wfail_latch;  /* 一个 episode 只留一条痕 */
+
+        if (why == NULL) {
+            (void)wave_ring_write_done(0);
+            s_wnext_idx = wave_store_next_idx(s_wnext_idx);  /* 成功才推进（转告(b)） */
+            s_wfail_latch = 0u;
+        } else {
+            if (opened != 0u) {
+                (void)f_unlink(s_wpath); /* 只清本道开过的文件；unlink 失败照旧 ACK */
+            }
+            (void)wave_ring_write_done(-1);
+            if (s_wfail_latch == 0u) {
+                s_wfail_latch = 1u;      /* 持续失败不刷屏；成功一次重新武装 */
+                DBG_ERROR("[WAVE] seg drop: %s (idx=%u written=%lu)", why,
+                          (unsigned)s_wnext_idx, (unsigned long)written);
+            }
+        }
+    }
+
+    /* 持锁耗时台账（lead 裁③i/ii）：超线按事件补一条 WARN（原先这里静默占锁，
+     * 就是「等锁即毁喂狗链」前例的同族黑洞）；峰值进静态供收工报告 */
+    held_ms = (uint32_t)xTaskGetTickCount() - t0_ms;
+    if (held_ms > s_wheld_ms_max) {
+        s_wheld_ms_max = held_ms;
+    }
+    if ((skip_ack == 0u) && (held_ms > (uint32_t)WAVE_DRAIN_HELD_WARN_MS)) {
+        /* 本仓 dbg_log 无 WARN 级（宏只有 ERROR/INFO/DEBUG，ERR 级自动带 [ERR] = /serial-boot-test
+         * 禁用标记）：[WARN] 按 console_log.c 先例进正文，慢不是错（真失败另有 seg drop） */
+        DBG_INFO("[WAVE][WARN] seg held %lu ms (idx=%u)",
+                 (unsigned long)held_ms, (unsigned)s_wnext_idx);
+    }
+    vol_lock_release();   /* 成败/跳过都放锁：锁泄漏比丢一段录波重一百倍 */
+}
+
 /*
 * 函数功能："保存网络配置"请求通知（注册给 net_cfg 的保存交接；
 *          2026-09-25 自 Src/freertos.c 迁出，逻辑零改动）
--- a/Show More
+++ b/Show More