wandering1/STM32F4-Base
1
0
Fork 0
Code Issues 30 Pull Requests Actions Packages Projects 2 Releases Wiki Activity
712 Commits 3 Branches 0 Tags
69d70af4cf2a9ad63292d454f062f63cb426b508
Commit Graph

31 Commits

Author SHA1 Message Date
wandering1 a275539c17 docs(全仓): 内容页黄金 47 → 53 的当前态同步——含钩子显示名，登记簿口径另笔 
task-9 让内容页黄金从 47 涨到 53（通讯设置页六态），本笔只做**当前态陈述**的同步；真值全部本轮实测：
`simulator/tests/ref/*.bin` = **53**；`git diff 31ca4a1f..HEAD` 对该目录 = **
6 个新增、零修改** ⇒ 存量 47 张
逐字节未变（这条是关键：新增页不该让旧页重生成，否则回归基线就失去意义）。

**四类命中各走各路，这是本笔的全部难点**（分类比替换重要得多）：
· 当前态 → 改，25 处页数，落在 16 只文件（AGENTS、钩子显示名、导航器 docstring、`lvgl-simulator` s
kill、
  门禁索引与 `ui-golden` 详解、UI 自动化流程、内容页架构、页面补齐规划与扩充方案、数据供给、自动化测
  试流程、覆盖率口径、测试开发标准流程、模拟器两份 README）；
· 变更记录历史行 → **一条不动**，另在其下一行插入当日「47 → 53」新行 6 条（含判据与零漂移证据）；
· **同数不同义 → 不动**：覆盖率口径里的「47 个 .c」「47 = 13+5+29」、ram_report 的表行号 47、`#47-D`
  诊断号、LSI 47kHz、47,360 栈字数、像素哈希 3476/3474 —— 一并替换就会毁掉六个不相干的事实；
· 带日期戳 / 自declare 冻结的快照 → 不臆改（数据供给篇那句上一笔已加「当时」，页面补齐规划里那张
  「2026-10-25 复核…剩 21 叶」的表自带「完成即冻结不回改」声明）。

复扫残留当前态 47 = **0**。⚠ 顺手纠一条**会教错方法**的陈旧：naive 计数 `grep -c '#page='` 上一笔写的是
22，现在真值是 **23**（文件头示例行也算一次）——旧文档里那个 22 **恰好等于新的正确 bound 数**，不改的话,
下一个人用错算法还能碰巧对上，比错更糟。

⚠ `AGENTS.md` 里本次有两件事同行相邻（本笔的内容页 53 页 + 批次三那句 `TC-*` 停发），**分两句说明**：
前者是计数同步，后者是昨天那条「批次三不坐」裁定的入口文案，二者不是同一件事。

钩子显示名改在 `.pre-commit-config.yaml`（47 → 53）。**这条必须与代码同批入库**：配置脏而未 stage 时
pre-commit 会直接报错挡住全仓任何提交（今天已实测两次），所以本笔先落它，把后面几笔的路清开。

自查：`check_doc_links --all` rc=0（203 篇）、`check_ids --strict` rc=0 且不可判定绝对
数 **979 未变**（新增
文本里的提交号与 `#page=comm` 没推高它）、`gen_task_table --check` 0、`check_bom_drift`
 0、18 只文件 noBOM /
LF / U+FFFD=0；行数变动 +49/−47 全部可归属（插 6、删 2、并 1），其余为 1:1 等行替换。登记簿销项与叶数
（`UI补齐.md` + `docs/任务规划/README.md`）**不在本笔** —— 那是口径变更不是计数同步。
 2026-10-27 13:54:05 +08:00
wandering1 c0d7bb9c8e docs(门禁): mem-budget 第 6 节补一条盲区——同码凭证按 git 索引生成，多人同树时必红 
今天道G 报出 `check_size_gate.py --local` 单跑 exit 1（代码指纹与体积测量指纹不一致），我复核后确认这不是
预算问题、也不是谁改坏了台账，而是**该凭证的定义在多人同树下必然不成立**：代码指纹取的是 **git 索引里的
blob**，而此刻工作区里有别的任务在飞、尚未入索引的改动 ⇒ 两边算出来的东西本来就不是同一份内容。

写进 §6 的三点判据：
· 它**只挂在 `scripts/ci_local.py` 的 L0c，不在这 51 条 pre-commit 钩子内** ⇒ 红它不等于提交
会被拦，别在
  提交被拦的清单里找它；
· 报错若同时列出「未入索引的文件」而那些文件正被别的任务改 ⇒ 等它们入库后统一 `@build` →
  `ram_baseline.py --update` 补凭证；**绝不为把它调绿去 `git add` 别人在飞的改动**（这条比前两条更要紧，
  今天就这样发生过一次：别人已 staged 的文件会被我的 add 顺手卷进我这一笔）；
· 本节写作时凭证**仍是红的**（回填发生在通讯卡入库之后）——我只写成因与判据，**不预告还没发生的结果**，
  这正是 `pre-commit使用说明.md` §2.5 那条「注释陈述事实不陈述意图」在同一天的第二次应用。

自查：`check_doc_links --all` exit 0（198 篇）、本篇 `--sections-strict` 通过、noBOM
 / LF / U+FFFD=0 / 结尾
换行齐；`id-check` 未受影响（本笔零编号）。本笔零代码，且此刻两条道正在写 `Drivers/BSP/UI/` 与
`App/algo/`，故只提这一只文档文件。
 2026-10-27 09:47:23 +08:00
wandering1 95beaab313 refactor(编号): 第一批清号——登记簿旧号/阶段号/台架阶段裸形三族清零，位号目录排除 
按 §9 批次一执行。**这批的关键发现是「看着像 62 处编号，实际能算编号的只有一小半」**，所以先分类再动手，
没有按站点数硬清：

· **真·编号（已改名）**：`N-6`（`MDK-ARM/tcp_reconnect_probe.py` 的「TRAP-NET-17 / N-6
」→ 只留 TRAP 锚点
  + 中文说明）；台架阶段裸形 `T0`~`T3` 全部转成场景名——`e11_keepalive_probe.py` 的「静默对端 / 正常空闲存活」、
  `ftp_auth_bench.py` 的「匿名登录 / 未登录直接 NLST / 错口令锁定」、`serial_tool.py` 自检里的「行拆分 /
  解码回退链 / 时间戳行格式 / 端口建议」、`net_test_task.c` 与 `CH395F_Test_Guide.md` 的「空闲存活场景」、
  网络自愈设计里的「三路审计」。另把 `test/host/iec104_master.py` 的变量 `T0` 改成 `t_start`（那是起始时刻
  变量，被裸形族误抓）。
· **不是编号、但被误判（按 §4.4 处理，不改语料）**：`tools/netlist_semantics/` 里的 `T1` 是**网络变压
器位号**
  （硬件知识库），整目录进 `excluded_paths`，与 `docs/硬件平台/` 同口径；`BSD_Socket_API_函数调用关系.
md` 的
  `T1/T2/T3` 是 **Mermaid 节点名**，已改成语义节点（`RetryTick`/`PendTick`/`PendShimTic
k`/`ReconcileTick`）——
  图本身没变，只是节点不再叫字母号；`docs/门禁说明/gitlint.md` 里的 `T2` 是 **gitlint 自己的规则名**（不是本仓
  的号），已改写成规则描述；`docs/算法/傅氏算法详解.md` 的 `N-1` 是**数学记号**（求和上界 `x(N-1)`），保留不动，
  并在 §4.4 登记为「唯一已知误判」。
· **规范自身两处示例**顺手去掉字面量：`S3 / TM-PHY-01 / DP-03` → `S3 / TM-… / DP-…`；「报告 N-
16」→「报告 +
  登记簿旧号」。

结果（用门禁接口复测）：`TM` 族 0 引用、`T-TEST` 族只剩规范自身 2 处示例、`N` 族只剩数学记号 1 处；
`F-*`（38 站点 / 12 个号，代码注释里的网络设计条目号）**留下批单独做**，因为每处要读懂语义、不能替换字面量。

口径变更已写进 §4.4：位号目录 `tools/netlist_semantics/` 进排除面；`N-1` 声明为已知误判。歧义面收窄后，
新错误级仍为 0、`id-check --strict` exit 0。

⚠ 这批**刻意没有复活「别名表洗白」那条路**：`N-6` 这类死号不进 `id_aliases.json`，让门禁继续咬将来的残留
引用（与 FTP 死号同一处理，见 §5.7）。
 2026-10-27 07:39:00 +08:00
wandering1 31ca4a1faa docs(计数): 内容页黄金参考 40 → 47 页全仓同步，登记簿剩余项与顺序一并更新 
上一笔 UI 落地时我把「文档计数与真值同源」这件事留在了别人身上（setpage 的移交项写得很明白：内容页 40→47
的全仓计数改写由 Lead 派）。这一笔把它做完，**只改当前态陈述，历史不动**：

· **改成 47 的判据**：simulator/tests/ref/ 实测 47 张 .bin（7 张新增、存量 40 张逐字节零漂移），共 1
6 处当前态
  陈述跨 11 只文件同步——含 AGENTS 的 ui-golden 条目、**钩子显示名**（.pre-commit-config.yaml）
、门禁索引与
  ui-golden 详解的标题与正文、UI 自动化流程的页数与 PASS 文案与快检张数、内容页架构回归段、覆盖率口径的
  「不做 UI 单测」理由、启动自动化流程回归段、导航器脚本 docstring。
· **不改的两处，理由写明**：5 只文件里的历史变更记录行「27 → 40 页」是当天事实，原样保留，只在各文件
  变更记录顶部加一行 2026-10-27 的 40 → 47；UI_界面制作流程 的「< 40KB」是绘制缓冲红线，与本数无关，
  属扫描误报，不动。
· **一处加限定语而不是改数**：UI_自动化测试流程 的「文本断言 310 条、覆盖 40 页中的…」带 2026-10-26 实跑
  日期戳，那是那天的测量口径 ⇒ 改成「覆盖**当时** 40 页」，310 条不臆改，等下一次实跑回填真值。

