Detailed design: fix four P2 findings from Opus 4.8 + DeepSeek reviews

Independent full-scope audits by Opus 4.8 (R6) and DeepSeek V4 Pro (R7)
converged on the same four P2 findings. This commit closes all four:

F1 §10.2: EvidenceStore.list_for_task() → list_for_entity("task", task_id)
  The fictional method list_for_task() was not in contracts §14. Now uses
  the real contract method list_for_entity() with task as entity_type.

F5 §16.1: DoctorService.check_capability() changed from public (+) to
  private (-) with a clarifying comment. Only run() is in contracts §19.

F2 §22.7: Context and Compaction class diagram now shows the internal
  dependency edges ContextAssembler ..> EvidenceStore (L6) and
  ContextAssembler ..> SessionStore (L7/L8), matching §10.2.

F3 §22.4: Tool and Permission class diagram now shows ToolRegistry -->
  ToolDefinition (registers) and ToolRegistry --> ToolExecutor (invokes),
  matching §9.1.

Also adds the two full-scope review reports that identified these findings.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

AirPlan/docs/architecture/opus4.8系统详细设计审查复查.md

@@ -0,0 +1,303 @@
+# Opus 4.8 系统详细设计与 UML 类图全量审查复查
+
+Date: 2026-06-01
+Reviewer: Claude Opus 4.8 (independent full-scope re-audit)
+Scope: 全量复查 — 覆盖性 + 内在一致性 + 基线遵守 + 架构合理性 + 内在冲突
+Target commit: `af99aed`（R 系列回归修复后）
+Inputs:
+- 详细设计：`system-detailed-design.md`（2290 行，23 章节，含 §22 8 张 Mermaid 类图）
+- 冻结基线：`interface-contracts-v1.md`、`event-registry-v1.md`、`db-schema-v1.md`、
+  `runtime-semantics-v1.md`、`scheduler-state-machine-v1.md`、`main-agent-state-machine.md`、
+  `prompt-layering-v1.md`、`scope-escalation-v1.md`、`security-model-v1.md`、`tool-registry-v1.md`、
+  `capability-trust-v1.md`、`artifact-naming-v1.md`、`error-taxonomy-v1.md`、`baselineV1.md`
+- 冻结概要设计：`system-overview-design.md`
+- 此前审查：DeepSeek / MIMO 2.5 Pro / GPT-5.5 Pro / Opus 4.8(R4) / Opus 4.7(R5 回归)
+
+---
+
+## 1. 审查方法
+
+本次为**独立全量复查**，不预设此前 5 轮审查已经完备。从零重建以下证据链：
+
+1. **逐行通读 DD 全文**（§0-§23，2290 行）
+2. **枚举式覆盖核对**：用脚本从基线提取契约接口名 / 事件名 / DB 表名 / 状态机，再与 DD 逐一比对（`comm -23` / `comm -13` 差集法）
+3. **基线遵守抽样核验**：对 DD 中所有 `Class.method()` 形式的引用，回查契约是否真实存在该方法（这正是 R5 发现 `current_profile()` 越界的同类问题，本次扩大到全部点名方法）
+4. **架构合理性**：依赖方向、职责分离、事件流时序、跨 DB outbox、FK-off 不变式
+5. **UML 逐张审查**：8 张类图的语法、类数、边与正文一致性
+6. **内在冲突**：同一概念跨章节是否自洽
+
+---
+
+## 2. 总览结论
+
+| 维度 | 状态 |
+|---|---|
+| 契约覆盖 | ✅ 100%（23 个契约章节全部映射） |
+| 事件覆盖 | ✅ 100%（55 durable + 7 ephemeral，含聚合写法） |
+| DB Schema 覆盖 | ✅ 100%（16 张主表 + 2 项目级 DB，schema_meta 归 MigrationRunner） |
+| 状态机覆盖 | ✅ 100%（main / scheduler / task / agent / workspace / capability 共 6 个） |
+| PromptLayer L0-L9 覆盖 | ✅ 100% |
+| 10 条禁止边 | ✅ 100% 显式继承 |
+| UML 类图 | ✅ 8/8 存在且语法可解析 |
+| R 系列(R1-01~R2-02) 回归修复 | ✅ 5/5 已闭合（本次复验） |
+| 架构合理性 | ✅ 无循环依赖，职责分离清晰 |
+| **新增 P0** | **0** |
+| **新增 P1** | **0** |
+| **新增 P2** | **4**（F1/F5 契约方法越界，F2/F3 类图欠完整） |
+| 综合判定 | **CONDITIONAL PASS** — 4 项 P2 不阻断实现，建议合并修复 |
+
+---
+
+## 3. 覆盖性矩阵
+
+### 3.1 契约覆盖（interface-contracts-v1 → DD）
+
+`interface-contracts-v1.md` 共 23 个章节（§2-§23），DD §21.1 逐一映射，复验全部命中：
+
+| 契约章节 | DD 章节 | 复验 |
+|---|---|---|
+| §2-§4 原语 / 错误 / 实体引用 | §3、§18.1 | ✓ |
+| §6 事务存储 | §4、§18.2 | ✓ |
+| §7 Event Bus/Store/Ingestor | §5 | ✓ 三接口签名逐字一致 |
+| §8 项目/会话 | §6 | ✓ |
+| §9 Task/Scheduler | §7 | ✓ |
+| §10-§11 Worker/IPC/Result | §8 | ✓ exit code 与 baselineV1 §8 逐行一致 |
+| §12-§13 Tool/Permission | §9 | ✓ |
+| §14 Artifact/Evidence | §11 | ⚠ 见 F1 |
+| §15 Provider | §12 | ✓ |
+| §16 Context | §10 | ✓ PromptLayerLoader 4 方法签名逐字一致 |
+| §17 Projection/UI | §13 | ✓ ProjectionSnapshot 8 个投影字段全覆盖 |
+| §18 Capability | §9.5 | ✓ |
+| §19 Doctor | §16 | ⚠ 见 F5 |
+| §20 Debug/Memory | §11.3 | ✓ lookup_by_signature/by_task 存在 |
+| §21 Diagnostic | §15 | ✓ |
+| §22-§23 版本/边界规则 | §3、§18.5 | ✓ 10 条禁止边全继承 |
+
+### 3.2 事件覆盖（event-registry-v1 → DD）
+
+差集法核对（registry §6 索引 55 durable + 7 ephemeral）：
+
+- DD §5.4 Table A/B 显式列出 46 个事件名；
+- 差集中 12 个"未直接出现"的事件（`agent.completed/failed/lost/cancelled`、6 个 `doctor.*`、`permission.prompt.requested/resolved`）经核查均由 DD 的**聚合写法**覆盖：
+  - `| agent.completed/failed/lost/cancelled | update agents.status |`（§5.4 L384）
+  - `| doctor.* | append (+ optional ...) |`（§5.4 L409）
+  - `| permission.prompt.requested/resolved | append |`（§5.4 L408）
+- 7 个 ephemeral 全部在 §5.5 与 §13.1 列出（含 `command.stdout.delta`/`command.stderr.delta`）。
+
+**结论**：55 + 7 全覆盖，无遗漏。差集中出现的 `agents.status`/`sessions.status`/`events_session.db` 为投影目标列/库名，非事件名，属正常。
+
+### 3.3 DB Schema 覆盖（db-schema-v1 → DD repositories）
+
+db-schema §2-§18 共 17 表。DD §4.3 仓库清单覆盖 §3-§18 的 16 张业务表（一一对应），`schema_meta`（§2）由 `MigrationRunner` 持有（DD §4.2、§21.3 明确）。两张项目级 DB（`debug-records.db`/`learned-memory.db`，§20）由 `DebugKnowledgeStore`/`LearnedMemoryStore` 持有（§11.3）。
+
+**结论**：17/17 表 + 2 项目级 DB 全覆盖。
+
+### 3.4 状态机覆盖
+
+| 状态机 | 基线 | DD |
+|---|---|---|
+| Main Agent | main-agent-state-machine.md | §14.1、§20.1 ✓ |
+| Scheduler | scheduler-state-machine-v1.md §4 | §7、§20.2 ✓（11 状态全列） |
+| Task status | db-schema §7 | §20.3 ✓ |
+| Agent status | db-schema §10 | §20.4 ✓ |
+| Workspace status | db-schema §16 | §20.5 ✓ |
+| Capability lifecycle | capability-trust §7 | §9.5、§20.6 ✓ |
+
+6/6 状态机全覆盖。
+
+### 3.5 需求覆盖（requirements → DD workflows）
+
+- C++ 全流程（configure/build/test/static-analysis/debug/fix/review）：DD §15 + §19.5 ✓
+- GUI/网络取证工具：通过 capability + tool 注册（§9.5、§15）✓
+- 静态分析（`docs/staticanalysis.md`）：`CppcheckRunner` + `DiagnosticParser`（§15）✓
+- TUI/HUD 投影：§13 ✓
+- Linux tier-1 release gate：§16（Doctor/release）+ overview §15 ✓
+
+### 3.6 PromptLayer L0-L9 覆盖
+
+DD §10.2 表 1 将 11 个 `PromptLayerLevel` 枚举值（含 `system_debug`）映射到 L0-L9，与 contracts §16 枚举、prompt-layering-v1 §2 完全对应。表 2 区分 PromptLayerLoader（L0/L1/L3/L5）与 ContextAssembler 内部装配（L2/L4/L6/L7/L8/L9）。✓
+
+### 3.7 UML 类图覆盖（§22.1-§22.8）
+
+| 图 | 类数 | 状态 |
+|---|---|---|
+| §22.1 契约包 | 9 | ✓ |
+| §22.2 运行时核心服务 | 9 | ✓ |
+| §22.3 Scheduler | 7 | ✓ |
+| §22.4 Tool/Permission | 5 | ⚠ F3 |
+| §22.5 Worker/IPC | 9 | ✓ 5 个 Role 继承齐全 |
+| §22.6 Provider | 6 | ✓ |
+| §22.7 Context/Compaction | 4 | ⚠ F2 |
+| §22.8 Agents | 2 | ✓ |
+
+8/8 存在且语法可解析。两处欠完整见 §7。
+
+---
+
+## 4. 基线遵守审查
+
+抽取 DD 中所有 `ClassName.method()` 形式引用，回查契约真实性：
+
+| DD 引用 | 契约真实性 | 判定 |
+|---|---|---|
+| `PromptLayerLoader.load_role()` | contracts §16 存在 | ✓ |
+| `EvidenceStore.list_for_task()` | contracts §14 **只有** `list_for_entity()` | ✗ **F1** |
+| `EventBus.publish()` | contracts §7 存在 | ✓ |
+| `ContextAssembler.load_layers()` | DD 内部私有方法（`-`），非契约 | ✓ |
+| `SessionStore.referential_check()` | SessionStore 是 DD 内部聚合，非契约接口 | ✓ |
+| `ProjectLocator.locate()` / `ProjectInitializer.scaffold()` | DD 标记 `IMPL` 辅助类 | ✓ |
+| `DoctorService.check_capability()` | contracts §19 **只有** `run()` | ✗ **F5** |
+| `current_profile()`（R5 旧问题） | DD 中已 0 处、契约 0 处 | ✓ R1-01 已闭合 |
+
+R 系列复验：`overview §10.3`（R2-01）、`agent.started 单状态 + §20.4`（R1-02）、`无 phase 字段`（R1-03）、`16 mandatory files`（R2-02）均已正确落地。
+
+---
+
+## 5. 架构合理性审查
+
+### 5.1 依赖方向与无循环
+
+DD §2 复述 c4/module.md 的允许导入图：`contracts ← llm/toolchain-cpp/tui/runtime ← cli`，`workers` 仅依赖 contracts + WorkerRuntime IPC。无逆向边、无环。✓
+
+### 5.2 职责分离
+
+- **Scheduler vs WorkspaceManager**（§7.5）：策略归 Scheduler、机制归 WorkspaceManager，9 行职责矩阵清晰，无泄漏。✓
+- **EventStore vs 领域服务**（§5.1、§5.3）：EventStore 只做事务投影，不创建 task/permission/memory；follow-up 由 owning service 发出。✓
+- **ToolRegistry / PermissionEngine / CapabilityRegistry**（§9）：所有副作用经 PermissionEngine；capability 永不绕过。✓
+
+### 5.3 事件流一致性
+
+producer → EventIngestor → (durable: EventStore tx + projection + post-commit publish | ephemeral: EventBus) 在 §5.1、§5.3、§18.2 三处描述一致；"publish AFTER commit"（contracts §7 rule 3）一致。✓
+
+### 5.4 跨 DB outbox 一致性
+
+§18.4 经 R1-03 修复后，采用"owning store 先外部写 → 成功后 ingest 单个完成态事件"模型；与 runtime-semantics §6.3-§6.4、event-registry §3 payload（无 phase 字段）一致；§5.4 Table B 与之呼应。✓ 无残留矛盾。
+
+### 5.5 FK-off 应用层不变式
+
+§18.3 列出 8 条不变式，与 runtime-semantics §14 逐条对应；`SessionStore.referential_check()` 在启动/周期运行。✓
+
+---
+
+## 6. 内在一致性与冲突审查
+
+| 检查点 | 结果 |
+|---|---|
+| §5.3 EventStore 正文 vs §22.2 类图 | ✓ 一致（append/append_many/query + publish-after-commit 边） |
+| §20.4 Agent 状态机 vs §5.4 `agent.started` 投影 | ✓ R1-02 修复后自洽（单状态 + §20.4 过渡） |
+| §10.3 Compaction 时序 vs §19.3 序列图 | ✓ 一致（仅 summary.created 插行） |
+| §4.4 derive_command_status vs contracts §17 CommandRunProjection.status | ✓ 五值一致 |
+| §17 CLI 命令清单 vs overview §14 catalog | ✓ DD 含 6 个 catalog 命令 + 5 个基础命令(run/init/doctor/e2e/release)，后者在 overview §4/§15 有据，属合理超集 |
+| §8.1 exit code vs baselineV1 §8 | ✓ 6 个 code 逐行一致 |
+
+未发现跨章节概念冲突或时序矛盾。
+
+---
+
+## 7. UML 类图详细审查（§22.1-§22.8 逐张）
+
+- **§22.1 契约包**：`EventSource.kind` 枚举与 §2 runtime-role 表协同；`RuntimeEvent → EventSource`、`WorkerResult → Artifact/Evidence`、`AirError → EntityRef` 边正确。✓
+- **§22.2 核心服务**：`EventStore → EventBus : publishes after commit`、`ProjectionStore → EventBus : subscribes` 准确反映事件流。✓
+- **§22.3 Scheduler**：6 个被组合类（TaskGraph/WavePlanner/RetryPlanner/WorkspaceManager/AgentMonitor/WorkerManager）齐全。建议旁注 "Scheduler owns policy; WorkspaceManager owns mechanism"（与 §7.5 呼应），非必须。
+- **§22.4 Tool/Permission** — **F3**：图中 `ToolRegistry` 缺少到 `ToolDefinition` / `ToolExecutor` 的关系边；正文 §9.1 明确 ToolRegistry 注册/调用这两者。建议补 `ToolRegistry --> ToolDefinition : registers` 与 `ToolRegistry --> ToolExecutor : invokes`。
+- **§22.5 Worker/IPC**：5 个 Role 实现 `WorkerRole` 继承齐全；`docs` TaskType 复用 ExecutorRole 无需新增节点，与 §8.3 一致。✓
+- **§22.6 Provider**：双 adapter 继承 + converter + normalizer 边正确。✓
+- **§22.7 Context/Compaction** — **F2**：图中 `ContextAssembler` 仅连 `PromptLayerLoader`/`CompactionPolicy`，但 §10.2 表 2 明确 ContextAssembler 内部装配 L2/L6/L7/L8 需读 `EvidenceStore`、`SessionStore.messages/tool_runs/command_runs`。类图低估了实际耦合。建议补 `ContextAssembler --> EvidenceStore`、`ContextAssembler --> SessionStore`（依赖型虚线即可）。
+- **§22.8 Agents**：`MainAgent`/`ArchitectureDesigner` → Scheduler/ContextAssembler/ProviderManager/EventIngestor 边正确；与 §2 "runtime role 不走 load_role" 决策一致。✓
+
+---
+
+## 8. 新发现（P0 / P1 / P2 分类）
+
+### F1 [P2] `EvidenceStore.list_for_task()` 不在契约
+
+- **位置**：DD §10.2 表 2，L6 Evidence 行（L932）
+- **问题**：引用 `EvidenceStore.list_for_task()`，但 contracts §14 `EvidenceStore` 仅声明 `create()` 与 `list_for_entity(entity_type, entity_id)`。
+- **根因**：与 R5 的 `current_profile()` 同类——为给 L6 找一个明确来源，点名了不存在的方法。
+- **影响**：实现 ContextAssembler 时找不到 `list_for_task()`；轻微，因为 `list_for_entity("task", task_id)` 即可替代。
+- **建议**：改为 `EvidenceStore.list_for_entity("task", task_id)`（契约真实方法）。
+- **工作量**：2 分钟
+
+### F5 [P2] `DoctorService.check_capability()` 不在契约
+
+- **位置**：DD §16.1（L1201）
+- **问题**：`DoctorService` 类列出 `+check_capability(capability): Promise<DoctorIssue[]>`（public `+`），但 contracts §19 `DoctorService` 仅声明 `run(input): Promise<DoctorRunOutput>`。
+- **根因**：把内部分解步骤当成公共契约方法暴露。
+- **影响**：与 §0 "不引入新公共契约" 约束冲突；轻微。
+- **建议**：改为私有 `-check_capability(...)`（与同段 `-self_bootstrap()` 一致风格），或并入 `run()` 内部说明。
+- **工作量**：1 分钟
+
+### F2 [P2] §22.7 类图缺 ContextAssembler 内部装配依赖边
+
+- 见 §7。建议补 `ContextAssembler --> EvidenceStore` / `--> SessionStore` 虚线依赖。
+- **工作量**：3 分钟
+
+### F3 [P2] §22.4 类图缺 ToolRegistry → ToolDefinition/ToolExecutor 边
+
+- 见 §7。建议补两条注册/调用关系边。
+- **工作量**：3 分钟
+
+无 P0、无 P1。F1/F5 是契约边界的两处"点名了不存在的方法"，与本轮独立抽样法直接相关；F2/F3 是类图完整度问题，不影响正文设计正确性。
+
+---
+
+## 9. 门禁判定
+
+| 条件 | 状态 |
+|---|---|
+| P0 = 0 | **PASS** |
+| 契约覆盖 100% | **PASS** |
+| 事件覆盖 100% | **PASS** |
+| DB Schema 覆盖 100% | **PASS** |
+| 状态机覆盖 100% | **PASS** |
+| L0-L9 覆盖 | **PASS** |
+| 禁止路径全继承 | **PASS** |
+| 架构无循环依赖 | **PASS** |
+| 职责分离无泄漏 | **PASS** |
+| R 系列(R1/R2)修复已闭合 | **PASS** |
+| 契约/payload 不变性（无越界方法/字段） | **FAIL**（F1 + F5 两处契约方法越界） |
+| UML 类图完整度 | **CONDITIONAL**（F2 + F3 欠边，不影响正确性） |
+
+**门禁结果：CONDITIONAL PASS** — 覆盖性、架构、状态机全部 PASS；4 项 P2 不阻断实现，但建议在冻结前一并修复以保持契约纯净。
+
+---
+
+## 10. 多轮累积视角
+
+| 轮次 | 模型 | 主要贡献 | P0 | P1 | P2 |
+|---|---|---|---|---|---|
+| R1 | DeepSeek | 全量覆盖性 | 0 | 0 | 3 |
+| R2 | MIMO 2.5 Pro | 内在一致性 | 0 | 2 | 5 |
+| R3 | GPT-5.5 Pro | 基线冲突检测 | 0 | 2 | 4 |
+| R4 | Opus 4.8 | 验证 + 根因 | 0 | 2 | 5 |
+| R5 | Opus 4.7 | 修复回归引入检测 | 0 | 3 | 2 |
+| R5-fix | — | R1-01~R2-02 闭合（commit af99aed） | — | — | — |
+| **R6** | **Opus 4.8（本次全量复查）** | **契约方法越界抽样 + 类图完整度** | **0** | **0** | **4** |
+
+**累积说明**：R1-R5 的 P1×4 + P2×9 + R 系列 5 项均已闭合。R6 在更系统的"点名方法 vs 契约"抽样下浮出 F1/F5（与 R5 的 `current_profile()` 同型，说明此类问题需要一次性全表扫描），以及两处类图欠边 F2/F3。无新增 P0/P1。
+
+---
+
+## 11. 最终结论与建议
+
+### 11.1 设计成熟度
+
+详细设计在**覆盖性、架构合理性、状态机一致性、基线遵守（主体）**四个维度均达标。事件 / 表 / 契约 / 状态机 / 禁止边 / L0-L9 / UML 七类对象 100% 覆盖，依赖无环，职责分离干净，跨 DB outbox 与 FK-off 不变式自洽。
+
+### 11.2 剩余问题
+
+仅剩 4 项 P2，全部为局部精修：
+- **F1 / F5**：两处"点名了不存在的契约方法"（`EvidenceStore.list_for_task`、`DoctorService.check_capability`），合计 3 分钟可改为真实方法 / 改私有。
+- **F2 / F3**：两张类图欠依赖边，合计 6 分钟补全。
+
+### 11.3 建议
+
+**总工作量约 9 分钟**即可收束全部 4 项 P2。这些不阻断进入实现阶段，但建议在正式冻结前一并修复，使契约纯净度与类图完整度达到 100%，避免实现者在 ContextAssembler / DoctorService 处遇到与 R5 同型的"找不到方法"困惑。
+
+### 11.4 最终判定
+
+**CONDITIONAL PASS (R6)** — 详细设计满足全量覆盖与结构正确性，R 系列回归修复全部闭合；本轮新增 4 项 P2（2 契约方法越界 + 2 类图欠边），均为分钟级修复，不阻断实现。
+
+---
+
+End of full-scope re-audit.