AirCoding/AirPlan/docs/architecture/gpt5概要设计审查.md

# GPT-5 概要设计审查

Date: 2026-05-29
Status: Traceability audit of `system-overview-design.md` against frozen baselines
Scope: Baseline-to-overview full item-by-item comparison; frozen docs are authoritative, overview is amendable

## 1. 审查范围

审查对象：`AirPlan/docs/architecture/system-overview-design.md`

审查基线（冻结，不修改）：

1. `AirPlan/docs/analysis/requirements.md`
2. `AirPlan/docs/architecture/baselineV1.md`
3. `AirPlan/docs/architecture/solution-architecture.md`
4. `AirPlan/docs/architecture/interface-contracts-v1.md`
5. `AirPlan/docs/architecture/db-schema-v1.md`
6. `AirPlan/docs/architecture/event-registry-v1.md`
7. `AirPlan/docs/architecture/runtime-semantics-v1.md`
8. `AirPlan/docs/architecture/c4/module.md`
9. `AirPlan/docs/architecture/c4/code-view.md`
10. `AirPlan/docs/architecture/main-agent-state-machine.md`
11. `AirPlan/docs/architecture/scheduler-state-machine-v1.md`
12. `AirPlan/docs/architecture/scope-escalation-v1.md`
13. `AirPlan/docs/architecture/security-model-v1.md`
14. `AirPlan/docs/architecture/capability-trust-v1.md`
15. `AirPlan/docs/architecture/provider-capability-matrix-v1.md`
16. `AirPlan/docs/architecture/prompt-layering-v1.md`
17. `AirPlan/docs/architecture/artifact-naming-v1.md`
18. `AirPlan/docs/architecture/error-taxonomy-v1.md`
19. `AirPlan/docs/architecture/tool-registry-v1.md`
20. `AirPlan/docs/architecture/cross-platform-matrix-v1.md`
21. `AirPlan/docs/architecture/decisions-round-1.md`
22. `AirPlan/docs/architecture/decisions-round-2.md`
23. `AirPlan/docs/architecture/decisions-round-3.md`
24. `idea.md`

原则：冻结基线不再修改。概要设计在基线之上补充设计决策，不修改基线原文。基线与概要设计冲突时以基线为准，概要设计标注差异并解决。

---

## 2. 总体结论

`system-overview-design.md` 在容器、运行时组件、事件/投影、执行流、权限、上下文、UI/HUD、Doctor/restore、验证门禁等大方向上与基线一致。主要缺口集中在：

- 参考项目边界和执行层质量基准未明确
- 技术栈细节（Bun/Turborepo/OpenTUI 包名/Python/分发）缺失
- 全局 `~/.air/` 布局和 `project_id` UUID 未提及
- 事件 envelope/路由/版本规则、IPC 字段/退出码未展开
- TaskSpec/WorkerResult 字段族和 failed vs blocked 语义缺失
- Claude Code 执行原语（read-before-edit、exact edit、verification-before-completion）未明确
- 权限边界规则（realpath、`.git/` 保护、build 目录不受限、`~/.air/` 内部绕过、`sudo` 不自动高危、项目外写入备份）未完整
- 日志、迁移、扫描器/初始化、分发、测试分类、contracts 包文件清单缺失
- C++ 工具链细节（Ninja/Make 优先级、compile_commands 按需生成、clangd CLI 模式、DiagnosticParser 所有权已解决但需确认）不完整
- Provider 能力矩阵摘要、OpenCode UI 复用边界、UI 设计资源能力缺失

以下按基线章节逐项列出缺口和建议补充内容。

---

## 3. 逐项缺口清单

### 3.1 产品定位（baseline §1）

缺口：概要设计未明确"not a Claude Code plugin/wrapper"；未列出完整编码循环（requirement → architecture → code reading → implementation → build → static analysis → test → run/debug → evidence → fix → summary → mining）。

建议补入概要设计 §2：

