chore: push all design docs, V2 plan specs, and current working state

Includes AirPlan design documents, AircOding-alpha1-plan, AirPlanV2,
AirPlan-ParaV2, AirPlan-Para V1 reference docs, and all working code
changes across packages.

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

AirPlan/docs/analysis/full-requirements-audit.md

@@ -0,0 +1,493 @@
+# AirCoding V1.0.0 Alpha — 完整需求、设计决策、约束提取
+
+**生成日期**: 2026-06-11
+**提取工具**: deepseek-v4-pro 全量提取
+**来源文档**: requirements.md + airplanV2-Qwen3.7-Max设计.md + baselineV1.md + solution-architecture.md + system-overview-design.md + system-detailed-design.md
+**参考原型**: air-suite-20260518 (V1 Python插件系统, 8个已验证插件)
+
+> 共 383 条。每条的 source 字段标注了来源文档和章节。
+
+---
+
+## FR (Functional Requirements) — 21条 + 7条子要求
+
+### 来源: requirements.md §3
+
+1. **FR-001** (requirements.md §3): CLI Startup and Project Initialization — 从CLI入口启动,检测/打开项目,需要时初始化`.air/`,加载资源/配置,运行只读Doctor,打开session。
+
+2. **FR-002** (requirements.md §3): Project-Local State — `.air/shared/`(可共享配置/规则/计划) + `.air/local/`(私有sessions/artifacts/workspaces/backups/local DBs)。
+
+3. **FR-003** (requirements.md §3): Session Persistence — SQLite at `<project>/.air/local/sessions/<session-id>/session.db`, 支持messages/drafts/durable events/task graph state/agents/tool/command runs/artifacts/diagnostics/evidence refs/workspaces/summaries/UI state。
+
+4. **FR-004** (requirements.md §3): Event-Driven Runtime — 发布RuntimeEvents用于实时行为,持久事件与域表更新事务一致。
+
+5. **FR-005** (requirements.md §3): Main Agent Conversation — 面向用户的Agent: 接收请求,适当直接回答,分类工作,显示进度,呈现阻断/确认。
+
+6. **FR-006** (requirements.md §3): Architecture Designer — 架构/接口/产品级决策路由到Architecture Designer: 更新架构制品,产生影响评估。
+
+7. **FR-007** (requirements.md §3): Scheduler and TaskGraph — 调度TaskSpec: hard/soft依赖,写区冲突处理,重试预算,子Worker派发,心跳监控,合并协调,重启恢复。
+
+8. **FR-007.5** (requirements.md §3): ADR级联失效与架构变更回滚 — 7条子要求:
+   - (a) 通过TaskNode.adr_refs溯源所有依赖该ADR的任务(含已完成)
+   - (b) 级联失效: completed→invalidated, running→终止, pending→cancelled
+   - (c) 冻结调度(dispatch_frozen),阻止新任务派发
+   - (d) 创建git回滚快照(rollback_ref),支持revert旧方案代码
+   - (e) 接收ArchitectureDesigner产出的PlanDelta增量重规划
+   - (f) apply_delta吸收新任务后解冻调度
+   - (g) 终审时检查INVALIDATED任务的旧代码是否已清理
+
+9. **FR-008** (requirements.md §3): Independent Worker Agents — Executor/Reviewer/Debugger/Compactor/ExperienceMiner作为独立Bun子进程,通过NDJSON IPC通信。
+
+10. **FR-009** (requirements.md §3): Claude Code-Quality Execution Primitives — 强制: read-before-edit, exact conservative edits, small patches, no unrelated refactors, permission checks, verification-before-completion。
+
+11. **FR-010** (requirements.md §3): ToolRegistry and Built-In Tools — Schema验证的工具: filesystem/shell/git/project scanning/完整C++ build/test/static-analysis/debug/GUI screenshot/network capture/artifacts/context assembly/permission requests/Doctor。
+
+12. **FR-011** (requirements.md §3): Permission and Security Model — 分类paths/commands/network/credentials,强制权限配置,保护系统敏感和凭证操作,项目外写入备份,拒绝不安全请求。
+
+13. **FR-012** (requirements.md §3): Plugin and Capability Foundation — manifest loading/validation/enable-disable config/dependency declaration/Doctor integration/namespaced tool registration/source-trust metadata/PermissionEngine enforcement。第三方registry/signing可延后,本地和内置capability打包必须可用。
+
+14. **FR-013** (requirements.md §3): Provider Layer — 内部Anthropic canonical消息,通过适配器路由provider调用,能力矩阵验证和转换报告。
+
+15. **FR-014** (requirements.md §3): Context Assembly and Compaction — 有序层组装prompt,适配token预算,记录遗漏,必要时copy-on-write压缩。
+
+16. **FR-015** (requirements.md §3): Artifact and Evidence Management — temp-file→atomic rename,记录URI/path/hash/metadata,通过evidence refs链接声明。
+
+17. **FR-016** (requirements.md §3): TUI and HUD — OpenTUI/Solid终端UI和HUD,仅消费ProjectionStore,不查询原始DB/EventBus。
+
+18. **FR-017** (requirements.md §3): Complete C++ Development Workflow — 项目检测→构建系统评估→CMake configure→Ninja优先/Make回退→编译器/链接器诊断解析→clangd代码智能查询→cppcheck静态分析→CTest/GoogleTest执行→debug run/log解析→失败诊断→范围修复→审查→证据支持验证。
+
+19. **FR-018** (requirements.md §3): Doctor — 启动时运行只读Doctor,报告环境/能力问题,在权限策略下支持修复模式。
+
+20. **FR-019** (requirements.md §3): Logging and Diagnostics — 可读`air.log`,加密`air.developer.log`,默认7天保留。
+
+21. **FR-020** (requirements.md §3): Release Gate — 定义tier-1 Linux发布门禁: unit tests/integration fixture replay/real LLM E2E/project init/C++ build-test flow/SQLite recovery/child IPC/TUI startup/artifact-event persistence。
+
+---
+
+## NFR (Non-Functional Requirements) — 8条
+
+### 来源: requirements.md §4
+
+22. **NFR-001** (requirements.md §4): Local-First Operation — 项目状态/制品/日志/调试知识保留在本地,除非用户显式导出/分享/上传。
+
+23. **NFR-002** (requirements.md §4): Recoverability — 从进程/session重启恢复:读取SQLite状态,检测丢失agents,保留workspaces,重建Scheduler队列。
+
+24. **NFR-003** (requirements.md §4): Extensibility — 通过`toolchain-*`包和能力清单添加语言/工具链支持。
+
+25. **NFR-004** (requirements.md §4): Provider Flexibility — 内部契约在Anthropic/OpenAI/OpenRouter/ollama/兼容端点间保持稳定。
+
+26. **NFR-005** (requirements.md §4): UI Responsiveness — Main Agent和TUI在后台Worker运行时保持响应。
+
+27. **NFR-006** (requirements.md §4): Evidence-Based Completion — 任务未获得build/test/debug/review证据或显式skipped-gate报告前不得标记完成。
+
+28. **NFR-007** (requirements.md §4): Linux-First Platform Support — Linux x86_64 tier1, arm64/WSL2 tier2, macOS实验, Windows native post-MVP/实验。
+
+29. **NFR-008** (requirements.md §4): Security Boundary Preservation — LLM输出/工具结果/插件/外部内容在被运行时契约和策略验证前为不可信数据。
+
+---
+
+## AC (Acceptance Criteria) — 13条
+
+### 来源: requirements.md §6
+
+30. **AC-01**: CLI starts and initializes/opens a project `.air/` tree.
+31. **AC-02**: Session DB schema initializes and persists messages/events/tasks/tool runs/artifacts.
+32. **AC-03**: EventStore transactionally applies core durable events to domain tables.
+33. **AC-04**: ProjectionStore hydrates and updates a usable TUI/HUD view.
+34. **AC-05**: Scheduler dispatches worker child processes via NDJSON IPC, supports tool calls, receives WorkerResult.
+35. **AC-06**: ToolRegistry executes filesystem/shell/git/artifact/context/doctor/C++/debug/GUI/network tools through PermissionEngine.
+36. **AC-07**: C++ workflow can detect, configure, build, statically analyze, test, debug, fix, review, re-verify a fixture project.
+37. **AC-08**: Failed build/test/debug commands produce diagnostics/artifacts/evidence refs and can trigger Debugger repair.
+38. **AC-09**: ContextAssembler produces Anthropic canonical messages with omissions where needed.
+39. **AC-10**: Provider adapter path can perform model calls under capability validation and conversion reporting.
+40. **AC-11**: Capability manifests can be loaded, validated, enabled, registered as namespaced tools.
+41. **AC-12**: Doctor reports platform/provider/toolchain/capability/display/network status and supports permissioned fix mode.
+42. **AC-13**: Release gate commands are documented and runnable on tier-1 Linux.
+
+---
+
+## CT (Constraints) — 16条
+
+### 来源: requirements.md §5 + baselineV1.md §3-§5
+
+43. **CT-01** (requirements.md §5): Runtime: TypeScript on Bun.
+44. **CT-02** (requirements.md §5): Monorepo: Bun workspaces + Turborepo.
+45. **CT-03** (requirements.md §5): TUI: OpenTUI/Solid.
+46. **CT-04** (requirements.md §5): IPC: NDJSON over stdio.
+47. **CT-05** (requirements.md §5): DB: SQLite per session with WAL/NORMAL/foreign_keys OFF.
+48. **CT-06** (requirements.md §5): Internal message format: Anthropic canonical content blocks.
+49. **CT-07** (requirements.md §5): C++ is first deep toolchain; runtime remains language-agnostic.
+50. **CT-08** (requirements.md §5): Python is subprocess-only helper layer, not core runtime.
+51. **CT-09** (requirements.md §5): Early distribution uses binary tarball, not public package channels.
+52. **CT-10** (requirements.md §5): Architecture docs and workflow state live under `AirPlan/`.
+53. **CT-11** (baselineV1 §3-§4): Monorepo packages (Alpha) — contracts, cli, tui, runtime, llm, toolchain-cpp.
+54. **CT-12** (baselineV1 §4): Dependency direction — contracts(no deps) → cli → tui/runtime/llm/toolchain-cpp; runtime → contracts + llm facade + toolchain via registry; tui → contracts only; runtime must not depend on tui.
+55. **CT-13** (baselineV1 §5): Global user directory — `~/.air/`.
+56. **CT-14** (baselineV1 §5): project_id is stable UUID in `.air/shared/project.json`, not derived from absolute path.
+57. **CT-15** (baselineV1 §5): `.gitignore`: `.air/local/`.
+58. **CT-16** (baselineV1 + solution-arch): All side effects must pass through ToolRegistry and PermissionEngine.
+
+---
+
+## RB (Reference Baselines) — 6条
+
+### 来源: baselineV1.md §2
+
+59. **RB-01** (baselineV1 §2): Claude Code CLI — Primary reference for execution-layer quality. Reference areas: file read/edit/write safety, exact conservative diff/update, patch granularity, tool lifecycle, permission checks, read-before-edit, small-step edits, no unrelated refactors, verification-before-completion, build/test/debug evidence, root-cause failure handling, blocker escalation, TAOR/TORI feedback loops.
+
+60. **RB-02** (baselineV1 §2): OpenCode — Reference for runtime layering, TUI visual style/interaction, session/event/sync concepts, provider/model abstraction, plugin/SDK ideas. **Reuse OpenTUI primitives. Do NOT reuse SDK/sync/session business state.**
+
+61. **RB-03** (baselineV1 §2): Hermes Agent — Reference for experience mining, Nudge Engine interval-triggered learning, Curator daemon, skill self-patching, SKILL.md format, FTS retrieval.
+
+62. **RB-04** (baselineV1 §2): OpenAI Codex — Reference for shell/patch/test direct execution loop, coding sandbox, tool orchestration, MCP implementation ideas.
+
+63. **RB-05** (baselineV1 §2): Anthropic Claude Skills — Reference for SKILL.md structure/frontmatter, skill directory layout (scripts/references/assets), reusable workflow packaging.
+
+64. **RB-06** (baselineV1 §2): asciinema / Atuin / claude-hud — Reference for PTY capture/terminal replay, command metadata/history indexing, HUD/statusline layout and activity display.
+
+---
+
+## PV (V1 Plugin Prototypes) — 8个已生产验证的插件工作流
+
+### 来源: air-suite-20260518 + airplanV2-Qwen3.7-Max设计.md §1.2
+
+> **核心架构原则**: Agent (MainAgent/Scheduler/Worker) 存在的目的是扩展插件的能力边界。**插件代表的工作流才是产品核心**。AirCoding V1.0.0 Alpha 是V1 8个插件从 Claude Code Skill 到 TypeScript 运行时的移植重构——不是从零开发,是给已验证的工作流换一个可靠的运行时底座。
+
+### 8个V1插件 → AirCoding移植映射
+
+| # | V1插件 | 目录 | 工作流 | AirCoding模块 | 移植状态 |
+|---|--------|------|--------|--------------|----------|
+| 1 | **AirArc** | `airplan-mkt/airarc/` | 架构规划设计器: 需求探讨→架构确认→生成规划 | `ArchitectureDesigner` | ❌ 正则替代LLM |
+| 2 | **AirEng** | `airplan-mkt/aireng/` | 调度引擎: 波次规划→Dispatch→Monitor→Merge→Repair | `Scheduler` | ⚠️ 基础可调度 |
+| 3 | **AirDo** | `airplan-mkt/airdo/` | 任务执行器: 接收TaskSpec→调用工具→验收→返回结果 | `ExecutorRole` | ⚠️ 简单任务可跑 |
+| 4 | **AirDbg** | `airplan-mkt/airdbg/` | 调试器: 确认症状→取证→定位根因→修复→验证→关闭 | `DebuggerRole` | ❌ 从未触发 |
+| 5 | **AirXDB** | `airplan-mkt/airxdb/` | GUI验证: 截图取证→diff对比→headless CI | `gui.screenshot` | ❌ 仅ImageMagick |
+| 6 | **AirNDB** | `airplan-mkt/airndb/` | 网络调试: 抓包→分析→TLS解密 | `network.capture` | ⚠️ tcpdump封装 |
+| 7 | **AirSDB** | `airplan-mkt/airsdb/` | 静态分析: cppcheck/clang-tidy→diff→多语言 | `toolchain-cpp` | ❌ 仅cppcheck注册 |
+| 8 | **AirContext** | `aircontext-mkt/` | 上下文管理: 压缩→token估算→stale lock检测 | `ContextAssembler`+`CompactorRole` | ⚠️ 基础实现 |
+
+### V1已验证能力 → AirCoding丢失清单
+
+| V1能力 | 来源缺陷 | AirCoding |
+|---------|----------|-----------|
+| 架构变更级联失效(ADR→Task失效→冻结→回滚→重规划) | P1-21, V2I-23 | ⚠️ 方法全实现, 零生产调用 |
+| 证据优先门控(不取证不许改代码) | P1-17, V2I-30 | ❌ |
+| 7步调试工作流强制(finish_worker 的 forced AirDbg routing) | P0-8, V2I-13, V2I-28 | ❌ |
+| Plan mode 阻断(架构器永不写代码) | P0-5, V2I-09 | ❌ |
+| 自主调度+中文锁定(不停下来问, 自动推进) | P0-6, P0-7, V2I-10, V2I-11 | ❌ |
+| 任务类型感知证据门控(GUI/Network/CodeOnly分类) | P0-1, V2I-04 | ❌ |
+| Worker超时+资源保护(7200s硬上限, load检测) | P1-10, V2I-07 | ⚠️ AgentMonitor基础 |
+| 修复回滚(pre_fix_snapshot, git revert修复) | V2I-29 | ✅ _create_rollback_snapshot |
+| 非原子写入保护(tempfile+os.replace) | P0-3 | ✅ ArtifactStore |
+| 并发控制(flock替代无锁读改写) | P0-4 | ✅ SQLite事务 |
+| Dispatch→Worker桥接(spawn_workers标准化,消除Agent回退) | P1-22, V2I-16 | ⚠️ WorkerManager可用 |
+
+---
+
+## AP (Architecture Principles) — 189条 (关键摘录)
+
+### 来源: baselineV1.md + solution-architecture.md + system-overview-design.md + system-detailed-design.md
+
+> 完整189条AP参见 `/home/airlongdian/DataDevices/AirWorkSpace/AirCoding/AirPlan/docs/analysis/requirements-audit-report.md`
+
+### 核心架构原则 (baselineV1)
+
+65. **AP-01**: AirCoding is a self-owned AI coding agent/runtime, not a Claude Code plugin wrapper.
+66. **AP-02**: Runtime is language-agnostic; C++ is first deep language profile.
+67. **AP-03**: Core loop: requirement → architecture design → code reading → implementation planning → build → static analysis → test → run/debug → evidence → fix → summary → experience mining.
+
+### 执行质量基准 (solution-architecture §3)
+
+68. **AP-45**: Execution quality follows Claude Code — read-before-edit, exact, conservative, small, verified before completion.
+69. **AP-46**: OpenCode is UI/runtime reference, not business-state dependency.
+70. **AP-47**: Project-local source of truth under `.air/`.
+71. **AP-48**: Events drive live behavior; SQLite drives recovery.
+72. **AP-49**: Workers are isolated child processes over NDJSON IPC.
+73. **AP-50**: Main Agent remains responsive; background work delegated to Scheduler.
+74. **AP-51**: Architecture changes are explicit — implementation-level continues silently.
+75. **AP-52**: Tool/capability boundaries are permissioned through ToolRegistry+PermissionEngine.
+76. **AP-53**: Provider boundary isolated — internal Anthropic canonical; adapters convert at boundary.
+77. **AP-54**: Evidence first-class — build/test/debug/review outputs become artifacts/evidence before completion.
+
+### 容器职责 (solution-architecture §4)
+
+78. **AP-55**: CLI: command entrypoint, startup, Doctor, project discovery, TUI/runtime bootstrap.
+79. **AP-56**: TUI/HUD: consumes ProjectionStore only, no SQLite/EventBus queries.
+80. **AP-57**: Runtime: MainAgent, ArchitectureDesigner, Scheduler, child process mgmt, EventBus/EventStore, SessionStore, ToolRegistry, PermissionEngine, CapabilityRegistry, ContextAssembler, ArtifactStore, EvidenceStore.
+81. **AP-58**: LLM: provider config, adapters, Anthropic canonical handling, conversion, capability matrix.
+82. **AP-59**: Toolchain C++: project detection, CMake, Ninja/Make, CTest, cppcheck, clangd, diagnostic parsing.
+83. **AP-60**: Contracts: compileable shared TS interfaces, no domain implementation deps.
+
+### 禁止路径 (system-overview §5)
+
+84. **AP-85**: Forbidden: TUI→SQLite, TUI→runtime private, Worker→SQLite, Worker→direct fs/shell/network, tool→no PermissionEngine, capability→install outside Doctor, provider→silent semantic loss, repository→scheduling policy, EventBus→recovery source, runtime→TUI import, LLM output→direct file/shell.
+
+### 控制流 (solution-architecture §7)
+
+85. **AP-71**: Startup: CLI→detect→load→open/init .air→read-only Doctor→open session DB→hydrate ProjectionStore→start TUI/Main Agent.
+86. **AP-72**: Normal execution: user→Main Agent classify→answer or plan→Scheduler create/load TaskGraph→ContextAssembler→dispatch Worker→tools→PermissionEngine→WorkerResult→retry/merge/review→report.
+87. **AP-73**: Requirement change: requirement.changed→Scheduler pause→Architecture Designer assess→silent continue or confirm/replan.
+88. **AP-74**: Recovery: restart→open DB→load tasks/agents→check liveness→emit lost/failed or resume→preserve workspaces→rebuild queues→hydrate ProjectionStore.
+
+### 数据架构 (solution-architecture §6)
+
+89. **AP-69**: SQLite: WAL/NORMAL/foreign_keys OFF.
+90. **AP-88**: Durable event insert + domain update in same SQLite transaction.
+91. **AP-91**: Event flow: Producer→EventIngestor→validate→durable: EventStore transaction+projection+EventBus publish; ephemeral: EventBus publish.
+
+### 安全 (solution-architecture §10, system-overview §12)
+
+92. **AP-79**: Security boundaries — LLM output untrusted; tools only path to effects; symlinks resolved by realpath; .git/ protected; project-outside writes require backup; credentials require confirmation; no auto-upload.
+93. **AP-104**: Permission evaluation order: tool capability → permission profile → TaskSpec scope → path/command/network risk → credential/system-sensitive → user prompt.
+94. **AP-105**: Permission actions: allow, deny, ask_user, block, refuse, announce_then_run.
+95. **AP-106**: Path risk categories (8): project_source, project_build_output, project_air_shared, project_air_local, project_git_internal, outside_project, credential_or_secret, system_sensitive.
+96. **AP-107**: Command risk categories (10): read_only, build, test, static_analysis, git_read, git_write, destructive, network, system_sensitive, credential_sensitive.
+
+### 上下文/压缩 (system-overview §13)
+
+97. **AP-109**: Compaction: ContextAssembler may request; Scheduler creates compact task; Compactor snapshots messages; summary.created; original messages preserved.
+98. **AP-158**: ContextAssembler assembles Anthropic-canonical context; fits to token_budget; reports omissions; sets compaction_requested if budget cannot fit required layers.
+99. **AP-77**: L0-L9 layers: runtime invariant, role/mode, safety/permission, project rules, architecture, task spec, evidence, conversation, tool history, instruction.
+
+### Worker/IPC (system-detailed-design §8)
+
+100. **AP-148**: WorkerManager spawn starts Bun child process then handshake; WorkerProcess owns NDJSON pipe.
+101. **AP-150**: Worker roles: ExecutorRole (scoped write), ReviewerRole (read-only), DebuggerRole (scoped write assigned), CompactorRole (summaries/artifacts only), ExperienceMinerRole (candidates/rules/skills assigned).
+102. **AP-151**: TaskType→WorkerRole: execute→Executor, review→Reviewer, debug→Debugger, compact→Compactor, mine_experience→ExperienceMiner, docs→Executor.
+103. **AP-103**: Workers never write SQLite directly; never perform side effects outside parent-mediated tools.
+
+### 调度器 (system-detailed-design §7)
+
+104. **AP-143**: Scheduler states: IDLE→LOADING_GRAPH→PLANNING_WAVE→DISPATCHING→MONITORING→COLLECTING_RESULTS→MERGING→REVIEWING_WAVE→REPAIRING_OR_CONTINUING. Terminals: COMPLETED, BLOCKED, CANCELLED.
+105. **AP-144**: TaskGraph: get_runnable_tasks honors hard deps completed, soft deps priority, conflict/serialization block concurrent dispatch on overlapping write areas.
+106. **AP-146**: RetryPlanner actions: retry, retry_serial, debug, skip, block, cancel.
+107. **AP-147**: WorkspaceManager strategies: main (no merge), worktree (git merge/patch), isolated_copy (copy-back/patch).
+
+### 可追溯性 (system-detailed-design §24)
+
+108. **AP-188**: System Detailed Design frozen as of 2026-06-01; multi-model review complete across 7 review rounds; all P0/P1/P2 findings closed; coverage: contracts 100%, events 100%, DB schema 100%, state machines 100%, forbidden edges 100%.
+
+### 不变量 (INV-1 ~ INV-5)
+
+109. **INV-1**: Session-DB state columns written only by event projection; no direct UPDATE from services.
+110. **INV-2**: Cross-DB/external writes use outbox model; EventStore.project() never opens external DBs or files.
+111. **INV-3**: All side effects only through tool + permission path (ToolRegistry.call → PermissionEngine.evaluate).
+112. **INV-4**: Import/dependency direction is one-way per allowed graph; never crossed.
+113. **INV-5**: EventBus is transport, never source of truth; recovery rebuilds from SQLite.
+
+### 参考复用 (system-detailed-design §23)
+
+114. **AP-185**: Reference reuse modes — npm-dep (consume directly), fork/adapt (copy+adapt), pattern (reference structure), behavioral (match behavior/quality).
+115. **AP-186**: Reference map — OpenTUI: npm-dep; OpenCode TUI: pattern only; @opencode-ai/llm: fork/adapt; Claude Code CLI: behavioral only; OpenAI Codex: pattern; Hermes Agent: pattern; Anthropic Skills: pattern; asciinema/Atuin/claude-hud: pattern.
+116. **AP-187**: Reference reuse rules — npm-dep items never re-implemented; fork/adapt items preserve own contracts/invariants; behavioral items contribute no code.
+
+---
+
+## DF (Defect Fixes from AirPlan V2) — 33条
+
+### 来源: airplanV2-Qwen3.7-Max设计.md §1.1
+
+### P0 — 已造成实际损失 (10条)
+
+117. **P0-1**: AirXDB false positive blocking — evidence gate no task-type awareness; 11+ tasks.
+118. **P0-2**: Deployment verification gap — validate_for_finalize() structural-only.
+119. **P0-3**: Non-atomic writes — 5 _json_dump sites use direct path.write_text().
+120. **P0-4**: Zero concurrency control — todo.md read-modify-write race.
+121. **P0-5**: AirArc hijacked by plan mode.
+122. **P0-6**: AirEng stops to ask instead of autonomous decisions.
+123. **P0-7**: AirEng no child-thread status polling — relies on Agent self-discipline.
+124. **P0-8**: AirDo does not call AirDbg — skips debug, directly reports blocked/false-done.
+125. **P0-9**: Installer script path errors.
+126. **P0-10**: AirEng deviates from scheduling to write code.
+
+### P1 — 限制可靠性与可维护性 (14条)
+
+127. **P1-1**: Hardcoded developer paths (debug_runtime.py:130, airxdb_runtime.py:156).
+128. **P1-2**: `_json_dump`/`_json_load` duplicated 5 times.
+129. **P1-3**: `_ordered_unique` duplicated 4 times.
+130. **P1-4**: policy normalization duplicated 3 times.
+131. **P1-5**: merge-into-state duplicated 3 times.
+132. **P1-6**: marker block upsert duplicated 2 times with different interfaces.
+133. **P1-7**: `_session_stamp` format inconsistent.
+134. **P1-8**: todo.md column index hardcoded (doc_sync.py:154-156).
+135. **P1-9**: Concurrency cap hardcoded as 3 (engine.py:527).
+136. **P1-10**: Child processes have no timeout in airxdb/debug runtime.
+137. **P1-11**: task_id path injection at worker.py:59 — no `../` validation.
+138. **P1-12**: Marker injection risk in doc_sync.py `_replace_marker_block()`.
+139. **P1-13**: Silent exception swallowing — session file corruption continue with no log.
+140. **P1-14**: Arc re-planning then Eng cannot connect — static todo.md table cannot absorb dynamic replanning.
+141. **P1-15**: Same-file non-conflicting tasks forced serial — file-level conflict detection.
+142. **P1-16**: AirArc skips requirements discussion, directly generates plan.
+143. **P1-17**: AirDbg modifies code without evidence collection.
+144. **P1-18**: Project lacks standardized logging (no spdlog).
+145. **P1-19**: No boundary tests + final review lacks high-risk checks.
+146. **P1-20**: UI design lacks professional Skill support.
+147. **P1-21**: ADR changes have no cascading invalidation mechanism.
+148. **P1-22**: Dispatch→Worker launch has no bridge — dispatch_worker_group() writes JSON, no Worker launch.
+149. **P1-23**: Dispatch instruction ambiguity — commands/eng.md intent description, not pseudocode.
+150. **P1-24**: Merge then TaskGraph state out of sync — merge_worker_result() doesn't update task-graph.json.
+
+### P2 — 限制规模化 (4条)
+
+151. **P2-1**: Conflict detection O(n²) — review.py combinations(active_tasks, 2).
+152. **P2-2**: state.json unbounded growth — mergedResults never truncated.
+153. **P2-3**: todo.md full re-parse on every operation.
+154. **P2-4**: Zero test coverage — entire air_runtime/.
+
+### P3 — 限制用户体验 (5条)
+
+155. **P3-1**: AGENTS.md bloat — AirEng sync appends without dedup.
+156. **P3-2**: Write-set rigidity causes cascading task chains.
+157. **P3-3**: Parallel Workers compete for shared hardware — no awareness.
+158. **P3-4**: Environment-specific fixes not persistable.
+159. **P3-5**: Cross-project knowledge not transferred.
+
+---
+
+## V2I (V2 Improvements) — 40条
+
+### 来源: airplanV2-Qwen3.7-Max设计.md §3
+
+160. **V2I-01** (§3.1.1): `air_runtime.io` — atomic_json_write (tempfile+os.replace), safe_json_load.
+161. **V2I-02** (§3.1.2): `air_runtime.lock` — FileLock based on fcntl.flock with timeout.
+162. **V2I-03** (§3.1.3): `air_runtime.utils` — ordered_unique, session_stamp, normalize_policy, sanitize.
+163. **V2I-04** (§3.2.1): EvidenceGatePolicy — task-type-aware (GUI_INDICATORS, NETWORK_INDICATORS).
+164. **V2I-05** (§3.2.2): Deploy verification enforcement in WorkerResult.validate_for_finalize.
+165. **V2I-06** (§3.2.3): AdaptivePoller — dynamic intervals (min 30s, max 300s).
+166. **V2I-07** (§3.2.4): Worker timeout (WORKER_MAX_WALL_TIME=7200s) + resource protection.
+167. **V2I-08** (§3.2.5): Merge transactionization with FileLock.
+168. **V2I-09** (§3.2.6): AirArc plan mode blocking — allowed_tools: [Read, Glob, Grep]; deny_plan_mode.
+169. **V2I-10** (§3.2.7): AirEng autonomous decision + Chinese lock.
+170. **V2I-11** (§3.2.8): AirEng hardcoded polling loop — mandatory 5-minute cycle.
+171. **V2I-12** (§3.2.8b): AirEng scheduling boundary — EXTREME_TAKEOVER only when budget exhausted + ≤5 lines.
+172. **V2I-13** (§3.2.9): AirDo mandatory AirDbg routing (forced=true).
+173. **V2I-14** (§3.2.10): Installer path correction — absolute paths + post_install_verify.
+174. **V2I-15** (§3.2.11): Dynamic graph scheduling (TaskGraph+PlanDelta) — **已在AirCoding实现**.
+175. **V2I-16** (§3.2.11b): Dispatch→Worker launch bridge — spawn_workers standardized.
+176. **V2I-17** (§3.2.11c): Merge→TaskGraph state sync — task-graph.json node status is authoritative.
+177. **V2I-18** (§3.2.12): Worktree isolation for same-file different-region parallelism.
+178. **V2I-19** (§3.2.13): AirArc requirements discussion gate — three-phase process.
+179. **V2I-20** (§3.2.14): Project-level spdlog logging standard.
+180. **V2I-21** (§3.2.15): Boundary test enforcement + final review high-risk audit.
+181. **V2I-22** (§3.2.16): frontend-design Skill integration.
+182. **V2I-23** (§3.2.17): ADR change cascading invalidation — **已在AirCoding实现方法,待生产接线**.
+183. **V2I-24** (§3.3.1): Compression quality validation — **已在AirCoding实现CompressionValidator**.
+184. **V2I-25** (§3.3.2): Token estimation improvement — AdaptiveTokenEstimator.
+185. **V2I-26** (§3.3.3): Stale lock detection.
+186. **V2I-27** (§3.4): AirSDB multi-language static analysis.
+187. **V2I-28** (§3.5.1): AirDbg workflow enforcement — 7 mandatory steps.
+188. **V2I-29** (§3.5.2): Fix rollback — pre_fix_snapshot.
+189. **V2I-30** (§3.5.3): Evidence-first gate.
+190. **V2I-31** (§3.6.1): AirXDB DRM/KMS native screenshot.
+191. **V2I-32** (§3.6.2): AirXDB headless CI XvfbCapture.
+192. **V2I-33** (§3.7.1): AirDep deployment plugin.
+193. **V2I-34** (§3.7.2): AirTst test runner plugin.
+194. **V2I-35** (§3.7.3): AirSec security scan plugin.
+195. **V2I-36** (§3.7.4): AirRvr requirements reviewer plugin.
+196. **V2I-37** (§3.7.4): Code-to-Design consistency review (mandatory line-level comparison every review).
+197. **V2I-38** (§3.7.4): AirRvr AirEng integration — verdict=pass/conditional-pass/fail.
+198. **V2I-39** (§3.7.4): Event index layer — EventLog as structured JSONL timeline.
+199. **V2I-40** (§3.8): air_runtime module reorganization — io.py, lock.py, utils.py, events.py, task_graph.py, etc.
+
+---
+
+## V2 Design Goals, Invariants, KPIs
+
+### 来源: airplanV2-Qwen3.7-Max设计.md §2, §7
+
+### V2 Goals
+200. Reliability — state writes not lost, concurrent ops race-free, self-healing after crash.
+201. Observability — all engine operations traceable, metrics exportable.
+202. Intelligence — evidence gating perceives task type, polling adaptive.
+203. Scale — support 100+ tasks, 5+ parallel Workers.
+
+### V2 Invariants
+204. INV-1: Artifact-driven communication through AirPlan/ files; V2 adds event index layer.
+205. INV-2: Context isolation (fork_context=false); V2 adds selective context inheritance.
+206. INV-3: Architecture sync mandatory — cannot DONE without updating architecture docs.
+207. INV-4: Evidence before repair — screenshot/packet-capture/static-analysis first.
+208. INV-5: Closed-loop auto-repair — execute→fail→debug→fix→re-execute.
+
+### V2 KPIs (26个)
+209. AirXDB false positive: V1 ~60% → V2 <5%
+210. State file corruption: V1 known → V2 0%
+211. Deployment consistency incidents: V1 1 critical → V2 0
+212. Hollow fix cycles: V1 11+ → V2 0
+213. Code duplication: V1 5 copies → V2 1 per function
+214. Test coverage: V1 0% → V2 core >80%
+215. AirArc plan mode hijack: V1 frequent → V2 0
+216. AirArc skip requirements: V1 every launch → V2 0
+217. AirEng non-Chinese output: V1 frequent → V2 0
+218. AirDo skips AirDbg: V1 frequent → V2 0
+219. AirDbg modifies code without evidence: V1 frequent → V2 0
+220. Boundary without test coverage: V1 all → V2 100%
+221. Final review missing high-risk: V1 none → V2 100%
+222. UI tasks without Skill: V1 all → V2 100%
+223. ADR change old code residue: V1 none → V2 0 (cascade+git revert)
+224. Dispatch→Worker broken: V1 Agent stops → V2 0 (spawn_workers + instruction ops)
+225. Post-merge duplicate dispatch: V1 redispatched → V2 0 (task-graph.json sync)
+
+---
+
+## V2 Phase Plan
+
+### 来源: airplanV2-Qwen3.7-Max设计.md §4
+
+226. **V2-Phase1** (P0 fixes): atomic I/O, file locks, utils dedup, EvidenceGatePolicy, deploy verify, hardcoded paths, child timeouts, injection protection, exception handling, Arc plan-mode blocking, Eng Chinese+autonomous, Eng polling, Do→Dbg forced routing, installer path fix, Arc requirements gate, Dbg evidence-first gate, spdlog standard, Eng boundary, boundary tests+highRiskAudit, frontend-design Skill, dispatch bridge, merge TaskGraph sync.
+
+227. **V2-Phase2** (Engine enhancement): AdaptivePoller, Worker timeout+resource, merge transactionization, AGENTS.md dedup, EventLog, todo column derivation, configurable concurrency, state.json cap, TaskGraph+PlanDelta, region conflict+worktree, ADR cascading invalidation.
+
+228. **V2-Phase3** (New plugins): AirDep, AirTst, AirSDB multi-lang, AirXDB kmsgrab+xvfb, AirDbg step tracking+rollback, AirRvr, AirSec.
+
+229. **V2-Phase4** (Scale): Conflict detection O(n log n), todo.md cache, compression validation, token estimation, stale lock, AirArc incremental replanning, cross-project ops template.
+
+230. **V2-Phase5** (Test coverage): todo_parser, review, doc_sync, contracts, engine, io, lock, evidence_gate, task_graph, worktree.
+
+---
+
+## 总结
+
+### 设计文档统计
+
+| 类别 | 数量 |
+|------|------|
+| FR | 21 + 7子要求 |
+| NFR | 8 |
+| AC | 13 |
+| CT | 16 |
+| RB | 6 |
+| **PV (V1插件原型)** | **8** |
+| AP (含INV) | 194 |
+| DF (P0-P3) | 33 |
+| V2I | 40 |
+| V2 Goals/Invariants/KPIs | 35 |
+| Phase items | 5 |
+| **总计** | **391** |
+
+### 架构核心原则
+
+**Agent 存在的目的是扩展插件的能力边界。插件代表的工作流才是产品核心。**
+
+AirCoding V1.0.0 Alpha 不是从零开发的新产品,而是将 8 个已验证的 Python/Claude Code Skill 插件移植到 TypeScript/Bun/SQLite 运行时。Agent (MainAgent/Scheduler/Worker) 是基础设施底座,8个插件工作流(AirArc/AirEng/AirDo/AirDbg/AirXDB/AirNDB/AirSDB/AirContext)才是交付给用户的价值。
+
+### V1插件 → AirCoding 移植完整度 (8个核心工作流)
+
+| V1插件 | AirCoding模块 | 工作流可运行? | 缺失 |
+|--------|--------------|-------------|------|
+| AirArc | ArchitectureDesigner | ❌ | 正则替代LLM, 无三步流程, 无PlanMode阻断 |
+| AirEng | Scheduler | ❌ | 基础调度可跑, 无级联保护/自主决策/硬编码轮询 |
+| AirDo | ExecutorRole | ⚠️ | 简单任务可跑, 不强制调AirDbg |
+| AirDbg | DebuggerRole | ❌ | 从未触发, 7步工作流仅在提示词中 |
+| AirXDB | gui.screenshot | ❌ | 仅ImageMagick, 无headless/diff |
+| AirNDB | network.capture | ⚠️ | 仅tcpdump封装, 不产artifact |
+| AirSDB | toolchain-cpp | ❌ | 仅cppcheck注册, 无build管道 |
+| AirContext | ContextAssembler+Compactor | ⚠️ | 基础可组装, CompactorRole未运行 |
+| **总体** | — | **0/8 可交付** | **8/8 需要工作流级别的移植** |
+
+### 产品差距 — V1已验证能力丢失
+
+407h的产出集中在了基础设施层(EventStore/Scheduler/ToolRegistry/SQLite),但8个V1已生产验证的插件工作流没有一个被完整移植。原因是开发从未以"插件工作流逐条移植"为目标,而是在造一个通用的Agent运行时——然后假设插件工作流"自然会跑在上面"。
+
+**正确的开发顺序**: 先移植插件工作流(AirArc→ArchitectureDesigner, AirEng→Scheduler, AirDo→ExecutorRole...),每移植一个就端到端验证一个。基础设施随工作流需求演进,而非反过来先造全套基础设施再填工作流。
+
+**核心结论**: 当前AirCoding产品不可发布。0/8 V1插件工作流可运行。397h的产出是一个Agent基础设施demo,不是符合6份设计文档391条要求的V1.0.0 Alpha产品。

