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>
This commit is contained in:
AirCoding
2026-06-01 14:23:45 +08:00
parent af99aed1f4
commit 2673e49cf8
3 changed files with 696 additions and 2 deletions

View File

@@ -929,7 +929,7 @@ configuration or resource loading (L0, L1, L3, L5). The remaining layers are ass
|---|---|---|
| L2 Safety | Active permission profile (`~/.air/permissions.yaml` + project permission config; same source the `PermissionEngine` implementation reads internally — no new contract method) | `ContextAssembler` |
| L4 Architecture | `TaskSpec.context_refs.arc_ref` → load from plan/ADR/C4 docs | `ContextAssembler` |
| L6 Evidence | `TaskSpec.context_refs.artifacts` + `EvidenceStore.list_for_task()` | `ContextAssembler` |
| L6 Evidence | `TaskSpec.context_refs.artifacts` + `EvidenceStore.list_for_entity("task", task_id)` | `ContextAssembler` |
| L7 Conversation | `SessionStore.messages.list_by_session()` (recent N messages) | `ContextAssembler` |
| L8 Tool output | `SessionStore.tool_runs` + `command_runs` for current task | `ContextAssembler` |
| L9 Immediate | `TaskSpec.description` + `acceptance_criteria` + immediate user instruction | `ContextAssembler` |
@@ -1198,7 +1198,7 @@ Implements contracts §19.
```text
class DoctorService implements DoctorService
+run(input: DoctorRunInput): Promise<DoctorRunOutput>
+check_capability(capability): Promise<DoctorIssue[]>
-check_capability(capability): DoctorIssue[] // internal helper, not a public contract method
-self_bootstrap(): DoctorIssue[] // Bun, SQLite, shell, .air writability
```
@@ -2124,6 +2124,8 @@ classDiagram
+register_tools(tool_registry): Promise~void~
}
ToolRegistry --> PermissionEngine
ToolRegistry --> ToolDefinition : registers
ToolRegistry --> ToolExecutor : invokes
PermissionEngine --> PathClassifier
PermissionEngine --> CommandRiskAnalyzer
CapabilityRegistry --> ToolRegistry : registers tools
@@ -2245,6 +2247,8 @@ classDiagram
}
ContextAssembler --> PromptLayerLoader
ContextAssembler --> CompactionPolicy
ContextAssembler ..> EvidenceStore : L6 evidence
ContextAssembler ..> SessionStore : L7/L8
PromptLayerLoader --> PromptLayer
```