```md
AirCoding is a self-owned local AI coding runtime, not a Claude Code plugin/wrapper.

Canonical V1 loop:
requirement → architecture/interface design → code reading → implementation planning
  → build → static analysis → test → run/debug → crash/log/network/GUI evidence analysis
  → fix → change summary → experience mining
```

### 3.2 参考项目与边界（baseline §2）

缺口：概要设计未说明参考影响和复用边界。

建议新增 §2.1 Reference Influence：

```md
Reference influences for V1.0.0 Alpha:

- Claude Code: primary execution-layer quality benchmark (read-before-edit, exact conservative edits,
  small patches, no unrelated refactors, verification-before-completion, evidence-backed closure).
- OpenCode: UI visual patterns and OpenTUI primitives only; no SDK/sync/session business-state reuse.
- Hermes Agent: experience mining, Nudge Engine triggers, Curator daemon, self-patch, SKILL.md format.
- OpenAI Codex: shell/patch/test loop and tool orchestration ideas.
- Anthropic Claude Skills: SKILL.md structure, skill directory layout, trigger descriptions.
- asciinema / Atuin / claude-hud: PTY capture, command history indexing, HUD/statusline layout.
```

### 3.3 技术基线（baseline §3）

缺口：概要设计未明确 Bun、Bun workspaces + Turborepo、OpenTUI 包名、SQLite、NDJSON、Python subprocess-only、binary tarball。

建议补入 §3 或新增 §3.1 Technology Baseline：

```md
Technology baseline:

- Runtime: TypeScript on Bun
- Monorepo: Bun workspaces + Turborepo
- TUI: `@opentui/solid`, `@opentui/core`, `@opentui/keymap`
- Storage: SQLite per session, project-local
- IPC: NDJSON over stdio
- Python: subprocess-only helper layer for existing scripts/libraries, not core runtime
- Distribution: binary tarball before public package channels
```

### 3.4 包集与未来扩展（baseline §4）

缺口：未来 `toolchain-python`、`toolchain-rust`、`toolchain-js` 未提及；`runtime must never depend on tui` 未显式说明。

建议补入 §4 或 §5：

```md
Future language packages:
- packages/toolchain-python
- packages/toolchain-rust
- packages/toolchain-js

Invariant: runtime must never import tui.
```

### 3.5 全局目录与 project_id（baseline §5）

缺口：全局 `~/.air/` 布局完全缺失；`project_id` 是稳定 UUID 未提及；`.air/local/` 应 gitignore 未提及。

建议新增 §8.0 Global Filesystem Layout：

```md
Global user directory:

~/.air/
  config.yaml
  models.yaml
  permissions.yaml
  compaction-rules.md
  project-index.db
  cache/{plugins,providers,lsp,downloads}/
  resources/versions/<version>/
  skills/
  logs/{air.log,air.developer.log}

`project_id` is a stable UUID generated at initialization and stored in `.air/shared/project.json`.
It is not derived from the absolute path.

`.air/local/` should be gitignored by default.
```

### 3.6 运行时架构细节（baseline §6）

缺口：Main Agent 保持 idle-ready、不执行后台工作的规则未显式；Scheduler 详细职责（TaskGraph、waves、conflicts、retries、workspaces、heartbeat、merge、restart recovery）未展开；worker 是独立角色循环而非通用循环未说明。

建议补入 §6 或 §7：

```md
Main Agent must remain idle-ready and never perform long-running background work.

Scheduler owns: TaskGraph loading, dependency resolution, write-area conflict handling,
wave planning, retry budgets, child worker dispatch, heartbeat monitoring, workspace
merge coordination, and restart recovery.

Each worker is an independent role loop (Executor/Reviewer/Debugger/Compactor/ExperienceMiner),
not a single generic worker loop.
```

### 3.7 RuntimeEvent envelope（baseline §7）

缺口：envelope 字段、`route` append-only 规则、EventStore 决定持久化策略、payload schema 变更需递增 event version 未展开。

建议补入 §9：

