Harness 可靠性审查标准
本文件是 skill-lint 对“Skill 是否能稳定完成任务”的单点真相。它适用于创建前设计预检、重大改造和发布前验收。格式合规、提示词写得详细或 Agent 自报“已完成”，都不能单独证明功能可靠。
本文件定义通用七层模型和候选绑定证据；旧版 Skill 识别、逐约束追踪、验证模态/产物阶段匹配和多轮漂移门禁见 instruction-stability-standards.md。两者互补，不复制规则。
一、边界：Skill 不是全部 Harness
稳健 Harness 至少由四类部件组成：
- 生产契约：说明输入、输出、副作用、失败语义和例外边界。
- 执行器：真正完成任务，且不越过权限、依赖和作用域边界。
- 独立验证器：不采信执行器的自报结论，检查真实产物和不变量。
- 闭环与适配层：绑定当前候选、记录证据、关闭任务，并把项目差异留在薄适配层。
skill-lint 可以审查上述部件是否存在、边界是否清楚，也可以验证审查证据是否仍对应当前候选；它不能代替每个业务领域自己的正确性验证器。
二、七层可靠性模型
| 层 | 必须回答的问题 | 可观察证据 |
|---|---|---|
| Contract | 输入、输出、副作用、失败和例外是否明确？ | 结构化契约、Hard Fail、验收标记 |
| Producer | 执行步骤是否真实可运行，权限和依赖是否受控？ | 脚本、命令、实际产物、错误退出码 |
| Verifier | 谁独立判断通过？是否检查产物而非自报？ | 独立 gate、active checker、失败日志 |
| Evidence Binding | 证据是否绑定当前候选和当前规则？ | 完整文件清单、SHA-256、策略清单 |
| Fault Injection | 已知失效和逃逸路径是否会被挡住？ | 正例、反例、历史回归、阻断日志 |
| Closure | “完成”是否需要证据并能在状态变更后重算？ | finding/task 状态机、关闭依据、合并后复算 |
| Composition | 与其他 Skill 的输入输出和责任边界是否可组合？ | 版本化接口、交接产物、薄项目适配器 |
成熟度判断
- L0 叙述型：只有原则或提示词，没有可执行流程。
- L1 可执行：能产生结果，但主要依靠执行器自检。
- L2 可验证：有独立验证器和明确 Hard Fail。
- L3 可追溯：证据绑定当前候选和规则，陈旧或空证据 fail-closed。
- L4 可组合闭环：跨 Skill 契约清楚，任务状态和持久化完成可复算。
总体成熟度不得高于必需层中的最低层；不能用平均分掩盖一个 Hard Fail。并非每个 Skill 都必须达到 L4，但凡声称“稳定完成”“可交付”“已验收”，至少应达到 L3。
三、创建或大改 Skill 时的预检
在写大量提示词或脚本前，先产出一页 Harness 设计：
- 列出最容易出错的 3—5 个结果属性，不以“认真检查”“确保完整”等动作词代替。
- 为每个属性指定生产者、验证者、证据和失败后的回炉动作。
- 明确哪些结论可机器判断，哪些只能由人作语义判断；客观项用硬门禁，主观项保留告警和人工复核。
- 写出至少一个正常样例、一个失败样例和一个可能逃逸的反例。
- 决定完成标记由谁产生。执行器不得给自己签发最终通过状态。
- 若需要组合其他 Skill，先定义交接文件、字段、版本和错误语义；项目差异写入薄适配器，不复制核心规则。
若上述信息缺失，先补设计，不直接扩大提示词篇幅。
四、Hard Fail
下列情况默认按严重问题处理：
- Skill 声称“已完成、已验证、可交付”，却没有独立可执行验证路径。
- 验证器只读取执行器自写的
PASS、勾选框、报告结论或任意 JSON，不检查真实产物。 - 证据未绑定当前候选；候选变化后旧证据仍可通过。
- scope、规则读集或候选清单为空，存在未知检查器、检查器异常、证据缺失时仍 fail-open。
- 仅测试正常样例，没有反例、历史失效回归或逃逸路径测试，却声称具备稳定门禁。
- 有写入、删除、联网、安装、外部发送等副作用，却未声明权限边界、确认点和失败/回滚策略。
- 管理任务或 findings 的 Skill 仅凭文字自报关闭，没有状态转换条件和证据引用。
- 跨 Skill 编排依靠隐含上下文，没有交接契约、版本边界或责任归属。
- 已知生产器、模板或验证器曾发生缺陷，修改后没有把该缺陷固化为回归用例。
- 硬约束没有稳定 ID，无法追踪到 checker、产物阶段和 case，或只因“存在某个 checker”就声称全部要求已覆盖。
- 几何、视觉、交互或状态约束使用不匹配的验证模态，或 checker 检查的阶段早于约束要求的最终/渲染阶段。
- 声称多轮稳定、不会漏项或产出不漂移，却没有 evaluator-signed 外部硬约束基线/held-out、当前 Harness evidence，或没有至少三轮同输入/配置、唯一 nonce/签名 producer log 的真实产物逐约束 active checker 证据。
五、警告与人工判断
以下问题通常先记为警告，除非项目规则提升为 Hard Fail：
- 语义标准宽泛，多个审查者可能得出不同结论。
- 例外边界没有最小化，容易把真实缺陷豁免掉。
- 只有示例测试，没有属性测试、变形测试或代表性边界样例。
- 核心规则在多个 Skill 或项目文档重复，缺少单点真相。
- 动态验证依赖某个未披露的本机工具或外部服务。
不得把主观判断伪装为精确分数。报告应写清“已验证”“仅静态推断”“未验证”三种证据等级。
六、具体失效模式静态审查
scripts/harness_failure_audit.py 是七层模型的确定性预筛，不执行候选代码。每条 finding 固定包含 ID、严重度、置信度、类别、相对文件、行号、证据、影响、修正建议和 detection level；同一规则在同一文件内聚合，避免逐个 || true 刷屏。
| ID | 失效族 |
|---|---|
| HFA-001 / HRA-001 | 生产 checker 异常被吞；测试/eval 丢弃真实退出码 |
| HFA-002 | process substitution 或结果管道没有传播 checker 退出状态 |
| HFA-003 / HFA-004 | 失败后无条件成功声明；`grep -c ... |
| HFA-005 / HFA-006 | 项目 state 固定在 Skill 根；声明状态副作用但入口未写入 |
| HFA-007 / HFA-013 | baseline/multiplier 未进入执行路径；config-driven 声明与硬编码漂移 |
| HFA-008 / HFA-009 | 未知参数静默忽略；配置、YAML 或动态正则错误 fail-open |
| HFA-010 | raw printf 拼 JSON 且未转义/解析 |
| HFA-011 | checkout/commit/push/PR 绕过 worktree、身份核验或真实 URL 回执 |
| HFA-012 / HRA-002 | 破坏性 trim/rewrite 缺数据守恒实现与幂等回归 |
静态命中证明存在可复查风险，不证明所有运行路径必然失败；没有命中也不等于动态行为已验证。未知候选默认停在本层与 assess 的 NOT_VERIFIED。动态故障探针须另行取得可信候选确认，在临时副本和最小环境中运行，并禁止自动安装或联网。
批量模式递归发现 SKILL.md，排除 archive、版本控制目录、缓存与依赖目录；发现零 Skill 必须 BLOCKED，不能把空范围判 PASS。普通文档中历史提到 SVG/figures 不构成视觉生产约束；只有 SKILL.md / references 中规范性硬要求与视觉/几何语义局部共现，才触发视觉模态审查。
七、候选绑定审查证据
正式创建验收或重大改造复查时，使用：
python3 scripts/harness_evidence_gate.py snapshot \
--candidate-root /path/to/skill \
--output /path/to/review/harness-review.json填写 JSON 中的 layers、hard_findings，以及候选 Skill 内要运行的 checks / fault_cases。每项动态用例只声明 runtime、候选内 checker、参数、超时；故障用例另声明具体非零预期退出码。不要填写或采信 exit_code、result、observed、PASS 或既有日志。然后执行：
python3 scripts/harness_evidence_gate.py verify \
--candidate-root /path/to/skill \
--evidence /path/to/review/harness-review.json \
--confirm-trusted-candidateverify 只允许用户已确认的自有/可信候选，并要求显式传入 --confirm-trusted-candidate。它会使用 shell=False 和最小环境白名单亲自运行候选清单内的 checker，不继承 Token、云凭证等任意环境变量；正常检查必须返回 0，故障用例必须返回声明的具体非零退出码。未知 runtime、未知 checker、超时、无审计输出、退出码不符以及 checker 修改候选或策略都会阻塞。当前支持 python3、bash、sh 和 node，checker 后缀必须与 runtime 匹配。
只有退出码为 0 且输出 HARNESS_REVIEW_VERIFIED，才能说“当前候选的 Harness 审查证据已验证”。该标记证明：候选与规则读集未漂移、七层结论完整、检查器和反例在本次运行中得到预期退出码；它不等于业务功能本身已被通用脚本证明正确。
若交付进一步声称“多轮指令遵循稳定”“不会漏掉指定维度”或“关键产出不漂移”，还必须按 instruction-stability-standards.md 取得最终签名并通过 verify-receipt 复验的 INSTRUCTION_STABILITY_VERIFIED。动态 verify 的 EVIDENCE_READY 和一次 checker 通过都不能推断重复执行的覆盖稳定性。
证据文件必须放在候选 Skill 目录之外，避免自引用清单。动态运行前先完成静态安全审查，向用户披露将执行的 checker；门禁不会运行 shell 字符串，也不会自动安装依赖。最小环境不是沙箱：checker 仍可能访问本机文件系统和网络。未知第三方候选不得在普通工作区动态执行；未进入用户明确授权的隔离环境时，只能给 NOT_VERIFIED。候选文件或策略文件变化后旧 snapshot 必须失效；复查时必须重新执行 verify，不能复用上次的输出标记。
八、完成结论
报告中的完成结论只能使用以下四类措辞：
HARNESS_REVIEW_VERIFIED：候选绑定的审查证据完整且当前有效。INSTRUCTION_STABILITY_VERIFIED：evaluator Ed25519-signed 外部硬约束基线/held-out、候选与 producer 运行记录和最终回执已由受信公钥复验，至少三轮真实产物逐约束通过，measurement 阈值满足且关键 observable 未漂移。DOMAIN_VERIFIED：目标 Skill 自己定义的业务验证器通过；必须同时给出验证器和产物证据。NOT_VERIFIED：仅完成静态检查、语义评议或证据不完整。
若一个交付声称稳定和业务正确，应要求前三项同时成立。任何未运行的检查不得写成“通过”。
九、设计理念
- 生产者不能给自己发毕业证：执行与验收必须在责任和数据来源上分离。
- 规则必须落到可观察属性：动作清单容易被表面执行，属性和不变量才能被独立复查。
- 证据必须属于当前候选：不绑定文件和策略哈希的 PASS 只是可复用文本，不是证明。
- 每次事故都应降低下一次复发概率：已知失效如果没有进入反例库，Harness 就没有真正学习。
- 通用层保持通用，项目层保持薄：核心 Skill 承载稳定契约，项目只声明范围、阈值和少量例外。