Commit Graph

8 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 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 7b05d7bfd4 docs: 任务规划目录收缩——只留推进顺序与硬件缺陷,其余待办归模块文档
按用户裁定(2026-11-10)把 docs/任务规划/ 从"全量待办表"收成两个文件:

1. 登记簿.md 只记 V0.1 硬件缺陷 → V0.2 改版要求(双转换器无共同采样触发、
   IA 前端差分滤波限制谐波带宽)。原 §1/§2/§4/§5/§6/§7/§8/§9 的待办按
   "待办跟着所属模块走"清空,四类事实在删除前先落到新归属:
   - 两点标定开工前要先拍板的三件事 → 算法层设计说明 §13.13(新节)
   - 通讯设置页真机判据 → 网络配置说明 §3.6 内联
   - 缩堆迁 CCM 后半、开入开出重开条件 → 原本各模块文档即唯一权威
2. 暂缓-RS485.md 删除,其唯一不可丢的"采集链路测试可验证性约束"三条与
   完成判据并入 产品需求设计文档 §5.10。
3. 任务规划/README.md 去掉全部历史叙述(UI 补齐销项流水、net 收口过程、
   故障录波近千字台账),只留:怎么用、条目规则、生成物单写者纪律、
   推进顺序表(每行只写当前状态与卡点)、维护约定。

同步改写全库引用(约 60 处):AGENTS.md、docs/README.md、产品需求、UI、
子系统设计、内存管理、环境与部署、算法、测试说明、门禁说明、问题记录,
以及 App/ 与 Drivers/BSP/ 的头注释、脚本与 .pre-commit-config.yaml 注释。
顺带修掉三处已失效的引用目标:链路延迟测试的队列往返重验项改指实机测试
实施指南 §7.3;并行工作树的 <ID> 行去掉已退役的 N-x/S-x/T-x 编号族;
任务规划 README 的 §1 旧编号在技能示例里的引用。

门禁:check_doc_links --all --sections-strict 214 篇通过、无法判定 0;
pre-commit 全 Passed(doc-links / mermaid / 任务表 / 内存数字 / BOM /
UI 像素回归 / generated-fresh / layer-deps / bsp-err / skill-size);
keil-build 0 错误 0 警告(Code=255160 RO=31204 RW=2080 ZI=152152),
RAM 预算门禁 PASS(RW_IRAM1 73.9%、RW_CCM 87.9%)。
2026-11-10 20:33:30 +08:00
wandering1 4a4ad6bc5f chore(全仓): @build/@test 旧文档别名清退为技能调用名
现状口径:/keil-build 与 /serial-boot-test 是 DSH 会话的技能调用名,
不是 shell 命令;「名 + 命令行参数」的命令形态改为可执行体
run_boot_test.py 的真实调用。

- AGENTS.md:别名说明重写为「技能调用名不是 shell 命令」,两条目改
  「编译(/keil-build)」「串口回归(/serial-boot-test)」
- keil-build / serial-boot-test 两 skill 调用名与示例同步;task-worktree
  方案文档去掉 @build/@test 惯例从句;@task 保留(不在点名范围)
- 123 文件现状陈述全改;台架捕获、变更记录/时间线、rename 映射输入
  等 41 行历史证据保留旧名
- gen_memory_svg.py 6 处措辞随改,3 张 SVG 产物同批重跑
- 顺手补并行方案同行漏网计数 51→52 钩子

验证:提交期快钩子对 123 文件实跑全 Passed;check_doc_links --all
rc=0(3038 处、无法判定 0);check_mermaid --all rc=0;YAML 解析 52
钩子不变;skill-size rc=0;py_compile 全过;字节卫生零漂移。
2026-10-30 13:03:12 +08:00
wandering1 2be49dc9dd docs(skills): 明确 @build/@test/@task 为文档别名并新增 precheck/postmerge 命令
CI / 静态门禁 (pre-commit) (push) Failing after 3m45s
CI / 主机侧单测 (MSVC) (push) Failing after 43s
AGENTS.md「构建与验证」新增总口径:@build / @test / @task 都是本仓库的
文档别名、不是 shell 命令(2026-10-30 实测:bash 敲 @task / @build 即
command not found,dsh task 被解析成 profile 名报错);`=` 后的命令行
才是可执行形态,DSH 会话显式调用为 /keil-build、/serial-boot-test、
/task-worktree。

- AGENTS.md / docs/README.md / 并行任务工作树方案.md:@task 三处定义位
  由「短命令」统一改为「文档别名」,并写入两种实测失败形态
- keil-build / serial-boot-test SKILL.md:定义位点破别名性质;@test 在
  skill 内原先没有定义句,补口径 blockquote
- task-worktree SKILL.md 与 reference/:whenToUse、标题、症状表、插件桥
  去 @task 前缀改指 list / 本 skill;frontmatter 能力清单同步
- task_worktree.py 新增 precheck(树内只读自查:BOM 漂移 / CR / U+FFFD、
  docs 逐档门禁、--msgfile 消息 BOM/CRLF/行长/禁词检查,自动补
  ci-artifacts/)与 postmerge(主树体积凭证自动诊断:新鲜跳过、红先短链
  再只读复检裁定是否升全链;check_doc_links --all;列文件不代提交)