AirPlan/docs/analysis/requirements-audit-report.md

@@ -0,0 +1,347 @@
+# AirCoding V1.0.0 Alpha — 完整需求清单与差距报告
+
+**生成日期**: 2026-06-11
+**状态**: Fable5 主模型终审 + deepseek-v4-pro 全文提取
+**来源文档**:
+1. `requirements.md` — 21条FR + 8条NFR + 13条AC + 10条CT
+2. `airplanV2-Qwen3.7-Max设计.md` — 25个P0-P3缺陷 + 40个V2改进 + 26个KPI
+3. `baselineV1.md` — 5个参考项目基准 + 44条架构原则
+4. `solution-architecture.md` — 10项架构原则 + 6个容器 + 4个控制流 + 安全模型
+5. `system-overview-design.md` — 18节系统概览设计
+6. `system-detailed-design.md` — 24节详细类方法设计 + 序列 + 状态机 + 可追溯矩阵
+
+---
+
+## 一、参考项目基准 (RB-01 ~ RB-06)
+
+| ID | 参考项目 | 要求复用的内容 |
+|----|----------|---------------|
+| RB-01 | **Claude Code CLI** | 执行层质量基准: 精确编辑、读后编辑、小块补丁、不重构无关代码、验证后完成、证据闭环、TAOR/TORI反馈循环 |
+| RB-02 | **OpenCode** | TUI视觉风格/交互布局、运行时分层、Session/事件/同步概念、Provider/模型抽象、插件/SDK思路。**复用OpenTUI原语,不复用SDK/sync/session业务逻辑** |
+| RB-03 | **Hermes Agent** | 经验挖掘、Nudge Engine间隔触发学习、Curator守护进程、Skill自修复、SKILL.md格式、FTS检索 |
+| RB-04 | **OpenAI Codex** | Shell/patch/test直接执行循环、编码沙箱、工具编排、MCP实现思路 |
+| RB-05 | **Anthropic Skills** | SKILL.md结构/前置元数据、技能目录布局(scripts/references/assets)、可复用工作流打包 |
+| RB-06 | **asciinema/Atuin/claude-hud** | PTY捕获和终端回放、命令元数据/历史索引、HUD/状态栏布局 |
+
+---
+
+## 二、功能需求 (FR-001 ~ FR-020 + FR-007.5)
+
+### FR-001 CLI启动与项目初始化
+从CLI入口启动,检测/打开项目,需要时初始化`.air/`,加载资源/配置,运行只读Doctor,打开session。
+
+### FR-002 项目本地状态
+`.air/shared/`(可共享配置/规则/计划) + `.air/local/`(私有sessions/artifacts/workspaces/backups/local DBs)
+
+### FR-003 会话持久化
+SQLite at `<project>/.air/local/sessions/<session-id>/session.db`, 支持: messages, drafts, durable events, task graph state, agents, tool/command runs, artifacts, diagnostics, evidence refs, workspaces, summaries, UI state
+
+### FR-004 事件驱动运行时
+发布RuntimeEvents用于实时行为,持久事件与域表更新在同一个事务中
+
+### FR-005 主代理对话
+面向用户的Main Agent: 接收请求、适当直接回答、分类工作、显示进度、呈现阻断/确认
+
+### FR-006 架构设计师
+架构/接口/产品级决策路由到Architecture Designer: 更新架构制品、产生影响评估
+
+### FR-007 调度器与任务图
+调度TaskSpec: hard/soft依赖、写区冲突处理、重试预算、子Worker派发、心跳监控、合并协调、重启恢复
+
+### FR-007.5 ADR级联失效与架构变更回滚 (7条子要求)
+1. 通过TaskNode.adr_refs溯源所有依赖该ADR的任务(含已完成)
+2. 级联失效: completed→invalidated, running→终止, pending→cancelled
+3. 冻结调度(dispatch_frozen),阻止新任务派发
+4. 创建git回滚快照(rollback_ref),支持revert旧方案代码
+5. 接收ArchitectureDesigner产出的PlanDelta增量重规划
+6. apply_delta吸收新任务后解冻调度
+7. 终审时检查INVALIDATED任务的旧代码是否已清理
+
+### FR-008 独立Worker Agent
+Executor/Reviewer/Debugger/Compactor/ExperienceMiner作为独立Bun子进程,通过NDJSON IPC通信
+
+### FR-009 Claude Code级执行原语
+强制: read-before-edit, exact conservative edits, small patches, no unrelated refactors, permission checks, verification-before-completion
+
+### FR-010 ToolRegistry和内置工具
+Schema验证的工具: filesystem/shell/git/project scanning/完整C++ build/test/static-analysis/debug/GUI screenshot/network capture/artifacts/context assembly/permission requests/Doctor
+
+### FR-011 权限与安全模型
+路径/命令/网络/凭证分类;强制权限配置;保护系统敏感和凭证操作;项目外写入备份;拒绝不安全请求
+
+### FR-012 插件与能力基础
+Manifest加载/验证、启用/禁用配置、依赖声明、Doctor集成、命名空间工具注册、源/信任元数据、PermissionEngine强制。第三方注册/签名可延后,本地和内置capability打包必须可用
+
+### FR-013 Provider层
+内部使用Anthropic canonical消息,通过适配器路由provider调用,能力矩阵验证,转换报告
+
+### FR-014 上下文组装与压缩
+有序层组装prompt、适配token预算、记录遗漏、必要时copy-on-write压缩
+
+### FR-015 制品与证据管理
+temp-file→atomic rename,记录URI/path/hash/metadata,通过evidence refs链接声明
+
+### FR-016 TUI与HUD
+OpenTUI/Solid终端UI和HUD,**仅消费ProjectionStore,不查询原始DB/EventBus**
+
+### FR-017 完整C++开发流程
+项目检测→构建系统评估→CMake configure→Ninja优先/Make回退→编译器/链接器诊断解析→clangd代码智能查询→cppcheck静态分析→CTest/GoogleTest执行→debug运行/日志解析→失败诊断→范围修复→审查→证据支持验证
+
+### FR-018 Doctor
+启动时运行只读Doctor;报告环境/能力问题;在权限策略下支持修复模式
+
+### FR-019 日志与诊断
+可读`air.log`,加密`air.developer.log`,默认7天保留
+
+### FR-020 发布门禁
+定义tier-1 Linux发布门禁: 单元测试、集成fixture重放、真实LLM E2E、项目初始化、C++构建/测试流程、SQLite恢复、子IPC、TUI启动、制品/事件持久化
+
+---
+
+## 三、非功能需求 (NFR-001 ~ NFR-008)
+
+| ID | 需求 |
+|----|------|
+| NFR-001 | 本地优先: 项目状态/制品/日志/调试知识保留在本地,除非用户显式导出/分享/上传 |
+| NFR-002 | 可恢复性: 从进程/session重启恢复,读取SQLite状态,检测丢失agents,保留workspaces,重建Scheduler队列 |
+| NFR-003 | 可扩展性: 通过`toolchain-*`包和能力清单添加语言/工具链支持 |
+| NFR-004 | Provider灵活性: 内部契约在Anthropic/OpenAI/OpenRouter/ollama/兼容端点保持稳定 |
+| NFR-005 | UI响应性: Main Agent和TUI在后台Worker运行时保持响应 |
+| NFR-006 | 证据驱动完成: 任务未获得build/test/debug/review证据或显式skipped-gate报告前不得标记完成 |
+| NFR-007 | Linux优先: Linux x86_64=tier1, arm64/WSL2=tier2, macOS=实验, Windows=post-MVP |
+| NFR-008 | 安全边界保持: LLM输出、工具结果、插件、外部内容在被运行时契约和策略验证前为不可信数据 |
+
+---
+
+## 四、验收标准 (AC-01 ~ AC-13)
+
+1. CLI启动并初始化/打开项目`.air/`树
+2. Session DB schema初始化并持久化messages/events/tasks/tool runs/artifacts
+3. EventStore事务性地将核心持久事件应用到域表
+4. ProjectionStore水合并更新可用的TUI/HUD视图
+5. Scheduler通过NDJSON IPC派发Worker子进程,通过父runtime支持工具调用,接收WorkerResult
+6. ToolRegistry通过PermissionEngine执行filesystem/shell/git/artifact/context/doctor/C++/debug/GUI/network证据工具
+7. C++工作流可检测、配置、构建、静态分析、测试、调试、修复、审查、重新验证代表性fixture项目
+8. 失败的构建/测试/调试命令产生diagnostics/artifacts/evidence refs并可触发Debugger修复
+9. ContextAssembler产生Anthropic canonical消息,必要时记录遗漏
+10. Provider适配器路径可在能力验证和转换报告下执行模型调用
+11. 能力清单可加载、验证、启用并注册为命名空间工具
+12. Doctor报告平台/provider/toolchain/capability/display/network状态并支持权限修复模式
+13. 发布门禁命令在tier-1 Linux上记录并可运行
+
+---
+
+## 五、约束 (CT-01 ~ CT-16)
+
+| ID | 约束 |
+|----|------|
+| CT-01 | 运行时: TypeScript on Bun |
+| CT-02 | Monorepo: Bun workspaces + Turborepo |
+| CT-03 | TUI: `@opentui/solid`, `@opentui/core`, `@opentui/keymap` |
+| CT-04 | IPC: NDJSON over stdio |
+| CT-05 | DB: SQLite per session, WAL/NORMAL/foreign_keys OFF |
+| CT-06 | 内部消息格式: Anthropic canonical content blocks |
+| CT-07 | C++第一个深度工具链; runtime保持语言无关 |
+| CT-08 | Python仅子进程辅助层,非核心runtime |
+| CT-09 | 早期发行用binary tarball,非公共包渠道 |
+| CT-10 | 架构文档和工作流状态在`AirPlan/`下 |
+| CT-11 | Monorepo包(Alpha): contracts/cli/tui/runtime/llm/toolchain-cpp |
+| CT-12 | 依赖方向: contracts←(none); cli→tui/runtime/llm/toolchain-cpp; runtime→contracts+llm+toolchain-*; tui→contracts only; runtime禁止依赖tui |
+| CT-13 | 全局用户目录: `~/.air/` |
+| CT-14 | project_id是`.air/shared/project.json`中的稳定UUID |
+| CT-15 | `.gitignore`: `.air/local/` |
+| CT-16 | 所有副作用必须通过ToolRegistry和PermissionEngine |
+
+---
+
+## 六、架构原则完整清单 (AP-01 ~ AP-189)
+
+> 详细AP清单已由deepseek-v4-pro提取,参见`/home/airlongdian/DataDevices/AirWorkSpace/AirCoding/AirPlan/docs/analysis/full-requirements-audit.md`
+> 包含: 本节仅列关键原则概要,完整189条见审计文件。
+
+### 核心执行原则
+- AP-01: AirCoding是自有的AI编码runtime,非Claude Code插件包装器
+- AP-02: Runtime语言无关; C++第一个深度profile; 通过`toolchain-<lang>`扩展
+- AP-03: 核心循环: requirement → design → reading → planning → build → analysis → test → debug → evidence → fix → summary → mining
+- AP-45: 执行质量遵循Claude Code: 读后编辑、精确、保守、小步、验证后完成
+- AP-46: OpenCode是UI/runtime参考,非业务状态依赖
+- AP-47: 项目本地为真源: session状态/制品/备份/项目规则在`.air/`下
+- AP-48: 事件驱动活动行为; SQLite驱动恢复
+- AP-49: Worker是隔离的子进程(Executor/Reviewer/Debugger/Compactor/ExperienceMiner),通过NDJSON IPC通信
+- AP-50: Main Agent保持响应; 长运行后台工作委派给Scheduler/Worker
+- AP-51: 架构变更是显式的; 实现级变更静默继续; 接口级变更通过Architecture Designer
+- AP-52: 工具/能力边界受权限保护; 所有内置和插件工具通过ToolRegistry+PermissionEngine
+- AP-53: Provider边界隔离; 内部Anthropic canonical; 适配器在边界转换
+- AP-54: 证据是一等公民: build/test/debug/review输出在完成声明前成为制品和证据引用
+
+### 容器依赖
+- AP-55: CLI容器: 命令入口/启动/初始化/Doctor/项目发现/TUI/runtime引导
+- AP-56: TUI/HUD容器: 仅消费ProjectionStore; 不查询SQLite/EventBus; 不持有调度状态
+- AP-57: Runtime容器: MainAgent/ArchitectureDesigner/Scheduler/子进程管理/EventBus/EventStore/SessionStore/ToolRegistry/PermissionEngine/CapabilityRegistry/ContextAssembler/ArtifactStore/EvidenceStore/ProjectionStore
+- AP-58: LLM容器: Provider配置/适配器/Anthropic canonical处理/转换/能力矩阵/流式/工具调用/Token计数
+- AP-59: Toolchain C++容器: 项目检测/CMake/Ninja/CTest/cppcheck/clangd/诊断解析/证据生成
+- AP-60: Contracts容器: 可编译共享TS接口; 不依赖域实现包
+
+### 禁止路径
+- AP-85: TUI→SQLite直接查询、TUI→runtime私有服务导入、Worker→SQLite直接写入、Worker→工具外fs/shell/network、工具→无PermissionEngine副作用、能力→Doctor外依赖安装、Provider适配器→静默语义损失、仓库→调度策略、EventBus→恢复真源、runtime→TUI导入、LLM输出→直接文件/shell副作用
+
+### 事件/数据规则
+- AP-69: SQLite: WAL/NORMAL/foreign_keys=OFF
+- AP-88: 持久事件插入+域表更新在同一SQLite事务中
+- AP-91: 事件流: Producer→EventIngestor→验证→持久:EventStore事务+域投影+EventBus发布; 短暂:EventBus发布
+- AP-92: route追加只; route_text从route.join("/")派生; payload schema变更需版本递增
+- AP-137: EventStore.append事务中schema验证→EventRepository.insert→project(event,tx)→提交后EventBus.publish
+
+### 控制流
+- AP-72: 正常执行: 用户请求→Main Agent分类→直接回答或架构/任务规划→Scheduler创建/加载TaskGraph→ContextAssembler→Scheduler派发Worker→工具→PermissionEngine→WorkerResult→Scheduler重试/合并/审查→Main Agent报告
+- AP-73: 需求变更: requirement.changed事件→Scheduler暂停受影响工作→Architecture Designer评估→实现级静默继续→架构/产品级路由用户确认/重规划
+- AP-74: 恢复: 重启→打开session DB→加载运行/中断任务→检查子进程存活→发出agent.lost/task.failed或重连/恢复→保留未合并workspaces→重建Scheduler队列→水合ProjectionStore
+
+### 安全 (AP-79, AP-104~108, AP-171)
+- LLM输出在验证前不可信
+- 工具是文件系统/shell/network副作用的唯一路径
+- 符号链接通过realpath解析后分类
+- `.git/`默认保护; build目录允许项目写入
+- 项目外写入需备份; 凭证/系统敏感操作需显式确认
+- 无自动上传日志/制品/调试知识/Doctor包
+- 权限评估顺序: 工具能力声明→权限profile→TaskSpec范围→路径/命令/网络风险→凭证/系统敏感→用户提示
+- 8个路径风险类别 + 10个命令风险类别
+
+### 可追溯性
+完整189条AP及11条INV详见审计文件:
+`/home/airlongdian/DataDevices/AirWorkSpace/AirCoding/AirPlan/docs/analysis/full-requirements-audit.md`
+
+---
+
+## 七、AirPlan V2 缺陷 (DF-P0 ~ DF-P3, 共33个)
+
+### P0 — 已造成实际损失 (DF-P0-01 ~ DF-P0-10)
+1. AirXDB假阳性阻塞 — 证据门控无任务类型感知
+2. 部署验证缺口 — validate_for_finalize()只检查结构完整性
+3. **非原子写入** — 5处_json_dump直接覆盖(→ AirCoding已用ArtifactStore temp+rename修复)
+4. **零并发控制** — todo.md读改写竞态(→ AirCoding已用SQLite事务修复)
+5. AirArc被plan模式劫持
+6. AirEng停问而不自主决策
+7. AirEng无子线程状态轮询
+8. AirDo不调用AirDbg
+9. 安装器脚本路径错误
+10. AirEng偏离调度亲自写代码
+
+### P1 — 限制可靠性 (DF-P1-01 ~ DF-P1-14)
+1. 硬编码开发者路径
+2. _json_dump重复5份
+3. _ordered_unique重复4份
+4. policy normalization重复3份
+5. merge-into-state重复3份
+6. marker block upsert重复2份
+7. _session_stamp格式不一致
+8. todo.md列索引硬编码
+9. 并发度硬编码为3
+10. 子进程无超时
+11. task_id路径注入
+12. 标记注入风险
+13. 静默吞异常
+14. Arc重规划后Eng无法衔接 → **AirCoding TaskGraph+PlanDelta解决**
+
+### P2 — 限制规模化 (DF-P2-01 ~ DF-P2-04)
+1. 冲突检测O(n²)
+2. state.json无界增长
+3. todo.md全量重解析
+4. 零测试覆盖
+
+### P3 — 限制用户体验 (DF-P3-01 ~ DF-P3-05)
+1. AGENTS.md膨胀
+2. 写集刚性导致级联任务链
+3. 并行Worker抢占共享硬件
+4. 环境特定修复不可持久
+5. 跨项目知识不迁移
+
+---
+
+## 八、AirPlan V2 改进 (V2I-01 ~ V2I-40)
+
+见完整审计文件,关键项:
+- V2I-01: 统一原子I/O模块(air_runtime.io)
+- V2I-04: 任务类型感知的证据门控
+- V2I-15: **动态图调度(TaskGraph+PlanDelta) — 已在AirCoding中实现**
+- V2I-18: Worktree隔离同文件不同区域并行
+- V2I-22: frontend-design Skill集成
+- **V2I-23: ADR变更级联失效 — 已在AirCoding中实现方法,待生产接线**
+- **V2I-24: 压缩质量验证(CompressionValidator) — 已在AirCoding中实现**
+- V2I-28: AirDbg 7步工作流强制
+- V2I-30: 证据优先门控(EvidenceFirstGate)
+- V2I-37: Code-to-Design一致性审查(每行比较)
+
+---
+
+## 九、V2 KPI (26个)
+
+| KPI | V1当前 | V2目标 |
+|-----|--------|--------|
+| AirXDB假阳性率 | ~60% | <5% |
+| 状态文件损坏率 | 已知发生 | 0% |
+| 部署一致性事故 | 1次关键 | 0 |
+| 空壳修复循环 | 11+ | 0 |
+| 代码重复 | 5份_json_dump | 每函数1份 |
+| 测试覆盖率 | 0% | >80% |
+| ADR变更旧代码残留 | 无自动清理 | 0(级联失效) |
+| Dispatch→Worker断链 | Agent停止调度 | 0(spawn_workers标准化) |
+
+---
+
+## 十、当前产品差距评估
+
+### 参考项目对照
+
+| 参考项目 | 要求 | 实际 |
+|----------|------|------|
+| **Claude Code CLI** (RB-01) | 执行层质量基准: read-before-edit, exact edits, verification | ❌ 全凭提示词,代码无强制 |
+| **OpenCode** (RB-02) | TUI视觉/交互/Provider抽象, 复用OpenTUI, 不复用SDK | ❌ 47个console.log撕裂TUI, 重写了Provider |
+| **Hermes Agent** (RB-03) | 经验挖掘/Nudge/Curator/Skill自修复 | ❌ ExperienceMinerRole从未运行 |
+| **OpenAI Codex** (RB-04) | Shell/patch/test执行循环, 工具编排 | ⚠️ 工具内联不统一 |
+| **Anthropic Skills** (RB-05) | SKILL.md格式, 技能目录布局 | ⚠️ 仅capability manifest |
+| **asciinema/Atuin/claude-hud** (RB-06) | PTY/HUD/状态栏 | ❌ HUD无对话面板 |
+
+### 21条FR严格评估
+
+| FR | 状态 | 说明 |
+|----|------|------|
+| FR-001 | ⚠️ | init可跑,Doctor执行但结果不展示 |
+| FR-002 | ✅ | 目录布局正确 |
+| FR-003 | ❌ | NOT NULL/UNIQUE持续崩溃 |
+| FR-004 | ❌ | 投影缺口持续,虽有诊断脚本修复,未端到端验证 |
+| FR-005 | ❌ | 正则分类器+dispatchTask,无对话 |
+| FR-006 | ❌ | 正则判断(文件数>10),无LLM |
+| FR-007 | ❌ | RetryPlanner字段不匹配 |
+| FR-007.5 | ❌ | 方法全有,零生产调用 |
+| FR-008 | ❌ | 仅ExecutorRole实跑过 |
+| FR-009 | ❌ | 全凭提示词 |
+| FR-010 | ❌ | 定义28个工具,cpp.*/debug.*从未触发 |
+| FR-011 | ⚠️ | 已修复部分崩溃,permission.request修复 |
+| FR-012 | ❌ | 仅1个capability包 |
+| FR-013 | ❌ | 仅OpenAI兼容适配器 |
+| FR-014 | ❌ | CompactorRole从未运行 |
+| FR-015 | ⚠️ | ArtifactStore可用,evidence_refs已修复 |
+| FR-016 | ❌ | 47个console.log撕裂TUI |
+| FR-017 | ❌ | cpp.*从未端到端 |
+| FR-018 | ❌ | Doctor跑了不展示 |
+| FR-019 | ⚠️ | Logger存在,写入未验证 |
+| FR-020 | ❌ | 27/27门禁方法级,产品不可用 |
+
+### 分类
+
+- ✅ 可达: 1/21 (FR-002)
+- ⚠️ 部分可达: 3/21 (FR-001, FR-011, FR-015, FR-019)
+- ❌ 不可达: 17/21
+
+---
+
+## 文件导航
+
+- 完整审计文件(383条详细清单): `/home/airlongdian/DataDevices/AirWorkSpace/AirCoding/AirPlan/docs/analysis/full-requirements-audit.md`
+- 功能需求: `AirPlan/docs/analysis/requirements.md`
+- 架构方案: `AirPlan/docs/architecture/solution-architecture.md`
+- 基准V1: `AirPlan/docs/architecture/baselineV1.md`
+- V2设计: `/home/airlongdian/DataDevices/AirWorkSpace/air-plugins-dist/airplanV2-Qwen3.7-Max设计.md`
+- 详细设计: `AirPlan/docs/architecture/system-detailed-design.md`
+- 系统概览: `AirPlan/docs/architecture/system-overview-design.md`

