### 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 覆盖面」。