验证证据纪律

概述

验收的目标不是"看起来全绿"，而是"绿灯可信"。本技能把"完成 / 已修复 / 真的生效"这类主张，变成可失败、可核对的证据。

复核模式（RECHECK）：用户说再次检查 / 重复检查 / 循环检查时

这不是"再做一遍同样的检查"，而是针对上一轮结论的加强复核。

触发与不触发

• 触发：再次检查、重新检查、重复检查、循环检查、复查、再复核、再验证、再确认、再核对等明确复核请求；或用户质疑上一轮"已修好 / 已完成"的结论。
• 不触发：首次"检查一下 / 帮我看看"；否定句"不用再次检查"；把触发词当例句、关键词或规则文本引用；只要求"再跑一遍"某个命令。
• 无法确定用户是在引用还是在下指令时，先一句话核对意图，不自行升级为复核模式。

三类历史资料

静态内容可以重新读取核对；当前运行状态必须本轮重新观测。哈希一致只证明内容未变，不能证明功能正确或进程已加载新代码。

六步

1. R1 冻结范围与权限：复述对象、待证结论、范围外项；默认只读，未获授权不改文件、不植入磁盘缺陷、不重启服务。
2. R2 建立待证清单：从本轮需求、当前实现/入口、旧报告三方建立清单，逐条写成可失败断言；旧结论标"待证假设"，并专门列出旧报告未覆盖的空白。
3. R3 取得本轮原始证据：重新读取当前文件、入口、配置、运行状态、产物或远端事实；记录命令、退出码、作用域、时间和哈希。
4. R4 多角度复核：关键行为至少用两种不同盲区的方法（静态 / 运行 / 第二入口 / 外部来源）；负对照用来证明方法能区分错误，不自动算第二条独立证据；同一执行路径、同一份错误快照或同一夹具的重复执行不算多方法。
5. R5 处理冲突与盲区：新旧结论不一致时先归因（历史错误 / 环境漂移 / 产物过期 / 量具缺陷 / 真实回归 / 范围差异），用隔离变量证明；检查上次未覆盖的负向、边界、未验证项和范围外项，并检查量具是否真正驱动入口。
6. R6 循环与收敛：再次检查只做一轮加强复核；循环检查每轮记录覆盖变化、证据变化和剩余问题。范围覆盖、关键结论有适配证据、冲突已处理、反例可识别且复扫无新未处理问题时，才能说"在本轮覆盖范围内收敛"；否则列出未验证项和原因。

报告固定五段：结论（已复核 / 部分复核 / 未复核）、待证清单与结果、差异与新发现、未验证项 + 原因、证据入口。小任务直接给表；大交付可落 VERIFY-RECHECK.md；多证据类型报告转 evidence-audit.cjs 的 JSON 审计。详见 references/recheck-protocol.md。

禁止：把旧报告 / 旧日志 / 文档字样当本轮证据；用同一方法重复执行冒充多方法；把负对照算作独立证据；只读请求顺手改代码；用"又跑了一遍还是绿"宣布复核通过；用轮数代替覆盖收敛；把"未验证"混进"已验证"。

通用检查与排错顺序

1. 明确要检查的声明：保留原问题、对象、范围、任务模式与验收；把“准确普适”拆成可检验的具体结论，不替用户增加需求。
2. 核对现场与实际入口：分清规则/代码存在、调用方真的使用、运行时发生、最终产物包含四件事。先读本轮原始记录、参数与产物，不用旧日志或目录名反推现场。
3. 分开事实与假设：列观察到的事实、竞争假设及各自反例。期望值来自独立的需求/协议/人工核对，不从被测输出倒推；看似合理的归因仍标假设。
4. 隔离变量与做对照：围绕一项假设只改变一个变量；保留正常基线和已知异常输入/缺陷对照，记录本轮作用域、输入、实际输出、退出码与未跑完项。负向用例可以正常退出，关键是实际观察与预期可区分；崩溃/超时不是成功的反证。
5. 判断是对象还是量具的问题：分别归类真缺陷、检查器假红/假绿、前置缺失、范围外版本差异和未覆盖情形。先检查取错目录、切片边界、控制组相同、匹配过宽、错误码被管道吞掉等量具缺陷；仅复跑成功不足以证明根因。
6. 最小修复并回归：只修已证实且获授权的差异，保留其他会话修改；重跑对应正负用例和受影响回归，按证据类型报告成立项、未验证项与范围外项。不把静态检查、模拟推演或文件操作成功称为真实交互验证。

