AirCoding/AirPlan/docs/architecture/概要设计修复回归审查.md

# 概要设计修复回归审查

Date: 2026-05-29
Status: Regression review after applying P0/P1/P2 overview audit repairs
Scope: Verify repaired `system-overview-design.md` against the four overview audit reports; no frozen baseline edits

---

## 1. 回归范围

审查对象：

- `AirPlan/docs/architecture/system-overview-design.md`

回归输入：

- `AirPlan/docs/architecture/gpt5概要设计审查.md`
- `AirPlan/docs/architecture/mimo2.5概要设计审查.md`
- `AirPlan/docs/architecture/Opus4.7概要设计审查.md`
- `AirPlan/docs/architecture/DeepSeek概要设计审查.md`

回归问题：

1. 原 10 个 P0 是否全部关闭？
2. 原 P1 是否已覆盖或明确转入详细设计？
3. 原 P2 中无需用户决策的对齐项是否已覆盖？
4. 是否引入新的明显基线冲突？

---

## 2. 总体结论

`system-overview-design.md` 已完成四模型审查后的修复回归。

结论：**可以进入详细设计 / 类图冻结。**

原因：

- 原 10 项 P0 全部关闭。
- 原 P1 全部在概要设计中获得覆盖。
- 原 P2 中不需要用户决策的对齐项已吸收；剩余仅为详细设计自然展开项。
- 未发现新的冻结基线冲突。
- 修复范围限定在概要设计和当前阶段索引/计划文档，没有修改冻结基线。

---

## 3. P0 回归表

| ID | 原缺口 | 修复位置 | 回归结论 |
|---|---|---|---|
| P0-01 | 源文档清单仅 11/24 | §1 Frozen source documents | **关闭**：24 份冻结基线全部列出 |
| P0-02 | 产品定位缺少 not wrapper + canonical loop | §2 System Goal | **关闭**：明确不是 Claude Code plugin/wrapper，并列出 V1 canonical loop |
| P0-03 | Global `~/.air/` layout + `project_id` UUID | §8.1 Filesystem layout | **关闭**：global/project-local layout、project_id UUID、`.air/local` gitignore 均覆盖 |
| P0-04 | Claude Code 执行原语系统约束 | §10.9 Claude Code execution discipline | **关闭**：read-before-edit、exact edit、scope、verification、evidence、block semantics 均覆盖 |
| P0-05 | 权限边界细则 | §12 Permission and Security Overview | **关闭**：PathRisk、CommandRisk、10 条边界规则覆盖 |
| P0-06 | IPC envelope + exit codes | §11 IPC and Worker Overview | **关闭**：envelope 字段、stdout/stderr、exit code 0-5 覆盖 |
| P0-07 | TaskSpec/WorkerResult 字段族 + failed/blocked | §10.10 TaskSpec and WorkerResult overview | **关闭**：字段族、status 语义、summary 规则覆盖 |
| P0-08 | 错误分类学缺失 | §9.2 Error taxonomy | **关闭**：AirError、ErrorKind、severity、retryability、semantic_signature 覆盖 |
| P0-09 | RuntimeEvent route/version/route_text | §9.1 Event flow | **关闭**：append-only、route_text、version increment、EventStore persistence policy 覆盖 |
| P0-10 | SQLite message storage invariants | §8.2 Session DB | **关闭**：canonical_format、message_drafts、no message_parts source-of-truth 覆盖 |

P0 结果：**10/10 关闭**。

---

## 4. P1 回归表

| ID | 原缺口 | 修复位置 | 回归结论 |
|---|---|---|---|
| P1-01 | 参考项目影响和复用边界 | §2 Reference influences and reuse boundaries | 关闭 |
| P1-02 | 技术栈约束条目 | §2 Technology baseline | 关闭 |
| P1-03 | Scheduler 状态机 | §10.3 Scheduler state machine | 关闭 |
| P1-04 | Main Agent 状态机 | §10.2 Main Agent state machine | 关闭 |
| P1-05 | ScopeImpactLevel 7 级分类 | §10.7 Review and architecture gate | 关闭 |
| P1-06 | FK-off 8 条不变量 | §8.2 Session DB | 关闭 |
| P1-07 | 日志架构 | §15 Logging | 关闭 |
| P1-08 | 迁移架构 | §15 Migration | 关闭 |
| P1-09 | 扫描器语义 | §15 Project scanner | 关闭 |
| P1-10 | 分发章节 | §15 Distribution | 关闭 |
| P1-11 | 测试分层 | §17 Validation Overview | 关闭 |
| P1-12 | contracts 包文件清单 | §4 Container Overview | 关闭 |
| P1-13 | C++ Ninja/Make/clangd 细节 | §10.8 C++ workflow | 关闭 |
| P1-14 | Provider 能力矩阵摘要 | §14 UI/HUD and Provider Overview | 关闭 |
| P1-15 | Capability Trust 生命周期和 trust level | §6 Runtime Component Overview | 关闭 |
| P1-16 | Artifact URI/ID/filename 规范 | §8.4 Artifact and evidence naming | 关闭 |
| P1-17 | C4 module 依赖图 | §4 Container Overview | 关闭 |
| P1-18 | Solution Architecture 四个核心决策 | §2 System Goal | 关闭 |

