refactor(docs): point entry-file references at their new homes

AGENTS.md stopped being the store of record for build steps, Python env,
hardware pins, doc conventions, log cost and task ownership. Those facts
already live in docs, skills and role files; the entry file now only
points at them. This commit moves every reference that used to name the
entry file to the authoritative landing point, so a reader who follows a
link arrives at the fact instead of at a sentence that no longer exists.

What changed is links and prose, not behaviour. Code, scripts and tests
only have comment and docstring lines touched; the only non-comment edit
in the whole changeset is one note string inside the generated pin table
JSON, and its generator was changed in the same step so the two stay
byte-identical.

New landing points created before the references were retargeted:
- The console single-writer log design doc, section 7.1, is now the single
  authority for log cost: about 90 B flash and 216 B stack per DBG_ line,
  and the rule that deep call chains must predefine DBG_LINE_BUF_MAX.
  It also carries the full list of the twelve translation units that have
  tightened it, plus the grep command that decides the truth if the list
  and the code ever disagree.
- The document writing standard, section 2, now holds the BOM list.
- keil-build skill gains an exit code table: 0 success, 1 build failure,
  2 BuildEnvError, 3 usage, 4 build lock held. This corrects a belief
  that was never actually written down anywhere: exit 2 does not simply
  mean environment error, argparse also exits 2 and the wrapper script
  was remapped so the two no longer collide.

Regenerated and checked byte for byte:
- The end-to-end architecture SVG in docs/images from its generator.
- tools/netlist_semantics/pinout_kb.json from gen_kb.py.
Both are idempotent; running the generators again produces no diff.

Deliberately not touched, because machines read them:
- scripts/check_bom_drift.py joins every line containing BOM and asserts
  four paths are present, so the entry file BOM line must stay one line.
- scripts/gen_task_table.py reads the TASK_TABLE anchors directly.
- scripts/rename_maps and scripts/archive keep their historical wording;
  they describe what happened, not what is true now.

