hellowind777/hello-verify

声称完成之前，必须有验证证据。 .helloagents/ 在本 skill 中统一按项目级存储路径理解：交付证据写入当前 state_path 所在目录下的 artifacts/*.json；若 project_store_mode=repo-shared，verify.yaml、方案包与 DESIGN.md 按当前上下文中已注入的项目知识/方案目录解析。

铁律

没有运行验证命令 = 不能说"完成"、"通过"、"已修复"。 没有看到验证输出 = 不能声称结果。

验证循环

验证不是一次性操作，而是循环直到通过：

任务完成
  ↓
运行验证命令（lint/test/build/typecheck）
  ↓
全部通过？
  ├─ 是 → 收集已激活技能的交付检查清单 → 逐项确认 → 报告完成
  └─ 否 → 反思 → 修复 → 重新运行验证（回到循环开头）

这个循环没有上限。验证失败就修复，修复后再验证，直到全部通过。 不允许在验证失败的状态下报告完成或询问用户是否跳过。

反思（验证失败时必须执行）

验证失败后，禁止跳过反思直接改代码。必须先回答：

1. 失败的根本原因是什么？
2. 之前的实现遗漏了什么？
3. 修复方案是什么？会不会引入新问题？

断路器

连续 3 次以上验证失败 → 激活 hello-debug 的卡住升级机制。

进展检测

声称任务完成时，必须有实际文件变更。如果 git diff 为空（没有任何文件变更），不能声称完成了产出文件的任务。

原子性自检

提交前检查变更范围：

• 如果单次变更涉及 >5 个文件 → 暂停，重新评估是否应该拆分为多个独立变更
• 用一句话描述变更内容，如果需要用"和"连接不相关的操作 → 拆分为多次提交
• 每次提交应该是一个原子操作：要么全部有意义，要么全部回滚

代码体积检查

变更涉及的文件必须符合 HelloAGENTS 编码原则中的体积控制规则：

• 文件/类 >300 行 → 评估是否需要拆分
• 文件/类 >400 行 → 必须按职责拆分（例外：生成代码、大型测试夹具、迁移脚本、协议常量表）
• 函数/方法 >40 行 → 评估是否需要拆分
• 函数/方法 >60 行 → 必须拆分

回归守卫

优化或新增功能不能破坏已有测试：

• 修改代码后，先运行已有测试确认无回归
• 如果新代码让指标改善但已有测试失败 → 修复回归（最多 2 次尝试），不修改已有测试
• 已有测试是底线，不能为了新功能而降低底线
• Bug 修复必须复跑最初的复现循环；如果没有自动化回归测试，必须记录替代验证和无法补测试的原因
• 新增或修改测试时，确认测试验证公共接口和用户可观察行为，而不是实现细节

验证命令来源

• 逻辑 .helloagents/verify.yaml 中的 commands（优先；project_store_mode=repo-shared 时按共享知识目录解析）
• package.json 中的 lint/test/typecheck 脚本
• pyproject.toml 中的 ruff/mypy/pytest

交付检查清单把关

验证命令全部通过后，还需要： 这些标记只用于交付检查清单、验收记录和验证结果，不用于普通说明、方案解释或进度汇报。

1. 收集所有已激活 hello-* 技能的交付检查清单
2. 逐项确认每个检查项，标记 [√] 并附带证据（如：src/api.ts:42 使用了参数化查询）
3. 不适用的项标记 [-] 并说明原因
4. 有未通过项 → 修复 → 重新运行验证循环
5. 若当前存在方案包并准备最终回复，优先调用 scripts/closeout-state.mjs write 写当前会话 artifacts/closeout.json，记录 requirementsCoverage 与 deliveryChecklist 两项结论；两项都必须包含 status（PASS / BLOCKED）和 summary
6. 若当前方案包要求 review-first，必须先确认当前会话 artifacts/review.json 已通过 scripts/review-state.mjs write 写成最新结构化证据；不要把审查自然语言消息直接当成交付证据
7. 若 contract.json 中 ui.visualValidation.required=true，必须确认当前会话 artifacts/visual.json 已通过 scripts/visual-state.mjs write 写成最新结构化证据；若没有视觉验收证据，不得把当前结果视为 UI 可交付
8. 本地版本检查点：非只读任务完成验证且产生工作区变更时，若 auto_commit_enabled=true，最终回复前自动执行本地提交；若 auto_commit_enabled=false，跳过这一步。先检查 git status --short；若不是 git 仓库或无变更则跳过。若发现 .env、密钥、凭据、明显不应提交的大文件或二进制产物，停止提交并说明风险；否则执行 git add -A，使用当前回复语言生成简洁 conventional commit message 后执行 git commit。显式 ~commit 不受这个开关影响。不自动远程 git push，除非用户明确要求
9. 若当前对话需要运行时识别验证收尾状态，优先调用 helloagents-turn-state write --kind complete --role main；若因阻塞判定等待输入或因前置条件缺失而停下，写 kind=waiting 或 kind=blocked，并同时写 reasonCategory 与 reason；显式 ~auto / ~loop 下还要写 blocker.target、blocker.evidence、blocker.requiredAction，不要让运行时从自然语言消息里猜状态

需求追踪验证

如果有方案包（requirements.md），执行完成后必须交叉检查：

1. 逐条读取 requirements.md 的需求（核心目标、功能边界、质量要求）
2. 确认每条需求都有对应的任务实现，没有被静默丢弃
3. 确认非目标章节列出的内容确实没有被实现（防止范围蔓延）
4. 若 tasks.md 中定义了“完成标准”，逐项确认每个任务的完成标准确实成立，不能只因为代码存在或命令通过就视为完成
5. 若存在 contract.json，逐项确认其中的 verifyMode、reviewer / tester 关注边界都已被本次验证覆盖
6. 若 contract.json 中 advisor.required=true 或 ui.styleAdvisor.required=true，额外确认当前会话 artifacts/advisor.json 已存在且结论为 clean；若没有 advisor 证据，不得把当前结果视为可交付
7. 若 contract.json 中 ui.visualValidation.required=true，额外确认当前会话 artifacts/visual.json 已存在、覆盖要求的关键 screens / states，且结论为 PASS；若没有视觉验收证据，不得把当前结果视为 UI 可交付
8. 发现遗漏 → 补充实现 → 重新验证

目标偏移检查

验证时必须区分真正目标和代理指标：

• 真正目标：用户实际要解决的问题（功能正确、体验达标、需求满足）
• 代理指标：测试通过、lint 干净、类型检查通过、diff 整洁

代理指标全部通过 ≠ 真正目标达成。验证时必须回答：

1. 用户的真正目标是什么？
2. 代码是否真的实现了这个目标？（不是"测试说通过了"，而是"功能确实能用"）
3. 是否存在测试通过但功能实际不工作的情况？（如：测试 mock 了关键依赖、测试只验证了 happy path）

目标反向验证

不要从"任务完成了吗"出发，而是从目标反向推导：

1. 明确阶段目标（用户要什么结果？）
2. 反向推导：要达成这个目标，哪些条件必须为真？
3. 逐条验证每个条件，使用四级验证深度

四级验证深度

每个关键产出必须通过四级检查：

1. 存在 — 文件/函数/组件确实存在
2. 真实 — 包含真实实现（不是 stub、TODO、placeholder、空函数）
3. 连接 — 被其他代码导入/调用/使用（不是孤立的死代码）
4. 数据流 — 有真实数据流过（API 返回真实数据、UI 渲染真实内容、事件真实触发）

未通过任何一级 → 视为未完成，必须修复。

危险信号

以下想法意味着你在合理化跳过验证：

• "应该没问题了" → 运行验证
• "我很有信心" → 信心 ≠ 证据
• "linter 过了" → linter ≠ 测试 ≠ 构建
• "代码改了应该修好了" → 运行验证确认
• "就这一次跳过" → 没有例外
• "问问用户要不要跳过" → 不允许，必须修复
• "先写完再测" → 未经测试的代码是负债不是资产
• "已经手动测过了" → 手动测试无记录、不可重复、不可回归
• "太简单不需要测" → 简单代码在复杂系统中照样出错
• "这次例外" → 每个例外都成为先例
• "用户没要求测试" → 质量是底线不是选项

五步证据链（每次声称完成前必须走完）

1. 识别 — 确定哪个命令能证明你的声明
2. 运行 — 完整执行该命令
3. 阅读 — 审查完整输出和退出码
4. 验证 — 确认输出确实支持你的声明
5. 声明 — 附带证据报告结果