证据类型不是线性高低等级

检查能力时先审读检查器是否真正驱动入口；自拟夹具编辑只证明文件操作，模拟问题没有实际提问/答复记录就不能报真实问答通过。模型/API排错同样先核对真实请求、响应和协议，每个假设用隔离变量对照；不从状态码单独推断凭据、客户端或额度原因，不自动改连接配置。

只读证据审计入口

复杂交付或涉及多个证据类型时，将本轮实际记录整理为报告并使用下列审计；小而可逆的任务仍按原验证强度配比，不强制造报告。缺少原始记录时先补采或标未验证，不编造材料凑通过。

node ~/.qoder/scripts/evidence-audit.cjs <report.json> [--json]

脚本只读取报告目录内的声明记录，不执行报告里的命令、不连外部服务、不自动修改规则。单次只审一份报告，多传路径报参数错误；最多100个检查项，每个JSON不超过2MiB，默认只显示前20个问题，完整结果可用 --json。

{
  "schema": 1, "task": "本轮任务", "runId": "本轮唯一标识", "cwd": "本轮工作目录",
  "checks": [{
    "id": "contract", "claim": "具体可失败声明", "status": "verified",
    "requiredLevel": "static", "changedVariable": "仅换成已知缺陷输入",
    "positive": {"file": "positive.json", "sha256": "替换为记录的64位SHA256", "expect": {"exitCode": 0, "stdoutIncludes": ["PASS"]}},
    "negative": {"file": "negative.json", "sha256": "替换为记录的64位SHA256", "expect": {"exitCode": 1, "stdoutIncludes": ["FAIL"]}}
  }]
}

• 先独立确定 expect，再实际执行并保存正负记录；SHA256用于冻结记录，不是功能正确的期望值。记录必须有 schema:1、runId、cwd、level、termination、exitCode、stdout、stderr；termination 区分 completed/skipped/timeout/crashed。
• requiredLevel 与记录 level 必须对应；不能用 static/simulation/artifact 记录证明 runtime。日志中的level标签仍由采集者声明，必须人工核对来源。
• status 为 unverified/hypothesis 时给 reason，返回 INCOMPLETE；excluded 必须有 reason，单独列出且不算通过；有已接受项和排除项时返回 PARTIAL（退出1），全空/全排除为 INCOMPLETE，均不能宣布全绿。
• PASS/退出0仅表示本报告每项证据要求与所给记录一致；正负预期必须交叉核对，若一套预期也匹配另一组记录即拒绝，不能仅因日志时间戳不同判对照有效。缺证、对照失效、输出不符、哈希或轮次变化返回1，坏报告/参数返回2。
• 审计不证明记录未被伪造、预期独立、验收范围完整、排除项有授权依据、因果归因正确或模型普适；这些仍须核对原请求、真实入口、用户答复和实际运行。
• 自测：node ~/.qoder/scripts/evidence-audit.test.js。流程可跨任务复用，技术栈特有探针留在各领域技能；不新建第二份验证总纲。

文稿语义与工具存在性

文稿改写

逐段对照原文的主体、动作、对象、条件、否定、比较、确定程度和完成状态，再核对数字、标题、命令与链接。数字集合不变、术语零命中或条数一致不能替代语义核对。

• 正例：描述模型重复试错时，保留“模型换个方式又从头踩一遍”。
• 反例：“换个人又从头踩一遍”把模型行为改成了人的行为，即使数字完全没变也应退回。
• 合法人类场景：作者判断、同事反馈、人工解锁和使用者安装体验不能被机械改成模型行为。
• 检查器只证明其覆盖的文本契约；逐段读懂另行完成，不宣称脚本已经验证了所有语义或所有模型行为。

“没有工具”的位置断言

