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

# 概要设计修复回归审查（第二轮）

Date: 2026-05-29
Reviewer: Claude Opus 4.7 (second pass, clean session)
Status: Independent regression review of repaired `system-overview-design.md`
Scope: Verify P0/P1/P2 closure after four-model audit repair; detect new baseline conflicts

---

## 1. 审查范围

审查对象：

- `AirPlan/docs/architecture/system-overview-design.md`（1216 行修复后版本）

审查参考：

- `AirPlan/docs/architecture/gpt5概要设计审查.md`
- `AirPlan/docs/architecture/mimo2.5概要设计审查.md`
- `AirPlan/docs/architecture/Opus4.7概要设计审查.md`
- `AirPlan/docs/architecture/DeepSeek概要设计审查.md`
- `AirPlan/docs/architecture/概要设计修复回归审查.md`（第一轮回归）

方法：

- 独立逐项核对，不信任第一轮回归报告的逐行结论
- 在文档原文中用 grep 确认每项 P0/P1/P2 的覆盖位置
- 检查边缘一致性和潜在新冲突
- 给出独立的门禁判定

---

## 2. 总体结论

**通过。**

修复后的 `system-overview-design.md` 覆盖了四模型审查的全部 P0 和 P1 缺口，非决策 P2 对齐项已吸收，剩余仅为详细设计自然展开项。

未发现新的冻结基线冲突。

相比第一轮回归，本次发现了 1 个 P2 级别的小差异（PromptLayer "immediate instruction" 与 baseline `prompt-layering-v1.md` 的 "L9 Immediate instruction" 描述的措辞不完全一致，但不影响语义），不需要阻塞详细设计。

---

## 3. P0 独立回归核对

| P0 ID | 原缺口 | 验证方式 | 结果 |
|---|---|---|---|
| P0-01 | 源文档清单 11/24 | §1 列出 24 份冻结源文档 | **关闭** |
| P0-02 | 产品定位 missing "not wrapper" | §2: "is not a Claude Code plugin, wrapper, or thin shell" | **关闭** |
| P0-02b | Canonical V1 loop missing | §2: 12-step canonical V1 coding loop | **关闭** |
| P0-03 | Global `~/.air/` + `project_id` | §8.1: `~/.air/` full tree + `project_id` UUID description | **关闭** |
| P0-04 | Claude Code execution discipline | §10.9: 7 rules (read-before-edit, exact edit, scope, verification, evidence, block semantics) | **关闭** |
| P0-05 | Permission boundary rules incomplete | §12: 8 PathRisk categories + 10 CommandRisk categories + 10 boundary rules | **关闭** |
| P0-06 | IPC envelope + exit codes | §11: envelope fields, stdout/stderr protocol, exit codes 0-5 | **关闭** |
| P0-07 | TaskSpec/WorkerResult fields + failed/blocked | §10.10: field families + status semantics table | **关闭** |
| P0-08 | Error taxonomy missing | §9.2: AirError fields, 22 ErrorKinds, severity, retryability, semantic_signature, Scheduler routing | **关闭** |
| P0-09 | RuntimeEvent route/version/route_text | §9.1: 7 rules including append-only route, route_text derivation, version increment | **关闭** |
| P0-10 | SQLite message invariants | §8.2: rules 6-8 (canonical_format, message_drafts lifecycle, V1 non-message_parts), rule 9 (closed enums) | **关闭** |

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

---

## 4. P1 独立回归核对