```md
RuntimeEvent envelope: id, type, version, timestamp, session_id, project_id?, source, route[], payload.

`route` is append-only: producers append their segment, never rewrite earlier entries.
EventStore decides durable vs ephemeral persistence by event type; producers must not decide ad hoc.
Payload schema changes require incrementing the event `version` for that event type.
```

### 3.8 IPC 协议细节（baseline §8）

缺口：Bun 子进程、IPC envelope 字段、stdout-only 协议、stderr 致命回退、退出码映射未展开。

建议补入 §11：

```md
IPC envelope fields: id, direction, kind, timestamp, session_id, agent_id, correlation_id?, protocol_version, payload.

Worker stdout is for NDJSON protocol only; stderr is for fatal fallback/logging.

Exit codes:
0 = success
1 = task failed
2 = worker crashed
3 = protocol error
4 = timeout
5 = cancelled
```

### 3.9 TaskSpec / WorkerResult（baseline §9）

缺口：TaskSpec 字段族（type、scope、deps、verification、constraints、refs、output_contract）和 WorkerResult 字段族（status、changed_files、artifacts、verification、risks、follow_up_tasks、evidence）未展开；`failed` vs `blocked` 语义未定义。

建议新增 §10.7 TaskSpec and WorkerResult Overview：

```md
TaskSpec required field families: type, title, description, acceptance_criteria, scope, dependencies,
verification, constraints, context_refs, output_contract.

WorkerResult required outputs: task_id, agent_id, agent_type, status, summary, changed_files,
artifacts, verification[], risks[], follow_up_tasks[], evidence_refs[], result.

- `failed`: task goal not achieved but Scheduler may decide retry/skip.
- `blocked`: higher-level decision or external condition required.
- `cancelled`: explicitly stopped.
```

### 3.10 工具与能力系统（baseline §10）

缺口：ToolDefinition schema 验证规则、`shell.run` 对应 Bash 命令、流式工具最终结果规则、能力 manifest/trust/dependency 生命周期未展开。

建议补入 §10.4 或 §12：

```md
ToolDefinition uses schema-validated input/output at registration and dispatch.
Shell commands run through `shell.run` tool.
Streaming tools emit progress events and must end with exactly one final `tool.result`.

Capability lifecycle:
- manifest load → validation → enable/disable → namespaced tool registration
- dependencies checked/installed by Doctor, not by arbitrary plugin scripts
- trust metadata: built_in | project_local | user_installed | verified_publisher | untrusted
```

### 3.11 Claude Code 执行原语（FR-009）

缺口：read-before-edit、exact conservative edits、small patches、no unrelated refactors、verification-before-completion 未作为系统级约束。

建议新增 §10.8 Execution Discipline：

```md
Execution-layer tools enforce Claude Code-quality discipline:

- read-before-edit: fs.edit/fs.patch require prior read observation for the target file
- exact conservative edits: old_string must match exactly, no guessing
- small patches: no broad rewrites unless explicitly fs.write
- no unrelated refactors: changes stay within task scope
- schema-validated tool I/O at all boundaries
- root-cause diagnosis before random retries
- verification-before-completion: code-changing tasks cannot complete without build/test/debug
  evidence or an explicit skipped-gate report
```

### 3.12 权限边界规则（baseline §11-12, security-model）

缺口：realpath symlink 解析、`.git/` 写保护、build 目录不受限、`~/.air/` 内部绕过 PermissionEngine、`sudo` 不自动高危、静态高危白名单 + LLM escape hatch、项目外写入需先备份到 `.air/local/backups/`。

建议补入 §12：

```md
Permission edge rules:

- Path policy resolves symlinks with `realpath` before risk classification.
- `.git/` writes require confirmation unless project policy overrides.
- Build/output directories are unrestricted for C++ workflows.
- `~/.air/` internal operations bypass PermissionEngine.
- `sudo` alone is not high-risk; system-sensitive paths still require confirmation.
- High-risk detection: static system path whitelist + LLM escape hatch only when
  static classification is inconclusive.
- Project-outside writes are backed up to `.air/local/backups/` git history before modification.
```

