inspect-change

检查变更

从两个相互独立的维度审查差异，每个维度由自己的子 Agent 执行：

• 规范 —— 代码是否遵循此仓库记录的约定，并避免基线中列出的代码异味？
• 规格 —— 代码是否逐项实现了需求中的要求？

这两个维度刻意分开，因为变更可能通过一个维度的检查，却未通过另一个：代码完美无瑕，却实现错了东西；或者实现忠实，却破坏了仓库的约定。合并后的报告可能会让一个维度掩盖另一个维度的问题。

1. 固定范围——快速失败

使用调用方提供的基准引用（SHA、分支、标签或合并基准）。确认它能解析——git rev-parse <base>——并确认 git diff <base>...HEAD 有内容。错误的引用或空差异必须在此处失败，而不是在两个并行子 Agent 中失败。同时捕获 git log <base>..HEAD --oneline。如果没有提供基准引用，请询问。完成条件：引用可解析，且差异非空。

1b. 反向追踪固定的范围（脚本，只读）

对固定的 base..HEAD 运行 map-features 反向运行器——仅作为建议性范围，不得向 INDEX／分片写入处置结果：

python3 skills/track/map-features/scripts/reconcile.py \
  --repo <root> --base <base> --head HEAD --mode full

仅当 .skills/ 可写且被 git 忽略时，才添加 --write-overlay（与 /map-features 处置步骤 0 的约定相同）。保留它输出的范围。第 2 步会使用它；不要在此处生成 Feature CODE。待处理 OBS → 指明 /map-features 进行处置；绝不自动调用它。 完成条件：已保留反向范围（或运行器明确给出的无状态结果）。

2. 定位规格

按以下顺序查找适用的需求，使用第 1b 步的范围：

1. 范围中的 known-impact CODE → 对应功能的 requirements.md。
2. 查找与分支、功能名称或差异路径所涉及的 INDEX 代码匹配的 docs/specs/<date>-<feature>/requirements.md（按照 catalog-query.md 精确查询 CODE——不要粘贴 INDEX）。
3. 调用方提供的路径。
4. 范围中的待处理 OBS／known-impact／未确定的未归属路径 → 不能视为“没有规格”。保留这些标记；不要因此跳过规格维度。
5. 否则询问用户。如果用户确认没有规格，且第 1b 步在这些路径上没有待处理 OBS，则跳过规格维度，并在最终报告中说明。

（需求 ID 不必通过提交说明尾注传递——仅以文档为依据。）

完成条件：已找到 requirements.md 路径，或未归属路径的待处理 OBS／未确定标记，或已按第 (5) 步明确确认“没有规格”。

3. 收集规范来源

收集此处代码应遵循的规范：CLAUDE.md、lint／格式化配置、CONTEXT.md，并优先查找 docs/standards/。如果缺少 docs/agents/project.md，请注明并建议运行 configure-repo。规范维度始终包含 standards-baseline.md（十二种代码异味 + 安全性 + 生产就绪性）。仓库中有文档记录的规范优先于基线要求。工具已强制执行的内容可跳过。完成条件：已掌握来源列表和基线文件路径。

3a. 检查是否与现有功能重复

对于差异中的已更改源文件（来自第 1 步固定的范围），必须使用 load-subgraph 子技能，并使用这些路径以及差异／PR 摘要中的可选关键词，以便 P0 和 P1 都能提供信息。保留邻近功能的 卡片，字段来自架构 1.1（path_evidence、term_evidence、via_traces）；指出 owns_coverage。有依据的结论（一个归属位置）：对该包得出的每项结论（包括规格维度的复用未命中），遵循 skills/execution/load-subgraph/references/grounded-claims.md。 完成条件：已保留重叠功能的卡片，或明确说明“无重叠”，并按照 grounded-claims.md 说明结果为空／覆盖范围。

3b. 不变量符合性（建议性）

当 docs/architecture/ 存在时，必需的子技能：对差异使用 inspect-invariants — 它会针对每个 Respects: ARCH-N 返回一个判定（符合 / 违反 / 不明确）。将违反/不明确的判定留到步骤 5。此流程本质上仅供参考，不属于两个硬性维度 — 绝不会成为合并阻断条件。如果 docs/architecture/ 不存在，则跳过此步骤，不注入任何内容。完成条件：已保留不变量判定，或明确说明“无主干”。

3c. 代码库导航文档（可选上下文）

适用范围： 差异路径与现有导航文档中的模块、所有权或依赖范围相交。加载： skills/project/define-system-doc/consult-recipe.md。

路径： docs/codebase/modules.md、ownership.md、dependencies.md。

获批时： 仅作为建议性的规范/标准上下文 — 将与文档记录的边界/所有权/依赖项相冲突之处标记为建议性发现（其本身不构成硬性合并门槛）。 所有权文档不用于实施访问控制。