先查已记录的安装入口，再核对启动器、注册入口和获准候选目录；PATH 只是一项线索。用绝对路径执行，并核对实际版本、解释器自报路径和当前用户 profile；不要遍历全盘或修改权限寻找工具。

Windows 可只读查询 py 启动器列表与 PythonCore 注册项；分别记录解释器、库和外部二进制是否可用。exit=0 但无版本输出只能判未验证，不能直接断言商店别名；访问被拒也不等于未安装。用已知存在路径和不存在路径作对照；旧结论被推翻时就地纠正，不把当前机器的版本写成通用规则。

真实代理与领域关联

沿 UI 动作、前端 service、代理和后端入口追到需求规定的权威实体与关联键；界面名称不决定后端实体。核对默认数据源和 localStorage 等运行时覆盖，构建后在本轮 dev server 查看实际代理日志与请求。

分别验证根页面、真实接口、静态文件和不存在路径；区分代理可达、鉴权跳转、业务成功与领域关联正确。不能把 HTTP 200 或 302 当成业务联调完成。关联率要有独立分母、真实期望键及不匹配负样本；缺少合法票据或真实数据时明确标未验证，不造模拟数据填补。

部署后回归的取证边界

• pid.log 可能过期，先只读核对监听端口、PID、启动命令与时间；取证不授权停止服务，核心服务启停仍单独批准。
• 注册查询使用现役配置的 namespace、group 和 profile；默认命名空间里的空列表不能证明目标服务未注册。端口 LISTEN、Started 标记、注册 healthy、版本指纹和业务成功分别取证。
• JAR 含变化的打包时间时，整包摘要不同不能单独证明代码不同；继续对比候选包内目标 class 与资源的 SHA-256，不因此放弃整包完整性检查。
• 未改动兄弟接口收到相同报文也失败，只支持“输入或共同依赖可能有问题”，不能证明与本次回归无关。补核接口各自的契约、完整请求、共享调用链，再用原版/新版或单个输入变量作对照；证据不足保留根因未定。

一、每条断言都必须能失败

写完任何断言（测试、探针、检查脚本）先问一句：它失败得了吗？

已知会永远为绿的具体形态，逐个排查：

• 在被测状态之外还有别的门槛挡着（例："免战期不许出击"因新手保护自带免战，不用道具也通过）
• 时间边界夹具只留 1ms 余量，执行耗时自己跨过去
• 选错时刻让两个值落在同一周，断言等于没写
• if 成功 else 断言失败 这种两边都算过的分支

二、启动与 HTTP 验收的固定判据

"curl 通了"本身不构成证据。以下必须同时成立：

1. 本轮编译退出码是验收判据的一部分 —— spring-boot:run 会静默复用上次编译留下的类，本轮 install/compile 已经红了，启动横幅与 HTTP 验收照样全绿（那时验的是旧进程）。Started Application 单独不算证据。
2. 打出启动横幅的是本轮自己起的那个进程。
3. 请求打的是本轮独占的端口 —— 并发会话的服务可能正占着默认端口，请求被它答了就是假绿灯。默认端口被占就换端口起，不要去杀别人的进程。
4. 对照组：同一份脚本里顺手请求一条故意编造的路径。有些工程"路由不存在"并不返回 404，而是被统一异常处理包成业务码信封（如 code=13000）—— 确认被验的几条回各自该回的业务码、编造路径回"接口不存在"，两者不同形，这批证据才成立。前端 SPA 更甚：任意路径都回 200 text/html，必须用 content-type / 特征串区分。

代理、流式链路与版本证据

