Commit Graph

6 Commits

Author SHA1 Message Date
wandering1 e4981aa2f6 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.
2026-11-16 19:38:27 +08:00
wandering1 1634088bd7 docs(screenlink): 屏板链路档去「说明」并瘦身,控制台档收编台架日志口
屏板链路设计说明.md -> 屏板链路设计.md(去档名「说明」,与 ADC 节拍 /
运行与自检记录两篇口径一致);控制台单写者日志设计说明.md 同改。
两档并存期间旧名引用 0 残留。

- 屏板链路 §3.2 台架日志口(RS232#1 / CN1 端子 / COM3)移入控制台档
  §3.4:日志口的接线属 UART5 控制台通道,不属屏板链路;屏板档只留
  「别去 CN1 找 USART1 端子」这句接线防错提示。
- 屏板链路 §7.1 由「根因账本 + 修复前后对比」改写为现状描述:延迟
  应答机制表 + 耗时分解表 + 两个计数口径 + 已知边界,40 行压到 24 行。
  顺带修正 §8 的错引:原指 `网络自愈架构设计.md` §8(实为「延后项」,
  不含 uiTask 内容)改为 §4.1 `net_reconcile_tick`。
- §9.1 增补长稳行(串口日志 2026-11-13 18:31 -> 2026-11-15 21:43,
  单次上电 51.2 h:rx=658262 ok=658262、crc/len/fmt/err 全 0、
  drop=7 仅启动期、kerr/abor/bad=0、全程 off=0);§9.2 销项三条
  (仪器项、2 h 长稳、len=7 观察项),新增「按键通路」一条——51.2 h
  日志 keys=0 kq=0 dfok=0 dfold=0,延迟应答在真机上从未执行过。
- 删除 sb_frame_b_build_logo() 及 SB_LOGO_MAGIC_* / SB_SCREEN_W/H
  与对应单测(TC-SBPROTO-022/023 全组、024c/024d),组帧入口只剩
  sb_frame_b_build_image()。sb_proto 单测 59 -> 45 条,45/45 通过。
- cfg_file.c 出厂模板三条中文字面量改 \uXXXX 转义:消除全量重编时的
  4 条 #870-D invalid multibyte character sequence,运行期字节不变,
  源码回到纯 ASCII(符合「字符串字面量必须纯 ASCII」)。

验证:keil-build 0 Error 0 Warning;sb_proto 45/45、sb_link 164/164;
pre-commit 48 钩子全 Passed;check_doc_links --sections-strict 通过。
2026-11-15 21:51:24 +08:00
wandering1 f5902bcc21 docs(design): 运行/自检记录与 ADC 节拍两篇改为现状设计并去掉档名"说明"
两篇规划期文档改成对当前系统的描述,档名统一去掉"设计说明"的"说明"。

运行与自检记录:
- 旧档重写为现状版(10 节:概览 / 记录布局 / 写入路径 / 读取与呈现 /
  事件分类 / 控制台日志 / 双端差异 / 内存 / 异常恢复 / 自测要点),
  删掉需求表、调研摘要、模块清单动作列、实施步骤与开放问题。
- 按代码纠正:七类记录齐备(原文只写了两类)、自检描述串换成实际
  落盘的 28 条、待机阈值以 ui_tokens.h 为准、记录页已走 ui_w_records
  共享组件、容量满只删该文件而非整卷清空。
- 待机屏移出本篇:它不属于日志,归 UI 侧;内容页架构补"待机屏
  (覆盖层)"一节,产品需求 FR-LOG-3 拆成单纯的上电/重启分类,
  待机显示归口已有的 FR-UI-3。

ADC 采样节拍:
- §4.5 从 45 行压到 24 行,只留规则 / 违反的代价 / 为什么 / 兜底与
  档案指针;九路置换实测表、A/B 对照、探针计数等取证归
  ADC_Trap_Records.md 的 TRAP-ADC-01(那里已有完整档案)。
- adc1_gap 字段去掉"2026-10-21 起、此前固件为次数"的修订记录式括号。
- app_main.c 的注释改为指向 TRAP-ADC-01 取证、§4.5 设计口径。

引用同步:两个旧档名全仓替换(含代码注释、角色档、归档 id 表),
旧名残留 0;对 ADC 篇的 § 引用逐条复核落在真实章节上。

验证:48 个提交期钩子全通过,check_doc_links --sections-strict 通过。
2026-11-15 21:30:07 +08:00
wandering1 ad87f979b1 docs(规约): 删除编号规范.md,生效规则并入文档规范 §7.1
用户裁定:docs/编号规范.md 在项目里已无意义,删除。

依据:该文 253 行里真正仍生效的只有两条规则(新条目一律不发编号、
人读文档存量编号继续清退)和一张存量族表;其余内容早有归属——两道
编号门禁的退役记录在 docs/门禁说明/id-check.md 与 id-check-new.md,
手工普查与恢复机器面在 scripts/archive/id_gate/README.md。留着就是
第二真相源,同一事实写在两处迟早漂移。

处理:
- docs/文档规范.md 新增 §7.1「条目与编号:一律不发」,承接规则、
  场景表、三条硬规矩、存量族表、已停发旧号族清单、不是编号的清单、
  清理动作与「没有机器门禁兜底」四段。
- 活跃引用 62 处逐条改指 §7.1 或归档 README:AGENTS.md 2 处、
  门禁说明三篇 18 处、其余文档 11 篇、代码与脚本 10 处、rename_maps
  七个 record 字段、.dsh/skills 四个文件 8 处。
- 归档区 107 处去掉 docs/ 前缀当纯文本提及;编号治理历史.md 45 处
  改为「原编号规范 §N」,避免被 doc-links 当自引用解析。
- 顺带修正 scripts/archive/id_gate/README.md 里仍称旧文为现行规范
  的表述。

门禁:check_doc_links --all --sections-strict 220 篇全通过、无法判定 0;
pre-commit 全 Passed。
2026-11-06 18:32:04 +08:00
wandering1 f754d59218 docs(测试说明): 按用途分六个子目录并同步全库引用
分层:流程与规范/ 单元测试/ 板级测试/ 专项验证/ 测试工具/ 测试数据/,
顶层只留新增的目录导航 README.md(归层判据 + 硬约束 + 本次处置记录)。

- 搬迁 28 个路径:测试数据三个目录 58 个文件为纯改名(R100,内容逐字节不变)
- 全库引用同步 124 个文件:AGENTS / docs 索引 / skills / 门禁注释 / scripts
- 门禁面:scripts/check_test_traceability.py 的 glob 改 rglob
  (分层后不递归扫描=追溯门禁直接瞎掉)
- scripts/rename_ref.py:收尾的 ℹ 提示在 GBK 代码页抛 UnicodeEncodeError,
  让进程以退出码 1 收场而改写其实已落盘(RC 与真实结果相反);改为把
  stdout/stderr reconfigure 成 UTF-8,与 check_doc_links.py 等同法
- docs/文档规范.md §1.1 补「子目录文件过多时再分一层」;§3.6 补 rename_ref
  搬整目录的两个实测坑:① 会改写目录内部文件的内容 ② 内部文件的 ../ 出链
  不补层级(本次 23 个被误改的证据文件已按 HEAD 原始字节逐字节还原)
- docs/README.md §6 改为与六个子目录一一对应,并补登原先漏登记的
  「启动日志原子性复验流程」一行
- .cubemx_survival_baseline.json:App/util/task_watchdog.c 的注释路径也随分层更新,
  该文件是存活审计的 watchdog-module 漂移锚点,按脚本自己的提示跑 --write 重建基线
  (实测重建后仅 watchdog-module 一条哈希变化)
- 铁律 4 例外(本次在任务树里改了单写者文件):AGENTS.md 与
  .pre-commit-config.yaml 只被 rename_ref 改写路径字面量(后者全在注释行),
  任务表块与钩子声明一字未动

验证:check_doc_links.py --sections-strict 覆盖全部 88 个改动 .md 全绿;
check_test_traceability.py 输出与主树逐行一致;196 个文本文件无 BOM、无新增
CR、无 U+FFFD、无行尾空白;陈旧引用面由主树 25 处降到 6 处(无新增断链)。
2026-10-30 07:16:07 +08:00
wandering1 1668842d61 chore(id-check): 退役全库编号语料审计(钩子 52 → 51)
第三步(用户裁定跳过观察期直接做)。第一步 bf2a5c21 把两根护栏转报告制,
第二步 a5832788 立起只查新增行的新门禁,本笔把旧的全库语料审计整体退役:
语义标识已是默认形态,这套 99 族语料不再有人需要维护。

移动(保留可复现性,不再进提交门禁):
- scripts/check_ids.py → scripts/archive/id_gate/check_ids.py
- id_registry.json(87.6 KB,99 族)/ id_aliases.json(187 KB)/ id_known_backlog.json
  一并归档;新写 archive README:为什么退役、现在用什么、怎么手工跑、归档纪律。
- 归档脚本改了自定位(仓库根往上 4 层、语料与脚本同目录)与一行退役横幅;
  从新路径实跑:811 文件 / 8,051 字面量,--strict rc=0。

钩子:删 id-check(52 → 51)。现役编号门禁只剩 id-check-new(只查新增行、零语料)。
声明数 51 = commit 阶段 50 + gitlint 1,三数已对齐(AGENTS / 门禁索引 / YAML)。

连带改动:
- rename_ids.py 的别名表路径指向归档(改名工具本身没退役);
- check_ids_new.py 排除面加 scripts/archive/(语料里全是编号字面量,天经地义);
- doc-links 跳过 .mnemon/ 与 ci-artifacts/(本地记忆状态与草稿,非项目文档)——
  语料搬家后这些目录里的旧路径引用会假红,它们本来就不该参与文档门禁;
- 全库 .md 里的旧路径引用改指 scripts/archive/id_gate/(含两份 skill 手册);
- id-check.md 加退役横幅并保留原文作留档;门禁索引把该行标成已退役;
- 编号规范 §8 改成「现行只有一道门禁」+ §8.1~§8.4 标为退役留档 + §8.5 ③ 置已完成;
  各加一条 2026-10-28 变更记录行。

验证(实测):YAML 口径 51 个钩子、id-check 不在其中;doc-links --all --sections-strict
通过(194 文档);mojibake / bom-guard / coding-standard / git diff --check 全 rc=0;
新门禁自检 5 正例 + 29 反例仍全过。
2026-10-28 12:38:38 +08:00