### 3.13 SQLite / 消息存储（baseline §13）

缺口：WAL/NORMAL 设置、`foreign_keys = OFF` + 应用层不变量、Anthropic canonical content JSON 存储、draft 删除规则、`message_parts` 不作为源表、查询友好列、`ui_state` 定期/退出时刷新未说明。

建议补入 §8.2 或 §13：

```md
Session DB uses WAL + synchronous NORMAL + foreign_keys OFF with application-level
referential invariant checks and startup orphan scans.

Messages store complete Anthropic canonical content JSON. Query-heavy relations
are extracted into domain tables and indexes.

`message_drafts` exist only during streaming/incomplete assistant output and are
deleted after the completed message is written.

`ui_state` is not source of truth for runtime state; it is flushed periodically and on exit.
```

### 3.14 Contracts 包文件清单（baseline §14）

缺口：`packages/contracts/src/` 的文件清单（ids.ts、runtime.ts、event.ts、ipc.ts、task.ts、worker-result.ts、tool.ts、artifact.ts、evidence.ts、project.ts、provider.ts、permission.ts、ui.ts、error.ts、capability.ts、platform.ts）未列出。

建议补入 §4 或新增 §4.1 Contracts Package Baseline：

```md
Expected contracts package structure:

packages/contracts/src/
  index.ts, ids.ts, runtime.ts, event.ts, ipc.ts, task.ts, worker-result.ts,
  tool.ts, artifact.ts, evidence.ts, project.ts, provider.ts, permission.ts,
  ui.ts, error.ts, capability.ts, platform.ts
```

### 3.15 Artifact 命名与布局（baseline §15a）

缺口：artifact URI/ID 命名规范、目录映射、压缩规则、metadata 记录、evidence 链接 artifact ID 未展开。

建议补入 §8.2 或 §6：

```md
Artifacts use canonical URI/ID naming with ULID, temp-write → hash/size → atomic rename → DB record.
Evidence links reference artifact IDs for claim traceability.
Artifact naming/layout rules are defined in the frozen artifact-naming-v1.md.
```

### 3.16 Context / Compaction（baseline §15b）

缺口：ContextAssembler 输出 Anthropic canonical messages、记录 token 预算 omissions、`context.compaction.requested`、compaction rules 文件格式（Markdown + YAML frontmatter）、位置（built-in / `~/.air/compaction-rules.md` / `<project>/.air/shared/compaction-rules.md`）、copy-on-write 语义未完整。

建议补入 §13：

```md
ContextAssembler outputs Anthropic canonical messages and records omissions.
Compaction rules use Markdown + YAML frontmatter at:
- built-in default
- ~/.air/compaction-rules.md
- <project>/.air/shared/compaction-rules.md

Compaction uses copy-on-write: snapshot messages, async Compactor produces summary,
original messages preserved for backtracking.
```

### 3.17 Memory / Skills / Debug Knowledge（baseline §16）

缺口：project rules 路径（`<project>/.air/shared/rules/`）、skills 路径（`~/.air/skills/<skill-name>/SKILL.md`）、promotion 策略（非调试经验需重复出现 + 用户确认，调试经验以验证证据为置信度）、debug sharing 需 redaction/preview/显式授权。

建议补入 §13 或 §8.3：

```md
Project rules: <project>/.air/shared/rules/{project-rules.md,toolchain-rules.md}
Skills: ~/.air/skills/<skill-name>/SKILL.md

Non-debug memories require repeated occurrence (N=3) plus user confirmation before promotion.
Debug experience confidence comes from verified evidence, not numeric scoring.
Debug knowledge sharing requires redaction, preview, and explicit authorization.
```

### 3.18 Provider 能力矩阵（baseline §17）

缺口：Anthropic/OpenAI 原生、OpenRouter/ollama/custom 兼容、provider conversion report、同提供商切换无格式转换成本（但 V1 session 选择在启动后固定）未说明。