顺带同步 docs/任务规划/README.md（登记簿销项，用户授权）：开篇「第一项是实现 param_request 写路径、然后做
整定 4 页」早已完成 ⇒ 改为剩余三项「通讯设置 → 记录 5 页 → 运行报告」；§2 顺序表「按 §1 的 1→5 推进」改为
「剩余 3 项按 1→3 推进（原第 1、2 两项已落地）」，与上一笔 UI补齐.md 的销项结果对齐。

三数同源自查：AGENTS 钩子数 51（YAML 解析口径）、内容页 47 页、门禁索引 27 篇均与配置一致；
check_doc_links.py --all exit 0、check_ids --strict exit 0 且不可判定绝对数 **1,156
 未变**（本笔没吃余量、
没新增编号引用）；13 只文件全部 noBOM / LF / U+FFFD=0 / 结尾换行齐。本笔零固件源，不改构建产物。
 2026-10-27 07:16:32 +08:00
wandering1 f1d0b5c2d9 docs(规范,门禁): 卷锁五态去裸形——本仓第一次真正还第二根护栏的债，并写清还债的算法 
最反直觉的是结果里的差值：36 处裸形态号全部清零，绝对数只从 1,162 降到 1,156（−6，余量 4 → 10 格）。
作者没把差值糊过去而是查到底：check_ids 只在字面量**落不进任何已登记族**时才计不可判定，撞进已登记族的
23 处本来就记在可判定侧，删它们分子分母同缩、比例反而从 86.74% 涨到 86.77%；真正在盲区里的只有族外
7 处，其中 1 处还被变更记录行豁免 ⇒ 账面 −6，算式对平（±1 属同窗别道在飞）。**这四条机制我写进
docs/门禁说明/id-check.md §6.10 并署名作者**——它是「怎么还这根护栏的债」的第一份操作口径。

改动面：App/fs/vol_lock.c 10 处、.h 6 处、vol_lock_test.c 14 处、卷锁单元测试说明.md 3 处 ⇒ 同口径
改后 0 处。四态语义只留 vol_lock.h 的 vol_lock_stats_t 注释一处，其余三处只描述断言并指回头文件，
不抄第二真源。除 4 行声明外全是注释文字，代码行为零改动。顺带消掉一个**同形两义**的撞号源。

实测：1,162（03:15:08）→ 1,156（03:21:56），写变更记录后复量仍 1,156（本笔没吃余量）；--strict exit
0；vol_lock 套件 45/45；**上限未动、刻意不跑 --update-baseline**（作者反对成立：重锚会把只减不增的线
按这次 −6 重画，白丢一次真还债的账面记录）；未改 id_registry.json / 台账，未跑 --all-files。
 2026-10-27 05:14:11 +08:00
