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. 不再修改冻结基线。