使用 TDD 与正常提交门禁开发¶
本工作流保留当前 C11 架构、格式与显式证据。Codex 负责平台维护；独立 agent 审查高风险变更。虚构人员或本地文件都不能建立 GitHub 分支保护。
安装并检查工具¶
先完成固定源码与递归依赖指南。然后从该仓库根目录安装维护工具：
python scripts/setup/install_dev_tools.py
.venv/bin/python -m pip install -r dependencies/environment-tools.txt
python tools/dev/dev.py doctor
Windows 使用 .venv/Scripts/python.exe。安装建立 pre-commit 和 commit-msg 钩子。钩子检查暂存输入，不替用户暂存，也不静默修复文件。保留未暂存工作和真实失败诊断；不得绕过钩子。
准备锁定的主机测试框架¶
GoogleTest 和 GoogleMock 由 Git 子模块 ext/googletest 提供。锁文件记录官方 1.16.0 的 upstream 基线 6910c9d9165801d8827d628cb72eb7ea9dd538c5；Gitlink 与锁文件所选 commit 固定该基线上的组织补丁 58ec32c09ed8a099e55cbdab9418597c4fd9b14f，其中包含 host 测试框架 RE 复制赋值的所有权修复。依赖清单分别记录官方 upstream 基线与所选补丁。 上面的递归 checkout 包含该子模块。对于已有 checkout，请在运行测试前显式准备 Native 依赖范围：
python tools/dev/dev.py prepare --scope native --allow-network
如果只需初始化此子模块，可改用 git submodule update --init --recursive ext/googletest。准备阶段可以使用网络；CMake 配置只使用已准备的本地源码，缺失、版本与锁定值不符或存在本地修改均失败。配置过程不获取依赖，也不使用系统安装替代。框架只进入主机测试目标图；ARM 构建和固件 SDK 消费者不需要它。
执行 RED、GREEN 与评审¶
新增 C 行为或修复缺陷时，先添加有意义的 GoogleTest／GoogleMock 回归。执行并保留预期失败原因与原命令。实现最小正确生产变更，执行 GREEN，再重构。Mock 外部端口／MMIO，而不是被测实现。覆盖相关拒绝、取消、排空、溢出、隔离保留和实例隔离。Python 生产工具使用标准库 unittest，遵循相同实际 RED／GREEN 规则。
python scripts/ci/tdd_gate.py --all --preset native-debug
完整门禁构建锁定的离线框架，以新报告执行发现的全部用例，不使用 filter／shard。空、跳过、部分、陈旧或变化输入均失败。钩子核对暂存树保持不变；CI 独立执行门禁。框架仅用于主机 C++17；固件保持 C11。自动化证明执行，保留的开发日志记录历史 RED／GREEN 顺序。纯正文或图源修改需要对应文档检查和语义审查，不需要镜像实现测试。
将完整本地软件计划关联到 Pull Request¶
GitHub Actions 不可用时，tools/maintenance/local_ci.py 校验维护中的 tools/dev/plans/software.json 的既有执行。默认只读：报告精确源码与范围前，检查实际完整阶段、命令收条、干净源码、输入以及同一计划。它不运行计划，也不把中断或部分报告改成成功。
python tools/maintenance/local_ci.py --report /path/to/software/report.json
显式 --publish 使用已配置且获授权的 GitHub 凭据和既有开放 PR。它两次核对 PR head/base，只向已验证 head SHA 发布 nexus/local-software-plan；后来的 head 不能继承该状态。保留的收条区分 pending、confirmed 和 unconfirmed 发布。两次观察不构成原子的 GitHub 合并事务。
此状态只证明维护中的本地计划范围。它不是 GitHub Actions job、封存软件候选、已配置分支规则或产品发布。服务器规则需单独实际回读；独立 agent 审查不虚构 CODEOWNERS 账号或人工批准。现有 release workflow 仍要求其声明的最终 main CI jobs 和可信发布检查；本地状态不能悄悄替代这些要求。
快速反馈与完整证据¶
先对修改的行为执行定向开发测试，再对最终源码执行正常完整验收门禁。发现已维护的测试名称，不增加重复测试程序。保留原始 RED 失败、GREEN 结果和实际命令。过滤执行或缓存结果不能使完整候选通过验收。
python tools/dev/dev.py timings /path/to/receipts 汇总已有进程 receipt，不重新运行工作。分别观察准备、配置、编译、测试、文档和 SDK 消费。保留失败／取消的尝试以及未观测的 CPU 或 RSS；重叠的墙钟时间不能相加作为总耗时。比较等价源码、工具与配置范围后再归因提速。
在 Linux 上，正常回收的进程（包括非零退出）可带有由 wait4 观测的 resource_usage：用户态／内核态 CPU 秒数和 maximum_process_rss_bytes。范围是被等待的进程及其已经回收的后代。RSS 值是观测到的最大单进程峰值，不是整个进程树的同时占用。超时、取消、启动失败、旧收据和其他平台保留未知值，不从墙钟耗时估算。
耗时汇总公开 measured_resource_attempts 和 maximum_observed_process_rss_bytes，同时保留每份原始收据。汇总的 cpu_seconds、peak_rss_bytes 和 cache_hits 仍为未知，因为嵌套收据可能重复计算工作，这些观测也不能建立全局内存峰值或缓存行为。分别比较同一工具链、源码和 profile 下的 cold 与 warm 尝试；小型工具回归的测量不能量化全项目构建收益。
根据可用 RAM 与磁盘显式选择有限编译并发预算，不能只看 CPU 数量。复用已验证的源码／工具准备与正常增量构建；按正常规则使改变的配置、依赖和生成输入失效。不得缓存验收报告、恢复不相容的对象或同时修改同一构建树。完整门禁发现、实际退出码、输出身份及失败／取消保留仍为必需。
运行较长的资格计划前，应显式选择有限的外层命令预算，并选择平台输入 checkout 之外、无符号链接或父路径别名的新规范化绝对输出路径。NEXUS_COMMAND_TIMEOUT 为没有显式 timeout 的 process 调用提供默认预算，不替代计划各阶段的期限。维护中的软件计划在输出目录下打包 SDK，因此既有 SDK 边界会拒绝位于平台 checkout 内或带路径别名的输出。
先检查本次调用的环境：维护中的 provider 和 TrustZone 验收拒绝所有 GIT_ 变量，包括仅控制显示的 GIT_PAGER。若启动器注入了 GIT_PAGER，只在本次启动的进程环境中省略它；若仍有其他 GIT_ 变量名，则停止启动。维护中的调用方式见开发命令参考。应保留失败和中断的尝试；更长的重试预算和前面阶段通过，都不等于完整计划已经完成或候选已经封存。
删除测试前，指出其行为责任和仍存在的独立覆盖。仅删除过时行为或已经证明重复覆盖同一合同的测试。保留检查拒绝所有权、借用保留、实例隔离、取消、IRQ 顺序、真实厂家行为或外部 SDK 消费的测试。照着实现编写的通过断言本身不能作为独立替代。审查未找到可安全删除的测试时应保留；减少测试数量不是优化目标。
保留风格与范围¶
使用未改变的 .clang-format 和 .editorconfig：80 列、四空格、附着大括号、类型侧指针星号和反斜杠 Doxygen 注释。公共头文件说明上下文、截止时间、所有权和失败。源注释解释不变量和硬件顺序，不重复声明参数。新增／修改文件通过整文件检查；已有冻结欠账只能减少。
每次使用 Conventional Commits 提交一个可评审变更。将接口／配置变化与图示、示例、翻译和执行范围一起评审。产品、执行任务、私有 PCB 和恢复策略保留在 Nexus 外。记录实际源码／配置／工具／ELF 身份与物理待执行项；成功 commit 或 CI 不将结果升级为产品发行。