缺失 / 不具权威性时： 继续（不执行任何操作）。仅当缺少导航文档会有助于评审时，建议一次 /define-system-doc codebase/modules|ownership|dependencies；绝不自动调用。

完成条件：已保留导航上下文，或明确说明因文档缺失而不执行任何操作。

3d. UI 评审 — 可观察条件

当步骤 1 的范围中 --name-only 列表包含浏览器会渲染的文件 （HTML、CSS/样式、JSX/TSX/Vue/Svelte 组件、模板）时 → 必需的 子技能：对同一范围使用 inspect-ui。将其基于截图的 发现结果及其 needs-human-eyes 行留到步骤 5。差异中没有渲染文件 → 跳过，不注入任何内容。完成条件：已保留 UI 发现结果，或明确说明“无渲染界面”。

3e. 暂存规范

必需的子技能：在规范分派之前（以及内联规范检查之前）使用 hold-stage。纳入此固定差异所实现或违反的 ID。适用规范中的所有其他 ID 均不在此范围内 — 如果规范承诺了这些 ID，仍需报告一次该列表；不要为每个非适用项单独撰写完整发现。完成条件：规范简报列出了纳入的 ID 集合和一行不在范围内的列表（或说明“所有 ID 均在范围内”）。

3f. 影响范围证明 — 可观察条件

当固定范围更改运行时行为、存储、线缆/契约结构或配置时 → 阅读此文件旁的 blast-prove.md，并在给出合并判定前严格遵循其中说明。将 ## Blast prove 区块留到步骤 5。仅包含文档/测试的差异 → 跳过。完成条件：已证明或明确说明尚未证明，或说明“无运行时界面”。

4. 并行派发两个子 Agent

发送一条消息，其中包含两个派发任务，让它们并发运行，且互不污染对方的上下文。两者都必须只读：不得修改工作树、索引、HEAD 或分支状态；如需检查其他修订版本，请使用临时工作树（git worktree add <tmpdir> <sha>），绝不要移动 HEAD。每份任务说明都必须少于 400 个单词。派发时绝不要预判结果——不要写“不要报告”，也不要预先评定严重程度。

标准子 Agent需要：diff 命令和提交列表；标准来源路径；standards-baseline.md 的路径，它必须先读取该文件。

其报告必须采用固定格式，包含五个部分，并按顺序逐一完整写完：

• (a) 文档化标准 — 列出 diff 违反仓库文档规则的每一处，并注明相关文档和规则。包括 CONTEXT.md 中的词汇偏移（diff 重命名或更改术语的词汇表概念也属于发现项）。
• (b) 十二项代码异味 — 对每项异味各写一行结论，按 1–12 编号，包括未命中的项。写出异味名称，然后写 HIT（指出位置并引用代码片段）或 no hit。如果 (b) 部分少于十二行结论，则视为不完整，必须重跑。
• (c) 安全 — 仅针对跨越信任边界的代码块检查第 13–18 项（不可信输入、机密处理或特权操作）。若未跨越边界，只需说明一次，然后继续；不要凭空制造发现项。
• (d) 生产就绪度 — 仅当 diff 更改运行时行为、存储、契约或配置时检查第 19–24 项。说明触发问题时运维人员会看到什么。第 24 项必须通过搜索 diff 以外的仓库内容作答——它要求检查的读取方位于 diff 未涉及的文件中，只看 diff 总会错误地得出没有问题。
• (e) 测试 — 仅当 diff 新增或更改测试文件时检查第 25–27 项。每个新增或更改的测试文件各写一行结论；若文件中的测试很少，也可按每项测试分别写。注明测试名称和条目编号，并引用断言。复述字面值、重复另一个测试的失败，或根本无法失败的测试，均属于发现项；绝不要凭借此类测试报告“已覆盖”。若 diff 不包含测试文件，只需说明一次。

(c)、(d)、(e) 各自受其适用条件约束；不适用的部分必须明确标为不适用，不能直接省略。新增后续部分绝不意味着可以缩短前面的部分——无论 (c)、(d)、(e) 是否适用，(b) 都必须逐项完整检查。违反文档规定的情况可能属于硬性问题；基线代码异味、安全和生产就绪度条目始终需要判断；仓库文档优先于基线；跳过工具强制执行的内容。

