verify

验证

你正在运行 verify 维护技能。你的任务是弥合 CONTEXT.md 文件与其所描述代码之间的差距——但不要悄悄改写已明确约定的内容。

运行辅助脚本

此技能将辅助脚本打包在自己的 scripts/ 目录中（与此 SKILL.md 一同安装）。将 SKILL_DIR 设置为此技能的绝对路径——路径显示在本文件末尾的 此技能的基础目录 部分——然后从项目根目录运行脚本（这些脚本会处理项目的 .changes/ 和 CONTEXT.md 文件）：

SKILL_DIR="<absolute path to this skill's directory>"

以下所有 node "$SKILL_DIR/scripts/..." 命令都依赖此设置。切勿引用 packages/build/——该路径仅存在于工具包的开发仓库中，不存在于已安装的技能中。

你的立场

在阅读参考资料、发现上下文或启动子 Agent 之前，先了解目标和可观察到的结果、受影响的范围、约束与反目标，以及需求是已明确、部分明确还是尚未明确。然后阅读 references/drift-control.md。核心的不对称性如下：

• **软性偏差：**代码发生了变化；更新 CONTEXT.md 以与代码保持一致。代码是事实依据。
• **硬性偏差：**不要悄悄改写。向用户说明：这是有意的变更（→ 硬性变更流程），还是回归问题（→ 标记为 Bug）？

这种不对称性不可妥协。悄悄更新硬性边界的描述，使其符合违反约定的代码，是最糟糕的结果——这会把 Bug 粉饰成规范。

前置条件

无——verify 无需活动的变更清单即可运行。这是一种维护工具。

可选：如果 .changes/active/ 中有活动变更，其 architecture.md 和 decisions.md 可作为针对性协调的“变更内容”参考。

阶段 1：发现并扫描

node "$SKILL_DIR/scripts/context-discover.mjs"

然后运行偏差检测器：

node "$SKILL_DIR/scripts/context-verify.mjs" --all [--run-tests]

解析 JSON 输出。现在你已了解：

• 哪些 CONTEXT.md 文件已过时（自上次记录后代码发生了变化）
• 哪些文件包含带测试引用的硬性边界
• 哪些硬性边界对应的测试文件缺失（在 CI 中会导致硬性阻断）

阶段 2：按约定强度分类

针对每个过时的 CONTEXT.md，使用探索型子 Agent 了解实际发生了哪些变化：

“以下 CONTEXT.md 已过时（自上次验证后代码发生了变化）。阅读 CONTEXT.md，然后阅读发生变化的相关代码文件。对于 CONTEXT.md 中的每项声明，请告诉我：它是否仍然成立？现在是否不准确？是否部分准确？尤其关注标记为 [firmness: firm] 的边界。”

向子 Agent 提供：

• CONTEXT.md 的内容
• 变更文件列表（来自 context-verify 输出的 changedFiles）
• 组件当前的代码

对每项偏差进行分类：

偏差	约定强度	操作
软性描述不准确	软	自动更新
软性边界描述已变化	软	自动更新
软性验收标准已变化	软	自动更新
硬性边界描述已变化	硬	告知用户
硬性验收标准已变化	硬	告知用户
硬性约定对应的代码已变化	硬	告知用户 + 检查测试

阶段 3：处理软性偏差

对于每项软性偏差：更新 CONTEXT.md，使其与当前代码一致。描述要具体——不要只说“刷新”，而要准确说明新的状态。

规则：

• 只更新发生变化的内容。仍然准确的部分不要重写。
• 如果代码变更已解决某个软性已知问题，将其删除。
• 如果代码变更引入了新的技术债务，将其添加到 Known-soft-spots。
• 保持与现有 CONTEXT.md 一致的语气和结构。

阶段 4：处理 firm 分歧

对于每个 firm 分歧，向用户展示：

“我在一个 firm 接缝处发现了分歧：[SEAM-]

CONTEXT.md 中的说明： [claim] 代码的实际行为： [actual behavior]

这是： (A) 对契约的有意更改 → 我将执行 firm-change protocol (B) 回归问题（代码有误，而非规范有误）→ 将其标记为 bug”

如果选择 (A) — 有意更改：

• 按照 references/firm-change-protocol.md 中的 firm-change protocol 执行。
• 更新 CONTEXT.md，以反映新的契约。
• 说明 firm-seam 测试需要通过正式的 firm-change 流程更新。
• 如果存在有效的 change manifest，则在 decisions.md 中记录。

如果选择 (B) — 回归问题：

• 不要更新 CONTEXT.md。
• 记录回归问题：违反了哪个 firm 接缝、哪个代码路径违反了它，以及本应捕获该问题的 firm-seam 测试（如有）。
• 建议：创建 triage 或 architect 类型的更改来修复回归问题。

阶段 5：重新盖章记录来源

对于每个已更新的 CONTEXT.md（软性协调，或通过 (A) 进行的 firm 更新）：

1. 获取当前 HEAD sha：git rev-parse HEAD
2. 更新 Provenance: validated-at: 行。

阶段 6：展示摘要

向用户展示：

• 已更新的文件（软性协调）
• 发现的 firm 分歧及其处理结果
• 发现的任何回归问题（未更新；需要采取行动）
• 缺失的任何 firm-seam 测试文件

在最终确认前征求用户确认。用户应至少抽查一个已更新的 CONTEXT.md。

阶段 7：报告 CI 上下文

如果使用 --ci 调用（或处于 CI 上下文中），则输出 context-verify.mjs 的 JSON 报告，并以以下代码退出：

• 0 — 没有 firm 失败
• 1 — 至少有一个 firm-seam 测试文件缺失或未通过
• 2 — 仅存在过时内容（警告）

这样 CI 就能采取非对称处理：firm 失败会阻止流程；过时内容只发出警告。

verify 不会做什么

• 它不会更改代码实现。
• 它不会运行 architect 或 specify —— 这些是用于更改架构的独立工具。
• 它不能保证运行后 CONTEXT.md 100% 准确 —— 这只是尽力协调。残留的不准确之处很正常，会在下一次 verify 时被发现。

参考文件

• references/drift-control.md — 核心漂移模型
• references/firm-change-protocol.md — 用于被判定为有意更改的 firm 分歧
• references/context-schema.md — CONTEXT.md 字段及其语义
• references/seam-and-test-taxonomy.md — firm 接缝测试规则