- done 快路径打印与门禁拦截提示均指向 postmerge

实测:precheck 对坏消息文件抓到 CRLF、行长 95>80、禁词×3(rc=1);
postmerge 端到端「凭证同码新鲜→跳链→doc --all 绿(2967 章节引用 /
214 文档)→列 dirty 文件」rc=0;check_skill_size.py 与 py_compile 通过;
frontmatter 改动后 DSH 已用新值真加载过一轮。无 .c/.h 改动,不涉及体积。
2026-10-30 10:25:05 +08:00
wandering1 2b478588a7 docs(task-worktree skill): 补「只改注释也刷红体积同码凭证」实测坑
done testdoc 撞上的一次新型红:size-gate 的判据是索引 blob 指纹,不是体积数字。
全库路径同步顺带改了 20 个 .c/.h 的注释,Program Size 逐项没变,凭证照样报
「不同码」。处置比 C 节补绿链短:合并后 done 自己那次 @build 已 0 错 0 警,
只需 ram_baseline.py --update 重写 scripts/size_attestation.json,
不 --write 动内存受管快照(数字没变就去改受管区=给别的在飞分支造冲突面)。

连带登记第二个坑:done 在「分支已合入」的路径上于门禁之前就 return,
补完凭证重跑不会替你复绿,落主干后的全量证据要自己跑 ci_local.py
(实测 47 runner / 3896 断言全绿)与主树 check_doc_links.py --all
(实测 215 个文档 / 2993 处章节引用 rc=0)。

只加 reference/pitfalls.md 一条,SKILL.md 正文一字未动(受插件写侧
65536 字节上限,深规程一律进 reference/)。
2026-10-30 09:14:49 +08:00
wandering1 ecf9d3ad3d docs(task-worktree skill): 修 @T3@ 围栏腐坏,正文瘦身并把细节外置 reference/
围栏腐坏是真 bug:@T3@ 是被误提交进仓的代码围栏占位符,Markdown 渲染出
来就是一行 @T3@ 加裸命令。git log -S 定位:842d711e(2026-10-28)
SKILL.md 还有 18 个真三反引号围栏行、0 个占位符;21c68521(2026-10-29
插件桥接那笔)起变 0 围栏 / 34 个占位符。全仓只有本技能 6 个文件有此
病,draw-diagram / keil-build / ui-verify 等都用真围栏。本轮七个文件
占位符清零、围栏全部成对。

信息密度:SKILL.md 28,139 → 23,087 B(−18%,占插件写侧上限 65536 的
35%,给自进化留头量)。同一句外置理由在 C2/D/E/F/G/陷阱/验证 重复 7 次
→ 0;frontmatter 与 F 节写了两遍的插件桥接说明收进 F 节;「这不是免费
的」「挡给你看的保护」这类修辞删掉。删掉的细节全部落进对应 reference
篇——skill-size 钩子会校验指针不悬空:现 26 处链接 / 8 篇目标 / 悬空 0,
每篇都有入口。

锚点未重排:节号 A–G/C2、各节步骤号、铁律编号被 reference/ 反向引用
(铁律 3/5/7/9 与 A 第 1、5 步,C 第 5~7 步,E 第 1~6 步均结构性存在)。
只在 SKILL.md 出现的 PIPESTATUS 教训保留(reference/ 里没有,删了就丢)。

门禁:check_skill_size.py rc=0(17 个 SKILL.md 全在写侧上限内、无悬空
指针);七文件均无 BOM / CR / U+FFFD、单个尾换行。
2026-10-30 00:31:36 +08:00
wandering1 f08b12a46c docs(技能渐进展开): 五个技能正文逐字外置到 reference/,主文只留索引与指针
按「主文留头量、深规程外置」重写本仓技能,全部是逐字搬移:
搬移前断言原文每条非空行必须出现在新主文或 reference 文件里,
0 丢失才落盘;步骤编号一律不重排(正文有「第 12 步」交叉引用);
每个切点保留原小标题 + 索引(加粗引导句与步骤标题)+ 指针行。

主文变化(上限口径 = 插件写侧 65536 字节,见上一笔 skill-size 钩子):
- id-family-semantic-migration 33392 -> 10968(17%),reference 3 篇
- stale-doc-count-sweep 19811 -> 6945(11%),reference 2 篇
- mem-budget 19963 -> 13042(19%),reference 3 篇
- keil-build 12917 -> 8879(14%),reference 2 篇
- task-worktree 72601 -> 28139(42%),reference 8 篇

task-worktree 本笔同时收录另一会话已写完的 C2/D/G 三节正文——那
三处手改与我的拆分落在同一份文件改动里,不可分离;其内容同样已
随 reference/ 外置,主文只剩标题、索引与指针。

外置语料合计 122211 字节 / 30 篇:围栏数逐篇为偶,无 BOM/CR/U+FFFD。
draw-diagram 与 serial-boot-test 脚本是另一会话的在飞改动,本笔未含。

skill-size 钩子在本笔首次真跑(前一笔无 .dsh/skills 文件可触发)。

gate: pre-commit 全绿(doc-links、id-check-new、check-yaml、
      skill-size、check-added-large-files);30 篇 reference 手工字节
      体检 clean;skill() 逐个复载确认加载的是拆分版。
2026-10-29 15:03:12 +08:00