规范子 Agent需要：diff 命令和提交列表；requirements.md 路径；第 3e 步中已纳入范围的 ID 集合和不在范围列表；任务说明——遍历已纳入范围的 ID，并报告 (a) 缺失或仅部分实现的 ID，(b) diff 中没有任何需求要求的行为（范围蔓延），(c) 看似已实现但实际错误的 ID；每项发现都必须引用需求 ID；不在范围的 ID 只列出一次（如果曾承诺实现，它们仍算缺失，无需逐个长篇说明）；还要检查每个已覆盖的纳入范围 ID 是否有测试或验收证据覆盖其行为（使用领域语言编写的测试——不要求在测试源码中标注 ID）。如果第 3a 步发现了功能重叠，规范子 Agent 还会收到这些相邻功能卡片（所属路径和 Out-of-Scope）作为上下文；其任务说明需指示它标记任何重复实现相邻功能已有行为的 diff 内容，并将其作为 reuse-miss 发现项，引用相邻功能代码。

完成条件：两个报告均已返回。

4b. 第二轮 Standards 审查——条件允许时

Standards 轴涵盖了审查能发现的大多数问题，而只审查一遍会遗漏发现。如果执行环境可以调度另一个只读子 Agent，就在全新的独立上下文中，使用完全相同的说明再安排一位 Standards 审查员。执行环境提供选择时，优先选择不同的模型；否则就在同一模型上再审查一遍，因为第二轮才是关键，模型不同只是额外好处，目前这里没人衡量过。报告中注明每轮 Standards 审查所用的模型，或写 unknown——绝不能根据执行环境名称推断模型。

将两份结果合并为并集，绝不能投票。 一位审查员提出、另一位遗漏的问题，不会因此变得不那么重要。在一份植入问题的 diff 上测试时，四位审查员对前五项发现意见一致，对其余发现意见不一；其中恰好只有一位审查员提出的两项发现，却是整组中最深入的——审计日志无法重建其代码本身所能导致的事故，以及首次配置中的隐式信任边界。按意见一致度加权会降低这两项发现的优先级。对于描述同一个缺陷的两份报告，去重；如果它们指出同一行代码导致的不同故障，则保留两种表述；绝不因为没有第二位审查员提出而删除任何发现。

5. 汇总

在 ## Standards 和 ## Spec 标题下呈现报告——至多进行轻微整理。不要合并或跨轴去重，也不要将一条轴的发现与另一条轴的发现重新排序；正是这种分离防止了重新排序。如果步骤 3b 得出了不变量判定，就在单独的 ## Invariants (advisory) 标题下呈现——这是第三条独立通道，绝不与 Standards/Spec 合并或重新排序。如果运行了步骤 3d，就在 ## UI 标题下呈现 inspect-ui 的发现——其发现带有严重性，且与两条轴的发现一样计入判定（这些发现有截图佐证，并非仅供参考）；其 needs-human-eyes 行须原样复现。如果运行了步骤 3f，就在 ## Blast prove 下呈现其区块——未经证明的安全事实会阻止判定 Ready to merge? Yes。

每项发现都包含：严重性（Critical / Important / Minor）、文件:行号、重要性说明，以及建议的修复方案（除非显而易见）。

以判定结尾：

Ready to merge? Yes | No | With fixes
[1–2 sentences of technical reasoning]

然后填写 banked 栏。如果判定为可以合并，但存在本分支无人处理的 Minor 发现，那么这些发现只存在于本报告中。对于每一项此类 Minor，都要输出以下区块——栏位名称与 record-debt 的 The entry 相同，但标题中不包含 DEBT-N（/record-debt 会分配 ID）。注明由用户运行 /record-debt。Critical 和 Important 绝不能列入 banked。

### `<path>` — <one-line finding>

- **Found:** `<YYYY-MM-DD>` · inspect-change on `<branch or range>`
- **Cost:** <what this makes harder or riskier, concretely>
- **Deferred because:** unactioned Minor on this branch
- **Fix shape:** <one line | Unknown>
- **Ticket:** none
- **Status:** open

没有答案的栏位填写 Unknown——绝不能省略该行。“只列出剩余项”／“不要编造台账格式”不代表可以跳过这些栏位。在这里创建 **DEBT-N** 会造成冲突；请勿这样做。

完成条件：两条轴的章节、判定和 banked 栏均已提交——若没有尚未处理的 Minor，则 banked 填写“none to bank”。

行内备用方案（不支持子 Agent）

此执行环境不支持子 Agent？请在同一上下文中依次自行审查两条轴：先审查 Standards——阅读 standards-baseline.md，根据其中十二种常见问题、安全性章节和生产就绪性章节逐项检查 diff；再审查 Spec——先检查 hold 阶段，然后检查已纳入的 ID（对于不在范围内的情况，只检查一次）；接着，如果步骤 3d 已触发，按照 inspect-ui 的要求检查 UI 通道。完成并记录一条轴的全部审查后，再开始下一条；并且仍须在单独的 ## Standards、## Spec（以及 ## UI）标题下呈现，不要将一条轴的发现与另一条轴的发现重新排序。这种做法缺少两个子 Agent 所提供的上下文隔离，因此，先结束一条轴再开始下一条的严谨流程，才能避免两者相互混淆。