# Known Failure Prevention

本项目把历史失败分成“执行前可判定”和“只能运行后判定”两类。前者必须在
scheduler/CMake/WASM gate 之前拦截，后者只允许一次受控重试并保留原始 evidence。

| 失败模式 | 提前防线 | 结果 |
| --- | --- | --- |
| stale context / batch mismatch | `preflight_current_module_batch.py`、continuation checker、context fingerprint | 不启动代理，先重规划 |
| 旧 gate 硬编码 batch | 当前 manifest 驱动、`batchId`/记录集合校验 | 不重复旧批次 |
| `method_evidence_pending` 被误认为完成 | evidence index v4 仅把 module-batch 记录加入 pending；支持顶层和 `result.records` | 历史 family evidence 不再阻塞新批次 |
| `passed_boundary` 漏记 | 统一终态集合 | 边界记录只处理一次 |
| ESM/CJS worker 错误或旧 `.worker.cjs` 被复用 | `tools/wasm-probe-runtime.mjs` 统一 build/bin 归一、按 size/mtime 刷新 CJS staging，并通过 `locateFile` 指向 staging | 避免 Node loader 失败和陈旧 pthread bootstrap |
| 缺失 OCCT archive | `check_web_link_closure.py` 检查 `-lTK*` 归档 | 链接前失败，不浪费 wasm-ld |
| `FreeCADCoreProbe` 别名错误 | 闭包预检按当前模块解析到主 probe，并记录 requested/resolved target | 不再因通用别名退出 1 |
| `configure`/`configure/bin` 混用 | link preflight 自动归一到含 `build.ninja` 的 build tree | gate/预检不再因目录层级误报 |
| 重复解析大型 build.ninja | `web-link-preflight-cache.json` 按 inode/mtime/size 缓存 | 预检命中缓存 |
| 无关模块长链接 | `build_web_module_artifacts.py` 当前模块主 probe 选择 | 避免跨模块失败 |
| Part WASM heap 越界 | Part generic-object 批次上限 12 | 降低批量 fixture 内存峰值 |
| 搜索参数/无匹配退出 | `fast_source_search.py` 支持 intermixed/额外路径；无匹配按成功探索处理 | 通配路径和空结果不再误判 |
| 仓库级 `rg` 或无 pathspec 的 `git diff/status` | 子回合 PATH 使用 `tools/scheduler-bin/{rg,git}`，目录级搜索退出 64；git 检查必须使用 `-- <current-files>` | 在数十万字符输出进入模型前阻断，避免百万级 input token |
| dry-run JSON 参数不兼容 | `build_web_module_artifacts.py` 兼容 `--dry-run --json` | 预览命令不会因输出格式参数退出 2 |
| continuation checker 参数不兼容 | `check_continuation_state.py` 兼容 `--json`，输出稳定 machine-readable 状态 | 状态检查不会因参数退出 2 |
| 同一命令反复失败 | canonical command 回合计数与重复失败收口 | 下一回合从 checkpoint 恢复 |
| `apply_patch` 校验失败/多操作目标冲突 | scheduler 将 `apply_patch verification failed`、`invalid patch` 和 `multiple operations target` 单独归类；编辑前重新读取当前文件并拆分 patch | 不再把补丁冲突误归为普通失败或重复提交同一补丁 |
| 无 stderr 的 gate/build/orchestration 失败 | scheduler 按命令形态兜底分类到 `failure-patterns.json` | 后续预防动作仍可命中，不再全部落入 `other` |

所有防线都保留真实失败状态；它们只减少重复工作，不把边界改写成通过。

调度器每次落盘失败账本时都会同步更新
`docs/current/failure-patterns.json`。新错误会按已知类别归档；无法匹配的错误进入
`other`，保留代表命令和首错，后续可直接据此新增预检规则。