STM32F4-Base/.dsh/skills/stale-doc-count-sweep/SKILL.md

name, description, whenToUse

name	description	whenToUse
stale-doc-count-sweep	全仓陈旧计数同步 playbook——某个事实数（黄金参考页数/张数、菜单树叶数与已绑叶数、字库字数与字形数、提交钩子数等）变了之后：每个数先剔伪命中再双源互证定真值 → 全形态全命中面扫描（含 .pre-commit 钩子显示名与 .dsh/skills 正文）→ 逐条分类（当前态改 / 历史行冻结（只有保留变更记录的 5 篇真台账与 scripts/archive/ 归档） / 同数不同义不动 / 带日期戳的测量只加「当时」/ 数字对但口径描述错另起一笔）→ 每处先读现文再字面替换并断言命中数 → 全文通读核对各小节 → 提交后再按全部旧形态复扫归零 → 跑门禁分笔提交。	某个计数/数字变了要跨 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。动手前先读那篇。

Pitfalls

• 把伪命中计进真值
• 字形数没剔 notdef
• 数字对但口径描述错
• 权威脚本乱码就臆读或退回抄文档
• 钩子数用 grep 声明行
• 张数与页数互相冒充
• 只扫 docs/
• 提交完就收工
• 去已删掉变更记录的文档里「补一行流水」
• 历史行被当陈旧值改掉
• 照抄用户给的数
• 把节点行当叶子数
• 整文件正则批处理
• 反引号截断
• 只改记得的那节
• 误报跟着改
• 带日期戳的测量臆改新数
• 用截断的 grep 输出判定
• 新写文本撞编号门禁

本节全文（逐字搬移、未改写，含命令与实测数字）→ 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 号 + 每笔改了哪些文件 + 没动的那几类及理由