wandering1 1d39571114 feat(门禁): 第 51 条 nested-comment——把 ARMCC #9-D 的按包含者刷屏拦在提交前 
动机是今天一天复发三次的同一形态：在块注释里写作用域路径，那个 `/*` 被 ARMCC 当第二次注释起点（诊断 9-D），
而且**按包含者数量刷屏、只在重编译那个 TU 时才暴露**——本仓的诱因就是「注释里写 Drivers/BSP/UI/**」。
AGENTS 早就写了这条铁律（写全目录或用尖括号），但它一直是纯口头纪律，所以同一天还是复发三次。

新脚本 scripts/check_nested_comment.py：纯标准库、只读、五状态机（代码 / 行注释 / 块注释 / 字符串 / 字符
字面量），**只有块注释体内的 /* 才算问题**——字符串里的、行注释里的、未闭合判定都不误报。口径上刻意与钩子
的 types: [c] 对齐（403 个 .c/.h 同面），避免「手跑面 ≠ 提交面」这类我们今天就踩过的错位；零第三方依赖是
刻意的，为了让 generated-fresh 那天的解释器假红不长第二遍（实测 .venv 与机器级 C:Python314 两种解释器结论
一致）。

存量口径：全仓实扫**新发 0、存量 2 处**（test/host/common/ch395f_fake.h:7 与 fatfs_fake.h:9，同一形态
「注释里写作用域 test/host/**」）。两份假件头不参与 MCU 构建所以今天不报，一旦被 include 进板端 TU 就会
按包含者刷 9-D——属 test/ 写域，作者**没代改**，而是钉进 BASELINE 走只减不增，**其余零豁免**。

自证有一条必须写清的诚实边界：作者想「拿旧字节回放今天那三处真复发」，实测**做不到**——近 150 个提交里被
改过的 281 份 .c/.h 旧字节**零命中**，因为那三处同类从来没有一处在 HEAD 里留过字节（全靠人工编译后清掉）。
于是改测**形态**（这是能证的部分）：10 项形态电池 10/10，含把已入库的尖括号写法退回星号形态 → 命中 1 处；
另用现存两份真字节做双跑：空基线 → 2 条 [NEW] + exit 1，加基线 → exit 0，证明**基线只决定算不算新的，
不掩盖有没有**。编译器侧原文（run_par.c(267) #9-D）冻结抄进新文档 §2.1——构建日志每次 @build 被覆盖且不入库，
所以文档里刻意没写「最近一次日志里仍有」这种会过期的话。

计数三处同批：AGENTS「共 **51** 个钩子」、门禁索引「51 个 hook → 27 篇 + 1 指针 + 1 外置」、配置声明；并记
文本 grep「 - id:」= 52 的成因（第 65 行被注释掉的 clang-format 候选），收紧行首口径 = 51。作者顺带自打了
一次：在配置注释里复述了那个 grep 字面量 → 文本计数当场虚高 1，已改写并把「配置注释里别复述字面量」写进
README §2 与 AGENTS。

同笔带上 task-28 的裁定句（AGENTS 一只文件里两卡改动天然混在一起，拆开会多两次改写与一次风险）：不补第
23 根 ui-sink 专属钩子——22 根的唯一意义是秒级归因，而 ui_sink 失败面全落在 test-coverage 总闸必跑路径、
失败照样拦；读「这套跑没跑」去看总闸输出，别数钩子。

实测与本笔自查：validate-config = 0；nested-comment --selftest 4/4、--all = 403 / 新发 0 /
存量 2 → exit 0；
doc-links --sections-strict（4 篇）= 0；gen_task_table --check = 0；generated-fresh
PASS（5 处存量走 WARN）；
check_ids --strict exit 0，**不可判定绝对数全程未被本闸吃掉**（作者开工 1,162、写完新闸与新文档仍 1,162；
现 1,156 是队友还清的）；全部改动文件 noBOM / LF / U+FFFD=0。未跑 pre-commit --all-files（只跑本闸）。

**本笔使用 --no-verify 的凭证（唯一允许的两条之一，按 MEMORY 台账例外口径）**：把本批 6 只文件单独
staged 后跑 `pre-commit run --files <这 6 只>` → **13 条 Passed / 1 条 Failed**
唯一失败的是 `mem-budget`
（RAM 92% 阈值，**全树检查**）。本批**零固件源、零 .map 变更**，该红来自其他队友在飞的固件改动造成的 .map
漂移（当前树 Code=231,952 / RW=1,528 / ZI=136,264，在库台账 231,712 / 1,504 / 136,216
差 = run_par setter
与 vol_lock 计数两笔，均未提交）；台账回填由我在树能编后统一 `--write`，不在分支上跑（避免多分支同改受管表）。
gate: only mem-budget pending lead ledger backfill。字节卫生本笔自查：6 只文件均 noBOM / L
F / U+FFFD=0，
新脚本纯 ASCII 输出路径无关，AGENTS 与索引两处计数与配置 YAML 解析口径 51 一致。

另收一条今天反复出现的元教训（Lead 与作者各错过一次、方向相反）：**`pre-commit run` 与 git 钩子不是同一根
探针**——config 处于 modified-unstaged 时只有后者 [ERROR] 拒绝，前者与 validate-config 都 Passed
。它与「stash
只覆盖已跟踪未暂存」「未跟踪文件永不进 stash」同族：手跑的探针不能替真提交的探针作证。
 2026-10-27 03:44:18 +08:00
wandering1 c90380bf9c docs(门禁): 拆开「不可判定绝对数」的真实构成，并写下每批自证没吃余量的做法 
起因是今天下午我自己给三条道下过一条错指令：「编号余量只剩 4，别新增 TC 号、优先用母号加小写子项」。
刚才用检查器自己量了一遍，**那条指令的机制是错的，而且方向危险**：

  refs_total 8,744 − decidable 7,582 = 1,162，逐项拆开精确闭合、无第四类：
  · skip_bare_unmanaged 834 —— 裸形盲区（同字母多义的裸号出现在属主登记处之外，§6 明令不判）
  · noise_allowed        326 —— 命中 id_registry.json 的 noise_literals 白名单（不是编号
形态像）
  · undecidable            2 —— 真·硬不可判定：族还登记着、属主登记处已空（清号批次遗留）

也就是说这 1,162 里约 99.8% 是**设计上的豁免**，而带属主登记处的族无论加多少引用都是「可判定」，
一点不吃这根护栏。更要紧的是：我那条指令会把人推向「把编号改写成语义短语/散文」——**那恰好是
§7.6 加这根绝对数护栏要防的稀释**（比值会被清号动作稀释，绝对数不会）。等于我让团队去撞自己立的闸。
指令已向五条道撤回，并写进新增的 §7.7 第 3 条读法里，免得下一个人再走一遍。

§7.7 同时把「每批自证没吃余量」写成可复制的五项式：改前先记三个数 → 改后逐数比对（⚠ --strict 只
回答有没有新错误级，不回答可判定占比动没动，不能当替身）→ 若涨了用 git show HEAD:<路径> 取临时副本
或开一棵 worktree **只回退自己名下文件**再跑同一扫描器（明令禁止用 git stash / checkout 回退，那会
把别人在飞的改动一起收走，本仓同一天刚为此踩过）→ 报告写全 refs/dec/und/比值/错误 五项差值，
不许只写「跑过没问题」→ 真还掉一块后用 --update-baseline 同步下调上限（脚本自己拒绝上调；
手工调高上限等于自废这道闸）。

另澄清一处容易误读的地方：本文件打印的「校验 1 未登记前缀：0 处」与这 1,162 不矛盾——校验 1 报的是
**新增错误级行为**，护栏统计的是**分母水位**，一个是行为一个是水位，别互相替换。

实测与本笔自查：check_ids.py --strict exit 0（可判定 7,582/8,744 = 86.71%、不可判定绝对数 1,162
**未变**，本笔没吃余量，也没新增任何编号引用）；check_doc_links.py --all exit 0（186 个文档）；
本篇 --sections-strict exit 0（新增引用一律写成可校验的紧邻形式：docs/文档规范.md §3.5，并把草稿里
指向不存在的 §5.2 改对——编号规范只有 5.1/5.3/5.5/5.7）；字节卫生 bom=false / CRLF=0 / U+FFFD=0 /
结尾换行齐。裸形与噪声样例没有写进正文（[示例] 行虽在进分母前就豁免，但把野形态抄进文档没有收益）。

看板：本笔收口 task-34。其余在飞任务由五条道继续，我只暂存本篇一个文件。
 2026-10-27 01:59:28 +08:00
wandering1 b24b2b5f31 docs(计数): 内容页黄金参考 27 → 40 全仓同源改写，含钩子显示名这最后一处不同码
CI / L0 静态门禁 (pre-commit) (push) Failing after 49s
Details
CI / L0.5 主机侧单测 (MSVC) (push) Failing after 45s
Details 
UI 三页落地后机器真值变了，文档却还写着 27 页——这不是笔误，是会骗人的现在时。
作者（batch-auditor）先自己从机器面取数再动笔：git ls-files 里 ref/*.bin = 40、
PAGES 40 项、TEXTS 37 页 310 条、ABSENT 16 页 29 条、池 5448 B 与常驻堆 5368 B 未变、
字库 183 字未扩。**它还纠了我一个数**：我报 ABSENT +19，实测 11 → 29 = +18；作者按
实测写文档，并且不在文档里写 ABSENT 总数，免得把我这个差 1 的数固化成第二真源。

改写面（现在时陈述，共 12 + 3 处）：AGENTS.md 的 ui-golden 半句、门禁说明 ui-golden.md
（标题与「拦不住什么」段）与索引行、simulator/tests/README.md、simulator/README.md 两处、
UI_自动化测试流程.md（310 条 / 40 页 / PASS 文案 / 覆盖面）、内容页架构.md、页面补齐规划.md、
主机单测覆盖率口径.md、自动化测试流程.md、测试开发标准流程.md，外加
.pre-commit-config.yaml 里 ui-golden 的显示名——那是「声明 / 文档 / 实跑」三数同源的最后
一处不同码：AGENTS 与门禁说明都已 40，配置里还写着 27。

两条纪律作者都自证了，不是口头：
· **历史数字一律保留**：8 处变更记录行里的 27 / 242 / 24 / 11 原样未改；两处带日期的
  验证记录只加限定语（「该下限此后已扩至 40 页，双次逐字节一致需按同口径重跑回填」），
  没有把 27 改成 40 去造连续性。
· **同名不同义的数字不许全局替换**：页面补齐规划.md:12 与 :157、页面扩充详细方案.md:649
  里的「27」是**空叶子口径**，与黄金参考数无关——三处故意没动。这条比改对更值钱。
· 余量自证（回退名下 12 文件复跑同一扫描器）：refs +0 / dec +0 / und +0 / 比值 +0.00pp /
  错误 +0，本笔零消耗，也未新增任何编号引用；simulator/tests/ref/ 下 40 个 .bin 零改动。

闸线现状照实挂着：id-check 不可判定 1,162 / 上限 1,166，**余量只剩 4**（吃进者是今天
UI 那笔的注释引用，账在 Lead）。清账之前任何人新增编号都可能直接撞闸。
 2026-10-27 00:16:07 +08:00
wandering1 41c277a8ae docs(门禁): 抢跑等价门禁自查表落地——把「谁漏跑一次，这道检查这次就不存在」写死 
今天三次 --no-verify 共放过三类真问题：5 条 CODE-RULE-17（.c/.h 配对）、2 个缺尾换行加
1 个漏提文件（HEAD 一度是「代码已整行独占、旁边 runner 文档串还写着无锁直发」）、
以及共享尾段 +80 B 把 iec104Task 压到 1,024 B ISR 底线之下。根因不是「不该抢跑」，
而是**抢跑时只跑了部分等价门禁**——doc-links、id-check、字节卫生都跑了，唯独漏了
stack_report，而它恰恰是数字与安全边界那一类。

§2.4 三组清单（任何人可用，不是 Lead 特权说明）：A 抢跑前必跑（stack_report、
ram_report、ram_baseline --gate 含「跳过不等于有余量」、coding-standard、bom-drift
含「别用有 BOM 就是错的外行判据」、mojibake、受影响模块单测、test-coverage、id-check、
doc-links、generated-fresh 必须 .venv、ci_local 并注明它**不含** stack_report 与
ram_baseline 所以不能当替身）；B 手跑代替不了真提交的三类（改写型钩子、要靠 stash
才能正确归因的、只有真提交才碰到的 gitlint 与正文每行 80 列）；C 抢跑之后：
git show --stat 对交付清单 + git status 里不该再出现声明过的文件（含 ??，漏提 runner
就是这么发现的），并强制在正文点名「哪些没跑、为什么、谁在飞」。

一条结构性说明：stack_report 与 ram_baseline **不在钩子清单里**，所以「人漏跑一次 =
这道检查这次不存在」；要机械化得先解决「磁盘 .htm/.map 属于最后一次构建的那个人」
——与 stash 覆盖面那条同源，不是加一根钩子就完事。另写明 --all-files **也不 stash**，
会让改写型钩子当场改全库，只能在静默窗口跑、跑完复核。

文档里的命令必须能直接跑：只读等价那条一行式刻意纯 ASCII——Windows PowerShell 5.1 按
ANSI 读无 BOM 的 .ps1，带中文标签的版本会碎成 SyntaxError（作者踩过并复现），改完后
从文档里抽出来重跑验证：checked 40 files (incl untracked)，problems 0。

同篇顺手核掉的同源不同源（可单独回滚）：§6 钩子数 40 → 50（口径 = YAML 解析条目；
直接 grep 声明行会多算一条被注释掉的候选 = 51）、主机侧单测「16 个合一篇」→ 22 根
专属钩子 + 18 套走 test-coverage 总闸；两处跨行断行的表格行修好，全文 8 个表格块
列数一致（脚本核过）。generated-fresh.md §4 补上解释器解析口径与 [ENV] 输出。
 2026-10-26 23:42:41 +08:00
wandering1 0f8b88337e docs(门禁): 主机侧单测覆盖面改写成口径陈述，第三处计数不同源一并修 
「22 根专属钩子」是**口径**不是缺口：test/host 实测 42 个目录去掉 common/__pycache__
= 40 套带 run_unit_test.py，配置里带 -unit-test 后缀的只有 22 根 ⇒ 其余 18 套
（含 ui_sink、console_log、net_socket、lftpd 三兄弟、sys_log_mcu、iec104_serv、
task_prof…）没有独立 files: 触发面，但每次提交都被 test-coverage 总闸全量真跑，
失败照样拦——执行面无洞的证据核到源码：check_test_coverage.py:134 用 rglob 发现
全部 40 套，:44-46 的退出码语义写死「有单测失败即 1」。缺的只是秒级归因。

补钩子的判据也现成：pre-commit 4.x 移除了 always: true，没有 files: 触发面就等于
永不跑，所以**不能**靠"补第 23 根"解决，要补就得先给该模块划触发面。

顺带查出同类的第三处不同源（也在 docs/门禁说明/ 内）：host-unit-tests.md 自己还写
着「16 个钩子 / 另有 12 套 / 总闸跑 28 套」，三个数全部过期，已改成 22 / 18 / 40，
§1 表补齐 2026-10-25 增补的六行，§6 第 4 条重写成覆盖面台账，§9 留变更记录。
另用 git log -S 核实原句「23 个 / 含 ui-sink 七个」是双重错：ui-sink-unit-test、
iec104-serv-unit-test、console-log-unit-test 在配置历史里**从未存在**过。
页数不变（26 篇），钩子数不变（声明 50 / 实跑 50 / 专属单测钩子 22）。
 2026-10-26 19:27:01 +08:00
wandering1 7d9db33a25 chore(门禁+文档): 生成器幂等钩子落地，文档真值与 UI 清单销项同步 
新增 generated-fresh 钩子（scripts/check_generated_fresh.py，只读）：把 gen_menu.py、
中文字库链、tools/arch_diagram/gen_*.py 拷进系统临时目录重跑，与工作区逐字节必须
一致；钩子本身不写仓库、不 stash 别人在飞的改动。实证起点是上一笔 0f7b5a87 改了
模板文字却没重跑生成物，接线前实测另有 5 张 docs/images 配图已漂（文档挪目录只改了
生成器里的路径）——那 5 张按既有范式钉成只减不增基线，业务生成物零豁免面。

计数三数同源核查：文本 grep 配置得到 51 是把第 63 行**注释掉的** clang-format 候选
算进去了，口径统一为「YAML 解析后的 hook 条目数」= 50（实跑 49 + gitlint = 50），
AGENTS 与 docs/门禁说明/README.md §2 用同一条自查命令。顺带更正「主机侧单测 23 个
（含 ui-sink）」：实为 22 个，test/host/ui_sink 有 run_unit_test.py 却没有 per-module
钩子，只有覆盖率总闸跑得到它（已另立待办，不当既成事实写进文档）。

文档真值一批（都按脚本/仓库实测取数，不抄旧文档）：内容页黄金 11/18 页 → 27 页
（8 处，含 ui-golden 钩子显示名）、文本级断言 50 条 → 242 条、池容量 4784/4864 →
5368/5448（含菜单页面设计.md 与同文档 1.5 节自相矛盾的那处）、页面补齐规划的立项
快照加限定语（日期按该文档自身标题 2026-10-23，不臆造现值）。变更记录里的历史数字
（11 页、50 条、老基线时代的绝对峰值）一律不改；无法实测的绝对峰值改成增量口径并
标注「待按新基线重测」。

销项（用户裁定 2026-10-26）：UI补齐.md 与 README §1 删除「param_request 写路径」
与「整定 4 页」两行并重排序号，叶数口径 12/21/16 改 16/17/12；定值项数按
App/algo/prot_set.h 的 PS_ID_COUNT 更正为 40（原写 31 是旧口径）；「主站地址白名单」
移入当前不做并写明理由：CH395F 单连接 socket 上「拒绝即 close+重 listen」等于给扫描
风暴开门，且该值现在没有任何既有消费点。

台架证据入库（像 = 77779d49，仓外 detached worktree 只读出像）：启动日志、仅复位不
重烧日志、104 定值写读腿、控制台交错一手字节证据与四张板照，boot_log_data 台账登记。
.gitignore 兜一条 %SystemDrive%/：子进程环境缺 SystemDrive/ProgramData 时 UV4 会按
字面量在仓库根建字体缓存目录，本会话实测复发两次，不兜住某次 git add -A 就进历史。

自证：改前后编号门禁 refs / 不可判定 / 比例 / 错误级逐项差值为 0（未把可判定引用改成
散文）；check_doc_links --all 无法判定 0；文档路径检查通过 177 篇。

本笔不含三条在飞源码道与板端导航脚本修复，它们各自单独一笔。

为什么本笔走 --no-verify（按仓库既有约定，非偷懒）：本笔内容是**纯文档 + 门禁脚本/配置 +
台架证据**，不含任何业务代码；而工作树里同时压着三条在飞源码道（UI 装置维护 3 页、
[comm] 配置段、控制台行级原子性）。pre-commit 跑钩子前会 stash 未 staged 改动，那
等于把别人未完成的代码算进本笔账——console_log 套件的属主自己就报告过「当前还没跑过
该套件」。逐条相关门禁已单独实跑：check_doc_links --all（无法判定 0）、check_ids
（余量差值为 0）、generated-fresh 用 .venv 解释器直跑 PASS（4 项 / 一致 3 / 存量基线
1 / 报错 0）、validate-config 0、BOM 漂移与 mojibake 干净、YAML 解析条目 50 与文档
及实跑三数同源。唯一会红的是 mem-budget：磁盘上的 .map 含上述在飞代码，与 HEAD 台账
不同码；台账与体积凭证由我在源码道全部落地后统一重建回填。证据文件：
ci-artifacts/commitA2.log（上一次尝试的完整钩子输出）。

另记一条本笔实测到的坑（已写进 AGENTS「Python 环境」与 docs/门禁说明/generated-fresh.md
§4）：钩子 entry 的裸 python 会被 pre-commit 解析成机器级解释器（本机 = C:\\Python314，
无 fontTools）→ 字体链生成器报 No module named fontTools、generated-fresh 假红。修法
是脚本内自己按「显式 var > 当前解释器 > 仓库 .venv > PATH」解析并做探针校验（装了
pre-commit 不等于装了 fontTools），但 entry 不写死绝对路径，否则门禁被绑死在一台机器。
这与 scripts/ci_local.py 文件头记的 2026-10-11「L0 全灭」是同一族问题的第二次发作。

台架证据补两行：板端 UI 导航脚本修复的真机冷启动闭环 PASS（首帧待机页 UNKNOWN →
按 e → 9 步到 view_set，终帧墨量与黄金 shot_vset 一致），存证同目录；该脚本本身的
改动留给下一笔。
 2026-10-26 18:26:47 +08:00
wandering1 0f7b5a87fb chore(编号): 存量编号全量转语义短语，门禁识别面与语料同批重打 
登记簿、文档与代码注释里的存量字母加数字编号（N-x / S-x / T-x / E-x / A-x / 卡号）
一律改写为语义短语，净删 2,028 处引用；删除基线与待确认、并行分道方案、排期详述、
采集保护收尾 4 篇（内容已并入 docs/任务规划/README 与登记簿）。

门禁机器与三张账同批重打：check_ids.py 新增变更记录行豁免与第二根护栏
undecidable_total_ceiling；check_test_traceability.py 只加 stdout/stderr UTF-8
reconfigure（TC_RE 未动）；check_cubemx_survival.py 的 --write 固定 newline=LF；
id_registry / id_aliases（+19 条 retired-to-phrase）/ id_known_backlog 重打。

test/ 56 个文件同步 TC 标签语义化，其中 18 个 TU 改了 CHECK / printf 里的标签文字，
是本批唯一改变构建产物的文件集合。

为什么合成一笔、不拆四笔（实测撞闸，非偏好）：pre-commit 跑钩子前会 stash 未 staged
部分，拆开后中间提交必然是「新规则 + 旧语料」——实跑可判定 85.15% < 基线 86.00%、
不可判定 1,453 > 上限 1,166，编号门禁直接拦下。编号识别面与它描述的语料只能同码移动。

实跑基线（工作区全量）：754 文件 / 8,230 处编号字面量 / 可判定 7,079 = 86.01%
（基线 86.0%，容差 0.1pp）/ 不可判定绝对数 1,151（上限 1,166）/ 校验 1-6 错误级 0 /
告警 = 悬空 2（App/algo/freq.c 的 S2，属 §4.4 同号不同义）+ 孤儿 50。

基线从 84.0 抬到 86.0 的理由见 docs/门禁说明/id-check.md §7.6：本批真删了 2,028 处
引用，可判定面随真实内容上升，不是把分母做小。同批新增排除 docs/硬件平台/ 语料，使
识别面少 264 处——芯片手册位号与网表料号不属编号空间（registry 有 excluded_paths_note）。

⚠ 余量只剩 0.11pp（约 10 处）与绝对数 15 处：把「可判定的引用」改成散文会立刻撞第二
根护栏。另遗留一项：id_aliases 里 retired 的 N / S / T / A 别名没有 scope（U1~U5 有），
今后有人新写一个 A-4，校验 3 不会响，只能靠人，建议下批补 scope。

固件不变证据：115 个 .c/.h 剥注释并归一字符串后与 HEAD 逐字节全等，残留代码差异 0；
App / Src / Drivers 的字符串字面量零改动。@build 0 错误 0 警告；40/40 主机套件、2,889
断言全通过；覆盖率 line 89.2% / func 92.6%；pre-commit 48 钩子 --all-files 全绿；
check_doc_links --all 通过（176 文档，章节引用无法判定 0）；逐字节卫生核过：14 个带
BOM 文件与 HEAD 一致、0 个 CR、0 个 U+FFFD，字符串字面量纯 ASCII。

.cubemx_survival_baseline.json 的 watchdog-module 哈希 56bf27 变 2bb051 属合法：
Src/freertos.c 的 USER CODE 区内只有注释文字随编号改写，代码未变。

同批带上体积同码凭证与 RAM 台账行（@build 之后盖戳）：RW_IRAM1 79,008 B / 60.3%，
RW_CCM 57,376 B / 87.9%，阈值 92%。
 2026-10-26 12:28:14 +08:00
wandering1 a92baa269e docs(boot_log_data): f3rounds 验收两轮日志存档 + id-check 二进制工件跳过 
道F task-22 commit 2/2（F1 票收尾）。素材 = 2026-10-25 最终主干 1a624b1（含看门狗
v1.5 按位分账 + F3 推流心跳边界）上的两轮 30min 判据轮；serial-assistant live 日志
按字节偏移切片（不 clear、行边界对齐），gz 前置 ASCII 头行记录偏移窗/负载定义/
v1.1 判据结论。原 megawin 16:18-16:48 摘录因 @test clear 轮转灭失（全盘无副本，
lead 核定非事故），归档位按裁改存这两只（v1.1 判据下的达标基线 + 残留真信号）。

轮①（:7003 relisten_stress 单独 30min，2200 connect/close 零拒绝）= PASS：
stall=0；MISS 758 条 NET 缺席=0（旧 12 条 NET 参与组合消失达成）；uisn 在途峰
103ms / uis 完成峰 183ms / UI 周期最坏 254ms——F2 复合零误报 + F3 阻塞型治愈的
定案样本。sha256 前 16 = 383dd291f37c6a5d（gz 165KB / raw 1.87MB）。

轮②（e02_probe 单独 30min，50 掉线窗）= FAIL（如实申报，零放水）：stall=8 = 3
事件（20:06:05/20:16:54/20:20:30；mask=0x1E7 纯 UI×7 + 0x167 UI+I104×1，h= 环全部
>=8 连窗真申报）；饿死型证据链：每样本点 uisn=0 + mg=217/262 + 拖点在 feed/port
墙钟而非推流段——「reconcile 突发饿死 uiTask」登记行与 E-27/28 批 3 的直接立项
证据（lead 裁定单列，处置方向 = 优先级矩阵复核 / reconcile 突发分片让路两条）。
全窗无 IWDG 复位。sha256 前 16 = b44eb3371c25e04c（gz 79KB / raw 0.75MB）。

README §3 表首两行沿用 B6/B7 验收轮先例（第三列放判据摘要）+ 表后存档说明行
（判读证据存档 != [STACK] 水位快照；判据口径指针 §7.2/工具名）。

【配套门禁修复（越界申报，因果耦合）】id-check 对二进制工件按文本 errors=replace
扫描：gz 乱码流随机拼出「字母-数字」形态伪编号，把无关存量顶成校验 1 台账外新账
（本 gz 入库实测拦下提交；png 属同类侥幸未撞形态）。iter_files 增加二进制嗅探跳过
（gzip 魔数或头 2KB 含 NUL → binary_skipped），与 noise_literals/盲区同口径；
docs/门禁说明/id-check.md §6 第 9 条 + 变更记录同步。教训自含：修复说明里引用噪声
示例本身会被再扫一遍——文档措辞只描述形态不举例（本次真实返工一次）。
scripts/check_ids.py 可写工具面，非登记簿/单写者文件；.pre-commit-config.yaml 未动。

【门禁】本树补跑 @build 0/0 落 .map；--all-files 48 绿 0 红；uvprojx UV4 抖动未入库；
登记簿双销项 + 新语义行 = lead 单写，本提交不碰 docs/任务规划/**。
 2026-10-25 20:51:44 +08:00
wandering1 e771a8ea21 docs(门禁计数): 钩子 48→49、单测行 16→22、uinav-selftest 上索引 
navtool 合入（3e03375）带进第 49 个钩子 uinav-selftest（快检档，专篇待补、
指针指向 UI_自动化测试流程 §7.3 正文）；门禁 README 索引头 42/25 系批 2
两批钩子未追平，本次一并核账为 49/26+1 指针，主机单测行 16→22（含批 2
六新套）；AGENTS 两处计数与新增括注同步。纯计数与索引，无口径变化。
 2026-10-25 18:10:44 +08:00
wandering1 7099c56c34 chore(ledger): pages 批 1~4 合入后回填凭证/覆盖率并同步黄金参考计数 
task/pages-ui 合入（merge dea7591 + 修复 498cc60）：三页回炉 + SOE 页 +
四查看页 + 遥信 33 行页 + ui_data 三通道 + soe_store 只读 API + 字库与
门禁配套共 12 笔。凭证重盖（Code=224,688 / RW_IRAM1 78,992 B=60.3% /
CCM 87.9%）；覆盖率基线 39/39 套件复算。ui-golden 黄金参考 11→18 页
随批 4 扩容，AGENTS 门禁行/索引行与门禁说明两处、覆盖率口径一处同步；
两篇新详解（bom-guard/setview-check）已由道E 交付、索引去"待补"。
memset 隐式声明一条教训：分支树增量构建"0 警"不覆盖未重编文件，
done 主树全量重编才是终判。
 2026-10-25 15:49:42 +08:00
wandering1 fa80b17d5f docs(门禁说明): 补 bom-guard 与 setview-check 两篇详解 
票面：task-20 合入后 README 索引上挂着我名的两篇（Lead 指定挂批 4 MR）。按本目录八段结构写，
「拦下过什么真事」一栏用同日实测，作者自己的也算。

- bom-guard.md：立项依据是 2026-10-25 一天内 5 次（道E 4 次 + 道B 1 次）；症状 #870-D / #8 /
  #274 一类**假语法错**，位置不指向真因；MSVC 与既有钩子全照不出来；"人工逐文件比 HEAD"只防得
  住记得做的人。两条刻意不报的边界（新文件无 BOM、反向加 BOM）+ 一条刻意不做（不自动补，整文件
  重写会把可修的丢 BOM 变成不可修的 U+FFFD）+ 三处互指防漂移，各写清理由。也记了本门禁自己的
  立项提交被 gitlint 拦过（正文一行 92>80，量出来仍按了提交）——这一栏只挑别人的事写就等于暗示
  写门禁的人不需要门禁。
- setview-check.md：立论点是"分层边界制造的物理盲区"——BSP 不得 include App 头，行表 id 只能是
  裸数字 + 注名，编译期无法自证；像素断言又只看可见 8 行，40 项分 5 页，错位一行时第 1 页可能
  看着完全正常。另收两条脚本自身实测坑：\w+ 吃不下带引号的单位导致**整行静默跳过**（故加行数
  硬闸）、打印中文时 CP936 半路崩（门禁脚本崩在半路 = 一条都没检查）。退出码 1 与 2 分开：把
  "我没读懂"报成"你写错了"是检查类脚本最坏的一种失败。
- README.md：索引加两行；"那 46 个钩子" → 48、"40 个 hook → 23 篇" → 42 → 25 篇（不同步就是在
  让索引说谎）。AGENTS 里"两篇待补"那句已过期，但 AGENTS 是单写者文件，留给 Lead 收。

跳过的门禁（三条同族）：mem-numbers / mem-budget / size-gate（L0c），与本笔无关，等台账回填。
 2026-10-25 15:33:46 +08:00
wandering1 30ebbe0c26 fix(字体门禁): 35 个"未知冗余"字成组并入 KEEP_EXTRA，钉死"按 extract 重写=洗字形" 
本笔不改任何代码行为，只补一条**已存在的保护洞**（Lead 裁定 2026-10-25 随道E task-15 顺手提
独立提交）。

现象：font-charset 门禁的"未知冗余"WARN 清单（txt 有、源码无、且不在 KEEP_EXTRA）实测正好
35 字——一位公分合外已年度延态总接显最月未求温状电示秒请跳载近道部配重长间闸障。这批字是
2026-09 窗口固件写进 /log/selftest.log 与 /log/run.log 定长 64 B 记录的中文描述用字（那批
源码文案后来整体改写成 ASCII，字面量已不在）。

为什么要登记而不是当冗余删掉：
- extract_cn.py 只认"当前源码字面量"（实测 144 字），而 ui_cn_chars.txt 现有 183 字。谁按
  extract 的输出重写 txt（font-regen 流程的第 2 步就是这么用的），这 39 字（含此前逐字登记的
  异/常/片/芯 4 字）会被静默洗掉，下次 make_font 生成的字体不再有这些字形；
- 后果不在本机、在**现场翻旧账**时：2026-09 那批历史自检/运行记录渲染成空白方块，无日志无
  报错，只能肉眼发现；字形不可再生，等于不可逆毁历史审计证据；
- 代价：约 35 字 × 27 B ≈ 1 KB RO。收益/代价不对称（同本目录"收益不抵风险"整簇暂缓的判据）。

诚实处理：这 35 字**逐字出处已不可靠复原**（能确认来源是落盘记录用字，指不到单条 commit）。
故按"成组 + 一条共同理由"登记，不给每个字编一条看起来可信的理由；删除前置条件写明（确认设备
上已无该窗口落盘记录，或产品侧接受历史记录部分空白），并把成因与事故路径实名写进门禁说明。

改动
- scripts/check_font_charset.py：KEEP_EXTRA 4 → 39 字（新增 _KEEP_HIST_SELFTEST 成组
  理由 + update 并入 35 字）；A 段按"必需字"处理，缺字即 GAP FAIL 并逐字打印理由
  （--strict 同样拦）
- docs/门禁说明/font-charset.md：新增 §6.1「按 extract 输出重写字符集 = 洗字形」（实测数字
  144/183/39、事故路径、机械化拦截点、删除前置条件）；§5/§6/§7 与变更记录联动
- .dsh/skills/font-regen/SKILL.md：第 2 步的保留字提示不再逐字列举（列举必然过期），改为指向
  KEEP_EXTRA 字典与门禁说明 §6.1——**共享基建文件，越界自加，见回报申报**

验证（本笔零代码、零像素、零体积，钩子全绿未跳）：
- check_font_charset.py：rc=0，打印 [KEEP] 刻意保留 39 个；--strict 亦 rc=0（原 35 项 WARN 归零）
- 钩子（staged 全量）：空白/EOF/乱码/doc-links/id-check/font-charset 全 Passed，体积两条
  钩子因无相关触发面自动 Skipped；@build 未跑（无源码改动，台账不受影响）
- 编码自查：三文件均无 BOM（与本目录现状一致）、CR = 0、U+FFFD = 0
 2026-10-25 14:44:44 +08:00
wandering1 42b47aa5ac chore(ledger): runpar 合入后回填台账/凭证/覆盖率并同步计数 
task/runpar-par 合入（merge 7bbcc9c）：卡10 运行参数段 [run_par] 9 键 +
104 映射 0x8030~0x804F + 死区真源收编 + SYS_EVT_RUN_PAR_SAVE 落盘链。
@build 0/0：Code=219,620 / RO=22,036 / RW=1,280 / ZI=132,864；
RW_IRAM1 76,720 B（58.6%）、CCM 87.9%。Flash +1,912 B、RAM +8 B 与
lane-d 申报一致，--no-verify 欠账清。meas.c 静态更名越界照准（同 TU
撞名 C2369 的最小修）。run_par.c 入覆盖率基线（39/39 套件）；钩子
45→46、单测钩子 21→22、总闸 38→39（AGENTS + 门禁 README）。
 2026-10-25 13:21:39 +08:00
wandering1 adeef7d21b chore(ledger): meas 与 n17 两笔合入后回填台账/凭证/覆盖率并同步计数 
task/meas-snap 合入（merge 9c2653c，meas 快照层，分支树冲突由 lead 并集
手工解：id_registry 三族 UIDATA/VOLSYNC/MEAS 共存，JSON 校验过；该合并
提交按 mem 域例外 --no-verify，理由=合并树 .map 滞后，回填本笔兑现）。
task/n17-probe 合入（merge 969fc5c，drop 路径异步化 Flash +16 B/RAM 0）。
合并后 @build 0/0：Code=217,828 / RO=21,600 / RW=1,264 / ZI=132,840；
RW_IRAM1 76,664 B（58.5%）、CCM 87.9% 不变。覆盖率 38/38 套件基线登记
（meas.c 入账）；凭证按最终 .map 重盖。计数：钩子 44→45、单测钩子
20→21、总闸 37→38 套（AGENTS + 门禁 README）。
 2026-10-25 10:37:05 +08:00
wandering1 b746a1ff00 chore(ledger): ui-data 合入后回填台账/凭证/覆盖率并同步门禁计数 
task/ui-data-feed 合入（merge 98664a1）：ui_data 三通道快照 +
ui_data_feed 装配 + ui_w_soe 显示名 + 字库 +4 字（采/样/恢/效，
179→183）。合并后 @build 0/0：Code=217,204 / RO=21,504 /
RW=1,256 / ZI=132,680；RW_IRAM1 76,512 B（58.4%）、CCM 87.9%。
lane-e 分支侧 --no-verify 欠账清；覆盖率基线登记 ui_data.c
（37/37 套件、tested 41）；凭证重盖（L0c 恢复序列）。
AGENTS/门禁 README 计数 42→44 钩、18→20 单测钩子（n22+ui-data 两笔带进来）。
 2026-10-25 10:07:15 +08:00
wandering1 13ef0715bb docs(销项): 批 1 登记簿收口 + A-5 口径联动到三处门禁文档 
销项（登记簿删行 + 结论沉淀指针）：
- 数据可信.md：卡 1~7 行删除，表下补销项记录（merge 231dc81/d39e5c9/
  59da40b）；§2.1 口径冲突注改 ✅ 已定死；§6 顺序图与失效预警改写为
  "批1 已销项 + 批2 在途"现状；卡 0/0b/12 与 M4①⑤台架面保留待跑
- 测试与架构专项.md：未闭环一览删 S12 / A-5 两行；§1 标题 1 项→0 项，
  P1-10 剩余两条改已销项记录（5 档构建 + f3 PASS，数字正文在
  test/board/ch395f_test.h）；§2.1 S12、§2.3 A-5 标题 ⬜→✅ 带落点
- README.md：一览删 P1 收步行；网络/结构/UI 行加 🟦批2 在途标记；
  测试基础设施 5→3；数据可信行改"在途 7 卡"；验证常态两处删
  P1-10/S12/A-5
口径联动（A-5 已落地，文档追平）：
- CI 远程CI完整指南.md §0.0 整节重写（盲区→同码凭证强制 + 三项仍
  守不住 + 变更记录行）；CI README 索引行同步
- 门禁说明/mem-numbers.md §1/§6、mem-budget.md §6 第 4 条：远端缺口
  已由 check_size_gate.py 关闭，唯一正文 = 其 docstring
 2026-10-25 08:36:44 +08:00
wandering1 db9f256fd0 docs(收口): 批 1 台架记录与门禁/产物分家口径落档（道C 文案兑现） 
- test/board/ch395f_test.h：f3 轮台架记录追加——VERDICT PASS，
  task stall 468→14（net 类 431→0，掩码复活实锤），余 13 条为
  netTask 自挂起前喂一次 vs 精确匹配判据的语义打架 + 1 条 uiTask
  瞬态 + 1 条设计内 P2 留痕；lead 裁决不放宽超集判定
- 主机单测覆盖率口径.md：中间产物路径 L80 与坑 12 重写为
  %TEMP%/dtu_host/<工作树哈希>/ 分家 + runs 独占（adabb6a 落地，
  旧固定共享名作废；判据正文指向 harness 顶部）
- 并行任务工作树方案.md §5 表：单测产物一行——不需要锁但必须
  按树分家（对照 build/bench 真独占）
- 门禁说明/cubemx-survival.md §6：新增第 7 条「基线漏项=静默不检」
  （net-msgq-adopt 实证，--write 后抽查新增条目）
- 门禁说明/id-check.md §5：拦下过真事追加——P1-10 注释裸编号被
  校验 6 拦（紧邻写法在 C 注释同样生效）
 2026-10-25 06:12:02 +08:00
wandering1 c4edf352fe refactor(UI): 记录页改注入式 reader，layer-deps 基线 6->3(道B task-6) 
B-6 分层收紧（UI_数据供给设计说明.md §7.2 契约原样落地）：
- ui_w_records：删 #include "sys_log.h"，改 ui_rec_reader_t 只读函数表 +
  ui_w_records_bind() 模块级注入（sys_log 读 API 本为全局，函数表共享、
  实例读盘缓存仍各自独享——切页陈旧行防御不变）；log_id 换不透明编号
  UI_W_REC_LOG_RUN/SELFTEST；缓冲容量宏本地化 UI_W_REC_TS/DESC_LEN
  （20/29，与 sys_log 契约下限同宽；读失败退化空行防御保留）
- ui_page_runlog / ui_page_selftest：去 sys_log include，实例改不透明编号
- 两端薄包装适配层（编号→syslog_id_t 显式映射，错误码 0/-1/-2 直通不改写）：
  App/task/ui_task.c 与 simulator/main.c（无头+窗口两个 init 点），均在
  ui_menu_init 之前 ui_w_records_bind；未绑定窗口组件按空态防御不读野
- scripts/check_layer_deps.py：BASELINE 6→3（--prune 实测恰 3 条 UI 记录
  边消失后写回；剩 NETCFG×2 + lftpd_io 与 UI 无关）——道B 独占收紧口径
- 文档同步：门禁说明 layer-deps.md §1/§6/§9 与 README 计数 6→3；
  UI_数据供给设计说明.md §7.2 加落地注记、§14"计划削减"改"已兑现"
- 首提被 id-check 拦下：注释/文档里自造"批卡编号"（B-6/道B-3）命中
  "未登记前缀"增量拦截——已全数改回 task-6/道B 普通指称（编号不回收、
  禁自造，教训入本提交）；id-check 复跑 RC=0（S10 告警为存量非本改动）

验证：
- 模拟器 0 警告；菜单 8 状态 + 内容页 11 页黄金参考逐字节 PASS
  （记录页数据流经 reader 后像素与基线一致，无基线更新提交）
- cppcheck/coding-standard/bsp-err/font-charset/no-mojibake 单跑全绿；
  layer-deps 复跑：6 处反向 include = 豁免 3 / 基线内 3 / 新增 0，
  --prune 显示"基线无需收紧（3 条存量全部仍成立）"
- doc-links --all 的 35 处告警全为本仓检出路径含空格误扫 SDL2 自带 md
  （环境问题、非本改动引入；提交门禁按暂存文件名过滤不受影响）
- @build 0 Error 0 Warning（终树复跑 BUILD_OK）；uvprojx 无 UV4 抖动、
  无新文件不涉注册；其余 38 钩全绿（ui-golden/font-charset/coding-standard/
  bsp-err/id-check/cppcheck…单跑复验 RC=0）

增量（A/B 同树 .map，基线 = 合入 c1b425d 后 HEAD）：
- Flash：Code +104 B、RO +8 B（两端薄包装代码 + reader 函数表 const）
- RAM：RW +4 B（s_reader 指针）/ ZI +4 B（两页实例 struct 枚举改 uint8
  本应 -8 B，链接段对齐后净 +4 B）；RW+ZI 合计 +8 B

gate: only mem-budget/mem-numbers pending lead ledger backfill
- pre-commit run --all-files 实测仅这两条失败（台账/RAM 文档 vs .map 漂移，
  根因即上列 Code +104/RO +8/RW +4/ZI +4），其余 38 钩全绿；按 Lead 裁决
  （task-4 口径"以后照此办理"，含 Flash/RAM 漂移同例外）--no-verify 提交，
  合并后请主树回填台账（scripts/ram_baseline.py --write 由 Lead 侧执行）
- 手工自查通过：5 个 BOM 文件 BOM=EF BB BF 齐全、docs/py/main.c 保持无 BOM，
  全部 10 文件 CR=0、U+FFFD=0
- 台账增量供回填：Flash Code +104 B、RO +8 B；RAM RW +4 B、ZI +4 B
 2026-10-25 05:21:05 +08:00
wandering1 15aa08552c docs(问题记录): 删除项目审查与优化建议报告，结论并入模块文档与编号规范 
用户裁定：该报告大部分内容已闭环，可删除；仍有价值的迁到合适文档。删前逐条核对，
确认绝大多数结论在仓内早已有权威副本（LV_DRAW_SW_COMPLEX / osFlagsNoClear / SPI 分频 8
/ 分层反向依赖存量基线等），只迁真正独有的四类内容：

1. 暂缓理由与重开条件（三条量化门槛）→ RAM 使用分析与优化方案 §4，并明确「本节是唯一
   权威」，其它文档只留指针；同时把 10 处指向报告 §5.3 的重开条件引用改指该节。
2. 2026-10-22「常驻 vs 动态」三项诊断（静态前五块 43,462 B = 58%；动态面只有 heap_4，
   故栈余量=CCM 余量；栈深主因是日志/配置写链）→ 同文档 §2.5。
3. `_fp_digits` 1,018 B 删不掉的机理与 F-6 根因修法（Q10 宏改单精度，−332 B，4.49e6 例
   逐位等价）→ §2.6.4。
4. 「UI 侧缓冲进 CCM」要按 DMA 可达性二分（LVGL 池可进，帧缓冲/推流缓冲不可）→ 暂缓清单。

编号侧（报告曾是 6 个族的属主登记处）：
- 原报告 §9 的 26 行「号 → 现在详述于」对照表迁到 docs/编号规范.md 新增 §4.5，6 族
  owner_docs 改指该节。规范正文含大量写法示例，直接当定义集会误伤，故 check_ids.py
  新增 `_def_owners`：snapshot_only 族剔除规范正文，只恢复可判定、不参与悬空/撞号/裸形
  /紧邻判定（实测若不分，裸形 S1 误报 238 条、S-3 与登记簿 S-3 误判重复定义）。
- 11 个已死号（N-03b/N-10~N-13/N-20/N-21/N-24/N-26/S-1/S-2）在 id_aliases.json 登记
  status=void 并写明去处——它们被约 110 处代码注释与文档引用，原先只靠「报告里顺带提过
  一句」才算有定义，报告一删就集体悬空。N-21/S-1/S-2 一号两义，注记已分别标明。
- 顺带修 id_aliases.json 的 note 被脚本累积重复 26 次；修 registry 里 3 处仍指向改名前的
  任务卡文件名（W1-采集保护收尾.md / W8-数据可信.md），以及 iec104_master.py 两处同类注释。

门禁：check_ids --strict 通过（可判定 8747/10410 = 84.02%，基线由 82.6% 抬到 84.0%）；
check_doc_links --all --sections-strict 通过（177 文档）；pre-commit 相关钩子全过。
 2026-10-25 02:08:58 +08:00
wandering1 2d7c4fd40b ci(gates): test-coverage 的触发面补上门禁自身，否则改坏 files: 就没人跑这根闸 
上一提交落地后立刻暴露这个口子：那次提交里新钩子显示 Skipped (no files to check)，
因为它自己的 files: 不含 .pre-commit-config.yaml —— 也就是说，任何人改坏这一行
正则（哪怕只是打错一个字符），这根闸就永久静默停用，而提交照样全绿。这正是
本仓反对的"会静默失效的门禁"，且已有先例处置：lv-conf-sync 与 bsp-err 都把
"门禁自身"写进触发面。

验证方式（不是只测绿的一半）：
- 改前：pre-commit run test-coverage --files .pre-commit-config.yaml → Skipped
- 改后：同一命令 → 实跑并 Passed（约 45 s，28 套）
代价：以后改门禁配置要多等 45 秒——这种提交本来就是低频操作，值。

顺带修两处上一批留下的表述：
- 口径 §8 的 YAML 块补同一个 files: 模式（保持与落库那份一致）。
- 该节抬头那句我上次写坏了：JS 里把续行写成独立表达式，导致"…README.md 里只挂
  一行索引指向本文"这半句被丢掉，句子断在文档名上。已补全。
- 门禁说明 host-unit-tests.md 的触发面描述同步为"含门禁自身"，并写明理由。

自查：doc-links --all --sections-strict 通过；改动文件 U+FFFD = 0、无 CRLF；
零代码改动故未跑 @build。未 push。
 2026-10-24 07:53:40 +08:00
wandering1 744a1cb086 ci(gates): 接线 test-coverage 覆盖率总闸（FAIL 语义），并修三处已成假话的门禁文档 
用户裁定 2026-10-24：缺 mscoverage 组件时**失败**，不做 skip。于是 P1 之后那个
"钩子只挂 16/28 套"的缺口关闭了。

为什么挂这一根而不是补 12 根 per-module 钩子：本闸跑**全部 28 套**，并且守
"已覆盖行只增不减"的基线台账。这是 per-module 钩子结构性做不到的——删掉一套
测试，它那根钩子只会因为"没有文件要检查"而静默跳过（Skipped 不等于失败）。
实测接线代价：45 s（28 套，含 28 次 MSVC 编译与插桩运行）。

FAIL 语义已按本仓"合成自证"的纪律验证（不是只测绿的那一半）：把
DTU_MS_COVERAGE 指到一个不存在的文件 → 钩子 Failed、脚本退出码 2、并打印可
执行的 [ENV] 提示（说明该 exe 装在哪、怎么覆盖）。脚本对显式环境变量刻意
"不做自动探测回退"，所以指错会被点名，而不是悄悄换一份工具跑出另一本账。

顺手修掉三条**现在已经不成立**的文档说法（门禁文档最贵的就是骗人）：
- 口径 §7 第 8 条：原写"只有 BuildTools 且没勾代码覆盖率工具的机器会退出码 2"。
  实测本机 Community 18.10 与 BuildTools 18.9 **两份安装都自带**该 exe（mtime
  2026-09-15 02:30 / 2026-09-05 16:17，都是各自安装当日，不是后来补勾）→ VS 18
  的 BuildTools 默认就带它。真实风险面只剩：裸 MSVC 无 VS 的机器、环境变量指错、
  以及靠 PATH 兜底的环境。
- 门禁说明 host-unit-tests.md 盲区第 4 条：原写"没有对应钩子的模块 = 零回归"——
  如今 12 套新模块由总闸兜住，这句话已经不成立，改成两种口径并写清触发面。
- 同篇第 6 条：原写"无覆盖率统计"。行/函数覆盖**已有**度量（本闸出 Cobertura 并
  守基线），仍无的只是分支覆盖——那是用户裁定 2026-10-23 记下的**已接受缺口**，
  不是待办，改口时把这个区分写清楚。

钩子计数同步（新增 1 根 → 声明 40 根 / pre-commit 阶段 39 根 + commit-msg 的
gitlint，已用脚本核对，不是手数）：AGENTS.md（总数、枚举、索引表）、
pre-commit使用说明.md（66 / 91 / 234 三处，含清点日期）、门禁说明 README
（正文与索引标题，另加一行索引指向口径文档——23 篇不变，同一事实不在两处维护）、
门禁说明 gitlint.md（--no-verify 跳过的"其它 38 个"→39）、并行任务工作树方案。

自查：end-of-file-fixer 与 trailing-whitespace 复跑 Passed（首轮 --all-files 只
因末行空行红过一次，已按钩子自身规范化）；doc-links --all --sections-strict 通过
（178 个文档）；id-check --strict 零台账外新账；8 个改动文件 U+FFFD = 0、无 CRLF。
零代码改动，故未跑 @build。未 push。
 2026-10-24 07:50:53 +08:00
wandering1 6505cef9df feat(门禁): coding-standard 加 CODE-RULE-20 禁 C 库堆分配（销 §4.8 空白 ②） 
规则：在**掩码后**的文本上匹配 malloc/calloc/realloc/strdup/strndup/
free/aligned_alloc 调用。三条判据都是踩过坑之后定的——
- 大小写敏感：pvPortMalloc / vPortFree（唯一允许的配对）不会误报；
- 词边界 \b：dhara_nand_is_free(、buf_alloc( 这类同形后缀不误报；
- 用掩码：注释与字符串字面量里写 malloc 不报（规范示例就踩过这种）。
覆盖名比 AGENTS 列的五枚多带上 strndup / aligned_alloc——同族同类，
漏一个就等于留后门。

出处不在规范 V1.0，在平台约束：MicroLIB 的 C 堆由 startup_stm32f407xx.s
的 Heap_Size EQU 0x200 只有 512 B，KB 级分配必返 NULL，而模拟器（宿主
CRT 堆）完全正常、**照不出来**——配置引擎 2026-09-18 那次堆分配纠偏与
lftpd 的 malloc 隐患都是**先上线才发现**的那类，靠评审等于没管。

落地前按 门禁说明/coding-standard.md §8 的纪律先全库普查：钩子范围内
C/H 共 151 个文件，命中**只有** simulator/sim/cfg_file_store_sim.c 两行，
即 cfg_store_alloc/cfg_store_free = **平台分配后端的宿主侧实现**（设计依据
写在 docs/子系统设计/配置文件设计说明.md 的"MCU 端 = pvPortMalloc、
模拟器端 = 宿主 CRT"）。所以零基线、直接硬拦截；豁免用脚本里的
HEAP_ALLOC_ALLOWLIST（**文件路径 + 函数名**双条件），刻意不做目录级豁免：
下次谁要碰 C 堆就得往这张表加一行，评审看得见。

自证：临时样例文件里 malloc/calloc/free 各报一处，pvPortMalloc/vPortFree/
buf_alloc(、注释、字符串五种陷阱形态全部不误报；
pre-commit run coding-standard --all-files → **Passed**（= 全库零存量）。

顺带修三处口径不一致：
- 规范 V1.0 §6.1 的示例自己写着 malloc/free（通用 C 模板遗留）→ 已在示例
  下加"本仓例外，别照抄"批注，事实源指向 AGENTS.md 平台约束；
- docs/门禁说明/mem-budget.md 里"这条纪律只靠 AGENTS 铁律与评审"已过期 →
  更正为由 CODE-RULE-20 机器拦截；
- AGENTS.md 平台约束条加"已机器拦截 + 唯一豁免"一句；scripts/README.md
  补登 check_test_coverage.py（上一个提交漏登记）。

另：本次一并修好上一处编辑事故——报告 §4.8 曾被我的脚本调用截成半句
（只落第一行、丢掉 malloc 那半句），已重写为"两处空白均已闭合"。

自查：pre-commit run --files（9 个改动文件）适用项全 Passed；
check_doc_links.py --all = 35 处，与主干同数（本分支贡献 0）；
check_ids.py --strict 通过（裸编号 P0-1 改平实说法，避免记成新账）；
9 个文件 BOM/CR/U+FFFD/行尾与 HEAD 逐项一致。本轮零 .c/.h 改动，未跑
@build、未占 build/bench 锁；分支已 rebase 到 v2-on-ui，覆盖率脚本全量
回归仍 16/16、line=2552/2893 不变。
 2026-10-23 23:44:46 +08:00
wandering1 6822726b2c docs(门禁说明): 手册 §2 收敛为通用机制与查号表，逐项详解归一到 23 篇 
用户一句"现在门禁都在干什么，我一概不知"引出的收尾。原手册 §2 有 27 个逐钩子小节，只回答
"拦了什么、怎么配"，回答不了"什么时候会骗我"；docs/门禁说明/ 已把逐项详解（含"限制与盲区"
一节）建好，本笔做收敛：同一事实只留一处（docs/文档规范.md 的要求）。

**先搬后删**（否则收敛等于丢事实）：旧 §2 里独有条目逐篇折回，共 18 处插入、15 篇受益。折回的
东西包括：六套主机单测的来历与用例规模（13/36/82/46/32/149 断言，含 nand-port 的"与旧算法
对照"）与"改动公共骨架 unit_test_harness.py 会同时触发 16 个钩子"；UI 页面**两层注册**（构建
注册 vs 框架注册：枚举 + s_defs[] 描述符表）与"豁免不整目录一刀切"；lv-conf-sync 首次落地清掉
26 个 LVGL 9.3 不存在的选项、3 处重复定义、10 项隐式开关显式化，以及 ALLOW_DIFF 端专属白名单
与必须穿过 lv_conf_internal.h 里那层 KCONFIG 包裹；cubemx-survival 的 16 项清单、断言前先剥
C 注释（本仓注释刻意引用历史代码，不剥就恒定误报）、旧手册"自造标记区"建议与看门狗文档实测
教训之间的优先级；id-check 顺带收编 check_test_traceability.py、裸形同字母多义属**显式承认的
盲区**、--update-baseline 只许涨；layer-deps 的注入自证与报错时三条修法（注入回调 / 上层递数据
/ 才谈 ALLOW）；coding-standard **nand_ftl.* 也在排除清单**（我先前那篇漏了）；test-suite-switch
的剥注释判定与派生宏白名单；mem-budget 两类软提醒不拦、退出码 2 是解析失败不是通过；doc-links
的排除目录与状态词 ±40 字符距离；task-table 改栈三步；gitlint 报错样例；no-mojibake 的修复路径。

**顺带抓到旧文档两处错**（记进文档，不悄悄改）：一是 check-added-large-files 的阈值旧手册写
"单个文件 > 1MB"，按本机安装的钩子源码实测是 --maxkb 默认 **500**（500 KB）——已更正，并把
"本目录任何默认值都以实测或安装的钩子源码为准"写进 end-of-file-fixer 当反面教材；二是
**ui-golden 在旧手册里连小节都没有**，只活在配置注释里：除了"有基线不等于有门禁"，这是另一种
失踪——有钩子、没文档。

手册 §2 改写为三节：迁移说明 / **旧编号 → 新文档 查号表**（历史引用靠它读，旧号按"冻结历史不
回改"保留）/ **跨钩子通用机制**：两阶段与换机必须重装 hooks 才带 commit-msg、stash 陷阱、
always: true 已废、改写型与只读型豁免不对称、增量拦截三段式且刻意没有 --write、没有 .map 是
"跳过"不是"通过"、改配置的验收是看目标钩子出现在输出里且不是 Skipped、新增门禁三步必须做
注入自证且"限制与盲区"不许留空，另有快速自查入口。手册 707 行 → 273 行。

引用**按内容**重指（只核编号存在与否不够，同号小节会被当本文自引用静默放过）：编号规范、
scripts/README（顺带更正那里过时的 warn-only 说法，早已关闸为增量拦截）、RAM 使用分析与优化
方案、测试开发标准流程、lvgl-simulator skill、AGENTS 文档表（拆成"每门禁一篇详解"与"通用
机制"两行）、.pre-commit-config.yaml 头注释、docs/README.md 描述、手册自身 §5.5 与 §6 的两处
内部引用。另：表格里的裸节号会被 doc-links 判成本文自引用，查号表统一写成不带 § 的形态。

写说明过程又被自家门禁拦一次：gitlint 篇里引用报错样例时写了两个规则号字面量，被判形态不合规
→ 改成中文描述，没有往台账里塞 reason 解决。

验证：纯文档与注释改动，不动代码，Program Size 不变，故不跑 @build/@test；
check_doc_links --all --sections-strict **171 篇 0 问题**；id-check 增量拦截通过；
pre-commit run **RC=0 / 13 项 Passed**；28 个改动文件字节卫生 **0 异常**（无 BOM、无 CR、
无 U+FFFD、均 LF、无行尾空白）。
 2026-10-23 11:44:21 +08:00
wandering1 871ace422b docs(门禁说明): 统一第八节标题措辞，新增模块单测的入口写在标题上 2026-10-23 10:55:34 +08:00
wandering1 dc44c1e54e docs(门禁说明): 补齐 23 篇逐项门禁文档，每种门禁一篇含限制与盲区 
用户诉求原话："现在门禁都在干什么，我一概不知。" 原有文档回答"有哪些钩子、怎么配"，回答不了
"这一条到底在拦什么、什么时候会骗我"。本目录按**每种门禁一篇**补齐 23 篇（39 个 hook id 全覆盖：
16 个主机单测是同机制 16 实例合一篇；cppcheck 与 test-cppcheck 是同工具两套范围合一篇），
文件名用 hook id，与提交输出里的名字一致、可 grep。

八段固定结构：查什么 / 为什么要它（拦下过什么真事）/ 触发面 / 报错怎么读 / 好处 /
**限制与盲区** / 豁免与基线口径 / 改门禁本身要注意什么。最后一节是这批文档存在的理由——
只看"拦了什么"的文档会让人以为绿就是对的；本仓三个增量拦截门禁（layer-deps 6 条、bsp-err 38 条、
id-check 台账 640 处）的绿灯含义只是"没比上次更差"。README 另立"三种拦截姿态"一节：改写型 /
硬拦截 / 增量拦截，分清才知道报错时该改代码还是该还基线。

有实证的地方全部带数字，没实证的地方直接写"预防性、未记录到实际拦截案例"（不编故事）：
· cppcheck：把 simulator/ 纳入受检后立刻揪出 sim_syslog.c 真实空指针；test/ 曾有 s_rx_buf
  使用先于声明；**并记入两条实测负结果**——它对 14 处丢弃 HAL_SPI_* 返回值与"未初始化局部量
  进 P_FAIL 判定"一条不报（这正是 consume-result 的由来）。
· lv-conf-sync：漂移导致 64,576 B 死代码入库（旧镜像的 23.5%），且 golden 跑的是模拟器那份配置。
· cubemx-survival：2026-09-29 一次重生成覆盖 4 处定制（P0×1+P1×2+P2×1），且不报编译错。
· registration-check：rs485_task.c、lftpd_log.c 两处都没注册 = 从不参与编译的死代码；第四类
  "页面描述了但没接进 s_defs[] 表"编译链接全过，前三类完全照不出。
· test-suite-switch：实测已提交的 HEAD 里 TEST_SUITE_CH395F 就是开着的，.map 含 34 处 test 代码。
· task-table：2026-09 两张表都比源码落后一大截（写 2048/4096/…/16384，实际 1024…512）。
· mem-numbers：2026-09-26 复核，文档写 82,048 B / 62.6%，实际 87,040 B / 66.4%；Flash 写
  249,432 / 23.8%，实际 261,932 / 25.0%。
· ui-golden：注入 .top_y +3 像素 → golden FAIL 点名"1366 px 差异"、退出码 1；并把"有基线
  ≠ 有门禁"与"逼人 --no-verify 的门禁等于没有门禁"两条选型依据写进去。
· check-yaml：本仓已移除的 always 键只告警 Unexpected key(s) 然后忽略——配置"看起来生效其实没
  生效"而本门全绿，所以验收方式是实跑看目标钩子是 Passed 还是 Skipped。
· no-mojibake：types: [c] 只管 C/H，**文档侧乱码无人管**——覆盖面与需求错配定性写进限制一节。

盲区写法示例（每篇都要求写真实限度，不留空）：layer-deps 只查直接 include、按 basename 匹配、
不查是否真的用到；font-charset 管不到运行期拼出来的字符串与配置文件里的字；host-unit-tests 用宿主
编译器、桩是第二份真相、include_dirs 手写、没有对应钩子的模块等于零回归；mem-budget 的 92% 是管理
阈值不是安全余量、.map 缺失即"通过式跳过"；registration-check 不看条件编译与注册指向是否正确；
coding-standard 的 CODE-RULE-17 在无配对头时跳过、规则编号 14 作废不回收。

写文档过程自己被自家门禁拦了两轮，都按规矩改而不是绕过：
① doc-links 拦下我自己——我在解释"写 §数字 而没紧邻文档名会被判成本文自引用"这段话里，正好
   就犯了这个写法（两处），另有一处示例输出未标记；改成正例写法 + [示例] 标记。
② id-check 拦下 7 类新账：示例报错行里的号、档号引用未紧邻文档名、说明"裸形不合规"时自己写了
   裸形。全部改成平实描述或补文档名、给样例加 [示例]，没有一条是往台账里塞 reason 解决的。
这两次本身已写进相关篇目的"限制/变更记录"，是这套文档最实在的注脚。

同步：手册 pre-commit使用说明.md 的 §2 顶部加指针（逐项详解已迁往本目录；两处收敛为"通用机制 +
总览 + 指针"排在 docs/门禁说明/README.md §4 的下一步，并注明收敛要按内容重指既有引用——只核编号
存在与否不够）；README 索引 23 行状态全部置为已写、文档列改为可达链接。

验证：纯文档，不动代码与构建产物；check_doc_links --all --sections-strict **171 篇 0 问题**
（新目录 24 个文件的内部链接与跨文档引用都纳入判定）；id-check --strict 增量拦截通过；本次受影响
文件 pre-commit run **RC=0**；24 个文件字节卫生 0 异常（无 BOM、无 CR、无 U+FFFD、均有尾换行）。
 2026-10-23 10:54:33 +08:00
wandering1 3488617bc9 docs(门禁说明): 新建逐项门禁文档目录，先落索引 README 与 bsp-err 首篇 
用户的原话是："现在门禁都在干什么，我一概不知。" 现有文档只回答"有哪些钩子、怎么配"
（docs/代码规范/pre-commit使用说明.md），回答不了"这一条到底在拦什么、什么时候会骗我"。
故新开一个目录，**每种门禁一篇**，八段固定结构：查什么 / 为什么要它（拦下过什么真事）/
触发面 / 报错怎么读 / 好处 / **限制与盲区** / 豁免与基线口径 / 改门禁本身要注意什么。

**最后一节是这批文档存在的理由**：只看"拦了什么"的门禁文档会让人以为绿就是对的。而本仓
三个增量拦截门禁（layer-deps 6 条、bsp-err 38 条、id-check 台账 640 处）的绿灯含义只是
"没有比上次更差"。

索引按 39 个 hook → 23 篇规划（16 个主机单测是同机制 16 实例，合一篇；cppcheck 与
test-cppcheck 是同工具两套范围，合一篇），文件直接用 hook id 命名，与提交输出里的名字
一致、可 grep。README 另有一节"三种拦截姿态"——改写型 / 硬拦截 / 增量拦截——分清这三类，
报错时才知道该改代码、还是该还基线。钩子清单、files 范围、pass_filenames 全部从
.pre-commit-config.yaml 实测解析（39 个 id：官方 5 + gitlint + local 33），不是手抄。

本次交付：索引 README + 首篇 bsp-err.md。首篇里把今天踩过的坑全写进"限制与盲区"，共 10 条，
例如：只扫 Drivers/BSP（App 层同类问题仍无人管）；consume-result 只认单行整句的裸调用，
跨行写的调用按正则形状测不到；must-use 名单靠"返回类型 + 注释关键词"启发式，注释不写
"错误码/失败"就漏、改名就能绕开规则；HAL 族是固定清单，清单外的返回 HAL 状态的函数不在
名单里；return-doc 的判据是"注释块里出现『返回值』字样"，**散文里出现这三个字也会放行**
（本仓真发生过两条靠函数说明里的关键词误判通过）；基线键带出现序号，--prune 只报"消失"、
不会报告某处只是搬了家；改标签名等于改基线键，必须原子完成。在册数量与构成按当前基线
逐条数出来写（38 = consume-result 37：gd5f2gq5ue.c 28 含 14 处 HAL 丢弃 + 14 处自家原语、
ui_net_sink.c 6 全为 net_close、rs485.c 2、nand_ftl.c 1；err-type 1 为 bool
ui_content_page_open()）。

同步指向：AGENTS.md 提交门禁一节改为"每种门禁一篇详解 → docs/门禁说明/README.md"，通用
机制仍指 pre-commit使用说明.md；docs/README.md §7.1 增加索引行；.pre-commit-config.yaml 的
bsp-err 注释块顺手更正（原文还写着"三条规则""现 1 条""只能靠书写约定兜着"，均已过时）。
迁移状态用索引表的"状态"列跟踪；全部写完后 pre-commit使用说明.md §2 收敛为通用机制 +
总览，同一事实只留一处（docs/文档规范.md 的要求）。

验证：纯文档与注释改动，未触碰构建产物；check_doc_links --all --sections-strict 149 篇
0 问题（新目录的相对链接、跨文档章节引用都能判定）；bsp-err 仍 38/38/0；本次受影响文件的
pre-commit 全绿 RC=0；两份新文档字节卫生 ok（无 BOM、无 CR、无 U+FFFD、有尾换行）。
 2026-10-23 09:48:26 +08:00