hrt-align-consistency-review

hrt-align-consistency-review

在编写任何代码之前，验证每份 tempa-spec 产物彼此一致且忠实于需求，并确认确实有人工阅读过这些内容，而不只是由 Agent 相互比对检查。

一个周期：先 ALIGN（此 Agent 检查各产物之间的一致性），然后 VERIFY（由具有全新上下文的子 Agent 重新检查 ALIGN 自己的映射，并进行修正——仅当本周期的 ALIGN 提出至少一项 HIGH 级别的问题时），最后 WALKTHROUGH（向人工展示一份以规格和设计为主的摘要，并询问是否有任何需要更改之处）。WALKTHROUGH 的反馈会重新进入 ALIGN。重复此流程，直到某一轮 WALKTHROUGH 没有提出任何新问题，或用户提前签字确认（参见“结束循环”）。每个周期开始时都要报告周期编号。第三个尚未结束循环的周期之后，询问用户是要继续还是签字确认——不要自行停止。

ALIGN

1. 重新阅读所有产物：proposal.md、specs/**/*.md、design.md、tasks.md。运行 openspec validate --strict 和 hrt-artifact-lint 技能。Lint 负责结构和覆盖情况：spec 结构、capability 与 spec 文件的对应关系、design 中的 Covers: 目标、每个场景是否由某个任务组覆盖（以及每个组的 Covers: 名称是否真实存在）、每项威胁是否由负面场景或具名检查回应、proposal 的大小和形态。直接修复每个 lint ERROR，并将每项记录为 MECHANICAL 发现；如果某个 ERROR 有多个有效修复方式（例如某个场景可由多个组交付），则将其记录为 DECISION 发现。注明 lint 是否运行干净，并保留其 Size facts: 行，以便 WALKTHROUGH 使用。design.md 是必需文件——缺失时属于 HIGH 发现。
2. 建立一致性映射：对以下每个维度，列出检查了什么以及发现了什么——必须先于分类。这些维度需要判断；lint 已覆盖其余部分，因此除非 lint 无法运行，否则不要手动重新检查。
   • proposal <-> design 和 specs：双向检查。正向：proposal.md 的 Why 中每个结果以及 Capabilities 中的每项能力，都必须由 specs 中的某个场景体现，并在 design 中说明。反向：specs 和 design 不得添加 proposal 未提及的能力或行为，也不得出现 Out of Scope 中列出的内容。lint 已检查每项能力都有对应的 spec 文件——这里仅判断内容是否匹配。仅由 LLM 判断。
   • specs <-> design（包括接缝）：design 说明如何满足每项需求，且不得与任何需求矛盾。仅由 LLM 判断。接缝：specs/** 中的每个 #### Scenario，在 design.md 的 Shape / Seams 部分都必须有一个接缝，以供其测试接入。步骤 1 的 lint 已检查每个接缝的 Covers: 目标是否指向真实需求/场景——这里仅判断正向关系（每个场景是否都有可供测试接入的接缝），以及该接入是否确实合适。只有当 Shape / Seams 是一行“no new code surface”说明（纯配置/数据变更）时，才跳过接缝检查。如果步骤 1 的 lint 报告了 security-gate WARN（proposal/specs 中出现信任边界关键词，但没有 [Threat 条目，也没有 Security pass: skipped - <reason> 行），则判断该边界是否真实存在：真实存在但没有威胁列表，属于 MEDIUM；跳过理由与 specs 矛盾，也属于 MEDIUM。即使没有 WARN，也要检查 specs 涉及的每个信任边界（上传、登录、webhook）是否都有 [Threat 行：lint 只要发现任意一行 threat 就不会报警，因此未覆盖的边界属于 MEDIUM。
   • design <-> tasks：双向检查。正向：design.md 中的每项 Decision 都必须有任务落实；design 记录的前置因素必须放在前置组中，并且依赖它的切片必须依赖该组。反向：任务不得超出 design 的范围或接缝；各组的规模和顺序必须支持逐组 RED 再 GREEN（过于粗略而无法演示的组，或未声明依赖却需要另一组代码的组，都属于发现）。lint 已检查场景和威胁覆盖——不要重复检查。仅由 LLM 判断。
   • tasks 图：仅当 tasks.md 中有任何 Depends on: 行时检查。步骤 1 的 lint 已检查结构（格式错误的值、未知 ID、循环）——这里仅判断声明的图是否属实，因为声明的依赖是并行运行组之间唯一的隔离机制：某组需要另一组的代码或测试却未在 Depends on: 中列出，或者两个组之间没有依赖路径却会编辑同一文件（查看 design.md 的 Shape / Seams 和任务中列出的文件），都属于发现。缺少依赖边是危险方向。
   • design/tasks -> 代码库：design.md 或 tasks.md 对现有系统作出的每项具体断言（例如某个函数、方法、模块、文件、端点、架构或配置已存在或必须修改）都必须依据实际代码库核实，不得想当然。必须使用工具（codegraph > codebase-memory-mcp > ripgrep）确认其是否存在；仅判断产物对该代码的描述是否准确。在 align.md 中记录每项已核实的断言及其结果。第 2 轮及之后：只需重新核实自上轮以来新增或变更的断言——align 期间代码库不会改变（代码在 apply 阶段编写），因此之前已核实且未变更的断言仍然有效。
   • 第 2 轮及之后：还要纳入上一轮 WALKTHROUGH 提出的内容——将每项作为映射中的独立条目，而不是脚注。
3. 以上所有维度的规则：仅对存在/引用/结构部分进行机械检查（X 是否存在、是否引用 X、格式是否正确），绝不对语义部分进行机械检查（X 是否真正实现意图）。关键词匹配不能代替判断。
4. 停下。暂不分类。确认上述 5 个维度（以及任何延续自 WALKTHROUGH 的事项）的一致性映射均已完成，然后再继续。
5. 对每项发现进行分类。**先应用后果门槛：**只有能明确说明未修复时下游会出什么问题，发现才属于 HIGH 或 MEDIUM——例如实现者错误地编码了矛盾内容、需求未经测试就发布、apply 遵循了误导性的代码库描述。其他一律为 LOW——例如“design.md 和 tasks.md 对同一事物使用了不同词语”或“这些需求重新分组后会更易读”都没有指出下游故障。
   • HIGH：产物之间存在矛盾；design 添加了 proposal 未提及的能力；破坏 OpenSpec 解析的结构错误；proposal.md 的 Why 中有某个结果未由任何 spec 场景验证；design/tasks 对代码库的断言（所引用的函数、模块、文件或 API）与实际情况不符。
   • MEDIUM：覆盖不完整；缺少设计决策的重要技术选择；任务粒度过粗或顺序不当；某项 Decision 没有任务落实；proposal 暗示了边缘情况，但没有对应场景；某个场景没有可供其接入的接缝；任务超出 design 的范围或接缝；specs 涉及的边界没有 [Threat 行。
   • LOW：术语不一致、措辞、格式、顺序、轻微遗漏——任何确有问题但未通过后果门槛的事项。 需求含糊或不可测试，属于 Structural Auditor 在 specs 阶段提出的发现，不属于 align 发现。
6. 为每项发现标注 MECHANICAL 或 DECISION：
   • MECHANICAL：只有一种正确修复方式，不需要判断范围或意图，并且有确定性锚点——可重新运行的 grep/正则/计数检查，以便在修复前确认（例如 hashtag 数量、复选框格式、kebab-case 名称不匹配、任务重排）。“显然是机械问题”还不够，必须有可重复运行的锚点——符合机械问题形式但没有锚点的发现（例如“术语统一”——需要判断两个术语是否含义相同；或“明显缺少场景”）属于 DECISION。
   • DECISION：存在多个有效解决方案、涉及范围或意图，或者虽符合 MECHANICAL 的形式却没有锚点（例如设计与 spec 矛盾、某个结果没有场景、某个边界没有威胁行，以及上述缺少锚点的情形）。“推迟”或“接受不一致”不算有效解决方案——但即使已有明确修复方案，只要具备资质的作者仍可能作出不同选择，该发现仍属于 DECISION。
7. 按 HIGH / MEDIUM / LOW 分组展示本轮发现，并为每项标注 MECHANICAL 或 DECISION，清楚说明问题。
8. 解决这些问题：
   • MECHANICAL 发现（任何严重级别）：直接修复并记录变更内容。
   • **需要单独答复：**每项 HIGH DECISION 发现，以及任何会改变 proposal.md 已确定范围的 DECISION 发现、单向门问题（数据迁移或破坏性架构变更、删除存储数据、更改已发布的 API 或事件契约、移除其他代码会读取的配置或标志，或必须手动撤销的步骤），或 HIGH 严重级别的安全权衡。不要静默编辑，也不要退出技能后再报告。将这些问题集中在一条消息中。对每项问题：先中立说明权衡（冲突是什么、有哪些有效解决方案），然后再给出建议方案（以 proposal.md 为意图依据）——建议必须放在第二位，让用户先权衡。用户必须逐项回答；单独一个“ok”不算回答。每项都必须获得明确的解决方案或明确且有理由的延期答复——存在未解决的 HIGH 时不得继续。
   • **摘要：**上述问题解决后，将其他所有 DECISION 发现（MEDIUM 和 LOW）放入一条摘要消息中：每项都附上建议方案和一句理由。用户回复“ok”即接受全部；用户可明确指出任何例外。LOW 发现最多显示 5 项；其余留在 align.md 的 Known Issues 中，并在摘要中说明数量。最终仍未解决的发现须列入 Known Issues（“除非你希望处理，否则无需采取行动”）。这些问题不会阻塞本轮。
   • 两条消息都必须遵守 plain-language-writing 技能的 COMMS 规则。
9. 将本轮 ALIGN 结果追加到 align.md：包括发现（严重级别 x 类型）、已应用的机械修复，以及用户作出的决定（包括任何明确延期及用户给出的理由）。每条记录的决定和已解决的 HIGH 都要附上来源指针——文档和章节（例如“proposal.md > What Changes”）；apply 会先读取 align.md，并根据指针定位到确切内容。如果用户认为某项检查错误或噪声过大（lint 规则、某个维度、某个评审环节、变更规模问题），就在 Gate Records 下添加一行：记录门禁、输入、输出以及用户采取的行动（接受、推翻、编辑）。这能保留该门禁并为维护者提供数据。此处的文字必须遵守 plain-language-writing 技能的 ARTIFACT 规则。
10. 每项 HIGH 问题在 ALIGN 完成前必须有以下两种结果之一：已修复（通过机械方式或依照用户选择的解决方案），或由用户明确认定不在范围内并记录理由——这也算已解决，而非延期。仅仅说“以后再处理”并不足够；该问题的第 8 步解决讨论必须保持开放，直到达成这两种结果之一。只有当本轮映射中的每项 HIGH 都有上述结果后，才可继续 VERIFY。

VERIFY

ALIGN 会对自己的发现进行分类，并自行应用 MECHANICAL 修复，但没有独立的检查者来核查这些工作。VERIFY 通过一次全新的上下文复查来弥补这一缺口，并将资源用在最有价值的地方：发现了 HIGH 的周期。

触发条件。 仅当本周期的 ALIGN 至少提出一项 HIGH 发现时，才运行 VERIFY。否则跳过，并在 align.md 中记录此次跳过。MEDIUM 或 LOW 发现，以及 lint ERROR，均不会触发 VERIFY。在 47 次真实运行中的测量显示，此触发条件会跳过一些本可发现新问题的运行；WALKTHROUGH 是兜底措施。如果实践中出现漏检，请扩大触发范围。

1. 启动一个对上方 ALIGN 阶段毫无记忆的子 Agent：它只能接收当前状态下的产物（修复后）以及本技能 ALIGN 第 2 步的检查清单。它不会收到 ALIGN 生成的一致性映射、发现或解决方案。
2. 子 Agent 针对同样的 5 个维度（以及任何沿用的 walkthrough 项目）重新推导自己的 一致性映射，并报告：它发现了哪些 ALIGN 映射中遗漏的 HIGH，包括 ALIGN 将某项列为 LOW，但全新审查会将其判定为 HIGH 或 MEDIUM 的情况（即关卡遗漏的后果）；以及它能验证 ALIGN 应用的哪些 MECHANICAL 修复确实正确（修复符合产物当前的需求），哪些仍然错误或不完整。
3. 如果 VERIFY 没有发现任何新问题：继续执行 WALKTHROUGH。
4. 如果 VERIFY 发现 ALIGN 遗漏的 HIGH，或发现某项 MECHANICAL 修复并未真正解决问题：将其纳入本周期的映射中（与任何 ALIGN 发现一样，追加到 align.md），按照 ALIGN 第 8 步的规则解决（直接应用 MECHANICAL 修复；对于 HIGH DECISION，则针对该问题单独给出答案），然后继续执行 WALKTHROUGH——同一周期内不要再次运行 VERIFY；如果 WALKTHROUGH 重新发现问题，第二次漏检会由下一周期的 VERIFY 捕获。
5. 如果当前环境无法启动子 Agent：说明 VERIFY 无法运行，并询问用户是否要在不运行 VERIFY 的情况下继续执行 WALKTHROUGH。不要默默跳过此步骤。

WALKTHROUGH

ALIGN 和 VERIFY 用于验证各项产物彼此一致。两者都无法验证是否有人类读过这些内容——即使除了 Agent 之外没人看过内容，它们也可能找不到任何值得指出的问题。VERIFY 完成（或跳过）后，每个周期都运行一次 WALKTHROUGH，包括第一个周期，即使 ALIGN 和 VERIFY 完全没有发现问题也要运行。

一轮只问一个问题，顺序与评审者阅读时一致：

1. 展示一页摘要，按以下顺序排列：
   • **规格：**每项能力一行——说明它的要求，以及包含多少个场景。
   • **设计：**Decision 标题、Risks / Trade-offs 中的威胁描述，以及按名称列出的 Shape / Seams。如果其中列出了实际的 seam（而不是“no new code surface”），请让用户阅读该部分本身：这些 seam 是实现所依据的测试边界；如果边界有误，很容易被略过，因为它看起来像一份签名，而不是一种行为。
   • **覆盖表：**每个场景一行：场景 -> 任务组（来自 tasks.md 的 Covers:）-> seam（来自 design.md 的 Shape / Seams）。根据 lint 已检查过的链接生成；没有 seam 的场景显示“no seam”，且已作为一项发现提出。
   • **任务和提案：**各用一行，仅列出文件名；它们位于评审者首先阅读的规格和设计之后。
   • **规模事实：**将 lint 的 Size facts: 行作为纯事实列出（能力、场景、任务组）。不作判断。
2. 提出一个涵盖整份摘要的通用问题：询问用户是否希望更改这些文件中的任何内容，而不是要求其回答是或否。回答“没有”也有效。此问题必须遵循 plain-language-writing 技能的 COMMS 规则。
3. 在 align.md 的 Walkthrough log 中记录本轮：列出展示的文件，标注周期编号，并逐字记录用户的回答（包括回答“没有”）。

不要根据沉默，或用户在对话中回答了其他问题，就推断本轮已完成。必须单独提出一个涵盖整份摘要的问题，并记录其回答。

结束循环

WALKTHROUGH 一轮完成后（即本轮的问题得到回答），决定下一步：

• **本轮无反馈：**回答是“没有”。循环结束。继续执行 apply。
• **收到反馈：**回答提出了某些内容。开启一个新周期——在下一次 ALIGN 的一致性映射（步骤 2）中纳入这些反馈，并在那里解决（HIGH/MEDIUM/LOW、MECHANICAL/DECISION，与其他发现相同），然后使用新的摘要再次运行 WALKTHROUGH。
• **用户提前签字确认：**用户可以明确表示产物已准备就绪，无需继续进行后续周期。只有在至少完成一轮完整的 WALKTHROUGH 后，这才有效——它不能替代第一次 walkthrough，只能在实际完成一轮后结束循环。在 align.md 中记录签字确认（周期编号、用户的陈述），然后停止。
• **已完成三个周期：**如果第三个周期完成后循环仍未结束，询问用户是要继续还是签字确认（此处仍可通过 WALKTHROUGH 签字确认）。记录用户的回答。这是一个检查点，而不是上限——如果用户希望继续，循环就继续。

除上述情况外，不得继续执行 apply——不能仅凭 ALIGN、不能凭未完成的 walkthrough，也不能凭沉默。