conflict-detector

用途

conflict-detector 用于在派发一个拟议的 T4 任务之前，检测它与待确认（pending-confirm）同级任务之间是否存在冲突。它面向 AI 消费，优化供 Claude 在执行期间读取。人类可读说明见 docs/architecture/HIERARCHICAL_PLANNING.md 或 docs/getting-started/。

状态

v3.7.0-beta.2：L1 与 L2 已具备功能；L3 与 L4 为占位实现，等待 rc.1 中的 LLM 派发基础设施。

五类冲突（依据规范 §21.1）

C1：文件级重叠，检测层 L1，免费
C2：函数/区域重叠，检测层 L2，低成本（约 10ms 正则）
C3：Schema/契约冲突，检测层 L2，低成本
C4：语义意图冲突，检测层 L3，LLM（beta.2 中为占位）
C5：架构冲突，检测层 L4，LLM 罕见（beta.2 中为占位）

分层派发（依据规范 §21.3）

在 dispatch_request(task) 时：

L1 = check-l1-files.sh，始终运行，免费。
若 L1 重叠且置信度 >= 0.95，返回 conflict(L1)。
若 L1 重叠但置信度低，则运行 L2 = check-l2-syntactic.sh，深入检查重叠文件；若 L2 重叠，返回 conflict(L2)。
若 task.tier <= 2 或 task.creates_new_pattern，则运行 L4 = check-architectural（LLM，占位，beta.2 中跳过）；若 L4 矛盾，返回 conflict(L4)。
若 task.parent 存在任何 pending-confirm 同级任务，则运行 L3 = check-semantic（LLM，占位，beta.2 中跳过）；若 L3 矛盾，返回 conflict(L3)。
返回 clear。

禁用

设置 AF_CONFLICT_LLM_DISABLED=true 可在 L3+L4 于 rc.1+ 落地后短路其派发，适用于对成本敏感的场景。L1+L2（确定性 bash）始终运行；该环境变量仅影响由 LLM 支撑的层。在 v3.7.0-beta.2 / rc.1 中它实际上是空操作，因为 L3+L4 已是占位；此说明为与 v3.7.x 补丁版本的前向兼容而记录。

行为

从计划节点 frontmatter 解析拟议任务的 artifacts[].path。
解析 pending-confirm 同级任务（status: planned 且父 T3 活跃，或 status: blocked-on-confirm）。
以任务与同级任务的 artifact 列表运行 scripts/conflicts/check-l1-files.sh。
若 L1 返回重叠且置信度 < 0.95，或文件重叠不明确，则对重叠文件运行 check-l2-syntactic.sh。
L3（语义）：beta.2 中返回 {layer:L3, status:stubbed_for_rc1}。rc.1 中派发 LLM 调用比较意图，并将结果缓存到 conflict_cache.jsonl。
L4（架构）：beta.2 中返回 {layer:L4, status:stubbed_for_rc1}。rc.1 中派发 LLM 调用与 permanent_memory.md 中的决策进行比较。
若发现冲突，向 .claude/plans/conflicts.jsonl 追加发现（依据规范 §21.4）。

冲突记录 Schema（.claude/plans/conflicts.jsonl）

{
  "conflict_id": "CONFLICT-00007",
  "detected_at": "2026-05-07T10:30:00Z",
  "detected_by": "pre-dispatch-conflict-check.cjs",
  "layer": "L1",
  "type": "file_overlap",
  "participants": [{"task": "TASK-00125", "role": "proposed"},
                   {"task": "TASK-00120", "role": "pending-confirm"}],
  "overlap": {"files": ["src/auth.py"], "functions": null, "schema_elements": null},
  "confidence": 1.0,
  "arbitration": null,
  "actions_taken": [],
  "resolution": null,
  "resolved_at": null
}

conflict-arbiter 代理稍后填写 arbitration 与 resolution。

延迟目标（依据规范 §21.7）

L1：p95 <100ms，硬上限 500ms
L2：p95 <300ms，硬上限 1s
L3 缓存：p95 <50ms，硬上限 100ms
L3 冷启动：p95 <3s，硬上限 10s（rc.1）
L4 缓存：p95 <50ms，硬上限 100ms
L4 冷启动：p95 <8s，硬上限 20s（rc.1）

若触及硬上限：记录警告，按存在冲突继续（故障安全——宁可放慢也不静默覆盖）。

本技能不做什么

不在 beta.2 中执行 L3/L4（占位返回占位发现）。
不修改计划树状态（仅写入 conflicts.jsonl；freeze/replan/escalate 由 conflict-arbiter 代理执行）。
不决定解决方案（那是 conflict-arbiter 的职责）。
不直接阻断工具调用（由 pre-dispatch-conflict-check 钩子基于本技能的发现来阻断）。
不跨项目边界——按项目、按 .claude/plans/。

关联

规范：§21（完整冲突检测）
脚本：scripts/conflicts/check-l1-files.sh、scripts/conflicts/check-l2-syntactic.sh
代理：conflict-arbiter——冲突发现的唯一消费者（决定解决方案）
钩子：hooks/pre-dispatch-conflict-check.cjs——主要自动触发（PreToolUse）
钩子：hooks/post-execute-conflict-rescan.cjs——在阻塞项完成后对冻结任务重新运行检测
命令：/aura-frog:plan-conflicts——手动 list/show/resolve
规则：rules/workflow/conflict-arbitration-policy.md——仲裁决策表
规则：rules/workflow/plan-lifecycle.md——冻结状态语义与级联
未来（rc.1）：L3/L4 LLM 派发器 + conflict_cache.jsonl LRU