• 使用隔离的可信本地 TLS 上游和独占端口，原版与修订版跑同套断言；为旧版补偿依赖或路径时明确列出，不改变正在比较的逻辑。不要关闭生产 TLS 校验来使夹具通过。
• 先核对夹具自身的事件顺序，再归因取消或超时；测试先触发 aborted 造成的断连不能算被测代理缺陷。记录何时完成上传、开始响应、主动取消和出现终态。
• 分别证明本地健康、HTTP 响应头成功、流完整结束和模型生成成功；四者不能相互替代。SSE 须按具体协议断言完成事件、工具参数完整性及正常结束，中途断流或缺完成事件均不得报成功。
• "上次已经修过、用户说还是坏"先证运行态 == 磁盘：任何常驻进程 / 守护 / sidecar 的修复，先做三条比对再谈逻辑缺陷——① 进程启动时间 vs 文件 mtime（晚于启动的改动不可能生效）；② 服务自带的版本端点（或 /_health 回显的源码 sha256 前 12 位）vs 磁盘文件哈希；③ 不一致即判"新代码未被加载"，重启后复验版本一致才算修好，只看到"进程还在、端口还在"不算。Windows 下按精确 PID 停启与接管确认见 local-reverse-proxy-triage。
• 磁盘版本与现役进程版本要分别核验：文件 SHA-256 只证明写盘成功，运行版本须有本轮可关联的启动记录或版本指纹。未经批准重载的修订版应写「代码已验证，现役未生效」，不能为补证据擅自重启核心服务。
• 新实例在独立端口成功，只证明实例状态差异；CLOSE_WAIT 或上游连接数也只是线索，不能直接认定旧实例连接池卡死。因果结论需要进一步隔离变量及反证，否则保留为假设。

流式 / 分块文本识别专项验收

• 单测全绿不等于矩阵全绿：主入口的完整字符串用例可能漏掉其它入口与字节切分。先列全部入口/分支，做跨分支反例矩阵（实测 31 例独立矩阵里 27 例失败，而原单测全绿）。
• 真实分块测试要有接收确认：先等子进程确认收到首段，再发余下字节，最后比较完整输出；不要一次 write 完就当作分块。至少覆盖两种字段切分与两种字节切分（含汉字跨块）。
• 合法密集输入也要有性能判据：密集引文/长文本可能耗时十几秒；给出可接受上限与实测耗时，不能用“功能对”掩盖超时。
• 末轮发现的问题会让前面证据失效：同一语义在另一分支复现同类缺陷时，已跑过的矩阵要按新增反例重跑；不能保留“之前全绿”的结论。
• 同族语义覆盖所有入口：修一处后扫一片（所有调用点/所有模式），并给每个入口一条能失败的断言。

差分回归证据

• 需要“修前红、修后绿”时，不要回退工作树：用 git show HEAD:<path> 取原版副本到独立目录，补齐同目录依赖（如 client-root、测试导出），保持被测逻辑不变。
• 先在原版上复现缺陷（原版必须判红），再在修订版上验证修复，最后跑全量回归；隔离 HOME，记录命令、退出码与全树 SHA-256。
• 区分量具故障与产品缺陷：HEAD 副本缺依赖、标签重名、索引前置缺失都会造成假“未复现”；先排除这些再下结论。
• 只读审查的零写入探针见 counterexample-driven-plan-review。

三、计数断言先列"会改世界的操作"

"某集合应有 N 项"是最容易永远红的断言，因为同一条用例在被断言之前还会改世界。写计数断言时，把该行之前所有会增删对象的操作列一遍再定数字；并确认这个数字在摘掉被测过滤后仍会变红。

实测案例：用例先解散一个国家、随后又成功新建了第五个，"活国列表"实际是 3，而不是按前半段推算的 2。

四、多出来的红先归因自己

探针跑出"比瞄准的那条更多"的红时，不要当成额外战果 —— 多出来的红通常是新断言自己算错了。逐条归因后再判断哪些是真缺陷。

五、检查器与探针也会撒谎

自己写的计数型检查同样不可信，固定动作：