建议补入 §6 或 §14：

```md
Provider support:
- Native: Anthropic, OpenAI
- Compatible: OpenRouter, ollama, custom Anthropic/OpenAI-compatible endpoints

Same-provider model switching has no format conversion cost, but V1 session selection
is fixed after startup (provider/model immutability rule).

Provider conversion reports track omissions/warnings/required_confirmation for lossy translation.
```

### 3.19 OpenCode UI 复用边界（baseline §18）

缺口：OpenCode 复用的具体 UI 原语列表和不复用 SDK/sync/session 业务状态的规则。

建议补入 §14：

```md
OpenCode UI primitive reuse: theme system, dialog/modal/toast patterns, keymap wrapper,
layout style, spinner/border/error components, markdown/code/diff rendering patterns.

No reuse of OpenCode SDK/sync/session business layer.
```

### 3.20 UI 设计资源能力（baseline §19）

缺口：可选 `ui-design-assets` 能力（ASCII/wireframe/spec/SVG/screenshot analysis/外部 prompt、bitmap post-MVP、artifacts first、preview before project writes）缺失。

建议补入 §14 或 §2：

```md
Optional `ui-design-assets` capability for V1.0.0 Alpha:
ASCII/wireframe mockups, design specs, SVG icons, screenshot design analysis,
prompts for external image generators.

Generated design assets are artifacts first and must be shown to the user
before being written into project files. Production bitmap generation is post-Alpha.
```

### 3.21 C++ 工具链细节（baseline §20）

缺口：CMake Ninja-first/Make fallback、CTest/GoogleTest、cppcheck（clang-tidy later）、clangd CLI mode、`compile_commands.json` 按需生成不缓存、build-system 冲突展示给用户、内置修复优先然后路由 Debugger。

建议补入 §10.6：

```md
C++ toolchain details:

- Build: CMake built-in, Ninja first then Make fallback.
- Test: CTest + GoogleTest first.
- Static analysis: cppcheck built-in; clang-tidy later.
- Code intelligence: clangd CLI mode.
- compile_commands.json: generated on demand, not persisted as cache.
- Build-system conflicts shown to the user.
- BuildTool attempts built-in repair first; unresolved failures route to Debugger.
- DiagnosticParser: deterministic extraction in toolchain-cpp; LLM interpretation in Debugger/Reviewer.
```

### 3.22 项目初始化（baseline §21）

缺口：full metadata-only scanner（完整目录树、无排除、无深度限制）、extension stats / special files / git summary、LLM ProjectProfile + 用户确认、schema path 检测。

建议新增 §15.1 Project Initialization：

```md
Project initialization uses a full metadata-only scanner:
- complete directory tree, no directory exclusions, no depth limit
- file extension statistics, special file types, git summary
- no file content reading during tree scan
- symlink targets recorded, permission errors as error metadata

Scanner output is interpreted by Main Agent/LLM into a ProjectProfile.
User confirms or corrects the profile.
```

### 3.23 Schema 迁移（baseline §22）

缺口：检测 schema 版本、用户确认迁移计划（即使高权限模式也确认）、备份 `.air/`、失败回滚、迁移备份路径。

建议新增 §15.2 Schema Migration：

```md
Schema migration flow:

1. detect schema_meta.schema_version on session open
2. if older than current, display migration plan
3. require user confirmation (even in high-permission mode)
4. backup .air/ to .air/local/backups/migrations/<timestamp>/
5. apply migration
6. on failure, rollback to backup
```

### 3.24 日志与 Bundle（baseline §23）

缺口：`air.log`（用户可读）、`air.developer.log`（加密，开发团队公钥）、7 天保留、doctor bundle 不自动脱敏/不自动上传、bundle 与 debug knowledge 分离。

建议新增 §15.3 Logging：