Verified: doc links report the same six pre-existing findings as the base
commit and no new ones, generated-fresh passes, bom drift is clean across
101 files, and AGENTS.md itself is unchanged in this commit.
This commit is contained in:
2026-11-16 19:38:27 +08:00
parent ab20302999
commit e4981aa2f6
134 changed files with 276 additions and 212 deletions
+1 -1
View File
@@ -3246,7 +3246,7 @@
"N-03b": {
"to": null,
"status": "void",
"note": "报告 N-03b(IWDG / `configASSERT` / 两个钩子 / 4 个 Fault 现场)——属主文档 docs/问题记录/项目审查与优化建议报告.md 已于 2026-10-25 删除。现行去处:docs/子系统设计/看门狗设计说明.md §4.4、§10.1/§10.2 + AGENTS.md「平台约束」"
"note": "报告 N-03b(IWDG / `configASSERT` / 两个钩子 / 4 个 Fault 现场)——属主文档 docs/问题记录/项目审查与优化建议报告.md 已于 2026-10-25 删除。现行去处:docs/子系统设计/看门狗设计说明.md §4.4、§10.1/§10.2"
},
"N-10": {
"to": null,
+1 -1
View File
@@ -927,7 +927,7 @@
"审查"
],
"collides_with": "N",
"cursor_note": "⚠ 与登记簿 N-x 同名不同义(§4.3 / AGENTS.md 模块约定)→ 引用必须紧邻「报告」或报告文档名",
"cursor_note": "⚠ 与登记簿 N-x 同名不同义(§4.3 / 网络模块约定)→ 引用必须紧邻「报告」或报告文档名",
"snapshot_only": true,
"snapshot_note": "§4.3 冻结历史快照:只在引用写了文档名(紧邻线索)时参与定族,不参与「定义位优先」——避免同号把活登记处接管走",
"owner_note": "属主文档 docs/问题记录/项目审查与优化建议报告.md 已于 2026-10-25 删除(用户裁定:内容大部分已闭环);登记职责与 26 行「号 → 现在详述于」对照表迁到 编号规范.md §4.5,故 owner_docs 指向该节——它只用于**恢复可判定比例**(§4.5 是冻结存档登记处),定义集仍为空(snapshot_only 族剔除规范正文,见 check_ids.py 的 _def_owners),因此不参与悬空/撞号/裸形判定。未闭环项早已并轨到登记簿 N-19~N-29 + U 簇"
+1 -1
View File
@@ -3,7 +3,7 @@
模块名称:BOM 漂移检查(提交门禁 bom-guard 的实现)
模块功能:对给定文件集合(默认 = pre-commit 传进来的本次所改文件)逐个比较 HEAD 版本与工作区
版本的前 3 字节:HEAD 有 UTF-8 BOM(EF BB BF)而工作区没有 → FAIL 并列出补救动作。
为什么要这条:AGENTS 铁律第 2 条记载的实测坑——编辑工具会**静默剥掉**文件原有 BOM,ARMCC
为什么要这条:编码铁律记载的实测坑(口径 → docs/文档规范.md §2)——编辑工具会**静默剥掉**文件原有 BOM,ARMCC
于是按 CP936 解码带中文的源文件,报出 #870-D / #8 / #274 一类**假语法错**(错的位置
和内容都不指向真因);MSVC(模拟器侧)与任何"只跑编译"的门禁都不覆盖这一步,历史
"0 警告"不代表安全。2026-10-25 一天之内道E 一个任务踩了 4 次、道B 批 1 踩过 1 次,
+3 -3
View File
@@ -42,7 +42,7 @@ C_KEYWORDS = {'if', 'for', 'while', 'switch', 'do', 'else', 'return',
NAME_PAREN_RE = re.compile(r'([A-Za-z_][A-Za-z0-9_]*)\s*\(')
# CODE-RULE-20 的例外:平台分配后端的**宿主侧实现**(AGENTS.md「只用 pvPortMalloc/vPortFree,
# CODE-RULE-20 的例外:平台分配后端的**宿主侧实现**(口径「只用 pvPortMalloc/vPortFree,
# 或把分配收进平台后端」说的就是这种收口点)。只点名到文件 + 只放行这两个函数名,
# 不做目录级豁免——新增一个想 malloc 的文件必须显式加进这里,评审时看得见。
HEAP_ALLOC_ALLOWLIST = {
@@ -291,14 +291,14 @@ def check_file(path):
# CODE-RULE-19 (4.4.2) 函数定义左大括号必须与右括号同行
# CODE-RULE-20 (平台约束,2026-10-23) 禁止 C 库堆分配
# 出处**不在规范 V1.0**(其 §6.1 示例本身就写着 malloc/free,属通用 C 模板遗留,已同日在示例
# 下方加"本仓禁止"批注),而在 AGENTS.md「平台约束」+ docs/内存管理/RAM使用分析与优化方案.md:
# 下方加"本仓禁止"批注),而在本脚本的 FORBIDDEN 名单 + docs/内存管理/RAM使用分析与优化方案.md:
# MicroLIB 的 C 堆由 startup_stm32f407xx.s 的 Heap_Size EQU 0x200 限定为 **512 B**,KB 级分配
# 必然返回 NULL,而**模拟器(宿主 CRT 堆)完全正常、照不出来** —— 典型"只有真机才炸",必须机器拦。
# 判据细节(三条都是踩过坑之后定的):
# - 大小写敏感:pvPortMalloc / vPortFree(唯一允许的配对)不会中招;
# - 词边界 \b:dhara_nand_is_free(、buf_alloc( 这类"同形后缀"的自有函数名不会误报;
# - 跑在 masked 上:注释与字符串字面量里提到 malloc 不报(规范示例就是这种命中)。
# 覆盖名比 AGENTS 列的五枚多带上 strndup / aligned_alloc —— 同族同类,漏一个就等于留个后门。
# 覆盖名比口径列的五枚多带上 strndup / aligned_alloc —— 同族同类,漏一个就等于留个后门。
norm = path.replace('\\', '/')
allow = frozenset()
for suffix, names in HEAP_ALLOC_ALLOWLIST.items():
+1 -1
View File
@@ -30,7 +30,7 @@ CubeMX 重生成存活审计(check_cubemx_survival.py)
退出码:0 = 通过;1 = 有 FAIL 项。
设计依据:docs/子系统设计/看门狗设计说明.md §10.2/§10.3;AGENTS.md「平台约束」。
设计依据:docs/子系统设计/看门狗设计说明.md §10.2/§10.3;docs/门禁说明/cubemx-survival.md。
注意
----
+1 -1
View File
@@ -254,7 +254,7 @@ def report_no_interpreter(table):
q = chr(39)
print(" 修法(任一,改完直接重跑本脚本自检):")
print(" 1) 显式指定:PowerShell 里 $env:DTU_GEN_PYTHON = " + q + venv + q)
print(" 2) 重建仓库虚拟环境(口径 AGENTS.md「Python 环境」):")
print(" 2) 重建仓库虚拟环境(口径见 new-machine-setup skill):")
print(" & <本机任一 python ≥3.10> -m venv .venv ; & " + q + venv + q
+ " -m pip install -r requirements.txt")
print(" ⚠ 这一项刻意**不 SKIP**:解释器或依赖坏了必须响,静默跳过等于造一根会假绿的闸")
+1 -1
View File
@@ -4,7 +4,7 @@
背景(2026-10-22 加)
----------------
AGENTS.md 与 docs/架构设计/项目架构总览.md 都写着"六层单向依赖:业务 → UI/基础服务
docs/架构设计/项目架构总览.md §1 与 §2 写着"六层单向依赖:业务 → UI/基础服务
→ 中间件 → BSP 驱动 → HAL/RTOS → 硬件",但**此前没有任何机械检查**:Drivers/BSP/ 里
可以随手 include "cfg_file.h" 而无人报警。后果是可测量的口径漂移——2026-09 审查报告
记"NETCFG 一处",2026-10-22 实测已长到 8 个文件 9 处。边界的静默腐蚀只能靠门禁止住:
+2 -2
View File
@@ -51,7 +51,7 @@
原始字节——本仓 core.autocrlf=true 而 .gitattributes 写死 eol=lf,实测主树 1046/1388
个受管源码落成 CRLF、新建工作树同一提交落成 LF,而索引 blob 完全一致;按原始字节算
会让同一份代码在不同 checkout 得到不同指纹(主树盖的戳在别人工作树与 runner 上误红)
→ 索引 blob 才是跨 checkout 稳定的身份,也是 AGENTS「不依赖 core.autocrlf」的机器化。
→ 索引 blob 才是跨 checkout 稳定的身份,也是「不依赖 core.autocrlf」口径的机器化(→ docs/文档规范.md §2)。
推论:**未 staged 的改动不在索引里**,凭证覆盖不到 → --stamp 拒绝在有脏时盖章,
--local/--ci 也把它单独报出来(已 git add 的不算脏:索引已含其内容,正是要测的那份)。
@@ -121,7 +121,7 @@ def index_snapshot():
完全相同**(实测 dbg_cfg.h:1247 B/LF vs 1293 B/CRLF,blob 都是 c39395f7)。
拿原始字节算指纹 = 同一份代码在不同 checkout 得到不同指纹:主树盖的戳在道C
新工作树里判"不同码",runner 上同样会误红——**门禁自己造 false positive**。
索引 blob 是 git 归一化后的身份,跨 checkout 稳定,也正是 AGENTS「行尾由
索引 blob 是 git 归一化后的身份,跨 checkout 稳定,也正是「行尾由
.gitattributes 写死、不依赖 core.autocrlf」的机器化说法。
"""
raw = _git(["ls-files", "-s", "-z"])
+2 -2
View File
@@ -10,7 +10,7 @@
(measured 2026-10-12: master 18 defined / 17 reported, v2-on-ui 26 / 25).
The missing one is `gitlint`: its hook definition declares
`stages: [commit-msg]`, while `pre-commit run --all-files` only runs the
`pre-commit` stage. So the commit-message rule from AGENTS.md (title
`pre-commit` stage. So the commit-message rule (title
< 100 chars, body lines <= 80) was enforced on developer machines and
NEVER in CI -- a silent gate gap, not a failure.
@@ -198,7 +198,7 @@ try {
exit 2
}
if ($failed -gt 0) {
Write-Host '::error::commit message gate failed -- see the gitlint output above for the exact rule id (rules in .gitlint; AGENTS.md: title <= 100 chars, body lines <= 80)'
Write-Host '::error::commit message gate failed -- see the gitlint output above for the exact rule id (rules in .gitlint; title <= 100 chars, body lines <= 80)'
exit 1
}
exit 0