silent-failure-catalog

# 静默失败目录（Silent Failure Catalog） 这是一个系统化目录，收录了**验证看似通过、实则未检查任何内容**的失败模式。它聚焦于CI门禁、测试套件、数据管道和AI代理工具链中的“假绿”或“验证缺口”问题。 ## 核心问题 > “一个永远通过的测试比没有测试更糟。它看起来像有覆盖率，实则毫无保障。” 崩溃会自我宣告，但静默失败不会。页面照常加载、DOI照常解析、流水线照常打印`PASS`、代理照常报告进度——**没有一处是红的，也没有一处是对的**。这些失败共有的特征是：系统缺乏“本应发生的事情没有发生”的信号。缺失、为空、跳过、未计数和错误归属的状态，最终都呈现为**成功**。 ## 目录结构 本目录包含**14个已命名的静默失败模式**，分为五个家族： - **A · 空洞验证（Vacuous Verification）**：检查运行了，但没有判别力（SF-001至SF-004） - **B · 未计数的缺失（Uncounted Absence）**：必需项缺失，但缺失不算失败（SF-005至SF-007） - **C · 错误证据（Wrong Evidence）**：所用信号无法证明所得结论（SF-008至SF-010） - **D · 漂移的预言机（Drifting Oracle）**：检查本身退化——豁免、子串匹配、错误归属（SF-011至SF-012） - **E · 流程与环境（Process & Environment）**：失败存在于逻辑之外——陈旧产物、僵尸进程（SF-013至SF-014） 每个条目都遵循统一的六部分结构：**症状 → 为何静默 → 最小复现 → 自检 → 修复 → 相关**。 ## 共同根因 所有家族本质上都是同一缺陷在不同层面的体现： > **把“没有证据”当成了“没有问题”的证据。** 由此得出两条最实用的规则： 1. **缺失必须进入退出码**——若“该有的没有”只记成日志、中性标记或跳过，那它永远产出`exit 0`，门禁恰好在最要紧处失明。 2. **没有阴性对照就没有证据**——一个从未被观察到失败的检查，没有被证明过它能失败。每个否定结论都需要一个阳性对照。 ## 快速开始 ```bash git clone https://github.com/zhaoxinghua09-cell/silent-failure-catalog.git cd silent-failure-catalog # 检查你信任的门禁/验证器/审计脚本 python tools/gate-lint.py path/to/your_gate.py # 验证目录本身内部一致 python tools/check-catalog.py ``` 两个脚本均为**纯标准库**实现——无需安装、无需联网，Python 3.9+即可。 ## 自带体检器（gate-lint.py） 该工具可扫描你自己的门禁脚本，识别这些静默失败模式，例如： - `SFL-001 no-nonzero-exit`：文件内无任何`exit()`/`raise`/`assert`，无法失败 - `SFL-002 swallow-exception`：`except`块仅执行`pass` - `SFL-003 unchecked-empty`：空/假值被当作正常处理 - `SFL-004 counter-does-not-gate-exit`：计数器从不影响退出码 - `SFL-005 zero-item-pass`：调用测试运行器但从不防范“0项收集” - `SFL-006 no-negative-control`：未发现阴性对照样本，无法证明检查能失败 低严重级别的发现会**在输出中明确标注为降级**，而不是静默丢弃——因为静默丢弃正是本目录所记录的失败。使用`--strict`可将低级别发现提升为非零退出。 ## 内容完整性 `INTEGRITY.md`和`manifest.sha256`为每个文件记录SHA-256摘要，并提供一个集合摘要，以便读者确认持有与本页描述完全相同的字节。`tools/make-manifest.py --check`在任何漂移时退出码为1。CI会强制要求在修改内容文件时重新生成清单，并故意损坏一个字节以验证检查确实能失败。 ## 贡献 欢迎在你能提供**复现**和**阴性对照**时提交新条目——仅有事件报告是不够的，因为它无法被机械检查。 ## 许可 本仓库采用分层许可：**代码为MIT**，**内容保留所有权利**（注明出处可引用）。