# 0002 系统级原理修复与意图保真门禁架构 (System-Level Root-Cause Repair & Intent Fidelity Gate)

- **决策编号**：`ADR-0002`
- **状态**：已批准 (Approved) ✅
- **关联规格**：[`docs/specs/SPEC-004-RSI副轨漏洞巡检与原理级修复规范.md`](../specs/SPEC-004-RSI副轨漏洞巡检与原理级修复规范.md)
- **关联研报**：[`docs/research/RESEARCH-007-SOTA标杆逆向解构与RSI副轨自动化治理架构实证研报.md`](../research/RESEARCH-007-SOTA标杆逆向解构与RSI副轨自动化治理架构实证研报.md)
- **统一语言遵循**：[`CONTEXT.md`](../../CONTEXT.md)
- **决策时间**：2026年10月

---

## 1. 决策背景 (Context & Problem Statement)

在以往自动化修复或日常编码中，频繁出现两大导致严重返工的顽疾：
1. **“症状治疗与投机补丁”**：AI 在排查 Bug 时只看当前报错行，习惯性采用“包一层 `try-catch`”、“无脑加 `if (x != null)`”、“引入额外全局标志位”等表层修补，掩盖了深层状态机破坏或领域公理违规；
2. **“意图漂移与散弹式破坏”**：修改了一个局部模块，导致架构退化、接口膨胀，甚至发生“改了A漏了B、修了B坏了C”的涟漪回归破坏，导致最终交付物与开发者原始预期严重不一致。

为了从系统层面根治该问题，我们确立本项架构决策。

---

## 2. 核心架构决策 (Decisions)

### 决策 1：确立“原理锚定先行”原则 (First-Principles Anchoring)
- 任何故障修复与功能演进，**严禁从单行报错直接修改代码**；
- 必须沿着数据流与调用栈执行**因果图溯源（Causal Tracing）**，定位导致系统状态失衡的本质机理（Root Cause）；
- 修复必须维护系统领域模型（[`CONTEXT.md`](../../CONTEXT.md)）的统一语言与全局守恒律。

### 决策 2：设立“意图保真与反投机补丁门禁” (Intent-Fidelity & Anti-Hack Gate)
- 建立自动化审查工具，在代码提交前强制扫描以下“投机坏味道”并实行**一票否决**：
  1. **裸吞异常 (Bare Exception Swallowing)**：无处理逻辑的空 catch 或无条件默认值覆盖；
  2. **浅层防御性判空蔓延 (Defensive Null Creep)**：在核心领域层破坏深模块接口，暴露未校验的空状态；
  3. **架构降级 (Architectural Degradation)**：擅自修改既有核心接口契约或引入隐式全局变量。

### 决策 3：设立“AST 变更爆炸半径全域扫描” (Blast Radius Hunter)
- 针对每次代码修改（Git Diff），通过抽象语法树（AST）分析所有直接调用方、间接递归调用方以及类型依赖集合；
- 若检测到变更影响集（Impact Set）中的依赖模块未在本次修改中同步更新，必须立即阻断并警告，**终结“改了A漏了B”的散弹式遗漏**。

### 决策 4：隔离的 RSI 副轨双环博弈 (Isolated RSI Crucible Loop)
- RSI（递归自我改进）治理循环必须在**独立的 Git Worktree（`--worktree new-child`）**中运行，与主轨开发物理隔离；
- **红队机制**：采用属性基测试（Property-based Testing）与代码变异测试（Mutation Testing），主动对刚修复的逻辑注入极限与并发攻击；
- **蓝队机制**：仅当能够稳定跑通“最小可复现切片（Minimal Repro Test）”且通过意图门禁后，副轨才向主轨提请 PR 或登记工单（`docs/issues/`）。

---

## 3. 结果与影响 (Consequences)

### 正向收益
- **零意图漂移**：AI Agent 无法通过投机取巧的表层补丁蒙混过关，交付物与人类心智模型高度对齐；
- **杜绝连锁破坏**：爆炸半径分析与变异对抗在代码合入前扼杀所有未被察觉的隐式回归破坏；
- **全流程实体留痕**：每一次原理级修复均有因果溯源证据链与最小复现测试支持。

### 约束与成本
- 每次复杂修改必须运行意图校验与爆炸半径扫描脚本，引入毫秒级至秒级的静态门禁开销；
- 副轨的红蓝对抗需分配独立计算资源，通过异步 Worktree 执行，不占用主轨交互时间。