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」同族：手跑的探针不能替真提交的探针作证。

.pre-commit-config.yaml

@@ -791,3 +791,28 @@ 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
+      #       条，把整批真警告挤到看不见）。有了这根，提交时就报，不用等 @build。
+      #     接线当日实证（冻结引用，别去翻构建日志——它每次 @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]