踩坑指南与失败验收
实践 / 建议踩坑指南：把已发现的差距转成验收用例
下表来自本轮文件/源码核对及仓内案例。它们是具体缺口或风险，不代表本次实际发生生产事故。
| 症状 | 已有证据与成因 | 修法与验收 |
|---|---|---|
| “测试成功”却不能证明没失败 | fs-feeds test/ciVerify 使用 -Dmaven.test.failure.ignore=true，部署构建另有 skip |
校准必需门禁并解析报告；注入失败/跳过/缺报告均不得 PASS |
| 本地 verify 与 CI 不等价 | Egress pnpm verify:ci 实际聚合 Maven，证据 Python 检查由 CI 另调 |
对齐或改准确名称；用同一失败夹具验证本地与 CI 判定一致 |
| 同一规范出现三套正文 | feeds 的团队层指 FSpec，BDD 多主源、路由仍 L1/L2，FSpec 已 L0–L3 | 唯一正文+固定引用；变更上游后能检测消费者待升级 |
| 规则同步绿灯但规范落后 | FSpec baseline CI 证明本仓片段一致，没证明与 ai-wiki 权威版本一致 | 同时记录源 revision 和差异；上游变更触发升级待办 |
| 下游接到旧阶段 | FSpec 文档记载编排索引未刷新 | handoff 校验阶段、产物、远端 SHA；旧索引拒绝派单 |
| done 触发错误推进 | FSpec 产物 done 可带 FAIL，Golden Path 合并 done 不等于生产恢复 | delivery_state、verdict、deployment、incident 分开，构造 FAIL+done 验收 |
| 集中运行池拿不到文件 | 个人绝对路径、副本、只在本机的 checkpoint | 正式版本库/证据存储+push SHA；第二台干净 runtime 恢复 |
| 工作区初始化互相覆盖 | 项目 .worktrees 约定与托管目录、技能链接不同 |
本地/托管 profile；两任务并发且已有技能不丢失 |
| lint 改了文件却继续用旧证据 | IDP lint 包含 markdownlint --fix |
check/fix 分开，修改后刷新输入再验 |
| 装了 hooks 就当强制生效 | 两仓 commit-msg 为 warn-only；服务端保护本轮未核验 | 本地快速反馈+服务端必需 CI；绕过本地 hook 仍被必需门禁阻断 |
| push 检查错分支 | pre-push 当前 checkout 与实际推送 ref 语义有差异，部分检查明确 skip | 检查实际 ref，并由 CI 兜底；非 HEAD push 负向测试 |
| 源知识有状态，检索看不到 | wiki-bot 部分元数据在发布中丢失 | 源→发布→索引往返验收，未审定知识不能伪装审定规则 |
| Agent 自报走了路径就算实测 | bug-finder path-eval 为结构化自述，fixture 为合成样本 | 分开统计结构检查、回放和真实工具执行；抽查真实端到端任务 |
| 两个任务验证了不同制品 | Golden Path 共享环境非原子占用 | 租约/队列+前后制品核验，覆盖测试必须使证据失效 |
| 诊断成功被解释为代码可修 | 异常可能来自配置、容量、数据或采集错误 | 明确处理类型，只有合同满足才进入代码修复 |
| 群聊重复建单或机器人循环 | 多源事件、诸葛入口和同步平台可能重叠 | 单一建单责任+跨源映射+机器人事件过滤，重复重放只产生一个任务 |
最值得先落地的不是新增几十页说明，而是将前六类问题变成失败夹具和门禁。 每次踩坑形成“症状 → 最小复现 → 根因 → 检查/测试 → 唯一维护源 → 适用范围”的闭环。 未经确认的诊断留在案例区，经验证的稳定规则再进入规范区。
本节依据： 路径评测边界、IDP CI、Egress 验证规范；feeds/FSpec 固定源码入口见 L2/L3。