AirPlan/docs/analysis/requirements.md

@@ -58,6 +58,15 @@ AirCoding must route architecture/interface/product-impacting decisions to an Ar
 
 AirCoding must schedule TaskSpec records with hard/soft dependencies, write-area conflict handling, retry budgets, child worker dispatch, heartbeat monitoring, merge coordination, and restart recovery.
 
+**FR-007.5 ADR 级联失效与架构变更回滚**：当 ADR 发生架构方案变更（如 ffmpeg → gstreamer）时，调度器必须：
+1. 通过 TaskNode.adr_refs 溯源所有依赖该 ADR 的任务（含已完成）
+2. 级联失效受影响任务（completed→invalidated、running→终止、pending→cancelled）
+3. 冻结调度（dispatch_frozen），阻止新任务派发
+4. 创建 git 回滚快照（rollback_ref），支持 revert 旧方案代码
+5. 接收 ArchitectureDesigner 产出的 PlanDelta 增量重规划
+6. apply_delta 吸收新任务后解冻调度
+7. 终审时检查 INVALIDATED 任务的旧代码是否已清理
+
 ### FR-008 Independent Worker Agents
 
 Executor, Reviewer, Debugger, Compactor, and ExperienceMiner must run as independent Bun child processes communicating through NDJSON IPC.