```md
LoggingService writes:
- air.log: user-readable, startup/config/environment failures
- air.developer.log: full debug/performance log, encrypted with development-team public key

Default retention: 7 days, auto-rotated.

Doctor bundles are local artifacts containing full diagnostics.
Bundles are never auto-uploaded and are not necessarily auto-redacted.
Doctor bundle channel is separate from Debug Knowledge sharing/redaction flow.
```

### 3.25 测试分类（baseline §24）

缺口：unit/integration/E2E 定义、recorded LLM fixture replay for integration、real LLM for release gate E2E、cross-platform validation matrix。

建议补入 §17：

```md
Testing taxonomy:

- Unit: bun test, CI per push, <30s, no LLM calls
- Integration: CI per push, <1min, recorded LLM fixture replay
- E2E: release gate, real LLM calls, must pass before release

Validation references cross-platform matrix (Linux x86_64 tier 1, arm64/WSL2 tier 2).
```

### 3.26 分发（baseline §25）

缺口：tarball 内容（`bin/air`、`resources/`、`LICENSE`）、resources 内容（templates、prompts、themes、HUD presets、Python scripts、toolchain resources）、无 npm/brew/apt/winget 直到稳定。

建议新增 §17.1 Distribution：

```md
Distribution:

Binary tarball contains: bin/air, resources/, LICENSE

Resources include: compaction rule templates, HUD presets, prompt assets,
Python helper scripts, toolchain resources.

No public package channels (npm, brew, apt, winget) until stable.
```

### 3.27 冻结基线完整列表（baseline §26）

缺口：概要设计 §1 的 source documents 列表不完整，缺少多个冻结基线。

建议更新 §1：

```md
Source documents (frozen baselines):

1. requirements.md
2. solution-architecture.md
3. baselineV1.md
4. interface-contracts-v1.md
5. db-schema-v1.md
6. event-registry-v1.md
7. runtime-semantics-v1.md
8. c4/module.md
9. c4/code-view.md
10. main-agent-state-machine.md
11. scheduler-state-machine-v1.md
12. scope-escalation-v1.md
13. security-model-v1.md
14. capability-trust-v1.md
15. provider-capability-matrix-v1.md
16. prompt-layering-v1.md
17. artifact-naming-v1.md
18. error-taxonomy-v1.md
19. tool-registry-v1.md
20. cross-platform-matrix-v1.md
21. decisions-round-1.md
22. decisions-round-2.md
23. decisions-round-3.md
24. idea.md
25. todo.md

Where decision rounds conflict, later rounds supersede earlier rounds for V1.0.0 Alpha
unless a frozen architecture baseline explicitly says otherwise.
```

---

## 4. FR/NFR 覆盖矩阵

### 4.1 Functional Requirements

| FR | 覆盖状态 | 缺口 |
|---|---|---|
| FR-001 CLI Startup | 已覆盖 | — |
| FR-002 Project-Local State | 已覆盖 | 全局 ~/.air/ 缺失 |
| FR-003 Session Persistence | 部分覆盖 | WAL/NORMAL、canonical message JSON、draft 删除、no message_parts 缺失 |
| FR-004 Event-Driven Runtime | 部分覆盖 | envelope/route/version 规则缺失 |
| FR-005 Main Agent | 已覆盖 | — |
| FR-006 Architecture Designer | 已覆盖 | review gate 已补 |
| FR-007 Scheduler | 部分覆盖 | dependency/write-area/timeout/retry/concurrency 细节不足 |
| FR-008 Worker Agents | 已覆盖 | — |
| FR-009 Claude Code Primitives | 缺失 | read-before-edit、exact edit、verification-before-completion 未作为系统约束 |
| FR-010 Built-In Tools | 部分覆盖 | 工具清单不完整 |
| FR-011 Permission/Security | 部分覆盖 | 边界规则缺失 |
| FR-012 Capability Foundation | 部分覆盖 | source/trust/namespaced registration 需明确 |
| FR-013 Provider Layer | 部分覆盖 | provider 列表/兼容矩阵缺失 |
| FR-014 Context/Compaction | 部分覆盖 | omissions、Anthropic canonical output、rule locations 缺失 |
| FR-015 Artifact/Evidence | 已覆盖 | — |
| FR-016 TUI/HUD | 已覆盖 | OpenCode UI 复用边界缺失 |
| FR-017 C++ Workflow | 部分覆盖 | Ninja/Make、compile_commands、clangd 细节缺失 |
| FR-018 Doctor | 已覆盖 | first-start/fix nuance 部分缺失 |
| FR-019 Logging | 缺失 | 双日志、加密 dev log、7 天保留 |
| FR-020 Release Gate | 已覆盖 | — |