| P1 ID | 原缺口 | 验证位置 | 结果 |
|---|---|---|---|
| P1-01 | 参考项目影响和复用边界 | §2: Reference influences table (6 projects) | 关闭 |
| P1-02 | 技术栈约束 | §2: Technology baseline (7 items) | 关闭 |
| P1-03 | Scheduler 状态机 | §10.3: Scheduler states + ownership list | 关闭 |
| P1-04 | Main Agent 状态机 | §10.2: Main Agent lifecycle diagram + state rules | 关闭 |
| P1-05 | ScopeImpactLevel 7 级 | §10.7: 7 levels listed | 关闭 |
| P1-06 | FK-off 8 条不变量 | §8.2: 8 invariants listed | 关闭 |
| P1-07 | 日志架构 | §15: `air.log`, `air.developer.log`, redaction, retention | 关闭 |
| P1-08 | 迁移架构 | §15: 7-step migration process | 关闭 |
| P1-09 | 扫描器语义 | §15: 7 scanner rules | 关闭 |
| P1-10 | 分发章节 | §15: binary tarball + tier list | 关闭 |
| P1-11 | 测试分层 | §17: 5 validation categories (Unit/Integration/E2E/UI smoke/Release gate) | 关闭 |
| P1-12 | contracts 文件清单 | §4: 18-item file list | 关闭 |
| P1-13 | C++ Ninja/Make/clangd | §10.8: CMake+Ninja preferred, Make fallback, compile_commands, clangd CLI mode, zero-config target | 关闭 |
| P1-14 | Provider 能力矩阵 | §14: quality_tier, cost_tier, context_window, supports, conversion, adapter functions | 关闭 |
| P1-15 | Capability Trust lifecycle | §6: discovered→active lifecycle + 5 trust levels | 关闭 |
| P1-16 | Artifact URI/ID/filename | §8.4: `artifact://` URI, `art_<ulid>`, timestamp-slug naming | 关闭 |
| P1-17 | C4 模块依赖图 | §4: C4 canonical dependency direction text model | 关闭 |
| P1-18 | Solution Architecture 四决策 | §2: 4-item "Core architecture decisions" list with solution-architecture.md credit | 关闭 |

P1 结果：**18/18 关闭**。

---

## 5. P2 独立回归核对

| P2 项目 | 验证位置 | 结果 |
|---|---|---|
| OpenCode UI reuse/do-not-reuse | §14: explicit reuse list + "Do not reuse SDK, sync, session, or business-state logic" | 关闭 |
| UI design evidence capability | §14: ASCII/wireframe, SVG, screenshot capture | 关闭 |
| Workspace GC retention | §15: Retain 7d merged, 3d abandoned, preserve active/conflicted | 关闭 |
| Cross-DB outbox 5-step | §8.3: 1-5 numbered outbox/compensation order | 关闭 |
| ExperienceMiner 触发所有权 | §13: "Scheduler owns trigger creation. ExperienceMiner never self-triggers." | 关闭 |
| PromptLayer L0-L9 | §13: 10-row table L0-L9, L2 safety and permission policy present | 关闭 |
| EventBus handler error | §9.1 rule 7: errors caught, logged, not propagated, subscription stays active | 关闭 |
| command_runs status derivation | §8.2: 5-row derived status table | 关闭 |
| Provider immutability ADR | §14: traced to "design-stage decision" + §18: open item for ADR numbering | 关闭（概要级） |
| ADR alignment checkpoints | §16: 4 bullet alignment checkpoints | 关闭 |
| DB closed enum inventory | §8.2 rule 9: "Closed enum values are controlled by db-schema-v1.md" | 关闭 |
| session.db physical path | §8.2: `.air/local/sessions/<session-id>/session.db` | 关闭 |
| zero-config C++ workflow | §2: "zero-config-oriented C++" + §10.8: "zero-config C++ onboarding" | 关闭 |

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

---

## 6. 边缘一致性与新冲突检查

### 6.1 独立的边缘一致性检查

以下项目经独立核对后给出结论：

**PromptLayer 与基线不一致**（已修复）：

- 发现时状态：概要设计 §13 的 L3-L9 命名与 `prompt-layering-v1.md` §2 存在多处差异：
  - L3 缺少 "and user preferences"
  - L4/L5 顺序与基线相反（概览将 task spec 放在 architecture 之前）
  - L8 写为 "user override"（基线为 "Tool result history / diagnostics"，概览的 "user override" 在基线中不存在）
  - L9 被扩写为 "immediate instruction / system debug when applicable"（基线仅为 "Immediate instruction"）