P1 结果：**全部关闭**。

注：P1 编号合并了 Opus/DeepSeek 两份报告的分类差异；DeepSeek 将 C4 依赖图和 solution decisions 追加为 P1，已覆盖。

---

## 5. P2 回归表

| 原缺口 | 修复位置 | 回归结论 |
|---|---|---|
| OpenCode UI reuse/do-not-reuse | §14 OpenCode reuse boundary | 关闭 |
| UI design evidence capability | §14 UI design evidence capability | 关闭 |
| Workspace GC 具体保留天数 | §15 Workspace GC policy | 关闭 |
| Cross-DB outbox 5 步流程 | §8.3 Project-level DBs | 关闭 |
| ExperienceMiner 触发所有权 | §13 ExperienceMiner triggers | 关闭 |
| PromptLayer L0-L9 一致性 | §13 PromptLayers L0-L9 | 关闭 |
| EventBus handler 异常处理 | §9.1 Event flow | 关闭 |
| command_runs 状态派生 | §8.2 Session DB | 关闭 |
| Provider runtime immutability ADR 溯源 | §14 + §18 Open Items | 关闭：已标注为设计阶段决策，ADR 编号留详细设计 |
| ADR 关键决策交叉引用 | §16 ADR alignment checkpoints | 关闭到概要级；具体编号留详细设计 |
| DB 关闭枚举清单引用 | §8.2 Session DB | 关闭 |
| session.db 物理路径/共享拓扑 | §8.1-§8.3 | 关闭 |
| zero-config C++ workflow | §2 + §10.8 | 关闭 |

P2 结果：**不需要用户决策的对齐项已关闭；剩余为详细设计自然展开项**。

---

## 6. 新冲突检查

未发现新的明显基线冲突。

重点检查结果：

1. **冻结基线未修改**：本次修复只改概要设计、计划/任务索引和新增审查报告。
2. **Provider/model runtime immutability**：概要设计标注为设计阶段决策，并在 §18 留 ADR 编号给详细设计，未伪装为冻结基线原文。
3. **TUI 边界**：继续保持 TUI 只依赖 ProjectionClient/contracts，不直接访问 runtime internals/SQLite/EventBus。
4. **Runtime/EventStore 边界**：保留 EventIngestor 入口、EventStore transaction、EventBus 非恢复源的语义。
5. **PermissionEngine 边界**：新增细则没有绕过 credential/system-sensitive override。
6. **Worker 边界**：仍禁止 worker 直接写 SQLite 或绕过 parent-mediated tools。
7. **Doctor/restore**：保持已覆盖的 Doctor self-bootstrap 和 restore 三粒度，没有引入与 runtime-semantics 冲突的语义。

---

## 7. 进入详细设计建议

建议进入详细设计，但详细设计开头应继承以下约束：

1. 不再修改冻结需求/基线，除非用户明确重新开基线变更流程。
2. `packages/contracts` 是第一冻结对象，优先从 `interface-contracts-v1.md` 和修复后的 `system-overview-design.md` 转写。
3. 详细设计需要给出具体类/模块/文件布局，而不是再次重复概要设计。
4. Provider/model runtime immutability 需要补 ADR 编号或详细设计决策记录。
5. Architecture Designer gate、Scheduler state machine、PermissionEngine、EventStore、IPC、TaskSpec/WorkerResult 应作为详细设计优先展开对象。

---

## 8. 回归门禁判定

| 门禁 | 状态 |
|---|---|
| P0 全部关闭 | PASS |
| P1 全部覆盖 | PASS |
| 非决策 P2 对齐项处理 | PASS |
| 新基线冲突 | PASS |
| 可进入详细设计 | **PASS** |

最终结论：**概要设计修复回归通过。**