### 4.2 Non-Functional Requirements

| NFR | 覆盖状态 | 缺口 |
|---|---|---|
| NFR-001 Local-First | 已覆盖 | — |
| NFR-002 Recoverability | 已覆盖 | — |
| NFR-003 Extensibility | 已覆盖 | — |
| NFR-004 Provider Flexibility | 部分覆盖 | 跨 provider 稳定性列表不明确 |
| NFR-005 UI Responsiveness | 部分覆盖 | Main Agent/TUI 保持响应需显式说明 |
| NFR-006 Evidence-Based Completion | 已覆盖 | — |
| NFR-007 Linux-First | 部分覆盖 | tier-1/tier-2/experimental 平台矩阵不完整 |
| NFR-008 Security Boundary | 已覆盖 | — |

---

## 5. 需要用户决策的冲突点

### 5.1 D-014 vs 当前设计：DiagnosticParser 所有权

`decisions-round-1.md` D-014 要求所有 compiler/linker 输出由 LLM 解析。

当前概要设计和 `runtime-semantics-v1.md §12` 明确规定：

- `toolchain-cpp` 只做确定性提取
- LLM 解释归 Debugger/Reviewer

这不是概要设计的错误，而是后续基线已覆盖了 D-014 的早期表述。建议在概要设计中注明：

```md
D-014 (round-1 LLM-parsed diagnostics) is superseded by runtime-semantics §12 for V1.0.0 Alpha:
deterministic extraction in toolchain-cpp, LLM interpretation in Debugger/Reviewer context.
```

### 5.2 D-025/D-037 vs D-047：Compaction rules 文件格式

D-025/D-037（round-2）提到 YAML compaction rules。D-047（round-3）改为 Markdown + YAML frontmatter。概要设计应采用 round-3 的 Markdown 格式并注明 round-3 取代 round-2。

---

## 6. 修复建议优先级

### P0 — 概要设计必须补充（影响下游设计/实现）

1. Claude Code 执行原语（§10.8）
2. 权限边界规则（§12 补充）
3. TaskSpec/WorkerResult 字段族和 failed/blocked 语义（§10.7）
4. RuntimeEvent envelope/route/version 规则（§9 补充）
5. IPC envelope 字段和退出码（§11 补充）
6. SQLite 消息存储不变量（§8.2 补充）
7. 全局 ~/.air/ 布局和 project_id（§8.0 补充）
8. 冻结基线完整列表（§1 更新）

### P1 — 概要设计应补充（影响设计完整性）

9. 参考项目影响和边界（§2.1）
10. 技术栈细节（§3.1）
11. 项目初始化/扫描器（§15.1）
12. Schema 迁移（§15.2）
13. 日志（§15.3）
14. C++ 工具链细节（§10.6 补充）
15. Context/Compaction 规则位置和格式（§13 补充）
16. Memory/Skills 路径和 promotion 策略（§13 补充）
17. 测试分类（§17 补充）
18. 分发（§17.1）
19. Contracts 包文件清单（§4.1）
20. Provider 能力矩阵摘要（§6 补充）

### P2 — 概要设计可选补充

21. OpenCode UI 复用边界（§14 补充）
22. UI 设计资源能力（§14 补充）
23. Artifact 命名/布局摘要（§8.2 补充）
24. 未来语言包（§4 补充）
25. D-014 supersession 注明
26. D-025/D-037 vs D-047 format conflict 注明