audit-trace

审计追踪

纵向可追溯性检查。它通过证据回答：需求 ID 在规范三件套（以及可选的架构文档）中是否一致？能力目录是否没有重复 CODE、Code 单元格中的 OBS-<6hex>，以及损坏的分片引用？

这不是主观判断。所有输入都通过 grep 和读取来收集——采用确定性流程——且每条发现都遵循固定规则。在同一个仓库上运行此检查的两个 Agent 会得到相同的发现集。

**仅检查文档：**此检查绝不会在应用源代码、测试文件或提交消息中 grep 需求 ID。测试对行为的覆盖由 execute-family Spec review、test-first 和 prove-claim verify 命令来保证，而不是在代码中嵌入 CODE-N.M。

检查结果

一组发现，每项均为 ERROR 或 WARNING：

Code	级别	条件
E1	错误	任务引用了任何需求文件都未定义的 ID
E3	错误	同一个 ID 在多个文件中以粗体定义
W1	警告	没有任务引用某项状态为 Approved 或 In-progress 的需求
W2	警告	requirements.md 缺少 Status: 或 Feature code: 行
E4	错误	Respects: 行引用了任何 docs/architecture/ 文件都未定义的 ARCH-N
E5	错误	Respects: 行引用了已废弃（删除线标记）的 ARCH-N
W3	警告	没有任何 design.md 引用某项有效的 **ARCH-N** 不变量
E6	错误	Security: 行引用了规范 Approved 安全文档中没有有效粗体定义的 TB-N/THR-N/CMP-N
E7	错误	Security: 行引用了已废弃（删除线标记）的 TB-N/THR-N/CMP-N
E8	错误	同一个 TB-N/THR-N/CMP-N/SLO-N 在多个规范文件中以粗体定义
E9	错误	Reliability: 行引用了 Approved docs/ops/reliability.md 中没有有效粗体定义的 SLO-N
E10	错误	Reliability: 行引用了已废弃（删除线标记）的 SLO-N
E11	错误	多个目录行（跨分片）中出现了相同的功能 CODE
E12	错误	路由器的 Feature catalog 路径缺失，或不是 docs/specs/ 下可读取的文件
E14	错误	INDEX 使用了平面 `
E13	错误	规范目录的 Code 单元格为 OBS-<6hex>（OBS-[0-9a-f]{6}）
W4	警告	目录中的 Spec 指针（非 —/空值）指向 docs/specs/ 下不存在的目录
W5	警告	多个 .skills/reverse-features/active/*.md 卡片中出现了相同的 OBS-<6hex>

E4/E5/W3 来自不变量检查，仅在存在主干文档时运行。E6–E10 来自系统 ID 检查；若定义文档不存在或不具权威性，则跳过。E11–E13 和 W4 仅在 docs/specs/INDEX.md 存在时运行。W5 与这些目录检查归为一组；即使 active/ 存在，只要 INDEX 缺失也会跳过。不要仅因有效系统 ID 没有功能引用而发出警告。不要判断语义符合性。遵循相同的仅检查文档规则。

**已废弃：**不再发出 E2（针对 Implemented/Shipped 的代码侧 ID 存在性）。不要重新引入会在代码库中 grep ID 的发现规则。

错误表示审计追踪存在问题。警告表示审计追踪不完整，但没有错误。prove-claim/cut-release 会将任何错误视为未通过的门禁；警告会报告，但不会导致失败，除非调用方另有规定。

输入

• 规格位于 docs/specs/ 下（或 docs/agents/project.md 中指定的 specsDir）。定义来自以 requirements.md 或 fixes.md 结尾的文件；任务引用来自以 tasks.md 结尾的文件。
• 架构（可选）：当 docs/architecture/ 存在时，不变量检查会读取该目录树，以及功能 design.md 文件中的 Respects: 行。
• 决策记录（可选）：当 .skills/decisions/ 存在时，运行随附的验证器（见下文）。
• 遍历目录树时跳过 node_modules .git dist build target coverage .next .skills vendor，以及任何点文件／点目录；但有意检查决策记录路径和目录清单 OBS 唯一性检查（仅 .skills/reverse-features/active/）时除外。

不要在应用或测试目录树中搜索需求 ID 覆盖情况。此检查会忽略使用方仓库中的旧版 /// REQ: 或测试标题标签。

检查项

在仓库根目录运行这些检查，并完整读取每项检查的输出——遵循下文“不可妥协”部分中的整树规则。

1. 定义——需求／修复文件中的粗体 ID，去除已废弃的 ID。

# every bold **CODE-N.M** in a requirements/fixes file, retired (~~struck~~) ones deleted first
grep -rnE '\*\*[A-Z][A-Z0-9]{1,11}-[0-9]+\.[0-9]+\*\*' docs/specs \
  --include='*requirements.md' --include='fixes.md' \
  | sed -E 's/~~[^~]*~~//g' \
  | grep -E '\*\*[A-Z][A-Z0-9]{1,11}-[0-9]+\.[0-9]+\*\*'

每个保留行的格式均为 path:line:text；其中每个剩余的粗体 ID 都是定义，归 path 所有。sed 会删除 ~~ … ~~ 范围，因此已废弃的 ID 不会出现在结果中。需求文件中的普通（非粗体）ID 是正文，不是定义。

2. 状态和功能代码——逐个需求文件检查。

grep -rnE '^(Status:|Feature code:)' docs/specs --include='*requirements.md'

Status: 的取值为 Draft | Approved | In-progress | Implemented | Shipped（匹配到的第一个为准）。

3. 任务引用——_Requirements: 行上的 ID。

grep -roE '_Requirements:.*' docs/specs --include='*tasks.md' \
  | grep -oE '^[^:]+:|[A-Z][A-Z0-9]{1,11}-[0-9]+(\.[0-9]+)+' \
  | grep -E '^[^:]+:$|^[A-Z][A-Z0-9]{1,11}-[0-9]+\.[0-9]+$'

只有包含字面字符串 _Requirements: 的行上的 ID 才是任务引用。输出会交替列出 path: 行和其中引用的 ID——每个 ID 都属于其上方的 path:。末尾的 grep 只保留完整的两级标记，因此三段式 CODE-1.2.3 绝不会被误读为对 CODE-1.2 的引用。

不变量检查——仅当 docs/architecture/ 存在时

如果仓库没有 docs/architecture/ 目录，则完全跳过检查项 4–5；发现项集合仅包含检查项 1–3，保持不变。当主干目录存在时，读取本文件旁的 invariant-passes.md 并严格遵循其中说明。

系统 ID 检查——安全与可靠性（可选文档）

如果相关的规范文件缺失，则完全跳过。当 docs/security/threat-model.md、docs/security/compliance.md 或 docs/ops/reliability.md 存在时，读取本文件旁的 system-id-passes.md 并严格遵循其中说明。不要将这些 ID 视为任务页脚引用；也不要仅仅因为某个有效系统 ID 未被任何设计引用而发出警告。

目录完整性检查——仅当 docs/specs/INDEX.md 存在时

如果缺少 docs/specs/INDEX.md，则跳过本节（规格目录树完全不存在时，已适用“不必检查任何内容”的停止规则）。当 INDEX 存在时，读取本文件旁的 catalog-passes.md 并严格遵循其中说明。不要评判已识别卡片是否应该有三元组（Spec — 是允许的），也不要在此处将 OBS 提升为 CODE。

规则

将开头的发现项表应用于各项检查生成的集合。W1 的状态要求：

状态	需要任务（W1）
Draft	否
Approved / In-progress	是
Implemented / Shipped	否（可以保留任务历史记录；不设代码侧 ID 门槛）

Status: Implemented / Shipped 的证据属于流程（任务已勾选、验证通过、规格审查），而不是测试文件中可通过搜索匹配到的 ID。

任务引用完整性是文本层面的——不要对此进行判断

当某个 ID 出现在 _Requirements: 行上时，该 ID 就是任务引用。仅此而已。不要阅读任务步骤来判断该任务是否“真正”实现了需求。此类判断属于规范审查 / 声明验证，而非此项检查。

收集 specs 目录树下所有匹配的 requirements 和 tasks 文件。漏掉一个 requirements 文件会凭空产生一个错误的 E1；漏掉一个 tasks 文件会凭空产生一个错误的 W1。搜索整个 specs 目录树；不要抽样。

同一规则也适用于不变量检查：E4/E5/W3 只检查 Respects: ARCH-N 引用是否指向仍然有效的不变量——也就是检查其是否存在且有效。绝不要判断设计是否真正遵循该不变量；这种语义判断属于 inspect-invariants / inspect-change，而非 audit-trace。

决策记录检查——仅当 .skills/decisions/ 存在时

如果仓库中没有 .skills/decisions/ 目录，则完全跳过本节；所有已运行检查的发现集合保持不变。若该目录存在，则阅读本文件旁边的 decision-record-pass.md 并严格遵照执行。

输出

先报告数量，再列出发现：

trace: 24 requirements · 24 task-cited
  ERROR E1 task cites unknown requirement SHELL-9.9 (docs/specs/…/tasks.md)
  warn  W1 NOTES-2.1 (…/requirements.md, Approved) is not cited by any task

具体措辞和顺序不作要求——发现集合必须一致。如果 docs/specs/ 不存在，则说明没有内容需要检查，并停止。门槛：错误数为零。若 INDEX 存在，则目录错误（E11–E13）计入错误；警告 W4–W5 保持非致命，除非调用方另有说明。