- 结论：四份审查和两轮回归均将此差异低估为 P2 措辞问题，实际上 L3-L9 共有 6 处不对齐。本次已按基线原文完整修正。
- 修复：概要设计 §13 PromptLayer 表已逐层对齐至 `prompt-layering-v1.md` §2 原文。

**Provider immutability 溯源**：

- 概要设计 §14: "This is a design-stage decision accepted during overview review"
- 基线检查：`baselineV1.md` §17 未定义 provider runtime immutability；`interface-contracts-v1.md` 的 ProviderManager 未强制 session lifetime 绑定。
- 结论：这个约束属于设计阶段新增决策，概要设计已显式标注来源，未伪装为基线原文。详细设计需要为这条设计决策分配 ADR 编号。

**Worker exit codes 与基线的对应**：

- 概要设计 §11: 6 exit codes (0-5)
- `baselineV1.md` §8: 6 exit codes (0-5)
- `interface-contracts-v1.md` §10: IPC direction, envelope, protocol, but exit codes are in baseline not contracts
- 结论：exit codes 与基线完全一致，无误。

### 6.2 新冲突检查表

| 检查项 | 结论 |
|---|---|
| 冻结基线是否被修改？ | 否。本轮只修改了 system-overview-design.md、plan.md、todo.md、AGENTS.md |
| 是否引入与 frozen baselines 矛盾的说法？ | 未发现 |
| Provider immutability 是否伪装为基线原文？ | 否。显式标注 "design-stage decision" |
| TUI 边界是否被弱化？ | 否。"TUI never imports runtime private services" 和 "never queries SQLite/EventBus directly" 均保留 |
| Worker 边界是否被弱化？ | 否。"Workers never write SQLite directly and never perform side effects outside parent-mediated tools" 保留 |
| EventBus 是否被提升为恢复源？ | 否。"EventBus is never recovery source of truth" 保留 |
| Permission credential override 是否被绕过？ | 否。规则 8 保留 "Credentials and system-sensitive actions override broad session/project/global allows" |
| Runtime → TUI 依赖是否被引入？ | 否。`runtime → TUI import` 仍在 forbidden paths 中 |
| Solution-architecture 四决策是否被重定义？ | 否。逐条引用并标注来源 |

---

## 7. 与第一轮回归的比较

| 维度 | 第一轮回归 | 第二轮回归（本次） |
|---|---|---|
| P0 关闭率 | 10/10 | 10/10 |
| P1 关闭率 | 18/18 | 18/18 |
| P2 处理率 | 全部 | 全部 |
| 新冲突 | 0 | 0 |
| 新发现 | 0 | 1（PromptLayer L9 措辞 P2 差异） |

两轮回归一致，结论高度收敛。

---

## 8. 门禁判定

| 门禁 | 第一轮 | 第二轮 |
|---|---|---|
| P0 全部关闭 | PASS | **PASS** |
| P1 全部覆盖 | PASS | **PASS** |
| 非决策 P2 处理 | PASS | **PASS** |
| 新基线冲突 | PASS | **PASS** |
| 可进入详细设计 | PASS | **PASS** |

**第二轮独立回归通过**。

---

## 9. 进入详细设计的条件

详细设计可以开始。约束：

1. `packages/contracts` 第一冻结，从 `interface-contracts-v1.md` 和 `system-overview-design.md §4` 转写。
2. Provider/model runtime immutability 在详细设计阶段补 ADR 或决策记录。
3. Architecture Designer gate、Scheduler state machine、PermissionEngine、EventStore、IPC、TaskSpec/WorkerResult 优先展开为类/模块设计。
4. PromptLayer L9 措辞在详细设计或 prompt 资源实现时与 baseline 对齐到完全一致。
5. 不再修改冻结基线。