• 每写一条计数型检查，先植入一次违规看它报红。
• 给文件数 / 字节数 / 命中数加下限断言 —— 0 命中是故障，不是结论（曾把"全部匹配失败"当成"全部未使用"交付）。
• 豁免必须写成可被证伪的出处（指向必须真实存在的清单行或规格文件，由检查器去核对），否则就是给自己开免检口子。
• 会误伤合法用法、需要大段豁免名单才能绿的检查，主动不做。
• 按行切片的检查器注意：整行 catch (X e) { return MAX; } 会被丢空、删注释不保留换行会让行号指向无辜文件 —— 报出的位置先自查。
• 植入违规时要把"崩"改成"红"：让检查器跑到真实回归上，如果它抛异常退出，退出码会与"工具自己坏了"同形，读的人只会重跑一次而不是去查代码。判据要逐条干净报 FAIL 并用不同的退出码区分（约定：判据失败 = 1，前置不满足 / 量具自身异常 = 2 并打出修复命令）。缺失的前置对象要让相关断言退化成 FAIL，不要让它们把整轮带走。
• 函数名不是验证：见到 verifyXxx / 判据函数，先读它的函数体——只做本地数组计数、直接 pass: true、读回刚赋进去的对象、检查刚初始化的空集合，这四种"证明"在被测系统完全没跑起来时也全绿。自查问句：它读的是被测系统，还是它自己刚写进去的夹具？ 读自己 ⇒ 伪验证，要么改成真驱动，要么显式标 UNVERIFIED（pass:false）并让整体 allPass=false。
• "记录了测量方法"不等于"完成了测量"：容量 / 性能 / 覆盖率这类验收最典型的假绿——脚本只要命令退出码 0 就报 PASS 并打印"测量完成"，实际一个数据点都没采。固定动作：让"缺少原始数据"走 FAIL 或 INCOMPLETE 路径并以非 0 退出，自测覆盖"缺报告 / 零测试 / 跳过 / 失败"各情形。
• 跨平台 dry-run 不应执行平台安装守卫：Windows 资产在 Linux CI 上跑 --dry-run，预览阶段只提示平台限制，执行阶段仍在动手前拒绝。回归用 --require 桩覆盖 process.platform、spawnSync 与网络，断言预览成功且配置不变；同时断言非 dry-run 仍拒绝。只测“dry-run 过了”或只测“执行被拒”都不完整。

六、文档里的"已完成"不等于运行时发生

策略函数写得再讲究、单测再全，生产链路没有调用点就是没做。判"某项是否完成"要去找调用点与承载数据（谁调用、输入从哪来），而不是看函数 / 配置项在不在。同理：写好的机制要顺手确认"默认真的会跑"（默认 false 的开关、声明了没人读的能力）。

脚本、卡片勾选、台账三处口径必须同批对齐：脚本判据改成 UNVERIFIED 之后，验收卡片的 [x] 与台账状态要同批撤回；文档勾选跑在脚本前面单独"完成"，就是脱节信号。收尾汇报前把三处对一遍，对不齐就把差异写成"未验证"。

七、标注未验证项

拿不出可失败证据的结论，单独写明"未验证 + 原因"，不要让它跟着别的结论一起被读成"已验证"—— 读者会把整段当作同等强度，沉默就是夸证。写"未验证"不扣可信度，只让其余部分更可信。

被前置门槛（等级、资源、真实登录）挡住、造不出成功路径时同样明写："真 HTTP 只验到守卫链，成功那一段的证据是进程内用例"。

八、验证强度配比任务体量

• 小而可逆的运维操作：一次编写 + 一次执行 + 一条属于本轮且能失败的判据，够了就汇报。不要为验证连环开新查询 / 新脚本挤掉主线。
• 有交付物的实现任务：要"可信的全绿"，按第二节执行。
• UI 功能：另见 verify-ui-in-browser 技能。
• 按难度选档（可选，未启用时不用）：用户要求选择验证方式或已明确启用本任务流程时，按 选档流程 准备事实、展示当前完整提案和四项选择，再绑定真实答复；assisted 执行所选清单，shadow 执行基线与所选并集，人工不自动运行且保持未完成。取消/未答复不默认选择，选档不豁免本节其余要求；仓库入口不代表现役装载，也不授予安装、启用或发布权限。

九、输出形式跟随任务规模

• 小任务：回复里给简短清单 —— 成立项 / 未验证项 / 对照组结果，不落盘文件。
• 大交付（PR 级）：除对话清单外，可落一份验收报告文件（如 VERIFY.md）随交付提交。

十、边界

本地可逆动作（跑测试、写探针、改文件）自主推进；对外可见 / 不可逆动作（推 PR、撤回、删数据、改共享配置）先把发现与选项报告给用户，等拍板。